@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/nlp/deterministic-planner-suggestions.js

@@ -0,0 +1,579 @@
+import { z } from "zod";
+import { allowedBlockTypes, blockSchemas, getAllBlockMeta, getBlockMeta, getPropDisplayName, deriveFieldMetaFromSchema } from "@avocadostudio-ai/shared";
+export function editablePropsFromBlock(block) {
+    if (!block || !block.props || typeof block.props !== "object")
+        return [];
+    return Object.keys(block.props);
+}
+const CLARIFICATION_LABELS = {
+    heading: "Edit heading",
+    subheading: "Edit subheading",
+    ctaText: "Edit CTA",
+    ctaHref: "Update link",
+    imageUrl: "Replace image",
+    imageAlt: "Write alt",
+    secondaryCtaText: "Add CTA",
+    secondaryCtaHref: "Update link",
+    body: "Edit body",
+    title: "Edit title",
+    description: "Edit description",
+    features: "Edit features",
+    items: "Edit items",
+    cards: "Edit cards",
+    left: "Edit left column",
+    right: "Edit right column",
+    columns: "Edit columns",
+    children: "Edit content",
+    content: "Edit content"
+};
+export function promptFromPropKey(propKey, blockType) {
+    if (CLARIFICATION_LABELS[propKey])
+        return CLARIFICATION_LABELS[propKey];
+    const human = blockType ? getPropDisplayName(blockType, propKey) : propKey;
+    // Fall back to the registry-declared label so host-app overrides (e.g.
+    // villa's TwoColumn adding `sectionId`) surface as "Edit Section id" rather
+    // than leaking the raw camelCase key into the UI.
+    return human === propKey ? `Edit ${propKey}` : `Edit ${human.toLowerCase()}`;
+}
+// Keys we never want to surface as clarification chips — they're structural
+// identifiers, layout style enums, or other non-content props that users don't
+// "edit" as a primary action. Host apps add these via TwoColumn / Card / etc.
+const NON_CONTENT_PROP_KEYS = new Set([
+    "sectionId",
+    "anchor",
+    "id",
+    "variant",
+    "style",
+    "theme",
+    "layout",
+    "align",
+    "alignment"
+]);
+function rankPropKeysForClarification(blockType, keys) {
+    const meta = getBlockMeta(blockType);
+    const listKeys = new Set(meta?.listFields ? Object.keys(meta.listFields) : []);
+    // Derive from CLARIFICATION_LABELS so adding a new label automatically
+    // updates the ranker — single source of truth.
+    const known = new Set(Object.keys(CLARIFICATION_LABELS));
+    const score = (k) => {
+        if (NON_CONTENT_PROP_KEYS.has(k))
+            return 3;
+        if (listKeys.has(k))
+            return 0;
+        if (known.has(k))
+            return 1;
+        return 2;
+    };
+    return [...keys].sort((a, b) => score(a) - score(b));
+}
+export function userFacingPropNames(blockType, keys) {
+    return keys.map((key) => getPropDisplayName(blockType, key));
+}
+export const ORDINALS = ["first", "second", "third", "fourth", "fifth", "sixth", "seventh", "eighth", "ninth", "tenth"];
+export function humanizeArrayPath(root) {
+    const match = root.match(/^([a-zA-Z_]+)\[(\d+)\]$/);
+    if (!match)
+        return root;
+    const [, listName, indexStr] = match;
+    const index = Number(indexStr);
+    const ordinal = ORDINALS[index] ?? `#${index + 1}`;
+    const singular = {
+        cards: "card",
+        features: "feature",
+        items: "item",
+        stats: "stat",
+        columns: "column"
+    };
+    const noun = singular[listName] ?? listName.replace(/s$/, "");
+    return `the ${ordinal} ${noun}`;
+}
+export function childSuggestions(args) {
+    const { selected, editablePath } = args;
+    const path = editablePath.trim();
+    if (!path)
+        return [];
+    const root = path.split(".")[0] ?? path;
+    const human = humanizeArrayPath(root);
+    if (selected.type === "CardGrid" && root.startsWith("cards[")) {
+        return [
+            `Edit ${human}'s title`,
+            `Edit ${human}'s description`,
+            `Edit ${human}'s CTA`,
+            `Update ${human}'s link`
+        ];
+    }
+    if (selected.type === "FeatureGrid" && root.startsWith("features[")) {
+        return [`Edit ${human}'s title`, `Edit ${human}'s description`];
+    }
+    if (selected.type === "Testimonials" && root.startsWith("items[")) {
+        return [`Edit ${human}'s quote`, `Edit ${human}'s author`];
+    }
+    if (selected.type === "FAQAccordion" && root.startsWith("items[")) {
+        return [`Edit ${human}'s question`, `Edit ${human}'s answer`];
+    }
+    return [`Edit ${human}`];
+}
+export function clarificationSuggestions(args) {
+    const { selected, current } = args;
+    if (selected) {
+        const allKeys = editablePropsFromBlock(selected);
+        const ranked = rankPropKeysForClarification(selected.type, allKeys);
+        // Drop non-content props (sectionId, variant, etc.) unless we have nothing else.
+        const contentKeys = ranked.filter((k) => !NON_CONTENT_PROP_KEYS.has(k));
+        const candidate = contentKeys.length > 0 ? contentKeys : ranked;
+        if (candidate.length > 0)
+            return candidate.slice(0, 4).map((k) => promptFromPropKey(k, selected.type));
+        return [
+            `Edit ${selected.type}`,
+            `Move ${selected.type}`
+        ];
+    }
+    const suggestions = [];
+    const existingTypes = new Set(current.blocks.map((b) => b.type));
+    const first = current.blocks[0];
+    if (first)
+        suggestions.push(`Edit ${first.type}`);
+    if (!existingTypes.has("Testimonials"))
+        suggestions.push("Add Testimonials");
+    else if (!existingTypes.has("FAQAccordion"))
+        suggestions.push("Add FAQ");
+    else if (!existingTypes.has("CardGrid"))
+        suggestions.push("Add CardGrid");
+    if (existingTypes.has("FAQAccordion"))
+        suggestions.push("Move FAQ");
+    else if (existingTypes.has("CTA"))
+        suggestions.push("Edit CTA");
+    if (suggestions.length === 0)
+        suggestions.push("Edit heading", "Add Testimonials");
+    return suggestions.slice(0, 4);
+}
+// Action-oriented follow-ups shown right after a block is added. A bare
+// "Edit <Type>" reads like a chore; these nudge the user toward a concrete,
+// engaging next move. Only suggest actions the block actually supports (see the
+// item shapes in `_blockNotes`). Falls back to "Edit <Type>" for unlisted types.
+const ADD_BLOCK_FOLLOWUPS = {
+    Testimonials: ["Add another testimonial", "Add author photos", "Add roles & companies"],
+    FAQAccordion: ["Add another question", "Rewrite the answers"],
+    FeatureGrid: ["Add another feature", "Add icons to the features"],
+    Stats: ["Add another stat", "Add icons to the stats"],
+    CardGrid: ["Add another card", "Add images to the cards"]
+};
+export function postEditSuggestions(args) {
+    const { plan, current } = args;
+    if (plan.ops.some((op) => op.op === "remove_page"))
+        return [];
+    const suggestions = [];
+    const existingTypes = new Set(current.blocks.map((b) => b.type));
+    // `current` is the pre-apply page, so a block we just added isn't in it yet.
+    // Track added types separately so the forward-looking section nudges below
+    // don't suggest "Add Testimonials" immediately after one was added.
+    const addedTypes = new Set(plan.ops.flatMap((op) => (op.op === "add_block" ? [op.block.type] : [])));
+    const hasType = (type) => existingTypes.has(type) || addedTypes.has(type);
+    const pushUniqueSuggestion = (value) => {
+        if (suggestions.includes(value))
+            return;
+        suggestions.push(value);
+    };
+    // Detect if this was primarily an image update
+    const isImageUpdate = plan.change_log.some((entry) => /\b(image|images|unsplash|photo)\b/i.test(entry));
+    for (const op of plan.ops) {
+        if (op.op === "update_props") {
+            const block = current.blocks.find((b) => b.id === op.blockId);
+            if (block) {
+                if (isImageUpdate) {
+                    // After image updates, suggest content edits relevant to the block
+                    const blockType = block.type;
+                    if (blockType === "CardGrid" || blockType === "Card") {
+                        pushUniqueSuggestion("Edit cards");
+                        pushUniqueSuggestion("Update links");
+                    }
+                    else if (blockType === "FeatureGrid") {
+                        pushUniqueSuggestion("Edit features");
+                    }
+                    else if (blockType === "Hero") {
+                        pushUniqueSuggestion("Edit heading");
+                        pushUniqueSuggestion("Edit CTA");
+                    }
+                    else {
+                        pushUniqueSuggestion(`Edit ${blockType}`);
+                    }
+                }
+                else {
+                    const patchKeys = Object.keys(op.patch);
+                    const otherKeys = editablePropsFromBlock(block)
+                        .filter((k) => !patchKeys.includes(k) && !NON_CONTENT_PROP_KEYS.has(k));
+                    for (const key of otherKeys.slice(0, 2)) {
+                        pushUniqueSuggestion(promptFromPropKey(key, block.type));
+                    }
+                }
+            }
+        }
+        else if (op.op === "create_page") {
+            pushUniqueSuggestion("Generate image");
+        }
+        else if (op.op === "add_block") {
+            const followups = ADD_BLOCK_FOLLOWUPS[op.block.type];
+            if (followups)
+                for (const f of followups)
+                    pushUniqueSuggestion(f);
+            else
+                pushUniqueSuggestion(`Edit ${op.block.type}`);
+        }
+        else if (op.op === "remove_block") {
+            if (!hasType("CTA"))
+                pushUniqueSuggestion("Add CTA");
+        }
+    }
+    // Keep one or two forward-looking section suggestions even after non-structural edits.
+    if (!hasType("Testimonials") && suggestions.length < 4)
+        pushUniqueSuggestion("Add Testimonials");
+    if (!hasType("FAQAccordion") && suggestions.length < 4)
+        pushUniqueSuggestion("Add FAQ");
+    if (!hasType("Stats") && suggestions.length < 4)
+        pushUniqueSuggestion("Add Stats");
+    return suggestions.slice(0, 4);
+}
+export function demoPlanFromMessage(message, slug, activeBlockId, activeBlockType) {
+    const lower = message.toLowerCase();
+    const quoted = /"([^"]+)"/.exec(message)?.[1];
+    // SEO metadata patterns — checked early so "seo title" isn't mistaken for hero heading
+    const hasSeoKeyword = /\b(seo|meta\s*desc(?:ription)?|meta\s*title|metadata|og\s*image|open\s*graph)\b/.test(lower);
+    if (hasSeoKeyword) {
+        // Multi-field metadata: "add metadata with the title '...' and description '...'"
+        const multiFieldMatch = lower.match(/\b(?:set|change|update|add)\b.*?\bmetadata\b/);
+        if (multiFieldMatch) {
+            const patch = {};
+            const changeLog = [];
+            const titleMatch = message.match(/\btitle\s+['"]([^'"]+)['"]/i)
+                ?? message.match(/\btitle\s+to\s+['"]([^'"]+)['"]/i);
+            if (titleMatch) {
+                patch.title = titleMatch[1];
+                changeLog.push(`Title \u2192 "${titleMatch[1]}".`);
+            }
+            const descMatch = message.match(/\bdescription\s+['"]([^'"]+)['"]/i)
+                ?? message.match(/\bdescription\s+to\s+['"]([^'"]+)['"]/i);
+            if (descMatch) {
+                patch.description = descMatch[1];
+                changeLog.push(`Description \u2192 "${descMatch[1]}".`);
+            }
+            const ogMatch = message.match(/\b(?:og\s*image|open\s*graph\s*image)\s+['"]([^'"]+)['"]/i)
+                ?? message.match(/\b(?:og\s*image|open\s*graph\s*image)\s+to\s+['"]([^'"]+)['"]/i);
+            if (ogMatch) {
+                patch.ogImage = ogMatch[1];
+                changeLog.push(`OG image \u2192 "${ogMatch[1]}".`);
+            }
+            if (Object.keys(patch).length > 0) {
+                const fields = changeLog.length === 1 ? changeLog[0].split(" \u2192")[0] : "page metadata";
+                return {
+                    intent: "edit_plan",
+                    summary_for_user: `Updated ${fields}.`,
+                    change_log: changeLog,
+                    ops: [{ op: "update_page_meta", pageSlug: slug, patch }]
+                };
+            }
+        }
+        const seoGenerate = /\b(write|generate|create|add)\b.*\b(seo|meta)\b/.test(lower) && !quoted;
+        const seoSetMatch = lower.match(/\b(?:set|change|update|add)\b.*?\b(meta\s*desc(?:ription)?|seo\s*desc(?:ription)?)\b/)
+            ?? lower.match(/\b(?:set|change|update|add)\b.*?\b(seo\s*title|meta\s*title)\b/)
+            ?? lower.match(/\b(?:set|change|update|add)\b.*?\b(og\s*image|open\s*graph\s*image)\b/);
+        if (seoSetMatch) {
+            const fieldRaw = seoSetMatch[1].toLowerCase();
+            const isTitle = /title/.test(fieldRaw);
+            const isOgImage = /og|open\s*graph/.test(fieldRaw);
+            const extractedQuoted = quoted;
+            const singleQuoted = /'([^']+)'/.exec(message)?.[1];
+            const afterTo = message.match(/\bto\s+(.+)$/i)?.[1]?.trim();
+            const value = extractedQuoted ?? singleQuoted ?? afterTo ?? "";
+            if (!value) {
+                return {
+                    intent: "needs_clarification",
+                    summary_for_user: `Please provide the value — e.g. set ${isTitle ? "SEO title" : isOgImage ? "OG image" : "meta description"} to "Your value here".`,
+                    change_log: [],
+                    ops: []
+                };
+            }
+            const patch = {};
+            const fieldLabel = isTitle ? "SEO title" : isOgImage ? "OG image" : "Meta description";
+            if (isTitle)
+                patch.title = value;
+            else if (isOgImage)
+                patch.ogImage = value;
+            else
+                patch.description = value;
+            return {
+                intent: "edit_plan",
+                summary_for_user: `Updated the ${fieldLabel}.`,
+                change_log: [`${fieldLabel} \u2192 "${value}".`],
+                ops: [{ op: "update_page_meta", pageSlug: slug, patch }]
+            };
+        }
+        if (seoGenerate) {
+            return {
+                intent: "needs_clarification",
+                summary_for_user: "Demo mode cannot generate SEO metadata automatically. Please provide the exact title or description you'd like to set, for example: set meta description to \"Your description here\".",
+                change_log: [],
+                ops: []
+            };
+        }
+    }
+    if (lower.includes("make this shorter") && activeBlockId && activeBlockType === "Hero") {
+        return {
+            intent: "edit_plan",
+            summary_for_user: "Shortened the selected hero copy.",
+            change_log: ["Updated hero heading and subheading to be more concise."],
+            ops: [
+                {
+                    op: "update_props",
+                    pageSlug: slug,
+                    blockId: activeBlockId,
+                    patch: {
+                        heading: "Edit your site in seconds",
+                        subheading: "Describe a change and preview it instantly."
+                    }
+                }
+            ]
+        };
+    }
+    if ((lower.includes("title") || lower.includes("heading")) && activeBlockId && activeBlockType === "Hero") {
+        const headingText = quoted ??
+            message
+                .replace(/change/i, "")
+                .replace(/hero/i, "")
+                .replace(/title/i, "")
+                .replace(/heading/i, "")
+                .replace(/\bto\b/i, "")
+                .trim();
+        if (headingText) {
+            return {
+                intent: "edit_plan",
+                summary_for_user: "Updated the hero title.",
+                change_log: [`Changed hero heading to "${headingText}".`],
+                ops: [
+                    {
+                        op: "update_props",
+                        pageSlug: slug,
+                        blockId: activeBlockId,
+                        patch: { heading: headingText }
+                    }
+                ]
+            };
+        }
+    }
+    if (lower.includes("rich text") || lower.includes("richtext") || lower.includes("text block") || lower.includes("prose")) {
+        if (lower.includes("add") || lower.includes("insert") || lower.includes("create")) {
+            return {
+                intent: "edit_plan",
+                summary_for_user: "Added a rich text section.",
+                change_log: ["Inserted RichText block."],
+                ops: [
+                    {
+                        op: "add_block",
+                        pageSlug: slug,
+                        block: {
+                            id: `b_richtext_${Date.now()}`,
+                            type: "RichText",
+                            props: {
+                                title: "",
+                                body: "Add your content here.\n\nUse a second paragraph to break up the text into readable sections."
+                            }
+                        }
+                    }
+                ]
+            };
+        }
+        if (activeBlockId && activeBlockType === "RichText" && quoted) {
+            return {
+                intent: "edit_plan",
+                summary_for_user: "Updated the rich text body.",
+                change_log: [`Set body to "${quoted}".`],
+                ops: [{ op: "update_props", pageSlug: slug, blockId: activeBlockId, patch: { body: quoted } }]
+            };
+        }
+    }
+    if (lower.includes("add testimonials")) {
+        return {
+            intent: "edit_plan",
+            summary_for_user: "Added a testimonials section below the hero.",
+            change_log: ["Inserted Testimonials block after the hero section."],
+            ops: [
+                {
+                    op: "add_block",
+                    pageSlug: slug,
+                    afterBlockId: "b_hero_home",
+                    block: {
+                        id: `b_testimonials_${Date.now()}`,
+                        type: "Testimonials",
+                        props: {
+                            title: "Loved by small teams",
+                            items: [
+                                { quote: "We launched in a day.", author: "Ana, Founder" },
+                                { quote: "Edits are now effortless.", author: "Chris, Marketer" }
+                            ]
+                        }
+                    }
+                }
+            ]
+        };
+    }
+    if (lower.includes("remove") && activeBlockId) {
+        return {
+            intent: "edit_plan",
+            summary_for_user: "Removed the selected block.",
+            change_log: ["Deleted selected section from the page."],
+            ops: [{ op: "remove_block", pageSlug: slug, blockId: activeBlockId }]
+        };
+    }
+    return {
+        intent: "needs_clarification",
+        summary_for_user: "I need one clarification: what section should I change and what exactly should be updated?",
+        change_log: [],
+        ops: []
+    };
+}
+export function titleCaseSentence(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return trimmed;
+    return trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+}
+export function pageMetaContractSummary() {
+    return {
+        op: "update_page_meta",
+        fields: {
+            title: "SEO/og title (falls back to page.title if absent). Max 60 chars; put primary keyword near front; avoid generic words like 'Home' or 'Welcome'; must be unique per page.",
+            description: "Meta description for search engines and social sharing. 150-160 chars; front-load key info in first 110 chars (mobile truncation); include a CTA verb; use active voice; never use quotes; never repeat the title verbatim.",
+            ogImage: "Open Graph image URL for social previews. Must be HTTPS; recommended dimensions 1200x630px."
+        },
+        notes: "Merge-patch semantics: only supplied keys are updated. Set a field to empty string to clear it. Always include the actual values you set in change_log so the user can see them (meta tags are not visible in the page preview)."
+    };
+}
+/**
+ * Per-block notes that supplement the auto-derived contract.
+ * Only add entries here when the block needs guidance beyond what the registry
+ * metadata can auto-generate (list-field shapes are derived automatically).
+ */
+const _blockNotes = {
+    Hero: "Use heading for the main headline; never invent prop names. imagePosition controls layout and must be 'left', 'right', or 'full' (default 'right'). textAlign can be 'left' or 'center' (default 'left') — use 'center' for centered hero layouts especially with imagePosition 'full'. eyebrow is optional short text above the heading (e.g. 'New', 'Coming Soon'). For imageUrl: use any placeholder value (the system resolves images separately); if the user provides an explicit URL, use that. imageAlt is accessibility alt text describing what is depicted — never the user's instruction. Omit imageAlt from the patch unless the user explicitly provides a caption. Do NOT mention a specific image source in summary_for_user. secondaryCtaText/secondaryCtaHref are optional: set them to add a ghost/outline secondary button beside the primary CTA; omit or set to empty string to hide it.",
+    CTA: "Keep existing props unless the user asks to change them. secondaryCtaText/secondaryCtaHref are optional: set both to show a secondary button next to the primary CTA.",
+    Card: "A standalone card with one CTA. variant can be 'default' or 'full-bleed'. Use 'full-bleed' when a background image with dark overlay and white text is desired — requires imageUrl.",
+    RichText: "body is a string; use \\n\\n to separate paragraphs. Supported inline syntax: **word** for bold, *word* for italic, [text](url) for links, '# Heading' lines become h3 headings. title is an optional section heading. Never invent prop names.",
+    Stats: "stats must be a non-empty array of {value, label, icon?, description?}. value is a short string like '10K+' or '99.9%'. icon is optional and MUST be a single emoji such as '📈' or '🌍' — never an icon-library name like 'chevronRight' and never an invented/relative image URL (only use a full https:// URL if the user explicitly provides one). description is optional explanatory text below the label. title is an optional section heading.",
+    FeatureGrid: "features is a non-empty array of {icon?, title, description}. icon is optional and MUST be a single emoji such as '⚡' or '🔒' — never an icon-library name like 'chevronRight' and never an invented/relative image URL (only use a full https:// URL if the user explicitly provides one). columns controls the grid layout: '2', '3' (default), or '4'.",
+    Testimonials: "items is a non-empty array of {quote, author, role?, icon?, imageUrl?, imageAlt?}. role is the author's job title or company. icon is optional and MUST be a single emoji (e.g. a company/brand glyph) — never an icon-library name and never an invented image URL; it renders at the top of the card. imageUrl/imageAlt are for an optional circular author avatar photo.",
+    CardGrid: "cards is a non-empty array of {title, description, ctaText, ctaHref, imageUrl?, imageAlt?}. columns controls the grid layout: '2', '3' (default), or '4'. cardVariant can be 'default' or 'full-bleed' — applies to all cards in the grid. Use 'full-bleed' for background images with dark overlay and white text (requires imageUrl on cards). subtitle is optional.",
+    Tabs: "tabs is a non-empty array of {label, content}. content supports richtext markdown. title is an optional section heading above the tab bar.",
+    Banner: "Full-width announcement bar. variant sets preset theme: 'info' (default blue), 'success' (green), or 'warning' (amber). For custom brand colors, set backgroundColor and/or textColor (CSS color strings, e.g. '#1a1a2e' or 'rgb(26,26,46)'). Custom colors override the variant background/text. ctaText/ctaHref are optional: set both to show a button.",
+    FAQAccordion: "items is a non-empty array of {q, a}. The answer (a) supports richtext: **bold**, *italic*, [link](url), lists (- item), and paragraph breaks (\\n\\n).",
+    TwoColumn: "Image + text side-by-side layout. imagePosition is 'left' or 'right' (default 'right'). body supports inline markdown (**bold**, *italic*, [link](url)). ctaText/ctaHref are optional: set both to show a CTA button. For imageUrl: use any placeholder value (the system resolves images separately).",
+    Footer: "columns must be a non-empty array of {title, links}. links is a string with one 'Label|URL' per line (use \\n to separate). Example: 'Home|/\\nAbout|/about\\nBlog|/blog'."
+};
+/**
+ * Derive block contracts from the registry so new blocks are automatically
+ * included without maintaining a parallel hardcoded map.
+ *
+ * When a `manifest` is provided (external site), manifest-declared props are
+ * merged into the contract for shared-name blocks (e.g. Hero with extra
+ * `logoUrl`, `carouselImages`), and manifest-only blocks (e.g. ContactForm)
+ * get a contract derived from their JSON schema.
+ */
+export function blockContractsSummary(manifest) {
+    const allMeta = getAllBlockMeta();
+    const result = {};
+    // Build a lookup of manifest block types → propsSchema properties
+    const manifestByType = new Map();
+    if (manifest) {
+        for (const def of manifest.blocks) {
+            const props = def.propsSchema?.properties;
+            if (props && typeof props === "object" && !Array.isArray(props)) {
+                manifestByType.set(def.type, props);
+            }
+        }
+    }
+    for (const type of allowedBlockTypes) {
+        const schema = blockSchemas[type];
+        const meta = allMeta[type];
+        if (!schema || !meta)
+            continue;
+        // Derive allowed/required/optional from Zod schema shape
+        const shape = schema.shape;
+        const allProps = Object.keys(shape);
+        const required = [];
+        const optional = [];
+        for (const key of allProps) {
+            if (shape[key].isOptional() || shape[key] instanceof z.ZodDefault) {
+                optional.push(key);
+            }
+            else {
+                required.push(key);
+            }
+        }
+        // Merge manifest-declared props that the shared Zod schema doesn't know about
+        const manifestProps = manifestByType.get(type);
+        if (manifestProps) {
+            for (const key of Object.keys(manifestProps)) {
+                if (!allProps.includes(key)) {
+                    allProps.push(key);
+                    optional.push(key);
+                }
+            }
+            manifestByType.delete(type); // consumed — remaining are manifest-only blocks
+        }
+        // Collect image spec hints for scalar fields
+        const imageHints = [];
+        for (const [fieldKey, fieldMeta] of Object.entries(meta.fields)) {
+            if (fieldMeta.imageSpec) {
+                const s = fieldMeta.imageSpec;
+                imageHints.push(`${fieldKey}: recommended ${s.aspectRatio} ${s.width}\u00d7${s.height}`);
+            }
+        }
+        // Append list-field item shapes to notes for array props
+        let autoNotes = "";
+        if (meta.listFields) {
+            const parts = [];
+            for (const [listKey, listMeta] of Object.entries(meta.listFields)) {
+                const itemKeys = Object.keys(listMeta.itemFields).join(", ");
+                parts.push(`${listKey} must be a non-empty array of {${itemKeys}}`);
+                // Collect image spec hints for list item fields
+                for (const [itemKey, itemMeta] of Object.entries(listMeta.itemFields)) {
+                    if (itemMeta.imageSpec) {
+                        const s = itemMeta.imageSpec;
+                        imageHints.push(`${listKey}[].${itemKey}: recommended ${s.aspectRatio} ${s.width}\u00d7${s.height}`);
+                    }
+                }
+            }
+            if (parts.length > 0)
+                autoNotes = parts.join(". ") + ".";
+        }
+        const imageHintStr = imageHints.length > 0 ? imageHints.join(". ") + "." : "";
+        let notes = _blockNotes[type] ?? (autoNotes || `${meta.description ?? type} Never invent prop names.`);
+        if (imageHintStr) {
+            notes += (notes ? " " : "") + imageHintStr;
+        }
+        const entry = {
+            allowedProps: allProps,
+            required,
+            notes
+        };
+        if (optional.length > 0)
+            entry.optional = optional;
+        result[type] = entry;
+    }
+    // Add manifest-only blocks (not in shared registry) — derive contracts from JSON schema
+    for (const [type, manifestProps] of manifestByType) {
+        const derived = deriveFieldMetaFromSchema({ type: "object", properties: manifestProps });
+        const allProps = Object.keys(manifestProps);
+        // Derive list-field notes
+        const listParts = [];
+        for (const [listKey, listMeta] of Object.entries(derived.listFields)) {
+            const itemKeys = Object.keys(listMeta.itemFields).join(", ");
+            listParts.push(`${listKey} must be a non-empty array of {${itemKeys}}`);
+        }
+        const autoNotes = listParts.length > 0 ? listParts.join(". ") + "." : `${type} block. Never invent prop names.`;
+        result[type] = {
+            allowedProps: allProps,
+            required: allProps, // conservative: treat all as required
+            notes: autoNotes
+        };
+    }
+    return result;
+}

