@barefootjs/jsx 0.21.4 → 0.24.1

package/dist/index.js

@@ -3141,18 +3141,39 @@ function createTemplateAwareStringProtector() {
     stash.push(s);
     return `__STRLIT_${i}__`;
   };
+  const STRING_LIT_RE = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g;
   const protect = (s) => {
     s = s.replace(/`([^`]*)`/g, (_full, inner) => {
       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) => {
     return s.replace(/__STRLIT_(\d+)__/g, (_, i) => stash[Number(i)]);
   };
-  return { protect, restore };
+  const replaceProtectedCall = (haystack, needle, replacement) => {
+    const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const litValues = [];
+    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 };
 }
 var VOID_ELEMENTS = new Set([
   "area",
@@ -4709,6 +4730,9 @@ function createAnalyzerContext(sourceFile, filePath) {
     jsxFunctions: new Map,
     jsxMultiReturnFunctions: new Map,
     reactiveFactories: new Map,
+    declinedReactiveFactories: new Map,
+    reactiveShapedHelpers: new Set,
+    cleanFactoryImports: new Set,
     signalTupleRefs: new Map,
     propsType: null,
     propsParams: [],
@@ -5217,7 +5241,10 @@ var ErrorCodes = {
   STAGE_INIT_LOCAL_IN_TEMPLATE: "BF061",
   STAGE_AWAIT_IN_TEMPLATE: "BF062",
   INLINE_JSX_CALLBACK_CAPTURE: "BF080",
-  UNRECOGNIZED_REACTIVE_FACTORY: "BF110"
+  UNRECOGNIZED_REACTIVE_FACTORY: "BF110",
+  REACTIVE_FACTORY_RENAME_UNSUPPORTED: "BF111",
+  REACTIVE_FACTORY_MODULE_CAPTURE: "BF112",
+  REACTIVE_FACTORY_IMPORT_COLLISION: "BF113"
 };
 var errorMessages = {
   [ErrorCodes.MISSING_USE_CLIENT]: "'use client' directive required for components with createSignal or event handlers",
@@ -5241,7 +5268,10 @@ var errorMessages = {
   [ErrorCodes.STAGE_INIT_LOCAL_IN_TEMPLATE]: "Init-scope local referenced from template scope. The template lambda runs at module scope (via render() / renderChild()) and cannot reach init-body locals. Wrap the JSX expression in /* @client */, or lift the value to a prop or module-scope const.",
   [ErrorCodes.STAGE_AWAIT_IN_TEMPLATE]: "AwaitExpression in template scope. The generated template and init functions are synchronous — a bare `await` produces a SyntaxError at parse time. Move the await into the component body (before the return) or into an onMount/effect callback, and pass the resolved value to JSX.",
   [ErrorCodes.INLINE_JSX_CALLBACK_CAPTURE]: "Inline JSX-returning arrow function captures a non-module identifier. Extract the callback into a top-level 'use client' component (e.g. `function MyNode(n) { return <div/> }` then `renderNode={MyNode}`) or pass captured values via component props.",
-  [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.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."
 };
 function createError(code, loc, options) {
   if (code === undefined || !(code in errorMessages)) {
@@ -5567,6 +5597,10 @@ function analyzeComponent(source, filePath, targetComponentName, program) {
   }
   const ctx = createAnalyzerContext(sourceFile, filePath);
   ctx.checker = checker;
+  ctx.reactiveFactories = prescan.factories;
+  ctx.declinedReactiveFactories = prescan.declined;
+  ctx.reactiveShapedHelpers = prescan.reactiveShaped;
+  ctx.cleanFactoryImports = prescan.cleanFactoryImports;
   const brandImportLoc = findBrandPackageImportLoc(sourceFile, filePath);
   if (!hadSharedProgram && brandImportLoc !== null) {
     ctx.errors.push(createError(ErrorCodes.SHARED_PROGRAM_REQUIRED, brandImportLoc));
@@ -6472,6 +6506,7 @@ var CLIENT_EXPORTS = new Set([
   "cleanupPortalPlaceholder",
   "createSearchParams",
   "queryHref",
+  "formatDate",
   "Async",
   "Region"
 ]);
@@ -7721,27 +7756,368 @@ var REACTIVE_PRIMITIVES = new Set([
 function prescanReactiveFactoriesInSource(source, filePath) {
   const sourceFile = ts8.createSourceFile(filePath + ".prescan", source, ts8.ScriptTarget.Latest, true, ts8.ScriptKind.TSX);
   const factories = new Map;
+  const declined = new Map;
+  const reactiveShaped = new Set;
+  const cleanFactoryImports = new Set;
   function visitTop(node) {
     if (ts8.isFunctionDeclaration(node) && node.name && node.body) {
-      const info = detectReactiveFactory(node, sourceFile, filePath);
-      if (info)
-        factories.set(node.name.text, info);
+      const det = detectReactiveFactory(node, sourceFile, filePath);
+      if (!det)
+        return;
+      switch (det.kind) {
+        case "factory":
+          factories.set(node.name.text, det.info);
+          break;
+        case "declined":
+          declined.set(node.name.text, det.declined);
+          break;
+        case "reactive-shaped":
+          reactiveShaped.add(node.name.text);
+          break;
+      }
     }
   }
   ts8.forEachChild(sourceFile, visitTop);
-  return { factories, sourceFile };
+  const result = { factories, declined, reactiveShaped, cleanFactoryImports, sourceFile };
+  prescanImportedReactiveFactories(sourceFile, filePath, result);
+  return result;
+}
+function toComponentRelativeSpecifier(resolvedAbs, componentFilePath) {
+  let rel = path_default.relative(path_default.dirname(componentFilePath), resolvedAbs).split(path_default.sep).join("/");
+  rel = rel.replace(/\.(tsx|ts|jsx|js)$/, "");
+  if (rel === "")
+    rel = ".";
+  if (!rel.startsWith("."))
+    rel = "./" + rel;
+  return rel;
+}
+function buildEntryImportIndex(sf, filePath) {
+  const index = new Map;
+  for (const stmt of sf.statements) {
+    if (!ts8.isImportDeclaration(stmt))
+      continue;
+    if (!ts8.isStringLiteral(stmt.moduleSpecifier))
+      continue;
+    if (stmt.importClause?.isTypeOnly)
+      continue;
+    const src = stmt.moduleSpecifier.text;
+    const targetKey = src.startsWith("./") || src.startsWith("../") ? resolveRelativeImportToFile(src, filePath) ?? "unresolved:" + src : src;
+    const namedBindings = stmt.importClause?.namedBindings;
+    if (namedBindings && ts8.isNamedImports(namedBindings)) {
+      for (const el of namedBindings.elements) {
+        if (el.isTypeOnly)
+          continue;
+        index.set(el.name.text, { targetKey, exportedName: (el.propertyName ?? el.name).text });
+      }
+    }
+  }
+  return index;
+}
+function collectEntryBindingNames(sf) {
+  const names = new Set;
+  function visit2(node) {
+    if (ts8.isImportDeclaration(node) && node.importClause) {
+      if (node.importClause.name)
+        names.add(node.importClause.name.text);
+      const namedBindings = node.importClause.namedBindings;
+      if (namedBindings && ts8.isNamedImports(namedBindings)) {
+        for (const el of namedBindings.elements)
+          names.add(el.name.text);
+      }
+      if (namedBindings && ts8.isNamespaceImport(namedBindings)) {
+        names.add(namedBindings.name.text);
+      }
+    }
+    if (ts8.isVariableDeclaration(node)) {
+      const out = [];
+      addBindingNames(node.name, out);
+      for (const n of out)
+        names.add(n);
+    }
+    if ((ts8.isFunctionDeclaration(node) || ts8.isClassDeclaration(node) || ts8.isEnumDeclaration(node)) && node.name) {
+      names.add(node.name.text);
+    }
+    if (ts8.isFunctionLike(node)) {
+      for (const p of node.parameters) {
+        const out = [];
+        addBindingNames(p.name, out);
+        for (const n of out)
+          names.add(n);
+      }
+    }
+    ts8.forEachChild(node, visit2);
+  }
+  visit2(sf);
+  return names;
+}
+function prescanImportedReactiveFactories(entrySourceFile, filePath, result) {
+  const candidateCallees = new Set;
+  function collectCandidates(node) {
+    if (ts8.isVariableDeclaration(node) && (ts8.isArrayBindingPattern(node.name) || ts8.isObjectBindingPattern(node.name)) && node.initializer && ts8.isCallExpression(node.initializer) && ts8.isIdentifier(node.initializer.expression)) {
+      candidateCallees.add(node.initializer.expression.text);
+    }
+    ts8.forEachChild(node, collectCandidates);
+  }
+  collectCandidates(entrySourceFile);
+  if (candidateCallees.size === 0)
+    return;
+  const importsToCheck = [];
+  for (const stmt of entrySourceFile.statements) {
+    if (!ts8.isImportDeclaration(stmt))
+      continue;
+    if (!ts8.isStringLiteral(stmt.moduleSpecifier))
+      continue;
+    const src = stmt.moduleSpecifier.text;
+    if (!src.startsWith("./") && !src.startsWith("../"))
+      continue;
+    if (stmt.importClause?.isTypeOnly)
+      continue;
+    const namedBindings = stmt.importClause?.namedBindings;
+    if (!namedBindings || !ts8.isNamedImports(namedBindings))
+      continue;
+    const specs = [];
+    for (const el of namedBindings.elements) {
+      if (el.isTypeOnly)
+        continue;
+      const local = el.name.text;
+      if (!candidateCallees.has(local))
+        continue;
+      specs.push({ exported: (el.propertyName ?? el.name).text, local });
+    }
+    if (specs.length === 0)
+      continue;
+    importsToCheck.push({ src, specs });
+  }
+  if (importsToCheck.length === 0)
+    return;
+  const entryBindingNames = collectEntryBindingNames(entrySourceFile);
+  const entryImportIndex = buildEntryImportIndex(entrySourceFile, filePath);
+  const plannedInjections = new Map;
+  for (const { src, specs } of importsToCheck) {
+    const resolved = resolveRelativeImportToFile(src, filePath);
+    if (!resolved)
+      continue;
+    let content;
+    try {
+      content = fs.readFileSync(resolved, "utf8");
+    } catch {
+      continue;
+    }
+    const alreadyKnown = (name) => result.factories.has(name) || result.declined.has(name) || result.reactiveShaped.has(name);
+    const hasAnyPrimitiveText = [...REACTIVE_PRIMITIVES].some((p) => content.includes(p));
+    if (!hasAnyPrimitiveText) {
+      for (const spec of specs) {
+        if (!alreadyKnown(spec.local))
+          result.cleanFactoryImports.add(spec.local);
+      }
+      continue;
+    }
+    const helperSf = ts8.createSourceFile(resolved + ".prescan", content, ts8.ScriptTarget.Latest, true, ts8.ScriptKind.TSX);
+    const localFns = new Map;
+    const exportedFns = new Map;
+    for (const stmt of helperSf.statements) {
+      if (ts8.isFunctionDeclaration(stmt) && stmt.name && stmt.body) {
+        localFns.set(stmt.name.text, stmt);
+        const hasExportModifier = stmt.modifiers?.some((m) => m.kind === ts8.SyntaxKind.ExportKeyword) ?? false;
+        const hasDefaultModifier = stmt.modifiers?.some((m) => m.kind === ts8.SyntaxKind.DefaultKeyword) ?? false;
+        if (hasExportModifier && !hasDefaultModifier) {
+          exportedFns.set(stmt.name.text, stmt);
+        }
+      }
+    }
+    for (const stmt of helperSf.statements) {
+      if (ts8.isExportDeclaration(stmt) && stmt.exportClause && ts8.isNamedExports(stmt.exportClause) && !stmt.moduleSpecifier && !stmt.isTypeOnly) {
+        for (const el of stmt.exportClause.elements) {
+          if (el.isTypeOnly)
+            continue;
+          const fn = localFns.get((el.propertyName ?? el.name).text);
+          if (fn)
+            exportedFns.set(el.name.text, fn);
+        }
+      }
+    }
+    const moduleBindings = collectHelperModuleValueBindings(helperSf);
+    for (const spec of specs) {
+      if (alreadyKnown(spec.local))
+        continue;
+      const fn = exportedFns.get(spec.exported);
+      if (!fn) {
+        result.cleanFactoryImports.add(spec.local);
+        continue;
+      }
+      const det = detectReactiveFactory(fn, helperSf, resolved);
+      if (!det) {
+        result.cleanFactoryImports.add(spec.local);
+        continue;
+      }
+      switch (det.kind) {
+        case "reactive-shaped":
+          result.reactiveShaped.add(spec.local);
+          break;
+        case "declined":
+          result.declined.set(spec.local, det.declined);
+          break;
+        case "factory": {
+          const capture = moduleCaptureCheck(fn, det.info, moduleBindings, fn.name.text);
+          if (capture.captured.length > 0) {
+            result.declined.set(spec.local, {
+              code: "BF112",
+              detail: `'${capture.captured.join("', '")}'`,
+              loc: det.info.loc
+            });
+            break;
+          }
+          const required = [];
+          const pending = [];
+          let declinedEntry = null;
+          for (const ref of capture.importedRefs) {
+            let specifier;
+            let targetKey;
+            if (ref.source.startsWith("./") || ref.source.startsWith("../")) {
+              const abs = resolveRelativeImportToFile(ref.source, resolved);
+              if (!abs) {
+                declinedEntry = {
+                  code: "BF112",
+                  detail: `'${ref.localName}' (import '${ref.source}' did not resolve from the helper file)`,
+                  loc: det.info.loc
+                };
+                break;
+              }
+              specifier = toComponentRelativeSpecifier(abs, filePath);
+              targetKey = abs;
+            } else {
+              specifier = ref.source;
+              targetKey = ref.source;
+            }
+            const existing = entryImportIndex.get(ref.localName);
+            if (existing && existing.targetKey === targetKey && existing.exportedName === ref.exportedName) {
+              continue;
+            }
+            const planned = plannedInjections.get(ref.localName);
+            const collides = existing !== undefined || planned !== undefined && (planned.targetKey !== targetKey || planned.exportedName !== ref.exportedName) || planned === undefined && entryBindingNames.has(ref.localName);
+            if (collides) {
+              declinedEntry = {
+                code: "BF113",
+                detail: `'${ref.localName}' from '${specifier}'`,
+                loc: det.info.loc
+              };
+              break;
+            }
+            pending.push([ref.localName, { targetKey, exportedName: ref.exportedName }]);
+            required.push({ localName: ref.localName, exportedName: ref.exportedName, specifier });
+          }
+          if (declinedEntry) {
+            result.declined.set(spec.local, declinedEntry);
+            break;
+          }
+          for (const [name, id] of pending)
+            plannedInjections.set(name, id);
+          det.info.sourceFilePath = resolved;
+          if (required.length > 0)
+            det.info.requiredImports = required;
+          result.factories.set(spec.local, det.info);
+          break;
+        }
+      }
+    }
+  }
+}
+function collectHelperModuleValueBindings(sf) {
+  const local = new Set;
+  const imported = new Map;
+  for (const stmt of sf.statements) {
+    if (ts8.isVariableStatement(stmt)) {
+      const out = [];
+      for (const decl of stmt.declarationList.declarations) {
+        addBindingNames(decl.name, out);
+      }
+      for (const n of out)
+        local.add(n);
+      continue;
+    }
+    if ((ts8.isFunctionDeclaration(stmt) || ts8.isClassDeclaration(stmt) || ts8.isEnumDeclaration(stmt)) && stmt.name) {
+      local.add(stmt.name.text);
+      continue;
+    }
+    if (ts8.isImportDeclaration(stmt)) {
+      if (stmt.importClause?.isTypeOnly)
+        continue;
+      if (!ts8.isStringLiteral(stmt.moduleSpecifier))
+        continue;
+      const src = stmt.moduleSpecifier.text;
+      if (src === "@barefootjs/client" || src === "@barefootjs/client/runtime")
+        continue;
+      if (stmt.importClause?.name)
+        local.add(stmt.importClause.name.text);
+      const namedBindings = stmt.importClause?.namedBindings;
+      if (namedBindings && ts8.isNamedImports(namedBindings)) {
+        for (const el of namedBindings.elements) {
+          if (el.isTypeOnly)
+            continue;
+          imported.set(el.name.text, { source: src, exportedName: (el.propertyName ?? el.name).text });
+        }
+      }
+      if (namedBindings && ts8.isNamespaceImport(namedBindings)) {
+        local.add(namedBindings.name.text);
+      }
+    }
+  }
+  return { local, imported };
+}
+function moduleCaptureCheck(fn, info, moduleBindings, selfName) {
+  if (!fn.body)
+    return { captured: [], importedRefs: [] };
+  const free = extractFreeIdentifiersFromNode(fn.body);
+  const exclude = new Set(info.params);
+  for (const b of info.localBindings)
+    exclude.add(b);
+  for (const r of info.returnTupleIdentifiers)
+    exclude.add(r);
+  for (const p of REACTIVE_PRIMITIVES)
+    exclude.add(p);
+  exclude.add(selfName);
+  const captured = [];
+  const importedRefs = [];
+  for (const id of free) {
+    if (exclude.has(id))
+      continue;
+    if (moduleBindings.local.has(id)) {
+      captured.push(id);
+      continue;
+    }
+    const imp = moduleBindings.imported.get(id);
+    if (imp)
+      importedRefs.push({ localName: id, source: imp.source, exportedName: imp.exportedName });
+  }
+  captured.sort();
+  importedRefs.sort((a, b) => a.localName < b.localName ? -1 : 1);
+  return { captured, importedRefs };
 }
 function detectReactiveFactory(node, sourceFile, filePath) {
   if (!node.body || !node.name)
     return null;
-  let tupleReturn = null;
+  let hasReactiveCall = false;
+  function checkForReactive(n) {
+    if (hasReactiveCall)
+      return;
+    if (ts8.isCallExpression(n) && ts8.isIdentifier(n.expression) && REACTIVE_PRIMITIVES.has(n.expression.text)) {
+      hasReactiveCall = true;
+      return;
+    }
+    ts8.forEachChild(n, checkForReactive);
+  }
+  checkForReactive(node.body);
+  if (!hasReactiveCall)
+    return null;
+  const loc = getSourceLocation(node, sourceFile, filePath);
+  let returnExpr = null;
   let returnCount = 0;
   for (const stmt of node.body.statements) {
     if (!ts8.isReturnStatement(stmt))
       continue;
     returnCount++;
     if (!stmt.expression)
-      return null;
+      return { kind: "reactive-shaped" };
     let expr = stmt.expression;
     while (ts8.isParenthesizedExpression(expr))
       expr = expr.expression;
@@ -7749,33 +8125,42 @@ function detectReactiveFactory(node, sourceFile, filePath) {
       expr = expr.expression;
     if (ts8.isTypeAssertionExpression(expr))
       expr = expr.expression;
-    if (!ts8.isArrayLiteralExpression(expr))
-      return null;
-    tupleReturn = expr;
+    returnExpr = expr;
   }
-  if (returnCount !== 1 || !tupleReturn)
-    return null;
+  if (returnCount !== 1 || !returnExpr)
+    return { kind: "reactive-shaped" };
   const returnTupleIdentifiers = [];
-  for (const el of tupleReturn.elements) {
-    if (!ts8.isIdentifier(el))
-      return null;
-    returnTupleIdentifiers.push(el.text);
-  }
-  if (returnTupleIdentifiers.length === 0)
-    return null;
-  let hasReactiveCall = false;
-  function checkForReactive(n) {
-    if (hasReactiveCall)
-      return;
-    if (ts8.isCallExpression(n) && ts8.isIdentifier(n.expression) && REACTIVE_PRIMITIVES.has(n.expression.text)) {
-      hasReactiveCall = true;
-      return;
+  let returnKind;
+  if (ts8.isArrayLiteralExpression(returnExpr)) {
+    returnKind = "tuple";
+    for (const el of returnExpr.elements) {
+      if (!ts8.isIdentifier(el))
+        return { kind: "reactive-shaped" };
+      returnTupleIdentifiers.push(el.text);
+    }
+    if (returnTupleIdentifiers.length === 0)
+      return { kind: "reactive-shaped" };
+  } else if (ts8.isObjectLiteralExpression(returnExpr)) {
+    returnKind = "object";
+    const hasNonShorthand = returnExpr.properties.some((p) => !ts8.isShorthandPropertyAssignment(p));
+    if (hasNonShorthand) {
+      return {
+        kind: "declined",
+        declined: {
+          code: "BF111",
+          detail: `return object of '${node.name.text}' uses non-shorthand properties`,
+          loc
+        }
+      };
     }
-    ts8.forEachChild(n, checkForReactive);
+    for (const p of returnExpr.properties) {
+      returnTupleIdentifiers.push(p.name.text);
+    }
+    if (returnTupleIdentifiers.length === 0)
+      return { kind: "reactive-shaped" };
+  } else {
+    return { kind: "reactive-shaped" };
   }
-  checkForReactive(node.body);
-  if (!hasReactiveCall)
-    return null;
   const localBindings = [];
   for (const stmt of node.body.statements) {
     if (ts8.isVariableStatement(stmt)) {
@@ -7788,19 +8173,24 @@ function detectReactiveFactory(node, sourceFile, filePath) {
   }
   const bodyStatements = node.body.statements.filter((s) => !ts8.isReturnStatement(s)).map((s) => s.getText(sourceFile)).join(`
 `);
-  const params = node.parameters.map((p) => {
-    if (ts8.isIdentifier(p.name))
-      return p.name.text;
-    return "";
-  });
-  if (params.some((p) => p === ""))
-    return null;
+  const params = [];
+  for (const p of node.parameters) {
+    if (ts8.isIdentifier(p.name)) {
+      params.push(p.name.text);
+      continue;
+    }
+    return { kind: "reactive-shaped" };
+  }
   return {
-    params,
-    bodySource: bodyStatements,
-    returnTupleIdentifiers,
-    localBindings,
-    loc: getSourceLocation(node, sourceFile, filePath)
+    kind: "factory",
+    info: {
+      params,
+      bodySource: bodyStatements,
+      returnTupleIdentifiers,
+      returnKind,
+      localBindings,
+      loc
+    }
   };
 }
 function addBindingNames(name, out) {
@@ -7825,6 +8215,7 @@ function rewriteFactoryCallsInSource(source, prescan) {
   const { factories, sourceFile } = prescan;
   const edits = [];
   let callSiteIndex = 0;
+  const inlinedFactories = new Set;
   function visitStmt(node, inComponent) {
     if (ts8.isVariableStatement(node) && inComponent) {
       for (const decl of node.declarationList.declarations) {
@@ -7838,8 +8229,6 @@ function rewriteFactoryCallsInSource(source, prescan) {
     });
   }
   function maybeRewriteDecl(stmt, decl) {
-    if (!ts8.isArrayBindingPattern(decl.name))
-      return;
     if (!decl.initializer || !ts8.isCallExpression(decl.initializer))
       return;
     if (!ts8.isIdentifier(decl.initializer.expression))
@@ -7848,7 +8237,21 @@ function rewriteFactoryCallsInSource(source, prescan) {
     const factory = factories.get(factoryName);
     if (!factory)
       return;
-    const elements = decl.name.elements;
+    if (ts8.isArrayBindingPattern(decl.name)) {
+      if (factory.returnKind !== "tuple")
+        return;
+      rewriteTupleDecl(stmt, decl.name, decl.initializer, factory);
+      return;
+    }
+    if (ts8.isObjectBindingPattern(decl.name)) {
+      if (factory.returnKind !== "object")
+        return;
+      rewriteObjectDecl(stmt, decl.name, decl.initializer, factory);
+      return;
+    }
+  }
+  function rewriteTupleDecl(stmt, pattern, call, factory) {
+    const elements = pattern.elements;
     if (elements.length !== factory.returnTupleIdentifiers.length)
       return;
     const callerNames = [];
@@ -7857,15 +8260,43 @@ function rewriteFactoryCallsInSource(source, prescan) {
         return;
       callerNames.push(el.name.text);
     }
-    const argTexts = decl.initializer.arguments.map((a) => a.getText(sourceFile));
+    const excludeFromSuffixRename = new Set(factory.params);
+    for (const r of factory.returnTupleIdentifiers)
+      excludeFromSuffixRename.add(r);
+    const renameReturnToCallerNames = new Map;
+    for (let i = 0;i < factory.returnTupleIdentifiers.length; i++) {
+      renameReturnToCallerNames.set(factory.returnTupleIdentifiers[i], callerNames[i]);
+    }
+    inlineFactoryCallAtSite(stmt, factory, call.arguments, excludeFromSuffixRename, renameReturnToCallerNames);
+  }
+  function rewriteObjectDecl(stmt, pattern, call, factory) {
+    const destructured = new Set;
+    for (const el of pattern.elements) {
+      if (el.dotDotDotToken)
+        return;
+      if (el.propertyName)
+        return;
+      if (el.initializer)
+        return;
+      if (!ts8.isIdentifier(el.name))
+        return;
+      if (!factory.returnTupleIdentifiers.includes(el.name.text))
+        return;
+      destructured.add(el.name.text);
+    }
+    const excludeFromSuffixRename = new Set(factory.params);
+    for (const d of destructured)
+      excludeFromSuffixRename.add(d);
+    inlineFactoryCallAtSite(stmt, factory, call.arguments, excludeFromSuffixRename, null);
+  }
+  function inlineFactoryCallAtSite(stmt, factory, args, excludeFromSuffixRename, renameReturnToCallerNames) {
+    const argTexts = args.map((a) => a.getText(sourceFile));
     const thisCallIndex = callSiteIndex++;
     const suffix = `_bf${thisCallIndex}`;
     let body = factory.bodySource;
     const internalRenames = new Set(factory.localBindings);
-    for (const p of factory.params)
-      internalRenames.delete(p);
-    for (const r of factory.returnTupleIdentifiers)
-      internalRenames.delete(r);
+    for (const ex of excludeFromSuffixRename)
+      internalRenames.delete(ex);
     for (const name of internalRenames) {
       body = body.replace(new RegExp(`\\b${escapeRegex(name)}\\b`, "g"), name + suffix);
     }
@@ -7876,20 +8307,44 @@ function rewriteFactoryCallsInSource(source, prescan) {
       const wrapped = atomicArg.test(a.trim()) ? a.trim() : `(${a})`;
       body = body.replace(new RegExp(`\\b${escapeRegex(p)}\\b`, "g"), wrapped);
     }
-    for (let i = 0;i < factory.returnTupleIdentifiers.length; i++) {
-      const n = factory.returnTupleIdentifiers[i];
-      const caller = callerNames[i];
-      body = body.replace(new RegExp(`\\b${escapeRegex(n)}\\b`, "g"), caller);
+    if (renameReturnToCallerNames) {
+      for (const [n, caller] of renameReturnToCallerNames) {
+        body = body.replace(new RegExp(`\\b${escapeRegex(n)}\\b`, "g"), caller);
+      }
     }
     edits.push({
       start: stmt.getStart(sourceFile),
       end: stmt.getEnd(),
       replacement: body
     });
+    inlinedFactories.add(factory);
   }
   visitStmt(sourceFile, false);
   if (edits.length === 0)
     return source;
+  const importsBySpecifier = new Map;
+  for (const f of inlinedFactories) {
+    for (const r of f.requiredImports ?? []) {
+      let names = importsBySpecifier.get(r.specifier);
+      if (!names) {
+        names = new Map;
+        importsBySpecifier.set(r.specifier, names);
+      }
+      names.set(r.localName, r.exportedName);
+    }
+  }
+  if (importsBySpecifier.size > 0) {
+    const lines = [...importsBySpecifier].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([spec, names]) => {
+      const specifiers = [...names].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([local, exported]) => exported === local ? local : `${exported} as ${local}`);
+      return `import { ${specifiers.join(", ")} } from '${spec}'`;
+    });
+    const at = factoryImportInsertionOffset(sourceFile);
+    edits.push({ start: at, end: at, replacement: at === 0 ? lines.join(`
+`) + `
+` : `
+` + lines.join(`
+`) });
+  }
   edits.sort((a, b) => b.start - a.start);
   let out = source;
   for (const e of edits) {
@@ -7897,6 +8352,20 @@ function rewriteFactoryCallsInSource(source, prescan) {
   }
   return out;
 }
+function factoryImportInsertionOffset(sf) {
+  let lastImportEnd = -1;
+  let directiveEnd = -1;
+  for (const stmt of sf.statements) {
+    if (ts8.isImportDeclaration(stmt)) {
+      lastImportEnd = stmt.getEnd();
+      continue;
+    }
+    if (directiveEnd === -1 && ts8.isExpressionStatement(stmt) && ts8.isStringLiteral(stmt.expression) && stmt.expression.text === "use client") {
+      directiveEnd = stmt.getEnd();
+    }
+  }
+  return lastImportEnd >= 0 ? lastImportEnd : directiveEnd >= 0 ? directiveEnd : 0;
+}
 function isPascalCaseComponentFn(node) {
   if (ts8.isFunctionDeclaration(node) && node.name) {
     return /^[A-Z]/.test(node.name.text);
@@ -7909,6 +8378,25 @@ function isPascalCaseComponentFn(node) {
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function declinedFactoryMessage(callee, d) {
+  if (d.code === "BF112") {
+    return `Reactive factory '${callee}' references ${d.detail} from its own module ` + `scope and cannot be inlined. Move the referenced helper(s) into this file, ` + `pass them as factory arguments, or inline the factory here.`;
+  }
+  if (d.code === "BF113") {
+    return `Reactive factory '${callee}' cannot be inlined: it needs ${d.detail} ` + `imported 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 (import { x as y }).`;
+  }
+  return `Reactive factory '${callee}' cannot be inlined: ${d.detail}.`;
+}
+function declinedFactoryErrorCode(code) {
+  switch (code) {
+    case "BF112":
+      return ErrorCodes.REACTIVE_FACTORY_MODULE_CAPTURE;
+    case "BF113":
+      return ErrorCodes.REACTIVE_FACTORY_IMPORT_COLLISION;
+    default:
+      return ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED;
+  }
+}
 function validateReactiveFactoryCalls(ctx) {
   if (!ctx.componentNode)
     return;
@@ -7919,26 +8407,104 @@ function validateReactiveFactoryCalls(ctx) {
     if (!ts8.isVariableStatement(stmt))
       continue;
     for (const decl of stmt.declarationList.declarations) {
-      if (!ts8.isArrayBindingPattern(decl.name))
-        continue;
       if (!decl.initializer || !ts8.isCallExpression(decl.initializer))
         continue;
       if (!ts8.isIdentifier(decl.initializer.expression))
         continue;
       const callee = decl.initializer.expression.text;
-      if (callee === "createSignal" || callee === "createMemo")
-        continue;
-      if (resolveEnvSignalKey(decl.initializer, ctx))
+      const loc = getSourceLocation(stmt, ctx.sourceFile, ctx.filePath);
+      if (ts8.isArrayBindingPattern(decl.name)) {
+        if (callee === "createSignal" || callee === "createMemo")
+          continue;
+        if (resolveEnvSignalKey(decl.initializer, ctx))
+          continue;
+        const declinedEntry = ctx.declinedReactiveFactories.get(callee);
+        if (declinedEntry) {
+          ctx.errors.push(createError(declinedFactoryErrorCode(declinedEntry.code), loc, { severity: "error", message: declinedFactoryMessage(callee, declinedEntry) }));
+          continue;
+        }
+        const objectFactory = ctx.reactiveFactories.get(callee);
+        if (objectFactory && objectFactory.returnKind === "object") {
+          ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+            severity: "error",
+            message: `'${callee}' is a reactive factory that returns an object — destructure ` + `it with a matching object pattern: const { ${objectFactory.returnTupleIdentifiers.join(", ")} } = ${callee}(...)`
+          }));
+          continue;
+        }
+        ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+          severity: "error",
+          message: `Tuple destructuring of '${callee}(...)': this helper is not a ` + `recognised reactive factory (createSignal / createMemo / a ` + `same-file helper that wraps them with a single \`return [a, b, ...]\`).`,
+          suggestion: {
+            message: `Inline the createSignal call at the call site, or move the ` + `helper into this file as a function that returns a tuple of ` + `identifiers at its single exit point.`
+          }
+        }));
         continue;
-      ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, getSourceLocation(stmt, ctx.sourceFile, ctx.filePath), {
+      }
+      if (ts8.isObjectBindingPattern(decl.name)) {
+        validateObjectFactoryDestructure(ctx, decl.name, callee, loc);
+      }
+    }
+  }
+}
+function validateObjectFactoryDestructure(ctx, pattern, callee, loc) {
+  const factory = ctx.reactiveFactories.get(callee);
+  if (factory) {
+    if (factory.returnKind === "tuple") {
+      ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
         severity: "error",
-        message: `Tuple destructuring of '${callee}(...)': this helper is not a ` + `recognised reactive factory (createSignal / createMemo / a ` + `same-file helper that wraps them with a single \`return [a, b, ...]\`).`,
-        suggestion: {
-          message: `Inline the createSignal call at the call site, or move the ` + `helper into this file as a function that returns a tuple of ` + `identifiers at its single exit point.`
-        }
+        message: `'${callee}' is a reactive factory that returns a tuple — destructure ` + `it positionally: const [${factory.returnTupleIdentifiers.join(", ")}] = ${callee}(...)`
+      }));
+      return;
+    }
+    const hasUnsupportedElement = pattern.elements.some((el) => !!el.propertyName || !!el.initializer || !!el.dotDotDotToken || !ts8.isIdentifier(el.name));
+    if (hasUnsupportedElement) {
+      ctx.errors.push(createError(ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED, loc, {
+        severity: "error",
+        message: `Object destructure of reactive factory '${callee}' uses a property ` + `rename, default, or rest element; only shorthand destructuring of ` + `{ ${factory.returnTupleIdentifiers.join(", ")} } is supported.`
       }));
+      return;
+    }
+    const unknown = pattern.elements.map((el) => ts8.isIdentifier(el.name) ? el.name.text : "").filter((name) => name && !factory.returnTupleIdentifiers.includes(name));
+    if (unknown.length > 0) {
+      const label = unknown.length === 1 ? "property" : "properties";
+      ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+        severity: "error",
+        message: `Object destructure of reactive factory '${callee}' references ${label} ` + `'${unknown.join("', '")}' not present in its return { ${factory.returnTupleIdentifiers.join(", ")} }.`
+      }));
+      return;
+    }
+    return;
+  }
+  const declinedEntry = ctx.declinedReactiveFactories.get(callee);
+  if (declinedEntry) {
+    ctx.errors.push(createError(declinedFactoryErrorCode(declinedEntry.code), loc, { severity: "error", message: declinedFactoryMessage(callee, declinedEntry) }));
+    return;
+  }
+  if (ctx.reactiveShapedHelpers.has(callee)) {
+    ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+      severity: "error",
+      message: `Object destructure of '${callee}(...)': this helper wraps a reactive ` + `primitive but does not match the inlinable factory shape (single ` + "`return { a, b }` of shorthand identifiers at its one exit point)."
+    }));
+    return;
+  }
+  if (ctx.cleanFactoryImports.has(callee))
+    return;
+  let matchedImportSource = null;
+  for (const imp of ctx.imports) {
+    if (imp.isTypeOnly)
+      continue;
+    const spec = imp.specifiers.find((s) => !s.isTypeOnly && (s.alias ?? s.name) === callee);
+    if (spec) {
+      matchedImportSource = imp.source;
+      break;
     }
   }
