@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/lib/reactivity/createInstanceValueState.ts

@@ -0,0 +1,166 @@
+import type { Signal } from 'solid-js';
+import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } 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;
+}
+
+const getInitialValue = (
+	context: InstanceValueContext,
+	options: InstanceValueStateOptions
+): string => {
+	const { initialValueSource = 'FORM_DEFAULT' } = options;
+
+	if (initialValueSource === 'FORM_DEFAULT') {
+		const { defaultValue } = context.definition;
+
+		return context.decodeInstanceValue(defaultValue);
+	}
+
+	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+};
+
+type BaseValueState = Signal<string>;
+
+type RelevantValueState = SimpleAtomicState<string>;
+
+/**
+ * Wraps {@link baseValueState} in a signal-like interface which:
+ *
+ * - produces a blank value for nodes ({@link context}) in a non-relevant state
+ * - persists, and restores, the most recent non-blank value state when a
+ *   node/context's relevance is restored
+ */
+const createRelevantValueState = (
+	context: InstanceValueContext,
+	baseValueState: BaseValueState
+): RelevantValueState => {
+	return context.scope.runTask(() => {
+		const [getRelevantValue, setValue] = baseValueState;
+
+		const getValue = createMemo(() => {
+			if (context.isRelevant()) {
+				return getRelevantValue();
+			}
+
+			return '';
+		});
+
+		return [getValue, setValue];
+	});
+};
+
+/**
+ * For fields with a `readonly` bind expression, prevent downstream
+ * (client/user) writes when the field is in a `readonly` state.
+ */
+const guardDownstreamReadonlyWrites = (
+	context: InstanceValueContext,
+	baseState: SimpleAtomicState<string>
+): SimpleAtomicState<string> => {
+	const { readonly } = context.definition.bind;
+
+	if (readonly.isDefaultExpression) {
+		return baseState;
+	}
+
+	const [getValue, baseSetValue] = baseState;
+
+	const setValue: SimpleAtomicStateSetter<string> = (value) => {
+		if (context.isReadonly()) {
+			const reference = untrack(() => context.contextReference());
+
+			throw new Error(`Cannot write to readonly field: ${reference}`);
+		}
+
+		return baseSetValue(value);
+	};
+
+	return [getValue, setValue];
+};
+
+/**
+ * Defines a reactive effect which writes the result of `calculate` bind
+ * computations to the provided value setter, on initialization and any
+ * subsequent reactive update.
+ */
+const createCalculation = (
+	context: InstanceValueContext,
+	setRelevantValue: SimpleAtomicStateSetter<string>,
+	calculateDefinition: BindComputationExpression<'calculate'>
+): void => {
+	context.scope.runTask(() => {
+		const calculate = createComputedExpression(context, calculateDefinition, {
+			defaultValue: '',
+		});
+
+		createComputed(() => {
+			if (context.isAttached() && context.isRelevant()) {
+				const calculated = calculate();
+				const value = context.decodeInstanceValue(calculated);
+
+				setRelevantValue(value);
+			}
+		});
+	});
+};
+
+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 const createInstanceValueState = (
+	context: InstanceValueContext,
+	options: InstanceValueStateOptions = {}
+): InstanceValueState => {
+	return context.scope.runTask(() => {
+		const initialValue = getInitialValue(context, options);
+		const baseValueState = createSignal(initialValue);
+		const relevantValueState = createRelevantValueState(context, baseValueState);
+		const { calculate } = context.definition.bind;
+
+		if (calculate != null) {
+			const [, setValue] = relevantValueState;
+
+			createCalculation(context, setValue, calculate);
+		}
+
+		return guardDownstreamReadonlyWrites(context, relevantValueState);
+	});
+};

package/src/lib/reactivity/createNoteReadonlyThunk.ts

@@ -1,31 +1,36 @@
 import type { Accessor } from 'solid-js';
 import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