package/dist/nlp/deterministic-planner.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { type BlockType, type EditPlan, type PageDoc } from "@avocadostudio-ai/shared";
+export declare const blockTypeEnum: z.ZodEnum<{
+    [x: BlockType]: BlockType;
+}>;
+export declare const intentSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        info: "info";
+        add: "add";
+        update: "update";
+        remove: "remove";
+        move: "move";
+        clarify: "clarify";
+    }>;
+    target_block_ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    target_block_type: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        [x: BlockType]: BlockType;
+    }>>>;
+    new_block_type: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        [x: BlockType]: BlockType;
+    }>>>;
+    position: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        after: "after";
+        bottom: "bottom";
+        top: "top";
+        before: "before";
+    }>>>;
+    anchor_block_ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    patch: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assumption: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    complexity: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        simple: "simple";
+        standard: "standard";
+        complex: "complex";
+    }>>>;
+}, z.core.$strip>;
+export type ParsedIntent = z.infer<typeof intentSchema>;
+export declare function inferDeterministicIntent(args: {
+    message: string;
+    currentPage: PageDoc;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+}): ParsedIntent | null;
+export declare function isMultiIntentRequest(raw: string): boolean;
+/**
+ * Returns true only when UI context makes the intent completely unambiguous,
+ * so the deterministic planner can handle it without an LLM call.
+ */
+export declare function isHighConfidenceDeterministicCase(args: {
+    message: string;
+    currentPage: PageDoc;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+}): boolean;
+/**
+ * Attempts to handle a compound message ("remove the hero and add a CTA")
+ * by decomposing it into sub-intents and running each through the
+ * deterministic planner. Returns null if any sub-intent can't be handled
+ * deterministically.
+ */
+export declare function tryCompoundDeterministicPlan(args: {
+    session: string;
+    message: string;
+    slug: string;
+    currentPage: PageDoc;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+}): EditPlan | null;
+export declare function compileDeterministicPlan(args: {
+    session: string;
+    intent: ParsedIntent;
+    message: string;
+    slug: string;
+    currentPage: PageDoc;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+    locale?: string;
+}): EditPlan | null;
+export { extractAudienceTarget, extractAudienceTargets, titleCaseWords, addAudienceSuffix, audiencePatchForBlock, coercePatchForBlock, parseIndexedPath, inferSimpleFieldPatchFromMessage, isRewriteRequest, isTranslationRequest, shouldKeepRichTextTitleOnTranslate, inferFieldHintFromMessage, rewriteFromExisting, coercePatchForEditablePath, quotedText, buildListAppendPatch } from "./deterministic-planner-patches.ts";
+export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.ts";
+export { nextAvailableSlug, createPageBlocks, buildCreatePagePlan, isPageRouteRenameRequest } from "./deterministic-planner-pages.ts";
+export { readPathValue, resolveImageUrlForAltField, fetchImageAsBase64, resolveAttachmentsForLlm, selectedBlockSnapshot, arrayPropLengths, pageIntentSummary, plannerContextPack } from "./deterministic-planner-context.ts";
+export type { ResolvedLlmAttachment } from "./deterministic-planner-context.ts";
+export { inferAddedBlockTypeFromMessage, resolveBlockRef, ordinalToIndex, resolveByDescriptor, resolveReferencesFromMessage } from "./deterministic-planner-refs.ts";