@jay-framework/jay-stack-cli 0.19.8 → 0.21.0

package/agent-kit-template/designer/INSTRUCTIONS.md

@@ -11,7 +11,7 @@ Jay Stack is a full-stack framework where:
 - **jay-html** templates provide the UI that binds to contract data
 - **Rendering phases** determine when data is available (build-time, request-time, client-side)
 
-Your job is to create `.jay-html` pages that bind to the data and interactions defined by contracts.
+Your job is to create `.jay-html` pages that bind to the data and interactions defined by contracts. **All visible UI structure belongs in jay-html** — not in `page.ts` via `document.createElement`. Behavior and state live in `page.ts`; elements are reached through **refs** declared in the template.
 
 ## Rendering Phases
 

package/agent-kit-template/designer/jay-html-components.md

@@ -71,6 +71,20 @@ Use `<jay:contract-name>` tags with props:
 </jay:product-widget>
 ```
 
+**With bindings from page data** (props from keyed components or page ViewState):
+
+```html
+<!-- p is a keyed headless component providing product data -->
+<jay:category-products categorySlug="{p.categorySlug}" limit="4">
+  <div class="product-card">
+    <h3>{name}</h3>
+    <span>{price}</span>
+  </div>
+</jay:category-products>
+```
+
+Use `{path}` syntax to bind props to values from the page's ViewState. The binding is resolved at render time — works with both slow and fast phase data.
+
 **With forEach** (dynamic props from parent data):
 
 ```html
@@ -85,6 +99,34 @@ Use `<jay:contract-name>` tags with props:
 
 Inside `<jay:...>`, bindings resolve to **that instance's** contract tags (not the parent).
 
+### Prop binding summary
+
+| Syntax                            | Resolves to          | Example                   |
+| --------------------------------- | -------------------- | ------------------------- |
+| `prop="literal"`                  | Literal string value | `productId="prod-1"`      |
+| `prop="{field}"`                  | Page ViewState field | `slug="{p.categorySlug}"` |
+| `prop="{field}"` (inside forEach) | ForEach item field   | `productId="{_id}"`       |
+
+### Prop phase constraints
+
+Contract props can declare a `phase` (defaults to `slow`). The binding source must be available at that phase:
+
+- A **slow** prop (default) must bind to a literal, a route param, or a slow-phase tag
+- A **fast** prop can also bind to fast-phase tags
+
+If a slow prop binds to a fast-phase field, `jay-stack validate` flags an error — the component's slow render would receive an empty value.
+
+```yaml
+# In the component's contract:
+props:
+  - name: categorySlug
+    type: string
+    phase: slow # Must be available at build time
+  - name: filter
+    type: string
+    phase: fast # Only needs to be available at request time
+```
+
 ## Headfull Components
 
 In Jay Stack, headfull components are full-stack. They must have a `.jay-contract` file and are created using `makeJayStackComponent` in their `.ts` file. They support server rendering (slow/fast/interactive phases) and must include a `contract` attribute in the import.

package/agent-kit-template/developer/component-refs.md

@@ -119,3 +119,35 @@ A tag can be both data and interactive:
 ```
 
 This generates both a ViewState field and a ref.
+
+## DOM access rules (Jay Stack pages)
+
+Refs are the **only supported path** from TypeScript to elements Jay renders. Direct `document` access bypasses the framework and can break rendering, updates, and performance.
+
+### Do
+
+- Declare elements in **jay-html** with `ref="..."`.
+- Drive overlays, lists, and visibility with **ViewState** (`if`, `forEach`, signal-backed bindings).
+- Attach handlers with ref APIs: `refs.myRef.onclick`, `oninput`, `onkeydown`, etc.
+- Use `refs.myRef.exec$((element, viewState) => …)` **inside handlers** for focus, scroll, measure, or native APIs.
+- For drags: `setPointerCapture` on the ref element that received `pointerdown`, then listen on that element.
+
+### Avoid
+
+- `document.querySelector` / `getElementById` to find template elements
+- `document.createElement` + `appendChild` for UI that belongs in jay-html
+- `document.addEventListener('mousemove'|'mouseup')` for drags (use pointer capture instead)
+
+### Rare `document` exceptions
+
+Use only when no ref can exist, with an inline comment:
+
+| Case                   | Example                                               |
+| ---------------------- | ----------------------------------------------------- |
+| Offscreen processing   | `document.createElement('canvas')` for image export   |
+| Coordinate hit-testing | `document.elementFromPoint` during cross-overlay drag |
+| Tests                  | `document.dispatchEvent` in Vitest                    |
+
+Global shortcuts or paste: prefer a root shell ref (`ref="appRoot"`) with capture listeners.
+
+See also: `.cursor/skills/jay-dom-refs/SKILL.md` in the jay monorepo.

package/agent-kit-template/developer/page-components.md

@@ -81,6 +81,12 @@ export const page = makeJayStackComponent<ProductPageContract>()
   });
 ```
 
