@barefootjs/go-template 0.16.0 → 0.17.1

package/src/adapter/lib/compile-state.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-compile mutable state for the Go html/template adapter. The adapter is a
+ * reused singleton; everything established (and reset) per `generate()` /
+ * `generateTypes()` run lives here. The adapter holds a single `CompileState`
+ * and resets its members at the start of each compile.
+ *
+ * NOT included (deliberately): cross-compile child-shape registries
+ * (`childComponentShapes`, `childContextConsumers`, populated before a parent
+ * compiles), the render-recursion cursor stacks (`loopParamStack`,
+ * `filterExprDepth`, …), and constant config (`options`, `templatePrimitives`).
+ */
+
+import type {
+  CompilerError,
+  ContextConsumer,
+  EnvSignalReader,
+  IRMetadata,
+  IRNode,
+  LoweringMatcher,
+  MemoInfo,
+  SsrSeedPlan,
+  TypeDefinition,
+  TypeInfo,
+} from '@barefootjs/jsx'
+
+export class CompileState {
+  // --- Reset at the start of `generate()` -----------------------------------
+
+  componentName: string = ''
+  errors: CompilerError[] = []
+
+  /** Component-scope derived consts referenced by the template during rendering
+   *  (e.g. `root` → `.Root`). `generateTypes` emits a computed field for each
+   *  that's resolvable and non-colliding. */
+  referencedDerivedConsts: Set<string> = new Set()
+
+  templateVarCounter: number = 0
+
+  /**
+   * Companion `{{define "<Component>__children_<slot>"}}` blocks queued while
+   * rendering the template body. Flushed after the main define in `generate()`.
+   */
+  pendingChildrenDefines: Array<{ name: string; content: string }> = []
+
+  propsObjectName: string | null = null
+
+  /**
+   * Component-scoped rest binding identifier (`function({ a, ...rest }: P)`
+   * → `'rest'`). Stashed at `generate()` entry so per-attribute emitter
+   * callbacks can classify a spread expression against it.
+   */
+  restPropsName: string | null = null
+
+  /**
+   * Module-scope pure string-literal constants (`const X = 'literal'` at
+   * file top-level), keyed by name → resolved literal value. When an identifier
+   * resolves to one of these, the adapter inlines the literal value instead of
+   * emitting a struct-field reference.
+   */
+  moduleStringConsts: Map<string, string> = new Map()
+
+  /**
+   * All local constants (module + function-scope) from the IR, retained for
+   * the lifetime of `generate()` so the memo-computation path can resolve
+   * `Record`-index lookups without re-threading the full `ir` through helpers.
+   */
+  localConstants: IRMetadata['localConstants'] = []
+
+  /**
+   * Names of component-scope arrow-const helpers (`const sortClass = …`),
+   * eligible for call-site inlining.
+   */
+  localHelperNames: Set<string> = new Set()
+
+  /** The current IR's memos, stashed like `localConstants` so nested memo
+   *  resolution can recurse without threading the list through every signature.
+   *  Full `MemoInfo` so consumers can read the analyzer-attached `parsed` tree. */
+  currentMemos: MemoInfo[] = []
+
+  /** Full type definitions from the current IR, stashed for loop-datum field resolution. */
+  currentTypeDefinitions: TypeDefinition[] = []
+
+  /**
+   * `useContext(...)` consumers in the component being generated. Each becomes
+   * a struct field defaulted to the `createContext` default.
+   */
+  contextConsumers: ContextConsumer[] = []
+
+  /**
+   * Local binding names the request-scoped `searchParams()` env signal is
+   * imported under (handles `import { searchParams as sp }`).
+   */
+  searchParamsLocals: Set<string> = new Set()
+
+  /**
+   * Env-signal getter (local binding name, e.g. `searchParams` or an alias) →
+   * its registered {@link EnvSignalReader}, keyed by the RECEIVER signal's own
+   * `envReader` registration rather than a hardcoded key — so a memo body's
+   * `<local>().<method>(...)` resolves to whichever reader that particular
+   * local belongs to (open-closed for a future second env signal).
+   */
+  envSignalReadersByLocal: Map<string, EnvSignalReader> = new Map()
+
+  /**
+   * The backend-neutral SSR seed plan (`computeSsrSeedPlan`, Package G) for
+   * the IR currently being compiled — single authority for which signal/memo
+   * getters are value-materializable at SSR time (`env-reader` steps are
+   * per-request readers; everything else is `derived`/`opaque`). Populated in
+   * `primeCompileState`; `envSignalReadersByLocal` and `searchParamsLocals`
+   * derive from it there, and the memo-analysis path in `memo-compute.ts`
+   * reads its `steps` directly instead of re-deriving from `metadata`.
+   */
+  ssrSeedPlan: SsrSeedPlan = { baseScope: [], steps: [] }
+
+  /**
+   * Memo name → the hoisted Go local variable name the constructor assigned
+   * its SSR value to (populated by the sibling-memo hoisting pre-pass before
+   * the main memo-field loop runs). When a later filter-arm memo's free-var
+   * resolution finds an entry here, it reuses the local instead of
+   * recomputing the sibling's expression a second time.
+   */
+  hoistedMemoLocals: Map<string, string> = new Map()
+
+  /**
+   * Call-lowering matchers active for this component (#2057), bound to its
+   * metadata at init via `prepareLoweringMatchers`. Each maps a recognised call
+   * to a backend-neutral `LoweringNode` the adapter renders. Covers both userland
+   * plugins and the compiler's built-in plugins (e.g. `queryHref` → `bf_query`,
+   * #2042), so there is no separate per-API recognition path.
+   */
+  loweringMatchers: LoweringMatcher[] = []
+
+  /**
+   * Prop NAMES whose resolved Go struct-field type is exactly `interface{}`
+   * — i.e. nillable. Used by the attribute emitter to omit a dynamic attribute
+   * whose value is a bare reference to such a prop when it's nil.
+   */
+  nillablePropNames: Set<string> = new Set()
+
+  /** Component root scope element(s) — each carries `data-key` for a keyed loop
+   *  item. */
+  rootScopeNodes: Set<IRNode> = new Set()
+
+  /** Array-memo name → the handler-filled loop slice field its `.map()` feeds
+   *  (e.g. `visible` → `PostListItems`). Lets `<memo>().length` lower to the
+   *  slice's length instead of a nil/unset memo field. */
+  memoBackedLoopSlice: Map<string, string> = new Map()
+
+  // --- Reset at the start of `generateTypes()` ------------------------------
+
+  /** Set during type generation when any emit references
+   *  `template.HTML(...)`; toggles the `"html/template"` import. */
+  usesHtmlTemplate: boolean = false
+
+  /** Set during type generation when any emit references `fmt.Sprint(...)`;
+   *  toggles the `"fmt"` import. */
+  usesFmt: boolean = false
+
+  /** Local type names resolved from typeDefinitions (populated during generateTypes). */
+  localTypeNames: Set<string> = new Set()
+
+  /** Local type aliases mapping type name to base type (e.g., Filter → 'string'). */
+  localTypeAliases: Map<string, string> = new Map()
+
+  /**
+   * Per-struct field map (type name → source TS key → Go field name), populated
+   * during generateTypes. The object-literal baker consults this so a baked
+   * struct literal only names fields the generated struct actually declares.
+   */
+  localStructFields: Map<string, Map<string, string>> = new Map()
+
+  /**
+   * Synthesised array types for untyped object-array signals (signal getter →
+   * `[]SynthStruct` TypeInfo), populated during generateTypes.
+   */
+  synthStructTypes: Map<string, TypeInfo> = new Map()
+
+  /** Set when a constructor-context lowering emits a `strings.` call, so
+   *  `strings` is added to the generated types file's import block. */
+  needsStringsImport = false
+}

