@barefootjs/jsx 0.21.4 → 0.24.1

package/src/analyzer.ts

@@ -7,7 +7,7 @@
  */
 
 import ts from 'typescript'
-import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo } from './types.ts'
+import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, SourceLocation } from './types.ts'
 import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
 import { incrementCounter } from './instrumentation.ts'
@@ -23,7 +23,7 @@ import {
   isArrowComponentFunction,
   collectReactiveGetterNames,
 } from './analyzer-context.ts'
-import { createError, createWarning, ErrorCodes } from './errors.ts'
+import { createError, createWarning, ErrorCodes, type ErrorCode } from './errors.ts'
 import { baseTypeName } from './rich-type-evidence.ts'
 import { CATALOGUED_RICH_TYPE_NAMES } from './date-lowering.ts'
 import path from 'node:path'
@@ -232,6 +232,15 @@ export function analyzeComponent(
   const ctx = createAnalyzerContext(sourceFile, filePath)
   ctx.checker = checker
 
+  // Reactive-factory prescan results (#931, #2325 cross-file + object-
+  // return round 2) — same-file and relative-imported factories, plus the
+  // declined / reactive-shaped buckets `validateReactiveFactoryCalls` uses
+  // to emit a specific diagnostic instead of the generic BF110.
+  ctx.reactiveFactories = prescan.factories
+  ctx.declinedReactiveFactories = prescan.declined
+  ctx.reactiveShapedHelpers = prescan.reactiveShaped
+  ctx.cleanFactoryImports = prescan.cleanFactoryImports
+
   // BF050 — surface "no shared Program supplied for type-based reactivity
   // classification" as a diagnostic so callers can fail strict builds
   // rather than silently depending on the per-file Program fallback
@@ -1865,6 +1874,10 @@ const CLIENT_EXPORTS = new Set([
   // `searchParams`. Runs natively on the client; SSR adapters lower a
   // `queryHref(base, { … })` call to their query helper (go-template: `bf_query`).
   'queryHref',
+  // Pure date formatter (#2324). Runs natively on the client; SSR adapters
+  // lower a `formatDate(date, pattern, tz)` call to their `format_date`
+  // helper (spec/template-helpers.md).
+  'formatDate',
   // Compile-away JSX built-ins (#1915) — importing them is what scopes the
   // compiler's `<Async>` / `<Region>` recognition; the import is elided on emit.
   'Async', 'Region',
@@ -3867,14 +3880,27 @@ export const REACTIVE_PRIMITIVES = new Set([
 
 interface PrescanResult {
   factories: Map<string, ReactiveFactoryInfo>
+  /** Factories recognized but declined for inlining (#2325). */
+  declined: Map<string, DeclinedReactiveFactory>
+  /** Module-scope helpers whose body wraps a reactive primitive but whose
+   *  shape is not an inlinable factory (#2325). */
+  reactiveShaped: Set<string>
+  /** Imported destructured-callee names whose helper file was resolved,
+   *  read, and found reactive-free / factory-free (#2325, filled by
+   *  `prescanImportedReactiveFactories`). */
+  cleanFactoryImports: Set<string>
   sourceFile: ts.SourceFile
 }
 
 /**
  * Scan a source string for module-level function declarations that match
- * the reactive-factory shape (single `return [a, b, ...]` exit + at least
- * one reactive primitive call in the body). Returns a map from factory
- * name to its metadata, and the parsed source file for call-site rewriting.
+ * the reactive-factory shape (single `return [a, b, ...]` / `return { a, b
+ * }` exit + at least one reactive primitive call in the body). Returns a
+ * map from factory name to its metadata, and the parsed source file for
+ * call-site rewriting. Also resolves factories defined in a relative-
+ * imported helper file (#2325, see `prescanImportedReactiveFactories`) —
+ * every `analyzeComponent` caller gets cross-file resolution with no call-
+ * site changes elsewhere.
  */
 function prescanReactiveFactoriesInSource(
   source: string,
@@ -3888,11 +3914,25 @@ function prescanReactiveFactoriesInSource(
     ts.ScriptKind.TSX
   )
   const factories = new Map<string, ReactiveFactoryInfo>()
+  const declined = new Map<string, DeclinedReactiveFactory>()
+  const reactiveShaped = new Set<string>()
+  const cleanFactoryImports = new Set<string>()
 
   function visitTop(node: ts.Node): void {
     if (ts.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
+      }
     }
     // Not recursing into function bodies: factory helpers are at module
     // scope only for this round (issue #931 "In scope" §1).
@@ -3900,58 +3940,595 @@ function prescanReactiveFactoriesInSource(
 
   ts.forEachChild(sourceFile, visitTop)
 
-  return { factories, sourceFile }
+  const result: PrescanResult = { factories, declined, reactiveShaped, cleanFactoryImports, sourceFile }
+  prescanImportedReactiveFactories(sourceFile, filePath, result)
+  return result
+}
+
+/**
+ * #2332 — portable component-relative import specifier for a resolved
+ * absolute helper-import target. Same `'.'`/`'./'` prefix convention as the
+ * CLI's buildRelativeImportRewriter (packages/cli/src/lib/build.ts); strips
+ * the resolved extension to match the codebase's extensionless-import
+ * style. Unlike `buildRelativeImportRewriter`, this normalizes
+ * `path.relative`'s separators to POSIX (`/`) — a backslash-separated
+ * specifier is not valid ESM syntax, so on win32 `path.relative`'s native
+ * output would inject a broken import rather than merely an unconventional
+ * one (Copilot review, PR #2338).
+ */
+function toComponentRelativeSpecifier(resolvedAbs: string, componentFilePath: string): string {
+  let rel = path.relative(path.dirname(componentFilePath), resolvedAbs).split(path.sep).join('/')
+  rel = rel.replace(/\.(tsx|ts|jsx|js)$/, '')
+  if (rel === '') rel = '.'
+  if (!rel.startsWith('.')) rel = './' + rel
+  return rel
+}
+
+/**
+ * localName -> identity of what the entry file's own top-level named value
+ * imports bind, for the satisfied-import dedupe check (#2332): if the
+ * component file already imports the exact binding a factory needs to
+ * re-provision, injecting it again would be a duplicate declaration rather
+ * than a shadow, so that case is skipped instead of injected. `targetKey` is
+ * the resolved absolute path for relative sources (or `unresolved:<source>`
+ * when probing fails) and the raw specifier for bare sources.
+ */
+function buildEntryImportIndex(
+  sf: ts.SourceFile,
+  filePath: string
+): Map<string, { targetKey: string; exportedName: string }> {
+  const index = new Map<string, { targetKey: string; exportedName: string }>()
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue
+    if (!ts.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 && ts.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
+}
+
+/**
+ * Every value-binding name anywhere in the entry file (imports, variable
+ * declarations at any depth, function/class/enum names, function
+ * parameters) — used by the #2332 re-provisioned-import collision check
+ * (BF113). Deliberately over-broad: the inlined factory body lands INSIDE a
+ * component function, where any nested binding (params, destructures,
+ * locals) would silently shadow a top-level import injected by this round.
+ * A scan limited to top-level bindings would miss that, so any hit anywhere
+ * in the file declines re-provisioning with a loud BF113 rather than
+ * risking a silent shadow — matching `moduleCaptureCheck`'s stated failure-
+ * direction philosophy (loud build error over silent runtime break).
+ */
+function collectEntryBindingNames(sf: ts.SourceFile): Set<string> {
+  const names = new Set<string>()
+  function visit(node: ts.Node): void {
+    if (ts.isImportDeclaration(node) && node.importClause) {
+      if (node.importClause.name) names.add(node.importClause.name.text)
+      const namedBindings = node.importClause.namedBindings
+      if (namedBindings && ts.isNamedImports(namedBindings)) {
+        // Type-only specifiers still occupy the identifier at the TS level.
+        for (const el of namedBindings.elements) names.add(el.name.text)
+      }
+      if (namedBindings && ts.isNamespaceImport(namedBindings)) {
+        names.add(namedBindings.name.text)
+      }
+    }
+    if (ts.isVariableDeclaration(node)) {
+      const out: string[] = []
+      addBindingNames(node.name, out)
+      for (const n of out) names.add(n)
+    }
+    if (
+      (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isEnumDeclaration(node)) &&
+      node.name
+    ) {
+      names.add(node.name.text)
+    }
+    if (ts.isFunctionLike(node)) {
+      for (const p of node.parameters) {
+        const out: string[] = []
+        addBindingNames(p.name, out)
+        for (const n of out) names.add(n)
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return names
 }
 
+/**
+ * Cross-file half of the factory prescan (#2325 round 2): resolve factories
+ * defined in a relative-imported helper file so `const { count } =
+ * createCounter(0)` inlines the same way whether `createCounter` lives in
+ * this file or in `./hooks`. Mutates `result`'s maps in place.
+ *
+ * Perf: gated on a candidate-callee set collected from the ALREADY-parsed
+ * entry AST (no regex over source text, per CONTRIBUTING.md's "never parse
+ * imports with regex" rule) — files with no tuple/object-destructured call
+ * at all skip every filesystem access below. A second cheap gate (does the
+ * helper file's raw text contain any `REACTIVE_PRIMITIVES` substring) skips
+ * the AST parse of helper files that plainly aren't reactive; this is a
+ * skip-gate over content, not an import parse, so it doesn't run afoul of
+ * that same rule.
+ *
+ * Name-collision precedence: a same-file factory/declined/reactive-shaped
+ * entry always wins over a same-named cross-file import — every write
+ * below is guarded on the name being unclaimed in all three buckets.
+ */
+function prescanImportedReactiveFactories(
+  entrySourceFile: ts.SourceFile,
+  filePath: string,
+  result: PrescanResult
+): void {
+  // 1. Candidate gate: names destructured (tuple or object) from a direct
+  //    call-expression initializer, anywhere in the file. Cheap AST walk,
+  //    no filesystem access.
+  const candidateCallees = new Set<string>()
+  function collectCandidates(node: ts.Node): void {
+    if (
+      ts.isVariableDeclaration(node) &&
+      (ts.isArrayBindingPattern(node.name) || ts.isObjectBindingPattern(node.name)) &&
+      node.initializer &&
+      ts.isCallExpression(node.initializer) &&
+      ts.isIdentifier(node.initializer.expression)
+    ) {
+      candidateCallees.add(node.initializer.expression.text)
+    }
+    ts.forEachChild(node, collectCandidates)
+  }
+  collectCandidates(entrySourceFile)
+  if (candidateCallees.size === 0) return
+
+  // 2. Relative imports whose named specifiers overlap the candidate set.
+  interface CandidateSpec {
+    /** Name exported from the helper file. */
+    exported: string
+    /** Local (call-site) binding name — the key every result map uses. */
+    local: string
+  }
+  const importsToCheck: { src: string; specs: CandidateSpec[] }[] = []
+  for (const stmt of entrySourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue
+    if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue
+    const src = stmt.moduleSpecifier.text
+    // Mirrors `scanImportedClientSignals`'s restriction to relative
+    // specifiers — non-relative (bare/aliased) imports resolve through
+    // bundler / tsconfig-paths configuration this layer doesn't consume.
+    if (!src.startsWith('./') && !src.startsWith('../')) continue
+    if (stmt.importClause?.isTypeOnly) continue
+    const namedBindings = stmt.importClause?.namedBindings
+    if (!namedBindings || !ts.isNamedImports(namedBindings)) continue
+
+    const specs: CandidateSpec[] = []
+    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
+
+  // #2332 — computed once per entry file, shared across all helper files.
+  const entryBindingNames = collectEntryBindingNames(entrySourceFile)
+  const entryImportIndex = buildEntryImportIndex(entrySourceFile, filePath)
+  // localName -> planned injection identity; a later factory requiring the
+  // same name from a DIFFERENT (targetKey, exportedName) is a collision.
+  const plannedInjections = new Map<string, { targetKey: string; exportedName: string }>()
+
+  for (const { src, specs } of importsToCheck) {
+    const resolved = resolveRelativeImportToFile(src, filePath)
+    // Unresolvable — left alone here; the name-heuristic BF110 branch in
+    // validateReactiveFactoryCalls handles it at validation time.
+    if (!resolved) continue
+
+    let content: string
+    try {
+      content = fs.readFileSync(resolved, 'utf8')
+    } catch {
+      continue
+    }
+
+    const alreadyKnown = (name: string): boolean =>
+      result.factories.has(name) || result.declined.has(name) || result.reactiveShaped.has(name)
+
+    // Cheap text-level skip-gate (not an import/JS parse — see docstring):
+    // a helper file with no reactive-primitive substring anywhere cannot
+    // define a reactive factory, so skip parsing it entirely.
+    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 = ts.createSourceFile(
+      resolved + '.prescan',
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX
+    )
+
+    // Map exported name -> module-scope FunctionDeclaration via the AST.
+    const localFns = new Map<string, ts.FunctionDeclaration>()
+    const exportedFns = new Map<string, ts.FunctionDeclaration>()
+    for (const stmt of helperSf.statements) {
+      if (ts.isFunctionDeclaration(stmt) && stmt.name && stmt.body) {
+        localFns.set(stmt.name.text, stmt)
+        const hasExportModifier = stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
+        const hasDefaultModifier = stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false
+        if (hasExportModifier && !hasDefaultModifier) {
+          exportedFns.set(stmt.name.text, stmt)
+        }
+      }
+    }
+    // `export { f }` / `export { f as g }` — keyed by the EXTERNAL export name.
+    for (const stmt of helperSf.statements) {
+      if (
+        ts.isExportDeclaration(stmt) &&
+        stmt.exportClause &&
+        ts.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)
+        }
+      }
+    }
+
+    // Module-scope bindings the helper file declares — an inlined factory
+    // body must not reference any of these (#2325 §4h / BF112), since
+    // inlining moves the body into the component file where they don't
+    // exist.
+    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
+          }
+          // #2332 — re-provision the helper file's own named value imports
+          // that the factory body references, instead of declining. Each
+          // ref resolves to a component-relative specifier (or passes
+          // through unchanged for bare/npm specifiers); a ref already
+          // satisfied by an identical top-level import in the component
+          // file is dropped rather than injected (would redeclare it). A
+          // ref whose local name collides with a DIFFERENT existing/planned
+          // binding declines with BF113 — `pending` is only merged into
+          // `plannedInjections` on full factory success (§3.4), so a
+          // factory that declines mid-loop reserves nothing.
+          const required: RequiredFactoryImport[] = []
+          const pending: Array<[string, { targetKey: string; exportedName: string }]> = []
+          let declinedEntry: DeclinedReactiveFactory | null = null
+          for (const ref of capture.importedRefs) {
+            let specifier: string
+            let targetKey: string
+            if (ref.source.startsWith('./') || ref.source.startsWith('../')) {
+              // Resolve from the HELPER file's directory (`resolved` is its
+              // absolute path). Unresolvable → same posture as a local
+              // capture: nothing importable to re-provision (BF112).
+              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 // bare/npm specifier — unchanged (#2332 test 2)
+              targetKey = ref.source
+            }
+            // Already satisfied by an identical top-level import in the
+            // component file — injecting again would redeclare the binding.
+            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
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Value bindings at the helper file's module scope, split by whether they
+ * have a re-importable module of their own (#2332).
+ *
+ * `local` bindings — top-level const/let/var, function/class/enum names,
+ * plus default-import and namespace-import names — have no module a
+ * component file could re-import them from, so an inlined factory body
+ * referencing one unconditionally declines with BF112 (#2325 §4h): moving
+ * the body into the component file would leave a dangling reference.
+ *
+ * `imported` bindings — the helper file's own named value imports — CAN be
+ * re-provisioned: the component file can import the same binding under the
+ * same specifier (#2332). These are collected here (keyed by the helper
+ * file's local name) but are NOT captures; `moduleCaptureCheck` below
+ * reports them separately from `local` hits so the caller can decide
+ * whether to re-import rather than unconditionally decline.
+ *
+ * EXCEPT in both cases: imports from '@barefootjs/client' /
+ * '@barefootjs/client/runtime'. Those are re-provisioned from usage by the
+ * client-JS emitter regardless of where the call that used them textually
+ * came from (`resolveFinalImports` / `detectUsedImports` regex-scan the
+ * *generated* code, not the consumer's source imports — see #2325 spec C1),
+ * so an inlined body calling `createSignal` is never a capture even though
+ * the helper file itself imports it. Type-only imports/declarations carry
+ * no runtime binding and are excluded.
+ */
+interface HelperModuleBindings {
+  /** Declared directly in the helper file — unconditional BF112 capture. */
+  local: Set<string>
+  /** Named value-import specifiers, keyed by helper-file local name —
+   *  re-provisionable into the component file (#2332). */
+  imported: Map<string, { source: string; exportedName: string }>
+}
+
+function collectHelperModuleValueBindings(sf: ts.SourceFile): HelperModuleBindings {
+  const local = new Set<string>()
+  const imported = new Map<string, { source: string; exportedName: string }>()
+  for (const stmt of sf.statements) {
+    if (ts.isVariableStatement(stmt)) {
+      const out: string[] = []
+      for (const decl of stmt.declarationList.declarations) {
+        addBindingNames(decl.name, out)
+      }
+      for (const n of out) local.add(n)
+      continue
+    }
+    if (
+      (ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)) &&
+      stmt.name
+    ) {
+      local.add(stmt.name.text)
+      continue
+    }
+    if (ts.isImportDeclaration(stmt)) {
+      if (stmt.importClause?.isTypeOnly) continue
+      if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue
+      const src = stmt.moduleSpecifier.text
+      if (src === '@barefootjs/client' || src === '@barefootjs/client/runtime') continue
+      // Default/namespace imports stay hard BF112 (#2332 scope decision):
+      // no single named export to re-provision under one local name.
+      if (stmt.importClause?.name) local.add(stmt.importClause.name.text)
+      const namedBindings = stmt.importClause?.namedBindings
+      if (namedBindings && ts.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 && ts.isNamespaceImport(namedBindings)) {
+        local.add(namedBindings.name.text)
+      }
+    }
+  }
+  return { local, imported }
+}
+
+/**
+ * Categorized free-identifier references of a reactive-factory body into
+ * its own module scope (#2332): `captured` are unconditional BF112 hits
+ * (helper-local bindings — the body would dangle if inlined verbatim);
+ * `importedRefs` are references to the helper file's own named value
+ * imports, which the caller may re-provision into the component file
+ * instead of declining (§3.4 in the #2332 spec).
+ */
+interface ModuleCaptureResult {
+  /** Free refs resolving to helper-local bindings (BF112), sorted. */
+  captured: string[]
+  /** Free refs resolving to the helper's own named value imports, sorted by localName. */
+  importedRefs: Array<{ localName: string; source: string; exportedName: string }>
+}
+
+/**
+ * Free identifiers of a reactive-factory body that resolve to bindings at
+ * its own module scope (#2325 §4h / BF112, #2332) — references the inlined
+ * body would silently lose once spliced into the component file, unless
+ * re-provisioned as an import. Returns `captured` (unconditional BF112) and
+ * `importedRefs` (re-provisionable) separately, each sorted for stable
+ * diagnostic/injection text.
+ *
+ * Known accepted limitation: `extractFreeIdentifiersFromNode` only scope-
+ * tracks arrow-function parameters, not nested `function` declarations'
+ * parameters or nested-block declarations — a body-nested binding that
+ * happens to shadow a helper-module binding could false-positive into
+ * BF112 or `importedRefs`. Acceptable: the failure direction is always a
+ * loud build error (BF112/BF113) or a redundant-but-harmless injected
+ * import, never a silent dangling reference.
+ */
+function moduleCaptureCheck(
+  fn: ts.FunctionDeclaration,
+  info: ReactiveFactoryInfo,
+  moduleBindings: HelperModuleBindings,
+  selfName: string
+): ModuleCaptureResult {
+  if (!fn.body) return { captured: [], importedRefs: [] }
+  const free = extractFreeIdentifiersFromNode(fn.body)
+  const exclude = new Set<string>(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: string[] = []
+  const importedRefs: ModuleCaptureResult['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 }
+}
+
+/**
+ * Classification result for a module-level function that might be a
+ * reactive-factory helper (#2325). `null` means the function has no
+ * reactive-primitive call anywhere in its body, so it isn't reactive-
+ * related at all — every other case implies at least one such call.
+ */
+type FactoryDetection =
+  | { kind: 'factory'; info: ReactiveFactoryInfo }
+  | { kind: 'declined'; declined: DeclinedReactiveFactory }
+  | { kind: 'reactive-shaped' } // wraps a reactive primitive but shape unsupported
+  | null
+
 function detectReactiveFactory(
   node: ts.FunctionDeclaration,
   sourceFile: ts.SourceFile,
   filePath: string
-): ReactiveFactoryInfo | null {
+): FactoryDetection {
   if (!node.body || !node.name) return null
 
-  // Require: exactly one top-level `return` whose argument is an array
-  // literal of plain identifiers (optionally wrapped in `as const` / parens).
-  let tupleReturn: ts.ArrayLiteralExpression | null = null
+  // Body must contain at least one reactive primitive call so that the
+  // factory is actually the right thing to inline (not just a helper that
+  // happens to look similar). Checked FIRST: a function with zero reactive
+  // calls is not reactive-related in any way, so it is out of scope for
+  // every diagnostic below, not just "not a factory".
+  let hasReactiveCall = false
+  function checkForReactive(n: ts.Node): void {
+    if (hasReactiveCall) return
+    if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) &&
+        REACTIVE_PRIMITIVES.has(n.expression.text)) {
+      hasReactiveCall = true
+      return
+    }
+    ts.forEachChild(n, checkForReactive)
+  }
+  checkForReactive(node.body)
+  if (!hasReactiveCall) return null
+
+  const loc = getSourceLocation(node, sourceFile, filePath)
+
+  // Require exactly one top-level `return`, whose argument (after unwrapping
+  // parens / `as const` / type-assertion) is a tuple (array literal) or a
+  // shorthand-object literal.
+  let returnExpr: ts.Expression | null = null
   let returnCount = 0
   for (const stmt of node.body.statements) {
     if (!ts.isReturnStatement(stmt)) continue
     returnCount++
-    if (!stmt.expression) return null
+    if (!stmt.expression) return { kind: 'reactive-shaped' }
     let expr: ts.Expression = stmt.expression
     while (ts.isParenthesizedExpression(expr)) expr = expr.expression
     // Accept `... as const` / `<const>...`
     if (ts.isAsExpression(expr)) expr = expr.expression
     if (ts.isTypeAssertionExpression(expr)) expr = expr.expression
-    if (!ts.isArrayLiteralExpression(expr)) return null
-    tupleReturn = expr
+    returnExpr = expr
   }
-  if (returnCount !== 1 || !tupleReturn) return null
+  if (returnCount !== 1 || !returnExpr) return { kind: 'reactive-shaped' }
 
-  // Every element must be a plain identifier (no spreads, computed,
-  // call expressions). Otherwise the caller-side rename would not be sound.
   const returnTupleIdentifiers: string[] = []
-  for (const el of tupleReturn.elements) {
-    if (!ts.isIdentifier(el)) return null
-    returnTupleIdentifiers.push(el.text)
-  }
-  if (returnTupleIdentifiers.length === 0) return null
-
-  // Body must contain at least one reactive primitive call so that the
-  // factory is actually the right thing to inline (not just a tuple-returning
-  // helper that happens to look similar).
-  let hasReactiveCall = false
-  function checkForReactive(n: ts.Node): void {
-    if (hasReactiveCall) return
-    if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) &&
-        REACTIVE_PRIMITIVES.has(n.expression.text)) {
-      hasReactiveCall = true
-      return
+  let returnKind: 'tuple' | 'object'
+
+  if (ts.isArrayLiteralExpression(returnExpr)) {
+    returnKind = 'tuple'
+    // Every element must be a plain identifier (no spreads, computed,
+    // call expressions). Otherwise the caller-side rename would not be sound.
+    for (const el of returnExpr.elements) {
+      if (!ts.isIdentifier(el)) return { kind: 'reactive-shaped' }
+      returnTupleIdentifiers.push(el.text)
     }
-    ts.forEachChild(n, checkForReactive)
+    if (returnTupleIdentifiers.length === 0) return { kind: 'reactive-shaped' }
+  } else if (ts.isObjectLiteralExpression(returnExpr)) {
+    returnKind = 'object'
+    const hasNonShorthand = returnExpr.properties.some(p => !ts.isShorthandPropertyAssignment(p))
+    if (hasNonShorthand) {
+      return {
+        kind: 'declined',
+        declined: {
+          code: 'BF111',
+          detail: `return object of '${node.name.text}' uses non-shorthand properties`,
+          loc,
+        },
+      }
+    }
+    for (const p of returnExpr.properties) {
+      // Every property already proven ts.isShorthandPropertyAssignment above.
+      returnTupleIdentifiers.push((p as ts.ShorthandPropertyAssignment).name.text)
+    }
+    if (returnTupleIdentifiers.length === 0) return { kind: 'reactive-shaped' }
+  } else {
+    return { kind: 'reactive-shaped' }
   }
-  checkForReactive(node.body)
-  if (!hasReactiveCall) return null
 
   // Collect local bindings in the factory body for identifier hygiene at
   // inlining time. Only direct-child declarations of the block are
@@ -3968,26 +4545,35 @@ function detectReactiveFactory(
   }
 
   // Serialize the body without the outer braces and without the return
-  // statement — the return tuple is dissolved into caller-named identifiers.
+  // statement — the return tuple/object is dissolved into caller-named
+  // identifiers.
   const bodyStatements = node.body.statements
     .filter(s => !ts.isReturnStatement(s))
     .map(s => s.getText(sourceFile))
     .join('\n')
 
-  const params = node.parameters.map(p => {
-    if (ts.isIdentifier(p.name)) return p.name.text
+  const params: string[] = []
+  for (const p of node.parameters) {
+    if (ts.isIdentifier(p.name)) {
+      params.push(p.name.text)
+      continue
+    }
     // Destructured params are uncommon for this helper shape and out of
-    // initial scope; return a placeholder so we can skip the factory.
-    return ''
-  })
-  if (params.some(p => p === '')) return null
+    // initial scope; the factory still wraps a reactive primitive, so
+    // classify it as reactive-shaped rather than silently ignoring it.
+    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,
+    },
   }
 }
 
@@ -4029,6 +4615,12 @@ function rewriteFactoryCallsInSource(
   type Edit = { start: number; end: number; replacement: string }
   const edits: Edit[] = []
   let callSiteIndex = 0
+  // #2332 — factories actually inlined in this walk (not merely present in
+  // `prescan.factories`; `maybeRewriteDecl` bails on arity mismatch/omitted
+  // elements/rename destructures without inlining), so their
+  // `requiredImports` can be re-provisioned without adding a dead import
+  // for a factory that was never actually spliced in.
+  const inlinedFactories = new Set<ReactiveFactoryInfo>()
 
   function visitStmt(node: ts.Node, inComponent: boolean): void {
     if (ts.isVariableStatement(node) && inComponent) {
@@ -4048,16 +4640,33 @@ function rewriteFactoryCallsInSource(
   }
 
   function maybeRewriteDecl(stmt: ts.VariableStatement, decl: ts.VariableDeclaration): void {
-    if (!ts.isArrayBindingPattern(decl.name)) return
     if (!decl.initializer || !ts.isCallExpression(decl.initializer)) return
     if (!ts.isIdentifier(decl.initializer.expression)) return
     const factoryName = decl.initializer.expression.text
     const factory = factories.get(factoryName)
     if (!factory) return
 
+    if (ts.isArrayBindingPattern(decl.name)) {
+      if (factory.returnKind !== 'tuple') return
+      rewriteTupleDecl(stmt, decl.name, decl.initializer, factory)
+      return
+    }
+    if (ts.isObjectBindingPattern(decl.name)) {
+      if (factory.returnKind !== 'object') return
+      rewriteObjectDecl(stmt, decl.name, decl.initializer, factory)
+      return
+    }
+  }
+
+  function rewriteTupleDecl(
+    stmt: ts.VariableStatement,
+    pattern: ts.ArrayBindingPattern,
+    call: ts.CallExpression,
+    factory: ReactiveFactoryInfo
+  ): void {
     // Arity check — bail out on mismatch so the analyzer can report BF110
     // on the untouched source.
-    const elements = decl.name.elements
+    const elements = pattern.elements
     if (elements.length !== factory.returnTupleIdentifiers.length) return
 
     // Caller-side identifier names (one per tuple slot). Omitted slots
@@ -4069,17 +4678,74 @@ function rewriteFactoryCallsInSource(
       callerNames.push(el.name.text)
     }
 
-    const argTexts = decl.initializer.arguments.map(a => a.getText(sourceFile))
+    // Exclude params + every return-tuple identifier from suffix-renaming
+    // (they're renamed to caller names below instead).
+    const excludeFromSuffixRename = new Set<string>(factory.params)
+    for (const r of factory.returnTupleIdentifiers) excludeFromSuffixRename.add(r)
+
+    const renameReturnToCallerNames = new Map<string, string>()
+    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: ts.VariableStatement,
+    pattern: ts.ObjectBindingPattern,
+    call: ts.CallExpression,
+    factory: ReactiveFactoryInfo
+  ): void {
+    // Shorthand destructuring only (no renames/defaults/rest) of names the
+    // factory actually returns. Anything else bails so the analyzer can
+    // report BF110/BF111 on the untouched source. Subset destructures are
+    // allowed — a caller may destructure fewer than all returned names.
+    const destructured = new Set<string>()
+    for (const el of pattern.elements) {
+      if (el.dotDotDotToken) return
+      if (el.propertyName) return
+      if (el.initializer) return
+      if (!ts.isIdentifier(el.name)) return
+      if (!factory.returnTupleIdentifiers.includes(el.name.text)) return
+      destructured.add(el.name.text)
+    }
+
+    // Exclude params + the destructured names from suffix-renaming (caller
+    // name already equals the property name under shorthand, C4). Returned
+    // names the caller did NOT destructure are ordinary internal locals and
+    // DO get suffix-renamed — otherwise two subset calls of the same
+    // factory collide on the undestructured name.
+    const excludeFromSuffixRename = new Set<string>(factory.params)
+    for (const d of destructured) excludeFromSuffixRename.add(d)
+
+    // No return-name→caller-name rename step: identity under shorthand.
+    inlineFactoryCallAtSite(stmt, factory, call.arguments, excludeFromSuffixRename, null)
+  }
+
+  /**
+   * Shared inlining tail for both return shapes: suffix-rename internal
+   * bindings not in `excludeFromSuffixRename`, splice argument expressions
+   * in for parameters, optionally rename return identifiers to caller
+   * names (tuple path only — see C4 for why the object path passes null),
+   * and push the resulting edit for this call site.
+   */
+  function inlineFactoryCallAtSite(
+    stmt: ts.VariableStatement,
+    factory: ReactiveFactoryInfo,
+    args: ts.NodeArray<ts.Expression>,
+    excludeFromSuffixRename: Set<string>,
+    renameReturnToCallerNames: Map<string, string> | null
+  ): void {
+    const argTexts = args.map(a => a.getText(sourceFile))
     const thisCallIndex = callSiteIndex++
     const suffix = `_bf${thisCallIndex}`
 
     // Apply renames to the factory body source.
     let body = factory.bodySource
-    // 1. Suffix-rename internal bindings (exclude params + return tuple
-    //    + caller names to avoid collisions).
+    // 1. Suffix-rename internal bindings.
     const internalRenames = new Set<string>(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)
     }
@@ -4094,11 +4760,11 @@ function rewriteFactoryCallsInSource(
       const wrapped = atomicArg.test(a.trim()) ? a.trim() : `(${a})`
       body = body.replace(new RegExp(`\\b${escapeRegex(p)}\\b`, 'g'), wrapped)
     }
-    // 3. Return tuple identifiers → caller destructure names.
-    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)
+    // 3. Return identifiers → caller destructure names (tuple path only).
+    if (renameReturnToCallerNames) {
+      for (const [n, caller] of renameReturnToCallerNames) {
+        body = body.replace(new RegExp(`\\b${escapeRegex(n)}\\b`, 'g'), caller)
+      }
     }
 
     edits.push({
@@ -4106,13 +4772,51 @@ function rewriteFactoryCallsInSource(
       end: stmt.getEnd(),
       replacement: body,
     })
+    inlinedFactories.add(factory)
   }
 
   visitStmt(sourceFile, false)
 
   if (edits.length === 0) return source
 
-  // Apply edits from bottom to top so earlier offsets stay valid.
+  // #2332 — one deduped import statement per specifier for every inlined
+  // cross-file factory's re-provisioned imports. Injected as a zero-width
+  // edit so the ordinary bottom-to-top splice below applies it; the result
+  // is indistinguishable from a hand-written import for every downstream
+  // consumer (ctx.imports → SSR templateImports AND client
+  // collectExternalImports both parse this same rewritten string).
+  const importsBySpecifier = new Map<string, Map<string, string>>() // specifier -> localName -> exportedName
+  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) // same-key duplicates are identical by prescan construction
+    }
+  }
+  if (importsBySpecifier.size > 0) {
+    // Sort specifiers and, within each, named-import entries by local name —
+    // `importsBySpecifier`/`inlinedFactories` iterate in incidental AST-
+    // traversal/insertion order, which would otherwise make this generated
+    // text order-unstable across unrelated refactors (Copilot review, PR
+    // #2338).
+    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('\n') + '\n' : '\n' + lines.join('\n') })
+  }
+
+  // Apply edits from bottom to top so earlier offsets stay valid. A factory
+  // with `requiredImports` is by definition imported, so the entry file has
+  // at least one import statement and `at` above lands strictly inside the
+  // import prologue — every call-site edit's start is strictly greater
+  // (separated at minimum by the statement break after the last import), so
+  // starts never tie and no sort tiebreak is needed.
   edits.sort((a, b) => b.start - a.start)
   let out = source
   for (const e of edits) {
@@ -4121,6 +4825,24 @@ function rewriteFactoryCallsInSource(
   return out
 }
 
+/**
+ * Offset just after the last top-level import (else after the 'use client'
+ * directive, else 0) in the prescan source file — where re-provisioned
+ * factory imports are injected (#2332).
+ */
+function factoryImportInsertionOffset(sf: ts.SourceFile): number {
+  let lastImportEnd = -1
+  let directiveEnd = -1
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt)) { lastImportEnd = stmt.getEnd(); continue }
+    if (directiveEnd === -1 && ts.isExpressionStatement(stmt) &&
+        ts.isStringLiteral(stmt.expression) && stmt.expression.text === 'use client') {
+      directiveEnd = stmt.getEnd()
+    }
+  }
+  return lastImportEnd >= 0 ? lastImportEnd : directiveEnd >= 0 ? directiveEnd : 0
+}
+
 function isPascalCaseComponentFn(node: ts.Node): boolean {
   if (ts.isFunctionDeclaration(node) && node.name) {
     return /^[A-Z]/.test(node.name.text)
@@ -4140,10 +4862,54 @@ function escapeRegex(s: string): string {
 // =============================================================================
 
 /**
- * Scan a compiled component context for tuple-destructures whose callee is
- * neither `createSignal` / `createMemo` nor an inlinable reactive factory.
- * These are the silent-failure shapes that produced broken client JS prior
- * to factory inlining — emit BF110 so users get a clear message instead.
+ * Build the diagnostic for a call site whose callee was recognised but
+ * declined for inlining (#2325 — cross-file factories that rename their
+ * return properties or capture their own module scope; #2332 — a
+ * re-provisioned helper import collides with an existing binding). BF112
+ * and BF113's wording is specific to their respective failure; every other
+ * declined reason (currently only BF111 — non-shorthand return properties)
+ * shares BF111's generic "cannot be inlined: <detail>" phrasing, matching
+ * the wording used for the tuple call-site path.
+ */
+function declinedFactoryMessage(callee: string, d: DeclinedReactiveFactory): string {
+  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}.`
+}
+
+/** Diagnostic code for a declined reactive-factory call site (#2325 / #2332). */
+function declinedFactoryErrorCode(code: DeclinedReactiveFactory['code']): ErrorCode {
+  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
+  }
+}
+
+/**
+ * Scan a compiled component context for destructures (tuple or object)
+ * whose callee is neither `createSignal` / `createMemo` nor an inlinable
+ * reactive factory. These are the silent-failure shapes that produced
+ * broken client JS prior to factory inlining — emit BF110 (unrecognised
+ * shape), BF111 (unsupported rename), or BF112 (module-scope capture) so
+ * users get a clear message instead.
+ *
+ * Only walks top-level component-body statements, matching the scope the
+ * inliner itself operates on (#931) — a factory call inside a nested block
+ * is out of scope for both inlining and this diagnostic.
  */
 export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
   if (!ctx.componentNode) return
@@ -4155,44 +4921,197 @@ export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
   for (const stmt of body.statements) {
     if (!ts.isVariableStatement(stmt)) continue
     for (const decl of stmt.declarationList.declarations) {
-      if (!ts.isArrayBindingPattern(decl.name)) continue
       if (!decl.initializer || !ts.isCallExpression(decl.initializer)) continue
       if (!ts.isIdentifier(decl.initializer.expression)) continue
       const callee = decl.initializer.expression.text
-      if (callee === 'createSignal' || callee === 'createMemo') continue
-      // Env-signal factories (`createSearchParams`, #2057) are `createSignal`-
-      // shaped and recognised structurally — a valid tuple destructure. Resolve
-      // via the same path as recognition (`resolveEnvSignalKey`) so an aliased
-      // import (`import { createSearchParams as csp }`) is accepted here too,
-      // rather than falling through to a spurious BF110.
-      if (resolveEnvSignalKey(decl.initializer, ctx)) continue
-      // Inlined factories were rewritten away before this analysis, so
-      // anything still matching the shape is a destructure of an
-      // unrecognised callee (imported helper, ad-hoc tuple fn, factory
-      // with arity mismatch).
-      ctx.errors.push(
-        createError(
-          ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY,
-          getSourceLocation(stmt, ctx.sourceFile, ctx.filePath),
-          {
+      const loc = getSourceLocation(stmt, ctx.sourceFile, ctx.filePath)
+
+      if (ts.isArrayBindingPattern(decl.name)) {
+        if (callee === 'createSignal' || callee === 'createMemo') continue
+        // Env-signal factories (`createSearchParams`, #2057) are `createSignal`-
+        // shaped and recognised structurally — a valid tuple destructure. Resolve
+        // via the same path as recognition (`resolveEnvSignalKey`) so an aliased
+        // import (`import { createSearchParams as csp }`) is accepted here too,
+        // rather than falling through to a spurious BF110.
+        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:
-              `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: {
+              `'${callee}' is a reactive factory that returns an object — destructure ` +
+              `it with a matching object pattern: const { ${objectFactory.returnTupleIdentifiers.join(', ')} } = ${callee}(...)`,
+          }))
+          continue
+        }
+
+        // Inlined factories were rewritten away before this analysis, so
+        // anything still matching the shape is a destructure of an
+        // unrecognised callee (imported helper, ad-hoc tuple fn, factory
+        // with arity mismatch).
+        ctx.errors.push(
+          createError(
+            ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY,
+            loc,
+            {
+              severity: 'error',
               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.`,
-            },
-          }
+                `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
+      }
+
+      if (ts.isObjectBindingPattern(decl.name)) {
+        validateObjectFactoryDestructure(ctx, decl.name, callee, loc)
+      }
     }
   }
 }
 
+/**
+ * Object-destructure half of `validateReactiveFactoryCalls` (#2325). Split
+ * out so the tuple path above stays a straight read of the pre-#2325 logic
+ * (the tuple diagnostics are pinned by pre-existing tests) while this path
+ * covers the previously-silent object-destructure failure modes: an
+ * unrecognised callee, a tuple factory destructured as an object, a rename/
+ * default/rest destructure of a shorthand-only factory, an unknown
+ * property, a declined (BF111/BF112/BF113) factory, or an uninspectable
+ * import that looks reactive-factory-shaped by name.
+ */
+function validateObjectFactoryDestructure(
+  ctx: AnalyzerContext,
+  pattern: ts.ObjectBindingPattern,
+  callee: string,
+  loc: SourceLocation
+): void {
+  const factory = ctx.reactiveFactories.get(callee)
+  if (factory) {
+    // Return-shape mismatch takes priority over element-form validation: a
+    // tuple-return factory destructured as an object is *never* valid,
+    // regardless of whether the object pattern happens to use shorthand or
+    // a rename/default/rest element — always point the caller at positional
+    // destructuring (BF110) instead of the shorthand-only guidance below
+    // (BF111), which only makes sense for genuinely object-return factories.
+    if (factory.returnKind === 'tuple') {
+      ctx.errors.push(createError(ErrorCodes.UNRECOGNIZED_REACTIVE_FACTORY, loc, {
+        severity: 'error',
+        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 || !ts.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 => (ts.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
+    }
+
+    // Shorthand object pattern that matches the factory's return shape —
+    // already inlined; nothing to report.
+    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
+  }
+
+  // Proven non-reactive import (helper file resolved, read, and found to
+  // export nothing reactive-shaped under this name) — silent, correctly
+  // (C2: an ordinary object destructure must not become a false positive).
+  if (ctx.cleanFactoryImports.has(callee)) return
+
+  // Last resort: an import the compiler cannot inspect (non-relative or
+  // unresolvable path) whose name looks like a hook/factory. Name-based
+  // heuristic only — false negatives here fall through to silence, which
+  // matches this file's ordinary-object-destructure default (C2).
+  let matchedImportSource: string | null = 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.`,
+    }))
+  }
+  // Otherwise: ordinary object destructure of unrelated code — leave untouched (C2).
+}
+
 // =============================================================================
 // Export
 // =============================================================================