canvas.h

Go to the documentation of this file.

#ifndef YAZE_GUI_CANVAS_H
#define YAZE_GUI_CANVAS_H
 
#include "app/gfx/render/tilemap.h"
#define IMGUI_DEFINE_MATH_OPERATORS
 
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
#include "absl/types/span.h"
#include "app/gfx/core/bitmap.h"
#include "app/gfx/util/bpp_format_manager.h"
#include "app/gui/canvas/bpp_format_ui.h"
#include "app/gui/canvas/canvas_context_menu.h"
#include "app/gui/canvas/canvas_geometry.h"
#include "app/gui/canvas/canvas_interaction_handler.h"
#include "app/gui/canvas/canvas_menu.h"
#include "app/gui/canvas/canvas_modals.h"
#include "app/gui/canvas/canvas_performance_integration.h"
#include "app/gui/canvas/canvas_popup.h"
#include "app/gui/canvas/canvas_rendering.h"
#include "app/gui/canvas/canvas_state.h"
#include "app/gui/canvas/canvas_usage_tracker.h"
#include "app/gui/canvas/canvas_utils.h"
#include "app/gui/widgets/palette_editor_widget.h"
#include "rom/rom.h"
#include "zelda3/game_data.h"
#include "imgui/imgui.h"
 
namespace yaze {
 
namespace gui {
 
// Forward declarations (full includes would cause circular dependency or bloat)
class CanvasAutomationAPI;
struct CanvasExtensions;
 
using gfx::Bitmap;
using gfx::BitmapTable;
 
enum class CanvasType { kTile, kBlock, kMap };
enum class CanvasMode { kPaint, kSelect };
enum class CanvasGridSize { k8x8, k16x16, k32x32, k64x64 };
 
struct CanvasRuntime {
  ImDrawList* draw_list = nullptr;
  ImVec2 canvas_p0 = ImVec2(0, 0);
  ImVec2 canvas_sz = ImVec2(0, 0);
  ImVec2 scrolling = ImVec2(0, 0);
  ImVec2 mouse_pos_local = ImVec2(0, 0);
  bool hovered = false;
  float grid_step = 16.0f;
  float scale = 1.0f;
  ImVec2 content_size = ImVec2(0, 0);
};
 
struct CanvasFrameOptions {
  ImVec2 canvas_size = ImVec2(0, 0);
  bool draw_context_menu = true;
  bool draw_grid = true;
  std::optional<float> grid_step;
  bool draw_overlay = true;
  bool render_popups = true;
  // When true, wraps canvas in ImGui::BeginChild for scrollable container
  // Default false to match legacy DrawBackground behavior
  bool use_child_window = false;
  // Only applies when use_child_window is true
  bool show_scrollbar = false;
};
 
struct BitmapPreviewOptions {
  ImVec2 canvas_size = ImVec2(0, 0);
  ImVec2 dest_pos = ImVec2(0, 0);
  ImVec2 dest_size = ImVec2(0, 0);
  ImVec2 src_pos = ImVec2(0, 0);
  ImVec2 src_size = ImVec2(0, 0);
  float scale = 1.0f;
  int alpha = 255;
  bool draw_context_menu = false;
  bool draw_grid = true;
  std::optional<float> grid_step;
  bool draw_overlay = true;
  bool render_popups = true;
  bool ensure_texture = false;
  int selector_tile_size = 0;
  int selector_tile_size_y = 0;
};
 
struct TileHit {
  int tile_index = -1;
  ImVec2 tile_origin = ImVec2(0, 0);
  ImVec2 tile_size = ImVec2(0, 0);
};
 
struct BitmapDrawOpts {
  ImVec2 dest_pos = ImVec2(0, 0);
  ImVec2 dest_size = ImVec2(0, 0);
  ImVec2 src_pos = ImVec2(0, 0);
  ImVec2 src_size = ImVec2(0, 0);
  float scale = 1.0f;
  int alpha = 255;
  bool ensure_texture = true;
};
 
struct SelectorPanelOpts {
  ImVec2 canvas_size = ImVec2(0, 0);
  float grid_step = 16.0f;
  bool show_grid = true;
  bool show_overlay = true;
  bool render_popups = true;
  bool ensure_texture = true;
  int tile_selector_size = 0;
  int tile_selector_size_y = 0;
};
 
struct PreviewPanelOpts {
  ImVec2 canvas_size = ImVec2(0, 0);
  ImVec2 dest_pos = ImVec2(0, 0);
  ImVec2 dest_size = ImVec2(0, 0);
  float grid_step = 0.0f;  // 0 = no grid
  bool render_popups = false;
  bool ensure_texture = true;
};
 
struct ZoomToFitResult {
  float scale;
  ImVec2 scroll;
};
 
class Canvas {
 public:
  // Default constructor
  Canvas();
  ~Canvas();
 
