From b0ec3d4375985db79f50a942e1dfb8693bd3060e Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Mon, 27 May 2024 11:35:51 -0700
Subject: [PATCH] Initial support for appearances (and body classes)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Automated testing is pending. Some manual validation has been done to verify that this likely works as intended. The intent is to make this first pass available for client iteration as quickly as possible.

While it’s possible to include unit tests for `TokenListParser`, it seems more likely we’ll want to add integration tests in the `scenario` package. Given there’s a ton of unaddressed feedback in #110, it seems most prudent to get this into draft first, and bring in integration tests once that  lands.
---
 .../types/string/PartiallyKnownString.ts      |  27 +++
 .../xforms-engine/src/body/BodyDefinition.ts  |  34 +++-
 .../src/body/RepeatElementDefinition.ts       |   4 +
 .../body/appearance/inputAppearanceParser.ts  |  39 +++++
 .../body/appearance/selectAppearanceParser.ts |  38 +++++
 .../structureElementAppearanceParser.ts       |   7 +
 .../src/body/control/ControlDefinition.ts     |   4 +
 .../src/body/control/InputDefinition.ts       |  13 ++
 .../body/control/select/SelectDefinition.ts   |  19 ++-
 .../src/body/group/BaseGroupDefinition.ts     |   4 +
 .../src/body/text/TextElementDefinition.ts    |   6 +-
 packages/xforms-engine/src/client/BaseNode.ts |  10 +-
 .../xforms-engine/src/client/GroupNode.ts     |   4 +
 .../src/client/NodeAppearances.ts             |  22 +++
 .../src/client/RepeatInstanceNode.ts          |   4 +
 .../src/client/RepeatRangeNode.ts             |   4 +
 packages/xforms-engine/src/client/RootNode.ts |  22 +++
 .../xforms-engine/src/client/SelectNode.ts    |   4 +
 .../xforms-engine/src/client/StringNode.ts    |   4 +
 .../xforms-engine/src/client/SubtreeNode.ts   |   1 +
 packages/xforms-engine/src/instance/Group.ts  |   8 +-
 .../src/instance/RepeatInstance.ts            |  13 +-
 .../xforms-engine/src/instance/RepeatRange.ts |  39 ++++-
 packages/xforms-engine/src/instance/Root.ts   |   6 +-
 .../xforms-engine/src/instance/SelectField.ts |   5 +-
 .../xforms-engine/src/instance/StringField.ts |   6 +-
 .../xforms-engine/src/instance/Subtree.ts     |   2 +-
 .../src/instance/abstract/InstanceNode.ts     |   3 +
 .../xforms-engine/src/instance/children.ts    |  22 ++-
 .../xforms-engine/src/lib/TokenListParser.ts  | 156 ++++++++++++++++++
 .../src/model/ModelDefinition.ts              |   2 +-
 .../xforms-engine/src/model/RootDefinition.ts |   4 +-
 .../src/model/ValueNodeDefinition.ts          |   5 +-
 33 files changed, 507 insertions(+), 34 deletions(-)
 create mode 100644 packages/common/types/string/PartiallyKnownString.ts
 create mode 100644 packages/xforms-engine/src/body/appearance/inputAppearanceParser.ts
 create mode 100644 packages/xforms-engine/src/body/appearance/selectAppearanceParser.ts
 create mode 100644 packages/xforms-engine/src/body/appearance/structureElementAppearanceParser.ts
 create mode 100644 packages/xforms-engine/src/client/NodeAppearances.ts
 create mode 100644 packages/xforms-engine/src/lib/TokenListParser.ts

diff --git a/packages/common/types/string/PartiallyKnownString.ts b/packages/common/types/string/PartiallyKnownString.ts
new file mode 100644
index 00000000..25b0019d
--- /dev/null
+++ b/packages/common/types/string/PartiallyKnownString.ts
@@ -0,0 +1,27 @@
+/**
+ * Produces a `string` type while preserving autocomplete/autosuggest
+ * functionality for a known string (union).
+ *
+ * @see {@link https://www.totaltypescript.com/tips/create-autocomplete-helper-which-allows-for-arbitrary-values}
+ *
+ * @example
+ * ```ts
+ * let foo: PartiallyKnownString<'a' | 'b' | 'zed'>;
+ *
+ * // Each of these will be suggested by a TypeScript-supporting editor:
+ * foo = 'a';
+ * foo = 'b';
+ * foo = 'zed';
+ *
+ * // ... but any string is valid:
+ * foo = 'lmnop';
+ * ```
+ */
+// prettier-ignore
+export type PartiallyKnownString<Known extends string> =
+	[string] extends [Known]
+		? string
+		: (
+				| Known
+				| (string & { /* Type hack! */ })
+			);
diff --git a/packages/xforms-engine/src/body/BodyDefinition.ts b/packages/xforms-engine/src/body/BodyDefinition.ts
index a5136a77..8ebd272f 100644
--- a/packages/xforms-engine/src/body/BodyDefinition.ts
+++ b/packages/xforms-engine/src/body/BodyDefinition.ts
@@ -1,5 +1,7 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
 import { DependencyContext } from '../expression/DependencyContext.ts';
+import type { ParsedTokenList } from '../lib/TokenListParser.ts';
+import { TokenListParser } from '../lib/TokenListParser.ts';
 import { RepeatElementDefinition } from './RepeatElementDefinition.ts';
 import { UnsupportedBodyElementDefinition } from './UnsupportedBodyElementDefinition.ts';
 import { ControlDefinition } from './control/ControlDefinition.ts';
@@ -15,14 +17,18 @@ export interface BodyElementParentContext {
 	readonly element: Element;
 }
 
+// prettier-ignore
+export type ControlElementDefinition =
+	| AnySelectDefinition
+	| InputDefinition;
+
 type SupportedBodyElementDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RepeatElementDefinition
 	| LogicalGroupDefinition
 	| PresentationGroupDefinition
 	| StructuralGroupDefinition
-	| InputDefinition
-	| AnySelectDefinition;
+	| ControlElementDefinition;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type BodyElementDefinitionConstructor = new (...args: any[]) => SupportedBodyElementDefinition;
@@ -135,6 +141,10 @@ class BodyElementMap extends Map<BodyElementReference, AnyBodyElementDefinition>
 	}
 }
 
