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.
• Keep each variation code field at or below 500,000 characters. Apex refuses data URIs longer than 4,096 characters. Upload images on the Assets page, with apex assets upload, through an Operator attachment, or through automatic CLI asset upload. Then use the hosted delivery URL in custom code or mutations.

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.