@designcrowd/library.brand-page 5.17.28 → 5.18.0

package/lib/src/metadata-builder/models.js

@@ -27,6 +27,7 @@ export const BUILDER_TYPES = {
     CREATE_PINTEREST: 'create-pinterest',
     CREATE_TWITCH: 'create-twitch',
     CREATE_TIKTOK: 'create-tiktok',
+    CREATE_BOOKING_SECTION: 'create-booking-section',
     // Per-section builder types (update)
     UPDATE_BANNER_SECTION: 'update-banner-section',
     UPDATE_ABOUT_SECTION: 'update-about-section',
@@ -52,19 +53,31 @@ export const BUILDER_TYPES = {
     UPDATE_PINTEREST: 'update-pinterest',
     UPDATE_TWITCH: 'update-twitch',
     UPDATE_TIKTOK: 'update-tiktok',
+    UPDATE_BOOKING_SECTION: 'update-booking-section',
     // Section-level operations
     DELETE_SECTION: 'delete-section',
     MOVE_SECTION: 'move-section',
     // Page-level operations
     ADD_PAGE: 'add-page',
     REMOVE_PAGE: 'remove-page',
+    RENAME_PAGE: 'rename-page',
+    // Footer operations
+    UPDATE_FOOTER: 'update-footer',
+    // Global styles operations
+    UPDATE_GLOBAL_STYLES: 'update-global-styles',
+    // Header operations
+    UPDATE_HEADER: 'update-header',
+    // Website-level operations
+    UNDO_WEBSITE: 'undo-website',
 };
 export class BaseMetadataBuilder {
     request;
     logger;
-    constructor(request, logger) {
+    eventTracker;
+    constructor(request, logger, eventTracker) {
         this.request = request;
         this.logger = logger;
+        this.eventTracker = eventTracker;
     }
     log(argument) {
         if (this.logger) {

package/lib/src/metadata-builder/parsers/ai-toolcall-parser.d.ts

@@ -1,4 +1,5 @@
 import type { AiAssistantToolCall } from '../../clients/ai-assistant-client';
+import type { FooterDisplayStyle, HeaderDisplayStyle, NavigationDisplayType } from '../../brand-page/constants';
 import type { SectionType } from './section-tool-arguments';
 export declare const AI_ASSISTANT_TOOL_NAMES: {
     readonly UPDATE_TEXT: "updateText";
@@ -28,10 +29,16 @@ export declare const AI_ASSISTANT_TOOL_NAMES: {
     readonly BUILD_SHAPES_SECTION: "build_shapes-section_section";
     readonly BUILD_TESTIMONIAL_SECTION: "build_testimonial-section_section";
     readonly BUILD_DIVIDER_SECTION: "build_divider-section_section";
+    readonly BUILD_BOOKING_SECTION: "build_booking-section_section";
     readonly DELETE_SECTION: "delete_section";
     readonly MOVE_SECTION: "move_section";
     readonly ADD_PAGE: "add_page";
     readonly REMOVE_PAGE: "remove_page";
+    readonly RENAME_PAGE: "rename_page";
+    readonly UPDATE_FOOTER: "update_footer";
+    readonly UPDATE_GLOBAL_STYLES: "tool_update_global_styles";
+    readonly UPDATE_HEADER: "update_header";
+    readonly UNDO: "undo";
 };
 export type AiAssistantToolName = (typeof AI_ASSISTANT_TOOL_NAMES)[keyof typeof AI_ASSISTANT_TOOL_NAMES];
 export interface ParsedToolCall {
@@ -75,4 +82,141 @@ export interface AddPageArguments {
 export interface RemovePageArguments {
     page_id: string;
 }
+export interface RenamePageArguments {
+    page_id: string;
+    page_name: string;
+}
+export interface ReorderPagesArguments {
+    page_order: string[];
+}
+/**
+ * Arguments for the `undo` tool call.
+ *
+ * Empty by design: the snapshot to restore is determined externally (it's the
+ * snapshot taken before the most recent change-producing prompt). The library
+ * does not own snapshot persistence.
+ */
+export interface UndoArguments {
+}
+export interface FooterSocialLinkItem {
+    item_index?: number;
+    insert_at?: number;
+    social_link_icon?: string;
+    url?: string;
+}
+/**
+ * Per-viewport field overrides for a single update_footer call with viewport='both'.
+ * Fields set here take precedence over the top-level value for that specific viewport.
+ */
+export interface ViewportFooterOverrides {
+    display_style?: FooterDisplayStyle;
+    background_color?: string | null;
+    copyright_text_color?: string;
+    icon_color?: string;
+    is_logo_visible?: boolean;
+    logo_image_height?: string;
+    logo_image_width?: string;
+}
+export interface UpdateFooterArguments {
+    copyright_text?: string;
+    copyright_text_font_family?: string;
+    social_links?: FooterSocialLinkItem[];
+    _replace_social_links?: boolean;
+    _remove_social_link_indices?: number[];
+    _reorder_social_links?: number[];
+    /** Desktop-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */
+    desktop?: ViewportFooterOverrides;
+    /** Mobile-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */
+    mobile?: ViewportFooterOverrides;
+}
+export interface TextStyleOptionStyle {
+    fontFamily?: string;
+    fontSize?: string;
+    letterSpacing?: string;
+    lineHeight?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    textDecoration?: string;
+    color?: string;
+}
+export interface UpdateGlobalStylesArguments {
+    backgroundStyles?: {
+        style?: {
+            background?: string;
+        };
+        /** Site background color in hex → sets style.background */
+        backgroundColor?: string;
+        /** Background shape/accent color in hex → sets backgroundShapeStyle.background */
+        shapeColor?: string;
+        /** Background image URL ('' clears the image) → sets backgroundImageUrl */
+        backgroundImageUrl?: string;
+        /** Background shape SVG URL ('' clears shapes) → updates backgroundShapes[0].name. No-op if backgroundShapes is empty. */
+        backgroundShapeUrl?: string;
+    };
+    textStyles?: {
+        style?: {
+            color?: string;
+        };
+        textFontFamily?: string;
+        textStyleOptions?: {
+            titles?: {
+                style?: TextStyleOptionStyle;
+                isModified?: boolean;
+            };
+            headings?: {
+                style?: TextStyleOptionStyle;
+                isModified?: boolean;
+            };
+            paragraphs?: {
+                style?: TextStyleOptionStyle;
+                isModified?: boolean;
+            };
+            buttons?: {
+                style?: TextStyleOptionStyle;
+                isModified?: boolean;
+            };
+        };
+    };
+    buttonStyles?: {
+        style?: {
+            color?: string;
+            borderColor?: string;
+            backgroundColor?: string;
+        };
+        iconStyle?: {
+            fill?: string;
+        };
+        selectedButtonStyleId?: string;
+    };
+}
+export interface UpdateHeaderNavRoute {
+    route_index?: number;
+    display_name?: string;
+}
+export interface ViewportHeaderOverrides {
+    display_style?: HeaderDisplayStyle;
+    background_color?: string | null;
+    is_logo_visible?: boolean;
+    logo_image_height?: string;
+    logo_image_width?: string;
+    nav_display_type?: NavigationDisplayType;
+    link_text_color?: string;
+    link_text_font?: string;
+    link_bg_color?: string | null;
+    link_default_border_color?: string | null;
+    link_selected_color?: string;
+    link_selected_bg_color?: string | null;
+    link_selected_border_color?: string;
+    hamburger_icon_color?: string;
+    hamburger_icon_bg_color?: string | null;
+    overlay_default_text_color?: string | null;
+    overlay_default_bg_color?: string | null;
+    overlay_selected_text_color?: string | null;
+    overlay_selected_bg_color?: string | null;
+}
+export interface UpdateHeaderArguments {
+    nav_routes?: UpdateHeaderNavRoute[];
+    desktop?: ViewportHeaderOverrides;
+    mobile?: ViewportHeaderOverrides;
+}
 export declare const parseToolCalls: (toolCalls: AiAssistantToolCall[]) => ParsedToolCall[];

package/lib/src/metadata-builder/parsers/ai-toolcall-parser.js

@@ -33,12 +33,26 @@ export const AI_ASSISTANT_TOOL_NAMES = {
     BUILD_SHAPES_SECTION: 'build_shapes-section_section',
     BUILD_TESTIMONIAL_SECTION: 'build_testimonial-section_section',
     BUILD_DIVIDER_SECTION: 'build_divider-section_section',
+    BUILD_BOOKING_SECTION: 'build_booking-section_section',
     // Section-level operation tools
     DELETE_SECTION: 'delete_section',
     MOVE_SECTION: 'move_section',
     // Page-level operation tools
     ADD_PAGE: 'add_page',
     REMOVE_PAGE: 'remove_page',
+    RENAME_PAGE: 'rename_page',
+    // Footer operation tools
+    UPDATE_FOOTER: 'update_footer',
+    // Global styles operation tools
+    UPDATE_GLOBAL_STYLES: 'tool_update_global_styles',
+    // Header operation tools
+    UPDATE_HEADER: 'update_header',
+    // Website-level operations
+    // `undo` restores the website to the snapshot taken before the most recent
+    // change-producing prompt. The actual snapshot restore is performed outside
+    // this library — the library only recognizes the tool call and signals the
+    // request via BuilderResult.undoRequested.
+    UNDO: 'undo',
 };
 // Maps each section tool name to its SectionType.
 // Mode is now determined from the tool arguments, not the tool name.
@@ -94,6 +108,9 @@ export const SECTION_TOOL_MAP = {
     [AI_ASSISTANT_TOOL_NAMES.BUILD_DIVIDER_SECTION]: {
         sectionType: 'divider-section',
     },
+    [AI_ASSISTANT_TOOL_NAMES.BUILD_BOOKING_SECTION]: {
+        sectionType: 'booking-section',
+    },
 };
 export const parseToolCalls = (toolCalls) => {
     if (!toolCalls || toolCalls.length === 0) {

package/lib/src/metadata-builder/parsers/section-tool-arguments.d.ts

@@ -6,8 +6,39 @@
  */
 import type { ContentType } from '../../brand-page/models';
 /** Content types not supported by the AI builder. */
-type UnsupportedContentType = 'logo' | 'video' | 'map' | 'request-payment' | 'support-me' | 'shop-section' | 'booking-section';
+type UnsupportedContentType = 'logo' | 'video' | 'map' | 'request-payment' | 'support-me' | 'shop-section';
 export type SectionType = Exclude<ContentType, UnsupportedContentType>;
+export interface TiptapMark {
+    type: 'bold' | 'italic' | 'underline' | 'strike' | 'link' | 'textStyle' | 'highlight';
+    attrs?: {
+        href?: string;
+        color?: string;
+        fontSize?: string;
+        fontFamily?: string;
+        letterSpacing?: string;
+        lineHeight?: string;
+    };
+}
+export interface TiptapTextNode {
+    type: 'text';
+    text: string;
+    marks?: TiptapMark[];
+}
+export interface TiptapBlockNode {
+    type: 'paragraph' | 'heading' | 'blockquote';
+    attrs?: {
+        level?: number;
+    };
+    content?: TiptapTextNode[];
+}
+export interface TiptapDocument {
+    type: 'doc';
+    content: TiptapBlockNode[];
+}
+/** A rich text field can be plain text (string) or Tiptap JSON. */
+export type RichTextField = string | TiptapDocument;
+/** Type guard: checks if a value is a TiptapDocument object. */
+export declare const isTiptapDocument: (value: unknown) => value is TiptapDocument;
 export interface TextStyleArguments {
     fontSize?: string | null;
     color?: string | null;
@@ -17,7 +48,32 @@ export interface TextStyleArguments {
     textDecoration?: string | null;
     backgroundColor?: string | null;
     letterSpacing?: number | null;
-    lineHeight?: number | null;
+    lineHeight?: string | null;
+    fontFamily?: string | null;
+}
+/**
+ * Style schema for button label text. Narrower than `TextStyleArguments`:
+ * `backgroundColor` is excluded because a button label has no meaningful
+ * background (the button fill behind the label is set at the site level).
+ *
+ * `color` IS included — the brand-page renderer reads
+ * `section.button_text_style.color` for label paint. The VALUE is the
+ * site-level DECISION (`site.button-text` in the AI's color_spec), but
+ * the APPLICATION is per-section: every section's tool call writes the
+ * same site-decided hex into this field.
+ *
+ * See `ai-pipelines/src/agents/website/tools/section_types_tool.py`
+ * (`_button_text_style_field`) for the AI-side mirror.
+ */
+export interface ButtonTextStyleArguments {
+    color?: string | null;
+    fontSize?: string | null;
+    fontWeight?: string | null;
+    fontStyle?: string | null;
+    textAlign?: string | null;
+    textDecoration?: string | null;
+    letterSpacing?: number | null;
+    lineHeight?: string | null;
     fontFamily?: string | null;
 }
 export interface BackgroundStyleArguments {
@@ -29,9 +85,9 @@ export interface CardStyleArguments {
     borderColor?: string | null;
 }
 export interface ProfileSectionArguments {
-    name?: string;
-    title?: string;
-    description?: string;
+    name?: RichTextField;
+    title?: RichTextField;
+    description?: RichTextField;
     avatar_image_url?: string;
     background_color?: string | null;
 }
@@ -40,12 +96,12 @@ export interface TextSectionItem {
     item_index?: number;
     /** 0-based position to insert a new item at */
     insert_at?: number;
-    text?: string;
+    text?: RichTextField;
     text_style?: TextStyleArguments;
 }
 export interface TextSectionArguments {
     /** Single text field (BrandPage/BrandContact or shorthand for first item) */
-    text?: string;
+    text?: RichTextField;
     text_style?: TextStyleArguments;
     /** Number of columns ('1'–'4') for multi-block text layouts */
     column_style?: '1' | '2' | '3' | '4';
@@ -73,6 +129,7 @@ export interface ImageGalleryItem {
 export interface ImageGallerySectionArguments {
     images?: ImageGalleryItem[];
     gallery_type?: 'grid' | 'carousel' | 'masonry';
+    is_full_width?: boolean;
     _replace_items?: boolean;
     /** 0-based indices of items to remove */
     _remove_item_indices?: number[];
@@ -142,6 +199,10 @@ export interface SocialLink {
 export interface SocialLinksSectionArguments {
     links?: SocialLink[];
     icon_style?: 'none' | 'square' | 'circle';
+    /** Style for the social-icon SVG fill (filled from the palette by the slot router). */
+    icon_fill_style?: TextStyleArguments;
+    /** Style for the icon container background (used when icon_style is 'square' or 'circle'). */
+    icon_background_style?: TextStyleArguments;
     _replace_items?: boolean;
     /** 0-based indices of items to remove */
     _remove_item_indices?: number[];
@@ -149,8 +210,11 @@ export interface SocialLinksSectionArguments {
     _reorder_items?: number[];
 }
 export interface MailingListSectionArguments {
-    title?: string;
+    title?: RichTextField;
     button_text?: string;
+    accepted_fields?: 'emailOnly' | 'nameAndEmail';
+    title_style?: TextStyleArguments;
+    button_text_style?: ButtonTextStyleArguments;
 }
 export interface ContactFormFieldToggle {
     /** Field ID matching FORM_FIELD_IDS (e.g., 'firstName', 'lastName', 'phoneNumber', 'message') */
@@ -159,37 +223,45 @@ export interface ContactFormFieldToggle {
     enabled: boolean;
 }
 export interface ContactFormSectionArguments {
-    title?: string;
-    description?: string;
+    title?: RichTextField;
+    description?: RichTextField;
     button_text?: string;
-    success_message?: string;
+    success_message?: RichTextField;
     response_email?: string;
     header_image_url?: string;
     display_style?: 'preview' | 'collapsed';
     layout_style?: 'center-card-aligned' | 'centered' | 'text-only' | 'center-card-aligned-image' | 'left-aligned-full-image' | 'right-aligned-full-image';
     title_style?: TextStyleArguments;
     description_style?: TextStyleArguments;
-    button_text_style?: TextStyleArguments;
+    success_message_style?: TextStyleArguments;
+    button_text_style?: ButtonTextStyleArguments;
     /** Toggle visibility of form fields */
     fields?: ContactFormFieldToggle[];
     background_color?: string | null;
+    card_style?: CardStyleArguments;
 }
 export interface BannerSectionArguments {
-    title?: string;
-    description?: string;
+    title?: RichTextField;
+    description?: RichTextField;
     button_text?: string;
+    button_link_type?: 'url' | 'page' | 'mailTo' | 'tel';
     button_url?: string;
     background_image_url?: string;
+    background_shape_url?: string;
+    color_theme?: string;
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'big-image' | 'left-aligned-big-image' | 'right-aligned-full-image' | 'left-aligned-full-image' | 'center-card-aligned-image' | 'left-card-aligned-image';
     title_style?: TextStyleArguments;
     description_style?: TextStyleArguments;
-    button_text_style?: TextStyleArguments;
+    button_text_style?: ButtonTextStyleArguments;
     background_color?: string | null;
+    card_style?: CardStyleArguments;
 }
 export interface AboutSectionArguments {
-    title?: string;
-    paragraph?: string;
+    title?: RichTextField;
+    paragraph?: RichTextField;
     about_image_url?: string;
+    about_shape_url?: string;
+    color_theme?: string;
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'text-only' | 'left-aligned-full-image' | 'right-aligned-full-image';
     title_style?: TextStyleArguments;
     paragraph_style?: TextStyleArguments;
@@ -206,8 +278,8 @@ export interface ImagesSectionItem {
     button_text?: string;
 }
 export interface ImagesSectionArguments {
-    title?: string;
-    description?: string;
+    title?: RichTextField;
+    description?: RichTextField;
     items?: ImagesSectionItem[];
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'media-only' | 'center-card-aligned-image' | 'alternate-image';
     _replace_items?: boolean;
@@ -219,6 +291,7 @@ export interface ImagesSectionArguments {
     description_style?: TextStyleArguments;
     heading_style?: TextStyleArguments;
     paragraph_style?: TextStyleArguments;
+    button_text_style?: ButtonTextStyleArguments;
     aspect_ratio?: string;
     are_images_full_width?: boolean;
     background_style?: BackgroundStyleArguments;
@@ -233,9 +306,11 @@ export interface TestimonialItem {
     name?: string;
     position?: string;
     avatar_image_url?: string;
+    avatar_shape_url?: string;
+    color_theme?: string;
 }
 export interface TestimonialSectionArguments {
-    title?: string;
+    title?: RichTextField;
     items?: TestimonialItem[];
     display_style?: 'centered' | 'big-image' | 'columns';
     _replace_items?: boolean;
@@ -257,13 +332,13 @@ export interface ShapesSectionItem {
     insert_at?: number;
     icon_image_url?: string;
     shape_url?: string;
-    keep_color?: boolean;
+    color_theme?: string;
     heading?: string;
     text?: string;
 }
 export interface ShapesSectionArguments {
-    title?: string;
-    description?: string;
+    title?: RichTextField;
+    description?: RichTextField;
     items?: ShapesSectionItem[];
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'media-only' | 'center-card-aligned-image' | 'alternate-image';
     _replace_items?: boolean;
@@ -279,16 +354,30 @@ export interface ShapesSectionArguments {
     background_style?: BackgroundStyleArguments;
     card_style?: CardStyleArguments;
 }
+export interface BookingSectionArguments {
+    title?: RichTextField;
+    description?: RichTextField;
+    button_text?: string;
+    button_link_type?: 'url' | 'page' | 'mailTo' | 'tel';
+    button_url?: string;
+    title_style?: TextStyleArguments;
+    description_style?: TextStyleArguments;
+    button_text_style?: ButtonTextStyleArguments;
+    background_color?: string | null;
+}
 export interface DividerSectionArguments {
     divider_style?: 'none' | 'thin' | 'thick';
+    divider_color?: string | null;
     background_color?: string | null;
+    padding?: number;
 }
-export type SectionToolArguments = ProfileSectionArguments | TextSectionArguments | ImageSectionArguments | ImageGallerySectionArguments | GeneralLinkSectionArguments | WebsiteSectionArguments | EmailSectionArguments | PhoneSectionArguments | FacebookSectionArguments | XSectionArguments | InstagramSectionArguments | YoutubeSectionArguments | LinkedinSectionArguments | PinterestSectionArguments | TwitchSectionArguments | TiktokSectionArguments | SocialLinksSectionArguments | MailingListSectionArguments | ContactFormSectionArguments | BannerSectionArguments | AboutSectionArguments | ImagesSectionArguments | TestimonialSectionArguments | ShapesSectionArguments | DividerSectionArguments;
+export type SectionToolArguments = ProfileSectionArguments | TextSectionArguments | ImageSectionArguments | ImageGallerySectionArguments | GeneralLinkSectionArguments | WebsiteSectionArguments | EmailSectionArguments | PhoneSectionArguments | FacebookSectionArguments | XSectionArguments | InstagramSectionArguments | YoutubeSectionArguments | LinkedinSectionArguments | PinterestSectionArguments | TwitchSectionArguments | TiktokSectionArguments | SocialLinksSectionArguments | MailingListSectionArguments | ContactFormSectionArguments | BannerSectionArguments | AboutSectionArguments | ImagesSectionArguments | TestimonialSectionArguments | ShapesSectionArguments | BookingSectionArguments | DividerSectionArguments;
 export interface SectionToolCallShape {
     mode: 'create' | 'update';
     type: string;
     content_id?: string;
     page_id?: string;
+    move_before_content_id?: string;
     arguments: SectionToolArguments;
 }
 export {};

package/lib/src/metadata-builder/parsers/section-tool-arguments.js

@@ -4,4 +4,8 @@
  * Canonical reference: service.ai-pipelines/src/agents/website/section_schemas.py
  * Every field defined there has a corresponding TS field here.
  */
-export {};
+/** Type guard: checks if a value is a TiptapDocument object. */
+export const isTiptapDocument = (value) => typeof value === 'object' &&
+    value !== null &&
+    value.type === 'doc' &&
+    Array.isArray(value.content);

package/lib/src/metadata-builder/sanitizers/rte-schema-check.d.ts

@@ -0,0 +1,22 @@
+import { type SectionCheck } from './section-args-validator';
+/**
+ * Validates a Tiptap doc against the headless editor's real ProseMirror
+ * schema (`schema.nodeFromJSON`). Catches malformed AI input — stray
+ * non-node children in `content`, unknown node types, malformed attrs —
+ * before the builder runs and the renderer's silent `setContent` drops
+ * the doc to `<p></p>` (BP-5669).
+ *
+ * Returns the field-prefixed error string so the AI's tool-call retry
+ * loop reads it via `BuilderResult.errors` → `tool_result.errorMessage`
+ * and re-emits a corrected payload.
+ */
+export declare const rteSchemaCheck: (field: string) => SectionCheck;
+/**
+ * Returns [rteSchemaCheck(field), textCheck(field, max), rteStyleCheck(field)].
+ * Use with spread in a CHECKS array to validate the Tiptap doc structure
+ * (against the editor's real ProseMirror schema), plain text length, and
+ * inline RTE mark styles for the same field. Schema check runs first so
+ * a malformed doc surfaces an actionable error to the AI retry loop
+ * before the renderer can silently swallow it.
+ */
+export declare const textAndRteChecks: (field: string, max: number) => SectionCheck[];

package/lib/src/metadata-builder/sanitizers/rte-schema-check.js

@@ -0,0 +1,84 @@
+import { Editor } from '@tiptap/vue-3';
+import StarterKit from '@tiptap/starter-kit';
+import Underline from '@tiptap/extension-underline';
+import TextStyle from '@tiptap/extension-text-style';
+import TextAlign from '@tiptap/extension-text-align';
+import FontFamily from '@tiptap/extension-font-family';
+import ColorExtension from '@tiptap/extension-color';
+import Highlight from '@tiptap/extension-highlight';
+import Link from '@tiptap/extension-link';
+import { FontSize } from '../../brand-page-maker/composables/rich-text-editor/extensions/FontSize';
+import { LetterSpacing } from '../../brand-page-maker/composables/rich-text-editor/extensions/LetterSpacing';
+import { LineHeight } from '../../brand-page-maker/composables/rich-text-editor/extensions/LineHeight';
+import { AutoLink } from '../../brand-page-maker/composables/rich-text-editor/extensions/AutoLink';
+import { isTiptapDocument } from '../parsers/section-tool-arguments';
+import { rteStyleCheck, textCheck, } from './section-args-validator';
+/**
+ * Constructs a headless Tiptap Editor with the same extension set as
+ * `useExternalRichTextEditor` in the maker. We import the Tiptap extension
+ * files directly (they are leaf modules) instead of going through the maker
+ * composable, which would pull in the AI executor → section-builders →
+ * section-rules graph and re-enter this file before its exports are bound.
+ */
+const buildHeadlessEditor = () => new Editor({
+    editable: false,
+    extensions: [
+        StarterKit,
+        Underline,
+        TextStyle.configure({ mergeNestedSpanStyles: true }),
+        TextAlign.configure({ types: ['heading', 'paragraph'] }),
+        FontFamily.configure({ types: ['textStyle'] }),
+        FontSize,
+        LetterSpacing,
+        LineHeight,
+        ColorExtension.configure({ types: ['textStyle'] }),
+        Highlight.configure({ multicolor: true }),
+        Link.configure({
+            openOnClick: false,
+            defaultProtocol: 'https',
+            autolink: true,
+        }),
+        AutoLink,
+    ],
+});
+/**
+ * Validates a Tiptap doc against the headless editor's real ProseMirror
+ * schema (`schema.nodeFromJSON`). Catches malformed AI input — stray
+ * non-node children in `content`, unknown node types, malformed attrs —
+ * before the builder runs and the renderer's silent `setContent` drops
+ * the doc to `<p></p>` (BP-5669).
+ *
+ * Returns the field-prefixed error string so the AI's tool-call retry
+ * loop reads it via `BuilderResult.errors` → `tool_result.errorMessage`
+ * and re-emits a corrected payload.
+ */
+export const rteSchemaCheck = (field) => (record) => {
+    const value = record[field];
+    if (!isTiptapDocument(value))
+        return null;
+    const editor = buildHeadlessEditor();
+    try {
+        editor.schema.nodeFromJSON(value);
+        return null;
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `"${field}" is not valid Tiptap JSON: ${detail}`;
+    }
+    finally {
+        editor.destroy();
+    }
+};
+/**
+ * Returns [rteSchemaCheck(field), textCheck(field, max), rteStyleCheck(field)].
+ * Use with spread in a CHECKS array to validate the Tiptap doc structure
+ * (against the editor's real ProseMirror schema), plain text length, and
+ * inline RTE mark styles for the same field. Schema check runs first so
+ * a malformed doc surfaces an actionable error to the AI retry loop
+ * before the renderer can silently swallow it.
+ */
+export const textAndRteChecks = (field, max) => [
+    rteSchemaCheck(field),
+    textCheck(field, max),
+    rteStyleCheck(field),
+];

package/lib/src/metadata-builder/sanitizers/sanitizer-rules.d.ts

@@ -0,0 +1,47 @@
+/**
+ * sanitizer-rules.ts
+ *
+ * Shared style/logo/page constraint rules and the SectionRules interface.
+ * Per-section rules live colocated with each builder (e.g. banner-section.rules.ts).
+ */
+export declare const STYLE_RULES: {
+    readonly fontUnit: {
+        readonly allowedUnits: readonly ["em"];
+    };
+    readonly fontSize: {
+        readonly minEm: string;
+        readonly maxEm: string;
+    };
+    readonly lineHeight: {
+        readonly min: 1;
+        readonly max: 2.5;
+    };
+    readonly letterSpacing: {
+        readonly min: 0;
+        readonly max: 100;
+    };
+    readonly fontFamilyNames: Set<string>;
+    readonly fontFamilyKeys: Set<string>;
+};
+export declare const LOGO_SIZE_RULES: {
+    readonly unit: "rem";
+    readonly desktop: {
+        readonly min: 1;
+        readonly max: 20;
+    };
+    readonly mobile: {
+        readonly min: 1;
+        readonly max: 13;
+    };
+};
+export declare const PAGE_RULES: {
+    readonly pageName: 30;
+    readonly subPageName: 20;
+    readonly navDisplayName: 30;
+};
+export interface ItemCapRule {
+    brandSite: number;
+    brandPage: number;
+    /** The args field name that holds the items array (e.g. 'items', 'links'). */
+    arrayField: string;
+}