@getodk/xforms-engine 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "description": "XForms engine for ODK Web Forms",
   "type": "module",
@@ -54,27 +54,28 @@
     "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "papaparse": "^5.4.1",
-    "solid-js": "^1.9.3"
+    "bin-packer": "1.7.0",
+    "papaparse": "^5.5.2",
+    "solid-js": "^1.9.5"
   },
   "devDependencies": {
-    "@babel/core": "^7.26.0",
-    "@getodk/tree-sitter-xpath": "0.1.2",
-    "@getodk/xpath": "0.4.0",
+    "@babel/core": "^7.26.10",
+    "@getodk/tree-sitter-xpath": "0.1.3",
+    "@getodk/xpath": "0.4.1",
     "@playwright/test": "^1.49.1",
     "@types/papaparse": "^5.3.15",
-    "@vitest/browser": "^2.1.8",
-    "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
+    "@vitest/browser": "^3.0.9",
+    "babel-plugin-transform-jsbi-to-bigint": "^1.4.2",
     "http-server": "^14.1.1",
-    "jsdom": "^25.0.1",
-    "typedoc": "^0.27.5",
-    "vite": "^5.4.11",
-    "vite-plugin-dts": "^4.3.0",
+    "jsdom": "^26.0.0",
+    "typedoc": "^0.28.2",
+    "vite": "^6.2.3",
+    "vite-plugin-dts": "^4.5.3",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.1.8"
+    "vitest": "^3.0.9"
   },
   "peerDependencies": {
-    "solid-js": "^1.9.3"
+    "solid-js": "^1.9.5"
   },
   "peerDependenciesMeta": {
     "solid-js": {

package/src/client/RootNode.ts

@@ -8,7 +8,10 @@ import type {
 	InstancePayload,
 	MonolithicInstancePayload,
 } from './serialization/InstancePayload.ts';
-import type { InstancePayloadOptions } from './serialization/InstancePayloadOptions.ts';
+import type {
+	InstancePayloadOptions,
+	InstancePayloadType,
+} from './serialization/InstancePayloadOptions.ts';
 import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
@@ -94,11 +97,13 @@ export interface RootNode extends BaseNode {
 	 * case a {@link ChunkedInstancePayload} will be produced, with form
 	 * attachments
 	 */
-	prepareInstancePayload(): Promise<MonolithicInstancePayload>;
 	prepareInstancePayload(
-		options: InstancePayloadOptions<'monolithic'>
+		options?: InstancePayloadOptions<'monolithic'>
 	): Promise<MonolithicInstancePayload>;
 	prepareInstancePayload(
 		options: InstancePayloadOptions<'chunked'>
 	): Promise<ChunkedInstancePayload>;
+	prepareInstancePayload<PayloadType extends InstancePayloadType>(
+		options: InstancePayloadOptions<PayloadType>
+	): Promise<InstancePayload<PayloadType>>;
 }

package/src/client/UploadNode.ts

@@ -0,0 +1,78 @@
+import type { PartiallyKnownString } from '@getodk/common/types/string/PartiallyKnownString.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { UploadControlDefinition } from '../parse/body/control/UploadControlDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { RootNode } from './RootNode.ts';
+import type { InstanceAttachmentFileName } from './serialization/InstanceData.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+import type { ValueType } from './ValueType.ts';
+
+export type UploadValue = File | null;
+
+export interface UploadNodeState extends BaseValueNodeState<UploadValue> {
+	get valueOptions(): null;
+	get value(): UploadValue;
+	get instanceValue(): InstanceAttachmentFileName;
+}
+
+export interface UploadDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	readonly bodyElement: UploadControlDefinition;
+}
+
+// prettier-ignore
+export type UploadMediaType = PartiallyKnownString<
+	| '*'
+	| 'audio'
+	| 'image'
+	| 'video'
+>;
+
+export type UploadMediaSubtype = PartiallyKnownString<'*'>;
+
+// prettier-ignore
+export type UploadMediaAccept = PartiallyKnownString<
+	| '*'
+	| `${UploadMediaType}/${UploadMediaSubtype}`
+>;
+
+interface BaseUploadMediaOptions {
+	readonly accept: UploadMediaAccept;
+	readonly type: UploadMediaType | null;
+	readonly subtype: UploadMediaSubtype | null;
+}
+
+export interface ExplicitUploadMediaOptions extends BaseUploadMediaOptions {
+	readonly type: UploadMediaType;
+	readonly subtype: UploadMediaSubtype;
+}
+
+export interface UnspecifiedUploadMediaOptions extends BaseUploadMediaOptions {
+	readonly type: null;
+	readonly subtype: null;
+}
+
+// prettier-ignore
+export type UploadMediaOptions =
+	| ExplicitUploadMediaOptions
+	| UnspecifiedUploadMediaOptions;
+
+export interface UploadNodeOptions {
+	readonly media: UploadMediaOptions;
+}
+
+export interface UploadNode extends BaseValueNode<'binary', UploadValue> {
+	readonly nodeType: 'upload';
+	/** @todo */
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions: UploadNodeOptions;
+	readonly valueType: 'binary';
+	readonly definition: UploadDefinition<'binary'>;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: UploadNodeState;
+	readonly validationState: LeafNodeValidationState;
+
+	setValue(value: UploadValue): RootNode;
+}

package/src/client/attachments/InstanceAttachmentMeta.ts

@@ -0,0 +1,10 @@
+import type { FormNodeID } from '../identity.ts';
+
+export type InstanceAttachmentExtension = `.${string}`;
+
+export interface InstanceAttachmentMeta {
+	readonly nodeId: FormNodeID;
+	readonly writtenAt: Date | null;
+	readonly basename: string;
+	readonly extension: InstanceAttachmentExtension | null;
+}

package/src/client/attachments/InstanceAttachmentsConfig.ts

@@ -0,0 +1,13 @@
+import type { InstanceAttachmentMeta } from './InstanceAttachmentMeta.ts';
+
+export interface UpdatedInstanceAttachmentMeta extends InstanceAttachmentMeta {
+	readonly writtenAt: Date;
+}
+
+export type InstanceAttachmentFileNameFactory = (
+	meta: UpdatedInstanceAttachmentMeta
+) => string | null;
+
+export interface InstanceAttachmentsConfig {
+	readonly fileNameFactory?: InstanceAttachmentFileNameFactory;
+}

package/src/client/form/FormInstanceConfig.ts

@@ -1,3 +1,4 @@
+import type { InstanceAttachmentsConfig } from '../attachments/InstanceAttachmentsConfig.ts';
 import type { OpaqueReactiveObjectFactory } from '../OpaqueReactiveObjectFactory.ts';
 
 export interface FormInstanceConfig {
@@ -15,4 +16,6 @@ export interface FormInstanceConfig {
 	 * mechanism to handle state updates conveyed by the engine.
 	 */
 	readonly stateFactory?: OpaqueReactiveObjectFactory;
+
+	readonly instanceAttachments?: InstanceAttachmentsConfig;
 }

package/src/client/hierarchy.ts

@@ -4,6 +4,7 @@ import type { AnyInputNode } from './InputNode.ts';
 import type { AnyModelValueNode } from './ModelValueNode.ts';
 import type { AnyNoteNode } from './NoteNode.ts';
 import type { AnyRangeNode } from './RangeNode.ts';
+import type { RankNode } from './RankNode.ts';
 import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
@@ -11,11 +12,7 @@ import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
 import type { TriggerNode } from './TriggerNode.ts';
-import type { RankNode } from './RankNode.ts';
-import type { UploadNode } from './unsupported/UploadNode.ts';
-
-// prettier-ignore
-export type AnyUnsupportedControlNode = UploadNode;
+import type { UploadNode } from './UploadNode.ts';
 
 // prettier-ignore
 export type AnyControlNode =
@@ -24,13 +21,13 @@ export type AnyControlNode =
 	| AnyRangeNode
 	| RankNode
 	| SelectNode
-	| TriggerNode;
+	| TriggerNode
+	| UploadNode;
 
 // prettier-ignore
 export type AnyLeafNode =
 	| AnyControlNode
-	| AnyModelValueNode
-	| AnyUnsupportedControlNode;
+	| AnyModelValueNode;
 
 // prettier-ignore
 export type RepeatRangeNode =

package/src/client/index.ts

@@ -1,3 +1,5 @@
+export type * from './attachments/InstanceAttachmentMeta.ts';
+export type * from './attachments/InstanceAttachmentsConfig.ts';
 export type * from './constants.ts';
 export * as constants from './constants.ts';
 export type * from './form/CreateFormInstance.ts';
@@ -16,11 +18,11 @@ export type {
 	AnyLeafNode,
 	AnyNode,
 	AnyParentNode,
-	AnyUnsupportedControlNode,
 	GeneralChildNode,
 	GeneralParentNode,
 	RepeatRangeNode,
 } from './hierarchy.ts';
+export type * from './identity.ts';
 export type * from './InputNode.ts';
 export type * from './ModelValueNode.ts';
 export type * from './NoteNode.ts';
@@ -42,6 +44,6 @@ export type * from './submission/SubmissionMeta.ts';
 export type * from './SubtreeNode.ts';
 export type * from './TextRange.ts';
 export type * from './TriggerNode.ts';
-export type * from './unsupported/UploadNode.ts';
+export type * from './UploadNode.ts';
 export type * from './validation.ts';
 export type * from './ValueType.ts';

package/src/client/node-types.ts

@@ -1,5 +1,3 @@
-export type UnsupportedControlNodeType = 'upload';
-
 // prettier-ignore
 export type RepeatRangeNodeType =
 	| 'repeat-range:controlled'
@@ -15,7 +13,7 @@ export type LeafNodeType =
 	| 'trigger'
 	| 'range'
 	| 'rank'
-	| UnsupportedControlNodeType;
+	| 'upload';
 
 // prettier-ignore
 export type InstanceNodeType =
@@ -25,5 +23,4 @@ export type InstanceNodeType =
 	| 'repeat-instance'
 	| 'group'
 	| 'subtree'
-	| LeafNodeType
-	| UnsupportedControlNodeType;
+	| LeafNodeType;

package/src/client/serialization/InstanceData.ts

@@ -2,14 +2,22 @@ import type { INSTANCE_FILE_NAME, InstanceFile } from './InstanceFile.ts';
 
 export type InstanceAttachmentFileName = string;
 
+export type InstanceDataEntryValue = File;
+
 export interface InstanceData extends FormData {
-	get(name: INSTANCE_FILE_NAME): InstanceFile;
+	[Symbol.iterator](): FormDataIterator<[string, InstanceDataEntryValue]>;
+	entries(): FormDataIterator<[string, InstanceDataEntryValue]>;
+	values(): FormDataIterator<InstanceDataEntryValue>;
 
-	/**
-	 * @todo Can we guarantee (both in static types and at runtime) that
-	 * {@link InstanceData} only contains files?
-	 */
-	get(name: InstanceAttachmentFileName): FormDataEntryValue | null;
+	forEach(
+		callbackfn: (value: InstanceDataEntryValue, key: string, parent: InstanceData) => void,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		thisArg?: any
+	): void;
+
+	get(name: INSTANCE_FILE_NAME): InstanceFile;
+	get(name: InstanceAttachmentFileName): InstanceDataEntryValue | null;
+	getAll(name: string): InstanceDataEntryValue[];
 
 	has(name: INSTANCE_FILE_NAME): true;
 	has(name: InstanceAttachmentFileName): boolean;

package/src/client/serialization/InstancePayloadOptions.ts

@@ -1,7 +1,7 @@
 export type InstancePayloadType = 'chunked' | 'monolithic';
 
 interface BaseInstancePayloadOptions<PayloadType extends InstancePayloadType> {
-	readonly payloadType?: PayloadType | undefined;
+	readonly payloadType: PayloadType;
 
 	/**
 	 * As described in the
@@ -13,11 +13,12 @@ interface BaseInstancePayloadOptions<PayloadType extends InstancePayloadType> {
 }
 
 interface ChunkedInstancePayloadOptions extends BaseInstancePayloadOptions<'chunked'> {
+	readonly payloadType: 'chunked';
 	readonly maxSize: number;
 }
 
 interface MonolithicInstancePayloadOptions extends BaseInstancePayloadOptions<'monolithic'> {
-	readonly payloadType?: 'monolithic' | undefined;
+	readonly payloadType: 'monolithic';
 	readonly maxSize?: never;
 }
 

package/src/entrypoints/FormInstance.ts

@@ -37,9 +37,10 @@ export class FormInstance<Mode extends FormInstanceInitializationMode>
 		readonly formResult: InstantiableFormResult,
 		options: FormInstanceOptions<Mode>
 	) {
-		const { mode, initialState } = options;
+		const { mode, initialState, instanceConfig } = options;
 		const config: InstanceConfig = {
-			clientStateFactory: options.instanceConfig.stateFactory ?? identity,
+			clientStateFactory: instanceConfig.stateFactory ?? identity,
+			computeAttachmentName: instanceConfig.instanceAttachments?.fileNameFactory ?? (() => null),
 		};
 		const primaryInstanceOptions: PrimaryInstanceOptions<Mode> = {
 			...options.instanceOptions,

package/src/error/UploadValueTypeError.ts

@@ -0,0 +1,13 @@
+import type { UploadDefinition } from '../client/UploadNode.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+
+type UnsupportedUploadValueType = Exclude<ValueType, 'binary'>;
+
+export class UploadValueTypeError extends XFormsSpecViolationError {
+	constructor(definition: UploadDefinition<UnsupportedUploadValueType>) {
+		const { valueType } = definition;
+
+		super(`Expected upload control to have 'binary' value type, got: ${valueType}`);
+	}
+}

package/src/instance/PrimaryInstance.ts

@@ -32,6 +32,7 @@ import type { ModelDefinition } from '../parse/model/ModelDefinition.ts';
 import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import type { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
 import { InstanceNode } from './abstract/InstanceNode.ts';
+import { InstanceAttachmentsState } from './attachments/InstanceAttachmentsState.ts';
 import type { InitialInstanceState } from './input/InitialInstanceState.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
@@ -113,12 +114,9 @@ export class PrimaryInstance<
 		EvaluationContext,
 		ClientReactiveSerializableInstance
 {
-	/**
-	 * @todo this will be populated as we introduce other initialization modes!
-	 */
-	readonly initializationMode: FormInstanceInitializationMode = 'create';
-
+	readonly initializationMode: FormInstanceInitializationMode;
 	readonly model: ModelDefinition;
+	readonly attachments: InstanceAttachmentsState;
 
 	// InstanceNode
 	protected readonly state: SharedNodeState<PrimaryInstanceStateSpec>;
@@ -169,6 +167,7 @@ export class PrimaryInstance<
 
 		this.initializationMode = mode;
 		this.model = model;
+		this.attachments = new InstanceAttachmentsState(initialState?.attachments);
 		this.instanceNode = activeInstance;
 
 		const [isAttached, setIsAttached] = createSignal(false);

package/src/instance/UploadControl.ts

@@ -0,0 +1,184 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type { TextRange } from '../client/TextRange.ts';
+import type { UploadDefinition, UploadNode, UploadNodeOptions } from '../client/UploadNode.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import type { InstanceAttachmentFileName, InstanceState } from '../client/index.ts';
+import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { UploadValueTypeError } from '../error/UploadValueTypeError.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
+import { createValueNodeInstanceState } from '../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
+import { createInstanceAttachment } from '../lib/reactivity/createInstanceAttachment.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
+import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
+import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type {
+	InstanceAttachment,
+	InstanceAttachmentRuntimeValue,
+} from './attachments/InstanceAttachment.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { InstanceAttachmentContext } from './internal-api/InstanceAttachmentContext.ts';
+import type {
+	DecodeInstanceValue,
+	InstanceValueContext,
+} from './internal-api/InstanceValueContext.ts';
+import type { ValidationContext } from './internal-api/ValidationContext.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
+
+export type AnyUploadDefinition = {
+	[V in ValueType]: UploadDefinition<V>;
+}[ValueType];
+
+type AssertUploadDefinition = (
+	definition: AnyUploadDefinition
+) => asserts definition is UploadDefinition<'binary'>;
+
+const assertUploadDefinition: AssertUploadDefinition = (definition) => {
+	const { valueType } = definition;
+
+	if (valueType !== 'binary') {
+		throw new UploadValueTypeError(definition);
+	}
+};
+
+interface UploadControlStateSpec extends DescendantNodeStateSpec<InstanceAttachmentRuntimeValue> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly children: null;
+	readonly valueOptions: null;
+	readonly value: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+	readonly instanceValue: Accessor<InstanceAttachmentFileName>;
+}
+
+export class UploadControl
+	extends DescendantNode<
+		UploadDefinition<'binary'>,
+		UploadControlStateSpec,
+		GeneralParentNode,
+		null
+	>
+	implements
+		UploadNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		InstanceAttachmentContext,
+		InstanceValueContext,
+		ValidationContext,
+		ClientReactiveSerializableValueNode
+{
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: UploadDefinition
+	): UploadControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnyUploadDefinition
+	): UploadControl {
+		assertUploadDefinition(definition);
+
+		return new this(parent, instanceNode, definition);
+	}
+
+	private readonly validation: SharedValidationState;
+	private readonly instanceAttachment: InstanceAttachment;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+	override readonly getXPathValue: () => InstanceAttachmentFileName;
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<UploadControlStateSpec>;
+	protected readonly engineState: EngineState<UploadControlStateSpec>;
+
+	// InstanceValueContext
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	// UploadNode
+	readonly nodeType = 'upload';
+	readonly valueType = 'binary';
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions: UploadNodeOptions;
+	readonly currentState: CurrentState<UploadControlStateSpec>;
+
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
+	readonly instanceState: InstanceState;
+
+	private constructor(
+		parent: GeneralParentNode,
+		override readonly instanceNode: StaticLeafElement | null,
+		definition: UploadDefinition<'binary'>
+	) {
+		super(parent, instanceNode, definition);
+
+		this.appearances = definition.bodyElement.appearances;
+		this.nodeOptions = definition.bodyElement.options;
+
+		const instanceAttachment = createInstanceAttachment(this);
+
+		this.instanceAttachment = instanceAttachment;
+		this.decodeInstanceValue = instanceAttachment.decodeInstanceValue;
+		this.getXPathValue = instanceAttachment.getInstanceValue;
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
+
+				label: createNodeLabel(this, definition),
+				hint: createFieldHint(this, definition),
+				children: null,
+				valueOptions: null,
+				value: instanceAttachment.valueState,
+				instanceValue: instanceAttachment.getInstanceValue,
+			},
+			this.instanceConfig
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+		this.validation = createValidationState(this, this.instanceConfig);
+		this.instanceState = createValueNodeInstanceState(this);
+	}
+
+	// ValidationContext
+	getViolation(): AnyViolation | null {
+		return this.validation.engineState.violation;
+	}
+
+	isBlank(): boolean {
+		return this.getXPathValue() === '';
+	}
+
+	// InstanceNode
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	// UploadNode
+	setValue(value: InstanceAttachmentRuntimeValue): Root {
+		this.instanceAttachment.setValue(value);
+
+		return this.root;
+	}
+}

