ChemDraft

ChemDraft is a lightweight, local-file-first chemical drawing application under early development. The current milestone has a clean monorepo foundation, strict package boundaries, a native document model scaffold, plugin API/host foundations, page-layout infrastructure, a narrow active Ketcher molecule-editor host, and an optional fixture-backed MolScribe OCSR plugin scaffold.

This repository intentionally does not include full chemistry drawing beyond the first native single-bond and connected carbon-chain slices plus selected-molecule Ketcher editing, full RDKit integration, CDXML/CDX parsing, native clipboard handling, plugin sandboxing, real MolScribe OCSR inference, or proprietary assets yet.

Current Status

• apps/desktop contains a Tauri v2, Vite, React, and TypeScript desktop shell with native floating toolset windows for desktop builds and command-backed File > Page Setup controls.
• Packaged macOS builds use Sparkle 2 to check for signed app updates automatically and expose File > Check for Updates…; installed plugins remain in Application Support across app replacement.
• Phase 7 has started with command-backed active drawing tools, keyboard shortcut routing, a minimal document-backed native single-bond insertion path, selected carbon-chain extension through native atom/bond payloads, and a lazy Ketcher host for active selected-molecule editing.
• packages/chem-core owns the first native document model, schemas, patches, serialization, history helpers, page layout state, and paper-size presets.
• packages/ketcher-adapter provides a host adapter boundary with capability reporting and molecule load/save contracts. Ketcher is embedded only through a narrow desktop active molecule-editor host; chem-core remains the document/page source of truth.
• packages/plugin-api defines manifest schemas, permission names, command contributions, plugin context types, and recognition-result types.
• packages/plugin-host contains command registration, permission checks, plugin storage scoping, and proposed-patch handling.
• packages/viewport-engine owns viewport state, coordinate conversion, zoom math, and ruler render state; rulers and crosshairs consume document page layout.
• apps/desktop/src/surfaces contains a tiny metadata-only UX surface scaffold. Rendered UI is not yet driven from it.
• Other packages are boundary placeholders for future work.
• examples/plugins/molscribe-ocsr provides an optional fixture-backed MolScribe OCSR scaffold without adding ML dependencies.

Commands

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm dev
pnpm dev:web

pnpm dev launches the ChemDraft Tauri desktop app through ./run-app --dev, so normal dev launches clear stale ChemDraft instances and use the same app identity as packaged runs. In the desktop app, drawing toolsets are separate native windows that route command IDs back to the main document window, with visibility and placement persisted by the desktop shell. Use pnpm dev:web only as a secondary browser preview while working on the React surface; the browser preview uses in-window floating palette overlays, not palettes embedded in the document canvas.

The first native build downloads the pinned Sparkle framework from its official release and verifies
its SHA-256 before use. Release/appcast instructions are in
docs/releasing/macos-updates.md; Sparkle update checks run only from a packaged macOS app, not the
browser-only preview.

The ./run-app helper builds the packaged macOS app and launches it as ChemDraft (dev), identifier org.chemdraft.desktop.dev.<worktree-slug>, with its own app data and single-instance lock. It moves the bundle into <worktree>/app/ and never builds over, renames, or unregisters the stable /Applications/ChemDraft.app (org.chemdraft.desktop), which is built from main (AGENTS.md §15.2 The stable app is never replaced). Use ./run-app --dev only when you explicitly want Tauri dev mode with Vite/HMR; it runs a bare binary with no bundle identifier. Tauri requires Rust/Cargo to be installed and available on PATH.

Windows

The same commands work on Windows 10/11 (x64). pnpm dev and the desktop build/tauri scripts run
through Node launchers (scripts/dev.mjs, scripts/desktop-tauri.mjs) that keep macOS on its exact
existing path and skip the macOS-only steps (Sparkle, signing) elsewhere.

Prerequisites: Node 24 + pnpm 10.12.1, Rust via rustup (the pinned toolchain installs itself), Visual
Studio 2022 Build Tools with the C++ workload, and WebView2 (preinstalled on Windows 11). For the
optional pieces: a JDK for the OPSIN runtime, CMake for the Engine 3D sidecar.

pnpm install
pnpm dev
node scripts/build-opsin-runtime.mjs
pnpm --filter @chemdraft/desktop build --bundles nsis

• The build produces apps/desktop/src-tauri/target/release/bundle/nsis/ChemDraft_<version>_x64-setup.exe,
  a per-user installer (no admin); it is unsigned, so SmartScreen will ask once.
• Built from any branch but main, it is ChemDraft (dev) (ChemDraft (dev)_<version>_x64-setup.exe,
  installed to %LOCALAPPDATA%\ChemDraft (dev)), with a per-worktree identifier — its own app data and
  single-instance lock, so it installs beside the stable app rather than over it (AGENTS.md §21.2).
  Release automation building a tagged commit sets CHEMDRAFT_STABLE_BUILD=1.
• The released app updates itself: a daily check of a signed feed on main, File ▸ Check for
  Updates…, and never a silent install. Publishing an update, and where the signing key lives, is in
  docs/releasing/windows-updates.md. The installer itself is not Authenticode-signed yet, so
  SmartScreen still warns on a manual download.
• The Windows installer registers .chemdraft only (tauri.windows.conf.json). The macOS .cdxml entry
  ranks ChemDraft as an Alternate handler, but NSIS ignores rank: a per-user install would write
  HKCU\Software\Classes\.cdxml, which outranks ChemDraw's machine-wide registration and silently takes
  over every .cdxml double-click. Open .cdxml files through File ▸ Open or Explorer's "Open with".
• The Windows sidecar binary is committed; rebuild it with
  cmake --preset windows-msvc && cmake --build --preset windows-msvc in native/avogadro3d-sidecar
  after fetching _deps as its README describes.
• Keep the checkout outside OneDrive. Syncing node_modules and target/ makes builds and the test
  suite several times slower.
• Debug builds are large (~9 GB of target/debug with full debuginfo); on a small disk set
  CARGO_PROFILE_DEV_DEBUG=0.

Using ChemDraft from an AI assistant

The ChemDraft agent skill guides local assistants through
the headless CLI and eight MCP tools for structures, reaction schemes, analysis, NMR
predictions and exports. It requires computed results and preserves warnings and
chemical identity. See setup for macOS and
Windows installation, Claude Code, Claude Desktop with MCP, and Codex configuration.

Architecture Rules

Read PLAN.md and AGENTS.md before making changes. In short:

• Chemical identity must not be silently changed.
• CDXML/CDX compatibility must not become the native document model.
• External engines must stay behind adapter packages.
• Plugins must request document changes through controlled APIs.
• Migration-critical drawing and clipboard workflows are first-release concerns.
• Do not copy proprietary icons, templates, documentation, sample files, or visual assets.
• Do not use MolScribe as the app name; reserve it for the optional OCSR plugin integration.

Dependency Notes

The initial dependency inventory is recorded in docs/architecture/dependency-inventory.md.