@getodk/xforms-engine 0.4.0 → 0.5.0

package/dist/client/BaseNode.d.ts

@@ -1,7 +1,9 @@
 import { AnyNodeDefinition } from '../parse/model/NodeDefinition.ts';
 import { NodeAppearances } from './NodeAppearances.ts';
 import { TextRange } from './TextRange.ts';
+import { FormNodeID } from './identity.ts';
 import { InstanceNodeType } from './node-types.ts';
+import { SubmissionState } from './submission/SubmissionState.ts';
 import { NodeValidationState } from './validation.ts';
 export interface BaseNodeState {
     /**
@@ -113,7 +115,6 @@ export interface BaseNodeState {
      */
     get value(): unknown;
 }
-type FormNodeID = string;
 /**
  * Base interface for common/shared aspects of any node type.
  */
@@ -153,7 +154,7 @@ export interface BaseNode {
      * Each node links back to its parent, if any. All nodes have a parent except
      * the form's {@link root}.
      */
-    readonly parent: BaseNode | null;
+    readonly parent: unknown;
     /**
      * Each node provides a discrete object representing the stateful aspects\* of
      * that node which will change over time. When a client provides a
@@ -205,5 +206,15 @@ export interface BaseNode {
      * clients to explicitly pause and resume recomputation.
      */
     readonly validationState: NodeValidationState;
+    /**
+     * Represents the current submission state of the node.
+     *
+     * @see {@link SubmissionState.submissionXML} for additional detail.
+     *
+     * @todo Consider whether this can (should) be merged with
+     * {@link currentState}, while providing the same client-reactivity
+     * guarantees. (The challenge there is in defining client-reactive state which
+     * self-referentially derives state from its own definition.)
+     */
+    readonly submissionState: SubmissionState;
 }
-export {};

package/dist/client/BaseValueNode.d.ts

@@ -0,0 +1,32 @@
+import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeType } from './node-types.ts';
+import { LeafNodeValidationState } from './validation.ts';
+import { ValueType } from './ValueType.ts';
+export interface BaseValueNodeState<Value> extends BaseNodeState {
+    get children(): null;
+    get valueOptions(): null;
+    get value(): Value;
+    /**
+     * Reflects the serialized string representation of a {@link BaseValueNode}'s
+     * {@link value} state. This representation allows access to the node's value
+     * _as primary instance state_. In other words, this is the value which:
+     *
+     * - would be serialized as a text node in
+     *   {@link SubmissionState.submissionXML} (note: this value is **NOT**
+     *   escaped for XML serialization, as it is there)
+     *
+     * - is used when the node's value is referenced in any of a form's XPath
+     *   expressions
+     */
+    get instanceValue(): string;
+}
+export interface BaseValueNode<V extends ValueType = ValueType, Value = string> extends BaseNode {
+    readonly nodeType: LeafNodeType;
+    readonly valueType: V;
+    readonly definition: LeafNodeDefinition;
+    readonly parent: GeneralParentNode;
+    readonly currentState: BaseValueNodeState<Value>;
+    readonly validationState: LeafNodeValidationState;
+}

package/dist/client/EngineConfig.d.ts

