@getodk/xforms-engine 0.4.0 → 0.5.0

package/dist/instance/abstract/InstanceNode.d.ts

@@ -1,22 +1,30 @@
-import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor, Signal } from 'solid-js';
 import { BaseNode } from '../../client/BaseNode.ts';
 import { NodeAppearances } from '../../client/NodeAppearances.ts';
-import { InstanceNodeType } from '../../client/node-types.ts';
+import { FormNodeID } from '../../client/identity.ts';
+import { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
+import { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import { NodeValidationState } from '../../client/validation.ts';
-import { TextRange } from '../../index.ts';
+import { ActiveLanguage, TextRange } from '../../index.ts';
+import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import { XFormsXPathPrimaryInstanceNode, XFormsXPathPrimaryInstanceNodeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { SimpleAtomicState } from '../../lib/reactivity/types.ts';
 import { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import { PrimaryInstance } from '../PrimaryInstance.ts';
 import { Root } from '../Root.ts';
-import { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
-import { NodeID } from '../identity.ts';
+import { AnyChildNode, AnyParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { InstanceConfig } from '../internal-api/InstanceConfig.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+export type EngineInstanceNodeType = ClientInstanceNodeType | 'primary-instance';
+export interface BaseEngineNode extends Omit<BaseNode, 'nodeType'> {
+    readonly nodeType: EngineInstanceNodeType;
+}
 export interface InstanceNodeStateSpec<Value = never> {
     readonly reference: Accessor<string> | string;
     readonly readonly: Accessor<boolean> | boolean;
@@ -24,7 +32,7 @@ export interface InstanceNodeStateSpec<Value = never> {
     readonly required: Accessor<boolean> | boolean;
     readonly label: Accessor<TextRange<'label'> | null> | null;
     readonly hint: Accessor<TextRange<'hint'> | null> | null;
-    readonly children: Accessor<readonly NodeID[]> | null;
+    readonly children: Accessor<readonly FormNodeID[]> | null;
     readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
     readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
@@ -43,13 +51,17 @@ interface ComputableReferenceNode {
 type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(this: This, parent: This['parent'], definition: This['definition']) => string;
 export interface InstanceNodeOptions {
     readonly computeReference?: () => string;
+    readonly scope?: ReactiveScope;
 }
-export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Child extends AnyChildNode | null = null> implements BaseNode, EvaluationContext, SubscribableDependency {
+export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Parent extends AnyParentNode | null, Child extends AnyChildNode | null = null> implements BaseEngineNode, XFormsXPathPrimaryInstanceNode, EvaluationContext {
     readonly engineConfig: InstanceConfig;
-    readonly parent: AnyParentNode | null;
+    readonly parent: Parent;
     readonly definition: Definition;
     protected abstract readonly state: SharedNodeState<Spec>;
     protected abstract readonly engineState: EngineState<Spec>;
+    abstract readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceNodeKind;
+    readonly rootDocument: PrimaryInstance;
+    abstract readonly root: Root;
     /**
      * @package Exposed on every node type to facilitate inheritance, as well as
      * conditional behavior for value nodes.
@@ -70,37 +82,45 @@ export declare abstract class InstanceNode<Definition extends AnyNodeDefinition,
      * conditional behavior for value nodes.
      */
     abstract readonly isRelevant: Accessor<boolean>;
-    readonly nodeId: NodeID;
-    abstract readonly nodeType: InstanceNodeType;
+    readonly nodeId: FormNodeID;
+    abstract readonly nodeType: EngineInstanceNodeType;
     abstract readonly appearances: NodeAppearances<Definition>;
     abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
     abstract readonly validationState: NodeValidationState;
-    abstract readonly root: Root;
-    abstract readonly evaluator: XFormsXPathEvaluator;
+    abstract readonly submissionState: SubmissionState;
+    abstract readonly evaluator: EngineXPathEvaluator;
+    abstract readonly getActiveLanguage: Accessor<ActiveLanguage>;
+    abstract readonly isAttached: Accessor<boolean>;
     readonly scope: ReactiveScope;
     readonly computeReference: ComputeInstanceNodeReference;
     protected readonly computeChildStepReference: ComputeInstanceNodeReference;
     readonly contextReference: () => string;
-    abstract readonly contextNode: Element;
-    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition, options?: InstanceNodeOptions);
     /**
-     * @package This presently serves a few internal use cases, where certain
-     * behaviors depend on arbitrary traversal from any point in the instance
-     * tree, without particular regard for the visited node type. It isn't
-     * intended for external traversal or any other means of consuming children by
-     * a client. This return type intentionally deviates from one structural
-     * expectation, requiring even leaf nodes to return an array (though for those
-     * nodes it will always be empty). This affords consistency and efficiency of
-     * interface for those internal uses.
+     * Note: it is expected that at least some node subclasses will override this
+     * to reflect (or in the case of intermediate abstract base classes, to
+     * constrain) their more specific `this` type.
+     */
+    readonly contextNode: PrimaryInstanceXPathNode;
+    constructor(engineConfig: InstanceConfig, parent: Parent, definition: Definition, options?: InstanceNodeOptions);
+    /** @package */
+    isPrimaryInstance(): this is PrimaryInstance;
+    /** @package */
+    isRoot(): this is Root;
+    /**
+     * @package This presently serves a growing variety of internal use cases,
+     * where certain behaviors depend on arbitrary traversal from any point in the
+     * instance tree, without particular regard for the visited node type. It
+     * isn't intended for external traversal or any other means of consuming
+     * children by a client. This return type intentionally deviates from one
+     * structural expectation, requiring even leaf nodes to return an array
+     * (though for those nodes it will always be empty). This affords consistency
+     * and efficiency of interface for those internal uses.
      */
     abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
-    getNodesByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): readonly SubscribableDependency[];
-    getSubscribableDependenciesByReference(this: AnyNode, reference: string): readonly SubscribableDependency[];
     /**
-     * This is a default implementation suitable for most node types. The rest
-     * (currently: `Root`, `RepeatRange`, `RepeatInstance`) should likely extend
-     * this behavior, rather than simply overriding it.
+     * @todo Values as text nodes(?)
      */
-    subscribe(): void;
+    getXPathChildNodes(): readonly AnyChildNode[];
+    getXPathValue(): string;
 }
 export {};

package/dist/instance/abstract/UnsupportedControl.d.ts

@@ -1,16 +1,19 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { UnsupportedControlNodeType } from '../../client/node-types.ts';
+import { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import { TextRange } from '../../client/TextRange.ts';
 import { UnsupportedControlDefinition, UnsupportedControlElementDefinition, UnsupportedControlNode } from '../../client/unsupported/UnsupportedControlNode.ts';
 import { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
+import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
 import { SimpleAtomicState } from '../../lib/reactivity/types.ts';
 import { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
-import { GeneralParentNode } from '../hierarchy.ts';
+import { AnyUnsupportedControl, GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { ClientReactiveSubmittableLeafNode } from '../internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 import { ValidationContext } from '../internal-api/ValidationContext.ts';
 import { ValueContext } from '../internal-api/ValueContext.ts';
 import { DescendantNode, DescendantNodeStateSpec } from './DescendantNode.ts';
@@ -27,17 +30,21 @@ interface UnsupportedControlStateSpec extends DescendantNodeStateSpec<unknown> {
     readonly value: SimpleAtomicState<unknown>;
     readonly valueOptions: never;
 }
-export declare abstract class UnsupportedControl<Type extends UnsupportedControlNodeType> extends DescendantNode<TypedUnsupportedControlDefinition<Type>, UnsupportedControlStateSpec, null> implements UnsupportedControlNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<unknown> {
+export declare abstract class UnsupportedControl<Type extends UnsupportedControlNodeType> extends DescendantNode<TypedUnsupportedControlDefinition<Type>, UnsupportedControlStateSpec, GeneralParentNode, null> implements UnsupportedControlNode, XFormsXPathElement, EvaluationContext, ValidationContext, ValueContext<unknown>, ClientReactiveSubmittableLeafNode<unknown> {
     private readonly validation;
     protected readonly state: SharedNodeState<UnsupportedControlStateSpec>;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly engineState: EngineState<UnsupportedControlStateSpec>;
     abstract readonly nodeType: Type;
     readonly appearances: UnknownAppearanceDefinition;
     readonly currentState: CurrentState<UnsupportedControlStateSpec>;
     get validationState(): LeafNodeValidationState;
+    readonly submissionState: SubmissionState;
+    abstract readonly contextNode: AnyUnsupportedControl & this;
     readonly encodeValue: (instanceValue: unknown) => string;
     readonly decodeValue: (instanceValue: unknown) => unknown;
     constructor(parent: GeneralParentNode, definition: TypedUnsupportedControlDefinition<Type>);
+    getXPathValue(): string;
     getViolation(): AnyViolation | null;
     isBlank(): boolean;
     getChildren(): readonly [];

package/dist/instance/abstract/ValueNode.d.ts

@@ -0,0 +1,48 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
+import { BaseValueNode } from '../../client/BaseValueNode.ts';
+import { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
+import { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
+import { ValueType } from '../../client/ValueType.ts';
+import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { RuntimeValueSetter, RuntimeValueState, ValueCodec } from '../../lib/codecs/ValueCodec.ts';
+import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
+import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
+import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import { SharedValidationState } from '../../lib/reactivity/validation/createValidation.ts';
+import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { DecodeInstanceValue, InstanceValueContext } from '../internal-api/InstanceValueContext.ts';
+import { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import { ValidationContext } from '../internal-api/ValidationContext.ts';
+import { DescendantNodeStateSpec, DescendantNode } from './DescendantNode.ts';
+export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
+export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
+    readonly children: null;
+    readonly valueOptions: null;
+    readonly value: SimpleAtomicState<RuntimeValue>;
+    readonly instanceValue: Accessor<string>;
+}
+export declare abstract class ValueNode<V extends ValueType, Definition extends ValueNodeDefinition<V>, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> extends DescendantNode<Definition, ValueNodeStateSpec<RuntimeValue>, GeneralParentNode, null> implements BaseValueNode<V, RuntimeValue>, XFormsXPathElement, EvaluationContext, InstanceValueContext, ValidationContext, ClientReactiveSubmittableValueNode {
+    protected readonly validation: SharedValidationState;
+    protected readonly getInstanceValue: Accessor<string>;
+    protected readonly valueState: RuntimeValueState<RuntimeValue>;
+    protected readonly setValueState: RuntimeValueSetter<RuntimeInputValue>;
+    readonly [XPathNodeKindKey] = "element";
+    readonly getXPathValue: () => string;
+    protected abstract readonly state: SharedNodeState<ValueNodeStateSpec<RuntimeValue>>;
+    protected abstract readonly engineState: EngineState<ValueNodeStateSpec<RuntimeValue>>;
+    readonly decodeInstanceValue: DecodeInstanceValue;
+    abstract readonly nodeType: ValueNodeType;
+    readonly valueType: V;
+    abstract readonly currentState: CurrentState<ValueNodeStateSpec<RuntimeValue>>;
+    get validationState(): LeafNodeValidationState;
+    readonly submissionState: SubmissionState;
+    constructor(parent: GeneralParentNode, definition: Definition, codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>);
+    getViolation(): AnyViolation | null;
+    isBlank(): boolean;
+    getChildren(): readonly [];
+}

package/dist/instance/hierarchy.d.ts

@@ -1,22 +1,23 @@
 import { Group } from './Group.ts';
-import { ModelValue } from './ModelValue.ts';
+import { AnyInputControl } from './InputControl.ts';
+import { AnyModelValue } from './ModelValue.ts';
 import { Note } from './Note.ts';
+import { PrimaryInstance } from './PrimaryInstance.ts';
 import { RepeatInstance } from './repeat/RepeatInstance.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import { Root } from './Root.ts';
 import { SelectField } from './SelectField.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';
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
-export type UnsupportedControl = RangeControl | RankControl | UploadControl;
-export type AnyNode = Root | Group | Subtree | RepeatRange | RepeatInstance | Note | ModelValue | StringField | SelectField | TriggerControl | UnsupportedControl;
-export type AnyParentNode = Root | Group | Subtree | RepeatRange | RepeatInstance;
+export type AnyUnsupportedControl = RangeControl | RankControl | UploadControl;
+export type AnyNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance | Note | AnyModelValue | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
+export type AnyParentNode = PrimaryInstance | Root | Group | Subtree | RepeatRange | RepeatInstance;
 export type GeneralParentNode = Root | Group | Subtree | RepeatInstance;
-export type AnyChildNode = Group | Subtree | RepeatRange | RepeatInstance | ModelValue | Note | StringField | SelectField | TriggerControl | UnsupportedControl;
-export type GeneralChildNode = Group | Subtree | RepeatRange | ModelValue | Note | StringField | SelectField | TriggerControl | UnsupportedControl;
-export type AnyValueNode = ModelValue | Note | StringField | SelectField | TriggerControl | UnsupportedControl;
+export type AnyChildNode = Root | Group | Subtree | RepeatRange | RepeatInstance | AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
+export type GeneralChildNode = Group | Subtree | RepeatRange | AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;
+export type AnyValueNode = AnyModelValue | Note | AnyInputControl | SelectField | TriggerControl | AnyUnsupportedControl;

package/dist/instance/identity.d.ts

@@ -1,7 +1,2 @@
-declare const NODE_ID_BRAND: unique symbol;
-type NODE_ID_BRAND = typeof NODE_ID_BRAND;
-export type NodeID = string & {
-    readonly [NODE_ID_BRAND]: true;
-};
-export declare const declareNodeID: (id: string) => NodeID;
-export {};
+import { FormNodeID } from '../client/identity.ts';
+export declare const nodeID: (id: string) => FormNodeID;

package/dist/instance/internal-api/EvaluationContext.d.ts

@@ -1,10 +1,8 @@
-import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
+import { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import { SubscribableDependency } from './SubscribableDependency.ts';
 import { 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:
@@ -16,20 +14,63 @@ 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/dist/instance/internal-api/InstanceConfig.d.ts

@@ -1,6 +1,12 @@
-import { EngineConfig } from '../../client/EngineConfig.ts';
+import { MissingResourceBehavior } from '../../client/constants.ts';
+import { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
+import { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
 import { CreateUniqueId } from '../../lib/unique-id.ts';
-export interface InstanceConfig 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/dist/instance/internal-api/InstanceValueContext.d.ts

@@ -0,0 +1,20 @@
+import { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { 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;
+}
+export {};

package/dist/instance/internal-api/PrimaryInstanceDocument.d.ts

@@ -0,0 +1,36 @@
+import { FormLanguage } from '../../client/FormLanguage.ts';
+import { RootNode, RootNodeState } from '../../client/RootNode.ts';
+export interface PrimaryInstanceDocumentState extends Omit<RootNodeState, '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, 'nodeType' | 'currentState' | 'setLanguage'> {
+    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/dist/instance/internal-api/TranslationContext.d.ts

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

package/dist/instance/internal-api/ValidationContext.d.ts

@@ -1,9 +1,8 @@
+import { FormNodeID } from '../../client/identity.ts';
 import { AnyViolation } from '../../client/validation.ts';
 import { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
-import { NodeID } from '../identity.ts';
 import { EvaluationContext } from './EvaluationContext.ts';
-import { SubscribableDependency } from './SubscribableDependency.ts';
 interface ValidationContextCurrentState {
     get reference(): string;
 }
@@ -16,8 +15,8 @@ interface ValidationContextDefinitionBind {
 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;
     getViolation(): AnyViolation | null;

package/dist/instance/internal-api/ValueContext.d.ts

@@ -1,3 +1,4 @@
+import { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import { EvaluationContext } from './EvaluationContext.ts';
@@ -13,7 +14,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;
     readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;

package/dist/instance/internal-api/submission/ClientReactiveSubmittableInstance.d.ts

@@ -0,0 +1,14 @@
+import { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import { AncestorNodeValidationState } from '../../../client/validation.ts';
+import { Root } from '../../Root.ts';
+import { 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;
+}
+export {};

package/dist/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.d.ts

@@ -0,0 +1,31 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { EscapedXMLText } from '../../../lib/xml-serialization.ts';
+import { 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;
+}
+export {};

package/dist/instance/internal-api/submission/ClientReactiveSubmittableParentNode.d.ts

@@ -0,0 +1,18 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+export interface ClientReactiveSubmittableChildNode {
+    readonly submissionState: SubmissionState;
+}
+interface ClientReactiveSubmittableParentNodeCurrentState<Child extends ClientReactiveSubmittableChildNode> {
+    get relevant(): boolean;
+    get children(): readonly Child[];
+}
+export interface ClientReactiveSubmittableParentNodeDefinition {
+    readonly nodeName: string;
+}
+export interface ClientReactiveSubmittableParentNode<Child extends ClientReactiveSubmittableChildNode> {
+    readonly definition: ClientReactiveSubmittableParentNodeDefinition;
+    readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode> | null;
+    readonly currentState: ClientReactiveSubmittableParentNodeCurrentState<Child>;
+    readonly submissionState: SubmissionState;
+}
+export {};

package/dist/instance/internal-api/submission/ClientReactiveSubmittableValueNode.d.ts

@@ -0,0 +1,17 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableChildNode, ClientReactiveSubmittableParentNode } from './ClientReactiveSubmittableParentNode.ts';
+interface ClientReactiveSubmittableValueNodeCurrentState {
+    get relevant(): boolean;
+    get instanceValue(): string;
+}
+export type SerializedSubmissionValue = string;
+interface ClientReactiveSubmittableValueNodeDefinition {
+    readonly nodeName: string;
+}
+export interface ClientReactiveSubmittableValueNode {
+    readonly definition: ClientReactiveSubmittableValueNodeDefinition;
+    readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode>;
+    readonly currentState: ClientReactiveSubmittableValueNodeCurrentState;
+    readonly submissionState: SubmissionState;
+}
+export {};