@bettercms-ai/types 1.23.1 → 1.25.0

package/dist/index.d.ts

@@ -13,6 +13,276 @@ interface Workspace {
     updatedAt: string;
 }
 
+/**
+ * Generated by scripts/gen-dock-icon-names.mjs from the vendored icon tarball
+ * (sha256 0691620e50bdf453c2fed06224d9dc52d521574ab254a149eba47664b92fb889).
+ * 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"];
+type DockIconName = (typeof DOCK_ICON_NAMES)[number];
+declare const DOCK_ICON_NAME_SET: ReadonlySet<string>;
+
+/**
+ * ContentModel — the structured content model (schema) for a workspace.
+ * Defines which content fields are available for authors to fill in.
+ */
+interface ContentModel {
+    id: string;
+    workspaceId: string;
+    name: string;
+    description?: string;
+    /** 'block' models hold no entries — they are instantiable only inside a `modular` field. */
+    kind?: ContentModelKind;
+    fields: ContentModelField[];
+    /** Authoring-only field grouping for the schema builder. Never affects the API shape. */
+    fieldsets?: Fieldset[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Canonical field types. Nesting lives on `array` via `config.zones`
+ * (see {@link ArrayZoneConfig}): `group`/`repeater` are accepted as legacy input
+ * by the API but normalized to `array` + zones on write, so stored/delivered
+ * content never contains them.
+ */
+type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location";
+type ContentModelKind = "model" | "block";
+/**
+ * How a fieldset renders in the dock. ABSENT ≡ today's flat list (V2): a legacy `{id, name}`
+ * fieldset never regroups anything.
+ *   - `group` a disclosure; `row` ≤3 pairable scalars on one line; `tab` one of ≤3 top-level tabs.
+ */
+type FieldsetKind = "group" | "row" | "tab";
+/** Who last shaped a path's authoring chrome. Server-owned: a client echo is discarded. */
+type UiOrigin = "human" | "agent" | "derived";
+/**
+ * The chrome a field had before the first agent write over a non-agent state, kept so a human
+ * can revert it. Server-owned, like {@link UiOrigin}.
+ */
+interface UiBefore {
+    ui?: ContentModelFieldUi;
+    fieldsetId?: string;
+    /** Index among the field's siblings at the time. */
+    position: number;
+    label?: string;
+    helpText?: string;
+}
+/**
+ * A fieldset's chrome before the first agent change over a human/derived (or unstamped) state,
+ * kept so a person can revert it. `label` is the set's `name`. Server-owned, like {@link UiOrigin}:
+ * frozen while the origin stays `agent`, cleared by a human or derived change, carried by id.
+ */
+interface FieldsetUiBefore {
+    label: string;
+    ui: {
+        kind?: FieldsetKind;
+        tab?: string;
+        icon?: DockIconName;
+        collapsed?: boolean;
+    };
+}
+/** A named, UI-only grouping of a model's fields. Order is the array index. */
+interface Fieldset {
+    id: string;
+    name: string;
+    /** One line shown under the card title in the editor. Editor-only. */
+    description?: string;
+    kind?: FieldsetKind;
+    icon?: DockIconName;
+    /** A `group` that starts closed. */
+    collapsed?: boolean;
+    /** A group/row that sits inside this `kind:"tab"` fieldset. */
+    tab?: string;
+    uiOrigin?: UiOrigin;
+    uiBefore?: FieldsetUiBefore;
+}
+/**
+ * Nested-content config for an `array` field. A zone holds ordinary fields, and a
+ * zone field may itself be an `array` with its own zones, so nesting is recursive
+ * to any depth.
+ *   - `nonRepeatable` — a single fixed block of fields (former `group`).
+ *   - `repeatable`    — a repeating list of field-objects (former `repeater`).
+ * Mutually exclusive with the primitive form (`config.itemType`).
+ */
+interface ArrayZoneConfig {
+    nonRepeatable?: ContentModelField[];
+    repeatable?: {
+        fields: ContentModelField[];
+        minItems?: number;
+        maxItems?: number;
+    };
+}
+/** Per-type config for a field (the typed shape behind the loose `config` bag). */
+interface FieldConfig {
+    /** primitive array: list of scalars */
+    itemType?: "text" | "number" | "date";
+    /** nested array: zoned fields (recursive) */
+    zones?: ArrayZoneConfig;
+    /** reference / multi-reference */
+    contentModelId?: string;
+    min?: number;
+    max?: number;
+    /** date / datetime */
+    includeTime?: boolean;
+    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
+    blockSlugs?: string[];
+    /** modular: bounds on how many block instances the field may hold. */
+    minItems?: number;
+    maxItems?: number;
+    /**
+     * sections: SLUGS of the sections an author may insert into this zone.
+     *
+     * Deliberately NOT named `blockSlugs`. That key means "kind='block' content models" and is
+     * read by ModularField; these are section-registry slugs resolved from a different place.
+     * One key meaning two things is how `blockModels`/`blockSlugs` already drifted apart in the
+     * dashboard — a distinct name costs nothing and cannot be confused at a call site.
+     *
+     * ⚠ ABSENT ≠ EMPTY:
+     *     absent   → UNRESTRICTED, every registry section may be inserted
+     *     []       → DENY ALL, a deliberate empty restriction
+     *     [a, b]   → only those
+     * `[]` means DENY here to match `components.allowed_on` (migration 0190), so two adjacent
+     * allow-lists never disagree about what empty means.
+     *
+     * Absent rather than "all current slugs" because the registry GROWS — it is fed by repo
+     * pushes and project components, so materializing today's slugs at field-creation time would
+     * silently exclude every section shipped afterwards.
+     *
+     * NOT READ DIRECTLY. Insertability is this list INTERSECTED with the component's `allowedOn`
+     * (where that section may be placed), computed by one resolver so the two cannot drift.
+     *
+     * Enforced on NEW picks only. Narrowing the list later must never invalidate sections an
+     * author already placed, the same rule modular's blockSlugs and component-ref's allowlist
+     * follow.
+    */
+    allowedSections?: string[];
+    /** Durable project-local authored Zone mode. Legacy zones omit this key. */
+    mode?: "authored-v2";
+    /** Durable Zone id. Present when `mode` is `authored-v2`. */
+    zoneId?: string;
+    /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
+    legacyResolved?: boolean;
+    legacyMappings?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Where a field renders in the entry editor.
+ *
+ * AUTHORING ONLY — this has no delivery or storage effect. It does not change the
+ * shape of `data`, is not read by any renderer in @bettercms-ai/next or /astro, and
+ * cannot move a value onto or off a published page. It decides one thing: where the
+ * control sits while somebody is writing.
+ *
+ * Granularity is REGION-level, never interleaved between body blocks: the canvas is
+ * `[hero slots] → [free block flow] → [inline fields] → [panel fields in the drawer]`.
+ * A field cannot be positioned "between two paragraphs" — there is no coordinate space
+ * for that, and inventing one would mean mounting form controls inside the Lexical tree.
+ *
+ * - `cover` / `title` / `excerpt` / `body` — the four hero slots, rendered unlabelled
+ *   and typographically native. SCHEMA-LEVEL ONLY: a per-entry override may never
+ *   claim one, or one author's click renders anonymous 40px text over anonymous text
+ *   on that entry alone.
+ * - `inline` — in the canvas, below the block flow, labelled.
+ * - `panel` — in the drawer.
+ *
+ * ABSENT is meaningful and is the default for every model that predates this: the
+ * editor falls back to its title-gated heuristic. Only an explicit value promotes a
+ * field past that gate.
+ */
+type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inline" | "panel";
+interface ContentModelField {
+    key: string;
+    label: string;
+    type: ContentModelFieldType;
+    required?: boolean;
+    /**
+     * No two entries of the model may hold the same value (trimmed, case-insensitive). On a
+     * repeater child, every row of every entry at that path. Scalar types only.
+     */
+    unique?: boolean;
+    defaultValue?: unknown;
+    options?: string[];
+    /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
+    config?: FieldConfig | null;
+    /**
+     * Which fieldset this field renders under in the schema builder. Authoring-only: it is
+     * never delivered and cannot move a value — see {@link Fieldset}.
+     */
+    fieldsetId?: string;
+    /**
+     * Authoring-only editor placement. See {@link ContentModelFieldPlacement}.
+     * Field ORDER is the array index — there is deliberately no `order` property.
+     */
+    placement?: ContentModelFieldPlacement;
+    /**
+     * Authoring chrome — how the field PRESENTS in the editor. Never delivered, never read by a
+     * renderer, and never able to move a value; the same contract as {@link placement}.
+     *
+     * A SIBLING of `config`, not a member of it: `config` is per-type and strict on several
+     * types, and the normalizer rebuilds it wholesale for every nesting field — so a `config.ui`
+     * survives on leaves and vanishes on exactly the fields `preview` is for.
+     *
+     * `preview.title` / `preview.media` name a CHILD FIELD KEY of this field (validated on
+     * write). Still no `order`: order is the array index, per the note on {@link placement}.
+     */
+    ui?: ContentModelFieldUi;
+    /** Server-owned provenance of this field's chrome. @see UiOrigin */
+    uiOrigin?: UiOrigin;
+    /** Server-owned revert point. @see UiBefore */
+    uiBefore?: UiBefore;
+}
+/** @see ContentModelField.ui */
+interface ContentModelFieldUi {
+    /** Start this nesting field's panel collapsed. Absent ≡ the editor's own default. */
+    collapsed?: boolean;
+    /** How one item of a nesting field summarises itself when collapsed. Keys, not values. */
+    preview?: {
+        /** Child field key whose value titles the row. */
+        title?: string;
+        /** Child field key whose value is the row's second line. */
+        subtitle?: string;
+        /** Child field key whose value is the row's thumbnail. Type is not constrained. */
+        media?: string;
+    };
+    /**
+     * How the ITEMS of a nesting field are arranged. ABSENT ≡ `"list"` — every field stored
+     * before this key existed means `"list"`, so a reader must treat undefined as list and never
+     * as "unset, pick something".
+     *
+     * Same placement rule as {@link ContentModelFieldUi.preview}: nesting fields only.
+     */
+    layout?: "list" | "grid" | "table";
+    /**
+     * Whether the items of a list may be dragged. ABSENT ≡ `true`, for the same reason — nothing
+     * stored today carries it, and everything stored today is reorderable.
+     *
+     * `false` LOCKS the order: a "three steps" band, a semantic nav, a timeline. Valid only where
+     * there is a list (a repeatable zone, a `repeater`, or `modular`), so a reader that honours it
+     * must disable the sortable behaviour, not just hide the grip — a hidden grip still reorders
+     * from the keyboard.
+     */
+    reorderable?: boolean;
+    /**
+     * Which editor control a LEAF renders with. ABSENT ≡ the type's default (a dropdown for a
+     * `select`, a plain input for a `number`). `segmented` is valid on a single-choice `select`;
+     * `slider` on a `number` whose config.min < config.max.
+     */
+    control?: "segmented" | "slider";
+    /** The branch row's icon. Nesting fields only. */
+    icon?: DockIconName;
+    /** What one item is called ("Slide", "Member"), 1–24 chars. Nesting fields only. */
+    itemLabel?: string;
+}
+/**
+ * A field inside an array zone — identical to a top-level {@link ContentModelField}.
+ * Kept as a named alias so consumers can express "zone field" intent; recursion
+ * (an array zone field with its own `config.zones`) is supported.
+ */
+type ZoneField = ContentModelField;
+
 /**
  * Page — a published content page within a workspace.
  */
@@ -27,6 +297,16 @@ interface Page {
     publishedAt?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * The content model that holds this page's own fields (content_models.page_id), for dock
+     * writes: its optimistic version is the If-Match. `null` for a static page or a legacy row with
+     * no page_id; absent on reads that do not resolve it.
+     */
+    backingModel?: {
+        id: string;
+        optimisticVersion: number;
+        fieldsets: Fieldset[] | null;
+    } | null;
 }
 
 /**
@@ -107,6 +387,15 @@ interface BlockStyle {
     border?: boolean;
     /** 🔴 The one free-form string. MUST go through `safeCssUrl()` before reaching CSS. */
     bgImage?: string;
+    /** A button's look while the pointer is over it. Only the paint changes; unset keys keep the rest. */
+    hover?: BlockHoverStyle;
+}
+/** The paint a button swaps to on hover: fill, text colour, and the all-round border. */
+interface BlockHoverStyle {
+    bg?: BgToken;
+    bgCustom?: string;
+    textColor?: ColorToken;
+    border?: boolean;
 }
 interface HeadingProps {
     text: string;
@@ -222,6 +511,10 @@ interface ButtonProps {
     text: string;
     href: string;
     variant?: "primary" | "secondary";
+    /** 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`. */
+    fullWidth?: boolean;
 }
 interface ButtonBlock {
     type: "button";
@@ -395,6 +688,14 @@ interface ComponentProps {
      * declaration's, because the prop holds every row.
      */
     source?: Record<string, string>;
+    /**
+     * A bound placement whose page spells its fields differently from the component's props — a
+     * locale copy (`/fr`) placed on its default-locale twin's component: `{ <propKey>: "<this page's
+     * field path>" }`. Readers resolve a prop's copy through it before `bind`, since the twin's own
+     * group keys (`personnalisez-titre`) are not the component's (`customize-title`). Written only
+     * while `bind` is; dropped with it when the instance takes its copy.
+     */
+    bindPaths?: Record<string, string>;
 }
 interface ComponentBlock {
     type: "component";
@@ -622,214 +923,6 @@ declare function componentInstanceAddresses(instanceBlockId: string, props: read
 /** A CSS declaration object (key → value) usable as a React `style` prop, or undefined when empty. */
 declare function blockStyleToCss(style: BlockStyle | undefined): Record<string, string | number> | undefined;
 
-/**
- * ContentModel — the structured content model (schema) for a workspace.
- * Defines which content fields are available for authors to fill in.
- */
-interface ContentModel {
-    id: string;
-    workspaceId: string;
-    name: string;
-    description?: string;
-    /** 'block' models hold no entries — they are instantiable only inside a `modular` field. */
-    kind?: ContentModelKind;
-    fields: ContentModelField[];
-    /** Authoring-only field grouping for the schema builder. Never affects the API shape. */
-    fieldsets?: Fieldset[];
-    createdAt: string;
-    updatedAt: string;
-}
-/**
- * Canonical field types. Nesting lives on `array` via `config.zones`
- * (see {@link ArrayZoneConfig}): `group`/`repeater` are accepted as legacy input
- * by the API but normalized to `array` + zones on write, so stored/delivered
- * content never contains them.
- */
-type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location";
-type ContentModelKind = "model" | "block";
-/** A named, UI-only grouping of a model's fields. Order is the array index. */
-interface Fieldset {
-    id: string;
-    name: string;
-    /** One line shown under the card title in the editor. Editor-only. */
-    description?: string;
-}
-/**
- * Nested-content config for an `array` field. A zone holds ordinary fields, and a
- * zone field may itself be an `array` with its own zones, so nesting is recursive
- * to any depth.
- *   - `nonRepeatable` — a single fixed block of fields (former `group`).
- *   - `repeatable`    — a repeating list of field-objects (former `repeater`).
- * Mutually exclusive with the primitive form (`config.itemType`).
- */
-interface ArrayZoneConfig {
-    nonRepeatable?: ContentModelField[];
-    repeatable?: {
-        fields: ContentModelField[];
-        minItems?: number;
-        maxItems?: number;
-    };
-}
-/** Per-type config for a field (the typed shape behind the loose `config` bag). */
-interface FieldConfig {
-    /** primitive array: list of scalars */
-    itemType?: "text" | "number" | "date";
-    /** nested array: zoned fields (recursive) */
-    zones?: ArrayZoneConfig;
-    /** reference / multi-reference */
-    contentModelId?: string;
-    min?: number;
-    max?: number;
-    /** date / datetime */
-    includeTime?: boolean;
-    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
-    blockSlugs?: string[];
-    /** modular: bounds on how many block instances the field may hold. */
-    minItems?: number;
-    maxItems?: number;
-    /**
-     * sections: SLUGS of the sections an author may insert into this zone.
-     *
-     * Deliberately NOT named `blockSlugs`. That key means "kind='block' content models" and is
-     * read by ModularField; these are section-registry slugs resolved from a different place.
-     * One key meaning two things is how `blockModels`/`blockSlugs` already drifted apart in the
-     * dashboard — a distinct name costs nothing and cannot be confused at a call site.
-     *
-     * ⚠ ABSENT ≠ EMPTY:
-     *     absent   → UNRESTRICTED, every registry section may be inserted
-     *     []       → DENY ALL, a deliberate empty restriction
-     *     [a, b]   → only those
-     * `[]` means DENY here to match `components.allowed_on` (migration 0190), so two adjacent
-     * allow-lists never disagree about what empty means.
-     *
-     * Absent rather than "all current slugs" because the registry GROWS — it is fed by repo
-     * pushes and project components, so materializing today's slugs at field-creation time would
-     * silently exclude every section shipped afterwards.
-     *
-     * NOT READ DIRECTLY. Insertability is this list INTERSECTED with the component's `allowedOn`
-     * (where that section may be placed), computed by one resolver so the two cannot drift.
-     *
-     * Enforced on NEW picks only. Narrowing the list later must never invalidate sections an
-     * author already placed, the same rule modular's blockSlugs and component-ref's allowlist
-     * follow.
-    */
-    allowedSections?: string[];
-    /** Durable project-local authored Zone mode. Legacy zones omit this key. */
-    mode?: "authored-v2";
-    /** Durable Zone id. Present when `mode` is `authored-v2`. */
-    zoneId?: string;
-    /** Explicit migration acknowledgement while the legacy allowlist remains readable. */
-    legacyResolved?: boolean;
-    legacyMappings?: Record<string, string>;
-    [key: string]: unknown;
-}
-/**
- * Where a field renders in the entry editor.
- *
- * AUTHORING ONLY — this has no delivery or storage effect. It does not change the
- * shape of `data`, is not read by any renderer in @bettercms-ai/next or /astro, and
- * cannot move a value onto or off a published page. It decides one thing: where the
- * control sits while somebody is writing.
- *
- * Granularity is REGION-level, never interleaved between body blocks: the canvas is
- * `[hero slots] → [free block flow] → [inline fields] → [panel fields in the drawer]`.
- * A field cannot be positioned "between two paragraphs" — there is no coordinate space
- * for that, and inventing one would mean mounting form controls inside the Lexical tree.
- *
- * - `cover` / `title` / `excerpt` / `body` — the four hero slots, rendered unlabelled
- *   and typographically native. SCHEMA-LEVEL ONLY: a per-entry override may never
- *   claim one, or one author's click renders anonymous 40px text over anonymous text
- *   on that entry alone.
- * - `inline` — in the canvas, below the block flow, labelled.
- * - `panel` — in the drawer.
- *
- * ABSENT is meaningful and is the default for every model that predates this: the
- * editor falls back to its title-gated heuristic. Only an explicit value promotes a
- * field past that gate.
- */
-type ContentModelFieldPlacement = "cover" | "title" | "excerpt" | "body" | "inline" | "panel";
-interface ContentModelField {
-    key: string;
-    label: string;
-    type: ContentModelFieldType;
-    required?: boolean;
-    /**
-     * No two entries of the model may hold the same value (trimmed, case-insensitive). On a
-     * repeater child, every row of every entry at that path. Scalar types only.
-     */
-    unique?: boolean;
-    defaultValue?: unknown;
-    options?: string[];
-    /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
-    config?: FieldConfig | null;
-    /**
-     * Which fieldset this field renders under in the schema builder. Authoring-only: it is
-     * never delivered and cannot move a value — see {@link Fieldset}.
-     */
-    fieldsetId?: string;
-    /**
-     * Authoring-only editor placement. See {@link ContentModelFieldPlacement}.
-     * Field ORDER is the array index — there is deliberately no `order` property.
-     */
-    placement?: ContentModelFieldPlacement;
-    /**
-     * Authoring chrome — how the field PRESENTS in the editor. Never delivered, never read by a
-     * renderer, and never able to move a value; the same contract as {@link placement}.
-     *
-     * A SIBLING of `config`, not a member of it: `config` is per-type and strict on several
-     * types, and the normalizer rebuilds it wholesale for every nesting field — so a `config.ui`
-     * survives on leaves and vanishes on exactly the fields `preview` is for.
-     *
-     * `preview.title` / `preview.media` name a CHILD FIELD KEY of this field (validated on
-     * write). Still no `order`: order is the array index, per the note on {@link placement}.
-     */
-    ui?: ContentModelFieldUi;
-}
-/** @see ContentModelField.ui */
-interface ContentModelFieldUi {
-    /** Start this nesting field's panel collapsed. Absent ≡ the editor's own default. */
-    collapsed?: boolean;
-    /** How one item of a nesting field summarises itself when collapsed. Keys, not values. */
-    preview?: {
-        /** Child field key whose value titles the row. */
-        title?: string;
-        /** Child field key whose value is the row's second line. */
-        subtitle?: string;
-        /** Child field key whose value is the row's thumbnail. Type is not constrained. */
-        media?: string;
-    };
-    /**
-     * How the ITEMS of a nesting field are arranged. ABSENT ≡ `"list"` — every field stored
-     * before this key existed means `"list"`, so a reader must treat undefined as list and never
-     * as "unset, pick something".
-     *
-     * Same placement rule as {@link ContentModelFieldUi.preview}: nesting fields only.
-     */
-    layout?: "list" | "grid" | "table";
-    /**
-     * Whether the items of a list may be dragged. ABSENT ≡ `true`, for the same reason — nothing
-     * stored today carries it, and everything stored today is reorderable.
-     *
-     * `false` LOCKS the order: a "three steps" band, a semantic nav, a timeline. Valid only where
-     * there is a list (a repeatable zone, a `repeater`, or `modular`), so a reader that honours it
-     * must disable the sortable behaviour, not just hide the grip — a hidden grip still reorders
-     * from the keyboard.
-     */
-    reorderable?: boolean;
-    /**
-     * Which editor control a LEAF renders with. ABSENT ≡ the type's default (a dropdown for a
-     * `select`, a plain input for a `number`). `segmented` is valid on a single-choice `select`;
-     * `slider` on a `number` whose config.min < config.max.
-     */
-    control?: "segmented" | "slider";
-}
-/**
- * A field inside an array zone — identical to a top-level {@link ContentModelField}.
- * Kept as a named alias so consumers can express "zone field" intent; recursion
- * (an array zone field with its own `config.zones`) is supported.
- */
-type ZoneField = ContentModelField;
-
 /**
  * Generated from lucide-react@1.8.0 dynamic icon names.
  * Legacy CamelCase identifiers remain valid for existing Layout documents.
@@ -1330,8 +1423,28 @@ interface ComponentPropDef {
      * `preview`/`layout` on `group`, `table` and `slot`; `reorderable` on `table` ALONE, the only
      * prop type whose value is a list. The save schema refuses the rest with the valid set named.
      */
-    ui?: ContentModelFieldUi;
+    ui?: ComponentPropUi;
+    /** Server-owned provenance of this prop's chrome. @see UiOrigin */
+    uiOrigin?: UiOrigin;
+    /** Server-owned revert point. @see UiBefore */
+    uiBefore?: UiBefore;
 }
+/**
+ * A top-level prop's dock group. Props have no fieldsets column, so the group rides inline: the
+ * first prop to carry an `id` defines it (label, kind, icon, collapsed), later props name `{id}`.
+ */
+interface PropGroup {
+    id: string;
+    /** 1–32 chars. Required on the defining prop. */
+    label?: string;
+    kind?: Exclude<FieldsetKind, "tab">;
+    icon?: DockIconName;
+    collapsed?: boolean;
+}
+/** 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. */
 interface ComponentSubField {
     key: string;
@@ -1443,6 +1556,158 @@ interface DeliveryComponent {
     props: ComponentPropDef[];
 }
 
+/**
+ * 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
+ * golden this module emits (src/__tests__/fixtures/dock-budget.golden.json). No dependencies.
+ *
+ * A SCREEN is one navigation level of the dock, modelled on what the dock renders:
+ *   - `root`  the lane's first screen: the page fields, a page section, or a component's props;
+ *   - `list`  a repeatable's items, one branch hop below the row that opens it (a repeater, an
+ *             `array` with a repeatable zone, a `table` prop, `modular`);
+ *   - `item`  one item of that list, a second hop. `modular` has no item screen: its items are
+ *             other models.
+ * A non-repeatable zone (`group`, `array` + zones.nonRepeatable, a `group` prop) is NOT a screen.
+ * It renders inline as a group, collapsed only when its own `ui.collapsed` is true.
+ *
+ * On a screen:
+ *   - fieldsets with no `kind` are FLAT (V2): members render ungrouped, in document order;
+ *   - `kind:"group"` is a disclosure placed at its first member; `collapsed` costs 1 activation;
+ *   - `kind:"row"` is ONE leaf, however many members it holds;
+ *   - `kind:"tab"`, root screens only: a strip renders only with ≥2 non-empty tabs. Tab 1 is the
+ *     first panel, each later tab costs 1 activation, untabbed fields are PINNED above the strip,
+ *     and a group/row with `tab: <id>` sits in that tab. Below the root a tab reference is flat.
+ *   - component props join a group through `ui.group`; the first prop naming an id defines it.
+ *
+ * Budget, per screen (DOCK_BUDGET holds the limits):
+ *   - ungroupedLeaves: rows outside any group (a leaf, a row fieldset, a branch), as the max over
+ *     panels of pinned + panel. No picker term: tabs are capped at 3, so the strip never overflows.
+ *   - maxGroupLeaves: the largest group's own rows (a nested group counts in its own entry).
+ *   - depth: branch hops from the lane's root screen.
+ *   - maxActivations: the dearest value on the screen counted from the lane's root: +1 per branch
+ *     hop, +1 per collapsed group, +1 for a non-first tab. A screen with no values costs its entry.
+ */
+declare const DOCK_BUDGET: {
+    readonly ungrouped: 8;
+    readonly group: 12;
+    readonly depth: 3;
+    readonly activations: 2;
+};
+type DockLane = "page-fields" | "page-section" | "component";
+interface DockBudget {
+    ungroupedLeaves: number;
+    maxGroupLeaves: number;
+    depth: number;
+    maxActivations: number;
+}
+/** One row on a screen. Keys are paths from the screen's own fields (`hero.title`). */
+type DockNode = {
+    kind: "leaf";
+    key: string;
+} | {
+    kind: "row";
+    id: string;
+    keys: string[];
+} | {
+    kind: "branch";
+    key: string;
+} | {
+    kind: "group";
+    id: string;
+    collapsed: boolean;
+    nodes: DockNode[];
+};
+interface DockScreen {
+    /** `<lane>`, then `/<branch key>` per list and `/item` per item: `page-fields/quotes/item`. */
+    id: string;
+    lane: DockLane;
+    kind: "root" | "list" | "item";
+    title: string;
+    depth: number;
+    /** Activations spent reaching this screen from the lane's root. */
+    entry: number;
+    pinned: DockNode[];
+    /** One panel per tab, in fieldset order. Empty when no strip renders. */
+    tabs: DockNode[][];
+}
+/** The structural subset of a model field or component prop that this module reads. */
+interface DockFieldLike {
+    key: string;
+    label?: string;
+    type: string;
+    fieldsetId?: string;
+    ui?: {
+        collapsed?: boolean;
+        group?: DockPropGroupLike;
+    } | null;
+    config?: unknown;
+    /** Legacy `group`/`repeater` children, and a component sub-field's own children. */
+    fields?: DockFieldLike[];
+}
+interface DockFieldsetLike {
+    id: string;
+    name?: string;
+    kind?: "group" | "row" | "tab";
+    collapsed?: boolean;
+    tab?: string;
+}
+interface DockPropGroupLike {
+    id: string;
+    label?: string;
+    kind?: "group" | "row";
+    collapsed?: boolean;
+}
+/**
+ * Every screen of one lane, root first. Pass `props` for a component lane (its `fields` and
+ * `fieldsets` are then ignored): a prop's `ui.group` becomes the fieldset it joins.
+ */
+declare function dockScreens(source: {
+    fields?: DockFieldLike[] | null;
+    fieldsets?: DockFieldsetLike[] | null;
+}, lane: DockLane, props?: DockFieldLike[] | null): DockScreen[];
+declare function dockBudget(screen: DockScreen): DockBudget;
+
+/**
+ * THE button-link pairing rule, pure: which two sibling fields render as ONE button unit (the words
+ * on the button + where it goes). The dashboard folds them together; the backend refuses a write
+ * that splits such a pair across fieldsets (`pair_split`). One copy, so both ends agree.
+ *
+ * Presentation only: a pair keeps its own keys, values and writers.
+ *
+ * 1. A key is split into words whatever its spelling (`hero_cta_label`, `ctaText`, `button-link`);
+ *    a dotted path counts only its last segment.
+ * 2. The LAST word is the role: `label text title cta button btn name` are TEXT roles, `href link
+ *    url to` LINK roles. Everything before it is the STEM.
+ * 3. A text candidate is a text-typed field (`text`, `string`) with a text role. A key that is a
+ *    button noun (`cta`, `primaryButton`) also offers its full key as a stem.
+ * 4. A link candidate is a link-typed field (`link`, `url`), or a text-typed field with a link role
+ *    that is not a media address (`image_url`). A link-typed field whose last word is not a link
+ *    role offers both its stem and its full key.
+ * 5. Two fields pair when their stem holds EXACTLY one text and one link candidate. Three or more
+ *    candidates on a stem: none pair. A field that would pair two ways pairs neither way.
+ *
+ * When the key's words say nothing, the visible LABEL is read the same way, its stems namespaced
+ * (`label:`) so a label reading only ever meets another label reading.
+ */
+/** What the rule needs to know about one field. */
+interface ButtonLinkCandidate {
+    key: string;
+    type?: string;
+    label?: string;
+    /** The current value, when known: a structured value never pairs as text. */
+    value?: unknown;
+}
+/** `hero_cta_primary_label` / `ctaText` / `primaryButton-link` → lowercase words. */
+declare function keyWords(key: string): string[];
+type Role = {
+    role: "text" | "link";
+    stems: string[];
+};
+/** The role one field plays, with every stem it offers, or null. */
+declare function candidateRole(candidate: ButtonLinkCandidate): Role | null;
+/** Every unambiguous pair in one sibling list, as `[textIndex, linkIndex]`, in list order. */
+declare function buttonLinkPairs(candidates: readonly ButtonLinkCandidate[]): Array<[number, number]>;
+
 /**
  * ContentEntry — a single unit of content, representing the
  * published layout of a page: a collection of ordered blocks
@@ -2043,4 +2308,4 @@ 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, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockStyle, type BlockType, type ButtonBlock, type ButtonProps, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentProps, type ComponentSubField, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type CornerToken, DIALOG_SELECTOR, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type ElementLike, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, 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 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 RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, componentInstanceAddresses, componentPropTargetKey, expandBlockBindings, formatPropsAttribute, getBlockType, isBlock, isChromeLandmark, landmarkRegions, locatorFor, parsePropsAttribute, readPath, regionOf, spaceTokenCss };
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonLinkCandidate, type ButtonProps, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type 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 DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, 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, 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 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, type RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, 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 WeightToken, type Workspace, type ZoneField, blockStyleToCss, buttonLinkPairs, candidateRole, componentInstanceAddresses, componentPropTargetKey, dockBudget, dockScreens, expandBlockBindings, formatPropsAttribute, getBlockType, isBlock, isChromeLandmark, keyWords, landmarkRegions, locatorFor, parsePropsAttribute, readPath, regionOf, spaceTokenCss };