@agntcms/next 0.2.0

package/dist/client.d.cts

@@ -0,0 +1,806 @@
+import { P as Page, D as Section, S as SectionSchema, a as FormSchema, b as FormDefinition, x as FieldValueFor, n as FormFieldOverrides, A as AnyFormDefinition, d as ImageValue, e as VideoValue, h as LinkValue, i as ButtonValue, E as SelectOption, z as ListItem } from './form-BqY0H1V5.cjs';
+export { q as FormFieldOverride } from './form-BqY0H1V5.cjs';
+import { A as AnySectionDefinition, E as EditableSlot, c as SlotItem } from './defineSection-9qQ5ulAH.cjs';
+import { ReactNode, ReactElement } from 'react';
+
+interface PageRendererProps {
+    /** The page data from getContent. */
+    readonly page: Page;
+    /** The registry of section definitions. */
+    readonly definitions: readonly AnySectionDefinition[];
+}
+/**
+ * Renders all sections of a page in order. Wraps them in a `<div>` tagged
+ * with `data-agntcms-page` for debugging and testing (not for styling).
+ */
+declare function PageRenderer(props: PageRendererProps): React.ReactElement;
+
+interface SectionRendererProps {
+    /** The section data from the page's sections array. */
+    readonly section: Section;
+    /** The registry of section definitions to look up the component. */
+    readonly definitions: readonly AnySectionDefinition[];
+}
+/**
+ * Looks up `section.type` in the `definitions` array and renders the
+ * matching component with `section.data` as props.
+ *
+ * If no matching definition is found: in development, renders a visible
+ * red-bordered error box; in production, returns `null` silently.
+ */
+declare function SectionRenderer(props: SectionRendererProps): React.ReactElement | null;
+
+/** Preview or published — matches the runtime concept but defined locally for the client bundle. */
+type PreviewMode = 'preview' | 'published';
+interface PreviewContextValue {
+    readonly mode: PreviewMode;
+}
+interface PreviewProviderProps {
+    readonly mode: PreviewMode;
+    readonly children: ReactNode;
+}
+/**
+ * Wraps the page tree to broadcast the current preview mode.
+ *
+ * In preview mode, an <AgentTaskProvider> is automatically mounted
+ * between the PreviewContext and the children so every descendant shares
+ * one task coordinator. In published mode, no AgentTaskProvider is
+ * mounted — there is no preview UI to drive.
+ */
+declare function PreviewProvider({ mode, children }: PreviewProviderProps): React.ReactElement;
+/** Returns the current preview mode. Defaults to 'published' outside a PreviewProvider. */
+declare function usePreviewMode(): PreviewMode;
+
+/**
+ * Minimal shape of a section definition needed by the picker.
+ * Kept deliberately narrow so the modal doesn't depend on the full
+ * domain `SectionDefinition` type at runtime — only at the call site.
+ *
+ * `schema` and `label` are optional because the picker itself does
+ * not need them. They are surfaced here so that other preview-time
+ * consumers (notably `<SectionSettingsModal>`) can find a section's
+ * field-descriptor map and human label without a parallel definitions
+ * channel. At runtime every real `AnySectionDefinition` carries both,
+ * so the optional declaration is a type-system relaxation rather than
+ * a runtime contract change.
+ */
+interface DefinitionLike {
+    readonly name: string;
+    readonly category?: string;
+    readonly component: (props: never) => unknown;
+    /**
+     * Pre-computed defaults. Values are `unknown` because each field
+     * kind produces its own default shape — v1 built-ins all resolve
+     * to strings (text, image-filename, reference id), but keeping the
+     * channel lossless avoids breaking downstream if a future built-in
+     * introduces a non-string value. Preview cards cast the definition's
+     * component to the right shape at render time.
+     */
+    readonly defaults?: Record<string, unknown>;
+    /**
+     * Field-descriptor schema. Optional in the type because tests and
+     * isolated callers may build minimal stubs; in practice every real
+     * definition supplies it.
+     */
+    readonly schema?: SectionSchema;
+    /** Optional human-friendly label. Falls back to `name`. */
+    readonly label?: string;
+    /**
+     * Optional layout names declared on the section definition. When a
+     * section with layouts is being edited (caller passes `currentSection`
+     * + `onSelectLayout`), the modal renders a "Layout" tab with a
+     * preview card per layout. Undefined means no Layout tab.
+     */
+    readonly layouts?: readonly string[];
+}
+/**
+ * A global content block entry as returned by /api/agntcms/global/list.
+ * Kept minimal — we only need name and type for display and selection.
+ */
+interface GlobalEntry {
+    readonly name: string;
+    readonly type: string;
+}
+interface SectionPickerModalProps {
+    /** Whether the modal is open. */
+    readonly open: boolean;
+    /** Called when the modal should close. */
+    readonly onClose: () => void;
+    /** Called when a section type is selected. */
+    readonly onSelect: (typeName: string) => void;
+    /** Available section definitions to display. */
+    readonly definitions: readonly DefinitionLike[];
+    /** Title shown in the modal header. */
+    readonly title: string;
+    /** Called when a global is selected instead of a section type.
+     *  When omitted, the globals group is not shown (backwards compatible). */
+    readonly onSelectGlobal?: (globalName: string) => void;
+    /**
+     * The section currently being edited. When provided together with
+     * `onSelectLayout` AND the matching definition declares `layouts` with
+     * length >= 2, the modal exposes a "Layout" tab next to "Replace".
+     *
+     * `data` is a plain record (not a PreviewField-wrapped one). Callers in
+     * preview mode must strip wrappers before passing — the Layout tab
+     * renders `<Component {...data} layout={v} />` and React would reject
+     * PreviewField objects as children. See SectionEditControls'
+     * `stripSectionData` for the stripper.
+     */
+    readonly currentSection?: {
+        readonly id: string;
+        readonly type: string;
+        readonly data: Record<string, unknown>;
+    };
+    /**
+     * Called when the user picks a layout from the Layout tab. Omitting
+     * this prop hides the Layout tab even if `currentSection` is present —
+     * the callback is the only way a click can actually change anything.
+     */
+    readonly onSelectLayout?: (layoutName: string) => void;
+}
+declare function SectionPickerModal(props: SectionPickerModalProps): ReactElement | null;
+
+interface PreviewToolbarProps {
+    /**
+     * Optional section definitions. When provided, the Admin modal's
+     * Edit-global flow renders the real section component with inline
+     * editable fields instead of a generic form. Forwarded verbatim to
+     * AdminModal.
+     */
+    readonly definitions?: readonly DefinitionLike[];
+}
+/**
+ * Fixed-position bar at the bottom of the viewport, visible only in preview mode.
+ * Layout: "Preview Mode" | Publish | M | Agent | Exit Preview.
+ */
+declare function PreviewToolbar(props?: PreviewToolbarProps): React.ReactElement | null;
+
+interface SectionEditControlsProps {
+    /** The page whose sections are being edited. */
+    readonly page: Page;
+    /** Section definitions — used both to render sections and to populate the
+     *  "add section" picker. Replaces the old `renderSection` callback + separate
+     *  `sectionTypes` list: passing definitions is RSC-serializable (component
+     *  refs are serializable as module references), while a function callback is
+     *  not. */
+    readonly definitions: readonly DefinitionLike[];
+    /** Called after a mutation succeeds. Typically triggers a router refresh. */
+    readonly onMutated?: () => void;
+}
+/**
+ * Wraps the section list with add/remove controls visible only in preview
+ * mode. In published mode, renders the plain section list with no overhead.
+ */
+declare function SectionEditControls(props: SectionEditControlsProps): React.ReactElement;
+
+/**
+ * Derived payload shape for a `FormDefinition<S>`. Maps every field to its
+ * runtime value type. We re-derive locally rather than re-using
+ * `domain/schema.ts:DataOf<S>` because forms don't use the section data
+ * record shape (`hasUniqueSectionIds`, etc.) — they use a flat record.
+ */
+type PayloadOf<S extends FormSchema> = {
+    readonly [K in keyof S]: FieldValueFor<S[K]>;
+};
+interface FormProps<S extends FormSchema> {
+    /** The form definition produced by `defineForm`. Drives schema-based rendering. */
+    readonly definition: FormDefinition<S>;
+    /**
+     * Content rendered in place of the form on a successful submit. Default:
+     * a plain "Thanks — we'll be in touch." message. Set to `null` to render
+     * nothing on success.
+     */
+    readonly successMessage?: ReactNode;
+    /** Submit endpoint. Defaults to `/api/agntcms/forms/submit`. */
+    readonly endpoint?: string;
+    /** Called with the submitted payload after a successful (stored) submit. */
+    readonly onSubmitSuccess?: (payload: PayloadOf<S>) => void;
+    /** Called instead of POSTing when the surrounding `<PreviewProvider mode="preview">` is active. */
+    readonly onPreviewSubmit?: (payload: PayloadOf<S>) => void;
+    /** Class applied to the root `<form>` element. */
+    readonly className?: string;
+    /** Submit button label. Defaults to "Submit". */
+    readonly submitLabel?: string;
+    /**
+     * Per-section-instance display chrome and instance defaults for the form's
+     * fields. See `FormFieldOverrides` (domain/formOverrides.ts) and
+     * ARCHITECTURE.md §6.5. Field NAMES, KINDS, and VALIDATION are NOT
+     * overridable — only `label`, `placeholder`, `helpText`, `hidden`,
+     * `order`, and `default`.
+     *
+     * A hidden field with a `default` is included in the submitted payload as
+     * if the user had typed it. A hidden field WITHOUT a default is omitted
+     * entirely — the server-side schema validation will reject if that field
+     * is required, by design (callers must provide a default whenever they
+     * hide a required field).
+     */
+    readonly overrides?: FormFieldOverrides;
+}
+/**
+ * End-user form. Renders one input per declared field, validates server-side
+ * via the submit handler, and surfaces error/success states.
+ *
+ * In preview mode (inside a `<PreviewProvider mode="preview">`) the submit
+ * is intercepted: no network call is made, an inline notice is shown, and
+ * the optional `onPreviewSubmit` callback receives the typed payload.
+ */
+declare function Form<S extends FormSchema>(props: FormProps<S>): ReactElement;
+
+/**
+ * The registry value plumbed through context. An empty map is the
+ * default — components that look up a form by name and miss render a
+ * graceful "form not found" message instead of crashing.
+ */
+type FormsByName = ReadonlyMap<string, AnyFormDefinition>;
+interface FormsRegistryProviderProps {
+    /**
+     * Either a `ReadonlyMap<string, AnyFormDefinition>` (used directly)
+     * or a list of definitions (the provider builds the map). The list
+     * shape is convenient for callers who already hold the array from
+     * `defineConfig({ forms })`.
+     */
+    readonly forms?: FormsByName | ReadonlyArray<AnyFormDefinition>;
+    readonly children: ReactNode;
+}
+/**
+ * Provider that exposes the registered forms to descendant preview
+ * widgets via context. When `forms` is omitted, descendants see the
+ * default (empty map) — same outcome as no provider at all.
+ *
+ * Usage:
+ *   <FormsRegistryProvider forms={[Contact, Newsletter]}>
+ *     <SectionEditControls ... />
+ *   </FormsRegistryProvider>
+ */
+declare function FormsRegistryProvider(props: FormsRegistryProviderProps): React.ReactElement;
+/**
+ * Returns the current forms registry. Defaults to an empty map outside
+ * a `FormsRegistryProvider`. Consumers MUST handle the empty case
+ * gracefully — a missing form name renders a helpful inline message,
+ * not a crash.
+ */
+declare function useFormsRegistry(): FormsByName;
+
+interface SectionReplaceOverlayProps {
+    /** The section being replaced (id + current type). */
+    readonly sectionId: string;
+    readonly currentType: string;
+    readonly pageSlug: string;
+    /** Section definitions with live preview components. */
+    readonly definitions: readonly DefinitionLike[];
+    /** Whether we're in preview mode (only show in preview). */
+    readonly isPreview: boolean;
+    /** Callback after the replacement task completes. */
+    readonly onReplaced?: () => void;
+    /** Called when a global is selected as the replacement.
+     *  When provided, the picker shows globals alongside section types. */
+    readonly onSelectGlobal?: (globalName: string) => void;
+    /**
+     * The section currently being edited. Forwarded to `SectionPickerModal`
+     * to enable the "Layout" tab for sections with declared layouts. Data
+     * must be PreviewField-stripped by the caller (SectionEditControls does
+     * this via its `stripSectionData` helper). When omitted, the Layout tab
+     * is hidden regardless of `onSelectLayout`.
+     */
+    readonly currentSection?: {
+        readonly id: string;
+        readonly type: string;
+        readonly data: Record<string, unknown>;
+    };
+    /** Called when a layout is picked from the Layout tab. */
+    readonly onSelectLayout?: (layoutName: string) => void;
+}
+declare function SectionReplaceOverlay(props: SectionReplaceOverlayProps): React.ReactElement | null;
+
+interface SectionWrapperProps {
+    readonly sectionId: string;
+    readonly sectionType: string;
+    readonly pageSlug: string;
+    readonly definitions: readonly DefinitionLike[];
+    readonly isPreview: boolean;
+    readonly onReplaced?: () => void;
+    /** Forwarded to the picker to allow replacing a section with a global. */
+    readonly onSelectGlobal?: (globalName: string) => void;
+    /**
+     * The section currently being edited. Forwarded to the picker modal so
+     * sections declaring `layouts` can expose a "Layout" tab. `data` must
+     * be PreviewField-stripped by the caller — the picker renders the section
+     * component with this data and React rejects wrapper objects as props.
+     */
+    readonly currentSection?: {
+        readonly id: string;
+        readonly type: string;
+        readonly data: Record<string, unknown>;
+    };
+    /** Forwarded to the picker; invoked when a layout is chosen. */
+    readonly onSelectLayout?: (layoutName: string) => void;
+    /**
+     * Optional slot rendered inside the hover-controls area next to the ⇄
+     * replace button. The caller composes any React node (typically an
+     * <AgentActionButton />) and passes it in. SectionWrapper stays
+     * agnostic — it does NOT import from react/agent/ (invariant 2 keeps
+     * this module a leaf).
+     */
+    readonly agentAction?: React.ReactNode;
+    /**
+     * Optional slot for the delete (×) button. Rendered INSIDE the
+     * .agntcms-section-wrap div so the single group-hover rule in
+     * HOVER_STYLE reveals it together with ⇄ and ✨. The caller owns the
+     * button's appearance and behavior (confirm, fetch, etc.); SectionWrapper
+     * just places it in the hover scope.
+     */
+    readonly deleteAction?: React.ReactNode;
+    /**
+     * Optional slot for the edit (✎) button. Same composition pattern
+     * as `agentAction` and `deleteAction`: rendered inside the hover scope
+     * so the same group-hover rule fades it in. The caller positions and
+     * styles the button; SectionWrapper stays agnostic of the modal it
+     * opens (which would otherwise pull preview-only deps into this leaf).
+     */
+    readonly settingsAction?: React.ReactNode;
+    readonly children: React.ReactNode;
+}
+/**
+ * Wraps a rendered section with a hover overlay showing the replace
+ * button. In published mode, renders children with no wrapper.
+ */
+declare function SectionWrapper(props: SectionWrapperProps): React.ReactElement;
+
+type TaskStatus = 'idle' | 'dispatching' | 'in_progress' | 'completed' | 'failed';
+interface TaskState {
+    readonly status: TaskStatus;
+    readonly messages: readonly string[];
+    readonly result?: string;
+    readonly error?: string;
+}
+/**
+ * Manages the full lifecycle of a single MCP task:
+ * idle -> dispatching -> (in_progress | completed | failed).
+ *
+ * `dispatch` POSTs to the MCP handler, then subscribes to SSE for progress.
+ * `reset` returns to idle so the hook can be reused for the next task.
+ */
+declare function useTaskEvents(): {
+    state: TaskState;
+    dispatch: (type: string, payload: Record<string, unknown>) => Promise<void>;
+    reset: () => void;
+};
+
+interface AdminModalProps {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    /**
+     * Optional registered section definitions. When provided and a global's
+     * `type` matches a definition, the Edit-global modal renders the real
+     * section component with inline `EditableText` / `EditableImage`
+     * affordances — same experience as editing a page section. When absent
+     * (or no matching definition), it falls back to a generic field form.
+     */
+    readonly definitions?: readonly DefinitionLike[];
+}
+declare function AdminModal(props: AdminModalProps): ReactElement | null;
+
+/**
+ * The origin metadata carried by a preview-mode field. Mirrors
+ * `PreviewFieldOrigin` from runtime types but defined locally to avoid
+ * importing server code into the client bundle.
+ *
+ * `kind` and `globalName` were added in v0.2 to support `<GlobalSlot>`:
+ * fields that come from a global carry `kind: 'global'` and
+ * `globalName: <name>`, which lets the save dispatcher route to
+ * `/api/agntcms/global/save` instead of the page draft endpoint.
+ * The discriminator is OPTIONAL for backward compatibility — when
+ * absent, the field is treated as a page-origin field.
+ */
+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;
+}
+/**
+ * Structural replica of `PreviewField<T>` for use in client components.
+ * See file header for why this is duplicated rather than imported.
+ */
+interface PreviewFieldLike<T = unknown> {
+    readonly __agntcmsPreview: true;
+    readonly value: T;
+    readonly origin: PreviewFieldOriginLike;
+}
+/**
+ * Runtime check: is the given value a preview-mode wrapped field?
+ *
+ * Uses the `__agntcmsPreview` brand property that the runtime sets on
+ * every `PreviewField<T>` instance. This is a cheap property-existence
+ * check — no deep validation of the origin shape.
+ */
+declare function isPreviewField<T>(field: unknown): field is PreviewFieldLike<T>;
+
+/**
+ * Collapse an `EditableSlot<K, V>` to its bare value `V`.
+ *
+ * In published mode, `slot.value` is already `V`, so the helper is a
+ * straight read. In preview mode, `slot.value` is a `PreviewFieldLike<V>`
+ * carrying origin metadata; the helper unwraps to `.value`.
+ *
+ * The slot kind `K` is irrelevant to the unwrap and is therefore widened
+ * via `string` in the parameter type — section authors call `read(linkSlot)`
+ * without knowing or caring which slot kind they hold.
+ */
+declare function read<V>(slot: EditableSlot<string, V>): V;
+/**
+ * Is this slot currently rendering in preview mode?
+ *
+ * In preview mode, `slot.value` is a `PreviewFieldLike<V>` carrying origin
+ * metadata. In published mode, it is the bare `V`. This helper is the
+ * canonical signal an author should use to keep an OPTIONAL link/image/etc.
+ * field VISIBLE and CLICKABLE in preview when it would otherwise be hidden
+ * by an empty-value short-circuit.
+ *
+ * The canonical idiom for an optional CTA:
+ *
+ *     const cta = read(rawCta)
+ *     const showCta = Boolean(hrefOf(cta)) || isSlotInPreview(rawCta)
+ *     {showCta && <a ...><EditableLink field={rawCta} ... /></a>}
+ *
+ * Without the `|| isSlotInPreview(...)` clause, an unconfigured optional CTA
+ * disappears in preview mode and the author has no click target to open the
+ * link picker. With it, the `<a>` (and the `<EditableLink>` inside) stays
+ * mounted in preview, but the published site still hides it.
+ *
+ * The slot kind `K` is irrelevant to the check (the preview wrapper shape is
+ * the same for every kind), so it is widened via `string` in the parameter
+ * type — authors call `isSlotInPreview(linkSlot)` without naming the kind.
+ */
+declare function isSlotInPreview<V>(slot: EditableSlot<string, V>): boolean;
+
+interface EditableTextProps {
+    /**
+     * The slot for this text field. SectionRenderer hands every editable
+     * field through `wrapAsSlot` (EDITABILITY_DESIGN.md sub-task 2), so the
+     * component receives an `EditableSlot<'text', string>` whose `.value`
+     * is either a bare string (published) or `PreviewFieldLike<string>`
+     * (preview). The slot kind `'text'` makes a mismatched widget
+     * (`<EditableImage field={textSlot}>`) a TS error.
+     */
+    readonly field: EditableSlot<'text', string>;
+    /** HTML tag to render. Default: 'div'. */
+    readonly as?: keyof React.JSX.IntrinsicElements;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user saves an edit in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<string>['origin'], newValue: string) => void;
+}
+/**
+ * Renders a plain-text field value. In published mode, renders the raw
+ * string in the specified tag with zero overhead. In preview mode,
+ * delegates to an inner component that provides click-to-edit via a modal.
+ */
+declare function EditableText(props: EditableTextProps): React.ReactElement;
+
+interface EditableRichTextProps {
+    /**
+     * The slot for this rich-text field. The slot kind `'richText'` is
+     * distinct from `'text'` so passing a `RichTextField` slot to
+     * `<EditableText>` (or vice versa) is a TS error — closing the
+     * substring-overlap blind spot the old heuristic gate had.
+     * `slot.value` is `string | PreviewFieldLike<string>`.
+     */
+    readonly field: EditableSlot<'richText', string>;
+    /** HTML tag to render. Default: 'div'. */
+    readonly as?: keyof React.JSX.IntrinsicElements;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user saves an edit in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<string>['origin'], newValue: string) => void;
+}
+/**
+ * Renders a rich-text field value with markdown processing. In published
+ * mode, renders markdown-derived HTML in the specified tag with zero
+ * overhead. In preview mode, delegates to an inner component that provides
+ * click-to-edit via a modal markdown editor.
+ */
+declare function EditableRichText(props: EditableRichTextProps): React.ReactElement;
+
+interface EditableImageProps {
+    /**
+     * The slot for this image field. `slot.value` is either a bare
+     * `ImageValue` (published) or `PreviewFieldLike<ImageValue>` (preview).
+     * The slot kind `'image'` rejects mismatched widgets at compile time.
+     */
+    readonly field: EditableSlot<'image', ImageValue>;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user picks a new image in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<ImageValue>['origin'], newValue: ImageValue) => void;
+}
+/**
+ * Renders an image field value. In published mode, renders a plain
+ * `<img>` with zero overhead. In preview mode, delegates to an inner
+ * component that opens the image picker on click.
+ */
+declare function EditableImage(props: EditableImageProps): React.ReactElement;
+
+interface EditableVideoProps {
+    /**
+     * The slot for this video field. `slot.value` is either a bare
+     * `VideoValue` (published) or `PreviewFieldLike<VideoValue>`
+     * (preview). The slot kind `'video'` rejects mismatched widgets at
+     * compile time.
+     */
+    readonly field: EditableSlot<'video', VideoValue>;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /**
+     * Force a specific aspect ratio regardless of `field.value.aspectRatio`.
+     * Useful when a section design fixes the ratio and the per-instance
+     * choice is not meaningful — the picker still surfaces the ratio
+     * selector, but the rendered iframe ignores it.
+     */
+    readonly aspectRatioOverride?: VideoValue['aspectRatio'];
+    /** Called when the user picks a new value in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<VideoValue>['origin'], newValue: VideoValue) => void;
+}
+/**
+ * Renders a video field value. In published mode, renders the provider
+ * iframe with no hooks (or `null` when there is no URL). In preview
+ * mode, delegates to an inner component that opens the URL picker on
+ * click and shows a placeholder when the URL is empty/unrecognised.
+ */
+declare function EditableVideo(props: EditableVideoProps): ReactElement | null;
+
+interface EditableLinkProps {
+    /**
+     * The slot for this link field. `slot.value` is either a bare
+     * `LinkValue` (published) or `PreviewFieldLike<LinkValue>` (preview).
+     * The slot kind `'link'` rejects mismatched widgets at compile time.
+     */
+    readonly field: EditableSlot<'link', LinkValue>;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user saves an edit in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<LinkValue>['origin'], newValue: LinkValue) => void;
+}
+declare function EditableLink(props: EditableLinkProps): React.ReactElement;
+
+interface EditableButtonProps {
+    /**
+     * The slot for this button field. `slot.value` is either a bare
+     * `ButtonValue` (published) or `PreviewFieldLike<ButtonValue>`
+     * (preview). The slot kind `'button'` rejects mismatched widgets at
+     * compile time.
+     */
+    readonly field: EditableSlot<'button', ButtonValue>;
+    /**
+     * The closed list of variants the section supports — surfaced in
+     * the picker's `<select>`. Should match the schema's `ButtonField`
+     * variants list. Required because EditableButton has no link to
+     * the descriptor at runtime.
+     */
+    readonly variants: ReadonlyArray<SelectOption>;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user saves an edit in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<ButtonValue>['origin'], newValue: ButtonValue) => void;
+}
+declare function EditableButton(props: EditableButtonProps): React.ReactElement;
+
+interface ButtonPickerModalProps {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    /**
+     * Fired when the user clicks Save. The caller is responsible for
+     * persisting the value; the modal also calls `onClose` immediately
+     * afterwards.
+     */
+    readonly onInsert: (value: ButtonValue) => void;
+    /** Variants list from the descriptor. */
+    readonly variants: ReadonlyArray<SelectOption>;
+    /** Current value, used to seed the inputs on open. */
+    readonly initialValue?: ButtonValue;
+    /**
+     * Stacking override. Defaults to 100000 — same plane as
+     * VideoPickerModal / ImagePickerModal.
+     */
+    readonly zIndex?: number;
+}
+declare function ButtonPickerModal(props: ButtonPickerModalProps): ReactElement | null;
+
+interface EditableNumberProps {
+    /**
+     * The slot for this number field. `slot.value` is either a bare
+     * number (published) or `PreviewFieldLike<number>` (preview). The
+     * slot kind `'number'` rejects mismatched widgets at compile time.
+     */
+    readonly field: EditableSlot<'number', number>;
+    /** HTML tag to render in display mode. Default: 'span'. */
+    readonly as?: keyof React.JSX.IntrinsicElements;
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Lower bound HINT for the input's clamping. Optional. */
+    readonly min?: number;
+    /** Upper bound HINT for the input's clamping. Optional. */
+    readonly max?: number;
+    /** Step HINT for the input. Default 1 (integer-friendly). */
+    readonly step?: number;
+    /** Called when the user commits a new value in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<number>['origin'], newValue: number) => void;
+}
+declare function EditableNumber(props: EditableNumberProps): React.ReactElement;
+
+interface EditableBooleanProps {
+    /**
+     * The slot for this boolean field. `slot.value` is either a bare
+     * boolean (published) or `PreviewFieldLike<boolean>` (preview). The
+     * slot kind `'boolean'` rejects mismatched widgets at compile time.
+     */
+    readonly field: EditableSlot<'boolean', boolean>;
+    /** Additional className applied to the wrapper. */
+    readonly className?: string;
+    /** Optional label rendered alongside the toggle in preview mode. */
+    readonly label?: string;
+    /** Called when the user toggles the value in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<boolean>['origin'], newValue: boolean) => void;
+}
+declare function EditableBoolean(props: EditableBooleanProps): React.ReactElement | null;
+
+interface EditableSelectProps {
+    /**
+     * The slot for this select field. `slot.value` is either a bare
+     * string (published) or `PreviewFieldLike<string>` (preview). The
+     * slot kind `'select'` rejects mismatched widgets at compile time.
+     */
+    readonly field: EditableSlot<'select', string>;
+    /**
+     * The option set. The section component passes this — typically the
+     * same array used in its descriptor — so the dropdown stays in sync
+     * with the schema.
+     */
+    readonly options: readonly SelectOption[];
+    /** Additional className applied to the outer element. */
+    readonly className?: string;
+    /** Called when the user picks a different option. */
+    readonly onSave?: (origin: PreviewFieldLike<string>['origin'], newValue: string) => void;
+}
+declare function EditableSelect(props: EditableSelectProps): React.ReactElement;
+
+type AnyItem = ListItem<SectionSchema>;
+interface EditableListProps<S extends SectionSchema = SectionSchema> {
+    /**
+     * The slot for this list field. SectionRenderer hands every editable
+     * field through `wrapAsSlot` (EDITABILITY_DESIGN.md sub-tasks 2 / 3),
+     * so the component receives an
+     * `EditableSlot<'list', ReadonlyArray<SlotItem<S>>>` whose `slot.value`
+     * is either a raw items array (published) or a
+     * `PreviewFieldLike<ReadonlyArray<…>>` carrying the list-level origin
+     * (preview).
+     *
+     * The runtime element type inside the array is `ListItem<S>` (bare
+     * items); the type asserts `SlotItem<S>` because the section author
+     * never sees the bare item directly — `<EditableList renderItem>`
+     * produces the slot-typed shape at render time via
+     * `wrapItemForPreview` (preview) or `wrapItemAsSlot` (published).
+     * Items are structurally compatible: the slot brand is phantom and
+     * adds no runtime keys.
+     */
+    readonly field: EditableSlot<'list', ReadonlyArray<SlotItem<S>>>;
+    /**
+     * The item schema. Section components MUST pass the same schema they
+     * declared in their descriptor — this is the schema the editor uses
+     * to render per-field controls inside each item card.
+     */
+    readonly itemSchema: S;
+    /** Optional minimum number of items the editor will keep visible. */
+    readonly min?: number;
+    /** Optional maximum number of items the editor will allow. */
+    readonly max?: number;
+    /** Additional className applied to the wrapper. */
+    readonly className?: string;
+    /**
+     * Render an item.
+     *
+     * `item` arrives as a `SlotItem<S>` in BOTH modes: every editable
+     * field on the schema is an `EditableSlot<K, V>`, and the section
+     * author drops `<EditableRichText field={item.title}>` straight into
+     * the card. In preview mode the slot's `value` carries a
+     * `PreviewFieldLike<…>` (with origin + inline-save closure); in
+     * published mode the slot's `value` is the bare data. A single
+     * `renderItem` body works in both modes.
+     *
+     * Falls back to `JSON.stringify` (using the bare items) when not
+     * provided so the editor at least sees something. */
+    readonly renderItem?: (item: SlotItem<S>, index: number) => React.ReactNode;
+    /** Called when the user mutates the array in preview mode. */
+    readonly onSave?: (origin: PreviewFieldLike<ReadonlyArray<AnyItem>>['origin'], newValue: ReadonlyArray<AnyItem>) => void;
+}
+declare function EditableList<S extends SectionSchema = SectionSchema>(props: EditableListProps<S>): React.ReactElement;
+
+interface VideoPickerModalProps {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    /**
+     * Fired when the user clicks Save. The caller is responsible for
+     * persisting the value; the modal also calls `onClose` immediately
+     * afterwards.
+     */
+    readonly onInsert: (value: VideoValue) => void;
+    /** Current value, used to seed the URL + ratio inputs on open. */
+    readonly initialValue?: VideoValue;
+    /**
+     * Stacking override. Defaults to 100000 — same plane as
+     * ImagePickerModal / MarkdownEditorModal. Callers that mount this
+     * picker on top of another modal should pass a higher value so the
+     * shared document-level Escape handler dismisses only the topmost
+     * modal instead of both at once.
+     */
+    readonly zIndex?: number;
+}
+declare function VideoPickerModal(props: VideoPickerModalProps): ReactElement | null;
+
+/**
+ * Function signature for field-level save. Accepts the origin metadata
+ * (which section + field) and the new field value.
+ *
+ * `newValue` is `unknown` because the save callback stores the value
+ * verbatim into `section.data[fieldPath]`, and each editable component
+ * is responsible for producing the right value shape before calling
+ * save. In v1 every built-in field resolves to a string, but keeping
+ * the channel lossless avoids a breaking change if a future BUILT-IN
+ * field type introduces a non-string value.
+ */
+type SaveFieldFn = (origin: PreviewFieldOriginLike, newValue: unknown) => void;
+interface SaveProviderProps {
+    readonly saveField: SaveFieldFn;
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides a `saveField` callback to all EditableText/EditableImage
+ * descendants. Typically placed by SectionEditControls around the
+ * preview section list.
+ */
+declare function SaveProvider(props: SaveProviderProps): React.ReactElement;
+/**
+ * Returns the `saveField` function from the nearest SaveProvider, or
+ * `null` if no provider is present (e.g., published mode).
+ */
+declare function useSaveField(): SaveFieldFn | null;
+
+interface GlobalSaveProviderProps {
+    readonly globalName: string;
+    readonly globalType: string;
+    /**
+     * The global's data as returned by `getGlobal` in preview mode —
+     * each value is a `PreviewField<T>`. We strip the wrappers when
+     * constructing the save payload so the on-disk global stores plain
+     * values. Keeping `initialData` as a snapshot lets the provider patch
+     * a single field without re-fetching the whole global.
+     */
+    readonly initialData: Readonly<Record<string, unknown>>;
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides a `saveField` callback that routes a single field-level
+ * edit to `/api/agntcms/global/save`. After a successful save we
+ * trigger a full page reload so layout-level globals (header, footer)
+ * pick up server-recomputed history/dedup state. We don't use Next.js's
+ * `useRouter().refresh()` because `<GlobalSlot>` typically renders at
+ * `app/layout.tsx` level where router context is unreliable; the reload
+ * is the conservative pattern `SectionEditControls` already uses for
+ * its global-ref save path.
+ *
+ * Concurrency note: two synchronous `saveField` calls in the same
+ * render cycle (e.g. a UI that batches two edits) MUST compose. The
+ * first call's update has to be visible to the second call. `useState`
+ * alone breaks this — `setLatestData` schedules an update for the next
+ * render, so the second call inside the same tick still reads the old
+ * snapshot. We back the state with a `useRef` that we mutate
+ * synchronously inside the callback; the `useState` mirror exists only
+ * so the React tree re-renders if the provider's children depend on
+ * data identity.
+ */
+declare function GlobalSaveProvider(props: GlobalSaveProviderProps): React.ReactElement;
+
+export { AdminModal, type AdminModalProps, ButtonPickerModal, type ButtonPickerModalProps, type DefinitionLike, EditableBoolean, type EditableBooleanProps, EditableButton, type EditableButtonProps, EditableImage, type EditableImageProps, EditableLink, type EditableLinkProps, EditableList, type EditableListProps, EditableNumber, type EditableNumberProps, EditableRichText, type EditableRichTextProps, EditableSelect, type EditableSelectProps, EditableSlot, EditableText, type EditableTextProps, EditableVideo, type EditableVideoProps, Form, FormFieldOverrides, type FormProps, type FormsByName, FormsRegistryProvider, type FormsRegistryProviderProps, type GlobalEntry, GlobalSaveProvider, type GlobalSaveProviderProps, PageRenderer, type PageRendererProps, type PayloadOf, type PreviewContextValue, type PreviewFieldLike, type PreviewFieldOriginLike, type PreviewMode, PreviewProvider, type PreviewProviderProps, PreviewToolbar, type PreviewToolbarProps, type SaveFieldFn, SaveProvider, type SaveProviderProps, SectionEditControls, type SectionEditControlsProps, SectionPickerModal, type SectionPickerModalProps, SectionRenderer, type SectionRendererProps, SectionReplaceOverlay, type SectionReplaceOverlayProps, SectionWrapper, type SectionWrapperProps, SlotItem, type TaskState, type TaskStatus, VideoPickerModal, type VideoPickerModalProps, isPreviewField, isSlotInPreview, read, useFormsRegistry, usePreviewMode, useSaveField, useTaskEvents };