widgets.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <pulp/canvas/attributed_string.hpp>
#include <pulp/canvas/text_shaper.hpp> // canvas::ShapedLayout for Label's shaped-layout cache
#include <pulp/view/accessibility.hpp>
#include <pulp/view/animation.hpp>
#include <pulp/view/text_line_metrics.hpp>
#include <pulp/view/inspector_facts.hpp>
#include <pulp/view/data_display.hpp>
#include <pulp/view/caret.hpp>
#include <pulp/view/custom_shader_host.hpp>
#include <pulp/view/frame_clock.hpp>
#include <pulp/view/hit_metrics.hpp>
#include <pulp/view/selectable_text.hpp>
#include <pulp/view/slider_core.hpp>
#include <pulp/view/sprite_strip.hpp>
#include <pulp/view/value_source.hpp>
#include <pulp/view/view.hpp>
#include <pulp/view/widget_painter.hpp>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::view {
 
class TextEditor;   // pulp/view/text_editor.hpp — the Label's inline edit field
 
// ── Label ────────────────────────────────────────────────────────────────────
// Static or dynamic text display

enum class LabelAlign { left, center, right, auto_, justify, match_parent };
 
class Label : public View, public SelectableText {
  public:
    Label() { set_access_role(AccessRole::label); }
    explicit Label(std::string text) : text_(std::move(text)) {
        set_access_role(AccessRole::label);
        set_derived_access_label(text_);
    }
 
    // Changes the copy. Requests paint only when no layout output can depend
    // on it; otherwise invalidates layout as well.
    void set_text(std::string text);
    const std::string& text() const { return text_; }
 
    // Per-range styled text (design-import mixed text). Every line shape and
    // paint path retains the spans; captured lines and responsive reflow share
    // the same attributed renderer.
    void set_attributed_string(canvas::AttributedString a) {
        attributed_runs_ = std::move(a);
        has_attributed_ = !attributed_runs_.spans().empty();
        // A run mutation changes advances independently of the Label-wide
        // typography captured in set_cached_line_boxes(). Callers that want to
        // install both must set the runs first and the captured basis second.
        cached_line_boxes_.clear();
        shaped_cache_valid_ = false;
        invalidate_layout();
    }
    void clear_attributed_string() {
        has_attributed_ = false;
        cached_line_boxes_.clear();
        shaped_cache_valid_ = false;
        invalidate_layout();
    }
    bool has_attributed_string() const { return has_attributed_; }
    std::size_t attributed_span_count() const { return attributed_runs_.spans().size(); }
 
    // Each setter marks the corresponding has_own_* flag so
    // paint() can distinguish "default value" from "explicitly set" and
    // fall through to inheritable_*() for unset properties.
    // Typography that feeds the shaper's cache key — size, family, weight,
    // style, letter spacing, line height, wrap mode, case transform — decides
    // this Label's measured box, so changing it is a geometry mutation and has
    // to advance the layout generation. Both layout gates
    // (View::layout_children_if_needed and WidgetBridge::ensure_layout) elide
    // the pass while the applied generation matches the tree's, so a setter
    // that stays silent here leaves the Label painting at the box its PREVIOUS
    // typography solved to, and leaves every ancestor sized for it.
    //
    // Each setter is guarded on an actual change. A materialized React commit
    // replays an element's complete style object when only paint state moved;
    // dirtying the tree for an identical write would make every following
    // geometry read pay for a full Yoga pass, which is the same contract
    // flex_styles_equal keeps on the flex path.
    void set_font_size(float size) {
        if (has_own_font_size_ && font_size_ == size)
            return;
        font_size_ = size;
        has_own_font_size_ = true;
        invalidate_layout();
    }
    float font_size() const { return font_size_; }
    bool has_own_font_size() const { return has_own_font_size_; }

    void set_font_family(std::string family) {
        if (font_family_ == family)
            return;
        font_family_ = std::move(family);
        invalidate_layout();
    }
    const std::string& font_family() const { return font_family_; }
 
    // 100-900, 400=normal, 700=bold
    void set_font_weight(int weight) {
        if (has_own_font_weight_ && font_weight_ == weight)
            return;
        font_weight_ = weight;
        has_own_font_weight_ = true;
        invalidate_layout();
    }
    int font_weight() const { return font_weight_; }
    bool has_own_font_weight() const { return has_own_font_weight_; }
 
    // 0=normal, 1=italic, 2=oblique
    void set_font_style(int style) {
        if (font_style_ == style)
            return;
        font_style_ = style;
        invalidate_layout();
    }
    int font_style() const { return font_style_; }
 
    void set_letter_spacing(float sp) {
        if (has_own_letter_spacing_ && letter_spacing_ == sp)
            return;
        letter_spacing_ = sp;
        has_own_letter_spacing_ = true;
        invalidate_layout();
    }
    float letter_spacing() const { return letter_spacing_; }
    bool has_own_letter_spacing() const { return has_own_letter_spacing_; }

    void set_font_smoothing(canvas::FontSmoothing smoothing) {
        if (font_smoothing_ == smoothing)
            return;
        font_smoothing_ = smoothing;
        request_repaint();
    }
    canvas::FontSmoothing font_smoothing() const {
        return font_smoothing_;
    }
 
    void set_line_height(float lh) {
        if (line_height_ == lh)
            return;
        line_height_ = lh;
        invalidate_layout();
    }
    float line_height() const { return line_height_; }
 
    void set_text_align(LabelAlign align) { text_align_ = align; has_own_text_align_ = true; }
    LabelAlign text_align() const { return text_align_; }
    bool has_own_text_align() const { return has_own_text_align_; }
 
    // Explicit text color override on the Label itself. When
    // set, overrides any inherited typography color and the theme token.
    void set_text_color(canvas::Color c) { text_color_ = c; has_own_text_color_ = true; }
    bool has_own_text_color() const { return has_own_text_color_; }
    canvas::Color text_color() const { return text_color_; }
 
    void set_multi_line(bool ml) {
        if (multi_line_ == ml)
            return;
        multi_line_ = ml;
        invalidate_layout();
    }
    bool multi_line() const { return multi_line_; }

    bool soft_wraps() const { return multi_line_ && !inherits_nowrap(); }
    bool inherits_nowrap() const;

    void set_line_clamp(int n) { line_clamp_ = (n < 0) ? 0 : n; }
    int line_clamp() const { return line_clamp_; }

    enum class TextTransform { none, uppercase, lowercase, capitalize };
    void set_text_transform(TextTransform t) {
        if (text_transform_ == t)
            return;
        text_transform_ = t;
        invalidate_layout();
    }
    TextTransform text_transform() const { return text_transform_; }

    enum class TextDecoration { none, underline, line_through, overline };
    void set_text_decoration(TextDecoration d) { text_decoration_ = d; }
    TextDecoration text_decoration() const { return text_decoration_; }
    void set_text_decoration_color(canvas::Color c) { decoration_color_ = c; has_decoration_color_ = true; }
    canvas::Color text_decoration_color() const { return decoration_color_; }
    bool has_text_decoration_color() const { return has_decoration_color_; }

    enum class TextDecorationStyle { solid, double_, dotted, dashed, wavy };
    void set_text_decoration_style(TextDecorationStyle s) { text_decoration_style_ = s; }
    TextDecorationStyle text_decoration_style() const { return text_decoration_style_; }
 
    void paint(canvas::Canvas& canvas) override;

    Rect own_text_box() const { return own_text_box_; }
    bool has_own_text_box() const { return own_text_box_.width >= 0.0f; }
    void set_own_text_box(Rect box) { own_text_box_ = box; }
    void clear_own_text_box() { own_text_box_ = {0.0f, 0.0f, -1.0f, -1.0f}; }

    float intrinsic_width() const override;

    float max_content_width() const;

    float intrinsic_height() const override;

    float measured_height(float available_width) const;

    float measured_width(float available_width) const;

    struct PaintedTextExtents {
        bool measured = false;
        float width = 0.0f;       
        float height = 0.0f;      
        int line_count = 0;
        Rect ink{};
    };
    PaintedTextExtents painted_text_extents(float available_width) const;

    struct CachedLineBox {
        float left = 0.0f;
        float top = 0.0f;
        float width = 0.0f;
        float height = 0.0f;
        int start = 0;
        int length = 0;
    };

    struct LineBreakPathCounts {
        int cached = 0;      
        int reflowed = 0;    
        int uncached = 0;    
    };
    static LineBreakPathCounts line_break_path_counts();
    static void reset_line_break_path_counts();

    void set_cached_line_boxes(std::vector<CachedLineBox> boxes,
                               float basis_width, std::string basis_face,
                               bool wrap_on_cache_miss = false);
    void clear_cached_line_boxes() {
        cached_line_boxes_.clear();
        cached_line_metrics_.reset();
        shaped_cache_valid_ = false;
        invalidate_layout();
    }

    void set_cached_line_metrics(LineMetrics metrics);
    const std::vector<CachedLineBox>& cached_line_boxes() const {
        return cached_line_boxes_;
    }
    bool captured_wrap_fallback() const { return captured_wrap_fallback_; }

    int effective_font_weight() const;

    std::string effective_font_family() const;

    float baseline_y() const;

    struct TextEditMetrics {
        std::string display_text;
        float local_text_left = 0.0f;   
        float local_band_y = 0.0f;      
        float band_height = 0.0f;
        std::vector<float> caret_x_by_byte;  
    };
    TextEditMetrics text_edit_metrics(canvas::Canvas& canvas,
                                      std::string_view edit_text) const;
 
    // ── Click-to-edit ────────────────────────────────────────────────────
    //
    // A Label can turn itself into a text field in place. `set_editable`
    // arms the gesture; a matching click spawns a child TextEditor sized to
    // the Label's bounds, seeded with the Label's text, focused and
    // select-all'd. Return commits (the Label's text is replaced and
    // `on_text_change` fires), Escape reverts, and clicking away commits —
    // the three endings a rename field is expected to have.
    //
    // The editor is a real child View, so a painter or metrics delegate
    // installed on an ancestor styles it exactly like any other text field.
 
    enum class EditTrigger {
        none,          
        single_click,
        double_click,
    };
 
    void set_editable(EditTrigger trigger) {
        edit_trigger_ = trigger;
        set_cursor(trigger == EditTrigger::none ? CursorStyle::default_ : CursorStyle::text);
    }
    EditTrigger editable() const { return edit_trigger_; }

    std::function<void(const std::string& text)> on_text_change;

    std::function<void()> on_editor_show;
    std::function<void()> on_editor_hide;

    void show_editor();
    void hide_editor(bool commit);
    bool editor_active() const { return editor_ != nullptr; }
    TextEditor* editor() const { return editor_; }
 
    void on_mouse_down(Point pos) override;
    bool wants_mouse_input() const override { return edit_trigger_ != EditTrigger::none; }
 
    // ── SelectableText ──────────────────────────────────────────────────
    // A Label joins a document-level selection (pulp/view/selectable_text.hpp)
    // using the line geometry its own paint already computes. The geometry is
    // recorded during paint rather than re-derived, so the band a selection
    // draws sits on the glyphs that were actually emitted — including after
    // text-transform, soft wrap, line-clamp and ellipsis truncation, none of
    // which a re-measurement from `text_` would reproduce.
 
