@adia-ai/adia-ui-forge 0.8.61 → 0.8.63

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

@@ -1,7 +1,7 @@
-# Guard patterns — the established fix shape per failure shape
+# Guard patterns, the established fix shape per failure shape
 
 Cites the actual shipped code (gh#285 PR #292, gh#286 PR #290) as the pattern to copy
-for a NEW instance of the same failure class — don't re-derive the shape, match it.
+for a NEW instance of the same failure class, don't re-derive the shape, match it.
 
 ## §1 · A browser-only API constructor/method call
 
@@ -9,16 +9,16 @@ for a NEW instance of the same failure class — don't re-derive the shape, matc
 `IntersectionObserver`, `MutationObserver`, `PerformanceObserver`) or `typeof
 this.<method> === 'function'` (for instance methods: `attachInternals`) or `'<prop>'
 in <object>` (for object properties: `document.adoptedStyleSheets`) guards the call;
-the ELSE branch is picked by what downstream code does with the reference — there is
+the ELSE branch is picked by what downstream code does with the reference, there is
 no one boilerplate to paste everywhere.
 
 **Three concrete shapes, all live in the repo:**
 
-**(a) Field assigned, used later with `?.` on teardown** — the majority case. Guard the
+**(a) Field assigned, used later with `?.` on teardown**, the majority case. Guard the
 construction; every later reference to the field must already (or now needs to) use
 optional chaining, since the field can legitimately stay unset:
 ```js
-// packages/web-modules/shell/admin-sidebar/admin-sidebar.js — #setupChildResizeObserver
+// packages/web-modules/shell/admin-sidebar/admin-sidebar.js, #setupChildResizeObserver
 #setupChildResizeObserver() {
   this.#childRO = new ResizeObserver((entries) => { ... });
   this.#childRO.observe(this);
@@ -31,7 +31,7 @@ if (typeof ResizeObserver !== 'undefined') {
 // disconnectedCallback: this.#childRO?.disconnect();  ← already needs the `?.`
 ```
 
-**(b) Early-return no-op** — when the entire trait/method's purpose IS the observer;
+**(b) Early-return no-op**, when the entire trait/method's purpose IS the observer;
 nothing else in the function is worth running without it:
 ```js
 // packages/web-components/traits/resize-observer/resize-observer.js
@@ -41,7 +41,7 @@ setup({ host }) {
 }
 ```
 
