@getodk/xforms-engine 0.3.0 → 0.5.0

package/dist/instance/repeat/BaseRepeatRange.d.ts

@@ -1,74 +1,64 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
+import { FormNodeID } from '../../client/identity.ts';
 import { NodeAppearances } from '../../client/NodeAppearances.ts';
 import { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import { TextRange } from '../../client/TextRange.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
+import { XFormsXPathNodeRange, XFormsXPathNodeRangeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.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 { AnyRepeatRangeDefinition, ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
-import { DescendantNodeParent, DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
-import { NodeID } from '../identity.ts';
+import { AnyRepeatRangeDefinition, ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import { RepeatInstance, RepeatDefinition } from './RepeatInstance.ts';
-
 interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
     readonly hint: null;
     readonly label: Accessor<TextRange<'label'> | null>;
-    readonly children: Accessor<readonly NodeID[]>;
+    readonly children: Accessor<readonly FormNodeID[]>;
     readonly valueOptions: null;
     readonly value: null;
 }
 type BaseRepeatRangeNodeType<Definition extends AnyRepeatRangeDefinition> = Definition extends ControlledRepeatRangeDefinition ? 'repeat-range:controlled' : 'repeat-range:uncontrolled';
-export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition> extends DescendantNode<Definition, RepeatRangeStateSpec, RepeatInstance> implements BaseRepeatRangeNode, 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?
-     */
-    protected readonly anchorNode: Comment;
+export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition> extends DescendantNode<Definition, RepeatRangeStateSpec, GeneralParentNode, RepeatInstance> implements BaseRepeatRangeNode, XFormsXPathNodeRange, EvaluationContext, ClientReactiveSubmittableParentNode<RepeatInstance> {
     protected readonly childrenState: ChildrenState<RepeatInstance>;
     /**
-     * Provides an {@link EvaluationContext} from which to evaluate expressions
-     * where some LocationPath sub-expressions may be **relative to the repeat
-     * range itself**. This is useful for evaluation of expressions where:
-     *
-     * - the expression is typically contextualized to any of its
-     *   {@link RepeatInstance} children, but it presently has none (i.e.
-     *   `relevant`)
-     *
-     * - the expression is conceptually intended to be evaluated in the context of
-     *   the repeat range itself (i.e. `jr:count`)
-     */
-    protected readonly selfEvaluationContext: EvaluationContext & {
-        readonly contextNode: Comment;
-    };
-    /**
-     * @see {@link isSelfRelevant}
+     * A repeat range doesn't have a corresponding primary instance element of its
+     * own. It is represented in the following ways:
+     *
+     * - As a comment node (in terms of XPath semantics), immediately preceding
+     *   the repeat range's {@link RepeatInstance | repeat instances} (if it
+     *   presently has any; as a placeholder where they may be appended
+     *   otherwise). This is necessary to support certain ODK XForms functionality
+     *   where an expression is expected to be evaluated against "repeats" as a
+     *   conceptual unit. Most typically, this includes:
+     *
+     *   - `jr:count` expressions associated with the repeat's body element
+     *   - `relevant` bind computations associated with the repeat's nodeset
+     *
+     * - As a subtree with {@link RepeatInstance | repeat instance} **children**,
+     *   in service of the client-facing {@link RepeatRangeNode} API (and with the
+     *   same structural semantics internally)
+     *
+     * Ultimately, this means there is a fundamental impedance mismatch between
+     * two representations which are either necessary (XPath) or high value
+     * (providing a coherent mental model for clients and the engine
+     * implementation servicing that client-facing model).
+     *
+     * In recognition that this is a truly odd mix of inherent and incidental
+     * complexity, here we use the special {@link XFormsXPathNodeRangeKind}
+     * branded type as a dedicated point of (internal) documentation where the two
+     * models diverge.
      */
-    protected readonly isEmptyRangeSelfRelevant: Accessor<boolean>;
+    readonly [XPathNodeKindKey]: XFormsXPathNodeRangeKind;
     protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
-    protected engineState: EngineState<RepeatRangeStateSpec>;
+    protected readonly engineState: EngineState<RepeatRangeStateSpec>;
     /**
      * @todo Should we special case repeat `readonly` state the same way
      * we do for `relevant`?
@@ -76,40 +66,6 @@ export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeD
      * @see {@link isSelfRelevant}
      */
     isSelfReadonly: Accessor<boolean>;
-    /**
-     * A repeat range does not exist in the primary instance tree. A `relevant`
-     * expression applies to each {@link RepeatInstance} child of the repeat
-     * range. Determining whether a repeat range itself "is relevant" isn't a
-     * concept the spec addresses, but it may be used by clients to determine
-     * whether to allow interaction with the range (e.g. by adding a repeat
-     * instance, or presenting the range's label when empty).
-     *
-     * As a naive first pass, it seems like the heuristic for this should be:
-     *
-     * 1. Does the repeat range have any repeat instance children?
-     *
-     *     - If yes, go to 2.
-     *     - If no, go to 3.
-     *
-     * 2. Does one or more of those children return `true` for the node's
-     *    `relevant` expression (i.e. is the repeat instance "self relevant")?
-     *
-     * 3. Does the relevant expression return `true` for the repeat range itself
-     *    (where, at least for now, the context of that evaluation would be the
-     *    repeat range's {@link anchorNode} to ensure correct relative expressions
-     *    resolve correctly)?
-     *
-     * @todo While (3) is proactively implemented, there isn't presently a test
-     * exercising it. It felt best for now to surface this for discussion in
-     * review to validate that it's going in the right direction.
-     *
-     * @todo While (2) **is actually tested**, the tests currently in place behave
-     * the same way with only the logic for (3), regardless of whether the repeat
-     * range actually has any repeat instance children. It's unclear (a) if that's
-     * a preferable simplification and (b) how that might affect performance (in
-     * theory it could vary depending on form structure and runtime state).
-     */
-    readonly isSelfRelevant: Accessor<boolean>;
     abstract readonly nodeType: BaseRepeatRangeNodeType<Definition>;
     /**
      * @todo RepeatRange*, RepeatInstance* (and RepeatTemplate*) all share the
@@ -147,14 +103,13 @@ export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeD
     abstract readonly appearances: NodeAppearances<Definition>;
     readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
     abstract readonly validationState: AncestorNodeValidationState;
-    constructor(parent: DescendantNodeParent<Definition>, definition: Definition);
+    readonly submissionState: SubmissionState;
+    constructor(parent: GeneralParentNode, definition: Definition);
     protected getLastIndex(): number;
-    protected initializeContextNode(parentContextNode: Element): Element;
     getInstanceIndex(instance: RepeatInstance): number;
     private createChildren;
     protected addChildren(afterIndex: number, definitions: readonly RepeatDefinition[]): readonly RepeatInstance[];
     protected removeChildren(startIndex: number, count: number): readonly RepeatInstance[];
-    subscribe(): void;
     getChildren(): readonly RepeatInstance[];
 }
 export {};

package/dist/instance/repeat/RepeatInstance.d.ts

@@ -1,35 +1,37 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
+import { FormNodeID } from '../../client/identity.ts';
 import { RepeatDefinition, RepeatInstanceNode, RepeatInstanceNodeAppearances } from '../../client/repeat/RepeatInstanceNode.ts';
+import { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import { TextRange } from '../../client/TextRange.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
+import { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.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 { DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
-import { AnyChildNode, GeneralChildNode, RepeatRange } from '../hierarchy.ts';
-import { NodeID } from '../identity.ts';
+import { GeneralChildNode, RepeatRange } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
-
+import { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 export type { RepeatDefinition };
 interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
     readonly label: Accessor<TextRange<'label'> | null>;
     readonly hint: null;
-    readonly children: Accessor<readonly NodeID[]>;
+    readonly children: Accessor<readonly FormNodeID[]>;
     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 {
+export declare class RepeatInstance extends DescendantNode<RepeatDefinition, RepeatInstanceStateSpec, RepeatRange, GeneralChildNode> implements RepeatInstanceNode, XFormsXPathElement, EvaluationContext, ClientReactiveSubmittableParentNode<GeneralChildNode> {
     readonly parent: RepeatRange;
     private readonly childrenState;
     private readonly currentIndex;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<RepeatInstanceStateSpec>;
-    protected engineState: EngineState<RepeatInstanceStateSpec>;
+    protected readonly engineState: EngineState<RepeatInstanceStateSpec>;
     /**
      * @todo Should we special case repeat `readonly` inheritance the same way
      * we do for `relevant`?
@@ -58,28 +60,7 @@ export declare class RepeatInstance extends DescendantNode<RepeatDefinition, Rep
     readonly appearances: RepeatInstanceNodeAppearances;
     readonly currentState: MaterializedChildren<CurrentState<RepeatInstanceStateSpec>, GeneralChildNode>;
     readonly validationState: AncestorNodeValidationState;
+    readonly submissionState: SubmissionState;
     constructor(parent: RepeatRange, definition: RepeatDefinition, options: RepeatInstanceOptions);
-    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/repeat/RepeatRangeControlled.d.ts

@@ -1,13 +1,12 @@
 import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
 import { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
-import { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { XFormsXPathNodeRange } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 import { BaseRepeatRange } from './BaseRepeatRange.ts';
-
-export declare class RepeatRangeControlled extends BaseRepeatRange<ControlledRepeatRangeDefinition> implements RepeatRangeControlledNode, EvaluationContext, SubscribableDependency {
+export declare class RepeatRangeControlled extends BaseRepeatRange<ControlledRepeatRangeDefinition> implements RepeatRangeControlledNode, XFormsXPathNodeRange, EvaluationContext {
     readonly nodeType = "repeat-range:controlled";
     readonly appearances: RepeatRangeNodeAppearances;
     readonly validationState: AncestorNodeValidationState;

package/dist/instance/repeat/RepeatRangeUncontrolled.d.ts

@@ -1,14 +1,13 @@
 import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
 import { RepeatRangeUncontrolledNode } from '../../client/repeat/RepeatRangeUncontrolledNode.ts';
 import { AncestorNodeValidationState } from '../../client/validation.ts';
-import { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { XFormsXPathNodeRange } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 import { Root } from '../Root.ts';
 import { BaseRepeatRange } from './BaseRepeatRange.ts';
-
-export declare class RepeatRangeUncontrolled extends BaseRepeatRange<UncontrolledRepeatRangeDefinition> implements RepeatRangeUncontrolledNode, EvaluationContext, SubscribableDependency {
+export declare class RepeatRangeUncontrolled extends BaseRepeatRange<UncontrolledRepeatRangeDefinition> implements RepeatRangeUncontrolledNode, XFormsXPathNodeRange, EvaluationContext {
     readonly nodeType = "repeat-range:uncontrolled";
     readonly appearances: RepeatRangeNodeAppearances;
     readonly validationState: AncestorNodeValidationState;

package/dist/instance/resource.d.ts

@@ -1,6 +1,5 @@
-import { FetchResource, FetchResourceResponse } from '../client/EngineConfig.ts';
 import { FormResource } from '../client/index.ts';
-
+import { FetchResource, FetchResourceResponse } from '../client/resources.ts';
 export type { FetchResource, FetchResourceResponse, FormResource };
 export interface ResourceOptions {
     readonly fetchResource: FetchResource;

package/dist/instance/text/TextChunk.d.ts

@@ -1,7 +1,6 @@
 import { ActiveLanguage } from '../../client/FormLanguage.ts';
 import { TextChunk as ClientTextChunk, TextChunkSource } from '../../client/TextRange.ts';
 import { TranslationContext } from '../internal-api/TranslationContext.ts';
-
 export declare class TextChunk implements ClientTextChunk {
     readonly context: TranslationContext;
     readonly source: TextChunkSource;

package/dist/instance/text/TextRange.d.ts

@@ -1,10 +1,9 @@
 import { TextRange as ClientTextRange, TextChunk, TextOrigin, TextRole } from '../../client/TextRange.ts';
-
 export declare class TextRange<Role extends TextRole, Origin extends TextOrigin> implements ClientTextRange<Role, Origin> {
     readonly origin: Origin;
     readonly role: Role;
     protected readonly chunks: readonly TextChunk[];
-    [Symbol.iterator](): Generator<TextChunk, void, undefined>;
+    [Symbol.iterator](): Generator<TextChunk, void, unknown>;
     get formatted(): Record<PropertyKey, unknown>;
     get asString(): string;
     constructor(origin: Origin, role: Role, chunks: readonly TextChunk[]);

package/dist/instance/unsupported/RangeControl.d.ts

@@ -0,0 +1,6 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+import { ValueContext } from '../internal-api/ValueContext.ts';
+export declare class RangeControl extends UnsupportedControl<'range'> implements ValueContext<unknown> {
+    readonly nodeType = "range";
+    readonly contextNode: this;
+}

package/dist/instance/unsupported/RankControl.d.ts

@@ -0,0 +1,6 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+import { ValueContext } from '../internal-api/ValueContext.ts';
+export declare class RankControl extends UnsupportedControl<'rank'> implements ValueContext<unknown> {
+    readonly nodeType = "rank";
+    readonly contextNode: this;
+}

package/dist/instance/unsupported/UploadControl.d.ts

@@ -0,0 +1,6 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+import { ValueContext } from '../internal-api/ValueContext.ts';
+export declare class UploadControl extends UnsupportedControl<'upload'> implements ValueContext<unknown> {
+    readonly nodeType = "upload";
+    readonly contextNode: this;
+}

package/dist/integration/xpath/EngineXPathEvaluator.d.ts

@@ -0,0 +1,14 @@
+import { XFormsItextTranslationMap, XFormsSecondaryInstanceMap, XFormsXPathEvaluator } from '@getodk/xpath';
+import { PrimaryInstance } from '../../instance/PrimaryInstance.ts';
+import { ItextTranslationRootDefinition } from '../../parse/model/ItextTranslation/ItextTranslationRootDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../../parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts';
+import { EngineXPathNode } from './adapter/kind.ts';
+interface EngineXPathEvaluatorOptions {
+    readonly rootNode: PrimaryInstance;
+    readonly itextTranslationsByLanguage: XFormsItextTranslationMap<ItextTranslationRootDefinition>;
+    readonly secondaryInstancesById: XFormsSecondaryInstanceMap<SecondaryInstanceRootDefinition>;
+}
+export declare class EngineXPathEvaluator extends XFormsXPathEvaluator<EngineXPathNode> {
+    constructor(options: EngineXPathEvaluatorOptions);
+}
+export {};

package/dist/integration/xpath/adapter/XFormsXPathNode.d.ts

@@ -0,0 +1,71 @@
+import { XPathAttributeKind, XPathCommentKind, XPathDocumentKind, XPathElementKind, XPathTextKind, XPathNodeKindKey } from '@getodk/xpath';
+declare const XFORMS_XPATH_NODE_RANGE_BRAND: unique symbol;
+/**
+ * To be used with any engine representation of a "range" of contiguous child
+ * nodes (also somewhat analogous to a DOM "fragment"). This mapping is
+ * conceptually disjoint, but serves an important purpose:
+ *
+ * - While such a "range" may increase the hierarchical depth of an
+ *   engine-internal representation, it **DOES NOT** contribute the same
+ *   hierarchy in XPath evaluation semantics.
+ * - Such a "range" may be treated as a distinct context node for evaluating an
+ *   expression. This most cleanly maps to XPath's comment semantics in that it
+ *   allows the "range" to have a clear document position (hierarchically a
+ *   child of its parent element; sequentially a sibling to that parent's other
+ *   child nodes).
+ *
+ * (Note: while this is phrased as an abstract concept, it is intended to
+ * correspond directly to the engine's "repeat range" concept. The specific type
+ * is not referenced here because they have an inverse relationship in the
+ * module/type graph.)
+ */
+export type XFormsXPathNodeRangeKind = 'comment' & {
+    readonly [XFORMS_XPATH_NODE_RANGE_BRAND]: true;
+};
+export declare const XFORMS_XPATH_NODE_RANGE_KIND: XFormsXPathNodeRangeKind;
+export type XFormsXPathNodeKind = XPathDocumentKind | XFormsXPathNodeRangeKind | XPathElementKind | XPathAttributeKind | XPathTextKind | XPathCommentKind;
+export interface XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XFormsXPathNodeKind;
+    readonly rootDocument: XFormsXPathDocument;
+    readonly root: XFormsXPathElement;
+    getXPathChildNodes(this: XFormsXPathNode): readonly XFormsXPathDescendantNode[];
+    getXPathValue(this: XFormsXPathNode): string;
+}
+export interface XFormsXPathDocument extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathDocumentKind;
+}
+export interface XFormsXPathElement extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathElementKind;
+}
+/**
+ * @see {@link XFormsXPathNodeRangeKind}
+ */
+export interface XFormsXPathNodeRange extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XFormsXPathNodeRangeKind;
+}
+export interface XFormsXPathAttribute extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathAttributeKind;
+}
+export interface XFormsXPathText extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathTextKind;
+}
+export interface XFormsXPathComment extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathCommentKind;
+}
+export type XPathNamedNodeKind = XPathElementKind | XPathAttributeKind;
+export interface XFormsXPathNamedNode extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XPathNamedNodeKind;
+}
+export type XFormsXPathDescendantNodeKind = XFormsXPathNodeRangeKind | XPathElementKind | XPathTextKind | XPathCommentKind;
+export interface XFormsXPathDescendantNode extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XFormsXPathDescendantNodeKind;
+}
+export type XFormsXPathPrimaryInstanceNodeKind = XPathDocumentKind | XFormsXPathNodeRangeKind | XPathElementKind | XPathTextKind;
+export interface XFormsXPathPrimaryInstanceNode extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceNodeKind;
+}
+export type XFormsXPathPrimaryInstanceDescendantNodeKind = XFormsXPathNodeRangeKind | XPathElementKind | XPathTextKind;
+export interface XFormsXPathPrimaryInstanceDescendantNode extends XFormsXPathNode {
+    readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceDescendantNodeKind;
+}
+export {};

