Formats and Apply Strategies
Choosing a Format
| Question | Use |
|---|---|
| I only need helix topology and colors | cadnano_json |
| I need sequences, oligo names, or modifications | foldnano_json |
| I need to mutate the model and preserve sequences | foldnano_json with replacePartKeepAnnotationsWhereMatched |
| I want to write code that mutates the part directly (one undo step) | foldnano_edit with replayMutationLog / …InRegion |
cadnano_json is a lossy format: it carries helix topology and staple colors but drops sequences, modifications, oligo names, and the explicit scaffold flag. cadnano's scaf/stap arrays are only a direction convention, so a cadnano_json result carries no scaffold flag; replaceRegionKeepAnnotationsWhereMatched puts it back on oligos whose segments still match, replaceRegion doesn't.
Before a cadnano_json plugin runs, Foldnano checks whether the active region fits in cadnano JSON. Problems that would corrupt the plugin's input, such as a connection between a cadnano scaffold path and a staple path, always ask the user first. For replaceRegion strategies the user is also told what applying the result would lose (connections to other regions, repeat-group copies, and so on), since the region is then replaced by what came back. The user can cancel; the plugin doesn't run.
foldnano_json is the lossless Part.toJSON() snapshot. It includes everything: per-slot sequences, skip/insert structure, modifications, oligo names, isScaffold flag, and UUIDs. It is the only format that exposes sequence data to plugins. Its shape is the same as one entry of parts in a .fn.json file; the File Format page documents every field.
foldnano_edit is the mutable API. The plugin operates on a MutablePart whose mutations are captured as a structured op log; the host replays the log against the real JS-side Part under one undo step. This is the only format that lets you express direct edits (oligo.color = '#f00', part.create_segment(...), part.make_crossover(...), part.break_at(...)) instead of producing a whole-part snapshot.
live is reserved for a future phase and is not currently installable. Manifests that declare format: "live" are rejected at install time.
Choosing an Apply Strategy
| Strategy | When to use |
|---|---|
previewOnly | Analysis-only plugins that produce logs, CSV reports, or other artifacts without mutating the design. The model is never touched. |
replacePartKeepAnnotationsWhereMatched | Whole-part replacement for foldnano_json plugins when sequences, modifications, and names should be re-grafted onto matched segments after the replace. |
replacePart | Whole-part replacement for foldnano_json plugins when annotation re-grafting would be incorrect. Shows a data-loss warning before apply. |
replaceRegion / replaceRegionKeepAnnotations… | Region-scoped replacement for cadnano_json plugins. Cross-region links are re-grafted automatically. Region replacement must preserve the region's VH index set; creating new VHs is not supported. |
replayMutationLog | Replay a foldnano_edit mutation log against the existing part. One undo step covers the whole run. |
replayMutationLogInRegion | As above, but every op's target VH must belong to the active region; otherwise the replay aborts cleanly. |
For foldnano_json mutations, always prefer replacePartKeepAnnotationsWhereMatched unless you are intentionally changing the topology. It ensures sequences assigned before the run survive the apply.
For foldnano_edit mutations, choose replayMutationLogInRegion when your plugin only touches the active region (the host enforces the scope) and replayMutationLog when it touches the whole part.
For cadnano_json region replacement, treat the active region's VH numbering as fixed. A replaceRegion* plugin may rewrite topology within those helices, but it must not introduce brand-new VHs for that region.
Install-time validation enforces the supported combinations:
cadnano_json:previewOnly,replaceRegion,replaceRegionKeepAnnotationsWhereMatchedfoldnano_json:previewOnly,replacePart,replacePartKeepAnnotationsWhereMatchedfoldnano_edit:previewOnly,replayMutationLog,replayMutationLogInRegion
When a Result Can't Be Applied
For replacePart* and replaceRegion* strategies, a run that returns a result doesn't always offer Apply. Before it does, Foldnano checks the returned JSON twice:
- Result validation checks its shape against the declared
format: well-formedvstrandsorPart.toJSON()data, and references that point somewhere. Small inconsistencies are repaired (for example, a connection recorded on only one side is cleared when the other end is free); malformed data is rejected. - Design verification rebuilds the result the way Apply would, on a throwaway copy, and looks for dangling references, segments outside their helix, connections that don't match up, and, for region strategies, a change to the active region's set of helices. It also rejects designs the editor itself never produces: a skip or insert that differs between the two strands of one base, a skip or insert on a constrained crossover site, two helices on one lattice position, or a negative lattice position. A helix whose number is odd on an even lattice position (or the reverse) is only logged to the console.
If either check fails, the plugin panel names the offending field or id instead of showing Apply, and your design is untouched. So a replaceRegion* plugin that adds or removes a helix in the active region runs without error but never offers Apply.