gui_application.h

Go to the documentation of this file.

#pragma once
 
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <unordered_map>
#include <unordered_set>
#include <variant>
#include <vector>
#include <cassert>
#include <source_location>
#include <span>
#include <functional>
#include <initializer_list>
#include <limits>
#include <string>
#include <utility>
 
#include <gui_core/frame/gui_frame_clock.h>
#include <gui_core/graphics/gui_graphics_context.h>
#include <gui_core/graphics/gui_renderer.h>
 
#include <gui_core/text/gui_clipboard.h>
#include <gui_core/text/skribidi/gui_text_system_skribidi.h>
#include <gui_core/text/gui_text_system.h>
#include <gui_core/text/gui_text_atlas_manager.h>
 
#include <gui_core/windows/gui_os_window_manager.h>
#include <gui_core/windows/gui_window_registry.h>
#include <gui_core/windows/gui_window_backend.h>
#include <gui_core/windows/gui_image_window_backend.h>
 
#include <gui_core/style/gui_style.h>
#include <gui_core/style/gui_gradient_manager.h>
#include <gui_core/style/gui_style_manager.h>
 
#include <gui_core/input/gui_input_state.h>
#include <gui_core/input/gui_input_manager.h>
#include <gui_core/input/gui_command_manager.h>
#include <gui_core/input/gui_input_handler_func.h>
#include <gui_core/input/gui_input_handler_broadcaster.h>
 
#include <gui_core/layout/gui_layout_engine.h>
 
#include <gui_core/elements/gui_element_storage.h>
 
#include <gui_core/graphics/gui_custom_draw_context.h>
 
#include <gui_core/state/gui_state_manager.h>
#include <gui_core/state/gui_tab_chain_manager.h>
 
#include <gui_core/frame/gui_frame_pipeline.h>
 
#include <gui_core/gui_id_manager.h>
 
#include <gui_controls/gui_transition_manager.h>
#include <gui_controls/gui_type_dimensions.h>
#include <gui_controls/gui_default_handlers.h>
#include <gui_controls/gui_tooltip_manager.h>
#include <gui_controls/gui_menu_manager.h>
#include <gui_controls/gui_dock_node.h>
#include <gui_controls/gui_table_helpers.h>
#include <gui_controls/gui_theme.h>
#include <gui_controls/gui_content.h>
#include <gui_controls/controls_toolbar_dock.h>
#include <gui_core/gui_result.h>
 
#include <gui_controls/gui_widget_state_types.h>
#include <gui_controls/gui_node_view_types.h>
#include <gui_controls/gui_table_types.h>
#include <gui_controls/gui_tree_grid_types.h>
#include <gui_controls/gui_docking_types.h>
#include <gui_controls/gui_notification_types.h>
 
#include <gui_controls/subsystems/gui_subsystem_state.h>
#include <gui_controls/subsystems/gui_label_group_subsystem.h>
#include <gui_controls/subsystems/gui_button_group_subsystem.h>
#include <gui_controls/subsystems/gui_color_picker_subsystem.h>
#include <gui_controls/subsystems/gui_gradient_editor_subsystem.h>
#include <gui_controls/subsystems/gui_reorderable_subsystem.h>
#include <gui_controls/subsystems/gui_ui_cache_subsystem.h>
 
namespace tachyon
{

    void VERIFY(ElementStorageResult result);
    void VERIFY(RegistryResult result);

    void VERIFY(AddWindowResult result);
    void VERIFY(RequestCloseResult result);
 
 
    // ---- MessageDialog: a modal question (GUIApplication::MessageDialog) ----
    enum class MessageIcon : uint8_t { Warning, Quit, Question, Info, Error };
    enum class MessageButtonKind : uint8_t { Secondary, Primary, Danger };

    struct MessageButton
    {
        std::string_view  label;
        MessageButtonKind kind      = MessageButtonKind::Secondary;   
        bool              alignLeft = false;   
    };

    struct MessageDialogItem
    {
        std::string_view name;             
        std::string_view meta;             
        color4f          color {};         
        bool*            checked = nullptr;   
    };

    struct MessageDialogDesc
    {
        MessageIcon                        icon = MessageIcon::Question;   
        std::string_view                   title;      
        std::string_view                   message;    
        std::span<const MessageButton>     buttons;    
        int                                defaultButton = 0;    
        int                                cancelButton  = -1;   
        std::span<const MessageDialogItem> items;      
        bool*                              dontAskAgain = nullptr;   
        std::string_view                   details;    
    };
 
    // Outside GUIApplication: GCC can't use a nested struct's member initializers in a
    // default argument of the class being defined.
    struct GUIApplicationInitializeOptions
    {
        bool loadStyles             = true;  
        bool commandShortcuts       = true;  
        bool repaintWhileResizing   = true;  
        bool closeMenusOnWindowMove = true;  
        std::string_view fallbackFonts {};
    };

    class GUIApplication
    {
    public:
        std::unique_ptr<InputManager>     inputManager;
        std::unique_ptr<LayoutEngine>     layoutEngine;
        std::unique_ptr<OSWindowManager>  windowManager;
        std::unique_ptr<TextAtlasManager> textAtlasManager;
        std::unique_ptr<IClipboard>       clipboard;          

        ITextSystem*        textSystem      { nullptr };
        IWindowBackend*     windowBackend   { nullptr };   
        GraphicsContext*    graphicsContext { nullptr };   
        GUIRenderer*        guiRenderer     { nullptr };

        IDManager           idManager{};
        GUIStateManager     guiStateManager{};
        TransitionManager   transitionManager{};
        TabChainManager     tabChainManager{};

        MenuManager         menuManager{};
        TooltipManager      tooltipManager{};
 
    private:
        FramePipeline       m_frame{};
 
        std::unique_ptr<SliderFieldTrackSubsystem> m_sliderFieldTrack;
        std::unique_ptr<MenuRectsSubsystem>        m_menuRects;
        std::unique_ptr<LabelGroupSubsystem>       m_labelGroup;
        std::unique_ptr<ButtonGroupSubsystem>      m_buttonGroup;
        std::unique_ptr<ColorPickerSubsystem>      m_colorPickerSub;
        std::unique_ptr<GradientEditorSubsystem>   m_gradientEditorSub;
        std::unique_ptr<RenameSubsystem>           m_renameSub;
        std::unique_ptr<ReorderableSubsystem>      m_reorderable;
        std::unique_ptr<DockTabDragSubsystem>      m_dockTabDragSub;
        ToolbarWindowDragSubsystem                 m_toolbarWindowDrag{};
        std::unique_ptr<UICacheManager>            m_uiCache;
 
    public:

        GradientManager     gradientManager{};
        StyleManager        styleManager { gradientManager };

        ElementStorage      elementStorage { styleManager, &guiStateManager.GetElementDataStore() };
        WindowRegistry      windowRegistry {};

        CommandManager      commandManager {};

        InputHandlerBroadcaster inputBroadcaster {};

        OnGuiFunc           onGui           {};

        GUITheme theme{};
 

        bool applicationQuit = false;
        std::chrono::steady_clock::time_point m_frameStart{};
        float frameTime = 0.0f;
        float frameBuildTime = 0.0f;

        struct FrameTimingSample { float buildMs = 0.0f; float totalMs = 0.0f; };
        static constexpr int kFrameHistoryCount = 240;   

        void GetFrameTimingHistory(std::span<FrameTimingSample> out) const;

 


        void CreatePanel(std::unordered_map<tachyon::ID, tachyon::Panel>& panels, ID id, std::string title, tachyon::IconID icon,
                         std::function<void()> onPanelGUI,
                         std::string panelType = {},
                         std::function<void()> onEnable = {},
                         std::function<void()> onDisable = {});

        tachyon::ID CreatePanel(std::unordered_map<tachyon::ID, tachyon::Panel>& panels, std::string title, tachyon::IconID icon,
                            std::function<void()> onPanelGUI,
                            std::string panelType = {},
                            std::function<void()> onEnable = {},
                            std::function<void()> onDisable = {})
        {
            ID id = idManager.CreateStaticID();
            CreatePanel(panels, id, std::move(title), icon, std::move(onPanelGUI),
                        std::move(panelType), std::move(onEnable), std::move(onDisable));
            return id;
        }
 

        void DisableAllPanels(DockingLayout& layout);

        void EmitFloatingToolbarWindows(std::vector<struct FloatingToolbarItem>& floatingItems,
                                        const struct FloatingToolbarOptions* options = nullptr);

        DockLeafResult FindDockLeafAtScreenPos(tachyon::int2 screenPos);

        DockDropResult FindDockDropTargetAtScreenPos(tachyon::int2 screenPos);

        void EmitFloatingDockWindows();
        void EmitFloatingDockWindows(const DocumentSet& documents);
        bool FloatPanel(DockingLayout& layout, ID panelID, int2 screenPos);

        void CloseFloatingDockWindow(size_t index);

        void CloseDockedPanel(DockingLayout& layout, DockNode& leaf, int tabIndex);

        Document& CreateDocument(DocumentSet& set, std::string name, std::string extension, std::string kind,
                                 tachyon::IconID icon);
        void CloseDocument(DocumentSet& set, int index);

        static void TransferPanel(tachyon::ID panelID, tachyon::DockNode* sourceNode,
                                  DockingLayout* sourceLayout,
                                  DockingLayout* targetLayout);


 
                virtual ~GUIApplication() = default;

        using InitializeOptions = GUIApplicationInitializeOptions;

        virtual Result<void> Initialize(const InitializeOptions& options = {});
        virtual void Cleanup();

        Result<void> InitializeStyles();

        virtual void OnStylesReloaded() {}

        void RequestReloadTheme(std::string_view themePath, float fontScale);
        const Result<void>& ThemeReloadResult() const { return m_themeReload; }
        const std::string& GetThemePath() const { return m_themePath; }

        void SetResourceRoot(std::string_view root) { m_resourceRoot = std::string(root); }
        const std::string& GetResourceRoot() const { return m_resourceRoot; }



        void InjectMouseMove(ID windowID, int2 pos, KeyModifier mods = KeyModifier::None);
        void InjectMouseButton(ID windowID, int2 pos, MouseButtons button, bool down, KeyModifier mods = KeyModifier::None);
        void InjectMouseScroll(ID windowID, int2 pos, float2 offset, KeyModifier mods = KeyModifier::None);
        void InjectMouseLeave(ID windowID);
        void InjectFocus(ID windowID, bool focused);
        void InjectKey(ID windowID, KeyCode key, KeyAction action, KeyModifier mods = KeyModifier::None);
        void InjectText(ID windowID, std::string_view utf8);

        Result<void> ReadWindowPixels(ID windowID, std::span<uint8_t> bgra);



        void SetGraphicsBackend(std::unique_ptr<GraphicsContext> backend) { m_graphicsBackend = std::move(backend); }

        void SetWindowBackend(std::unique_ptr<IWindowBackend> backend) { m_osWindowBackend = std::move(backend); }
        void SetClipboard(std::unique_ptr<IClipboard> clipboardImpl) { clipboard = std::move(clipboardImpl); }

        void SetAllocationHooks(const AllocationHooks& hooks) { m_allocationHooks = hooks; }

        void SetStyleFiles(std::span<const std::string_view> files);
        float GetGlobalFontScale() const { return m_globalFontScale; }

        void  SetUIScale(float scale);
        float GetUIScale() const { return m_uiScale; }

        void SetReducedMotion(std::optional<bool> reduced);
        bool IsThemeCrossfading() const { return !m_crossfades.empty(); }
        bool IsReducedMotion() const { return transitionManager.IsReducedMotion(); }



        virtual void OnGUI() = 0;

        Result<void> Run();

        bool         UpdateFrame();
        Result<void> RecordFrame();
        void         PresentFrame();


 
        // ---- Event handler factories ----
        //
        // Event handlers run at END OF FRAME (input dispatch), not during OnGUI. Captures must
        // outlive the frame: user-owned pointers, GUIApplication members and copies are fine;
        // transient construction state (m_treeState, ...) and OnGUI stack locals are not.
        //
        tachyon::EventHandler MakeToggleHandler(bool& toggle);
        tachyon::EventHandler MakeButtonHandler(std::function<void()> onClick);
        tachyon::EventHandler MakeLabelHandler();

        tachyon::ElementRef RegisterElement(tachyon::Element&& element, LayoutOverride&& constraints);
        tachyon::ElementRef RegisterElement(tachyon::Element&& element, std::string_view text, LayoutOverride&& constraints);
 

        bool TakeEscapeFor(ID popupWindowID, ID triggerID);

        tachyon::ElementRef RegisterControl(tachyon::Element&& element, LayoutOverride&& constraints);
        tachyon::ElementRef RegisterControl(tachyon::Element&& element, std::string_view text, LayoutOverride&& constraints);
        tachyon::ElementRef RegisterControl(tachyon::Element&& element, std::function<TextID(tachyon::Element& element)> createTextID, LayoutOverride&& constraints);

        tachyon::ElementRef MenuItemRow(ID id, tachyon::EventHandler handler, StyleRef rowStyle,
                                    bool reserveIcon, IconID icon, std::string_view text,
                                    std::string_view trailing, StyleRef trailingStyle,
                                    LayoutOverride&& constraints, bool destructive = false);
        bool MenuItemImpl(ID id, const GUIContent& content, std::string_view shortcut,
                          std::function<void()> onClick, StyleRef style, bool destructive, LayoutOverride&& constraints);
        void ShowContentTooltip(ID id, const GUIContent& content) { if (!content.tooltip.empty()) SetTooltip(id, content.tooltip); }

        bool BeginIndeterminate() { guiStateManager.Construction().PushIndeterminate(); return true; }
        void EndIndeterminate()   { guiStateManager.Construction().PopIndeterminate(); }



