@adia-ai/adia-ui-forge 0.8.39 → 0.8.41

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.