  void Init(const CanvasConfig& config);
  void Init(const std::string& id, ImVec2 canvas_size = ImVec2(0, 0));
 
  // COMPAT: Legacy constructors - prefer default ctor + Init() for new code
  [[deprecated("Use default ctor + Init(id, size) instead")]]
  explicit Canvas(const std::string& id);
  [[deprecated("Use default ctor + Init(id, size) instead")]]
  explicit Canvas(const std::string& id, ImVec2 canvas_size);
  [[deprecated("Use default ctor + Init(config) instead")]]
  explicit Canvas(const std::string& id, ImVec2 canvas_size,
                  CanvasGridSize grid_size);
  [[deprecated("Use default ctor + Init(config) instead")]]
  explicit Canvas(const std::string& id, ImVec2 canvas_size,
                  CanvasGridSize grid_size, float global_scale);
 
  // COMPAT: Legacy constructors with renderer - prefer default ctor + Init()
  [[deprecated("Use default ctor + SetRenderer() + Init() instead")]]
  explicit Canvas(gfx::IRenderer* renderer);
  [[deprecated("Use default ctor + SetRenderer() + Init(id, size) instead")]]
  explicit Canvas(gfx::IRenderer* renderer, const std::string& id);
  [[deprecated("Use default ctor + SetRenderer() + Init(id, size) instead")]]
  explicit Canvas(gfx::IRenderer* renderer, const std::string& id,
                  ImVec2 canvas_size);
  [[deprecated("Use default ctor + SetRenderer() + Init(config) instead")]]
  explicit Canvas(gfx::IRenderer* renderer, const std::string& id,
                  ImVec2 canvas_size, CanvasGridSize grid_size);
  [[deprecated("Use default ctor + SetRenderer() + Init(config) instead")]]
  explicit Canvas(gfx::IRenderer* renderer, const std::string& id,
                  ImVec2 canvas_size, CanvasGridSize grid_size,
                  float global_scale);
 
  // Set renderer after construction (for late initialization)
  void SetRenderer(gfx::IRenderer* renderer) { renderer_ = renderer; }
  gfx::IRenderer* renderer() const { return renderer_; }
 
  // COMPAT: prefer CanvasFrameOptions.grid_step for per-frame grid control
  void SetGridSize(CanvasGridSize grid_size) {
    switch (grid_size) {
      case CanvasGridSize::k8x8:
        config_.grid_step = 8.0f;
        break;
      case CanvasGridSize::k16x16:
        config_.grid_step = 16.0f;
        break;
      case CanvasGridSize::k32x32:
        config_.grid_step = 32.0f;
        break;
      case CanvasGridSize::k64x64:
        config_.grid_step = 64.0f;
        break;
    }
    custom_step_ = config_.grid_step;
  }
 
  // COMPAT: prefer CanvasFrameOptions.grid_step for per-frame grid control
  void SetCustomGridStep(float step) {
    config_.grid_step = step;
    custom_step_ = step;
  }
 
