@jay-framework/jay-stack-cli 0.24.5 → 0.24.7

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

@@ -2,7 +2,9 @@
 
 ## Headless Components
 
-Headless components provide data and interactions with no UI. The page or headfull component provides the template.
+`Headless components provide data and interactions with no UI of their own. The page (or a consuming component) provides the template. **Every component a Jay Stack page composes is headless** — imported with `application/jay-headless`.
+
+The page can supply that template two ways: **write the `<jay:X>` body by hand**, or **flatten one the component ships** — a _design-system element_. **Prefer flattening a shipped template** when the component provides one: a component can offer one or more `.jay-html` templates, so add `template=` to the import and run `jay-stack sync` to copy a chosen one into your page, then edit the copy. You get UI that stays consistent across pages and upgrades in one step, with `jay-stack validate` tracking drift from the source and `jay-stack sync` re-flattening it. Hand-author the `<jay:X>` body only when no template is shipped. See [design-system-guide.md](design-system-guide.md) for the full model.
 
 ### Pattern 1: Key-Based Import
 
@@ -37,7 +39,7 @@ Access data and refs with the key prefix:
 </div>
 ```
 
-Key-based imports are only available in **pages** (not in headfull FS components).
+Key-based imports are only available in **pages** (not in shared full-stack components).
 
 **Important:** Do NOT use `<jay:keyName>` for key-based imports. The key is for ViewState access (`{key.field}`), not for inline elements. `<jay:>` tags use the **contract name**, not the key.
 
@@ -139,44 +141,60 @@ props:
     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.
+## Full-Stack Shared Components (Headless)
 
