@bettercms-ai/types 1.40.0 → 1.42.0

package/dist/index.d.ts

@@ -15,16 +15,84 @@ interface Workspace {
 
 /**
  * Generated by scripts/gen-dock-icon-names.mjs from the vendored icon tarball
- * (sha256 0691620e50bdf453c2fed06224d9dc52d521574ab254a149eba47664b92fb889).
+ * (sha256 0691620e50bdf453c2fed06224d9dc52d521574ab254a149eba47664b92fb889)
+ * and the vendored line-icon subset (sha256 06cd85d602d1104d962ed8ace64f6c4d64846ee50bd62bd328252c9d8f697b75).
  * Do not edit by hand: rerun the script (`--check` fails CI on drift).
  *
  * The closed vocabulary for `ui.icon` (field ui, fieldsets, prop ui.group). `as const` because a
  * z.enum needs the literal tuple; a `readonly string[]` would type every string as valid.
  */
-declare const DOCK_ICON_NAMES: readonly ["access-denied", "activity", "add", "add-circle", "add-comment", "add-document", "add-user", "api", "archive", "arrow-down", "arrow-left", "arrow-right", "arrow-top-right", "arrow-up", "asterisk", "bar-chart", "basket", "bell", "bill", "binary-document", "block-content", "block-element", "blockquote", "bold", "bolt", "book", "bookmark", "bookmark-filled", "bottle", "bug", "bulb-filled", "bulb-outline", "calendar", "case", "chart-upward", "checkmark", "checkmark-circle", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle", "clipboard", "clipboard-image", "clock", "close", "close-circle", "code", "code-block", "cog", "collapse", "color-wheel", "comment", "component", "compose", "compose-sparkles", "confetti", "controls", "copy", "credit-card", "crop", "cube", "dashboard", "database", "desktop", "diamond", "document", "document-pdf", "document-remove", "document-sheet", "document-text", "document-video", "document-word", "document-zip", "documents", "dot", "double-chevron-down", "double-chevron-left", "double-chevron-right", "double-chevron-up", "double-quote", "download", "drag-handle", "drop", "earth-americas", "earth-globe", "edit", "ellipsis-horizontal", "ellipsis-vertical", "empty", "enter", "enter-right", "envelope", "equal", "error-filled", "error-outline", "error-screen", "expand", "eye-closed", "eye-open", "face-happy", "face-indifferent", "face-sad", "feedback", "filter", "folder", "generate", "github", "groq", "hash", "heart", "heart-filled", "help-circle", "highlight", "home", "ice-cream", "image", "image-remove", "images", "inbox", "info-filled", "info-outline", "inline", "inline-element", "insert-above", "insert-below", "italic", "joystick", "json", "launch", "leave", "lemon", "link", "link-removed", "linkedin", "list", "lock", "logo-js", "logo-ts", "marker", "marker-removed", "master-detail", "menu", "microphone", "microphone-slash", "mobile-device", "moon", "number", "ok-hand", "olist", "overage", "package", "panel-left", "panel-right", "pause", "pin", "pin-filled", "pin-removed", "play", "plug", "presentation", "progress-50", "progress-75", "projects", "publish", "read-only", "redo", "refresh", "remove", "remove-circle", "reset", "restore", "retrieve", "retry", "revert", "robot", "rocket", "schema", "search", "select", "share", "sort", "sparkle", "sparkles", "spinner", "split-horizontal", "split-vertical", "square", "stack", "stack-compact", "star", "star-filled", "stop", "strikethrough", "string", "sun", "sync", "tablet-device", "tag", "tags", "target", "task", "terminal", "text", "th-large", "th-list", "thumbs-down", "thumbs-up", "tiers", "timeline", "toggle-arrow-right", "token", "transfer", "translate", "trash", "trend-upward", "triangle-outline", "trolley", "truncate", "twitter", "ulist", "unarchive", "underline", "undo", "unknown", "unlink", "unlock", "unpublish", "upload", "user", "users", "versions", "video", "warning-filled", "warning-outline", "wrench"];
+declare const DOCK_ICON_NAMES: readonly ["abc", "access-denied", "activity", "add", "add-circle", "add-comment", "add-document", "add-user", "address-book", "adjustments", "adjustments-horizontal", "alarm", "alert-triangle", "align-left", "api", "app-window", "apple", "apps", "archive", "arrow-back-up", "arrow-down", "arrow-guide", "arrow-left", "arrow-right", "arrow-top-right", "arrow-up", "arrows-diagonal", "arrows-down", "arrows-exchange", "arrows-horizontal", "arrows-left-right", "arrows-shuffle", "arrows-sort", "article", "aspect-ratio", "asterisk", "award", "axis-x", "backpack", "badge", "badge-cc", "badges", "bar-chart", "basket", "bell", "bill", "binary-document", "block-content", "block-element", "blockquote", "bold", "bolt", "book", "book-2", "bookmark", "bookmark-filled", "books", "bottle", "box", "brand-dribbble", "brand-facebook", "brand-instagram", "brand-linkedin", "brand-pinterest", "brand-tiktok", "brand-x", "brand-youtube", "briefcase", "broadcast", "browser", "bug", "building", "building-skyscraper", "building-store", "bulb-filled", "bulb-outline", "calculator", "calendar", "calendar-dollar", "calendar-event", "calendar-exclamation", "calendar-off", "calendar-plus", "calendar-star", "calendar-time", "camera", "campfire", "carousel-horizontal", "case", "cash", "category", "category-2", "chart-area", "chart-arrows", "chart-bar", "chart-bar-popular", "chart-donut", "chart-dots", "chart-line", "chart-upward", "check", "checkbox", "checklist", "checkmark", "checkmark-circle", "chef-hat", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "chevrons-right", "circle", "circle-check", "circle-dot", "circle-number-1", "circle-plus", "click", "clipboard", "clipboard-image", "clipboard-text", "clock", "clock-check", "clock-hour-4", "close", "close-circle", "code", "code-block", "cog", "collapse", "color-wheel", "columns", "columns-2", "columns-3", "comment", "component", "compose", "compose-sparkles", "confetti", "controls", "cookie", "copy", "credit-card", "crop", "cube", "currency-dollar", "dashboard", "database", "database-search", "desktop", "device-desktop", "device-mobile", "device-tablet", "devices", "diamond", "discount", "document", "document-pdf", "document-remove", "document-sheet", "document-text", "document-video", "document-word", "document-zip", "documents", "door-exit", "dot", "double-chevron-down", "double-chevron-left", "double-chevron-right", "double-chevron-up", "double-quote", "download", "drag-handle", "drop", "droplet", "droplet-half", "earth-americas", "earth-globe", "edit", "egg", "ellipsis-horizontal", "ellipsis-vertical", "empty", "enter", "enter-right", "envelope", "equal", "error-filled", "error-outline", "error-screen", "expand", "eye-closed", "eye-off", "eye-open", "face-happy", "face-indifferent", "face-sad", "feather", "feedback", "file", "file-certificate", "file-code", "file-download", "file-text", "filter", "flag", "flame", "flask", "focus-2", "folder", "folders", "forms", "frame", "generate", "gift", "git-branch", "github", "grid-dots", "groq", "hammer", "hand-finger", "hanger", "hash", "headphones", "headset", "heart", "heart-filled", "heart-handshake", "help-circle", "highlight", "history", "home", "hourglass", "ice-cream", "id-badge", "id-badge-2", "image", "image-remove", "images", "inbox", "infinity", "info-circle", "info-filled", "info-outline", "info-square-rounded", "inline", "inline-element", "input-search", "insert-above", "insert-below", "italic", "joystick", "json", "language", "launch", "layout", "layout-align-center", "layout-board", "layout-board-split", "layout-bottombar", "layout-bottombar-expand", "layout-cards", "layout-columns", "layout-dashboard", "layout-grid", "layout-list", "layout-navbar", "layout-rows", "layout-sidebar", "layout-sidebar-right", "leaf", "leave", "lemon", "library-photo", "lifebuoy", "link", "link-removed", "linkedin", "list", "list-check", "list-details", "list-numbers", "list-tree", "lock", "logo-js", "logo-ts", "mail", "map-2", "map-pin", "map-pins", "marker", "marker-removed", "master-detail", "math-function", "meat", "menu", "message", "message-2", "message-check", "message-circle", "message-circle-2", "message-plus", "message-star", "microphone", "microphone-slash", "mobile-device", "mood-empty", "moon", "movie", "news", "notes", "number", "ok-hand", "olist", "overage", "package", "packages", "palette", "panel-left", "panel-right", "paperclip", "pause", "pencil", "phone", "photo", "photo-scan", "photo-search", "pig-money", "pin", "pin-filled", "pin-removed", "play", "player-play", "player-track-next", "playlist-add", "plug", "plug-connected", "plus-minus", "point", "presentation", "printer", "progress-50", "progress-75", "projects", "publish", "qrcode", "quote", "read-only", "receipt", "recycle", "redo", "refresh", "remove", "remove-circle", "repeat", "reset", "restore", "retrieve", "retry", "revert", "robot", "rocket", "rosette", "route", "ruler", "ruler-measure", "salad", "scale", "schema", "school", "search", "section", "select", "send", "server", "settings", "share", "shield-check", "shield-lock", "shopping-bag", "shopping-cart", "shopping-cart-plus", "signature", "sitemap", "slideshow", "sort", "sort-descending", "spacing-vertical", "sparkle", "sparkles", "speakerphone", "spinner", "split-horizontal", "split-vertical", "square", "stack", "stack-2", "stack-compact", "stairs", "stairs-up", "star", "star-filled", "stars", "stop", "strikethrough", "string", "subtask", "sun", "superscript", "sync", "table", "table-options", "tablet-device", "tag", "tags", "target", "task", "template", "tent", "terminal", "terminal-2", "text", "th-large", "th-list", "thumb-up", "thumbs-down", "thumbs-up", "ticket", "tiers", "timeline", "toggle-arrow-right", "toggle-right", "token", "tool", "tools-kitchen-2", "transfer", "translate", "trash", "trend-upward", "triangle-outline", "trolley", "truck", "truck-delivery", "truncate", "twitter", "typography", "ulist", "unarchive", "underline", "undo", "unknown", "unlink", "unlock", "unpublish", "upload", "user", "user-circle", "user-plus", "user-search", "user-star", "users", "users-group", "versions", "video", "vocabulary", "vs", "warning-filled", "warning-outline", "weight", "world", "wrench", "zoom-question"];
 type DockIconName = (typeof DOCK_ICON_NAMES)[number];
 declare const DOCK_ICON_NAME_SET: ReadonlySet<string>;
 
+/**
+ * How a `number` field's value is SHOWN: `config.format` on the field.
+ *
+ * An imported site shows `$1,299.00`, `38%`, `12,000+`, `4 900 €`. The value an author edits and
+ * Delivery returns is the number (`1299`, `38`, `12000`, `4900`); everything around the digits is
+ * presentation, read once off the built page and kept here. The contract both halves hold:
+ *
+ *   formatNumber(parseNumberText(text).value, parseNumberText(text).format) === text
+ *
+ * so a page nobody edited is published byte for byte, and an edited value is shown the way the
+ * site showed the old one. `parseNumberText` answers null for anything it cannot give back
+ * exactly, and that text stays a text field.
+ *
+ * Pure, and in this package because three programs read it: the import (parse), the publish
+ * writers (format) and the dashboard's number input (format, for the preview beside the box).
+ */
+/** `config.format` of a `number` field. Every key optional; absent = none. */
+interface NumberFieldFormat {
+    /** Shown before the digits: `$`, `€ `, `+`, `(`, `~`. */
+    prefix?: string;
+    /** Shown after the digits: `%`, `+`, `k`, ` / month`, ` €`, `)`. */
+    suffix?: string;
+    /** Thousands separator: `,` `.` ` ` (also no-break and narrow no-break space) `'`. `""` or absent = none. */
+    group?: string;
+    /** Decimal mark, `.` unless the site writes `,`. */
+    decimal?: "." | ",";
+    /** Fraction digits always shown (`2` for `£3.20`). A value with more keeps its own, up to six. */
+    decimals?: number;
+}
+/** The format a stored `config.format` holds, with anything malformed dropped: a bad row never throws at publish. */
+declare function readNumberFormat(raw: unknown): NumberFieldFormat;
+/** The number as the site shows it. A value that is no finite number prints as nothing. */
+declare function formatNumber(value: number, format?: NumberFieldFormat): string;
+/**
+ * A text that is ONE number and its presentation, or null.
+ *
+ * Null, on purpose, for: words around the number (`From £2,400`, `3 products`), a leading zero
+ * (`01`, `007`: a step marker, a code), digits grouped any other way than in threes (a phone
+ * number), two decimal marks (`1.2.3`), a minus (a dash is as often an ornament), an ordinal, and
+ * anything `formatNumber` would not print back exactly.
+ *
+ * `lang` (a BCP 47 tag) settles the one ambiguity, `1.234` and `1,234`, and names the thousands
+ * mark of a number too short to show one. `machine`: an attribute a script reads (`data-target`),
+ * which is plain digits and stays so.
+ */
+declare function parseNumberText(text: string, opts?: {
+    lang?: string | null;
+    machine?: boolean;
+}): {
+    value: number;
+    format: NumberFieldFormat;
+} | null;
+
+/** Longest `description` a choice option may carry: one line under its label (V2's longest is 71). */
+declare const OPTION_DESCRIPTION_MAX = 140;
+/**
+ * One choice of a select / multiselect / tags field or prop. Values are judged by `value` alone;
+ * `icon` (a dock icon name, bettercms://icons/dock) and `description` (one line under the label)
+ * are editor chrome. A bare string is a choice whose label is its value.
+ */
+interface ChoiceOption {
+    label: string;
+    value: string;
+    /** A `DockIconName`, typed as a string so a stored row (db `ComponentPropDef`) stays assignable. */
+    icon?: string;
+    description?: string;
+}
 /**
  * ContentModel — the structured content model (schema) for a workspace.
  * Defines which content fields are available for authors to fill in.
@@ -48,7 +116,7 @@ interface ContentModel {
  * 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" | "button" | "multiselect" | "icon";
+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" | "button" | "multiselect" | "icon" | "object" | "tags" | "rating" | "code" | "video" | "table" | "slot";
 type ContentModelKind = "model" | "block";
 /**
  * How a fieldset renders in the dock. ABSENT ≡ today's flat list (V2): a legacy `{id, name}`
@@ -69,6 +137,11 @@ interface UiBefore {
     position: number;
     label?: string;
     helpText?: string;
+    /** The V2 editor keys, snapshotted with the rest so a Revert restores them. */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    openMode?: OpenMode;
 }
 /**
  * A fieldset's chrome before the first agent change over a human/derived (or unstamped) state,
@@ -82,6 +155,9 @@ interface FieldsetUiBefore {
         tab?: string;
         icon?: DockIconName;
         collapsed?: boolean;
+        collapsible?: boolean;
+        columns?: 1 | 2;
+        layout?: "stack" | "breakpoints";
     };
     /** Its index among the model's fieldsets before the agent's change; absent on older snapshots. */
     position?: number;
@@ -98,6 +174,12 @@ interface Fieldset {
     collapsed?: boolean;
     /** A group/row that sits inside this `kind:"tab"` fieldset. */
     tab?: string;
+    /** `false`: a static heading with no toggle. */
+    collapsible?: boolean;
+    /** `2`: short fields side by side. */
+    columns?: 1 | 2;
+    /** `breakpoints`: its per-screen-size `object` fields (desktop, tablet, phone; joined by `fieldsetId`) shown as ONE group with a switcher. */
+    layout?: "stack" | "breakpoints";
     uiOrigin?: UiOrigin;
     uiBefore?: FieldsetUiBefore;
 }
@@ -119,24 +201,34 @@ interface ArrayZoneConfig {
 }
 /** 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";
+    /**
+     * primitive array: list of scalars, or of images, links or rich text (V2 `array` of one
+     * primitive), each item judged by its own type's validator.
+     */
+    itemType?: "text" | "number" | "date" | "image" | "link" | "richtext";
     /** nested array: zoned fields (recursive) */
     zones?: ArrayZoneConfig;
     /** reference / multi-reference */
     contentModelId?: string;
     min?: number;
     max?: number;
+    /** number: how the value is shown on the site (`$1,299.00`, `38%`). @see NumberFieldFormat */
+    format?: NumberFieldFormat;
+    /** A derived field whose value lives in an ATTRIBUTE and is written there: `aria-label`, or the `data-target` a count-up script reads. */
+    attr?: string;
     /** date / datetime */
     includeTime?: boolean;
     /**
-     * date / datetime with a time: "site" (the project's own zone) or an IANA zone name. When set,
-     * a stored value must carry `Z` or a numeric offset, so it names one instant in every region.
+     * date / datetime with a time: "site" (the project's own zone), an IANA zone name, or V2 `true`
+     * (the editor picks a zone) / `false` (no zone, ≡ absent). When set (not false), a stored value
+     * must carry `Z` or a numeric offset, so it names one instant in every region.
      */
-    timezone?: string;
-    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
+    timezone?: string | boolean;
+    /** modular / slot: SLUGS of the kind='block' models this field accepts. Non-empty. */
     blockSlugs?: string[];
-    /** modular: bounds on how many block instances the field may hold. */
+    /** slot: per-child layout settings, what each child's `_settings` holds (leaf fields). */
+    slotSettings?: ContentModelField[];
+    /** modular: bounds on how many block instances the field may hold; a primitive array (itemType): how many items. */
     minItems?: number;
     maxItems?: number;
     /**
@@ -172,6 +264,21 @@ interface FieldConfig {
     zoneId?: string;
     /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
     legacyResolved?: boolean;
+    /** number: a V2 scale (stepped range, numeric or token steps, units, presets, custom escape hatch). */
+    scale?: NumberScale;
+    /** number: V2 `numeric.unit`, what it counts ("%", "USD", "days"), shown beside the input. 1–24 chars. */
+    unit?: string;
+    /** number: V2 `validation.min / max`, the error bounds; they win over `min` / `max` (the input's range). */
+    validation?: {
+        min?: number;
+        max?: number;
+    };
+    /** text / longtext / richtext: length in characters (richtext: its plain text). */
+    minLength?: number;
+    maxLength?: number;
+    /** text / longtext: a regex (≤ 200 characters) and the message shown when a value does not match it. */
+    pattern?: string;
+    patternMessage?: string;
     legacyMappings?: Record<string, string>;
     /**
      * image: `"icon"` marks an inline SVG icon the import derived (its value a `data:image/svg+xml`
@@ -179,8 +286,52 @@ interface FieldConfig {
      * and the field-pruning guards leave it alone: an icon is editable content, never markup to tidy.
      */
     media?: "icon";
+    /** multiselect / tags: the choices (tags: suggestions unless allowCustom is false). */
+    options?: Array<string | ChoiceOption>;
     [key: string]: unknown;
 }
