@barefootjs/jsx 0.21.4 → 0.23.0

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,9 @@ 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"
 };
 var errorMessages = {
   [ErrorCodes.MISSING_USE_CLIENT]: "'use client' directive required for components with createSignal or event handlers",
@@ -5241,7 +5267,9 @@ 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."
 };
 function createError(code, loc, options) {
   if (code === undefined || !(code in errorMessages)) {
@@ -5567,6 +5595,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 +6504,7 @@ var CLIENT_EXPORTS = new Set([
   "cleanupPortalPlaceholder",
   "createSearchParams",
   "queryHref",
+  "formatDate",
   "Async",
   "Region"
 ]);
@@ -7721,27 +7754,241 @@ 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 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;
+  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 offending = moduleCaptureCheck(fn, det.info, moduleBindings, fn.name.text);
+          if (offending.length > 0) {
+            result.declined.set(spec.local, {
+              code: "BF112",
+              detail: `'${offending.join("', '")}'`,
+              loc: det.info.loc
+            });
+          } else {
+            det.info.sourceFilePath = resolved;
+            result.factories.set(spec.local, det.info);
+          }
+          break;
+        }
+      }
+    }
+  }
+}
+function collectHelperModuleValueBindings(sf) {
+  const names = new Set;
+  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)
+        names.add(n);
+      continue;
+    }
+    if ((ts8.isFunctionDeclaration(stmt) || ts8.isClassDeclaration(stmt) || ts8.isEnumDeclaration(stmt)) && stmt.name) {
+      names.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)
+        names.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;
+          names.add(el.name.text);
+        }
+      }
+      if (namedBindings && ts8.isNamespaceImport(namedBindings)) {
+        names.add(namedBindings.name.text);
+      }
+    }
+  }
+  return names;
+}
+function moduleCaptureCheck(fn, info, moduleBindings, selfName) {
+  if (!fn.body)
+    return [];
+  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 offending = [];
+  for (const id of free) {
+    if (exclude.has(id))
+      continue;
+    if (moduleBindings.has(id))
+      offending.push(id);
+  }
+  return offending.sort();
 }
 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 +7996,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 +8044,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) {
@@ -7838,8 +8099,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 +8107,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 +8130,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,10 +8177,10 @@ 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),
@@ -7909,6 +8210,12 @@ 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.`;
+  }
+  return `Reactive factory '${callee}' cannot be inlined: ${d.detail}.`;
+}
 function validateReactiveFactoryCalls(ctx) {
   if (!ctx.componentNode)
     return;
@@ -7919,26 +8226,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(declinedEntry.code === "BF112" ? ErrorCodes.REACTIVE_FACTORY_MODULE_CAPTURE : ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED, 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(declinedEntry.code === "BF112" ? ErrorCodes.REACTIVE_FACTORY_MODULE_CAPTURE : ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED, 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 +8845,114 @@ 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 patternCache = new Map;
+function resolveLocaleDatePattern(locale) {
+  const cached = patternCache.get(locale);
+  if (cached !== undefined)
+    return cached;
+  const derived = derivePattern(locale);
+  patternCache.set(locale, derived);
+  return derived;
+}
+function derivePattern(locale) {
+  let parts;
+  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;
+  }
+  let pattern = "";
+  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";
+        else if (part.value === "02")
+          pattern += "MM";
+        else
+          return null;
+        break;
+      case "day":
+        if (part.value === "3")
+          pattern += "D";
+        else if (part.value === "03")
+          pattern += "DD";
+        else
+          return null;
+        break;
+      case "literal":
+        if (/[YMD]/.test(part.value))
+          return null;
+        pattern += part.value;
+        break;
+      default:
+        return null;
+    }
+  }
+  if (!pattern.includes("YYYY") || !/M/.test(pattern) || !/D/.test(pattern))
+    return null;
+  return pattern;
+}
+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 (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" }
+    ]
+  };
+}
+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 +9048,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 +9089,38 @@ 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] = node.args;
+    if (patternArg?.kind !== "literal" || tzArg?.kind !== "literal")
+      continue;
+    const receiverText = ctx.getJS(propAccess.expression);
+    const matchText = ctx.getJS(call);
+    result = replaceProtectedCall(result, matchText, () => `formatDate(${receiverText}, ${JSON.stringify(patternArg.value)}, ${JSON.stringify(tzArg.value)})`);
+  }
+  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 +13972,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 +15259,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 +15270,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 +17153,56 @@ 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] = node.args;
+    if (patternArg?.kind !== "literal" || tzArg?.kind !== "literal")
+      continue;
+    const receiverText = propAccess.expression.getText(sourceFile);
+    const matchText = call.getText(sourceFile);
+    result = replaceProtectedCall(result, matchText, () => `formatDate(${receiverText}, ${JSON.stringify(patternArg.value)}, ${JSON.stringify(tzArg.value)})`);
+  }
+  return restore(result);
+}
 function lowerDateCallsInReactiveExpr(expr, matcher) {
   if (!matcher)
     return expr;
@@ -16641,6 +17242,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 +17252,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 +20477,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 +22000,29 @@ function isOmitBranch(node) {
   }
   return false;
 }
+// src/format-date-lowering.ts
+var UTC_LITERAL = { kind: "literal", value: "UTC", literalType: "string" };
+function matchFormatDateCall(callee, args, locals) {
+  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]
+  };
+}
+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 +22036,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 +25084,7 @@ export {
   formatFallbackExplanations,
   formatEventSummary,
   formatError,
+  formatDateLocalNames,
   formatComponentSummary,
   formatComponentGraph,
   formatBudgetDiff,