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

package/skills/adia-site-docs/evals/routing-corpus.json

@@ -1,176 +1,38 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-site-docs routing accuracy corpus",
-  "version": "1.0.0",
-  "purpose": "Routing-eval corpus for adia-site-docs (adia-forge plugin). Each phrase declares whether adia-site-docs 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-site-docs routing — does this phrase activate adia-site-docs?",
-
-  "minimums_per_spec": {
-    "trigger_phrases": 16,
-    "adversarial_phrases": 6,
-    "task_shapes_covered": "new-page, review-page, callout-fix, demo-frame-consistency, contrast-token, sibling-boundary",
-    "adversarial_fraction": "27%"
-  },
-
-  "phrases": [
-    {
-      "id": "site-docs-review-01",
-      "phrase": "review this site docs page for consistency",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Canonical review-a-page task shape."
-    },
-    {
-      "id": "site-docs-review-02",
-      "phrase": "does this callout look like plain text to you",
-      "should_route_to_site_docs": true,
-      "expected_shape": "callout-fix",
-      "rationale": "Symptom description matching Defect 2 (fabricated data-alert)."
-    },
-    {
-      "id": "site-docs-review-03",
-      "phrase": "why is the code background not visible on this page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "contrast-token",
-      "rationale": "Symptom description matching Defect 1 (inline-code contrast)."
-    },
-    {
-      "id": "site-docs-new-page-01",
-      "phrase": "add a new pattern page under site/pages/patterns",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Explicit site/pages/patterns path mention."
-    },
-    {
-      "id": "site-docs-new-page-02",
-      "phrase": "author a new getting-started guide page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "getting-started/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-new-page-03",
-      "phrase": "write a new architecture explainer page for the docs site",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "architecture/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-new-page-04",
-      "phrase": "create a reference page documenting the MCP tools",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "reference/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-demo-frame-01",
-      "phrase": "this demo page needs a tamed static frame like the other pattern pages",
-      "should_route_to_site_docs": true,
-      "expected_shape": "demo-frame-consistency",
-      "rationale": "Matches the .demo-frame consolidation rule."
-    },
-    {
-      "id": "site-docs-demo-frame-02",
-      "phrase": "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
-      "should_route_to_site_docs": true,
-      "expected_shape": "demo-frame-consistency",
-      "rationale": "Direct match on rule 3 (reuse .demo-frame)."
-    },
-    {
-      "id": "site-docs-review-04",
-      "phrase": "is this site page consistent with our authoring conventions",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Direct convention-compliance ask."
-    },
-    {
-      "id": "site-docs-review-05",
-      "phrase": "audit site/pages/guides for the same callout bug we found elsewhere",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Explicit guides/ path + defect-class reference."
-    },
-    {
-      "id": "site-docs-callout-01",
-      "phrase": "this warning box on the docs page has no background at all",
-      "should_route_to_site_docs": true,
-      "expected_shape": "callout-fix",
-      "rationale": "Symptom description matching the fabricated data-alert defect."
-    },
-    {
-      "id": "site-docs-new-page-05",
-      "phrase": "what's the shared skeleton every site docs page should follow",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Direct ask about the template decomposition this skill carries."
-    },
-    {
-      "id": "site-docs-contrast-01",
-      "phrase": "what token should a new chip-like surface use to stay readable against the page background",
-      "should_route_to_site_docs": true,
-      "expected_shape": "contrast-token",
-      "rationale": "Direct match on rule 1 (--a-canvas-well-strong)."
-    },
-    {
-      "id": "site-docs-review-06",
-      "phrase": "check the patterns pages for any other unstyled data attributes like data-alert",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Direct defect-class sweep request."
-    },
-    {
-      "id": "site-docs-new-page-06",
-      "phrase": "scaffold a new getting-started/theming-dark-mode.html page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Explicit new-file-under-owned-category shape."
-    },
-
-    {
-      "id": "site-docs-adversarial-01",
-      "phrase": "review this component's own demo gallery in its .examples.html file",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "packages/web-components/components/*/*.examples.html is adia-author's remit, not this skill's."
-    },
-    {
-      "id": "site-docs-adversarial-02",
-      "phrase": "fix this gen-ui training exemplar page under site/pages/examples",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "site/pages/examples/** is the pure-primitive-composition training-harvest surface governed by composition-and-examples.md + adia-a2ui, explicitly fenced out."
-    },
-    {
-      "id": "site-docs-adversarial-03",
-      "phrase": "tune the zettel retrieval threshold for the chunk corpus",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "A2UI pipeline internals belong to adia-a2ui, unrelated to site/pages authoring."
-    },
-    {
-      "id": "site-docs-adversarial-04",
-      "phrase": "add a new prop to the button-ui primitive",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Primitive authoring is adia-author's remit."
-    },
-    {
-      "id": "site-docs-adversarial-05",
-      "phrase": "cut the next npm release for the 9 @adia-ai packages",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Release engineering is adia-release's remit, unrelated to docs-page authoring."
-    },
-    {
-      "id": "site-docs-adversarial-06",
-      "phrase": "deploy the docs site to ui-kit.exe.xyz",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Deploy operations are adia-deploy's remit; this skill authors content, it doesn't ship it."
-    }
+  "positives": [
+    "review this site docs page for consistency",
+    "does this callout look like plain text to you",
+    "why is the code background not visible on this page",
+    "add a new pattern page under site/pages/patterns",
+    "author a new getting-started guide page",
+    "write a new architecture explainer page for the docs site",
+    "create a reference page documenting the MCP tools",
+    "this demo page needs a tamed static frame like the other pattern pages",
+    "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
+    "is this site page consistent with our authoring conventions",
+    "audit site/pages/guides for the same callout bug we found elsewhere",
+    "this warning box on the docs page has no background at all",
+    "what's the shared skeleton every site docs page should follow",
+    "what token should a new chip-like surface use to stay readable against the page background",
+    "check the patterns pages for any other unstyled data attributes like data-alert",
+    "scaffold a new getting-started/theming-dark-mode.html page"
   ],
-
-  "evaluator_notes": "Adversarial phrases 1-2 specifically test the two hardest-to-distinguish fences (component .examples.html vs site/pages/patterns/*.html; site/pages/examples/** vs site/pages/{architecture,getting-started,guides,patterns,reference}/**) — both surfaces are literally *.html under similar-looking paths, so the description must lean on the explicit path lists, not just 'site pages' as a phrase."
+  "negatives": [
+    "review this component's own demo gallery in its .examples.html file",
+    "fix this gen-ui training exemplar page under site/pages/examples",
+    "tune the zettel retrieval threshold for the chunk corpus",
+    "add a new prop to the button-ui primitive",
+    "cut the next npm release for the 9 @adia-ai packages",
+    "deploy the docs site to ui-kit.exe.xyz",
+    "fix this gen-ui training exemplar page",
+    "add a demo to the patterns page for card-ui"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.733,
+    "precision": 0.786,
+    "recall": 0.688,
+    "exit_code": 0
+  }
 }