  // COMPAT: prefer CanvasFrameOptions.grid_step for per-frame grid control
  void SetCanvasGridSize(CanvasGridSize grid_size) { SetGridSize(grid_size); }
 
  CanvasGridSize grid_size() const {
    if (config_.grid_step == 8.0f)
      return CanvasGridSize::k8x8;
    if (config_.grid_step == 16.0f)
      return CanvasGridSize::k16x16;
    if (config_.grid_step == 32.0f)
      return CanvasGridSize::k32x32;
    if (config_.grid_step == 64.0f)
      return CanvasGridSize::k64x64;
    return CanvasGridSize::k16x16;  // Default
  }
 
  void UpdateColorPainter(gfx::IRenderer* renderer, gfx::Bitmap& bitmap,
                          const ImVec4& color,
                          const std::function<void()>& event, int tile_size,
                          float scale = 1.0f);
 
  void UpdateInfoGrid(ImVec2 bg_size, float grid_size = 64.0f,
                      int label_id = 0);
 
  // ==================== Modern ImGui-Style Interface ====================
 
  void Begin(ImVec2 canvas_size = ImVec2(0, 0));
  void Begin(const CanvasFrameOptions& options);
 
  void End();
  void End(const CanvasFrameOptions& options);
 
  // ==================== Legacy Interface (Backward Compatible)
  // ====================
 
  // Background for the Canvas represents region without any content drawn to
  // it, but can be controlled by the user.
  void DrawBackground(ImVec2 canvas_size = ImVec2(0, 0));
 
  // Context Menu refers to what happens when the right mouse button is pressed
  // This routine also handles the scrolling for the canvas.
  void DrawContextMenu();
 
  // Phase 4: Use unified menu item definition from canvas_menu.h
  using CanvasMenuItem = gui::CanvasMenuItem;
 
  // Enhanced canvas components (non-optional, used every frame)
  std::unique_ptr<CanvasContextMenu> context_menu_;
  std::shared_ptr<CanvasUsageTracker> usage_tracker_;
  std::shared_ptr<CanvasPerformanceIntegration> performance_integration_;
  CanvasInteractionHandler interaction_handler_;
 
  void AddContextMenuItem(const gui::CanvasMenuItem& item);
  void ClearContextMenuItems();
 
  // Phase 4: Access to editor-provided menu definition
  CanvasMenuDefinition& editor_menu() { return editor_menu_; }
  const CanvasMenuDefinition& editor_menu() const { return editor_menu_; }
  void SetContextMenuEnabled(bool enabled) { context_menu_enabled_ = enabled; }
  void SetShowBuiltinContextMenu(bool show) {
    config_.show_builtin_context_menu = show;
  }
 
  // Persistent popup management for context menu actions
  void OpenPersistentPopup(const std::string& popup_id,
                           std::function<void()> render_callback);
  void ClosePersistentPopup(const std::string& popup_id);
  void RenderPersistentPopups();
 
  // Popup registry access (Phase 3: for advanced users and testing)
  PopupRegistry& GetPopupRegistry() { return popup_registry_; }
  const PopupRegistry& GetPopupRegistry() const { return popup_registry_; }
 
  // Enhanced view and edit operations
  void ShowAdvancedCanvasProperties();
  void ShowScalingControls();
  void SetZoomToFit(const gfx::Bitmap& bitmap);
  void ResetView();
  void ApplyConfigSnapshot(const CanvasConfig& snapshot);
  void ApplyScaleSnapshot(const CanvasConfig& snapshot);
 
  // Modular component access
  CanvasConfig& GetConfig() { return config_; }
  const CanvasConfig& GetConfig() const { return config_; }
  CanvasSelection& GetSelection() { return selection_; }
  const CanvasSelection& GetSelection() const { return selection_; }
 
  // Enhanced palette management
  void InitializePaletteEditor(Rom* rom);
  void ShowPaletteEditor();
  void ShowColorAnalysis();
  bool ApplyROMPalette(int group_index, int palette_index);
 
