@getodk/xforms-engine 0.1.0

package/src/client/OpaqueReactiveObjectFactory.ts

@@ -0,0 +1,100 @@
+import type { DefineMutableObject } from '../../test/helpers/reactive/internal.ts';
+
+// This type is intended to satisfy two goals, each corresponding to the order
+// of the call signatures within the type:
+//
+// 1. Ensure that **general** compatible interfaces are assignable.
+// 2. Ensure that **specific** call sites correctly infer their return type.
+//
+// It does **not** currently satisfy another goal it was originally intended to
+// address: ensure that attempts to assign a function fail when the function
+// **does not** accept an object. The remnants of this attempt are intentionally
+// left here in case we want to try simplifying and clarifying these types
+// further, in a future effort.
+//
+// It also does **not** currently make a difference to:
+//
+// - specify `in out` as is currently specified
+// - specify distinct `in` and `in out` type parameters
+//
+// These TypeScript keywords are intended to allow greater control over the
+// variance of type parameters in function argument/return type positions. It
+// was thought that they might aid in relaxing assignability for Vue's `reactive`,
+// but that didn't pan out (within the timebox allotted thus far). This, too, is
+// left as a remnant in case we want to revisit this in the future.
+interface BaseOpaqueReactiveObjectFactory<in out Input extends object = object> {
+	<T extends Input>(object: T): T;
+	<T extends object>(object: T): T;
+}
+
+/**
+ * A client-provided reactivity factory. We assume little about the mechanism
+ * of reactivity a client provides (and a client may opt to provide no reactive
+ * mechanism at all, if it will consume state changes by other means). From an
+ * API perspective, the expectation is:
+ *
+ * - The factory accepts a single argument, which **MUST** be an object.
+ *   Reactive primitive values are unsupported by this interface.
+ * - The factory **MUST** return an object of the same shape (i.e. it must
+ *   have the same property key/value pairs).
+ * - The factory's return object **MUST** be mutable by the web-forms engine.
+ * - The web-forms engine **WILL** propagate changes to state as they occur,
+ *   by mutating properties of the object corresponding to those aspects of
+ *   state.
+ * - The client **MAY** read any property of the factory's returned object.
+ * - Because the client's reactivity mechanism (if any) is unknown, it is
+ *   **ASSUMED** that the engine's mutations are observable by the client,
+ *   and that the client has a defined means to subscribe to those mutations.
+ *   It is **IMPLIED** (but **NOT REQUIRED**) that the typical reactive client
+ *   will subscribe to mutations by reading the pertinent properties of the
+ *   reactive object in a reactive context appropriate for that client.
+ * - In common usage, the engine **MAY** convey computed getter property types
+ *   back to the client, to indicate that certain aspects the engine mutates
+ *   are read-only to the client (even if they are mutable by the engine).
+ *
+ * Real world examples of reactive implementations include:
+ *
+ * - {@link https://vuejs.org/api/reactivity-core.html#reactive | `reactive` (Vue)}
+ * - {@link https://docs.solidjs.com/reference/store-utilities/create-mutable | `createMutable` (Solid)}
+ * - {@link DefineMutableObject | our internal `mutable` test helper}
+ *
+ * Each of these implementations are targeted as part of our effort to ensure
+ * the `xforms-engine` is agnostic to a client's framework and/or implementation
+ * of state.
+ *
+ * @example
+ *
+ * ```ts
+ * declare const clientFactory: OpaqueReactiveObjectFactory;
+ *
+ * interface ClientFoo {
+ *   get bar(): string;
+ * }
+ *
+ * interface MutableFoo {
+ *   bar: string;
+ * }
+ *
+ * // State internally updated by engine
+ * let mutableFoo = clientFactory<MutableFoo>({ bar: 'bat' });
+ *
+ * // Same state, consumed by the client as computed but read-only
+ * let clientFoo: ClientFoo = engineFoo;
+ *
+ * // Client: subscribe to mutations by the engine
+ * reactiveContext(() => {
+ *   // Implied client subscription to `clientFoo.bar` on property access
+ *   doSomethingWith(clientFoo.bar);
+ * });
+ *
+ * // Engine: mutate values to convey state changes to subscribed client
+ * engineFoo.bar = 'quux';
+ * ```
+ */
+// prettier-ignore
+export type OpaqueReactiveObjectFactory<Input extends object = object> =
+	// Possibly a TypeScript bug? The order of this intersection matters! Changing
+	// the order causes types in `createClientState.ts` to fail inexplicably.
+	& BaseOpaqueReactiveObjectFactory<Input>
+	& ((object: object) => unknown)
+	;

