MoleQL

Build a molecule from a periodic table, watch it relax into correct 3D geometry, and turn it over with your hands in front of a webcam.

The point is the moment a thing you assembled is named back to you — drop an oxygen, hang two hydrogens off it, and the app says Water · H₂O and shows you why it is bent. No headset, no research-grade tooling, no account.

Build — place atoms, bond them, undo it all	Read — computed, retrieved, and estimated never mix
Analyze — real measured angles, VSEPR shapes, lone pairs	Stereochemistry — CIP labels on every chiral centre
Search — by name, by formula, or browse 98 built-ins	Library — what you built stays on your machine

Why you'll like it

• The chemistry is real. Geometry comes from RDKit — ETKDG plus MMFF94, or UFF where MMFF has no parameters, and the app tells you which one ran. Nothing on screen is a cartoon.
• It never bluffs. Computed, retrieved, and estimated values live in separate sections that values may not cross between. The melting-point estimate is shown as a range, because a point value would be a lie.
• An impossible molecule is explained, not rejected. Five bonds on a nitrogen gets you RDKit's own words about why, which is the teaching moment.
• Your hands work as a controller — pinch to pan, one fist to rotate, two fists to zoom — and everything works perfectly well without them.

Download

Download MoleQL for macOS (Apple Silicon) — a DMG with the chemistry engine already inside. No Python, no Node, no account.

First launch on an unsigned build

The build is not notarized, so macOS will refuse it on the first double-click. Right-click the app and choose Open, then confirm — or clear the quarantine flag from a terminal:

xattr -dr com.apple.quarantine /Applications/MoleQL.app

Intel Macs and other platforms are not built yet. Everything runs from source on any machine that can run Electron and RDKit.

Run it from source

macOS, Node 20+, and uv for the Python side.

npm install          # also fetches the hand-tracking model and MediaPipe's WASM
npm run setup:py     # creates sidecar/.venv and installs RDKit
npm run dev          # Vite dev server + Electron with live reload

npm start builds and runs the app without the dev server. npm run package produces the DMG, bundling a relocatable Python so the download needs nothing installed.

What it does

Build. Pick an element, click the viewport to place it, drag between atoms to bond them. Bond, erase, undo, redo. Every atom is explicit: an oxygen you drop alone stays atomic oxygen and does not quietly become water.

Solve. The structure goes to a bundled Python process running RDKit, which returns real 3D coordinates and a valence verdict.

Read. A minimal always-on strip carries formula, name, and any valence warning. Everything else sits behind a detail panel split into three sections:

Section	Contains
Computed	Exact RDKit descriptors — MW, LogP, TPSA, H-bond donors/acceptors, rotatable bonds, formal charge, aromatic rings
Retrieved	PubChem name, IUPAC name, synonyms, CID, with attribution and a link
Estimated	Melting point via Joback group contribution, as a range (±40 °C) whose width reflects model uncertainty, never as a point value

Any computed row can be pinned, and pins survive a relaunch.

Manipulate. Mouse orbit, zoom, and pan are complete and first-class. Turn on hand gestures and three pose-gated gestures drive the same camera:

Gesture	Does
Pinch and drag	Translate
Two closed fists, apart or together	Zoom
One closed fist, drag	Rotate

Measured in the Phase 0 spike on an M-series laptop, GPU delegate: 12.7 ms p95 end to end against an 80 ms budget, 109 fps, and zero false fires in a 60-second test with hands resting in frame. Every gesture is pose-gated, which is what made that possible — motion-gated gestures could not be made reliable at any threshold.

Honest limitations

• macOS on Apple Silicon for the download, and the build is unsigned.
• Camera frames never leave the machine, and the app is fully usable with the camera denied, missing, or switched off. Gestures are opt-in per session and never auto-start.
• PubChem needs the network. Offline, you keep every computed value and lose only the compound's name and formula search. No local compound dataset ships yet.
• The melting-point band is wide (±40 °C), which is the published error of the Joback method. This is honest, not a placeholder. Confidence is communicated through range width, not through model confidence scores.
• Gesture fatigue is unmeasured. Every gesture metric comes from short deliberate testing, not a study-length session. MediaPipe's landmark quality under real hands and real ergonomics remain unvalidated until usability testing.
• Gesture-precision testing is classifier validation only — that the classifier detects intended poses given synthetic landmark geometry — not end-to-end latency or comfort with real hands.
• Chlorine trifluoride is not in the built-in list. RDKit will not accept three bonds on a neutral chlorine in any encoding, and a card that can only fail is worse than an absent one.
• Proteins, constitutional isomer subtypes, and exhaustive stereoisomer enumeration are later phases, deliberately.

Status

MVP: PRD phases 0–7 and 9–11 are complete — chemistry, builder, viewer, property panel, gestures, geometry overlays, formula search with isomer classification, and melting-point prediction all work end to end. Phase 8, a usability test with n≥5 first-time learners, is the open gate on the core hypothesis and has not been run.

Development

npm test             # vitest: graph, MOL block, gestures, controller, panel, presets, IPC clients
npm run test:py      # pytest against the RDKit sidecar
npm run typecheck    # renderer and main process, both strict
npm run smoke        # boot the real app, screenshot it, fail on any renderer error

The gesture constants in src/gesture/ are tuned values from a measured spike. Changing one is not a code-review decision — it requires re-running the 60-second idle test.

Under the hood

• docs/architecture.md — module contracts and how the pieces fit
• .claude/PRPs/prds/moleql.prd.md — requirements and the reasoning behind every decision
• docs/usability-test.md — the Phase 8 protocol, still to be run
• LICENSE — MIT, plus the licences of everything bundled
• spikes/ — the Phase 0 and 1 throwaway prototypes, kept because they document how the decisions were reached

Electron and TypeScript, NGL for rendering, RDKit in a bundled Python sidecar for chemistry, MediaPipe Tasks Vision for hand landmarks, and PubChem PUG-REST for identification. Almost all of the chemistry and all of the rendering is borrowed; what is written here is the builder, the panel, the gesture interpretation, and the glue.