  // BPP format management
  void ShowBppFormatSelector();
  void ShowBppAnalysis();
  void ShowBppConversionDialog();
  bool ConvertBitmapFormat(gfx::BppFormat target_format);
  gfx::BppFormat GetCurrentBppFormat() const;
 
  // Enhanced canvas management
  void InitializeEnhancedComponents();
  void SetUsageMode(CanvasUsage usage);
  auto usage_mode() const { return config_.usage_mode; }
 
  void RecordCanvasOperation(const std::string& operation_name, double time_ms);
  void ShowPerformanceUI();
  void ShowUsageReport();
 
  // Interaction handler access
  CanvasInteractionHandler& GetInteractionHandler() {
    return interaction_handler_;
  }
  const CanvasInteractionHandler& GetInteractionHandler() const {
    return interaction_handler_;
  }
 
  // Automation API access (Phase 4A)
  CanvasAutomationAPI* GetAutomationAPI();
 
  // Initialization and cleanup
  void InitializeDefaults();
  void Cleanup();
 
  // Size reporting for ImGui table integration
  ImVec2 GetMinimumSize() const;
  ImVec2 GetPreferredSize() const;
  ImVec2 GetCurrentSize() const { return config_.canvas_size; }
  void SetAutoResize(bool auto_resize) { config_.auto_resize = auto_resize; }
  bool IsAutoResize() const { return config_.auto_resize; }
 
  // Table integration helpers
  void ReserveTableSpace(const std::string& label = "");
  bool BeginTableCanvas(const std::string& label = "");
  void EndTableCanvas();
 
  CanvasRuntime BeginInTable(const std::string& label,
                             const CanvasFrameOptions& options);
  void EndInTable(CanvasRuntime& runtime, const CanvasFrameOptions& options);
 
  // Improved interaction detection
  bool HasValidSelection() const;
  bool WasClicked(ImGuiMouseButton button = ImGuiMouseButton_Left) const;
  bool WasDoubleClicked(ImGuiMouseButton button = ImGuiMouseButton_Left) const;
  ImVec2 GetLastClickPosition() const;
 
  // Tile painter methods
  bool DrawTilePainter(const Bitmap& bitmap, int size, float scale = 1.0f);
  bool DrawSolidTilePainter(const ImVec4& color, int size);
  void DrawTileOnBitmap(int tile_size, gfx::Bitmap* bitmap, ImVec4 color);
 
  void DrawOutline(int x, int y, int w, int h);
  void DrawOutlineWithColor(int x, int y, int w, int h, ImVec4 color);
  void DrawOutlineWithColor(int x, int y, int w, int h, uint32_t color);
 
  void DrawRect(int x, int y, int w, int h, ImVec4 color);
 
  void DrawText(const std::string& text, int x, int y);
  void DrawGridLines(float grid_step);
 
  void DrawInfoGrid(float grid_step = 64.0f, int tile_id_offset = 8,
                    int label_id = 0);
 
  void DrawLayeredElements();
 
  int GetTileIdFromMousePos() {
    float x = mouse_pos_in_canvas_.x;
    float y = mouse_pos_in_canvas_.y;
    float step = custom_step_ != 0.0f ? custom_step_ : config_.grid_step;
    float scale = config_.global_scale != 0.0f ? config_.global_scale : 1.0f;
    if (step <= 0.0f) {
      return -1;
    }
    int num_columns = (canvas_sz_.x / scale) / step;
    int num_rows = (canvas_sz_.y / scale) / step;
    if (num_columns <= 0 || num_rows <= 0) {
      return -1;
    }
    int tile_id =
        static_cast<int>((x / step) + (y / step) * static_cast<float>(num_columns));
    if (tile_id >= num_columns * num_rows) {
      tile_id = -1;  // Invalid tile ID
    }
    return tile_id;
  }
  void DrawCustomHighlight(float grid_step);
  bool IsMouseHovering() const { return is_hovered_; }
  void ZoomIn();
  void ZoomOut();
 
