@contember/bindx-react 0.1.57 → 0.1.59

package/src/hooks/useRootSelection.ts

@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useRef, type ReactNode } from 'react'
+import { buildQueryFromSelection } from '@contember/bindx'
+import type { EntityAccessor } from '../jsx/types.js'
+import { useSchemaRegistry } from './BackendAdapterContext.js'
+import { useSelectionCollection, type SelectionCollectionResult } from './useSelectionCollection.js'
+import { COMPILED_ROOT_KEY, resolveCompiledRootSelection, type CompiledSelection } from '../jsx/compiledSelection.js'
+import { isValidCompiledSelection } from '../jsx/compiledSelectionShape.js'
+import { isCompiledSelectionsEnabled, isStaticSelectionValidationEnabled, validateCompiledRootSelection } from '../jsx/componentFactory.js'
+
+/**
+ * Params for {@link useRootSelection}.
+ */
+export interface UseRootSelectionParams {
+	readonly entityType: string
+	readonly depsKey: string
+	readonly children: (entity: EntityAccessor<unknown>) => ReactNode
+	/** Compiler-injected root selection. Absent ⇒ the runtime children walk runs. */
+	readonly compiledSelection?: CompiledSelection
+}
+
+/**
+ * Root selection for <Entity>. With a compiled selection the root SelectionMeta is
+ * built statically and `children` is NEVER invoked with a collector; without it the
+ * runtime children-collector walk runs as before. Validate mode additionally runs
+ * the walk (contained) and diffs it against the compiled root for under-fetches.
+ */
+export function useRootSelection(params: UseRootSelectionParams): SelectionCollectionResult {
+	const { entityType, depsKey, children, compiledSelection } = params
+	const schemaRegistry = useSchemaRegistry()
+	const validateMode = isStaticSelectionValidationEnabled()
+	const compiledEnabled = isCompiledSelectionsEnabled()
+	// Same query ⇒ same result object, so consumers keyed on the selection keep their handles.
+	const compiledCacheRef = useRef<SelectionCollectionResult | null>(null)
+
+	// Compiled root selection — present ⇒ skip the children(collector) walk (unless validating).
+	// Killswitch off or a malformed/throwing literal yields null ⇒ the runtime walk runs. Decided
+	// INSIDE the memo so the hook sequence below stays identical across the compiled/uncompiled path.
+	const compiledResult = useMemo((): SelectionCollectionResult | null => {
+		if (!compiledSelection || !compiledEnabled) {
+			return null
+		}
+		if (!isValidCompiledSelection(compiledSelection, [COMPILED_ROOT_KEY])) {
+			console.warn(
+				`[bindx] compiled selection for <Entity ${entityType}> is malformed (version/shape check failed) — `
+				+ 'falling back to the runtime children walk.',
+			)
+			return null
+		}
+		try {
+			const selection = resolveCompiledRootSelection({
+				compiled: compiledSelection,
+				entityType,
+				schemaRegistry,
+				validateMode,
+			})
+			const queryKey = JSON.stringify(buildQueryFromSelection(selection))
+			const cached = compiledCacheRef.current
+			if (cached && cached.queryKey === queryKey) {
+				return cached
+			}
+			const result = { selection, queryKey }
+			compiledCacheRef.current = result
+			return result
+		} catch (error) {
+			console.warn(
+				`[bindx] compiled selection for <Entity ${entityType}> failed to resolve — `
+				+ 'falling back to the runtime children walk.',
+				error,
+			)
+			return null
+		}
+	}, [compiledSelection, compiledEnabled, entityType, schemaRegistry, validateMode])
+
+	// Runtime walk. Its collect no-ops when compiled & not validating, so children is
+	// never called with a collector. In validate mode the walk runs to feed the diff;
+	// a crash there is contained so it cannot break the compiled path.
+	// The skip is part of the memo key: leaving the compiled path after mount (killswitch,
+	// prop dropped) must re-run the walk instead of reusing the empty skipped result.
+	const isWalkSkipped = compiledResult !== null && !validateMode
+	const runtimeResult = useSelectionCollection({
+		entityType,
+		depsKey: isWalkSkipped ? `${depsKey}::compiled` : depsKey,
+		collect: collector => {
+			if (isWalkSkipped) {
+				return null
+			}
+			try {
+				return children(collector as EntityAccessor<unknown>)
+			} catch (error) {
+				if (!compiledResult) {
+					throw error
+				}
+				console.error(
+					`[bindx] validate-mode children walk of <Entity ${entityType}> crashed — `
+					+ 'under-fetch diff skipped; the compiled selection still stands.',
+					error,
+				)
+				return null
+			}
+		},
+	})
+
+	// Validate mode: warn on fields the runtime walk requests but the compiled root omits.
+	useEffect(() => {
+		if (compiledResult && validateMode) {
+			validateCompiledRootSelection(compiledResult.selection, runtimeResult.selection, entityType)
+		}
+	}, [compiledResult, runtimeResult, validateMode, entityType])
+
+	return compiledResult ?? runtimeResult
+}

