@getodk/xforms-engine 0.1.0

package/dist/instance/Group.d.ts

@@ -0,0 +1,31 @@
+import type { Accessor } from 'solid-js';
+import type { GroupDefinition, GroupNode } from '../client/GroupNode.ts';
+import type { TextRange } from '../index.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+interface GroupStateSpec extends DescendantNodeSharedStateSpec {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: null;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+}
+export declare class Group extends DescendantNode<GroupDefinition, GroupStateSpec, GeneralChildNode> implements GroupNode, EvaluationContext, SubscribableDependency {
+    private readonly childrenState;
+    protected readonly state: SharedNodeState<GroupStateSpec>;
+    protected engineState: EngineState<GroupStateSpec>;
+    readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
+    readonly nodeType = "group";
+    constructor(parent: GeneralParentNode, definition: GroupDefinition);
+    protected computeReference(parent: GeneralParentNode): string;
+    getChildren(): readonly GeneralChildNode[];
+}
+export {};

package/dist/instance/RepeatInstance.d.ts

@@ -0,0 +1,60 @@
+import type { Accessor } from 'solid-js';
+import type { RepeatDefinition, RepeatInstanceNode } from '../client/RepeatInstanceNode.ts';
+import type { TextRange } from '../index.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { RepeatRange } from './RepeatRange.ts';
+import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { AnyChildNode, GeneralChildNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+export type { RepeatDefinition };
+interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: null;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+}
+interface RepeatInstanceOptions {
+    readonly precedingPrimaryInstanceNode: Comment | Element;
+    readonly precedingInstance: RepeatInstance | null;
+}
+export declare class RepeatInstance extends DescendantNode<RepeatDefinition, RepeatInstanceStateSpec, GeneralChildNode> implements RepeatInstanceNode, EvaluationContext, SubscribableDependency {
+    readonly parent: RepeatRange;
+    private readonly childrenState;
+    private readonly currentIndex;
+    protected readonly state: SharedNodeState<RepeatInstanceStateSpec>;
+    protected engineState: EngineState<RepeatInstanceStateSpec>;
+    readonly nodeType = "repeat-instance";
+    readonly currentState: MaterializedChildren<CurrentState<RepeatInstanceStateSpec>, GeneralChildNode>;
+    constructor(parent: RepeatRange, definition: RepeatDefinition, options: RepeatInstanceOptions);
+    protected computeReference(parent: RepeatRange): string;
+    protected initializeContextNode(parentContextNode: Element, nodeName: string): Element;
+    subscribe(): void;
+    getChildren(): readonly GeneralChildNode[];
+    /**
+     * Performs repeat instance node-specific removal logic, then general node
+     * removal logic, in that order:
+     *
+     * 1. At present, before any reactive state change is performed, the repeat
+     *    instance's {@link contextNode} is removed from the primary instance's
+     *    XML DOM backing store (which also removes any descendant nodes from that
+     *    store, as a side effect). This behavior may become unnecessary if/when
+     *    we phase out use of this XML DOM backing store. This should be peformed
+     *    first, so that any following reactive logic which evaluates affected
+     *    XPath expressions will be performed against a state consistent with the
+     *    repeat instance's removal (and that of its XML DOM descendants).
+     *
+     * 2. Performs any remaining removal logic as defined in
+     *    {@link DescendantNode.remove}.
+     *
+     * These removal steps **must also** occur before any update to the parent
+     * {@link RepeatRange}'s reactive children state.
+     */
+    remove(this: AnyChildNode): void;
+}

package/dist/instance/RepeatRange.d.ts