  // Points accessors - points_ is maintained separately for custom overlay
  // drawing
  const ImVector<ImVec2>& points() const { return points_; }
  ImVector<ImVec2>* mutable_points() { return &points_; }
  auto push_back(ImVec2 pos) { points_.push_back(pos); }
  auto draw_list() const { return draw_list_; }
  auto zero_point() const { return canvas_p0_; }
  ImVec2 ToCanvasPos(ImVec2 local) const;
  auto scrolling() const { return scrolling_; }
  void set_scrolling(ImVec2 scroll) {
    scrolling_ = scroll;
    config_.scrolling = scroll;  // Sync to config for persistence
  }
  auto drawn_tile_position() const { return drawn_tile_pos_; }
  auto canvas_size() const { return canvas_sz_; }
  // COMPAT: prefer CanvasRuntime.scale for per-frame scale control
  void set_global_scale(float scale);
  void set_draggable(bool draggable) { draggable_ = draggable; }
 
  // Modern accessors using modular structure
  bool IsSelectRectActive() const { return select_rect_active_; }
  const std::vector<ImVec2>& GetSelectedTiles() const {
    return selected_tiles_;
  }
  ImVec2 GetSelectedTilePos() const { return selected_tile_pos_; }
  void SetSelectedTilePos(ImVec2 pos) { selected_tile_pos_ = pos; }
 
  // Configuration accessors
  // COMPAT: prefer CanvasFrameOptions.canvas_size for per-frame size control
  void SetCanvasSize(ImVec2 canvas_size) {
    config_.canvas_size = canvas_size;
    config_.custom_canvas_size = true;
  }
  float GetGlobalScale() const { return config_.global_scale; }
  // COMPAT: prefer CanvasRuntime.scale for per-frame scale control
  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; }
 
  // Legacy compatibility accessors
  auto select_rect_active() const { return select_rect_active_; }
  auto selected_tiles() const { return selected_tiles_; }
  auto selected_tile_pos() const { return selected_tile_pos_; }
  void set_selected_tile_pos(ImVec2 pos) { selected_tile_pos_ = pos; }
  auto global_scale() const { return config_.global_scale; }
  auto custom_labels_enabled() { return &config_.enable_custom_labels; }
  auto custom_step() const { return config_.grid_step; }
  auto width() const { return config_.canvas_size.x; }
  auto height() const { return config_.canvas_size.y; }
 
  // Public accessors for methods that need to be accessed externally
  auto canvas_id() const { return canvas_id_; }
 