package/src/adapter/lib/constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Compile-time constant tables for the Go html/template adapter.
+ */
+
+import type { PrimitiveSpec } from "./types.ts"
+import { wrapGoArg } from "./go-emit.ts"
+
+/**
+ * Single source of truth for the Go adapter's template-primitive surface. Each
+ * entry pairs the expected arity with the emit function so the two derived maps
+ * (`templatePrimitives` and `templatePrimitiveArities`) can't drift out of sync.
+ */
+export const GO_TEMPLATE_PRIMITIVES: Record<string, PrimitiveSpec> = {
+  'JSON.stringify': { arity: 1, emit: (args) => `bf_json ${wrapGoArg(args[0])}` },
+  'String':         { arity: 1, emit: (args) => `bf_string ${wrapGoArg(args[0])}` },
+  'Number':         { arity: 1, emit: (args) => `bf_number ${wrapGoArg(args[0])}` },
+  'Math.floor':     { arity: 1, emit: (args) => `bf_floor ${wrapGoArg(args[0])}` },
+  'Math.ceil':      { arity: 1, emit: (args) => `bf_ceil ${wrapGoArg(args[0])}` },
+  'Math.round':     { arity: 1, emit: (args) => `bf_round ${wrapGoArg(args[0])}` },
+  // Two-arg forms only; an N-arg `Math.min(a, b, c)` falls through to the
+  // standard BF101 unsupported-call diagnostic via the arity gate.
+  'Math.min':       { arity: 2, emit: (args) => `bf_min ${wrapGoArg(args[0])} ${wrapGoArg(args[1])}` },
+  'Math.max':       { arity: 2, emit: (args) => `bf_max ${wrapGoArg(args[0])} ${wrapGoArg(args[1])}` },
+}

