@embeddables/forms 0.0.5 → 0.2.1

package/dist/{form-9Tp91g6a.js → form-7wmC3G_q.js}

@@ -31,119 +31,128 @@ var ValidatorError = class extends FormsError {
 		this.name = "ValidatorError";
 	}
 };
-const DEVELOPMENT_BASE_URL = void 0;
-/**
-* Returns null when persistence cannot be configured (missing publishable key
-* or fetch). The SDK keeps the no-op default in that case.
-*/
-function resolvePersistenceConfig(config) {
-	const core = config.core;
-	const publishableKey = config.publishableKey ?? core.getPublishableKey();
-	if (!publishableKey || !isValidPublishableKey({ value: publishableKey })) return null;
-	const projectId = core.getProjectId();
-	const appUserId = core.getAppUserId();
-	if (!projectId || !appUserId) return null;
-	const fetchImpl = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
-	if (!fetchImpl) return null;
-	return {
-		core,
-		projectId,
-		appUserId,
-		publishableKey,
-		baseUrl: config.baseUrl ?? DEVELOPMENT_BASE_URL ?? "https://backend-worker.heysavvy.workers.dev",
-		fetch: fetchImpl,
-		timeoutMs: config.timeoutMs ?? 1e4
-	};
+//#endregion
+//#region src/types/form-file.ts
+function contentTypeMatchesAccept({ contentType, accept }) {
+	const normalized = contentType.split(";", 1)[0]?.trim().toLowerCase() || "";
+	return accept.some((entry) => {
+		const pattern = entry.trim().toLowerCase();
+		if (pattern.endsWith("/*")) return normalized.startsWith(pattern.slice(0, -1));
+		return normalized === pattern;
+	});
+}
+function isFormFileRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value;
+	return typeof record.file_id === "string" && typeof record.name === "string" && typeof record.content_type === "string" && typeof record.size === "number" && Number.isFinite(record.size) && (record.status === "uploading" || record.status === "done" || record.status === "error");
 }
 //#endregion