  // Public methods for drawing operations
  void DrawBitmap(Bitmap& bitmap, int border_offset, float scale);
  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,
                       int local_map_size = 0x200,
                       ImVec2 total_map_size = ImVec2(0x1000, 0x1000));
  void DrawBitmapPreview(Bitmap& bitmap,
                         const BitmapPreviewOptions& options);
  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);
  void DrawGrid(float grid_step = 64.0f, int tile_id_offset = 8);
  void DrawOverlay();
  auto labels(int i) {
    if (i >= labels_.size()) {
      labels_.push_back(ImVector<std::string>());
    }
    return labels_[i];
  }
  auto mutable_labels(int i) {
    if (i >= labels_.size()) {
      int x = i;
      while (x >= labels_.size()) {
        labels_.push_back(ImVector<std::string>());
        x--;
      }
      labels_.push_back(ImVector<std::string>());
    }
    return &labels_[i];
  }
 
  auto set_current_labels(int i) { current_labels_ = i; }
  auto set_highlight_tile_id(int i) { highlight_tile_id = i; }
 
  auto mutable_selected_tiles() { return &selected_tiles_; }
  auto mutable_selected_points() { return &selected_points_; }
  auto selected_points() const { return selected_points_; }
 
  auto hover_mouse_pos() const { return mouse_pos_in_canvas_; }
 
  void set_rom(Rom* rom) { rom_ = rom; }
  Rom* rom() const { return rom_; }
  void SetGameData(zelda3::GameData* game_data);
  zelda3::GameData* game_data() const { return game_data_; }
 
  void AddImageAt(ImTextureID texture, ImVec2 local_top_left, ImVec2 size);
  void AddRectFilledAt(ImVec2 local_top_left, ImVec2 size, uint32_t color);
  void AddTextAt(ImVec2 local_pos, const std::string& text, uint32_t color);
 
 private:
  void DrawContextMenuItem(const gui::CanvasMenuItem& item);
 
  // Helper to build CanvasRuntime from current state (for delegation to
  // stateless helpers)
  CanvasRuntime BuildCurrentRuntime() const {
    CanvasRuntime rt;
    rt.draw_list = draw_list_;
    rt.canvas_p0 = canvas_p0_;
    rt.canvas_sz = canvas_sz_;
    rt.scrolling = scrolling_;
    rt.mouse_pos_local = mouse_pos_in_canvas_;
    rt.hovered = is_hovered_;
    rt.grid_step = custom_step_;
    rt.scale = global_scale_;
    rt.content_size = config_.content_size;
    return rt;
  }
 
  // Modular configuration and state
  gfx::IRenderer* renderer_ = nullptr;
  CanvasConfig config_;
  CanvasSelection selection_;
 
  // Phase 4: Optional extensions (lazy-initialized on first use)
  // Contains: bpp_format_ui, bpp_conversion_dialog, bpp_comparison_tool,
  //           modals, palette_editor, automation_api
  std::unique_ptr<CanvasExtensions> extensions_;
  CanvasExtensions& EnsureExtensions();
 
  // Phase 1: Consolidated state (gradually replacing scattered members)
  CanvasState state_;
 
  // Core canvas state
  bool is_hovered_ = false;
  bool refresh_graphics_ = false;
 
  // Phase 4: Context menu system (declarative menu definition)
  CanvasMenuDefinition editor_menu_;
  bool context_menu_enabled_ = true;
 
  // Phase 4: Persistent popup state for context menu actions (unified registry)
  PopupRegistry popup_registry_;
 
  // Legacy members (to be gradually replaced)
  int current_labels_ = 0;
  int highlight_tile_id = -1;
  uint16_t edit_palette_index_ = 0;
  uint64_t edit_palette_group_name_index_ = 0;
  uint64_t edit_palette_sub_index_ = 0;
 
  // Core canvas state
  Bitmap* bitmap_ = nullptr;
  Rom* rom_ = nullptr;
  zelda3::GameData* game_data_ = nullptr;
  ImDrawList* draw_list_ = nullptr;
 
  // Canvas geometry and interaction state
  ImVec2 scrolling_;
  ImVec2 canvas_sz_;
  ImVec2 canvas_p0_;
  ImVec2 canvas_p1_;
  ImVec2 drawn_tile_pos_;
  ImVec2 mouse_pos_in_canvas_;
 
  // Drawing and labeling
  // NOTE: points_ synchronized from interaction_handler_ for backward
  // compatibility
  ImVector<ImVec2> points_;
  ImVector<ImVector<std::string>> labels_;
 
  // Identification
  std::string canvas_id_ = "Canvas";
  std::string context_id_ = "CanvasContext";
 
  // Legacy compatibility (gradually being replaced by selection_)
  std::vector<ImVec2> selected_tiles_;
  ImVector<ImVec2> selected_points_;
  ImVec2 selected_tile_pos_ = ImVec2(-1, -1);
  bool select_rect_active_ = false;
  float custom_step_ = 32.0f;
  float global_scale_ = 1.0f;
  bool enable_grid_ = true;
  bool enable_hex_tile_labels_ = false;
  bool enable_custom_labels_ = false;
  bool enable_context_menu_ = true;
  bool custom_canvas_size_ = false;
  bool draggable_ = false;
};
 
void BeginCanvas(Canvas& canvas, ImVec2 child_size = ImVec2(0, 0));
void EndCanvas(Canvas& canvas);
 