    SelectableText* as_selectable_text() override {
        return is_selectable() ? this : nullptr;
    }

    enum class SelectionPolicy { inherit, always, never };
    void set_selection_policy(SelectionPolicy policy) {
        if (selection_policy_ == policy)
            return;
        selection_policy_ = policy;
        if (!is_selectable())
            set_selection_highlight(0, 0);
        request_repaint();
    }
    SelectionPolicy selection_policy() const {
        return selection_policy_;
    }

    bool is_selectable() const {
        if (selection_policy_ == SelectionPolicy::always)
            return true;
        if (selection_policy_ == SelectionPolicy::never)
            return false;
        return enclosing_text_selection_region(*const_cast<Label*>(this)) != nullptr;
    }
 
    std::string_view selectable_text() const override {
        return text_;
    }
    SelectableLayout selectable_layout() const override {
        return selection_layout_;
    }
    void set_selection_highlight(int start_utf8, int end_utf8) override;
    bool selection_highlight(int& start_utf8, int& end_utf8) const override;
    View* selectable_view() override {
        return this;
    }
 
private:
  SelectionPolicy selection_policy_ = SelectionPolicy::inherit;
  int selection_start_utf8_ = 0;
  int selection_end_utf8_ = 0;
  mutable SelectableLayout selection_layout_;
  mutable SelectableLayout selection_layout_pending_;

  void paint_selection_line_(canvas::Canvas& canvas, const std::string& line, float x, float top,
                             float line_height, int source_start, const canvas::Color& text_color,
                             bool vertical);
 
  EditTrigger edit_trigger_ = EditTrigger::none;
  TextEditor* editor_ = nullptr; 
  int click_count_ = 0;
  double last_click_time_ = 0.0;

  struct ResolvedTextStyle {
      std::string family;
      float font_size = 14.0f;
      int font_weight = 400;
      int font_slant = 0;
      float letter_spacing = 0.0f;
      LabelAlign text_align = LabelAlign::left;
      float baseline_y = 0.0f; 
  };
    ResolvedTextStyle resolve_text_style() const;
    std::string apply_text_transform(const std::string& in) const;
    std::vector<canvas::Canvas::FontFeature> resolved_font_features() const;
    void apply_font_features(canvas::Canvas& canvas) const;
    canvas::AttributedString resolved_attributed_string() const;
 
    std::string text_;
    Rect own_text_box_{0.0f, 0.0f, -1.0f, -1.0f};
    std::string font_family_;     
    float font_size_ = 14.0f;
    int font_weight_ = 400;       
    int font_style_ = 0;          
    float letter_spacing_ = 0;    
    canvas::FontSmoothing font_smoothing_ = canvas::FontSmoothing::auto_smoothing;
    float line_height_ = 0;       
    LabelAlign text_align_ = LabelAlign::left;
    bool multi_line_ = false;
    int line_clamp_ = 0;          
    TextTransform text_transform_ = TextTransform::none;
    TextDecoration text_decoration_ = TextDecoration::none;
    canvas::Color decoration_color_{};
    bool has_decoration_color_ = false;
    TextDecorationStyle text_decoration_style_ = TextDecorationStyle::solid;
    canvas::TextDirection text_direction_ = canvas::TextDirection::left_to_right;
    canvas::TextVerticalAlign vertical_align_ = canvas::TextVerticalAlign::top;
    // Explicit-vs-inherited tracking. Fields keep their default
    // values until a setter is called; the has_own_* flag tells paint()
    // whether to honor the field or fall through to View::inheritable_*().
    canvas::Color text_color_{};
    bool has_own_text_color_ = false;
    canvas::AttributedString attributed_runs_;  
    bool has_attributed_ = false;
    void paint_text_(canvas::Canvas& canvas, Rect text_box);
 
    void paint_decoration_(canvas::Canvas& canvas, float x, float width,
                           float baseline, float font_size,
                           const canvas::Color& color);
    void paint_attributed_lines_(canvas::Canvas& canvas,
                                 const canvas::ShapedLayout& layout,
                                 float baseline_y, float line_height,
                                 int visible_lines, bool append_ellipsis,
                                 bool single_line_ellipsis,
                                 bool captured_positions);
    LabelAlign
    resolve_effective_align_() const; 
    bool has_own_font_size_ = false;
    bool has_own_font_weight_ = false;
    bool has_own_letter_spacing_ = false;
    bool has_own_text_align_ = false;
 
    // Cache of the soft-wrap shaped layout so paint() reuses it instead of
    // re-running the expensive TextShaper prepare()+layout each frame. Keyed on
    // every input the shaper reads; a key mismatch recomputes, so no stale hit
    // is possible.
    //
    // Weight IS one of those inputs. A Bold face is a different set of glyph
    // advances, not a Regular one drawn heavier, so the same string at the same
    // size in the same family breaks at a different word depending on it —
    // which is why a key without it serves a Regular layout to a Bold label.
    struct ShapedLayoutKey {
        std::string display_text;  // text_ after text-transform
        std::string family;        // resolved family ("Inter" fallback)
        std::string font_variant;
        float font_size = 0.0f;
        int font_weight = 400;     // CSS numeric weight; selects the face
        int font_style = 0;
        float letter_spacing = 0.0f;
        float width = 0.0f;        // bounds().width — changes every resize
        float line_height = 0.0f;
        int break_mode = 0;        // canvas::BreakMode as int
        int max_lines = 0;         // attributed nowrap uses one; wrap is unlimited
        // Captured browser line positions and native reflow can have identical
        // shaping inputs but different x/y origins. Eligibility may change as
        // imported ancestor styles settle, so it is part of the cache key,
        // not merely a branch taken on cache construction.
        bool captured_positions = false;
        std::uint64_t font_gen = 0;  // font_registration_generation() snapshot
        bool operator==(const ShapedLayoutKey& o) const {
            return display_text == o.display_text && family == o.family &&
                   font_variant == o.font_variant &&
                   font_size == o.font_size && font_weight == o.font_weight &&
                   font_style == o.font_style &&
                   letter_spacing == o.letter_spacing &&
                   width == o.width && line_height == o.line_height &&
                   break_mode == o.break_mode && max_lines == o.max_lines &&
                   captured_positions == o.captured_positions &&
                   font_gen == o.font_gen;
        }
    };
    struct ShapingSetup {
        std::string display_text;
        float line_height = 0.0f;
        float font_size = 0.0f;
        float letter_spacing = 0.0f;
        float shaping_line_height = 0.0f;
        canvas::BreakMode break_mode = canvas::BreakMode::normal;
    };
    ShapingSetup shaping_setup() const;

    canvas::PreparedText prepare_shaped(const ShapingSetup& setup) const;

    canvas::ShapedLayout shaper_layout_for(const canvas::PreparedText& prepared,
                                           const ShapingSetup& setup,
                                           float available_width) const;

    bool cached_line_layout_usable(const std::string& display_text,
                                   float effective_font_size,
                                   float effective_letter_spacing,
                                   float layout_width) const;

    canvas::ShapedLayout layout_from_cached_lines(const std::string& text, float line_height,
                                                  const std::string& family,
                                                  float effective_font_size,
                                                  float effective_letter_spacing) const;
    canvas::ShapedLayout layout_attributed_from_cached_lines(
        const canvas::AttributedString& text, float line_height) const;
 
    std::vector<CachedLineBox> cached_line_boxes_;
    bool captured_wrap_fallback_ = false;
    // Measured-size memo. See Label::sync_measure_basis in label.cpp for why
    // the basis is the resolved style and why the face is keyed through the
    // font-registration generation rather than resolved per call.
    struct MeasureBasis {
        std::string text;
        std::string family;
        std::string font_variant;
        float font_size = 0.0f;
        float letter_spacing = 0.0f;
        int font_weight = 400;
        int font_style = 0;
        int text_direction = 0;
        int line_clamp = 0;
        bool multi_line = false;
        bool wrap_fallback = false;
        std::uint64_t font_gen = 0;
        // Every input shaping_setup()/prepare_shaped() reads must appear
        // here, or a restyle that changes only one of them keeps the stale
        // box: line height scales measured height directly, a text-transform
        // changes advances and so can change the line count, the word-break
        // mode changes where lines break, and font features change shaping.
        float line_height = 0.0f;
        int text_transform = 0;
        std::string word_break;
        std::vector<canvas::Canvas::FontFeature> font_features;
        bool operator==(const MeasureBasis&) const = default;
    };
    bool sync_measure_basis() const;
    float compute_intrinsic_width() const;
    float compute_max_content_width() const;
    bool paints_as_lines() const { return soft_wraps() || captured_wrap_fallback_; }
    float compute_intrinsic_height() const;
    float compute_measured_height(float available_width) const;
    mutable MeasureBasis measure_basis_;
    mutable bool measure_basis_valid_ = false;
    mutable float measure_width_ = -1.0f;
    mutable float measure_height_ = -1.0f;
    mutable float measure_wrapped_for_width_ = -1.0f;
    mutable float measure_wrapped_height_ = -1.0f;
 
    float cached_line_basis_width_ = 0.0f;
    std::optional<LineMetrics> cached_line_metrics_;
    std::string cached_line_basis_face_;
    std::string cached_line_basis_text_;
    // Set once the label's copy diverged from the captured basis; the boxes
    // are kept for reflow but never honored verbatim again.
    bool cached_line_basis_retired_ = false;
    std::string cached_line_basis_font_variant_;
    float cached_line_basis_font_size_ = 0.0f;
    float cached_line_basis_letter_spacing_ = 0.0f;
    int cached_line_basis_font_weight_ = 400;
    int cached_line_basis_font_style_ = 0;
 
    ShapedLayoutKey shaped_cache_key_;
    canvas::ShapedLayout shaped_cache_layout_;
    bool shaped_cache_valid_ = false;
    // The shaped-layout cache cannot prevent work performed before its lookup.
    // Retain the expensive attributed preparation separately so an unchanged
    // paint performs no shaping even though it still resolves inherited spans.
    canvas::AttributedString attributed_prepare_source_;
    std::vector<canvas::Canvas::FontFeature> attributed_prepare_features_;
    canvas::PreparedText attributed_prepare_cache_;
    std::uint64_t attributed_prepare_font_gen_ = 0;
    bool attributed_prepare_valid_ = false;

    struct FaceMetrics {
        float ascent = 0.0f;
        float descent = 0.0f;
        // fDescent; see PreparedText::typographic_descent().
        float typographic_descent = 0.0f;
        bool real = false;
    };
    FaceMetrics face_metrics(const std::string& family, float font_size,
                             int font_weight, int font_style) const;
    mutable std::string face_metrics_family_;
    mutable float face_metrics_font_size_ = 0.0f;
    mutable int face_metrics_font_weight_ = 400;
    mutable int face_metrics_font_style_ = 0;
    mutable std::uint64_t face_metrics_font_gen_ = 0;
    mutable FaceMetrics face_metrics_cache_;
    mutable bool face_metrics_valid_ = false;
public:
    void set_text_direction(canvas::TextDirection d) { text_direction_ = d; }
    canvas::TextDirection text_direction() const { return text_direction_; }

    void set_vertical_align(canvas::TextVerticalAlign a) { vertical_align_ = a; }
    canvas::TextVerticalAlign vertical_align() const { return vertical_align_; }
};
 