+const bodyClassParser = new TokenListParser(['pages' /*, 'theme-grid' */]);
+
+export type BodyClassList = ParsedTokenList<typeof bodyClassParser>;
+
 export class BodyDefinition extends DependencyContext {
 	static getChildElementDefinitions(
 		form: XFormDefinition,
@@ -156,6 +166,25 @@ export class BodyDefinition extends DependencyContext {
 	}
 
 	readonly element: Element;
+
+	/**
+	 * @todo this class is already an oddity in that it's **like** an element
+	 * definition, but it isn't one itself. Adding this property here emphasizes
+	 * that awkwardness. It also extends the applicable scope where instances of
+	 * this class are accessed. While it's still ephemeral, it's anticipated that
+	 * this extension might cause some disomfort. If so, the most plausible
+	 * alternative is an additional refactor to:
+	 *
+	 * 1. Introduce a `BodyElementDefinition` sublass for `<h:body>`.
+	 * 2. Disambiguate the respective names of those, in some reasonable way.
+	 * 3. Add a layer of indirection between this class and that new body element
+	 *    definition's class.
+	 * 4. At that point, we may as well prioritize the little bit of grunt work to
+	 *    pass the `BodyDefinition` instance by reference rather than assigning it
+	 *    to anything.
+	 */
+	readonly classes: BodyClassList;
+
 	readonly elements: readonly AnyBodyElementDefinition[];
 
 	protected readonly elementsByReference: BodyElementMap;
@@ -171,6 +200,7 @@ export class BodyDefinition extends DependencyContext {
 
 		this.reference = form.rootReference;
 		this.element = element;
+		this.classes = bodyClassParser.parseFrom(element, 'class');
 		this.elements = BodyDefinition.getChildElementDefinitions(form, this, element);
 		this.elementsByReference = new BodyElementMap(this.elements);
 	}
diff --git a/packages/xforms-engine/src/body/RepeatElementDefinition.ts b/packages/xforms-engine/src/body/RepeatElementDefinition.ts
index 5e4bb144..67c0e986 100644
--- a/packages/xforms-engine/src/body/RepeatElementDefinition.ts
+++ b/packages/xforms-engine/src/body/RepeatElementDefinition.ts
@@ -3,6 +3,8 @@ import type { XFormDefinition } from '../XFormDefinition.ts';
 import type { BodyElementDefinitionArray, BodyElementParentContext } from './BodyDefinition.ts';
 import { BodyDefinition } from './BodyDefinition.ts';
 import { BodyElementDefinition } from './BodyElementDefinition.ts';
+import type { StructureElementAppearanceDefinition } from './appearance/structureElementAppearanceParser.ts';
+import { structureElementAppearanceParser } from './appearance/structureElementAppearanceParser.ts';
 import { LabelDefinition } from './text/LabelDefinition.ts';
 
 export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
@@ -13,6 +15,7 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 	override readonly category = 'structure';
 	readonly type = 'repeat';
 	override readonly reference: string;
+	readonly appearances: StructureElementAppearanceDefinition;
 	override readonly label: LabelDefinition | null;
 
 	// TODO: this will fall into the growing category of non-`BindExpression`
@@ -35,6 +38,7 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 		}
 
 		this.reference = reference;
+		this.appearances = structureElementAppearanceParser.parseFrom(element, 'appearance');
 		this.countExpression = element.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'count');
 
 		const childElements = Array.from(element.children).filter((childElement) => {
diff --git a/packages/xforms-engine/src/body/appearance/inputAppearanceParser.ts b/packages/xforms-engine/src/body/appearance/inputAppearanceParser.ts
new file mode 100644
index 00000000..7e5abb5a
--- /dev/null
+++ b/packages/xforms-engine/src/body/appearance/inputAppearanceParser.ts
@@ -0,0 +1,39 @@
+import { TokenListParser, type ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export const inputAppearanceParser = new TokenListParser([
+	'multiline',
+	'numbers',
+	'url',
+	'thousand-sep',
+
+	// date (TODO: data types)
+	'no-calendar',
+	'month-year',
+	'year',
+	// date > calendars
+	'ethiopian',
+	'coptic',
+	'islamic',
+	'bikram-sambat',
+	'myanmar',
+	'persian',
+
+	// geo (TODO: data types)
+	'placement-map',
+	'maps',
+
+	// image/media (TODO: move to eventual `<upload>`?)
+	'hidden-answer',
+	'annotate',
+	'draw',
+	'signature',
+	'new-front',
+	'new',
+	'front',
+
+	// *?
+	'printer', // Note: actual usage uses `printer:...` (like `ex:...`).
+	'masked',
+]);
+
+export type InputAppearanceDefinition = ParsedTokenList<typeof inputAppearanceParser>;
diff --git a/packages/xforms-engine/src/body/appearance/selectAppearanceParser.ts b/packages/xforms-engine/src/body/appearance/selectAppearanceParser.ts
new file mode 100644
index 00000000..0cf8f2b0
--- /dev/null
+++ b/packages/xforms-engine/src/body/appearance/selectAppearanceParser.ts
@@ -0,0 +1,38 @@
+import { TokenListParser, type ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export const selectAppearanceParser = new TokenListParser(
+	[
+		// From XLSForm Docs:
+		'compact',
+		'horizontal',
+		'horizontal-compact',
+		'label',
+		'list-nolabel',
+		'minimal',
+
+		// From Collect `Appearances.kt`:
+		'columns',
+		'columns-1',
+		'columns-2',
+		'columns-3',
+		'columns-4',
+		'columns-5',
+		// Note: Collect supports arbitrary columns-n. Technically we do too (we parse
+		// out any appearance, not just those we know about). But we'll only include
+		// types/defaults up to 5.
+		'columns-pack',
+		'autocomplete',
+
+		// TODO: these are `<select1>` only
+		'likert',
+		'quick',
+		'quickcompact',
+		'map',
+		// "quick map"
+	],
+	{
+		aliases: [{ fromAlias: 'search', toCanonical: 'autocomplete' }],
+	}
+);
+
+export type SelectAppearanceDefinition = ParsedTokenList<typeof selectAppearanceParser>;
diff --git a/packages/xforms-engine/src/body/appearance/structureElementAppearanceParser.ts b/packages/xforms-engine/src/body/appearance/structureElementAppearanceParser.ts
new file mode 100644
index 00000000..a1a65f16
--- /dev/null
+++ b/packages/xforms-engine/src/body/appearance/structureElementAppearanceParser.ts
@@ -0,0 +1,7 @@
+import { TokenListParser, type ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export const structureElementAppearanceParser = new TokenListParser(['field-list', 'table-list']);
+
+export type StructureElementAppearanceDefinition = ParsedTokenList<
+	typeof structureElementAppearanceParser
+>;
diff --git a/packages/xforms-engine/src/body/control/ControlDefinition.ts b/packages/xforms-engine/src/body/control/ControlDefinition.ts
index 8470c531..bbe167bf 100644
--- a/packages/xforms-engine/src/body/control/ControlDefinition.ts
+++ b/packages/xforms-engine/src/body/control/ControlDefinition.ts
@@ -1,4 +1,5 @@
 import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { ParsedTokenList } from '../../lib/TokenListParser.ts';
 import type { BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
 import { HintDefinition } from '../text/HintDefinition.ts';
@@ -23,6 +24,9 @@ export abstract class ControlDefinition<
 	override readonly label: LabelDefinition | null;
 	override readonly hint: HintDefinition | null;
 
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	abstract readonly appearances: ParsedTokenList<any>;
+
 	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
 		super(form, parent, element);
 
diff --git a/packages/xforms-engine/src/body/control/InputDefinition.ts b/packages/xforms-engine/src/body/control/InputDefinition.ts
index 8c532bf7..8010c2b5 100644
--- a/packages/xforms-engine/src/body/control/InputDefinition.ts
+++ b/packages/xforms-engine/src/body/control/InputDefinition.ts
@@ -1,3 +1,9 @@
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { BodyElementParentContext } from '../BodyDefinition.ts';
+import {
+	inputAppearanceParser,
+	type InputAppearanceDefinition,
+} from '../appearance/inputAppearanceParser.ts';
 import { ControlDefinition } from './ControlDefinition.ts';
 
 export class InputDefinition extends ControlDefinition<'input'> {
@@ -6,4 +12,11 @@ export class InputDefinition extends ControlDefinition<'input'> {
 	}
 
 	readonly type = 'input';
+	readonly appearances: InputAppearanceDefinition;
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		super(form, parent, element);
+
+		this.appearances = inputAppearanceParser.parseFrom(element, 'appearance');
+	}
 }
diff --git a/packages/xforms-engine/src/body/control/select/SelectDefinition.ts b/packages/xforms-engine/src/body/control/select/SelectDefinition.ts
index 5e8a696b..7b31a8c3 100644
--- a/packages/xforms-engine/src/body/control/select/SelectDefinition.ts
+++ b/packages/xforms-engine/src/body/control/select/SelectDefinition.ts
@@ -3,14 +3,21 @@ import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
 import type { XFormDefinition } from '../../../XFormDefinition.ts';
 import { getItemElements, getItemsetElement } from '../../../lib/dom/query.ts';
 import type { AnyBodyElementDefinition, BodyElementParentContext } from '../../BodyDefinition.ts';
+import type { SelectAppearanceDefinition } from '../../appearance/selectAppearanceParser.ts';
+import { selectAppearanceParser } from '../../appearance/selectAppearanceParser.ts';
 import { ControlDefinition } from '../ControlDefinition.ts';
 import { ItemDefinition } from './ItemDefinition.ts';
 import { ItemsetDefinition } from './ItemsetDefinition.ts';
 
-// TODO: `<trigger>` is *almost* reasonable to support here too. The main
-// hesitation is that its single, implicit "item" does not have a distinct
-// <label>, and presumably has different UX **and translation** considerations.
-const selectLocalNames = new Set(['rank', 'select', 'select1'] as const);
+/**
+ * @todo We were previously a bit overzealous about introducing `<rank>` support
+ * here. It'll likely still fit, but we should approach it with more intention.
+ *
+ * @todo `<trigger>` is *almost* reasonable to support here too. The main
+ * hesitation is that its single, implicit "item" does not have a distinct
+ * <label>, and presumably has different UX **and translation** considerations.
+ */
+const selectLocalNames = new Set([/* 'rank', */ 'select', 'select1'] as const);
 
 export type SelectType = CollectionValues<typeof selectLocalNames>;
 
@@ -34,6 +41,7 @@ export class SelectDefinition<Type extends SelectType> extends ControlDefinition
 
 	override readonly type: Type;
 	override readonly element: SelectElement;
+	readonly appearances: SelectAppearanceDefinition;
 
 	readonly itemset: ItemsetDefinition | null;
 	readonly items: readonly ItemDefinition[];
@@ -45,8 +53,9 @@ export class SelectDefinition<Type extends SelectType> extends ControlDefinition
 
 		super(form, parent, element);
 
-		this.element = element;
 		this.type = element.localName as Type;
+		this.element = element;
+		this.appearances = selectAppearanceParser.parseFrom(element, 'appearance');
 
 		const itemsetElement = getItemsetElement(element);
 		const itemElements = getItemElements(element);
diff --git a/packages/xforms-engine/src/body/group/BaseGroupDefinition.ts b/packages/xforms-engine/src/body/group/BaseGroupDefinition.ts
index 8472555b..14ec616b 100644
--- a/packages/xforms-engine/src/body/group/BaseGroupDefinition.ts
+++ b/packages/xforms-engine/src/body/group/BaseGroupDefinition.ts
@@ -7,6 +7,8 @@ import {
 	type BodyElementParentContext,
 } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import type { StructureElementAppearanceDefinition } from '../appearance/structureElementAppearanceParser.ts';
+import { structureElementAppearanceParser } from '../appearance/structureElementAppearanceParser.ts';
 import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 /**
@@ -67,6 +69,7 @@ export abstract class BaseGroupDefinition<
 	readonly children: BodyElementDefinitionArray;
 
 	override readonly reference: string | null;
+	readonly appearances: StructureElementAppearanceDefinition;
 	override readonly label: LabelDefinition | null;
 
 	constructor(
@@ -79,6 +82,7 @@ export abstract class BaseGroupDefinition<
 
 		this.children = children ?? this.getChildren(element);
 		this.reference = element.getAttribute('ref');
+		this.appearances = structureElementAppearanceParser.parseFrom(element, 'appearance');
 		this.label = LabelDefinition.forGroup(form, this);
 	}
 
diff --git a/packages/xforms-engine/src/body/text/TextElementDefinition.ts b/packages/xforms-engine/src/body/text/TextElementDefinition.ts
index 1ebf8cf7..d5b5c8d2 100644
--- a/packages/xforms-engine/src/body/text/TextElementDefinition.ts
+++ b/packages/xforms-engine/src/body/text/TextElementDefinition.ts
@@ -4,10 +4,9 @@ import { type AnyDependentExpression } from '../../expression/DependentExpressio
 import type { AnyGroupElementDefinition } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
 import type { RepeatElementDefinition } from '../RepeatElementDefinition.ts';
-import type { InputDefinition } from '../control/InputDefinition.ts';
+import type { AnyControlDefinition } from '../control/ControlDefinition.ts';
 import type { ItemDefinition } from '../control/select/ItemDefinition.ts';
 import type { ItemsetDefinition } from '../control/select/ItemsetDefinition.ts';
-import type { AnySelectDefinition } from '../control/select/SelectDefinition.ts';
 import { TextElementOutputPart } from './TextElementOutputPart.ts';
 import { TextElementReferencePart } from './TextElementReferencePart.ts';
 import { TextElementStaticPart } from './TextElementStaticPart.ts';
@@ -19,9 +18,8 @@ export interface TextElement extends Element {
 }
 
 export type TextElementOwner =
+	| AnyControlDefinition
 	| AnyGroupElementDefinition
-	| AnySelectDefinition
-	| InputDefinition
 	| ItemDefinition
 	| ItemsetDefinition
 	| RepeatElementDefinition;
diff --git a/packages/xforms-engine/src/client/BaseNode.ts b/packages/xforms-engine/src/client/BaseNode.ts
index 9a9f5d5c..67193b47 100644
--- a/packages/xforms-engine/src/client/BaseNode.ts
+++ b/packages/xforms-engine/src/client/BaseNode.ts
@@ -1,7 +1,9 @@
+import type { TokenListParser } from '../lib/TokenListParser.ts';
 import type { AnyNodeDefinition } from '../model/NodeDefinition.ts';
-import type { InstanceNodeType } from './node-types.js';
+import type { NodeAppearances } from './NodeAppearances.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 import type { TextRange } from './TextRange.ts';
+import type { InstanceNodeType } from './node-types.ts';
 
 export interface BaseNodeState {
 	/**
@@ -126,6 +128,12 @@ export interface BaseNode {
 	 */
 	readonly nodeId: FormNodeID;
 
+	/**
+	 * @see {@link TokenListParser} for details.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly appearances: NodeAppearances<any> | null;
+
 	/**
 	 * Each node has a definition which specifies aspects of the node defined in
 	 * the form. These aspects include (but are not limited to) the node's data
diff --git a/packages/xforms-engine/src/client/GroupNode.ts b/packages/xforms-engine/src/client/GroupNode.ts
index 342c57ce..637847ad 100644
--- a/packages/xforms-engine/src/client/GroupNode.ts
+++ b/packages/xforms-engine/src/client/GroupNode.ts
@@ -1,6 +1,7 @@
 import type { AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
 import type { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 
@@ -17,6 +18,8 @@ export interface GroupDefinition extends SubtreeDefinition {
 	readonly bodyElement: AnyGroupElementDefinition;
 }
 
+export type GroupNodeAppearances = NodeAppearances<GroupDefinition>;
+
 /**
  * A node corresponding to an XForms `<group>`.
  */
@@ -26,6 +29,7 @@ export interface GroupDefinition extends SubtreeDefinition {
 // for context.
 export interface GroupNode extends BaseNode {
 	readonly nodeType: 'group';
+	readonly appearances: GroupNodeAppearances;
 	readonly definition: GroupDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
diff --git a/packages/xforms-engine/src/client/NodeAppearances.ts b/packages/xforms-engine/src/client/NodeAppearances.ts
new file mode 100644
index 00000000..1c4161c7
--- /dev/null
+++ b/packages/xforms-engine/src/client/NodeAppearances.ts
@@ -0,0 +1,22 @@
+import type { ParsedTokenList } from '../lib/TokenListParser.ts';
+import type { NodeDefinition } from '../model/NodeDefinition.ts';
+
+/**
+ * - Provides a means to distinguish between internal and client-facing names
+ *   for the same {@link ParsedTokenList} types.
+ *
+ * - Anticipates some iteration on both parsed ("definition") types and
+ *   client-facing node types, which may not happen in tandem.
+ */
+// prettier-ignore
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type NodeAppearances<Definition extends NodeDefinition<any>> =
+	Definition extends {
+		readonly bodyElement: {
+			readonly appearances:
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				infer Appearances extends ParsedTokenList<any>
+		};
+	}
+		? Appearances
+		: null;
diff --git a/packages/xforms-engine/src/client/RepeatInstanceNode.ts b/packages/xforms-engine/src/client/RepeatInstanceNode.ts
index 1716f407..9692cd0c 100644
--- a/packages/xforms-engine/src/client/RepeatInstanceNode.ts
+++ b/packages/xforms-engine/src/client/RepeatInstanceNode.ts
@@ -1,6 +1,7 @@
 import type { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
 import type { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RepeatRangeNode } from './RepeatRangeNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
@@ -22,8 +23,11 @@ export type RepeatDefinition =
 	| RepeatInstanceDefinition
 	| RepeatTemplateDefinition;
 
+export type RepeatInstanceNodeAppearances = NodeAppearances<RepeatDefinition>;
+
 export interface RepeatInstanceNode extends BaseNode {
 	readonly nodeType: 'repeat-instance';
+	readonly appearances: RepeatInstanceNodeAppearances;
 	readonly definition: RepeatDefinition;
 	readonly root: RootNode;
 
diff --git a/packages/xforms-engine/src/client/RepeatRangeNode.ts b/packages/xforms-engine/src/client/RepeatRangeNode.ts
index 911a07fe..966be56b 100644
--- a/packages/xforms-engine/src/client/RepeatRangeNode.ts
+++ b/packages/xforms-engine/src/client/RepeatRangeNode.ts
@@ -1,5 +1,6 @@
 import type { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { TextRange } from './TextRange.ts';
@@ -23,6 +24,8 @@ export interface RepeatRangeNodeState extends BaseNodeState {
 	get value(): null;
 }
 
+export type RepeatRangeNodeAppearances = NodeAppearances<RepeatRangeDefinition>;
+
 /**
  * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
  * (accessed by its
@@ -89,6 +92,7 @@ export interface RepeatRangeNodeState extends BaseNodeState {
  */
 export interface RepeatRangeNode extends BaseNode {
 	readonly nodeType: 'repeat-range';
+	readonly appearances: RepeatRangeNodeAppearances;
 	readonly definition: RepeatRangeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
diff --git a/packages/xforms-engine/src/client/RootNode.ts b/packages/xforms-engine/src/client/RootNode.ts
index b0ce9fce..be714374 100644
--- a/packages/xforms-engine/src/client/RootNode.ts
+++ b/packages/xforms-engine/src/client/RootNode.ts
@@ -1,3 +1,4 @@
+import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { RootDefinition } from '../model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
@@ -21,6 +22,27 @@ export interface RootNodeState extends BaseNodeState {
 
 export interface RootNode extends BaseNode {
 	readonly nodeType: 'root';
+
+	/**
+	 * @todo this along with {@link classes} is... awkward.
+	 */
+	readonly appearances: null;
+
+	/**
+	 * @todo This is another odd deviation in {@link RootNode}. Unlike
+	 * {@link languages}, it doesn't feel particularly **essential**. While it
+	 * would deviate from XForms spec terminology, it seems like it _might be
+	 * reasonable_ to instead convey `<h:body class="...">` as
+	 * {@link RootNode.appearances} in the client interface. They do have slightly
+	 * different spec semantics (i.e. a body class can be anything, to trigger
+	 * styling in a form UI). But the **most likely anticipated** use case in Web
+	 * Forms would be the "pages" class, and perhaps "theme-grid". The former is
+	 * definitely conceptually similar to a XForms `appearance` (albeit
+	 * form-global, which is not a spec concept). The latter does as well, and we
+	 * already anticipate applying that concept in non-form-global ways.
+	 */
+	readonly classes: BodyClassList;
+
 	readonly definition: RootDefinition;
 	readonly root: RootNode;
 	readonly parent: null;
diff --git a/packages/xforms-engine/src/client/SelectNode.ts b/packages/xforms-engine/src/client/SelectNode.ts
index 23d2a4e9..ecb105ab 100644
--- a/packages/xforms-engine/src/client/SelectNode.ts
+++ b/packages/xforms-engine/src/client/SelectNode.ts
@@ -1,6 +1,7 @@
 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 { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { StringNode } from './StringNode.ts';
 import type { TextRange } from './TextRange.ts';
@@ -38,8 +39,11 @@ export interface SelectDefinition extends ValueNodeDefinition {
 	readonly bodyElement: AnySelectDefinition;
 }
 
+export type SelectNodeAppearances = NodeAppearances<SelectDefinition>;
+
 export interface SelectNode extends BaseNode {
 	readonly nodeType: 'select';
+	readonly appearances: SelectNodeAppearances;
 	readonly definition: SelectDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
diff --git a/packages/xforms-engine/src/client/StringNode.ts b/packages/xforms-engine/src/client/StringNode.ts
index 22c1ff8d..740dcab6 100644
--- a/packages/xforms-engine/src/client/StringNode.ts
+++ b/packages/xforms-engine/src/client/StringNode.ts
@@ -1,6 +1,7 @@
 import type { InputDefinition } from '../body/control/InputDefinition.ts';
 import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 
@@ -21,6 +22,8 @@ export interface StringDefinition extends ValueNodeDefinition {
 	readonly bodyElement: InputDefinition | null;
 }
 
+export type StringNodeAppearances = NodeAppearances<StringDefinition>;
+
 /**
  * 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
@@ -30,6 +33,7 @@ export interface StringDefinition extends ValueNodeDefinition {
  */
 export interface StringNode extends BaseNode {
 	readonly nodeType: 'string';
+	readonly appearances: StringNodeAppearances;
 	readonly definition: StringDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
diff --git a/packages/xforms-engine/src/client/SubtreeNode.ts b/packages/xforms-engine/src/client/SubtreeNode.ts
index 467894ad..d5dfe752 100644
--- a/packages/xforms-engine/src/client/SubtreeNode.ts
+++ b/packages/xforms-engine/src/client/SubtreeNode.ts
@@ -50,6 +50,7 @@ export interface SubtreeDefinition extends BaseSubtreeDefinition {
 // TODO: directly test presentation of non-group subtree children/descendants
 export interface SubtreeNode extends BaseNode {
 	readonly nodeType: 'subtree';
+	readonly appearances: null;
 	readonly definition: SubtreeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
diff --git a/packages/xforms-engine/src/instance/Group.ts b/packages/xforms-engine/src/instance/Group.ts
index 142d6371..85ec584e 100644
--- a/packages/xforms-engine/src/instance/Group.ts
+++ b/packages/xforms-engine/src/instance/Group.ts
@@ -1,5 +1,5 @@
 import type { Accessor } from 'solid-js';
-import type { GroupDefinition, GroupNode } from '../client/GroupNode.ts';
+import type { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
 import type { TextRange } from '../index.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
@@ -38,13 +38,15 @@ export class Group
 	protected override engineState: EngineState<GroupStateSpec>;
 
 	// GroupNode
-	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
-
 	readonly nodeType = 'group';
+	readonly appearances: GroupNodeAppearances;
+	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
 
 	constructor(parent: GeneralParentNode, definition: GroupDefinition) {
 		super(parent, definition);
 
+		this.appearances = definition.bodyElement.appearances;
+
 		const childrenState = createChildrenState<Group, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
diff --git a/packages/xforms-engine/src/instance/RepeatInstance.ts b/packages/xforms-engine/src/instance/RepeatInstance.ts
index 0035dabb..e1ffae3f 100644
--- a/packages/xforms-engine/src/instance/RepeatInstance.ts
+++ b/packages/xforms-engine/src/instance/RepeatInstance.ts
@@ -1,6 +1,10 @@
 import type { Accessor } from 'solid-js';
 import { createComputed, createSignal, on } from 'solid-js';
-import type { RepeatDefinition, RepeatInstanceNode } from '../client/RepeatInstanceNode.ts';
+import type {
+	RepeatDefinition,
+	RepeatInstanceNode,
+	RepeatInstanceNodeAppearances,
+} from '../client/RepeatInstanceNode.ts';
 import type { TextRange } from '../index.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
@@ -49,6 +53,11 @@ export class RepeatInstance
 	// RepeatInstanceNode
 	readonly nodeType = 'repeat-instance';
 
+	/**
+	 * @see {@link RepeatRange.appearances}
+	 */
+	readonly appearances: RepeatInstanceNodeAppearances;
+
 	readonly currentState: MaterializedChildren<
 		CurrentState<RepeatInstanceStateSpec>,
 		GeneralChildNode
@@ -61,6 +70,8 @@ export class RepeatInstance
 	) {
 		super(parent, definition);
 
+		this.appearances = definition.bodyElement.appearances;
+
 		const childrenState = createChildrenState<RepeatInstance, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
diff --git a/packages/xforms-engine/src/instance/RepeatRange.ts b/packages/xforms-engine/src/instance/RepeatRange.ts
index 7bbc6182..b61d33dd 100644
--- a/packages/xforms-engine/src/instance/RepeatRange.ts
+++ b/packages/xforms-engine/src/instance/RepeatRange.ts
@@ -1,6 +1,6 @@
 import { insertAtIndex } from '@getodk/common/lib/array/insert.ts';
 import type { Accessor } from 'solid-js';
-import type { RepeatRangeNode } from '../client/RepeatRangeNode.ts';
+import type { RepeatRangeNode, RepeatRangeNodeAppearances } from '../client/RepeatRangeNode.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -67,11 +67,48 @@ export class RepeatRange
 	// RepeatRangeNode
 	readonly nodeType = 'repeat-range';
 
+	/**
+	 * @todo RepeatRange*, RepeatInstance* (and RepeatTemplate*) all share the
+	 * same body element, and thus all share the same definition `bodyElement`. As
+	 * such, they also all share the same `appearances`. At time of writing,
+	 * `web-forms` (Vue UI package) treats a `RepeatRangeNode`...
+	 *
+	 * - ... as a group, if the node has a label (i.e.
+	 *   `<group><label/><repeat/></group>`)
+	 * - ... effectively as a fragment containing only its instances, otherwise
+	 *
+	 * We now collapse `<group><repeat>` into `<repeat>`, and no longer treat
+	 * "repeat group" as a concept (after parsing). According to the spec, these
+	 * appearances **are supposed to** come from that "repeat group" in the form
+	 * definition. In practice, many forms do define appearances directly on a
+	 * repeat element. The engine currently produces an error if both are defined
+	 * simultaneously, but otherwise makes no distinction between appearances in
+	 * these form definition shapes:
+	 *
+	 * ```xml
+	 * <group ref="/data/rep1" appearance="...">
+	 *   <repeat nodeset="/data/rep1"/>
+	 * </group>
+	 *
+	 * <group ref="/data/rep1">
+	 *   <repeat nodeset="/data/rep1"/ appearance="...">
+	 * </group>
+	 *
+	 * <repeat nodeset="/data/rep1"/ appearance="...">
+	 * ```
+	 *
+	 * All of the above creates considerable ambiguity about where "repeat
+	 * appearances" should apply, under which circumstances.
+	 */
+	readonly appearances: RepeatRangeNodeAppearances;
+
 	readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
 
 	constructor(parent: GeneralParentNode, definition: RepeatRangeDefinition) {
 		super(parent, definition);
 
+		this.appearances = definition.bodyElement.appearances;
+
 		const childrenState = createChildrenState<RepeatRange, RepeatInstance>(this);
 
 		this.childrenState = childrenState;
diff --git a/packages/xforms-engine/src/instance/Root.ts b/packages/xforms-engine/src/instance/Root.ts
index f46a8f5e..44110f7e 100644
--- a/packages/xforms-engine/src/instance/Root.ts
+++ b/packages/xforms-engine/src/instance/Root.ts
@@ -2,6 +2,7 @@ import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor, Signal } from 'solid-js';
 import { createSignal } from 'solid-js';
 import type { XFormDOM } from '../XFormDOM.ts';
+import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { RootNode } from '../client/RootNode.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
@@ -118,7 +119,8 @@ export class Root
 
 	// RootNode
 	readonly nodeType = 'root';
-
+	readonly appearances = null;
+	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 
 	protected readonly instanceDOM: XFormDOM;
@@ -154,6 +156,8 @@ export class Root
 	) {
 		super(engineConfig, null, definition);
 
+		this.classes = definition.classes;
+
 		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
diff --git a/packages/xforms-engine/src/instance/SelectField.ts b/packages/xforms-engine/src/instance/SelectField.ts
index b7fa7bcb..294185d2 100644
--- a/packages/xforms-engine/src/instance/SelectField.ts
+++ b/packages/xforms-engine/src/instance/SelectField.ts
@@ -2,7 +2,7 @@ import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/white
 import type { Accessor } from 'solid-js';
 import { untrack } from 'solid-js';
 import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import type { SelectItem, SelectNode } from '../client/SelectNode.ts';
+import type { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
 import type { TextRange } from '../index.ts';
 import { createSelectItems } from '../lib/reactivity/createSelectItems.ts';
 import { createValueState } from '../lib/reactivity/createValueState.ts';
@@ -50,7 +50,7 @@ export class SelectField
 
 	// SelectNode
 	readonly nodeType = 'select';
-
+	readonly appearances: SelectNodeAppearances;
 	readonly currentState: CurrentState<SelectFieldStateSpec>;
 
 	// ValueContext
@@ -83,6 +83,7 @@ export class SelectField
 	constructor(parent: GeneralParentNode, definition: SelectFieldDefinition) {
 		super(parent, definition);
 
+		this.appearances = definition.bodyElement.appearances;
 		this.selectExclusive = definition.bodyElement.type === 'select1';
 
 		const valueOptions = createSelectItems(this);
diff --git a/packages/xforms-engine/src/instance/StringField.ts b/packages/xforms-engine/src/instance/StringField.ts
index ea3ecc84..ac84b4fc 100644
--- a/packages/xforms-engine/src/instance/StringField.ts
+++ b/packages/xforms-engine/src/instance/StringField.ts
@@ -1,7 +1,7 @@
 import { identity } from '@getodk/common/lib/identity.ts';
 import type { Accessor } from 'solid-js';
 import type { InputDefinition } from '../body/control/InputDefinition.ts';
-import type { StringNode } from '../client/StringNode.ts';
+import type { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
 import type { TextRange } from '../index.ts';
 import { createValueState } from '../lib/reactivity/createValueState.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -43,7 +43,7 @@ export class StringField
 
 	// StringNode
 	readonly nodeType = 'string';
-
+	readonly appearances: StringNodeAppearances;
 	readonly currentState: CurrentState<StringFieldStateSpec>;
 
 	// ValueContext
@@ -54,6 +54,8 @@ export class StringField
 	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
 		super(parent, definition);
 
+		this.appearances = (definition.bodyElement?.appearances ?? null) as StringNodeAppearances;
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
diff --git a/packages/xforms-engine/src/instance/Subtree.ts b/packages/xforms-engine/src/instance/Subtree.ts
index 902b86c1..1fae93da 100644
--- a/packages/xforms-engine/src/instance/Subtree.ts
+++ b/packages/xforms-engine/src/instance/Subtree.ts
@@ -36,7 +36,7 @@ export class Subtree
 
 	// SubtreeNode
 	readonly nodeType = 'subtree';
-
+	readonly appearances = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 
 	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
diff --git a/packages/xforms-engine/src/instance/abstract/InstanceNode.ts b/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
index 08fb9b60..f1130989 100644
--- a/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
+++ b/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
@@ -2,6 +2,7 @@ import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor, Signal } from 'solid-js';
 import { createSignal } from 'solid-js';
 import type { BaseNode } from '../../client/BaseNode.ts';
+import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { InstanceNodeType } from '../../client/node-types.ts';
 import type { TextRange } from '../../index.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -130,6 +131,8 @@ export abstract class InstanceNode<
 	// BaseNode: node types and variants (e.g. for narrowing)
 	abstract readonly nodeType: InstanceNodeType;
 
+	abstract readonly appearances: NodeAppearances<Definition>;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
 	// BaseNode: structural
diff --git a/packages/xforms-engine/src/instance/children.ts b/packages/xforms-engine/src/instance/children.ts
index 18e3f737..f0af1499 100644
--- a/packages/xforms-engine/src/instance/children.ts
+++ b/packages/xforms-engine/src/instance/children.ts
@@ -1,11 +1,12 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import { SelectDefinition } from '../body/control/select/SelectDefinition.ts';
 import type { GroupDefinition } from '../client/GroupNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
 import type { SubtreeDefinition as ModelSubtreeDefinition } from '../model/SubtreeDefinition.ts';
 import { Group } from './Group.ts';
 import { RepeatRange } from './RepeatRange.ts';
-import { SelectField, type SelectFieldDefinition } from './SelectField.ts';
+import type { SelectFieldDefinition } from './SelectField.ts';
+import { SelectField } from './SelectField.ts';
+import type { StringFieldDefinition } from './StringField.ts';
 import { StringField } from './StringField.ts';
 import { Subtree } from './Subtree.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
@@ -37,11 +38,20 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 			}
 
 			case 'value-node': {
-				if (child.bodyElement instanceof SelectDefinition) {
-					return new SelectField(parent, child as SelectFieldDefinition);
+				// TODO: this sort of awkwardness might go away if we embrace a
+				// proliferation of node types throughout.
+				switch (child.bodyElement?.type) {
+					case 'select':
+					case 'select1':
+						return new SelectField(parent, child as SelectFieldDefinition);
+
+					case 'input':
+					case undefined:
+						return new StringField(parent, child as StringFieldDefinition);
+
+					default:
+						throw new UnreachableError(child.bodyElement);
 				}
-
-				return new StringField(parent, child);
 			}
 
 			default: {
diff --git a/packages/xforms-engine/src/lib/TokenListParser.ts b/packages/xforms-engine/src/lib/TokenListParser.ts
new file mode 100644
index 00000000..bd9531e0
--- /dev/null
+++ b/packages/xforms-engine/src/lib/TokenListParser.ts
@@ -0,0 +1,156 @@
+import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
+import type { PartiallyKnownString } from '@getodk/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>
+>;
+
+/**
+ * @see {@link TokenListParser}
+ */
+// prettier-ignore
+export type TokenList<CanonicalToken extends string = string> = {
+	readonly [Key in TokenListKey<CanonicalToken>]:
+		Key extends SymbolIterator
+			? () => TokenListIterator<CanonicalToken>
+			: boolean;
+};
+
+interface TokenListAlias<CanonicalToken extends string> {
+	readonly fromAlias: string;
+	readonly toCanonical: CanonicalToken;
+}
+
+type TokenAliases<CanonicalToken extends string> = ReadonlyArray<TokenListAlias<CanonicalToken>>;
+
+interface TokenListParserOptions<CanonicalToken extends string> {
+	readonly aliases?: TokenAliases<CanonicalToken>;
+}
+
+type TokenListAttributeName = PartiallyKnownString<'appearance' | 'class'>;
+
+/**
+ * Intended primarily for use in parsing these features:
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#appearances | appearances} ({@link https://xlsform.org/en/#appearance | additional documentation})
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#body-attributes | body `class` attribute}
+ *
+ * This class is named as a reference to {@link DOMTokenList}
+ * ({@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList | MDN}),
+ * with these similarities:
+ *
+ * - Represents a value whose serialization is a space-separated list.
+ * - Each member ("token") is a string (without whitespace).
+ * - Provides set-like semantics to determine presence of members.
+ * - Provides ordering semantics as determined by the serialization.
+ *
+ * This class differs from that prior art in that:
+ *
+ * - It provides a notion of "canonical" members. This is _mostly_ (but not
+ *   entirely) intended as a convenience to client developers, automatically
+ *   populating canonical/known tokens for a given parser type in
+ *   editor-provided autocomplete, etc. **Importantly**, non-canonical tokens
+ *   _are not ignored_ in either the {@link TokenList}'s types or runtime
+ *   values.
+ *
+ * - Provided "canonical" members may also be used to specify
+ *   {@link TokenListParserOptions.aliases | optional aliases}. (Example: when
+ *   parsing "appearances", an alias might map an older deprecated appearance to
+ *   a newer canonical equivalent.) **Importantly**, when a token matches an
+ *   alias, both that alias _and the token as-specified_ will be present in the
+ *   produced {@link TokenList}.
+ *
+ * - As a parser, it is intended to be read-only. The serialized format which it
+ *   parses is _generally_ the source of truth (excepting e.g. aliases).
+ *   Notably, and as mentioned above, ordering is determined by:
+ *
+ *     - Iterating each member, as provided by the serialized representation
+ *
+ *     - If that member corresponds to an alias, that alias is yielded first
+ *
+ *     - Regardless of whether the member corresponds to an alias, the member is
+ *       yielded as-specified
+ *
+ * - A parsed {@link TokenList} is intended to maximize convenience of read-only
+ *   access. Despite many _conceptual similarities_, most of the
+ *   {@link DOMTokenList} **interface** is eschewed in favor of two (mutually
+ *   equivalent) access mechanisms:
+ *
+ *     - `Iterable<Token>`, with the ordering semantics described above
+ *     - `Record<Token, boolean>`
+ *
+ * \* This may change, as we refine requirements. In the future, we may
+ * introduce a notion of mutually exclusive tokens (e.g. "appearances" which
+ * cannot be used together), which may in turn utilize instance-defined ordering
+ * as part of that mechanism.
+ */
+export class TokenListParser<
+	CanonicalToken extends string,
+	// Note: this is a separate type parameter so that specifying an alias does
+	// not cause it to be mistakenly inferred as a `CanonicalToken` which was
+	// not otherwise specified.
+	TokenAlias extends CanonicalToken = CanonicalToken,
+> {
+	private readonly aliases: ReadonlyMap<string, CanonicalToken>;
+
+	constructor(
+		readonly canonicalTokens: readonly CanonicalToken[],
+		options?: TokenListParserOptions<TokenAlias>
+	) {
+		this.aliases = new Map(
+			(options?.aliases ?? []).map(({ fromAlias, toCanonical }) => {
+				return [fromAlias, toCanonical];
+			})
+		);
+	}
+
+	parseFrom(element: Element, attributeName: TokenListAttributeName): TokenList<CanonicalToken> {
+		const serialized = element.getAttribute(attributeName) ?? '';
+		const specified = xmlXPathWhitespaceSeparatedList(serialized, {
+			ignoreEmpty: true,
+		});
+		const { aliases } = this;
+		const resolved = specified.flatMap((token) => {
+			const alias = aliases.get(token);
+
+			if (alias == null) {
+				return token;
+			}
+
+			return [alias, token];
+		});
+		const tokens = new Set(resolved);
+
+		return new Proxy(
+			{
+				[Symbol.iterator]() {
+					return resolved.values();
+				},
+			} satisfies TokenList<string> as TokenList<CanonicalToken>,
+			{
+				get(target, property, receiver) {
+					if (typeof property === 'symbol') {
+						return Reflect.get(target, property, receiver);
+					}
+
+					return tokens.has(property);
+				},
+
+				set() {
+					return false;
+				},
+			}
+		);
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ParsedTokenList<Parser extends TokenListParser<any>> =
+	Parser extends TokenListParser<infer CanonicalToken> ? TokenList<CanonicalToken> : never;
diff --git a/packages/xforms-engine/src/model/ModelDefinition.ts b/packages/xforms-engine/src/model/ModelDefinition.ts
index bb2638eb..2ad57f92 100644
--- a/packages/xforms-engine/src/model/ModelDefinition.ts
+++ b/packages/xforms-engine/src/model/ModelDefinition.ts
@@ -8,7 +8,7 @@ export class ModelDefinition {
 
 	constructor(readonly form: XFormDefinition) {
 		this.binds = ModelBindMap.fromModel(this);
-		this.root = new RootDefinition(form, this);
+		this.root = new RootDefinition(form, this, form.body.classes);
 	}
 
 	toJSON() {
diff --git a/packages/xforms-engine/src/model/RootDefinition.ts b/packages/xforms-engine/src/model/RootDefinition.ts
index f4a3b5a5..84458a70 100644
--- a/packages/xforms-engine/src/model/RootDefinition.ts
+++ b/packages/xforms-engine/src/model/RootDefinition.ts
@@ -1,4 +1,5 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 import type {
@@ -28,7 +29,8 @@ export class RootDefinition implements NodeDefinition<'root'> {
 
 	constructor(
 		protected readonly form: XFormDefinition,
-		protected readonly model: ModelDefinition
+		protected readonly model: ModelDefinition,
+		readonly classes: BodyClassList
 	) {
 		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be
 		// namespaced. It also may make more sense to determine the root nodeset
diff --git a/packages/xforms-engine/src/model/ValueNodeDefinition.ts b/packages/xforms-engine/src/model/ValueNodeDefinition.ts
index 88e9a240..8db070ca 100644
--- a/packages/xforms-engine/src/model/ValueNodeDefinition.ts
+++ b/packages/xforms-engine/src/model/ValueNodeDefinition.ts
@@ -1,11 +1,10 @@
-import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import type { AnyControlDefinition } from '../body/control/ControlDefinition.ts';
+import type { AnyBodyElementDefinition, ControlElementDefinition } from '../body/BodyDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 
 export class ValueNodeDefinition
-	extends DescendentNodeDefinition<'value-node', AnyControlDefinition | null>
+	extends DescendentNodeDefinition<'value-node', ControlElementDefinition | null>
 	implements NodeDefinition<'value-node'>
 {
 	readonly type = 'value-node';