@getodk/xforms-engine 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "description": "XForms engine for ODK Web Forms",
   "type": "module",
@@ -29,7 +29,7 @@
     "README.md"
   ],
   "engines": {
-    "node": "^18.20.4 || ^20.17.0 || ^22.8.0",
+    "node": "^18.20.4 || ^20.17.0 || ^22.9.0",
     "yarn": "1.22.22"
   },
   "scripts": {
@@ -54,22 +54,24 @@
     "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "solid-js": "^1.8.22"
+    "papaparse": "^5.4.1",
+    "solid-js": "^1.9.1"
   },
   "devDependencies": {
     "@babel/core": "^7.25.2",
     "@getodk/tree-sitter-xpath": "0.1.2",
-    "@getodk/xpath": "0.2.0",
-    "@playwright/test": "^1.46.1",
-    "@vitest/browser": "^2.0.5",
+    "@getodk/xpath": "0.3.0",
+    "@playwright/test": "^1.47.2",
+    "@types/papaparse": "^5.3.15",
+    "@vitest/browser": "^2.1.1",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
     "http-server": "^14.1.1",
-    "jsdom": "^25.0.0",
-    "typedoc": "^0.26.6",
-    "vite": "^5.4.3",
-    "vite-plugin-dts": "^4.1.0",
+    "jsdom": "^25.0.1",
+    "typedoc": "^0.26.7",
+    "vite": "^5.4.8",
+    "vite-plugin-dts": "^4.2.2",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.0.5"
+    "vitest": "^2.1.1"
   },
   "peerDependencies": {
     "solid-js": "^1.8.18"

package/src/client/BaseNode.ts

@@ -3,7 +3,9 @@ import type { AnyNodeDefinition } from '../parse/model/NodeDefinition.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 import type { TextRange } from './TextRange.ts';
+import type { FormNodeID } from './identity.ts';
 import type { InstanceNodeType } from './node-types.ts';
+import type { SubmissionState } from './submission/SubmissionState.ts';
 import type {
 	AncestorNodeValidationState,
 	LeafNodeValidationState,
@@ -129,8 +131,6 @@ export interface BaseNodeState {
 	get value(): unknown;
 }
 
-type FormNodeID = string;
-
 /**
  * Base interface for common/shared aspects of any node type.
  */
@@ -189,15 +189,13 @@ export interface BaseNode {
 	// 2. If `parent` does become nullable state, how best to convey the same
 	//    information for removed descendants. Some ideas:
 	//
-	//    - Apply null-as-removed recursively. This wouldn't technically be true
-	//      for the engine's current use of a DOM backing store (but that's an
-	//      implementation detail clients don't/shouldn't care about).
+	//    - Apply null-as-removed recursively.
 	//
 	//    - Borrow the browser DOM's notion of node "connected"-ness. When a node
 	//      is removed, its `isConnected` property is `false`. The same is true
 	//      for any of its descendants, even though they retain their own direct
 	//      parent reference.
-	readonly parent: BaseNode | null;
+	readonly parent: unknown;
 
 	/**
 	 * Each node provides a discrete object representing the stateful aspects\* of
@@ -251,4 +249,16 @@ 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;
 }

package/src/client/BaseValueNode.ts

@@ -0,0 +1,35 @@
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeType } from './node-types.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+import type { 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/src/client/EngineConfig.ts

@@ -1,35 +1,7 @@
+import type { initializeForm } from '../instance/index.ts';
+import type { MissingResourceBehavior, MissingResourceBehaviorDefault } from './constants.ts';
 import type { 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 type { FetchFormAttachment, FetchResource } from './resources.ts';
 
 /**
  * Options provided by a client to specify certain aspects of engine runtime
@@ -55,29 +27,58 @@ 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:
+	 *
+	 * - 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.
+	 *
+	 * - 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:
 	 *
-	 * 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 be consulted for all supported form attachments,
+	 *   as a part of {@link initializeForm | form initialization}.
 	 *
-	 * - 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)
+	 * - 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/src/client/InputNode.ts

@@ -0,0 +1,77 @@
+import type { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import type { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
+import type { RootNode } from './RootNode.ts';
+import type { ValueType } from './ValueType.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { 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'>;
+
+// prettier-ignore
+type SupportedInputValueType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'string'
+	| 'int'
+	| 'decimal';
+
+type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
+
+export type TemporaryStringValueInputNode = InputNode<TemporaryStringValueType>;
+
+// prettier-ignore
+export type AnyInputNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| StringInputNode
+	| IntInputNode
+	| DecimalInputNode
+	| TemporaryStringValueInputNode;

package/src/client/ModelValueNode.ts

@@ -1,10 +1,15 @@
+import type { RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { RootNode } from './RootNode.ts';
 import type { LeafNodeValidationState } from './validation.ts';
+import type { ValueType } from './ValueType.ts';
 
-export interface ModelValueNodeState extends BaseNodeState {
+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;
@@ -15,10 +20,11 @@ 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;
 }
 
@@ -29,12 +35,29 @@ 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/src/client/NoteNode.ts

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

package/src/client/RootNode.ts

@@ -3,14 +3,14 @@ import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
+import type { SubmissionChunkedType, SubmissionOptions } from './submission/SubmissionOptions.ts';
+import type { SubmissionResult } from './submission/SubmissionResult.ts';
 import type { 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;
 
@@ -46,15 +46,45 @@ export interface RootNode extends BaseNode {
 
 	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/src/client/SelectNode.ts

@@ -1,9 +1,9 @@
 import type { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { InputNode } from './InputNode.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
-import type { StringNode } from './StringNode.ts';
 import type { TextRange } from './TextRange.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { LeafNodeValidationState } from './validation.ts';
@@ -60,7 +60,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;
@@ -69,7 +69,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/src/client/ValueType.ts

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

package/src/client/constants.ts

@@ -1,5 +1,66 @@
+import type { PrimaryInstance } from '../instance/PrimaryInstance.ts';
+import type { InitializeForm } from './index.ts';
 import type { ValidationTextRole } from './TextRange.ts';
 
+export 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}
+	 */
+	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}
+	 */
+	BLANK: 'BLANK',
+
+	/**
+	 * @see {@link MISSING_RESOURCE_BEHAVIOR.ERROR}
+	 */
+	get DEFAULT(): 'ERROR' {
+		return MISSING_RESOURCE_BEHAVIOR.ERROR;
+	},
+} as const;
+
+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.
+ */
+// prettier-ignore
+export type MissingResourceBehavior =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| MissingResourceBehaviorError
+	| MissingResourceBehaviorBlank;
+
 export const VALIDATION_TEXT = {
 	constraintMsg: 'Condition not satisfied: constraint',
 	requiredMsg: 'Condition not satisfied: required',
@@ -8,3 +69,9 @@ export const VALIDATION_TEXT = {
 type ValidationTextDefaults = typeof VALIDATION_TEXT;
 
 export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];
+
+export const SUBMISSION_INSTANCE_FILE_NAME = 'xml_submission_file';
+export type SubmissionInstanceFileName = typeof SUBMISSION_INSTANCE_FILE_NAME;
+
+export const SUBMISSION_INSTANCE_FILE_TYPE = 'text/xml';
+export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;

package/src/client/hierarchy.ts

@@ -1,13 +1,13 @@
 import type { ExpandUnion } from '@getodk/common/types/helpers.d.ts';
 import type { GroupNode } from './GroupNode.ts';
-import type { ModelValueNode } from './ModelValueNode.ts';
+import type { AnyInputNode } from './InputNode.ts';
+import type { AnyModelValueNode } from './ModelValueNode.ts';
 import type { NoteNode } from './NoteNode.ts';
 import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
-import type { StringNode } from './StringNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
 import type { TriggerNode } from './TriggerNode.ts';
 import type { RangeNode } from './unsupported/RangeNode.ts';
@@ -22,16 +22,16 @@ export type AnyUnsupportedControlNode =
 
 // prettier-ignore
 export type AnyControlNode =
+	| AnyInputNode
 	| NoteNode
 	| SelectNode
-	| StringNode
 	| TriggerNode;
 
 // prettier-ignore
 export type AnyLeafNode =
 	| AnyControlNode
-	| AnyUnsupportedControlNode
-	| ModelValueNode;
+	| AnyModelValueNode
+	| AnyUnsupportedControlNode;
 
 // prettier-ignore
 export type RepeatRangeNode =

package/src/client/identity.ts

@@ -0,0 +1,16 @@
+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}`;