@barefootjs/jsx 0.31.8 → 0.31.10

package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts

@@ -14,7 +14,7 @@
 import { varSlotId, DATA_BF_PH, keyAttrName, profileBindingId } from '../../utils.ts'
 import { emitComponentAndEventSetup } from '../shared.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
-import { templateRootIsSvg } from './template-parse.ts'
+import { namespaceWrapForTemplate } from './template-parse.ts'
 import { emitListenerLine } from './event-listener.ts'
 import { nameForRegistryRef } from '../../component-scope.ts'
 import { claimPlanLiteral, claimWriterVarName, type ClaimSlotSpec } from './claim-plan.ts'
@@ -139,9 +139,8 @@ export function stringifyBranchInnerLoops(
       lines.push(`${indent}  ${inner.paramUnwrap}`)
     }
     {
-      const isSvg = templateRootIsSvg(inner.wrappedTemplate)
-      const innerHtml = isSvg ? `<svg>${inner.wrappedTemplate}</svg>` : inner.wrappedTemplate
-      const childPath = isSvg ? '.firstElementChild.firstElementChild' : '.firstElementChild'
+      const { wrapTag, childPath } = namespaceWrapForTemplate(inner.wrappedTemplate)
+      const innerHtml = wrapTag ? `<${wrapTag}>${inner.wrappedTemplate}</${wrapTag}>` : inner.wrappedTemplate
       lines.push(`${indent}  let __bel${uid} = __existing ?? (() => { const __t = document.createElement('template'); __t.innerHTML = \`${innerHtml}\`; return __t.content${childPath}.cloneNode(true) })()`)
     }
     if (inner.wrappedKey) {

package/src/ir-to-client-js/control-flow/stringify/loop.ts

@@ -32,7 +32,7 @@
 import { emitRefCall, varSlotId, profileBindingId } from '../../utils.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
 import { stringifyReactiveEffects } from './reactive-effects.ts'
-import { emitTemplateCloneInline, emitLoopItemElementSetup, emitHoistedTemplateDecl, hoistedCloneExpr, templateRootIsSvg, multiRootTemplateNeedsSvgWrap } from './template-parse.ts'
+import { emitTemplateCloneInline, emitLoopItemElementSetup, emitHoistedTemplateDecl, hoistedCloneExpr, namespaceWrapForTemplate, multiRootNamespaceWrapForTemplate, wrapHtmlForNamespace } from './template-parse.ts'
 import { buildSkeletonPathPlan, type SkeletonPathPlan } from './skeleton-paths.ts'
 import { stringifyComponentLoop } from './component-loop.ts'
 import { stringifyCompositeLoop } from './composite-loop.ts'
@@ -401,17 +401,21 @@ export function stringifyStaticLoop(lines: string[], plan: StaticLoopPlan): void
   lines.push(`      let __iterEl = ${containerVar}.children[${childIndexExpr}]`)
   if (csrMaterialize) {
     lines.push(`      if (!__iterEl) {`)
-    // SVG-rooted item templates parse inside a synthetic `<svg>` wrap and
-    // descend one extra level (#2219) — `template.innerHTML` alone parses in
-    // the HTML namespace and the materialized elements would never draw.
-    // Mirrors `templateRootIsSvg` handling on the reactive clone paths;
-    // HTML-rooted templates keep byte-identical output. Multi-root fragments
-    // use the fragment-aware predicate so an `<svg>`-container-first fragment
-    // isn't over-wrapped (#2233 Copilot review).
-    const isSvg = csrMaterialize.bodyIsMultiRoot
-      ? multiRootTemplateNeedsSvgWrap(csrMaterialize.itemTemplate)
-      : templateRootIsSvg(csrMaterialize.itemTemplate)
-    const itemHtml = isSvg ? `<svg>${csrMaterialize.itemTemplate}</svg>` : csrMaterialize.itemTemplate
+    // SVG/MathML-rooted item templates parse inside a synthetic namespace
+    // wrap and descend one extra level (#2219, #1096) — `template.innerHTML`
+    // alone parses in the HTML namespace and the materialized elements
+    // would never draw. Reads the wrap decision AND descent path through
+    // the same single door as the reactive clone emitters
+    // (`namespaceWrapForTemplate`, #2662 Copilot review) so a future
+    // namespace or fragment-rule tweak can't update one path and miss the
+    // other; HTML-rooted templates keep byte-identical
+    // output. Multi-root fragments use the fragment-aware predicate so a
+    // `<svg>`/`<math>`-container-first fragment isn't over-wrapped (#2233
+    // Copilot review).
+    const { wrapTag, childPath } = csrMaterialize.bodyIsMultiRoot
+      ? multiRootNamespaceWrapForTemplate(csrMaterialize.itemTemplate)
+      : namespaceWrapForTemplate(csrMaterialize.itemTemplate)
+    const itemHtml = wrapHtmlForNamespace(csrMaterialize.itemTemplate, wrapTag)
     if (csrMaterialize.bodyIsMultiRoot) {
       // Multi-root: clone every top-level sibling of the per-item template and
       // insert them in order. `__iterEl` is the first root (the one reactive
@@ -420,7 +424,7 @@ export function stringifyStaticLoop(lines: string[], plan: StaticLoopPlan): void
       lines.push(`        __mtpl.innerHTML = \`${itemHtml}\``)
       lines.push(`        const __anchor = ${containerVar}.children[${childIndexExpr}] ?? null`)
       lines.push(`        let __first = null`)
-      lines.push(`        let __sib = __mtpl.content${isSvg ? '.firstElementChild' : ''}.firstElementChild`)
+      lines.push(`        let __sib = __mtpl.content${childPath}.firstElementChild`)
       lines.push(`        while (__sib) {`)
       lines.push(`          const __next = __sib.nextElementSibling`)
       lines.push(`          const __cloned = __sib.cloneNode(true)`)
@@ -432,7 +436,7 @@ export function stringifyStaticLoop(lines: string[], plan: StaticLoopPlan): void
     } else {
       lines.push(`        const __tpl = document.createElement('template')`)
       lines.push(`        __tpl.innerHTML = \`${itemHtml}\``)
-      lines.push(`        const __cloned = __tpl.content${isSvg ? '.firstElementChild' : ''}.firstElementChild`)
+      lines.push(`        const __cloned = __tpl.content${childPath}`)
       lines.push(`        if (__cloned) {`)
       lines.push(`          const __anchor = ${containerVar}.children[${childIndexExpr}] ?? null`)
       lines.push(`          ${containerVar}.insertBefore(__cloned, __anchor)`)

package/src/ir-to-client-js/control-flow/stringify/template-parse.ts

@@ -1,7 +1,7 @@
 /**
  * Helpers for emitting code that parses a template literal into a DOM
- * element clone, while preserving the SVG namespace when the loop body
- * root is an SVG element.
+ * element clone, while preserving the SVG/MathML namespace when the loop
+ * body root is a foreign-content element.
  *
  * Background (#135): the standard pattern
  *   `const __tpl = document.createElement('template')`
@@ -14,10 +14,14 @@
  * Editor block when a new edge `<path>` was appended via mapArray and
  * never showed up on the canvas.
  *
- * Fix: when the template's root tag is an SVG element, wrap the parsed
- * markup in a synthetic `<svg>` so the HTML5 parser walks into SVG
- * foreign content and assigns the correct namespace, then descend one
- * extra level to get the real root.
+ * Fix: when the template's root tag is an SVG (or, #1096, MathML) element,
+ * wrap the parsed markup in the matching synthetic namespace root
+ * (`<svg>` / `<math>`) so the HTML5 parser walks into foreign content and
+ * assigns the correct namespace, then descend one extra level to get the
+ * real root. The two namespaces share every byte of this machinery —
+ * only the wrap tag name differs — so `detectRootNamespaceWrapTag` and
+ * `namespaceWrapForTemplate` below are the single door every emitter
+ * (in this file and its consumers) reads the wrap decision through.
  */
 
 import { findInterpolationEnd, findTopLevelTemplateLiterals } from '../../../scanner/js-scanner.ts'
@@ -37,73 +41,140 @@ const SVG_ROOT_TAGS = new Set([
 ])
 
 /**
- * Decide whether a template literal needs SVG-context parsing.
- * Looks at the first opening tag in the literal. The check is purely
- * lexical so that interpolations inside attribute values do not
- * confuse it.
+ * MathML root tags (#1096 — port of the SVG fix above). `math` itself is
+ * included alongside the element vocabulary, mirroring how `svg` is
+ * included in `SVG_ROOT_TAGS`: a template whose bare root is the
+ * namespace container tag also needs the parser nudge (unlike the
+ * MULTI-ROOT fragment case in `multiRootTemplateNeedsNamespaceWrap`,
+ * where a container-first fragment already parses correctly on its own).
+ */
+const MATHML_ROOT_TAGS = new Set([
+  'math',
+  'mrow', 'mfrac', 'msup', 'msub', 'msubsup', 'mn', 'mi', 'mo', 'mtext',
+  'munder', 'mover', 'munderover', 'mtable', 'mtr', 'mtd',
+  'msqrt', 'mroot', 'mstyle', 'merror', 'mpadded', 'mphantom', 'menclose',
+  'semantics', 'annotation', 'annotation-xml',
+])
+
+/** Namespaces whose root tags need the synthetic-wrap parser nudge. */
+export type NamespaceWrapTag = 'svg' | 'math'
+
+/**
+ * Look up which foreign-content namespace (if any) a single tag name
+ * belongs to. Case-insensitive fallback mirrors `templateRootIsSvg`'s
+ * original comment: SVG/MathML element names are case-sensitive in JSX
+ * (e.g. `linearGradient`, `annotation-xml`) but the canonical lower-case
+ * set is checked first, then the lower-cased tag, so both spellings match.
+ */
+function namespaceForTag(tag: string): NamespaceWrapTag | null {
+  if (SVG_ROOT_TAGS.has(tag) || SVG_ROOT_TAGS.has(tag.toLowerCase())) return 'svg'
+  if (MATHML_ROOT_TAGS.has(tag) || MATHML_ROOT_TAGS.has(tag.toLowerCase())) return 'math'
+  return null
+}
+
+/**
+ * Decide whether a template literal needs foreign-content (SVG or MathML)
+ * parsing, and which. Looks at the first opening tag in the literal. The
+ * check is purely lexical so that interpolations inside attribute values
+ * do not confuse it.
  *
  * Three shapes are recognised:
- *   1. Direct element root — `<circle .../>`
+ *   1. Direct element root — `<circle .../>` / `<mrow>...</mrow>`
  *   2. Conditional body (#1088) — `${cond ? `<circle .../>` : `<rect .../>`}`
- *      where every result-position template literal starts with an SVG
- *      tag. The compiler emits this shape for `.map(s => cond ? <a/> : <b/>)`
- *      bodies; without the wrap the cloned element ends up in the xhtml
- *      namespace and renders nothing.
+ *      where every result-position template literal (recursively) resolves
+ *      to the SAME namespace. The compiler emits this shape for
+ *      `.map(s => cond ? <a/> : <b/>)` bodies; without the wrap the cloned
+ *      element ends up in the xhtml namespace and renders nothing.
  *   3. Reactive-conditional body — a branch wrapped in `<!--bf-cond-start:sX-->`
  *      / `<!--bf-cond-end:sX-->` markers (emitted for nested reactive
  *      conditionals). The check skips leading HTML comments and recurses
  *      into the inner `${...}`.
  *
- * Mixed-namespace branches (one HTML, one SVG) intentionally fall through
- * to no-wrap so the user sees the same broken output as before instead of
- * a silent over-wrap into a `<foreignObject>`-style mismatch.
+ * Mixed-namespace branches (HTML+SVG, HTML+MathML, or SVG+MathML)
+ * intentionally fall through to no-wrap so the user sees the same broken
+ * output as before instead of a silent over-wrap that would drag one
+ * branch into the wrong foreign-content namespace.
  */
-export function templateRootIsSvg(template: string): boolean {
+export function detectRootNamespaceWrapTag(template: string): NamespaceWrapTag | null {
   const stripped = stripLeadingNonContent(template)
 
   // Shape 1: direct element root.
   const m = stripped.match(/^<\s*([A-Za-z][A-Za-z0-9-]*)/)
-  if (m) {
-    // SVG element names are case-sensitive in JSX (e.g., `linearGradient`)
-    // and arrive lowercased to the renderer for the kebab-cased forms;
-    // match case-insensitively against the canonical lower-case set, but
-    // keep the canonical name's casing in the lookup table so JSX names
-    // like `clipPath` still match.
-    const tag = m[1]
-    if (SVG_ROOT_TAGS.has(tag)) return true
-    return SVG_ROOT_TAGS.has(tag.toLowerCase())
-  }
+  if (m) return namespaceForTag(m[1])
 
   // Shapes 2 & 3: single `${...}` interpolation whose result-position
-  // template literals all (recursively) resolve to SVG roots (Option A in
-  // #1088).
+  // template literals all (recursively) resolve to the SAME namespace
+  // (Option A in #1088, generalised to MathML in #1096).
   const branches = extractConditionalBranchTemplates(stripped)
-  if (branches === null || branches.length === 0) return false
-  return branches.every(templateRootIsSvg)
+  if (branches === null || branches.length === 0) return null
+  let result: NamespaceWrapTag | null | undefined
+  for (const branch of branches) {
+    const branchNs = detectRootNamespaceWrapTag(branch)
+    if (result === undefined) {
+      result = branchNs
+    } else if (result !== branchNs) {
+      return null
+    }
+  }
+  return result ?? null
 }
 
 /**
  * Wrap decision for MULTI-ROOT (fragment) templates, where the synthetic
- * `<svg>` wrap swallows every sibling root at once (#2233 Copilot review).
+ * namespace wrap swallows every sibling root at once (#2233 Copilot
+ * review, generalised to MathML in #1096).
  *
- * `templateRootIsSvg` inspects only the FIRST root tag. For single-root
- * templates that's exact, but a fragment whose first root is an `<svg>`
- * CONTAINER (`<><svg/><span/></>`) doesn't need the wrap at all — the
- * HTML parser enters foreign content at `<svg>` on its own — and wrapping
- * would drag the HTML siblings into the SVG namespace (`<span>` becomes an
- * SVGUnknownElement, silently undrawn). So `<svg>`-first fragments skip
- * the wrap; only leaf-rooted fragments (`<line>`, `<circle>`, ...) get it.
+ * `detectRootNamespaceWrapTag` inspects only the FIRST root tag. For
+ * single-root templates that's exact, but a fragment whose first root is
+ * the namespace CONTAINER itself (`<><svg/><span/></>`, `<><math/><span/></>`)
+ * doesn't need the wrap at all — the HTML parser enters foreign content at
+ * `<svg>`/`<math>` on its own — and wrapping would drag the HTML siblings
+ * into the foreign namespace (`<span>` becomes an SVGUnknownElement/etc.,
+ * silently undrawn). So container-first fragments skip the wrap; only
+ * leaf-rooted fragments (`<line>`, `<circle>`, `<mrow>`, ...) get it.
  *
- * Known edge (degenerate, pre-existing): an `<svg>`-first fragment with
- * SVG-LEAF siblings (`<><svg/><line/></>`) leaves the bare leaf siblings
- * in the HTML namespace — exactly the pre-#2219 behavior. Deciding that
- * shape correctly needs a scan of every top-level root tag; not worth the
- * parser until a real component hits it.
+ * Known edge (degenerate, pre-existing): a container-first fragment with
+ * LEAF siblings of the same namespace (`<><svg/><line/></>`) leaves the
+ * bare leaf siblings in the HTML namespace — exactly the pre-#2219
+ * behavior. Deciding that shape correctly needs a scan of every top-level
+ * root tag; not worth the parser until a real component hits it.
  */
-export function multiRootTemplateNeedsSvgWrap(template: string): boolean {
+export function multiRootTemplateNeedsNamespaceWrap(template: string): NamespaceWrapTag | null {
   const m = stripLeadingNonContent(template).match(/^<\s*([A-Za-z][A-Za-z0-9-]*)/)
-  if (m && m[1].toLowerCase() === 'svg') return false
-  return templateRootIsSvg(template)
+  if (m) {
+    const tagLower = m[1].toLowerCase()
+    if (tagLower === 'svg' || tagLower === 'math') return null
+  }
+  return detectRootNamespaceWrapTag(template)
+}
+
+/**
+ * Single door for the "wrap tag + descent path" pair every namespace-aware
+ * clone site needs. Consumers outside this file (`inner-loop.ts`,
+ * `loop-child-arm.ts`, `loop.ts`) read the wrap decision through this
+ * function instead of re-deriving `isSvg ? '<svg>' : ...` locally — keeps
+ * the SVG/MathML wrap code path in exactly one place (#1096).
+ */
+export function namespaceWrapForTemplate(template: string): { wrapTag: NamespaceWrapTag | null; childPath: string } {
+  const wrapTag = detectRootNamespaceWrapTag(template)
+  return {
+    wrapTag,
+    childPath: wrapTag ? '.firstElementChild.firstElementChild' : '.firstElementChild',
+  }
+}
+
+/** `namespaceWrapForTemplate`, but for the multi-root fragment predicate. */
+export function multiRootNamespaceWrapForTemplate(template: string): { wrapTag: NamespaceWrapTag | null; childPath: string } {
+  const wrapTag = multiRootTemplateNeedsNamespaceWrap(template)
+  return {
+    wrapTag,
+    childPath: wrapTag ? '.firstElementChild' : '',
+  }
+}
+
+/** Wrap `html` in the namespace's synthetic root tag, or return it as-is. */
+export function wrapHtmlForNamespace(html: string, wrapTag: NamespaceWrapTag | null): string {
+  return wrapTag ? `<${wrapTag}>${html}</${wrapTag}>` : html
 }
 
 /**
@@ -159,14 +230,13 @@ function extractConditionalBranchTemplates(template: string): string[] | null {
  *
  *   ` const __tpl = document.createElement('template'); __tpl.innerHTML = \`${template}\`; return __tpl.content.firstElementChild.cloneNode(true) `
  *
- * For SVG roots, the `innerHTML` is wrapped in `<svg>...</svg>` and the
- * traversal descends one extra level.
+ * For SVG/MathML roots, the `innerHTML` is wrapped in the matching
+ * namespace root tag and the traversal descends one extra level.
  */
 export function emitTemplateCloneInline(template: string): string {
-  if (templateRootIsSvg(template)) {
-    return `const __tpl = document.createElement('template'); __tpl.innerHTML = \`<svg>${template}</svg>\`; return __tpl.content.firstElementChild.firstElementChild.cloneNode(true)`
-  }
-  return `const __tpl = document.createElement('template'); __tpl.innerHTML = \`${template}\`; return __tpl.content.firstElementChild.cloneNode(true)`
+  const { wrapTag, childPath } = namespaceWrapForTemplate(template)
+  const html = wrapHtmlForNamespace(template, wrapTag)
+  return `const __tpl = document.createElement('template'); __tpl.innerHTML = \`${html}\`; return __tpl.content${childPath}.cloneNode(true)`
 }
 
 /**
@@ -177,13 +247,14 @@ export function emitTemplateCloneInline(template: string): string {
  * STATIC-ONLY skeleton produced by `buildLoopSkeletonTemplate` (dynamic attrs
  * omitted, text markers empty) — never the per-row interpolated `template`.
  *
- * SVG namespace wrap mirrors `emitTemplateCloneLines` (#135 / #1088):
- * `templateRootIsSvg` is re-checked against the skeleton (same root tag as
- * the interpolated template, so the same wrap decision applies).
+ * Namespace wrap mirrors `emitTemplateCloneLines` (#135 / #1088 / #1096):
+ * `detectRootNamespaceWrapTag` is re-checked against the skeleton (same
+ * root tag as the interpolated template, so the same wrap decision
+ * applies).
  */
 export function emitHoistedTemplateDecl(lines: string[], indent: string, tplVar: string, skeletonTemplate: string): void {
-  const isSvg = templateRootIsSvg(skeletonTemplate)
-  const html = isSvg ? `<svg>${skeletonTemplate}</svg>` : skeletonTemplate
+  const { wrapTag } = namespaceWrapForTemplate(skeletonTemplate)
+  const html = wrapHtmlForNamespace(skeletonTemplate, wrapTag)
   lines.push(`${indent}const ${tplVar} = document.createElement('template')`)
   lines.push(`${indent}${tplVar}.innerHTML = \`${html}\``)
 }
@@ -194,9 +265,7 @@ export function emitHoistedTemplateDecl(lines: string[], indent: string, tplVar:
  * `emitTemplateCloneInline` / `emitTemplateCloneLines` parse-and-clone.
  */
 export function hoistedCloneExpr(tplVar: string, skeletonTemplate: string): string {
-  return templateRootIsSvg(skeletonTemplate)
-    ? `${tplVar}.content.firstElementChild.firstElementChild.cloneNode(true)`
-    : `${tplVar}.content.firstElementChild.cloneNode(true)`
+  return `${tplVar}.content${namespaceWrapForTemplate(skeletonTemplate).childPath}.cloneNode(true)`
 }
 
 /**
@@ -204,17 +273,12 @@ export function hoistedCloneExpr(tplVar: string, skeletonTemplate: string): stri
  * Returns three statements with no trailing newlines.
  */
 export function emitTemplateCloneLines(template: string, indent: string): string[] {
-  if (templateRootIsSvg(template)) {
-    return [
-      `${indent}const __tpl = document.createElement('template')`,
-      `${indent}__tpl.innerHTML = \`<svg>${template}</svg>\``,
-      `${indent}return __tpl.content.firstElementChild.firstElementChild.cloneNode(true)`,
-    ]
-  }
+  const { wrapTag, childPath } = namespaceWrapForTemplate(template)
+  const html = wrapHtmlForNamespace(template, wrapTag)
   return [
     `${indent}const __tpl = document.createElement('template')`,
-    `${indent}__tpl.innerHTML = \`${template}\``,
-    `${indent}return __tpl.content.firstElementChild.cloneNode(true)`,
+    `${indent}__tpl.innerHTML = \`${html}\``,
+    `${indent}return __tpl.content${childPath}.cloneNode(true)`,
   ]
 }
 
@@ -312,13 +376,13 @@ export function emitMultiRootTemplateCloneLines(
   varEl: string,
   varExtras: string,
 ): string[] {
-  const isSvg = multiRootTemplateNeedsSvgWrap(template)
-  // Wrap in `<svg>` so the parser walks into SVG foreign content; we then
-  // descend one level to pick up the per-item roots.
-  const innerHtmlExpr = isSvg ? `\`<svg>${template}</svg>\`` : `\`${template}\``
+  const { wrapTag, childPath } = multiRootNamespaceWrapForTemplate(template)
+  // Wrap in the namespace's root tag so the parser walks into foreign
+  // content; we then descend one level to pick up the per-item roots.
+  const innerHtmlExpr = `\`${wrapHtmlForNamespace(template, wrapTag)}\``
   // `parent` is the element whose direct children are the per-item roots
-  // (the `<svg>` wrap for SVG, the template's content for HTML).
-  const parentExpr = isSvg ? `__tpl.content.firstElementChild` : `__tpl.content`
+  // (the namespace wrap for SVG/MathML, the template's content for HTML).
+  const parentExpr = `__tpl.content${childPath}`
   return [
     `${indent}const __tpl = document.createElement('template')`,
     `${indent}__tpl.innerHTML = ${innerHtmlExpr}`,

package/src/ir-to-client-js/emit-registration.ts

@@ -203,7 +203,11 @@ export function emitRegistrationAndHydration(
   // Build ComponentDef object for hydrate()
   const defParts: string[] = [`init: init${name}`]
   if (canGenerateStaticTemplate(_ir.root, propNamesForStaticCheck, inlinableConstants, unsafeLocalNames)) {
-    const templateHtml = irToComponentTemplate(_ir.root, inlinableConstants, restSpreadNames, ctx.propsObjectName)
+    // `ctx.dynamicElements` is the claim-plan-'markup' membership
+    // (#2651) — see `generateCsrTemplate`'s identical derivation below
+    // for why this is reused as-is rather than re-derived.
+    const markupSlotIds = new Set(ctx.dynamicElements.map(e => e.slotId))
+    const templateHtml = irToComponentTemplate(_ir.root, inlinableConstants, restSpreadNames, ctx.propsObjectName, markupSlotIds)
     if (templateHtml) {
       defParts.push(buildTemplateDefPart(ctx, templateHtml))
     }

package/src/ir-to-client-js/html-template.ts

@@ -321,9 +321,22 @@ function escapeAttrValueExpr(valExpr: string): string {
  * escaped, so this is applied only at the four text-marker emit sites.
  * Hono escapes text content with the same set as attribute values
  * (`& " ' < >`), so `escapeText` delegates to the same operation.
+ *
+ * `isMarkup` (#2651) switches to `escapeTextOrMarkup` — `escapeText`'s
+ * strict superset that additionally unwraps a `bfMarkup()`-branded value
+ * raw instead of escaping it. Two of the four text-marker call sites
+ * (`irToComponentTemplateWithOpts`, `generateCsrTemplateWithOpts`) pass
+ * `true` for a slot `ctx.dynamicElements` also claims — the same
+ * membership `emit-reactive.ts` uses to pick the 'markup' writer kind for
+ * this slot's REACTIVE update, so the initial-render escape and the
+ * reactive-update escape agree on whether the slot may carry raw markup.
+ * The other two (`irToHtmlTemplate`, `irToPlaceholderTemplate`) build
+ * loop-item / conditional-branch HTML, which the reactive side always
+ * treats as plain text (`__bfText`) regardless — they never pass `true`,
+ * so they keep calling `escapeText` byte-for-byte as before.
  */
-function escapeTextSlotExpr(innerExpr: string): string {
-  return `escapeText(${innerExpr})`
+function escapeTextSlotExpr(innerExpr: string, isMarkup = false): string {
+  return `${isMarkup ? 'escapeTextOrMarkup' : 'escapeText'}(${innerExpr})`
 }
 
 /**
@@ -901,7 +914,20 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
             case 'jsx-children': {
               const hoistedRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, true)
               const childHtml = p.value.children.map(c => hoistedRecurse(c)).join('')
-              return `${quotePropName(p.name)}: \`${childHtml}\``
+              // Brand the assembled HTML (#2651) — every text segment inside
+              // `childHtml` was already escaped node-by-node during
+              // `hoistedRecurse`'s own build, so the concatenated result is
+              // safe to splice raw; the child's own template evaluates this
+              // prop through `escapeTextOrMarkup`/`escapeTextOrNode`, which
+              // trust the brand and skip re-escaping it. EXCEPT an explicit
+              // `children={<jsx/>}` prop (out of scope, unchanged): the
+              // child's `{children}` interpolation is the bare-passthrough
+              // door (`escapeTextSlotExpr`'s own docstring), never routed
+              // through an escape/unwrap call, so a branded object here
+              // would stringify to `[object Object]` instead of unwrapping.
+              return p.name === 'children'
+                ? `${quotePropName(p.name)}: \`${childHtml}\``
+                : `${quotePropName(p.name)}: bfMarkup(\`${childHtml}\`)`
             }
             case 'literal':
               return `${quotePropName(p.name)}: ${JSON.stringify(p.value.value)}`
@@ -1478,6 +1504,25 @@ export function irChildrenToJsExpr(children: IRNode[]): string {
   return `[${exprs.join(', ')}]`
 }
 
+/**
+ * Narrow gate for branding a nested `jsx-children` getter's value with
+ * `bfMarkup()` (#2651) — the `irNodeToJsExprs` counterpart of
+ * `collect-elements.ts`'s `isSingleElementJsxChildren` (duplicated rather
+ * than imported: `collect-elements.ts` already imports FROM this file, so
+ * the reverse import would cycle). Same shape, same reasoning: a
+ * `jsx-children` prop's value is always a single stored node
+ * (`AttrValueOf.jsxChildren([...])`); only when that node is a lone
+ * `'element'` does `irChildrenToJsExpr` reduce it to ONE HTML-string
+ * template literal — the shape `bfMarkup` + `escapeTextOrNode` /
+ * `escapeTextOrMarkup` have a proven contract for. A `'fragment'` (multiple
+ * children) or `'conditional'` node reduces to an array literal or a
+ * nested ternary instead — left unbranded here for the same reason as the
+ * `collect-elements.ts` twin.
+ */
+function isSingleElementJsxChildren(nodes: IRNode[]): boolean {
+  return nodes.length === 1 && nodes[0].type === 'element'
+}
+
 function irNodeToJsExprs(node: IRNode): string[] {
   switch (node.type) {
     case 'component': {
@@ -1488,8 +1533,19 @@ function irNodeToJsExprs(node: IRNode): string[] {
             return `${quotePropName(p.name)}: ${attrValueToString(p.value) ?? 'undefined'}`
           }
           switch (p.value.kind) {
-            case 'jsx-children':
-              return `get ${quotePropName(p.name)}() { return ${irChildrenToJsExpr(p.value.children)} }`
+            case 'jsx-children': {
+              // Brand (#2651) only the lone-'element' shape, and never an
+              // explicit `children={<jsx/>}` prop — see
+              // `isSingleElementJsxChildren` (this file) for the shape
+              // argument and the `collect-elements.ts` twin for the
+              // `children`-exclusion argument (bare-passthrough consumer,
+              // no unwrap call).
+              const jsxExpr = irChildrenToJsExpr(p.value.children)
+              const wrapped = (p.name !== 'children' && isSingleElementJsxChildren(p.value.children))
+                ? `bfMarkup(${jsxExpr})`
+                : jsxExpr
+              return `get ${quotePropName(p.name)}() { return ${wrapped} }`
+            }
             case 'literal':
               return `get ${quotePropName(p.name)}() { return ${JSON.stringify(p.value.value)} }`
             case 'boolean-shorthand':
@@ -1644,6 +1700,20 @@ export interface TemplateOptions {
    * the template phase agree on which children defer (dropped-prop fix).
    */
   deferredChildSlots?: ReadonlySet<string>
+  /**
+   * Slot ids of top-level, non-conditional dynamic expressions
+   * (`ctx.dynamicElements`, populated by `collectElements` — the exact set
+   * `emit-reactive.ts`'s `emitDynamicTextUpdates` claims `kind: 'markup'`
+   * for on the REACTIVE side, #2651). When a text-marker expression's
+   * `slotId` is a member, `escapeTextSlotExpr` emits `escapeTextOrMarkup`
+   * instead of `escapeText` so a `bfMarkup()`-branded prop value (a JSX
+   * element passed at a non-`children` component prop position) reaches
+   * the initial-render template raw, matching what the reactive writer
+   * already does via `escapeTextOrNode`. Computed once per component from
+   * `ctx.dynamicElements` by `irToComponentTemplate` / `generateCsrTemplate`
+   * — never re-derived here.
+   */
+  markupSlotIds?: ReadonlySet<string>
 }
 
 /**
@@ -1659,9 +1729,10 @@ export function irToComponentTemplate(
   node: IRNode,
   inlinableConstants?: Map<string, string>,
   restSpreadNames?: Set<string>,
-  propsObjectName?: string | null
+  propsObjectName?: string | null,
+  markupSlotIds?: ReadonlySet<string>
 ): string {
-  return irToComponentTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, loopDepth: -1 })
+  return irToComponentTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, loopDepth: -1, markupSlotIds })
 }
 
 function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): string {
@@ -1829,7 +1900,8 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
         ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')`
         : wrapped
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`
+        const isMarkup = opts.markupSlotIds?.has(node.slotId) ?? false
+        return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped, isMarkup)}}<!--/-->`
       }
       return `\${${value}}`
     }
@@ -1873,7 +1945,12 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
             case 'jsx-children': {
               const hoistedRecurse = (n: IRNode): string => irToComponentTemplateWithOpts(n, { ...opts, inHoistedChildren: true })
               const childHtml = p.value.children.map(c => hoistedRecurse(c)).join('')
-              return `${quotePropName(p.name)}: \`${childHtml}\``
+              // Brand the assembled HTML (#2651), except an explicit
+              // `children={<jsx/>}` prop — see the identical
+              // `irToHtmlTemplate` case above for both arguments.
+              return p.name === 'children'
+                ? `${quotePropName(p.name)}: \`${childHtml}\``
+                : `${quotePropName(p.name)}: bfMarkup(\`${childHtml}\`)`
             }
             case 'literal':
               return `${quotePropName(p.name)}: ${JSON.stringify(p.value.value)}`
@@ -2075,7 +2152,14 @@ export function generateCsrTemplate(
     }
   }
   const effectiveUnsafeLocalNames = mergeCsrNullUnsafe(ctx, unsafeLocalNames)
-  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, unsafeLocalNames: effectiveUnsafeLocalNames, deferredChildSlots, loopDepth: -1 })
+  // `ctx.dynamicElements` (populated by `collectElements`, before any
+  // template-string build runs) IS the claim-plan-'markup' membership
+  // `emit-reactive.ts` claims for these same slot ids on the reactive
+  // side (#2651) — every entry is already non-conditional / non-`@client`
+  // by construction (`collectElements`'s `expression` visitor only pushes
+  // here). Reused as-is, not re-derived.
+  const markupSlotIds = new Set(ctx.dynamicElements.map(e => e.slotId))
+  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, unsafeLocalNames: effectiveUnsafeLocalNames, deferredChildSlots, loopDepth: -1, markupSlotIds })
 }
 
 /**
@@ -2440,7 +2524,8 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
           ? `Array.isArray(${expr}) ? ${expr}.join('') : (${expr} ?? '')`
           : expr
         if (node.slotId) {
-          return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(expr)}}<!--/-->`
+          const isMarkup = opts.markupSlotIds?.has(node.slotId) ?? false
+          return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(expr, isMarkup)}}<!--/-->`
         }
         return `\${${value}}`
       }
@@ -2499,7 +2584,13 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
             case 'jsx-children': {
               const hoistedRecurse = (n: IRNode): string => generateCsrTemplateWithOpts(n, { ...opts, inHoistedChildren: true })
               const childHtml = p.value.children.map(c => hoistedRecurse(c)).join('')
-              return `${quotePropName(p.name)}: \`${childHtml}\``
+              // Brand the assembled HTML (#2651), except an explicit
+              // `children={<jsx/>}` prop — see the identical
+              // `irToHtmlTemplate` case (top of this file) for both
+              // arguments.
+              return p.name === 'children'
+                ? `${quotePropName(p.name)}: \`${childHtml}\``
+                : `${quotePropName(p.name)}: bfMarkup(\`${childHtml}\`)`
             }
             case 'literal':
               return `${quotePropName(p.name)}: ${JSON.stringify(p.value.value)}`

package/src/ir-to-client-js/imports.ts

@@ -20,6 +20,10 @@ export const RUNTIME_IMPORT_CANDIDATES = [
   'createPortal',
   'provideContext', 'createContext', 'useContext',
   'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss', 'escapeAttr', 'escapeText', 'escapeTextOrNode',
+  // JSX-element-as-non-children-prop markup brand (#2651) — `bfMarkup` wraps
+  // the compiler-built HTML at the producer (renderChild / initChild props);
+  // `escapeTextOrMarkup` unwraps it at the claim-plan-'markup' template slot.
+  'bfMarkup', 'escapeTextOrMarkup',
   'qsa', 'qsaItem', 'qsaChildScope', 'qsaChildScopes', 'upsertChildItem', '__slot', '__bfSlot', '__bfText',
   // Claim-plan interpreter (slot unification A2/A3, spec/slot-unification.md)
   // — the "one claim mechanism" that replaced `patchSlotRange` and

package/src/ir-to-client-js/index.ts

@@ -259,7 +259,12 @@ function generateTemplateOnlyMount(ir: ComponentIR, ctx: ClientJsContext): strin
   let templateHtml: string | undefined
 
   if (canGenerateStaticTemplate(ir.root, propNamesForStaticCheck, inlinableConstants, unsafeLocalNames)) {
-    templateHtml = irToComponentTemplate(ir.root, inlinableConstants, restSpreadNames, ctx.propsObjectName)
+    // `ctx.dynamicElements` is always empty on this template-only path
+    // (`needsClientJs(ctx)` gates it) — passed through anyway so this
+    // matches `emitRegistrationAndHydration`'s derivation byte-for-byte
+    // rather than special-casing "no markup slots here" (#2651).
+    const markupSlotIds = new Set(ctx.dynamicElements.map(e => e.slotId))
+    templateHtml = irToComponentTemplate(ir.root, inlinableConstants, restSpreadNames, ctx.propsObjectName, markupSlotIds)
   }
 
   // CSR fallback: when static template generation fails (e.g., components with