@barefootjs/jsx 0.23.0 → 0.25.0

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

@@ -19,22 +19,38 @@
  *     `rich-type-refusal.ts`, whose gate exempts exactly what a registered
  *     plugin claims).
  *
+ * A NON-literal locale is admitted in exactly one shape (#2324's
+ * union-typed-locale stage): a REQUIRED prop whose TS type is a closed
+ * string-literal union (`locale: 'en-US' | 'ja-JP'`). Every member's pattern
+ * resolves at build time and the pattern argument lowers to a ternary over
+ * the runtime value — runtime locale switching, still zero runtime CLDR.
+ * The type IS the contract: TS keeps the runtime value inside the union.
+ *
  * Deliberately NOT lowered (decline → loud BF021, never a silent guess):
  *   - zero-arg / locale-only calls — they read the host's locale and/or
  *     timezone, the implicit-environment hole #2273 closed;
- *   - a non-literal locale (`props.locale`) — build-time CLDR resolution is
- *     impossible; the app's i18n layer owns locale → pattern there, feeding
- *     `formatDate` directly;
+ *   - an OPEN-typed runtime locale (`locale: string`) — build-time CLDR
+ *     resolution is impossible; the app's i18n layer owns locale → pattern
+ *     there, feeding `formatDate` directly. An OPTIONAL union prop also
+ *     declines: `undefined` at runtime makes real `toLocaleDateString` read
+ *     the host locale, which no frozen pattern table can reproduce;
  *   - an IANA `timeZone` name — couples output to the host's tzdata version
  *     (only `'UTC'` and fixed `±HH:MM` offsets are deterministic);