// ── Knob ─────────────────────────────────────────────────────────────────────
// Rotary control for audio parameters (gain, frequency, etc.)
 
// AccessibilityValueInterface: `AccessRole::slider` advertises the UIA
// RangeValue/Value patterns and the AT-SPI Value interface. A slider with no
// value source announces its name and then reads nothing (macOS) or reports
// 0 in a degenerate 0..0 range (Windows). The role and the value ship together.
class Knob : public View, public CustomShaderHost, public AccessibilityValueInterface {
public:
    Knob() {
        mark_runtime_view_kind(RuntimeViewKind::knob);
        set_access_role(AccessRole::slider);
        set_focusable(true);
        // A knob's pointer travel is shorter than a fader's: 150px crosses the
        // whole range, which is what a compact plugin panel expects.
        core_.set_drag_sensitivity(150);
    }
 
    // ── Value engine ─────────────────────────────────────────────────────
    //
    // The knob's REAL-WORLD value, range, interval, response curve and drag law
    // live in a SliderCore (slider_core.hpp). `value()` below stays the
    // normalized [0,1] position in that range — that is the space a parameter
    // store and the design/JS bridges speak — so a knob with the default 0..1
    // range behaves exactly as it always has, and `set_range()` is what turns it
    // into a real control (20..20000 Hz, -60..+12 dB, quantized to an interval).
 
    SliderCore& slider() { return core_; }
    const SliderCore& slider() const { return core_; }

    void set_range(double min_value, double max_value, double interval = 0.0) {
        core_.set_range(min_value, max_value, interval);
        core_.set_normalized(value_, Notify::none);
        value_ = static_cast<float>(core_.normalized());
        request_repaint();
    }
    double real_value() const { return core_.value(); }
    bool set_real_value(double v, Notify notify = Notify::sync) {
        core_.set_value(v, Notify::none);
        return store_normalized(static_cast<float>(core_.normalized()), notify);
    }
 
    // ── AccessibilityValueInterface (normalized 0..1, like value()) ──────
    double get_current_value() const override { return value_; }
    void set_current_value(double v) override {
        const float prev = value_;
        set_value(static_cast<float>(v));
        if (value_ != prev && on_change) on_change(value_);
    }
    double get_minimum_value() const override { return 0.0; }
    double get_maximum_value() const override { return 1.0; }
    std::string get_value_string() const override {
        return format_ ? format_(value_)
                       : AccessibilityValueInterface::get_value_string();
    }
 
    void set_render_style(WidgetRenderStyle s) { render_style_ = s; }
    WidgetRenderStyle render_style() const { return render_style_; }
 
    // Programmatic set_value() must request_repaint() when the value actually
    // changes. The host's mouseDown handler invalidates after every input event,
    // so user drags repaint correctly via that side channel; preset application
    // and other JS-driven bridge mutations go through this code path and would
    // otherwise leave the painted state stale until the next user input.
    //
    // Gate the invalidation on a real change. WidgetBridge::sync_from_store()
    // and restore_values(...) call set_value()/set_on() in tight loops during
    // sync/reload; firing a host repaint per call when the value is unchanged
    // burns wall-clock on large widget trees with no visible benefit.
    void set_value(float v) { store_normalized(v, Notify::none); }

    bool set_value(float v, Notify notify) { return store_normalized(v, notify); }
 
    float value() const { return value_; }
 
    void set_default_value(float v) {
        default_value_ = std::clamp(v, 0.0f, 1.0f);
        core_.set_default_value(core_.value_for_normalized(default_value_));
    }
    float default_value() const { return default_value_; }

    void set_skew(float s) { core_.set_skew(s); }
    float skew() const { return static_cast<float>(core_.skew()); }
    void set_skew_from_midpoint(float mid_normalized) {
        core_.set_skew_from_midpoint(
            core_.value_for_normalized(std::clamp(mid_normalized, 1e-4f, 1.0f - 1e-4f)));
    }
    float position_for_value() const {
        const float s = skew();
        return s == 1.0f ? value_ : std::pow(value_, s);
    }
    float value_for_position(float p) const {
        p = std::clamp(p, 0.0f, 1.0f);
        const float s = skew();
        return s == 1.0f ? p : std::pow(p, 1.0f / s);
    }
 
    void set_label(std::string text) {
        if (label_ == text) return;
        label_ = std::move(text);
        set_derived_access_label(label_);  // the visible label is the accessible name
        request_repaint();
    }
    const std::string& label() const { return label_; }
 
    void set_show_label(bool show) {
        if (show_label_ == show) return;
        show_label_ = show;
        request_repaint();
    }
    bool show_label() const { return show_label_; }

    void set_show_value(bool show) {
        if (show_value_ == show) return;
        show_value_ = show;
        request_repaint();
    }
    bool show_value() const { return show_value_; }
 
    // Display format: called with normalized value to produce display text.
    // No equality check (std::function doesn't compare) — formatters are
    // set at construction or theme-change time, not in tight sync loops.
    void set_format(std::function<std::string(float)> fmt) {
        format_ = std::move(fmt);
        request_repaint();
    }

    std::function<void(float)> on_change;
    std::function<void()> on_gesture_begin;
    std::function<void()> on_gesture_end;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_event(const MouseEvent& event) override;
    void on_mouse_enter() override;
    void on_mouse_leave() override;
    void on_mouse_down(Point pos) override;
    void on_mouse_up(Point pos) override;
    void on_mouse_drag(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
    // Animation accessors for testing
    float hover_glow() const { return hover_glow_.value(); }
    void advance_animations(float dt) override;
 
    // Arc range in radians (default: 270-degree sweep)
    static constexpr float start_angle = 2.356f;  // 135 degrees (bottom-left)
    static constexpr float end_angle = 7.069f;    // 405 degrees (bottom-right via top)
 
    // Custom body shader comes from CustomShaderHost — it replaces the
    // body/track/fill arc drawing; labels, value text, and hover glow still
    // draw in C++.
 
    // Declarative widget schema: JSON defining appearance as data (Rive-inspired)
    void set_widget_schema(std::string json) { widget_schema_ = std::move(json); }
    const std::string& widget_schema() const { return widget_schema_; }
 
    // ── Modulation rings (Saturn) ───────────────────────────────────────
    // Thin concentric rings drawn OUTSIDE the value arc, one per modulation
    // source. Matches the Figma "Knob Modulation" set (LFO / ENV / VEL / MACRO).
    // Empty by default (a plain knob).
    struct ModulationRing {
        // Two INDEPENDENT signed offsets from the base value, one per arc end —
        // dragging one handle moves only that end (not a symmetric grow/shrink
        // off a single depth). Unipolar-positive: lo=0, hi>0. Unipolar-negative:
        // lo<0, hi=0. Bipolar: lo<0, hi>0. The range is [base+lo, base+hi]; the
        // endpoints sort themselves, so the two may cross without breaking paint.
        float lo = 0.0f;             
        float hi = 0.0f;             
        canvas::Color color;         
    };
    void set_modulation_rings(std::vector<ModulationRing> rings) {
        mod_rings_ = std::move(rings);
        request_repaint();
    }
    const std::vector<ModulationRing>& modulation_rings() const { return mod_rings_; }
 
    // Live modulation phase in [-1, 1] — the instantaneous output of the
    // assigned source(s). Drives the indicator dot that rides the modulation
    // arc, showing where the parameter actually IS right now. Set it from a
    // master/macro control or animate it from the host (e.g. an LFO).
    void set_modulation_phase(float p) {
        float c = std::clamp(p, -1.0f, 1.0f);
        // Also a hot path — a host/LFO can drive this every frame.
        if (c != mod_phase_) { mod_phase_ = c; request_repaint_self(); }
    }
    float modulation_phase() const { return mod_phase_; }
 
    // ── Modulated value display ─────────────────────────────────────────
    //
    // The value a processor is PLAYING while a modulator (an internal LFO, an
    // envelope, MPE) moves this parameter around the value the user set.
    // Display only, and the contract every modulated control keeps:
    //
    //   * value() stays the BASE. A drag, a wheel notch or a key starts from
    //     it, and on_change / gestures report it, so
    //     host automation records the user's moves and nothing else.
    //   * set_modulated_value() never fires on_change and never writes a
    //     parameter: modulation must not write a host automation lane. It
    //     offsets around the automated (or user-set) base, so a control host
    //     automation is moving shows both -- the base following the lane and
    //     the modulated marker following the modulator around it.
    //   * The marker repaints the knob's own box (request_repaint_self), never
    //     the whole surface and never the layout, so a modulator animating a
    //     control at the display rate costs one bounded repaint per frame.
    //
    // One indicator, never two: while a played value is set, the knob's single
    // pointer and value arc show the value PLAYING, in the modulation colour
    // (token `knob.modulation`), on every body style; the base is a quiet
    // notch across the ring. The value text prints the played value, and the
    // base while the user drags it (the drag edits the base and the notch
    // follows).
    // Values are normalized 0..1, like value(). Unlike the Saturn rings above,
    // which DERIVE the live value from base + depth x phase, this takes the
    // value the processor computed, for modulation laws that are not a linear
    // offset (a proportional pull, a clamp, a stepped target).
    void set_modulated_value(float normalized) {
        const float v = std::isfinite(normalized) ? std::clamp(normalized, 0.0f, 1.0f) : value_;
        if (has_modulated_ && v == modulated_)
            return;
        has_modulated_ = true;
        modulated_ = v;
        request_repaint_self(kModulatedMarkerHalo);
    }
    void clear_modulated_value() {
        if (!has_modulated_)
            return;
        has_modulated_ = false;
        request_repaint_self(kModulatedMarkerHalo);
    }
    bool has_modulated_value() const {
        return has_modulated_;
    }

    float modulated_display_value() const {
        return has_modulated_ ? modulated_ : value_;
    }
 
    // The modulation range is [value+lo, value+hi] clipped to [0,1], sorted so
    // the returned .first ≤ .second regardless of which end is which. Exposes the
    // clipped endpoints of ring i for tests / hosts. Returns {lo_v, hi_v}.
    std::pair<float, float> modulation_range(size_t ring) const;
    // The live modulated value of ring i: phase≥0 sweeps toward base+hi, phase<0
    // toward base+lo, clipped to [0,1].
    float modulated_value(size_t ring) const;
 
    // Fired when dragging a modulation-arc handle changes a ring's endpoints.
    // Reports BOTH offsets (the dragged one moved, the other is unchanged).
    std::function<void(int ring, float lo, float hi)> on_modulation_change;
    // True while a modulation-arc handle is being dragged (vs the value).
    bool dragging_modulation() const { return mod_drag_ring_ >= 0; }
 
    // Scroll-wheel adjusts the value (hover + wheel).
    bool wants_wheel_value() const override { return true; }
    void on_wheel(float delta_y) override {
        // A QUANTIZED control moves by exactly one interval per notch. The
        // continuous nudge below is smaller than most intervals, so snapping
        // would return the value to the step it started on and the wheel would
        // do nothing at all — a control with an interval had a dead wheel.
        if (core_.interval() > 0.0) {
            const double step = (delta_y < 0.0f ? 1.0 : -1.0) * core_.interval();
            set_real_value(core_.value() + step, Notify::sync);
            return;
        }
        store_normalized(value_ + (-delta_y) * 0.004f, Notify::sync);
    }
 
    // True while a value drag (or modulation-handle drag) is in progress so a
    // declarative param binding yields the value to the user mid-turn.
    bool is_gesture_active() const override { return gesture_active_ || mod_drag_ring_ >= 0; }
 
private:
  static constexpr float kModulatedMarkerHalo = 6.0f;
  void paint_modulated_marker(canvas::Canvas& canvas, float cx, float cy, float ring_r,
                              float arc_w);
  bool has_modulated_ = false; 
  float modulated_ = 0.0f;     
  std::vector<ModulationRing> mod_rings_;
  float mod_phase_ = 0.0f;           
  int mod_drag_ring_ = -1;           
  bool mod_drag_is_high_ = true;     
  float mod_drag_last_angle_ = 0.0f; 
  float value_ = 0.0f;
  SliderCore core_;            
  float default_value_ = 0.5f; 
  std::string label_;
  std::function<std::string(float)> format_;
  ValueAnimation hover_glow_{0.0f};
  float drag_start_y_ = 0;
  float drag_start_proportion_ = 0; 
  float drag_last_y_ = 0;           
  bool gesture_active_ = false;

 
  bool store_normalized(float n, Notify notify) {
      core_.set_normalized(std::clamp(n, 0.0f, 1.0f), Notify::none);
      const float snapped = static_cast<float>(core_.normalized());
      if (snapped == value_)
          return false;
      value_ = snapped;
      request_repaint_self();
      if (notify == Notify::sync) {
          if (on_change)
              on_change(value_);
      } else if (notify == Notify::async && on_change) {
          auto fn = on_change;
          const float v = value_;
          queue_async_notification([fn, v] { fn(v); });
      }
      return true;
  }
    bool show_label_ = true;
    bool show_value_ = true;
    std::string widget_schema_;   // JSON declarative schema
    std::string lottie_json_;     // Lottie animation JSON
    WidgetRenderStyle render_style_ = WidgetRenderStyle::standard;
    float lottie_time_ = 0;       // Current playback position (0-1)
 
public:
    void set_lottie_json(std::string json) { lottie_json_ = std::move(json); }
    const std::string& lottie_json() const { return lottie_json_; }
    void set_lottie_time(float t) { lottie_time_ = std::clamp(t, 0.0f, 1.0f); }
    float lottie_time() const { return lottie_time_; }

    void set_sprite_strip(std::shared_ptr<SpriteStrip> strip) { sprite_strip_ = std::move(strip); }
    const std::shared_ptr<SpriteStrip>& sprite_strip() const { return sprite_strip_; }

    void set_sprite_core(float x, float y, float w, float h) {
        sprite_core_x_ = x; sprite_core_y_ = y;
        sprite_core_w_ = w; sprite_core_h_ = h;
    }
    bool has_sprite_core() const { return sprite_core_w_ > 0.0f && sprite_core_h_ > 0.0f; }

    void set_captured_raster_origin(float x, float y, float scale) {
        captured_raster_origin_x_ = x;
        captured_raster_origin_y_ = y;
        captured_raster_scale_ = scale > 0.0f ? scale : 0.0f;
    }
    float captured_raster_scale() const { return captured_raster_scale_; }
    float captured_raster_origin_x() const { return captured_raster_origin_x_; }
    float captured_raster_origin_y() const { return captured_raster_origin_y_; }

    void set_captured_indicator(float r_in, float r_out, float width_px,
                                canvas::Color color, float phase_rad = 0.0f,
                                bool color_authored = true) {
        ind_r_in_ = r_in; ind_r_out_ = r_out;
        ind_width_ = width_px; ind_color_ = color;
        ind_phase_rad_ = phase_rad;
        ind_color_authored_ = color_authored;
        has_captured_indicator_ = true;
        request_repaint();
    }
    bool has_captured_indicator() const { return has_captured_indicator_; }
    float captured_indicator_r_in() const { return ind_r_in_; }
    float captured_indicator_r_out() const { return ind_r_out_; }
    float captured_indicator_phase_rad() const { return ind_phase_rad_; }
    bool captured_indicator_color_authored() const {
        return ind_color_authored_;
    }

    void set_captured_indicator_outline(canvas::Color color, float width_px) {
        ind_outline_color_ = color;
        ind_outline_width_ = std::max(0.0f, width_px);
        request_repaint();
    }
    float captured_indicator_outline_width() const { return ind_outline_width_; }
    canvas::Color captured_indicator_outline_color() const {
        return ind_outline_color_;
    }
 
private:
    std::shared_ptr<SpriteStrip> sprite_strip_;
    float sprite_core_x_ = 0.0f;
    float sprite_core_y_ = 0.0f;
    float sprite_core_w_ = 0.0f;
    float sprite_core_h_ = 0.0f;
    float captured_raster_origin_x_ = 0.0f;
    float captured_raster_origin_y_ = 0.0f;
    float captured_raster_scale_ = 0.0f;
    bool has_captured_indicator_ = false;
    float ind_r_in_ = 0.0f;
    float ind_r_out_ = 0.0f;
    float ind_width_ = 0.0f;
    float ind_phase_rad_ = 0.0f;
    canvas::Color ind_color_ = canvas::Color::rgba(1.0f, 1.0f, 1.0f, 1.0f);
    bool ind_color_authored_ = true;
    canvas::Color ind_outline_color_ = canvas::Color::rgba(0, 0, 0, 1.0f);
    float ind_outline_width_ = 0.0f;
};
 
// ── Fader ────────────────────────────────────────────────────────────────────
// Linear slider for audio parameters
 
class Fader : public View, public CustomShaderHost, public AccessibilityValueInterface {
public:
    enum class Orientation { vertical, horizontal };
    enum class ThumbShape { circle, rectangle };
 
