@barefootjs/jsx 0.26.2 → 0.26.4

package/src/loop-destructure.ts

@@ -1,4 +1,5 @@
 import type { IRLoop, IRNode, AttrValue, IRTemplatePart } from './types.ts'
+import { preambleAnalysisText, preambleAnalysisTemplateText } from './types.ts'
 
 /**
  * True when a loop's `.map()` destructure param is one of the shapes this
@@ -154,12 +155,15 @@ function restNamesMisused(loop: IRLoop, names: string[]): boolean {
     check(l.array)
     check(l.templateArray)
     check(l.key)
-    check(l.mapPreamble)
-    check(l.templateMapPreamble)
+    if (l.preamble) {
+      check(preambleAnalysisText(l.preamble))
+      check(preambleAnalysisTemplateText(l.preamble))
+    }
     if (l.flatMapCallback) {
-      check(l.flatMapCallback.body)
-      check(l.flatMapCallback.templateBody)
-      l.flatMapCallback.fragments.forEach(f => visit(f.ir))
+      check(preambleAnalysisText(l.flatMapCallback))
+      for (const seg of l.flatMapCallback.segments) {
+        if (seg.kind === 'jsx') visit(seg.ir)
+      }
     }
     l.children.forEach(visit)
   }

package/src/rich-type-refusal.ts

@@ -299,8 +299,12 @@ function walkNode(
       for (const nested of node.nestedComponents ?? []) {
         for (const child of nested.children) walkNode(child, meta, loopBindings, matchers, errors, seen)
       }
-      for (const frag of node.flatMapCallback?.fragments ?? []) {
-        walkNode(frag.ir, meta, loopBindings, matchers, errors, seen)
+      for (const seg of node.flatMapCallback?.segments ?? []) {
+        if (seg.kind === 'jsx') walkNode(seg.ir, meta, loopBindings, matchers, errors, seen)
+      }
+      // Preamble leaves (array-builder bodies) are nested IR the same way.
+      for (const seg of node.preamble?.segments ?? []) {
+        if (seg.kind === 'jsx') walkNode(seg.ir, meta, loopBindings, matchers, errors, seen)
       }
       break
     }

package/src/strip-types.ts

@@ -71,6 +71,53 @@ export function reconstructWithoutTypes(
   return result
 }
 
+/**
+ * Split a node's text into JS/marker segments: type ranges are stripped from
+ * the JS text, and each `markers` span becomes its own segment boundary
+ * (emitting `{ marker: i }` for the i-th marker, in the order given). Used by
+ * the Stage-3 preamble collector to carry mixed content (JS text + JSX leaves)
+ * as structured segments instead of a sentinel-bearing string — the marker
+ * index maps to the compiled leaf IR. Markers are absolute-position,
+ * non-overlapping sub-spans of `node`; a type range inside a marker span is
+ * subsumed.
+ */
+export function reconstructAsSegments(
+  node: ts.Node,
+  sourceFile: ts.SourceFile,
+  ranges: ExcludeRange[],
+  markers: Array<{ start: number; end: number }>
+): Array<{ js: string } | { marker: number }> {
+  const nodeStart = node.getStart(sourceFile)
+  const nodeEnd = node.getEnd()
+  const fullText = sourceFile.text
+
+  type Edit = { start: number; end: number; marker: number | null }
+  const edits: Edit[] = []
+  for (const r of ranges) {
+    if (r.end <= nodeStart || r.start >= nodeEnd) continue
+    edits.push({ start: r.start, end: r.end, marker: null })
+  }
+  markers.forEach((m, i) => edits.push({ start: m.start, end: m.end, marker: i }))
+  edits.sort((a, b) => a.start - b.start || b.end - a.end)
+
+  const segments: Array<{ js: string } | { marker: number }> = []
+  let jsBuf = ''
+  let pos = nodeStart
+  for (const edit of edits) {
+    if (edit.start < pos) continue // subsumed by an already-emitted span
+    jsBuf += fullText.slice(pos, edit.start)
+    if (edit.marker !== null) {
+      if (jsBuf) segments.push({ js: jsBuf })
+      jsBuf = ''
+      segments.push({ marker: edit.marker })
+    }
+    pos = edit.end
+  }
+  if (pos < nodeEnd) jsBuf += fullText.slice(pos, nodeEnd)
+  if (jsBuf) segments.push({ js: jsBuf })
+  return segments
+}
+
 function mergeRanges(ranges: ExcludeRange[]): ExcludeRange[] {
   if (ranges.length === 0) return []
   const merged: ExcludeRange[] = [ranges[0]]

package/src/types.ts

@@ -371,6 +371,24 @@ export interface IRExpression {
   loc: SourceLocation
   /** When true, expression should be evaluated on client side only */
   clientOnly?: boolean
+  /**
+   * Stage 3 / D4 (spec/callback-fidelity.md) — this expression child references
+   * an array built by an arbitrary `.map()` preamble (`return <tr>{out}</tr>`
+   * where `out` is `push`-populated with element strings). Phase-2 string-
+   * template emission must join it (`Array.isArray(out) ? out.join('') : …`)
+   * rather than `String([])`-comma-collapse it. JSX SSR adapters ignore the
+   * flag (their JSX runtime renders an array child natively).
+   */
+  joinArrayChild?: boolean
+  /**
+   * True when this expression was classified as a loop's preamble-patched
+   * region (#2389 — see `IRLoop.preambleRegions`): its free identifiers
+   * intersect the enclosing loop's `preamble.declaredNames`. Excludes the
+   * node from `collectLoopChildReactiveTexts` (which patches via
+   * `.textContent`, wrong for markup) regardless of `reactive` / `slotId` —
+   * the region-patch effect (`patchSlotRange`) is its only wiring.
+   */
+  preambleRegion?: boolean
   /** When true, expression calls signal getters or memos (has reactive `foo()` pattern). */
   callsReactiveGetters?: boolean
   /** When true, expression contains function call(s) — any `identifier()` pattern (computed from AST). */
@@ -678,21 +696,43 @@ export interface IRLoop {
    */
   bodyIsItemConditional?: boolean
 
-  /**
-   * Raw JS of pre-return statements in block body .map() callback.
-   * Example: `items.map(item => { const label = item.name.toUpperCase(); return <li>{label}</li> })`
-   * stores "const label = item.name.toUpperCase();" as mapPreamble.
-   */
-  mapPreamble?: string
-  /** Pre-transformed mapPreamble with destructured prop refs rewritten to _p.xxx. */
-  templateMapPreamble?: string
-
   /** Type annotation for loop param (e.g., 'Desk'), preserved for .tsx output */
   paramType?: string
   /** Type annotation for loop index param (e.g., 'number'), preserved for .tsx output */
   indexType?: string
-  /** mapPreamble with TypeScript type annotations preserved, for .tsx output */
-  typedMapPreamble?: string
+  /**
+   * Structured pre-return statements of a block-body `.map()` callback
+   * (Stage 3 root cure, spec/callback-fidelity.md). Replaces the former
+   * `mapPreamble` / `templateMapPreamble` / `typedMapPreamble` string carriers
+   * and `preambleFragments`: mixed content (JS text + JSX leaves) is carried as
+   * a segment list, never as a sentinel-bearing string, so an emitter that
+   * lacks preamble support cannot accidentally interpolate it — rendering goes
+   * through `renderPreamble()` (html-template.ts) or not at all.
+   */
+  preamble?: MapCallbackPreamble
+
+  /**
+   * Expression children of the loop body whose free identifiers intersect
+   * `preamble.declaredNames` (#2389, patch-on-update follow-up to the Stage 3
+   * root cure) — e.g. `{cells}` in `arr.map(t => { const cells = []; ...;
+   * return <tr>{cells}<td>{t.name}</td></tr> })`. `mapArray` reuses the same
+   * DOM node on a same-key item update via per-item `setItem`, re-running
+   * only the wired text/attr slots — a preamble-derived child has NEITHER
+   * (it's a bare interpolation, `joinArrayChild` array-join or otherwise),
+   * so without this it freezes at its mount-time value forever. Each entry's
+   * `slotId` is emitted as the usual `<!--bf:sN-->...<!--/-->` marker pair
+   * (same door as a reactive text slot — `irToHtmlTemplate` / Hono's
+   * `renderExpression` key off `slotId` alone), but the CLIENT wiring is a
+   * distinct `patchSlotRange`-based region-patch effect (`preambleRegions`
+   * in the client-JS loop plan), NOT a `reactiveTexts` entry — patching via
+   * `.textContent` would escape markup that a `joinArrayChild` region must
+   * render raw. `collectLoopChildReactiveTexts` excludes any node collected
+   * here (`IRExpression.preambleRegion`) so a qualifying expression is never
+   * double-wired. Populated only when `preamble` is set and the loop is NOT
+   * `isStaticArray` — a static array's SSR-rendered items are never
+   * recreated via signals, so there is nothing to patch.
+   */
+  preambleRegions?: PreambleRegionSource[]
 
   /**
    * When `.map(callback)` destructures its item parameter (array or object
@@ -720,9 +760,9 @@ export interface IRLoop {
   /**
    * For flatMap callbacks whose body can't be decomposed into simple
    * `children` (block bodies with conditional returns, variable-assigned
-   * JSX, etc.). Carries the full callback body with JSX fragments
-   * replaced by `__BF_JSX_N__` placeholders, plus the IR for each
-   * fragment so each adapter can render them appropriately.
+   * JSX, etc.). Carries the body as structured segments (JS text +
+   * compiled JSX-leaf IR) rendered through `renderPreamble()`, plus the
+   * raw TSX for JSX-runtime SSR adapters.
    *
    * When present, `children` is empty — emitters use this field instead.
    */
@@ -730,31 +770,115 @@ export interface IRLoop {
 }
 
 /**
- * A compiled flatMap callback body. JSX elements in the original
- * callback have been transformed to IR nodes and replaced with
- * `__BF_JSX_0__`, `__BF_JSX_1__`, … placeholders in `body`.
- *
- * Each emitter (html-template, hono-adapter) renders the IR fragments
- * in its own format and substitutes the placeholders accordingly.
+ * A compiled flatMap callback body, carried as structured segments (the same
+ * shape as {@link MapCallbackPreamble}, rendered through the same
+ * `renderPreamble()` door) — never as a sentinel-bearing string. JSX-runtime
+ * SSR adapters emit `rawBody` (real TSX, branded) instead.
  */
 export interface FlatMapCallback {
   /** Callback parameters text, e.g. `"(frame, i)"` */
   params: string
-  /** Callback body text with JSX replaced by `__BF_JSX_N__` placeholders */
-  body: string
-  /** Same as `body` but with prop refs rewritten for template context */
-  templateBody?: string
-  /** Original callback body text with JSX preserved (for Hono .tsx output) */
-  rawBody: string
-  /** IR nodes for each JSX placeholder, ordered by placeholder index */
-  fragments: FlatMapJsxFragment[]
-}
-
-export interface FlatMapJsxFragment {
-  /** Placeholder string, e.g. `"__BF_JSX_0__"` */
-  placeholder: string
-  /** Compiled IR node for this JSX fragment */
-  ir: IRNode
+  /** Callback body as js-text / compiled-JSX-leaf segments. */
+  segments: PreambleSegment[]
+  /** Original callback body text (JSX intact) for JSX-runtime SSR adapters. */
+  rawBody: TsxSourceText
+}
+
+/**
+ * Raw TSX source text (types + JSX intact), branded so it is only assignable
+ * where a JSX-runtime SSR adapter emits real TSX (Hono / TestAdapter). Plain
+ * strings destined for the client bundle cannot satisfy this type, and this
+ * type must never be spliced into plain-JS emission — the write-side twin of
+ * the "never parse JS with regex" rule: raw source crossing into an emitted
+ * artifact is tagged with its only legal destination.
+ */
+export type TsxSourceText = string & { readonly __tsxSourceBrand: unique symbol }
+
+/** Constructor for {@link TsxSourceText} — the single place the brand is applied. */
+export function tsxSourceText(raw: string): TsxSourceText {
+  return raw as TsxSourceText
+}
+
+/**
+ * One segment of a `.map()` callback preamble. Mixed content is structured,
+ * never a sentinel-bearing string: `js` segments carry JSX-free JS source text
+ * (types stripped; `templateText` set when the destructured-prop rewrite
+ * differs), `jsx` segments carry the compiled IR of one JSX leaf. Segments
+ * concatenate in source order with no separators (they are sub-statement
+ * spans).
+ */
+export type PreambleSegment =
+  | {
+      kind: 'js'
+      /** Type-stripped JS text for the client bundle. */
+      text: string
+      /** `text` with destructured prop refs rewritten to `_p.xxx`, when different. */
+      templateText?: string
+    }
+  | { kind: 'jsx'; ir: IRNode }
+
+/**
+ * The structured pre-return statements of a block-body `.map()` callback
+ * (Stage 3 root cure, spec/callback-fidelity.md). Client emission renders
+ * `segments` via `renderPreamble()` (html-template.ts) — the only door; a
+ * consumer that can't call it has no way to splice the preamble, so a missing
+ * wire-up is a type error or an explicit refusal, never a silent leak.
+ * JSX-runtime SSR adapters emit `ssrText` (real TSX) instead.
+ */
+export interface MapCallbackPreamble {
+  segments: PreambleSegment[]
+  /** Raw preamble source (types + JSX intact) for JSX-runtime SSR adapters. */
+  ssrText: TsxSourceText
+  /** const/let/function names the preamble declares (D5 key-derivability guard). */
+  declaredNames: string[]
+  /**
+   * The subset of {@link declaredNames} that accumulate JSX leaves — the
+   * `push`/`unshift` targets of a `jsx` segment and the declaration targets of
+   * a leaf-bearing initializer (`const out = xs.map(x => <td/>)`). Only these
+   * get the `{out}` array-join child emission; a value-only local (`{label}`)
+   * keeps the plain interpolation it always had.
+   */
+  builderNames: string[]
+}
+
+/**
+ * One loop-body expression child classified as a preamble-patched region
+ * (#2389 — see `IRLoop.preambleRegions`). `expr` is the raw (unwrapped)
+ * expression text, exactly as carried on the source `IRExpression` node;
+ * emitters wrap it with the loop-param accessor at codegen time, matching
+ * every other loop-body expression. `joinArrayChild` mirrors the
+ * `IRExpression` field of the same name — the client-JS plan builder uses it
+ * to decide between the array-join value expression and a plain (escaped)
+ * text value, keeping the region's re-render byte-identical to the row
+ * template's own `irToHtmlTemplate` rendering of the same node.
+ */
+export interface PreambleRegionSource {
+  slotId: string
+  expr: string
+  joinArrayChild?: boolean
+}
+
+/**
+ * The preamble's JS text (js segments only, concatenated), for read-side
+ * analysis — free-identifier scans, reachability edges, rest-misuse checks.
+ * JSX-leaf interiors are compiled IR and are analyzed through their own IR
+ * walks, exactly as the former placeholder carrier excluded them. NEVER use
+ * this for emission — emission goes through `renderPreamble()`.
+ */
+export function preambleAnalysisText(p: Pick<MapCallbackPreamble, 'segments'>): string {
+  let out = ''
+  for (const seg of p.segments) if (seg.kind === 'js') out += seg.text
+  return out
+}
+
+/**
+ * Template-context variant of {@link preambleAnalysisText} (destructured prop
+ * refs rewritten). Read-side analysis only.
+ */
+export function preambleAnalysisTemplateText(p: Pick<MapCallbackPreamble, 'segments'>): string {
+  let out = ''
+  for (const seg of p.segments) if (seg.kind === 'js') out += seg.templateText ?? seg.text
+  return out
 }
 
 /**