feat: add packed-u32 GID encoding helpers for schema-v2 maps

encode_gid / decode_gid pack atlas_index (8 bits), tile_id (20 bits), and
rotation (2 bits) into a single u32; gid == 0 is reserved as the empty-cell
sentinel. Lua 5.4 native bitwise operators used throughout.

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

init.lua

@@ -12,6 +12,37 @@ local map_registry      = {}    -- map_id -> Map
 local tilemap_registry  = {}    -- full_tilemap_id -> Tilemap
 local current_map_id    = nil
 
+-- =====================================================================
+-- Packed-u32 GID encoding (Schema-v2)
+-- Bit-Layout:
+--   Bits 31..24 : atlas_index  (8 bits, 0..255)
+--   Bits 23..4  : tile_id      (20 bits, 0..1_048_575)
+--   Bits 3..2   : rotation     (2 bits, 0..3, n * 90° CW)
+--   Bits 1..0   : reserved     (must be 0 in v2; future flip-h/v)
+-- gid == 0 means empty cell (atlas 0 + tile 0 reserved as null).
+-- =====================================================================
+
+local GID_ATLAS_SHIFT = 24
+local GID_TILE_SHIFT  = 4
+local GID_ROT_SHIFT   = 2
+local GID_ATLAS_MASK  = 0xFF        -- 8 bits
+local GID_TILE_MASK   = 0xFFFFF     -- 20 bits
+local GID_ROT_MASK    = 0x3         -- 2 bits
+
+local function encode_gid(atlas_index, tile_id, rotation)
+    rotation = rotation or 0
+    return (atlas_index << GID_ATLAS_SHIFT)
+         | (tile_id     << GID_TILE_SHIFT)
+         | (rotation    << GID_ROT_SHIFT)
+end
+
+local function decode_gid(gid)
+    local atlas_index = (gid >> GID_ATLAS_SHIFT) & GID_ATLAS_MASK
+    local tile_id     = (gid >> GID_TILE_SHIFT)  & GID_TILE_MASK
+    local rotation    = (gid >> GID_ROT_SHIFT)   & GID_ROT_MASK
+    return atlas_index, tile_id, rotation
+end
+
 -- =====================================================================
 -- Internal helpers
 -- =====================================================================
@@ -321,4 +352,7 @@ function M.pin(map_id, reason)
     engine.warn("maps.pin: deferred to map-topology lifecycle slice")
 end
 
+M.encode_gid = encode_gid
+M.decode_gid = decode_gid
+
 return M