    Fader() {
        mark_runtime_view_kind(RuntimeViewKind::fader);
        set_access_role(AccessRole::slider);
        set_focusable(true);
    }
 
    // ── AccessibilityValueInterface (normalized 0..1) ────────────────────
    double get_current_value() const override { return value_; }
    void set_current_value(double v) override {
        const float prev = value_;
        set_value(static_cast<float>(v));
        if (value_ != prev && on_change) on_change(value_);
    }
    double get_minimum_value() const override { return 0.0; }
    double get_maximum_value() const override { return 1.0; }
 
    void set_render_style(WidgetRenderStyle s) { render_style_ = s; }
    WidgetRenderStyle render_style() const { return render_style_; }
 
    // Same programmatic repaint contract as Knob::set_value(), including the
    // no-change guard for bridge sync/reload loops. This form is silent (no
    // change callback), which is what a sync FROM the bound parameter wants.
    void set_value(float v) {
        float clamped = std::clamp(v, 0.0f, 1.0f);
        if (clamped == value_) return;
        value_ = clamped;
        request_repaint_self();
    }

    bool set_value(float v, Notify notify) {
        float clamped = std::clamp(v, 0.0f, 1.0f);
        if (clamped == value_) return false;
        value_ = clamped;
        request_repaint_self();
        if (notify == Notify::sync) {
            if (on_change) on_change(value_);
        } else if (notify == Notify::async && on_change) {
            auto fn = on_change;
            const float nv = value_;
            queue_async_notification([fn, nv] { fn(nv); });
        }
        return true;
    }
    float value() const { return value_; }

    void set_modulated_value(float normalized) {
        const float v = std::isfinite(normalized) ? std::clamp(normalized, 0.0f, 1.0f) : value_;
        if (has_modulated_ && v == modulated_)
            return;
        has_modulated_ = true;
        modulated_ = v;
        request_repaint_self(kModulatedMarkerHalo);
    }
    void clear_modulated_value() {
        if (!has_modulated_)
            return;
        has_modulated_ = false;
        request_repaint_self(kModulatedMarkerHalo);
    }
    bool has_modulated_value() const {
        return has_modulated_;
    }
    float modulated_display_value() const {
        return has_modulated_ ? modulated_ : value_;
    }
 
    // Scroll-wheel adjusts the value (hover + wheel).
    bool wants_wheel_value() const override { return true; }
    void on_wheel(float delta_y) override {
        float nv = std::clamp(value_ + (-delta_y) * 0.004f, 0.0f, 1.0f);
        if (nv != value_) { set_value(nv); if (on_change) on_change(value_); }
    }
 
    // True while the thumb is being dragged so a param binding yields mid-drag.
    bool is_gesture_active() const override { return dragging_; }
 
    void set_orientation(Orientation o) { orientation_ = o; }
    Orientation orientation() const { return orientation_; }
 
    void set_thumb_shape(ThumbShape shape) {
        if (thumb_shape_ == shape) return;
        thumb_shape_ = shape;
        request_repaint();
    }
    ThumbShape thumb_shape() const { return thumb_shape_; }
 
    void set_thumb_size(float width, float height) {
        thumb_width_ = std::max(0.0f, width);
        thumb_height_ = std::max(0.0f, height);
        request_repaint();
    }
    float thumb_width() const { return thumb_width_; }
    float thumb_height() const { return thumb_height_; }
 
    void set_thumb_corner_radius(float radius) {
        thumb_corner_radius_ = std::max(0.0f, radius);
        request_repaint();
    }
    float thumb_corner_radius() const { return thumb_corner_radius_; }
 
    void set_label(std::string text) {
        if (label_ == text) return;
        label_ = std::move(text);
        set_derived_access_label(label_);  // the visible label is the accessible name
        request_repaint();
    }
    const std::string& label() const { return label_; }

