@barefootjs/jsx 0.19.1 → 0.20.0

package/src/__tests__/client-js-generation.test.ts

@@ -1162,6 +1162,65 @@ describe('Client JS generation', () => {
       expect(basicErrorCount).toBe(1) // only inside computeError body
       expect(isDuplicateCount).toBe(1) // only inside computeError body
     })
+
+    test('import used only inside a module-level helper is traced into the client bundle (#2283)', () => {
+      const source = `
+        'use client'
+        import { createMemo } from '@barefootjs/client'
+        import { computeSheetGeometry } from '../src/lib/sheetGeometry'
+
+        function buildSheetVMs(count: number) {
+          return computeSheetGeometry(count)
+        }
+
+        export function PrintSheets(props: { count: number }) {
+          const sheets = createMemo(() => buildSheetVMs(props.count))
+          return <div>{sheets()}</div>
+        }
+      `
+
+      const result = compileJSX(source, 'PrintSheets.tsx', { adapter })
+      expect(result.errors).toHaveLength(0)
+
+      const clientJs = result.files.find(f => f.type === 'clientJs')
+      expect(clientJs).toBeDefined()
+      const content = clientJs!.content
+
+      // The helper's body (which references the import) must be emitted...
+      expect(content).toContain('computeSheetGeometry(count)')
+      // ...and the import that body depends on must be traced and emitted too,
+      // otherwise the browser throws `ReferenceError: computeSheetGeometry is not defined`.
+      expect(content).toContain("import { computeSheetGeometry } from '../src/lib/sheetGeometry'")
+    })
+
+    test('module-level helper body containing a literal "$&" is spliced in verbatim', () => {
+      // A plain-string second argument to String.replace() specially
+      // interprets `$&`/`$1`/`$$` — the placeholder-substitution step must
+      // use the replacer-function form so a helper body containing one of
+      // these sequences isn't corrupted (piconic-ai/barefootjs#2286 review).
+      const source = `
+        'use client'
+        import { createMemo } from '@barefootjs/client'
+
+        function formatMoney(amount: number) {
+          return '$&' + amount
+        }
+
+        export function Price(props: { amount: number }) {
+          const label = createMemo(() => formatMoney(props.amount))
+          return <div>{label()}</div>
+        }
+      `
+
+      const result = compileJSX(source, 'Price.tsx', { adapter })
+      expect(result.errors).toHaveLength(0)
+
+      const clientJs = result.files.find(f => f.type === 'clientJs')
+      expect(clientJs).toBeDefined()
+      const content = clientJs!.content
+
+      expect(content).toContain("'$&' + amount")
+    })
   })
 
   describe('child component value/boolean prop binding', () => {

package/src/__tests__/nested-loop-reactive-attrs.test.ts

@@ -342,4 +342,60 @@ describe('reactive attributes inside a nested .map() body (#135)', () => {
     expect(content).toMatch(/createEffect\(\(\) => \{[\s\S]*?\.textContent = String\(panel\(\)\.text\)/)
     expect(content).toContain("setAttribute('class'")
   })
+
+  test('reactive text child of a triple-nested inner loop read through an opaque helper gets an update effect (#2282)', () => {
+    // #2264 fixed the case where `classifyReactivity` proves the text
+    // reactive via the loop-param path (bare `panel.text`). It left a
+    // sibling gap: `collectLoopChildReactiveTexts` had no Solid-style
+    // AST-flag fallback, so a text read through an opaque helper the
+    // classifier can't see through (`labelAt(pi)` where `const labelAt =
+    // (i) => labels()[i]`) still silently dropped its update effect — while
+    // `collectLoopChildReactiveAttrs` already had that fallback (#1673,
+    // see `reactive-attrs-in-map.test.ts`), so the sibling `className`
+    // effect on the SAME element kept working. Reported as #2282 ("child
+    // inlined into a parent island drops the innermost reactive text
+    // effect"); the issue's own literal `{panel.text}` repro snippet
+    // doesn't reproduce it (that shape is exactly what #2264 already
+    // fixed) — this test pins the actual asymmetry root-caused during
+    // investigation, using the opaque-helper shape that does reproduce.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      type Panel = { id: number; cls: string }
+      type Band = { id: string; panels: Panel[] }
+      type Page = { id: string; bands: Band[] }
+
+      export function Doc2() {
+        const [pages] = createSignal<Page[]>([])
+        const [labels] = createSignal<string[]>([])
+        const labelAt = (i: number) => labels()[i]
+        return (
+          <div>
+            {pages().map(page => (
+              <div key={page.id}>
+                {page.bands.map(band => (
+                  <div key={band.id}>
+                    {band.panels.map((panel, pi) => (
+                      <div key={panel.id} className={panel.cls}>{labelAt(pi)}</div>
+                    ))}
+                  </div>
+                ))}
+              </div>
+            ))}
+          </div>
+        )
+      }
+    `
+    const result = compileJSX(source, 'Doc2.tsx', { adapter })
+    expect(result.errors).toHaveLength(0)
+    const content = result.files.find((f) => f.type === 'clientJs')!.content
+
+    // The helper call must appear inside a createEffect alongside the
+    // textContent write — `labelAt(` also appears in the static template
+    // clone, so asserting it independently would pass even with the
+    // effect missing (the exact regression here).
+    expect(content).toMatch(/createEffect\(\(\) => \{[\s\S]*?\.textContent = String\(labelAt\(pi\)\)/)
+    expect(content).toContain("setAttribute('class'")
+  })
 })

package/src/__tests__/rich-type-method-refusal.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Rich-type method-call refusal (BF021, #2273).
+ *
+ * A method call on a prop typed as a built-in host rich type (`Date`,
+ * `Map`, …) has no catalogued lowering in any adapter — left unchecked it
+ * transliterates into the target template's own syntax and dies at request
+ * time. `checkRichTypeMethodCalls` (rich-type-refusal.ts) is wired into
+ * `compileJSX` (not the bare analyzer/jsxToIR pipeline other BF021 tests in
+ * this directory use), so these tests go through `compileJSX` directly.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { ErrorCodes } from '../errors'
+import { TestAdapter } from '../adapters/test-adapter'
+import { registerLoweringPlugin, __resetLoweringPluginsForTest, getLoweringPlugins, type LoweringPlugin } from '../lowering-registry'
+
+const adapter = new TestAdapter()
+
+function bf021(source: string, filePath = 'Test.tsx') {
+  const result = compileJSX(source, filePath, { adapter })
+  return result.errors.filter((e) => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+}
+
+describe('rich-type method-call refusal — fires (BF021)', () => {
+  test('inline-destructured Date in text position', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{createdAt.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toISOString()'")
+    expect(errors[0].message).toContain("'createdAt'")
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('props-object member chain in attribute position', () => {
+    const errors = bf021(`
+      export function Foo(props: { d: Date }) {
+        return <div data-year={props.d.getUTCFullYear()} />
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.getUTCFullYear()'")
+    expect(errors[0].message).toContain("'props.d'")
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('named interface Props Date field (typeDefinitions deref)', () => {
+    const errors = bf021(`
+      interface Props { createdAt: Date }
+      export function Foo({ createdAt }: Props) {
+        return <div>{createdAt.getFullYear()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.getFullYear()'")
+    expect(errors[0].message).toContain("'createdAt'")
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('optional-chained call', () => {
+    const errors = bf021(`
+      export function Foo({ d }: { d: Date | undefined }) {
+        return <div>{d?.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toISOString()'")
+  })
+
+  test('Date | null union resolves to Date', () => {
+    const errors = bf021(`
+      export function Foo({ d }: { d: Date | null }) {
+        return <div>{d.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('loop-item member (items.map(i => i.at.getTime()))', () => {
+    const errors = bf021(`
+      export function Foo({ items }: { items: { at: Date }[] }) {
+        return <ul>{items.map(i => <li>{i.at.getTime()}</li>)}</ul>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.getTime()'")
+    // A loop item is prop-DERIVED but not itself a prop — the message must
+    // not call it one (only bare / props-object receivers earn "prop").
+    expect(errors[0].message).toContain("on 'i.at'")
+    expect(errors[0].message).not.toContain("prop 'i.at'")
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('renamed destructured prop ({ createdAt: c })', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt: c }: { createdAt: Date }) {
+        return <div>{c.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toISOString()'")
+    expect(errors[0].message).toContain("prop 'c'")
+    expect(errors[0].message).toContain("'Date'")
+  })
+
+  test('conditional-branch call without @client', () => {
+    const errors = bf021(`
+      export function Foo({ d }: { d: Date | null }) {
+        return <div>{d && <span>{d.toISOString()}</span>}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toISOString()'")
+  })
+
+  test('two distinct receivers at the same expression report separately', () => {
+    const errors = bf021(`
+      export function Foo({ a, b }: { a: Date; b: Date }) {
+        return <div>{a.getTime() + b.getTime()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(2)
+    expect(errors[0].message).toContain("prop 'a'")
+    expect(errors[1].message).toContain("prop 'b'")
+  })
+
+  test('Date in component-prop position', () => {
+    const errors = bf021(`
+      function Bar(props: { value: string }) {
+        return <div>{props.value}</div>
+      }
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <Bar value={createdAt.toISOString()} />
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toISOString()'")
+    expect(errors[0].message).toContain("'createdAt'")
+  })
+
+  test('Map.get() (broad host-type list)', () => {
+    const errors = bf021(`
+      export function Foo({ m }: { m: Map<string, string> }) {
+        return <div>{m.get('x')}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.get()'")
+    expect(errors[0].message).toContain("'Map'")
+  })
+
+  test('diagnostic carries the @client suggestion', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{createdAt.toISOString()}</div>
+      }
+    `)
+    expect(errors[0].severity).toBe('error')
+    expect(errors[0].suggestion?.message).toContain('@client')
+  })
+})
+
+describe('rich-type method-call refusal — silent (no BF021)', () => {
+  test('/* @client */-prefixed Date call', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('/* @client */-wrapped conditional branch', () => {
+    const errors = bf021(`
+      export function Foo({ d }: { d: Date | null }) {
+        return <div>{/* @client */ d && <span>{d.toISOString()}</span>}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('module const sharing a propsType field name (object-props mode)', () => {
+    const errors = bf021(`
+      const version = 'v1'
+      export function Foo(props: { version: Map<string, string> }) {
+        return <div>{version.toUpperCase()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('string method on string prop', () => {
+    const errors = bf021(`
+      export function Foo({ s }: { s: string }) {
+        return <div>{s.toUpperCase()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('array method on array prop', () => {
+    const errors = bf021(`
+      export function Foo({ items }: { items: string[] }) {
+        return <div>{items.join(',')}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('untyped receiver (no type annotation)', () => {
+    const errors = bf021(`
+      export function Foo({ d }) {
+        return <div>{d.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('generic type-parameter receiver', () => {
+    const errors = bf021(`
+      export function Foo<T>({ d }: { d: T }) {
+        return <div>{d.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('imported named type receiver', () => {
+    const errors = bf021(`
+      import type { Widget } from './widget'
+      export function Foo({ w }: { w: Widget }) {
+        return <div>{w.render()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('signal getter call result (d().toISOString())', () => {
+    const errors = bf021(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Foo() {
+        const [d, setD] = createSignal(new Date())
+        return <div>{d().toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('local-function call (not a member call on the receiver)', () => {
+    const errors = bf021(`
+      function formatDate(x: Date): string { return x.toString() }
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{formatDate(createdAt)}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('.length non-call access', () => {
+    const errors = bf021(`
+      export function Foo({ items }: { items: string[] }) {
+        return <div>{items.length}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('in-file interface Date shadow', () => {
+    const errors = bf021(`
+      interface Date { iso: string }
+      export function Foo({ d }: { d: Date }) {
+        return <div>{d.toISOString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('registry-claimed call is exempt (#2274 seam)', () => {
+    const samplePlugin: LoweringPlugin = {
+      name: 'sample-date-lowering',
+      prepare: () => (callee, _args) =>
+        callee.kind === 'member' && !callee.computed && callee.property === 'toISOString'
+          ? { kind: 'helper-call', helper: 'isoDate', args: [] }
+          : null,
+    }
+    registerLoweringPlugin(samplePlugin)
+    try {
+      const errors = bf021(`
+        export function Foo({ createdAt }: { createdAt: Date }) {
+          return <div>{createdAt.toISOString()}</div>
+        }
+      `)
+      expect(errors).toHaveLength(0)
+    } finally {
+      __resetLoweringPluginsForTest(getLoweringPlugins().filter((p) => p.name !== 'sample-date-lowering'))
+    }
+  })
+})

package/src/analyzer.ts

@@ -3068,6 +3068,8 @@ function extractProps(param: ts.ParameterDeclaration, ctx: AnalyzerContext): voi
           optional: !!member?.optional || !!element.initializer,
           defaultValue,
           defaultContainsArrow: defaultContainsArrow || undefined,
+          // Only aliased bindings carry the source key — see ParamInfo.sourceName.
+          ...(sourcePropName !== localName && { sourceName: sourcePropName }),
         })
       }
     }

package/src/compiler.ts

@@ -24,6 +24,7 @@ import { applyCssLayerPrefix } from './css-layer-prefixer.ts'
 import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.ts'
 import { extractSsrDefaults } from './ssr-defaults.ts'
 import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
+import { checkRichTypeMethodCalls } from './rich-type-refusal.ts'
 
 /**
  * Extended compile options with required adapter
@@ -137,6 +138,7 @@ function compileMultipleComponents(
     }
 
     componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
+    checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
 
     if (options.cssLayerPrefix) {
       applyCssLayerPrefix(componentIR, options.cssLayerPrefix)
@@ -615,6 +617,7 @@ export function compileJSX(
 
   // Pre-compute client JS analysis for adapter optimization
   componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
+  checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
 
   // Cross-file @client signal sources: identify which import sources
   // need `.client.js` path rewriting in the client bundle.

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

@@ -99,16 +99,23 @@ export function generateInitFunction(
   let generatedCode = rewritePropsObjectRef(lines.join('\n'), ctx.propsObjectName)
   generatedCode += '\n' + hydrateLine
 
-  const allImportLines = resolveFinalImports(generatedCode, ir, localImportPrefixes)
+  // Substitute module-level declarations BEFORE import detection: a
+  // module-level helper's body (e.g. `buildSheetVMs` calling
+  // `computeSheetGeometry`) only exists in `moduleConstantsCode`, so
+  // scanning `generatedCode` first would miss any import referenced
+  // only from that body and silently drop it (#2283).
   const moduleConstantsCode = emitModuleLevelDeclarations(
     classification.moduleLevelConstants,
     classification.moduleLevelFunctions,
     classification.moduleLevelSignals,
     classification.moduleLevelMemos,
   )
+  // Replacer-function form: a plain replacement string would let literal
+  // `$&`/`$1`/`$$` sequences in user helper bodies or import paths be
+  // reinterpreted by `String.replace`'s special-pattern handling.
+  const codeWithModuleConstants = generatedCode.replace(MODULE_CONSTANTS_PLACEHOLDER, () => moduleConstantsCode)
+  const allImportLines = resolveFinalImports(codeWithModuleConstants, ir, localImportPrefixes)
 
-  return generatedCode
-    .replace(IMPORT_PLACEHOLDER, allImportLines)
-    .replace(MODULE_CONSTANTS_PLACEHOLDER, moduleConstantsCode)
+  return codeWithModuleConstants.replace(IMPORT_PLACEHOLDER, () => allImportLines)
 }
 

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

@@ -529,8 +529,19 @@ export function collectLoopChildReactiveTexts(
       const originFreeIds = freeIdsFromRefs(n.origin?.freeRefs)
       const expanded = expandConstantForReactivity(n.expr, ctx, originFreeIds)
       // Include if expression reads signals OR references the loop parameter
-      // (loop param becomes a signal accessor via per-item signals).
-      if (classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind === 'none') return
+      // (loop param becomes a signal accessor via per-item signals). Falls
+      // back to the Solid-style AST-flag wrap decision — mirroring
+      // `collectLoopChildReactiveAttrs`'s `callsReactiveGetters` /
+      // `hasFunctionCalls` fallback (#1673) and the top-level text path's
+      // `decideWrapFromAstFlags` gate (`collectElements`'s `expression`
+      // handler) — so a loop-item text read through an opaque helper
+      // (`textAt(i)` where `const textAt = (i) => rows()[i]`, which
+      // `classifyReactivity` can't see through) still gets an update
+      // effect instead of silently freezing at its SSR value (#2282).
+      const reactive =
+        classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind !== 'none'
+        || decideWrapFromAstFlags(n).wrap
+      if (!reactive) return
       texts.push({
         slotId: n.slotId,
         expression: expanded.expr,

package/src/rich-type-evidence.ts

@@ -0,0 +1,159 @@
+/**
+ * Type-evidence resolution for the rich-type method-call refusal (#2273).
+ *
+ * `resolveReceiverType` answers one question: "what TypeScript type, if any,
+ * does this `ParsedExpr` evaluate to?" — using only the structured metadata
+ * already collected at IR-build time (`propsType` / `typeDefinitions`), never
+ * a fresh type-checker pass. It is deliberately conservative: any receiver
+ * shape it doesn't recognize (a call result, computed access, a local not in
+ * `bindings`, …) resolves to `null` ("no evidence"), which the caller must
+ * treat as "don't flag" rather than "flag as unknown". A false negative here
+ * only misses a refusal; a false positive would incorrectly block valid code.
+ */
+
+import type { IRMetadata, PropertyInfo, TypeInfo } from './types.ts'
+import type { ParsedExpr } from './expression-parser.ts'
+
+/**
+ * Built-in JS/TS types whose instance methods have no catalogued lowering
+ * (spec/subset-conformance.md). A prop typed as one of these is opaque past
+ * this point — the adapters have no structural representation for `Date`,
+ * `Map`, etc., only for the primitives/arrays/plain-objects the IR already
+ * lowers. Names only (no generic args) — compare against `baseTypeName`.
+ *
+ * Two shapes deliberately escape this catalogue (conservative misses, not
+ * bugs — a miss only skips a refusal, never misdiagnoses):
+ *   - keyword-typed `bigint` / `symbol` annotations lower to
+ *     `{ kind: 'unknown' }` in `typeNodeToTypeInfo` (only the object-form
+ *     `BigInt` / `Symbol` type references reach `kind: 'interface'` and
+ *     match here);
+ *   - a local alias of a host type (`type Timestamp = Date`) resolves to
+ *     the alias NAME — `derefNamedType` only fills in `properties` from a
+ *     declaration, it never rewrites `raw` to the alias target — so the
+ *     catalogue lookup sees `Timestamp`, not `Date`.
+ */
+export const HOST_RICH_TYPE_NAMES: ReadonlySet<string> = new Set([
+  'Date',
+  'Map',
+  'Set',
+  'WeakMap',
+  'WeakSet',
+  'URL',
+  'URLSearchParams',
+  'RegExp',
+  'Promise',
+  'Error',
+  'Symbol',
+  'BigInt',
+  'Function',
+])
+
+/**
+ * Strip generic type arguments from a `TypeInfo.raw` string (`Map<string,
+ * string>` → `Map`) so a parametrized host type still matches the bare-name
+ * catalogue above. `raw` is source-verbatim (`typeNodeToTypeInfo`), so this
+ * is a plain substring split on the first `<` — not a type-syntax parse.
+ */
+export function baseTypeName(raw: string): string {
+  const idx = raw.indexOf('<')
+  return (idx === -1 ? raw : raw.slice(0, idx)).trim()
+}
+
+type EvidenceMetadata = Pick<IRMetadata, 'propsType' | 'propsObjectName' | 'propsParams' | 'typeDefinitions'>
+
+/**
+ * Collapse a union to its single non-nullish arm (`Date | null` → `Date`),
+ * recursively, so an optional rich-typed prop still carries evidence. A
+ * union with more than one non-nullish arm has no single answer and is left
+ * as-is (its `kind` is `'union'`, which never matches the `'interface'`
+ * check callers gate on).
+ */
+function isNullishArm(t: TypeInfo): boolean {
+  if (t.kind === 'primitive' && (t.primitive === 'null' || t.primitive === 'undefined')) return true
+  // `null` as a type annotation is a `ts.LiteralTypeNode` (not the
+  // `NullKeyword` `typeNodeToTypeInfo`'s primitive switch checks for), so it
+  // falls through to `{ kind: 'unknown', raw: 'null' }` there — a pre-existing
+  // gap in that shared helper, out of scope to fix here. Match on `raw` too
+  // so `Date | null` still strips down to `Date`.
+  return t.kind === 'unknown' && (t.raw === 'null' || t.raw === 'undefined')
+}
+
+function stripUnion(type: TypeInfo | null): TypeInfo | null {
+  if (!type || type.kind !== 'union' || !type.unionTypes) return type
+  const nonNullish = type.unionTypes.filter((t) => !isNullishArm(t))
+  return nonNullish.length === 1 ? stripUnion(nonNullish[0]) : type
+}
+
+/**
+ * Resolve a named type (`{ kind: 'interface', raw: 'Props' }`) that carries
+ * no inline `properties` to its declaration's field list via
+ * `metadata.typeDefinitions`. A type already carrying properties (an inline
+ * object literal type, or a type resolved from `tsTypeToTypeInfo`) is
+ * returned unchanged — this only fills in the gap left by a *named*
+ * reference, which `typeNodeToTypeInfo` intentionally resolves to
+ * `{ kind: 'interface', raw }` with no member walk of its own.
+ */
+function derefNamedType(type: TypeInfo, meta: EvidenceMetadata): TypeInfo {
+  if (type.kind !== 'interface') return type
+  if (type.properties && type.properties.length > 0) return type
+  const name = baseTypeName(type.raw)
+  const def = meta.typeDefinitions.find((d) => d.name === name)
+  if (!def?.properties) return type
+  return { ...type, properties: def.properties }
+}
+
+/**
+ * Resolve one property's type off an object-shaped receiver type, deref'ing
+ * a named type first (`Props.createdAt`) and stripping a nullable union off
+ * the result (`Date | null` field). Returns `null` when the receiver has no
+ * evidence, or the property isn't found on it.
+ */
+function lookupProperty(objType: TypeInfo | null, propName: string, meta: EvidenceMetadata): TypeInfo | null {
+  const stripped = stripUnion(objType)
+  if (!stripped) return null
+  const deref = derefNamedType(stripped, meta)
+  const prop = deref.properties?.find((p: PropertyInfo) => p.name === propName)
+  return prop ? stripUnion(prop.type) : null
+}
+
+/**
+ * Resolve the TypeInfo of a receiver expression, using only propsType /
+ * propsParams / typeDefinitions and the caller-supplied local bindings.
+ * `bindings` maps a name to its known type — or explicitly to `null` for a
+ * shadow the caller has proven carries no evidence (e.g. an arrow param, a
+ * loop item whose array type isn't known). A `bindings` hit always wins over
+ * the props fallback, matching JS lexical shadowing.
+ *
+ * Only two `ParsedExpr` shapes carry evidence: a bare identifier and a
+ * non-computed member access. Everything else (calls, computed/index
+ * access, literals, …) resolves to `null` — see the module doc.
+ */
+export function resolveReceiverType(
+  expr: ParsedExpr,
+  meta: EvidenceMetadata,
+  bindings: ReadonlyMap<string, TypeInfo | null>,
+): TypeInfo | null {
+  if (expr.kind === 'identifier') {
+    if (bindings.has(expr.name)) return stripUnion(bindings.get(expr.name) ?? null)
+    if (meta.propsObjectName !== null) {
+      // Object-props mode: props are only reachable through the props object,
+      // so a bare identifier is never a prop — treating every name that
+      // happens to match a propsType field as one would misattribute module
+      // consts / imports that share a field's name.
+      return expr.name === meta.propsObjectName ? stripUnion(meta.propsType) : null
+    }
+    // Destructured mode: only a declared param binding is a prop (membership
+    // via propsParams, which carries LOCAL names — including rename targets).
+    // The TYPE must come from propsType.properties keyed by the SOURCE prop
+    // name: propsParams' own `type` degrades to `unknown` for non-primitive
+    // props (`collectMemberTypes`' primitives-only gate).
+    const param = meta.propsParams.find((p) => p.name === expr.name && !p.isRest)
+    if (!param) return null
+    return lookupProperty(meta.propsType, param.sourceName ?? param.name, meta)
+  }
+  if (expr.kind === 'member' && !expr.computed) {
+    const objType = resolveReceiverType(expr.object, meta, bindings)
+    return lookupProperty(objType, expr.property, meta)
+  }
+  return null
+}