void GraphicsBinCanvasPipeline(int width, int height, int tile_size,
                               int num_sheets_to_load, int canvas_id,
                               bool is_loaded, BitmapTable& graphics_bin);
 
void BitmapCanvasPipeline(gui::Canvas& canvas, gfx::Bitmap& bitmap, int width,
                          int height, int tile_size, bool is_loaded,
                          bool scrollbar, int canvas_id);
 
// Table-optimized canvas pipeline with automatic sizing
void TableCanvasPipeline(gui::Canvas& canvas, gfx::Bitmap& bitmap,
                         const std::string& label = "",
                         bool auto_resize = true);
 
// ---------- Optional helper APIs ----------
CanvasRuntime BeginCanvas(gui::Canvas& canvas,
                          const CanvasFrameOptions& options);
void EndCanvas(gui::Canvas& canvas, CanvasRuntime& runtime,
               const CanvasFrameOptions& options);
 
// New Stateless Drawing Helpers (CanvasRuntime-based)
void DrawBitmap(const CanvasRuntime& rt, gfx::Bitmap& bitmap, int border_offset = 2, float scale = 1.0f);
void DrawBitmap(const CanvasRuntime& rt, gfx::Bitmap& bitmap, int x_offset, int y_offset, float scale = 1.0f, int alpha = 255);
void DrawBitmap(const CanvasRuntime& rt, gfx::Bitmap& bitmap, ImVec2 dest_pos, ImVec2 dest_size, ImVec2 src_pos, ImVec2 src_size);
void DrawBitmap(const CanvasRuntime& rt, gfx::Bitmap& bitmap, const BitmapDrawOpts& opts);
 
// New Stateless Preview Helpers
void DrawBitmapPreview(const CanvasRuntime& rt, gfx::Bitmap& bitmap, const BitmapPreviewOptions& options);
bool RenderPreviewPanel(const CanvasRuntime& rt, gfx::Bitmap& bmp, const PreviewPanelOpts& opts);
 
bool DrawTilemapPainter(const CanvasRuntime& rt, gfx::Tilemap& tilemap, int current_tile, ImVec2* out_drawn_pos);
bool DrawTileSelector(const CanvasRuntime& rt, int size, int size_y, ImVec2* out_selected_pos);
void DrawSelectRect(const CanvasRuntime& rt, int current_map, int tile_size, float scale, CanvasSelection& selection);
 
TileHit TileIndexAt(const ImVec2& local_pos, float grid_step, float scale,
                    const ImVec2& canvas_px);
 
void DrawTileOutline(const CanvasRuntime& rt, const ImVec2& tile_pos_px,
                     const ImVec2& tile_size_px, ImU32 color);
void DrawTileHighlight(const CanvasRuntime& rt, const ImVec2& tile_pos_px,
                       const ImVec2& tile_size_px, ImU32 color);
void DrawTileLabel(const CanvasRuntime& rt, const ImVec2& tile_pos_px,
                   const char* text, ImU32 color);
 
// Stateless DrawRect/DrawText helpers (CanvasRuntime-based)
void DrawRect(const CanvasRuntime& rt, int x, int y, int w, int h,
              ImVec4 color);
void DrawText(const CanvasRuntime& rt, const std::string& text, int x, int y);
void DrawOutline(const CanvasRuntime& rt, int x, int y, int w, int h,
                 ImU32 color = IM_COL32(255, 255, 255, 200));
 
bool DrawBitmap(gui::Canvas& canvas, CanvasRuntime& rt, gfx::Bitmap& bmp,
                const BitmapDrawOpts& opts);
 
bool DrawTilemapRegion(gui::Canvas& canvas, CanvasRuntime& rt,
                       gfx::Tilemap& tilemap, absl::Span<const int> tile_ids,
                       int tile_size, float scale, ImVec2 clamp_px);
 
