@jay-framework/jay-stack-cli 0.24.6 → 0.25.0

package/agent-kit-template/INSTRUCTIONS.md

@@ -2,6 +2,29 @@
 
 This agent kit provides role-specific guides for building a Jay Stack application. Each role covers a different aspect of the project.
 
+## Component model: Jay Stack is headless-only
+
+Jay has two component models, and **Jay Stack uses only one of them — headless.**
+
+- **Headless — the Jay Stack model.** Logic + a `.jay-contract`, with **no bound template of its own**. The
+  consuming page (or component) provides the UI by flattening the component's template into a `<jay:X>`
+  region. Authored with `makeJayStackComponent` (full-stack: slow/fast/interactive) or provided by a plugin.
+  Imported with `<script type="application/jay-headless" contract="…" [src="…"] [template="…"]>`. This is the
+  only component model a Jay Stack page composes.
+- **Headfull — the lower-level Jay model.** Logic bundled with its **own** template via `makeJayComponent`.
+  Imported with `<script type="application/jay-headfull" src="…" names="…">` (**no** `contract=`). It has **no
+  server rendering**, so it is **never used directly in a Jay Stack page** — use it only in standalone,
+  client-only Jay apps. A `jay-headfull` import carrying a `contract=` is a hard build error (DL#196).
+
+Throughout this kit, "component" means a headless component unless it explicitly says otherwise.
+
+**Prefer a design system.** When UI is reused — or could be — compose it from headless components that ship
+`.jay-html` templates (a _design system_) and **flatten** those templates into your pages as design-system
+elements (`template=` + `jay-stack sync`), rather than hand-writing each `<jay:X>` region's markup. Flattened
+regions stay consistent across pages and upgrade in one step via `sync`, while `validate` tracks any
+per-page edits you choose to keep. Hand-author a region's body only when no template is shipped for it. See
+[designer/design-system-guide.md](designer/design-system-guide.md).
+
 ## Roles
 
 ### Designer (`designer/`)
@@ -12,7 +35,7 @@ Creates `.jay-html` pages and templates. Binds to contract data using template s
 
 ### Developer (`developer/`)
 
-Creates page components (`page.ts`) using `makeJayStackComponent`, defines page contracts (`page.jay-contract`), configures routing, and sets up project services. Also creates headfull components for shared UI sections (headers, footers).
+Creates page components (`page.ts`) using `makeJayStackComponent`, defines page contracts (`page.jay-contract`), configures routing, and sets up project services. Also creates shared full-stack components (headless) for reusable UI sections (headers, footers).
 
 **Use when:** adding page logic, defining data shapes, configuring the project, or creating shared components.
 

package/agent-kit-template/contracts/GUIDE.md

@@ -13,7 +13,7 @@ A page has its own data that isn't fully provided by plugins.
 - Can coexist with plugin headless contracts on the same page
 - See [page-contracts.md](page-contracts.md)
 
-### Headfull component contract
+### Full-stack component contract
 
 A shared UI section (header, footer, sidebar) that appears across multiple pages.
 

package/agent-kit-template/contracts/component-contracts.md

@@ -1,25 +1,27 @@
-# Headfull Component Contracts
+# Full-Stack Component Contracts
 
-Headfull components in Jay Stack are full-stack and must have a contract. The contract defines the data the component provides to its template.
+Shared full-stack components in Jay Stack are **headless** — logic + a contract, with their template
+provided by the consuming page. The contract defines the data the component provides to that template.
 
 ## When to Use
 
-Use a headfull component contract for shared UI sections that appear across multiple pages: headers, footers, sidebars, navigation menus.
+Use a full-stack component contract for shared UI sections that appear across multiple pages: headers,
+footers, sidebars, navigation menus.
 
 ## File Structure
 
-Each headfull component lives in its own subdirectory under `src/components/`:
+Each component lives in its own subdirectory under `src/components/`:
 
 ```
 src/components/site-header/
   site-header.ts             # makeJayStackComponent logic
-  site-header.jay-html       # template
+  site-header.jay-html       # source template (flattened into the page)
   site-header.jay-contract   # contract (required)
 ```
 
 ## Contract with Props
 
-Headfull components use `props` (not `params`) for configuration passed by the parent page:
+Full-stack components use `props` (not `params`) for configuration passed by the parent page:
 
 ```yaml
 name: site-header
@@ -55,23 +57,51 @@ tags:
 
 ## Importing in jay-html
 
-The import must include the `contract` attribute:
+Import it as a headless component — `src=` for the logic, `contract=` for the data shape, and `template=`
+so `jay-stack sync` can flatten the component's markup into the page:
 
 ```html
 <script
-  type="application/jay-headfull"
+  type="application/jay-headless"
   src="../components/site-header/site-header"
-  names="SiteHeader"
   contract="../components/site-header/site-header.jay-contract"
+  template="../components/site-header/site-header.jay-html"
 ></script>
 ```
 
-Usage in the page body:
+Usage in the page body — place the region and run `jay-stack sync` to flatten its body:
 
 ```html
-<jay:SiteHeader logoUrl="/logo.png" />
+<jay:SiteHeader ref="header" logoUrl="/logo.png" />
 ```
 
+> `application/jay-headfull` with a `contract=` attribute is a hard build error (DL#196). `jay-headfull` is
+> the lower-level Jay model (`makeJayComponent`, no server rendering) and is never used in a Jay Stack page.
+> See [jay-html-components.md](../designer/jay-html-components.md#headfull-components-are-not-for-jay-stack).
+
+## Templates and the sync / validate pair
+
+A headless component has **no bound template of its own** — but it can **ship one or more `.jay-html`
+templates** alongside its logic and contract, for pages to flatten. Each is a self-contained template over
+the same contract; a page chooses which one to flatten with `template=`:
+
+```
+src/components/site-header/
+  site-header.ts                 # logic (makeJayStackComponent)
+  site-header.jay-contract       # contract (required)
+  site-header.jay-html           # default template
+  site-header-compact.jay-html   # an alternative template (optional)
+```
+
+Flattening copies the chosen template's markup into the page, where you own and edit the copy. This is a
+**design-system element** — and the `sync` / `validate` pair keeps the copy honest:
+
+- `jay-stack validate` diffs the page's flattened region against its source `template=` and reports drift
+  (at facet granularity) as warnings.
+- `jay-stack sync` re-flattens from the current source, preserving the facets you marked `override`.
+
+See [design-system-guide.md](../designer/design-system-guide.md) for the full drift / facet / sync model.
+
 ## Component Contract vs Page Contract
 
 |              | Page contract                          | Component contract                                                   |
@@ -79,4 +109,4 @@ Usage in the page body:
 | **Location** | `src/pages/.../page.jay-contract`      | `src/components/<name>/<name>.jay-contract`                          |
 | **Params**   | Yes (from route segments)              | No (components don't own routes)                                     |
 | **Props**    | Rarely                                 | Yes (configured by parent)                                           |
-| **Import**   | `<script type="application/jay-data">` | `<script type="application/jay-headfull">` with `contract` attribute |
+| **Import**   | `<script type="application/jay-data">` | `<script type="application/jay-headless">` with `contract` attribute |

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

@@ -31,31 +31,34 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 4. **Read actions** — read `.jay-action` files (paths from plugins-index) to see action descriptions, input schemas, and output schemas. This tells you what data each action accepts and returns.
 5. **Read references** — check `references/<plugin>/` for pre-generated discovery data (product catalogs, collection schemas, etc.). These are generated by `jay-stack agent-kit` and contain real data from the site.
 6. **Discover data** — run `jay-stack params <plugin>/<contract>` for SSG route params, `jay-stack action <plugin>/<action>` for data discovery. Use reference files (step 5) first when available — they're faster than running CLI commands.
-7. **Create pages** — write `.jay-html` files under `src/pages/` following directory-based routing. For static override routes (a static page that overrides a dynamic route for a specific URL), declare params with `<script type="application/jay-params">`. Jay-html `if` and `{…}` bind to **tag names only** — no `.length`, method calls, or bracket indexing; derive booleans and counts in `page.ts` (see [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important)).
+7. **Create pages** — write `.jay-html` files under `src/pages/` following directory-based routing. **Prefer a design system:** when a plugin or component ships a `.jay-html` template, flatten it into your page as a design-system element (`template=` + `jay-stack sync`) and tweak the copy, rather than hand-writing the `<jay:X>` body — see [design-system-guide.md](design-system-guide.md). For static override routes (a static page that overrides a dynamic route for a specific URL), declare params with `<script type="application/jay-params">`. Jay-html `if` and `{…}` bind to **tag names only** — no `.length`, method calls, or bracket indexing; derive booleans and counts in `page.ts` (see [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important)).
 8. **Validate** — run `jay-stack validate` to check for errors.
 9. **Test** — run `jay-stack dev --test-mode` and verify pages render.
 
 ## Reference Docs
 
-| File                                                       | Topic                                                                                           |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| [project-structure.md](project-structure.md)               | Project layout, styling patterns (CSS themes, design tokens), configuration files               |
-| [jay-html-syntax.md](jay-html-syntax.md)                   | Jay-HTML overview: philosophy, component types, nesting rules, links to sub-files               |
-| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: data binding, conditions, expression limits (no `.length`), loops, refs        |
-| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), headfull FS, nesting patterns                       |
-| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic style bindings, class bindings                               |
-| [routing.md](routing.md)                                   | Directory-based routing: page structure, dynamic routes, route priority                         |
-| [navigation-patterns.md](navigation-patterns.md)           | Active menu/sidebar patterns using `jay.url.path`, `===`, and `^=` operators                    |
-| [contracts-and-plugins.md](contracts-and-plugins.md)       | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                 |
-| [Contract Authoring Guide](../contracts/GUIDE.md)          | Writing contracts: syntax, page/component/linked contracts, examples                            |
-| [script-tags.md](script-tags.md)                           | Script tag policy: use page.ts for behavior, jay-script="allow" for third-party scripts         |
-| [cli-commands.md](cli-commands.md)                         | CLI commands: setup, validate, params, action, dev server                                       |
-| [validation-guide.md](validation-guide.md)                 | Understanding validation output: static analysis, component warnings, how to act on findings    |
-| `../references/<plugin>/`                                  | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
-
-## When to Use Headfull Components
-
-Use headfull full-stack components for **shared UI sections that should look the same across pages** — headers, navigation menus, footers, sidebars. These are placed in `src/components/` and imported into any page that needs them. This keeps the shared layout in one place: update the component once and every page reflects the change.
+| File                                                       | Topic                                                                                                                                                          |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [project-structure.md](project-structure.md)               | Project layout, styling patterns (CSS themes, design tokens), configuration files                                                                              |
+| [jay-html-syntax.md](jay-html-syntax.md)                   | Jay-HTML overview: philosophy, component types, nesting rules, links to sub-files                                                                              |
+| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: data binding, conditions, expression limits (no `.length`), loops, refs                                                                       |
+| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), full-stack components, nesting, per-instance customization                                                         |
+| [design-system-guide.md](design-system-guide.md)           | Design-system elements — **create** (author template + contract, `jay-content` slots) and **use** (flatten with `template=`, drift, `override` facets, `sync`) |
+| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic style bindings, class bindings                                                                                              |
+| [routing.md](routing.md)                                   | Directory-based routing: page structure, dynamic routes, route priority                                                                                        |
+| [navigation-patterns.md](navigation-patterns.md)           | Active menu/sidebar patterns using `jay.url.path`, `===`, and `^=` operators                                                                                   |
+| [contracts-and-plugins.md](contracts-and-plugins.md)       | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                                                                                |
+| [Contract Authoring Guide](../contracts/GUIDE.md)          | Writing contracts: syntax, page/component/linked contracts, examples                                                                                           |
+| [script-tags.md](script-tags.md)                           | Script tag policy: use page.ts for behavior, jay-script="allow" for third-party scripts                                                                        |
+| [cli-commands.md](cli-commands.md)                         | CLI commands: setup, validate, sync, params, action, dev server                                                                                                |
+| [validation-guide.md](validation-guide.md)                 | Understanding validation output: static analysis, component warnings, how to act on findings                                                                   |
+| `../references/<plugin>/`                                  | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`)                                                                |
+
+## When to Use Shared Full-Stack Components
+
+Use shared full-stack components (headless — `makeJayStackComponent` + contract) for **shared UI sections that should look the same across pages** — headers, navigation menus, footers, sidebars. These are placed in `src/components/` and imported into any page that needs them. This keeps the shared layout in one place: update the component once and every page reflects the change.
+
+The component ships its UI as one or more `.jay-html` templates. A page **flattens** a chosen template into a `<jay:X>` region (a **design-system element**) with `template=` + `jay-stack sync`, and may then tweak that copy. `jay-stack validate` reports where the copy has drifted from the source and `jay-stack sync` re-flattens it — so the component stays reusable while a page can still own per-instance edits. See [design-system-guide.md](design-system-guide.md).
 
 If a section is **unique to a single page**, write it directly in the page's `.jay-html` — no component needed.
 

