@getodk/xforms-engine 0.6.0 → 0.8.0

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,7 +17,7 @@ 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>;
@@ -25,7 +26,8 @@ export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpe
     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>;
@@ -39,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/attachments/InstanceAttachment.d.ts

@@ -0,0 +1,42 @@
+import { Accessor } from 'solid-js';
+import { SimpleAtomicState, SimpleAtomicStateSetter } from '../../lib/reactivity/types.ts';
+import { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import { DecodeInstanceValue } from '../internal-api/InstanceValueContext.ts';
+export type InstanceAttachmentFileName = string;
+export type InstanceAttachmentRuntimeValue = File | null;
+export interface InstanceAttachmentOptions {
+    readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+    readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+    readonly decodeInstanceValue: DecodeInstanceValue;
+    readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+    readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+    readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+}
+export declare class InstanceAttachment {
+    /**
+     * 1. Creates {@link InstanceAttachment | attachment state} from
+     *    {@link InstanceAttachmentOptions}
+     * 2. Registers that attachment state in an instance-global
+     *    {@link InstanceAttachmentsState} entry
+     *
+     * This allows an instance to:
+     *
+     * - Produce distinct file names for each attachment
+     * - Track all attachments so they can be serialized in an
+     *   {@link InstancePayload}
+     */
+    static init(context: InstanceAttachmentContext, options: InstanceAttachmentOptions): InstanceAttachment;
+    /**
+     * This property isn't used at runtime. It causes TypeScript to treat
+     * {@link InstanceAttachment} as a nominal type, ensuring
+     * {@link InstanceAttachment.init} is called to instantiate it.
+     */
+    protected readonly _: null;
+    readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+    readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+    readonly decodeInstanceValue: DecodeInstanceValue;
+    readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+    readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+    readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+    private constructor();
+}

package/dist/instance/attachments/InstanceAttachmentsState.d.ts

@@ -0,0 +1,9 @@
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { InstanceAttachmentMap } from '../input/InstanceAttachmentMap.ts';
+import { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import { InstanceAttachment, InstanceAttachmentRuntimeValue } from './InstanceAttachment.ts';
+export declare class InstanceAttachmentsState extends Map<InstanceAttachmentContext, InstanceAttachment> {
+    private readonly sourceAttachments;
+    constructor(sourceAttachments?: InstanceAttachmentMap | null);
+    getInitialFileValue(instanceNode: StaticLeafElement | null): InstanceAttachmentRuntimeValue;
+}

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

@@ -4,6 +4,7 @@ import { AnyModelValue } from './ModelValue.ts';
 import { AnyNote } from './Note.ts';
 import { PrimaryInstance } from './PrimaryInstance.ts';
 import { AnyRangeControl } from './RangeControl.ts';
+import { RankControl } from './RankControl.ts';
 import { RepeatInstance } from './repeat/RepeatInstance.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
@@ -11,13 +12,11 @@ import { Root } from './Root.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';
+import { UploadControl } from './UploadControl.ts';
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
-export type AnyUnsupportedControl = UploadControl;
-export type AnyNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance | AnyNote | AnyModelValue | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | AnyUnsupportedControl;
+export type AnyNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance | AnyNote | AnyModelValue | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | UploadControl;
 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 | 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;
+export type AnyChildNode = Root | Group | Subtree | RepeatRange | RepeatInstance | AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | UploadControl;
+export type GeneralChildNode = Group | Subtree | RepeatRange | AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | UploadControl;
+export type AnyValueNode = AnyModelValue | AnyNote | AnyInputControl | AnyRangeControl | RankControl | SelectControl | TriggerControl | UploadControl;

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/InstanceAttachmentContext.d.ts

@@ -0,0 +1,19 @@
+import { Accessor } from 'solid-js';
+import { FormNodeID } from '../../client/identity.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { InstanceAttachmentsState } from '../attachments/InstanceAttachmentsState.ts';
+import { InstanceConfig } from './InstanceConfig.ts';
+interface InstanceAttachmentRootDocument {
+    readonly attachments: InstanceAttachmentsState;
+}
+export interface InstanceAttachmentContext {
+    readonly instanceConfig: InstanceConfig;
+    readonly scope: ReactiveScope;
+    readonly rootDocument: InstanceAttachmentRootDocument;
+    readonly nodeId: FormNodeID;
+    readonly instanceNode: StaticLeafElement | null;
+    readonly isRelevant: Accessor<boolean>;
+    readonly isAttached: Accessor<boolean>;
+}
+export {};

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

@@ -1,14 +1,9 @@
-import { MissingResourceBehavior } from '../../client/constants.ts';
+import { InstanceAttachmentFileNameFactory } from '../../client/attachments/InstanceAttachmentsConfig.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;
+    readonly computeAttachmentName: InstanceAttachmentFileNameFactory;
 }

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

@@ -1,7 +1,12 @@
+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;
@@ -10,11 +15,13 @@ 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;
     isRelevant(): boolean;

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

@@ -0,0 +1,16 @@
+import { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
+import { AncestorNodeValidationState } from '../../../client/validation.ts';
+import { InstanceAttachmentsState } from '../../attachments/InstanceAttachmentsState.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 attachments: InstanceAttachmentsState;
+    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
@@ -104,12 +106,12 @@ export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeD
     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;
@@ -61,7 +63,8 @@ export declare class RepeatInstance extends DescendantNode<RepeatDefinition, Rep
     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

package/dist/instance/resource.d.ts

@@ -1,4 +1,4 @@
-import { FormResource } from '../client/index.ts';
+import { FormResource } from '../client/form/FormResource.ts';
 import { FetchResource, FetchResourceResponse } from '../client/resources.ts';
 export type { FetchResource, FetchResourceResponse, FormResource };
 export interface ResourceOptions {
@@ -8,3 +8,7 @@ declare const resourceXMLPrefix = "<";
 type ResourceXMLPrefix = typeof resourceXMLPrefix;
 type ResourceXML = `${ResourceXMLPrefix}${string}`;
 export declare const retrieveSourceXMLResource: (resource: FormResource, options: ResourceOptions) => Promise<ResourceXML>;
+interface RetrieveFormDefinitionOptions {
+    readonly fetchFormDefinition: FetchResource;
+}
+export declare const retrieveFormDefinition: (resource: FormResource, options: RetrieveFormDefinitionOptions) => Promise<ResourceXML>;

package/dist/integration/xpath/EngineXPathEvaluator.d.ts

@@ -1,7 +1,7 @@
 import { XFormsItextTranslationMap, XFormsSecondaryInstanceMap, XFormsXPathEvaluator } from '@getodk/xpath';
 import { PrimaryInstance } from '../../instance/PrimaryInstance.ts';
-import { ItextTranslationRootDefinition } from '../../parse/model/ItextTranslation/ItextTranslationRootDefinition.ts';
-import { SecondaryInstanceRootDefinition } from '../../parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts';
+import { ItextTranslationRootDefinition } from '../../parse/model/ItextTranslationsDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
 import { EngineXPathNode } from './adapter/kind.ts';
 interface EngineXPathEvaluatorOptions {
     readonly rootNode: PrimaryInstance;