    std::function<void(float)> on_change;
    std::function<void()> on_gesture_begin;
    std::function<void()> on_gesture_end;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_enter() override;
    void on_mouse_leave() override;
    void on_mouse_down(Point pos) override;
    void on_mouse_up(Point pos) override;
    void on_mouse_event(const MouseEvent& event) override;
    void on_mouse_drag(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
    // Animation accessors for testing
    float hover_scale() const { return hover_thumb_scale_.value(); }
    void advance_animations(float dt) override;

    void set_skew(float s) { skew_ = std::max(0.0001f, s); }
    float skew() const { return skew_; }
    void set_skew_from_midpoint(float mid_normalized) {
        float p = std::clamp(mid_normalized, 1e-4f, 1.0f - 1e-4f);
        skew_ = std::max(0.0001f, std::log(0.5f) / std::log(p));
    }

    float position_for_value() const { return skew_ == 1.0f ? value_ : std::pow(value_, skew_); }
    float value_for_position(float p) const {
        p = std::clamp(p, 0.0f, 1.0f);
        return skew_ == 1.0f ? p : std::pow(p, 1.0f / skew_);
    }
 
    // Custom body shader comes from CustomShaderHost.
    void set_widget_schema(std::string json) { widget_schema_ = std::move(json); }
    const std::string& widget_schema() const { return widget_schema_; }
    void set_lottie_json(std::string json) { lottie_json_ = std::move(json); }
    const std::string& lottie_json() const { return lottie_json_; }
    void set_lottie_time(float t) { lottie_time_ = std::clamp(t, 0.0f, 1.0f); }
    float lottie_time() const { return lottie_time_; }
 
 
private:
  static constexpr float kModulatedMarkerHalo = 6.0f;
  void paint_modulated_marker(canvas::Canvas& canvas);
  // The stock thumb (slab or circle) at track position `pos`, 0..1.
  void paint_stock_thumb(canvas::Canvas& canvas, float pos, canvas::Color color);
  bool has_modulated_ = false;
  float modulated_ = 0.0f;
  float value_ = 0.0f;
  float skew_ = 1.0f; 
  Orientation orientation_ = Orientation::vertical;
  // Ink & Signal faders use a slab/handle thumb by default (matches the Figma
  // design language); callers can opt back to a circle per-widget.
  ThumbShape thumb_shape_ = ThumbShape::rectangle;
  float thumb_width_ = 0.0f;
  float thumb_height_ = 0.0f;
  float thumb_corner_radius_ = 0.0f;
  bool has_skin_thumb_style_ = false;
  ThumbShape pre_skin_thumb_shape_ = ThumbShape::rectangle;
  float pre_skin_thumb_width_ = 0.0f;
  float pre_skin_thumb_height_ = 0.0f;
  float pre_skin_thumb_corner_radius_ = 0.0f;
  std::string label_;
  ValueAnimation hover_thumb_scale_{1.0f};
  bool dragging_ = false;
  std::string widget_schema_;
  std::string lottie_json_;
  float lottie_time_ = 0.0f;
  WidgetRenderStyle render_style_ = WidgetRenderStyle::standard;
 
public:
    void set_sprite_strip(std::shared_ptr<SpriteStrip> strip) { sprite_strip_ = std::move(strip); }
    const std::shared_ptr<SpriteStrip>& sprite_strip() const { return sprite_strip_; }

    void set_captured_art(std::shared_ptr<SpriteStrip> body,
                          std::shared_ptr<SpriteStrip> indicator,
                          float indicator_cross = 0.5f,
                          float body_origin_x = 0.0f,
                          float body_origin_y = 0.0f,
                          float control_natural_w = 0.0f,
                          float control_natural_h = 0.0f,
                          bool body_includes_static_track = false) {
        captured_body_ = std::move(body);
        captured_indicator_ = std::move(indicator);
        captured_indicator_cross_ = std::clamp(indicator_cross, 0.0f, 1.0f);
        captured_body_origin_x_ = body_origin_x;
        captured_body_origin_y_ = body_origin_y;
        captured_control_natural_w_ = control_natural_w;
        captured_control_natural_h_ = control_natural_h;
        captured_body_includes_static_track_ = body_includes_static_track;
        request_repaint();
    }
    void set_captured_raster_origin(float x, float y, float scale) {
        captured_raster_origin_x_ = x;
        captured_raster_origin_y_ = y;
        captured_raster_scale_ = scale > 0.0f ? scale : 0.0f;
    }
    float captured_raster_scale() const { return captured_raster_scale_; }
    float captured_raster_origin_x() const { return captured_raster_origin_x_; }
    float captured_raster_origin_y() const { return captured_raster_origin_y_; }
    bool has_captured_indicator_art() const {
        return captured_indicator_ && captured_indicator_->loaded();
    }
    float captured_indicator_cross() const { return captured_indicator_cross_; }
    bool captured_body_includes_static_track() const {
        return captured_body_includes_static_track_;
    }
 
    // ── Skin overrides ────────────────────────────────────────────────────
    // Per-widget appearance, generalising the knob sprite-strip path to the
    // fader: instead of baking the captured Figma art (which would freeze the
    // thumb at its captured value), the importer derives the track / fill /
    // thumb colors from the design and the widget redraws them procedurally
    // so the thumb still MOVES with set_value(). Unset → today's theme-token
    // behavior (back-compat). Mirrors RangeSlider's accent override.
    void set_skin_track_color(canvas::Color c) { track_color_ = c; has_skin_track_ = true; request_repaint(); }
    void set_skin_fill_color(canvas::Color c)  { fill_color_  = c; has_skin_fill_  = true; request_repaint(); }
    void set_skin_thumb_color(canvas::Color c) { thumb_color_ = c; has_skin_thumb_ = true; request_repaint(); }
    void begin_skin_thumb_style() {
        if (has_skin_thumb_style_) return;
        pre_skin_thumb_shape_ = thumb_shape_;
        pre_skin_thumb_width_ = thumb_width_;
        pre_skin_thumb_height_ = thumb_height_;
        pre_skin_thumb_corner_radius_ = thumb_corner_radius_;
        has_skin_thumb_style_ = true;
    }

    void set_skin_thumb_fallback_color(canvas::Color c) {
        thumb_fallback_color_ = c;
        has_skin_thumb_fallback_ = true;
        // A later panel/theme fallback is a provenance transition, not merely
        // another stored palette value. Retire any older per-control override
        // so paint can resolve the live control.thumb token again.
        has_skin_thumb_ = false;
        request_repaint();
    }

    void clear_skin_thumb_colors() {
        has_skin_thumb_ = false;
        has_skin_thumb_fallback_ = false;
        request_repaint();
    }

    void clear_skin_thumb_style() {
        clear_skin_thumb_colors();
        has_skin_thumb_border_ = false;
        if (has_skin_thumb_style_) {
            thumb_shape_ = pre_skin_thumb_shape_;
            thumb_width_ = pre_skin_thumb_width_;
            thumb_height_ = pre_skin_thumb_height_;
            thumb_corner_radius_ = pre_skin_thumb_corner_radius_;
            has_skin_thumb_style_ = false;
        }
        request_repaint();
    }
    void set_skin_thumb_border_color(canvas::Color c) { thumb_border_color_ = c; has_skin_thumb_border_ = true; request_repaint(); }
    // Outline of the empty track: the lighter edge the captured art draws
    // around the dark channel. When set, the skinned fader strokes the track
    // rect so it doesn't read as a flat dark slab.
    void set_skin_track_border_color(canvas::Color c) { track_border_color_ = c; has_skin_track_border_ = true; request_repaint(); }
    // Derived thin track width (logical px). When set, the skinned fader draws
    // its track / fill at exactly this width (centerd) instead of a fraction of
    // the widget box, matching the captured art's narrow track.
    void set_skin_track_width(float w) {
        if (w > 0.0f) { skin_track_width_ = w; has_skin_track_width_ = true; request_repaint(); }
    }
    float skin_track_width() const { return skin_track_width_; }
    bool has_skin_track_width() const { return has_skin_track_width_; }
    void clear_skin() {
        clear_skin_thumb_style();
        has_skin_track_ = has_skin_fill_ = false;
        has_skin_track_border_ = false;
        has_skin_track_width_ = false;
        request_repaint();
    }
    bool has_skin() const {
        return has_skin_track_ || has_skin_fill_ || has_skin_thumb_ ||
               has_skin_thumb_border_ || has_skin_track_border_;
    }
    bool has_skin_track_color() const { return has_skin_track_; }
    bool has_skin_fill_color() const { return has_skin_fill_; }
    bool has_skin_thumb_color() const { return has_skin_thumb_; }
    bool has_skin_thumb_fallback_color() const {
        return has_skin_thumb_fallback_;
    }
    bool has_skin_thumb_border_color() const { return has_skin_thumb_border_; }
    bool has_skin_track_border_color() const { return has_skin_track_border_; }
    canvas::Color skin_track_color() const { return track_color_; }
    canvas::Color skin_fill_color() const { return fill_color_; }
    canvas::Color skin_thumb_color() const { return thumb_color_; }
    canvas::Color skin_thumb_fallback_color() const {
        return thumb_fallback_color_;
    }
    canvas::Color skin_thumb_border_color() const { return thumb_border_color_; }
    canvas::Color skin_track_border_color() const { return track_border_color_; }
 
private:
    std::shared_ptr<SpriteStrip> sprite_strip_;
    std::shared_ptr<SpriteStrip> captured_body_;
    std::shared_ptr<SpriteStrip> captured_indicator_;
    float captured_indicator_cross_ = 0.5f;
    float captured_body_origin_x_ = 0.0f;
    float captured_body_origin_y_ = 0.0f;
    float captured_control_natural_w_ = 0.0f;
    float captured_control_natural_h_ = 0.0f;
    bool captured_body_includes_static_track_ = false;
    float captured_raster_origin_x_ = 0.0f;
    float captured_raster_origin_y_ = 0.0f;
    float captured_raster_scale_ = 0.0f;
    canvas::Color track_color_{};
    canvas::Color fill_color_{};
    canvas::Color thumb_color_{};
    canvas::Color thumb_fallback_color_{};
    canvas::Color thumb_border_color_{};
    canvas::Color track_border_color_{};
    bool has_skin_track_ = false;
    bool has_skin_fill_ = false;
    bool has_skin_thumb_ = false;
    bool has_skin_thumb_fallback_ = false;
    bool has_skin_thumb_border_ = false;
    bool has_skin_track_border_ = false;
    float skin_track_width_ = 0.0f;
    bool has_skin_track_width_ = false;
};

std::optional<canvas::Canvas::SDFShape> widget_chart_shape(const View& view);

inline float fader_chart_track_thickness(float cross_extent) {
    return std::clamp(cross_extent * 0.5f, 8.0f, 24.0f);
}
 
// ── UA form-control skins ───────────────────────────────────────────────────
// An imported `appearance: auto` form control carries no CSS paint: the
// browser's UA theme draws it. RangeSlider and Checkbox can wear Chromium's
// cross-platform form-control theme so such a control renders the way the
// browser drew it. The types below are shared by those widgets.

enum class UaSkin { platform, chromium_refresh };

enum class UaColorScheme { light, dark };

enum class UaControlState { normal, hovered, pressed, disabled };

UaColorScheme ua_scheme_for_accent(canvas::Color accent, UaColorScheme scheme,
                                   canvas::Color contrast_light, canvas::Color contrast_dark);
 
// ── RangeSlider ──────────────────────────────────────────────────────────────
// Generic min/max/step slider mapped to HTML <input type="range">.
//
// Distinct from Knob (rotary, normalized 0..1) and Fader (DSP linear with
// decorative track + large thumb). RangeSlider is the plain rectangular
// track + circular handle the web uses for volume / morph / scrubber UIs.
// Caller-supplied min/max/step are honoured natively — the bridge does
// not preprocess them. Quantisation happens inside the widget so JS-side
// callers see the same value the renderer paints.
//
class RangeSlider : public View, public AccessibilityValueInterface {
public:
    enum class Orientation { horizontal, vertical };
 
    RangeSlider() {
        set_access_role(AccessRole::slider);
        set_focusable(true);
        // The control paints 16pt on its minor axis, which is comfortable to
        // look at and uncomfortable to hit. Grow only the hit area to the 44pt
        // touch target HitMetrics specifies -- (44 - 16) / 2 = 14pt per edge --
        // so the thumb is grabbable without the box, the layout or the paint
        // changing. The major axis gets the same 14pt so the thumb is still
        // grabbable at either travel extreme, where half of it sits outside
        // the track.
        const float target = HitMetrics::default_min_target_pt(PointerType::touch);
        const float slop = std::max(0.0f, (target - kMinorAxisExtent) * 0.5f);
        set_hit_slop(slop);
    }

    static constexpr float kMinorAxisExtent = 16.0f;
 