@@ -0,0 +1,81 @@
+import type { Accessor } from 'solid-js';
+import type { RepeatRangeNode } from '../client/RepeatRangeNode.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
+import type { RepeatDefinition } from './RepeatInstance.ts';
+import { RepeatInstance } from './RepeatInstance.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { TextRange } from './text/TextRange.ts';
+interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
+    readonly hint: null;
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+}
+export declare class RepeatRange extends DescendantNode<RepeatSequenceDefinition, RepeatRangeStateSpec, RepeatInstance> implements RepeatRangeNode, EvaluationContext, SubscribableDependency {
+    /**
+     * A repeat range doesn't have a corresponding primary instance element of its
+     * own, and its instances are appended to the range's parent element. During
+     * creation of the initial primary instance state and DOM trees, we _could_
+     * reliably append all of the range's instances in order as the definition
+     * tree is recursed. But that would fail to handle some instance addition
+     * cases afterwards.
+     *
+     * Most notably, we need to know where in the primary instance tree to append
+     * instances created for a range which is currently empty. As a lucky
+     * coincidence, this need coincides with the ability to add instances at any
+     * arbitrary index within the range. In each case, we can reference a primary
+     * instance DOM node which will become the new instance's preceding sibling.
+     * Where the range is empty, we use this {@link Comment} node (itself created
+     * and appended during range initialization) in lieu of a nonexistent
+     * preceding instance's {@link contextNode}.
+     *
+     * @todo We likely want to remove these during submission serialization.
+     * @todo Can we use a
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Range | DOM Range}
+     * instead?
+     */
+    private readonly anchorNode;
+    private readonly childrenState;
+    protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
+    protected engineState: EngineState<RepeatRangeStateSpec>;
+    readonly nodeType = "repeat-range";
+    readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
+    constructor(parent: GeneralParentNode, definition: RepeatSequenceDefinition);
+    private getLastIndex;
+    protected initializeContextNode(parentContextNode: Element): Element;
+    protected computeReference(parent: GeneralParentNode): string;
+    getInstanceIndex(instance: RepeatInstance): number;
+    addInstances(afterIndex?: number, count?: number, definition?: RepeatDefinition): Root;
+    /**
+     * Removes the {@link RepeatInstance}s corresponding to the specified range of
+     * indexes, and then removes those repeat instances from the repeat range's
+     * own children state in that order:
+     *
+     * 1. Identify the set of {@link RepeatInstance}s to be removed.
+     *
+     * 2. For each {@link RepeatInstance} pending removal, perform that node's
+     *    removal logic. @see {@link RepeatInstance.remove} for more detail.
+     *
+     * 3. Finalize update to the repeat range's own {@link childrenState},
+     *    omitting those {@link RepeatInstance}s which were removed.
+     *
+     * This ordering ensures a consistent representation of state is established
+     * prior to any downstream reactive updates, and ensures that removed nodes'
+     * reactivity is cleaned up.
+     */
+    removeInstances(startIndex: number, count?: number): Root;
+    subscribe(): void;
+    getChildren(): readonly RepeatInstance[];
+}
+export {};

package/dist/instance/Root.d.ts

