@barefootjs/jsx 0.21.3 → 0.23.0

package/src/builtin-lowering-plugins.ts

@@ -17,6 +17,8 @@ import { registerLoweringPlugin } from './lowering-registry.ts'
 import { queryHrefLocalNames } from './adapters/env-signal.ts'
 import { matchQueryHrefCall } from './query-href-lowering.ts'
 import { datePlugin } from './date-lowering.ts'
+import { formatDatePlugin } from './format-date-lowering.ts'
+import { toLocaleDatePlugin } from './to-locale-date-lowering.ts'
 
 /**
  * `queryHref(base, { … })` — the pure URL-query builder (#2042). Its runtime
@@ -42,7 +44,12 @@ export const queryHrefPlugin: LoweringPlugin = {
 }
 
 /** Every plugin the compiler ships and applies by default. */
-export const BUILTIN_LOWERING_PLUGINS: readonly LoweringPlugin[] = [queryHrefPlugin, datePlugin]
+export const BUILTIN_LOWERING_PLUGINS: readonly LoweringPlugin[] = [
+  queryHrefPlugin,
+  datePlugin,
+  formatDatePlugin,
+  toLocaleDatePlugin,
+]
 
 /**
  * Register the built-in plugins into the shared registry. Called for its side

package/src/date-lowering.ts

@@ -62,7 +62,7 @@ const EMPTY_BINDINGS: Bindings = new Map()
  * properties of the SAME named type aren't short-circuited against each
  * other.
  */