@@ -1,32 +1,6 @@
+import { MissingResourceBehavior } from './constants.ts';
 import { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
-/**
- * @todo this is currently a strict subset of the web standard `Response`. Is it
- * sufficient? Ways it might not be:
- *
- * - No way to convey metadata about the resource
- * - Ambiguous if a client supplies an alternative implementation which doesn't
- *   exhaust the body on access
- */
-export interface FetchResourceResponse {
-    readonly ok?: boolean;
-    readonly body?: ReadableStream<Uint8Array> | null;
-    readonly bodyUsed?: boolean;
-    readonly blob: () => Promise<Blob>;
-    readonly text: () => Promise<string>;
-}
-/**
- * @todo this is a strict subset of the web standard `fetch` interface. It
- * implicitly assumes that the engine itself will only ever issue `GET`-like
- * requests. It also provides no further request-like semantics to the engine.
- * This is presumed sufficient for now, but notably doesn't expose any notion of
- * content negotiation (e.g. the ability to supply `Accept` headers).
- *
- * This also completely ignores any notion of mapping
- * {@link https://getodk.github.io/xforms-spec/#uris | `jr:` URLs} to their
- * actual resources (likely, but not necessarily, accessed at a corresponding
- * HTTP URL).
- */
-export type FetchResource = (resource: URL) => Promise<FetchResourceResponse>;
+import { FetchFormAttachment, FetchResource } from './resources.ts';
 /**
  * Options provided by a client to specify certain aspects of engine runtime
  * behavior. These options will generally be intended to facilitate cooperation
@@ -50,29 +24,56 @@ export interface EngineConfig {
      */
     readonly stateFactory?: OpaqueReactiveObjectFactory;
     /**
-     * A client may specify a generic function for retrieving resources referenced
-     * by a form, such as:
      *
-     * - Form definitions themselves (if not provided directly to the engine by
-     *   the client)
-     * - External secondary instances
-     * - Media (images, audio, video, etc.)
+     * A client may specify an arbitrary {@link fetch}-like function for retrieving an XML XForm form
+     * definition.
+     *
+     * Notes:
      *
-     * The function is expected to be a subset of the
-     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API},
-     * performing `GET` requests for:
+     * - This configuration will only be consuled for calls to
+     *   {@link initializeForm} with a URL referencing an XML XForm definition. It
+     *   will be ignored for calls passing an XML XForm form definition directly.
      *
-     * - Text resources (e.g. XML, CSV, JSON/GeoJSON)
-     * - Binary resources (e.g. media)
-     * - Optionally streamed binary data of either (e.g. for optimized
-     *   presentation of audio/video)
+     * - For calls to {@link initializeForm} with a URL, if this configuration is
+     *   not specified it will default to the global {@link fetch} function (if
+     *   one is defined).
+     */
+    readonly fetchFormDefinition?: FetchResource;
+    /**
+     * A client may specify an arbitrary {@link fetch}-like function to retrieve a
+     * form's attachments, i.e. any `jr:` URL referenced by the form (as specified
+     * by {@link https://getodk.github.io/xforms-spec/ | ODK XForms}).
+     *
+     * Notes:
+     *
+     * - This configuration will be consulted for all supported form attachments,
+     *   as a part of {@link initializeForm | form initialization}.
+     *
+     * - If this configuration is not specified it will default to the global
+     *   {@link fetch} function (if one is defined).
+     *
+     * This default behavior will typically result in failure to load form
+     * attachments—and in most cases this will also cause
+     * {@link initializeForm | form initialization} to fail overall—with the
+     * following exceptions:
+     *
+     * - **CLIENT-SPECIFIC:** Usage in coordination with a client-implemented
+     *   {@link https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API | Serivce Worker},
+     *   which can intercept network requests **generally**. Clients already using
+     *   a Service Worker may opt for the convenience of handling network requests
+     *   for `jr:` URLs along with any other network interception logic. Client
+     *   implementors should be warned, however, that such `jr:` URLs are not
+     *   namespaced or otherwise scoped to a particular form; such a client would
+     *   therefore inherently need to coordinate state between the Service Worker
+     *   and the main thread (or whatever other realm calls
+     *   {@link initializeForm}).
+     */
+    readonly fetchFormAttachment?: FetchFormAttachment;
+    /**
+     * @see {@link MissingResourceBehavior}
+     * @see {@link MissingResourceBehaviorDefault}
      *
-     * If provided by a client, this function will be used by the engine to
-     * retrieve any such resource, as required for engine functionality. If
-     * absent, the engine will use the native `fetch` function (if available, a
-     * polyfill otherwise). Clients may use this function to provide resources
-     * from sources other than the network, (or even in a test client to provide
-     * e.g. resources from test fixtures).
+     * @default MissingResourceBehaviorDefault
      */
-    readonly fetchResource?: FetchResource;
+    readonly missingResourceBehavior?: MissingResourceBehavior;
 }

package/dist/client/InputNode.d.ts

