@orkestrel/form 0.0.4 → 0.0.6

package/dist/src/core/index.cjs

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
-/** Every field control, in the order declared by the public contract. */
+/** Lists every field control, in the order declared by the public contract. */
 var FIELD_CONTROLS = Object.freeze([
 	"text",
 	"editor",
@@ -17,13 +17,69 @@ var FIELD_CONTROLS = Object.freeze([
 	"checkbox",
 	"file"
 ]);
-/** Every form lifecycle status. */
+/** Lists the members every field declares, whatever its control. */
+var FIELD_BASE_KEYS = Object.freeze([
+	"control",
+	"name",
+	"label",
+	"help",
+	"group",
+	"hidden",
+	"disabled",
+	"locked",
+	"rule",
+	"meta"
+]);
+/**
+* Lists every member one field control permits, composed from {@link FIELD_BASE_KEYS} and the
+* members the control's own interface adds.
+*/
+var FIELD_KEYS = Object.freeze({
+	text: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	editor: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	password: Object.freeze([...FIELD_BASE_KEYS, "mask"]),
+	number: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	date: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	time: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	datetime: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	color: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	confirm: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	select: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default",
+		"open"
+	]),
+	checkbox: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default"
+	]),
+	file: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"accept",
+		"multiple"
+	])
+});
+/** Lists every form lifecycle status. */
 var FORM_STATUSES = Object.freeze([
 	"editing",
 	"settled",
 	"abandoned"
 ]);
-/** Default failure copy for every named field rule. */
+/** Holds the default failure copy for every named field rule. */
 var RULE_MESSAGES = Object.freeze({
 	required: "This field is required",
 	minimum: "Must be at least {limit}",
@@ -35,50 +91,62 @@ var RULE_MESSAGES = Object.freeze({
 	integer: "Must be an integer",
 	alphanumeric: "Must contain only letters and numbers"
 });
-/** A practical whole-address email shape. */
+/** Matches a practical whole-address email shape. */
 var EMAIL_PATTERN = Object.freeze(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
-/** An absolute HTTP or HTTPS URL shape. */
+/** Matches an absolute HTTP or HTTPS URL shape. */
 var URL_PATTERN = Object.freeze(/^https?:\/\/[^\s]+$/);
-/** One or more ASCII letters or digits. */
+/** Matches one or more ASCII letters or digits. */
 var ALPHANUMERIC_PATTERN = Object.freeze(/^[A-Za-z0-9]+$/);
-/** A signed or unsigned base-ten integer string. */
+/** Matches a signed or unsigned base-ten integer string. */
 var INTEGER_PATTERN = Object.freeze(/^[+-]?\d+$/);
-/** A six-digit hexadecimal color string. */
+/** Matches a six-digit hexadecimal color string. */
 var COLOR_PATTERN = Object.freeze(/^#[0-9A-Fa-f]{6}$/);
-/** An ISO calendar date string in `YYYY-MM-DD` form. */
+/** Matches an ISO calendar date string in `YYYY-MM-DD` form. */
 var DATE_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/);
-/** A 24-hour time string with optional seconds. */
+/** Matches a 24-hour time string with optional seconds. */
 var TIME_PATTERN = Object.freeze(/^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
-/** An ISO local date and time string with optional seconds. */
+/** Matches an ISO local date and time string with optional seconds. */
 var DATETIME_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
-/** The maximum accepted source length for an authored regular expression. */
+/** Caps the accepted source length for an authored regular expression, at 256. */
 var PATTERN_LIMIT = 256;
-/** The maximum number of fields one schema may declare. */
+/** Caps the number of fields one schema may declare, at 512. */
 var FIELD_LIMIT = 512;
-/** The maximum number of groups one schema may declare. */
+/** Caps the number of groups one schema may declare, at 64. */
 var GROUP_LIMIT = 64;
-/** The maximum number of choices one `select` or `checkbox` field may offer. */
+/** Caps the number of choices one `select` or `checkbox` field may offer, at 1024. */
 var CHOICE_LIMIT = 1024;
-/** The maximum number of entries one list-valued answer may hold. */
+/** Caps the number of entries one list-valued answer may hold, at 1024. */
 var LIST_LIMIT = 1024;
-/** The maximum length, in UTF-16 code units, of a schema, group, or field name. */
+/** Caps the length, in UTF-16 code units, of a schema, group, or field name, at 128. */
 var NAME_LIMIT = 128;
-/** The maximum length, in UTF-16 code units, of any single retained string. */
+/** Caps the length, in UTF-16 code units, of any single retained string, at 65536. */
 var STRING_LIMIT = 65536;
-/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+/** Caps the total length, in UTF-16 code units, of every string one schema retains, at 1048576. */
 var TEXT_LIMIT = 1048576;
-/** The maximum total number of records, arrays, and leaves one schema retains. */
+/** Caps the total number of records, arrays, and leaves one schema retains, at 16384. */
 var NODE_LIMIT = 16384;
 //#endregion
 //#region src/core/errors.ts
-/** An error raised by the form domain. */
+/**
+* Represents an error raised by the form domain.
+*
+* @example
+* ```ts
+* const error = new FormError('FIELD', 'The schema declares no field named "nickname"', {
+* 	field: 'nickname',
+* })
+*
+* error.code // 'FIELD'
+* error.context // { field: 'nickname' }
+* ```
+*/
 var FormError = class extends Error {
-	/** The machine-readable reason for this failure. */
+	/** Holds the machine-readable reason for this failure. */
 	code;
-	/** Structured values that locate or explain this failure. */
+	/** Holds structured values that locate or explain this failure. */
 	context;
 	/**
-	* Create a form error.
+	* Creates a form error.
 	*
 	* @param code - The machine-readable reason.
 	* @param message - The human-readable failure text.
@@ -92,10 +160,10 @@ var FormError = class extends Error {
 	}
 };
 /**
-* Determine whether an unknown value is a form error.
+* Determines whether an unknown value is a form error.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a {@link FormError} instance.
+* @returns True if the value is a {@link FormError} instance; false otherwise.
 */
 function isFormError(input) {
 	return input instanceof FormError;
@@ -103,37 +171,41 @@ function isFormError(input) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether an unknown value is a declared field control.
+* Determines whether an unknown value is a declared field control.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field control.
+* @returns True if the value is a field control; false otherwise.
 */
 function isFieldControl(input) {
 	return FIELD_CONTROLS.some((control) => control === input);
 }
 /**
-* Determine whether an unknown value is a form lifecycle status.
+* Determines whether an unknown value is a form lifecycle status.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form status.
+* @returns True if the value is a form status; false otherwise.
 */
 function isFormStatus(input) {
 	return FORM_STATUSES.some((status) => status === input);
 }
 /**
-* Determine whether an unknown value has a form field value shape.
+* Determines whether an unknown value has a form field value shape.
+*
+* @remarks
+* A string, a finite number, a boolean, and a list of strings each qualify. A number that is not
+* finite does not, so `NaN` and `Infinity` are refused.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field value.
+* @returns True if the value is a field value; false otherwise.
 */
 function isFieldValue(input) {
 	return (0, _orkestrel_contract.unionOf)(_orkestrel_contract.isString, _orkestrel_contract.isFiniteNumber, _orkestrel_contract.isBoolean, (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString))(input);
 }
 /**
-* Determine whether an unknown value is one exact field choice record.
+* Determines whether an unknown value is one exact field choice record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field choice.
+* @returns True if the value is a field choice; false otherwise.
 */
 function isFieldChoice(input) {
 	const keys = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.isRecord)(input) && Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key)));
@@ -146,10 +218,10 @@ function isFieldChoice(input) {
 	}, ["help", "disabled"])(input);
 }
 /**
-* Determine whether an unknown value is one exact field rule record.
+* Determines whether an unknown value is one exact field rule record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid field rule.
+* @returns True if the value is a structurally valid field rule; false otherwise.
 */
 function isFieldRule(input) {
 	const keys = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.isRecord)(input) && Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key)));
