Render surface maps directly and preserve their quality

docs/surface-maps.md

@@ -0,0 +1,27 @@
+# Surface maps
+
+Plugin exports now produce a flat, north-up map rather than a textured aerial
+render. The map uses up to 128 cells along its longest side, chooses the dominant
+surface material in each cell, shades slopes and water depth, and retains the
+original world bounds. Transparent glass and small vegetation do not hide the
+ground. Unknown blocks use stone gray; material colors are approximations.
+
+Uncaptured terrain appears as parchment. The saved WebP uses lossless compression
+and nearest-neighbor scaling, with a subtle grid. Fabric maps retain their
+client-captured colors and are also compressed losslessly. The web preview,
+player guessing map and results share a parchment frame.
+
+New plugin uploads automatically use the new renderer. Existing processed images
+are not regenerated merely by restarting the web server. For an unpublished
+original capture, use the existing `npm run reprocess -- <dataset UUID>` workflow
+with the worker stopped, then restart the worker. Published revisions retain
+their approved media.
+
+To create just a local map image from a retained export, without rerendering
+panoramas or changing stored data:
+
+```sh
+npm run render:map -- path/to/terrain.json.gz path/to/map.webp
+```
+
+The parchment is a local SVG UI asset; no remote textures are required.