@adia-ai/adia-ui-forge 0.8.43 → 0.8.44

package/skills/primitive-authoring/references/code-style.md

@@ -1,5 +1,30 @@
 # AdiaUI code style — best practices
 
+## First principles (SKILL.md's own summary, expanded)
+
+1. **Invariants are enforced by the next author, not the linter.** A component
+   that violates the contract silently teaches the next agent the violation is
+   acceptable. Write as if your component is the reference the next one is
+   patterned after — because it will be.
+2. **Default behavior is the absent attribute.** `<component-ui>` with no
+   attributes does the expected default thing; every Boolean prop defaults to
+   `false`. If the expected default is "on," the prop name is wrong — flip it
+   (`closable` → `permanent`, `animate` → `static`).
+3. **Variants change tokens; modes change layout.** A variant body contains
+   only `--component-*: var(...)` lines — no `padding`, `display`, `position`,
+   `width`, `height`, `gap`, `flex`, `grid`, `overflow`, `border-radius`.
+   Layout-changing attributes are modes and require a Sanctioned Mode
+   Attributes entry in the contract doc.
+4. **Symmetric lifecycle or it's a leak.** Every listener added in
+   `connected()` is removed in `disconnected()`; every timer cleared, observer
+   disconnected, cached ref nulled. Handlers are stable `#field` arrows so
+   `removeEventListener` can match — inline arrows bit three components in one
+   audit cycle.
+5. **Component tokens consume L3, not L2.** Alias from the role×state matrix
+   (`--a-primary-bg-hover`), never the family base (`--a-primary`) — bypassing
+   L3 strands the component outside theme / dark-mode / contrast cascades
+   silently.
+
 Modern AdiaUI is small, declarative, and token-driven. Most of the "bugs" agents write are bugs _against the conventions_ — bare `<div>`s where `col-ui` belongs, raw `<input>` where `input-ui` belongs, hex colors where tokens belong. The conventions are not stylistic preferences; each one corresponds to a working feature (theme switching, density modes, form association, focus rings) that breaks silently when the convention is violated.
 
 When in doubt: look up the catalog (the `lookup_component` MCP tool, or the adia-factory plugin's composition skill), pick the existing primitive, wire through tokens.
@@ -221,6 +246,19 @@ Default behavior is the absent attribute. Attributes exist to opt OUT or carry a
 
 State-bearing Booleans must `reflect: true` so CSS can match `:scope[disabled]`, `:scope[selected]`, etc. Without reflection, hover / active / selected styles break silently.
 
+[verified 2026-08-19] **The literal string `"false"` is not "presence = true"
+here.** ADR-0075 special-cases `parseAttr` for `Boolean`-typed props so the
+literal attribute string `"false"` parses to JS `false`, not `true` —
+deviating from strict HTML semantics on purpose, to match this repo's own
+A2UI transpiler (which already special-cased it defensively) and the
+authoring intuition both human and generated markup default to. Writing
+`show-label="false"` on a `default: true` Boolean prop does what it looks
+like it does. (`default: true` is itself the rare, ratified exception to
+this section's "every Boolean defaults to `false`" rule — ADR-0063's
+stamped-attribute mechanism, gh#961 — not a license to skip the flip rule
+above for a new prop.) See [api-contract.md](api-contract.md)'s field-rules
+section for the full rule and shipped blast radius (`core/element.js:93-94`).
+
 Native DOM accessors (`textContent`, `innerHTML`) get clobbered if declared in `static properties` — `installProps` overrides the native setter and `el.textContent = ''` becomes a signal write, not a child-wipe. Don't declare those names in `static properties`.
 
 ## Symmetric lifecycle

package/skills/primitive-authoring/references/token-contract.md

@@ -142,7 +142,7 @@ mechanics; never work from this summary alone):
   granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
 
 Beyond the global grammar, ADR-0063
