@adia-ai/web-components 0.6.6 → 0.6.8

package/core/template.js

@@ -91,6 +91,106 @@ function getTemplate(strings) {
   return tpl;
 }
 
+// §-TBD (FB-55, P1): the HTML parser lowercases attribute names inside
+// <template>.innerHTML per HTML5 §13.2.5.32, so `.className=${expr}`
+// arrives at scan() as `.classname`. The `name.slice(1)` strips the dot
+// and the binding writes to a lowercase enumerable expando instead of
+// invoking the camelCase property setter. Net: classes never apply, no
+// warning, no error.
+//
+// The trap affects every camelCase DOM property surface — `.className`,
+// `.innerText`, `.tabIndex`, `.ariaLabel`, `.contentEditable`,
+// `.readOnly`, `.maxLength`, `.minLength`, `.colSpan`, `.rowSpan` — AND
+// every camelCase property declared via `UIElement.static properties`
+// (e.g. `.minL`, `.maxChroma`, `.hueDriftMax`, `.colorScheme`,
+// `.strokeWidth`, `.collapseKeepLeading`). Even the canonical example
+// `<my-panel .minL=${minL}>` from packages/web-components/README.md:212
+// silently failed pre-fix.
+//
+// Two-layer fix:
+//
+//   1. Static PROP_CASE_FIX map covers built-in DOM camelCase property
+//      names (zero-cost lookup, no prototype walk per binding for the
+//      common case).
+//
+//   2. Prototype-walk fallback finds the canonical camelCase property
+//      name on the element's prototype chain via case-insensitive
+//      match. Cost is O(prototype-chain-depth × prototype-key-count)
+//      per UNIQUE template binding (cached in parts[i].name, not
+//      re-walked per update() tick). Custom-element prototype chains
+//      are short (subclass → UIElement → HTMLElement → Element → Node
+//      → EventTarget); cost is negligible.
+//
+// Backward-compatible: when the prototype walk finds no case-insensitive
+// match (genuine lowercase-expando case — rare but possible), the
+// original lowercase name is preserved. No consumer that was
+// deliberately writing to a lowercase expando regresses.
+//
+// Verification: 8-test matrix in core/template.test.js's FB-55 describe
+// block. RESPONSE-55 documents the trap end-to-end.
+const PROP_CASE_FIX = {
+  classname: 'className',
+  innertext: 'innerText',
+  innerhtml: 'innerHTML',
+  outerhtml: 'outerHTML',
+  textcontent: 'textContent',
+  tabindex: 'tabIndex',
+  arialabel: 'ariaLabel',
+  ariadescribedby: 'ariaDescribedBy',
+  arialabelledby: 'ariaLabelledBy',
+  ariarole: 'role',
+  contenteditable: 'contentEditable',
+  readonly: 'readOnly',
+  maxlength: 'maxLength',
+  minlength: 'minLength',
+  colspan: 'colSpan',
+  rowspan: 'rowSpan',
+  cellpadding: 'cellPadding',
+  cellspacing: 'cellSpacing',
+  usemap: 'useMap',
+  ismap: 'isMap',
+  accesskey: 'accessKey',
+  defaultchecked: 'defaultChecked',
+  defaultvalue: 'defaultValue',
+  defaultselected: 'defaultSelected',
+};
+
+// Resolve a lowercase property name to its canonical camelCase form on
+// the given element. Returns the original `lower` name when no
+// case-insensitive match exists (preserves expando semantics). Walks
+// instance own-properties first (UIElement installs camelCase props via
+// `Object.defineProperty(this, ...)` in the constructor, so they live
+// on the instance, not the prototype), then prototype chain. Skips
+// Object.prototype to avoid noisy matches on `toString` etc.
+//
+// IMPORTANT: at scan() time the custom element has typically NOT yet
+// been constructed (template fragment is cloned + scanned before
+// insertion → upgrade), so instance-defined props aren't visible yet.
+// PROP_CASE_FIX covers built-in DOM camelCase props at scan() time;
+// the per-element walk runs ALSO at applyValue() time (lazy resolve,
+// cached on the part after first hit) to catch UIElement instance props
+// once the element has been upgraded.
+function resolvePropName(el, lower) {
+  if (PROP_CASE_FIX[lower]) return PROP_CASE_FIX[lower];
+  // Instance own-properties (UIElement installProps lives here).
+  const ownNames = Object.getOwnPropertyNames(el);
+  for (let i = 0; i < ownNames.length; i++) {
+    const n = ownNames[i];
+    if (n !== lower && n.toLowerCase() === lower) return n;
+  }
+  // Prototype chain (built-in DOM camelCase + class-defined accessors).
+  let proto = Object.getPrototypeOf(el);
+  while (proto && proto !== Object.prototype) {
+    const names = Object.getOwnPropertyNames(proto);
+    for (let i = 0; i < names.length; i++) {
+      const n = names[i];
+      if (n !== lower && n.toLowerCase() === lower) return n;
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return lower;
+}
+
 export function stamp(result, container) {
   let inst = container._i;
   if (!inst || inst.s !== result.strings) {
@@ -104,12 +204,118 @@ export function stamp(result, container) {
 function mount(result, container) {
   const { strings } = result;
   const tpl = getTemplate(strings);
-  const f = tpl.content.cloneNode(true);
+  let f = tpl.content.cloneNode(true);
+
+  // §-TBD (FB-57, P1): when stamping into an SVG or MathML context, the
+  // fragment's Elements arrive HTML-namespaced because `tpl.innerHTML =
+  // m` is parsed at document level without foreign-content context. SVG
+  // and MathML layout are namespace-strict — HTMLUnknownElement nodes
+  // inside an SVG render to zero-bound-rect invisible. Re-namespace the
+  // fragment before insertion, respecting `<foreignObject>` and
+  // `<annotation-xml>` HTML boundaries per the HTML5 foreign-content
+  // insertion-mode spec.
+  //
+  // Discriminator runs once per mount() call (no per-update cost).
+  // Re-namespacing walks the fragment recursively (O(node-count)),
+  // cheap for typical interpolation arrays (16 lines + 11 stops in
+  // the canonical curve-preview case = 27 createElementNS calls).
+  //
+  // Implementation site choice: mount() rather than getTemplate(),
+  // because:
+  //   - container reference is in hand only at mount()
+  //   - the same cached template may be stamped into either context;
+  //     namespacing per-cache-entry would double the WeakMap size
+  //     and require a cache-key extension
+  //   - cloning is already happening here; re-namespacing piggybacks
+  //     on the existing fragment walk
+  //
+  // RESPONSE-57 documents the trap end-to-end. Regression tests pin
+  // the inline-SVG path (must keep working), nested-SVG path (would
+  // fail pre-fix), foreignObject boundary (HTML inside SVG stays
+  // HTML), and MathML parallel.
+  const ns = foreignContentNS(container);
+  if (ns) f = renamespaceFragment(f, ns);
+
   const parts = scan(f, result.values.length);
   container.replaceChildren(f);
   return { s: strings, p: parts };
 }
 
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const MATHML_NS = 'http://www.w3.org/1998/Math/MathML';
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+
+// Determine whether `container` is inside an SVG or MathML subtree, and
+// return the namespace to re-namespace stamped fragments into. Returns
+// null when the container is in HTML context (the no-op case — vast
+// majority of templates). Respects `<foreignObject>` (SVG) and
+// `<annotation-xml encoding=text/html|application/xhtml+xml>` (MathML)
+// HTML boundaries per HTML5 §12.2.5 foreign-content insertion mode.
+function foreignContentNS(container) {
+  if (!container || container.nodeType !== 1) return null;
+  // Direct check — container's own namespace is a fast-path.
+  if (container.namespaceURI === SVG_NS) return SVG_NS;
+  if (container.namespaceURI === MATHML_NS) return MATHML_NS;
+  // Walk ancestors to find a foreign-content root. `closest()` matches
+  // the element itself + ancestors, so this catches the wrap()-span
+  // case (HTML span inside an SVG subtree). The first match wins —
+  // foreignObject/annotation-xml inside SVG short-circuits before we
+  // see the outer <svg>, correctly returning null (HTML context).
+  if (typeof container.closest !== 'function') return null;
+  const anchor = container.closest('svg, math, foreignObject, annotation-xml');
+  if (!anchor) return null;
+  const tag = anchor.localName;
+  if (tag === 'foreignobject' || tag === 'foreignObject') return null;
+  if (tag === 'annotation-xml') {
+    const enc = (anchor.getAttribute('encoding') || '').toLowerCase();
+    if (enc === 'text/html' || enc === 'application/xhtml+xml') return null;
+    return MATHML_NS;
+  }
+  if (tag === 'svg') return SVG_NS;
+  if (tag === 'math') return MATHML_NS;
+  return null;
+}
+
+// Recursively transfer fragment children into a new fragment with each
+// Element recreated in the target namespace. Text/comment nodes clone
+// unchanged. `<foreignObject>` and `<annotation-xml encoding=text/html>`
+// stay in the target namespace themselves, but their descendants revert
+// to HTML (matches the browser parser's foreign-content insertion mode).
+function renamespaceFragment(fragment, ns) {
+  const out = document.createDocumentFragment();
+  transferChildren(fragment, out, ns);
+  return out;
+}
+
+function transferChildren(src, dstParent, ns) {
+  for (const child of [...src.childNodes]) {
+    const t = child.nodeType;
+    if (t === 1 /* Element */) {
+      const dst = document.createElementNS(ns, child.localName);
+      for (const a of child.attributes) {
+        if (a.namespaceURI) dst.setAttributeNS(a.namespaceURI, a.name, a.value);
+        else dst.setAttribute(a.name, a.value);
+      }
+      dstParent.appendChild(dst);
+      // Boundary handling: <foreignObject> (SVG) and
+      // <annotation-xml encoding=text/html> (MathML) revert to HTML.
+      const local = child.localName;
+      let childNs = ns;
+      if (ns === SVG_NS && (local === 'foreignObject' || local === 'foreignobject')) {
+        childNs = XHTML_NS;
+      } else if (ns === MATHML_NS && local === 'annotation-xml') {
+        const enc = (child.getAttribute('encoding') || '').toLowerCase();
+        if (enc === 'text/html' || enc === 'application/xhtml+xml') childNs = XHTML_NS;
+      }
+      transferChildren(child, dst, childNs);
+    } else {
+      // Text, comment, etc. — clone unchanged. Comments are load-bearing
+      // (the `<!--p:N-->` placeholders scan() looks for).
+      dstParent.appendChild(child.cloneNode(true));
+    }
+  }
+}
+
 function scan(fragment, count) {
   const parts = new Array(count);
   const w = document.createTreeWalker(fragment, 129);
@@ -146,14 +352,21 @@ function scan(fragment, count) {
             // canonical style-object path; for everything else keep
             // the generic property-assignment recipe.
             const a = attr.name;
+            // §-TBD (FB-55 #2, P1): updated post-fix. The v0.5.5 §184
+            // recommendation had `.className=${expression}` first;
+            // that path now works (§-TBD PROP_CASE_FIX above) but
+            // `class="${expression}"` is the more discoverable form
+            // that doesn't require knowing the camelCase property
+            // name. Promoting it first. The `.classList=` line is
+            // removed entirely — classList is a read-only getter, no
+            // PROP_CASE_FIX entry can make it assignable.
             const specific =
               a === 'class'
-                ? `    .className=\${expression}  ← write to the className property (NOT .class, which is an expando)\n` +
-                  `    class="\${expression}"      ← full replacement (whole class string is the expression)\n` +
-                  `    .classList=\${{foo: true, bar: false}}  ← if/when implemented; verify in USAGE.md\n`
+                ? `    class="\${expression}"      ← full replacement (whole class string is the expression)\n` +
+                  `    .className=\${expression}  ← writes to the className property (resolved camelCase since FB-55 fix)\n`
                 : a === 'style'
-                  ? `    .style.cssText=\${expression}  ← write CSS text to .style.cssText\n` +
-                    `    style="\${expression}"      ← full replacement of the style string\n`
+                  ? `    style="\${expression}"      ← full replacement of the style string\n` +
+                    `    .style.cssText=\${expression}  ← write CSS text via the style.cssText accessor\n`
                   : `    ${a}="\${expression}"      ← full replacement (whole attr is the placeholder)\n` +
                     `    .${a}=\${expression}        ← property assignment (preferred for objects/functions)\n`;
             // eslint-disable-next-line no-console
@@ -173,8 +386,12 @@ function scan(fragment, count) {
           n.removeAttribute(name);
           parts[i] = { t: 'e', n, name: name.slice(1), c: undefined, _fx: null };
         } else if (name[0] === '.') {
+          // §-TBD (FB-55, P1): resolve the parser-lowercased property
+          // name back to its canonical camelCase via PROP_CASE_FIX +
+          // prototype walk. See PROP_CASE_FIX comment above for context.
+          // Lazy-resolve in applyValue() too — see _resolved guard there.
           n.removeAttribute(name);
-          parts[i] = { t: 'p', n, name: name.slice(1), c: undefined, _fx: null };
+          parts[i] = { t: 'p', n, name: resolvePropName(n, name.slice(1)), c: undefined, _fx: null, _resolved: false };
         } else if (name[0] === '?') {
           // §250 (v0.5.11, FEEDBACK-27): Lit-style boolean attribute syntax
           // (`?attr=${bool}`) is NOT supported. Without this branch, the
@@ -256,6 +473,18 @@ function applyValue(p, v) {
     if (v == null || v === false) p.n.removeAttribute(p.name);
     else p.n.setAttribute(p.name, v === true ? '' : v);
   } else if (p.t === 'p') {
+    // §-TBD (FB-55, P1): two-phase property-name resolution. PROP_CASE_FIX
+    // resolved at scan() time for zero-cost built-in DOM camelCase (the
+    // common case). For UIElement custom-element props installed on the
+    // INSTANCE via the constructor's installProps(), the property doesn't
+    // exist at scan() time (element not yet upgraded), so a lazy lookup
+    // here catches them. Resolution is cached back into p.name on first
+    // hit — subsequent updates skip the walk.
+    if (!p._resolved) {
+      const resolved = resolvePropName(p.n, p.name);
+      if (resolved !== p.name) p.name = resolved;
+      p._resolved = true;
+    }
     p.n[p.name] = v;
   } else if (p.t === 'e') {
     if (isHandler(p.c)) p.n.removeEventListener(p.name, p.c);

package/core/template.test.js

@@ -279,3 +279,297 @@ describe('html template — FB-47 (v0.5.19) stamp() cache + repeat() keyed reuse
     expect(secondDiv.textContent).toBe('second');
   });
 });
+
+describe('html template — FB-55 (v0.6.8) `.camelCase=${expr}` property-binding lowercase trap close', () => {
+  // FEEDBACK-55: the HTML parser lowercases attribute names inside
+  // <template>.innerHTML per HTML5 §13.2.5.32. Pre-fix, `.className=` arrived
+  // at scan() as `.classname`, then `name.slice(1)` yielded `"classname"`,
+  // and `applyValue()` wrote `p.n["classname"] = v` — an enumerable expando,
+  // never invoking the camelCase property setter. Classes never applied; no
+  // warn, no error.
+  //
+  // Fix: PROP_CASE_FIX static map (for built-in DOM camelCase props) +
+  // prototype-walk fallback (for UIElement-defined custom-element props).
+  // Backward-compatible: when no case-insensitive match exists, the
+  // original lowercase name is preserved (genuine expando consumers
+  // unaffected).
+  //
+  // RESPONSE-55 documents the trap end-to-end + reviewer-#A scope
+  // expansion to UIElement primitives.
+
+  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('.className=${expr} writes to the real className property (not lowercase expando)', () => {
+    const tpl = html`<span .className=${'foo bar'}>x</span>`;
+    stamp(tpl, container);
+    const span = container.querySelector('span');
+    expect(span.className).toBe('foo bar');              // ✅ real className set
+    expect(span.getAttribute('class')).toBe('foo bar');  // ✅ reflected to DOM attr
+    expect(span.classname).toBeUndefined();              // ✅ NO lowercase expando
+  });
+
+  it('.tabIndex=${n} writes to the real tabIndex property', () => {
+    const tpl = html`<div .tabIndex=${3}></div>`;
+    stamp(tpl, container);
+    const div = container.querySelector('div');
+    expect(div.tabIndex).toBe(3);
+    expect(div.getAttribute('tabindex')).toBe('3');
+  });
+
+  it('.innerHTML=${str} survives unchanged (already-lowercase name)', () => {
+    // .innerHTML is one of the few camelCase-looking names whose
+    // canonical form is already lowercase (well, it's `innerHTML` but
+    // the parser lowercases it to `innerhtml` AND PROP_CASE_FIX maps
+    // back to `innerHTML`). Verify it lands on the property regardless.
+    const tpl = html`<div .innerHTML=${'<span class="inner">payload</span>'}></div>`;
+    stamp(tpl, container);
+    const div = container.querySelector('div');
+    expect(div.querySelector('.inner')?.textContent).toBe('payload');
+  });
+
+  it('.lowercaseProp=${v} on a stock element preserves expando semantics (backward compat)', () => {
+    // The fallback prototype walk skips Object.prototype to avoid noisy
+    // matches. A genuinely-lowercase property name with no matching
+    // camelCase pair on the chain (e.g. `.myexpando`) lands on the
+    // element as a lowercase expando — the documented escape hatch
+    // for arbitrary data attachment. Verify no regression.
+    const tpl = html`<div .myexpando=${'attached'}></div>`;
+    stamp(tpl, container);
+    const div = container.querySelector('div');
+    expect(div.myexpando).toBe('attached');
+  });
+
+  it('.camelCaseProp=${v} on a UIElement-style custom element invokes the canonical setter', async () => {
+    // Reviewer-addition #A from RESPONSE-55: UIElement defines
+    // properties under camelCase keys via Object.defineProperty. The
+    // pre-fix trap wrote `el['camelprop'] = v` (expando) instead of
+    // invoking the setter. Verify the fix routes correctly through
+    // the prototype-walk fallback.
+    class FB55El extends HTMLElement {
+      constructor() {
+        super();
+        let _camelProp = '';
+        Object.defineProperty(this, 'camelProp', {
+          get() { return _camelProp; },
+          set(v) { _camelProp = v; this.dataset.lastSet = v; },
+          configurable: true,
+          enumerable: true,
+        });
+      }
+    }
+    if (!customElements.get('fb55-el')) customElements.define('fb55-el', FB55El);
+
+    const tpl = html`<fb55-el .camelProp=${'via-setter'}></fb55-el>`;
+    stamp(tpl, container);
+    const el = container.querySelector('fb55-el');
+    expect(el.camelProp).toBe('via-setter');             // ✅ getter returns set value
+    expect(el.dataset.lastSet).toBe('via-setter');       // ✅ setter side-effect ran
+    expect(el.camelprop).toBeUndefined();                // ✅ NO lowercase expando
+  });
+
+  it('.maxChroma=${n} on a UIElement-style ce reaches the camelCase property', () => {
+    // Real-world surface: <color-picker max-chroma> and <color-input
+    // max-chroma> declare `maxChroma` as a static property. Consumers
+    // reaching for `.maxChroma=${value}` template binding must invoke
+    // the setter, not write an expando.
+    class FB55Numeric extends HTMLElement {
+      constructor() {
+        super();
+        let _maxChroma = 0;
+        Object.defineProperty(this, 'maxChroma', {
+          get() { return _maxChroma; },
+          set(v) { _maxChroma = v; },
+          configurable: true, enumerable: true,
+        });
+      }
+    }
+    if (!customElements.get('fb55-num')) customElements.define('fb55-num', FB55Numeric);
+
+    const tpl = html`<fb55-num .maxChroma=${0.42}></fb55-num>`;
+    stamp(tpl, container);
+    const el = container.querySelector('fb55-num');
+    expect(el.maxChroma).toBe(0.42);
+  });
+
+  it('updates to .className=${expr} re-route through the setter on every value change', () => {
+    // The PROP_CASE_FIX resolution is cached in parts[i].name at scan()
+    // time. Subsequent update() ticks must continue to use the resolved
+    // camelCase name. Verify by re-stamping with a new value.
+    const make = (cls) => html`<span .className=${cls}>x</span>`;
+    stamp(make('a'), container);
+    let span = container.querySelector('span');
+    expect(span.className).toBe('a');
+
+    stamp(make('b'), container);
+    span = container.querySelector('span');
+    expect(span.className).toBe('b');                    // ✅ second update routes correctly
+    expect(span.getAttribute('class')).toBe('b');
+  });
+
+  it('warning text no longer recommends .className= as the FIRST option for class= partial interp', () => {
+    // FB-55 #2: pre-fix, the v0.5.5 §184 warn text put `.className=`
+    // first; post-fix, `class="${expr}"` (the discoverable form) leads.
+    // Both work now (FB-55 #1), but the recommended ordering matters
+    // for new consumers reading the warning cold.
+    const cls = 'foo';
+    const tpl = html`<span class="prefix ${cls}">x</span>`;
+    stamp(tpl, container);
+    expect(warnSpy).toHaveBeenCalled();
+    const msg = warnSpy.mock.calls[0][0];
+    const classFullPos = msg.indexOf('class="${expression}"');
+    const classNamePos = msg.indexOf('.className=${expression}');
+    expect(classFullPos).toBeGreaterThan(-1);
+    expect(classNamePos).toBeGreaterThan(-1);
+    expect(classFullPos).toBeLessThan(classNamePos);     // ✅ class="" first, .className= second
+  });
+
+  it('warning text dropped the .classList= aspirational line (FB-55 #2)', () => {
+    // Pre-fix the warn text mentioned `.classList=${{foo: true, bar: false}}`
+    // as "if/when implemented". classList is a read-only DOMTokenList
+    // accessor — no PROP_CASE_FIX could make it assignable, so the line
+    // was misleading. Post-fix it's removed.
+    const cls = 'foo';
+    const tpl = html`<span class="prefix ${cls}">x</span>`;
+    stamp(tpl, container);
+    const msg = warnSpy.mock.calls[0][0];
+    expect(msg).not.toMatch(/\.classList=/);
+  });
+
+  it('does not regress: canonical .style=${cssText}, .title=${str}, .value=${v} still work', () => {
+    // These property names are already lowercase, so they survived
+    // the parser pre-fix. Verify PROP_CASE_FIX didn't break them.
+    const tpl = html`<input .title=${'tip'} .value=${'val'}>`;
+    stamp(tpl, container);
+    const input = container.querySelector('input');
+    expect(input.title).toBe('tip');
+    expect(input.value).toBe('val');
+  });
+});
+
+describe('html template — FB-57 (v0.6.8) nested SVG/MathML template namespace re-routing', () => {
+  // FEEDBACK-57: nested `${html`<svg-child/>`}` interpolations produce
+  // HTML-namespaced elements (HTMLUnknownElement) instead of SVGElement.
+  // Root cause: each nested html`` is a SEPARATE cached template, and
+  // `tpl.innerHTML = m` is parsed at document level without SVG context.
+  // The <span style="display:contents"> wrapper from wrap() doesn't fix
+  // it because display:contents is layout-level not namespace-level;
+  // SVG layout is namespace-strict → invisible-but-present output.
+  //
+  // Fix: namespace-aware mount() — when the container is inside an SVG
+  // (or MathML) subtree, recursively re-namespace the cloned fragment
+  // via createElementNS. <foreignObject> and <annotation-xml
+  // encoding=text/html> revert to HTML per HTML5 §12.2.5 foreign-content
+  // insertion mode.
+  //
+  // RESPONSE-57 documents the trap end-to-end + the implementation-site
+  // choice (mount() not getTemplate(), to keep cache coherent).
+
+  const SVG_NS = 'http://www.w3.org/2000/svg';
+  const MATHML_NS = 'http://www.w3.org/1998/Math/MathML';
+
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it('inline <svg><circle/></svg> in a single template keeps working (regression)', () => {
+    // Pre-fix this case already worked because the HTML parser sees
+    // <svg> in tpl.innerHTML and enters SVG insertion mode for its
+    // descendants. Post-fix it must still work — the container is
+    // HTML-namespaced (<div>), so foreignContentNS() returns null,
+    // re-namespacing is skipped, and the inline parser's NS survives.
+    const tpl = html`<svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="3"/></svg>`;
+    stamp(tpl, container);
+    const svg = container.querySelector('svg');
+    const circle = container.querySelector('circle');
+    expect(svg.namespaceURI).toBe(SVG_NS);
+    expect(circle.namespaceURI).toBe(SVG_NS);
+  });
+
+  it('nested ${html`<circle/>`} inside an SVG container now lands in SVG namespace', () => {
+    // The canonical fix surface. Pre-fix, the inner template's <circle>
+    // arrived as HTMLUnknownElement (NS xhtml). Post-fix, the wrap()
+    // span is HTML-namespaced (correct — it has display:contents) but
+    // its children get re-namespaced via the wrap-span's closest('svg')
+    // matching the outer SVG.
+    const svgRoot = document.createElementNS(SVG_NS, 'svg');
+    container.appendChild(svgRoot);
+    const dots = [{ x: 1 }, { x: 2 }, { x: 3 }];
+    const tpl = html`${dots.map(d => html`<circle cx=${d.x} cy="5" r="2"/>`)}`;
+    stamp(tpl, svgRoot);
+    const circles = svgRoot.querySelectorAll('circle');
+    expect(circles.length).toBe(3);
+    for (const c of circles) {
+      expect(c.namespaceURI).toBe(SVG_NS);                       // ✅ SVG-NS
+    }
+  });
+
+  it('a directly-stamped html`<circle/>` template into an SVG container is SVG-namespaced', () => {
+    // Even without array interpolation, stamping a single SVG-content
+    // template into an SVG container must re-namespace.
+    const svgRoot = document.createElementNS(SVG_NS, 'svg');
+    container.appendChild(svgRoot);
+    const tpl = html`<circle cx="5" cy="5" r="3"/>`;
+    stamp(tpl, svgRoot);
+    const circle = svgRoot.querySelector('circle');
+    expect(circle.namespaceURI).toBe(SVG_NS);
+  });
+
+  it('<foreignObject> children REVERT to HTML namespace (per HTML5 spec)', () => {
+    // <foreignObject> is the spec-defined HTML escape hatch inside SVG.
+    // Re-namespacing must stop at the foreignObject boundary; its
+    // children stay HTML-namespaced.
+    const svgRoot = document.createElementNS(SVG_NS, 'svg');
+    container.appendChild(svgRoot);
+    const tpl = html`<foreignObject><div class="html-inside-svg">html content</div></foreignObject>`;
+    stamp(tpl, svgRoot);
+    const fo = svgRoot.querySelector('foreignObject');
+    const innerDiv = svgRoot.querySelector('.html-inside-svg');
+    expect(fo.namespaceURI).toBe(SVG_NS);                        // ✅ foreignObject itself is SVG
+    expect(innerDiv.namespaceURI).toBe('http://www.w3.org/1999/xhtml');  // ✅ children HTML
+  });
+
+  it('MathML <math><mi/></math> inline template stays in MathML namespace via the HTML parser', () => {
+    // Like inline-SVG: the HTML parser enters MathML insertion mode for
+    // <math>, so inline children arrive correctly namespaced even
+    // pre-fix. Post-fix this remains true (no re-namespacing because
+    // the container is HTML).
+    const tpl = html`<math><mi>x</mi></math>`;
+    stamp(tpl, container);
+    const math = container.querySelector('math');
+    const mi = container.querySelector('mi');
+    // happy-dom may or may not surface MathML namespace; smoke that the
+    // elements at least exist and the math element is acknowledged.
+    expect(math).not.toBeNull();
+    expect(mi).not.toBeNull();
+    expect(math.localName).toBe('math');
+  });
+
+  it('does not re-namespace when stamping into an HTML container (no overhead in the common case)', () => {
+    // Probe the discriminator: a plain <div> container should skip the
+    // re-namespacing path entirely. Verify by stamping a template
+    // whose children are HTML elements and confirming they stay HTML.
+    const tpl = html`<p class="probe">html paragraph</p>`;
+    stamp(tpl, container);
+    const p = container.querySelector('p.probe');
+    expect(p.namespaceURI).toBe('http://www.w3.org/1999/xhtml');
+  });
+});