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

package/skills/adia-ssr/evals/audit-report.md

@@ -0,0 +1,63 @@
+# adia-ssr skill audit (FLOOR)
+
+Skill: `packages/plugins/adia-ui-forge/skills/adia-ssr/` · Standards: skill-authoring-standards · Lint: clean
+Verdict: **PASS**
+
+Species: knowledge (`disable-model-invocation: false`, `user-invocable: false`) — sibling in
+shape to `packages/plugins/adia-ui-factory/skills/adia-tokens/`, confirmed.
+
+| ID | Verdict | Severity | Evidence (file:line) | Fix |
+|----|---------|----------|----------------------|-----|
+| R1 Behavior delta | PASS | — | `SKILL.md:67-73` (caveat: don't invent a component-local workaround for gh#284 — deleting it removes the one line steering Claude away from a plausible wrong answer); `SKILL.md:36-38` (gh#288 dependency on gh#284 — deleting it, Claude could treat #288 as independently actionable); `SKILL.md:51` (test-without-linkedom consult row — deleting it loses the exact routing signal to the one file that explains why the repo's default test env can't reproduce SSR bugs) | none |
+| R2 Trigger fidelity | PASS | — | Description (`SKILL.md:3-10`) phrasings "does X work under SSR", "why does X crash/disappear when server-rendered", "is this connect-time read safe" are the literal `should_route_to_ssr: true` phrases in `evals/routing-corpus.json:20,35,90`; fences ("NOT for implementing a fix (adia-author) or consumer host/hydration wiring (adia-host...)") correctly repel `ssr-adversarial-01/02/05` (routing-corpus.json:104-107, 110-114, 130-135) | none |
+| R3 Species/dial agreement | PASS | — | `SKILL.md:11-12` both dials explicit and correct for knowledge species; name `adia-ssr` follows the established local `adia-*` topic-noun convention (matches sibling `adia-tokens`, `adia-a2ui`) rather than the generic `x-patterns` grammar — acceptable under the project's own precedent | none |
+| R4 Register | PASS | — | Load-bearing lines cite exact file:line, PR, and issue numbers rather than describing generically, e.g. `SKILL.md:63-66` ("`UIElement.connectedCallback`... calls `stamp(result, this)`... currently line 194") — verified accurate, see Notes | none |
+| R5 No restatement | PASS | — | No drift-pair found against `component-token-contract.md` / `component-implementation-patterns.md` / AGENTS.md — none cover SSR. Pack explicitly fences out generic web-components-SSR theory (`SKILL.md:97-99`), so it doesn't restate model-general knowledge either | none |
+| R6 Position | MINOR | minor | Body is only ~108 lines (~2,000 tokens, well inside the 5,000-token survival window, so no practical compaction risk) — but structurally, "Deviation doctrine" and "Boundaries" (`SKILL.md:75-99`, gate-shaped content) sit *after* the "Worked example" (`SKILL.md:55-74`), inverted from the "contracts/gates first, examples last" rule | Move Deviation doctrine + Boundaries above the Worked example on next semantic edit; not urgent given total size |
+| R8 Quantities | PASS | — | `127+ primitives`, `24 component/trait/module files`, `12 files` calling `this.internals.*`, `~110-line shim`, dated `2026-07-17`, gh#284-288 — all load-bearing counts are numeric, none vague | none |
+
+R7 (Contracts): N/A — knowledge species, not procedural/command.
+
+## Notes — factual grounding (beyond the R1-R8 checklist, but relevant to a knowledge pack's core promise)
+
+Spot-checked every concrete claim against the actual repo state rather than trusting the pack's
+own self-description:
+
+- `packages/web-components/core/template.js:194` — `export function stamp(result, container)` is
+  exactly where `failure-shapes.md` and the Worked example say it is.
+- `packages/web-components/core/element.js` — `attachInternals` shim (`this.internals = typeof
+  this.attachInternals === 'function' ? this.attachInternals() : NOOP_INTERNALS`),
+  `adoptedStyleSheets` guard (`if (!('adoptedStyleSheets' in document)) return;`), and the
+  `connectedCallback` → `stamp()` call all match `guard-patterns.md` and `failure-shapes.md`
+  verbatim.
+- `packages/web-modules/shell/admin-sidebar/admin-sidebar.js` — `#syncCollapsedFromWidth` (zero-rect
+  `return` before the decision) and `#setupChildResizeObserver` (`typeof ResizeObserver ===
+  'undefined'` guard, deferred correction) match `guard-patterns.md` §3's cited code exactly,
+  including `SNAP_THRESHOLD`.
+- `packages/web-components/core/element.test.js:259` — the `describe('UIElement — SSR
+  browser-API absence (gh#285)'` block matches `test-without-linkedom.md`'s cited delete/try/finally
+  pattern.
+- `git log`: PR #292 (gh#285) and PR #290 (gh#286) both merged 2026-07-17, matching every date
+  cited in `status-ledger.md` and `consumer-workarounds.md`.
+- No `linkedom` in any `package.json` in the tree — confirms `test-without-linkedom.md`'s central
+  claim.
+- Live `gh issue view` for 284-288 today: #284 OPEN, #285 CLOSED, #286 CLOSED, #287 OPEN, #288
+  OPEN — matches `status-ledger.md`'s table exactly, row for row, including the "#287 is
+  unrelated" framing.
+
+Every citable fact in this pack checked out. This is unusually high grounding for a hand-authored
+knowledge pack — worth naming as the standard other `adia-*` knowledge skills should be held to.
+
+## Top 3
+
+1. **Ship as-is.** Zero blocking or major findings; lint clean; every code/issue citation
+   independently verified against the live repo and `gh issue view` — the pack's core promise
+   ("cited to the actual shipped/open code") is actually true today, not just claimed.
+2. **Routing corpus is well-formed and matches its own spec** — 12 trigger / 5 adversarial phrases
+   (29.4% adversarial, spec says ~29%), all 5 reference files covered by `expected_shape`, and the
+   3 adversarial near-misses (gh#287 bundler bug, a2ui pipeline, generic hydration theory) are
+   genuinely hard boundary cases, not straw men.
+3. **One minor, non-blocking structural nit (R6):** the gate-shaped "Deviation doctrine" and
+   "Boundaries" sections trail the "Worked example" instead of leading it. Harmless at this body
+   size (~2K tokens, nowhere near the 5K compaction cutoff) — fix opportunistically on the next
+   semantic edit to this file, not worth a dedicated pass.

package/skills/adia-ssr/evals/routing-corpus.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-ssr routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-ssr (adia-forge plugin). Each phrase declares whether adia-ssr SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
+  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
+  "license": "internal",
+  "scope": "adia-ssr routing — does this phrase activate adia-ssr?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 12,
+    "adversarial_phrases": 5,
+    "task_shapes_covered": "failure-shapes, guard-patterns, status-ledger, test-without-linkedom, consumer-workarounds",
+    "adversarial_fraction": "~29%"
+  },
+
+  "phrases": [
+    {
+      "id": "ssr-trigger-01",
+      "phrase": "why does text-ui render empty when we server-render it with Astro",
+      "should_route_to_ssr": true,
+      "expected_shape": "failure-shapes",
+      "rationale": "Canonical shape-2 symptom (projected-text content loss) — the worked example in SKILL.md."
+    },
+    {
+      "id": "ssr-trigger-02",
+      "phrase": "our SSR pass crashes on attachInternals not being a function",
+      "should_route_to_ssr": true,
+      "expected_shape": "guard-patterns",
+      "rationale": "Directly names the highest-leverage shape-1 crash site the pack documents."
+    },
+    {
+      "id": "ssr-trigger-03",
+      "phrase": "does select-ui work under linkedom",
+      "should_route_to_ssr": true,
+      "expected_shape": "failure-shapes",
+      "rationale": "The pack's core orienting question — 'does X work under SSR'."
+    },
+    {
+      "id": "ssr-trigger-04",
+      "phrase": "admin-sidebar snaps collapsed on every server-rendered page load",
+      "should_route_to_ssr": true,
+      "expected_shape": "failure-shapes",
+      "rationale": "Shape-3 symptom (connect-time measurement treated as confirmed) — the gh#286 precedent."
+    },
+    {
+      "id": "ssr-trigger-05",
+      "phrase": "is gh#284 fixed yet, can we drop the attribute-only SSR registration restriction",
+      "should_route_to_ssr": true,
+      "expected_shape": "status-ledger",
+      "rationale": "Direct status-ledger ask, names the issue and the exact consumer workaround."
+    },
+    {
+      "id": "ssr-trigger-06",
+      "phrase": "how do we test that a new ResizeObserver guard actually works without installing linkedom",
+      "should_route_to_ssr": true,
+      "expected_shape": "test-without-linkedom",
+      "rationale": "Canonical test-methodology ask this pack's most concrete axis exists for."
+    },
+    {
+      "id": "ssr-trigger-07",
+      "phrase": "new ResizeObserver() throws under our DOM-shim SSR environment",
+      "should_route_to_ssr": true,
+      "expected_shape": "guard-patterns",
+      "rationale": "Shape-1 crash, observer-construction variant — guard-patterns §1 shape (a)/(b)/(c)."
+    },
+    {
+      "id": "ssr-trigger-08",
+      "phrase": "table-ui and chart-ui always render empty in our server-rendered HTML even though the data is set",
+      "should_route_to_ssr": true,
+      "expected_shape": "failure-shapes",
+      "rationale": "Shape-4 (property-only components, gh#288), explicitly named as blocked on shape 2."
+    },
+    {
+      "id": "ssr-trigger-09",
+      "phrase": "what's the actual root cause of the SSR content-loss bug, container CEs losing their nested children",
+      "should_route_to_ssr": true,
+      "expected_shape": "failure-shapes",
+      "rationale": "Shape-2 container-CE symptom, the other half of the worked example's shape."
+    },
+    {
+      "id": "ssr-trigger-10",
+      "phrase": "can our app finally delete the 110-line browser-API shim now that 0.8.5 is out",
+      "should_route_to_ssr": true,
+      "expected_shape": "consumer-workarounds",
+      "rationale": "Direct ask about a named consumer workaround's deletability."
+    },
+    {
+      "id": "ssr-trigger-11",
+      "phrase": "is it safe to call getBoundingClientRect() synchronously in connectedCallback",
+      "should_route_to_ssr": true,
+      "expected_shape": "guard-patterns",
+      "rationale": "Shape-3 general-principle ask ('unknown vs confirmed'), independent of any specific component."
+    },
+    {
+      "id": "ssr-trigger-12",
+      "phrase": "document.adoptedStyleSheets is undefined and our component library crashes on import",
+      "should_route_to_ssr": true,
+      "expected_shape": "guard-patterns",
+      "rationale": "Shape-1 crash, the adoptStyles() call site specifically."
+    },
+    {
+      "id": "ssr-adversarial-01",
+      "phrase": "add hydration-aware stamping so connectedCallback stops overwriting existing children",
+      "should_route_to_ssr": false,
+      "expected_alternative": "adia-author",
+      "rationale": "This is IMPLEMENTING the gh#284 fix, not asking whether/why something fails — routes to the builder, not this answers-only pack."
+    },
+    {
+      "id": "ssr-adversarial-02",
+      "phrase": "set up Astro's rendering mode and hydration boundaries for our admin app",
+      "should_route_to_ssr": false,
+      "expected_alternative": "adia-host",
+      "rationale": "Consumer-side host/hydration wiring — explicitly fenced to adia-host in the boundaries section."
+    },
+    {
+      "id": "ssr-adversarial-03",
+      "phrase": "explain how custom element hydration works in general, independent of any specific framework",
+      "should_route_to_ssr": false,
+      "expected_alternative": "general knowledge, no pack",
+      "rationale": "Generic web-components/SSR theory not grounded in THIS repo's own code/issues — explicitly out of scope per the boundaries section."
+    },
+    {
+      "id": "ssr-adversarial-04",
+      "phrase": "the icon registry comes back empty because of a workspace-hoisting import.meta.glob path bug",
+      "should_route_to_ssr": false,
+      "expected_alternative": "adia-author (gh#287, a bundler/dep-optimizer bug, not one of the three SSR lifecycle shapes)",
+      "rationale": "gh#287 is explicitly named in status-ledger.md as unrelated to this pack's failure taxonomy — a near-miss adversarial by design."
+    },
+    {
+      "id": "ssr-adversarial-05",
+      "phrase": "wire up the a2ui generation pipeline to run inside a server-rendered page",
+      "should_route_to_ssr": false,
+      "expected_alternative": "adia-a2ui",
+      "rationale": "A2UI runtime/pipeline concern, not the UIElement lifecycle this pack is scoped to — explicitly fenced in the boundaries section."
+    }
+  ]
+}

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

