Variants (Block Alternatives)

​

Overview

​

When to use which path

​

Triggering variants (REST pipeline)

​

Detection

• Verbs: generate, create, make, show, give, produce, draft
• Nouns: variations?, variants?, alternatives?, options

​

Example messages

• “generate 3 variations”
• “show me 5 alternatives”
• “give 2 variants”
• “create four options for this hero”
• “make some variants with different copy”

​

Count parsing

• Numeric: \b(\d{1,2})\s+(variations?|variants?|alternatives?|options)\b
• Word form: one..twelve followed by the same nouns
• Default: 3
• Cap: 12 (anything higher is clamped silently)

​

Constraints

​

Triggering variants (agent tool)

1. Loads the page + block.
2. Filters each patch to keys that exist on the block and differ from current values.
3. Caps the list at 6.
4. Serializes the result as a tool response.

​

How variants are generated (REST pipeline)

​

1. LLM generation

// system
buildVariationSystemPrompt({ count, keepTitle, cardsOnly, blockType, locale })

// user
{
  "request":           "generate 3 variations with a crisper tone",
  "blockId":           "b_hero",
  "blockType":         "Hero",
  "currentProps":      { "heading": "…", "subheading": "…", … },
  "allowedPatchKeys":  ["heading", "subheading", "ctaText", "imageUrl", …]
}

{
  "variations": [
    {
      "title":   "Crisp & Direct",
      "summary": "Shorter and more action-oriented copy.",
      "patch":   { "heading": "Fresh avocados, daily", "ctaText": "Shop now" }
    },
    …
  ]
}

• OpenAI: called with response_format: { type: "json_object" }.
• Anthropic: system prompt goes through anthropicSystemPromptWithCache() for prompt caching; the response is parsed from the first text block via extractJsonObject.
• Both providers go through resolveEffectiveProvider / resolveModelKey for routing, so /status/planner availability applies.

​

2. Deterministic fallback

• CardGrid blocks get three pre-written tones — Crisp, Benefit-led, Action-driven — that rewrite each card’s description + ctaText.
• Every other block type with a string prop gets a suffix appended to the inferred primary text key (preference order: heading, title, subheading, description, body, ctaText, imageAlt, then the first non-empty string).

​

3. Image variation

1. If the message contains a URL, every variant uses that URL.
2. If deriveVariationImageIntent classifies the message as wanting AI- generated images, the pipeline dispatches to either Gemini (generateVariationImageWithGemini, default) or OpenAI (generateVariationImageWithOpenAI) based on IMAGE_GEN_PROVIDER. The per-variant prompt is built from the block type, heading, and subheading.
3. Otherwise it calls Unsplash via resolveUnsplashImage. With uniqueness enforced (the default), it uses resolveDistinctUnsplashImage which retries against a usedImageUrls set — up to 5 attempts, or 8 if the user explicitly asked for no duplicates.

​

4. Patch sanitization

const safePatch  = coercePatchForBlock(block, patch)      // type-coerce
const nextProps  = { ...block.props, ...safePatch }
const validated  = validateBlockProps(block.type, nextProps)
if (!validated.success) return null                       // drop invalid
if (deep-equal to current props) return null              // drop no-op
return safePatch

​

Rendering

​

Variation modal (REST pipeline)

• A read-only reference panel showing the block’s current props.
• A grid of variant cards. Each card has:
  • Title + summary from the variant.
  • Live preview — the real block renderer with the variant’s patch applied, wrapped in VariationScaledPreview. The component uses a ResizeObserver to measure the shell and canvas, then applies a CSS transform: scale(…) to fit the preview into the card without re-flowing the block’s internal layout.
  • Apply button — fires POST /ops with a single update_props op carrying variationModal.pageSlug, variationModal.blockId, and the variant’s patch.

1. Sets isApplyingVariation on the editor store to prevent double-clicks.
2. Sends the op.
3. Moves block focus to data.focusBlockId (usually the same block).
4. Broadcasts the patch to the preview iframe — either via postPatchToSite (if enablePatchTransport is on and we got a previewVersion) or the coarser draftUpdated broadcast.
5. Closes the modal and pushes an applied assistant message with canUndo: true.

​

Inline agent cards (agent tool)

​

Data shape

​

Request (REST)

{
  session: string
  siteId?: string
  slug: string
  message: string                               // the user prompt
  modelKey?: "fast" | "balanced" | "reasoning" | "codex"
  provider?: "openai" | "anthropic" | "gemini"
  activeBlockId: string                         // required — the selected block
  activeBlockType: string
  activeEditablePath?: string
  locale?: string
  businessContext?: { purpose?, tone?, constraints? } | string
  siteContext?: { siteId?, siteName?, purpose?, hosting?, tone?, constraints? } | string
}

​

Response (REST)

{
  status: "ok"
  summary: string                               // "Generated 3 variations for Hero."
  blockId: string
  blockType: BlockType
  pageSlug: string
  baseProps: Record<string, unknown>            // current block props, as reference
  variations: Array<{
    id: string                                  // "var_1713792134567_a3f2x"
    title: string                               // "Crisp & Direct"
    summary: string                             // "Shorter, more direct copy."
    patch: Record<string, unknown>              // only the keys that should change
    changedKeys: string[]
  }>
  plannerSource: "openai" | "anthropic" | "gemini" | "demo"
  modelUsed: string                             // e.g. "gpt-4o"
  modelKey: ModelKey
  usage?: {
    inputTokens: number
    outputTokens: number
    totalTokens: number
    cacheCreationInputTokens?: number
    cacheReadInputTokens?: number
    estimatedUsd: number | null
  }
}

​

Agent tool output

​

Persistence

• No variant list is ever persisted. Only the chosen patch, applied as a standard update_props op, lands in the draft.
• The applied variant participates in the normal session store history (undo/redo, version log, recent edits).
• If the user dismisses the modal, all generated variants are discarded client-side — nothing ever went to SQLite.

​

Demo mode

• REST pipeline — plannerSource resolves to "demo" for demo sessions. The pipeline currently only has LLM branches for openai and anthropic, so demo sessions skip the LLM and hit the deterministic fallback directly. Users still get three variants, just from the hand-written tones rather than the model.
• Image variation — DEMO_DISABLE_IMAGE_GEN=1 short-circuits both Unsplash and DALL·E calls inside detectImageOps, so demo variants keep whatever image the block already has.

​

Flags, caps, and defaults

​

Env vars

​

Testing

pnpm --filter @ai-site-editor/orchestrator test:chat
# or target the single file:
cd apps/orchestrator && npx tsx --test src/chat/variation-pipeline.test.ts

• Unsplash uniqueness enforcement (retries, final URL set size).
• “Keep same image” opt-out path.
• requestedVariationCount across synonyms (variations, variants, alternatives, options), word forms, and the max-count clamp.

​

Key files

​

Related

• How It Works — the chat pipeline the REST variation detour slots into.
• Asset Manager & AI Images — the providers behind withDefaultImageVariations (Unsplash, OpenAI image models).
• Custom Blocks — how allowedPatchKeys is derived from your block’s Zod schema.