@getodk/xforms-engine 0.1.0

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

@@ -0,0 +1,59 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+/**
+ * Provides a common interface to explicitly establish a reactive subscription
+ * to a form node, regardless of which node-specific details might trigger
+ * reactive updates. This is primarily intended for use in coordination with a
+ * node's {@link EvaluationContext} interface, so that computed expression
+ * evaluations can be re-executed when their dependencies update, without
+ * requiring a given evaluation to handle node-specific logic to determine
+ * when/whether updates have occurred.
+ *
+ * @example Given a form with these bindings:
+ *
+ * ```xml
+ * <bind nodeset="/data/field-1" />
+ * <bind nodeset="/data/field-2" type="int" />
+ * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
+ * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
+ * ```
+ *
+ * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
+ *
+ * - `/data-field-2` (explicit)
+ * - `/data/group-a` (implicit: non-relevance is inherited)
+ *
+ * (This is an oversimplification, but it helps to illustrate the concept.)
+ *
+ * The first dependency's subscription is clearly concerned with that leaf
+ * node's value. In which case, that node's `subscribe` method should react to
+ * updates to its value (e.g. its `currentState.value` or the internal reactive
+ * representation thereof).
+ *
+ * Whereas the second dependency has no value (no parent nodes do); instead, the
+ * subscription would be concerned with that node's relevance. In which case,
+ * that node's `subscribe` method should react to updates to its relevance state
+ * (e.g. its `currentState.relevant` or the internal reactive represeentation
+ * thereof).
+ *
+ * @example Given a form with:
+ *
+ * ```xml
+ * <!-- model -->
+ * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
+ * <!-- body -->
+ * <repeat nodeset="/data/repeat-a" />
+ * ```
+ *
+ * The field `/data/repeat-a/field-a-1` has a dependency on its containing
+ * repeat instance. That node also doesn't have a value, and here the dynamic
+ * aspect of the dependency is the node's current position. Here the node's
+ * `subscribe` method should react to changes in its position (likely indirectly
+ * by reading its `contextReference`).
+ *
+ * @see {@link EvaluationContext}
+ * @see {@link EvaluationContext.contextReference}
+ */
+export interface SubscribableDependency {
+    readonly scope: ReactiveScope;
+    readonly subscribe: VoidFunction;
+}

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

@@ -0,0 +1,4 @@
+import type { ActiveLanguage } from '../../index.ts';
+export interface TranslationContext {
+    get activeLanguage(): ActiveLanguage;
+}

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

@@ -0,0 +1,22 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputation } from '../../model/BindComputation.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+export type InstanceValue = string;
+interface ValueContextDefinitionBind {
+    readonly calculate: BindComputation<'calculate'> | null;
+    readonly readonly: BindComputation<'readonly'>;
+}
+export interface ValueContextDefinition {
+    readonly bind: ValueContextDefinitionBind;
+    readonly defaultValue: InstanceValue;
+}
+export interface ValueContext<RuntimeValue> extends EvaluationContext {
+    readonly scope: ReactiveScope;
+    readonly definition: ValueContextDefinition;
+    readonly contextNode: Element;
+    get isReadonly(): boolean;
+    get isRelevant(): boolean;
+    readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;
+    readonly decodeValue: (this: unknown, instanceValue: InstanceValue) => RuntimeValue;
+}
+export {};

package/dist/instance/resource.d.ts

@@ -0,0 +1,10 @@
+import type { FetchResource, FetchResourceResponse } from '../client/EngineConfig.ts';
+import type { FormResource } from '../client/index.ts';
+export type { FetchResource, FetchResourceResponse, FormResource };
+export interface ResourceOptions {
+    readonly fetchResource: FetchResource;
+}
+declare const resourceXMLPrefix = "<";
+type ResourceXMLPrefix = typeof resourceXMLPrefix;
+type ResourceXML = `${ResourceXMLPrefix}${string}`;
+export declare const retrieveSourceXMLResource: (resource: FormResource, options: ResourceOptions) => Promise<ResourceXML>;

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

@@ -0,0 +1 @@
+export declare const FormattedTextStub: Record<PropertyKey, unknown>;

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