-**(c) Module-level `const`, ternary at declaration** — when the observer is a
+**(c) Module-level `const`, ternary at declaration**, when the observer is a
 singleton constructed at import time, not per-instance:
 ```js
 // packages/web-components/core/data-stream.js
@@ -51,10 +51,9 @@ 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).**
+**(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:
+`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;
@@ -62,7 +61,7 @@ if (typeof w !== 'number') return 'lg';                                   // fal
 if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') { … }
 ```
 
-**(e) `instanceof <DOM constructor>` — use `core/dom.js` (gh#1436).** Only
+**(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
@@ -73,13 +72,13 @@ 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
+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
+`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
+**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
 `this.internals.setValidity(...)` / `.setFormValue(...)` unconditionally (form
@@ -108,33 +107,33 @@ returned object/value is always truthy and call methods on it unconditionally?"
 yes, a no-op shim matching the ACTUAL consumed surface (grep for it, don't guess) is
 the right answer, not leaving the field `undefined`. If the API is purely
 fire-and-forget infrastructure with no return value anyone depends on (most
-Observers), a plain construction guard (shapes a/b/c above) is sufficient — no shim
+Observers), a plain construction guard (shapes a/b/c above) is sufficient, no shim
 needed.
 
-## §2 · Destructive `stamp()` on connect (gh#284 — narrowed to a static audit, not a stamp() patch)
+## §2 · Destructive `stamp()` on connect (gh#284, narrowed to a static audit, not a stamp() patch)
 
 There is no `stamp()`/`connectedCallback` fix, and per the 2026-07-17 narrowing
-there isn't meant to be one — the mechanism is real but zero shipped components
+there isn't meant to be one: the mechanism is real but zero shipped components
 are exposed (see [`failure-shapes.md`](failure-shapes.md) §2 for the full survey).
 The shipped guard is `scripts/dev/audit-template-child-conflict.mjs`: it flags a
 NEW component that pairs a non-null `static template` with a yaml `slots.default`
-entry (critical) or a body-text usage example (advisory) — i.e. it prevents the
+entry (critical) or a body-text usage example (advisory), i.e. it prevents the
 conflict shape from being reintroduced, rather than patching the render lifecycle
 every component goes through (150 at the 2026-07 survey; the census grows). **A component author who hits this
 audit's finding fixes it by making the template `() => null`** (the pattern every
-current children-accepting component already uses — compose via CSS + `render()`'s
+current children-accepting component already uses, compose via CSS + `render()`'s
 own surgical DOM manipulation, matching `avatar-ui`'s `#imgEl`/`#initialsEl`
-pattern) — NOT by inventing a component-local stamp-skip flag or a marker
+pattern), NOT by inventing a component-local stamp-skip flag or a marker
 attribute; either of those drifts from the established convention and isn't
 covered by this audit's "safe" classification. If a genuinely new component NEEDS
 both a non-null template AND real consumer children (unlike anything shipped
-today), route through `primitive-authoring` before authoring it — that's a real design
+today), route through `primitive-authoring` before authoring it, that's a real design
 question, not a mechanical fix.
 
 ## §2b · Reflected properties not initialized from pre-existing attributes on upgrade (gh#284's REAL fix, PR #309)
 
 **Shape:** a `reflect: true` property stays at its class default after a LATE
-custom-element upgrade — the element was parsed/appended (or server-rendered)
+custom-element upgrade: the element was parsed/appended (or server-rendered)
 with its attribute already present, but the tag wasn't `customElements.define`d
 until afterward. `<nav-item-ui text="Profile">` renders an empty label; any
 other reflected prop on any component is at equal risk under the same
@@ -143,10 +142,10 @@ sequence.
 **Root cause:** the custom-elements spec's "upgrade an element" algorithm
 (§4.13.5 step 6) requires replaying `attributeChangedCallback` for every
 attribute already on the element BEFORE `connectedCallback` fires on upgrade.