@@ -168,7 +240,7 @@ function isFieldRule(input) {
 	}, true)(input);
 }
 /**
-* Determine whether an unknown value is one exact discriminated form field.
+* Determines whether an unknown value is one exact discriminated form field.
 *
 * @remarks
 * Metadata is admitted structurally as bounded JSON. An accessor-bearing metadata record is
@@ -176,120 +248,15 @@ function isFieldRule(input) {
 * data properties only.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid form field.
+* @returns True if the value is a structurally valid form field; false otherwise.
 */
 function isFormField(input) {
 	const outcome = (0, _orkestrel_contract.attempt)(() => {
 		if (!(0, _orkestrel_contract.isRecord)(input) || !Object.hasOwn(input, "control") || !Object.hasOwn(input, "name")) return false;
 		const control = input.control;
 		if (!isFieldControl(control)) return false;
-		if (!Reflect.ownKeys(input).every((key) => {
-			if (!(0, _orkestrel_contract.isString)(key)) return false;
-			switch (control) {
-				case "text":
-				case "editor": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default",
-					"placeholder"
-				].includes(key);
-				case "password": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"mask"
-				].includes(key);
-				case "number": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default",
-					"placeholder"
-				].includes(key);
-				case "date":
-				case "time":
-				case "datetime":
-				case "color":
-				case "confirm": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default"
-				].includes(key);
-				case "select": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"choices",
-					"default",
-					"open"
-				].includes(key);
-				case "checkbox": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"choices",
-					"default"
-				].includes(key);
-				case "file": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"accept",
-					"multiple"
-				].includes(key);
-			}
-		})) return false;
+		const permitted = FIELD_KEYS[control];
+		if (!Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key) && permitted.includes(key))) return false;
 		const name = input.name;
 		const hasLabel = Object.hasOwn(input, "label");
 		const label = hasLabel ? input.label : void 0;
@@ -370,10 +337,10 @@ function isFormField(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one exact form group record.
+* Determines whether an unknown value is one exact form group record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form group.
+* @returns True if the value is a form group; false otherwise.
 */
 function isFormGroup(input) {
 	const keys = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.isRecord)(input) && Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key)));
