@adia-ai/web-components 0.5.17 → 0.5.19

package/components/swatch/class.js

@@ -192,10 +192,47 @@ export class UISwatch extends UIElement {
   #onHostKey = null;
   #onCopyClick = null;
   #copyResetTimer = null;
+  #chromeObserver = null;
 
   connected() {
     this.#stamp();
     this.#wireInteraction();
+    // §-TBD (v0.5.19, FB-44): observe late-arriving slot="chrome" children
+    // and re-run #absorbChromeSlot(). The parent template's update() walks
+    // attribute/property parts BEFORE child node parts (per core/template.js
+    // scan(): TreeWalker visits element.attributes before descending), so
+    // property assignments fire render() → #syncCore() → #absorbChromeSlot()
+    // while chrome interpolations are still empty placeholder text nodes.
+    // The once-only absorb pass therefore sees an empty set and the chrome
+    // — arriving moments later — sits at its arrival position rather than
+    // the canonical post-tile region. MutationObserver closes this gap for
+    // every arrival path: single-template ordering skew, separate render
+    // cycle, or imperative host.appendChild().
+    this.#chromeObserver = new MutationObserver((mutations) => {
+      let hasChrome = false;
+      for (const m of mutations) {
+        for (const n of m.addedNodes) {
+          if (n.nodeType !== 1) continue;
+          // Direct chrome child OR a display:contents wrapper-span carrying chrome.
+          if (n.getAttribute?.('slot') === 'chrome') { hasChrome = true; break; }
+          if (
+            n.tagName === 'SPAN' &&
+            n.style?.display === 'contents' &&
+            n.querySelector?.('[slot="chrome"]')
+          ) { hasChrome = true; break; }
+        }
+        if (hasChrome) break;
+      }
+      if (!hasChrome) return;
+      // Re-entrancy guard: #absorbChromeSlot() calls insertBefore() which itself
+      // generates childList mutations on the host. Without this guard, every
+      // absorb pass would re-trigger the observer indefinitely. takeRecords()
+      // drains the queue without dispatch so the next observation cycle starts
+      // clean.
+      this.#absorbChromeSlot();
+      this.#chromeObserver.takeRecords();
+    });
+    this.#chromeObserver.observe(this, { childList: true });
   }
 
   render() {
@@ -234,14 +271,45 @@ export class UISwatch extends UIElement {
     const chromeSlot = Array.from(this.children).filter(
       n => n.getAttribute && n.getAttribute('slot') === 'chrome'
     );
-    // Also collect chrome elements nested inside wrapper-spans (template-render path).
-    for (const wrapper of Array.from(this.children)) {
-      if (wrapper.getAttribute?.('slot') === 'chrome') continue;
-      const nested = wrapper.querySelectorAll?.('[slot="chrome"]');
-      if (nested) for (const n of nested) chromeSlot.push(n);
-    }
     for (const n of chromeSlot) n.remove();
 
+    // §341 (v0.5.x, FB-43): preserve display:contents wrapper-spans that
+    // already contain chrome at #stamp() time (rare — typically when a
+    // setup script pre-built the subtree before connect). AdiaUI's `html\`\``
+    // template engine wraps each `${...}` interpolation in a `<span
+    // style="display: contents">` (per `core/template.js:212` `wrap()`);
+    // re-renders update wrapper contents via `part.n`. Detach + re-attach
+    // at canonical position so they survive innerHTML='' below.
+    const chromeWrappers = Array.from(this.children).filter(n =>
+      n.tagName === 'SPAN' &&
+      n.style?.display === 'contents' &&
+      n.querySelector?.('[slot="chrome"]')
+    );
+    for (const w of chromeWrappers) w.remove();
+
+    // §341 (FB-43): preserve template-engine text-node + comment
+    // placeholders. AdiaUI's `scan()` (template.js:113) replaces
+    // `<!--p:N-->` comments with empty text nodes; `wrap()` later
+    // creates `<span style="display: contents">` and replaces the text
+    // node in-place via `replaceWith(part.n, wrapper)`. For that
+    // replaceWith to work, the text node MUST still be attached when
+    // parent's update() runs (it runs AFTER our connectedCallback
+    // synchronously, so AFTER #stamp()). Pre-§341, innerHTML='' below
+    // wiped the text node → replaceWith no-op → wrapper detached →
+    // chrome stamped into a detached subtree (never reaches DOM).
+    //
+    // Fix: extract empty text + comment nodes before the wipe, re-attach
+    // at the canonical chrome region (between tile and badge). Parent's
+    // update() then replaces them with live wrapper-spans in place;
+    // subsequent re-renders update the wrappers in-place too.
+    const placeholders = [];
+    for (const n of Array.from(this.childNodes)) {
+      if ((n.nodeType === 3 && !n.data) || n.nodeType === 8) {
+        placeholders.push(n);
+      }
+    }
+    for (const p of placeholders) p.remove();
+
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
     // `[slot="chrome"]` children are already removed above, so won't appear here.
@@ -279,6 +347,19 @@ export class UISwatch extends UIElement {
     // `position: absolute; top: 2px; right: 2px` and anchor against the host's
     // padding-box, which matches the tile's geometry in the block layout.
     for (const n of chromeSlot) this.appendChild(n);
+    // §341 (FB-43): re-attach chrome-bearing wrapper-spans at canonical
+    // position. Wrapper preserves the template-engine's `part.n`
+    // reference so parent re-renders can update chrome content in-place
+    // without detaching the wrapper.
+    for (const w of chromeWrappers) this.appendChild(w);
+    // §341 (FB-43): re-attach template-engine placeholders at canonical
+    // chrome region. Parent's pending update() will replace each
+    // placeholder with a live wrapper-span (via `wrap(part)`'s
+    // `replaceWith`), landing chrome content visually between tile +
+    // badge. Without this re-attach, the placeholders would have been
+    // wiped by `innerHTML = ''` and the parent's `replaceWith` would
+    // no-op against a detached node.
+    for (const p of placeholders) this.appendChild(p);
 
     // Badge container — holds one or more <span data-badge-variant="..."> children.
     // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
@@ -350,9 +431,18 @@ export class UISwatch extends UIElement {
         this.insertBefore(child, this.#badgeEl);
       }
     }
-    // §331 (v0.5.16, FB-39): also handle wrapper-spanned chrome children
-    // that arrive AFTER #stamp() (parent template's late update() pass).
-    // Hoist them OUT of any non-internal wrapper + into the canonical slot.
+    // §331 (v0.5.16, FB-39): handle wrapper-spanned chrome children that
+    // arrive AFTER #stamp() (parent template's late update() pass).
+    //
+    // §341 (FB-43) refinement: move the WRAPPER to canonical position
+    // rather than hoisting chrome OUT of it. The wrapper is the parent
+    // template engine's `part.n` reference; if we extract chrome, the
+    // next parent re-render lands new chrome inside the now-empty
+    // wrapper at the wrapper's original (non-canonical) position. By
+    // moving the wrapper itself to canonical position, future parent
+    // updates land at the right visual location automatically.
+    // Wrapper is `display: contents` → no layout box → chrome anchors
+    // against the swatch's padding-box correctly.
     for (const child of Array.from(this.children)) {
       if (
         child === this.#tileEl ||
@@ -361,11 +451,12 @@ export class UISwatch extends UIElement {
         child === this.#detailEl ||
         child === this.#copyEl
       ) continue;
-      const nested = child.querySelectorAll?.('[slot="chrome"]');
-      if (!nested || !nested.length) continue;
-      for (const n of nested) {
-        this.insertBefore(n, this.#badgeEl);
-      }
+      // Only move display:contents wrappers that actually carry chrome.
+      const isWrapper = child.tagName === 'SPAN' && child.style?.display === 'contents';
+      if (!isWrapper) continue;
+      const hasNested = child.querySelector?.('[slot="chrome"]');
+      if (!hasNested) continue;
+      this.insertBefore(child, this.#badgeEl);
     }
   }
 
@@ -584,6 +675,10 @@ export class UISwatch extends UIElement {
       clearTimeout(this.#copyResetTimer);
       this.#copyResetTimer = null;
     }
+    if (this.#chromeObserver) {
+      this.#chromeObserver.disconnect();
+      this.#chromeObserver = null;
+    }
     if (this.#onHostClick) this.removeEventListener('click', this.#onHostClick);
     if (this.#onHostKey)   this.removeEventListener('keydown', this.#onHostKey);
     if (this.#copyEl && this.#onCopyClick) this.#copyEl.removeEventListener('click', this.#onCopyClick);

package/components/swatch/swatch.test.js

@@ -175,7 +175,10 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
     // <span style="display: contents"> (per core/template.js:212 `wrap()`).
     // When consumer writes `html`<swatch-ui>${chromeFrag}</swatch-ui>``,
     // the chromeFrag's content lands NESTED inside a wrapper span — not
-    // as direct children of <swatch-ui>. Pre-§331 the chrome was wiped.
+    // as direct children of <swatch-ui>. Pre-§331 the chrome was wiped;
+    // §341 (FB-43) refined to keep chrome INSIDE the wrapper + move the
+    // wrapper to canonical position (preserves template-engine `part.n`
+    // identity so parent re-renders update in-place).
     const swatch = document.createElement('swatch-ui');
     swatch.setAttribute('shape', 'block');
     swatch.setAttribute('label-position', 'overlay');
@@ -196,18 +199,22 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
 
     const found = swatch.querySelector('#wrapped-chrome');
     expect(found).not.toBeNull();
-    // Chrome child should be a direct host sibling positioned between tile + badge.
+    // §341: chrome stays inside the display:contents wrapper; wrapper is
+    // at canonical position (between tile + badge). Visually equivalent
+    // to direct-child placement because display:contents collapses the box.
+    expect(found.parentElement).toBe(wrapper);
+    expect(wrapper.parentElement).toBe(swatch);
     const tile = swatch.querySelector('[data-tile]');
     const badge = swatch.querySelector('[data-badge]');
-    expect(found.parentElement).toBe(swatch);
-    expect(found.previousElementSibling).toBe(tile);
-    expect(found.nextElementSibling).toBe(badge);
+    expect(wrapper.previousElementSibling).toBe(tile);
+    expect(wrapper.nextElementSibling).toBe(badge);
   });
 
   it('handles MULTIPLE chrome children nested in separate wrapper spans', async () => {
     // Each interpolated fragment in html`` gets its own wrapper span,
     // so multi-chrome usage (`${badge}${dot1}${dot2}`) produces multiple
-    // wrapper spans, each containing one chrome child.
+    // wrapper spans, each containing one chrome child. §341: wrappers
+    // stay intact, chrome remains inside them.
     const swatch = document.createElement('swatch-ui');
     swatch.setAttribute('shape', 'block');
     swatch.setAttribute('label-position', 'overlay');
@@ -230,7 +237,10 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
     for (const id of ids) {
       const found = swatch.querySelector(`#${id}`);
       expect(found).not.toBeNull();
-      expect(found.parentElement).toBe(swatch);
+      // §341: chrome stays inside its wrapper; wrapper is a direct child of swatch.
+      expect(found.parentElement.tagName).toBe('SPAN');
+      expect(found.parentElement.style.display).toBe('contents');
+      expect(found.parentElement.parentElement).toBe(swatch);
     }
   });
 
@@ -260,11 +270,15 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
 
     const found = swatch.querySelector('#late-wrapped');
     expect(found).not.toBeNull();
-    expect(found.parentElement).toBe(swatch);
+    // §341: chrome stays inside wrapper; wrapper is now at canonical
+    // position (between tile and badge) after #absorbChromeSlot()'s
+    // re-positioning of the wrapper.
+    expect(found.parentElement).toBe(wrapper);
+    expect(wrapper.parentElement).toBe(swatch);
     const tile = swatch.querySelector('[data-tile]');
     const badge = swatch.querySelector('[data-badge]');
-    expect(found.previousElementSibling).toBe(tile);
-    expect(found.nextElementSibling).toBe(badge);
+    expect(wrapper.previousElementSibling).toBe(tile);
+    expect(wrapper.nextElementSibling).toBe(badge);
   });
 });
 
@@ -329,3 +343,221 @@ describe('<swatch-ui> [auto-contrast] does not override [label-position="overlay
     expect(block).toMatch(/position\s*:\s*absolute/);
   });
 });
