From a2ca59838e8ddbcba5a31de5af882ab79050baef Mon Sep 17 00:00:00 2001
From: Kyuhwan Lee <145569428+wtdlee@users.noreply.github.com>
Date: Fri, 26 Dec 2025 19:51:01 +0900
Subject: [PATCH] docs(web): add WASM version compatibility section

Add documentation about version compatibility requirements between
web-tree-sitter and tree-sitter-cli for WASM file generation.

This helps users understand why Language.load() might fail when using
pre-built WASM files from third-party packages that were built with
incompatible tree-sitter-cli versions.

Closes #5171
---
 lib/binding_web/README.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/lib/binding_web/README.md b/lib/binding_web/README.md
index 08a939dc..acf18d7d 100644
--- a/lib/binding_web/README.md
+++ b/lib/binding_web/README.md
@@ -191,6 +191,29 @@ npx tree-sitter build --wasm node_modules/tree-sitter-javascript
 
 If everything is fine, file `tree-sitter-javascript.wasm` should be generated in current directory.
 
+### WASM Version Compatibility
+
+> [!IMPORTANT]
+> WASM language files must be generated with a compatible version of `tree-sitter-cli`.
+
+The WASM binary format includes ABI (Application Binary Interface) information that must match between `web-tree-sitter` and the generated `.wasm` files. Using incompatible versions will cause `Language.load()` to fail.
+
+| web-tree-sitter | Compatible tree-sitter-cli |
+|-----------------|---------------------------|
+| 0.26.x          | 0.26.x                    |
+| 0.25.x          | 0.20.x - 0.25.x           |
+| 0.24.x          | 0.20.x - 0.24.x           |
+
+**If you're using pre-built WASM files** from third-party packages (e.g., `tree-sitter-wasms`), ensure they were built with a compatible `tree-sitter-cli` version.
+
+**Recommended**: Generate WASM files with the same major.minor version of `tree-sitter-cli` as your `web-tree-sitter` version:
+
+```sh
+# For web-tree-sitter@0.26.x, use tree-sitter-cli@0.26.x
+npm install tree-sitter-cli@0.26
+npx tree-sitter build --wasm node_modules/tree-sitter-javascript
+```
+
 ### Running .wasm in Node.js
 
 Notice that executing `.wasm` files in Node.js is considerably slower than running [Node.js bindings][node bindings].