packwise-skills 1.0.0 → 1.2.0

package/sub-skills/web/wasm.md

@@ -1,243 +1,243 @@
-# WebAssembly Build Sub-Skill
-
-Compile Rust, Go, C/C++, or AssemblyScript to WebAssembly (.wasm) for browser and edge runtime use.
-
-**Current version**: WASM 2.0 / wasm-pack 0.13 / Emscripten 3.1 (2025-2026)
-
-## When to Use
-
-- Performance-critical code in the browser (image processing, crypto, physics, codecs)
-- Reuse existing Rust/Go/C libraries in web frontends
-- Edge computing (Cloudflare Workers, Fastly Compute)
-- Plugin systems (WASM sandboxed execution)
-- Game engines in the browser
-
-## Rust → WASM (Recommended Path)
-
-### Prerequisites
-
-```bash
-# Rust toolchain with WASM target
-rustup target add wasm32-unknown-unknown
-
-# wasm-pack (build tool + npm package generator)
-cargo install wasm-pack
-
-# wasm-bindgen (JS ↔ Rust interop)
-# (automatically used by wasm-pack)
-```
-
-### Project Setup
-
-```bash
-# Create library crate
-cargo new --lib my-wasm-lib
-cd my-wasm-lib
-```
-
-```toml
-# Cargo.toml
-[lib]
-crate-type = ["cdylib", "rlib"]
-
-[dependencies]
-wasm-bindgen = "0.2"
-serde = { version = "1", features = ["derive"] }
-serde-wasm-bindgen = "0.6"
-js-sys = "0.3"
-web-sys = { version = "0.3", features = ["console"] }
-```
-
-```rust
-// src/lib.rs
-use wasm_bindgen::prelude::*;
-
-#[wasm_bindgen]
-pub fn fibonacci(n: u32) -> u32 {
-    match n {
-        0 => 0,
-        1 => 1,
-        _ => fibonacci(n - 1) + fibonacci(n - 2),
-    }
-}
-
-#[wasm_bindgen]
-pub fn process_image(data: &[u8], width: u32, height: u32) -> Vec<u8> {
-    // Heavy computation that would be slow in JS
-    data.iter().map(|&pixel| 255 - pixel).collect()
-}
-
-// Access browser APIs via web-sys
-#[wasm_bindgen]
-pub fn log_to_console(msg: &str) {
-    web_sys::console::log_1(&msg.into());
-}
-```
-
-### Build
-
-```bash
-# Build for bundler (webpack/vite/rollup)
-wasm-pack build --target web
-# Output: pkg/my_wasm_lib_bg.wasm + pkg/my_wasm_lib.js
-
-# Build for Node.js
-wasm-pack build --target nodejs
-
-# Build for direct browser (no bundler)
-wasm-pack build --target no-modules
-
-# Release optimized
-wasm-pack build --target web --release
-```
-
-### Use in JavaScript
-
-```javascript
-// With bundler (Vite/Webpack)
-import init, { fibonacci, process_image } from './pkg/my_wasm_lib.js';
-
-await init(); // Initialize WASM module
-console.log(fibonacci(40)); // Fast!
-
-// With vanilla HTML (no-modules target)
-// <script src="./pkg/my_wasm_lib.js"></script>
-// my_wasm_lib().then(module => { module.fibonacci(40); });
-```
-
-### Vite Integration
-
-```bash
-# vite-plugin-wasm 3.6+ and vite-plugin-top-level-await 1.6+ both support Vite 2-8
-npm install vite-plugin-wasm vite-plugin-top-level-await
-```
-
-```javascript
-// vite.config.js
-import wasm from 'vite-plugin-wasm';
-import topLevelAwait from 'vite-plugin-top-level-await';
-
-export default {
-  plugins: [wasm(), topLevelAwait()],
-};
-```
-
-## Go → WASM
-
-```bash
-# Go has built-in WASM support (GOOS=js GOARCH=wasm)
-GOOS=js GOARCH=wasm go build -o main.wasm .
-
-# Copy the WASM exec helper
-cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .
-
-# The wasm_exec.js file is required to load the WASM module in browsers
-```
-
-```go
-// main.go
-package main
-
-import (
-    "fmt"
-    "syscall/js"
-)
-
-func fibonacci(this js.Value, args []js.Value) interface{} {
-    n := args[0].Int()
-    if n <= 1 { return n }
-    a, b := 0, 1
-    for i := 2; i <= n; i++ { a, b = b, a+b }
-    return b
-}
-
-func main() {
-    c := make(chan struct{})
-    js.Global().Set("fibonacci", js.FuncOf(fibonacci))
-    fmt.Println("Go WASM initialized")
-    <-c // Keep running
-}
-```
-
-```html
-<!-- Load in browser -->
-<script src="wasm_exec.js"></script>
-<script>
-const go = new Go();
-WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject)
-  .then(result => {
-    go.run(result.instance);
-    console.log(fibonacci(40));
-  });
-</script>
-```
-
-## C/C++ → WASM (Emscripten)
-
-```bash
-# Install Emscripten
-git clone https://github.com/emscripten-core/emsdk.git
-cd emsdk && ./emsdk install latest && ./emsdk activate latest
-source ./emsdk_env.sh
-
-# Compile C to WASM
-emcc myfile.c -o myfile.js -s WASM=1 -s EXPORTED_FUNCTIONS='["_process_data"]' -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap"]'
-
-# Compile with optimization
-emcc myfile.c -o myfile.js -O3 -s WASM=1 --closure 1
-```
-
-## AssemblyScript → WASM
-
-```bash
-# AssemblyScript: TypeScript-like syntax compiled to WASM
-npm install -g assemblyscript
-npx asc myModule.ts --outFile myModule.wasm --optimize
-```
-
-```typescript
-// myModule.ts (AssemblyScript — NOT regular TypeScript)
-export function fibonacci(n: i32): i32 {
-  if (n <= 1) return n;
-  let a = 0, b = 1;
-  for (let i = 2; i <= n; i++) {
-    const temp = b;
-    b = a + b;
-    a = temp;
-  }
-  return b;
-}
-```
-
-## Size Optimization
-
-| Technique | Tool | Typical Savings |
-|-----------|------|----------------|
-| `wasm-opt` | `wasm-pack` runs automatically | 10–30% |
-| `--release` flag | All toolchains | 40–60% vs debug |
-| `wee_alloc` | Rust: `#[global_allocator]` | 10–20KB |
-| Feature gates | Cargo: `default-features = false` | Varies |
-| `twiggy` profiler | `cargo install twiggy` | Identify bloat |
-| Brotli compression | Server-side | 70–80% transfer size |
-
-```rust
-// Use wee_alloc to reduce WASM binary size
-extern crate wee_alloc;
-#[global_allocator]
-static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
-```
-
-## Common Pitfalls
-
-| Issue | Fix |
-|-------|-----|
-| WASM binary too large | Use `--release`; enable `wee_alloc`; check features with `twiggy` |
-| `wasm-pack build` fails | Ensure `wasm-bindgen` version matches `wasm-pack` version |
-| Vite doesn't load WASM | Add `vite-plugin-wasm` and `vite-plugin-top-level-await` |
-| Go WASM not loading | Must include `wasm_exec.js` from Go installation |
-| CORS error when loading .wasm | Serve from same origin; add MIME type `application/wasm` |
-| Can't use `console.log` from Rust | Use `web_sys::console::log_1` via `web-sys` crate |
-| Memory grows unbounded | Use `#[wasm_bindgen]` memory management; call `drop()` explicitly |
-| Debugging is hard | Use `console_error_panic_hook` crate for Rust; `console.log` for Go |
-| Thread support | WASM threads require `SharedArrayBuffer` + COOP/COEP headers |
-| SIMD support | Use `wasm32-unknown-unknown` target with nightly or stable 1.72+ |
+# WebAssembly Build Sub-Skill
+
+Compile Rust, Go, C/C++, or AssemblyScript to WebAssembly (.wasm) for browser and edge runtime use.
+
+**Current version**: WASM 2.0 / wasm-pack 0.13 / Emscripten 3.1 (2025-2026)
+
+## When to Use
+
+- Performance-critical code in the browser (image processing, crypto, physics, codecs)
+- Reuse existing Rust/Go/C libraries in web frontends
+- Edge computing (Cloudflare Workers, Fastly Compute)
+- Plugin systems (WASM sandboxed execution)
+- Game engines in the browser
+
+## Rust → WASM (Recommended Path)
+
+### Prerequisites
+
+```bash
+# Rust toolchain with WASM target
+rustup target add wasm32-unknown-unknown
+
+# wasm-pack (build tool + npm package generator)
+cargo install wasm-pack
+
+# wasm-bindgen (JS ↔ Rust interop)
+# (automatically used by wasm-pack)
+```
+
+### Project Setup
+
+```bash
+# Create library crate
+cargo new --lib my-wasm-lib
+cd my-wasm-lib
+```
+
+```toml
+# Cargo.toml
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+wasm-bindgen = "0.2"
+serde = { version = "1", features = ["derive"] }
+serde-wasm-bindgen = "0.6"
+js-sys = "0.3"
+web-sys = { version = "0.3", features = ["console"] }
+```
+
+```rust
+// src/lib.rs
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn fibonacci(n: u32) -> u32 {
+    match n {
+        0 => 0,
+        1 => 1,
+        _ => fibonacci(n - 1) + fibonacci(n - 2),
+    }
+}
+
+#[wasm_bindgen]
+pub fn process_image(data: &[u8], width: u32, height: u32) -> Vec<u8> {
+    // Heavy computation that would be slow in JS
+    data.iter().map(|&pixel| 255 - pixel).collect()
+}
+
+// Access browser APIs via web-sys
+#[wasm_bindgen]
+pub fn log_to_console(msg: &str) {
+    web_sys::console::log_1(&msg.into());
+}
+```
+
+### Build
+
+```bash
+# Build for bundler (webpack/vite/rollup)
+wasm-pack build --target web
+# Output: pkg/my_wasm_lib_bg.wasm + pkg/my_wasm_lib.js
+
+# Build for Node.js
+wasm-pack build --target nodejs
+
+# Build for direct browser (no bundler)
+wasm-pack build --target no-modules
+
+# Release optimized
+wasm-pack build --target web --release
+```
+
+### Use in JavaScript
+
+```javascript
+// With bundler (Vite/Webpack)
+import init, { fibonacci, process_image } from './pkg/my_wasm_lib.js';
+
+await init(); // Initialize WASM module
+console.log(fibonacci(40)); // Fast!
+
+// With vanilla HTML (no-modules target)
+// <script src="./pkg/my_wasm_lib.js"></script>
+// my_wasm_lib().then(module => { module.fibonacci(40); });
+```
+
+### Vite Integration
+
+```bash
+# vite-plugin-wasm 3.6+ and vite-plugin-top-level-await 1.6+ both support Vite 2-8
+npm install vite-plugin-wasm vite-plugin-top-level-await
+```
+
+```javascript
+// vite.config.js
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+
+export default {
+  plugins: [wasm(), topLevelAwait()],
+};
+```
+
+## Go → WASM
+
+```bash
+# Go has built-in WASM support (GOOS=js GOARCH=wasm)
+GOOS=js GOARCH=wasm go build -o main.wasm .
+
+# Copy the WASM exec helper
+cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .
+
+# The wasm_exec.js file is required to load the WASM module in browsers
+```
+
+```go
+// main.go
+package main
+
+import (
+    "fmt"
+    "syscall/js"
+)
+
+func fibonacci(this js.Value, args []js.Value) interface{} {
+    n := args[0].Int()
+    if n <= 1 { return n }
+    a, b := 0, 1
+    for i := 2; i <= n; i++ { a, b = b, a+b }
+    return b
+}
+
+func main() {
+    c := make(chan struct{})
+    js.Global().Set("fibonacci", js.FuncOf(fibonacci))
+    fmt.Println("Go WASM initialized")
+    <-c // Keep running
+}
+```
+
+```html
+<!-- Load in browser -->
+<script src="wasm_exec.js"></script>
+<script>
+const go = new Go();
+WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject)
+  .then(result => {
+    go.run(result.instance);
+    console.log(fibonacci(40));
+  });
+</script>
+```
+
+## C/C++ → WASM (Emscripten)
+
+```bash
+# Install Emscripten
+git clone https://github.com/emscripten-core/emsdk.git
+cd emsdk && ./emsdk install latest && ./emsdk activate latest
+source ./emsdk_env.sh
+
+# Compile C to WASM
+emcc myfile.c -o myfile.js -s WASM=1 -s EXPORTED_FUNCTIONS='["_process_data"]' -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap"]'
+
+# Compile with optimization
+emcc myfile.c -o myfile.js -O3 -s WASM=1 --closure 1
+```
+
+## AssemblyScript → WASM
+
+```bash
+# AssemblyScript: TypeScript-like syntax compiled to WASM
+npm install -g assemblyscript
+npx asc myModule.ts --outFile myModule.wasm --optimize
+```
+
+```typescript
+// myModule.ts (AssemblyScript — NOT regular TypeScript)
+export function fibonacci(n: i32): i32 {
+  if (n <= 1) return n;
+  let a = 0, b = 1;
+  for (let i = 2; i <= n; i++) {
+    const temp = b;
+    b = a + b;
+    a = temp;
+  }
+  return b;
+}
+```
+
+## Size Optimization
+
+| Technique | Tool | Typical Savings |
+|-----------|------|----------------|
+| `wasm-opt` | `wasm-pack` runs automatically | 10–30% |
+| `--release` flag | All toolchains | 40–60% vs debug |
+| `wee_alloc` | Rust: `#[global_allocator]` | 10–20KB |
+| Feature gates | Cargo: `default-features = false` | Varies |
+| `twiggy` profiler | `cargo install twiggy` | Identify bloat |
+| Brotli compression | Server-side | 70–80% transfer size |
+
+```rust
+// Use wee_alloc to reduce WASM binary size
+extern crate wee_alloc;
+#[global_allocator]
+static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
+```
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| WASM binary too large | Use `--release`; enable `wee_alloc`; check features with `twiggy` |
+| `wasm-pack build` fails | Ensure `wasm-bindgen` version matches `wasm-pack` version |
+| Vite doesn't load WASM | Add `vite-plugin-wasm` and `vite-plugin-top-level-await` |
+| Go WASM not loading | Must include `wasm_exec.js` from Go installation |
+| CORS error when loading .wasm | Serve from same origin; add MIME type `application/wasm` |
+| Can't use `console.log` from Rust | Use `web_sys::console::log_1` via `web-sys` crate |
+| Memory grows unbounded | Use `#[wasm_bindgen]` memory management; call `drop()` explicitly |
+| Debugging is hard | Use `console_error_panic_hook` crate for Rust; `console.log` for Go |
+| Thread support | WASM threads require `SharedArrayBuffer` + COOP/COEP headers |
+| SIMD support | Use `wasm32-unknown-unknown` target with nightly or stable 1.72+ |