@agntcms/next 0.2.0

package/dist/defineForm-Bp9vzW56.d.ts

@@ -0,0 +1,71 @@
+import { a as FormSchema, b as FormDefinition } from './form-BqY0H1V5.js';
+
+/**
+ * Input shape for `defineForm`. Split out so the factory can use a single
+ * generic parameter for both input and output, the same pattern as
+ * `defineSection`.
+ */
+interface DefineFormInput<S extends FormSchema> {
+    readonly name: string;
+    readonly schema: S;
+    /**
+     * Optional honeypot field name (out-of-schema). The route handler treats
+     * a non-empty value at this key in the submit payload as a bot
+     * indicator and silently drops the submission. The handler MUST NOT
+     * leak suppression to the client (returns 200 ok with `stored: false`).
+     *
+     * MUST NOT collide with any field name in `schema`.
+     */
+    readonly honeypot?: string;
+}
+/** Thrown when `defineForm` rejects a form schema that violates the v1 restrictions. */
+declare class InvalidFormFieldError extends Error {
+    readonly formName: string;
+    readonly fieldName: string;
+    readonly fieldKind: string;
+    constructor(formName: string, fieldName: string, fieldKind: string);
+}
+/**
+ * Thrown when a `honeypot` value is unusable. Discriminated by `reason`:
+ *
+ *   - `'collision'` — the honeypot name matches a field already declared
+ *     in the schema. This would let bot traffic occupy a real field key.
+ *   - `'empty'` — the honeypot name is the empty string. An empty key is
+ *     never a valid identifier in the submit payload, so the honeypot
+ *     check would silently always pass; this is treated as an authoring
+ *     mistake.
+ *
+ * Single class with a discriminator (rather than a second error class)
+ * keeps the public error surface small while still letting callers
+ * distinguish the two failure modes through `err.reason`.
+ */
+declare class HoneypotCollisionError extends Error {
+    readonly formName: string;
+    readonly fieldName: string;
+    readonly reason: 'collision' | 'empty';
+    constructor(formName: string, fieldName: string, reason?: 'collision' | 'empty');
+}
+/** Thrown when `name` is empty or fails the conservative URL-segment check. */
+declare class InvalidFormNameError extends Error {
+    constructor(name: string);
+}
+/**
+ * Type-safe factory for a `FormDefinition`.
+ *
+ * Compile-time guarantee: `S extends FormSchema` constrains each field
+ * to `FormFieldDescriptor` (the closed v1 subset). Runtime guarantee:
+ * the factory iterates `schema` and throws `InvalidFormFieldError` if any
+ * descriptor's `kind` is in `FORM_FORBIDDEN_KINDS`. Both layers exist on
+ * purpose — see file header.
+ *
+ * Allowed field kinds (see ARCHITECTURE.md §6.5):
+ *   text, richText, number, boolean, select, link
+ *
+ * Forbidden in v1 (throws):
+ *   image     — file upload deferred (§6.5, §12)
+ *   reference — semantic mismatch for user input
+ *   list      — recursive payload validation, YAGNI for v1
+ */
+declare function defineForm<S extends FormSchema>(input: DefineFormInput<S>): FormDefinition<S>;
+
+export { type DefineFormInput as D, HoneypotCollisionError as H, InvalidFormFieldError as I, InvalidFormNameError as a, defineForm as d };

package/dist/defineForm-CJ8KZC93.d.cts