package/dist/integration/xpath/adapter/engineDOMAdapter.d.ts

@@ -0,0 +1,5 @@
+import { XPathDOMAdapter } from '@getodk/xpath';
+import { EngineXPathNode } from './kind.ts';
+export interface EngineDOMAdapter extends XPathDOMAdapter<EngineXPathNode> {
+}
+export declare const engineDOMAdapter: EngineDOMAdapter;

package/dist/integration/xpath/adapter/kind.d.ts

@@ -0,0 +1,32 @@
+import { XPathNodeKind } from '@getodk/xpath';
+import { AnyChildNode, AnyNode, AnyParentNode, AnyValueNode } from '../../../instance/hierarchy.ts';
+import { ValueContext } from '../../../instance/internal-api/ValueContext.ts';
+import { PrimaryInstance } from '../../../instance/PrimaryInstance.ts';
+import { ItextTranslationDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationDefinition.ts';
+import { ItextTranslationRootDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationRootDefinition.ts';
+import { SecondaryInstanceDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts';
+import { StaticAttribute } from '../static-dom/StaticAttribute.ts';
+import { StaticDocument } from '../static-dom/StaticDocument.ts';
+import { StaticElement } from '../static-dom/StaticElement.ts';
+import { StaticText } from '../static-dom/StaticText.ts';
+import { XFormsXPathComment, XFormsXPathDocument, XFormsXPathElement, XFormsXPathPrimaryInstanceNode } from './XFormsXPathNode.ts';
+export type PrimaryInstanceXPathNode = Extract<AnyNode, XFormsXPathPrimaryInstanceNode>;
+export type PrimaryInstanceXPathElement = Extract<AnyChildNode, XFormsXPathElement>;
+export type PrimaryInstanceXPathComment = Extract<AnyChildNode, XFormsXPathComment>;
+export type PrimaryInstanceXPathChildNode = PrimaryInstanceXPathElement | PrimaryInstanceXPathComment;
+export type PrimaryInstanceXPathValueElement<Value> = AnyValueNode & ValueContext<Value> & XFormsXPathElement;
+export type EngineXPathDocument = PrimaryInstance | ItextTranslationDefinition | SecondaryInstanceDefinition | StaticDocument;
+export type EngineXPathElement = PrimaryInstanceXPathElement | ItextTranslationRootDefinition | SecondaryInstanceRootDefinition | StaticElement;
+export type EngineXPathComment = PrimaryInstanceXPathComment;
+export type EngineXPathAttribute = StaticAttribute;
+export type EngineXPathText = StaticText;
+export type XFormsXPathChildNode = EngineXPathElement | EngineXPathText | EngineXPathComment;
+type XPathAdapterParentNode = XFormsXPathDocument | XFormsXPathElement;
+type PrimaryInstanceXPathParentNode = Extract<AnyParentNode, XPathAdapterParentNode>;
+export type EngineXPathParentNode = PrimaryInstanceXPathParentNode | ItextTranslationDefinition | SecondaryInstanceDefinition | ItextTranslationRootDefinition | SecondaryInstanceRootDefinition | StaticDocument | StaticElement;
+export type EngineXPathNode = EngineXPathDocument | EngineXPathElement | EngineXPathAttribute | EngineXPathText | EngineXPathComment;
+export declare const isEngineXPathNode: (value: unknown) => value is EngineXPathNode;
+export declare const getEngineXPathNodeKind: (node: EngineXPathNode) => XPathNodeKind;
+export declare const isEngineXPathElement: (node: EngineXPathNode) => node is EngineXPathElement;
+export {};

package/dist/integration/xpath/adapter/names.d.ts

@@ -0,0 +1,16 @@
+import { EngineXPathNode } from './kind.ts';
+export declare const getEngineXPathNodeNamespaceURI: (node: EngineXPathNode) => string | null;
+/**
+ * @todo currently, neither {@link InstanceNode} nor {@link StaticNode} account
+ * for prefixes in qualified names. This was already a general enough gap that
+ * it makes sense to defer to a broader solution as it becomes a priority
+ * (likely prompted by a bug report about unexpected behavior of the XPath
+ * `name` function).
+ */
+export declare const getEngineXPathNodeQualifiedName: (node: EngineXPathNode) => string;
+export declare const getEngineXPathNodeLocalName: (node: EngineXPathNode) => string;
+export declare const getEngineProcessingInstructionName: () => never;
+/**
+ * @todo @see {@link getNamespaceDeclarations}
+ */
+export declare const resolveEngineXPathNodeNamespaceURI: (_: EngineXPathNode, prefix: string | null) => "http://www.w3.org/1999/xhtml" | "http://www.w3.org/2005/xpath-functions" | "http://openrosa.org/javarosa" | "http://www.opendatakit.org/xforms" | "http://openrosa.org/xforms" | "http://www.w3.org/2002/xforms" | "http://enketo.org/xforms" | null;

package/dist/integration/xpath/adapter/traversal.d.ts

@@ -0,0 +1,25 @@
+import { EngineXPathAttribute, EngineXPathDocument, EngineXPathElement, EngineXPathNode, EngineXPathParentNode, XFormsXPathChildNode } from './kind.ts';
+export declare const getContainingEngineXPathDocument: (node: EngineXPathNode) => EngineXPathDocument;
+export declare const getEngineXPathAttributes: (node: EngineXPathNode) => Iterable<EngineXPathAttribute>;
+/**
+ * @todo XML XForms may actually define explicit namespace declarations on
+ * non-root elements (i.e. elements other than the form definition's `h:html`,
+ * itext `translation`, secondary `instance`). Expressions defined in such forms
+ * may also expect to use those namespace declarations. It would even seem
+ * likely! Why declare namespaces on a subtree if you don't intend to use them?
+ * We don't currently capture namespace declarations below `h:html` in the parse
+ * stage (which, if we intend to support the use case, is where we should
+ * start).
+ *
+ * @todo At the very least, we should probably produce a set of default namespace declarations. At least for `h:html`, maybe for other "root" nodes.
+ */
+export declare const getNamespaceDeclarations: () => Iterable<never>;
+export declare const getParentNode: (node: EngineXPathNode) => EngineXPathParentNode | null;
+export declare const getChildNodes: (node: EngineXPathNode) => readonly XFormsXPathChildNode[];
+export declare const getChildElements: (node: EngineXPathNode) => readonly EngineXPathElement[];
+export declare const getPreviousSiblingNode: (node: EngineXPathNode) => XFormsXPathChildNode | null;
+export declare const getPreviousSiblingElement: (node: EngineXPathNode) => EngineXPathElement | null;
+export declare const getNextSiblingNode: (node: EngineXPathNode) => XFormsXPathChildNode | null;
+export declare const getNextSiblingElement: (node: EngineXPathNode) => EngineXPathElement | null;
+export declare const isDescendantNode: (ancestor: EngineXPathNode, other: EngineXPathNode) => boolean;
+export declare const compareDocumentOrder: () => never;

package/dist/integration/xpath/adapter/values.d.ts

@@ -0,0 +1,2 @@
+import { EngineXPathNode } from './kind.ts';
+export declare const getEngineXPathNodeValue: (node: EngineXPathNode) => string;

package/dist/integration/xpath/static-dom/StaticAttribute.d.ts

@@ -0,0 +1,19 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathAttribute } from '../adapter/XFormsXPathNode.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticNamedNodeOptions, StaticNamedNode } from './StaticNamedNode.ts';
+interface StaticAttributeOptions extends StaticNamedNodeOptions {
+    readonly value: string;
+}
+export declare class StaticAttribute extends StaticNamedNode<'attribute'> implements XFormsXPathAttribute {
+    readonly parent: StaticElement;
+    readonly [XPathNodeKindKey] = "attribute";
+    readonly nodeType = "static-attribute";
+    readonly root: StaticElement;
+    readonly attributes: readonly [];
+    readonly children: null;
+    readonly value: string;
+    constructor(parent: StaticElement, options: StaticAttributeOptions);
+    getXPathValue(): string;
+}
+export {};

package/dist/integration/xpath/static-dom/StaticDocument.d.ts

@@ -0,0 +1,16 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathDocument } from '../adapter/XFormsXPathNode.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticNode } from './StaticNode.ts';
+export type StaticDocumentRootFactory<T extends StaticDocument, Root extends StaticElement> = (staticDocument: T) => Root;
+export declare abstract class StaticDocument<DocumentRoot extends StaticElement = StaticElement> extends StaticNode<'document'> implements XFormsXPathDocument {
+    readonly [XPathNodeKindKey] = "document";
+    readonly nodeType = "static-document";
+    readonly rootDocument: StaticDocument;
+    readonly root: DocumentRoot;
+    readonly isXFormsNamespace: boolean;
+    readonly parent: null;
+    readonly children: readonly [root: DocumentRoot];
+    constructor(rootFactory: StaticDocumentRootFactory<StaticDocument<DocumentRoot>, DocumentRoot>);
+    getXPathValue(): string;
+}

package/dist/integration/xpath/static-dom/StaticElement.d.ts

@@ -0,0 +1,40 @@
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME, XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathElement } from '../adapter/XFormsXPathNode.ts';
+import { StaticAttribute } from './StaticAttribute.ts';
+import { StaticNamedNodeOptions, StaticNamedNode } from './StaticNamedNode.ts';
+import { StaticChildNode, StaticParentNode } from './StaticNode.ts';
+export type StaticElementAttributesFactory = (element: StaticElement) => readonly StaticAttribute[];
+export type StaticElementChildNodesFactory = (element: StaticElement) => readonly StaticChildNode[];
+export interface StaticElementOptions extends StaticNamedNodeOptions {
+}
+type StaticElementKnownAttributeValue<T extends StaticElement, LocalName extends string> = T extends {
+    readonly [XFORMS_KNOWN_ATTRIBUTE]: LocalName;
+} ? string : string | null;
+export declare class StaticElement<Parent extends StaticParentNode = StaticParentNode> extends StaticNamedNode<'element'> implements XFormsXPathElement {
+    readonly [XFORMS_LOCAL_NAME]?: string;
+    readonly [XFORMS_KNOWN_ATTRIBUTE]?: string;
+    readonly [XPathNodeKindKey] = "element";
+    readonly nodeType = "static-element";
+    readonly root: StaticElement;
+    readonly attributes: readonly StaticAttribute[];
+    readonly children: readonly StaticChildNode[];
+    constructor(parent: Parent, attributesFactory: StaticElementAttributesFactory, childNodesFactory: StaticElementChildNodesFactory, options: StaticElementOptions);
+    /**
+     * @todo Generalize this, incorporate into {@link EngineDOMAdapter}
+     * @todo Namespaced lookup
+     * @todo Optimize: lookup from map and/or caching
+     */
+    protected getAttributeNode(localName: string): StaticAttribute | null;
+    /**
+     * @todo Generalize this, incorporate into {@link EngineDOMAdapter}
+     * @todo Namespaced lookup
+     * @todo Optimize: lookup from map and/or caching (especially asserting known
+     * attributes!)
+     * @todo As long as this depends on {@link getAttributeNode}, push assertion
+     * up. (This was put off because the types are already plenty complex as it
+     * is.)
+     */
+    getAttributeValue<This extends StaticElement, LocalName extends string>(this: This, localName: LocalName): StaticElementKnownAttributeValue<This, LocalName>;
+    getXPathValue(): string;
+}
+export {};

package/dist/integration/xpath/static-dom/StaticNamedNode.d.ts

@@ -0,0 +1,17 @@
+import { XFormsXPathNamedNode, XPathNamedNodeKind } from '../adapter/XFormsXPathNode.ts';
+import { StaticDocument } from './StaticDocument.ts';
+import { StaticParentNode, StaticNode } from './StaticNode.ts';
+export interface StaticNamedNodeOptions {
+    readonly namespaceURI: string | null;
+    readonly localName: string;
+    readonly value?: string;
+}
+export declare abstract class StaticNamedNode<Kind extends XPathNamedNodeKind> extends StaticNode<Kind> implements XFormsXPathNamedNode {
+    readonly parent: StaticParentNode;
+    readonly rootDocument: StaticDocument;
+    readonly isXFormsNamespace: boolean;
+    readonly namespaceURI: string | null;
+    readonly localName: string;
+    readonly value: string | null;
+    protected constructor(parent: StaticParentNode, options: StaticNamedNodeOptions);
+}