@@ -0,0 +1,11 @@
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
+import type { TextChunk as ClientTextChunk, TextChunkSource } from '../../client/TextRange.ts';
+import type { TranslationContext } from '../internal-api/TranslationContext.ts';
+export declare class TextChunk implements ClientTextChunk {
+    readonly context: TranslationContext;
+    readonly source: TextChunkSource;
+    readonly asString: string;
+    get formatted(): Record<PropertyKey, unknown>;
+    get language(): ActiveLanguage;
+    constructor(context: TranslationContext, source: TextChunkSource, asString: string);
+}

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

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

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

@@ -0,0 +1,20 @@
+import type { KnownAttributeLocalNamedElement, LocalNamedElement } from '../../../../common/types/dom.ts';
+import type { SelectElement } from '../../body/control/select/SelectDefinition';
+export interface HintElement extends LocalNamedElement<'hint'> {
+}
+export interface ItemElement extends LocalNamedElement<'item'> {
+}
+export interface ItemsetElement extends KnownAttributeLocalNamedElement<'itemset', 'nodeset'> {
+}
+export interface LabelElement extends LocalNamedElement<'label'> {
+}
+export interface RepeatElement extends KnownAttributeLocalNamedElement<'repeat', 'nodeset'> {
+}
+export interface ValueElement extends LocalNamedElement<'value'> {
+}
+export declare const getHintElement: (parent: Element) => HintElement | null;
+export declare const getItemElements: (parent: SelectElement) => readonly ItemElement[];
+export declare const getItemsetElement: (parent: Element) => ItemsetElement | null;
+export declare const getLabelElement: (parent: Element) => LabelElement | null;
+export declare const getRepeatElement: (parent: Element) => RepeatElement | null;
+export declare const getValueElement: (parent: ItemElement | ItemsetElement) => ValueElement | null;

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

@@ -0,0 +1,36 @@
+import { type Accessor, type Setter, type Signal } from 'solid-js';
+import type { AnyChildNode, AnyParentNode } from '../../instance/hierarchy.ts';
+import type { 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[]>;
+}
+/**
+ * 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}
+ *
+ * This state is used, in tandem with {@link materializeCurrentStateChildren},
+ * to ensure children in **client-facing** state are not written into nested
+ * {@link OpaqueReactiveObjectFactory} calls.
+ *
+ * The produced {@link ChildrenState.children} (and its get/set convenience
+ * methods) signal is intended to be used to store the engine's children state,
+ * and update that state when appropriate (when appending children of any parent
+ * node during form initialization, and when appending repeat instances and
+ * their descendants subsequently during a form session).
+ *
+ * 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.
+ *
+ * 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
+ * {@link materializeCurrentStateChildren}.
+ */
+export declare const createChildrenState: <Parent extends AnyParentNode, Child extends AnyChildNode>(parent: Parent) => ChildrenState<Child>;

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

@@ -0,0 +1,12 @@
+import type { Accessor } from 'solid-js';
+import type { DependentExpression, DependentExpressionResultType } from '../../expression/DependentExpression.ts';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+interface ComputedExpressionResults {
+    readonly boolean: boolean;
+    readonly nodes: Node[];
+    readonly string: string;
+}
+type EvaluatedExpression<Type extends DependentExpressionResultType> = ComputedExpressionResults[Type];
+type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<EvaluatedExpression<Type>>;
+export declare const createComputedExpression: <Type extends "string" | "boolean" | "nodes">(context: EvaluationContext, dependentExpression: DependentExpression<Type>) => ComputedExpression<Type>;
+export {};

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

@@ -0,0 +1,16 @@
+import type { Accessor } from 'solid-js';
+import type { SelectItem } from '../../index.ts';
+import type { SelectField } from '../../instance/SelectField.ts';
+/**
+ * Creates a reactive computation of a {@link SelectField}'s
+ * {@link SelectItem}s, in support of the field's `valueOptions`.
+ *
+ * - Selects defined with static `<item>`s will compute to an corresponding
+ *   static list of items.
+ * - Selects defined with a computed `<itemset>` will compute to a reactive list
+ *   of items.
+ * - Items of both will produce {@link SelectItem.label | labels} reactive to
+ *   their appropriate dependencies (whether relative to the itemset item node,
+ *   referencing a form's `itext` translations, etc).
+ */
+export declare const createSelectItems: (selectField: SelectField) => Accessor<readonly SelectItem[]>;

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

