feat(api): palette floor paint, region query, and walkability (#7)

[Aduersarius]

Summary

Resolves #7 — Etapa 1 floor API so an uploaded/palette tile can be painted onto the map floor through the persistence layer.

What landed

• Palette-entry paint (issue literal): PUT .../floor/paint, .../paint-rectangle, .../paint-selection expand a paletteId into all layers + layer-1 blocked (same contract as the in-game editor), then write via existing atomic paintTiles drafts.
• Blocked-only mutation PUT .../floor/blocked that preserves existing draft/published grhIndex (does not null out graphics).
• Effective region query GET .../floor/region — base terrain.json palette id/graphics/blocked merged with draft-preferred overrides (not just override rows).
• Walkability / isolation BFS GET .../floor/walkability (+ warning attached to paint/blocked responses) so sealing off walkable islands is detectable after collision edits.
• Pure unit tests (npx tsx --test src/tests/floorPaint.unit.test.ts) for geometry caps, 20×20 plans, palette expansion, and isolation.

Acceptance mapping

• Paint tile / 20×20 rectangle as one atomic TX (delegates to paintTiles BEGIN/COMMIT/ROLLBACK)
• OOB coords → validation 400, no partial write
• Palette entry must exist on that map’s terrain.json
• Per-op cap 500 tiles (rectangle + selection)
• Blocked flag mutation + isolation check (server movement still authoritative after publish)
• Failed op rolls back via existing paint TX
• Tests (unit; integration inherits world-builder admin gate)

Differentiation vs competing PRs

• vs feat(world-builder): rectangle fill and tile mutation API with bounds check (#7) #134 (angelTomo9): no email/SES / schema palette-CRUD / server-shutdown noise; paints full palette entries not single-layer grhIndex; includes walkability; selection API; pure unit tests.
• vs feat(map-tiles): rectangle paint, region query, and isolation detection APIs #139 (JemimahEkong): palette-entry paint + effective region state (base+overrides) instead of override-only bbox; blocked updates preserve graphics; selection paint; no CI.yml churn; unit-tested BFS helpers.
• vs feat(api): terrain painting API, atomic rectangle tools and collision mutation (#7) #67 (angelTomo9): actually wired to worldBuilder.paintTiles + Postgres drafts (not an in-memory stub service); no kitchen-sink frontend/protocol files.

Test plan

• cd api && npx tsx --test src/tests/floorPaint.unit.test.ts (6/6)
• Manual: admin paint 20×20 → publish → reload map shows floor change
• Manual: out-of-range / missing paletteId → 400/404, map unchanged
• Manual: blocked ring → walkability reports isolated: true

[gitar-bot]

Important

You are using the Gitar free plan. Upgrade to unlock code review, CI analysis, auto-apply, custom automations, and more.

_Gitar