@barefootjs/jsx 0.24.1 → 0.26.0

package/src/__tests__/reactive-factory-rename-fidelity.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Regression tests for #2341 BUG-1: reactive-factory call-site inlining used
+ * to rename identifiers with a whole-body regex (`\bname\b` -> `name_bf0`,
+ * applied three times in sequence for suffix-renaming, param substitution,
+ * and return->caller renaming). A regex has no notion of AST position, so
+ * it also matched string-literal contents, template-literal text chunks,
+ * object/property-access keys, and JSX intrinsic tags that merely happened
+ * to spell the same identifier — corrupting them.
+ *
+ * Fix: collect exact identifier-node rename sites once at detection time
+ * (`detectReactiveFactory`), then apply a single merged bottom-to-top
+ * position splice at inline time (`inlineFactoryCallAtSite`) instead of any
+ * text search. This file pins the corruption classes the old regex produced
+ * and the BF114 diagnostic for the one shape the new approach must decline
+ * rather than silently substitute (a factory parameter re-declared inside
+ * the body).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { analyzeComponent } from '../analyzer'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+describe('AST-position-based rename fidelity (#2341 BUG-1)', () => {
+  test('R1: string-literal argument sharing a local-binding name is preserved', () => {
+    // `stored` must feed into `createSignal` (not merely sit unused) so the
+    // general local-constant retention pass keeps the statement — an
+    // unrelated, pre-existing behavior of the component-body pipeline, out
+    // of scope for #2341.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createTheme(initial: string) {
+        const stored = localStorage.getItem('stored') ?? initial
+        const [theme, setTheme] = createSignal(stored)
+        return [theme, setTheme] as const
+      }
+
+      export function App() {
+        const [theme, setTheme] = createTheme('light')
+        return <button onClick={() => setTheme('dark')}>{theme()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'App.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    // The string literal argument to getItem must stay untouched...
+    expect(clientJs).toMatch(/localStorage\.getItem\('stored'\)/)
+    expect(clientJs).not.toMatch(/'stored_bf/)
+    // ...while the local binding declaration is still suffix-renamed.
+    expect(clientJs).toMatch(/stored_bf\d+ = localStorage/)
+  })
+
+  test('R2: SSR template also preserves the string literal', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createTheme(initial: string) {
+        const stored = localStorage.getItem('stored') ?? initial
+        const [theme, setTheme] = createSignal(stored)
+        return [theme, setTheme] as const
+      }
+
+      export function App() {
+        const [theme, setTheme] = createTheme('light')
+        return <button onClick={() => setTheme('dark')}>{theme()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'App.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const template = result.files.find(f => f.type === 'markedTemplate')
+    expect(template).toBeDefined()
+    expect(template!.content).toContain("getItem('stored')")
+  })
+
+  test('R3: template-literal text chunks are preserved, only substitutions rename', () => {
+    // Tuple factories require every return element to be destructured at
+    // the call site (arity must match), so all three elements are bound.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createLabelled(initial: string) {
+        const [value, setValue] = createSignal(initial)
+        const stored = initial
+        const label = \`\${stored} stored\`
+        return [value, setValue, label] as const
+      }
+
+      export function Labelled() {
+        const [value, setValue, label] = createLabelled('x')
+        return <p>{value()} {label}</p>
+      }
+    `
+
+    const result = compileJSX(source, 'Labelled.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    // The substitution `${stored}` renames with the local; the literal text
+    // chunk ` stored` after it must not.
+    expect(clientJs).toMatch(/`\$\{stored_bf\d+\} stored`/)
+  })
+
+  test('R4: shorthand property + string-literal argument expands to longhand (Repro B)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createUser(name: string) {
+        const [user, setUser] = createSignal({ name, loggedIn: false })
+        return [user, setUser] as const
+      }
+
+      export function Profile() {
+        const [user, setUser] = createUser('Alice')
+        return <p onClick={() => setUser({ name: 'Bob', loggedIn: true })}>{user().name}</p>
+      }
+    `
+
+    const result = compileJSX(source, 'Profile.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).toMatch(/\{\s*name:\s*'Alice',\s*loggedIn:\s*false\s*\}/)
+  })
+
+  test('R5: shorthand property with a suffix-renamed local keeps its key', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createBox(initial: number) {
+        const size = initial + 1
+        const [box, setBox] = createSignal({ size })
+        return { box, setBox }
+      }
+
+      export function BoxDisplay() {
+        const { box, setBox } = createBox(1)
+        return <p onClick={() => setBox({ size: 2 })}>{box().size}</p>
+      }
+    `
+
+    const result = compileJSX(source, 'BoxDisplay.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).toMatch(/\{\s*size:\s*size_bf\d+\s*\}/)
+  })
+
+  test('R6: caller-rename of a return identifier leaves unrelated strings alone (Repro C)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createInput(initial: string) {
+        const [value, setValue] = createSignal(initial)
+        const update = (next: string) => {
+          if (next.length > 10) throw new Error('value too long')
+          setValue(next)
+        }
+        return [value, update] as const
+      }
+
+      export function Field() {
+        const [email, setEmail] = createInput('')
+        return <input value={email()} onInput={(e) => setEmail(e.target.value)} />
+      }
+    `
+
+    const result = compileJSX(source, 'Field.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).toContain("'value too long'")
+    expect(clientJs).not.toContain("throw new Error('email")
+    // The wrapper's declaration is renamed to the caller's setter name.
+    expect(clientJs).toMatch(/setEmail\s*=/)
+  })
+
+  test('R7: object-pattern shorthand binding (nested callback parameter) expands and keeps its key', () => {
+    // The ObjectBindingPattern shape is exercised on a nested callback's own
+    // parameter — `({ pos }) => ...` — rather than a top-level `const { pos }
+    // = ...` body statement: the latter is dropped by an unrelated,
+    // pre-existing gap in the component-body local-constant pipeline (out of
+    // scope for #2341; confirmed to reproduce identically outside any
+    // factory). The callback parameter here deliberately shadows the
+    // factory's own `pos` binding, pinning the alpha-rename guarantee from
+    // the #2341 BUG-1 spec: the walker does not stop at nested-function
+    // boundaries, so the shadowing parameter and the outer binding rename
+    // identically and consistently.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createPoint(seed: number) {
+        const [pos, setPos] = createSignal(seed)
+        const moveTo = ({ pos }: { pos: number }) => setPos(pos)
+        return { pos, moveTo }
+      }
+
+      export function PointDisplay() {
+        const { moveTo } = createPoint(0)
+        return <p onClick={() => moveTo({ pos: 5 })}>ok</p>
+      }
+    `
+
+    const result = compileJSX(source, 'PointDisplay.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).toMatch(/\{\s*pos:\s*pos_bf\d+\s*\}/)
+  })
+
+  test('R8: property keys and .prop tails sharing a param name are untouched', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createConfigured(initial: number) {
+        const config = { initial: 0 }
+        const [n, setN] = createSignal(config.initial ?? initial)
+        return [n, setN] as const
+      }
+
+      export function Counter() {
+        const [n, setN] = createConfigured(5)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Counter.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).toMatch(/\{\s*initial:\s*0\s*\}/)
+    expect(clientJs).toMatch(/config_bf\d+\.initial/)
+    expect(clientJs).toMatch(/\?\?\s*5/)
+  })
+
+  test('R9: a nested declaration that shadows a factory parameter declines with BF114', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createOops(initial: number) {
+        const [n, setN] = createSignal(initial)
+        const reset = (initial: number) => setN(initial)
+        return { n, reset }
+      }
+
+      export function Oops() {
+        const { n, reset } = createOops(0)
+        return <button onClick={() => reset(0)}>{n()}</button>
+      }
+    `
+
+    const ctx = analyzeComponent(source, 'Oops.tsx')
+    expect(ctx.signals.length).toBe(0)
+
+    const result = compileJSX(source, 'Oops.tsx', { adapter })
+    const bf114 = result.errors.find(e => e.code === 'BF114')
+    expect(bf114).toBeDefined()
+    expect(bf114!.message).toContain('initial')
+    expect(bf114!.message).toContain('createOops')
+  })
+
+  test('R10: an argument expression is never re-scanned by a later rename pass (cascade fix)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createInput(initial: string) {
+        const [value, setValue] = createSignal(initial)
+        const update = (next: string) => setValue(next)
+        return [value, update] as const
+      }
+
+      export function Field() {
+        const value = 'seed'
+        const [email, setEmail] = createInput(value)
+        return <input value={email()} onInput={(e) => setEmail(e.target.value)} />
+      }
+    `
+
+    const result = compileJSX(source, 'Field.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    // `value` (the outer local passed as the argument) must reach
+    // createSignal verbatim — a later return->caller rename pass renaming
+    // the factory's own `value` return identifier to `email` must not
+    // re-scan and corrupt the already-substituted argument text.
+    expect(clientJs).toMatch(/createSignal\(\s*value\s*\)/)
+  })
+
+  test('R11: a tuple array-binding pattern in the body is not shorthand-expanded (ArrayBindingPattern trap)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function createCounter(initial: number) {
+        const [c, s] = createSignal(initial)
+        return [c, s] as const
+      }
+
+      export function Counter() {
+        const [count, setCount] = createCounter(0)
+        return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+      }
+    `
+
+    const result = compileJSX(source, 'Counter.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+    const clientJs = result.files.find(f => f.type === 'clientJs')!.content
+    expect(clientJs).not.toMatch(/\[\s*\w+:\s/)
+  })
+})