@@ -0,0 +1,44 @@
+import type { ValueContext } from '../../instance/internal-api/ValueContext.ts';
+import type { SimpleAtomicState } from './types.ts';
+type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
+export interface ValueStateOptions {
+    /**
+     * Specifies the source of a {@link createValueState} 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} (currently an XML DOM
+     *   backing store/source of thruth for primary instance state). 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 createV} signal's initial state
+     * should be derived from the current text content of the
+     * {@link ValueNode.contextNode | primary instance DOM state}.
+     */
+    readonly initialValueSource?: InitialValueSource;
+}
+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
+ * - 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
+ */
+export declare const createValueState: <RuntimeValue>(context: ValueContext<RuntimeValue>, options?: ValueStateOptions) => ValueState<RuntimeValue>;
+export {};

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

@@ -0,0 +1,18 @@
+import type { AnyChildNode } from '../../instance/hierarchy.ts';
+import type { NodeID } from '../../instance/identity.ts';
+import type { ChildrenState } from './createChildrenState.ts';
+export interface EncodedParentState {
+    readonly children: readonly NodeID[];
+}
+export type MaterializedChildren<BaseState extends EncodedParentState, Child extends AnyChildNode | null> = Omit<BaseState, 'children'> & {
+    readonly children: readonly Child[];
+};
+/**
+ * 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.
+ *
+ * @see {@link createChildrenState} for further detail.
+ */
+export declare const materializeCurrentStateChildren: <Child extends AnyChildNode, ParentState extends EncodedParentState>(currentState: ParentState, childrenState: ChildrenState<Child>) => MaterializedChildren<ParentState, Child>;

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

@@ -0,0 +1,9 @@
+import type { ShallowMutable } from '../../../../../common/types/helpers.js';
+import type { OpaqueReactiveObjectFactory } from '../../../index.ts';
+import type { ReactiveScope } from '../scope.ts';
+import type { EngineState } from './createEngineState.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import type { 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

@@ -0,0 +1,6 @@
+import type { ReactiveScope } from '../scope.ts';
+import type { ClientState } from './createClientState.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import type { 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

@@ -0,0 +1,5 @@
+import type { ReactiveScope } from '../scope.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import type { 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

@@ -0,0 +1,22 @@
+import type { OpaqueReactiveObjectFactory } from '../../../index.ts';
+import type { ReactiveScope } from '../scope.ts';
+import type { ClientState, SpecifiedClientStateFactory } from './createClientState.ts';
+import type { CurrentState } from './createCurrentState.ts';
+import type { EngineState } from './createEngineState.ts';
+import type { 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];
+type SetEnginePropertyState<Spec extends StateSpec> = <K extends MutableKeyOf<Spec>>(key: K, newValue: SpecifiedState<Spec>[K]) => SpecifiedState<Spec>[K];
+export interface SharedNodeState<Spec extends StateSpec> {
+    readonly spec: Spec;
+    readonly engineState: EngineState<Spec>;
+    readonly clientState: ClientState<Spec>;
+    readonly currentState: CurrentState<Spec>;
+    readonly setProperty: SetEnginePropertyState<Spec>;
+}
+interface SharedNodeStateOptions<Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec> {
+    readonly clientStateFactory: SpecifiedClientStateFactory<Factory, Spec>;
+}
+export declare const createSharedNodeState: <Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec>(scope: ReactiveScope, spec: Spec, options: SharedNodeStateOptions<Factory, Spec>) => SharedNodeState<Spec>;
+export {};

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

@@ -0,0 +1,6 @@
+import type { StatePropertySpec } from './createSpecifiedState.ts';
+export interface SpecifiedPropertyDescriptor<T = any> extends TypedPropertyDescriptor<T> {
+    readonly configurable: true;
+    readonly enumerable: true;
+}
+export declare const createSpecifiedPropertyDescriptor: <T>(propertySpec: StatePropertySpec<T>) => SpecifiedPropertyDescriptor<T>;

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

