path: root/gui-libs/pixdecor/files/pixdecor-focus-flash.patch

diff --git a/meson.build b/meson.build
index f4eeef3..6899f5e 100644
--- a/meson.build
+++ b/meson.build
@@ -21,3 +21,7 @@ glm    = dependency('glm')
 subdir('src')
 subdir('metadata')
 subdir('locale')
+
+# Unit tests for the focus flash logic (`meson test`); not built by default.
+focus_flash_test = executable('focus-flash-test', 'tests/focus-flash-test.cpp', build_by_default: false)
+test('focus-flash', focus_flash_test)
diff --git a/metadata/pixdecor.xml b/metadata/pixdecor.xml
index a4a3da2..7c50e8a 100644
--- a/metadata/pixdecor.xml
+++ b/metadata/pixdecor.xml
@@ -115,6 +115,33 @@
 				<default>0.0 0.0 0.0 0.25</default>
 			</option>
 		</group>
+		<group>
+			<_short>Focus flash</_short>
+			<option name="focus_flash" type="bool">
+				<_short>Flash the frame edge on focus</_short>
+				<_long>Sculpted overlay only: when keyboard focus lands on a window you are not pointing at (a window closed and the next one took over, keyboard switching, an app activating itself), its frame edge lights up for a moment so you can see where typing goes. Clicking or hovering a window, and windows that just opened, do not flash.</_long>
+				<default>true</default>
+			</option>
+			<option name="focus_flash_width" type="int">
+				<_short>Flash width</_short>
+				<_long>Width of the flashing band along the frame's outer edge, in pixels.</_long>
+				<default>3</default>
+				<min>1</min>
+				<max>16</max>
+			</option>
+			<option name="focus_flash_duration" type="int">
+				<_short>Flash duration</_short>
+				<_long>Milliseconds from the flash to nothing: full strength for the first 30%, then a fade.</_long>
+				<default>550</default>
+				<min>100</min>
+				<max>5000</max>
+			</option>
+			<option name="focus_flash_color" type="color">
+				<_short>Flash color</_short>
+				<_long>Used when frames do not follow the shell theme. With the shell theme, the flash uses the theme's accent when it contrasts with the frame by at least 4.5:1, otherwise the theme's text color.</_long>
+				<default>#FFFFFFFF</default>
+			</option>
+		</group>
 		<group>
 			<_short>General</_short>
 			<option name="ignore_views" type="string">
diff --git a/src/deco-effects.cpp b/src/deco-effects.cpp
index 957d22b..92064a8 100644
--- a/src/deco-effects.cpp
+++ b/src/deco-effects.cpp
@@ -2598,6 +2598,10 @@ void smoke_t::step_effect(const wf::scene::render_instruction_t& data, wf::geome
                     GL_CALL(glUniform1f(10, border_depth));
                     GL_CALL(glUniform4fv(11, 1, rim_f));
                     GL_CALL(glUniform1i(12, int(border_padding) > 0 ? int(border_padding) : 0));
+                    GLfloat flash_f[4] = {GLfloat(flash_color.r), GLfloat(flash_color.g),
+                        GLfloat(flash_color.b), GLfloat(flash_color.a)};
+                    GL_CALL(glUniform4fv(13, 1, flash_f));
+                    GL_CALL(glUniform1f(14, GLfloat(flash_width)));
                 }
             }
 
diff --git a/src/deco-effects.hpp b/src/deco-effects.hpp
index f24072e..70e3b08 100644
--- a/src/deco-effects.hpp
+++ b/src/deco-effects.hpp
@@ -36,6 +36,10 @@ class smoke_t
     wf::option_wrapper_t<int> rounded_corner_radius{"pixdecor/rounded_corner_radius"};
 
   public:
+    // Focus flash for the next step_effect (Sculpted only); alpha 0 = none.
+    wf::color_t flash_color{0, 0, 0, 0};
+    double flash_width = 0;
+
     smoke_t();
     ~smoke_t();
 
