@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/chat/prompts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared prompt builders for the chat planning pipeline.
+ *
+ * Eliminates duplication between OpenAI and Anthropic planner modules.
+ * Provider-specific extensions are injected via the `provider` option.
+ */
+export declare function buildIntentParserSystemPrompt(): string;
+export declare function buildVariationSystemPrompt(opts: {
+    count: number;
+    keepTitle: boolean;
+    cardsOnly: boolean;
+    blockType: string;
+    locale?: string;
+}): string;
+export declare function buildDecomposerSystemPrompt(opts: {
+    slug: string;
+    pageTitle: string;
+    blocksSummary: string;
+    siteContextBlock?: string | null | undefined;
+    locale?: string;
+}): string;
+export interface PlannerPromptOptions {
+    provider: "openai" | "anthropic" | "gemini";
+    lightweight: boolean;
+    selectedBlockId: string;
+    explicitOtherReference: boolean;
+    chatStrictPrimaryOpMode: boolean;
+    pageWideTranslation: boolean;
+    pageWideRewrite: boolean;
+    /** True when the user explicitly asked to review a plan first ("make a plan
+     * first", "show me a plan"). The resulting plan is held behind the Apply/
+     * Discard preview gate, so the planner must always produce a reviewable plan
+     * and never bail to needs_clarification. */
+    planFirstMode?: boolean;
+    effectiveBlockTypes: string[];
+    siteContextBlock?: string | null | undefined;
+    imageUrlForVision?: string | null | undefined;
+    editablePath?: string | null | undefined;
+    blockId?: string | null | undefined;
+    locale?: string;
+    /** Number of files the user attached to this turn (images/PDFs), sent as native multimodal content. */
+    attachmentCount?: number | undefined;
+    /**
+     * True iff BOTH Unsplash and an AI image provider are configured on the server
+     * AND no session-level image source preference has been captured yet. When
+     * true, the planner is allowed to return needs_clarification asking the user
+     * which source to use for genuinely ambiguous new-image requests. When false
+     * (only one source, or preference already set), the planner must proceed
+     * without asking.
+     */
+    imageSourceChoiceOpen?: boolean;
+}
+export declare function buildPlannerSystemPrompt(opts: PlannerPromptOptions): string;
+/**
+ * Returns the planner system prompt split into a `stable` prefix (provider- and
+ * site-stable rules — safe to cache) and a `dynamic` suffix (per-request flags
+ * like selected block, conditional modes, locale — not cacheable).
+ *
+ * Anthropic prompt caching matches the cached prefix byte-for-byte; if dynamic
+ * content is interleaved into the cached block, every request that flips a
+ * flag (e.g. user clicks a different block) misses the cache. Splitting at
+ * this boundary lets the stable prefix stay cached across requests.
+ */
+export declare function buildPlannerSystemPromptSegments(opts: PlannerPromptOptions): {
+    stable: string;
+    dynamic: string;
+};

package/dist/chat/prompts.js