package/src/__tests__/to-locale-date-lowering.test.ts

@@ -88,14 +88,39 @@ describe('matchToLocaleDateStringCall accept/decline table', () => {
     })
   })
 
+  test('a canonical IANA zone timeZone is admitted via the build probe (#2344)', () => {
+    const node = match(`createdAt.toLocaleDateString('ja-JP', { timeZone: 'Asia/Tokyo' })`)
+    expect(node).toMatchObject({
+      helper: 'format_date',
+      args: [
+        { kind: 'identifier', name: 'createdAt' },
+        { kind: 'literal', value: 'YYYY/M/D' },
+        { kind: 'literal', value: 'Asia/Tokyo' },
+        { kind: 'array-literal', elements: [] },
+      ],
+    })
+    expect(match(`createdAt.toLocaleDateString('en-US', { timeZone: 'America/New_York' })`)).toMatchObject({
+      helper: 'format_date',
+      args: [expect.anything(), { value: 'M/D/YYYY' }, { value: 'America/New_York' }, expect.anything()],
+    })
+  })
+
+  test('unverifiable timeZone literals decline (#2344 probe-and-verify)', () => {
+    // unknown zone: real toLocaleDateString throws RangeError
+    expect(match(`createdAt.toLocaleDateString('ja-JP', { timeZone: 'Asia/Tokyoo' })`)).toBeNull()
+    // non-canonical case: the probe canonicalizes it away, and backend
+    // tzdata layers disagree on case-folded spellings
+    expect(match(`createdAt.toLocaleDateString('ja-JP', { timeZone: 'asia/tokyo' })`)).toBeNull()
+    // host-environment aliases
+    expect(match(`createdAt.toLocaleDateString('ja-JP', { timeZone: 'Local' })`)).toBeNull()
+  })
+
   test('implicit-environment and runtime-value shapes all decline', () => {
     // zero-arg / locale-only: reads host locale and/or timezone
     expect(match(`createdAt.toLocaleDateString()`)).toBeNull()
     expect(match(`createdAt.toLocaleDateString('ja-JP')`)).toBeNull()
     // non-literal locale: no build-time CLDR resolution
     expect(match(`createdAt.toLocaleDateString(locale, { timeZone: 'UTC' })`)).toBeNull()
-    // IANA zone name: host-tzdata coupling
-    expect(match(`createdAt.toLocaleDateString('ja-JP', { timeZone: 'Asia/Tokyo' })`)).toBeNull()
     // non-literal timeZone
     expect(match(`createdAt.toLocaleDateString('ja-JP', { timeZone: tz })`)).toBeNull()
     // out-of-range fixed offsets: real toLocaleDateString throws RangeError

package/src/adapters/dangerous-inner-html.ts

@@ -1,30 +1,39 @@
 /**
  * Shared `dangerouslySetInnerHTML={{ __html: expr }}` recognition + policy
- * (#2207). Single place every template adapter calls from `renderElement`,
- * so the injection-safety-relevant policy — "only a compile-time string
- * literal is lowered; anything else refuses loudly" — lives in exactly one
- * reviewable spot instead of being re-derived independently in 8 adapters.
+ * (#2207, dynamic lowering #2319). Single place every template adapter calls
+ * from `renderElement`, so the injection-safety-relevant policy lives in
+ * exactly one reviewable spot instead of being re-derived independently in
+ * 8 adapters. `resolveDangerousInnerHtml` classifies the `__html` value into
+ * three cases the adapter then renders uniformly:
  *
- * Scope, deliberately narrow for v1 (see #2207 / #2215 for the follow-up):
- * a static literal is spliced directly into the adapter's OWN template
- * source as trusted text (same trust domain as hand-writing the HTML into
- * the template) — never routed through a `|safe`/`|raw`/`{!! !!}`-style
- * runtime raw-output primitive, which would reopen a template-source
- * injection surface for no benefit (the value is already fully known at
- * compile time). A DYNAMIC value (signal, prop, a template literal WITH a
- * substitution, local const, anything non-literal) is refused with
- * `BF101` — a no-substitution template literal is NOT dynamic; the parser
- * normalizes it to the same `{kind:'literal', literalType:'string'}` shape
- * as a plain string literal, so it's treated identically (see
- * `staticHtmlLiteral` below). Hono/CSR already support it (the client
- * drives a `createEffect`-based `el.innerHTML = …`
- * assignment — see `ir-to-client-js/emit-reactive.ts`), so this is a
- * template-adapter-only gap, tracked separately (#2215) rather than folded
- * into this literal-only cut.
+ * - `static` — a compile-time string literal. Spliced directly into the
+ *   adapter's OWN template source as trusted text (same trust domain as
+ *   hand-writing the HTML into the template), guarded per-adapter against
+ *   that language's template metacharacters (`dangerousInnerHtmlMetachar
+ *   Violation`). NOT routed through a runtime raw-output primitive — the
+ *   value is fully known at compile time, so a runtime sink would reopen a
+ *   template-source injection surface for no benefit.
+ *
+ * - `dynamic` — a prop-/signal-derived value (a signal read, prop, template
+ *   literal WITH a substitution, local const, `??`-fallback, anything
+ *   non-literal). The adapter serializes the `__html` expression via its own
+ *   `convertExpressionTo<Lang>` and wraps the result in its runtime
+ *   raw-output sink (Blade `{!! !!}`, ERB bare `<%= %>`, Go `template.HTML`,
+ *   Jinja/MiniJinja `|safe`, Twig `|raw`, Mojolicious `<%== %>`, Xslate
+ *   `mark_raw`). The runtime evaluates the expression at request time — the
+ *   VALUE is never spliced into template source, so no metachar guard
+ *   applies. This matches React's contract ("dangerously" = the caller owns
+ *   the value's safety) and the Hono/CSR path, which already drives a
+ *   `createEffect`-based `el.innerHTML = …` assignment (see
+ *   `ir-to-client-js/emit-reactive.ts`).
+ *
+ * - `unlowerable` — the value is not a `{ __html: <expr> }` object literal
+ *   at all (bare boolean/spread, or a variable holding the object). No
+ *   `__html` expression to lower, so the adapter refuses with `BF101`.
  */
 
 import type { CompilerError, IRAttribute, IRElement, SourceLocation } from '../types.ts'
-import { parseExpression, type ParsedExpr } from '../expression-parser.ts'
+import { parseExpression, stringifyParsedExpr, type ParsedExpr } from '../expression-parser.ts'
 
 const DANGEROUS_INNER_HTML_ATTR = 'dangerouslySetInnerHTML'
 
@@ -33,8 +42,28 @@ export function isDangerousInnerHtmlAttr(attr: IRAttribute): boolean {
 }
 
 export type DangerousInnerHtmlResolution =
+  // A compile-time string literal — spliced directly into the adapter's own
+  // template source as trusted text (guarded per-adapter against that
+  // language's template metacharacters). #2207.
   | { kind: 'static'; html: string }
-  | { kind: 'dynamic'; expr: string; loc: SourceLocation }
+  // A dynamic (prop-/signal-derived) `__html` value. `valueParsed` is the
+  // inner expression's IR-parsed tree and `valueExpr` its re-stringified
+  // source — both accepted by every adapter's `convertExpressionTo<Lang>`,
+  // which serializes the expression so the adapter can wrap the result in
+  // its own runtime raw-output sink (Blade `{!! !!}`, ERB bare `<%= %>`,
+  // Go `template.HTML`, Jinja/MiniJinja `|safe`, Twig `|raw`, Mojolicious
+  // `<%== %>`, Xslate `mark_raw`). NO template-metacharacter guard applies:
+  // the value is evaluated at request time by the target runtime, never
+  // spliced into template source, so it cannot forge a template construct.
+  // This matches React semantics ("dangerously" = the caller owns the
+  // safety of the value) and the Hono/CSR path, which already drives a
+  // signal-reactive `el.innerHTML = …`. #2319 (successor to #2215).
+  | { kind: 'dynamic'; valueExpr: string; valueParsed: ParsedExpr; loc: SourceLocation }
+  // The attribute value is not a `{ __html: <expr> }` object literal at all
+  // (a bare boolean/spread, or a variable holding the object) — there is no
+  // `__html` expression to lower, so the adapter refuses with BF101. `expr`
+  // is the raw source for the diagnostic.
+  | { kind: 'unlowerable'; expr: string; loc: SourceLocation }
 
 /**
  * Resolve `element`'s `dangerouslySetInnerHTML` attribute, if present.
@@ -57,35 +86,44 @@ export function resolveDangerousInnerHtml(element: IRElement): DangerousInnerHtm
   if (!attr) return null
   if (attr.clientOnly) return null
   if (attr.value.kind !== 'expression') {
-    return { kind: 'dynamic', expr: '', loc: attr.loc }
+    return { kind: 'unlowerable', expr: '', loc: attr.loc }
   }
   const parsed = attr.value.parsed ?? parseExpression(attr.value.expr.trim())
-  const html = staticHtmlLiteral(parsed)
-  if (html !== null) return { kind: 'static', html }
-  return { kind: 'dynamic', expr: attr.value.expr, loc: attr.loc }
+  const value = htmlPropValue(parsed)
+  // Not a `{ __html: <expr> }` object literal — nothing to lower.
+  if (value === null) return { kind: 'unlowerable', expr: attr.value.expr, loc: attr.loc }
+  // A compile-time string literal (a quoted string or a no-substitution
+  // template literal, which the parser normalises to the same
+  // `{kind:'literal', literalType:'string'}` shape) is spliced as trusted
+  // template text; everything else is a dynamic value the adapter lowers
+  // through its raw-output sink.
+  if (value.kind === 'literal' && value.literalType === 'string') {
+    return { kind: 'static', html: value.value as string }
+  }
+  return {
+    kind: 'dynamic',
+    valueExpr: stringifyParsedExpr(value),
+    valueParsed: value,
+    loc: attr.loc,
+  }
 }
 
 /**
- * `{ __html: '<b>bold</b>' }` → the literal string, nothing else. Exactly
- * one property, key `__html` (identifier or string form — `{ __html: … }`
- * and `{ '__html': … }` are equivalent JS), non-shorthand (`{ __html }`
- * would read a variable, not a literal), value a compile-time STRING
- * LITERAL `ParsedExpr` (`{kind:'literal', literalType:'string'}`) — which
- * a no-substitution template literal (`` `<b>bold</b>` ``) already parses
- * to, so it's accepted the same as a quoted string. A template literal
- * WITH a substitution, a local `const`, string concatenation, or any other
- * non-literal shape all fall through to `null` — no const-folding, no
- * partial evaluation. Widening this is a single-place change here,
- * deliberately not attempted in v1 (#2207).
+ * The `__html` value expression of a `{ __html: <expr> }` object literal, or
+ * `null` when the parsed value is not that shape. Exactly one property, key
+ * `__html` (identifier or string form — `{ __html: … }` and `{ '__html': … }`
+ * are equivalent JS). Shorthand `{ __html }` reads a variable of that name;
+ * it is a valid dynamic value (its `value` is the identifier `__html`), so it
+ * is admitted the same as `{ __html: __html }` — the caller then classifies
+ * literal-vs-dynamic. Spreads, computed keys, and multi-property objects fall
+ * through to `null` (the caller refuses them).
  */
-function staticHtmlLiteral(parsed: ParsedExpr): string | null {
+function htmlPropValue(parsed: ParsedExpr): ParsedExpr | null {
   if (parsed.kind !== 'object-literal') return null
   if (parsed.properties.length !== 1) return null
   const [prop] = parsed.properties
-  if (prop.shorthand) return null
   if (prop.key !== '__html') return null
-  if (prop.value.kind !== 'literal' || prop.value.literalType !== 'string') return null
-  return prop.value.value as string
+  return prop.value
 }
 
 /**
@@ -162,25 +200,40 @@ export function dangerousInnerHtmlMetacharViolation(html: string, adapterId: str
 
 /**
  * Purpose-built `BF101` for a `dangerouslySetInnerHTML` value this adapter
- * can't lower — either genuinely dynamic (not a literal) or a static
- * literal that fails the metachar guard above. Named `reason` so both
- * refusal paths funnel through the same message shape rather than growing
- * two near-identical adapter-side error strings.
+ * can't lower. Two distinct failure families funnel through here, so the base
+ * message is chosen by whether a `reason` is supplied:
+ *
+ * - WITHOUT a `reason` — the value is not the required SHAPE: it must be an
+ *   object literal with exactly one `__html` property (no spreads, extra keys,
+ *   or computed keys). The message states that contract so a near-miss like
+ *   `{ __html: x, extra: 1 }` (refused as `unlowerable`) doesn't get told it
+ *   "expects an { __html: … }" it already appears to have.
+ * - WITH a `reason` — the value IS a well-formed `{ __html: … }` object
+ *   literal that this adapter still can't lower: a static literal carrying
+ *   template metacharacters (`dangerousInnerHtmlMetacharViolation`), or — on
+ *   the Go adapter — a template-literal / conditional inner expression with no
+ *   single-argument raw form. The `reason` is the real story; the base states
+ *   only that the value can't be lowered here, not that the shape is wrong.
+ *
+ * A genuinely dynamic value with a lowerable inner expression no longer
+ * reaches here — it is lowered through the adapter's raw-output sink (#2319).
  */
 export function dangerousInnerHtmlDiagnostic(
   expr: string,
   loc: SourceLocation,
   reason?: string,
 ): CompilerError {
-  const detail = reason ? ` — ${reason}.` : ''
+  const base = reason
+    ? `dangerouslySetInnerHTML value cannot be lowered on this adapter — ${reason}`
+    : 'dangerouslySetInnerHTML requires an object literal with a single `__html` property (e.g. { __html: value }) — spreads, extra keys, and computed keys are not supported'
   return {
     code: 'BF101',
     severity: 'error',
-    message: `dangerouslySetInnerHTML requires a compile-time string literal __html value on template adapters (e.g. { __html: '...' })${expr ? `: ${expr.trim()}` : ''}${detail}`,
+    message: `${base}${expr ? `: ${expr.trim()}` : ''}`,
     loc,
     suggestion: {
       message:
-        'Dynamic or signal-derived HTML for dangerouslySetInnerHTML is only supported on Hono/CSR today (tracked separately: https://github.com/piconic-ai/barefootjs/issues/2215). Use an inline string literal, or defer it to the client with /* @client */ (e.g. dangerouslySetInnerHTML={/* @client */ { __html: expr }}) so hydration sets it instead of SSR.',
+        'Pass an object literal { __html: value } with exactly one `__html` property (a string literal is spliced as trusted template text; a prop/signal value is lowered through the adapter\'s raw-output sink). To force it onto the client instead of SSR, use /* @client */ (e.g. dangerouslySetInnerHTML={/* @client */ { __html: expr }}) so hydration sets it.',
     },
   }
 }