NAK-569 Use industry best practices in wasm

[Victorcorcos]

Summary

This PR compiles the C++ equations-parser to WebAssembly using Emscripten, wires it into a generalized JS wrapper, and adds a browser playground for interactive evaluation. It also introduces a modern project structure (ESM/CJS entries, types, tests, lint/format), aligning with the Parsec Web vision in AGENTS.md.

Context & Motivation

• Deliver a reusable, cross-platform JS library backed by WebAssembly for fast, client-side equation evaluation.
• Provide an interactive HTML test page for easy manual validation and demos.

Changes

High-level:

• Build WebAssembly with Emscripten into a single JS artifact (wasm/equations_parser.js) for easy browser loading.
• Add js/equations_parser_wrapper.js exposing a Parsec class with initialize() and eval().
• Add dev tooling: Vitest, ESLint, Prettier, npm scripts, and TypeScript types.
• Add an HTML playground to exercise the library from the browser.

Commits (latest first):

• Add wasm/equations_parser.js
• Generate wasm file via Emscripten
• Improve CLAUDE.md

Files added/updated (relative to main):

• Added: .eslintrc.cjs, .prettierrc, .prettierignore
• Added CI: .github/tests.yml, .github/workflows/tests.yml
• Added docs: AGENTS.md, CLAUDE.md (development guide)
• Updated: .gitignore, README.md, build.sh
• Added C++: cpp/equations_parser_wrapper.cpp
• Added HTML demo: html/equations-parser-test.html
• Added entries: index.cjs, index.mjs, types.d.ts
• Added wrapper: js/equations_parser_wrapper.js
• Added config: package.json, package-lock.json, vitest.config.js
• Added WASM bundle: wasm/equations_parser.js (SINGLE_FILE JS with embedded WASM)
• Removed legacy phase-1 artifacts: cpp/math_functions.cpp, html/test.html, js/math_wrapper.js, test-phase1.sh, wasm/math_functions.js, docs/phase1-guide.md

Implementation Details

• Emscripten build (see build.sh):

  • Key flags: -s MODULARIZE=1, -s EXPORT_ES6=1, -s SINGLE_FILE=1, -s ENVIRONMENT=web, -O3, --bind, -s ALLOW_MEMORY_GROWTH=1.
  • Output: wasm/equations_parser.js — ES module exposing EquationsModule factory. The .wasm binary is embedded in the JS (no separate file).
  • Sources: cpp/equations_parser_wrapper.cpp + all files under equations-parser/parser/.

• JS wrapper (js/equations_parser_wrapper.js):

  • Exposes a Parsec class with initialize() to load the WASM module and eval(expression) to evaluate a string expression.
  • Designed for browser usage first; compatible with ES modules.

• Package setup (package.json):

  • Dual entry points: index.cjs (CommonJS), index.mjs (ESM), plus types.d.ts.
  • Scripts: build, test, lint, format, style:fix, dev/serve.
  • Vitest configured with jsdom environment.

How to Test

Automated (Vitest):

• npm install
• npm test — run all tests
• npm run test:watch / npm run test:coverage as needed

Manual (Browser UI):

1. Start dev server: npm run dev (serves on http://localhost:8000)
2. Open http://localhost:8000/html/equations-parser-test.html
3. Verify the yellow status changes to green: “Equations-Parser WebAssembly module ready!”.
4. In “Interactive Equation Evaluation”:
   • Type 2 + 3 * 4 and click “Evaluate” → expect 14.
   • Type sin(pi/2) → expect 1.
   • Type concat("Hello", " ", "World") → expect "Hello World".
   • Try a ternary: 5 > 3 ? "yes" : "no" → expect "yes".
5. Click items under “Quick Test Examples” to auto-fill equations; click “Evaluate” and observe results.
6. Use “Supported Functions” list: click any function to auto-fill an example; evaluate and confirm outputs.
7. Open the “Console Output” section to see JS/C++ logs; use “Clear Console” to reset.

Expected:

• UI enables “Evaluate”, “Clear”, and “Run All Tests” after initialization.
• Correct numeric and string results; errors are displayed with red styling.

Risks & Considerations

• Current build targets browser (-s ENVIRONMENT=web). If Node runtime support is needed for the WASM module itself, we can extend to web,worker,node.
• The Emscripten compiler uses a cache outside the workspace; CI scripts install and activate emsdk accordingly.
• The SINGLE_FILE output eases hosting but increases JS bundle size. If separate .wasm is preferred, we can remove -s SINGLE_FILE=1 and adjust loader.

Rollback Plan

• Revert this PR to restore the phase-1 setup and remove the WASM module and related files.

Checklist

• Build succeeds locally: npm run build
• Tests pass: npm test
• Lint/format clean: npm run style:fix
• Browser manual checks pass via html/equations-parser-test.html