inspector_overlay.hpp

Go to the documentation of this file.

// inspector_overlay.hpp — Visual inspector overlay for Pulp view trees
// Renders highlight, property panel, and frame stats on top of the plugin UI.
// Toggled via Cmd+I (macOS) / Ctrl+I (Windows/Linux).
#pragma once
 
#include <pulp/view/view.hpp>
#include <pulp/view/input_events.hpp>
#include <pulp/canvas/canvas.hpp>
#include <pulp/design/design_knobs.hpp>
#include <pulp/inspect/editor_url.hpp>
#include <pulp/inspect/source_jump.hpp>
#include <pulp/inspect/tweak_store.hpp>
#include <pulp/state/edit_history.hpp>
 
#include <choc/containers/choc_Value.h>
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
#include <vector>
 
namespace pulp::render { class RenderPassManager; }
namespace pulp::render { class AtlasInventory; }
 
namespace pulp::inspect {
 
using namespace pulp::view;
using namespace pulp::canvas;
 
class InspectorOverlay {
public:
    explicit InspectorOverlay(View& root);
    ~InspectorOverlay();
 
    // The root View this overlay inspects and paints into. Used by the
    // installed paint hook to gate: the overlay's selection box /
    // handles / drop indicators paint only when this exact root is the one being
    // painted, so they never leak into the floating inspector window's surface.
    View& inspected_root() const { return root_; }
 
    // ── Toggle ──────────────────────────────────────────────────────
    bool is_active() const { return active_; }
    void set_active(bool active);
    void toggle() { set_active(!active_); }
 
    // ── Tool palette ─────────────────────────────────────────────────
    //
    // The active tool gates what a canvas click DOES, making the
    // select-vs-manipulate-vs-edit modality explicit (Figma convention):
    //   - Select (V): the existing overlay behavior — click selects,
    //     body-drag moves (reflow), handle-drag resizes, Shift scales.
    //     UNCHANGED.
    //   - Text (T): click a text-bearing element (Label / TextEditor) to
    //     edit its copy in place. Enter commits (live View text + a `text`
    //     content tweak, one undoable EditHistory unit), Esc cancels.
    // Default Select so every existing host + test is unaffected until the
    // user opts into the Text tool. V/T are bound in handle_key_event(),
    // gated to active_ && editing_field_.empty() && text edit not in
    // progress so they never fire mid-edit.
    enum class Tool : std::uint8_t { select, text };
    Tool tool() const { return tool_; }
    void set_tool(Tool t);
    void toggle_tool() {
        set_tool(tool_ == Tool::select ? Tool::text : Tool::select);
    }
 
    // ── Input interception ──────────────────────────────────────────
    // Call from host BEFORE dispatching to view tree.
    // Returns true if the inspector consumed the event.
    bool handle_key_event(const KeyEvent& event);
    bool handle_mouse_event(const MouseEvent& event);
    // Text-tool inline editing consumes UTF-8 character input (separate
    // from KeyEvent, which carries no character payload). The host routes
    // TextInputEvents here BEFORE the view tree while the overlay is
    // active; returns true when an inline text edit is in progress and
    // the text was appended to the edit buffer. A no-op (returns false)
    // otherwise, so non-text-tool input falls through to widgets.
    bool handle_text_input(const TextInputEvent& event);
 
    // ── Painting ────────────────────────────────────────────────────
    // Call AFTER View::paint_overlays() to paint on top of everything.
    void paint(Canvas& canvas);
 
    // ── Data sources ────────────────────────────────────────────────
    void set_render_pass_manager(render::RenderPassManager* rpm) { rpm_ = rpm; }

    void set_atlas_inventory(const render::AtlasInventory* inv) {
        atlas_inventory_ = inv;
    }
    const render::AtlasInventory* atlas_inventory() const {
        return atlas_inventory_;
    }

    void set_tweak_store(TweakStore* store) { tweak_store_ = store; }
    TweakStore* tweak_store() const { return tweak_store_; }

    void set_edit_history(pulp::state::EditHistory* h) { edit_history_ = h; }
    pulp::state::EditHistory* edit_history() const { return edit_history_; }

    struct ReparentSourceEdit {
        std::string child_anchor;
        std::string new_parent_anchor;
        std::string insert_after_anchor;  // preceding sibling, or "" = first child
    };
    void set_reparent_source_sink(std::function<void(const ReparentSourceEdit&)> sink) {
        reparent_source_sink_ = std::move(sink);
    }
    bool has_reparent_source_sink() const {
        return static_cast<bool>(reparent_source_sink_);
    }

    void set_knob_schema(pulp::design::KnobSchema schema) { knob_schema_ = std::move(schema); }
    const pulp::design::KnobSchema& knob_schema() const { return knob_schema_; }
 
    struct KnobApplyEdit {
        std::string knob_id;  
        std::string value;    
    };
    void set_knob_apply_sink(std::function<void(const KnobApplyEdit&)> sink) {
        knob_apply_sink_ = std::move(sink);
    }
    bool has_knob_apply_sink() const { return static_cast<bool>(knob_apply_sink_); }

    std::string knob_selection(std::string_view knob_id) const;

    struct AgentRequestEdit {
        std::string text;  
    };
    void set_agent_request_sink(std::function<void(const AgentRequestEdit&)> sink) {
        agent_request_sink_ = std::move(sink);
    }
    bool has_agent_request_sink() const { return static_cast<bool>(agent_request_sink_); }

    struct KnobHit {
        std::string knob_id;
        std::string value;
        Rect bounds;  
    };
    const std::vector<KnobHit>& knob_hits() const { return knob_hits_; }
    Rect agent_field_bounds() const { return agent_field_bounds_; }
    Rect agent_send_bounds() const { return agent_send_bounds_; }
    const std::string& agent_text_buffer() const { return agent_text_buffer_; }
    bool agent_field_active() const { return agent_field_active_; }

    void clear_edit_history() {
        if (edit_history_) edit_history_->clear();
    }

    bool emit_tweak_for_selection(std::string_view property_path,
                                  choc::value::Value value,
                                  std::string_view source = "inspector-gesture");
 
    // ── Drag handles ─────────────────────────────────────────────────
    void set_dragging_enabled(bool enabled) { dragging_enabled_ = enabled; }
    bool dragging_enabled() const { return dragging_enabled_; }
    void toggle_dragging() { dragging_enabled_ = !dragging_enabled_; }
 
    // ── Minimal in-canvas manipulate layer ───────────────────────────
    //
    // The full inspector HUD (tree / props / stats side panel) belongs
    // in the FLOATING InspectorWindow. When the in-canvas overlay is used
    // purely for direct manipulation (move / resize handles), it should
    // paint ONLY the selection box + handles, NOT its dev side-panel —
    // otherwise the panel duplicates the floating window and clutters the
    // canvas. `manipulate_only_` flips paint() into that bare mode and
    // makes point_in_panel() always return false so the whole canvas is
    // live for selection + drag. Default OFF so the standalone dev HUD is
    // unchanged. When this mode is on, dragging is implicitly enabled so
    // handles paint without a separate D-key toggle.
    void set_manipulate_only(bool on) {
        manipulate_only_ = on;
        if (on) dragging_enabled_ = true;
    }
    bool manipulate_only() const { return manipulate_only_; }

