Package Surfaces
| Surface | Package | Runtime |
|---|---|---|
| JavaScript / WASM | @libraz/formulon | Browser, worker, Node |
| Native Node | @libraz/formulon-native | Node.js N-API addon |
| Python | formulon | py3 wheel using wasmtime |
| CLI | formulon-cli-<os>-<arch> | Standalone binary |
| C ABI | headers and native library | Custom hosts |
| MCP | @libraz/formulon-mcp | stdio MCP server for agents |
| UI shell | @libraz/formulon-cell | Browser spreadsheet UI (beta) |
All surfaces should expose the same calculation core. Differences should be packaging differences, not semantic differences.
Glossary: surface
A packaging boundary on top of the shared C++17 engine. Every surface speaks to the engine through the C ABI (directly or transitively). What changes between surfaces is host language, memory ownership, and IO style — never formula semantics.
Surface maturity
| Surface | Maturity | Notes |
|---|---|---|
| WASM | broadest JS API | Full generated formulon.d.ts, browser and Node support |
| Python | stable subset | wasmtime-backed wrapper, context-manager workbook lifecycle |
| CLI | focused tools | eval, recalc, dump |
| Native Node | MVP subset | Faster native path, not yet full parity with WASM |
| C ABI | binding contract | Stable low-level contract for packaged surfaces |
| MCP | agent-facing surface | Built on top of WASM; allowlisted method dispatch |
formulon-cell | beta UI | Demonstration host for the WASM engine |
When surfaces disagree
If two surfaces produce different values for the same workbook and the same profile, treat it as a bug or a documented compatibility gap. The parity runner under make parity-test exercises shared fixtures across available channels and reports both missing and mismatched results.
Read next
- WASM API — JavaScript surface.
- Python API — top-level wrapper.
- CLI reference — command surface.
- Choose a surface — decision guide.