v3 Experiment Designer Quick Start

v0.20 | 2026-06-01 15:25 ET — Edit Protocol v3 YAML directly, with anchors and comments preserved on round-trip.

The v3 Experiment Designer is a YAML round-trip editor for Protocol v3. It loads an existing v3 YAML (or starts a fresh one with ＋ New), lets you edit it through a structured UI, and exports it back — preserving your anchors, comments, and key order. The on-disk YAML is the single source of truth.

The interface

Three columns over a flattened-timeline preview. The left column is split into a Library of conditions and an always-visible Variables (anchors) panel.

┌───────────────┬──────────────────────┬─────────────────┐
│ LIBRARY       │ EXPERIMENT SEQUENCE  │ INSPECTOR       │
│  conditions   │  ▸ arena check       │  selected       │
│  (search,     │  ▾ main block        │  condition /    │
│   + Add)      │      trials, reps    │  block /        │
├───────────────┤  ▸ posttrial         │  ref details    │
│ VARIABLES     │                      │  (edit commands │
│  &dur_short 3 │                      │   inline)       │
│  &dur_long 10 │                      │                 │
│  + Add        │                      │                 │
├───────────────┴──────────────────────┴─────────────────┤
│ FLATTENED TIMELINE PREVIEW (every rep × trial expanded) │
└─────────────────────────────────────────────────────────┘

Library — every condition in the protocol. Click to inspect; drag onto the sequence; + Add creates one.
Variables — the variables: anchors. Edit a scalar value or rename an anchor and every *alias updates. Always visible now (no longer hidden in Settings).
Experiment Sequence — the ordered run: bare refs to conditions and blocks (groups of trials with repetitions / randomize / intertrial).
Inspector — edits the selected item: a condition's commands, a block's properties, a ref.
Timeline — a read-only preview of the flattened run order.
Settings ▾ (header) — experiment metadata, the rig path, and the plugins list, where you can add or remove plugins (their commands then appear in the Inspector's "+ add" picker).

Walkthrough: edit and export a protocol

Load or create a protocol. Use Import YAML to open your own file, ＋ New to start from a minimum-valid blank skeleton, or Load demo ▾ to start from a bundled example (e.g. canonical_a).

Inspect a condition. Click any row in the Library. Its commands appear in the Inspector — controller (trialParams), wait, and plugin commands. Edit fields inline; changes write straight to the YAML model.

Need a plugin command that isn't listed (e.g. a thermometer for temperature monitoring)? Open Settings ▾ → Plugins, pick the plugin from the dropdown, and click Add — its commands appear in the "+ add" picker immediately. Set config values (device id, channels, ports) in the exported YAML.

Use a Variable (anchor). In the Variables panel, edit &dur_long's value — every command that references it via *dur_long resolves to the new value on export. Click + Add to create a new anchor, or rename one to cascade the change across all references.

Complex anchors (maps / sequences) show a read-only badge — edit those in the YAML directly; renaming still works.

Arrange the sequence. Drag a Library condition onto the Experiment Sequence to add a ref, use + Ref / + Block, reorder by dragging, and edit block repetitions / randomize / intertrial in the Inspector. The Timeline preview updates live.

Export. Export YAML writes the file back out with your anchors and comments intact. A non-blocking warnings strip flags unused conditions / anchors; a blocking modal catches errors (duplicate names, dangling aliases) before you export.

Round-trip safe. Import → edit → export changes only what you touched. Anchors, inline comments, and key order are preserved, so a diff against the original shows just your edits.

Cross-library import (copy conditions between protocols)

Pull conditions out of a second v3 YAML — a sibling lab's protocol, or an older version of your own — into the one you're editing, bringing along the anchors and plugin declarations they depend on.

Open a source. With a protocol loaded, click Import from YAML… and pick a second v3 file. The layout swaps: your protocol locks on the left, the source's conditions appear in the middle, and an import inspector opens on the right.

Stage conditions. Click ← Add on a source condition. It joins "Pending additions" — its referenced anchors and plugins come along automatically (transitively).

Adjust names. Imported anchors and plugins get a prefix__ (editable in the banner) so they don't clash with yours; conditions keep their own names. The inspector flags any name collision and suggests a fix. Plugins that match one of yours (same class + config) merge instead of duplicating.

Commit. Commit import applies the whole batch in one step (one Undo reverts all of it). Imported nodes are stamped # imported from <source>. Cancel discards everything and changes nothing.

Scope. Import copies conditions plus their direct dependencies and appends a bare sequence ref so each is runnable. It does not reproduce the source's block membership, repetitions, or intertrial placement — arrange those in your sequence afterward.

Key concepts

Condition — a named list of commands (the unit you reuse). Lives in conditions:.
Sequence ref vs. block — the experiment: list is the run order. A ref is a single condition; a block groups trials with repetitions, randomize, and an optional intertrial.
Anchor / alias — &name value defines a reusable value in variables:; *name references it. Editing the anchor updates every reference.
Plugin — a runtime resource (camera, LED controller) declared in plugins: and called by plugin commands.
Controller modes — Mode 2 (constant rate, frame_rate set, gain 0) vs. Mode 4 (closed-loop, gain set, frame_rate 0).

Keyboard & history

Ctrl/Cmd+Z — undo
Ctrl/Cmd+Y — redo (also Ctrl/Cmd+Shift+Z)
⟲ Reset — clear to a blank minimum-valid skeleton (reversible with undo)

Edits are in-memory until you Export — the page warns before close/reload if you have unsaved changes or an import in progress.