@adia-ai/web-components 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.3] — 2026-06-01
+
+### Added
+
+- **Parametric named gap scale `xs`–`xl` (`--a-gap-k`)** — the named gap vocabulary is now a complete, parametric 5-step scale: `--a-gap-{xs,sm,md,lg,xl}` = `half + half·--a-gap-k` (a fixed floor + a k-scaled half). The new `--a-gap-k` knob (`@property`, default 1) is a root/provider-level scale control with the same semantics as `--a-density` (subtree override is inert — set it at `:root`/a top provider). At k=1: **4/8/12/16/20px**. `gap="xs"` and `gap="xl"` now resolve (they were documented in yaml but unimplemented — silently did nothing in both the CSS `[gap]` path and the JS `@bp` responsive path). At k=1 the named scale coincides with the integer scale: xs=1, sm=2, md=3, lg=4, xl=5. (spec GS-P2-SPEC-2 §5.2)
+
+### Changed
+
+- **Behavior change (MINOR): explicit `[gap="sm|md|lg"]` resolves smaller** — `gap="sm|md|lg"` on layout primitives (col/row/grid) now resolves to `--a-gap-{sm,md,lg}` = **8/12/16px** (was the hardcoded `--a-space-4/6/8` = 16/24/32px). This unifies the three gap paths that previously disagreed — explicit `[gap="md"]` was 24px while the responsive (`gap="md@bp"`, JS `_gapToCss`) and ambient (`[size]`) paths were 12px; all three are now `--a-gap-md`. Integer `gap="N"` is unchanged (literal `--a-space-N`, k-independent). `[size]` / `<card-ui size="…">` unaffected. (audit C1/C2)
+- **`[gap]` no longer leaks into nested layout primitives (audit C3)** — `[gap="N"]` now sets a NON-inheriting `--a-gap-self` (`@property{syntax:"*";inherits:false}`); the inheriting `--a-gap` is reserved for the *ambient* `[size]`/`[prose]`/`:root` cascade. The six gap-readers (col/row/grid/card/swiper/stat) resolve `var(--a-gap-self, var(--a-gap))` — explicit-on-self wins, else the inherited ambient. Previously a parent's explicit `gap="8"` bled into a nested `<row-ui>` that declared no gap of its own. Verified via `scripts/qa/cascade-gap-self-probe.mjs` (5 truth-table rows + parametric + coincidence, all green).
+- **`col`/`row`/`grid` yaml gap docs + layout demo reconciled to impl** — documented the two grammars (named parametric + integer 0–16), fixed grid's range claim (`0–12`→`0–16`), dropped the phantom-value framing (`xs`/`xl` real now). `layout.examples.html`: Properties tables corrected, broken `gap="none"` demo → `gap="0"`, col demo filled out to the complete `xs`→`xl` scale. Sidecars regenerated.
+
+### Fixed
+
+- **`<tree-item-ui>` adopts interpolated `[slot="actions"]`/`[slot="caret"]` children (FB-96)** — the FB-89 actions-adoption used a `this.querySelectorAll(':scope > [slot="actions"]')` direct-child query that ran once at `#stamp()` time, so a `<button-ui slot="actions">` rendered through the template engine (`.map()`/`repeat()`/conditional) was missed twice over: it arrives in a *later* reactive tick (after `#stamp`) **and** nested in a `display:contents` wrapper span. The un-adopted button stayed a bare `role="button"` child of the `group`/`tree`, tripping axe `aria-required-children` even after the FB-94 `role="presentation"` fix (which addresses role-flattening, not structural adoption). `#stamp()` now stamps an empty placeholder and a re-entrancy-guarded `MutationObserver` adopts the real `[slot="actions"]`/`[slot="caret"]` into the row whenever they appear, via a wrapper-piercing "logical children" walk that stops at nested `tree-item-ui` boundaries (so a child item's actions aren't mis-adopted) and drops the placeholder once a real child lands. +2 regression tests; verified with axe-core (`.map()` tree + interpolated actions button → 0 `aria-required-children`). The structural-adoption sibling of the FB-92 `menu #show()` fix — same `:scope >` + `display:contents` trap. (Tokens Studio / color-app FB-96)
+
+### Changed — styles + build
+
+- **Gap scale + grammar span `styles/` → `components/` → `patterns/` → `dist/`** — the parametric `--a-gap-k` scale is defined in `styles/` (foundation tokens); the `[gap]` grammar applies on `components/col` / `components/row` / `components/grid`; `patterns/` demos were updated to the named scale; and the `dist/` CDN bundles (`web-components.min.css` + `web-components.min.js`) were regenerated.
+
+## [0.7.2] — 2026-06-01
+
+### Fixed
+
+- **template engine — ARIA-transparent `display:contents` wrapper spans (FB-94)** — the interpolation wrapper span the engine emits for `${…}` parts (`.map()` / conditional / `repeat()`) now carries `role="presentation"`. `display:contents` removes the span's box from layout but it still generated a generic accessibility node, which broke `aria-required-children` / `aria-required-parent` when the span sat between a role-bearing parent and role-bearing children rendered via interpolation — e.g. a `.map()`-rendered `<tree-ui>` (the mainstream consumer case) tripped axe `aria-required-children` even after the FB-91 static-markup fix landed. `role="presentation"` promotes the children to the real parent in the a11y tree. Fixed at all three wrapper sites (`wrap()` + array branch + keyed `repeat()`); +3 regression tests assert the wrappers carry `role="presentation"`. This is the consumer-preferred + peer-recommended central fix and is structurally sound (the spurious generic node between `tree`→`treeitem` is removed). **Honest verification note:** `aria-required-children` could not be made to fire on any in-repo tree (shallow *or* deeply-nested, axe-core, `:5300`) — it triggers only on color-app's exact published-package `dts-token-tree` — so local axe reads 0 both before and after; the firing→cleared transition is **pending the consumer's confirmation** on their next `@adia-ai/web-components` upgrade. (Tokens Studio / color-app FB-94)
+- **`<menu-item-ui>` no longer an orphan `menuitem` when the menu is closed (FB-95)** — `UIMenuItem.connected()` set `role="menuitem"` unconditionally, but a closed `<menu-ui>` moves its items back into its own light DOM (no `role="menu"` ancestor), so every closed declarative menu tripped axe `aria-required-parent`. The role (+ `tabindex="-1"`) is now applied only when the item has a `role="menu"`/`menubar` ancestor; the open popover adopts items via `appendChild` (which re-fires `connected()`), so the role re-applies on open and drops on close. **Verified with axe-core**: closed menu → **0** `aria-required-parent` violations (was 3); open menu → items are `role="menuitem"`, 0 violations. (Tokens Studio / color-app FB-95)
+
+### Changed — styles + build
+
+- **Tokens cascade-layer completed (`styles/`)** — `typography.css` (`type/scale.css`) + `roles.css` `:root` role-token blocks moved into `@layer(tokens)`, finishing the `@layer` migration's tokens cut (the type-scale + role tokens had stayed unlayered). Behavior-neutral — the `[variant]`/state rules keep their existing precedence; only the base `:root` token declarations join the layer.
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) for the template-engine + tokens-layer changes.
+
 ## [0.7.1] — 2026-05-31
 
 ### Fixed

