fix(maps): v0.5.6 — derive bitmask from cell's own corner paint-tiles

compute_cell_bitmask_v3 now reads the 8-bit neighbour bitmask from
the render-cell's own 4 corner paint-tiles (cardinal bit set iff
at least one of the 2 paint-tiles on that edge is painted; diagonal
bit set iff the corner paint-tile is painted), not from the
any-corner material status of the 8 neighbour render-cells.

Pre-0.5.6 used cell-neighbour-material, which let two cells share
connectivity across an empty paint-tile gap whenever any unrelated
corner of either was painted — producing connected blob shapes
where two visually separated 2x2 islands were expected.

Atlas, paint storage, override sublayer, public API and the slot
lookup table all unchanged. Doc comment and README painting-model
section rewritten to describe the dual-grid offset explicitly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -5,7 +5,7 @@ Multi-layer tile-grid map implementation with vertex-painted autotile
 loading + UV resolution, walkability + sight-blocking queries, and a
 v3 multi-layer render pipeline with opaque-ceiling cache.
 
-**Version:** 0.5.4
+**Version:** 0.5.6
 **Lib-ID:** lib-core.maps
 **Requires:** (none)
 **Tags:** maps, tile-grid, multi-layer, vertex-painting, autotile, blob-14, override, walkability, tilemap
@@ -18,19 +18,35 @@ v3 multi-layer render pipeline with opaque-ceiling cache.
 | v2 | Multi-atlas + multi-layer with packed-u32 GIDs (atlas_idx + tile_id + rotation). `set_cell_gid`, `save_to_disk`. |
 | v3 | Per-layer `material` (atlas-alias), optional `vertices` ((W+1)·(H+1) grid), optional `overrides` ({"x:y": int OR {slot, rot, flip}}). Renderer derives slot/rot/flip from neighbour-bitmask blob-gating; overrides force-place specific orientations. |
 
-## Painting model (v3 autotile)
+## Painting model (v3 autotile, dual-grid)
 
-- **Vertex grid**: (W+1)·(H+1) cells. Any-corner rule: cell (x,y) is
-  material iff any of its 4 corner vertices is painted.
-- **Blob-gating + SLOT_LOOKUP**: each material cell's 8-bit
-  neighbour-bitmask (clockwise from N) is blob-gated (diagonals zeroed
-  unless both adjacent cardinals are set), then mapped to one of 14
-  canonical slots × {0,1,2,3} rotation × {0,1} flip via a D4-orbit
-  table. 47 distinct gated bitmasks total.
+Two grids offset by half a tile. The PAINT grid (called `vertices` in
+storage, "map-tiles" in design docs) is what users paint. The RENDER
+grid (called `cells`) is offset by (+0.5, +0.5) tile and is where
+sprites sit. Each render-cell spans 4 surrounding paint-tiles which
+act as its 4 corners (TL, TR, BL, BR).
+
+- **Paint grid**: (W+1)·(H+1) cells. Any-corner rule: render-cell
+  (x,y) is material iff any of its 4 corner paint-tiles is painted.
+- **Bitmask + SLOT_LOOKUP** (0.5.6 dual-grid native): each material
+  render-cell's 8-bit neighbour-bitmask (clockwise from N) is derived
+  from its own 4 corner paint-tiles — cardinal bit set iff ≥1 of the
+  edge's 2 paint-tiles painted, diagonal bit set iff the corner
+  paint-tile is painted. Blob-gating then zeroes diagonals whose 2
+  adjacent cardinals are not both set. The gated bitmask maps to one
+  of 14 canonical slots × {0,1,2,3} rotation × {0,1} flip via a
+  D4-orbit table.
 - **Override sublayer**: sparse `{"x:y": slot}` or `{"x:y": {slot, rot,
   flip}}`. Takes precedence over the bitmask-derived slot AND forces
   material-presence on the cell.
 
+**0.5.6 fix:** pre-0.5.6 derived the bitmask from the material status
+of the 8 neighbour render-cells, which violated dual-grid semantics —
+two cells whose shared edge had no painted paint-tiles still saw each
+other as material whenever any unrelated corner of either was painted,
+producing connected blobs across visually empty paint-tile gaps. See
+plan `2026-05-29-painting-model-rethink`.
+
 ## Topology
 
 <!-- topology:start (auto-generated; do not edit) -->