+  if (matchedImportSource !== null && !matchedImportSource.startsWith("@barefootjs/") && /^(use|create)[A-Z]/.test(callee)) {
+    ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+      severity: "error",
+      message: `Object destructure of imported '${callee}(...)': the compiler cannot ` + `inspect this import (non-relative or unresolvable path), so if it wraps ` + `createSignal/createMemo the destructured bindings will not be reactive. Move ` + `the helper to a relative-imported file or inline its body.`
+    }));
+  }
 }
 
 // src/jsx-to-ir.ts
@@ -8460,6 +9026,330 @@ function resolveFreeRefs(node, env) {
   return resolveFreeRefsInternal(node, env, new Set);
 }
 
+// src/to-locale-date-lowering.ts
+var TO_LOCALE_TZ_RE = /^(?:UTC|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+var PROBE_UTC = new Date(Date.UTC(2001, 1, 3));
+var formatCache = new Map;
+var namesCache = new Map;
+function deriveMonthNames(locale, ctx) {
+  return deriveNamesCached(`${locale}|m|${ctx}`, () => {
+    const months = (width) => 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")];
+  });
+}
+function deriveWeekdayNames(locale, ctx) {
+  return deriveNamesCached(`${locale}|w|${ctx}`, () => {
+    const weekdays = (width) => 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, options, utc, type) {
+  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, derive) {
+  const cached = namesCache.get(key);
+  if (cached !== undefined)
+    return cached;
+  let derived;
+  try {
+    derived = derive();
+  } catch {
+    derived = null;
+  }
+  namesCache.set(key, derived);
+  return derived;
+}
+function resolveLocaleDateFormat(locale, probeOptions) {
+  const key = `${locale}|${JSON.stringify(probeOptions, Object.keys(probeOptions).sort())}`;
+  const cached = formatCache.get(key);
+  if (cached !== undefined)
+    return cached;
+  const derived = deriveFormat(locale, probeOptions);
+  formatCache.set(key, derived);
+  return derived;
+}
+var VERIFY_UTC = new Date(Date.UTC(2001, 4, 13));
+function renderPatternAt(pattern, names, y, m, d, wd) {
+  const pad2 = (n) => 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, probeOptions) {
+  let dtf;
+  let parts;
+  try {
+    dtf = new Intl.DateTimeFormat(locale, {
+      ...probeOptions,
+      timeZone: "UTC"
+    });
+    const resolved = dtf.resolvedOptions();
+    if (resolved.calendar !== "gregory" || resolved.numberingSystem !== "latn")
+      return null;
+    parts = dtf.formatToParts(PROBE_UTC);
+  } catch {
+    return null;
+  }
+  const monthTables = [
+    deriveMonthNames(locale, "formatting"),
+    deriveMonthNames(locale, "standalone")
+  ];
+  const weekdayTables = [
+    deriveWeekdayNames(locale, "formatting"),
+    deriveWeekdayNames(locale, "standalone")
+  ];
+  let monthTable = null;
+  let weekdayTable = null;
+  let pattern = "";
+  let usesNames = false;
+  for (const part of parts) {
+    switch (part.type) {
+      case "year":
+        if (part.value !== "2001")
+          return null;
+        pattern += "YYYY";
+        break;
+      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;
+        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;
+        weekdayTable = wide ?? abbr;
+        usesNames = true;
+        break;
+      }
+      case "literal":
+        if (/[YMD]/.test(part.value) || /ddd/.test(part.value))
+          return null;
+        pattern += part.value;
+        break;
+      default:
+        return null;
+    }
+  }
+  if (!/YYYY|MMMM|MMM|MM|M/.test(pattern) && !/DD|D/.test(pattern))
+    return null;
+  if (!usesNames)
+    return { pattern, names: null };
+  const names = [
+    ...monthTable ?? monthTables[0] ?? monthTables[1] ?? Array(24).fill(""),
+    ...weekdayTable ?? weekdayTables[0] ?? weekdayTables[1] ?? Array(14).fill("")
+  ];
+  if (renderPatternAt(pattern, names, 2001, 5, 13, 0) !== dtf.format(VERIFY_UTC))
+    return null;
+  return { pattern, names };
+}
+function unionMemberLiteral(member) {
+  const m = /^'([^'\\]*)'$|^"([^"\\]*)"$/.exec(member.raw.trim());
+  return m ? m[1] ?? m[2] : null;
+}
+function resolveLocaleUnionMembers(locale, metadata) {
+  let sourcePropName = 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 = [];
+  for (const member of type.unionTypes) {
+    const value = unionMemberLiteral(member);
+    if (value === null)
+      return null;
+    members.push(value);
+  }
+  return members;
+}
+var strLit = (value) => ({ kind: "literal", value, literalType: "string" });
+function strArr(values) {
+  return {
+    kind: "array-literal",
+    elements: values.map((v) => strLit(v)),
+    raw: JSON.stringify(values)
+  };
+}
+function foldMembers(locale, members, leaves, allEqual) {
+  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;
+}
+function matchToLocaleDateStringCall(callee, args, metadata) {
+  if (callee.kind !== "member" || callee.computed)
+    return null;
+  if (callee.property !== "toLocaleDateString" || args.length !== 2)
+    return null;
+  const [locale, options] = args;
+  if (options.kind !== "object-literal")
+    return null;
+  let tz = null;
+  const probeOptions = {};
+  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;
+  const typeName = baseTypeName(receiverType.raw);
+  if (typeName !== "Date")
+    return null;
+  if (metadata.typeDefinitions.some((d) => d.name === typeName))
+    return null;
+  if (locale.kind === "literal" && locale.literalType === "string") {
+    const format2 = resolveLocaleDateFormat(String(locale.value), probeOptions);
+    if (format2 === null)
+      return null;
+    return {
+      kind: "helper-call",
+      helper: "format_date",
+      args: [callee.object, strLit(format2.pattern), strLit(tz), strArr(format2.names ?? [])]
+    };
+  }
+  const members = resolveLocaleUnionMembers(locale, metadata);
+  if (!members)
+    return null;
+  const formats = [];
+  for (const member of members) {
+    const format2 = resolveLocaleDateFormat(member, probeOptions);
+    if (format2 === null)
+      return null;
+    formats.push(format2);
+  }
+  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,
+      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)
+    ]
+  };
+}
+function foldedArgToClientJs(arg, localeText) {
+  if (arg.kind === "literal")
+    return JSON.stringify(arg.value);
+  if (arg.kind === "array-literal") {
+    const values = [];
+    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;
+  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}`;
+}
+var toLocaleDatePlugin = {
+  name: "toLocaleDateString",
+  prepare(metadata) {
+    if (!metadata.propsType || !typeReachesDate(metadata.propsType, metadata, new Set))
+      return null;
+    return (callee, args) => matchToLocaleDateStringCall(callee, args, metadata);
+  }
+};
+
 // src/jsx-to-ir.ts
 import { toHTMLAttrName, decodeEntities } from "@barefootjs/shared";
 var CLIENT_DIRECTIVE_INTERIOR_RE2 = /^\s*@client\s*$/;
@@ -8555,6 +9445,19 @@ function getDateLoweringMatcher(ctx) {
   }
   return ctx._dateLoweringMatcher;
 }
+function getToLocaleDateLoweringMatcher(ctx) {
+  if (ctx._toLocaleDateLoweringMatcher === undefined) {
+    const a = ctx.analyzer;
+    const metadataSlice = {
+      propsType: a.propsType,
+      propsObjectName: a.propsObjectName,
+      propsParams: a.propsParams,
+      typeDefinitions: a.typeDefinitions
+    };
+    ctx._toLocaleDateLoweringMatcher = toLocaleDatePlugin.prepare(metadataSlice);
+  }
+  return ctx._toLocaleDateLoweringMatcher;
+}
 function lowerDateCalls(text, expr, ctx) {
   const matcher = getDateLoweringMatcher(ctx);
   if (!matcher)
@@ -8583,8 +9486,48 @@ function lowerDateCalls(text, expr, ctx) {
   }
   return restore(result);
 }
+function lowerToLocaleDateCalls(text, expr, ctx) {
+  const matcher = getToLocaleDateLoweringMatcher(ctx);
+  if (!matcher)
+    return text;
+  const candidates = [];
+  function visit2(n) {
+    if (ts11.isCallExpression(n) && n.arguments.length === 2 && ts11.isPropertyAccessExpression(n.expression) && !n.expression.questionDotToken && n.expression.name.text === "toLocaleDateString") {
+      candidates.push(n);
+    }
+    ts11.forEachChild(n, visit2);
+  }
+  visit2(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;
+    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;
+    let namesJs = 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);
+    result = replaceProtectedCall(result, matchText, () => `formatDate(${receiverText}, ${patternJs}, ${JSON.stringify(tzArg.value)}${namesJs !== null ? `, ${namesJs}` : ""})`);
+  }
+  return restore(result);
+}
 function rewriteBarePropRefs2(text, expr, ctx) {
-  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;
@@ -13436,7 +14379,8 @@ var RUNTIME_IMPORT_CANDIDATES = [
   "tAfter",
   "beginTurn",
   "endTurn",
-  "date"
+  "date",
+  "formatDate"
 ];
 var RUNTIME_MODULE = "@barefootjs/client/runtime";
 var IMPORT_PLACEHOLDER = "/* __BAREFOOTJS_DOM_IMPORTS__ */";
@@ -14722,7 +15666,7 @@ function importsSearchParams(metadata) {
 function queryHrefLocalNames(metadata) {
   const names = new Set;
   for (const imp of metadata.imports) {
-    if (!QUERY_HREF_SOURCES.has(imp.source) || imp.isTypeOnly)
+    if (!CLIENT_HELPER_SOURCES.has(imp.source) || imp.isTypeOnly)
       continue;
     for (const s of imp.specifiers) {
       if (s.isTypeOnly || s.isNamespace || s.isDefault)
@@ -14733,10 +15677,24 @@ function queryHrefLocalNames(metadata) {
   }
   return names;
 }
-var QUERY_HREF_SOURCES = new Set([
+var CLIENT_HELPER_SOURCES = new Set([
   "@barefootjs/client",
   "@barefootjs/client/runtime"
 ]);
+function formatDateLocalNames(metadata) {
+  const names = new Set;
+  for (const imp of metadata.imports) {
+    if (!CLIENT_HELPER_SOURCES.has(imp.source) || imp.isTypeOnly)
+      continue;
+    for (const s of imp.specifiers) {
+      if (s.isTypeOnly || s.isNamespace || s.isDefault)
+        continue;
+      if (s.name === "formatDate")
+        names.add(s.alias ?? s.name);
+    }
+  }
+  return names;
+}
 function matchSearchParamsMethodCall(callee, args, localNames) {
   if (callee.kind !== "member" || callee.computed)
     return null;
@@ -16602,6 +17560,66 @@ function getReactiveDateLoweringMatcher(ctx) {
   };
   return datePlugin.prepare(metadataSlice);
 }
+function getReactiveToLocaleMatcher(ctx) {
+  if (!ctx.propsType)
+    return null;
+  const metadataSlice = {
+    propsType: ctx.propsType,
+    propsObjectName: ctx.propsObjectName,
+    propsParams: ctx.propsParams,
+    typeDefinitions: ctx.typeDefinitions ?? []
+  };
+  return toLocaleDatePlugin.prepare(metadataSlice);
+}
+function lowerToLocaleCallsInReactiveExpr(expr, matcher) {
+  if (!matcher)
+    return expr;
+  let sourceFile;
+  try {
+    sourceFile = ts14.createSourceFile("__reactive_expr__.ts", `(${expr});`, ts14.ScriptTarget.Latest, true, ts14.ScriptKind.TS);
+  } catch {
+    return expr;
+  }
+  const stmt = sourceFile.statements[0];
+  if (!stmt || !ts14.isExpressionStatement(stmt))
+    return expr;
+  const root = ts14.isParenthesizedExpression(stmt.expression) ? stmt.expression.expression : stmt.expression;
+  const candidates = [];
+  const visit3 = (n) => {
+    if (ts14.isCallExpression(n) && n.arguments.length === 2 && ts14.isPropertyAccessExpression(n.expression) && !n.expression.questionDotToken && n.expression.name.text === "toLocaleDateString") {
+      candidates.push(n);
+    }
+    ts14.forEachChild(n, visit3);
+  };
+  visit3(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;
+    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;
+    let namesJs = 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);
+    result = replaceProtectedCall(result, matchText, () => `formatDate(${receiverText}, ${patternJs}, ${JSON.stringify(tzArg.value)}${namesJs !== null ? `, ${namesJs}` : ""})`);
+  }
+  return restore(result);
+}
 function lowerDateCallsInReactiveExpr(expr, matcher) {
   if (!matcher)
     return expr;
@@ -16641,6 +17659,7 @@ function lowerDateCallsInReactiveExpr(expr, matcher) {
 }
 function emitDynamicTextUpdates(lines, ctx) {
   const dateLoweringMatcher = getReactiveDateLoweringMatcher(ctx);
+  const toLocaleMatcher = getReactiveToLocaleMatcher(ctx);
   const byExpression = new Map;
   for (const elem of ctx.dynamicElements) {
     const key = elem.expression;
@@ -16650,7 +17669,7 @@ function emitDynamicTextUpdates(lines, ctx) {
     byExpression.get(key).push(elem);
   }
   for (const [rawExpr, elems] of byExpression) {
-    const expr = lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher);
+    const expr = lowerToLocaleCallsInReactiveExpr(lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher), toLocaleMatcher);
     const conditionalElems = elems.filter((e) => e.insideConditional);
     const normalElems = elems.filter((e) => !e.insideConditional);
     if (normalElems.length > 0 || conditionalElems.length > 0) {
@@ -19875,13 +20894,14 @@ function pushDiagnostic(errors, seen, loc, method, receiverPath, isProp, typeNam
     return;
   seen.add(key);
   const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`;
+  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
     }
   });
 }