+## DOM access in interactive phase
+
+Reach rendered elements through **refs** only. Put overlays, panels, and lists in **jay-html**; drive them with ViewState from `.withInteractive`. Do not use `document.querySelector`, imperative `createElement` UI, or document-level drag listeners.
+
+See [component-refs.md](component-refs.md#dom-access-rules-jay-stack-pages).
+
 ## Calling File Upload Actions
 
 Actions created with `.withFiles()` accept browser `File` objects directly. Use `oninput` events on file inputs to drive signals, then pass them to the action:

package/agent-kit-template/plugin/INSTRUCTIONS.md

@@ -12,9 +12,25 @@ A plugin provides headless components (data + interactions, no UI) that project
 2. **Implement components** matching the contracts
 3. **Define actions** with `.jay-action` metadata
 4. **Optionally add routes** — pages for admin tools and dashboards
-5. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes
-6. **Configure build** — dual entry points (server + client), vite.config.ts, package.json exports
-7. **Validate** with `jay-stack validate-plugin`
+5. **Optionally add validators** — custom jay-html validation rules
+6. **Optionally add setup/references handlers** — config templating, add-menu generation
+7. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes, validators, setup
+8. **Configure build** — dual entry points (server + client), vite.config.ts, package.json exports
+9. **Validate** with `jay-stack validate-plugin`
+
+## Plugin Lifecycle — CLI Commands
+
+The plugin participates in four CLI commands, each running different hooks:
+
+| Command                     | When               | What runs from your plugin                                                         |
+| --------------------------- | ------------------ | ---------------------------------------------------------------------------------- |
+| `jay-stack validate-plugin` | Plugin development | Checks plugin.yaml structure, contracts, exports, handler references               |
+| `jay-stack setup <plugin>`  | Project setup      | `setup.handler` — creates config files, validates credentials                      |
+| `jay-stack agent-kit`       | Before development | `setup.references` — generates add-menu items, reference data                      |
+| `jay-stack validate`        | During development | `validators[].handler` — runs your validation rules against project jay-html files |
+
+**`validate-plugin`** validates YOUR plugin's structure. Run it during plugin development.  
+**`validate`** runs your plugin's validators against a PROJECT that uses your plugin. Run it from the project.
 
 ## Guides
 
@@ -36,6 +52,7 @@ A plugin provides headless components (data + interactions, no UI) that project
 | [seo-guide.md](seo-guide.md)                      | SEO head tags: title, meta, OG, canonical via phaseOutput               |
 | [commands-guide.md](commands-guide.md)            | makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run      |
 | [validation.md](validation.md)                    | jay-stack validate-plugin, writing custom jay-html validators           |
+| [setup-guide.md](setup-guide.md)                  | Setup handlers, references handlers, add-menu generation                |
 | [dev-server-service.md](dev-server-service.md)    | Dev server service API: routes, params, freeze management               |
 | `../references/<plugin>/`                         | Plugin reference data                                                   |
 

package/agent-kit-template/plugin/component-refs.md

@@ -119,3 +119,35 @@ A tag can be both data and interactive:
 ```
 
 This generates both a ViewState field and a ref.
+
+## DOM access rules (Jay Stack pages)
+
+Refs are the **only supported path** from TypeScript to elements Jay renders. Direct `document` access bypasses the framework and can break rendering, updates, and performance.
+
+### Do
+
+- Declare elements in **jay-html** with `ref="..."`.
+- Drive overlays, lists, and visibility with **ViewState** (`if`, `forEach`, signal-backed bindings).
+- Attach handlers with ref APIs: `refs.myRef.onclick`, `oninput`, `onkeydown`, etc.
+- Use `refs.myRef.exec$((element, viewState) => …)` **inside handlers** for focus, scroll, measure, or native APIs.
+- For drags: `setPointerCapture` on the ref element that received `pointerdown`, then listen on that element.
+
+### Avoid
+
+- `document.querySelector` / `getElementById` to find template elements
+- `document.createElement` + `appendChild` for UI that belongs in jay-html
+- `document.addEventListener('mousemove'|'mouseup')` for drags (use pointer capture instead)
+
+### Rare `document` exceptions
+
+Use only when no ref can exist, with an inline comment:
+
+| Case                   | Example                                               |
+| ---------------------- | ----------------------------------------------------- |
+| Offscreen processing   | `document.createElement('canvas')` for image export   |
+| Coordinate hit-testing | `document.elementFromPoint` during cross-overlay drag |
+| Tests                  | `document.dispatchEvent` in Vitest                    |
+
+Global shortcuts or paste: prefer a root shell ref (`ref="appRoot"`) with capture listeners.
+
+See also: `.cursor/skills/jay-dom-refs/SKILL.md` in the jay monorepo.

package/agent-kit-template/plugin/plugin-structure.md

@@ -63,7 +63,7 @@ commands:
 
 validators:
   - name: media-optimization
-    handler: ./validators/media-validator
+    handler: validateMediaOptimization
     description: Ensures media URLs use resize parameters
 
 setup:
@@ -193,16 +193,26 @@ Commands are CLI operations run via `jay-stack run`. Use `makeCliCommand()` to c
 ### Validator Entry Fields
 
 - `name` — Validator name (shown in validation output as `plugin-name/validator-name`)
-- `handler` — Relative path to the validator module (must export a `validate` function)
+- `handler` — Export name (NPM plugins) or relative path (local plugins) to the validator function
 - `description` — (optional) What this validator checks
 
-Validators run during `jay-stack validate` against every parsed jay-html file. The handler module exports a `validate` function that receives a `JayHtmlValidationContext` and returns an array of findings. See [validation.md](validation.md) for implementation details.
+**NPM plugins:** `handler` is the export name from the package entry point (e.g., `validateMediaOptimization`). The function must be exported from `lib/index.ts`.  
+**Local plugins:** `handler` is a relative path to the module (e.g., `./validators/media-validator`). The module must export a `validate` function.
+
+Validators run during `jay-stack validate` against every parsed jay-html file in the project. See [validation.md](validation.md) for implementation details.
 
 ### Setup Fields
 
-- `handler` — Setup handler for `jay-stack setup` (handles config, credentials)
-- `references` — Reference generator for `jay-stack agent-kit` (generates discovery data)
-- `configTemplate` — Config file templates to copy during setup
+- `handler` — Export name (NPM) or relative path (local) for `jay-stack setup <plugin>`. Creates config files, validates credentials and services.
+- `references` — Export name (NPM) or relative path (local) for `jay-stack agent-kit`. Generates discovery data: add-menu items, reference files.
+- `description` — (optional) What this setup does
+
+**NPM plugins:** `handler` and `references` are export names from the package entry point.  
+**Local plugins:** relative paths to the handler modules.
+
+`jay-stack validate-plugin` checks that these handlers exist and are correctly exported.
+
+See [setup-guide.md](setup-guide.md) for implementation details.
 
 ## Package Layout
 

package/agent-kit-template/plugin/setup-guide.md

@@ -0,0 +1,177 @@
+# Plugin Setup & References
+
+Plugins can provide two hooks for project configuration and AI agent discovery:
+
+- **Setup handler** — runs during `jay-stack setup <plugin>`. Creates config files, validates credentials, copies AIditor assets.
+- **References handler** — runs during `jay-stack agent-kit`. Generates discovery data (add-menu items, reference files) using live services.
+
+## When Each Runs
+
+```
+jay-stack setup <plugin>     →  setup.handler()
+jay-stack agent-kit          →  setup.references()  (after contract materialization)
+```
+
+Setup runs once when a project first installs the plugin. Agent-kit runs whenever the developer regenerates the agent kit — it can use live services to produce fresh data.
+
+## Declaring in plugin.yaml
+
+```yaml
+setup:
+  handler: setupMyPlugin # export name (NPM) or ./path (local)
+  references: generateMyReferences # export name (NPM) or ./path (local)
+  description: Install My Plugin config and AIditor catalog
+```
+
+**NPM plugins:** both values are export names from the package entry point (`lib/index.ts`).  
+**Local plugins:** relative paths to the handler modules.
+
+`jay-stack validate-plugin` checks that these exist and are correctly exported.
+
+## Writing a Setup Handler
+
+The setup handler creates config files and AIditor assets. It receives a `PluginSetupContext` and returns a `PluginSetupResult`.
+
+```typescript
+import type { PluginSetupContext, PluginSetupResult } from '@jay-framework/stack-server-runtime';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export async function setupMyPlugin(ctx: PluginSetupContext): Promise<PluginSetupResult> {
+  if (ctx.initError) {
+    return { status: 'error', message: `Init failed: ${ctx.initError.message}` };
+  }
+
+  const configCreated: string[] = [];
+
+  // Write AIditor add-menu catalog
+  const addMenuPath = path.join(ctx.projectRoot, 'agent-kit/aiditor/add-menu/my-plugin.yaml');
+  if (!fs.existsSync(addMenuPath) || ctx.force) {
+    fs.mkdirSync(path.dirname(addMenuPath), { recursive: true });
+    fs.writeFileSync(addMenuPath, templateContent, 'utf-8');
+    configCreated.push('agent-kit/aiditor/add-menu/my-plugin.yaml');
+  }
+
+  return {
+    status: 'configured',
+    configCreated,
+    message:
+      configCreated.length > 0
+        ? 'My Plugin catalog installed.'
+        : 'My Plugin catalog already present (use --force to rewrite).',
+  };
+}
+```
+
+### PluginSetupContext
+
+| Field         | Type      | Description                                                       |
+| ------------- | --------- | ----------------------------------------------------------------- |
+| `pluginName`  | `string`  | Plugin name from plugin.yaml                                      |
+| `projectRoot` | `string`  | Absolute project root path                                        |
+| `configDir`   | `string`  | Config directory (from `.jay` configBase, defaults to `./config`) |
+| `services`    | `Map`     | Registered services (may be empty if init failed)                 |
+| `initError`   | `Error?`  | Present if plugin init failed — check this before using services  |
+| `force`       | `boolean` | Whether `--force` flag was passed                                 |
+
+### PluginSetupResult
+
+| Field           | Type                                        | Description                                     |
+| --------------- | ------------------------------------------- | ----------------------------------------------- |
+| `status`        | `'configured' \| 'needs-config' \| 'error'` | Overall result                                  |
+| `configCreated` | `string[]?`                                 | Config files created (relative to project root) |
+| `message`       | `string?`                                   | Human-readable status message                   |
+
+## Writing a References Handler
+
+The references handler generates discovery data at agent-kit time. It can use live services (database queries, API calls) to produce dynamic content.
+
+```typescript
+import type {
+  PluginReferencesContext,
+  PluginReferencesResult,
+} from '@jay-framework/stack-server-runtime';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export async function generateMyReferences(
+  ctx: PluginReferencesContext,
+): Promise<PluginReferencesResult> {
+  if (ctx.initError) {
+    return { referencesCreated: [], message: `Skipped: ${ctx.initError.message}` };
+  }
+
+  // Example: generate add-menu items from live data
+  const outputPath = path.join(ctx.projectRoot, 'agent-kit/aiditor/add-menu/my-plugin.yaml');
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  const items = [
+    { id: 'my-plugin:feature-1', title: 'Feature 1', category: 'My Plugin', prompt: '...' },
+  ];
+  fs.writeFileSync(outputPath, yaml.dump({ items }), 'utf-8');
+
+  return {
+    referencesCreated: ['agent-kit/aiditor/add-menu/my-plugin.yaml'],
+    message: `Generated ${items.length} add-menu items`,
+  };
+}
+```
+
+### PluginReferencesContext
+
+| Field           | Type      | Description                                                     |
+| --------------- | --------- | --------------------------------------------------------------- |
+| `pluginName`    | `string`  | Plugin name from plugin.yaml                                    |
+| `projectRoot`   | `string`  | Absolute project root path                                      |
+| `referencesDir` | `string`  | Directory for reference data (`agent-kit/references/<plugin>/`) |
+| `services`      | `Map`     | Registered services                                             |
+| `initError`     | `Error?`  | Present if plugin init failed                                   |
+| `force`         | `boolean` | Whether `--force` flag was passed                               |
+
+### PluginReferencesResult
+
+| Field               | Type       | Description                              |
+| ------------------- | ---------- | ---------------------------------------- |
+| `referencesCreated` | `string[]` | Files created (relative to project root) |
+| `message`           | `string?`  | Human-readable status message            |
+
+## Setup vs References — When to Use Which
+
+| Use case                                                             | Handler            | Why                                                             |
+| -------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
+| Copy static template files (add-menu catalog, skill guides)          | `setup.handler`    | Templates don't change — copy once                              |
+| Generate data from live services (product catalogs, CMS schemas)     | `setup.references` | Needs services initialized; regenerated on each `agent-kit` run |
+| Validate credentials / API keys                                      | `setup.handler`    | Part of initial project configuration                           |
+| Write AIditor add-menu from project-specific data (DESIGN.md tokens) | `setup.references` | Data comes from project files, not static templates             |
+
+## AIditor Add-Menu Items
+
+Both handlers can write to `agent-kit/aiditor/add-menu/<plugin-name>.yaml`. The AIditor discovers and loads all YAML files in this directory.
+
+Each item:
+
+```yaml
+items:
+  - id: my-plugin:feature-name # unique ID
+    title: Feature Name # shown in the add menu
+    category: My Plugin # grouping
+    subCategory: Components # sub-grouping
+    pluginName: my-plugin # optional: plugin attribution
+    packageName: '@my-org/my-plugin' # optional: npm package name
+    prompt: | # instructions for the AI agent
+      Use headless component @my-org/my-plugin / contract feature-name.
+      Read agent-kit/designer/feature-name.md for usage guide.
+```
+
+## Exporting Handlers
+
+For NPM plugins, export the handlers from the package entry point:
+
+```typescript
+// lib/index.ts
+export { setupMyPlugin } from './setup.js';
+export { generateMyReferences } from './references.js';
+// ... other exports (components, actions, services)
+```
+
+For local plugins, use relative paths in plugin.yaml instead of export names.

package/agent-kit-template/plugin/validation.md

@@ -1,5 +1,12 @@
 # Plugin Validation
 
+Two separate validation commands:
+
+- **`jay-stack validate-plugin`** — validates your plugin's own structure (run during plugin development)
+- **`jay-stack validate`** — validates a project's jay-html files, including running your plugin's custom validators (run from a project that uses your plugin)
+
+## validate-plugin
+
 Run `jay-stack validate-plugin` to check your plugin for errors.
 
 ## Usage
@@ -119,20 +126,27 @@ Values: `title`, `meta:<name>` (e.g., `meta:description`), `link:<rel>` (e.g., `
 
 Validators access this via `ctx.headlessImports[].providedHeadTags`.
 
-## Plugin Validators
+## Plugin Validators (jay-stack validate)
 
-Plugins can provide custom jay-html validation rules that run during `jay-stack validate`. Declare validators in `plugin.yaml`:
+Plugins can provide custom jay-html validation rules that run during `jay-stack validate` in projects that use your plugin. Declare validators in `plugin.yaml`:
 
 ```yaml
 validators:
   - name: media-optimization
-    handler: ./validators/media-validator
+    handler: validateMediaOptimization # export name from package entry point
     description: Ensures media URLs use resize parameters
 ```
 
+**Handler format:**
+
+- **NPM plugins** — `handler` is an export name from the package entry point (e.g., `validateMediaOptimization`). The function must be exported from `lib/index.ts`.
+- **Local plugins** (`src/plugins/`) — `handler` is a relative path to the module (e.g., `./validators/media-validator`). The module must export a `validate` function.
+
+`jay-stack validate-plugin` checks that the handler exists and is correctly exported.
+
 ### Writing a Validator
 
-The handler module exports a `validate` function:
+Export the validator function from the package entry point (for NPM) or from the handler module (for local):
 
 ```typescript
 import type { JayHtmlValidatorFn, JayHtmlValidationFinding } from '@jay-framework/compiler-shared';

package/dist/index.js

@@ -2748,15 +2748,6 @@ async function runRebuild(projectPath, options) {
     process.exit(1);
   }
 }
-const runProduction = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  initLogger,
-  resolveProductionContext,
-  resolveVersionFromPackageJson,
-  runBuild,
-  runRebuild,
-  runServe
-}, Symbol.toStringTag, { value: "Module" }));
 const s = createRequire(import.meta.url), e = s("typescript"), u = e;
 new Proxy(e, {
   get(t, r) {
@@ -3210,6 +3201,14 @@ async function validateSchema(context, result) {
             location: "plugin.yaml",
             suggestion: 'Specify the exported member name from the module (e.g., "moodTracker")'
           });
+        } else {
+          validateHandlerRef(
+            contract.component,
+            `Contract "${contract.name}" component`,
+            `plugin.yaml contracts[${index}]`,
+            context,
+            result
+          );
         }
       });
     }
@@ -3242,6 +3241,24 @@ async function validateSchema(context, result) {
           suggestion: 'Specify prefix for dynamic contract names (e.g., "cms")'
         });
       }
+      if (config.component) {
+        validateHandlerRef(
+          config.component,
+          `dynamic_contracts[${prefix}] component`,
+          `plugin.yaml dynamic_contracts`,
+          context,
+          result
+        );
+      }
+      if (config.generator) {
+        validateHandlerRef(
+          config.generator,
+          `dynamic_contracts[${prefix}] generator`,
+          `plugin.yaml dynamic_contracts`,
+          context,
+          result
+        );
+      }
     }
   }
   if (!manifest.contracts && !manifest.dynamic_contracts) {
@@ -3312,6 +3329,23 @@ async function validateSchema(context, result) {
       });
     }
   }
+  if (manifest.actions) {
+    for (const entry of manifest.actions) {
+      const exportName = typeof entry === "string" ? entry : entry.name;
+      if (exportName) {
+        validateHandlerRef(
+          exportName,
+          `Action "${exportName}"`,
+          "plugin.yaml actions",
+          context,
+          result
+        );
+      }
+    }
+  }
+  if (manifest.init) {
+    validateHandlerRef(manifest.init, "Init handler", "plugin.yaml init", context, result);
+  }
   if (manifest.routes) {
     if (!Array.isArray(manifest.routes)) {
       result.errors.push({
@@ -3343,6 +3377,14 @@ async function validateSchema(context, result) {
             location: "plugin.yaml",
             suggestion: "Specify the exported member name for the page component"
           });
+        } else {
+          validateHandlerRef(
+            route.component,
+            `Route "${route.path}" component`,
+            `plugin.yaml routes`,
+            context,
+            result
+          );
         }
         if (route.jayHtml) {
           validateDocFile(
@@ -3382,22 +3424,105 @@ async function validateSchema(context, result) {
             suggestion: "Specify the relative path to the validator handler module"
           });
         }
-        if (validator.handler && !context.isNpmPackage) {
-          const handlerPath = path.join(context.pluginPath, validator.handler);
-          const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
-          const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
-          if (!found) {
-            result.errors.push({
-              type: "file-missing",
-              message: `Validator "${validator.name}" handler not found: ${validator.handler}`,
-              location: "plugin.yaml validators",
-              suggestion: `Create the validator handler at ${handlerPath}.ts`
-            });
-          }
+        if (validator.handler) {
+          validateHandlerRef(
+            validator.handler,
+            `Validator "${validator.name}" handler`,
+            "plugin.yaml validators",
+            context,
+            result
+          );
         }
       });
     }
   }
+  if (manifest.setup) {
+    if (manifest.setup.handler) {
+      validateHandlerRef(
+        manifest.setup.handler,
+        "Setup handler",
+        "plugin.yaml setup.handler",
+        context,
+        result
+      );
+    }
+    if (manifest.setup.references) {
+      validateHandlerRef(
+        manifest.setup.references,
+        "References handler",
+        "plugin.yaml setup.references",
+        context,
+        result
+      );
+    }
+  }
+}
+function checkExportExists(exportName, context) {
+  const packageJsonPath = path.join(context.pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath))
+    return true;
+  let mainPath;
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    if (packageJson.exports?.["."]) {
+      const entry = packageJson.exports["."];
+      const entryPath = typeof entry === "string" ? entry : entry.default || entry.import;
+      if (entryPath)
+        mainPath = path.join(context.pluginPath, entryPath);
+    }
+    if (!mainPath && packageJson.main) {
+      mainPath = path.join(context.pluginPath, packageJson.main);
+    }
+  } catch {
+    return true;
+  }
+  if (!mainPath || !fs.existsSync(mainPath))
+    return true;
+  try {
+    const content = fs.readFileSync(mainPath, "utf-8");
+    const patterns = [
+      new RegExp(`export\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`, "m"),
+      new RegExp(`export\\s+(?:async\\s+)?function\\s+${exportName}\\b`),
+      new RegExp(`export\\s+(?:const|let|var)\\s+${exportName}\\b`)
+    ];
+    return patterns.some((p) => p.test(content));
+  } catch {
+    return true;
+  }
+}
+function isRelativePath(value) {
+  return value.startsWith("./") || value.startsWith("../");
+}
+function validateHandlerRef(value, label, location, context, result) {
+  if (context.isNpmPackage) {
+    if (isRelativePath(value)) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: `${label} "${value}" is a relative path, but NPM plugins must use an export name`,
+        location,
+        suggestion: `Export the function from the package entry point and use the export name instead of a path`
+      });
+    } else if (!checkExportExists(value, context)) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: `${label} "${value}" is not exported from the package`,
+        location,
+        suggestion: `Add "export { ${value} } from '...'" to the package entry point`
+      });
+    }
+  } else if (isRelativePath(value)) {
+    const handlerPath = path.join(context.pluginPath, value);
+    const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
+    const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
+    if (!found) {
+      result.errors.push({
+        type: "file-missing",
+        message: `${label} not found: ${value}`,
+        location,
+        suggestion: `Create the handler at ${handlerPath}.ts`
+      });
+    }
+  }
 }
 function resolveContractFile(contractSpec, context) {
   if (context.isNpmPackage) {
@@ -4218,6 +4343,32 @@ const HEADLESS_SKIP_ATTRS = /* @__PURE__ */ new Set([
   "jay-coordinate-base",
   "jay-scope"
 ]);
+const PHASE_ORDER = {
+  slow: 0,
+  fast: 1,
+  "fast+interactive": 2
+};
+function resolveBindingPhase(bindingPath, jayHtml) {
+  const segments = bindingPath.split(".");
+  const root = segments[0];
+  const keyedImport = jayHtml.headlessImports.find((i) => i.key === root && i.contract);
+  if (keyedImport?.contract) {
+    const tagPath = segments.slice(1).join(".");
+    if (!tagPath)
+      return void 0;
+    const tag = resolveContractTag(keyedImport.contract, tagPath);
+    if (!tag)
+      return void 0;
+    return tag.phase || "slow";
+  }
+  if (jayHtml.contract) {
+    const tag = resolveContractTag(jayHtml.contract, bindingPath);
+    if (!tag)
+      return void 0;
+    return tag.phase || "slow";
+  }
+  return void 0;
+}
 function checkHeadlessInstanceProps(jayHtml, file) {
   const imports = jayHtml.headlessImports;
   const warnings = [];
@@ -4236,25 +4387,53 @@ function checkHeadlessInstanceProps(jayHtml, file) {
           }
         }
         if (passedProps.size > 0) {
-          const contractPropNames = new Set((contract.props || []).map((p) => p.name));
+          const contractPropNamesLower = new Set(
+            (contract.props || []).map((p) => p.name.toLowerCase())
+          );
           for (const prop of passedProps) {
-            if (!contractPropNames.has(prop)) {
-              imp.key ? `${imp.key} (${contractName})` : contractName;
+            if (!contractPropNamesLower.has(prop.toLowerCase())) {
               warnings.push(
                 `<jay:${contractName}> passes attribute "${prop}" but the "${contract.name}" contract does not declare it as a prop. Add to ${contractName}.jay-contract: props: [{ name: ${prop}, type: string }]`
               );
             }
           }
         }
+        const passedPropsLower = new Set([...passedProps].map((p) => p.toLowerCase()));
         if (contract.props) {
           for (const contractProp of contract.props) {
-            if (contractProp.required && !passedProps.has(contractProp.name)) {
+            if (contractProp.required && !passedPropsLower.has(contractProp.name.toLowerCase())) {
               warnings.push(
                 `<jay:${contractName}> is missing required prop "${contractProp.name}" declared in the "${contract.name}" contract.`
               );
             }
           }
         }
+        if (contract.props) {
+          const lowerAttrs = {};
+          for (const [k, v] of Object.entries(attrs)) {
+            lowerAttrs[k.toLowerCase()] = v;
+          }
+          for (const contractProp of contract.props) {
+            const attrValue = lowerAttrs[contractProp.name.toLowerCase()];
+            if (!attrValue)
+              continue;
+            const bindingMatch = attrValue.match(/^\{(.+)\}$/);
+            if (!bindingMatch)
+              continue;
+            const bindingPath = bindingMatch[1];
+            const sourcePhase = resolveBindingPhase(bindingPath, jayHtml);
+            if (!sourcePhase)
+              continue;
+            const propPhase = contractProp.phase ?? "slow";
+            const sourceOrder = PHASE_ORDER[sourcePhase] ?? 0;
+            const propOrder = PHASE_ORDER[propPhase] ?? 0;
+            if (sourceOrder > propOrder) {
+              warnings.push(
+                `<jay:${contractName}> prop "${contractProp.name}" (phase: ${propPhase}) is bound to {${bindingPath}} which is phase: ${sourcePhase}. The binding source phase must be ≤ the prop phase. Use a ${propPhase}-phase binding, a route param, or a literal value.`
+              );
+            }
+          }
+        }
       }
     }
     for (const child of element.childNodes ?? []) {
@@ -4294,6 +4473,7 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
     if (!plugin.manifest.validators)
       continue;
     for (const validatorDef of plugin.manifest.validators) {
+      const source = `${plugin.name}/${validatorDef.name}`;
       let validatorFn;
       try {
         let handlerModule;
@@ -4308,19 +4488,22 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
           errors.push({
             file: `plugin:${plugin.name}`,
             message: `Validator "${validatorDef.name}" handler does not export a "validate" function`,
-            stage: "plugin"
+            stage: "plugin",
+            source
           });
+          loadedValidators.push(source);
           continue;
         }
       } catch (loadErr) {
         errors.push({
           file: `plugin:${plugin.name}`,
           message: `Failed to load validator "${validatorDef.name}": ${loadErr.message}`,
-          stage: "plugin"
+          stage: "plugin",
+          source
         });
+        loadedValidators.push(source);
         continue;
       }
-      const source = `${plugin.name}/${validatorDef.name}`;
       loadedValidators.push(source);
       for (const { relativePath, parsed } of parsedFiles) {
         const pageContractPath = parsed.contractRef ? path.resolve(
@@ -4660,12 +4843,12 @@ async function runValidatePlugin(pluginPath, options) {
     strict: options.strict,
     generateTypes: options.generateTypes
   });
-  printValidationResult(result, options.verbose ?? false);
+  printPluginValidationResult(result, options.verbose ?? false);
   if (!result.valid || options.strict && result.warnings.length > 0) {
     process.exit(1);
   }
 }
-function printValidationResult(result, verbose) {
+function printPluginValidationResult(result, verbose) {
   const logger = getLogger();
   if (result.valid && result.warnings.length === 0) {
     logger.important(chalk.green("Plugin validation successful!\n"));
@@ -5462,9 +5645,8 @@ program.command("rebuild").description("Rebuild instances by contract, route, or
 });
 program.command("cleanup").description("Delete orphaned files from previous rebuilds").option("--version <n>", "Build version (default: from package.json)").option("-p, --path <path>", "Project root (default: cwd)").action(async (options) => {
   try {
-    const { initLogger: initLogger2, resolveProductionContext: resolveProductionContext2 } = await Promise.resolve().then(() => runProduction);
-    initLogger2();
-    const ctx = await resolveProductionContext2(options.path, options.version);
+    initLogger();
+    const ctx = await resolveProductionContext(options.path, options.version);
     const { cleanupOrphanedFiles } = await import("@jay-framework/production-server");
     await cleanupOrphanedFiles(ctx.buildRoot, ctx.version);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.19.8",
+  "version": "0.21.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,15 +24,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.19.8",
-    "@jay-framework/compiler-shared": "^0.19.8",
-    "@jay-framework/dev-server": "^0.19.8",
-    "@jay-framework/editor-server": "^0.19.8",
-    "@jay-framework/fullstack-component": "^0.19.8",
-    "@jay-framework/logger": "^0.19.8",
-    "@jay-framework/plugin-validator": "^0.19.8",
-    "@jay-framework/production-server": "^0.19.8",
-    "@jay-framework/stack-server-runtime": "^0.19.8",
+    "@jay-framework/compiler-jay-html": "^0.21.0",
+    "@jay-framework/compiler-shared": "^0.21.0",
+    "@jay-framework/dev-server": "^0.21.0",
+    "@jay-framework/editor-server": "^0.21.0",
+    "@jay-framework/fullstack-component": "^0.21.0",
+    "@jay-framework/logger": "^0.21.0",
+    "@jay-framework/plugin-validator": "^0.21.0",
+    "@jay-framework/production-server": "^0.21.0",
+    "@jay-framework/stack-server-runtime": "^0.21.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -43,7 +43,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.19.8",
+    "@jay-framework/dev-environment": "^0.21.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",