@barefootjs/jsx 0.24.1 → 0.26.0

package/src/analyzer.ts

@@ -7,7 +7,7 @@
  */
 
 import ts from 'typescript'
-import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, SourceLocation } from './types.ts'
+import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation } from './types.ts'
 import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
 import { incrementCounter } from './instrumentation.ts'
@@ -2542,6 +2542,59 @@ export function extractFreeIdentifiersFromNode(node: ts.Node): Set<string> {
   return ids
 }
 
+/**
+ * Identifiers referenced in TYPE position anywhere under `node` (#2350) —
+ * the mirror image of `extractFreeIdentifiersFromNode`, which explicitly
+ * skips type nodes since they carry no runtime reference. Walks the whole
+ * tree without stopping at type nodes; every `TypeReferenceNode`'s root
+ * name is collected, which by plain `forEachChild` recursion also reaches
+ * nested references (generic type arguments, array/union/tuple members,
+ * function-type params/returns) without needing to special-case each shape.
+ * Also collects `TypeQueryNode` (`typeof Foo`) root names — `Foo` there is
+ * a VALUE reference in type position, so `moduleCaptureCheck`'s fallback to
+ * `moduleBindings.imported`/`local` (added for the plain-value-import case,
+ * Copilot review, PR #2351) resolves it the same way (Copilot review, PR
+ * #2351).
+ * A function-like node's own type parameters (`<T>`) are tracked and
+ * excluded within its body/signature, same idea as the value walker's
+ * arrow-parameter tracking — otherwise a generic named the same as a
+ * module-scope type (`function useThing<SavedList>(x: SavedList)`) would
+ * be misclassified as a reference to the import (Copilot review, PR
+ * #2351). Doesn't exclude body-local type/interface declarations that
+ * shadow a module-scope name — rare enough here that, per this file's
+ * accepted-limitation policy, a redundant-but-harmless re-provisioned
+ * import is an acceptable outcome (never a silent dangling reference).
+ */
+function extractFreeTypeIdentifiersFromNode(node: ts.Node): Set<string> {
+  const ids = new Set<string>()
+  const boundTypeParams = new Set<string>()
+  function rootName(name: ts.EntityName): ts.Identifier {
+    return ts.isQualifiedName(name) ? rootName(name.left) : name
+  }
+  function visit(n: ts.Node): void {
+    if (ts.isTypeReferenceNode(n)) {
+      const name = rootName(n.typeName).text
+      if (!boundTypeParams.has(name)) ids.add(name)
+      // Keep descending — nested references (`Promise<SavedList>`,
+      // `Record<string, SavedList>`) live in this same node's type arguments.
+    }
+    if (ts.isTypeQueryNode(n)) {
+      const name = rootName(n.exprName).text
+      if (!boundTypeParams.has(name)) ids.add(name)
+    }
+    if (ts.isFunctionLike(n) && n.typeParameters && n.typeParameters.length > 0) {
+      const names = n.typeParameters.map((p) => p.name.text)
+      for (const p of names) boundTypeParams.add(p)
+      ts.forEachChild(n, visit)
+      for (const p of names) boundTypeParams.delete(p)
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+  return ids
+}
+
 /**
  * Check if a const initializer expression contains JSX at a non-root
  * position — ternary with JSX on either side, logical-AND / OR /
@@ -3965,32 +4018,40 @@ function toComponentRelativeSpecifier(resolvedAbs: string, componentFilePath: st
 }
 
 /**
- * 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.
+ * localName -> identity of what the entry file's own top-level named
+ * imports bind, for the satisfied-import dedupe check (#2332, type-only
+ * imports included #2350): 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. `isTypeOnly` matters at the call site: an
+ * existing type-only import satisfies a factory's type-only need but NOT a
+ * value need (it has no runtime binding) — treating it as satisfying both
+ * would silently skip re-provisioning a value the inlined body actually
+ * calls, the same dangling-reference failure #2341 BUG-2 already covers.
  */
 function buildEntryImportIndex(
   sf: ts.SourceFile,
   filePath: string
-): Map<string, { targetKey: string; exportedName: string }> {
-  const index = new Map<string, { targetKey: string; exportedName: string }>()
+): Map<string, { targetKey: string; exportedName: string; isTypeOnly: boolean }> {
+  const index = new Map<string, { targetKey: string; exportedName: string; isTypeOnly: boolean }>()
   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 wholeTypeOnly = stmt.importClause?.isTypeOnly === true
     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 })
+        index.set(el.name.text, {
+          targetKey,
+          exportedName: (el.propertyName ?? el.name).text,
+          isTypeOnly: wholeTypeOnly || el.isTypeOnly,
+        })
       }
     }
   }
@@ -4034,6 +4095,9 @@ function collectEntryBindingNames(sf: ts.SourceFile): Set<string> {
     ) {
       names.add(node.name.text)
     }