+
+describe('<swatch-ui> chrome survives parent template re-render (FB-43 / §341)', () => {
+  // FB-43 (P1): claim is `template.js` mount() replaceChildren() destroys
+  // chrome children on every re-render. The real mechanism is more subtle:
+  // §331's #stamp() does `innerHTML = ''` which wipes the wrapper-span
+  // created by the parent template engine's wrap() (after collecting
+  // chrome into chromeSlot). The parent template's `part.n` still points
+  // to the now-detached wrapper-span. On parent re-render, applyValue()
+  // stamps the new chrome value INTO the detached wrapper-span — landing
+  // in memory but not in the DOM. Chrome is effectively destroyed.
+  //
+  // This empirical test reproduces the exact scenario.
+  let host;
+  let html, stamp;
+
+  beforeAll(async () => {
+    ({ html, stamp } = await import('../../core/template.js'));
+  });
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  // §341 contract: chrome is queryable from swatch + lives inside a
+  // display:contents wrapper-span (the template-engine's stable part.n).
+  // The wrapper sits at canonical chrome position (between tile + badge).
+  // Visually equivalent to direct-child placement because display:contents
+  // collapses the wrapper's box.
+  function assertChromeCanonical(swatch, chrome) {
+    expect(chrome).not.toBeNull();
+    const wrapper = chrome.parentElement;
+    expect(wrapper).not.toBeNull();
+    // The wrapper is the chrome's direct parent + a display:contents span
+    // that's a direct child of the swatch (the template-engine's
+    // wrap()-created stable reference).
+    expect(wrapper.tagName).toBe('SPAN');
+    expect(wrapper.style.display).toBe('contents');
+    expect(wrapper.parentElement).toBe(swatch);
+    // Wrapper sits between tile and badge (canonical chrome region).
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(tile).not.toBeNull();
+    expect(badge).not.toBeNull();
+    // Walk from tile forward: should hit wrapper before badge.
+    let cursor = tile.nextElementSibling;
+    let foundWrapper = false;
+    while (cursor && cursor !== badge) {
+      if (cursor === wrapper) { foundWrapper = true; break; }
+      cursor = cursor.nextElementSibling;
+    }
+    expect(foundWrapper).toBe(true);
+  }
+
+  it('FB-43: chrome interpolated via html`` template survives first render', async () => {
+    const chromeFrag = html`<span slot="chrome" id="fb43-chrome">P3</span>`;
+    const tpl = html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    stamp(tpl, host);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = host.querySelector('#fb43-chrome');
+    expect(found).not.toBeNull();
+    const swatch = host.querySelector('swatch-ui');
+    assertChromeCanonical(swatch, found);
+  });
+
+  it('FB-43: chrome interpolated via html`` template survives second parent re-stamp (same strings)', async () => {
+    // FB-43's core claim: re-render destroys chrome. Same template strings
+    // → stamp() cache should hit → update() runs. Chrome content updates
+    // in-place inside the preserved wrapper-span.
+    function renderOnce(chromeText) {
+      const chromeFrag = html`<span slot="chrome" id="fb43-chrome">${chromeText}</span>`;
+      return html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    }
+    stamp(renderOnce('P3'), host);
+    await new Promise((r) => setTimeout(r, 80));
+    expect(host.querySelector('#fb43-chrome')).not.toBeNull();
+
+    // Re-stamp with same template strings (different value).
+    stamp(renderOnce('OOG'), host);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const swatch = host.querySelector('swatch-ui');
+    const chrome = swatch.querySelector('[slot="chrome"]');
+    expect(chrome).not.toBeNull();
+    expect(chrome.textContent).toBe('OOG');
+    assertChromeCanonical(swatch, chrome);
+  });
+
+  it('FB-43: chrome survives N consecutive re-renders (regression stress test)', async () => {
+    function renderOnce(chromeText) {
+      const chromeFrag = html`<span slot="chrome" id="fb43-chrome">${chromeText}</span>`;
+      return html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    }
+    for (let i = 0; i < 5; i++) {
+      stamp(renderOnce(`label-${i}`), host);
+      await new Promise((r) => setTimeout(r, 60));
+    }
+    const swatch = host.querySelector('swatch-ui');
+    const chrome = swatch.querySelector('[slot="chrome"]');
+    expect(chrome).not.toBeNull();
+    expect(chrome.textContent).toBe('label-4');
+    assertChromeCanonical(swatch, chrome);
+  });
+});
+
+describe('<swatch-ui> chrome absorbed on late arrival (FB-44 / §-TBD)', () => {
+  // FB-44 (P1): #absorbChromeSlot() runs from #syncCore() which only fires
+  // on attribute/property changes. scan() walks element.attributes BEFORE
+  // descending to child nodes, so the parent template's update() loop
+  // assigns properties (→ render() → #syncCore() → #absorbChromeSlot())
+  // BEFORE interpolating child node parts. The once-only absorb pass sees
+  // an empty children set; chrome lands moments later at the arrival
+  // position, not the canonical post-tile region.
+  //
+  // §-TBD adds a MutationObserver on host childList that re-runs
+  // #absorbChromeSlot() when chrome (direct or wrapper-spanned) arrives.
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  // Inline a minimal canonical-position assertion (same shape as the
+  // FB-43 helper but local to this describe block).
+  function assertChromePositionedBeforeBadge(swatch, chrome) {
+    expect(chrome).not.toBeNull();
+    const badge = swatch.querySelector('[data-badge]');
+    expect(badge).not.toBeNull();
+    // The chrome (or its wrapper-span ancestor) should be a child of swatch
+    // that appears before the badge.
+    let chromeChild = chrome;
+    while (chromeChild.parentElement !== swatch && chromeChild.parentElement) {
+      chromeChild = chromeChild.parentElement;
+    }
+    expect(chromeChild.parentElement).toBe(swatch);
+    // Walk siblings from chromeChild forward — badge must be reachable.
+    let cursor = chromeChild;
+    let foundBadge = false;
+    while (cursor) {
+      if (cursor === badge) { foundBadge = true; break; }
+      cursor = cursor.nextElementSibling;
+    }
+    expect(foundBadge).toBe(true);
+  }
+
+  it('FB-44: chrome appended via host.appendChild() after connect lands at canonical position', async () => {
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('color', '#3b82f6');
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // Append chrome AFTER initial #stamp() + #syncCore() pass completed.
+    const badge = document.createElement('span');
+    badge.setAttribute('slot', 'chrome');
+    badge.id = 'fb44-late-chrome';
+    badge.textContent = 'P3';
+    swatch.appendChild(badge);
+    // Wait a microtask for the MutationObserver to fire.
+    await new Promise((r) => setTimeout(r, 30));
+
+    const found = swatch.querySelector('#fb44-late-chrome');
+    assertChromePositionedBeforeBadge(swatch, found);
+  });
+
+  it('FB-44: chrome appended via display:contents wrapper-span after connect lands at canonical position', async () => {
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('color', '#3b82f6');
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // Simulate the template engine's wrap() output: display:contents span
+    // carrying the chrome child as its only descendant.
+    const wrapper = document.createElement('span');
+    wrapper.style.display = 'contents';
+    const badge = document.createElement('span');
+    badge.setAttribute('slot', 'chrome');
+    badge.id = 'fb44-wrapped-chrome';
+    badge.textContent = 'OOG';
+    wrapper.appendChild(badge);
+    swatch.appendChild(wrapper);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const found = swatch.querySelector('#fb44-wrapped-chrome');
+    assertChromePositionedBeforeBadge(swatch, found);
+  });
+
+  it('FB-44: chrome observer is disconnected when host leaves the DOM (leak regression)', async () => {
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('color', '#3b82f6');
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 30));
+
+    // Remove from DOM — disconnected() should disconnect the observer.
+    swatch.remove();
+    await new Promise((r) => setTimeout(r, 30));
+
+    // Subsequent appendChild on the now-orphaned host should not throw,
+    // and re-attaching the swatch should re-arm a fresh observer.
+    document.body.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const badge = document.createElement('span');
+    badge.setAttribute('slot', 'chrome');
+    badge.id = 'fb44-reattach-chrome';
+    swatch.appendChild(badge);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const found = swatch.querySelector('#fb44-reattach-chrome');
+    expect(found).not.toBeNull();
+    assertChromePositionedBeforeBadge(swatch, found);
+    swatch.remove();
+  });
+});

