Project Rules

Project Rules

This page summarizes the repository-wide contribution rules and points to the detailed developer guides.

AGENTS.md is the binding repository source. This digest helps a new contributor understand its intent; it does not replace the full rules or the active slice in PLANS.md. Rules apply to human and automated contributors on every branch.

Ship macOS and Windows together

Every code change must work on both platforms. Releases use the same commit and version, with a macOS DMG and Windows NSIS installer. Shared code is preferred; necessary platform branches are implemented together.

Test TypeScript platform differences through an injectable platform parameter. Native code must pass format, clippy with warnings denied and tests on both hosts. Report macOS and Windows verification separately, naming exactly what remains if one is unavailable. A shared test pass is not a native platform pass.

Respect the existing differences: macOS has an application-wide menu, while Windows gives a menu only to the document window. Utility windows remain document-owned and avoid stealing focus or appearing on the Windows taskbar. Windows registers .chemdraft only, never taking over .cdxml. New cross-platform scripts use Node and path APIs.

Preserve chemical meaning

Conversions preserve atoms, bond orders, charge, isotopes, radicals, stereochemistry, represented superatoms/R-groups, reaction roles/components and applicable coordinates. Mechanism annotations stay editable. If a representation cannot preserve meaning, warn or fail instead of degrading silently.

Drawing style and layout are not chemistry edits. Tests compare relevant chemical identity, formula, charge, stereo and graph counts, with geometry tolerances where needed. Unknown bonds do not become single bonds merely to make an export succeed.

Analysis numbers retain methods, interpretations, units, conventions and honest statuses. Unsupported chemistry returns unsupported rather than a fallback number. Chemistry engines derive chemistry; presentation code does not become a second interpretation engine. Branch on classification flags rather than descriptive derivation or claim labels.

NMR predictions use the OCL-native HOSE lookup over NMRShiftDB2 experimental assignments. Label first-order multiplicity and coupling estimates, warn on partial results and do not fabricate shifts for unmatched environments. Recognition is experimental and always reviewed before insertion.

Keep one implementation per responsibility

The native model is chem-core; CDXML is a compatibility boundary. Molecule rendering math and atom-label grammar live only in layout-engine, including Spin 3D geometry consumers. Pure document functions shared with CLI/MCP live in document-workflow-core, without UI, native APIs or engine loading.

Menus, toolbars, shortcuts and plugin actions use registered commands or typed host capabilities. IDs encode their values through factory helpers. Do not create click-only major behavior, generic hidden-parameter setters or speculative permanently disabled tools.

Compatibility claims are fixture-driven. Preserve unknown objects or report warnings, and distinguish supported chemistry from approximated graphics. Never advertise universal CDXML/CDX compatibility from a handful of successful files.

Grant extensions only declared authority

A plugin imports only @chemdraft/plugin-api among ChemDraft packages. Permissions are declared in its manifest and enforced by the host. File, network, process, model, clipboard and document access do not appear as undeclared side effects. Process-spawning capabilities also require native.execute.

Plugins and agents edit through patches, one labelled undo entry per action, leaving changed content selected. Deterministic insertion of user-authored input can use the command-scoped document.write gate. Existing-content edits and uncertain generated results use proposal review; image recognition never uses direct insertion.

Keep one persistent runtime through document/selection/undo changes. Analyzer workers have complete teardown, and report panels use the shared declarative renderer. API contracts are typed and versioned: additive changes bump the patch; breaking changes bump the minor in the current 0.x API series.

Keep desktop surfaces honest and movable

Use real native document objects or an honest unavailable state. New desktop tool palettes, panels and dialogs float in their own document-owned windows and can move to another monitor. Shared dialog-host forms do not receive arbitrary native or document authority. Simple confirmations use native message boxes.

Preserve accessible submenu behavior, exactly-once command invocation and specific temporary disabled reasons. Do not invent tooltips or show unfinished tools as permanently disabled promises.

Keep assets, names and licences clean

The app is ChemDraft. Public text does not name or compare commercial competing chemical-drawing products. MolScribe refers only to the external recognition project and optional plugin. Use original or legally redistributable assets and fixtures.

Core code is Apache-2.0; the two SDK packages and example plugins are MIT. Dataset terms remain separate. Ship NOTICE, record new vendored binaries in the inventory, and retain the unresolved InChI 1.07.3 redistribution gate until formally cleared.

Finish with evidence

Work in your branch's worktree, land through a green pull request and never replace the stable app with a branch build. Preserve worktree labels. Runtime changes require the build-stamp bump, supported launch and relevant automated/manual checks. Move completed slices into docs/shipped/README.md.

Report the summary, changed files, commands and pass/fail results, both platform statuses, limitations and one next task. Specific errors and explicit gaps are more useful than an unsupported claim of completion.

See also

• Contributing
• Testing and CI
• Package Map
• Chemistry Guarantees