gowm 1.0.8 → 1.1.1

package/README.md

@@ -14,16 +14,58 @@
 
 ## ✨ Features
 
-- 🚀 **Unified Interface** - Load Go WASM modules from local files or GitHub repositories
+- 🚀 **Loader System** - Intelligent loader for all source types (files, URLs, GitHub)
 - 🔧 **Cross-Platform** - Full support for Node.js and browser environments
-- ⚛️ **React Integration** - Built-in hooks (`useWasm`, `useWasmFromGitHub`)
-- 🖖 **Vue 3 Support** - Reactive composables with automatic cleanup
+- 🎯 **Auto-Detection** - Automatically detects source type and optimal loading strategy
 - 📦 **GitHub Direct Loading** - Load WASM modules directly from GitHub repositories
 - 🏷️ **Version Control** - Support for branches, tags, and specific commits
-- 🛡️ **Error Handling** - Robust error handling and automatic retries
-- 🧹 **Memory Management** - Automatic resource cleanup and memory management
-- 📊 **Module Statistics** - Built-in monitoring and performance metrics
-- 🔄 **Flexible Calls** - Both synchronous and asynchronous function calls
+- 🛡️ **Enhanced Error Handling** - Robust error handling with fallback strategies
+- 🧹 **Smart Memory Management** - Safe memory allocation and resource cleanup
+- 📊 **Comprehensive Statistics** - Built-in monitoring, testing, and performance metrics
+- 🔄 **Flexible API** - Both synchronous and asynchronous function calls
+- 📝 **TypeScript Support** - Full TypeScript definitions included
+- ⚛️ **React Hooks** - `useWasm()` and `useWasmFromGitHub()` hooks
+- 💚 **Vue Composables** - `useWasm()` and `useWasmFromGitHub()` composables
+- 🔧 **CLI** - `npx gowm list|info|types|verify|install`
+- 📡 **Event System** - `on()` / `off()` / `once()` for module lifecycle events
+- 🏗️ **Type Generator** - Generate TypeScript interfaces from `module.json`
+
+### 🆕 New in v1.1.1
+
+- 📡 **Event System** - `on('module:loaded')`, `on('module:error')`, `on('memory:warning')` with chaining
+- ⚛️ **React Hooks** - `import { useWasm } from 'gowm/react'` with auto-cleanup and reload
+- 💚 **Vue 3 Composables** - `import { useWasm } from 'gowm/vue'` with reactive refs and watch
+- 🔧 **CLI** - `npx gowm list|info|types|verify|install` for module discovery and management
+- 🏗️ **Type Generator** - `generateTypes()` creates TypeScript interfaces from `module.json`
+- 📦 **ESM Exports Map** - Sub-path exports `gowm/react`, `gowm/vue`, `gowm/tools/type-generator`
+- 📋 **TypeScript Definitions** - Dedicated `types/react.d.ts` and `types/vue.d.ts`
+- 🧪 **274 Unit Tests** - Extended coverage for all Phase 4 features
+
+### Previous (v1.4.0)
+
+- 📋 **Module Metadata** - Automatic `module.json` fetching from GitHub repositories
+- 🔒 **SHA256 Integrity** - WASM file integrity verification via `.wasm.integrity` files (SRI format)
+- 🎯 **readySignal Auto-Discovery** - Uses `gowmConfig.readySignal` from metadata instead of generic polling
+- ✅ **Function Call Validation** - Parameter count validation, type warnings in debug mode
+- 📖 **`describe()` Documentation** - Inline documentation for functions (`bridge.describe('add')`)
+- 📊 **`getDetailedFunctions()`** - Rich function listing with parameters, types, examples
+- 🗂️ **`getFunctionCategories()`** - Organized function categories from metadata
+
+### Previous (v1.3.0)
+
+- 💾 **Multi-Level Cache** - Memory (L1) + disk/IndexedDB (L2) caching with configurable TTL
+- 🔁 **Retry with Backoff** - Automatic retry with exponential backoff on network failures
+- ⚡ **Streaming Instantiation** - `WebAssembly.instantiateStreaming()` for HTTP loads (compile during download)
+- 🎯 **Promise-Based Readiness** - Callback-first signals with adaptive polling fallback
+- 📦 **Compressed WASM** - Auto-detect and decompress `.wasm.gz` and `.wasm.br` files
+
+### Previous (v1.2.0)
+
+- 🔒 **Module Namespace Isolation** - Each module gets its own namespace via `globalThis.__gowm_modules_`
+- 🌿 **Auto Branch Detection** - GitHub default branch auto-detected via API
+- 🔍 **Improved Source Detection** - Strict local path and GitHub URL detection
+- 📝 **Configurable Logging** - Log levels with custom logger support
+- 🛡️ **Safe Memory Allocation** - Removed unsafe offset-based fallback
 
 ## 📥 Installation
 
