@barefootjs/jsx 0.37.1 → 0.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/dist/action-accessor.d.ts +159 -0
  2. package/dist/action-accessor.d.ts.map +1 -0
  3. package/dist/adapters/env-signal.d.ts +0 -8
  4. package/dist/adapters/env-signal.d.ts.map +1 -1
  5. package/dist/adapters/interface.d.ts +12 -0
  6. package/dist/adapters/interface.d.ts.map +1 -1
  7. package/dist/adapters/jsx-adapter.d.ts.map +1 -1
  8. package/dist/analyzer.d.ts +61 -1
  9. package/dist/analyzer.d.ts.map +1 -1
  10. package/dist/async-action-refusal.d.ts +45 -0
  11. package/dist/async-action-refusal.d.ts.map +1 -0
  12. package/dist/builtin-lowering-plugins.d.ts.map +1 -1
  13. package/dist/compiler.d.ts.map +1 -1
  14. package/dist/component-root-scope-comment.d.ts +36 -0
  15. package/dist/component-root-scope-comment.d.ts.map +1 -0
  16. package/dist/debug.d.ts +61 -5
  17. package/dist/debug.d.ts.map +1 -1
  18. package/dist/errors.d.ts +7 -0
  19. package/dist/errors.d.ts.map +1 -1
  20. package/dist/event-handler-name.d.ts +13 -0
  21. package/dist/event-handler-name.d.ts.map +1 -0
  22. package/dist/expression-parser.d.ts +9 -0
  23. package/dist/expression-parser.d.ts.map +1 -1
  24. package/dist/format-date-refusal.d.ts +33 -0
  25. package/dist/format-date-refusal.d.ts.map +1 -0
  26. package/dist/index.d.ts +6 -4
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +3260 -1914
  29. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  31. package/dist/ir-to-client-js/compute-inlinability.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/compute-scope.d.ts.map +1 -1
  33. package/dist/ir-to-client-js/control-flow/plan/build-branch-loop.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/control-flow/plan/build-component-loop.d.ts.map +1 -1
  35. package/dist/ir-to-client-js/control-flow/plan/build-composite-loop.d.ts.map +1 -1
  36. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  37. package/dist/ir-to-client-js/control-flow/plan/build-loop.d.ts.map +1 -1
  38. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts +2 -0
  39. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts.map +1 -1
  40. package/dist/ir-to-client-js/control-flow/plan/lazy-row-eligibility.d.ts +1 -1
  41. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts +57 -12
  42. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts.map +1 -1
  43. package/dist/ir-to-client-js/control-flow/shared.d.ts +44 -3
  44. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts +7 -5
  46. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts.map +1 -1
  47. package/dist/ir-to-client-js/csr-substitute.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/declaration-sort.d.ts +2 -1
  49. package/dist/ir-to-client-js/declaration-sort.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/emit-module-level.d.ts.map +1 -1
  51. package/dist/ir-to-client-js/emit-reactive.d.ts +43 -2
  52. package/dist/ir-to-client-js/emit-reactive.d.ts.map +1 -1
  53. package/dist/ir-to-client-js/emit-registration.d.ts.map +1 -1
  54. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  55. package/dist/ir-to-client-js/plan/declaration-emit.d.ts +7 -5
  56. package/dist/ir-to-client-js/plan/declaration-emit.d.ts.map +1 -1
  57. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  58. package/dist/ir-to-client-js/reactivity.d.ts +9 -1
  59. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  60. package/dist/ir-to-client-js/source-map.d.ts.map +1 -1
  61. package/dist/ir-to-client-js/types.d.ts +4 -0
  62. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  63. package/dist/ir-to-client-js/utils.d.ts +66 -1
  64. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  65. package/dist/jsx-to-ir.d.ts.map +1 -1
  66. package/dist/opaque-local-accessor.d.ts +27 -0
  67. package/dist/opaque-local-accessor.d.ts.map +1 -0
  68. package/dist/signal-initializer.d.ts +24 -0
  69. package/dist/signal-initializer.d.ts.map +1 -0
  70. package/dist/template-position-walk.d.ts +68 -0
  71. package/dist/template-position-walk.d.ts.map +1 -0
  72. package/dist/to-locale-date-lowering.d.ts +7 -4
  73. package/dist/to-locale-date-lowering.d.ts.map +1 -1
  74. package/dist/types.d.ts +104 -17
  75. package/dist/types.d.ts.map +1 -1
  76. package/package.json +2 -2
  77. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +878 -4528
  78. package/src/__tests__/action-accessor.test.ts +166 -0
  79. package/src/__tests__/binding-scope-ratchet.test.ts +21 -10
  80. package/src/__tests__/branch-local-in-raw-capture.test.ts +1 -1
  81. package/src/__tests__/branch-local-same-name-collision.test.ts +9 -9
  82. package/src/__tests__/client-js-generation.test.ts +175 -0
  83. package/src/__tests__/component-root-scope-comment.test.ts +106 -0
  84. package/src/__tests__/create-mutation.test.ts +220 -0
  85. package/src/__tests__/create-query.test.ts +644 -0
  86. package/src/__tests__/csr-fragment-root-scope-shape.test.ts +156 -0
  87. package/src/__tests__/debug.test.ts +222 -0
  88. package/src/__tests__/doc-examples.test.ts +78 -25
  89. package/src/__tests__/event-handler-name.test.ts +74 -0
  90. package/src/__tests__/flatmap-segments.test.ts +11 -9
  91. package/src/__tests__/format-date-refusal.test.ts +134 -0
  92. package/src/__tests__/fragment-wrapped-conditional-return-branch.test.ts +132 -0
  93. package/src/__tests__/hydrate-template.test.ts +9 -1
  94. package/src/__tests__/issue-2798-static-nested-loop-bindings.test.ts +2 -2
  95. package/src/__tests__/issue-3009-loop-branch-ref.test.ts +2 -2
  96. package/src/__tests__/issue-3044-nested-prop-object-array-not-static.test.ts +213 -0
  97. package/src/__tests__/issue-3113-init-fn-name-collision.test.ts +133 -0
  98. package/src/__tests__/jsx-return-type-assertion.test.ts +2 -2
  99. package/src/__tests__/lazy-row-eligibility.test.ts +5 -4
  100. package/src/__tests__/loop-row-child-children-reactive-attrs.test.ts +108 -0
  101. package/src/__tests__/loop-row-child-text-children-markers.test.ts +158 -0
  102. package/src/__tests__/opaque-local-accessor.test.ts +90 -0
  103. package/src/__tests__/profiler-e2e.test.ts +13 -8
  104. package/src/__tests__/props-destructuring.test.ts +79 -4
  105. package/src/__tests__/reactive-factory-arity.test.ts +311 -0
  106. package/src/__tests__/ref-attr-absent-at-ssr.test.ts +472 -0
  107. package/src/__tests__/ssr-portal-ref-callback.test.ts +219 -0
  108. package/src/action-accessor.ts +289 -0
  109. package/src/adapters/env-signal.ts +2 -21
  110. package/src/adapters/interface.ts +13 -0
  111. package/src/adapters/jsx-adapter.ts +17 -0
  112. package/src/analyzer.ts +589 -60
  113. package/src/async-action-refusal.ts +254 -0
  114. package/src/builtin-lowering-plugins.ts +0 -2
  115. package/src/compiler.ts +27 -0
  116. package/src/component-root-scope-comment.ts +59 -0
  117. package/src/debug.ts +318 -103
  118. package/src/errors.ts +83 -1
  119. package/src/event-handler-name.ts +14 -0
  120. package/src/expression-parser.ts +41 -17
  121. package/src/format-date-refusal.ts +147 -0
  122. package/src/index.ts +14 -3
  123. package/src/ir-to-client-js/build-references.ts +6 -2
  124. package/src/ir-to-client-js/child-components.ts +8 -3
  125. package/src/ir-to-client-js/collect-elements.ts +28 -13
  126. package/src/ir-to-client-js/compute-inlinability.ts +2 -1
  127. package/src/ir-to-client-js/compute-scope.ts +3 -1
  128. package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts +2 -4
  129. package/src/ir-to-client-js/control-flow/plan/build-component-loop.ts +67 -5
  130. package/src/ir-to-client-js/control-flow/plan/build-composite-loop.ts +3 -6
  131. package/src/ir-to-client-js/control-flow/plan/build-insert.ts +1 -0
  132. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +2 -1
  133. package/src/ir-to-client-js/control-flow/plan/build-loop.ts +23 -11
  134. package/src/ir-to-client-js/control-flow/plan/insert.ts +2 -0
  135. package/src/ir-to-client-js/control-flow/plan/lazy-row-eligibility.ts +3 -3
  136. package/src/ir-to-client-js/control-flow/plan/loop.ts +51 -10
  137. package/src/ir-to-client-js/control-flow/shared.ts +78 -5
  138. package/src/ir-to-client-js/control-flow/stringify/component-loop.ts +25 -12
  139. package/src/ir-to-client-js/control-flow/stringify/insert.ts +1 -1
  140. package/src/ir-to-client-js/csr-substitute.ts +11 -3
  141. package/src/ir-to-client-js/declaration-sort.ts +7 -3
  142. package/src/ir-to-client-js/emit-module-level.ts +7 -4
  143. package/src/ir-to-client-js/emit-reactive.ts +140 -10
  144. package/src/ir-to-client-js/emit-registration.ts +6 -11
  145. package/src/ir-to-client-js/generate-init.ts +2 -2
  146. package/src/ir-to-client-js/html-template.ts +41 -19
  147. package/src/ir-to-client-js/index.ts +9 -3
  148. package/src/ir-to-client-js/phases/ref-callbacks.ts +1 -1
  149. package/src/ir-to-client-js/plan/build-declaration-emit.ts +16 -15
  150. package/src/ir-to-client-js/plan/declaration-emit.ts +7 -5
  151. package/src/ir-to-client-js/prop-handling.ts +4 -0
  152. package/src/ir-to-client-js/reactivity.ts +21 -16
  153. package/src/ir-to-client-js/source-map.ts +2 -1
  154. package/src/ir-to-client-js/stringify/declaration-emit.ts +14 -7
  155. package/src/ir-to-client-js/types.ts +4 -0
  156. package/src/ir-to-client-js/utils.ts +89 -7
  157. package/src/jsx-to-ir.ts +772 -50
  158. package/src/opaque-local-accessor.ts +44 -0
  159. package/src/rich-type-refusal.ts +1 -1
  160. package/src/signal-initializer.ts +36 -0
  161. package/src/template-position-walk.ts +203 -0
  162. package/src/to-locale-date-lowering.ts +7 -4
  163. package/src/types.ts +103 -15
  164. package/dist/format-date-lowering.d.ts +0 -30
  165. package/dist/format-date-lowering.d.ts.map +0 -1
  166. package/src/__tests__/create-selector.test.ts +0 -124
  167. package/src/__tests__/format-date-lowering.test.ts +0 -125
  168. package/src/format-date-lowering.ts +0 -55