    void set_selected_view(View* v) { selected_ = v; }
 
    // ── Drill-down / nested selection ────────────────────────────────
    //
    // Selection resolves to the DEEPEST hittable element at the click
    // point (View::hit_test already returns deepest). Esc-to-ascend
    // walks the selection up to its parent so a user can reach a
    // container after landing on a nested child. select_parent() is a
    // no-op (returns false) at the root or with no selection.
    bool select_parent();
 
    // ── Cursor affordances over the selected element ────────────────
    //
    // While dragging mode is on and a view is selected, hovering the
    // selection should reveal whether a press will MOVE vs RESIZE before the
    // user commits: a resize cursor (NW/NE/SW/SE diagonal) over a corner
    // handle, a move cursor (4-way) over the element body, and the default
    // cursor anywhere else. `cursor_affordance_at` is the pure hit-test that
    // resolves a root-coord point to the right CursorStyle; the host wires it
    // through View::set_inspector_cursor_hook so the platform layer applies
    // the NSCursor continuously on hover. Returns `default_` when there is no
    // selection, dragging is off, or the point is outside the selection (so
    // the host falls back to the normal hit-view cursor). Visible for tests.
    enum class CursorAffordance : std::uint8_t {
        none, move,
        resize_nw_se,   
        resize_ne_sw,   
        resize_ns,      
        resize_ew       
    };
    CursorAffordance cursor_affordance_at(Point pos) const;

    bool drop_indicator_active() const {
        return move_active_ && !move_float_ && drop_target_ != nullptr &&
               (drop_indicator_.width > 0 || drop_indicator_.height > 0);
    }

    int drop_index() const { return drop_index_; }
    bool drop_indicator_is_line() const { return drop_indicator_is_line_; }
    Rect drop_indicator_rect() const { return drop_indicator_; }
    const View* drop_target() const { return drop_target_; }
    int cursor_style_for(Point pos) const;
 
    // ── Per-pass GPU/render attribution viewer ───────────────────────
    //
    // The RenderPassManager already populates per-pass
    // `PassStats { type, draw_calls, time_ms }` every frame, but only
    // keeps the *last* frame. The attribution viewer accumulates a
    // rolling history (kPassHistoryFrames) per pass type so the panel
    // can show frame-over-frame trend + smoothed averages + a
    // budget-overrun event count.
    //
    // IMPORTANT (honesty about what's measured): `PassStats::time_ms`
    // is CPU wall-time around the pass's draw calls — NOT true GPU
    // time. The viewer labels its timings "cpu" so nobody mistakes them
    // for GPU-side numbers.

    struct PassAttribution {
        int type = 0;             
        const char* name = "";    
        bool present = false;     
        float last_cpu_ms = 0.0f; 
        float avg_cpu_ms = 0.0f;  
        float peak_cpu_ms = 0.0f; 
        int last_draw_calls = 0;  
        int peak_draw_calls = 0;  
        std::size_t samples = 0;  
    };

    static constexpr std::size_t kPassHistoryFrames = 60;

    bool capture_pass_frame();

    std::vector<PassAttribution> pass_attribution() const;

    int budget_overrun_count() const { return budget_overrun_count_; }

    std::uint64_t pass_frames_captured() const { return pass_frames_captured_; }

    void set_pass_viewer_enabled(bool enabled) { pass_viewer_enabled_ = enabled; }
    bool pass_viewer_enabled() const { return pass_viewer_enabled_; }
    void toggle_pass_viewer() { pass_viewer_enabled_ = !pass_viewer_enabled_; }
 
    // ── Color eyedropper ─────────────────────────────────────────────
    void set_eyedropper_active(bool active);
    bool eyedropper_active() const { return eyedropper_active_; }
    void toggle_eyedropper() { set_eyedropper_active(!eyedropper_active_); }

    Color eyedropper_sample() const { return eyedropper_sample_; }

    bool eyedropper_has_sample() const { return eyedropper_has_sample_; }

    const std::string& eyedropper_target() const { return eyedropper_target_; }
    void set_eyedropper_target(std::string path) {
        if (!path.empty()) eyedropper_target_ = std::move(path);
    }

    bool sample_color_at(Point pos, Canvas* canvas, Color& out) const;

    bool apply_eyedropper_pick();
 
    // ── Selection ───────────────────────────────────────────────────
    View* selected_view() const { return selected_; }
    View* hovered_view() const { return hovered_; }
 
    // ── Selection-mode toggle ────────────────────────────────────────
    enum class SelectionMode : std::uint8_t { follows_focus, follows_mouse };

    SelectionMode selection_mode() const { return selection_mode_; }
    void set_selection_mode(SelectionMode mode) { selection_mode_ = mode; }
    void toggle_selection_mode() {
        selection_mode_ = (selection_mode_ == SelectionMode::follows_focus)
                              ? SelectionMode::follows_mouse
                              : SelectionMode::follows_focus;
    }
 
    // ── Source-jump ──────────────────────────────────────────────────
    void set_config(InspectorConfig config) { config_ = std::move(config); }
    const InspectorConfig& config() const { return config_; }

    SourceJumpResult jump_to_selection_source(bool dry_run = true);
 
    // ── Live-editable box-model fields ──────────────────────────────
    //
    // Public read-only accessors for the editing state — used by tests
    // and by host-side cursor hints. The setter side is internal: edit
    // mode is entered by clicking on a numeric value in the property
    // panel and exited via Enter / Esc / Tab / blur.
    //
    // `editing_field()` returns the dotted property path of the field
    // currently being edited (e.g. "layout.padding"), or an empty
    // string when not editing. `edit_buffer()` is the live text the
    // user has typed so far (digits + optional sign / decimal); empty
    // until at least one character is entered. `edit_caret_pos()` is
    // the 0-based caret index into `edit_buffer()`.
    const std::string& editing_field() const { return editing_field_; }
    const std::string& edit_buffer() const { return edit_buffer_; }
    std::size_t edit_caret_pos() const { return edit_caret_pos_; }
    bool is_editing() const { return !editing_field_.empty(); }

    bool begin_field_edit(std::string field_path, float initial_value);

    bool commit_field_edit();

    void cancel_field_edit();
 
    // ── Inline text editing (Text tool) ──────────────────────────────
    //
    // Distinct from the numeric field edit above: this edits a
    // text-bearing View's COPY (Label / TextEditor) in place. The Text
    // tool (set_tool(Tool::text)) routes a canvas click on a text element
    // here; typing live-updates the View's text for an immediate preview,
    // Enter commits, Esc cancels. On commit the live text stays AND a
    // `text` content tweak is emitted via TweakStore as ONE undoable
    // EditHistory unit (Cmd+Z restores the prior text).
    //
    // `text_editing()` is true while an inline text edit is in progress;
    // `text_edit_buffer()` is the live edited copy; `text_edit_target()`
    // is the View being edited (or null). These are visible for tests +
    // host cursor hints.
    bool text_editing() const { return text_edit_target_ != nullptr; }
    const std::string& text_edit_buffer() const { return text_edit_buffer_; }
    View* text_edit_target() const { return text_edit_target_; }
 
