@barefootjs/jsx 0.17.0 → 0.18.0

package/src/index.ts

@@ -12,6 +12,10 @@ export type { CompileResult, CompileOptions, CompileOptionsWithAdapter, FileOutp
 export { extractSsrDefaults } from './ssr-defaults.ts'
 export type { SsrDefault } from './ssr-defaults.ts'
 
+// Backend-neutral SSR seed plan (in-template derived signal/memo seeding)
+export { computeSsrSeedPlan } from './ssr-seed-plan.ts'
+export type { SsrSeedPlan, SsrSeedStep } from './ssr-seed-plan.ts'
+
 // Pure IR types
 export type {
   ComponentIR,
@@ -22,6 +26,9 @@ export type {
   IRConditional,
   IRLoop,
   IRLoopChildComponent,
+  LoopParamBinding,
+  LoopBindingPathSegment,
+  RestExcludeKey,
   IRComponent,
   IRFragment,
   IRSlot,
@@ -46,6 +53,8 @@ export type {
   TypeDefinition,
   SourceLocation,
   CompilerError,
+  ConformancePin,
+  ConformancePins,
 } from './types.ts'
 
 // Analyzer
@@ -77,13 +86,15 @@ export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
 export { emitParsedExpr } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
-export { importsSearchParams, searchParamsLocalNames, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export { importsSearchParams, searchParamsLocalNames, envSignalLocalNames, envSignalReaderFor, ENV_SIGNAL_READERS, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export type { EnvSignalReader } from './adapters/env-signal.ts'
 export { matchQueryHrefCall, queryHrefArgs, type QueryHrefCall, type QueryHrefTriple } from './query-href-lowering.ts'
 export {
   registerLoweringPlugin,
   getLoweringPlugins,
   prepareLoweringMatchers,
   matchLoweringCall,
+  isValidHelperId,
   __resetLoweringPluginsForTest,
   type LoweringPlugin,
   type LoweringNode,
@@ -255,6 +266,22 @@ export interface BuildOptions {
    * Forwarded to `compileJSX` as `CompileOptions.localImportPrefixes`.
    */
   localImportPrefixes?: string[]
+  /**
+   * How the CLI produces `barefoot.js` (the client runtime bundle):
+   *   - `'treeshake'` (default) — bundle only the runtime exports this
+   *     project's compiled client JS actually imports, plus a small
+   *     always-kept public mount API (`render`, `hydrate`, etc.).
+   *   - `'full'` — copy the entire prebuilt runtime bundle verbatim.
+   * See `@barefootjs/cli`'s `runtime-treeshake.ts` for the collector and
+   * `ALWAYS_KEEP_RUNTIME_EXPORTS` for the always-kept names.
+   */
+  runtimeBundle?: 'treeshake' | 'full'
+  /**
+   * Extra `@barefootjs/client*` export names to force-keep in `barefoot.js`
+   * under `runtimeBundle: 'treeshake'` — for names only ever referenced
+   * from hand-written page scripts the CLI never compiles.
+   */
+  runtimeKeep?: string[]
 }
 
 // AttrValue constructors
@@ -276,12 +303,12 @@ export {
 export { ErrorCodes, createError, formatError, generateCodeFrame } from './errors.ts'
 
 // Expression Parser
-export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
+export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, freeIdentifiers, materializeGetterCalls, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'
 export type { ParsedExpr, ObjectLiteralProperty, ParsedStatement, SortComparator, SortKey, FlatDepth, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
 export { buildLoopChainExpr } from './loop-chain.ts'
 export type { LoopChainInputs } from './loop-chain.ts'
-export { isLowerableObjectRestDestructure } from './loop-destructure.ts'
+export { isLowerableLoopDestructure, isLowerableObjectRestDestructure } from './loop-destructure.ts'
 
 // Debug analysis
 export {

package/src/ir-to-client-js/collect-elements.ts

@@ -6,7 +6,7 @@ import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings } from './reactivity.ts'
-import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr } from './html-template.ts'
+import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate } from './html-template.ts'
 import { expandDynamicPropValue, expandConstantForReactivity } from './prop-handling.ts'
 import { walkIR, stopAt } from './walker.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
@@ -671,6 +671,7 @@ export function collectElements(
 
       let template = ''
       let staticItemTemplate: string | undefined
+      let skeletonTemplate: string | undefined
       if (l.childComponent) {
         template = '' // childComponent path uses createComponent directly
         // CSR materialize fallback (#1268): when the loop array references an
@@ -714,6 +715,18 @@ export function collectElements(
           staticItemTemplate = useElementReconciliation
             ? irToPlaceholderTemplate(l.children[0], buildRestSpreadNames(ctx), 0)
             : irToHtmlTemplate(l.children[0], buildRestSpreadNames(ctx), 0)
+        } else if (!useElementReconciliation && !l.bodyIsMultiRoot && !l.bodyIsItemConditional) {
+          // Hoisted shared-template fast path (perf): only for the plain
+          // `mapArray` shape — single-root, dynamic array, no element
+          // reconciliation. `buildLoopSkeletonTemplate` re-derives safety
+          // from the raw IR (spread attrs, conditionals, unslotted dynamic
+          // expressions, …) and returns `null` for anything it can't prove
+          // safe; the plan builder (`build-loop.ts`) falls back to the
+          // per-row `template` above whenever this stays `undefined`.
+          skeletonTemplate = buildLoopSkeletonTemplate(l.children[0], {
+            reactiveAttrKeys: new Set(bindings.reactiveAttrs.map(a => `${a.childSlotId}::${a.attrName}`)),
+            reactiveTextSlotIds: new Set(bindings.reactiveTexts.map(t => t.slotId)),
+          }) ?? undefined
         }
       }
 
@@ -732,6 +745,7 @@ export function collectElements(
         iterationShape: l.iterationShape,
         template,
         staticItemTemplate,
+        skeletonTemplate,
         childEventHandlers: childHandlers,
         bindings,
         childComponent: l.childComponent,

package/src/ir-to-client-js/compute-inlinability.ts

@@ -64,7 +64,12 @@ export function buildEnvFromCtx(ctx: ClientJsContext): RelocateEnv {
       effects: ctx.effects,
       onMounts: ctx.onMounts,
       initStatements: ctx.initStatements,
-      imports: [],
+      // Real component imports (#2069) — `buildRelocateEnvFromIR` calls
+      // `prepareLoweringMatchers(metadata)` on this reconstructed object,
+      // and plugin `prepare()` resolves local import names from
+      // `metadata.imports`. `[]` here would silently disable every
+      // import-aware LoweringPlugin for the client-JS inline-safety gate.
+      imports: ctx.imports,
       templateImports: [],
       namedExports: [],
       localFunctions: ctx.localFunctions,

package/src/ir-to-client-js/control-flow/plan/build-loop.ts

@@ -102,6 +102,7 @@ export function buildPlainLoopPlan(elem: TopLevelLoop, profileComponentName?: st
     indexParam: elem.index || '__idx',
     mapPreambleWrapped: elem.mapPreamble ? wrap(elem.mapPreamble) : '',
     template: elem.template,
+    skeletonTemplate: elem.skeletonTemplate,
     reactiveEffects: hasReactive ? buildLoopReactiveEffectsPlan(elem, profileComponentName) : null,
     childRefs: buildChildRefBindings(elem.bindings.refs, elem.param, elem.paramBindings),
     bodyIsMultiRoot: elem.bodyIsMultiRoot ?? false,

package/src/ir-to-client-js/control-flow/plan/loop.ts

@@ -94,6 +94,15 @@ interface PlainLoopVariant extends DynamicLoopCommon {
   mapPreambleWrapped: string
   /** HTML template string for one item. */
   template: string
+  /**
+   * Shared once-per-loop skeleton template (perf) — see
+   * `buildLoopSkeletonTemplate` (html-template.ts). When present, the
+   * stringifier declares it once (before the `mapArray` call) and clones
+   * from it instead of re-parsing `template`'s interpolated innerHTML per
+   * row. `undefined` means the loop body wasn't proven safe to hoist; the
+   * stringifier falls back to the legacy per-row `emitTemplateCloneInline`.
+   */
+  skeletonTemplate?: string
   /** Resolved reactive-effects plan — null forces the single-line renderItem shape. */
   reactiveEffects: ReactiveEffectsPlan | null
   /**

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

@@ -27,7 +27,7 @@
 import { emitRefCall, varSlotId, profileBindingId } from '../../utils.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
 import { stringifyReactiveEffects } from './reactive-effects.ts'
-import { emitTemplateCloneInline, emitLoopItemElementSetup } from './template-parse.ts'
+import { emitTemplateCloneInline, emitLoopItemElementSetup, emitHoistedTemplateDecl, hoistedCloneExpr } from './template-parse.ts'
 import { stringifyComponentLoop } from './component-loop.ts'
 import { stringifyCompositeLoop } from './composite-loop.ts'
 import type { LoopChildRefBinding, LoopPlan, PlainLoopPlan, StaticLoopPlan } from '../plan/types.ts'
@@ -117,6 +117,7 @@ export function stringifyPlainLoop(
     indexParam,
     mapPreambleWrapped,
     template,
+    skeletonTemplate,
     reactiveEffects,
     childRefs,
     bodyIsMultiRoot,
@@ -133,6 +134,21 @@ export function stringifyPlainLoop(
     return
   }
 
+  // Hoisted shared-template fast path (perf, see `buildLoopSkeletonTemplate`):
+  // declare the once-per-loop template BEFORE the `mapArray` call so every
+  // row clones from an already-parsed node instead of re-running
+  // `document.createElement('template')` + an `innerHTML` parse per row.
+  // `bodyIsMultiRoot` is re-checked defensively even though the plan builder
+  // only sets `skeletonTemplate` when it's already false.
+  const hoistedTpl = !bodyIsMultiRoot && skeletonTemplate ? skeletonTemplate : null
+  // Keyed off `markerId` (unique per loop, #1087), NOT `containerVar` —
+  // sibling `.map()` calls under the same parent share the container slot,
+  // so a container-derived name would collide ("has already been declared").
+  const tplVar = `__tpl_${markerId.replace(/[^A-Za-z0-9_$]/g, '_')}`
+  if (hoistedTpl) {
+    emitHoistedTemplateDecl(lines, topIndent, tplVar, hoistedTpl)
+  }
+
   // `childRefs` need `__el` as a handle to invoke the user's callback inside
   // the factory, so non-empty refs force the multi-line layout the same way
   // reactive effects do (#1244).
@@ -141,7 +157,9 @@ export function stringifyPlainLoop(
     // Single-line renderItem (no reactive effects, single root, no refs).
     const unwrapInline = paramUnwrap ? `${paramUnwrap} ` : ''
     const preamble = mapPreambleWrapped ? `${mapPreambleWrapped}; ` : ''
-    const cloneExpr = emitTemplateCloneInline(template)
+    const cloneExpr = hoistedTpl
+      ? `return ${hoistedCloneExpr(tplVar, hoistedTpl)}`
+      : emitTemplateCloneInline(template)
     lines.push(
       `${topIndent}mapArray(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (${paramHead}, ${indexParam}, __existing) => { ${unwrapInline}${preamble}if (__existing) return __existing; ${cloneExpr} }, '${markerId}'${loopBfId})`,
     )
@@ -153,12 +171,16 @@ export function stringifyPlainLoop(
   const bodyIndent = topIndent + '  '
   if (paramUnwrap) lines.push(`${bodyIndent}${paramUnwrap}`)
   if (mapPreambleWrapped) lines.push(`${bodyIndent}${mapPreambleWrapped}`)
-  emitLoopItemElementSetup(lines, {
-    template,
-    bodyIsMultiRoot,
-    indent: bodyIndent,
-    singleRootLayout: 'inline',
-  })
+  if (hoistedTpl) {
+    lines.push(`${bodyIndent}const __el = __existing ?? ${hoistedCloneExpr(tplVar, hoistedTpl)}`)
+  } else {
+    emitLoopItemElementSetup(lines, {
+      template,
+      bodyIsMultiRoot,
+      indent: bodyIndent,
+      singleRootLayout: 'inline',
+    })
+  }
   if (reactiveEffects !== null) {
     stringifyReactiveEffects(lines, reactiveEffects, { indent: bodyIndent, elVar: '__el', bodyIsMultiRoot })
   }

package/src/ir-to-client-js/control-flow/stringify/template-parse.ts

@@ -145,6 +145,36 @@ export function emitTemplateCloneInline(template: string): string {
   return `const __tpl = document.createElement('template'); __tpl.innerHTML = \`${template}\`; return __tpl.content.firstElementChild.cloneNode(true)`
 }
 
+/**
+ * Emit the ONE-TIME declaration of a loop's hoisted shared template (perf):
+ * built once per loop, before the `mapArray` call, so every row clones from
+ * an already-parsed node instead of re-running `document.createElement
+ * ('template')` + an `innerHTML` parse per row. `skeletonTemplate` is the
+ * STATIC-ONLY skeleton produced by `buildLoopSkeletonTemplate` (dynamic attrs
+ * omitted, text markers empty) — never the per-row interpolated `template`.
+ *
+ * SVG namespace wrap mirrors `emitTemplateCloneLines` (#135 / #1088):
+ * `templateRootIsSvg` is re-checked against the skeleton (same root tag as
+ * the interpolated template, so the same wrap decision applies).
+ */
+export function emitHoistedTemplateDecl(lines: string[], indent: string, tplVar: string, skeletonTemplate: string): void {
+  const isSvg = templateRootIsSvg(skeletonTemplate)
+  const html = isSvg ? `<svg>${skeletonTemplate}</svg>` : skeletonTemplate
+  lines.push(`${indent}const ${tplVar} = document.createElement('template')`)
+  lines.push(`${indent}${tplVar}.innerHTML = \`${html}\``)
+}
+
+/**
+ * Clone expression reading off a hoisted template variable declared via
+ * `emitHoistedTemplateDecl`, in place of the per-row
+ * `emitTemplateCloneInline` / `emitTemplateCloneLines` parse-and-clone.
+ */
+export function hoistedCloneExpr(tplVar: string, skeletonTemplate: string): string {
+  return templateRootIsSvg(skeletonTemplate)
+    ? `${tplVar}.content.firstElementChild.firstElementChild.cloneNode(true)`
+    : `${tplVar}.content.firstElementChild.cloneNode(true)`
+}
+
 /**
  * Multi-line variant for code paths that emit each line separately.
  * Returns three statements with no trailing newlines.

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

@@ -102,8 +102,10 @@ export function buildInlinableConstants(
  * — the AST substitution + chain resolution now lives upstream.
  *
  * Excludes constants whose entry is `null` (unsafe to inline) — those
- * stay in `unsafeLocalNames` and the CSR template's expression
- * substitution surfaces the UNSAFE sentinel for any reference to them.
+ * are also folded into the unsafe set `generateCsrTemplate` uses
+ * internally (see `mergeCsrNullUnsafe` in html-template.ts, #2106), so
+ * every caller of `generateCsrTemplate` gets a consistent
+ * substitute-or-fallback decision with no extra wiring required here.
  */
 export function csrInlinableConstantsFromCtx(ctx: ClientJsContext): Map<string, string> {
   const out = new Map<string, string>()

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

@@ -702,6 +702,139 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
   }
 }
 
+/**
+ * Slots a top-level (`mapArray`-driven) loop body proves safe to hoist into a
+ * shared, once-per-loop template (perf: avoid per-row `document.createElement
+ * ('template')` + innerHTML parse + escapeText/escapeAttr, see
+ * `buildLoopSkeletonTemplate`).
+ */
+export interface LoopSkeletonSafeSlots {
+  /** `"<childSlotId>::<attrName>"` pairs already covered by a loop-child reactive-attribute `createEffect`. */
+  reactiveAttrKeys: ReadonlySet<string>
+  /** Text-marker slot ids already covered by a loop-child reactive-text `createEffect`. */
+  reactiveTextSlotIds: ReadonlySet<string>
+}
+
+/**
+ * Build the STATIC skeleton of a top-level loop body — the shared template
+ * cloned once per row instead of re-parsed from a per-row interpolated
+ * `innerHTML` string (perf: create-heavy `.map()` loops, see
+ * spec/compiler.md "Loop emission shapes").
+ *
+ * The skeleton keeps every static element / attr / text verbatim, keeps `bf="sN"`
+ * marker attributes (needed for `qsa` / `$t` lookups), and keeps text-marker
+ * comments (`<!--bf:sN--><!--/-->`) but EMPTIES the interpolation between them.
+ * Every dynamic attribute is DROPPED entirely rather than interpolated — both
+ * forms rely on the loop-child `createEffect`s (already emitted alongside the
+ * clone, see `stringifyReactiveEffects`) to fill in the real value on their
+ * eager first run, so nothing is lost — UNLESS a dynamic attr/text isn't
+ * proven covered by one of those effects, in which case this function refuses
+ * (returns `null`) and the caller falls back to the per-row interpolated
+ * template (`irToHtmlTemplate`). `key` is special-cased to an always-empty
+ * `data-key=""` placeholder — `mapArray` stamps the real key onto freshly
+ * created elements itself (see `map-array.ts`), so the clone path never needs
+ * to bake one in.
+ *
+ * Refuses (returns `null`) on anything not proven safe: spread attrs,
+ * `dangerouslySetInnerHTML`, a dynamic attribute/text not present in `safe`,
+ * a bare (unslotted) dynamic expression (no DOM anchor to backfill later),
+ * conditionals, child components, nested loops, and provider/async/if-statement
+ * boundaries. Callers additionally gate on the loop shape itself (single-root,
+ * non-static, no `useElementReconciliation`) before invoking this — see
+ * `collect-elements.ts`'s `loop` visitor.
+ */
+export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSlots): string | null {
+  switch (node.type) {
+    case 'element': {
+      const attrParts: string[] = []
+      for (const a of node.attrs) {
+        if (a.name === '...') return null
+        if (a.name === 'dangerouslySetInnerHTML') return null
+        if (a.name === 'key') {
+          attrParts.push(`${keyAttrName(0)}=""`)
+          continue
+        }
+        const v = a.value
+        switch (v.kind) {
+          case 'literal':
+            attrParts.push(`${toHtmlAttrName(a.name)}="${v.value}"`)
+            break
+          case 'boolean-attr':
+            attrParts.push(toHtmlAttrName(a.name))
+            break
+          case 'boolean-shorthand':
+          case 'jsx-children':
+            // Never legal on an intrinsic element in well-formed IR — emit nothing.
+            break
+          case 'expression':
+          case 'template': {
+            const attrKey = node.slotId ? `${node.slotId}::${a.name}` : null
+            if (!attrKey || !safe.reactiveAttrKeys.has(attrKey)) return null
+            // Covered by a loop-child createEffect — omit from the skeleton
+            // entirely; the effect's eager first run fills it in.
+            break
+          }
+          case 'spread':
+            return null
+        }
+      }
+
+      if (node.slotId) attrParts.push(`bf="${node.slotId}"`)
+
+      const attrs = attrParts.join(' ')
+      let children = ''
+      for (const child of node.children) {
+        const rendered = buildLoopSkeletonTemplate(child, safe)
+        if (rendered === null) return null
+        children += rendered
+      }
+
+      if (children || !VOID_ELEMENTS.has(node.tag)) {
+        return `<${node.tag}${attrs ? ' ' + attrs : ''}>${children}</${node.tag}>`
+      }
+      return `<${node.tag}${attrs ? ' ' + attrs : ''} />`
+    }
+
+    case 'text':
+      return node.value
+
+    case 'expression':
+      if (node.expr === 'null' || node.expr === 'undefined') return ''
+      if (!node.slotId) {
+        // No DOM anchor to backfill later — this is a one-time SSR-baked
+        // value with no corresponding createEffect. Can't safely omit.
+        return null
+      }
+      if (!safe.reactiveTextSlotIds.has(node.slotId)) return null
+      return `<!--bf:${node.slotId}--><!--/-->`
+
+    case 'fragment': {
+      let out = ''
+      for (const child of node.children) {
+        const rendered = buildLoopSkeletonTemplate(child, safe)
+        if (rendered === null) return null
+        out += rendered
+      }
+      return out
+    }
+
+    // Conditionals, child components, nested loops, and provider/async/
+    // if-statement/slot boundaries are all out of scope for the hoisted
+    // fast path — the caller falls back to `irToHtmlTemplate`.
+    case 'conditional':
+    case 'component':
+    case 'loop':
+    case 'if-statement':
+    case 'provider':
+    case 'async':
+    case 'slot':
+      return null
+
+    default:
+      return assertNever(node)
+  }
+}
+
 /**
  * Generate an HTML template for composite element reconciliation.
  * Identical to irToHtmlTemplate except component nodes become placeholder
@@ -1382,7 +1515,71 @@ export function generateCsrTemplate(
       }
     }
   }
-  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames, deferredChildSlots, loopDepth: -1 })
+  const effectiveUnsafeLocalNames = mergeCsrNullUnsafe(ctx, unsafeLocalNames)
+  return generateCsrTemplateWithOpts(node, { inlinableConstants, restSpreadNames, propsObjectName, csrEnv, insideLoop, unsafeLocalNames: effectiveUnsafeLocalNames, deferredChildSlots, loopDepth: -1 })
+}
+
+/**
+ * Fold `ctx.csrInlinable`'s null verdicts into `unsafeLocalNames`, so
+ * `generateCsrTemplate`'s callers can't independently drift out of sync
+ * with `ctx.csrInlinable` (#2106).
+ *
+ * The two "is this constant's value safe to inline into a module-scope
+ * template" checks in `compute-inlinability.ts` can legitimately disagree:
+ *
+ *   - Stage-2 classification (`classifyConstantInitial`) runs
+ *     `isInlinableInTemplate` on the RAW initializer text — deliberately,
+ *     so it can still see bridged prop args (`useYjs(props.X)`) for the
+ *     #1138 rejection. A call whose raw receiver is an identifier path
+ *     (`someModuleArray.includes(name)`) can pass this check (e.g. an
+ *     adapter with a broad `acceptsTemplateCall` accepts any
+ *     identifier-path callee) even though `name` is a bridged prop arg.
+ *   - `populateCsrInlinable` re-runs the same check on the
+ *     CSR-*substituted* form, where `someModuleArray` has already been
+ *     literal-inlined (`['a','b'].includes(name)`). The callee is no
+ *     longer an identifier path at all, so the adapter can't vouch for
+ *     it, and the bridged-arg rejection correctly fires — recorded as
+ *     `ctx.csrInlinable.get(name) === null`.
+ *
+ * `unsafeLocalNames` (passed in from the Stage-2-derived
+ * `toLegacyInlinability` result) only reflects the first, looser verdict,
+ * so a name `populateCsrInlinable` refused could still be missing from
+ * it. Left alone, `transformExpr` below finds no CSR substitution for the
+ * name (`inlinableConstants` — built from `ctx.csrInlinable` by the
+ * caller — excludes null entries) AND no unsafe flag, so the bare,
+ * module-scope-invisible identifier leaks straight into the emitted
+ * template text (`ReferenceError` at template evaluation, #2106).
+ *
+ * `ctx.csrInlinable` is the ground truth for the CSR path — this makes it
+ * the single source added to (never subtracted from) the effective
+ * unsafe set used below: any post-substitution refusal is unsafe here,
+ * full stop, regardless of what the looser Stage-2 check concluded.
+ * Doing this once, inside `generateCsrTemplate` itself, means every
+ * caller (the full-init path in `emit-registration.ts` AND the
+ * template-only path in `index.ts`) gets the correction for free instead
+ * of each needing to remember to fold `ctx.csrInlinable` in themselves.
+ *
+ * System-construct (`createContext()`, `new WeakMap()`) and JSX-inline
+ * constants are exempted even though `populateCsrInlinable` also marks
+ * them `null` — that's "not applicable" routing (module-scope singleton
+ * referenced by name at runtime / already inlined at IR level), not an
+ * unsafe reference, and `toLegacyInlinability` never treated them as
+ * unsafe either.
+ */
+function mergeCsrNullUnsafe(ctx: ClientJsContext, unsafeLocalNames: Set<string> | undefined): Set<string> | undefined {
+  let merged: Set<string> | null = null
+  // Built lazily on the first null verdict, so the common all-inlinable
+  // component pays nothing; a Set keeps the merge linear in the number
+  // of local constants instead of a per-name `.find()` scan.
+  let exemptNames: Set<string> | null = null
+  for (const [name, entry] of ctx.csrInlinable) {
+    if (entry !== null || unsafeLocalNames?.has(name)) continue
+    exemptNames ??= new Set(ctx.localConstants.filter((c) => c.isJsx || c.systemConstructKind).map((c) => c.name))
+    if (exemptNames.has(name)) continue
+    if (!merged) merged = new Set(unsafeLocalNames ?? [])
+    merged.add(name)
+  }
+  return merged ?? unsafeLocalNames
 }
 
 /**

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

@@ -171,6 +171,7 @@ function createContext(
     initStatements: ir.metadata.initStatements ?? [],
     localFunctions: ir.metadata.localFunctions,
     localConstants: ir.metadata.localConstants,
+    imports: ir.metadata.imports,
     propsParams: ir.metadata.propsParams,
     propsObjectName: ir.metadata.propsObjectName,
     restPropsName: ir.metadata.restPropsName,

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

@@ -19,6 +19,7 @@ import type {
   ConstantInfo,
   ParamInfo,
   CompilerError,
+  ImportInfo,
 } from '../types.ts'
 import type { CsrInlinabilityMap } from './csr-substitute.ts'
 
@@ -53,6 +54,15 @@ export interface ClientJsContext {
   initStatements: InitStatementInfo[]
   localFunctions: FunctionInfo[]
   localConstants: ConstantInfo[]
+  /**
+   * Component-file import list, threaded through so `buildEnvFromCtx`'s
+   * reconstructed `IRMetadata`-shaped object carries REAL imports (#2069)
+   * — `prepareLoweringMatchers` needs the real list to resolve a
+   * `LoweringPlugin`'s local import names (e.g. `queryHrefLocalNames`);
+   * an empty `imports: []` would silently disable every import-aware
+   * plugin for the client-JS inline-safety gate.
+   */
+  imports: ImportInfo[]
   propsParams: ParamInfo[]
   propsObjectName: string | null
   restPropsName: string | null
@@ -497,6 +507,18 @@ export interface TopLevelLoop extends LoopCore {
    * that becomes `[]` in the CSR template substitution.
    */
   staticItemTemplate?: string
+  /**
+   * Shared once-per-loop skeleton template (perf), built by
+   * `buildLoopSkeletonTemplate` when the loop body is a statically-analyzable
+   * single-root element tree whose only dynamic parts are text/attribute
+   * slots already covered by a loop-child `createEffect`. Present only for
+   * dynamic (`mapArray`) top-level loops that pass the safety predicate in
+   * `collect-elements.ts`'s `loop` visitor — `undefined` means "fall back to
+   * the per-row interpolated `template` above" (conditionals, spread attrs,
+   * multi-root bodies, nested components/loops, or any dynamic attr/text not
+   * proven covered by an effect).
+   */
+  skeletonTemplate?: string
   childEventHandlers: string[] // Bare-identifier event handler names (for the reachability graph)
   childComponent?: IRLoopChildComponent // For createComponent-based rendering
   nestedComponents?: IRLoopChildComponent[] // For nested components in loop bodies