feat(packages): ludic.minimap - a map's logic: the explored fog over a grid of cells round an origin (revealed within a reach, a version for rebaking, explored as a share of the land over a core square, the grid as text for an older save), the player's marks (a cap, a symbol, a colour, the day, a name; the open one and the followed one, rubbing out, the last symbol reused, the nearest for a compass) and the view (world to window and back, zoom in steps and about a point, a drag, pick and place, the camp, you, a focus that never pulls back out, a scale bar, bounds); the world through a port; seen and marks in its own save section by key

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/ludic.minimap/README.md

@@ -0,0 +1,80 @@
+# ludic.minimap
+
+What a map knows without drawing anything: which cells of a grid have been walked, the marks the
+player put on it, and where its window looks. The game paints the picture - the ground, the fog,
+the icons, the legend - from the package's queries. Uses [`ludic.base`](../ludic.base/README.md)
+and nothing else.
+
+```ludic
+import "ludic.minimap"
+```
+
+## The explored fog
+
+A square grid of `cells` per side, `cell_m` metres each, centred on `MinimapWorld.origin`.
+`minimap_reveal(x, z, r)` marks every cell any part of which lies within `r`; `minimap_version()`
+goes up whenever what has been seen changes, so a baked fog texture is rebuilt only then.
+**Explored** is a share of LAND, over a core square of the grid (`minimap_config_core`), so open
+water is not unexplored and a bigger grid does not change what a chapter's "walk 30%" asks for.
+
+## The marks
+
+A mark (`MinimapPin { x, z, icon, colour, day, label }`) is a note at a place: it does not route
+anyone and it does not move. There is a cap; `minimap_pin_add` answers -1 past it and the game
+says so. One mark may be **open** (the legend edits it) and one **followed** (the game puts it on
+its compass); a new mark takes the symbol last chosen. Rubbing one out moves the later ones up,
+and the open and followed indices with them.
+
+## The view
+
+A square window of `size` pixels showing `span` metres across at zoom 1, centred on a world point
+and kept inside `MinimapWorld`'s bounds. World to window (`minimap_px`, `minimap_py`) and back
+(`minimap_wx`, `minimap_wz`, from a point measured from the window's corner), zoom in steps or
+about a point (what is under the pointer stays under it), a drag that pans, a press that picks the
+mark under it or drops a new one, "the camp" and "you", and a focus that goes there and closes in
+but never pulls a closer view back out.
+
+## The port
+
+```ludic
+export port MinimapWorld {       # every member has a default
+  origin_x, origin_z             # the grid's centre
+  land(x, z) -> bool             # what "explored" counts
+  you_x, you_z, camp_x, camp_z   # the two places a view recentres on
+  day() -> int                   # a mark remembers the day it was made
+  lo_x, lo_z, hi_x, hi_z         # the view's centre stays inside these
+}
+```
+
+## API
+
+| | |
+| --- | --- |
+| `minimap_config(cells, cell_m)`, `minimap_config_core(from, n)`, `minimap_land_changed()` | the grid, the square explored is measured over, and a new ground under it |
+| `minimap_reveal(x, z, r)`, `minimap_reveal_cell(c)` | walking |
+| `minimap_cell(x, z)`, `minimap_cells()`, `minimap_cell_m()`, `minimap_cell_x(i)`, `minimap_cell_z(j)`, `minimap_grid_x0()`, `minimap_grid_z0()`, `minimap_grid_half()` | the grid's geometry |
+| `minimap_seen(c)`, `minimap_seen_at(x, z)`, `minimap_seen_count()`, `minimap_version()`, `minimap_explored_pct()` | what has been seen |
+| `minimap_seen_text()`, `minimap_seen_from_text(s)` | the grid as one string of 0 / 1 (an older save's shape) |
+| `minimap_config_pins(max, symbols, colours)`, `minimap_pins_clear()` | the marks' cap and ranges |
+| `minimap_pin_add(x, z, icon, label) -> int`, `minimap_pin_put(x, z, icon, colour, day, label)`, `minimap_pin_remove(i)` | a mark made today, one as saved, and rubbing one out |
+| `minimap_pin_count()`, `minimap_pin_max()`, `minimap_pin_full()`, `minimap_pin(i) -> MinimapPin` | the marks |
+| `minimap_pin_set_label/icon/colour(i, v)`, `minimap_pin_last_icon()` | editing one |
+| `minimap_pin_open()`, `minimap_pin_select(i)`, `minimap_pin_followed()`, `minimap_pin_follow(i)`, `minimap_pin_follow_toggle()` | the open one and the followed one |
+| `minimap_pins_near(x, z, n, within) -> []int` | the nearest marks, not the followed one (for a compass) |
+| `minimap_config_view(span, zoom_min, zoom_max, focus)`, `minimap_window(x0, y0, size)` | the view's range, and where the window is this frame |
+| `minimap_px(x)`, `minimap_py(z)`, `minimap_wx(rx)`, `minimap_wz(ry)`, `minimap_span()`, `minimap_scale()`, `minimap_scale_metres()` | projection, and a scale bar's round distance |
+| `minimap_zoom()`, `minimap_zoom_set(z)`, `minimap_zoom_step(dir)`, `minimap_zoom_about(rx, ry, factor)` | zoom |
+| `minimap_view_x()`, `minimap_view_z()`, `minimap_have_view()`, `minimap_centre(x, z)`, `minimap_clamp()`, `minimap_recentre(on_you)`, `minimap_focus(on_you)` | where it looks |
+| `minimap_pan_begin(rx, ry)`, `minimap_pan_to(rx, ry)`, `minimap_pan_end()`, `minimap_panning()` | a drag |
+| `minimap_pick(rx, ry, r) -> int`, `minimap_placing()`, `minimap_place_toggle()`, `minimap_place(rx, ry, label) -> int` | a press: open the mark under it, or drop the next one there |
+| `minimap_reset()`, `minimap_system() -> System` | `"minimap"`: the seen grid, the marks, the followed one and the last symbol in its own section, by key; the view is not saved |
+
+## Tests
+
+```bash
+ludic test packages/ludic.minimap
+```
+
+A 20 x 20 grid with sea on one side: the cells, revealing and the land's share, the marks' cap,
+editing and rubbing out, the nearest for a compass, projection, zoom about a point, a pan, focus
+and the clamp, picking and placing, the scale bar, and the save.