Seregon/StratoSDK

StratoSDK is a framework with a declarative approach similar to Flutter/React, written and designed entirely for Rust.

Rust/27.3 KB/No license
examples/wasm_demo/README.md
raw
StratoSDK / examples / wasm_demo / README.md
1# OxideUI WASM Demo
2 
3A comprehensive demonstration of OxideUI running in the browser via WebAssembly.
4 
5## Features
6 
7- ✅ Counter application with increment/decrement/reset
8- ✅ Real-time metrics display
9- ✅ Responsive design
10- ✅ Modern UI with glassmorphism effects
11- ✅ Performance monitoring
12- ✅ Browser compatibility detection
13 
14## Building
15 
16### Prerequisites
17 
18```bash
19# Install wasm-pack
20cargo install wasm-pack
21 
22# Install a local web server
23cargo install basic-http-server
24```
25 
26### Build for Web
27 
28```bash
29# Development build
30wasm-pack build --target web --dev
31 
32# Production build (optimized)
33wasm-pack build --target web --release
34 
35# Production build with maximum optimization
36RUSTFLAGS='-C link-arg=-s' wasm-pack build --target web --release
37```
38 
39### Serve Locally
40 
41```bash
42# Using basic-http-server
43basic-http-server .
44 
45# OR using Python
46python -m http.server 8000
47 
48# OR using Node.js http-server
49npx http-server .
50```
51 
52Then open http://localhost:8000 in your browser.
53 
54## Testing
55 
56```bash
57# Run WASM tests in headless browser
58wasm-pack test --headless --firefox
59wasm-pack test --headless --chrome
60 
61# Run tests in real browser
62wasm-pack test --firefox
63```
64 
65## Bundle Size
66 
67Current bundle sizes (after optimization):
68 
69- **WASM binary**: ~150KB (uncompressed)
70- **WASM binary**: ~45KB (gzip compressed)
71- **WASM binary**: ~35KB (brotli compressed)
72- **JavaScript glue**: ~15KB
73 
74Total: **~50KB** (compressed)
75 
76## Performance
77 
78- **Startup time**: <100ms
79- **Frame rate**: 60 FPS
80- **Memory usage**: ~5MB
81 
82## Browser Compatibility
83 
84- ✅ Chrome 57+
85- ✅ Firefox 52+
86- ✅ Safari 11+
87- ✅ Edge 16+
88 
89## Deployment
90 
91### Static Hosting
92 
93This demo can be deployed to any static hosting service:
94 
95- **Netlify**: Drop the folder or connect to Git
96- **Vercel**: `vercel deploy`
97- **GitHub Pages**: Push to `gh-pages` branch
98- **Cloudflare Pages**: Connect to repository
99 
100### Example: Deploy to Netlify
101 
102```bash
103# Install Netlify CLI
104npm install -g netlify-cli
105 
106# Build
107wasm-pack build --target web --release
108 
109# Deploy
110netlify deploy --prod
111```
112 
113## Architecture
114 
115```
116┌─────────────────────────────────────┐
117│ Browser (HTML/JS) │
118├─────────────────────────────────────┤
119│ wasm-bindgen (JS Glue) │
120├─────────────────────────────────────┤
121│ WASM Module (Rust) │
122│ ┌───────────────────────────────┐ │
123│ │ WasmApp (Main Logic) │ │
124│ ├───────────────────────────────┤ │
125│ │ oxide-widgets (UI Layer) │ │
126│ ├───────────────────────────────┤ │
127│ │ oxide-core (State/Events) │ │
128│ ├───────────────────────────────┤ │
129│ │ oxide-renderer (WebGL/2D) │ │
130│ └───────────────────────────────┘ │
131└─────────────────────────────────────┘
132```
133 
134## Code Structure
135 
136```
137wasm_demo/
138├── Cargo.toml # Dependencies and build config
139├── src/
140│ └── lib.rs # WASM application code
141├── index.html # HTML entry point
142├── README.md # This file
143└── pkg/ # Generated WASM output (after build)
144 ├── oxide_wasm_demo.js
145 ├── oxide_wasm_demo_bg.wasm
146 └── ...
147```
148 
149## Optimization Tips
150 
151### 1. Minimize Bundle Size
152 
153```toml
154[profile.release]
155opt-level = "z" # Optimize for size
156lto = true # Link-time optimization
157codegen-units = 1 # Better optimization
158```
159 
160### 2. Use Feature Flags
161 
162```toml
163[dependencies]
164oxide-core = { version = "0.1.0", default-features = false, features = ["wasm"] }
165```
166 
167### 3. Lazy Loading
168 
169Load heavy features only when needed:
170 
171```rust
172#[wasm_bindgen]
173pub async fn load_heavy_feature() -> Result<(), JsValue> {
174 // Load on demand
175 Ok(())
176}
177```
178 
179### 4. Code Splitting
180 
181Split large modules into separate WASM files.
182 
183## Troubleshooting
184 
185### Issue: "RuntimeError: memory access out of bounds"
186 
187**Solution**: Increase WASM memory or optimize memory usage.
188 
189### Issue: Large bundle size
190 
191**Solution**:
192- Enable LTO and size optimization
193- Remove unused dependencies
194- Use `cargo-bloat` to identify large dependencies
195 
196### Issue: Slow performance
197 
198**Solution**:
199- Profile with browser DevTools
200- Minimize JS ↔ WASM calls
201- Use Web Workers for heavy computation
202 
203### Issue: CORS errors
204 
205**Solution**: Serve files with a proper web server, not `file://`
206 
207## Next Steps
208 
2091. Explore the code in `src/lib.rs`
2102. Modify the UI and rebuild
2113. Add new features
2124. Deploy to production
2135. Monitor performance
214 
215## Resources
216 
217- [OxideUI Documentation](../../README.md)
218- [WASM Guide](../../WASM_GUIDE.md)
219- [wasm-bindgen Book](https://rustwasm.github.io/wasm-bindgen/)
220- [Rust and WebAssembly Book](https://rustwasm.github.io/book/)
221 
222## License
223 
224Same as OxideUI (MIT OR Apache-2.0)
225