-(`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies six
+(`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven
 CROSS-SIBLING conventions for component-local attribute naming — the axis
 ADR-0053/0054 don't cover. Any new attribute follows these:
 
@@ -179,12 +179,72 @@ ADR-0053/0054 don't cover. Any new attribute follows these:
 - **`-picker` is reserved for the outer trigger+popover form-associated
   composite** — never the inline substrate it composes. `color-picker-ui`
   (the inline substrate) renames to `color-area-ui`.
+- **[verified 2026-08-19] Preset-boolean-vs-alias-retirement boundary**
+  (ADR-0076): a boolean attribute that is additive sugar over several
+  existing granular `no-*` opt-outs — `table-toolbar-ui[chrome-only]`
+  equivalent to setting all four of `no-filter`, `no-sort`, `no-columns`,
+  `no-search` — is NOT an ADR-0063-style alias-retirement case (the
+  granular attributes aren't duplicate spellings of one concept the way
+  `alert[dismissible]`/`[closable]` were; a consumer may legitimately want
+  a subset off, a combination the preset alone can't express), so the
+  granular attributes stay shipped, independently-addressable API with no
+  deprecation. The preset's precedence is **pure, absolute OR — never a
+  tri-state**: while set, all covered controls are off, full stop, with no
+  partial re-enable via clearing an individual `no-*` while the preset
+  remains set (ADR-0076: "`no-*` attributes are presence-based booleans …
+  meaning 'presence forces off' is expressible but 'absence means defer to
+  [the preset]'s own OR' is not without a tri-state amendment"). A second
+  auto-snap-enum precedent alongside ADR-0074's chart `ratio` lands here
+  too: `table-toolbar-ui[stage]` (`full | search-tight | icon-only |
+  overflow`) — unset auto-snaps via `@container` queries against studied
+  breakpoints, an explicit value pins and overrides the query, no
+  interpolation between stages.
 
 The renames above have LANDED: dual-read compat shims shipped via gh#1563,
 and the breaking cut removed the old names in 0.8.43 (gh#1617). The new
 spellings are the sole ones — a yaml or demo still showing an old name is
 stale and should be fixed.
 
+## Disabled-state tokens
+
+[verified 2026-08-19] ADR-0073 ratifies the standing convention for any
+control supporting the `disabled` boolean attribute/state:
+
+- **Shared bg role, container-low tier.** `--a-ui-bg-disabled`
+  (`styles/colors/semantics/features.css`) resolves to
+  `var(--md-sys-color-neutral-container-low)` — the same 10%-tint role
+  `--a-bg-hover` / `--a-bg-muted` ride for REST-state de-emphasis. A
+  component's own `--<component>-bg-disabled` indirection aliases this
+  shared role — never a raw color, never a per-family `*-container-low`
+  variant (none exists in the disabled path).
+- **`[state][disabled]` specificity override for checked/selected fills.**
+  A `[checked]`/`[selected]` selector outranks a plain `[disabled]` rule on
+  CSS specificity (2 attribute selectors beat 1), so a checked+disabled
+  control silently keeps its active-state fill unless the component adds an
+  explicit higher-specificity override — `[checked][disabled]` /
+  `[selected][disabled]` — routed through its own
+  `--<component>-...-checked-disabled` (or `-selected-disabled`) custom
+  prop, itself aliasing `--a-ui-bg-disabled`.
+- **Reduced-contrast disabled border — the `--input-border-disabled`
+  pattern.** Any control that renders a border when disabled adds
+  `--<component>-border-disabled: var(--a-ui-border-disabled)`, applied as
+  `border-color` under `:scope[disabled]`.
+
+Quoting ADR-0073's Decision 5: "a control supporting `disabled` uses the
+shared, single neutral `--md-sys-color-neutral-container-low` role for
+background … always through a `--<component>-bg-disabled` … indirection
+aliasing `--a-ui-bg-disabled` … uses the reduced-contrast
+`--input-border-disabled` pattern … for any border it renders when disabled
+… overrides any checked/selected state fill at `[state][disabled]`
+specificity rather than relying on `[disabled]` alone."
+
+The re-runnable check is `scripts/audit/audit-disabled-fill-tokens.mjs`
+(`check:disabled-fill-audit`, advisory) — it fails any `[disabled]`-scoped
+`background`/`background-color` that doesn't resolve through a
+disabled-aware indirection.
+
+Source: [ADR-0073](../../../../../../docs/ops/adr/adr-0073-disabled-state-container-low-token-convention.md).
+
 ## When to update this reference
 
 If you add a new token category (like `--a-chrome-*` was added), update both this file and `.claude/docs/specs/component-token-contract.md`. The spec doc is the live source of truth; this file is the practitioner's checklist.

package/skills/site-deployment/SKILL.md

@@ -28,13 +28,11 @@ directives are findings.
 
 ## Platform contract (the non-obvious bits)
 
-- The app binds **`:8000` plain HTTP**; the exe.dev edge terminates TLS on
-  `<host>.exe.xyz` and forwards to VM `:8000`. Nothing listening ⇒ exe.dev
-  serves its "**Port 8000 unbound.**" error page (its nginx hint is just an
-  example — anything binding :8000 works). Don't bind :443 on the VM.
-- Default user **`exedev`** (uid 1000, in `sudo` + `docker`); service
-  processes run as it. Preinstalled: `git`, `rsync`, `docker`. NOT
-  preinstalled: `caddy`, `node`, `nginx` (apt + NodeSource).
+- The app binds **`:8000` plain HTTP**; the exe.dev edge terminates TLS and
+  forwards to VM `:8000`. Nothing listening ⇒ "**Port 8000 unbound.**"
+  Don't bind :443 on the VM.
+- Default user **`exedev`** (uid 1000, `sudo` + `docker`); service runs as
+  it. Preinstalled: `git`, `rsync`, `docker`. NOT: `caddy`, `node`, `nginx`.
 - **`127.0.0.1:9999` runs `shelley`** — exe.dev's internal agent,
   localhost-only. Leave it running; don't bind 9999.
 - Disk: 25 GB on `/`. New VMs ship RSA-2048-only host keys — verify the
@@ -47,18 +45,15 @@ Standard layout: `/srv/<app>/dist/` webroot (exedev-owned) ·
 
 ## Deploy-freshness cadence — a lockstep cut is not a site deploy
 
-`package-release` cutting and publishing the lockstep version (the roster in
-`scripts/package-paths.mjs` is the live count) does
-**not** itself update `ui-kit.exe.xyz` — that only happens on a `site-v*` tag
-push (see below). Any lockstep cut that changes a package the site actually
-serves — `web-components`, `web-modules`, `llm`, or `a2ui/*` — **owes a site
-deploy in the same release cycle**, or an explicit operator decision to skip
-it, recorded in the release notes (who decided, why). "The release finished"
-is not evidence the site is current: the v0.8.x window is the proof case — a
-lockstep cut touching served packages landed with no matching `site-v*` tag,
-and the deployed site sat a week behind npm before anyone noticed. When
-handing off from a release, check whether the cut touched a served package
-and close the loop before calling the cycle done.
+`package-release` cutting and publishing does **not** itself update
+`ui-kit.exe.xyz` — only a `site-v*` tag push does. Any lockstep cut that
+changes a package the site actually serves (`web-components`,
+`web-modules`, `llm`, `a2ui/*`) **owes a site deploy in the same release
+cycle**, or an explicit, recorded operator decision to skip it. "The
+release finished" is not evidence the site is current (the v0.8.x window:
+a served-package cut landed with no matching tag, site sat a week stale).
+When handing off from a release, check whether the cut touched a served
+package before calling the cycle done.
 
 ## Current deployments
 
@@ -72,60 +67,22 @@ VM artifacts (Caddyfile, unit, env example) live in repo `deploy/`.
 
 **Never run `npm run deploy:site` from a local shell.** Push a tag matching
 `site-v*` (or run the workflow via `workflow_dispatch`) — `deploy-site.yml`
-builds, dry-runs, and (once the `production-site` GitHub Environment has
-required reviewers configured — a one-time repo-settings step, Settings →
-Environments) waits for a human to read the dry-run's delete summary in the
-job before the destructive `deploy` job runs. The hardened sequence below
-is what the workflow automates; it's kept here as the reference for what
-the workflow does and as a manual fallback if CI itself is unavailable.
-
-`npm run deploy:site` still exists locally (`build:site` + `rsync -az
---delete dist/ → /srv/adia-ui/dist/`) for that fallback case only. It is
-destructive (a 2026-06-08 manual run deleted 3,572 files) — every step
-below is incident-earned; the reference carries the full commands and the
-delete-adjudication classes.
-
-1. Build from clean, fully-merged `main`. In a fresh worktree,
-   `npm run build -w @adia-ai/llm` runs **before** `build:site` — llm compiles
-   at publish time and its outputs are gitignored, so without it
-   `/packages/llm/core/index.js` 404s and component registration breaks site-wide
-   (found live 2026-06-09).
-2. Dry-run `rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/'`
-   and bucket **every** `*deleting` line into a known-safe class; any
-   unexplained served-content delete aborts the deploy. The exclude protects
-   prod-only runtime-written files (feedback logs wiped 2026-06-10).
-3. Snapshot prod: `cp -al /srv/<app>/dist /srv/<app>/dist.bak-<date>`
-   (hardlink farm — instant, and the only rollback).
-4. Real rsync — the dry-run minus `-n`, SAME excludes, and the SAME BYTES:
-   both jobs rsync the artifact-round-tripped tree, and the deploy job aborts
-   if its tree's sha256 fingerprint differs from the one whose delete summary
-   was approved (gh#425 — the dry-run used to read the build job's own
-   `dist/`, so the v0.8.14 summary listed 3,128 deletions the real send never
-   performed; an over-reporting summary trains reviewers to approve past scary
-   numbers, and the same gap can under-report).
-5. Verify a fixture **file** that only exists in the new build, then
-   render-check a `/site/components/*` page headlessly (SPA returns 200 shell
-   for any route; file presence alone misses the llm-404 class).
-6. On verify failure: `rm -rf dist && mv dist.bak-<date> dist`. Keep the
-   snapshot until the deploy is confirmed good.
+builds, dry-runs, and waits for a human to read the delete summary before
+the destructive `deploy` job runs. `npm run deploy:site` still exists
+locally for CI-unavailable fallback only, and is destructive (a 2026-06-08
+manual run deleted 3,572 files). The full step-by-step hardened sequence
+(llm-build-first gotcha, delete-adjudication classes, snapshot, verified
+rsync, fixture+render verify, rollback) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s "Hardened
+`--delete` deploy sequence" — every step there is incident-earned; read it
+before running the fallback by hand.
 
 If `server.js` changed: rsync it, then `sudo systemctl restart <app>`.
 
-### One-time CI setup for `ui-kit.exe.xyz`
-
-- **Repo secret `SITE_DEPLOY_SSH_KEY`** — done. An ed25519 keypair generated
-  *by a human*, never by the agent (Hard gate 1). Public half goes in the
-  VM's `~exedev/.ssh/authorized_keys`; private half goes in
-  Settings → Secrets and variables → Actions, pasted directly — it should
-  never appear in an agent's Bash context or a commit.
-- **Environment `production-site` reviewer gate — CONFIGURED** (verified
-  live 2026-08-11, `gh api repos/<org>/<repo>/environments`:
-  `protection_rules` carries `required_reviewers`). The `deploy` job in
-  `deploy-site.yml` therefore blocks on a human approval after its dry-run
-  job — the delete-adjudication gate this skill's hardened-deploy design
-  assumes. Changing the reviewer set is operator-only (repo Settings →
-  Environments → `production-site`) — no agent can configure it. Re-check
-  the API output before trusting this line; it drifts with repo settings.
+One-time CI setup for `ui-kit.exe.xyz` (the deploy SSH key, the
+`production-site` reviewer gate) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s own section by
+that name.
 
 ## Other playbooks (reference §-anchors)
 
@@ -161,24 +118,9 @@ rollback state:    not-needed | rolled-back — <if rolled back, what triggered
 verdict:           shipped | held — <one line>
 ```
 
-Filled example (a real cut, `gh run view 29586391343`):
-
-```text
-Deploy Record
-tag / run id:      site-v4 (workflow run 29586391343, 2026-07-17T14:03:15Z)
-dry-run deletes:   see the run's dry-run job log for the class breakdown
-fixture verified:  pass — CI's post-deploy verify step, run marked success
-render verified:   pass — CI's post-deploy verify step, run marked success
-snapshot:          CI pre-deploy hardlink step (deploy-site.yml)
-rollback state:    not-needed
-verdict:           shipped
-```
-
-This example cites the run URL rather than restating its log inline — the
-record's job is to point at the evidence, not transcribe it; re-derive the
-dry-run/fixture/render lines from `gh run view <id> --log` if the detail is
-ever needed, don't assume this filled example's prose stays current with a
-run that already happened.
+A filled worked example (a real cut) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s own "Deploy Record"
+section.
 
 ## Hard gates
 

package/skills/site-deployment/references/deploy-playbooks.md

@@ -97,6 +97,22 @@ sudo vim /etc/<app>.env
 sudo systemctl restart <app>
 ```
 
+## One-time CI setup for `ui-kit.exe.xyz`
+
+- **Repo secret `SITE_DEPLOY_SSH_KEY`** — done. An ed25519 keypair generated
+  *by a human*, never by the agent (Hard gate 1). Public half goes in the
+  VM's `~exedev/.ssh/authorized_keys`; private half goes in
+  Settings → Secrets and variables → Actions, pasted directly — it should
+  never appear in an agent's Bash context or a commit.
+- **Environment `production-site` reviewer gate — CONFIGURED** (verified
+  live 2026-08-11, `gh api repos/<org>/<repo>/environments`:
+  `protection_rules` carries `required_reviewers`). The `deploy` job in
+  `deploy-site.yml` therefore blocks on a human approval after its dry-run
+  job — the delete-adjudication gate this skill's hardened-deploy design
+  assumes. Changing the reviewer set is operator-only (repo Settings →
+  Environments → `production-site`) — no agent can configure it. Re-check
+  the API output before trusting this line; it drifts with repo settings.
+
 ## Playbook: deploy an update
 
 **Push a tag matching `site-v*`** (or trigger `.github/workflows/deploy-site.yml`
@@ -282,3 +298,25 @@ Add new hosts here as they come online.
 
 Release engineering (`package-release`) builds and publishes artifacts; this
 playbook owns the deploy step that pushes them to the VM.
+
+## Deploy Record — a filled example
+
+The schema lives in SKILL.md's own "The Deploy Record" section; this is a
+worked example (a real cut, `gh run view 29586391343`):
+
+```text
+Deploy Record
+tag / run id:      site-v4 (workflow run 29586391343, 2026-07-17T14:03:15Z)
+dry-run deletes:   see the run's dry-run job log for the class breakdown
+fixture verified:  pass — CI's post-deploy verify step, run marked success
+render verified:   pass — CI's post-deploy verify step, run marked success
+snapshot:          CI pre-deploy hardlink step (deploy-site.yml)
+rollback state:    not-needed
+verdict:           shipped
+```
+
+This example cites the run URL rather than restating its log inline — the
+record's job is to point at the evidence, not transcribe it; re-derive the
+dry-run/fixture/render lines from `gh run view <id> --log` if the detail is
+ever needed, don't assume this filled example's prose stays current with a
+run that already happened.

package/skills/ssr-compatibility/SKILL.md

@@ -2,17 +2,16 @@
 name: ssr-compatibility
 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 prove a fix under the linkedom shim gate. Use when
-  asked "does this work under SSR", why a component crashes on
-  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof Node`
-  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 (primitive-authoring) or consumer
-  host/hydration wiring (host-wiring, adia-ui-factory plugin).
+  under SSR (linkedom/Astro) — the four known failure shapes, what's fixed
+  vs open, how to prove a fix under the linkedom shim gate. Use for "does
+  this work under SSR", why a component crashes on
+  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof
+  Node` under a DOM shim, why table-ui/chart-ui/select-ui or a container CE
+  renders empty or drops nested children server-rendered, whether
+  getBoundingClientRect() is safe in connectedCallback, or whether a shim
+  can be deleted after a fix ships. ANSWERS only. NOT for a fix
+  (primitive-authoring) or host/hydration wiring (host-wiring,
+  adia-ui-factory).
 disable-model-invocation: false
 user-invocable: false
 ---
@@ -29,36 +28,14 @@ this" and "what's the state of each shape's fix" — it never carries the fix it
 
 ## 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.
+1. **A browser-only API is called unconditionally → crash** (`attachInternals`, Observers, `adoptedStyleSheets`). **Fixed** (gh#285).
+2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.** ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284) — doesn't currently expose against any shipped component.
+2b. **Custom-element upgrade doesn't replay `attributeChangedCallback` for pre-existing attributes → reflected properties stuck at class default.** The REAL mechanism behind gh#284's symptom. **Fixed 2026-07-18** (PR #309).
+3. **A connect-time layout measurement is treated as confirmed, not unknown.** **Fixed for one component** (gh#286); the general pattern is unswept.
+4. **Property-only components can't seed initial state from SSR HTML** (gh#288) — a feature gap, **CLOSED 2026-07-18** (table-ui's `data="[…]"` attribute).
 
-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).
+Full symptom → root-cause → status detail, cited to the actual shipped/open
+code: [failure-shapes.md](references/failure-shapes.md).
 
 ## Consult table
 
@@ -74,17 +51,12 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 
 ## 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; the linkedom shim gate (`scripts/dev/ssr-linkedom-smoke.mjs`, gh#1430) exists
-because happy-dom implements every API in the documented shape-1 cases that linkedom
-lacks (matchMedia, rAF, the Observers, `Node`/`Element` globals, rect APIs), so the
-unit suite is blind to that class by construction — deletion-based testing is the unit-level complement, not
-the proof.
-If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
-new pattern. Route it through `primitive-authoring` — don't force-fit the nearest existing
-shape.
+Every fix pattern this pack cites ([guard-patterns.md](references/guard-patterns.md))
+carries the reasoning for why it looks the way it does (e.g. the no-op
+`ElementInternals` shim exists because `undefined` would relocate the crash,
+not remove it). If a new case doesn't fit an existing pattern's reasoning,
+that's a signal to design a new pattern — route through `primitive-authoring`,
+don't force-fit the nearest existing shape.
 
 ## Boundaries
 
@@ -104,25 +76,11 @@ shape.
 
 ## 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 at the 2026-07 survey — the census has since grown) and cites exactly why every
-current children-accepting component is unaffected.
+A "content vanished" report can match shape 2's symptom while shape 2
+itself no longer applies (it was narrowed 2026-07-17) — the general lesson
+(grep the component's `static template` before answering "known issue,
+shape 2") plus a full worked ask/answer are in
+[failure-shapes.md](references/failure-shapes.md) §2's own Worked example.
 
 ## Corpus of record
 

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

@@ -131,6 +131,29 @@ the attribute-upgrade-replay gap was real-and-live (now fixed in #309). A
 future "content vanished under SSR" report should check the attribute-replay
 mechanism FIRST — it's the one that was actually firing.
 
+### Worked example — answering a new "content vanished" report
+
+**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. This
+survey (150 components at the 2026-07 survey — the census has since grown)
+cites exactly why every current children-accepting component is unaffected.
+
 ## 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)