diff --git a/src/deco-subsurface.cpp b/src/deco-subsurface.cpp
index 8eb57e9..8496c3e 100644
--- a/src/deco-subsurface.cpp
+++ b/src/deco-subsurface.cpp
@@ -29,6 +29,8 @@
 
 #include <cairo.h>
 #include "shade.hpp"
+#include "shell-theme.hpp"
+#include "focus-flash.hpp"
 
 
 namespace wf
@@ -47,6 +49,9 @@ wf::option_wrapper_t<std::string> effect_type{"pixdecor/effect_type"};
 wf::option_wrapper_t<bool> maximized_borders{"pixdecor/maximized_borders"};
 wf::option_wrapper_t<bool> maximized_shadows{"pixdecor/maximized_shadows"};
 wf::option_wrapper_t<int> title_text_align{"pixdecor/title_text_align"};
+wf::option_wrapper_t<int> focus_flash_width{"pixdecor/focus_flash_width"};
+wf::option_wrapper_t<int> focus_flash_duration{"pixdecor/focus_flash_duration"};
+wf::option_wrapper_t<wf::color_t> focus_flash_color{"pixdecor/focus_flash_color"};
 
 class simple_decoration_node_t : public wf::scene::node_t, public wf::pointer_interaction_t,
     public wf::touch_interaction_t
@@ -110,6 +115,46 @@ class simple_decoration_node_t : public wf::scene::node_t, public wf::pointer_in
     int current_titlebar;
     wf::pointf_t current_cursor_position;
 
+    // Focus flash: started by the plugin, drawn while it fades out. A timer
+    // damages the frame meanwhile, since nothing else redraws it.
+    bool flashing = false;
+    uint32_t flash_started = 0;
+    wf::wl_timer<true> flash_frames;
+
+    double flash_level()
+    {
+        return flashing ? focus_flash::level(wf::get_current_time() - flash_started,
+            int(focus_flash_duration)) : 0.0;
+    }
+
+    void damage_frame()
+    {
+        wf::scene::damage_node(shared_from_this(), cached_region + wf::pointf_t{get_offset()});
+    }
+
+    void start_flash()
+    {
+        flashing = true;
+        flash_started = wf::get_current_time();
+        damage_frame();
+        flash_frames.set_timeout(10, [this]
+        {
+            flashing = flash_level() > 0;
+            damage_frame();
+            return flashing;
+        });
+    }
+
+    void stop_flash()
+    {
+        if (flashing)
+        {
+            flashing = false;
+            flash_frames.disconnect();
+            damage_frame();
+        }
+    }
+
     simple_decoration_node_t(wayfire_toplevel_view view) :
         node_t(false),
         theme{},