@@ -40,162 +82,146 @@ pnpm add gowm
 ### Node.js Example
 
 ```javascript
-const { load, loadFromGitHub } = require('gowm');
+const { GoWM } = require("gowm");
 
 async function example() {
   try {
-    // Load from GitHub repository (recommended)
-    const math = await loadFromGitHub('benoitpetit/wasm-modules-repository', { 
-      name: 'math',
-      path: 'math-wasm',
-      branch: 'master'
-    });
-    
+    // Create a GoWM instance with configurable logging
+    const gowm = new GoWM({ logLevel: "info" });
+
+    // Load from GitHub repository (branch auto-detected)
+    // v1.4.0: module.json metadata fetched, SHA256 integrity verified
+    const math = await gowm.loadFromGitHub(
+      "benoitpetit/wasm-modules-repository",
+      {
+        name: "math",
+        path: "math-wasm",
+        retries: 3, // retry on network failure
+        cache: { ttl: 3600000 }, // cache for 1 hour
+        // metadata: true,      // auto-fetch module.json (default)
+        // integrity: true,     // verify SHA256 hash (default)
+        // validateCalls: true, // validate parameters (default)
+      },
+    );
+
+    // Call functions (v1.4.0: parameters validated against metadata)
+    const result = math.call("add", 5, 3);
+    console.log("5 + 3 =", result); // 8
+
+    // v1.4.0: Describe a function from module.json metadata
+    const desc = gowm.describeFunction("math", "add");
+    console.log(desc);
+    // { name: 'add', description: '...', parameters: [...], returnType: '...' }
+
+    // v1.4.0: Get detailed function list with metadata
+    const functions = math.getDetailedFunctions();
+    console.log("Functions:", functions.length);
+
+    // v1.4.0: Get function categories
+    const categories = math.getFunctionCategories();
+    console.log("Categories:", Object.keys(categories));
+
+    // v1.4.0: Module metadata
+    const metadata = gowm.getModuleMetadata("math");
+    console.log(`${metadata.name} v${metadata.version}`);
+
+    // Load from HTTP URL (uses streaming instantiation when possible)
+    const remoteWasm = await gowm.loadFromUrl(
+      "https://example.com/module.wasm",
+    );
+
     // Load from local file
-    const localWasm = await load('./math.wasm', { name: 'local-math' });
-    
-    // Call functions
-    const result = math.call('add', 5, 3);
-    console.log('5 + 3 =', result); // 8
-    
+    const localWasm = await gowm.load("./math.wasm", { name: "local-math" });
+
+    // Disable cache for a specific load
+    const freshLoad = await gowm.load("./module.wasm", { cache: false });
+
     // Async calls
-    const asyncResult = await math.callAsync('multiply', 4, 7);
-    console.log('4 * 7 =', asyncResult); // 28
-    
+    const asyncResult = await math.callAsync("multiply", 4, 7);
+    console.log("4 * 7 =", asyncResult); // 28
+
     // Check available functions
-    if (math.hasFunction('divide')) {
-      console.log('divide function is available');
+    if (math.hasFunction("divide")) {
+      console.log("divide function is available");
     }
-    
-    // Get module statistics
+
+    // Get comprehensive statistics
     const stats = math.getStats();
-    console.log('Available functions:', stats.functions);
-    
+    console.log("Available functions:", stats.functions);
+    console.log("Memory usage:", stats.memoryUsage);
+
+    // Clear the cache
+    await gowm.clearCache();
   } catch (error) {
-    console.error('Error:', error);
+    console.error("Error:", error);
   }
 }
 
 example();
 ```
 
