# SyncKit WASM Core
> **Note:** This document is for contributors building the WASM core from source.
> End users should use the TypeScript SDK (`@synckit-js/sdk`) instead.
> See [Getting Started](../docs/guides/getting-started.md) for user documentation.
WebAssembly core for SyncKit's sync engine, providing high-performance CRDT implementations and conflict resolution algorithms.
## 🎯 What's Included
The WASM core implements SyncKit's performance-critical components:
- **Fugue Text CRDT** - Collaborative text editing with maximal non-interleaving
- **Peritext Rich Text CRDT** - Text formatting that handles conflicts correctly
- **PN-Counter** - Distributed increment/decrement operations
- **OR-Set** - Conflict-free add/remove operations
- **Vector Clocks** - Causal consistency tracking
- **LWW Resolution** - Last-Write-Wins conflict resolution
- **Protocol Buffers** - Efficient network serialization
## 📦 Build Prerequisites
- Rust 1.83+ with `wasm32-unknown-unknown` target
- `wasm-bindgen-cli` version 0.2.105
- `wasm-opt` from Binaryen toolkit (for optimization)
```bash
# Install wasm32 target
rustup target add wasm32-unknown-unknown
# Install wasm-bindgen-cli
cargo install wasm-bindgen-cli --version 0.2.105
# Install wasm-opt (optional but recommended)
# macOS: brew install binaryen
# Ubuntu: apt install binaryen
# Windows: Download from https://github.com/WebAssembly/binaryen/releases
```
## 🔨 Building
### Quick Build (Recommended)
Use the root-level build script:
```bash
# Build default variant (full features)
./scripts/build-wasm.sh default
# Build lite variant (minimal features)
./scripts/build-wasm.sh lite
```
The script handles compilation, wasm-bindgen, and wasm-opt optimization automatically.
### Manual Build
If you need fine-grained control:
```bash
# Step 1: Build Rust to WASM
cd core
cargo build \
--target wasm32-unknown-unknown \
--profile wasm-release \
--features wasm,full \
--no-default-features
# Step 2: Generate JavaScript bindings
wasm-bindgen \
target/wasm32-unknown-unknown/wasm-release/synckit_core.wasm \
--out-dir ../pkg-default \
--target web
# Step 3: Optimize with wasm-opt
wasm-opt -Oz \
--strip-debug \
--strip-producers \
../pkg-default/synckit_core_bg.wasm \
-o ../pkg-default/synckit_core_bg.wasm
```
## 📊 Bundle Sizes (v0.2.0)
Production sizes with all optimizations applied:
### Default Variant (Full Features)
```
Raw WASM: 330.6 KB
Gzipped: 141.1 KB
```
**Includes:** Fugue Text CRDT, Peritext Rich Text, PN-Counter, OR-Set, Vector Clocks, Protocol Buffers, Network sync
### Lite Variant (Minimal)
```
Raw WASM: 79.2 KB
Gzipped: 43.8 KB
```
**Includes:** LWW resolution, Vector Clocks, Local sync only (no network, no CRDTs)
### Complete SDK Sizes
These WASM binaries are part of the full SDK package:
- **Default SDK**: 154 KB gzipped (141 KB WASM + 13 KB JS)
- **Lite SDK**: 46 KB gzipped (44 KB WASM + 2 KB JS)
See [BUNDLE_SIZE.md](../analysis/BUNDLE_SIZE.md) for detailed breakdown.
## 🧪 Testing
### Browser Test
```bash
# Build first
./scripts/build-wasm.sh default
# The build output includes test files
cd pkg-default
node server.js
# Open http://localhost:8000/test.html
```
### Node.js Test
```bash
# Build with Node.js target
cd core
cargo build --target wasm32-unknown-unknown --release --features wasm,full
wasm-bindgen \
target/wasm32-unknown-unknown/release/synckit_core.wasm \
--out-dir ../pkg-nodejs \
--target nodejs
# Run test
cd ..
node tests/wasm_test.mjs
```
## 📚 Low-Level API Usage
> **Note:** Most developers should use the high-level TypeScript SDK instead of calling WASM directly.
### Document Operations
```javascript
import init, { WasmDocument } from './synckit_core.js';
// Initialize WASM module
await init();
// Create a document
const doc = new WasmDocument('doc-1');
// Set fields (values must be JSON strings)
doc.setField('name', JSON.stringify('Alice'), 1n, 'client-1');
doc.setField('age', JSON.stringify(30), 2n, 'client-1');
// Get a field
const name = doc.getField('name');
console.log(JSON.parse(name)); // "Alice"
// Merge documents
doc.merge(otherDoc);
// Export to JSON
const json = doc.toJSON();
```
### Vector Clock
```javascript
import { WasmVectorClock } from './synckit_core.js';
const vc = new WasmVectorClock();
vc.tick('client-1'); // Increment
const clock = vc.get('client-1'); // Get value
// Merge vector clocks
vc.merge(otherVectorClock);
```
### Delta Computation
```javascript
import { WasmDelta } from './synckit_core.js';
// Compute changes between two documents
const delta = WasmDelta.compute(doc1, doc2);
console.log(`Changes: ${delta.changeCount()}`);
// Apply delta to a document
delta.applyTo(doc1, 'client-1');
```
## 🔧 Cargo Features
Control what gets included in the WASM binary:
- `wasm` - Enable WASM bindings (required)
- `full` - Include all CRDTs and network protocol
- `core-lite` - Minimal build (LWW + Vector Clock only)
- `text-crdt` - Include Fugue Text CRDT
- `rich-text` - Include Peritext Rich Text CRDT
- `counters` - Include PN-Counter
- `sets` - Include OR-Set
### Build Variants
```bash
# Default: All features
cargo build --features wasm,full
# Lite: Minimal features
cargo build --features wasm,core-lite
# Custom: Only what you need
cargo build --features wasm,text-crdt,counters
```
## 🎛️ Build Profiles
The `Cargo.toml` includes optimized profiles:
### `wasm-release` (Recommended)
```toml
[profile.wasm-release]
inherits = "release"
opt-level = "z" # Optimize for size
lto = "fat" # Aggressive link-time optimization
codegen-units = 1 # Better optimization (slower build)
panic = "abort" # Smaller binary
strip = "symbols" # Remove debug symbols
```
### `release` (Standard)
```toml
[profile.release]
opt-level = 3 # Optimize for speed
lto = "thin"
```
## 🔍 Optimization Pipeline
Our build uses a 3-stage optimization pipeline:
1. **Rust compiler** - `opt-level = "z"` for size optimization
2. **Link-time optimization (LTO)** - `lto = "fat"` for cross-crate optimization
3. **wasm-opt** - `-Oz` for aggressive post-processing
This achieves **~57% size reduction** from unoptimized builds.
## 🐛 Troubleshooting
### "Module not found" errors
Ensure you've built the WASM module and are importing from the correct path:
```javascript
// ✅ Correct: Import from build output
import init from './pkg-default/synckit_core.js'
// ❌ Wrong: Import from source
import init from './core/src/wasm/mod.rs'
```
### Version mismatch errors
The `wasm-bindgen-cli` version must match the `wasm-bindgen` crate version in `Cargo.toml` (currently 0.2.105):
```bash
cargo install wasm-bindgen-cli --version 0.2.105 --force
```
### CORS errors in browser
WASM files must be served via HTTP(S), not `file://`:
```bash
# Use the provided server
cd pkg-default
node server.js
# Or use any HTTP server
npx http-server pkg-default
python -m http.server 8000
```
### Build is slow
WASM builds are slower than regular Rust builds due to optimization:
- **Development:** Use `--release` profile (~30s build)
- **Production:** Use `--profile wasm-release` (~2-3 min build)
Optimization time is worth it - you get 57% smaller binaries.
## 📝 Technical Notes
- Clock values use `BigInt` in JavaScript (use `1n` syntax)
- Field values must be serialized as JSON strings
- Memory management is automatic via wasm-bindgen
- Use `init_panic_hook()` for better error messages in development
- WASM binaries are deterministic (same input = same output)
## 🔗 See Also
- [Bundle Size Analysis](../analysis/BUNDLE_SIZE.md) - Detailed size breakdown
- [SDK Documentation](../docs/guides/getting-started.md) - High-level TypeScript API
- [Architecture](../docs/architecture/ARCHITECTURE.md) - How WASM fits into SyncKit
- [Contributing Guide](../CONTRIBUTING.md) - How to contribute to the core