Tidy scheme¶

Tidy scheme lays a whole reaction scheme out the way papers draw it, in one explicit step. It never runs on its own: placing things by hand always wins, and Tidy scheme keeps what you decided. It keeps the order of the steps, which molecule is a reactant, a reagent or a product, and every annotation. The browser button, vibe-sketch tidy, the REST routes and the MCP tidy_scheme tool all use vibesketch.document.scheme.tidy_scheme, and Undo takes it back.

A three-step synthesis drawn by hand: molecules at uneven heights, short arrows with their conditions overlapping them, compound numbers off-centre. — three-step.vsk as drawn.¶

The same document after Tidy scheme.¶

from vibesketch.document import load, save
from vibesketch.document.scheme import tidy_scheme

result, report = tidy_scheme(load("scheme.vsk"), width=24)
if report.tidied:
    save(result.document, "tidy.vsk")
else:
    print("left as drawn:", report.reason)

What it does¶

Each molecule is first cleaned, exactly as Clean up does it (Drawing cleanup). Tidy scheme then reads the drawing the way species and reactions are read from it, and places the molecules:

Linear sequences go in rows. When one step’s products are the next step’s reactants, the steps share a row. Molecules are centred on the arrows’ line. A row longer than width (24 bond lengths by default, about a two-column page) continues below: the arrow turns down and the next row runs back the other way, as mechanisms are often drawn. Every other sequence starts a row of its own, in step order.
Divergent schemes branch off the row. When a molecule feeds two or three steps, its first step stays in the row. The second leaves it by a diagonal arrow down to a row below, the third up to a row above, and each branch runs on to the right. The arrow lies on the line through both molecules’ centres.
Convergent schemes are laid out as a Y. When two sequences meet in one step, the two molecules that react sit side by side, without a plus sign. The first sequence arrives from above, the second from below, and the joint step runs on to the right. Draw the two molecules that way, close together and without a plus sign, so each stays the product of its own step: with a plus sign they would read as one side of every step they touch.
Arrows fit what they carry. Reagent molecules go above an arrow and condition texts below it, in their order, and the arrow is long enough for the widest of them. Beside a vertical or diagonal arrow they sit on its outer side, reagents first. Texts are measured in the document’s publication style (Figures), so the arrows fit the exported figure; in the editor’s smaller text they look generous.
Sides keep their meaning. Molecules joined by plus signs are laid out in a row with fresh plus signs. A side you arranged otherwise, such as a base drawn by the hydrogen it takes, keeps that arrangement. Molecules in it that overlap are eased apart.
Compound numbers are centred under their structures.
Annotations stay with their molecules. Curved (electron-pushing) arrows, crossed-out arrows and free text are not laid out. Each end of a curved arrow moves with the molecule it is drawn at, and its curvature is kept. Free text moves with the nearest molecule.
Molecules in no step go in a last row.

The scheme keeps its top left corner where the drawing had it.

A divergent scheme: benzyl alcohol (2) used twice.¶

A convergent scheme: a Williamson ether synthesis from two short sequences.¶

What it refuses¶

The result is checked before it is kept: the reactions read back from the tidied drawing must be the ones read before, with the same arrows, conditions and compound numbers, and for a linear scheme in the same order. The steps of a branched scheme are read in the order they are drawn, so they may come back in another order. Within a side, the reading order may follow the new arrangement. If a layout with turning rows would read differently, one long row is tried. If that fails too, the drawing is left exactly as it was and the report gives the reason. The same happens when:

the scheme branches in a way the layout cannot express yet: a molecule feeding four or more steps, a branch that branches again, a join fed by a branch, or more than two sequences joining;
two branches in the band below (or above) the row would run into each other;
an arrow has no molecules on one of its sides.

Draw a molecule again where the scheme branches to tidy it as separate sequences. The CLI exits with status 3, and the REST routes and the MCP tool answer 422, with the reason.

Measuring a scheme¶

vibesketch.document.scheme.scheme_metrics measures any drawing, tidied or not:

Measure	Meaning
`overlaps`	Pairs of molecules, texts and plus signs whose boxes intersect, and reaction arrows, as lines 0.3 bond lengths wide, that touch one of those boxes or each other; a molecule’s box reaches 0.3 bond lengths beyond its atoms.
`baseline_offset`	The largest distance of a reactant or product side’s centre from its arrow’s line.
`arrow_room`	The smallest margin of a reaction arrow’s length over its widest condition text, measured along the arrow.

The tests hold the Claisen mechanism, the three-step synthesis above, a retrosynthesis and the divergent and convergent schemes above, as drawn and with every atom jittered, to no overlaps, sides on their arrows’ line and arrows at least as long as their texts.