@@ -0,0 +1,53 @@
+import { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
+import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
+import { RootNode } from './RootNode.ts';
+import { ValueType } from './ValueType.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeValidationState } from './validation.ts';
+export type InputValue<V extends ValueType> = RuntimeValue<V>;
+export type InputNodeInputValue<V extends ValueType> = RuntimeInputValue<V>;
+export interface InputNodeState<V extends ValueType> extends BaseValueNodeState<InputValue<V>> {
+    get children(): null;
+    get valueOptions(): null;
+    /**
+     * Reflects the current value of a {@link InputNode}. This value may be
+     * populated when a form is loaded, and it may be updated by certain
+     * computations defined by the form. It may also be updated by a client, using
+     * the {@link InputNode.setValue} method.
+     */
+    get value(): InputValue<V>;
+}
+export interface InputDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+    readonly bodyElement: InputControlDefinition;
+}
+export type InputNodeAppearances = NodeAppearances<InputDefinition>;
+/**
+ * A node corresponding to form field defined as an
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | XForms `<input>`},
+ * which a user-facing client would likely present for a user to fill..
+ */
+export interface InputNode<V extends ValueType = ValueType> extends BaseValueNode<V, InputValue<V>> {
+    readonly nodeType: 'input';
+    readonly valueType: V;
+    readonly appearances: InputNodeAppearances;
+    readonly definition: InputDefinition<V>;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: InputNodeState<V>;
+    readonly validationState: LeafNodeValidationState;
+    /**
+     * For use by a client to update the value of an {@link InputNode}.
+     */
+    setValue(value: InputNodeInputValue<V>): RootNode;
+}
+export type StringInputNode = InputNode<'string'>;
+export type IntInputNode = InputNode<'int'>;
+export type DecimalInputNode = InputNode<'decimal'>;
+type SupportedInputValueType = 'string' | 'int' | 'decimal';
+type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
+export type TemporaryStringValueInputNode = InputNode<TemporaryStringValueType>;
+export type AnyInputNode = StringInputNode | IntInputNode | DecimalInputNode | TemporaryStringValueInputNode;
+export {};

package/dist/client/ModelValueNode.d.ts

