@jini-ai/cms 0.5.2 → 0.5.4

package/dist/forms/duplicate-slug.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file `content_duplicate`'s `"form"` resource needs a slug for the copy, and Forms — unlike Posts —
+ * has nowhere to get one.
+ *
+ * `createPost` derives and disambiguates a slug itself whenever the caller omits one, which is why
+ * `duplicatePostOrPage` can just pass `slug: undefined` and be done. `createFormDefinition` is the
+ * opposite: `slug` is required, is immutable after creation (`updateFormDefinition` always re-passes
+ * `existing.slug`), and is validated against `@jini-ai/cms/forms`' `SLUG_PATTERN` plus the adapter's
+ * reserved set. Duplicating a form therefore has to arrive with a valid, free slug in hand — otherwise every
+ * copy of "Contact Us" collides with the previous one and the operator sees a raw
+ * `FormSlugConflictError` instead of a copy.
+ *
+ * Kept as its own pure module (mirroring `features/post/duplicate-embeds.ts`) rather than inlined in
+ * `tool-registrations.ts`: the character-class, truncation and suffix-search edges are exactly the
+ * kind of logic that is cheap to assert directly and expensive to reach through a repo, a command
+ * gateway and an outbox.
+ *
+ * Deliberately NOT exported as a general-purpose Forms slug helper: `forms_create_definition` still
+ * takes an explicit caller-supplied slug, and giving it a silent derivation would change a published
+ * tool contract this task has no mandate to change.
+ *
+ * The bounded suffix-search LOOP itself was first shared with
+ * `../content-duplication/derive-available-name.ts` (2026-09-08), generalized from this file's own
+ * original loop. Its implementation and rationale now live in `@jini-ai/core/naming`'s
+ * `deriveAvailableName`, keeping the collision-search shape shared with the NAME derivation every
+ * `content_duplicate` resource needs, rather than reinvented a second time. This file keeps
+ * everything SLUG-specific: the character class (`slugifyFormName`), the length ceiling and
+ * base-shortening (`withSuffix`), and the reserved-word list (`RESERVED_SLUGS`).
+ */
+/** The ceiling `SLUG_PATTERN` (`^[a-z0-9][a-z0-9-]{0,63}$`) itself imposes: 1 + 63 characters. */
+export declare const FORM_SLUG_MAX_LENGTH = 64;
+/**
+ * Route sentinel the admin Forms editor reserves for its own create-mode URL — re-stated from
+ * `write-service.ts`'s private `RESERVED_SLUGS` because it is private there. A derived slug landing
+ * on it is treated as taken rather than rejected: the caller never chose it, so suffixing is the
+ * right repair, and `createFormDefinition` would reject it outright a moment later anyway.
+ */
+/**
+ * Converts a form name into the longest `SLUG_PATTERN`-satisfying slug it can, or `""` when the name
+ * contains nothing sluggable.
+ *
+ * Returns `""` rather than a fallback so a caller can tell "nothing to work with" apart from a real
+ * derivation — {@link deriveAvailableFormSlug} is where the fallback is applied. Truncation trims any
+ * hyphen the cut exposes, since a trailing hyphen is legal under the pattern but reads as a mistake.
+ *
+ * @param name - The (possibly already numbered, e.g. "Landing sample — xai 2") form name to derive
+ * from.
+ * @returns A slug of at most {@link FORM_SLUG_MAX_LENGTH} characters, or `""`.
+ * @complexity O(n) in the name's length.
+ */
+export declare function slugifyFormName({ name, slugify }: {
+    name: string;
+    slugify: (name: string) => string;
+}, _optional?: Record<string, never>): string;
+/**
+ * Derives a slug for a duplicated form that is both valid under `SLUG_PATTERN` and free.
+ *
+ * `isTaken` is injected rather than a repo handle so the search is directly testable and so this
+ * module carries no port dependency; production passes a `formDefinitionRepo.findBySlug` lookup.
+ * Note this is advisory, not a lock: the DB unique index remains the real tie-break, so a genuine
+ * race still surfaces as `FormSlugConflictError` from `createFormDefinition`. That is the intended
+ * split (`write-service.ts`'s own header states it), not a gap this function is trying to close.
+ *
+ * The suffix is appended within the length ceiling, truncating the base as needed, so a maximum
+ * length name still disambiguates instead of producing an over-long slug create would reject.
+ *
+ * @param required.name - The copy's name, already defaulted by the caller.
+ * @param options.isTaken - Whether a candidate slug is already used in this workspace.
+ * @returns A slug satisfying `SLUG_PATTERN` that `isTaken` reported free.
+ * @throws {Error} If {@link MAX_SUFFIX_ATTEMPTS} candidates are all taken.
+ * @complexity O(k) `isTaken` calls where k is the number of colliding candidates, bounded at
+ * {@link MAX_SUFFIX_ATTEMPTS}.
+ */
+export declare function deriveAvailableFormSlug(required: {
+    name: string;
+    slugify: (name: string) => string;
+    maxAttempts: number;
+    reservedSlugs: ReadonlySet<string>;
+    isTaken: (slug: string) => Promise<boolean>;
+}, _optional?: Record<string, never>): Promise<string>;
+//# sourceMappingURL=duplicate-slug.d.ts.map

