From aa07cdde5c448c6df21e2ce5ebd6fe20167a9dac Mon Sep 17 00:00:00 2001
From: MatiasManevi <manevimatias@gmail.com>
Date: Wed, 18 Mar 2026 11:48:11 -0300
Subject: [PATCH] Add documentation

---
 wasm/README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/wasm/README.md b/wasm/README.md
index 2c2595b3..5de7570b 100644
--- a/wasm/README.md
+++ b/wasm/README.md
@@ -19,6 +19,7 @@ TypeScript.
 > (installation succeeded on one Windows 11 machine but failed on others)._
 
 ## Installation
+
 The easiest way to use the MuJoCo JavaScript bindings is to install the
 `@mujoco/mujoco` package from npm:
 
@@ -30,6 +31,36 @@ This package is ESM (`type: module`) and includes the pre-compiled WebAssembly
 module, JavaScript bindings, and TypeScript declarations. Ensure your bundler or
 dev server serves the `.wasm` asset at runtime.
 
+### Threading Models
+
+The `@mujoco/mujoco` package includes two distinct builds of the engine to
+support different browser environments and performance needs.
+
+#### 1. Single-Threaded (Default)
+
+The standard single-threaded version is located at the root of the package. It
+is compatible with all modern browsers and does not require special security
+headers.
+```typescript
+import loadMujoco from '@mujoco/mujoco';
+```
+
+#### 2. Multi-Threaded (MT)
+
+The multi-threaded version is located in the `/mt` subfolder. It utilizes Web
+Workers and `SharedArrayBuffer` to parallelize physics computations.
+```typeScript
+import loadMujoco from '@mujoco/mujoco/mt';
+```
+
+> [!CAUTION]
+> Due to the use of `SharedArrayBuffer`, browsers require Cross-Origin Isolation
+> to enable multi-threading. Your web server must send the following HTTP
+> headers:
+>    - `Cross-Origin-Opener-Policy: same-origin`
+>    - `Cross-Origin-Embedder-Policy: require-corp`
+> If these headers are missing, the module will fail to initialize.
+
 ## Build from source
 
 ### Prerequisites
@@ -98,6 +129,14 @@ This command will generate the following folders under the project root:
 - `build`: contains MuJoCo compiled using Emscripten.
 - `wasm/dist`: contains the WebAssembly module, `.js` and `.d.ts` files.
 
+The assets inside those folders are compiled and prepared to run as
+single-threaded. If you need to operate with a multi-threaded version of the
+module make sure to pass the `-DMUJOCO_WASM_THREADS=ON` flag like:
+
+```sh
+emcmake cmake -B build -DMUJOCO_WASM_THREADS=ON && cmake --build build
+```
+
 ### Example Application
 
 After generating the bindings you will be ready to write web applications using