package/src/client/README.md

@@ -0,0 +1,39 @@
+# @getodk/xforms-engine: Client interface
+
+The modules in this directory define the explicit interface between:
+
+- an ODK Web Forms client (typically, but not necessarily, providing a user interface), henceforth "client"; and,
+- `@getodk/xforms-engine`; henceforth "the engine"
+
+The interface is defined as TypeScript type definitions, with a work-in-progress effort to provide browsable documentation of the same.
+
+## Purpose
+
+The interface is designed to:
+
+- Provide a means for clients to initiate an [ODK XForm](https://getodk.github.io/xforms-spec/)
+- Convey the structure of the form as a tree, _roughly analogous_ in structure to its [primary instance](https://getodk.github.io/xforms-spec/#primary-instance) model
+- Convey definitional aspects of for each of the form's nodes, from which clients may implement particular modes of presentation and user interaction
+- Convey the current state, at any given time, of each node in that tree
+- Provide explicit mechanisms for clients to manipulate pertinent aspects of that state
+- Facilitate propagation of state updates to clients as and where they occur throughout that tree, by means of a client-provided generic state factory[^1]
+- Facilitate loading any of a form's externally referenced resources, by means of a client-provided generic resource accessor[^2]
+
+[^1]: This factory **may be** reactive, and for many clients that is the anticipated usage. But no assumptions are made by the engine about reactivity or any other implementation details beyond the factory's type definition.
+[^2]: This accessor **may** access networked resources, and for many clients that is the anticipated usage. But no assumptions are made by the engine about the provenance of any resources it requests beyond the accessor's type definition.
+
+### Non-goals
+
+The interface is explicitly **not designed** to proscribe any particular mode of presentation or user interaction. Furthermore, it does not specify or mandate:
+
+- Any particular reactive behavior, or implementation of reactivity generally
+- Access to any network or other resource store per se, beyond the means to load and execute the engine itself in a compatible runtime environment
+
+## Notes on interface contract and stability
+
+> [!IMPORTANT]
+> The interface in this directory represents the **complete contract** between a client and the engine. The engine _may_ expose an implementation which exceeds this explicit contract; clients are **strongly discouraged** from depending on details not exposed by the interface itself, as they are considered implementation details subject to change at any time.
+
+The general design and approach to this interface has gone through several iterations. The types defined _within this directory_ are expected to be fairly stable, apart from additive changes to support coming feature work.
+
+Any types referenced _outside this directory_ should be treated as at least moderately unstable; these types are generally concerned with static aspects of a parsed form (typically referenced as a `definition`). We **will** be revisiting and refining these types as early client work proceeds, and are quite likely to introduce more limited client-facing types much like those within this directory to take their place.

package/src/client/RepeatInstanceNode.ts

@@ -0,0 +1,41 @@
+import type { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
+import type { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+
+export interface RepeatInstanceNodeState extends BaseNodeState {
+	// TODO(?): Previous iteration included an `index` getter here. I don't see it
+	// accessed by the current (Solid) client, and I don't know that it really has
+	// any use to a client that wouldn't be satisfied by accessing the same index
+	// while iterating the parent range's children.
+
+	get hint(): null;
+	get children(): readonly GeneralChildNode[];
+	get valueOptions(): null;
+	get value(): null;
+}
+
+// prettier-ignore
+export type RepeatDefinition =
+	| RepeatInstanceDefinition
+	| RepeatTemplateDefinition;
+
+export interface RepeatInstanceNode extends BaseNode {
+	readonly nodeType: 'repeat-instance';
+	readonly definition: RepeatDefinition;
+	readonly root: RootNode;
+
+	/**
+	 * A repeat instance may only be a child of a {@link RepeatRangeNode}.
+	 *
+	 * Note: the web-forms engine's representation of this structure differs from
+	 * the underlying XForms specification's primary instance structure.
+	 *
+	 * @see {@link RepeatRangeNode} for additional detail.
+	 */
+	readonly parent: RepeatRangeNode;
+
+	readonly currentState: RepeatInstanceNodeState;
+}

package/src/client/RepeatRangeNode.ts

@@ -0,0 +1,100 @@
+import type { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+
+export interface RepeatRangeNodeState extends BaseNodeState {
+	get hint(): null;
+	get label(): TextRange<'label'> | null;
+
+	/**
+	 * A repeat range's children may only be {@link RepeatInstanceNode}s.
+	 *
+	 * Note: the web-forms engine's representation of this structure differs from
+	 * the underlying XForms specification's primary instance structure.
+	 *
+	 * @see {@link RepeatRangeNode} for additional detail.
+	 */
+	get children(): readonly RepeatInstanceNode[];
+
+	get valueOptions(): null;
+	get value(): null;
+}
+
+/**
+ * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
+ * (accessed by its
+ * {@link RepeatRangeNodeState.children | `currentState.children`}).
+ *
+ * This structure is modeled as a node, like any other, in the web-forms engine
+ * representation, which notably differs from the corresponding structure in the
+ * underlying ODK XForms specification's primary instance state.
+ *
+ * _Conceptually_, it more closely corresponds to the concept of a set of
+ * repeats as defined by a `<repeat>` element in the XForms body. Whereas its
+ * {@link RepeatInstanceNode} children, if any, correspond directly to the
+ * XForms primary instance's state.
+ *
+ * More precisely, clients should be advised that the presentation aspect of a
+ * `RepeatRangeNode` corresponds to a pair of
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | `<group>` and `<repeat>` body elements}
+ * referencing the same nodeset. (Forms which define a repeat without a
+ * corresponding group are semantically equivalent to those with this
+ * group/repeat pair. The web-forms engine model simplifies this by producing
+ * the same runtime structure for either case.)
+ *
+ * @example
+ *
+ * To illustrate the structural divergence from the underlying XForms concepts,
+ * consider this (abridged) XForm definition:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <rep />
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <repeat nodeset="/data/rep" />
+ * ```
+ *
+ * The engine's representation maps to that structure roughly like:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <!-- RepeatRangeNode(/data/rep).currentState.children: [ -->
+ *       <!-- RepeatInstanceNode(/data/rep[1]): --> <rep />
+ *       <!-- RepeatInstanceNode(/data/rep[2]): --> <rep />
+ *       <!-- ... -->
+ *     <!-- ] -->
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <!-- RepeatRangeNode(/data/rep).definition: { ... -->
+ *   <group ref="/data/rep">
+ *     <repeat nodeset="/data/rep" />
+ *   </group>
+ * <!-- } -->
+ * ```
+ *
+ * Importantly, if the state of a given repeat range has no instances, no aspect
+ * of these repeats will be present in the underlying XForms primary instance
+ * state, but the web-forms engine's representations **retains a reference** to
+ * its {@link RepeatRangeNode}.
+ */
+export interface RepeatRangeNode extends BaseNode {
+	readonly nodeType: 'repeat-range';
+	readonly definition: RepeatSequenceDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: RepeatRangeNodeState;
+
+	addInstances(afterIndex?: number, count?: number): RootNode;
+
+	removeInstances(startIndex: number, count?: number): RootNode;
+}

package/src/client/RootNode.ts

@@ -0,0 +1,36 @@
+import type { RootDefinition } from '../model/RootDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+
+export interface RootNodeState extends BaseNodeState {
+	/**
+	 * This, along with {@link RootNode.languages} is the most significant break
+	   in consistency across node types' state and static properties. Exposing it
+	   across all node types seems like a point of potential confusion, so this
+	   particular divergence seems like the most reasonable compromise.
+	 */
+	get activeLanguage(): ActiveLanguage;
+
+	get label(): null;
+	get hint(): null;
+	get children(): readonly GeneralChildNode[];
+	get valueOptions(): null;
+	get value(): null;
+}
+
+export interface RootNode extends BaseNode {
+	readonly nodeType: 'root';
+	readonly definition: RootDefinition;
+	readonly root: RootNode;
+	readonly parent: null;
+	readonly currentState: RootNodeState;
+
+	/**
+	 * @todo as with {@link RootNodeState.activeLanguage}, this is the most
+	 * significant break in consistency across node types.
+	 */
+	readonly languages: FormLanguages;
+
+	setLanguage(language: FormLanguage): RootNode;
+}

package/src/client/SelectNode.ts

@@ -0,0 +1,69 @@
+import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { StringNode } from './StringNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+
+export interface SelectItem {
+	get value(): string;
+	get label(): TextRange<'label'> | null;
+}
+
+export interface SelectNodeState extends BaseNodeState {
+	get children(): null;
+
+	/**
+	 * @todo should {@link BaseNodeState} include this??
+	 */
+	get valueOptions(): readonly SelectItem[];
+
+	/**
+	 * This value is treated as set-like by the engine, where each
+	 * {@link SelectItem.value | item's `value`} may occur once (at most), and:
+	 *
+	 * - Fields defined with an XForms `<select>` may contain multiple items
+	 * - Fields defined with an XForms `<select1>` will always produce one item
+	 *   (at most)
+	 *
+	 * @todo Maybe it makes more sense for the client interface to break these up!
+	 * Should a `SelectNodeState` have this `value` type, whereas a hypothetical
+	 * `Select1NodeState` would have `get value(): SelectItem | null`?
+	 */
+	get value(): readonly SelectItem[];
+}
+
+export interface SelectDefinition extends ValueNodeDefinition {
+	readonly bodyElement: AnySelectDefinition;
+}
+
+export interface SelectNode extends BaseNode {
+	readonly nodeType: 'select';
+	readonly definition: SelectDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: SelectNodeState;
+
+	/**
+	 * For use by a client to update the selection of a select node where:
+	 *
+	 * - For fields defined with an XForms `<select>`, calling this method is
+	 *   additive, i.e. it will include the item in its
+	 *   {@link SelectNodeState.value}.
+	 * - For fields defined with an XForms `<select1>`, calling this method will
+	 *   replace the selection (if any).
+	 *
+	 * @todo @see {@link StringNode.setValue} re: write restrictions
+	 * @todo @see {@link SelectNodeState.value} re: breaking up the types
+	 */
+	select(item: SelectItem): RootNode;
+
+	/**
+	 * For use by a client to remove an item from the node's
+	 * {@link SelectNodeState.value}.
+	 *
+	 * @todo @see {@link StringNode.setValue} re: write restrictions
+	 */
+	deselect(item: SelectItem): RootNode;
+}

package/src/client/StringNode.ts

@@ -0,0 +1,46 @@
+import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+
+export interface StringNodeState extends BaseNodeState {
+	get children(): null;
+	get valueOptions(): null;
+
+	/**
+	 * Reflects the current value of a {@link StringNode}. This value may be
+	 * populated when a form is loaded, and it may be updated by certain
+	 * computations defined by the form. It may also be updated by a client, using
+	 * the {@link StringNode.setValue} method.
+	 */
+	get value(): string;
+}
+
+export interface StringDefinition extends ValueNodeDefinition {
+	readonly bodyElement: InputDefinition | null;
+}
+
+/**
+ * A node which can be assigned a string/text value. A string node **MAY**
+ * correspond to form field defined as an XForms `<input>`, which a user-facing
+ * client would likely present for a user to fill. It may not correspond to an
+ * `<input>`, or necessarily have any presentational implications for a client
+ * (for instance if the node is bound to an XForms `calculate` expression).
+ */
+export interface StringNode extends BaseNode {
+	readonly nodeType: 'string';
+	readonly definition: StringDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: StringNodeState;
+
+	/**
+	 * For use by a client to update the value of a string node.
+	 *
+	 * @todo [how] should we express write restrictions to a client? E.g. what
+	 * happens when a string node is readonly, and a client attempts to call this
+	 * method?
+	 */
+	setValue(value: string): RootNode;
+}

package/src/client/SubtreeNode.ts

@@ -0,0 +1,57 @@
+import type { SubtreeDefinition as BaseSubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+
+export interface SubtreeNodeState extends BaseNodeState {
+	get label(): null;
+	get hint(): null;
+	get children(): readonly GeneralChildNode[];
+	get valueOptions(): null;
+	get value(): null;
+}
+
+// TODO: obviously there is a naming inconsistency emerging here.
+export interface SubtreeDefinition extends BaseSubtreeDefinition {
+	readonly bodyElement: null;
+}
+
+/**
+ * A non-root node which has children, but **no** corresponding XForms
+ * `<group>`. A subtree node does not have any direct implications for
+ * presentation to users, but its descendants may specify presentational details
+ * in their own {@link BaseNode.definition | definition}s.
+ *
+ * @example
+ *
+ * A common `SubtreeNode` case will be a form's `<meta>` element:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <some-group>
+ *       <some-field />
+ *     </some-group>
+ *     <!-- Note that `meta` does not have a corresponding group body element -->
+ *     <!-- SubtreeNode(/data/meta): { ... -->
+ *     <meta>
+ *       <instanceID/>
+ *     </meta>
+ *     <!-- } -->
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <group ref="/data/some-group">
+ *   <input ref="/data/some-group/some-field" />
+ * </group>
+ * ```
+ */
+// TODO: directly test presentation of non-group subtree children/descendants
+export interface SubtreeNode extends BaseNode {
+	readonly nodeType: 'subtree';
+	readonly definition: SubtreeDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: SubtreeNodeState;
+}

package/src/client/TextRange.ts

@@ -0,0 +1,63 @@
+import type { ActiveLanguage } from './FormLanguage.ts';
+import type { RootNodeState } from './RootNode.ts';
+
+export type TextChunkSource = 'itext' | 'output' | 'static';
+
+/**
+ * @todo This (and everything else to do with {@link TextRange}s is for
+ * illustration purposes, as a starting point where any particular detail is of
+ * unknown utility. We can iterate on all aspects of text ranges in actual
+ * clients and refine from there.
+ *
+ * @see {@link TextRange}
+ */
+export interface TextChunk {
+	readonly source: TextChunkSource;
+
+	/**
+	 * @see {@link ActiveLanguage} for additional commentary
+	 */
+	get language(): ActiveLanguage;
+
+	get asString(): string;
+	get formatted(): unknown;
+}
+
+/**
+ * Represents aspects of a form which produce text, which _might_ be:
+ *
+ * - Computed from multiple sources
+ * - Capable of conveying certain formatting (which may be presentational and/or
+ *   structural)
+ *
+ * Computed text values may be updated by:
+ *
+ * - Changing a {@link RootNodeState.activeLanguage | form's active language}
+ * - Changes to any state referenced by an
+ *   {@link https://getodk.github.io/xforms-spec/#body-elements | output},
+ *   within any text-presenting aspect of a form (e.g. labels and hints, as well
+ *   as itext translations referenced by those)
+ *
+ * As a client interface, the intent is to convey that this text may be dynamic
+ * (and thus potentially reactive for clients supplying a
+ * {@link OpaqueReactiveObjectFactory}), and may produce multiple spans of text
+ * (or none at all) depending on the structure and state of the form.
+ *
+ * @todo This interface should be considered **incomplete and in flux**, and
+ * subject to change as we evaluate client needs and engine responsibilities. In
+ * particular, we've deferred a notion of an interface for formatting aspects,
+ * while leaving open the possibility that it may come in future iterations.
+ *
+ * {@link role} is intended to convey that individual text ranges may be
+ * reasoned about differently by clients depending on their role (for instance,
+ * a text range's role may correspond to the "short" or "guidance" `form` of a
+ * {@link https://getodk.github.io/xforms-spec/#languages | translation}).
+ */
+export interface TextRange<Role extends string | null = null> {
+	readonly role: Role;
+
+	[Symbol.iterator](): Iterable<TextChunk>;
+
+	get asString(): string;
+	get formatted(): unknown;
+}

package/src/client/hierarchy.ts

@@ -0,0 +1,63 @@
+import type { ExpandUnion } from '@getodk/common/types/helpers.d.ts';
+import type { GroupNode } from './GroupNode.ts';
+import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { SelectNode } from './SelectNode.ts';
+import type { StringNode } from './StringNode.ts';
+import type { SubtreeNode } from './SubtreeNode.ts';
+
+// prettier-ignore
+export type AnyLeafNode =
+	| SelectNode
+	| StringNode;
+
+/**
+ * Any of the concrete node types which may be a parent of any other node.
+ *
+ * This is an intermediate type, which shouldn't be referenced by other concrete
+ * node types directly. Instead:
+ *
+ * - Repeat instances should (continue to) specify {@link RepeatRangeNode}.
+ * - All other child nodes should specify {@link GeneralParentNode}.
+ */
+export type AnyParentNode =
+	| RootNode // eslint-disable-line @typescript-eslint/sort-type-constituents
+	| SubtreeNode
+	| GroupNode
+	| RepeatRangeNode
+	| RepeatInstanceNode;
+
+/**
+ * Any of the concrete node types a client may get from the engine's form
+ * representation. This union should be updated when any new concrete node type
+ * is added (or when any of the current members is changed/removed).
+ *
+ * @see {@link GeneralParentNode}, which is derived from this type
+ * @see {@link GeneralChildNode}, which is derived from this type
+ */
+export type AnyNode = ExpandUnion<AnyLeafNode | AnyParentNode>;
+
+/**
+ * Any of the concrete node types which may be a parent of non-repeat instance
+ * child nodes.
+ */
+export type GeneralParentNode = Exclude<AnyParentNode, RepeatRangeNode>;
+
+/**
+ * Any of the concrete node types which may be a child of any other node.
+ *
+ * This is an intermediate type, which shouldn't be referenced by other concrete
+ * node types directly. Instead:
+ *
+ * - Repeat ranges should (continue to) specify {@link RepeatInstanceNode}.
+ * - All other parent nodes should specify {@link GeneralChildNode}.
+ */
+// prettier-ignore
+export type AnyChildNode = Exclude<AnyNode, RootNode>;
+
+/**
+ * Any of the concrete node types which may be a child of non-repeat range
+ * parent nodes.
+ */
+export type GeneralChildNode = Exclude<AnyChildNode, RepeatInstanceNode>;

package/src/client/index.ts

@@ -0,0 +1,29 @@
+import type { EngineConfig } from './EngineConfig.ts';
+import type { RootNode } from './RootNode.ts';
+
+export type FormResource = Blob | URL | string;
+
+export interface InitializeFormOptions {
+	readonly config: EngineConfig;
+
+	// E.g. opening a submitted form instance for edit. TDOO: the `FormResource`
+	// name is shared here for both init input and initial state, but the shape of
+	// those resources would differ. Probably a more generic name is appropriate.
+	readonly initialState?: FormResource;
+}
+
+/**
+ * Creates an instance of a form to be filled (or edited) by a client.
+ */
+// TODO: initialization is represented as asynchronous here, so that any
+// requisite resources can be retrieved before passing control to a client. This
+// is an obvious first step, but we can consider a more complex (if optional)
+// flow, e.g.:
+//
+// - Where it can be determined upfront that the form has no need to perform IO
+// - Where the IO may have already been performed (e.g. offline, other potential
+//   caching cases where appropriate)
+export type InitializeForm = (
+	input: FormResource,
+	options?: InitializeFormOptions
+) => Promise<RootNode>;

package/src/client/node-types.ts

@@ -0,0 +1,10 @@
+// prettier-ignore
+export type InstanceNodeType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'root'
+	| 'repeat-range'
+	| 'repeat-instance'
+	| 'group'
+	| 'subtree'
+	| 'select'
+	| 'string';