From c869196a624bfaca69cddcb34c750f6259091196 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Mon, 11 May 2026 02:48:47 +0200
Subject: [PATCH] =?UTF-8?q?feat:=20P.3.1=20reference=20test-module=20?=
 =?UTF-8?q?=E2=80=94=20lib-core.maps=20assertions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore                             |  2 ++
 README.md                              | 17 ++++++++++++
 assets/tiles/demo_tilemap.tilemap.json |  8 ++++++
 init.lua                               | 37 ++++++++++++++++++++++++++
 manifest.core                          |  6 +++++
 manifest.module                        | 10 +++++++
 maps/demo.map.json                     | 23 ++++++++++++++++
 7 files changed, 103 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 assets/tiles/demo_tilemap.tilemap.json
 create mode 100644 init.lua
 create mode 100644 manifest.core
 create mode 100644 manifest.module
 create mode 100644 maps/demo.map.json

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..41ae811
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+build/
+*.log
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d31157a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,17 @@
+# sporel-module-lib-core.maps-test
+
+P.3.1 reference test-module — validates `lib-core.maps` API contracts
+via the `engine.test.*` assertion surface.
+
+- Module-ID: `lib-core.maps-test`
+- Version: `0.1.0`
+- Kind: `test-module` (headless; runs init() once + exits)
+- Spec: `meta/docs/superpowers/specs/2026-05-10-test-module-pattern-design.md`
+
+## Run
+
+```bash
+Sporel.exe --module=lib-core.maps-test
+```
+
+Output is TAP version 13 on stdout; exit-code = failure-count (0 = all pass).
diff --git a/assets/tiles/demo_tilemap.tilemap.json b/assets/tiles/demo_tilemap.tilemap.json
new file mode 100644
index 0000000..a5381d2
--- /dev/null
+++ b/assets/tiles/demo_tilemap.tilemap.json
@@ -0,0 +1,8 @@
+{
+  "id": "demo_tilemap",
+  "tile_size": 32,
+  "tiles": [
+    {"id": "grass", "walkable": true,  "color": [110, 170, 80]},
+    {"id": "stone", "walkable": false, "color": [120, 120, 120]}
+  ]
+}
diff --git a/init.lua b/init.lua
new file mode 100644
index 0000000..7035fce
--- /dev/null
+++ b/init.lua
@@ -0,0 +1,37 @@
+-- =====================================================================
+-- lib-core.maps-test — Reference test-module (P.3.1)
+-- Validates lib-core.maps API contracts via engine.test.* assertions.
+-- See: meta/docs/superpowers/specs/2026-05-10-test-module-pattern-design.md
+-- =====================================================================
+local maps = require("lib-core.maps")
+
+function init(ctx)
+    -- Setup
+    local demo_map = maps.load("maps/demo.map.json")
+    maps.set_current(demo_map)
+
+    -- Geometry assertions
+    local size = maps.size()
+    engine.test.equals(size.w, 16, "map width = 16")
+    engine.test.equals(size.h, 16, "map height = 16")
+    engine.test.equals(maps.tile_size(), 32, "tile_size = 32")
+
+    -- Tile lookup + walkability
+    engine.test.equals(maps.tile_at(0, 0).id,  "stone", "tile_at(0,0) is stone")
+    engine.test.equals(maps.tile_at(5, 5).id,  "grass", "tile_at(5,5) is grass")
+    engine.test.assert(not maps.is_walkable(0, 0), "stone border non-walkable")
+    engine.test.assert(maps.is_walkable(5, 5),     "grass interior walkable")
+
+    -- Arity-flex tile_at: 3-arg with nil map_id falls back to current_map (P.2.1)
+    engine.test.equals(maps.tile_at(nil, 5, 5).id, "grass", "tile_at 3-arg nil-fallback")
+
+    -- Out-of-bounds returns nil
+    engine.test.equals(maps.tile_at(-1, 0), nil, "tile_at OOB negative tx returns nil")
+    engine.test.equals(maps.tile_at(0, 16), nil, "tile_at OOB ty=size.h returns nil")
+
+    -- list() returns registered map-id
+    local list = maps.list()
+    engine.test.equals(#list, 1, "maps.list returns 1 registered map")
+
+    engine.exit(engine.test.failures())
+end
diff --git a/manifest.core b/manifest.core
new file mode 100644
index 0000000..5ea164a
--- /dev/null
+++ b/manifest.core
@@ -0,0 +1,6 @@
+{
+    "id": "lib-core.maps-test.core",
+    "kind": "lib",
+    "version": "0.1.0",
+    "license": "Proprietary"
+}
diff --git a/manifest.module b/manifest.module
new file mode 100644
index 0000000..b4abd0d
--- /dev/null
+++ b/manifest.module
@@ -0,0 +1,10 @@
+{
+    "id": "lib-core.maps-test",
+    "kind": "test-module",
+    "version": "0.1.0",
+    "api": "^0.1",
+    "entry_point": "init.lua",
+    "deps": [
+        {"id": "lib-core.maps", "version": "0.1.1"}
+    ]
+}
diff --git a/maps/demo.map.json b/maps/demo.map.json
new file mode 100644
index 0000000..af8d150
--- /dev/null
+++ b/maps/demo.map.json
@@ -0,0 +1,23 @@
+{
+  "id": "demo",
+  "tilemap": "demo_tilemap",
+  "size": {"w": 16, "h": 16},
+  "tiles": [
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2
+  ]
+}