- *   - options beyond `timeZone` (`dateStyle`, `month: 'long'`, …) — the
- *     name-table stage of #2324, not this slice;
- *   - a locale whose default format needs anything beyond numeric
- *     year/month/day in latin digits on the gregorian calendar (e.g.
- *     `ar-SA`: islamic-umalqura calendar, arabic-indic digits).
+ *   - an options bag the probe cannot reproduce EXACTLY in the token+table
+ *     vocabulary — era, dayPeriod, 2-digit year, narrow name forms,
+ *     non-literal option values ("faithful or loud", never approximate);
+ *   - a locale/options combination needing non-latin digits or a
+ *     non-gregorian calendar (e.g. `ar-SA`: islamic-umalqura, arabic-indic
+ *     digits).
+ *
+ * Options beyond `timeZone` ARE admitted when literal (#2334): the compiler
+ * probes the exact bag with `formatToParts`; month/weekday NAME parts
+ * resolve to the `MMMM`/`MMM`/`dddd`/`ddd` tokens plus the 38-slot name
+ * table shipped as an ordinary array argument — the backend receives
+ * values, never locale knowledge.
  */
 
-import type { IRMetadata } from './types.ts'
+import type { IRMetadata, TypeInfo } from './types.ts'
 import type { ParsedExpr } from './expression-parser.ts'
 import type { LoweringNode, LoweringPlugin } from './lowering-registry.ts'
 import { resolveReceiverType, baseTypeName } from './rich-type-evidence.ts'
@@ -59,68 +75,276 @@ export const TO_LOCALE_TZ_RE = /^(?:UTC|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/
  */
 const PROBE_UTC = new Date(Date.UTC(2001, 1, 3))
 
-/** Build-time cache: locale tag → derived pattern (or null = not representable). */
-const patternCache = new Map<string, string | null>()
+/**
+ * The 38-slot `names` table layout (spec/template-helpers.md "format_date"):
+ * [0..11] wide months, [12..23] abbreviated months, [24..30] wide weekdays
+ * (Sunday-first), [31..37] abbreviated weekdays.
+ */
+export interface LocaleDateFormat {
+  pattern: string
+  /** The 38-slot table, present iff `pattern` contains a name token. */
+  names: string[] | null
+}
+
+/** Build-time caches: locale tag (+ options key) → derived result (null = not representable). */
+const formatCache = new Map<string, LocaleDateFormat | null>()
+const namesCache = new Map<string, string[] | null>()
+
+/**
+ * Name-derivation context (Copilot review on #2336): many locales inflect
+ * month (and sometimes weekday) names by DATE CONTEXT — Russian renders
+ * `{month:'long'}` alone as nominative `март` but `dateStyle:'long'` as
+ * genitive `марта`. So each section of the table is derived under BOTH a
+ * `formatting` probe (name alongside a day — the form full date styles
+ * use) and a `standalone` probe (name alone), and `deriveFormat` ships
+ * whichever table the probed output actually matches.
+ */
+type NameContext = 'formatting' | 'standalone'
+
+/**
+ * Derive a locale's 24 month names (12 wide + 12 abbreviated) under one
+ * {@link NameContext}, or null when any probe fails. The compiler is the
+ * only owner of locale data; backends receive the values as an ordinary
+ * array argument and stay type-only (#2334).
+ */
+function deriveMonthNames(locale: string, ctx: NameContext): string[] | null {
+  return deriveNamesCached(`${locale}|m|${ctx}`, () => {
+    const months = (width: 'long' | 'short') =>
+      Array.from({ length: 12 }, (_, m) =>
+        probePart(
+          locale,
+          ctx === 'formatting' ? { month: width, day: 'numeric' } : { month: width },
+          Date.UTC(2001, m, 15),
+          'month',
+        ),
+      )
+    return [...months('long'), ...months('short')]
+  })
+}
 
 /**
- * Resolve a locale literal to its default date pattern in the v1
- * `format_date` token language (`YYYY`/`MM`/`M`/`DD`/`D` + literal text), or
- * null when the locale's default format is not representable. The gate is
- * structural, not an allowlist: the format must resolve to the gregorian
- * calendar in latin digits and consist solely of numeric year/month/day
- * parts (4-digit year) plus separator literals that cannot collide with the
- * token alphabet. `en-US` → `M/D/YYYY`, `ja-JP` → `YYYY/M/D`, `en-GB` →
- * `DD/MM/YYYY`, `de-DE` → `D.M.YYYY`; `ar-SA` (islamic-umalqura/arab) and
- * any 2-digit-year or era/weekday-bearing default → null.
+ * Derive a locale's 14 weekday names (7 wide + 7 abbreviated,
+ * Sunday-first — matching `Date.prototype.getUTCDay`) under one context.
+ */
+function deriveWeekdayNames(locale: string, ctx: NameContext): string[] | null {
+  return deriveNamesCached(`${locale}|w|${ctx}`, () => {
+    // 2023-01-01 was a Sunday; day offsets walk Sunday..Saturday.
+    const weekdays = (width: 'long' | 'short') =>
+      Array.from({ length: 7 }, (_, d) =>
+        probePart(
+          locale,
+          ctx === 'formatting' ? { weekday: width, month: 'numeric', day: 'numeric' } : { weekday: width },
+          Date.UTC(2023, 0, 1 + d),
+          'weekday',
+        ),
+      )
+    return [...weekdays('long'), ...weekdays('short')]
+  })
+}
+
+function probePart(
+  locale: string,
+  options: Intl.DateTimeFormatOptions,
+  utc: number,
+  type: string,
+): string {
+  const parts = new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }).formatToParts(new Date(utc))
+  const found = parts.find((p) => p.type === type)
+  if (!found || !found.value) throw new Error('missing part')
+  return found.value
+}
+
+function deriveNamesCached(key: string, derive: () => string[]): string[] | null {
+  const cached = namesCache.get(key)
+  if (cached !== undefined) return cached
+  let derived: string[] | null
+  try {
+    derived = derive()
+  } catch {
+    derived = null
+  }
+  namesCache.set(key, derived)
+  return derived
+}
+
+/**
+ * Back-compat convenience over {@link resolveLocaleDateFormat}: the
+ * default-options pattern (numeric-only or it doesn't resolve — the default
+ * date format of every locale is name-free, so `names` is always null here).
  */
 export function resolveLocaleDatePattern(locale: string): string | null {
-  const cached = patternCache.get(locale)
+  return resolveLocaleDateFormat(locale, {})?.pattern ?? null
+}
+
+/**
+ * Resolve (locale, probe options) to a `format_date` pattern — and, when the
+ * probed format contains month/weekday NAMES, the 38-slot table those tokens
+ * read (#2334). The fidelity contract: the result is exactly what the user's
+ * `toLocaleDateString(locale, options)` evaluates to under the build
+ * machine's ECMA-402 — reproduce it exactly or decline (null), never
+ * approximate. The gate is structural, not an allowlist: gregorian calendar,
+ * latin digits, and every part must be a numeric 4-digit year / numeric or
+ * named month / numeric day / named weekday / non-colliding literal.
+ * `en-US` default → `M/D/YYYY`; `en-US` + `{dateStyle:'long'}` → `MMMM D,
+ * YYYY` + names; `ja-JP` + `{dateStyle:'long'}` → `YYYY年M月D日` (numeric —
+ * no names needed, which the probe discovers naturally); era / dayPeriod /
+ * 2-digit-year / non-latn digits → null.
+ */
+export function resolveLocaleDateFormat(
+  locale: string,
+  probeOptions: Record<string, string>,
+): LocaleDateFormat | null {
+  const key = `${locale}|${JSON.stringify(probeOptions, Object.keys(probeOptions).sort())}`
+  const cached = formatCache.get(key)
   if (cached !== undefined) return cached
-  const derived = derivePattern(locale)
-  patternCache.set(locale, derived)
+  const derived = deriveFormat(locale, probeOptions)
+  formatCache.set(key, derived)
   return derived
 }
 