@@ -0,0 +1,70 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor, Signal } from 'solid-js';
+import type { XFormDOM } from '../XFormDOM.ts';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { RootNode } from '../client/RootNode.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { RootDefinition } from '../model/RootDefinition.ts';
+import { InstanceNode } from './abstract/InstanceNode.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext, EvaluationContextRoot } from './internal-api/EvaluationContext.ts';
+import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { TranslationContext } from './internal-api/TranslationContext.ts';
+interface RootStateSpec {
+    readonly reference: string;
+    readonly readonly: boolean;
+    readonly relevant: boolean;
+    readonly required: boolean;
+    readonly label: null;
+    readonly hint: null;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+    readonly activeLanguage: Signal<ActiveLanguage>;
+}
+export declare class Root extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode> implements RootNode, EvaluationContext, EvaluationContextRoot, SubscribableDependency, TranslationContext {
+    static initialize(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig): Promise<Root>;
+    private readonly childrenState;
+    protected readonly state: SharedNodeState<RootStateSpec>;
+    protected readonly engineState: EngineState<RootStateSpec>;
+    readonly nodeType = "root";
+    readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
+    protected readonly instanceDOM: XFormDOM;
+    readonly root: this;
+    readonly evaluator: XFormsXPathEvaluator;
+    private readonly rootReference;
+    get contextReference(): string;
+    readonly contextNode: Element;
+    readonly parent: null;
+    readonly languages: FormLanguages;
+    get activeLanguage(): ActiveLanguage;
+    protected constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
+    /**
+     * Waits until form state is fully initialized.
+     *
+     * As much as possible, all instance state computations are implemented so
+     * that they complete synchronously.
+     *
+     * There is currently one exception: because instance nodes may form
+     * computation dependencies into their descendants as well as their ancestors,
+     * there is an allowance **during form initialization only** to account for
+     * this chicken/egg scenario. Note that this allowance is intentionally,
+     * strictly limited: if form state initialization is not resolved within a
+     * single microtask tick we throw/reject.
+     *
+     * All subsequent computations are always performed synchronously (and we will
+     * use tests to validate this, by utilizing the synchronously returned `Root`
+     * state from client-facing write interfaces).
+     */
+    formStateInitialized(): Promise<void>;
+    protected computeReference(_parent: null, definition: RootDefinition): string;
+    getChildren(): readonly GeneralChildNode[];
+    setLanguage(language: FormLanguage): Root;
+    subscribe(): void;
+}
+export {};

package/dist/instance/SelectField.d.ts

@@ -0,0 +1,45 @@
+import type { Accessor } from 'solid-js';
+import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
+import type { SelectItem, SelectNode } from '../client/SelectNode.ts';
+import type { TextRange } from '../index.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ValueContext } from './internal-api/ValueContext.ts';
+export interface SelectFieldDefinition extends ValueNodeDefinition {
+    readonly bodyElement: AnySelectDefinition;
+}
+interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectItem[]> {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: Accessor<TextRange<'hint'> | null>;
+    readonly children: null;
+    readonly value: SimpleAtomicState<readonly SelectItem[]>;
+    readonly valueOptions: Accessor<readonly SelectItem[]>;
+}
+export declare class SelectField extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null> implements SelectNode, EvaluationContext, SubscribableDependency, ValueContext<readonly SelectItem[]> {
+    private readonly selectExclusive;
+    protected readonly state: SharedNodeState<SelectFieldStateSpec>;
+    protected engineState: EngineState<SelectFieldStateSpec>;
+    readonly nodeType = "select";
+    readonly currentState: CurrentState<SelectFieldStateSpec>;
+    readonly encodeValue: (runtimeValue: readonly SelectItem[]) => string;
+    readonly decodeValue: (instanceValue: string) => readonly SelectItem[];
+    protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
+    constructor(parent: GeneralParentNode, definition: SelectFieldDefinition);
+    protected getSelectItemsByValue(valueOptions?: readonly SelectItem[]): ReadonlyMap<string, SelectItem>;
+    protected computeReference(parent: GeneralParentNode): string;
+    protected updateSelectedItemValues(values: readonly string[]): void;
+    protected setSelectedItemValue(value: string | null): void;
+    select(selectedItem: SelectItem): Root;
+    deselect(deselectedItem: SelectItem): Root;
+    getChildren(): readonly [];
+}
+export {};

package/dist/instance/StringField.d.ts

@@ -0,0 +1,39 @@
+import type { Accessor } from 'solid-js';
+import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { StringNode } from '../client/StringNode.ts';
+import type { TextRange } from '../index.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ValueContext } from './internal-api/ValueContext.ts';
+export interface StringFieldDefinition extends ValueNodeDefinition {
+    readonly bodyElement: InputDefinition | null;
+}
+interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: Accessor<TextRange<'hint'> | null>;
+    readonly children: null;
+    readonly value: SimpleAtomicState<string>;
+    readonly valueOptions: null;
+}
+export declare class StringField extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null> implements StringNode, EvaluationContext, SubscribableDependency, ValueContext<string> {
+    protected readonly state: SharedNodeState<StringFieldStateSpec>;
+    protected engineState: EngineState<StringFieldStateSpec>;
+    readonly nodeType = "string";
+    readonly currentState: CurrentState<StringFieldStateSpec>;
+    readonly encodeValue: (value: string) => string;
+    readonly decodeValue: (value: string) => string;
+    constructor(parent: GeneralParentNode, definition: StringFieldDefinition);
+    protected computeReference(parent: GeneralParentNode): string;
+    getChildren(): readonly [];
+    setValue(value: string): Root;
+}
+export {};

