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

@@ -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
 

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
+      ]
+    }
+  }
+}