package/src/jsx-to-ir.ts CHANGED
@@ -32,7 +32,7 @@ import {
32
32
  type PreambleSegment,
33
33
  type PreambleRegionSource,
34
34
  type PreambleValueDeclaration,
35
- tsxSourceText,
35
+ tsxSourceText, type TsxSourceText,
36
36
  type SourceLocation,
37
37
  type TypeInfo,
38
38
  type OriginInfo,
@@ -54,6 +54,7 @@ import {
54
54
  } from './prop-rewrite.ts'
55
55
  import { boundPropLocalNames, buildPropAliasMap, resolveAliasOrigin, resolveRestSpreadOriginCore, livePropReadExpr } from './props-binding.ts'
56
56
  import { PROPS_PARAM } from './ir-to-client-js/utils.ts'
57
+ import { walkIR } from './ir-to-client-js/walker.ts'
57
58
  import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironment } from './free-refs.ts'
58
59
  import { computeFileScope } from './ir-to-client-js/component-scope.ts'
59
60
  import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template.ts'
@@ -61,13 +62,15 @@ import { extractFreeIdentifiersFromText } from './ir-to-client-js/csr-substitute
61
62
  import { datePlugin, DATE_METHODS } from './date-lowering.ts'
62
63
  import { toLocaleDatePlugin, foldedArgToClientJs } from './to-locale-date-lowering.ts'
63
64
  import type { LoweringMatcher } from './lowering-registry.ts'
64
- import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx, extractMultiReturnJsxBranches, type MultiReturnJsxBranches } from './analyzer.ts'
65
+ import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx, extractMultiReturnJsxBranches, rootIdentifierOf, type MultiReturnJsxBranches } from './analyzer.ts'
65
66
  import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
66
67
  import { reconstructAsSegments } from './strip-types.ts'
67
68
  import { templatePartsToJsExpr } from './template-parts.ts'
68
69
  import { toHTMLAttrName, decodeEntities, BF_KEY, keyAttrName } from '@barefootjs/shared'
69
70
  import { BindingScope } from './scope/binding-scope.ts'
70
71
  import { identifierPattern, identifierCallPattern } from './identifier-pattern.ts'
72
+ import { isEventHandlerName } from './event-handler-name.ts'
73
+ import { seedActionAccessorReads } from './action-accessor.ts'
71
74
 
72
75
  // =============================================================================
73
76
  // Transform Context
