From f5f9ea8cd9c192b411b2ebee596a5b0803767c96 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 parser ABIs 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.

Co-authored-by: Will Lillis <will.lillis24@gmail.com>
---
 lib/binding_web/README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/lib/binding_web/README.md b/lib/binding_web/README.md
index 2a62bf6a8..3dfd31966 100644
--- a/lib/binding_web/README.md
+++ b/lib/binding_web/README.md
@@ -193,6 +193,19 @@ 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 compatibility
+
+`web-tree-sitter` supports the same parser ABI versions as the corresponding tree-sitter library:
+
+| web-tree-sitter version | Min parser ABI version | Max parser ABI version |
+|-------------------------|------------------------|------------------------|
+| 0.24.x                  | 13                     | 14                     |
+| >= 0.25.0               | 13                     | 15                     |
+
+> [!WARNING]
+> Some prebuilt `.wasm` files use an older dynamic-linking format that newer versions of `web-tree-sitter` cannot
+> load, even if their parser ABI is supported. Rebuild these files using a current tree-sitter CLI.
+
 ### Running .wasm in Node.js
 
 Notice that executing `.wasm` files in Node.js is considerably slower than running [Node.js bindings][node bindings].