@adia-ai/web-components 0.5.16 → 0.5.18

package/CHANGELOG.md

@@ -11,6 +11,20 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.18] - 2026-05-16
+
+### Fixed
+- §341 (FB-43; P1) — `<swatch-ui>` chrome destroyed when interpolated via parent `html\`\`` template `${chromeFrag}`. `template.js`'s `scan()` replaces `<!--p:N-->` comments with empty text nodes inside the swatch element when the parent template is cloned; `wrap()` later mutates those text nodes in-place via `replaceWith()`. Pre-§341: the swatch's `#stamp()` ran `innerHTML = ''` between the parent's `mount()` and `update()` (synchronous custom-element connectedCallback timing), wiping the text-node placeholders. Parent's `replaceWith()` then ran on detached nodes — silent no-op — leaving wrapper-spans detached and chrome stamped into a subtree that never reached the live DOM. Symptom: chrome interpolated as `${chromeFrag}` was completely invisible (queryable from neither swatch nor host). Blocked Tokens Studio's C1.3 main-palette dogfood migration (~80 swatches inside `repeat()`). **Fix:** preserve empty text nodes + comment nodes (template-engine placeholders) AND display:contents wrapper-spans through `innerHTML = ''`. Detach them before the wipe, re-attach at the canonical chrome position (between tile + badge) after the canonical structure is stamped. Wrapper-spans preserved in-place keep the template-engine's `part.n` reference stable across re-renders → chrome content updates land in the same DOM location automatically. `#absorbChromeSlot()`'s late-arriving wrapper handler also updated: MOVE the wrapper (not hoist chrome out of it) to canonical position — same identity-preservation rationale. **§331 contract refined:** previously chrome was hoisted to be a direct sibling of the swatch's internal elements (`parentElement === swatch`); §341 keeps chrome inside the wrapper-span which is a direct sibling. Visually identical (display:contents collapses the wrapper's box) but the DOM identity is now wrapper-bearing. 3 NEW vitest cases (`FB-43 / §341`) + 3 §331 (FB-39) tests updated for new contract. 15/15 swatch tests passing.
+
+## [0.5.17] - 2026-05-16
+
+### Fixed
+- §339 (FB-41; P2) — `<swatch-ui>` `[auto-contrast]` overrode `[label-position="overlay"]` position. Two `@scope (swatch-ui)` rules at equal specificity (0,3,1) collided on `> [data-label] { position }`; source order favored auto-contrast's `position: relative` over overlay's `position: absolute` → label dropped below tile (host doubled to 2× block-h). Blocks the canonical `label-position="overlay" + auto-contrast` pattern §253 enabled. Fix: drop `position: relative` from `[auto-contrast]` data-label + data-detail rules — z-index works on positioned elements (overlay supplies position: absolute), and non-overlay defaults are flex flow where z-index is irrelevant. 3 NEW vitest cases lock the CSS source structurally.
+- §340 (FB-42; P2) — `<list-item-ui>` `render()` text-branch asymmetry. Icon + description branches had create-if-missing paths; text branch only updated existing stamped spans. Template engine `.text=${expr}` (canonical authoring pattern per USAGE.md) arrives AFTER `connectedCallback` `#stamp()` — `this.text` was `''` at stamp time so no span created, `render()` fired but couldn't recover → primary text silently invisible. Fix: mirror description branch's create-if-missing + remove-when-cleared pattern. NEW `list.test.js` with 5 vitest cases (create-on-prop-set / update / remove / parity-with-description / consumer-stamp non-interference).
+
+### Tests
+- §338 (FB-40; misdiagnosed) — 4 NEW vitest cases in `core/template.test.js` lock the existing FEEDBACK-06 comment-aware `inTag()` fix (line 55-78). FB-40 reported apostrophes-in-HTML-comments crashes claiming the parser mis-classifies subsequent `${…}` placeholders; the cited mechanism is incorrect — `inTag()` has skipped past `<!--…-->` wholesale since FEEDBACK-06 (pre-v0.5.x). The 4 new tests empirically verify the fix covers apostrophe-comment + double-quote-comment + multi-apostrophe + apostrophe+em-dash cases. RESPONSE-40 requests stack-trace evidence for the actual crash mechanism since the cited apostrophe diagnosis is empirically wrong against current source.
+
 ## [0.5.16] - 2026-05-16
 
 ### v0.5.16 §331 — `<swatch-ui>` chrome-slot wrapper-span deep-walk (FB-39; P1)

package/components/list/class.js

@@ -227,9 +227,24 @@ export class UIListItem extends UIElement {
       iconEl.remove();
     }
 
-    // Sync text — only touch elements we stamped.
+    // Sync text — mirror the icon + description branches: create-if-missing
+    // path so post-connect property bindings (template engine `.text=${expr}`)
+    // can stamp the span when `#stamp()` ran with `this.text === ''`. §340
+    // (FB-42) — without this, primary text is silently invisible when set
+    // via property binding (the canonical authoring pattern per USAGE.md).
     const textEl = this.#ownChild('[slot="text"]');
-    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+    if (this.text) {
+      if (textEl) {
+        if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+      } else {
+        const el = this.#stampMark(document.createElement('span'));
+        el.setAttribute('slot', 'text');
+        el.textContent = this.text;
+        this.appendChild(el);
+      }
+    } else if (this.#wasStamped(textEl)) {
+      textEl.remove();
+    }
 
     // Sync description — only touch elements we stamped.
     const descEl = this.#ownChild('[slot="description"]');

package/components/list/list.test.js

@@ -0,0 +1,106 @@
+/**
+ * <list-item-ui> behavioral tests.
+ *
+ * Initial scope: FB-42 / §340 regression coverage — `render()`'s text
+ * branch can now create the slot element when `this.text` is set
+ * post-connect (e.g. via template-engine property binding), matching
+ * the icon + description branches' create-if-missing pattern.
+ *
+ * Test setup note: happy-dom connects custom elements synchronously
+ * during innerHTML parsing. To exercise the post-connect property-set
+ * timing (template-engine path), tests use `document.createElement` +
+ * `host.appendChild()` to connect with empty `text`, then set the
+ * property AFTER connect to trigger render()'s recovery path.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./list.js');
+});
+
+describe('<list-item-ui> render() text branch — post-connect property binding (FB-42 / §340)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('creates [slot="text"] span when .text is set AFTER connectedCallback (template-engine timing)', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    // connectedCallback fires here with this.text === '' — span NOT stamped
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+
+    // Template engine sets the property post-connect
+    li.text = 'Primary text via property binding';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('Primary text via property binding');
+  });
+
+  it('updates existing [slot="text"] span when .text changes', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'initial');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('initial');
+
+    li.text = 'updated';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]').textContent).toBe('updated');
+  });
+
+  it('removes stamped [slot="text"] span when .text is cleared', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'will be removed');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).not.toBeNull();
+
+    li.text = '';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+  });
+
+  it('text branch parity with description branch — both create-if-missing post-connect', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+    expect(li.querySelector('[slot="description"]')).toBeNull();
+
+    li.text = 'primary';
+    li.description = 'secondary';
+    await new Promise((r) => setTimeout(r, 30));
+
+    expect(li.querySelector('[slot="text"]')?.textContent).toBe('primary');
+    expect(li.querySelector('[slot="description"]')?.textContent).toBe('secondary');
+  });
+
+  it('does not stamp [slot="text"] for unauthored consumer-provided text content', async () => {
+    // If the consumer provides their own [slot="text"] child (e.g. for
+    // richer markup), the render() branch must NOT touch it.
+    const li = document.createElement('list-item-ui');
+    const userSpan = document.createElement('span');
+    userSpan.setAttribute('slot', 'text');
+    userSpan.innerHTML = '<strong>bold</strong> user';
+    li.appendChild(userSpan);
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    li.text = 'attempt to set';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const span = li.querySelector('[slot="text"]');
+    expect(span).toBe(userSpan); // identity preserved
+    expect(span.innerHTML).toBe('<strong>bold</strong> user'); // markup preserved
+  });
+});

package/components/swatch/class.js

@@ -234,14 +234,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 +310,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 +394,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 +414,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);
     }
   }
 

package/components/swatch/swatch.css

@@ -255,9 +255,20 @@
      stamps [data-on-light] or [data-on-dark] on the label. The label then
      swaps fg color so it remains legible against the tile background.
      Only fires for shape="block" (label sits ON the tile); for other
-     shapes the label is beside the tile and uses the normal chrome fg. */
+     shapes the label is beside the tile and uses the normal chrome fg.
+
+     §339 (FB-41): the auto-contrast rules previously set `position:
+     relative` which collided at equal specificity (0,3,1) with the
+     overlay rule's `position: absolute` (line 164). Source order made
+     the later auto-contrast rule win, so `[label-position="overlay"]
+     [auto-contrast]` resolved the label to `position: relative`,
+     dropping it OUT of overlay and below the tile (host height doubled).
+     Fix: drop `position: relative` from auto-contrast. `z-index: 1`
+     only does work on a positioned element; the overlay rule already
+     supplies `position: absolute` for the overlay case. For the
+     non-overlay default (label below tile), the label is in normal
+     flow and doesn't overlap anything, so z-index is irrelevant. */
   :scope[shape="block"][auto-contrast] > [data-label] {
-    position: relative;
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] {
@@ -268,7 +279,6 @@
   }
   /* Detail line follows the same auto-contrast choice. */
   :scope[shape="block"][auto-contrast] > [data-detail] {
-    position: relative;
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] ~ [data-detail] {

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,10 +270,181 @@ 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);
+  });
+});
+
+describe('<swatch-ui> [auto-contrast] does not override [label-position="overlay"] position (FB-41 / §339)', () => {
+  // Structural CSS-source-string assertion: happy-dom does not resolve
+  // @scope CSS specificity reliably, so we verify the fix by reading
+  // swatch.css text and asserting the auto-contrast rules don't carry
+  // `position: relative` (which collided at equal specificity with the
+  // overlay rule's `position: absolute` via source order).
+  //
+  // Pre-§339: `:scope[shape="block"][auto-contrast] > [data-label]`
+  // declared `position: relative; z-index: 1`. Combined with overlay
+  // attribute, the later rule won → label dropped out of overlay layout.
+  //
+  // Post-§339: only `z-index: 1` remains (z-index is no-op on static
+  // elements but harmless; for the overlay case it stacks above the
+  // tile correctly via the overlay rule's `position: absolute`).
+  it('auto-contrast label rule does NOT declare position: relative (regression for FB-41)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[auto-contrast\]\s*>\s*\[data-label\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    expect(block).not.toMatch(/position\s*:\s*relative/);
+    expect(block).toMatch(/z-index\s*:\s*1/);
+  });
+
+  it('auto-contrast detail rule does NOT declare position: relative (regression for FB-41)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[auto-contrast\]\s*>\s*\[data-detail\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    expect(block).not.toMatch(/position\s*:\s*relative/);
+    expect(block).toMatch(/z-index\s*:\s*1/);
+  });
+
+  it('overlay rule still declares position: absolute (regression for FB-41)', async () => {
+    // Defensive: also assert the overlay rule's `position: absolute` is
+    // still in place — if a future refactor drops it, the §253 contract
+    // breaks regardless of the auto-contrast collision.
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[label-position="overlay"\]\s*>\s*\[data-label\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    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);
   });
 });

