@getodk/xforms-engine 0.6.0 → 0.7.0

package/src/instance/internal-api/InstanceConfig.ts

@@ -1,16 +1,9 @@
-import type { MissingResourceBehavior } from '../../client/constants.ts';
+import type { FormInstanceConfig } from '../../client/form/FormInstanceConfig.ts';
 import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
-import type { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
-import type { CreateUniqueId } from '../../lib/unique-id.ts';
 
 export interface InstanceConfig {
-	readonly stateFactory: OpaqueReactiveObjectFactory;
-	readonly fetchFormDefinition: FetchResource;
-	readonly fetchFormAttachment: FetchFormAttachment;
-	readonly missingResourceBehavior: MissingResourceBehavior;
-
 	/**
-	 * Uniqueness per form instance session (so e.g. persistence isn't necessary).
+	 * @see {@link FormInstanceConfig.stateFactory}
 	 */
-	readonly createUniqueId: CreateUniqueId;
+	readonly clientStateFactory: OpaqueReactiveObjectFactory;
 }

package/src/instance/internal-api/InstanceValueContext.ts

@@ -1,8 +1,14 @@
+import type { FormInstanceInitializationMode } from '../../client/index.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
 
+export interface InstanceValueContextDocument {
+	readonly initializationMode: FormInstanceInitializationMode;
+}
+
 export type DecodeInstanceValue = (value: string) => string;
 
 interface InstanceValueContextDefinitionBind {
@@ -13,12 +19,14 @@ interface InstanceValueContextDefinitionBind {
 
 export interface InstanceValueContextDefinition {
 	readonly bind: InstanceValueContextDefinitionBind;
-	readonly defaultValue: string;
+	readonly template: StaticLeafElement;
 }
 
 export interface InstanceValueContext extends EvaluationContext {
 	readonly scope: ReactiveScope;
+	readonly rootDocument: InstanceValueContextDocument;
 	readonly definition: InstanceValueContextDefinition;
+	readonly instanceNode: StaticLeafElement | null;
 	readonly decodeInstanceValue: DecodeInstanceValue;
 
 	isReadonly(): boolean;

package/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts

@@ -0,0 +1,20 @@
+import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
+import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { Root } from '../../Root.ts';
+import type {
+	ClientReactiveSerializableParentNode,
+	ClientReactiveSerializableParentNodeDefinition,
+} from './ClientReactiveSerializableParentNode.ts';
+
+interface ClientReactiveSerializableInstanceDefinition
+	extends ClientReactiveSerializableParentNodeDefinition {
+	readonly submission: SubmissionMeta;
+}
+
+export interface ClientReactiveSerializableInstance
+	extends ClientReactiveSerializableParentNode<Root> {
+	readonly definition: ClientReactiveSerializableInstanceDefinition;
+	readonly root: Root;
+	readonly parent: null;
+	readonly validationState: AncestorNodeValidationState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts

@@ -0,0 +1,43 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
+import type {
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
+
+interface ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue> {
+	get relevant(): boolean;
+	get value(): RuntimeValue;
+}
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableLeafNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableLeafNode<RuntimeValue> {
+	readonly definition: ClientReactiveSerializableLeafNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue>;
+
+	/**
+	 * A client-reactive serializble leaf node is responsible for producing a
+	 * string representation of its value state, suitable for instance
+	 * serialization. It **MUST NOT** perform any further instance
+	 * serialization-specific serialization duties: in particular, the value
+	 * **MUST NOT** be escaped for XML. This responsibility is delegated up the
+	 * stack, to avoid repeat escaping.
+	 *
+	 * Note: excluding {@link EscapedXMLText} here does not have an effect on the
+	 * type system, it is a documentation-only hint, to help guard against future
+	 * double-escaping mistakes.
+	 */
+	readonly encodeValue: (
+		this: unknown,
+		runtimeValue: RuntimeValue
+	) => Exclude<string, EscapedXMLText>;
+
+	readonly instanceState: InstanceState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts

@@ -0,0 +1,26 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+
+export interface ClientReactiveSerializableChildNode {
+	readonly instanceState: InstanceState;
+}
+
+export interface ClientReactiveSerializableParentNodeCurrentState<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	get relevant(): boolean;
+	get children(): readonly Child[];
+}
+
+export interface ClientReactiveSerializableParentNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableParentNode<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	readonly definition: ClientReactiveSerializableParentNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode> | null;
+	readonly currentState: ClientReactiveSerializableParentNodeCurrentState<Child>;
+	readonly instanceState: InstanceState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts

@@ -0,0 +1,24 @@
+import type { TemplatedNodeAttributeSerializationError } from '../../../error/TemplatedNodeAttributeSerializationError.ts';
+import type { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import type { GeneralChildNode } from '../../hierarchy.ts';
+import type {
+	ClientReactiveSerializableParentNode,
+	ClientReactiveSerializableParentNodeCurrentState,
+	ClientReactiveSerializableParentNodeDefinition,
+} from './ClientReactiveSerializableParentNode.ts';
+
+export interface ClientReactiveSerializableTemplatedNodeCurrentState
+	extends ClientReactiveSerializableParentNodeCurrentState<GeneralChildNode> {
+	/** @see {@link TemplatedNodeAttributeSerializationError} */
+	get attributes(): unknown;
+}
+
+export interface ClientReactiveSerializableTemplatedNodeDefinition
+	extends ClientReactiveSerializableParentNodeDefinition {
+	readonly template: StaticElement;
+}
+
+export interface ClientReactiveSerializableTemplatedNode
+	extends ClientReactiveSerializableParentNode<GeneralChildNode> {
+	readonly currentState: ClientReactiveSerializableTemplatedNodeCurrentState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts

@@ -0,0 +1,28 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type {
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableValueNodeCurrentState {
+	get relevant(): boolean;
+
+	/**
+	 * @todo Consider moving into {@link InstanceState}
+	 */
+	get instanceValue(): SerializedInstanceValue;
+}
+
+interface ClientReactiveSerializableValueNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableValueNode {
+	readonly definition: ClientReactiveSerializableValueNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableValueNodeCurrentState;
+	readonly instanceState: InstanceState;
+}

package/src/instance/repeat/BaseRepeatRange.ts

@@ -4,9 +4,10 @@ import type { Accessor } from 'solid-js';
 import { untrack } from 'solid-js';
 import type { RepeatRangeNode } from '../../client/hierarchy.ts';
 import type { FormNodeID } from '../../client/identity.ts';
+import type { AnyRepeatDefinition } from '../../client/index.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type {
@@ -14,7 +15,8 @@ import type {
 	XFormsXPathNodeRangeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createNodeRangeSubmissionState } from '../../lib/client-reactivity/submission/createNodeRangeSubmissionState.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { createNodeRangeInstanceState } from '../../lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -24,10 +26,7 @@ import type { EngineState } from '../../lib/reactivity/node-state/createEngineSt
 import type { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createSharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createNodeLabel } from '../../lib/reactivity/text/createNodeLabel.ts';
-import type {
-	AnyRepeatRangeDefinition,
-	ControlledRepeatRangeDefinition,
-} from '../../parse/model/RepeatRangeDefinition.ts';
+import type { ControlledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import type {
 	AnyDescendantNode,
 	DescendantNodeSharedStateSpec,
@@ -35,8 +34,8 @@ import type {
 import { DescendantNode } from '../abstract/DescendantNode.ts';
 import type { GeneralParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
-import { RepeatInstance, type RepeatDefinition } from './RepeatInstance.ts';
+import type { ClientReactiveSerializableParentNode } from '../internal-api/serialization/ClientReactiveSerializableParentNode.ts';
+import { RepeatInstance } from './RepeatInstance.ts';
 
 interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly hint: null;
@@ -47,18 +46,18 @@ interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
 }
 
 // prettier-ignore
-type BaseRepeatRangeNodeType<Definition extends AnyRepeatRangeDefinition> =
-	Definition extends ControlledRepeatRangeDefinition
+type BaseRepeatRangeNodeType<Definition extends AnyRepeatDefinition> =
+	Definition extends ControlledRepeatDefinition
 		? 'repeat-range:controlled'
 		: 'repeat-range:uncontrolled';
 
-export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition>
+export abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition>
 	extends DescendantNode<Definition, RepeatRangeStateSpec, GeneralParentNode, RepeatInstance>
 	implements
 		BaseRepeatRangeNode,
 		XFormsXPathNodeRange,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<RepeatInstance>
+		ClientReactiveSerializableParentNode<RepeatInstance>
 {
 	protected readonly childrenState: ChildrenState<RepeatInstance>;
 
@@ -149,10 +148,10 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 	abstract override readonly validationState: AncestorNodeValidationState;
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(parent: GeneralParentNode, definition: Definition) {
-		super(parent, definition);
+		super(parent, definition.template, definition);
 
 		const repeatRange = this as AnyDescendantNode as RepeatRange;
 
@@ -160,10 +159,6 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 		this.childrenState = childrenState;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -178,7 +173,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 				valueOptions: null,
 				value: null,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
@@ -188,7 +183,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 			state.currentState,
 			childrenState
 		);
-		this.submissionState = createNodeRangeSubmissionState(this);
+		this.instanceState = createNodeRangeInstanceState(this);
 	}
 
 	protected getLastIndex(): number {
@@ -201,7 +196,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 	private createChildren(
 		afterIndex: number,
-		definitions: readonly RepeatDefinition[]
+		instanceNodes: readonly StaticElement[]
 	): readonly RepeatInstance[] {
 		return this.scope.runTask(() => {
 			let initialPrecedingInstance: RepeatInstance | null;
@@ -220,7 +215,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 			const repeatRange = this as AnyDescendantNode as RepeatRange;
 
-			return definitions.reduce<RepeatInstance[]>((acc, definition) => {
+			return instanceNodes.reduce<RepeatInstance[]>((acc, definition) => {
 				const precedingInstance = acc[acc.length - 1] ?? initialPrecedingInstance;
 				const newInstance = new RepeatInstance(repeatRange, definition, {
 					precedingInstance,
@@ -235,11 +230,11 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 	protected addChildren(
 		afterIndex: number,
-		definitions: readonly RepeatDefinition[]
+		instanceNodes: readonly StaticElement[]
 	): readonly RepeatInstance[] {
 		return this.scope.runTask(() => {
 			const initialIndex = afterIndex + 1;
-			const newInstances = this.createChildren(afterIndex, definitions);
+			const newInstances = this.createChildren(afterIndex, instanceNodes);
 
 			return this.childrenState.setChildren((currentInstances) => {
 				return insertAtIndex(currentInstances, initialIndex, newInstances);

package/src/instance/repeat/RepeatInstance.ts

@@ -3,15 +3,17 @@ import type { Accessor } from 'solid-js';
 import { createComputed, createSignal, on } from 'solid-js';
 import type { FormNodeID } from '../../client/identity.ts';
 import type {
-	RepeatDefinition,
+	AnyRepeatDefinition,
 	RepeatInstanceNode,
 	RepeatInstanceNodeAppearances,
 } from '../../client/repeat/RepeatInstanceNode.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
+import type { TemplatedNodeAttributeSerializationError } from '../../error/TemplatedNodeAttributeSerializationError.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createParentNodeSubmissionState } from '../../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { createTemplatedNodeInstanceState } from '../../lib/client-reactivity/instance-state/createTemplatedNodeInstanceState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -24,16 +26,18 @@ import { createNodeLabel } from '../../lib/reactivity/text/createNodeLabel.ts';
 import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { DescendantNodeSharedStateSpec } from '../abstract/DescendantNode.ts';
 import { DescendantNode } from '../abstract/DescendantNode.ts';
-import { buildChildren } from '../children.ts';
+import { buildChildren } from '../children/buildChildren.ts';
 import type { GeneralChildNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
-
-export type { RepeatDefinition };
+import type { ClientReactiveSerializableTemplatedNode } from '../internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts';
 
 interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: null;
+
+	/** @see {@link TemplatedNodeAttributeSerializationError} */
+	readonly attributes: null;
+
 	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
@@ -44,12 +48,17 @@ interface RepeatInstanceOptions {
 }
 
 export class RepeatInstance
-	extends DescendantNode<RepeatDefinition, RepeatInstanceStateSpec, RepeatRange, GeneralChildNode>
+	extends DescendantNode<
+		AnyRepeatDefinition,
+		RepeatInstanceStateSpec,
+		RepeatRange,
+		GeneralChildNode
+	>
 	implements
 		RepeatInstanceNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableTemplatedNode
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 	private readonly currentIndex: Accessor<number>;
@@ -99,19 +108,20 @@ export class RepeatInstance
 		GeneralChildNode
 	>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		override readonly parent: RepeatRange,
-		definition: RepeatDefinition,
+		instanceNode: StaticElement | null,
 		options: RepeatInstanceOptions
 	) {
+		const { definition } = parent;
 		const { precedingInstance } = options;
 		const precedingIndex = precedingInstance?.currentIndex ?? (() => -1);
 		const initialIndex = precedingIndex() + 1;
 		const [currentIndex, setCurrentIndex] = createSignal(initialIndex);
 
-		super(parent, definition, {
+		super(parent, instanceNode, definition, {
 			computeReference: (): string => {
 				const currentPosition = currentIndex() + 1;
 
@@ -126,10 +136,6 @@ export class RepeatInstance
 		this.childrenState = childrenState;
 		this.currentIndex = currentIndex;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -141,11 +147,12 @@ export class RepeatInstance
 				// TODO: only-child <group><label>
 				label: createNodeLabel(this, definition),
 				hint: null,
+				attributes: null,
 				children: childrenState.childIds,
 				valueOptions: null,
 				value: null,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
@@ -178,8 +185,8 @@ export class RepeatInstance
 		});
 
 		childrenState.setChildren(buildChildren(this));
-		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.validationState = createAggregatedViolations(this, this.instanceConfig);
+		this.instanceState = createTemplatedNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/repeat/RepeatRangeControlled.ts

@@ -1,45 +1,69 @@
 import { createComputed } from 'solid-js';
+import type { LoadFormWarnings } from '../../client/form/LoadFormResult.ts';
 import type { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
 import type { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type { XFormsXPathNodeRange } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
-import type { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { ControlledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import type { GeneralParentNode } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { BaseRepeatRange } from './BaseRepeatRange.ts';
-import type { RepeatDefinition } from './RepeatInstance.ts';
+
+// prettier-ignore
+type RepeatCountControlType =
+	| 'REPEAT_COUNT_CONTROL_DYNAMIC'
+	| 'REPEAT_COUNT_CONTROL_FIXED';
 
 export class RepeatRangeControlled
-	extends BaseRepeatRange<ControlledRepeatRangeDefinition>
+	extends BaseRepeatRange<ControlledRepeatDefinition>
 	implements RepeatRangeControlledNode, XFormsXPathNodeRange, EvaluationContext
 {
+	private readonly isInstanceCreation: boolean;
+	private readonly countControlType: RepeatCountControlType;
+
 	// RepeatRangeControlledNode
 	readonly nodeType = 'repeat-range:controlled';
 	readonly appearances: RepeatRangeNodeAppearances;
 	readonly validationState: AncestorNodeValidationState;
 
-	constructor(parent: GeneralParentNode, definition: ControlledRepeatRangeDefinition) {
+	constructor(
+		parent: GeneralParentNode,
+		instanceNodes: readonly StaticElement[],
+		definition: ControlledRepeatDefinition
+	) {
 		super(parent, definition);
 
+		this.isInstanceCreation = parent.rootDocument.initializationMode === 'create';
 		this.appearances = definition.bodyElement.appearances;
 
-		this.initializeControlledChildrenState(definition);
+		if (definition.count.isConstantExpression()) {
+			this.countControlType = 'REPEAT_COUNT_CONTROL_FIXED';
+		} else {
+			this.countControlType = 'REPEAT_COUNT_CONTROL_DYNAMIC';
+		}
 
-		this.validationState = createAggregatedViolations(this, {
-			clientStateFactory: this.engineConfig.stateFactory,
-		});
+		this.initializeControlledChildrenState(definition, instanceNodes);
+
+		this.validationState = createAggregatedViolations(this, this.instanceConfig);
 	}
 
-	private initializeControlledChildrenState(definition: ControlledRepeatRangeDefinition): void {
+	private initializeControlledChildrenState(
+		definition: ControlledRepeatDefinition,
+		instanceNodes: readonly StaticElement[]
+	): void {
 		this.scope.runTask(() => {
-			const { count, instances, template } = definition;
+			const { count, template } = definition;
+			const repeatInstanceNodes = definition.omitTemplate(instanceNodes);
 			const computeCount = createComputedExpression(this, count, {
 				defaultValue: 0,
 			});
 
-			createComputed<number>((previousCount) => {
+			createComputed((previousCountComputation: number | null = null): number => {
+				const previousCount = previousCountComputation ?? 0;
+
 				let currentCount = computeCount();
 
 				if (Number.isFinite(currentCount) && currentCount < 0) {
@@ -58,17 +82,19 @@ export class RepeatRangeControlled
 					return previousCount;
 				}
 
+				this.warnDroppedInstanceNodes(repeatInstanceNodes, previousCountComputation, currentCount);
+
 				if (currentCount > previousCount) {
 					const delta = currentCount - previousCount;
-					const definitions = Array<RepeatDefinition>(delta)
-						.fill(template)
-						.map((baseDefinition, index) => {
+					const inputNodes = Array(delta)
+						.fill(null)
+						.map((_, index) => {
 							const instanceIndex = previousCount + index;
 
-							return instances[instanceIndex] ?? baseDefinition;
+							return repeatInstanceNodes[instanceIndex] ?? template;
 						});
 
-					this.addChildren(previousCount - 1, definitions);
+					this.addChildren(previousCount - 1, inputNodes);
 				} else {
 					const delta = previousCount - currentCount;
 
@@ -76,7 +102,54 @@ export class RepeatRangeControlled
 				}
 
 				return currentCount;
-			}, 0);
+			});
 		});
 	}
+
+	/**
+	 * Note: we do not warn about dropping "excess" repeat instances...
+	 *
+	 * - ... after the instance is fully loaded: dropping repeat instances after
+	 *   that point is an expected behavior of _dynamically-controlled repeats_
+	 *   (i.e. those defined with `jr:count`), and it does not occur for
+	 *   _fixed-controlled repeats_ (i.e. defined with `jr:noAddRemove`);
+	 *
+	 * - ... for dynamic (`jr:count`) repeats _in newly created form instances_, i.e. instances whose input instance
+	 *   nodes are derived from the _form definition_: those form-defined repeat
+	 *   instances are not "dropped", instead they're retained in memory to be
+	 *   added as count is recomputed to a larger value.
+	 *
+	 * @todo ^ it is pretty likely that retain-in-memory behavior also applies to
+	 * instance state which has been serialized and restored as well! In this way,
+	 * it's possible we're not really "dropping" those nodes, only deferring their
+	 * restoration. Is this what we want?
+	 *
+	 * @todo Design and produce {@link LoadFormWarnings | warnings} as values!
+	 */
+	private warnDroppedInstanceNodes(
+		repeatInstanceNodes: readonly StaticElement[],
+		previousCountComputation: number | null,
+		initialCount: number
+	): void {
+		// See this method's JSDoc notes for reasoning!
+		if (this.isInstanceCreation) {
+			return;
+		}
+
+		// See this method's JSDoc notes for reasoning!
+		const isInstanceLoad = previousCountComputation == null;
+
+		if (isInstanceLoad && this.countControlType === 'REPEAT_COUNT_CONTROL_DYNAMIC') {
+			return;
+		}
+
+		const droppedCount = repeatInstanceNodes.length - initialCount;
+
+		if (droppedCount > 0) {
+			// eslint-disable-next-line no-console
+			console.warn(
+				`Dropped ${droppedCount} repeat instances for repeat range ${this.contextReference()}`
+			);
+		}
+	}
 }