@contember/bindx-react 0.1.57 → 0.1.59

package/src/jsx/compiledSelectionShape.ts

@@ -0,0 +1,86 @@
+/**
+ * Runtime shape check for a compiler-emitted {@link CompiledSelection} literal.
+ * A stale or corrupt literal must never be half-read into the fetch plan —
+ * consumers fall back to the runtime proxy pass when this check fails.
+ */
+import type { CompiledSelection } from './compiledSelection.js'
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStringArray(value: unknown): boolean {
+	return Array.isArray(value) && value.every(item => typeof item === 'string')
+}
+
+function isValidFieldMap(value: unknown): boolean {
+	return isPlainObject(value) && Object.values(value).every(isValidFieldNode)
+}
+
+function isValidOptionalFieldMap(value: unknown): boolean {
+	return value === undefined || isValidFieldMap(value)
+}
+
+/** Only known keys: a literal from a newer emitter that still says `v: 2` must not be half-read. */
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+	return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function isValidFieldNode(node: unknown): boolean {
+	if (node === true) {
+		return true
+	}
+	if (!isPlainObject(node) || !hasOnlyKeys(node, ['fields', 'hasOneFields', 'many', 'assumesNotHasOne'])) {
+		return false
+	}
+	if (node['fields'] === undefined && node['hasOneFields'] === undefined && node['assumesNotHasOne'] === undefined) {
+		return false
+	}
+	return isValidOptionalFieldMap(node['fields'])
+		&& isValidOptionalFieldMap(node['hasOneFields'])
+		&& (node['many'] === undefined || node['many'] === true)
+		&& (node['assumesNotHasOne'] === undefined || node['assumesNotHasOne'] === true)
+}
+
+function isValidThunkMap(value: unknown): boolean {
+	return value === undefined
+		|| (isPlainObject(value) && Object.values(value).every(thunk => typeof thunk === 'function'))
+}
+
+function isValidHole(hole: unknown, entityPropNames: readonly string[]): boolean {
+	if (!isPlainObject(hole) || !hasOnlyKeys(hole, ['component', 'entityProps', 'literalProps', 'extraProps'])) {
+		return false
+	}
+	if (typeof hole['component'] !== 'function' || !isPlainObject(hole['entityProps'])) {
+		return false
+	}
+	const hasValidOrigins = Object.values(hole['entityProps']).every(origin =>
+		isPlainObject(origin)
+		&& hasOnlyKeys(origin, ['source', 'path'])
+		&& typeof origin['source'] === 'string'
+		&& entityPropNames.includes(origin['source'])
+		&& isStringArray(origin['path']),
+	)
+	return hasValidOrigins
+		&& (hole['literalProps'] === undefined || isPlainObject(hole['literalProps']))
+		&& isValidThunkMap(hole['extraProps'])
+}
+
+/**
+ * True when `value` is a v2 literal whose field maps and holes are well-formed and
+ * reference only `entityPropNames` (the host's implicit entity props; `['entity']` for <Entity>).
+ */
+export function isValidCompiledSelection(
+	value: unknown,
+	entityPropNames: readonly string[],
+): value is CompiledSelection {
+	if (!isPlainObject(value) || !hasOnlyKeys(value, ['v', 'props', 'holes']) || value['v'] !== 2 || !isPlainObject(value['props'])) {
+		return false
+	}
+	const hasValidProps = Object.entries(value['props']).every(([propName, fieldMap]) =>
+		entityPropNames.includes(propName) && isValidFieldMap(fieldMap),
+	)
+	const holes = value['holes']
+	return hasValidProps
+		&& (holes === undefined || (Array.isArray(holes) && holes.every(hole => isValidHole(hole, entityPropNames))))
+}

package/src/jsx/componentBuilder.ts

@@ -19,6 +19,7 @@ import type {
 	ComponentBuilderState,
 	CreateComponentOptions,
 } from './componentBuilder.types.js'
