@adia-ai/adia-ui-forge 0.8.40 → 0.8.42

package/skills/primitive-authoring/references/yaml-contract.md

@@ -2,7 +2,7 @@
 
 Authoritative source-of-truth fields for `packages/web-components/components/<name>/<name>.yaml` and `packages/web-modules/<cluster>/<name>/<name>.yaml`. The build pipeline (`scripts/build/components.mjs`) reads these yamls + emits sidecar JSON (`<name>.a2ui.json`) that feeds the docs site, the A2UI runtime registries, and consumer harnesses.
 
-This is the authoritative schema reference for the authoring lane. The full validator + JSON Schema lives at `scripts/schemas/component.yaml.schema.json` (referenced by every yaml's `$schema:` key). This file covers the human-facing contract: what each field means, when to use which value, and the canonical shape of a complete yaml.
+This is the authoritative schema reference for the authoring lane. The JSON Schema lives at `scripts/schemas/component.yaml.schema.json` (referenced by every yaml's `$schema:` key). Amended 2026-08-16 per ADR-0057: that schema is the documented contract + IDE aid, not a run validator — no build step evaluates it against the yamls. The build-time checks that DO exist are hand-written throws in `compileComponent()` (`scripts/build/components.mjs`): a missing `component:` field, a `component: Surface` (reserved — the A2UI v1.0 implicit root container, SPEC REQ-011/gh#1353), a `status:` value outside the five-value enum (see §`status:` below), a missing `category:` field OR a `category:` value outside the twelve-value enum (see §`category:` below, ADR-0065), and malformed `a2ui.allowedParents`/`a2ui.allowedChildren` composition constraints (see §composition constraints below — plus a full-build cross-reference check that every referenced name is a real `component:` in the catalog). Every other schema constraint (`required: [name, tag, component, description]`, `minLength`, …) is IDE-visible only. This file covers the human-facing contract: what each field means, when to use which value, and the canonical shape of a complete yaml.
 
 ---
 
@@ -14,7 +14,7 @@ $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIMyComponent          # Class name (PascalCase, UI-prefixed)
 tag: my-component-ui         # Custom element tag (kebab-case, -ui-suffixed)
 component: MyComponent       # Short component name (no UI- prefix)
-category: form               # Category — form / display / layout / chrome / a2ui / shell
+category: form               # Category — see §category field below (ADR-0065, twelve-value enum)
 version: 1                   # Schema version (always 1 for now)
 status: stable               # Stability tier — see §status field below
 description: >-
@@ -26,13 +26,104 @@ props:
 events:
   …                          # Event schemas — fired by the component
 slots:
-  …                          # Named slot semantics
+  …                          # Consumer-fillable light-DOM insertion points — see §slots vs parts below
+parts:
+  …                          # Template-owned anatomy — see §slots vs parts below
 css-vars:
   …                          # CSS custom properties the component reads
 ```
 
 ---
 
+## `slots:` vs `parts:` — consumer-fillable vs template-owned anatomy (ADR-0067)
+
+**Decision rule**: does an author (a human, or an LLM generating an A2UI
+document) ever place their OWN content at this named span? If yes — even
+with a stamped fallback when nothing is supplied — it's `slots:`. If the
+component's own `render()`/template ALWAYS stamps it itself, from a prop or
+attribute, and no author-supplied content is ever accepted there — it's
+`parts:`. **Check element source, never the description prose alone**
+(AGENTS.md: source wins) — a name that *sounds* internal
+(`actions`, `text`, `leading`) can still be a real insertion point in a
+given component; `table-toolbar.yaml`'s `actions` slot LOOKS stamped by
+name but its `class.js` explicitly absorbs pre-existing `[slot="actions"]`
+children (a real, author-fillable insertion point) — the opposite of
+`check.yaml`'s `box`, which `static template = () => html\`<span
+slot="box"></span>\`` stamps unconditionally every render.
+
+Both keys share the identical `Slot` schema shape (`description:` required,
+`fallback:` optional) — the only difference is which key an entry lives
+under. `scripts/build/components.mjs` forwards both verbatim onto the
+sidecar (`x-adiaui.slots` / `x-adiaui.parts`) with no other processing.
+
+**Why the split matters — three real consumers read `slots:` and present
+every entry as fillable, with no code-level filtering for anything under
+`parts:`:**
+
+- `packages/gen-ui/engine/retrieval/component-entry.js`'s
+  `serializeReference()` — feeds the LLM-facing `reference`-detail catalog
+  entry (MCP tools, `getComponentAPI()`).
+- `packages/gen-ui/engine/compose/strategies/monolithic/_shared.js`'s
+  `adaptV09Component()` — feeds the monolithic engine's prompt catalog.
+- `scripts/docs/anatomy-sweep.mjs`'s `genSlots()` — renders the docs-site
+  "slots" anatomy section.
+
+A `parts:` entry never reaches any of the three above — moving template-owned
+anatomy there is a structural fix, not a naming convention alone. An
+existing entry under `slots:` that's actually template-owned (e.g. a
+component predating this ADR) is a real bug: it advertises to an LLM that
+filling it does something, when the component's own template replaces
+whatever's there on the next render — the exact gh#284 destructive-replace
+shape, applied to a *documented* slot instead of an undocumented one.
+
+`scripts/dev/audit-slot-vocab-vs-css.mjs` (the yaml-vs-CSS `[slot="X"]`
+cross-check) reads BOTH `slots:` and `parts:` — a `parts:` entry is still a
+real `slot="X"` DOM attribute the component's own CSS may position, just
+never author-fillable, so it stays in that audit's declared-vocabulary set.
+`scripts/dev/audit-template-child-conflict.mjs` (the gh#284 container-shape
+check) is unaffected either way — it only checks for a slot literally named
+`default`.
+
+---
+
+## `a2ui.allowedParents:` / `a2ui.allowedChildren:` — composition constraints (SPEC REQ-011, gh#1353)
+
+Optional keys inside the `a2ui:` block, alongside `rules:`. Each is a
+non-empty list of catalog `component:` names (NOT tags) naming the direct
+parents this component may sit under / the direct children it may contain.
+The reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
+only in `allowedParents` and means "may sit at the surface root". **Omitted
+means unconstrained** — never write an empty list (that would mean "allowed
+nowhere"; the build refuses it).
+
+```yaml
+a2ui:
+  allowedParents:
+    - Accordion        # AccordionItem only makes sense inside an Accordion
+  rules:
+    - …
+```
+
+**Authoring rule — verify against element source, exactly like the
+`slots:`/`parts:` decision above.** Declare a constraint only when the
+component's own source enforces or assumes it (e.g. `stepper.class.js`
+queries `stepper-item-ui`; `segmented.class.js` warns on non-`segment-ui`
+children). A parent that adopts items through wrappers (menu.class.js's
+deliberate descendant query) must NOT constrain — a declared constraint
+stricter than the source is a defect, not documentation.
+
+Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
+referenced name against the full catalog on a full build, and forwards the
+lists onto `x-adiaui` → `catalog-a2ui_0_9.json`.
+`scripts/build/derive-genui-catalog.mjs` then translates them into the
+canonical v1.0 key space (yaml `Segmented` → catalog `SegmentedControl`) on
+`base.json`/`adia-pack.json`, where the vendored `@genui/core` validator
+enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier yamls
+(web-modules) carry constraints as dialect-catalog metadata only — modules
+have no v1.0 sidecar.
+
+---
+
 ## `status:` field — stability tier
 
 **Required** for all new components. Existing components default to `stable` if unset, but new yamls MUST set this explicitly.
@@ -45,6 +136,8 @@ css-vars:
 | `deprecated` | Has a replacement; check the component's `related:` section. Docs site shows a `danger`-variant badge labeled "deprecated". |
 | `early-access` | Customer-preview tier; release notes gate. Docs site shows an `info`-variant badge labeled "early access". |
 
+**Ratified, closed enum — compiler-enforced at build time, mirrored in the schema (ADR-0057, ratified 2026-08-15).** The five values above are the whole vocabulary; `draft` is NOT a value (the one `draft` in the estate, `embed-shell.yaml`, was corrected to `experimental` when the enum went live — a sixth value on a single occurrence is data-entry drift, not a vocabulary gap). Enforcement: `scripts/build/components.mjs:105` holds `STATUS_VALUES` and `compileComponent()` (`components.mjs:258-260`) throws on any out-of-enum `status:` at the same place it throws on a missing `component:` — so `npm run verify:components` (`node scripts/build/components.mjs --verify`, a member of the `npm run check` aggregate) hard-fails the yaml with a file-and-value error. An invalid status no longer merely skips a docs badge; it stops the build. `scripts/schemas/component.yaml.schema.json:23-27` declares the same enum (default `stable`) for the `$schema:` IDE contract, but no validator runs that file — the hand-synced constant in `components.mjs` is the live gate. `status` is orthogonal to the ADR-0050 L0–L4 tier ladder (tier = what a component is composed of; status = how much to trust its contract today), and nothing in `packages/gen-ui/engine/retrieval/` filters or ranks on it. Source: ADR-0057.
+
 **Guidance**:
 
 - Set `beta` or `experimental` at FIRST AUTHORING for any component that's not in the stable API contract yet. Don't default to `stable` and bump later — the badge is consumer-facing, and stable→beta is a downgrade signal.
@@ -57,6 +150,106 @@ css-vars:
 
 ---
 
+## `category:` field — functional grouping
+
+**Required.** Every yaml sets this; `scripts/build/components.mjs` forwards it verbatim onto the sidecar as `x-adiaui.category`, and `packages/gen-ui/engine/retrieval/catalog.js` reads it from there for every YAML-backed component — no second, hand-maintained category list for anything with a yaml SoT. `catalog.js` does still carry one small, DELIBERATE exception: a 3-entry `PSEUDO_TYPE_CATEGORY` map (`section`/`header`/`footer` → `card-child`) for `@adia-ai/a2ui` registry pseudo-types that have no yaml SoT at all (v0.9 composition slot-children, not real primitives) — nothing to derive from, so this one small map stays hand-maintained by design, not drift.
+
+| Value | When to use |
+| --- | --- |
+| `action` | A standalone, click-to-fire trigger (`button-ui`, `toggle-scheme-ui`). |
+| `agent` | AI/agent-facing surfaces — chat, trace, tool output, tabular/chart data views (`chat-thread-ui`, `agent-trace-ui`, `table-ui`, `chart-ui`, `embed-ui`). |
+| `container` | A chrome/wrapping surface that holds other content (`card-ui`, `modal-ui`, `drawer-ui`, `menu-ui`, `command-ui`). |
+| `data` | Structured/tabular data display, not a full agent surface (`tree-ui`, `heatmap-ui`). |
+| `display` | Passive content rendering — text, media, status glyphs (`text-ui`, `icon-ui`, `badge-ui`, `avatar-ui`, `link-ui`, `mark-ui`, `richtext-ui` — a non-editable renderer, not a form field). |
+| `feedback` | Status/notification/progress communication (`spinner-ui`, `inline-message-ui`, `progress-ui`, `progress-row-ui`, `step-progress-ui`, `feed-ui`, `feed-item-ui`). |
+| `form` | Data-entry composite/field-level components, not raw bindable controls (`field-ui`, `fields-ui`, `rating-ui`, `toggle-option-ui`). |
+| `input` | Bindable form controls (`input-ui`, `select-ui`, `check-ui`, `switch-ui`, `textarea-ui`, `radio-ui`). |
+| `layout` | Pure structural/spatial primitives — no content semantics of their own (`row-ui`, `col-ui`, `grid-ui`, `stack-ui`, `list-ui`). |
+| `navigation` | Wayfinding/switcher controls, including a switcher family's child items (`breadcrumb-ui`, `pagination-ui`, `menu-item-ui`, `segmented-ui`/`segment-ui`, `tabs-ui`/`tab-ui`, `stepper-ui`/`stepper-item-ui`). `toggle-group-ui` is `navigation` too, but its child `toggle-option-ui` is `form` (a wrapper/item split, like `menu-ui`/`menu-item-ui` — not a same-category pair). |
+| `shells` | Page-level app-shell composites (`simple-shell-ui` and its siblings). |
+| `utility` | Non-visual/accessibility helpers (`skip-nav-ui`, `visually-hidden-ui`). |
+
+**Ratified, closed enum — compiler-enforced at build time, mirrored in the schema (ADR-0065).** These twelve values are the whole vocabulary; the census that ratified them found 18 free-form values in live use (typos like `forms`/`data-display`, one-off singletons, and three named misclassifications) — all folded or corrected onto this set as part of the same change. Enforcement: `scripts/build/components.mjs` holds `CATEGORY_VALUES` and `compileComponent()` throws on a MISSING `category:` field (unlike `status:`, `category:` is required, not defaulted) as well as on any out-of-enum value, the same place and severity as the `status:` check above — so `npm run verify:components` hard-fails an invalid OR absent category. `scripts/schemas/component.yaml.schema.json`'s `category` enum mirrors this list for the `$schema:` IDE contract; the hand-synced constant in `components.mjs` is the live gate, same relationship as `status`. Source: ADR-0065.
+
+**A sibling family (a wrapper + its child items, e.g. `tabs-ui`/`tab-ui`) is not required to share one category by default** — `menu-ui` (`container`) + `menu-item-ui` (`navigation`) is a deliberate, working split. Where a family's sibling values disagreed with no evident rationale, ADR-0065 unified them; new families should pick per-component, not assume unification is required.
+
+**Sidecar emission**: `x-adiaui.category` field in `<name>.a2ui.json`. `packages/gen-ui/engine/retrieval/catalog.js`'s `buildCatalog()` reads this directly per entry — no separate registration step.
+
+---
+
+## Semantic color-family axis — two role-classes, two names (ADR-0044, ADR-0064)
+
+Every component carries at most one STYLE axis and one FAMILY axis (the
+semantic color family: `default | info | success | warning | danger`,
+`+primary` where the role-class already carries brand emphasis), and every
+enum value belongs to exactly one axis. The family axis's ATTRIBUTE NAME is
+decided by role-class — never one universal name (a same-name meaning-flip
+is a silent-failure migration and poisons the trained corpus, per ADR-0044
+LLD §3):
+
+- **Role-class A — `variant` is unclaimed:** the family axis is named
+  `variant`. Badge/tag's ratified shape (ADR-0044), plus `rating-ui` and the
+  `variant`-only siblings (inline-message, feed-item, empty-state, menu-item,
+  progress-row).
+- **Role-class B — an existing identity/style axis already claims the
+  selector slot:** the family axis is named `color`. Button's shape
+  (`variant`=style, `color`=family), extended by ADR-0064 to `text-ui`
+  (`variant`=typography role), `chart-ui`/`heatmap-ui` (`type`=kind),
+  `icon-ui` (`weight`=glyph style), `spinner-ui` (`variant`=animation), and
+  `toggle-scheme-ui`. Renames owed by this ruling (follow-on build, gh#1376
+  — not yet landed): `icon-ui[tone]` → `[color]`, `heatmap-ui[colorScheme]`
+  → `[color]`, `spinner-ui[tone]` → `[color]`.
+
+`accent` is RETIRED from the family enum everywhere — ADR-0044 removed it
+from badge/tag/button; ADR-0064 removes it from the seven stragglers
+(text, chart, icon, heatmap, rating, spinner, toggle-scheme) with no
+replacement value. Never mint `accent` in a new enum.
+
+Two ratified non-family exceptions — the name without the semantics:
+
+- `swatch-ui[color]` / `noodles-ui[color]` — an arbitrary CSS color string,
+  not a semantic enum (ADR-0054 §11 exemption, unchanged).
+- `spinner-ui[color]` (post-rename) — a closed contrast-mode enum
+  (`current | subtle | inverse`), NOT the family vocabulary; never assume it
+  accepts `info`/`success`/`warning`/`danger` by analogy.
+
+---
+
+## Catalog tiers — L0–L4, `origin`, and the promotion rule (ADR-0050, ADR-0066)
+
+ADR-0050's L0–L4 ladder is the ONLY tier grammar — never mint a second
+manifest format. ADR-0066 refines it three ways:
+
+- **`origin: primitive | module` on every L0 entry** — both YAML source
+  roots (web-components primitives AND web-modules composites) compile into
+  the same `catalog-a2ui_0_9.json` through one shared contract;
+  `derive-catalog-tiers.mjs` stamps which root an entry came from onto
+  `tier-index.json`. A module is legitimately a member of TWO rungs at two
+  grains: its component API (props/events/slots) is L0, its assembled shell
+  composition is L3 — ruled correct, not a modeling defect.
+- **The promotion rule, stated once:** patterns/zettel compositions are the
+  SOLE promotion source, and they enter the ladder at exactly one point —
+  pattern → L1 widget, through `curate-l1-widgets.mjs`'s gates (which writes
+  only `l1-widgets.json`). The higher rungs (L1 → L2 → L3 → L4) are AUTHORED
+  edges — hand-written `tiers/l*-*.json` manifests whose `composes` reference
+  the rung below, reserved/unblocked per ADR-0050's own phasing; a module's
+  L3 membership comes from an authored L3 manifest, never from its yaml
+  (which contributes only the L0 entry + `origin`). There is no
+  patterns↔module edge, primitives and modules never "promote" into each
+  other, and nothing promotes automatically or in reverse — curation is the
+  one-way valve (ADR-0050: "corpus derives from catalogs, never the
+  reverse").
+- **The two pattern-facing outputs stay separate by design:**
+  `site/patterns-index.json` / `pattern-index.md` are a generated,
+  developer-facing index over the FULL pattern/template census, intentionally
+  independent of the L0–L4 machine-validated schema — a different audience,
+  never a convergence gap to "fix".
+
+(`status:` above is orthogonal to the tier ladder — tier = what an entry is
+composed of; status = how much to trust its contract today.)
+
+---
+
 ## `props:` field — prop schemas
 
 Each prop is a top-level key inside `props:`. The full prop schema:
@@ -146,7 +339,7 @@ string-list schema is the exact silent-mismatch shape.
 | --- | --- | --- |
 | `[data-col]` | `display: flex; flex-direction: column; gap: var(--page-grid-gap)` | column layout helper |
 | `[data-row]` | `display: flex; align-items: center; gap: var(--page-grid-gap)` | row layout helper |
-| `[data-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-grid="3"`) | 2- or 3-col grid helper |
+| `[data-layout-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-layout-grid="3"`) | 2- or 3-col grid helper |
 | `[data-actions]` | `display: flex; align-items: center; gap: var(--page-actions-gap)` | action button cluster |
 | `[data-spacer]` | `flex: 1` | flex spacer for pushing content to edges |
 
