@adia-ai/web-components 0.7.6 → 0.7.8

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.8] — 2026-06-02
+
+### Fixed
+
+- **Wrapper-trap drain — 8 components no longer mis-handle `.map()`/interpolated slotted children.** A new shared `core/logical-children.js` (`logicalChildren` / `logicalSlotted`) pierces the template engine's `display:contents` / `role="presentation"` wrapper spans, so consumer slot content supplied via interpolation (`${items.map(…)}` / conditionals) is seen by a component's slot reads — not just static literals. Migrated 14 `:scope > [slot]` direct-child reads that previously missed wrapped content: **`combobox-ui`** (prefix / suffix / empty / loading / footer) + **`input-ui`** (leading / trailing) grabbed affordances then ran `innerHTML = ''`, wiping the wrapped ones (the `agent-artifact-ui` data-loss class); **`nav-group-ui`** (header), **`option-card-ui`** (heading / description / icon), **`timeline-item-ui`** (label), **`step-progress-ui`** (caption / track), and **`date-range-picker-ui`** (presets / footer) used `if (!query) stamp()` guards that false-negatived on a wrapped slot and stamped a DUPLICATE over the consumer's content. Companion field-reads were pierced in lockstep so they don't null-ref. `tree-item-ui`'s `[slot="row"]` is left as-is (a single static / stamped container, not an interpolated collection). New `core/logical-children.test.js` + per-component regression tests; consolidates the prior hand-rolled walks (`select-ui` `#logicalOptionChildren`, `tree-ui` `#logicalSlotChildren`). Files: `core/logical-children.js` + 8 component class files.
+
+### Changed
+- **CDN bundles rebuilt** — `dist/web-components.min.js` regenerated so the wrapper-trap drain (the new `core/logical-children.js` helper + the 14 pierced component reads) reaches `@adia-ai/web-components@0.7` CDN consumers.
+
+## [0.7.7] — 2026-06-02
+
+### Fixed
+
+- **`[verse]` register now scales `--a-toggle-size` (check / radio / switch) down with its type + controls.** Companion to the 0.7.6 `[verse]` icon/caret fix (`91460aae2`). `--a-toggle-size` (the check / radio / switch control size) is declared at `:root` (`styles/foundation/size.css` = `--a-size-sm − --a-space-1` = 20px @md) and shifted by the global `[size]` rules (`styles/api/sizing.css` = 16/24 at sm/lg), but was **absent from `styles/verse.css`** — so in a verse context check / radio / switch chrome stayed the `:root`-computed 20px against verse's smaller (18/20/24) controls and 11/12/13px type. Added `--a-toggle-size` to all three verse sites (base `[verse]` + `[verse][size="lg"]` + `[verse][size="sm"]`) on clean `--a-space` rungs, one tier down: verse toggle is now **12 / 16 / 20px** at sm/md/lg (was a flat 20px); the regular register is unchanged (16/20/24). The explicit `[size]` tier rules are **required** — verse's `context` layer shadows the lower-layer global `[size]` `--a-toggle-size` rules, the same reason `--a-size` and the icon/caret tokens need them. `--a-space` rungs (not literal px like icon/caret) because the toggle targets land exactly on rungs, keeping the values density-aware and consistent with verse's inset/gap. Verified by `scripts/qa/register-scale-probe.mjs` (extended with a toggle axis): verse 12/16/20, regular 16/20/24, all other registers/axes unchanged. Showcased on the `check` / `radio` / `switch` demos (a "Typography registers" section, mirroring the card / button / text / field / badge / stat pages). File: `styles/verse.css`.
+- **`<agent-artifact-ui>` no longer strands `.map()`-rendered action buttons in the body.** `#build()` grabbed the author's `slot="primary"` / `slot="secondary"` buttons with a `:scope > [slot]` direct-child query, then `this.innerHTML = ''`. Buttons supplied via interpolation (`${actions.map(…)}`) arrive nested in the template engine's `display:contents` / `role="presentation"` wrapper spans, so the direct-child grab missed them and the wipe left them rendered in the artifact *body* instead of the header actions cluster. `#build()` now partitions children with a wrapper-piercing logical walk (the FB-92/96/98 pattern, mirroring `select-ui` `#logicalOptionChildren`), so interpolated AND static action buttons both reach the actions cluster. +2 regression tests. Surfaced by `audit-wrapper-trap` arm 2. File: `components/agent-artifact/agent-artifact.class.js`.
+
+### Changed
+
+- **`<drawer-ui>` body inset is now register / size-aware (`--drawer-inset` → `var(--a-inset)`).** `--drawer-inset` hardcoded `var(--a-space-4)` (a literal 16px rung); it now reads `var(--a-inset)`, matching its sibling `card-ui` (`--card-inset: var(--a-inset)`). **Behavior-neutral at the default tier** (`--a-inset-md` == `--a-space-4` == 16px); the change is that the drawer body / header / footer inset (header & footer padding derive from `--drawer-inset`) now scales with `[size]` (sm 14 / lg 18), `[verse]` (12), and `[prose]` (40). drawer's `[padding]` / `[bleed]` are layout *modes* (canvas-bg / no-pad), not a value scale — unchanged. Part of the 0.7.7 inset-alignment audit, which left `page` / `canvas` / `table` filter / `richtext` `pre` as intentional fixed rungs (their literals aren't 16px, so a swap would change behavior). Files: `components/drawer/drawer.css`, `components/drawer/drawer.examples.html`.
+- **CDN bundle rebuilt** — `dist/web-components.min.css` regenerated so the `[verse]` `--a-toggle-size` fix + the drawer inset reach `@adia-ai/web-components@0.7` CDN consumers.
+
 ## [0.7.6] — 2026-06-02
 
 ### Added