+import { resolveDependencyNodesets } from '../../parse/xpath/dependency-analysis.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 
 export const createNoteReadonlyThunk = (
 	context: EvaluationContext,
-	readonlyDefinition: BindComputation<'readonly'>
+	definition: NoteNodeDefinition
 ): Accessor<true> => {
-	if (!readonlyDefinition.isConstantTruthyExpression()) {
+	const { reference } = definition.bodyElement;
+	const { readonly } = definition.bind;
+
+	if (!readonly.isConstantTruthyExpression()) {
 		throw new Error('Expected a static readonly expression');
 	}
 
 	let result = true;
 
 	if (import.meta.env.DEV) {
-		const { expression } = readonlyDefinition;
+		const { expression } = readonly;
+		const dependencyReferences = resolveDependencyNodesets(reference, expression);
 
-		if (readonlyDefinition.dependencyReferences.size > 0) {
+		if (dependencyReferences.length > 0) {
 			throw new Error(`Expected expression ${expression} to have no dependencies`);
 		}
 
-		const computedExpression = createComputedExpression(context, readonlyDefinition);
+		const computedExpression = createComputedExpression(context, readonly);
 
 		result = computedExpression();
 
 		if (result !== true) {
-			throw new Error(`Expected expression ${readonlyDefinition.expression} to return true`);
+			throw new Error(`Expected expression ${readonly.expression} to return true`);
 		}
 	}
 

package/src/lib/reactivity/createSelectItems.ts

@@ -1,27 +1,25 @@
 import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
-import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
 import type { TextRange as ClientTextRange } from '../../client/TextRange.ts';
-import type { SelectItem } from '../../index.ts';
+import type { ActiveLanguage, SelectItem } from '../../index.ts';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { TranslationContext } from '../../instance/internal-api/TranslationContext.ts';
 import type { SelectField } from '../../instance/SelectField.ts';
-import type {
-	EvaluationContext,
-	EvaluationContextRoot,
-} from '../../instance/internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
 import { TextChunk } from '../../instance/text/TextChunk.ts';
 import { TextRange } from '../../instance/text/TextRange.ts';
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { ItemDefinition } from '../../parse/body/control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../parse/body/control/select/ItemsetDefinition.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { ReactiveScope } from './scope.ts';
 import { createTextRange } from './text/createTextRange.ts';
 
 type DerivedItemLabel = ClientTextRange<'item-label', 'form-derived'>;
 
-const derivedItemLabel = (context: EvaluationContext, value: string): DerivedItemLabel => {
-	const chunk = new TextChunk(context.root, 'static', value);
+const derivedItemLabel = (context: TranslationContext, value: string): DerivedItemLabel => {
+	const chunk = new TextChunk(context, 'literal', value);
 
 	return new TextRange('form-derived', 'item-label', [chunk]);
 };
@@ -61,23 +59,21 @@ const createTranslatedStaticSelectItems = (
 };
 
 class ItemsetItemEvaluationContext implements EvaluationContext {
+	readonly isAttached: Accessor<boolean>;
 	readonly scope: ReactiveScope;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly root: EvaluationContextRoot;
+	readonly evaluator: EngineXPathEvaluator;
 	readonly contextReference: Accessor<string>;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 
 	constructor(
-		private readonly selectField: SelectField,
-		readonly contextNode: Node
+		selectField: SelectField,
+		readonly contextNode: EngineXPathNode
 	) {
+		this.isAttached = selectField.isAttached;
 		this.scope = selectField.scope;
 		this.evaluator = selectField.evaluator;
-		this.root = selectField.root;
 		this.contextReference = selectField.contextReference;
-	}
-
-	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[] {
-		return this.selectField.getSubscribableDependenciesByReference(reference);
+		this.getActiveLanguage = selectField.getActiveLanguage;
 	}
 }
 
@@ -107,14 +103,18 @@ const createItemsetItems = (
 	itemset: ItemsetDefinition
 ): Accessor<readonly ItemsetItem[]> => {
 	return selectField.scope.runTask(() => {
-		const itemNodes = createComputedExpression(selectField, itemset.nodes);
-		const itemsCache = new UpsertableMap<Node, ItemsetItem>();
+		const itemNodes = createComputedExpression(selectField, itemset.nodes, {
+			defaultValue: [],
+		});
+		const itemsCache = new UpsertableMap<EngineXPathNode, ItemsetItem>();
 
 		return createMemo(() => {
 			return itemNodes().map((itemNode) => {
 				return itemsCache.upsert(itemNode, () => {
 					const context = new ItemsetItemEvaluationContext(selectField, itemNode);
-					const value = createComputedExpression(context, itemset.value);
+					const value = createComputedExpression(context, itemset.value, {
+						defaultValue: '',
+					});
 					const label = createSelectItemsetItemLabel(context, itemset, value);
 
 					return {

package/src/lib/reactivity/createTranslationState.ts

@@ -0,0 +1,61 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createComputed, createSignal } from 'solid-js';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from '../../client/FormLanguage.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { ReactiveScope } from './scope.ts';
+import type { 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 const createTranslationState = (
+	scope: ReactiveScope,
+	evaluator: EngineXPathEvaluator
+): TranslationState => {
+	const activeLanguageName = evaluator.getActiveLanguage();
+	const languageNames = evaluator.getLanguages();
+
+	let defaultLanguage: ActiveLanguage;
+	let languages: FormLanguages;
+
+	if (activeLanguageName == null) {
+		defaultLanguage = { isSyntheticDefault: true, language: '' };
+		languages = [defaultLanguage];
+	} else {
+		const inactiveLanguages = languageNames
+			.filter((languageName) => languageName !== activeLanguageName)
+			.map((language) => ({ language }));
+
+		defaultLanguage = { language: activeLanguageName };
+		languages = [defaultLanguage, ...inactiveLanguages];
+	}
+
+	const [getActiveLanguage, baseSetActiveLanguage] = createSignal(defaultLanguage);
+
+	const setActiveLanguage: SimpleAtomicStateSetter<FormLanguage> = (value) => {
+		return baseSetActiveLanguage(value);
+	};
+
+	scope.runTask(() => {
+		createComputed(() => {
+			evaluator.setActiveLanguage(getActiveLanguage().language);
+		});
+	});
+
+	return {
+		languages,
+		getActiveLanguage,
+		setActiveLanguage,
+	};
+};

package/src/lib/reactivity/createValueState.ts

@@ -1,8 +1,7 @@
-import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import type { DependentExpression } from '../../expression/DependentExpression.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+import { createComputed, createMemo, createSignal, untrack, type Signal } from 'solid-js';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { ValueContext } from '../../instance/internal-api/ValueContext.ts';
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
 
@@ -19,8 +18,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.
 	 *
@@ -33,110 +31,54 @@ export interface ValueStateOptions {
 	readonly initialValueSource?: InitialValueSource;
 }
 
-interface PersistedValueState {
-	readonly isRelevant: boolean;
-	readonly value: string;
-}
-
-type PrimaryInstanceValueState = SimpleAtomicState<string>;
-
-type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
-
-/**
- * Creates a signal which:
- *
- * 1. Persists its state to the primary instance's
- *    {@link ValueContext.contextNode | contextNode} on state changes.
- * 2. Propagates downstream reactivity only after that write is persisted.
- *
- * This ensures that reactive subscriptions get a consistent view of a node's
- * current state, regardless of whether they derive state from values in the
- * primary instance (currently: computed {@link DependentExpression}
- * evaluations) or from other aspects of reactive runtime state (generally,
- * everything besides computed {@link DependentExpression}s).
- */
-const createPrimaryInstanceValueState = <RuntimeValue>(
+const getInitialValue = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	options: ValueStateOptions
-): PrimaryInstanceValueState => {
-	const { contextNode, definition, scope } = context;
-	const { initialValueSource } = options;
-	const { defaultValue } = definition;
+): string => {
+	const { initialValueSource = 'FORM_DEFAULT' } = options;
 
-	return scope.runTask(() => {
-		// prettier-ignore
-		const initialValue =
-			initialValueSource === 'PRIMARY_INSTANCE'
-				? contextNode.textContent ?? defaultValue
-				: defaultValue;
+	if (initialValueSource === 'FORM_DEFAULT') {
+		return context.definition.defaultValue;
+	}
 
-		const persistedValueState = createSignal<PersistedValueState>(
-			{
-				isRelevant: context.isRelevant(),
-				value: initialValue,
-			},
-			{
-				// This could return a single boolean expression, but checking each
-				// equality condition separately feels like it more clearly expresses
-				// the intent.
-				equals: (previous, updated) => {
-					if (updated.isRelevant !== previous.isRelevant) {
-						return false;
-					}
+	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+};
 
-					return updated.value === previous.value;
-				},
-			}
-		);
-		const [persistedValue, setValueForPersistence] = persistedValueState;
+type BaseValueState = Signal<string>;
 
-		createComputed(() => {
-			const isRelevant = context.isRelevant();
+type RelevantValueState = SimpleAtomicState<string>;
 
-			setValueForPersistence((persisted) => {
-				return {
-					isRelevant,
-					value: persisted.value,
-				};
-			});
-		});
+/**
+ * Wraps {@link baseValueState} in a signal-like interface which:
+ *
+ * - produces a blank value for nodes ({@link context}) in a non-relevant state
+ * - persists, and restores, the most recent non-blank value state when a
+ *   node/context's relevance is restored
+ */
+const createRelevantValueState = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	baseValueState: BaseValueState
+): RelevantValueState => {
+	return context.scope.runTask(() => {
+		const [getRelevantValue, setValue] = baseValueState;
 
-		const toSignalValue = (current: PersistedValueState): string => {
-			if (current.isRelevant) {
-				return current.value;
+		const getValue = createMemo(() => {
+			if (context.isRelevant()) {
+				return getRelevantValue();
 			}
 
 			return '';
-		};
-
-		const [signalValue, setSignalValue] = createSignal(toSignalValue(persistedValue()));
-
-		createComputed(() => {
-			const { isRelevant, value } = persistedValue();
-			const preparedTextContent = isRelevant ? value : '';
-			const assignedTextContent = (contextNode.textContent = preparedTextContent);
-
-			setSignalValue(assignedTextContent);
 		});
 
-		const setPrimaryInstanceValue: SimpleAtomicStateSetter<string> = (value) => {
-			// TODO: Check (error?) for non-relevant value change?
-			const persisted = setValueForPersistence({
-				isRelevant: context.isRelevant(),
-				value,
-			});
-
-			return persisted.value;
-		};
-
-		return [signalValue, setPrimaryInstanceValue];
+		return [getValue, setValue];
 	});
 };
 
+type RuntimeValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
+
 /**
- * Wraps a node's {@link PrimaryInstanceValueState} in a signal-like interface
- * which automatically encodes and decodes a node's runtime value
- * representation:
+ * Wraps {@link relevantValueState} in a signal-like interface which
+ * automatically encodes and decodes a node's runtime value representation:
  *
  * - Values read by a node will be read from the current state as persisted in
  *   the primary instance, then {@link ValueContext.decodeValue | decoded} (as
@@ -144,21 +86,17 @@ const createPrimaryInstanceValueState = <RuntimeValue>(
  *   functionality provided by that node.
  *
  * - Values written by a node will be {@link ValueContext.encodeValue | encoded}
- *   (also as implemented by that node) into a string appropriate to persist to
- *   the primary instance, and written to it as such.
- *
- * - Downstream reactive computations should subscribe to updates to this
- *   runtime state (suggesting the value node itself should access this state in
- *   its {@link SubscribableDependency.subscribe} implementation).
+ *   (also as implemented by that node) into a string value appropriate for
+ *   serialization in an instance submission.
  */
 const createRuntimeValueState = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
-	primaryInstanceState: PrimaryInstanceValueState
-): ValueState<RuntimeValue> => {
+	relevantValueState: RelevantValueState
+): RuntimeValueState<RuntimeValue> => {
 	const { decodeValue, encodeValue } = context;
 
 	return context.scope.runTask(() => {
-		const [primaryInstanceValue, setPrimaryInstanceValue] = primaryInstanceState;
+		const [primaryInstanceValue, setPrimaryInstanceValue] = relevantValueState;
 		const getRuntimeValue = createMemo(() => {
 			return decodeValue(primaryInstanceValue());
 		});
@@ -209,13 +147,15 @@ const guardDownstreamReadonlyWrites = <RuntimeValue>(
 const createCalculation = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	setValue: SimpleAtomicStateSetter<RuntimeValue>,
-	calculateDefinition: BindComputation<'calculate'>
+	calculateDefinition: BindComputationExpression<'calculate'>
 ): void => {
 	context.scope.runTask(() => {
-		const calculate = createComputedExpression(context, calculateDefinition);
+		const calculate = createComputedExpression(context, calculateDefinition, {
+			defaultValue: '',
+		});
 
 		createComputed(() => {
-			if (context.isRelevant()) {
+			if (context.isAttached() && context.isRelevant()) {
 				const calculated = calculate();
 				const value = context.decodeValue(calculated);
 
@@ -225,34 +165,36 @@ const createCalculation = <RuntimeValue>(
 	});
 };
 
+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 const createValueState = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	options: ValueStateOptions = {}
 ): ValueState<RuntimeValue> => {
-	const primaryInstanceState = createPrimaryInstanceValueState(context, options);
-	const runtimeState = createRuntimeValueState(context, primaryInstanceState);
-
-	const { calculate } = context.definition.bind;
+	return context.scope.runTask(() => {
+		const initialValue = getInitialValue(context, options);
+		const baseValueState = createSignal(initialValue);
+		const valueState = createRelevantValueState(context, baseValueState);
+		const runtimeState = createRuntimeValueState(context, valueState);
+		const { calculate } = context.definition.bind;
 
-	if (calculate != null) {
-		const [, setValue] = runtimeState;
+		if (calculate != null) {
+			const [, setValue] = runtimeState;
 
-		createCalculation(context, setValue, calculate);
-	}
+			createCalculation(context, setValue, calculate);
+		}
 
-	return guardDownstreamReadonlyWrites(context, runtimeState);
+		return guardDownstreamReadonlyWrites(context, runtimeState);
+	});
 };

package/src/lib/reactivity/materializeCurrentStateChildren.ts

@@ -1,13 +1,13 @@
+import type { FormNodeID } from '../../client/identity.ts';
 import type { AnyChildNode } from '../../instance/hierarchy.ts';
-import type { NodeID } from '../../instance/identity.ts';
 import type { ChildrenState, createChildrenState } from './createChildrenState.ts';
 import type { ClientState } from './node-state/createClientState.ts';
 import type { CurrentState } from './node-state/createCurrentState.ts';
 import type { ReactiveScope } from './scope.ts';
 
 interface InconsistentChildrenStateDetails {
-	readonly missingIds: readonly NodeID[];
-	readonly unexpectedIds: readonly NodeID[];
+	readonly missingIds: readonly FormNodeID[];
+	readonly unexpectedIds: readonly FormNodeID[];
 }
 
 class InconsistentChildrenStateError extends Error {
@@ -37,7 +37,7 @@ class InconsistentChildrenStateError extends Error {
 }
 
 export interface EncodedParentState {
-	readonly children: readonly NodeID[];
+	readonly children: readonly FormNodeID[];
 }
 
 /**
@@ -58,7 +58,7 @@ export interface EncodedParentState {
  * @todo should we throw rather than warn until we have this confidence?
  */
 const reportInconsistentChildrenState = (
-	expectedClientIds: readonly NodeID[],
+	expectedClientIds: readonly FormNodeID[],
 	actualNodes: readonly AnyChildNode[]
 ): void => {
 	const actualIds = actualNodes.map((node) => node.nodeId);
@@ -88,8 +88,8 @@ export type MaterializedChildren<
 /**
  * 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.
  */