@barefootjs/jsx 0.31.3 → 0.31.5

package/src/ir-to-client-js/reactivity.ts

@@ -18,6 +18,41 @@ import { attrValueToString, freeIdsFromRefs, tokenContainsIdent } from './utils.
 import { expandConstantForReactivity } from './prop-handling.ts'
 import { extractFreeIdentifiersFromText } from './csr-substitute.ts'
 import { walkIR, stopAt } from './walker.ts'
+import { BindingScope } from '../scope/binding-scope.ts'
+import { identifierCallPattern } from '../identifier-pattern.ts'
+
+/**
+ * Build the `BindingScope` for one loop row's own bindings — item /
+ * destructured param / index names plus (when supplied) the `.map()`
+ * callback's preamble locals (#2447) — for the `expandConstantForReactivity`
+ * shadow guard (#2482 Stage 1b). `undefined` when there's no enclosing loop
+ * (`loopParam` unset), matching every caller's existing "no loop" shape.
+ *
+ * `loopIndex` (Copilot review on #2595): a `.map((item, i) => ...)`
+ * callback's second param is a real row-scoped binding exactly like
+ * `item` — an `i`-shadows-a-module-const attr/text (e.g.
+ * `data-idx={/* @client *\/ i}`) const-folds to the outer value exactly
+ * like an item-param shadow does when the index name isn't in scope.
+ * Only guarded when the CALLER passes it in, though — none of the
+ * `collectLoopChild*` collectors' own callers threaded the IR loop's
+ * `index` field through before this fix (see each call site's own
+ * `undefined`/omitted-arg default), so `undefined` here still means "not
+ * guarded," not "no index param."
+ */
+export function buildLoopRowScope(
+  loopParam?: string,
+  loopParamBindings?: readonly LoopParamBinding[],
+  preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
+): BindingScope | undefined {
+  if (!loopParam) return undefined
+  return BindingScope.EMPTY.enterLoopRow({
+    param: loopParam,
+    paramBindings: loopParamBindings,
+    index: loopIndex,
+    preamble: preambleNames && preambleNames.size > 0 ? { declaredNames: [...preambleNames] } : undefined,
+  })
+}
 
 /**
  * Phase 2 reactivity detection: determines if a code expression needs `createEffect`
@@ -146,13 +181,13 @@ export function needsEffectWrapper(
   freeIdentifiers?: ReadonlySet<string>,
 ): boolean {
   for (const signal of ctx.signals) {
-    if (new RegExp(`\\b${signal.getter}\\s*\\(`).test(expr)) {
+    if (identifierCallPattern(signal.getter).test(expr)) {
       return true
     }
   }
 
   for (const memo of ctx.memos) {
-    if (new RegExp(`\\b${memo.name}\\s*\\(`).test(expr)) {
+    if (identifierCallPattern(memo.name).test(expr)) {
       return true
     }
   }
@@ -555,6 +590,14 @@ function traverseForComponents(
  * Defaults to false: some callers (e.g. a plain nested `.map()`'s own
  * per-item bindings) have no sibling conditional collector, so a slotId'd
  * conditional's inlined content is only ever reachable by descending here.
+ *
+ * `preambleNames` (#2482 Stage 1b): the enclosing loop's `.map()` callback
+ * preamble locals (#2447), when known — folded into the `expandConstantForReactivity`
+ * shadow guard via `buildLoopRowScope` so a preamble local shadowing a
+ * component/module const doesn't get const-folded here.
+ *
+ * `loopIndex` (Copilot review on #2595): the loop's index param name
+ * (`.map((item, i) => ...)`'s `i`), when known — see `buildLoopRowScope`.
  */
 export function collectLoopChildReactiveTexts(
   node: IRNode,
@@ -562,8 +605,11 @@ export function collectLoopChildReactiveTexts(
   loopParam?: string,
   loopParamBindings?: readonly LoopParamBinding[],
   stopAtReactiveConditionals = false,
+  preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
 ): LoopChildReactiveText[] {
   const texts: LoopChildReactiveText[] = []
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
   walkIR(node, false, {
     // Skip loop/async/if-statement subtrees — the original walker omitted
     // them; they have their own scopes (inner-loop reconciliation, async
@@ -579,7 +625,7 @@ export function collectLoopChildReactiveTexts(
       // (a `joinArrayChild` region's value is raw HTML, not text).
       if (n.preambleRegion) return
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs)
-      const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds)
+      const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds, scope)
       // Include if expression reads signals OR references the loop parameter
       // (loop param becomes a signal accessor via per-item signals). Falls
       // back to the Solid-style AST-flag wrap decision — mirroring
@@ -621,10 +667,14 @@ export function collectLoopChildReactiveTexts(
  * `stopAtReactiveConditionals` (#2347): see `collectLoopChildReactiveTexts` —
  * same semantics. Pass true only when the caller also separately collects
  * nested reactive conditionals and gives each its own `insert()`.
+ *
+ * `loopIndex` (Copilot review on #2595): see `collectLoopChildReactiveTexts`.
  */
 /** Does any name in `names` appear in `set`? Iterates rather than
- *  spreading — this runs per attribute (Copilot review). */
-function anyNameIn(names: Iterable<string>, set: ReadonlySet<string>): boolean {
+ *  spreading — this runs per attribute (Copilot review). Exported for
+ *  `collectLoopChildConditionals`'s `readsPreamble` check (#2596), the
+ *  condition-position twin of the attr check just below this uses it for. */
+export function anyNameIn(names: Iterable<string>, set: ReadonlySet<string>): boolean {
   for (const n of names) if (set.has(n)) return true
   return false
 }
@@ -636,8 +686,10 @@ export function collectLoopChildReactiveAttrs(
   loopParamBindings?: readonly LoopParamBinding[],
   stopAtReactiveConditionals = false,
   preambleNames?: ReadonlySet<string>,
+  loopIndex?: string | null,
 ): LoopChildReactiveAttr[] {
   const attrs: LoopChildReactiveAttr[] = []
+  const scope = buildLoopRowScope(loopParam, loopParamBindings, preambleNames, loopIndex)
   traverseElements(node, (el) => {
     if (el.slotId) {
       for (const attr of el.attrs) {
@@ -653,7 +705,7 @@ export function collectLoopChildReactiveAttrs(
         if (attr.name === 'key') continue
         const valueStr = attrValueToString(attr.value)
         if (!valueStr) continue
-        const expanded = expandConstantForReactivity(valueStr, ctx, attr.freeIdentifiers)
+        const expanded = expandConstantForReactivity(valueStr, ctx, attr.freeIdentifiers, scope)
         // `/* @client */` always defers via per-item createEffect
         // regardless of the reactivity classifier — matches the
         // top-level `collectElements.element` and the conditional

package/src/ir-to-client-js/rewrite-props-object.ts

@@ -24,6 +24,7 @@
 
 import ts from 'typescript'
 import { PROPS_PARAM } from './utils.ts'
+import { identifierPattern } from '../identifier-pattern.ts'
 
 /**
  * Rename every value-position reference to `propsObjectName` in `code`
@@ -36,7 +37,7 @@ export function rewritePropsObjectRef(code: string, propsObjectName: string | nu
   if (srcPropsName === PROPS_PARAM) return code
 
   // Quick exit when the name doesn't appear at all.
-  if (!new RegExp(`\\b${srcPropsName}\\b`).test(code)) return code
+  if (!identifierPattern(srcPropsName).test(code)) return code
 
   const sourceFile = ts.createSourceFile(
     'init-body.ts',

package/src/ir-to-client-js/types.ts

@@ -578,6 +578,22 @@ export interface LoopChildConditional {
    * constants' own `freeIdentifiers`.
    */
   conditionFreeIdentifiers?: ReadonlySet<string>
+  /**
+   * `condition` references a `.map()` callback preamble-declared name
+   * (#2596, twin of `LoopChildReactiveAttr.readsPreamble` #2447) — the
+   * emitter must run the preamble ahead of evaluating the condition getter
+   * passed to `insert()`, since the local is not otherwise in scope there.
+   * Set whenever the condition mentions ANY preamble-declared name
+   * (`preambleNamesOf`), regardless of why the conditional was classified
+   * reactive — the scope obligation is the same either way. Whether the
+   * conditional is wired reactive AT ALL is the separate, stricter Phase-1
+   * question (`IRLoop.preamble.reactiveNames` via
+   * `markPreambleConditionalReactivity`, plus the ordinary signal/prop
+   * classifiers); `classifyReactivity` can't answer it from the token
+   * alone because `expandConstantForReactivity`'s shadow guard leaves a
+   * preamble-bound identifier unexpanded on purpose (#2482 Stage 1b).
+   */
+  readsPreamble?: boolean
 }
 
 export interface TopLevelLoop extends LoopCore {

package/src/ir-to-client-js/utils.ts

@@ -8,6 +8,7 @@ import type { AttrValue, IRTemplatePart, LoopParamBinding, FreeReference, IRNode
 import type { TopLevelLoop, BranchLoop, LoopOffset } from './types.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
 import { templatePartsToJsExpr } from '../template-parts.ts'
+import { escapeIdentifierForRegex, ID_BOUNDARY_BEFORE, ID_BOUNDARY_AFTER } from '../identifier-pattern.ts'
 import {
   iterateJsTokens,
   isIdentifierLikeToken,
@@ -337,10 +338,6 @@ export function inferDefaultValue(type: { kind: string; primitive?: string }): s
   return 'undefined'
 }
 
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
 /**
  * Flatten an `OriginInfo.freeRefs` list to a plain `Set<string>` of free
  * identifier names (#1267). Skips `kind: 'reactive-brand'` entries whose
@@ -561,8 +558,12 @@ export function wrapLoopParamAsAccessor(expr: string, paramName: string, binding
   if (bindings && bindings.length > 0) {
     return rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
   }
-  const re = new RegExp(`\\b${escapeRegExp(paramName)}\\b(?!\\s*\\()(?!-)`, 'g')
-  return replaceInExprContexts(expr, re, `${paramName}()`)
+  // `paramName` is a legal JS identifier and may itself start with `$`
+  // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
+  // reading those as backreference/whole-match sequences, so use a replacer
+  // function to insert the accessor text literally (#2592).
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+  return replaceInExprContexts(expr, re, () => `${paramName}()`)
 }
 
 /**
@@ -588,8 +589,8 @@ function rewriteLoopBindingRefs(
   const byName = new Map<string, LoopParamBinding>()
   for (const b of bindings) byName.set(b.name, b)
   const preprocessed = expandShorthandBindings(expr, new Set(byName.keys()))
-  const alt = bindings.map(b => escapeRegExp(b.name)).join('|')
-  const re = new RegExp(`\\b(${alt})\\b`, 'g')
+  const alt = bindings.map(b => escapeIdentifierForRegex(b.name)).join('|')
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}(${alt})${ID_BOUNDARY_AFTER}`, 'gu')
   return replaceInExprContexts(preprocessed, re, (_m: string, name: string) =>
     renderLoopBindingAccess(byName.get(name)!, accessor),
   )
@@ -697,6 +698,21 @@ export interface LoopParamSpec {
  * avoiding post-hoc regex replacement on full template strings.
  *
  * Accepts either a bare param name or a spec carrying destructure bindings.
+ *
+ * #2482: this `loopParams` parameter (and the same-named param on
+ * `irToHtmlTemplate` / `irToPlaceholderTemplate` in `html-template.ts`,
+ * threaded through `collect-elements.ts` / `build-event-delegation.ts`) is
+ * NOT one of the ratchet's tracked ad-hoc scope devices, even though the
+ * ledger's textual pattern happens to match its spelling. `BindingScope`
+ * answers EXISTENCE/kind/depth queries about bound names; this ordered
+ * `ReadonlyArray<string | LoopParamSpec>` instead carries the ACCESSOR-
+ * REWRITE payload for outermost-to-innermost text substitution
+ * (`item` → `__bfItem().path`) — a rendering/codegen concern `BindingScope`
+ * has no field for by design, the client-JS-emitter twin of the Go
+ * adapter's `loopBindingStack` (see that field's docstring on
+ * `GoTemplateAdapter`). Order matters here (each nesting level's wrap
+ * composes over the previous), which is exactly what a scope EXISTENCE
+ * stack does not model.
  */
 export function wrapExprWithLoopParams(expr: string, loopParams?: ReadonlyArray<string | LoopParamSpec>): string {
   if (!loopParams) return expr

package/src/jsx-to-ir.ts

@@ -63,6 +63,7 @@ import { reconstructAsSegments } from './strip-types.ts'
 import { templatePartsToJsExpr } from './template-parts.ts'
 import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
 import { BindingScope } from './scope/binding-scope.ts'
+import { identifierPattern, identifierCallPattern } from './identifier-pattern.ts'
 
 // =============================================================================
 // Transform Context
@@ -681,19 +682,19 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
-        pattern: new RegExp(`\\b${s.getter}\\s*\\(`),
+        pattern: identifierCallPattern(s.getter),
       })),
       memos: analyzer.memos.map(m => ({
         name: m.name,
-        pattern: new RegExp(`\\b${m.name}\\s*\\(`),
+        pattern: identifierCallPattern(m.name),
       })),
       props: analyzer.propsParams
         .filter(p => p.name !== 'children')
-        .map(p => ({ name: p.name, pattern: new RegExp(`\\b${p.name}\\b`) })),
+        .map(p => ({ name: p.name, pattern: identifierPattern(p.name) })),
       constants: analyzer.localConstants.map(c => ({
         name: c.name,
         value: c.value,
-        pattern: new RegExp(`\\b${c.name}\\b`),
+        pattern: identifierPattern(c.name),
       })),
     },
     getJS(node: ts.Node): string {
@@ -844,7 +845,7 @@ function makeBindingEnv(ctx: TransformContext): BindingEnvironment {
     // mutated (cached on the immutable `BindingScope`) — a stable
     // snapshot even if `ctx.scope` is later reassigned by an enclosing
     // visitor frame, which swaps the instance rather than mutating it.
-    loopParams: boundNames,
+    loopValueBoundNames: boundNames,
     checker: a.checker,
   }
   ctx._bindingEnv = env
@@ -2201,7 +2202,7 @@ function transformExpressionInner(
   // (#2482 Stage 1a Commit 2).
   const scopeValueNames = ctx.scope.valueBoundNames()
   const refsLoopParam = scopeValueNames.size > 0
-    && Array.from(scopeValueNames).some(p => new RegExp(`\\b${p}\\b`).test(exprText))
+    && Array.from(scopeValueNames).some(p => identifierPattern(p).test(exprText))
 
   // Compute AST-derived flags. `callsReactive` recognises signal-getter / memo
   // calls even inside deeper expressions (e.g., `format(count())`); `hasCalls`
@@ -2267,7 +2268,11 @@ function transformJsxFunctionCall(
   const substitutedGetJS = (node: ts.Node) => {
     let text = baseGetJS(node)
     for (const [paramName, argExpr] of substitutions) {
-      text = text.replace(new RegExp(`\\b${paramName}\\b`, 'g'), argExpr)
+      // Replacer function, not the string form: `argExpr` is arbitrary
+      // caller-supplied JS text and may itself contain `$` sequences
+      // (`$&`, `$1`, …) that `String.replace`'s string-replacement form
+      // would interpret specially instead of inserting literally (#2592).
+      text = text.replace(identifierPattern(paramName, 'g'), () => argExpr)
     }
     return text
   }
@@ -2319,7 +2324,11 @@ function transformMultiReturnJsxFunctionCall(
   const substitutedGetJS = (node: ts.Node) => {
     let text = baseGetJS(node)
     for (const [paramName, argExpr] of substitutions) {
-      text = text.replace(new RegExp(`\\b${paramName}\\b`, 'g'), argExpr)
+      // Replacer function, not the string form: `argExpr` is arbitrary
+      // caller-supplied JS text and may itself contain `$` sequences
+      // (`$&`, `$1`, …) that `String.replace`'s string-replacement form
+      // would interpret specially instead of inserting literally (#2592).
+      text = text.replace(identifierPattern(paramName, 'g'), () => argExpr)
     }
     return text
   }
@@ -5012,6 +5021,13 @@ function transformMapCall(
   // the row effect re-runs the preamble ahead of the write.
   if (preamble && !isStaticArray) {
     markPreambleAttrSlots(children, new Set(preamble.declaredNames), ctx)
+    // #2596 follow-up to the two passes above — the CONDITION-position twin.
+    // See `markPreambleConditionalReactivity`'s docstring for why this one is
+    // gated on `reactiveNames` (genuinely signal-derived) rather than the
+    // blanket `declaredNames` the region/attr passes use.
+    if (preamble.reactiveNames && preamble.reactiveNames.length > 0) {
+      markPreambleConditionalReactivity(children, new Set(preamble.reactiveNames), ctx)
+    }
   }
 
   // Collect nested components for both static and dynamic arrays.
@@ -5448,6 +5464,67 @@ function markPreambleAttrSlots(
   visit(nodes)
 }
 
+/**
+ * Grant the IR `reactive` flag (and a slot id) to a loop-body CONDITIONAL
+ * whose condition bare-references a preamble local that is itself reactive
+ * (#2596) — `reactiveNames`, computed by `computePreambleReactiveNames`.
+ *
+ * Root cause this closes: a plain (non-preamble) condition's `reactive` flag
+ * comes from `isReactiveExpression`/`isReactiveOrigin` run against the
+ * condition's OWN text at `transformConditional`/`transformLogicalAnd`/the
+ * if-else-chain builder — none of which know about an enclosing loop's
+ * `.map()` callback preamble (that's assembled and only becomes available
+ * on `IRLoop` after `children` is already built, same ordering constraint
+ * `collectPreambleRegions`/`markPreambleAttrSlots` work around). A condition
+ * that's just a bare reference to a preamble local (`label ? <A/> : <B/>`)
+ * therefore falls through every one of those classifiers with `reactive:
+ * false` even when `label`'s initializer reads a signal — the classifiers
+ * only ever see the token `label`, never its declaration.
+ *
+ * Deliberately narrower than `collectPreambleRegions`/`markPreambleAttrSlots`:
+ * those two mark ANY reference to `declaredNames` because their region-patch
+ * effect re-runs the WHOLE preamble unconditionally on row update, so a
+ * merely item-derived local (`const label = item.title`) still ends up
+ * correctly tracked by ordinary signal auto-tracking inside that effect —
+ * marking it reactive there costs nothing extra. A conditional is different:
+ * `reactive: true` here means Phase 2 wraps it in an `insert()` that swaps
+ * whole DOM subtrees, which is real cost and, for an item-only local, pure
+ * waste — the row already renders fresh whenever it's (re)constructed. So
+ * this only fires for `reactiveNames`, the subset PROVEN to depend on an
+ * actual external signal/memo/prop.
+ *
+ * Mirrors the sibling passes' traversal shape (conditional arms included).
+ */
+function markPreambleConditionalReactivity(
+  nodes: IRNode[],
+  reactiveNames: ReadonlySet<string>,
+  ctx: TransformContext,
+): void {
+  if (reactiveNames.size === 0) return
+  const visit = (list: IRNode[]): void => {
+    for (const node of list) {
+      switch (node.type) {
+        case 'element':
+        case 'fragment':
+          visit(node.children)
+          break
+        case 'conditional': {
+          if (!node.reactive) {
+            const refs = extractFreeIdentifiersFromText(node.condition)
+            if ([...refs].some((r) => reactiveNames.has(r))) {
+              node.reactive = true
+              if (!node.slotId) node.slotId = generateSlotId(ctx)
+            }
+          }
+          visit([node.whenTrue, ...(node.whenFalse ? [node.whenFalse] : [])])
+          break
+        }
+      }
+    }
+  }
+  visit(nodes)
+}
+
 /**
  * Expression-bearing source text of an attribute value, for the
  * free-identifier scan. Only used as a FALLBACK — an attribute normally
@@ -5494,6 +5571,52 @@ function collectPreambleDeclaredNames(stmt: ts.Statement, out: Set<string>): voi
   }
 }
 
+/**
+ * Which {@link MapCallbackPreamble.declaredNames} are themselves reactive —
+ * their OWN initializer reads a signal / memo / reactive prop, directly or
+ * transitively through an earlier declaration in the same preamble (#2596).
+ *
+ * Reuses the same Phase-1 classifier (`isReactiveExpression`) already applied
+ * to every non-preamble condition/attribute — this doesn't invent a second
+ * reactivity heuristic, it runs the existing one over one more declaration
+ * list. `ctx.patterns.constants` (the component-level constant chain
+ * `isSignalOrMemoReference`/`isPropsReference` already walk) doesn't reach
+ * these names — they're scoped to the `.map()` callback body, never added to
+ * `ctx.patterns` — so without this pass a preamble local reading a signal is
+ * invisible to the classifier.
+ *
+ * Value-declaration statements only (`const`/`let x = expr`, including
+ * destructuring targets, which mark every bound name reactive together since
+ * they share one initializer). A non-declaration preamble statement
+ * (assignment, loop, side-effecting call) contributes no reactive names —
+ * consistent with `neutralPreambleDeclarations`'s all-or-nothing DSL gate
+ * treating anything past that as un-lowerable, though this walk (client/JS-
+ * runtime SSR only) doesn't require the same all-or-nothing: it simply skips
+ * what it can't classify.
+ */
+function computePreambleReactiveNames(
+  statements: readonly ts.Statement[],
+  ctx: TransformContext,
+): Set<string> {
+  const reactiveNames = new Set<string>()
+  for (const stmt of statements) {
+    if (!ts.isVariableStatement(stmt)) continue
+    for (const decl of stmt.declarationList.declarations) {
+      if (!decl.initializer) continue
+      const boundNames = new Set<string>()
+      collectBindingNames(decl.name, boundNames)
+      const initText = ctx.getJS(decl.initializer)
+      const initFreeRefs = extractFreeIdentifiersFromNode(decl.initializer)
+      const readsEarlierReactive = [...initFreeRefs].some((r) => reactiveNames.has(r))
+      const isReactive = readsEarlierReactive || isReactiveExpression(initText, ctx, decl.initializer)
+      if (isReactive) {
+        for (const n of boundNames) reactiveNames.add(n)
+      }
+    }
+  }
+  return reactiveNames
+}
+
 /**
  * Build a {@link MapCallbackPreamble} from value-only (JSX-free) pre-return
  * statements — the Stage-2 fold preamble and the plain block-body preamble.
@@ -5517,6 +5640,7 @@ function preambleFromValueStatements(
     typedParts.push(raw0.endsWith(';') ? raw0 : raw0 + ';')
     segments.push(tjs !== js ? { kind: 'js', text: js, templateText: tjs } : { kind: 'js', text: js })
   }
+  const reactiveNames = computePreambleReactiveNames(statements, ctx)
   return {
     segments: trimPreambleSegments(segments),
     ssrText: tsxSourceText(typedParts.join(' ')),
@@ -5524,6 +5648,7 @@ function preambleFromValueStatements(
     // Value-only preambles accumulate no JSX, so no child needs the array join.
     builderNames: [],
     declarations: neutralPreambleDeclarations(statements, ctx) ?? undefined,
+    reactiveNames: reactiveNames.size > 0 ? [...reactiveNames] : undefined,
   }
 }
 
@@ -7104,7 +7229,7 @@ function referencesLoopParam(expr: string, ctx: TransformContext): boolean {
   const boundNames = ctx.scope.valueBoundNames()
   if (boundNames.size === 0) return false
   for (const p of boundNames) {
-    if (new RegExp(`\\b${p}\\b`).test(expr)) return true
+    if (identifierPattern(p).test(expr)) return true
   }
   return false
 }
@@ -7238,7 +7363,7 @@ function hasReactiveAttributes(attrs: IRAttribute[], ctx: TransformContext): boo
     const scopeValueNames = ctx.scope.valueBoundNames()
     if (scopeValueNames.size > 0) {
       for (const p of scopeValueNames) {
-        if (new RegExp(`\\b${p}\\b`).test(valueToCheck)) return true
+        if (identifierPattern(p).test(valueToCheck)) return true
       }
     }
   }

package/src/module-exports.ts

@@ -5,7 +5,9 @@
  * This is a compiler-layer concern, not adapter-specific.
  */
 
+import ts from 'typescript'
 import type { ComponentIR, ParamInfo } from './types.ts'
+import { identifierPattern } from './identifier-pattern.ts'
 
 /**
  * Emit module-level exports for local declarations and `export { ... } [from '...']`
@@ -140,7 +142,7 @@ export function findReachableNames(
   const queue: string[] = []
 
   for (const name of allNames) {
-    if (new RegExp(`\\b${name}\\b`).test(primaryRefs)) {
+    if (identifierPattern(name).test(primaryRefs)) {
       reachable.add(name)
       queue.push(name)
     }
@@ -150,7 +152,7 @@ export function findReachableNames(
     const current = queue.shift()!
     const body = bodyMap.get(current) || ''
     for (const name of allNames) {
-      if (!reachable.has(name) && new RegExp(`\\b${name}\\b`).test(body)) {
+      if (!reachable.has(name) && identifierPattern(name).test(body)) {
         reachable.add(name)
         queue.push(name)
       }
@@ -160,6 +162,142 @@ export function findReachableNames(
   return reachable
 }
 
+/**
+ * Which of `candidates` does `bodyText` ASSIGN to?
+ *
+ * Reachability above answers "is this declaration referenced?", which is
+ * the right question for pruning SSR-irrelevant code. It is the wrong
+ * question for a MUTABLE binding: a surviving `let` whose only writer got
+ * pruned is left declared-and-read but never assigned, and TypeScript's
+ * control-flow analysis then narrows it to `never` at every guarded use
+ * (#2598). `closeOverWritersOfMutableBindings` uses this to restore the
+ * missing half of that pair.
+ *
+ * Recognizes the forms that actually write a local binding:
+ *   `x = …`, `x += …` (and every other compound operator), `x++`, `--x`
+ * Destructuring assignment (`[x] = …`, `({ x } = …)`) is deliberately NOT
+ * recognized: it never appears in the ref/handler shapes this exists for,
+ * and a wrong guess here over-retains rather than fails loudly, so leaving
+ * it out keeps the retained set honest. If one shows up, it will present
+ * as this same `never` narrowing and can be added with a fixture.
+ *
+ * Parsed with the TS AST, not matched as text: `identifierPattern` (used
+ * for reference detection above) cannot tell a write from a read, and a
+ * regex for `name\s*=` would match `name == x`, a `name=` inside a string
+ * or JSX attribute, and a property write `obj.name = x` that assigns
+ * nothing of the sort.
+ */
+export function findAssignedNames(
+  bodyText: string,
+  candidates: ReadonlySet<string>,
+): Set<string> {
+  const assigned = new Set<string>()
+  if (candidates.size === 0) return assigned
+
+  const sf = ts.createSourceFile(
+    'bf-assignment-scan.tsx',
+    bodyText,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ false,
+    ts.ScriptKind.TSX,
+  )
+
+  // A bare Identifier on the left of an assignment — `obj.x = …` is a
+  // PropertyAccessExpression and writes through the binding rather than to
+  // it, so it does not count.
+  const record = (target: ts.Node): void => {
+    if (ts.isIdentifier(target) && candidates.has(target.text)) {
+      assigned.add(target.text)
+    }
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isBinaryExpression(node) && isAssignmentOperator(node.operatorToken.kind)) {
+      record(node.left)
+    } else if (
+      (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+      (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken)
+    ) {
+      record(node.operand)
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  ts.forEachChild(sf, visit)
+  return assigned
+}
+
+/**
+ * `findReachableNames`, plus the invariant it cannot express on its own:
+ * **a mutable binding that survives keeps the declarations that write it.**
+ *
+ * Reachability is seeded from the RENDERED JSX, which has already had the
+ * client-only attributes stripped — `ref={setRef}` leaves no `setRef`
+ * behind, and `onClick={handleClick}` is rendered as `onClick={() => {}}`.
+ * That is deliberate: code reachable only from a handler is client-only
+ * and should not be emitted into an SSR template.
+ *
+ * It goes wrong when a `let` outlives its writer. The binding survives
+ * because some OTHER surviving declaration reads it, while its only
+ * assignment lived in a pruned handler — so the emitted template declares
+ * it, reads it, and never assigns it. TypeScript's control-flow analysis
+ * concludes it is permanently `null`, narrows every guarded use to `never`,
+ * and each member access on it fails:
+ *
+ *     let highlightEl: HTMLElement | null = null      // writer was pruned
+ *     const syncScroll = () => {
+ *       if (highlightEl && textareaEl) {
+ *         highlightEl.scrollTop = textareaEl.scrollTop   // TS2339 on `never`
+ *       }
+ *     }
+ *
+ * Pulling the writers back in restores the source's shape for exactly the
+ * bindings that survived — nothing else. The retained writer is dead code
+ * at SSR (it only ever runs from a hydrated event), which is the same
+ * harmless-unused-declaration trade `generateModuleScopeDeclarations`
+ * already makes deliberately.
+ *
+ * Iterates to a fixpoint because a newly retained writer can read further
+ * declarations, and can itself write another mutable binding. Bounded by
+ * the declaration count: each round either adds a name or stops.
+ */
+export function closeOverWritersOfMutableBindings(
+  primaryRefs: string,
+  declarations: { name: string; body: string }[],
+  mutableNames: ReadonlySet<string>,
+): Set<string> {
+  let reachable = findReachableNames(primaryRefs, declarations)
+  if (mutableNames.size === 0) return reachable
+
+  let seedText = primaryRefs
+  for (let round = 0; round <= declarations.length; round++) {
+    const survivingMutables = new Set(
+      [...reachable].filter(name => mutableNames.has(name)),
+    )
+    if (survivingMutables.size === 0) return reachable
+
+    const added = declarations
+      .filter(d => !reachable.has(d.name))
+      .filter(d => findAssignedNames(d.body, survivingMutables).size > 0)
+      .map(d => d.name)
+    if (added.length === 0) return reachable
+
+    // Re-seed by NAME rather than merging sets directly, so each retained
+    // writer's own transitive dependencies come along through the same
+    // traversal instead of a second, divergent one.
+    seedText += '\n' + added.join('\n')
+    reachable = findReachableNames(seedText, declarations)
+  }
+  return reachable
+}
+
+function isAssignmentOperator(kind: ts.SyntaxKind): boolean {
+  return (
+    kind >= ts.SyntaxKind.FirstAssignment &&
+    kind <= ts.SyntaxKind.LastAssignment
+  )
+}
+
 /**
  * Extract parameter names from a function expression string.
  * Handles: arrow functions, single-param arrows, function expressions.

package/src/relocate.ts

@@ -22,6 +22,7 @@ import type {
 } from './adapters/interface.ts'
 import { tsNodeToParsedExpr, type ParsedExpr } from './expression-parser.ts'
 import { prepareLoweringMatchers, type LoweringMatcher } from './lowering-registry.ts'
+import { identifierPattern } from './identifier-pattern.ts'
 
 export interface RelocateEnv {
   /**
@@ -713,7 +714,7 @@ function scanRefsByName(
 ): Map<string, ts.Identifier[]> {
   const result = new Map<string, ts.Identifier[]>()
   for (const name of bindings.keys()) {
-    const re = new RegExp(`\\b${name}\\b`)
+    const re = identifierPattern(name)
     if (re.test(text)) result.set(name, [])
   }
   return result