@getodk/xforms-engine 0.6.0 → 0.7.0

package/src/instance/SelectControl.ts

@@ -12,6 +12,7 @@ import type { TextRange } from '../client/TextRange.ts';
 import type { ValueType } from '../client/ValueType.ts';
 import { SelectValueTypeError } from '../error/SelectValueTypeError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
 import { getSelectCodec } from '../lib/codecs/getSelectCodec.ts';
 import { createItemCollection } from '../lib/reactivity/createItemCollection.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -28,7 +29,7 @@ import { ValueNode } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 export type AnySelectDefinition = {
 	[V in ValueType]: SelectDefinition<V>;
@@ -59,13 +60,21 @@ export class SelectControl
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
-	static from(parent: GeneralParentNode, definition: SelectDefinition): SelectControl;
-	static from(parent: GeneralParentNode, definition: AnySelectDefinition): SelectControl {
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: SelectDefinition
+	): SelectControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnySelectDefinition
+	): SelectControl {
 		assertSupportedSelectValueType(definition);
 
-		return new this(parent, definition);
+		return new this(parent, instanceNode, definition);
 	}
 
 	private readonly mapOptionsByValue: Accessor<SelectItemMap>;
@@ -86,10 +95,14 @@ export class SelectControl
 	readonly nodeOptions = null;
 	readonly currentState: CurrentState<SelectControlStateSpec>;
 
-	private constructor(parent: GeneralParentNode, definition: SelectDefinition<'string'>) {
+	private constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: SelectDefinition<'string'>
+	) {
 		const codec = getSelectCodec(definition);
 
-		super(parent, definition, codec);
+		super(parent, instanceNode, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
 		this.selectType = definition.bodyElement.type;
@@ -123,10 +136,6 @@ export class SelectControl
 			});
 		});
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -142,7 +151,7 @@ export class SelectControl
 				value: valueState,
 				instanceValue: this.getInstanceValue,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;

package/src/instance/Subtree.ts

@@ -1,11 +1,12 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { FormNodeID } from '../client/identity.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
 import type { AncestorNodeValidationState } from '../client/validation.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 { createParentNodeInstanceState } from '../lib/client-reactivity/instance-state/createParentNodeInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -17,10 +18,10 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 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, GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 
 interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: null;
@@ -36,7 +37,7 @@ export class Subtree
 		SubtreeNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -52,19 +53,19 @@ export class Subtree
 	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
-	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
-		super(parent, definition);
+	constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticElement | null,
+		definition: SubtreeDefinition
+	) {
+		super(parent, instanceNode, definition);
 
 		const childrenState = createChildrenState<Subtree, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -79,7 +80,7 @@ export class Subtree
 				valueOptions: null,
 				value: null,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
@@ -91,8 +92,8 @@ export class Subtree
 		);
 
 		childrenState.setChildren(buildChildren(this));
-		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.validationState = createAggregatedViolations(this, this.instanceConfig);
+		this.instanceState = createParentNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/TriggerControl.ts

@@ -5,6 +5,7 @@ import type { TriggerNode, TriggerNodeDefinition } from '../client/TriggerNode.t
 import type { ValueType } from '../client/ValueType.ts';
 import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
 import type { TriggerInputValue, TriggerRuntimeValue } from '../lib/codecs/TriggerCodec.ts';
 import { TriggerCodec } from '../lib/codecs/TriggerCodec.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -19,7 +20,7 @@ import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 interface TriggerControlStateSpec extends ValueNodeStateSpec<TriggerRuntimeValue> {
 	readonly label: Accessor<TextRange<'label'> | null>;
@@ -45,17 +46,25 @@ export class TriggerControl
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
-	static from(parent: GeneralParentNode, definition: TriggerNodeDefinition): TriggerControl;
-	static from(parent: GeneralParentNode, definition: AnyTriggerNodeDefinition): TriggerControl {
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: TriggerNodeDefinition
+	): TriggerControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnyTriggerNodeDefinition
+	): TriggerControl {
 		if (definition.valueType !== 'string') {
 			throw new ErrorProductionDesignPendingError(
 				`Unsupported trigger value type: ${definition.valueType}`
 			);
 		}
 
-		return new this(parent, definition);
+		return new this(parent, instanceNode, definition);
 	}
 
 	// XFormsXPathElement
@@ -71,15 +80,15 @@ export class TriggerControl
 	readonly nodeOptions = null;
 	readonly currentState: CurrentState<TriggerControlStateSpec>;
 