-function derivePattern(locale: string): string | null {
+/**
+ * Second verification instant: 2001-05-13 UTC — a SUNDAY in MAY, so both
+ * the month and weekday indexes differ from {@link PROBE_UTC}'s. The
+ * chosen name tables are re-verified against the real ICU output at this
+ * instant, closing the coincidental-match hole: a table whose form only
+ * happens to agree with the probed format AT the probe month/weekday (but
+ * diverges elsewhere) would otherwise ship a silently-wrong name — the
+ * one failure class the fidelity rule ("reproduce exactly or decline")
+ * cannot tolerate (Copilot review on #2336).
+ */
+const VERIFY_UTC = new Date(Date.UTC(2001, 4, 13))
+
+/** Render `pattern` + `names` at a fixed calendar point — the compiler-side
+ *  mirror of the runtime token scan, used only for the VERIFY_UTC check. */
+function renderPatternAt(
+  pattern: string,
+  names: readonly string[],
+  y: number,
+  m: number,
+  d: number,
+  wd: number,
+): string {
+  const pad2 = (n: number) => String(n).padStart(2, '0')
+  return pattern.replace(/YYYY|MMMM|MMM|MM|DD|dddd|ddd|M|D/g, (token) => {
+    switch (token) {
+      case 'YYYY':
+        return String(y).padStart(4, '0')
+      case 'MMMM':
+        return names[m - 1] ?? ''
+      case 'MMM':
+        return names[12 + m - 1] ?? ''
+      case 'MM':
+        return pad2(m)
+      case 'M':
+        return String(m)
+      case 'DD':
+        return pad2(d)
+      case 'D':
+        return String(d)
+      case 'dddd':
+        return names[24 + wd] ?? ''
+      default:
+        return names[31 + wd] ?? ''
+    }
+  })
+}
+
+function deriveFormat(locale: string, probeOptions: Record<string, string>): LocaleDateFormat | null {
+  let dtf: Intl.DateTimeFormat
   let parts: Intl.DateTimeFormatPart[]
   try {
-    const dtf = new Intl.DateTimeFormat(locale, { timeZone: 'UTC' })
+    dtf = new Intl.DateTimeFormat(locale, {
+      ...(probeOptions as Intl.DateTimeFormatOptions),
+      timeZone: 'UTC',
+    })
     const resolved = dtf.resolvedOptions()
     if (resolved.calendar !== 'gregory' || resolved.numberingSystem !== 'latn') return null
     parts = dtf.formatToParts(PROBE_UTC)
   } catch {
-    return null // invalid language tag
+    return null // invalid language tag or invalid/conflicting options
   }
+  // Probe instant 2001-02-03 is a Saturday in February: month index 1,
+  // weekday index 6 in the Sunday-first table. Each name part is matched
+  // against BOTH derivation contexts (formatting first — full date styles
+  // use the in-context form) so context-inflecting locales (ru: `марта`
+  // vs `март`) resolve to the table whose form the format actually uses.
+  const monthTables: Array<string[] | null> = [
+    deriveMonthNames(locale, 'formatting'),
+    deriveMonthNames(locale, 'standalone'),
+  ]
+  const weekdayTables: Array<string[] | null> = [
+    deriveWeekdayNames(locale, 'formatting'),
+    deriveWeekdayNames(locale, 'standalone'),
+  ]
+  let monthTable: string[] | null = null
+  let weekdayTable: string[] | null = null
   let pattern = ''
+  let usesNames = false
   for (const part of parts) {
     switch (part.type) {
       case 'year':
-        if (part.value !== '2001') return null // 2-digit-year default has no v1 token
+        if (part.value !== '2001') return null // 2-digit-year form has no token
         pattern += 'YYYY'
         break
-      case 'month':
-        if (part.value === '2') pattern += 'M'
-        else if (part.value === '02') pattern += 'MM'
-        else return null // name/narrow month — the later name-table stage
+      case 'month': {
+        if (part.value === '2') {
+          pattern += 'M'
+          break
+        }
+        if (part.value === '02') {
+          pattern += 'MM'
+          break
+        }
+        const wide = monthTables.find((t) => t && part.value === t[1]) ?? null
+        const abbr = wide ? null : (monthTables.find((t) => t && part.value === t[12 + 1]) ?? null)
+        if (wide) pattern += 'MMMM'
+        else if (abbr) pattern += 'MMM'
+        else return null // narrow / unmatched month form
+        monthTable = wide ?? abbr
+        usesNames = true
         break
+      }
       case 'day':
         if (part.value === '3') pattern += 'D'
         else if (part.value === '03') pattern += 'DD'
         else return null
         break
+      case 'weekday': {
+        const wide = weekdayTables.find((t) => t && part.value === t[6]) ?? null
+        const abbr = wide ? null : (weekdayTables.find((t) => t && part.value === t[7 + 6]) ?? null)
+        if (wide) pattern += 'dddd'
+        else if (abbr) pattern += 'ddd'
+        else return null // narrow / unmatched weekday form
+        weekdayTable = wide ?? abbr
+        usesNames = true
+        break
+      }
       case 'literal':
-        // A literal containing the token alphabet would be re-tokenized by
-        // the helper's scan; no real numeric-format separator does, but the
-        // gate must prove it rather than assume it.
-        if (/[YMD]/.test(part.value)) return null
+        // A literal colliding with the token alphabet would be re-tokenized
+        // by the helper's scan: any uppercase Y/M/D, or a lowercase run of
+        // three-plus `d`s (single/double `d` is not a token).
+        if (/[YMD]/.test(part.value) || /ddd/.test(part.value)) return null
         pattern += part.value
         break
       default:
-        return null // era, weekday, dayPeriod, … — not representable
+        return null // era, dayPeriod, … — not representable
     }
   }
-  if (!pattern.includes('YYYY') || !/M/.test(pattern) || !/D/.test(pattern)) return null
-  return pattern
+  // The probed format must actually be a date (guards a pathological
+  // options bag that yields, say, only a weekday).
+  if (!/YYYY|MMMM|MMM|MM|M/.test(pattern) && !/DD|D/.test(pattern)) return null
+  if (!usesNames) return { pattern, names: null }
+  // Compose the shipped 38-slot table from whichever context matched each
+  // section (unused sections default to the formatting context).
+  const names = [
+    ...(monthTable ?? monthTables[0] ?? monthTables[1] ?? Array<string>(24).fill('')),
+    ...(weekdayTable ?? weekdayTables[0] ?? weekdayTables[1] ?? Array<string>(14).fill('')),
+  ]
+  // Two-point verification: reproduce the SECOND instant (Sunday, May 13)
+  // with the frozen pattern + table and byte-compare against real ICU. A
+  // probe-index coincidence between contexts cannot survive both points.
+  if (renderPatternAt(pattern, names, 2001, 5, 13, 0) !== dtf.format(VERIFY_UTC)) return null
+  return { pattern, names }
 }
 
 /**
@@ -131,6 +355,95 @@ function derivePattern(locale: string): string | null {
  * `date-lowering.ts`'s `matchDateCall` exactly (prop-rooted, `Date`-typed,
  * no in-file type shadow, `EMPTY_BINDINGS`).
  */
+/** A quoted string-literal union member's value, or null when the member is anything else. */
+function unionMemberLiteral(member: TypeInfo): string | null {
+  const m = /^'([^'\\]*)'$|^"([^"\\]*)"$/.exec(member.raw.trim())
+  return m ? (m[1] ?? m[2]) : null
+}
+
+/**
+ * Resolve a NON-literal `locale` argument to its closed set of string-literal
+ * union members (#2324's union-typed-locale stage), or null to decline.
+ * Prop-rooting follows `resolveReceiverType`'s rules exactly, per props
+ * mode (Copilot review on #2331 — the looser first cut could mis-identify a
+ * same-named LOCAL binding as the prop):
+ *   - object-props mode (`propsObjectName` set): ONLY a
+ *     `<propsObjectName>.<name>` member — a bare identifier is never a prop
+ *     there;
+ *   - destructured mode: ONLY a bare identifier that is one of
+ *     `propsParams` (resolved through `sourceName` for aliased bindings) —
+ *     there is no props object to member-access.
+ * The prop must be REQUIRED (an optional union can be `undefined` at
+ * runtime, and real `toLocaleDateString(undefined, …)` falls back to the
+ * HOST locale — the implicit-environment read this plugin exists to rule
+ * out) and every union member a quoted string literal.
+ */
+function resolveLocaleUnionMembers(locale: ParsedExpr, metadata: IRMetadata): string[] | null {
+  let sourcePropName: string | null = null
+  if (metadata.propsObjectName) {
+    if (
+      locale.kind === 'member' &&
+      !locale.computed &&
+      locale.object.kind === 'identifier' &&
+      locale.object.name === metadata.propsObjectName
+    ) {
+      sourcePropName = locale.property
+    }
+  } else if (locale.kind === 'identifier') {
+    const name = locale.name
+    const param = metadata.propsParams?.find((pp) => pp.name === name)
+    if (param) sourcePropName = param.sourceName ?? param.name
+  }
+  if (!sourcePropName) return null
+  const target = sourcePropName
+  const prop = metadata.propsType?.properties?.find((p) => p.name === target)
+  if (!prop || prop.optional) return null
+  const type = prop.type
+  if (type.kind !== 'union' || !type.unionTypes || type.unionTypes.length === 0) return null
+  const members: string[] = []
+  for (const member of type.unionTypes) {
+    const value = unionMemberLiteral(member)
+    if (value === null) return null
+    members.push(value)
+  }
+  return members
+}
+
+const strLit = (value: string): ParsedExpr => ({ kind: 'literal', value, literalType: 'string' })
+
+/** Array-literal ParsedExpr over string values (the `names` helper argument). */
+function strArr(values: readonly string[]): ParsedExpr {
+  return {
+    kind: 'array-literal',
+    elements: values.map((v) => strLit(v)),
+    raw: JSON.stringify(values),
+  } as ParsedExpr
+}
+
+/**
+ * Fold per-union-member values into a right-folded ternary over the runtime
+ * locale expression (last member needs no guard — the TS type keeps the
+ * value inside the union). Equal values collapse to the plain leaf.
+ */
+function foldMembers(
+  locale: ParsedExpr,
+  members: readonly string[],
+  leaves: readonly ParsedExpr[],
+  allEqual: boolean,
+): ParsedExpr {
+  let expr = leaves[leaves.length - 1]
+  if (allEqual) return expr
+  for (let i = leaves.length - 2; i >= 0; i--) {
+    expr = {
+      kind: 'conditional',
+      test: { kind: 'binary', op: '===', left: locale, right: strLit(members[i]) },
+      consequent: leaves[i],
+      alternate: expr,
+    }
+  }
+  return expr
+}
+
 export function matchToLocaleDateStringCall(
   callee: ParsedExpr,
   args: readonly ParsedExpr[],
@@ -139,13 +452,25 @@ export function matchToLocaleDateStringCall(
   if (callee.kind !== 'member' || callee.computed) return null
   if (callee.property !== 'toLocaleDateString' || args.length !== 2) return null
   const [locale, options] = args
-  if (locale.kind !== 'literal' || locale.literalType !== 'string') return null
-  if (options.kind !== 'object-literal' || options.properties.length !== 1) return null
-  const prop = options.properties[0]
-  if (prop.key !== 'timeZone') return null
-  if (prop.value.kind !== 'literal' || prop.value.literalType !== 'string') return null
-  const tz = String(prop.value.value)
-  if (!TO_LOCALE_TZ_RE.test(tz)) return null
+  // Options bag: `timeZone` is REQUIRED (a literal 'UTC' | valid ±HH:MM —
+  // its omission would read the host timezone); every OTHER key rides into
+  // the Intl probe as-is when its value is a string literal (#2334's
+  // fidelity rule: admit any literal options bag the probe can reproduce
+  // exactly, decline everything else — dateStyle, month/weekday forms, …).
+  if (options.kind !== 'object-literal') return null
+  let tz: string | null = null
+  const probeOptions: Record<string, string> = {}
+  for (const prop of options.properties) {
+    if (prop.value.kind !== 'literal' || prop.value.literalType !== 'string') return null
+    const value = String(prop.value.value)
+    if (prop.key === 'timeZone') {
+      if (!TO_LOCALE_TZ_RE.test(value)) return null
+      tz = value
+    } else {
+      probeOptions[prop.key] = value
+    }
+  }
+  if (tz === null) return null
 
   const receiverType = resolveReceiverType(callee.object, metadata, new Map())
   if (!receiverType || receiverType.kind !== 'interface') return null
@@ -153,19 +478,82 @@ export function matchToLocaleDateStringCall(
   if (typeName !== 'Date') return null
   if (metadata.typeDefinitions.some((d) => d.name === typeName)) return null
 
-  const pattern = resolveLocaleDatePattern(String(locale.value))
-  if (pattern === null) return null
+  // Literal locale: resolve one pattern (+ name table when the probed
+  // format contains month/weekday names) at build time.
+  if (locale.kind === 'literal' && locale.literalType === 'string') {
+    const format = resolveLocaleDateFormat(String(locale.value), probeOptions)
+    if (format === null) return null
+    return {
+      kind: 'helper-call',
+      helper: 'format_date',
+      args: [callee.object, strLit(format.pattern), strLit(tz), strArr(format.names ?? [])],
+    }
+  }
+
+  // Union-typed locale (#2324's union stage): a REQUIRED prop typed as a
+  // closed string-literal union resolves every member's format at build
+  // time; the pattern AND names arguments each lower to a right-folded
+  // ternary over the runtime locale value — runtime locale switching with
+  // zero runtime CLDR.
+  const members = resolveLocaleUnionMembers(locale, metadata)
+  if (!members) return null
+  const formats: LocaleDateFormat[] = []
+  for (const member of members) {
+    const format = resolveLocaleDateFormat(member, probeOptions)
+    if (format === null) return null
+    formats.push(format)
+  }
+  const patterns = formats.map((f) => f.pattern)
+  const nameTables = formats.map((f) => JSON.stringify(f.names ?? []))
   return {
     kind: 'helper-call',
     helper: 'format_date',
     args: [
       callee.object,
-      { kind: 'literal', value: pattern, literalType: 'string' },
-      { kind: 'literal', value: tz, literalType: 'string' },
+      foldMembers(locale, members, patterns.map(strLit), new Set(patterns).size === 1),
+      strLit(tz),
+      foldMembers(
+        locale,
+        members,
+        formats.map((f) => strArr(f.names ?? [])),
+        new Set(nameTables).size === 1,
+      ),
     ],
   }
 }
 
+/**
+ * Render a matched node's helper argument — the pattern (`strLit` leaf) or
+ * the #2334 names table (`strArr` leaf), either possibly wrapped in
+ * `foldMembers`' right-folded ternary — as client-JS text for the
+ * #2292-style rewrite sites (`jsx-to-ir.ts` / `emit-reactive.ts`). Leaves
+ * stringify directly; a fold re-serializes its tests against `localeText` —
+ * the rewrite site's own source text for the locale argument, so downstream
+ * prop-prefix rewrites treat it like any other reference. Returns null for
+ * any shape this module didn't build (the caller then leaves the expression
+ * raw rather than guessing).
+ */
+export function foldedArgToClientJs(arg: ParsedExpr, localeText: string): string | null {
+  if (arg.kind === 'literal') return JSON.stringify(arg.value)
+  if (arg.kind === 'array-literal') {
+    const values: string[] = []
+    for (const el of arg.elements) {
+      if (el.kind !== 'literal') return null
+      values.push(String(el.value))
+    }
+    return JSON.stringify(values)
+  }
+  if (arg.kind !== 'conditional') return null
+  const t = arg.test
+  if (t.kind !== 'binary' || t.op !== '===' || t.right.kind !== 'literal') return null
+  // Right-fold shape: the consequent must be a leaf (only alternates nest).
+  if (arg.consequent.kind !== 'literal' && arg.consequent.kind !== 'array-literal') return null
+  const cons = foldedArgToClientJs(arg.consequent, localeText)
+  const rest = foldedArgToClientJs(arg.alternate, localeText)
+  if (cons === null || rest === null) return null
+  return `${localeText} === ${JSON.stringify(t.right.value)} ? ${cons} : ${rest}`
+}
+
 export const toLocaleDatePlugin: LoweringPlugin = {
   name: 'toLocaleDateString',
   prepare(metadata) {

package/src/types.ts

@@ -1455,6 +1455,19 @@ export interface NamedExportSpecifier {
   isTypeOnly: boolean
 }
 
+/** One identifier occurrence in a factory body that call-site inlining may
+ *  rename (#2341 BUG-1). Offsets are relative to ReactiveFactoryInfo.bodySource. */
+export interface FactoryRenameSite {
+  name: string
+  start: number
+  end: number
+  /** 'shorthand' = the identifier is simultaneously a property key and a
+   *  value/binding reference ({ name } literal, or { name } object-pattern
+   *  element). Renaming it must EXPAND to `name: <replacement>` to preserve
+   *  the key. 'plain' = ordinary reference or declaration name. */
+  form: 'plain' | 'shorthand'
+}
+
 /**
  * Reactive factory helper metadata (#931). Collected when a same-file
  * function matches the factory shape: exactly one top-level `return` whose
@@ -1492,16 +1505,49 @@ export interface ReactiveFactoryInfo {
    * (local factories win), not by consulting this field.
    */
   sourceFilePath?: string
+  /**
+   * Imports to re-provision into the component file when this cross-file
+   * factory is inlined (#2332). Absent/empty for same-file factories and
+   * for factories whose body references no helper-file import. Entries
+   * already satisfied by an identical top-level import in the component
+   * file are dropped at prescan time.
+   */
+  requiredImports?: RequiredFactoryImport[]
+  /**
+   * Identifier occurrences within `bodySource` that call-site inlining may
+   * rename (#2341 BUG-1) — collected by the same AST walk that produces
+   * `bodySource`, so offsets stay in lockstep with the serialized text.
+   * Same-file and cross-file factories both get this (both flow through
+   * `detectReactiveFactory`).
+   */
+  renameSites: FactoryRenameSite[]
+}
+
+/**
+ * An import the helper file holds that an inlined factory body references
+ * (#2332). Not a BF112 capture: the component file can import the same
+ * binding itself. Collected at prescan with the specifier ALREADY rewritten
+ * relative to the component file (or unchanged for bare/npm specifiers);
+ * the source rewriter injects one deduped import statement per specifier.
+ */
+export interface RequiredFactoryImport {
+  /** Local binding name as referenced inside the factory body. */
+  localName: string
+  /** Name exported by the target module (`import { exportedName as localName }`). */
+  exportedName: string
+  /** Component-file-relative specifier (`../lib/mathmod`), or the unchanged bare specifier. */
+  specifier: string
 }
 
 /**
  * A helper that was recognized as a would-be reactive factory but declined
  * for inlining (#2325). Recorded so validateReactiveFactoryCalls can emit
- * the specific diagnostic (BF111 rename / BF112 module-scope capture) at
- * the call site instead of the generic BF110.
+ * the specific diagnostic (BF111 rename / BF112 module-scope capture /
+ * BF113 re-provisioned-import name collision) at the call site instead of
+ * the generic BF110.
  */
 export interface DeclinedReactiveFactory {
-  code: 'BF111' | 'BF112'
+  code: 'BF111' | 'BF112' | 'BF113' | 'BF114'
   /** Detail spliced into the call-site message (e.g. offending identifier list). */
   detail: string
   /** Definition site (in the helper file for cross-file declines). */