@adia-ai/web-components 0.5.18 → 0.5.19

package/CHANGELOG.md

@@ -11,6 +11,23 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.19] - 2026-05-17
+
+### Added
+- §348 (FB-51 #3; P3) — `<description-list-ui>` `align="stretch"` enum value (joins `start`, `between`). For `layout="inline"`, sets `justify-self: stretch` + `width: 100%` on `<dd>` (and `width: 100%` on its direct children) so block-level form controls — `<slider-ui>`, `<select-ui>`, `<color-picker-ui>` — reach the column edge rather than shrink-wrapping to content. Closes the Tokens Studio dts-right-panel migration path for property-row pairs where the value is a control, not text. Schema + generated `.d.ts` + `a2ui.json` updated. NEW `description-list.test.js` with 3 cases (CSS source contract, host attribute precondition, yaml enum shape).
+- §347 (FB-50 #3; P3) — `<command-ui>` `select` event detail now carries `category` from the parent `<optgroup label="…">`. Items without a group surface `category = ''` so destructuring stays safe. Schema (`command.yaml`) + generated `.d.ts` + `a2ui.json` updated. Closes Tokens Studio's consumer pattern of routing selected commands by section (Navigation / Edit / etc.) without re-walking the DOM to find the parent optgroup label.
+- §342 (FB-44; P1) — `<swatch-ui>` `MutationObserver` for late-arriving `[slot="chrome"]` children. `#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 therefore sees an empty children set and chrome — arriving moments later — sits at its arrival position rather than the canonical post-tile region. Fix: arm a `MutationObserver` on host `childList` in `connected()` that re-runs `#absorbChromeSlot()` whenever a direct `[slot="chrome"]` child OR a `display:contents` wrapper-span containing chrome is added. Observer is torn down in `disconnected()`. Closes the post-§341 follow-up gap in Tokens Studio's C1.3 main-palette dogfood (gamut badges + override / tracked dots invisible despite §341 placeholder-preservation). 3 NEW vitest cases in `swatch.test.js`'s `FB-44 / §-TBD` describe block.
+- §343 (FB-46; P2) — `<tree-ui>` `tree-select` event detail now forwards `ctrlKey` / `metaKey` / `shiftKey` from the originating `MouseEvent` or `KeyboardEvent`. Unblocks consumer-side Ctrl/Cmd+click multi-select implementations (Tokens Studio token-tree). `select(item, originatingEvent = null)` is the new public signature; programmatic calls (no event) surface all three modifiers as `false`. Schema (`tree.yaml`) + generated `.d.ts` + `a2ui.json` updated. 4 NEW vitest cases in new `tree.test.js`. Backward-compatible: existing `detail.{item,text,value}` shape unchanged; new fields are additive.
+
+### Tests
+- §344 (FB-47; partial / misdiagnosed) — 3 NEW vitest cases in `core/template.test.js`'s `FB-47` describe block lock the actual contract: (1) `stamp()` with same template strings reuses the mounted instance (no `replaceChildren()`); (2) `repeat()` with same key preserves wrapper children across re-renders; (3) the `Array.isArray(v)` branch in `applyValue()` DOES rebuild on every re-render (the actual `.map()` destruction surface, documented behavior). The FB-47 author's "`stamp()` is unconditional" + "`repeat()` keyed diffing defeated" claims are empirically false; the tests pin current behavior to catch future drift. See RESPONSE-47 for the consumer-side `.map()` → `repeat()` migration recommendation.
+- §347 (FB-50 #3) — NEW `command.test.js` (first dedicated test file for `<command-ui>`) with 3 cases: emits `category=""` for ungrouped options, emits `category="<optgroup label>"` for items inside an optgroup, backward-compat `{ value, label }` destructuring still works. 3/3 passing.
+
+### Docs
+- USAGE.md — new `§345 (v0.5.19) — .map() vs repeat() for reactive lists (FB-47)` section under the template parser invariants. Documents the keyed-reuse contract, when `repeat()` matters, and the key-selection guidance (use a stable consumer-supplied identifier, NOT array index).
+- USAGE.md — new `§349 (v0.5.19) — Event handling inside reactive lists (FB-49)` section. Explains that `closest()` works through `display:contents` wrapper-spans (DOM walk, not box walk) for typical bubble-phase handlers; reserves `composedPath()` for cross-subtree / shadow-DOM / whitespace-retarget cases with explicit examples. Closes the documentation gap that caused three consumer `composedPath()` workarounds in Tokens Studio to ship without rationale.
+- §346 — NEW `components/command/USAGE.md` (FB-50 #1) — first dedicated USAGE doc for `<command-ui>`. Documents the native `<option data-shortcut data-icon>` content API (the actual shape; there is no `command-item-ui` custom element), the `<optgroup label>` grouping pattern, the new `category` field in `select` detail (per FB-50 #3 above), the Cmd+K wiring pattern, `setItems()` imperative API, recent-items behavior, and the `empty` + `footer` slots. Closes Tokens Studio's discoverability gap that drove ~350 LOC of hand-rolled `<dts-command-palette>` fallback.
+
 ## [0.5.18] - 2026-05-16
 
 ### Fixed

package/USAGE.md

@@ -1086,6 +1086,74 @@ Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective
 - HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
 - Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
 
+### §-TBD (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
+
+Use **`repeat(items, keyFn, tplFn)`** for any list whose items are signal-driven and should preserve identity across re-renders. Plain `.map()` returns an `Array` of template results, which the template engine materializes via `container.replaceChildren()` on every parent update — correct, but per-item DOM is re-created from scratch.
+
+```js
+import { html, repeat } from '@adia-ai/web-components/core/element';
+
+// ❌ .map() — every re-render destroys and re-creates each wrapper-span
+html`
+  <div class="row">
+    ${stops.map(stop => renderSwatch(stop))}
+  </div>
+`;
+
+// ✅ repeat() — wrapper-spans + child custom elements preserved across re-renders
+html`
+  <div class="row">
+    ${repeat(stops, stop => stop.key, stop => renderSwatch(stop))}
+  </div>
+`;
+```
+
+**When `repeat()` matters:**
+
+- Lists of custom elements with internal state (`<swatch-ui>` with chrome slots, `<chat-thread>` with scroll position, `<select-ui>` with focus).
+- Lists where re-creation causes flicker (animations restart, transitions interrupt, IntersectionObservers re-fire).
+- Long lists (≥10 items) where per-item DOM allocation costs add up under signal-driven update churn.
+
+**Mechanism:** `repeat()` keys each item by `keyFn(item)` and stores wrapper-spans in a key-indexed map on the container. On re-render with the same key, the wrapper is reused; `stamp()` falls through to its same-strings cache hit and only `update()`s the parts in-place. With `.map()`, there is no key channel — the runtime cannot tell which result corresponds to which prior item, so it conservatively rebuilds every wrapper.
+
+**Key selection:** pick a stable consumer-supplied identifier (database id, slot.key, etc.), NOT array index. Array indices are unstable under insert/remove and defeat the keyed-reuse contract.
+
+### §-TBD (v0.5.19) — Event handling inside reactive lists (FB-49)
+
+Custom-element children rendered inside `repeat()` (or as an `${array}` interpolation) are each wrapped in a `<span style="display:contents">` by the template engine. These wrapper spans generate no boxes (`display:contents`) and cannot be click targets, but they ARE in the DOM tree.
+
+For most consumer event handlers, this is transparent. `Element.closest()` walks the **DOM tree** (not the box tree), so `display:contents` ancestors are walked through normally:
+
+```js
+// ✅ Bubble-phase listener on or inside the list — closest() works fine
+tree.addEventListener('tree-select', (e) => {
+  const item = e.detail.item;  // tree-ui already does the right walk for you
+});
+
+// ✅ Bubble-phase listener on a parent — closest() walks past display:contents wrappers
+host.addEventListener('click', (e) => {
+  const item = e.target.closest('tree-item-ui');
+  if (item && host.contains(item)) { /* … */ }
+});
+```
+
+Reach for `e.composedPath()` only when one of these specific cases applies:
+
+1. **Cross-subtree listeners.** If the listener's host is in a different subtree than the items (capture-phase on an ancestor far above), `closest()` walks UP from `e.target` but doesn't tell you which descendant of the listener's host was clicked. `composedPath()` returns the full leaf-to-document chain — filter that for the descendant tag you want.
+2. **Crossing shadow-DOM boundaries.** If `e.target` is retargeted to a shadow host (per the shadow DOM spec), `closest()` walks the light-DOM ancestor chain from that host. `composedPath()` exposes the actual leaf inside the shadow root.
+3. **Click on whitespace between list items.** Text nodes sometimes retarget to their parent element. If the parent is a `display:contents` wrapper-span, `closest('your-tag')` from that wrapper returns null (the wrapper's siblings include your tag, but not its descendants). `composedPath()` gives sibling context to walk.
+
+```js
+// ✅ For capture-phase / cross-subtree / shadow-DOM cases
+host.addEventListener('click', (e) => {
+  const item = e.composedPath().find(
+    (el) => el?.tagName?.toLowerCase() === 'tree-item-ui' && host.contains(el)
+  );
+}, { capture: true });
+```
+
+**Don't reach for `composedPath()` reflexively** — it rebuilds the full path on every call and is slower than `closest()`. Default to `closest()` for direct bubble-phase handlers; use `composedPath()` only when one of the three cases above applies.
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):

package/components/command/USAGE.md

@@ -0,0 +1,160 @@
+# `<command-ui>` — Searchable command palette
+
+`<command-ui>` is a searchable command palette with keyboard navigation, recent-items memory, and grouped sections. It accepts **native `<option>` and `<optgroup>` children** as its content API — no custom element wrappers around items.
+
+```html
+<command-ui open placeholder="Type a command…">
+  <optgroup label="Navigation">
+    <option value="home" data-icon="house" data-shortcut="⌘H">Go Home</option>
+    <option value="settings" data-icon="gear" data-shortcut="⌘,">Settings</option>
+  </optgroup>
+  <optgroup label="Edit">
+    <option value="undo" data-icon="arrow-counter-clockwise" data-shortcut="⌘Z">Undo</option>
+    <option value="redo" data-icon="arrow-clockwise" data-shortcut="⌘⇧Z">Redo</option>
+  </optgroup>
+  <option value="logout" data-icon="sign-out" data-shortcut="⌘⇧Q">Log out</option>
+</command-ui>
+```
+
+## Why native `<option>`
+
+The native option semantics carry through to screen readers automatically, mirror the form-control patterns consumers already know, and inherit standard `disabled` handling. The alternative — a `<command-item-ui>` custom element — would duplicate the surface without adding capability.
+
+If you're coming from a primitive that uses `*-item-ui` children (e.g. `<tree-item-ui>` inside `<tree-ui>`, `<menu-item-ui>` inside `<menu-ui>`), the `<option>`-based API here is the deliberate exception. Other primitives ship custom-element children because their item state (open / selected / expanded) is rich; commands are stateless declarative entries.
+
+## Attributes
+
+| On `<command-ui>` | Type | Default | Description |
+|---|---|---|---|
+| `open` | boolean | `false` | Whether the palette is visible (reflected — set via property or attribute). |
+| `placeholder` | string | `Type a command…` | Search input placeholder. |
+
+| On each `<option>` | Description |
+|---|---|
+| `value` | Identifier emitted in the `select` event detail. |
+| `data-icon` | Phosphor icon name (rendered as `<icon-ui>` to the left of the label). |
+| `data-shortcut` | Keyboard shortcut hint string (rendered to the right, e.g. `⌘K`, `⇧E`). Display-only — wiring the actual shortcut is the consumer's responsibility (see "Wiring a global Cmd+K trigger" below). |
+| `data-keywords` | Extra space-separated keywords folded into the search index alongside the label. |
+| `disabled` | Boolean — render as inactive, skipped during keyboard navigation. |
+
+| On each `<optgroup>` | Description |
+|---|---|
+| `label` | Section heading. Propagates to `event.detail.category` on selection (§-TBD / FB-50 #3, v0.5.19+). |
+
+## Events
+
+```ts
+type CommandSelectDetail = {
+  value: string;     // option's [value]
+  label: string;     // option's text content
+  category: string;  // parent <optgroup label="…"> label, or '' if the option has no group
+};
+```
+
+```js
+palette.addEventListener('select', (e) => {
+  const { value, label, category } = e.detail;
+  switch (category) {
+    case 'Navigation': router.navigate(value); break;
+    case 'Edit':       editor.invoke(value);   break;
+    default:           runCommand(value);
+  }
+});
+
+palette.addEventListener('dismiss', () => {
+  // User pressed Escape — close it
+  palette.open = false;
+});
+```
+
+The palette doesn't auto-close on selection — the consumer decides whether to stay open (multi-action flow) or dismiss (typical single-action flow):
+
+```js
+palette.addEventListener('select', () => { palette.open = false; });
+```
+
+## Slots
+
+| Slot | What goes inside |
+|---|---|
+| `empty` | Shown when the filter has no matches. Use for a "No commands match" affordance or a "Create new" call-to-action. |
+| `footer` | Persistent footer band — usually a `<kbd>` hint bar like `↑↓ to navigate · ↵ to select · esc to close`. |
+
+```html
+<command-ui open placeholder="Type a command…">
+  <option value="…">…</option>
+
+  <div slot="empty">
+    <text-ui variant="caption" muted>No commands match — try a different search.</text-ui>
+  </div>
+
+  <div slot="footer">
+    <kbd>↑</kbd> <kbd>↓</kbd> navigate · <kbd>↵</kbd> select · <kbd>esc</kbd> close
+  </div>
+</command-ui>
+```
+
+## Wiring a global Cmd+K trigger
+
+Common pattern — global keyboard listener flips the `[open]` property:
+
+```js
+const palette = document.querySelector('command-ui');
+
+window.addEventListener('keydown', (e) => {
+  // Cmd+K on Mac, Ctrl+K elsewhere
+  if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+    e.preventDefault();
+    palette.open = true;
+  }
+});
+
+palette.addEventListener('dismiss', () => { palette.open = false; });
+palette.addEventListener('select',   () => { palette.open = false; });
+```
+
+Once `open` flips to true, the input auto-focuses and Escape / outside-click fire `dismiss`. The palette handles arrow-key navigation, Enter to select, and recent-items recall on its own.
+
+## Dynamic command lists
+
+If your commands change reactively (signal-bound, fetched, etc.), use `palette.setItems([…])` to swap the entire item set in one call. Each item is `{ value, label, icon?, shortcut?, keywords?, disabled?, category? }`:
+
+```js
+palette.setItems([
+  // ungrouped items
+  { value: 'new', label: 'New file', icon: 'plus', shortcut: '⌘N' },
+
+  // a group — pass items inline, the palette renders the group header
+  { label: 'Recent', items: [
+    { value: 'open:foo.ts', label: 'foo.ts' },
+    { value: 'open:bar.ts', label: 'bar.ts' },
+  ]},
+]);
+```
+
+Or stay declarative and update the `<option>` / `<optgroup>` children directly — the palette re-parses on every `open` flip and when `setItems()` is called.
+
+## Recent items
+
+The palette automatically tracks the last 10 selected values and shows them as a "Recent" section when the search input is empty. Items appear in MRU order; selections promote items to the top. Recent items are filtered against the current item set, so a stale recent (item removed via `setItems()`) is silently dropped.
+
+This is a built-in behavior — no consumer wiring needed. To disable, override with an explicit empty group at the top, or skip and use the section-based grouping pattern instead.
+
+## Required icons
+
+`<command-ui>` auto-stamps the `magnifying-glass` icon in the search field. Per `command.yaml` `requiredIcons:`, this is aggregated into the global icon-load manifest by `installIconLoadersForRegistered()`. Any additional `data-icon="<name>"` on options must be in the Phosphor icon set (or registered via `IconRegistry.register(name, svgString)`).
+
+## Accessibility
+
+- The search input has `role="combobox"`, `aria-expanded`, `aria-controls`, and `aria-activedescendant` wiring per WAI-ARIA combobox pattern.
+- Each rendered option has `role="option"` and reflects `aria-disabled` from the source `<option>`.
+- The active item (keyboard-highlighted) gets `data-active` for CSS targeting + `aria-activedescendant` reference from the input.
+- Escape fires `dismiss` (not `close`) — the consumer decides whether to actually close.
+
+## Related primitives
+
+- `<menu-ui>` — for static actionable lists tied to a trigger (e.g. context menu). Not searchable.
+- `<select-ui>` — single-value form input with options. Not searchable.
+- `<tree-ui>` — hierarchical navigation with expand/collapse. Carries selection state.
+
+`<command-ui>` is the right choice when: (a) the user is typing to filter from a list, (b) the action set is broad (10+ items), (c) keyboard-first navigation is the primary affordance, OR (d) you need a Cmd+K-style global launcher.

package/components/command/class.js

@@ -144,19 +144,24 @@ export class UICommand extends UIElement {
     const items = [];
     for (const child of this.children) {
       if (child.tagName === 'OPTGROUP') {
-        const group = { label: child.label, items: [] };
+        const groupLabel = child.label;
+        const group = { label: groupLabel, items: [] };
         for (const opt of child.querySelectorAll('option')) {
-          group.items.push(this.#optionToItem(opt));
+          group.items.push(this.#optionToItem(opt, groupLabel));
         }
         items.push(group);
       } else if (child.tagName === 'OPTION') {
-        items.push(this.#optionToItem(child));
+        items.push(this.#optionToItem(child, ''));
       }
     }
     this.#items = items;
   }
 
-  #optionToItem(opt) {
+  // §-TBD (v0.5.19, FB-50 #3): forward the parent <optgroup label> as
+  // `category` on each item so the `select` event detail can surface
+  // which group the chosen item came from. Items without a group
+  // (direct <option> children of <command-ui>) get category = ''.
+  #optionToItem(opt, category = '') {
     return {
       value: opt.value,
       label: opt.textContent.trim(),
@@ -164,6 +169,7 @@ export class UICommand extends UIElement {
       shortcut: opt.dataset.shortcut || '',
       keywords: opt.dataset.keywords || '',
       disabled: opt.disabled,
+      category,
     };
   }
 
@@ -302,11 +308,18 @@ export class UICommand extends UIElement {
     this.#activate(parseInt(options[next].dataset.idx));
   }
 
+  // §-TBD (v0.5.19, FB-50 #3): emit `category` (from parent <optgroup
+   // label>) in the select detail so consumers can route on group.
+   // Items without a group surface category = ''.
   #select(item) {
     this.#pushRecent(item.value);
     this.dispatchEvent(new CustomEvent('select', {
       bubbles: true,
-      detail: { value: item.value, label: item.label },
+      detail: {
+        value: item.value,
+        label: item.label,
+        category: item.category || '',
+      },
     }));
   }
 
@@ -315,10 +328,14 @@ export class UICommand extends UIElement {
     if (!active) return;
     const value = active.dataset.value;
     const label = active.querySelector('[data-text]')?.textContent || '';
+    // Look up the item to surface category — the rendered DOM doesn't
+    // carry the group label, but #items / #itemByEl do.
+    const item = this.#itemByEl.get(active) || this.#findItem(value);
+    const category = item?.category || '';
     this.#pushRecent(value);
     this.dispatchEvent(new CustomEvent('select', {
       bubbles: true,
-      detail: { value, label },
+      detail: { value, label, category },
     }));
   }
 

package/components/command/command.a2ui.json

@@ -40,8 +40,12 @@
         "description": "Fired when Escape is pressed"
       },
       "select": {
-        "description": "Fired when an item is selected. Detail contains { value, label, item }.",
+        "description": "Fired when an item is selected. detail: { value, label, category }. `category` is the parent `<optgroup label=\"…\">` label, or empty string when the item is a direct child of `<command-ui>` with no group.\n",
         "detail": {
+          "category": {
+            "description": "Parent optgroup label (empty string when item has no group).",
+            "type": "string"
+          },
           "label": {
             "description": "Item label text.",
             "type": "string"

package/components/command/command.d.ts

@@ -14,6 +14,8 @@ import { UIElement } from '../../core/element.js';
 
 export type CommandDismissEvent = CustomEvent<unknown>;
 export interface CommandSelectEventDetail {
+  /** Parent optgroup label (empty string when item has no group). */
+  category: string;
   /** Item label text. */
   label: string;
   /** Item value attribute. */

package/components/command/command.test.js

@@ -0,0 +1,99 @@
+/**
+ * <command-ui> behavioral tests.
+ *
+ * FB-50 #3 (v0.5.19): the `select` event detail now carries `category`
+ * derived from the parent <optgroup label> (or '' when the item has
+ * no group).
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./command.js');
+});
+
+describe('<command-ui> select event detail includes category (FB-50 #3)', () => {
+  let host;
+  let palette;
+
+  beforeEach(async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+
+    palette = document.createElement('command-ui');
+    palette.setAttribute('open', '');
+
+    // Mixed: one ungrouped option, one optgroup with two options.
+    const ungrouped = document.createElement('option');
+    ungrouped.setAttribute('value', 'logout');
+    ungrouped.textContent = 'Log out';
+
+    const optgroup = document.createElement('optgroup');
+    optgroup.setAttribute('label', 'Navigation');
+    const opt1 = document.createElement('option');
+    opt1.setAttribute('value', 'home');
+    opt1.textContent = 'Go Home';
+    const opt2 = document.createElement('option');
+    opt2.setAttribute('value', 'settings');
+    opt2.textContent = 'Settings';
+    optgroup.appendChild(opt1);
+    optgroup.appendChild(opt2);
+
+    palette.appendChild(ungrouped);
+    palette.appendChild(optgroup);
+    host.appendChild(palette);
+
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('emits category="" for an ungrouped option', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => { received = e.detail; });
+
+    // Use the imperative setItems() path to bypass DOM-walk ordering;
+    // the optgroup path is exercised in the next test.
+    palette.setItems([{ value: 'logout', label: 'Log out' }]);
+
+    // Simulate user clicking the logout row.
+    const row = palette.querySelector('[role="option"][data-value="logout"]');
+    expect(row).not.toBeNull();
+    row.click();
+
+    expect(received).not.toBeNull();
+    expect(received.value).toBe('logout');
+    expect(received.label).toBe('Log out');
+    expect(received.category).toBe('');
+  });
+
+  it('emits category="<optgroup label>" for an item inside an optgroup', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => { received = e.detail; });
+
+    const homeRow = palette.querySelector('[role="option"][data-value="home"]');
+    expect(homeRow).not.toBeNull();
+    homeRow.click();
+
+    expect(received).not.toBeNull();
+    expect(received.value).toBe('home');
+    expect(received.label).toBe('Go Home');
+    expect(received.category).toBe('Navigation');
+  });
+
+  it('detail shape stays backward-compatible (existing destructuring works)', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => {
+      const { value, label } = e.detail;  // pre-FB-50 destructuring shape
+      received = { value, label };
+    });
+
+    const settingsRow = palette.querySelector('[role="option"][data-value="settings"]');
+    settingsRow.click();
+
+    expect(received.value).toBe('settings');
+    expect(received.label).toBe('Settings');
+  });
+});

package/components/command/command.yaml

@@ -19,7 +19,12 @@ events:
   dismiss:
     description: Fired when Escape is pressed
   select:
-    description: Fired when an item is selected. Detail contains { value, label, item }.
+    description: >
+      Fired when an item is selected.
+      detail: { value, label, category }.
+      `category` is the parent `<optgroup label="…">` label, or empty
+      string when the item is a direct child of `<command-ui>` with no
+      group.
     detail:
       value:
         type: string
@@ -27,6 +32,9 @@ events:
       label:
         type: string
         description: Item label text.
+      category:
+        type: string
+        description: Parent optgroup label (empty string when item has no group).
 slots:
   empty:
     description: Empty state shown when no items match

package/components/description-list/description-list.a2ui.json

@@ -19,11 +19,12 @@
       "default": []
     },
     "align": {
-      "description": "Alignment for inline layout — between = term left, value right.",
+      "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.\n",
       "type": "string",
       "enum": [
         "start",
-        "between"
+        "between",
+        "stretch"
       ],
       "default": "start"
     },

package/components/description-list/description-list.css

@@ -65,6 +65,22 @@
     text-align: end;
   }
 
+  /* §-TBD (v0.5.19, FB-51 #3): align="stretch" lets dd fill the
+     remaining inline-grid track width. Useful when dd hosts a block-
+     level form control (slider-ui / select-ui / color-picker-ui) that
+     would otherwise shrink-wrap to content. width:100% on direct
+     children reaches block controls that have their own inline-flex
+     :scope rule (e.g. <slider-ui>) so they stretch to track width. */
+  :scope[layout="inline"][align="stretch"] > [data-dl-desc],
+  :scope[layout="inline"][align="stretch"] > dd {
+    justify-self: stretch;
+    width: 100%;
+  }
+  :scope[layout="inline"][align="stretch"] > [data-dl-desc] > *,
+  :scope[layout="inline"][align="stretch"] > dd > * {
+    width: 100%;
+  }
+
   /* Size handled by the universal [size] attribute scaling --a-ui-size;
      components pick up font-size from token chain automatically. */
 }

package/components/description-list/description-list.d.ts

@@ -15,8 +15,9 @@ import { UIElement } from '../../core/element.js';
 export class UIDescriptionList extends UIElement {
   /** Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children */
   items: unknown[];
-  /** Alignment for inline layout — between = term left, value right. */
-  align: 'start' | 'between';
+  /** Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.
+ */
+  align: 'start' | 'between' | 'stretch';
   /** stacked: term above description. inline: term and description on one row. */
   layout: 'stacked' | 'inline';
 }

package/components/description-list/description-list.test.js

@@ -0,0 +1,72 @@
+/**
+ * <description-list-ui> behavioral tests.
+ *
+ * FB-51 #3 (v0.5.19): align="stretch" lets <dd> fill the remaining
+ * inline-grid track width so block-level form controls inside (e.g.
+ * <slider-ui>, <select-ui>, <color-picker-ui>) reach the column edge
+ * rather than shrink-wrapping to content.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+beforeAll(async () => {
+  await import('./description-list.js');
+});
+
+describe('<description-list-ui> align="stretch" (FB-51 #3)', () => {
+  let host;
+  let dl;
+
+  beforeEach(async () => {
+    host = document.createElement('div');
+    host.style.width = '600px';
+    document.body.appendChild(host);
+
+    dl = document.createElement('description-list-ui');
+    dl.setAttribute('layout', 'inline');
+    dl.setAttribute('align', 'stretch');
+
+    const dt = document.createElement('dt');
+    dt.textContent = 'Source hue';
+    const dd = document.createElement('dd');
+    dd.id = 'fb51-stretch-dd';
+    const probe = document.createElement('div');
+    probe.id = 'fb51-stretch-probe';
+    probe.textContent = 'inner';
+    dd.appendChild(probe);
+    dl.appendChild(dt);
+    dl.appendChild(dd);
+
+    host.appendChild(dl);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('CSS source declares justify-self: stretch + width: 100% for align="stretch" inline layout', () => {
+    const cssText = readFileSync(resolve(HERE, 'description-list.css'), 'utf8');
+    expect(cssText).toMatch(/\[layout="inline"\]\[align="stretch"\][^{]*\{[^}]*justify-self:\s*stretch/);
+    expect(cssText).toMatch(/\[layout="inline"\]\[align="stretch"\][^{]*\{[^}]*width:\s*100%/);
+  });
+
+  it('host carries the align="stretch" attribute (CSS selector match precondition)', () => {
+    expect(dl.getAttribute('align')).toBe('stretch');
+    expect(dl.getAttribute('layout')).toBe('inline');
+  });
+
+  it('yaml enum includes "stretch" (schema contract)', () => {
+    const yamlText = readFileSync(resolve(HERE, 'description-list.yaml'), 'utf8');
+    // Match the align enum block specifically (between `align:` and the next prop).
+    const alignBlock = yamlText.match(/align:[\s\S]*?(?=\n  \w+:)/)?.[0] || '';
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+start/);
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+between/);
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+stretch/);
+  });
+});

package/components/description-list/description-list.yaml

@@ -10,12 +10,21 @@ description: Semantic key-value list (dl/dt/dd). Preserves native HTML semantics
   and SSR. Layout supports stacked (default) or inline.
 props:
   align:
-    description: Alignment for inline layout — between = term left, value right.
+    description: >
+      Alignment for inline layout.
+      `start` (default): term and value pack to the term column edge.
+      `between`: term left, value right-aligned with `text-align: end`.
+      `stretch`: value fills the remaining track width (e.g. for a
+      `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>`
+      that should span the full row). Sets `justify-self: stretch` and
+      `width: 100%` on `dd` so block-level form controls inside reach
+      the column edge rather than shrink-wrapping to content.
     type: string
     default: start
     enum:
       - start
       - between
+      - stretch
   items:
     description: Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children
     type: array

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() {
@@ -638,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

@@ -448,3 +448,116 @@ describe('<swatch-ui> chrome survives parent template re-render (FB-43 / §341)'
     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);
+  });
+});

package/components/tree/tree.yaml

@@ -15,7 +15,11 @@ composes:
 props: {}
 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.
     detail:
       item:
         type: object
@@ -26,6 +30,15 @@ events:
       value:
         type: string
         description: Item value attribute.
+      ctrlKey:
+        type: boolean
+        description: Ctrl key held during activation (false for programmatic select()).
+      metaKey:
+        type: boolean
+        description: Meta (Cmd) key held during activation (false for programmatic select()).
+      shiftKey:
+        type: boolean
+        description: Shift key held during activation (false for programmatic select()).
 slots:
   default (tree-item-ui children):
     description: "Child content region for the `default (tree-item-ui children)` slot."

package/core/template.test.js

@@ -13,7 +13,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { html, stamp } from './template.js';
+import { html, stamp, repeat } from './template.js';
 
 describe('html template — §250 (v0.5.11) ?attr=${bool} silent-failure trap', () => {
   let container;
@@ -179,3 +179,103 @@ describe('html template — FB-40 (v0.5.16) apostrophe in HTML comments does NOT
     expect(received).not.toBeNull();
   });
 });
+
+describe('html template — FB-47 (v0.5.19) stamp() cache + repeat() keyed reuse', () => {
+  // FEEDBACK-47 claimed `stamp()` unconditionally calls `mount()` →
+  // `replaceChildren()`, defeating `repeat()` keyed reconciliation. Source
+  // inspection (template.js:94-102) shows `stamp()` has a per-container
+  // cache keyed on `result.strings`; `mount()` runs ONLY on cache miss
+  // (first stamp on this container OR new template strings). These tests
+  // verify the cache behavior empirically against the same-template
+  // re-stamp + repeat()-same-key paths.
+
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it('stamp() with same template strings reuses the mounted instance (no replaceChildren)', () => {
+    // Build a template factory whose strings literal is reference-stable
+    // (the tagged-template caller — closure captures `strings` once).
+    const make = (value) => html`<div class="probe">${value}</div>`;
+
+    stamp(make('first'), container);
+    const firstDiv = container.querySelector('.probe');
+    expect(firstDiv).not.toBeNull();
+    expect(firstDiv.textContent).toBe('first');
+
+    // Mark the existing node so we can prove it survives the re-stamp.
+    firstDiv.dataset.marker = 'preserved';
+
+    stamp(make('second'), container);
+    const secondDiv = container.querySelector('.probe');
+    expect(secondDiv).toBe(firstDiv);                     // ✅ same node
+    expect(secondDiv.dataset.marker).toBe('preserved');   // ✅ no replaceChildren
+    expect(secondDiv.textContent).toBe('second');         // ✅ value updated in-place
+  });
+
+  it('repeat() with same key preserves wrapper children across re-renders', () => {
+    // FB-47's central reproduction: same-key repeat() should preserve the
+    // per-item wrapper-span AND the child element stamped into it on the
+    // prior render. Both the outer template AND the per-item template must
+    // share strings references across renders (single tagged-template-literal
+    // sites) — JS spec gives each source site its own strings array, so
+    // inline-duplicating the html`` between stamp calls would force a
+    // cache miss and defeat preservation. Real consumers naturally satisfy
+    // this by having one render function called repeatedly.
+    const items = [{ id: 'a', label: 'first' }];
+    const tplFn = (item) => html`<div class="probe" data-id=${item.id}>${item.label}</div>`;
+    const renderAll = (its) => html`${repeat(its, (x) => x.id, tplFn)}`;
+
+    stamp(renderAll(items), container);
+    const firstDiv = container.querySelector('.probe[data-id="a"]');
+    expect(firstDiv).not.toBeNull();
+
+    // Append a manually-added child that the framework should NOT destroy.
+    const probe = document.createElement('span');
+    probe.id = 'fb47-manual-child';
+    probe.textContent = 'sentinel';
+    firstDiv.appendChild(probe);
+
+    // Re-stamp with the same items array (same key 'a').
+    items[0] = { id: 'a', label: 'second' };
+    stamp(renderAll(items), container);
+
+    const secondDiv = container.querySelector('.probe[data-id="a"]');
+    expect(secondDiv).toBe(firstDiv);                     // ✅ wrapper reused
+    expect(secondDiv.querySelector('#fb47-manual-child')).not.toBeNull();
+    expect(secondDiv.firstChild.nodeValue).toBe('second');  // text updated in-place
+  });
+
+  it('Array.isArray() branch in applyValue does replace children on every re-render (the actual root cause)', () => {
+    // FB-47's empirical observation IS valid for `.map()` — the
+    // Array.isArray() branch in applyValue() (template.js:232-244) does
+    // unconditional `container.replaceChildren()` + allocates fresh wrapper
+    // spans per item. Switching consumers to repeat() avoids this. This
+    // test pins the current behavior so any future "make .map() smart"
+    // change is intentional, not accidental. Use a single render function
+    // (one tagged-template-literal site for the outer template) so the
+    // observed re-creation is isolated to the .map() Array branch, not
+    // a cache miss from inline-duplicated source sites.
+    const items = [{ id: 'a', label: 'first' }];
+    const tplFn = (item) => html`<div class="probe" data-id=${item.id}>${item.label}</div>`;
+    const renderAll = (its) => html`${its.map(tplFn)}`;
+
+    stamp(renderAll(items), container);
+    const firstDiv = container.querySelector('.probe[data-id="a"]');
+    expect(firstDiv).not.toBeNull();
+
+    items[0] = { id: 'a', label: 'second' };
+    stamp(renderAll(items), container);
+
+    const secondDiv = container.querySelector('.probe[data-id="a"]');
+    expect(secondDiv).not.toBe(firstDiv);                 // ✅ NEW node — .map() re-creates
+    expect(secondDiv.textContent).toBe('second');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",