@@ -236,6 +239,14 @@ interface TransformContext {
236
239
  * aliased `import { Async as Boundary }` maps `<Boundary>` to the built-in.
237
240
  */
238
241
  _clientBuiltinTags?: Map<string, ClientBuiltinTag>
242
+ /** Lazily computed local name → export name of every `@barefootjs/client` value import. */
243
+ _clientValueImports?: ReadonlyMap<string, string>
244
+ /**
245
+ * BF063 candidates keyed by element position (`line:column`), recorded
246
+ * while transforming and reported by `reportRefAttrsAbsentAtSsr` once the
247
+ * IR shows which elements SSR renders.
248
+ */
249
+ _refAttrAbsences?: Map<string, RefAttrAbsence>
239
250
  /**
240
251
  * Cached `datePlugin` matcher (#2292), bound once to this component's
241
252
  * metadata. `undefined` = not yet computed; `null` = computed and
@@ -284,6 +295,53 @@ function hasLeadingClientDirective(expr: ts.Expression, sourceFile: ts.SourceFil
284
295
  return false
285
296
  }
286
297
 
298
+ /** Whether `node`'s subtree renders any child component (a `component` IR node). */
299
+ function irSubtreeRendersComponent(node: IRNode): boolean {
300
+ let found = false
301
+ walkIR(node, null, {
302
+ component: () => { found = true },
303
+ })
304
+ return found
305
+ }
306
+
307
+ /**
308
+ * #3063: refuse a fragment-wrapped branch of a multi-return client
309
+ * component loudly instead of silently shipping a branch whose events
310
+ * never bind after hydrating existing SSR markup (see
311
+ * `ErrorCodes.FRAGMENT_WRAPPED_CONDITIONAL_RETURN_BRANCH`'s docstring for
312
+ * the mechanism). Called once per branch from `buildIfStatementChain`,
313
+ * right after that branch transforms — `rawNode` is the branch's own raw
314
+ * JSX return expression (needed for the `/* @client *\/` escape check;
315
+ * `transformNode`'s output doesn't retain a pointer back to it), `node` is
316
+ * what that transform produced.
317
+ *
318
+ * Fires when the component hydrates this branch: either it is a
319
+ * `'use client'` component, or the fragment branch itself renders a child
320
+ * component. In the second case a non-client parent still gets
321
+ * `needsInit` and an `initChild` for that child, which runs only if the
322
+ * branch's scope is claimed, so the child's own events never bind either.
323
+ * A non-client component whose fragment branch renders no component has
324
+ * nothing to initialize there and compiles as before. The check is
325
+ * branch-local on purpose: a child component in a DIFFERENT branch doesn't
326
+ * make this branch's missing claim observable.
327
+ */
328
+ function checkFragmentWrappedConditionalReturnBranch(
329
+ node: IRNode | null,
330
+ rawNode: ts.Expression | null | undefined,
331
+ ctx: TransformContext
332
+ ): void {
333
+ if (!node || node.type !== 'fragment' || !(node as IRFragment).needsScopeComment) return
334
+ if (!ctx.analyzer.hasUseClientDirective && !irSubtreeRendersComponent(node)) return
335
+ if (!rawNode || hasLeadingClientDirective(rawNode, ctx.sourceFile)) return
336
+ ctx.analyzer.errors.push(
337
+ createError(ErrorCodes.FRAGMENT_WRAPPED_CONDITIONAL_RETURN_BRANCH, node.loc, {
338
+ suggestion: {
339
+ message: 'Add /* @client */ immediately before this branch\'s JSX to compile it anyway.',
340
+ },
341
+ })
342
+ )
343
+ }
344
+
287
345
  /**
288
346
  * The set of known reactive getter names (signal accessors + memo names) for the
289
347
  * component, built once and cached on `ctx`. These reads are idempotent within a
@@ -1126,19 +1184,25 @@ function resolveRootKeyAttr(node: IRNode | null): void {
1126
1184
  }
1127
1185
 
1128
1186
  export function jsxToIR(analyzer: AnalyzerContext): IRNode | null {
1129
- const root = buildIRRoot(analyzer)
1187
+ const ctx = createTransformContext(analyzer)
1188
+ const root = buildIRRoot(analyzer, ctx)
1130
1189
  if (root) {
1190
+ reportRefAttrsAbsentAtSsr(root, ctx)
1131
1191
  attachParsedExpressions(root, analyzer)
1192
+ // #3166: seed a query/mutation action's `isPending()` / `error()` read
1193
+ // where the seed renders like the reference — `action-accessor.ts`'s gate
1194
+ // decides which positions, the same gate BF117's refusal-lift reads.
1195
+ // Runs on the attached `parsed` trees, so it must follow the attach walk.
1196
+ seedActionAccessorReads(root, analyzer.signals)
1132
1197
  resolveRootKeyAttr(root)
1133
1198
  }
1134
1199
  return root
1135
1200
  }
1136
1201
 
1137
- function buildIRRoot(analyzer: AnalyzerContext): IRNode | null {
1202
+ function buildIRRoot(analyzer: AnalyzerContext, ctx: TransformContext): IRNode | null {
1138
1203
  // If there are conditional returns (if statements with JSX returns),
1139
1204
  // build an if-statement chain instead of a single node
1140
1205
  if (analyzer.conditionalReturns.length > 0) {
1141
- const ctx = createTransformContext(analyzer)
1142
1206
  // #2463: a chain whose conditions are ALL reactive (signal/memo reads)
1143
1207
  // is semantically the root ternary, and the IRIfStatement contract
1144
1208
  // ("client JS handles all branches and switches at runtime") demands
@@ -1174,7 +1238,6 @@ function buildIRRoot(analyzer: AnalyzerContext): IRNode | null {
1174
1238
 
1175
1239
  if (!analyzer.jsxReturn) return null
1176
1240
 
1177
- const ctx = createTransformContext(analyzer)
1178
1241
  const jsxReturn = analyzer.jsxReturn
1179
1242
 
1180
1243
  // Direct JSX return — the IR root is an `IRElement` / `IRFragment` that
@@ -1369,21 +1432,34 @@ function transformNode(node: ts.Node, ctx: TransformContext): IRNode | null {
1369
1432
  function clientBuiltinTags(ctx: TransformContext): Map<string, ClientBuiltinTag> {
1370
1433
  if (ctx._clientBuiltinTags) return ctx._clientBuiltinTags
1371
1434
  const map = new Map<string, ClientBuiltinTag>()
1435
+ for (const [local, name] of clientValueImports(ctx)) {
1436
+ if (isClientBuiltinName(name)) map.set(local, name)
1437
+ }
1438
+ ctx._clientBuiltinTags = map
1439
+ return map
1440
+ }
1441
+
1442
+ /**
1443
+ * Local name → export name of every named VALUE import from
1444
+ * `@barefootjs/client` (`import { createEffect as ce }` → `ce` →
1445
+ * `createEffect`), from the analyzer's import metadata. The one answer to
1446
+ * "is this identifier that client export" for import-scoped recognition — a
1447
+ * same-named local declaration never matches. Value imports only: `import
1448
+ * type { Async }` / `import { type Async }` bring no value binding into scope
1449
+ * (and are never runtime imports) (#1915 review). Memoized on `ctx`; the
1450
+ * import list is fixed for the compile.
1451
+ */
1452
+ function clientValueImports(ctx: TransformContext): ReadonlyMap<string, string> {
1453
+ if (ctx._clientValueImports) return ctx._clientValueImports
1454
+ const map = new Map<string, string>()
1372
1455
  for (const imp of ctx.analyzer.imports) {
1373
- // Require a *value* import: the tag is used as a JSX value, and the design
1374
- // is import-value-required. `import type { Async }` brings no value binding
1375
- // into scope (and is never a runtime import), so it does not scope the
1376
- // built-in — `<Async>` then falls through to BF054 (#1915 review).
1377
1456
  if (imp.source !== CLIENT_BUILTIN_SOURCE || imp.isTypeOnly) continue
1378
1457
  for (const spec of imp.specifiers) {
1379
- // Skip per-specifier `import { type Async }` — no value binding.
1380
1458
  if (spec.isDefault || spec.isNamespace || spec.isTypeOnly) continue
1381
- if (isClientBuiltinName(spec.name)) {
1382
- map.set(spec.alias ?? spec.name, spec.name)
1383
- }
1459
+ map.set(spec.alias ?? spec.name, spec.name)
1384
1460
  }
1385
1461
  }
1386
- ctx._clientBuiltinTags = map
1462
+ ctx._clientValueImports = map
1387
1463
  return map
1388
1464
  }
1389
1465
 
@@ -1694,7 +1770,7 @@ function transformHtmlElement(
1694
1770
  ctx: TransformContext,
1695
1771
  tagName: string
1696
1772
  ): IRElement {
1697
- const { attrs, events, ref } = processAttributes(
1773
+ const { attrs, events, ref, ssrPortalOwnerScope } = processAttributes(
1698
1774
  node.openingElement.attributes,
1699
1775
  ctx
1700
1776
  )
@@ -1726,6 +1802,7 @@ function transformHtmlElement(
1726
1802
  children,
1727
1803
  slotId,
1728
1804
  needsScope,
1805
+ ...(ssrPortalOwnerScope && { ssrPortalOwnerScope }),
1729
1806
  loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
1730
1807
  }
1731
1808
  }
@@ -1759,7 +1836,7 @@ function transformSelfClosingElement(
1759
1836
  return transformSelfClosingComponent(node, ctx, resolved ?? tagName)
1760
1837
  }
1761
1838
 
1762
- const { attrs, events, ref } = processAttributes(node.attributes, ctx)
1839
+ const { attrs, events, ref, ssrPortalOwnerScope } = processAttributes(node.attributes, ctx)
1763
1840
  const selfClosingChildren: IRNode[] = []
1764
1841
  lowerFormControlValueSsr(tagName, attrs, selfClosingChildren)
1765
1842
 
@@ -1779,6 +1856,7 @@ function transformSelfClosingElement(
1779
1856
  children: selfClosingChildren,
1780
1857
  slotId,
1781
1858
  needsScope,
1859
+ ...(ssrPortalOwnerScope && { ssrPortalOwnerScope }),
1782
1860
  loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
1783
1861
  }
1784
1862
  }
@@ -2204,7 +2282,8 @@ function markDataKeyCarrier(children: IRNode[]): IRNode[] {
2204
2282
  * The marked copy of `node` if this subtree can render an element in first
2205
2283
  * position, or null if it cannot.
2206
2284
  *
2207
- * Descends through `conditional` because a fragment whose only top-level
2285
+ * Descends through a nested `fragment` (no DOM of its own) and through
2286
+ * `conditional`, because a fragment whose only top-level
2208
2287
  * child is a ternary or `&&` is still a single-visual-root row —
2209
2288
  * `{done ? <li class="done"/> : <li/>}` renders exactly one `<li>`. A flat
2210
2289
  * `children.findIndex(c => c.type === 'element')` returns -1 there and
@@ -2232,6 +2311,15 @@ function markCarrierIn(node: IRNode): IRNode | null {
2232
2311
  if (!whenTrue && !whenFalse) return null
2233
2312
  return { ...cond, whenTrue: whenTrue ?? cond.whenTrue, whenFalse: whenFalse ?? cond.whenFalse }
2234
2313
  }
2314
+ if (node.type === 'fragment') {
2315
+ // A fragment nested directly inside the root fragment (`<><><li/></></>`)
2316
+ // renders no DOM of its own, so its first element is the row's first
2317
+ // element too — the one the CSR runtime stamps the key on
2318
+ // (`component.ts`'s `roots.find(isElement)`, #2735).
2319
+ const frag = node as IRFragment
2320
+ const children = markDataKeyCarrier(frag.children)
2321
+ return children === frag.children ? null : { ...frag, children }
2322
+ }
2235
2323
  return null
2236
2324
  }
2237
2325
 
@@ -4291,7 +4379,7 @@ function leafIsWirelessElement(el: ts.JsxElement | ts.JsxSelfClosingElement): bo
4291
4379
  if (ts.isJsxSpreadAttribute(attr)) { ok = false; return }
4292
4380
  if (ts.isJsxAttribute(attr)) {
4293
4381
  const name = attr.name.getText()
4294
- if (isEventHandlerAttrName(name)) { ok = false; return }
4382
+ if (isEventHandlerName(name)) { ok = false; return }
4295
4383
  }
4296
4384
  }
4297
4385
  }
@@ -5364,7 +5452,7 @@ function transformMapCall(
5364
5452
  .map((p) => ({
5365
5453
  name: p.name,
5366
5454
  value: p.value,
5367
- isEventHandler: p.name.startsWith('on') && p.name.length > 2,
5455
+ isEventHandler: isEventHandlerName(p.name),
5368
5456
  })),
5369
5457
  children: comp.children,
5370
5458
  }