@@ -160,6 +353,46 @@ string-list schema is the exact silent-mismatch shape.
 
 ---
 
+## `data-msg-*` — exempt component-side config family (gh#1332/#1464, ADR-0060)
+
+`data-msg-required` / `data-msg-pattern` / `data-msg-minlength` /
+`data-msg-maxlength` / `data-msg-min` / `data-msg-max` / `data-msg-bad-input`
+are read directly by form-associated components (`core/form.js`'s shared
+`UIFormElement` validation path, plus `input`, `select`, `tags-input`,
+`code`, `date-range-picker`, `datetime-picker`, and
+`payment-method-form.class.js`) to override a native constraint-violation's
+default message with a consumer-supplied string.
+
+**Disposition: EXEMPT — never declared as a yaml `states:`/`props:` entry.**
+Both yaml surfaces this contract offers are the wrong shape for this family:
+
+- `states:` declares **presence-boolean host state the component itself
+  reflects outward** (idle/loaded/error, this file's own §Reserved section's
+  neighbor pattern) — `data-msg-*` carries no state at all; it is a
+  consumer-authored string the component only ever *reads*, never sets.
+- `props:` would need one string prop per validation-message key, repeated
+  across every one of the 7+ consuming components — but the read path is
+  `core/form.js`'s shared mixin, not any single component's own yaml SoT.
+  Declaring it per-component would multiply one shared mixin contract across
+  every consumer's yaml with no single owning SoT to declare it once — a
+  cross-cutting mixin-contract change, not a per-component yaml edit.
+
+ADR-0060's own boundary discriminator (§Decision 3) already places this
+family outside the trait-tier `data-*` ratification and explicitly routes it
+"to gh#1332's Category A/D triage for its own converge-or-ratify call" — this
+section IS that call. The family stays `data-*`, undeclared in any yaml,
+with its contract documented at the shared source instead: `core/form.js`'s
+own header JSDoc (the mixin all consumers share) and the canonical
+`form-system` pattern doc (`packages/web-components/patterns/form-system/
+form-system.examples.html`, mirrored at `site-a2ui/pages/
+site__patterns__form-system.a2ui.json`) — both already enumerate the full
+family with a worked example. A future architectural pass that wants to
+promote this to a declared per-component contract needs its own ADR (the
+scope is a mixin-wide contract change, not a small-ticket edit); nothing
+here forecloses that, it only records today's call.
+
+---
+
 ## Build pipeline
 
 ```bash
@@ -171,7 +404,7 @@ node scripts/build/components.mjs --verify   # same as above, direct invocation
 The build:
 
 1. Reads every `<name>.yaml` under `packages/web-components/components/` and `packages/web-modules/<cluster>/`
-2. Validates against `scripts/schemas/component.yaml.schema.json`
+2. Hand-checks the source yaml in `compileComponent()` — missing `component:` and out-of-enum `status:` both throw (`components.mjs:255-260`). Amended 2026-08-16 per ADR-0057: it does NOT run `scripts/schemas/component.yaml.schema.json` as a validator (an earlier revision of this list claimed it did); the schema file is documentation + IDE contract only.
 3. Emits `<name>.a2ui.json` (the sidecar) co-located with the yaml + js + css
 4. Emits the `traits/_catalog.json` aggregate
 5. `--verify` mode: re-runs steps 1-4 in-memory and fails if any sidecar drifts from disk content (CI hard-fail)
@@ -263,4 +496,4 @@ After the playbook, the component is consumable by the docs site, the A2UI runti
 - [css-patterns.md](css-patterns.md) — light-DOM CSS cascade rules
 - [api-contract.md](api-contract.md) — props/events/slots conventions
 - [authoring-cycle.md](authoring-cycle.md) — the 5-step authoring procedure
-- `scripts/schemas/component.yaml.schema.json` — JSON Schema (authoritative)
+- `scripts/schemas/component.yaml.schema.json` — JSON Schema (documented contract + IDE aid; not run as a validator — `compileComponent()` enforces only `component:` and the `status` enum, see §Build pipeline)

package/skills/site-deployment/references/deploy-playbooks.md

@@ -139,10 +139,18 @@ itself is unavailable.
    - **`build:site` copies packages but does NOT rebuild their dist bundles** — after
      component `.css`/`.js` source changes, rebuild first (`npm run build -w
      @adia-ai/llm`, then `npm run build:bundles`) or the deployed bundles are stale.
-   - **`scripts/build/site.mjs` is per-package (`copyX()` functions), not glob-based** —
-     every new or renamed package needs its own copy fn or `dist/` silently omits it
-     (local Vite works, prod 404s; caused the v0.3.0 `@adia-ai/llm` + `a2ui-runtime`
-     deploy gaps). After any package add/rename, check `site.mjs` before deploying.
+   - **Package registration is one manifest, `scripts/build/site-package-registry.mjs`
+     (ADR-0062)** — every `@adia-ai/*` package the site ships is one registry entry, from
+     which the dist copy, BOTH importmaps (one shared `renderImportMapBlock()` — the
+     `site/index.html` copy is a generated artifact, `npm run build:site-importmap`),
+     the `dist/node_modules` symlinks, and the CI build order all derive. The old
+     failure class (per-package `copyX()` hand-edits; local Vite works, prod 404s —
+     v0.3.0 llm/a2ui-runtime, v0.8.27 persona+agent) is gated mechanically:
+     `check:site-packages-registered` scans every shipped source root for an
+     unregistered bare `@adia-ai/*` import and fails naming file:line, alongside
+     `check:site-importmap-fresh` and `check:deploy-workflow-build-order` — all three
+     in `npm run check` and early in `deploy-site.yml`. After any package add/rename,
+     add the registry entry; the gates say the rest.
 2. **Dry-run first, and adjudicate every delete — BEFORE the real rsync, never after:**
    ```sh
    rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/' \

package/skills/ssr-compatibility/SKILL.md

@@ -3,9 +3,10 @@ name: ssr-compatibility
 description: >-
   Answers why an AdiaUI component crashes, drops content, or renders wrong
   under SSR (linkedom/Astro consumers) — the four known failure shapes,
-  what's fixed vs open, how to test without a linkedom install. Use when
+  what's fixed vs open, how to prove a fix under the linkedom shim gate. Use when
   asked "does this work under SSR", why a component crashes on
-  attachInternals/ResizeObserver/adoptedStyleSheets under a DOM shim, why
+  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof Node`
+  under a DOM shim, why
   table-ui/chart-ui/select-ui or a container CE renders empty or loses its
   nested children when server-rendered, whether it's safe to call
   getBoundingClientRect() synchronously in connectedCallback, or whether a
@@ -64,10 +65,10 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 | Ask | Answer from |
 | --- | --- |
 | "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2 — shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
-| "why does this crash / throw at construction under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 |
+| "why does this crash / throw at import, construction or connect under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED twice (gh#285, gh#1430/#1436) and now GATED by `scripts/dev/ssr-linkedom-smoke.mjs`; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 — feature-detect the API, never `typeof window` |
 | "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3 — the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
 | "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md) — re-verify against `gh issue view` before trusting it, it drifts |
-| "how do I test an SSR gap — we have no linkedom installed" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — the delete/try/finally pattern, and what it does NOT prove |
+| "how do I test / prove an SSR gap or fix" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — run the linkedom shim gate first (`node scripts/dev/ssr-linkedom-smoke.mjs`, the consumer's exact global surface), then the unit-level delete/try/finally pattern and what it does NOT prove |
 | "what's the consumer's current workaround, and can they drop it yet" | [`consumer-workarounds.md`](references/consumer-workarounds.md) |
 | "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4 — shape 5, CLOSED (table-ui's `data="[…]"` attribute); check whether the reporting component is registered server-side first if it still reproduces |
 
@@ -76,7 +77,11 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 Every fix pattern this pack cites ([`guard-patterns.md`](references/guard-patterns.md))
 carries the reasoning for why it looks the way it does — the no-op `ElementInternals`
 shim exists because leaving the field `undefined` would relocate a crash, not remove
-it; deletion-based testing exists because this repo has no `linkedom` devDependency.
+it; the linkedom shim gate (`scripts/dev/ssr-linkedom-smoke.mjs`, gh#1430) exists
+because happy-dom implements every API in the documented shape-1 cases that linkedom
+lacks (matchMedia, rAF, the Observers, `Node`/`Element` globals, rect APIs), so the
+unit suite is blind to that class by construction — deletion-based testing is the unit-level complement, not
+the proof.
 If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
 new pattern. Route it through `primitive-authoring` — don't force-fit the nearest existing
 shape.

package/skills/ssr-compatibility/references/consumer-workarounds.md

@@ -21,12 +21,20 @@ and force-assigned `document.adoptedStyleSheets = []`. Two named fragilities:
   `globalThis.ResizeObserver` affects EVERY component and every other library in the
   same process, not just AdiaUI's.
 
-**Status as of gh#285's fix (PR #292, merged 2026-07-17): this shim should no longer
-be necessary** — the framework guards its own call sites now. This pack's own routing
-corpus / the issue thread is where confirmation from the consumer would land; don't
-assume it's been removed without checking the issue's comment thread for that
-confirmation, since a consumer removing a workaround is THEIR change, not something
-this fix does automatically.
+**Status as of gh#285's fix (PR #292, merged 2026-07-17): the AdiaUI-facing sections
+of this shim are no longer necessary** — the framework guards its own call sites now.
+**Consumer-confirmed 2026-08-17 (gh#1430 §Additional context, against 0.8.40):**
+`attachInternals`, the four Observer stubs and `adoptedStyleSheets` are all confirmed
+unnecessary. **But gh#285's closing comment over-reached** in saying the shim "as a
+whole" can go: two of its sections patch `CustomElementRender.prototype` — a
+`setAttribute` null-guard and a `renderShadow` null-guard — i.e. they patch
+`custom-elements-ssr` itself, which reads `shadowRoot.innerHTML` unconditionally and
+AdiaUI is light-DOM-only, so `shadowRoot` is always `null`. Remove those two and every
+SSR'd fixture dies with `Cannot read properties of null (reading 'innerHTML')`. No fix
+in this repo can retire them; they belong to the renderer. Tell the next consumer that
+explicitly rather than "the shim is unnecessary". (Also from that trial: `matchMedia`
+was a further AdiaUI-side gap the #292 sweep missed — fixed by gh#1430, so a
+`matchMedia` stub is not needed either from the version carrying it.)
 
 ## Attribute-only SSR registration restriction (gh#284 — likely no longer necessary, unconfirmed)
 

package/skills/ssr-compatibility/references/failure-shapes.md

@@ -19,14 +19,37 @@ or a write to `document.adoptedStyleSheets`.
 not a partial/quirky implementation, an absence. Any unconditional call throws
 `TypeError` or `ReferenceError` (undefined global) immediately.
 
-**Status: FIXED** (gh#285, PR #292, merged 2026-07-17). `UIElement`'s constructor
-(`packages/web-components/core/element.js`) plus a sweep of component/trait/module
-files had this shape — the per-file tally is
+**Status: FIXED, twice — and now GATED.** First wave gh#285 (PR #292, merged
+2026-07-17): `UIElement`'s constructor (`packages/web-components/core/element.js`)
+plus a sweep of component/trait/module files — the per-file tally is
 [`status-ledger.md`](status-ledger.md)'s #285 row (the ledger, not this line, is
-the count of record). The fix pattern (feature-detect + fallback matched to how the reference is
-used downstream) is [`guard-patterns.md`](guard-patterns.md) — apply that pattern to
-any NEW file that construct-calls one of these APIs; don't re-derive the shape from
-scratch.
+the count of record). Second wave gh#1430 + gh#1436 (2026-08-17, found by adiav2's
+first SSR admission trial at 0.8.40): the sweep had missed
+- **environment-detection instead of feature-detection at MODULE scope** —
+  `core/responsive.js` guarded `window.matchMedia(...)` behind `typeof window !==
+  'undefined'`; linkedom HAS a `window`, just no `matchMedia` and no numeric
+  `innerWidth`, so six components (`block`/`col`/`grid`/`row`/`text`/`demo-toggle`)
+  could not be IMPORTED server-side at all;
+- **bare `instanceof Node|Element|HTMLElement`** (15 sites — `core/template.js`
+  `applyValue`, table/list-window renderer results, event-target checks) — a
+  `ReferenceError`, not `false`, because custom-elements-ssr installs ONLY
+  `HTMLElement` as a global (never `Node`, `Element`, `Text`, `DocumentFragment`);
+  now `core/dom.js` `isNode()`/`isElement()` (structural `nodeType` tests);
+- **`requestAnimationFrame` / `MutationObserver` / `getBoundingClientRect` at
+  connect** in feed-item/toast, noodles, preview, toolbar (rAF), nav-group,
+  stepper (MutationObserver — the #292 sweep guarded four Observer sites, not
+  these two) and nav-ui (`getBoundingClientRect` is absent, not zero, on linkedom).
+
+**Why happy-dom could not see any of it:** it implements every one of those APIs.
+The gate that closes the class is `scripts/dev/ssr-linkedom-smoke.mjs`, run by
+`packages/web-components/test/ssr-linkedom-smoke.test.js` — a real `linkedom`
+devDependency installing EXACTLY the six globals `custom-elements-ssr/server-shim.js`
+installs, then importing every `components/*/*.js` entry and constructing +
+connecting every registered tag (124/124 import, every tag renders). A new
+shape-1 instance fails that test, not a consumer's build. The fix pattern
+(feature-detect + fallback matched to how the reference is used downstream) is
+[`guard-patterns.md`](guard-patterns.md) — apply it to any NEW call site; don't
+re-derive the shape from scratch, and don't guard on `typeof window`.
 
 ## 2 · `connectedCallback` destructively re-stamps existing DOM → content loss
 

package/skills/ssr-compatibility/references/guard-patterns.md

@@ -51,6 +51,34 @@ const observer = typeof MutationObserver !== 'undefined'
 // every later use: observer?.observe(...) / bootstrap() no-ops via the same check
 ```
 