@@ -0,0 +1,139 @@
+import type { Accessor, Signal } from 'solid-js';
+import type { SimpleAtomicState } from '../types.ts';
+/**
+ * Specifies a state object's property as mutable. Basic usage:
+ *
+ * ```ts
+ * import { createSignal } from 'solid-js';
+ *
+ * const count = createSignal(1);
+ *
+ * const state = createSpecifiedState({ count });
+ * //    ^? { count: number }
+ * ```
+ *
+ * While basic usage involves passing a Solid {@link Signal}, a
+ * {@link SimpleAtomicState} type is also supported, allowing a slightly more
+ * permissive setter type.
+ *
+ * @see {@link SimpleAtomicState} and its related types for more detail.
+ *
+ * A property specified with this type will be used to define a reactively
+ * mutable property on the resulting state object where:
+ *
+ * - Reading the property will read its value from the provided spec's getter
+ *   function, establishing an internally reactive subscription.
+ *
+ * - Mutating the property will pass the assigned value to the provided spec's
+ *   setter function, triggering any downstream computations—whether that
+ *   computation is associated with the provided spec itself, or reads from the
+ *   derived property.
+ *
+ * - All such mutations will be propagated to any derived (client) state object.
+ */
+export type MutablePropertySpec<T> = SimpleAtomicState<T> | Signal<T>;
+/**
+ * Specifies a state object's property as reactively computed, and read-only.
+ * Basic usage:
+ *
+ * ```ts
+ * import { createMemo, createSignal } from 'solid-js';
+ *
+ * const [count, setCount] = createSignal(1);
+ * const doubleCount = createMemo(() => count() * 2);
+ *
+ * const state = createSpecifiedState({ doubleCount });
+ * //    ^? { readonly doubleCount: number }
+ * ```
+ *
+ * Note: ideally, the produced type would better reflect the computed nature of
+ * the resulting property. Unfortunately this isn't currently supported by the
+ * TypeScript type system (by inferring the derived state type). This tradeoff
+ * is reasonable for internal engine use, but should not be used to derive types
+ * which will be directly consumed by clients.
+ *
+ * Any property specified by a thunk (zero-argument function) is supported. A
+ * property specified with this type will be used to define a reactively
+ * readable property on the resulting state object where:
+ *
+ * - Reading the property will read its value on each access, establishing an
+ *   internally reactive subscription (presuming the input property spec is
+ *   itself reactive).
+ *
+ * - Mutating the property will throw a {@link TypeError}, just as it would when
+ *   attempting to mutate a normal `get` accessor.
+ *
+ * - Any change which would result in a reactive update in the property spec
+ *   itself will be propagated to any derived (client) state object.
+ */
+export type ComputedPropertySpec<T> = Accessor<T>;
+/**
+ * @see {@link StaticPropertySpec}
+ */
+type NonStaticValue = Function | Signal<any> | SimpleAtomicState<any>;
+/**
+ * Specifies a state object's property with a static value, immutable for the
+ * lifetime of that state object. Basic usage:
+ *
+ * ```ts
+ * const state = createSpecifiedState({ num: 10 });
+ * //    ^? { readonly num: number }
+ * ```
+ *
+ * Properties will be specified as static when they are none of:
+ *
+ * - {@link MutablePropertySpec}
+ * - {@link ComputedPropertySpec}
+ * - Any function with a non-zero arity (which are not supported for specifying
+ *   a state object's properties at all)
+ *
+ * Any property so specified will produce a property where:
+ *
+ * - Reading the property will produce the provided static value.
+ *
+ * - Mutating the property will throw a {@link TypeError}, just as it would when
+ *   attempting to mutate a normal `get` accessor (or a
+ *   {@link PropertyDescriptor} with `writable: false`).
+ *
+ * - The property will reflect the same static value on any derived (client)
+ *   state object.
+ */
+export type StaticPropertySpec<T> = Exclude<T, NonStaticValue>;
+/**
+ * Every state property may be specified with any of these types:
+ *
+ * - {@link MutablePropertySpec}
+ * - {@link ComputedPropertySpec}
+ * - {@link StaticPropertySpec}
+ */
+export type StatePropertySpec<T = any> = MutablePropertySpec<T> | ComputedPropertySpec<T> | StaticPropertySpec<T>;
+export declare const isMutablePropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is MutablePropertySpec<T>;
+export declare const isComputedPropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is ComputedPropertySpec<T>;
+export declare const isStaticPropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is Exclude<T, NonStaticValue>;
+export type StateSpec = Record<string, StatePropertySpec>;
+type SpecifiedStatePropertyValue<PropertySpec extends StatePropertySpec> = PropertySpec extends StatePropertySpec<infer T> ? T : never;
+type DerivedMutableKeys<Spec extends StateSpec> = {
+    [K in keyof Spec]: Spec[K] extends MutablePropertySpec<any> ? K : never;
+}[keyof Spec];
+type DerivedMutableState<Spec extends StateSpec> = {
+    -readonly [K in DerivedMutableKeys<Spec>]: SpecifiedStatePropertyValue<Spec[K]>;
+};
+type DerivedReadableKeys<Spec extends StateSpec> = Exclude<keyof Spec, DerivedMutableKeys<Spec>>;
+type DerivedReadableState<Spec extends StateSpec> = {
+    readonly [K in DerivedReadableKeys<Spec>]: SpecifiedStatePropertyValue<Spec[K]>;
+};
+export type SpecifiedState<Spec extends StateSpec> = (DerivedMutableState<Spec> & DerivedReadableState<Spec>) extends infer DerivedState ? {
+    [K in keyof Spec]: K extends keyof DerivedState ? DerivedState[K] : never;
+} : never;
+/**
+ * Produces an (internally) reactive object whose properties may be a mix of:
+ *
+ * - {@link MutablePropertySpec | mutable} (atomically reactive when mutated by
+ *   engine internal logic; reactively propagated as read-only to clients)
+ * - {@link ComputedPropertySpec | computed} (read-only, reactive to changes in
+ *   derived state; reactively propagated as read-only to clients)
+ * - {@link StaticPropertySpec | static} (read-only, immutable after creation;
+ *   statically propagated as read-only to clients)
+ */
+export declare const createSpecifiedState: <Spec extends StateSpec>(spec: Spec) => SpecifiedState<Spec>;
+export {};

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