package/dist/forms/duplicate-slug.js

@@ -0,0 +1,115 @@
+import { SLUG_PATTERN } from "./write-service.js";
+import { deriveAvailableName } from "@jini-ai/core/naming";
+/**
+ * @file `content_duplicate`'s `"form"` resource needs a slug for the copy, and Forms — unlike Posts —
+ * has nowhere to get one.
+ *
+ * `createPost` derives and disambiguates a slug itself whenever the caller omits one, which is why
+ * `duplicatePostOrPage` can just pass `slug: undefined` and be done. `createFormDefinition` is the
+ * opposite: `slug` is required, is immutable after creation (`updateFormDefinition` always re-passes
+ * `existing.slug`), and is validated against `@jini-ai/cms/forms`' `SLUG_PATTERN` plus the adapter's
+ * reserved set. Duplicating a form therefore has to arrive with a valid, free slug in hand — otherwise every
+ * copy of "Contact Us" collides with the previous one and the operator sees a raw
+ * `FormSlugConflictError` instead of a copy.
+ *
+ * Kept as its own pure module (mirroring `features/post/duplicate-embeds.ts`) rather than inlined in
+ * `tool-registrations.ts`: the character-class, truncation and suffix-search edges are exactly the
+ * kind of logic that is cheap to assert directly and expensive to reach through a repo, a command
+ * gateway and an outbox.
+ *
+ * Deliberately NOT exported as a general-purpose Forms slug helper: `forms_create_definition` still
+ * takes an explicit caller-supplied slug, and giving it a silent derivation would change a published
+ * tool contract this task has no mandate to change.
+ *
+ * The bounded suffix-search LOOP itself was first shared with
+ * `../content-duplication/derive-available-name.ts` (2026-09-08), generalized from this file's own
+ * original loop. Its implementation and rationale now live in `@jini-ai/core/naming`'s
+ * `deriveAvailableName`, keeping the collision-search shape shared with the NAME derivation every
+ * `content_duplicate` resource needs, rather than reinvented a second time. This file keeps
+ * everything SLUG-specific: the character class (`slugifyFormName`), the length ceiling and
+ * base-shortening (`withSuffix`), and the reserved-word list (`RESERVED_SLUGS`).
+ */
+/** The ceiling `SLUG_PATTERN` (`^[a-z0-9][a-z0-9-]{0,63}$`) itself imposes: 1 + 63 characters. */
+export const FORM_SLUG_MAX_LENGTH = 64;
+/**
+ * The slug used when a name has no sluggable characters at all (e.g. `"!!! ---"`, or a name written
+ * entirely in a script this ASCII-only pattern cannot represent). `SLUG_PATTERN` has no "empty"
+ * form, so something concrete has to stand in; the suffix search below then disambiguates it the
+ * same way it disambiguates any other collision.
+ */
+const FALLBACK_SLUG = "form";
+/**
+ * Route sentinel the admin Forms editor reserves for its own create-mode URL — re-stated from
+ * `write-service.ts`'s private `RESERVED_SLUGS` because it is private there. A derived slug landing
+ * on it is treated as taken rather than rejected: the caller never chose it, so suffixing is the
+ * right repair, and `createFormDefinition` would reject it outright a moment later anyway.
+ */
+// The host supplies this reserved set; its admin create-route sentinel remains host policy.
+/**
+ * Converts a form name into the longest `SLUG_PATTERN`-satisfying slug it can, or `""` when the name
+ * contains nothing sluggable.
+ *
+ * Returns `""` rather than a fallback so a caller can tell "nothing to work with" apart from a real
+ * derivation — {@link deriveAvailableFormSlug} is where the fallback is applied. Truncation trims any
+ * hyphen the cut exposes, since a trailing hyphen is legal under the pattern but reads as a mistake.
+ *
+ * @param name - The (possibly already numbered, e.g. "Landing sample — xai 2") form name to derive
+ * from.
+ * @returns A slug of at most {@link FORM_SLUG_MAX_LENGTH} characters, or `""`.
+ * @complexity O(n) in the name's length.
+ */
+export function slugifyFormName({ name, slugify }, _optional = {}) {
+    return slugify(name).slice(0, FORM_SLUG_MAX_LENGTH).replace(/-+$/g, "");
+}
+/**
+ * Derives a slug for a duplicated form that is both valid under `SLUG_PATTERN` and free.
+ *
+ * `isTaken` is injected rather than a repo handle so the search is directly testable and so this
+ * module carries no port dependency; production passes a `formDefinitionRepo.findBySlug` lookup.
+ * Note this is advisory, not a lock: the DB unique index remains the real tie-break, so a genuine
+ * race still surfaces as `FormSlugConflictError` from `createFormDefinition`. That is the intended
+ * split (`write-service.ts`'s own header states it), not a gap this function is trying to close.
+ *
+ * The suffix is appended within the length ceiling, truncating the base as needed, so a maximum
+ * length name still disambiguates instead of producing an over-long slug create would reject.
+ *
+ * @param required.name - The copy's name, already defaulted by the caller.
+ * @param options.isTaken - Whether a candidate slug is already used in this workspace.
+ * @returns A slug satisfying `SLUG_PATTERN` that `isTaken` reported free.
+ * @throws {Error} If {@link MAX_SUFFIX_ATTEMPTS} candidates are all taken.
+ * @complexity O(k) `isTaken` calls where k is the number of colliding candidates, bounded at
+ * {@link MAX_SUFFIX_ATTEMPTS}.
+ */
+export async function deriveAvailableFormSlug(required, _optional = {}) {
+    const base = slugifyFormName({ name: required.name, slugify: required.slugify }) || FALLBACK_SLUG;
+    return deriveAvailableName({
+        base,
+        withSuffix: ({ base, suffix }) => withSuffix(base, suffix),
+        // RESERVED_SLUGS/SLUG_PATTERN are "skip this candidate", not "this candidate is taken" — but
+        // the generic loop makes no distinction between the two (see its own doc), so folding both
+        // checks in here reproduces this function's original `continue`-then-try-the-next-suffix
+        // behavior exactly.
+        isTaken: async ({ candidate }) => {
+            if (required.reservedSlugs.has(candidate))
+                return true;
+            if (!SLUG_PATTERN.test(candidate))
+                return true;
+            return required.isTaken(candidate);
+        },
+        exhaustionMessage: ({ maxAttempts }) => `no free slug could be derived from '${required.name}' after ${maxAttempts} attempts — ` +
+            "give the copy an explicit slug",
+    }, { maxAttempts: required.maxAttempts });
+}
+/**
+ * Appends `-<suffix>` while keeping the result within {@link FORM_SLUG_MAX_LENGTH}, shortening the
+ * base (never the suffix) when the two together would overflow — the suffix is what makes the slug
+ * unique, so it is the half that must survive.
+ *
+ * @complexity O(1).
+ */
+function withSuffix(base, suffix) {
+    const tail = `-${suffix}`;
+    const room = FORM_SLUG_MAX_LENGTH - tail.length;
+    return `${base.slice(0, room).replace(/-+$/g, "")}${tail}`;
+}
+//# sourceMappingURL=duplicate-slug.js.map