    // ── AccessibilityValueInterface (caller's min/max/step units) ────────
    double get_current_value() const override { return value_; }
    void set_current_value(double v) override {
        const float prev = value_;
        set_value(static_cast<float>(v));
        if (value_ != prev && on_change) on_change(value_);
    }
    double get_minimum_value() const override { return min_; }
    double get_maximum_value() const override { return max_; }
    double get_step_size() const override {
        return step_ > 0.0f
            ? step_
            : AccessibilityValueInterface::get_step_size();
    }

    void set_min(float v) { min_ = v; clamp_and_quantize_(); }
    float min_value() const { return min_; }

    void set_max(float v) { max_ = v; clamp_and_quantize_(); }
    float max_value() const { return max_; }

    void set_step(float v) { step_ = v; clamp_and_quantize_(); }
    float step() const { return step_; }

    void set_value(float v, Notify notify = Notify::sync) {
        float prev = value_;
        value_ = v;
        clamp_and_quantize_(notify);
        if (value_ != prev) request_repaint();
    }
    float value() const { return value_; }

    void set_modulated_value(float normalized) {
        const float v =
            std::isfinite(normalized) ? std::clamp(normalized, 0.0f, 1.0f) : value_to_position_();
        if (has_modulated_ && v == modulated_)
            return;
        has_modulated_ = true;
        modulated_ = v;
        request_repaint_self(kModulatedMarkerHalo);
    }
    void clear_modulated_value() {
        if (!has_modulated_)
            return;
        has_modulated_ = false;
        request_repaint_self(kModulatedMarkerHalo);
    }
    bool has_modulated_value() const {
        return has_modulated_;
    }

    float modulated_display_value() const {
        return modulated_;
    }
 
    // Scroll-wheel adjusts the value (hover + wheel), scaled to the range.
    bool wants_wheel_value() const override { return true; }
    void on_wheel(float delta_y) override {
        float prev = value_;
        set_value(value_ + (-delta_y) * 0.004f * (max_ - min_));
        if (value_ != prev && on_change) on_change(value_);
    }
 
    // True while the handle is being dragged so a param binding yields mid-drag.
    bool is_gesture_active() const override { return dragging_; }
 
    void set_orientation(Orientation o) { orientation_ = o; }
    Orientation orientation() const { return orientation_; }

    void set_accent_color(canvas::Color c) {
        accent_color_ = c;
        has_accent_color_ = true;
    }
    void clear_accent_color() { has_accent_color_ = false; }
    bool has_accent_color() const { return has_accent_color_; }
    canvas::Color accent_color() const { return accent_color_; }

    using Skin = UaSkin;
    using ColorScheme = UaColorScheme;
    using ControlState = UaControlState;
    void set_skin(Skin s) {
        if (skin_ == s)
            return;
        skin_ = s;
        request_repaint();
    }
    Skin skin() const {
        return skin_;
    }

    void set_color_scheme(ColorScheme scheme) {
        if (color_scheme_ == scheme)
            return;
        color_scheme_ = scheme;
        request_repaint();
    }
    ColorScheme color_scheme() const {
        return color_scheme_;
    }

    struct ChromiumRefreshParts {
        Rect track;              
        float track_radius = 0;  
        Rect value_clip;         
        Rect border;             
        float border_radius = 0; 
        float border_width = 1.0f;
        Rect thumb; 
        ColorScheme scheme = ColorScheme::light; 
        canvas::Color track_fill{};
        canvas::Color value_fill{};
        canvas::Color border_color{};
        canvas::Color thumb_fill{};
    };

    static ChromiumRefreshParts
    chromium_refresh_parts(Rect bounds, float position, bool vertical, ControlState state,
                           ColorScheme scheme, std::optional<canvas::Color> accent = std::nullopt,
                           float device_scale = 1.0f);

    ChromiumRefreshParts chromium_refresh_parts(float device_scale = 1.0f) const;

    ControlState control_state() const;

    void set_track_thickness(float t) { track_thickness_ = std::max(1.0f, t); }
    float track_thickness() const { return track_thickness_; }

    void set_skew(float s) { skew_ = std::max(0.0001f, s); }
    float skew() const { return skew_; }
    void set_skew_from_midpoint(float mid_value);
    float position_for_value() const { return value_to_position_(); }

    std::function<void(float)> on_change;

    std::function<void()> on_gesture_begin;
    std::function<void()> on_gesture_end;
 
    void paint(canvas::Canvas& canvas) override;
    float intrinsic_height() const override { return 16.0f; }
    void on_mouse_event(const MouseEvent& event) override;
    void on_mouse_drag(Point pos) override;
    void on_mouse_enter() override;
    void on_mouse_leave() override;
    bool wants_mouse_input() const override { return true; }
    void advance_animations(float dt) override { hover_scale_.advance(dt); }
    float hover_scale() const { return hover_scale_.value(); }
 
private:
    ValueAnimation hover_scale_{1.0f};  
    float position_to_value_(float t) const;

    void clamp_and_quantize_(Notify notify = Notify::sync);

    void update_from_position_(Point pos);

    float value_to_position_() const;
 
    float min_ = 0.0f;
    float max_ = 1.0f;
    float step_ = 0.0f;
    float value_ = 0.0f;
    bool has_modulated_ = false;
    float modulated_ = 0.0f;
    static constexpr float kModulatedMarkerHalo = 2.0f;
    float skew_ = 1.0f;   
    Orientation orientation_ = Orientation::horizontal;
    bool dragging_ = false;
    float track_thickness_ = 5.0f;
    canvas::Color accent_color_{};
    bool has_accent_color_ = false;
    Skin skin_ = Skin::platform;
    ColorScheme color_scheme_ = ColorScheme::light;
 
    void paint_chromium_refresh_(canvas::Canvas& canvas);
};
 
// ── Toggle ───────────────────────────────────────────────────────────────────
// Boolean on/off switch
 
class Toggle : public View, public CustomShaderHost {
public:
    Toggle() : thumb_position_(0.0f), hover_opacity_(0.0f) {
        mark_runtime_view_kind(RuntimeViewKind::toggle);
        set_access_role(AccessRole::toggle);
        // Seed the ARIA state; Toggle::set_on() keeps it in sync. A `toggle`
        // (ARIA switch) with no state announces nothing about on/off.
        set_access_checked("false");
        set_focusable(true);
    }

    void set_on(bool v, bool animate = true);
    bool is_on() const { return on_; }

    bool set_on(bool v, Notify notify, bool animate = true);
 
    void set_label(std::string text) {
        label_ = std::move(text);
        set_derived_access_label(label_);  // the visible label is the accessible name
    }
    const std::string& label() const { return label_; }

    std::function<void(bool)> on_toggle;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    void on_mouse_enter() override;
    void on_mouse_leave() override;
    bool wants_mouse_input() const override { return true; }
 
    // Animation accessors for testing
    float thumb_position() const { return thumb_position_.value(); }
    float hover_opacity() const { return hover_opacity_.value(); }
    void advance_animations(float dt) override;
 
    void set_designed_overlay(bool enabled) { designed_overlay_ = enabled; request_repaint(); }
    bool designed_overlay() const { return designed_overlay_; }
 
    // Custom body shader comes from CustomShaderHost.
    void set_widget_schema(std::string json) { widget_schema_ = std::move(json); }
    const std::string& widget_schema() const { return widget_schema_; }
    void set_lottie_json(std::string json) { lottie_json_ = std::move(json); }
    const std::string& lottie_json() const { return lottie_json_; }
    void set_lottie_time(float t) { lottie_time_ = std::clamp(t, 0.0f, 1.0f); }
    float lottie_time() const { return lottie_time_; }
 
 
private:
    bool on_ = false;
    std::string label_;
    ValueAnimation thumb_position_;
    ValueAnimation hover_opacity_;
    std::string widget_schema_;
    std::string lottie_json_;
    float lottie_time_ = 0.0f;
    bool designed_overlay_ = false;
};
 
// ── Checkbox ────────────────────────────────────────────────────────────────
// Rounded-square checkbox with check glyph
 
class Checkbox : public View {
public:
    // `checkbox`, not `toggle`: ARIA/AT-SPI/UIA all distinguish a checkbox
    // from a switch. Toggle/ToggleButton keep `toggle` (ARIA `switch`).
    // access_checked is the state slot every bridge reads (NSAccessibility
    // accessibilityValue, UIA ToggleState, the AT-SPI CHECKED state): a
    // `checkbox` role with an unset state announces the control and then says
    // nothing about whether it is checked. Seeded here, kept in sync below.
    Checkbox() {
        set_access_role(AccessRole::checkbox);
        set_access_checked("false");
        set_focusable(true);
    }
 
    // Same programmatic repaint contract as Knob::set_value(), including the
    // no-change guard for bridge sync/reload loops.
    void set_checked(bool v) {
        if (checked_ == v) return;
        checked_ = v;
        set_access_checked(indeterminate_ ? "mixed" : (v ? "true" : "false"));
        request_repaint_self();
    }

    bool set_checked(bool v, Notify notify) {
        if (checked_ == v) return false;
        checked_ = v;
        set_access_checked(indeterminate_ ? "mixed" : (v ? "true" : "false"));
        request_repaint();
        if (notify == Notify::sync) {
            if (on_change) on_change(checked_);
        } else if (notify == Notify::async && on_change) {
            auto fn = on_change;
            const bool nv = checked_;
            queue_async_notification([fn, nv] { fn(nv); });
        }
        return true;
    }
    bool is_checked() const { return checked_; }

    enum class Kind { checkbox, radio };
    void set_kind(Kind k) {
        if (kind_ == k)
            return;
        kind_ = k;
        set_access_role(k == Kind::radio ? AccessRole::radio : AccessRole::checkbox);
        request_repaint();
    }
    Kind kind() const {
        return kind_;
    }
    void set_radio_group(int id) {
        radio_group_ = id;
    }
    int radio_group() const {
        return radio_group_;
    }

    void set_indeterminate(bool v) {
        if (indeterminate_ == v)
            return;
        indeterminate_ = v;
        set_access_checked(v ? "mixed" : (checked_ ? "true" : "false"));
        request_repaint();
    }
    bool is_indeterminate() const {
        return indeterminate_;
    }

    using Skin = UaSkin;
    using ColorScheme = UaColorScheme;
    using ControlState = UaControlState;
    void set_skin(Skin s) {
        if (skin_ == s)
            return;
        skin_ = s;
        request_repaint();
    }
    Skin skin() const {
        return skin_;
    }
    void set_color_scheme(ColorScheme scheme) {
        if (color_scheme_ == scheme)
            return;
        color_scheme_ = scheme;
        request_repaint();
    }
    ColorScheme color_scheme() const {
        return color_scheme_;
    }
    void set_accent_color(canvas::Color c) {
        accent_color_ = c;
        request_repaint();
    }
    void clear_accent_color() {
        accent_color_.reset();
        request_repaint();
    }
    std::optional<canvas::Color> accent_color() const {
        return accent_color_;
    }

    struct ChromiumRefreshParts {
        Rect box;                                
        float radius = 0;                        
        ColorScheme scheme = ColorScheme::light; 
        std::optional<canvas::Color> lighten;    
        Rect background_rect;                    
        canvas::Color background{};
        std::optional<canvas::Color> border; 
        Rect border_rect;
        std::optional<canvas::Color> accent_fill; 
        canvas::Color mark{};                     
        bool has_check = false;                   
        std::array<Point, 3> check{};
        float check_width = 0;
        std::optional<Rect> dash; 
        std::optional<Rect> dot;  
    };