@@ -0,0 +1,25 @@
+import type { 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;
+type INTERNAL_CLIENT_REPRESENTATION = typeof INTERNAL_CLIENT_REPRESENTATION;
+declare const READONLY_CLIENT_REPRESENTATION: unique symbol;
+type READONLY_CLIENT_REPRESENTATION = typeof READONLY_CLIENT_REPRESENTATION;
+type RepresentationType = ENGINE_REPRESENTATION | INTERNAL_CLIENT_REPRESENTATION | READONLY_CLIENT_REPRESENTATION;
+type TypedRepresentation<Type extends RepresentationType, T> = T & {
+    readonly [K in RepresentationType]?: K extends Type ? K : never;
+};
+export type EngineRepresentation<T extends object> = TypedRepresentation<ENGINE_REPRESENTATION, ShallowMutable<T>>;
+export declare const declareEngineRepresentation: <T extends object>(stateObject: T) => EngineRepresentation<T>;
+export type InternalClientRepresentation<T extends object> = TypedRepresentation<INTERNAL_CLIENT_REPRESENTATION, ShallowMutable<T>>;
+export declare const declareInternalClientRepresentation: <T extends object>(stateObject: T) => InternalClientRepresentation<T>;
+export type ReadonlyClientRepresentation<T> = TypedRepresentation<READONLY_CLIENT_REPRESENTATION, T>;
+/**
+ * Provides a static type mechanism to reduce the chance of mistakenly assigning
+ * one state representation to another (e.g. `engineState = clientState` or
+ * `doSomethingWithCurrentState(engineState)`). Each representation is either
+ * fully or partially assignable to the other, but this bit of indirection should
+ * prevent that (unless one of the types is widened to {@link T}).
+ */
+export declare const declareReadonlyClientRepresentation: <T extends object>(stateObject: Readonly<T>) => ReadonlyClientRepresentation<T>;
+export {};

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

@@ -0,0 +1,23 @@
+import type { Owner } from 'solid-js';
+type ReactiveScopeTask<T> = (scope: ReactiveScope) => T;
+type RunReactiveScopeTask = <T>(task: ReactiveScopeTask<T>) => T;
+export interface ReactiveScope {
+    readonly owner: Owner;
+    readonly dispose: VoidFunction;
+    readonly runTask: RunReactiveScopeTask;
+}
+interface CreateReactiveScopeOptions {
+    readonly owner?: Owner | null;
+}
+/**
+ * Creates a reactive scope for internal engine use. This currently uses Solid's
+ * implementation of reactivity, and makes no attempt to obscure that. As such,
+ * all of the terms and types exposed are intentionally direct references to
+ * their concepts in Solid.
+ *
+ * This reactive scope is suitable for isolating reactivity between tests. It is
+ * also suitable for scoping reactivity for nodes in engine/client state, as
+ * well as creating nested scopes for their descendants.
+ */
+export declare const createReactiveScope: (options?: CreateReactiveScopeOptions) => ReactiveScope;
+export {};

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

@@ -0,0 +1,5 @@
+import { type Accessor } from 'solid-js';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { TextRange } from '../../../instance/text/TextRange.ts';
+import type { ValueNodeDefinition } from '../../../model/ValueNodeDefinition.ts';
+export declare const createFieldHint: (context: EvaluationContext, definition: ValueNodeDefinition) => Accessor<TextRange<'hint'> | null>;

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

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

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

@@ -0,0 +1,19 @@
+import { type Accessor } from 'solid-js';
+import type { TextElementDefinition } from '../../../body/text/TextElementDefinition.ts';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { TextRange, type TextRole } from '../../../instance/text/TextRange.ts';
+interface CreateTextRangeOptions<FallbackValue extends string | null> {
+    readonly fallbackValue?: FallbackValue;
+}
+type ComputedTextRange<Role extends TextRole, Definition extends TextElementDefinition<Role> | null, FallbackValue extends string | null> = Accessor<Definition extends null ? FallbackValue extends null ? TextRange<Role> | null : TextRange<Role> : TextRange<Role>>;
+/**
+ * Creates a text range (e.g. label or hint) from the provided definition,
+ * reactive to:
+ *
+ * - The form's current language (e.g. `<label ref="jr:itext('text-id')" />`)
+ * - Direct `<output>` references within the label's children
+ *
+ * @todo This does not yet handle itext translations **with** outputs!
+ */
+export declare const createTextRange: <Role extends TextRole, Definition extends TextElementDefinition<Role> | null, FallbackValue extends string | null = null>(context: EvaluationContext, role: Role, definition: Definition, options?: CreateTextRangeOptions<FallbackValue> | undefined) => ComputedTextRange<Role, Definition, FallbackValue>;
+export {};

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

@@ -0,0 +1,21 @@
+import type { 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
+ * required for conforming implementations.
+ */
+export type SimpleAtomicStateSetter<T> = (newValue: T) => T;
+/**
+ * A read/write interface to reactive atomic state. This type is intended to be
+ * used as a relaxed version of {@link Signal}, with a
+ * {@link SimpleAtomicStateSetter | simpler setter type}.
+ */
+export type SimpleAtomicState<T> = readonly [
+    get: Accessor<T>,
+    set: SimpleAtomicStateSetter<T>
+];
+export type AtomicStateSetter<T> = Setter<T> | SimpleAtomicStateSetter<T>;
+export type AtomicState<T> = readonly [
+    get: Accessor<T>,
+    set: AtomicStateSetter<T>
+];

package/dist/lib/unique-id.d.ts

@@ -0,0 +1,27 @@
+/**
+ * **WARNING:** Uniqueness is not guaranteed across multiple sessions. Do not
+ * use IDs produced by this function in persistence scenarios, or where external
+ * interfaces expect stronger uniqueness guarantees.
+ */
+export type CreateUniqueId = () => string;
+/**
+ * Where available, uses the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API | Web Crypto API}'s
+ * {@link crypto.randomUUID | `randomUUID`}.
+ *
+ * Notes on supported environments:
+ *
+ * - Browsers: only available in a
+ *   {@link https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts | secure context}
+ * - Node: >= v19.0.0
+ * - Deno: >= 1.11
+ * - Bun: fully supported, unknown minimum version
+ *
+ * Where `randomUUID` is not supported, falls back to an internal implementation
+ * with weaker uniqueness constraints.
+ *
+ * **WARNING:** Uniqueness is not guaranteed across multiple sessions. Do not
+ * use IDs produced by this function in persistence scenarios, or where external
+ * interfaces expect stronger uniqueness guarantees.
+ */
+export declare const createUniqueId: CreateUniqueId;

package/dist/lib/xpath/analysis.d.ts

@@ -0,0 +1,22 @@
+import type { AnySyntaxNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
+export type SingleChildNode = Extract<AnySyntaxNode, {
+    readonly children: readonly [AnySyntaxNode];
+}>;
+export declare const isItextFunctionCalled: (expression: string) => boolean;
+interface GetNodesetDependenciesOptions {
+    readonly contextReference?: string | null;
+    /**
+     * @default false
+     */
+    readonly ignoreContextReference?: boolean;
+    /**
+     * Ignores location path sub-expressions whose full text is `null`. While this
+     * is technically a valid relative name test step, it seems that real forms in
+     * the wild use it as if XPath had an actual `null` token/value.
+     *
+     * @default true
+     */
+    readonly ignoreNullExpressions?: boolean;
+}
+export declare const getNodesetDependencies: (expression: string, options?: GetNodesetDependenciesOptions) => Set<string>;
+export {};