@barefootjs/jsx 0.34.0 → 0.35.0

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

@@ -0,0 +1,243 @@
+/**
+ * Escape-by-default for client-JS HTML template strings (#2795).
+ *
+ * Every builder in `html-template.ts` assembles a JS template literal whose
+ * `${...}` holes are evaluated in the browser and parsed as HTML
+ * (`innerHTML`). Whether a hole's value is escaped used to be an OPT-IN each
+ * builder remembered separately — `escapeInClientTemplate` on the IR node, a
+ * pre-baked `escapeText(...)` string in `templateExpr`, an
+ * `escapeLeafTextExpressions` rewrite pass, and a hand-rolled `escapeText`
+ * in `buildPreambleRegionPlans` — and a forgotten opt-in shipped raw text
+ * twice (#1694, #2765/#2792). This module inverts that:
+ *
+ *   - `SafeHtml` is a compile-time nominal brand (the `TsxSourceText`
+ *     precedent, `types.ts`) on a JS EXPRESSION STRING meaning "when this
+ *     evaluates in the client template, the result is HTML that is safe to
+ *     concatenate in". Nothing outside this module can construct one, so a
+ *     `SafeHtml` value is the compiler vouching for itself — unlike the
+ *     runtime `bfMarkup()` brand (`@barefootjs/client/runtime`), which
+ *     vouches for a value the compiler never saw.
+ *   - `interp` is the ONLY way to turn a value into a `${...}` hole, and it
+ *     accepts `SafeHtml` only. A builder holding a plain `string` cannot
+ *     splice it: it must either go through a named producer below (each of
+ *     which documents WHY its output is safe) or through `spliceChildValue`,
+ *     the door for a child-position expression, whose default is
+ *     `escapeText(...)`.
+ *
+ * The runtime dispatch that already existed for values the compiler cannot
+ * classify statically is unchanged: a branch-slot value still goes through
+ * `__bfSlot` (may be a live Node), a claim-plan `'markup'` slot still goes
+ * through `escapeTextOrMarkup` (may be a `bfMarkup()`-branded prop). Those
+ * are producers here too — they escape internally, so their output is safe
+ * by construction.
+ *
+ * Attribute-value holes (`escapeAttr`, `spreadAttrs`) are a separate,
+ * always-on path in `html-template.ts` and are not routed through this
+ * module; `client-template-escape-soundness.test.ts` pins their count.
+ */
+
+import type { IRExpression } from '../types.ts'
+
+/**
+ * A JS expression string that evaluates, in the client template, to HTML
+ * safe to splice raw. Branded at construction by the producers below; only
+ * `interp` consumes it.
+ */
+export type SafeHtml = string & { readonly __safeHtmlBrand: unique symbol }
+
+/** The single place the brand is applied. Module-private on purpose. */
+function safeHtml(expr: string): SafeHtml {
+  return expr as SafeHtml
+}
+
+/**
+ * Emit a `${...}` hole. The parameter type is the whole mechanism: a builder
+ * that has only a `string` in hand cannot call this, so "forgot to escape"
+ * is a type error at the splice, not a runtime surprise in the browser.
+ */
+export function interp(span: SafeHtml): string {
+  return `\${${span}}`
+}
+
+// ---------------------------------------------------------------------------
+// Producers — escaping forms. Each wraps a runtime helper from
+// `@barefootjs/client/runtime` (see `imports.ts`'s allowlist) that escapes
+// its own input.
+// ---------------------------------------------------------------------------
+
+/** `escapeText(expr)` — the default for any child-position value. */
+export function escapedText(expr: string): SafeHtml {
+  return safeHtml(`escapeText(${expr})`)
+}
+
+/**
+ * `escapeTextOrMarkup(expr)` — `escapeText`'s strict superset that unwraps a
+ * `bfMarkup()`-branded value raw (#2651). Used only for a slot whose
+ * REACTIVE claim writer is `kind: 'markup'` (`markup-slots.ts`), so the
+ * initial render and the update agree on whether the slot may carry a
+ * compiler-built JSX prop value.
+ */
+export function escapedTextOrMarkup(expr: string): SafeHtml {
+  return safeHtml(`escapeTextOrMarkup(${expr})`)
+}
+
+/**
+ * `__bfSlot(expr, slots)` — a conditional-branch `template()` value. The
+ * runtime returns raw `<!--bf-slot:N-->` markers for live Nodes (spliced
+ * back by `insert()`) and `escapeText`s every string itself
+ * (`branch-slot.ts`). Wrapping this in another escape corrupts the markers
+ * and drops slotted content (the #1694 regression) — hence a producer, not
+ * an input to `escapedText`.
+ */
+export function branchSlotValue(expr: string, slotsVar: string): SafeHtml {
+  return safeHtml(`__bfSlot(${expr}, ${slotsVar})`)
+}
+
+// ---------------------------------------------------------------------------
+// Producers — already-HTML forms. The value is markup the compiler or
+// runtime built (and escaped piecewise) BEFORE it reaches the hole.
+// ---------------------------------------------------------------------------
+
+/**
+ * `markupOrEmpty(expr)` — a bare `{children}` passthrough (#2775). The value
+ * is the HTML string `materializeComponent` joined from the caller's
+ * children, or `undefined` when none were passed; the helper's entire job is
+ * the nullish case. Never escaped: escaping would render real child markup
+ * as visible `&lt;span&gt;` text.
+ */
+export function childrenMarkup(expr: string): SafeHtml {
+  return safeHtml(`markupOrEmpty(${expr})`)
+}
+
+/**
+ * Stage 3 / D4 — an element-array child (`{out}`) built by an arbitrary
+ * `.map()` preamble is an array of compiled-leaf HTML strings; join it
+ * rather than let `${[...]}` `String`-comma-collapse it. Each leaf's own
+ * holes already went through `interp`, so the concatenation is exactly as
+ * safe as any other compiler-emitted fragment. Also used by
+ * `buildPreambleRegionPlans` for the region-patch effect's value so the
+ * re-render matches the row template byte-for-byte.
+ */
+export function joinedMarkup(expr: string): SafeHtml {
+  return safeHtml(`Array.isArray(${expr}) ? ${expr}.join('') : (${expr} ?? '')`)
+}
+
+/**
+ * `renderChild('Name', props, ...scopeArgs)` — a child component rendered
+ * from its registered template at runtime. Its output is that component's
+ * own compiled template, whose holes went through this module in turn.
+ */
+export function renderChildCall(registryName: string, propsExpr: string, tailArgs: string): SafeHtml {
+  return safeHtml(`renderChild('${registryName}', ${propsExpr}${tailArgs})`)
+}
+
+/**
+ * `dangerouslySetInnerHTML={{ __html: E }}` — the intentional, React-style,
+ * author-facing escape hatch, and the ONLY one: the element's content is
+ * whatever `E.__html` holds, unescaped by design (mirroring every SSR
+ * adapter's native handling). The name carries the warning so an audit of
+ * raw-markup producers (`grep dangerousInnerHtml`) finds it.
+ */
+export function dangerousInnerHtml(expr: string): SafeHtml {
+  return safeHtml(`((${expr}) ?? {}).__html ?? ''`)
+}
+
+/**
+ * `cond ? \`whenTrue\` : \`whenFalse\`` — both branches are compiled
+ * template-literal BODIES (already-assembled HTML with `interp`ed holes),
+ * not values; the condition only selects between them.
+ */
+export function conditionalMarkup(condition: string, whenTrue: string, whenFalse: string): SafeHtml {
+  return safeHtml(`${condition} ? \`${whenTrue}\` : \`${whenFalse}\``)
+}
+
+/**
+ * `array.method(params => body).join('')` — a loop rendered inline. `body`
+ * is either a compiled row template literal (\`...\`), a preamble block
+ * returning one, or a flatMap descriptor body rendered through
+ * `renderPreamble`; every hole inside it went through `interp`.
+ */
+export function mappedRowsMarkup(arrayExpr: string, method: string, params: string, body: string): SafeHtml {
+  return safeHtml(`${arrayExpr}.${method}(${params} => ${body}).join('')`)
+}
+
+/** The empty string literal — a deferred placeholder the init effect fills (#1128). */
+export const EMPTY_MARKUP: SafeHtml = safeHtml("''")
+
+// ---------------------------------------------------------------------------
+// The door for a child-position expression node.
+// ---------------------------------------------------------------------------
+
+/**
+ * Recognizes a JSX child-position expression that is exactly a reference to
+ * the reserved `children` prop — bare `children` (destructured) or
+ * `<receiver>.children` for any single-identifier receiver (`props.children`,
+ * a custom props-param name, a loop-scoped alias closing over props, ...).
+ *
+ * Deliberately LOOSER than `isTransparentFragment` (`jsx-to-ir.ts`), which
+ * runs on the TS AST with the analyzer-resolved props name in hand. This
+ * layer works on IR text with no analyzer, so any single-identifier receiver
+ * is the available approximation. The looseness costs nothing measurable: an
+ * unrelated `.children` member (a tree node's own `children` array, say) is a
+ * reactive member expression that gets a `slotId` and takes the slotted arm
+ * of `spliceChildValue` before this predicate is consulted.
+ */
+function isChildrenPassthroughExpr(expr: string): boolean {
+  return /^([A-Za-z_$][\w$]*\.)?children$/.test(expr.trim())
+}
+
+export interface ChildSpliceContext {
+  /**
+   * Set while emitting inside a conditional-branch `template()` arrow
+   * (`irToHtmlTemplate`'s `branchSlotsVar`): every value in that context is
+   * routed through `__bfSlot`, which owns its own coercion.
+   */
+  readonly branchSlotsVar?: string
+  /**
+   * Slot ids whose reactive claim writer is `kind: 'markup'`
+   * (`markupSlotIdsOf(ctx)`, `markup-slots.ts`). Absent for the loop-row /
+   * branch-row builders, whose reactive twin is a `kind: 'text'` writer
+   * (`String(...)` into `nodeValue`) — plain `escapeText` is the consistent
+   * choice there, and it is also the choice that never unwraps a
+   * `bfMarkup()`-shaped object arriving in JSON-sourced loop data.
+   */
+  readonly markupSlotIds?: ReadonlySet<string>
+}
+
+/**
+ * THE door for a child-position `IRExpression` value entering a client HTML
+ * template. Takes the caller's already-wrapped/transformed expression text
+ * (`wrapExpr` / `transformExpr` output) and decides, in exactly one place,
+ * which producer it goes through. The last arm is the default, and it
+ * escapes: there is no arm that returns `valueExpr` unwrapped.
+ *
+ * Arms, first match wins:
+ *   1. `joinArrayChild`         → `joinedMarkup`      (array of compiled leaves)
+ *   2. `branchSlotsVar`         → `branchSlotValue`   (runtime coercion, may be a Node)
+ *   3. `slotId` ∈ markupSlotIds → `escapedTextOrMarkup`
+ *   4. `slotId`                 → `escapedText`
+ *   5. `{children}` passthrough → `childrenMarkup`    (bare splice only, #2775/#2786)
+ *   6. otherwise                → `escapedText`
+ *
+ * Arm 5 tests BOTH `node.expr` (the original source text, stable across
+ * builders) and the caller's resolved form (parens stripped): a
+ * destructured-and-renamed children (`const { children: kids } = props`)
+ * reads `kids` in the source and `(_p.children)` after substitution, and
+ * either alone misses one of the two shapes (#2786).
+ */
+export function spliceChildValue(
+  node: Pick<IRExpression, 'expr' | 'slotId' | 'joinArrayChild'>,
+  valueExpr: string,
+  cx: ChildSpliceContext,
+): SafeHtml {
+  if (node.joinArrayChild) return joinedMarkup(valueExpr)
+  if (cx.branchSlotsVar) return branchSlotValue(valueExpr, cx.branchSlotsVar)
+  if (node.slotId) {
+    return cx.markupSlotIds?.has(node.slotId) ? escapedTextOrMarkup(valueExpr) : escapedText(valueExpr)
+  }
+  const resolved = valueExpr.trim().replace(/^\(+|\)+$/g, '')
+  if (isChildrenPassthroughExpr(node.expr) || isChildrenPassthroughExpr(resolved)) {
+    return childrenMarkup(valueExpr)
+  }
+  return escapedText(valueExpr)
+}

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

