Doc: Update README.md

README.md

@@ -13,6 +13,24 @@ A modular, async, and cross-platform cryptographic stack in Rust. Built for both
 - **browser_extension/** _(planned)_: Browser extension for secure scripting and automation
 - **rhai scripting** _(planned)_: Unified scripting API for both CLI and browser (see [`docs/rhai_architecture_plan.md`](docs/rhai_architecture_plan.md))
 
+---
+
+## What is Rust Conditional Compilation?
+
+Rust's conditional compilation allows you to write code that only gets included for certain platforms or configurations. This is done using attributes like `#[cfg(target_arch = "wasm32")]` for WebAssembly, or `#[cfg(not(target_arch = "wasm32"))]` for native platforms. It enables a single codebase to support multiple targets (such as desktop and browser) with platform-specific logic where needed.
+
+**Example:**
+```rust
+#[cfg(target_arch = "wasm32")]
+// This code only compiles for WebAssembly targets
+```
+
+## What is WASM (WebAssembly)?
+
+WebAssembly (WASM) is a binary instruction format for a stack-based virtual machine. It allows code written in languages like Rust, C, or C++ to run at near-native speed in web browsers and other environments. In this project, WASM enables the cryptographic vault to work securely inside the browser, exposing Rust functions to JavaScript and web applications.
+
+---
+
 ## Directory Structure
 > **Note:** Some directories are planned for future extensibility and scripting, and may not exist yet in the current workspace.
 
@@ -36,6 +54,42 @@ A modular, async, and cross-platform cryptographic stack in Rust. Built for both
 - **Extensible:** Trait-based APIs for signers and providers, ready for scripting and new integrations
 - **Tested everywhere:** Native and browser (WASM) backends are covered by automated tests and a unified Makefile
 
+---
+
+## Conditional Compilation & WASM Support
+
+This project makes extensive use of Rust's conditional compilation to support both native and WebAssembly (WASM) environments with a single codebase. Key points:
+
+- **Platform-specific code:**
+  - Rust's `#[cfg(target_arch = "wasm32")]` attribute is used to write WASM-specific code, while `#[cfg(not(target_arch = "wasm32"))]` is for native targets.
+  - This pattern is used for struct definitions, method implementations, and even module imports.
+
+- **Example: SessionManager**
+  ```rust
+  #[cfg(not(target_arch = "wasm32"))]
+  pub struct SessionManager<S: KVStore + Send + Sync> { ... }
+
+  #[cfg(target_arch = "wasm32")]
+  pub struct SessionManager<S: KVStore> { ... }
+  ```
+
+- **WASM Bindings:**
+  - The `wasm_app` crate uses `wasm-bindgen` to expose Rust functions to JavaScript, enabling browser integration.
+  - Functions are annotated with `#[wasm_bindgen]` and exported for use in JS/TS.
+
+- **Storage Backends:**
+  - Native uses `sled` or other file-based stores.
+  - WASM uses IndexedDB (via `kvstore::wasm::WasmStore`).
+
+- **Building for WASM:**
+  - Use `wasm-pack build --target web` to build the WASM package.
+  - Serve the resulting files with a static server for browser use.
+
+- **Testing:**
+  - Both native and WASM tests are supported. WASM tests can be run in headless browsers using `wasm-pack test --headless --firefox` or similar commands.
+
+---
+
 ## Building and Testing
 
 ### Prerequisites