-function typeReachesDate(type: TypeInfo | null, meta: IRMetadata, seen: Set<string>): boolean {
+export function typeReachesDate(type: TypeInfo | null, meta: IRMetadata, seen: Set<string>): boolean {
   const stripped = stripUnion(type)
   if (!stripped) return false
   // `kind: 'object'` is an INLINE type literal (`{ createdAt: Date }` — the

package/src/errors.ts

@@ -87,6 +87,8 @@ export const ErrorCodes = {
 
   // Reactive factory errors (BF110-BF119)
   UNRECOGNIZED_REACTIVE_FACTORY: 'BF110',
+  REACTIVE_FACTORY_RENAME_UNSUPPORTED: 'BF111',
+  REACTIVE_FACTORY_MODULE_CAPTURE: 'BF112',
 } as const
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]
@@ -165,6 +167,17 @@ const errorMessages: Record<ErrorCode, string> = {
 
   [ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY]:
     'Tuple destructuring of a non-reactive factory call. The compiler only recognizes createSignal / createMemo calls and same-file helpers that wrap them with a single `return [a, b]` exit.',
+
+  [ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED]:
+    'Reactive factory object return/destructure must use shorthand properties only. ' +
+    'Property renames (`{ lists: myLists }`), defaults, and rest elements are not ' +
+    'supported — destructure with the factory\'s own property names.',
+
+  [ErrorCodes.REACTIVE_FACTORY_MODULE_CAPTURE]:
+    'Imported reactive factory references bindings from its own module scope, so its ' +
+    'body cannot be inlined into the component file. Move those helpers into the ' +
+    'component file, pass them to the factory as parameters, or define the factory ' +
+    'in the component file.',
 }
 
 // =============================================================================

package/src/format-date-lowering.ts

@@ -0,0 +1,51 @@
+/**
+ * `formatDate` lowering plugin (#2324) — the pure-function date formatter
+ * (`packages/client/src/format-date.ts`). A call to the `formatDate` binding
+ * imported from `@barefootjs/client` lowers to a backend-neutral
+ * `helper-call` on the `format_date` helper (spec/template-helpers.md), which
+ * every adapter renders through its generic helper-call path (#2069) — no
+ * adapter-specific recognition code, only the runtime helper each backend
+ * ships.
+ *
+ * The canonical helper arity is 3: a two-arg call site
+ * (`formatDate(d, 'YYYY/M/D')`) is normalized here by supplying the
+ * `'UTC'` literal the client function defaults to, so backend helpers stay
+ * fixed-arity. Unlike the `date` plugin there is no receiver-type gate —
+ * `formatDate` is recognised by its import binding (like `queryHref`), and
+ * its own receiver contract (native date / ISO string / nil → `''`) is total,
+ * so any argument expression the adapter can evaluate is admissible.
+ */
+
+import type { ParsedExpr } from './expression-parser.ts'
+import type { LoweringNode, LoweringPlugin } from './lowering-registry.ts'
+import { formatDateLocalNames } from './adapters/env-signal.ts'
+
+const UTC_LITERAL: ParsedExpr = { kind: 'literal', value: 'UTC', literalType: 'string' }
+
+/**
+ * Recognise `formatDate(date, pattern[, timeZone])` against the component's
+ * local import bindings, or decline (null): a non-identifier callee, a name
+ * not bound to the `@barefootjs/client` import, or an arity outside 2–3.
+ */
+export function matchFormatDateCall(
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+  locals: ReadonlySet<string>,
+): LoweringNode | null {
+  if (callee.kind !== 'identifier' || !locals.has(callee.name)) return null
+  if (args.length < 2 || args.length > 3) return null
+  return {
+    kind: 'helper-call',
+    helper: 'format_date',
+    args: [args[0], args[1], args[2] ?? UTC_LITERAL],
+  }
+}
+
+export const formatDatePlugin: LoweringPlugin = {
+  name: 'formatDate',
+  prepare(metadata) {
+    const locals = formatDateLocalNames(metadata)
+    if (locals.size === 0) return null
+    return (callee, args) => matchFormatDateCall(callee, args, locals)
+  },
+}

package/src/index.ts

@@ -91,7 +91,7 @@ export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, Lit
 export { collectLoopBoundNames } from './adapters/loop-bound-names.ts'
 export { evaluateSignalInit, tryEvaluateSignalInit, type SignalInitEvalResult } from './signal-init-eval.ts'
 export { evaluateStaticLiteral, isFullyStaticLiteral, resolveStaticLoopSource } from './static-literal.ts'
-export { importsSearchParams, searchParamsLocalNames, envSignalLocalNames, envSignalReaderFor, ENV_SIGNAL_READERS, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export { importsSearchParams, searchParamsLocalNames, envSignalLocalNames, envSignalReaderFor, ENV_SIGNAL_READERS, queryHrefLocalNames, formatDateLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
 export type { EnvSignalReader } from './adapters/env-signal.ts'
 export { matchQueryHrefCall, queryHrefArgs, type QueryHrefCall, type QueryHrefTriple } from './query-href-lowering.ts'
 export {

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

@@ -11,6 +11,7 @@ import type { ClientJsContext } from './types.ts'
 import { toHtmlAttrName, varSlotId, PROPS_PARAM } from './utils.ts'
 import { createTemplateAwareStringProtector } from './html-template.ts'
 import { datePlugin, DATE_METHODS } from '../date-lowering.ts'
+import { toLocaleDatePlugin } from '../to-locale-date-lowering.ts'
 import { tsNodeToParsedExpr } from '../expression-parser.ts'
 import type { LoweringMatcher } from '../lowering-registry.ts'
 
@@ -122,6 +123,80 @@ function getReactiveDateLoweringMatcher(ctx: ClientJsContext): LoweringMatcher |
   return datePlugin.prepare(metadataSlice as unknown as IRMetadata)
 }
 
+/** `getReactiveDateLoweringMatcher`'s twin for `toLocaleDatePlugin` (#2324 slice 2). */
+function getReactiveToLocaleMatcher(ctx: ClientJsContext): LoweringMatcher | null {
+  if (!ctx.propsType) return null
+  const metadataSlice: Pick<IRMetadata, 'propsType' | 'propsObjectName' | 'propsParams' | 'typeDefinitions'> = {
+    propsType: ctx.propsType,
+    propsObjectName: ctx.propsObjectName,
+    propsParams: ctx.propsParams,
+    typeDefinitions: ctx.typeDefinitions ?? [],
+  }
+  return toLocaleDatePlugin.prepare(metadataSlice as unknown as IRMetadata)
+}
+
+/**
+ * Reactive-path counterpart to `jsx-to-ir.ts`'s `lowerToLocaleDateCalls`
+ * (#2324 slice 2): rewrite a literal-locale `toLocaleDateString` call the
+ * SAME `toLocaleDatePlugin` matcher claims to `formatDate(recv, pattern,
+ * tz)` with the build-time-frozen pattern, for the same two reasons as the
+ * `date` rewrite above — the hydrated prop is an ISO STRING (a raw
+ * `.toLocaleDateString()` on it throws), and the client must render the
+ * frozen pattern, not the browser's own ICU output.
+ */
+function lowerToLocaleCallsInReactiveExpr(expr: string, matcher: LoweringMatcher | null): string {
+  if (!matcher) return expr
+  let sourceFile: ts.SourceFile
+  try {
+    sourceFile = ts.createSourceFile('__reactive_expr__.ts', `(${expr});`, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  } catch {
+    return expr
+  }
+  const stmt = sourceFile.statements[0]
+  if (!stmt || !ts.isExpressionStatement(stmt)) return expr
+  const root = ts.isParenthesizedExpression(stmt.expression) ? stmt.expression.expression : stmt.expression
+
+  const candidates: ts.CallExpression[] = []
+  const visit = (n: ts.Node): void => {
+    if (
+      ts.isCallExpression(n) &&
+      n.arguments.length === 2 &&
+      ts.isPropertyAccessExpression(n.expression) &&
+      !n.expression.questionDotToken &&
+      n.expression.name.text === 'toLocaleDateString'
+    ) {
+      candidates.push(n)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(root)
+  if (candidates.length === 0) return expr
+
+  const { protect, restore, replaceProtectedCall } = createTemplateAwareStringProtector()
+  let result = protect(expr)
+  for (const call of candidates) {
+    const propAccess = call.expression as ts.PropertyAccessExpression
+    const node = matcher(
+      tsNodeToParsedExpr(propAccess),
+      call.arguments.map((a) => tsNodeToParsedExpr(a)),
+    )
+    if (!node || node.kind !== 'helper-call' || node.helper !== 'format_date') continue
+    const [, patternArg, tzArg] = node.args
+    if (patternArg?.kind !== 'literal' || tzArg?.kind !== 'literal') continue
+    const receiverText = propAccess.expression.getText(sourceFile)
+    const matchText = call.getText(sourceFile)
+    // The call text contains string literals (placeholders in the protected
+    // haystack) — go through the protector's stash-verified matcher, same
+    // as the static-path rewrite in jsx-to-ir.ts.
+    result = replaceProtectedCall(
+      result,
+      matchText,
+      () => `formatDate(${receiverText}, ${JSON.stringify(patternArg.value)}, ${JSON.stringify(tzArg.value)})`,
+    )
+  }
+  return restore(result)
+}
+
 /**
  * Reactive-path counterpart to `jsx-to-ir.ts`'s `lowerDateCalls` (#2292):
  * without this, a Date-typed prop's catalogued accessor call re-evaluated
@@ -197,6 +272,7 @@ function lowerDateCallsInReactiveExpr(expr: string, matcher: LoweringMatcher | n
 /** Emit createEffect blocks that update text nodes for reactive expressions. */
 export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): void {
   const dateLoweringMatcher = getReactiveDateLoweringMatcher(ctx)
+  const toLocaleMatcher = getReactiveToLocaleMatcher(ctx)
   // Group elements by expression to consolidate effects with same dependencies
   const byExpression = new Map<string, typeof ctx.dynamicElements>()
   for (const elem of ctx.dynamicElements) {
@@ -208,7 +284,10 @@ export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): v
   }
 
   for (const [rawExpr, elems] of byExpression) {
-    const expr = lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher)
+    const expr = lowerToLocaleCallsInReactiveExpr(
+      lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher),
+      toLocaleMatcher,
+    )
     // Separate conditional vs non-conditional elements
     const conditionalElems = elems.filter(e => e.insideConditional)
     const normalElems = elems.filter(e => !e.insideConditional)

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

@@ -75,21 +75,55 @@ export function splitTemplateInterpolations(inner: string): string[] {
 export function createTemplateAwareStringProtector(): {
   protect: (s: string) => string
   restore: (s: string) => string
+  replaceProtectedCall: (haystack: string, needle: string, replacement: () => string) => string
 } {
   const stash: string[] = []
   const save = (s: string) => { const i = stash.length; stash.push(s); return `__STRLIT_${i}__` }
+  const STRING_LIT_RE = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g
   const protect = (s: string): string => {
     s = s.replace(/`([^`]*)`/g, (_full, inner: string) => {
       const parts = splitTemplateInterpolations(inner)
       return '`' + parts.map(p => p.startsWith('${') ? p : save(p)).join('') + '`'
     })
-    s = s.replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g, m => save(m))
+    s = s.replace(STRING_LIT_RE, m => save(m))
     return s
   }
   const restore = (s: string): string => {
     return s.replace(/__STRLIT_(\d+)__/g, (_, i) => stash[Number(i)])
   }
-  return { protect, restore }
+  /**
+   * Replace one occurrence of `needle` (raw source text that may CONTAIN
+   * string literals, e.g. a `toLocaleDateString('en-US', { timeZone:
+   * 'UTC' })` call) inside an already-`protect`ed `haystack`. A plain
+   * `.replace(needle, …)` can't work there: the haystack's literals are
+   * `__STRLIT_i__` placeholders while the needle still carries quotes. The
+   * needle's literal segments become placeholder wildcards, and each
+   * candidate occurrence is verified against the stash CONTENT — so two
+   * same-shaped calls differing only in their literals (two locales in one
+   * expression) can't be cross-replaced, and a protected template-literal
+   * static segment (stashed wholesale) can never match (#2294's hazard
+   * class). Replaces the first verified occurrence only.
+   */
+  const replaceProtectedCall = (haystack: string, needle: string, replacement: () => string): string => {
+    const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const litValues: string[] = []
+    let pattern = ''
+    let last = 0
+    for (const m of needle.matchAll(STRING_LIT_RE)) {
+      pattern += escape(needle.slice(last, m.index))
+      pattern += '__STRLIT_(\\d+)__'
+      litValues.push(m[0])
+      last = m.index + m[0].length
+    }
+    pattern += escape(needle.slice(last))
+    for (const m of haystack.matchAll(new RegExp(pattern, 'g'))) {
+      const verified = m.slice(1).every((idx, i) => stash[Number(idx)] === litValues[i])
+      if (!verified) continue
+      return haystack.slice(0, m.index) + replacement() + haystack.slice(m.index + m[0].length)
+    }
+    return haystack
+  }
+  return { protect, restore, replaceProtectedCall }
 }
 
 const VOID_ELEMENTS = new Set([

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

@@ -21,6 +21,10 @@ export const RUNTIME_IMPORT_CANDIDATES = [
   // every SSR adapter's `date` runtime helper (`date-lowering.ts`'s
   // `datePlugin`).
   'date',
+  // Literal-locale `toLocaleDateString` sugar (#2324 slice 2) — the client
+  // rewrite targets `formatDate(recv, pattern, tz)`, so the emitted code
+  // needs the runtime export when the component didn't import it itself.
+  'formatDate',
 ] as const
 
 /** @deprecated Use RUNTIME_IMPORT_CANDIDATES */

package/src/jsx-to-ir.ts

@@ -49,6 +49,7 @@ import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironme
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template.ts'
 import { datePlugin, DATE_METHODS } from './date-lowering.ts'
+import { toLocaleDatePlugin } from './to-locale-date-lowering.ts'
 import type { LoweringMatcher } from './lowering-registry.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
@@ -175,6 +176,11 @@ interface TransformContext {
    * own `prepare` gate). See `getDateLoweringMatcher`.
    */
   _dateLoweringMatcher?: LoweringMatcher | null
+  /**
+   * Cached `toLocaleDatePlugin` matcher (#2324 slice 2), same lifecycle as
+   * `_dateLoweringMatcher`. See `getToLocaleDateLoweringMatcher`.
+   */
+  _toLocaleDateLoweringMatcher?: LoweringMatcher | null
 }
 
 /**
@@ -326,6 +332,21 @@ function getDateLoweringMatcher(ctx: TransformContext): LoweringMatcher | null {
   return ctx._dateLoweringMatcher
 }
 
+/** `getDateLoweringMatcher`'s twin for `toLocaleDatePlugin` (#2324 slice 2) — same metadata slice, same cache lifecycle. */
+function getToLocaleDateLoweringMatcher(ctx: TransformContext): LoweringMatcher | null {
+  if (ctx._toLocaleDateLoweringMatcher === undefined) {
+    const a = ctx.analyzer
+    const metadataSlice: Pick<IRMetadata, 'propsType' | 'propsObjectName' | 'propsParams' | 'typeDefinitions'> = {
+      propsType: a.propsType,
+      propsObjectName: a.propsObjectName,
+      propsParams: a.propsParams,
+      typeDefinitions: a.typeDefinitions,
+    }
+    ctx._toLocaleDateLoweringMatcher = toLocaleDatePlugin.prepare(metadataSlice as unknown as IRMetadata)
+  }
+  return ctx._toLocaleDateLoweringMatcher
+}
+
 /**
  * Client-side counterpart to `datePlugin` (#2274 was SSR-only; #2292
  * closes the gap). The client emitter (`ir-to-client-js/`) emits raw,
@@ -401,6 +422,63 @@ function lowerDateCalls(text: string, expr: ts.Node, ctx: TransformContext): str
   return restore(result)
 }
 
+/**
+ * `lowerDateCalls`' twin for the literal-locale `toLocaleDateString` sugar
+ * (#2324 slice 2). A call the SAME `toLocaleDatePlugin` matcher claims (so
+ * client and SSR lower under identical evidence, mandatory per #2292)
+ * rewrites to `formatDate(recv, "<pattern>", "<tz>")` — the pattern and tz
+ * literals come off the matched helper-call node, so the client renders the
+ * exact build-time-frozen pattern the templates render, and the ISO-string
+ * prop value the client actually holds post-hydration (no type-aware JSON
+ * revival) flows through `formatDate`'s string-receiver normalization
+ * instead of throwing on a raw `.toLocaleDateString()` string call.
+ */
+function lowerToLocaleDateCalls(text: string, expr: ts.Node, ctx: TransformContext): string {
+  const matcher = getToLocaleDateLoweringMatcher(ctx)
+  if (!matcher) return text
+
+  const candidates: ts.CallExpression[] = []
+  function visit(n: ts.Node) {
+    if (
+      ts.isCallExpression(n) &&
+      n.arguments.length === 2 &&
+      ts.isPropertyAccessExpression(n.expression) &&
+      !n.expression.questionDotToken &&
+      n.expression.name.text === 'toLocaleDateString'
+    ) {
+      candidates.push(n)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(expr)
+  if (candidates.length === 0) return text
+
+  const { protect, restore, replaceProtectedCall } = createTemplateAwareStringProtector()
+  let result = protect(text)
+  for (const call of candidates) {
+    const propAccess = call.expression as ts.PropertyAccessExpression
+    const node = matcher(
+      tsNodeToParsedExpr(propAccess),
+      call.arguments.map((a) => tsNodeToParsedExpr(a)),
+    )
+    if (!node || node.kind !== 'helper-call' || node.helper !== 'format_date') continue
+    const [, patternArg, tzArg] = node.args
+    if (patternArg?.kind !== 'literal' || tzArg?.kind !== 'literal') continue
+    const receiverText = ctx.getJS(propAccess.expression)
+    const matchText = ctx.getJS(call)
+    // Unlike `lowerDateCalls`' zero-arg needle, this call text CONTAINS
+    // string literals, which the protected haystack holds as placeholders —
+    // so the replacement must go through the protector's stash-verified
+    // matcher rather than a plain `.replace`.
+    result = replaceProtectedCall(
+      result,
+      matchText,
+      () => `formatDate(${receiverText}, ${JSON.stringify(patternArg.value)}, ${JSON.stringify(tzArg.value)})`,
+    )
+  }
+  return restore(result)
+}
+
 /**
  * Rewrite bare destructured prop references in expression text.
  * Thin wrapper that caches prop names on ctx and delegates to the shared core.
@@ -415,7 +493,7 @@ function rewriteBarePropRefs(text: string, expr: ts.Node, ctx: TransformContext)
   // unconditionally — ahead of the `propNames` gate — because Date
   // evidence comes from `ctx.analyzer.propsType`, independent of whether
   // this component destructures its props.
-  const dateLowered = lowerDateCalls(text, expr, ctx)
+  const dateLowered = lowerToLocaleDateCalls(lowerDateCalls(text, expr, ctx), expr, ctx)
   let propNames = getDestructuredPropNames(ctx)
   if (!propNames) return dateLowered === text ? undefined : dateLowered
   // #2222: a name bound as an enclosing loop callback's item/index param

package/src/rich-type-refusal.ts

@@ -96,13 +96,21 @@ function pushDiagnostic(
   if (seen.has(key)) return
   seen.add(key)
   const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`
+  // `toLocaleDateString` has a catalogued explicit-input form (#2324 slice
+  // 2) — point the fix at it instead of the generic escape hatches alone.
+  // The implicit-environment forms (zero-arg, locale-only, non-literal
+  // locale, IANA timeZone) stay refused by design.
+  const suggestion =
+    method === 'toLocaleDateString' && typeName === 'Date'
+      ? "Pass a literal locale and an explicit literal timeZone — .toLocaleDateString('ja-JP', { timeZone: 'UTC' }) (or a fixed '±HH:MM' offset) — to compile it to the format_date helper; for a runtime locale, resolve the pattern in your i18n layer and use formatDate(date, pattern, tz) from @barefootjs/client. Alternatively add /* @client */ or pre-compute server-side."
+      : 'Add /* @client */ to evaluate this expression on the client only, or pre-compute the value server-side.'
   errors.push({
     code: ErrorCodes.UNSUPPORTED_JSX_PATTERN,
     severity: 'error',
     message: `Expression cannot be compiled to marked template: method '.${method}()' on ${receiver} of host type '${typeName}' has no catalogued lowering.`,
     loc,
     suggestion: {
-      message: 'Add /* @client */ to evaluate this expression on the client only, or pre-compute the value server-side.',
+      message: suggestion,
     },
   })
 }

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

@@ -0,0 +1,175 @@
+/**
+ * Literal-locale `toLocaleDateString` lowering plugin (#2324 slice 2 — the
+ * "upper layer" sugar over the `format_date` primitive).
+ *
+ * `createdAt.toLocaleDateString('ja-JP', { timeZone: 'UTC' })` on a
+ * `Date`-typed prop, with a **compile-time literal** locale and an explicit
+ * literal `timeZone`, resolves the locale's default date pattern ONCE at
+ * build time (via the build machine's own `Intl.DateTimeFormat`) and lowers
+ * to the exact same backend-neutral `helper-call` on `format_date` that
+ * `formatDate(date, pattern, tz)` produces. Consequences:
+ *
+ *   - no runtime ICU/CLDR on any backend — the CLDR lookup happens once, in
+ *     the compiler;
+ *   - SSR and (rewritten) client JS render from the same frozen pattern, so
+ *     output is byte-identical by construction;
+ *   - no locale allowlist: any locale whose default date format the
+ *     structural gate below can prove representable in the v1 token set is
+ *     admitted, and every other shape declines (→ BF021 via
+ *     `rich-type-refusal.ts`, whose gate exempts exactly what a registered
+ *     plugin claims).
+ *
+ * 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 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).
+ */
+
+import type { IRMetadata } 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'
+import { typeReachesDate } from './date-lowering.ts'
+
+/**
+ * `timeZone` literals the lowering admits: `'UTC'` or a fixed `±HH:MM`
+ * offset **within ECMA-402's valid offset range** (hours 00–23, minutes
+ * 00–59). An out-of-range shape like `'+25:00'` or `'+99:99'` must DECLINE
+ * (→ BF021), not lower: real `toLocaleDateString` throws a RangeError on
+ * it, so compiling it would render a nonsense offset on the template
+ * adapters while the JS-native path (Hono, and the pre-rewrite semantics
+ * the sugar stands in for) crashes — the exact divergence the sugar exists
+ * to rule out.
+ */
+export const TO_LOCALE_TZ_RE = /^(?:UTC|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/
+
+/**
+ * Probe instant for pattern derivation: 2001-02-03 UTC. Month and day are
+ * distinct single-digit values, so the rendered part text distinguishes both
+ * the field order (`M/D` vs `D.M`) and zero-padding (`02` → `MM`, `2` → `M`).
+ */
+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>()
+
+/**
+ * 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.
+ */
+export function resolveLocaleDatePattern(locale: string): string | null {
+  const cached = patternCache.get(locale)
+  if (cached !== undefined) return cached
+  const derived = derivePattern(locale)
+  patternCache.set(locale, derived)
+  return derived
+}
+
+function derivePattern(locale: string): string | null {
+  let parts: Intl.DateTimeFormatPart[]
+  try {
+    const dtf = new Intl.DateTimeFormat(locale, { 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
+  }
+  let pattern = ''
+  for (const part of parts) {
+    switch (part.type) {
+      case 'year':
+        if (part.value !== '2001') return null // 2-digit-year default has no v1 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
+        break
+      case 'day':
+        if (part.value === '3') pattern += 'D'
+        else if (part.value === '03') pattern += 'DD'
+        else return null
+        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
+        pattern += part.value
+        break
+      default:
+        return null // era, weekday, dayPeriod, … — not representable
+    }
+  }
+  if (!pattern.includes('YYYY') || !/M/.test(pattern) || !/D/.test(pattern)) return null
+  return pattern
+}
+
+/**
+ * Recognise `<Date-typed prop>.toLocaleDateString(<locale literal>,
+ * { timeZone: <'UTC' | '±HH:MM' literal> })` per the module doc and return
+ * the `format_date` helper-call with the build-time-resolved pattern, or
+ * decline (null) for every other shape. Receiver evidence mirrors
+ * `date-lowering.ts`'s `matchDateCall` exactly (prop-rooted, `Date`-typed,
+ * no in-file type shadow, `EMPTY_BINDINGS`).
+ */
+export function matchToLocaleDateStringCall(
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+  metadata: IRMetadata,
+): LoweringNode | null {
+  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
+
+  const receiverType = resolveReceiverType(callee.object, metadata, new Map())
+  if (!receiverType || receiverType.kind !== 'interface') return null
+  const typeName = baseTypeName(receiverType.raw)
+  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
+  return {
+    kind: 'helper-call',
+    helper: 'format_date',
+    args: [
+      callee.object,
+      { kind: 'literal', value: pattern, literalType: 'string' },
+      { kind: 'literal', value: tz, literalType: 'string' },
+    ],
+  }
+}
+
+export const toLocaleDatePlugin: LoweringPlugin = {
+  name: 'toLocaleDateString',
+  prepare(metadata) {
+    if (!metadata.propsType || !typeReachesDate(metadata.propsType, metadata, new Set())) return null
+    return (callee, args) => matchToLocaleDateStringCall(callee, args, metadata)
+  },
+}

package/src/types.ts

@@ -1474,8 +1474,10 @@ export interface ReactiveFactoryInfo {
    * return tuple removed. Identifiers are renamed at the call site.
    */
   bodySource: string
-  /** Identifier names inside the returned array literal, in order. */
+  /** Ordered return binding names (tuple elements or object shorthand property names). */
   returnTupleIdentifiers: string[]
+  /** Return shape: `[a, b] as const` (tuple) or `{ a, b }` shorthand object (#2325). */
+  returnKind: 'tuple' | 'object'
   /**
    * Names declared anywhere in the factory body (local bindings). Used by
    * the call-site inliner to apply unique-suffix renaming and keep
@@ -1483,6 +1485,27 @@ export interface ReactiveFactoryInfo {
    */
   localBindings: string[]
   loc: SourceLocation
+  /**
+   * Absolute path of the defining file when the factory was resolved from a
+   * relative import (#2325). Undefined for same-file factories. Diagnostic
+   * detail only — name-collision precedence is enforced at merge time
+   * (local factories win), not by consulting this field.
+   */
+  sourceFilePath?: 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.
+ */
+export interface DeclinedReactiveFactory {
+  code: 'BF111' | 'BF112'
+  /** Detail spliced into the call-site message (e.g. offending identifier list). */
+  detail: string
+  /** Definition site (in the helper file for cross-file declines). */
+  loc: SourceLocation
 }
 
 export interface ImportSpecifier {