@@ -341,6 +386,11 @@ class simple_decoration_node_t : public wf::scene::node_t, public wf::pointer_in
 
             if ((std::string(effect_type) != "none") || (std::string(overlay_engine) != "none"))
             {
+                const double flash = activated ? self->flash_level() : 0.0;
+                auto flash_color = shell_focus_flash_color(focus_flash_color);
+                flash_color.a *= flash;
+                self->theme.smoke.flash_color = flash > 0 ? flash_color : wf::color_t{0, 0, 0, 0};
+                self->theme.smoke.flash_width = std::max(1, int(focus_flash_width));
                 self->theme.smoke.step_effect(data, rectangle, std::string(effect_type) == "ink",
                     self->current_cursor_position, self->theme.get_decor_color(activated),
                     self->theme.get_shadow_color(activated), effect_color,
@@ -602,6 +652,11 @@ simple_decorator_t::simple_decorator_t(wayfire_toplevel_view view)
 
     on_view_activated = [this] (auto)
     {
+        if (!this->view->activated)
+        {
+            deco->stop_flash();
+        }
+
         wf::scene::damage_node(deco, deco->get_bounding_box());
     };
 
@@ -658,6 +713,11 @@ void simple_decorator_t::update_colors()
     deco->theme.update_colors();
 }
 
+void simple_decorator_t::flash()
+{
+    deco->start_flash();
+}
+
 void simple_decorator_t::effect_updated()
 {
     deco->theme.smoke.effect_updated();
diff --git a/src/deco-subsurface.hpp b/src/deco-subsurface.hpp
index 8f56e00..a7ca1fc 100644
--- a/src/deco-subsurface.hpp
+++ b/src/deco-subsurface.hpp
@@ -48,6 +48,8 @@ class simple_decorator_t : public wf::custom_data_t
   public:
     void update_colors();
     void effect_updated();
+    // Flash the frame edge (Sculpted overlay) for pixdecor/focus_flash_duration.
+    void flash();
     void recreate_frame();
     void update_decoration_size();
     simple_decorator_t(wayfire_toplevel_view view);
diff --git a/src/decoration.cpp b/src/decoration.cpp
index e3933bb..bebd6f4 100644
--- a/src/decoration.cpp
+++ b/src/decoration.cpp
@@ -26,6 +26,9 @@
 #include <chrono>
 #include <set>
 #include "shell-theme.hpp"
+#include "focus-flash.hpp"
+#include <wayfire/seat.hpp>
+#include <wayfire/view-helpers.hpp>
 
 namespace wf
 {
@@ -47,6 +50,65 @@ class wayfire_pixdecor : public wf::plugin_interface_t
         update_colors();
         recreate_frames();
     };
+    // Focus flash (focus-flash.hpp). Keyboard focus changes are judged once the
+    // event loop is idle, so a burst of changes flashes only where focus ends.
+    wf::option_wrapper_t<bool> focus_flash_enabled{"pixdecor/focus_flash"};
+    std::weak_ptr<wf::view_interface_t> focused_window; // the app window that last had keyboard focus
+    wf::wl_idle_call judge_focus;
+    struct mapped_at_t : public wf::custom_data_t
+    {
+        uint32_t time = wf::get_current_time();
+    };
+
+    wf::signal::connection_t<wf::view_mapped_signal> on_view_mapped = [] (wf::view_mapped_signal *ev)
+    {
+        ev->view->store_data(std::make_unique<mapped_at_t>());
+    };
+
+    wf::signal::connection_t<wf::keyboard_focus_changed_signal> on_focus_changed =
+        [this] (wf::keyboard_focus_changed_signal*)
+    {
+        judge_focus.run_once([this] { judge_focus_change(); });
+    };
+
+    static bool same_window(wayfire_toplevel_view a, wayfire_toplevel_view b)
+    {
+        return a && b && (wf::find_topmost_parent(a) == wf::find_topmost_parent(b));
+    }
+
+    void judge_focus_change()
+    {
+        auto& core = wf::get_core();
+        auto view  = wf::toplevel_cast(core.seat->get_active_view());
+        if (!view || (view->role != wf::VIEW_ROLE_TOPLEVEL) || !view->is_mapped())
+        {
+            return; // a panel, launcher or popup: not a change of window
+        }
+
+        auto previous = focused_window.lock();
+        auto before   = wf::toplevel_cast(previous.get());
+        focused_window = view->weak_from_this();
+        if (before == view)
+        {
+            return;
+        }
+
+        auto deco = view->toplevel()->get_data<simple_decorator_t>();
+        focus_flash::change_t change;
+        change.enabled     = focus_flash_enabled;
+        change.framed      = deco && (std::string(overlay_engine) == "sculpted");
+        change.same_window = same_window(before, view);
+        auto mapped = view->get_data<mapped_at_t>();
+        change.just_mapped = mapped && (wf::get_current_time() - mapped->time < focus_flash::map_grace_ms);
+        auto at    = core.scene()->find_node_at(core.get_cursor_position());
+        auto under = at ? wf::toplevel_cast(wf::node_to_view(at->node.get())) : nullptr;
+        change.under_pointer = same_window(under, view);
+        if (focus_flash::should_flash(change))
+        {
+            deco->flash();
+        }
+    }
+
     wf::option_wrapper_t<int> border_size{"pixdecor/border_size"};
     wf::option_wrapper_t<std::string> title_font{"pixdecor/title_font"};
     wf::option_wrapper_t<int> title_text_align{"pixdecor/title_text_align"};
@@ -328,6 +390,8 @@ class wayfire_pixdecor : public wf::plugin_interface_t
         wf::get_core().connect(&on_app_id_changed);
         wf::get_core().connect(&on_title_changed);
         wf::get_core().connect(&on_view_tiled);
+        wf::get_core().connect(&on_view_mapped);
+        wf::get_core().connect(&on_focus_changed);
 
         if (bool(enable_shade))
         {
@@ -653,6 +717,14 @@ class wayfire_pixdecor : public wf::plugin_interface_t
         on_new_tx.disconnect();
         on_app_id_changed.disconnect();
         on_title_changed.disconnect();
+        on_view_mapped.disconnect();
+        on_focus_changed.disconnect();
+        judge_focus.disconnect();
+        for (auto view : wf::get_core().get_all_views())
+        {
+            view->erase_data<mapped_at_t>(); // its destructor lives in this plugin
+        }
+
 
         wf::get_core().bindings->rem_binding(&shade_axis_cb);
         remove_shade_transformers();
diff --git a/src/focus-flash.hpp b/src/focus-flash.hpp
new file mode 100644
index 0000000..40482ae
--- /dev/null
+++ b/src/focus-flash.hpp
@@ -0,0 +1,89 @@
+#pragma once
+// Focus flash: the outer edge of a Sculpted frame lights up for a moment when
+// keyboard focus lands on a window you are not pointing at (a window closed
+// and the next one took over, keyboard switching, an app activating itself),
+// so you can see where typing goes. Pure logic, no Wayfire dependencies.
+#include <cmath>
+#include <optional>
+#include <utility>
+
+namespace wf::pixdecor::focus_flash
+{
+// A keyboard focus change to an app window, judged once the event loop is idle
+// (several changes in one go flash only the last).
+struct change_t
+{
+    bool enabled = true;        // pixdecor/focus_flash
+    bool framed = false;        // the window has a Sculpted frame to draw on
+    bool same_window = false;   // focus was already in this window or one of its dialogs
+    bool just_mapped = false;   // the window appeared moments ago: opening is cue enough
+    bool under_pointer = false; // the pointer is over the window: clicked, or hovered with follow-focus
+};
+
+inline bool should_flash(const change_t& c)
+{
+    return c.enabled && c.framed && !c.same_window && !c.just_mapped && !c.under_pointer;
+}
+
+// How long after mapping a window's first focus counts as part of opening it.
+inline constexpr double map_grace_ms = 1000;
+
+// Strength over time: full for the first 30% of the duration, then an eased
+// fade to nothing.
+inline double level(double elapsed_ms, double duration_ms)
+{
+    if ((duration_ms <= 0) || (elapsed_ms >= duration_ms))
+    {
+        return 0;
+    }
+
+    const double hold = duration_ms * 0.3;
+    if (elapsed_ms <= hold)
+    {
+        return 1;
+    }
+
+    const double t = (elapsed_ms - hold) / (duration_ms - hold);
+    return 1 - t * t * (3 - 2 * t);
+}
+
+struct rgb_t
+{
+    double r = 0, g = 0, b = 0;
+};
+
+// WCAG relative luminance and contrast ratio.
+inline double luminance(rgb_t c)
+{
+    auto linear = [] (double v)
+    {
+        return v <= 0.04045 ? v / 12.92 : std::pow((v + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * linear(c.r) + 0.7152 * linear(c.g) + 0.0722 * linear(c.b);
+}
+
+inline double contrast(rgb_t a, rgb_t b)
+{
+    double la = luminance(a), lb = luminance(b);
+    if (la < lb)
+    {
+        std::swap(la, lb);
+    }
+
+    return (la + 0.05) / (lb + 0.05);
+}
+
+// The theme's accent when it stands out from the frame by at least 4.5:1
+// (WCAG's minimum for text), otherwise the theme's text colour, which every
+// theme keeps readable against its surfaces.
+inline constexpr double min_contrast = 4.5;
+inline rgb_t pick(const std::optional<rgb_t>& accent, rgb_t foreground, rgb_t frame)
+{
+    if (accent && (contrast(*accent, frame) >= min_contrast))
+    {
+        return *accent;
+    }
+
+    return foreground;
+}
+}
diff --git a/src/sculpted-overlay.hpp b/src/sculpted-overlay.hpp
index eaa0019..5727b6a 100644
--- a/src/sculpted-overlay.hpp
+++ b/src/sculpted-overlay.hpp
@@ -20,6 +20,10 @@ layout(location = 9) uniform vec4 shadow_color;
 layout(location = 10) uniform float border_depth;
 layout(location = 11) uniform vec4 pinstripe_color;
 layout(location = 12) uniform int border_padding;
+// Focus flash: a band this many pixels wide along the outer edge; alpha is its
+// current strength (0 = no flash, pixel-identical to the frame without it).
+layout(location = 13) uniform vec4 flash_color;
+layout(location = 14) uniform float flash_width;
 
 vec4 over(vec4 base, vec4 tint)
 {
@@ -106,6 +110,12 @@ void main()
     vec4 rim = pinstripe_color;
     rim.a *= 1.0 - smoothstep(0.5, 1.5, inset);
     body = over(body, rim);
+    if (flash_color.a > 0.0)
+    {
+        vec4 flash = flash_color;
+        flash.a *= 1.0 - smoothstep(flash_width - 0.5, flash_width + 0.5, inset);
+        body = over(body, flash);
+    }
     imageStore(out_frame, pos, body * coverage + shadow * (1.0 - coverage));
 }
 )";
diff --git a/src/shell-theme.hpp b/src/shell-theme.hpp
index 5bc7877..00ea868 100644
--- a/src/shell-theme.hpp
+++ b/src/shell-theme.hpp
@@ -1,5 +1,6 @@
 #pragma once
 
+#include "focus-flash.hpp"
 #include <wayfire/util.hpp>
 #include <wayfire/nonstd/json.hpp>
 #include <optional>
@@ -11,6 +12,7 @@ namespace wf::pixdecor
 struct shell_palette_t
 {
     wf::color_t background, surface, foreground, muted, border;
+    std::optional<wf::color_t> accent; // Optional: older shells do not send it.
 };
 
 inline wf::color_t shell_color(const wf::json_t& value)
@@ -27,9 +29,15 @@ inline wf::color_t shell_color(const wf::json_t& value)
 
 inline shell_palette_t parse_shell_palette(const wf::json_t& data)
 {
-    return {shell_color(data["background"]), shell_color(data["surface"]),
+    shell_palette_t palette{shell_color(data["background"]), shell_color(data["surface"]),
         shell_color(data["foreground"]), shell_color(data["muted"]),
-        shell_color(data["border"])};
+        shell_color(data["border"]), std::nullopt};
+    if (data.has_member("accent"))
+    {
+        palette.accent = shell_color(data["accent"]);
+    }
+
+    return palette;
 }
 
 // Live presentation only. Saved custom colors remain in wayfire.ini.
@@ -47,4 +55,16 @@ inline wf::color_t shell_pinstripe_color(wf::color_t custom)
     themed.a = custom.a;
     return themed;
 }
+// The focus flash on a focused frame (drawn in the theme's surface colour):
+// the accent if it contrasts enough, else the text colour. Custom colors use
+// pixdecor/focus_flash_color.
+inline wf::color_t shell_focus_flash_color(wf::color_t custom)
+{
+    if (!shell_colors_active()) return custom;
+    auto rgb = [] (wf::color_t c) { return focus_flash::rgb_t{c.r, c.g, c.b}; };
+    std::optional<focus_flash::rgb_t> accent;
+    if (shell_palette->accent) accent = rgb(*shell_palette->accent);
+    auto chosen = focus_flash::pick(accent, rgb(shell_palette->foreground), rgb(shell_palette->surface));
+    return {chosen.r, chosen.g, chosen.b, 1.0};
+}
 }
diff --git a/tests/focus-flash-test.cpp b/tests/focus-flash-test.cpp
new file mode 100644
index 0000000..362948d
--- /dev/null
+++ b/tests/focus-flash-test.cpp
@@ -0,0 +1,80 @@
+// Unit tests for the focus flash: when it flashes, how it fades, and which
+// theme colour it uses.
+#include "../src/focus-flash.hpp"
+#include <cassert>
+#include <cstdio>
+
+using namespace wf::pixdecor::focus_flash;
+
+static change_t keyboard_switch()
+{
+    change_t c;
+    c.framed = true;
+    return c;
+}
+
+static rgb_t hex(unsigned v)
+{
+    return {((v >> 16) & 0xff) / 255.0, ((v >> 8) & 0xff) / 255.0, (v & 0xff) / 255.0};
+}
+
+static bool same(rgb_t a, rgb_t b)
+{
+    return a.r == b.r && a.g == b.g && a.b == b.b;
+}
+
+int main()
+{
+    // Focus moved to another framed window that you are not pointing at:
+    // closing a window, Alt+Tab, an app activating itself.
+    change_t c = keyboard_switch();
+    assert(should_flash(c));
+
+    // Clicked or hovered (follow-focus): the pointer is on it, no flash.
+    c.under_pointer = true;
+    assert(!should_flash(c));
+
+    // Back to the same window or between a window and its dialogs.
+    c = keyboard_switch();
+    c.same_window = true;
+    assert(!should_flash(c));
+
+    // A window that just opened takes focus: opening is cue enough.
+    c = keyboard_switch();
+    c.just_mapped = true;
+    assert(!should_flash(c));
+
+    // Switched off, or nothing to draw on (no frame, not Sculpted).
+    c = keyboard_switch();
+    c.enabled = false;
+    assert(!should_flash(c));
+    c = keyboard_switch();
+    c.framed = false;
+    assert(!should_flash(c));
+
+    // Strength: full, held for 30%, eased to nothing, then off.
+    assert(level(0, 550) == 1);
+    assert(level(165, 550) == 1);
+    double mid = level(357.5, 550), late = level(500, 550);
+    assert(mid > 0.49 && mid < 0.51);
+    assert(late > 0 && late < mid);
+    assert(level(550, 550) == 0 && level(9000, 550) == 0);
+    assert(level(100, 0) == 0);
+
+    // Contrast: WCAG ratios.
+    assert(contrast(hex(0xffffff), hex(0x000000)) > 20.99);
+    assert(contrast(hex(0x777777), hex(0x777777)) == 1);
+
+    // Colour: Flexoki Dark's accent (4.4:1 against its surface) misses 4.5:1,
+    // so its text colour is used; OLED's accent (10:1) is used; Forest
+    // (light, 3.3:1) falls back to its dark text colour.
+    rgb_t flexoki_surface = hex(0x1c1b1a), flexoki_text = hex(0xcecdc3);
+    assert(same(pick(hex(0x4385be), flexoki_text, flexoki_surface), flexoki_text));
+    assert(same(pick(hex(0x86badf), hex(0xf0f3f5), hex(0x000000)), hex(0x86badf)));
+    assert(same(pick(hex(0x279141), hex(0x151e17), hex(0xe4ece6)), hex(0x151e17)));
+    // No accent from the shell (older Pyr): the text colour.
+    assert(same(pick(std::nullopt, flexoki_text, flexoki_surface), flexoki_text));
+
+    std::puts("focus flash tests passed");
+    return 0;
+}