From 8453b1fc8f6f44f25076b019a624efc0decc0747 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Sun, 24 May 2026 00:25:12 +0200
Subject: [PATCH] Add asserts for set_cell_gid write API

Covers happy-path round-trip, bounds rejection (positive and negative),
unknown-layer rejection, and on-demand layer allocation.
---
 init.lua                 | 36 ++++++++++++++++++++++++++++++++++++
 maps/write_test.map.json | 16 ++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 maps/write_test.map.json

diff --git a/init.lua b/init.lua
index 371e554..20c948b 100644
--- a/init.lua
+++ b/init.lua
@@ -246,6 +246,42 @@ function M.run_tests(ctx)
     local list = maps.list()
     engine.test.equals(#list, 2, "maps.list returns 2 registered maps")
 
+    -- ---------- v0.4.0: Write APIs — set_cell_gid ----------
+    -- Build a fresh v2 map for write tests (separate from earlier load-based tests).
+    -- maps.create only handles the v1 path (requires tilemap_table); use maps.load
+    -- with a fixture file for the v2 path instead.
+    local write_id = maps.load("maps/write_test.map.json")
+    maps.set_current(write_id)
+
+    -- Happy path
+    local gid_painted = maps.encode_gid(0, 1, 0)
+    maps.set_cell_gid("surface", 1, 2, gid_painted)
+    engine.test.equals(maps.cell_gid("surface", 1, 2), gid_painted,
+        "set_cell_gid writes the cell that cell_gid reads back")
+
+    -- Bounds-error: x >= w
+    local ok1, err1 = pcall(function() maps.set_cell_gid("surface", 4, 0, gid_painted) end)
+    engine.test.assert(not ok1, "set_cell_gid rejects x out of bounds")
+    engine.test.assert(err1 and err1:find("bounds"), "set_cell_gid bounds-error mentions 'bounds'")
+
+    -- Bounds-error: negative coord
+    local ok2 = pcall(function() maps.set_cell_gid("surface", -1, 0, gid_painted) end)
+    engine.test.assert(not ok2, "set_cell_gid rejects negative x")
+
+    -- Unknown-layer error
+    local ok3, err3 = pcall(function() maps.set_cell_gid("bogus_layer", 0, 0, gid_painted) end)
+    engine.test.assert(not ok3, "set_cell_gid rejects unknown layer")
+    engine.test.assert(err3 and err3:find("layer"), "unknown-layer error mentions 'layer'")
+
+    -- On-demand layer allocation
+    engine.test.assert(maps.cell_gid("wall", 0, 0) == 0,
+        "wall layer empty before any write")
+    maps.set_cell_gid("wall", 2, 2, gid_painted)
+    engine.test.equals(maps.cell_gid("wall", 2, 2), gid_painted,
+        "set_cell_gid auto-allocates the wall layer")
+    engine.test.equals(maps.cell_gid("wall", 0, 0), 0,
+        "auto-allocated layer initialised to all-zero except the written cell")
+
     engine.exit(engine.test.failures())
 end
 
diff --git a/maps/write_test.map.json b/maps/write_test.map.json
new file mode 100644
index 0000000..d0a047c
--- /dev/null
+++ b/maps/write_test.map.json
@@ -0,0 +1,16 @@
+{
+  "schema_version": 2,
+  "id": "write_test",
+  "size": { "w": 4, "h": 4 },
+  "atlases": ["demo_tilemap"],
+  "layers": {
+    "surface": {
+      "tiles": [
+        0, 0, 0, 0,
+        0, 0, 0, 0,
+        0, 0, 0, 0,
+        0, 0, 0, 0
+      ]
+    }
+  }
+}