@@ -5552,11 +5640,16 @@ function buildFlatMapCallback(
5552
5640
  // the map-preamble collector.
5553
5641
  const leafSpans: Array<{ start: number; end: number }> = []
5554
5642
  const leafIrs: IRNode[] = []
5643
+ const leafKeyAttrs: ts.JsxAttribute[] = []
5555
5644
  let refusalNode: ts.Node | undefined
5556
5645
  const collectJsx = (n: ts.Node, underTemplate: boolean): void => {
5557
5646
  if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n)) {
5558
5647
  if (underTemplate) refusalNode ??= n
5559
5648
  leafSpans.push({ start: n.getStart(ctx.sourceFile), end: n.getEnd() })
5649
+ if (!ts.isJsxFragment(n)) {
5650
+ const keyAttr = findKeyJsxAttribute(ts.isJsxElement(n) ? n.openingElement : n)
5651
+ if (keyAttr) leafKeyAttrs.push(keyAttr)
5652
+ }
5560
5653
  const ir = transformNode(n as ts.Expression, ctx)
5561
5654
  leafIrs.push(ir ?? { type: 'text', value: '', loc: getSourceLocation(n, ctx.sourceFile, ctx.filePath) })
5562
5655
  return
@@ -5662,8 +5755,50 @@ function buildFlatMapCallback(
5662
5755
  return {
5663
5756
  params: `(${paramsText})`,
5664
5757
  segments,
5665
- rawBody: tsxSourceText(body.getText(ctx.sourceFile)),
5758
+ rawBody: flatMapRawBodyWithLeafKeys(body, leafKeyAttrs, ctx.sourceFile),
5759
+ }
5760
+ }
5761
+
5762
+ /**
5763
+ * The raw TSX body a JSX-runtime SSR adapter evaluates, with every keyed
5764
+ * leaf's reconciliation attribute made explicit: ` data-key={String(<key>)}`
5765
+ * spliced in right after the leaf's own `key={…}` attribute. A JSX runtime
5766
+ * strips `key` from the rendered HTML, so without this the server row
5767
+ * carries no `data-key` while the client runtime stamps one on every row it
5768
+ * adopts or creates (`mapArray`'s `BF_KEY` default — the descriptor path
5769
+ * never passes a depth-suffixed name) — a pre-/post-hydration divergence on
5770
+ * exactly the attribute reconciliation keys on. `String(...)` matches the
5771
+ * client's `String(__bfD.k ?? __bfI)` stamping, and the runtime escapes the
5772
+ * value like any other attribute. Position-based splice over the AST's own
5773
+ * attribute spans — the body text is never pattern-matched.
5774
+ */
5775
+ function flatMapRawBodyWithLeafKeys(
5776
+ body: ts.Block | ts.Expression,
5777
+ leafKeyAttrs: readonly ts.JsxAttribute[],
5778
+ sourceFile: ts.SourceFile,
5779
+ ): TsxSourceText {
5780
+ const text = body.getText(sourceFile)
5781
+ if (leafKeyAttrs.length === 0) return tsxSourceText(text)
5782
+ const bodyStart = body.getStart(sourceFile)
5783
+ const insertions = leafKeyAttrs
5784
+ .map((attr) => {
5785
+ const init = attr.initializer
5786
+ const keyText = init === undefined
5787
+ ? 'true'
5788
+ : ts.isJsxExpression(init)
5789
+ ? (init.expression?.getText(sourceFile) ?? 'undefined')
5790
+ : init.getText(sourceFile)
5791
+ return { at: attr.getEnd() - bodyStart, text: ` ${BF_KEY}={String(${keyText})}` }
5792
+ })
5793
+ .sort((a, b) => a.at - b.at)
5794
+ let out = ''
5795
+ let cursor = 0
5796
+ for (const { at, text: ins } of insertions) {
5797
+ out += text.slice(cursor, at) + ins
5798
+ cursor = at
5666
5799
  }
5800
+ out += text.slice(cursor)
5801
+ return tsxSourceText(out)
5667
5802
  }
5668
5803
 
5669
5804
  /**
@@ -6092,7 +6227,7 @@ function neutralPreambleDeclarations(
6092
6227
  // JSX attribute position, e.g. `const handleClick = () => {...}`) has
6093
6228
  // no template-expression form on any backend — no DSL here has a
6094
6229
  // callable value. But every adapter's own SSR component-prop builder
6095
- // already skips an event-handler prop (`isEventHandlerAttrName`)
6230
+ // already skips an event-handler prop (`isEventHandlerName`)
6096
6231
  // outright, so a name read ONLY that way needs no SSR representation
6097
6232
  // at all — elide the declaration instead of refusing the whole
6098
6233
  // preamble. The client-JS preamble (`segments`, not `declarations`)
@@ -6131,7 +6266,7 @@ function isFunctionLiteral(node: ts.Expression): boolean {
6131
6266
  * Whether every read of `name` in `bodyStatements`, other than its own
6132
6267
  * binding site, sits inside an event-handler `JsxAttribute`'s
6133
6268
  * (`onClick`/`onInput`/...) value — i.e. `name={<ident>}` where the
6134
- * attribute's own name passes {@link isEventHandlerAttrName}, the exact
6269
+ * attribute's own name passes {@link isEventHandlerName}, the exact
6135
6270
  * predicate every DSL adapter's own SSR prop-builder already uses to skip an
6136
6271
  * event-handler prop (e.g. `packages/adapter-jinja/src/adapter/
6137
6272
  * jinja-adapter.ts`'s `renderComponent`, `packages/adapter-go-template/...`'s
@@ -6165,7 +6300,7 @@ function everyReadIsEventHandlerPropValue(name: string, bodyStatements: readonly
6165
6300
  ts.isJsxAttribute(attr) &&
6166
6301
  attr.initializer === jsxExpr &&
6167
6302
  ts.isIdentifier(attr.name) &&
6168
- isEventHandlerAttrName(attr.name.text)
6303
+ isEventHandlerName(attr.name.text)
6169
6304
  if (!isEventHandlerAttrValue) return true
6170
6305
  }
6171
6306
  }
@@ -6174,18 +6309,6 @@ function everyReadIsEventHandlerPropValue(name: string, bodyStatements: readonly
6174
6309
  return !bodyStatements.some(findDisallowedRead)
6175
6310
  }
6176
6311
 
6177
- /**
6178
- * Whether a JSX attribute name is an event handler (`onClick`, `onInput`,
6179
- * ...) rather than a plain attribute/prop. Shared by every site in this file
6180
- * that needs the same call: native-element attribute extraction (routes into
6181
- * `IREvent`, never rendered HTML), the preamble-verbatim-leaf wiring guard,
6182
- * and {@link everyReadIsEventHandlerPropValue}'s elision safety check — one
6183
- * decision, one implementation, per CLAUDE.md.
6184
- */
6185
- function isEventHandlerAttrName(name: string): boolean {
6186
- return /^on[A-Z]/.test(name)
6187
- }
6188
-
6189
6312
  /** Drop the trailing separator space from the final js segment. */
6190
6313
  function trimPreambleSegments(segments: PreambleSegment[]): PreambleSegment[] {
6191
6314
  const last = segments[segments.length - 1]
@@ -6326,7 +6449,7 @@ function collectNestedComponents(nodes: IRNode[]): IRLoopChildComponent[] {
6326
6449
  .map(p => ({
6327
6450
  name: p.name,
6328
6451
  value: p.value,
6329
- isEventHandler: p.name.startsWith('on') && p.name.length > 2,
6452
+ isEventHandler: isEventHandlerName(p.name),
6330
6453
  })),
6331
6454
  children: node.children,
6332
6455
  loopDepth,
@@ -6375,6 +6498,8 @@ interface ProcessedAttributes {
6375
6498
  attrs: IRAttribute[]
6376
6499
  events: IREvent[]
6377
6500
  ref: string | null
6501
+ /** See {@link isSsrPortalRefCallback}. */
6502
+ ssrPortalOwnerScope: boolean
6378
6503
  }
6379
6504
 
6380
6505
  // Spread expansion: shared between HTML attrs and component props.
@@ -6510,9 +6635,12 @@ function processAttributes(
6510
6635
  const attrs: IRAttribute[] = []
6511
6636
  const events: IREvent[] = []
6512
6637
  let ref: string | null = null
6638
+ let refExpr: ts.Expression | null = null
6639
+ let hasSpread = false
6513
6640
 
6514
6641
  for (const attr of attributes.properties) {
6515
6642
  if (ts.isJsxSpreadAttribute(attr)) {
6643
+ hasSpread = true
6516
6644
  attrs.push(...expandSpreadAttribute(attr, ctx))
6517
6645
  continue
6518
6646
  }
@@ -6529,6 +6657,7 @@ function processAttributes(
6529
6657
  if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
6530
6658
  reportJsxBranchLocalInCallback(attr.initializer.expression, ctx)
6531
6659
  ref = ctx.getJS(attr.initializer.expression)
6660
+ refExpr = attr.initializer.expression
6532
6661
  }
6533
6662
  continue
6534
6663
  }
@@ -6537,7 +6666,7 @@ function processAttributes(
6537
6666
  // they're wired up at hydration time (delegated event registration) and
6538
6667
  // must not leak into rendered HTML. The DOM event name is lowercase
6539
6668
  // (`click`, not `Click`), so strip the `on` prefix and downcase.
6540
- if (isEventHandlerAttrName(rawName)) {
6669
+ if (isEventHandlerName(rawName)) {
6541
6670
  if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
6542
6671
  const eventName = rawName.slice(2).toLowerCase()
6543
6672
  reportJsxBranchLocalInCallback(attr.initializer.expression, ctx)
@@ -6600,7 +6729,538 @@ function processAttributes(
6600
6729
  })
6601
6730
  }
6602
6731
 
6603
- return { attrs, events, ref }
6732
+ // The ref callback is resolved once, for both the SSR-portal recognition
6733
+ // and BF063. BF063 runs after the loop so it sees every attribute this
6734
+ // element's JSX renders, whether `ref` came before or after it.
6735
+ let ssrPortalOwnerScope = false
6736
+ if (refExpr) {
6737
+ const refCallback = resolveRefCallback(refExpr)
6738
+ ssrPortalOwnerScope = isSsrPortalRefCallback(refCallback)
6739
+ if (!hasSpread) recordRefAttrsAbsentAtSsr(refExpr, refCallback, attributes, attrs, ctx)
6740
+ }
6741
+
6742
+ return { attrs, events, ref, ssrPortalOwnerScope }
6743
+ }
6744
+
6745
+ // =============================================================================
6746
+ // Ref-written attribute absent at SSR (BF063)
6747
+ // =============================================================================
6748
+
6749
+ /**
6750
+ * BF063: a `ref` callback that unconditionally writes an attribute at mount
6751
+ * which the element's own JSX never renders. A `ref` callback never runs at
6752
+ * SSR, so the server HTML always lacks that attribute and the first client
6753
+ * pass adds it — the pre- and post-hydration DOM differ, a visible snap at
6754
+ * the hydrate boundary.
6755
+ *
6756
+ * Deliberately narrow, so it only fires where the divergence is certain:
6757
+ *
6758
+ * - The callback resolves statically (`resolveRefCallback`): an inline
6759
+ * arrow / function expression, or a named local function. Anything else
6760
+ * — an imported helper, a prop, a call result — is opaque.
6761
+ * - Only mount-time writes to the callback's own element parameter count
6762
+ * (see `collectMountAttrWrites`), and only those no later removal
6763
+ * cancels.
6764
+ * - An attribute the JSX renders in any form is skipped: SSR emits it, and
6765
+ * whether an effect's first run agrees with the rendered value is not
6766
+ * decidable here — `data-state="closed"` overwritten by an effect that
6767
+ * computes `closed` on mount is the correct, common case.
6768
+ * - An element with a spread (`{...props}`, which may render the
6769
+ * attribute) is skipped by the caller, and a leading `/* @client *\/` on
6770
+ * the ref expression opts out (the author accepts the attribute
6771
+ * appearing only after hydration).
6772
+ *
6773
+ * Whether SSR renders the element at all is only known once the IR is built
6774
+ * (a client-only conditional or loop around it), so this records a
6775
+ * candidate and `reportRefAttrsAbsentAtSsr` decides.
6776
+ */
6777
+ function recordRefAttrsAbsentAtSsr(
6778
+ refExpr: ts.Expression,
6779
+ callback: RefCallback | undefined,
6780
+ attributes: ts.JsxAttributes,
6781
+ attrs: readonly IRAttribute[],
6782
+ ctx: TransformContext,
6783
+ ): void {
6784
+ if (!callback?.param || hasLeadingClientDirective(refExpr, ctx.sourceFile)) return
6785
+ const rendered = new Set(attrs.map(a => a.name.toLowerCase()))
6786
+ const writes = collectMountAttrWrites(callback.body, callback.param, ctx).filter(w => !rendered.has(w.name))
6787
+ if (writes.length === 0) return
6788
+ const element = attributes.parent
6789
+ const key = sourcePositionKey(getSourceLocation(element, ctx.sourceFile, ctx.filePath))
6790
+ ctx._refAttrAbsences ??= new Map()
6791
+ ctx._refAttrAbsences.set(key, { element: `<${element.tagName.getText(ctx.sourceFile)}> at ${key}`, writes })
6792
+ }
6793
+
6794
+ /** `line:column` of a location's start — the `-->` notation `formatError` prints. */
6795
+ function sourcePositionKey(loc: SourceLocation): string {
6796
+ return `${loc.start.line}:${loc.start.column}`
6797
+ }
6798
+
6799
+ /**
6800
+ * Report the candidates `recordRefAttrsAbsentAtSsr` recorded on elements SSR
6801
+ * actually renders. An element inside a client-only conditional or loop (a
6802
+ * `/* @client *\/` child, a module-level client signal, an auto-deferred
6803
+ * reactive-brand condition — whatever set the IR's `clientOnly`) never
6804
+ * reaches the server HTML, so there is nothing for hydration to diverge
6805
+ * from. One error per write site: a handler shared by several elements is
6806
+ * reported once, naming every element that lacks the attribute.
6807
+ */
6808
+ function reportRefAttrsAbsentAtSsr(root: IRNode, ctx: TransformContext): void {
6809
+ const pending = ctx._refAttrAbsences
6810
+ if (!pending) return
6811
+ const bySite = new Map<string, { write: RefAttrWrite; elements: string[] }>()
6812
+ walkIR<boolean>(root, false, {
6813
+ element: ({ node, scope: clientOnly, descend }) => {
6814
+ const key = sourcePositionKey(node.loc)
6815
+ const absence = clientOnly ? undefined : pending.get(key)
6816
+ if (absence) {
6817
+ // A source element transformed more than once (an inlined JSX
6818
+ // helper) is still one element.
6819
+ pending.delete(key)
6820
+ for (const write of absence.writes) {
6821
+ const site = `${write.node.getStart(ctx.sourceFile)}:${write.name}`
6822
+ const group = bySite.get(site) ?? { write, elements: [] }
6823
+ group.elements.push(absence.element)
6824
+ bySite.set(site, group)
6825
+ }
6826
+ }
6827
+ descend()
6828
+ },
6829
+ conditional: ({ node, scope, descend }) => descend(scope || !!node.clientOnly),
6830
+ loop: ({ node, scope, descend }) => descend(scope || !!node.clientOnly),
6831
+ async: ({ node, walk, descend }) => {
6832
+ walk(node.fallback)
6833
+ descend()
6834
+ },
6835
+ component: ({ descend, descendJsxChildren }) => {
6836
+ descend()
6837
+ descendJsxChildren()
6838
+ },
6839
+ })
6840
+ for (const { write, elements } of bySite.values()) {
6841
+ ctx.analyzer.errors.push(
6842
+ createError(ErrorCodes.REF_ATTR_ABSENT_AT_SSR, getSourceLocation(write.node, ctx.sourceFile, ctx.filePath), {
6843
+ message:
6844
+ `The ref callback writes '${write.name}' on mount, but the JSX of ${elements.join(' and ')} never renders it. ` +
6845
+ 'A ref callback never runs at SSR, so the server HTML lacks the attribute and hydration adds it — ' +
6846
+ 'the DOM visibly changes at the hydrate boundary.',
6847
+ suggestion: {
6848
+ message:
6849
+ `Render '${write.name}' in the element's JSX from props or signals (e.g. \`${write.name}={…}\`) so SSR ` +
6850
+ 'and hydration agree — the ref may keep writing it afterwards. Or add /* @client */ before the ref ' +
6851
+ 'expression to accept the attribute appearing only after hydration.',
6852
+ escape: [{ kind: 'rewrite' }, { kind: 'client-directive' }],
6853
+ },
6854
+ }),
6855
+ )
6856
+ }
6857
+ }
6858
+
6859
+ /** A BF063 candidate awaiting `reportRefAttrsAbsentAtSsr`. */
6860
+ interface RefAttrAbsence {
6861
+ /** `<tag> at line:column`, naming the element in the diagnostic. */
6862
+ element: string
6863
+ /** Mount-time writes of attributes this element's JSX never renders. */
6864
+ writes: RefAttrWrite[]
6865
+ }
6866
+
6867
+ interface RefAttrWrite {
6868
+ /** Lower-cased HTML attribute name (`data-*` for a `dataset` write). */
6869
+ name: string
6870
+ node: ts.Node
6871
+ }
6872
+
6873
+ /** Mount-time primitives: both run their callback synchronously on creation. */
6874
+ const MOUNT_TIME_PRIMITIVES: ReadonlySet<string> = new Set(['createEffect', 'onMount'])
6875
+
6876
+ /**
6877
+ * The writes to `param` in a ref body that are certain to have happened, and
6878
+ * not been undone, when the ref's mount-time run ends — first write per
6879
+ * attribute, in order.
6880
+ *
6881
+ * The run is the ref body's top-level statements plus, inline at their call
6882
+ * position, the top-level statements of a `createEffect` / `onMount` callback
6883
+ * that is itself a top-level statement of the ref body (both run
6884
+ * synchronously on creation). Within it:
6885
+ *
6886
+ * - A write is a top-level `param.setAttribute('<lit>', …)`,
6887
+ * `param.dataset.<key> = …` or `param.dataset['<key>'] = …`; writes
6888
+ * anywhere else (under an `if`, in a listener, a timer, any closure) may
6889
+ * never run on mount and are ignored.
6890
+ * - A top-level `param.removeAttribute('<lit>')` / `delete
6891
+ * param.dataset.<key>` cancels the earlier write; a removal under an
6892
+ * `if`, a loop, … makes it uncertain, so cancels it too.
6893
+ * - A statement holding a `return` / `throw` of its function (an early-exit
6894
+ * guard, a `try` / loop / `switch` that can return) may skip everything
6895
+ * after it, so collection stops there — for the whole run, since a
6896
+ * `throw` in a nested callback propagates out of the ref.
6897
+ * - A body that redeclares `param` (a `const` / `var` / `function` /
6898
+ * destructuring, or a nested callback parameter) writes some other
6899
+ * node, so contributes nothing.
6900
+ */
6901
+ function collectMountAttrWrites(body: ts.ConciseBody, param: string, ctx: TransformContext): RefAttrWrite[] {
6902
+ const live = new Map<string, RefAttrWrite>()
6903
+ const apply = (effect: RefAttrEffect): void => {
6904
+ if (effect.kind === 'remove') live.delete(effect.name)
6905
+ else if (!live.has(effect.name)) live.set(effect.name, effect)
6906
+ }
6907
+ // Removals anywhere in `node` outside nested closures; true when it can
6908
+ // end the run early.
6909
+ const scan = (node: ts.Node): boolean => {
6910
+ let exits = false
6911
+ const visit = (n: ts.Node): void => {
6912
+ if (ts.isFunctionLike(n) || ts.isClassLike(n)) return
6913
+ if (ts.isReturnStatement(n) || ts.isThrowStatement(n)) exits = true
6914
+ const effect = matchRefAttrEffect(n, param)
6915
+ if (effect?.kind === 'remove') live.delete(effect.name)
6916
+ ts.forEachChild(n, visit)
6917
+ }
6918
+ visit(node)
6919
+ return exits
6920
+ }
6921
+ // False when the run may have ended before this body's end.
6922
+ const run = (fnBody: ts.ConciseBody, allowNested: boolean): boolean => {
6923
+ if (findScopeDeclaration(param, fnBody)) return true
6924
+ const units: readonly ts.Node[] = ts.isBlock(fnBody) ? fnBody.statements : [fnBody]
6925
+ for (const unit of units) {
6926
+ const expr = ts.isExpressionStatement(unit) ? unit.expression : ts.isExpression(unit) ? unit : undefined
6927
+ const effect = expr && matchRefAttrEffect(expr, param)
6928
+ if (effect) {
6929
+ apply(effect)
6930
+ continue
6931
+ }
6932
+ const nested = expr && allowNested ? mountCallbackBody(expr, param, ctx) : undefined
6933
+ if (nested ? !run(nested, false) : scan(unit)) return false
6934
+ }
6935
+ return true
6936
+ }
6937
+ run(body, true)
6938
+ return [...live.values()]
6939
+ }
6940
+
6941
+ /**
6942
+ * `createEffect(() => {…})` / `onMount(function () {…})` → the callback body,
6943
+ * unless its parameters rebind `param`. The callee must be a value import of
6944
+ * the primitive from `@barefootjs/client` (an alias included), so a local
6945
+ * function that happens to be named `onMount` is not one.
6946
+ */
6947
+ function mountCallbackBody(expr: ts.Expression, param: string, ctx: TransformContext): ts.ConciseBody | undefined {
6948
+ const call = unwrapTransparentTsWrappers(expr)
6949
+ if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression)) return undefined
6950
+ const primitive = clientValueImports(ctx).get(call.expression.text)
6951
+ if (!primitive || !MOUNT_TIME_PRIMITIVES.has(primitive)) return undefined
6952
+ const fn = call.arguments[0] && unwrapTransparentTsWrappers(call.arguments[0])
6953
+ if (!fn || !(ts.isArrowFunction(fn) || ts.isFunctionExpression(fn))) return undefined
6954
+ if (fn.parameters.some(p => bindingDeclares(p.name, param))) return undefined
6955
+ return fn.body
6956
+ }
6957
+
6958
+ interface RefAttrEffect extends RefAttrWrite {
6959
+ kind: 'set' | 'remove'
6960
+ }
6961
+
6962
+ /**
6963
+ * `param.setAttribute('<lit>', …)` / `param.dataset.<key> = …` (a set) or
6964
+ * `param.removeAttribute('<lit>')` / `delete param.dataset.<key>` (a remove).
6965
+ */
6966
+ function matchRefAttrEffect(node: ts.Node, param: string): RefAttrEffect | undefined {
6967
+ if (!ts.isExpression(node)) return undefined
6968
+ const expr = unwrapTransparentTsWrappers(node)
6969
+ if (ts.isCallExpression(expr)) {
6970
+ const callee = expr.expression
6971
+ if (!ts.isPropertyAccessExpression(callee)) return undefined
6972
+ const kind = callee.name.text === 'setAttribute' ? 'set' : callee.name.text === 'removeAttribute' ? 'remove' : undefined
6973
+ const [nameArg] = expr.arguments
6974
+ if (kind && nameArg && ts.isStringLiteralLike(nameArg) && isParamReference(callee.expression, param)) {
6975
+ return { kind, name: nameArg.text.toLowerCase(), node: expr }
6976
+ }
6977
+ return undefined
6978
+ }
6979
+ const target =
6980
+ ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.EqualsToken ? { kind: 'set' as const, lhs: expr.left }
6981
+ : ts.isDeleteExpression(expr) ? { kind: 'remove' as const, lhs: expr.expression }
6982
+ : undefined
6983
+ const name = target && datasetAttrName(target.lhs, param)
6984
+ return name ? { kind: target.kind, name, node: expr } : undefined
6985
+ }
6986
+
6987
+ /** `param.dataset.<key>` / `param.dataset['<key>']` → the `data-*` attribute it maps to. */
6988
+ function datasetAttrName(target: ts.Expression, param: string): string | undefined {
6989
+ const access = unwrapTransparentTsWrappers(target)
6990
+ const key = ts.isPropertyAccessExpression(access)
6991
+ ? access.name.text
6992
+ : ts.isElementAccessExpression(access) && ts.isStringLiteralLike(access.argumentExpression)
6993
+ ? access.argumentExpression.text
6994
+ : undefined
6995
+ if (key === undefined) return undefined
6996
+ const dataset = unwrapTransparentTsWrappers((access as ts.PropertyAccessExpression | ts.ElementAccessExpression).expression)
6997
+ if (!ts.isPropertyAccessExpression(dataset) || dataset.name.text !== 'dataset') return undefined
6998
+ return isParamReference(dataset.expression, param) ? datasetKeyToAttrName(key) : undefined
6999
+ }
7000
+
7001
+ function isParamReference(expr: ts.Expression, param: string): boolean {
7002
+ const inner = unwrapTransparentTsWrappers(expr)
7003
+ return ts.isIdentifier(inner) && inner.text === param
7004
+ }
7005
+
7006
+ /** `nmOpenDelay` → `data-nm-open-delay` (the DOMStringMap camelCase → attribute mapping). */
7007
+ function datasetKeyToAttrName(key: string): string {
7008
+ let out = 'data-'
7009
+ for (const ch of key) {
7010
+ out += ch >= 'A' && ch <= 'Z' ? `-${ch.toLowerCase()}` : ch
7011
+ }
7012
+ return out
7013
+ }
7014
+
7015
+ // =============================================================================
7016
+ // Ref callback resolution
7017
+ // =============================================================================
7018
+
7019
+ interface LocalCallback {
7020
+ param: string | undefined
7021
+ body: ts.ConciseBody
7022
+ }
7023
+
7024
+ interface RefCallback extends LocalCallback {
7025
+ /** Bound by name (`ref={handleMount}`) rather than written inline. */
7026
+ named: boolean
7027
+ /**
7028
+ * True only for a named callback declared in the `ref`'s innermost
7029
+ * enclosing function scope; false for an inline callback and for one
7030
+ * `findNamedCallback`'s outward walk found further out (e.g. a `ref` in a
7031
+ * `.map()` row naming a component-body handler). BF063 ignores this;
7032
+ * `isSsrPortalRefCallback` requires it.
7033
+ */
7034
+ innermostScope: boolean
7035
+ }
7036
+
7037
+ /**
7038
+ * Resolve a `ref={…}` expression to its callback's first param + body, when
7039
+ * statically visible: an inline arrow / function expression, or an
7040
+ * identifier naming a local function (`findNamedCallback`). Resolved once per
7041
+ * element and shared by the SSR-portal recognition and BF063.
7042
+ */
7043
+ function resolveRefCallback(refExpr: ts.Expression): RefCallback | undefined {
7044
+ const expr = unwrapTransparentTsWrappers(refExpr)
7045
+ if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
7046
+ return { param: firstSimpleParamName(expr), body: expr.body, named: false, innermostScope: false }
7047
+ }
7048
+ if (!ts.isIdentifier(expr)) return undefined
7049
+ const resolved = findNamedCallback(expr)
7050
+ return resolved && { ...resolved.callback, named: true, innermostScope: resolved.innermostScope }
7051
+ }
7052
+
7053
+ type FunctionLike = ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration
7054
+
7055
+ function isFunctionLike(node: ts.Node): node is FunctionLike {
7056
+ return ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node)
7057
+ }
7058
+
7059
+ /**
7060
+ * Walk `.parent` links up from `node` to the nearest enclosing function
7061
+ * (arrow, function expression, or `function` declaration).
7062
+ */
7063
+ function findEnclosingFunctionLike(node: ts.Node): FunctionLike | undefined {
7064
+ let current: ts.Node | undefined = node.parent
7065
+ while (current) {
7066
+ if (isFunctionLike(current)) return current
7067
+ current = current.parent
7068
+ }
7069
+ return undefined
7070
+ }
7071
+
7072
+ /**
7073
+ * Resolve `ident` to a NAMED local function (`const name = (…) => {…}`,
7074
+ * `const name = function (…) {…}`, or `function name(…) {…}`), searching the
7075
+ * enclosing function scopes innermost-first up to the outermost — the
7076
+ * component — so a `ref` inside a `.map()` row arrow still finds a handler
7077
+ * declared in the component body. The first scope binding the name decides:
7078
+ * a parameter, or a declaration that is not a function, makes it opaque.
7079
+ * Never searches a nested function's own body: two sibling components in the
7080
+ * same file can each declare their own, unrelated `handleMount`, and reaching
7081
+ * into the wrong one's closure would misattribute its behavior to this `ref`.
7082
+ * `innermostScope` reports whether the deciding scope was the `ref`'s own
7083
+ * innermost one: BF063 accepts any scope, the SSR-portal recognition only
7084
+ * that one (see `isSsrPortalRefCallback`).
7085
+ */
7086
+ function findNamedCallback(
7087
+ ident: ts.Identifier,
7088
+ ): { callback: LocalCallback; innermostScope: boolean } | undefined {
7089
+ const innermost = findEnclosingFunctionLike(ident)
7090
+ for (let fn = innermost; fn; fn = findEnclosingFunctionLike(fn)) {
7091
+ if (fn.parameters.some(p => bindingDeclares(p.name, ident.text))) return undefined
7092
+ const decl = fn.body && findScopeDeclaration(ident.text, fn.body)
7093
+ if (!decl) continue
7094
+ const callback = localCallbackOf(decl)
7095
+ return callback && { callback, innermostScope: fn === innermost }
7096
+ }
7097
+ return undefined
7098
+ }
7099
+
7100
+ /** The callback a scope declaration binds, when it binds a function at all. */
7101
+ function localCallbackOf(
7102
+ decl: ts.VariableDeclaration | ts.FunctionDeclaration | ts.ClassDeclaration,
7103
+ ): LocalCallback | undefined {
7104
+ if (ts.isFunctionDeclaration(decl)) return decl.body && { param: firstSimpleParamName(decl), body: decl.body }
7105
+ const init = ts.isVariableDeclaration(decl) && ts.isIdentifier(decl.name) && decl.initializer
7106
+ ? unwrapTransparentTsWrappers(decl.initializer)
7107
+ : undefined
7108
+ return init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))
7109
+ ? { param: firstSimpleParamName(init), body: init.body }
7110
+ : undefined
7111
+ }
7112
+
7113
+ /**
7114
+ * The first declaration of `name` in `scopeBody` — a `const` / `let` / `var`
7115
+ * (destructuring included), a `function` with a body (not an overload
7116
+ * signature) or a `class` — at any block depth, but never inside a nested
7117
+ * function or class, which scope their own names. Block depth is not
7118
+ * distinguished (a `const` inside an `if` block counts too): both callers
7119
+ * want a conservative "is this name rebound here" answer.
7120
+ */
7121
+ function findScopeDeclaration(
7122
+ name: string,
7123
+ scopeBody: ts.Node,
7124
+ ): ts.VariableDeclaration | ts.FunctionDeclaration | ts.ClassDeclaration | undefined {
7125
+ let found: ts.VariableDeclaration | ts.FunctionDeclaration | ts.ClassDeclaration | undefined
7126
+ const visit = (node: ts.Node): void => {
7127
+ if (found) return
7128
+ if (ts.isVariableDeclaration(node) && bindingDeclares(node.name, name)) {
7129
+ found = node
7130
+ return
7131
+ }
7132
+ if (((ts.isFunctionDeclaration(node) && node.body) || ts.isClassDeclaration(node)) && node.name?.text === name) {
7133
+ found = node
7134
+ return
7135
+ }
7136
+ if (ts.isFunctionLike(node) || ts.isClassLike(node)) return
7137
+ ts.forEachChild(node, visit)
7138
+ }
7139
+ visit(scopeBody)
7140
+ return found
7141
+ }
7142
+
7143
+ function bindingDeclares(binding: ts.BindingName, name: string): boolean {
7144
+ const names = new Set<string>()
7145
+ collectBindingNames(binding, names)
7146
+ return names.has(name)
7147
+ }
7148
+
7149
+ // =============================================================================
7150
+ // SSR portal ref-callback recognition (#3059)
7151
+ // =============================================================================
7152
+
7153
+ /**
7154
+ * Structural (AST-only, no text/regex matching) recognition of the
7155
+ * `ref`-callback portal pattern the Dialog/DropdownMenu/Popover/Portal
7156
+ * primitives use: a `ref` bound to a LOCAL, NAMED function (arrow-const,
7157
+ * function-expression-const, or `function` declaration) whose body — at
7158
+ * any statement depth, e.g. inside an `if` guard — directly calls
7159
+ * `createPortal(<the callback's own first param>, document.body, { ownerScope: … })`.
7160
+ *
7161
+ * Recognizing only the DIRECT call (never through a second helper
7162
+ * function) is a deliberate, checked choice, not a shortcut: every
7163
+ * shipped `ref`-callback portal user (dialog, dropdown-menu, popover,
7164
+ * portal, combobox, select) calls `createPortal` directly inside the
7165
+ * `ref` callback itself (`SelectContent`/`ComboboxContent`'s deferral
7166
+ * through `queueMicrotask` is still the SAME callback's own call, not a
7167
+ * second helper — see `containsSsrPortalPlacementCall`'s docstring) —
7168
+ * there is no indirection through a shared `moveToBody`-style helper
7169
+ * anywhere in `ui/components/ui/*` today. Recognizing through a helper
7170
+ * (the "worth the scope-walk?" open question from #3059) is therefore
7171
+ * left for when a real caller needs it.
7172
+ *
7173
+ * The callback must be declared in the `ref`'s INNERMOST enclosing
7174
+ * function scope (`RefCallback.innermostScope`) — BF063 shares the
7175
+ * resolution but may walk further out; this recognition may not. The gate
7176
+ * only restores the scope limit recognition had before BF063 widened the
7177
+ * lookup, so sharing the resolution does not widen what is recognized. It
7178
+ * is not a `.map()`-row guard: a portal element inside a row is broken
7179
+ * either way (a row-declared callback is still recognized, and still
7180
+ * breaks) — the known limitation `loop-row-ref-portal`
7181
+ * (`packages/adapter-tests/limitations/loop-row-ref-portal.ts`).
7182
+ *
7183
+ * A match makes `element.ssrPortalOwnerScope` true, which every adapter
7184
+ * (#3119) uses to place the element's SSR markup at its own portal
7185
+ * outlet instead of inline.
7186
+ */
7187
+ function isSsrPortalRefCallback(callback: RefCallback | undefined): boolean {
7188
+ return (
7189
+ !!callback?.named &&
7190
+ callback.innermostScope &&
7191
+ !!callback.param &&
7192
+ containsSsrPortalPlacementCall(callback.body, callback.param)
7193
+ )
7194
+ }
7195
+
7196
+ function firstSimpleParamName(
7197
+ fn: ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration,
7198
+ ): string | undefined {
7199
+ const first = fn.parameters[0]
7200
+ return first && ts.isIdentifier(first.name) ? first.name.text : undefined
7201
+ }
7202
+
7203
+ /**
7204
+ * Walk every descendant of `body` for a `createPortal(<paramName>,
7205
+ * document.body, { ownerScope: … })` call — the exact triple the
7206
+ * shipped components pass. Requires the `ownerScope` option: without it
7207
+ * the client-side `createPortal` never stamps `bf-po`, so SSR placing
7208
+ * the element at the outlet and adding `bf-po` would itself create a new
7209
+ * SSR/hydration mismatch instead of closing the existing one.
7210
+ *
7211
+ * Deliberately does NOT stop at a nested function/arrow boundary the way
7212
+ * `findScopeDeclaration` does: `SelectContent`
7213
+ * (`ui/components/ui/select/index.tsx`) defers its call through
7214
+ * `queueMicrotask(() => createPortal(el, document.body, { ownerScope
7215
+ * }))` — still the SAME `ref` callback's own call, just scheduled async,
7216
+ * not routed through a separately-declared helper — and must match here
7217
+ * the same as a direct call. The `if (…) createPortal(…)` guard that
7218
+ * decides WHETHER to call still runs synchronously inside `handleMount`
7219
+ * itself; only the call is deferred. So once SSR places the element at
7220
+ * the outlet with `bf-po`, hydration's `isSSRPortal(el)` check is true
7221
+ * before the microtask would even be scheduled, keeping the guard a
7222
+ * no-op exactly like the direct-call components. The "DIRECT call only"
7223
+ * guarantee `isSsrPortalRefCallback`'s docstring describes is about NOT
7224
+ * crossing into a separately-declared helper function's own body — which
7225
+ * this walk never does, because it does not resolve call targets: a
7226
+ * `moveToBody(el)` call inside the callback is just a call node, and the
7227
+ * helper's declaration is never visited — not about this same-callback
7228
+ * scheduling deferral.
7229
+ */
7230
+ function containsSsrPortalPlacementCall(body: ts.Node, paramName: string): boolean {
7231
+ let found = false
7232
+ const visit = (node: ts.Node): void => {
7233
+ if (found) return
7234
+ if (ts.isCallExpression(node) && isSsrPortalPlacementCall(node, paramName)) {
7235
+ found = true
7236
+ return
7237
+ }
7238
+ ts.forEachChild(node, visit)
7239
+ }
7240
+ visit(body)
7241
+ return found
7242
+ }
7243
+
7244
+ function isSsrPortalPlacementCall(call: ts.CallExpression, paramName: string): boolean {
7245
+ if (!ts.isIdentifier(call.expression) || call.expression.text !== 'createPortal') return false
7246
+ const [target, container, options] = call.arguments
7247
+ if (!target || !ts.isIdentifier(target) || target.text !== paramName) return false
7248
+ if (!container || !isDocumentBodyAccess(container)) return false
7249
+ if (!options || !ts.isObjectLiteralExpression(options)) return false
7250
+ return options.properties.some(p => {
7251
+ if (ts.isShorthandPropertyAssignment(p)) return p.name.text === 'ownerScope'
7252
+ if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.name)) return p.name.text === 'ownerScope'
7253
+ return false
7254
+ })
7255
+ }
7256
+
7257
+ function isDocumentBodyAccess(expr: ts.Expression): boolean {
7258
+ return (
7259
+ ts.isPropertyAccessExpression(expr) &&
7260
+ ts.isIdentifier(expr.expression) &&
7261
+ expr.expression.text === 'document' &&
7262
+ expr.name.text === 'body'
7263
+ )
6604
7264
  }
