@barefootjs/jsx 0.5.2 → 0.6.0

package/src/ir-to-client-js/control-flow/stringify/event-delegation.ts

@@ -32,7 +32,7 @@
  * sentinel before destructuring (#951 TDZ-safe).
  */
 
-import { toDomEventName, varSlotId, substituteLoopBindings, DATA_KEY, keyAttrName } from '../../utils'
+import { toDomEventName, varSlotId, substituteLoopBindings, buildLoopChildIndexSubtraction, DATA_KEY, keyAttrName } from '../../utils'
 import type {
   EventDelegationPlan,
   KeyedItemLookup,
@@ -187,11 +187,11 @@ function emitStaticIndexLookup(
   lookup: StaticIndexItemLookup,
   containerVar: string,
 ): void {
-  const { arrayExpr, param, mapPreamble, siblingOffset } = lookup
+  const { arrayExpr, param, mapPreamble, offset } = lookup
   ls.push(`      let __el = ${varSlotId(ev.childSlotId)}El`)
   ls.push(`      while (__el.parentElement && __el.parentElement !== ${containerVar}) __el = __el.parentElement`)
   ls.push(`      if (__el.parentElement === ${containerVar}) {`)
-  const idxOffset = siblingOffset ? ` - ${siblingOffset}` : ''
+  const idxOffset = buildLoopChildIndexSubtraction(offset ?? undefined)
   ls.push(`        const __idx = Array.from(${containerVar}.children).indexOf(__el)${idxOffset}`)
   ls.push(`        const ${param} = ${arrayExpr}[__idx]`)
   if (mapPreamble) ls.push(`        ${mapPreamble}`)

package/src/ir-to-client-js/emit-reactive.ts

@@ -17,6 +17,15 @@ import { createTemplateAwareStringProtector } from './html-template'
  */
 export function emitAttrUpdate(target: string, attrName: string, expression: string, meta: AttrMeta): string[] {
   const htmlName = toHtmlAttrName(attrName)
+  if (attrName === 'dangerouslySetInnerHTML' || htmlName === 'dangerouslySetInnerHTML') {
+    // `{ __html }` is not an attribute — it replaces the element's content.
+    // Assign `innerHTML` (raw, intentional escape hatch) to mirror the SSR
+    // adapters' native `dangerouslySetInnerHTML` handling instead of
+    // stringifying the object into a bogus attribute.
+    return [
+      `{ const __v = ${expression}; ${target}.innerHTML = __v != null && __v.__html != null ? String(__v.__html) : '' }`,
+    ]
+  }
   if (htmlName === 'style') {
     return [
       `{ const __v = styleToCss(${expression}); if (__v != null) ${target}.setAttribute('style', __v); else ${target}.removeAttribute('style') }`,

package/src/ir-to-client-js/emit-registration.ts

@@ -168,7 +168,7 @@ export function emitRegistrationAndHydration(
     // transformation runs at this layer (#1277).
     const csrInlinableConstants = csrInlinableConstantsFromCtx(ctx)
     const templateHtml = generateCsrTemplate(
-      _ir.root, csrInlinableConstants, ctx, undefined, restSpreadNames, ctx.propsObjectName, unsafeLocalNames
+      _ir.root, csrInlinableConstants, ctx, undefined, restSpreadNames, ctx.propsObjectName, unsafeLocalNames, ctx.deferredChildSlots
     )
     if (templateHtml) {
       defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``)

package/src/ir-to-client-js/generate-init.ts

@@ -14,7 +14,8 @@ import { PROPS_PARAM } from './utils'
 import { buildReferencesGraph } from './build-references'
 import { computePropUsage } from './compute-prop-usage'
 import { IMPORT_PLACEHOLDER, MODULE_CONSTANTS_PLACEHOLDER } from './imports'
-import { emitRegistrationAndHydration } from './emit-registration'
+import { emitRegistrationAndHydration, csrInlinableConstantsFromCtx } from './emit-registration'
+import { computeDeferredChildSlots } from './html-template'
 import { emitChildComponentImports } from './child-components'
 import { classifyLocalDeclarations } from './init-declarations'
 import { emitModuleLevelDeclarations, resolveFinalImports } from './emit-module-level'
@@ -55,6 +56,20 @@ export function generateInitFunction(
   // duplicate warnings (#1247).
   const inlinability = buildInlinableConstants(ctx, graph, ir.root)
 
+  // Decide which direct child components must defer their render to init
+  // because a forwarded prop resolves to an init-scope-only / non-inlinable
+  // local (dropped-prop fix). The child-init phase reads this set to emit
+  // `upsertChild` instead of `initChild`; `emitRegistrationAndHydration`
+  // reads it to emit a `data-bf-ph` placeholder instead of
+  // `renderChild(...)`. Computed here, once `unsafeLocalNames` is known.
+  ctx.deferredChildSlots = computeDeferredChildSlots(
+    ir.root,
+    ctx,
+    csrInlinableConstantsFromCtx(ctx),
+    inlinability.unsafeLocalNames,
+    ctx.propsObjectName,
+  )
+
   // --- Emission: declarative phase pipeline. Each entry in `PHASES`
   //     declares its inputs (dependsOn) and emission action (run); the
   //     stable topological execution preserves the legacy by-position

package/src/ir-to-client-js/html-template.ts

@@ -2,7 +2,7 @@
  * IR → HTML template string generation and validation.
  */
 
-import type { AttrValue, IRAttribute, IRNode } from '../types'
+import type { AttrValue, IRAttribute, IRNode, IRProp } from '../types'
 import { isBooleanAttr } from '../html-constants'
 import { toHtmlAttrName, attrValueToString, quotePropName, PROPS_PARAM, DATA_BF_PH, keyAttrName, loopStartMarker, loopEndMarker, loopItemMarker, freeIdsFromRefs, setIntersects, wrapExprWithLoopParams } from './utils'
 import type { LoopParamSpec } from './utils'
@@ -192,11 +192,16 @@ const UNSAFE_TEMPLATE_EXPR = 'undefined'
  * @param attr - Attribute metadata (only presenceOrUndefined flag is used)
  */
 function templateAttrExpr(attrName: string, valExpr: string, presenceOrUndefined?: boolean): string {
+  // `dangerouslySetInnerHTML={{ __html }}` is not an attribute — its value
+  // becomes the element's raw innerHTML (emitted as element content). Never
+  // serialise the `{ __html }` object into a `dangerouslySetInnerHTML="…"`
+  // attribute.
+  if (attrName === 'dangerouslySetInnerHTML') return ''
   if (isBooleanAttr(attrName) || presenceOrUndefined) {
     return `\${${valExpr} ? '${attrName}' : ''}`
   }
   if (attrName === 'style') {
-    return `\${((v) => v != null ? 'style="' + v + '"' : '')(styleToCss(${valExpr}))}`
+    return `\${((v) => v != null ? 'style="' + ${escapeAttrValueExpr('v')} + '"' : '')(styleToCss(${valExpr}))}`
   }
   // `data-key` / `data-key-N` is a reconciliation contract — every loop item
   // must carry one. Emit unconditionally; if the user passes `key={undefined}`
@@ -205,7 +210,60 @@ function templateAttrExpr(attrName: string, valExpr: string, presenceOrUndefined
   if (attrName === 'data-key' || attrName.startsWith('data-key-')) {
     return `${attrName}="\${${valExpr}}"`
   }
-  return `\${(${valExpr}) != null ? '${attrName}="' + (${valExpr}) + '"' : ''}`
+  return `\${(${valExpr}) != null ? '${attrName}="' + ${escapeAttrValueExpr(valExpr)} + '"' : ''}`
+}
+
+/**
+ * Build a runtime expression that HTML-escapes an interpolated attribute
+ * value, matching the SSR adapters' attribute escaping (Hono escapes
+ * `& " ' < >`) via the `escapeAttr` runtime helper. The client template
+ * assembles an HTML string inserted via `innerHTML`, so an unescaped `"`
+ * / `<` / `>` in a value — e.g. UnoCSS arbitrary variants like
+ * `[class*="size-"]` or `has-[>svg]` — corrupts attribute parsing (and
+ * diverges from the SSR-rendered bytes). Escaping at interpolation time
+ * is the only correct layer: a post-assembly pass can't tell a delimiter
+ * `"` from a value `"`.
+ */
+function escapeAttrValueExpr(valExpr: string): string {
+  return `escapeAttr(${valExpr})`
+}
+
+/**
+ * Build a runtime expression that HTML-escapes an interpolated **text
+ * content** slot, via the `escapeText` runtime helper. Only the
+ * `<!--bf:sN-->${expr}<!--/-->` text-marker form is text content: the
+ * runtime treats whatever sits between the markers as the slot's text, so
+ * a string value containing `<` / `&` (e.g. `{user.name}`) must be escaped
+ * to parse correctly under `innerHTML` and to match the SSR-rendered
+ * bytes. Bare `${...}` interpolations — `{children}` passthrough and
+ * `renderChild(...)` output — are pre-rendered HTML and must NOT be
+ * escaped, so this is applied only at the four text-marker emit sites.
+ * Hono escapes text content with the same set as attribute values
+ * (`& " ' < >`), so `escapeText` delegates to the same operation.
+ */
+function escapeTextSlotExpr(innerExpr: string): string {
+  return `escapeText(${innerExpr})`
+}
+
+/**
+ * `dangerouslySetInnerHTML={{ __html: E }}` makes the element's content its
+ * raw innerHTML — the intentional, React-style escape hatch. Returns the
+ * raw-content template expression to use *instead of* the element's normal
+ * children (emitted UNescaped by design, mirroring the SSR adapters'
+ * native handling), or `null` when the element carries no such attribute.
+ * The attribute itself is suppressed in `templateAttrExpr`, and the
+ * matching reactive update is emitted by `emitAttrUpdate` (assigns
+ * `innerHTML`). `toExpr` is the walker's value transform (`wrapExpr` /
+ * `transformExpr`) so the `{ __html }` object is lowered the same way an
+ * attribute value would be.
+ */
+function dangerouslyHtmlChildren(
+  attrs: ReadonlyArray<IRAttribute>,
+  toExpr: (v: { expr: string; templateExpr?: string }) => string,
+): string | null {
+  const attr = attrs.find(a => a.name === 'dangerouslySetInnerHTML')
+  if (!attr || attr.value.kind !== 'expression') return null
+  return `\${((${toExpr(attr.value)}) ?? {}).__html ?? ''}`
 }
 
 /**
@@ -322,6 +380,12 @@ export interface MergeContext {
 function isMergeableAttr(a: IRAttribute, ctx: MergeContext): boolean {
   if (ctx.honorClientOnly && a.clientOnly) return false
   if (a.name === 'key') return false
+  // `dangerouslySetInnerHTML` is not an attribute — its `{ __html }` value
+  // becomes the element's raw innerHTML (emitted as content, set via
+  // `innerHTML` in init). Keep it out of the `spreadAttrs({...})` merge so
+  // it isn't serialised back into a bogus `dangerouslySetInnerHTML="…"`
+  // attribute when the element also carries a spread.
+  if (a.name === 'dangerouslySetInnerHTML') return false
   const v = a.value
   if (v.kind === 'jsx-children') return false
   if (v.kind === 'boolean-shorthand') return false
@@ -476,7 +540,7 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
 
       const attrs = attrParts.join(' ')
       const childrenRecurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, insideLoop, false)
-      const children = node.children.map(childrenRecurse).join('')
+      const children = dangerouslyHtmlChildren(node.attrs, v => wrapExpr(v.expr)) ?? node.children.map(childrenRecurse).join('')
 
       // Non-void elements must use open+close tags (HTML parsers ignore self-closing on div, span, etc.)
       if (children || !VOID_ELEMENTS.has(node.tag)) {
@@ -491,7 +555,15 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${wrapInterpolation(wrapExpr(node.expr))}}<!--/-->`
+        const inner = wrapInterpolation(wrapExpr(node.expr))
+        // In branch-slot context `wrapInterpolation` routes the value
+        // through `__bfSlot`, which returns raw `<!--bf-slot:N-->` markers
+        // for live `Node` values (spliced back by `insert()`). Escaping
+        // would corrupt those markers and drop slotted content (#1694
+        // regression). `__bfSlot` owns coercion of its own value, so the
+        // text-escape applies only to the non-slot (plain text) form.
+        const slotted = branchSlotsVar ? inner : escapeTextSlotExpr(inner)
+        return `<!--bf:${node.slotId}-->\${${slotted}}<!--/-->`
       }
       return `\${${wrapInterpolation(wrapExpr(node.expr))}}`
 
@@ -656,7 +728,7 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
       }
 
       const attrs = attrParts.join(' ')
-      const children = node.children.map(recurse).join('')
+      const children = dangerouslyHtmlChildren(node.attrs, v => wrapExpr(v.expr)) ?? node.children.map(recurse).join('')
 
       if (children || !VOID_ELEMENTS.has(node.tag)) {
         return `<${node.tag}${attrs ? ' ' + attrs : ''}>${children}</${node.tag}>`
@@ -670,7 +742,7 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<stri
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${wrapExpr(node.expr)}}<!--/-->`
+        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(wrapExpr(node.expr))}}<!--/-->`
       }
       return `\${${wrapExpr(node.expr)}}`
 
@@ -890,6 +962,20 @@ export interface TemplateOptions {
   loopDepth?: number
   /** Emit `bf-s` placeholder on scoped elements inside a jsx-children prop (#1320). */
   inHoistedChildren?: boolean
+  /**
+   * Slot ids of direct child components whose render must be DEFERRED to
+   * init because at least one forwarded (non-`/* @client *\/`) prop value
+   * references an init-scope-only / non-inlinable local — the module-scope
+   * template lambda can't supply it, so eagerly calling `renderChild` with
+   * the prop dropped would make the child template read `undefined`.
+   *
+   * For these slots the CSR `component` case emits a `data-bf-ph`
+   * placeholder instead of `renderChild(...)`; the parent init replaces it
+   * via `upsertChild` (→ `createComponent` with the complete getter props).
+   * Computed up front by `computeDeferredChildSlots` so the init phase and
+   * the template phase agree on which children defer (dropped-prop fix).
+   */
+  deferredChildSlots?: ReadonlySet<string>
 }
 
 /**
@@ -1041,7 +1127,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
       }
 
       const attrs = attrParts.join(' ')
-      const children = node.children.map(childrenRecurse).join('')
+      const children = dangerouslyHtmlChildren(node.attrs, v => transformExpr(v.expr, v.templateExpr)) ?? node.children.map(childrenRecurse).join('')
 
       if (children || !VOID_ELEMENTS.has(node.tag)) {
         return `<${node.tag}${attrs ? ' ' + attrs : ''}>${children}</${node.tag}>`
@@ -1055,7 +1141,7 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
     case 'expression':
       if (node.expr === 'null' || node.expr === 'undefined') return ''
       if (node.slotId) {
-        return `<!--bf:${node.slotId}-->\${${transformExpr(node.expr, node.templateExpr)}}<!--/-->`
+        return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(transformExpr(node.expr, node.templateExpr))}}<!--/-->`
       }
       return `\${${transformExpr(node.expr, node.templateExpr)}}`
 
@@ -1281,6 +1367,7 @@ export function generateCsrTemplate(
   restSpreadNames?: Set<string>,
   propsObjectName?: string | null,
   unsafeLocalNames?: Set<string>,
+  deferredChildSlots?: ReadonlySet<string>,
 ): string {
   // Build the substitution env once per component. Signals + memos come
   // from `buildSignalMemoEnv`; inlinable constants layer in here so
@@ -1295,7 +1382,134 @@ export function generateCsrTemplate(
       }
     }
   }
-  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames, loopDepth: -1 })
+  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames, deferredChildSlots, loopDepth: -1 })
+}
+
+/**
+ * Build the per-component CSR substitution env (signals + memos + inlinable
+ * constants), matching what `generateCsrTemplate` builds. Shared so the
+ * deferred-child analysis and the template emit agree on substitution
+ * results.
+ */
+function buildCsrEnvForCtx(
+  ctx: ClientJsContext,
+  inlinableConstants: Map<string, string> | undefined,
+  propsObjectName?: string | null,
+): CsrEnv {
+  const base = buildSignalMemoEnv(ctx.signals, ctx.memos, propsObjectName ?? null)
+  const csrEnv: CsrEnv = { substitutions: new Map(base.substitutions), propsObjectName: base.propsObjectName }
+  if (inlinableConstants) {
+    for (const [name, value] of inlinableConstants) {
+      if (!csrEnv.substitutions.has(name)) {
+        csrEnv.substitutions.set(name, { kind: 'identifier', replacement: value, freeIdentifiers: new Set() })
+      }
+    }
+  }
+  return csrEnv
+}
+
+/**
+ * Decide whether a single forwarded component prop value would be DROPPED
+ * by the CSR `component` emit — i.e. after `csrSubstitute` its expression
+ * still references a name in `unsafeLocalNames`. Mirrors the
+ * `transformExpr` UNSAFE gate so the deferral analysis matches the actual
+ * template output exactly.
+ */
+function propResolvesUnsafe(
+  prop: IRProp,
+  env: CsrEnv,
+  unsafeLocalNames: ReadonlySet<string>,
+): boolean {
+  if (unsafeLocalNames.size === 0) return false
+  let source: string | undefined
+  switch (prop.value.kind) {
+    case 'expression':
+    case 'spread':
+      source = prop.value.expr
+      break
+    case 'template':
+      source = attrValueToString(prop.value, { useTemplate: true }) ?? undefined
+      break
+    default:
+      // literal / boolean / jsx-children carry no init-scope identifiers.
+      return false
+  }
+  if (!source) return false
+  const { freeIdentifiers } = csrSubstitute(source, env)
+  return setIntersects(freeIdentifiers, unsafeLocalNames)
+}
+
+/**
+ * Walk the component IR and collect the slot ids of DIRECT child
+ * components whose render must be deferred to init because at least one
+ * forwarded (non-`/* @client *\/`, non-event) prop resolves to an
+ * init-scope-only / non-inlinable local. The module-scope CSR template
+ * lambda can't supply such a value, so `renderChild(...)` would drop the
+ * prop and the child template would read `undefined` and throw.
+ *
+ * Only top-level (non-loop, non-clientOnly-conditional) children are
+ * considered — those are the ones rendered via the `renderChild(...)` form
+ * in the registration template and wired through `ctx.childInits`. Loop /
+ * conditional-branch children already go through their own
+ * placeholder + `createComponent` materialize paths.
+ */
+export function computeDeferredChildSlots(
+  node: IRNode,
+  ctx: ClientJsContext,
+  inlinableConstants: Map<string, string> | undefined,
+  unsafeLocalNames: ReadonlySet<string> | undefined,
+  propsObjectName?: string | null,
+): Set<string> {
+  const deferred = new Set<string>()
+  if (!unsafeLocalNames || unsafeLocalNames.size === 0) return deferred
+  const env = buildCsrEnvForCtx(ctx, inlinableConstants, propsObjectName)
+
+  const visit = (n: IRNode): void => {
+    switch (n.type) {
+      case 'component': {
+        if (n.name === 'Portal') {
+          n.children.forEach(visit)
+          return
+        }
+        if (n.slotId) {
+          const dropped = n.props.some(p => {
+            // Spread props (`...`) are forwarded via the rest-spread path
+            // (`restSpreadNames`), not the per-prop inline form, so they are
+            // out of scope for this drop check; `key` and event handlers
+            // (`onX`) likewise never carry init-scope render values. This
+            // filter set MUST mirror the `propsEntries` filter in the CSR
+            // `component` emit below so the deferral decision matches output.
+            if (p.name === '...' || p.name.startsWith('...') || p.name === 'key') return false
+            if (p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()) return false
+            if (p.clientOnly) return false
+            return propResolvesUnsafe(p, env, unsafeLocalNames)
+          })
+          if (dropped) deferred.add(n.slotId)
+        }
+        // Do not descend into a component's JSX-children props here: those
+        // children render in the parent scope only when hoisted, and the
+        // deferral concern is the direct child component's own props.
+        return
+      }
+      case 'element':
+        n.children.forEach(visit)
+        return
+      case 'fragment':
+        n.children.forEach(visit)
+        return
+      case 'conditional':
+        // Conditional branch children are handled by the branch
+        // materialize path, not the top-level renderChild form.
+        return
+      case 'loop':
+        // Loop children go through the loop materialize path.
+        return
+      default:
+        return
+    }
+  }
+  visit(node)
+  return deferred
 }
 
 function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): string {
@@ -1417,7 +1631,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       }
 
       const attrs = attrParts.join(' ')
-      const children = node.children.map(childrenRecurse).join('')
+      const children = dangerouslyHtmlChildren(node.attrs, v => transformExpr(v.expr, v.templateExpr)) ?? node.children.map(childrenRecurse).join('')
 
       if (children || !VOID_ELEMENTS.has(node.tag)) {
         return `<${node.tag}${attrs ? ' ' + attrs : ''}>${children}</${node.tag}>`
@@ -1440,7 +1654,7 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         // an empty placeholder instead.
         const expr = transformed === UNSAFE_TEMPLATE_EXPR ? "''" : transformed
         if (node.slotId) {
-          return `<!--bf:${node.slotId}-->\${${expr}}<!--/-->`
+          return `<!--bf:${node.slotId}-->\${${escapeTextSlotExpr(expr)}}<!--/-->`
         }
         return `\${${expr}}`
       }
@@ -1470,6 +1684,18 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         return node.children.map(recurse).join('')
       }
 
+      // Deferred child (dropped-prop fix): at least one forwarded prop
+      // resolves to an init-scope-only local the module-scope template
+      // lambda can't supply. Emitting `renderChild('Child', { /* prop
+      // dropped */ })` would make the child template read `undefined` and
+      // throw. Emit a `data-bf-ph` placeholder instead — the parent init
+      // resolves it via `upsertChild` → `createComponent` with the full
+      // getter props (mirrors the `irToPlaceholderTemplate` deferral and
+      // the clientOnly-conditional empty-marker precedent).
+      if (node.slotId && opts.deferredChildSlots?.has(node.slotId)) {
+        return `<div ${DATA_BF_PH}="${node.slotId}"></div>`
+      }
+
       const propsEntries = node.props
         .filter(p => p.name !== '...' && !p.name.startsWith('...') && p.name !== 'key')
         .filter(p => !(p.name.startsWith('on') && p.name.length > 2 && p.name[2] === p.name[2].toUpperCase()))

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

@@ -11,7 +11,7 @@ export const RUNTIME_IMPORT_CANDIDATES = [
   'createComponent', 'renderChild', 'registerComponent', 'registerTemplate', 'initChild', 'upsertChild', 'updateClientMarker',
   'createPortal',
   'provideContext', 'createContext', 'useContext',
-  'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss',
+  'forwardProps', 'applyRestAttrs', 'splitProps', 'spreadAttrs', 'styleToCss', 'escapeAttr', 'escapeText',
   'qsa', 'qsaItem', 'qsaChildScope', 'qsaChildScopes', 'upsertChildItem', '__slot', '__bfSlot', '__bfText',
 ] as const
 

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

@@ -176,6 +176,7 @@ function createContext(
     loopElements: [],
     refElements: [],
     childInits: [],
+    deferredChildSlots: new Set(),
     reactiveProps: [],
     reactiveChildProps: [],
     reactiveAttrs: [],

package/src/ir-to-client-js/phases/provider-and-child-inits.ts

@@ -28,8 +28,19 @@ export function emitProviderAndChildInits(lines: string[], ctx: ClientJsContext)
     lines.push('')
     lines.push(`  // Initialize child components with props`)
     for (const child of ctx.childInits) {
+      const registryName = nameForRegistryRef(child.name)
+      // Deferred child (dropped-prop fix): the registration template emits
+      // a `data-bf-ph` placeholder for this slot rather than rendering it.
+      // `upsertChild` resolves both shapes — an existing SSR scope (→
+      // initChild) or the placeholder (→ createComponent with the full
+      // getter props). Use it so the child is created/initialised with
+      // complete props instead of running against a missing prop.
+      if (child.slotId && ctx.deferredChildSlots.has(child.slotId)) {
+        lines.push(`  upsertChild(__scope, '${registryName}', '${child.slotId}', ${child.propsExpr})`)
+        continue
+      }
       const scopeRef = child.slotId ? `_${varSlotId(child.slotId)}` : '__scope'
-      lines.push(`  initChild('${nameForRegistryRef(child.name)}', ${scopeRef}, ${child.propsExpr})`)
+      lines.push(`  initChild('${registryName}', ${scopeRef}, ${child.propsExpr})`)
     }
   }
 }

package/src/ir-to-client-js/plan/build-static-array-child-init.ts

@@ -16,7 +16,7 @@
 import type { IRLoopChildComponent } from '../../types'
 import type { NestedLoop, TopLevelLoop } from '../types'
 import type { ClientJsContext } from '../types'
-import { quotePropName, varSlotId, attrValueToString } from '../utils'
+import { quotePropName, varSlotId, attrValueToString, buildLoopChildIndexExpr } from '../utils'
 import { irChildrenToJsExpr } from '../html-template'
 import { buildCompSelector } from '../control-flow/shared'
 
@@ -98,7 +98,7 @@ function buildOuterNestedPlan(
     arrayExpr: elem.array,
     param: elem.param,
     indexParam,
-    offsetExpr: elem.siblingOffset ? `${indexParam} + ${elem.siblingOffset}` : indexParam,
+    offsetExpr: buildLoopChildIndexExpr(indexParam, elem.offset),
     outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
     propsExpr: buildStaticPropsExpr(comp.props),
   }
@@ -122,16 +122,12 @@ function buildInnerLoopNestedPlan(
     outerArrayExpr: elem.array,
     outerParam: elem.param,
     outerIndexParam,
-    outerOffsetExpr: elem.siblingOffset
-      ? `${outerIndexParam} + ${elem.siblingOffset}`
-      : outerIndexParam,
+    outerOffsetExpr: buildLoopChildIndexExpr(outerIndexParam, elem.offset),
     outerPreludeStatements: elem.mapPreamble ? [elem.mapPreamble] : [],
     innerContainerSlotId: innerLoop.containerSlotId ?? null,
     innerArrayExpr: innerLoop.array,
     innerParam: innerLoop.param,
-    innerOffsetExpr: innerLoop.siblingOffset
-      ? `__innerIdx + ${innerLoop.siblingOffset}`
-      : '__innerIdx',
+    innerOffsetExpr: buildLoopChildIndexExpr('__innerIdx', innerLoop.offset),
     innerPreludeStatements: innerLoop.mapPreamble ? [innerLoop.mapPreamble] : [],
     depth: innerLoop.depth,
     comps,

package/src/ir-to-client-js/plan/static-array-child-init.ts

@@ -75,7 +75,7 @@ export interface OuterNestedInitPlan {
   arrayExpr: string
   param: string
   indexParam: string
-  /** `indexParam` or `${indexParam} + ${siblingOffset}` — already substituted. */
+  /** `indexParam` plus any sibling-offset terms (`+ 1 + (arr).length`) — already substituted. */
   offsetExpr: string
   /**
    * Outer `.map()` callback preamble locals (#1064), emitted inside the
@@ -99,7 +99,7 @@ export interface InnerLoopNestedInitPlan {
   outerArrayExpr: string
   outerParam: string
   outerIndexParam: string
-  /** Outer offset — `outerIndexParam` or `${outerIndexParam} + ${siblingOffset}`. */
+  /** Outer offset — `outerIndexParam` plus any sibling-offset terms. */
   outerOffsetExpr: string
   /**
    * Outer `.map()` callback preamble locals, emitted after the
@@ -115,7 +115,7 @@ export interface InnerLoopNestedInitPlan {
   innerContainerSlotId: string | null
   innerArrayExpr: string
   innerParam: string
-  /** Inner offset — `__innerIdx` or `__innerIdx + ${siblingOffset}`. */
+  /** Inner offset — `__innerIdx` plus any sibling-offset terms. */
   innerOffsetExpr: string
   /**
    * Inner `.map()` callback preamble locals, emitted after the

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

@@ -59,6 +59,16 @@ export interface ClientJsContext {
   loopElements: TopLevelLoop[]
   refElements: RefElement[]
   childInits: ChildInit[]
+  /**
+   * Slot ids of direct child components whose render is DEFERRED to init
+   * (dropped-prop fix). For these, the CSR registration template emits a
+   * `data-bf-ph` placeholder instead of `renderChild(...)`, and the init
+   * body uses `upsertChild` (→ `createComponent` with full getter props)
+   * instead of `initChild`. Computed in `generateInitFunction` once
+   * `unsafeLocalNames` is known, then read by the child-init phase and the
+   * registration-template emit so both agree on which children defer.
+   */
+  deferredChildSlots: Set<string>
   reactiveProps: ReactiveComponentProp[]
   reactiveChildProps: ReactiveChildProp[]
   reactiveAttrs: ReactiveAttribute[]
@@ -166,6 +176,29 @@ export interface ConditionalBranchReactiveAttr extends AttrMeta {
   expression: string
 }
 
+/**
+ * How many element children precede a loop's items in its container — the
+ * offset applied to `container.children[idx]` so each item resolves to the
+ * right element during hydration.
+ *
+ * Two contributions, kept distinct because they codegen differently:
+ *   - `staticCount`: siblings of statically-known element count, folded to a
+ *     compile-time integer (`+ 1`).
+ *   - `dynamicTerms`: one JS expression per sibling whose element count is
+ *     only known at runtime — a preceding `.map()` (`(arr).length`) or a
+ *     preceding conditional (`(cond ? 1 : 0)`) — each added as `+ <term>`.
+ *
+ * Carried as one value object end-to-end (collect → IR loop → plan → codegen)
+ * so a future offset contributor is added in one place, not threaded as a new
+ * field through every layer (#1693).
+ */
+export interface LoopOffset {
+  /** Folded element count of statically-sized preceding siblings. `0` = none. */
+  staticCount: number
+  /** Runtime element-count expressions of dynamic preceding siblings; `[]` = none. */
+  dynamicTerms: readonly string[]
+}
+
 /**
  * Fields shared by every flavour of collected loop (top-level, branch-scoped, nested).
  * The three loop-info variants (`TopLevelLoop`, `BranchLoop`, `NestedLoop`) each extend
@@ -363,8 +396,8 @@ export interface NestedLoop extends LoopCore {
   childComponents?: import('../types').IRLoopChildComponent[]
   /** True when this loop is inside a conditional branch (handled by insert() bindEvents instead) */
   insideConditional?: boolean
-  /** Number of non-loop DOM siblings before this loop in its container element */
-  siblingOffset?: number
+  /** Offset of this loop's items past its preceding container siblings (#1693). */
+  offset?: LoopOffset
   // Per-item bindings (events / reactiveAttrs / reactiveTexts / refs / conditionals)
   // now live on `LoopCore.bindings` — see issue #1244 §B.
 }
@@ -468,8 +501,8 @@ export interface TopLevelLoop extends LoopCore {
   useElementReconciliation?: boolean // True: reconcileElements + composite rendering (native root with child components)
   /** Inner loop metadata for composite element reconciliation (array, param, key, container) */
   innerLoops?: NestedLoop[]
-  /** Number of non-loop DOM siblings before this loop in its parent element. Used to offset children[idx] access. */
-  siblingOffset?: number
+  /** Offset of this loop's items past its preceding container siblings (#1693). */
+  offset?: LoopOffset
   filterPredicate?: {
     param: string
     raw: string  // Original filter predicate expression or block body