package/components/agent-artifact/agent-artifact.class.js

@@ -139,19 +139,35 @@ export class UIAgentArtifact extends UIElement {
     // To keep the Light-DOM approach consistent, we wrap existing children
     // into a body container if one isn't already present.
 
-    // Capture any existing non-slotted children to put into the body wrapper
-    const existingBodyNodes = Array.from(this.childNodes).filter((n) => {
-      if (n.nodeType === 1) {
-        const slot = /** @type {Element} */ (n).getAttribute?.('slot') || '';
-        return slot !== 'primary' && slot !== 'secondary';
+    // Partition the author's children by LOGICAL slot, piercing the template
+    // engine's display:contents / role="presentation" wrapper spans. A consumer
+    // that interpolates the action buttons — `${actions.map(a => html`<button-ui
+    // slot="primary">…`)}` — gets them nested in wrapper spans (core/template.js
+    // wrap()), so the old `:scope > [slot="primary"]` direct-child grab returned
+    // nothing and `innerHTML = ''` stranded them in the body. This is the
+    // wrapper-trap class (FB-92/96/98); walk + pierce so wrapped action buttons
+    // reach the header actions cluster. Wrappers are flattened (display:contents
+    // is layout-transparent); everything non-action becomes body.
+    const primaryBtns = [];
+    const secondaryBtns = [];
+    const bodyNodes = [];
+    const isWrapper = (el) =>
+      el.getAttribute('role') === 'presentation' || el.style?.display === 'contents';
+    const partition = (nodes) => {
+      for (const n of nodes) {
+        if (n.nodeType === 1) {
+          const el = /** @type {Element} */ (n);
+          if (isWrapper(el)) { partition(el.childNodes); continue; } // pierce; drop the wrapper
+          const slot = el.getAttribute('slot') || '';
+          if (slot === 'primary') { primaryBtns.push(el); continue; }
+          if (slot === 'secondary') { secondaryBtns.push(el); continue; }
+        }
+        bodyNodes.push(n);
       }
-      return true;
-    });
-
-    // Clear — we'll rebuild, preserving slotted action buttons
-    const primaryBtns = this.querySelectorAll(':scope > [slot="primary"]');
-    const secondaryBtns = this.querySelectorAll(':scope > [slot="secondary"]');
+    };
+    partition(Array.from(this.childNodes));
 
+    // Clear — we'll rebuild around the captured (now-detached) children.
     this.innerHTML = '';
 
     // Header — keyboard-focusable button-style row that toggles collapsed.
@@ -197,7 +213,7 @@ export class UIAgentArtifact extends UIElement {
     // Body
     this.#bodyEl = document.createElement('div');
     this.#bodyEl.setAttribute('data-artifact-body', '');
-    for (const n of existingBodyNodes) this.#bodyEl.appendChild(n);
+    for (const n of bodyNodes) this.#bodyEl.appendChild(n);
     if (this.collapsed) this.#bodyEl.hidden = true;
 
     this.append(this.#headerEl, this.#bodyEl);

package/components/agent-artifact/agent-artifact.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './agent-artifact.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('agent-artifact-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // Baseline — static slot="primary"/"secondary" buttons route into the header
+  // actions cluster, and the default-slot content lands in the body.
+  it('routes static action buttons into the header actions cluster (not the body)', async () => {
+    const a = mount(`
+      <agent-artifact-ui title="Build">
+        <button-ui slot="primary">Run</button-ui>
+        <button-ui slot="secondary">Cancel</button-ui>
+        <p>Body content</p>
+      </agent-artifact-ui>
+    `);
+    await tick();
+    const actions = a.querySelector('[data-artifact-actions]');
+    const body = a.querySelector('[data-artifact-body]');
+    expect(actions).toBeTruthy();
+    expect(actions.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(2);
+    expect(body.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(0);
+    expect(body.textContent).toContain('Body content');
+  });
+
+  // Wrapper-trap regression (audit-wrapper-trap arm 2): action buttons rendered
+  // via `.map()`/`repeat()` arrive nested in the template engine's
+  // display:contents / role="presentation" wrapper spans. The old `:scope >
+  // [slot="primary"]` direct-child grab missed them, so `innerHTML = ''`
+  // stranded them in the body. They must reach the actions cluster.
+  it('routes WRAPPED (interpolated) action buttons into the actions cluster, not the body', async () => {
+    const a = mount(`
+      <agent-artifact-ui title="Build">
+        <span style="display:contents" role="presentation">
+          <span style="display:contents" role="presentation"><button-ui slot="primary">Run</button-ui></span>
+          <span style="display:contents" role="presentation"><button-ui slot="secondary">Cancel</button-ui></span>
+        </span>
+        <p>Body content</p>
+      </agent-artifact-ui>
+    `);
+    await tick();
+    const actions = a.querySelector('[data-artifact-actions]');
+    const body = a.querySelector('[data-artifact-body]');
+    expect(actions.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(2);
+    // The regression: before the wrapper-pierce fix these landed in the body.
+    expect(body.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(0);
+    expect(body.textContent).toContain('Body content');
+    // No empty wrapper spans left dangling — they're flattened, not re-appended.
+    expect(a.querySelectorAll('[role="presentation"]').length).toBe(0);
+  });
+});

package/components/combobox/combobox.class.js

@@ -40,6 +40,7 @@
 import { UIFormElement } from '../../core/form.js';
 import { anchorPopover } from '../../core/anchor.js';
 import { untracked } from '../../core/signals.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 function escapeHTML(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -213,11 +214,14 @@ export class UICombobox extends UIFormElement {
     const inputId = `${this.#instanceId}-input`;
 
     // Capture consumer-supplied slotted children before innerHTML wipes them.
-    const prefixNodes = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
-    const suffixNodes = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
-    const emptyNodes = Array.from(this.querySelectorAll(':scope > [slot="empty"]'));
-    const loadingNodes = Array.from(this.querySelectorAll(':scope > [slot="loading"]'));
-    const footerNodes = Array.from(this.querySelectorAll(':scope > [slot="footer"]'));
+    // logicalSlotted pierces the template engine's display:contents wrapper spans,
+    // so `.map()`/`repeat()`-interpolated affordances aren't missed then wiped
+    // (the wrapper trap — audit-wrapper-trap arm 2).
+    const prefixNodes = logicalSlotted(this, 'prefix');
+    const suffixNodes = logicalSlotted(this, 'suffix');
+    const emptyNodes = logicalSlotted(this, 'empty');
+    const loadingNodes = logicalSlotted(this, 'loading');
+    const footerNodes = logicalSlotted(this, 'footer');
 
     this.innerHTML = `
       <span data-label id="${labelId}"${this.label ? '' : ' style="display:none"'}>${escapeHTML(this.label || '')}</span>

package/components/combobox/combobox.test.js

@@ -28,6 +28,23 @@ describe('combobox-ui', () => {
     expect(el.options[0].label).toBe('Alpha');
   });
 
+  // Wrapper-trap regression (audit-wrapper-trap arm 2): a `.map()`-interpolated
+  // affordance (here [slot="footer"]) arrives nested in a display:contents
+  // wrapper span. The old `:scope > [slot]` grab missed it → innerHTML='' wiped
+  // it. logicalSlotted pierces the wrapper so the footer survives the rebuild.
+  it('preserves a WRAPPED (interpolated) [slot="footer"] across the rebuild (wrapper trap)', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <span style="display:contents" role="presentation"><div slot="footer" data-test="ft">Footer</div></span>
+      </combobox-ui>
+    `);
+    await tick(); await tick();
+    const footer = el.querySelector('[slot="footer"]');
+    expect(footer).not.toBeNull();
+    expect(footer.dataset.test).toBe('ft');
+  });
+
   it('honours <option selected> as initial value', async () => {
     const el = mount(`
       <combobox-ui>

package/components/date-range-picker/date-range-picker.class.js

@@ -40,6 +40,7 @@
 import { UIFormElement } from '../../core/form.js';
 import { anchorPopover } from '../../core/anchor.js';
 import { untracked } from '../../core/signals.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 const MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const MONTHS_LONG  = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
@@ -392,7 +393,7 @@ export class UIDateRangePicker extends UIFormElement {
       this.#popoverRef.appendChild(calArea);
     }
     // Preset rail (unless author supplied [slot="presets"] OR no-presets is set).
-    const authorPresets = this.querySelector(':scope > [slot="presets"]');
+    const authorPresets = logicalSlotted(this, 'presets')[0];
     if (authorPresets && authorPresets.parentElement !== this.#popoverRef) {
       this.#popoverRef.appendChild(authorPresets);
       this.#presetRailRef = authorPresets;
@@ -425,7 +426,7 @@ export class UIDateRangePicker extends UIFormElement {
     this.#calFromRef = calArea.querySelector(':scope > [data-cal-from]');
     this.#calToRef = calArea.querySelector(':scope > [data-cal-to]');
     // Footer slot — author-supplied; lift into popover after calendar area.
-    const authorFooter = this.querySelector(':scope > [slot="footer"]');
+    const authorFooter = logicalSlotted(this, 'footer')[0];
     if (authorFooter && authorFooter.parentElement !== this.#popoverRef) {
       this.#popoverRef.appendChild(authorFooter);
     }
@@ -477,7 +478,7 @@ export class UIDateRangePicker extends UIFormElement {
 
     // Render the preset rail (unless overridden by [slot="presets"] or
     // hidden via [no-presets]).
-    if (!this.querySelector(':scope > [slot="presets"]')) {
+    if (!logicalSlotted(this, 'presets').length) {
       if (this.noPresets) {
         this.#presetRailRef?.remove();
         this.#presetRailRef = null;

package/components/drawer/drawer.css

@@ -19,7 +19,7 @@
   /* ── Geometry ── */
   --drawer-width:       24rem;
   --drawer-height:      24rem;
-  --drawer-inset:       var(--a-space-4);
+  --drawer-inset:       var(--a-inset);
   --drawer-header-pad:  var(--drawer-inset);
   --drawer-footer-pad:  var(--drawer-inset);
   --drawer-header-gap:  var(--a-space-2);

package/components/input/input.class.js

@@ -52,6 +52,7 @@
 
 import { UIFormElement } from '../../core/form.js';
 import { isIconName, whenIconRegistryReady } from '../../core/icons.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 const renderAffix = (v) => isIconName(v)
   ? `<icon-ui name="${v}"></icon-ui>`
@@ -133,11 +134,13 @@ export class UIInput extends UIFormElement {
     // §199 (v0.5.7): consumer-supplied leading/trailing buttons live as
     // direct children of <input-ui> at author time. Capture references
     // BEFORE innerHTML wipes them, so we can move them into [slot="field"]
-    // after the shell is built. Querying `:scope > [slot="leading|trailing"]`
-    // (direct-child) avoids matching anything we already moved on a prior
-    // re-render.
-    const leadingNodes = Array.from(this.querySelectorAll(':scope > [slot="leading"]'));
-    const trailingNodes = Array.from(this.querySelectorAll(':scope > [slot="trailing"]'));
+    // after the shell is built. logicalSlotted pierces the template engine's
+    // display:contents wrapper spans (so `.map()`-interpolated affordances
+    // aren't missed then wiped — the wrapper trap), and still won't re-match
+    // nodes already moved into the field (those nest in a real element, not a
+    // transparent wrapper).
+    const leadingNodes = logicalSlotted(this, 'leading');
+    const trailingNodes = logicalSlotted(this, 'trailing');
 
     if (!this.querySelector('[slot="text"]')) {
       const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';

package/components/input/input.test.js

@@ -68,6 +68,22 @@ describe('input-ui — §199 leading/trailing affordance slots', () => {
     expect(el.querySelector(':scope > [slot="leading"]')).toBeNull();
   });
 
+  // Wrapper-trap regression (audit-wrapper-trap arm 2): a `.map()`-interpolated
+  // affordance arrives nested in a display:contents/role=presentation wrapper
+  // span. The old `:scope > [slot]` direct-child grab missed it, so innerHTML=''
+  // wiped it. logicalSlotted pierces the wrapper → it reaches the field.
+  it('moves a WRAPPED (interpolated) [slot="trailing"] into the field (wrapper trap)', () => {
+    const el = mount(`
+      <input-ui value="Theme 1" suffix="Light">
+        <span style="display:contents" role="presentation"><button slot="trailing" data-test="open" aria-label="Open">↗</button></span>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const trailing = field.querySelector(':scope > [slot="trailing"]');
+    expect(trailing).not.toBeNull();
+    expect(trailing.dataset.test).toBe('open');
+  });
+
   it('positions trailing after suffix and before controls (number mode)', () => {
     const el = mount(`
       <input-ui type="number" value="42" suffix="kg">

package/components/nav-group/nav-group.class.js

@@ -27,6 +27,7 @@
 
 import { UIElement } from '../../core/element.js';
 import { anchorPopover } from '../../core/anchor.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 export class UINavGroup extends UIElement {
   static properties = {
@@ -59,7 +60,7 @@ export class UINavGroup extends UIElement {
   connected() {
     this.setAttribute('role', 'group');
 
-    if (!this.querySelector(':scope > [slot="header"]')) {
+    if (!logicalSlotted(this, 'header').length) {
       this.#headerEl = document.createElement('div');
       this.#headerEl.setAttribute('slot', 'header');
       this.#headerEl.setAttribute('tabindex', '0');
@@ -71,7 +72,7 @@ export class UINavGroup extends UIElement {
       `;
       this.prepend(this.#headerEl);
     } else {
-      this.#headerEl = this.querySelector(':scope > [slot="header"]');
+      this.#headerEl = logicalSlotted(this, 'header')[0];
     }
 
     this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);

package/components/nav-group/nav-group.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './nav-group.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mount(html) {
+  const w = document.createElement('div');
+  w.innerHTML = html;
+  document.body.appendChild(w);
+  return w.firstElementChild;
+}
+
+describe('nav-group-ui — header stamp-if-absent (wrapper trap)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('stamps a header when the consumer provides none', async () => {
+    const el = mount('<nav-group-ui text="Reports"></nav-group-ui>');
+    await tick();
+    expect(el.querySelectorAll('[slot="header"]').length).toBe(1);
+  });
+
+  // Regression (audit-wrapper-trap arm 2): a `.map()`/conditional-interpolated
+  // [slot="header"] arrives nested in a display:contents wrapper. The old
+  // `:scope > [slot="header"]` absence check missed it and stamped a DUPLICATE.
+  it('does NOT stamp a duplicate when a WRAPPED consumer header is present', async () => {
+    const el = mount(`<nav-group-ui text="Reports"><span style="display:contents" role="presentation"><div slot="header" data-test="h">Custom</div></span></nav-group-ui>`);
+    await tick();
+    const headers = el.querySelectorAll('[slot="header"]');
+    expect(headers.length).toBe(1);
+    expect(headers[0].dataset.test).toBe('h');
+  });
+});

package/components/option-card/option-card.class.js

@@ -45,6 +45,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 export class UIOptionCard extends UIFormElement {
   static properties = {
@@ -97,21 +98,21 @@ export class UIOptionCard extends UIFormElement {
   /** Stamp heading / description / icon from attributes when the
    *  consumer hasn't already provided slotted content. */
   #ensureLayout() {
-    if (this.heading && !this.querySelector(':scope > [slot="heading"]')) {
+    if (this.heading && !logicalSlotted(this, 'heading').length) {
       const el = document.createElement('span');
       el.setAttribute('slot', 'heading');
       el.dataset.fromAttr = 'true';
       el.textContent = this.heading;
       this.appendChild(el);
     }
-    if (this.description && !this.querySelector(':scope > [slot="description"]')) {
+    if (this.description && !logicalSlotted(this, 'description').length) {
       const el = document.createElement('span');
       el.setAttribute('slot', 'description');
       el.dataset.fromAttr = 'true';
       el.textContent = this.description;
       this.appendChild(el);
     }
-    if (this.icon && !this.querySelector(':scope > [slot="icon"]')) {
+    if (this.icon && !logicalSlotted(this, 'icon').length) {
       const el = document.createElement('icon-ui');
       el.setAttribute('slot', 'icon');
       el.dataset.fromAttr = 'true';

package/components/option-card/option-card.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './option-card.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mount(html) {
+  const w = document.createElement('div');
+  w.innerHTML = html;
+  document.body.appendChild(w);
+  return w.firstElementChild;
+}
+
+describe('option-card-ui — heading/description stamp-if-absent (wrapper trap)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('stamps heading + description from attrs when no slots are provided', async () => {
+    const el = mount('<option-card-ui heading="Pro" description="Best value"></option-card-ui>');
+    await tick();
+    expect(el.querySelectorAll('[slot="heading"]').length).toBe(1);
+    expect(el.querySelectorAll('[slot="description"]').length).toBe(1);
+  });
+
+  // Regression (audit-wrapper-trap arm 2): a WRAPPED consumer [slot="heading"]
+  // override must suppress the attr-stamp, not collide with it.
+  it('does NOT stamp a duplicate heading when a WRAPPED consumer heading is present', async () => {
+    const el = mount(`<option-card-ui heading="Pro"><span style="display:contents" role="presentation"><h3 slot="heading" data-test="h">Custom</h3></span></option-card-ui>`);
+    await tick();
+    const headings = el.querySelectorAll('[slot="heading"]');
+    expect(headings.length).toBe(1);
+    expect(headings[0].dataset.test).toBe('h');
+  });
+});

package/components/step-progress/step-progress.class.js

@@ -30,6 +30,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 export class UIStepProgress extends UIElement {
   static properties = {
@@ -48,7 +49,7 @@ export class UIStepProgress extends UIElement {
     this.setAttribute('aria-valuemin', '0');
 
     // Auto-mint internal structure if the consumer didn't provide custom slots.
-    if (!this.querySelector(':scope > [slot="caption"]') && !this.querySelector(':scope > [slot="track"]')) {
+    if (!logicalSlotted(this, 'caption').length && !logicalSlotted(this, 'track').length) {
       this.#captionEl = document.createElement('span');
       this.#captionEl.setAttribute('slot', 'caption');
       this.appendChild(this.#captionEl);
@@ -57,8 +58,8 @@ export class UIStepProgress extends UIElement {
       this.#trackEl.setAttribute('slot', 'track');
       this.appendChild(this.#trackEl);
     } else {
-      this.#captionEl = this.querySelector(':scope > [slot="caption"]');
-      this.#trackEl = this.querySelector(':scope > [slot="track"]');
+      this.#captionEl = logicalSlotted(this, 'caption')[0];
+      this.#trackEl = logicalSlotted(this, 'track')[0];
     }
   }
 

package/components/step-progress/step-progress.test.js

@@ -115,4 +115,15 @@ describe('step-progress-ui', () => {
     const el = mount('<step-progress-ui value="3" total="10"></step-progress-ui>');
     expect(() => el.remove()).not.toThrow();
   });
+
+  // Regression (audit-wrapper-trap arm 2): WRAPPED consumer [slot="caption"] +
+  // [slot="track"] (e.g. via `.map()`/conditional interpolation) must be seen by
+  // the absence check so it doesn't MINT duplicates over the consumer's slots.
+  it('does NOT mint duplicates when WRAPPED consumer caption + track are present', async () => {
+    const el = mount(`<step-progress-ui value="2" total="5"><span style="display:contents" role="presentation"><span slot="caption" data-test="c">Custom</span><div slot="track" data-test="t"></div></span></step-progress-ui>`);
+    await tick();
+    expect(el.querySelectorAll('[slot="caption"]').length).toBe(1);
+    expect(el.querySelectorAll('[slot="track"]').length).toBe(1);
+    expect(el.querySelector('[slot="caption"]').dataset.test).toBe('c');
+  });
 });

package/components/timeline/timeline.class.js

@@ -56,6 +56,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { logicalSlotted } from '../../core/logical-children.js';
 
 // ── Container ──────────────────────────────────────────────────
 
@@ -104,7 +105,7 @@ export class UITimelineItem extends UIElement {
   }
 
   connected() {
-    if (!this.querySelector(':scope > [slot="label"]')) {
+    if (!logicalSlotted(this, 'label').length) {
       // Author provided just text/time — stamp the default slot structure
       this.innerHTML = `
         <span slot="label"></span>

package/components/timeline/timeline.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './timeline.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mount(html) {
+  const w = document.createElement('div');
+  w.innerHTML = html;
+  document.body.appendChild(w);
+  return w.firstElementChild;
+}
+
+describe('timeline-item-ui — label stamp-if-absent (wrapper trap)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('stamps the label structure when the consumer provides none', async () => {
+    const el = mount('<timeline-item-ui text="Shipped"></timeline-item-ui>');
+    await tick();
+    expect(el.querySelectorAll('[slot="label"]').length).toBe(1);
+  });
+
+  // Regression (audit-wrapper-trap arm 2): a WRAPPED consumer [slot="label"]
+  // must suppress the default-structure stamp, not produce a duplicate label.
+  it('does NOT stamp a duplicate when a WRAPPED consumer label is present', async () => {
+    const el = mount(`<timeline-item-ui text="Shipped"><span style="display:contents" role="presentation"><span slot="label" data-test="l">Custom</span></span></timeline-item-ui>`);
+    await tick();
+    const labels = el.querySelectorAll('[slot="label"]');
+    expect(labels.length).toBe(1);
+    expect(labels[0].dataset.test).toBe('l');
+  });
+});

package/components/tree/tree.class.js

@@ -297,6 +297,13 @@ export class UITreeItem extends UIElement {
     // required parent, and the row's required `group` parent is the host.
     this.setAttribute('role', 'group');
 
+    // [slot="row"] is a SINGLE per-item container — supplied statically or
+    // component-stamped, never a `.map()` collection. A full wrapper-pierce would
+    // have to migrate all 9 focus / keyboard-nav row reads in lockstep
+    // (`item.querySelector(':scope > [slot="row"]')`), or nav breaks for a wrapped
+    // row — high regression risk for a rare interpolated-single-row case (the
+    // common path, actions / caret, is already FB-96-handled below).
+    // wrapper-trap-ok: row is static / stamped, not an interpolated collection.
     if (!this.querySelector(':scope > [slot="row"]')) {
       this.#stamp();
     }

package/core/logical-children.js

@@ -0,0 +1,55 @@
+/**
+ * core/logical-children.js — wrapper-piercing light-DOM child access.
+ *
+ * The template engine wraps EVERY interpolated value — a single result OR a
+ * `.map()` / `repeat()` array — in a `display:contents` / `role="presentation"`
+ * span (core/template.js `wrap()` + the Array branch). So a `:scope > [slot="X"]`
+ * direct-child query (or a `for (… of this.children)` loop) MISSES interpolated
+ * slotted children: they arrive as grand-children of a wrapper span, not direct
+ * children of the host. This is the recurring "wrapper trap" (FB-92 menu #show,
+ * FB-96 tree #stamp, FB-98 select #parseOptions, agent-artifact actions).
+ * `scripts/dev/audit-wrapper-trap.mjs` flags the un-pierced reads.
+ *
+ * `logicalChildren(host)` returns the host's LOGICAL direct children — its
+ * direct element children, but recursing THROUGH (and dropping) the transparent
+ * wrapper spans — so interpolated and static children read identically.
+ * `logicalSlotted(host, name)` filters those to `slot="<name>"`.
+ *
+ * Consolidates the per-component hand-rolled walks (select `#logicalOptionChildren`,
+ * tree `#logicalSlotChildren`) into one tested helper.
+ */
+
+/** A transparent template-engine wrapper span (never authored by a consumer). */
+const isWrapper = (el) =>
+  el.getAttribute?.('role') === 'presentation' || el.style?.display === 'contents';
+
+/**
+ * The host's logical direct element children, piercing display:contents /
+ * role="presentation" wrapper spans (depth-first, wrappers flattened away).
+ * @param {Element} host
+ * @returns {Element[]}
+ */
+export function logicalChildren(host) {
+  const out = [];
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      if (n.nodeType !== 1) continue;        // elements only (slotted children are elements)
+      if (isWrapper(n)) { walk(n.children); continue; } // pierce + drop the wrapper
+      out.push(n);
+    }
+  };
+  if (host) walk(host.children);
+  return out;
+}
+
+/**
+ * Logical direct children carrying `slot="<slotName>"`, wrapper-pierced.
+ * Use `.length` for a stamp-if-absent guard, `[0]` for the single case, or the
+ * array for a collection grab — all safe against interpolated content.
+ * @param {Element} host
+ * @param {string} slotName
+ * @returns {Element[]}
+ */
+export function logicalSlotted(host, slotName) {
+  return logicalChildren(host).filter((el) => el.getAttribute('slot') === slotName);
+}