@bettercms-ai/mcp 0.73.0 → 0.73.2

package/dist/index.js

@@ -2989,6 +2989,8 @@ var PARAM_TEXT = {
   recommendedMax: "a SOFT limit (characters, items or value): the editor warns past it, never refuses",
   openMode: "object/array/group/repeater: how the value (or each row) opens: 'inline', 'drill', 'popover' or 'dialog'",
   fromBuiltin: "a builtin:* id from list_components: copies it into the project; fields you send win",
+  componentPreview: "a slot row's look: {title?, subtitle?, media?} TOP-LEVEL prop keys, fallback?, icon?; null clears. \xA73 of bettercms://playbook/schema",
+  componentIcon: "the block icon, a dock icon name; null clears. \xA73 of bettercms://playbook/schema",
   describes: "for editors: what it is and holds; omitted: written for you",
   runtimeBundle: "instead of pageId: the server-app bundle cleanup",
   pageRef: "page id or path ('/de/about'); a bare slug only when one page has it",
@@ -3034,7 +3036,7 @@ var DETACHED_COPY_NOTE = "{overrides?}: a rich-text embed's separate-copy `field
 var UNPROPPED_COPY_NOTE = "A `warnings` entry UNPROPPED_COPY names copy no prop targets, which nobody can edit: add a prop with a `target` for each leaf it lists.";
 var UPDATE_PAGE_IF_MATCH_NOTE = "get_page's `optimisticVersion`: the write applies only at that version, and a 409 means the page changed since, so read it again. Send it whenever you pass blockJson, which REPLACES the whole composition.";
 var SLOT_MULTIPLE_NOTE = "'slot' with config.multiple holds a list [{componentId, overrides?}] (config.maxItems, default 12, at most 50): target.path 'props.children' on a section. V2 slots, 'table' mode 'types': playbook \xA75.";
-var PROP_V2_NOTE = "Props take the fields' V2 keys (\xA714): 'object' = ONE {child: value} from config.fields, \u226410 levels (field_depth_exceeded); datetime|slug|email|phone|json|location|tags|rating|code|reference|multi-reference as that field (a reference names contentModelId, or polymorphic + allowedModelSlugs; page reads hydrate its entries); helpMore, advanced, recommendedMax, openMode, config.scale, ui.layout rows|chips|gallery, ui.preview.fallback, showIf notEmpty|empty.";
+var PROP_V2_NOTE = "Props take the fields' V2 keys (\xA714): 'object' = ONE {child: value} from config.fields, \u226410 levels (field_depth_exceeded); datetime|slug|email|phone|json|location|tags|rating|code|reference|multi-reference as that field (a reference names contentModelId, or polymorphic + allowedModelSlugs; page reads hydrate its entries); helpMore, advanced, recommendedMax, openMode, config.scale, ui.layout rows|chips|gallery, ui.preview.fallback, showIf notEmpty|empty. Send helpText: null for a prop whose /kit schema has no description (omitted, the platform writes one).";
 var LAYOUT_LOCK_NOTE = "A Global field with `overridable:false` + `lockReason` (add-field `field`, update-field `patch`) refuses page overrides (LAYOUT_FIELD_NOT_OVERRIDABLE); get_layout scope page lists stored ones as `shadowed`.";
 
 // src/entry-query.ts
@@ -3268,10 +3270,10 @@ var propUiObject = uiObject.extend({
   }).optional().describe("the group this prop (or sub-field) sits in. The FIRST member defines {id, label, kind?, icon?, collapsed?, description?, columns?, collapsible?, layout?, order?}; later ones send only {id}."),
   tab: z.strictObject({
     id: z.string().min(1).max(40),
-    label: z.string().min(1).max(20).optional(),
+    label: z.string().min(1).max(40).optional(),
     icon: uiObject.shape.icon,
     order: z.number().int().min(0).max(99).optional()
-  }).optional().describe("TOP-LEVEL props only: the dock tab this prop sits in (a V2 kit schema `groups` entry: Content, Design, \u2026). The FIRST prop in a tab defines {id, label, icon?, order?}; later ones send only {id}. \u22648 tabs, labels unique; a group's members share one tab.")
+  }).optional().describe("TOP-LEVEL props only: the dock tab this prop sits in (a V2 kit schema `groups` entry: Content, Design, \u2026). The FIRST prop in a tab defines {id, label, icon?, order?}; later ones send only {id}. \u22648 tabs, labels \u226440 chars and unique; a group's members share one tab.")
 });
 var choiceOption = z.union([z.string(), z.object({ label: z.string(), value: z.string(), icon: z.string().optional(), description: z.string().optional() })]);
 var fieldShape = {
@@ -3664,7 +3666,7 @@ var withProjectId = (def) => ({
     return currentProject.run(arg("projectId"), () => currentBranch.run(arg("branchId"), () => def.handler(args)));
   }
 });
