feat(sdk): request settings in wasm sdk

packages/wasm-sdk/CACHING.md

@@ -0,0 +1,146 @@
+# WASM SDK Caching
+
+The WASM SDK implements multiple caching strategies to improve performance and reduce network requests.
+
+## How Cache Invalidation Works
+
+The cache system uses two mechanisms to ensure users get updates:
+
+### 1. ETag Support (with server.py)
+
+When using `python3 server.py`:
+- Server generates **ETags** based on file content
+- Browser validates cache using ETags
+- Returns `304 Not Modified` if unchanged
+- Automatic cache invalidation when files change
+
+### 2. Cache-First with Background Updates
+
+The service worker:
+- **Serves from cache immediately** (fast!)
+- **Updates cache in background**
+- Next reload gets the updated version
+- No manual cache busting needed
+
+### How It Works
+
+1. **First visit**: Downloads and caches WASM files
+2. **Subsequent visits**: Loads from cache instantly
+3. **Background**: Checks for updates
+4. **File changes**: New ETag → Cache updated
+5. **Next visit**: New version served
+
+## Service Worker Caching
+
+The SDK uses a Service Worker to cache the WASM binary and JavaScript files. This provides:
+
+- **Offline capability**: Once cached, the SDK can work offline
+- **Faster loading**: Subsequent visits load from cache instantly
+- **Automatic updates**: The service worker checks for updates hourly
+
+### Files Cached
+
+- `/pkg/wasm_sdk.js` - JavaScript bindings
+- `/pkg/wasm_sdk_bg.wasm` - WASM binary (several MB)
+- `/pkg/wasm_sdk.d.ts` - TypeScript definitions
+- `/index.html` - Main page
+
+## Using the Cache
+
+### Automatic Caching
+
+The service worker automatically caches files on first load. Subsequent loads will use the cached version.
+
+### Manual Cache Control
+
+The UI provides a "Clear Cache" button that:
+1. Clears the service worker cache
+2. Clears all browser caches
+3. Reloads the page with fresh resources
+
+### Using the Python Server with Cache Headers
+
+For better cache control, use the provided Python server:
+
+```bash
+# Instead of:
+python3 -m http.server 8888
+
+# Use:
+python3 server.py
+```
+
+This server adds proper cache headers:
+- WASM files: Cached for 1 week
+- JS files in /pkg/: Cached for 1 week  
+- HTML files: Not cached
+- Other files: Cached for 1 hour
+
+## Browser Developer Tips
+
+### Force Refresh
+- **Chrome/Edge**: Ctrl+Shift+R (Cmd+Shift+R on Mac)
+- **Firefox**: Ctrl+F5 (Cmd+Shift+R on Mac)
+- **Safari**: Cmd+Option+R
+
+### Disable Cache in DevTools
+1. Open Developer Tools (F12)
+2. Go to Network tab
+3. Check "Disable cache"
+
+### View Service Worker
+1. Open Developer Tools
+2. Go to Application tab
+3. Click on "Service Workers" in sidebar
+4. You can manually unregister the worker here
+
+## How It Works
+
+### Automatic Cache Updates
+
+1. **Build**: Just run `./build.sh` or `wasm-pack build`
+2. **Deploy**: Upload the new files
+3. **Automatic Detection**: Service worker detects the new WASM file hash
+4. **User Notification**: Users see "New version detected!" 
+5. **Update**: Users refresh to get the new version
+
+### Example Flow
+
+```bash
+# Make changes to Rust code
+vim src/lib.rs
+
+# Build (cache updates automatically!)
+./build.sh
+
+# That's it! No version increment needed
+```
+
+### Cache Names
+
+The cache is named based on content hash:
+- `wasm-sdk-cache-a1b2c3d4` (old version)
+- `wasm-sdk-cache-e5f6g7h8` (new version after rebuild)
+
+The service worker:
+- Detects the hash changed
+- Creates new cache with new name
+- Deletes old cache
+- Notifies users
+
+## Troubleshooting
+
+### Cache not working?
+- Check if service worker registered (see console)
+- Ensure HTTPS or localhost (service workers require secure context)
+- Check browser support for service workers
+
+### Old version still loading?
+1. Click "Clear Cache" button
+2. Or manually unregister service worker in DevTools
+3. Force refresh the page
+
+### Service worker errors?
+- Check console for registration errors
+- Ensure `/service-worker.js` is accessible
+- Try incognito/private mode to bypass cache