@getodk/xforms-engine 0.5.0 → 0.7.0

package/dist/instance/abstract/DescendantNode.d.ts

@@ -6,7 +6,7 @@ import { InstanceNodeType } from '../../client/node-types.ts';
 import { PrimaryInstanceXPathChildNode } from '../../integration/xpath/adapter/kind.ts';
 import { XFormsXPathPrimaryInstanceDescendantNode, XFormsXPathPrimaryInstanceDescendantNodeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
-import { AnyDescendantNodeDefinition } from '../../parse/model/DescendentNodeDefinition.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import { AnyChildNode, AnyParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
@@ -19,13 +19,21 @@ export interface DescendantNodeSharedStateSpec {
     readonly required: Accessor<boolean>;
 }
 export type DescendantNodeStateSpec<Value = never> = InstanceNodeStateSpec<Value> & DescendantNodeSharedStateSpec;
-export type DescendantNodeDefinition = Extract<AnyNodeDefinition, AnyDescendantNodeDefinition>;
+export type DescendantNodeDefinition = AnyNodeDefinition;
 export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any, any>;
 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 declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Parent extends AnyParentNode, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Parent, Child> implements BaseNode, XFormsXPathPrimaryInstanceDescendantNode, EvaluationContext {
     readonly parent: Parent;
+    readonly instanceNode: StaticElement | null;
     readonly definition: Definition;
     /**
      * Partial implementation of {@link isAttached}, used to check whether `this`
@@ -57,7 +65,7 @@ export declare abstract class DescendantNode<Definition extends DescendantNodeDe
     readonly evaluator: EngineXPathEvaluator;
     readonly contextNode: PrimaryInstanceXPathChildNode;
     readonly getActiveLanguage: Accessor<ActiveLanguage>;
-    constructor(parent: Parent, definition: Definition, options?: DescendantNodeOptions);
+    constructor(parent: Parent, instanceNode: StaticElement | null, definition: Definition, options?: DescendantNodeOptions);
     /**
      * @package
      *

package/dist/instance/abstract/InstanceNode.d.ts

@@ -4,12 +4,14 @@ import { BaseNode } from '../../client/BaseNode.ts';
 import { NodeAppearances } from '../../client/NodeAppearances.ts';
 import { FormNodeID } from '../../client/identity.ts';
 import { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
-import { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import { InstanceState } from '../../client/serialization/InstanceState.ts';
 import { NodeValidationState } from '../../client/validation.ts';
 import { ActiveLanguage, TextRange } from '../../index.ts';
 import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import { XFormsXPathPrimaryInstanceNode, XFormsXPathPrimaryInstanceNodeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
@@ -25,6 +27,7 @@ export type EngineInstanceNodeType = ClientInstanceNodeType | 'primary-instance'
 export interface BaseEngineNode extends Omit<BaseNode, 'nodeType'> {
     readonly nodeType: EngineInstanceNodeType;
 }
+export type InstanceNodeValueOptionsStateSpec = Accessor<null> | Accessor<readonly unknown[]> | null;
 export interface InstanceNodeStateSpec<Value = never> {
     readonly reference: Accessor<string> | string;
     readonly readonly: Accessor<boolean> | boolean;
@@ -33,7 +36,7 @@ export interface InstanceNodeStateSpec<Value = never> {
     readonly label: Accessor<TextRange<'label'> | null> | null;
     readonly hint: Accessor<TextRange<'hint'> | null> | null;
     readonly children: Accessor<readonly FormNodeID[]> | null;
-    readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+    readonly valueOptions: InstanceNodeValueOptionsStateSpec;
     readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 type AnyInstanceNode = InstanceNode<AnyNodeDefinition, InstanceNodeStateSpec<any>, any>;
@@ -54,8 +57,9 @@ export interface InstanceNodeOptions {
     readonly scope?: ReactiveScope;
 }
 export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Parent extends AnyParentNode | null, Child extends AnyChildNode | null = null> implements BaseEngineNode, XFormsXPathPrimaryInstanceNode, EvaluationContext {
-    readonly engineConfig: InstanceConfig;
+    readonly instanceConfig: InstanceConfig;
     readonly parent: Parent;
+    readonly instanceNode: StaticDocument | StaticElement | null;
     readonly definition: Definition;
     protected abstract readonly state: SharedNodeState<Spec>;
     protected abstract readonly engineState: EngineState<Spec>;
@@ -85,9 +89,10 @@ export declare abstract class InstanceNode<Definition extends AnyNodeDefinition,
     readonly nodeId: FormNodeID;
     abstract readonly nodeType: EngineInstanceNodeType;
     abstract readonly appearances: NodeAppearances<Definition>;
+    abstract readonly nodeOptions: object | null;
     abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
     abstract readonly validationState: NodeValidationState;
-    abstract readonly submissionState: SubmissionState;
+    abstract readonly instanceState: InstanceState;
     abstract readonly evaluator: EngineXPathEvaluator;
     abstract readonly getActiveLanguage: Accessor<ActiveLanguage>;
     abstract readonly isAttached: Accessor<boolean>;
@@ -101,7 +106,7 @@ export declare abstract class InstanceNode<Definition extends AnyNodeDefinition,
      * constrain) their more specific `this` type.
      */
     readonly contextNode: PrimaryInstanceXPathNode;
-    constructor(engineConfig: InstanceConfig, parent: Parent, definition: Definition, options?: InstanceNodeOptions);
+    constructor(instanceConfig: InstanceConfig, parent: Parent, instanceNode: StaticDocument | StaticElement | null, definition: Definition, options?: InstanceNodeOptions);
     /** @package */
     isPrimaryInstance(): this is PrimaryInstance;
     /** @package */

package/dist/instance/abstract/ValueNode.d.ts

@@ -2,10 +2,11 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { BaseValueNode } from '../../client/BaseValueNode.ts';
 import { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
-import { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import { InstanceState } from '../../client/serialization/InstanceState.ts';
 import { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import { ValueType } from '../../client/ValueType.ts';
 import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { RuntimeValueSetter, RuntimeValueState, ValueCodec } from '../../lib/codecs/ValueCodec.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -16,17 +17,17 @@ import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { DecodeInstanceValue, InstanceValueContext } from '../internal-api/InstanceValueContext.ts';
-import { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import { ValidationContext } from '../internal-api/ValidationContext.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './DescendantNode.ts';
 export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
 export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
     readonly children: null;
-    readonly valueOptions: null;
     readonly value: SimpleAtomicState<RuntimeValue>;
     readonly instanceValue: Accessor<string>;
 }
-export declare abstract class ValueNode<V extends ValueType, Definition extends ValueNodeDefinition<V>, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> extends DescendantNode<Definition, ValueNodeStateSpec<RuntimeValue>, GeneralParentNode, null> implements BaseValueNode<V, RuntimeValue>, XFormsXPathElement, EvaluationContext, InstanceValueContext, ValidationContext, ClientReactiveSubmittableValueNode {
+export declare abstract class ValueNode<V extends ValueType, Definition extends ValueNodeDefinition<V>, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> extends DescendantNode<Definition, ValueNodeStateSpec<RuntimeValue>, GeneralParentNode, null> implements BaseValueNode<V, RuntimeValue>, XFormsXPathElement, EvaluationContext, InstanceValueContext, ValidationContext, ClientReactiveSerializableValueNode {
+    readonly instanceNode: StaticLeafElement | null;
     protected readonly validation: SharedValidationState;
     protected readonly getInstanceValue: Accessor<string>;
     protected readonly valueState: RuntimeValueState<RuntimeValue>;
@@ -40,8 +41,8 @@ export declare abstract class ValueNode<V extends ValueType, Definition extends
     readonly valueType: V;
     abstract readonly currentState: CurrentState<ValueNodeStateSpec<RuntimeValue>>;
     get validationState(): LeafNodeValidationState;
-    readonly submissionState: SubmissionState;
-    constructor(parent: GeneralParentNode, definition: Definition, codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>);
+    readonly instanceState: InstanceState;
+    constructor(parent: GeneralParentNode, instanceNode: StaticLeafElement | null, definition: Definition, codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>);
     getViolation(): AnyViolation | null;
     isBlank(): boolean;
     getChildren(): readonly [];

package/dist/instance/children/DescendantNodeInitOptions.d.ts

@@ -0,0 +1,32 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { ChildNodeDefinition } from '../../parse/model/NodeDefinition.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/dist/instance/{children.d.ts → children/buildChildren.d.ts}

@@ -1,2 +1,2 @@
-import { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import { GeneralChildNode, GeneralParentNode } from '../hierarchy.ts';
 export declare const buildChildren: (parent: GeneralParentNode) => GeneralChildNode[];

package/dist/instance/children/childrenInitOptions.d.ts

@@ -0,0 +1,9 @@
+import { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { DescendantNodeInitOptions } from './DescendantNodeInitOptions.ts';
+export interface ChildrenInitOptions {
+    readonly parent: GeneralParentNode;
+    readonly model: ModelDefinition;
+    readonly children: readonly DescendantNodeInitOptions[];
+}
+export declare const childrenInitOptions: (parent: GeneralParentNode) => ChildrenInitOptions;

package/dist/instance/children/normalizeChildInitOptions.d.ts

@@ -0,0 +1,2 @@
+import { ChildrenInitOptions } from './childrenInitOptions.ts';
+export declare const normalizeChildInitOptions: (options: ChildrenInitOptions) => ChildrenInitOptions;

package/dist/instance/hierarchy.d.ts

@@ -1,23 +1,23 @@
 import { Group } from './Group.ts';
 import { AnyInputControl } from './InputControl.ts';
 import { AnyModelValue } from './ModelValue.ts';
-import { Note } from './Note.ts';
+import { AnyNote } from './Note.ts';
 import { PrimaryInstance } from './PrimaryInstance.ts';
+import { AnyRangeControl } from './RangeControl.ts';
 import { RepeatInstance } from './repeat/RepeatInstance.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import { Root } from './Root.ts';
-import { SelectField } from './SelectField.ts';
+import { SelectControl } from './SelectControl.ts';
 import { Subtree } from './Subtree.ts';
 import { TriggerControl } from './TriggerControl.ts';
-import { RangeControl } from './unsupported/RangeControl.ts';
-import { RankControl } from './unsupported/RankControl.ts';
+import { RankControl } from './RankControl.ts';
 import { UploadControl } from './unsupported/UploadControl.ts';
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
-export type AnyUnsupportedControl = RangeControl | RankControl | UploadControl;
-export type AnyNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance | Note | AnyModelValue | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
+export type AnyUnsupportedControl = UploadControl;
+export type AnyNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance | AnyNote | AnyModelValue | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | AnyUnsupportedControl;
 export type AnyParentNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance;
 export type GeneralParentNode = Root | Group | Subtree | RepeatInstance;
-export type AnyChildNode = Root | Group | Subtree | RepeatRange | RepeatInstance | AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
-export type GeneralChildNode = Group | Subtree | RepeatRange | AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
-export type AnyValueNode = AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
+export type AnyChildNode = Root | Group | Subtree | RepeatRange | RepeatInstance | AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | AnyUnsupportedControl;
+export type GeneralChildNode = Group | Subtree | RepeatRange | AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | AnyUnsupportedControl;
+export type AnyValueNode = AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | AnyUnsupportedControl;

package/dist/instance/input/InitialInstanceState.d.ts

@@ -0,0 +1,13 @@
+import { EditFormInstanceInput } from '../../client/form/EditFormInstance.ts';
+import { InstanceData } from '../../client/serialization/InstanceData.ts';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import { InstanceAttachmentMap } from './InstanceAttachmentMap.ts';
+export type InitialInstanceStateSources = readonly [InstanceData, ...InstanceData[]];
+export declare class InitialInstanceState {
+    static from(model: ModelDefinition, data: InitialInstanceStateSources): Promise<InitialInstanceState>;
+    static resolve(model: ModelDefinition, input: EditFormInstanceInput): Promise<InitialInstanceState>;
+    readonly document: StaticDocument;
+    readonly attachments: InstanceAttachmentMap;
+    private constructor();
+}

package/dist/instance/input/InstanceAttachmentMap.d.ts

@@ -0,0 +1,19 @@
+import { ResolvableInstanceAttachmentsMap } from '../../client/form/EditFormInstance.ts';
+type InstanceAttachmentMapSourceEntry = readonly [key: string, value: FormDataEntryValue];
+interface InstanceAttachmentMapSource {
+    entries(): Iterable<InstanceAttachmentMapSourceEntry>;
+}
+type InstanceAttachmentMapSources = readonly [
+    InstanceAttachmentMapSource,
+    ...InstanceAttachmentMapSource[]
+];
+export declare class InstanceAttachmentMap extends Map<string, File> {
+    static from(sources: InstanceAttachmentMapSources): InstanceAttachmentMap;
+    /**
+     * @todo
+     * @see {@link resolveInstanceAttachmentMapSource}
+     */
+    static resolve(input: ResolvableInstanceAttachmentsMap): Promise<InstanceAttachmentMap>;
+    private constructor();
+}
+export {};

package/dist/instance/internal-api/InstanceConfig.d.ts

@@ -1,14 +1,7 @@
-import { MissingResourceBehavior } from '../../client/constants.ts';
 import { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
-import { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
-import { 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/dist/instance/internal-api/InstanceValueContext.d.ts

@@ -1,18 +1,27 @@
+import { FormInstanceInitializationMode } from '../../client/index.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
 import { EvaluationContext } from './EvaluationContext.ts';
+export interface InstanceValueContextDocument {
+    readonly initializationMode: FormInstanceInitializationMode;
+}
 export type DecodeInstanceValue = (value: string) => string;
 interface InstanceValueContextDefinitionBind {
+    readonly preload: AnyBindPreloadDefinition | null;
     readonly calculate: BindComputationExpression<'calculate'> | null;
     readonly readonly: BindComputationExpression<'readonly'>;
 }
 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;
     isRelevant(): boolean;

package/dist/instance/internal-api/serialization/ClientReactiveSerializableInstance.d.ts

@@ -0,0 +1,14 @@
+import { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
+import { AncestorNodeValidationState } from '../../../client/validation.ts';
+import { Root } from '../../Root.ts';
+import { 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;
+}
+export {};

package/dist/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.d.ts

@@ -0,0 +1,32 @@
+import { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import { EscapedXMLText } from '../../../lib/xml-serialization.ts';
+import { 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;
+}
+export {};

package/dist/instance/internal-api/serialization/ClientReactiveSerializableParentNode.d.ts

@@ -0,0 +1,18 @@
+import { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import { 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/dist/instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.d.ts

@@ -0,0 +1,13 @@
+import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import { GeneralChildNode } from '../../hierarchy.ts';
+import { 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/dist/instance/internal-api/serialization/ClientReactiveSerializableValueNode.d.ts

@@ -0,0 +1,21 @@
+import { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import { 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;
+}
+export {};

package/dist/instance/repeat/BaseRepeatRange.d.ts

@@ -1,23 +1,25 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { FormNodeID } from '../../client/identity.ts';
+import { AnyRepeatDefinition } from '../../client/index.ts';
 import { NodeAppearances } from '../../client/NodeAppearances.ts';
 import { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
-import { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import { InstanceState } from '../../client/serialization/InstanceState.ts';
 import { TextRange } from '../../client/TextRange.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
 import { XFormsXPathNodeRange, XFormsXPathNodeRangeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
-import { AnyRepeatRangeDefinition, ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { ControlledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
-import { RepeatInstance, RepeatDefinition } from './RepeatInstance.ts';
+import { ClientReactiveSerializableParentNode } from '../internal-api/serialization/ClientReactiveSerializableParentNode.ts';
+import { RepeatInstance } from './RepeatInstance.ts';
 interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
     readonly hint: null;
     readonly label: Accessor<TextRange<'label'> | null>;
@@ -25,8 +27,8 @@ interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
     readonly valueOptions: null;
     readonly value: null;
 }
-type BaseRepeatRangeNodeType<Definition extends AnyRepeatRangeDefinition> = Definition extends ControlledRepeatRangeDefinition ? 'repeat-range:controlled' : 'repeat-range:uncontrolled';
-export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition> extends DescendantNode<Definition, RepeatRangeStateSpec, GeneralParentNode, RepeatInstance> implements BaseRepeatRangeNode, XFormsXPathNodeRange, EvaluationContext, ClientReactiveSubmittableParentNode<RepeatInstance> {
+type BaseRepeatRangeNodeType<Definition extends AnyRepeatDefinition> = Definition extends ControlledRepeatDefinition ? 'repeat-range:controlled' : 'repeat-range:uncontrolled';
+export declare abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition> extends DescendantNode<Definition, RepeatRangeStateSpec, GeneralParentNode, RepeatInstance> implements BaseRepeatRangeNode, XFormsXPathNodeRange, EvaluationContext, ClientReactiveSerializableParentNode<RepeatInstance> {
     protected readonly childrenState: ChildrenState<RepeatInstance>;
     /**
      * A repeat range doesn't have a corresponding primary instance element of its
@@ -101,14 +103,15 @@ export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeD
      * appearances" should apply, under which circumstances.
      */
     abstract readonly appearances: NodeAppearances<Definition>;
+    readonly nodeOptions: null;
     readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
     abstract readonly validationState: AncestorNodeValidationState;
-    readonly submissionState: SubmissionState;
+    readonly instanceState: InstanceState;
     constructor(parent: GeneralParentNode, definition: Definition);
     protected getLastIndex(): number;
     getInstanceIndex(instance: RepeatInstance): number;
     private createChildren;
-    protected addChildren(afterIndex: number, definitions: readonly RepeatDefinition[]): readonly RepeatInstance[];
+    protected addChildren(afterIndex: number, instanceNodes: readonly StaticElement[]): readonly RepeatInstance[];
     protected removeChildren(startIndex: number, count: number): readonly RepeatInstance[];
     getChildren(): readonly RepeatInstance[];
 }

package/dist/instance/repeat/RepeatInstance.d.ts

@@ -1,11 +1,12 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { FormNodeID } from '../../client/identity.ts';
-import { RepeatDefinition, RepeatInstanceNode, RepeatInstanceNodeAppearances } from '../../client/repeat/RepeatInstanceNode.ts';
-import { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import { AnyRepeatDefinition, RepeatInstanceNode, RepeatInstanceNodeAppearances } from '../../client/repeat/RepeatInstanceNode.ts';
+import { InstanceState } from '../../client/serialization/InstanceState.ts';
 import { TextRange } from '../../client/TextRange.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
 import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -13,11 +14,12 @@ import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNod
 import { DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
 import { GeneralChildNode, RepeatRange } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
-export type { RepeatDefinition };
+import { 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;
@@ -25,7 +27,7 @@ interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
 interface RepeatInstanceOptions {
     readonly precedingInstance: RepeatInstance | null;
 }
-export declare class RepeatInstance extends DescendantNode<RepeatDefinition, RepeatInstanceStateSpec, RepeatRange, GeneralChildNode> implements RepeatInstanceNode, XFormsXPathElement, EvaluationContext, ClientReactiveSubmittableParentNode<GeneralChildNode> {
+export declare class RepeatInstance extends DescendantNode<AnyRepeatDefinition, RepeatInstanceStateSpec, RepeatRange, GeneralChildNode> implements RepeatInstanceNode, XFormsXPathElement, EvaluationContext, ClientReactiveSerializableTemplatedNode {
     readonly parent: RepeatRange;
     private readonly childrenState;
     private readonly currentIndex;
@@ -58,9 +60,11 @@ export declare class RepeatInstance extends DescendantNode<RepeatDefinition, Rep
      * @see {@link RepeatRange.appearances}
      */
     readonly appearances: RepeatInstanceNodeAppearances;
+    readonly nodeOptions: null;
     readonly currentState: MaterializedChildren<CurrentState<RepeatInstanceStateSpec>, GeneralChildNode>;
     readonly validationState: AncestorNodeValidationState;
-    readonly submissionState: SubmissionState;
-    constructor(parent: RepeatRange, definition: RepeatDefinition, options: RepeatInstanceOptions);
+    readonly instanceState: InstanceState;
+    constructor(parent: RepeatRange, instanceNode: StaticElement | null, options: RepeatInstanceOptions);
     getChildren(): readonly GeneralChildNode[];
 }
+export {};

package/dist/instance/repeat/RepeatRangeControlled.d.ts

@@ -2,14 +2,38 @@ import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeN
 import { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
 import { XFormsXPathNodeRange } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { ControlledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { BaseRepeatRange } from './BaseRepeatRange.ts';
-export declare class RepeatRangeControlled extends BaseRepeatRange<ControlledRepeatRangeDefinition> implements RepeatRangeControlledNode, XFormsXPathNodeRange, EvaluationContext {
+export declare class RepeatRangeControlled extends BaseRepeatRange<ControlledRepeatDefinition> implements RepeatRangeControlledNode, XFormsXPathNodeRange, EvaluationContext {
+    private readonly isInstanceCreation;
+    private readonly countControlType;
     readonly nodeType = "repeat-range:controlled";
     readonly appearances: RepeatRangeNodeAppearances;
     readonly validationState: AncestorNodeValidationState;
-    constructor(parent: GeneralParentNode, definition: ControlledRepeatRangeDefinition);
+    constructor(parent: GeneralParentNode, instanceNodes: readonly StaticElement[], definition: ControlledRepeatDefinition);
     private initializeControlledChildrenState;
+    /**
+     * 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;
 }

package/dist/instance/repeat/RepeatRangeUncontrolled.d.ts

@@ -2,16 +2,17 @@ import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeN
 import { RepeatRangeUncontrolledNode } from '../../client/repeat/RepeatRangeUncontrolledNode.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
 import { XFormsXPathNodeRange } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { UncontrolledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { Root } from '../Root.ts';
 import { BaseRepeatRange } from './BaseRepeatRange.ts';
-export declare class RepeatRangeUncontrolled extends BaseRepeatRange<UncontrolledRepeatRangeDefinition> implements RepeatRangeUncontrolledNode, XFormsXPathNodeRange, EvaluationContext {
+export declare class RepeatRangeUncontrolled extends BaseRepeatRange<UncontrolledRepeatDefinition> implements RepeatRangeUncontrolledNode, XFormsXPathNodeRange, EvaluationContext {
     readonly nodeType = "repeat-range:uncontrolled";
     readonly appearances: RepeatRangeNodeAppearances;
     readonly validationState: AncestorNodeValidationState;
-    constructor(parent: GeneralParentNode, definition: UncontrolledRepeatRangeDefinition);
+    constructor(parent: GeneralParentNode, instanceNodes: readonly StaticElement[], definition: UncontrolledRepeatDefinition);
     addInstances(afterIndex?: number, count?: number): Root;
     /**
      * Removes the {@link RepeatInstance}s corresponding to the specified range of