Run request analysis on demand on the VPS

docs/kb/systems/layers-tile-editing.md

@@ -0,0 +1,47 @@
+# Layers And Tile Editing
+
+## What It Does
+
+This subsystem handles normal tile painting, erasing, selection, visible layer management, sparse height layers, and the mapping between visible document edits and stored chunk data.
+
+## Key Files
+
+- `src/worldshaperStudio/interactionController.ts`
+- `src/worldshaperStudio/runtime.ts`
+- `src/worldshaperStudio/sidebarController.ts`
+- `src/worldshaperStudio/mapDocumentController.ts`
+- `src/worldshaperStudio/popupSessionStore.ts`
+- `src/worldshaperStudio/dom.ts`
+
+## Endpoints It Uses
+
+- primarily saved through `POST /api/world/:worldId/chunks/batch-save`
+
+## Important Data And Rules
+
+- room layer `0` is the base layer
+- non-base layers use sparse or transparent-style fill semantics
+- height layers are separate structures from room layers
+- visibility is tracked in popup session state
+- painting in world mode must mark affected chunks dirty
+
+## Invariants And Constraints
+
+- layer ordering matters to rendering and selection behavior
+- layer visibility must not destroy layer data
+- tile edits in world mode must map local viewport coordinates back to world chunk coordinates
+- height layers are not the same thing as standard room layers
+
+## Common Request Themes
+
+- better layer reordering
+- more precise tiling tools
+- height/elevation features
+- snapping or unsnapped placement
+- erase or selection behavior
+
+## Triage Questions
+
+- Is this about normal room layers or height layers?
+- Does the request affect paint semantics, visibility, ordering, or storage?
+- Does it apply to map mode, world mode, or both?