+import type { CompiledSelection } from './compiledSelection.js'
 export type { SelectionPropMeta } from './componentBuilder.types.js'
 import type { Condition } from './conditions.js'
 import { buildComponent, type EntityConfig } from './componentFactory.js'
@@ -50,6 +51,7 @@ export class ComponentBuilderImpl<
 		private readonly conditionFn: ((props: Record<string, unknown>) => Condition) | null = null,
 		private readonly slotNames: readonly string[] = ['children'],
 		private readonly useFns: readonly ((props: Record<string, unknown>) => object)[] = [],
+		private readonly mockValues: Record<string, unknown> = {},
 	) {}
 
 	entity(
@@ -69,6 +71,7 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			this.slotNames,
 			this.useFns,
+			this.mockValues,
 		)
 	}
 
@@ -99,6 +102,7 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			this.slotNames,
 			this.useFns,
+			this.mockValues,
 		)
 	}
 
@@ -112,6 +116,7 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			this.slotNames,
 			this.useFns,
+			this.mockValues,
 		)
 	}
 
@@ -124,6 +129,21 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			this.slotNames,
 			[...this.useFns, useFn],
+			this.mockValues,
+		)
+	}
+
+	mock(values: Record<string, unknown>): ComponentBuilderImpl<TState> {
+		// Later calls merge over earlier ones
+		return new ComponentBuilderImpl(
+			this.schemaRegistry,
+			this.entityConfigs,
+			this.roles,
+			this.hasInterfacesMode,
+			this.conditionFn,
+			this.slotNames,
+			this.useFns,
+			{ ...this.mockValues, ...values },
 		)
 	}
 
@@ -136,6 +156,7 @@ export class ComponentBuilderImpl<
 			conditionFn,
 			this.slotNames,
 			this.useFns,
+			this.mockValues,
 		)
 	}
 
@@ -148,10 +169,14 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			names,
 			this.useFns,
+			this.mockValues,
 		)
 	}
 
-	render(renderFn: (props: Record<string, unknown>) => ReactNode): unknown {
+	render(
+		renderFn: (props: Record<string, unknown>) => ReactNode,
+		compiled?: CompiledSelection,
+	): unknown {
 		return buildComponent(
 			this.entityConfigs,
 			this.roles,
@@ -161,6 +186,8 @@ export class ComponentBuilderImpl<
 			this.conditionFn,
 			this.slotNames,
 			this.useFns,
+			this.mockValues,
+			compiled ?? null,
 		)
 	}
 }

package/src/jsx/componentBuilder.types.ts

@@ -19,6 +19,7 @@ import type {
 } from '@contember/bindx'
 import type { SelectionProvider } from './types.js'
 import type { Condition } from './conditions.js'
+import type { CompiledSelection } from './compiledSelection.js'
 
 // ============================================================================
 // Symbols (re-exported from createComponent.ts)
@@ -480,6 +481,34 @@ export interface ComponentBuilder<
 		useFn: (props: BuildRenderProps<TState>) => TUse,
 	): ComponentBuilder<AddUseProps<TState, TUse>>
 