package/src/index.ts

@@ -37,6 +37,9 @@ export type {
 	FluentDefiner,
 	HasManyOptions,
 	InferSelection,
+	// Static (precompiled) selection
+	StaticFieldMap,
+	StaticFieldNode,
 	QuerySpec,
 	QueryFieldSpec,
 	// Query types (typed filter/orderBy)
@@ -274,6 +277,9 @@ export type {
 	BuildProps,
 	BuildFragmentProps,
 	InitialBuilderState,
+	// Compiled selection contract (v2)
+	CompiledSelection,
+	CompiledHole,
 } from './jsx/index.js'
 
 // ============================================================================
@@ -356,6 +362,11 @@ export {
 	// Component (unified API)
 	createComponent,
 	withCollector,
+	COLLECTOR_CONTRACT,
+	itemOf,
+	entityOf,
+	type CallbackContract,
+	type CollectorContract,
 	isBindxComponent,
 	mergeFragments,
 	COMPONENT_MARKER,
@@ -365,6 +376,8 @@ export {
 	getComponentBrand,
 	setBrandValidation,
 	validateBrand,
+	setStaticSelectionValidation,
+	setCompiledSelectionsEnabled,
 } from './jsx/index.js'
 
 // Entity Scope

package/src/jsx/analyzer.ts

@@ -113,13 +113,21 @@ export function analyzeJsx(node: ReactNode, selection: SelectionMetaCollector):
 	}
 }
 