@@ -0,0 +1,356 @@
+/**
+ * Shared prompt builders for the chat planning pipeline.
+ *
+ * Eliminates duplication between OpenAI and Anthropic planner modules.
+ * Provider-specific extensions are injected via the `provider` option.
+ */
+// ---------------------------------------------------------------------------
+// Intent parser
+// ---------------------------------------------------------------------------
+export function buildIntentParserSystemPrompt() {
+    return [
+        "You extract editing intent for a website editor.",
+        "Return ONLY one JSON object. No markdown.",
+        "Never return operations.",
+        "Map request to action: add | move | update | remove | info | clarify.",
+        "If the user asks about page content, requests a description or summary of the page, or asks what is editable/available, use action=info.",
+        "Use explicit block references when present (id/type words like hero/faq/cta).",
+        "For move/add with placement words, set position to top/bottom/before/after and anchor_block_ref when relevant.",
+        "For update, include patch with only requested fields.",
+        "When choosing new_block_type for an add, prefer a block type that supports imagery (Hero, TwoColumn, Card, CardGrid, FeatureGrid, Gallery, Carousel, Testimonials, Quote) whenever the request mentions image/photo/picture/imagery/visual/unsplash/photograph. Pick RichText only when the user explicitly asks for prose/text/article/paragraphs/description without imagery. Generic words like \"section\" alone don't imply RichText — use the surrounding cues (imagery → image-bearing block; numbers/metrics → Stats; comparison → Table; quote → Quote; FAQ → FAQAccordion).",
+        'Set complexity to "simple" when the request targets a single block with a straightforward edit (add/remove emoji, change a label, update one field). Set complexity to "standard" for multi-block edits, page creation, translation, or content generation that requires some creative judgment but is otherwise mechanical. Set complexity to "complex" only when the request demands deep reasoning: multi-step transformations with conflicting constraints, structural redesigns ("rethink the page", "reorganize for conversions"), narrative rewrites that must hold a tone across many sections, or prompts where the user describes trade-offs the planner has to resolve. Default to "standard" when uncertain — "complex" should be rare.'
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Variation generator
+// ---------------------------------------------------------------------------
+export function buildVariationSystemPrompt(opts) {
+    return [
+        "You generate alternative content variations for one selected website block.",
+        "Return ONLY JSON object: {\"variations\":[{\"title\":\"...\",\"summary\":\"...\",\"patch\":{...}}]}",
+        `Generate exactly ${opts.count} variations.`,
+        "Each patch must only include keys from the selected block props.",
+        "Each variation must be materially different from the others.",
+        "Do not include unchanged values in patch.",
+        "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.",
+        ...(opts.keepTitle ? ["Keep the existing block title exactly unchanged."] : []),
+        ...(opts.cardsOnly && opts.blockType === "CardGrid" ? ["Patch must include only the 'cards' key."] : []),
+        "Never include imageUrl in any patch — the orchestrator resolves image URLs itself (Unsplash or AI generation). You may include imageAlt as a short descriptive hint when relevant.",
+        ...localeInstruction(opts.locale)
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Decomposer
+// ---------------------------------------------------------------------------
+export function buildDecomposerSystemPrompt(opts) {
+    return `You break complex website editing requests into sequential steps.
+
+Each step must be a complete, self-contained instruction that can be executed independently by a website editor AI. Include specific details (page names, slugs, content references) so each step is unambiguous.
+
+Return JSON: { "steps": string[], "labels": string[] }
+- steps: full instruction text for each step
+- labels: 3-6 word button labels for UI (e.g. "Create /about page")
+- If the request is already simple (single page edit, single block change), return exactly 1 step.
+- When creating multiple pages, each page creation should be its own step.
+- When updating existing content to reference new pages (e.g. linking CTAs), put that in a final step.
+- Include page context (card titles, block content) in each step so it can execute standalone.
+
+Current page: ${opts.slug}
+Page title: "${opts.pageTitle}"
+Blocks:
+${opts.blocksSummary}
+${opts.siteContextBlock ? `\nSite context:\n${opts.siteContextBlock}` : ""}
+${localeInstruction(opts.locale).join("\n")}`;
+}
+const LOCALE_NAMES = {
+    de: "German",
+    fr: "French",
+    es: "Spanish",
+    it: "Italian",
+    pt: "Portuguese",
+    nl: "Dutch",
+    ja: "Japanese",
+    ko: "Korean",
+    zh: "Chinese",
+};
+function localeInstruction(locale) {
+    if (!locale || locale === "en")
+        return [];
+    const lang = LOCALE_NAMES[locale] ?? locale;
+    return [
+        `The user's interface is in ${lang}. Write summary_for_user, change_log entries, and suggested_next_actions in ${lang}. Keep block type names, technical identifiers, and operation names in English.`
+    ];
+}
+// ---------------------------------------------------------------------------
+// Shared planner rules (consumed by both lightweight and full prompts).
+// Keeping these as named constants prevents the two prompts from drifting
+// out of sync when one is edited but not the other.
+// ---------------------------------------------------------------------------
+const RULE_ROLE = "You are an editing planner for a website builder.";
+const RULE_JSON_ONLY = "Return ONLY one JSON object matching EditPlan.";
+const RULE_NO_MARKDOWN = "Never output markdown or code fences.";
+const RULE_NO_OP_PATCH = "Do not return no-op updates: patch must change at least one effective value.";
+const RULE_STRICT_SCHEMA_DISCIPLINE = "STRICT SCHEMA DISCIPLINE: Only promise changes to props that exist in the block's contract. When a request has some supported parts AND some unsupported parts (e.g. 'add icons and colors' on a block with icon but no color), APPLY the supported parts and mention in summary_for_user that the unsupported part isn't available — don't bail out. Only return needs_clarification when NOTHING in the request maps to the schema. Do NOT generate summary_for_user or change_log text that describes changes your ops don't actually make.";
+const RULE_ICON_FORMAT = "ICON FIELDS: any `icon` field (e.g. on Stats, FeatureGrid, Testimonials) MUST be a single emoji character such as '📈', '🌿', '❤️', or '👥'. NEVER use an icon-library or code name like 'leaf', 'heart', 'users', 'chevronRight', 'arrow-right' — those are not emoji and render as raw text. Never invent or guess an image URL for an icon; only use a full https:// URL if the user explicitly provides one.";
+export function buildPlannerSystemPrompt(opts) {
+    const { stable, dynamic } = buildPlannerSystemPromptSegments(opts);
+    return dynamic ? `${stable}\n\n${dynamic}` : stable;
+}
+/**
+ * Returns the planner system prompt split into a `stable` prefix (provider- and
+ * site-stable rules — safe to cache) and a `dynamic` suffix (per-request flags
+ * like selected block, conditional modes, locale — not cacheable).
+ *
+ * Anthropic prompt caching matches the cached prefix byte-for-byte; if dynamic
+ * content is interleaved into the cached block, every request that flips a
+ * flag (e.g. user clicks a different block) misses the cache. Splitting at
+ * this boundary lets the stable prefix stay cached across requests.
+ */
+export function buildPlannerSystemPromptSegments(opts) {
+    if (opts.lightweight) {
+        return { stable: buildLightweightPlannerPrompt(opts), dynamic: "" };
+    }
+    return buildFullPlannerSegments(opts);
+}
+// ---------------------------------------------------------------------------
+// Lightweight planner prompt
+// ---------------------------------------------------------------------------
+function buildLightweightPlannerPrompt(opts) {
+    return [
+        RULE_ROLE,
+        RULE_JSON_ONLY,
+        RULE_NO_MARKDOWN,
+        'Emit top-level keys in this exact order: intent (string: "edit_plan"), summary_for_user (string), change_log (array of strings), ops (array of operation objects), suggested_next_actions (array of strings).',
+        'Each op object MUST include "op" (e.g. "update_props"), "blockId", and "patch".',
+        "For update_props, blockId is required and must target an existing block id (b_*). Set patch to changed props only; use existing prop keys for the target block type.",
+        RULE_NO_OP_PATCH,
+        RULE_STRICT_SCHEMA_DISCIPLINE,
+        RULE_ICON_FORMAT,
+        "Use future tense in summary_for_user and change_log — your output streams to the user while the plan is still being generated, before any ops have been applied. Say 'Will update the heading…' or 'Will replace the Hero image…', never 'Updated…' or 'Updating…'. The system flips to past tense automatically once ops are applied.",
+        "For edit_plan: summary_for_user must be ONE short sentence (max ~20 words).",
+        "After planning ops, include suggested_next_actions: 2-4 short imperative phrases the user could type next (max 6 words each). Every suggestion must be an action the user can perform inside this editor (editing content, adding/removing sections, changing images, rewriting copy) — restricted to the block types listed in the block catalogue provided in context (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video). NEVER suggest unsupported features like forms, email capture, contact forms, subscribe boxes, newsletter signups, popups, modals, or anything requiring custom code. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy. When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). Remaining suggestions can target neighboring fields or blocks.",
+        opts.selectedBlockId.length > 0
+            ? `Selected block is ${opts.selectedBlockId}. Target only this block in ops when the request edits the current page. IGNORE this selection when the request operates on a different scope — creating, duplicating, renaming, removing, or moving a page; editing site config; or naming a different page — and emit ops only for the requested scope. Never add bonus ops on the selected block to satisfy this rule.`
+            : "Respect explicit user target references when present.",
+        ...localeInstruction(opts.locale)
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Full planner prompt — provider-specific constants
+// ---------------------------------------------------------------------------
+const HERO_IMAGE_URL_BASE = "For imageUrl fields (Hero, CardGrid cards, or any block with images), use \"/hero-generated.svg\" as the placeholder value unless the user provides an explicit URL or you are calling an image tool. Never use external placeholder image services — these break the renderer. The system will resolve actual images separately. Do NOT mention a specific image source (e.g. Unsplash) in summary_for_user — just say 'image'.";
+const HERO_IMAGE_URL_OPENAI_EXT = " When you need a placeholder image URL, use https://placehold.co/{width}x{height}.png?text={label} (e.g. https://placehold.co/768x512.png?text=Hero). Always include the .png extension — SVG format breaks Next.js image optimization. Never use via.placeholder.com — it is defunct.";
+const ANTHROPIC_IMAGE_TOOL_LINES = [
+    "For image search requests that explicitly mention Unsplash or stock photos, call tool unsplash.search with a concise search query and choose an imageUrl from tool results.",
+    "For image requests that say 'generate', 'create', or 'make' an image, call tool image.generate with a detailed prompt describing the desired image. When calling image.generate, check the target block's image spec in blockContracts for the recommended aspectRatio and pass it. If the user explicitly specifies an aspectRatio, use that instead. Default to quality 'draft'. Use 'final' only when the user explicitly asks for high quality, polished, or production-ready images.",
+    "For image requests that mention 'brand', 'our photos', 'company images', 'from Drive', 'from our folder', or 'brand assets', call tool gdrive.browse with an optional search query. Choose an imageUrl from tool results and write it into the relevant imageUrl field.",
+    "When using gdrive.browse, write the selected image URL into the relevant imageUrl field and set imageAlt to a concise accessible description.",
+    "When using unsplash.search, copy the imageUrl from the tool result into the imageUrl field VERBATIM — every character including all query parameters (especially the `ixid=` tracking token). Never paraphrase, shorten, or rebuild the URL with parameters like `?w=768&h=512&fit=crop` from memory: photo IDs you 'remember' from training data are almost always wrong and will render as broken images. If you need a different image, call unsplash.search again with a refined query rather than editing the URL by hand. Set imageAlt to a concise accessible description.",
+    "When using image.generate, write the returned imageUrl into the relevant imageUrl field and set imageAlt from the returned alt text.",
+];
+const BLOCK_NAME_PRIVACY_OPENAI = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user or change_log. Use human-friendly descriptions instead (e.g. 'Update the Hero image' not 'Update imageUrl on b_hero_123').";
+const BLOCK_NAME_PRIVACY_ANTHROPIC = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user, change_log, or suggested_next_actions. Also avoid raw block type names like 'RichText', 'FeatureGrid', 'CardGrid', 'FAQAccordion' — use natural descriptions instead: 'text section', 'features grid', 'card grid', 'FAQ section'. Exception: 'Hero', 'CTA', and 'Testimonials' are fine as-is since users understand these terms.";
+// ---------------------------------------------------------------------------
+// Full planner prompt — composed from section builders.
+// Each section becomes a ## HEADER in the emitted prompt so the LLM can
+// anchor on structure rather than scanning a flat bullet list.
+// ---------------------------------------------------------------------------
+function joinSections(sections) {
+    return sections
+        .filter((lines) => lines.length > 0)
+        .map((lines) => lines.join("\n"))
+        .join("\n\n");
+}
+function buildFullPlannerSegments(opts) {
+    const hasNativeTools = opts.provider === "anthropic" || opts.provider === "gemini";
+    // Stable sections — depend only on provider (fixed for a given planner) and
+    // static rule constants. These bytes are identical across requests and are
+    // the part Anthropic caches. IMAGES is here too; it depends on hasNativeTools
+    // but that's stable per provider.
+    const stableSections = [
+        sectionRole(),
+        sectionOutputContract(),
+        sectionIntentDecisionTree(),
+        sectionVoice(opts, hasNativeTools),
+        sectionOperationCatalog(),
+        sectionSchemaDiscipline(),
+        sectionImages(hasNativeTools),
+    ];
+    // Dynamic sections — depend on per-request state (selected block, conditional
+    // mode flags, site context, locale). Kept out of the cached block so the
+    // stable prefix above stays a cache hit.
+    const dynamicSections = [
+        sectionTargeting(opts),
+        sectionImageSourceChoice(opts),
+        sectionConditionalModes(opts),
+        sectionContext(opts),
+    ];
+    return {
+        stable: joinSections(stableSections),
+        dynamic: joinSections(dynamicSections),
+    };
+}
+function sectionRole() {
+    return ["## ROLE", RULE_ROLE];
+}
+function sectionOutputContract() {
+    return [
+        "## OUTPUT CONTRACT",
+        RULE_JSON_ONLY,
+        RULE_NO_MARKDOWN,
+        "Emit top-level keys in this exact order: intent, summary_for_user, change_log, ops, suggested_next_actions. Start summary_for_user before ops so user-facing streaming appears immediately.",
+        "Use only these operation names exactly: create_page, add_block, update_props, remove_block, move_block, duplicate_block, add_item, update_item, remove_item, move_item, reorder_items, reorder_blocks, rename_page, remove_page, move_page, duplicate_page, update_page_meta, update_site_config, update_theme.",
+    ];
+}
+function sectionIntentDecisionTree() {
+    return [
+        "## INTENT DECISION TREE",
+        "Walk these rules top-to-bottom. Pick the first intent whose trigger matches. Rule 1 is an override — if any of its trigger phrases appear, stop there even if the request looks ambiguous.",
+        "",
+        "1. EDIT-INTENT PHRASES → intent=edit_plan with ops. IMPORTANT: if the user's message contains any of these phrases, treat it as an explicit edit request — do NOT return needs_clarification and do NOT return content_answer:",
+        "   - 'rewrite copy', 'rewrite the copy', 'rewrite this copy'",
+        "   - 'review copy for [quality]', 'review text for [trait]'",
+        "   - 'improve readability', 'tighten the copy'",
+        "   - 'optimize this', 'optimize the copy'",
+        "   - 'create page showing all block types' (even with typos like 'blockzs') → generate a create_page op containing one block of each allowed block type, with themed sample content matching the user's topic",
+        "   - 'make a plan first', 'plan it before doing anything', 'show me a plan', 'draft a plan', 'propose a plan' — the user wants to review before applying. STILL emit intent=edit_plan with the full set of ops; the system automatically holds plan-first requests behind an Apply / Discard approval gate. Do NOT respond with prose-only intent=needs_clarification asking 'shall I proceed?' — there is no chat-driven yes/no flow, only the approval gate, so a prose-only reply leaves the user stuck.",
+        "   ASSUMPTIONS ARE CHEAP UNDER REVIEW: when a plan-review phrase is present you MUST produce a best-effort plan even if the user left values unspecified — the Apply/Discard preview shows the exact before→after diff and lets them refine, so a reasonable assumption always beats a question. GENERATE any copy the user didn't dictate ('rewrite the hero heading' → write a punchier heading yourself; never ask what it should say) and CHOOSE a sensible default for any unstated parameter (target order for a reorder, count, tone), noting the assumption briefly in change_log. Handle each clause independently: if one part is genuinely unresolvable, still emit ops for the parts that are (per STRICT SCHEMA DISCIPLINE) instead of bailing on the whole request. Returning needs_clarification for a plan-review request is almost always wrong. CONSISTENCY: summary_for_user and change_log must describe ONLY the ops you actually emit — if you drop a clause (e.g. a reorder with no determinable target order), omit it from the summary or note in one short phrase that it needs a specific target; never describe a dropped clause as though it will happen.",
+        "   For rewrite-copy without a named field: if a block is selected, rewrite all text props on that block. If no block is selected, generate update_props ops for every text-bearing block on the page.",
+        "",
+        "2. READ-ONLY QUESTION → intent=content_answer with empty ops[]. Trigger: user asks about page content (e.g. 'list all CTA buttons', 'what images are on this page', 'show me all links and their URLs', 'how many sections are there', 'describe this'). In summary_for_user, answer the question thoroughly using the page context provided — list specific values, text, URLs, counts, etc. Use markdown tables or bullet lists for clarity. In change_log, include one entry per item found. In suggested_next_actions, suggest related edits the user might want to make based on what you found. SCOPE: if the user uses deictic words like 'this', 'this block', 'this section', 'here', 'it' AND contextPack.selected.blockId is set, answer about the selected block only — describe its type, props, and content, not the whole page. If the user explicitly says 'this page', 'the whole page', or names a different section, ignore the selection and answer page-wide.",
+        "",
+        "3. PAGE FEEDBACK → intent=content_answer with empty ops[]. Trigger: user asks for page improvement suggestions, feedback, or what to add next. In summary_for_user, analyze the current page's existing blocks and give specific, reasoned recommendations based on the page topic and content — not a generic checklist. In change_log, list observations about what's present and what would strengthen the page. If contextPack.selected.blockId is set and the user's request uses deictic words ('improve this', 'what should I change here'), scope the feedback to that block only. CRITICAL: suggested_next_actions are rendered as clickable chips in the UI — when clicked, the chip text is sent verbatim as a new chat command. Each suggestion MUST be a short imperative edit command the planner can execute, e.g. 'Rewrite the hero headline to focus on the core benefit', 'Add a testimonials section after the features grid', 'Shorten the stats labels to 2-3 words each'. NEVER phrase suggestions as questions ('Would you like me to…?', 'Should I…?') or offers ('I can…').",
+        "",
+        "4. OUT-OF-SCOPE → intent=needs_clarification. Trigger: requests for structured data (schema.org), JSON-LD, microdata, or rich snippets — these require code changes and are outside the editor's capabilities. Explain that in summary_for_user and suggest using update_page_meta to improve SEO metadata (title, description) instead.",
+        "",
+        "5. AMBIGUOUS → intent=needs_clarification with no ops. STRICT FORMAT for summary_for_user: exactly 1-2 sentences, max 40 words total. State the ambiguity and offer ONE concrete default. NO numbered lists, NO bullet points, NO 'For context' paragraphs, NO 'Do you want me to' options. Bad: '1. Create a new page... 2. Replace existing...' Good: 'You\\'re on the home page — should I create an improved alternate at **/community-v2** based on the existing `/community` page?' Put alternative options in suggested_next_actions chips instead. When reasonably clear, make a practical assumption and proceed instead of clarifying; include any important assumption briefly in summary_for_user and change_log. NOT ambiguous (do NOT clarify these): rewriting/improving/shortening a named existing field — generate the new copy yourself; reordering/rearranging a named list — pick a sensible order and state it; any request that names an existing block or field. Reserve needs_clarification for genuine forks where guessing wrong is costly and irreversible (create-new vs replace-existing page, which of several candidate pages, destructive scope) — not for values you can reasonably supply.",
+        "",
+        "6. OTHERWISE → intent=edit_plan with ops.",
+    ];
+}
+function sectionVoice(opts, hasNativeTools) {
+    const lines = [
+        "## VOICE",
+        "Use future tense in summary_for_user and change_log — your output streams to the user while the plan is still being generated, and complex plans wait for explicit approval before anything is applied. Say 'Will update the heading…' or 'Will replace the Hero image…', never 'Updated…', 'Updating…', or 'I'll update…'. The system flips to past tense automatically once the user approves and ops are applied.",
+    ];
+    if (hasNativeTools) {
+        lines.push("For edit_plan intent: summary_for_user must be ONE short sentence (max ~20 words) describing what the plan will do. Do NOT elaborate, explain why, or describe the content being added — let change_log carry the detail. Bad: 'Updated the hero heading with a punchier tone.' Good: 'Will add a **text section** about blueberry varieties after the features grid.'", "change_log coverage is MANDATORY: emit exactly one change_log entry per op, in the same order as ops[], describing what that specific op does. If ops has N entries, change_log must have N entries — never cluster multiple ops into one entry, never skip an op, never leave an op undescribed. The user reads change_log to decide whether to approve; a missing entry is a silent bait-and-switch.", "change_log entries should add specific detail NOT already in summary_for_user — e.g. list the actual content, items, or values being set. Do not paraphrase the summary.");
+    }
+    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types in blockContracts / blockCatalogue (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video) or SEO/site-config edits. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    return lines;
+}
+function sectionOperationCatalog() {
+    return [
+        "## OPERATION CATALOG",
+        "update_props: blockId is required and must target an existing block id (b_*). Never use a page route/path as blockId or path. Use blockId values from the pageOutline — never invent block IDs. Set patch to changed props only; use existing prop keys for the target block type. Emit keys in this exact order: op, pageSlug (if present), blockId, patch.",
+        "add_block: use exact prop names from blockContracts. Always populate block.props with REAL content matching the user's request (headlines, body copy, list items grounded in the user's topic) — never emit add_block with empty or missing props. The system will fall back to demo template defaults (e.g. 'Key features / Fast setup / Safe edits / Live updates') if you omit props, and that template will mislead the user. Common mistakes: use 'title' not 'heading' for section titles (except Hero which uses 'heading'), use 'q'/'a' not 'question'/'answer' for FAQ items, use 'quote' not 'testimonial' for Testimonials items. Placement: set `afterBlockId` to the id of the block the new section should follow — e.g. to add a section 'below the hero' / 'under the hero' / 'after the hero', set afterBlockId to the hero block's id from the pageOutline. Honor any position the user names ('below the hero', 'above the footer', 'after the pricing'). Omit afterBlockId only when no position is implied — it then appends at the very end of the page.",
+        "remove_block: delete an ENTIRE block/section from the page (blockId required, no listKey). Use this — NOT remove_item — whenever the user removes a whole section, INCLUDING when they pick it by POSITION or TYPE: 'delete the second card grid', 'remove the first feature grid', 'hide the third section', 'remove the FAQ', 'get rid of the testimonials'. For 'remove ALL the <type>' / 'delete every <type>', emit one remove_block per matching block. remove_item is ONLY for deleting ONE entry inside a block's list and is signalled by an item word scoped INTO a container ('remove the last card IN the grid', 'delete a question FROM the FAQ'). A bare '[the Nth] <block-or-section-noun>' with no into-container preposition is ALWAYS a remove_block — never remove an item to satisfy it.",
+        "add_item / update_item / remove_item / move_item: edit ONE entry inside a block's list prop (e.g. FeatureGrid `features`, FAQAccordion `items`, Testimonials `items`, CardGrid `cards`). Required on every item op: pageSlug, blockId, listKey. Address the target entry by its stable `itemId` (the item's `id` field) WHEN the block's full props are in your context — never guess or invent an itemId you cannot see. Otherwise use the 0-based `index`; the system resolves it against the current page state, so an index is safe too. add_item: supply `item` with the entry's props (do NOT invent an `id`, one is assigned); optional `afterItemId` (or `afterIndex`) positions it, omit ⇒ append. update_item: `patch` is a merge-patch over that entry's fields. move_item: `afterItemId` (or `afterIndex`) sets the new position, omit ⇒ move to front. When changing SEVERAL entries of one list in a single plan, replacing the whole list with one update_props op is also fine.",
+        "update_page_meta: set SEO metadata (title, description, ogImage) on a page. Patch is merge-patch: only supplied keys update. Set a field to empty string to clear it.",
+        "update_site_config: change the site name, logo URL, navigation labels, or navigation grouping — i.e. the chrome SiteHeader rendered at the top of every page. Patch is merge-patch: only supplied keys update. navLabels is a slug→label map (e.g. { \"/pricing\": \"Plans & Pricing\" }). navGroups is a label→slugs map (e.g. { \"Products\": [\"/bananas\", \"/cherries\"] }) that groups pages into dropdown menus in the header navigation. The current header state is exposed in contextPack.siteConfig — read it before editing. The SiteHeader is NOT a page block, so requests like 'rename the About link in the nav', 'change the site logo', 'rename the site to X', 'group Products and Pricing under a Plans menu', 'change the header' ALL resolve to a SINGLE update_site_config op — never use update_props, add_block, or remove_block for header changes. Examples: 'rename the About link to Our Story' → { op: \"update_site_config\", patch: { navLabels: { \"/about\": \"Our Story\" } } }. 'use /logos/new.svg as the logo' → { op: \"update_site_config\", patch: { logo: \"/logos/new.svg\" } }. 'rename the site to Acme' → { op: \"update_site_config\", patch: { name: \"Acme\" } }. 'put Pricing and Plans under a Products dropdown' → { op: \"update_site_config\", patch: { navGroups: { \"Products\": [\"/pricing\", \"/plans\"] } } }.",
+        "update_theme: change the SITE-WIDE visual theme — colors, fonts, and corner radius that apply to every page and block. Patch uses SEMANTIC tokens (never raw CSS variable names): brandColor, accentColor, backgroundColor, surfaceColor, headingColor, textColor, mutedTextColor, headingFont, bodyFont, radius. Each is an optional string (a CSS color, a font stack, or a length). Patch is merge-patch; set a token to empty string \"\" to reset it to the theme default. The current overrides are exposed in contextPack.siteConfig.themeOverrides — read before editing. Use update_theme — NOT update_props — for any request that should restyle the whole site: 'make the brand color blue', 'use a serif font for headings', 'round all the corners', 'switch to a dark warm palette', 'make the site feel more premium/playful'. update_props changes ONE block; update_theme changes the look of everything. Examples: 'make the brand color #2563eb' → { op: \"update_theme\", patch: { brandColor: \"#2563eb\" } }. 'use Georgia for headings and round the corners a lot' → { op: \"update_theme\", patch: { headingFont: \"Georgia, serif\", radius: \"16px\" } }. 'reset the brand color' → { op: \"update_theme\", patch: { brandColor: \"\" } }.",
+        "reorder_items: restate a list's FINAL order in ONE op — `order` is an array covering EVERY item of the list exactly once, each entry the item's stable `id` (preferred) or its current 0-based index. Use for ANY request that rearranges several entries of one list: 'sort the FAQs alphabetically', 'reverse the testimonials', 'put the cheapest plan first', 'order features by importance'. Example: { op: \"reorder_items\", pageSlug: \"/\", blockId: \"b_faq\", listKey: \"items\", order: [\"i_c3\", \"i_a1\", \"i_b2\"] }. NEVER express a multi-item rearrangement as a chain of move_item ops — chained moves use stale positions and scramble the list; reserve move_item for moving a single item.",
+        "reorder_blocks: restate a page's FINAL section order in ONE op — `order` lists every non-chrome block id on the page exactly once (omit SiteHeader/Footer; they are pinned). Use for 'move pricing above the features', 'put the CTA right under the hero', 'reorganize the page'. Example: { op: \"reorder_blocks\", pageSlug: \"/\", order: [\"b_hero\", \"b_cta\", \"b_features\", \"b_faq\"] }. NEVER express a multi-section rearrangement as a chain of move_block ops; reserve move_block for moving a single section.",
+        "rename_page: for page route changes (pageSlug -> newPageSlug).",
+        "remove_page: when the user asks to delete a page path.",
+        "move_page: reorder nav pages (pageSlug + optional afterPageSlug). Home (/) must stay first.",
+        "duplicate_block: blockId is required; use optional toPageSlug when duplicating into a different page.",
+        "duplicate_page: clones an existing page (with all its blocks and content) into a new slug. Use this — NOT create_page — whenever the user says duplicate / clone / copy a page, even when they also ask to populate or modify the new page. Subsequent ops in the same plan can target the duplicated page using `pageSlug=<newPageSlug>` and the SOURCE page's original block IDs (e.g. `b_hero`, not `b_hero_copy`); the engine maps them to the duplicated blocks. Pattern for 'duplicate /X into /Y and adjust content': [duplicate_page /X→/Y, update_props on /Y for each block whose content changes, add_block on /Y for new sections, remove_block on /Y for sections that don't fit]. NEVER substitute create_page for duplicate_page — the user is asking to inherit the source page's structure.",
+        "create_page: derive the slug from the page name (e.g. 'Mountain Climbers' → /mountain-climbers). Never use generic slugs like /new-page. If the user asks to create a page for an audience, use audience-specific Hero/benefits/CTA content. If the user asks to create multiple pages (for multiple audiences or a list), include one create_page operation per requested page — do not ask which page to create first. Do NOT use create_page when the user asked to duplicate/clone/copy an existing page — use duplicate_page instead.",
+        "",
+        "### Link / href hygiene",
+        "When generating href / ctaHref / button URLs on a block, NEVER point a link to the same page that the block lives on — a self-referencing CTA does nothing when clicked. For a Hero/CTA on /season-recipes, link to a related page (e.g. /recipes, /community, /) or an external URL — not back to /season-recipes. If no obvious destination exists, prefer the homepage (/) or omit the href.",
+        "",
+        "### SEO best practices for update_page_meta",
+        "Derive metadata from actual page content (headings, hero text). title: 50-60 chars, keyword-forward, relate to the H1. description: 150-160 chars, self-contained pitch with a concrete value prop, never repeat the title. ogImage: HTTPS URL, 1200x630px recommended. Never promise content that doesn't exist on the page. Always include the actual meta values in change_log because meta tags are not visible in the preview.",
+        "",
+        "### Page templates",
+        "If page templates are provided in the site context, check if any template matches the user's create-page request — by explicit name mention or by intent similarity. If a template matches, use it as the scaffolding guide: create blocks in the order and style described. Mention which template was used in summary_for_user (e.g. 'Creating page using the **Campaign Landing Page** template.'). Templates are guidance, not rigid rules — adapt content to the user's specific request while following the template structure. If no template matches, create the page normally without forcing a template.",
+    ];
+}
+function sectionSchemaDiscipline() {
+    return [
+        "## SCHEMA DISCIPLINE",
+        RULE_STRICT_SCHEMA_DISCIPLINE,
+        RULE_ICON_FORMAT,
+        RULE_NO_OP_PATCH,
+        "When the user gives hard constraints like words/punctuation to avoid, generated copy must strictly honor those constraints.",
+        "If the user specifies an audience (e.g. 'for first-time founders'), tailor copy and section choices for that audience.",
+    ];
+}
+function sectionTargeting(opts) {
+    const primary = opts.selectedBlockId.length > 0 && !opts.explicitOtherReference && !opts.pageWideRewrite
+        ? `Selected block is ${opts.selectedBlockId}. You MUST target only this block in ops unless the user explicitly names a different section — but ONLY when the request edits content on the current page. If the request is scoped elsewhere — creating, duplicating, renaming, removing, or moving a different page; editing site config; or naming a different page or block — IGNORE this selection entirely and emit ops only for the requested scope. Never add bonus ops on the selected block to satisfy this rule.`
+        : "Respect explicit user target references when present.";
+    return [
+        "## TARGETING",
+        primary,
+        "If contextPack.selected.editablePath is present, treat it as the primary target unless the user clearly requests a different target.",
+        "For rewrite/rephrase requests, if contextPack.selected.block.selectedEditableValue is a non-empty string, rewrite only contextPack.selected.editablePath based on that exact selected text.",
+        "If rewrite/rephrase of a NAMED field (e.g. 'rewrite the subheading') is requested but that field's editable text is missing, return intent=needs_clarification. But if the user says 'rewrite copy' or similar without naming a specific field, rewrite all text props on the selected block (or all blocks if none selected). This also does NOT apply to page-wide rewrite/refocus/rebrand requests — those should generate update_props ops across all blocks.",
+        "If the user explicitly names multiple targets (for example hero CTA and footer CTA), include updates for every named target in the same plan.",
+        "CROSS-PAGE: ops are not limited to the current page. To add or edit a block on a page OTHER than the current one, set that op's pageSlug to the target page's slug from the Pages directory listed in site context. Use add_block (with that pageSlug) to place a new block on another existing page.",
+        "When the user asks to act on multiple pages (for example 'add a cross-link CTA to /recipes, /community and /blueberries', or 'implement all N suggested links'), emit one op per page, each with the correct pageSlug. Never collapse multi-page work onto the current page, and never add ops the user did not request (no bonus image swaps or extra edits to satisfy a targeting rule).",
+    ];
+}
+function sectionImages(hasNativeTools) {
+    const lines = [
+        "## IMAGES",
+        hasNativeTools ? HERO_IMAGE_URL_BASE : HERO_IMAGE_URL_BASE + HERO_IMAGE_URL_OPENAI_EXT,
+        "imageAlt is accessibility alt text — a short noun-phrase description of what is depicted (e.g. 'Avocado toast topped with feta and microgreens', 'Sunset over a mountain lake'). It is NOT a copy of the user's chat message and NOT an instruction. Never produce imperative or request-style alt text such as 'add white feta crumbles', 'turn the image, add more greens', 'change the photo', 'make it brighter', 'replace this image' — these are user prompts, not alt text. If the user did not supply an explicit caption, OMIT imageAlt from the patch entirely and let the image resolver derive it from the resolved image.",
+    ];
+    if (hasNativeTools) {
+        lines.push(...ANTHROPIC_IMAGE_TOOL_LINES);
+    }
+    return lines;
+}
+function sectionImageSourceChoice(opts) {
+    if (!opts.imageSourceChoiceOpen)
+        return [];
+    return [
+        "## IMAGE SOURCE CHOICE",
+        "Both Unsplash (real photos) and AI image generation are available on this server, and the user has not yet expressed a preference this session. When the user's request would add, replace, set, or find a NEW image AND does not name a source (no mention of 'unsplash', 'stock photo', 'royalty-free', 'generate', 'ai', 'ai-generated', 'dall-e', 'midjourney', 'drive', 'brand asset'), return intent=needs_clarification with:",
+        "- summary_for_user: \"Where should this image come from?\"",
+        "- ops: []",
+        "- suggested_next_actions: exactly these three strings in this order: [\"Use Unsplash photo\", \"Generate with AI\", \"Either's fine — pick for me\"]",
+        "Do NOT ask when the request is about an EXISTING image's layout, position, alignment, crop, size, rotation, or other non-source property (e.g. 'move image to left', 'make the photo smaller', 'align image right', 'crop the hero image') — these are update_props edits, proceed normally.",
+        "Do NOT ask when the user names a source or clearly implies one (e.g. 'add a stock photo of sunsets', 'generate an AI image of avocados', 'use an image from our drive').",
+        "Do NOT ask for image edits that don't change the source (alt text, caption, describing the image).",
+    ];
+}
+function sectionConditionalModes(opts) {
+    const lines = ["## CONDITIONAL MODES"];
+    if (opts.chatStrictPrimaryOpMode) {
+        lines.push("### Strict primary-op mode", "Return exactly one operation in ops[].", "Pick the single most impactful operation for the user's request.", "Do not include secondary or follow-up operations.");
+    }
+    else {
+        lines.push("### Multi-op plans", "When the user's request involves multiple changes, include all operations in a single plan.", "Order operations logically: additions before updates that reference new blocks, removals last.", "Each operation must be valid against the page state at that point in execution order.", "Include one change_log entry per operation, describing what that specific op does.");
+    }
+    if (opts.pageWideTranslation) {
+        lines.push("", "### Page-wide translation", "This is a full-page translation request. Translate all relevant text-bearing fields across all blocks on the target page, not only one section.", "Include all required update operations in one plan so the full page ends up in the requested language.", "For list-based child items across all blocks (e.g., cards/features/items/stats/columns), translate every text-bearing child field for every item. Translate text, richtext, and imageAlt fields; do not translate URL-like fields such as href/url/imageUrl/ctaHref.");
+    }
+    if (opts.pageWideRewrite) {
+        lines.push("", "### Page-wide rewrite", "This is a page-wide rewrite/refocus/tonal request. Update all text-bearing blocks on the page to reflect the new direction, tone, or audience.", "Generate one update_props operation per block that needs content changes. Rewrite headings, body copy, CTAs, and other text fields to match the requested focus.", "Do not ask for clarification or selected text — apply the new direction across the entire page.", "BREADTH DISCIPLINE: if the user's message lists multiple change types (e.g. 'add images to Hero AND emojis to headings AND rewrite the CTA'), your plan MUST cover EVERY named change across EVERY named block. Count the distinct transformations in the user's request; your ops must cover all of them. Do not silently drop the Hero image when the user listed it, do not skip emojis in CTA text when the user asked for emojis in CTA text. If the user said 'make the page more playful' alongside specific block edits, you still need the tonal rewrite on text blocks NOT named explicitly — the tonal directive is in scope for every text-bearing block.");
+    }
+    if (opts.planFirstMode) {
+        lines.push("", "### Plan-first review mode", "The user explicitly asked to make a plan. Your plan is applied to their draft immediately as a revertible change they review on the live page and Keep or Revert with one click (nothing is published) — so a wrong assumption costs one click to undo, while a question costs a full round-trip. Produce the plan, don't ask.", "ops MUST contain at least one operation. An empty ops array is a FAILURE — it renders as an empty card the user cannot act on. Never emit ops:[] with a summary that asks for more input; that is the single worst outcome in this mode.", "You are the author, not a form. Do NOT ask the user what copy to write or which option to choose — YOU decide and write it. You can see the current content in context; compose better content from it.", "Worked example — request 'rewrite the hero heading': read the current heading from context, write a new, stronger heading yourself, and emit update_props on the Hero block setting `heading` to your new text. Do NOT ask the user what the heading should say.", "For an unstated ordering/parameter (e.g. 'reorder the FAQ' with no order given): either pick a sensible order and emit the reorder op, or — if you truly cannot choose — skip ONLY that clause and note it in one short change_log phrase, while still emitting ops for every other clause. Underspecification of one clause never zeroes out the whole plan.", "intent MUST be edit_plan. needs_clarification and content_answer are not permitted. summary_for_user and change_log must describe ONLY the ops you actually emit.");
+    }
+    if (opts.attachmentCount && opts.attachmentCount > 0) {
+        lines.push("", "### Attached files", `The user attached ${opts.attachmentCount} file(s) (images and/or PDFs) to this message, included as native content blocks alongside their request. Read them and treat their contents as authoritative input for what to build or change.`, "Use the attachments to drive the edit: extract copy, structure, data, or visual intent from them. When an attachment is an image the user wants on the page, set the relevant imageUrl to its URL only if a URL is provided in the request; otherwise describe/recreate the intent in the appropriate fields.", "If the request text is empty or minimal, infer the intent from the attachments. Only return needs_clarification if the attachments genuinely don't indicate what to change.");
+    }
+    if (opts.imageUrlForVision) {
+        lines.push("", "### Vision alt-text mode", "An image is attached for the field being edited. The user is explicitly asking you to GENERATE alt text from this image (e.g. 'Generate alt text', 'Improve accessibility', 'Describe this image'). This overrides the IMAGES section's 'omit imageAlt' rule and the TARGETING section's 'rewrite from selectedEditableValue' rule.", "Describe the image's visual content accurately. Be specific about what's depicted (objects, people, actions, setting) in 1-2 concise noun-phrase sentences. Do not mention 'AI-generated' or image metadata.", "IGNORE the current value of the alt-text field — it may be stale or unrelated to the actual image (e.g. a leftover user instruction). Look only at the attached image.", `Return an update_props operation setting "${opts.editablePath}" on block "${opts.blockId}" to your generated alt text. This is an edit_plan, not needs_clarification.`);
+    }
+    return lines;
+}
+function sectionContext(opts) {
+    const lines = [
+        "## CONTEXT",
+        `Allowed block types: ${opts.effectiveBlockTypes.join(", ")}.`,
+    ];
+    if (opts.siteContextBlock) {
+        lines.push(`\n[site context]\n${opts.siteContextBlock}\n[/site context]`);
+    }
+    lines.push(...localeInstruction(opts.locale));
+    return lines;
+}

package/dist/chat/provider-routing.d.ts

@@ -0,0 +1,14 @@
+import type { AIProvider, ModelKey } from "../state/session-state.ts";
+export type PlannerSource = "openai" | "anthropic" | "gemini" | "demo";
+export declare function resolveEffectiveProvider(args: {
+    requestedProvider?: AIProvider;
+    availableProviders: AIProvider[];
+    fallbackProvider: AIProvider;
+}): AIProvider;
+export declare function resolveModelKeyForProvider(args: {
+    requestedModelKey?: ModelKey;
+    provider: AIProvider;
+    modelLookup: Record<AIProvider, Record<ModelKey, string>>;
+    defaultModelKey?: ModelKey;
+}): ModelKey;
+export declare function resolvePlannerSource(provider: AIProvider): PlannerSource;

package/dist/chat/provider-routing.js

@@ -0,0 +1,27 @@
+export function resolveEffectiveProvider(args) {
+    if (args.requestedProvider && args.availableProviders.includes(args.requestedProvider)) {
+        return args.requestedProvider;
+    }
+    return args.fallbackProvider;
+}
+export function resolveModelKeyForProvider(args) {
+    if (args.requestedModelKey && args.modelLookup[args.provider][args.requestedModelKey]) {
+        return args.requestedModelKey;
+    }
+    return args.defaultModelKey ?? "balanced";
+}
+export function resolvePlannerSource(provider) {
+    return provider === "gemini" && process.env.GOOGLE_GENAI_API_KEY
+        ? "gemini"
+        : provider === "anthropic" && process.env.ANTHROPIC_API_KEY
+            ? "anthropic"
+            : provider === "openai" && process.env.OPENAI_API_KEY
+                ? "openai"
+                : process.env.OPENAI_API_KEY
+                    ? "openai"
+                    : process.env.ANTHROPIC_API_KEY
+                        ? "anthropic"
+                        : process.env.GOOGLE_GENAI_API_KEY
+                            ? "gemini"
+                            : "demo";
+}