package/dist/instance/Subtree.d.ts

@@ -0,0 +1,30 @@
+import { type Accessor } from 'solid-js';
+import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
+    readonly label: null;
+    readonly hint: null;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+}
+export declare class Subtree extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralChildNode> implements SubtreeNode, EvaluationContext, SubscribableDependency {
+    private readonly childrenState;
+    protected readonly state: SharedNodeState<SubtreeStateSpec>;
+    protected engineState: EngineState<SubtreeStateSpec>;
+    readonly nodeType = "subtree";
+    readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
+    constructor(parent: GeneralParentNode, definition: SubtreeDefinition);
+    protected computeReference(parent: GeneralParentNode): string;
+    getChildren(): readonly GeneralChildNode[];
+}
+export {};

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

@@ -0,0 +1,76 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type { BaseNode } from '../../client/BaseNode.ts';
+import type { AnyDescendantNodeDefinition } from '../../model/DescendentNodeDefinition.ts';
+import type { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
+import type { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
+import type { ValueNodeDefinition } from '../../model/ValueNodeDefinition.ts';
+import type { RepeatRange } from '../RepeatRange.ts';
+import type { Root } from '../Root.ts';
+import type { AnyChildNode, GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import type { InstanceNodeStateSpec } from './InstanceNode.ts';
+import { InstanceNode } from './InstanceNode.ts';
+export interface DescendantNodeSharedStateSpec {
+    readonly reference: Accessor<string>;
+    readonly readonly: Accessor<boolean>;
+    readonly relevant: Accessor<boolean>;
+    readonly required: Accessor<boolean>;
+}
+export type DescendantNodeStateSpec<Value = never> = InstanceNodeStateSpec<Value> & DescendantNodeSharedStateSpec;
+export type DescendantNodeDefinition = Extract<AnyNodeDefinition, AnyDescendantNodeDefinition>;
+export type DescendantNodeParent<Definition extends DescendantNodeDefinition> = Definition extends ValueNodeDefinition ? GeneralParentNode : Definition extends RepeatInstanceDefinition ? RepeatRange : GeneralParentNode;
+export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any>;
+export declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Child> implements BaseNode, EvaluationContext, SubscribableDependency {
+    readonly parent: DescendantNodeParent<Definition>;
+    readonly definition: Definition;
+    readonly root: Root;
+    readonly evaluator: XFormsXPathEvaluator;
+    readonly contextNode: Element;
+    constructor(parent: DescendantNodeParent<Definition>, definition: Definition);
+    protected computeChildStepReference(parent: DescendantNodeParent<Definition>): string;
+    protected abstract computeReference(parent: DescendantNodeParent<Definition>, definition: Definition): string;
+    protected buildSharedStateSpec(parent: DescendantNodeParent<Definition>, definition: Definition): DescendantNodeSharedStateSpec;
+    protected createContextNode(parentContextNode: Element, nodeName: string): Element;
+    /**
+     * Currently expected to be overridden by...
+     *
+     * - Repeat range: returns its parent's context node, because it doesn't have
+     *   a node in the primary instance tree.
+     *
+     * - Repeat instance: returns its created context node, but overrides handles
+     *   appending behavior separately (for inserting at the end of its parent
+     *   range, or even at an arbitrary index within the range, after instance
+     *   creation is has completed).
+     */
+    protected initializeContextNode(parentContextNode: Element, nodeName: string): Element;
+    /**
+     * @package
+     *
+     * Performs recursive removal, first of the node's descendants, then of the
+     * node itself. For all {@link DescendantNode}s, removal involves **at least**
+     * disposal of its {@link scope} ({@link ReactiveScope}).
+     *
+     * It is expected that the outermost node targeted for removal will always be
+     * a {@link RepeatInstance}. @see {@link RepeatInstance.remove} for additional
+     * details.
+     *
+     * It is also expected that upon that outermost node's removal, its parent
+     * {@link RepeatRange} will perform a reactive update to its children state so
+     * that:
+     *
+     * 1. Any downstream computations affected by the removal are updated.
+     * 2. The client invoking removal is also reactively updated (where
+     *    applicable).
+     *
+     * @see {@link RepeatInstance.remove} and {@link RepeatRange.removeInstances}
+     * for additional details about their respective node-specific removal
+     * behaviors and ordering.
+     *
+     * @todo Possibly retain removed repeat instances in memory. This came up as a
+     * behavior of Collect/JavaRosa, and we should investigate the details and
+     * ramifications of that, and whether it's the desired behavior.
+     */
+    remove(this: AnyChildNode): void;
+}

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

@@ -0,0 +1,107 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor, Signal } from 'solid-js';
+import type { BaseNode } from '../../client/BaseNode.ts';
+import type { InstanceNodeType } from '../../client/node-types.ts';
+import type { TextRange } from '../../index.ts';
+import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import type { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
+import type { Root } from '../Root.ts';
+import type { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
+import type { NodeID } from '../identity.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { InstanceConfig } from '../internal-api/InstanceConfig.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+export interface InstanceNodeStateSpec<Value = never> {
+    readonly reference: Accessor<string> | string;
+    readonly readonly: Accessor<boolean> | boolean;
+    readonly relevant: Accessor<boolean> | boolean;
+    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 valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+    readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
+}
+type AnyInstanceNode = InstanceNode<AnyNodeDefinition, InstanceNodeStateSpec<any>, any>;
+interface InitializedStateOptions<T, K extends keyof T> {
+    readonly uninitializedFallback: T[K];
+}
+/**
+ * This type has the same effect as {@link MaterializedChildren}, but abstractly
+ * handles leaf node types as well.
+ */
+export type InstanceNodeCurrentState<Spec extends InstanceNodeStateSpec<any>, Child> = CurrentState<Omit<Spec, 'children'>> & {
+    readonly children: [Child] extends [AnyChildNode] ? readonly Child[] : null;
+};
+export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Child extends AnyChildNode | null = null> implements BaseNode, EvaluationContext, SubscribableDependency {
+    readonly engineConfig: InstanceConfig;
+    readonly parent: AnyParentNode | null;
+    readonly definition: Definition;
+    protected readonly isStateInitialized: Accessor<boolean>;
+    protected abstract readonly state: SharedNodeState<Spec>;
+    protected abstract readonly engineState: EngineState<Spec>;
+    /**
+     * Provides a generalized mechanism for accessing a reactive state value
+     * during a node's construction, while {@link engineState} is still being
+     * defined and thus isn't assigned.
+     *
+     * The fallback value specified in {@link options} will be returned on access
+     * until {@link isStateInitialized} returns true. This ensures:
+     *
+     * - a value of the expected type will be available
+     * - any read access will become reactive to the actual state, once it has
+     *   been initialized and {@link engineState} is assigned
+     *
+     * @todo This is one among several chicken/egg problems encountered trying to
+     * support state initialization in which some aspects of the state derive from
+     * other aspects of it. It would be nice to dispense with this entirely. But
+     * if it must persist, we should also consider replacing the method with a
+     * direct accessor once state initialization completes, so the initialized
+     * check is only called until it becomes impertinent.
+     */
+    protected getInitializedState<K extends keyof EngineState<Spec>>(key: K, options: InitializedStateOptions<EngineState<Spec>, K>): EngineState<Spec>[K];
+    /**
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
+     */
+    get isReadonly(): boolean;
+    /**
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
+     */
+    get isRelevant(): boolean;
+    readonly nodeId: NodeID;
+    abstract readonly nodeType: InstanceNodeType;
+    abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
+    abstract readonly root: Root;
+    abstract readonly evaluator: XFormsXPathEvaluator;
+    readonly scope: ReactiveScope;
+    get contextReference(): string;
+    abstract readonly contextNode: Element;
+    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition);
+    /**
+     * @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.
+     */
+    abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
+    protected abstract computeReference(parent: AnyInstanceNode | null, definition: Definition): string;
+    getNodeByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): SubscribableDependency | null;
+    getSubscribableDependencyByReference(this: AnyNode, reference: string): SubscribableDependency | null;
+    /**
+     * 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.
+     */
+    subscribe(): void;
+}
+export {};

package/dist/instance/children.d.ts

@@ -0,0 +1,2 @@
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+export declare const buildChildren: (parent: GeneralParentNode) => GeneralChildNode[];

package/dist/instance/hierarchy.d.ts

@@ -0,0 +1,12 @@
+import type { Group } from './Group.ts';
+import type { RepeatInstance } from './RepeatInstance.ts';
+import type { RepeatRange } from './RepeatRange.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';
+export type AnyNode = Root | Group | Subtree | RepeatRange | RepeatInstance | StringField | SelectField;
+export type AnyParentNode = Root | Group | Subtree | RepeatRange | RepeatInstance;
+export type GeneralParentNode = Root | Group | Subtree | RepeatInstance;
+export type AnyChildNode = Group | Subtree | RepeatRange | RepeatInstance | StringField | SelectField;
+export type GeneralChildNode = Group | Subtree | RepeatRange | StringField | SelectField;

package/dist/instance/identity.d.ts

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

package/dist/instance/index.d.ts

@@ -0,0 +1,8 @@
+import type { RootNode } from '../client/RootNode.ts';
+import type { InitializeFormOptions as BaseInitializeFormOptions, FormResource } from '../client/index.ts';
+import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
+interface InitializeFormOptions extends BaseInitializeFormOptions {
+    readonly config: Partial<InstanceConfig>;
+}
+export declare const initializeForm: (input: FormResource, options?: Partial<InitializeFormOptions>) => Promise<RootNode>;
+export {};

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

@@ -0,0 +1,34 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { SubscribableDependency } from './SubscribableDependency.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:
+ *
+ * - the expression may have dynamic dependency **references** (e.g. relative
+ *   references resolve to repeat instances or their descendants)
+ * - the expression may reference dynamic dependency **values** (e.g. an
+ *   expression referencing the value of another node)
+ * - 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
+ */
+export interface EvaluationContext {
+    readonly scope: ReactiveScope;
+    readonly evaluator: XFormsXPathEvaluator;
+    readonly root: EvaluationContextRoot;
+    /**
+     * Produces the current absolute reference to the {@link contextNode}, where
+     * the absolute `/` resolves to the active form state's primary instance root.
+     */
+    get contextReference(): string;
+    readonly contextNode: Node;
+    /**
+     * Resolves a nodeset reference, possibly relative to the
+     * {@link EvaluationContext.contextNode}.
+     */
+    readonly getSubscribableDependencyByReference: (reference: string) => SubscribableDependency | null;
+}

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

@@ -0,0 +1,8 @@
+import type { EngineConfig } from '../../client/EngineConfig.ts';
+import type { CreateUniqueId } from '../../lib/unique-id.ts';
+export interface InstanceConfig extends Required<EngineConfig> {
+    /**
+     * Uniqueness per form instance session (so e.g. persistence isn't necessary).
+     */
+    readonly createUniqueId: CreateUniqueId;
+}