-//#region src/storage/persistence.ts
+//#region src/core/validation.ts
+/** Runtime counterpart to `FieldType`. Exhaustive by construction. */
+const FIELD_TYPE_PREDICATES = {
+	text: (value) => typeof value === "string",
+	email: (value) => typeof value === "string",
+	number: (value) => typeof value === "number",
+	boolean: (value) => typeof value === "boolean",
+	select: (value) => typeof value === "string",
+	multiselect: (value) => Array.isArray(value),
+	json: () => true,
+	file: (value) => value === null || isFormFileRef(value)
+};
+const EMAIL_PATTERN = /^[\w.!#$%&'*+/=?^`{|}~-]+@[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?(?:\.[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?)*$/;
 /**
-* The default: does nothing, never throws, and recovers nothing. With this in
-* place a form is pure local state, exactly as before the port existed.
+* Every message a single field's value earns. Empty means valid. Not generic:
+* the per-field types live at the instance boundary, and the cast down to
+* `JsonValue` happens once, in `initForm`.
 */
-function createNoopPersistence() {
-	return {
-		savePartial: () => void 0,
-		saveFields: () => void 0,
-		saveSubmission: () => void 0,
-		recoverRegistryFields: () => ({})
-	};
-}
-//#endregion
-//#region src/storage/persistence-client.ts
-const PUBLISHABLE_KEY_HEADER = "x-publishable-key";
-const hcWithType = (...args) => hc(...args);
-function withTimeout(fetchImpl, timeoutMs) {
-	return async (input, init) => {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
-		const path = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-		try {
-			return await fetchImpl(input, {
-				...init,
-				signal: controller.signal
-			});
-		} catch (error) {
-			if (error instanceof Error && error.name === "AbortError") throw new Error(`Request to ${path} timed out after ${timeoutMs}ms`, { cause: error });
-			throw new Error(`Request to ${path} failed to reach the API`, { cause: error });
-		} finally {
-			clearTimeout(timer);
+function validateValue({ field, value, values, pattern, validator }) {
+	const rules = field.validations;
+	const messages = [];
+	const isAbsent = value === void 0 || value === null;
+	const isBlank = isAbsent || value === "" || Array.isArray(value) && value.length === 0;
+	if (rules?.required === true && isBlank) messages.push(`${field.label} is required`);
+	if (isAbsent) return messages;
+	if (!FIELD_TYPE_PREDICATES[field.type](value)) messages.push(`${field.label} expects ${/^[aeiou]/.test(field.type) ? "an" : "a"} ${field.type} value`);
+	if (typeof value === "string") {
+		if (field.type === "email" && value !== "" && !EMAIL_PATTERN.test(value)) messages.push(`${field.label} must be a valid email address`);
+		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must be at least ${rules.minLength} characters`);
+		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must be at most ${rules.maxLength} characters`);
+		if (pattern && !pattern.test(value)) messages.push(`${field.label} is not in the expected format`);
+	}
+	if (Array.isArray(value)) {
+		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must have at least ${rules.minLength} items`);
+		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must have at most ${rules.maxLength} items`);
+	}
+	if (typeof value === "number") {
+		if (rules?.min !== void 0 && value < rules.min) messages.push(`${field.label} must be at least ${rules.min}`);
+		if (rules?.max !== void 0 && value > rules.max) messages.push(`${field.label} must be at most ${rules.max}`);
+	}
+	if (field.type === "select" || field.type === "multiselect") {
+		const options = field.options;
+		if (options) {
+			const allowed = new Set(options.map((option) => option.value));
+			if (field.type === "select" && typeof value === "string" && !allowed.has(value)) messages.push(`${field.label} must be one of the allowed options`);
+			if (field.type === "multiselect" && Array.isArray(value)) {
+				if (value.some((entry) => typeof entry !== "string" || !allowed.has(entry))) messages.push(`${field.label} has values that are not allowed options`);
+			}
 		}
-	};
-}
-async function rpcCall(fn) {
-	const res = await fn();
-	if (!res.ok) {
-		const problem = await res.json().catch(() => null);
-		const message = problem?.detail ?? problem?.title ?? `forms persistence failed: ${res.status}`;
-		throw new Error(message);
 	}
-	return res.json();
-}
-function createApiPersistence(config) {
-	const root = config.baseUrl.replace(/\/+$/, "");
-	const rpc = hcWithType(`${root}/forms`, {
-		fetch: withTimeout(config.fetch, config.timeoutMs),
-		headers: { [PUBLISHABLE_KEY_HEADER]: config.publishableKey }
+	if (rules?.oneOf) {
+		const encoded = canonicalize(value);
+		if (!rules.oneOf.some((option) => canonicalize(option) === encoded)) messages.push(`${field.label} must be one of the allowed options`);
+	}
+	if (field.type === "file" && isFormFileRef(value)) {
+		if (value.status !== "done") messages.push(`${field.label} upload is not complete`);
+		if (rules?.maxSize !== void 0 && value.size > rules.maxSize) messages.push(`${field.label} must be at most ${rules.maxSize} bytes`);
+		if (rules?.accept !== void 0 && !contentTypeMatchesAccept({
+			contentType: value.content_type,
+			accept: rules.accept
+		})) messages.push(`${field.label} must be one of the allowed file types`);
+	}
+	if (!validator || messages.length > 0) return messages;
+	return normalizeValidatorResult({
+		result: validator({
+			value,
+			values
+		}),
+		field
 	});
-	return {
-		savePartial({ formKey, values }) {
-			return rpcCall(() => rpc.v1.public.sessions.$post({ json: {
-				project_id: config.projectId,
-				app_user_id: config.appUserId,
-				form_id: formKey,
-				data: values
-			} })).then(() => void 0);
-		},
-		saveFields: () => void 0,
-		saveSubmission({ formKey, values }) {
-			return rpcCall(() => rpc.v1.public.submissions.$post({ json: {
-				project_id: config.projectId,
-				app_user_id: config.appUserId,
-				form_id: formKey,
-				values
-			} })).then(() => void 0);
-		},
-		recoverRegistryFields: () => ({})
-	};
 }
-function resolveDefaultPersistence(config) {
-	const resolved = resolvePersistenceConfig(config);
-	if (!resolved) return createNoopPersistence();
-	return createApiPersistence(resolved);
+function normalizeValidatorResult({ result, field }) {
+	if (isThenable(result)) throw new ValidatorError(`Validator for "${field.key}" returned a promise; custom validators must be synchronous`);
+	if (result === null || result === void 0) return [];
+	if (typeof result === "string") return [result];
+	if (Array.isArray(result)) return result.filter((entry) => typeof entry === "string");
+	throw new ValidatorError(`Validator for "${field.key}" returned ${typeof result}; expected a string, an array of strings, or null`);
+}
+function isThenable(value) {
+	return typeof value?.then === "function";
+}
+/**
+* JSON encoding with object keys sorted at every depth, so two values compare
+* by content rather than by insertion order.
+*/
+function canonicalize(value) {
+	const walk = (input) => {
+		if (Array.isArray(input)) return input.map(walk);
+		if (input !== null && typeof input === "object") return Object.fromEntries(Object.entries(input).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, item]) => [key, walk(item)]));
+		return input;
+	};
+	return JSON.stringify(walk(value));
 }
 //#endregion
 //#region src/storage/storage.ts
 /** Every form on the origin shares this one entry, indexed by form ID. */
 const FORM_DATA_KEY = "EMBEDDABLES-FORM-DATA";
-const FIELD_TYPES$1 = [
+const FIELD_TYPES$2 = [
 	"text",
 	"email",
 	"number",
 	"boolean",
 	"select",
 	"multiselect",
-	"json"
+	"json",
+	"file"
 ];
 const LIVE_DOCUMENTS = /* @__PURE__ */ new WeakMap();
 function readDocumentFromStorage({ storage }) {
@@ -151,7 +160,7 @@ function readDocumentFromStorage({ storage }) {
 		const raw = storage.getItem(FORM_DATA_KEY);
 		if (raw === null) return {};
 		const parsed = JSON.parse(raw);
-		if (!isObjectLike$1(parsed)) return {};
+		if (!isObjectLike$2(parsed)) return {};
 		return parsed;
 	} catch {
 		return {};
@@ -178,7 +187,7 @@ function resolveStorage({ storage }) {
 		candidate.getItem(FORM_DATA_KEY);
 		return candidate;
 	} catch {
-		return createMemoryStorage();
+		return createMemoryFormsStorage();
 	}
 }
 /**
@@ -186,7 +195,7 @@ function resolveStorage({ storage }) {
 * whose real storage started throwing mid-session.
 */
 function degradeToMemory({ storage }) {
-	const shim = createMemoryStorage();
+	const shim = createMemoryFormsStorage();
 	const snapshot = { ...LIVE_DOCUMENTS.get(storage) ?? readDocumentFromStorage({ storage }) };
 	shim.setItem(FORM_DATA_KEY, JSON.stringify(snapshot));
 	LIVE_DOCUMENTS.set(shim, snapshot);
@@ -194,18 +203,18 @@ function degradeToMemory({ storage }) {
 }
 function readFields({ storage, formKey, fieldDefinitions }) {
 	const bag = loadDocument({ storage })[formKey];
-	if (!isObjectLike$1(bag)) return {};
+	if (!isObjectLike$2(bag)) return {};
 	const declared = new Set(fieldDefinitions.map((field) => field.key));
 	const values = {};
 	for (const [key, entry] of Object.entries(bag)) {
 		if (!declared.has(key)) continue;
-		if (isStoredField(entry)) values[key] = entry.value;
+		if (isStoredField$1(entry)) values[key] = entry.value;
 	}
 	return values;
 }
 function writeFields({ storage, formKey, fields, fieldDefinitions }) {
 	const current = loadDocument({ storage });
-	const currentForm = isObjectLike$1(current[formKey]) ? current[formKey] : {};
+	const currentForm = isObjectLike$2(current[formKey]) ? current[formKey] : {};
 	const declaredKeys = new Set(fieldDefinitions.map((field) => field.key));
 	const nextForm = {};
 	for (const [key, entry] of Object.entries(currentForm)) if (!declaredKeys.has(key)) nextForm[key] = entry;
@@ -250,7 +259,8 @@ function isSerializable({ value }) {
 		return false;
 	}
 }
-function createMemoryStorage() {
+/** In-memory storage for server-side form init and tests that inject a store. */
+function createMemoryFormsStorage() {
 	const entries = /* @__PURE__ */ new Map();
 	return {
 		getItem: (key) => entries.get(key) ?? null,
@@ -262,6 +272,47 @@ function createMemoryStorage() {
 		}
 	};
 }
+function isObjectLike$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStoredField$1(value) {
+	if (!isObjectLike$2(value) || !Object.hasOwn(value, "value")) return false;
+	if (!isSerializable({ value: value["value"] })) return false;
+	if (typeof value["type"] !== "string" || !FIELD_TYPES$2.includes(value["type"]) || typeof value["label"] !== "string") return false;
+	if (value["registryId"] !== void 0 && typeof value["registryId"] !== "string") return false;
+	if (value["protocolFieldId"] !== void 0 && typeof value["protocolFieldId"] !== "string") return false;
+	return true;
+}
+//#endregion
+//#region src/storage/cookie-form-data.ts
+const FIELD_TYPES$1 = [
+	"text",
+	"email",
+	"number",
+	"boolean",
+	"select",
+	"multiselect",
+	"json"
+];
+function formatFormCookieDataKey({ projectId, formId }) {
+	return `EMBEDDABLES--${projectId}--COOKIES-FORM-DATA--${formId}`;
+}
+function buildCookiePayloadFromBag({ bag, fieldDefinitions }) {
+	const payload = {};
+	for (const field of fieldDefinitions) {
+		if (field.includeInCookies !== true) continue;
+		const value = bag[field.key];
+		if (value === void 0) continue;
+		payload[field.key] = {
+			value,
+			type: field.type,
+			label: field.label,
+			...field.registryId === void 0 ? {} : { registryId: field.registryId },
+			...field.protocolFieldId === void 0 ? {} : { protocolFieldId: field.protocolFieldId }
+		};
+	}
+	return payload;
+}
 function isObjectLike$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -273,6 +324,265 @@ function isStoredField(value) {
 	if (value["protocolFieldId"] !== void 0 && typeof value["protocolFieldId"] !== "string") return false;
 	return true;
 }
+function entryMatchesFieldDefinition(entry, field) {
+	if (entry.type !== field.type || entry.label !== field.label) return false;
+	if ((entry.registryId ?? void 0) !== (field.registryId ?? void 0)) return false;
+	if ((entry.protocolFieldId ?? void 0) !== (field.protocolFieldId ?? void 0)) return false;
+	return FIELD_TYPE_PREDICATES[field.type](entry.value);
+}
+function serializeBrowserCookie(key, value) {
+	const locationRef = globalThis.location;
+	const parts = [
+		`${key}=${encodeURIComponent(value)}`,
+		"Path=/",
+		"SameSite=Lax"
+	];
+	if (locationRef?.protocol === "https:") parts.push("Secure");
+	return parts.join("; ");
+}
+function writeBrowserCookie(key, value) {
+	const documentRef = globalThis.document;
+	if (!documentRef) return;
+	try {
+		documentRef.cookie = serializeBrowserCookie(key, value);
+	} catch {}
+}
+function clearBrowserCookie(key) {
+	const documentRef = globalThis.document;
+	if (!documentRef) return;
+	try {
+		const locationRef = globalThis.location;
+		const parts = [
+			`${key}=`,
+			"Path=/",
+			"Max-Age=0",
+			"SameSite=Lax"
+		];
+		if (locationRef?.protocol === "https:") parts.push("Secure");
+		documentRef.cookie = parts.join("; ");
+	} catch {}
+}
+function writeFormCookieData({ projectId, formId, bag, fieldDefinitions }) {
+	try {
+		const payload = buildCookiePayloadFromBag({
+			bag,
+			fieldDefinitions
+		});
+		writeBrowserCookie(formatFormCookieDataKey({
+			projectId,
+			formId
+		}), JSON.stringify(payload));
+	} catch {}
+}
+function clearFormCookieData({ projectId, formId }) {
+	try {
+		clearBrowserCookie(formatFormCookieDataKey({
+			projectId,
+			formId
+		}));
+	} catch {}
+}
+function readFormCookieStoredForm({ projectId, formId, getCookie, fieldDefinitions }) {
+	try {
+		const raw = getCookie(formatFormCookieDataKey({
+			projectId,
+			formId
+		}));
+		if (raw === null || raw === "") return {};
+		const parsed = JSON.parse(decodeURIComponent(raw));
+		if (!isObjectLike$1(parsed)) return {};
+		const optedInFields = new Map(fieldDefinitions.filter((field) => field.includeInCookies === true).map((field) => [field.key, field]));
+		const storedForm = {};
+		for (const [key, entry] of Object.entries(parsed)) {
+			const field = optedInFields.get(key);
+			if (!field || !isStoredField(entry)) continue;
+			if (!entryMatchesFieldDefinition(entry, field)) continue;
+			storedForm[key] = entry;
+		}
+		return storedForm;
+	} catch {
+		return {};
+	}
+}
+function seedServerFormsStorageFromCookies({ storage, projectId, formIds, getFormSchema, getCookie }) {
+	const document = {};
+	for (const formId of formIds) {
+		const rawSchema = getFormSchema(formId);
+		if (typeof rawSchema !== "object" || rawSchema === null) continue;
+		const storedForm = readFormCookieStoredForm({
+			projectId,
+			formId,
+			getCookie,
+			fieldDefinitions: rawSchema.fields
+		});
+		if (Object.keys(storedForm).length === 0) continue;
+		document[formId] = storedForm;
+	}
+	if (Object.keys(document).length === 0) return;
+	storage.setItem(FORM_DATA_KEY, JSON.stringify(document));
+}
+const DEVELOPMENT_BASE_URL = void 0;
+/**
+* Returns null when persistence cannot be configured (missing publishable key
+* or fetch). The SDK keeps the no-op default in that case.
+*/
+function resolvePersistenceConfig(config) {
+	const core = config.core;
+	const publishableKey = config.publishableKey ?? core.getPublishableKey();
+	if (!publishableKey || !isValidPublishableKey({ value: publishableKey })) return null;
+	const projectId = core.getProjectId();
+	const appUserId = core.getAppUserId();
+	if (!projectId || !appUserId) return null;
+	const fetchImpl = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
+	if (!fetchImpl) return null;
+	return {
+		core,
+		projectId,
+		appUserId,
+		publishableKey,
+		baseUrl: config.baseUrl ?? DEVELOPMENT_BASE_URL ?? "https://backend-worker.heysavvy.workers.dev",
+		fetch: fetchImpl,
+		timeoutMs: config.timeoutMs ?? 1e4
+	};
+}
+//#endregion
+//#region src/storage/persistence.ts
+/**
+* The default: does nothing, never throws, and recovers nothing. With this in
+* place a form is pure local state, exactly as before the port existed.
+*/
+function createNoopPersistence() {
+	return {
+		savePartial: () => void 0,
+		saveFields: () => void 0,
+		saveSubmission: () => void 0,
+		recoverRegistryFields: () => ({})
+	};
+}
+//#endregion
+//#region src/storage/persistence-client.ts
+const PUBLISHABLE_KEY_HEADER$1 = "x-publishable-key";
+const hcWithType = (...args) => hc(...args);
+function withTimeout(fetchImpl, timeoutMs) {
+	return async (input, init) => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const path = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+		try {
+			return await fetchImpl(input, {
+				...init,
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw new Error(`Request to ${path} timed out after ${timeoutMs}ms`, { cause: error });
+			throw new Error(`Request to ${path} failed to reach the API`, { cause: error });
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+async function rpcCall(fn) {
+	const res = await fn();
+	if (!res.ok) {
+		const problem = await res.json().catch(() => null);
+		const message = problem?.detail ?? problem?.title ?? `forms persistence failed: ${res.status}`;
+		throw new Error(message);
+	}
+	return res.json();
+}
+function createApiPersistence(config) {
+	const root = config.baseUrl.replace(/\/+$/, "");
+	const rpc = hcWithType(`${root}/forms`, {
+		fetch: withTimeout(config.fetch, config.timeoutMs),
+		headers: { [PUBLISHABLE_KEY_HEADER$1]: config.publishableKey }
+	});
+	return {
+		savePartial({ formKey, values }) {
+			return rpcCall(() => rpc.v1.public.sessions.$post({ json: {
+				project_id: config.projectId,
+				app_user_id: config.appUserId,
+				form_id: formKey,
+				data: values
+			} })).then(() => void 0);
+		},
+		saveFields: () => void 0,
+		saveSubmission({ formKey, values }) {
+			return rpcCall(() => rpc.v1.public.submissions.$post({ json: {
+				project_id: config.projectId,
+				app_user_id: config.appUserId,
+				form_id: formKey,
+				values
+			} })).then(() => void 0);
+		},
+		recoverRegistryFields: () => ({})
+	};
+}
+function resolveDefaultPersistence(config) {
+	const resolved = resolvePersistenceConfig(config);
+	if (!resolved) return createNoopPersistence();
+	return createApiPersistence(resolved);
+}
+//#endregion
+//#region src/storage/upload-client.ts
+const PUBLISHABLE_KEY_HEADER = "x-publishable-key";
+function mapUploadErrorMessage(problem, status) {
+	const code = problem?.code;
+	if (code === "validation.file_too_large") return problem?.detail ?? "Maximum upload size is 25 MiB.";
+	if (code === "validation.unsupported_content_type") return problem?.detail ?? "Unsupported file type.";
+	if (code === "validation.upload_failed") return problem?.detail ?? "Upload could not be completed.";
+	if (code === "service.form_uploads_not_configured") return problem?.detail ?? "File uploads are not configured for this project.";
+	if (code === "validation.failed") return problem?.detail ?? "Upload metadata is invalid.";
+	return problem?.detail ?? problem?.title ?? `File upload failed (${status}).`;
+}
+function uploadResultToFormFileRef(result) {
+	return {
+		file_id: result.file_id,
+		name: result.name,
+		content_type: result.content_type,
+		size: result.size,
+		status: "done",
+		uploaded_at: result.uploaded_at
+	};
+}
+function toUploadFetchError(error, path, timeoutMs) {
+	if (error instanceof FormsError) return error;
+	if (error instanceof Error && error.name === "AbortError") return new FormsError(`Request to ${path} timed out after ${timeoutMs}ms`, { cause: error });
+	return new FormsError(`Request to ${path} failed to reach the API`, { cause: error });
+}
+function toUploadDecodeError(error, path) {
+	return new FormsError(`Upload response from ${path} could not be decoded`, { cause: error });
+}
+async function uploadFormFile(config, input) {
+	const url = `${config.baseUrl.replace(/\/+$/, "")}/forms/v1/public/uploads`;
+	const formData = new FormData();
+	formData.append("project_id", config.projectId);
+	formData.append("app_user_id", config.appUserId);
+	formData.append("form_id", input.formId);
+	formData.append("field_key", input.fieldKey);
+	const fileName = input.fileName ?? (typeof File !== "undefined" && input.file instanceof File ? input.file.name : "upload");
+	formData.append("file", input.file, fileName);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+	try {
+		const res = await config.fetch(url, {
+			method: "POST",
+			headers: { [PUBLISHABLE_KEY_HEADER]: config.publishableKey },
+			body: formData,
+			signal: controller.signal
+		});
+		clearTimeout(timer);
+		if (!res.ok) throw new FormsError(mapUploadErrorMessage(await res.json().catch(() => null), res.status));
+		try {
+			return uploadResultToFormFileRef(await res.json());
+		} catch (error) {
+			throw toUploadDecodeError(error, url);
+		}
+	} catch (error) {
+		throw toUploadFetchError(error, url, config.timeoutMs);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 //#endregion
 //#region src/core/analytics.ts
 /** The ingest bound on a `data:updated` entry's `value`. */
@@ -288,10 +598,11 @@ function mapFieldUpdatedType(type) {
 * raw `field_value`; only the batch event caps and stringifies for ingest.
 */
 function formatFieldValue({ value }) {
+	if (value === void 0) return "";
 	return (typeof value === "string" ? value : JSON.stringify(value)).slice(0, MAX_VALUE_LENGTH);
 }
 /** One event carrying every key in one `.set()` call. */
-function buildDataUpdatedEvent({ fields, patch }) {
+function buildDataUpdatedEvent({ fields, patch, formId }) {
 	const byKey = new Map(fields.map((field) => [field.key, field]));
 	return {
 		event_name: "data:updated",
@@ -304,11 +615,12 @@ function buildDataUpdatedEvent({ fields, patch }) {
 				}),
 				label: (field?.label ?? key).slice(0, MAX_LABEL_LENGTH)
 			}];
-		}))
+		})),
+		form_id: formId
 	};
 }
 /** One `field:updated` per changed key, emitted alongside `data:updated`. */
-function buildFieldUpdatedEvents({ fields, patch }) {
+function buildFieldUpdatedEvents({ fields, patch, formId }) {
 	const byKey = new Map(fields.map((field) => [field.key, field]));
 	return Object.entries(patch).map(([key, value]) => {
 		const field = byKey.get(key);
@@ -316,14 +628,33 @@ function buildFieldUpdatedEvents({ fields, patch }) {
 			event_name: "field:updated",
 			field_key: key,
 			field_type: mapFieldUpdatedType(field?.type ?? "text"),
-			field_value: value
+			form_id: formId
 		};
+		if (value !== void 0) event.field_value = value;
 		if (field?.registryId !== void 0) event.registry_field_id = field.registryId;
 		if (field?.protocolFieldId !== void 0) event.protocol_field_id = field.protocolFieldId;
 		return event;
 	});
 }
 //#endregion
+//#region src/core/options.ts
+/**
+* The array a `multiselect` patch should actually store, given what it added
+* relative to the previous value. An added exclusive option wins outright; an
+* added regular option evicts every exclusive value; a patch that only removed
+* values passes through.
+*/
+function normalizeExclusiveSelection({ next, previous, options }) {
+	const exclusive = new Set(options.filter((option) => option.exclusive === true).map((option) => option.value));
+	if (exclusive.size === 0) return next;
+	const previousValues = new Set(previous);
+	const added = next.filter((entry) => !previousValues.has(entry));
+	const addedExclusive = added.filter((entry) => exclusive.has(entry));
+	if (addedExclusive.length > 0) return [addedExclusive[addedExclusive.length - 1]];
+	if (added.length > 0) return next.filter((entry) => !exclusive.has(entry));
+	return next;
+}
+//#endregion
 //#region src/core/resolve.ts
 const FIELD_TYPES = [
 	"text",
@@ -332,7 +663,8 @@ const FIELD_TYPES = [
 	"boolean",
 	"select",
 	"multiselect",
-	"json"
+	"json",
+	"file"
 ];
 const VALIDATION_RULES = [
 	"required",
@@ -341,21 +673,31 @@ const VALIDATION_RULES = [
 	"min",
 	"max",
 	"pattern",
-	"patternFlags",
 	"oneOf",
+	"accept",
+	"maxSize",
 	"custom"
 ];
 const NUMERIC_RULES = [
 	"minLength",
 	"maxLength",
 	"min",
-	"max"
+	"max",
+	"maxSize"
+];
+const FILE_ONLY_RULES = ["accept", "maxSize"];
+const OPTION_KEYS = [
+	"value",
+	"label",
+	"exclusive"
 ];
+/** The two field types whose choices are declared through a field-level `options`. */
+const OPTION_FIELD_TYPES = ["select", "multiselect"];
 /** The ingest `z.string().max(128)` bound on a `data:updated` key. */
 const MAX_FIELD_KEY_LENGTH = 128;
 /** The ingest `z.string().max(128)` bound on a `form:submitted` key. */
 const MAX_FORM_KEY_LENGTH = 128;
-const VALID_PATTERN_FLAGS = /^[dgimsuvy]*$/;
+const INLINE_PATTERN_FLAGS = /^\(\?([dgimsuvy]+)\)/;
 const RESOLVED_SCHEMAS = /* @__PURE__ */ new WeakMap();
 function resolveForm({ schema }) {
 	const memoized = RESOLVED_SCHEMAS.get(schema);
@@ -411,25 +753,56 @@ function validateField({ field, path, seenKeys, patterns }) {
 	if (registryId !== void 0 && typeof registryId !== "string") throw new SchemaError(`${path}.registryId: must be a string`);
 	const protocolFieldId = field["protocolFieldId"];
 	if (protocolFieldId !== void 0 && typeof protocolFieldId !== "string") throw new SchemaError(`${path}.protocolFieldId: must be a string`);
+	const includeInCookies = field["includeInCookies"];
+	if (includeInCookies !== void 0 && typeof includeInCookies !== "boolean") throw new SchemaError(`${path}.includeInCookies: must be a boolean`);
+	validateOptions({
+		field,
+		type,
+		path
+	});
 	const validations = field["validations"];
 	if (validations === void 0) return;
 	validateValidations({
 		validations,
+		type,
 		path: `${path}.validations`
 	});
 	if (!isObjectLike(validations)) return;
 	const pattern = validations["pattern"];
 	if (typeof pattern !== "string") return;
-	const flags = validations["patternFlags"];
 	patterns.set(key, compilePattern({
 		pattern,
-		flags: typeof flags === "string" ? flags : "",
 		path: `${path}.validations.pattern`
 	}));
 }
-function validateValidations({ validations, path }) {
+function validateOptions({ field, type, path }) {
+	const options = field["options"];
+	if (options === void 0) return;
+	if (!OPTION_FIELD_TYPES.includes(type)) throw new SchemaError(`${path}.options: only a select or multiselect field may declare options`);
+	if (!(Array.isArray(options) && options.length > 0)) throw new SchemaError(`${path}.options: must be a non-empty array`);
+	const entries = options;
+	const seenValues = /* @__PURE__ */ new Set();
+	entries.forEach((option, index) => {
+		const at = `${path}.options[${index}]`;
+		if (!isObjectLike(option)) throw new SchemaError(`${at}: must be an object`);
+		for (const optionKey of Object.keys(option)) if (!OPTION_KEYS.includes(optionKey)) throw new SchemaError(`${at}.${optionKey}: unknown option key; expected one of ${OPTION_KEYS.join(", ")}`);
+		const value = option["value"];
+		if (typeof value !== "string" || value.trim() === "") throw new SchemaError(`${at}.value: must be a non-empty string`);
+		const label = option["label"];
+		if (label !== void 0 && typeof label !== "string") throw new SchemaError(`${at}.label: must be a string`);
+		const exclusive = option["exclusive"];
+		if (exclusive !== void 0 && typeof exclusive !== "boolean") throw new SchemaError(`${at}.exclusive: must be a boolean`);
+		if (exclusive === true && type === "select") throw new SchemaError(`${at}.exclusive: only a multiselect field may declare an exclusive option`);
+		if (seenValues.has(value)) throw new SchemaError(`${at}.value: duplicate option value "${value}" on this field`);
+		seenValues.add(value);
+	});
+}
+function validateValidations({ validations, type, path }) {
 	if (!isObjectLike(validations)) throw new SchemaError(`${path}: must be an object`);
-	for (const rule of Object.keys(validations)) if (!VALIDATION_RULES.includes(rule)) throw new SchemaError(`${path}.${rule}: unknown validation rule; expected one of ${VALIDATION_RULES.join(", ")}`);
+	for (const rule of Object.keys(validations)) {
+		if (!VALIDATION_RULES.includes(rule)) throw new SchemaError(`${path}.${rule}: unknown validation rule; expected one of ${VALIDATION_RULES.join(", ")}`);
+		if (type !== "file" && FILE_ONLY_RULES.includes(rule)) throw new SchemaError(`${path}.${rule}: is only valid for file fields`);
+	}
 	const required = validations["required"];
 	if (required !== void 0 && typeof required !== "boolean") throw new SchemaError(`${path}.required: must be a boolean`);
 	for (const rule of NUMERIC_RULES) {
@@ -443,17 +816,23 @@ function validateValidations({ validations, path }) {
 	const max = validations["max"];
 	if (typeof min === "number" && typeof max === "number" && max < min) throw new SchemaError(`${path}.max: must be greater than or equal to min`);
 	const oneOf = validations["oneOf"];
+	if (oneOf !== void 0 && OPTION_FIELD_TYPES.includes(type)) throw new SchemaError(`${path}.oneOf: not allowed on a ${type} field; declare choices through the field's options instead`);
 	if (oneOf !== void 0 && !(Array.isArray(oneOf) && oneOf.length > 0)) throw new SchemaError(`${path}.oneOf: must be a non-empty array`);
+	const accept = validations["accept"];
+	if (accept !== void 0 && !(Array.isArray(accept) && accept.length > 0 && accept.every((entry) => typeof entry === "string" && entry.trim() !== ""))) throw new SchemaError(`${path}.accept: must be a non-empty array of strings`);
+	const maxSize = validations["maxSize"];
+	if (maxSize !== void 0 && !(typeof maxSize === "number" && Number.isFinite(maxSize) && maxSize > 0)) throw new SchemaError(`${path}.maxSize: must be a positive finite number`);
 	const pattern = validations["pattern"];
 	if (pattern !== void 0 && typeof pattern !== "string") throw new SchemaError(`${path}.pattern: must be a string`);
-	const patternFlags = validations["patternFlags"];
-	if (patternFlags !== void 0 && !(typeof patternFlags === "string" && VALID_PATTERN_FLAGS.test(patternFlags))) throw new SchemaError(`${path}.patternFlags: must contain only the characters dgimsuvy`);
 	const custom = validations["custom"];
 	if (custom !== void 0 && typeof custom !== "function") throw new SchemaError(`${path}.custom: must be a function (received ${typeof custom})`);
 }
-function compilePattern({ pattern, flags, path }) {
+function compilePattern({ pattern, path }) {
+	const prefix = INLINE_PATTERN_FLAGS.exec(pattern);
+	const source = prefix ? pattern.slice(prefix[0].length) : pattern;
+	const flags = prefix?.[1] ?? "";
 	try {
-		return new RegExp(pattern, flags.replace(/[gy]/g, ""));
+		return new RegExp(source, flags.replace(/[gy]/g, ""));
 	} catch (error) {
 		throw new SchemaError(`${path}: invalid pattern — ${errorMessage(error)}`, { cause: error });
 	}
@@ -576,81 +955,6 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
-//#region src/core/validation.ts
-/** Runtime counterpart to `FieldType`. Exhaustive by construction. */
-const FIELD_TYPE_PREDICATES = {
-	text: (value) => typeof value === "string",
-	email: (value) => typeof value === "string",
-	number: (value) => typeof value === "number",
-	boolean: (value) => typeof value === "boolean",
-	select: (value) => typeof value === "string",
-	multiselect: (value) => Array.isArray(value),
-	json: () => true
-};
-const EMAIL_PATTERN = /^[\w.!#$%&'*+/=?^`{|}~-]+@[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?(?:\.[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?)*$/;
-/**
-* Every message a single field's value earns. Empty means valid. Not generic:
-* the per-field types live at the instance boundary, and the cast down to
-* `JsonValue` happens once, in `initForm`.
-*/
-function validateValue({ field, value, values, pattern, validator }) {
-	const rules = field.validations;
-	const messages = [];
-	const isAbsent = value === void 0 || value === null;
-	const isBlank = isAbsent || value === "" || Array.isArray(value) && value.length === 0;
-	if (rules?.required === true && isBlank) messages.push(`${field.label} is required`);
-	if (isAbsent) return messages;
-	if (!FIELD_TYPE_PREDICATES[field.type](value)) messages.push(`${field.label} expects ${/^[aeiou]/.test(field.type) ? "an" : "a"} ${field.type} value`);
-	if (typeof value === "string") {
-		if (field.type === "email" && value !== "" && !EMAIL_PATTERN.test(value)) messages.push(`${field.label} must be a valid email address`);
-		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must be at least ${rules.minLength} characters`);
-		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must be at most ${rules.maxLength} characters`);
-		if (pattern && !pattern.test(value)) messages.push(`${field.label} is not in the expected format`);
-	}
-	if (Array.isArray(value)) {
-		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must have at least ${rules.minLength} items`);
-		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must have at most ${rules.maxLength} items`);
-	}
-	if (typeof value === "number") {
-		if (rules?.min !== void 0 && value < rules.min) messages.push(`${field.label} must be at least ${rules.min}`);
-		if (rules?.max !== void 0 && value > rules.max) messages.push(`${field.label} must be at most ${rules.max}`);
-	}
-	if (rules?.oneOf) {
-		const encoded = canonicalize(value);
-		if (!rules.oneOf.some((option) => canonicalize(option) === encoded)) messages.push(`${field.label} must be one of the allowed options`);
-	}
-	if (!validator || messages.length > 0) return messages;
-	return normalizeValidatorResult({
-		result: validator({
-			value,
-			values
-		}),
-		field
-	});
-}
-function normalizeValidatorResult({ result, field }) {
-	if (isThenable(result)) throw new ValidatorError(`Validator for "${field.key}" returned a promise; custom validators must be synchronous`);
-	if (result === null || result === void 0) return [];
-	if (typeof result === "string") return [result];
-	if (Array.isArray(result)) return result.filter((entry) => typeof entry === "string");
-	throw new ValidatorError(`Validator for "${field.key}" returned ${typeof result}; expected a string, an array of strings, or null`);
-}
-function isThenable(value) {
-	return typeof value?.then === "function";
-}
-/**
-* JSON encoding with object keys sorted at every depth, so two values compare
-* by content rather than by insertion order.
-*/
-function canonicalize(value) {
-	const walk = (input) => {
-		if (Array.isArray(input)) return input.map(walk);
-		if (input !== null && typeof input === "object") return Object.fromEntries(Object.entries(input).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, item]) => [key, walk(item)]));
-		return input;
-	};
-	return JSON.stringify(walk(value));
-}
-//#endregion
 //#region src/core/form.ts
 const REQUIRED_CORE_METHODS = [
 	"getAppUserId",
@@ -685,41 +989,117 @@ function mergeCustomValidations({ schema, customValidations }) {
 	};
 }
 /**
-* Validates the core instance and the schema map once, then returns a client
-* whose `getForm` builds each form by id.
+* Validates the core instance and registered form schemas once, then returns a
+* client whose `getForm` builds each form by id.
 */
 function initForms(options) {
 	return createFormsClient(options);
 }
-function createFormsClient({ core, schemas, analyticsInstance, baseUrl, storage, persistence }) {
-	if (!hasRequiredCoreMethods(core)) throw new FormsError("initForms requires an initialized Embeddables core instance.");
-	if (typeof schemas !== "object" || schemas === null) throw new SchemaError("initForms requires a schemas map keyed by form id.");
-	for (const [formId, schema] of Object.entries(schemas)) {
-		if (typeof schema !== "object" || schema === null) throw new SchemaError(`schemas["${formId}"]: must be a form schema object`);
-		if (typeof schema.id === "string" && schema.id !== "" && schema.id !== formId) throw new SchemaError(`schemas["${formId}"]: schema.id is "${String(schema.id)}" — it must equal its map key`);
+const REQUIRED_CORE_FORM_METHODS = ["getFormIds", "getFormSchema"];
+function hasCoreFormSchemaMethods(value) {
+	return REQUIRED_CORE_FORM_METHODS.every((method) => typeof value[method] === "function");
+}
+function toFormSchema(value, formId) {
+	if (typeof value !== "object" || value === null) throw new SchemaError(`Registered form "${formId}": schema must be an object.`);
+	const schema = value;
+	if (typeof schema.id !== "string" || schema.id === "") throw new SchemaError(`Registered form "${formId}": schema.id must be a non-empty string.`);
+	if (schema.id !== formId) throw new SchemaError(`Registered form "${formId}": schema id must match map key.`);
+	return schema;
+}
+function indexOverrideEntries({ entries, label, valueKey }) {
+	if (entries === void 0) return /* @__PURE__ */ new Map();
+	const byFormId = /* @__PURE__ */ new Map();
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		if (typeof entry !== "object" || entry === null) throw new SchemaError(`${label}[${index}]: must be an object.`);
+		const { formId } = entry;
+		if (typeof formId !== "string" || formId === "") throw new SchemaError(`${label}[${index}].formId: must be a non-empty string.`);
+		const value = entry[valueKey];
+		if (value === void 0) throw new SchemaError(`${label}[${index}].${String(valueKey)}: is required.`);
+		if (byFormId.has(formId)) throw new SchemaError(`${label}: duplicate form id "${formId}".`);
+		byFormId.set(formId, value);
+	}
+	return byFormId;
+}
+function resolveInitConfig({ core, customValidations, serverFormData }) {
+	if (!hasCoreFormSchemaMethods(core)) throw new FormsError("initForms requires a Core instance with registered form schemas.");
+	const formIds = core.getFormIds();
+	if (formIds.length === 0) throw new FormsError("initForms requires at least one form schema registered on Core.");
+	const customByFormId = indexOverrideEntries({
+		entries: customValidations,
+		label: "customValidations",
+		valueKey: "customValidations"
+	});
+	const serverDataByFormId = indexOverrideEntries({
+		entries: serverFormData,
+		label: "serverFormData",
+		valueKey: "serverFormData"
+	});
+	const registeredIds = new Set(formIds);
+	for (const formId of customByFormId.keys()) if (!registeredIds.has(formId)) throw new SchemaError(`customValidations: unknown form id "${formId}".`);
+	for (const formId of serverDataByFormId.keys()) if (!registeredIds.has(formId)) throw new SchemaError(`serverFormData: unknown form id "${formId}".`);
+	const registry = /* @__PURE__ */ new Map();
+	for (const formId of formIds) {
+		const schema = toFormSchema(core.getFormSchema(formId), formId);
+		const entryCustomValidations = customByFormId.get(formId);
+		const entryServerFormData = serverDataByFormId.get(formId);
+		mergeCustomValidations({
+			schema,
+			customValidations: entryCustomValidations
+		});
+		registry.set(formId, {
+			schema,
+			customValidations: entryCustomValidations,
+			serverFormData: entryServerFormData
+		});
 	}
+	return registry;
+}
+function createFormsClient({ core, customValidations, serverFormData, analyticsInstance, baseUrl, fetch: fetchImpl, storage, persistence }) {
+	if (!hasRequiredCoreMethods(core)) throw new FormsError("initForms requires an initialized Embeddables core instance.");
+	const registry = resolveInitConfig({
+		core,
+		customValidations,
+		serverFormData
+	});
+	const uploadConfig = resolvePersistenceConfig({
+		core,
+		baseUrl,
+		fetch: fetchImpl
+	});
 	const resolvedPersistence = persistence ?? resolveDefaultPersistence({
 		core,
-		baseUrl
+		baseUrl,
+		fetch: fetchImpl
 	});
 	const instances = /* @__PURE__ */ new Map();
-	return { getForm: ({ formId, customValidations }) => {
+	return { getForm({ formId }) {
 		const existing = instances.get(formId);
 		if (existing !== void 0) return existing;
-		const schema = schemas[formId];
-		if (schema === void 0) throw new FormsError(`Unknown form id "${formId}".`);
+		const entry = registry.get(formId);
+		if (entry === void 0) throw new FormsError(`Unknown form id "${formId}".`);
 		const instance = createFormInstance({
 			analyticsInstance,
 			storage,
 			persistence: resolvedPersistence,
-			schema,
-			customValidations
+			uploadConfig,
+			schema: entry.schema,
+			customValidations: entry.customValidations,
+			serverFormData: entry.serverFormData,
+			projectId: core.getProjectId()
 		});
 		instances.set(formId, instance);
 		return instance;
 	} };
 }
-function createFormInstance({ analyticsInstance, storage, persistence, schema, customValidations }) {
+function mergeInitialBag({ fromStorage, serverFormData }) {
+	if (serverFormData === void 0) return { ...fromStorage };
+	return {
+		...fromStorage,
+		...serverFormData
+	};
+}
+function createFormInstance({ analyticsInstance, storage, persistence, uploadConfig, schema, customValidations, serverFormData, projectId }) {
 	const resolved = resolveForm({ schema: mergeCustomValidations({
 		schema,
 		customValidations
@@ -739,11 +1119,14 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 	};
 	const state = {
 		storage: resolvedStorage,
-		bag: { ...readFields({
-			storage: resolvedStorage,
-			formKey: resolved.formKey,
-			fieldDefinitions: resolved.fields
-		}) },
+		bag: mergeInitialBag({
+			fromStorage: readFields({
+				storage: resolvedStorage,
+				formKey: resolved.formKey,
+				fieldDefinitions: resolved.fields
+			}),
+			serverFormData
+		}),
 		errors: /* @__PURE__ */ new Map()
 	};
 	const firePersistence = (run) => {
@@ -814,12 +1197,24 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		}
 	};
 	const set = (patch) => {
-		const changes = patch;
-		const entries = Object.entries(changes);
-		if (entries.length === 0) return Promise.resolve({
+		const changes = { ...patch };
+		if (Object.keys(changes).length === 0) return Promise.resolve({
 			ok: true,
 			errors: noErrors()
 		});
+		const previousBag = readBag();
+		for (const [key, value] of Object.entries(changes)) {
+			const field = declared.get(key);
+			if (!field || field.type !== "multiselect" || !field.options) continue;
+			if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) continue;
+			const stored = previousBag[key];
+			changes[key] = [...normalizeExclusiveSelection({
+				next: value,
+				previous: Array.isArray(stored) ? stored : [],
+				options: field.options
+			})];
+		}
+		const entries = Object.entries(changes);
 		const errors = /* @__PURE__ */ new Map();
 		for (const [key, value] of entries) {
 			const field = declared.get(key);
@@ -827,12 +1222,14 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 				errors.set(key, [`Unknown field: ${key}`]);
 				continue;
 			}
+			if (value === void 0) continue;
 			if (!isSerializable({ value })) errors.set(key, [`${field.label} value is not JSON-serializable`]);
 		}
 		const candidate = {
-			...readBag(),
+			...previousBag,
 			...changes
 		};
+		for (const [key, value] of entries) if (value === void 0) delete candidate[key];
 		const snapshot = narrow(candidate);
 		for (const [key, value] of entries) {
 			const field = declared.get(key);
@@ -866,12 +1263,18 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		} catch {
 			return Promise.resolve(degradeAndReport({ entries }));
 		}
+		writeFormCookieData({
+			projectId,
+			formId: resolved.formKey,
+			bag: candidate,
+			fieldDefinitions: resolved.fields
+		});
 		notify();
 		const persistedFields = entries.map(([key, value]) => {
 			const field = declared.get(key);
 			return {
 				key,
-				value,
+				value: value === void 0 ? null : value,
 				...field?.registryId === void 0 ? {} : { registryId: field.registryId },
 				...field?.protocolFieldId === void 0 ? {} : { protocolFieldId: field.protocolFieldId }
 			};
@@ -890,10 +1293,12 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		});
 		return analyticsInstance.trackEvent([buildDataUpdatedEvent({
 			fields: resolved.fields,
-			patch: changes
+			patch: changes,
+			formId: schema.id
 		}), ...buildFieldUpdatedEvents({
 			fields: resolved.fields,
-			patch: changes
+			patch: changes,
+			formId: schema.id
 		})]).then(() => ({
 			ok: true,
 			errors: noErrors()
@@ -1058,6 +1463,10 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		});
 		state.bag = {};
 		state.errors.clear();
+		clearFormCookieData({
+			projectId,
+			formId: resolved.formKey
+		});
 		notify();
 	};
 	const subscribe = (listener) => {
@@ -1066,6 +1475,27 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 			listeners.delete(listener);
 		};
 	};
+	const uploadFile = async ({ key, file, fileName }) => {
+		const field = declared.get(key);
+		if (!field) throw new FormsError(`Unknown field: ${key}`);
+		if (field.type !== "file") throw new FormsError(`Field "${key}" is not a file field`);
+		if (!uploadConfig) throw new FormsError("File uploads require a valid publishable key and initialized Embeddables core instance.");
+		const rules = field.validations;
+		const contentType = file.type || "application/octet-stream";
+		const byteLength = file.size;
+		if (byteLength > 26214400) throw new FormsError("Maximum upload size is 25 MiB.");
+		if (rules?.maxSize !== void 0 && byteLength > rules.maxSize) throw new FormsError(`${field.label} must be at most ${rules.maxSize} bytes`);
+		if (rules?.accept !== void 0 && !contentTypeMatchesAccept({
+			contentType,
+			accept: rules.accept
+		})) throw new FormsError(`${field.label} must be one of the allowed file types`);
+		return uploadFormFile(uploadConfig, {
+			formId: resolved.formKey,
+			fieldKey: key,
+			file,
+			fileName
+		});
+	};
 	return {
 		key: schema.id,
 		set,
@@ -1076,10 +1506,11 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		validate,
 		errors: () => freeze(state.errors),
 		clear,
+		uploadFile,
 		subscribe
 	};
 }
 //#endregion
-export { ValidatorError as a, SchemaError as i, FORM_DATA_KEY as n, FormsError as r, initForms as t };
+export { FORM_DATA_KEY as a, SchemaError as c, seedServerFormsStorageFromCookies as i, ValidatorError as l, initForms as n, createMemoryFormsStorage as o, createNoopPersistence as r, FormsError as s, createFormsClient as t };
 
-//# sourceMappingURL=form-9Tp91g6a.js.map
+//# sourceMappingURL=form-7wmC3G_q.js.map