@getodk/xforms-engine 0.3.0 → 0.5.0

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

@@ -0,0 +1,33 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathNode } from '../adapter/XFormsXPathNode.ts';
+import { StaticAttribute } from './StaticAttribute.ts';
+import { StaticDocument } from './StaticDocument.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticText } from './StaticText.ts';
+export type StaticNodeKind = 'document' | 'element' | 'attribute' | 'text';
+export type StaticNodeType<Kind extends StaticNodeKind> = `static-${Kind}`;
+export declare abstract class StaticNode<Kind extends StaticNodeKind> implements XFormsXPathNode {
+    abstract readonly [XPathNodeKindKey]: Kind;
+    abstract readonly nodeType: StaticNodeType<Kind>;
+    /**
+     * A concrete {@link StaticDocument} instance, representing the topmost node
+     * of a static document tree, containing all of:
+     *
+     * - {@link root}
+     * - {@link children}
+     * - any {@link StaticChildNode} descendants of either of the above
+     */
+    abstract readonly rootDocument: StaticDocument;
+    /**
+     * A concrete {@link StaticElement} instance, representing the single,
+     * immediate child of {@link rootDocument}, containing all other descendants
+     * of its document tree.
+     */
+    abstract readonly root: StaticElement;
+    abstract readonly children: readonly StaticChildNode[] | null;
+    getXPathChildNodes(): readonly StaticChildNode[];
+    abstract getXPathValue(): string;
+}
+export type AnyStaticNode = StaticDocument | StaticElement | StaticAttribute | StaticText;
+export type StaticParentNode = StaticDocument | StaticElement;
+export type StaticChildNode = StaticElement | StaticText;

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

@@ -0,0 +1,16 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathText } from '../adapter/XFormsXPathNode.ts';
+import { StaticDocument } from './StaticDocument.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticNode } from './StaticNode.ts';
+export declare class StaticText extends StaticNode<'text'> implements XFormsXPathText {
+    readonly parent: StaticElement;
+    readonly value: string;
+    readonly [XPathNodeKindKey] = "text";
+    readonly nodeType = "static-text";
+    readonly rootDocument: StaticDocument;
+    readonly root: StaticElement;
+    readonly children: null;
+    constructor(parent: StaticElement, value: string);
+    getXPathValue(): string;
+}

package/dist/lib/TokenListParser.d.ts

@@ -1,12 +1,12 @@
 import { PartiallyKnownString } from '../../../common/types/string/PartiallyKnownString.ts';
-
 type SymbolIterator = typeof Symbol.iterator;
 type TokenListKey<CanonicalToken extends string> = PartiallyKnownString<CanonicalToken> | SymbolIterator;
 type TokenListIterator<CanonicalToken extends string> = IterableIterator<PartiallyKnownString<CanonicalToken>>;
+type PassthroughTokenList = Readonly<Record<string, boolean>>;
 /**
  * @see {@link TokenListParser}
  */