-	private constructor(parent: GeneralParentNode, definition: TriggerNodeDefinition<'string'>) {
-		super(parent, definition, codec);
+	private constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: TriggerNodeDefinition<'string'>
+	) {
+		super(parent, instanceNode, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -95,7 +104,7 @@ export class TriggerControl
 				value: this.valueState,
 				instanceValue: this.getInstanceValue,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;

package/src/instance/abstract/DescendantNode.ts

@@ -11,9 +11,11 @@ import type {
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNodeInitOptions } from '../children/DescendantNodeInitOptions.ts';
 import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { RepeatInstance } from '../repeat/RepeatInstance.ts';
@@ -50,6 +52,13 @@ interface DescendantNodeOptions {
 	readonly computeReference?: Accessor<string>;
 }
 
+/**
+ * @todo Unify constructor signatures of {@link DescendantNode} and its
+ * subclasses, which will simplify the branchy logic of child node construction
+ * and minimize internal churn as common themes evolve. A good starting point is
+ * beginning to form in {@link DescendantNodeInitOptions} (not to be confused
+ * with the current module-local {@link DescendantNodeOptions}).
+ */
 export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -128,10 +137,11 @@ export abstract class DescendantNode<
 
 	constructor(
 		override readonly parent: Parent,
+		override readonly instanceNode: StaticElement | null,
 		override readonly definition: Definition,
 		options?: DescendantNodeOptions
 	) {
-		super(parent.engineConfig, parent, definition, options);
+		super(parent.instanceConfig, parent, instanceNode, definition, options);
 
 		if (this.isRoot()) {
 			this.root = this;
@@ -142,7 +152,7 @@ export abstract class DescendantNode<
 		const { evaluator } = parent;
 
 		// See notes on property declaration
-		if (definition.type === 'repeat-range') {
+		if (definition.type === 'repeat') {
 			this[XPathNodeKindKey] = XFORMS_XPATH_NODE_RANGE_KIND;
 		} else {
 			this[XPathNodeKindKey] = 'element';

package/src/instance/abstract/InstanceNode.ts

@@ -4,7 +4,7 @@ import type { BaseNode } from '../../client/BaseNode.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { FormNodeID } from '../../client/identity.ts';
 import type { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { NodeValidationState } from '../../client/validation.ts';
 import type { ActiveLanguage, TextRange } from '../../index.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
@@ -13,6 +13,8 @@ import type {
 	XFormsXPathPrimaryInstanceNodeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -20,6 +22,7 @@ import type { SharedNodeState } from '../../lib/reactivity/node-state/createShar
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { createReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import { createUniqueId } from '../../lib/unique-id.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
@@ -148,7 +151,7 @@ export abstract class InstanceNode<
 
 	abstract readonly validationState: NodeValidationState;
 
-	abstract readonly submissionState: SubmissionState;
+	abstract readonly instanceState: InstanceState;
 
 	// EvaluationContext: instance-global/shared
 	abstract readonly evaluator: EngineXPathEvaluator;
@@ -186,8 +189,9 @@ export abstract class InstanceNode<
 		this as AnyInstanceNode as PrimaryInstanceXPathNode;
 
 	constructor(
-		readonly engineConfig: InstanceConfig,
+		readonly instanceConfig: InstanceConfig,
 		readonly parent: Parent,
+		readonly instanceNode: StaticDocument | StaticElement | null,
 		readonly definition: Definition,
 		options?: InstanceNodeOptions
 	) {
@@ -208,8 +212,8 @@ export abstract class InstanceNode<
 		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
 
 		this.scope = options?.scope ?? createReactiveScope();
-		this.engineConfig = engineConfig;
-		this.nodeId = nodeID(engineConfig.createUniqueId());
+		this.instanceConfig = instanceConfig;
+		this.nodeId = nodeID(createUniqueId());
 		this.definition = definition;
 	}
 

package/src/instance/abstract/ValueNode.ts

@@ -2,11 +2,12 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { BaseValueNode } from '../../client/BaseValueNode.ts';
 import type { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { ValueType } from '../../client/ValueType.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createValueNodeSubmissionState } from '../../lib/client-reactivity/submission/createValueNodeSubmissionState.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { createValueNodeInstanceState } from '../../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
 import type {
 	RuntimeValueSetter,
 	RuntimeValueState,
@@ -26,7 +27,7 @@ import type {
 	DecodeInstanceValue,
 	InstanceValueContext,
 } from '../internal-api/InstanceValueContext.ts';
-import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from '../internal-api/ValidationContext.ts';
 import type { DescendantNodeStateSpec } from './DescendantNode.ts';
 import { DescendantNode } from './DescendantNode.ts';
@@ -52,7 +53,7 @@ export abstract class ValueNode<
 		EvaluationContext,
 		InstanceValueContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	protected readonly validation: SharedValidationState;
 	protected readonly getInstanceValue: Accessor<string>;
@@ -80,21 +81,20 @@ export abstract class ValueNode<
 		return this.validation.currentState;
 	}
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		parent: GeneralParentNode,
+		override readonly instanceNode: StaticLeafElement | null,
 		definition: Definition,
 		codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>
 	) {
-		super(parent, definition);
+		super(parent, instanceNode, definition);
 
 		this.valueType = definition.valueType;
 		this.decodeInstanceValue = codec.decodeInstanceValue;
 
-		const instanceValueState = createInstanceValueState(this, {
-			initialValueSource: 'FORM_DEFAULT',
-		});
+		const instanceValueState = createInstanceValueState(this);
 		const valueState = codec.createRuntimeValueState(instanceValueState);
 
 		const [getInstanceValue] = instanceValueState;
@@ -106,10 +106,8 @@ export abstract class ValueNode<
 			return this.getInstanceValue();
 		};
 		this.valueState = valueState;
-		this.validation = createValidationState(this, {
-			clientStateFactory: this.engineConfig.stateFactory,
-		});
-		this.submissionState = createValueNodeSubmissionState(this);
+		this.validation = createValidationState(this, this.instanceConfig);
+		this.instanceState = createValueNodeInstanceState(this);
 	}
 
 	// ValidationContext

package/src/instance/children/DescendantNodeInitOptions.ts

@@ -0,0 +1,35 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ChildNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { childrenInitOptions } from './childrenInitOptions.ts';
+
+/**
+ * @todo We could pretty significantly simplify downstream child node
+ * construction logic, if we break this down into a tagged union (essentially
+ * moving the branchy type refinement aspects up the stack, probably trimming
+ * the construction logic itself down to a switch statement). At which point,
+ * it'd also probably be easier to reason about each of those constructors
+ * accepting input exactly as it's represented as a member of this hypothetical
+ * tagged union. Something like this:
+ *
+ * - Revise each concrete {@link DescendantNode} class to accept an options-like
+ *   object suitable for its construction, each respectively defined by an
+ *   interface whose name is consistent with that node
+ * - Update this type to be a union of those interfaces
+ * - Implement that in {@link childrenInitOptions}
+ * - Update downstream construction to switch over whatever narrows the union
+ * - Bonus points: revise each concrete {@link DescendantNode} to use a common
+ *   constructor API (i.e. a static `from` method, since several such classes
+ *   already have private constructors). Then downstream isn't even a switch
+ *   statement, it's just a lookup table.
+ *
+ * @todo As of this commit, and as now mentioned on {@link DescendantNode}, and
+ * as discussed in
+ * {@link https://github.com/getodk/web-forms/pull/352#discussion_r2008237762}:
+ * this interface is intended as an intermediate step toward these goals.
+ */
+export interface DescendantNodeInitOptions {
+	readonly childNodeset: string;
+	readonly definition: ChildNodeDefinition;
+	readonly instanceNodes: readonly StaticElement[];
+}

package/src/instance/{children.ts → children/buildChildren.ts}

@@ -1,34 +1,35 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import type { GroupDefinition } from '../client/GroupNode.ts';
-import type { InputDefinition } from '../client/InputNode.ts';
-import type { ModelValueDefinition } from '../client/ModelValueNode.ts';
-import type { SelectDefinition } from '../client/SelectNode.ts';
-import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
-import type { TriggerNodeDefinition } from '../client/TriggerNode.ts';
-import type { RankDefinition } from '../client/RankNode.ts';
-import type { UploadNodeDefinition } from '../client/unsupported/UploadNode.ts';
-import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
+import type { GroupDefinition } from '../../client/GroupNode.ts';
+import type { InputDefinition } from '../../client/InputNode.ts';
+import type { ModelValueDefinition } from '../../client/ModelValueNode.ts';
+import type { RankDefinition } from '../../client/RankNode.ts';
+import type { SelectDefinition } from '../../client/SelectNode.ts';
+import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
+import type { TriggerNodeDefinition } from '../../client/TriggerNode.ts';
+import type { UploadNodeDefinition } from '../../client/unsupported/UploadNode.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
 import type {
 	AnyRangeNodeDefinition,
 	RangeLeafNodeDefinition,
-} from '../parse/model/RangeNodeDefinition.ts';
-import { RangeNodeDefinition } from '../parse/model/RangeNodeDefinition.ts';
-import type { SubtreeDefinition as ModelSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
-import { Group } from './Group.ts';
-import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { InputControl } from './InputControl.ts';
-import { ModelValue } from './ModelValue.ts';
-import { Note } from './Note.ts';
-import { RangeControl } from './RangeControl.ts';
-import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
-import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
-import { SelectControl } from './SelectControl.ts';
-import { Subtree } from './Subtree.ts';
-import { TriggerControl } from './TriggerControl.ts';
-import { RankControl } from './RankControl.ts';
-import { UploadControl } from './unsupported/UploadControl.ts';
+} from '../../parse/model/RangeNodeDefinition.ts';
+import { RangeNodeDefinition } from '../../parse/model/RangeNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../../parse/model/SubtreeDefinition.ts';
+import { Group } from '../Group.ts';
+import type { GeneralChildNode, GeneralParentNode } from '../hierarchy.ts';
+import { InputControl } from '../InputControl.ts';
+import { ModelValue } from '../ModelValue.ts';
+import { Note } from '../Note.ts';
+import { RangeControl } from '../RangeControl.ts';
+import { RankControl } from '../RankControl.ts';
+import { RepeatRangeControlled } from '../repeat/RepeatRangeControlled.ts';
+import { RepeatRangeUncontrolled } from '../repeat/RepeatRangeUncontrolled.ts';
+import { SelectControl } from '../SelectControl.ts';
+import { Subtree } from '../Subtree.ts';
+import { TriggerControl } from '../TriggerControl.ts';
+import { UploadControl } from '../unsupported/UploadControl.ts';
+import { childrenInitOptions } from './childrenInitOptions.ts';
 
 const isSubtreeDefinition = (
 	definition: ModelSubtreeDefinition
@@ -127,72 +128,78 @@ const isUploadNodeDefinition = (
 };
 
 export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
-	const { children } = parent.definition;
+	const { children } = childrenInitOptions(parent);
 
-	return children.map((child): GeneralChildNode => {
-		switch (child.type) {
+	return children.map(({ instanceNodes, definition }): GeneralChildNode => {
+		const [instanceNode = null] = instanceNodes;
+
+		switch (definition.type) {
 			case 'subtree': {
-				if (isSubtreeDefinition(child)) {
-					return new Subtree(parent, child);
+				if (isSubtreeDefinition(definition)) {
+					return new Subtree(parent, instanceNode, definition);
 				}
 
 				// TODO: it'd be good to be able to do without this type assertion. The
 				// only distinction between the types is whether `bodyElement` is
 				// `null`, but for some reason that's insufficient to narrow the union.
-				return new Group(parent, child as GroupDefinition);
+				return new Group(parent, instanceNode, definition as GroupDefinition);
 			}
 
-			case 'repeat-range': {
-				if (child.isControlled()) {
-					return new RepeatRangeControlled(parent, child);
+			case 'repeat': {
+				if (definition.isControlled()) {
+					return new RepeatRangeControlled(parent, instanceNodes, definition);
 				}
 
-				return new RepeatRangeUncontrolled(parent, child);
+				return new RepeatRangeUncontrolled(parent, instanceNodes, definition);
 			}
 
 			case 'leaf-node': {
-				if (child instanceof NoteNodeDefinition) {
-					return new Note(parent, child);
+				if (instanceNode != null && !instanceNode.isLeafElement()) {
+					throw new ErrorProductionDesignPendingError();
+				}
+
+				if (definition instanceof NoteNodeDefinition) {
+					return new Note(parent, instanceNode, definition);
 				}
 
 				// More specific type helps with narrowing below
-				const leafChild: AnyLeafNodeDefinition = child;
+				const leafChild: AnyLeafNodeDefinition = definition;
 
 				if (isModelValueDefinition(leafChild)) {
-					return ModelValue.from(parent, leafChild);
+					return ModelValue.from(parent, instanceNode, leafChild);
 				}
 
 				if (isInputDefinition(leafChild)) {
-					return InputControl.from(parent, leafChild);
+					return InputControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isSelectDefinition(leafChild)) {
-					return SelectControl.from(parent, leafChild);
+					return SelectControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isRankDefinition(leafChild)) {
-					return RankControl.from(parent, leafChild);
+					return RankControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isTriggerNodeDefinition(leafChild)) {
-					return TriggerControl.from(parent, leafChild);
+					return TriggerControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isRangeLeafNodeDefinition(leafChild)) {
 					assertRangeNodeDefinition(leafChild);
 
-					return RangeControl.from(parent, leafChild);
+					return RangeControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isUploadNodeDefinition(leafChild)) {
-					return new UploadControl(parent, leafChild);
+					return new UploadControl(parent, instanceNode, leafChild);
 				}
 
 				throw new UnreachableError(leafChild);
 			}
 
 			default: {
-				throw new UnreachableError(child);
+				throw new UnreachableError(definition);
 			}
 		}
 	});