package/dist/forms/errors.d.ts

@@ -0,0 +1,53 @@
+/** Stable domain error types; callers map them to their own transport errors. */
+export declare class FormFieldValidationError extends Error {
+    readonly fieldErrors: Array<{
+        field: string;
+        reason: string;
+    }>;
+    constructor({ message, fieldErrors }: {
+        message: string;
+        fieldErrors?: Array<{
+            field: string;
+            reason: string;
+        }> | undefined;
+    });
+}
+export declare class FormSubmissionValidationError extends Error {
+    readonly fieldErrors: Array<{
+        field: string;
+        reason: string;
+    }>;
+    constructor({ message, fieldErrors }: {
+        message: string;
+        fieldErrors?: Array<{
+            field: string;
+            reason: string;
+        }> | undefined;
+    });
+}
+export declare class FormSlugConflictError extends Error {
+    readonly slug: string;
+    constructor({ message, slug }: {
+        message: string;
+        slug: string;
+    });
+}
+/** Disabled definitions deliberately use the same not-found error as missing definitions. */
+export declare class FormDefinitionNotFoundError extends Error {
+    constructor({ message }: {
+        message: string;
+    });
+}
+export declare class FormSubmissionNotFoundError extends Error {
+    constructor({ message }: {
+        message: string;
+    });
+}
+export declare class FormRateLimitExceededError extends Error {
+    readonly retryAfterSeconds: number;
+    constructor({ message, retryAfterSeconds }: {
+        message: string;
+        retryAfterSeconds: number;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/forms/errors.js

@@ -0,0 +1,25 @@
+/** Stable domain error types; callers map them to their own transport errors. */
+export class FormFieldValidationError extends Error {
+    fieldErrors;
+    constructor({ message, fieldErrors = [] }) { super(message); this.fieldErrors = fieldErrors; }
+}
+export class FormSubmissionValidationError extends Error {
+    fieldErrors;
+    constructor({ message, fieldErrors = [] }) { super(message); this.fieldErrors = fieldErrors; }
+}
+export class FormSlugConflictError extends Error {
+    slug;
+    constructor({ message, slug }) { super(message); this.slug = slug; }
+}
+/** Disabled definitions deliberately use the same not-found error as missing definitions. */
+export class FormDefinitionNotFoundError extends Error {
+    constructor({ message }) { super(message); }
+}
+export class FormSubmissionNotFoundError extends Error {
+    constructor({ message }) { super(message); }
+}
+export class FormRateLimitExceededError extends Error {
+    retryAfterSeconds;
+    constructor({ message, retryAfterSeconds }) { super(message); this.retryAfterSeconds = retryAfterSeconds; }
+}
+//# sourceMappingURL=errors.js.map

package/dist/forms/express/handler.d.ts

@@ -0,0 +1,59 @@
+import type { Request, Response } from "express";
+import type { FormDefinitionRepoPort } from "../ports.js";
+import type { SubmitFormInput } from "../submit-service.js";
+export type FormSubmissionRedirectResult = {
+    kind: "success";
+    slug: string;
+} | {
+    kind: "validation";
+    slug: string;
+    fieldErrors: ReadonlyArray<{
+        field: string;
+        reason: string;
+    }>;
+    values?: Readonly<Record<string, string>>;
+} | {
+    kind: "rate-limited";
+    slug: string;
+    retryAfterSeconds: number;
+} | {
+    kind: "error";
+    slug: string;
+};
+/** The host owns the existing query/cookie wire format and safe site target policy. */
+export interface FormSubmitResultCodec {
+    encodeResultQuery: (result: FormSubmissionRedirectResult) => Iterable<[string, string]>;
+    clearResultQueryParams: (params: URLSearchParams) => void;
+    encodeFlashCookie: (payload: {
+        slug: string;
+        values: Record<string, string>;
+    }) => string | undefined;
+    flashCookieName: string;
+}
+/** Anonymous HTTP composition; the definition read is used only to repopulate failed HTML POSTs. */
+export interface CreateFormSubmitHandlerRequired {
+    workspaceId: string;
+    submit: (required: {
+        input: SubmitFormInput;
+    }, optional?: Record<string, never>) => Promise<{
+        status: "accepted";
+    }>;
+    definitionRepo: Pick<FormDefinitionRepoPort, "findBySlug">;
+    resolveClientIp: (req: Request) => string;
+    isHttpsRequest: (req: Request) => boolean;
+    resultCodec: FormSubmitResultCodec;
+    targetRefusalReason: (target: string) => string | null;
+}
+/** Registers `POST /forms/:slug/submit`. Must be registered BEFORE the site `/:slug` catch-all.
+ *
+ * `express.urlencoded` is mounted on THIS route's own POST registration (not a global `app.ts`
+ * mount — same scoping precedent as `template-preview.ts`'s `POST` handler) because a real,
+ * JavaScript-disabled `<form method="post">` — the exact case this file's Post/Redirect/Get fix
+ * exists for — always encodes its body as `application/x-www-form-urlencoded`, which `app.ts`'s
+ * blanket `express.json()` cannot parse; without this, every field on a genuine browser submission
+ * would silently arrive as missing, failing REQUIRED-field validation on every real, non-JS
+ * submission regardless of the redirect fix. A `fetch`/JSON caller (every pre-existing test in this
+ * file) is unaffected — Express dispatches to whichever parser matches the request's actual
+ * `Content-Type`, so mounting both here is additive, never a double-parse of the same request. */
+export declare function createFormSubmitHandler(deps: CreateFormSubmitHandlerRequired, _optional?: Record<string, never>): (req: Request, res: Response) => Promise<void>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/forms/express/handler.js

@@ -0,0 +1,217 @@
+import { FormDefinitionNotFoundError, FormRateLimitExceededError, FormSubmissionValidationError } from "../errors.js";
+/**
+ * @file Public submission route for `forms` (SPEC-010 `FORMS_POST_SUBMIT`, REQ-05).
+ *
+ * Mirrors `routes/site/analytics-ingest.ts`'s public-route shape: no session required, registered
+ * before the site `/:slug` catch-all (see `server/app.ts`'s wiring). Reuses `resolveClientIp`
+ * (`core/rate-limit/rate-limit.ts`) rather than re-deriving IP resolution — all real validation
+ * happens inside `submitForm` (C-008); this file owns only the HTTP boundary.
+ *
+ * A native `<form>` POST navigates the browser to whatever this route returns — the ORIGINAL bug
+ * here (2026-08-31 fix) was that every branch replied with raw JSON, which a JS-disabled visitor saw
+ * as a literal `{"status":"accepted"}` screen instead of their page. `wantsHtmlResponse` splits the
+ * two audiences this endpoint actually has by content negotiation: a fetch/XHR/API caller (this
+ * file's own existing tests, none of which set an `Accept` header, land here) keeps the untouched
+ * JSON contract; a real browser form submission (`Accept: text/html,...`) gets a Post/Redirect/Get
+ * 303 back to the page that hosted the form, with the outcome threaded through the query string via
+ * {@link encodeFormSubmissionResultQuery} — `routes/site/pages.ts` decodes and splices it back into
+ * that page (`http/site/render.ts`'s `injectFormSubmissionResultIntoHtml`) on the way back down.
+ *
+ * A validation failure ALSO sets the host's form flash cookie ({@link setFormFlashCookieForValidationFailure})
+ * so the OTHER fields the visitor already typed survive that same round trip instead of coming back
+ * wiped (2026-08-31 fix) — see `http/site/form-render.ts`'s "Validation flash cookie" section for why
+ * this travels via a cookie rather than the query string.
+ */
+const MAX_BODY_STRING_LENGTH = 5000;
+/** Truncates string values in an untrusted body before it reaches `submitForm`; other types pass through unchanged so `validateSubmissionPayload` can reject them by type, mirroring `analytics-ingest.ts`'s `parseBeacon`. */
+function boundBody(body) {
+    const raw = (body ?? {});
+    const bounded = {};
+    for (const [key, value] of Object.entries(raw)) {
+        bounded[key] = typeof value === "string" ? value.slice(0, MAX_BODY_STRING_LENGTH) : value;
+    }
+    return bounded;
+}
+/** True for a real browser's form-POST navigation (`Accept: text/html,...`); false for the
+ *  fetch/XHR/API caller shape every pre-existing test in this file already sends (`*\/*`, or no
+ *  header at all), which must keep getting the untouched JSON contract. */
+function wantsHtmlResponse(req) {
+    return (req.get("accept") ?? "").includes("text/html");
+}
+/**
+ * Resolves the safe base URL {@link redirectWithFormResult} rebuilds its Location around. `Referer`
+ * is the only signal available for "which page hosted this form" — `render.ts`'s
+ * `renderWidgetContactForm` has no request in scope to stash a return path in (see that file's own
+ * module doc) — and it is entirely visitor-controlled: a hostile page anywhere on the internet can
+ * point a plain `<form>` at this exact endpoint and set its own Referer to whatever it likes.
+ * Redirecting there unchecked would turn this endpoint into an open redirect (secure-input-handling:
+ * untrusted header). Comparing `refUrl.host` against this REQUEST's own `Host` header closes that
+ * off — an absent, unparsable, or cross-origin Referer all fall back to the site root instead, a
+ * real and safe page rather than a raw JSON blob, just not necessarily the one the visitor submitted
+ * from.
+ *
+ * The host match alone is not enough (t91 open-redirect sweep, 2026-09-16): the Location is rebuilt
+ * from the Referer's `pathname` + `search` only, and `http://site//evil.example/x` (or the `/\` and
+ * `/.//` spellings a URL parser folds into it) has the right host but a pathname of
+ * `//evil.example/x` — a protocol-relative Location. The pathname must also pass the redirects write
+ * gate's site-relative check, which refuses that shape (and the admin surface) the same way.
+ */
+function resolveSameOriginRedirectBase(req, targetRefusalReason) {
+    const fallback = new URL("/", `${req.protocol}://${req.get("host") ?? "localhost"}`);
+    const referer = req.get("referer");
+    if (!referer)
+        return fallback;
+    try {
+        const refUrl = new URL(referer);
+        const onThisSite = refUrl.host === req.get("host") && targetRefusalReason(refUrl.pathname) === null;
+        return onThisSite ? refUrl : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Issues the Post/Redirect/Get 303 a JS-disabled form submission needs: back to the same-origin
+ *  page {@link resolveSameOriginRedirectBase} resolved, with any PRIOR `form_*` result params
+ *  cleared (so resubmitting doesn't accumulate stale ones from an earlier visit) and `result`'s own
+ *  freshly encoded in their place. */
+function redirectWithFormResult(req, res, result, deps) {
+    const target = resolveSameOriginRedirectBase(req, deps.targetRefusalReason);
+    deps.resultCodec.clearResultQueryParams(target.searchParams);
+    for (const [key, value] of deps.resultCodec.encodeResultQuery(result))
+        target.searchParams.set(key, value);
+    res.redirect(303, `${target.pathname}${target.search}`);
+}
+// ---------------------------------------------------------------------------
+// Validation flash cookie (2026-08-31 field-wipe fix) — see `http/site/form-render.ts`'s own
+// "Validation flash cookie" section header for the full mechanism this half feeds.
+// ---------------------------------------------------------------------------
+const FORM_FLASH_COOKIE_MAX_AGE_SECONDS = 120;
+/** Field types eligible to be echoed back into the flash cookie — an ALLOWLIST, not a denylist, so a
+ *  future `FieldType` this codebase has not added yet (a `password` type, say) is excluded the
+ *  moment it exists, with zero code change required here: only a type explicitly added to this set
+ *  is ever repopulated. `checkbox` is excluded too — its stored value is a boolean-ish flag, never
+ *  text a visitor "typed" and could lose, so the bug this fixes never applied to it. */
+const REPOPULATABLE_FIELD_TYPES = new Set(["text", "email", "textarea"]);
+/** Extracts the submitted values worth flashing back: only fields BOTH declared on this form AND of
+ *  a {@link REPOPULATABLE_FIELD_TYPES} type — iterating `fields` (not `body`'s own keys) means a
+ *  non-field key like the honeypot (`_hp`) is excluded automatically, never by a separate denylist
+ *  check. Per-value/total-size bounding for the cookie itself is `encodeFormFlashCookieValue`'s own
+ *  job (`form-render.ts`), not duplicated here.
+ * @complexity O(f) in the form's own declared field count (bounded by forms' `MAX_FIELDS`). */
+function buildFormFlashValues(fields, body) {
+    const values = {};
+    for (const field of fields) {
+        if (!REPOPULATABLE_FIELD_TYPES.has(field.type))
+            continue;
+        const raw = body[field.id];
+        if (typeof raw === "string" && raw !== "")
+            values[field.id] = raw;
+    }
+    return values;
+}
+/** Sets the short-lived, read-once flash cookie a validation-failure redirect uses to survive the
+ *  303's fresh GET with the visitor's OTHER field values intact (2026-08-31 fix — see this route's
+ *  own module doc header, and `form-render.ts`'s "Validation flash cookie" section, for the full
+ *  round trip). `HttpOnly` — this mechanism exists so the JS-DISABLED path works, there is no reason
+ *  to also expose it to page JS. `SameSite=Lax`, not `Strict` — the cookie's only read happens on
+ *  this SAME redirect's own follow-up GET, a top-level same-site navigation `Lax` already allows,
+ *  mirroring `complete-sign-in.ts`'s identical `SameSite=Lax` rationale. `Secure` only when
+ *  {@link isHttpsRequest} — unlike `dev-auth.ts`'s/`complete-sign-in.ts`'s always-on `Secure` (both
+ *  gate a real login session), an unconditional `Secure` here would silently break this exact feature
+ *  on a plain `http://localhost` dev/test run.
+ *
+ * `encodeFormFlashCookieValue` returning `undefined` (the submission's own values did not fit even
+ * after truncation/dropping) is a silent no-op — the redirect still happens; the visitor just sees
+ * the pre-fix wiped-fields behavior for that one oversized submission rather than a broken
+ * `Set-Cookie` header. */
+function setFormFlashCookie(req, res, payload, deps) {
+    const json = deps.resultCodec.encodeFlashCookie(payload);
+    if (!json)
+        return;
+    res.cookie(deps.resultCodec.flashCookieName, json, {
+        httpOnly: true, path: "/", maxAge: FORM_FLASH_COOKIE_MAX_AGE_SECONDS * 1000,
+        sameSite: "lax", secure: deps.isHttpsRequest(req),
+    });
+}
+/** Builds and sets the flash cookie for a validation failure reached via a real browser form POST.
+ *  Looks up the form's field descriptors a SECOND time — `submitForm` already did once, internally,
+ *  to build `err.fieldErrors`, but that lookup's own `FormDefinitionRecord` never escapes
+ *  `submit-service.ts` — so this route can filter by field `type` without widening `submitForm`'s
+ *  own return/throw contract for a single caller's cookie concern. The extra read only happens on
+ *  the HTML/validation-failure path, never on every submission. A workspace/slug with no matching
+ *  definition (should not happen — `submitForm` just resolved the same slug successfully enough to
+ *  reach validation) degrades to an empty field list rather than throwing. */
+async function setFormFlashCookieForValidationFailure(req, res, deps, slug, body) {
+    const definition = await deps.definitionRepo.findBySlug({ workspaceId: deps.workspaceId, slug });
+    const values = buildFormFlashValues(definition?.fields ?? [], body);
+    if (Object.keys(values).length === 0)
+        return;
+    setFormFlashCookie(req, res, { slug, values }, deps);
+}
+function outcomeForSuccess(slug, result) {
+    return { redirectResult: { kind: "success", slug }, json: { status: 201, body: result } };
+}
+/** Maps `submitForm`'s three typed failure modes (REQ-05/07's error taxonomy) to both response
+ *  shapes at once; an error `submitForm` never actually raises today still degrades to a generic
+ *  500/`"error"` pair rather than throwing out of this mapper. */
+function outcomeForError(slug, err) {
+    if (err instanceof FormDefinitionNotFoundError) {
+        return { redirectResult: { kind: "error", slug }, json: { status: 404, body: { error: err.message, code: "FORMS_DEFINITION_NOT_FOUND" } } };
+    }
+    if (err instanceof FormSubmissionValidationError) {
+        return {
+            redirectResult: { kind: "validation", slug, fieldErrors: err.fieldErrors },
+            json: { status: 400, body: { error: err.message, code: "FORMS_SUBMISSION_VALIDATION_ERROR", details: { fieldErrors: err.fieldErrors } } },
+        };
+    }
+    if (err instanceof FormRateLimitExceededError) {
+        return {
+            redirectResult: { kind: "rate-limited", slug, retryAfterSeconds: err.retryAfterSeconds },
+            json: { status: 429, body: { error: err.message, code: "FORMS_RATE_LIMIT_EXCEEDED", details: { retryAfterSeconds: err.retryAfterSeconds } } },
+        };
+    }
+    return { redirectResult: { kind: "error", slug }, json: { status: 500, body: { error: "internal error", code: "INTERNAL_ERROR" } } };
+}
+function sendFormSubmitOutcome(req, res, outcome, deps) {
+    if (wantsHtmlResponse(req)) {
+        redirectWithFormResult(req, res, outcome.redirectResult, deps);
+        return;
+    }
+    res.status(outcome.json.status).json(outcome.json.body);
+}
+/** Registers `POST /forms/:slug/submit`. Must be registered BEFORE the site `/:slug` catch-all.
+ *
+ * `express.urlencoded` is mounted on THIS route's own POST registration (not a global `app.ts`
+ * mount — same scoping precedent as `template-preview.ts`'s `POST` handler) because a real,
+ * JavaScript-disabled `<form method="post">` — the exact case this file's Post/Redirect/Get fix
+ * exists for — always encodes its body as `application/x-www-form-urlencoded`, which `app.ts`'s
+ * blanket `express.json()` cannot parse; without this, every field on a genuine browser submission
+ * would silently arrive as missing, failing REQUIRED-field validation on every real, non-JS
+ * submission regardless of the redirect fix. A `fetch`/JSON caller (every pre-existing test in this
+ * file) is unaffected — Express dispatches to whichever parser matches the request's actual
+ * `Content-Type`, so mounting both here is additive, never a double-parse of the same request. */
+export function createFormSubmitHandler(deps, _optional = {}) {
+    return async (req, res) => {
+        const slug = String(req.params.slug ?? "");
+        const body = boundBody(req.body);
+        const sourceIp = deps.resolveClientIp(req);
+        try {
+            const result = await deps.submit({
+                input: { workspaceId: deps.workspaceId, slug, body, sourceIp },
+            });
+            sendFormSubmitOutcome(req, res, outcomeForSuccess(slug, result), deps);
+        }
+        catch (err) {
+            if (err instanceof FormSubmissionValidationError && wantsHtmlResponse(req)) {
+                try {
+                    await setFormFlashCookieForValidationFailure(req, res, deps, slug, body);
+                }
+                catch (flashErr) {
+                    console.error(`[site/forms-submit] failed to set validation flash cookie (slug=${slug})`, flashErr);
+                }
+            }
+            sendFormSubmitOutcome(req, res, outcomeForError(slug, err), deps);
+        }
+    };
+}
+//# sourceMappingURL=handler.js.map

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

@@ -0,0 +1,2 @@
+export * from "./handler.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/forms/express/index.js

@@ -0,0 +1,2 @@
+export * from "./handler.js";
+//# sourceMappingURL=index.js.map

package/dist/forms/fields-json.d.ts

@@ -0,0 +1,14 @@
+import type { FormDefinitionRecord } from "./types.js";
+export type FormAuthoring = {
+    mode?: "builder" | "html";
+    html?: string | undefined;
+};
+export type HtmlFormDefinitionRecord = FormDefinitionRecord & FormAuthoring;
+/** Old rows remain arrays; authored forms use the same JSON-in-text column, without a migration. */
+export declare function decodeFormFields({ json }: {
+    json: string;
+}, _optional?: {}): Pick<HtmlFormDefinitionRecord, "fields" | "mode" | "html">;
+export declare function encodeFormFields({ definition }: {
+    definition: HtmlFormDefinitionRecord;
+}, _optional?: {}): string;
+//# sourceMappingURL=fields-json.d.ts.map

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