package/skills/adia-ssr/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: adia-ssr
+description: >-
+  Answers why an AdiaUI component crashes, drops content, or renders wrong
+  under SSR (linkedom/Astro consumers) — the four known failure shapes,
+  what's fixed vs open, how to test without a linkedom install. Use when
+  asked "does this work under SSR", why a component crashes on
+  attachInternals/ResizeObserver/adoptedStyleSheets under a DOM shim, why
+  table-ui/chart-ui/select-ui or a container CE renders empty or loses its
+  nested children when server-rendered, whether it's safe to call
+  getBoundingClientRect() synchronously in connectedCallback, or whether a
+  browser-API shim/workaround can finally be deleted after a fix ships.
+  ANSWERS only. NOT for implementing a fix (adia-author) or consumer
+  host/hydration wiring (adia-host, adia-ui-factory plugin).
+disable-model-invocation: false
+user-invocable: false
+---
+
+# adia-ssr — does it work under SSR, and why not if it doesn't
+
+Two real consumers (adiav2's `admin-portal-fe` and `factory-dashboard`) server-render
+AdiaUI's light-DOM components via Astro 5 + `custom-elements-ssr`, which runs on
+linkedom — a DOM shim with no layout engine and missing browser APIs the framework's
+base class assumes exist. Every SSR bug that's surfaced maps onto one of four root-cause
+shapes; misclassifying a new report against the wrong shape sends the investigation
+to the wrong fix (or worse, invents a redundant one). This pack answers "which shape is
+this" and "what's the state of each shape's fix" — it never carries the fix itself.
+
+## The four shapes, in one line each
+
+1. **A browser-only API is called unconditionally → crash.** `attachInternals`,
+   the four Observer constructors, `document.adoptedStyleSheets`. **Fixed** (gh#285).
+2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.**
+   The ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284) — zero
+   shipped components currently pair a non-null template with real light-DOM
+   content, so this specific mechanism isn't exposed today; a forward audit catches
+   a future regression. **Do not stop here** — see shape 2b, the actual live bug
+   found investigating the same report.
+2b. **Custom-element upgrade doesn't replay `attributeChangedCallback` for
+   pre-existing attributes → reflected properties stuck at their class default.**
+   The REAL mechanism behind gh#284's reported symptom. happy-dom and (by strong
+   inference) linkedom both skip the custom-elements spec's upgrade-time
+   attribute replay (§4.13.5 step 6); any `reflect: true` property seeded only
+   from pre-parsed/SSR HTML never initializes. **Fixed 2026-07-18** (gh#284,
+   PR #309) — `connectedCallback` now re-syncs every declared property from its
+   live attribute before `connected()` runs.
+3. **A connect-time layout measurement is treated as confirmed, not unknown.** A zero
+   rect (shim, or real pre-layout connect) drives a wrong persistent decision.
+   **Fixed for one component** (gh#286); the general pattern is unswept.
+
+A fifth item, **property-only components can't seed initial state from SSR HTML**
+(gh#288), was a feature gap — **CLOSED 2026-07-18**. It was never actually blocked
+on shape 2/2b (table-ui/chart-ui/select-ui all use `static template = () => null`
+too), and the real scope was narrower than filed: `select-ui` already declares
+options via native `<option>` children, `chart-ui` already hydrates `.data` from a
+JSON `data="[…]"` attribute — only `table-ui`'s `.data` had no declarative form,
+now fixed the same way.
+
+Full symptom → root-cause → status detail, cited to the actual shipped/open code:
+[`references/failure-shapes.md`](references/failure-shapes.md).
+
+## Consult table
+
+| Ask | Answer from |
+| --- | --- |
+| "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2 — shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
+| "why does this crash / throw at construction under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 |
+| "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3 — the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
+| "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md) — re-verify against `gh issue view` before trusting it, it drifts |
+| "how do I test an SSR gap — we have no linkedom installed" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — the delete/try/finally pattern, and what it does NOT prove |
+| "what's the consumer's current workaround, and can they drop it yet" | [`consumer-workarounds.md`](references/consumer-workarounds.md) |
+| "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4 — shape 5, CLOSED (table-ui's `data="[…]"` attribute); check whether the reporting component is registered server-side first if it still reproduces |
+
+## Deviation doctrine
+
+Every fix pattern this pack cites ([`guard-patterns.md`](references/guard-patterns.md))
+carries the reasoning for why it looks the way it does — the no-op `ElementInternals`
+shim exists because leaving the field `undefined` would relocate a crash, not remove
+it; deletion-based testing exists because this repo has no `linkedom` devDependency.
+If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
+new pattern. Route it through `adia-author` — don't force-fit the nearest existing
+shape.
+
+## Boundaries
+
+- **Implementing any fix — new or matching an existing pattern.** Route to
+  `adia-author`. This pack orients and cites; it never edits
+  `packages/web-components/core/` or any component source.
+- **Consumer-side SSR/hydration host wiring** (an app's own Astro/Next config, which
+  rendering mode to pick, how to structure the hydration boundary). Route to
+  `adia-host` (adia-ui-factory plugin) — this pack answers whether the FRAMEWORK's own
+  components are SSR-safe, not how a consumer app should be structured around them.
+- **A2UI runtime/generation-pipeline SSR concerns** (if any surface later). Route to
+  `adia-a2ui` — this pack is scoped to `UIElement`'s own lifecycle and the
+  component/trait/module layer, not the generative pipeline.
+- **Not a general web-components-SSR tutorial.** Every claim here is cited to this
+  specific framework's actual code, issues, and PRs — general SSR/custom-elements
+  theory that isn't grounded in this repo's own history doesn't belong in this pack.
+
+## Worked example — the answer contract
+
+**Ask:** "`<text-ui>Adia Admin</text-ui>` renders as an empty tag in our SSR output —
+is this a known issue?"
+
+**Answer:** It matches shape 2's SYMPTOM (`connectedCallback` destructively
+re-stamping existing DOM), but shape 2 was narrowed on 2026-07-17 — verify against
+the CURRENT code before reusing the old answer, because this is exactly the case it
+no longer covers. `text-ui`'s `static template` (`packages/web-components/components/text/text.class.js`)
+is `() => null` — `connectedCallback`'s `if (result) stamp(result, this)` never
+enters the branch, so `stamp()` never touches `<text-ui>`'s children at all. This
+component isn't exposed to shape 2; something else is dropping the text — check
+whether `text-ui` is even registered server-side (a different, structural gap: is
+the tag defined before the SSR pass runs?), or whether another mutation (a parent
+re-render, `innerHTML` elsewhere) is clearing it. **The general lesson, not just
+this one component:** before answering "yes, known issue, shape 2" for ANY new
+report, grep the component's own `static template` — if it's the literal
+`() => null`, shape 2 cannot be the cause, no matter how closely the symptom
+matches the old description. [`failure-shapes.md`](references/failure-shapes.md)
+§2 has the full survey (150 components checked) and cites exactly why every
+current children-accepting component is unaffected.
+
+## Corpus of record
+
+Routing-eval corpus: [`evals/routing-corpus.json`](evals/routing-corpus.json).
+This pack is hand-authored from verified session work (not a research-wave corpus) —
+re-sync it per [`status-ledger.md`](references/status-ledger.md)'s own instructions
+whenever an issue referenced here changes state, rather than letting the ledger and
+reality drift apart silently.

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,34 @@
+{
+  "positives": [
+    "why does text-ui render empty when we server-render it with Astro",
+    "our SSR pass crashes on attachInternals not being a function",
+    "does select-ui work under linkedom",
+    "admin-sidebar snaps collapsed on every server-rendered page load",
+    "is gh#284 fixed yet, can we drop the attribute-only SSR registration restriction",
+    "how do we test that a new ResizeObserver guard actually works without installing linkedom",
+    "new ResizeObserver() throws under our DOM-shim SSR environment",
+    "table-ui and chart-ui always render empty in our server-rendered HTML even though the data is set",
+    "what's the actual root cause of the SSR content-loss bug, container CEs losing their nested children",
+    "can our app finally delete the 110-line browser-API shim now that 0.8.5 is out",
+    "is it safe to call getBoundingClientRect() synchronously in connectedCallback",
+    "document.adoptedStyleSheets is undefined and our component library crashes on import"
+  ],
+  "negatives": [
+    "add hydration-aware stamping so connectedCallback stops overwriting existing children",
+    "set up Astro's rendering mode and hydration boundaries for our admin app",
+    "explain how custom element hydration works in general, independent of any specific framework",
+    "the icon registry comes back empty because of a workspace-hoisting import.meta.glob path bug",
+    "wire up the a2ui generation pipeline to run inside a server-rendered page",
+    "add a new primitive to the component catalog",
+    "compose the billing settings screen from the catalog",
+    "deploy the latest build to ui-kit.exe.xyz"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.957,
+    "precision": 1.0,
+    "recall": 0.917,
+    "exit_code": 0
+  }
+}

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

@@ -0,0 +1,81 @@
+# 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): the STAMP() reason for this
+restriction is gone** — 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.
+
+**UPDATE 2026-07-18 — but there WAS a second, independent, real reason this
+restriction was justified, now also fixed.** Every component this restriction
+names is attribute/property-driven — and until PR #309, attribute-driven
+content was ITSELF broken under a late/SSR upgrade (see `failure-shapes.md` §2's
+"UPDATE 2026-07-18" and `guard-patterns.md` §2b): `attributeChangedCallback`
+never replayed for pre-existing attributes on upgrade, so `<nav-item-ui
+text="Profile">` rendered with an empty label regardless of the stamp()
+question. That's now fixed at the framework level (`element.js`
+`connectedCallback`). So as of the version carrying PR #309, both reasons this
+restriction existed are addressed — not just the one gh#284 originally named.
+
+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.
+
+## gh#288 (property-only components) — CLOSED 2026-07-18, workaround droppable
+
+The consumer's PRE-fix behavior for `table-ui`/`chart-ui`/`select-ui` with
+programmatic content was: render empty in the SSR response, then a per-page
+wiring script does `customElements.whenDefined(...) → getElementById → assign
+properties` after hydration. As of the fix, that boilerplate is droppable for all
+three — `select-ui` via native `<option>` children (already worked, pre-existing),
+`chart-ui` via a `data="[…]"` JSON attribute (already worked, pre-existing),
+`table-ui` via the same `data="[…]"` attribute (new) plus `<col-def>` children for
+columns (pre-existing). Don't assume the consumer has removed the wiring script
+without their confirmation — see [`failure-shapes.md`](failure-shapes.md) §4 for
+the full narrative.