    // Selection chrome predicate. While an inline text edit is active the
    // orange resize box + corner/edge handles would obstruct the
    // text being edited (and resize is meaningless mid-edit), so the selection
    // is drawn as a SUBTLE thin blue outline with NO handles. The Select tool
    // (move/resize) keeps the orange box + handles. This predicate reports
    // which chrome paint_highlight() draws for the selected element, so a
    // headless test can assert "Text-edit mode → no handles / subtle" vs
    // "Select mode → orange box + handles" without inspecting pixels.
    bool selection_shows_resize_handles() const {
        // Handles only ever paint in drag-handles mode AND never while a text
        // edit is active (the subtle-outline path owns the visuals then).
        return dragging_enabled_ && !text_editing();
    }

    bool selection_uses_subtle_edit_outline() const {
        return text_editing() && selected_ != nullptr &&
               selected_ == text_edit_target_;
    }

    static bool view_has_editable_text(const View* v);
    static std::string editable_text_of(const View* v);
    static void set_editable_text_of(View* v, const std::string& text);

    bool begin_text_edit(View* v);

    bool commit_text_edit();

    void cancel_text_edit();
 
    // ── In-place text-edit caret + selection ─────────────────────────
    //
    // The inline Text-tool edit keeps the LIVE View text (real-UI look —
    // no TextEditor widget chrome is swapped in). This layers TextEditor's
    // text-manipulation LOGIC on top: a caret index into the buffer, a
    // selection range, arrow / word / line caret movement, shift-select,
    // and Cmd+A/C/V/X clipboard. The caret + selection are painted as a
    // light overlay on the in-place text (see paint()), NOT as a styled
    // input box. Esc=cancel and Enter/click-away=commit are unchanged.

    std::size_t text_caret() const { return text_caret_; }
    std::pair<std::size_t, std::size_t> text_selection() const;
    bool text_has_selection() const { return text_caret_ != text_sel_anchor_; }

    void text_move_caret(int delta, bool extend);
    void text_move_word(int direction, bool extend);
    void text_move_home(bool extend);
    void text_move_end(bool extend);
    void text_select_all();
    bool text_copy();
    bool text_cut();
    bool text_paste();
    void text_insert(const std::string& utf8);
    void text_delete_backward();
    void text_delete_forward();

    const std::string& text_tweak_path() const { return text_tweak_path_; }
    void set_text_tweak_path(std::string path) {
        if (!path.empty()) text_tweak_path_ = std::move(path);
    }
 
    // ── Tweak management panel ───────────────────────────────────────
    //
    // A scrollable panel listing every tweak in the attached
    // TweakStore, grouped by anchor. Each tweak row carries three
    // per-tweak controls: bypass (eye), lock, and delete. Toggled with
    // `Shift+T` while the inspector is active (the bare `T` key now
    // selects the Figma-style Text tool). Default OFF so the inspector
    // layout is unchanged until the user opts in.
    void set_tweaks_panel_visible(bool visible) { tweaks_panel_visible_ = visible; }
    bool tweaks_panel_visible() const { return tweaks_panel_visible_; }
    void toggle_tweaks_panel() { tweaks_panel_visible_ = !tweaks_panel_visible_; }

    std::size_t tweak_row_count() const { return tweak_rows_.size(); }
 
    // ── Drift drawer ─────────────────────────────────────────────────
    //
    // A collapsible panel that lists tweaks whose anchor_id no longer
    // resolves to any live view (orphaned) or whose property path no
    // longer maps (drifted). It surfaces the silent-failure case where
    // a design re-import changed an element so a stored tweak quietly
    // stops applying. The drawer auto-expands the first time drift is
    // detected after a re-import; the user can collapse it with the
    // header chevron.

    void refresh_drift();

    std::size_t drift_count() const { return drifted_.size(); }

    bool drift_drawer_open() const { return drift_drawer_open_; }
    void set_drift_drawer_open(bool open) { drift_drawer_open_ = open; }
    void toggle_drift_drawer() { drift_drawer_open_ = !drift_drawer_open_; }

    const std::vector<TweakStore::DriftedTweak>& drifted() const {
        return drifted_;
    }
 
    // ── Reconciliation tab ───────────────────────────────────────────
    //
    // The reconciliation tab answers one question per tweak: "will this
    // edit survive a re-import?" It builds on lock-to-source and
    // source-jump data — it is a *read-only* report over the
    // existing TweakStore + live view tree, inventing no parallel data
    // model. Every stored tweak is classified into exactly one of three
    // reconciliation states:
    //
    //   * locked-to-source — the tweak's anchor is in the TweakStore
    //     lock set AND still resolves to a live view. It has been (or
    //     will be) promoted into the authored source, so it survives a
    //     fresh re-import. This is the "reconciled" state.
    //   * drifted — the tweak's anchor resolves to a live view but the
    //     anchor is NOT locked. The edit lives only in the runtime
    //     tweak layer (`pulp-tweaks.json`); a re-import that regenerates
    //     the element would not carry it. "Live-only, not written back."
    //   * unresolvable — no live view carries the tweak's anchor_id
    //     (orphaned, per TweakStore::DriftReason::anchor_not_found). The
    //     inspector cannot tell where this edit belongs; locking it is
    //     impossible until the anchor is re-established. Conservative
    //     fallback — never crash, never guess.
    //
    // The tab toggles with the `R` key (reconcile) and, when on, takes
    // over the property-panel region exactly like the pass attribution
    // viewer does — the tree section above stays put.

    enum class ReconcileStatus : std::uint8_t {
        locked_to_source,  
        drifted,           
        unresolvable,      
    };

    static const char* reconcile_status_str(ReconcileStatus status);

    struct ReconcileRow {
        std::string anchor_id;
        std::string property_path;
        ReconcileStatus status = ReconcileStatus::unresolvable;
    };

    struct ReconcileReport {
        std::vector<ReconcileRow> rows;
        std::size_t locked_count = 0;
        std::size_t drifted_count = 0;
        std::size_t unresolvable_count = 0;
 
        std::size_t total() const { return rows.size(); }
    };

    ReconcileReport reconcile_report() const;

    void set_reconcile_tab_visible(bool visible) {
        reconcile_tab_visible_ = visible;
    }
    bool reconcile_tab_visible() const { return reconcile_tab_visible_; }
    void toggle_reconcile_tab() {
        reconcile_tab_visible_ = !reconcile_tab_visible_;
    }

    std::size_t reconcile_row_count() const {
        return reconcile_rows_.size();
    }
 
    // ── Texture atlas viewer ─────────────────────────────────────────
    //
    // The render layer packs small bitmaps into a handful
    // of shelf-packed GPU texture atlases — the glyph atlas (SDF text),
    // the image atlas, the gradient ramp atlas, the path atlas. When an
    // atlas fills, rendering thrashes (evict + re-pack churn). The
    // atlas viewer answers "is my SDF atlas thrashing?" without leaving
    // the inspector.
    //
    // It is a *read-only* report over a render::AtlasInventory — a
    // value-snapshot collection the host wires in via
    // set_atlas_inventory(). The tab invents no parallel data model:
    // every per-atlas figure (dimensions, page count, occupancy, entry
    // count) comes straight from the Pulp-owned atlas classes'
    // introspection accessors. When no inventory is attached the tab
    // renders a graceful "GPU atlas unavailable" empty state.
    //
    // The tab toggles with the `A` key (atlas) and, when on, takes over
    // the property-panel region exactly like the pass attribution viewer
    // and reconciliation tab — the tree section above stays
    // put so the user keeps navigation context.

    void set_atlas_viewer_visible(bool visible) {
        atlas_viewer_visible_ = visible;
    }
    bool atlas_viewer_visible() const { return atlas_viewer_visible_; }
    void toggle_atlas_viewer() {
        atlas_viewer_visible_ = !atlas_viewer_visible_;
    }

    std::size_t atlas_row_count() const { return atlas_row_count_; }
 
    // ── 20× zoom loupe ───────────────────────────────────────────────
    //
    // A magnified-pixel preview panel ("loupe") that shows the region
    // under the cursor blown up by `zoom_factor_`. It complements the
    // eyedropper: where the eyedropper grabs a single pixel, the loupe
    // shows a grid of surrounding pixels with a center
    // crosshair so the user can align edges + verify color boundaries.
    //
    // Toggled with the `Z` key (drag=D, eyedropper=E, text=T, and
    // tweak-panel=Shift+T are already taken). When active, mouse-move re-centers the sampled
    // region on the cursor; paint() draws paint_zoom_panel() last so
    // the loupe sits on top of everything, including the props panel.
    //
    // Pixel source mirrors the eyedropper's dual path:
    //   - Skia raster surface  → Canvas::read_pixels() gives true RGBA
    //   - non-Skia / headless  → graceful degradation: the loupe still
    //     paints its frame + readout, filling the grid with the
    //     resolved background color of the View under the cursor (or a
    //     neutral checkerboard when that View has no background).
    bool zoom_active() const { return zoom_active_; }
    void set_zoom_active(bool active);
    void toggle_zoom() { set_zoom_active(!zoom_active_); }

    int zoom_factor() const { return zoom_factor_; }
    void set_zoom_factor(int factor);

    Point zoom_sample_center() const { return zoom_sample_center_; }

    Color zoom_center_color() const { return zoom_center_color_; }
 
private:
    View& root_;
    bool active_ = false;
 
    View* selected_ = nullptr;
    View* hovered_ = nullptr;
 
    // Distance measurement mode
    View* distance_anchor_ = nullptr;
 
    // Selection-mode toggle. follows_focus (default) keeps the
    // selection pinned until an explicit click; follows_mouse re-selects
    // the hovered View on every pointer-move. Toggled via the `M` hotkey.
    SelectionMode selection_mode_ = SelectionMode::follows_focus;
 
    // Alt-hover sibling distance (Figma-style spacing reveal).
    // Tracks the View under the cursor while Alt is held; cleared as soon
    // as Alt is released or the cursor leaves the view area. Distinct from
    // distance_anchor_ (which is Alt+click sticky-anchor mode).
    View* alt_hover_target_ = nullptr;
 
    // Panel layout
    float panel_width_ = 300.0f;
    float tree_scroll_y_ = 0.0f;
 
    // ── Editable-field state ─────────────────────────────────────────
    //
    // editing_field_ doubles as the "currently editing" flag and the
    // dotted property path (e.g. "layout.padding"). Empty = not
    // editing. edit_buffer_ holds the live numeric text the user has
    // typed; edit_caret_pos_ is a 0-based index into it. The original
    // value is captured at edit-begin time so Esc can revert without
    // re-querying the View (which may have been mutated by Yoga
    // reflow already).
    std::string editing_field_;
    std::string edit_buffer_;
    std::size_t edit_caret_pos_ = 0;
    float edit_original_value_ = 0.0f;
    View* edit_target_view_ = nullptr;  
 
    // ── Tool palette + inline text edit state ────────────────────────
    //
    // tool_ is the active canvas tool (Select default, Text). The Text
    // tool drives the inline-text-edit state below: text_edit_target_ is
    // the View whose copy is being edited (null = not editing),
    // text_edit_buffer_ is the live edited string, text_edit_original_ is
    // the copy at edit start (for Esc-cancel + undo). text_tweak_path_ is
    // the dotted path the committed copy is persisted under ("text").
    Tool tool_ = Tool::select;
    View* text_edit_target_ = nullptr;
    std::string text_edit_buffer_;
    std::string text_edit_original_;
    std::string text_tweak_path_ = "text";
 
    // Caret + selection over the live in-place edit buffer.
    // text_caret_ is the active caret byte-offset; text_sel_anchor_ is the
    // selection anchor (== caret when there is no selection). Both are kept
    // on UTF-8 codepoint boundaries. text_blink_ticks_ is a free-running
    // paint counter that drives the blink (no wall clock needed — works
    // headless); the caret shows while (ticks / kBlinkPeriod) is even.
    std::size_t text_caret_ = 0;
    std::size_t text_sel_anchor_ = 0;
    mutable std::uint32_t text_blink_ticks_ = 0;
 
    // Paint helper for the caret + selection highlight as a light
    // overlay on the live in-place edit (called from paint()).
    void paint_text_edit_overlay(Canvas& canvas);
 
    // Ordered list of editable fields populated during paint_props_section()
    // — used (a) for Tab to walk forward, and (b) for click hit-testing.
    struct EditableField {
        std::string path;   
        Rect bounds;        
        float value;        
    };
    std::vector<EditableField> editable_fields_;
 
    // ── Tweak management panel state ─────────────────────────────────
    //
    // The panel is laid out during paint_tweaks_section(); the row
    // hit-rects are stashed in tweak_rows_ so the SAME-frame mouse
    // handler can resolve a click to a (anchor, path, action). Each
    // row carries three 16×16 icon hit-rects: bypass / lock / delete.
    bool tweaks_panel_visible_ = false;
    float tweaks_scroll_y_ = 0.0f;
    enum class TweakAction : std::uint8_t { none, bypass, lock, remove };
    struct TweakRow {
        std::string anchor_id;     
        std::string property_path; 
        Rect bypass_icon;          
        Rect lock_icon;
        Rect delete_icon;
    };
    std::vector<TweakRow> tweak_rows_;
 
    // ── Semantic knobs + send-to-agent (tweaks-panel top region) ──────
    // The knob schema the panel renders; the current selection per knob id
    // (display only — the host owns authoritative state); and this frame's
    // knob hit-rects, stashed like tweak_rows_ so the SAME-frame mouse handler
    // can resolve a click to a (knob_id, value). The agent text field is a
    // single-line free-text buffer whose bounds + Send-button rect are captured
    // each paint for hit-testing.
    pulp::design::KnobSchema knob_schema_;
    std::function<void(const KnobApplyEdit&)> knob_apply_sink_ = nullptr;
    std::function<void(const AgentRequestEdit&)> agent_request_sink_ = nullptr;
    std::unordered_map<std::string, std::string> knob_selection_;
    std::vector<KnobHit> knob_hits_;
    bool agent_field_active_ = false;
    std::string agent_text_buffer_;
    std::size_t agent_caret_ = 0;
    Rect agent_field_bounds_{};
    Rect agent_send_bounds_{};
 
    // Tree expansion: collapsed nodes
    std::unordered_set<const View*> collapsed_;
 
    // Optional stats source
    render::RenderPassManager* rpm_ = nullptr;
 
    // ── Per-pass attribution history ─────────────────────────────────
    //
    // The RenderPassManager forgets everything but the current frame,
    // so the viewer keeps its own rolling buffers. There are exactly 5
    // RenderPassType values; each gets a fixed-size ring of CPU-time +
    // draw-call samples. Indexing the outer array by RenderPassType
    // (cast to size_t) keeps capture O(passes) with no allocation.
    static constexpr std::size_t kPassTypeCount = 5;
    struct PassRing {
        std::array<float, kPassHistoryFrames> cpu_ms{};
        std::array<int, kPassHistoryFrames> draw_calls{};
        std::size_t count = 0;  
        std::size_t head = 0;   
        // Whether this pass type appeared in the most recently captured
        // frame — distinguishes "no history" from "history but absent
        // this frame" so the panel can dim a pass that just went quiet.
        bool present_last_frame = false;
    };
    std::array<PassRing, kPassTypeCount> pass_rings_{};
    int budget_overrun_count_ = 0;
    std::uint64_t pass_frames_captured_ = 0;
    // Last frame_count() observed from the RPM — capture is a no-op if
    // the manager hasn't advanced a frame, so multiple paints of the
    // same frame don't inflate the history with duplicates.
    std::uint64_t last_captured_frame_ = 0;
    bool pass_viewer_enabled_ = false;
 
    // Optional in-process gesture-tweak persistence.
    // When null, emit_tweak_for_selection() is a no-op.
    TweakStore* tweak_store_ = nullptr;
 
    // Optional EditHistory. When null, gestures
    // apply exactly as before with no undo entry pushed. See
    // set_edit_history().
    pulp::state::EditHistory* edit_history_ = nullptr;
 
    // Optional sink for promoting a live structural reparent into
    // the generated source. When null (the default), a reparent affects only
    // the live tree + EditHistory; the structural edit is not locked to source.
    // See set_reparent_source_sink().
    std::function<void(const ReparentSourceEdit&)> reparent_source_sink_ = nullptr;
 
    // ── Gesture undo helpers ─────────────────────────────────────────
    //
    // A snapshot of every live View layout input a gesture mutates, plus
    // the prior TweakStore value for each path the gesture writes (so undo
    // can apply-or-remove). Captured at gesture START, consumed at COMMIT
    // when building the EditHistory entry's undo lambda.
    struct LayoutSnapshot {
        // Resize inputs.
        float preferred_width = 0.0f;
        float preferred_height = 0.0f;
        Dimension dim_width{};
        Dimension dim_height{};
        // Move inputs.
        View::Position position = View::Position::static_;
        float left = 0.0f;
        float top = 0.0f;
        DimensionUnit left_unit = DimensionUnit::px;
        DimensionUnit top_unit = DimensionUnit::px;
        bool has_left = false;
        bool has_top = false;
        // Content scale (proportional resize via View::set_scale()).
        float scale = 1.0f;
        // Transform-origin + overflow captured so undo of a proportional
        // resize also reverts the top-left scale anchor and
        // the box-clip we apply to keep scaled content inside the box.
        float origin_x = 0.5f;
        float origin_y = 0.5f;
        View::Overflow overflow = View::Overflow::visible;
        // Resolved bounds at capture (so undo restores the local paint box
        // before Yoga's next layout pass overwrites it).
        Rect bounds{};
    };
 
    // Per-path prior-value capture: nullopt means "no tweak existed, so
    // undo must remove_tweak"; a value means "restore via apply_tweak".
    struct PriorTweak {
        std::string path;
        std::optional<choc::value::Value> value;
    };
 
    // Capture the resize-relevant View inputs of the selected view.
    LayoutSnapshot snapshot_layout(const View* v) const;
    // Restore a previously-captured snapshot onto `v` (resize fields only
    // for resize undo, plus position/insets for move undo). Re-applies the
    // captured bounds and invalidates layout.
    void restore_layout(View* v, const LayoutSnapshot& s) const;
    // Capture the current TweakStore values for `paths` under `anchor`.
    std::vector<PriorTweak> snapshot_tweaks(
        std::string_view anchor,
        const std::vector<std::string>& paths) const;
    // Apply a previously-captured prior-tweak list: restore-or-remove each.
    void restore_tweaks(std::string_view anchor,
                        const std::vector<PriorTweak>& prior,
                        std::string_view source) const;
 
    // Resize gesture-start captures (consumed at resize commit to build the
    // EditHistory entry). Populated alongside drag_start_pref_w_/h_.
    LayoutSnapshot resize_before_layout_{};
    std::vector<PriorTweak> resize_before_tweaks_;
    std::string resize_anchor_;
 
    // Move gesture-start captures (consumed at move commit).
    LayoutSnapshot move_before_layout_{};
    std::vector<PriorTweak> move_before_tweaks_;
    std::string move_anchor_;
 
    // Editor-URL config for the `J` source-jump hotkey.
    // Defaults to the built-in VS Code template; the env override
    // (PULP_INSPECTOR_EDITOR_URL) still applies at jump time.
    InspectorConfig config_{};
 
    // ── Drift-drawer state ───────────────────────────────────────────
    //
    // drifted_ is the cached drift list from the last refresh_drift().
    // drift_drawer_open_ tracks the expand/collapse state; it flips to
    // true automatically the first time drift is detected (so a stale
    // tweak is never silent), and the user can collapse it after.
    // drift_refreshed_once_ guards the first-paint auto-refresh so the
    // drawer is populated even if the host never calls refresh_drift()
    // explicitly.
    std::vector<TweakStore::DriftedTweak> drifted_;
    bool drift_drawer_open_ = false;
    bool drift_refreshed_once_ = false;
    // Hit-rect of the drift drawer header chevron from the last paint,
    // in root coords — used by handle_mouse_event() to toggle the
    // drawer. width==0 means "not painted this frame".
    Rect drift_header_hit_{};
 
    // ── Reconciliation-tab state ─────────────────────────────────────
    //
    // reconcile_tab_visible_ tracks the R-key toggle; off by default so
    // the panel layout is unchanged until the user opts in.
    // reconcile_rows_ caches the rows the tab laid out on the last
    // paint so reconcile_row_count() can report them to tests and the
    // tab scroll stays stable across frames.
    bool reconcile_tab_visible_ = false;
    float reconcile_scroll_y_ = 0.0f;
    std::vector<ReconcileRow> reconcile_rows_;
 
    // ── Texture-atlas-viewer state ───────────────────────────────────
    //
    // atlas_viewer_visible_ tracks the `A`-key toggle; off by default
    // so the panel layout is unchanged until the user opts in.
    // atlas_inventory_ is a non-owning pointer to the render layer's
    // snapshot collection (nullptr → graceful empty state).
    // atlas_scroll_y_ keeps the row list stable across frames;
    // atlas_row_count_ caches how many rows the last paint laid out so
    // atlas_row_count() can report it to tests without scraping pixels.
    bool atlas_viewer_visible_ = false;
    const render::AtlasInventory* atlas_inventory_ = nullptr;
    float atlas_scroll_y_ = 0.0f;
    std::size_t atlas_row_count_ = 0;
 
