@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/instance/children.ts

@@ -1,20 +1,30 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import type { GroupDefinition } from '../client/GroupNode.ts';
+import type { InputDefinition } from '../client/InputNode.ts';
+import type { ModelValueDefinition } from '../client/ModelValueNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
-import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
-import type { SubtreeDefinition as ModelSubtreeDefinition } from '../model/SubtreeDefinition.ts';
-import { NoteNodeDefinition } from '../parse/NoteNodeDefinition.ts';
+import type { TriggerNodeDefinition } from '../client/TriggerNode.ts';
+import type { RangeNodeDefinition } from '../client/unsupported/RangeNode.ts';
+import type { RankNodeDefinition } from '../client/unsupported/RankNode.ts';
+import type { UnsupportedControlDefinition } from '../client/unsupported/UnsupportedControlNode.ts';
+import type { UploadNodeDefinition } from '../client/unsupported/UploadNode.ts';
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 import { Group } from './Group.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { ModelValue, type ModelValueDefinition } from './ModelValue.ts';
+import { InputControl } from './InputControl.ts';
+import { ModelValue } from './ModelValue.ts';
 import { Note } from './Note.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { SelectFieldDefinition } from './SelectField.ts';
 import { SelectField } from './SelectField.ts';
-import type { StringFieldDefinition } from './StringField.ts';
-import { StringField } from './StringField.ts';
 import { Subtree } from './Subtree.ts';
