@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/instance/children.ts

@@ -1,28 +1,33 @@
 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 { SelectDefinition } from '../client/SelectNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.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 { RankDefinition } from '../client/RankNode.ts';
 import type { UploadNodeDefinition } from '../client/unsupported/UploadNode.ts';
+import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
+import type {
+	AnyRangeNodeDefinition,
+	RangeLeafNodeDefinition,
+} from '../parse/model/RangeNodeDefinition.ts';
+import { RangeNodeDefinition } from '../parse/model/RangeNodeDefinition.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 { RangeControl } from './RangeControl.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 { SelectControl } from './SelectControl.ts';
 import { Subtree } from './Subtree.ts';
 import { TriggerControl } from './TriggerControl.ts';
-import { RangeControl } from './unsupported/RangeControl.ts';
-import { RankControl } from './unsupported/RankControl.ts';
+import { RankControl } from './RankControl.ts';
 import { UploadControl } from './unsupported/UploadControl.ts';
 
 const isSubtreeDefinition = (
@@ -31,16 +36,16 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
-type AnyUnsupportedControlDefinition =
-	| RangeNodeDefinition
-	| RankNodeDefinition
-	| UploadNodeDefinition;
+// prettier-ignore
+type AnyUnsupportedControlDefinition = UploadNodeDefinition;
 
 // prettier-ignore
 type ControlNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| SelectFieldDefinition
-	| StringFieldDefinition
+	| InputDefinition
+	| RangeLeafNodeDefinition
+	| SelectDefinition
+	| RankDefinition
 	| TriggerNodeDefinition
 	| AnyUnsupportedControlDefinition;
 
@@ -52,28 +57,61 @@ 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 => {
+const isSelectDefinition = (definition: ControlNodeDefinition): definition is SelectDefinition => {
 	return definition.bodyElement.type === 'select' || definition.bodyElement.type === 'select1';
 };
 
-const isRangeNodeDefinition = (
-	definition: UnsupportedControlDefinition
-): definition is RangeNodeDefinition => {
+const isRankDefinition = (definition: ControlNodeDefinition): definition is RankDefinition => {
+	return definition.bodyElement.type === 'rank';
+};
+
+const isRangeLeafNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is RangeLeafNodeDefinition => {
 	return definition.bodyElement.type === 'range';
 };
 
-const isRankNodeDefinition = (
-	definition: UnsupportedControlDefinition
-): definition is RankNodeDefinition => {
-	return definition.bodyElement.type === 'rank';
+type AssertRangeNodeDefinition = (
+	definition: RangeLeafNodeDefinition
+) => asserts definition is AnyRangeNodeDefinition;
+
+/**
+ * We need some way to narrow the base {@link RangeLeafNodeDefinition} type to
+ * {@link RankNodeDefinition} type.
+ *
+ * At time of writing, we know there is no code path to produce the broader
+ * type, but appeasing the type checker for it will help guard against
+ * introducing one. (And it would have caught exactly such a mistake in this
+ * phase of development, where a more optimistic type cast did not.)
+ *
+ * An `instanceof` check is appropriate because the narrower type refines all of
+ * the following:
+ *
+ * - `valueType` is a subset of the full range of
+ *   {@link ValueType | specified value types} (only `int` or `decimal` are
+ *   supported for range controls)
+ *
+ * - addition of range-specific properties: `min`, `max`, `step`
+ */
+const assertRangeNodeDefinition: AssertRangeNodeDefinition = (definition) => {
+	if (definition instanceof RangeNodeDefinition) {
+		return;
+	}
+
+	/**
+	 * At time of writing we know there is no code path producing this
+	 * case, but appeasing the type checker for it now will guard against
+	 * it happening mistakenly in any future refactoring. (Hint: it
+	 * occurred during some refactoring that arrived here, which is why
+	 * this isn't a type cast!)
+	 */
+	throw new ErrorProductionDesignPendingError(
+		`Invalid <range> definition with value type: ${definition.valueType}`
+	);
 };
 
 const isTriggerNodeDefinition = (
@@ -121,27 +159,29 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 				const leafChild: AnyLeafNodeDefinition = child;
 
 				if (isModelValueDefinition(leafChild)) {
-					return new ModelValue(parent, leafChild);
+					return ModelValue.from(parent, leafChild);
 				}
 
-				if (isStringFieldDefinition(leafChild)) {
-					return new StringField(parent, leafChild);
+				if (isInputDefinition(leafChild)) {
+					return InputControl.from(parent, leafChild);
 				}
 
-				if (isSelectFieldDefinition(leafChild)) {
-					return new SelectField(parent, leafChild);
+				if (isSelectDefinition(leafChild)) {
+					return SelectControl.from(parent, leafChild);
 				}
 
-				if (isTriggerNodeDefinition(leafChild)) {
-					return new TriggerControl(parent, leafChild);
+				if (isRankDefinition(leafChild)) {
+					return RankControl.from(parent, leafChild);
 				}
 
-				if (isRangeNodeDefinition(leafChild)) {
-					return new RangeControl(parent, leafChild);
+				if (isTriggerNodeDefinition(leafChild)) {
+					return TriggerControl.from(parent, leafChild);
 				}
 
-				if (isRankNodeDefinition(leafChild)) {
-					return new RankControl(parent, leafChild);
+				if (isRangeLeafNodeDefinition(leafChild)) {
+					assertRangeNodeDefinition(leafChild);
+
+					return RangeControl.from(parent, leafChild);
 				}
 
 				if (isUploadNodeDefinition(leafChild)) {

package/src/instance/hierarchy.ts

@@ -1,44 +1,46 @@
 import type { Group } from './Group.ts';
-import type { ModelValue } from './ModelValue.ts';
-import type { Note } from './Note.ts';
+import type { AnyInputControl } from './InputControl.ts';
+import type { AnyModelValue } from './ModelValue.ts';
+import type { AnyNote } from './Note.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
+import type { AnyRangeControl } from './RangeControl.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 { SelectControl } from './SelectControl.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 { RankControl } from './RankControl.ts';
 import type { UploadControl } from './unsupported/UploadControl.ts';
 
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
 // prettier-ignore
-export type UnsupportedControl =
-	| RangeControl
-	| RankControl
-	| UploadControl;
+export type AnyUnsupportedControl = 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
+	| AnyNote
+	| AnyModelValue
+	| AnyInputControl
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyParentNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
 	| Root
 	| Group
 	| Subtree
@@ -56,16 +58,19 @@ export type GeneralParentNode =
 // prettier-ignore
 export type AnyChildNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
 	| Group
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
-	| ModelValue
-	| Note
-	| StringField
-	| SelectField
+	| AnyModelValue
+	| AnyNote
+	| AnyInputControl
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type GeneralChildNode =
@@ -73,19 +78,23 @@ export type GeneralChildNode =
 	| Group
 	| Subtree
 	| RepeatRange
-	| ModelValue
-	| Note
-	| StringField
-	| SelectField
+	| AnyModelValue
+	| AnyNote
+	| AnyInputControl
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyValueNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| ModelValue
-	| Note
-	| StringField
-	| SelectField
+	| AnyModelValue
+	| AnyNote
+	| AnyInputControl
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
-	| UnsupportedControl;
+	| 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 { 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 { XFormDOM } from '../parse/XFormDOM.ts';
 import { XFormDefinition } from '../parse/XFormDefinition.ts';
-import { Root } from './Root.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 { 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 { DependentExpression } from '../../parse/expression/abstract/DependentExpression.ts';
-import type { SubscribableDependency } from './SubscribableDependency.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,26 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+export type DecodeInstanceValue = (value: string) => string;
+
+interface InstanceValueContextDefinitionBind {
+	readonly preload: AnyBindPreloadDefinition | null;
+	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,9 +1,8 @@
+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 { NodeID } from '../identity.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
-import type { SubscribableDependency } from './SubscribableDependency.ts';
 
 interface ValidationContextCurrentState {
 	get reference(): string;
@@ -20,8 +19,8 @@ interface ValidationContextDefinition {
 	readonly bind: ValidationContextDefinitionBind;
 }
 
-export interface ValidationContext extends EvaluationContext, SubscribableDependency {
-	readonly nodeId: NodeID;
+export interface ValidationContext extends EvaluationContext {
+	readonly nodeId: FormNodeID;
 	readonly definition: ValidationContextDefinition;
 	readonly currentState: ValidationContextCurrentState;
 

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

@@ -1,3 +1,4 @@
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
@@ -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;
+}