@@ -581,17 +581,63 @@ function renderLoopBindingAccess(b: LoopParamBinding, base: string): string {
  * binding name is rewritten to `__bfItem()${path}` instead of wrapping the
  * raw pattern text. `paramName` is ignored in that case — destructured
  * callbacks never expose the pattern itself as a local.
- */
-export function wrapLoopParamAsAccessor(expr: string, paramName: string, bindings?: readonly LoopParamBinding[]): string {
+ *
+ * `indexParam` (#2859): the same `.map()` callback's index parameter
+ * (`(item, i) => ...`'s `i`), when the loop declares one. `mapArray`/
+ * `mapArrayAnchored` hand `renderItem` an INDEX ACCESSOR (mirroring the item
+ * accessor) precisely so a same-key reorder — which never re-invokes
+ * `renderItem`, only pushes fresh values through the item/index signals —
+ * can keep a row's index-derived output live. A bare reference to
+ * `indexParam` is therefore rewritten the same way as the item param; a
+ * caller that never threads an index through (e.g. no second callback
+ * param) simply omits it and behavior is unchanged. Rewritten as a SEPARATE
+ * pass after the item/bindings rewrite so an index name that happens to
+ * collide with a destructured binding name is a no-op here (the binding
+ * rewrite already consumed it; `!== paramName` below only guards the plain,
+ * non-destructured case, since `bindings` and `paramName` are mutually
+ * exclusive inputs to the item rewrite above).
+ */
+export function wrapLoopParamAsAccessor(
+  expr: string,
+  paramName: string,
+  bindings?: readonly LoopParamBinding[],
+  indexParam?: string | null,
+): string {
+  let result: string
   if (bindings && bindings.length > 0) {
-    return rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
+    result = rewriteLoopBindingRefs(expr, bindings, '__bfItem()')
+  } else {
+    // `paramName` is a legal JS identifier and may itself start with `$`
+    // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
+    // reading those as backreference/whole-match sequences, so use a replacer
+    // function to insert the accessor text literally (#2592).
+    const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+    result = replaceInExprContexts(expr, re, () => `${paramName}()`)
+  }
+  if (indexParam && indexParam !== paramName) {
+    result = wrapIndexParamAsAccessor(result, indexParam)
   }
-  // `paramName` is a legal JS identifier and may itself start with `$`
-  // (`$1`, `$&`, …) — a plain string replacement would risk `String.replace`
-  // reading those as backreference/whole-match sequences, so use a replacer
-  // function to insert the accessor text literally (#2592).
-  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(paramName)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
-  return replaceInExprContexts(expr, re, () => `${paramName}()`)
+  return result
+}
+
+/**
+ * The index-only half of `wrapLoopParamAsAccessor` — same regex shape, own
+ * identifier. Factored out so `wrapLoopParamAsAccessor` can run it as a
+ * second pass regardless of which item-rewrite branch (bindings vs. plain
+ * param) ran first (#2859).
+ *
+ * Also exported standalone for `build-loop.ts`/`build-branch-loop.ts`: a
+ * plain loop's `template`/`mapPreambleWrapped` are built ONCE, before lazy
+ * eligibility is known, because the lazy row plan reuses them verbatim when
+ * this loop turns out to be lazy-eligible (`mapArrayLazy`'s `createRow`
+ * still hands the row a plain index NUMBER, never an accessor). So those two
+ * builders wrap item references up front (safe either way) and apply this
+ * index-only pass afterward, ONLY once `buildLazyRowPlan` confirms the loop
+ * is NOT going lazy.
+ */
+export function wrapIndexParamAsAccessor(expr: string, indexParam: string): string {
+  const re = new RegExp(`${ID_BOUNDARY_BEFORE}${escapeIdentifierForRegex(indexParam)}(?!\\s*\\()(?!-)${ID_BOUNDARY_AFTER}`, 'gu')
+  return replaceInExprContexts(expr, re, () => `${indexParam}()`)
 }
 
 /**
@@ -718,6 +764,8 @@ export function substituteLoopBindings(
 export interface LoopParamSpec {
   param: string
   bindings?: readonly LoopParamBinding[]
+  /** This loop's index parameter name, when it declares one (#2859). */
+  index?: string | null
 }
 
 /**
@@ -747,7 +795,7 @@ export function wrapExprWithLoopParams(expr: string, loopParams?: ReadonlyArray<
   let result = expr
   for (const p of loopParams) {
     const spec = typeof p === 'string' ? { param: p } : p
-    result = wrapLoopParamAsAccessor(result, spec.param, spec.bindings)
+    result = wrapLoopParamAsAccessor(result, spec.param, spec.bindings, spec.index)
   }
   return result
 }

package/src/jsx-to-ir.ts

@@ -18,6 +18,7 @@ import {
   type IRIfStatement,
   type IRProvider,
   type IRAttribute,
+  type ExpressionAttr,
   type IREvent,
   type IRProp,
   type AttrValue,
@@ -606,12 +607,14 @@ function collectBranchLocalPropRefsViaSubstitution(
   let acc: Set<string> | undefined
   function visit(n: ts.Node, parent?: ts.Node) {
     if (ts.isIdentifier(n) && propDepsMap!.has(n.text)) {
-      // Same skip rules as `collectAstPropRefs` — only value
-      // positions count, not object keys / property-access names.
+      // Same skip rules as `collectAstPropRefs` — only value positions
+      // count, not object keys / property-access names. A shorthand
+      // property (`{ page }`) IS a value reference (#2828) — its name
+      // is simultaneously the key and the value — so it participates
+      // here too, same as `collectAstPropRefs`.
       const isObjectKey = parent && ts.isPropertyAssignment(parent) && parent.name === n
-      const isShorthand = parent && ts.isShorthandPropertyAssignment(parent) && parent.name === n
       const isAccessName = parent && ts.isPropertyAccessExpression(parent) && parent.name === n
-      if (!isObjectKey && !isShorthand && !isAccessName) {
+      if (!isObjectKey && !isAccessName) {
         const deps = propDepsMap!.get(n.text)
         if (deps && deps.size > 0) {
           if (!acc) acc = new Set()
@@ -1484,15 +1487,13 @@ function lowerFormControlValueSsr(
 
   if (tagName === 'textarea') {
     if (children.length > 0) return
+    // A plain text child: SSR engines escape text children natively, and
+    // the client builders escape every child-position value by default
+    // (`ir-to-client-js/safe-html.ts`, #2795) — nothing to mark here.
     children.push({
       type: 'expression',
       expr,
-      // Escaped for client string-building; `expr` stays raw since SSR
-      // engines escape text children natively.
-      templateExpr: `escapeText(${templateExpr ?? expr})`,
-      // Init-scope builders can't just swap in `templateExpr` (its `_p.`
-      // binding differs) — see `escapeInClientTemplate`'s docstring.
-      escapeInClientTemplate: true,
+      templateExpr,
       typeInfo: null,
       reactive: false,
       slotId: null,
@@ -1502,7 +1503,7 @@ function lowerFormControlValueSsr(
     return
   }
 
-  const selectedForLiteral = (optValue: string): AttrValue =>
+  const selectedForLiteral = (optValue: string): ExpressionAttr =>
     AttrValueOf.expression(
       `(${expr}) === ${JSON.stringify(optValue)}`,
       templateExpr !== undefined
@@ -1519,35 +1520,129 @@ function lowerFormControlValueSsr(
   // `classifyLazyBinding` already know how to place into both `applyItem`
   // (row changed) and `applyOuter` (controlled value changed) — no new loop
   // machinery, just one more per-row reactive attribute (#2466).
-  const selectedForExpr = (optExpr: string, optTemplateExpr: string | undefined): AttrValue =>
+  const selectedForExpr = (optExpr: string, optTemplateExpr: string | undefined): ExpressionAttr =>
     AttrValueOf.expression(
       `(${expr}) === (${optExpr})`,
       templateExpr !== undefined || optTemplateExpr !== undefined
         ? { templateExpr: `(${templateExpr ?? expr}) === (${optTemplateExpr ?? optExpr})` }
         : undefined,
     )
+  // #2758: a bound value outside the option set makes SSR and hydration
+  // disagree about what "no match" means. SSR (below) never marks any
+  // `<option>` `selected`, so the browser falls back to its own default —
+  // the FIRST option. Hydration's controlled-value effect then assigns
+  // `select.value` directly (`emitValueUpdateStatements` in
+  // `ir-to-client-js/emit-reactive.ts`), and a value matching no option
+  // yields `selectedIndex = -1` (nothing selected). So the page renders
+  // showing the first option, and the moment hydration runs the selection
+  // visibly disappears.
+  //
+  // Resolution: treat the client's reading as correct ("no match" means no
+  // selection) and make SSR able to express it. When every `<option>` here
+  // is statically enumerable (no `.map()` loop, no conditional/component/
+  // slot child, no author-supplied `selected`), collect each option's match
+  // condition and, for a single-selection `<select>` (not `multiple`, not
+  // `size` > 1 — a list-box already shows no implicit default, so SSR and
+  // hydration already agree there), inject a hidden `disabled` placeholder
+  // option whose own `selected` is the negation of every real option's
+  // condition ORed together. It is only ever actually selected when nothing
+  // else matched, so it changes nothing for the common case where the value
+  // does match an option.
+  //
+  // Bails (leaves prior behaviour) whenever the option set isn't fully
+  // statically known — a `.map()`-rendered list has an unknown number of
+  // rows at compile time, so there is no finite OR to negate.
+  const matchConditions: ExpressionAttr[] = []
+  let optionSetIsDynamic = false
+
   const distribute = (nodes: IRNode[]): void => {
     for (const n of nodes) {
+      if (n.type === 'text') continue
       if (n.type === 'element' && n.tag === 'option') {
-        if (n.attrs.some(a => a.name === 'selected')) continue
+        if (n.attrs.some(a => a.name === 'selected')) {
+          optionSetIsDynamic = true
+          continue
+        }
         const optValue = n.attrs.find(a => a.name === 'value')
-        if (!optValue) continue
+        if (!optValue) {
+          // No `value` attr: the browser falls back to the option's text
+          // content as its implicit value, which this pass can't compare
+          // against without re-deriving that text — bail rather than
+          // silently dropping this option out of the "no match" OR.
+          optionSetIsDynamic = true
+          continue
+        }
         if (optValue.value.kind === 'literal') {
-          n.attrs.push({ name: 'selected', value: selectedForLiteral(optValue.value.value), loc: n.loc })
+          const selected = selectedForLiteral(optValue.value.value)
+          n.attrs.push({ name: 'selected', value: selected, loc: n.loc })
+          matchConditions.push(selected)
         } else if (optValue.value.kind === 'expression') {
           const selected = selectedForExpr(optValue.value.expr, optValue.value.templateExpr)
           n.attrs.push({ name: 'selected', value: selected, loc: n.loc })
+          matchConditions.push(selected)
+        } else {
+          // A `value` shape neither builder above can compare (e.g. a
+          // structured `template` part) — same bail, not a silent drop.
+          optionSetIsDynamic = true
         }
-      } else if (
-        n.type === 'fragment' ||
-        n.type === 'loop' ||
-        (n.type === 'element' && n.tag === 'optgroup')
-      ) {
+      } else if (n.type === 'fragment' || (n.type === 'element' && n.tag === 'optgroup')) {
+        distribute(n.children)
+      } else if (n.type === 'loop') {
+        // A `.map()`-rendered option list still needs its per-row `selected`
+        // distributed (#2466, preserved below) — but its row count is
+        // unknown at compile time, so it can't feed the "no match" OR.
+        optionSetIsDynamic = true
         distribute(n.children)
+      } else {
+        // Conditionals/if-statements, components, slots — an option here
+        // may or may not exist at runtime, so the option set can't be
+        // exhaustively enumerated at compile time.
+        optionSetIsDynamic = true
       }
     }
   }
   distribute(children)
+
+  if (optionSetIsDynamic || matchConditions.length === 0) return
+  if (isMultiSelection(attrs)) return
+
+  const orExpr = matchConditions.map(c => `(${c.expr})`).join(' || ')
+  const orTemplateExpr = matchConditions.some(c => c.templateExpr !== undefined)
+    ? matchConditions.map(c => `(${c.templateExpr ?? c.expr})`).join(' || ')
+    : undefined
+
+  children.unshift({
+    type: 'element',
+    tag: 'option',
+    attrs: [
+      { name: 'value', value: AttrValueOf.literal(''), loc: valueAttr.loc },
+      { name: 'disabled', value: AttrValueOf.booleanAttr(), loc: valueAttr.loc },
+      { name: 'hidden', value: AttrValueOf.booleanAttr(), loc: valueAttr.loc },
+      {
+        name: 'selected',
+        value: AttrValueOf.expression(
+          `!(${orExpr})`,
+          orTemplateExpr !== undefined ? { templateExpr: `!(${orTemplateExpr})` } : undefined,
+        ),
+        loc: valueAttr.loc,
+      },
+    ],
+    events: [],
+    ref: null,
+    children: [],
+    slotId: null,
+    needsScope: false,
+    loc: valueAttr.loc,
+  })
+}
+
+/** `<select multiple>` or `size` > 1: a list box has no implicit default
+ *  selection, so SSR (no option `selected`) and hydration (`selectedIndex`
+ *  left at whatever it was) already agree without a placeholder option. */
+function isMultiSelection(attrs: IRAttribute[]): boolean {
+  if (attrs.some(a => a.name === 'multiple')) return true
+  const sizeAttr = attrs.find(a => a.name === 'size')
+  return sizeAttr?.value.kind === 'literal' && Number(sizeAttr.value.value) > 1
 }
 
 function transformHtmlElement(

package/src/prop-rewrite.ts

@@ -105,9 +105,14 @@ function isNonValuePosition(n: ts.Identifier, parent: ts.Node | undefined): bool
 /**
  * Walk an AST node for destructured-prop value references and add
  * each found name to `out`. Same skip rules as the rewrite path —
- * object-literal keys, shorthand properties, property-access names,
- * and names shadowed by a binding inside `node` are excluded so only
- * true value references get picked up. Exported for callers that need
+ * object-literal keys, property-access names, and names shadowed by a
+ * binding inside `node` are excluded so only true value references get
+ * picked up. A shorthand property (`{ page }`) IS a value reference —
+ * its name is simultaneously the key and the value, and
+ * `applyScopedPropRefRewrite` below already expands it correctly
+ * (`{ page }` → `{ page: _p.page }`) — so it must be discovered here
+ * too, or the rewrite is never even attempted for text whose only prop
+ * reference is a shorthand one (#2828). Exported for callers that need
  * the raw discovery set (e.g. the branch-local prop-dep cache from
  * #1425).
  */
@@ -118,7 +123,6 @@ export function collectAstPropRefs(
 ): void {
   walkWithScope(node, (n, parent, shadowed) => {
     if (shadowed || !propNames.has(n.text)) return
-    if (parent && ts.isShorthandPropertyAssignment(parent) && parent.name === n) return
     if (isNonValuePosition(n, parent)) return
     out.add(n.text)
   })

package/src/props-binding.ts

@@ -1,5 +1,5 @@
 import ts from 'typescript'
-import type { ParamInfo } from './types.ts'
+import type { ConstantInfo, ParamInfo } from './types.ts'
 
 /**
  * Authoritative IdentifierName classification for a destructure-pattern
@@ -69,6 +69,42 @@ export function buildPropAliasMap(params: readonly ParamInfo[]): Map<string, str
   return map
 }
 
+/**
+ * Local-name → caller-facing-key map for a BARE-PROPS-form component
+ * (`function Foo(props: Props)`) whose BODY destructures a prop under a
+ * different local name (`const { children: kids } = props`) — the
+ * body-level twin of `buildPropAliasMap` above, which only sees
+ * PARAMETER-destructuring aliases (`{ n: count }`, tracked via
+ * `ParamInfo.sourceName`). For the bare-props form, `propsParams` comes
+ * from the TYPE annotation (`extractPropsFromTypeMembers`) and has no
+ * notion of a body-level rename at all — but the analyzer already
+ * resolves such a destructuring statement into an ordinary
+ * `localConstants` entry whose `parsed` is a plain `props.<key>` member
+ * read (`const { children: kids } = props` → a `kids` local const valued
+ * `props.children`). Recognizing that shape here is enough to answer
+ * "what caller-facing prop key does this local alias" without a second,
+ * dedicated AST walk of the destructuring pattern itself (#2788).
+ *
+ * Returns an empty map for a parameter-destructuring component
+ * (`propsObjectName === null`) — that shape's aliasing is already fully
+ * covered by `buildPropAliasMap`.
+ */
+export function resolveBodyDestructuredPropAliases(
+  localConstants: readonly ConstantInfo[],
+  propsObjectName: string | null,
+): Map<string, string> {
+  const aliases = new Map<string, string>()
+  if (propsObjectName === null) return aliases
+  for (const c of localConstants) {
+    if (c.isModule) continue
+    const m = c.parsed
+    if (m?.kind === 'member' && !m.computed && m.object.kind === 'identifier' && m.object.name === propsObjectName) {
+      aliases.set(c.name, m.property)
+    }
+  }
+  return aliases
+}
+
 /**
  * The props-parameter shape needed to answer "is `name` an actual local
  * binding introduced by the props parameter" — as opposed to

package/src/ssr-defaults.ts

@@ -31,6 +31,8 @@
 
 import ts from 'typescript'
 import { extractFreeIdentifiersFromNode } from './analyzer.ts'
+import { resolveGetterAliases, collectAliasableGetterNames } from './ir-to-client-js/csr-substitute.ts'
+import { resolveBodyDestructuredPropAliases } from './props-binding.ts'
 import type { IRMetadata } from './types.ts'
 
 /**
@@ -311,6 +313,49 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
     bindings[memo.name] = value
   }
 
+  // #2813: a bare local-const alias of a signal/memo getter
+  // (`const items__alias = items`) is a DIFFERENT identifier from the
+  // getter it aliases, but a template-stash adapter's `.map()` loop over
+  // `items__alias()` looks up the stash entry BY THAT NAME — which the
+  // loops above never create, since they only seed the getter's own
+  // name. Reuses `resolveGetterAliases` (the same alias-hop walker
+  // #2778's CSR-template fix introduced) rather than a third alias-hop
+  // walker: every alias of a getter seeded above gets the SAME entry
+  // under its own name, so the stash has both `items` and `items__alias`
+  // pointing at one value. Env-signal getters are excluded from the
+  // getter-name set (they're never given an `out` entry above — an
+  // adapter's own env-signal binding seeds them instead).
+  {
+    const getterNames = collectAliasableGetterNames(metadata.signals, metadata.memos)
+    for (const [alias, origin] of resolveGetterAliases(metadata.localConstants ?? [], (n) => getterNames.has(n))) {
+      if (alias in out) continue
+      out[alias] = out[origin]
+    }
+  }
+
+  // #2788: a bare-props-form component (`function Foo(props: Props)`)
+  // whose BODY destructures a prop under a different local name
+  // (`const { children: kids } = props`) has no `ParamInfo.sourceName` to
+  // key off above — `propsParams` here comes from the TYPE annotation
+  // (`extractPropsFromTypeMembers`), which has no notion of a body-level
+  // rename. `resolveBodyDestructuredPropAliases` recognizes such a
+  // destructuring statement's `localConstants` shape; seeding the LOCAL
+  // name too (alongside the caller-facing key already seeded above) is
+  // enough to fix what a template-stash adapter's compiled output
+  // actually reads (`v[:kids]` / `$kids`). Without this, a stash-based
+  // adapter reading the renamed local sees an undefined/nil value instead
+  // of the prop — fatal under Perl strict mode (Mojolicious), a
+  // nonexistent Go struct field, or (on an adapter whose runtime
+  // tolerates a missing key) a silent wrong render the moment a caller
+  // actually supplies a value. Parameter-destructuring aliases (`{ n:
+  // count }`) need no such entry — `sourceName`/`name` already handle
+  // that shape via `callerPropName` above.
+  for (const [local, callerKey] of resolveBodyDestructuredPropAliases(metadata.localConstants ?? [], metadata.propsObjectName)) {
+    if (local in out) continue
+    const origin = out[callerKey]
+    if (origin) out[local] = origin
+  }
+
   // Bare-props-arg safety net: the prop block above covers every prop
   // *declared* on the props type, but `propsParams` can miss props read
   // through an untyped / inline-typed `props` object. A signal / memo