package/src/adapter/lib/go-emit.ts

@@ -0,0 +1,309 @@
+/**
+ * Go html/template emit helpers: string escaping, argument wrapping, `bf_*`
+ * runtime-helper call construction, and JSX-literal → Go-literal lowering.
+ * Pure free functions — none read adapter instance state.
+ */
+
+import type { SortComparator, SupportResult, ParsedExpr } from '@barefootjs/jsx'
+import { serializeParsedExpr, freeVarsInBody } from '@barefootjs/jsx'
+
+import { capitalize } from "./go-naming.ts"
+
+/** Escape a value for embedding in a Go-template double-quoted string. */
+export function escapeGoString(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+/**
+ * Wrap a rendered Go template fragment in parens when it would otherwise parse
+ * as multiple sibling args of an enclosing prefix call. A bare identifier /
+ * dotted path / quoted literal stays uncluttered; anything containing
+ * whitespace (a call, `len ...`) gets `(...)` so `bf_join (...) bf_trim .Raw`
+ * doesn't degrade to four args of `bf_join`.
+ */
+export function wrapIfMultiToken(rendered: string): string {
+  if (rendered.startsWith('(') && rendered.endsWith(')')) return rendered
+  // Quoted literals may contain spaces but parse as one token — leave alone.
+  if (rendered.startsWith('"') && rendered.endsWith('"')) return rendered
+  if (/\s/.test(rendered)) return `(${rendered})`
+  return rendered
+}
+
+/**
+ * Parenthesize a compound Go template argument (`or .Checked false`) so a
+ * primitive call reads it as ONE argument — unwrapped, the parser splits it
+ * into three and `bf_string` fails with "want 1 got 3".
+ */
+export function wrapGoArg(arg: string): string {
+  if (!/\s/.test(arg)) return arg
+  if (arg.startsWith('(') && arg.endsWith(')')) return arg
+  return `(${arg})`
+}
+
+/**
+ * Emit the `bf_sort` call:
+ *
+ *   bf_sort <recv> (<keyKind> <keyName> <compareType> <direction>)+
+ *
+ *   keyKind:      "self" | "field"
+ *   keyName:      "" when keyKind=self; capitalised field name otherwise
+ *   compareType:  "numeric" | "string" | "auto"
+ *   direction:    "asc" | "desc"
+ *
+ * The 4-string group repeats once per comparison key: a simple comparator emits
+ * one group; a `||`-chained multi-key comparator emits one per operand, applied
+ * in order as tie-breakers by the variadic `bf_sort` runtime. Capitalisation
+ * mirrors the Go struct-field convention so the runtime's reflect lookup
+ * matches without a recapitalise step.
+ */
+export function emitBfSort(recv: string, c: SortComparator): string {
+  const groups = c.keys.map((k) => {
+    const keyName = k.key.kind === 'field' ? capitalize(k.key.field) : ''
+    return `"${k.key.kind}" "${keyName}" "${k.type}" "${k.direction}"`
+  })
+  return `bf_sort ${wrapIfMultiToken(recv)} ${groups.join(' ')}`
+}
+
+/**
+ * Build the `bf_env` base_env argument for a callback body: one `"name" <value>`
+ * pair per captured free variable (a body identifier that isn't a callback
+ * param), each lowered to its Go template value via `emit`. No captures →
+ * the bare `bf_env` (an empty env).
+ */
+function emitEvalEnvArg(body: ParsedExpr, params: string[], emit: (e: ParsedExpr) => string): string {
+  const free = freeVarsInBody(body, new Set(params))
+  if (free.length === 0) return 'bf_env'
+  const pairs = free.map(
+    n => `"${escapeGoString(n)}" ${wrapIfMultiToken(emit({ kind: 'identifier', name: n }))}`,
+  )
+  return `(bf_env ${pairs.join(' ')})`
+}
+
+/**
+ * Emit a `.sort(cmp)` via the evaluator (#2018): the comparator body travels as
+ * serialized-ParsedExpr JSON, evaluated per comparison against `{paramA, paramB,
+ * …captured}`. Returns null when the comparator can't be evaluated (e.g. a
+ * `localeCompare` body — `serializeParsedExpr` refuses it), so the caller falls
+ * back to the structured `bf_sort`. A `||`-chained multi-key comparator needs no
+ * special handling — JS `0 || next` is exactly the tie-break semantics.
+ */
+export function emitSortEval(
+  recv: string,
+  body: ParsedExpr,
+  params: string[],
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  // A comparator needs both params; a wrong-arity arrow would bind the wrong
+  // env (or treat a real param as a free var), so fail over to the structured
+  // fallback / BF101 instead of inventing default names.
+  if (params.length < 2) return null
+  const paramA = params[0]
+  const paramB = params[1]
+  const env = emitEvalEnvArg(body, [paramA, paramB], emit)
+  return `bf_sort_eval ${wrapIfMultiToken(recv)} "${escapeGoString(json)}" "${paramA}" "${paramB}" ${env}`
+}
+
+/**
+ * Emit a `.reduce(fn, init)` via the evaluator (#2018): the reducer body travels
+ * as serialized-ParsedExpr JSON, folded over the receiver from `init`. Returns
+ * null when the body can't be evaluated, or when `init` isn't a string/number
+ * literal (a non-literal seed has no template-time value). A numeric seed is
+ * passed through `bf_number` (handles any decimal incl. negative / float); a
+ * string seed as a quoted string.
+ */
+export function emitReduceEval(
+  recv: string,
+  body: ParsedExpr,
+  params: string[],
+  init: ParsedExpr,
+  direction: 'left' | 'right',
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  // A reducer needs both the accumulator and the element param; a wrong-arity
+  // arrow would bind the wrong env, so refuse cleanly (→ BF101) rather than
+  // defaulting the names.
+  if (params.length < 2) return null
+  const paramAcc = params[0]
+  const paramItem = params[1]
+  // Only a literal seed has a template-time value; anything else (an identifier
+  // / call) can't be folded here, so bail to the structured-less fallback (BF101).
+  let initGo: string
+  if (init.kind === 'literal' && init.literalType === 'string') {
+    initGo = `"${escapeGoString(String(init.value))}"`
+  } else if (init.kind === 'literal' && init.literalType === 'number') {
+    initGo = `(bf_number "${escapeGoString(init.raw ?? String(init.value))}")`
+  } else {
+    return null
+  }
+  const env = emitEvalEnvArg(body, [paramAcc, paramItem], emit)
+  return `bf_reduce_eval ${wrapIfMultiToken(recv)} "${escapeGoString(json)}" "${paramAcc}" "${paramItem}" ${initGo} "${direction}" ${env}`
+}
+
+/**
+ * Emit a higher-order predicate call via the evaluator (#2018, P2): the
+ * predicate body (already a `ParsedExpr` on the `higher-order` IR node) travels
+ * as serialized-ParsedExpr JSON, evaluated per element against `{param,
+ * …captured}`. Generalizes the field-equality / truthiness catalogues of
+ * `bf_filter` / `bf_find` / `bf_every` / `bf_some` to any pure predicate body.
+ * Returns null when the predicate is outside the evaluator surface (e.g. a
+ * method-call predicate — `serializeParsedExpr` refuses it), so the caller
+ * falls back to the structured helper / template-block path.
+ *
+ *   <func> <recv> "<json>" "<param>" [<extraArgs>…] <env>
+ *
+ * `extraArgs` are inserted between the param name and the env — used for the
+ * find / findIndex `forward` bool (`true` = find / findIndex, `false` =
+ * findLast / findLastIndex).
+ */
+export function emitPredicateEval(
+  funcName: string,
+  recv: string,
+  predicate: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+  extraArgs: string[] = [],
+): string | null {
+  const json = serializeParsedExpr(predicate)
+  if (json === null) return null
+  const env = emitEvalEnvArg(predicate, [param], emit)
+  const extra = extraArgs.length > 0 ? ` ${extraArgs.join(' ')}` : ''
+  return `${funcName} ${wrapIfMultiToken(recv)} "${escapeGoString(json)}" "${param}"${extra} ${env}`
+}
+
+/**
+ * Emit a `.flatMap(proj)` via the evaluator (#2018, P3): the projection body
+ * (e.g. `i.tags` / `[i.a, i.b]`) is serialized and evaluated per element by
+ * `bf_flat_map_eval`, which flattens the results one level. Returns null when
+ * the projection is outside the evaluator surface (→ caller pushes BF101).
+ */
+export function emitFlatMapEval(
+  recv: string,
+  body: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  const env = emitEvalEnvArg(body, [param], emit)
+  return `bf_flat_map_eval ${wrapIfMultiToken(recv)} "${escapeGoString(json)}" "${param}" ${env}`
+}
+
+/**
+ * Emit a value-producing `.map(cb)` via the evaluator (#2073): the projection
+ * body is serialized and evaluated per element by `bf_map_eval`, one result
+ * per element (no flatten — the JS `.map` contract). Composes through the
+ * array-method chain (`bf_join (bf_map_eval …) " "`). Returns null when the
+ * projection is outside the evaluator surface (→ caller pushes BF101). The
+ * JSX-returning `.map` is an IRLoop upstream and never reaches this emit.
+ */
+export function emitMapEval(
+  recv: string,
+  body: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  const env = emitEvalEnvArg(body, [param], emit)
+  return `bf_map_eval ${wrapIfMultiToken(recv)} "${escapeGoString(json)}" "${param}" ${env}`
+}
+
+/**
+ * Make an equality comparison string-tolerant when exactly one side is a Go
+ * string literal: JS `sorted === 'asc'` is loosely false for `sorted = false`,
+ * but Go's template `eq` ERRORS on bool-vs-string (`incompatible types for
+ * comparison`). Routing the non-literal side through `bf_string` preserves JS
+ * comparison semantics for every concrete type while leaving same-kind
+ * comparisons untouched.
+ */
+export function stringTolerantEqOperands(l: string, r: string): [string, string] {
+  const isStrLit = (x: string) => /^"(?:[^"\\]|\\.)*"$/.test(x)
+  if (isStrLit(l) === isStrLit(r)) return [l, r]
+  // Keep `wrapGoArg`'s parens: a compound operand must reach `bf_string` as ONE
+  // argument — `(bf_string (or .Placement "top"))`, not `(bf_string or …)`.
+  const wrap = (x: string) => (isStrLit(x) ? x : `(bf_string ${wrapGoArg(x)})`)
+  return [wrap(l), wrap(r)]
+}
+
+// Generic remediation appended to BF101 / BF102 diagnostics whose reason
+// doesn't already carry actionable next steps.
+export const GO_REMEDIATION_OPTIONS =
+  'Options:\n1. Use @client directive for client-side evaluation\n2. Pre-compute the value in Go code'
+
+// Build the `suggestion.message` for an unsupported expression/condition.
+// A self-contained reason (it already spells out the fix — e.g. the
+// pre-compute / @client hint or the tailored forEach message) is shown
+// as-is; a low-level reason gets the generic options appended; with no
+// reason at all we fall back to the options alone.
+export function buildUnsupportedSuggestion(support: SupportResult): string {
+  if (!support.reason) return GO_REMEDIATION_OPTIONS
+  if (support.selfContained) return support.reason
+  return `${support.reason}\n\n${GO_REMEDIATION_OPTIONS}`
+}
+
+/**
+ * Translate a JSX param default (e.g. `'default'`, `0`, `false`) into the
+ * corresponding Go literal.
+ *
+ * @returns the Go literal, or `null` when the default is absent or non-trivial
+ *   (objects, arrow functions, …) — caller then lets Go's zero value win.
+ */
+export function goPropDefault(defaultValue: string | undefined): string | null {
+  if (!defaultValue) return null
+  const trimmed = defaultValue.trim()
+  if (trimmed === '') return null
+  if (trimmed === 'true' || trimmed === 'false') return trimmed
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed
+  if (
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+  ) {
+    const body = trimmed.slice(1, -1)
+    return JSON.stringify(body)
+  }
+  // Anything richer (objects, arrays, expressions) would mis-execute as Go.
+  return null
+}
+
+/**
+ * Wrap an `in.X` reference in a Go expression that substitutes `fallback` when
+ * the input is the zero value for its type; the comparison is picked from the
+ * fallback literal's shape.
+ *
+ * Asymmetry on bool/zero defaults is intentional (Go has no
+ * unset-vs-explicit-false distinction at the struct-field level):
+ *   - `true` default → `(in.X || true)`, which is ALWAYS `true`; a caller
+ *     wanting `false` must set it after `NewXxxProps`, not via the input struct.
+ *   - `false` / `0` default → matches the Go zero value, so this is a no-op
+ *     (returns `ref` unchanged).
+ * Non-zero numeric defaults substitute, matching JSX `(initial = 5) => …`.
+ */
+export function applyGoFallback(ref: string, fallback: string): string {
+  if (fallback === 'true' || fallback === 'false') {
+    return fallback === 'true' ? `(${ref} || true)` : ref
+  }
+  if (/^-?\d+(\.\d+)?$/.test(fallback)) {
+    if (fallback === '0') return ref
+    return `func() int { if ${ref} == 0 { return ${fallback} }; return ${ref} }()`
+  }
+  // String fallback (quoted).
+  return `func() string { if ${ref} == "" { return ${fallback} }; return ${ref} }()`
+}
+
+/** Convert a JavaScript literal value to Go literal syntax. */
+export function goLiteral(value: string): string {
+  if (value === 'true' || value === 'false') return value
+  if (/^-?\d+(\.\d+)?$/.test(value)) return value
+  // Single-quoted → Go double quotes; double-quoted kept as-is.
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return `"${value.slice(1, -1)}"`
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value
+  }
+  return `"${value}"`
+}