@@ -1,9 +1,12 @@
+import { RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
 import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { RootNode } from './RootNode.ts';
 import { LeafNodeValidationState } from './validation.ts';
-export interface ModelValueNodeState extends BaseNodeState {
+import { ValueType } from './ValueType.ts';
+export type ModelValue<V extends ValueType> = RuntimeValue<V>;
+export interface ModelValueNodeState<V extends ValueType> extends BaseValueNodeState<ModelValue<V>> {
     get label(): null;
     get hint(): null;
     get children(): null;
@@ -13,9 +16,9 @@ export interface ModelValueNodeState extends BaseNodeState {
      * populated when a form is loaded, and it may be updated by certain
      * computations defined by the form.
      */
-    get value(): string;
+    get value(): ModelValue<V>;
 }
-export interface ModelValueDefinition extends LeafNodeDefinition {
+export interface ModelValueDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
     readonly bodyElement: null;
 }
 /**
@@ -25,12 +28,14 @@ export interface ModelValueDefinition extends LeafNodeDefinition {
  * - a leaf/value node (i.e. it has no element children; it may be defined in
  *   the form's `<model>` as either an {@link Element} or {@link Attr})
  */
-export interface ModelValueNode extends BaseNode {
+export interface ModelValueNode<V extends ValueType = ValueType> extends BaseValueNode<V, ModelValue<V>> {
     readonly nodeType: 'model-value';
+    readonly valueType: V;
     readonly appearances: null;
-    readonly definition: ModelValueDefinition;
+    readonly definition: ModelValueDefinition<V>;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
-    readonly currentState: ModelValueNodeState;
+    readonly currentState: ModelValueNodeState<V>;
     readonly validationState: LeafNodeValidationState;
 }
+export type AnyModelValueNode = ModelValueNode<'barcode'> | ModelValueNode<'binary'> | ModelValueNode<'boolean'> | ModelValueNode<'date'> | ModelValueNode<'dateTime'> | ModelValueNode<'decimal'> | ModelValueNode<'geopoint'> | ModelValueNode<'geoshape'> | ModelValueNode<'geotrace'> | ModelValueNode<'int'> | ModelValueNode<'intent'> | ModelValueNode<'string'> | ModelValueNode<'time'>;

package/dist/client/NoteNode.d.ts

@@ -1,4 +1,4 @@
-import { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
 import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
@@ -32,7 +32,7 @@ export interface NoteNodeState extends BaseNodeState {
     get value(): string | null;
 }
 export interface NoteDefinition extends LeafNodeDefinition {
-    readonly bodyElement: InputDefinition;
+    readonly bodyElement: InputControlDefinition;
 }
 export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
 /**

package/dist/client/RootNode.d.ts

@@ -3,13 +3,13 @@ import { RootDefinition } from '../parse/model/RootDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import { GeneralChildNode } from './hierarchy.ts';
+import { SubmissionChunkedType, SubmissionOptions } from './submission/SubmissionOptions.ts';
+import { SubmissionResult } from './submission/SubmissionResult.ts';
 import { AncestorNodeValidationState } from './validation.ts';
 export interface RootNodeState extends BaseNodeState {
     /**
-     * This, along with {@link RootNode.languages} is the most significant break
-       in consistency across node types' state and static properties. Exposing it
-       across all node types seems like a point of potential confusion, so this
-       particular divergence seems like the most reasonable compromise.
+     * @todo If we ever expose an interface to the primary instance document, it
+     * would make sense to move this state up.
      */
     get activeLanguage(): ActiveLanguage;
     get label(): null;
@@ -40,13 +40,40 @@ export interface RootNode extends BaseNode {
     readonly classes: BodyClassList;
     readonly definition: RootDefinition;
     readonly root: RootNode;
-    readonly parent: null;
+    readonly parent: unknown;
     readonly currentState: RootNodeState;
     readonly validationState: AncestorNodeValidationState;
     /**
-     * @todo as with {@link RootNodeState.activeLanguage}, this is the most
-     * significant break in consistency across node types.
+     * @todo as discussed on {@link RootNodeState.activeLanguage}
      */
     readonly languages: FormLanguages;
     setLanguage(language: FormLanguage): RootNode;
+    /**
+     * Prepares the current form instance state for submission.
+     *
+     * A {@link SubmissionResult} will be prepared even if the current form state
+     * includes `constraint` or `required` violations. This is intended to serve
+     * two purposes:
+     *
+     * - A client may effectively use this method as a part of its own "submit"
+     *   routine, and use any violations included in the {@link SubmissionResult}
+     *   to prompt users to address those violations.
+     *
+     * - A client may inspect the submission state of a form at any time.
+     *   Depending on the client and use case, this may be a convenience (e.g. for
+     *   developers to inspect that form state at a current point in time); or it
+     *   may provide necessary functionality (e.g. for test or tooling clients).
+     *
+     * Note on asynchrony: preparing a {@link SubmissionResult} is expected to be
+     * a fast operation. It may even be nearly instantaneous, or roughly
+     * proportionate to the size of the form itself. However, this method is
+     * designed to be asynchronous out of an abundance of caution, anticipating
+     * that some as-yet undeveloped operations on binary data (e.g. form
+     * attachments) may themselves impose asynchrony (i.e. by interfaces provided
+     * by the platform and/or external dependencies).
+     *
+     * A client may specify {@link SubmissionOptions<'chunked'>}, in which case a
+     * {@link SubmissionResult<'chunked'>} will be produced, with form attachments
+     */
+    prepareSubmission<ChunkedType extends SubmissionChunkedType>(options?: SubmissionOptions<ChunkedType>): Promise<SubmissionResult<ChunkedType>>;
 }

package/dist/client/SelectNode.d.ts

@@ -51,7 +51,7 @@ export interface SelectNode extends BaseNode {
      * - For fields defined with an XForms `<select1>`, calling this method will
      *   replace the selection (if any).
      *
-     * @todo @see {@link StringNode.setValue} re: write restrictions
+     * @todo @see {@link InputNode.setValue} re: write restrictions
      * @todo @see {@link SelectNodeState.value} re: breaking up the types
      */
     select(item: SelectItem): RootNode;
@@ -59,7 +59,7 @@ export interface SelectNode extends BaseNode {
      * For use by a client to remove an item from the node's
      * {@link SelectNodeState.value}.
      *
-     * @todo @see {@link StringNode.setValue} re: write restrictions
+     * @todo @see {@link InputNode.setValue} re: write restrictions
      */
     deselect(item: SelectItem): RootNode;
 }

package/dist/client/ValueType.d.ts

@@ -0,0 +1,3 @@
+import { ExpandUnion } from '../../../common/types/helpers.js';
+import { BindType } from '../parse/model/BindTypeDefinition.ts';
+export type ValueType = ExpandUnion<BindType>;

package/dist/client/constants.d.ts

@@ -1,8 +1,58 @@
 import { ValidationTextRole } from './TextRange.ts';
+export declare const MISSING_RESOURCE_BEHAVIOR: {
+    /**
+     * When this behavior is configured, {@link InitializeForm | initializing} a
+     * {@link PrimaryInstance} for a form which references any **missing**
+     * resources will fail, producing an error to the calling client.
+     *
+     * @see {@link MissingResourceBehavior}
+     */
+    readonly ERROR: "ERROR";
+    /**
+     * When this behavior is configured, {@link InitializeForm | initializing} a
+     * {@link PrimaryInstance} for a form which references any **missing**
+     * resources will succeed (producing a warning).
+     *
+     * Such missing resources will be parsed as if they are blank, as appropriate
+     * for the resource's XForm semantic usage and/or format.
+     *
+     * @see {@link MissingResourceBehavior}
+     */
+    readonly BLANK: "BLANK";
+    /**
+     * @see {@link MISSING_RESOURCE_BEHAVIOR.ERROR}
+     */
+    readonly DEFAULT: "ERROR";
+};
+export type MissingResourceBehaviorError = typeof MISSING_RESOURCE_BEHAVIOR.ERROR;
+export type MissingResourceBehaviorBlank = typeof MISSING_RESOURCE_BEHAVIOR.BLANK;
+export type MissingResourceBehaviorDefault = typeof MISSING_RESOURCE_BEHAVIOR.DEFAULT;
+/**
+ * Specifies behavior for {@link InitializeForm | initializing} a form's
+ * {@link PrimaryInstance} which references any **missing** resources.
+ *
+ * Here the term "missing" is consistent with
+ * {@link https://www.rfc-editor.org/rfc/rfc9110#status.404 | HTTP 404 status}
+ * semantics. Clients which provide access to form attachments by performing
+ * HTTP network requests (e.g. with {@link fetch}) can generally convey this
+ * semantic meaning with a standard {@link Response}.
+ *
+ * **IMPORTANT**
+ *
+ * The term "missing" is distinct from other network/IO failures, e.g. when
+ * network access itself is unavailable. In these cases, the engine will
+ * consider a resource's availability **ambiguous**, producing an error
+ * regardless of the configured behavior for **missing** resources.
+ */
+export type MissingResourceBehavior = MissingResourceBehaviorError | MissingResourceBehaviorBlank;
 export declare const VALIDATION_TEXT: {
     readonly constraintMsg: "Condition not satisfied: constraint";
     readonly requiredMsg: "Condition not satisfied: required";
 };
 type ValidationTextDefaults = typeof VALIDATION_TEXT;
 export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];
+export declare const SUBMISSION_INSTANCE_FILE_NAME = "xml_submission_file";
+export type SubmissionInstanceFileName = typeof SUBMISSION_INSTANCE_FILE_NAME;
+export declare const SUBMISSION_INSTANCE_FILE_TYPE = "text/xml";
+export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;
 export {};

package/dist/client/hierarchy.d.ts

@@ -1,21 +1,21 @@
 import { ExpandUnion } from '../../../common/types/helpers.d.ts';
 import { GroupNode } from './GroupNode.ts';
-import { ModelValueNode } from './ModelValueNode.ts';
+import { AnyInputNode } from './InputNode.ts';
+import { AnyModelValueNode } from './ModelValueNode.ts';
 import { NoteNode } from './NoteNode.ts';
 import { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import { RootNode } from './RootNode.ts';
 import { SelectNode } from './SelectNode.ts';
-import { StringNode } from './StringNode.ts';
 import { SubtreeNode } from './SubtreeNode.ts';
 import { TriggerNode } from './TriggerNode.ts';
 import { RangeNode } from './unsupported/RangeNode.ts';
 import { RankNode } from './unsupported/RankNode.ts';
 import { UploadNode } from './unsupported/UploadNode.ts';
 export type AnyUnsupportedControlNode = RangeNode | RankNode | UploadNode;
-export type AnyControlNode = NoteNode | SelectNode | StringNode | TriggerNode;
-export type AnyLeafNode = AnyControlNode | AnyUnsupportedControlNode | ModelValueNode;
+export type AnyControlNode = AnyInputNode | NoteNode | SelectNode | TriggerNode;
+export type AnyLeafNode = AnyControlNode | AnyModelValueNode | AnyUnsupportedControlNode;
 export type RepeatRangeNode = RepeatRangeControlledNode | RepeatRangeUncontrolledNode;
 /**
  * Any of the concrete node types which may be a parent of non-repeat instance

package/dist/client/identity.d.ts

@@ -0,0 +1,14 @@
+type ODKXFormsUUID = `uuid:${string}`;
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type InstanceID = ODKXFormsUUID;
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type DeprecatedID = ODKXFormsUUID;
+/**
+ * Represents a session-stable identifier for any particular node i
+ */
+export type FormNodeID = `node:${string}`;
+export {};

package/dist/client/node-types.d.ts

@@ -1,3 +1,4 @@
 export type UnsupportedControlNodeType = 'range' | 'rank' | 'upload';
 export type RepeatRangeNodeType = 'repeat-range:controlled' | 'repeat-range:uncontrolled';
-export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | 'model-value' | 'note' | 'select' | 'string' | 'trigger' | UnsupportedControlNodeType;
+export type LeafNodeType = 'model-value' | 'note' | 'select' | 'input' | 'trigger' | UnsupportedControlNodeType;
+export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | LeafNodeType | UnsupportedControlNodeType;

package/dist/client/resources.d.ts

@@ -0,0 +1,93 @@
+import { JRResourceURL } from '../../../common/src/jr-resources/JRResourceURL.ts';
+interface FetchResourceHeadersIterator<T> extends IteratorObject<T, BuiltinIteratorReturn, unknown> {
+    [Symbol.iterator](): FetchResourceHeadersIterator<T>;
+}
+type FetchResourceHeadersForEachCallbackFn = (value: string, key: string, parent: FetchResourceResponseHeaders) => void;
+/**
+ * A read-only strict subset of the web standard {@link Headers}.
+ *
+ * Note that the engine may make the following assumptions about
+ * {@link FetchResourceResponse.headers}:
+ *
+ * - If {@link FetchResourceResponse} is an instance of {@link Response}, it
+ *   will be assumed its {@link FetchResourceResponse.headers | headers object}
+ *   _is present_, and that it is an instance of {@link Headers}. In other
+ *   words: for the purposes of resource resolution, we explicitly expect that
+ *   clients using APIs provided by the runtime platform (or polyfills thereof)
+ *   will not monkey-patch properties of values produced by those APIs.
+ *
+ * - If the object is an instance of {@link Headers} (whether by inference as a
+ *   property of {@link Response}, or by a direct instance type check), the
+ *   engine will assume it is safe to treat header names as case insensitive for
+ *   any lookups it may perform. In other words: we explicitly expect that
+ *   clients _providing access_ to APIs rovided by the runtime platform (or
+ *   polyfills thereof) will not alter the guarantees of those APIs.
+ *
+ * - If the object is not an instance of {@link Headers}, it will be treated as
+ *   a {@link ReadonlyMap<string, string>}. In other words: we explicitly expect
+ *   that clients, when providing a bespoke implementation of
+ *   {@link FetchResourceResponse} and its constituent parts, will likely
+ *   implement them partially (and in the case of
+ *   {@link FetchResourceResponse.headers}, with the nearest common idiom
+ *   available). In this case, we will favor a best effort at correctness,
+ *   generally at some expense of performance.
+ */
+export interface FetchResourceResponseHeaders {
+    [Symbol.iterator](): FetchResourceHeadersIterator<[string, string]>;
+    entries(): FetchResourceHeadersIterator<[string, string]>;
+    keys(): FetchResourceHeadersIterator<string>;
+    values(): FetchResourceHeadersIterator<string>;
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callbackfn: FetchResourceHeadersForEachCallbackFn): void;
+}
+/**
+ * This is a strict subset of the web standard {@link Response}. Clients are
+ * encouraged to use the global {@link Response} constructor (as provided by the
+ * runtime platform, or by a global runtime polyfill), but may also provide a
+ * bespoke implementation if it suits their needs.
+ *
+ * Since we cannot assume a client's implementation will always be an instance
+ * of {@link Response}, we make some assumptions about its {@link headers}
+ * object (if available, as detailed on {@link FetchResourceResponseHeaders}).
+ *
+ * For other properties, we make the following assumptions (all of which are
+ * assumptions we would make about a platform-provided/polyfilled
+ * {@link Response}, but are explicitly stated for the benefit of confidence in
+ * client implementations):
+ *
+ * - If we read {@link body} directly, we will assume it is consumed on first
+ *   read, and will not read it again.
+ *
+ * - We assume that {@link blob} and {@link text} indirectly consume
+ *   {@link body} on first read as well, and will only ever read one of each of
+ *   these properties, and only ever once.
+ *
+ * Furthermore, if the engine intends to read {@link body} (or its indirect
+ * {@link blob} or {@link text} consumers), it will do so in the course of a
+ * client's call to {@link initializeForm}, and before the
+ * {@link Promise<PrimaryInstance>} returned by that call is resolved.
+ */
+export interface FetchResourceResponse {
+    readonly ok?: boolean;
+    readonly status?: number;
+    readonly body?: ReadableStream<Uint8Array> | null;
+    readonly bodyUsed?: boolean;
+    readonly headers?: FetchResourceResponseHeaders;
+    readonly blob: () => Promise<Blob>;
+    readonly text: () => Promise<string>;
+}
+/**
+ * This is a strict subset of the web standard `fetch` interface. It implicitly
+ * assumes that the engine itself will only ever perform `GET`-like network/IO
+ * requests. It also provides no further request-like semantics to the engine.
+ *
+ * This is presumed sufficient for now, but notably doesn't expose any notion of
+ * content negotiation (e.g. the ability for the engine to include `Accept`
+ * headers in resource requests issued to a client's {@link FetchResource}
+ * implementation).
+ */
+export type FetchResource<Resource extends URL = URL> = (resource: Resource) => Promise<FetchResourceResponse>;
+export type FormAttachmentURL = JRResourceURL;
+export type FetchFormAttachment = FetchResource<FormAttachmentURL>;
+export {};

package/dist/client/submission/SubmissionData.d.ts

@@ -0,0 +1,7 @@
+import { SubmissionInstanceFile, SubmissionInstanceFileName } from './SubmissionInstanceFile.ts';
+export interface SubmissionData extends FormData {
+    get(name: SubmissionInstanceFileName): SubmissionInstanceFile;
+    get(name: string): FormDataEntryValue | null;
+    has(name: SubmissionInstanceFileName): true;
+    has(name: string): boolean;
+}

package/dist/client/submission/SubmissionDefinition.d.ts

@@ -0,0 +1,14 @@
+export interface SubmissionDefinition {
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `action` submission attribute}
+     */
+    readonly submissionAction: URL | null;
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `method` submission attribute}
+     */
+    readonly submissionMethod: 'post';
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `base64RsaPublicKey` submission attribute}
+     */
+    readonly encryptionKey: string | null;
+}

package/dist/client/submission/SubmissionInstanceFile.d.ts

@@ -0,0 +1,6 @@
+import { SubmissionInstanceFileName, SubmissionInstanceFileType } from '../constants.ts';
+export type { SubmissionInstanceFileName, SubmissionInstanceFileType };
+export interface SubmissionInstanceFile extends File {
+    readonly name: SubmissionInstanceFileName;
+    readonly type: SubmissionInstanceFileType;
+}

package/dist/client/submission/SubmissionOptions.d.ts

@@ -0,0 +1,23 @@
+export type SubmissionChunkedType = 'chunked' | 'monolithic';
+interface BaseSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+    readonly chunked?: ChunkedType | undefined;
+    /**
+     * As described in the
+     * {@link https://docs.getodk.org/openrosa-form-submission/#extended-transmission-considerations | OpenRosa Form Submission API},
+     * clients may obtain this value from an OpenRosa server's
+     * `X-OpenRosa-Accept-Content-Length` header.
+     */
+    readonly maxSize?: number;
+}
+interface ChunkedSubmissionOptions extends BaseSubmissionOptions<'chunked'> {
+    readonly maxSize: number;
+}
+interface MonolithicSubmissionOptions extends BaseSubmissionOptions<'monolithic'> {
+    readonly chunked?: 'monolithic' | undefined;
+    readonly maxSize?: never;
+}
+export type SubmissionOptions<ChunkedType extends SubmissionChunkedType = 'monolithic'> = {
+    chunked: ChunkedSubmissionOptions;
+    monolithic: MonolithicSubmissionOptions;
+}[ChunkedType];
+export {};