+    if ((ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)) && node.name) {
+      names.add(node.name.text)
+    }
     if (ts.isFunctionLike(node)) {
       for (const p of node.parameters) {
         const out: string[] = []
@@ -4047,18 +4111,56 @@ function collectEntryBindingNames(sf: ts.SourceFile): Set<string> {
   return names
 }
 
+// One `export ... from` hop is followed when resolving a re-exported name
+// (#2341 BUG-2) — a visited-set guards against cycles regardless, so
+// raising this later is safe without further changes.
+const MAX_REEXPORT_HOPS = 1
+
+/** A helper file's export surface, cached per absolute path for the
+ *  lifetime of one `prescanImportedReactiveFactories` call (#2341 BUG-2). */
+interface HelperFileInfo {
+  sf: ts.SourceFile
+  /** Module-scope function declarations exported under their external name
+   *  (own `export function`, or a local `export { f as g }`). */
+  exportedFns: Map<string, ts.FunctionDeclaration>
+  /** `export { a as b } from 'src'` re-exports, keyed by the EXTERNAL name
+   *  `b` — a barrel file's whole reason for existing (#2341 BUG-2). */
+  reexports: Map<string, { source: string; innerName: string }>
+  /** Any `export * from '...'` in this file — a named lookup that misses
+   *  `exportedFns`/`reexports` might still resolve through one of these, so
+   *  it can never be classified `'clean'`. (`export * as ns from` is a
+   *  `NamespaceExport` clause and is excluded: a named lookup can never
+   *  come through it.) */
+  hasStarReexport: boolean
+  moduleBindings: HelperModuleBindings
+}
+/** `'clean'` = read, parsed (or gate-skipped), and proven to define no
+ *  reactive factory under any name reachable from it. `null` = unreadable. */
+type LoadedHelper = HelperFileInfo | 'clean' | null
+type ExportLookup =
+  | { kind: 'fn'; fn: ts.FunctionDeclaration; file: HelperFileInfo; definingPath: string }
+  | { kind: 'clean' } // proven non-reactive under this name → cleanFactoryImports
+  | { kind: 'unknown' } // cannot prove → leave unclassified so the BF110 name heuristic still fires
+
 /**
  * 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.
+ * this file or in `./hooks`. Follows one `export ... from` hop so a barrel
+ * `index.ts` re-exporting the real helper resolves to the file that
+ * actually DEFINES it (#2341 BUG-2) — every classification (factory /
+ * declined / reactive-shaped / clean) and every downstream anchor (module-
+ * capture check, helper-import re-provisioning, `sourceFilePath`) is keyed
+ * off that defining file, never the barrel. 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
+ * helper file's raw text contain any `REACTIVE_PRIMITIVES` substring, or
+ * any `export ... from` re-export text) skips the AST parse of helper files
+ * that plainly define no factory and re-export nothing; this is a
  * skip-gate over content, not an import parse, so it doesn't run afoul of
  * that same rule.
  *
@@ -4127,47 +4229,48 @@ function prescanImportedReactiveFactories(
   const entryImportIndex = buildEntryImportIndex(entrySourceFile, filePath)
   // localName -> planned injection identity; a later factory requiring the
   // same name from a DIFFERENT (targetKey, exportedName) is a collision.
+  // Deliberately isTypeOnly-agnostic: a value need and a type need for the
+  // SAME (targetKey, exportedName) aren't a real collision (the eventual
+  // value import satisfies both) — the final line-generation step below
+  // drops the redundant type-only line rather than declining here.
   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
+  // #2341 BUG-2 — one read+parse per helper file per entry file, memoized
+  // across every spec/hop that touches it (a barrel is typically visited
+  // once per re-exported name it satisfies).
+  const helperCache = new Map<string, LoadedHelper>()
+
+  function loadHelperFile(abs: string): LoadedHelper {
+    const cached = helperCache.get(abs)
+    if (cached !== undefined) return cached
 
     let content: string
     try {
-      content = fs.readFileSync(resolved, 'utf8')
+      content = fs.readFileSync(abs, 'utf8')
     } catch {
-      continue
+      helperCache.set(abs, null)
+      return null
     }
 
-    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.
+    // a file with no reactive-primitive substring AND no re-export gate
+    // text (`export` ... `from`) can neither define a reactive factory nor
+    // re-export one, so skip parsing it entirely. Substring checks only —
+    // false positives merely cause an AST parse whose outcome is still
+    // correct, they never cause a false 'clean'.
     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 hasReexportText = content.includes('export') && content.includes('from')
+    if (!hasAnyPrimitiveText && !hasReexportText) {
+      helperCache.set(abs, 'clean')
+      return 'clean'
     }
 
-    const helperSf = ts.createSourceFile(
-      resolved + '.prescan',
-      content,
-      ts.ScriptTarget.Latest,
-      true,
-      ts.ScriptKind.TSX
-    )
+    const sf = ts.createSourceFile(abs + '.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) {
+    for (const stmt of sf.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
@@ -4177,20 +4280,37 @@ function prescanImportedReactiveFactories(
         }
       }
     }
-    // `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
-      ) {
+
+    const reexports = new Map<string, { source: string; innerName: string }>()
+    let hasStarReexport = false
+    for (const stmt of sf.statements) {
+      if (!ts.isExportDeclaration(stmt) || stmt.isTypeOnly) continue
+      if (!stmt.moduleSpecifier) {
+        // `export { f }` / `export { f as g }` — keyed by the EXTERNAL export name.
+        if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+          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)
+          }
+        }
+        continue
+      }
+      if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue
+      if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+        // `export { a as b } from 'src'` — keyed by the EXTERNAL name `b`.
         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)
+          reexports.set(el.name.text, {
+            source: stmt.moduleSpecifier.text,
+            innerName: (el.propertyName ?? el.name).text,
+          })
         }
+      } else if (!stmt.exportClause) {
+        // `export * from 'src'`. (`export * as ns from` carries a
+        // NamespaceExport clause here, not `undefined` — excluded on
+        // purpose: a named lookup can never come through it.)
+        hasStarReexport = true
       }
     }
 
@@ -4198,17 +4318,77 @@ function prescanImportedReactiveFactories(
     // 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)
+    const moduleBindings = collectHelperModuleValueBindings(sf)
+
+    const info: HelperFileInfo = { sf, exportedFns, reexports, hasStarReexport, moduleBindings }
+    helperCache.set(abs, info)
+    return info
+  }
+
+  /**
+   * Resolve `exportedName` from the file at `abs`, following one
+   * `export ... from` hop through a barrel re-export (#2341 BUG-2).
+   * `visited` guards against self/indirect barrel cycles.
+   */
+  function lookupExportedFactory(
+    abs: string,
+    exportedName: string,
+    visited: Set<string>,
+    hopsLeft: number
+  ): ExportLookup {
+    if (visited.has(abs)) return { kind: 'unknown' }
+    visited.add(abs)
+
+    const file = loadHelperFile(abs)
+    if (file === null) return { kind: 'unknown' }
+    if (file === 'clean') return { kind: 'clean' }
+
+    const fn = file.exportedFns.get(exportedName)
+    if (fn) return { kind: 'fn', fn, file, definingPath: abs }
+
+    const re = file.reexports.get(exportedName)
+    if (re) {
+      if (hopsLeft <= 0) return { kind: 'unknown' }
+      // Non-relative re-export specifiers (`export { x } from 'pkg'`)
+      // resolve through bundler/tsconfig-paths configuration this layer
+      // doesn't consume — same restriction as direct imports.
+      if (!re.source.startsWith('./') && !re.source.startsWith('../')) return { kind: 'unknown' }
+      const target = resolveRelativeImportToFile(re.source, abs)
+      if (!target) return { kind: 'unknown' } // unresolvable re-export target: never mark clean
+      return lookupExportedFactory(target, re.innerName, visited, hopsLeft - 1)
+    }
+
+    // `export * from` might still reach this name through a file this
+    // layer doesn't enumerate — never clean. Otherwise the file was fully
+    // inspected and genuinely doesn't define or re-export this name.
+    if (file.hasStarReexport) return { kind: 'unknown' }
+    return { kind: 'clean' }
+  }
+
+  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
+
+    const alreadyKnown = (name: string): boolean =>
+      result.factories.has(name) || result.declined.has(name) || result.reactiveShaped.has(name)
 
     for (const spec of specs) {
       if (alreadyKnown(spec.local)) continue
 
-      const fn = exportedFns.get(spec.exported)
-      if (!fn) {
+      const found = lookupExportedFactory(resolved, spec.exported, new Set<string>(), MAX_REEXPORT_HOPS)
+      if (found.kind === 'clean') {
         result.cleanFactoryImports.add(spec.local)
         continue
       }
-      const det = detectReactiveFactory(fn, helperSf, resolved)
+      if (found.kind === 'unknown') continue
+
+      const { fn, file, definingPath } = found
+      const helperSf = file.sf
+      const moduleBindings = file.moduleBindings
+
+      const det = detectReactiveFactory(fn, helperSf, definingPath)
       if (!det) {
         result.cleanFactoryImports.add(spec.local)
         continue
@@ -4221,6 +4401,9 @@ function prescanImportedReactiveFactories(
           result.declined.set(spec.local, det.declined)
           break
         case 'factory': {
+          // Module-capture check is anchored to the DEFINING file's own
+          // module bindings, not the barrel's (#2341 BUG-2) — the barrel
+          // itself contributes no bindings the inlined body could reference.
           const capture = moduleCaptureCheck(fn, det.info, moduleBindings, fn.name!.text)
           if (capture.captured.length > 0) {
             result.declined.set(spec.local, {
@@ -4231,7 +4414,9 @@ function prescanImportedReactiveFactories(
             break
           }
           // #2332 — re-provision the helper file's own named value imports
-          // that the factory body references, instead of declining. Each
+          // that the factory body references, instead of declining (type-
+          // only refs included #2350 — same treatment, tagged `isTypeOnly`
+          // so the line-generator below emits `import type { ... }`). 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
@@ -4243,14 +4428,20 @@ function prescanImportedReactiveFactories(
           const required: RequiredFactoryImport[] = []
           const pending: Array<[string, { targetKey: string; exportedName: string }]> = []
           let declinedEntry: DeclinedReactiveFactory | null = null
-          for (const ref of capture.importedRefs) {
+          const allRefs = [
+            ...capture.importedRefs.map((r) => ({ ...r, isTypeOnly: false })),
+            ...capture.importedTypeRefs.map((r) => ({ ...r, isTypeOnly: true })),
+          ]
+          for (const ref of allRefs) {
             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
+              // Resolve from the DEFINING file's directory (#2341 BUG-2 —
+              // `definingPath` is the file that actually declares this
+              // import, which may differ from the barrel that was
+              // imported). Unresolvable → same posture as a local
               // capture: nothing importable to re-provision (BF112).
-              const abs = resolveRelativeImportToFile(ref.source, resolved)
+              const abs = resolveRelativeImportToFile(ref.source, definingPath)
               if (!abs) {
                 declinedEntry = {
                   code: 'BF112',
@@ -4267,8 +4458,13 @@ function prescanImportedReactiveFactories(
             }
             // Already satisfied by an identical top-level import in the
             // component file — injecting again would redeclare the binding.
+            // A type-only need is satisfiable by ANY matching import (value
+            // or type — a value import brings its type into scope too); a
+            // value need can only be satisfied by an existing value import,
+            // since a type-only import has no runtime binding (#2350).
             const existing = entryImportIndex.get(ref.localName)
-            if (existing && existing.targetKey === targetKey && existing.exportedName === ref.exportedName) {
+            if (existing && existing.targetKey === targetKey && existing.exportedName === ref.exportedName &&
+                (ref.isTypeOnly || !existing.isTypeOnly)) {
               continue
             }
             const planned = plannedInjections.get(ref.localName)
@@ -4285,14 +4481,17 @@ function prescanImportedReactiveFactories(
               break
             }
             pending.push([ref.localName, { targetKey, exportedName: ref.exportedName }])
-            required.push({ localName: ref.localName, exportedName: ref.exportedName, specifier })
+            required.push({ localName: ref.localName, exportedName: ref.exportedName, specifier, isTypeOnly: ref.isTypeOnly || undefined })
           }
           if (declinedEntry) {
             result.declined.set(spec.local, declinedEntry)
             break
           }
           for (const [name, id] of pending) plannedInjections.set(name, id)
-          det.info.sourceFilePath = resolved
+          // #2341 BUG-2 — anchored to the file that actually defines the
+          // factory, not the (possibly barrel) import path the component
+          // used to reach it.
+          det.info.sourceFilePath = definingPath
           if (required.length > 0) det.info.requiredImports = required
           result.factories.set(spec.local, det.info)
           break
@@ -4325,8 +4524,17 @@ function prescanImportedReactiveFactories(
  * 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.
+ * the helper file itself imports it.
+ *
+ * `localTypes`/`importedTypes` are the type-position mirror of `local`/
+ * `imported` (#2350): a factory body's return-type annotations, generic
+ * type arguments, and local variable type annotations reference names too,
+ * and those need the exact same capture-or-re-provision treatment — a type
+ * declared directly in the helper file can't be re-imported (BF112,
+ * folded into `local`'s capture handling since the failure mode is
+ * identical), but a type the helper file itself imports (`import type {
+ * X }` or the per-specifier `import { type X }`) can be re-provisioned as
+ * `import type { X } from '<specifier>'` in the component file.
  */
 interface HelperModuleBindings {
   /** Declared directly in the helper file — unconditional BF112 capture. */
@@ -4334,10 +4542,18 @@ interface HelperModuleBindings {
   /** Named value-import specifiers, keyed by helper-file local name —
    *  re-provisionable into the component file (#2332). */
   imported: Map<string, { source: string; exportedName: string }>
+  /** Type/interface declared directly in the helper file — unconditional
+   *  BF112 capture, same as `local` (#2350). */
+  localTypes: Set<string>
+  /** The helper file's own type-only named imports, keyed by local name —
+   *  re-provisionable as `import type { X } from '<specifier>'` (#2350). */
+  importedTypes: Map<string, { source: string; exportedName: string }>
 }
 
 function collectHelperModuleValueBindings(sf: ts.SourceFile): HelperModuleBindings {
   const local = new Set<string>()
+  const localTypes = new Set<string>()
+  const importedTypes = new Map<string, { source: string; exportedName: string }>()
   const imported = new Map<string, { source: string; exportedName: string }>()
   for (const stmt of sf.statements) {
     if (ts.isVariableStatement(stmt)) {
@@ -4355,35 +4571,43 @@ function collectHelperModuleValueBindings(sf: ts.SourceFile): HelperModuleBindin
       local.add(stmt.name.text)
       continue
     }
+    if ((ts.isTypeAliasDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)) && stmt.name) {
+      localTypes.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
+      const wholeTypeOnly = stmt.importClause?.isTypeOnly === true
       // 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)
+      // no single named export to re-provision under one local name. A
+      // type-only default/namespace import has the same problem, so it
+      // goes to `localTypes` rather than `importedTypes`.
+      if (stmt.importClause?.name) (wholeTypeOnly ? localTypes : 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 })
+          const entry = { source: src, exportedName: (el.propertyName ?? el.name).text }
+          if (wholeTypeOnly || el.isTypeOnly) importedTypes.set(el.name.text, entry)
+          else imported.set(el.name.text, entry)
         }
       }
       if (namedBindings && ts.isNamespaceImport(namedBindings)) {
-        local.add(namedBindings.name.text)
+        (wholeTypeOnly ? localTypes : local).add(namedBindings.name.text)
       }
     }
   }
-  return { local, imported }
+  return { local, imported, localTypes, importedTypes }
 }
 
 /**
  * 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
+ * its own module scope (#2332, type positions added #2350): `captured` are
+ * unconditional BF112 hits (helper-local bindings — the body would dangle
+ * if inlined verbatim, value or type alike); `importedRefs`/
+ * `importedTypeRefs` are references to the helper file's own named value/
+ * type imports, which the caller may re-provision into the component file
  * instead of declining (§3.4 in the #2332 spec).
  */
 interface ModuleCaptureResult {
@@ -4391,23 +4615,27 @@ interface ModuleCaptureResult {
   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 type-position refs resolving to the helper's own named type imports, sorted by localName. */
+  importedTypeRefs: 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.
+ * its own module scope (#2325 §4h / BF112, #2332, type positions #2350) —
+ * 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`/`importedTypeRefs`
+ * (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.
+ * BF112 or `importedRefs`/`importedTypeRefs`. 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,
@@ -4415,16 +4643,24 @@ function moduleCaptureCheck(
   moduleBindings: HelperModuleBindings,
   selfName: string
 ): ModuleCaptureResult {
-  if (!fn.body) return { captured: [], importedRefs: [] }
+  if (!fn.body) return { captured: [], importedRefs: [], importedTypeRefs: [] }
   const free = extractFreeIdentifiersFromNode(fn.body)
+  const freeTypes = extractFreeTypeIdentifiersFromNode(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)
+  // extractFreeTypeIdentifiersFromNode only tracks type parameters declared
+  // BY nodes it walks — it never sees `fn` itself (only `fn.body`), so the
+  // factory's own `<T>` list needs excluding here instead (Copilot review,
+  // PR #2351: `function useThing<Item>(...)` shadowing a module-scope
+  // `Item` type import).
+  if (fn.typeParameters) for (const p of fn.typeParameters) exclude.add(p.name.text)
 
   const captured: string[] = []
   const importedRefs: ModuleCaptureResult['importedRefs'] = []
+  const importedTypeRefs: ModuleCaptureResult['importedTypeRefs'] = []
   for (const id of free) {
     if (exclude.has(id)) continue
     if (moduleBindings.local.has(id)) {
@@ -4434,9 +4670,29 @@ function moduleCaptureCheck(
     const imp = moduleBindings.imported.get(id)
     if (imp) importedRefs.push({ localName: id, source: imp.source, exportedName: imp.exportedName })
   }
+  for (const id of freeTypes) {
+    if (exclude.has(id)) continue
+    if (free.has(id)) continue // already resolved above — same name, value position wins
+    if (moduleBindings.localTypes.has(id) || moduleBindings.local.has(id)) {
+      captured.push(id)
+      continue
+    }
+    const typeImp = moduleBindings.importedTypes.get(id)
+    if (typeImp) {
+      importedTypeRefs.push({ localName: id, source: typeImp.source, exportedName: typeImp.exportedName })
+      continue
+    }
+    // A name used ONLY in type position can still resolve to the helper's
+    // own VALUE import (e.g. a class referenced purely as `(): Foo`) —
+    // re-provision it as a normal value import, which brings the type into
+    // scope too, instead of missing it entirely (Copilot review, PR #2351).
+    const valueImp = moduleBindings.imported.get(id)
+    if (valueImp) importedRefs.push({ localName: id, source: valueImp.source, exportedName: valueImp.exportedName })
+  }
   captured.sort()
   importedRefs.sort((a, b) => (a.localName < b.localName ? -1 : 1))
-  return { captured, importedRefs }
+  importedTypeRefs.sort((a, b) => (a.localName < b.localName ? -1 : 1))
+  return { captured, importedRefs, importedTypeRefs }
 }
 
 /**
@@ -4478,6 +4734,27 @@ function detectReactiveFactory(
 
   const loc = getSourceLocation(node, sourceFile, filePath)
 
+  // Count `return`s ANYWHERE in the body, stopping at nested function-like
+  // boundaries (ts.isFunctionLike — functions, arrows, methods, accessors,
+  // and constructors; broader than isMultiReturnJsxFunctionBody's #932
+  // three-kind check, which only needs to catch JSX-returning callbacks and
+  // was never exercised against class/object methods) — a return inside a
+  // nested callback OR a class/object method declared in the factory body
+  // belongs to that inner scope, not this factory (Copilot review, PR
+  // #2342: the narrower check would misclassify a factory with, e.g., a
+  // helper class whose method contains a `return` as having multiple
+  // returns, declining it unnecessarily). A return nested in if/try/loop
+  // blocks DOES count, so guard-clause factories are declassified instead
+  // of splicing an early `return` into the component's init function
+  // (#2341 BUG-3).
+  let totalReturnCount = 0
+  function countReturns(n: ts.Node): void {
+    if (ts.isFunctionLike(n)) return
+    if (ts.isReturnStatement(n)) { totalReturnCount++; return }
+    ts.forEachChild(n, countReturns)
+  }
+  ts.forEachChild(node.body, countReturns)
+
   // 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.
@@ -4494,7 +4771,12 @@ function detectReactiveFactory(
     if (ts.isTypeAssertionExpression(expr)) expr = expr.expression
     returnExpr = expr
   }
-  if (returnCount !== 1 || !returnExpr) return { kind: 'reactive-shaped' }
+  // `totalReturnCount === 1 && returnCount === 1` jointly guarantee the
+  // single return is a direct child of `node.body` (top-level returns are a
+  // subset of total) — so a guard-clause / try-catch / loop return
+  // declassifies the factory instead of silently producing an inert
+  // component (#2341 BUG-3).
+  if (totalReturnCount !== 1 || returnCount !== 1 || !returnExpr) return { kind: 'reactive-shaped' }
 
   const returnTupleIdentifiers: string[] = []
   let returnKind: 'tuple' | 'object'
@@ -4530,6 +4812,22 @@ function detectReactiveFactory(
     return { kind: 'reactive-shaped' }
   }
 
+  // Collect parameter names first — the rename-site walk below needs them
+  // as part of `relevantNames` and to detect param-shadowing declarations
+  // (BF114). Hoisted above local-binding/body-serialization collection
+  // (#2341 BUG-1); it has no dependency on either.
+  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; the factory still wraps a reactive primitive, so
+    // classify it as reactive-shaped rather than silently ignoring it.
+    return { kind: 'reactive-shaped' }
+  }
+
   // Collect local bindings in the factory body for identifier hygiene at
   // inlining time. Only direct-child declarations of the block are
   // considered — good enough for the typical helper shape.
@@ -4544,24 +4842,146 @@ function detectReactiveFactory(
     }
   }
 
+  // Names that call-site inlining may rename: params (substituted with
+  // arbitrary argument expressions), local bindings (suffix-renamed for
+  // per-call-site hygiene), and return identifiers (renamed to the
+  // caller's destructure names). Every other identifier in the body is
+  // left untouched — the #2341 BUG-1 fix for the old whole-body regex
+  // renames, which corrupted string/template literals, property keys,
+  // and `.prop` tails that merely happened to share a relevant name.
+  const relevantNames = new Set<string>([...params, ...localBindings, ...returnTupleIdentifiers])
+
+  const renameSites: FactoryRenameSite[] = []
+  let shadowedParam: string | null = null
+
+  /**
+   * Recursive AST walk collecting rename sites for one kept statement.
+   * `toBodyOffset` converts a position in `sourceFile` (this statement's
+   * original source) to an offset in the final joined `bodyStatements`
+   * string — see the join loop below for why this must stay a pure
+   * function of `stmtStart`/`base`.
+   */
+  function collectRenameSites(root: ts.Node, toBodyOffset: (pos: number) => number): void {
+    function push(id: ts.Identifier, form: 'plain' | 'shorthand'): void {
+      renameSites.push({
+        name: id.text,
+        start: toBodyOffset(id.getStart(sourceFile)),
+        end: toBodyOffset(id.getEnd()),
+        form,
+      })
+    }
+
+    function classify(id: ts.Identifier): void {
+      if (!relevantNames.has(id.text)) return
+      const p = id.parent
+      // Pure-key / non-reference positions — never rename:
+      if (ts.isPropertyAccessExpression(p) && p.name === id) return        // obj.name tail (incl. ?. chains)
+      if (ts.isPropertyAssignment(p) && p.name === id) return              // { name: v } key
+      if (ts.isBindingElement(p) && p.propertyName === id) return          // { name: local } pattern key
+      if ((ts.isMethodDeclaration(p) || ts.isGetAccessorDeclaration(p) ||
+           ts.isSetAccessorDeclaration(p) || ts.isPropertyDeclaration(p) ||
+           ts.isEnumMember(p)) && p.name === id) return                    // member keys
+      if (ts.isJsxAttribute(p) && p.name === id) return                    // JSX attr name
+      if ((ts.isLabeledStatement(p) && p.label === id) ||
+          ((ts.isBreakStatement(p) || ts.isContinueStatement(p)) && p.label === id)) return
+      if ((ts.isJsxOpeningElement(p) || ts.isJsxSelfClosingElement(p) || ts.isJsxClosingElement(p)) &&
+          p.tagName === id && /^[a-z]/.test(id.text)) return               // intrinsic tag <div>
+
+      // Shorthand dual-role positions → expansion form (renaming must
+      // preserve the implied key): `{ name }` object literal / pattern.
+      if (ts.isShorthandPropertyAssignment(p) && p.name === id) { push(id, 'shorthand'); return }
+      if (ts.isBindingElement(p) && p.name === id && !p.propertyName &&
+          ts.isObjectBindingPattern(p.parent)) {
+        // ArrayBindingPattern trap: a tuple destructure element
+        // (`const [a, b] = ...`) ALSO has propertyName === undefined —
+        // the ts.isObjectBindingPattern(p.parent) check above is what
+        // keeps tuple elements out of the shorthand-expansion path.
+        if (params.includes(id.text)) shadowedParam = id.text            // decl of a param name → BF114
+        push(id, 'shorthand')
+        return
+      }
+
+      // Declaration-name positions → plain rename, but a param name
+      // re-declared here is a shadow: params are substituted with
+      // arbitrary argument expressions, so a shadowing declaration would
+      // receive an invalid left-hand side (BF114 declines instead).
+      const isDecl =
+        (ts.isVariableDeclaration(p) || ts.isParameter(p) || ts.isBindingElement(p) ||
+         ts.isFunctionDeclaration(p) || ts.isFunctionExpression(p) ||
+         ts.isClassDeclaration(p) || ts.isClassExpression(p)) && p.name === id
+      if (isDecl && params.includes(id.text)) shadowedParam = id.text
+
+      push(id, 'plain')                                                   // genuine value reference or decl
+    }
+
+    function visit(n: ts.Node): void {
+      // Never descend into type-land: annotations are stripped downstream,
+      // and splicing an argument EXPRESSION into a type position would be
+      // invalid JS.
+      if (ts.isTypeNode(n) || ts.isTypeParameterDeclaration(n) ||
+          ts.isTypeAliasDeclaration(n) || ts.isInterfaceDeclaration(n)) return
+      if (ts.isIdentifier(n)) { classify(n); return }                      // identifiers have no relevant children
+      ts.forEachChild(n, visit)
+    }
+
+    visit(root)
+  }
+
   // Serialize the body without the outer braces and without the return
   // 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')
+  // identifiers. `renameSites` is collected in this SAME loop so its
+  // offsets (relative to the joined `bodyStatements` string) can never
+  // drift from the join logic — this invariant is the single most fragile
+  // part of the rename mechanism (#2341 BUG-1): site collection and
+  // `bodyStatements` construction must use the identical statement filter,
+  // identical `getText` slices, and identical '\n' join.
+  const keptStatements = node.body.statements.filter(s => !ts.isReturnStatement(s))
+  const pieces: string[] = []
+  let base = 0
+  for (const stmt of keptStatements) {
+    const text = stmt.getText(sourceFile)
+    const stmtStart = stmt.getStart(sourceFile)
+    collectRenameSites(stmt, (pos) => pos - stmtStart + base)
+    pieces.push(text)
+    base += text.length + 1 // +1 for the '\n' join — MUST match the join below
+  }
+  const bodyStatements = pieces.join('\n')
+
+  if (shadowedParam !== null) {
+    return {
+      kind: 'declined',
+      declined: {
+        code: 'BF114',
+        detail: `parameter '${shadowedParam}' of '${node.name.text}' is shadowed by a nested declaration inside the factory body`,
+        loc,
+      },
+    }
+  }
 
-  const params: string[] = []
-  for (const p of node.parameters) {
-    if (ts.isIdentifier(p.name)) {
-      params.push(p.name.text)
-      continue
+  // Dev invariant: every collected site's [start, end) range must slice
+  // out exactly the identifier text it was collected for, or the
+  // bottom-to-top splice in inlineFactoryCallAtSite would corrupt
+  // unrelated text. Cheap (bounded by body size) — kept as a permanent
+  // guard against the offset math drifting under a future edit. Declines
+  // rather than throwing (Copilot review, PR #2342): compileJSX does not
+  // catch analyzer errors, so a thrown exception here would crash the
+  // whole compilation instead of failing one factory loudly-but-
+  // gracefully as a diagnostic — this should never trigger in practice,
+  // but the failure mode if it ever does must stay "loud decline," not
+  // "hard crash," matching this feature's whole design philosophy.
+  for (const site of renameSites) {
+    if (bodyStatements.slice(site.start, site.end) !== site.name) {
+      return {
+        kind: 'declined',
+        declined: {
+          code: 'BF111',
+          detail:
+            `internal rename-site offset mismatch for '${site.name}' — this is a compiler bug, ` +
+            `please report it`,
+          loc,
+        },
+      }
     }
-    // Destructured params are uncommon for this helper shape and out of
-    // 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 {
@@ -4573,6 +4993,7 @@ function detectReactiveFactory(
       returnKind,
       localBindings,
       loc,
+      renameSites,
     },
   }
 }
@@ -4741,30 +5162,49 @@ function rewriteFactoryCallsInSource(
     const thisCallIndex = callSiteIndex++
     const suffix = `_bf${thisCallIndex}`
 
-    // Apply renames to the factory body source.
-    let body = factory.bodySource
-    // 1. Suffix-rename internal bindings.
-    const internalRenames = new Set<string>(factory.localBindings)
-    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)
+    // Merged rename map, one entry per old name → replacement text.
+    // Precedence (matches the pre-#2341 sequential-pass outcome): param
+    // substitution > return→caller rename > internal suffix rename — later
+    // `.set()` calls for the same key overwrite earlier ones below.
+    const renames = new Map<string, string>()
+    // 1. Suffix-rename internal bindings not excluded (tuple params/returns,
+    //    or object-path destructured names — see excludeFromSuffixRename's
+    //    callers).
+    for (const name of factory.localBindings) {
+      if (!excludeFromSuffixRename.has(name)) renames.set(name, name + suffix)
+    }
+    // 2. Return identifiers → caller destructure names (tuple path only).
+    if (renameReturnToCallerNames) {
+      for (const [n, caller] of renameReturnToCallerNames) {
+        if (caller !== n) renames.set(n, caller) // identity rename = no-op, skip
+      }
     }
-    // 2. Parameters → argument expressions. Atomic arguments (bare
+    // 3. Parameters → argument expressions. Atomic arguments (bare
     //    identifiers, numeric literals, string literals) are spliced
     //    directly; anything more complex is wrapped in parens to preserve
-    //    operator precedence at the splice site.
+    //    operator precedence at the splice site. Overwrites any same-name
+    //    return rename above — param substitution wins, as before #2341.
     const atomicArg = /^(?:[\w$.]+|'[^'\\]*'|"[^"\\]*"|-?\d+(?:\.\d+)?)$/
     for (let i = 0; i < factory.params.length; i++) {
       const p = factory.params[i]
-      const a = argTexts[i] ?? 'undefined'
-      const wrapped = atomicArg.test(a.trim()) ? a.trim() : `(${a})`
-      body = body.replace(new RegExp(`\\b${escapeRegex(p)}\\b`, 'g'), wrapped)
+      const a = (argTexts[i] ?? 'undefined').trim()
+      renames.set(p, atomicArg.test(a) ? a : `(${a})`)
     }
-    // 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)
-      }
+
+    // Apply the merged renames as a single bottom-to-top position splice
+    // over `bodySource`, using the sites collected once at detection time
+    // (#2341 BUG-1) — never a text search, so string/template-literal
+    // contents, property keys, `.prop` tails, and JSX intrinsic tags are
+    // never touched, and (unlike the old sequential regex passes) an
+    // argument expression already spliced in for an earlier site can never
+    // be re-scanned and corrupted by a later rename.
+    let body = factory.bodySource
+    for (let i = factory.renameSites.length - 1; i >= 0; i--) {
+      const site = factory.renameSites[i]
+      const repl = renames.get(site.name)
+      if (repl === undefined) continue
+      const text = site.form === 'shorthand' ? `${site.name}: ${repl}` : repl
+      body = body.slice(0, site.start) + text + body.slice(site.end)
     }
 
     edits.push({
@@ -4780,33 +5220,61 @@ function rewriteFactoryCallsInSource(
   if (edits.length === 0) return source
 
   // #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
+  // cross-file factory's re-provisioned imports (type-only refs #2350, kept
+  // on separate `import type { ... }` lines since a value and a type
+  // import can't share one specifier list). 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
+  const typeImportsBySpecifier = 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) }
+      const bySpecifier = r.isTypeOnly ? typeImportsBySpecifier : importsBySpecifier
+      let names = bySpecifier.get(r.specifier)
+      if (!names) { names = new Map(); bySpecifier.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}'`
-      })
+  // Two different factories can independently need the same (specifier,
+  // localName) — one only in value position, one only in type position
+  // (#2350). The value import already brings the type into scope, so drop
+  // the now-redundant type-only line rather than emit both (which TypeScript
+  // would reject as a duplicate identifier).
+  for (const [spec, typeNames] of typeImportsBySpecifier) {
+    const valueNames = importsBySpecifier.get(spec)
+    if (!valueNames) continue
+    for (const local of [...typeNames.keys()]) {
+      if (valueNames.has(local)) typeNames.delete(local)
+    }
+    if (typeNames.size === 0) typeImportsBySpecifier.delete(spec)
+  }
+  if (importsBySpecifier.size > 0 || typeImportsBySpecifier.size > 0) {
+    // One sorted pass over the UNION of specifiers (value + type-only), not
+    // two separately-sorted lists — the latter would leave the value/
+    // type-only halves each internally sorted but not globally sorted
+    // against each other (a type-only import from 'a' could land after a
+    // value import from 'b'), an unstable-looking order across unrelated
+    // refactors (Copilot review, PR #2351). Within each specifier, named-
+    // import entries are sorted by local name too — `importsBySpecifier`/
+    // `inlinedFactories` iterate in incidental AST-traversal/insertion
+    // order (Copilot review, PR #2338).
+    const buildLine = (names: Map<string, string>, keyword: string, spec: string) => {
+      const specifiers = [...names]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([local, exported]) => (exported === local ? local : `${exported} as ${local}`))
+      return `import ${keyword}{ ${specifiers.join(', ')} } from '${spec}'`
+    }
+    const allSpecifiers = new Set([...importsBySpecifier.keys(), ...typeImportsBySpecifier.keys()])
+    const lines = [...allSpecifiers].sort().flatMap((spec) => {
+      const out: string[] = []
+      const valueNames = importsBySpecifier.get(spec)
+      if (valueNames) out.push(buildLine(valueNames, '', spec))
+      const typeNames = typeImportsBySpecifier.get(spec)
+      if (typeNames) out.push(buildLine(typeNames, 'type ', spec))
+      return out
+    })
     const at = factoryImportInsertionOffset(sourceFile)
     edits.push({ start: at, end: at, replacement: at === 0 ? lines.join('\n') + '\n' : '\n' + lines.join('\n') })
   }
@@ -4853,10 +5321,6 @@ function isPascalCaseComponentFn(node: ts.Node): boolean {
   return false
 }
 
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
 // =============================================================================
 // BF110 diagnostic (#931)
 // =============================================================================
@@ -4895,6 +5359,7 @@ function declinedFactoryErrorCode(code: DeclinedReactiveFactory['code']): ErrorC
   switch (code) {
     case 'BF112': return ErrorCodes.REACTIVE_FACTORY_MODULE_CAPTURE
     case 'BF113': return ErrorCodes.REACTIVE_FACTORY_IMPORT_COLLISION
+    case 'BF114': return ErrorCodes.REACTIVE_FACTORY_PARAM_SHADOWED
     default: return ErrorCodes.REACTIVE_FACTORY_RENAME_UNSUPPORTED
   }
 }