@barefootjs/go-template 0.31.10 → 0.32.0

package/dist/vite.js

@@ -7777,7 +7777,18 @@ function collectNullishConsumedPropNames(ctx, ir) {
   };
   walk(ir.root);
   for (const signal of ir.metadata.signals) {
-    const match = ctx.extractPropFallback(signal.initialValue, resolveSignalParsedThroughSeedPlan(ctx.state, signal));
+    const resolvedParsed = resolveSignalParsedThroughSeedPlan(ctx.state, signal);
+    let match = ctx.extractPropFallback(signal.initialValue, resolvedParsed);
+    if (!match) {
+      const collision = ctx.extractCollisionDerivation(resolvedParsed);
+      if (collision) {
+        const collisionParam = ir.metadata.propsParams.find((p) => p.name === collision.propName);
+        const collisionField = collisionParam ? capitalizeFieldName(collisionParam.sourceName ?? collision.propName) : null;
+        if (collisionField && capitalizeFieldName(signal.getter) === collisionField) {
+          match = { propName: collision.propName, goFallback: collision.goFallback };
+        }
+      }
+    }
     if (!match || !optionalParams.has(match.propName))
       continue;
     const f = match.goFallback;
@@ -7962,6 +7973,7 @@ class GoTemplateAdapter extends BaseAdapter {
     convertConditionToGo: (jsCondition, preParsed) => this.convertConditionToGo(jsCondition, preParsed),
     extractPropNameFromInitialValue: (initialValue, preParsed) => this.extractPropNameFromInitialValue(initialValue, preParsed),
     extractPropFallback: (initialValue, preParsed) => this.extractPropFallback(initialValue, preParsed),
+    extractCollisionDerivation: (parsed) => this.extractCollisionDerivation(parsed),
     resolveModuleStringConst: (name) => this.resolveModuleStringConst(name)
   };
   get errors() {
@@ -8740,6 +8752,7 @@ ${goFields.join(`
       }
       lines.push("");
     }
+    this.emitCallerPropsInit(lines, ir, nestedComponents, staticWithoutBody, staticWithBody, dynamicWithBody, emittedWrapperVars, propTypeOverrides);
     lines.push(`	return ${propsTypeName}{`);
     lines.push("\t\tScopeID: scopeID,");
     lines.push("\t\tBfParent: in.BfParent,");
@@ -8747,6 +8760,7 @@ ${goFields.join(`
     if (this.usesSearchParams(ir)) {
       lines.push("\t\tSearchParams: in.SearchParams,");
     }
+    lines.push("\t\tBfCallerProps: bfCallerProps,");
     const nestedArrayFields = this.propDerivedNestedArrayFields(nestedComponents);
     const memoFallbacks = new Map;
     for (const memo of ir.metadata.memos) {
@@ -8772,7 +8786,8 @@ ${goFields.join(`
         continue;
       const hoisted = propFallbackVars.get(param.name);
       if (hoisted) {
-        lines.push(`		${fieldName}: ${hoisted.varName},`);
+        const value = hoisted.collisionWrap ? `${hoisted.varName} ${hoisted.collisionWrap.operator} ${hoisted.collisionWrap.operand}` : hoisted.varName;
+        lines.push(`		${fieldName}: ${value},`);
       } else {
         const paramDefault = goPropDefault(param.defaultValue);
         const memoFold = memoFallbacks.get(fieldName);
@@ -8851,6 +8866,53 @@ ${goFields.join(`
     lines.push("\t}");
     lines.push("}");
   }
+  emitCallerPropsInit(lines, ir, nestedComponents, staticWithoutBody, staticWithBody, dynamicWithBody, emittedWrapperVars, propTypeOverrides) {
+    lines.push("\tbfCallerProps := map[string]interface{}{}");
+    const bfCallerPropsTakenTags = new Set;
+    const nestedArrayFields = this.propDerivedNestedArrayFields(nestedComponents);
+    for (const param of ir.metadata.propsParams) {
+      if (param.name === "children")
+        continue;
+      if (this.isNestedArrayShadowed(param, nestedArrayFields))
+        continue;
+      const callerKey = this.claimJsonTag(this.toJsonTag(param.sourceName ?? param.name), bfCallerPropsTakenTags);
+      if (callerKey === "-")
+        continue;
+      const inputField = `in.${capitalizeFieldName(param.sourceName ?? param.name)}`;
+      const goType = resolvePropGoType(this.emitCtx, param, propTypeOverrides);
+      const isNillable = goType === "interface{}" || goType === "map[string]interface{}" || goType.startsWith("[]");
+      if (param.optional && isNillable) {
+        lines.push(`	if ${inputField} != nil {`);
+        lines.push(`		bfCallerProps["${callerKey}"] = ${inputField}`);
+        lines.push(`	}`);
+      } else {
+        lines.push(`	bfCallerProps["${callerKey}"] = ${inputField}`);
+      }
+    }
+    for (const nested of [...staticWithoutBody, ...staticWithBody, ...dynamicWithBody]) {
+      if (!nested.isPropDerived)
+        continue;
+      const varName = `${nested.name.charAt(0).toLowerCase()}${nested.name.slice(1)}s`;
+      const isBuilt = staticWithoutBody.includes(nested) || emittedWrapperVars.has(varName);
+      if (!isBuilt)
+        continue;
+      const arrayFieldName = capitalizeFieldName(`${nested.name}s`);
+      const param = ir.metadata.propsParams.find((p) => capitalizeFieldName(p.name) === arrayFieldName || capitalizeFieldName(p.sourceName ?? p.name) === arrayFieldName);
+      if (!param || !this.isNestedArrayShadowed(param, nestedArrayFields))
+        continue;
+      const callerKey = this.claimJsonTag(this.toJsonTag(param.sourceName ?? param.name), bfCallerPropsTakenTags);
+      if (callerKey === "-")
+        continue;
+      if (param.optional) {
+        lines.push(`	if in.${nested.name}s != nil {`);
+        lines.push(`		bfCallerProps["${callerKey}"] = ${varName}`);
+        lines.push(`	}`);
+      } else {
+        lines.push(`	bfCallerProps["${callerKey}"] = ${varName}`);
+      }
+    }
+    lines.push("");
+  }
   emitStaticChildInstances(lines, ir) {
     const staticChildren = this.collectStaticChildInstances(ir.root, ir.metadata.propsParams);
     for (const child of staticChildren) {
@@ -9302,6 +9364,7 @@ ${goFields.join(`
     if (this.usesSearchParams(ir)) {
       lines.push('\tSearchParams bf.SearchParams `json:"-"`');
     }
+    lines.push('\tBfCallerProps map[string]interface{} `json:"-"`');
   }
   emitPropsDataFields(lines, ir, nestedComponents, propTypeOverrides, takenJsonTags) {
     const nestedArrayFields = this.propDerivedNestedArrayFields(nestedComponents);
@@ -9713,7 +9776,19 @@ ${goFields.join(`
     }
     const propTypeOverrides = buildPropTypeOverrides(this.emitCtx, ir);
     for (const signal of ir.metadata.signals) {
-      const match = this.extractPropFallback(signal.initialValue, this.resolvedSignalParsed(signal));
+      let match = this.extractPropFallback(signal.initialValue, this.resolvedSignalParsed(signal));
+      let collisionWrap;
+      if (!match) {
+        const collision = this.extractCollisionDerivation(this.resolvedSignalParsed(signal));
+        if (collision) {
+          const collisionParam = ir.metadata.propsParams.find((p) => p.name === collision.propName);
+          const collisionField = collisionParam ? capitalizeFieldName(collisionParam.sourceName ?? collision.propName) : null;
+          if (collisionField && capitalizeFieldName(signal.getter) === collisionField) {
+            match = { propName: collision.propName, goFallback: collision.goFallback };
+            collisionWrap = { operator: collision.operator, operand: collision.operand };
+          }
+        }
+      }
       if (!match)
         continue;
       if (result.has(match.propName))
@@ -9752,7 +9827,8 @@ ${goFields.join(`
         fieldName,
         goFallback: match.goFallback,
         zeroLiteral,
-        ...nullishLowered ? { assertType: concreteType } : {}
+        ...nullishLowered ? { assertType: concreteType } : {},
+        ...collisionWrap ? { collisionWrap } : {}
       });
     }
     return result;
@@ -9802,6 +9878,26 @@ ${goFields.join(`
       return null;
     return { propName, goFallback };
   }
+  extractCollisionDerivation(parsed) {
+    if (!parsed || parsed.kind !== "binary")
+      return null;
+    if (!["*", "+", "-", "/"].includes(parsed.op))
+      return null;
+    const { right } = parsed;
+    if (right.kind !== "literal" || right.literalType !== "number" || typeof right.value !== "number" || !Number.isInteger(right.value) || right.value < 0) {
+      return null;
+    }
+    if (parsed.op === "/" && right.value === 0)
+      return null;
+    const coalesce = parsed.left;
+    if (coalesce.kind !== "logical" || coalesce.op !== "??" || coalesce.right.kind !== "literal" || coalesce.right.literalType !== "number") {
+      return null;
+    }
+    const inner = this.extractPropFallbackFromParsed(parsed.left);
+    if (!inner)
+      return null;
+    return { ...inner, operator: parsed.op, operand: String(right.value) };
+  }
   extractPropNameFromInitialValue(initialValue, preParsed) {
     if (!this.state.propsObjectName) {
       if (preParsed?.kind === "logical" && (preParsed.op === "??" || preParsed.op === "||") && preParsed.left.kind === "identifier") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/go-template",
-  "version": "0.31.10",
+  "version": "0.32.0",
   "description": "Go html/template adapter for BarefootJS - generates Go template files from IR",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "directory": "packages/adapter-go-template"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.31.10"
+    "@barefootjs/shared": "0.32.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0",
@@ -67,9 +67,9 @@
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/client": "0.31.10",
-    "@barefootjs/jsx": "0.31.10",
-    "@barefootjs/vite": "0.31.10",
+    "@barefootjs/client": "0.32.0",
+    "@barefootjs/jsx": "0.32.0",
+    "@barefootjs/vite": "0.32.0",
     "vite": "^6.0.0"
   }
 }

package/src/__tests__/go-template-adapter.test.ts

@@ -1121,7 +1121,11 @@ export function Rows() {
       expect(types).toContain('DataX string `json:"data-x"`')
       expect(types).not.toContain('"Data-x"')
       expect(types).toContain('Row{ID: "r1", Meta: RowMeta{DataX: "v"}}')
-      expect(types).not.toContain('map[string]interface{}')
+      // `Meta` resolved to the real synthesized struct, not the
+      // `map[string]interface{}` fallback — scoped to the field itself
+      // since `BfCallerProps map[string]interface{}` (#2684) legitimately
+      // appears elsewhere in every generated Props struct now.
+      expect(types).not.toMatch(/Meta map\[string\]interface\{\}/)
     })
 
     test('snake_case keys keep their underscore in the generated field name (#2089 review)', () => {
@@ -5011,7 +5015,10 @@ export function Foo({ q: searchParams }: { q: string }) {
     expect((result.errors ?? []).filter(e => e.code === 'BF101')).toHaveLength(0)
     const types = result.files.find(f => f.type === 'types')!.content
     const structStart = types.indexOf('type FooProps struct')
-    const fooPropsBody = types.slice(structStart, types.indexOf('}', structStart))
+    // The struct's actual closing brace is the first `}` that starts its
+    // OWN line (fields are tab-indented) — a bare `indexOf('}', ...)` would
+    // stop early at the embedded `}` inside `BfCallerProps map[string]interface{}` (#2684).
+    const fooPropsBody = types.slice(structStart, types.indexOf('\n}', structStart))
     // Exactly one "SearchParams" field in the struct body — the prop's
     // own — never a second `SearchParams bf.SearchParams` reader field
     // colliding with it (a Go redeclaration error).
@@ -5021,6 +5028,188 @@ export function Foo({ q: searchParams }: { q: string }) {
   })
 })
 
+// #2684: `bf-p` must carry only what the caller actually passed — required
+// props always, optional ones only when supplied — never the author's
+// baked default (`x ?? 7`), never `null` for an omitted optional, never a
+// Go zero value standing in for "unset". `NewXxxProps` now ALSO populates a
+// `BfCallerProps map[string]interface{}` sidecar (marshaled by `BfPropsAttr`
+// INSTEAD OF the whole struct) with exactly the caller-supplied, raw
+// (undefaulted) values — see the field's doc comment in
+// `emitPropsStructHeader` for the two-consumers rationale.
+describe('GoTemplateAdapter - BfCallerProps hydration sidecar (#2684)', () => {
+  test('NewXxxProps populates BfCallerProps for the three classes: required, nullish-consumed optional, concrete-typed optional residual', () => {
+    const result = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { x?: number; label?: string; name: string }) {
+  const [x] = createSignal(props.x ?? 7)
+  return <div data-name={props.name}>{x()}</div>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    expect((result.errors ?? []).filter(e => e.code === 'BF101')).toHaveLength(0)
+    const types = result.files.find(f => f.type === 'types')!.content
+    // The sidecar field itself, on the Props struct.
+    expect(types).toContain('BfCallerProps map[string]interface{} `json:"-"`')
+
+    const newProps = types.slice(types.indexOf('func NewCProps'))
+    expect(newProps).toContain('bfCallerProps := map[string]interface{}{}')
+    // Class 1 — required prop: always included, raw `in.Name` (never a
+    // baked/defaulted value — there is none for a required prop anyway).
+    expect(newProps).toContain('bfCallerProps["name"] = in.Name')
+    // Class 2 — optional, nullish-consumed (`??`) prop: flips to `interface{}`
+    // (#2248) and is included ONLY when the caller actually passed something.
+    // Critically, the RAW `in.X` goes in the map, never the baked default
+    // `7` the hoisted fallback var applies to the template-facing field.
+    expect(newProps).toContain('if in.X != nil {')
+    expect(newProps).toContain('bfCallerProps["x"] = in.X')
+    expect(newProps).not.toMatch(/bfCallerProps\["x"\]\s*=\s*7/)
+    // Class 3 — optional prop that resolves to a CONCRETE type (`label` is
+    // never consumed nullish/attr/text/presence-wise, so it stays a plain
+    // `string`): presence is unknowable from Input alone, so it's included
+    // unconditionally — a documented residual, not silently dropped.
+    expect(newProps).toContain('bfCallerProps["label"] = in.Label')
+
+    // The struct literal wires the local into the field.
+    expect(newProps).toContain('BfCallerProps: bfCallerProps,')
+  })
+
+  test('a required nested-array-shadowed prop (#2672/#2525) is carried via its reshaped array local, not silently dropped', () => {
+    const result = compileJSX(`
+type ToggleItemProps = { label: string; defaultOn?: boolean }
+function ToggleItem(props: ToggleItemProps) {
+  return <div>{props.label}</div>
+}
+type ToggleProps = { toggleItems: ToggleItemProps[] }
+export function Toggle({ toggleItems }: ToggleProps) {
+  return <div>{toggleItems.map((item) => <ToggleItem key={item.label} label={item.label} defaultOn={item.defaultOn} />)}</div>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    expect((result.errors ?? []).filter(e => e.code === 'BF101')).toHaveLength(0)
+    const types = result.files.find(f => f.type === 'types')!.content
+    const newProps = types.slice(types.indexOf('func NewToggleProps'))
+    // The shadowed prop has no `in.ToggleItems` scalar field to read — its
+    // data is carried via the already-built reshaped array local instead.
+    // `toggleItems` is REQUIRED here, so it's unconditional — same
+    // required-stays-unconditional rule as the main loop.
+    expect(newProps).toContain('bfCallerProps["toggleItems"] = toggleItems')
+    expect(newProps).not.toContain('if in.ToggleItems != nil {')
+  })
+})
+
+describe('GoTemplateAdapter - collision-derivation lowering (#2683)', () => {
+  test('a signal colliding with its own prop composes the presence-check fold with the surrounding arithmetic', () => {
+    const result = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { count?: number }) {
+  const [count, setCount] = createSignal((props.count ?? 1) * 2)
+  return <span>{count()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    expect((result.errors ?? []).filter(e => e.code === 'BF101')).toHaveLength(0)
+    const types = result.files.find(f => f.type === 'types')!.content
+    // The collision flips the field to the nillable representation — the
+    // SAME flip an ordinary `??`-consumed optional prop gets (#2248) — so an
+    // absent prop (nil) and an explicit `0` stay distinguishable.
+    expect(types).toContain('Count interface{}')
+    const newProps = types.slice(types.indexOf('func NewCProps'))
+    // The presence-check fold (`extractPropFallbackFromParsed`'s shape,
+    // reused unchanged) hoists the RAW coalesced value into a local...
+    expect(newProps).toContain('var count int = 1')
+    expect(newProps).toContain('if in.Count != nil {')
+    expect(newProps).toContain('count = bf.ToInt(in.Count)')
+    // ...and the shared field carries the FULLY DERIVED value — the local
+    // with the surrounding `* 2` composed back on, not just the coalesce
+    // result.
+    expect(newProps).toContain('Count: count * 2,')
+    // `BfCallerProps` (#2684) keeps carrying the RAW caller value, never the
+    // derived one.
+    expect(newProps).toContain('if in.Count != nil {')
+    expect(newProps).toContain('bfCallerProps["count"] = in.Count')
+    expect(newProps).not.toMatch(/bfCallerProps\["count"\]\s*=\s*count/)
+  })
+
+  test('a NON-NUMERIC `??` fallback declines collision-derivation — raw passthrough, never invalid Go (Copilot review, #2694)', () => {
+    // `(props.label ?? 'x') + 2` would otherwise hoist `var label string =
+    // "x"` and emit `Label: label + 2,` — invalid Go (string + int), a
+    // compile BREAK where the pre-fix behavior at least built. JS semantics
+    // are string concatenation here besides, so a numeric compose could
+    // never be faithful; the shape stays on the raw-passthrough path.
+    const result = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { label?: string }) {
+  const [label, setLabel] = createSignal((props.label ?? 'x') + 2)
+  return <span>{label()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    const types = result.files.find(f => f.type === 'types')!.content
+    const newProps = types.slice(types.indexOf('func NewCProps'))
+    expect(newProps).not.toContain('label + 2')
+    expect(newProps).not.toContain('var label string = "x"')
+    // The field keeps the pre-existing raw passthrough.
+    expect(newProps).toContain('Label: in.Label,')
+  })
+
+  test('a `/ 0` operand declines collision-derivation — Go constant division by zero is a compile error', () => {
+    const result = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { count?: number }) {
+  const [count, setCount] = createSignal((props.count ?? 1) / 0)
+  return <span>{count()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    const types = result.files.find(f => f.type === 'types')!.content
+    const newProps = types.slice(types.indexOf('func NewCProps'))
+    expect(newProps).not.toContain('count / 0')
+    expect(newProps).toContain('Count: in.Count,')
+  })
+
+  test('the same collision reached through a component-scope const hop (#2685) lowers identically', () => {
+    const direct = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Direct(props: { count?: number }) {
+  const [count, setCount] = createSignal((props.count ?? 1) * 2)
+  return <span>{count()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    const viaConst = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function ViaConst(props: { count?: number }) {
+  const mid = props.count
+  const [count, setCount] = createSignal((mid ?? 1) * 2)
+  return <span>{count()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    const directTypes = direct.files.find(f => f.type === 'types')!.content
+    const viaConstTypes = viaConst.files.find(f => f.type === 'types')!.content
+    expect(directTypes.slice(directTypes.indexOf('func NewDirectProps'))).toContain('Count: count * 2,')
+    expect(viaConstTypes.slice(viaConstTypes.indexOf('func NewViaConstProps'))).toContain('Count: count * 2,')
+  })
+
+  test('a differently-named signal deriving from the same prop (no collision) is untouched — its own field, not the shared one', () => {
+    const result = compileJSX(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function NonCollide(props: { count?: number }) {
+  const [doubled, setDoubled] = createSignal((props.count ?? 1) * 2)
+  return <span>{doubled()}</span>
+}
+`.trimStart(), 'test.tsx', { adapter: new GoTemplateAdapter(), outputIR: false })
+    const types = result.files.find(f => f.type === 'types')!.content
+    // No collision here — `count`'s own field stays the plain concrete type,
+    // byte-identical to before this fix.
+    expect(types).toContain('Count int')
+    expect(types).not.toContain('Count interface{}')
+    const newProps = types.slice(types.indexOf('func NewNonCollideProps'))
+    expect(newProps).not.toContain('var count int')
+    expect(newProps).toContain('Count: in.Count,')
+  })
+})
+
 // #2228: a `.filter(t => …).map(todo => <Child todo={todo} .../>)` loop whose
 // body is a single child component ranges the WRAPPER slice (`.TodoItems`,
 // `.{ChildName}s` — see #2130 above), so `{{if}}`'s dot context for the
@@ -6032,9 +6221,11 @@ export { TaggedList }
     expect(types).toContain('Title string `json:"title"`')
     expect(types).toContain('Tags []string `json:"tags"`')
     // The Input/Props field is a typed struct slice, not the old
-    // `[]map[string]interface{}` fallback.
+    // `[]map[string]interface{}` fallback. Scoped to the field itself —
+    // `BfCallerProps map[string]interface{}` (#2684) legitimately appears
+    // elsewhere in every generated Props struct now.
     expect(types).toMatch(/Items \[\]TaggedListItemsItem/)
-    expect(types).not.toContain('map[string]interface{}')
+    expect(types).not.toMatch(/Items \[?\]?map\[string\]interface\{\}/)
   })
 
   test('nested anonymous property inside a NAMED type synthesizes a named struct (case ii, Row.user)', () => {
@@ -6068,7 +6259,10 @@ export function NestedNames() {
     // The signal's inline initial value bakes through the STRUCT literal
     // path, not `bakeInlineObjectAsGoMap`'s capitalized-key map convention.
     expect(types).toContain('Row{ID: "r1", User: RowUser{Name: "Ada"}}')
-    expect(types).not.toContain('map[string]interface{}')
+    // Scoped to the `User` field itself — `BfCallerProps
+    // map[string]interface{}` (#2684) legitimately appears elsewhere in
+    // every generated Props struct now.
+    expect(types).not.toMatch(/User map\[string\]interface\{\}/)
   })
 
   test('a synthesized-name collision gracefully falls back to the pre-#2674 map convention, not a regression', () => {
@@ -6165,7 +6359,53 @@ export function NestedNames() {
       .replace(/&#34;/g, '"')
       .replace(/&quot;/g, '"')
     const payload = JSON.parse(decoded)
-    // No props at all on this component — bf-p carries nothing.
+    // No props at all on this component — bf-p carries nothing. Still a
+    // real, present `bf-p="{}"` (#2684's sidecar substitution isn't gated
+    // on emptiness — see `BfPropsAttr`'s doc comment for why).
     expect(payload).toEqual({})
   })
+
+  // #2684 end-to-end: an omitted optional prop must not resurrect the
+  // author's default, or a `null`, in the wire payload — and an EXPLICIT
+  // falsy/zero value the caller DID pass must still come through.
+  test('real go-run render: bf-p carries only caller-supplied keys — omitted optional absent, explicit zero present, required always present', async () => {
+    const source = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { x?: number; label?: string; name: string }) {
+  const [x] = createSignal(props.x ?? 7)
+  return <div data-name={props.name}>{x()}</div>
+}
+export { C }
+`
+    let htmlOmitted: string
+    let htmlExplicitZero: string
+    try {
+      htmlOmitted = await renderGoTemplateComponent({
+        source,
+        adapter: new GoTemplateAdapter(),
+        props: { name: 'Ada' },
+      })
+      htmlExplicitZero = await renderGoTemplateComponent({
+        source,
+        adapter: new GoTemplateAdapter(),
+        props: { name: 'Ada', x: 0 },
+      })
+    } catch (err) {
+      if (err instanceof GoNotAvailableError) return // Go toolchain not installed on this host
+      throw err
+    }
+    const decode = (html: string) => {
+      const m = html.match(/bf-p="([^"]*)"/)
+      expect(m).not.toBeNull()
+      return JSON.parse(m![1].replace(/&#34;/g, '"').replace(/&quot;/g, '"'))
+    }
+    // `x` omitted: no baked `7`, no `null` — the key is simply absent.
+    // `label` (class-3 residual, no consumption anywhere) still shows up at
+    // its Go zero value — documented, not silently dropped.
+    expect(decode(htmlOmitted)).toEqual({ name: 'Ada', label: '' })
+    // `x: 0` explicitly passed: present with the caller's real value, not
+    // coalesced away or confused with "absent".
+    expect(decode(htmlExplicitZero)).toEqual({ name: 'Ada', label: '', x: 0 })
+  })
 })

package/src/adapter/emit-context.ts

@@ -59,6 +59,20 @@ export interface GoEmitContext {
     preParsed?: ParsedExpr,
   ): { propName: string; goFallback: string } | null
 
+  /**
+   * #2683: match the collision-derivation shape `(props.X ?? <lit>) <op>
+   * <int>` against an already-resolved `ParsedExpr` — the ONE non-idempotent
+   * form this adapter faithfully lowers when a signal's Go field name
+   * collides with its own prop's field. Composes
+   * {@link extractPropFallback}'s structural presence-check recognition
+   * (applied to the embedded `??` subtree) with the same non-negative-
+   * integer arithmetic wrap the memo-computation emitter already supports
+   * for a bare `props.X <op> N`. Returns null for any other shape.
+   */
+  extractCollisionDerivation(
+    parsed: ParsedExpr | undefined,
+  ): { propName: string; goFallback: string; operator: string; operand: string } | null
+
   /**
    * Inline a module string const by name as a Go double-quoted literal
    * (`"<escaped>"`), or null when the name is not such a const (loop vars and