Add comprehensive Canvas guide and refactor documentation

- Introduced a new `CANVAS_GUIDE.md` file detailing the Canvas system, including core concepts, usage patterns, and features such as tile painting, selection, and custom overlays.
- Created `CANVAS_REFACTORING_STATUS.md` to summarize the current state of refactoring efforts, including completed tasks and outstanding issues.
- Enhanced `overworld_editor` functionality by implementing critical fixes for rectangle selection and painting, ensuring proper handling of large map boundaries.
- Updated `canvas_utils.h` to include configuration options for rectangle clamping, preventing wrapping issues during tile selection.
- Refactored `canvas.cc` and `canvas.h` to improve method signatures and documentation, facilitating better understanding and usage of the Canvas API.
- Improved overall documentation structure for clarity and ease of access, consolidating multiple files into focused references.

src/app/gui/canvas.cc

@@ -35,10 +35,8 @@ using ImGui::OpenPopupOnItemClick;
 using ImGui::Selectable;
 using ImGui::Text;
 
-constexpr uint32_t kBlackColor = IM_COL32(0, 0, 0, 255);
 constexpr uint32_t kRectangleColor = IM_COL32(32, 32, 32, 255);
 constexpr uint32_t kWhiteColor = IM_COL32(255, 255, 255, 255);
-constexpr uint32_t kOutlineRect = IM_COL32(255, 255, 255, 200);
 
 constexpr ImGuiButtonFlags kMouseFlags =
     ImGuiButtonFlags_MouseButtonLeft | ImGuiButtonFlags_MouseButtonRight;