+	/**
+	 * Supply deterministic stand-in values for scalar / `.use()` props used
+	 * EXCLUSIVELY during static selection analysis — never at runtime render,
+	 * where real props and real `.use()` outputs always win.
+	 *
+	 * The generic tolerant stand-in survives most code but under-collects when a
+	 * mocked value drives control flow: indexing a real object with a mocked key
+	 * (`LABELS[key].x` crashes), branching on a scalar (nondeterministic branch),
+	 * or `.map()` over a scalar array (callback never runs, so entity fields
+	 * accessed inside it are silently missed). A concrete mock fixes all three.
+	 *
+	 * Later calls merge over earlier ones. Entity props cannot be mocked (type error).
+	 * Does not change the builder state type.
+	 *
+	 * @example
+	 * ```typescript
+	 * createComponent()
+	 *   .entity('article', schema.Article)
+	 *   .props<{ labelKey: string; tabs: { key: string }[] }>()
+	 *   .use(() => ({ t: useTranslator() }))
+	 *   .mock({ labelKey: 'k1', tabs: [{ key: 'x' }], t: key => key })
+	 *   .render(({ article, labelKey, tabs, t }) => ...)
+	 * ```
+	 */
+	mock(
+		values: Partial<Omit<BuildRenderProps<TState>, keyof TState['__entityProps']>>,
+	): ComponentBuilder<TState>
+
 	/**
 	 * Add a condition that must be true for the component to render.
 	 * If the condition is false, the component renders null.
@@ -531,9 +560,17 @@ export interface ComponentBuilder<
 	 * Build the component with the render function.
 	 *
 	 * @param renderFn - React render function receiving typed props
+	 * @param compiled - Precompiled selection injected by the selection compiler
+	 *   (per-prop static field maps + nested-component holes). Compiler-facing
+	 *   only — do NOT hand-write it. When present, the runtime skips the proxy
+	 *   collection pass and uses this instead; enable
+	 *   {@link setStaticSelectionValidation} in dev/CI to cross-check it.
 	 * @returns Bindx component with fragment properties
 	 */
-	render(renderFn: (props: BuildRenderProps<TState>) => ReactNode): BindxComponent<TState>
+	render(
+		renderFn: (props: BuildRenderProps<TState>) => ReactNode,
+		compiled?: CompiledSelection,
+	): BindxComponent<TState>
 }
 
 // ============================================================================

package/src/jsx/componentFactory.ts

@@ -31,6 +31,9 @@ import type { SelectionProvider, SelectionFieldMeta } from './types.js'
 import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from './types.js'
 import { createCollectorProxy } from './proxy.js'
 import { collectSelection } from './analyzer.js'
+import { createFragment, createScalarPropMock } from './collectionHelpers.js'
+import { applyCompiledSelection, type CompiledSelection } from './compiledSelection.js'
+import { isValidCompiledSelection } from './compiledSelectionShape.js'
 import { type Condition, evaluateCondition } from './conditions.js'
 import { useRefSubscription } from '../hooks/useFields.js'
 
@@ -53,6 +56,45 @@ export const COMPONENT_BRAND = Symbol('COMPONENT_BRAND')
  */
 export const COMPONENT_SELECTIONS = Symbol('COMPONENT_SELECTIONS')
 
+// ============================================================================
+// Static Selection Validation
+// ============================================================================
+
+/**
+ * When enabled, components carrying a precompiled static selection ALSO run the
+ * runtime proxy pass and warn on any per-prop mismatch. Trust-building mode for
+ * dev/CI; off by default so production skips the proxy pass entirely.
+ */
+let staticSelectionValidationEnabled = false
+
+/**
+ * Enables or disables static-selection validate mode (module-level flag).
+ */
+export function setStaticSelectionValidation(enabled: boolean): void {
+	staticSelectionValidationEnabled = enabled
+}
+
+/** Reads the module-level validate-mode flag (used by <Entity>'s root compilation). */
+export function isStaticSelectionValidationEnabled(): boolean {
+	return staticSelectionValidationEnabled
+}
+
+/** Killswitch: when off, all consumers ignore compiled literals and use the runtime proxy path. */
+let compiledSelectionsEnabled = true
+
+/**
+ * Disables compiled selections at runtime — incident mitigation without a rebuild.
+ * <Entity> roots switch on their next render; a createComponent switches only if not yet collected.
+ */
+export function setCompiledSelectionsEnabled(enabled: boolean): void {
+	compiledSelectionsEnabled = enabled
+}
+
+/** Reads the module-level compiled-selections killswitch (used by both consumers). */
+export function isCompiledSelectionsEnabled(): boolean {
+	return compiledSelectionsEnabled
+}
+
 // ============================================================================
 // Entity Config (Runtime)
 // ============================================================================