package/components/tree/class.js

@@ -53,13 +53,24 @@ export class UITree extends UIElement {
     return this.querySelector('tree-item-ui[selected]');
   }
 
-  select(item) {
+  // §-TBD (v0.5.19, FB-46): originatingEvent forwards Mouse/KeyboardEvent
+  // modifier state into the dispatched tree-select detail so consumers can
+  // implement Ctrl/Cmd+click multi-select cleanly. Programmatic select()
+  // calls (no event) surface ctrlKey/metaKey/shiftKey as false.
+  select(item, originatingEvent = null) {
     const prev = this.selectedItem;
     if (prev && prev !== item) prev.removeAttribute('selected');
     item.setAttribute('selected', '');
     this.dispatchEvent(new CustomEvent('tree-select', {
       bubbles: true,
-      detail: { item, text: item.text, value: item.value },
+      detail: {
+        item,
+        text: item.text,
+        value: item.value,
+        ctrlKey:  !!originatingEvent?.ctrlKey,
+        metaKey:  !!originatingEvent?.metaKey,
+        shiftKey: !!originatingEvent?.shiftKey,
+      },
     }));
   }
 
@@ -150,7 +161,7 @@ export class UITree extends UIElement {
     if (!row || !(e.target === row || row.contains(e.target))) return;
 
     // Single click: select + toggle if has children
-    this.select(item);
+    this.select(item, e);
     if (item.hasChildren) {
       item.open = !item.open;
     }
@@ -198,7 +209,7 @@ export class UITree extends UIElement {
       case 'Enter':
       case ' ':
         e.preventDefault();
-        this.select(item);
+        this.select(item, e);
         break;
     }
   };

package/components/tree/tree.a2ui.json

@@ -29,12 +29,24 @@
     ],
     "events": {
       "tree-select": {
-        "description": "Fired when an item is selected. detail: { item, text, value }",
+        "description": "Fired when an item is selected. detail: { item, text, value, ctrlKey, metaKey, shiftKey }. Modifier flags mirror the originating MouseEvent / KeyboardEvent; all default false for programmatic select() calls.\n",
         "detail": {
+          "ctrlKey": {
+            "description": "Ctrl key held during activation (false for programmatic select()).",
+            "type": "boolean"
+          },
           "item": {
             "description": "Selected tree-item element.",
             "type": "object"
           },
+          "metaKey": {
+            "description": "Meta (Cmd) key held during activation (false for programmatic select()).",
+            "type": "boolean"
+          },
+          "shiftKey": {
+            "description": "Shift key held during activation (false for programmatic select()).",
+            "type": "boolean"
+          },
           "text": {
             "description": "Item text content.",
             "type": "string"

package/components/tree/tree.d.ts

@@ -13,8 +13,14 @@
 import { UIElement } from '../../core/element.js';
 
 export interface TreeSelectEventDetail {
+  /** Ctrl key held during activation (false for programmatic select()). */
+  ctrlKey: boolean;
   /** Selected tree-item element. */
   item: Record<string, unknown>;
+  /** Meta (Cmd) key held during activation (false for programmatic select()). */
+  metaKey: boolean;
+  /** Shift key held during activation (false for programmatic select()). */
+  shiftKey: boolean;
   /** Item text content. */
   text: string;
   /** Item value attribute. */

package/components/tree/tree.test.js

@@ -0,0 +1,103 @@
+/**
+ * <tree-ui> behavioral tests.
+ *
+ * FB-46 (v0.5.19): tree-select detail now forwards ctrlKey/metaKey/shiftKey
+ * from the originating MouseEvent or KeyboardEvent. Programmatic select()
+ * calls (no event) surface all three as false.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./tree.js');
+});
+
+describe('<tree-ui> tree-select forwards modifier keys (FB-46)', () => {
+  let host;
+  let tree;
+
+  beforeEach(async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+
+    tree = document.createElement('tree-ui');
+    const a = document.createElement('tree-item-ui');
+    a.setAttribute('text', 'Alpha');
+    a.setAttribute('value', 'a');
+    const b = document.createElement('tree-item-ui');
+    b.setAttribute('text', 'Beta');
+    b.setAttribute('value', 'b');
+    tree.appendChild(a);
+    tree.appendChild(b);
+    host.appendChild(tree);
+
+    // Let connectedCallback + #stamp() settle.
+    await new Promise((r) => setTimeout(r, 30));
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('programmatic select() emits ctrlKey/metaKey/shiftKey = false', () => {
+    let received = null;
+    tree.addEventListener('tree-select', (e) => { received = e.detail; });
+
+    const alpha = tree.querySelector('tree-item-ui[value="a"]');
+    tree.select(alpha);
+
+    expect(received).not.toBeNull();
+    expect(received.item).toBe(alpha);
+    expect(received.text).toBe('Alpha');
+    expect(received.value).toBe('a');
+    expect(received.ctrlKey).toBe(false);
+    expect(received.metaKey).toBe(false);
+    expect(received.shiftKey).toBe(false);
+  });
+
+  it('select(item, event) forwards Mouse/KeyboardEvent modifier flags into detail', () => {
+    let received = null;
+    tree.addEventListener('tree-select', (e) => { received = e.detail; });
+
+    const alpha = tree.querySelector('tree-item-ui[value="a"]');
+    // Synthesize an event with all three modifiers held.
+    const fakeEvent = new MouseEvent('click', {
+      ctrlKey: true,
+      metaKey: true,
+      shiftKey: true,
+    });
+    tree.select(alpha, fakeEvent);
+
+    expect(received.ctrlKey).toBe(true);
+    expect(received.metaKey).toBe(true);
+    expect(received.shiftKey).toBe(true);
+  });
+
+  it('detail shape stays backward-compatible (existing fields unchanged)', () => {
+    let received = null;
+    tree.addEventListener('tree-select', (e) => { received = e.detail; });
+
+    const beta = tree.querySelector('tree-item-ui[value="b"]');
+    tree.select(beta);
+
+    // Existing consumers destructure { item, text, value } — those keys
+    // MUST remain present + carry the expected values.
+    const { item, text, value } = received;
+    expect(item).toBe(beta);
+    expect(text).toBe('Beta');
+    expect(value).toBe('b');
+  });
+
+  it('partial modifier state passes through (single key held)', () => {
+    let received = null;
+    tree.addEventListener('tree-select', (e) => { received = e.detail; });
+
+    const alpha = tree.querySelector('tree-item-ui[value="a"]');
+    const onlyMeta = new MouseEvent('click', { metaKey: true });
+    tree.select(alpha, onlyMeta);
+
+    expect(received.ctrlKey).toBe(false);
+    expect(received.metaKey).toBe(true);
+    expect(received.shiftKey).toBe(false);
+  });
+});