Wire up editor: input bindings, frame hooks, launcher script

init.lua loads the work map, binds hotkeys (E/R/S/Esc), tracks
mouse-cell per frame, dispatches clicks to the UI hit-tester
and falls through to paint-cell for unconsumed map-area clicks.
run-map-editor.sh handles copy-in/copy-out for a real target map
or runs in-place against the module's work slot.

README.md

@@ -1,15 +1,46 @@
 # sporel-module-map-editor
 
-Interactive map editor module for v2 Sporel maps. Click-to-paint, vertical layer-chip overlay, collapsible atlas+tile picker.
-
-## Status
-
-`v0.1.0` — initial POC. See `docs/superpowers/specs/2026-05-23-sporel-module-map-editor-design.md` in `sporel-meta` for the full spec.
+Interactive map editor for v2 Sporel map files. Click-to-paint, vertical layer-chip overlay on the left edge, collapsible atlas+tile picker bottom-left.
 
 ## Run
 
+Default — edit the module's in-place work map:
+
 ```bash
-bash scripts/run-map-editor.sh [target_map.json]
+bash scripts/run-map-editor.sh
 ```
 
-(Detailed hotkey reference and UI walkthrough added in a later commit.)
+With a target — copy a real map in, edit, copy back out:
+
+```bash
+bash scripts/run-map-editor.sh ~/Projects/Sporel/sporel-modules/spine-prototype/maps/demo.map.json
+```
+
+## UI
+
+- **Layer chips** (left edge, vertical): top-of-stack down. `Rf` at top toggles roof-edit mode; the other eight chips select the active layer.
+  - **Left-click** = set active layer (or toggle roof mode)
+  - **Right-click** = toggle layer visibility (Rf chip ignores right-click)
+- **Atlas + tile picker** (bottom-left): collapsed chip shows the active tile. Click to expand; click again or outside to collapse.
+- **Status chip** (bottom-right): current mouse-cell coordinate plus a `*` when the map has unsaved changes.
+
+## Hotkeys
+
+| Key | Action |
+|---|---|
+| `Left click` on map | Paint cell with active tile (or set roof flag in roof-mode) |
+| `E` | Erase the cell under the mouse |
+| `R` | Cycle rotation 0 → 1 → 2 → 3 → 0 |
+| `S` | Save to disk (overwrites the work map) |
+| `Esc` | Quit |
+
+## Limitations (v0.1.0)
+
+- Tile thumbnails in the picker render as gray placeholders with tile-IDs as text — lib-core.maps v0.4.0 does not expose per-tile UVs to Lua, so visual thumbnails are a v0.2.0 task.
+- Atlas list in the picker is purely informational; if a map declares multiple atlases, the active atlas is set from `state.lua` defaults at startup and cannot yet be switched via UI (v0.2.0 hit-tests inside the expanded picker).
+- Engine bindings `engine.render.draw_rect_lines` and `engine.render.draw_line` are not yet registered — active-chip borders, hidden-layer strikethroughs, and the entity-slot divider will trigger runtime errors when their code paths execute. Adding the bindings is a small engine-side follow-up.
+- No undo/redo, no multi-tile brush, no entity placement, no heightmap editing — see the design spec §1 for the full out-of-scope list.
+
+## Spec
+
+`docs/superpowers/specs/2026-05-23-sporel-module-map-editor-design.md` in the `sporel-meta` repo.