+/**
+ * Resolves a human-readable name for a component for error/warn attribution,
+ * falling back to 'anonymous' when nothing usable is present.
+ */
+export function resolveComponentName(component: unknown): string {
+	const c = component as { displayName?: string; name?: string; type?: { displayName?: string; name?: string } }
+	return c.displayName ?? c.type?.displayName ?? (c.name || c.type?.name) ?? 'anonymous'
+}
+
 /**
  * Reports a selection-analysis failure of a single component with attribution,
  * so one broken component doesn't silently cost its siblings their selection.
  */
 function reportAnalysisError(component: unknown, error: unknown): void {
-	const c = component as { displayName?: string; name?: string; type?: { displayName?: string; name?: string } }
-	const name = c.displayName ?? c.type?.displayName ?? (c.name || c.type?.name) ?? 'anonymous'
+	const name = resolveComponentName(component)
 	console.error(
 		`[bindx] Selection analysis of <${name}> failed — its fields were NOT added to the fetch plan. `
 		+ 'Fix the error below; fields it uses may be missing from queries until then.',

package/src/jsx/collectionHelpers.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared building blocks for the selection collection pass — used by both the
+ * runtime proxy collector (componentFactory) and compiled-selection/hole
+ * resolution (compiledSelection). Extracted to keep a clean module boundary
+ * and avoid a cycle between those two.
+ */
+import type { FluentFragment, SelectionMeta, AnyBrand } from '@contember/bindx'
+import { ComponentBrand } from '@contember/bindx'
+
+/**
+ * Creates a FluentFragment from selection metadata.
+ */
+export function createFragment(
+	selection: SelectionMeta,
+	componentBrand: ComponentBrand,
+	roles: readonly string[],
+): FluentFragment<unknown, object, AnyBrand> {
+	return {
+		__meta: selection,
+		__resultType: {} as object,
+		__modelType: undefined as unknown,
+		__isFragment: true,
+		__brand: componentBrand,
+		__brands: new Set([componentBrand.brandSymbol]),
+		__roles: roles.length > 0 ? roles : undefined,
+	}
+}
+
+/**
+ * Creates a tolerant stand-in for scalar (non-entity) props during collection.
+ * Render bodies may call it (`t('key')`), read nested properties
+ * (`labels.heading`) or coerce it to a primitive — all are no-ops so the
+ * collection pass keeps capturing entity field accesses (see issue #57).
+ */
+export function createScalarPropMock(): unknown {
+	const mock: unknown = new Proxy(function () {}, {
+		get(_target, prop): unknown {
+			if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+				return (): string => ''
+			}
+			if (prop === Symbol.iterator) {
+				return function* (): Generator<never> {}
+			}
+			// undefined keeps JSON.stringify from recursing via a callable toJSON
+			if (prop === 'toJSON') {
+				return undefined
+			}
+			return mock
+		},
+		apply(): unknown {
+			return mock
+		},
+	})
+	return mock
+}

package/src/jsx/collectorContract.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from 'react'
+import type { EntityRef, HasManyRef, HasOneRef } from './types.js'
+import { HasMany } from './components/HasMany.js'
+import { HasOne } from './components/HasOne.js'
+
+/**
+ * Declares how a callback prop is invoked, so the analyzer can treat it like a HasMany/HasOne child.
+ * Source of truth: the build-time compiler imports these types (see
+ * packages/bindx-compiler/src/contracts.ts) to parse what this module derives.
+ */
+export interface CallbackContract {
+	readonly kind: 'itemOf' | 'entityOf'
+	readonly field: string
+}
+
+/** Maps a callback prop name (`children` included) to the relation it is invoked over. */
+export type CollectorContract = Record<string, CallbackContract>
+
+/** Symbol under which a contract is attached to a component for introspection. */
+export const COLLECTOR_CONTRACT: unique symbol = Symbol('bindx.collectorContract')
+
+/** Callback prop `field` receives each item of the has-many relation prop `field`. */
+export function itemOf(field: string): CallbackContract {
+	return { kind: 'itemOf', field }
+}
+
+/** Callback prop `field` receives the entity of the has-one relation prop `field`. */
+export function entityOf(field: string): CallbackContract {
+	return { kind: 'entityOf', field }
+}
+
+type RelationCallback = (value: EntityRef<unknown>, index?: number) => ReactNode
+
+// Collection-boundary narrowing only: props here are collector proxies, so the ref predicates
+// check object-ness, not ref shape; a wrong prop is caught by HasMany/HasOne collection itself.
+function isRelationCallback(value: unknown): value is RelationCallback {
+	return typeof value === 'function'
+}
+
+function isHasManyRef(value: unknown): value is HasManyRef<unknown> {
+	return typeof value === 'object' && value !== null
+}
+
+function isHasOneRef(value: unknown): value is HasOneRef<unknown> {
+	return typeof value === 'object' && value !== null
+}
+
+/**
+ * Derives a staticRender from a contract: one `<HasMany>`/`<HasOne>` per entry, replaying
+ * the callback prop as its child. A missing callback still registers the relation with no
+ * nested selection — mirroring HasMany/HasOne when their children collect nothing.
+ */
+export function deriveContractStaticRender(contract: CollectorContract): (props: Record<string, unknown>) => ReactNode {
+	const entries = Object.entries(contract)
+	return (props: Record<string, unknown>): ReactNode => (
+		<>
+			{entries.map(([callbackName, { kind, field }]) => {
+				const fieldValue = props[field]
+				const callbackValue = props[callbackName]
+				const child = isRelationCallback(callbackValue) ? callbackValue : (): ReactNode => null
+
+				if (kind === 'itemOf') {
+					if (!isHasManyRef(fieldValue)) return null
+					return <HasMany key={callbackName} field={fieldValue}>{(item, index) => child(item, index)}</HasMany>
+				}
+				if (!isHasOneRef(fieldValue)) return null
+				return <HasOne key={callbackName} field={fieldValue}>{entity => child(entity)}</HasOne>
+			})}
+		</>
+	)
+}

package/src/jsx/collectorProxy.ts

@@ -12,7 +12,7 @@ import {
 	FIELD_REF_META,
 	SCOPE_REF,
 } from './types.js'
-import { wrapEntityRefWithFieldAccessProxy } from './proxyShared.js'
+import { wrapEntityRefWithFieldAccessProxy, REACT_ELEMENT_PROBE_KEYS } from './proxyShared.js'
 
 /**
  * Combined ref type for collector that satisfies all accessor interfaces.
@@ -300,6 +300,12 @@ function wrapCollectorRefWithFieldAccessProxy(
 				return Reflect.get(target, prop)
 			}
 
+			// React element probes (e.g. `{article.title}` rendered directly as a
+			// child) must not upgrade this scalar ref to a relation.
+			if (REACT_ELEMENT_PROBE_KEYS.has(prop)) {
+				return Reflect.get(target, prop)
+			}
+
 			if (isHasOneRelation) {
 				// For has-one relations, match runtime EntityHandle proxy behavior:
 				// Only pass through id, $-prefixed, and __-prefixed properties.

package/src/jsx/compiledSelection.ts

@@ -0,0 +1,353 @@
+/**
+ * Compiled-selection contract (v2) and its runtime resolution.
+ *
+ * The selection compiler emits a {@link CompiledSelection} as the 2nd argument
+ * of `.render()`. Phase 1 covered per-prop static field maps; phase 2 adds
+ * `holes` — statically-emitted references to nested components that received
+ * entity-derived values. Holes are resolved here at collection time through the
+ * target's existing runtime selection surface (`getSelection` / `staticRender`),
+ * the Relay-fragment-spread equivalent, WITHOUT executing the host render body.
+ *
+ * Phase 2.1 adds {@link CompiledHole.extraProps}: non-entity values (module-scope
+ * bindings, render-scope-free closures) lifted into the hole so a target that
+ * invokes them during collection stays oracle-equal — see docs/compiler-plan.md.
+ */
+import type { ReactNode } from 'react'
+import type { SelectionMeta, StaticSelectionSchema } from '@contember/bindx'
+import { SchemaRegistry, SelectionScope, ComponentBrand, driveSelectionScope } from '@contember/bindx'
+import { SelectionMetaCollector, mergeSelections } from './SelectionMeta.js'
+import type { StaticFieldMap } from '@contember/bindx'
+import { createCollectorProxy } from './proxy.js'
+import { collectSelection, resolveComponentName } from './analyzer.js'
+import { createFragment, createScalarPropMock } from './collectionHelpers.js'
+import type { SelectionPropMeta } from './componentBuilder.types.js'
+import type { SelectionProvider } from './types.js'
+import type { EntityConfig } from './componentFactory.js'
+
+// ============================================================================
+// Contract v2
+// ============================================================================
+
+/**
+ * Precompiled selection injected by the selection compiler. Breaking-change
+ * shape within the experiment — hand-write only in tests that simulate emit.
+ */
+export interface CompiledSelection {
+	/** Contract version marker — the runtime falls back to the proxy pass unless this is exactly 2. */
+	v: 2
+	/** Per implicit entity prop — same {@link StaticFieldMap} as phase 1. */
+	props: Record<string, StaticFieldMap>
+	/** Nested components that received entity-derived values. */
+	holes?: CompiledHole[]
+}
+
+/**
+ * A nested component composition the compiler could not inline statically.
+ * Resolved at collection time through the target's selection surface.
+ */
+export interface CompiledHole {
+	/**
+	 * Thunk, not a direct reference — dodges TDZ for components defined later in
+	 * the module (same reason runtime collection is lazy).
+	 */
+	component: () => unknown
+	/**
+	 * Target prop name → where its value comes from: a host entity prop plus a
+	 * member path. Empty path = the root entity prop itself.
+	 */
+	entityProps: Record<string, { source: string; path: readonly string[] }>
+	/**
+	 * Statically-literal non-entity props of the JSX element. Non-literal
+	 * non-entity props are simply omitted.
+	 */
+	literalProps?: Record<string, unknown>
+	/**
+	 * Non-entity props lifted verbatim from the emit site: module-scope values
+	 * (imports / top-level bindings) and render-scope-free inline closures. Each
+	 * is a thunk (TDZ-safe, same reason as {@link component}) resolved to the real
+	 * value at collection time, so a target's `staticRender` that *invokes* one
+	 * (e.g. `props.children(entity)`) collects the same fields the oracle would.
+	 */
+	extraProps?: Record<string, () => unknown>
+}
+
+// ============================================================================
+// Runtime resolution
+// ============================================================================
+
+export interface ApplyCompiledSelectionParams {
+	readonly compiled: CompiledSelection
+	readonly selectionsMap: Map<string, SelectionPropMeta>
+	readonly componentBrand: ComponentBrand
+	readonly roles: readonly string[]
+	readonly implicitConfigs: [string, EntityConfig][]
+	readonly schemaRegistry: SchemaRegistry<Record<string, object>> | null
+	readonly componentDisplayName: string
+	readonly validateMode: boolean
+}
+
+/**
+ * Builds `selectionsMap` entries from a compiled selection — resolving the
+ * per-prop SelectionMeta (fields + holes) then wrapping each in a fragment.
+ * Replaces the proxy pass entirely; the host render function is never executed.
+ */
+export function applyCompiledSelection(params: ApplyCompiledSelectionParams): void {
+	const { selectionsMap, componentBrand, roles } = params
+	// Like the proxy pass, a component keeps only what reached its scopes (returned fields are dropped).
+	const { metas } = resolveCompiledSelection({
+		compiled: params.compiled,
+		implicitConfigs: params.implicitConfigs,
+		schemaRegistry: params.schemaRegistry,
+		componentDisplayName: params.componentDisplayName,
+		validateMode: params.validateMode,
+	})
+	for (const [propName, selection] of metas) {
+		selectionsMap.set(propName, {
+			selection,
+			fragment: createFragment(selection, componentBrand, roles),
+		})
+	}
+}
+
+interface ResolveCompiledSelectionParams {
+	readonly compiled: CompiledSelection
+	readonly implicitConfigs: readonly [string, EntityConfig][]
+	readonly schemaRegistry: SchemaRegistry<Record<string, object>> | null
+	readonly componentDisplayName: string
+	readonly validateMode: boolean
+}
+
+interface ResolvedCompiledSelection {
+	/** Snapshotted selection per entity prop that captured fields. */
+	readonly metas: Map<string, SelectionMeta>
+	/** What hole targets returned instead of writing into a scope (kept by the <Entity> root walk only). */
+	readonly returned: SelectionMeta
+}
+
+/**
+ * Core resolution shared by createComponent (fragments) and <Entity> (root
+ * selection): seeds one live scope per entity prop from the static field maps,
+ * resolves every hole into the matching scope, and snapshots them. The host render fn
+ * is never run. Throws on a broken literal (missing hole component, throwing thunk) so
+ * the caller falls back to the proxy pass instead of under-fetching.
+ */
+function resolveCompiledSelection(params: ResolveCompiledSelectionParams): ResolvedCompiledSelection {
+	const { compiled } = params
+	const propScopes = new Map<string, SelectionScope>()
+
+	const scopeFor = (propName: string): SelectionScope => {
+		let scope = propScopes.get(propName)
+		if (!scope) {
+			scope = new SelectionScope()
+			propScopes.set(propName, scope)
+		}
+		return scope
+	}
+
+	const ctx: HoleResolutionContext = {
+		scopeFor,
+		implicitConfigsMap: new Map(params.implicitConfigs),
+		schemaRegistry: params.schemaRegistry,
+		componentDisplayName: params.componentDisplayName,
+		validateMode: params.validateMode,
+	}
+
+	// 1. Seed a live (open) scope per entity prop from the static field maps.
+	for (const [propName, fieldMap] of Object.entries(compiled.props)) {
+		driveSelectionScope(scopeFor(propName), fieldMap, schemaFor(propName, ctx))
+	}
+
+	// 2. Resolve each hole into the same scopes (fragment-spread equivalent).
+	const returned = new SelectionMetaCollector()
+	for (const hole of compiled.holes ?? []) {
+		resolveHole(hole, ctx, returned)
+	}
+
+	// 3. Snapshot every scope that captured fields.
+	const metas = new Map<string, SelectionMeta>()
+	for (const [propName, scope] of propScopes) {
+		if (scope.hasFields()) {
+			metas.set(propName, scope.toSelectionMeta())
+		}
+	}
+	return { metas, returned }
+}
+
+/** Fixed key under which <Entity> stores its compiled root field map + hole sources. */
+export const COMPILED_ROOT_KEY = 'entity'
+
+export interface ResolveCompiledRootSelectionParams {
+	readonly compiled: CompiledSelection
+	readonly entityType: string
+	readonly schemaRegistry: SchemaRegistry<Record<string, object>> | null
+	readonly validateMode: boolean
+}
+
+/**
+ * Builds the single root SelectionMeta for a compiled <Entity>: fields under the
+ * fixed `entity` key plus every hole (all rooted at `entity`). No fragments —
+ * <Entity> is a selection root, not a composable component.
+ */
+export function resolveCompiledRootSelection(params: ResolveCompiledRootSelectionParams): SelectionMeta {
+	const { metas, returned } = resolveCompiledSelection({
+		compiled: params.compiled,
+		implicitConfigs: [[COMPILED_ROOT_KEY, { entityName: params.entityType }]],
+		schemaRegistry: params.schemaRegistry,
+		componentDisplayName: `Entity(${params.entityType})`,
+		validateMode: params.validateMode,
+	})
+	const selection = metas.get(COMPILED_ROOT_KEY) ?? { fields: new Map() }
+	// The runtime root walk merges what its JSX components return (e.g. an uploader's nested fields).
+	mergeSelections(selection, returned)
+	return selection
+}
+
+interface HoleResolutionContext {
+	readonly scopeFor: (propName: string) => SelectionScope
+	readonly implicitConfigsMap: Map<string, EntityConfig>
+	readonly schemaRegistry: SchemaRegistry<Record<string, object>> | null
+	readonly componentDisplayName: string
+	readonly validateMode: boolean
+}
+
+/**
+ * Resolves one hole: assembles the target's props (entity values replayed from
+ * the source scopes + literal props) and feeds them to its selection surface,
+ * mirroring `analyzeJsx` order. A broken literal throws; an error inside the
+ * target's own surface is contained, as in the proxy pass.
+ */
+function resolveHole(hole: CompiledHole, ctx: HoleResolutionContext, returned: SelectionMetaCollector): void {
+	const target = hole.component()
+	if (target === null || (typeof target !== 'object' && typeof target !== 'function')) {
+		throw new Error(`hole component thunk returned ${String(target)} (stale compiled selection?)`)
+	}
+	const props = assembleHoleProps(hole, ctx)
+
+	try {
+		if (hasGetSelection(target)) {
+			// Entity values carry SCOPE_REF, so most targets merge into the source scopes as a side
+			// effect; some only return their fields.
+			addReturnedFields(returned, target.getSelection(props, collectNested))
+		} else if (hasStaticRender(target)) {
+			const jsx = target.staticRender(wrapPropsWithScalarFallback(props))
+			if (jsx !== null && jsx !== undefined) {
+				mergeSelections(returned, collectSelection(jsx))
+			}
+		} else if (ctx.validateMode) {
+			// Plain React target: the runtime proxy pass is equally blind here, so
+			// compiled behavior stays equivalent — surface the blind spot in dev/CI.
+			console.warn(
+				`[bindx] <${resolveComponentName(target)}> inside <${ctx.componentDisplayName}> exposes no `
+				+ 'selection surface (getSelection/staticRender) — its fields are a selection blind spot.',
+			)
+		}
+	} catch (error) {
+		reportHoleError(target, ctx.componentDisplayName, error)
+	}
+}
+
+/** Adds a `getSelection` result the way `analyzeJsx` does. */
+function addReturnedFields(returned: SelectionMetaCollector, result: ReturnType<SelectionProvider['getSelection']>): void {
+	if (!result) {
+		return
+	}
+	for (const field of Array.isArray(result) ? result : [result]) {
+		returned.addField(field)
+	}
+}
+
+/** Real nested-collection walk for `getSelection` targets. */
+function collectNested(node: ReactNode): SelectionMeta {
+	return collectSelection(node)
+}
+
+/**
+ * Assembles the target's props: each entity prop is the source prop's collector
+ * proxy with the member path replayed via property gets; literal props merge in.
+ */
+function assembleHoleProps(hole: CompiledHole, ctx: HoleResolutionContext): Record<string, unknown> {
+	const props: Record<string, unknown> = { ...hole.literalProps }
+	// Lifted values reach the target before entity proxies (which must win on collision).
+	for (const [prop, thunk] of Object.entries(hole.extraProps ?? {})) {
+		props[prop] = thunk()
+	}
+	for (const [targetProp, origin] of Object.entries(hole.entityProps)) {
+		const proxy = createSourceProxy(origin.source, ctx)
+		props[targetProp] = replayPath(proxy, origin.path)
+	}
+	return props
+}
+
+/**
+ * Creates the collector proxy for a source entity prop, using the same scope +
+ * entity-name + schema config that the proxy pass uses for that prop.
+ */
+function createSourceProxy(sourceProp: string, ctx: HoleResolutionContext): unknown {
+	const { entityName, schemaRegistry } = schemaFor(sourceProp, ctx)
+	return createCollectorProxy(ctx.scopeFor(sourceProp), entityName, schemaRegistry)
+}
+
+/** The entity name + schema the proxy pass would collect an entity prop with. */
+function schemaFor(propName: string, ctx: HoleResolutionContext): StaticSelectionSchema {
+	const config = ctx.implicitConfigsMap.get(propName)
+	return {
+		entityName: config?.entityName ?? null,
+		schemaRegistry: config?.schema ? new SchemaRegistry(config.schema) : ctx.schemaRegistry,
+	}
+}
+
+/** Replays a member path via property gets — identical to the proxy pass. */
+function replayPath(root: unknown, path: readonly string[]): unknown {
+	let current = root
+	for (const key of path) {
+		if (current === null || (typeof current !== 'object' && typeof current !== 'function')) {
+			return current
+		}
+		current = Reflect.get(current, key)
+	}
+	return current
+}
+
+/**
+ * Wraps a staticRender target's props so unknown keys fall back to the tolerant
+ * scalar mock (holes carry no children/render-prop closures).
+ */
+function wrapPropsWithScalarFallback(props: Record<string, unknown>): Record<string, unknown> {
+	return new Proxy(props, {
+		get(target, key): unknown {
+			if (typeof key === 'symbol' || Object.hasOwn(target, key)) {
+				return Reflect.get(target, key)
+			}
+			return createScalarPropMock()
+		},
+	})
+}
+
+interface GetSelectionSurface {
+	getSelection(props: Record<string, unknown>, collectNested: (node: ReactNode) => SelectionMeta): ReturnType<SelectionProvider['getSelection']>
+}
+
+interface StaticRenderSurface {
+	staticRender(props: Record<string, unknown>): ReactNode
+}
+
+function hasGetSelection(target: object): target is GetSelectionSurface {
+	return 'getSelection' in target && typeof target.getSelection === 'function'
+}
+
+function hasStaticRender(target: object): target is StaticRenderSurface {
+	return 'staticRender' in target && typeof target.staticRender === 'function'
+}
+
+/**
+ * Reports a hole-resolution failure with attribution, matching the
+ * report-and-continue policy of `analyzeJsx`'s per-component error handling.
+ */
+function reportHoleError(target: unknown, hostName: string, error: unknown): void {
+	const name = resolveComponentName(target)
+	console.error(
+		`[bindx] Hole resolution of <${name}> inside <${hostName}> failed — its fields were NOT added to the fetch plan. `
+		+ 'Fix the error below; fields it uses may be missing from queries until then.',
+		error,
+	)
+}