package/core/template.test.js

@@ -95,3 +95,87 @@ describe('html template — §250 (v0.5.11) ?attr=${bool} silent-failure trap',
     expect(warnSpy).not.toHaveBeenCalled();
   });
 });
+
+describe('html template — FB-40 (v0.5.16) apostrophe in HTML comments does NOT mis-classify subsequent placeholders', () => {
+  // FEEDBACK-06 §1 P0 (long resolved) made `inTag()` comment-aware:
+  // when scan() hits `<!--` outside a string context, it jumps past
+  // `-->` wholesale. FB-40 (filed 2026-05-16 post-v0.5.16 cut) reported
+  // crashes attributed to apostrophes in comments. This suite verifies
+  // empirically that the comment-aware logic still holds — the FB-40
+  // diagnosis is mistaken about the mechanism (the existing fix covers
+  // the apostrophe-in-comment case).
+
+  let container;
+  let warnSpy;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    container.remove();
+    warnSpy.mockRestore();
+  });
+
+  it('@event=${handler} placeholder AFTER apostrophe-bearing comment is classified as attribute-position', () => {
+    let received = null;
+    const handler = (e) => { received = e; };
+    const tpl = html`
+      <div>
+        <!-- editor-shell's named slots -->
+        <button data-test="probe" @click=${handler}>X</button>
+      </div>
+    `;
+    stamp(tpl, container);
+    const btn = container.querySelector('[data-test="probe"]');
+    expect(btn).not.toBeNull();
+    btn.click();
+    expect(received).not.toBeNull();
+    expect(received.type).toBe('click');
+  });
+
+  it('double-quote in HTML comment does not mis-classify subsequent attribute placeholder', () => {
+    const tpl = html`
+      <div>
+        <!-- the "Stop Override" button below -->
+        <button data-test="probe" data-id=${'42'}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    const btn = container.querySelector('[data-test="probe"]');
+    expect(btn).not.toBeNull();
+    expect(btn.getAttribute('data-id')).toBe('42');
+  });
+
+  it('multiple apostrophes across multiple comments still keep subsequent placeholders attribute-position', () => {
+    let received = null;
+    const tpl = html`
+      <div>
+        <!-- one's first comment -->
+        <span>x</span>
+        <!-- two's second comment -->
+        <button data-test="probe" @click=${(e) => { received = e; }}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    container.querySelector('[data-test="probe"]').click();
+    expect(received).not.toBeNull();
+  });
+
+  it('apostrophe + em-dash (U+2014) in a single comment does not break parsing', () => {
+    // dts-export-drawer.ts case from FB-40's cited crashes:
+    // <!-- 2026-05-14 — migrated number inputs ... -->
+    let received = null;
+    const tpl = html`
+      <div>
+        <!-- 2026-05-14 — author's notes about migrated number inputs -->
+        <button data-test="probe" @click=${(e) => { received = e; }}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    container.querySelector('[data-test="probe"]').click();
+    expect(received).not.toBeNull();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "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",