Variant builder, visual mutations, and code mode

Simple terms

The builder is where a control or treatment variation is prepared. It can save simple DOM mutations or a richer code workspace.

The builder authors the actual storefront change for a variation. It supports visual mutations, custom CSS/JS, file-based code workspaces, previews, revisions, and generated changes.

Routes

• /tests/[id]/variations/[varId]

Implementation behavior

• Visual mutations are saved as structured JSON actions such as text, HTML, style, attribute, remove, insert before, and insert after.
• The SDK applies mutations idempotently after targeting and assignment succeed.
• Code mode stores generated workspace files, preview builds, build status, and revision metadata for more complex variants.
• Selector generation and mutation generation APIs help produce or refine changes from prompts and page context.
• Revision history lets teams inspect earlier builder states and roll forward from known working versions.

How to use it

• Start with visual mutations for simple copy, style, layout, or insertion changes.
• Use code mode when the change needs component logic, assets, or multi-file behavior.
• Save frequently, preview the forced variation, then run QA before launching traffic.
• For draft controls, use control edits for baseline-only setup or fixes, and preview the forced control arm before launch. Non-draft controls remain read-only but retain preview access; control edits apply only to visitors assigned to control.
• Put helpers or code that every arm needs in experiment-level CSS/JS instead of copying them into control and treatment variations.

When not to use it

• Do not use code mode for a copy or color change that a structured mutation can handle.
• Do not use control-only edits for the treatment idea: launch readiness still requires a saved treatment change.
• Do not launch a generated variant without previewing and saving the final state.

Implementation source

• The editor route is src/app/(dashboard)/tests/[id]/variations/[varId]/page.tsx.
• Operator and builder logic lives under src/features/apex-operator plus variation handlers under /api/experiments/[id]/variations/[variationId].
• Mutation payloads are stored on Variation.mutations; code workspace files, revisions, and builds use the experiment variation workspace APIs.

Data and API

• Prisma Variation.mutations, variation weight/control fields, code workspace models, preview artifact records, and revision records.
• APIs: /api/variations/[varId], /api/generate-mutations, /api/generate-selector, /api/experiments/[id]/variations/[variationId]/workspace, /api/experiments/[id]/variations/[variationId]/build, /api/experiments/[id]/variations/[variationId]/files, and /api/experiments/[id]/variations/[variationId]/revisions.
• SDK mutation engine and preview-session runtime.

Failure modes

• Change flashes or appears late: tune anti-flicker, selector timing, or target container.
• Mutation misses element: inspect selector, iframe/shadow DOM boundaries, and dynamic rendering.
• Code preview fails: review build status, generated files, unsupported browser APIs, and asset paths.