@@ -385,10 +352,14 @@ function isFormGroup(input) {
 	}, ["help"])(input);
 }
 /**
-* Determine whether an unknown value is one exact structural form schema.
+* Determines whether an unknown value is one exact structural form schema.
+*
+* @remarks
+* Structure alone is read. Domain soundness — a duplicate name, a bound no answer satisfies, a
+* breached budget — is {@link auditSchema}'s question.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid form schema.
+* @returns True if the value is a structurally valid form schema; false otherwise.
 */
 function isFormSchema(input) {
 	const keys = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.isRecord)(input) && Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key)));
@@ -407,10 +378,10 @@ function isFormSchema(input) {
 	])(input);
 }
 /**
-* Determine whether an unknown value is a record of field values.
+* Determines whether an unknown value is a record of field values.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form values record.
+* @returns True if the value is a form values record; false otherwise.
 */
 function isFormValues(input) {
 	const outcome = (0, _orkestrel_contract.attempt)(() => {
@@ -420,10 +391,10 @@ function isFormValues(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one exact field error record.
+* Determines whether an unknown value is one exact field error record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field error.
+* @returns True if the value is a field error; false otherwise.
 */
 function isFieldError(input) {
 	const keys = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.isRecord)(input) && Reflect.ownKeys(input).every((key) => (0, _orkestrel_contract.isString)(key)));
@@ -431,7 +402,7 @@ function isFieldError(input) {
 	return (0, _orkestrel_contract.recordOf)({
 		field: _orkestrel_contract.isString,
 		message: _orkestrel_contract.isString,
-		rule: (0, _orkestrel_contract.literalOf)("required", "minimum", "maximum", "step", "pattern", "email", "url", "integer", "alphanumeric")
+		rule: (0, _orkestrel_contract.keyOf)(RULE_MESSAGES)
 	}, ["rule"])(input);
 }
 //#endregion
@@ -440,7 +411,7 @@ function cloneValue(value) {
 	return (0, _orkestrel_contract.isArray)(value) ? Object.freeze(value.slice()) : value;
 }
 /**
-* Clone a field's choices into an owned frozen snapshot.
+* Clones a field's choices into an owned frozen snapshot.
 *
 * @param choices - The choices to own.
 * @returns A frozen list of frozen choice records.
@@ -449,7 +420,7 @@ function cloneChoices(choices) {
 	return Object.freeze(choices.map((choice) => Object.freeze({ ...choice })));
 }
 /**
-* Clone one form field into an owned frozen snapshot.
+* Clones one form field into an owned frozen snapshot.
 *
 * @param field - The field to own.
 * @returns A frozen field with every nested collection owned.
@@ -500,7 +471,7 @@ function cloneFormField(field) {
 	}
 }
 /**
-* Clone a form schema into an owned frozen snapshot.
+* Clones a form schema into an owned frozen snapshot.
 *
 * @param schema - The schema to own.
 * @returns A frozen schema with every nested record and list owned.
@@ -516,11 +487,68 @@ function cloneFormSchema(schema) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Check whether a value has the shape required by one field control.
+* Writes one own enumerable data property onto a record.
+*
+* @param target - The record to write into.
+* @param name - The property name to write.
+* @param value - The value to store.
+*
+* @remarks
+* Plain assignment runs an inherited setter, so writing a `__proto__` key that way reaches
+* `Object.prototype` and leaves the record without the entry. Defining the property writes the
+* record itself, whatever the prototype chain declares. The entry stays writable and configurable.
+*
+* @example
+* ```ts
+* const values: Record<string, number> = {}
+* defineEntry(values, '__proto__', 1)
+* Object.hasOwn(values, '__proto__') // true
+* ```
+*/
+function defineEntry(target, name, value) {
+	Object.defineProperty(target, name, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+}
+/**
+* Writes one own enumerable data property that cannot be rewritten or removed.
+*
+* @param target - The record to write into.
+* @param name - The property name to write.
+* @param value - The value to store.
+*
+* @remarks
+* The prototype-safe write of {@link defineEntry}, frozen: the entry is neither writable nor
+* configurable, so the record a parser hands back cannot be edited through the key it filled.
+*
+* @example
+* ```ts
+* const values: Record<string, number> = {}
+* freezeEntry(values, '__proto__', 1)
+* Object.getOwnPropertyDescriptor(values, '__proto__')?.writable // false
+* ```
+*/
+function freezeEntry(target, name, value) {
+	Object.defineProperty(target, name, {
+		value,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+}
+/**
+* Checks whether a value has the shape required by one field control.
+*
+* @remarks
+* Every write and every seeded value passes through this gate, and it reads `STRING_LIMIT` and
+* `LIST_LIMIT` before it consults the control, so no regular expression sees an over-long value.
 *
 * @param field - The field that owns the value.
 * @param value - The unknown value to inspect.
-* @returns Whether the control can hold the value.
+* @returns True if the control can hold the value; false otherwise.
 */
 function matchesField(field, value) {
 	if ((0, _orkestrel_contract.isString)(value) && value.length > 65536) return false;
@@ -549,7 +577,7 @@ function matchesField(field, value) {
 	}
 }
 /**
-* Decide whether a raw binding value projects to an answered field.
+* Decides whether a raw binding value projects to an answered field.
 *
 * @remarks
 * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
@@ -558,13 +586,13 @@ function matchesField(field, value) {
 * its `required` rule remains presence-only.
 *
 * @param value - The raw field value, or absence.
-* @returns Whether the binding should preserve the value as an answer.
+* @returns True if the binding preserves the value as an answer; false otherwise.
 */
 function matchesAnswer(value) {
 	return value !== void 0 && (!(0, _orkestrel_contract.isString)(value) || value.trim().length > 0);
 }
 /**
-* Check whether a named rule applies to one field control.
+* Checks whether a named rule applies to one field control.
 *
 * @remarks
 * The runtime control-membership check keeps this boundary total for JavaScript callers that
@@ -572,7 +600,7 @@ function matchesAnswer(value) {
 *
 * @param control - The field control to inspect.
 * @param rule - The named rule to inspect.
-* @returns Whether the control evaluates that rule.
+* @returns True if the control evaluates that rule; false otherwise.
 */
 function appliesRule(control, rule) {
 	if (!FIELD_CONTROLS.some((candidate) => candidate === control)) return false;
@@ -590,23 +618,21 @@ function appliesRule(control, rule) {
 	return false;
 }
 /**
-* Evaluate one field rule against its current value.
+* Evaluates one field rule against its current value.
 *
 * @param field - The field and rule to evaluate.
 * @param value - The current value, or absence.
 * @param values - Every value available to a custom rule.
 * @param messages - Optional rule-specific message replacements.
 * @returns Every failure in rule order.
+* @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+*   its own value escapes unchanged, because this helper adds no boundary around it.
 */
 function evaluateField(field, value, values, messages) {
 	const errors = [];
 	const rule = field.rule;
 	if (value === void 0) {
-		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("required", void 0, messages),
-			rule: "required"
-		}));
+		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(createFieldError(field, "required", void 0, messages));
 	}
 	if (rule === void 0) return Object.freeze(errors);
 	if (rule.minimum !== void 0 && appliesRule(field.control, "minimum")) {
@@ -628,11 +654,7 @@ function evaluateField(field, value, values, messages) {
 			case "checkbox":
 			case "file": failed = (0, _orkestrel_contract.isArray)(value) && (0, _orkestrel_contract.isFiniteNumber)(rule.minimum) && value.length < rule.minimum;
 		}
-		if (failed) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("minimum", rule.minimum, messages),
-			rule: "minimum"
-		}));
+		if (failed) errors.push(createFieldError(field, "minimum", rule.minimum, messages));
 	}
 	if (rule.maximum !== void 0 && appliesRule(field.control, "maximum")) {
 		let failed = false;
@@ -653,63 +675,27 @@ function evaluateField(field, value, values, messages) {
 			case "checkbox":
 			case "file": failed = (0, _orkestrel_contract.isArray)(value) && (0, _orkestrel_contract.isFiniteNumber)(rule.maximum) && value.length > rule.maximum;
 		}
-		if (failed) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("maximum", rule.maximum, messages),
-			rule: "maximum"
-		}));
+		if (failed) errors.push(createFieldError(field, "maximum", rule.maximum, messages));
 	}
 	if (rule.step !== void 0 && appliesRule(field.control, "step") && (0, _orkestrel_contract.isFiniteNumber)(value)) {
 		const multiple = (value - ((0, _orkestrel_contract.isFiniteNumber)(rule.minimum) ? rule.minimum : 0)) / rule.step;
-		if (!(0, _orkestrel_contract.isFiniteNumber)(rule.step) || rule.step === 0 || !(0, _orkestrel_contract.isFiniteNumber)(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("step", rule.step, messages),
-			rule: "step"
-		}));
+		if (!(0, _orkestrel_contract.isFiniteNumber)(rule.step) || rule.step === 0 || !(0, _orkestrel_contract.isFiniteNumber)(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(createFieldError(field, "step", rule.step, messages));
 	}
 	if ((0, _orkestrel_contract.isString)(value)) {
 		if (rule.pattern !== void 0 && appliesRule(field.control, "pattern")) {
 			const pattern = rule.pattern;
-			if (pattern.length > 256) errors.push(Object.freeze({
-				field: field.name,
-				message: formatMessage("pattern", void 0, messages),
-				rule: "pattern"
-			}));
+			if (pattern.length > 256) errors.push(createFieldError(field, "pattern", void 0, messages));
 			else {
 				const outcome = (0, _orkestrel_contract.attempt)(() => new RegExp(pattern).test(value));
-				if (!outcome.success || !outcome.value) errors.push(Object.freeze({
-					field: field.name,
-					message: formatMessage("pattern", void 0, messages),
-					rule: "pattern"
-				}));
+				if (!outcome.success || !outcome.value) errors.push(createFieldError(field, "pattern", void 0, messages));
 			}
 		}
-		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("email", void 0, messages),
-			rule: "email"
-		}));
-		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("url", void 0, messages),
-			rule: "url"
-		}));
-		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("alphanumeric", void 0, messages),
-			rule: "alphanumeric"
-		}));
-		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("integer", void 0, messages),
-			rule: "integer"
-		}));
+		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(createFieldError(field, "email", void 0, messages));
+		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(createFieldError(field, "url", void 0, messages));
+		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(createFieldError(field, "alphanumeric", void 0, messages));
+		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	}
-	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !(0, _orkestrel_contract.isInteger)(value)) errors.push(Object.freeze({
-		field: field.name,
-		message: formatMessage("integer", void 0, messages),
-		rule: "integer"
-	}));
+	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !(0, _orkestrel_contract.isInteger)(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	if (rule.custom !== void 0) {
 		const result = rule.custom(value, values);
 		if ((0, _orkestrel_contract.isString)(result)) errors.push(Object.freeze({
@@ -720,12 +706,14 @@ function evaluateField(field, value, values, messages) {
 	return Object.freeze(errors);
 }
 /**
-* Evaluate every active field in schema order.
+* Evaluates every active field in schema order.
 *
 * @param schema - The form schema to evaluate.
 * @param values - The values keyed by field name.
 * @param options - Optional message replacements and the effective disabled field set.
 * @returns Every field failure in schema and rule order.
+* @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+*   its own value escapes unchanged, because this helper adds no boundary around it.
 */
 function evaluateForm(schema, values, options) {
 	const errors = [];
@@ -736,7 +724,11 @@ function evaluateForm(schema, values, options) {
 	return Object.freeze(errors);
 }
 /**
-* Compute the values explicitly seeded by a schema.
+* Computes the values explicitly seeded by a schema.
+*
+* @remarks
+* `password` and `file` declare no default, so a field of either control never appears in the
+* result.
 *
 * @param schema - The schema whose defaults to collect.
 * @returns A value record containing only fields with defaults.
@@ -745,12 +737,7 @@ function computeDefaults(schema) {
 	const defaults = {};
 	for (const field of schema.fields) switch (field.control) {
 		case "checkbox":
-			if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
-				value: cloneValue(field.default),
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			if (field.default !== void 0) defineEntry(defaults, field.name, cloneValue(field.default));
 			break;
 		case "password":
 		case "file": break;
@@ -762,35 +749,30 @@ function computeDefaults(schema) {
 		case "datetime":
 		case "color":
 		case "confirm":
-		case "select": if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
-			value: field.default,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		case "select": if (field.default !== void 0) defineEntry(defaults, field.name, field.default);
 	}
 	return Object.freeze(defaults);
 }
 /**
-* Compare two field values by scalar identity or ordered list content.
+* Compares two field values by scalar identity or ordered list content.
 *
 * @param a - The first field value.
 * @param b - The second field value.
-* @returns Whether both values contain the same answer.
+* @returns True if both values contain the same answer; false otherwise.
 */
 function matchesValue(a, b) {
 	if ((0, _orkestrel_contract.isArray)(a) || (0, _orkestrel_contract.isArray)(b)) return (0, _orkestrel_contract.isArray)(a) && (0, _orkestrel_contract.isArray)(b) && a.length === b.length && a.every((entry, index) => entry === b[index]);
 	return a === b;
 }
 /**
-* Extract the names whose answers differ between two form value records.
+* Extracts the names whose answers differ between two form value records.
 *
 * @remarks
 * Presence is compared in both directions before present values are compared through
 * {@link matchesValue}. The returned set is a new snapshot, exposed as readonly because later
 * changes to either input never alter its membership.
 *
-* @param current - The values held now.
+* @param current - The values the form holds.
 * @param opened - The values held when the form opened.
 * @returns A readonly snapshot of changed field names.
 */
@@ -809,17 +791,21 @@ function extractChanges(current, opened) {
 	return changed;
 }
 /**
-* Compare two form value records by keys and value content.
+* Compares two form value records by keys and value content.
 *
 * @param a - The first value record.
 * @param b - The second value record.
-* @returns Whether both records contain the same answers.
+* @returns True if both records contain the same answers; false otherwise.
 */
 function matchesValues(a, b) {
 	return extractChanges(a, b).size === 0;
 }
 /**
-* Resolve and interpolate one rule message.
+* Resolves and interpolates one rule message.
+*
+* @remarks
+* A replacement in `messages` is read first and {@link RULE_MESSAGES} supplies the copy otherwise,
+* and `{limit}` in whichever text wins is replaced with the rule's operand.
 *
 * @param rule - The rule whose message to resolve.
 * @param limit - The optional operand substituted for `{limit}`.
@@ -831,7 +817,34 @@ function formatMessage(rule, limit, messages) {
 	return limit === void 0 ? message : message.replaceAll("{limit}", String(limit));
 }
 /**
-* Project a schema into JSON while removing custom validators and absent values.
+* Creates one named-rule failure against a field.
+*
+* @param field - The field the rule failed on.
+* @param rule - The named rule that failed.
+* @param limit - The rule's operand, substituted for `{limit}`, or absence when it carries none.
+* @param messages - Optional rule-specific message replacements.
+* @returns A frozen {@link FieldError} carrying the field's name, the resolved text, and the rule.
+*
+* @remarks
+* A `custom` validator and the form's `invalidate` method both report a message of their own
+* under no rule name, so neither builds its failure here.
+*
+* @example
+* ```ts
+* const field: FormField = { control: 'text', name: 'nickname', rule: { minimum: 3 } }
+* const error = createFieldError(field, 'minimum', 3)
+* error.message // 'Must be at least 3'
+* ```
+*/
+function createFieldError(field, rule, limit, messages) {
+	return Object.freeze({
+		field: field.name,
+		message: formatMessage(rule, limit, messages),
+		rule
+	});
+}
+/**
+* Projects a schema into JSON while removing custom validators and absent values.
 *
 * @param schema - The schema to project.
 * @returns A deep JSON copy of the serializable schema.
@@ -933,7 +946,7 @@ function serializeForm(schema) {
 	return (0, _orkestrel_contract.cloneJSONRecord)(output);
 }
 /**
-* Select referenced groups in first-reference field order.
+* Selects referenced groups in first-reference field order.
 *
 * @param schema - The schema whose group references to resolve.
 * @returns The referenced schema groups without duplicates.
@@ -948,7 +961,7 @@ function extractGroups(schema) {
 	return Object.freeze(groups);
 }
 /**
-* Audit a structurally valid schema for domain invariants.
+* Audits a structurally valid schema for domain invariants.
 *
 * @param schema - The form schema to audit.
 * @returns Human-readable invariant violations, or an empty list when the schema is sound.
@@ -1123,7 +1136,7 @@ function auditSchema(schema) {
 //#endregion
 //#region src/core/parsers.ts
 /**
-* Parse unknown wire data into an owned, semantically sound form schema.
+* Parses unknown wire data into an owned, semantically sound form schema.
 *
 * @param input - The unknown schema value to parse.
 * @returns An owned schema with custom rules removed, or `undefined` on refusal.
@@ -1134,12 +1147,7 @@ function parseForm(input) {
 		const schema = {};
 		for (const key of Reflect.ownKeys(input)) {
 			if (!(0, _orkestrel_contract.isString)(key)) return void 0;
-			Object.defineProperty(schema, key, {
-				value: input[key],
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			defineEntry(schema, key, input[key]);
 		}
 		const fields = schema.fields;
 		if (!(0, _orkestrel_contract.isArray)(fields)) return void 0;
@@ -1155,24 +1163,14 @@ function parseForm(input) {
 			const copy = {};
 			for (const key of Reflect.ownKeys(field)) {
 				if (!(0, _orkestrel_contract.isString)(key)) return void 0;
-				Object.defineProperty(copy, key, {
-					value: field[key],
-					enumerable: true,
-					configurable: true,
-					writable: true
-				});
+				defineEntry(copy, key, field[key]);
 			}
 			const rule = copy.rule;
 			if ((0, _orkestrel_contract.isRecord)(rule)) {
 				const projected = {};
 				for (const key of Reflect.ownKeys(rule)) {
 					if (!(0, _orkestrel_contract.isString)(key)) return void 0;
-					if (key !== "custom") Object.defineProperty(projected, key, {
-						value: rule[key],
-						enumerable: true,
-						configurable: true,
-						writable: true
-					});
+					if (key !== "custom") defineEntry(projected, key, rule[key]);
 				}
 				copy.rule = projected;
 			}
@@ -1186,7 +1184,11 @@ function parseForm(input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parse one answer against its field control.
+* Parses one answer against its field control.
+*
+* @remarks
+* A numeric string coerces to a number for a `number` field, and `'true'` and `'false'` coerce to
+* a boolean for a `confirm` field. Every other value must already have its control's shape.
 *
 * @param field - The field that defines the accepted value.
 * @param input - The unknown value to parse.
@@ -1208,7 +1210,7 @@ function parseValue(field, input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parse a strict answer record against the fields declared by a schema.
+* Parses a strict answer record against the fields declared by a schema.
 *
 * @param schema - The schema that owns the accepted field names and controls.
 * @param input - The unknown answer record to parse.
@@ -1224,12 +1226,7 @@ function parseValues(schema, input) {
 			if (field === void 0) return void 0;
 			const value = parseValue(field, input[key]);
 			if (value === void 0) return void 0;
-			Object.defineProperty(values, key, {
-				value,
-				enumerable: true,
-				configurable: false,
-				writable: false
-			});
+			freezeEntry(values, key, value);
 		}
 		return Object.freeze(values);
 	});
@@ -1238,7 +1235,8 @@ function parseValues(schema, input) {
 //#endregion
 //#region src/core/Form.ts
 /**
-* A form: a schema, the answers given against it, and the errors they carry.
+* Implements `FormInterface` exactly, over an owned schema, the answers given against it, and the
+* errors they carry.
 *
 * @remarks
 * The form owns its schema, so a later edit to the schema the caller passed changes nothing here.
@@ -1278,7 +1276,7 @@ var Form = class {
 	#evaluation = 0;
 	#pending = false;
 	/**
-	* Open a form against a schema.
+	* Opens a form against a schema.
 	*
 	* @param schema - The form to ask. It is copied, and the copy is what the form asks.
 	* @param options - The form's settings.
@@ -1287,93 +1285,76 @@ var Form = class {
 	*   value is one its field's control cannot hold.
 	*/
 	constructor(schema, options) {
-		const problems = isFormSchema(schema) ? auditSchema(schema) : ["The schema is not a form schema"];
-		if (problems.length > 0) throw new FormError("SCHEMA", `The form schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
-		this.#schema = cloneFormSchema(schema);
+		const owned = (0, _orkestrel_contract.attempt)(() => cloneFormSchema(schema));
+		if (!owned.success && isFormError(owned.error)) throw owned.error;
+		const copy = owned.success && isFormSchema(owned.value) ? owned.value : void 0;
+		const problems = copy === void 0 ? ["The schema is not a form schema"] : auditSchema(copy);
+		if (copy === void 0 || problems.length > 0) throw new FormError("SCHEMA", `The form schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
+		this.#schema = copy;
 		this.#messages = options?.messages === void 0 ? void 0 : Object.freeze({ ...options.messages });
 		const baseline = {};
-		for (const [name, value] of Object.entries(computeDefaults(this.#schema))) Object.defineProperty(baseline, name, {
-			value,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(computeDefaults(this.#schema))) defineEntry(baseline, name, value);
 		for (const [name, value] of Object.entries(options?.values ?? {})) {
 			const field = this.#requireField(name);
 			if (!matchesField(field, value)) throw new FormError("CONTROL", `The ${field.control} field "${name}" cannot hold that value`, {
 				field: name,
 				control: field.control
 			});
-			Object.defineProperty(baseline, name, {
-				value: cloneValue(value),
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			defineEntry(baseline, name, cloneValue(value));
 		}
 		this.#baseline = Object.freeze(baseline);
 		this.#values = {};
-		for (const [name, value] of Object.entries(baseline)) Object.defineProperty(this.#values, name, {
-			value,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(baseline)) defineEntry(this.#values, name, value);
 		this.#resolvers.promise.catch(() => void 0);
 		this.#emitter = new _orkestrel_emitter.Emitter(options);
 		this.#evaluate();
 	}
-	/** The form's event emitter. */
+	/** Holds the form's event emitter. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The schema this form asks, owned and frozen. */
+	/** Holds the schema this form asks, owned and frozen. */
 	get schema() {
 		return this.#schema;
 	}
-	/** The answers held right now. */
+	/** Reports the answers the form holds. */
 	get values() {
 		const values = {};
-		for (const name of Object.keys(this.#values)) Object.defineProperty(values, name, {
-			value: this.#values[name],
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(this.#values)) defineEntry(values, name, value);
 		return Object.freeze(values);
 	}
-	/** The answers the form opened with. */
+	/** Holds the answers the form opened with. */
 	get baseline() {
 		return this.#baseline;
 	}
-	/** Every error the last completed evaluation produced. */
+	/** Holds every error the last completed evaluation produced. */
 	get errors() {
 		return this.#errors;
 	}
-	/** The names of the fields somebody has visited. */
+	/** Lists the names of the fields somebody has visited. */
 	get touched() {
 		return new Set(this.#touched);
 	}
-	/** The names of the fields currently out of the form. */
+	/** Lists the names of the fields that are out of the form. */
 	get disabled() {
 		const disabled = /* @__PURE__ */ new Set();
 		for (const field of this.#schema.fields) if ((this.#disabled.get(field.name) ?? field.disabled === true) === true) disabled.add(field.name);
 		return disabled;
 	}
-	/** Where the form sits in its life. */
+	/** Reports where the form sits in its life. */
 	get status() {
 		return this.#status;
 	}
-	/** Whether the last completed evaluation found no error. */
+	/** Reports whether the last completed evaluation found no error. */
 	get valid() {
 		return this.#errors.length === 0;
 	}
-	/** Whether any answer has moved since the form opened. */
+	/** Reports whether any answer has moved since the form opened. */
 	get dirty() {
 		return !matchesValues(this.values, this.#baseline);
 	}
 	/**
-	* The answers, once the form settles.
+	* Holds the answers after the form settles.
 	*
 	* @remarks
 	* It resolves with the submitted values on the first valid submit, and rejects with a
@@ -1383,7 +1364,7 @@ var Form = class {
 		return this.#resolvers.promise;
 	}
 	/**
-	* Find one field by name.
+	* Finds one field by name.
 	*
 	* @param name - The field's name.
 	* @returns The field, or `undefined` when the schema declares no such name.
@@ -1392,7 +1373,7 @@ var Form = class {
 		return this.#schema.fields.find((field) => field.name === name);
 	}
 	/**
-	* Answer one field or several.
+	* Answers one field or several.
 	*
 	* @param input - One field's name, or the answers to write keyed by field name.
 	* @param value - The answer to write when `input` names one field.
@@ -1415,12 +1396,7 @@ var Form = class {
 			for (const [name, answer] of entries) {
 				if (this.#differs(name, answer)) moved.push(name);
 				if (answer === void 0) delete this.#values[name];
-				else Object.defineProperty(this.#values, name, {
-					value: cloneValue(answer),
-					enumerable: true,
-					configurable: true,
-					writable: true
-				});
+				else defineEntry(this.#values, name, cloneValue(answer));
 				this.#invalidations.delete(name);
 			}
 			for (const name of moved) {
@@ -1431,7 +1407,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Record that somebody has visited a field.
+	* Records that somebody has visited a field.
 	*
 	* @param name - The field's name.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1443,7 +1419,7 @@ var Form = class {
 		this.#touched.add(name);
 	}
 	/**
-	* Fail a field from outside, for what the rules cannot see.
+	* Fails a field from outside, for what the rules cannot see.
 	*
 	* @param name - The field's name.
 	* @param message - What to tell the person.
@@ -1462,7 +1438,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Take one or more fields out of the form.
+	* Takes one or more fields out of the form.
 	*
 	* @param input - One field name, several names, or absence to select every field.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1474,7 +1450,7 @@ var Form = class {
 		this.#change(input, true);
 	}
 	/**
-	* Put one or more fields back into the form.
+	* Puts one or more fields back into the form.
 	*
 	* @param input - One field name, several names, or absence to select every field.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1486,7 +1462,7 @@ var Form = class {
 		this.#change(input, false);
 	}
 	/**
-	* Check every answer and settle the form when they all pass.
+	* Checks every answer and settles the form when they all pass.
 	*
 	* @returns The values on success, or every error that stopped them.
 	* @remarks
@@ -1539,7 +1515,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Return every answer to the ones the form opened with: the schema's defaults, overlaid with
+	* Returns every answer to the ones the form opened with: the schema's defaults, overlaid with
 	* any seeded `values`. Reset the runtime disabled state to the schema's declarations.
 	*
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
@@ -1548,12 +1524,7 @@ var Form = class {
 		this.#gate();
 		this.#batch(() => {
 			for (const name of Object.keys(this.#values)) delete this.#values[name];
-			for (const [name, value] of Object.entries(this.#baseline)) Object.defineProperty(this.#values, name, {
-				value,
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			for (const [name, value] of Object.entries(this.#baseline)) defineEntry(this.#values, name, value);
 			this.#touched.clear();
 			this.#disabled.clear();
 			this.#invalidations.clear();
@@ -1563,7 +1534,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Tear the form down, abandoning it when it has not settled.
+	* Tears the form down, abandoning it when it has not settled.
 	*
 	* @remarks
 	* Destroying twice does nothing the second time. A settled form keeps its `settled` status and
@@ -1641,12 +1612,7 @@ var Form = class {
 		const disabled = this.disabled;
 		for (const field of this.#schema.fields) {
 			const value = Object.hasOwn(this.#values, field.name) ? this.#values[field.name] : void 0;
-			if (!disabled.has(field.name) && value !== void 0) Object.defineProperty(answers, field.name, {
-				value,
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			if (!disabled.has(field.name) && value !== void 0) defineEntry(answers, field.name, value);
 		}
 		return Object.freeze(answers);
 	}
@@ -1671,7 +1637,7 @@ var Form = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Open a form against a schema.
+* Opens a form against a schema.
 *
 * @param schema - The form to ask. It is copied, and the copy is what the form asks.
 * @param options - The form's settings.
@@ -1682,8 +1648,10 @@ var Form = class {
 * @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
 *   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded value
 *   is one its field's control cannot hold.
-* @example
+* @example Open a form, answer it, and settle it
 * ```ts
+* import { createForm } from '@orkestrel/form'
+*
 * const form = createForm({
 * 	label: 'Sign up',
 * 	fields: [
@@ -1693,7 +1661,8 @@ var Form = class {
 * })
 *
 * form.fill({ email: 'ada@example.com', terms: true })
-* form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+* const result = form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+* const answers = await form.answer // { email: 'ada@example.com', terms: true }
 * ```
 */
 function createForm(schema, options) {
@@ -1706,7 +1675,9 @@ exports.COLOR_PATTERN = COLOR_PATTERN;
 exports.DATETIME_PATTERN = DATETIME_PATTERN;
 exports.DATE_PATTERN = DATE_PATTERN;
 exports.EMAIL_PATTERN = EMAIL_PATTERN;
+exports.FIELD_BASE_KEYS = FIELD_BASE_KEYS;
 exports.FIELD_CONTROLS = FIELD_CONTROLS;
+exports.FIELD_KEYS = FIELD_KEYS;
 exports.FIELD_LIMIT = FIELD_LIMIT;
 exports.FORM_STATUSES = FORM_STATUSES;
 exports.Form = Form;
@@ -1729,12 +1700,15 @@ exports.cloneFormField = cloneFormField;
 exports.cloneFormSchema = cloneFormSchema;
 exports.cloneValue = cloneValue;
 exports.computeDefaults = computeDefaults;
+exports.createFieldError = createFieldError;
 exports.createForm = createForm;
+exports.defineEntry = defineEntry;
 exports.evaluateField = evaluateField;
 exports.evaluateForm = evaluateForm;
 exports.extractChanges = extractChanges;
 exports.extractGroups = extractGroups;
 exports.formatMessage = formatMessage;
+exports.freezeEntry = freezeEntry;
 exports.isFieldChoice = isFieldChoice;
 exports.isFieldControl = isFieldControl;
 exports.isFieldError = isFieldError;