0002 — TypeScript engines as source packages

Status: accepted

Context

The same engines must run in the browser, in Electron, in Node (CLI, CI) and in workers. The blueprint suggested Rust/WASM for the kernel “where it provides value”.

Decision

Engines are written in strict TypeScript and published as source (exports pointing at .ts). Every consumer already bundles: Vite for the app, esbuild for Electron, tsx for the CLI. Geometry uses integer nanometres, which keeps arithmetic exact without a native kernel. Third-party native code is consumed as WebAssembly where possible (Yosys and nextpnr through YoWASP). Rust is reserved for areas where TypeScript is demonstrably insufficient. The solid-modelling kernel (OpenCascade) is the expected first case.

Alternatives

• Rust core with TypeScript bindings: more build complexity on four platforms, and slower iteration while the model is still changing.
• Shipping compiled JavaScript: possible later for third-party consumers. For now it would add a build step to every engine change.

Consequences

Type definitions are the source, and no .d.ts files drift. When the SDK goes public, its package will be compiled to JavaScript with declarations.