# Foldnano Contributor Documentation

────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/contributor-overview -->

# Contributor Overview

## What Is Foldnano

Foldnano is a browser-based DNA nanostructure design tool built with SvelteKit. It's local-first: designs live in the browser's IndexedDB working copy, with optional sync to a GitHub repository. It embeds a Python plugin runtime (via Pyodide, running in a Web Worker), so design operations can be scripted in Python without leaving the browser. It also supports importing and exporting the legacy cadnano `.json` format alongside its own native `.fn.json`.

This section is a curated contributor guide. It is not a mirror of every internal file in the repository `docs/` folder.

Public-facing contributor docs should explain how to work on Foldnano. Internal audits, release-review notes, and exploration reports stay in the repository's `docs/` folder rather than on this site, unless they are rewritten as stable guidance.

## What To Read First

1. Coming from Python (skip if you're already comfortable with JS/TS/pnpm)
2. Local setup
3. Architecture overview
4. Model and command invariants
5. Storage, autosave, and GitHub sync
6. Plugin runtime architecture
7. Code style and tests

For deeper implementation detail, use the repo docs such as `docs/architecture.md`, `docs/dna-model.md`, `docs/commands-and-history.md`, and `docs/storage-architecture.md`.

## Branch Model And PR Workflow

- `main` is the stable branch; open pull requests against it.
- Name feature branches `feat/<name>` and bug-fix branches `fix/<name>`.
- Run `pnpm check && pnpm test` before pushing. `pnpm test` scopes to suites affected by your changes; run `pnpm test:branch` (suites affected vs. `main`) before opening the PR.

## Contribution Principle

Foldnano has a reactive editor, an undoable model, local persistence, and multi-tab protection. Most regressions come from bypassing one of those ownership boundaries. Prefer small changes that preserve the existing command, storage, and view-context contracts.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/coming-from-python -->

# Coming From Python

Foldnano's frontend is TypeScript and Svelte, not Python. If you already work comfortably in a JS/TS toolchain, skip this page and go straight to Local Setup. If your background is Python (scripting, Jupyter, scientific computing), this page maps the ecosystem before you touch a terminal command.

## What Are JavaScript, TypeScript, And Svelte?

If the names above are unfamiliar, here's the short version before anything else:

- **JavaScript** is the programming language every web browser runs: the browser understands it natively, the same way it only understands HTML/CSS for markup and layout. It's dynamically typed, like Python. See [MDN's JavaScript guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide) for an introduction.
- **TypeScript** is JavaScript plus a type system, checked before the code runs, not at runtime. Think Python type hints, except the compiler (`tsc`, run here via `pnpm check`) *enforces* them rather than just suggesting them, and strips the types out to produce plain JavaScript. This project is TypeScript throughout; see the [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/intro.html).
- **Svelte** is a UI framework for building interactive web pages out of reusable components, the same role [React](https://react.dev/) or [Vue](https://vuejs.org/) play, if you've heard of either. The difference that matters here: React/Vue ship a runtime library that does its work in the browser at page-load time, while Svelte is mostly a *compiler*. It turns your components into plain, minimal JavaScript ahead of time, so there's less framework code shipped to the browser. See [Svelte's introduction](https://svelte.dev/docs/svelte/overview).
- **SvelteKit** is the application framework built on top of Svelte: it adds routing, server-side rendering, and API endpoints, the same relationship [Next.js](https://nextjs.org/) has to React, or Django has to plain Python. See [SvelteKit's introduction](https://svelte.dev/docs/kit/introduction).

## The Mental Model

| Python world                   | JS/TS/Svelte equivalent here                                              |
| ------------------------------- | --------------------------------------------------------------------------- |
| `python` / `pyenv`              | [Node.js](https://nodejs.org/en/docs) / `nvm`                               |
| `pip` / `conda` / `uv`          | [pnpm](https://pnpm.io/)                                                     |
| `venv` / `.venv`                | `node_modules/` (auto-managed, never commit)                                |
| `requirements.txt`              | `package.json` + `pnpm-lock.yaml`                                           |
| a module (`.py`)                | a [TypeScript](https://www.typescriptlang.org/docs/) module (`.ts`, or `.svelte.ts` if it uses reactive state) |
| a function/class you call       | a [Svelte](https://svelte.dev/docs/svelte) *component* (`.svelte` file: template, script, and scoped style together) |
| a Flask/Django route            | a [SvelteKit](https://svelte.dev/docs/kit) file-based route (`src/routes/.../+page.svelte`) |
| a `@dataclass` field others read | a Svelte 5 [*rune*](https://svelte.dev/docs/svelte/what-are-runes) (`$state`, `$derived`, `$props`), an explicitly reactive field |
| `pytest`                        | [Vitest](https://vitest.dev/)                                                |
| `python -m mymodule` / `uv run` | `pnpm run <script>`                                                         |

## How Svelte/TypeScript Dev Works Here

A few things that don't have a direct Python analogue:

- **Components compile away.** A `.svelte` file isn't interpreted at runtime like a Python module. The [Svelte compiler](https://svelte.dev/docs/svelte/overview) turns it into plain, targeted DOM-update JavaScript at build time. There's no framework runtime diffing a virtual tree on every change.
- **Reactivity is explicit, via runes.** [`$state`, `$derived`, and `$props`](https://svelte.dev/docs/svelte/what-are-runes) mark a field as reactive; code that reads it re-runs when it changes, similar to a spreadsheet cell recalculating. Plain fields are not reactive; this trips people up coming from Python, where every attribute is implicitly "live." See `docs/reactivity-patterns.md` for the details, including why class files using runes need the `.svelte.ts` extension.
- **SvelteKit is the meta-framework.** It gives you [file-based routing](https://svelte.dev/docs/kit/routing) (`src/routes/`), server-side rendering, and API route handlers (`+server.ts`), roughly the role Flask or Django plays, but routes are directories, not decorators.
- **TypeScript is checked, not run directly.** `pnpm check` runs `svelte-kit sync` + [`svelte-check`](https://www.npmjs.com/package/svelte-check); there's no separate "compile" step you invoke by hand during dev. `pnpm dev` handles it.

The specific libraries in play (Konva for the 2D strand view, Three.js for the 3D view, Dexie over IndexedDB for storage, Pyodide for the Python plugin runtime) are listed in `CLAUDE.md`'s Tech Stack section.

## Install Node.js Via nvm

[nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) is the recommended way to install Node: it lets you switch Node versions per project, the same role `pyenv` plays for Python.

**macOS / Linux:**

```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
```

Restart your shell, then install the Node version this project requires (pinned in `package.json`'s `engines` field):

```sh
nvm install 24
nvm use 24       # or: nvm alias default 24  to make it the global default
node --version   # should print v24.x.x
```

**Windows:** use [nvm-windows](https://github.com/coreybutler/nvm-windows): download the installer from its releases page, run it, then open a new terminal and run the same `nvm install 24` / `nvm use 24` commands above. (Native `nvm` is a shell script and doesn't run on Windows; nvm-windows is a separate, compatible tool with the same command surface.) Alternatively, install Node 24 directly from [nodejs.org](https://nodejs.org) if you don't need to switch versions.

## Install pnpm Via Corepack

This project uses [Corepack](https://nodejs.org/api/corepack.html) (ships with Node) to manage the pnpm version pinned in `package.json`. You don't install pnpm manually; Corepack downloads the exact pinned version on first use.

```sh
corepack enable       # one-time; tells Node to let Corepack manage package managers
pnpm --version         # Corepack downloads pnpm on first use; should print 10.x or later
```

## Clone, Install, Run

```sh
git clone https://github.com/XinShiLab/foldnano.git
cd foldnano
pnpm install          # reads package.json, installs everything into node_modules/
pnpm dev               # starts http://localhost:5173, hot-reloads on save
```

`pnpm install` is the equivalent of `pip install -r requirements.txt`; re-run it whenever `package.json` changes (e.g. after pulling commits that add a dependency). `node_modules/` is the `venv` equivalent: it's fully regenerable from the lockfile and is never committed.

Continue to Local Setup for the rest of the repo-specific commands (`pnpm check`, `pnpm lint`, `pnpm test`).

## Where The Docs Live

| Location                            | What it's for                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| `docs/*.md`                          | Internal, per-subsystem deep dives (model, commands, storage, plugin system…). Read the relevant one before a non-trivial edit in that area; each ends with a "Boundaries / Don'ts" section. |
| `CLAUDE.md` / `AGENTS.md`            | A pocket reference of commands, invariants, and style rules. Written for a coding agent, but works as a human cheat sheet too. |
| `src/content/contributors/*` | This guide: curated, public-facing contributor onboarding.                    |
| `src/content/guide/*`                | The end-user manual (how to use the app, not how to build it).                 |
| `src/content/plugin-development/*`   | Authoring guide for third-party Python plugin authors.                         |

## Working With A Coding Agent On This Repo

`CLAUDE.md` and `AGENTS.md` (identical content) are automatically read by coding agents (Claude Code, and other tools that follow the `AGENTS.md` convention) at the start of a session in this repo. That means you don't need to re-explain the command/history invariants, the `Part`-owns-mutations rule, or the style guide every time; the agent already has them.

Practical notes if you're new to working alongside an agent here:

- Point the agent at the relevant `docs/*.md` file before asking for a non-trivial change in that area. The agent is expected to load it, but naming it explicitly (e.g. "read `docs/commands-and-history.md` first") avoids it guessing.
- Treat agent-written changes like your own: run `pnpm check && pnpm test` (or the scoped `pnpm test`, which only runs suites affected by your diff) before considering the change done.
- [Claude Code](https://claude.com/claude-code) is the CLI this project's `CLAUDE.md` is written for; see its docs for installation.

## Further Reading

- [Node.js documentation](https://nodejs.org/en/docs)
- [nvm](https://github.com/nvm-sh/nvm) / [nvm-windows](https://github.com/coreybutler/nvm-windows)
- [pnpm documentation](https://pnpm.io/); see [pnpm vs npm/yarn](https://pnpm.io/motivation) if you're curious why this project uses it
- [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
- [Svelte documentation](https://svelte.dev/docs/svelte) and [Svelte 5 runes](https://svelte.dev/docs/svelte/what-are-runes)
- [SvelteKit documentation](https://svelte.dev/docs/kit)
- [Vitest documentation](https://vitest.dev/guide/)
- [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html), the base this project's style follows (see Code Style And Testing)


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/local-setup -->

# Local Setup

Foldnano uses SvelteKit 2, Svelte 5 runes, TypeScript, Konva, Three.js, Dexie, Pyodide, Tailwind 4, shadcn-svelte components (built on bits-ui), paneforge, and pnpm.

## Commands

```bash
pnpm dev
pnpm build
pnpm preview
pnpm check
pnpm lint
pnpm test
```

Run a single unit test file with:

```bash
pnpm vitest run src/lib/model/test/VirtualHelix.spec.ts
```

After cloning, enable blame ignore for the mass-format commit:

```bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
```

## Development Notes

- Tests run in jsdom.
- Model specs live primarily under `src/lib/model/test`.
- Svelte class files that use runes must use `.svelte.ts`.
- Runtime persistence uses IndexedDB, not `localStorage`.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/architecture -->

# Architecture Overview

Foldnano separates the DNA model, command/history layer, editor session, view context, and viewer components.

## Main Areas

| Area | Responsibility |
| --- | --- |
| `src/lib/model` | Part, regions, virtual helices, oligos, segments, ends, sequence slots |
| `src/lib/commands` | Undoable mutations and history capture |
| `src/lib/components/Editor/context` | Document session and view context |
| `src/lib/components/Editor` | Editor shell, toolbar, panels, viewers |
| `src/lib/services/storage` | IndexedDB and GitHub-backed document providers |
| `src/lib/plugin` | Plugin manifests, runtime coordination, Python bridge |
| `src/routes` | SvelteKit pages and API proxies |

## Editor Session Split

`EditorDocumentSession` owns document state, the history stack, storage manager, GitHub metadata, and tab ownership.

`EditorViewContext` owns active editor mode, active region/viewer state, strand-view context, UI controllers, selection sets, and derived tab-owner state.

Keep persistence and document lifecycle in the session. Keep transient editor UI state in the view context.

## Viewer Responsibilities

- Strand view is the main routing surface.
- Helix/lattice and freeform viewers edit virtual-helix placement in a design region.
- 3D view inspects lab-frame geometry, plane transforms, simulation previews, and 3D exports.

All lab-frame placement should come from `part.getVirtualHelixFrame(vh)`.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/model-commands-history -->

# Model, Commands, And History

## Commands And Transactions

**All model mutations go through commands.** Commands are plain functions in `src/lib/commands/` (not classes) that mutate the live model only inside a `HistoryStack` transaction:

```ts
export function someCmd(args: Args, history: HistoryStack): void {
	history.tx('Label', (rec) => {
		args.part.someMutation();
	});
}
```

Mutations made outside a transaction are reactive (the UI updates) but not undoable: the history stack never saw them, so undo/redo has nothing to replay. This is the single most common way a new feature quietly breaks undo.

There are two transaction APIs, and the choice matters:

- **`historyStack.tx(label, rec => ...)`**: use for targeted edits. It runs the mutation, records only the specific fields/slots that changed via the recorder (`rec.field(...)`, `rec.slot(...)`, `rec.oligo(...)`), and commits only if something actually differs. Cheap, and produces small, precise undo patches.
- **`historyStack.snapshotTx(label, () => ...)`**: use for structural edits (adding/removing virtual helices, regions, oligos, or anything else that changes the shape of the document, not just a field's value). It snapshots the whole document before and after and stores the diff as one `DocumentSnapshotChange`. More expensive, but correct for changes a targeted patch can't safely describe.

When in doubt: if you can name the exact fields that changed, use `tx`. If the edit restructures the document, use `snapshotTx`.

## Part Is The Only Mutation Owner

`Part` is the only mutation owner inside the model. Never write directly to `VirtualHelix._length`, `OligoSegment.slots`, `StrandSet.segmentIds`, or similar internal fields; go through a `Part` method instead.

This exists because `Part` is the one place that keeps derived state consistent when topology changes: the `SpatialIndexService` hit-test cache (keyed by `vh.id`), `vh.listRow` (row order), and the undo/redo mementos all assume mutations funnel through `Part`. A direct field write skips all of that bookkeeping: the model looks mutated, but the spatial index, row order, or undo history silently fall out of sync with it.

Concretely: `vh.listRow` is assigned by `Part.syncListRows()`, not derived on read. If you reorder a region's `vhOrder`, call the `reorderVirtualHelixCmd` command and let it rebuild `listRow`; don't write `vh.listRow` yourself. The same applies to `vh.latticeCoords` and `vh.localFrame`: go through region helpers and movement commands, not direct field assignment.

## Topology Identity: `vh.id`, Not `vh.listRow`

Topology (the spatial index, identity lookups) is keyed by `vh.id`. `vh.listRow` is a *display* concern: it can change when a region collapses or a user reorders the VH list, and it must not invalidate anything that depends on identity. Use `getEntitiesAtVh(vhId, ...)` when you need identity-stable lookups; `getEntitiesAt(vhRow, ...)` is a thin row-index adapter for display code only.

## Regions And Capabilities

Capability flags live on `DesignRegion`, not `Part`: `supportsLatticeGrid`, `supportsConstrainedXoverSites`, `supportsLatticeAutoStaple`. Use these, not `instanceof` checks, for UI and IO decisions, and gate on the *active region*, not the part. A single `Part` can contain a mix of lattice and freeform regions, so a part-level "is this lattice?" answer is frequently wrong for at least one of its regions.

## Reactivity

Reactive collections must be `SvelteSet`/`SvelteMap`: a plain `Set`/`Map` won't trigger Svelte's reactivity when mutated, so the UI silently goes stale. Plain `Set`/`Map` are fine only for caches that are intentionally non-reactive (e.g. `SpatialIndexService`'s internal index).

Class files that use `$state` or `$derived` must use the `.svelte.ts` extension: the Svelte compiler only applies the runes transform to files with that extension, and a rune in a plain `.ts` file is inert. See `docs/reactivity-patterns.md` for the full pattern, including snapshotting reactive classes for the history recorder.

## Crossover Direction

Crossover connections are always recorded 3' to 5': call `ThreePrimeEnd.connectTo(FivePrimeEnd)`, never the reverse. Downstream code (sequence generation, export) assumes this direction consistently.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/storage-github -->

# Storage, Autosave, And GitHub

## Storage Model

Foldnano is local-first: the live document lives in memory, is persisted to **IndexedDB** as the working copy through `StorageManager`, and is only synced to GitHub when the user explicitly commits or pulls. `localStorage` must not be used at runtime.

Local-first is a deliberate choice, not an accident of implementation order: it means a design is never lost to a flaky network request, a GitHub outage, or a user who's editing offline. The working copy is always the durable, in-browser source of truth. GitHub is layered on top as an explicit sync target, not the primary persistence backend, so a failed GitHub sync degrades to "you still have your local copy," not "you lost your edits."

GitHub-backed documents still keep local working-copy metadata (`GitHubMetadataStore`, `GitHubExplorerStateStore`, both backed by IndexedDB tables) for the same reason: the editor should stay usable and recoverable even if GitHub is briefly unreachable.

## Autosave

Autosave is a browser persistence path, not a publish path: it writes local IndexedDB state when dirty-state thresholds are met, and it must never stage, commit, or push to GitHub on its own.

Autosave and Git commits are deliberately kept as separate actions, even though a commit does persist the in-memory snapshot to IndexedDB first (so autosave and commit share one exact snapshot rather than racing against each other). The reason to keep them separate rather than "just auto-commit": committing is a visible, attributable action in someone else's GitHub history. A user should always be the one who decides a change is ready to be pushed, even though Foldnano is free to save their local progress continuously.

Only the tab owner may write. `EditorDocumentSession` checks `isTabOwner` before writing; preserve that gate when adding any new save path. This exists because IndexedDB is shared across tabs; without a single-writer gate, two tabs open on the same document could autosave over each other's in-progress edits.

## GitHub API Boundary

All GitHub API calls go through `/api/github/*`. The OAuth token is stored in an httpOnly cookie set by the SvelteKit server routes under `/api/auth/github/`; client code never reads or stores it.

This boundary exists specifically so that a client-side vulnerability (e.g. an XSS bug in a dependency) can't exfiltrate a user's GitHub token: the token is never in a place client-side JavaScript can reach, by construction, not by convention. Any new GitHub-touching feature must route through the server proxy rather than calling the GitHub API directly from the browser.

Current GitHub proxy areas include:

- repos
- branches
- contents
- trees
- commits

## Conflict And Overwrite Safety

Pull or overwrite flows must persist the current local snapshot first, then replace the browser working copy through a save that carries a `backup` option with a reason (`before_pull`, `before_accept_remote`, and so on). The storage layer keeps the replaced copy in the design's backup timeline in the *same transaction* as the overwrite, so there is never a moment where the overwrite happened and the backup didn't. Without it, a pull that turns out to be unwanted (wrong branch, stale local edits the user forgot about) would have no way back. The backup is what makes "pull" a safe, reversible action instead of a destructive one.

Any new GitHub write path should keep this same local-first behavior explicit: local autosave and Git commits/pulls stay separate actions, and destructive-looking operations (overwriting the working copy) get a backup first.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/plugin-runtime -->

# Plugin Runtime Architecture

The plugin runtime lets Python analyze or mutate designs without giving Python direct access to the live JavaScript model.

That last clause is deliberate: Python code runs inside a Pyodide (WASM) Web Worker, sandboxed away from the main thread. A plugin never gets a live handle into the editor's `Part`; it only ever receives a serialized snapshot and returns a serialized result (or a mutation log). All of that result is then applied back to the model by host-side TypeScript (`ResultApplicator`), inside a normal `historyStack` transaction, so a plugin can't corrupt the model, bypass undo, or touch anything outside what its declared format/strategy allows.

## Formats

| Format | Purpose |
| --- | --- |
| `cadnano_json` | Compatibility topology format. Lossy: sequences, modifications, oligo names are dropped. |
| `foldnano_json` | Full Foldnano snapshot: everything, including `isScaffold` and UUIDs. |
| `foldnano_edit` | Mutable Python mirror that records a replayable mutation log, rather than returning a whole new document. |
| `live` | Reserved and rejected by manifest validation (planned direct in-worker access; not available yet). |

`foldnano_edit` exists because whole-document replace/re-graft (`foldnano_json`) is coarse: any edit, however small, means diffing a full snapshot and re-matching annotations by coordinate. A mutation log instead captures the actual Python-side operations (add VH, set sequence, add crossover, …) as a structured op list, which the host replays against the *existing* live `Part` in one undo step. No coordinate re-matching is needed, and IDs for newly created entities are shared between the Python mirror and the host rather than guessed.

## Apply Strategies

Preview strategies (`previewOnly`) never touch the model: output is diff/log only, for analysis-only plugins. Replacement strategies (`replacePart[KeepAnnotationsWhereMatched]`, `replaceRegion[KeepAnnotationsWhereMatched]`) deserialize returned JSON and swap it into the document; the `KeepAnnotationsWhereMatched` variants re-graft sequences/mods/names onto segments whose coordinates are unchanged, since a whole-part replace otherwise regenerates all UUIDs and loses that data. Replay strategies (`replayMutationLog`, `replayMutationLogInRegion`) apply a `foldnano_edit` mutation log through command transactions against the live `Part`. This is why `foldnano_edit` is the only format the replay strategies accept: replaying an op log only makes sense against the format that produced one.

Use `replayMutationLogInRegion` when a plugin must be scoped to the active region: it rejects any operation that targets a VH outside the recorded active region and aborts the whole replay cleanly, rather than partially applying it. Without that check, a region-scoped plugin could silently reach outside its declared scope and mutate unrelated parts of the design.

## Contributor Rules

- Manifest validation must enforce compatible format/apply-strategy pairs: the pairing above isn't just a convention, install-time validation rejects mismatched combinations (e.g. `cadnano_json` + `replayMutationLog`).
- Mutating plugin results must become undoable editor history entries: `ResultApplicator` wraps every apply in `historyStack.snapshotTx` so a plugin run is always one undo step, never an untracked mutation.
- Region-scoped replay must reject out-of-region operations, per above.
- Plugin artifacts are downloads, not model mutations: an artifact a plugin produces for the user to save is not the same thing as applying a result to the live document.
- Plugin entrypoint and requirement loading should stay explicit and reviewable: a plugin's manifest declares what it needs (Python packages, wheel URLs) up front rather than fetching arbitrary code at run time.

Read `docs/python-plugin-system.md` for deeper implementation detail, and the [Plugin Development](https://fold.xinshilab.com/docs/plugin-development/plugin-quickstart) pages for the author-facing API.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/code-style-testing -->

# Code Style And Testing

## Naming

- `UpperCamelCase` for classes, interfaces, type aliases, enums, and Svelte components.
- `lowerCamelCase` for variables, functions, methods, parameters, and reactive fields.
- `SCREAMING_SNAKE_CASE` for module-level true constants.
- `_prefixedName` for private class members.
- File names are kebab-case for regular TypeScript, `ComponentName.svelte` for components, and `ClassName.svelte.ts` for rune-using classes.

The `.svelte.ts` extension on rune-using classes isn't stylistic: the Svelte compiler only applies the runes transform (`$state`, `$derived`, `$props`) to files with that extension. A `$state` field in a plain `.ts` file is inert; it looks reactive but never triggers a UI update.

## Types

Use interfaces for object shapes and type aliases for unions or intersections. Avoid `any`; use `unknown` with narrowing. Annotate public method return types. TypeScript can usually infer them, but an explicit return type documents the contract for callers and keeps a signature change from silently propagating an inferred type through the codebase.

## Comments

Comment only when the reason is not obvious: hidden constraints, subtle invariants, or workarounds. Keep comments short.

```ts
// Bad: restates what the code already says
// increment the counter by one
counter += 1;

// Good: explains a non-obvious constraint
// GitHub's contents API 404s on a 0-byte file, so write a single
// newline instead of an empty string.
await writeFile(path, content || '\n');
```

Comments describing *what* code does rot as the code changes and the comment doesn't; a well-named function or variable already says what, so the only comment worth writing is the *why* a reader can't get from the code itself.

## Formatting

Prettier owns formatting. Run:

```bash
pnpm lint
```

Use `pnpm format` only when intentionally rewriting formatting.

## Test Expectations

Run checks that match the change risk:

- `pnpm check` for Svelte and TypeScript correctness.
- `pnpm test` for unit tests (scoped to suites affected by your uncommitted changes; fast, the default inner loop).
- `pnpm test:branch` before pushing/opening a PR (scoped to suites affected vs. `main`).
- Targeted `pnpm vitest run ...` for focused model or service changes.
- Manual browser checks for UI, canvas, 3D, storage, GitHub, and plugin workflows; these aren't covered by the unit suite.

For model changes, prefer focused tests around commands, undo/redo, region behavior, and persistence snapshots.


────────────────────────────────────────────────────────────

<!-- Source: https://fold.xinshilab.com/docs/contributors/file-format -->

# File Format (.fn.json)

A Foldnano design file (`.fn.json`) is a single JSON document. It is what Foldnano commits to GitHub, what **Export as Foldnano JSON** downloads, and what you could share with other researchers. This page is the contract for that file: what each field means, its units and conventions, and what stays stable between versions.

It is written for anyone who reads or writes these files outside the editor: analysis scripts, other design tools, reviewers checking supplementary data, and contributors changing the model.

## Machine-readable schema

Each format version has a JSON Schema (draft 2020-12), published with the app:

| Format version | Schema                                                               |
| -------------- | -------------------------------------------------------------------- |
| 1              | [`/schemas/foldnano-v1.schema.json`](https://fold.xinshilab.com/schemas/foldnano-v1.schema.json) |
| 2              | [`/schemas/foldnano-v2.schema.json`](https://fold.xinshilab.com/schemas/foldnano-v2.schema.json) |

The schema checks structure and types. It does not check cross-references (for example that a segment's helix exists) or the conventions described below, so a file can pass the schema and still fail to load. The schema is also stricter than the app: it rejects fields it doesn't define, while Foldnano ignores them when loading and drops them on the next save.

Foldnano's test suite validates everything the app writes against the current schema and rejects unknown fields, so the schema, this page and the app cannot drift apart silently.

## Versioning and compatibility

Every file starts with a header:

```json
{
	"format": "foldnano",
	"formatVersion": 2,
	"savedWith": { "app": "0.5.1", "commit": "8e358c7" },
	"id": "…",
	"name": "…",
	"parts": []
}
```

- `format` is always `"foldnano"`.
- `formatVersion` is an integer. It is the only field Foldnano uses to decide whether it can open a file.
- `savedWith` records the Foldnano release and source commit that last saved the file. It is provenance only; never use it to decide how to read a file.

What Foldnano does:

1. **Older files keep opening.** A newer Foldnano upgrades an older file on load. Files saved before versioning existed (no header) are version 1.
2. **Newer files are refused, never misread.** If a file's `formatVersion` is higher than the running app supports, Foldnano shows an error and does not change anything, including your local copy.
3. **The version goes up whenever an older app could lose data**, including when a new field is added, because an older app would drop the unknown field when it saved the file again.

If you write a tool that reads `.fn.json`, check `formatVersion` first and refuse versions you don't know, the same way Foldnano does.

## Conventions

- **Base-pair index (`bp`)**: an integer position along a helix, starting at 0.
- **Strand direction**: every helix has two strands. Strand 0 runs 5'→3' in the direction of increasing bp index; strand 1 runs 5'→3' towards decreasing bp index.
- **Ranges are inclusive**: a segment from bp 0 to bp 20 covers 21 positions.
- **Lengths and positions in 3D are in nanometres (nm).**
- **Identifiers** are strings (UUIDs in practice). They are unique within a file and stable across saves, so they are safe to use for diffing two versions of a design.
- **Colours** are CSS hex strings such as `"#ff0000"`.

## Top level

| Field           | Type   | Meaning                                                  |
| --------------- | ------ | -------------------------------------------------------- |
| `format`        | string | Always `"foldnano"`                                      |
| `formatVersion` | int    | File format version (see above)                          |
| `savedWith`     | object | `{ app, commit }`: which build last saved the file       |
| `id`            | string | Document id                                              |
| `name`          | string | Document name                                            |
| `parts`         | array  | The designs in this document; most editing works on the first |

## Part

A part is one DNA origami design: its helices, strands and layout.

| Field                 | Type   | Meaning                                                                           |
| --------------------- | ------ | --------------------------------------------------------------------------------- |
| `id`, `name`          | string |                                                                                   |
| `planes`              | array  | Coordinate frames that regions are laid out on                                    |
| `regions`             | array  | Lattice or freeform areas that own helices                                        |
| `virtualHelices`      | array  | The double-helix positions                                                        |
| `oligos`              | array  | The DNA strands                                                                   |
| `customModifications` | array  | Optional. User-defined end modifications, `{ name, color }`                       |
| `overlayPlacements`   | array  | Optional. Where external 3D structures were placed; display only                  |
| `repeatGroups`        | array  | Optional. Repeat units; see [Repeat groups](#repeat-groups-and-mirror-oligos)      |

Optional arrays are left out when empty.

## Planes

A plane is a coordinate frame in 3D: `origin`, and the unit vectors `u`, `v` and `normal`, each `{ x, y, z }`. Regions place their helices in plane coordinates; the plane maps them into the shared 3D space.

## Regions

A region is an area of the design with one layout rule.

| Field          | Type           | Meaning                                                                                     |
| -------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `id`, `name`   | string         |                                                                                             |
| `kind`         | string         | `"HONEYCOMB"`, `"SQUARE"`, `"FREEFORM"` or `"WIREFRAME"`                                    |
| `planeId`      | string         | The plane this region sits on                                                               |
| `vhOrder`      | array of ids   | Display order of this region's helices (by helix `id`)                                      |
| `step`         | int            | Helix length grows in multiples of this many bp (honeycomb 21, square 32)                   |
| `turnsPerStep` | number         | Helical turns per `step`; `step / turnsPerStep` is the helical pitch in bp                  |
| `subStepSize`  | int            | Crossover spacing unit in bp                                                                |
| `twistOffset`  | number         | Phase offset of the helix twist, in degrees                                                 |
| `minBase`      | int            | First usable bp index; defaults to 0 if absent                                              |
| `maxBase`      | int            | Region length in bp. Older files call it `defaultMaxBase`; read that when `maxBase` is absent |
| `referenceGeometry` | object | Wireframe regions only, optional: the input shape, see below |

### Reference geometry

A wireframe region can store the shape it was designed from. It is reference material only: the helices are the source of truth, and nothing keeps the two in sync. A wireframe region otherwise behaves like a freeform region.

```json
"referenceGeometry": {
	"unit": "nm",
	"mesh": {
		"vertices": [[0, 0, 0], [12.5, 0, 0], [6.25, 10.8, 0]],
		"faces": [[0, 1, 2]],
		"edges": []
	}
}
```

- `unit` is always `"nm"`, and coordinates are in the region's plane coordinates, so the shape moves with the plane.
- `vertices` are `[x, y, z]` positions. `faces` are polygons and `edges` are pairs, both as indices into `vertices`. All three arrays are present in a `mesh`, and may be empty.

## Virtual helices

A virtual helix (VH) is one double-helix position. It holds two strands, which segments occupy.

| Field           | Type   | Meaning                                                                                                   |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `id`            | string | Stable identity                                                                                           |
| `index`         | int    | Helix number, unique within the part (the number cadnano shows). Segments refer to helices by this number |
| `listRow`       | int    | Row in the editor's strand view. Display only; don't use it as an identity                                |
| `regionId`      | string | The region that owns this helix                                                                           |
| `length`        | int    | Number of bp positions                                                                                    |
| `latticeCoords` | object | Lattice helices only: `{ row, col }` on the region's lattice                                              |
| `localFrame`    | object | Freeform helices only: `{ origin, axis, radial0 }` in the plane's coordinates, in nm                      |
| `strandSets`    | array  | Exactly two entries, strand 0 then strand 1                                                               |

In `localFrame`, `origin` is the position of bp 0, `axis` is the unit vector towards increasing bp index, and `radial0` is a unit vector perpendicular to the axis that fixes the rotation of the helix.

Each strand set is `{ strandIndex, segmentIds }`: the ids of every segment on that strand. It must agree with the segments' own positions.

## Oligos

An oligo is one continuous DNA strand, a staple or the scaffold, made of one or more segments joined end to end.

| Field              | Type    | Meaning                                                                                              |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `id`               | string  |                                                                                                      |
| `name`             | string  | Empty string when unnamed                                                                            |
| `color`            | string  | Display colour                                                                                       |
| `isScaffold`       | boolean | This oligo is the scaffold strand                                                                    |
| `isSequenceLocked` | boolean | A sequence was assigned to the whole oligo (for example the scaffold) and has not been edited since |
| `segments`         | array   | The oligo's segments. The array order carries no meaning; follow the end connections                |
| `repeatGroupId`    | string  | Optional. Marks an original of a repeat group                                                        |
| `mirrorOf`         | object  | Optional. Marks a mirror oligo; see below                                                            |

## Segments

A segment is the part of an oligo that lies on a single helix strand.

| Field                 | Type   | Meaning                                                                          |
| --------------------- | ------ | -------------------------------------------------------------------------------- |
| `id`                  | string |                                                                                  |
| `inVirtualHelixIndex` | int    | The helix's `index`                                                              |
| `fivePrime`           | object | The 5' end                                                                       |
| `threePrime`          | object | The 3' end                                                                       |
| `slots`               | array  | One entry per bp position, in 5'→3' order: `{ bpIndex, seq }`                    |
| `sequence`            | string | All slot sequences joined, 5'→3'. Redundant copy of `slots`, kept for readability |

The strand follows from the ends: if the 5' end's bp index is lower than the 3' end's, the segment is on strand 0, otherwise on strand 1.

A slot's `seq` describes what is at that bp position:

- one base (`"A"`): a normal position
- empty (`""`): a **skip**, no nucleotide at this position
- several bases (`"ATT"`): the base at this position followed by **insertions**
- `"N"`: a base whose sequence has not been assigned yet

Keep `sequence` equal to the joined slots when writing a file. If the two disagree but have the same total length, Foldnano uses `sequence`.

### Segment ends

| Field                | Type           | Meaning                                                                                                          |
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `segmentId`          | string         | The segment this end belongs to                                                                                  |
| `isThreePrime`       | boolean        | `true` for the 3' end                                                                                            |
| `index`              | int            | bp index of the end base (inclusive)                                                                             |
| `connectedSegmentId` | string or null | The next segment (from a 3' end) or the previous segment (from a 5' end); `null` at a free strand end             |
| `modification`       | string or null | Name of an end modification: a built-in (`Thiol`, `Biotin`, `Cy3`, `Cy5`) or one of the part's `customModifications` |
| `isConstrained`      | boolean        | Computed by Foldnano from the design; written for reference and ignored on load                                  |

Connections always run from a 3' end to the next segment's 5' end. To walk an oligo 5'→3', start at the segment whose 5' end has `connectedSegmentId: null` and follow each 3' end's `connectedSegmentId`. A scaffold that forms a closed loop has no free end; start anywhere.

## Repeat groups and mirror oligos

A repeat group copies a set of original oligos (those with its `repeatGroupId`) to other positions. Each entry in `instances` is `{ id, bpOffset }`: one copy shifted by `bpOffset` bp. (`vhMap` is reserved for future use.)

The copies are stored as ordinary oligos with a `mirrorOf` tag `{ groupId, instanceId, sourceOligoId, structure }`. `structure` is an internal fingerprint; treat it as opaque. Foldnano rebuilds mirrors from their originals, so edit the originals, not the mirrors.

Foldnano's staple exports leave mirror oligos out. If you build a staple list from a `.fn.json` yourself, decide deliberately whether to include oligos that have `mirrorOf`.

## Overlay placements

Where the user placed external 3D structures (PDB or mrDNA files) next to the design: `{ id, sourceKey, transform }`, with `transform.position` in nm and `transform.quaternion` as `[x, y, z, w]`. `sourceKey` is the PDB accession or file name. Only the placement is stored, not the structure itself, and it has no effect on the design.

## For contributors: changing the format

Any change to what `toJSON()` writes is a format change. In the same commit:

1. Increment `CURRENT_FORMAT_VERSION` in `src/lib/model/documentFormat.ts` and add a migration from the previous version to `MIGRATIONS`.
2. Add `static/schemas/foldnano-v<N>.schema.json`, keeping the older schemas, and add the version to the table on this page.
3. Add the fixture `test_files/fixtures/document_format/v<N>.fn.json`.
4. Update this page.

`DocumentFormat.spec.ts` and `DocumentSchema.spec.ts` fail until steps 1 to 3 are done; nothing checks step 4, so don't skip it.