@adia-ai/web-components 0.7.7 → 0.7.9

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.9] — 2026-06-03
+
+### Changed
+
+- **`[verse]` control heights bumped one tier — `--a-size` 18/20/24 → 20/24/28px** (sm/md/lg @ density=1). Form-element / control heights in the compact `[verse]` register grow: `--a-size-sm` `1.125→1.250rem`, `--a-size-md` `1.25→1.500rem`, `--a-size-lg` `1.5→1.750rem` (still density-scaled rem). **Behavior change** — inputs / buttons / selects in a `[verse]` context render taller; the `[verse][size]` tier rules inherit the new values (they re-point `--a-size` to the sm/lg token). Verified by `scripts/qa/register-scale-probe.mjs` (verse 20/24/28; regular 24/30/36 + prose 28/36/44 unchanged). **Chrome follows:** `--a-toggle-size` 12/16/20 → 16/20/24, `--a-icon-size` 12/14/16 → 14/16/18, `--a-caret-size` 10/12/14 → 12/14/16 (each +1 tier) so check / radio / switch boxes + select carets + icons stay proportional to the larger controls. File: `styles/verse.css`.
+- **Semantic color tier lift + status-compat removal (the `warning-yellow-cusp-lift`).** Per-family `-strong` tiers moved one step richer (`-50`/`-70` → `-60`) and the `-bg` aliases now read the base family token (`var(--a-accent)` etc.) instead of `-strong`, across accent / brand / info / success / warning (`colors/semantics/core.css` + `colors/parameters.css` + `colors/primitives-warning.css` — the warning yellow's cusp re-tuned for legibility). The legacy `colors/semantics/aliases.css` **STATUS COMPAT block** that overrode `--a-danger` / `--a-success` to `-strong` was **removed** — status families now resolve to their base tier deliberately (base tokens are defined upstream in `core.css`, so non-breaking); the `--a-scrim-*` role aliases in that file are **retained** (modal / drawer / tour / loading-overlay backdrops depend on them). **Behavior change** — danger / success / accent / brand / info surfaces shift tone. Gate-clean: no raw colors, `verify:contrast` + `check:foundation-layers` pass.
+- **CDN bundles rebuilt** — `dist/host.min.css` + `dist/web-components.min.css` regenerated so the color cusp-lift + `[verse]` tier bump reach `@adia-ai/web-components@0.7` CDN consumers.
+
+## [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

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/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);
+}

package/core/logical-children.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { logicalChildren, logicalSlotted } from './logical-children.js';
+
+function host(html) {
+  const el = document.createElement('div');
+  el.innerHTML = html;
+  return el;
+}
+
+describe('logical-children', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('returns static direct children as-is', () => {
+    const h = host(`<button slot="primary">A</button><p>body</p><button slot="secondary">B</button>`);
+    expect(logicalChildren(h).map((e) => e.tagName)).toEqual(['BUTTON', 'P', 'BUTTON']);
+    expect(logicalSlotted(h, 'primary').length).toBe(1);
+    expect(logicalSlotted(h, 'secondary')[0].textContent).toBe('B');
+    expect(logicalSlotted(h, 'missing').length).toBe(0);
+  });
+
+  it('pierces a single display:contents/role=presentation wrapper', () => {
+    const h = host(`
+      <span style="display:contents" role="presentation"><button slot="primary">A</button></span>
+      <p>body</p>
+    `);
+    // Without piercing, h.querySelector(':scope > [slot="primary"]') would be null:
+    expect(h.querySelector(':scope > [slot="primary"]')).toBeNull();
+    // With the helper, it's found:
+    expect(logicalSlotted(h, 'primary').length).toBe(1);
+    expect(logicalChildren(h).map((e) => e.tagName)).toEqual(['BUTTON', 'P']);
+  });
+
+  it('pierces NESTED wrappers (the .map() shape)', () => {
+    const h = host(`
+      <span style="display:contents" role="presentation">
+        <span style="display:contents" role="presentation"><button slot="act">A</button></span>
+        <span style="display:contents" role="presentation"><button slot="act">B</button></span>
+      </span>
+    `);
+    expect(logicalSlotted(h, 'act').map((e) => e.textContent)).toEqual(['A', 'B']);
+  });
+
+  it('does NOT pierce non-wrapper elements (logical = direct, wrappers aside)', () => {
+    const h = host(`<div><button slot="primary">nested-in-real-div</button></div>`);
+    // The button is inside a real <div>, not a transparent wrapper → not a logical child.
+    expect(logicalSlotted(h, 'primary').length).toBe(0);
+    expect(logicalChildren(h).map((e) => e.tagName)).toEqual(['DIV']);
+  });
+
+  it('tolerates a null host', () => {
+    expect(logicalChildren(null)).toEqual([]);
+    expect(logicalSlotted(null, 'x')).toEqual([]);
+  });
+});