    static ChromiumRefreshParts
    chromium_refresh_parts(Rect bounds, Kind kind, bool checked, bool indeterminate,
                           ControlState state, ColorScheme scheme,
                           std::optional<canvas::Color> accent = std::nullopt);
    ChromiumRefreshParts chromium_refresh_parts() const;

    ControlState control_state() const;
 
    std::function<void(bool)> on_change;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
private:
    bool checked_ = false;
    bool indeterminate_ = false;
    Kind kind_ = Kind::checkbox;
    int radio_group_ = 0;
    Skin skin_ = Skin::platform;
    ColorScheme color_scheme_ = ColorScheme::light;
    std::optional<canvas::Color> accent_color_;
 
    void paint_chromium_refresh_(canvas::Canvas& canvas);
};
 
// ── ButtonSurface ───────────────────────────────────────────────────────────
// The themed surface of an imported `appearance: auto` HTML <button>: Chromium's
// push-button background, border and per-state colours, plus its focus-visible
// ring. It paints nothing else; the button's content (labels, icons) is its
// children, laid out like any container's. Only an explicitly constructed
// ButtonSurface wears this skin; TextButton and generated UI are unaffected.
//
// The focus ring reaches one CSS px (two device px at scale 2) outside the
// view's bounds, as Chromium's does; it is painted in paint() before the
// children, which never reach the 2px band at the edge it covers.
 
class ButtonSurface : public View {
  public:
    using ColorScheme = UaColorScheme;
    using ControlState = UaControlState;
 
    ButtonSurface() {
        set_access_role(AccessRole::button);
    }

    void set_color_scheme(ColorScheme scheme) {
        if (color_scheme_ == scheme)
            return;
        color_scheme_ = scheme;
        request_repaint();
    }
    ColorScheme color_scheme() const {
        return color_scheme_;
    }

    void set_pressed(bool pressed) {
        if (pressed_ == pressed)
            return;
        pressed_ = pressed;
        request_repaint();
    }
    bool is_pressed() const {
        return pressed_;
    }

    void set_focus_visible(bool visible) {
        if (focus_visible_ == visible)
            return;
        focus_visible_ = visible;
        request_repaint();
    }
    bool is_focus_visible() const {
        return focus_visible_;
    }

    ControlState control_state() const;

    struct ChromiumRefreshParts {
        bool solid = false;
        Rect bounds;
        Rect surface;     
        float radius = 0; 
        float border_width = 1.0f;
        std::optional<canvas::Color> lighten;
        canvas::Color fill{};
        canvas::Color border{};
        bool focus_ring = false;
        Rect outer_ring; 
        Rect inner_ring; 
        float ring_width = 0;
        canvas::Color outer_ring_color{};
        canvas::Color inner_ring_color{};
    };

    static ChromiumRefreshParts chromium_refresh_parts(Rect bounds, ControlState state,
                                                       ColorScheme scheme, bool focus_visible,
                                                       float device_scale = 1.0f);
    ChromiumRefreshParts chromium_refresh_parts(float device_scale = 1.0f) const;
 
    void paint(canvas::Canvas& canvas) override;
 
  private:
    ColorScheme color_scheme_ = ColorScheme::light;
    bool pressed_ = false;
    bool focus_visible_ = false;
};
 
// ── ToggleButton ────────────────────────────────────────────────────────────
// Full-width rounded button that toggles on/off
 
class ToggleButton : public View {
public:
    ToggleButton() {
        set_access_role(AccessRole::toggle);
        set_access_checked("false");
        set_focusable(true);
    }
 
    // Same programmatic repaint contract as Knob::set_value(), including the
    // no-change guard for bridge sync/reload loops.
    void set_on(bool v) {
        if (on_ == v) return;
        on_ = v;
        set_access_checked(v ? "true" : "false");
        request_repaint();
    }

    bool set_on(bool v, Notify notify) {
        if (on_ == v) return false;
        on_ = v;
        set_access_checked(v ? "true" : "false");
        request_repaint();
        if (notify == Notify::sync) {
            if (on_toggle) on_toggle(on_);
        } else if (notify == Notify::async && on_toggle) {
            auto fn = on_toggle;
            const bool nv = on_;
            queue_async_notification([fn, nv] { fn(nv); });
        }
        return true;
    }
    bool is_on() const { return on_; }
 
    void set_label(std::string text) {
        if (label_ == text) return;
        label_ = std::move(text);
        set_derived_access_label(label_);  // the visible label is the accessible name
        request_repaint();
    }
    const std::string& label() const { return label_; }
 
    void set_on_background_color(canvas::Color color) { on_background_color_ = color; request_repaint(); }
    void set_off_background_color(canvas::Color color) { off_background_color_ = color; request_repaint(); }
    void set_on_text_color(canvas::Color color) { on_text_color_ = color; request_repaint(); }
    void set_off_text_color(canvas::Color color) { off_text_color_ = color; request_repaint(); }
    void set_on_border_color(canvas::Color color) { on_border_color_ = color; request_repaint(); }
    void set_off_border_color(canvas::Color color) { off_border_color_ = color; request_repaint(); }
    void set_corner_radius(float radius) { corner_radius_ = std::max(0.0f, radius); request_repaint(); }
    void set_font_size(float size) { font_size_ = std::max(1.0f, size); request_repaint(); }

    void set_radio_group(int id) { radio_group_ = id; }
    int radio_group() const { return radio_group_; }
 
    const std::optional<canvas::Color>& on_background_color_override() const { return on_background_color_; }
    const std::optional<canvas::Color>& off_background_color_override() const { return off_background_color_; }
    const std::optional<canvas::Color>& on_text_color_override() const { return on_text_color_; }
    const std::optional<canvas::Color>& off_text_color_override() const { return off_text_color_; }
    const std::optional<canvas::Color>& on_border_color_override() const { return on_border_color_; }
    const std::optional<canvas::Color>& off_border_color_override() const { return off_border_color_; }
    std::optional<float> corner_radius_override() const { return corner_radius_; }
    std::optional<float> font_size_override() const { return font_size_; }
    void set_designed_overlay(bool enabled) { designed_overlay_ = enabled; request_repaint(); }
    bool designed_overlay() const { return designed_overlay_; }
 
    std::function<void(bool)> on_toggle;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
    float intrinsic_height() const override { return 36.0f; }
 
private:
    bool on_ = false;
    int radio_group_ = 0;   
    std::string label_;
    std::optional<canvas::Color> on_background_color_;
    std::optional<canvas::Color> off_background_color_;
    std::optional<canvas::Color> on_text_color_;
    std::optional<canvas::Color> off_text_color_;
    std::optional<canvas::Color> on_border_color_;
    std::optional<canvas::Color> off_border_color_;
    std::optional<float> corner_radius_;
    std::optional<float> font_size_;
    bool designed_overlay_ = false;
};
 
// ── Icon ────────────────────────────────────────────────────────────────────
// Simple vector icons drawn with canvas strokes and fills
 
class Icon : public View {
public:
    enum class Type { image_upload, send, search, close };
 
    Icon() {}
    explicit Icon(Type t) : type_(t) {}
 
    void set_type(Type t) { type_ = t; }
    Type type() const { return type_; }
 
    void paint(canvas::Canvas& canvas) override;
 
private:
    Type type_ = Type::image_upload;
};
 
// ── ImageView ───────────────────────────────────────────────────────────────
// Displays an image loaded from a file path
 
class ImageCache;  // fwd; include pulp/view/image_cache.hpp in consumers
 
class ImageView : public View {
public:
    ImageView() {}

    void set_image_path(const std::string& path) {
        set_image_source(path.empty() ? std::string{} : "file://" + path);
    }
    const std::string& image_path() const { return path_; }

    void set_image_source(const std::string& uri) {
        if (uri != path_) {
            path_ = uri;
            loaded_ = false;
            cached_data_.clear();
            cached_data_key_.clear();
            cached_data_width_ = 0.0f;
            cached_data_height_ = 0.0f;
            inline_decode_failed_ = false;
        }
    }
    const std::string& image_source() const { return path_; }

    void set_image_cache(ImageCache* cache) { cache_ = cache; }
    ImageCache* image_cache() const { return cache_; }

    void set_fill_value(float value) {
        fill_value_ = value;
        request_repaint();
    }
    float fill_value() const { return fill_value_; }
    void set_fill_color(canvas::Color color) {
        fill_color_ = color;
        request_repaint();
    }
    bool has_fill() const { return fill_value_ >= 0.0f; }

    void set_fill_gradient(std::vector<canvas::Color> stops) {
        fill_gradient_ = std::move(stops);
        request_repaint();
    }
    const std::vector<canvas::Color>& fill_gradient() const { return fill_gradient_; }
    bool has_fill_gradient() const { return fill_gradient_.size() >= 2; }
 
    void paint(canvas::Canvas& canvas) override;
 
private:
    canvas::Color fill_gradient_color_at(float t) const;
 
    std::string path_;
    bool loaded_ = false;
    std::vector<uint8_t> cached_data_;  // File bytes cached after first successful load
    std::string cached_data_key_;       // SHA-256 hex of cached_data_; empty when unset
    float cached_data_width_ = 0.0f;    // Intrinsic size of cached_data_; 0 until measured
    float cached_data_height_ = 0.0f;
    bool inline_decode_failed_ = false; // Inline bytes no decoder accepted; never retried
    ImageCache* cache_ = nullptr;       // optional; owned externally
    float fill_value_ = -1.0f;          // <0 disables the silhouette fill overlay
    canvas::Color fill_color_ = canvas::Color::rgba(0.49f, 0.42f, 1.0f, 0.55f);
    std::vector<canvas::Color> fill_gradient_;  // ≥2 stops ⇒ gradient fill
};
 
// ── XYPad ────────────────────────────────────────────────────────────────────
// 2D parameter control surface (e.g., filter frequency × resonance)
 
class XYPad : public View {
public:
    XYPad() = default;
 
    void set_x(float v) { x_ = std::clamp(v, 0.0f, 1.0f); request_repaint(); }
    void set_y(float v) { y_ = std::clamp(v, 0.0f, 1.0f); request_repaint(); }
    float x_value() const { return x_; }
    float y_value() const { return y_; }

    void set_modulated_x(float normalized) {
        set_modulated_axis(has_mod_x_, mod_x_, x_, normalized);
    }
    void set_modulated_y(float normalized) {
        set_modulated_axis(has_mod_y_, mod_y_, y_, normalized);
    }
    void clear_modulated_x() {
        clear_modulated_axis(has_mod_x_);
    }
    void clear_modulated_y() {
        clear_modulated_axis(has_mod_y_);
    }
    bool has_modulated_value() const {
        return has_mod_x_ || has_mod_y_;
    }

    float modulated_display_x() const {
        return has_mod_x_ ? mod_x_ : x_;
    }
    float modulated_display_y() const {
        return has_mod_y_ ? mod_y_ : y_;
    }
 
    void set_x_label(std::string l) { x_label_ = std::move(l); }
    void set_y_label(std::string l) { y_label_ = std::move(l); }
 