    // Drag-handles state. Off by default so the inspector behaves
    // identically until the user opts in (D-key toggle in handle_key_event).
    bool dragging_enabled_ = false;
    // Resize handles: four corners + four edge midpoints. Edge handles
    // resize a single axis (n/s → height, e/w → width); corner handles
    // resize both. Edge handles let the selection box resize from any
    // side, not only the corners, and let each zone drive a
    // context-aware resize cursor.
    enum class DragCorner : std::uint8_t {
        none, nw, ne, sw, se, n, s, e, w
    };
    DragCorner active_drag_ = DragCorner::none;
    Point drag_start_pos_{};         // mouse pos when drag began (root coords)
    Rect drag_start_bounds_{};       // selected_->bounds() snapshot
    float drag_start_pref_w_ = 0.0f; // flex().preferred_width snapshot
    float drag_start_pref_h_ = 0.0f; // flex().preferred_height snapshot
 
    // ── Proportional (Shift) resize ──────────────────────────────────
    //
    // Plain corner-drag resizes the box (children reflow). Shift +
    // corner-drag scales the container's
    // CONTENT proportionally — a uniform View::set_scale() on the
    // selected view tied to the box delta, so the panel keeps its
    // internal proportions instead of just stretching the box. We track
    // whether the active resize is proportional and the content scale at
    // gesture start so undo restores it exactly.
    bool resize_proportional_ = false;   // Shift held when this resize began
    float drag_start_scale_ = 1.0f;      // selected_->scale() at gesture start
 
    // Returns the corner whose 8px handle hit-rectangle contains `pos`,
    // for the currently-selected view (root coords). Returns
    // DragCorner::none if no handle is hit or no view selected.
    DragCorner hit_test_drag_handle(Point pos) const;
 
    // Map a resize-handle corner/edge to its cursor affordance. Pure
    // helper shared by cursor_affordance_at's active-drag pin and
    // idle-hover paths. Declared after DragCorner so the
    // return/parameter types are complete at the declaration point.
    static CursorAffordance affordance_for_corner(DragCorner c);
 
    // ── Minimal manipulate layer ─────────────────────────────────────
    // When true, paint() draws only the selection box + handles (no dev
    // side-panel) and point_in_panel() reports false everywhere. See
    // set_manipulate_only().
    bool manipulate_only_ = false;
 
    // ── Drag-to-move gesture state ───────────────────────────────────
    //
    // A body-drag (mouse-down on the selected view's body, NOT a resize
    // handle) repositions the view via position:absolute + left/top.
    // Mirrors the resize state machine: press starts, every
    // is_down=false event live-updates and overwrites the tweaks, the
    // next is_down=true ends the gesture. The three move tweaks
    // (layout.position / layout.left / layout.top) land in a single
    // atomic TweakStore batch each tick.
    bool move_active_ = false;            // a move gesture is in progress
    bool move_refused_grid_ = false;      // last body-press was refused (grid parent)
    Point move_start_pos_{};              // mouse pos when move began (root coords)
    float move_seed_left_ = 0.0f;         // seeded left at conversion (no delta)
    float move_seed_top_ = 0.0f;          // seeded top at conversion (no delta)
 
    // ── Drag ghost for smooth reflow-move tracking ───────────────────
    //
    // A reflow (non-float) move does NOT mutate the live layout while
    // dragging — the dragged element stays in flow and only the drop
    // indicator moves. Without a follower, the element appears to do
    // nothing and then teleport to the drop slot on release. To make the
    // drag track the cursor
    // fluidly we paint a translucent GHOST of the dragged element that
    // follows the pointer with a STABLE grab offset (the delta between the
    // press point and the element's top-left), so there is no teleport on
    // grab and no per-tick jitter — the ghost is pure paint, no relayout.
    // move_grab_offset_ is (press - element-origin) captured once at press;
    // move_ghost_ is the element's size, also captured at press so the
    // ghost keeps a constant size even though no relayout runs.
    Point move_grab_offset_{};            // press point minus element origin
    Rect move_ghost_{};                   // element bounds snapshot at press
    Point move_cursor_{};                 // latest cursor pos during the drag
 
    // ── Reflow-aware move ────────────────────────────────────────────
    //
    // The default body-drag is reflow-aware, not free-absolute: during
    // the drag we resolve a drop
    // target (an insertion point between flex siblings, or a container to
    // drop INTO) and on release we reorder via flex().order and/or
    // reparent via remove_child/add_child, then the tree reflows. The
    // free-absolute float (position:absolute + left/top) is the explicit
    // ⌘-drag escape hatch.
    //
    // move_float_ is true for a ⌘-drag (absolute float). When false, the
    // gesture is reflow-aware and the drop-target fields below describe
    // where a release would land.
    bool move_float_ = false;
 
    // The container the cursor is currently over for a reflow drop, and
    // the insertion index among that container's children (0..count).
    // When drop_inside_ is true the element reparents INTO drop_target_
    // (appended / inserted at drop_index_); when false it reorders among
    // drop_target_'s existing children at drop_index_. null target = no
    // valid drop resolved this tick (release is a no-op reflow).
    View* drop_target_ = nullptr;
    int drop_index_ = 0;
    bool drop_inside_ = false;
    // Geometry of the drop affordance in root coords, computed each move
    // tick for paint(): an insertion LINE (zero-area rect along an edge)
    // when reordering, or a container HIGHLIGHT rect when dropping inside.
    Rect drop_indicator_{};
    bool drop_indicator_is_line_ = false;
 
    // Resolve the drop target for the current cursor position during a
    // reflow move. Walks the tree for the deepest flex container under
    // the cursor (excluding the dragged subtree), picks an insertion gap
    // among its children by the cursor's main-axis position, and fills
    // drop_target_ / drop_index_ / drop_inside_ / drop_indicator_*.
    void resolve_drop_target(Point pos);
    // Commit the resolved reflow drop: reorder (rewrite flex().order) or
    // reparent (remove_child + add_child at drop_index_). Returns true if
    // the tree actually changed. Normalizes sibling order on success.
    bool commit_reflow_drop(View* dragged);
    // True if `ancestor` is `v` or an ancestor of `v` — guards against
    // dropping a node into its own subtree.
    static bool is_self_or_ancestor(const View* ancestor, const View* v);
 
    // Structural primitive: detach `v` from its current parent and insert
    // it into `new_parent` at child index `index` (clamped). When the view
    // is already a child of new_parent the index is honored (reorder by
    // insertion position). No-op when v / new_parent is null. Used by the
    // reflow commit and by undo/redo to round-trip a reparent. Updates
    // selected_ to keep pointing at the moved view (its address is stable —
    // ownership transfers via unique_ptr, the View itself is not copied).
    void reparent_view(View* v, View* new_parent, int index);
 
