@adia-ai/adia-ui-forge 0.8.4 → 0.8.5

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

@@ -0,0 +1,113 @@
+# Testing an SSR gap without a real linkedom install
+
+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:
+
+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
+   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'` /
+   `typeof x === 'function'` check the guard actually uses.
+
+## 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
+(`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.
+**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
+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:
+
+```js
+it('constructs without throwing when attachInternals does not exist', () => {
+  const desc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'attachInternals');
+  delete HTMLElement.prototype.attachInternals;
+  try {
+    class El extends UIElement {}
+    const tag = registerTestElement(El);
+    expect(() => mount(tag)).not.toThrow();
+  } finally {
+    if (desc) Object.defineProperty(HTMLElement.prototype, 'attachInternals', desc);
+  }
+});
+```
+
+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');
+delete globalThis.ResizeObserver;
+try {
+  // ... construct the component, assert it doesn't throw and degrades sanely ...
+} finally {
+  if (desc) Object.defineProperty(globalThis, 'ResizeObserver', desc);
+}
+```
+
+For `document.adoptedStyleSheets` (an own-property on `Document.prototype`), delete
+the property descriptor and restore it the same way:
+```js
+const desc = Object.getOwnPropertyDescriptor(Document.prototype, 'adoptedStyleSheets');
+delete Document.prototype.adoptedStyleSheets;
+try {
+  // ... assert ...
+} finally {
+  if (desc) Object.defineProperty(Document.prototype, 'adoptedStyleSheets', desc);
+}
+```
+
+## What this method does NOT catch
+
+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
+  the consumer's bug report for the exact error, don't assume "missing" when the
+  report says something more specific);
+- anything about shape 2 (destructive `stamp()`, gh#284 — narrowed 2026-07-17) or
+  shape 4 (declarative data binding, gh#288) — neither is an API-absence bug, so this
+  test method doesn't apply. Shape 2's narrowing was verified with exactly the shape
+  of test this section 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
+  `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 (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.
+
+## 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
+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.
+
+## If a deeper simulation becomes worth the cost
+
+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.