+type ScaleUnit = "px" | "%" | "rem" | "em" | "vw" | "vh";
+/** A V2 scale's custom value: a number in one of the scale's units. */
+interface ScaleCustomValue {
+    value: number;
+    unit: ScaleUnit;
+}
+/**
+ * A number field's `config.scale` (V2 scale.ts, CPO D41). The value a field with a scale stores is
+ * a bare number (range or numeric steps), a token step's string value, or a {@link ScaleCustomValue}
+ * when `allowCustom` is set (within its bounds).
+ */
+interface NumberScale {
+    steps: {
+        min: number;
+        max: number;
+        step?: number;
+    } | Array<{
+        value: number;
+        label?: string;
+    }> | Array<{
+        value: string;
+        label: string;
+        title?: string;
+        px?: number;
+        css?: string;
+    }>;
+    units?: ScaleUnit[];
+    defaultUnit?: ScaleUnit;
+    /** Fixed values only (false, absent) or fixed + custom: `true`, or the custom value's bounds. */
+    allowCustom?: boolean | {
+        min?: number | Partial<Record<ScaleUnit, number>>;
+        max?: number | Partial<Record<ScaleUnit, number>>;
+        units?: ScaleUnit[];
+        step?: number;
+    };
+    presets?: Array<{
+        label?: string;
+        value: number | string | ScaleCustomValue;
+    }>;
+}
+/** V2: how a compound field (an `object`, or an array's rows) opens when edited. Editor-only. */
+type OpenMode = "inline" | "drill" | "popover" | "dialog";
 /**
  * Where a field renders in the entry editor.
  *
@@ -213,7 +364,8 @@ type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inli
  */
 interface ShowIfRule {
     field: string;
-    op: "eq" | "neq" | "in" | "isSet";
+    /** `notEmpty` ≡ `isSet`; `empty` passes while the source holds nothing. Neither reads `value`. */
+    op: "eq" | "neq" | "in" | "isSet" | "notEmpty" | "empty";
     value?: string | string[];
 }
 interface ShowIf {
@@ -233,9 +385,20 @@ interface ContentModelField {
      */
     unique?: boolean;
     defaultValue?: unknown;
-    options?: string[];
+    /** select: the choices (multiselect / tags keep theirs on `config.options`). */
+    options?: Array<string | ChoiceOption>;
     /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
     config?: FieldConfig | null;
+    /** `object`: its child fields. */
+    fields?: ContentModelField[];
+    /** `object` / `array`: how the value (or each row) opens when edited. */
+    openMode?: OpenMode;
+    /** Longer help behind the ⓘ next to the label. Editor-only. */
+    helpMore?: string;
+    /** Tuck into the closed "Advanced" section. Editor-only. */
+    advanced?: boolean;
+    /** A soft limit the editor warns at, never a refusal. */
+    recommendedMax?: number;
     /**
      * Which fieldset this field renders under in the schema builder. Authoring-only: it is
      * never delivered and cannot move a value — see {@link Fieldset}.
@@ -258,6 +421,12 @@ interface ContentModelField {
     readOnly?: true | "developer";
     /** Which system owns the value; shown on the refusal. At most 200 characters. */
     lockReason?: string;
+    /**
+     * V2 per-field localization (the locale chip). Once any field of a schema is marked, a
+     * translation row owns only its localized values; the rest are inherited from its source, and a
+     * translation write that changes one is 409 `FIELD_NOT_LOCALIZED`. None marked: rows copy as before.
+     */
+    localized?: boolean;
     /**
      * 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}.
@@ -293,6 +462,10 @@ interface ContentModelFieldUi {
         subtitle?: string;
         /** Child field key whose value is the row's thumbnail. Type is not constrained. */
         media?: string;
+        /** A literal row label while the title child is empty ("Untitled question"). Not a key. */
+        fallback?: string;
+        /** The row's icon while it has no media (V2 `preview.icon`). */
+        icon?: DockIconName;
     };
     /**
      * How the ITEMS of a nesting field are arranged. ABSENT ≡ `"list"` — every field stored
@@ -301,7 +474,7 @@ interface ContentModelFieldUi {
      *
      * Same placement rule as {@link ContentModelFieldUi.preview}: nesting fields only.
      */
-    layout?: "list" | "grid" | "table";
+    layout?: "list" | "grid" | "table" | "rows" | "chips" | "gallery";
     /**
      * 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.
@@ -318,11 +491,39 @@ interface ContentModelFieldUi {
      * `slider` on a `number` whose config.min < config.max; `rating` on a `number` with numeric
      * config.min, max and step (stars).
      */
-    control?: "segmented" | "slider" | "rating";
+    control?: "segmented" | "slider" | "rating" | "dropdown" | "radio" | "cards" | "grid" | "switch" | "checkbox";
     /** The branch row's icon. Nesting fields only. */
     icon?: DockIconName;
-    /** What one item is called ("Slide", "Member"), 1–24 chars. Nesting fields only. */
+    /** What one item is called ("Slide", "Member"), 1–24 chars (V2 itemNoun). Nesting fields and lists. */
     itemLabel?: string;
+    /** V2 `rows`: the lines a text box opens with (1–40). text / longtext only. */
+    rows?: number;
+    /** V2 `placeholder` on a field of any type. A prop keeps its own `placeholder`. */
+    placeholder?: string;
+    /** V2 item identity on a list: the item type's own name (an identifier) and title. */
+    itemName?: string;
+    itemTitle?: string;
+    /** V2 `synced`: the value comes from a global, so an edit applies everywhere. A marker. */
+    synced?: {
+        from: string;
+    };
+    /** V2 `valueShape`: a link / image / button writes a plain string or the object. */
+    valueShape?: "string" | "object";
+    /** V2 field access (D58): who sees and who changes it. The editor gates; the backend stores. */
+    access?: {
+        view?: "schema.view";
+        edit?: "schema.manage";
+    };
+    /** V2 `hidden`: true = never shown in the form; false ≡ absent. A conditional hide is `showIf`. */
+    hidden?: boolean;
+    /**
+     * V2 per-item chrome of a `modular` field (`of[i].icon` / `preview`), by block slug: how a row
+     * of that block type reads in this field. Each slug is one of `config.blockSlugs`.
+     */
+    blocks?: Record<string, {
+        icon?: DockIconName;
+        preview?: ContentModelFieldUi["preview"];
+    }>;
     /**
      * A custom dock input, by NAME: the project's own input (built with its site, served on its
      * own inputs origin, never the dashboard's) draws this field instead of the stock control.
@@ -399,14 +600,110 @@ declare const SPACE_BOTTOM_TOKENS: ("section-space-none" | "section-space-small"
 /** `var(--bcms-<token>,<px>)`, or "" for anything that is not a known token (closed set). */
 declare function spaceTokenCss(token: unknown): string;
 
+/**
+ * A LINK VALUE: what a `link` field, a `link` prop and a button's `href` store.
+ *
+ * Two shapes, both valid forever:
+ *   - a plain href string ("/about", "https://example.com"), which is what every value stored
+ *     before the V2 link element holds;
+ *   - the V2 link object (dashboard kit `controls/link.tsx`, `LinkValue` after `finalizeLink`):
+ *     `{ type, href, title?, newTab?, target?, rel?, section?, ref? }`.
+ *
+ * `href` is always the final href the site renders (`mailto:`, `tel:`, `#anchor` included), so a
+ * reader that only wants a destination reads `href` and nothing else. `ref` is the id of the page
+ * or CMS item a `page` / `entry` link points at: the write path checks it exists and delivery
+ * resolves it like a reference. Keys the kit writes beside these (`pageId`, `entryId`, `assetId`,
+ * `anchor`, `email`, `subject`, `phone`, `label`) are kept as sent.
+ */
+/** A link's relation beyond a new tab's own `noopener noreferrer`. */
+declare const LINK_RELS: readonly ["nofollow", "sponsored", "ugc"];
+type LinkRel = (typeof LINK_RELS)[number];
+/**
+ * What a link points at. `section` is the kit's spelling of `anchor` (a `#fragment` on the page);
+ * both are accepted and stored as sent.
+ */
+declare const LINK_VALUE_TYPES: readonly ["url", "page", "entry", "email", "phone", "anchor", "section", "file"];
+type LinkValueType = (typeof LINK_VALUE_TYPES)[number];
+interface LinkValue {
+    type?: LinkValueType;
+    href: string;
+    title?: string;
+    newTab?: boolean;
+    /** Legacy mirror of `newTab`; must agree with it. */
+    target?: "_self" | "_blank";
+    /** Absent = a normal link (the kit's "follow" is dropped on write). */
+    rel?: LinkRel;
+    /** The `#anchor` on the target page. */
+    section?: string;
+    /** The page id (`type: "page"`) or entry id (`type: "entry"`) this link points at. */
+    ref?: string;
+}
+/** A link object (`{ href: string, … }`), as opposed to a plain href string. */
+declare function isLinkObject(value: unknown): value is LinkValue & Record<string, unknown>;
+/** A link value's destination: the string itself, or the object's `href`. Null for anything else. */
+declare function linkHref(value: unknown): string | null;
+/** The page or entry a `page` / `entry` link points at, or null. Reads `ref`, then the kit's `pageId` / `entryId`. */
+declare function linkRefOf(value: unknown): {
+    kind: "page" | "entry";
+    id: string;
+} | null;
+/** `javascript:`, `data:` and `vbscript:`, also behind the control characters a URL parser strips. */
+declare const isScriptHref: (href: string) => boolean;
+/**
+ * Why a link OBJECT is not a link value, or null when it is. The href's own grammar (which schemes,
+ * which relative forms) is the caller's rule; this refuses only what no link may be.
+ * Messages start with `link_value_invalid:` so every surface can name the refusal.
+ */
+declare function linkValueProblem(value: unknown): string | null;
+/**
+ * A link value as it is stored: a string as sent; an object with the kit's `rel: "follow"` dropped
+ * (no rel IS a normal link), `newTab` filled from a lone `target`, a page/entry link's
+ * `pageId` / `entryId` copied to `ref`, and the read-only `resolved` dropped. Never invents a destination.
+ */
+declare function normalizeLinkValue<T>(value: T): T;
+/** What an anchor for this link value carries: its href, whether it opens a new tab, and its rel. */
+declare function linkAnchorOf(value: unknown): {
+    href: string;
+    newTab: boolean;
+    rel?: LinkRel;
+} | null;
+
 declare const BUTTON_VARIANTS: readonly ["primary", "secondary", "tertiary", "brand", "dark", "light", "outline", "link"];
 type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
 /** Each icon's inner SVG markup (viewBox `0 0 25 25`), by name. */
 declare const BUTTON_ICONS: Readonly<Record<DockIconName, string>>;
 type ButtonIcon = DockIconName;
-declare const BUTTON_ICON_NAMES: readonly ["access-denied", "activity", "add", "add-circle", "add-comment", "add-document", "add-user", "api", "archive", "arrow-down", "arrow-left", "arrow-right", "arrow-top-right", "arrow-up", "asterisk", "bar-chart", "basket", "bell", "bill", "binary-document", "block-content", "block-element", "blockquote", "bold", "bolt", "book", "bookmark", "bookmark-filled", "bottle", "bug", "bulb-filled", "bulb-outline", "calendar", "case", "chart-upward", "checkmark", "checkmark-circle", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle", "clipboard", "clipboard-image", "clock", "close", "close-circle", "code", "code-block", "cog", "collapse", "color-wheel", "comment", "component", "compose", "compose-sparkles", "confetti", "controls", "copy", "credit-card", "crop", "cube", "dashboard", "database", "desktop", "diamond", "document", "document-pdf", "document-remove", "document-sheet", "document-text", "document-video", "document-word", "document-zip", "documents", "dot", "double-chevron-down", "double-chevron-left", "double-chevron-right", "double-chevron-up", "double-quote", "download", "drag-handle", "drop", "earth-americas", "earth-globe", "edit", "ellipsis-horizontal", "ellipsis-vertical", "empty", "enter", "enter-right", "envelope", "equal", "error-filled", "error-outline", "error-screen", "expand", "eye-closed", "eye-open", "face-happy", "face-indifferent", "face-sad", "feedback", "filter", "folder", "generate", "github", "groq", "hash", "heart", "heart-filled", "help-circle", "highlight", "home", "ice-cream", "image", "image-remove", "images", "inbox", "info-filled", "info-outline", "inline", "inline-element", "insert-above", "insert-below", "italic", "joystick", "json", "launch", "leave", "lemon", "link", "link-removed", "linkedin", "list", "lock", "logo-js", "logo-ts", "marker", "marker-removed", "master-detail", "menu", "microphone", "microphone-slash", "mobile-device", "moon", "number", "ok-hand", "olist", "overage", "package", "panel-left", "panel-right", "pause", "pin", "pin-filled", "pin-removed", "play", "plug", "presentation", "progress-50", "progress-75", "projects", "publish", "read-only", "redo", "refresh", "remove", "remove-circle", "reset", "restore", "retrieve", "retry", "revert", "robot", "rocket", "schema", "search", "select", "share", "sort", "sparkle", "sparkles", "spinner", "split-horizontal", "split-vertical", "square", "stack", "stack-compact", "star", "star-filled", "stop", "strikethrough", "string", "sun", "sync", "tablet-device", "tag", "tags", "target", "task", "terminal", "text", "th-large", "th-list", "thumbs-down", "thumbs-up", "tiers", "timeline", "toggle-arrow-right", "token", "transfer", "translate", "trash", "trend-upward", "triangle-outline", "trolley", "truncate", "twitter", "ulist", "unarchive", "underline", "undo", "unknown", "unlink", "unlock", "unpublish", "upload", "user", "users", "versions", "video", "warning-filled", "warning-outline", "wrench"];
+declare const BUTTON_ICON_NAMES: readonly ["abc", "access-denied", "activity", "add", "add-circle", "add-comment", "add-document", "add-user", "address-book", "adjustments", "adjustments-horizontal", "alarm", "alert-triangle", "align-left", "api", "app-window", "apple", "apps", "archive", "arrow-back-up", "arrow-down", "arrow-guide", "arrow-left", "arrow-right", "arrow-top-right", "arrow-up", "arrows-diagonal", "arrows-down", "arrows-exchange", "arrows-horizontal", "arrows-left-right", "arrows-shuffle", "arrows-sort", "article", "aspect-ratio", "asterisk", "award", "axis-x", "backpack", "badge", "badge-cc", "badges", "bar-chart", "basket", "bell", "bill", "binary-document", "block-content", "block-element", "blockquote", "bold", "bolt", "book", "book-2", "bookmark", "bookmark-filled", "books", "bottle", "box", "brand-dribbble", "brand-facebook", "brand-instagram", "brand-linkedin", "brand-pinterest", "brand-tiktok", "brand-x", "brand-youtube", "briefcase", "broadcast", "browser", "bug", "building", "building-skyscraper", "building-store", "bulb-filled", "bulb-outline", "calculator", "calendar", "calendar-dollar", "calendar-event", "calendar-exclamation", "calendar-off", "calendar-plus", "calendar-star", "calendar-time", "camera", "campfire", "carousel-horizontal", "case", "cash", "category", "category-2", "chart-area", "chart-arrows", "chart-bar", "chart-bar-popular", "chart-donut", "chart-dots", "chart-line", "chart-upward", "check", "checkbox", "checklist", "checkmark", "checkmark-circle", "chef-hat", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "chevrons-right", "circle", "circle-check", "circle-dot", "circle-number-1", "circle-plus", "click", "clipboard", "clipboard-image", "clipboard-text", "clock", "clock-check", "clock-hour-4", "close", "close-circle", "code", "code-block", "cog", "collapse", "color-wheel", "columns", "columns-2", "columns-3", "comment", "component", "compose", "compose-sparkles", "confetti", "controls", "cookie", "copy", "credit-card", "crop", "cube", "currency-dollar", "dashboard", "database", "database-search", "desktop", "device-desktop", "device-mobile", "device-tablet", "devices", "diamond", "discount", "document", "document-pdf", "document-remove", "document-sheet", "document-text", "document-video", "document-word", "document-zip", "documents", "door-exit", "dot", "double-chevron-down", "double-chevron-left", "double-chevron-right", "double-chevron-up", "double-quote", "download", "drag-handle", "drop", "droplet", "droplet-half", "earth-americas", "earth-globe", "edit", "egg", "ellipsis-horizontal", "ellipsis-vertical", "empty", "enter", "enter-right", "envelope", "equal", "error-filled", "error-outline", "error-screen", "expand", "eye-closed", "eye-off", "eye-open", "face-happy", "face-indifferent", "face-sad", "feather", "feedback", "file", "file-certificate", "file-code", "file-download", "file-text", "filter", "flag", "flame", "flask", "focus-2", "folder", "folders", "forms", "frame", "generate", "gift", "git-branch", "github", "grid-dots", "groq", "hammer", "hand-finger", "hanger", "hash", "headphones", "headset", "heart", "heart-filled", "heart-handshake", "help-circle", "highlight", "history", "home", "hourglass", "ice-cream", "id-badge", "id-badge-2", "image", "image-remove", "images", "inbox", "infinity", "info-circle", "info-filled", "info-outline", "info-square-rounded", "inline", "inline-element", "input-search", "insert-above", "insert-below", "italic", "joystick", "json", "language", "launch", "layout", "layout-align-center", "layout-board", "layout-board-split", "layout-bottombar", "layout-bottombar-expand", "layout-cards", "layout-columns", "layout-dashboard", "layout-grid", "layout-list", "layout-navbar", "layout-rows", "layout-sidebar", "layout-sidebar-right", "leaf", "leave", "lemon", "library-photo", "lifebuoy", "link", "link-removed", "linkedin", "list", "list-check", "list-details", "list-numbers", "list-tree", "lock", "logo-js", "logo-ts", "mail", "map-2", "map-pin", "map-pins", "marker", "marker-removed", "master-detail", "math-function", "meat", "menu", "message", "message-2", "message-check", "message-circle", "message-circle-2", "message-plus", "message-star", "microphone", "microphone-slash", "mobile-device", "mood-empty", "moon", "movie", "news", "notes", "number", "ok-hand", "olist", "overage", "package", "packages", "palette", "panel-left", "panel-right", "paperclip", "pause", "pencil", "phone", "photo", "photo-scan", "photo-search", "pig-money", "pin", "pin-filled", "pin-removed", "play", "player-play", "player-track-next", "playlist-add", "plug", "plug-connected", "plus-minus", "point", "presentation", "printer", "progress-50", "progress-75", "projects", "publish", "qrcode", "quote", "read-only", "receipt", "recycle", "redo", "refresh", "remove", "remove-circle", "repeat", "reset", "restore", "retrieve", "retry", "revert", "robot", "rocket", "rosette", "route", "ruler", "ruler-measure", "salad", "scale", "schema", "school", "search", "section", "select", "send", "server", "settings", "share", "shield-check", "shield-lock", "shopping-bag", "shopping-cart", "shopping-cart-plus", "signature", "sitemap", "slideshow", "sort", "sort-descending", "spacing-vertical", "sparkle", "sparkles", "speakerphone", "spinner", "split-horizontal", "split-vertical", "square", "stack", "stack-2", "stack-compact", "stairs", "stairs-up", "star", "star-filled", "stars", "stop", "strikethrough", "string", "subtask", "sun", "superscript", "sync", "table", "table-options", "tablet-device", "tag", "tags", "target", "task", "template", "tent", "terminal", "terminal-2", "text", "th-large", "th-list", "thumb-up", "thumbs-down", "thumbs-up", "ticket", "tiers", "timeline", "toggle-arrow-right", "toggle-right", "token", "tool", "tools-kitchen-2", "transfer", "translate", "trash", "trend-upward", "triangle-outline", "trolley", "truck", "truck-delivery", "truncate", "twitter", "typography", "ulist", "unarchive", "underline", "undo", "unknown", "unlink", "unlock", "unpublish", "upload", "user", "user-circle", "user-plus", "user-search", "user-star", "users", "users-group", "versions", "video", "vocabulary", "vs", "warning-filled", "warning-outline", "weight", "world", "wrench", "zoom-question"];
 /** A stored variant as it renders: anything off the list is Primary. */
 declare function buttonVariantOf(value: unknown): ButtonVariant;
+/**
+ * How an IMPORTED site draws one look of its Button family: the classes its own stylesheet PAINTS
+ * the look by, the `data-variant` it keys the look on when it uses one, and the paint classes of
+ * every other spelling of the same look (`also`), which a publish takes off the anchor with the rest.
+ * A look comes in sizes: `size` are the classes that size its most-used spelling and `sizeAlso`
+ * those of the others. A publish leaves a button's size classes on it and adds `size` only to a
+ * button that has none. Measured from the built site and stored on the look's button block as
+ * `props.siteLook`.
+ */
+interface ButtonSiteLook {
+    classes: string[];
+    attrs?: {
+        "data-variant"?: string;
+    };
+    also?: string[];
+    size?: string[];
+    sizeAlso?: string[];
+}
+/** A button block's `props.siteLook`, read defensively: null when it names nothing to paint with. */
+declare function buttonSiteLookOf(value: unknown): ButtonSiteLook | null;
+/**
+ * The value a `button` stores to pick one look of the project's Button family: what the site's own
+ * `data-variant` calls the look when it keys on one, the look's component slug otherwise. A
+ * publish writes it back as the anchor's `data-variant`.
+ */
+declare function buttonLookValue(slug: string, siteLook: ButtonSiteLook | null): string;
+/** Is this a value that could name a family look (or one of the fixed names)? */
+declare function isButtonLookValue(value: unknown): value is string;
 /** A stored icon as it renders: anything off the list is no icon. */
 declare function buttonIconOf(value: unknown): ButtonIcon | null;
 /** One icon as inline SVG sized to the button's text, hidden from assistive tech (the label names the button). */
@@ -418,8 +715,6 @@ type ButtonSizeName = (typeof BUTTON_SIZES)[number];
  * object. Only `label` and `href` are required; every look key is optional and absent reads as
  * today's default (Primary, medium, no arrow, no icon, same tab).
  */
-declare const LINK_RELS: readonly ["nofollow", "sponsored", "ugc"];
-type LinkRel = (typeof LINK_RELS)[number];
 /**
  * The target and rel attributes of an anchor, as one string. A new tab keeps the `noopener
  * noreferrer` pair; a link relation joins it in the SAME rel attribute, so an anchor never
@@ -428,7 +723,8 @@ type LinkRel = (typeof LINK_RELS)[number];
 declare function anchorTargetRel(newTab: boolean, rel?: unknown): string;
 interface ButtonValue {
     label: string;
-    href: string;
+    /** A plain href, or a link object (@see LinkValue) whose newTab / rel apply when the button sets none. */
+    href: string | LinkValue;
     variant?: ButtonVariant;
     size?: ButtonSizeName;
     arrow?: boolean;
@@ -438,11 +734,17 @@ interface ButtonValue {
     rel?: LinkRel;
 }
 /** A stored button value as it renders: `rel` stays optional, every other key is filled. */
-type ReadButtonValue = Required<Omit<ButtonValue, "rel">> & Pick<ButtonValue, "rel">;
+type ReadButtonValue = Required<Omit<ButtonValue, "rel" | "href">> & Pick<ButtonValue, "rel"> & {
+    href: string;
+};
 /** A stored button value as it renders: every key read through the same allow-lists as a block. */
 declare function readButtonValue(value: unknown): ReadButtonValue;
-/** Why a value is not a button, or null when it is. Look keys are checked only when present. */
-declare function buttonValueProblem(value: unknown): string | null;
+/**
+ * Why a value is not a button, or null when it is. Look keys are checked only when present.
+ * `looks` are the values that pick a look of the project's own Button family (@see
+ * buttonLookValue): a variant is one of those or one of the fixed names.
+ */
+declare function buttonValueProblem(value: unknown, looks?: ReadonlySet<string>): string | null;
 /** The look keys an instance of a Button component may override, beside its label and link. */
 declare const BUTTON_LOOK_KEYS: readonly ["variant", "size", "arrow", "icon", "newTab"];
 type ButtonLookKey = (typeof BUTTON_LOOK_KEYS)[number];
@@ -721,8 +1023,11 @@ interface ImageBlock {
 interface ButtonProps {
     text: string;
     href: string;
-    /** Absent or off the list ⇒ "primary". Renders `bcms-btn-{variant}`. */
-    variant?: ButtonVariant;
+    /**
+     * One of the fixed names, which render `bcms-btn-{variant}`, or the value of a look of the
+     * project's own Button family (@see buttonLookValue). Absent ⇒ "primary".
+     */
+    variant?: ButtonVariant | (string & {});
     /** Padding + font-size step. Absent ⇒ "md", today's button. sm/lg render `bcms-btn-sm|lg`. */
     size?: "sm" | "md" | "lg";
     /** Stretch to the column's width. Absent ⇒ false. true renders `bcms-btn-full`. */
@@ -1342,7 +1647,9 @@ declare const FOOTER_SECTION_ID: "footer";
 
 type LayoutZone = "above-page-content" | "below-page-content";
 type ReservedLayoutSection = "navigation" | "footer";
-type LayoutScalarFieldType = "text" | "longtext" | "richtext" | "number" | "toggle" | "date" | "image" | "file" | "link" | "email" | "phone" | "select" | "color" | "json" | "reference" | "multi-reference";
+type LayoutScalarFieldType = "text" | "longtext" | "richtext" | "number" | "toggle" | "date" | "image" | "file" | "link"
+/** A call to action as one value, `{ label, href, variant? }`: what a page's `button` field holds. */
+ | "button" | "email" | "phone" | "select" | "color" | "json" | "reference" | "multi-reference";
 type LayoutFieldType = LayoutScalarFieldType | "group" | "repeater";
 /** A recursive, stable-ID field contract shared by Sections and variant inputs. */
 interface LayoutFieldDefinition {
@@ -1676,7 +1983,15 @@ interface DeliveredLayout {
             id: string;
             kind: "field";
             fieldId: string;
+            /** The stored value, unchanged. */
             value: unknown;
+            /**
+             * Present only when the field holds references: `value` with them hydrated (depth 1),
+             * as Delivery serves an entry's (an entry → `{ id, slug, title, data, … }`, a page /
+             * form / collection target → `{ kind, id, title, slug, url }`). A published read
+             * resolves published targets only; one that did not resolve stays as stored.
+             */
+            resolved?: unknown;
         } | {
             id: string;
             kind: "component";
@@ -1752,7 +2067,7 @@ declare function visibleDeliveredLayout<T extends DeliveredLayout | null | undef
  *
  * A constant rather than three paraphrases, because updating some of them is exactly how this happened.
  */
-declare const 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. An IMPORTED site's components are its own (read the repo); its nav, footer and modals are the Layout. On a blank site, 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.";
+declare const 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. An IMPORTED site's components are its own (read the repo); its nav, footer and modals are the Layout. On a blank site, 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 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 it with create_component `from` 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.";
 type ComponentCategory = "navbar" | "footer" | "button" | "section" | "slider" | "tabs" | "form" | "custom" | "hero" | "content" | "social-proof" | "conversion";
 /**
  * A single overridable field on a component. `target` points at the block + JSON
@@ -1771,7 +2086,7 @@ type ComponentCategory = "navbar" | "footer" | "button" | "section" | "slider" |
  *
  * 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", "link", "button", "date", "color", "file", "icon", "multiselect"];
+declare const COMPONENT_PROP_TYPES: readonly ["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot", "form", "link", "button", "date", "color", "file", "icon", "multiselect", "object", "datetime", "slug", "email", "phone", "json", "location", "tags", "rating", "code", "reference", "multi-reference", "video", "array", "longtext"];
 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
@@ -1817,7 +2132,11 @@ interface ComponentPropDef {
      *   number → a number (heading.level, columns.count)
      *   select → one string from `config.options`
      *   group  → an object keyed by `config.fields`
-     *   table  → an array of such objects (slider.slides)
+     *   table  → an array of such objects (slider.slides); with `config.mode: "data"` instead ONE
+     *            V2 `TableValue` (typed, keyed columns × keyed rows, table-value.ts), the value a
+     *            `table` FIELD stores. Aimed at a text or richtext block's `props.html` it renders
+     *            as the semantic HTML table. With `config.mode: "types"` a V2 polymorphic list: rows of
+     *            several item types (`config.itemTypes`), each row naming its type in `_type`.
      *   link   → an href string (URL, internal path or #fragment)
      *   button → ONE `ButtonValue` (button-look.ts): label, href and look as a unit, never a text prop plus
      *            a url prop that drift apart. Targets the `props` of a `button` block.
@@ -1826,9 +2145,19 @@ interface ComponentPropDef {
      *   file   → `{ url, name?, size? }`, or a bare URL string
      *   icon   → a BetterCMS icon name (`DOCK_ICON_NAMES`), or an uploaded icon as an image value
      *   multiselect → a `string[]`, each one of `config.options`
-     *
-     * `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.
+     *   object → ONE `{ [childKey]: value }` keyed by `config.fields` (the V2 model-field `object`)
+     *   datetime · slug · email · phone · json · location → what the same-named model FIELD stores
+     *   tags · rating · code → what the same-named model FIELD stores (a string[], a number,
+     *            `{ language?, code }` or a string)
+     *   reference · multi-reference → what the same-named model FIELD stores: an entry id, or a
+     *            list of them (`config.contentModelId`, or `polymorphic` + `allowedModelSlugs`;
+     *            `min`/`max` on the list). Delivery and preview hydrate the ids in a page's overrides
+     *            to entries at the read's `depth`; a plain-text slot renders the entry's title.
+     *   video  → a URL string or `{ url, poster?, autoplay?, loop?, transcript? }` (the video
+     *            block's props; aimed at a video block it lands as them) @see VideoValue
+     *   array  → a list of `config.itemType` values: text, number, date, image, link or richtext
+     *            (the model field's primitive `array`; a list of objects is a `table`)
+     *   longtext → a multi-line string (the model field `longtext`; `text` is one line)
      */
     type: ComponentPropType;
     defaultValue?: unknown;
@@ -1853,12 +2182,25 @@ interface ComponentPropDef {
      * key) hold these values. The save schema refuses a key no prop of the component declares.
      */
     showIf?: ShowIf;
+    /** V2 editor-only keys, as on a model field. @see ContentModelField.helpMore */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    /**
+     * F1.x: a list prop's items (a table's rows) distinct; on a table sub-field, no two rows share
+     * the value. Refused (`unique_prop_scope`) on a top-level scalar: nothing to be unique across.
+     */
+    unique?: boolean;
+    /** `object` / `group` / `table`: how the value (or each row) opens when edited. */
+    openMode?: OpenMode;
     /**
      * The content-model field's `readOnly` / `lockReason` pair, as STORED MARKERS only: the
      * editor may render the prop read-only, and no write of a prop value is refused for them.
      */
     readOnly?: true | "developer";
     lockReason?: string;
+    /** V2 per-field localization (the locale chip): a stored marker, as on a model field. */
+    localized?: boolean;
     /** Per-type settings; the save schema enforces that each is present on the type needing it. */
     config?: {
         /** `slot` — a pick allowlist. */
@@ -1868,20 +2210,52 @@ interface ComponentPropDef {
         /** `slot` with `multiple` — bounds on the list. `maxItems` defaults to {@link SLOT_MAX_ITEMS}. */
         minItems?: number;
         maxItems?: number;
+        /**
+         * `slot` — per-child layout settings (V2 `slotSettings`, e.g. a bento span): what a V2 child's
+         * `_settings` holds (`{ _key, _type, _settings, ...props }`, slot-child.ts). Leaf sub-fields.
+         */
+        slotSettings?: ComponentSubField[];
+        /**
+         * `table` with `mode: "types"` — a V2 polymorphic list: each row is ONE of these item types,
+         * named by the row's `_type` (`{ _key?, _type, ...values }`), its values keyed by that type's `fields`.
+         */
+        itemTypes?: Array<{
+            name: string;
+            label?: string;
+            fields: ComponentSubField[];
+        }>;
         /**
          * `select` / `multiselect` — the choices. Required, and a default must be one of them. `{ label, value }`
          * when the stored value is not what an author should read (a component id, for instance).
          */
-        options?: Array<string | {
-            label: string;
-            value: string;
-        }>;
-        /** `group` / `table` — the sub-shape, nestable to 3 levels. */
+        options?: Array<string | ChoiceOption>;
+        /** `group` / `table` / `object` — the sub-shape; 10 levels at most, counting the prop (MAX_FIELD_DEPTH). */
         fields?: ComponentSubField[];
-        /** `number` — bounds for the control. */
+        /**
+         * `table` — which value it holds: `"rows"` (the default, an array of `fields` rows) or
+         * `"data"` (one V2 TableValue, with the table field's options beside it: columnTypes,
+         * lockColumns, minRows, maxRows, maxColumns, requireCaption, …). A data table has no `fields`.
+         */
+        mode?: "rows" | "data" | "types";
+        /** `number` — bounds for the control; `multiselect` / `tags` / `multi-reference` — how many items. */
         min?: number;
         max?: number;
         step?: number;
+        /** `number` — V2 `validation.min / max`: the error bounds, which win over `min` / `max`. */
+        validation?: {
+            min?: number;
+            max?: number;
+        };
+        /** `text` / `url` / `richtext` — length in characters (richtext: its plain text). */
+        minLength?: number;
+        maxLength?: number;
+        /** `text` / `url` — a regex (≤ 200 characters) and the message shown when it does not match. */
+        pattern?: string;
+        patternMessage?: string;
+        /** `reference` / `multi-reference` — the target model, or `polymorphic` with an allowlist of model slugs. */
+        contentModelId?: string;
+        polymorphic?: boolean;
+        allowedModelSlugs?: string[];
     } & Record<string, unknown>;
     /**
      * AUTHORING CHROME — the same object a content-model FIELD carries ({@link ContentModelFieldUi}),
@@ -1914,12 +2288,18 @@ interface PropGroup {
     kind?: Exclude<FieldsetKind, "tab">;
     icon?: DockIconName;
     collapsed?: boolean;
+    /** V2 fieldset keys (CPO D45), on the defining prop: a line under the header (≤200), members side by side, a static header, a breakpoint switcher, and its place among the groups (0–99; absent = where its first prop sits). */
+    description?: string;
+    columns?: 1 | 2;
+    collapsible?: boolean;
+    layout?: "stack" | "breakpoints";
+    order?: number;
 }
 /** A prop's `ui`: the field-lane chrome plus its inline {@link PropGroup}. */
 type ComponentPropUi = ContentModelFieldUi & {
     group?: PropGroup;
 };
-/** One field inside a `group` prop or a `table` row. Recursive, capped at 3 levels deep. */
+/** One field inside a `group` / `object` prop or a `table` row. Recursive, 10 levels at most counting the prop (MAX_FIELD_DEPTH). */
 interface ComponentSubField {
     key: string;
     label: string;
@@ -1931,8 +2311,23 @@ interface ComponentSubField {
     helpText?: string;
     helpSource?: "auto" | "human" | "agent";
     placeholder?: string;
-    options?: string[];
-    /** CANONICAL. A nested `group`/`table`'s own sub-shape. */
+    options?: Array<string | ChoiceOption>;
+    /** The V2 editor keys, one level down. `showIf` names SIBLING sub-fields. @see ComponentPropDef */
+    helpMore?: string;
+    advanced?: boolean;
+    recommendedMax?: number;
+    /** On a table's sub-field: no two rows share the value; on a list: no item repeats. */
+    unique?: boolean;
+    openMode?: OpenMode;
+    showIf?: ShowIf;
+    /** The prop's `ui`, inline group included: V2 fieldsets nest, so sub-fields group too. */
+    ui?: ComponentPropUi;
+    /** V2 sub-field read-only / developer lock: stored markers, as on the prop. `"developer"` needs a lockReason. */
+    readOnly?: true | "developer";
+    lockReason?: string;
+    /** V2 per-field localization: a stored marker, as on the prop. */
+    localized?: boolean;
+    /** CANONICAL. A nested `group`/`table`/`object`'s own sub-shape. */
     fields?: ComponentSubField[];
     /**
      * A READ-ONLY MIRROR of `options`/`fields`, in the shape `ComponentPropDef` puts them in.
@@ -1950,7 +2345,7 @@ interface ComponentSubField {
      */
     config?: {
         fields?: ComponentSubField[];
-        options?: string[];
+        options?: Array<string | ChoiceOption>;
     } & Record<string, unknown>;
 }
 /** The value a `slot` prop holds — the draft half of a `component-ref`, deliberately. */
@@ -2063,6 +2458,66 @@ interface DeliveryComponent {
     props: ComponentPropDef[];
 }
 
+/**
+ * V2 slot children (DESIGN.md, V2 `engine/slot.tsx`): blocks inside a block, stored INLINE as
+ * `{ _key, _type, _variant?, _settings?, ...values }`. The block's own values sit at the child's
+ * root, beside four reserved keys:
+ *
+ *   _key       the child's stable identity (reorders, diffs, React keys). Unique in its slot.
+ *   _type      the block type: a `kind: 'block'` model's SLUG on a model's `slot` field, a
+ *              component's ID on a `slot` prop.
+ *   _variant   a block variant (layout) name. Model slots only: a component variant is its own
+ *              component in BetterCMS, so a prop slot names it in `_type`.
+ *   _settings  per-child layout settings, keyed by the slot's `slotSettings`.
+ *
+ * The same `_key` / `_type` pair discriminates the items of a polymorphic list prop (a `table` prop
+ * with `config.mode: "types"`): `_type` names one of its `config.itemTypes`.
+ *
+ * Pure: shape only. Whether a block type exists, is allowed, and whether a child's values fit it,
+ * is the caller's (it knows the block models or the components).
+ */
+/** The reserved keys of a slot child; every other key is one of the block's own values. */
+declare const SLOT_CHILD_KEYS: readonly ["_key", "_type", "_variant", "_settings"];
+/** One block inside a V2 slot. @see SLOT_CHILD_KEYS */
+interface SlotChild {
+    _key: string;
+    _type: string;
+    _variant?: string;
+    _settings?: Record<string, unknown>;
+    [value: string]: unknown;
+}
+/** Is this a V2 slot child (an object naming its block type in `_type`)? */
+declare const isSlotChild: (v: unknown) => v is SlotChild;
+/** A slot child's own values: everything but the reserved keys (a new object; the values are shared). */
+declare function slotChildValues(child: Record<string, unknown>): Record<string, unknown>;
+type SlotShapeProblem = {
+    path: Array<string | number>;
+    code: string;
+    message: string;
+};
+type SlotShapeOptions = {
+    /** Bounds on the list. `max` is clamped by the caller's hard cap. */
+    min?: number;
+    max?: number;
+    /** Does the slot declare `slotSettings`? A `_settings` is refused without them. */
+    settings?: boolean;
+    /** May a child name a `_variant`? (model slots yes, prop slots no) */
+    variants?: boolean;
+    /** What the list is called in messages ("Body", "slot 'cards'"). */
+    label?: string;
+    /** What `_type` names, for messages ("a block model slug", "a component id"). */
+    typeNoun?: string;
+};
+/**
+ * Why a value cannot be a slot's list of children, each at its path inside the value (`[2, "_key"]`),
+ * codes first in each message. Shape only: a list of objects, each with a non-empty `_key` (unique)
+ * and `_type`, `_variant` a string where allowed, `_settings` an object where declared, no other
+ * `_`-prefixed key (a typo'd reserved key would otherwise be stored as a value nothing reads).
+ */
+declare function slotShapeProblems(value: unknown, opts?: SlotShapeOptions): SlotShapeProblem[];
+/** `rows[2]._key`-style path text for a problem path. */
+declare const slotPathString: (path: Array<string | number>) => string;
+
 /**
  * The dock's click budget, as ONE pure function both ends read (V9): the backend's next-steps
  * rules call it on live data, and the dashboard's reach test measures its RENDERED dock against the
@@ -2232,6 +2687,210 @@ declare function derivedPairs(candidates: readonly ButtonLinkCandidate[]): Map<n
 /** Every unambiguous pair in one sibling list, as `[textIndex, linkIndex]`, in list order. */
 declare function buttonLinkPairs(candidates: readonly ButtonLinkCandidate[]): Array<[number, number]>;
 
+/**
+ * The V2 video value (DESIGN.md §6.2, §8.15): a pasted provider link or a file URL, as a bare
+ * string or as `{ url, poster?, autoplay?, loop?, transcript? }`.
+ *
+ * The object's keys are the `video` block's own props (`VideoProps`, block.ts), so a video prop
+ * aimed at a video block lands as that block's props unchanged, and a video field renders the way
+ * the block does. Any other key is refused by name (`video_value_invalid`), never dropped.
+ */
+/** The keys a video object may carry: exactly the `video` block's props. */
+declare const VIDEO_VALUE_KEYS: readonly ["url", "poster", "autoplay", "loop", "transcript"];
+/** A video value's object form. A bare string is the same value with only `url`. */
+interface VideoValue {
+    url: string;
+    poster?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    transcript?: string;
+}
+/** Same cap as the video block's transcript (CPO-093). */
+declare const VIDEO_TRANSCRIPT_MAX = 100000;
+/** The url a video value plays, or null when it holds none (a bare string is its url). */
+declare function videoUrlOf(value: unknown): string | null;
+/** Why `value` is not a video value, or null when it is. Every message starts `video_value_invalid:`. */
+declare function videoValueProblem(value: unknown): string | null;
+
+declare const TABLE_COLUMN_TYPES: readonly ["text", "number", "money", "boolean", "rating", "link", "richtext-inline", "reference"];
+type TableColumnType = (typeof TABLE_COLUMN_TYPES)[number];
+declare const TABLE_RESPONSIVE: readonly ["scroll", "stack", "cards"];
+type TableResponsive = (typeof TABLE_RESPONSIVE)[number];
+declare const TABLE_JSONLD_TYPES: readonly ["none", "ItemList", "Dataset", "Offers"];
+type TableJsonLdType = (typeof TABLE_JSONLD_TYPES)[number];
+/** Hard limits, whatever a field allows: past these a table is a dataset, not page content. */
+declare const TABLE_LIMITS: {
+    readonly columns: 50;
+    readonly rows: 1000;
+    readonly cellChars: 5000;
+    readonly captionChars: 300;
+    readonly notesChars: 2000;
+    readonly keyChars: 64;
+    readonly labelChars: 300;
+};
+interface TableColumn {
+    _key: string;
+    label: string;
+    type: TableColumnType;
+    description?: string;
+    unit?: string;
+    currency?: string;
+    decimals?: number;
+    align?: "start" | "center" | "end";
+    sortable?: boolean;
+    group?: string;
+    trueLabel?: string;
+    falseLabel?: string;
+    max?: number;
+    refTo?: string[];
+    highlight?: boolean;
+}
+interface TableGroup {
+    _key: string;
+    label: string;
+}
+interface TableLink {
+    label: string;
+    href: string;
+    newTab?: boolean;
+    rel?: "follow" | "nofollow" | "ugc" | "sponsored";
+}
+/** What a read that resolves references writes onto a reference cell (never stored). */
+interface TableRefResolved {
+    kind: "page" | "entry";
+    id: string;
+    title: string;
+    slug: string | null;
+    url: string | null;
+}
+interface TableRef {
+    ref: string;
+    label?: string;
+    href?: string;
+    resolved?: TableRefResolved;
+}
+type TableCellValue = string | number | boolean | null | TableLink | TableRef;
+interface TableCellObject {
+    value: TableCellValue;
+    type?: TableColumnType;
+    note?: string;
+}
+type TableCell = TableCellValue | TableCellObject;
+interface TableRow {
+    _key: string;
+    cells: Record<string, TableCell | undefined>;
+    group?: string;
+    footer?: boolean;
+    type?: TableColumnType;
+    highlight?: boolean;
+}
+interface TableFootnote {
+    _key: string;
+    text: string;
+}
+interface TableValue {
+    id?: string;
+    caption: string;
+    notes?: string;
+    headerRow: boolean;
+    headerColumn: boolean;
+    columns: TableColumn[];
+    columnGroups?: TableGroup[];
+    rowGroups?: TableGroup[];
+    rows: TableRow[];
+    footnotes?: TableFootnote[];
+    filterable?: boolean;
+    design?: {
+        responsive?: TableResponsive;
+        sticky?: boolean;
+        striped?: boolean;
+        density?: "compact" | "comfortable";
+        hideCaption?: boolean;
+    };
+    jsonLd?: {
+        type: TableJsonLdType;
+        axis?: "rows" | "columns";
+        priceRow?: string;
+    };
+}
+/** The field-level options (`config` of a `table` field, or of a `table` prop in `mode: "data"`). */
+interface TableFieldOptions {
+    columnTypes?: TableColumnType[];
+    lockColumns?: boolean;
+    minRows?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    requireCaption?: boolean;
+    allowGroups?: boolean;
+    allowFootnotes?: boolean;
+    allowNote?: boolean;
+    settings?: {
+        headers?: boolean;
+        totals?: boolean;
+        phones?: TableResponsive[];
+        highlight?: boolean;
+        sticky?: boolean;
+        sort?: boolean;
+        search?: boolean;
+    };
+    jsonLd?: Exclude<TableJsonLdType, "none">[];
+}
+/** A value shaped like a table (`columns` and `rows` arrays): what a walker hands to the table lane. */
+declare const isTableValue: (v: unknown) => v is TableValue;
+type TableProblem = {
+    path: Array<string | number>;
+    code: string;
+    message: string;
+};
+type TableCheckOptions = TableFieldOptions & {
+    /** The columns a `lockColumns` table must keep (the field's default table): same keys, types and order. */
+    lockedColumns?: ReadonlyArray<{
+        _key: string;
+        type: string;
+    }>;
+    /** The caller's href grammar (which relative forms a site may hold); script hrefs are always refused. */
+    hrefProblem?: (href: string) => string | null;
+};
+/**
+ * Every reason `value` is not a table this field takes, each at its own path inside the value
+ * (`rows[2].cells.price`). Empty when it is one. Cells whose words do not match their column's type
+ * (text in a number column) are accepted, as V2 accepts them: the type decides formatting, and the
+ * editor warns. A cell OBJECT must match its type (a link in a link cell, a reference in a reference
+ * cell), so nothing is stored that the renderer would drop.
+ */
+declare function tableValueProblems(value: unknown, opts?: TableCheckOptions): TableProblem[];
+/** A {@link TableProblem}'s path as the dotted / indexed string error maps use: `rows[2].cells.price`. */
+declare function tablePathString(path: ReadonlyArray<string | number>): string;
+/**
+ * The stored form of a table value: explicit `headerRow` / `headerColumn`, and no `resolved` on a
+ * reference cell (a read writes it; a client echoing a read back must not store it). Everything
+ * else is kept as sent. A value that is not table-shaped is returned as is, for the validator.
+ */
+declare function normalizeTableValue<T>(value: T): T;
+/** Every reference cell a table holds: the object (resolved in place by a read), its id, path and column's `refTo`. */
+declare function tableRefCells(value: unknown): Array<{
+    cell: TableRef;
+    id: string;
+    path: Array<string | number>;
+    refTo: string[] | null;
+}>;
+/** The words a cell says (Markdown, search, screen readers). Booleans say their words, never a tick. */
+declare function tableCellText(col: TableColumn, row: TableRow | undefined, c: unknown): string;
+/**
+ * The table as semantic HTML (published form: no editing marks): `<figure class="bt-table">` ›
+ * `<table>` with caption, column-group headers, `<thead>`, one `<tbody>` per row group, `<tfoot>`,
+ * then notes and footnotes. Stack / cards layouts restate the table roles (CSS display drops them).
+ */
+declare function renderTableHtml(input: TableValue): string;
+/**
+ * The table as GFM: the caption in bold above, one header row (a column group prefixes its
+ * columns: "Sizes · Chest"), a row group as a bold label row, then notes, column descriptions and
+ * footnotes. Booleans say their words. Links and resolved references are Markdown links.
+ */
+declare function tableToMarkdown(input: TableValue): string;
+/** The words a table holds, for site search: caption, notes, headers, group labels, every cell's text, footnotes. */
+declare function tableSearchText(input: unknown): string;
+
 /**
  * ContentEntry — a single unit of content, representing the
  * published layout of a page: a collection of ordered blocks
@@ -2372,18 +3031,41 @@ interface DeliveryEntry<T = Record<string, unknown>> {
  */
 interface PageMetaJson {
     canonical?: string;
+    /** The card. `image*` describe `image`; `locale` is `og:locale`, `localeAlternate` every `og:locale:alternate`. */
     og?: {
         title?: string;
         description?: string;
         image?: string;
         type?: string;
+        imageWidth?: number;
+        imageHeight?: number;
+        imageAlt?: string;
+        locale?: string;
+        localeAlternate?: string[];
+        siteName?: string;
     };
     twitter?: {
         card?: string;
         title?: string;
         description?: string;
         image?: string;
+        imageAlt?: string;
+        site?: string;
+        creator?: string;
+    };
+    /** `article:*`: published and modified times (ISO 8601), author, section, tags. */
+    article?: {
+        publishedTime?: string;
+        modifiedTime?: string;
+        author?: string;
+        section?: string;
+        tags?: string[];
     };
+    /** `<link rel="alternate" hreflang>`: the same page in other languages. */
+    alternates?: Array<{
+        hreflang: string;
+        href: string;
+    }>;
     schema?: Record<string, unknown> | Array<Record<string, unknown>>;
 }
 /** `DeliveryEntry.seo`: the page meta shape plus the entry's flat title, description and noindex. */
@@ -2405,10 +3087,18 @@ interface SiteSeoDefaults {
     og?: {
         image?: string;
         type?: string;
+        siteName?: string;
+        locale?: string;
     };
     twitter?: {
         card?: string;
     };
+    /** The feeds the site links from every page (`<link rel="alternate" type="application/rss+xml">`). */
+    feeds?: Array<{
+        type: string;
+        href: string;
+        title?: string;
+    }>;
     /** Site-wide JSON-LD emitted alongside the page's own `schema`. */
     siteSchema?: Record<string, unknown> | Array<Record<string, unknown>>;
 }
@@ -2860,4 +3550,77 @@ declare function regionOf<E extends {
     el: E;
 }[], el: unknown): string | null;
 
-export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BREAKPOINTS, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSizeName, type ButtonValue, type ButtonVariant, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, 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, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_SIZE_ZOOM, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldSize, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, 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, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkRel, type LocatorGrammar, MAIN_SELECTOR, 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 PropGroup, RESPONSIVE_CSS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotItem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, type VariantInputMapping, type VideoBlock, type VideoProps, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, buttonBlockProps, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, expandBlockBindings, fieldStyleCssText, fieldStyleToCss, formatPropsAttribute, getBlockType, headingPaintCss, hideOnAttr, inWindow, isBlock, isChromeLandmark, keyWords, landmarkRegions, locatorFor, normalizeWindow, parsePropsAttribute, pickFieldStyle, readButtonValue, readPath, regionOf, safeCssUrl, slotItems, spaceTokenCss, splitButtonStyle, usesHideOn, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps };
+/**
+ * `<BcmsSections>`: which of a page's sections render, in what order, and which block each one is.
+ *
+ * A code-built page passes every section it can draw as a named SLOT; the CMS page's block list
+ * says the order. This is the one place that joins the two, shared by @bettercms-ai/astro and
+ * @bettercms-ai/next so a site renders the same list on either. The backend reads a placement's
+ * group through the same `placementBindOf`, so a slot's name is the id the platform measured.
+ *
+ * Pure: no DOM, no framework, no I/O.
+ */
+/**
+ * The tag-shaped heads the derive lane mints keys from (`h1-welcome`, `p-we-build-things`,
+ * `img-logo`, `list-benefits`, `a-contact`). A key whose head is one of these names an ELEMENT,
+ * not a section family, so it has no group root.
+ *
+ * 🔴 NOT ONLY TEXT TAGS. Derive also keys a text leaf found by SHAPE by its own tag (`span-dismiss`,
+ * `div-samantha-ruiz`, `time-…`) and a media leaf by its kind (`icon-icon`, `bg-…`). Missing here,
+ * each of those heads read as a FAMILY: an unmarked announcement bar became components called
+ * "Span" and "Icon".
+ */
+declare const TAG_HEADS: ReadonlySet<string>;
+/** The top-level field key a path belongs to: `hero.title` → `hero`, `faq[0].q` → `faq`. */
+declare const topFieldKeyOf: (path: string) => string;
+/**
+ * The GROUP a top-level field key belongs to, and whether that group has a real root.
+ *
+ * Two shapes are groups: a repeater the derive lane already folded (`group-*`), and a family prefix
+ * on an authored or renamed key (`hero-title`, `hero.title` → `hero`). Everything else is a bare
+ * element key with no family, and grouping those by their tag would mint one section per heading.
+ */
+declare function fieldGroupOf(topKey: string, flat?: boolean): {
+    groupKey: string;
+    rooted: boolean;
+};
+/**
+ * The GROUP a placement renders, or null if this block is not a placement of the site's own code.
+ *
+ * Two spellings: `props.bind` says the group outright; `props.source` (`{ propKey: "<page path>" }`)
+ * is what is left once the copy moved onto the instance, and the group is derived from it. A
+ * section added from the library carries neither, which is how it is told apart: the site's code
+ * has nothing to draw it with.
+ */
+declare function placementBindOf(block: unknown): string | null;
+/**
+ * A slot the CMS was not known to hold when the page was wrapped is spelled `code:<bind>`.
+ * It matches a block bound to `<bind>` like the bare spelling does; it differs only when no block
+ * names it: a `code:` slot then renders where the source has it, a bare one is a removed section.
+ */
+declare const CODE_SLOT_PREFIX = "code:";
+/** The bind a slot answers to: `code:hero` and `hero` → `hero`. */
+declare const slotBindOf: (slot: string) => string;
+/** One thing `<BcmsSections>` renders: the page's own slot (with its block, when one names it), or a CMS block. */
+type SectionPlanItem<B> = {
+    slot: string;
+    block: B | null;
+} | {
+    slot: null;
+    block: B;
+};
+/**
+ * The render order of a page: its slots (in source order) joined with its block list (in CMS order).
+ *
+ * - No block list (a build with no snapshot, the API down): every slot, in source order, no block.
+ * - A block bound to a slot renders that slot at the block's position. Each slot renders once: a
+ *   second block of the same bind is skipped, as is a bound block the page passed no slot for
+ *   (the site draws that one somewhere this list cannot reach, so drawing it again would double it).
+ * - A block with no bind (a section added from the library) is the CMS's own to draw.
+ * - A slot no block names: a `code:` slot always renders, after the source slot before it. A bare
+ *   slot renders the same way while the list names none of this page's slots (another project's
+ *   snapshot, a page never placed); once it names one, an unnamed bare slot is a removed section.
+ */
+declare function planSections<B>(slots: readonly string[], blocks: readonly B[] | null | undefined): SectionPlanItem<B>[];
+
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BREAKPOINTS, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSiteLook, type ButtonSizeName, type ButtonValue, type ButtonVariant, CODE_SLOT_PREFIX, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type ChoiceOption, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, 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, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_SIZE_ZOOM, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldSize, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, 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, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, LINK_VALUE_TYPES, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkRel, type LinkValue, type LinkValueType, type LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, type NumberFieldFormat, type NumberScale, OPTION_DESCRIPTION_MAX, type OpenMode, 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 PropGroup, RESPONSIVE_CSS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SLOT_CHILD_KEYS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type ScaleUnit, type SectionBlock, type SectionPlanItem, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotChild, type SlotItem, type SlotShapeOptions, type SlotShapeProblem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, TABLE_COLUMN_TYPES, TABLE_JSONLD_TYPES, TABLE_LIMITS, TABLE_RESPONSIVE, TAG_HEADS, type TabItem, type TableCell, type TableCellObject, type TableCellValue, type TableCheckOptions, type TableColumn, type TableColumnType, type TableFieldOptions, type TableFootnote, type TableGroup, type TableLink, type TableProblem, type TableRef, type TableRefResolved, type TableRow, type TableValue, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, VIDEO_TRANSCRIPT_MAX, VIDEO_VALUE_KEYS, type VariantInputMapping, type VideoBlock, type VideoProps, type VideoValue, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, buttonBlockProps, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonLookValue, buttonSiteLookOf, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, expandBlockBindings, fieldGroupOf, fieldStyleCssText, fieldStyleToCss, formatNumber, formatPropsAttribute, getBlockType, headingPaintCss, hideOnAttr, inWindow, isBlock, isButtonLookValue, isChromeLandmark, isLinkObject, isScriptHref, isSlotChild, isTableValue, keyWords, landmarkRegions, linkAnchorOf, linkHref, linkRefOf, linkValueProblem, locatorFor, normalizeLinkValue, normalizeTableValue, normalizeWindow, parseNumberText, parsePropsAttribute, pickFieldStyle, placementBindOf, planSections, readButtonValue, readNumberFormat, readPath, regionOf, renderTableHtml, safeCssUrl, slotBindOf, slotChildValues, slotItems, slotPathString, slotShapeProblems, spaceTokenCss, splitButtonStyle, tableCellText, tablePathString, tableRefCells, tableSearchText, tableToMarkdown, tableValueProblems, topFieldKeyOf, usesHideOn, videoUrlOf, videoValueProblem, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps };