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

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

@@ -6,9 +6,9 @@ A page component (`page.ts`) uses `makeJayStackComponent` to provide page-level
 
 ```typescript
 import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
-import type { HomePageContract } from './page.jay-contract.generated';
+import type { PageContract } from './page.jay-contract';
 
-export const page = makeJayStackComponent<HomePageContract>()
+export const page = makeJayStackComponent<PageContract>()
   .withSlowlyRender(async () => {
     return phaseOutput({ heroTitle: 'Welcome', heroSubtitle: 'Build something great' }, {});
   })
@@ -19,6 +19,27 @@ export const page = makeJayStackComponent<HomePageContract>()
 
 The export name must be `page` for page-level components.
 
+## Where to import page types from
+
+Both `page.jay-contract.d.ts` and `page.jay-html.d.ts` are generated next to your page (on `dev`/`build`).
+They cover **different surfaces** — import from the right one:
+
+- **Data types and runtime enum/variant _values_** (`PageContract`, `PageViewState`, `PageSlowViewState`,
+  `PageFastViewState`, `PageRefs`, and any `enum` your contract declares) → import from **`./page.jay-contract`**.
+  This mirrors how a component's `.ts` imports from its own `./X.jay-contract`. A runtime enum value
+  (e.g. `Status.warning`) **must** come from here — importing it from `./page.jay-html` pulls the browser element
+  module into server-side SSR and fails.
+- **Composed refs that come from the template** — child-component refs, and DL#198 free refs like
+  `refs.card.dismiss` — live only in `page.jay-html.d.ts`. Import them **type-only** from **`./page.jay-html`**
+  (type-only so nothing is loaded at runtime):
+
+  ```typescript
+  import type { PageElementRefs } from './page.jay-html';
+  ```
+
+Rule of thumb: **data → `./page.jay-contract`; template/composed refs → `./page.jay-html` (type-only)**.
+Do not import runtime values from `./page.jay-html`, and there is no `.generated` suffix.
+
 ## Page Component with Params
 
 For dynamic routes, use `withLoadParams` and access params via props:

package/agent-kit-template/developer/project-structure.md

@@ -14,7 +14,7 @@ my-project/
 │   ├── project.conf.yaml       # Project metadata (name, etc.)
 │   └── <plugin-name>.yaml      # Plugin-specific config files
 ├── src/
-│   ├── components/              # Headfull full-stack components (shared across pages)
+│   ├── components/              # Shared full-stack components, headless (shared across pages)
 │   │   └── site-header/
 │   │       ├── site-header.ts
 │   │       ├── site-header.jay-html

package/agent-kit-template/developer/routing.md

@@ -124,7 +124,7 @@ tags:
 
 ## Dynamic Routes and Contract Params
 
-When a component on the page — whether the page contract, a headless component, or a headfull full-stack component — declares `params`, the page should be placed in a dynamic route directory that provides those params.
+When a component on the page — whether the page contract, a plugin headless component, or a shared full-stack component — declares `params`, the page should be placed in a dynamic route directory that provides those params.
 
 For example, if a headless component's contract declares:
 

package/agent-kit-template/devops/production-build.md

@@ -72,7 +72,7 @@ The build is **environment-agnostic**. The same output serves any deployment mod
 
 For production builds to work correctly:
 
-- **Headfull FS components** must be in `src/components/` (not inside page directories)
+- **Full-stack components** (headless) must be in `src/components/` (not inside page directories)
 - **Headless plugins** must be in `src/plugins/`
 - **Actions** must be in `src/actions/` with `*.actions.ts` naming
 - **Init** must be at `src/init.ts`

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

@@ -4,7 +4,7 @@ This folder contains guides for creating jay-stack plugins: contracts, headless
 
 ## What is a Jay Plugin?
 
-A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can also provide complete pages (backoffice tools, admin dashboards) via routes. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
+A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can also provide complete pages (backoffice tools, admin dashboards) via routes. **Prefer shipping your components as design-system elements** — a component that also ships one or more `.jay-html` templates designers flatten into their pages and upgrade via `jay-stack sync` (see [design-system-guide.md](design-system-guide.md)). Shipping a template gives consumers consistent, upgradable UI out of the box instead of hand-authoring every region; ship a bare contract (no template) only when the component truly has no default markup. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
 
 ## Workflow
 
@@ -40,6 +40,7 @@ The plugin participates in four CLI commands, each running different hooks:
 | [contracts-guide.md](contracts-guide.md)               | Plugin-specific contract concerns                                       |
 | [plugin-structure.md](plugin-structure.md)             | plugin.yaml, package layout, exports                                    |
 | [component-structure.md](component-structure.md)       | makeJayStackComponent, builder API, three-phase rendering               |
+| [design-system-guide.md](design-system-guide.md)       | Shipping a template designers flatten; upgrades via `jay-stack sync`    |
 | [component-state.md](component-state.md)               | createSignal, createMemo, createEffect, createDerivedArray, createEvent |
 | [component-refs.md](component-refs.md)                 | Refs, collection refs, element types                                    |
 | [component-data.md](component-data.md)                 | Immutable data, JSON Patch, createPatchableSignal                       |
@@ -61,6 +62,7 @@ The plugin participates in four CLI commands, each running different hooks:
 ## Key Principles
 
 - **Contract is the source of truth** — define it before implementing the component
+- **Ship a design system** — give each component one or more `.jay-html` templates so consumers flatten and upgrade via `jay-stack sync`, rather than hand-authoring UI
 - **Data is immutable** — never mutate ViewState directly, use JSON Patch
 - **Phase-aware** — choose the right rendering phase for each piece of data
 - **Props for configuration, params for URLs** — props are passed by parent components, params come from route segments

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

@@ -6,7 +6,7 @@ Full-stack components use `makeJayStackComponent` with a fluent builder API and
 
 ```typescript
 import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
