@bettercms-ai/mcp 0.73.0 → 0.73.1

package/dist/index.js

@@ -2989,6 +2989,7 @@ 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: "how ONE instance reads as a ROW in a parent's slot list (a /kit schema's document-level `preview`): {title?, subtitle?, media?} each a TOP-LEVEL prop key (422 preview_key_unknown otherwise), fallback? a literal row label (\u2264120), icon? a dock icon name. null clears it",
   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 +3035,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 +3269,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 +3665,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();
@@ -3971,6 +3972,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 +3984,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 +4073,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 +4091,7 @@ 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(),
     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 +4108,7 @@ 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(),
     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 +4117,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 +6540,11 @@ 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\` ({title?, subtitle?, media?} are top-level prop keys, plus \`fallback?\`, \`icon?\`); slot rows read it.
 
 \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,7 +6596,12 @@ 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
+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 }]\`, rows
 \`[{ _key?, _type: '<name>', ...values }]\`.
 
@@ -7038,8 +7057,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
@@ -7406,7 +7427,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 +7505,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 +7787,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.