+import { TriggerControl } from './TriggerControl.ts';
+import { RangeControl } from './unsupported/RangeControl.ts';
+import { RankControl } from './unsupported/RankControl.ts';
+import { UploadControl } from './unsupported/UploadControl.ts';
 
 const isSubtreeDefinition = (
 	definition: ModelSubtreeDefinition
@@ -22,7 +32,18 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
-type ControlNodeDefinition = SelectFieldDefinition | StringFieldDefinition;
+type AnyUnsupportedControlDefinition =
+	| RangeNodeDefinition
+	| RankNodeDefinition
+	| UploadNodeDefinition;
+
+// prettier-ignore
+type ControlNodeDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| InputDefinition
+	| SelectFieldDefinition
+	| TriggerNodeDefinition
+	| AnyUnsupportedControlDefinition;
 
 type AnyLeafNodeDefinition = ControlNodeDefinition | ModelValueDefinition;
 
@@ -32,12 +53,40 @@ const isModelValueDefinition = (
 	return definition.bodyElement == null;
 };
 
-const isStringFieldDefinition = (
-	definition: ControlNodeDefinition
-): definition is StringFieldDefinition => {
+const isInputDefinition = (definition: ControlNodeDefinition): definition is InputDefinition => {
 	return definition.bodyElement.type === 'input';
 };
 
+const isSelectFieldDefinition = (
+	definition: ControlNodeDefinition
+): definition is SelectFieldDefinition => {
+	return definition.bodyElement.type === 'select' || definition.bodyElement.type === 'select1';
+};
+
+const isRangeNodeDefinition = (
+	definition: UnsupportedControlDefinition
+): definition is RangeNodeDefinition => {
+	return definition.bodyElement.type === 'range';
+};
+
+const isRankNodeDefinition = (
+	definition: UnsupportedControlDefinition
+): definition is RankNodeDefinition => {
+	return definition.bodyElement.type === 'rank';
+};
+
+const isTriggerNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is TriggerNodeDefinition => {
+	return definition.bodyElement.type === 'trigger';
+};
+
+const isUploadNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is UploadNodeDefinition => {
+	return definition.bodyElement.type === 'upload';
+};
+
 export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
 	const { children } = parent.definition;
 
@@ -71,14 +120,34 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 				const leafChild: AnyLeafNodeDefinition = child;
 
 				if (isModelValueDefinition(leafChild)) {
-					return new ModelValue(parent, leafChild);
+					return ModelValue.from(parent, leafChild);
+				}
+
+				if (isInputDefinition(leafChild)) {
+					return InputControl.from(parent, leafChild);
+				}
+
+				if (isSelectFieldDefinition(leafChild)) {
+					return new SelectField(parent, leafChild);
+				}
+
+				if (isTriggerNodeDefinition(leafChild)) {
+					return new TriggerControl(parent, leafChild);
+				}
+
+				if (isRangeNodeDefinition(leafChild)) {
+					return new RangeControl(parent, leafChild);
+				}
+
+				if (isRankNodeDefinition(leafChild)) {
+					return new RankControl(parent, leafChild);
 				}
 
-				if (isStringFieldDefinition(leafChild)) {
-					return new StringField(parent, leafChild);
+				if (isUploadNodeDefinition(leafChild)) {
+					return new UploadControl(parent, leafChild);
 				}
 
-				return new SelectField(parent, leafChild);
+				throw new UnreachableError(leafChild);
 			}
 
 			default: {

package/src/instance/hierarchy.ts

@@ -1,32 +1,47 @@
 import type { Group } from './Group.ts';
-import type { ModelValue } from './ModelValue.ts';
+import type { AnyInputControl } from './InputControl.ts';
+import type { AnyModelValue } from './ModelValue.ts';
 import type { Note } from './Note.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
 import type { RepeatInstance } from './repeat/RepeatInstance.ts';
 import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { Root } from './Root.ts';
 import type { SelectField } from './SelectField.ts';
-import type { StringField } from './StringField.ts';
 import type { Subtree } from './Subtree.ts';
+import type { TriggerControl } from './TriggerControl.ts';
+import type { RangeControl } from './unsupported/RangeControl.ts';
+import type { RankControl } from './unsupported/RankControl.ts';
+import type { UploadControl } from './unsupported/UploadControl.ts';
 
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
+// prettier-ignore
+export type AnyUnsupportedControl =
+	| RangeControl
+	| RankControl
+	| UploadControl;
+
 // prettier-ignore
 export type AnyNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
 	| Root
 	| Group
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
 	| Note
-	| ModelValue
-	| StringField
-	| SelectField;
+	| AnyModelValue
+	| AnyInputControl
+	| SelectField
+	| TriggerControl
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyParentNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
 	| Root
 	| Group
 	| Subtree
@@ -44,14 +59,17 @@ export type GeneralParentNode =
 // prettier-ignore
 export type AnyChildNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
 	| Group
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
-	| SelectField;
+	| AnyInputControl
+	| SelectField
+	| TriggerControl
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type GeneralChildNode =
@@ -59,15 +77,19 @@ export type GeneralChildNode =
 	| Group
 	| Subtree
 	| RepeatRange
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
-	| SelectField;
+	| AnyInputControl
+	| SelectField
+	| TriggerControl
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyValueNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
-	| SelectField;
+	| AnyInputControl
+	| SelectField
+	| TriggerControl
+	| AnyUnsupportedControl;

package/src/instance/identity.ts

@@ -1,11 +1,5 @@
-declare const NODE_ID_BRAND: unique symbol;
-type NODE_ID_BRAND = typeof NODE_ID_BRAND;
+import type { FormNodeID } from '../client/identity.ts';
 
-export type NodeID = string & { readonly [NODE_ID_BRAND]: true };
-
-// Just another added safeguard to ensure we're not mistakenly handling
-// rando `NodeID` strings which aren't explicitly attached to the node
-// types we expect.
-export const declareNodeID = (id: string): NodeID => {
-	return id as NodeID;
+export const nodeID = (id: string): FormNodeID => {
+	return `node:${id}` satisfies FormNodeID;
 };

package/src/instance/index.ts

@@ -1,24 +1,32 @@
 import { identity } from '@getodk/common/lib/identity.ts';
-import { XFormDefinition } from '../XFormDefinition.ts';
+import { getOwner } from 'solid-js';
+import type { EngineConfig } from '../client/EngineConfig.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import { MISSING_RESOURCE_BEHAVIOR } from '../client/constants.ts';
 import type {
 	InitializeFormOptions as BaseInitializeFormOptions,
 	FormResource,
 	InitializeForm,
 } from '../client/index.ts';
 import { retrieveSourceXMLResource } from '../instance/resource.ts';
+import { createReactiveScope } from '../lib/reactivity/scope.ts';
 import { createUniqueId } from '../lib/unique-id.ts';
-import { Root } from './Root.ts';
+import { XFormDOM } from '../parse/XFormDOM.ts';
+import { XFormDefinition } from '../parse/XFormDefinition.ts';
+import { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
+import { PrimaryInstance } from './PrimaryInstance.ts';
 import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
 
 interface InitializeFormOptions extends BaseInitializeFormOptions {
 	readonly config: Partial<InstanceConfig>;
 }
 
-const buildInstanceConfig = (options: Partial<InstanceConfig> = {}): InstanceConfig => {
+const buildInstanceConfig = (options: EngineConfig = {}): InstanceConfig => {
 	return {
-		createUniqueId: options.createUniqueId ?? createUniqueId,
-		fetchResource: options.fetchResource ?? fetch,
+		createUniqueId,
+		fetchFormDefinition: options.fetchFormDefinition ?? fetch,
+		fetchFormAttachment: options.fetchFormAttachment ?? fetch,
+		missingResourceBehavior: options.missingResourceBehavior ?? MISSING_RESOURCE_BEHAVIOR.DEFAULT,
 		stateFactory: options.stateFactory ?? identity,
 	};
 };
@@ -27,11 +35,21 @@ export const initializeForm = async (
 	input: FormResource,
 	options: Partial<InitializeFormOptions> = {}
 ): Promise<RootNode> => {
+	const owner = getOwner();
+	const scope = createReactiveScope({ owner });
 	const engineConfig = buildInstanceConfig(options.config);
-	const sourceXML = await retrieveSourceXMLResource(input, engineConfig);
-	const form = new XFormDefinition(sourceXML);
+	const sourceXML = await retrieveSourceXMLResource(input, {
+		fetchResource: engineConfig.fetchFormDefinition,
+	});
+	const xformDOM = XFormDOM.from(sourceXML);
+	const secondaryInstances = await SecondaryInstancesDefinition.load(xformDOM, {
+		fetchResource: engineConfig.fetchFormAttachment,
+		missingResourceBehavior: engineConfig.missingResourceBehavior,
+	});
+	const form = new XFormDefinition(xformDOM);
+	const primaryInstance = new PrimaryInstance(scope, form.model, secondaryInstances, engineConfig);
 
-	return new Root(form.xformDOM, form.model.root, engineConfig);
+	return primaryInstance.root;
 };
 
 initializeForm satisfies InitializeForm;

package/src/instance/internal-api/EvaluationContext.ts

@@ -1,12 +1,16 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
-import type { DependentExpression } from '../../expression/DependentExpression.ts';
+import type { engineDOMAdapter } from '../../integration/xpath/adapter/engineDOMAdapter.ts';
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticNode } from '../../integration/xpath/static-dom/StaticNode.ts';
+import type { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
+import type { createTranslationState } from '../../lib/reactivity/createTranslationState.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { SubscribableDependency } from './SubscribableDependency.ts';
+import type { DependentExpression } from '../../parse/expression/abstract/DependentExpression.ts';
+import type { InstanceNode } from '../abstract/InstanceNode.ts';
+import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { TranslationContext } from './TranslationContext.ts';
 
-export interface EvaluationContextRoot extends SubscribableDependency, TranslationContext {}
-
 /**
  * Provides a common interface to establish context for XPath-based
  * computations, i.e. to evaluate {@link DependentExpression}s where:
@@ -18,23 +22,66 @@ export interface EvaluationContextRoot extends SubscribableDependency, Translati
  * - the expression may be dependent on the form's currently active language
  *   (e.g. `jr:itext`)
  * - any dynamic case is expected to be internally reactive
+ *
+ * Historical note: we previously utilized static analysis and a related
+ * abstraction to set up reactive subscriptions to node references, values, and
+ * other pertinent state changes warranting an expression's recomputation. Those
+ * are still described above because they provide useful insight for the
+ * **effect** of evaluating a given {@link DependentExpression}, with a given
+ * {@link EvaluationContext}.
+ *
+ * The reactive subscription mechanism has since been largely replaced, with the
+ * engine's implementation of {@link EngineXPathEvaluator} and its corresponding
+ * {@link engineDOMAdapter | XPath DOM adapter implementation}.
+ *
+ * @todo There is still one notable exception: translation expressions (i.e.
+ * expressions calling {@link https://getodk.github.io/xforms-spec/#fn:jr:itext}
+ * | `jr:itext`). We still perform analysis to identify such calls, and when
+ * evaluating those expressions we still explicitly subscribe to the form's
+ * active language state. A further refactor, moving more of the responsibility
+ * for translation state up out of `@getodk/xpath` into the engine, would likely
+ * allow us to further simplify the engine's reactive XPath recomputation
+ * approach.
+ *
+ * @see {@link createTranslationState} for additional context.
  */
-export interface EvaluationContext {
+export interface EvaluationContext extends TranslationContext {
+	/**
+	 * Used to determine whether {@link contextNode} is attached to its
+	 * {@link EngineXPathNode} document hierarchy.
+	 *
+	 * - If this function returns `true`: expressions are evaluated as defined.
+	 * - If this function returns `false`: expressions are evaluated to either an
+	 *   explicit default value (if provided) or an implicit default value
+	 *   appropriate for the requested result type.
+	 *
+	 * @see {@link createComputedExpression} for further detail on the latter.
+	 */
+	readonly isAttached: Accessor<boolean>;
+
 	readonly scope: ReactiveScope;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly root: EvaluationContextRoot;
+	readonly evaluator: EngineXPathEvaluator;
 
 	/**
 	 * Produces the current absolute reference to the {@link contextNode}, where
-	 * the absolute `/` resolves to the active form state's primary instance root.
+	 * the AbsoluteLocationPath expression `/` resolves to the active
+	 * {@link PrimaryInstance}, and each Step and/or position Predicate from there
+	 * corresponds to the node hierarchy descending from there.
 	 */
 	readonly contextReference: Accessor<string>;
 
-	readonly contextNode: Node;
-
 	/**
-	 * Resolves nodes corresponding to the provided node-set reference, possibly
-	 * relative to the {@link EvaluationContext.contextNode}.
+	 * Note: in most cases, implementations of {@link EvaluationContext} will
+	 * **also** be an implementation of {@link EngineXPathNode} (as concrete
+	 * implementations of {@link InstanceNode}). This property is an intentional
+	 * indirection which:
+	 *
+	 * - Expresses only the much more limited set of properties which must be
+	 *   present to initialize computations during those nodes' construction.
+	 *
+	 * - Allows for a handful of cases where an {@link InstanceNode} provides the
+	 *   requisite facilities for evaluating expressions in a {@link StaticNode}'s
+	 *   context (itemsets being a prominent example).
 	 */
-	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[];
+	readonly contextNode: EngineXPathNode;
 }

package/src/instance/internal-api/InstanceConfig.ts

@@ -1,7 +1,14 @@
-import type { EngineConfig } from '../../client/EngineConfig.ts';
+import type { MissingResourceBehavior } from '../../client/constants.ts';
+import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
+import type { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
 import type { CreateUniqueId } from '../../lib/unique-id.ts';
 
-export interface InstanceConfig extends Required<EngineConfig> {
+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).
 	 */

package/src/instance/internal-api/InstanceValueContext.ts

@@ -0,0 +1,24 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+export type DecodeInstanceValue = (value: string) => string;
+
+interface InstanceValueContextDefinitionBind {
+	readonly calculate: BindComputationExpression<'calculate'> | null;
+	readonly readonly: BindComputationExpression<'readonly'>;
+}
+
+export interface InstanceValueContextDefinition {
+	readonly bind: InstanceValueContextDefinitionBind;
+	readonly defaultValue: string;
+}
+
+export interface InstanceValueContext extends EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly definition: InstanceValueContextDefinition;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	isReadonly(): boolean;
+	isRelevant(): boolean;
+}

package/src/instance/internal-api/PrimaryInstanceDocument.ts

@@ -0,0 +1,53 @@
+import type { FormLanguage } from '../../client/FormLanguage.ts';
+import type { RootNode, RootNodeState } from '../../client/RootNode.ts';
+
+export interface PrimaryInstanceDocumentState
+	extends Omit<
+		RootNodeState,
+		// Allow for override with `RootNode`, which is not presently considered a
+		// child node in the client API
+		'children'
+	> {
+	/**
+	 * @todo while this is an internal interface, this feels like maybe an
+	 * unnecessary indirection? It would probably be fine for it to reference
+	 * `Root` directly? We do get some minor benefit from making sure the client
+	 * and internal types are aligned, but we also already enforce that by
+	 * ensuring `Root implements RootNode`...
+	 */
+	get children(): readonly RootNode[];
+}
+
+/**
+ * Provides an interface most similar to what we would expose at the
+ * `@getodk/xforms-engine` package boundary, if we were to document the primary
+ * instance document's types for a client.
+ *
+ * Note: this interface (as well as {@link currentState}'s {@link PrimaryInstanceDocumentState}) is derived from {@link RootNode} to help avoid drift if that underlying interface (or its shared {@link BaseNode} interface) is updated.
+ *
+ */
+export interface PrimaryInstanceDocument
+	extends Omit<
+		RootNode,
+		// prettier-ignore
+		// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+		| 'nodeType' // Allow for override with 'primary-instance'
+		| 'currentState' // Allow for override of `children`
+		| 'setLanguage' // Allow for override of return type
+	> {
+	readonly nodeType: 'primary-instance';
+	readonly currentState: PrimaryInstanceDocumentState;
+
+	/**
+	 * @todo This intentionally returns `unknown` as a hint that we will likely
+	 * want to move away from returning {@link RootNode} (i.e. "all of the state",
+	 * as it was conceived in that design effort) on every state change.
+	 *
+	 * In this case, it may be sensible to return any of:
+	 *
+	 * - Just the state set directly (i.e. the input {@link FormLanguage})
+	 * - That effective state, and some representation of all affected nodes
+	 * - Something less obvious, but potentially more useful to clients?
+	 */
+	setLanguage(language: FormLanguage): unknown;
+}

package/src/instance/internal-api/TranslationContext.ts

@@ -1,5 +1,6 @@
-import type { ActiveLanguage } from '../../index.ts';
+import type { Accessor } from 'solid-js';
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
 
 export interface TranslationContext {
-	get activeLanguage(): ActiveLanguage;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 }

package/src/instance/internal-api/ValidationContext.ts

@@ -1,12 +1,17 @@
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { FormNodeID } from '../../client/identity.ts';
+import type { AnyViolation } from '../../client/validation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
-import type { SubscribableDependency } from './SubscribableDependency.ts';
+
+interface ValidationContextCurrentState {
+	get reference(): string;
+}
 
 interface ValidationContextDefinitionBind {
-	readonly constraint: BindComputation<'constraint'>;
+	readonly constraint: BindComputationExpression<'constraint'>;
 	readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
-	readonly required: BindComputation<'required'>;
+	readonly required: BindComputationExpression<'required'>;
 	readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
 }
 
@@ -14,9 +19,12 @@ interface ValidationContextDefinition {
 	readonly bind: ValidationContextDefinitionBind;
 }
 
-export interface ValidationContext extends EvaluationContext, SubscribableDependency {
+export interface ValidationContext extends EvaluationContext {
+	readonly nodeId: FormNodeID;
 	readonly definition: ValidationContextDefinition;
+	readonly currentState: ValidationContextCurrentState;
 
+	getViolation(): AnyViolation | null;
 	isRelevant(): boolean;
 	isRequired(): boolean;
 	isBlank(): boolean;

package/src/instance/internal-api/ValueContext.ts

@@ -1,12 +1,13 @@
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
 
 export type InstanceValue = string;
 
 interface ValueContextDefinitionBind {
-	readonly calculate: BindComputation<'calculate'> | null;
-	readonly readonly: BindComputation<'readonly'>;
+	readonly calculate: BindComputationExpression<'calculate'> | null;
+	readonly readonly: BindComputationExpression<'readonly'>;
 }
 
 export interface ValueContextDefinition {
@@ -17,7 +18,7 @@ export interface ValueContextDefinition {
 export interface ValueContext<RuntimeValue> extends EvaluationContext {
 	readonly scope: ReactiveScope;
 	readonly definition: ValueContextDefinition;
-	readonly contextNode: Element;
+	readonly contextNode: EngineXPathNode & this;
 
 	isReadonly(): boolean;
 	isRelevant(): boolean;

package/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts

@@ -0,0 +1,20 @@
+import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { Root } from '../../Root.ts';
+import type {
+	ClientReactiveSubmittableParentNode,
+	ClientReactiveSubmittableParentNodeDefinition,
+} from './ClientReactiveSubmittableParentNode.ts';
+
+interface ClientReactiveSubmittableInstanceDefinition
+	extends ClientReactiveSubmittableParentNodeDefinition {
+	readonly submission: SubmissionDefinition;
+}
+
+export interface ClientReactiveSubmittableInstance
+	extends ClientReactiveSubmittableParentNode<Root> {
+	readonly definition: ClientReactiveSubmittableInstanceDefinition;
+	readonly root: Root;
+	readonly parent: null;
+	readonly validationState: AncestorNodeValidationState;
+}

package/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts

@@ -0,0 +1,42 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
+import type {
+	ClientReactiveSubmittableChildNode,
+	ClientReactiveSubmittableParentNode,
+} from './ClientReactiveSubmittableParentNode.ts';
+
+interface ClientReactiveSubmittableLeafNodeCurrentState<RuntimeValue> {
+	get relevant(): boolean;
+	get value(): RuntimeValue;
+}
+
+export type SerializedSubmissionValue = string;
+
+interface ClientReactiveSubmittableLeafNodeDefinition {
+	readonly nodeName: string;
+}
+
+export interface ClientReactiveSubmittableLeafNode<RuntimeValue> {
+	readonly definition: ClientReactiveSubmittableLeafNodeDefinition;
+	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode>;
+	readonly currentState: ClientReactiveSubmittableLeafNodeCurrentState<RuntimeValue>;
+
+	/**
+	 * A client-reactive submittable leaf node is responsible for producing a
+	 * string representation of its value state, suitable for serialization for
+	 * submission. It **MUST NOT** perform any further submission-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 submissionState: SubmissionState;
+}