-import type { MyContract } from './my-contract.generated';
+import type { MyContract } from './my-contract.jay-contract';
 
 export const myComponent = makeJayStackComponent<MyContract>()
   .withSlowlyRender(async (props) => {

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

@@ -173,12 +173,30 @@ props:
   - name: productId
     type: string
     required: true
+    phase: fast # slow (default), fast, or fast+interactive
     description: The product to display
   - name: showPricing
     type: boolean
     default: 'true'
 ```
 
+#### Prop phases — declare the phase you consume the prop
+
+A prop has a `phase` just like a tag, and it declares **when your component reads that prop**. The binding at the usage site must have a source phase ≤ the prop's phase (validated at build; see [validation.md](validation.md)).
+
+| Prop phase         | Resolved at       | At `slow` it is…   | Read it in                                      | At interactive it is…              |
+| ------------------ | ----------------- | ------------------ | ----------------------------------------------- | ---------------------------------- |
+| `slow` (default)   | build             | present            | `slowlyRender`, `fastRender`, `withInteractive` | a signal `() => T`, constant value |
+| `fast`             | request           | `undefined` / `''` | `fastRender`, `withInteractive`                 | a signal `() => T`, constant value |
+| `fast+interactive` | request (initial) | `undefined` / `''` | `fastRender`, `withInteractive`                 | a **reactive** signal `() => T`    |
+
+Two rules to internalize:
+
+- **A `fast` / `fast+interactive` prop is `undefined` (or `''` for a string binding) during `slow`.** Never read such a prop in `slowlyRender` — declare the prop at the phase where you actually consume it (the same phase your render function runs at). `markdown-content` reads `props.markdown` at slow → `slow`; `markdown-live` reads it at fast and as a signal at interactive → `fast+interactive`.
+- **At the interactive phase every prop arrives as a signal (`() => T`)** — the same shape for all phases, reactive only for `fast+interactive`. Type interactive props as `() => T` in the `.ts` (matching client-only Jay), regardless of phase.
+
+The prop type stays a single in-code declaration (`.withProps<T>()`) — the framework does not generate per-phase prop types. It is the author's job (backed by validation) not to read a `fast` prop at slow.
+
 ### Params — URL route segments
 
 Params come from dynamic route segments (`[slug]`, `[[lang]]`, `[...path]`). Use for page-level routing data.

package/agent-kit-template/plugin/design-system-guide.md

@@ -0,0 +1,173 @@
+# Shipping a Design-System Element
+
+A classic plugin component is **headless**: it ships a contract (and usually code) and provides _no UI_ —
+the project designer writes the template. A **design-system element** is the opposite end of the same
+mechanism: your plugin also ships a **template** (`.jay-html`), and the designer _flattens_ (copies) it into
+their page rather than authoring the markup from scratch. The designer then owns the copy and tweaks it;
+when you release a new version of the template, they pull your changes with `jay-stack sync`.
+
+Use this when your component has an opinionated look you want to _provide_ (a pricing card, a product tile,
+a callout) while still letting each project edit individual instances.
+
+## What you ship
+
+A design-system element ships three things — the template is what makes it a design-system element:
+
+| File            | Required? | Purpose                                                                |
+| --------------- | --------- | ---------------------------------------------------------------------- |
+| `.jay-contract` | Yes\*     | Data shape, props, refs — the source of truth (as for any component)   |
+| `.ts`           | Optional  | Logic (`makeJayStackComponent`). Omit for a pure-markup element        |
+| `.jay-html`     | **Yes**   | The template the designer flattens — its `<body>` markup and `<style>` |
+
+> **You ship a template, not a running UI.** The `.jay-html` is a _source to copy from_, not a live
+> component that renders itself at the usage site. The designer's flattened copy is what compiles and
+> renders. This is why upgrades flow through `sync` (below) rather than automatically — the project owns
+> its copy.
+
+> \* **The contract can be empty for a pure presentational element.** It must exist (it names the element
+> and is what the consumer's `contract=` import resolves), but if the element binds no data and ships no
+> `.ts`, the contract needs nothing but a name — `name: HeroBanner` plus `tags: []`.
+
+### The template file
+
+An ordinary `.jay-html`: a `<head>` declaring the contract, a `<body>` with the markup, and an optional
+`<style>`. Bind `{…}` against your own contract tags/props.
+
+```html
+<!-- pricing-card/pricing-card.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-data" contract="./pricing-card.jay-contract"></script>
+  </head>
+  <body>
+    <div class="pricing-card">
+      <h3 class="plan">{planName}</h3>
+      <p class="price">{price}</p>
+      <button class="cta">{ctaLabel}</button>
+    </div>
+  </body>
+  <style>
+    .plan {
+      font-weight: 600;
+    }
+    .cta {
+      background: var(--brand, #2b6cb0);
+    }
+  </style>
+</html>
+```
+
+The component's CSS is copied alongside the markup and `@scope`-wrapped by the region's `ref` at the usage
+site, so it never leaks into the project's other selectors.
+
+## How the designer consumes it
+
+The designer imports the component with a `template=` provenance marker pointing at your shipped `.jay-html`,
+places the region, and runs `jay-stack sync` to flatten it:
+
+```html
+<script
+  type="application/jay-headless"
+  plugin="my-plugin"
+  contract="pricing-card"
+  template="./node_modules/@my-org/my-plugin/lib/components/pricing-card/pricing-card.jay-html"
+></script>
+```
+
+```html
+<jay:pricing-card ref="pro" planName="Pro">…flattened copy, edited freely…</jay:pricing-card>
+```
+
+They edit the copy, marking any facet they want to keep with `override` (see the designer guide,
+`designer/design-system-guide.md`). `jay-stack validate` reports unmarked edits as drift.
+
+## Upgrades flow through `sync`
+
+Because the designer owns a _copy_, a change you ship in the template does **not** reach their page
+automatically. To pull your update, the designer runs:
+
+```bash
+jay-stack sync
+```
+
+Sync re-flattens every region from the current source template, **preserving the facets the project marked
+`override`** and overwriting the rest. It is a deterministic overwrite-with-holes — no merge base, no
+conflict resolution — so an upgrade can never silently mis-merge project edits with your changes.
+
+### Design your template for clean upgrades
+
+- **Keep structural churn low between versions.** Sync preserves a marked facet by matching nodes
+  positionally; large structural rewrites force the project to re-mark and re-review. Prefer additive,
+  localized changes.
+- **Name meaningful hooks with `class`.** Projects override at the facet level (`class`, a style property,
+  `children`). Stable class names make their `override` marks survive your edits.
+- **Version your template with your package.** The template ships from your package path; a project's
+  `jay-stack sync` reads whatever version is installed, so a normal dependency bump + `sync` is the whole
+  upgrade path.
+- **Document the intended override points** in the contract `description` — tell projects which parts are
+  meant to be customized versus left to reconcile.
+
+## Declaring content slots — `jay-content`
+
+`override` is the designer's tool, applied **per page, per instance**, to keep an edit you did not
+anticipate. `jay-content` is **your** tool: put it on a template node to declare up front "this is the
+consumer's to fill." Edits to a marked facet are then expected by design — `validate` never reports them as
+drift, and `sync` keeps the consumer's version — **without** the designer marking anything. It is the
+source-of-truth way to say "fill this in" for the parts of your template that are meant to vary.
+
+It lives on the **source template only**. It is never copied onto the flattened page (sync strips it), so it
+is stated **once** and is resilient to your future template edits: as long as the marker stays, consumer
+content stays silent; remove it and that node falls back to the normal override model.
+
+**It is optional, not required.** Unlike slot syntax in other frameworks, you do not have to annotate every
+variable node — an unmarked spot still works, it just surfaces as drift until the consumer marks `override`
+or runs `sync`. Add `jay-content` only where it earns its keep: a node genuinely meant to vary, where you'd
+rather spare every consumer from repeating the same `override`.
+
+### Options (same facet-list grammar as `override`)
+
+| You declare consumer-owned…      | Write                        | Typical use                                      |
+| -------------------------------- | ---------------------------- | ------------------------------------------------ |
+| the children (text/markup)       | `jay-content` (bare)         | a body copy / heading slot — **the default**     |
+| specific attributes              | `jay-content="src alt"`      | a media `<img>` the consumer supplies            |
+| one inline-style declaration     | `jay-content="style.color"`  | a themeable color the consumer sets              |
+| children **and** some attributes | `jay-content="children src"` | a figure whose image and caption are both theirs |
+| the whole node                   | `jay-content="*"`            | an entirely consumer-authored region             |
+
+Facets are space- or comma-separated (`jay-content="src, alt"`). The grammar is identical to `override`
+with **one** difference: a **bare** `jay-content` means **children** (the common text slot), whereas a bare
+`override` means the whole node. Use `*` when you really mean the whole node.
+
+```html
+<!-- card.jay-html (your template) -->
+<div class="ds-card">
+  <h3 class="ds-card__heading">{heading}</h3>
+  <p class="ds-card__body" jay-content>{body}</p>
+  <img class="ds-card__media" jay-content="src alt" src="placeholder.png" alt="" />
+</div>
+```
+
+The consumer flattens this and edits the `<p>` text and the `<img>` `src`/`alt` with no `override` marks;
+`validate` stays clean and `sync` preserves their copy. The `class` on each node is **not** a slot, so it
+still reconciles with your source on every upgrade.
+
+### `jay-content` vs. `override` — which to reach for
+
+- **You (template author)** declare the parts meant to vary with `jay-content`, once, on the source. This
+  is the preferred path for intended variation — it needs no per-page marks and survives your edits.
+- **The designer** uses `override` on their page for an edit you did **not** declare a slot for (an
+  unanticipated tweak they want to keep through `sync`). Prefer giving them a `jay-content` slot over
+  leaving them to `override` the same spot on every instance.
+
+## Design-system element vs. headless component
+
+|                               | Headless component              | Design-system element                |
+| ----------------------------- | ------------------------------- | ------------------------------------ |
+| Ships a `.jay-html` template? | No                              | **Yes**                              |
+| Who writes the markup?        | The project designer            | You (project copies & edits it)      |
+| Import marker                 | `contract=` (+ optional `key=`) | `contract=` **and** `template=`      |
+| Upgrades                      | Automatic (code is imported)    | Via `jay-stack sync` (copy is owned) |
+| Drift-checked / synced        | No                              | Yes                                  |
+
+Both can be server-only or interactive, and both use the same `.jay-contract`. The only additional thing a
+design-system element ships is the template — and the only additional thing the project runs is `sync`.

package/dist/{index-B9vCxAZ1.js → index-l6QVpvnY.js}

@@ -6,8 +6,8 @@ import { getLogger } from "@jay-framework/logger";
 import path__default from "node:path";
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
-import { runLoadParams, scanPlugins, DevSlowlyChangingPhase, slowRenderInstances } from "@jay-framework/stack-server-runtime";
-import { parseJayFile, JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, assignCoordinatesToJayHtml, discoverHeadlessInstances, generateElementHydrateFile, generateServerElementFile } from "@jay-framework/compiler-jay-html";
+import { runLoadParams, scanPlugins, makePassthroughInstanceComponent, DevSlowlyChangingPhase, slowRenderInstances } from "@jay-framework/stack-server-runtime";
+import { parseJayFile, JAY_IMPORT_RESOLVER, assignCoordinatesToJayHtml, discoverHeadlessInstances, generateElementHydrateFile, generateServerElementFile } from "@jay-framework/compiler-jay-html";
 import { normalizeActionEntry, checkValidationErrors, RuntimeMode } from "@jay-framework/compiler-shared";
 import crypto, { createHash } from "node:crypto";
 import * as productionServer from "@jay-framework/production-server";
@@ -276,7 +276,12 @@ async function loadProductionPageParts(route, pageModule, jayHtmlContent, projec
     }
     let headlessCompDef;
     if (headlessImport.structural) {
-      continue;
+      headlessCompDef = makePassthroughInstanceComponent(
+        (headlessImport.contract?.tags ?? []).map((t) => ({
+          name: t.tag,
+          phase: t.phase
+        }))
+      );
     } else {
       const resolvedModulePath = isLocalModule ? modulePath : require$1.resolve(module, { paths: [dirName] });
       const headlessModule = await import(resolvedModulePath);
@@ -323,7 +328,13 @@ async function loadProductionPageParts(route, pageModule, jayHtmlContent, projec
         isLocal: isLocalModule,
         contractName: headlessImport.contractName,
         propNames: headlessImport.contract.props?.map((p) => p.name) ?? [],
-        structural: headlessImport.structural
+        structural: headlessImport.structural,
+        ...headlessImport.structural ? {
+          structuralTags: (headlessImport.contract.tags ?? []).map((t) => ({
+            name: t.tag,
+            phase: t.phase
+          }))
+        } : {}
       });
     }
   }
@@ -332,11 +343,7 @@ async function loadProductionPageParts(route, pageModule, jayHtmlContent, projec
     contract: hi.contract,
     contractPath: hi.contractPath
   }));
-  const jayHtmlForDiscovery = injectHeadfullFSTemplates(
-    jayHtmlContent,
-    dirName,
-    JAY_IMPORT_RESOLVER
-  );
+  const jayHtmlForDiscovery = jayHtmlContent;
   let discoveredInstances = [];
   let forEachInstances = [];
   if (headlessInstanceComponents.length > 0) {
@@ -388,7 +395,7 @@ function buildPagePartsConfig(pageParts, pageServerModule, pageExportName, build
         source: info.isLocal ? "local" : "npm",
         contractName: info.contractName,
         propNames: info.propNames ?? [],
-        ...info.structural ? { structural: true } : {}
+        ...info.structural ? { structural: true, structuralTags: info.structuralTags ?? [] } : {}
       });
     }
   }
@@ -763,8 +770,7 @@ async function compileRouteServerElement(jayHtmlPath, outputPath, projectRoot, t
   const jayHtmlContent = await fs.readFile(jayHtmlPath, "utf-8");
   const sourceDir = path__default.dirname(jayHtmlPath);
   const outputDir = path__default.dirname(outputPath);
-  let jayHtml = injectHeadfullFSTemplates(jayHtmlContent, sourceDir, JAY_IMPORT_RESOLVER);
-  jayHtml = resolveJayHtmlPaths(jayHtml, sourceDir, outputDir);
+  const jayHtml = resolveJayHtmlPaths(jayHtmlContent, sourceDir, outputDir);
   return compileServerElement(
     jayHtml,
     path__default.basename(jayHtmlPath),
@@ -779,8 +785,7 @@ async function compileRouteServerElement(jayHtmlPath, outputPath, projectRoot, t
 async function compileRouteHydrateScript(jayHtmlPath, outputDir, projectRoot, tsConfigFilePath, minify = true) {
   const jayHtmlContent = await fs.readFile(jayHtmlPath, "utf-8");
   const sourceDir = path__default.dirname(jayHtmlPath);
-  let jayHtml = injectHeadfullFSTemplates(jayHtmlContent, sourceDir, JAY_IMPORT_RESOLVER);
-  jayHtml = resolveJayHtmlPaths(jayHtml, sourceDir, outputDir);
+  const jayHtml = resolveJayHtmlPaths(jayHtmlContent, sourceDir, outputDir);
   const jayFile = await parseJayFile(
     jayHtml,
     path__default.basename(jayHtmlPath),