package/components/card/card.css

@@ -8,7 +8,7 @@
   :where(:scope) {
     /* ── Spacing ── */
     --card-inset-default:             var(--a-inset);
-    --card-gap-default:               var(--a-gap);
+    --card-gap-default:               var(--a-gap-self, var(--a-gap));
     --card-header-gap-default:        var(--a-space-2);
     --card-footer-gap-default:        var(--a-space-2);
 

package/components/col/col.a2ui.json

@@ -22,7 +22,7 @@
       "const": "Col"
     },
     "gap": {
-      "description": "Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung (\"1\"…\"16\", mapped to --a-space-N). Accepts `@bp` notation: gap=\"2 4@md\" = 2 below md, 4 from md upward.",
+      "description": "Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl) and an integer space-rung (\"0\"…\"10\", \"12\", \"16\", mapped to --a-space-N). The named scale is parametric (half + half·--a-gap-k, = 4/8/12/16/20px at the default k=1); the integer rungs are literal / k-independent. At k=1 the two coincide: xs=1, sm=2, md=3, lg=4, xl=5. Accepts `@bp` notation: gap=\"2 4@md\" = 2 below md, 4 from md upward.",
       "type": "string",
       "default": "md"
     },

package/components/col/col.css

@@ -1,6 +1,6 @@
 @scope (col-ui) {
   :where(:scope) {
-    --col-gap-default:     var(--a-gap);
+    --col-gap-default:     var(--a-gap-self, var(--a-gap));
     --col-justify-default: flex-start;
     --col-align-default:   stretch;
   }

package/components/col/col.d.ts

@@ -23,7 +23,7 @@ import { UIElement } from '../../core/element.js';
 export class UICol extends UIElement {
   /** Cross-axis alignment (start/center/end/stretch). Accepts `@bp` notation: align="stretch center@sm" applies stretch below sm, center from sm up. */
   align: string;
-  /** Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung ("1"…"16", mapped to --a-space-N). Accepts `@bp` notation: gap="2 4@md" = 2 below md, 4 from md upward. */
+  /** Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl) and an integer space-rung ("0"…"10", "12", "16", mapped to --a-space-N). The named scale is parametric (half + half·--a-gap-k, = 4/8/12/16/20px at the default k=1); the integer rungs are literal / k-independent. At k=1 the two coincide: xs=1, sm=2, md=3, lg=4, xl=5. Accepts `@bp` notation: gap="2 4@md" = 2 below md, 4 from md upward. */
   gap: string;
   /** Fills remaining space in a flex parent (e.g. inside a Row). CSS-only attribute via :scope[grow] in col.css. */
   grow: boolean;

package/components/col/col.yaml

@@ -25,9 +25,12 @@ props:
     default: stretch
   gap:
     description: >-
-      Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing
-      rung ("1"…"16", mapped to --a-space-N). Accepts `@bp` notation:
-      gap="2 4@md" = 2 below md, 4 from md upward.
+      Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl) and an
+      integer space-rung ("0"…"10", "12", "16", mapped to --a-space-N). The named
+      scale is parametric (half + half·--a-gap-k, = 4/8/12/16/20px at the default
+      k=1); the integer rungs are literal / k-independent. At k=1 the two coincide:
+      xs=1, sm=2, md=3, lg=4, xl=5. Accepts `@bp` notation: gap="2 4@md" = 2 below
+      md, 4 from md upward.
     type: string
     default: md
   grow:

package/components/grid/grid.a2ui.json

@@ -27,7 +27,7 @@
       "const": "Grid"
     },
     "gap": {
-      "description": "Grid gap. Accepts numeric space-scale values (0–12) or named sizes (xs/sm/md/lg/xl). Responsive notation supported: \"2 4@md\" = 2 below md, 4 from md upward.",
+      "description": "Grid gap (row + column). Two grammars: a NAMED scale (xs/sm/md/lg/xl, parametric via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung (\"0\"…\"10\", \"12\", \"16\", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4, xl=5. Responsive `@bp` notation supported: \"2 4@md\" = 2 below md, 4 from md upward.",
       "type": "string",
       "default": "md"
     },

