@agntcms/next 0.2.0

package/dist/form-BqY0H1V5.d.cts

@@ -0,0 +1,753 @@
+/**
+ * Per-field override record. Every property is optional; an absent property
+ * means "fall back to the form schema's behaviour for this field":
+ *
+ *   - `label`         — visible label. Defaults to `titleCase(fieldName)`.
+ *                       Field NAME (the payload key) is NEVER renamable.
+ *   - `placeholder`   — input placeholder text.
+ *   - `helpText`      — small text rendered below the input.
+ *   - `hidden`        — when `true`, the field is not rendered. If `default`
+ *                       is also set, the default value is included in the
+ *                       submitted payload exactly as if the user had typed it.
+ *                       If no default, the field is omitted entirely (the
+ *                       submit handler will reject if required).
+ *   - `order`         — sort key. Lower values render first. Fields without
+ *                       `order` render last in their original schema order
+ *                       (stable). Ties broken by schema order.
+ *   - `default`       — initial value seeded into the input. Stored as
+ *                       `unknown` because the override record is keyed by
+ *                       raw field name with no compile-time link back to
+ *                       the form schema. The `<Form>` component narrows
+ *                       per descriptor kind at render time and falls back
+ *                       to the schema default (with a one-shot console
+ *                       warning) when the stored shape doesn't match.
+ *
+ * Both the interface and the property values are `readonly` — overrides
+ * are content (snapshot-versioned, JSON-serialisable) and the runtime
+ * never mutates them after read.
+ */
+interface FormFieldOverride {
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly helpText?: string;
+    readonly hidden?: boolean;
+    readonly order?: number;
+    /**
+     * Initial value seeded into the field. Type is `unknown` because there
+     * is no compile-time link from the keyed field name back to the form
+     * schema. See file header for narrowing/fallback policy.
+     */
+    readonly default?: unknown;
+}
+/**
+ * Map from field name to override record. Keys are the form schema's
+ * raw field names (the payload keys). Fields not present in the map use
+ * schema defaults.
+ *
+ * Stored as a plain `Record` rather than `Readonly<Record<...>>` so it
+ * round-trips through `JSON.parse` cleanly (parsed objects are plain
+ * mutable objects). The runtime treats it as read-only by convention.
+ */
+type FormFieldOverrides = Record<string, FormFieldOverride>;
+/**
+ * A field descriptor a section author uses to expose per-section-instance
+ * form overrides as content. The `formName` references a registered
+ * `FormDefinition` by name (NOT a function reference, so the value is
+ * RSC-serialisable and can travel through the section data record like
+ * any other field).
+ *
+ * NOT allowed inside a form schema (forbidden via `FORM_FORBIDDEN_KINDS`
+ * in `domain/form.ts`). Forms cannot contain a form-overrides field —
+ * that would be a recursive content shape with no ergonomic editor UI.
+ *
+ * The descriptor's runtime value type is `FormFieldOverrides` (see
+ * `FieldValueFor` in `domain/schema.ts`).
+ */
+interface FormOverridesFieldDescriptor {
+    readonly kind: 'formOverrides';
+    /**
+     * Name of the form whose fields this descriptor overrides. Must match
+     * a form registered in `defineConfig({ forms: [...] })`. The runtime
+     * does NOT validate this at section-definition time (the form
+     * registry isn't visible to `defineSection`); the editor widget shows
+     * a "form not found" message instead of crashing.
+     */
+    readonly formName: string;
+    /**
+     * Default override map for a freshly inserted section. Defaults to
+     * `{}` (i.e. all fields fall back to schema defaults) when omitted —
+     * the conditional spread in `FormOverridesField()` keeps the property
+     * absent under `exactOptionalPropertyTypes`.
+     */
+    readonly default?: FormFieldOverrides;
+}
+/**
+ * Factory for a `FormOverridesFieldDescriptor`.
+ *
+ * `formName` matches the `name` of the `FormDefinition` produced by
+ * `defineForm()`. The factory itself does NOT validate that the name
+ * resolves to a registered form — registry lookup happens lazily in
+ * the editor widget, with a graceful "form not found" message.
+ *
+ * Why a factory and not a singleton: every section author binds this
+ * descriptor to a specific form name, so there is no useful no-args
+ * shape. `LinkField` is a singleton because every link descriptor is
+ * structurally identical; `FormOverridesField('contact')` is not.
+ */
+declare const FormOverridesField: (formName: string, opts?: {
+    readonly default?: FormFieldOverrides;
+}) => FormOverridesFieldDescriptor;
+
+/**
+ * A section schema: a record mapping field names to built-in field
+ * descriptors. This is the COMPILE-TIME description authors pass to
+ * `defineSection` and that the runtime uses to resolve per-field types.
+ *
+ * Defined as a plain `Record<string, FieldDescriptor>` — deliberately
+ * WITHOUT a `Readonly<>` wrapper. The reason: `SectionSchema` is used
+ * as a constraint in `extends` position (e.g. `S extends SectionSchema`).
+ * Adding `Readonly` forces an index signature onto any schema extending
+ * it, which collapses `keyof S` to `string` under mapped types and
+ * erases the concrete field names the type machinery depends on. Keeping
+ * it as a plain Record lets finite object-literal schemas remain
+ * assignable without acquiring an index signature, preserving `keyof S`
+ * as the precise union of field-name literals.
+ *
+ * The `Readonly` safety concern (preventing mutation of schema objects)
+ * is a compile-time convenience; the `keyof S` preservation is a
+ * correctness requirement for `DataOf<S>`, `PageContent<Mode, S>`, and
+ * every mapped type that fans out over schema keys.
+ */
+type SectionSchema = Record<string, FieldDescriptor>;
+/**
+ * The runtime value of a `ReferenceField`: a pointer to another page by
+ * slug. In v1 references are always page-to-page; richer target kinds
+ * (collections, entries, etc.) are out of scope (ARCHITECTURE.md section 12).
+ */
+interface ReferenceValue {
+    readonly slug: string;
+}
+/**
+ * Maps a built-in `FieldDescriptor` to the type of its runtime value.
+ *
+ * This is the authoritative mapping used by both the runtime's
+ * `PageContent<Mode, S>` and the section-definition layer's own
+ * type machinery.
+ *
+ * Built-in field -> runtime type:
+ *   text       -> string
+ *   richText   -> string         (markdown source)
+ *   image      -> ImageValue     (`{ filename, alt }`, see domain/fields.ts)
+ *   video      -> VideoValue     (`{ url, aspectRatio? }`, see domain/fields.ts)
+ *   reference  -> ReferenceValue
+ *   link       -> LinkValue      (discriminated union; see `domain/fields.ts`)
+ *   button     -> ButtonValue    (`{ label, variant, link? }`, see domain/fields.ts)
+ *   number     -> number
+ *   boolean    -> boolean
+ *   select     -> string         (one of the descriptor's option values)
+ *   list       -> Array<ListItem<S>>  (each item: derived data shape of S
+ *                                      plus opaque `_id`)
+ *   formOverrides -> FormFieldOverrides
+ *                                     (record of per-field overrides for
+ *                                      a section instance pointing at a
+ *                                      named form; see domain/formOverrides.ts)
+ *
+ * The `list` case recurses through the schema. The recursion has to live
+ * on this side of the descriptor/value seam because `ListField<S>`'s
+ * value depends on `FieldValueFor` applied to every member of `S`.
+ */
+type FieldValueFor<F extends FieldDescriptor> = F extends TextField ? string : F extends RichTextField ? string : F extends ImageField ? ImageValue : F extends VideoField ? VideoValue : F extends ReferenceField ? ReferenceValue : F extends LinkField ? LinkValue : F extends ButtonField ? ButtonValue : F extends NumberField ? number : F extends BooleanField ? boolean : F extends SelectField ? string : F extends ListField<infer S> ? ReadonlyArray<ListItem<S>> : F extends FormOverridesFieldDescriptor ? FormFieldOverrides : never;
+/**
+ * The runtime shape of a single item in a `ListField<S>` value.
+ *
+ * Each item is the derived per-field record of `S` (every field name
+ * resolved through `FieldValueFor`) plus an opaque stable `_id` string.
+ * The `_id` is set once when the item is created in the editor and
+ * persists for the item's lifetime — this is how the editor tracks
+ * items across reorder and delete without using index positions.
+ *
+ * `_id` is exposed in the runtime value type because section components
+ * may need it (e.g. to use as a React key when rendering the array).
+ * The underscore prefix signals "framework-managed; don't put authoring
+ * data here".
+ */
+type ListItem<S extends SectionSchema> = {
+    readonly [K in keyof S]: FieldValueFor<S[K]>;
+} & {
+    readonly _id: string;
+};
+
+/**
+ * Runtime value of an image field. Both fields required; empty alt is a
+ * validation error. Alt is collected per-usage in the picker modal — it
+ * is not stored on disk as metadata, because that experiment (v0.1.16–17)
+ * was reverted as over-engineering. Keep alt required to preserve a11y
+ * as a hard floor.
+ */
+interface ImageValue {
+    readonly filename: string;
+    readonly alt: string;
+}
+/**
+ * Runtime value of a video field. `url` is the raw URL the author
+ * pasted. `aspectRatio` is optional; when absent the rendered iframe
+ * defaults to 16:9. The closed string-literal union mirrors the
+ * options the picker modal exposes — adding a ratio means updating the
+ * union AND the picker's `<select>`. `caption` is an optional short
+ * plain-text caption rendered below the iframe; intentionally NOT
+ * markdown (see `VideoField` JSDoc).
+ */
+interface VideoValue {
+    readonly url: string;
+    readonly aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
+    readonly caption?: string;
+}
+/**
+ * Runtime value of a `LinkField`. Discriminated by `type`:
+ *
+ *   - `internal` carries a `slug` (no leading `/`). Empty string is
+ *     "not yet selected"; `'home'` is the canonical root page; any
+ *     other slug renders as `/<slug>` via `hrefOf()`.
+ *   - `external` carries a full `url` (must start with `http://` or
+ *     `https://`). Empty string is "not yet entered".
+ *   - `email` carries an `email` address. `hrefOf()` returns
+ *     `mailto:<email>` when populated, or `''` when empty so the
+ *     section component can avoid rendering a stray anchor.
+ *   - `phone` carries a `phone` string for display (the formatted form
+ *     authors typed). `hrefOf()` strips non-`[\d+]` characters when
+ *     producing the `tel:` URI, so `phone` may carry parens, spaces,
+ *     and hyphens for legibility.
+ *
+ * `label` is always required (empty string allowed). It is the display
+ * text the section component renders.
+ */
+type LinkValue = {
+    readonly type: 'internal';
+    readonly slug: string;
+    readonly label: string;
+} | {
+    readonly type: 'external';
+    readonly url: string;
+    readonly label: string;
+} | {
+    readonly type: 'email';
+    readonly email: string;
+    readonly label: string;
+} | {
+    readonly type: 'phone';
+    readonly phone: string;
+    readonly label: string;
+};
+/**
+ * Runtime value of a `ButtonField`.
+ *
+ *   - `label`   — visible button text. Required, may be empty (the
+ *                 picker shows a "Click to add label" hint then).
+ *   - `variant` — a presentation key matching one of the descriptor's
+ *                 declared `variants[].value`. Section components map
+ *                 this to a className. Stored verbatim so a variant
+ *                 removed from the schema after content was authored
+ *                 does not silently rewrite the saved value — the
+ *                 picker surfaces the stale variant as "(missing)" so
+ *                 the editor can fix it.
+ *   - `link`    — OPTIONAL. When present, a discriminated `LinkValue`
+ *                 (the same union used by `LinkField`). Sections decide
+ *                 whether to wrap the rendered button in an `<a>` based
+ *                 on `link !== undefined`.
+ */
+interface ButtonValue {
+    readonly label: string;
+    readonly variant: string;
+    readonly link?: LinkValue;
+}
+/** A single option in a `SelectField`. */
+interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * The shape of a single seed item declared on `ListField.default`. Authors
+ * may omit any field — missing fields fall back to per-kind blanks at
+ * build time. `_id` is intentionally excluded: the editor regenerates ids
+ * recursively when cloning the default, so a literal id in the schema
+ * would be overwritten anyway.
+ */
+type ListItemDefault<S extends SectionSchema> = {
+    readonly [K in keyof S]?: FieldValueFor<S[K]>;
+};
+/**
+ * The closed union of all built-in field descriptors.
+ *
+ * This is the v1 vocabulary for describing a section's schema. It is closed
+ * on purpose: consistency of the editing UI depends on the runtime knowing
+ * every possible field type ahead of time.
+ *
+ * `FormOverridesFieldDescriptor` is section-only: it is a member of this
+ * union (so a section schema can carry it) but is explicitly listed in
+ * `FORM_FORBIDDEN_KINDS` (see `domain/form.ts`), so a form schema cannot
+ * carry one. The descriptor lives in `domain/formOverrides.ts` to keep
+ * the override-shape types (`FormFieldOverride`, `FormFieldOverrides`) in
+ * the same file as the descriptor that produces them.
+ */
+type FieldDescriptor = TextField | RichTextField | ImageField | VideoField | ReferenceField | LinkField | ButtonField | NumberField | BooleanField | SelectField | ListField | FormOverridesFieldDescriptor;
+/** String literal union of every descriptor's `kind` — useful for maps and tables. */
+type FieldKind = FieldDescriptor['kind'];
+/** Plain inline text (single-line or small multi-line without formatting). */
+interface TextField {
+    readonly kind: 'text';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: string;
+}
+declare const TextField: TextField;
+/** Rich text with inline formatting (bold, links, etc.); serialized as markdown. */
+interface RichTextField {
+    readonly kind: 'richText';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: string;
+}
+declare const RichTextField: RichTextField;
+/**
+ * An image stored through the asset adapter.
+ *
+ * The runtime value is an `ImageValue` object (`{ filename, alt }`). Alt
+ * is collected per-usage in the image picker modal and lives in the
+ * section's `data` alongside the filename — it is NOT stored on disk as
+ * asset metadata (the 0.1.16–0.1.17 sidecar experiment was reverted).
+ * Keeping alt required at the descriptor level preserves a11y as a hard
+ * floor at authoring time.
+ */
+interface ImageField {
+    readonly kind: 'image';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: ImageValue;
+}
+declare const ImageField: ImageField;
+/**
+ * An embedded video referenced by URL.
+ *
+ * The runtime value is a `VideoValue` object (`{ url, aspectRatio?, caption? }`).
+ * Unlike `ImageField`, videos are NOT stored as assets on disk — `url` is a
+ * full URL pointing at YouTube / Vimeo / Wistia / Loom (the v1 set of
+ * recognised providers). Detection of the embed URL is done by the
+ * pure helper `parseVideoUrl()` (`domain/video.ts`); when that helper
+ * returns no embed URL, the editor renders a "no video — click to add"
+ * placeholder.
+ *
+ * `aspectRatio` is OPTIONAL on purpose: omitting it means "auto", which
+ * the editor and the rendered iframe both interpret as 16:9. Encoding
+ * "auto" as the absence of the key (rather than the literal string
+ * `'auto'`) keeps `VideoValue` minimal and matches how
+ * `exactOptionalPropertyTypes` distinguishes "not set" from "explicitly
+ * undefined".
+ *
+ * `caption` is an optional short plain-text caption rendered below the
+ * iframe. It is intentionally PLAIN TEXT (not markdown) — captions are
+ * short ("A 2-minute walkthrough") and don't need rich-text features.
+ * It travels with the video data so the picker modal can edit URL,
+ * ratio, and caption in one place.
+ */
+interface VideoField {
+    readonly kind: 'video';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: VideoValue;
+}
+declare const VideoField: VideoField;
+/** A reference to another page or content entry by id. */
+interface ReferenceField {
+    readonly kind: 'reference';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: string;
+}
+declare const ReferenceField: ReferenceField;
+/**
+ * A link with display label, modelled as an explicit choice between an
+ * internal page reference, an external URL, an email address, or a
+ * phone number.
+ *
+ * Runtime value is a `LinkValue` discriminated union — see below.
+ * The descriptor itself does NOT render an anchor; section components
+ * decide how to render. The typical pattern is to compute the href via
+ * `hrefOf(link)` and the target/rel pair via `linkAnchorAttrs(link)`
+ * (see `domain/link.ts`).
+ *
+ * Why an explicit `type` discriminator rather than the previous
+ * "external?: boolean" flag: each branch carries fundamentally
+ * different data (a slug reference, a URL, an email address, a phone
+ * number) and the editor renders a different sub-form for each. Having
+ * a tagged value-side per branch lets each carry exactly the data it
+ * needs without a dual-purpose `href` string that means different
+ * things in different modes.
+ */
+interface LinkField {
+    readonly kind: 'link';
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: LinkValue;
+}
+declare const LinkField: LinkField;
+/**
+ * A numeric value with optional validation hints.
+ *
+ * `min`/`max`/`step` are HINTS for the editor widget, not enforced at the
+ * descriptor level. The runtime never validates — the editor's number
+ * input clamps and steps to keep authoring sensible. Storage carries
+ * whatever the author committed, including out-of-range values from
+ * older content if the descriptor's bounds tighten over time.
+ */
+interface NumberField {
+    readonly kind: 'number';
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+declare const NumberField: NumberField;
+/** A boolean toggle. */
+interface BooleanField {
+    readonly kind: 'boolean';
+    readonly default?: boolean;
+}
+declare const BooleanField: BooleanField;
+/**
+ * A choice from a fixed list of options.
+ *
+ * Runtime value is `string` (one of the option `value`s). We deliberately
+ * do NOT type the value as a literal union derived from `options` in v1
+ * — that would require `as const` discipline at every author's call
+ * site, which is a footgun for the typical author. A generic-tied
+ * literal-union variant can be added later without breaking the v1
+ * shape.
+ */
+interface SelectField {
+    readonly kind: 'select';
+    readonly options: readonly SelectOption[];
+    readonly default?: string;
+}
+/**
+ * Factory for a `SelectField`. The `options` array shape is preserved on
+ * the descriptor for the editor widget to render; the runtime value is a
+ * plain `string` in v1 (see `SelectField` for why we did not derive a
+ * literal union from `options`).
+ */
+declare const SelectField: (options: readonly SelectOption[], opts?: {
+    readonly default?: string;
+}) => SelectField;
+/**
+ * A styled call-to-action button.
+ *
+ * Runtime value is a `ButtonValue` ({ label, variant, link? }). The
+ * descriptor itself does NOT render styles — variant strings are opaque
+ * presentation keys (`'primary'` / `'secondary'` / `'ghost'` / whatever
+ * the section declares); section components own their CSS and pick a
+ * className from `value.variant` at render time. The framework does
+ * NOT enforce a global variant set; each `ButtonField` declaration
+ * carries the closed list of variants its section supports.
+ *
+ * `link` is optional on purpose. A button without a link is a pure UI
+ * affordance (e.g. "Open dialog", a future click handler) — separating
+ * the styled-CTA concern from the navigation concern keeps `LinkField`
+ * pure navigation data and lets sections use `ButtonValue` for both
+ * link-CTAs and non-navigating action buttons.
+ *
+ * Why a separate descriptor instead of `LinkField` + a sibling
+ * `SelectField` for the variant: in the editor, label + variant + link
+ * belong together. Surfacing them as two unrelated fields forced
+ * authors to edit the visible text in one modal and the visual style in
+ * another. `ButtonField` collapses that into a single picker modal.
+ */
+interface ButtonField {
+    readonly kind: 'button';
+    /**
+     * The closed list of variants this button supports. The picker modal
+     * renders a `<select>` populated from these options; section authors
+     * decide what styles their CSS supports. Order is preserved — index 0
+     * is the canonical fallback when content has no variant set.
+     */
+    readonly variants: ReadonlyArray<SelectOption>;
+    /** Override the built-in placeholder used when inserting a new section. */
+    readonly default?: ButtonValue;
+}
+/**
+ * Factory for a `ButtonField`. The `variants` array shape is preserved
+ * verbatim so the picker modal can render the variant `<select>` from
+ * the descriptor; the runtime value (`ButtonValue.variant`) is a plain
+ * string in v1 (same rationale as `SelectField` — see that JSDoc).
+ *
+ * If `default.variant` does not match any declared `variants[].value`,
+ * the picker still surfaces the stored value as "(missing)" so authors
+ * can fix it. We do not validate at factory time: schema-author errors
+ * surface at editing time, not at module-load time.
+ */
+declare const ButtonField: (variants: ReadonlyArray<SelectOption>, opts?: {
+    readonly default?: ButtonValue;
+}) => ButtonField;
+/**
+ * A list of structured items, each shaped by a sub-schema.
+ *
+ * Runtime value is `Array<ListItem<S>>` where `ListItem<S>` is the
+ * derived data shape of `itemSchema` plus an opaque stable `_id` string.
+ * The `_id` is generated when an item is first inserted (via the
+ * editable widget) and persists for the item's lifetime so the editor
+ * can track items across reorder/delete without index churn.
+ *
+ * `itemSchema` is `SectionSchema` — the same vocabulary as a top-level
+ * section's data. This means lists of objects with text/richText/image/
+ * link/number/boolean/select fields, and even nested lists. Recursion
+ * is allowed but not optimised; deeply nested lists will work but the
+ * editor UX is intentionally flat (one level of cards).
+ *
+ * `min`/`max` are HINTS for the editor widget, not enforced at runtime.
+ *
+ * `default` (optional) is an array of seed items used when the editor
+ * builds a blank instance of a parent item that contains this list — the
+ * canonical case is "a new tier comes pre-filled with two feature rows".
+ * Each entry is a `Partial` over the item shape so authors can omit fields
+ * they don't care about (those fall back to per-kind blanks). `_id` is
+ * deliberately NOT part of the default-item shape: the editor mints a
+ * fresh `_id` for every cloned entry, recursively, so two consecutive
+ * blank-builds never share ids. See `buildBlankItem` in
+ * `react/editable/ItemFormEditor.tsx` for the regeneration rule.
+ */
+interface ListField<S extends SectionSchema = SectionSchema> {
+    readonly kind: 'list';
+    readonly itemSchema: S;
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: ReadonlyArray<ListItemDefault<S>>;
+}
+/**
+ * Factory for a `ListField`. Generic over the item schema so the runtime
+ * value type (`FieldValueFor<ListField<S>>`) can include the precise
+ * shape of each list item. See `domain/schema.ts` for the recursion.
+ */
+declare const ListField: <S extends SectionSchema>(itemSchema: S, opts?: {
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: ReadonlyArray<ListItemDefault<S>>;
+}) => ListField<S>;
+
+interface Section<T extends string = string, D = unknown> {
+    readonly id: string;
+    readonly type: T;
+    readonly data: D;
+    /** When set, this section is a reference to a named global.
+     *  The runtime resolves `type` and `data` from the global at read time. */
+    readonly globalRef?: string;
+}
+
+interface PageSeo {
+    readonly title: string;
+    readonly description: string;
+    readonly ogImage?: ImageValue;
+    readonly canonical?: string;
+}
+interface Page {
+    readonly slug: string;
+    readonly seo: PageSeo;
+    /**
+     * Tags for `listPages` filtering. Matching is case-sensitive exact:
+     * `tags: ['Post']` does NOT match a query for `tag=post`.
+     * (See ARCHITECTURE.md §4.)
+     */
+    readonly tags?: readonly string[];
+    /** Short summary used by listing sections (PostList etc.). */
+    readonly excerpt?: string;
+    /** Cover image for listing sections / blog cards. */
+    readonly coverImage?: ImageValue;
+    /**
+     * ISO 8601 publication date used by `listPages` for sorting. When
+     * absent, the runtime falls back to the storage adapter's "last
+     * modified" timestamp (file mtime for the FS adapter).
+     */
+    readonly publishedAt?: string;
+    readonly sections: readonly Section[];
+}
+/**
+ * `Page` without `sections` — the metadata-only projection returned by
+ * `listPages`. Used for blog-index-style listing pages where loading
+ * every page's full section tree would be wasteful.
+ *
+ * Defined as `Omit<Page, 'sections'>` so adding a new metadata field to
+ * `Page` automatically widens `PageSummary` — no two-place edits.
+ */
+type PageSummary = Omit<Page, 'sections'>;
+
+/**
+ * Closed union of field descriptors allowed in a form schema in v1.
+ *
+ * Why this is a strict subset of `FieldDescriptor`:
+ *   - `image`     → file upload is deferred (§6.5, §12).
+ *   - `video`     → forms collect text/numbers/etc. from end users; a
+ *                   public submission carrying an embed URL is a semantic
+ *                   outlier (videos are authoring content, not user input).
+ *   - `reference` → semantically odd for user input — references are an
+ *                   authoring construct, not a public-site concern.
+ *   - `list`      → payload validation becomes recursive; YAGNI for the
+ *                   newsletter/contact use cases v1 targets.
+ *
+ * Keeping this set closed at the type level makes the restriction visible
+ * to authors at compile time. The runtime check in `defineForm()` provides
+ * the same guarantee for callers that erase types via `as`.
+ */
+type FormFieldDescriptor = TextField | RichTextField | NumberField | BooleanField | SelectField | LinkField;
+/**
+ * A form schema: a record mapping field names to allowed form-field descriptors.
+ *
+ * Defined as a plain `Record` (no `Readonly<>`) for the same `keyof S`
+ * preservation reason described in `domain/schema.ts`'s `SectionSchema`.
+ */
+type FormSchema = Record<string, FormFieldDescriptor>;
+/**
+ * Registration record produced by `defineForm`. The runtime registry
+ * (`forms/registry.ts`) stores these keyed by `name`, mirroring the
+ * section registry.
+ *
+ * `honeypot` is the OPTIONAL name of an additional hidden field the
+ * frontend renders out-of-schema (e.g. `<input name="website" style="display:none">`).
+ * If a non-empty value arrives in a submit payload at that key, the server
+ * suppresses the submission silently. On the wire the response is
+ * indistinguishable from a successful no-op (200 OK with `{ ok: true,
+ * stored: false }`) — by design, so a bot cannot tell from the response
+ * whether it was filtered. The `suppressed: 'honeypot'` marker is INTERNAL
+ * to the runtime's `SubmitFormResult` discriminant (see
+ * `runtime/submitForm.ts`); the submit route handler strips it before
+ * returning. The honeypot field name MUST NOT collide with any real schema
+ * field name — `defineForm()` enforces this.
+ */
+interface FormDefinition<S extends FormSchema = FormSchema> {
+    /** Unique name. Used as the URL-safe identifier in submit/list/read endpoints. */
+    readonly name: string;
+    /** Field descriptors. */
+    readonly schema: S;
+    /** Optional honeypot field name (out-of-schema). See type doc. */
+    readonly honeypot?: string;
+}
+/**
+ * Erased/heterogeneous form definition for use in lists (e.g.
+ * `defineConfig({ forms: [Contact, Newsletter] })`). Mirrors the
+ * `AnySectionDefinition` pattern in `sections/defineSection.ts`.
+ */
+interface AnyFormDefinition {
+    readonly name: string;
+    readonly schema: FormSchema;
+    readonly honeypot?: string;
+}
+/**
+ * Minimal lookup interface for a registry of form definitions.
+ *
+ * Lives in `domain/` because the runtime (`runtime/submitForm.ts`) needs
+ * to depend on "something that can look up a form by name" without having
+ * to import from the `forms/` sibling. This keeps the dependency graph
+ * `runtime → domain, storage` (ARCHITECTURE.md §8) intact.
+ *
+ * The concrete registry built by `forms/registry.ts` (`FormRegistry`)
+ * structurally satisfies this interface — no wrapping needed at the call
+ * site. `definitions` is included so handlers can enumerate registered
+ * forms (for `forms/list`).
+ */
+interface FormLookup {
+    readonly definitions: ReadonlyArray<AnyFormDefinition>;
+    get(name: string): AnyFormDefinition | undefined;
+    has(name: string): boolean;
+}
+/**
+ * A single form submission stored by a `SubmissionStorageAdapter`.
+ *
+ * Shape is intentionally flat:
+ *   - `formName` selects the form schema this submission belongs to.
+ *   - `payload` is the validated record of field values, opaque to the
+ *     storage layer (storage doesn't know schemas; the runtime validates
+ *     before calling the adapter).
+ *   - `submittedAt` is an ISO-8601 string. We use a string rather than a
+ *     `Date` because submissions cross JSON boundaries (route handler →
+ *     adapter → potentially webhook → potentially admin UI) and
+ *     `Date.toISOString()` round-tripping has known edge cases.
+ *   - `id` is an opaque, lex-sortable identifier. The FS adapter uses it
+ *     as a tie-breaker when two submissions share a `submittedAt`
+ *     millisecond.
+ *
+ * Privacy note: the IP address is NOT stored by default (ARCHITECTURE.md
+ * §6.5 / §11). Adding it would be a config-flag change.
+ */
+interface Submission {
+    readonly formName: string;
+    /**
+     * Validated payload. Each value type matches the runtime type of its
+     * declared `FormFieldDescriptor` (see `formPayloadValueFor`). Stored
+     * as `unknown` here so the storage layer stays schema-agnostic.
+     */
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** ISO-8601 timestamp of when the submit handler accepted the payload. */
+    readonly submittedAt: string;
+    /** Lex-sortable opaque identifier (ULID-like). */
+    readonly id: string;
+}
+/**
+ * Lightweight summary of a stored submission, returned by
+ * `SubmissionStorageAdapter.list`. The full payload is fetched on demand
+ * via `read` so the AdminModal list view stays cheap even when a form
+ * accumulates thousands of entries.
+ */
+interface SubmissionSummary {
+    readonly id: string;
+    readonly submittedAt: string;
+}
+/**
+ * Public adapter-info descriptor surfaced through the runtime so handlers
+ * (notably the frozen `forms/list` route) can tell the AdminModal whether
+ * submissions are locally readable. Two shapes:
+ *   - `{ kind: 'fs' }`               — local FS submissions; readable.
+ *   - `{ kind: 'webhook', host }`    — webhook adapter; not locally readable.
+ *
+ * The host is the `URL.host` portion of the configured webhook (no path,
+ * no query, no credentials) — surfaced so the AdminModal can render a
+ * "POSTed to <host>" hint without leaking secrets.
+ */
+type SubmissionAdapterInfo = {
+    readonly kind: 'fs';
+} | {
+    readonly kind: 'webhook';
+    readonly host: string;
+};
+/**
+ * Storage adapter for form submissions (ARCHITECTURE.md §5, §6.5).
+ *
+ * Implementations:
+ *   - FS: writes `<root>/<formName>/<submittedAt>-<id>.json`. Default.
+ *   - Webhook: POSTs each submission to a configured URL; does NOT write
+ *              to disk. `list`/`read` throw if called (no local copy).
+ *
+ * `store` is the only mandatory write path. `list`/`read` are required
+ * to satisfy AdminModal's "Submissions" tab (Dispatch 2). A webhook-only
+ * setup signals "no local copies" by throwing a typed error so the route
+ * handler can return a clean 405.
+ *
+ * `info` is a small introspection field. Frozen route handlers wire the
+ * adapter into `createFormsListHandler` so the AdminModal knows whether
+ * to attempt `/forms/read` (FS) or render a "remote" hint (webhook).
+ * Without it the handler would default to `kind: 'fs'` and the modal
+ * would issue 501-returning fetches against a webhook adapter.
+ *
+ * Implementations MUST NOT throw for "form has no submissions"; `list`
+ * MUST return an empty array in that case. `read(formName, id)` MUST
+ * return `null` for an unknown id (mirrors `ContentStorageAdapter.readPage`).
+ */
+interface SubmissionStorageAdapter {
+    /** Static descriptor of this adapter. See `SubmissionAdapterInfo`. */
+    readonly info: SubmissionAdapterInfo;
+    /** Persist a submission. Returns void; the runtime stamps id+submittedAt. */
+    store(submission: Submission): Promise<void>;
+    /** List submissions for a form, newest first. Returns [] if none. */
+    list(formName: string): Promise<ReadonlyArray<SubmissionSummary>>;
+    /** Read a single submission. Returns `null` if the id is unknown. */
+    read(formName: string, id: string): Promise<Submission | null>;
+}
+/**
+ * Thrown by adapters that have no local read surface (e.g. webhook-only).
+ * The route handler maps this to HTTP 501 / 405 so the AdminModal can
+ * surface a helpful message.
+ */
+declare class SubmissionsNotReadableError extends Error {
+    constructor(message?: string);
+}
+
+export { type AnyFormDefinition as A, ButtonField as B, type PageSeo as C, type Section as D, type SelectOption as E, type FormLookup as F, ImageField as I, LinkField as L, NumberField as N, type Page as P, RichTextField as R, type SectionSchema as S, TextField as T, VideoField as V, type FormSchema as a, type FormDefinition as b, type FieldDescriptor as c, type ImageValue as d, type VideoValue as e, ReferenceField as f, type ReferenceValue as g, type LinkValue as h, type ButtonValue as i, BooleanField as j, SelectField as k, ListField as l, type FormOverridesFieldDescriptor as m, type FormFieldOverrides as n, type SubmissionStorageAdapter as o, type FormFieldDescriptor as p, type FormFieldOverride as q, FormOverridesField as r, type Submission as s, type SubmissionAdapterInfo as t, type SubmissionSummary as u, SubmissionsNotReadableError as v, type PageSummary as w, type FieldValueFor as x, type FieldKind as y, type ListItem as z };