-happy-dom (this repo's test DOM) does not do this — confirmed directly with a
+happy-dom (this repo's test DOM) does not do this, confirmed directly with a
 bare `HTMLElement` subclass, no AdiaUI code involved
 (`packages/web-components/core/element.test.js`,
-`describe('UIElement — SSR attribute-upgrade replay (gh#284)')`, first test).
+`describe('UIElement: SSR attribute-upgrade replay (gh#284)')`, first test).
 linkedom is a similarly from-scratch custom-elements registry, so the same gap
 is the working hypothesis there too pending direct confirmation.
 
@@ -165,29 +164,28 @@ for (const [key, cfg] of Object.entries(ctor.properties)) {
 
 Safe on every environment: `connectedCallback` fires reliably everywhere
 (unlike the shimmed `attributeChangedCallback` replay), and the resync is a
-no-op where the replay already happened correctly — the property setter's
+no-op where the replay already happened correctly: the property setter's
 `Object.is` check short-circuits when the value already matches, so no extra
-render pass. This is a FRAMEWORK-LEVEL fix, already shipped — a component
+render pass. This is a FRAMEWORK-LEVEL fix, already shipped, a component
 author hitting this shape doesn't need to do anything component-local; if a
 reflected prop still looks wrong after upgrade on a version carrying this fix,
-that's a new, different bug — don't assume it's this one recurring.
+that's a new, different bug, don't assume it's this one recurring.
 
 ## §3 · A connect-time measurement is "unknown," not "confirmed"
 
 **Shape:** treat a zero (or otherwise clearly-bogus) synchronous read as "no signal
 yet" and DEFER the decision to whatever async correction mechanism the component
-already has — don't add a new one if an existing `ResizeObserver`/similar already
+already has, don't add a new one if an existing `ResizeObserver`/similar already
 watches the same dimension.
 ```js
-// packages/web-modules/shell/admin-sidebar/admin-sidebar.js — #syncCollapsedFromWidth
+// packages/web-modules/shell/admin-sidebar/admin-sidebar.js, #syncCollapsedFromWidth
 #syncCollapsedFromWidth() {
   const w = this.getBoundingClientRect().width;
-  if (w === 0) return;              // ← unknown, not "confirmed collapsed" —
-  this.collapsed = w <= SNAP_THRESHOLD;   //   leaves whatever connected() already
+  if (w === 0) return;              // ← unknown, not "confirmed collapsed", this.collapsed = w <= SNAP_THRESHOLD;   //   leaves whatever connected() already
 }                                          //   restored (persisted state, or default)
 
 // the component's EXISTING ResizeObserver callback (already watching this.host for
-// an unrelated reason — flipping select-ui placement) gains ONE more line, so its
+// an unrelated reason, flipping select-ui placement) gains ONE more line, so its
 // first REAL tick (post-hydration, or after the display:none ancestor is revealed)
 // resolves what connect-time couldn't:
 #setupChildResizeObserver() {
@@ -201,25 +199,24 @@ watches the same dimension.
 }
 ```
 The key move: reuse the observer that's ALREADY there rather than adding a
-purpose-built one — a second observer watching the same element for two unrelated
+purpose-built one, a second observer watching the same element for two unrelated
 reasons is a maintenance smell, and per §1 above, a NEW observer needs its own
 construction guard anyway.
 
-## §4 · Adopt-or-diff — value-diff before mutating, never guess or half-adopt (gh#1678, gh#1687)
+## §4 · Adopt-or-diff, value-diff before mutating, never guess or half-adopt (gh#1678, gh#1687)
 
 **Shape:** don't mutate a DOM position until a comparison proves it actually
 needs to change. `setAttribute()` queues a mutation record even when the new
 value is byte-identical to the old one (confirmed directly against both
 happy-dom and linkedom); `removeAttribute()` on an already-absent attribute
-does NOT (the spec's own asymmetry — no compare-first guard needed there).
+does NOT (the spec's own asymmetry, no compare-first guard needed there).
 Two concrete shapes, both shipped, picked by whether the reconciled unit
 carries a stable identity key:
 
-**(a) A flat, keyed list — seed the keyed-reconcile map from the adopted
+**(a) A flat, keyed list, seed the keyed-reconcile map from the adopted
 DOM (`pagination-ui`, gh#1687).** `connected()` adopts a pre-existing
 server-rendered structural child (`this.#nav = this.querySelector(':scope
-> nav[slot="nav"]')`) instead of unconditionally creating a fresh one —
-but adopting the CONTAINER alone isn't sufficient: `reconcile()`'s own
+> nav[slot="nav"]')`) instead of unconditionally creating a fresh one, but adopting the CONTAINER alone isn't sufficient: `reconcile()`'s own
 keyed diff (`core/element.js`) keys off a `parent[KEY_MAP]` populated by
 this element's OWN prior render calls, which a freshly-parsed SSR fragment
 never has. Without seeding it, the very first render treats every adopted
@@ -230,13 +227,13 @@ mismatch (`#childMatchesItem()` checking tag + marker, not just count) is
 left unseeded so reconcile falls back to a genuine clean rebuild instead of
 miskeying a wrong-tagged survivor in place.
 
-**(b) An arbitrary positional child with no stable key — compare via
+**(b) An arbitrary positional child with no stable key, compare via
 `Node.isEqualNode()` (`table-ui`, gh#1678).** Table cells have no identity
 key the way a pagination item does (no natural "this is always the id
 column" marker independent of position), so `adoptOrDiffChildren()`
 (`table.class.js`) builds each fresh candidate exactly as before, then
 compares it against the existing child at that position with
-`existing.isEqualNode(fresh)` — standard DOM, present under every
+`existing.isEqualNode(fresh)`, standard DOM, present under every
 environment this framework runs in (browsers, happy-dom, linkedom), never
 one of §1's browser-only APIs:
 ```js
@@ -248,12 +245,12 @@ function adoptOrDiffChildren(container, freshChildren) {
     if (!existing) container.appendChild(fresh);
     else if (RENDERER_OWNED.has(fresh) || !existing.isEqualNode(fresh)) container.replaceChild(fresh, existing);
     // else: matches byte-for-byte AND carries no renderer-owned runtime
-    // state (§4.1 below) — adopt in place, touch nothing.
+    // state (§4.1 below), adopt in place, touch nothing.
   }
 }
 ```
 A match adopts in place (zero mutation); a mismatch replaces the position
-wholesale exactly as the pre-fix code always did — never a partial patch of
+wholesale exactly as the pre-fix code always did, never a partial patch of
 a mismatched node's individual attributes, which would risk leaving a
 wrong-tagged or wrong-shaped survivor "fixed" in place instead of really
 rebuilt (the same failure mode (a) above guards against via
@@ -261,7 +258,7 @@ rebuilt (the same failure mode (a) above guards against via
 
 ### §4.1 · `isEqualNode()` proves structural safety, never runtime-state safety (gh#1678 CodeRabbit follow-up, closed on PR #1756 before merge)
 
-**The gap:** (b) above is a *structural* diff — tag, attributes, text,
+**The gap:** (b) above is a *structural* diff, tag, attributes, text,
 descendants. It's a necessary adoption test but not a sufficient one: it
 cannot see an event listener (or any other runtime/imperative state) that a
 renderer attached to the candidate node it returned. `table.class.js`'s
@@ -269,16 +266,16 @@ renderer attached to the candidate node it returned. `table.class.js`'s
 consumer function; or a built-in cell-type renderer, `typeDef.render`)
 BEFORE the candidate ever reaches `adoptOrDiffChildren()`. If that renderer
 attached a listener, the candidate can still be `isEqualNode()`-identical to
-the existing (e.g. listener-less, SSR-parsed) DOM at that position — the
+the existing (e.g. listener-less, SSR-parsed) DOM at that position, the
 guard reports a match, adopts the OLD node, discards the fresh one, and the
 listener silently never lands. The pre-adopt-or-diff, unconditional-
 `replaceChild()` code never had this bug, because it always installed
 whatever the renderer had just built, every time.
 
-**The fix — an explicit renderer-owned marker, not a deeper structural
+**The fix, an explicit renderer-owned marker, not a deeper structural
 check.** A `Node.isEqualNode()`-shaped fix can only ever prove declarative
 shape; it structurally cannot see a listener, so the fix isn't "compare
-harder" — it's "know which candidates a comparison can't clear in the first
+harder", it's "know which candidates a comparison can't clear in the first
 place, and never let structural equality alone adopt one of those." A
 module-level `RENDERER_OWNED` `WeakSet` tags exactly the cells built by
 something free to attach listeners/runtime state:
@@ -288,7 +285,7 @@ const RENDERER_OWNED = new WeakSet();
 if (typeof col.render === 'function') {
   const result = col.render(value, data, cell, dataIndex);
   // ... apply result to cell ...
-  RENDERER_OWNED.add(cell);           // arbitrary code — always tag
+  RENDERER_OWNED.add(cell);           // arbitrary code, always tag
 } else if (typeof col.format !== 'function') {
   const typeDef = cellTypes[col.type || 'text'];
   if (typeDef?.render) {
@@ -297,19 +294,19 @@ if (typeof col.render === 'function') {
   }
 }
 ```
-`col.render()` is always tagged — it's opaque consumer code, impossible to
+`col.render()` is always tagged, it's opaque consumer code, impossible to
 introspect for safety. A built-in cell-type renderer is tagged only when
-its own registration declares `attachesListeners: true` — in this
+its own registration declares `attachesListeners: true`, in this
 framework, currently just `cellTypes.actions` (`cell-types.js`), the one
 built-in type that calls `addEventListener()` directly on a node it builds.
 Every OTHER built-in cell type (text/number/currency/percent/date/datetime/
 boolean/badge/avatar/link/markdown/progress) only sets attributes on
-already-declarative custom elements or plain nodes — no listeners, so
+already-declarative custom elements or plain nodes, no listeners, so
 tagging them buys nothing and costs the zero-mutation benefit for the
 overwhelmingly common case. **This was measured, not assumed**: an earlier
 draft of this fix tagged every `typeDef.render` cell unconditionally and
 broke the AC-004a zero-mutation test (§ above) for plain text/number/date
-cells — narrowed to the declared-flag form before merge.
+cells, narrowed to the declared-flag form before merge.
 
 **Applying this pattern to a NEW adopt-or-diff instance (elsewhere in this
 framework, or #1755/#1754 if either goes this direction):** before trusting
@@ -317,17 +314,17 @@ framework, or #1755/#1754 if either goes this direction):** before trusting
 invokes to build a candidate node is free to attach a listener or stash
 other runtime state on it. If yes, that candidate needs its own
 `RENDERER_OWNED`-shaped tag (or equivalent) and must always be replaced,
-never adopted on structural equality alone — an activation step that tries
+never adopted on structural equality alone, an activation step that tries
 to re-attach the listener onto the ADOPTED node instead is a fragile
 protocol this fix deliberately did not attempt (unclear how to discover
 "what would the renderer have attached" without re-running the renderer,
 at which point you already have the fresh node to just use).
 
-**(c) Idempotent attribute writes — the write itself must be guarded, not
+**(c) Idempotent attribute writes, the write itself must be guarded, not
 just the value.** Any attribute set that runs on EVERY render/connect
 regardless of whether the value changed (a host's `role`/`tabindex`, an
 inline computed style, a row's `data-index`/`aria-selected`) needs a
-compare-before-write wrapper — `setAttrIfChanged(el, name, value)` — because
+compare-before-write wrapper, `setAttrIfChanged(el, name, value)`, because
 a bare `setAttribute(el, name, sameValue)` still mutates. `removeAttribute`
 needs no equivalent guard (already a no-op on an absent attribute per
 spec, confirmed directly).
@@ -338,9 +335,8 @@ of cells/fields with no such per-position identity → (b). Both fall back to
 the SAME principle on a mismatch: rebuild for real, never guess and never
 half-adopt (leave a wrong node "patched" in place instead of replaced).
 
-**The conditional-inject class (querySelector-guard-before-innerHTML —
-`search-ui`, `pagination-ui`) is this same principle at container
-granularity** — `if (!this.querySelector('input-ui')) this.innerHTML = …`
+**The conditional-inject class (querySelector-guard-before-innerHTML, `search-ui`, `pagination-ui`) is this same principle at container
+granularity**, `if (!this.querySelector('input-ui')) this.innerHTML = …`
 IS an adopt-or-diff check, just a boolean presence check instead of a value
 comparison. It's SSR-safe exactly when the querySelector target is
 STRUCTURALLY SPECIFIC (an exact tag/slot, never "has any children at all").
@@ -351,4 +347,4 @@ idempotent-write guard, not yet applied to `search-ui`/`pagination-ui`).
 ## Verify targets for a new guard
 
 See [`test-without-linkedom.md`](test-without-linkedom.md) for how to prove a new
-guard actually works — deleting the real API in a test, not mocking it.
+guard actually works, deleting the real API in a test, not mocking it.

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

@@ -1,41 +1,41 @@
-# SSR support — status ledger
+# 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
+(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
+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
+**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
 number may have been superseded by a follow-up fix, etc. This ledger is a map, not
-the territory — the territory is `gh issue list` / `gh issue view`.
+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. |
-| [#287](https://github.com/adiahealth/gen-ui-kit/issues/287) | Unrelated to the three SSR shapes above — a Phosphor-icon `import.meta.glob` path failure under workspace hoisting, plus the dep-optimizer silently emptying the icon registry | **CLOSED** | PR #294 (merged 2026-07-17) | Root cause confirmed empirically (a from-scratch pnpm workspace repro): the glob's leading `/` joined to Vite's configured root, which only reaches a transitive dependency's assets when hoisted there. Fixed by switching to an entry-file-relative glob (`../node_modules/...`). A second, independent cause (Vite's dev-server `optimizeDeps` pre-bundling) has no package-side fix — documented as a consumer `optimizeDeps.exclude` workaround. A bundler/workspace-resolution bug, not an SSR-lifecycle bug — still doesn't route through this pack's failure taxonomy. |
-| [#1678](https://github.com/adiahealth/gen-ui-kit/issues/1678) | §5 (new) — a custom `render()`/`connected()` unconditionally rebuilds a subtree that already matches; §5.1 (new) — `isEqualNode()` proves structural safety only, never runtime-state safety (a renderer-owned listener can be silently dropped on adoption — CodeRabbit finding, closed in the same PR); §6 (new) — the conditional-inject class, decision recorded | **PR #1756 opened 2026-08-20 (branch `1678-table-ssr-adopt-or-diff`), NOT yet merged — human review required before landing (core table-ui render path)** | `table.class.js` `adoptOrDiffChildren()` + `RENDERER_OWNED` + `setAttrIfChanged()`/`removeAttrIfPresent()`; `cell-types.js`'s `attachesListeners: true` on `actions` | §5/§5.1 implemented for table-ui only, pending merge — no framework-wide static audit exists for this shape yet. §6's decision: querySelector-guard-before-innerHTML (`search-ui`, `pagination-ui`) is SSR-safe when the guard target is structurally specific; [#1755](https://github.com/adiahealth/gen-ui-kit/issues/1755) (filed alongside this PR, already merged) extends the idempotent-write guard to those two components' own post-adopt attribute writes, scoped OUT of this PR. |
+| [#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. |
+| [#287](https://github.com/adiahealth/gen-ui-kit/issues/287) | Unrelated to the three SSR shapes above, a Phosphor-icon `import.meta.glob` path failure under workspace hoisting, plus the dep-optimizer silently emptying the icon registry | **CLOSED** | PR #294 (merged 2026-07-17) | Root cause confirmed empirically (a from-scratch pnpm workspace repro): the glob's leading `/` joined to Vite's configured root, which only reaches a transitive dependency's assets when hoisted there. Fixed by switching to an entry-file-relative glob (`../node_modules/...`). A second, independent cause (Vite's dev-server `optimizeDeps` pre-bundling) has no package-side fix, documented as a consumer `optimizeDeps.exclude` workaround. A bundler/workspace-resolution bug, not an SSR-lifecycle bug, still doesn't route through this pack's failure taxonomy. |
+| [#1678](https://github.com/adiahealth/gen-ui-kit/issues/1678) | §5 (new), a custom `render()`/`connected()` unconditionally rebuilds a subtree that already matches; §5.1 (new), `isEqualNode()` proves structural safety only, never runtime-state safety (a renderer-owned listener can be silently dropped on adoption, CodeRabbit finding, closed in the same PR); §6 (new), the conditional-inject class, decision recorded | **PR #1756 opened 2026-08-20 (branch `1678-table-ssr-adopt-or-diff`), NOT yet merged, human review required before landing (core table-ui render path)** | `table.class.js` `adoptOrDiffChildren()` + `RENDERER_OWNED` + `setAttrIfChanged()`/`removeAttrIfPresent()`; `cell-types.js`'s `attachesListeners: true` on `actions` | §5/§5.1 implemented for table-ui only, pending merge, no framework-wide static audit exists for this shape yet. §6's decision: querySelector-guard-before-innerHTML (`search-ui`, `pagination-ui`) is SSR-safe when the guard target is structurally specific; [#1755](https://github.com/adiahealth/gen-ui-kit/issues/1755) (filed alongside this PR, already merged) extends the idempotent-write guard to those two components' own post-adopt attribute writes, scoped OUT of this PR. |
 
 ## What "done" looks like for the open items
 
-- **#284's original scope is closed as a non-issue against 0.8.4** — see the ledger
+- **#284's original scope is closed as a non-issue against 0.8.4**, see the ledger
   row above. Re-open only if a FUTURE component's yaml/class.js trips
   `audit-template-child-conflict.mjs`, or if `adiav2`'s production workaround
   (`consumer-workarounds.md`) turns out to be catching something this repo's
   synthetic repro didn't (confirm via the issue thread before assuming so).
-- **#288 is done** — see the ledger row above. `table-ui`'s `data="[…]"` attribute
+- **#288 is done**, see the ledger row above. `table-ui`'s `data="[…]"` attribute
   is the shipped form; `select-ui` and `chart-ui` already had their own declarative
   forms before this issue was even filed.
 
@@ -43,5 +43,5 @@ the territory — the territory is `gh issue list` / `gh issue view`.
 
 When any row's status changes, update the table AND re-check whether
 [`consumer-workarounds.md`](consumer-workarounds.md)'s claims about what's "now
-deletable" are still accurate — a workaround section that says "should no longer be
+deletable" are still accurate, a workaround section that says "should no longer be
 necessary" for a shape that's since re-opened is a false manifest, not a stale detail.

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

@@ -1,51 +1,51 @@
-# Testing an SSR gap — the linkedom gate first, then the deletion pattern
+# Testing an SSR gap, the linkedom gate first, then the deletion pattern
 
 **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
+(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
+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
+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
    exercised without `attachInternals` proves nothing.
-2. **The house pattern is deletion, not mocking** — `delete
+2. **The house pattern is deletion, not mocking**, `delete
    HTMLElement.prototype.attachInternals` (or `delete
    Document.prototype.adoptedStyleSheets`, or `delete globalThis.ResizeObserver`)
    inside a `try { ... } finally { restore }` block, in the SAME test environment the
    suite already runs in. This is a closer approximation of "the API is genuinely
    absent" than a mock that might itself paper over the exact code path that would
-   throw — deleting the real thing exercises the REAL `typeof x === 'undefined'` /
+   throw, deleting the real thing exercises the REAL `typeof x === 'undefined'` /
    `typeof x === 'function'` check the guard actually uses.
 
-## The pattern (descriptor-based restore — copy this shape for a new test)
+## The pattern (descriptor-based restore, copy this shape for a new test)
 
 The shipped test (`packages/web-components/core/element.test.js`, describe block
-`'UIElement — SSR browser-API absence (gh#285)'`) restores via a plain `=` assignment
+`'UIElement, SSR browser-API absence (gh#285)'`) restores via a plain `=` assignment
 (`HTMLElement.prototype.attachInternals = original`). That works there ONLY because
 `original` is always a real function in this repo's test environment (happy-dom always
-provides `attachInternals`) — it never actually exercises the absent-original case.
+provides `attachInternals`), it never actually exercises the absent-original case.
 **Don't copy that shortcut.** If `original` is ever genuinely `undefined` (a NEW test
 targeting an API this environment doesn't have either), a plain assignment leaves the
-property present with value `undefined` instead of restoring true absence — later
+property present with value `undefined` instead of restoring true absence, later
 tests checking `'attachInternals' in HTMLElement.prototype` would wrongly see `true`,
 making pass/fail order-dependent (flagged by review on this pack's own PR #293).
-Use the descriptor-based restore — the exact shape `adoptedStyleSheets` already uses
-below — for every new instance of this pattern:
+Use the descriptor-based restore, the exact shape `adoptedStyleSheets` already uses
+below, for every new instance of this pattern:
 
 ```js
 it('constructs without throwing when attachInternals does not exist', () => {
@@ -61,8 +61,7 @@ it('constructs without throwing when attachInternals does not exist', () => {
 });
 ```
 
-For a global (not a prototype method), the same descriptor-based restore applies —
-globals are own-properties of `globalThis`, so `Object.getOwnPropertyDescriptor`
+For a global (not a prototype method), the same descriptor-based restore applies, globals are own-properties of `globalThis`, so `Object.getOwnPropertyDescriptor`
 works identically:
 ```js
 const desc = Object.getOwnPropertyDescriptor(globalThis, 'ResizeObserver');
@@ -91,31 +90,31 @@ try {
 Deletion proves "the guarded code path doesn't throw when the API is absent." It does
 **not** prove:
 - that linkedom's ACTUAL behavior matches "absent" exactly (linkedom may implement a
-  PARTIAL or subtly-wrong version of an API rather than nothing at all — always check
+  PARTIAL or subtly-wrong version of an API rather than nothing at all, always check
   the consumer's bug report for the exact error, don't assume "missing" when the
   report says something more specific);
 - anything about shape 2's ORIGINAL destructive-`stamp()` diagnosis (narrowed
-  2026-07-17) or shape 5 (declarative data binding, gh#288) — neither is an
+  2026-07-17) or shape 5 (declarative data binding, gh#288), neither is an
   API-absence bug, so this deletion-based method doesn't apply to them. Shape
   2's narrowing was verified with exactly the shape of test this section
-  describes — a container element given real children (or text) BEFORE
+  describes, a container element given real children (or text) BEFORE
   `document.appendChild()` connects it (simulating server-parsed markup that
-  already has content when `connectedCallback` first runs) — confirming
+  already has content when `connectedCallback` first runs), confirming
   `nav-ui`/`check-ui` preserve pre-existing content while a synthetic
   non-null-template component loses it (see
   [`failure-shapes.md`](failure-shapes.md) §2). That reproduction was a
-  throwaway, not a shipped permanent test — if shape 2 needs re-verifying later
+  throwaway, not a shipped permanent test, if shape 2 needs re-verifying later
   (a new component trips `audit-template-child-conflict.mjs`, or the consumer
   reports something new), rebuild it the same way rather than assuming the old
   narrowing still holds.
 
   **Shape 2b (the attribute-upgrade-replay gap, gh#284's real fix, 2026-07-18)
-  IS testable this way, and now HAS a shipped permanent test** — it's not an
+  IS testable this way, and now HAS a shipped permanent test**, it's not an
   API-absence bug either, but the exact same "define the tag AFTER the markup
   already exists" sequence reproduces it directly, no deletion trick needed
   (the gap is happy-dom's own upgrade behavior, not a missing API to delete).
   See `packages/web-components/core/element.test.js`,
-  `describe('UIElement — SSR attribute-upgrade replay (gh#284)')`, for the
+  `describe('UIElement: SSR attribute-upgrade replay (gh#284)')`, for the
   canonical `mountLateUpgrade()` helper and four tests: confirms the
   environment gap on a bare custom element, confirms a reflected string prop
   and a reflected boolean prop both resolve correctly post-fix, and confirms
@@ -126,19 +125,19 @@ Deletion proves "the guarded code path doesn't throw when the API is absent." It
 ## Live-browser confirmation is still required, separately
 
 The delete/try/finally tests prove the GUARD doesn't crash. They do not prove real
-browsers are unaffected — that's a SEPARATE check, done live (Playwright or the
+browsers are unaffected, that's a SEPARATE check, done live (Playwright or the
 Chrome extension), confirming the real API still gets used correctly when it's
 actually present. Both gh#285 and gh#286's fixes were verified this second way before
 shipping (a real `ElementInternals` instance still used and functional; a real
-`ResizeObserver` tick still corrects state) — do both, never one instead of the other.
+`ResizeObserver` tick still corrects state), do both, never one instead of the other.
 
-## The deeper simulation — DONE 2026-08-17
+## The deeper simulation, DONE 2026-08-17
 
 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
+`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
+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.