package/components/grid/grid.css

@@ -1,8 +1,9 @@
 @scope (grid-ui) {
   :where(:scope) {
-    /* Read `--a-gap` so the universal `[gap="N"]` rules (tokens.css)
-       reach the grid; defaults to `--a-gap-md` at :root. */
-    --grid-gap-default:        var(--a-gap);
+    /* Explicit-then-ambient: `[gap="N"]` sets non-inheriting
+       `--a-gap-self`; `[size]`/`:root` set inheriting `--a-gap` (base
+       `--a-gap-md`). See styles/api/sizing.css + spec §5.2. */
+    --grid-gap-default:        var(--a-gap-self, var(--a-gap));
     --grid-column-gap-default: var(--grid-gap, var(--grid-gap-default));
     --grid-row-gap-default:    var(--grid-gap, var(--grid-gap-default));
   }

package/components/grid/grid.d.ts

@@ -17,7 +17,7 @@ export class UIGrid extends UIElement {
   columnGap: string;
   /** Number of equal columns (1–6), "auto-fill", or "auto-fit". Accepts responsive `@bp` notation: "1 2@sm 4@lg" = 1 on xs, 2 from sm, 4 from lg/xl. Unannotated value is the mobile-first base. */
   columns: string;
-  /** Grid gap. Accepts numeric space-scale values (0–12) or named sizes (xs/sm/md/lg/xl). Responsive notation supported: "2 4@md" = 2 below md, 4 from md upward. */
+  /** Grid gap (row + column). Two grammars: a NAMED scale (xs/sm/md/lg/xl, parametric via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung ("0"…"10", "12", "16", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4, xl=5. Responsive `@bp` notation supported: "2 4@md" = 2 below md, 4 from md upward. */
   gap: string;
   /** Minimum track width for columns="auto-fit"/"auto-fill" (any CSS length, e.g. "240px", "16rem"). Sets the minmax() floor so cards don't shrink below it before wrapping; unset uses the 12rem default. No effect on numeric columns. */
   minColumnWidth: string;

package/components/grid/grid.yaml

@@ -30,9 +30,11 @@ props:
     default: "3"
   gap:
     description: >-
-      Grid gap. Accepts numeric space-scale values (0–12) or named sizes
-      (xs/sm/md/lg/xl). Responsive notation supported: "2 4@md" = 2 below
-      md, 4 from md upward.
+      Grid gap (row + column). Two grammars: a NAMED scale (xs/sm/md/lg/xl,
+      parametric via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung
+      ("0"…"10", "12", "16", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4,
+      xl=5. Responsive `@bp` notation supported: "2 4@md" = 2 below md, 4 from md
+      upward.
     type: string
     default: md
   minColumnWidth:

package/components/menu/menu.class.js

@@ -266,8 +266,20 @@ export class UIMenuItem extends UIElement {
   static template = () => null;
 
   connected() {
-    this.setAttribute('role', 'menuitem');
-    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '-1');
+    // role="menuitem" ONLY when actually inside a menu container. A menu-ui
+    // closes by moving its items back into its own light DOM (see #hide()),
+    // where there is no role="menu"/menubar ancestor — a bare role="menuitem"
+    // there trips axe `aria-required-parent` on every closed menu (FB-95). The
+    // open popover (role="menu") adopts items via appendChild, which re-fires
+    // connected(), so the role re-applies when the menu opens and is dropped
+    // again on close.
+    if (this.closest('[role="menu"], [role="menubar"]')) {
+      this.setAttribute('role', 'menuitem');
+      if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '-1');
+    } else {
+      this.removeAttribute('role');
+      this.removeAttribute('tabindex');
+    }
     this.#stamp();
     this.#syncAria();
   }

package/components/row/row.a2ui.json

@@ -27,7 +27,7 @@
       "default": false
     },
     "gap": {
-      "description": "Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung (\"1\"…\"16\"). Accepts `@bp` notation: gap=\"2 4@md\".",
+      "description": "Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl, parametric via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung (\"0\"…\"10\", \"12\", \"16\", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4, xl=5. Accepts `@bp` notation: gap=\"2 4@md\".",
       "type": "string",
       "default": "md"
     },

package/components/row/row.css

@@ -1,9 +1,11 @@
 @scope (row-ui) {
   :where(:scope) {
-    /* `--a-gap` defaults to `--a-gap-md` at :root in tokens.css; the
-       universal `[gap="N"]` rules override it on the element, so reading
-       `--a-gap` here picks up `<row-ui gap="…">` automatically. */
-    --row-gap-default:     var(--a-gap);
+    /* Gap resolves explicit-then-ambient: `[gap="N"]` sets the
+       non-inheriting `--a-gap-self`; `[size]`/`:root` set the inheriting
+       ambient `--a-gap` (base `--a-gap-md`). Reading
+       `var(--a-gap-self, var(--a-gap))` picks up `<row-ui gap="…">` on
+       this element, else falls through to the inherited ambient. */
+    --row-gap-default:     var(--a-gap-self, var(--a-gap));
     --row-justify-default: flex-start;
     --row-align-default:   center;
     --row-drag-bg-active-default: var(--a-accent-muted);

package/components/row/row.d.ts

@@ -24,7 +24,7 @@ export class UIRow extends UIElement {
   align: string;
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
-  /** Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung ("1"…"16"). Accepts `@bp` notation: gap="2 4@md". */
+  /** Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl, parametric via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung ("0"…"10", "12", "16", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4, xl=5. Accepts `@bp` notation: gap="2 4@md". */
   gap: string;
   /** Fills remaining space in a flex parent. CSS-only attribute via :scope[grow] in row.css. */
   grow: boolean;

package/components/row/row.yaml

@@ -29,8 +29,10 @@ props:
     reflect: true
   gap:
     description: >-
-      Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing
-      rung ("1"…"16"). Accepts `@bp` notation: gap="2 4@md".
+      Gap between children. Two grammars: a NAMED scale (xs/sm/md/lg/xl, parametric
+      via --a-gap-k — 4/8/12/16/20px at k=1) and an integer space-rung ("0"…"10",
+      "12", "16", literal). At k=1 they coincide: xs=1, sm=2, md=3, lg=4, xl=5.
+      Accepts `@bp` notation: gap="2 4@md".
     type: string
     default: md
   grow:

package/components/stat/stat.css

@@ -13,7 +13,7 @@
     --stat-icon-fg-default:      var(--a-fg-muted);
 
     /* ── Spacing ── */
-    --stat-column-gap-default:   var(--a-gap);
+    --stat-column-gap-default:   var(--a-gap-self, var(--a-gap));
     --stat-row-gap-default:      var(--a-gap-sm);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }

package/components/swiper/swiper.css

@@ -21,7 +21,7 @@
 @scope (swiper-ui) {
   :where(:scope) {
     /* ── Layout ── */
-    --swiper-gap-default:           var(--a-gap);
+    --swiper-gap-default:           var(--a-gap-self, var(--a-gap));
     --swiper-peek-default:          var(--a-space-8);
     --swiper-snap-default:          start;
     --swiper-columns-default:       1;

package/components/tree/tree.class.js

@@ -266,6 +266,11 @@ export class UITreeItem extends UIElement {
 
   static template = () => null;
 
+  // FB-96: late-adoption of interpolated [slot="actions"]/[slot="caret"]
+  // children — see connected() + #adoptSlotted().
+  #slotObserver = null;
+  #adopting = false;
+
   get hasChildren() {
     return this.querySelector(':scope > tree-item-ui') !== null;
   }
@@ -303,6 +308,17 @@ export class UITreeItem extends UIElement {
       row.setAttribute('role', 'treeitem');
       if (!row.hasAttribute('tabindex')) row.setAttribute('tabindex', '0');
     }
+
+    // FB-96: declarative [slot="actions"]/[slot="caret"] children rendered via
+    // the template engine (`.map()`/`repeat()`/conditional) arrive in a LATER
+    // reactive tick — AFTER #stamp() — nested in the engine's display:contents
+    // wrapper spans. So neither a connect-time read nor a `:scope >` direct-child
+    // query sees them, and e.g. a `<button-ui slot="actions">` is left as a bare
+    // role=button child of the group/tree (axe `aria-required-children`). Adopt
+    // what's present now, then observe for the late arrivals.
+    this.#adoptSlotted();
+    this.#slotObserver = new MutationObserver(() => this.#adoptSlotted());
+    this.#slotObserver.observe(this, { childList: true, subtree: true });
   }
 
   #stamp() {
@@ -310,15 +326,18 @@ export class UITreeItem extends UIElement {
     row.setAttribute('slot', 'row');
     row.setAttribute('tabindex', '0');
 
-    // Caret — adopt a declarative [slot="caret"] child if the consumer supplied
-    // one, else stamp the default. (Adopt-or-stamp; same pattern as actions.)
-    const declaredCaret = this.querySelector(':scope > [slot="caret"]');
+    // Caret — adopt a declarative [slot="caret"] child if one is already present
+    // (incl. inside the engine's display:contents wrappers, FB-96), else stamp
+    // the default, marked so #adoptSlotted() can drop it if a declared caret
+    // arrives late.
+    const declaredCaret = this.#logicalSlotChildren('caret')[0];
     if (declaredCaret) {
       row.appendChild(declaredCaret);
     } else {
       const caret = document.createElement('icon-ui');
       caret.setAttribute('slot', 'caret');
       caret.setAttribute('name', 'caret-right');
+      caret.dataset.treeCaretDefault = '1';
       row.appendChild(caret);
     }
 
@@ -343,19 +362,16 @@ export class UITreeItem extends UIElement {
     if (this.badge) badgeEl.textContent = this.badge;
     row.appendChild(badgeEl);
 
-    // Actions — adopt pre-existing declarative [slot="actions"] children into
-    // the row (FEEDBACK-89) so per-row action buttons land in the styled,
-    // hover-revealed actions area; else stamp an empty placeholder. The host
-    // #onClick already excludes [slot="actions"] * from row selection, so
-    // adoption is click-safe.
-    const declaredActions = this.querySelectorAll(':scope > [slot="actions"]');
-    if (declaredActions.length) {
-      for (const a of declaredActions) row.appendChild(a);
-    } else {
-      const actions = document.createElement('span');
-      actions.setAttribute('slot', 'actions');
-      row.appendChild(actions);
-    }
+    // Actions — stamp an empty placeholder; the real declarative [slot="actions"]
+    // children (FEEDBACK-89) are moved into the row by #adoptSlotted(), which
+    // runs in connected() AND on later mutations, so interpolated buttons that
+    // arrive after #stamp (nested in the engine's display:contents wrappers,
+    // FB-96) get adopted too. The placeholder is dropped once a real one lands.
+    // (#onClick excludes [slot="actions"] * from row selection — adoption-safe.)
+    const actions = document.createElement('span');
+    actions.setAttribute('slot', 'actions');
+    actions.dataset.treeActionsPlaceholder = '1';
+    row.appendChild(actions);
 
     this.prepend(row);
   }
@@ -385,4 +401,61 @@ export class UITreeItem extends UIElement {
     const badgeEl = row.querySelector('[slot="badge"]');
     if (badgeEl) badgeEl.textContent = this.badge || '';
   }
+
+  // ── FB-96: wrapper-piercing, late adoption of slotted row children ──
+
+  /**
+   * Collect this item's logical `[slot="<slot>"]` children — direct, or nested
+   * inside the template engine's `display:contents` wrapper spans (which carry
+   * `role="presentation"` since 0.7.2) — but NOT inside a nested `<tree-item-ui>`
+   * (a plain descendant query would wrongly grab a child item's actions/caret).
+   */
+  #logicalSlotChildren(slot) {
+    const out = [];
+    const walk = (parent) => {
+      for (const ch of parent.children) {
+        if (ch.matches('tree-item-ui')) continue;                 // nested-item boundary
+        if (ch.getAttribute('slot') === slot) { out.push(ch); continue; }
+        // pierce the engine's transparent wrapper spans
+        if (ch.matches('[role="presentation"]') || ch.style?.display === 'contents') walk(ch);
+      }
+    };
+    walk(this);
+    return out;
+  }
+
+  /**
+   * Move declarative `[slot="actions"]`/`[slot="caret"]` children into the
+   * stamped row. Idempotent + re-entrancy-guarded (it mutates `this`, which
+   * re-fires #slotObserver). Drops the auto-stamped placeholder/default once a
+   * real child is adopted. (FEEDBACK-89 + FB-96.)
+   */
+  #adoptSlotted() {
+    if (this.#adopting) return;
+    const row = this.querySelector(':scope > [slot="row"]');
+    if (!row) return;
+    this.#adopting = true;
+    try {
+      const actions = this.#logicalSlotChildren('actions')
+        .filter((el) => !el.dataset.treeActionsPlaceholder && el.parentElement !== row);
+      if (actions.length) {
+        row.querySelector(':scope > [slot="actions"][data-tree-actions-placeholder]')?.remove();
+        for (const el of actions) row.appendChild(el);
+      }
+      const caret = this.#logicalSlotChildren('caret')
+        .find((el) => !el.dataset.treeCaretDefault && el.parentElement !== row);
+      if (caret) {
+        row.querySelector(':scope > [slot="caret"][data-tree-caret-default]')?.remove();
+        row.prepend(caret);
+      }
+    } finally {
+      this.#slotObserver?.takeRecords();   // drain self-mutations — no re-entrant pass
+      this.#adopting = false;
+    }
+  }
+
+  disconnected() {
+    this.#slotObserver?.disconnect();
+    this.#slotObserver = null;
+  }
 }

package/components/tree/tree.test.js

@@ -11,6 +11,7 @@ import { html, stamp } from '../../core/template.js';
 
 beforeAll(async () => {
   await import('./tree.js');
+  await import('../button/button.js');
 });
 
 describe('<tree-ui> tree-select forwards modifier keys (FB-46)', () => {
@@ -261,3 +262,51 @@ describe('<tree-item-ui> ARIA tree containment (FEEDBACK-91)', () => {
     expect(parent.querySelector(':scope > [slot="row"]').hasAttribute('aria-selected')).toBe(false);
   });
 });
+
+describe('<tree-item-ui> adopts interpolated [slot="actions"] into the row (FEEDBACK-96)', () => {
+  let host;
+  const settle = () => new Promise((r) => setTimeout(r, 40));
+  beforeEach(() => { host = document.createElement('div'); document.body.appendChild(host); });
+  afterEach(() => host.remove());
+
+  it('moves a `.map()`-rendered actions button into the treeitem row (not a stray child of the group)', async () => {
+    const PALS = [{ id: 'n', name: 'Neutral' }, { id: 'b', name: 'Brand' }];
+    stamp(html`
+      <tree-ui>
+        <tree-item-ui text="Colors" value="colors" open>
+          ${html`<button-ui slot="actions" icon="plus" title="Add"></button-ui>`}
+          ${PALS.map((p) => html`<tree-item-ui text="${p.name}" value="${p.id}"></tree-item-ui>`)}
+        </tree-item-ui>
+      </tree-ui>
+    `, host);
+    await settle();
+
+    const colors = host.querySelector('tree-item-ui[value="colors"]');
+    const row = colors.querySelector(':scope > [slot="row"]');
+    const btn = colors.querySelector('button-ui[slot="actions"]');
+    expect(btn).not.toBeNull();
+    // The fix: the interpolated button (wrapped in a display:contents span) is
+    // adopted INTO the row. Pre-fix, #stamp's `:scope >` query missed it (the
+    // button arrives after #stamp, inside a wrapper span) and it stayed a bare
+    // child of the group/tree → axe aria-required-children.
+    expect(btn.parentElement).toBe(row);
+    // Auto-stamped empty placeholder dropped — exactly one actions slot in the row.
+    expect(row.querySelectorAll(':scope > [slot="actions"]').length).toBe(1);
+    // Nested items NOT mis-adopted as actions (the tree-item-ui boundary holds).
+    expect(host.querySelectorAll('tree-item-ui').length).toBe(3);
+  });
+
+  it('is idempotent — no double-adopt across settles', async () => {
+    stamp(html`
+      <tree-ui>
+        <tree-item-ui text="Colors" value="colors" open>
+          ${html`<button-ui slot="actions" icon="plus"></button-ui>`}
+        </tree-item-ui>
+      </tree-ui>
+    `, host);
+    await settle();
+    await settle();
+    const row = host.querySelector('tree-item-ui[value="colors"] > [slot="row"]');
+    expect(row.querySelectorAll(':scope > [slot="actions"]').length).toBe(1);
+  });
+});

package/core/template.js

@@ -430,6 +430,13 @@ function wrap(part) {
   if (part.n.nodeType === 1 && part.n[PART]) return part.n;
   const c = document.createElement('span');
   c.style.display = 'contents';
+  // ARIA-transparent: display:contents removes the box from layout, but the
+  // span still generates a generic accessibility node — which breaks
+  // required-owned / required-parent relationships when it sits between a
+  // role-bearing parent and role-bearing children rendered via interpolation
+  // (tree→treeitem, menu→menuitem via `.map()`/`repeat()`). role="presentation"
+  // promotes the children to the real parent in the a11y tree. (FB-94 / FB-95)
+  c.setAttribute('role', 'presentation');
   c[PART] = true;
   part.n.replaceWith(c);
   part.n = c;
@@ -453,6 +460,7 @@ function applyValue(p, v) {
         if (isResult(item)) {
           const el = document.createElement('span');
           el.style.display = 'contents';
+          el.setAttribute('role', 'presentation'); // ARIA-transparent — see wrap()
           c.appendChild(el);
           stamp(item, el);
         } else {
@@ -526,6 +534,7 @@ export function repeat(items, keyFn, tplFn) {
         } else {
           const el = document.createElement('span');
           el.style.display = 'contents';
+          el.setAttribute('role', 'presentation'); // ARIA-transparent — see wrap()
           stamp(result, el);
           newMap.set(key, el);
         }

package/core/template.test.js

@@ -573,3 +573,39 @@ describe('html template — FB-57 (v0.6.8) nested SVG/MathML template namespace
     expect(p.namespaceURI).toBe('http://www.w3.org/1999/xhtml');
   });
 });
+
+describe('html template — FB-94/FB-95 (v0.7.x) ARIA-transparent wrapper spans', () => {
+  let container;
+  beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); });
+  afterEach(() => container.remove());
+
+  // The display:contents wrapper span the engine emits for interpolated parts
+  // must carry role="presentation" — display:contents removes the box from
+  // layout but the span still generates a generic a11y node, which breaks
+  // required-owned / required-parent relationships when it sits between a
+  // role-bearing parent and role-bearing children rendered via .map()/repeat()
+  // (tree→treeitem = FB-94, menu→menuitem = FB-95). Verified end-to-end with
+  // axe-core; these lock the substrate behaviour against regression.
+  const isContentsSpan = (s) => /display:\s*contents/.test(s.getAttribute('style') || '');
+
+  it('a `.map()` of templates wraps each item in a role="presentation" display:contents span', () => {
+    stamp(html`<ul>${['a', 'b', 'c'].map((x) => html`<li>${x}</li>`)}</ul>`, container);
+    const spans = [...container.querySelectorAll('span')].filter(isContentsSpan);
+    expect(spans.length).toBeGreaterThan(0);
+    spans.forEach((s) => expect(s.getAttribute('role')).toBe('presentation'));
+  });
+
+  it('a conditional `${cond ? html`` : null}` branch wraps in role="presentation"', () => {
+    stamp(html`<div>${true ? html`<span data-x>hi</span>` : null}</div>`, container);
+    const wrap = [...container.querySelectorAll('div > span')].find(isContentsSpan);
+    expect(wrap).toBeTruthy();
+    expect(wrap.getAttribute('role')).toBe('presentation');
+  });
+
+  it('`repeat()` keyed items wrap in role="presentation"', () => {
+    stamp(html`<ul>${repeat(['a', 'b'], (x) => x, (x) => html`<li>${x}</li>`)}</ul>`, container);
+    const spans = [...container.querySelectorAll('span')].filter(isContentsSpan);
+    expect(spans.length).toBeGreaterThan(0);
+    spans.forEach((s) => expect(s.getAttribute('role')).toBe('presentation'));
+  });
+});