6605
7265
 
6606
7266
  function getAttributeValue(attr: ts.JsxAttribute, ctx: TransformContext): AttrValue {
@@ -8039,9 +8699,23 @@ function checkBareSignalOrMemoIdentifier(
8039
8699
  * `const toggleItems__alias = toggleItems`, any number of hops, `const`
8040
8700
  * or `let`, #2724 — see `propAliasHopCandidates`'s docstring for why
8041
8701
  * `let` stays eligible)
8042
- * (b) A PropertyAccessExpression rooted at the props object (e.g. `props.items`),
8043
- * OR one whose object reaches the props object through the same kind of
8044
- * alias-hop chain as (a) (e.g. `const p = props; p.items`, #2724 review)
8702
+ * (b) A PropertyAccessExpression whose ROOT identifier (walking through any
8703
+ * number of chained `.foo` accesses via `rootIdentifierOf`, e.g.
8704
+ * `props.data.items` or `data.items`) is itself recognized by (a)'s
8705
+ * same terminal (`isDirectPropBindingName`) — the whole props object
8706
+ * (e.g. `props.items`) OR a destructured OBJECT-shaped prop (e.g.
8707
+ * `data.items` where `data` is the prop, #3044) — OR reaches either of
8708
+ * those through the same kind of alias-hop chain as (a) (e.g.
8709
+ * `const p = props; p.items`, #2724 review)
8710
+ *
8711
+ * (b) covers a REACTIVE PROP whose value is itself an object: the prop
8712
+ * identifier (`data`) is bound to a fresh object on every parent re-render,
8713
+ * so a `.map()` over one of its own properties (`data.items`) needs the same
8714
+ * `mapArray` reconciliation as a top-level array prop — before #3044 this
8715
+ * shape (destructured OBJECT prop + nested member access, as opposed to
8716
+ * `props.items`'s single member access off the WHOLE props object) fell
8717
+ * through both (a) and (b) and silently stayed on the static SSR-row-bind
8718
+ * path, so a parent's array-from-empty update never reached the child.
8045
8719
  *
8046
8720
  * Unlike the regex-based `isPropsReference`, this avoids false positives from
8047
8721
  * unrelated identifiers that happen to share a prop name (e.g. `state.items`
@@ -8065,16 +8739,14 @@ function checkBareSignalOrMemoIdentifier(
8065
8739
  * `isPropsReference`/`isSignalOrMemoReference`'s chain walk.
8066
8740
  */
8067
8741
  function isArrayExprDirectPropRef(arrayExpr: ts.Expression, ctx: TransformContext): boolean {
8068
- const propsObjName = ctx.analyzer.propsObjectName
8069
-
8070
8742
  if (ts.isIdentifier(arrayExpr)) {
8071
8743
  return resolveAliasOrigin(propAliasHopCandidates(ctx), arrayExpr.text, name => (isDirectPropBindingName(name, ctx) ? true : null)) === true
8072
8744
  }
8073
8745
 
8074
- if (ts.isPropertyAccessExpression(arrayExpr) && propsObjName) {
8075
- const obj = arrayExpr.expression
8076
- if (ts.isIdentifier(obj)) {
8077
- return resolveAliasOrigin(propAliasHopCandidates(ctx), obj.text, name => (name === propsObjName ? true : null)) === true
8746
+ if (ts.isPropertyAccessExpression(arrayExpr)) {
8747
+ const root = rootIdentifierOf(arrayExpr.expression)
8748
+ if (root !== null) {
8749
+ return resolveAliasOrigin(propAliasHopCandidates(ctx), root, name => (isDirectPropBindingName(name, ctx) ? true : null)) === true
8078
8750
  }
8079
8751
  }
8080
8752
 
@@ -8111,14 +8783,36 @@ function isArrayExprDirectPropRef(arrayExpr: ts.Expression, ctx: TransformContex
8111
8783
  * (needed so its regex still matches `props.<key>`) rather than local
8112
8784
  * bindings, so a same-named module const was matching here as if it were
8113
8785
  * the prop itself.
8786
+ *
8787
+ * Recognizes the WHOLE props object identifier itself (`name === propsObjName`)
8788
+ * as directly denoting a prop — needed so a hop landing on the bare `props`
8789
+ * identifier (e.g. `const p = props; p.items`, #2724 review) terminates
8790
+ * here rather than each caller re-checking `propsObjName` separately
8791
+ * (folded in during #3044 pullfrog review to remove exactly that
8792
+ * duplication, which had also skipped this function's shadow guard).
8793
+ *
8794
+ * The member-parsed branch walks `parsed.object` to the chain's ROOT (e.g.
8795
+ * `const items = props.data.items` or `const items = data.items`, #3044
8796
+ * pullfrog review), accepting it whether the root is the whole props object
8797
+ * OR itself a destructured prop binding — the same two-way root check
8798
+ * `isArrayExprDirectPropRef`'s own property-access branch makes (via
8799
+ * `rootIdentifierOf` + this same terminal) for the `.map()` array
8800
+ * expression directly. Without this, aliasing a nested prop-object array to
8801
+ * a local const first (an extremely common pattern) reproduced #3044's
8802
+ * exact silent-freeze bug one hop away from the direct expression this fix
8803
+ * otherwise covers.
8114
8804
  */
8115
8805
  function isDirectPropBindingName(name: string, ctx: TransformContext): boolean {
8116
8806
  if (ctx.scope.isBound(name)) return false
8117
8807
  if (ctx.boundPropNames.has(name)) return true
8118
8808
  const propsObjName = ctx.analyzer.propsObjectName
8119
- if (!propsObjName) return false
8809
+ if (propsObjName && name === propsObjName) return true
8120
8810
  const parsed = constantsByName(ctx).get(name)?.parsed
8121
- return !!parsed && parsed.kind === 'member' && !parsed.computed && parsed.object.kind === 'identifier' && parsed.object.name === propsObjName
8811
+ if (!parsed || parsed.kind !== 'member' || parsed.computed) return false
8812
+ let root: ParsedExpr = parsed.object
8813
+ while (root.kind === 'member' && !root.computed) root = root.object
8814
+ if (root.kind !== 'identifier' || ctx.scope.isBound(root.name)) return false
8815
+ return root.name === propsObjName || ctx.boundPropNames.has(root.name)
8122
8816
  }
8123
8817
 
8124
8818
  /**
@@ -8294,9 +8988,26 @@ function shouldAutoDeferReactiveBrand(expr: ts.Expression, ctx: TransformContext
8294
8988
  // Preserves the original "any native ref anywhere defers to non-deferred"
8295
8989
  // semantics by checking every reactive-brand leaf, not just the first.
8296
8990
  if (leaves.some((leaf) => isSignalOrMemoReference(ctx.getJS(leaf), ctx))) return false
8991
+ // A query action's accessors (`fetchPosts.isPending()`, #3165) are not a
8992
+ // client-only brand package: they stay in the template, where BF117
8993
+ // (`async-action-refusal.ts`) refuses them until they are seeded.
8994
+ if (leaves.some((leaf) => isAsyncActionLeaf(leaf, ctx))) return false
8297
8995
  return true
8298
8996
  }
8299
8997
 
8998
+ /**
8999
+ * Whether a reactive-brand leaf (`fetchPosts.isPending`,
9000
+ * `fetchPosts.isPending()`) is rooted at the action binding of an async
9001
+ * factory (`const [, fetchPosts] = createQuery(…)`, #3165).
9002
+ */
9003
+ function isAsyncActionLeaf(leaf: ts.Node, ctx: TransformContext): boolean {
9004
+ let node: ts.Node = leaf
9005
+ while (ts.isCallExpression(node) || ts.isPropertyAccessExpression(node)) node = node.expression
9006
+ if (!ts.isIdentifier(node)) return false
9007
+ const name = node.text
9008
+ return ctx.analyzer.signals.some((s) => s.factory?.action === name)
9009
+ }
9010
+
8300
9011
  /**
8301
9012
  * Regex-based signal/memo detection.
8302
9013
  * Complements TypeChecker for cases where imported types can't be resolved.
@@ -8579,6 +9290,14 @@ function buildIfStatementChain(
8579
9290
  if (analyzer.jsxReturn) {
8580
9291
  ctx.isRoot = !asConditional
8581
9292
  alternate = transformNode(analyzer.jsxReturn, ctx)
9293
+ // #3063: only the `if-statement` chain shape is at risk — in
9294
+ // `asConditional` mode (#2463) branches sit inside the caller's
9295
+ // synthetic `display:contents` wrapper element and never claim their
9296
+ // own root scope, so the per-component `comment`/`fragmentRoot` flag
9297
+ // this refusal exists for doesn't apply.
9298
+ if (!asConditional) {
9299
+ checkFragmentWrappedConditionalReturnBranch(alternate, analyzer.jsxReturn, ctx)
9300
+ }
8582
9301
  }
8583
9302
 
8584
9303
  // Build the if-else chain from the last conditional to the first
@@ -8711,6 +9430,9 @@ function buildIfStatementChain(
8711
9430
  let consequent: IRNode | null
8712
9431
  try {
8713
9432
  consequent = transformNode(condReturn.jsxReturn, ctx)
9433
+ if (!asConditional) {
9434
+ checkFragmentWrappedConditionalReturnBranch(consequent, condReturn.jsxReturn, ctx)
9435
+ }
8714
9436
  } finally {
8715
9437
  if (branchNames.length > 0) {
8716
9438
  ctx.getJS = prevCtxGetJS