package/agent-kit-template/designer/cli-commands.md

@@ -93,6 +93,52 @@ Errors:
 
 Always run validate after creating or editing jay-html and contract files.
 
+`validate` also nudges you to reuse UI through **design-system elements** (warnings, never blocking):
+`REGION-NOT-LINKED` (a hand-authored region that could link a shipped template), `COMPONENT-NO-TEMPLATE` (a
+component shipping no template), `REGION-OVERRIDE-NON-CONTENT` (a linked region restyled into its own
+variant), and `NO-DESIGN-SYSTEM` (the project uses none). Each is suppressible — see
+[design-system-guide.md](design-system-guide.md#suppressing-the-preference-warnings) and
+[validation-guide.md](validation-guide.md).
+
+## jay-stack sync
+
+Re-flatten **design-system elements** — `<jay:X>` regions whose import carries `template=` — from their
+current source templates. Fills an empty region on first use, and re-flattens after a component upgrade,
+**preserving every facet you marked `override`**. See
+[design-system-guide.md](design-system-guide.md) for the full model.
+
+```bash
+# Sync every design-system region in the project
+jay-stack sync
+
+# Sync a single page
+jay-stack sync src/pages/home.jay-html
+
+# Explicitly sync all pages
+jay-stack sync --all
+
+# Show pages that were already in sync
+jay-stack sync -v
+```
+
+Sync is **re-flatten, not merge**: it overwrites everything from source except your `override` facets — no
+merge base, no conflict prompt. It only touches regions with `template=` provenance; keyed and
+hand-authored nested components are left alone. CSS reconciles the same way: an `@scope (.<ref>)` block is
+rewritten to canonical form unless it carries a `/* jay:override */` pragma, which is preserved verbatim.
+
+Example output:
+
+```
+✓ synced 2 region(s) in src/pages/home.jay-html
+Synced 2 region(s) across 1 file(s).
+```
+
+When nothing needs re-flattening:
+
+```
+Nothing to sync.
+```
+
 ## jay-stack params
 
 Discover load param values for SSG route generation.

package/agent-kit-template/designer/contracts-and-plugins.md

@@ -1,5 +1,20 @@
 # Contracts and Plugins
 
+## Discovery: Design-System Index (what you can flatten)
+
+Before hand-authoring a `<jay:X>` region, check what design-system elements already exist. After
+`jay-stack agent-kit`, two generated files catalog every component you can flatten:
+
+- **`design-system.md`** — a human/agent "add-menu": each component, its template variants, and a
+  paste-ready `template=` import + `<jay:X>` snippet. Start here to pick something to add.
+- **`design-system-index.yaml`** — the structured form (linked from `plugins-index.yaml` via
+  `designSystemIndex`). Each component lists its `contractPath`, a component-level `description`, and
+  its `templates[]` (`{ path, variant, title? }`). An empty `templates: []` means the component ships
+  no template yet and must be hand-authored.
+
+Prefer flattening a listed template (link it with `template=` and run `jay-stack sync`) over
+hand-writing the region. See `designer/design-system-guide.md`.
+
 ## Discovery: Plugins Index
 
 After running `jay-stack agent-kit`, read `plugins-index.yaml`:
@@ -100,10 +115,24 @@ props:
   - name: productId
     type: string
     required: true
+    phase: fast # slow (default), fast, or fast+interactive
     description: The ID of the product to display
 ```
 
-Use in jay-html: `<jay:contract-name productId="value">`.
+Use in jay-html: `<jay:contract-name productId="value">` (a literal), or bind a page tag: `<jay:contract-name productId="{someTag}">`.
+
+**Prop phase must cover the binding source.** A prop has a `phase` (like a tag) that declares when the component reads it. When you bind a prop to a page tag, the **source tag's phase must be ≤ the prop's phase**:
+
+- Binding a `slow` prop to a `fast` / `fast+interactive` tag is a **validation error** — the prop is resolved at build, where the source doesn't exist yet, so it would render `''` at SSR. Bind a `fast`-phase source, a route param, or a literal instead.
+- Binding a `fast` (constant) prop to a `fast+interactive` (changing) source is also an error — a constant can't track a value that changes on the client.
+- A higher-phase prop accepts any lower-or-equal source (e.g. a `fast+interactive` prop takes a `slow`, `fast`, or `fast+interactive` binding).
+
+`jay-stack validate` (and `dev` / `build`) report these mismatches with the exact prop, source, and phases.
+
+**Enum prop values must match the contract.** For a prop typed `enum(a | b | c)`:
+
+- A **literal** value must be one of the declared members, case-sensitive — `status="success"` is fine, `status="sucess"` or `status="Success"` is a **validation error** naming the allowed members. (A wrong value silently renders nothing, because no `if="status===..."` branch matches.)
+- A **bound** value (`status="{someTag}"`) must come from a source that is itself an enum with the **same members in the same order**. Binding a `string` tag, or an enum with different or reordered members, to an enum prop is a validation error.
 
 ### Params