    // True if `pos` (root coords) is inside the selected view's body but
    // NOT on a resize handle — the body-drag trigger for a move.
    bool hit_test_body(Point pos) const;
 
    // Resolve the containing block Yoga uses for the selected view's
    // absolute insets: the nearest ancestor View whose position is NOT
    // static_/relative-mapped-as-static (i.e. relative/absolute/fixed),
    // else the root. Returns the ancestor and its origin in root coords.
    // Because Pulp maps static_ -> Yoga Relative, in practice the
    // immediate parent is almost always the containing block.
    const View* containing_block_of(const View* v, Rect& block_root_out) const;
 
    // Seed left/top so converting `v` to absolute does not visually jump,
    // using the border-edge formula:
    //   left = childRootX - blockRootX - blockBorderLeft - childMarginLeft
    //   top  = childRootY - blockRootY - blockBorderTop  - childMarginTop
    // Writes the seed into move_seed_left_ / move_seed_top_.
    void seed_move_origin(const View* v);
 
    // Whether the selected view's PARENT is a grid container — a move is
    // refused for grid children (grid ignores position/top/left today).
    bool selected_parent_is_grid() const;
 
    // ── Color eyedropper state ───────────────────────────────────────
    // Off by default so the inspector behaves identically until the
    // user opts in (E-key toggle).
    bool eyedropper_active_ = false;
    bool eyedropper_has_sample_ = false;
    Color eyedropper_sample_{0.0f, 0.0f, 0.0f, 0.0f};
    Point eyedropper_cursor_{};  
    std::string eyedropper_target_ = "style.background_color";
 
    // Walk from the View under `pos` up to the nearest ancestor that
    // has an explicit background color; returns that color. Returns
    // false when no view under the cursor carries a background — the
    // resolved-style fallback used when Canvas pixel readback is
    // unavailable.
    bool resolved_color_under(Point pos, Color& out) const;
 
    // Paint the cursor-following swatch + hex readout. No-op unless
    // eyedropper mode is active and at least one sample has landed.
    void paint_eyedropper_cursor(Canvas& canvas);
 
    // ── Zoom loupe state ─────────────────────────────────────────────
    // Off by default; the inspector behaves identically to the
    // normal inspector until the user opts in via the Z-key toggle.
    bool zoom_active_ = false;
    int zoom_factor_ = 20;                    
    Point zoom_sample_center_{};              
    Color zoom_center_color_{};               
    bool zoom_center_from_readback_ = false;   
 
    // Recompute zoom_center_color_ for the current zoom_sample_center_,
    // sampling `canvas` via read_pixels() when the surface supports it
    // and falling back to the resolved View color otherwise. Sets
    // zoom_center_from_readback_ to record which path was taken.
    void update_zoom_sample(Canvas& canvas);
    // Resolve the on-screen color at root-coord point `p` WITHOUT a
    // pixel readback — walks the view tree top-most-first and returns
    // the deepest hit View's background color. Returns false (and
    // leaves `out` untouched) when no background-bearing view is hit.
    bool resolve_view_color_at(Point p, Color& out) const;
 
    // ── Flat tree for rendering ─────────────────────────────────────
    struct TreeItem {
        const View* view;
        int depth;
    };
    std::vector<TreeItem> flat_tree_;
    void rebuild_flat_tree();
 
    // text_edit_target_ is a raw View*. If the edited
    // Label/TextEditor is destroyed mid-edit (e.g. a live React tree
    // rebuild), every subsequent text op (handle_text_input, Backspace,
    // commit/cancel) would deref freed memory. These guards keep the
    // text-edit state coherent with the live tree:
    //   - text_edit_target_reachable() walks from root_ to confirm the
    //     target is still attached (does NOT deref the target itself).
    //   - clear_text_edit_state() drops the target + buffers WITHOUT
    //     touching the (possibly freed) view.
    bool text_edit_target_reachable() const;
    void clear_text_edit_state();
 
    // Resolve a live View by its stable anchor id at
    // undo/redo time. The text-edit and reparent EditHistory closures used to
    // capture raw `View*` (e.g. `View* tgt = selected_;`). When a live React
    // SUBTREE rebuilds before the user hits Cmd+Z — which clear_edit_history()
    // does NOT cover, since it only fires at ROOT replacement — those pointers
    // dangle and undo derefs freed memory. Anchored captures now store the
    // anchor id and re-find the live view here (nullptr → graceful no-op).
    // Returns nullptr for an empty anchor or a view no longer in the tree.
    View* resolve_anchor(const std::string& anchor) const;
 
    // The anchor of the visible sibling immediately preceding
    // `child` under `parent` in flex-order (or "" when `child` is the first
    // child / parent is null / the preceding sibling is un-anchored). Used to
    // carry the requested insertion slot in ReparentSourceEdit so the source
    // rewrite drops the moved block at the dragged position, not first-child.
    static std::string preceding_sibling_anchor(const View* parent,
                                                 const View* child);
 
    // Un-anchored fallback. Some edited/reparented views
    // carry NO anchor (e.g. a --script Chainer label), so they cannot be
    // re-found by anchor. For those we keep the raw-pointer capture but RECORD
    // the pointer here; rebuild_flat_tree() clears the WHOLE EditHistory if any
    // tracked raw view left the tree, before its closures can deref it. Anchored
    // captures never go in this set (they self-heal via resolve_anchor).
    std::vector<View*> raw_history_views_;
    void track_raw_history_view(View* v);
    bool any_raw_history_view_dangling() const;
 
    // ── Gesture undo target ──────────────────────────────────────────
    //
    // Every per-gesture EditHistory closure that mutates a captured View
    // must survive a live React SUBTREE rebuild between capture and Cmd+Z:
    // clear_edit_history() only fires at ROOT replacement, so a bare `View*`
    // held in a closure can dangle. GestureUndoTarget centralizes the one
    // dangling-mitigation rule that the text-edit and reparent sites
    // hand-rolled — and that the resize + move-float sites historically
    // LACKED, a latent use-after-free. It holds the stable anchor when the
    // view has one (re-found via resolve_anchor() at replay) and falls back
    // to the raw pointer, TRACKED via track_raw_history_view() so
    // rebuild_flat_tree() clears the history if it leaves the tree. resolve()
    // returns nullptr for a freed/unresolvable target so a closure can no-op
    // gracefully. Copyable (an EditHistory closure captures it by value).
    struct GestureUndoTarget {
        View* raw = nullptr;
        std::string anchor;
        bool anchored = false;
        // Re-find the live view at replay time. A nested type may touch the
        // enclosing class's private resolve_anchor().
        View* resolve(const InspectorOverlay& ov) const {
            return anchored ? ov.resolve_anchor(anchor) : raw;
        }
    };
    // Capture `v` as a gesture undo target. `anchored_gate` lets a site keep
    // its own notion of when the anchored replay path applies (the text-edit
    // site ties it to a wired TweakStore); the target is anchored only when
    // the gate holds AND the view carries a non-empty anchor id. Tracks the
    // raw pointer when the target is NOT anchored so the rebuild seam can
    // clear the history before a dangling closure runs.
    GestureUndoTarget capture_undo_target(View* v, bool anchored_gate = true);
 
