@jini-ai/cms 0.5.5 → 0.5.7

package/dist/forms/forms.js

@@ -1,3 +1,5 @@
+import { FIELD_TYPE_REGISTRY, resolveFormField } from "./field-registry.js";
+import { commonDescriptorErrors } from "./descriptor-rules.js";
 // Domain validation stays independent of feature manifests, and returns decisions without I/O
 // or exceptions so write and submission services can choose their own error presentation.
 // Published tool schemas and render-time defensive checks use these exported bounds/patterns
@@ -9,7 +11,7 @@ export const MAX_LABEL_LENGTH = 200;
 export const MIN_MAX_LENGTH = 1;
 export const MAX_MAX_LENGTH = 5000;
 export const FIELD_ID_PATTERN = /^[a-z][a-z0-9_]*$/;
-export const FIELD_TYPES = new Set(["text", "email", "textarea", "checkbox"]);
+export const FIELD_TYPES = new Set(Object.keys(FIELD_TYPE_REGISTRY));
 export const MAX_CLASS_NAME_LENGTH = 300;
 export const MAX_ATTRIBUTES_PER_FIELD = 12;
 export const MAX_ATTRIBUTE_VALUE_LENGTH = 300;
@@ -25,7 +27,7 @@ export const HONEYPOT_KEY = "_hp";
 // Malformed IDs are never claimed: repeated malformed IDs must each report their shape error
 // rather than misleading the second field's author with a duplicate-ID diagnosis.
 function fieldIdErrors(descriptor, label, claimedIds) {
-    if (!descriptor.id || !FIELD_ID_PATTERN.test(descriptor.id)) {
+    if (typeof descriptor.id !== "string" || !descriptor.id || !FIELD_ID_PATTERN.test(descriptor.id)) {
         return [{ field: label, reason: "id must match ^[a-z][a-z0-9_]*$" }];
     }
     if (claimedIds.has(descriptor.id)) {
@@ -41,6 +43,8 @@ function fieldTypeErrors(descriptor, label) {
     return [];
 }
 function labelLengthErrors(descriptor, label) {
+    if (typeof descriptor.label !== "string")
+        return [{ field: label, reason: "label must be a string" }];
     if (descriptor.label.length < MIN_LABEL_LENGTH || descriptor.label.length > MAX_LABEL_LENGTH) {
         return [{ field: label, reason: `label must be ${MIN_LABEL_LENGTH}-${MAX_LABEL_LENGTH} characters` }];
     }
@@ -117,7 +121,9 @@ function attributeErrors(descriptor, label) {
  * Empty helper results mean a satisfied rule. Bounds are 1-20 fields, labels 1-200 characters,
  * and maxLength 1-5000 (never on checkboxes), with unique lowercase field IDs.
  */
-export function validateFieldDescriptors({ fields }) {
+export function validateFieldDescriptors({ fields }, _optional = {}) {
+    if (!Array.isArray(fields))
+        return { valid: false, fieldErrors: [{ field: "fields", reason: "must be an array" }] };
     const fieldErrors = [];
     if (fields.length < MIN_FIELDS) {
         fieldErrors.push({ field: "fields", reason: `at least ${MIN_FIELDS} field is required` });
@@ -127,85 +133,62 @@ export function validateFieldDescriptors({ fields }) {
     }
     const claimedIds = new Set();
     for (const descriptor of fields) {
+        if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
+            fieldErrors.push({ field: "fields", reason: "each field must be an object" });
+            continue;
+        }
         const label = descriptor.id || "(unknown)";
-        fieldErrors.push(...fieldIdErrors(descriptor, label, claimedIds), ...fieldTypeErrors(descriptor, label), ...labelLengthErrors(descriptor, label), ...maxLengthErrors(descriptor, label), ...checkboxValueErrors(descriptor, label), ...classNameErrors(descriptor, label), ...attributeErrors(descriptor, label));
+        fieldErrors.push(...fieldIdErrors(descriptor, label, claimedIds), ...fieldTypeErrors(descriptor, label), ...labelLengthErrors(descriptor, label), ...maxLengthErrors(descriptor, label), ...checkboxValueErrors(descriptor, label), ...classNameErrors(descriptor, label), ...attributeErrors(descriptor, label), ...commonDescriptorErrors({ field: descriptor }));
     }
     if (fieldErrors.length > 0)
         return { valid: false, fieldErrors };
     return { valid: true };
 }
+// Absence is distinct from acceptance: treating an omitted optional field as an accepted value
+// would write undefined and violate the guarantee that stored answers contain only declared keys.
 // The honeypot is tolerated in the raw body, but is excluded from stored answers.
-function unregisteredKeyErrors(body, fieldsById) {
-    const errors = [];
-    for (const key of Object.keys(body)) {
-        if (key === HONEYPOT_KEY)
-            continue;
-        if (!fieldsById.has(key)) {
-            errors.push({ field: key, reason: "unregistered_key" });
-        }
-    }
-    return errors;
-}
 // Whitespace is rejected only for required text; optional whitespace is an answer the definition
 // permits. Preserve the submitted string instead of silently trimming its stored value.
-function resolveTextValue(field, value) {
-    if (typeof value !== "string")
-        return { kind: "rejected", reason: "must be a string" };
-    if (field.required && value.trim() === "")
-        return { kind: "rejected", reason: "required" };
-    if (field.maxLength != null && value.length > field.maxLength)
-        return { kind: "rejected", reason: "too_long" };
-    return { kind: "accepted", value };
-}
 // Native URL-encoded forms submit "on" for checked boxes without a value attribute; accepting
 // only JSON booleans would reject every checked checkbox when client JavaScript is disabled.
 // An unticked native checkbox omits its key; submission resolution treats that as absence.
-const HTML_CHECKBOX_ON_VALUE = "on";
-function resolveCheckboxValue(field, value) {
-    if (field.checkboxValue !== undefined && typeof value === "string")
-        return { kind: "accepted", value };
-    if (typeof value === "boolean")
-        return { kind: "accepted", value };
-    if (value === HTML_CHECKBOX_ON_VALUE)
-        return { kind: "accepted", value: true };
-    return { kind: "rejected", reason: "must be a boolean" };
-}
 // JSON and native forms differ in how they represent missing values, so null/undefined both
-// mean absence. Boolean false is a real checkbox answer, including for a required checkbox.
-function resolveSubmittedValue(field, value) {
-    if (value === undefined || value === null) {
-        return field.required ? { kind: "rejected", reason: "required" } : { kind: "absent" };
-    }
-    if (field.type === "checkbox")
-        return resolveCheckboxValue(field, value);
-    return resolveTextValue(field, value);
+// mean absence. Boolean false is a real checkbox answer, only for optional native checkboxes; required consent must be checked.
+function unregisteredKeyErrors(body, fieldsById) {
+    return Object.keys(body).filter((key) => key !== HONEYPOT_KEY && !fieldsById.has(key)).map((field) => ({ field, reason: "unregistered_key" }));
 }
 /**
  * Only declared, accepted fields reach data; the reserved honeypot never does. Report unknown
  * body keys first, then declared-field errors in definition order, independent of body key order.
  * This keeps the declared-field portion of the error list stable across equivalent submissions.
  */
-export function validateSubmissionPayload(input) {
+export function validateSubmissionPayload(input, optional = {}) {
     const { definition, body } = input;
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return { valid: false, fieldErrors: [{ field: "body", reason: "must be an object" }] };
     const fieldsById = new Map(definition.fields.map((f) => [f.id, f]));
     const fieldErrors = unregisteredKeyErrors(body, fieldsById);
     const data = {};
+    const files = {};
     for (const field of definition.fields) {
-        const resolved = resolveSubmittedValue(field, body[field.id]);
+        const resolved = resolveFormField({ field, value: Object.hasOwn(body, field.id) ? body[field.id] : undefined }, optional);
         if (resolved.kind === "rejected") {
             fieldErrors.push({ field: field.id, reason: resolved.reason });
         }
         else if (resolved.kind === "accepted") {
             data[field.id] = resolved.value;
         }
+        else if (resolved.kind === "upload") {
+            files[field.id] = resolved.file;
+        }
     }
     if (fieldErrors.length > 0)
         return { valid: false, fieldErrors };
-    return { valid: true, data };
+    return Object.keys(files).length ? { valid: true, data, files } : { valid: true, data };
 }
 // Only a non-empty trimmed string trips the trap; absent, non-string or whitespace-only values
 // do not reject an otherwise valid submission.
-export function isHoneypotTripped(input) {
+export function isHoneypotTripped(input, _optional = {}) {
     if (typeof input.hp !== "string")
         return false;
     return input.hp.trim().length > 0;

package/dist/forms/html/html-authoring.js

@@ -3,6 +3,7 @@
  * Prototype belongs in @jini-ai/cms/forms later; its published release lacks HTML authoring. */
 import { parseFragment, serialize } from "parse5";
 import { FormFieldValidationError } from "../errors.js";
+import { FIELD_TYPE_REGISTRY } from "../field-registry.js";
 export { decodeFormFields, encodeFormFields } from "../fields-json.js";
 function invalid(reason) {
     throw new FormFieldValidationError({ message: reason, fieldErrors: [{ field: "html", reason }] });
@@ -37,6 +38,18 @@ function labelText(node) {
     }
     return text.trim();
 }
+/** Read only the nearest fieldset's direct legend; blank/missing text keeps control-label fallback.
+ * No I/O or mutation; O(d + c + t) time for ancestor depth, fieldset children and legend text,
+ * with labelText's O(t) traversal space. */
+function groupLabel({ element }, _optional = {}) {
+    for (let parent = element.parentNode; parent && "tagName" in parent; parent = parent.parentNode) {
+        if (parent.tagName !== "fieldset")
+            continue;
+        const legend = parent.childNodes.find((child) => "tagName" in child && child.tagName === "legend");
+        return legend ? labelText(legend) || undefined : undefined;
+    }
+    return undefined;
+}
 /** Keep the author's required-attribute spelling while retaining parser normalization that
  * discards dangling outer form closers. Both attribute ranges come from parse5, not a regex
  * that could mistake a script string for a control. No attribute value is synthesized here. */
@@ -97,14 +110,23 @@ export function deriveHtmlForm({ html }, _optional = {}) {
             element.attrs = element.attrs.filter((attribute) => attribute.name !== "name");
             continue;
         }
-        if (element.tagName === "input" && ["file", "password"].includes(inputType))
-            invalid(`Input type '${inputType}' is not supported`);
-        if (element.tagName === "select" && attr(element, "multiple") !== undefined)
-            invalid("Multiple selections are not supported");
-        if (fields.has(name)) {
-            if (inputType === "radio" && fields.get(name)?.type === "text") {
-                const group = fields.get(name);
-                group.required = group.required || attr(element, "required") !== undefined;
+        if (element.tagName === "input" && inputType === "password")
+            invalid("Password fields are not supported");
+        const existing = fields.get(name);
+        if (existing) {
+            // Radio/checkbox controls share a successful-control name by design; collect their allowed
+            // values rather than admitting arbitrary strings as the old HTML compatibility view did.
+            if (inputType === "radio" && existing.type === "radio" || inputType === "checkbox" && ["checkbox", "checkbox-group"].includes(existing.type)) {
+                const value = attr(element, "value") ?? "on";
+                if (existing.type === "checkbox") {
+                    existing.type = "checkbox-group";
+                    existing.options = [{ value: existing.checkboxValue ?? "on", label: existing.label }];
+                    // Seed option one before replacing its standalone label with the group's legend.
+                    existing.label = groupLabel({ element }) ?? existing.label;
+                    delete existing.checkboxValue;
+                }
+                existing.options.push({ value, label: element.parentNode && "tagName" in element.parentNode && element.parentNode.tagName === "label" ? labelText(element.parentNode) || value : value });
+                existing.required = existing.required || attr(element, "required") !== undefined;
                 continue;
             }
             invalid(`Duplicate field name '${name}'`);
@@ -117,14 +139,42 @@ export function deriveHtmlForm({ html }, _optional = {}) {
             ? element.parentNode : undefined;
         const label = labels.find((item) => id !== undefined && attr(item, "for") === id) ?? parentLabel;
         const maxLength = attr(element, "maxlength");
-        fields.set(name, {
+        const type = element.tagName === "select" ? (attr(element, "multiple") !== undefined ? "multi-select" : "select")
+            : element.tagName === "textarea" ? "textarea"
+                : inputType === "checkbox" && attr(element, "role") === "switch" ? "toggle"
+                    : Object.entries(FIELD_TYPE_REGISTRY).find(([, kind]) => kind.control === "input" && kind.htmlType === inputType)?.[0] ?? (inputType === "radio" ? "radio" : "text");
+        const choices = element.tagName === "select" ? elements(element.childNodes).filter((child) => child.tagName === "option").map((option) => ({ value: attr(option, "value") ?? labelText(option), label: labelText(option) })).filter((option) => option.value !== "")
+            : inputType === "radio" ? [{ value: attr(element, "value") ?? "on", label: label ? labelText(label) || name : attr(element, "value") ?? "on" }] : undefined;
+        const numeric = type === "number" || type === "range";
+        const descriptor = {
             id: name,
-            label: label ? labelText(label) || name : attr(element, "aria-label") || name,
-            type: element.tagName === "textarea" ? "textarea" : inputType === "email" ? "email" : inputType === "checkbox" ? "checkbox" : "text",
+            label: (type === "radio" ? groupLabel({ element }) : undefined) ?? (label ? labelText(label) || name : attr(element, "aria-label") || name),
+            type,
             required: attr(element, "required") !== undefined,
-            ...(checkboxValue !== undefined ? { checkboxValue } : {}),
+            ...(checkboxValue !== undefined && type === "checkbox" ? { checkboxValue } : {}),
             ...(maxLength !== undefined ? { maxLength: Number(maxLength) } : {}),
-        });
+            ...(choices ? { options: choices } : {}),
+        };
+        for (const key of ["placeholder", "pattern"]) {
+            const value = attr(element, key);
+            if (value !== undefined)
+                descriptor[key] = value;
+        }
+        for (const key of ["min", "max"]) {
+            const value = attr(element, key);
+            if (value !== undefined)
+                descriptor[key] = numeric ? Number(value) : value;
+        }
+        const minLength = attr(element, "minlength");
+        if (minLength !== undefined)
+            descriptor.minLength = Number(minLength);
+        const step = attr(element, "step");
+        if (step !== undefined)
+            descriptor.step = Number(step);
+        const accept = attr(element, "accept");
+        if (accept !== undefined && type === "file")
+            descriptor.accept = accept.split(",").map((item) => item.trim());
+        fields.set(name, descriptor);
     }
     // Re-serialization also discards ignored/dangling </form> tokens: they must never close our
     // server-owned wrapper early. Raw-text script contents are preserved by the HTML serializer.

package/dist/forms/html/html-submission-adapter.d.ts

@@ -1,9 +1,9 @@
 import type { FormDefinitionRecord } from "../index.js";
-/** Compatibility for the installed Jini release, which accepts boolean checkbox answers only.
- * Jini's next release natively reads checkboxValue; until then this CMS HTML adapter presents
- * authored checkbox strings as text to the same validator. It changes no durable descriptor.
- * Empty authored values are successful controls; missing required controls must still fail. */
-export declare function htmlSubmissionDefinition({ definition, body }: {
+/** Earlier published releases accepted boolean checkbox answers only, so their HTML view
+ * presented authored strings as text. The field registry now natively validates checkboxValue,
+ * choice options and file types. Keep this public adapter as identity for host compatibility:
+ * changing a choice to text here would bypass the server's declared-value allowlist. */
+export declare function htmlSubmissionDefinition({ definition }: {
     definition: FormDefinitionRecord;
     body: Record<string, unknown>;
 }, _optional?: {}): FormDefinitionRecord;

package/dist/forms/html/html-submission-adapter.js

@@ -1,15 +1,8 @@
-/** Compatibility for the installed Jini release, which accepts boolean checkbox answers only.
- * Jini's next release natively reads checkboxValue; until then this CMS HTML adapter presents
- * authored checkbox strings as text to the same validator. It changes no durable descriptor.
- * Empty authored values are successful controls; missing required controls must still fail. */
-export function htmlSubmissionDefinition({ definition, body }, _optional = {}) {
-    if (definition.mode !== "html")
-        return definition;
-    return { ...definition, fields: definition.fields.map((field) => {
-            const checkbox = field;
-            if (field.type !== "checkbox" || checkbox.checkboxValue === undefined || typeof body[field.id] !== "string")
-                return field;
-            return { ...field, type: "text", required: false };
-        }) };
+/** Earlier published releases accepted boolean checkbox answers only, so their HTML view
+ * presented authored strings as text. The field registry now natively validates checkboxValue,
+ * choice options and file types. Keep this public adapter as identity for host compatibility:
+ * changing a choice to text here would bypass the server's declared-value allowlist. */
+export function htmlSubmissionDefinition({ definition }, _optional = {}) {
+    return definition;
 }
 //# sourceMappingURL=html-submission-adapter.js.map

package/dist/forms/html-render.d.ts

@@ -12,12 +12,19 @@ export interface FormHtmlHooks {
 export declare function escapeFormHtml({ value }: {
     value: string;
 }, _optional?: {}): string;
+/** Renderer hooks retain the CMS's established styling/error anchors without defining a theme. */
+export interface FormBodyOptions {
+    submitLabel?: string;
+    idPrefix?: string;
+    fieldClass?: string;
+    errorClass?: string;
+}
+/** Shared body for authored and builder forms; every field's HTML semantics come from the registry.
+ * @complexity O(f + o) for fields and their bounded option lists, no I/O. */
 export declare function renderHtmlFormBody({ fields, hooks }: {
     fields: readonly FieldDescriptor[];
     hooks: Pick<FormHtmlHooks, "field">;
-}, { submitLabel }?: {
-    submitLabel?: string;
-}): string;
+}, options?: FormBodyOptions): string;
 /** `className` is the host's styling hook (the host passes its form CSS class so the active theme's form rules
  * apply); author CSS stays free to override it. Whitespace-separated, de-duplicated, never replaced. */
 export declare function renderHtmlForm({ slug, fields, action, hooks }: {

package/dist/forms/html-render.js

@@ -1,18 +1,86 @@
+import { FIELD_TYPE_REGISTRY, isSafeFieldPattern } from "./field-registry.js";
+import { ATTRIBUTE_NAME_PATTERN } from "./forms.js";
 export function escapeFormHtml({ value }, _optional = {}) {
     return value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
 }
-export function renderHtmlFormBody({ fields, hooks }, { submitLabel = "Send" } = {}) {
-    return fields.map((field) => {
-        const name = escapeFormHtml({ value: field.id });
-        const label = escapeFormHtml({ value: field.label });
-        const required = field.required ? " required" : "";
-        const maxLength = field.maxLength != null ? ` maxlength="${field.maxLength}"` : "";
-        const attributes = `name="${name}" ${hooks.field}="${name}" toolparamtitle="${label}" toolparamdescription="${label}"${required}${maxLength}`;
-        const control = field.type === "textarea"
-            ? `<textarea ${attributes}></textarea>`
-            : `<input type="${field.type}" ${attributes}>`;
-        return `<label>${label}${control}</label>`;
-    }).join("\n") + `\n<button type="submit">${escapeFormHtml({ value: submitLabel })}</button>`;
+const attr = (name, value) => ` ${name}="${escapeFormHtml({ value: String(value) })}"`;
+/** Extra attributes cannot override structural or server-backed constraints. Values are escaped at this sink. */
+function extraAttributes(field, claimed) {
+    return Object.entries(field.attributes ?? {}).filter(([name, value]) => ATTRIBUTE_NAME_PATTERN.test(name) && !claimed.has(name) && typeof value === "string" && (name !== "pattern" || isSafeFieldPattern({ pattern: value }))).map(([name, value]) => attr(name, value)).join("");
+}
+/** One registry control rendered with label/legend, help/error associations and escaped defaults. */
+function renderField(field, hooks, options) {
+    if (!field || typeof field.id !== "string" || typeof field.label !== "string" || !Object.hasOwn(FIELD_TYPE_REGISTRY, field.type))
+        return "";
+    const kind = FIELD_TYPE_REGISTRY[field.type];
+    const id = `${options.idPrefix ?? "form"}-${field.id}`;
+    const helpId = `${id}-help`;
+    const errorId = `${id}-error`;
+    const label = escapeFormHtml({ value: field.label });
+    const describedBy = [field.helpText ? helpId : "", errorId, field.attributes?.["aria-describedby"] ?? ""].filter(Boolean).join(" ");
+    const required = field.required ? " required" : "";
+    const base = attr("name", field.name ?? field.id) + attr(hooks.field, field.id) + attr("toolparamtitle", field.label) + attr("toolparamdescription", field.helpText ?? field.label) + attr("aria-describedby", describedBy);
+    const constraints = [
+        ["placeholder", field.placeholder], ["minlength", field.minLength], ["maxlength", field.maxLength], ["pattern", field.pattern],
+        ["min", field.min], ["max", field.max], ["step", field.step],
+    ];
+    const claimed = new Set(["aria-describedby"]);
+    let extra = field.className ? attr("class", field.className) : "";
+    for (const [name, value] of constraints) {
+        if (value == null)
+            continue;
+        if (name === "maxlength" && (!Number.isInteger(value) || Number(value) <= 0))
+            continue;
+        if (name === "minlength" && (!Number.isInteger(value) || Number(value) < 0))
+            continue;
+        if (name === "pattern" && !isSafeFieldPattern({ pattern: String(value) }))
+            continue;
+        extra += attr(name, value);
+        claimed.add(name);
+    }
+    extra += extraAttributes(field, claimed);
+    const help = field.helpText ? `<div${attr("id", helpId)} class="widget-form-field-help">${escapeFormHtml({ value: field.helpText })}</div>` : "";
+    const error = `<div${attr("class", options.errorClass ?? "widget-form-field-error")}${attr("data-field", field.id)}${attr("id", errorId)} hidden></div>`;
+    const defaultValues = Array.isArray(field.default) ? field.default : [field.default];
+    let control;
+    if (kind.control === "group") {
+        const inputs = (field.options ?? []).map((option, index) => {
+            const optionId = `${id}-${index}`;
+            const checked = defaultValues.includes(option.value) ? " checked" : "";
+            // Native checkbox-group required on each box means ALL, so server enforces one-or-more;
+            // aria-required communicates the group's requirement without changing that invariant.
+            const optionRequired = kind.multiple ? "" : required;
+            return `<label${attr("for", optionId)}><input${attr("id", optionId)}${attr("type", kind.htmlType)}${base}${attr("value", option.value)}${checked}${optionRequired}${extra}>${escapeFormHtml({ value: option.label })}</label>`;
+        }).join("");
+        return `<fieldset${attr("id", id)}${attr("class", options.fieldClass ?? "widget-form-field")}${attr("aria-describedby", describedBy)}${field.required ? ' aria-required="true"' : ""}><legend>${label}${field.required ? " *" : ""}</legend>${inputs}${help}${error}</fieldset>`;
+    }
+    if (kind.control === "select") {
+        const placeholder = kind.multiple ? "" : `<option value="">${escapeFormHtml({ value: field.placeholder ?? "Choose an option" })}</option>`;
+        const choices = (field.options ?? []).map((option) => `<option${attr("value", option.value)}${defaultValues.includes(option.value) ? " selected" : ""}>${escapeFormHtml({ value: option.label })}</option>`).join("");
+        control = `<select${attr("id", id)}${base}${kind.multiple ? " multiple" : ""}${required}${extra}>${placeholder}${choices}</select>`;
+    }
+    else if (kind.control === "textarea") {
+        control = `<textarea${attr("id", id)}${base}${required}${extra}>${escapeFormHtml({ value: String(field.default ?? "") })}</textarea>`;
+    }
+    else {
+        let value = field.default !== undefined ? attr("value", String(field.default)) : "";
+        if (kind.htmlType === "checkbox")
+            value = (field.checkboxValue !== undefined ? attr("value", field.checkboxValue) : "") + (field.default === true || field.default === field.checkboxValue && field.default !== undefined ? " checked" : "");
+        if (field.type === "file")
+            value = field.accept ? attr("accept", field.accept.join(",")) : "";
+        control = `<input${attr("type", kind.htmlType)}${attr("id", id)}${base}${field.type === "toggle" ? ' role="switch"' : ""}${required}${value}${extra}>`;
+    }
+    if (field.type === "hidden")
+        return control;
+    // The checkbox modifier lets the baseline put the box before its label on one line (owner report
+    // 2026-10-05: stacked and stretched like a text input, its glyph drew centred under the label).
+    const fieldClass = (options.fieldClass ?? "widget-form-field") + (kind.htmlType === "checkbox" ? " widget-form-field-checkbox" : "");
+    return `<div${attr("class", fieldClass)}><label${attr("for", id)}>${label}${field.required ? " *" : ""}</label>${control}${help}${error}</div>`;
+}
+/** Shared body for authored and builder forms; every field's HTML semantics come from the registry.
+ * @complexity O(f + o) for fields and their bounded option lists, no I/O. */
+export function renderHtmlFormBody({ fields, hooks }, options = {}) {
+    return fields.map((field) => renderField(field, hooks, options)).join("\n") + `\n<button type="submit">${escapeFormHtml({ value: options.submitLabel ?? "Send" })}</button>`;
 }
 /** `className` is the host's styling hook (the host passes its form CSS class so the active theme's form rules
  * apply); author CSS stays free to override it. Whitespace-separated, de-duplicated, never replaced. */
@@ -22,10 +90,44 @@ export function renderHtmlForm({ slug, fields, action, hooks }, { html, successM
     const classes = [...new Set((className ?? "").split(/\s+/).filter(Boolean))].join(" ");
     const classAttr = classes ? `class="${escapeFormHtml({ value: classes })}" ` : "";
     return `<div ${hooks.success} ${slugHook} role="status" hidden>${escapeFormHtml({ value: successMessage })}</div>` +
-        `<form ${classAttr}${hooks.form}="${escapedSlug}" ${slugHook} toolname="form_${escapeFormHtml({ value: slug.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 123) })}" tooldescription="${escapedSlug}" method="post" action="${escapeFormHtml({ value: action })}">` +
+        `<form ${classAttr}${hooks.form}="${escapedSlug}" ${slugHook} toolname="form_${escapeFormHtml({ value: slug.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 123) })}" tooldescription="${escapedSlug}" method="post"${fields.some((field) => field.type === "file") ? ' enctype="multipart/form-data"' : ""} action="${escapeFormHtml({ value: action })}">` +
         `<div ${hooks.error} ${slugHook} role="alert" hidden></div>` +
-        (html ?? renderHtmlFormBody({ fields, hooks })) +
+        (html ?? renderHtmlFormBody({ fields, hooks }, { idPrefix: `form-${slug}` })) +
         // Hidden container requires neither a theme class nor inline CSS; bots still see the input.
         `<div hidden aria-hidden="true"><input type="text" name="_hp" tabindex="-1" autocomplete="off"></div></form>`;
 }
+/* Migration rationale retained from the host renderer:
+
+ * Renders one field descriptor's `class`/extra-attribute string, both attached to the SAME
+ * rendered input element the field's own `id`/`name`/`required`/`type` already get. Re-checks
+ * `ATTRIBUTE_NAME_PATTERN` here rather than trusting that every stored field passed through
+ * `forms.ts`'s `validateFieldDescriptors` (this is the public render path, REQ-37/ADR-047) —
+ * defense in depth, since an attribute NAME is not something `escapeHtml` can make safe the way it
+ * can a value (`onclick` is structurally dangerous regardless of how its own text is escaped).
+ * `className` carries no such risk once escaped, so it is not re-validated, only escaped.
+
+ One `<textarea>`/checkbox/text-or-email `<input>` for a contact-form field descriptor — pulled out
+ *  of {@link renderField}'s old three-way nested ternary so each shape is a flat, separately
+ *  readable branch rather than one expression whose nesting depth drove the field-renderer's cognitive
+ *  complexity. `requiredAttr` is computed once and reused across all three shapes, same value the old
+ *  nested ternary recomputed per-branch. `describedByAttr` wires the field to its own (initially empty
+ *  and hidden) error slot for assistive tech — see {@link renderField}'s own doc for why
+ *  that slot exists even though nothing fills it in on the very first render.
+ The field's own `maxLength` as a `maxlength` attribute, so the browser stops input at the same
+ *  limit `forms.ts`'s `validateSubmissionPayload` enforces (`too_long`) instead of letting a visitor
+ *  type past it and lose the submission to a server rejection. Only a positive integer renders —
+ *  the value comes from stored JSON, so anything else is dropped rather than interpolated.
+ *  @complexity O(1).
+ One contact-form field descriptor -> its `<div class="widget-form-field">` markup — extracted from
+ *  {@link renderWidgetContactForm}'s old inline `.map()` callback so the field's own render logic is a
+ *  named, independently measured function rather than an anonymous closure.
+ *
+ *  Carries its own `<div class="widget-form-field-error" data-field="ID" hidden></div>` slot, hidden
+ *  and empty on every ordinary render — `renderWidgetContactForm` has no request in scope (this is a
+ *  pure prop-to-HTML function, no I/O), so it cannot know at render time whether THIS submission
+ *  failed validation on THIS field. The slot exists purely as a stable, pre-built anchor
+ *  {@link injectFormSubmissionResultIntoHtml} fills in and un-hides after the fact, on the
+ *  Post/Redirect/Get reload that follows a failed submission (see that function's own doc for the
+ *  full mechanism).
+ */
 //# sourceMappingURL=html-render.js.map

package/dist/forms/index.d.ts

@@ -14,4 +14,5 @@ export * from "./submission-email-validation.js";
 export * from "./delete-submission.js";
 export * from "./duplicate-slug.js";
 export * from "./repo.memory.js";
+export * from "./field-registry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/forms/index.js

@@ -14,4 +14,5 @@ export * from "./submission-email-validation.js";
 export * from "./delete-submission.js";
 export * from "./duplicate-slug.js";
 export * from "./repo.memory.js";
+export * from "./field-registry.js";
 //# sourceMappingURL=index.js.map

package/dist/forms/repo.memory.js

@@ -4,7 +4,7 @@ import { FormSlugConflictError } from "./errors.js";
 function cloneStored(row) {
     return {
         ...row,
-        fields: row.fields.map((f) => ({ ...f })),
+        fields: structuredClone(row.fields),
         notify: { ...row.notify, recipients: [...row.notify.recipients] },
     };
 }
@@ -95,12 +95,12 @@ export class InMemoryFormDefinitionRepo {
     }
 }
 function cloneSubmission(row) {
-    return { ...row, data: { ...row.data } };
+    return { ...row, data: structuredClone(row.data) };
 }
 /** The port's view of a stored row: the Trash columns stay inside this adapter. */
 function toSubmissionRecord(row) {
     const { deletedAt: _deletedAt, version: _version, ...record } = row;
-    return { ...record, data: { ...record.data } };
+    return { ...record, data: structuredClone(record.data) };
 }
 export class InMemoryFormSubmissionRepo {
     rows = new Map();
@@ -113,7 +113,7 @@ export class InMemoryFormSubmissionRepo {
         return toSubmissionRecord(row);
     }
     async create(record) {
-        this.rows.set(record.id, { ...record, data: { ...record.data }, deletedAt: null, version: 1 });
+        this.rows.set(record.id, { ...record, data: structuredClone(record.data), deletedAt: null, version: 1 });
     }
     /** Rolls this repo's rows back when `work` throws, as the SQL adapter's transaction does. Calls
      *  take turns (as the SQLite kernel's do) so one rollback cannot erase another call's row; a

package/dist/forms/submission-attempts.d.ts

@@ -49,7 +49,7 @@ export interface SubmissionAttempts {
  * The key one attempt is remembered under: a SHA-256 of workspace, slug, source IP, attempt token
  * (null when the request carried none) and the body. Body keys are sorted so their order cannot
  * change the key. Held only in memory, only for the window.
- * @complexity O(b log b) for b body keys.
+ * @complexity O(b log b + n) for b body keys and n uploaded bytes, hashed in 8 KiB chunks.
  */
 export declare function submissionAttemptKey({ input, attemptToken, hash }: {
     input: SubmitFormInput;

package/dist/forms/submission-attempts.js

@@ -10,11 +10,22 @@ export const DUPLICATE_ATTEMPT = Symbol("duplicate form submission attempt");
  * The key one attempt is remembered under: a SHA-256 of workspace, slug, source IP, attempt token
  * (null when the request carried none) and the body. Body keys are sorted so their order cannot
  * change the key. Held only in memory, only for the window.
- * @complexity O(b log b) for b body keys.
+ * @complexity O(b log b + n) for b body keys and n uploaded bytes, hashed in 8 KiB chunks.
  */
 export function submissionAttemptKey({ input, attemptToken, hash }, _optional = {}) {
     // Object keys are unique, so the comparator never sees a tie.
-    const body = Object.entries(input.body).sort(([a], [b]) => (a < b ? -1 : 1));
+    const body = Object.entries(input.body).map(([key, value]) => {
+        if (!value || typeof value !== "object" || !("bytes" in value) || !(value.bytes instanceof Uint8Array))
+            return [key, value];
+        // Hash bounded chunks rather than JSON-encoding millions of Uint8Array index properties.
+        // Chunk order and byte length remain bound to the digest; no uploaded bytes are remembered.
+        const digests = [];
+        for (let offset = 0; offset < value.bytes.byteLength; offset += 8192) {
+            digests.push(hash(String.fromCharCode(...value.bytes.subarray(offset, offset + 8192))));
+        }
+        const { bytes, ...metadata } = value;
+        return [key, { ...metadata, byteLength: bytes.byteLength, bytesHash: hash(JSON.stringify(digests)) }];
+    }).sort(([a], [b]) => (a < b ? -1 : 1));
     return hash(JSON.stringify([input.workspaceId, input.slug, input.sourceIp, attemptToken ?? null, body]));
 }
 /**

package/dist/forms/submission-email-validation.js

@@ -1,8 +1,6 @@
 import { FormSubmissionValidationError } from "./errors.js";
 import { isHoneypotTripped, validateSubmissionPayload } from "./forms.js";
-// Match native type=email syntax (WHATWG HTML email state), including single-label domains.
-// Do not trim or rewrite answers: Jini's payload contract preserves submitted strings.
-const EMAIL_PATTERN = /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+import { isValidFormEmail } from "./email-format.js";
 /** Compatibility guard until Jini validates email fields itself. Lookup remains the first step;
  * disabled forms and honeypots retain the package's response before any validation or writes. */
 export function assertSubmissionEmails({ definition, body }, _optional = {}) {
@@ -17,7 +15,7 @@ export function assertSubmissionEmails({ definition, body }, _optional = {}) {
         if (existing.some((error) => error.field === field.id))
             return false;
         // JS's $ can match before a final newline; comparing the full match refuses that bypass.
-        return EMAIL_PATTERN.exec(value)?.[0] !== value;
+        return !isValidFormEmail({ value });
     }).map((field) => field.id));
     if (invalid.size === 0)
         return;

package/dist/forms/submit-service.d.ts

@@ -27,6 +27,7 @@ import type { Clock, IdGenerator, UUID } from "@jini-ai/core/primitives";
 import type { FormDefinitionRepoPort, FormSubmissionRepoPort } from "./ports.js";
 import type { FormDefinitionViewPort } from "./ports.js";
 import { type SubmissionAttempts } from "./submission-attempts.js";
+import type { FormFileStoragePort } from "./types.js";
 export interface SubmitFormDeps {
     definitionRepo: FormDefinitionRepoPort;
     submissionRepo: FormSubmissionRepoPort;
@@ -36,6 +37,8 @@ export interface SubmitFormDeps {
     clock: Clock;
     idGen: IdGenerator;
     rateLimiter: RateLimiterPort;
+    /** Anonymous uploads go through the host media owner only after validation/rate/dedupe. */
+    files?: FormFileStoragePort;
     /** Omitted: the two writes run back to back with no rollback between them. */
     transaction?: SubmissionTransactionPort;
 }