@bettercms-ai/types 1.16.0 → 1.18.0

package/dist/index.d.ts

@@ -65,6 +65,15 @@ interface BlockStyle {
     paddingBottom?: number;
     paddingSides?: number;
     contentWidth?: ContentWidthToken;
+    /**
+     * Where the constrained content column sits, when `contentWidth` constrains it.
+     *
+     * Split out of `align`, which still means text alignment and is still the fallback when this
+     * is unset — so everything written before the split renders byte-identically. The two were one
+     * token until anything MEASURED a section's text alignment: copying a source site's
+     * `text-align: left` would otherwise also shove its column to the page edge.
+     */
+    contentAlign?: AlignToken;
     fullHeight?: boolean;
     /** 0–100. */
     opacity?: number;
@@ -89,6 +98,8 @@ interface HeadingBlock {
 }
 interface TextProps {
     html: string;
+    /** @see RichTextProps.level — the same payload takes the same level. */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
 }
 interface TextBlock {
     type: "text";
@@ -152,6 +163,13 @@ interface RichTextProps {
      * the stale string silently shadows the newer structure.
      */
     content?: PortableTextDocument;
+    /**
+     * Render the rich copy AS `<h1>`–`<h6>` instead of a paragraph container, so a title keeps
+     * its inline marks (a brand-coloured span) AND its heading semantics. Absent ⇒ ordinary rich
+     * text, as before. Set ⇒ the value must be ONE line of inline copy; the write schema refuses
+     * more. A component prop of type `number` or `select` can target `props.level`.
+     */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
 }
 interface RichTextBlock {
     type: "richtext";
@@ -217,6 +235,12 @@ interface VideoProps {
     poster?: string;
     autoplay?: boolean;
     loop?: boolean;
+    /**
+     * What is said in the video (CPO-093). The block carries its own because its url may be a
+     * pasted provider link with no library asset to hang one from. Rendered as <details> after
+     * the player and published in the .md twin.
+     */
+    transcript?: string;
 }
 interface VideoBlock {
     type: "video";
@@ -443,8 +467,13 @@ declare function getBlockType(value: unknown): BlockType | null;
  * `url` never takes a caret — a URL typed onto the page has nowhere to report a malformed
  * value — so it is edited in the element toolbar. `array` is a repeater slot: selectable and
  * locatable, edited in the dock.
+ *
+ * `document` is a whole Portable Text body: selectable as ONE container, repainted whole from the
+ * form, and edited per keyed block inside it. It is not a longer `richtext` — a Body stamped
+ * `richtext` goes into the rich-text lane, where an opt-out rewrites the value as an `{html}`
+ * envelope and the document's own block structure is destroyed.
  */
-type BindingKind = "text" | "richtext" | "image" | "url" | "number" | "array";
+type BindingKind = "text" | "richtext" | "image" | "document" | "url" | "number" | "array";
 interface BlockBinding {
     /** Path template in grammar A, relative to the block's `props`. `[]` = an array to walk. */
     readonly path: string;
@@ -564,6 +593,206 @@ declare function componentInstanceAddresses(instanceBlockId: string, props: read
 /** A CSS declaration object (key → value) usable as a React `style` prop, or undefined when empty. */
 declare function blockStyleToCss(style: BlockStyle | undefined): Record<string, string | number> | undefined;
 
+/**
+ * ContentModel — the structured content model (schema) for a workspace.
+ * Defines which content fields are available for authors to fill in.
+ */
+interface ContentModel {
+    id: string;
+    workspaceId: string;
+    name: string;
+    description?: string;
+    /** 'block' models hold no entries — they are instantiable only inside a `modular` field. */
+    kind?: ContentModelKind;
+    fields: ContentModelField[];
+    /** Authoring-only field grouping for the schema builder. Never affects the API shape. */
+    fieldsets?: Fieldset[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Canonical field types. Nesting lives on `array` via `config.zones`
+ * (see {@link ArrayZoneConfig}): `group`/`repeater` are accepted as legacy input
+ * by the API but normalized to `array` + zones on write, so stored/delivered
+ * content never contains them.
+ */
+type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location";
+type ContentModelKind = "model" | "block";
+/** A named, UI-only grouping of a model's fields. Order is the array index. */
+interface Fieldset {
+    id: string;
+    name: string;
+    /** One line shown under the card title in the editor. Editor-only. */
+    description?: string;
+}
+/**
+ * Nested-content config for an `array` field. A zone holds ordinary fields, and a
+ * zone field may itself be an `array` with its own zones, so nesting is recursive
+ * to any depth.
+ *   - `nonRepeatable` — a single fixed block of fields (former `group`).
+ *   - `repeatable`    — a repeating list of field-objects (former `repeater`).
+ * Mutually exclusive with the primitive form (`config.itemType`).
+ */
+interface ArrayZoneConfig {
+    nonRepeatable?: ContentModelField[];
+    repeatable?: {
+        fields: ContentModelField[];
+        minItems?: number;
+        maxItems?: number;
+    };
+}
+/** Per-type config for a field (the typed shape behind the loose `config` bag). */
+interface FieldConfig {
+    /** primitive array: list of scalars */
+    itemType?: "text" | "number" | "date";
+    /** nested array: zoned fields (recursive) */
+    zones?: ArrayZoneConfig;
+    /** reference / multi-reference */
+    contentModelId?: string;
+    min?: number;
+    max?: number;
+    /** date / datetime */
+    includeTime?: boolean;
+    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
+    blockSlugs?: string[];
+    /** modular: bounds on how many block instances the field may hold. */
+    minItems?: number;
+    maxItems?: number;
+    /**
+     * sections: SLUGS of the sections an author may insert into this zone.
+     *
+     * Deliberately NOT named `blockSlugs`. That key means "kind='block' content models" and is
+     * read by ModularField; these are section-registry slugs resolved from a different place.
+     * One key meaning two things is how `blockModels`/`blockSlugs` already drifted apart in the
+     * dashboard — a distinct name costs nothing and cannot be confused at a call site.
+     *
+     * ⚠ ABSENT ≠ EMPTY:
+     *     absent   → UNRESTRICTED, every registry section may be inserted
+     *     []       → DENY ALL, a deliberate empty restriction
+     *     [a, b]   → only those
+     * `[]` means DENY here to match `components.allowed_on` (migration 0190), so two adjacent
+     * allow-lists never disagree about what empty means.
+     *
+     * Absent rather than "all current slugs" because the registry GROWS — it is fed by repo
+     * pushes and project components, so materializing today's slugs at field-creation time would
+     * silently exclude every section shipped afterwards.
+     *
+     * NOT READ DIRECTLY. Insertability is this list INTERSECTED with the component's `allowedOn`
+     * (where that section may be placed), computed by one resolver so the two cannot drift.
+     *
+     * Enforced on NEW picks only. Narrowing the list later must never invalidate sections an
+     * author already placed, the same rule modular's blockSlugs and component-ref's allowlist
+     * follow.
+    */
+    allowedSections?: string[];
+    /** Durable project-local authored Zone mode. Legacy zones omit this key. */
+    mode?: "authored-v2";
+    /** Durable Zone id. Present when `mode` is `authored-v2`. */
+    zoneId?: string;
+    /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
+    legacyResolved?: boolean;
+    legacyMappings?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Where a field renders in the entry editor.
+ *
+ * AUTHORING ONLY — this has no delivery or storage effect. It does not change the
+ * shape of `data`, is not read by any renderer in @bettercms-ai/next or /astro, and
+ * cannot move a value onto or off a published page. It decides one thing: where the
+ * control sits while somebody is writing.
+ *
+ * Granularity is REGION-level, never interleaved between body blocks: the canvas is
+ * `[hero slots] → [free block flow] → [inline fields] → [panel fields in the drawer]`.
+ * A field cannot be positioned "between two paragraphs" — there is no coordinate space
+ * for that, and inventing one would mean mounting form controls inside the Lexical tree.
+ *
+ * - `cover` / `title` / `excerpt` / `body` — the four hero slots, rendered unlabelled
+ *   and typographically native. SCHEMA-LEVEL ONLY: a per-entry override may never
+ *   claim one, or one author's click renders anonymous 40px text over anonymous text
+ *   on that entry alone.
+ * - `inline` — in the canvas, below the block flow, labelled.
+ * - `panel` — in the drawer.
+ *
+ * ABSENT is meaningful and is the default for every model that predates this: the
+ * editor falls back to its title-gated heuristic. Only an explicit value promotes a
+ * field past that gate.
+ */
+type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inline" | "panel";
+interface ContentModelField {
+    key: string;
+    label: string;
+    type: ContentModelFieldType;
+    required?: boolean;
+    /**
+     * No two entries of the model may hold the same value (trimmed, case-insensitive). On a
+     * repeater child, every row of every entry at that path. Scalar types only.
+     */
+    unique?: boolean;
+    defaultValue?: unknown;
+    options?: string[];
+    /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
+    config?: FieldConfig | null;
+    /**
+     * Which fieldset this field renders under in the schema builder. Authoring-only: it is
+     * never delivered and cannot move a value — see {@link Fieldset}.
+     */
+    fieldsetId?: string;
+    /**
+     * Authoring-only editor placement. See {@link ContentModelFieldPlacement}.
+     * Field ORDER is the array index — there is deliberately no `order` property.
+     */
+    placement?: ContentModelFieldPlacement;
+    /**
+     * Authoring chrome — how the field PRESENTS in the editor. Never delivered, never read by a
+     * renderer, and never able to move a value; the same contract as {@link placement}.
+     *
+     * A SIBLING of `config`, not a member of it: `config` is per-type and strict on several
+     * types, and the normalizer rebuilds it wholesale for every nesting field — so a `config.ui`
+     * survives on leaves and vanishes on exactly the fields `preview` is for.
+     *
+     * `preview.title` / `preview.media` name a CHILD FIELD KEY of this field (validated on
+     * write). Still no `order`: order is the array index, per the note on {@link placement}.
+     */
+    ui?: ContentModelFieldUi;
+}
+/** @see ContentModelField.ui */
+interface ContentModelFieldUi {
+    /** Start this nesting field's panel collapsed. Absent ≡ the editor's own default. */
+    collapsed?: boolean;
+    /** How one item of a nesting field summarises itself when collapsed. Keys, not values. */
+    preview?: {
+        /** Child field key whose value titles the row. */
+        title?: string;
+        /** Child field key whose value is the row's thumbnail. Type is not constrained. */
+        media?: string;
+    };
+    /**
+     * How the ITEMS of a nesting field are arranged. ABSENT ≡ `"list"` — every field stored
+     * before this key existed means `"list"`, so a reader must treat undefined as list and never
+     * as "unset, pick something".
+     *
+     * Same placement rule as {@link ContentModelFieldUi.preview}: nesting fields only.
+     */
+    layout?: "list" | "grid" | "table";
+    /**
+     * Whether the items of a list may be dragged. ABSENT ≡ `true`, for the same reason — nothing
+     * stored today carries it, and everything stored today is reorderable.
+     *
+     * `false` LOCKS the order: a "three steps" band, a semantic nav, a timeline. Valid only where
+     * there is a list (a repeatable zone, a `repeater`, or `modular`), so a reader that honours it
+     * must disable the sortable behaviour, not just hide the grip — a hidden grip still reorders
+     * from the keyboard.
+     */
+    reorderable?: boolean;
+}
+/**
+ * A field inside an array zone — identical to a top-level {@link ContentModelField}.
+ * Kept as a named alias so consumers can express "zone field" intent; recursion
+ * (an array zone field with its own `config.zones`) is supported.
+ */
+type ZoneField = ContentModelField;
+
 /**
  * Generated from lucide-react@1.8.0 dynamic icon names.
  * Legacy CamelCase identifiers remain valid for existing Layout documents.
@@ -940,6 +1169,34 @@ type ComponentCategory = "navbar" | "footer" | "button" | "section" | "slider" |
  * "props.text"). Keeping overrides a declared allowlist (not arbitrary nested
  * rewrites) keeps instance data small and the contract explicit.
  */
+/**
+ * THE prop vocabulary. One list, imported everywhere a prop type is enumerated.
+ *
+ * It exists as a value (not just a union) because four places used to spell it out by hand —
+ * this file, the Drizzle schema, `COMPONENT_PROP_TYPES` in the backend's Zod schemas, and the
+ * MCP tool shape — and the MCP copy is the dangerous one: `update_component` REPLACES the whole
+ * `props` array, so a type its enum omits cannot be echoed back, and an agent that reads a
+ * component and writes it straight back DESTROYS every prop of that type with a 200.
+ *
+ * Order is not semantic; append rather than re-sort, so a diff stays readable.
+ */
+declare const COMPONENT_PROP_TYPES: readonly ["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot", "form"];
+type ComponentPropType = (typeof COMPONENT_PROP_TYPES)[number];
+/**
+ * The value a `form` prop STORES: just the id. The form itself is a Form document and stays the
+ * single source of truth for its fields — a component references one, it never re-declares it.
+ *
+ * `.strict()` at the write boundary, so a client that POSTs a hydrated form object alongside the
+ * id gets a 400 rather than a silent strip.
+ *
+ * There is deliberately NO resolved twin of this shape. Every renderer already receives forms the
+ * same way — a catalogue beside the blocks (`BcmsBlocks({blocks, forms})`, the site renderer's
+ * forms map) — and looks the id up in it. A hydrated `{formId, form}` prop value would be a shape
+ * that exists nowhere in delivery.
+ */
+interface ComponentFormPropRef {
+    formId: string;
+}
 interface ComponentPropDef {
     key: string;
     label: string;
@@ -969,7 +1226,7 @@ interface ComponentPropDef {
      * `reference` is absent on purpose: nothing resolves a content-entry id at component render
      * time, so such a prop would save cleanly and render as nothing.
      */
-    type: "text" | "richtext" | "image" | "url" | "boolean" | "number" | "select" | "group" | "table" | "slot";
+    type: ComponentPropType;
     defaultValue?: unknown;
     /**
      * EDITOR HINTS (playbook §12). Stored in the props JSON, so no migration.
@@ -998,13 +1255,26 @@ interface ComponentPropDef {
         max?: number;
         step?: number;
     } & Record<string, unknown>;
+    /**
+     * AUTHORING CHROME — the same object a content-model FIELD carries ({@link ContentModelFieldUi}),
+     * deliberately: an agent that has learned `ui` once has learned it on both lanes.
+     *
+     * A SIBLING of `config`, not a member of it. `config` is a loose bag, so a `config.ui` already
+     * survived the write — and that is the problem this key fixes: surviving is not declared, and
+     * an undeclared prop is a typo that saves cleanly and renders as nothing.
+     *
+     * WHERE EACH KEY IS LEGAL differs from the field lane, because the vocabulary does:
+     * `preview`/`layout` on `group`, `table` and `slot`; `reorderable` on `table` ALONE, the only
+     * prop type whose value is a list. The save schema refuses the rest with the valid set named.
+     */
+    ui?: ContentModelFieldUi;
 }
 /** One field inside a `group` prop or a `table` row. Recursive, capped at 3 levels deep. */
 interface ComponentSubField {
     key: string;
     label: string;
     /** No `slot`: a nested component instance belongs on the prop itself, not inside a row. */
-    type: Exclude<ComponentPropDef["type"], "slot">;
+    type: Exclude<ComponentPropDef["type"], "slot" | "form">;
     defaultValue?: unknown;
     /** The same editor hints as the prop above, one level down. @see ComponentPropDef */
     required?: boolean;
@@ -1124,157 +1394,6 @@ interface ContentEntry {
     updatedAt: string;
 }
 
-/**
- * ContentModel — the structured content model (schema) for a workspace.
- * Defines which content fields are available for authors to fill in.
- */
-interface ContentModel {
-    id: string;
-    workspaceId: string;
-    name: string;
-    description?: string;
-    /** 'block' models hold no entries — they are instantiable only inside a `modular` field. */
-    kind?: ContentModelKind;
-    fields: ContentModelField[];
-    /** Authoring-only field grouping for the schema builder. Never affects the API shape. */
-    fieldsets?: Fieldset[];
-    createdAt: string;
-    updatedAt: string;
-}
-/**
- * Canonical field types. Nesting lives on `array` via `config.zones`
- * (see {@link ArrayZoneConfig}): `group`/`repeater` are accepted as legacy input
- * by the API but normalized to `array` + zones on write, so stored/delivered
- * content never contains them.
- */
-type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location";
-type ContentModelKind = "model" | "block";
-/** A named, UI-only grouping of a model's fields. Order is the array index. */
-interface Fieldset {
-    id: string;
-    name: string;
-}
-/**
- * Nested-content config for an `array` field. A zone holds ordinary fields, and a
- * zone field may itself be an `array` with its own zones, so nesting is recursive
- * to any depth.
- *   - `nonRepeatable` — a single fixed block of fields (former `group`).
- *   - `repeatable`    — a repeating list of field-objects (former `repeater`).
- * Mutually exclusive with the primitive form (`config.itemType`).
- */
-interface ArrayZoneConfig {
-    nonRepeatable?: ContentModelField[];
-    repeatable?: {
-        fields: ContentModelField[];
-        minItems?: number;
-        maxItems?: number;
-    };
-}
-/** Per-type config for a field (the typed shape behind the loose `config` bag). */
-interface FieldConfig {
-    /** primitive array: list of scalars */
-    itemType?: "text" | "number" | "date";
-    /** nested array: zoned fields (recursive) */
-    zones?: ArrayZoneConfig;
-    /** reference / multi-reference */
-    contentModelId?: string;
-    min?: number;
-    max?: number;
-    /** date / datetime */
-    includeTime?: boolean;
-    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
-    blockSlugs?: string[];
-    /** modular: bounds on how many block instances the field may hold. */
-    minItems?: number;
-    maxItems?: number;
-    /**
-     * sections: SLUGS of the sections an author may insert into this zone.
-     *
-     * Deliberately NOT named `blockSlugs`. That key means "kind='block' content models" and is
-     * read by ModularField; these are section-registry slugs resolved from a different place.
-     * One key meaning two things is how `blockModels`/`blockSlugs` already drifted apart in the
-     * dashboard — a distinct name costs nothing and cannot be confused at a call site.
-     *
-     * ⚠ ABSENT ≠ EMPTY:
-     *     absent   → UNRESTRICTED, every registry section may be inserted
-     *     []       → DENY ALL, a deliberate empty restriction
-     *     [a, b]   → only those
-     * `[]` means DENY here to match `components.allowed_on` (migration 0190), so two adjacent
-     * allow-lists never disagree about what empty means.
-     *
-     * Absent rather than "all current slugs" because the registry GROWS — it is fed by repo
-     * pushes and project components, so materializing today's slugs at field-creation time would
-     * silently exclude every section shipped afterwards.
-     *
-     * NOT READ DIRECTLY. Insertability is this list INTERSECTED with the component's `allowedOn`
-     * (where that section may be placed), computed by one resolver so the two cannot drift.
-     *
-     * Enforced on NEW picks only. Narrowing the list later must never invalidate sections an
-     * author already placed, the same rule modular's blockSlugs and component-ref's allowlist
-     * follow.
-    */
-    allowedSections?: string[];
-    /** Durable project-local authored Zone mode. Legacy zones omit this key. */
-    mode?: "authored-v2";
-    /** Durable Zone id. Present when `mode` is `authored-v2`. */
-    zoneId?: string;
-    /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
-    legacyResolved?: boolean;
-    legacyMappings?: Record<string, string>;
-    [key: string]: unknown;
-}
-/**
- * Where a field renders in the entry editor.
- *
- * AUTHORING ONLY — this has no delivery or storage effect. It does not change the
- * shape of `data`, is not read by any renderer in @bettercms-ai/next or /astro, and
- * cannot move a value onto or off a published page. It decides one thing: where the
- * control sits while somebody is writing.
- *
- * Granularity is REGION-level, never interleaved between body blocks: the canvas is
- * `[hero slots] → [free block flow] → [inline fields] → [panel fields in the drawer]`.
- * A field cannot be positioned "between two paragraphs" — there is no coordinate space
- * for that, and inventing one would mean mounting form controls inside the Lexical tree.
- *
- * - `cover` / `title` / `excerpt` / `body` — the four hero slots, rendered unlabelled
- *   and typographically native. SCHEMA-LEVEL ONLY: a per-entry override may never
- *   claim one, or one author's click renders anonymous 40px text over anonymous text
- *   on that entry alone.
- * - `inline` — in the canvas, below the block flow, labelled.
- * - `panel` — in the drawer.
- *
- * ABSENT is meaningful and is the default for every model that predates this: the
- * editor falls back to its title-gated heuristic. Only an explicit value promotes a
- * field past that gate.
- */
-type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inline" | "panel";
-interface ContentModelField {
-    key: string;
-    label: string;
-    type: ContentModelFieldType;
-    required?: boolean;
-    defaultValue?: unknown;
-    options?: string[];
-    /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
-    config?: FieldConfig | null;
-    /**
-     * Which fieldset this field renders under in the schema builder. Authoring-only: it is
-     * never delivered and cannot move a value — see {@link Fieldset}.
-     */
-    fieldsetId?: string;
-    /**
-     * Authoring-only editor placement. See {@link ContentModelFieldPlacement}.
-     * Field ORDER is the array index — there is deliberately no `order` property.
-     */
-    placement?: ContentModelFieldPlacement;
-}
-/**
- * A field inside an array zone — identical to a top-level {@link ContentModelField}.
- * Kept as a named alias so consumers can express "zone field" intent; recursion
- * (an array zone field with its own `config.zones`) is supported.
- */
-type ZoneField = ContentModelField;
-
 /**
  * MediaAsset — a file uploaded to the CMS media library.
  */
@@ -1290,10 +1409,40 @@ interface MediaAsset {
     width?: number;
     height?: number;
     altText?: string;
+    /**
+     * Video/audio only: what is said in the recording (CPO-093). Stored once on the asset and
+     * resolved into every file value that references it. null/absent = nobody has written one.
+     */
+    transcript?: string | null;
+    /**
+     * RESERVED (CPO-093 §2) — caption/subtitle tracks for the player (WCAG 1.2.2). Not rendered,
+     * not writable and not returned yet; the shape is fixed now so the follow-up is additive.
+     */
+    captions?: MediaCaptionTrack[];
     isActive: boolean;
     createdAt: string;
     updatedAt: string;
 }
+/** RESERVED — one `.vtt` track. See MediaAsset.captions. */
+interface MediaCaptionTrack {
+    lang: string;
+    label: string;
+    url: string;
+    kind: "captions" | "subtitles";
+    default?: boolean;
+}
+/**
+ * A `file` (or `image`) field value as the delivery API returns it. `transcript` is the
+ * RESOLVED value — the referenced video/audio asset's own — so a client never follows the asset
+ * to find it. Present only when the asset is video or audio and has one.
+ */
+interface MediaFieldValue {
+    id?: string;
+    url: string;
+    name?: string;
+    altText?: string | null;
+    transcript?: string;
+}
 
 /**
  * Delivery API response shapes — the read surface consumed by framework
@@ -1310,6 +1459,13 @@ interface DeliveryEntry<T = Record<string, unknown>> {
     publishedAt: string | null;
     updatedAt: string | null;
     data: T;
+    /**
+     * The entry's SEO, ready for `<head>`: its collection template's meta and JSON-LD with
+     * `{{field}}` tokens already resolved for this entry, the entry's own values merged over it
+     * field by field, and an empty title/description auto-filled from its content. Feed it to
+     * `resolveSeo(entrySeoInput(entry), siteDefaults)`; there is no token work left to do.
+     */
+    seo?: DeliveryEntrySeo;
     /** Hydrated reference fields, present when `depth >= 1`. */
     _hydration?: Record<string, DeliveryEntry | DeliveryEntry[]>;
     _meta?: {
@@ -1360,6 +1516,12 @@ interface PageMetaJson {
     };
     schema?: Record<string, unknown> | Array<Record<string, unknown>>;
 }
+/** `DeliveryEntry.seo`: the page meta shape plus the entry's flat title, description and noindex. */
+interface DeliveryEntrySeo extends PageMetaJson {
+    metaTitle?: string;
+    metaDescription?: string;
+    noindex?: boolean;
+}
 /**
  * Site-level SEO defaults a headless consumer passes to `resolveSeo`/`buildMetadata`
  * so per-page meta layers over project-wide fallbacks (mirrors the server renderer's
@@ -1444,6 +1606,7 @@ interface FormField {
         equals: string;
     };
     validation?: FormFieldValidation;
+    ui?: FormFieldUi;
 }
 /**
  * Per-field validation rules (FLO-1017). Each key is only meaningful on the field
@@ -1464,6 +1627,27 @@ type FormFieldValidation = {
     /** `text` | `textarea` | `url` — anchored regex, compiled and length-capped at save time. */
     pattern?: string;
 };
+/**
+ * Per-field PRESENTATION options. Currently only the phone field's country picker.
+ *
+ * Deliberately NOT part of `FormFieldValidation`: that object is "rules the submit endpoint
+ * enforces", and `lib/forms/validate` never reads this one. The save route gates each key to
+ * the field types that actually render it, so a key accepted here is a key something draws.
+ */
+type FormFieldUi = {
+    /** `phone` — render a country picker beside the number. The value is stored as E.164. */
+    countryPicker?: boolean;
+    /** `phone` — ISO 3166-1 alpha-2, uppercase. The country the picker starts on. */
+    defaultCountry?: string;
+    /**
+     * `phone` — show the country's flag beside the dialling code.
+     *
+     * Only the dashboard's searchable picker can honour this: the site renderers use a native
+     * `<select>`, which cannot contain an SVG, and an emoji flag degrades to two grey letters on
+     * Windows. They show the country NAME instead, which carries the same information.
+     */
+    showFlags?: boolean;
+};
 /**
  * FormSubmission — a single form submission submitted by a visitor.
  */
@@ -1597,4 +1781,4 @@ type DeepReadonly<T> = T extends Function ? T : T extends object ? {
  */
 type AssertEqual<L, R> = [L] extends [R] ? ([R] extends [L] ? true : false) : false;
 
-export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, type BetterCMSErrorCode, type BindingKind, type BlockBinding, type BlockStyle, type BlockType, type ButtonBlock, type ButtonProps, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentPropDef, type ComponentProps, type ComponentSubField, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentPageResult, type ContentResponse, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryList, type DeliveryPage, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, type ImageBlock, type ImageProps, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type ManagementLayoutCommand, type MediaAsset, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, type SectionBlock, type SectionProps, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, componentInstanceAddresses, componentPropTargetKey, expandBlockBindings, formatPropsAttribute, getBlockType, isBlock, parsePropsAttribute, readPath };
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockStyle, type BlockType, type ButtonBlock, type ButtonProps, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentProps, type ComponentSubField, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type CornerToken, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, type ImageBlock, type ImageProps, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, type SectionBlock, type SectionProps, type ShadowToken, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, componentInstanceAddresses, componentPropTargetKey, expandBlockBindings, formatPropsAttribute, getBlockType, isBlock, parsePropsAttribute, readPath };

package/dist/index.js

@@ -128,6 +128,19 @@ function blockStyleToCss(style) {
 
 // src/component.ts
 var SECTION_DOCTRINE = "STRUCTURE (separate from schema): a page is composed of SECTIONS. NEVER build a page out of loose top-level heading/text/image/button/spacer blocks \u2014 they cannot be moved, duplicated or swapped as a unit, the visual editor cannot outline or name them, and every one of them becomes its own section in the editor. A hero of a headline, a lede and two CTAs is ONE section, not four. TWO SHAPES, and the choice is about REUSE. (1) A band that appears on more than one page, or that needs layout variants, is a COMPONENT with a `sectionType` \u2014 see create_component. Components sharing a `sectionType` are that section's VARIANTS (one Hero: 'Centered' for the home page and 'Two-column' for about, same prop keys so a swap keeps the content). This is also the only shape the editor's 'Add a section' picker can insert, and the only one that gets a family name and a variant switcher. (2) A genuinely one-off band on a single page is a `section` BLOCK whose `props.children` hold its blocks. THE TRADEOFF, stated in the present tense because it is real today: inside a component, ONLY the leaves a declared prop TARGETS are click-to-edit on the canvas \u2014 each declared prop's `target` is re-keyed to that PLACEMENT's own override address, so editing it changes this page and not the shared definition. A prop with no `target` still SHOWS as a dock control, but its override reaches no rendered slot, so editing it changes nothing on the page. Copy that no prop points at is worse still: no binding and no control, unreachable from click-to-edit AND from the dock, changeable only by editing the component definition, which rewrites every page that places it. A `section` block's children stay click-to-edit unconditionally. So when you choose a component, DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch; a component with un-propped editable copy is the defect, not the component. In the dock an unset prop shows EMPTY and inherits the definition's default, so set props explicitly when you want the current copy visible there. Do not hand-write a band's JSON: start from a built-in section blueprint (list_components returns locked `builtin:*` blueprints with no projectId \u2014 hero-centered, hero-split, feature-grid-three, cta-banner and nine more), each already rooted in a `section` block with its editable leaves declared as props. INLINE its blockJson as a `section` block for a one-off band; for a recurring band, materialize the blueprint with create_component so it becomes project-scoped before implementation validation, Output or publication. Direct `builtin:*` component references exist only for legacy delivery compatibility. Two consecutive call-to-action buttons are two sibling `button` blocks inside the same section \u2014 never a `columns` block, which is a `repeat(N,1fr)` grid and would stretch each CTA to half the container. Buttons are inline-level and flow side by side on their own.";
+var COMPONENT_PROP_TYPES = [
+  "text",
+  "richtext",
+  "image",
+  "url",
+  "boolean",
+  "number",
+  "select",
+  "group",
+  "table",
+  "slot",
+  "form"
+];
 
 // src/layout-lucide-icons.ts
 var LAYOUT_SECTION_ICONS = Object.freeze([
@@ -2097,6 +2110,7 @@ var NAVIGATION_SECTION_ID = "navigation";
 var FOOTER_SECTION_ID = "footer";
 export {
   BLOCK_BINDINGS,
+  COMPONENT_PROP_TYPES,
   FOOTER_SECTION_ID,
   LAYOUT_SECTION_ICONS,
   LAYOUT_SECTION_ICON_SET,