@@ -0,0 +1,71 @@
+import { a as FormSchema, b as FormDefinition } from './form-BqY0H1V5.cjs';
+
+/**
+ * Input shape for `defineForm`. Split out so the factory can use a single
+ * generic parameter for both input and output, the same pattern as
+ * `defineSection`.
+ */
+interface DefineFormInput<S extends FormSchema> {
+    readonly name: string;
+    readonly schema: S;
+    /**
+     * Optional honeypot field name (out-of-schema). The route handler treats
+     * a non-empty value at this key in the submit payload as a bot
+     * indicator and silently drops the submission. The handler MUST NOT
+     * leak suppression to the client (returns 200 ok with `stored: false`).
+     *
+     * MUST NOT collide with any field name in `schema`.
+     */
+    readonly honeypot?: string;
+}
+/** Thrown when `defineForm` rejects a form schema that violates the v1 restrictions. */
+declare class InvalidFormFieldError extends Error {
+    readonly formName: string;
+    readonly fieldName: string;
+    readonly fieldKind: string;
+    constructor(formName: string, fieldName: string, fieldKind: string);
+}
+/**
+ * Thrown when a `honeypot` value is unusable. Discriminated by `reason`:
+ *
+ *   - `'collision'` — the honeypot name matches a field already declared
+ *     in the schema. This would let bot traffic occupy a real field key.
+ *   - `'empty'` — the honeypot name is the empty string. An empty key is
+ *     never a valid identifier in the submit payload, so the honeypot
+ *     check would silently always pass; this is treated as an authoring
+ *     mistake.
+ *
+ * Single class with a discriminator (rather than a second error class)
+ * keeps the public error surface small while still letting callers
+ * distinguish the two failure modes through `err.reason`.
+ */
+declare class HoneypotCollisionError extends Error {
+    readonly formName: string;
+    readonly fieldName: string;
+    readonly reason: 'collision' | 'empty';
+    constructor(formName: string, fieldName: string, reason?: 'collision' | 'empty');
+}
+/** Thrown when `name` is empty or fails the conservative URL-segment check. */
+declare class InvalidFormNameError extends Error {
+    constructor(name: string);
+}
+/**
+ * Type-safe factory for a `FormDefinition`.
+ *
+ * Compile-time guarantee: `S extends FormSchema` constrains each field
+ * to `FormFieldDescriptor` (the closed v1 subset). Runtime guarantee:
+ * the factory iterates `schema` and throws `InvalidFormFieldError` if any
+ * descriptor's `kind` is in `FORM_FORBIDDEN_KINDS`. Both layers exist on
+ * purpose — see file header.
+ *
+ * Allowed field kinds (see ARCHITECTURE.md §6.5):
+ *   text, richText, number, boolean, select, link
+ *
+ * Forbidden in v1 (throws):
+ *   image     — file upload deferred (§6.5, §12)
+ *   reference — semantic mismatch for user input
+ *   list      — recursive payload validation, YAGNI for v1
+ */
+declare function defineForm<S extends FormSchema>(input: DefineFormInput<S>): FormDefinition<S>;
+
+export { type DefineFormInput as D, HoneypotCollisionError as H, InvalidFormFieldError as I, InvalidFormNameError as a, defineForm as d };

package/dist/defineSection-9qQ5ulAH.d.cts

