Mechanism Canvas

An organic chemistry canvas where WebMCP agents test competing mechanisms, show their evidence, and leave the final move to the learner.

Comment

About Mechanism Canvas

Inspiration

I kept coming back to a mismatch between how students solve organic chemistry problems and how AI tutors usually communicate. Reaction mechanisms live in diagrams. The important details are the atoms, bonds, lone pairs, curved arrows, and the order in which electrons move. A separate chat window sees almost none of that unless the student stops and translates the drawing into prose.

Giving an agent broad control of the drawing surface creates a different problem. It can finish the exercise before the learner has worked through it. I wanted to see whether an agent could help inside the real mechanism canvas while the student still controlled the consequential part: what actually gets added to the answer.

That became the central idea behind Mechanism Canvas. The agent gets a safe place to explore. The page checks the chemistry. The learner decides what comes back.

What I built

Mechanism Canvas is an organic chemistry workspace where a student and a WebMCP agent can work with the same structured mechanism. The page exposes meaningful chemistry objects instead of screen coordinates, so the agent can refer to a particular atom, bond, lone pair, or revision without guessing from pixels.

The main demo is a counterfactual (S_\mathrm{N}2) lab. The agent tests two electron-flow paths away from the learner's draft. In the first branch, it forms the new bond but forgets the coupled leaving-group cleavage. The production validator rejects that attempt. The second branch contains both moves, so the validator approves it.

The checked branch then reaches a visible proposal gate. It still does not change the learner's mechanism. The learner can inspect the evidence, add the proposal to the draft, request one more check, and make the final commit. An incorrect agent attempt becomes useful evidence instead of damage that has to be undone.

The site also works as a complete manual tutor when WebMCP is unavailable. Direct agent collaboration is an extra layer on top of the same interface rather than a separate agent-only experience.

How I built it

I built the app with React, TypeScript, and Vite. The mechanism canvas is backed by a structured graph with stable IDs for atoms, bonds, electron sources, and curved-arrow moves. A deterministic chemistry engine evaluates proposed steps against six reviewed fixtures. The model can suggest and explore, but it does not decide whether a mechanism is chemically valid.

The WebMCP layer registers 26 imperative tools through document.modelContext.registerTool. Each tool uses a closed JSON schema and calls the same TypeScript store commands as the visible interface. Mutating calls re-read live state and check the current revision, scope, and learner-granted permissions before they run.

Tool discovery changes with the task. Coach mode begins with 16 available tools. Opening the two-path lab adds the branch controls. Starting a six-action comparison session narrows the surface to the capabilities needed for that job. Once the action budget is used, the work tools disappear and only four evidence controls remain. A cached tool cannot restore access that the learner has already closed.

I also built a Collaboration Contract where the learner sets the agent's maximum role and hint level. An intent-bound session freezes the job, problem, revision, and action budget. The Live Run Observatory shows which capability batches the host accepted, and a Proof Ledger records privacy-minimized before-and-after receipts from the actual tool callback boundary.

Around that core, I added keyboard-operable SVG structures, local persistence, reversible commits, state diffs, electron-flow replay, and a lazy-loaded Three.js molecular inspector. The finished project is a static GitHub Pages site with no backend, account, or credentials required.

Challenges

The hardest engineering problem was keeping tool discovery honest while the page changed. A fixed list of 26 tools would technically work, but it would hide the learner's current intent inside descriptions. My first dynamic version swung too far in the other direction: every small store notification could publish a transient capability batch. Those batches were real, but they did not represent a stable state that a judge or learner could understand. I changed the registration layer to coalesce related updates, wait for the complete batch, and record only surfaces the host had accepted.

Proof was another difficult part. A model saying that it called a tool is only a claim. I needed the page to show whether the callback ran, whether the expected state changed, and whether the main draft stayed untouched. The Proof Ledger now wraps the real callback boundary, and the Observatory evaluates its seven demo claims from those receipts.

I also had to make failure safe without making it invisible. The two lab branches have real revisioned state and use the same validator as the main canvas, but they remain isolated until the learner chooses a checked proposal. That separation took more work than simply giving the agent an undo button. It is also the part that makes the workflow useful for learning.

What I learned

I learned that an agent's tool list is part of the user interface. A capability name, its schema, when it appears, and when it disappears all communicate authority. Encoding the learner's intent in that surface made the boundary much clearer than relying on prompt instructions alone.

I also learned how well deterministic software and agent reasoning can complement each other. The agent is good at generating alternatives and explaining a choice. The chemistry engine is good at enforcing exact constraints every time. Keeping those jobs separate made the result easier to trust.

Most of all, this project changed how I think about mistakes in learning software. A wrong attempt does not have to be erased or quietly corrected. When it is isolated, checked, and kept visible, it can show the learner exactly why the complete mechanism needs both electron-flow moves.

What's next

The current chemistry engine is intentionally limited to reviewed fixtures. I would like to add an instructor authoring flow for new mechanisms and study how different permission contracts affect the explanations students give. The same pattern could also work in circuit design, geometry, and other visual STEM tools where exploration is useful but ownership should stay with the learner.

Built With

Share this project:

Updates

Submission history