@adia-ai/web-components 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.9] — 2026-05-21
+
+### Fixed
+- **9 component CSS files — `@scope` blocks no longer use bare-combinator descendants (F-002, P1).** Pre-fix: 92 selector clauses across `action-list.css`, `card.css`, `chart.css`, `chat-thread.css`, `code.css`, `command.css`, `grid.css`, `pane.css`, `stack.css` used the `@scope { > X { } }` shape (bare `>` combinator with no left-hand selector inside `@scope`). Chromium/Firefox tolerate this; LightningCSS rejects it as "Invalid empty selector" (matches the CSS Nesting + `@scope` spec strictly). Symptom: consumers on Vite 7 (default `cssMinify: 'lightningcss'`) saw build-time failures at `card.css:152`; Vite 6 + earlier Vite 7 (esbuild minify) silently swallowed the same source. Fix: codemod-driven rewrite of all 92 clauses from `> X` to `& > X` (explicit `&` reference matches the modern CSS Nesting idiom; semantically identical; LightningCSS-clean). All 120 CSS files now pass LightningCSS minify against Vite 8 default targets (Chromium 125+, Safari 18+, Firefox 129+). Codemod source: `scripts/build/codemod-scope-bare-descendants.mjs` (committed for future audits; idempotent + `--verify` mode). Paired CI gate `check:scope-bare-descendants` blocks regression at PR time; companion `check:lightningcss-build` smoke-minifies every CSS file end-to-end against Vite 8 targets. Closes claims-ui FEEDBACK-02.
+
+### Documentation
+- **`USAGE.md` — new "Looking up a component's API" subsection.** Three discovery paths now documented in one place: `npx adia-ai-doc <component>` CLI (machine-readable + offline-safe), `<component>.examples.html` per-component live demo + Properties table, and `<component>.yaml` source-of-truth schema. Closes claims-ui FEEDBACK-09 (per-component opt-out attributes are documented; this subsection makes the doc-path discoverable from the top-level USAGE entrypoint).
+
+## [0.6.8] — 2026-05-20
+
+### Fixed
+- **`core/template.js` — `.camelCaseProp=${expr}` property bindings now route to the canonical setter (FB-55, P1).** Pre-fix: the HTML parser lowercases attribute names inside `<template>.innerHTML` per HTML5 §13.2.5.32, so `.className=${expr}` arrived at the binding scanner as `.classname`. The binding then wrote `element['classname'] = v` — an enumerable expando — never invoking the `HTMLElement.prototype.className` setter. Classes never applied; no warning, no error. Trap affected every camelCase DOM property surface (`.className`, `.innerText`, `.tabIndex`, `.ariaLabel`, `.contentEditable`, `.readOnly`, `.maxLength`, `.minLength`, `.colSpan`, `.rowSpan`) AND every camelCase property declared via `UIElement.static properties` (80+ across primitives — `<color-picker>` `.maxChroma`, `<grid>` `.columnGap`, `<breadcrumb>` `.collapseKeepLeading`, etc.). Even the canonical `<my-panel .minL=${minL}>` example from `README.md:212` silently failed. **Fix: two-layer name resolution** — (1) `PROP_CASE_FIX` static map at `scan()` time covers built-in DOM camelCase (zero-cost lookup, no prototype walk for the common case); (2) lazy prototype-walk fallback at `applyValue()` time finds canonical camelCase property names on the element's instance + prototype chain via case-insensitive match, caching resolution on the part after first hit. Catches UIElement custom-element props installed per-instance in `installProps()` (those don't exist at `scan()` time because the element hasn't been upgraded yet). Backward-compatible: when neither layer finds a case-insensitive match, the original lowercase name is preserved (consumers writing to lowercase expandos unaffected). 10 NEW vitest cases in `core/template.test.js`'s `FB-55` describe block pin the contract. Closes RESPONSE-55 (reviewer-#A expansion to UIElement primitives explicitly covered).
+- **`core/template.js` — nested `${html\`<svg-child/>\`}` interpolations now render in SVG namespace (FB-57, P1).** Pre-fix: each nested `html\`\`` is a separate cached template whose `tpl.innerHTML = m` is parsed at document level without SVG insertion-mode context, so `<circle>`/`<line>`/etc. arrived as `HTMLUnknownElement` (NS `http://www.w3.org/1999/xhtml`). The `<span style="display:contents">` wrapper from `wrap()` didn't fix it because `display: contents` is layout-level, not namespace-level; SVG layout is namespace-strict → present-but-invisible output, zero bounding rect, no error. **Fix: namespace-aware `mount()`** — discriminate via `container.closest('svg, math, foreignObject, annotation-xml')` at mount time; when stamping into an SVG/MathML subtree, recursively re-namespace the cloned fragment via `createElementNS`, transferring attributes via `setAttributeNS` to preserve attr-namespaces (e.g., legacy `xlink:href`). `<foreignObject>` (SVG) and `<annotation-xml encoding="text/html"|"application/xhtml+xml">` (MathML) descendants correctly REVERT to HTML namespace per HTML5 §12.2.5 foreign-content insertion mode. Implementation site: `mount()` rather than `getTemplate()` — keeps the template cache coherent (same `html\`\`` source can stamp into either context without doubling cache entries). 6 NEW vitest cases in `core/template.test.js`'s `FB-57` describe block (inline-SVG regression, nested-SVG fix, direct-stamp into SVG container, foreignObject boundary, MathML, HTML-container no-op). Closes RESPONSE-57 (Option A accepted with implementation-site refinement; Option B rejected as half-measure).
+- **`core/template.js` — partial-interp warning text recommends `class="${expr}"` first (FB-55 #2).** The v0.5.5 §184 warn text put `.className=${expression}` first as the recommended fix for partial class interpolation; that path now works post-FB-55 fix above, but `class="${expr}"` (full-attribute interpolation) is the more discoverable form that doesn't require knowing the camelCase property name. Promoting it first. The `.classList=${{foo: true, bar: false}}` aspirational line is removed — classList is a read-only DOMTokenList accessor, no `PROP_CASE_FIX` entry can make it assignable.
+
+### Docs
+- **`USAGE.md` — three new template-related sections** documenting the FB-55/56/57 cluster:
+  - **§-TBD (v0.6.8) — Host element display defaults (FB-56)** — surfaces the HTML-spec inline default for custom elements + the `:host(:where(*))` zero-specificity recipe used across the in-tree primitive set (30+ flex-container primitives). Documents why `UIElement` doesn't bake a `display` rule into the host (container vs leaf vs passthrough is a consumer-layout decision). Worked symptom + diagnostic recipe ("inspect the host directly — `getComputedStyle(host).display === 'inline'`").
+  - **§-TBD (v0.6.8) — SVG composition + namespacing (FB-57)** — documents three modes (inline, nested-interpolations, imperative-`.innerHTML`) with the `<foreignObject>` boundary semantics and the MathML parallel. Migration is zero — pre-fix code that worked keeps working; pre-fix code that was silently broken (nested SVG interpolations) starts producing visible output.
+  - **§-TBD (v0.6.8) — `.camelCaseProp=${expr}` property binding (FB-55)** — explains the two-layer name resolution, lists affected camelCase property surfaces, documents backward-compatibility for genuine expando consumers, and notes the discoverability trade-off (the simpler `class="${expr}"` doesn't require knowing the camelCase property name).
+- **USAGE.md `§-TBD (v0.6.8) — UIElement lifecycle hooks (FB-59 + FB-43/44/47/58 cluster)`** — new section documenting the canonical hook order: `adoptStyles` → `prepareParts` → **`connected()`** (line 122, inside `untracked()`) → effect first-run with **stamp at line 127** → `render()` → `updated()`. Source-cited from `core/element.js:107-142`. Resolves a cluster-wide misunderstanding about when `connected()` fires relative to the template stamp: it runs BEFORE the stamp wipes consumer-supplied light-DOM children, NOT after. Includes the "Container UIElement pattern" example showing `connected()` → capture children → arm MutationObserver, plus the defensive `if (present.length > 0) keep` cache-fallback pattern (consumer-discovered) that makes capture robust to ordering. Distinguishes `connected()` (recommended subclass hook) vs `connectedCallback()` (rarely overridden W3C hook). Closes FB-59 P3 docs ask + corrects the §B mechanism walkthrough in RESPONSE-58 (sibling followup-RESPONSE retracts the §B order claim).
+
 ## [0.6.7] — 2026-05-19
 
 ### Added

package/USAGE.md

@@ -59,6 +59,35 @@ import { signal, computed, effect, html, UIElement, UIFormElement } from '@adia-
 import '@adia-ai/web-components/traits';
 ```
 
+### Looking up a component's API
+
+Three reliable surfaces, in order of immediacy:
+
+```bash
+# 1. CLI (since v0.6.7) — prints yaml summary + live demo URL + first example
+npx adia-ui-doc table-toolbar     # full prop / slot / event surface
+npx adia-ui-doc                   # bare invocation lists all 96 components
+```
+
+```bash
+# 2. Per-component examples (ship in npm tarball since v0.6.7)
+cat node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.examples.md
+
+# Or the richer .examples.html for Properties tables + multi-section walks
+open node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.examples.html
+```
+
+```bash
+# 3. The component's yaml (authoritative — all props, defaults, descriptions)
+cat node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.yaml
+```
+
+The yaml is the source of truth for every property, slot, event, and token.
+The CLI reads it. The `.d.ts` files are generated from it. When this USAGE
+guide and the yaml disagree, the yaml wins — file a doc-bug FEEDBACK.
+
+For the live demo of every component: <https://ui-kit.exe.xyz/site/components/>.
+
 ---
 
 ## The mental model
@@ -1181,6 +1210,115 @@ Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective
 - HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
 - Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
 
+### §-TBD (v0.6.8) — Host element display defaults (FB-56)
+
+Per the HTML spec, **all custom elements default to `display: inline`** — and `UIElement` subclasses are no exception. When you use a `UIElement` subclass as a layout container (filling a flex parent, holding an SVG canvas, wrapping a fluid grid), the inline default collapses the host to zero height and any `height: 100%` descendant collapses with it.
+
+**Symptom you're hitting this trap:** content renders in DevTools with the expected DOM, but its computed height is 0 because the custom-element host between it and a layout parent has `display: inline`. Inspect the host element directly — `getComputedStyle(host).display === 'inline'` confirms.
+
+If you author a `UIElement` to be a layout container, set an explicit `display` on the host tag — the in-tree convention is `:host(:where(*))` so consumer-app CSS can still override without `!important`:
+
+```js
+import { css } from '@adia-ai/web-components/core/element';
+
+class MyContainer extends UIElement {
+  static styles = css`
+    :host(:where(*)) {       /* zero-specificity wrap; consumers override at (0,0,1) */
+      display: flex;
+      flex-direction: column;
+      flex: 1 1 auto;
+      min-height: 0;
+    }
+  `;
+  static template = (host) => html`<slot></slot>`;
+}
+```
+
+Or, if the host should be transparent to layout (its children inherit the parent's grid/flex context directly):
+
+```css
+my-passthrough-element { display: contents; }
+```
+
+See also: the slot-routing pass-through pattern that's the natural consumer of `display: contents` (cross-referenced from §345's `.map()` vs `repeat()` discussion where `wrap()` spans use the same mechanism).
+
+**`UIElement` does not bake a `display` rule into the host** because container vs leaf vs passthrough is a consumer-layout decision, not a framework one. Per primitive, a global default would risk breaking layouts where the consumer explicitly wants `inline` semantics (e.g. inline badge inside flowing text, `<icon>` rendered alongside surrounding `<text-ui>`, `<kbd-ui>` keystroke marker). The in-tree primitive set spans `inline` / `inline-block` / `block` / `flex` / `grid` / `contents` — no single default fits.
+
+**In-tree convention reference:** scan `packages/web-components/components/*/<name>.css` for the `:host(:where(*))` pattern. The 30+ flex-container primitives (`<editor-shell>`, `<nav>`, `<pane>`, `<page>`, `<card>`, etc.) all use this shape; copy from the closest-fit primitive.
+
+### §-TBD (v0.6.8) — SVG composition + namespacing (FB-57)
+
+`html\`\`` handles SVG content in three modes, with one historical trap closed in v0.6.8.
+
+**Mode 1 — inline SVG in a single template (always worked):**
+
+```js
+html`
+  <svg viewBox="0 0 100 100">
+    <circle cx="50" cy="50" r="10"/>
+    <path d="M 0 0 L 100 100"/>
+  </svg>
+`
+```
+
+When the parser sees `<svg>` in `tpl.innerHTML`, it enters SVG insertion mode for its descendants. Children arrive as proper `SVGElement` instances.
+
+**Mode 2 — nested template interpolations (now works, post-v0.6.8 FB-57 fix):**
+
+```js
+html`
+  <svg viewBox="0 0 100 100">
+    ${dots.map(d => html`<circle cx="${d.x}" cy="${d.y}" r="3"/>`)}
+  </svg>
+`
+```
+
+Each nested `html\`<circle/>\`` is a separate template parsed at document level (no SVG context), so pre-v0.6.8 the circles arrived as `HTMLUnknownElement` — present in the DOM but invisible to SVG layout (zero bounding rect, no stroke, no fill, no error). v0.6.8 `mount()` detects when the container is inside an SVG (or MathML) subtree and re-namespaces the cloned fragment via `createElementNS`. The natural composition pattern works.
+
+**Mode 3 — imperative `.innerHTML` commit (escape hatch for very large SVG):**
+
+For SVG content too large to template cleanly (thousands of nodes, dynamic shape strings):
+
+```js
+class MyChart extends UIElement {
+  static template = (host) => html`<svg viewBox="0 0 ${host.w} ${host.h}"></svg>`;
+  updated() {
+    const svg = this.querySelector('svg');
+    svg.innerHTML = host._buildSvgString();  // SVG-namespaced via SVGSVGElement.innerHTML
+  }
+}
+```
+
+`.innerHTML=${str}` as a template binding also works for this (the property name is already lowercase, so the FB-55 PROP_CASE_FIX entry just maps `innerhtml` → `innerHTML`, and the assignment routes through the SVGSVGElement's `innerHTML` setter which DOES enter SVG insertion mode).
+
+**`<foreignObject>` boundary:** content inside `<foreignObject>` returns to HTML namespace per HTML5 §12.2.5 foreign-content insertion mode. The template engine respects this — interpolations inside `<foreignObject>` are HTML-namespaced even when the outer container is SVG. Use it as the documented escape hatch for HTML widgets embedded in SVG graphs (tooltips, popovers, foreign Cells in dataviz).
+
+**MathML** uses the same mechanism: nested `${html\`<mi/>\`}` inside `<math>` gets re-namespaced to MathML NS. `<annotation-xml encoding="text/html">` is the MathML equivalent of `<foreignObject>` for HTML re-entry.
+
+**Migration:** zero. Pre-v0.6.8 code that already worked (inline SVG + `.innerHTML` commits) keeps working. Code that was silently broken (nested SVG interpolations) starts producing visible output.
+
+### §-TBD (v0.6.8) — `.camelCaseProp=${expr}` property binding (FB-55)
+
+Pre-v0.6.8 trap: the HTML parser lowercases attribute names inside `<template>.innerHTML` per HTML5 §13.2.5.32, so `.className=${expr}` arrived at the binding scanner as `.classname`. The binding then wrote `element['classname'] = v` — a lowercase enumerable **expando** — never invoking the `HTMLElement.prototype.className` setter. CSS classes never applied; no warning, no error.
+
+Same trap affected every camelCase DOM property surface: `.className`, `.innerText`, `.tabIndex`, `.ariaLabel`, `.contentEditable`, `.readOnly`, `.maxLength`, `.minLength`, `.colSpan`, `.rowSpan` — AND every camelCase property declared via `UIElement.static properties` (e.g. `<color-picker>`'s `.maxChroma`, `<grid>`'s `.columnGap`, `<breadcrumb>`'s `.collapseKeepLeading`, plus 80+ others across primitives). Even the canonical reactive-binding example from `README.md` (`<my-panel .minL=${minL}>`) silently failed.
+
+v0.6.8 fix: a two-layer name resolution in `core/template.js`:
+
+1. **`PROP_CASE_FIX` static map** at scan time covers built-in DOM camelCase properties (zero-cost lookup, no prototype walk for the common case).
+2. **Prototype-walk fallback** at `applyValue()` time finds canonical camelCase property names on the element's instance + prototype chain via case-insensitive match — caches the resolution on the part after first hit. Catches UIElement custom-element props installed per-instance in `installProps()`.
+
+```js
+// ✅ Works post-v0.6.8 — both forms route to the canonical setter
+html`<span .className=${'foo bar'}>text</span>`;
+html`<color-picker .maxChroma=${0.3}></color-picker>`;
+html`<my-panel .minL=${minL}></my-panel>`;
+```
+
+**Backward compatibility:** when neither the map nor the prototype walk finds a case-insensitive match, the original lowercase name is preserved. Consumers deliberately writing to lowercase expando properties (`.myexpando=${v}`) are unaffected.
+
+**Discoverability note:** the simpler form `class="${expr}"` (full-attribute interpolation) works without needing to know the camelCase property name and is the v0.6.8 partial-interp warn-text's first recommendation. Reach for `.className=` when you specifically want the property-binding semantics (e.g., when the value carries non-string types, or for performance in tight inner loops).
+
 ### §345 (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
 
 Use **`repeat(items, keyFn, tplFn)`** for any list whose items are signal-driven and should preserve identity across re-renders. Plain `.map()` returns an `Array` of template results, which the template engine materializes via `container.replaceChildren()` on every parent update — correct, but per-item DOM is re-created from scratch.
@@ -1277,6 +1415,83 @@ Use the descendant combinator (a single space) instead, which traverses any dept
 
 Same caveat applies to `:nth-child()` / `:nth-of-type()` / `:first-child` / `:last-child` against the parent — those count actual children (the wrapper-spans), not the items inside. If you need nth-item styling, key it via a data attribute on the item itself rather than relying on positional pseudo-classes against the wrapper layer.
 
+### §-TBD (v0.6.8) — UIElement lifecycle hooks (FB-59 + FB-43/44/47/58 cluster)
+
+UIElement orchestrates the custom-element lifecycle and exposes two extension points: the W3C standard `connectedCallback()` (rarely overridden) and the convenience **`connected()` hook (the recommended subclass extension point)**. Same pattern for `disconnected()`.
+
+#### Canonical hook order
+
+For a UIElement subclass with `static template = () => html\`<x/>\`` mounted into the DOM with consumer-supplied light-DOM children:
+
+1. **`adoptStyles(ctor)`** — adopted stylesheets attached to the document
+2. **`prepareParts(ctor)`** — `static template` markup parsed into the part registry
+3. **`this.connected()`** — subclass hook fires here, inside `untracked(...)`. **Light-DOM children supplied by the parent template are intact at this point.**
+4. **Effect first-run** — `stamp(result, this)` runs here if `ctor.template(this)` returns non-null. This is the call that **wipes consumer-supplied light-DOM children** (via `mount()` → `container.replaceChildren(f)`).
+5. **`this.render()`** — explicit render hook for imperative DOM updates
+6. **`this.updated(changedProps)`** — change-set hook for property-specific reactions
+
+**The key insight for container components: `connected()` runs BEFORE the stamp.** If your container UIElement has both a non-null `static template` AND wants to capture consumer-supplied light-DOM children, do the capture in `connected()`. The wipe runs in step 4, which is after step 3.
+
+Source: `packages/web-components/core/element.js:107-142` — `UIElement.connectedCallback()`. `connected()` fires at line 122 inside `untracked(...)`; the stamp runs at line 127 inside the effect registered at lines 123-137.
+
+#### Container UIElement pattern (FB-43/44/47/58 cluster — the right shape)
+
+When your UIElement is a container for consumer-supplied light-DOM children AND has its own internal `static template`, capture the children in `connected()`:
+
+```js
+class DtsGraph extends UIElement {
+  static template = () => html`<div class="dts-graph-root"></div>`;
+
+  // ✅ connected() runs BEFORE the stamp wipes children — capture here
+  connected() {
+    this._series = [...this.querySelectorAll('dts-graph-band, dts-graph-curve, …')];
+
+    // Optional: MutationObserver for late-arriving children (e.g. parent template
+    // toggles `${cond ? html\`<band/>\` : ''}` and the new band lands later)
+    this._mo = new MutationObserver(() => this._captureSeries());
+    this._mo.observe(this, { childList: true, subtree: true });
+  }
+
+  _captureSeries() {
+    const present = [...this.querySelectorAll('dts-graph-band, …')];
+    // Defensive cache-fallback: post-stamp wipe makes `present` empty, but the
+    // initial capture from connected() above already saved the refs. Keep them.
+    if (present.length > 0) this._series = present;
+  }
+
+  disconnected() {
+    this._mo?.disconnect();
+  }
+}
+```
+
+The `if (present.length > 0) keep` cache-fallback is the architectural pattern that makes the capture robust to either ordering. It works in any lifecycle environment with no specification dependency.
+
+#### `connected()` vs `connectedCallback()` reference
+
+| Hook | Who calls it | When (relative to step list above) | Use case |
+|---|---|---|---|
+| `connectedCallback()` | The browser, per W3C custom-elements spec | Orchestrates the whole sequence | Almost never override — UIElement runs the lifecycle for you |
+| **`connected()`** | UIElement, from within `connectedCallback()` at line 122 | Step 3 — after `prepareParts()`, BEFORE the template stamp | **Subclass setup, light-DOM capture, observer arming, signal effects** |
+| `render()` | The effect, after every signal change | Step 5 — after `stamp()` if the template returned non-null | Imperative DOM updates that don't fit the template engine |
+| `updated(changedProps)` | The effect | Step 6 — after `render()`, when properties changed | React to specific prop changes |
+| `disconnected()` | UIElement, from `disconnectedCallback()` | Element leaves the DOM | Teardown observers, timers, listeners |
+
+#### When NOT to override `connectedCallback()` directly
+
+`UIElement.connectedCallback()` orchestrates the entire lifecycle. Overriding it directly requires re-invoking `super.connectedCallback()` correctly, and you'd have to choose whether your work goes before or after super:
+
+- **BEFORE super**: you miss the `prepareParts(ctor)` call that initializes the part registry. `static template` won't stamp. Other downstream initialization breaks.
+- **AFTER super**: your work runs after step 6 (`updated()`), which means after the stamp wiped your light-DOM children. You'd need to capture in `constructor()` instead — but `constructor()` runs before the element is in the DOM, so light-DOM children aren't appended yet.
+
+`connected()` is the right hook for 99% of consumer code. It runs at exactly the right time: children present, stamp not yet run.
+
+#### Why `connected()` is wrapped in `untracked()`
+
+Per the comment in `element.js:112-121`: `connected()` commonly reads reactive properties via template-literal interpolation (`${this.label}` etc.) when stamping inner DOM. If the outer call path is inside another effect (e.g. a parent's render loop `appendChild`'ing this node), those reads would subscribe the outer effect to this element's signals — invisible cross-element coupling that looks like spooky re-runs on unrelated state changes. The `untracked()` wrapper prevents that subscription leak. The element's own effect (registered at lines 123-137) re-reads the same signals in its own tracking context, so reactivity within the element is unaffected.
+
+This means: inside `connected()`, you CAN read signals/props for setup logic, but those reads won't establish reactive subscriptions. Use the element's own `render()` or signal effects for reactive work; use `connected()` for one-shot setup.
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):

package/components/action-list/action-list.css

@@ -99,7 +99,7 @@ action-item-ui:hover [slot="icon"] {
   }
 
   /* Default slot (trailing content: kbd, badge, chevron) pushed to far right */
-  > :not([slot="icon"]):not([slot="text"]) {
+  & > :not([slot="icon"]):not([slot="text"]) {
     flex-shrink: 0;
     margin-inline-start: auto;
     color: var(--action-item-icon-fg);

package/components/card/card.css

@@ -149,7 +149,7 @@
      [padding] switches to padding mode with background.
      Grid layout: optional icon | heading+description | optional action */
 
-  > header {
+  & > header {
     display: block;
     margin: var(--card-inset);
   }
@@ -157,24 +157,24 @@
   /* Activate grid layout only when a DIRECT slotted child is present.
      Constraining to `:has(> [slot])` prevents deeply nested slots (e.g. an
      [slot="icon"] inside an <avatar-ui>) from falsely activating the grid. */
-  > header:has(> [slot]) {
+  & > header:has(> [slot]) {
     display: grid;
     gap: var(--card-header-gap);
     align-items: center;
   }
 
-  > header[padding] {
+  & > header[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
-  > header[divider] {
+  & > header[divider] {
     padding-bottom: var(--card-inset);
     border-bottom: 1px solid var(--card-divider);
   }
 
-  > header[center] {
+  & > header[center] {
     text-align: center;
     justify-items: center;
   }
@@ -182,16 +182,16 @@
   /* Column templates — match gen-ui-kit pattern. Direct-child `:has(> …)` so
      nested [slot="icon"] inside a composite (e.g. <avatar-ui>) can't trigger
      the icon column by accident. */
-  > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr max-content; }
-  > header:has(> [slot="icon"]):not(:has(> [slot="action"]))   { grid-template-columns: max-content 1fr; }
-  > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr max-content; }
-  > header:not(:has(> [slot="icon"])):not(:has(> [slot="action"])) { grid-template-columns: 1fr; }
+  & > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr max-content; }
+  & > header:has(> [slot="icon"]):not(:has(> [slot="action"]))   { grid-template-columns: max-content 1fr; }
+  & > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr max-content; }
+  & > header:not(:has(> [slot="icon"])):not(:has(> [slot="action"])) { grid-template-columns: 1fr; }
 
   /* Unslotted children (zettel fragment injection, etc.) — each on its own row,
      spanning the full width, stacked ABOVE the heading/description/action grid.
      This lets compositions inject logos, banners, etc. into a header without
      having to know the slot vocabulary. */
-  > header > *:not([slot]):not(h1):not(h2):not(h3):not(h4):not(h5):not(h6):not(p):not(small) {
+  & > header > *:not([slot]):not(h1):not(h2):not(h3):not(h4):not(h5):not(h6):not(p):not(small) {
     grid-column: 1 / -1;
     justify-self: center;
   }
@@ -200,7 +200,7 @@
      Default: single row, center-aligned with heading/action.
      When a description row exists, spans both rows and anchors to the
      start so the icon visually aligns with the heading. */
-  > header > [slot="icon"] {
+  & > header > [slot="icon"] {
     grid-column: 1;
     grid-row: 1;
     align-self: center;
@@ -209,39 +209,39 @@
     justify-content: center;
   }
 
-  > header:has(> :is([slot="description"], p, small)) > [slot="icon"] {
+  & > header:has(> :is([slot="description"], p, small)) > [slot="icon"] {
     grid-row: 1 / span 2;
     align-self: start;
   }
 
   /* Heading — row 1 */
-  > header > :is([slot="heading"], h1, h2, h3, h4, h5, h6),
-  > header > [slot="heading"] :is(h1, h2, h3, h4, h5, h6) {
+  & > header > :is([slot="heading"], h1, h2, h3, h4, h5, h6),
+  & > header > [slot="heading"] :is(h1, h2, h3, h4, h5, h6) {
     grid-row: 1;
     line-height: 1.3;
     margin: 0;
   }
   /* Heading slot is a flex container — can hold title + inline badges/metadata */
-  > header > [slot="heading"] {
+  & > header > [slot="heading"] {
     display: flex;
     align-items: center;
     gap: var(--card-header-gap);
   }
-  > header:has(> [slot="icon"]) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 2; }
-  > header:not(:has(> [slot="icon"])) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 1; }
+  & > header:has(> [slot="icon"]) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 2; }
+  & > header:not(:has(> [slot="icon"])) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 1; }
 
   /* Description — row 2 */
-  > header > :is([slot="description"], p, small) {
+  & > header > :is([slot="description"], p, small) {
     grid-row: 2;
     grid-column: 1 / -1;
     line-height: 1.4;
     margin: 0;
   }
-  > header:has(> [slot="icon"]) > :is([slot="description"], p, small) { grid-column: 2 / -1; }
+  & > header:has(> [slot="icon"]) > :is([slot="description"], p, small) { grid-column: 2 / -1; }
 
   /* Action — row 1, last column.
      Flex container so it can hold badge + button + anything inline. */
-  > header [slot="action"] {
+  & > header [slot="action"] {
     justify-self: end;
     align-self: center;
     grid-row: 1;
@@ -256,17 +256,17 @@
      [padding] switches to padding with background.
      [bleed] removes all spacing for edge-to-edge content. */
 
-  > section {
+  & > section {
     margin: var(--card-inset);
   }
 
-  > section[padding] {
+  & > section[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
-  > section[bleed] {
+  & > section[bleed] {
     margin: 0;
     padding: 0;
   }
@@ -276,7 +276,7 @@
      [divider] adds top border.
      [padding] switches to padded mode. */
 
-  > footer {
+  & > footer {
     display: block;
     margin: var(--card-inset);
   }
@@ -284,8 +284,8 @@
   /* Activate flex layout when a direct slotted child or multiple children are
      present. `:has(> [slot])` so nested [slot="…"] inside composites can't
      trigger the flex row. */
-  > footer:has(> [slot]),
-  > footer:has(> :nth-child(2)) {
+  & > footer:has(> [slot]),
+  & > footer:has(> :nth-child(2)) {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
@@ -293,30 +293,30 @@
   }
 
   /* col-ui in footer takes full width (common for stacked footer: button + divider + social) */
-  > footer > col-ui { width: 100%; }
+  & > footer > col-ui { width: 100%; }
 
-  > footer[justify="end"] {
+  & > footer[justify="end"] {
     justify-content: flex-end;
   }
 
-  > footer[divider] {
+  & > footer[divider] {
     margin-top: var(--card-inset);
     padding-top: var(--card-inset);
     border-top: 1px solid var(--card-divider);
   }
 
-  > footer[padding] {
+  & > footer[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
   /* Footer with direct-child description + action = space-between */
-  > footer:has(> :is([slot="description"], p, small)):has(> [slot="action"]) {
+  & > footer:has(> :is([slot="description"], p, small)):has(> [slot="action"]) {
     justify-content: space-between;
   }
 
-  > footer :is([slot="description"], p, small) {
+  & > footer :is([slot="description"], p, small) {
     font-size: var(--card-description-size);
     color: var(--card-description-fg);
     flex: 1;
@@ -327,7 +327,7 @@
   /* Footer heading — trend-stat line (symmetric with header's [slot="heading"]).
      Used for chart trend-footer patterns like "Trending up by 5.2% this month".
      Paired with [slot="description"] for a "Jan – Mar 2024" period caption. */
-  > footer > [slot="heading"] {
+  & > footer > [slot="heading"] {
     font-size: var(--card-font-size);
     font-weight: var(--a-weight-medium);
     color: var(--card-heading-fg);
@@ -339,21 +339,21 @@
   /* Footer with heading + description = column stack, heading on top. The
      existing flex-row layout becomes a flex-column when a heading is present,
      so the trend line and period caption stack naturally. */
-  > footer:has(> [slot="heading"]) {
+  & > footer:has(> [slot="heading"]) {
     flex-direction: column;
     align-items: flex-start;
     gap: var(--a-space-0-5);
   }
 
-  > footer:has(> [slot="heading"])[justify="end"] {
+  & > footer:has(> [slot="heading"])[justify="end"] {
     align-items: flex-end;
   }
 
-  > footer:has(> [slot="heading"])[justify="center"] {
+  & > footer:has(> [slot="heading"])[justify="center"] {
     align-items: center;
   }
 
-  > footer [slot="action"] {
+  & > footer [slot="action"] {
     margin-inline-start: auto;
     display: flex;
     gap: var(--card-footer-gap);
@@ -361,14 +361,14 @@
 
   /* Multiple direct action-slotted children (A2UI pattern):
      only the first pushes the group right; subsequent ones flow with gap */
-  > footer > [slot="action"] ~ [slot="action"] {
+  & > footer > [slot="action"] ~ [slot="action"] {
     margin-inline-start: 0;
   }
 
   /* Dual-cluster footer: leading action (e.g. Delete) on the inline-start
      edge, trailing action cluster on the inline-end. margin-inline-end:
      auto fills the gap between the two groups. */
-  > footer > [slot="action-leading"] {
+  & > footer > [slot="action-leading"] {
     margin-inline-end: auto;
     display: flex;
     gap: var(--card-footer-gap);
@@ -376,15 +376,15 @@
 
   /* ═══════ Images ═══════ */
 
-  > img,
-  > [slot="media"] {
+  & > img,
+  & > [slot="media"] {
     display: block;
     width: 100%;
     object-fit: cover;
   }
 
-  > img:first-child,
-  > [slot="media"]:first-child {
+  & > img:first-child,
+  & > [slot="media"]:first-child {
     border-radius: var(--card-radius) var(--card-radius) 0 0;
   }
 

package/components/chart/chart.css

@@ -112,7 +112,7 @@
   /* Empty-state slot — author places <empty-state-ui slot="empty"> inside
      chart-ui. CSS toggles visibility on [data-has-data] (set by chart.js
      when .data is non-empty). No data ⇒ empty-state visible; data ⇒ hidden. */
-  > [slot="empty"] { display: none; }
+  & > [slot="empty"] { display: none; }
   :scope:not([data-has-data]) > [slot="empty"] {
     display: flex;
     flex: 1 1 auto;

package/components/chat-thread/chat-thread.css

@@ -65,7 +65,7 @@
   }
 
   /* -- Header -- */
-  > header {
+  & > header {
     display: flex;
     align-items: center;
     gap: var(--chat-gap);
@@ -73,7 +73,7 @@
     border-bottom: 1px solid var(--chat-border-color);
   }
 
-  > header [slot="avatar"] {
+  & > header [slot="avatar"] {
     width: var(--chat-header-avatar-size);
     height: var(--chat-header-avatar-size);
     border-radius: var(--chat-header-avatar-radius);
@@ -87,19 +87,19 @@
     flex-shrink: 0;
   }
 
-  > header [slot="name"] {
+  & > header [slot="name"] {
     font-weight: var(--chat-header-name-weight);
     font-size: var(--chat-header-name-size);
   }
 
-  > header [slot="status"] {
+  & > header [slot="status"] {
     font-size: var(--chat-header-status-size);
     color: var(--chat-header-status-fg);
     margin-inline-start: auto;
   }
 
   /* -- Messages -- */
-  > section {
+  & > section {
     flex: 1;
     overflow-y: auto;
     padding: var(--chat-messages-padding);
@@ -175,7 +175,7 @@
   }
 
   /* -- Footer -- */
-  > footer {
+  & > footer {
     min-height: var(--chat-footer-min-height);
     display: flex;
     align-items: center;