@@ -0,0 +1,243 @@
+import { S as SectionSchema, c as FieldDescriptor, T as TextField, R as RichTextField, I as ImageField, d as ImageValue, V as VideoField, e as VideoValue, f as ReferenceField, g as ReferenceValue, L as LinkField, h as LinkValue, B as ButtonField, i as ButtonValue, N as NumberField, j as BooleanField, k as SelectField, l as ListField, m as FormOverridesFieldDescriptor, n as FormFieldOverrides } from './form-BqY0H1V5.cjs';
+
+declare const __slot: unique symbol;
+/**
+ * Opaque editable slot. The runtime hands `<EditableText>` /
+ * `<EditableImage>` / etc. exactly this shape; the brand `[__slot]: K` is
+ * phantom (never set at runtime) and exists only to stop the slot from
+ * being assigned to `React.ReactNode` at JSX render sites. The slot kind
+ * `K` lets the matching editable component refuse a mismatched widget at
+ * compile time (`<EditableText field={imageSlot}>` is a TS error).
+ *
+ * The `value` is `V | PreviewFieldLike<V>` because the runtime wraps with
+ * `PreviewField` only in preview mode; published mode hands the bare
+ * value. The `read()` helper unwraps both branches.
+ */
+interface EditableSlot<K extends string, V> {
+    readonly [__slot]: K;
+    readonly value: V | PreviewFieldLike<V>;
+}
+/**
+ * Local structural replica of `PreviewFieldLike<T>` from
+ * `react/editable/isPreviewField.ts`. Duplicated here (not imported) for
+ * the same reason that file exists: keeping `sections/` free of any
+ * dependency on `react/`. Both shapes must stay structurally identical —
+ * if one moves, both move.
+ */
+interface PreviewFieldLike<T> {
+    readonly __agntcmsPreview: true;
+    readonly value: T;
+    readonly origin: PreviewFieldOriginLike;
+}
+interface PreviewFieldOriginLike {
+    readonly pageSlug: string;
+    readonly sectionId: string;
+    readonly fieldPath: string;
+    readonly source: 'draft' | 'published';
+    readonly revision: string;
+    readonly kind?: 'page' | 'global';
+    readonly globalName?: string;
+}
+/**
+ * Recursive item shape for `ListField`. Every field on a list item becomes
+ * its own slot, so a section author who writes `{item.text}` raw inside
+ * `<EditableList renderItem={…}>` gets the SAME compile error as a raw
+ * `{title}` at the section level. This closes the structural blind spot
+ * a heuristic gate could not (see EDITABILITY_DESIGN.md, decision #2).
+ *
+ * `_id` is preserved as a bare string — section components routinely use
+ * it as a React key, and there is no inline-editing surface for it.
+ */
+type SlotItem<S extends SectionSchema> = {
+    readonly _id: string;
+} & {
+    readonly [K in keyof S]: FieldDataType<S[K]>;
+};
+
+/**
+ * Maps a single `FieldDescriptor` to the type a section component receives
+ * on its `props` for that field.
+ *
+ * Built-in field → component-prop type:
+ *   text          → EditableSlot<'text', string>
+ *   richText      → EditableSlot<'richText', string>
+ *   image         → EditableSlot<'image', ImageValue>
+ *   video         → EditableSlot<'video', VideoValue>
+ *   link          → EditableSlot<'link', LinkValue>
+ *   button        → EditableSlot<'button', ButtonValue>
+ *   number        → EditableSlot<'number', number>
+ *   boolean       → EditableSlot<'boolean', boolean>
+ *   select        → EditableSlot<'select', string>
+ *   list          → EditableSlot<'list', ReadonlyArray<SlotItem<S>>>
+ *   reference     → ReferenceValue          (raw — see decision #3)
+ *   formOverrides → FormFieldOverrides      (raw — see decision #4)
+ *
+ * EDITABILITY_DESIGN.md gates this design. The slot wrapping is the
+ * load-bearing change: a slot is not assignable to `React.ReactNode`, so
+ * `<h1>{title}</h1>` produces a TS error and forces the author into
+ * `<EditableText field={title}>`. `ListField` items recurse via
+ * `SlotItem<S>`, so raw rendering inside `renderItem` is also a TS error.
+ *
+ * `ReferenceField` stays raw because references are not inline-editable
+ * in v1 (decision #3): a slot would force a no-op `<EditableReference>`
+ * wrapper without UX value. `FormOverridesField` stays raw because
+ * forms render via a built-in `<Form>` component that reads the schema
+ * itself; there is no author-defined component receiving raw form-field
+ * values, and therefore no JSX surface where a raw render could leak
+ * (decision #4).
+ *
+ * `FieldDataType` and `FieldValueFor` (`domain/schema.ts`) NO LONGER
+ * agree element-by-element: `FieldValueFor` is the bare runtime payload
+ * shape (what storage carries, what `getContent` returns), and stays as
+ * it is; `FieldDataType` is the section-author-facing mapping that
+ * drives `DataOf<S>` and now wraps editable kinds in slots. The runtime
+ * wrapping happens at the SectionRenderer boundary (sub-task 2 wires
+ * `wrapAsSlot`) and is INTENTIONALLY NOT mirrored in `getContent` — see
+ * the comment in `runtime/getContent.ts` for why.
+ *
+ * The mapping is expressed per-descriptor so a future field type is one
+ * line of change instead of a redesign. That is not the same as
+ * "user-extensible field types" — invariant 5 (CLAUDE.md) forbids a
+ * plugin system; this is just the internal seam.
+ */
+type FieldDataType<F extends FieldDescriptor> = F extends TextField ? EditableSlot<'text', string> : F extends RichTextField ? EditableSlot<'richText', string> : F extends ImageField ? EditableSlot<'image', ImageValue> : F extends VideoField ? EditableSlot<'video', VideoValue> : F extends ReferenceField ? ReferenceValue : F extends LinkField ? EditableSlot<'link', LinkValue> : F extends ButtonField ? EditableSlot<'button', ButtonValue> : F extends NumberField ? EditableSlot<'number', number> : F extends BooleanField ? EditableSlot<'boolean', boolean> : F extends SelectField ? EditableSlot<'select', string> : F extends ListField<infer S> ? EditableSlot<'list', ReadonlyArray<SlotItem<S>>> : F extends FormOverridesFieldDescriptor ? FormFieldOverrides : never;
+/**
+ * Derives the SECTION-COMPONENT prop shape from its schema.
+ *
+ * Per `FieldDataType`, every editable field becomes an `EditableSlot<K,V>`
+ * (so `<h1>{title}</h1>` is a TS error); `ReferenceValue` and
+ * `FormFieldOverrides` stay raw. Example:
+ *
+ *   type HeroSchema = { title: TextField; image: ImageField; ref: ReferenceField }
+ *   DataOf<HeroSchema> ≡ {
+ *     readonly title: EditableSlot<'text', string>
+ *     readonly image: EditableSlot<'image', ImageValue>
+ *     readonly ref:   ReferenceValue
+ *   }
+ *
+ * NOTE: this is the COMPONENT-SIDE shape. The bare runtime payload (what
+ * `getContent` returns and what storage carries) is described by
+ * `FieldValueFor<F>` in `domain/schema.ts` — that mapping has not changed
+ * and must not change (see the slot-non-wrapping comment in
+ * `runtime/getContent.ts`).
+ */
+type DataOf<S extends SectionSchema> = {
+    readonly [K in keyof S]: FieldDataType<S[K]>;
+};
+/**
+ * The contract a section's React component must satisfy: a function taking
+ * exactly the derived props for its schema. The return type is intentionally
+ * `unknown` — `sections/` may not name React types (see file header). The
+ * downstream `react/` module is where the stricter `ReactElement` typing
+ * lives; here we only care that the props line up with the schema.
+ */
+type SectionComponent<S extends SectionSchema> = (props: DataOf<S>) => unknown;
+/**
+ * Registration record produced by `defineSection`. Consumers (the registry
+ * built by `defineConfig` in T-019, `SectionRenderer` in T-016) look up
+ * definitions by `name` and use `component` to render.
+ *
+ * Both generic parameters are required (no defaults). A heterogeneous
+ * registry — the list the runtime actually stores — is typed as
+ * `readonly AnySectionDefinition[]`, NOT `readonly SectionDefinition[]`.
+ *
+ * Why this split exists
+ * ---------------------
+ * `SectionComponent<S>` is a function whose parameter is contravariant. If
+ * we widened `SectionDefinition` to its default parameters and asked a
+ * concrete `SectionDefinition<{title: TextField}, (p: {title: string}) => unknown>`
+ * to be assignable to it, the function-parameter contravariance would
+ * refuse: the "widened" parameter type `DataOf<SectionSchema>` is stricter
+ * (more required keys, from TypeScript's perspective) than any concrete
+ * `DataOf<S>`. The erasure-safe form lives in `AnySectionDefinition`, which
+ * stores the component with `unknown` props. Every precise definition is
+ * assignable to `AnySectionDefinition`.
+ */
+interface SectionDefinition<S extends SectionSchema, C extends SectionComponent<S>> {
+    /** Stable type discriminator used to tag `Section.type` and in lookups. */
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    /** Field-descriptor schema. */
+    readonly schema: S;
+    /** React component reference. See file header on why not a thunk. */
+    readonly component: C;
+    /** Pre-computed placeholder values for each field, used when inserting a
+     *  new section in preview mode. Computed from field descriptors' `default`
+     *  property (when present) or from the built-in per-kind fallback.
+     *
+     *  Typed as `Record<string, unknown>` so the registry type stays stable
+     *  even if a future built-in field type introduces a non-string runtime
+     *  value. In v1 every value here is a `string`. The registry itself
+     *  never interprets these — consumers that read a specific field narrow
+     *  at the call site. */
+    readonly defaults: Record<string, unknown>;
+    /** Optional list of layout names supported by this section. When present
+     *  with length >= 2, the preview-mode section picker renders a "Layout"
+     *  tab so authors can switch the layout without editing JSON. The section
+     *  component reads the active layout from its `layout` prop; the picker
+     *  writes that value via the existing per-field save round-trip.
+     *
+     *  Layouts are a SECTION-level concern, not a field descriptor, because
+     *  they gate structure inside a single component rather than introducing
+     *  a new field type. See ARCHITECTURE.md §4. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * The erased/heterogeneous form used by the registry and by
+ * `defineConfig({ sections: [...] })`. Precise definitions produced by
+ * `defineSection` are assignable to this type because:
+ *   - `schema` widens to `SectionSchema` (covariant read),
+ *   - `component` widens to a function whose parameter type is `never`.
+ *     Under parameter contravariance, any concrete `(props: X) => unknown`
+ *     is assignable to `(props: never) => unknown` (for any `X`, `never` is
+ *     a subtype of `X`). Return widens to `unknown`.
+ *
+ * Callers that only need `name` / `schema` metadata treat a list of
+ * definitions as `readonly AnySectionDefinition[]`. Rendering code — which
+ * does need to INVOKE the component — recovers strong typing at the call
+ * site by looking up by name and casting to its section-specific
+ * `SectionComponent<S>` before calling. The registry itself never invokes
+ * components.
+ */
+interface AnySectionDefinition {
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    readonly schema: SectionSchema;
+    readonly component: (props: never) => unknown;
+    /** Pre-computed placeholder values — see `SectionDefinition.defaults`. */
+    readonly defaults: Record<string, unknown>;
+    /** Optional layout names — see `SectionDefinition.layouts`. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * Input shape for `defineSection`. Split out so the factory can use a single
+ * generic parameter set for both input and output.
+ */
+interface DefineSectionInput<S extends SectionSchema, C extends SectionComponent<S>> {
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    readonly schema: S;
+    readonly component: C;
+    /** Optional layout names — see `SectionDefinition.layouts`. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * Type-safe factory for a `SectionDefinition`.
+ *
+ * The compile-time win is the constraint `C extends SectionComponent<S>`: if
+ * the component's props do not match the derived `DataOf<S>`, TypeScript
+ * rejects the call. The factory itself is purely about binding — it does no
+ * validation at runtime, because in v1 there is nothing to validate (the
+ * schema is plain descriptor metadata, not a parser).
+ *
+ * Object and schema are not deep-frozen: doing so would add a runtime cost on
+ * every module load without preventing anything the type system does not
+ * already prevent in strict mode. `as const` at the author's call site is
+ * enough for literal inference.
+ */
+declare function defineSection<S extends SectionSchema, C extends SectionComponent<S>>(input: DefineSectionInput<S, C>): SectionDefinition<S, C>;
+
+export { type AnySectionDefinition as A, type DataOf as D, type EditableSlot as E, type FieldDataType as F, type SectionComponent as S, type DefineSectionInput as a, type SectionDefinition as b, type SlotItem as c, defineSection as d };

package/dist/defineSection-Kr0pWqMY.d.ts

@@ -0,0 +1,243 @@
+import { S as SectionSchema, c as FieldDescriptor, T as TextField, R as RichTextField, I as ImageField, d as ImageValue, V as VideoField, e as VideoValue, f as ReferenceField, g as ReferenceValue, L as LinkField, h as LinkValue, B as ButtonField, i as ButtonValue, N as NumberField, j as BooleanField, k as SelectField, l as ListField, m as FormOverridesFieldDescriptor, n as FormFieldOverrides } from './form-BqY0H1V5.js';
+
+declare const __slot: unique symbol;
+/**
+ * Opaque editable slot. The runtime hands `<EditableText>` /
+ * `<EditableImage>` / etc. exactly this shape; the brand `[__slot]: K` is
+ * phantom (never set at runtime) and exists only to stop the slot from
+ * being assigned to `React.ReactNode` at JSX render sites. The slot kind
+ * `K` lets the matching editable component refuse a mismatched widget at
+ * compile time (`<EditableText field={imageSlot}>` is a TS error).
+ *
+ * The `value` is `V | PreviewFieldLike<V>` because the runtime wraps with
+ * `PreviewField` only in preview mode; published mode hands the bare
+ * value. The `read()` helper unwraps both branches.
+ */
+interface EditableSlot<K extends string, V> {
+    readonly [__slot]: K;
+    readonly value: V | PreviewFieldLike<V>;
+}
+/**
+ * Local structural replica of `PreviewFieldLike<T>` from
+ * `react/editable/isPreviewField.ts`. Duplicated here (not imported) for
+ * the same reason that file exists: keeping `sections/` free of any
+ * dependency on `react/`. Both shapes must stay structurally identical —
+ * if one moves, both move.
+ */
+interface PreviewFieldLike<T> {
+    readonly __agntcmsPreview: true;
+    readonly value: T;
+    readonly origin: PreviewFieldOriginLike;
+}
+interface PreviewFieldOriginLike {
+    readonly pageSlug: string;
+    readonly sectionId: string;
+    readonly fieldPath: string;
+    readonly source: 'draft' | 'published';
+    readonly revision: string;
+    readonly kind?: 'page' | 'global';
+    readonly globalName?: string;
+}
+/**
+ * Recursive item shape for `ListField`. Every field on a list item becomes
+ * its own slot, so a section author who writes `{item.text}` raw inside
+ * `<EditableList renderItem={…}>` gets the SAME compile error as a raw
+ * `{title}` at the section level. This closes the structural blind spot
+ * a heuristic gate could not (see EDITABILITY_DESIGN.md, decision #2).
+ *
+ * `_id` is preserved as a bare string — section components routinely use
+ * it as a React key, and there is no inline-editing surface for it.
+ */
+type SlotItem<S extends SectionSchema> = {
+    readonly _id: string;
+} & {
+    readonly [K in keyof S]: FieldDataType<S[K]>;
+};
+
+/**
+ * Maps a single `FieldDescriptor` to the type a section component receives
+ * on its `props` for that field.
+ *
+ * Built-in field → component-prop type:
+ *   text          → EditableSlot<'text', string>
+ *   richText      → EditableSlot<'richText', string>
+ *   image         → EditableSlot<'image', ImageValue>
+ *   video         → EditableSlot<'video', VideoValue>
+ *   link          → EditableSlot<'link', LinkValue>
+ *   button        → EditableSlot<'button', ButtonValue>
+ *   number        → EditableSlot<'number', number>
+ *   boolean       → EditableSlot<'boolean', boolean>
+ *   select        → EditableSlot<'select', string>
+ *   list          → EditableSlot<'list', ReadonlyArray<SlotItem<S>>>
+ *   reference     → ReferenceValue          (raw — see decision #3)
+ *   formOverrides → FormFieldOverrides      (raw — see decision #4)
+ *
+ * EDITABILITY_DESIGN.md gates this design. The slot wrapping is the
+ * load-bearing change: a slot is not assignable to `React.ReactNode`, so
+ * `<h1>{title}</h1>` produces a TS error and forces the author into
+ * `<EditableText field={title}>`. `ListField` items recurse via
+ * `SlotItem<S>`, so raw rendering inside `renderItem` is also a TS error.
+ *
+ * `ReferenceField` stays raw because references are not inline-editable
+ * in v1 (decision #3): a slot would force a no-op `<EditableReference>`
+ * wrapper without UX value. `FormOverridesField` stays raw because
+ * forms render via a built-in `<Form>` component that reads the schema
+ * itself; there is no author-defined component receiving raw form-field
+ * values, and therefore no JSX surface where a raw render could leak
+ * (decision #4).
+ *
+ * `FieldDataType` and `FieldValueFor` (`domain/schema.ts`) NO LONGER
+ * agree element-by-element: `FieldValueFor` is the bare runtime payload
+ * shape (what storage carries, what `getContent` returns), and stays as
+ * it is; `FieldDataType` is the section-author-facing mapping that
+ * drives `DataOf<S>` and now wraps editable kinds in slots. The runtime
+ * wrapping happens at the SectionRenderer boundary (sub-task 2 wires
+ * `wrapAsSlot`) and is INTENTIONALLY NOT mirrored in `getContent` — see
+ * the comment in `runtime/getContent.ts` for why.
+ *
+ * The mapping is expressed per-descriptor so a future field type is one
+ * line of change instead of a redesign. That is not the same as
+ * "user-extensible field types" — invariant 5 (CLAUDE.md) forbids a
+ * plugin system; this is just the internal seam.
+ */
+type FieldDataType<F extends FieldDescriptor> = F extends TextField ? EditableSlot<'text', string> : F extends RichTextField ? EditableSlot<'richText', string> : F extends ImageField ? EditableSlot<'image', ImageValue> : F extends VideoField ? EditableSlot<'video', VideoValue> : F extends ReferenceField ? ReferenceValue : F extends LinkField ? EditableSlot<'link', LinkValue> : F extends ButtonField ? EditableSlot<'button', ButtonValue> : F extends NumberField ? EditableSlot<'number', number> : F extends BooleanField ? EditableSlot<'boolean', boolean> : F extends SelectField ? EditableSlot<'select', string> : F extends ListField<infer S> ? EditableSlot<'list', ReadonlyArray<SlotItem<S>>> : F extends FormOverridesFieldDescriptor ? FormFieldOverrides : never;
+/**
+ * Derives the SECTION-COMPONENT prop shape from its schema.
+ *
+ * Per `FieldDataType`, every editable field becomes an `EditableSlot<K,V>`
+ * (so `<h1>{title}</h1>` is a TS error); `ReferenceValue` and
+ * `FormFieldOverrides` stay raw. Example:
+ *
+ *   type HeroSchema = { title: TextField; image: ImageField; ref: ReferenceField }
+ *   DataOf<HeroSchema> ≡ {
+ *     readonly title: EditableSlot<'text', string>
+ *     readonly image: EditableSlot<'image', ImageValue>
+ *     readonly ref:   ReferenceValue
+ *   }
+ *
+ * NOTE: this is the COMPONENT-SIDE shape. The bare runtime payload (what
+ * `getContent` returns and what storage carries) is described by
+ * `FieldValueFor<F>` in `domain/schema.ts` — that mapping has not changed
+ * and must not change (see the slot-non-wrapping comment in
+ * `runtime/getContent.ts`).
+ */
+type DataOf<S extends SectionSchema> = {
+    readonly [K in keyof S]: FieldDataType<S[K]>;
+};
+/**
+ * The contract a section's React component must satisfy: a function taking
+ * exactly the derived props for its schema. The return type is intentionally
+ * `unknown` — `sections/` may not name React types (see file header). The
+ * downstream `react/` module is where the stricter `ReactElement` typing
+ * lives; here we only care that the props line up with the schema.
+ */
+type SectionComponent<S extends SectionSchema> = (props: DataOf<S>) => unknown;
+/**
+ * Registration record produced by `defineSection`. Consumers (the registry
+ * built by `defineConfig` in T-019, `SectionRenderer` in T-016) look up
+ * definitions by `name` and use `component` to render.
+ *
+ * Both generic parameters are required (no defaults). A heterogeneous
+ * registry — the list the runtime actually stores — is typed as
+ * `readonly AnySectionDefinition[]`, NOT `readonly SectionDefinition[]`.
+ *
+ * Why this split exists
+ * ---------------------
+ * `SectionComponent<S>` is a function whose parameter is contravariant. If
+ * we widened `SectionDefinition` to its default parameters and asked a
+ * concrete `SectionDefinition<{title: TextField}, (p: {title: string}) => unknown>`
+ * to be assignable to it, the function-parameter contravariance would
+ * refuse: the "widened" parameter type `DataOf<SectionSchema>` is stricter
+ * (more required keys, from TypeScript's perspective) than any concrete
+ * `DataOf<S>`. The erasure-safe form lives in `AnySectionDefinition`, which
+ * stores the component with `unknown` props. Every precise definition is
+ * assignable to `AnySectionDefinition`.
+ */
+interface SectionDefinition<S extends SectionSchema, C extends SectionComponent<S>> {
+    /** Stable type discriminator used to tag `Section.type` and in lookups. */
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    /** Field-descriptor schema. */
+    readonly schema: S;
+    /** React component reference. See file header on why not a thunk. */
+    readonly component: C;
+    /** Pre-computed placeholder values for each field, used when inserting a
+     *  new section in preview mode. Computed from field descriptors' `default`
+     *  property (when present) or from the built-in per-kind fallback.
+     *
+     *  Typed as `Record<string, unknown>` so the registry type stays stable
+     *  even if a future built-in field type introduces a non-string runtime
+     *  value. In v1 every value here is a `string`. The registry itself
+     *  never interprets these — consumers that read a specific field narrow
+     *  at the call site. */
+    readonly defaults: Record<string, unknown>;
+    /** Optional list of layout names supported by this section. When present
+     *  with length >= 2, the preview-mode section picker renders a "Layout"
+     *  tab so authors can switch the layout without editing JSON. The section
+     *  component reads the active layout from its `layout` prop; the picker
+     *  writes that value via the existing per-field save round-trip.
+     *
+     *  Layouts are a SECTION-level concern, not a field descriptor, because
+     *  they gate structure inside a single component rather than introducing
+     *  a new field type. See ARCHITECTURE.md §4. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * The erased/heterogeneous form used by the registry and by
+ * `defineConfig({ sections: [...] })`. Precise definitions produced by
+ * `defineSection` are assignable to this type because:
+ *   - `schema` widens to `SectionSchema` (covariant read),
+ *   - `component` widens to a function whose parameter type is `never`.
+ *     Under parameter contravariance, any concrete `(props: X) => unknown`
+ *     is assignable to `(props: never) => unknown` (for any `X`, `never` is
+ *     a subtype of `X`). Return widens to `unknown`.
+ *
+ * Callers that only need `name` / `schema` metadata treat a list of
+ * definitions as `readonly AnySectionDefinition[]`. Rendering code — which
+ * does need to INVOKE the component — recovers strong typing at the call
+ * site by looking up by name and casting to its section-specific
+ * `SectionComponent<S>` before calling. The registry itself never invokes
+ * components.
+ */
+interface AnySectionDefinition {
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    readonly schema: SectionSchema;
+    readonly component: (props: never) => unknown;
+    /** Pre-computed placeholder values — see `SectionDefinition.defaults`. */
+    readonly defaults: Record<string, unknown>;
+    /** Optional layout names — see `SectionDefinition.layouts`. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * Input shape for `defineSection`. Split out so the factory can use a single
+ * generic parameter set for both input and output.
+ */
+interface DefineSectionInput<S extends SectionSchema, C extends SectionComponent<S>> {
+    readonly name: string;
+    /** Optional grouping label for the section picker modal. */
+    readonly category?: string;
+    readonly schema: S;
+    readonly component: C;
+    /** Optional layout names — see `SectionDefinition.layouts`. */
+    readonly layouts?: readonly string[];
+}
+/**
+ * Type-safe factory for a `SectionDefinition`.
+ *
+ * The compile-time win is the constraint `C extends SectionComponent<S>`: if
+ * the component's props do not match the derived `DataOf<S>`, TypeScript
+ * rejects the call. The factory itself is purely about binding — it does no
+ * validation at runtime, because in v1 there is nothing to validate (the
+ * schema is plain descriptor metadata, not a parser).
+ *
+ * Object and schema are not deep-frozen: doing so would add a runtime cost on
+ * every module load without preventing anything the type system does not
+ * already prevent in strict mode. `as const` at the author's call site is
+ * enough for literal inference.
+ */
+declare function defineSection<S extends SectionSchema, C extends SectionComponent<S>>(input: DefineSectionInput<S, C>): SectionDefinition<S, C>;
+
+export { type AnySectionDefinition as A, type DataOf as D, type EditableSlot as E, type FieldDataType as F, type SectionComponent as S, type DefineSectionInput as a, type SectionDefinition as b, type SlotItem as c, defineSection as d };