@getodk/xforms-engine 0.6.0 → 0.7.0

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/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,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,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
@@ -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/instance/unsupported/UploadControl.d.ts

@@ -1,6 +1,34 @@
-import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
-import { ValueContext } from '../internal-api/ValueContext.ts';
-export declare class UploadControl extends UnsupportedControl<'upload'> implements ValueContext<unknown> {
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
+import { TextRange } from '../../client/TextRange.ts';
+import { ValueType } from '../../client/ValueType.ts';
+import { UploadNode, UploadNodeDefinition } from '../../client/unsupported/UploadNode.ts';
+import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { TempUnsupportedInputValue, TempUnsupportedRuntimeValue } from '../../lib/codecs/TempUnsupportedControlCodec.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 { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
+import { ValueNode, ValueNodeStateSpec } from '../abstract/ValueNode.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { ValidationContext } from '../internal-api/ValidationContext.ts';
+import { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
+interface UploadControlStateSpec extends ValueNodeStateSpec<TempUnsupportedRuntimeValue> {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: Accessor<TextRange<'hint'> | null>;
+    readonly valueOptions: null;
+}
+export declare class UploadControl extends ValueNode<ValueType, UploadNodeDefinition, TempUnsupportedRuntimeValue, TempUnsupportedInputValue> implements UploadNode, XFormsXPathElement, EvaluationContext, ValidationContext, ClientReactiveSerializableValueNode {
+    readonly [XPathNodeKindKey] = "element";
+    protected readonly state: SharedNodeState<UploadControlStateSpec>;
+    protected readonly engineState: EngineState<UploadControlStateSpec>;
     readonly nodeType = "upload";
-    readonly contextNode: this;
+    readonly appearances: UnknownAppearanceDefinition;
+    readonly nodeOptions: null;
+    readonly currentState: CurrentState<UploadControlStateSpec>;
+    constructor(parent: GeneralParentNode, instanceNode: StaticLeafElement | null, definition: UploadNodeDefinition);
+    setValue(_: never): never;
 }
+export {};

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;

package/dist/integration/xpath/adapter/kind.d.ts

@@ -1,11 +1,6 @@
 import { XPathNodeKind } from '@getodk/xpath';
-import { AnyChildNode, AnyNode, AnyParentNode, AnyValueNode } from '../../../instance/hierarchy.ts';
-import { ValueContext } from '../../../instance/internal-api/ValueContext.ts';
+import { AnyChildNode, AnyNode, AnyParentNode } from '../../../instance/hierarchy.ts';
 import { PrimaryInstance } from '../../../instance/PrimaryInstance.ts';
-import { ItextTranslationDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationDefinition.ts';
-import { ItextTranslationRootDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationRootDefinition.ts';
-import { SecondaryInstanceDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceDefinition.ts';
-import { SecondaryInstanceRootDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts';
 import { StaticAttribute } from '../static-dom/StaticAttribute.ts';
 import { StaticDocument } from '../static-dom/StaticDocument.ts';
 import { StaticElement } from '../static-dom/StaticElement.ts';
@@ -15,16 +10,15 @@ export type PrimaryInstanceXPathNode = Extract<AnyNode, XFormsXPathPrimaryInstan
 export type PrimaryInstanceXPathElement = Extract<AnyChildNode, XFormsXPathElement>;
 export type PrimaryInstanceXPathComment = Extract<AnyChildNode, XFormsXPathComment>;
 export type PrimaryInstanceXPathChildNode = PrimaryInstanceXPathElement | PrimaryInstanceXPathComment;
-export type PrimaryInstanceXPathValueElement<Value> = AnyValueNode & ValueContext<Value> & XFormsXPathElement;
-export type EngineXPathDocument = PrimaryInstance | ItextTranslationDefinition | SecondaryInstanceDefinition | StaticDocument;
-export type EngineXPathElement = PrimaryInstanceXPathElement | ItextTranslationRootDefinition | SecondaryInstanceRootDefinition | StaticElement;
+export type EngineXPathDocument = PrimaryInstance | StaticDocument;
+export type EngineXPathElement = PrimaryInstanceXPathElement | StaticElement;
 export type EngineXPathComment = PrimaryInstanceXPathComment;
 export type EngineXPathAttribute = StaticAttribute;
 export type EngineXPathText = StaticText;
 export type XFormsXPathChildNode = EngineXPathElement | EngineXPathText | EngineXPathComment;
 type XPathAdapterParentNode = XFormsXPathDocument | XFormsXPathElement;
 type PrimaryInstanceXPathParentNode = Extract<AnyParentNode, XPathAdapterParentNode>;
-export type EngineXPathParentNode = PrimaryInstanceXPathParentNode | ItextTranslationDefinition | SecondaryInstanceDefinition | ItextTranslationRootDefinition | SecondaryInstanceRootDefinition | StaticDocument | StaticElement;
+export type EngineXPathParentNode = PrimaryInstanceXPathParentNode | StaticDocument | StaticElement;
 export type EngineXPathNode = EngineXPathDocument | EngineXPathElement | EngineXPathAttribute | EngineXPathText | EngineXPathComment;
 export declare const isEngineXPathNode: (value: unknown) => value is EngineXPathNode;
 export declare const getEngineXPathNodeKind: (node: EngineXPathNode) => XPathNodeKind;

package/dist/integration/xpath/static-dom/StaticAttribute.d.ts

@@ -4,10 +4,9 @@ import { XFormsXPathAttribute } from '../adapter/XFormsXPathNode.ts';
 import { StaticDocument } from './StaticDocument.ts';
 import { StaticElement } from './StaticElement.ts';
 import { StaticNode } from './StaticNode.ts';
-interface StaticAttributeOptions {
-    readonly namespaceURI: string | null;
-    readonly prefix?: string | null;
-    readonly localName: string;
+import { StaticNodeNameSource } from './staticNodeName.ts';
+export interface StaticAttributeOptions {
+    readonly name: StaticNodeNameSource;
     readonly value: string;
 }
 export declare class StaticAttribute extends StaticNode<'attribute'> implements XFormsXPathAttribute {
@@ -17,10 +16,10 @@ export declare class StaticAttribute extends StaticNode<'attribute'> implements
     readonly rootDocument: StaticDocument;
     readonly root: StaticElement;
     readonly qualifiedName: QualifiedName;
+    readonly nodeset: string;
     readonly attributes: readonly [];
     readonly children: null;
     readonly value: string;
     constructor(parent: StaticElement, options: StaticAttributeOptions);
     getXPathValue(): string;
 }
-export {};

package/dist/integration/xpath/static-dom/StaticDocument.d.ts

@@ -1,15 +1,18 @@
-import { XPathNodeKindKey } from '@getodk/xpath';
 import { XFormsXPathDocument } from '../adapter/XFormsXPathNode.ts';
-import { StaticElement } from './StaticElement.ts';
-import { StaticNode } from './StaticNode.ts';
-export type StaticDocumentRootFactory<T extends StaticDocument, Root extends StaticElement> = (staticDocument: T) => Root;
-export declare abstract class StaticDocument<DocumentRoot extends StaticElement = StaticElement> extends StaticNode<'document'> implements XFormsXPathDocument {
-    readonly [XPathNodeKindKey] = "document";
-    readonly nodeType = "static-document";
+import { StaticElementOptions, StaticElement } from './StaticElement.ts';
+import { StaticParentNode } from './StaticParentNode.ts';
+interface StaticDocumentOptions {
+    readonly documentRoot: StaticElementOptions;
+    readonly nodesetPrefix?: string;
+}
+export declare class StaticDocument extends StaticParentNode<'document'> implements XFormsXPathDocument {
     readonly rootDocument: StaticDocument;
-    readonly root: DocumentRoot;
+    readonly root: StaticElement;
     readonly parent: null;
-    readonly children: readonly [root: DocumentRoot];
-    constructor(rootFactory: StaticDocumentRootFactory<StaticDocument<DocumentRoot>, DocumentRoot>);
+    readonly nodeset: string;
+    readonly children: readonly [root: StaticElement];
+    readonly childElements: readonly [root: StaticElement];
+    constructor(options: StaticDocumentOptions);
     getXPathValue(): string;
 }
+export {};