-### React Integration
+## 🔄 Loader System
 
-```jsx
-import React, { useState } from 'react';
-import { useWasmFromGitHub } from 'gowm/hooks/useWasm';
+GoWM v1.1.0 features a loader system that handles all source types with a single API:
 
-function Calculator() {
-  const { wasm, loading, error } = useWasmFromGitHub('benoitpetit/wasm-modules-repository', {
-    path: 'math-wasm',
-    branch: 'master',
-    name: 'calculator'
-  });
-  
-  const [result, setResult] = useState(null);
-
-  const calculate = async () => {
-    if (wasm) {
-      try {
-        const sum = await wasm.callAsync('add', 10, 20);
-        setResult(sum);
-      } catch (err) {
-        console.error('Calculation failed:', err);
-      }
-    }
-  };
+### Auto-Detection
 
-  if (loading) return <div>Loading WASM module...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+```javascript
+const { load } = require("gowm");
 
-  return (
-    <div>
-      <button onClick={calculate}>Calculate 10 + 20</button>
-      {result !== null && <p>Result: {result}</p>}
-    </div>
-  );
-}
+// Automatically detects source type
+await load("owner/repo"); // → GitHub repository
+await load("https://example.com/module.wasm"); // → HTTP URL
+await load("./local/module.wasm"); // → Local file
+await load("/absolute/path/module.wasm"); // → Absolute path
 ```
 
-### Vue 3 Integration
-
-```vue
-<template>
-  <div class="calculator">
-    <div v-if="loading">Loading WASM module...</div>
-    <div v-else-if="error" class="error">Error: {{ error.message }}</div>
-    <div v-else>
-      <input v-model.number="num1" type="number" placeholder="First number" />
-      <input v-model.number="num2" type="number" placeholder="Second number" />
-      <button @click="calculate">Calculate {{ num1 }} + {{ num2 }}</button>
-      <div v-if="result !== null" class="result">Result: {{ result }}</div>
-    </div>
-  </div>
-</template>
+### Specific Loading Methods
 
