@jini-ai/cms 0.5.3 → 0.5.4

package/dist/forms/fields-json.js

@@ -0,0 +1,11 @@
+/** Old rows remain arrays; authored forms use the same JSON-in-text column, without a migration. */
+export function decodeFormFields({ json }, _optional = {}) {
+    const stored = JSON.parse(json);
+    return Array.isArray(stored) ? { fields: stored } : { fields: stored.fields, mode: stored.mode, html: stored.html };
+}
+export function encodeFormFields({ definition }, _optional = {}) {
+    return JSON.stringify(definition.mode === "html"
+        ? { fields: definition.fields, mode: "html", html: definition.html ?? "" }
+        : definition.fields);
+}
+//# sourceMappingURL=fields-json.js.map

package/dist/forms/forms.d.ts

@@ -0,0 +1,59 @@
+/** Pure field/submission validation and honeypot decisions. Error order and stored value normalization are stable. */
+import type { FieldDescriptor, FormDefinitionRecord } from "./types.js";
+export declare const MAX_FIELDS = 20;
+export declare const MAX_LABEL_LENGTH = 200;
+export declare const MIN_MAX_LENGTH = 1;
+export declare const MAX_MAX_LENGTH = 5000;
+export declare const FIELD_ID_PATTERN: RegExp;
+export declare const FIELD_TYPES: Set<string>;
+export declare const MAX_CLASS_NAME_LENGTH = 300;
+export declare const MAX_ATTRIBUTES_PER_FIELD = 12;
+export declare const MAX_ATTRIBUTE_VALUE_LENGTH = 300;
+/**
+ * Escaping makes an attribute value inert, but cannot make a name such as onclick safe. Names
+ * are deny-by-default: only aria-* and data-* namespaces and a fixed closed list are accepted.
+ * Event handlers, style/formaction/href/src/srcdoc can inject behavior; id/name/type overrides
+ * can break label association, submission keys or the renderer's declared field vocabulary.
+ */
+export declare const ATTRIBUTE_NAME_PATTERN: RegExp;
+export declare const HONEYPOT_KEY = "_hp";
+export interface FieldError {
+    field: string;
+    reason: string;
+}
+export type FieldValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    fieldErrors: FieldError[];
+};
+/**
+ * Collect every violation, not just the first: arity errors, then descriptors in array order,
+ * then each rule in the fixed order below. Callers display this list as-is, so order is observable.
+ * 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 declare function validateFieldDescriptors({ fields }: {
+    fields: FieldDescriptor[];
+}): FieldValidationResult;
+export interface ValidateSubmissionPayloadInput {
+    definition: FormDefinitionRecord;
+    body: Record<string, unknown>;
+}
+export type SubmissionValidationResult = {
+    valid: true;
+    data: Record<string, string | boolean>;
+} | {
+    valid: false;
+    fieldErrors: FieldError[];
+};
+/**
+ * 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 declare function validateSubmissionPayload(input: ValidateSubmissionPayloadInput): SubmissionValidationResult;
+export declare function isHoneypotTripped(input: {
+    hp: unknown;
+}): boolean;
+//# sourceMappingURL=forms.d.ts.map

package/dist/forms/forms.js

@@ -0,0 +1,213 @@
+// 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
+// instead of restating them; validation owns the enforcement rule.
+const MIN_FIELDS = 1;
+export const MAX_FIELDS = 20;
+const MIN_LABEL_LENGTH = 1;
+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 MAX_CLASS_NAME_LENGTH = 300;
+export const MAX_ATTRIBUTES_PER_FIELD = 12;
+export const MAX_ATTRIBUTE_VALUE_LENGTH = 300;
+/**
+ * Escaping makes an attribute value inert, but cannot make a name such as onclick safe. Names
+ * are deny-by-default: only aria-* and data-* namespaces and a fixed closed list are accepted.
+ * Event handlers, style/formaction/href/src/srcdoc can inject behavior; id/name/type overrides
+ * can break label association, submission keys or the renderer's declared field vocabulary.
+ */
+export const ATTRIBUTE_NAME_PATTERN = /^(aria-[a-z0-9-]+|data-[a-z0-9-]+|placeholder|autocomplete|inputmode|pattern|title|min|max|step|minlength|spellcheck|readonly)$/;
+// Accepted as submission metadata, never as a declared field or stored answer.
+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)) {
+        return [{ field: label, reason: "id must match ^[a-z][a-z0-9_]*$" }];
+    }
+    if (claimedIds.has(descriptor.id)) {
+        return [{ field: descriptor.id, reason: "duplicate field id" }];
+    }
+    claimedIds.add(descriptor.id);
+    return [];
+}
+function fieldTypeErrors(descriptor, label) {
+    if (!FIELD_TYPES.has(descriptor.type)) {
+        return [{ field: label, reason: `type '${descriptor.type}' is not in the registered vocabulary` }];
+    }
+    return [];
+}
+function labelLengthErrors(descriptor, label) {
+    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` }];
+    }
+    return [];
+}
+// A checkbox carries a boolean, so no character cap can be honored. Report that prohibition
+// before any numeric range error, rather than asking the author to fix a number they must remove.
+function maxLengthErrors(descriptor, label) {
+    if (descriptor.maxLength == null)
+        return [];
+    if (descriptor.type === "checkbox") {
+        return [{ field: label, reason: "maxLength is forbidden for checkbox fields" }];
+    }
+    if (descriptor.maxLength < MIN_MAX_LENGTH || descriptor.maxLength > MAX_MAX_LENGTH) {
+        return [{ field: label, reason: `maxLength must be ${MIN_MAX_LENGTH}-${MAX_MAX_LENGTH}` }];
+    }
+    return [];
+}
+function checkboxValueErrors(descriptor, label) {
+    if (descriptor.checkboxValue === undefined)
+        return [];
+    if (descriptor.type !== "checkbox" || typeof descriptor.checkboxValue !== "string") {
+        return [{ field: label, reason: "checkboxValue must be a string on a checkbox field" }];
+    }
+    return [];
+}
+// HTML-escaped class names are inert; only their length is bounded. Check type defensively
+// because real inputs include parsed request bodies, regardless of the descriptor's static type.
+function classNameErrors(descriptor, label) {
+    const { className } = descriptor;
+    if (className == null)
+        return [];
+    if (typeof className !== "string") {
+        return [{ field: label, reason: "className must be a string" }];
+    }
+    if (className.length > MAX_CLASS_NAME_LENGTH) {
+        return [{ field: label, reason: `className must be at most ${MAX_CLASS_NAME_LENGTH} characters` }];
+    }
+    return [];
+}
+// A refused name will never render, so its value is moot. Reporting value errors as well would
+// imply that correcting a value could make a structurally unsafe attribute acceptable.
+function attributeEntryErrors(label, attrName, attrValue) {
+    if (!ATTRIBUTE_NAME_PATTERN.test(attrName)) {
+        return [{ field: label, reason: `attribute '${attrName}' is not allowed` }];
+    }
+    if (typeof attrValue !== "string") {
+        return [{ field: label, reason: `attribute '${attrName}' value must be a string` }];
+    }
+    if (attrValue.length > MAX_ATTRIBUTE_VALUE_LENGTH) {
+        return [{ field: label, reason: `attribute '${attrName}' value must be at most ${MAX_ATTRIBUTE_VALUE_LENGTH} characters` }];
+    }
+    return [];
+}
+// Exceeding the count cap still checks every attribute so the author sees unsafe names in one
+// round trip. This visits O(a) caller-supplied attributes; the reported cap does not truncate work.
+function attributeErrors(descriptor, label) {
+    const { attributes } = descriptor;
+    if (attributes == null)
+        return [];
+    const entries = Object.entries(attributes);
+    const errors = [];
+    if (entries.length > MAX_ATTRIBUTES_PER_FIELD) {
+        errors.push({ field: label, reason: `at most ${MAX_ATTRIBUTES_PER_FIELD} attributes are allowed` });
+    }
+    for (const [attrName, attrValue] of entries) {
+        errors.push(...attributeEntryErrors(label, attrName, attrValue));
+    }
+    return errors;
+}
+/**
+ * Collect every violation, not just the first: arity errors, then descriptors in array order,
+ * then each rule in the fixed order below. Callers display this list as-is, so order is observable.
+ * 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 }) {
+    const fieldErrors = [];
+    if (fields.length < MIN_FIELDS) {
+        fieldErrors.push({ field: "fields", reason: `at least ${MIN_FIELDS} field is required` });
+    }
+    if (fields.length > MAX_FIELDS) {
+        fieldErrors.push({ field: "fields", reason: `at most ${MAX_FIELDS} fields are allowed` });
+    }
+    const claimedIds = new Set();
+    for (const descriptor of fields) {
+        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));
+    }
+    if (fieldErrors.length > 0)
+        return { valid: false, fieldErrors };
+    return { valid: true };
+}
+// 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);
+}
+/**
+ * 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) {
+    const { definition, body } = input;
+    const fieldsById = new Map(definition.fields.map((f) => [f.id, f]));
+    const fieldErrors = unregisteredKeyErrors(body, fieldsById);
+    const data = {};
+    for (const field of definition.fields) {
+        const resolved = resolveSubmittedValue(field, body[field.id]);
+        if (resolved.kind === "rejected") {
+            fieldErrors.push({ field: field.id, reason: resolved.reason });
+        }
+        else if (resolved.kind === "accepted") {
+            data[field.id] = resolved.value;
+        }
+    }
+    if (fieldErrors.length > 0)
+        return { valid: false, fieldErrors };
+    return { 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) {
+    if (typeof input.hp !== "string")
+        return false;
+    return input.hp.trim().length > 0;
+}
+//# sourceMappingURL=forms.js.map

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

@@ -0,0 +1,34 @@
+import type { FormDefinitionRepoPort } from "../ports.js";
+import { type FormAuthoring, type HtmlFormDefinitionRecord } from "./html-authoring.js";
+import type { FormWriteServiceDeps } from "../write-service.js";
+export declare function prepareFormAuthoring({ deps, input, existing, permission }: {
+    deps: Pick<FormWriteServiceDeps, "authorize">;
+    /** Host permission for trusted, unsanitized HTML; no product policy is built in. */
+    permission: string;
+    input: FormAuthoring & {
+        workspaceId: string;
+        actor: {
+            id: string;
+        };
+    };
+    existing?: HtmlFormDefinitionRecord;
+}, _optional?: {}): Promise<(FormAuthoring & {
+    fields?: HtmlFormDefinitionRecord["fields"];
+}) | undefined>;
+/** A bounded decorator, with every repository method forwarded explicitly (class methods do not
+ * survive object spread). HTML names may be removed: they are the current markup's allowlist. */
+export declare function withFormAuthoring({ repo, authoring }: {
+    repo: FormDefinitionRepoPort;
+    authoring: FormAuthoring & {
+        fields?: HtmlFormDefinitionRecord["fields"];
+    };
+}, { replaceFields }?: {
+    replaceFields?: boolean;
+}): FormDefinitionRepoPort;
+/** Bind a host's raw-HTML permission to the audited authoring port.
+ * @returns Prepare/decorate operations; markup and fields persist in the same mutation.
+ * @complexity O(1) binding; prepare inherits parser cost. */
+export declare function createFormAuthoring({ permission }: {
+    permission: string;
+}, _optional?: Record<string, never>): import("../ports.js").FormAuthoringPort;
+//# sourceMappingURL=authoring-adapter.d.ts.map

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

@@ -0,0 +1,48 @@
+/** Host adapter around Jini's audited builder writes, pending upstream HTML authoring support.
+ * Stores derived fields and markup in the SAME mutation; never a follow-up unaudited write. */
+import { ForbiddenError } from "../../core/index.js";
+import { FormFieldValidationError } from "../errors.js";
+import { deriveHtmlForm } from "./html-authoring.js";
+export async function prepareFormAuthoring({ deps, input, existing, permission }, _optional = {}) {
+    const authored = input.mode !== undefined || input.html !== undefined;
+    if (!authored)
+        return existing?.mode === "html" ? deriveHtmlForm({ html: existing.html ?? "" }) : undefined;
+    // Match HTML Pages' trust boundary, including writes that switch out of authored HTML.
+    // Check before parsing so an editor cannot use validation as a way around raw-HTML authority.
+    if (input.mode === "builder" && input.html === undefined && existing?.mode !== "html")
+        return { mode: "builder", html: undefined };
+    const result = await deps.authorize({ principalId: input.actor.id, permission, workspaceId: input.workspaceId });
+    if (!result.allowed)
+        throw new ForbiddenError({ message: "HTML form authoring is restricted to admins and owners", permission, reason: result.reason });
+    if (input.mode !== undefined && input.mode !== "html" && input.mode !== "builder") {
+        throw new FormFieldValidationError({ message: "Invalid form mode", fieldErrors: [{ field: "mode", reason: "must be builder or html" }] });
+    }
+    if (input.mode === "builder")
+        return { mode: "builder", html: undefined };
+    return deriveHtmlForm({ html: input.html ?? existing?.html ?? "" });
+}
+/** A bounded decorator, with every repository method forwarded explicitly (class methods do not
+ * survive object spread). HTML names may be removed: they are the current markup's allowlist. */
+export function withFormAuthoring({ repo, authoring }, { replaceFields = false } = {}) {
+    return {
+        findById: async (target) => {
+            const record = await repo.findById(target);
+            return record && replaceFields ? { ...record, fields: [] } : record;
+        },
+        findBySlug: (target) => repo.findBySlug(target),
+        list: (target) => repo.list(target),
+        isSlugTaken: (target) => repo.isSlugTaken(target),
+        create: async (record) => { Object.assign(record, authoring); await repo.create(record); },
+        update: async (record) => { Object.assign(record, authoring); await repo.update(record); },
+    };
+}
+/** Bind a host's raw-HTML permission to the audited authoring port.
+ * @returns Prepare/decorate operations; markup and fields persist in the same mutation.
+ * @complexity O(1) binding; prepare inherits parser cost. */
+export function createFormAuthoring({ permission }, _optional = {}) {
+    return {
+        prepare: (required, optional = {}) => prepareFormAuthoring({ ...required, permission }, optional),
+        with: withFormAuthoring,
+    };
+}
+//# sourceMappingURL=authoring-adapter.js.map

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

@@ -0,0 +1,12 @@
+import type { FieldDescriptor } from "../types.js";
+export { decodeFormFields, encodeFormFields, type FormAuthoring, type HtmlFormDefinitionRecord } from "../fields-json.js";
+/** Derives the submission allowlist at save time and removes server-owned transport overrides.
+ * Parsing normalizes HTML syntax; scripts and authored styling remain unsanitized. */
+export declare function deriveHtmlForm({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): {
+    mode: "html";
+    html: string;
+    fields: FieldDescriptor[];
+};
+//# sourceMappingURL=html-authoring.d.ts.map

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

@@ -0,0 +1,133 @@
+/** HTML authoring adapter. Unsanitized, admin/owner trusted markup, like HTML Pages.
+ * parse5 supplies real HTML semantics (comments/scripts are never mistaken for inputs).
+ * Prototype belongs in @jini-ai/cms/forms later; its published release lacks HTML authoring. */
+import { parseFragment, serialize } from "parse5";
+import { FormFieldValidationError } from "../errors.js";
+export { decodeFormFields, encodeFormFields } from "../fields-json.js";
+function invalid(reason) {
+    throw new FormFieldValidationError({ message: reason, fieldErrors: [{ field: "html", reason }] });
+}
+function elements(nodes) {
+    const found = [];
+    const stack = [...nodes].reverse();
+    while (stack.length) {
+        const node = stack.pop();
+        if (!("tagName" in node))
+            continue;
+        found.push(node);
+        // Templates are inert and do not contribute successful controls.
+        if (node.tagName !== "template")
+            stack.push(...[...node.childNodes].reverse());
+    }
+    return found;
+}
+function attr(element, name) {
+    return element.attrs.find((item) => item.name === name)?.value;
+}
+function labelText(node) {
+    const stack = [...node.childNodes].reverse();
+    let text = "";
+    while (stack.length) {
+        const child = stack.pop();
+        if ("value" in child)
+            text += child.value;
+        else if ("tagName" in child && !["input", "select", "textarea", "script", "style"].includes(child.tagName)) {
+            stack.push(...[...child.childNodes].reverse());
+        }
+    }
+    return text.trim();
+}
+/** 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. */
+function serializeAuthoredRequired({ fragment, html }) {
+    const required = elements(fragment.childNodes).filter((element) => attr(element, "required") !== undefined)
+        .map((element) => element.sourceCodeLocation?.attrs?.required)
+        .map((location) => location ? html.slice(location.startOffset, location.endOffset) : undefined);
+    let output = serialize(fragment);
+    const generated = elements(parseFragment(output, { sourceCodeLocationInfo: true }).childNodes)
+        .filter((element) => attr(element, "required") !== undefined);
+    for (let index = generated.length - 1; index >= 0; index--) {
+        // The reverse loop indexes only elements in the generated array.
+        const location = generated[index].sourceCodeLocation?.attrs?.required;
+        if (location && required[index])
+            output = output.slice(0, location.startOffset) + required[index] + output.slice(location.endOffset);
+    }
+    return output;
+}
+/** Derives the submission allowlist at save time and removes server-owned transport overrides.
+ * Parsing normalizes HTML syntax; scripts and authored styling remain unsanitized. */
+export function deriveHtmlForm({ html }, _optional = {}) {
+    if (typeof html !== "string" || html.length > 200_000)
+        invalid("HTML must be a string of at most 200000 characters");
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const all = elements(fragment.childNodes);
+    const forms = all.filter((element) => element.tagName === "form");
+    if (forms.length > 1)
+        invalid("Use a form body or one outer form wrapper");
+    for (const form of forms) {
+        const parent = form.parentNode;
+        if (!parent)
+            continue;
+        const index = parent.childNodes.indexOf(form);
+        parent.childNodes.splice(index, 1, ...form.childNodes);
+        for (const child of form.childNodes)
+            child.parentNode = parent;
+    }
+    const fields = new Map();
+    const labels = all.filter((element) => element.tagName === "label");
+    for (const element of all) {
+        // A submit button's overrides or a control's `form` attribute must not bypass our endpoint.
+        for (const name of ["form", "formaction", "formmethod", "formenctype", "formtarget"]) {
+            element.attrs = element.attrs.filter((attribute) => attribute.name !== name);
+        }
+        if (!["input", "textarea", "select", "button"].includes(element.tagName))
+            continue;
+        if (element.tagName === "button") {
+            element.attrs = element.attrs.filter((attribute) => attribute.name !== "name"); // Buttons are actions, not submission columns.
+            continue;
+        }
+        const name = attr(element, "name");
+        if (!name)
+            continue;
+        if (name === "_hp" || ["__proto__", "constructor", "prototype"].includes(name))
+            invalid(`Reserved field name '${name}'`);
+        const inputType = (attr(element, "type") ?? "text").toLowerCase();
+        if (element.tagName === "input" && ["submit", "reset", "button", "image"].includes(inputType)) {
+            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;
+                continue;
+            }
+            invalid(`Duplicate field name '${name}'`);
+        }
+        // Earlier Jini releases stored only boolean checkboxes and forced the native "on" wire value.
+        // Record attribute presence instead: authored strings survive while no-value boxes stay boolean.
+        const checkboxValue = inputType === "checkbox" ? attr(element, "value") : undefined;
+        const id = attr(element, "id");
+        const parentLabel = element.parentNode && "tagName" in element.parentNode && element.parentNode.tagName === "label"
+            ? element.parentNode : undefined;
+        const label = labels.find((item) => id !== undefined && attr(item, "for") === id) ?? parentLabel;
+        const maxLength = attr(element, "maxlength");
+        fields.set(name, {
+            id: name,
+            label: label ? labelText(label) || name : attr(element, "aria-label") || name,
+            type: element.tagName === "textarea" ? "textarea" : inputType === "email" ? "email" : inputType === "checkbox" ? "checkbox" : "text",
+            required: attr(element, "required") !== undefined,
+            ...(checkboxValue !== undefined ? { checkboxValue } : {}),
+            ...(maxLength !== undefined ? { maxLength: Number(maxLength) } : {}),
+        });
+    }
+    // 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.
+    return { mode: "html", html: serializeAuthoredRequired({ fragment, html }), fields: [...fields.values()] };
+}
+//# sourceMappingURL=html-authoring.js.map

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

@@ -0,0 +1,10 @@
+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 }: {
+    definition: FormDefinitionRecord;
+    body: Record<string, unknown>;
+}, _optional?: {}): FormDefinitionRecord;
+//# sourceMappingURL=html-submission-adapter.d.ts.map

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

@@ -0,0 +1,15 @@
+/** 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 };
+        }) };
+}
+//# sourceMappingURL=html-submission-adapter.js.map

package/dist/forms/html/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./html-authoring.js";
+export * from "./authoring-adapter.js";
+export * from "./html-submission-adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/forms/html/index.js

@@ -0,0 +1,4 @@
+export * from "./html-authoring.js";
+export * from "./authoring-adapter.js";
+export * from "./html-submission-adapter.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,33 @@
+/** Framework-free HTML renderer, kept separate for extraction into @jini-ai/cms/forms.
+ * Local prototype authorized 2026-10-04; that original dispatch kept Jini read-only.
+ * The host owns the endpoint and the form's styling hook; author markup and CSS refine it. */
+import type { FieldDescriptor } from "./types.js";
+/** Attribute names are trusted host constants, not visitor input. Values are always escaped. */
+export interface FormHtmlHooks {
+    field: string;
+    form: string;
+    success: string;
+    error: string;
+}
+export declare function escapeFormHtml({ value }: {
+    value: string;
+}, _optional?: {}): string;
+export declare function renderHtmlFormBody({ fields, hooks }: {
+    fields: readonly FieldDescriptor[];
+    hooks: Pick<FormHtmlHooks, "field">;
+}, { submitLabel }?: {
+    submitLabel?: string;
+}): 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 }: {
+    slug: string;
+    fields: readonly FieldDescriptor[];
+    action: string;
+    hooks: FormHtmlHooks;
+}, { html, successMessage, className }?: {
+    html?: string;
+    successMessage?: string;
+    className?: string;
+}): string;
+//# sourceMappingURL=html-render.d.ts.map

package/dist/forms/html-render.js

@@ -0,0 +1,31 @@
+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>`;
+}
+/** `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 function renderHtmlForm({ slug, fields, action, hooks }, { html, successMessage = "Thanks — your message has been sent.", className } = {}) {
+    const escapedSlug = escapeFormHtml({ value: slug });
+    const slugHook = `data-form-slug="${escapedSlug}"`;
+    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 })}">` +
+        `<div ${hooks.error} ${slugHook} role="alert" hidden></div>` +
+        (html ?? renderHtmlFormBody({ fields, hooks })) +
+        // 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>`;
+}
+//# sourceMappingURL=html-render.js.map

package/dist/forms/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./types.js";
+export * from "./ports.js";
+export * from "./errors.js";
+export * from "./forms.js";
+export * from "./rate-limit-key.js";
+export * from "./write-service.js";
+export * from "./submit-service.js";
+export * from "./notify-subscriber.js";
+export * from "./submission-ip-retention.js";
+export * from "./fields-json.js";
+export * from "./html-render.js";
+export * from "./submission-attempts.js";
+export * from "./submission-email-validation.js";
+export * from "./delete-submission.js";
+export * from "./duplicate-slug.js";
+export * from "./repo.memory.js";
+//# sourceMappingURL=index.d.ts.map