-export type TokenList<CanonicalToken extends string = string> = {
+export type TokenList<CanonicalToken extends string = string> = PassthroughTokenList & {
     readonly [Key in TokenListKey<CanonicalToken>]: Key extends SymbolIterator ? () => TokenListIterator<CanonicalToken> : boolean;
 };
 interface TokenListAlias<CanonicalToken extends string> {
@@ -77,7 +77,7 @@ type TokenListAttributeName = PartiallyKnownString<'appearance' | 'class'>;
 export declare class TokenListParser<CanonicalToken extends string, TokenAlias extends CanonicalToken = CanonicalToken> {
     readonly canonicalTokens: readonly CanonicalToken[];
     private readonly aliases;
-    constructor(canonicalTokens: readonly CanonicalToken[], options?: TokenListParserOptions<TokenAlias>);
+    constructor(canonicalTokens?: readonly CanonicalToken[], options?: TokenListParserOptions<TokenAlias>);
     parseFrom(element: Element, attributeName: TokenListAttributeName): TokenList<CanonicalToken>;
 }
 export type ParsedTokenList<Parser extends TokenListParser<any>> = Parser extends TokenListParser<infer CanonicalToken> ? TokenList<CanonicalToken> : never;

package/dist/lib/client-reactivity/submission/createInstanceSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+export declare const createInstanceSubmissionState: (node: ClientReactiveSubmittableInstance) => SubmissionState;

package/dist/lib/client-reactivity/submission/createLeafNodeSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableLeafNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+export declare const createLeafNodeSubmissionState: <Value>(node: ClientReactiveSubmittableLeafNode<Value>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createNodeRangeSubmissionState.d.ts

@@ -0,0 +1,4 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
+export declare const createNodeRangeSubmissionState: (node: ClientReactiveSubmittableParentNode<RepeatInstance>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createParentNodeSubmissionState.d.ts

@@ -0,0 +1,4 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { GeneralChildNode } from '../../../instance/hierarchy.ts';
+import { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+export declare const createParentNodeSubmissionState: (node: ClientReactiveSubmittableParentNode<GeneralChildNode>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createValueNodeSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableValueNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+export declare const createValueNodeSubmissionState: (node: ClientReactiveSubmittableValueNode) => SubmissionState;

package/dist/lib/client-reactivity/submission/prepareSubmission.d.ts

@@ -0,0 +1,8 @@
+import { SubmissionChunkedType } from '../../../client/submission/SubmissionOptions.ts';
+import { SubmissionResult } from '../../../client/submission/SubmissionResult.ts';
+import { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+export interface PrepeareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+    readonly chunked: ChunkedType;
+    readonly maxSize: number;
+}
+export declare const prepareSubmission: <ChunkedType extends SubmissionChunkedType>(instanceRoot: ClientReactiveSubmittableInstance, options: PrepeareSubmissionOptions<ChunkedType>) => SubmissionResult<ChunkedType>;

package/dist/lib/codecs/DecimalValueCodec.d.ts

@@ -0,0 +1,6 @@
+import { ValueCodec } from './ValueCodec.ts';
+export type DecimalInputValue = bigint | number | string | null;
+export type DecimalRuntimeValue = number | null;
+export declare class DecimalValueCodec extends ValueCodec<'decimal', DecimalRuntimeValue, DecimalInputValue> {
+    constructor();
+}

package/dist/lib/codecs/IntValueCodec.d.ts

@@ -0,0 +1,6 @@
+import { ValueCodec } from './ValueCodec.ts';
+export type IntInputValue = bigint | number | string | null;
+export type IntRuntimeValue = bigint | null;
+export declare class IntValueCodec extends ValueCodec<'int', IntRuntimeValue, IntInputValue> {
+    constructor();
+}

package/dist/lib/codecs/StringValueCodec.d.ts

@@ -0,0 +1,4 @@
+import { ValueCodec } from './ValueCodec.ts';
+export declare class StringValueCodec extends ValueCodec<'string', string, string> {
+    constructor();
+}

package/dist/lib/codecs/ValueCodec.d.ts

@@ -0,0 +1,30 @@
+import { Accessor } from 'solid-js';
+import { ValueType } from '../../client/ValueType.ts';
+import { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
+import { SimpleAtomicState } from '../reactivity/types.ts';
+type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+type CodecDecoder<RuntimeValue> = (value: string) => RuntimeValue;
+type RuntimeValueAccessor<RuntimeValue> = Accessor<RuntimeValue>;
+export type RuntimeValueSetter<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (input: RuntimeInputValue) => RuntimeValue;
+export type RuntimeValueState<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = readonly [
+    get: RuntimeValueAccessor<RuntimeValue>,
+    set: RuntimeValueSetter<RuntimeValue, RuntimeInputValue>
+];
+export type CreateRuntimeValueState<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (instanceState: SimpleAtomicState<string>) => RuntimeValueState<RuntimeValue, RuntimeInputValue>;
+type RuntimeValueStateFactory<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>) => CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+type DecodeInstanceValueFactory<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>) => DecodeInstanceValue;
+interface ValueCodecOptions<RuntimeValue extends RuntimeInputValue, RuntimeInputValue> {
+    readonly decodeInstanceValueFactory?: DecodeInstanceValueFactory<RuntimeValue, RuntimeInputValue>;
+    readonly runtimeValueStateFactory?: RuntimeValueStateFactory<RuntimeValue, RuntimeInputValue>;
+}
+export declare abstract class ValueCodec<V extends ValueType, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> {
+    readonly valueType: V;
+    readonly encodeValue: CodecEncoder<RuntimeInputValue>;
+    readonly decodeValue: CodecDecoder<RuntimeValue>;
+    protected readonly defaultRuntimeValueStateFactory: RuntimeValueStateFactory<RuntimeValue, RuntimeInputValue>;
+    protected readonly defaultDecodeInstanceValueFactory: DecodeInstanceValueFactory<RuntimeValue, RuntimeInputValue>;
+    readonly decodeInstanceValue: DecodeInstanceValue;
+    readonly createRuntimeValueState: CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+    constructor(valueType: V, encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>, options?: ValueCodecOptions<RuntimeValue, RuntimeInputValue>);
+}
+export {};

package/dist/lib/codecs/ValueTypePlaceholderCodec.d.ts

@@ -0,0 +1,12 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { ValueCodec } from './ValueCodec.ts';
+/**
+ * Provides fallback functionality where a {@link ValueCodec} is expected, for
+ * those {@link ValueType | value types} which are still pending implementation.
+ * This allows consistent use of the {@link ValueCodec} interface while
+ * maintaining the current behavior of treating those unimplemented value types
+ * as string values.
+ */
+export declare class ValueTypePlaceholderCodec<V extends ValueType> extends ValueCodec<V, string, string> {
+    constructor(valueType: V);
+}

package/dist/lib/codecs/getSharedValueCodec.d.ts

@@ -0,0 +1,47 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { DecimalInputValue, DecimalRuntimeValue } from './DecimalValueCodec.ts';
+import { IntInputValue, IntRuntimeValue } from './IntValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+interface RuntimeValuesByType {
+    readonly string: string;
+    readonly int: IntRuntimeValue;
+    readonly decimal: DecimalRuntimeValue;
+    readonly boolean: string;
+    readonly date: string;
+    readonly time: string;
+    readonly dateTime: string;
+    readonly geopoint: string;
+    readonly geotrace: string;
+    readonly geoshape: string;
+    readonly binary: string;
+    readonly barcode: string;
+    readonly intent: string;
+}
+export type RuntimeValue<V extends ValueType> = RuntimeValuesByType[V];
+interface RuntimeInputValuesByType {
+    readonly string: string;
+    readonly int: IntInputValue;
+    readonly decimal: DecimalInputValue;
+    readonly boolean: string;
+    readonly date: string;
+    readonly time: string;
+    readonly dateTime: string;
+    readonly geopoint: string;
+    readonly geotrace: string;
+    readonly geoshape: string;
+    readonly binary: string;
+    readonly barcode: string;
+    readonly intent: string;
+}
+export type RuntimeInputValue<V extends ValueType> = RuntimeInputValuesByType[V];
+type SharedValueCodecs = {
+    readonly [V in ValueType]: ValueCodec<V, RuntimeValue<V>, RuntimeInputValue<V>>;
+};
+export type SharedValueCodec<V extends ValueType> = SharedValueCodecs[V];
+/**
+ * Provides codecs for each {@link ValueType | value type}, for nodes with a
+ * common representation of those value types.
+ */
+export declare const sharedValueCodecs: SharedValueCodecs;
+export declare const getSharedValueCodec: <V extends ValueType>(valueType: V) => SharedValueCodec<V>;
+export {};

package/dist/lib/dom/query.d.ts

@@ -1,6 +1,5 @@
 import { KnownAttributeLocalNamedElement, LocalNamedElement } from '../../../../common/types/dom.ts';
-import { SelectElement } from '../../body/control/select/SelectDefinition';
-
+import { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 export interface HintElement extends LocalNamedElement<'hint'> {
 }
 export interface ItemElement extends LocalNamedElement<'item'> {
@@ -24,3 +23,6 @@ export declare const getLabelElement: (parent: Element) => LabelElement | null;
 export declare const getRepeatGroupLabelElement: (parent: Element) => RepeatGroupLabelElement | null;
 export declare const getRepeatElement: (parent: Element) => RepeatElement | null;
 export declare const getValueElement: (parent: ItemElement | ItemsetElement) => ValueElement | null;
+export interface SubmissionElement extends LocalNamedElement<'submission'> {
+}
+export declare const getSubmissionElement: (parent: Element) => SubmissionElement | null;

package/dist/lib/reactivity/createChildrenState.d.ts

@@ -1,18 +1,18 @@
 import { Accessor, Setter, Signal } from 'solid-js';
+import { FormNodeID } from '../../client/identity.ts';
 import { AnyChildNode, AnyParentNode } from '../../instance/hierarchy.ts';
-import { NodeID } from '../../instance/identity.ts';
-
 export interface ChildrenState<Child extends AnyChildNode> {
     readonly children: Signal<readonly Child[]>;
     readonly getChildren: Accessor<readonly Child[]>;
     readonly setChildren: Setter<readonly Child[]>;
-    readonly childIds: Accessor<readonly NodeID[]>;
+    readonly childIds: Accessor<readonly FormNodeID[]>;
 }
 /**
  * Creates a synchronized pair of:
  *
  * - Internal children state suitable for all parent node types
- * - The same children state computed as an array of each child's {@link NodeID}
+ * - The same children state computed as an array of each child's
+ *   {@link FormNodeID}
  *
  * This state is used, in tandem with {@link materializeCurrentStateChildren},
  * to ensure children in **client-facing** state are not written into nested
@@ -27,11 +27,12 @@ export interface ChildrenState<Child extends AnyChildNode> {
  * The produced {@link ChildrenState.childIds} memo is intended to be used to
  * specify each parent node's `children` in an instance of {@link EngineState}.
  * In so doing, the node's corresponding (internal, synchronized)
- * {@link ClientState} will likewise store only the children's {@link NodeID}s.
+ * {@link ClientState} will likewise store only the children's
+ * {@link FormNodeID}s.
  *
  * As a client reacts to changes in a given parent node's `children` state, that
  * node's {@link CurrentState} should produce the child nodes corresponding to
- * those {@link NodeID}s with the aforementioned
+ * those {@link FormNodeID}s with the aforementioned
  * {@link materializeCurrentStateChildren}.
  */
 export declare const createChildrenState: <Parent extends AnyParentNode, Child extends AnyChildNode>(parent: Parent) => ChildrenState<Child>;

package/dist/lib/reactivity/createComputedExpression.d.ts

@@ -1,18 +1,30 @@
 import { Accessor } from 'solid-js';
-import { DependentExpression, DependentExpressionResultType } from '../../expression/DependentExpression.ts';
 import { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
-
+import { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import { DependentExpression, DependentExpressionResultType } from '../../parse/expression/abstract/DependentExpression.ts';
 interface ComputedExpressionResults {
     readonly boolean: boolean;
-    readonly nodes: Node[];
+    readonly nodes: EngineXPathNode[];
     readonly number: number;
     readonly string: string;
 }
 type EvaluatedExpression<Type extends DependentExpressionResultType> = ComputedExpressionResults[Type];
 type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<EvaluatedExpression<Type>>;
-interface CreateComputedExpressionOptions {
-    readonly arbitraryDependencies?: readonly SubscribableDependency[];
+interface CreateComputedExpressionOptions<Type extends DependentExpressionResultType> {
+    /**
+     * If a default value is provided, {@link createComputedExpression} will
+     * produce this value for computations in a non-attached evaluation context,
+     * i.e. when evaluating an expression against a node which has not yet been
+     * appended to its parents children state (or which has since been removed
+     * from that state). A non-attached state is detected when
+     * {@link EvaluationContext.isAttached} returns false.
+     *
+     * If no default value is provided, an implicit default value is produced as
+     * appropriate for the expression's intrinsic result type.
+     *
+     * @see {@link defaultEvaluationsByType} for these implicit defaults.
+     */
+    readonly defaultValue?: EvaluatedExpression<Type>;
 }
-export declare const createComputedExpression: <Type extends DependentExpressionResultType>(context: EvaluationContext, dependentExpression: DependentExpression<Type>, options?: CreateComputedExpressionOptions) => ComputedExpression<Type>;
+export declare const createComputedExpression: <Type extends DependentExpressionResultType>(context: EvaluationContext, dependentExpression: DependentExpression<Type>, options?: CreateComputedExpressionOptions<Type>) => ComputedExpression<Type>;
 export {};

package/dist/lib/reactivity/createInstanceValueState.d.ts

@@ -0,0 +1,40 @@
+import { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
+import { SimpleAtomicState } from './types.ts';
+type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
+export interface InstanceValueStateOptions {
+    /**
+     * Specifies the source of a {@link createInstanceValueState} signal's initial
+     * value state, where:
+     *
+     * - 'FORM_DEFAULT': Derives the initial state from the form's definition of
+     *   the node itself. This is the default option, appropriate when
+     *   initializing a form without additional primary instance data. In other
+     *   words, this value should not be used for edits.
+     *
+     * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
+     *   content of the {@link ValueNode.contextNode}. This option should be
+     *   specified when initializing a form with existing primary instance data,
+     *   such as when editing a previous submission.
+     *
+     * @default 'FORM_DEFAULT'
+     *
+     * Specifies whether a {@link createInstanceValueState} signal's initial state
+     * should be derived from the current text content of the
+     * {@link ValueNode.contextNode | primary instance DOM state}.
+     */
+    readonly initialValueSource?: InitialValueSource;
+}
+export type InstanceValueState = SimpleAtomicState<string>;
+/**
+ * Provides a consistent interface for value nodes of any type which:
+ *
+ * - derives initial state from either an existing instance (e.g. for edits) or
+ *   the node's definition (e.g. initializing a new submission)
+ * - decodes current primary instance state into the value node's runtime type
+ * - encodes updated runtime values to store updated instance state
+ * - initializes reactive computation of `calculate` bind expressions for those
+ *   nodes defined with one
+ * - prevents downstream writes to nodes in a readonly state
+ */
+export declare const createInstanceValueState: (context: InstanceValueContext, options?: InstanceValueStateOptions) => InstanceValueState;
+export {};

package/dist/lib/reactivity/createNoteReadonlyThunk.d.ts

@@ -1,5 +1,4 @@
 import { Accessor } from 'solid-js';
 import { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
-import { BindComputation } from '../../model/BindComputation.ts';
-
-export declare const createNoteReadonlyThunk: (context: EvaluationContext, readonlyDefinition: BindComputation<"readonly">) => Accessor<true>;
+import { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
+export declare const createNoteReadonlyThunk: (context: EvaluationContext, definition: NoteNodeDefinition) => Accessor<true>;

package/dist/lib/reactivity/createSelectItems.d.ts

@@ -1,7 +1,6 @@
 import { Accessor } from 'solid-js';
 import { SelectItem } from '../../index.ts';
 import { SelectField } from '../../instance/SelectField.ts';
-
 /**
  * Creates a reactive computation of a {@link SelectField}'s
  * {@link SelectItem}s, in support of the field's `valueOptions`.

package/dist/lib/reactivity/createTranslationState.d.ts

@@ -0,0 +1,19 @@
+import { Accessor } from 'solid-js';
+import { ActiveLanguage, FormLanguage, FormLanguages } from '../../client/FormLanguage.ts';
+import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import { ReactiveScope } from './scope.ts';
+import { SimpleAtomicStateSetter } from './types.ts';
+interface TranslationState {
+    readonly languages: FormLanguages;
+    readonly getActiveLanguage: Accessor<ActiveLanguage>;
+    readonly setActiveLanguage: SimpleAtomicStateSetter<FormLanguage>;
+}
+/**
+ * @todo It's been very silly all along that {@link XFormsXPathEvaluator} is
+ * responsible for parsing translation languages, and maintaining the active
+ * language state. It is especially silly now that we've moved _part of the
+ * parsing_ up to the constructor call site. Let's finish off that awkwardness
+ * in a subsequent refactor.
+ */
+export declare const createTranslationState: (scope: ReactiveScope, evaluator: EngineXPathEvaluator) => TranslationState;
+export {};

package/dist/lib/reactivity/createValueState.d.ts

@@ -1,6 +1,5 @@
 import { ValueContext } from '../../instance/internal-api/ValueContext.ts';
 import { SimpleAtomicState } from './types.ts';
-
 type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
 export interface ValueStateOptions {
     /**
@@ -13,8 +12,7 @@ export interface ValueStateOptions {
      *   other words, this value should not be used for edits.
      *
      * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
-     *   content of the {@link ValueNode.contextNode} (currently an XML DOM
-     *   backing store/source of thruth for primary instance state). This option
+     *   content of the {@link ValueNode.contextNode}. This option
      *   should be specified when initializing a form with existing primary
      *   instance data, such as when editing a previous submission.
      *
@@ -30,16 +28,13 @@ type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
 /**
  * Provides a consistent interface for value nodes of any type which:
  *
- * - derives initial state from either the existing primary instance state (e.g.
- *   for edits) or the node's definition (e.g. initializing a new submission)
- * - decodes primary instance state into the value node's runtime type
- * - encodes and persists updated values to the primary instance
+ * - derives initial state from either an existing instance (e.g. for edits) or
+ *   the node's definition (e.g. initializing a new submission)
+ * - decodes current primary instance state into the value node's runtime type
+ * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those
  *   nodes defined with one
- * - ensures any downstream reactive dependencies are updated only after writes
- *   (whether performed by a client, or by a reactive `calculate` computation)
- *   are persisted, ensuring a consistent view of state when downstream
- *   computations perform XPath evaluations against that primary instance state
+ * - prevents downstream writes to nodes in a readonly state
  */
 export declare const createValueState: <RuntimeValue>(context: ValueContext<RuntimeValue>, options?: ValueStateOptions) => ValueState<RuntimeValue>;
 export {};

package/dist/lib/reactivity/materializeCurrentStateChildren.d.ts

@@ -1,10 +1,9 @@
+import { FormNodeID } from '../../client/identity.ts';
 import { AnyChildNode } from '../../instance/hierarchy.ts';
-import { NodeID } from '../../instance/identity.ts';
 import { ChildrenState } from './createChildrenState.ts';
 import { ReactiveScope } from './scope.ts';
-
 export interface EncodedParentState {
-    readonly children: readonly NodeID[];
+    readonly children: readonly FormNodeID[];
 }
 export type MaterializedChildren<BaseState extends EncodedParentState, Child extends AnyChildNode | null> = Omit<BaseState, 'children'> & {
     readonly children: readonly Child[];
@@ -12,8 +11,8 @@ export type MaterializedChildren<BaseState extends EncodedParentState, Child ext
 /**
  * Creates a wrapper proxy around a parent node's {@link CurrentState} to map
  * `children` state, which is written to the node's (internal, synchronized)
- * {@link ClientState} as an array of {@link NodeID}s, back to the node objects
- * corresponding to those IDs.
+ * {@link ClientState} as an array of {@link FormNodeID}s, back to the node
+ * objects corresponding to those IDs.
  *
  * @see {@link createChildrenState} for further detail.
  */

package/dist/lib/reactivity/node-state/createClientState.d.ts

@@ -4,7 +4,6 @@ import { ReactiveScope } from '../scope.ts';
 import { EngineState } from './createEngineState.ts';
 import { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
 import { InternalClientRepresentation } from './representations.ts';
-
 export type SpecifiedClientStateFactory<Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec> = ShallowMutable<SpecifiedState<Spec>> extends Parameters<Factory>[0] ? Factory : never;
 export type ClientState<Spec extends StateSpec> = InternalClientRepresentation<SpecifiedState<Spec>>;
 export declare const createClientState: <Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec>(scope: ReactiveScope, engineState: EngineState<Spec>, clientStateFactory: SpecifiedClientStateFactory<Factory, Spec>) => ClientState<Spec>;

package/dist/lib/reactivity/node-state/createCurrentState.d.ts

@@ -2,6 +2,5 @@ import { ReactiveScope } from '../scope.ts';
 import { ClientState } from './createClientState.ts';
 import { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
 import { ReadonlyClientRepresentation } from './representations.ts';
-
 export type CurrentState<Spec extends StateSpec> = ReadonlyClientRepresentation<SpecifiedState<Spec>>;
 export declare const createCurrentState: <Spec extends StateSpec>(scope: ReactiveScope, clientState: ClientState<Spec>) => CurrentState<Spec>;

package/dist/lib/reactivity/node-state/createEngineState.d.ts

@@ -1,6 +1,5 @@
 import { ReactiveScope } from '../scope.ts';
 import { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
 import { EngineRepresentation } from './representations.ts';
-
 export type EngineState<Spec extends StateSpec> = EngineRepresentation<SpecifiedState<Spec>>;
 export declare const createEngineState: <Spec extends StateSpec>(scope: ReactiveScope, spec: Spec) => EngineState<Spec>;

package/dist/lib/reactivity/node-state/createSharedNodeState.d.ts

@@ -4,7 +4,6 @@ import { ClientState, SpecifiedClientStateFactory } from './createClientState.ts
 import { CurrentState } from './createCurrentState.ts';
 import { EngineState } from './createEngineState.ts';
 import { MutablePropertySpec, SpecifiedState, StateSpec } from './createSpecifiedState.ts';
-
 type MutableKeyOf<Spec extends StateSpec> = {
     [K in string & keyof Spec]: Spec[K] extends MutablePropertySpec<any> ? K : never;
 }[string & keyof Spec];

package/dist/lib/reactivity/node-state/createSpecifiedPropertyDescriptor.d.ts

@@ -1,5 +1,4 @@
 import { StatePropertySpec } from './createSpecifiedState.ts';
-
 export interface SpecifiedPropertyDescriptor<T = any> extends TypedPropertyDescriptor<T> {
     readonly configurable: true;
     readonly enumerable: true;

package/dist/lib/reactivity/node-state/createSpecifiedState.d.ts

@@ -1,6 +1,5 @@
 import { Accessor, Signal } from 'solid-js';
 import { SimpleAtomicState } from '../types.ts';
-
 /**
  * Specifies a state object's property as mutable. Basic usage:
  *

package/dist/lib/reactivity/node-state/representations.d.ts

@@ -1,5 +1,4 @@
 import { ShallowMutable } from '../../../../../common/types/helpers.js';
-
 declare const ENGINE_REPRESENTATION: unique symbol;
 type ENGINE_REPRESENTATION = typeof ENGINE_REPRESENTATION;
 declare const INTERNAL_CLIENT_REPRESENTATION: unique symbol;

package/dist/lib/reactivity/scope.d.ts

@@ -1,5 +1,4 @@
 import { Owner } from 'solid-js';
-
 type ReactiveScopeTask<T> = (scope: ReactiveScope) => T;
 type RunReactiveScopeTask = <T>(task: ReactiveScopeTask<T>) => T;
 export interface ReactiveScope {

package/dist/lib/reactivity/text/createFieldHint.d.ts

@@ -1,6 +1,5 @@
 import { Accessor } from 'solid-js';
 import { TextRange } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { LeafNodeDefinition } from '../../../model/LeafNodeDefinition.ts';
-
+import { LeafNodeDefinition } from '../../../parse/model/LeafNodeDefinition.ts';
 export declare const createFieldHint: (context: EvaluationContext, definition: LeafNodeDefinition) => Accessor<TextRange<"hint", "form"> | null>;

package/dist/lib/reactivity/text/createNodeLabel.d.ts

@@ -1,6 +1,5 @@
 import { Accessor } from 'solid-js';
 import { TextRange } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { AnyNodeDefinition } from '../../../model/NodeDefinition.ts';
-
+import { AnyNodeDefinition } from '../../../parse/model/NodeDefinition.ts';
 export declare const createNodeLabel: (context: EvaluationContext, definition: AnyNodeDefinition) => Accessor<TextRange<"label", "form"> | null>;

package/dist/lib/reactivity/text/createNoteText.d.ts

@@ -1,8 +1,7 @@
 import { Accessor } from 'solid-js';
 import { TextRange } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { NoteTextDefinition } from '../../../parse/NoteNodeDefinition.ts';
-
+import { NoteTextDefinition } from '../../../parse/model/NoteNodeDefinition.ts';
 export type NoteTextRole = 'label' | 'hint';
 export type ComputedNoteText<Role extends NoteTextRole = NoteTextRole> = Accessor<TextRange<Role, 'form'>>;
 interface BaseNoteText {

package/dist/lib/reactivity/text/createTextRange.d.ts

@@ -3,7 +3,6 @@ import { TextRole } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
 import { TextRange } from '../../../instance/text/TextRange.ts';
 import { TextRangeDefinition } from '../../../parse/text/abstract/TextRangeDefinition.ts';
-
 type ComputedFormTextRange<Role extends TextRole> = Accessor<TextRange<Role, 'form'>>;
 /**
  * Creates a text range (e.g. label or hint) from the provided definition,

package/dist/lib/reactivity/types.d.ts

@@ -1,5 +1,4 @@
 import { Accessor, Setter } from 'solid-js';
-
 /**
  * A write interface to reactive atomic state. This type is intended to be used
  * as a relaxed version of {@link Setter}, where its callback form isn't

package/dist/lib/reactivity/validation/createAggregatedViolations.d.ts

@@ -1,7 +1,6 @@
 import { OpaqueReactiveObjectFactory } from '../../../client/OpaqueReactiveObjectFactory.ts';
 import { AncestorNodeValidationState } from '../../../client/validation.ts';
 import { AnyParentNode } from '../../../instance/hierarchy.ts';
-
 interface AggregatedViolationsOptions {
     readonly clientStateFactory: OpaqueReactiveObjectFactory<AncestorNodeValidationState>;
 }

package/dist/lib/reactivity/validation/createValidation.d.ts

@@ -3,7 +3,6 @@ import { OpaqueReactiveObjectFactory } from '../../../client/OpaqueReactiveObjec
 import { AnyViolation, ConditionValidation, ValidationCondition } from '../../../client/validation.ts';
 import { ValidationContext } from '../../../instance/internal-api/ValidationContext.ts';
 import { SharedNodeState, SharedNodeStateOptions } from '../node-state/createSharedNodeState.ts';
-
 type ComputedConditionValidation<Condition extends ValidationCondition> = Accessor<ConditionValidation<Condition>>;
 type ComputedViolation = Accessor<AnyViolation | null>;
 interface ValidationStateSpec {