@@ -103,6 +145,8 @@ export function buildComponent<TProps extends object>(
 	conditionFn: ((props: TProps) => Condition) | null,
 	slotNames: readonly string[],
 	useFns: readonly ((props: TProps) => object)[],
+	mockValues: Record<string, unknown>,
+	compiled: CompiledSelection | null,
 ): unknown {
 	const selectionsMap = new Map<string, SelectionPropMeta>()
 	const componentDisplayName = `BindxComponent(${[...entityConfigs.keys()].join(', ')})`
@@ -129,11 +173,66 @@ export function buildComponent<TProps extends object>(
 	// Interface props are appended during lazy collection, before the first runtime render.
 	const entityPropNames = [...entityConfigs.keys()]
 
+	// Selector-backed props are the only ones step 1 seeds into selectionsMap; anything
+	// else there came from a collection pass and must not survive a reset.
+	const explicitEntityPropNames = [...entityConfigs.entries()]
+		.filter(([_, c]) => c.selector)
+		.map(([name]) => name)
+
 	// 2. Implicit entities - collect lazily to avoid TDZ errors
 	const implicitConfigs = [...entityConfigs.entries()].filter(([_, c]) => !c.selector)
 	// Tri-state: 'collecting' terminates self-recursive components
 	let collectionState: 'idle' | 'collecting' | 'done' = 'idle'
 
+	// Drops any implicit/hole-derived entries so a partial compiled pass can't leak into the fallback.
+	function resetToExplicitSelections(): void {
+		for (const key of [...selectionsMap.keys()]) {
+			if (!explicitEntityPropNames.includes(key)) {
+				selectionsMap.delete(key)
+			}
+		}
+	}
+
+	// Applies the compiled literal; returns false (⇒ caller falls back to the proxy pass) on a
+	// malformed literal or a top-level throw. Per-hole failures stay contained inside applyCompiledSelection.
+	function tryApplyCompiled(): boolean {
+		if (!isValidCompiledSelection(compiled, implicitConfigs.map(([name]) => name))) {
+			console.warn(
+				`[bindx] compiled selection for <${componentDisplayName}> is malformed (version/shape check failed) — `
+				+ 'falling back to runtime collection.',
+			)
+			return false
+		}
+		try {
+			applyCompiledSelection({
+				compiled,
+				selectionsMap,
+				componentBrand,
+				roles,
+				implicitConfigs,
+				schemaRegistry,
+				componentDisplayName,
+				validateMode: staticSelectionValidationEnabled,
+			})
+		} catch (error) {
+			resetToExplicitSelections()
+			console.warn(
+				`[bindx] compiled selection for <${componentDisplayName}> failed to resolve — `
+				+ 'falling back to runtime collection.',
+				error,
+			)
+			return false
+		}
+		if (staticSelectionValidationEnabled) {
+			validateCompiledSelection(
+				selectionsMap, componentDisplayName,
+				implicitConfigs, renderFn, componentBrand, roles,
+				hasInterfacesMode, schemaRegistry, conditionFn, mockValues,
+			)
+		}
+		return true
+	}
+
 	// Runs only from the static-analysis surface (getSelection, $propName fragment
 	// getters) — never from render. Render bodies stay pure runtime code.
 	function ensureImplicitCollected(): void {
@@ -145,7 +244,13 @@ export function buildComponent<TProps extends object>(
 		}
 		collectionState = 'collecting'
 		try {
-			collectImplicitSelections(implicitConfigs, renderFn, selectionsMap, componentBrand, roles, hasInterfacesMode, schemaRegistry, conditionFn)
+			// Precompiled selection present ⇒ build entries from it, skip the proxy pass.
+			// Killswitch off or a malformed/throwing literal falls back to the proxy pass wholesale (never under-fetch).
+			// Interfaces mode discovers props during the proxy pass; a literal cannot carry them.
+			if (compiled && !hasInterfacesMode && isCompiledSelectionsEnabled() && tryApplyCompiled()) {
+				return
+			}
+			collectImplicitSelections(implicitConfigs, renderFn, selectionsMap, componentBrand, roles, hasInterfacesMode, schemaRegistry, conditionFn, mockValues)
 		} catch (error) {
 			// Analysis is deterministic, so retrying is pointless — degrade loudly
 			// to the fields captured before the throw (scopes record eagerly).
@@ -291,34 +396,6 @@ function createExplicitPropMock(): unknown {
 	})
 }
 
-/**
- * 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).
- */
-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
-}
-
 /**
  * Collects selections from JSX for implicit entity props.
  *
@@ -334,6 +411,7 @@ function collectImplicitSelections<TProps extends object>(
 	hasInterfacesMode: boolean,
 	schemaRegistry: SchemaRegistry<Record<string, object>> | null,
 	conditionFn: ((props: TProps) => Condition) | null,
+	mockValues: Record<string, unknown>,
 ): void {
 	const propScopes = new Map<string, SelectionScope>()
 	const implicitConfigsMap = new Map(implicitConfigs)
@@ -373,6 +451,12 @@ function collectImplicitSelections<TProps extends object>(
 				return createCollectorProxy(scope, entityName, resolvedRegistry)
 			}
 
+			// Deterministic analysis-time value; must win over the interfaces-mode
+			// branch so a mocked scalar is never mistaken for an interface entity prop.
+			if (Object.hasOwn(mockValues, propName)) {
+				return mockValues[propName]
+			}
+
 			// In interfaces mode, any unknown prop could be an interface entity prop
 			// Create or reuse a scope for it and return a collector proxy
 			if (hasInterfacesMode) {
@@ -430,26 +514,112 @@ function collectImplicitSelections<TProps extends object>(
 }
 
 // ============================================================================
-// Fragment Creation
+// Static Selection Application & Validation
 // ============================================================================
 
 /**
- * Creates a FluentFragment from selection metadata.
+ * Validate mode: also run the proxy pass (which resolves nested holes by
+ * rendering them inline) and warn (once) when the compiled selection
+ * under-fetches relative to what runtime collection would produce. Diffs over
+ * the runtime props so hole-derived entity props are covered too.
  */
-function createFragment(
-	selection: SelectionMeta,
+function validateCompiledSelection<TProps extends object>(
+	compiledMap: Map<string, SelectionPropMeta>,
+	componentDisplayName: string,
+	implicitConfigs: [string, EntityConfig][],
+	renderFn: (props: TProps) => ReactNode,
 	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,
+	hasInterfacesMode: boolean,
+	schemaRegistry: SchemaRegistry<Record<string, object>> | null,
+	conditionFn: ((props: TProps) => Condition) | null,
+	mockValues: Record<string, unknown>,
+): void {
+	const runtimeMap = new Map<string, SelectionPropMeta>()
+	try {
+		collectImplicitSelections(implicitConfigs, renderFn, runtimeMap, componentBrand, roles, hasInterfacesMode, schemaRegistry, conditionFn, mockValues)
+	} catch (error) {
+		console.error(
+			`[bindx] validate-mode proxy pass of <${componentDisplayName}> crashed — `
+			+ 'under-fetch diff skipped; the compiled selection still stands.',
+			error,
+		)
+		return
+	}
+
+	const lines: string[] = []
+	for (const propName of runtimeMap.keys()) {
+		const compiledSelectionMeta = compiledMap.get(propName)?.selection
+		const runtimeSelectionMeta = runtimeMap.get(propName)?.selection
+		diffUnderfetchedFields(compiledSelectionMeta, runtimeSelectionMeta, [propName], lines)
+	}
+
+	if (lines.length > 0) {
+		console.warn(
+			`[bindx] static selection under-fetches for <${componentDisplayName}>:\n${lines.join('\n')}`,
+		)
+	}
+}
+
+/**
+ * Validate mode for a compiled <Entity> root: warn (once per collection) on fields
+ * the runtime children-collector walk requests but the compiled root omits. Reuses
+ * the same under-fetch-only diff as createComponent; the warn names the entity type.
+ */
+export function validateCompiledRootSelection(
+	compiledSelection: SelectionMeta,
+	runtimeSelection: SelectionMeta,
+	entityType: string,
+): void {
+	const lines: string[] = []
+	diffUnderfetchedFields(compiledSelection, runtimeSelection, [entityType], lines)
+	if (lines.length > 0) {
+		console.warn(
+			`[bindx] static selection under-fetches for <Entity ${entityType}>:\n${lines.join('\n')}`,
+		)
+	}
+}
+
+/**
+ * Under-fetch diff: warn only for fields the runtime (proxy) selection requests
+ * that the static selection omits — the sole mismatch class that is a fetch bug.
+ * Fields present only in static (branch unions) and params/alias/isArray-only
+ * differences are intentionally NOT reported: the compiler unions all branches
+ * and the runtime never records has-many params in implicit collection. Keyed by
+ * `fieldName` (not alias) so a params-driven alias never reads as a missing field.
+ */
+function diffUnderfetchedFields(
+	staticMeta: SelectionMeta | undefined,
+	runtimeMeta: SelectionMeta | undefined,
+	path: string[],
+	lines: string[],
+): void {
+	if (!runtimeMeta) {
+		return
+	}
+	const staticByField = indexByFieldName(staticMeta)
+	for (const runtimeField of runtimeMeta.fields.values()) {
+		const staticField = staticByField.get(runtimeField.fieldName)
+		if (!staticField) {
+			lines.push(`  missing from static (under-fetch): ${[...path, runtimeField.fieldName].join('.')}`)
+			continue
+		}
+		// Both sides fetch this relation — recurse into what the runtime nests.
+		if (runtimeField.nested) {
+			diffUnderfetchedFields(staticField.nested, runtimeField.nested, [...path, runtimeField.fieldName], lines)
+		}
+	}
+}
+
+/** Index a selection's top-level fields by field name (aliases collapse). */
+function indexByFieldName(meta: SelectionMeta | undefined): Map<string, SelectionFieldMeta> {
+	const byField = new Map<string, SelectionFieldMeta>()
+	if (meta) {
+		for (const field of meta.fields.values()) {
+			byField.set(field.fieldName, field)
+		}
 	}
+	return byField
 }
 
 // ============================================================================

package/src/jsx/components/Entity.tsx

@@ -2,7 +2,8 @@ import React, { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef,
 import { useBindxContext, useSchemaRegistry } from '../../hooks/BackendAdapterContext.js'
 import { annotateElement } from '../devAnnotations.js'
 import { useEntity } from '../../hooks/useEntity.js'
-import { useSelectionCollection } from '../../hooks/useSelectionCollection.js'
+import { useRootSelection } from '../../hooks/useRootSelection.js'
+import type { CompiledSelection } from '../compiledSelection.js'
 import type { EntityAccessor, EntityRef, SelectionMeta } from '../types.js'
 import { type EntityDef, type EntityUniqueWhere, type AnyBrand, type FieldError, EntityHandle, type SnapshotStore, type ActionDispatcher, type SchemaRegistry, type CommonEntity } from '@contember/bindx'
 
@@ -19,6 +20,12 @@ interface EntityBaseProps<TRoleMap extends Record<string, object>> {
 	children: (entity: EntityRef<CommonEntity<TRoleMap>>) => React.ReactNode
 	/** Error fallback */
 	error?: (error: FieldError) => React.ReactNode
+	/**
+	 * Precompiled root selection — injected by the bindx compiler, do not hand-write.
+	 * When present the root selection is built statically (fields under the fixed
+	 * `entity` key + resolved holes) and `children` is not invoked with a collector.
+	 */
+	compiledSelection?: CompiledSelection
 }
 
 /**
@@ -72,6 +79,7 @@ interface EntityByModeProps {
 	loading?: React.ReactNode
 	error?: (error: FieldError) => React.ReactNode
 	notFound?: React.ReactNode
+	compiledSelection?: CompiledSelection
 }
 
 interface EntityCreateModeProps {
@@ -79,6 +87,7 @@ interface EntityCreateModeProps {
 	children: (entity: EntityAccessor<unknown>) => React.ReactNode
 	error?: (error: FieldError) => React.ReactNode
 	onPersisted?: (id: string) => void
+	compiledSelection?: CompiledSelection
 }
 
 // ==================== EntityByMode Component ====================
@@ -94,6 +103,7 @@ function EntityByMode({
 	loading,
 	error: errorFallback,
 	notFound,
+	compiledSelection,
 }: EntityByModeProps): ReactElement | null {
 	const { store, dispatcher } = useBindxContext()
 	const schemaRegistry = useSchemaRegistry()
@@ -101,11 +111,13 @@ function EntityByMode({
 	// Stable key for the 'by' clause
 	const byKey = useMemo(() => JSON.stringify(by), [by])
 
-	// Phase 1: Collect JSX selection
-	const { selection, queryKey: selectionQueryKey } = useSelectionCollection({
+	// Phase 1: Build the root selection — statically when compiled, else via the
+	// children-collector walk.
+	const { selection, queryKey: selectionQueryKey } = useRootSelection({
 		entityType,
 		depsKey: byKey,
-		collect: collector => children(collector as EntityAccessor<unknown>),
+		children,
+		compiledSelection,
 	})
 
 	// Combine internal selection key with user-supplied invalidation key so
@@ -181,6 +193,7 @@ function EntityCreateMode({
 	entityType,
 	children,
 	onPersisted,
+	compiledSelection,
 }: EntityCreateModeProps): ReactElement {
 	const { store } = useBindxContext()
 	const tempIdRef = useRef<string | null>(null)
@@ -216,7 +229,7 @@ function EntityCreateMode({
 	}
 
 	return (
-		<EntityCreateModeInner entityType={entityType} tempId={tempId} onPersisted={onPersisted}>
+		<EntityCreateModeInner entityType={entityType} tempId={tempId} onPersisted={onPersisted} compiledSelection={compiledSelection}>
 			{children}
 		</EntityCreateModeInner>
 	)
@@ -232,11 +245,13 @@ function EntityCreateModeInner({
 	tempId,
 	children,
 	onPersisted,
+	compiledSelection,
 }: {
 	entityType: string
 	tempId: string
 	children: (entity: EntityAccessor<unknown>) => React.ReactNode
 	onPersisted?: (id: string) => void
+	compiledSelection?: CompiledSelection
 }): ReactElement {
 	const { store, dispatcher } = useBindxContext()
 	const schemaRegistry = useSchemaRegistry()
@@ -283,11 +298,13 @@ function EntityCreateModeInner({
 		}
 	}, [persistedId, onPersisted])
 
-	// Selection collection still works for building mutations
-	useSelectionCollection({
+	// Selection collection still works for building mutations. A compiled selection
+	// skips the children(collector) walk here too.
+	useRootSelection({
 		entityType,
 		depsKey: tempId,
-		collect: collector => children(collector as EntityAccessor<unknown>),
+		children,
+		compiledSelection,
 	})
 
 	// Create EntityHandle (no selection for create mode - all fields accessible)
@@ -414,6 +431,7 @@ function EntityImpl<TRoleMap extends Record<string, object>>(
 				children={createProps.children as (entity: EntityAccessor<unknown>) => React.ReactNode}
 				error={createProps.error}
 				onPersisted={createProps.onPersisted}
+				compiledSelection={createProps.compiledSelection}
 			/>
 		)
 	}
@@ -428,6 +446,7 @@ function EntityImpl<TRoleMap extends Record<string, object>>(
 			loading={byProps.loading}
 			error={byProps.error}
 			notFound={byProps.notFound}
+			compiledSelection={byProps.compiledSelection}
 		/>
 	)
 }