@@ -0,0 +1,63 @@
+# The consumer's current workarounds — what they look like, why they're fragile
+
+Two real consumers — adiav2's `admin-portal-fe` and `factory-dashboard` — SSR AdiaUI
+via Astro 5 + `custom-elements-ssr` (linkedom). Each open issue names a workaround
+they currently maintain in their OWN app code (not in this framework). Knowing the
+shape of each matters for two reasons: (1) it tells you what "done" looks like — the
+workaround should become deletable once the underlying gh issue closes; (2) it's the
+concrete evidence for WHY each open issue matters, beyond the abstract description.
+
+## The ~110-line browser-API shim (gh#285 — now deletable, unconfirmed)
+
+Before every component module import, the consumer's SSR entry point ran a
+prototype-patching shim: stubbed `attachInternals`, defined four no-op Observer
+classes (`ResizeObserver`/`IntersectionObserver`/`MutationObserver`/`PerformanceObserver`),
+and force-assigned `document.adoptedStyleSheets = []`. Two named fragilities:
+- **Fragile import order** — the shim MUST execute before any component module
+  loads, or the "deep-render pass" crashes anyway. This already broke once in a
+  production bundle (per the issue) — a bundler/tree-shaking change that reordered
+  imports silently reintroduced the crash.
+- **A global patch, not scoped** — patching `HTMLElement.prototype` /
+  `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.
+
+## Attribute-only SSR registration restriction (gh#284 — likely no longer necessary, unconfirmed)
+
+The consumer restricts server-side custom-element registration to components whose
+visible content derives ENTIRELY from attributes — `button-ui text="…"`, `icon-ui
+name="…"`. Every container (`admin-shell`, `admin-sidebar`, `nav-ui`) and every
+projected-text component (`text-ui`, `avatar-ui`, `badge-ui`, and by extension
+anything using `<component>slotted text</component>` markup) must register
+CLIENT-side only, upgrading after first paint.
+
+**Status as of gh#284's narrowing (2026-07-17): this restriction may no longer be
+needed** — every component it names (and every other shipped component with real
+content) currently derives its visible content from properties/attributes only,
+never from light-DOM children, so `stamp()`'s destructive replace never fires
+against real content for any of them (see [`failure-shapes.md`](failure-shapes.md)
+§2 for the empirical survey). This did NOT ship as a `stamp()` fix — it's a
+narrowing based on the CURRENT shape of the component set, backed by a forward
+static audit (`scripts/dev/audit-template-child-conflict.mjs`) that would catch a
+future regression. As with gh#285's shim: don't assume the consumer has actually
+relaxed this restriction without checking the issue thread for their confirmation
+— a consumer removing their own workaround is their change, not something this
+narrowing does automatically. If the consumer's linkedom/`custom-elements-ssr`
+setup surfaces something this repo's own repro didn't (a real second-connect
+timing difference, an app-level component not covered by this framework), that's
+new information worth feeding back into the issue, not something to assume away.
+
+## No workaround exists yet for gh#288 (property-only components)
+
+The consumer's current behavior for `table-ui`/`chart-ui`/`select-ui` with
+programmatic content is simply: render empty in the SSR response, then a per-page
+wiring script does `customElements.whenDefined(...) → getElementById → assign
+properties` after hydration. This is boilerplate the consumer repeats per page, not a
+shim with a specific fragility of its own beyond "structurally excluded from SSR" —
+see [`failure-shapes.md`](failure-shapes.md) §4.

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

@@ -0,0 +1,122 @@
+# SSR failure shapes — symptom → root cause → status
+
+Three distinct root-cause classes have surfaced from real SSR consumers (adiav2's
+`admin-portal-fe` and `factory-dashboard`, server-rendering AdiaUI via Astro 5 +
+`custom-elements-ssr`, which runs on linkedom — a DOM shim with no layout engine and
+missing many browser APIs). A new SSR bug report almost always maps onto one of
+these three; misclassifying it (e.g. treating a measurement-timing bug as a missing-API
+bug) sends the fix to the wrong place. Check symptom against this table first.
+
+## 1 · Browser-only API called unconditionally → crash
+
+**Symptom:** the SSR pass throws — often at construction, before any component-specific
+code runs. Stack trace points at `attachInternals`, `new ResizeObserver(...)`, `new
+IntersectionObserver(...)`, `new MutationObserver(...)`, `new PerformanceObserver(...)`,
+or a write to `document.adoptedStyleSheets`.
+
+**Root cause:** the call site assumes the API exists. linkedom implements none of these —
+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`) and 24 component/trait/module files had
+this shape. 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.
+
+## 2 · `connectedCallback` destructively re-stamps existing DOM → content loss
+
+**Symptom (as originally reported):** the component renders in the SSR HTML response
+as an EMPTY or STRUCTURALLY WRONG tag — not a crash, a silent loss. Two named
+variants:
+- A **container** (`admin-shell`, `admin-sidebar`, `nav-ui`) loses its nested custom-element
+  children — `<nav-item-ui>` inside `<nav-ui>` simply isn't in the response.
+- A **projected-text** leaf (`<text-ui>Adia Admin</text-ui>`, `<avatar-ui>A</avatar-ui>`,
+  `<badge-ui>warning</badge-ui>`) goes out as an empty tag — the authored text is gone.
+
+**Root cause (still real):** `UIElement.connectedCallback` (`packages/web-components/core/element.js`)
+runs `stamp(result, this)` (the `stamp` function in `packages/web-components/core/template.js`,
+currently at line 194) with the OWN template's output — this OVERWRITES the element's
+existing children rather than adopting/patching them. In a real browser this is
+correct and invisible: nothing exists inside the element yet at first connect. Under
+SSR, `connectedCallback` runs a SECOND TIME against the server-parsed DOM (which
+already has real, meaningful children from the HTML response) — the stamp silently
+replaces them.
+
+**Status: NARROWED, downgraded 2026-07-17** (gh#284). Verified against 0.8.4 — the
+mechanism is real (a synthetic repro, a component with a non-null template AND
+projected text, does lose it), but **every named example in the issue currently
+has `static template = () => null`**: `admin-shell`, `admin-sidebar`, `nav-ui`,
+`text-ui`, `badge-ui`, `avatar-ui` all skip `stamp()` entirely (`if (result)
+stamp(result, this)` — `null` never enters the branch). A framework-wide survey
+(150 components) found every component with a NON-null template derives its
+visible content from properties/attributes only (`check-ui`'s `label=`,
+`switch-ui`'s `label=`/`hint=`, `skip-nav`'s `text=`) — never from light-DOM
+children — so the destructive replace, where it does fire, only ever regenerates
+identical, template-owned content. Zero shipped components are exposed to the
+originally-reported symptom right now.
+
+**What shipped instead of a `stamp()` fix:** the two candidate directions the issue
+named (adopt-and-patch, or skip-on-marker) were explicitly rejected as
+disproportionate — "changes the render lifecycle of every primitive in the
+framework (127+), not a mechanical guard sweep" — for a risk with zero current
+instances. Shipped a forward-looking STATIC AUDIT instead:
+`scripts/dev/audit-template-child-conflict.mjs` — flags (critical) any future
+component pairing a non-null `static template` with a yaml `slots.default` entry
+(the container shape), and (advisory) a non-null template paired with a body-text
+usage example (the projected-text shape, no mechanical yaml signal to check). Wired
+into `adia-author`'s structural-gate sequence. This is an operator ruling (not a
+unilateral call) — see gh#284's comment thread for the full reasoning and the
+empirical survey it's based on.
+
+**Current consumer workaround still exists but may be over-conservative:**
+`adiav2`'s SSR component registration is restricted to attribute-only-content
+components (`button-ui text="…"`, `icon-ui name="…"`) — per this narrowing, EVERY
+currently-shipped component (container or leaf) with real content already
+qualifies as attribute/property-driven, so the restriction may no longer be
+necessary for 0.8.4+. Don't assume this without the consumer confirming it via the
+issue thread — see [`consumer-workarounds.md`](consumer-workarounds.md).
+
+## 3 · A connect-time layout MEASUREMENT is meaningless before real layout exists
+
+**Symptom:** a component makes a decision (a boolean state, a mode, a snapped value)
+by synchronously reading `getBoundingClientRect()` (or similar) inside `connected()`,
+and that decision comes out WRONG — not crashed, not empty, just incorrect — in any
+environment where real layout hasn't happened yet. This includes linkedom (no layout
+engine at all — always returns a 0×0 rect) but ALSO a real browser connecting an
+element before its first layout pass (inside a `display:none` ancestor, for instance) —
+SSR is the environment that surfaces it reliably, but the bug is not SSR-specific.
+
+**Root cause:** treating "the rect read 0" as equivalent to "the rect really is 0" —
+they are NOT the same fact. A zero rect from a shim/pre-layout read means "unknown,"
+and a decision derived from "unknown" as if it were "confirmed small" is a category
+error, not a rendering gap.
+
+**Status: FIXED for `admin-sidebar`'s specific instance** (gh#286, PR #290, merged
+2026-07-17) — see [`guard-patterns.md`](guard-patterns.md) §3 for the fix shape
+(treat a zero read as unknown, defer to the component's own `ResizeObserver`'s first
+real tick). **The general pattern is NOT swept framework-wide** — any OTHER component
+that derives a persistent decision from a synchronous connect-time measurement
+carries the same latent bug, undiscovered until someone hits it. If you're
+investigating a "wrong initial state under SSR" report that ISN'T a missing-API crash
+(shape 1) or a content-loss (shape 2), check whether the component reads a rect/size
+synchronously at connect and treat that as the working hypothesis first.
+
+## 4 · Feature gap, not a bug — property-only components can't seed from SSR HTML
+
+**Symptom:** not a bug report at all — a `table-ui`/`chart-ui`/`select-ui` with
+programmatic-only content (`.columns`, `.data`, `.options` set as JS properties)
+renders correctly in the browser but is STRUCTURALLY ABSENT from the SSR HTML response,
+because JS property assignments don't serialize into server-rendered markup. The
+component pops in empty and fills in after a post-hydration wiring script runs.
+
+**Root cause:** no declarative (HTML-serializable) form of the data these components
+need exists yet — property-only content is a deliberate API shape for CONSUMERS with a
+live client, not a gap in any individual component's code.
+
+**Status: OPEN, blocked on shape 2** (gh#288). A JSON-script-child or attribute form
+is proposed but explicitly depends on #284's resolution — reading a declarative payload
+at connect time is pointless if the very next thing `connectedCallback` does is
+overwrite whatever DOM it finds (including a `<script type="application/json">` child)
+with the stamp. Don't attempt #288 in isolation.

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

@@ -0,0 +1,142 @@
+# 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.
+
+## §1 · A browser-only API constructor/method call
+
+**Shape:** `typeof <Global> !== 'undefined'` (for globals: `ResizeObserver`,
+`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
+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
+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
+#setupChildResizeObserver() {
+  this.#childRO = new ResizeObserver((entries) => { ... });
+  this.#childRO.observe(this);
+}
+// guarded:
+if (typeof ResizeObserver !== 'undefined') {
+  this.#childRO = new ResizeObserver((entries) => { ... });
+  this.#childRO.observe(this);
+}
+// disconnectedCallback: this.#childRO?.disconnect();  ← already needs the `?.`
+```
+
+**(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
+setup({ host }) {
+  if (typeof ResizeObserver === 'undefined') return () => {};
+  // ... the rest of the trait, only reached when the API exists
+}
+```
+
+**(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
+const observer = typeof MutationObserver !== 'undefined'
+  ? new MutationObserver((mutations) => { ... })
+  : null;
+// every later use: observer?.observe(...) / bootstrap() no-ops via the same check
+```
+
+**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
+participation is a routine, expected thing for `UIFormElement` subclasses to do).
+Leaving `this.internals` as `undefined` when `attachInternals` doesn't exist would
+just relocate the crash one level deeper, into every one of those 12 consumers' first
+validation call. The actual fix is a frozen no-op object matching the EXACT surface
+those consumers call (grepped, not guessed: `setFormValue`, `setValidity`,
+`checkValidity`, `reportValidity`, `form`, `labels`, `validity`, `validationMessage`,
+`willValidate`):
+```js
+const NOOP_INTERNALS = Object.freeze({
+  setFormValue() {}, setValidity() {},
+  checkValidity() { return true; }, reportValidity() { return true; },
+  get form() { return null; }, get labels() { return []; },
+  get validity() { return {}; }, get validationMessage() { return ''; },
+  get willValidate() { return false; },
+});
+// constructor:
+this.internals = typeof this.attachInternals === 'function'
+  ? this.attachInternals()
+  : NOOP_INTERNALS;
+```
+**When a NEW browser-only API needs the same treatment:** ask "do consumers assume the
+returned object/value is always truthy and call methods on it unconditionally?" If
+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
+needed.
+
+## §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
+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
+conflict shape from being reintroduced, rather than patching the render lifecycle
+every one of the 150 components goes through. **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
+own surgical DOM manipulation, matching `avatar-ui`'s `#imgEl`/`#initialsEl`
+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 `adia-author` before authoring it — that's a real design
+question, not a mechanical fix.
+
+## §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
+watches the same dimension.
+```js
+// 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
+}                                          //   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
+// first REAL tick (post-hydration, or after the display:none ancestor is revealed)
+// resolves what connect-time couldn't:
+#setupChildResizeObserver() {
+  this.#childRO = new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const w = entry.contentBoxSize[0].inlineSize;
+      if (w > 0) this.collapsed = w <= SNAP_THRESHOLD;   // ← the deferred correction
+      // ...existing unrelated logic continues unchanged...
+    }
+  });
+}
+```
+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
+reasons is a maintenance smell, and per §1 above, a NEW observer needs its own
+construction guard anyway.
+
+## 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.

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

@@ -0,0 +1,35 @@
+# SSR support — status ledger
+
+**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`.
+
+| 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 |
+| [#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 | **NARROWED, downgraded 2026-07-17** | `scripts/dev/audit-template-child-conflict.mjs` | Verified against 0.8.4: EVERY component that accepts light-DOM children (nav-ui, admin-shell, admin-sidebar, text-ui, badge-ui, avatar-ui — every example the issue names) has `static template = () => null`, so `stamp()` never runs for them; every component with a non-null template derives content from properties only. The mechanism is still real (a synthetic repro confirms it), but zero shipped components are exposed. Fixing `stamp()`/`connectedCallback` itself was rejected as disproportionate (touches every primitive's render lifecycle for a currently-zero-instance risk) in favor of a static audit gate that catches a FUTURE component reintroducing the conflict shape. Operator ruling, not a unilateral call — see gh#284's comment thread. |
+| [#288](https://github.com/adiahealth/gen-ui-kit/issues/288) | §4 — property-only components can't seed from SSR HTML | **OPEN, blocked on #284's ORIGINAL scope** | — | #284's narrowing doesn't resolve this — #288 is about JS-property-only content (table-ui `.columns`, select-ui `.options`), a different gap from destructive stamping. Still needs its own declarative-data-channel design; don't attempt in isolation. |
+| [#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. |
+
+## 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
+  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 done** = a declarative data channel exists. It no longer strictly depends
+  on #284 shipping a `stamp()`-level fix (there isn't one), but a real design still
+  needs to answer "what happens if a future property-only component's data arrives
+  after a template that already stamped" — don't hand-wave that gap away just
+  because #284 narrowed.
+
+## Re-syncing this ledger
+
+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
+necessary" for a shape that's since re-opened is a false manifest, not a stale detail.