@@ -21397,6 +22417,30 @@ function isOmitBranch(node) {
   }
   return false;
 }
+// src/format-date-lowering.ts
+var UTC_LITERAL = { kind: "literal", value: "UTC", literalType: "string" };
+var EMPTY_NAMES = { kind: "array-literal", elements: [], raw: "[]" };
+function matchFormatDateCall(callee, args, locals) {
+  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]
+  };
+}
+var formatDatePlugin = {
+  name: "formatDate",
+  prepare(metadata) {
+    const locals = formatDateLocalNames(metadata);
+    if (locals.size === 0)
+      return null;
+    return (callee, args) => matchFormatDateCall(callee, args, locals);
+  }
+};
+
 // src/builtin-lowering-plugins.ts
 var queryHrefPlugin = {
   name: "queryHref",
@@ -21410,7 +22454,12 @@ var queryHrefPlugin = {
     };
   }
 };
-var BUILTIN_LOWERING_PLUGINS = [queryHrefPlugin, datePlugin];
+var BUILTIN_LOWERING_PLUGINS = [
+  queryHrefPlugin,
+  datePlugin,
+  formatDatePlugin,
+  toLocaleDatePlugin
+];
 function registerBuiltinLoweringPlugins() {
   for (const plugin of BUILTIN_LOWERING_PLUGINS)
     registerLoweringPlugin(plugin);
@@ -24453,6 +25502,7 @@ export {
   formatFallbackExplanations,
   formatEventSummary,
   formatError,
+  formatDateLocalNames,
   formatComponentSummary,
   formatComponentGraph,
   formatBudgetDiff,