@barefootjs/jsx 0.21.4 → 0.24.1

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,9 @@ export const ErrorCodes = {
 
   // Reactive factory errors (BF110-BF119)
   UNRECOGNIZED_REACTIVE_FACTORY: 'BF110',
+  REACTIVE_FACTORY_RENAME_UNSUPPORTED: 'BF111',
+  REACTIVE_FACTORY_MODULE_CAPTURE: 'BF112',
+  REACTIVE_FACTORY_IMPORT_COLLISION: 'BF113',
 } as const
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]
@@ -165,6 +168,22 @@ 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.',
+
+  [ErrorCodes.REACTIVE_FACTORY_IMPORT_COLLISION]:
+    'Inlining an imported reactive factory requires re-importing one of its helper ' +
+    'imports into this file, but that name is already bound here to something else. ' +
+    "Rename the conflicting binding in this file, or alias the import in the factory's own file.",
 }
 
 // =============================================================================

package/src/format-date-lowering.ts

@@ -0,0 +1,55 @@
+/**
+ * `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' }
+const EMPTY_NAMES: ParsedExpr = { kind: 'array-literal', elements: [], raw: '[]' } as ParsedExpr
+
+/**
+ * Recognise `formatDate(date, pattern[, timeZone[, names]])` 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–4. The canonical helper arity is 4 (#2334): omitted `timeZone` /
+ * `names` normalize to the `'UTC'` literal and the empty table the client
+ * function defaults to, so backend helpers stay fixed-arity.
+ */
+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 > 4) return null
+  return {
+    kind: 'helper-call',
+    helper: 'format_date',
+    args: [args[0], args[1], args[2] ?? UTC_LITERAL, args[3] ?? EMPTY_NAMES],
+  }
+}
+
+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, foldedArgToClientJs } from '../to-locale-date-lowering.ts'
 import { tsNodeToParsedExpr } from '../expression-parser.ts'
 import type { LoweringMatcher } from '../lowering-registry.ts'
 
@@ -122,6 +123,90 @@ 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, namesArg] = node.args
+    if (!patternArg || tzArg?.kind !== 'literal') continue
+    const localeText = call.arguments[0].getText(sourceFile)
+    const patternJs = foldedArgToClientJs(patternArg, localeText)
+    if (patternJs === null) continue
+    // The names table (#2334) — omitted when empty, same as the static path.
+    let namesJs: string | null = null
+    if (namesArg && !(namesArg.kind === 'array-literal' && namesArg.elements.length === 0)) {
+      namesJs = foldedArgToClientJs(namesArg, localeText)
+      if (namesJs === null) 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}, ${patternJs}, ${JSON.stringify(tzArg.value)}${namesJs !== null ? `, ${namesJs}` : ''})`,
+    )
+  }
+  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 +282,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 +294,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, foldedArgToClientJs } 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,74 @@ 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, namesArg] = node.args
+    if (!patternArg || tzArg?.kind !== 'literal') continue
+    const localeText = ctx.getJS(call.arguments[0])
+    const patternJs = foldedArgToClientJs(patternArg, localeText)
+    if (patternJs === null) continue
+    // The names table (#2334) — omitted from the client call when empty
+    // (the client function defaults to []).
+    let namesJs: string | null = null
+    if (namesArg && !(namesArg.kind === 'array-literal' && namesArg.elements.length === 0)) {
+      namesJs = foldedArgToClientJs(namesArg, localeText)
+      if (namesJs === null) 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}, ${patternJs}, ${JSON.stringify(tzArg.value)}${namesJs !== null ? `, ${namesJs}` : ''})`,
+    )
+  }
+  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 +504,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,
     },
   })
 }