DIGIT-2257 Implement web platform channel

[Victorcorcos]

Summary

This PR introduces full Web platform support for the Parsec Flutter plugin using WebAssembly (WASM) compiled from the same C++ equations-parser library used by native platforms. This ensures true cross-platform consistency and high performance for mathematical equation evaluation in web browsers.

Architecture Pattern

graph TD
    A[Parsec Plugin] --> B[ParsecPlatform Interface]
    B --> C[parsec_android - JNI/C++]
    B --> D[parsec_linux - FFI/C++]  
    B --> E[parsec_windows - FFI/C++]
    B --> F[parsec_web - WASM/JS]
    F --> G[equations-parser.wasm]
    C --> H[equations-parser C++]
    D --> H
    E --> H
    G --> H

Loading

Overview

Key Features Added

• ✅ WebAssembly Integration: Real WASM compilation from C++ equations-parser (38 source files)
• ✅ Automated WASM Generation: New Dart-based command dart bin/generate.dart
• ✅ Comprehensive Web Testing: Chrome-based automated testing with multi-Flutter version support
• ✅ Cross-Platform Consistency: Identical results across Web, Android, Linux, and Windows
• ✅ Performance Optimized: ~1-10ms evaluation times with offline capabilities
• ✅ Complete Documentation: Updated README with installation, troubleshooting, and testing guides

🏗️ New Package: parsec_web

• Implements ParsecPlatform interface for Web via WebAssembly
• Includes parsec-web JavaScript wrapper as git submodule
• Provides dart bin/generate.dart command for WASM compilation
• Supports all mathematical functions available on native platforms

🔧 Core Plugin Updates (parsec/)

• Added Web platform to federated plugin architecture in pubspec.yaml
• Enhanced platform detection and delegation
• Updated main Parsec class for async/await consistency
• Comprehensive documentation update in README.md

🧪 Testing Infrastructure

• Web Integration Tests: Full Chrome-based testing pipeline
• Multi-Flutter Support: Tests against Flutter 3.19.0 and 3.24.0
• WASM Artifact Management: Upload/download between CI jobs for efficiency
• Cross-Platform Validation: Ensures identical behavior across all platforms

📚 Documentation Enhancements

• Updated README.md: Complete installation, usage, and troubleshooting guide
• Web Setup Instructions: Step-by-step WebAssembly configuration
• Performance Benchmarks: Platform comparison and expected behavior
• Enhanced CLAUDE.md: Web development workflow and prerequisites

⚙️ CI/CD Improvements

• New web_tests.yml: Dedicated Web testing workflow
• WASM Artifact Reuse: Efficient build caching between workflow jobs
• Extended Analysis: Added parsec_web package to CI analysis pipeline

WebAssembly Workflow

1. Source: Same C++ equations-parser library (38 files)
2. Compilation: Emscripten toolchain generates WASM binary + JS glue
3. Integration: JavaScript wrapper provides Flutter-compatible API
4. Deployment: Assets served from packages/parsec_web/parsec-web/

Test Guidance

Prerequisites for Testing

1. Install Emscripten (for WASM generation):

# Ubuntu/Debian
sudo apt-get install emscripten

# Or via emsdk
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest

2. Generate WebAssembly Files:

cd parsec_web
dart bin/generate.dart

🧪 Step-by-Step Testing Process

1. Verify WASM Generation

cd parsec_web
dart bin/generate.dart

# Verify output files exist
ls -la lib/parsec-web/wasm/
# Should show: equations_parser.js (~635KB), equations_parser.wasm

2. Run Cross-Platform Tests

# Test all native platforms
cd parsec && flutter test

# Test Web platform specifically  
flutter test --platform chrome

# Test Web integration
flutter test --platform chrome test/parsec_web_integration_test.dart

3. Validate JavaScript Integration

cd parsec_web/lib/parsec-web
npm install && npm test

# Test both CommonJS and ES6 imports
node -e "const E = require('./index.cjs'); console.log('✅ CommonJS works')"
node --input-type=module -e "import('./index.mjs').then(()=>console.log('✅ ES6 works'))"

4. Manual Testing - Web Example

cd parsec/example
flutter run -d chrome

# Test equations in the web UI:
# - Basic: "2 + 3 * 4" → 14
# - Advanced: "sin(pi/2) + cos(0)" → 2.0
# - Complex: "5! + sqrt(16)" → 124

5. Manual Testing - Native Comparison

cd parsec/example

# Linux
flutter run -d linux

# Android (with device)  
flutter run -d android

# Verify identical results across platforms

6. Performance Validation

• Web: Should evaluate in ~1-10ms
• Native: Should evaluate in ~5-20ms
• Results: Must be identical across all platforms

7. Error Handling Verification

Test these error cases across all platforms:

• Invalid syntax: "2 + + 3" → Should throw ParsecEvalException
• Division by zero: "1/0" → Should handle gracefully
• Unknown function: "unknownfunc(1)" → Should provide clear error

🔍 Expected Behavior Validation

Cross-Platform Consistency Test

final parsec = Parsec();

// These should return identical results on ALL platforms
await parsec.eval('2 + 3');           // → 5
await parsec.eval('sin(pi/2)');       // → 1.0  
await parsec.eval('5!');              // → 120
await parsec.eval('"Hello" == "Hello"'); // → true

Web-Specific Features

// WebAssembly should handle these efficiently
await parsec.eval('log10(10) + ln(e)');     // → 2.0
await parsec.eval('max(1,2,3) + min(4,5,6)'); // → 7
await parsec.eval('round_decimal(3.14159, 2)'); // → 3.14

⚠️ Troubleshooting Common Issues

If tests fail, check:

1. WASM files missing: Run cd parsec_web && dart bin/generate.dart
2. Browser compatibility: Ensure Chrome/modern browser with WASM support
3. JavaScript errors: Check browser console for detailed error messages
4. Cache issues: Try hard refresh (Ctrl+Shift+R) in browser tests

🎯 Success Criteria

• ✅ All automated tests pass on both Flutter 3.19.0 and 3.24.0
• ✅ Web platform produces identical results to native platforms
• ✅ WebAssembly files generate successfully via dart bin/generate.dart
• ✅ Example app runs correctly on flutter run -d chrome
• ✅ Performance meets benchmarks (~1-10ms evaluation times)
• ✅ No JavaScript console errors during web testing

---

This implementation brings the Parsec Flutter plugin to feature parity across all supported platforms while maintaining the high performance and reliability expected from the native C++ equations-parser library.

[Victorcorcos]

In order to test this Pull Request as a whole, it requires the approval and merge of this one, which finaizes the implementation of parsec-web.

• 🎯 Phase 3: Automated Testing Framework & Modern Development Infrastructure parsec-web#10
  Waiting for @niltonvasques 's merge.

[niltonvasques]

Could you review the pr files? Seems that compiled files are committed here

[Victorcorcos]

@niltonvasques

All things done 👍

[niltonvasques]

Still complex, instead add the details here, move them to the main parsec flutter readme. Because on the end the users will install the main lib, instead the child libs.

[Victorcorcos]

I see, I though each one of them were meant to be working independently although parsec runs with all of them together.

[Victorcorcos]

Done.

[Victorcorcos]

@niltonvasques done

[niltonvasques]

Congrats man! 🚀

[Victorcorcos]

Thank tou, @niltonvasques !

@rodiguif , now the PR is merged!
Let’s go ahead with the next steps to publish in pub.dev ?