bool RenderSelectorPanel(gui::Canvas& canvas, gfx::Bitmap& bmp,
                         const SelectorPanelOpts& opts, TileHit* out_hit);
 
bool RenderPreviewPanel(gui::Canvas& canvas, gfx::Bitmap& bmp,
                        const PreviewPanelOpts& opts);
 
ZoomToFitResult ComputeZoomToFit(ImVec2 content_px, ImVec2 canvas_px,
                                 float padding_px);
ImVec2 ClampScroll(ImVec2 scroll, ImVec2 content_px, ImVec2 canvas_px);
 
struct CanvasMenuAction {
  std::string id;
  std::string label;
  std::string shortcut;
  std::function<bool()> enabled;
  std::function<void()> on_click;
};
 
class CanvasMenuActionHost {
 public:
  void Clear() { items_.clear(); }
  void AddItem(CanvasMenuAction item) { items_.push_back(std::move(item)); }
  absl::Span<const CanvasMenuAction> items() const { return items_; }
  const std::string& popup_id() const { return popup_id_; }
  void set_popup_id(std::string id) { popup_id_ = std::move(id); }
 
 private:
  std::vector<CanvasMenuAction> items_;
  std::string popup_id_ = "CanvasMenuHost";
};
 
void RegisterDefaultCanvasMenu(CanvasMenuActionHost& host,
                               const CanvasRuntime& rt, CanvasConfig& cfg);
void RenderContextMenu(CanvasMenuActionHost& host, const CanvasRuntime& rt,
                       CanvasConfig& cfg);
 
class ScopedCanvas {
 public:
  explicit ScopedCanvas(const std::string& id,
                        ImVec2 canvas_size = ImVec2(0, 0))
      : canvas_(new Canvas(id, canvas_size)), owned_(true), active_(true) {
    canvas_->Begin();
  }
 
  explicit ScopedCanvas(gfx::IRenderer* renderer, const std::string& id,
                        ImVec2 canvas_size = ImVec2(0, 0))
      : canvas_(new Canvas(renderer, id, canvas_size)),
        owned_(true),
        active_(true) {
    canvas_->Begin();
  }
 
  explicit ScopedCanvas(Canvas& canvas)
      : canvas_(&canvas), owned_(false), active_(true) {
    canvas_->Begin();
  }
 
  ~ScopedCanvas() {
    if (active_ && canvas_) {
      canvas_->End();
    }
    if (owned_) {
      delete canvas_;
    }
  }
 
  // No copy, move only
  ScopedCanvas(const ScopedCanvas&) = delete;
  ScopedCanvas& operator=(const ScopedCanvas&) = delete;
 
  ScopedCanvas(ScopedCanvas&& other) noexcept
      : canvas_(other.canvas_), owned_(other.owned_), active_(other.active_) {
    other.active_ = false;
    other.canvas_ = nullptr;
  }
 
  Canvas* operator->() { return canvas_; }
  const Canvas* operator->() const { return canvas_; }
 
  Canvas& operator*() { return *canvas_; }
  const Canvas& operator*() const { return *canvas_; }
 
  Canvas* get() { return canvas_; }
  const Canvas* get() const { return canvas_; }
 
 private:
  Canvas* canvas_;
  bool owned_;
  bool active_;
};
 
class CanvasFrame {
 public:
  CanvasFrame(Canvas& canvas,
              CanvasFrameOptions options = CanvasFrameOptions());
  ~CanvasFrame();
 
  CanvasFrame(const CanvasFrame&) = delete;
  CanvasFrame& operator=(const CanvasFrame&) = delete;
 
  CanvasFrame(CanvasFrame&& other) noexcept;
  CanvasFrame& operator=(CanvasFrame&& other) noexcept;
 
  Canvas* operator->() { return canvas_; }
  const Canvas* operator->() const { return canvas_; }
 
 private:
  Canvas* canvas_;
  CanvasFrameOptions options_;
  bool active_;
};
 
}  // namespace gui
}  // namespace yaze
 
#endif