+**(d) Feature, not environment — `typeof window` is NOT a guard (gh#1430).**
+linkedom defines `window` (an object) but neither `matchMedia` nor a numeric
+`innerWidth`, so `typeof window !== 'undefined'` passes and the call still throws —
+at MODULE scope that takes every importer off the server. Test the member:
+```js
+// packages/web-components/core/responsive.js
+const w = typeof window !== 'undefined' ? window.innerWidth : undefined;
+if (typeof w !== 'number') return 'lg';                                   // fallback
+if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') { … }
+```
+
+**(e) `instanceof <DOM constructor>` — use `core/dom.js` (gh#1436).** Only
+`HTMLElement` is a global under custom-elements-ssr; `v instanceof Node` /
+`Element` / `Text` / `DocumentFragment` is a `ReferenceError`, not `false`.
+`isNode(v)` / `isElement(v)` test `nodeType` structurally (and also accept nodes
+from another realm, which the constructor identity check never did):
+```js
+import { isNode, isElement } from '../../core/dom.js';
+if (isNode(result)) cell.replaceChildren(result);          // renderer output
+const row = isElement(e.target) ? e.target.closest('…') : null;  // event target
+```
+`isElement` is deliberately the SUPERSET of a former `instanceof HTMLElement` (it
+admits SVG elements too) — every swept site only needed "an element", none needed
+"an HTML element specifically". Absent-method form of the same idea:
+`typeof this.getBoundingClientRect === 'function' && …` (nav-ui) — linkedom has no
+rect API at all, so an unguarded call is a TypeError, not a zero rect (that zero-rect
+case is §3).
+
 **The `this.internals` special case — a shim, not `undefined`.** `UIElement`'s
 constructor (`packages/web-components/core/element.js`) needed a DIFFERENT answer
 than "guard and leave unset," because ~12 files across the framework call

package/skills/ssr-compatibility/references/status-ledger.md

@@ -1,5 +1,15 @@
 # SSR support — status ledger
 
+**Filing a new downstream SSR-seam report?** Use the `ssr` label plus
+[`.github/ISSUE_TEMPLATE/ssr-seam-report.md`](../../../../../../.github/ISSUE_TEMPLATE/ssr-seam-report.md)
+(gh#1384) — it captures the resolved `@adia-ai/web-components` version, the
+downstream kit version, the component + fixture, an SSR-vs-CSR diff or
+minimal repro, and a cosmetic/behavioral/blocked-upstream classification, so
+a report lands triageable instead of free-form (the archaeology the #284/#288
+rows below needed). `docs/ops/spec/spec-ssr-kit.md` is referenced by some
+downstream reports but does not exist in this repo — it lives in adiav2's own
+repo (`@adiav2/ssr-kit`'s spec); do not look for it here.
+
 **This file drifts fast — re-verify against the live issue tracker
 (`gh issue view <n>`) before trusting it for anything beyond a quick orientation.**
 Every row was true as of 2026-07-17; a closed issue below may have re-opened, a PR
@@ -9,6 +19,9 @@ the territory — the territory is `gh issue list` / `gh issue view`.
 | Issue | Failure shape | Status | Shipped in | Notes |
 |---|---|---|---|---|
 | [#285](https://github.com/adiahealth/gen-ui-kit/issues/285) | §1 — browser-only API called unconditionally | **CLOSED** | PR #292 (merged 2026-07-17) | `UIElement` constructor + `adoptStyles()` + 22 component/trait/module files guarded; 10 more already correct from an earlier pass |
+| [#1430](https://github.com/adiahealth/gen-ui-kit/issues/1430) | §1 — browser-only API called unconditionally (module scope: `window.matchMedia` behind a `typeof window` guard) | **FIXED 2026-08-17** | `core/responsive.js` feature-detects `matchMedia` + `innerWidth`; `swiper.class.js` `play()` guarded; `scripts/dev/ssr-linkedom-smoke.mjs` + `test/ssr-linkedom-smoke.test.js` gate the whole catalog under linkedom | 6 components (`block`/`col`/`grid`/`row`/`text`/`demo-toggle`) were un-importable server-side; 118→124 of 124. Side findings on the issue: gh#285's "shim no longer necessary" over-reached (two of the consumer's shim sections patch `custom-elements-ssr` itself, not this library — see `consumer-workarounds.md`); `audit-template-child-conflict.mjs` isn't shipped in the package. |
+| [#1436](https://github.com/adiahealth/gen-ui-kit/issues/1436) | §1 — bare `instanceof Node/Element/HTMLElement` (ReferenceError under linkedom, only `HTMLElement` is global) | **FIXED 2026-08-17** | `core/dom.js` `isNode()`/`isElement()`; 15 sites swept; plus rAF/MutationObserver/getBoundingClientRect guards in feed, noodles, preview, toolbar, nav-group, stepper, nav found by the same gate's render sweep | Same PR as #1430 — one root-cause class. |
+| [#1435](https://github.com/adiahealth/gen-ui-kit/issues/1435) | reported as §2 — check/radio/switch "lose" a `<span slot="label">` child | **NOT an SSR seam** (2026-08-17) | yaml/a2ui `slots` descriptions clarified for the three (separate follow-up PR — a docs-contract change, not a shape-1 guard) | The fixture is not a supported form in CSR either: `label` on all three is ATTRIBUTE-driven (`label="…"` → `aria-label` + `::after content: attr(label)` / template-owned span); a late CSR upgrade replaces the foreign child the same way. The yaml `slots:` entries name template-OWNED anatomy parts (`box`/`dot`/`track`/`thumb`/`label`), which a downstream reimplementation of the audit read as consumer insertion points — the audit's own definition (`slots.default` + non-null template) is what "consumer children" means here. |
 | [#286](https://github.com/adiahealth/gen-ui-kit/issues/286) | §3 — connect-time measurement treated as confirmed | **CLOSED** (for `admin-sidebar` specifically) | PR #290 (merged 2026-07-17) | The GENERAL pattern (any other component reading a rect/size synchronously at connect) is NOT swept — only this one instance is fixed |
 | [#284](https://github.com/adiahealth/gen-ui-kit/issues/284) | §2 — destructive `stamp()` on connect | **CLOSED 2026-07-18 — narrowed AND separately fixed** | `scripts/dev/audit-template-child-conflict.mjs` (PR #295) + `packages/web-components/core/element.js` connectedCallback resync (PR #309) | Two distinct findings. (1) The ORIGINAL diagnosis (destructive `stamp()`) was narrowed 2026-07-17: every component the issue names has `static template = () => null`, so `stamp()` never runs for them — zero shipped components exposed; a static audit gate catches a future regression instead of a lifecycle rewrite. (2) A SEPARATE, real, live bug was found in the same investigation area and fixed 2026-07-18: happy-dom/linkedom don't replay `attributeChangedCallback` for attributes already present at custom-element upgrade (spec §4.13.5 step 6) — any `reflect: true` property seeded only from pre-parsed/SSR HTML stayed at its class default after upgrade (e.g. `<nav-item-ui text="Profile">` rendered with an empty label). `connectedCallback` now re-syncs every declared property from its live attribute before `connected()` runs. See `failure-shapes.md` §2 for the full narrative. |
 | [#288](https://github.com/adiahealth/gen-ui-kit/issues/288) | §4 — property-only components can't seed from SSR HTML | **CLOSED 2026-07-18** | `table.class.js` `data="[…]"` attribute hydration | Never actually blocked on #284 (table-ui/chart-ui/select-ui all use `static template = () => null`, so the stamp() question never applied). Scope was narrower than filed: `select-ui` already parsed declarative `<option>` children, `chart-ui` already hydrated `.data` from a `data="[…]"` attribute — only `table-ui`'s `.data` had no declarative form. Fixed in the same attribute-hydration shape as chart-ui, not the JSON-script-child form originally proposed. |

package/skills/ssr-compatibility/references/test-without-linkedom.md

@@ -1,10 +1,24 @@
-# Testing an SSR gap without a real linkedom install
+# Testing an SSR gap — the linkedom gate first, then the deletion pattern
 
-This repo has **no `linkedom` devDependency** (checked 2026-07-17: not in
-`package.json` at any workspace level). The test suite runs on `happy-dom`/`jsdom`
-(whichever `vitest` is configured with), and BOTH of those implement most of the APIs
-linkedom lacks — so a naive test using the default environment will not reproduce an
-SSR-shaped bug. Two consequences:
+**UPDATE 2026-08-17 (gh#1430/#1436): this repo now HAS a `linkedom` root
+devDependency and a shipped shim gate.** `scripts/dev/ssr-linkedom-smoke.mjs`
+installs exactly the six globals `custom-elements-ssr/server-shim.js` installs
+(document, window, customElements, HTMLElement, Event, CustomEvent — and nothing
+else: no Node/Element/Text/DocumentFragment, no matchMedia, no
+requestAnimationFrame, no getBoundingClientRect), imports every
+`components/*/*.js` entry, and constructs + connects every registered tag the way
+`CustomElementRender` does; `packages/web-components/test/ssr-linkedom-smoke.test.js`
+runs it as a Node child process and fails on any import or render throw. **For a
+shape-1 question ("does this crash under SSR"), run that first** — `node
+scripts/dev/ssr-linkedom-smoke.mjs` — it is the consumer's environment, not an
+approximation. Add a row to its `FIXTURES` table when a guard lands on a branch only
+some attribute value reaches (`swiper-ui[autoplay]` is the model). The rest of this
+file is the UNIT-level pattern for a focused regression test in the happy-dom
+suite; it stays valid, but it is no longer the only proof available.
+
+The main test suite still runs on `happy-dom` (`vitest.config.js`), which
+implements most of the APIs linkedom lacks — so a naive test using the default
+environment will not reproduce an SSR-shaped bug. Two consequences:
 
 1. **You cannot trust "the tests pass" as proof an SSR fix works** unless the test
    itself removes the API under test. A guard around `attachInternals` that's never
@@ -118,12 +132,13 @@ actually present. Both gh#285 and gh#286's fixes were verified this second way b
 shipping (a real `ElementInternals` instance still used and functional; a real
 `ResizeObserver` tick still corrects state) — do both, never one instead of the other.
 
-## If a deeper simulation becomes worth the cost
+## The deeper simulation — DONE 2026-08-17
 
-A real `linkedom` install (as a devDependency, used only in a dedicated SSR-simulation
-test file, never in the main suite) would let a test actually import `linkedom`,
-create a document with it, and run REAL component code against REAL absent APIs
-end-to-end — closer to the consumer's actual failure mode than deletion, and the only
-way to test shape 2/4 meaningfully. This has not been done as of 2026-07-17 — it's a
-tooling investment, not a quick addition; raise it as its own decision if shape 2's
-investigation (gh#284) needs it.
+The real-`linkedom` simulation this section used to propose is now the shipped
+gate described at the top of this file (`scripts/dev/ssr-linkedom-smoke.mjs`,
+`linkedom` pinned as a root devDependency, used only there — the main suite stays
+on happy-dom). It sweeps import + connect for the whole catalog; a shape-2/4
+question (content preserved across a late upgrade, declarative data seeding) is
+still answered by a targeted test — extend the script's `FIXTURES` table with the
+attrs/children in question, or write the assertion in
+`test/ssr-upgrade-adoption-contract.test.js`'s late-upgrade shape.