    // ── Coordinate helpers ──────────────────────────────────────────
    Rect view_bounds_in_root(const View* v) const;
 
    // Effective on-screen scale of `v`, the product of
    // its own View::scale() and every ancestor's scale up to (but excluding)
    // root_. View::paint_all renders a subtree under each ancestor's
    // `scale(s,s)`, so a glyph at element-local distance d renders d*eff_scale
    // wide on screen. The inline-text-edit caret/selection overlay multiplies
    // the unscaled Label::text_edit_metrics by this factor so the caret tracks
    // the rendered glyphs after a proportional (Shift) resize, which sets
    // View::set_scale() rather than growing bounds. Returns 1.0 for an
    // untransformed chain.
    float effective_scale_in_root(const View* v) const;
 
    // ── Paint helpers ───────────────────────────────────────────────
    void paint_highlight(Canvas& canvas);
    // Paint the reflow-move drop affordance: a blue insertion line
    // between siblings (reorder) or a translucent container highlight
    // (drop-inside). No-op when no reflow move is in progress / no drop
    // target resolved.
    void paint_drop_indicator(Canvas& canvas);
    // Paint the translucent drag ghost that follows the cursor
    // during a reflow (non-float) move, giving the move smooth cursor
    // tracking without any per-tick relayout. No-op when no reflow move is
    // active.
    void paint_drag_ghost(Canvas& canvas);
    void paint_distance_lines(Canvas& canvas);
    void paint_box_model(Canvas& canvas, const View* v);
    void paint_panel(Canvas& canvas);
    void paint_tree_section(Canvas& canvas, float x, float y, float w, float& cursor_y);
    void paint_props_section(Canvas& canvas, float x, float y, float w, float h);
    void paint_stats_bar(Canvas& canvas, float x, float y, float w);
    void paint_pass_attribution(Canvas& canvas, float x, float y, float w, float h);
    float paint_drift_drawer(Canvas& canvas, float x, float y, float w);
    // Magnified-pixel loupe. Draws a fixed-corner panel with
    // a grid of `zoom_factor_`-scaled pixels sampled around the cursor,
    // a center crosshair marking the sample pixel, and a coordinate +
    // hex color readout strip beneath the grid.
    void paint_zoom_panel(Canvas& canvas);
 
    // Render the tweak management panel into the given
    // rect. Repopulates tweak_rows_ with this frame's hit-rects.
    void paint_tweaks_section(Canvas& canvas, float x, float y, float w, float h);
 
    // Render the semantic-knob controls + send-to-agent text field at the top of
    // the tweaks panel. Repopulates knob_hits_ and the agent field/send rects
    // with this frame's hit-rects. Returns the vertical space used so the tweak
    // list below can start beneath it. Paints nothing (returns 0) when there are
    // no knobs and no agent sink.
    float paint_knob_controls(Canvas& canvas, float x, float y, float w, float h);
 
    // Resolve a click in the tweaks panel against this frame's knob controls /
    // agent field. Returns true when the click was consumed (a knob was set, the
    // field focused, or Send pressed). Fires the relevant sink.
    bool handle_knob_panel_click(Point p);
 
    // Submit the current agent text buffer through the agent-request sink (when
    // non-empty and a sink is attached), then clear + defocus the field.
    void submit_agent_request();

    void paint_reconcile_tab(Canvas& canvas, float x, float y, float w, float h);

    void paint_atlas_tab(Canvas& canvas, float x, float y, float w, float h);
 
    // ── Mouse-event precedence chain ─────────────────────────────────
    //
    // handle_mouse_event() resolves the event's gesture phase ONCE, then
    // offers it to the handlers below in a fixed order. Modality
    // precedence — text tool over eyedropper, an in-flight gesture over a
    // fresh press, the panel over the canvas — IS that order.
    //
    // A handler returns a value to CONSUME the event (the bool is what
    // handle_mouse_event returns) or std::nullopt to decline and let the
    // next one look. Declining is not the same as not acting: a handler
    // may update state and still fall through, which is how a resize
    // release commits and then lets the same click re-select.

    struct MouseGesture {
        const MouseEvent& event;
        Point pos;
        bool is_press;
        bool is_drag_tick;
        bool is_release;
    };

    MouseGesture resolve_mouse_gesture(const MouseEvent& event) const;
 
    std::optional<bool> mouse_text_tool(const MouseGesture& g);
    void mouse_zoom_loupe(const MouseGesture& g);
    std::optional<bool> mouse_eyedropper(const MouseGesture& g);
    std::optional<bool> mouse_active_resize(const MouseGesture& g);
    std::optional<bool> mouse_begin_resize(const MouseGesture& g);
    std::optional<bool> mouse_active_move(const MouseGesture& g);
    std::optional<bool> mouse_begin_move(const MouseGesture& g);
    std::optional<bool> mouse_panel(const MouseGesture& g);
    std::optional<bool> mouse_select(const MouseGesture& g);
 
    // ── Panel hit testing ───────────────────────────────────────────
    bool point_in_panel(Point p) const;
    const TreeItem* tree_item_at_y(float panel_y) const;
 
    // Resolve a root-coord point to a tweak-row icon hit.
    // Sets `out_row` to the matching row index and returns the action;
    // returns TweakAction::none (out_row untouched) on a miss. Called
    // by handle_mouse_event() before the tree-selection fallthrough.
    TweakAction tweak_action_at(Point p, std::size_t& out_row) const;
 
    // ── Editable-field helpers ───────────────────────────────────────
    int editable_field_at(Point p) const;
    bool handle_edit_key(const KeyEvent& event);
    void apply_edit_buffer_to_view();
    float read_field_value(std::string_view field_path) const;
    void write_field_value(std::string_view field_path, float value);
 
    // ── Constants ───────────────────────────────────────────────────
    static constexpr float kRowHeight = 20.0f;
    static constexpr float kIndent = 16.0f;
    static constexpr float kFontSize = 11.0f;
    static constexpr float kStatsBarHeight = 24.0f;
 
    // Zoom loupe layout. The loupe samples a square grid of
    // kZoomGridCells × kZoomGridCells source pixels (odd so there's an
    // exact center pixel) and renders each at zoom_factor_ scale. The
    // panel sits in a fixed corner with a readout strip beneath.
    static constexpr int   kZoomGridCells   = 11;   
    static constexpr int   kZoomFactorMin   = 4;
    static constexpr int   kZoomFactorMax   = 40;
    static constexpr float kZoomReadoutH    = 36.0f;
    static constexpr float kZoomPanelMargin = 12.0f;
};

bool apply_move_tweak_to_view(View& view,
                              std::string_view property_path,
                              const choc::value::Value& value);

struct BadgePlacement {
    float x = 0.0f;
    float y = 0.0f;
    bool below = false;  
};

BadgePlacement compute_badge_placement(float sel_x, float sel_y, float sel_h,
                                       float badge_w, float badge_h,
                                       float root_w,
                                       float gap = 5.0f,
                                       float top_margin = 0.0f);

inline InspectorOverlay* g_active_inspector = nullptr;

void install_inspector_hooks(InspectorOverlay& inspector);

void uninstall_inspector_hooks();
 
} // namespace pulp::inspect