-var autoHelpNote = (args) => typeof args.helpText === "string" && args.helpText.trim() ? "" : " No helpText was sent, so the platform wrote it (helpSource: auto); send helpText with update_field to write your own.";
+var autoHelpNote = (args) => args.helpText === null || typeof args.helpText === "string" && args.helpText.trim() ? "" : " No helpText was sent, so the platform wrote it (helpSource: auto); send helpText with update_field to write your own.";
 function buildToolDefs(deps) {
   async function withClient(fn) {
     const token = await deps.auth.getAccessToken();
@@ -3722,7 +3724,7 @@ function buildToolDefs(deps) {
     ]).describe("block type; section/slider/tabs/columns nest child blocks"),
     id: z.string().min(1).describe("stable unique block id"),
     props: z.record(z.string(), z.unknown()).describe(
-      "per-type props: heading {text, level}; text/richtext {html} (NOT {text}), and both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only) \u2014 use it for a title that carries a styled span; image {src, alt}; button {text, href, variant? (hosted pages; else a Button component), size? sm|md|lg, fullWidth?, arrow? boolean, icon? ui.icon name, newTab? boolean, rel? nofollow|sponsored|ugc}; spacer {height}; video {url}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns, copyright?}; section {children: block[]}; columns {columns: block[][], gap} \u2014 a column may hold ANY block; slider {slides:[{id,children}]}; tabs {tabs:[{id,label,children}]}; collection {cardComponentId?, source? {modelId}, limit?, filters?, sort?, pinnedIds?, excludeCurrent?}: a collection's published entries as cards (every prop: skill content-modeling)"
+      "per-type props by block type: \xA75 of bettercms://playbook/schema (text/richtext {html}, NOT {text}; button {text, href, variant?, size? sm|md|lg, fullWidth?}; component {componentId, overrides?}). Containers nest blocks to any depth."
     ),
     style: z.record(z.string(), z.unknown()).optional().describe(
       "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop] (all three hides it on the page: kept in the draft, never published). A real marketing band is a `section` block carrying bg + padding + contentWidth."
@@ -3971,6 +3973,7 @@ function buildToolDefs(deps) {
       // 'select' — required, choices
       // 'group'/'table'/'object' sub-shape. Typed loosely here (the server validates the full
       // recursive shape, 10 levels at most) so a deep tree needs no Zod mirror in the client.
+      // A sub-field may be a 'slot' (its value at its key in the object or row), with the slot keys above.
       fields: z.array(z.record(z.string(), z.unknown())).optional(),
       min: z.number().optional(),
       // 'number'
@@ -3982,7 +3985,7 @@ function buildToolDefs(deps) {
     // override that omits it still saves — so it is a marker the dashboard renders and
     // get_site_composition counts, never a refusal. Parity: componentPropDefSchema on the server.
     required: z.boolean().optional().describe("mark the field required in the editor. An editor HINT: the API still accepts a placement that leaves it empty, and get_site_composition is what reports one."),
-    helpText: z.string().max(200).optional().describe("hint shown under the control, muted (\u2264 200 chars)"),
+    helpText: z.string().max(200).nullable().optional().describe("hint shown under the control, muted (\u2264 200 chars). null = no help on purpose (a /kit schema with no description); omitted = the platform writes it"),
     placeholder: z.string().max(120).optional().describe("ghost text inside a text-ish control (\u2264 120 chars)"),
     // Stored markers on a prop: nothing refuses a prop value for them. Declared so an echo keeps them.
     readOnly: z.union([z.literal(true), z.literal("developer")]).optional(),
@@ -4071,6 +4074,13 @@ function buildToolDefs(deps) {
     "section family, e.g. 'Hero' \u2014 set this with a library category to make the component selectable in the page editor's 'Add a section' picker. Components sharing one are layout variants of one section."
   );
   const allowedOn = z.array(z.string().regex(/^(\*|slug:[a-z0-9-]+|type:(singleton|dynamic|template))$/)).max(100).describe("placement allowlist: *, slug:<page-slug>, and/or type:singleton|dynamic|template");
+  const componentPreviewArg = z.strictObject({
+    title: z.string().min(1).max(64).optional(),
+    subtitle: z.string().min(1).max(64).optional(),
+    media: z.string().min(1).max(64).optional(),
+    fallback: z.string().min(1).max(120).optional(),
+    icon: dockIconArg.optional()
+  }).nullable().describe(PARAM_TEXT.componentPreview);
   const createComponentInput = z.object({
     name: z.string().min(1),
     slug: slug.describe("url-safe unique slug (lowercase letters/numbers/hyphens)"),
@@ -4082,6 +4092,8 @@ function buildToolDefs(deps) {
     projectId: z.string().nullable().optional().describe("owning project id; null creates a workspace-wide global component"),
     allowedOn: allowedOn.optional(),
     description: z.string().optional().describe(PARAM_TEXT.describes),
+    preview: componentPreviewArg.optional(),
+    icon: dockIconArg.nullable().optional().describe(PARAM_TEXT.componentIcon),
     blockJson: z.array(blockObject).default([]).describe("the component's block tree"),
     props: z.array(componentPropObject).default([]).describe(
       "overridable fields. DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch: only the leaves a prop targets are click-to-edit. Each one may carry `ui` to say how its control presents in the inspector \u2014 a collapsed group, what titles and thumbnails a table's rows, whether that table's rows can be dragged at all. 'button' is ONE unit {label, href, variant?, size?, arrow?, icon?, newTab?} on a button block's 'props', never a text prop plus a url prop. 'link' an href, 'date' YYYY-MM-DD, 'color' a hex, 'file' {url, name?}, 'icon' an icon name or an image, 'multiselect' a string[] from config.options (required). " + SLOT_MULTIPLE_NOTE + " " + PROP_V2_NOTE
@@ -4098,6 +4110,8 @@ function buildToolDefs(deps) {
     variantOf: z.string().min(1).max(255).optional().describe("see create_component"),
     allowedOn: allowedOn.optional().describe("REPLACES the placement allowlist"),
     description: z.string().optional(),
+    preview: componentPreviewArg.optional(),
+    icon: dockIconArg.nullable().optional().describe(PARAM_TEXT.componentIcon),
     blockJson: z.array(blockObject).optional().describe("REPLACES the block tree"),
     props: z.array(componentPropObject).optional().describe(
       "REPLACES the prop array \u2014 include every prop you want to keep, WITH its stored `ui`, or that prop's authoring chrome is dropped along with the prop. Read get_component first."
@@ -4106,7 +4120,7 @@ function buildToolDefs(deps) {
     propGroup: z.record(z.string(), z.record(z.string(), z.unknown()).nullable()).optional().describe("prop key \u2192 its ui.group ({id, label?, kind?, icon?, collapsed?}), null takes it out"),
     propTab: z.record(z.string(), z.record(z.string(), z.unknown()).nullable()).optional().describe("prop key \u2192 its ui.tab ({id, label?, icon?, order?}), the V2 schema group it sits in. The FIRST top-level prop in a tab defines {id, label, icon?, order?}, later ones send {id}; \u22648 tabs; one group's members share one tab. null takes it out"),
     propLabel: z.record(z.string(), z.string().min(1).max(255)).optional().describe("prop key \u2192 label"),
-    propHelpText: z.record(z.string(), z.string().max(200).nullable()).optional().describe("prop key \u2192 help text, null clears it"),
+    propHelpText: z.record(z.string(), z.string().max(200).nullable()).optional().describe("prop key \u2192 help text; null = no help on purpose (stays empty, never refilled)"),
     override: z.boolean().optional().describe(OVERRIDE_NOTE),
     ifMatch: z.number().int().min(0).optional().describe(COMPONENT_IF_MATCH_NOTE),
     confirmed: z.boolean().optional().describe(PARAM_TEXT.confirmedInput)
@@ -6529,8 +6543,14 @@ Then declare what an editor may change, via \`props\`:
     ]
 
 Each prop also takes \`required\`, \`helpText\` (\u2264 200 chars) and \`placeholder\` (\u2264 120), which the
-dashboard's prop editor renders. They are HINTS: nothing on the write path refuses a placement
+dashboard's prop editor renders. \`helpText\` is three-state: a string is yours, \`null\` is no help on
+purpose (send it for a prop whose /kit schema has no description; nothing refills it), and omitted
+lets the platform write one. They are HINTS: nothing on the write path refuses a placement
 that leaves a required prop empty, so \`get_site_composition\` is what reports one.
+A /kit schema's document-level \`preview\` \u2192 the component's \`preview\`: how ONE instance reads as a ROW in a parent's slot list. {title?, subtitle?, media?} each name a TOP-LEVEL prop key (422 \`preview_key_unknown\` otherwise), \`fallback?\` is a literal row label (\u2264 120) and \`icon?\` a dock icon name; null clears it.
+A /kit schema's document-level \`icon\` \u2192 the component's \`icon\` (a dock icon name from bettercms://icons/dock, null clears): the block icon on the root crumb, slot rows and slot child frames.
+
+**Prop types, one rule each.** 'select' REQUIRES \`config.options\` (a default must be one of them). 'group'/'table'/'object' REQUIRE \`config.fields\` (\`[{key,label,type,options?,fields?}]\`); a group writes an object, a table an array of them (\`config.mode: 'data'\`: ONE V2 table value, no fields). 'number' takes optional \`config.min/max/step\`. 'slot' holds ONE nested component instance: \`target.path: 'props'\` on an EMPTY component block (\`props.componentId: ""\`), \`config.componentIds\` restricts fills, defaultValue \`{componentId, overrides?}\`. 'form' holds ONE Form document: \`target.path: 'props'\` on an EMPTY form block (\`props.formId: ""\`), defaultValue \`{formId}\`, never the hydrated \`{formId, form}\` (400); do NOT re-declare the form's FIELDS as props, the Form document owns them. 'button' is ONE unit \`{label, href, variant?, size?, arrow?, icon?, newTab?}\` on a button block's 'props', never a text prop plus a url prop. 'link' an href, 'date' YYYY-MM-DD, 'color' a hex, 'file' \`{url, name?}\`, 'icon' an icon name or an image, 'multiselect' a string[] from \`config.options\` (required).
 
 \u{1F534} **On a components-first page, \`props\` is the ONLY editing surface.** Click-to-edit binds
 \`heading\`/\`text\`/\`button\`/\`image\` blocks; it does **not** bind a \`component\` block, because
@@ -6582,9 +6602,16 @@ A \`slot\` field (V2 blocks inside a block) takes the same \`config.blockSlugs\`
 but stores each child INLINE: \`[{ _key, _type: '<block slug>', _variant?, _settings?, ...values }]\`,
 its values judged by its block's fields. A component's \`slot\` prop with \`config.multiple\`
 takes the same child shape with \`_type\` the COMPONENT id (no \`_variant\`: a variant is its own
-component). A list of several item shapes on a component is a \`table\` prop with
-\`config.mode: 'types'\` and \`config.itemTypes: [{ name, label?, fields }]\`, rows
-\`[{ _key?, _type: '<name>', ...values }]\`.
+component). A \`slot\` may also be a SUB-FIELD: inside a \`group\` / \`object\` prop's
+\`config.fields\` or a \`table\` row (an item type's \`fields\` too), with the slot prop's
+config keys (\`componentIds\`, \`multiple\`, \`minItems\`/\`maxItems\`, \`slotSettings\`). Its value
+sits at its key in the object or row, \`{ componentId, overrides? }\` or a list with
+\`config.multiple\`, judged like a slot prop's: the same allowlist, depth cap and cycle refusal.
+A list of several item shapes on a component is a \`table\` prop with
+\`config.mode: 'types'\` and \`config.itemTypes: [{ name, label?, fields, preview?, icon? }]\`, rows
+\`[{ _key?, _type: '<name>', ...values }]\`. An item type's \`preview\` names its OWN fields (dotted ok, \`<table>.caption\`).
+
+**Block props by type** (a block's \`props\` in any \`blockJson\`): heading {text, level 1-6}; text/richtext {html} (NOT {text}), both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only); image {src (asset url), alt, caption?}; button {text, href, variant (hosted pages; else a Button component), size sm|md|lg, fullWidth, arrow, icon (a ui.icon name), newTab, rel nofollow|sponsored|ugc}; spacer {height px}; video {url, poster?}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns:[{heading?,links}], copyright?}; section {children: block[], background?, paddingY?, maxWidth?}; columns {columns: block[][], gap} (a column may hold ANY block); slider {slides:[{id,children:block[]}]}; tabs {tabs:[{id,label,children:block[]}]}; collection {cardComponentId?, source? {modelId}, limit?, filters?, sort?, pinnedIds?, excludeCurrent?}: a collection's published entries as cards. Containers nest blocks to any depth.
 
 A component inside a \`richtext\` value is \`{ _type: 'bcmsBlock', _key, schemaKey: 'component',
 schemaLabel?, fields: { componentId, overrides?, variant? } }\` and FOLLOWS the component: publishing
@@ -7038,8 +7065,10 @@ hints the dashboard renders \u2014 they are NOT enforced at write time, so an ov
 required prop still saves; \`get_site_composition\` is what reports those. Use \`select\` with
 \`config.options\` for layout / theme / alignment / spacing variants that change only styling,
 and a SEPARATE variant component when the markup differs. Repeatable list \u2192 \`table\`; fixed
-cluster \u2192 \`group\`. Nesting is capped at TWO levels from the prop (a \`table\` row may hold a
-\`table\`, and that inner row is scalars only). Flatten anything deeper.
+cluster \u2192 \`group\`. Nesting goes up to 10 levels counting the prop itself. A \`table\` row may hold a
+\`table\` (rows), a data table (\`config.mode: "data"\`) or a polymorphic list
+(\`config.mode: "types"\`), so a size guide's rows can each carry a chart and a multi-step
+form's steps can each carry their fields. Deeper is refused (\`field_depth_exceeded\`).
 
 **5. Design, responsiveness and accessibility.** \`componentize_sections\` and \`npx
 @bettercms-ai/convert --componentize\` move the section's markup VERBATIM \u2014 classes, responsive
@@ -7234,7 +7263,7 @@ conversion is yours to write.
    markup inside a \`text\` field.
    **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
    this platform stores \u2014 \`block\`, \`table\` (\`{_type:"table", rows:[{_key, cells:[{_key,
-   content:[...blocks], header?, group?}], group?}], caption?, notes?, rowGroups?, columnGroups?}\`,
+   content:[...blocks], header?, group?, highlight?, sortable?}], group?, footer?, highlight?}], caption?, notes?, rowGroups?, columnGroups?, filterable?, jsonLd?: {type: "ItemList"|"Dataset"|"Offers", axis?, priceRow?}, design?: {responsive?: "stack"|"cards", sticky?}}\`,
    groups \`[{_key, label}]\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
    is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, \`pullQuote\`
    (\`{quote, name, role?, link?}\`), \`keyTakeaways\` (\`{title?, points:[...strings]}\`,
@@ -7406,7 +7435,7 @@ back each prop's stored \`ui\` or you delete it along with the prop. Props have
 prop joins a group with \`ui.group\`: the FIRST prop of a group defines \`{ id, label, kind?, icon?,
 collapsed? }\` (kind \`group\` or \`row\`; a tab is \`ui.tab\`, never a group kind), and every later prop
 sends \`{ id }\` only. A prop joins a TAB with \`ui.tab\` the same way: the FIRST top-level prop in a tab
-defines \`{ id, label, icon?, order? }\`, later props send \`{ id }\`; at most 8 tabs, labels \u226420 characters
+defines \`{ id, label, icon?, order? }\`, later props send \`{ id }\`; at most 8 tabs, labels \u226440 characters
 and unique; top-level props only (never a sub-field); all members of one \`ui.group\` share one tab. A V2
 kit entry's schema \`groups\` and each field's \`group\` map 1:1 to \`ui.tab\`, so its \`design\` group is a
 tab named Design holding the theme, sticky and similar props. A FIELD never takes \`ui.group\` or
@@ -7484,7 +7513,7 @@ Importance orders a screen: required fields first, then array order.
 An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`openMode_leaf\`; a bad \`config.scale\` with \`scale_invalid\`; more than 10 nested field levels with \`field_depth_exceeded\`. update_field sets and clears (null) helpMore, advanced, recommendedMax and openMode on an existing field.
 
 **Tabs.** A \`kind: 'tab'\` fieldset is a tab:
-- at most **3** tabs, names at most 20 characters and unique;
+- at most **3** tabs, names at most 40 characters and unique;
 - top-level fields only: tabs never nest (a component's props take tabs through \`ui.tab\`, its own rules);
 - untabbed fields stay PINNED above the strip;
 - a group or row fieldset joins a tab with \`tab: '<tab id>'\`; groups in a non-first tab default open;
@@ -7766,7 +7795,7 @@ Read \`bettercms://playbook/schema\` \xA712 first \u2014 this is the short form
 4. **Fields** = \`props\`: text, richtext, image, url, boolean, number, select, group, table, slot.
    Always a \`defaultValue\`; \`required\` / \`helpText\` / \`placeholder\` are editor hints, not write
    -time enforcement. \`select\` for styling-only variants, a separate component when the markup
-   differs. Nesting is capped at two levels \u2014 flatten anything deeper.
+   differs. Nesting goes up to 10 levels; a \`table\` row may hold a data table or a polymorphic list.
 5. **Quality.** The componentize lane and \`npx @bettercms-ai/convert --componentize\` move markup
    VERBATIM \u2014 classes, responsive utilities, aria attributes, alt text all survive. Never
    restyle. Dry-run first.