package/src/instance/attachments/InstanceAttachment.ts

@@ -0,0 +1,69 @@
+import type { Accessor } from 'solid-js';
+import type { InstancePayload } from '../../client/index.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } from '../../lib/reactivity/types.ts';
+import type { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import type { DecodeInstanceValue } from '../internal-api/InstanceValueContext.ts';
+import type { InstanceAttachmentsState } from './InstanceAttachmentsState.ts';
+
+export type InstanceAttachmentFileName = string;
+export type InstanceAttachmentRuntimeValue = File | null;
+
+export interface InstanceAttachmentOptions {
+	readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+	readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+	readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+	readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+}
+
+export class InstanceAttachment {
+	/**
+	 * 1. Creates {@link InstanceAttachment | attachment state} from
+	 *    {@link InstanceAttachmentOptions}
+	 * 2. Registers that attachment state in an instance-global
+	 *    {@link InstanceAttachmentsState} entry
+	 *
+	 * This allows an instance to:
+	 *
+	 * - Produce distinct file names for each attachment
+	 * - Track all attachments so they can be serialized in an
+	 *   {@link InstancePayload}
+	 */
+	static init(
+		context: InstanceAttachmentContext,
+		options: InstanceAttachmentOptions
+	): InstanceAttachment {
+		const attachment = new this(options);
+		const { attachments } = context.rootDocument;
+
+		attachments.set(context, attachment);
+
+		return attachment;
+	}
+
+	/**
+	 * This property isn't used at runtime. It causes TypeScript to treat
+	 * {@link InstanceAttachment} as a nominal type, ensuring
+	 * {@link InstanceAttachment.init} is called to instantiate it.
+	 */
+	protected readonly _ = null;
+
+	readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+	readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+	readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+	readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+
+	private constructor(options: InstanceAttachmentOptions) {
+		this.getFileName = options.getFileName;
+		this.getInstanceValue = options.getInstanceValue;
+		this.decodeInstanceValue = options.decodeInstanceValue;
+		this.getValue = options.getValue;
+		this.setValue = options.setValue;
+		this.valueState = options.valueState;
+	}
+}

package/src/instance/attachments/InstanceAttachmentsState.ts

@@ -0,0 +1,18 @@
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { InstanceAttachmentMap } from '../input/InstanceAttachmentMap.ts';
+import type { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import type { InstanceAttachment, InstanceAttachmentRuntimeValue } from './InstanceAttachment.ts';
+
+export class InstanceAttachmentsState extends Map<InstanceAttachmentContext, InstanceAttachment> {
+	constructor(private readonly sourceAttachments: InstanceAttachmentMap | null = null) {
+		super();
+	}
+
+	getInitialFileValue(instanceNode: StaticLeafElement | null): InstanceAttachmentRuntimeValue {
+		if (instanceNode == null) {
+			return null;
+		}
+
+		return this.sourceAttachments?.get(instanceNode.value) ?? null;
+	}
+}