-Each headfull component lives in its own subdirectory under `src/components/` with three files: `.ts`, `.jay-html`, and `.jay-contract`. The production build only discovers server-side component modules from `src/components/` and `src/plugins/`. Placing them inside page directories will work in dev mode but fail in production.
+A shared UI section with its own logic — a site header, a footer, a side nav — is a **headless full-stack
+component**: logic authored with `makeJayStackComponent` against a `.jay-contract`, with its template
+provided by the consuming page. It supports server rendering (slow/fast/interactive phases). Like every
+Jay Stack component, it is imported with `application/jay-headless` — **not** `application/jay-headfull`
+(see [Headfull components are not for Jay Stack](#headfull-components-are-not-for-jay-stack) below).
 
-> **Note:** In Jay (without Jay Stack), headfull components use `makeJayComponent` and do not require a contract. However, `makeJayComponent` components should not be used in Jay Stack because they do not support server rendering.
+Each lives in its own subdirectory under `src/components/` with three files: `.ts`, `.jay-html` (its
+source template), and `.jay-contract`. The production build only discovers server-side component modules
+from `src/components/` and `src/plugins/`. Placing them inside page directories works in dev mode but
+fails in production.
 
 ### Import Declaration
 
+Import it like any coded headless component — `src=` for the logic, `contract=` for the data shape, and
+`template=` so its markup can be flattened into your page:
+
 ```html
 <head>
   <script
-    type="application/jay-headfull"
+    type="application/jay-headless"
     src="../components/shared-header/shared-header"
-    names="SharedHeader"
     contract="../components/shared-header/shared-header.jay-contract"
+    template="../components/shared-header/shared-header.jay-html"
   ></script>
 </head>
 ```
 
 **Attributes:**
 
-- `src` — Path to the component file (must include the filename, not just the directory)
-- `names` — Component name to import
-- `contract` — Path to the component's `.jay-contract` file (required in Jay Stack)
+- `src` — path to the component logic (include the filename, not just the directory)
+- `contract` — path to the component's `.jay-contract` file
+- `template` — path to the component's source `.jay-html`, so `jay-stack sync` can flatten its markup
+  into the region
 
 ### Usage
 
+Place a `<jay:X>` region (the tag is the contract's `name:`) and run `jay-stack sync` to flatten its body:
+
 ```html
-<jay:SharedHeader logoUrl="/logo.png" />
+<jay:SharedHeader ref="header" logoUrl="/logo.png" />
 ```
 
-> **Route params:** Headfull and instance-based headless components do not receive route params directly. To pass a route param, expose it through the page's ViewState and bind it as a prop: `<jay:SideNav activePage="{activePage}" />`. See [routing.md](routing.md) for the full pattern.
+After sync the region carries a flattened, editable copy of the component's template. See
+[design-system-guide.md](design-system-guide.md) for drift, facet-marking, and upgrades.
+
+> **Route params:** instance-based components do not receive route params directly. To pass a route param,
+> expose it through the page's ViewState and bind it as a prop: `<jay:SideNav activePage="{activePage}" />`.
+> See [routing.md](routing.md) for the full pattern.
 
 ### Component Structure
 
-Each headfull component needs three files in its subdirectory under `src/components/`:
+Each shared full-stack component needs three files in its subdirectory under `src/components/`:
 
 **`.jay-contract`** — declares props. Tags are optional (use `tags: []` or omit for structural components):
 
@@ -220,21 +238,72 @@ For a structural component with only props and no data logic, `.withFastRender`
 </html>
 ```
 
+### Headfull components are not for Jay Stack
+
+`application/jay-headfull` is the **lower-level Jay** component model: logic bundled with its _own_ template
+via `makeJayComponent`, imported with `src=` + `names=` and **no** `contract=`. It has no server rendering,
+so **it is never used directly in a Jay Stack page**. A `jay-headfull` import that carries a `contract=`
+attribute is a **hard build error** (DL#196) — declare the component with `application/jay-headless` and
+flatten it into a `<jay:X>` region instead. Reach for `makeJayComponent` / headfull only in standalone,
+client-only Jay apps, never in Jay Stack.
+
+## Customizing Component Markup — flatten, then edit
+
+To reuse a component but tweak **this one instance** — a label, an image, whether a paragraph appears, a
+container's children — you **flatten** (copy) its template into your page and edit the copy. There is no
+`<override>` tag; you edit real markup and mark the parts you own.
+
+Give the import a `template=` provenance marker, place the region, and run `jay-stack sync` to fill it:
+
+```html
+<head>
+  <script
+    type="application/jay-headless"
+    contract="./components/pricing-card/pricing-card.jay-contract"
+    template="./components/pricing-card/pricing-card.jay-html"
+  ></script>
+</head>
+<body>
+  <!-- after `jay-stack sync` fills the body, edit it freely -->
+  <jay:pricing-card ref="hero">
+    <button class="cta">Start free trial</button>
+    <!-- text rewritten; mark the facet you own so sync keeps it -->
+  </jay:pricing-card>
+</body>
+```
+
+- **Replace content:** rewrite the element's text/children in the copy; mark the element `override="children"`.
+- **Change an attribute:** edit it; mark `override="<attr>"` (e.g. `override="src"`). Others reconcile.
+- **Change one style property:** edit it; mark `override="style.<prop>"`. Other props reconcile.
+- **Remove an element:** delete it and mark the parent `override="children"` (else `sync` restores it).
+- **Own a whole node:** mark it with a bare `override`.
+
+`{binding}` expressions inside the region resolve against the **component's own** contract, exactly as its
+source template does. `jay-stack validate` reports any unmarked edit as drift, and `jay-stack sync`
+re-flattens from the current source while preserving your marked facets.
+
+**See [design-system-guide.md](design-system-guide.md)** for the full model: creating design-system
+elements, reading drift warnings, the complete facet-marking vocabulary (markup `override` + CSS
+`jay:override`), and upgrading with `sync`.
+
 ## Nesting Components
 
-### Headfull Inside Headfull
+Components nest by importing other headless components in their own `<head>` and composing them in their
+template.
 
-A layout component imports a header component:
+### A shared component composing another shared component
+
+A layout component flattens a header component:
 
 ```html
 <!-- layout/layout.jay-html -->
 <html>
   <head>
     <script
-      type="application/jay-headfull"
+      type="application/jay-headless"
       src="../header/header"
       contract="../header/header.jay-contract"
-      names="header"
+      template="../header/header.jay-html"
     ></script>
     <script type="application/jay-data">
       data:
@@ -243,14 +312,14 @@ A layout component imports a header component:
   </head>
   <body>
     <div class="layout">
-      <jay:header logoUrl="/logo.png" />
+      <jay:header ref="header" logoUrl="/logo.png" />
       <aside>{sidebarLabel}</aside>
     </div>
   </body>
 </html>
 ```
 
-### Headless Inside Headfull
+### A shared component using a plugin widget
 
 A header component uses a headless plugin widget:
 
@@ -275,19 +344,20 @@ A header component uses a headless plugin widget:
 </html>
 ```
 
-Nesting depth is unlimited. Circular imports are detected as errors. Key-based headless imports (`key="..."`) are not allowed inside headfull FS components — use instance-based imports instead.
+Nesting depth is unlimited. Circular imports are detected as errors. Key-based headless imports
+(`key="..."`) are only allowed in pages — inside a shared component use instance-based (`<jay:X>`) imports.
 
 ## Nesting Rules
 
-| Parent component | Can import headfull FS? | Can import headless (instance)? | Can import keyed headless? |
-| ---------------- | ----------------------- | ------------------------------- | -------------------------- |
-| **Page**         | Yes                     | Yes                             | Yes                        |
-| **Headfull FS**  | Yes (recursive)         | Yes (in its own head)           | No                         |
-| **Headless**     | No (no template)        | No (no template)                | No (no template)           |
+| Parent component            | Can compose full-stack components? | Can import instance headless? | Can import keyed headless? |
+| --------------------------- | ---------------------------------- | ----------------------------- | -------------------------- |
+| **Page**                    | Yes                                | Yes                           | Yes                        |
+| **Full-stack component**    | Yes (recursive)                    | Yes (in its own head)         | No                         |
+| **Keyed / plugin headless** | No (consumer owns the template)    | No                            | No                         |
 
 ## Complete Example
 
-A homepage with key-based, instance-based, and headfull components:
+A homepage with key-based, instance-based, and shared full-stack components — all headless:
 
 ```html
 <html>
@@ -304,10 +374,10 @@ A homepage with key-based, instance-based, and headfull components:
       contract="product-widget"
     ></script>
     <script
-      type="application/jay-headfull"
+      type="application/jay-headless"
       src="../components/shared-header/shared-header"
-      names="SharedHeader"
       contract="../components/shared-header/shared-header.jay-contract"
+      template="../components/shared-header/shared-header.jay-html"
     ></script>
     <script type="application/jay-data" contract="./page.jay-contract"></script>
     <style>
@@ -323,7 +393,7 @@ A homepage with key-based, instance-based, and headfull components:
     </style>
   </head>
   <body>
-    <jay:SharedHeader logoUrl="/logo.png" />
+    <jay:SharedHeader ref="header" logoUrl="/logo.png" />
     <h1>Homepage</h1>
 
     <!-- Key-based: mood tracker -->

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

@@ -19,6 +19,15 @@ Add `<style>` blocks in `<head>`:
 </head>
 ```
 
+## Styling a design-system region (`@scope` + `:scope`)
+
+CSS for a `<jay:X>` **design-system element** (a region with `template=` provenance) is not written as plain
+page rules — it lives in an `@scope (.<ref>)` block, and the component's own root rule must target `:scope`,
+not its block class (inside `@scope`, a class selector matches descendants of the scope root only). This has
+its own rules and is covered in full in
+[design-system-guide.md → The shape of a region's CSS](design-system-guide.md#the-shape-of-a-regions-css).
+The plain-`<style>` patterns on this page apply to ordinary page markup.
+
 ## External Stylesheets
 
 Link external CSS files:
@@ -95,3 +104,63 @@ Mix static, dynamic, and conditional classes:
 - `{condition ? classA : classB}` switches between two classes
 - `{!condition ? class}` uses negation
 - Multiple bindings can be combined in one `class` attribute
+
+## Viewport Height & Google Search Console
+
+Googlebot's Web Rendering Service does **not** render at a normal phone height. To capture lazy-loaded and
+below-the-fold content in one pass, it renders the page once into a **very tall viewport**
+(~9,000–12,000px). Any element sized to a fraction of viewport height resolves against that tall value:
+
+```css
+.hero {
+  min-height: 100vh;
+} /* phone: ~800px.  Googlebot: ~12,000px. */
+```
+
+On a **top-level container** (`<html>`/`<body>`/`<main>`, or a direct child of `<body>`/`<main>`) that
+makes the section enormous in the crawler's render — distorting Search Console screenshots and mobile
+usability / layout signals. The `design-viewport-height` validator flags unbounded viewport-height units
+(`vh`, `svh`, `lvh`, `dvh`, `vmax`) on these containers.
+
+**Swapping the unit is NOT a fix.** `svh`/`lvh`/`dvh` all resolve against the same tall viewport under
+Googlebot (there is no browser chrome to differentiate them), so `vh → dvh` changes nothing here.
+
+Choose the fix by what the container holds:
+
+- **Text-heavy section** — don't force full-viewport height at all. Let content determine height, or chain
+  from a bounded ancestor:
+
+  ```css
+  main {
+    min-height: 100%;
+  } /* inherits a real height, not the viewport */
+  ```
+
+- **Hero / visual section** that genuinely wants a full-screen feel — cap it, and scope the viewport height
+  to a real screen via a media query so it never applies to Googlebot's tall canvas:
+
+  ```css
+  .hero {
+    max-height: 900px;
+  }
+  @media (min-width: 480px) {
+    .hero {
+      min-height: 100vh;
+    }
+  }
+  ```
+
+  A `max-height` in an **absolute** unit (`px`/`rem`, or `%` of a bounded ancestor) clears the warning. A
+  `max-height` that also uses a viewport unit (`max-height: 100vh`) does **not** — it caps against the same
+  ~12,000px viewport.
+
+- **Overlay / modal / drawer** that is out of flow (`position: fixed/absolute/sticky`) — this is safe (it
+  doesn't expand the document canvas) and the validator already ignores it. If a false positive slips
+  through, suppress it per-page (see `validation-guide.md`):
+
+  ```html
+  <script type="application/jay-validations">
+    design-system:
+      allow-viewport-height: true
+  </script>
+  ```

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

@@ -14,24 +14,33 @@ The design tool can freely read and rewrite jay-html files as long as contract b
 
 Entry point at `src/pages/`. Can import all component types.
 
-### Headfull FS
+### Full-stack component (headless)
 
-Reusable component with its own template + contract + three-phase rendering (slow/fast/interactive). Must live in `src/components/` (not inside page directories) so the production build can discover and compile them. Can nest other headfull FS and instance headless in its own `<head>`. Cannot use keyed headless.
+Reusable component with logic + contract + three-phase rendering (slow/fast/interactive), authored with
+`makeJayStackComponent`. It has **no template of its own** — the consuming page flattens its template into a
+`<jay:X>` region. Must live in `src/components/` (not inside page directories) so the production build can
+discover and compile them. Can nest other full-stack components and instance headless in its own `<head>`.
+Cannot use keyed headless. (Imported with `application/jay-headless`, not `application/jay-headfull` — see
+[jay-html-components.md](jay-html-components.md#headfull-components-are-not-for-jay-stack).)
 
 ### Headless
 
-Plugin-provided logic component. No template — the page or headfull component provides the UI via inline template (`<jay:xxx>`). Two import patterns:
+Plugin-provided logic component. No template of its own — the page or consuming component provides the UI via inline template (`<jay:xxx>`). Two import patterns:
 
 - **Key-based** — one instance per page, data merged under a key prefix (`{key.tag}`)
 - **Instance-based** — multiple instances with props, each gets its own inline template
 
+**Prefer a design system:** if the component ships a `.jay-html` template, flatten it (`template=` +
+`jay-stack sync`) instead of hand-writing the inline body — see
+[design-system-guide.md](design-system-guide.md).
+
 ## Nesting Rules
 
-| Parent component | Can import headfull FS? | Can import headless (instance)? | Can import keyed headless? |
-| ---------------- | ----------------------- | ------------------------------- | -------------------------- |
-| **Page**         | Yes                     | Yes                             | Yes                        |
-| **Headfull FS**  | Yes (recursive)         | Yes (in its own head)           | No                         |
-| **Headless**     | No (no template)        | No (no template)                | No (no template)           |
+| Parent component            | Can compose full-stack components? | Can import headless (instance)? | Can import keyed headless? |
+| --------------------------- | ---------------------------------- | ------------------------------- | -------------------------- |
+| **Page**                    | Yes                                | Yes                             | Yes                        |
+| **Full-stack component**    | Yes (recursive)                    | Yes (in its own head)           | No                         |
+| **Keyed / plugin headless** | No (consumer owns the template)    | No                              | No                         |
 
 ## Validation
 
@@ -39,8 +48,8 @@ After creating or editing jay-html files, run `jay-stack validate` to check for
 
 ## Reference
 
-| File                                                       | Topic                                                                  |
-| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
-| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: file structure, data binding, conditions, loops, refs |
-| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), headfull FS, nesting       |
-| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic styles, class bindings              |
+| File                                                       | Topic                                                                      |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: file structure, data binding, conditions, loops, refs     |
+| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), full-stack components, nesting |
+| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic styles, class bindings                  |

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

@@ -18,8 +18,8 @@ A `.jay-html` file is standard HTML with jay-specific extensions.
     <!-- Headless component imports -->
     <script type="application/jay-headless" plugin="..." contract="..." key="..."></script>
 
-    <!-- Headfull component imports -->
-    <script type="application/jay-headfull" src="..." names="..." contract="..."></script>
+    <!-- Shared full-stack component imports (headless) -->
+    <script type="application/jay-headless" src="..." contract="..." template="..."></script>
 
     <!-- SEO head tags (support {binding} syntax) -->
     <title>{productPage.name} | My Store</title>
@@ -182,7 +182,7 @@ Available at all render phases (slow, fast, interactive). Use in text bindings,
 <a if="jay.url.path ^= '/docs'" class="docs-active">Docs</a>
 ```
 
-`jay.` bindings are available in **page templates only** — headfull components receive this data via props.
+`jay.` bindings are available in **page templates only** — shared full-stack components receive this data via props.
 
 ### Choosing the Right Condition Type
 

package/agent-kit-template/designer/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/designer/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:
 
@@ -146,7 +146,7 @@ Multiple components on the same page can each declare params. The route director
 
 ### Passing Route Params to Nested Components
 
-Route params flow automatically to keyed headless components that declare them as `params` in their contract. Instance-based headless components and headfull components do not receive route params directly — they receive props from the template.
+Route params flow automatically to keyed headless components that declare them as `params` in their contract. Instance-based headless components and shared full-stack components do not receive route params directly — they receive props from the template.
 
 #### Direct binding with `jay.params` (no page.ts needed)
 

package/agent-kit-template/designer/validation-guide.md

@@ -15,12 +15,12 @@
 The validator processes each `.jay-html` file with:
 
 - **Page template** — your HTML, bindings, and inline styles
-- **Headfull component content** — `<jay:SiteHeader />`, `<jay:DocsSidebar />` etc. are expanded into the page before validation
+- **Full-stack component content** — `<jay:SiteHeader />`, `<jay:DocsSidebar />` etc. are flattened into the page before validation
 - **Headless component tags** — `<jay:product-widget>` inline templates are visible
 - **Linked CSS files** — `<link rel="stylesheet" href="...">` referenced from `<head>` are read and validated (e.g., for CSS `@import` of external URLs)
 - **Inline `<style>` blocks** — CSS in `<head>` is parsed for rule violations
 
-So a warning about an `<img>` might come from a headfull component's template, not your page template. A CSS warning might come from a linked stylesheet.
+So a warning about an `<img>` might come from a full-stack component's template, not your page template. A CSS warning might come from a linked stylesheet.
 
 ## Errors vs Warnings
 
@@ -37,9 +37,9 @@ Each warning has:
 
 ### Acting on Warnings
 
-1. **Check if the element is in your template** — search your `.jay-html` file for the element. If it's not there, it comes from a headfull component.
+1. **Check if the element is in your template** — search your `.jay-html` file for the element. If it's not there, it comes from a full-stack component.
 
-2. **For headfull component warnings** — fix them in the component's `.jay-html` file (e.g., `src/components/site-header/site-header.jay-html`), not in the page that imports it.
+2. **For full-stack component warnings** — fix them in the component's `.jay-html` file (e.g., `src/components/site-header/site-header.jay-html`), not in the page that imports it.
 
 3. **For dynamic content warnings** — if the warning is about content inside a `{binding}` (like `{post.content}`), you can't fix it in the template. The content is generated at render time. These are usually false positives.
 
@@ -49,7 +49,7 @@ Each warning has:
 
 ### "Image without loading attribute" from a component
 
-The image is in a headfull component (e.g., sidebar icons). Fix it in the component's `.jay-html`, not the page.
+The image is in a full-stack component (e.g., sidebar icons). Fix it in the component's `.jay-html`, not the page.
 
 ### "Heading level skipped" with dynamic content
 
@@ -102,6 +102,32 @@ Multiple plugins can be configured in one tag:
     no-lcp-image: true
   design-system:
     allow-undefined-vars: true
+    allow-viewport-height: true
+</script>
+```
+
+Design-system suppression keys include `allow-undefined-vars`, `allow-viewport-height` (top-level
+viewport-height containers — see `jay-html-styling.md`), `allow-custom-breakpoints`,
+`allow-no-reduced-motion`, and `allow-font-no-fallback`.
+
+### Prefer-design-system-elements warnings (jay-stack namespace)
+
+The core `jay-stack validate` emits four warnings that nudge you to reuse UI through design-system elements
+(see `design-system-guide.md`). Suppress the legitimate case:
+
+| Rule                          | How to suppress                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `REGION-NOT-LINKED`           | `jay-validations="REGION-NOT-LINKED"` on the `application/jay-headless` import, or `jay-stack: allow-inline-region: [Contract]` |
+| `REGION-OVERRIDE-NON-CONTENT` | `jay-validations="REGION-OVERRIDE-NON-CONTENT"` on the import                                                                   |
+| `COMPONENT-NO-TEMPLATE`       | `jay-stack: allow-no-template: [Contract]`                                                                                      |
+| `NO-DESIGN-SYSTEM`            | `jay-stack: allow-no-design-system: true`                                                                                       |
+
+```html
+<script type="application/jay-validations">
+  jay-stack:
+    allow-inline-region: [Card]
+    allow-no-template: [MetricsProvider]
+    allow-no-design-system: true
 </script>
 ```
 

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

@@ -4,7 +4,9 @@ This folder contains guides for building jay-stack projects: project configurati
 
 ## What Does the Developer Role Do?
 
-The developer sets up the project, configures plugins, creates page-level components (`page.ts`), defines page contracts (`page.jay-contract`), and wires everything together. This is distinct from the designer role (creates jay-html UI) and the plugin role (creates reusable headless components).
+The developer sets up the project, configures plugins, creates page-level components (`page.ts`), defines page contracts (`page.jay-contract`), authors shared full-stack components (headless) for reusable UI sections like headers and footers, and wires everything together. This is distinct from the designer role (creates jay-html UI) and the plugin role (creates reusable headless components).
+
+**Shared components are headless** — logic (`makeJayStackComponent`) + a `.jay-contract`, placed in `src/components/<name>/`. **Prefer shipping each with a `.jay-html` template** (one or more) so pages flatten it as a design-system element (`template=` + `jay-stack sync`) instead of hand-writing the UI. See [design-system-guide.md](../designer/design-system-guide.md) for the model and [component-structure.md](../plugin/component-structure.md) for the builder API.
 
 ## Workflow
 
@@ -12,24 +14,27 @@ The developer sets up the project, configures plugins, creates page-level compon
 2. **Define routes** — create page directories under `src/pages/`
 3. **Create page contracts** — `page.jay-contract` for page-level data
 4. **Create page components** — `page.ts` with `makeJayStackComponent`
-5. **Configure services** — `src/init.ts` for project-level services
-6. **Validate** — `jay-stack validate`
-7. **Test** — `jay-stack dev --test-mode`
+5. **Author shared components** (when UI repeats across pages) — headless `makeJayStackComponent` + `.jay-contract` in `src/components/`, preferably shipping a `.jay-html` template for pages to flatten
+6. **Configure services** — `src/init.ts` for project-level services
+7. **Validate** — `jay-stack validate`
+8. **Test** — `jay-stack dev --test-mode`
 
 ## Guides
 
-| File                                              | Topic                                                                |
-| ------------------------------------------------- | -------------------------------------------------------------------- |
-| [project-structure.md](project-structure.md)      | Directory layout, configuration files                                |
-| [routing.md](routing.md)                          | Directory-based routing, dynamic routes                              |
-| [configuration.md](configuration.md)              | .jay file, plugin config, init.ts                                    |
-| [page-contracts.md](page-contracts.md)            | Page-level contracts (page.jay-contract)                             |
-| [Contract Authoring Guide](../contracts/GUIDE.md) | Writing contracts: syntax, page/component/linked contracts, examples |
-| [page-components.md](page-components.md)          | page.ts: makeJayStackComponent for pages                             |
-| [component-state.md](component-state.md)          | createSignal, createMemo, createEffect, createDerivedArray           |
-| [component-refs.md](component-refs.md)            | Refs, collection refs, element types                                 |
-| [component-data.md](component-data.md)            | Immutable data, JSON Patch, patching                                 |
-| [render-results.md](render-results.md)            | phaseOutput, RenderPipeline, errors, redirects                       |
-| [seo-guide.md](seo-guide.md)                      | SEO head tags: title, meta, OG, canonical via phaseOutput            |
-| [cli-commands.md](cli-commands.md)                | CLI commands: setup, validate, dev, agent-kit                        |
-| `../references/<plugin>/`                         | Plugin reference data                                                |
+| File                                                         | Topic                                                                                |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| [project-structure.md](project-structure.md)                 | Directory layout, configuration files                                                |
+| [routing.md](routing.md)                                     | Directory-based routing, dynamic routes                                              |
+| [configuration.md](configuration.md)                         | .jay file, plugin config, init.ts                                                    |
+| [page-contracts.md](page-contracts.md)                       | Page-level contracts (page.jay-contract)                                             |
+| [Contract Authoring Guide](../contracts/GUIDE.md)            | Writing contracts: syntax, page/component/linked contracts, examples                 |
+| [page-components.md](page-components.md)                     | page.ts: makeJayStackComponent for pages                                             |
+| [design-system-guide.md](../designer/design-system-guide.md) | Shared components as design-system elements: ship a template, flatten, drift, `sync` |
+| [component-structure.md](../plugin/component-structure.md)   | Builder API for shared/headless components: `.withProps()`, phases, render results   |
+| [component-state.md](component-state.md)                     | createSignal, createMemo, createEffect, createDerivedArray                           |
+| [component-refs.md](component-refs.md)                       | Refs, collection refs, element types                                                 |
+| [component-data.md](component-data.md)                       | Immutable data, JSON Patch, patching                                                 |
+| [render-results.md](render-results.md)                       | phaseOutput, RenderPipeline, errors, redirects                                       |
+| [seo-guide.md](seo-guide.md)                                 | SEO head tags: title, meta, OG, canonical via phaseOutput                            |
+| [cli-commands.md](cli-commands.md)                           | CLI commands: setup, validate, dev, agent-kit                                        |
+| `../references/<plugin>/`                                    | Plugin reference data                                                                |

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`