package/src/adapter/lib/go-naming.ts

@@ -0,0 +1,84 @@
+/**
+ * Go identifier / field-name conventions: the single source of truth for
+ * capitalisation, initialism handling, and slot/loop-key → Go field-path
+ * lowering. Pure helpers — none read adapter instance state.
+ */
+
+/** Matches a bare Go identifier (no dots, no brackets). */
+export const GO_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Go common initialisms that should be fully uppercased (https://go.dev/wiki/CodeReviewComments#initialisms) */
+export const GO_INITIALISMS = new Set([
+  'id', 'url', 'http', 'https', 'api', 'json', 'xml', 'html', 'css', 'sql',
+  'ip', 'tcp', 'udp', 'dns', 'ssh', 'tls', 'ssl', 'uri', 'uid', 'uuid',
+  'ascii', 'utf8', 'eof', 'grpc', 'rpc', 'cpu', 'gpu', 'ram', 'os',
+])
+
+/**
+ * Go reserved keywords. When hoisting a local var named after a JSX prop, a
+ * collision with one of these is resolved by appending `_` until free.
+ */
+export const GO_KEYWORDS = new Set([
+  'break', 'case', 'chan', 'const', 'continue', 'default', 'defer',
+  'else', 'fallthrough', 'for', 'func', 'go', 'goto', 'if', 'import',
+  'interface', 'map', 'package', 'range', 'return', 'select', 'struct',
+  'switch', 'type', 'var',
+])
+
+/**
+ * Capitalise a name for use as a Go template field projection. A whole-word
+ * Go initialism uppercases entirely (`id` → `ID`, `url` → `URL`) so the
+ * `bf_sort` / `bf_reduce` reflect lookup resolves the generated exported
+ * field instead of silently folding a zero value.
+ */
+export function capitalize(s: string): string {
+  if (s.length === 0) return s
+  if (GO_INITIALISMS.has(s.toLowerCase())) {
+    return s.toUpperCase()
+  }
+  return s[0].toUpperCase() + s.slice(1)
+}
+
+/** Capitalise a JSX prop / field name to its exported Go struct field name. */
+export function capitalizeFieldName(name: string): string {
+  if (!name) return name
+  // Whole-name initialism (e.g. 'id' → 'ID').
+  if (GO_INITIALISMS.has(name.toLowerCase())) {
+    return name.toUpperCase()
+  }
+  return name.charAt(0).toUpperCase() + name.slice(1)
+}
+
+/**
+ * Convert a slot ID (e.g., 's6') to a Go struct field suffix (e.g., 'Slot6').
+ * Keeps field names human-readable regardless of the internal slot ID format.
+ */
+export function slotIdToFieldSuffix(slotId: string): string {
+  // Strip the parent-owned prefix (^).
+  const cleanId = slotId.startsWith('^') ? slotId.slice(1) : slotId
+  const match = cleanId.match(/^s(\d+)$/)
+  if (match) {
+    return `Slot${match[1]}`
+  }
+  // Fallback for non-standard IDs.
+  return cleanId.replace('slot_', 'Slot')
+}
+
+/**
+ * Lower a keyed-loop `key` expression to the Go field path on the loop's range
+ * variable (always `item` in the generated `for i, item := range …`), e.g.
+ * `item.label` → `item.Label`.
+ *
+ * @returns `null` for a non-simple key (computed expression, whole-element key,
+ *   mismatched param) — caller then skips `data-key` rather than emit
+ *   something that won't compile.
+ */
+export function loopKeyToGoFieldPath(key: string | undefined, param: string | undefined): string | null {
+  if (!key || !param) return null
+  const segs = key.split('.')
+  if (segs[0] !== param) return null
+  const rest = segs.slice(1)
+  if (rest.length === 0) return null
+  if (!rest.every(s => /^[A-Za-z_]\w*$/.test(s))) return null
+  return 'item.' + rest.map(capitalize).join('.')
+}

package/src/adapter/lib/ir-scope.ts

@@ -0,0 +1,31 @@
+/**
+ * IR traversal helpers for the Go html/template adapter. Pure functions over
+ * the IR tree — no adapter instance state.
+ */
+
+import type { IRNode, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/**
+ * Collect the component's root scope element node(s) — the elements that become
+ * the rendered root and so carry `data-key` for a keyed loop item. A plain
+ * element root is itself; an `if-statement` (early-return) root contributes the
+ * top element of each branch, since exactly one renders at runtime.
+ */
+export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
+  const out = new Set<IRNode>()
+  const visit = (n: IRNode | null): void => {
+    if (!n) return
+    if (n.type === 'element') { out.add(n); return }
+    if (n.type === 'if-statement') {
+      const s = n as IRIfStatement
+      visit(s.consequent)
+      visit(s.alternate)
+      return
+    }
+    if (n.type === 'fragment') {
+      for (const c of (n as IRFragment).children) visit(c)
+    }
+  }
+  visit(node)
+  return out
+}