map rendered strings to template token source

README.md

@@ -125,6 +125,51 @@ render("./output", { web: "not a boolean", header: { show: true, title: "Hi" } }
 
 For safety, tdir refuses to render into the filesystem root, the current working directory, the home directory, or any directory that overlaps the template source. Dynamic file and directory names are also resolved against the output directory and cannot write outside it.
 
+## Reverse maps
+
+Pass `{ reverseMap: true }` as the third render argument to write `.tdir-map.json` into the output directory:
+
+```ts
+render("./output", {
+  web: true,
+  header: { show: true, title: "Hello" }
+}, { reverseMap: true })
+```
+
+Pass a string to choose a custom JSON path inside the output directory:
+
+```ts
+render("./output", context, { reverseMap: "meta/reverse-map.json" })
+```
+
+The map contains a flat lookup from rendered strings to template tokens plus per-file occurrences with path/range context:
+
+```json
+{
+  "version": 1,
+  "files": [
+    {
+      "outputPath": "web/index.html",
+      "templatePath": "<@if(context.web)>web/index.html",
+      "tokens": [
+        {
+          "kind": "content",
+          "result": "Hello",
+          "token": "<@var(context.header.title)>",
+          "contextPath": "header.title",
+          "outputPath": "web/index.html",
+          "templatePath": "<@if(context.web)>web/index.html",
+          "range": { "start": 16, "end": 21 }
+        }
+      ]
+    }
+  ],
+  "tokens": {
+    "Hello": ["<@var(context.header.title)>"]
+  }
+}
+```
+
 ## Unmatched directives
 
 A `<@if>` without a matching `<@endif>` throws when the renderer is initialized: