wifi-densepose/vendor/ruvector/crates/sona/BUILD_INSTRUCTIONS.md

SONA WASM Build Instructions

Prerequisites

1. Install Rust and wasm32 target:

rustup target add wasm32-unknown-unknown

2. Install wasm-pack (recommended):

cargo install wasm-pack

Building for WASM

Option 1: Using wasm-pack (Recommended)

cd crates/sona

# For web (browser)
wasm-pack build --target web --features wasm --out-dir wasm-example/pkg

# For Node.js
wasm-pack build --target nodejs --features wasm

# For bundlers (webpack, rollup, etc.)
wasm-pack build --target bundler --features wasm

# Release build (optimized)
wasm-pack build --target web --features wasm --release --out-dir wasm-example/pkg

Option 2: Using cargo directly

cd crates/sona
cargo build --target wasm32-unknown-unknown --features wasm --release

The WASM file will be at: ../../target/wasm32-unknown-unknown/release/sona.wasm

Running the Example

1. Build the WASM module:

cd crates/sona
wasm-pack build --target web --features wasm --out-dir wasm-example/pkg

2. Serve the example:

cd wasm-example
python3 -m http.server 8080
# Or use any static server

3. Open browser:

http://localhost:8080

File Structure

After building, you'll have:

crates/sona/
├── src/
│   ├── lib.rs           # Main library
│   ├── wasm.rs          # WASM bindings
│   ├── engine.rs        # SONA engine
│   ├── lora.rs          # LoRA implementations
│   ├── trajectory.rs    # Trajectory tracking
│   ├── ewc.rs           # EWC++ implementation
│   ├── reasoning_bank.rs # Pattern storage
│   ├── types.rs         # Core types
│   └── loops/           # Learning loops
├── wasm-example/
│   ├── index.html       # Demo page
│   ├── index.js         # Demo logic
│   ├── package.json     # NPM config
│   └── pkg/             # Generated WASM package
│       ├── sona.js      # JS bindings
│       ├── sona_bg.wasm # WASM binary
│       ├── sona.d.ts    # TypeScript definitions
│       └── package.json # NPM package info
└── Cargo.toml           # Rust config

Optimizing Build Size

1. Use release profile

wasm-pack build --target web --features wasm --release

2. Enable wasm-opt (automatically done by wasm-pack)

The wasm-release profile in Cargo.toml is optimized for size:

[profile.wasm-release]
inherits = "release"
opt-level = "z"      # Optimize for size
lto = true           # Link-time optimization
codegen-units = 1    # Better optimization
panic = "abort"      # Smaller panic handler

3. Use wasm-snip to remove panicking infrastructure

cargo install wasm-snip
wasm-snip target/wasm32-unknown-unknown/release/sona.wasm \
  -o sona_snipped.wasm

Troubleshooting

Build Errors

Error: getrandom not found

• Solution: Make sure the wasm feature is enabled, which includes getrandom with js feature.

Error: Missing wasm-bindgen

• Solution: Add wasm-bindgen to dependencies with the wasm feature.

Runtime Errors

Error: Memory allocation failed

• Solution: Increase WASM memory limit in your environment.

Error: Module not found

• Solution: Make sure paths in index.html correctly point to pkg/sona.js.

Performance Tips

1. Use release builds in production for better performance
2. Enable SIMD if targeting modern browsers (requires additional features)
3. Lazy load the WASM module to improve initial page load
4. Use Web Workers for heavy computations to avoid blocking UI

NPM Publishing

To publish the WASM package to NPM:

cd crates/sona
wasm-pack build --target bundler --features wasm --release
wasm-pack publish

Size Comparison

• Debug build: ~9MB
• Release build: ~2-3MB
• Release + wasm-opt: ~1-2MB
• With all optimizations: < 1MB

Browser Compatibility

• Chrome/Edge: 91+ (full support)
• Firefox: 89+ (full support)
• Safari: 14.1+ (full support)
• Node.js: 16+ (with --experimental-wasm-modules)

Next Steps

• See README.md for API documentation
• Check wasm-example/ for usage examples
• Read API Reference for detailed API docs