-<script>
-import { ref } from 'vue';
-import { useWasmFromGitHub } from 'gowm/composables/useWasm';
-
-export default {
-  name: 'Calculator',
-  setup() {
-    const { wasm, loading, error } = useWasmFromGitHub('benoitpetit/wasm-modules-repository', {
-      path: 'math-wasm',
-      branch: 'master',
-      name: 'math'
-    });
-    
-    const num1 = ref(10);
-    const num2 = ref(20);
-    const result = ref(null);
-
-    const calculate = async () => {
-      if (wasm.value) {
-        try {
-          result.value = await wasm.value.callAsync('add', num1.value, num2.value);
-        } catch (err) {
-          console.error('Calculation error:', err);
-        }
-      }
-    };
+```javascript
+const { loadFromFile, loadFromUrl, loadFromGitHub } = require("gowm");
 
-    return { wasm, loading, error, num1, num2, result, calculate };
-  }
-};
-</script>
+// Explicit methods for specific sources
+await loadFromFile("./module.wasm"); // Node.js only
+await loadFromUrl("https://example.com/mod.wasm"); // HTTP/HTTPS
+await loadFromGitHub("owner/repo", options); // GitHub repository
 ```
 
 ## 🐙 GitHub Repository Loading
 
-GoWM excels at loading WASM modules directly from GitHub repositories with intelligent file discovery:
+GoWM excels at loading WASM modules directly from GitHub repositories with intelligent file discovery and automatic default branch detection:
 
 ```javascript
-const { loadFromGitHub } = require('gowm');
+const { GoWM } = require("gowm");
+const gowm = new GoWM();
 
 async function examples() {
-  // Basic loading with automatic file discovery
-  const math = await loadFromGitHub('benoitpetit/wasm-modules-repository', {
-    path: 'math-wasm',
-    branch: 'master'
-  });
-    
+  // Basic loading — branch auto-detected via GitHub API
+  const math = await gowm.loadFromGitHub(
+    "benoitpetit/wasm-modules-repository",
+    {
+      path: "math-wasm",
+    },
+  );
+
   // Advanced loading with specific options
-  const crypto = await loadFromGitHub('benoitpetit/wasm-modules-repository', {
-    path: 'crypto-wasm',
-    filename: 'main.wasm',
-    branch: 'master',
-    name: 'crypto-processor'
-  });
-    
+  const crypto = await gowm.loadFromGitHub(
+    "benoitpetit/wasm-modules-repository",
+    {
+      path: "crypto-wasm",
+      filename: "main.wasm",
+      name: "crypto-processor",
+      timeout: 30000, // Custom timeout
+    },
+  );
+
   // Load from full GitHub URL
-  const image = await loadFromGitHub(
-    'https://github.com/benoitpetit/wasm-modules-repository', 
-    { 
-      path: 'image-wasm',
-      filename: 'main.wasm', 
-      branch: 'master' 
-    }
+  const image = await gowm.loadFromGitHub(
+    "https://github.com/benoitpetit/wasm-modules-repository",
+    {
+      path: "image-wasm",
+      filename: "main.wasm",
+    },
   );
 }
 ```
@@ -213,33 +239,62 @@ GoWM automatically searches for WASM files in these locations:
 
 ### Core Functions
 
+#### `load(source, options)`
+
+Universal loading function that auto-detects source type.
+
+**Parameters:**
+
+- `source` (string): Can be file path, HTTP URL, or GitHub repo
+- `options` (object, optional):
+  - `name` (string): Module identifier
+  - `timeout` (number): Initialization timeout (default: 15000ms)
+  - `preInit` (boolean): Pre-initialize module (default: true)
+  - `goRuntimePath` (string): Custom path to wasm_exec.js
+
+**Returns:** Promise<WasmBridge>
+
 #### `loadFromGitHub(githubRepo, options)`
 
 Loads a WASM module from a GitHub repository with automatic file resolution.
 
 **Parameters:**
+
 - `githubRepo` (string): GitHub repository ("owner/repo" or full GitHub URL)
 - `options` (object, optional):
   - `name` (string): Module identifier (default: repository name)
-  - `branch` (string): Git branch (default: 'master')
+  - `branch` (string): Git branch (default: auto-detected via GitHub API)
   - `tag` (string): Git tag (takes precedence over branch)
   - `path` (string): Path within repository (default: '')
   - `filename` (string): Specific filename (default: auto-detect)
+  - `timeout` (number): Initialization timeout (default: 15000ms)
   - `goRuntimePath` (string): Custom path to wasm_exec.js
   - `preInit` (boolean): Pre-initialize the module (default: true)
+  - `metadata` (boolean): Fetch module.json metadata (default: true) _(v1.4.0)_
+  - `integrity` (boolean): Verify SHA256 integrity (default: true) _(v1.4.0)_
+  - `validateCalls` (boolean): Validate function parameters (default: true) _(v1.4.0)_
 
 **Returns:** Promise<WasmBridge>
 
-#### `load(wasmPath, options)`
+#### `loadFromUrl(url, options)`
 
-Loads a WASM module from a local file or URL.
+Loads a WASM module from HTTP/HTTPS URL.
 
 **Parameters:**
-- `wasmPath` (string): Path to the .wasm file or URL
-- `options` (object, optional):
-  - `name` (string): Module identifier (default: 'default')
-  - `goRuntimePath` (string): Custom path to wasm_exec.js
-  - `preInit` (boolean): Pre-initialize the module (default: true)
+
+- `url` (string): HTTP/HTTPS URL to WASM file
+- `options` (object, optional): Same as `load()` options
+
+**Returns:** Promise<WasmBridge>
+
+#### `loadFromFile(filePath, options)`
+
+Loads a WASM module from local file (Node.js only).
+
+**Parameters:**
+
+- `filePath` (string): Path to the .wasm file
+- `options` (object, optional): Same as `load()` options
 
 **Returns:** Promise<WasmBridge>
 
@@ -248,58 +303,97 @@ Loads a WASM module from a local file or URL.
 Retrieves an already loaded module by name.
 
 **Parameters:**
-- `name` (string, optional): Module name (default: 'default')
 
-**Returns:** WasmBridge | null
+- `name` (string, optional): Module name (default: 'default')
 
-### WasmBridge Methods
+**Returns:** UnifiedWasmBridge | null
 
-#### `call(funcName, ...args)`
+### Enhanced Bridge Methods
 
-Calls a WASM function synchronously.
+The bridge provides comprehensive functionality:
 
-**Parameters:**
-- `funcName` (string): Name of the function to call
-- `...args`: Function arguments
+#### `call(funcName, ...args)`
 
-**Returns:** Function result
+Calls a WASM function synchronously. In v1.4.0, validates parameter count and types (debug mode) against module.json metadata.
 
 #### `callAsync(funcName, ...args)`
 
 Calls a WASM function asynchronously.
 
-**Parameters:**
-- `funcName` (string): Name of the function to call
-- `...args`: Function arguments
+#### `describe(funcName)` _(v1.4.0)_
 
-**Returns:** Promise<Function result>
+Returns inline documentation for a function from module.json metadata.
 
-#### `hasFunction(funcName)`
+**Returns:** `{ name, description, category, parameters, returnType, example, errorPattern }` or `null`
 
-Checks if a function exists in the WASM module.
+#### `getDetailedFunctions()` _(v1.4.0)_
 
-**Parameters:**
-- `funcName` (string): Function name to check
+Returns all functions with their full metadata (parameters, types, descriptions).
 
-**Returns:** boolean
+**Returns:** `Array<{ name, description, category, parameters, returnType, example }>`
 
-#### `getAvailableFunctions()`
+#### `getMetadata()` _(v1.4.0)_
 
-Gets a list of all available functions in the module.
+Returns the raw module.json metadata object.
 
-**Returns:** string[]
+#### `getFunctionCategories()` _(v1.4.0)_
 
-#### `getStats()`
+Returns function categories from metadata.
+
+**Returns:** `{ [category: string]: string[] }` or `null`
+
+#### `createBuffer(data)`
+
+Creates a buffer for data transfer with enhanced type support.
 
-Gets module statistics and information.
+**Supported Types:**
 
-**Returns:** Object with module statistics
+- `Float64Array`, `Float32Array`
+- `Uint8Array`, `Uint16Array`, `Uint32Array`
+- `Int8Array`, `Int16Array`, `Int32Array`
+- `Array`, `string`
 
-#### `cleanup()`
+#### `test()`
 
-Manually clean up module resources.
+Runs comprehensive tests on the module.
 
-**Returns:** void
+**Returns:** Object with test results:
+
+```javascript
+{
+  functionCalls: boolean,
+  memoryAllocation: boolean,
+  callbacks: boolean,
+  asyncCalls: boolean,
+  errors: string[]
+}
+```
+
+#### `getStats()`
+
+Gets comprehensive module statistics.
+
+**Returns:** Object with detailed statistics:
+
+```javascript
+{
+  name: string,
+  ready: boolean,
+  environment: 'Node.js' | 'Browser',
+  functions: string[],
+  callbacks: string[],
+  allocatedBuffers: number,
+  memoryUsage: {
+    total: number,
+    wasm: number,
+    go: number,
+    buffers: number,
+    buffersCount: number
+  },
+  supportedDataTypes: string[],
+  loadedAt: string
+}
+```
 
 ### Utility Functions
 
@@ -309,153 +403,287 @@ Manually clean up module resources.
 - `unloadAll()`: Unload all modules
 - `isLoaded(name)`: Check if a module is loaded
 - `getTotalMemoryUsage()`: Get total memory usage
+- `testAll()`: Test all loaded modules
+- `getHelp()`: Get comprehensive help information
+- `getVersion()`: Get GoWM version string
+- `clearCache()`: Clear all cached WASM bytes _(v1.3.0)_
+- `getModuleMetadata(name)`: Get module.json metadata _(v1.4.0)_
+- `describeFunction(moduleName, funcName)`: Describe a function from metadata _(v1.4.0)_
+- `on(event, callback)`: Register event listener _(v1.1.1)_
+- `off(event, callback)`: Remove event listener _(v1.1.1)_
+- `once(event, callback)`: One-time event listener _(v1.1.1)_
+- `generateTypes(metadata, options)`: Generate TypeScript types _(v1.1.1)_
+- `generateTypesFromGitHub(repo, options)`: Generate types from GitHub _(v1.1.1)_
 
-## ⚛️ React Hooks
+## 🌐 Browser Usage
 
-### `useWasm(wasmPath, options)`
+For browser environments, GoWM automatically optimizes for the browser:
 
-Hook for loading local WASM modules.
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="module">
+      import { loadFromGitHub } from "./node_modules/gowm/src/browser.js";
+
+      async function init() {
+        const wasm = await loadFromGitHub(
+          "benoitpetit/wasm-modules-repository",
+          {
+            path: "math-wasm",
+          },
+        );
+        const result = wasm.call("add", 21, 21);
+        console.log("21 + 21 =", result); // 42
+      }
 
-```jsx
-import { useWasm } from 'gowm/hooks/useWasm';
+      init();
+    </script>
+  </head>
+  <body>
+    <h1>GoWM Browser Example</h1>
+  </body>
+</html>
+```
 
-function MyComponent() {
-  const { wasm, loading, error } = useWasm('./my-module.wasm', {
-    name: 'myModule'
-  });
+### Global Usage
 
-  // Use wasm when loaded
-}
+```html
+<script src="path/to/gowm/src/browser.js"></script>
+<script>
+  GoWM.loadFromUrl("https://example.com/module.wasm");
+</script>
 ```
 
-### `useWasmFromGitHub(githubRepo, options)`
+## 📡 Event System _(v1.1.1)_
 
-Hook for loading WASM modules from GitHub repositories.
+Monitor module lifecycle with event listeners:
 
-```jsx
-import { useWasmFromGitHub } from 'gowm/hooks/useWasm';
+```javascript
+const gowm = new GoWM({ memoryWarningThreshold: 50 * 1024 * 1024 });
+
+gowm
+  .on("module:loading", ({ name, source }) => console.log(`Loading ${name}...`))
+  .on("module:loaded", ({ name, loadTime }) =>
+    console.log(`Loaded in ${loadTime}ms`),
+  )
+  .on("module:error", ({ name, error }) =>
+    console.error(`Failed: ${error.message}`),
+  )
+  .on("module:unloaded", ({ name }) => console.log(`Unloaded ${name}`))
+  .on("memory:warning", ({ totalMemory, threshold }) =>
+    console.warn("Memory warning!"),
+  );
 
-function MyComponent() {
-  const { wasm, loading, error } = useWasmFromGitHub('benoitpetit/wasm-modules-repository', {
-    path: 'math-wasm',
-    branch: 'master',
-    name: 'myModule'
-  });
-}
+// One-time listener
+gowm.once("module:loaded", ({ name }) =>
+  console.log(`First module loaded: ${name}`),
+);
+
+// Remove listener
+const handler = (data) => console.log(data);
+gowm.on("module:loaded", handler);
+gowm.off("module:loaded", handler);
 ```
 
-### `useMultipleWasmFromGitHub(githubRepos, options)`
+## ⚛️ React Hooks _(v1.1.1)_
 
-Hook for loading multiple WASM modules from GitHub repositories.
+```bash
+npm install gowm react
+```
 
-```jsx
-import { useMultipleWasmFromGitHub } from 'gowm/hooks/useWasm';
+```tsx
+import { useWasm, useWasmFromGitHub } from "gowm/react";
 
-function MyComponent() {
-  const { modules, loading, errors, reload } = useMultipleWasmFromGitHub([
-    { name: 'math', repo: 'benoitpetit/wasm-modules-repository', path: 'math-wasm' },
-    { name: 'crypto', repo: 'benoitpetit/wasm-modules-repository', path: 'crypto-wasm', branch: 'master' }
-  ]);
+function Calculator() {
+  const { bridge, loading, error, reload } = useWasmFromGitHub(
+    "benoitpetit/wasm-modules-repository",
+    { path: "math-wasm" },
+  );
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <div>
+      <p>5 + 3 = {bridge.call("add", 5, 3)}</p>
+      <button onClick={reload}>Reload</button>
+    </div>
+  );
 }
 ```
 
-## 🖖 Vue 3 Composables
+## 💚 Vue 3 Composables _(v1.1.1)_
 
-### `useWasm(wasmPath, options)`
-
-Composable for loading local WASM modules.
+```bash
+npm install gowm vue
+```
 
 ```vue
-<script>
-import { useWasm } from 'gowm/composables/useWasm';
+<script setup>
+import { useWasmFromGitHub } from "gowm/vue";
 
-export default {
-  setup() {
-    const { wasm, loading, error, reload } = useWasm('./my-module.wasm');
-    return { wasm, loading, error, reload };
-  }
-}
+const { bridge, loading, error, metadata, reload } = useWasmFromGitHub(
+  "benoitpetit/wasm-modules-repository",
+  { path: "math-wasm" },
+);
 </script>
+
+<template>
+  <p v-if="loading">Loading...</p>
+  <p v-else-if="error">Error: {{ error.message }}</p>
+  <div v-else>
+    <p>{{ metadata?.name }} v{{ metadata?.version }}</p>
+    <p>5 + 3 = {{ bridge.call("add", 5, 3) }}</p>
+    <button @click="reload">Reload</button>
+  </div>
+</template>
 ```
 
-### `useWasmFromGitHub(githubRepo, options)`
+## 🔧 CLI _(v1.1.1)_
 
-Composable for loading WASM modules from GitHub repositories.
+```bash
+# List available modules in a repository
+npx gowm list benoitpetit/wasm-modules-repository
 
-```vue
-<script>
-import { useWasmFromGitHub } from 'gowm/composables/useWasm';
-
-export default {
-  setup() {
-    const { wasm, loading, error } = useWasmFromGitHub('benoitpetit/wasm-modules-repository', {
-      path: 'math-wasm',
-      branch: 'master'
-    });
-    return { wasm, loading, error };
-  }
-}
-</script>
+# Get module info from module.json
+npx gowm info benoitpetit/wasm-modules-repository math-wasm
+
+# Generate TypeScript types from module.json
+npx gowm types benoitpetit/wasm-modules-repository math-wasm --out math-wasm.d.ts
+
+# Verify WASM file integrity
+npx gowm verify ./main.wasm --integrity sha256-xxxxxxxxx
+
+# Download a module (wasm + module.json + integrity)
+npx gowm install benoitpetit/wasm-modules-repository math-wasm --dir ./wasm
 ```
 
-### `useMultipleWasm(modules)`
+## 🏗️ Type Generator _(v1.1.1)_
 
-Composable for loading multiple WASM modules.
+Generate TypeScript interfaces from `module.json`:
 
-```vue
-<script>
-import { useMultipleWasm } from 'gowm/composables/useWasm';
-
-export default {
-  setup() {
-    const { modules, loading, errors } = useMultipleWasm([
-      { name: 'local', path: './local.wasm' },
-      { name: 'github', github: 'benoitpetit/wasm-modules-repository', path: 'math-wasm' }
-    ]);
-    return { modules, loading, errors };
-  }
+```javascript
+const { generateTypes, generateTypesFromGitHub } = require("gowm");
+
+// From a metadata object
+const ts = generateTypes(metadata, { includeJSDoc: true });
+
+// From GitHub
+const ts = await generateTypesFromGitHub(
+  "benoitpetit/wasm-modules-repository/math-wasm",
+  { branch: "master" },
+);
+```
+
+Generated output:
+
+```typescript
+import { WasmBridge } from "gowm";
+
+/** math-wasm v0.2.0 - Mathematical functions */
+export interface MathWasmBridge extends WasmBridge {
+  /** Add two numbers */
+  call(func: "add", a: number, b: number): number;
+  /** Calculate factorial */
+  call(func: "factorial", n: number): number;
+  // ...
 }
-</script>
 ```
 
-## 🌐 Browser Usage
+## 🏗️ Architecture
 
-For browser environments, use the ES6 module version:
+GoWM v1.1.1 features a clean architecture:
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <script type="module">
-        import { loadFromGitHub } from './node_modules/gowm/src/browser.js';
-        
-        async function init() {
-            const wasm = await loadFromGitHub('benoitpetit/wasm-modules-repository', {
-              path: 'math-wasm',
-              branch: 'master'
-            });
-            const result = wasm.call('add', 21, 21);
-            console.log('21 + 21 =', result); // 42
-        }
-        
-        init();
-    </script>
-</head>
-<body>
-    <h1>GoWM Browser Example</h1>
-</body>
-</html>
+```
+src/
+├── core/gowm.js              # Main GoWM class (events, logging)
+├── loaders/unified-loader.js  # Universal loading system with metadata & integrity
+├── bridges/unified-bridge.js  # Namespace-aware bridge with validation & describe()
+├── react/index.js             # React hooks (useWasm, useWasmFromGitHub)
+├── vue/index.js               # Vue 3 composables (useWasm, useWasmFromGitHub)
+├── cli/gowm-cli.js            # CLI (list, info, types, verify, install)
+├── tools/type-generator.js    # TypeScript type generation from module.json
+├── index.js                   # Main entry point
+└── browser.js                 # Browser-optimized entry
+types/
+├── index.d.ts                 # Core TypeScript definitions
+├── react.d.ts                 # React hooks types
+└── vue.d.ts                   # Vue composables types
 ```
 
+### Key Improvements in v1.1.1
+
+- **Event System**: `on()` / `off()` / `once()` for module lifecycle events with memory warnings
+- **React Hooks**: `useWasm()` and `useWasmFromGitHub()` with auto-cleanup
+- **Vue 3 Composables**: Reactive refs with `watch()` support and auto-cleanup
+- **CLI**: 5 commands for module discovery, inspection, type generation, integrity, and installation
+- **Type Generator**: Generate TypeScript interfaces from `module.json` metadata
+- **ESM Exports Map**: Sub-path exports for `gowm/react`, `gowm/vue`, `gowm/tools/type-generator`
+- **274 Unit Tests**: Extended test coverage for all features
+
 ## 📊 Examples
 
 Check out the `/examples` directory for comprehensive examples:
 
-- **Node.js examples**: Basic and advanced usage patterns
-- **React examples**: Complete React applications with hooks
-- **Vue examples**: Vue 3 application templates with composables
+- **Node.js examples**: Basic, crypto, text, and JSON/XML usage patterns
 - **Browser examples**: Vanilla JavaScript implementations
 
+### Running Examples
+
+```bash
+# Run basic Node.js example
+npm run test:basic
+
+# Run crypto example
+npm run test:crypto
+
+# Serve browser examples
+npm run demo:serve
+```
+
+## 🔧 Development
+
+### Running Tests
+
+```bash
+# Run all unit tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run all tests (unit + integration + examples)
+npm run test:all
+```
+
+### Testing Your Modules
+
+```javascript
+const { GoWM } = require("gowm");
+const gowm = new GoWM({ logLevel: "debug" });
+
+// Load and test a module
+const module = await gowm.load("your-module.wasm");
+const testResults = module.test();
+console.log("Test results:", testResults);
+
+// Get comprehensive statistics
+const stats = gowm.getStats();
+console.log("System stats:", stats);
+```
+
+### Custom Loading
+
+```javascript
+const { WasmLoader, WasmBridge } = require("gowm");
+
+// Use components directly for advanced scenarios
+const loader = new WasmLoader();
+const module = await loader.loadModule("source");
+const bridge = new WasmBridge(module, { moduleId: "my-module" });
+```
+
 ## 📄 License
 
 MIT License - see the [LICENSE](LICENSE) file for details.