@@ -1153,7 +1151,9 @@ void Canvas::DrawOutlineWithColor(int x, int y, int w, int h, uint32_t color) {
 }
 
 void Canvas::DrawBitmapGroup(std::vector<int> &group, gfx::Tilemap &tilemap,
-                             int tile_size, float scale) {
+                             int tile_size, float scale,
+                             int local_map_size,
+                             ImVec2 total_map_size) {
   if (selected_points_.size() != 2) {
     // points_ should contain exactly two points
     return;
@@ -1166,6 +1166,11 @@ void Canvas::DrawBitmapGroup(std::vector<int> &group, gfx::Tilemap &tilemap,
   // OPTIMIZATION: Use optimized rendering for large groups to improve performance
   bool use_optimized_rendering = group.size() > 128; // Optimize for large selections
   
+  // Use provided map sizes for proper boundary handling
+  const int small_map = local_map_size;
+  const float large_map_width = total_map_size.x;
+  const float large_map_height = total_map_size.y;
+  
   // Pre-calculate common values to avoid repeated computation
   const float tile_scale = tile_size * scale;
   const int atlas_tiles_per_row = tilemap.atlas.width() / tilemap.tile_size.x;
@@ -1256,10 +1261,49 @@ void Canvas::DrawBitmapGroup(std::vector<int> &group, gfx::Tilemap &tilemap,
 
   // Performance optimization completed - tiles are now rendered with pre-calculated values
 
+  // Reposition rectangle to follow mouse, but clamp to prevent wrapping across map boundaries
   const ImGuiIO &io = GetIO();
   const ImVec2 origin(canvas_p0_.x + scrolling_.x, canvas_p0_.y + scrolling_.y);
   const ImVec2 mouse_pos(io.MousePos.x - origin.x, io.MousePos.y - origin.y);
-  auto new_start_pos = AlignPosToGrid(mouse_pos, tile_size * scale);
+  
+  // CRITICAL FIX: Clamp BEFORE grid alignment for smoother dragging behavior
+  // This prevents the rectangle from even attempting to cross boundaries during drag
+  ImVec2 clamped_mouse_pos = mouse_pos;
+  
+  if (config_.clamp_rect_to_local_maps) {
+    // Calculate which local map the mouse is in
+    int mouse_local_map_x = static_cast<int>(mouse_pos.x) / small_map;
+    int mouse_local_map_y = static_cast<int>(mouse_pos.y) / small_map;
+    
+    // Calculate where the rectangle END would be if we place it at mouse position
+    float potential_end_x = mouse_pos.x + rect_width;
+    float potential_end_y = mouse_pos.y + rect_height;
+    
+    // Check if this would cross local map boundary (512x512 blocks)
+    int potential_end_map_x = static_cast<int>(potential_end_x) / small_map;
+    int potential_end_map_y = static_cast<int>(potential_end_y) / small_map;
+    
+    // Clamp mouse position to prevent crossing during drag
+    if (potential_end_map_x != mouse_local_map_x) {
+      // Would cross horizontal boundary - clamp mouse to safe zone
+      float max_mouse_x = (mouse_local_map_x + 1) * small_map - rect_width;
+      clamped_mouse_pos.x = std::min(mouse_pos.x, max_mouse_x);
+    }
+    
+    if (potential_end_map_y != mouse_local_map_y) {
+      // Would cross vertical boundary - clamp mouse to safe zone
+      float max_mouse_y = (mouse_local_map_y + 1) * small_map - rect_height;
+      clamped_mouse_pos.y = std::min(mouse_pos.y, max_mouse_y);
+    }
+  }
+  
+  // Now grid-align the clamped position
+  auto new_start_pos = AlignPosToGrid(clamped_mouse_pos, tile_size * scale);
+  
+  // Additional safety: clamp to overall map bounds
+  new_start_pos.x = std::clamp(new_start_pos.x, 0.0f, large_map_width - rect_width);
+  new_start_pos.y = std::clamp(new_start_pos.y, 0.0f, large_map_height - rect_height);
+  
   selected_points_.clear();
   selected_points_.push_back(new_start_pos);
   selected_points_.push_back(

src/app/gui/canvas.h

@@ -154,6 +154,30 @@ class Canvas {
     std::function<void()> callback;
     std::function<bool()> enabled_condition = []() { return true; };
     std::vector<ContextMenuItem> subitems;
+    
+    // Helper constructor for simple items
+    ContextMenuItem() = default;
+    ContextMenuItem(const std::string& lbl, std::function<void()> cb, 
+                   const std::string& sc = "")
+        : label(lbl), shortcut(sc), callback(std::move(cb)) {}
+    
+    // Helper to create disabled item
+    static ContextMenuItem Disabled(const std::string& lbl) {
+      ContextMenuItem item;
+      item.label = lbl;
+      item.enabled_condition = []() { return false; };
+      return item;
+    }
+    
+    // Helper to create conditional item
+    static ContextMenuItem Conditional(const std::string& lbl, std::function<void()> cb,
+                                      std::function<bool()> condition) {
+      ContextMenuItem item;
+      item.label = lbl;
+      item.callback = std::move(cb);
+      item.enabled_condition = std::move(condition);
+      return item;
+    }
   };
   
   // BPP format UI components
@@ -311,6 +335,10 @@ class Canvas {
   void SetGlobalScale(float scale) { config_.global_scale = scale; }
   bool* GetCustomLabelsEnabled() { return &config_.enable_custom_labels; }
   float GetGridStep() const { return config_.grid_step; }
+  
+  // Rectangle selection boundary control (prevents wrapping in large maps)
+  void SetClampRectToLocalMaps(bool clamp) { config_.clamp_rect_to_local_maps = clamp; }
+  bool GetClampRectToLocalMaps() const { return config_.clamp_rect_to_local_maps; }
   float GetCanvasWidth() const { return config_.canvas_size.x; }
   float GetCanvasHeight() const { return config_.canvas_size.y; }
   
@@ -333,7 +361,19 @@ class Canvas {
   void DrawBitmap(Bitmap &bitmap, int x_offset, int y_offset, float scale = 1.0f, int alpha = 255);
   void DrawBitmap(Bitmap &bitmap, ImVec2 dest_pos, ImVec2 dest_size, ImVec2 src_pos, ImVec2 src_size);
   void DrawBitmapTable(const BitmapTable &gfx_bin);
-  void DrawBitmapGroup(std::vector<int> &group, gfx::Tilemap &tilemap, int tile_size, float scale = 1.0f);
+  /**
+   * @brief Draw group of bitmaps for multi-tile selection preview
+   * @param group Vector of tile IDs to draw
+   * @param tilemap Tilemap containing the tiles
+   * @param tile_size Size of each tile (default 16)
+   * @param scale Rendering scale (default 1.0)
+   * @param local_map_size Size of local map in pixels (default 512 for standard maps)
+   * @param total_map_size Total map size for boundary clamping (default 4096x4096)
+   */
+  void DrawBitmapGroup(std::vector<int> &group, gfx::Tilemap &tilemap, 
+                      int tile_size, float scale = 1.0f,
+                      int local_map_size = 0x200,
+                      ImVec2 total_map_size = ImVec2(0x1000, 0x1000));
   bool DrawTilemapPainter(gfx::Tilemap &tilemap, int current_tile);
   void DrawSelectRect(int current_map, int tile_size = 0x10, float scale = 1.0f);
   bool DrawTileSelector(int size, int size_y = 0);

src/app/gui/canvas_utils.h

@@ -20,6 +20,7 @@ struct CanvasConfig {
   bool enable_context_menu = true;
   bool is_draggable = false;
   bool auto_resize = false;
+  bool clamp_rect_to_local_maps = true;  // NEW: Prevent rectangle wrap across 512x512 boundaries
   float grid_step = 32.0f;
   float global_scale = 1.0f;
   ImVec2 canvas_size = ImVec2(0, 0);