    std::function<void(float, float)> on_change;
    std::function<void()> on_gesture_begin;
    std::function<void()> on_gesture_end;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    void on_mouse_drag(Point pos) override;
    void on_mouse_up(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
    // True while the puck is being dragged so a param binding yields mid-drag.
    bool is_gesture_active() const override { return dragging_; }
 
private:
    void update_from_pos(Point pos);
    void set_modulated_axis(bool& has, float& slot, float base, float normalized) {
        const float v = std::isfinite(normalized) ? std::clamp(normalized, 0.0f, 1.0f) : base;
        if (has && v == slot)
            return;
        has = true;
        slot = v;
        request_repaint_self(kModulatedMarkerHalo);
    }
    void clear_modulated_axis(bool& has) {
        if (!has)
            return;
        has = false;
        request_repaint_self(kModulatedMarkerHalo);
    }
    static constexpr float kModulatedMarkerHalo = 2.0f;
    float x_ = 0.5f, y_ = 0.5f;
    bool has_mod_x_ = false, has_mod_y_ = false;
    float mod_x_ = 0.0f, mod_y_ = 0.0f;
    std::string x_label_, y_label_;
    bool dragging_ = false;
};
 
// ── Panel ────────────────────────────────────────────────────────────────────
// Styled container with background, border, and rounding. For visual chrome.
 
class Panel : public View {
public:
    // Seed the View-side radius slot so the default 8px rounding paints.
    Panel() { View::set_border_radius(8.0f); }
 
    void set_background_token(std::string token) { bg_token_ = std::move(token); }
    void set_border_token(std::string token) { border_token_ = std::move(token); }
    // Route through View::set_border_radius so the px slot the painter reads is
    // updated and the pct slot is cleared, matching documented semantics.
    void set_corner_radius(float r) { View::set_border_radius(r); }
    void set_border_width(float w) { border_width_ = w; }
 
    const std::string& background_token() const { return bg_token_; }
    const std::string& border_token() const { return border_token_; }
    float corner_radius() const { return View::corner_radius(); }
    float border_width() const { return border_width_; }
 
    void paint(canvas::Canvas& canvas) override;
 
private:
    std::string bg_token_ = "bg.surface";
    std::string border_token_ = "control.border";
    float border_width_ = 1.0f;
};
 
// ── GroupBox ───────────────────────────────────────────────────────────────
// A titled container: rounded frame, a title chip at the top-left, and an
// optional collapse chevron at the top-right. Collapsing hides the child
// content (the caller sizes a collapsed box to header height). Matches the
// Figma "Group Box" specimen (default / collapsible-expanded / collapsed /
// empty-title-only). Children are added via add_child() and positioned by the
// caller within the content area (origin = content_top()).
class GroupBox : public View {
public:
    static constexpr float header_height = 30.0f;
 
    void set_title(std::string t) { title_ = std::move(t); request_repaint(); }
    const std::string& title() const { return title_; }
 
    void set_collapsible(bool c) { collapsible_ = c; request_repaint(); }
    bool collapsible() const { return collapsible_; }
 
    // Collapsed hides all child content; expanded shows it. `notify` controls
    // whether the change reaches `on_toggle`: `Notify::sync` (default) fires it,
    // `Notify::none` writes silently (syncing FROM the bound state), and
    // `Notify::async` defers it to the next flush. Fires only on a real change.
    void set_collapsed(bool c, Notify notify = Notify::sync);
    bool collapsed() const { return collapsed_; }
 
    // Y at which child content begins (below the header band).
    float content_top() const { return header_height + 6.0f; }
 
    std::function<void(bool collapsed)> on_toggle;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_event(const MouseEvent& event) override;
    bool wants_mouse_input() const override { return true; }
 
private:
    void apply_child_visibility();
    std::string title_;
    bool collapsible_ = false;
    bool collapsed_ = false;
};
 
// ── DualRangeSlider ──────────────────────────────────────────────────────────
// Two-thumb min↔max range selector (the Figma "Range Slider"): a track with a
// filled segment between an independently-draggable low and high thumb. (The
// single-thumb pulp::view::RangeSlider is a plain value slider; this is the
// dual-handle variant.) Horizontal or vertical; optional disabled state.
class DualRangeSlider : public View {
public:
    enum class Orientation { horizontal, vertical };
    void set_orientation(Orientation o) { orientation_ = o; request_repaint(); }
    void set_range(float min, float max) { min_ = min; max_ = std::max(min, max); clamp_(); }
    void set_low(float v) { low_ = v; clamp_(); }
    void set_high(float v) { high_ = v; clamp_(); }
    float low() const { return low_; }
    float high() const { return high_; }
    float min_value() const { return min_; }
    float max_value() const { return max_; }
    void set_enabled(bool e) { enabled_ = e; request_repaint(); }
    bool enabled() const { return enabled_; }
    // When true, a dragged thumb stops at the other thumb instead of crossing it
    // (low ≤ high always). Default false (ends move freely / may cross).
    void set_no_cross(bool b) { no_cross_ = b; }
    bool no_cross() const { return no_cross_; }
 
    // Fired on a thumb drag with the (possibly-updated) low and high values.
    std::function<void(float low, float high)> on_change;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    void on_mouse_drag(Point pos) override;
    void on_mouse_up(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
private:
    void clamp_();
    float pos_for_(float v) const;        // value → 0..1 along the track
    float value_for_pos_(float t) const;  // 0..1 → value
    float pointer_t_(Point pos) const;    // pointer → 0..1 along the track
    void apply_(Point pos);               // move the active thumb to the pointer
    Orientation orientation_ = Orientation::horizontal;
    float min_ = 0.0f, max_ = 1.0f, low_ = 0.25f, high_ = 0.70f;
    bool enabled_ = true;
    bool no_cross_ = false;
    int drag_ = -1;   // 0 = low thumb, 1 = high thumb, -1 = none
};
 
// ── InlineValueEditor ────────────────────────────────────────────────────────
// A click-to-type numeric value readout (the Figma "Inline Value Editor"): shows
// `value + suffix` idle; click to edit (caret), Enter commits, Esc cancels. A
// committed value outside [min,max] shows a danger ring and is rejected. Pair it
// with a Knob/Fader (the readout drives the control via on_change; the control
// updates the readout via set_value). States: idle / editing / invalid / disabled.
class InlineValueEditor : public View {
public:
    InlineValueEditor() { set_focusable(true); }
 
    void set_value(double v) { value_ = v; request_repaint(); }
    double value() const { return value_; }
    void set_range(double min, double max) { min_ = min; max_ = max; }
    void set_suffix(std::string s) { suffix_ = std::move(s); request_repaint(); }
    void set_decimals(int d) { decimals_ = d; request_repaint(); }
    void set_enabled(bool e) { enabled_ = e; if (!e) editing_ = false; request_repaint(); }
    bool enabled() const { return enabled_; }
    bool editing() const { return editing_; }
    bool invalid() const { return invalid_; }
 
    // Fired when a typed value is committed in range.
    std::function<void(double)> on_change;
 
    void begin_edit();
    void commit_edit();
    void cancel_edit();

    void set_caret_style(CaretStyle style) { caret_style_ = style; request_repaint(); }
    CaretStyle caret_style() const { return caret_style_; }

    void set_caret_blink(const CaretBlinkConfig& config) {
        caret_blink_.set_config(config);
        request_repaint();
    }
    const CaretBlinkConfig& caret_blink() const { return caret_blink_.config(); }
 
    ~InlineValueEditor() override;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    void on_text_input(const TextInputEvent& event) override;
    bool on_key_event(const KeyEvent& event) override;
    void on_focus_changed(bool gained) override;
    void on_frame_clock_changed() override;
    bool wants_mouse_input() const override { return true; }
 
private:
    std::string display_() const;     // value + suffix
    void subscribe_caret_blink_();
    void unsubscribe_caret_blink_();
    double value_ = 0.0, min_ = -1e9, max_ = 1e9;
    int decimals_ = 1;
    std::string suffix_;
    bool enabled_ = true, editing_ = false, invalid_ = false;
    std::string edit_buffer_;
    CaretBlink caret_blink_;
    CaretStyle caret_style_ = default_caret_style();
    int caret_blink_sub_ = -1;
    FrameClock* caret_blink_clock_ = nullptr;  
};
 
// ── WaveformRecorder ─────────────────────────────────────────────────────────
// Three-state recorder control (Ink & Signal "Recorder" component). One widget
// composes a filled waveform display, a bottom level meter with a draggable
// threshold thumb, a center transport button, and a top-right status badge,
// and re-skins all four for each state:
//
//   armed     — faint/empty waveform, red record dot, "READY" badge; the
//               threshold thumb is draggable to arm the capture trigger.
//   recording — waveform tinted with accent.error, stop square, live "REC"
//               badge; the meter shows the incoming level but the thumb is
//               locked (you can't re-arm mid-take).
//   captured  — waveform in accent.primary (teal), play triangle, "CAPTURED"
//               badge with a check; the meter is inert.
//
// Clicking the center transport button advances the state in the cycle
// armed → recording → captured → armed and fires on_state_change plus the
// matching transport callback (on_record / on_stop / on_play). All chrome is
// drawn from theme tokens so it stays legible on the dark Ink & Signal theme.
class WaveformRecorder : public View {
public:
    enum class State { armed, recording, captured };
 
    WaveformRecorder() {
        set_access_role(AccessRole::group);
        set_focusable(true);
    }

    void set_state(State s, Notify notify = Notify::sync);
    State state() const { return state_; }
    std::function<void(State)> on_state_change;

    void set_waveform(std::vector<float> samples) {
        waveform_ = std::move(samples);
        request_repaint();
    }
    const std::vector<float>& waveform() const { return waveform_; }

    void set_level(float level) {
        float c = std::clamp(level, 0.0f, 1.0f);
        if (c == level_) return;
        level_ = c;
        request_repaint();
    }
    float level() const { return level_; }

    void set_threshold(float threshold) {
        float c = std::clamp(threshold, 0.0f, 1.0f);
        if (c == threshold_) return;
        threshold_ = c;
        request_repaint();
    }
    float threshold() const { return threshold_; }
    std::function<void(float)> on_threshold_change;

    std::function<void()> on_record;
    std::function<void()> on_stop;
    std::function<void()> on_play;
 
    void paint(canvas::Canvas& canvas) override;
    void on_mouse_down(Point pos) override;
    void on_mouse_drag(Point pos) override;
    void on_mouse_up(Point pos) override;
    bool wants_mouse_input() const override { return true; }
 
private:
    Rect meter_rect_() const;
    Rect waveform_rect_() const;
    float transport_radius_() const;
    Point transport_center_() const;
    void advance_state_();
    void update_threshold_from_x_(float x);
 
    State state_ = State::armed;
    std::vector<float> waveform_;
    float level_ = 0.0f;
    float threshold_ = 0.5f;
    bool dragging_threshold_ = false;
};
 
} // namespace pulp::view
 
// clang-format off
#if defined(PULP_VIEW_HAS_AUDIO_WIDGETS)
#include <pulp/view/audio_widgets.hpp>
#endif  // PULP_VIEW_HAS_AUDIO_WIDGETS
// clang-format on