        bool        Button(ID id, const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Button(ID id, const GUIContent& content, std::function<void()> onClick,                 LayoutOverride&& constraints = {}) { return Button(id,  content, std::move(onClick), theme.controls->button, std::move(constraints)); }
        inline bool Button(       const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Button(idManager.AllocateDynamicID(site), content, std::move(onClick), style, std::move(constraints)); }
        inline bool Button(       const GUIContent& content, std::function<void()> onClick,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Button(idManager.AllocateDynamicID(site), content, std::move(onClick), theme.controls->button, std::move(constraints)); }

        bool        CommandButton(CommandID command, StyleRef style, LayoutOverride&& constraints = {});
        inline bool CommandButton(CommandID command, LayoutOverride&& constraints = {}) { return CommandButton(command, theme.controls->button, std::move(constraints)); }

        bool        Checkbox(ID id, bool value, std::string_view text, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Checkbox(ID id, bool value, std::string_view text, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}) { return Checkbox(id, value, text, std::move(onToggle), theme.checkboxStyleRef, std::move(constraints)); }
        inline bool Checkbox(       bool value, std::string_view text, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Checkbox(idManager.AllocateDynamicID(site), value, text, std::move(onToggle), style, std::move(constraints)); }
        inline bool Checkbox(       bool value, std::string_view text, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Checkbox(idManager.AllocateDynamicID(site), value, text, std::move(onToggle), theme.checkboxStyleRef, std::move(constraints)); }
        inline bool Checkbox(ID id, bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {}) { return Checkbox(id, value, text, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Checkbox(ID id, bool& value, std::string_view text = {},           LayoutOverride&& constraints = {}) { return Checkbox(id, value, text, [&value](bool newValue){ value = newValue; }, theme.checkboxStyleRef, std::move(constraints)); }
        inline bool Checkbox(       bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Checkbox(idManager.AllocateDynamicID(site), value, text, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Checkbox(       bool& value, std::string_view text = {},           LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Checkbox(idManager.AllocateDynamicID(site), value, text, [&value](bool newValue){ value = newValue; }, theme.checkboxStyleRef, std::move(constraints)); }

        bool        Switch(ID id, bool value, std::string_view text, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Switch(ID id, bool value, std::string_view text, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}) { return Switch(id, value, text, std::move(onToggle), theme.switchStyleRef, std::move(constraints)); }
        inline bool Switch(       bool value, std::string_view text, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Switch(idManager.AllocateDynamicID(site), value, text, std::move(onToggle), style, std::move(constraints)); }
        inline bool Switch(       bool value, std::string_view text, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Switch(idManager.AllocateDynamicID(site), value, text, std::move(onToggle), theme.switchStyleRef, std::move(constraints)); }
        inline bool Switch(ID id, bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {}) { return Switch(id, value, text, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Switch(ID id, bool& value, std::string_view text = {},           LayoutOverride&& constraints = {}) { return Switch(id,                            value, text, [&value](bool newValue){ value = newValue; }, theme.switchStyleRef, std::move(constraints)); }
        inline bool Switch(       bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Switch(idManager.AllocateDynamicID(site), value, text, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Switch(       bool& value, std::string_view text = {},           LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Switch(idManager.AllocateDynamicID(site), value, text, [&value](bool newValue){ value = newValue; }, theme.switchStyleRef, std::move(constraints)); }

        bool        Toggle(ID id, bool value, const GUIContent& content, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Toggle(ID id, bool value, const GUIContent& content, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}) { return Toggle(id,  value, content, std::move(onToggle), theme.controls->toggle, std::move(constraints)); }
        inline bool Toggle(       bool value, const GUIContent& content, std::function<void(bool)> onToggle, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Toggle(idManager.AllocateDynamicID(site), value, content, std::move(onToggle), style, std::move(constraints)); }
        inline bool Toggle(       bool value, const GUIContent& content, std::function<void(bool)> onToggle,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Toggle(idManager.AllocateDynamicID(site), value, content, std::move(onToggle), theme.controls->toggle, std::move(constraints)); }
        inline bool Toggle(ID id, bool& value, const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {}) { return Toggle(id,  value, content, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Toggle(ID id, bool& value, const GUIContent& content,                 LayoutOverride&& constraints = {}) { return Toggle(id,  value, content, [&value](bool newValue){ value = newValue; }, theme.controls->toggle, std::move(constraints)); }
        inline bool Toggle(       bool& value, const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Toggle(idManager.AllocateDynamicID(site), value, content, [&value](bool newValue){ value = newValue; }, style, std::move(constraints)); }
        inline bool Toggle(       bool& value, const GUIContent& content,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Toggle(idManager.AllocateDynamicID(site), value, content, [&value](bool newValue){ value = newValue; }, theme.controls->toggle, std::move(constraints)); }



        bool        BeginMenu(ID id, std::string_view text, StyleRef buttonStyle, StyleRef menuStyle, StyleRef itemStyle, LayoutOverride&& constraints = {});
        inline bool BeginMenu(ID id, std::string_view text, LayoutOverride&& constraints = {}) { return BeginMenu(id, text, theme.controls->menuTrigger, theme.menuStyleRef, theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool BeginMenu(       std::string_view text, StyleRef buttonStyle, StyleRef menuStyle, StyleRef itemStyle, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginMenu(idManager.AllocateDynamicID(site), text, buttonStyle, menuStyle, itemStyle, std::move(constraints)); }
        inline bool BeginMenu(       std::string_view text, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginMenu(idManager.AllocateDynamicID(site), text, theme.controls->menuTrigger, theme.menuStyleRef, theme.menuItemRowStyleRef, std::move(constraints)); }
        bool        Dropdown(ID id, int& selected, std::span<const std::string_view> options, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Dropdown(ID id, int& selected, std::span<const std::string_view> options, LayoutOverride&& constraints = {}) { return Dropdown(id, selected, options, theme.controls->menuTrigger, std::move(constraints)); }
        inline bool Dropdown(       int& selected, std::span<const std::string_view> options, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Dropdown(idManager.AllocateDynamicID(site), selected, options, style, std::move(constraints)); }
        inline bool Dropdown(       int& selected, std::span<const std::string_view> options, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Dropdown(idManager.AllocateDynamicID(site), selected, options, theme.controls->menuTrigger, std::move(constraints)); }
        inline bool Dropdown(ID id, int& selected, std::initializer_list<std::string_view> options, LayoutOverride&& constraints = {}) { return Dropdown(id, selected, std::span<const std::string_view>(options.begin(), options.size()), theme.controls->menuTrigger, std::move(constraints)); }
        inline bool Dropdown(       int& selected, std::initializer_list<std::string_view> options, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Dropdown(idManager.AllocateDynamicID(site), selected, std::span<const std::string_view>(options.begin(), options.size()), theme.controls->menuTrigger, std::move(constraints)); }
        inline bool Dropdown(ID id, int& selected, std::initializer_list<std::string_view> options, StyleRef style, LayoutOverride&& constraints = {}) { return Dropdown(id, selected, std::span<const std::string_view>(options.begin(), options.size()), style, std::move(constraints)); }
        inline bool Dropdown(       int& selected, std::initializer_list<std::string_view> options, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Dropdown(idManager.AllocateDynamicID(site), selected, std::span<const std::string_view>(options.begin(), options.size()), style, std::move(constraints)); }
        void        MenuHeader(std::string_view text);
        int         MessageDialog(ID id, const MessageDialogDesc& desc, StyleRef style);
        inline int  MessageDialog(ID id, const MessageDialogDesc& desc) { return MessageDialog(id, desc, theme.messageBoxStyleRef); }
        inline int  MessageDialog(       const MessageDialogDesc& desc, StyleRef style, std::source_location site = std::source_location::current()) { return MessageDialog(idManager.AllocateDynamicID(site), desc, style); }
        inline int  MessageDialog(       const MessageDialogDesc& desc, std::source_location site = std::source_location::current()) { return MessageDialog(idManager.AllocateDynamicID(site), desc, theme.messageBoxStyleRef); }

        ToastID     ShowToast(ToastDesc desc);
        ToastDesc*  FindToast(ToastID toast);
        void        DismissToast(ToastID toast);
        void        Toasts();
        void        Banner(ID id, Severity severity, const GUIContent& message, std::span<const BannerAction> actions = {},
                           LayoutOverride&& constraints = {});
        inline void Banner(Severity severity, const GUIContent& message, std::span<const BannerAction> actions = {},
                           LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { Banner(idManager.AllocateDynamicID(site), severity, message, actions, std::move(constraints)); }

        bool        CloseRequested(ID windowID);

        void        MenuFilter();

        bool        MenuItem(ID id, const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {});
        inline bool MenuItem(ID id, const GUIContent& content, std::function<void()> onClick = nullptr, LayoutOverride&& constraints = {}) { return MenuItem(id, content, std::string_view{}, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool MenuItem(       const GUIContent& content, std::function<void()> onClick = nullptr, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return MenuItem(idManager.AllocateDynamicID(site), content, std::string_view{}, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool MenuItem(ID id, const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, LayoutOverride&& constraints = {}) { return MenuItem(id, content, shortcut, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool MenuItem(       const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return MenuItem(idManager.AllocateDynamicID(site), content, shortcut, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool MenuItem(       const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return MenuItem(idManager.AllocateDynamicID(site), content, shortcut, std::move(onClick), style, std::move(constraints)); }
        inline bool MenuItem(ID id, const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}) { return MenuItem(id, content, std::string_view{}, std::move(onClick), style, std::move(constraints)); }
        inline bool MenuItem(       const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return MenuItem(idManager.AllocateDynamicID(site), content, std::string_view{}, std::move(onClick), style, std::move(constraints)); }

        bool MenuItem(CommandID command);
        bool        DestructiveMenuItem(ID id, const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {});
        inline bool DestructiveMenuItem(ID id, const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, LayoutOverride&& constraints = {}) { return DestructiveMenuItem(id, content, shortcut, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool DestructiveMenuItem(       const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return DestructiveMenuItem(idManager.AllocateDynamicID(site), content, shortcut, std::move(onClick), style, std::move(constraints)); }
        inline bool DestructiveMenuItem(       const GUIContent& content, std::string_view shortcut, std::function<void()> onClick, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return DestructiveMenuItem(idManager.AllocateDynamicID(site), content, shortcut, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool DestructiveMenuItem(ID id, const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}) { return DestructiveMenuItem(id, content, std::string_view{}, std::move(onClick), style, std::move(constraints)); }
        inline bool DestructiveMenuItem(ID id, const GUIContent& content, std::function<void()> onClick, LayoutOverride&& constraints = {}) { return DestructiveMenuItem(id, content, std::string_view{}, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        inline bool DestructiveMenuItem(       const GUIContent& content, std::function<void()> onClick, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return DestructiveMenuItem(idManager.AllocateDynamicID(site), content, std::string_view{}, std::move(onClick), style, std::move(constraints)); }
        inline bool DestructiveMenuItem(       const GUIContent& content, std::function<void()> onClick, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return DestructiveMenuItem(idManager.AllocateDynamicID(site), content, std::string_view{}, std::move(onClick), theme.menuItemRowStyleRef, std::move(constraints)); }
        void EndMenu();

        bool        BeginMenuBar(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginMenuBar(ID id, LayoutOverride&& constraints = {}) { return BeginMenuBar(id, theme.menuBarStyleRef, std::move(constraints)); }
        inline bool BeginMenuBar(       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginMenuBar(idManager.AllocateDynamicID(site), theme.menuBarStyleRef, std::move(constraints)); }
        inline bool BeginMenuBar(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginMenuBar(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        void EndMenuBar();


 
        // ---- Title bar: a menu bar the window is dragged by ----
        // Whatever in it isn't a control is the caption: dragging it moves the window and a
        // double-click maximizes it. In a window with ElementFlags::WindowCustomTitleBar,
        // EndTitleBar adds the minimize, maximize / restore and close buttons.
        bool        BeginTitleBar(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginTitleBar(ID id, LayoutOverride&& constraints = {}) { return BeginTitleBar(id, theme.titleBarStyleRef, std::move(constraints)); }
        inline bool BeginTitleBar(       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginTitleBar(idManager.AllocateDynamicID(site), theme.titleBarStyleRef, std::move(constraints)); }
        inline bool BeginTitleBar(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginTitleBar(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        void        EndTitleBar();

        WindowHitArea TitleBarHitTest(ID windowID, int2 screenPos) const;

        void MenuSeparator();

        void SetTooltip(ID targetID, std::string_view text);
        void SetTooltip(ID targetID, IconID icon, std::string_view text);
        inline void SetTooltip(std::string_view text) { SetTooltip(elementStorage.GetLastItemID(), text); }
        inline void SetTooltip(IconID icon, std::string_view text) { SetTooltip(elementStorage.GetLastItemID(), icon, text); }
        void SetTooltip(ID targetID, std::string_view text, std::string_view shortcut);
        void SetTooltip(ID targetID, IconID icon, std::string_view text, std::string_view shortcut);
        inline void SetTooltip(std::string_view text, std::string_view shortcut) { SetTooltip(elementStorage.GetLastItemID(), text, shortcut); }
        void SetTooltip(ID targetID, const PropertyHelp& help);
        inline void SetTooltip(const PropertyHelp& help) { SetTooltip(elementStorage.GetLastItemID(), help); }
        void SetErrorTooltip(ID targetID, std::string_view message);
        inline void SetErrorTooltip(std::string_view message) { SetErrorTooltip(elementStorage.GetLastItemID(), message); }
        void SetDisabledTooltip(ID targetID, std::string_view text, std::string_view reason);
        inline void SetDisabledTooltip(std::string_view text, std::string_view reason) { SetDisabledTooltip(elementStorage.GetLastItemID(), text, reason); }

        bool BeginTooltip(ID targetID);
        inline bool BeginTooltip() { return BeginTooltip(elementStorage.GetLastItemID()); }
        void EndTooltip();

        bool BeginContextMenu(ID targetID);
        inline bool BeginContextMenu() { return BeginContextMenu(elementStorage.GetLastItemID()); }
        void EndContextMenu();
        void OpenContextMenu(ID targetID, int2 screenPos);



        bool        BeginLabelGroup(ID id, CssPx defaultWidth = 120, CssPx minWidth = 40, CssPx maxWidth = 500, bool resizable = true);
        inline bool BeginLabelGroup(CssPx defaultWidth = 120, CssPx minWidth = 40, CssPx maxWidth = 500, bool resizable = true, std::source_location site = std::source_location::current()) { return BeginLabelGroup(idManager.AllocateDynamicID(site), defaultWidth, minWidth, maxWidth, resizable); }
        void        EndLabelGroup();

        bool        BeginButtonGroup(LayoutOverride&& constraints = {});
        void        EndButtonGroup();
        bool        BeginToggleGroup(LayoutOverride&& constraints = {});
        void        EndToggleGroup();


        bool        BeginArea(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginArea(ID id,                 LayoutOverride&& constraints = {}) { return BeginArea(id, theme.collectionStyleRef, std::move(constraints)); }
        inline bool BeginArea(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginArea(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginArea(                       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginArea(idManager.AllocateDynamicID(site), theme.collectionStyleRef, std::move(constraints)); }
        void EndArea();

        bool        BeginCached(ID id, StyleRef style, uint64_t signature = 0, LayoutOverride&& constraints = {});
        inline bool BeginCached(ID id, uint64_t signature = 0, LayoutOverride&& constraints = {}) { return BeginCached(id, theme.collectionStyleRef, signature, std::move(constraints)); }
        void        EndCached();
        void        Invalidate(ID id);

        void        SetDrawCacheEnabled(bool enabled) { if (m_uiCache) m_uiCache->SetDrawCacheEnabled(enabled); }

        void        InvalidatePanel(ID panelId);

        bool        BeginHorizontal(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginHorizontal(ID id,                 LayoutOverride&& constraints = {}) { return BeginHorizontal(id, theme.emptyHorzStyleRef, std::move(constraints)); }
        inline bool BeginHorizontal(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginHorizontal(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginHorizontal(                       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginHorizontal(idManager.AllocateDynamicID(site), theme.emptyHorzStyleRef, std::move(constraints)); }
        void EndHorizontal();

        bool        BeginHorizontalWrap(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginHorizontalWrap(ID id,                 LayoutOverride&& constraints = {}) { return BeginHorizontalWrap(id, theme.emptyHorzWrapStyleRef, std::move(constraints)); }
        inline bool BeginHorizontalWrap(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginHorizontalWrap(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginHorizontalWrap(                       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginHorizontalWrap(idManager.AllocateDynamicID(site), theme.emptyHorzWrapStyleRef, std::move(constraints)); }
        void EndHorizontalWrap();

        bool        BeginVertical(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginVertical(ID id,                 LayoutOverride&& constraints = {}) { return BeginVertical(id, theme.emptyVertStyleRef, std::move(constraints)); }
        inline bool BeginVertical(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginVertical(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginVertical(                       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginVertical(idManager.AllocateDynamicID(site), theme.emptyVertStyleRef, std::move(constraints)); }
        void EndVertical();

        bool        BeginVerticalWrap(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginVerticalWrap(ID id,                 LayoutOverride&& constraints = {}) { return BeginVerticalWrap(id, theme.emptyVertWrapStyleRef, std::move(constraints)); }
        inline bool BeginVerticalWrap(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginVerticalWrap(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginVerticalWrap(                       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginVerticalWrap(idManager.AllocateDynamicID(site), theme.emptyVertWrapStyleRef, std::move(constraints)); }
        void EndVerticalWrap();

        bool BeginToolbar(bool horizontal = true);
        void EndToolbar();


 
        // ---- Scrollbars ----
        // Call from INSIDE the scrollable container `containerID`: the bar overlays
        // its border box, unaffected by its scroll offset. Paints nothing without
        // overflow, so it can always be emitted.
        void VerticalScrollbar  (ID scrollBarID, ID containerID);
        void VerticalScrollbar  (ID containerID) { (void)idManager.PushParent(containerID); const ID barID = idManager.AllocateDynamicID("vertical_scrollbar"); (void)idManager.PopParent(); VerticalScrollbar(barID, containerID); }
        void HorizontalScrollbar(ID scrollBarID, ID containerID);
        void HorizontalScrollbar(ID containerID) { (void)idManager.PushParent(containerID); const ID barID = idManager.AllocateDynamicID("horizontal_scrollbar"); (void)idManager.PopParent(); HorizontalScrollbar(barID, containerID); }

        void ScrollbarOverlay(ID containerID,
                              int2 lastInnerSize = int2{0, 0},
                              ID vertScrollBarID = ID::Invalid(),
                              ID horzScrollBarID = ID::Invalid(),
                              bool emitVert = true,
                              bool emitHorz = true);


 
        // ---- Reorderable Group: drag-to-reorder container ----
        // onReorder(fromIndex, toIndex) fires on drop. isWrapped allows multi-line layout.
        // onDragOut(index, screenPos): an item was released outside the group.
        // dragVisualizer(index, screenPos): each frame while dragging outside the group,
        // typically to draw a ghost window; suppresses the in-place cross-axis offset.
        bool        BeginReorderableGroup(ID id, ReorderDirection direction, bool isWrapped, std::function<void(int fromIndex, int toIndex)> onReorder, StyleRef style, LayoutOverride&& constraints = {}, std::function<void(int, tachyon::int2)> onDragOut = nullptr, std::function<void(int, tachyon::int2)> dragVisualizer = nullptr);
        inline bool BeginReorderableGroup(ID id, ReorderDirection direction, std::function<void(int fromIndex, int toIndex)> onReorder, StyleRef style, LayoutOverride&& constraints = {})
        { return BeginReorderableGroup(id, direction, false, std::move(onReorder), style, std::move(constraints)); }

        inline bool BeginReorderableGroup(ID id, ReorderDirection direction, std::function<void(int fromIndex, int toIndex)> onReorder, LayoutOverride&& constraints = {})
        { return BeginReorderableGroup(id, direction, false, std::move(onReorder), ReorderableGroupStyle(direction, false), std::move(constraints)); }

        inline bool BeginReorderableGroup(ID id, ReorderDirection direction, bool isWrapped, std::function<void(int fromIndex, int toIndex)> onReorder, LayoutOverride&& constraints = {})
        { return BeginReorderableGroup(id, direction, isWrapped, std::move(onReorder), ReorderableGroupStyle(direction, isWrapped), std::move(constraints)); }

        inline bool BeginReorderableGroup(ReorderDirection direction, bool isWrapped, std::function<void(int fromIndex, int toIndex)> onReorder, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { return BeginReorderableGroup(idManager.AllocateDynamicID(site), direction, isWrapped, std::move(onReorder), style, std::move(constraints)); }

        inline bool BeginReorderableGroup(ReorderDirection direction, bool isWrapped, std::function<void(int fromIndex, int toIndex)> onReorder, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { return BeginReorderableGroup(idManager.AllocateDynamicID(site), direction, isWrapped, std::move(onReorder), ReorderableGroupStyle(direction, isWrapped), std::move(constraints)); }

        inline bool BeginReorderableGroup(ReorderDirection direction, std::function<void(int fromIndex, int toIndex)> onReorder, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { return BeginReorderableGroup(idManager.AllocateDynamicID(site), direction, false, std::move(onReorder), style, std::move(constraints)); }

        inline bool BeginReorderableGroup(ReorderDirection direction, std::function<void(int fromIndex, int toIndex)> onReorder, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { return BeginReorderableGroup(idManager.AllocateDynamicID(site), direction, false, std::move(onReorder), ReorderableGroupStyle(direction, false), std::move(constraints)); }

        StyleRef ReorderableGroupStyle(ReorderDirection direction, bool isWrapped) const
        {
            if (isWrapped)
                return direction == ReorderDirection::Horizontal ? theme.horzReorderableGroupWrapStyleRef : theme.vertReorderableGroupWrapStyleRef;
            return direction == ReorderDirection::Horizontal ? theme.horzReorderableGroupStyleRef : theme.vertReorderableGroupStyleRef;
        }

        void EndReorderableGroup();

        bool        BeginReorderableItem(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginReorderableItem(ID id, LayoutOverride&& constraints = {}) { return BeginReorderableItem(id, theme.reorderableItemStyleRef, std::move(constraints)); }
        inline bool BeginReorderableItem(StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginReorderableItem(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        inline bool BeginReorderableItem(LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginReorderableItem(idManager.AllocateDynamicID(site), theme.reorderableItemStyleRef, std::move(constraints)); }
        void EndReorderableItem();

        void EmitDragHandle();


 
        // ---- ListView: scrollable list with selectable items ----
        bool        BeginListView(ID id, int* selectedIndex, int itemCount, ItemDragDropConfig* dragDrop, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginListView(ID id, int* selectedIndex, int itemCount, StyleRef style, LayoutOverride&& constraints = {}) { return BeginListView(id, selectedIndex, itemCount, nullptr, style, std::move(constraints)); }
        inline bool BeginListView(ID id, int* selectedIndex, int itemCount, LayoutOverride&& constraints = {}) { return BeginListView(id, selectedIndex, itemCount, nullptr, theme.listViewStyleRef, std::move(constraints)); }
        inline bool BeginListView(       int* selectedIndex, int itemCount, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginListView(idManager.AllocateDynamicID(site), selectedIndex, itemCount, nullptr, theme.listViewStyleRef, std::move(constraints)); }
        inline bool BeginListView(ID id, int* selectedIndex, int itemCount, ItemDragDropConfig* dragDrop, LayoutOverride&& constraints = {}) { return BeginListView(id, selectedIndex, itemCount, dragDrop, theme.listViewStyleRef, std::move(constraints)); }
        inline bool BeginListView(       int* selectedIndex, int itemCount, ItemDragDropConfig* dragDrop, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginListView(idManager.AllocateDynamicID(site), selectedIndex, itemCount, dragDrop, theme.listViewStyleRef, std::move(constraints)); }
        inline bool BeginListView(       int* selectedIndex, int itemCount, ItemDragDropConfig* dragDrop, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginListView(idManager.AllocateDynamicID(site), selectedIndex, itemCount, dragDrop, style, std::move(constraints)); }
        inline bool BeginListView(       int* selectedIndex, int itemCount, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginListView(idManager.AllocateDynamicID(site), selectedIndex, itemCount, nullptr, style, std::move(constraints)); }
        void EndListView();

        int FindListItemIndex(tachyon::ID id) const;

        bool        ListItem(ID id, const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {});
        inline bool ListItem(ID id, const GUIContent& content, LayoutOverride&& constraints = {}) { return ListItem(id, content, theme.listItemStyleRef, std::move(constraints)); }
        inline bool ListItem(       const GUIContent& content, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return ListItem(idManager.AllocateDynamicID(site), content, theme.listItemStyleRef, std::move(constraints)); }
        inline bool ListItem(       const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return ListItem(idManager.AllocateDynamicID(site), content, style, std::move(constraints)); }
 

        static void RebuildTreeViewIndex(std::vector<TreeViewRow>& rows);

        static void WalkTreeViewVisibility(const std::vector<TreeViewRow>& rows,
                                           std::vector<int>& visibleIdx);

        void VirtualTreeView(ID id,
                             std::vector<TreeViewRow>& rows,
                             std::vector<int>& visibleIdx,
                             TableState& state,
                             StyleRef style = {},
                             LayoutOverride&& constraints = {},
                             std::string_view header = {});
        inline void VirtualTreeView(std::vector<TreeViewRow>& rows, std::vector<int>& visibleIdx, TableState& state,
                                    StyleRef style = {}, LayoutOverride&& constraints = {}, std::string_view header = {},
                                    std::source_location site = std::source_location::current())
            { VirtualTreeView(idManager.AllocateDynamicID(site), rows, visibleIdx, state, style, std::move(constraints), header); }

        ID TreeDropTargetRow() const { return m_treeDropState.targetRowID; }

        bool IsFileDragging() const { return inputManager && inputManager->GetFileDrag() != nullptr; }
        ID FileDragTargetID() const { return m_fileDragTargetID; }
        void SetFileDropHandler(std::function<void(const FileDrop&)> handler) { m_fileDropHandler = std::move(handler); }

        bool BeginSelected() { guiStateManager.Construction().PushSelected(); return true; }
        void EndSelected()   { guiStateManager.Construction().PopSelected(); }
        bool BeginDisabled() { guiStateManager.Construction().PushDisabled(); return true; }
        void EndDisabled()   { guiStateManager.Construction().PopDisabled(); }
        bool BeginInvalid() { guiStateManager.Construction().PushInvalid(); return true; }
        void EndInvalid()   { guiStateManager.Construction().PopInvalid(); }


 
        // ---- GridView: 2D icon grid (like file explorer) ----
        bool        BeginGridView(ID id, int* selectedIndex, StyleRef style, MultiSelectState* multiSelect = nullptr, ItemDragDropConfig* dragDrop = nullptr, LayoutOverride&& constraints = {});
        inline bool BeginGridView(ID id, int* selectedIndex = nullptr, MultiSelectState* multiSelect = nullptr, ItemDragDropConfig* dragDrop = nullptr, LayoutOverride&& constraints = {}) { return BeginGridView(id, selectedIndex, theme.gridViewStyleRef, multiSelect, dragDrop, std::move(constraints)); }
        inline bool BeginGridView(int* selectedIndex, StyleRef style, MultiSelectState* multiSelect = nullptr, ItemDragDropConfig* dragDrop = nullptr, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginGridView(idManager.AllocateDynamicID(site), selectedIndex, style, multiSelect, dragDrop, std::move(constraints)); }
        inline bool BeginGridView(int* selectedIndex, MultiSelectState* multiSelect = nullptr, ItemDragDropConfig* dragDrop = nullptr, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginGridView(idManager.AllocateDynamicID(site), selectedIndex, theme.gridViewStyleRef, multiSelect, dragDrop, std::move(constraints)); }
        void EndGridView();

        bool        GridViewItem(ID id, const GUIContent& content,
                                 tachyon::ElementState extraState = tachyon::ElementState::None,
                                 std::string* renameBuffer = nullptr,
                                 StyleRef itemStyle = {},
                                 LayoutOverride&& constraints = {});
        inline bool GridViewItem(ID id, const GUIContent& content, LayoutOverride&& constraints)
            { return GridViewItem(id, content, tachyon::ElementState::None, nullptr, {}, std::move(constraints)); }

        inline bool GridViewItem(const GUIContent& content, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return GridViewItem(idManager.AllocateDynamicID(site), content, tachyon::ElementState::None, nullptr, {}, std::move(constraints)); }

        inline bool GridViewItem(ID id, const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {})
            { return GridViewItem(id, content, tachyon::ElementState::None, nullptr, style, std::move(constraints)); }

        inline bool GridViewItem(const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return GridViewItem(idManager.AllocateDynamicID(site), content, tachyon::ElementState::None, nullptr, style, std::move(constraints)); }

        bool IsRenaming() const { return m_renameSub && m_renameSub->isActive; }
 

        void VirtualGridView(ID id, GridViewVirtualState& vstate,
                             int itemCount, int2 cellSize,
                             const std::function<void(int index, ID itemID)>& generateItem,
                             int* selectedIndex = nullptr,
                             MultiSelectState* multiSelect = nullptr,
                             ItemDragDropConfig* dragDrop = nullptr,
                             StyleRef scrollStyle = {},
                             StyleRef rowStyle = {},
                             LayoutOverride&& constraints = {});
        inline void VirtualGridView(GridViewVirtualState& vstate, int itemCount, int2 cellSize,
                                    const std::function<void(int index, ID itemID)>& generateItem,
                                    int* selectedIndex = nullptr, MultiSelectState* multiSelect = nullptr,
                                    ItemDragDropConfig* dragDrop = nullptr, StyleRef scrollStyle = {}, StyleRef rowStyle = {},
                                    LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { VirtualGridView(idManager.AllocateDynamicID(site), vstate, itemCount, cellSize, generateItem, selectedIndex, multiSelect, dragDrop, scrollStyle, rowStyle, std::move(constraints)); }


 
        // ---- Table: row x column data grid ----
        bool  BeginTable(ID id, VirtualTableColumn* columns, size_t columnCount,
                         TableState& state, StyleRef style,
                         LayoutOverride&& constraints = {});
        inline bool BeginTable(ID id, VirtualTableColumn* columns, size_t columnCount,
                               TableState& state, LayoutOverride&& constraints = {})
            { return BeginTable(id, columns, columnCount, state, theme.tableStyleRef, std::move(constraints)); }

        template <size_t N>
        inline bool BeginTable(ID id, VirtualTableColumn (&columns)[N], TableState& state,
                               StyleRef style, LayoutOverride&& constraints = {})
            { return BeginTable(id, columns, N, state, style, std::move(constraints)); }

        template <size_t N>
        inline bool BeginTable(ID id, VirtualTableColumn (&columns)[N], TableState& state,
                               LayoutOverride&& constraints = {})
            { return BeginTable(id, columns, N, state, theme.tableStyleRef, std::move(constraints)); }

        inline bool BeginTable(VirtualTableColumn* columns, size_t columnCount, TableState& state, StyleRef style,
                               LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginTable(idManager.AllocateDynamicID(site), columns, columnCount, state, style, std::move(constraints)); }

        inline bool BeginTable(VirtualTableColumn* columns, size_t columnCount, TableState& state,
                               LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginTable(idManager.AllocateDynamicID(site), columns, columnCount, state, theme.tableStyleRef, std::move(constraints)); }

        template <size_t N>
        inline bool BeginTable(VirtualTableColumn (&columns)[N], TableState& state, StyleRef style,
                               LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginTable(idManager.AllocateDynamicID(site), columns, N, state, style, std::move(constraints)); }

        template <size_t N>
        inline bool BeginTable(VirtualTableColumn (&columns)[N], TableState& state,
                               LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginTable(idManager.AllocateDynamicID(site), columns, N, state, theme.tableStyleRef, std::move(constraints)); }

        void EndTable();

        bool BeginRow();
        void EndRow();

        void Cell(std::string_view text);

        void Cell(std::function<void()> emit);

        void TreeCell(std::string_view text, int depth, bool* isOpen,
                      IconID icon = IconID::Invalid,
                      uint32_t ancestorLineMask = 0,
                      bool isLastSibling = true,
                      std::string* renameBuffer = nullptr,
                      bool reserveExpander = true);

        void VirtualTable(ID id, TableState& state,
                          std::span<VirtualTableColumn> columns,
                          int totalRowCount,
                          CssPx rowHeight = 0,
                          StyleRef style = {},
                          LayoutOverride&& constraints = {});
        inline void VirtualTable(TableState& state, std::span<VirtualTableColumn> columns, int totalRowCount,
                                 CssPx rowHeight = 0, StyleRef style = {}, LayoutOverride&& constraints = {},
                                 std::source_location site = std::source_location::current())
            { VirtualTable(idManager.AllocateDynamicID(site), state, columns, totalRowCount, rowHeight, style, std::move(constraints)); }


 
        // ---- Breadcrumb ----
        bool        Breadcrumb(ID id, std::span<const std::string> segments, std::function<void(int)> onSelect, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Breadcrumb(ID id, std::span<const std::string> segments, std::function<void(int)> onSelect, LayoutOverride&& constraints = {}) { return Breadcrumb(id, segments, std::move(onSelect), theme.breadcrumbStyleRef, std::move(constraints)); }
        inline bool Breadcrumb(       std::span<const std::string> segments, std::function<void(int)> onSelect, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Breadcrumb(idManager.AllocateDynamicID(site), segments, std::move(onSelect), theme.breadcrumbStyleRef, std::move(constraints)); }
        inline bool Breadcrumb(       std::span<const std::string> segments, std::function<void(int)> onSelect, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Breadcrumb(idManager.AllocateDynamicID(site), segments, std::move(onSelect), style, std::move(constraints)); }


 
        // ---- Status bar ----
        bool        BeginStatusBar(ID id, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginStatusBar(ID id, LayoutOverride&& constraints = {}) { return BeginStatusBar(id, theme.statusBarStyleRef, std::move(constraints)); }
        inline bool BeginStatusBar(       LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginStatusBar(idManager.AllocateDynamicID(site), theme.statusBarStyleRef, std::move(constraints)); }
        inline bool BeginStatusBar(       StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return BeginStatusBar(idManager.AllocateDynamicID(site), style, std::move(constraints)); }
        void        EndStatusBar();
        void        StatusText(ID id, std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline void StatusText(ID id, std::string_view text, LayoutOverride&& constraints = {}) { StatusText(id, text, theme.statusTextStyleRef, std::move(constraints)); }
        inline void StatusText(       std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { StatusText(idManager.AllocateDynamicID(site), text, style, std::move(constraints)); }
        inline void StatusText(       std::string_view text, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { StatusText(idManager.AllocateDynamicID(site), text, theme.statusTextStyleRef, std::move(constraints)); }


 
        // ---- Command search ----
        bool        CommandSearch(ID id, CommandSearchState& state, StyleRef style, LayoutOverride&& constraints = {});
        inline bool CommandSearch(ID id, CommandSearchState& state, LayoutOverride&& constraints = {}) { return CommandSearch(id, state, theme.commandSearchStyleRef, std::move(constraints)); }
        inline bool CommandSearch(       CommandSearchState& state, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return CommandSearch(idManager.AllocateDynamicID(site), state, style, std::move(constraints)); }
        inline bool CommandSearch(       CommandSearchState& state, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return CommandSearch(idManager.AllocateDynamicID(site), state, theme.commandSearchStyleRef, std::move(constraints)); }
        static void FocusCommandSearch(CommandSearchState& state) { state.focusRequested = true; }


 
        // ---- Node view: self-contained graph editor ----
        // All state lives in `view`, so several views can coexist.
        void RenderNodeView(NodeView& view);

        void NodeText(std::string_view text);


 
        // ---- TabBar: reorderable tabs ----
        bool BeginTabBar(ID id, int* selectedIndex,
                         std::function<void(int, int)> onReorder,
                         std::function<void(int)> onClose = nullptr,
                         std::function<void(int, tachyon::int2)> onDragOut = nullptr,
                         std::function<void(int, tachyon::int2)> dragVisualizer = nullptr,
                         StyleRef style = {},
                         LayoutOverride&& constraints = {},
                         TabBarLayout* layout = nullptr,
                         const TabBarOptions& options = {});
        inline bool BeginTabBar(int* selectedIndex,
                                std::function<void(int, int)> onReorder,
                                std::function<void(int)> onClose = nullptr,
                                std::function<void(int, tachyon::int2)> onDragOut = nullptr,
                                std::function<void(int, tachyon::int2)> dragVisualizer = nullptr,
                                StyleRef style = {},
                                LayoutOverride&& constraints = {}, TabBarLayout* layout = nullptr,
                                std::source_location site = std::source_location::current())
            { return BeginTabBar(idManager.AllocateDynamicID(site), selectedIndex, std::move(onReorder), std::move(onClose), std::move(onDragOut), std::move(dragVisualizer), style, std::move(constraints), layout); }

        void EndTabBar();

        bool        Tab(ID id, const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {});
        bool BeginTab(ID id, const GUIContent& content, StyleRef style, StyleRef contentStyle,
                      LayoutOverride&& constraints = {});
        void EndTab();
        inline bool Tab(ID id, const GUIContent& content, LayoutOverride&& constraints = {}) { return Tab(id, content, theme.tabStyleRef, std::move(constraints)); }
        inline bool Tab(       const GUIContent& content, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Tab(idManager.AllocateDynamicID(site), content, theme.tabStyleRef, std::move(constraints)); }
        inline bool Tab(       const GUIContent& content, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Tab(idManager.AllocateDynamicID(site), content, style, std::move(constraints)); }


 
        // ---- DockingContainer ----
        bool BeginDockingContainer(ID id, DockingLayout* layout, StyleRef style, LayoutOverride&& constraints = {});
        inline bool BeginDockingContainer(ID id, DockingLayout* layout, LayoutOverride&& constraints = {})
            { return BeginDockingContainer(id, layout, theme.dockContainerStyleRef, std::move(constraints)); }

        inline bool BeginDockingContainer(DockingLayout* layout, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginDockingContainer(idManager.AllocateDynamicID(site), layout, style, std::move(constraints)); }

        inline bool BeginDockingContainer(DockingLayout* layout, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
            { return BeginDockingContainer(idManager.AllocateDynamicID(site), layout, theme.dockContainerStyleRef, std::move(constraints)); }

        void EndDockingContainer();

        void Documents(ID id, DocumentSet& set, LayoutOverride&& constraints = {});



        bool        Field(ID id, bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Field(       bool& value, std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, text, style, std::move(constraints)); }
        inline bool Field(ID id, bool& value, std::string_view text,                 LayoutOverride&& constraints = {}) { return Field(id,                            value, text, theme.controls->toggle, std::move(constraints)); }
        inline bool Field(       bool& value, std::string_view text,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, text, theme.controls->toggle, std::move(constraints)); }

        bool        Field(ID id, std::string& value, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Field(       std::string& value, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, textEditBehavior, style, std::move(constraints)); }
        inline bool Field(ID id, std::string& value, StyleRef style, LayoutOverride&& constraints = {}) { return Field(id, value, TextEditBehavior::ContinuousUpdate, style, std::move(constraints)); }
        inline bool Field(       std::string& value, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, style, std::move(constraints)); }
        inline bool Field(ID id, std::string& value, TextEditBehavior textEditBehavior, LayoutOverride&& constraints = {}) { return Field(id,                            value, textEditBehavior, theme.controls->textbox, std::move(constraints)); }
        inline bool Field(       std::string& value, TextEditBehavior textEditBehavior, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, textEditBehavior, theme.controls->textbox, std::move(constraints)); }
        inline bool Field(ID id, std::string& value, LayoutOverride&& constraints = {}) { return Field(id,                            value, TextEditBehavior::ContinuousUpdate, theme.controls->textbox, std::move(constraints)); }
        inline bool Field(       std::string& value, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, theme.controls->textbox, std::move(constraints)); }

        inline bool SearchField(ID id, std::string& value, IconID icon, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints = {}) { return SearchField(id, value, icon, textEditBehavior, style, std::move(constraints), nullptr); }
        inline bool SearchField(ID id, std::string& value, IconID icon, TextEditBehavior textEditBehavior = TextEditBehavior::ContinuousUpdate, LayoutOverride&& constraints = {}) { return SearchField(id, value, icon, textEditBehavior, theme.searchTextboxStyleRef, std::move(constraints)); }
        inline bool SearchField(       std::string& value, IconID icon, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SearchField(idManager.AllocateDynamicID(site), value, icon, textEditBehavior, style, std::move(constraints)); }
        inline bool SearchField(       std::string& value, IconID icon, TextEditBehavior textEditBehavior = TextEditBehavior::ContinuousUpdate, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SearchField(idManager.AllocateDynamicID(site), value, icon, textEditBehavior, theme.searchTextboxStyleRef, std::move(constraints)); }

        bool        AutocompleteField(ID id, std::string& value, std::span<const std::string_view> suggestions, StyleRef style, LayoutOverride&& constraints = {});
        inline bool AutocompleteField(ID id, std::string& value, std::span<const std::string_view> suggestions, LayoutOverride&& constraints = {}) { return AutocompleteField(id, value, suggestions, theme.controls->textbox, std::move(constraints)); }
        inline bool AutocompleteField(       std::string& value, std::span<const std::string_view> suggestions, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return AutocompleteField(idManager.AllocateDynamicID(site), value, suggestions, style, std::move(constraints)); }
        inline bool AutocompleteField(       std::string& value, std::span<const std::string_view> suggestions, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return AutocompleteField(idManager.AllocateDynamicID(site), value, suggestions, theme.controls->textbox, std::move(constraints)); }
 
 
 

        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, TextEditBehavior textEditBehavior, StyleRef style, NumericFieldConfig<ComponentT> config = {}, LayoutOverride&& constraints = {})
        {
            if (guiStateManager.Construction().IsIndeterminate())
            {
                RegisterControl(tachyon::Element { .id = id, .styleRef = style, .flags = ElementFlags::DoNotMeasureText },
                    [this](tachyon::Element& element) { return textSystem->RegisterText(element.id, "\xe2\x80\x94", element.styleRef, element.state); },
                    std::move(constraints));
                guiStateManager.SetModified(false);
                return false;
            }
 
            if constexpr (TypeDimensions<T>::dimensions == 1)
            {
                // Inside a node row, fill the body after the label so the node stays grid-aligned.
                if (nodeRowFieldMinWidth > 0 && !constraints.HasFixedWidth())
                    constraints.FlexGrow(1).MinWidth(Pixels{ nodeRowFieldMinWidth });
                bool modified = false;
                RegisterControl(tachyon::Element { .id = id, .eventHandler = ReportingChanges(guiStateManager, &value, MakeNumericalBoxHandler(guiStateManager, value, config)),
                                                   .styleRef = style, .flags = ElementFlags::DoNotMeasureText },
                                [this, &modified, &value, textEditBehavior, config](tachyon::Element& element) {
                                    const TextID textID = textSystem->RegisterEditableNumber(element.id, value, textEditBehavior, element.styleRef, element.state, modified, config);
                                    if constexpr (std::is_floating_point_v<T>)
                                        if (std::isnan(value))
                                            textSystem->SetTextColor(textID, theme.nanTextColor);   // NaN reads as a warning
                                    return textID;
                                },
                                std::move(constraints));
                // A label drag writes the value from the handler: reported the frame after.
                modified = modified || guiStateManager.Interaction().HasBeenClicked(id);
                guiStateManager.SetModified(modified);
                return modified;
            } else
            {
                bool modified = false;
                // Width 0 + flex-grow: the group fills remaining space after the label.
                constraints.Width(0);
                // Takes its components' states, so a tooltip or context menu on it covers them.
                RegisterElement(tachyon::Element{ .id = id, .eventHandler = ReportingChanges(guiStateManager, &value, MakeMultiDimDragHandler<T>(guiStateManager, value, config)),
                                                  .styleRef = theme.fieldElementGroupStyleRef,
                                                  .flags = ElementFlags::PropagatesDescendantState }, std::move(constraints));
                VERIFY(elementStorage.BeginChildren());
                {
                    // Each component: a colored axis label (drag it to change the value) attached
                    // to the component's field. A caller's own style replaces the attached field.
                    const StyleRef componentStyle = (style == theme.controls->number || style == theme.controls->textbox) ? theme.vectorComponentStyleRef : style;
                    for (int i = 0; i < TypeDimensions<T>::dimensions; i++)
                    {
                        DragLabel(TypeDimensions<T>::names[i], theme.axisLabelStyleRefs[i % 4],
                            LayoutOverride::FixedWidth(Pixels{ theme.axisLabelWidth }).KeepWithNext());   // wraps with its field
                        modified = Field(TypeDimensions<T>::GetComponent(value, i), textEditBehavior, componentStyle, config, LayoutOverride::Auto()
                            .MinWidth(40)) || modified;
                    }
                }
                VERIFY(elementStorage.EndChildren());
                modified = modified || guiStateManager.Interaction().HasBeenClicked(id);
                guiStateManager.SetModified(modified);
                return modified;
            }
        }

        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, TextEditBehavior textEditBehavior, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}) { return Field<T>(id, value, textEditBehavior, theme.controls->number, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, TextEditBehavior textEditBehavior, LayoutOverride&& constraints = {}) { return Field<T>(id, value, textEditBehavior, theme.controls->number, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, LayoutOverride&& constraints = {}) { return Field<T>(id, value, TextEditBehavior::ContinuousUpdate, theme.controls->number, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, StyleRef style, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}) { return Field<T>(id, value, TextEditBehavior::ContinuousUpdate, style, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, StyleRef style, LayoutOverride&& constraints = {}) { return Field<T>(id, value, TextEditBehavior::ContinuousUpdate, style, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(ID id, T& value, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}) { return Field<T>(id, value, TextEditBehavior::ContinuousUpdate, theme.controls->number, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(T& value, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, style, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(       T& value, TextEditBehavior textEditBehavior, StyleRef style, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, textEditBehavior, style, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(T& value, StyleRef style, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, style, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(       T& value, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, textEditBehavior, style, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(       T& value, TextEditBehavior textEditBehavior, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, textEditBehavior, theme.controls->number, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(T& value, NumericFieldConfig<ComponentT> config, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, theme.controls->number, config, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(       T& value, TextEditBehavior textEditBehavior, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, textEditBehavior, theme.controls->number, {}, std::move(constraints)); }
        template<typename T, typename ComponentT = typename TypeDimensions<T>::ComponentType>
        inline bool Field(       T& value, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Field<T>(idManager.AllocateDynamicID(site), value, TextEditBehavior::ContinuousUpdate, theme.controls->number, {}, std::move(constraints)); }
        

        template<typename T>
        static constexpr std::string_view TypeTag()
        {
            if constexpr (std::is_same_v<T, float>)         return "f32";
            else if constexpr (std::is_same_v<T, double>)   return "f64";
            else if constexpr (std::is_same_v<T, int8_t>)   return "i8";
            else if constexpr (std::is_same_v<T, int16_t>)  return "i16";
            else if constexpr (std::is_same_v<T, int32_t>)  return "i32";
            else if constexpr (std::is_same_v<T, int64_t>)  return "i64";
            else if constexpr (std::is_same_v<T, uint8_t>)  return "u8";
            else if constexpr (std::is_same_v<T, uint16_t>) return "u16";
            else if constexpr (std::is_same_v<T, uint32_t>) return "u32";
            else if constexpr (std::is_same_v<T, uint64_t>) return "u64";
            else if constexpr (std::is_same_v<T, std::string>) return "string";
            else return {};
        }

        template<typename T>
        bool TypedField(ID id, T& value, LayoutOverride&& constraints = {}) { return TypedField(id, value, theme.typedFieldStyleRef, std::move(constraints)); }
        template<typename T>
        bool TypedField(ID id, T& value, StyleRef style, LayoutOverride&& constraints = {})
        {
            // The box's and the type's IDs under the field's own, so they don't depend on what came before.
            [[maybe_unused]] const bool pushed = idManager.PushParent(id);
            const ID boxID  = idManager.AllocateDynamicID("typed_field");
            const ID typeID = idManager.AllocateDynamicID("typed_field_type");
            if (pushed) (void)idManager.PopParent();
            BeginFieldBox(boxID, style, std::move(constraints));
            const bool changed = Field(id, value, TextEditBehavior::ContinuousUpdate, theme.typedFieldInputStyleRef, {},
                                       LayoutOverride{}.FlexGrow(1));
            Text(typeID, TypeTag<T>(), theme.typedFieldTypeStyleRef);
            EndFieldBox();
            return changed;
        }

        template<typename T>
        bool TypedField(T& value, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return TypedField(idManager.AllocateDynamicID(site), value, std::move(constraints)); }
        template<typename T>
        bool TypedField(T& value, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return TypedField(idManager.AllocateDynamicID(site), value, style, std::move(constraints)); }

        template<typename T>
        void Field(ID id, std::vector<T>& items, StyleRef style, LayoutOverride&& constraints = {})
        {
            if (BeginArea(id, style, std::move(constraints)))
            {
                // Everything inside under the list's own ID.
                [[maybe_unused]] const bool pushed = idManager.PushParent(id);
                auto onReorder = [&items](int from, int to)
                {
                    if (from < 0 || from >= (int)items.size()) return;
                    if (to   < 0 || to   >= (int)items.size()) return;
                    T moved = std::move(items[from]);
                    items.erase(items.begin() + from);
                    items.insert(items.begin() + to, std::move(moved));
                };
 
                if (BeginReorderableGroup(idManager.AllocateDynamicID("list_rows"), ReorderDirection::Vertical, std::move(onReorder),
                                          theme.collectionListStyleRef, tachyon::LayoutOverride{}.FlexGrow(1)))
                {
                    for (int i = 0; i < (int)items.size(); i++)
                    {
                        BeginReorderableItem(idManager.AllocateDynamicID("list_row"), theme.collectionRowStyleRef,
                                             tachyon::LayoutOverride{}.FlexGrow(1));
                        {
                            EmitDragHandle();
                            Text(idManager.AllocateDynamicID("list_index"), std::to_string(i), theme.collectionIndexStyleRef);
                            if constexpr (std::is_arithmetic_v<T>)
                                TypedField(items[i], tachyon::LayoutOverride{}.FlexGrow(1));
                            else
                                Field(items[i], tachyon::LayoutOverride{}.FlexGrow(1));
                            Button(theme.tabCloseIcon, [&items, i]() { items.erase(items.begin() + i); },
                                   theme.collectionRemoveStyleRef, tachyon::LayoutOverride{}.NoGrow());
                        }
                        EndReorderableItem();
                    }
                    EndReorderableGroup();
                }
                Button(idManager.AllocateDynamicID("list_add"), "+  Add item", [&items]() { items.push_back({}); },
                       theme.collectionAddStyleRef);
                if (pushed) (void)idManager.PopParent();
                EndArea();
            }
        }

        template<typename T>
        void Field(ID id, std::vector<T>& items, LayoutOverride&& constraints = {}) { Field(id, items, theme.collectionAreaStyleRef, std::move(constraints)); }
        template<typename T>
        void Field(std::vector<T>& items, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, style, std::move(constraints)); }
        template<typename T>
        void Field(std::vector<T>& items, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, theme.collectionAreaStyleRef, std::move(constraints)); }

        template<typename V>
        void Field(ID id, std::vector<std::pair<std::string, V>>& items, StyleRef style, LayoutOverride&& constraints = {})
        {
            if (BeginArea(id, style, std::move(constraints)))
            {
                // Everything inside under the dictionary's own ID.
                [[maybe_unused]] const bool pushed = idManager.PushParent(id);
                CollectionHeader(TypeTag<V>());
                for (int i = 0; i < (int)items.size(); i++)
                {
                    BeginHorizontal(idManager.AllocateDynamicID("dictionary_row"), theme.collectionEntryStyleRef, tachyon::LayoutOverride{}.NoShrink());
                    Field(items[i].first,  tachyon::LayoutOverride{}.FlexGrow(1));
                    Field(items[i].second, TextEditBehavior::ContinuousUpdate, theme.collectionValueStyleRef, tachyon::LayoutOverride{}.FlexGrow(1));
                    Button(theme.tabCloseIcon, [&items, i]() { items.erase(items.begin() + i); },
                           theme.collectionRemoveStyleRef, tachyon::LayoutOverride{}.NoGrow());
                    EndHorizontal();
                }
                Button(idManager.AllocateDynamicID("dictionary_add"), "+  Add entry",
                       [&items]() { items.push_back({ std::string{}, V{} }); }, theme.collectionAddEntryStyleRef);
                if (pushed) (void)idManager.PopParent();
                EndArea();
            }
        }

        template<typename V>
        void Field(ID id, std::vector<std::pair<std::string, V>>& items, LayoutOverride&& constraints = {}) { Field(id, items, theme.collectionAreaStyleRef, std::move(constraints)); }
        template<typename V>
        void Field(std::vector<std::pair<std::string, V>>& items, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, style, std::move(constraints)); }
        template<typename V>
        void Field(std::vector<std::pair<std::string, V>>& items, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, theme.collectionAreaStyleRef, std::move(constraints)); }

        template<typename V>
        void Field(ID id, std::unordered_map<std::string, V>& items, StyleRef style, LayoutOverride&& constraints = {})
        {
            if (BeginArea(id, style, std::move(constraints)))
            {
                // Everything inside under the dictionary's own ID.
                [[maybe_unused]] const bool pushed = idManager.PushParent(id);
                CollectionHeader(TypeTag<V>());
                // Map keys are const: edit a copy, committed on Enter/blur, and re-key
                // after the loop (renaming onto an existing key is ignored).
                std::string renameFrom, renameTo;
                bool        rename = false;
                for (auto& pair : items)
                {
                    BeginHorizontal(idManager.AllocateDynamicID("dictionary_row"), theme.collectionEntryStyleRef, tachyon::LayoutOverride{}.NoShrink());
                    std::string key = pair.first;
                    if (Field(key, TextEditBehavior::None, tachyon::LayoutOverride{}.FlexGrow(1)) && key != pair.first)
                    {
                        renameFrom = pair.first;
                        renameTo   = key;
                        rename     = true;
                    }
                    Field(pair.second, TextEditBehavior::ContinuousUpdate, theme.collectionValueStyleRef, tachyon::LayoutOverride{}.FlexGrow(1));
                    Button(theme.tabCloseIcon, [&items, k = pair.first]() { items.erase(k); },
                           theme.collectionRemoveStyleRef, tachyon::LayoutOverride{}.NoGrow());
                    EndHorizontal();
                }
                if (rename && !items.contains(renameTo))
                {
                    auto node = items.extract(renameFrom);
                    node.key() = renameTo;
                    items.insert(std::move(node));
                }
                Button(idManager.AllocateDynamicID("dictionary_add"), "+  Add entry",
                       [&items]() { items.emplace(std::string{}, V{}); }, theme.collectionAddEntryStyleRef);
                if (pushed) (void)idManager.PopParent();
                EndArea();
            }
        }

        template<typename V>
        void Field(ID id, std::unordered_map<std::string, V>& items, LayoutOverride&& constraints = {}) { Field(id, items, theme.collectionAreaStyleRef, std::move(constraints)); }
        template<typename V>
        void Field(std::unordered_map<std::string, V>& items, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, style, std::move(constraints)); }
        template<typename V>
        void Field(std::unordered_map<std::string, V>& items, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Field(idManager.AllocateDynamicID(site), items, theme.collectionAreaStyleRef, std::move(constraints)); }

        void CollectionHeader(std::string_view valueType);

 

 
        // ---- ColorField: swatch + color picker popup ----
        bool        ColorField(ID id, tachyon::color4f& value, bool allowHDR, StyleRef style, LayoutOverride&& constraints = {});
        inline bool ColorField(ID id, tachyon::color4f& value, bool allowHDR = false, LayoutOverride&& constraints = {}) { return ColorField(id, value, allowHDR, theme.colorFieldStyleRef, std::move(constraints)); }
        inline bool ColorField(       tachyon::color4f& value, bool allowHDR, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return ColorField(idManager.AllocateDynamicID(site), value, allowHDR, style, std::move(constraints)); }
        inline bool ColorField(       tachyon::color4f& value, bool allowHDR = false, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return ColorField(idManager.AllocateDynamicID(site), value, allowHDR, theme.colorFieldStyleRef, std::move(constraints)); }
        bool        ColorField(ID id, tachyon::color4b& value, StyleRef style, LayoutOverride&& constraints = {});
        inline bool ColorField(ID id, tachyon::color4b& value, LayoutOverride&& constraints = {}) { return ColorField(id, value, theme.colorFieldStyleRef, std::move(constraints)); }
        inline bool ColorField(       tachyon::color4b& value, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return ColorField(idManager.AllocateDynamicID(site), value, style, std::move(constraints)); }
        inline bool ColorField(       tachyon::color4b& value, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())                        { return ColorField(idManager.AllocateDynamicID(site), value, theme.colorFieldStyleRef, std::move(constraints)); }
 
        // ---- GradientField: gradient swatch + editor popup ----
        bool        GradientField(ID id, tachyon::Gradient& value, StyleRef style, LayoutOverride&& constraints = {});
        inline bool GradientField(ID id, tachyon::Gradient& value, LayoutOverride&& constraints = {}) { return GradientField(id, value, theme.gradientSwatchStyleRef, std::move(constraints)); }
        inline bool GradientField(       tachyon::Gradient& value, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return GradientField(idManager.AllocateDynamicID(site), value, style, std::move(constraints)); }
        inline bool GradientField(       tachyon::Gradient& value, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return GradientField(idManager.AllocateDynamicID(site), value, theme.gradientSwatchStyleRef, std::move(constraints)); }


 
        // ---- SliderField: DragLabel + horizontal slider track + numeric textbox ----
        bool        SliderField(ID id, float& value, float minVal, float maxVal,
                                std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline bool SliderField(ID id, float& value, float minVal, float maxVal,
                                std::string_view text, LayoutOverride&& constraints = {}) { return SliderField(id, value, minVal, maxVal, text, theme.sliderFieldTrackStyleRef, std::move(constraints)); }

        inline bool SliderField(float& value, float minVal, float maxVal,
                                std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SliderField(idManager.AllocateDynamicID(site), value, minVal, maxVal, text, style, std::move(constraints)); }

        inline bool SliderField(float& value, float minVal, float maxVal,
                                std::string_view text, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SliderField(idManager.AllocateDynamicID(site), value, minVal, maxVal, text, theme.sliderFieldTrackStyleRef, std::move(constraints)); }

        bool        SliderField(ID id, int& value, int minVal, int maxVal,
                                std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline bool SliderField(ID id, int& value, int minVal, int maxVal,
                                std::string_view text, LayoutOverride&& constraints = {}) { return SliderField(id, value, minVal, maxVal, text, theme.sliderFieldTrackStyleRef, std::move(constraints)); }

        inline bool SliderField(int& value, int minVal, int maxVal,
                                std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SliderField(idManager.AllocateDynamicID(site), value, minVal, maxVal, text, style, std::move(constraints)); }

        inline bool SliderField(int& value, int minVal, int maxVal,
                                std::string_view text, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return SliderField(idManager.AllocateDynamicID(site), value, minVal, maxVal, text, theme.sliderFieldTrackStyleRef, std::move(constraints)); }

        bool        Slider(ID id, int& value, int minVal, int maxVal, StyleRef style, LayoutOverride&& constraints = {});
        inline bool Slider(ID id, int& value, int minVal, int maxVal, LayoutOverride&& constraints = {}) { return Slider(id, value, minVal, maxVal, theme.sliderStyleRef, std::move(constraints)); }
        inline bool Slider(int& value, int minVal, int maxVal, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Slider(idManager.AllocateDynamicID(site), value, minVal, maxVal, style, std::move(constraints)); }
        inline bool Slider(int& value, int minVal, int maxVal, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { return Slider(idManager.AllocateDynamicID(site), value, minVal, maxVal, theme.sliderStyleRef, std::move(constraints)); }
 
 



        void        DragLabel(ID id, std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline void DragLabel(ID id, std::string_view text,                 LayoutOverride&& constraints = {}) { DragLabel(id, text, theme.dragLabelStyleRef, std::move(constraints)); }
        inline void DragLabel(       std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { DragLabel(idManager.AllocateDynamicID(site), text, style, std::move(constraints)); }
        inline void DragLabel(       std::string_view text,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { DragLabel(idManager.AllocateDynamicID(site), text, theme.dragLabelStyleRef, std::move(constraints)); }

        void        Label(ID id, std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        void        Label(ID id, std::string_view text, std::string_view caption, StyleRef style, LayoutOverride&& constraints = {});
        inline void Label(ID id, std::string_view text, std::string_view caption, LayoutOverride&& constraints = {}) { Label(id, text, caption, theme.groupLabelTopStyleRef, std::move(constraints)); }
        inline void Label(       std::string_view text, std::string_view caption, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Label(idManager.AllocateDynamicID(site), text, caption, style, std::move(constraints)); }
        inline void Label(       std::string_view text, std::string_view caption, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Label(idManager.AllocateDynamicID(site), text, caption, theme.groupLabelTopStyleRef, std::move(constraints)); }
        inline void Label(ID id, std::string_view text,                 LayoutOverride&& constraints = {}) { Label(id, text, theme.labelStyleRef, std::move(constraints)); }
        inline void Label(       std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Label(idManager.AllocateDynamicID(site), text, style, std::move(constraints)); }
        inline void Label(       std::string_view text,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Label(idManager.AllocateDynamicID(site), text, theme.labelStyleRef, std::move(constraints)); }

        void        Text(ID id, std::string_view text, StyleRef style, LayoutOverride&& constraints = {});
        inline void Text(ID id, std::string_view text,                 LayoutOverride&& constraints = {}) { Text(id, text, theme.staticTextStyleRef, std::move(constraints)); }
        inline void Text(       std::string_view text, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Text(idManager.AllocateDynamicID(site), text, style, std::move(constraints)); }
        inline void Text(       std::string_view text,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Text(idManager.AllocateDynamicID(site), text, theme.staticTextStyleRef, std::move(constraints)); }

        void SelectableText(ID id, const std::span<ContentRun>& runs,
                            std::function<void(intptr_t contentId)> onLinkActivate,
                            StyleRef style, LayoutOverride&& constraints = {});
        inline void SelectableText(ID id, const std::span<ContentRun>& runs, StyleRef style, LayoutOverride&& constraints = {})
        { SelectableText(id, runs, {}, style, std::move(constraints)); }

        inline void SelectableText(ID id, const std::span<ContentRun>& runs, LayoutOverride&& constraints = {})
        { SelectableText(id, runs, {}, theme.staticTextStyleRef, std::move(constraints)); }

        inline void SelectableText(const std::span<ContentRun>& runs, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { SelectableText(idManager.AllocateDynamicID(site), runs, {}, style, std::move(constraints)); }

        inline void SelectableText(const std::span<ContentRun>& runs, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current())
        { SelectableText(idManager.AllocateDynamicID(site), runs, {}, theme.staticTextStyleRef, std::move(constraints)); }

        void        Image(ID id, ImageIndex image, StyleRef style, LayoutOverride&& constraints = {});
        inline void Image(ID id, ImageIndex image,                 LayoutOverride&& constraints = {}) { Image(id, image, theme.imageStyleRef, std::move(constraints)); }
        inline void Image(       ImageIndex image, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Image(idManager.AllocateDynamicID(site), image, style, std::move(constraints)); }
        inline void Image(       ImageIndex image,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Image(idManager.AllocateDynamicID(site), image, theme.imageStyleRef, std::move(constraints)); }

        void        Image(ID id, ImageIndex image, uint2 sourceSize, StyleRef style, LayoutOverride&& constraints = {});
        inline void Image(ID id, ImageIndex image, uint2 sourceSize,                 LayoutOverride&& constraints = {}) { Image(id, image, sourceSize, theme.imageStyleRef, std::move(constraints)); }
        inline void Image(       ImageIndex image, uint2 sourceSize, StyleRef style, LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Image(idManager.AllocateDynamicID(site), image, sourceSize, style, std::move(constraints)); }
        inline void Image(       ImageIndex image, uint2 sourceSize,                 LayoutOverride&& constraints = {}, std::source_location site = std::source_location::current()) { Image(idManager.AllocateDynamicID(site), image, sourceSize, theme.imageStyleRef, std::move(constraints)); }



        bool BeginGhostWindow(ID windowLayoutID, int2 position)
        {
            return BeginGhostWindow(windowLayoutID, position, int2{ styleManager.Px(28), styleManager.Px(28) });
        }

        bool BeginGhostWindow(ID windowLayoutID, int2 position, int2 size, StyleRef styleRef)
        {
            if (windowManager->GetWindowState(windowLayoutID) == WindowState::Closing)
            {
                m_windowOpen.push_back(false);   // its EndGhostWindow is still called
                return false;
            }
 
            LayoutOverride constraints = LayoutOverride::FixedSize(size).Position(position.x, position.y);
 
            ElementFlags elementFlags = tachyon::ElementFlags::WindowNoCaption | tachyon::ElementFlags::WindowIsTransparent;
            return BeginWindow(windowLayoutID, styleRef, std::move(constraints), elementFlags);
        }

        bool BeginGhostWindow(ID windowLayoutID, int2 position, int2 size)
        {
            return BeginGhostWindow(windowLayoutID, position, size, theme.ghostWindowStyleRef);
        }

        bool BeginGhostWindow(ID windowLayoutID, int2 position, StyleRef styleRef)
        {
            if (windowManager->GetWindowState(windowLayoutID) == WindowState::Closing)
            {
                m_windowOpen.push_back(false);   // its EndGhostWindow is still called
                return false;
            }
            LayoutOverride constraints = LayoutOverride{}.Position(position.x, position.y);
            ElementFlags elementFlags = ElementFlags::WindowNoCaption | ElementFlags::WindowIsTransparent;
            return BeginWindow(windowLayoutID, styleRef, std::move(constraints), elementFlags);
        }

        int2 CursorGhostOffset() const
        {
            const int32_t o = m_cursorSize > 0 ? (m_cursorSize * 14 + 16) / 32 : styleManager.Px(14);
            return int2{ o, o };
        }

        bool BeginCursorGhostWindow(ID windowLayoutID, int2 cursorPos)
        {
            return BeginGhostWindow(windowLayoutID, cursorPos + CursorGhostOffset());
        }

        bool BeginCursorGhostWindow(ID windowLayoutID, int2 cursorPos, int2 size, StyleRef styleRef)
        {
            return BeginGhostWindow(windowLayoutID, cursorPos + CursorGhostOffset(), size, styleRef);
        }

        bool BeginCursorGhostWindow(ID windowLayoutID, int2 cursorPos, int2 size)
        {
            return BeginGhostWindow(windowLayoutID, cursorPos + CursorGhostOffset(), size);
        }

        bool BeginCursorGhostWindow(ID windowLayoutID, int2 cursorPos, StyleRef styleRef)
        {
            return BeginGhostWindow(windowLayoutID, cursorPos + CursorGhostOffset(), styleRef);
        }

        void AddGhostIcon(IconID icon, std::source_location site = std::source_location::current())
        {
            auto dragGhostIconID = idManager.AllocateDynamicID(site);
            tachyon::Element ghostIcon
            {
                .id       = dragGhostIconID,
                .textID   = TextID::Invalid,
                .iconID   = icon,
                .styleRef = theme.ghostIconStyleRef,
            };
 
            auto ghostIconRes = elementStorage.Add(std::move(ghostIcon),
                                                   tachyon::LayoutOverride::FixedSize(28, 28));
            VERIFY(ghostIconRes.status);
            VERIFY(windowRegistry.Add(ghostIconRes.ref));
        }

        void EndGhostWindow()
        {
            EndWindow();
        }



        bool BeginWindow(ID windowLayoutID, std::string_view title, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, title, theme.windowStyleRef, LayoutOverride{}, flags, monitorIndex);
        }

        bool BeginWindow(ID windowLayoutID, std::string_view title, StyleRef styleRef, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, title, styleRef, LayoutOverride{}, flags, monitorIndex);
        }

        bool BeginWindow(ID windowLayoutID, std::string_view title, LayoutOverride&& constraints, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, title, theme.windowStyleRef, std::move(constraints), flags, monitorIndex);
        }
 

        bool BeginWindow(ID windowLayoutID, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, theme.windowStyleRef, LayoutOverride{}, flags, monitorIndex);
        }

        bool BeginWindow(ID windowLayoutID, StyleRef styleRef, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, styleRef, LayoutOverride{}, flags, monitorIndex);
        }

        bool BeginWindow(ID windowLayoutID, LayoutOverride&& constraints, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, theme.windowStyleRef, std::move(constraints), flags, monitorIndex);
        }

        bool BeginWindow(ID windowLayoutID, StyleRef styleRef, LayoutOverride&& constraints, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            return BeginWindow(windowLayoutID, "", styleRef, std::move(constraints), flags, monitorIndex);
        }
 

        bool BeginWindow(ID windowLayoutID, std::string_view title, StyleRef styleRef, LayoutOverride&& constraints, ElementFlags flags = ElementFlags::WindowUserControlled | ElementFlags::WindowIsCentered, int monitorIndex = -1)
        {
            const bool open = OpenWindow(windowLayoutID, title, styleRef, std::move(constraints), flags, monitorIndex);
            m_windowOpen.push_back(open);
            return open;
        }

        bool OpenWindow(ID windowLayoutID, std::string_view title, StyleRef styleRef, LayoutOverride&& constraints, ElementFlags flags, int monitorIndex)
        {
            if (windowLayoutID == ID::Invalid())
            {
                ReportMisuse("GUIApplication: BeginWindow with an invalid ID (not shown)");
                return false;
            }
 
            // Closed by the user since last frame.
            if (windowManager->GetWindowState(windowLayoutID) == WindowState::Closing
                || windowManager->WasUserClosed(windowLayoutID))
            {
                return false;
            }
            if (!m_restoredWindows.empty())
                ApplyRestoredWindow(windowLayoutID, constraints, flags);
 
            if (monitorIndex == -1)
            {
                if (constraints.x.type == PositionType::Fixed &&
                    constraints.y.type == PositionType::Fixed)
                {
                    monitorIndex = windowManager->GetMonitorIndexAt(tachyon::int2{ .x = constraints.x.near, .y = constraints.y.near });
                } else
                    monitorIndex = windowManager->GetPrimaryMonitorIndex();
            }
 
            Element windowElement
            {
                .id           = windowLayoutID,
                .textID       = (title.size() == 0) ? TextID::Invalid : textSystem->RegisterText(windowLayoutID, title, styleRef, tachyon::ElementState::None),
                .styleRef     = styleRef,
                .monitorIndex = (int16_t)monitorIndex,
                .flags        = ElementFlags::IsWindow | flags
            };
 
            auto addResult = elementStorage.Add(std::move(windowElement),
                                                std::move(constraints));
            VERIFY(addResult.status);
            windowRegistry.BeginWindowScope(windowLayoutID, addResult.ref);
            VERIFY(elementStorage.BeginChildren());
 
            tabChainManager.BeginWindow(windowLayoutID);
            [[maybe_unused]] bool pushed = idManager.PushParent(windowLayoutID);
            assert(pushed); // windows are top-level, so this can't fail
 
            m_windowIdScopeStack.push_back(pushed);
            activeWindowID = windowLayoutID;
            return true;
        }

        void EndWindow()
        {
            if (m_windowOpen.empty())
            {
                ReportMisuse("GUIApplication: EndWindow without BeginWindow (ignored)");
                return;
            }
            const bool open = m_windowOpen.back();
            m_windowOpen.pop_back();
            if (open)
                CloseWindow();
        }


        template<void (GUIApplication::*EndFn)()>
        class [[nodiscard]] Scope
        {
        public:
            Scope(GUIApplication& app, bool open) : m_app(&app), m_open(open) {}
            Scope(Scope&& other) noexcept : m_app(std::exchange(other.m_app, nullptr)), m_open(other.m_open) {}
            Scope(const Scope&)            = delete;
            Scope& operator=(const Scope&) = delete;
            Scope& operator=(Scope&&)      = delete;
            ~Scope() { End(); }

            void End()
            {
                if (GUIApplication* app = std::exchange(m_app, nullptr))
                    (app->*EndFn)();
            }
            explicit operator bool() const { return m_open; }
 
        private:
            GUIApplication* m_app;
            bool            m_open;
        };

        template<class... A> auto Window(A&&... a)           { return Scope<&GUIApplication::EndWindow>(*this, BeginWindow(std::forward<A>(a)...)); }
        template<class... A> auto GhostWindow(A&&... a)      { return Scope<&GUIApplication::EndGhostWindow>(*this, BeginGhostWindow(std::forward<A>(a)...)); }
        template<class... A> auto CursorGhostWindow(A&&... a){ return Scope<&GUIApplication::EndGhostWindow>(*this, BeginCursorGhostWindow(std::forward<A>(a)...)); }
        template<class... A> auto Menu(A&&... a)             { return Scope<&GUIApplication::EndMenu>(*this, BeginMenu(std::forward<A>(a)...)); }
        template<class... A> auto MenuBar(A&&... a)          { return Scope<&GUIApplication::EndMenuBar>(*this, BeginMenuBar(std::forward<A>(a)...)); }
        template<class... A> auto ContextMenu(A&&... a)      { return Scope<&GUIApplication::EndContextMenu>(*this, BeginContextMenu(std::forward<A>(a)...)); }
        template<class... A> auto Tooltip(A&&... a)          { return Scope<&GUIApplication::EndTooltip>(*this, BeginTooltip(std::forward<A>(a)...)); }
        template<class... A> auto Cached(A&&... a)           { return Scope<&GUIApplication::EndCached>(*this, BeginCached(std::forward<A>(a)...)); }
        template<class... A> auto Horizontal(A&&... a)       { return Scope<&GUIApplication::EndHorizontal>(*this, BeginHorizontal(std::forward<A>(a)...)); }
        template<class... A> auto Vertical(A&&... a)         { return Scope<&GUIApplication::EndVertical>(*this, BeginVertical(std::forward<A>(a)...)); }
        template<class... A> auto HorizontalWrap(A&&... a)   { return Scope<&GUIApplication::EndHorizontalWrap>(*this, BeginHorizontalWrap(std::forward<A>(a)...)); }
        template<class... A> auto VerticalWrap(A&&... a)     { return Scope<&GUIApplication::EndVerticalWrap>(*this, BeginVerticalWrap(std::forward<A>(a)...)); }
        template<class... A> auto Area(A&&... a)             { return Scope<&GUIApplication::EndArea>(*this, BeginArea(std::forward<A>(a)...)); }
        template<class... A> auto LabelGroup(A&&... a)       { return Scope<&GUIApplication::EndLabelGroup>(*this, BeginLabelGroup(std::forward<A>(a)...)); }
        template<class... A> auto ButtonGroup(A&&... a)      { return Scope<&GUIApplication::EndButtonGroup>(*this, BeginButtonGroup(std::forward<A>(a)...)); }
        template<class... A> auto ToggleGroup(A&&... a)      { return Scope<&GUIApplication::EndToggleGroup>(*this, BeginToggleGroup(std::forward<A>(a)...)); }
        template<class... A> auto Table(A&&... a)            { return Scope<&GUIApplication::EndTable>(*this, BeginTable(std::forward<A>(a)...)); }
        template<class... A> auto Row(A&&... a)              { return Scope<&GUIApplication::EndRow>(*this, BeginRow(std::forward<A>(a)...)); }
        template<class... A> auto ListView(A&&... a)         { return Scope<&GUIApplication::EndListView>(*this, BeginListView(std::forward<A>(a)...)); }
        template<class... A> auto GridView(A&&... a)         { return Scope<&GUIApplication::EndGridView>(*this, BeginGridView(std::forward<A>(a)...)); }
        template<class... A> auto TabBar(A&&... a)           { return Scope<&GUIApplication::EndTabBar>(*this, BeginTabBar(std::forward<A>(a)...)); }
        template<class... A> auto Toolbar(A&&... a)          { return Scope<&GUIApplication::EndToolbar>(*this, BeginToolbar(std::forward<A>(a)...)); }
        template<class... A> auto StatusBar(A&&... a)        { return Scope<&GUIApplication::EndStatusBar>(*this, BeginStatusBar(std::forward<A>(a)...)); }
        template<class... A> auto TitleBar(A&&... a)         { return Scope<&GUIApplication::EndTitleBar>(*this, BeginTitleBar(std::forward<A>(a)...)); }
        template<class... A> auto ReorderableGroup(A&&... a) { return Scope<&GUIApplication::EndReorderableGroup>(*this, BeginReorderableGroup(std::forward<A>(a)...)); }
        template<class... A> auto ReorderableItem(A&&... a)  { return Scope<&GUIApplication::EndReorderableItem>(*this, BeginReorderableItem(std::forward<A>(a)...)); }
        template<class... A> auto Disabled(A&&... a)         { return Scope<&GUIApplication::EndDisabled>(*this, BeginDisabled(std::forward<A>(a)...)); }
        template<class... A> auto Invalid(A&&... a)          { return Scope<&GUIApplication::EndInvalid>(*this, BeginInvalid(std::forward<A>(a)...)); }
        template<class... A> auto Selected(A&&... a)         { return Scope<&GUIApplication::EndSelected>(*this, BeginSelected(std::forward<A>(a)...)); }
        template<class... A> auto Indeterminate(A&&... a)    { return Scope<&GUIApplication::EndIndeterminate>(*this, BeginIndeterminate(std::forward<A>(a)...)); }
        template<class... A> auto DockingContainer(A&&... a) { return Scope<&GUIApplication::EndDockingContainer>(*this, BeginDockingContainer(std::forward<A>(a)...)); }
        template<class... A> auto DockingFrame(A&&... a)     { return Scope<&GUIApplication::EndDockingFrame>(*this, BeginDockingFrame(std::forward<A>(a)...)); }


        void CloseWindow()
        {
            tabChainManager.EndWindow();
            if (!m_windowIdScopeStack.empty() && m_windowIdScopeStack.back())
                (void)idManager.PopParent();
            if (!m_windowIdScopeStack.empty())
                m_windowIdScopeStack.pop_back();
            VERIFY(elementStorage.EndChildren());
            windowRegistry.EndWindowScope();
            activeWindowID = ID::Invalid();
            guiStateManager.Labels().ClearPendingLabel();
        }

        void AddBox(ID id, int2 size, StyleRef styleRef, TextID textID = TextID::Invalid)
        {
            Element boxElement {};
            boxElement.id = id;
            boxElement.flags = ElementFlags::None;
            boxElement.styleRef = styleRef;
            boxElement.textID = textID;
            boxElement.state = guiStateManager.GetCurrentState(id);
 
            auto childB1 = elementStorage.Add(std::move(boxElement), LayoutOverride::FixedSize(size));
            VERIFY(childB1.status);
            VERIFY(windowRegistry.Add(childB1.ref));
        }

        void AddBox(int2 size, StyleRef styleRef, TextID textID = TextID::Invalid, std::source_location site = std::source_location::current())
        {
            AddBox(idManager.AllocateDynamicID(site), size, styleRef, textID);
        }

        void AddBox(ID id, int2 size, StyleRef styleRef, std::string_view text)
        {
            ElementState state = guiStateManager.GetCurrentState(id);
            auto childB1 = elementStorage.Add(Element
                                              {
                                                  .id = id,
                                                  .textID = textSystem->RegisterText(id, text, styleRef, state),
                                                  .styleRef = styleRef,
                                                  .flags = ElementFlags::None,
                                                  .state = state
                                              },
                                              LayoutOverride::FixedSize(size));
            VERIFY(childB1.status);
            VERIFY(windowRegistry.Add(childB1.ref));
        }

        void AddBox(ID id, int2 size, StyleRef styleRef, IconID iconID, std::string_view text)
        {
            ElementState state = guiStateManager.GetCurrentState(id);
            auto childB1 = elementStorage.Add(Element
                                              {
                                                  .id = id,
                                                  .textID = textSystem->RegisterText(id, iconID, text, styleRef, state),
                                                  .styleRef = styleRef,
                                                  .flags = ElementFlags::None,
                                                  .state = state
                                              },
                                              LayoutOverride::FixedSize(size));
            VERIFY(childB1.status);
            VERIFY(windowRegistry.Add(childB1.ref));
        }

        void AddBox(ID id, StyleRef styleRef, IconID iconID, std::string_view text)
        {
            ElementState state = guiStateManager.GetCurrentState(id);
            auto childB1 = elementStorage.Add(Element
                                              {
                                                  .id = id,
                                                  .textID = textSystem->RegisterText(id, iconID, text, styleRef, state),
                                                  .styleRef = styleRef,
                                                  .flags = ElementFlags::None,
                                                  .state = state
                                              });
            VERIFY(childB1.status);
            VERIFY(windowRegistry.Add(childB1.ref));
        }

        void AddBox(StyleRef styleRef, std::string_view text, std::source_location site = std::source_location::current())
        {
            AddBox(idManager.AllocateDynamicID(site), styleRef, IconID::Invalid, text);
        }

        void AddBox(int2 size, StyleRef styleRef, std::string_view text, std::source_location site = std::source_location::current())
        {
            AddBox(idManager.AllocateDynamicID(site), size, styleRef, text);
        }


 
        // ------------------------------------------------------------------
        // Settings panel
        // ------------------------------------------------------------------
        // Two-pane settings panel: a page tree, a sizer, and the selected page's content.
        // Owns only selection and tree width; page state belongs to the application.
        struct SettingsPanelState
        {
            struct Page
            {
                tachyon::ID               id;
                std::string           name;
                std::function<void()> render;
            };

            std::vector<Page> pages;
            tachyon::ID           selectedID = tachyon::ID::Invalid();
            CssPx             treeWidth  = 200;

            struct Internal
            {
                std::vector<TreeViewRow> rows;
                std::vector<int>         visibleIdx;
                TableState               tableState;
            } internal;

            tachyon::ID AddPage(tachyon::ID id, std::string_view name, 
                            std::function<void()> render)
            {
                pages.push_back({ id, std::string(name), std::move(render) });
                if (selectedID == tachyon::ID::Invalid()) selectedID = id;
                return id;
            }
        };

        void RenderSettingsPanel(SettingsPanelState& state);



        void PersistWindow(std::string key, ID windowID);
        void PersistDocking(std::string key, DockingLayout& layout);
        void PersistTable(std::string key, TableState& state, std::span<VirtualTableColumn> columns);
        void PersistToolbars(std::string key, std::span<std::vector<ToolbarItem>, kToolbarSideCount> sides);
        void PersistValue(std::string key, bool& value);
        void PersistValue(std::string key, int& value);
        void PersistValue(std::string key, float& value);
        void PersistValue(std::string key, std::string& value);
        void PersistDocuments(std::string key, std::function<std::vector<DocumentWindowRef>()> windows);
        void PersistShortcuts(std::string key, CommandManager& commands);
        std::vector<SavedDocumentWindow> TakeSavedDocuments(std::string_view key);
        bool RestoreDocumentLayout(Document& document, const SavedDocument& saved);
        void RestoreWindowPlace(ID windowID, const SavedDocumentWindow& saved);
        std::string  SaveUIState() const;
        Result<void> RestoreUIState(std::string_view json);

 
    private:
        friend class GUIApplicationInternals;

        std::vector<ID>                            m_cacheRecordStack;

        bool     m_keyboardPending = false;
        bool     m_tabPending      = false;
        uint64_t m_inputFlagsFrame = 0;
        void     RefreshCachedInputFlags();

        void NoteSwatchClaim(ID swatchID);
        std::string PendingLabelText() const;
        struct ColorSwatchLook SwatchLook() const;

        std::unordered_map<tachyon::ID, tachyon::ID>       m_panelContentIDs;

        std::vector<const ControlStyles*> controlStylesStack;
 
        ID tooltipWindowID     { ID::Invalid() };
        ID contextMenuWindowID { ID::Invalid() };
        ID contextMenuTargetID { ID::Invalid() }; 
        std::optional<int2> contextMenuScreenPos; 
        bool m_contextMenuClaimed = false;   
        ID tabDragGhostWindowID{ ID::Invalid() }; 
 
        FrameTimingSample frameTimingHistory[kFrameHistoryCount] = {};
        int               frameTimingHead = 0;           

        ColumnDragState m_columnDrag{};
        TreeDropState   m_treeDropState{};
 
        // ---- ListView ID->index map (shared by every list view; cleared once per frame) ----
        // Filled by ListItem when dragDrop is on; valid in end-of-frame handlers via FindListItemIndex().
        std::unordered_map<tachyon::ID, int> m_listItemIndexByID;
 

        TreeViewState m_treeState{};
        GridViewState m_gridViewState;

        std::unordered_map<tachyon::ID, GridItemRenameInfo> m_gridItemRenameByID;
 

        std::optional<TableEmit> m_tableEmit;
        std::vector<std::optional<TableEmit>> m_outerTableEmits;
 
        int CurrentCellCol() const
        {
            const int c = m_tableEmit->currentCol;
            assert(c < int(m_tableEmit->columnCount));
            return c;
        }
 
        TabBarState m_tabBarState;
        TabState    m_tabState;

        void EnableVisiblePanels(DockingLayout& layout);

        DockingConstructionState m_dockingState;

        std::vector<DockingLayout*> m_dockingLayoutsThisFrame{};

        std::vector<struct ToolbarDockState*> m_toolbarDocksThisFrame{};

        void SyncDockingScrollOffsets();

        void SyncToolbarDockRects();

        tachyon::DockNode* FindDockLeafTabBarCachedAtScreenPos(tachyon::int2 screenPos);
 
        std::vector<std::unique_ptr<FloatingDockWindow>> m_floatingDockWindows;

        void EmitFloatingDockWindowsOf(const DocumentSet* documents);

        std::vector<DocumentSet*> m_documentSetsThisFrame{};
        bool ActivateDocumentOf(const DockingLayout* layout);
        struct ShownToast
        {
            ToastID   handle = 0;
            ToastDesc desc;
            ID        id = ID::Invalid();   
            float     shownAt = 0.0f;       
            float     leftAt  = -1.0f;      
            float     shownFor = 0.0f;      
        };
        std::vector<ShownToast> m_toasts;
        ToastID     m_nextToast = 0;
        float       m_toastsTime = -1.0f;   
        bool        m_toastsExpanded = false;   
        ID          m_toastStackID = ID::Invalid();
        bool        m_toastsBuilt  = false;   
 
        DocumentDrag m_documentDrag;   
        std::vector<IntRect> m_documentBarRects;   
        std::optional<DocumentMove> m_documentMove;   
        void ApplyDocumentMove();
        void SyncDocumentRects();
        DocumentSet* FindDocumentBarAt(tachyon::int2 screenPos);

        void RegisterFrameHooks();   // per-frame stage hooks; Initialize (and test harnesses) call it
        void RegisterFrameBalanceChecks();
        static void ReportMisuse(const char* message);
        bool OpenMenu(ID menuID, std::string_view text, StyleRef buttonStyle, StyleRef menuStyle, StyleRef itemStyle, LayoutOverride&& constraints);
        void CloseMenu();
        enum class TooltipBox : uint8_t { Plain, Lines, Help, Error };
        bool OpenTooltip(ID targetID, TooltipBox box = TooltipBox::Plain);
        void ShowPinTooltip(const NodeView& view, ID socketID, PropertyEndpoint pin, bool isOutput);
        void CloseTooltip();
        struct CutShortText
        {
            ID      id = ID::Invalid();
            ID      windowID = ID::Invalid();  
            int2    windowPos{};               
            int2    at{};                      
            int32_t width = 0;                 
            int32_t height = 0;                
            bool    textOnly = false;          
            int16_t monitorIndex = -1;         
        };
        CutShortText FindCutShortText(int2 mousePos) const;
        void ShowCutShortText();
        CutShortText m_cutShort{};
        bool OpenContextMenuWindow(ID targetID);
        bool OpenCached(ID id, StyleRef style, uint64_t signature, LayoutOverride&& constraints);
        static void ReportInvalidControlID(ID id);
        void RegisterTabStop(ID id);
        bool SearchField(ID id, std::string& value, IconID icon, TextEditBehavior textEditBehavior, StyleRef style, LayoutOverride&& constraints, ID* outFieldID);
        void BeginFieldBox(ID id, StyleRef style, LayoutOverride&& constraints);
        void EndFieldBox();

        void ApplyPendingStyleReload();

        void UpdateMouseCursor(ID hoverID, ID hoverWindowID, int2 mousePosition);
 
        void OnRender(float elapsedTimeSecs);
        void FireStateTransitions(float elapsedTimeSecs);
        struct TransitionsSeen
        {
            std::vector<ID> hover;
            std::vector<ID> focused;
            ID              active = ID::Invalid();
        };
        TransitionsSeen m_transitionsSeen;
        void RenderBoxShadows(IntRect rectLayout, IntRect clipRectScreen, const TransitionState& ts, bool ring);
        void RenderShadowLayer(IntRect rectLayout, IntRect clipRectScreen, const VisualShadow& s, float radius);
        void RenderInvalidHalo(IntRect rectLayout, IntRect clipRectScreen, const TransitionState& ts, float grown);
        void RenderInvalidBorder(IntRect rectLayout, IntRect clipRectScreen, const TransitionState& ts, IntRect snappedPx);
        IntRect OpaqueInterior(IntRect rectLayout, const TransitionState& ts) const;
        void OnFrame();
        Result<void> RecoverDevice();

        std::string m_resourceRoot;
        std::unique_ptr<IWindowBackend> m_osWindowBackend;     
        ImageWindowBackend*  m_imageWindows    { nullptr };    
        MouseButtons         m_injectedButtons { MouseButtons::None };
        int2 InjectedScreenPos(ID windowID, int2 pos);
        AllocationHooks m_allocationHooks;
        std::unique_ptr<GraphicsContext> m_graphicsBackend;
        MouseButtons m_lastPhysicalButtons { MouseButtons::None };  
        std::string ResourcePath(std::string_view path) const;   // relative paths resolve against m_resourceRoot
        std::string m_themePath     { "themes/dark.css" };
        bool        m_initialized = false;   
        bool        m_inFrame     = false;   
        Result<void> m_themeReload {};

        struct PersistedWindow   { std::string key; ID target; };
        struct PersistedDock     { std::string key; DockingLayout* target; };
        struct PersistedTable    { struct Target { TableState* state; std::span<VirtualTableColumn> columns; }; std::string key; Target target; };
        struct PersistedToolbars { std::string key; std::span<std::vector<ToolbarItem>, kToolbarSideCount> target; };
        struct PersistedValue    { using Target = std::variant<bool*, int*, float*, std::string*>; std::string key; Target target; };
        struct PersistedDocuments { std::string key; std::function<std::vector<DocumentWindowRef>()> target; };
        struct PersistedShortcuts { std::string key; CommandManager* target; };
        struct RestoredWindow
        {
            IntRect    rect {};
            IntRect    monitor {};            
            WindowMode mode = WindowMode::Normal;
            bool       hasMonitor  = false;
            bool       hasPosition = false;
            bool       rectDone    = false;
        };
        std::vector<PersistedWindow>   m_persistWindows;
        std::vector<PersistedDock>     m_persistDocks;
        std::vector<PersistedTable>    m_persistTables;
        std::vector<PersistedToolbars> m_persistToolbars;
        std::vector<PersistedValue>    m_persistValues;
        std::vector<PersistedDocuments> m_persistDocuments;
        std::vector<PersistedShortcuts> m_persistShortcuts;
        std::unordered_map<std::string, std::vector<SavedDocumentWindow>> m_savedDocuments;
        std::unordered_map<ID, RestoredWindow> m_restoredWindows;
        void ApplyRestoredWindow(ID windowID, LayoutOverride& constraints, ElementFlags& flags);
        void PlaceOnSavedMonitor(RestoredWindow& restored) const;
        int32_t      m_cursorSize  = 0;   
        std::vector<bool> m_windowOpen, m_menuOpen, m_tooltipOpen, m_cachedOpen;
        std::vector<ConstructionScopes> m_tooltipScopes;
        std::string m_loadedThemePath;
        float       m_loadedFontScale { 1.0f };
        std::vector<std::string> m_styleFiles { "styles.css" };
        float       m_globalFontScale { 1.0f };
        float       m_uiScale { 1.0f };
        std::optional<bool> m_reducedMotion;   

        struct ThemeCrossfade
        {
            ID         window = ID::Invalid();
            tachyon::Image* image = nullptr;
            ImageIndex index  = ImageIndex::Invalid;
        };
        static constexpr float kThemeCrossfadeSecs = 0.2f;
        std::vector<ThemeCrossfade> m_crossfades;
        float                       m_crossfadeStart = 0.0f;           
        VisualBoxStyleIndex         m_crossfadeStyle = VisualBoxStyleIndex::Invalid; 
        void CaptureThemeCrossfade();
        void EndThemeCrossfade();
        float       m_displayScale { 1.0f };
        FrameClock  m_frameClock;   
        bool        m_themeReloadPending { false };
 
        tachyon::ElementRef RegisterElementInternal(tachyon::Element&& element, LayoutOverride&& constraints, bool updateState = true);

        void        InvalidateCachedScopesForInput(ID overID);
        static std::vector<ID> CollectPropagatedAncestors(const ElementStorage& storage, ID leafID);
        void NoteTargetAncestors(int2 mousePos);
        ID TooltipHoverID() const
        {
            const ID hovered = guiStateManager.Interaction().GetHoveredID();
            return hovered != ID::Invalid() ? hovered : guiStateManager.Interaction().GetHoveredDisabledID();
        }
        void        InvalidateCachedScopesAbove(ID id);
        void        RebuildCachedScopesAbove(ID id) { m_cacheRebuildRequests.push_back(id); }
        std::vector<ID> m_cacheRebuildRequests;

        void        NotePanelContentID(ID panelId, ID contentID) { m_panelContentIDs[panelId] = contentID; }

        TextAlign nodeRowTextAlign = TextAlign::Start;

        int32_t nodeRowFieldMinWidth = 0;
 
        bool BeginDockingFrame();
        void EndDockingFrame();
 
        ID activeWindowID { ID::Invalid() };
        std::vector<bool> m_windowIdScopeStack;

        void EmitNodeViewOverlays(NodeView& view, ID canvasID);

        struct TitleBarInfo { ID barID = ID::Invalid(); ID maximizeID = ID::Invalid(); std::vector<ID> captions; };
        std::unordered_map<ID, TitleBarInfo> m_titleBars;
        std::vector<ID> m_titleBarStack;    
        std::vector<ID> m_titleBarCaptions; 
        std::unordered_set<ID> m_closeRequests;   
        struct SuggestionRow { IconID icon = IconID::Invalid; std::string_view text; std::string_view trailing; };
        static constexpr int kMaxSuggestions = 12;
        void SuggestionPopup(ID windowID, ID anchorID, std::span<const SuggestionRow> rows, int current,
                             bool reserveIcon, int32_t minWidth, std::function<void(int)> onPick);
        struct AutocompleteState
        {
            ID      listWindowID = ID::Invalid();
            int     current      = -1;      
            bool    dismissed    = false;   
            bool    picked       = false;   
            int32_t width        = 0;       
        };
        std::unordered_map<ID, AutocompleteState> m_autocomplete;

        struct PressOutsideWatch { ID inside[2]; std::function<void()> onPressOutside; };
        std::vector<PressOutsideWatch> m_pressOutsideWatches;   
        void CloseOnPressOutside(ID inside, ID alsoInside, std::function<void()> onPressOutside)
        { m_pressOutsideWatches.push_back({ { inside, alsoInside }, std::move(onPressOutside) }); }
        void RunPressOutsideWatches();
        void DispatchFileDrops(const FrameInput& input);
        ID   OfferFileDrop(EventType type, ID overID, int2 screenPos, const FileDrop* drop);
        ID   m_fileDragTargetID = ID::Invalid();
        std::vector<FileDrop> m_heldFileDrops;   
        std::function<void(const FileDrop&)> m_fileDropHandler;
        std::vector<TextStyle> m_mnemonicStyles;  
        struct ScrimFade { float amount = 0.0f; bool wanted = false; VisualColorStyleIndex color = VisualColorStyleIndex::Invalid; };
        std::unordered_map<ID, ScrimFade> m_scrims;
        float m_scrimTime = -1.0f;
        void DrawScrims(float now);
        struct PendingAfterDraw { uint32_t endIdx; ElementRef owner; };
        std::vector<PendingAfterDraw> m_pendingAfterDraws;
        void TitleBarCaption(ID id) { m_titleBarCaptions.push_back(id); }
        void DockFloatingWindow(FloatingDockWindow& fw);

        void EmitColorPicker(tachyon::color4f& outColor, bool allowHDR);
        void EmitGradientEditor(tachyon::Gradient& outGradient);

        void EmitColumnSizers(TableEmit& emit, int colStart, int colEnd,
                              bool skipDragged = false);
        void EmitColumnSeparators(TableEmit& emit, int colStart, int colEnd);
        void EmitColumnBackgrounds(TableEmit& emit, int colStart, int colEnd);

        void UpdateTableFollowTail(TableState& state, int32_t viewportH, int32_t contentH);
        void ScrollTableSectionsToBottom(TableState& state);
        void EmitTableSectionSeparator();

        tachyon::LayoutOverride ApplyColumnDragOffsetX(tachyon::LayoutOverride lo,
                                                   const TableEmit& emit, int c) const
        {
            if (emit.dragActive)
                lo = std::move(lo).PositionX(tachyon::PositionConstraintAxis::Relative(emit.columns[c].internal.dragOffsetX));
            return lo;
        }
        void MirrorTableScroll(TableState* state);
        void EmitTableHeaderCell(TableEmit& emit, tachyon::ID tableID, int c, int16_t gridCol,
                                 bool isStretchTrack, int sectionMin, int sectionMax,
                                 int effectiveSortCol, IconID sortIcon);
        void EmitTableHeaderSection(TableEmit& emit, tachyon::ID tableID,
                                    int colStart, int colEnd, bool lastColIsStretch,
                                    int effectiveSortCol, IconID sortIcon);
        GridTrack ComputeSectionColumnTrack(const TableEmit& emit, int c, int colEnd,
                                            bool isMiddle, bool fitContent = false) const;
        void OpenTableBodySection(TableEmit& emit, tachyon::ID sectionID, tachyon::StyleRef sectionStyle,
                                  tachyon::LayoutOverride&& layout, bool sampleViewport);
        void CloseTableBodySection(TableEmit& emit,
                                   tachyon::ID sectionBodyID, bool emitVerticalScrollbar,
                                   bool suppressHorzScrollbar = false);
        void EmitVirtualBodyRows(TableEmit& emit,
                                 int colStart, int colEnd,
                                 int totalRowCount, int32_t actualRowHeight,
                                 int firstVisible, int lastVisible,
                                 tachyon::ID rowsRangeID,
                                 bool isLastSection);

        void EmitDraggedColumnOnTop(TableEmit& emit, tachyon::ID tableID,
                                    int colStart, int colEnd,
                                    int firstVisible, int lastVisible,
                                    tachyon::ID rowsRangeID,
                                    bool lastColIsStretch,
                                    int effectiveSortCol, IconID sortIcon);
        void EmitDirectCellText(const VirtualTableColumn& column, TableEmit& emit,
                                tachyon::ID cellID, tachyon::ElementState cellState, tachyon::ElementFlags cellFlags,
                                tachyon::StyleRef cellStyleRef, tachyon::EventHandler cellHandler,
                                tachyon::TextID textID,
                                int colIdx, int colStart, int16_t gridRow);
        void EmitDirectCellCustom(const VirtualTableColumn& column, TableEmit& emit,
                                  tachyon::ID cellID, tachyon::ElementState cellState, tachyon::ElementFlags cellFlags,
                                  tachyon::StyleRef cellStyleRef, tachyon::EventHandler cellHandler,
                                  bool cellSelected,
                                  std::function<void()> emit_fn,
                                  int colIdx, int colStart, int16_t gridRow);
        void EmitDirectCellTree(const VirtualTableColumn& column, TableEmit& emit,
                                tachyon::ID cellID, tachyon::ElementState cellState, tachyon::ElementFlags cellFlags,
                                tachyon::StyleRef cellStyleRef, tachyon::EventHandler cellHandler,
                                bool cellSelected,
                                tachyon::TextID textID,
                                int treeDepth, bool* treeIsOpen, IconID treeIcon,
                                uint32_t treeAncestorMask, bool treeIsLastSibling,
                                std::string* treeRenameBuffer, bool treeRenameActive,
                                tachyon::ID treeBodyID, bool reserveExpander,
                                int colIdx, int colStart, int16_t gridRow);
        void EmitDirectRowBackdrop(tachyon::ID rowID, int16_t gridRow,
                                   int colStart, int colEnd,
                                   tachyon::ElementState backdropState,
                                   tachyon::ElementFlags backdropFlags,
                                   tachyon::StyleRef rowStyle,
                                   tachyon::EventHandler backdropHandler,
                                   TableState* tableState,
                                   bool isLastSection);
        void EmitDirectRowSpacer(int16_t gridRow,
                                 int colStart, int colEnd, int32_t height);
        tachyon::EventHandler BuildRowBackdropHandler(TableState* state,
                                                  tachyon::ID containerID);
        tachyon::EventHandler BuildTableContainerHandler(TableState* state,
                                                     tachyon::ID containerID);

        bool IsTreeItemSelected(tachyon::ID id, int itemIndex) const;
        tachyon::TextID TreeItemRegisterText(tachyon::ID id, std::string_view text, IconID icon, StyleRef style, tachyon::ElementState state);
        void TreeItemRowCustomDraw(const tachyon::ElementRef& rowRef, bool hasArrow, tachyon::ID rowID);
        tachyon::EventHandler MakeTreeRowDragDropHandler(tachyon::ID rowID, bool rowHasChildren, ItemDragDropConfig* dd, bool* isOpen = nullptr);
        bool TreeItemRenameCheck(tachyon::ID bodyID, std::string* renameBuffer, StyleRef textStyle);
 
        struct TreeClickState { tachyon::ID lastClickID = tachyon::ID::Invalid(); int64_t lastClickTimeNanos = 0; };
 
    };

} // namespace tachyon