raindown 0.5.1 → 0.7.0

data/lib/raindown/tui/navigator/search.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative '../events'
+require_relative '../views/endpoint_view'
+require_relative '../workers/worker'
+
+module Raindown
+  module TUI
+    # Teleport: "/" opens a search of the Dashboard, Code feelings, every file, heading and directive in the files, and every endpoint,
+    # matched as it's typed by letters in order, so "stp" finds "## Setup". Up and down move between the matches,
+    # Enter or a click opens the one selected, and Esc closes it. Other keys and clicks do nothing while it's open.
+    module Search
+      # The most matches it shows.
+      LIMIT = 10
+
+      # A place to teleport to: its text, where it is, like "guides/setup.md:12", and the step that opens it.
+      Place = Data.define(:text, :where, :open) do
+        # How well the query matches, or nil when it doesn't: in the text alone, which ranks above a match that needs
+        # where it is too, like "setup notes" for "## Setup" in notes.md.
+        def score(query)
+          in_text = letters_score(text, query)
+          return in_text + query.length if in_text
+
+          letters_score("#{text} #{where}", query)
+        end
+
+        private
+
+        # How well the query's letters appear in order in the text, ignoring case: higher for runs of them and for
+        # the starts of words, or nil when they don't all appear.
+        def letters_score(text, query)
+          haystack = text.downcase
+          last = -1
+          score = 0
+          query.downcase.each_char do |char|
+            index = haystack.index(char, last + 1)
+            return nil unless index
+
+            score += 1
+            score += 2 if index == last + 1
+            score += 2 if index.zero? || haystack[index - 1].match?(%r{[\s/#:._-]})
+            last = index
+          end
+          score
+        end
+      end
+
+      # What's typed, while the search is open, and the selected match.
+      attr_reader :query, :match
+
+      def searching? = !query.nil?
+
+      # The places that match what's typed, best first, then in the order they're in the files.
+      def matches
+        @places.each_with_index.filter_map { |place, index| (score = place.score(query)) && [-score, index, place] }
+               .min(LIMIT).map(&:last)
+      end
+
+      private
+
+      def open_search
+        @places = places
+        @match = 0
+        @query = ''
+        nil
+      end
+
+      def search_event(name)
+        case name
+        when :up, :down then move_match(name == :up ? -1 : 1)
+        when :enter then teleport
+        when :escape then close_search
+        when :backspace then type_query(query[0...-1])
+        end
+      end
+
+      def type_query(query)
+        @query = query
+        @match = 0
+        nil
+      end
+
+      def move_match(by)
+        @match = (@match + by).clamp(0, [matches.length - 1, 0].max)
+        nil
+      end
+
+      def teleport
+        place = matches[@match]
+        close_search
+        place&.open&.take(self)
+      end
+
+      def close_search
+        @query = nil
+        nil
+      end
+
+      def places
+        [Place.new(text: 'Dashboard', where: '', open: OpenView.new(view: dashboard)),
+         Place.new(text: 'Code feelings', where: '', open: OpenView.new(view: feelings)),
+         *@files.files.flat_map { file_places(it) },
+         *@endpoints.all.map { Place.new(text: it.text, where: "#{relative(it.path)}:#{it.line}", open: open_endpoint(it)) }]
+      end
+
+      # The file, then its headings and directives, in the order they're in it.
+      def file_places(path)
+        outline = @workers.for(path).call(:outline, path)
+        where = relative(path)
+        items = (outline.headings + outline.directives).sort_by(&:line)
+        [Place.new(text: where, where: '', open: Open.new(path:, line: nil)),
+         *items.map { Place.new(text: item_text(it), where: "#{where}:#{it.line}", open: Open.new(path:, line: it.line)) }]
+      rescue Worker::Error
+        []
+      end
+
+      def item_text(item)
+        return "#{'#' * item.level} #{item.text}" if item.is_a?(Document::Heading)
+
+        "#{item.name}: #{item.args}".strip
+      end
+
+      def open_endpoint(endpoint) = OpenView.new(view: EndpointView.new(endpoint, workers: @workers))
+    end
+  end
+end

data/lib/raindown/tui/navigator/views.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative '../views/dashboard_view'
+require_relative '../views/endpoint_view'
+require_relative '../feelings/feelings_view'
+require_relative '../views/outline_view'
+
+module Raindown
+  module TUI
+    # Beside the files, a Navigator shows a view: the open file's Outline, the Dashboard of the project's charts,
+    # which is the first item in the files and "d" switches to, or an EndpointView of an endpoint listed below them.
+    # A view has the pane that draws it, a next step for the keys it takes while it has the focus, and a target,
+    # what's opened it in the files. It loads when it's opened, and again after a change.
+    module Views
+      attr_reader :view, :dashboard, :feelings
+
+      # The path of the file the view shows, if any.
+      def path = view.path
+
+      # Shows the view right of the files, with the focus, and the files' cursor on the row that opened it.
+      def open_view(view)
+        @previous = @view unless view == @view
+        @view = view
+        @focus = :main
+        @nav.cursor = @nav.rows.index { it.target == view.target } || 0
+        view.load
+        @status = view.status(self)
+        nil
+      end
+
+      # Opens the file in the outline, on the heading or directive at the line.
+      def open_at(path, line)
+        path = File.expand_path(path)
+        @files.reveal(path)
+        open_view(OutlineView.new(path, workers: @workers))
+        view.cursor = view.rows.index { %i[heading directive].include?(it.kind) && it.target.line == line } || 0
+        nil
+      end
+
+      private
+
+      def open_feelings = open_view(feelings)
+
+      # Switches between the dashboard and the view before it.
+      def toggle_dashboard
+        return open_view(@previous) if view == dashboard && @previous
+
+        open_view(dashboard)
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/dashboard_renderer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+
+module Raindown
+  module TUI
+    # The dashboard, right of the files: a card for each of the projects' charts, as wide as its chart,
+    # with as many in a row as fit. With more than one project, each project's charts are under its path.
+    # A card has its file and heading, and its directive, both cut to the chart's width, then the chart,
+    # in a border with rounded corners:
+    #    ╭─────────────────────────────╮  ╭────────────────────────────────╮
+    #    │ raindown.rd › Charts        │  │ raindown.rd › Commits          │
+    #    │ chart: 'data/downloads.csv' │  │ chart: 'data/commits.csv' min… │
+    #    │ Jun  ██████▊           640  │  │ c2f98fc  -18  █│███▊      +96  │
+    #    ╰─────────────────────────────╯  ╰────────────────────────────────╯
+    class DashboardRenderer < Renderer
+      BUTTONS = [['Tab', 'Pane', :tab], ['Enter', 'Open', :enter], ['e', 'Edit', :edit], ['r', 'Reload', :reload],
+                 ['/', 'Search', :search], ['q', 'Quit', :quit]].freeze
+      PROJECTS_BUTTON = ['p', 'Projects', :projects].freeze
+
+      # Room for the project menu's button, when there's more than one project.
+      def buttons
+        return BUTTONS unless navigator.projects?
+
+        BUTTONS.dup.insert(3, PROJECTS_BUTTON)
+      end
+
+      def page = 'Dashboard'
+
+      def lines
+        cards = dashboard.cards
+        return blank(height, " No charts in #{File.basename(navigator.root)} yet, like <{ chart: '3 5 2 8' }>") if cards.empty?
+
+        rows = dashboard.rows(width)
+        @headings = headings(rows, cards)
+        grid(rows, cards)
+      end
+
+      private
+
+      def dashboard = navigator.dashboard
+
+      # Each project's path above its first row of cards, by the row's index, when there's more than one project.
+      def headings(rows, cards)
+        firsts = rows.each_index.chunk_while { |a, b| cards[rows[a].first].project == cards[rows[b].first].project }.map(&:first)
+        return {} if firsts.one?
+
+        firsts.to_h { [it, cards[rows[it].first].project] }
+      end
+
+      # The rows of cards from the first that's scrolled to, each card's lines side by side, with a line between rows.
+      def grid(rows, cards)
+        heights = rows.each_with_index.map { |row, index| row_height(row, cards) + (@headings.key?(index) ? 1 : 0) }
+        first = dashboard.scroll(heights, height)
+        lines = (first...rows.length).flat_map { |index| row_lines(rows[index], cards, heading: @headings[index]) }
+
+        (lines + blank(height)).first(height)
+      end
+
+      # The tallest card's lines, in its border, and one line below it.
+      def row_height(row, cards)
+        row.map { cards[it].box_height }.max + 1
+      end
+
+      def row_line(row, cards, line)
+        segments = [segment('', :blank, width: 1)]
+
+        row.each_with_index do |index, column|
+          segments << segment('', :blank, width: DashboardView::GAP) unless column.zero?
+          segments.concat(card_line(cards[index], index, line))
+        end
+
+        padded(segments)
+      end
+
+      # A card opens chart source when it's clicked, like Enter, but not the space below a card shorter than its row.
+      # The selected card's title is highlighted, like a selected row.
+      def card_line(card, index, line)
+        title_style = dashboard.cursor == index ? row_style(pane, nil, true) : :heading
+        event = Click.new(pane:, index:, action: :enter) if line < card.box_height
+        box_width = card.box_width(within: dashboard.card_widths(width))
+        card.format_line(line, box_width:, title_style:).map do |text, style, part_width|
+          segment(text, style, width: part_width, event:)
+        end
+      end
+
+      # A row of cards' lines, under its project's heading when it's the project's first row.
+      def row_lines(row, cards, heading:)
+        [*([heading_line(heading)] if heading), *Array.new(row_height(row, cards)) { |line| row_line(row, cards, line) }]
+      end
+
+      # A project's path from the home folder, above its charts.
+      def heading_line(project)
+        [segment(" #{from_home(project)}", :project)]
+      end
+
+      def blank(count, message = '')
+        [[segment(message, :info)], *Array.new([count - 1, 0].max) { [segment('', :blank)] }].first(count)
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/endpoint_renderer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative '../highlighter'
+require_relative 'renderer'
+require_relative 'outline_renderer'
+
+module Raindown
+  module TUI
+    # An endpoint opened from the files, right of them: its URL in a bar with rounded corners, and a button to run it,
+    # then its response:
+    #    ╭──────────────────────────────────────────╮
+    #    │ GET https://httpbin.org/uuid       [Run] │
+    #    ╰──────────────────────────────────────────╯
+    #
+    #    Response · json · fetched 2026-10-26
+    #    {
+    #      "uuid": "48024974-f1b1-431a-a0cf-5cac0099a1a5"
+    #    }
+    class EndpointRenderer < Renderer
+      RUN = '[Run]'
+      RUN_WIDTH = RUN.length
+      BUTTONS = OutlineRenderer::BUTTONS.reject { it.last == :write_back }.freeze
+
+      def buttons = BUTTONS
+      def page = navigator.view.endpoint.text
+
+      def lines
+        view = navigator.view
+        top = [*url_bar(view.endpoint), [segment('', :blank, width:)], about(view)]
+
+        (top + response(view, height - top.length)).first(height)
+      end
+
+      private
+
+      # A click on the response moves the focus to it, to scroll it.
+      def focus = Click.new(pane:, index: 0, action: :focus)
+
+      # The response's lines that fit, highlighted in the language of its code block, like json.
+      def response(view, lines)
+        code = Highlighter.lines(view.visible([lines, 0].max), language: view.language)
+        Array.new([lines, 0].max) do |line|
+          [segment(' ', :response, width: 1, event: focus), *code_segments(code[line] || [], width - 1, event: focus)]
+        end
+      end
+
+      # The bar is a column in from each side of the pane, with the URL and the button inside its border.
+      def url_bar(endpoint)
+        inner = [width - 6, 0].max
+        [edge('╭', '╮', inner), padded([margin, segment('│ ', :border, width: 2), *request(endpoint, inner)]),
+         edge('╰', '╯', inner)]
+      end
+
+      # The method in its colour, then the URL, cut to what the method and button leave, then the button,
+      # and the border's side.
+      def request(endpoint, inner)
+        method_width = display_width(endpoint.method)
+        url_width = [inner - method_width - RUN_WIDTH - 1, 0].max
+
+        [segment(endpoint.method, endpoint.style, width: method_width), segment(" #{endpoint.url} ", :url, width: url_width + 1),
+         run_button, segment(' │', :border, width: 2)]
+      end
+
+      def run_button = segment(RUN, :button, width: RUN_WIDTH, event: Click.new(pane:, index: 0, action: :execute))
+
+      def edge(left, right, inner)
+        padded([margin, segment("#{left}#{'─' * (inner + 2)}#{right}", :border, width: inner + 4)])
+      end
+
+      def margin = segment('', :blank, width: 1)
+
+      def about(view)
+        return [segment(" #{view.error}", :error, width:)] if view.error
+        return [segment(' No response yet. X runs the request.', :heading, width:)] if view.response.empty?
+
+        details = ['Response', view.language, ("fetched #{view.fetched}" if view.fetched)].reject { it.to_s.empty? }
+        [segment(" #{details.join(' · ')}", :heading, width:)]
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/list_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+
+module Raindown
+  module TUI
+    # A ListView's rows in its pane, like the files in the nav or a file's outline, each with its buttons.
+    class ListRenderer < Renderer
+      def lines
+        list = navigator.content(pane).visible(height)
+        Array.new(height) { |index| cell(pane, *list, index, width) }
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/outline_renderer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'list_renderer'
+
+module Raindown
+  module TUI
+    # The open file's outline, right of the files: a row on each line, with its buttons.
+    class OutlineRenderer < ListRenderer
+      BUTTONS = [['Tab', 'Pane', :tab], ['Enter', 'Open', :enter], ['x', 'Run', :execute], ['e', 'Edit', :edit],
+                 ['w', 'Write back', :write_back], ['r', 'Reload', :reload], ['/', 'Search', :search], ['q', 'Quit', :quit]].freeze
+
+      def buttons = BUTTONS
+
+      def page
+        return 'No Markdown files' unless navigator.path
+
+        navigator.relative(navigator.path)
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/renderer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../events'
+require_relative '../rows'
+require_relative '../text'
+
+module Raindown
+  module TUI
+    # Draws what's in a pane, :nav or :main, as lines of the pane's width and height, which the Layout puts in it.
+    Renderer = Struct.new(:navigator, :pane, :width, :height) do
+      include Rows
+      include Text
+
+      # Its side of the line above the panes, which is blank unless it has something to say there, like a progress.
+      def spacer = [segment('', :blank)]
+    end
+  end
+end

data/lib/raindown/tui/row.rb

@@ -3,14 +3,23 @@
 module Raindown
   module TUI
     # A line of a pane. Target is what it's about: a folder or file path, a Heading or Directive, or a line number.
-    # Buttons are [label, event] pairs, like ['[Run]', :execute].
-    Row = Data.define(:text, :depth, :kind, :target, :buttons) do
-      def initialize(buttons: [], **) = super
+    # Buttons are [label, event] pairs, like ['[Run]', :execute], and a tag is an Endpoint, whose method is before its text.
+    # Open is the Navigator's next step on Enter, like an Open of a file, and fold, a block that folds or expands the row.
+    # Code is the text highlighted, as [text, style] parts, for a line of code, like a directive's body.
+    # Each optional field has a default, which is why initialize takes so many.
+    Row = Data.define(:text, :depth, :kind, :target, :buttons, :tag, :open, :fold, :code) do
+      def initialize(buttons: [], tag: nil, open: nil, fold: nil, code: nil, **) = super # rubocop:disable Metrics/ParameterLists
+
+      # A separator is space between a pane's sections, which the cursor skips and clicks don't reach.
+      def selectable? = kind != :separator
 
       # The line the editor opens at for the row.
       def line
         target.is_a?(Integer) ? target : target.line
       end
     end
+
+    # Space between a pane's sections, like the Dashboard and the files.
+    Row::SEPARATOR = Row.new(text: '', depth: 0, kind: :separator, target: nil)
   end
 end

data/lib/raindown/tui/rows.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A ListRenderer's rows, like the files and the outline, each a line of the pane's width: a row's text, after its tag,
+    # like an endpoint's method, then its buttons.
+    module Rows
+      private
+
+      # A row as its text, then its buttons, or blank below its last row.
+      def cell(pane, rows, offset, index, cell_width)
+        row = rows[index]
+        return [segment('', :blank, width: cell_width)] unless row&.selectable?
+
+        index += offset
+        selected = navigator.content(pane).cursor == index
+        buttons = row_buttons(row, pane:, index:, selected:, cell_width:)
+        text_width = cell_width - display_width(buttons.map(&:text).join)
+        parts = row_parts(row, row_style(pane, row, selected), selected)
+
+        [*spread_segments(parts, text_width, event: Click.new(pane:, index:, action: :enter)), *buttons]
+      end
+
+      # A line's segments, then blank to the edge.
+      def padded(segments) = [*segments, segment('', :blank, width: [width - segments.sum { display_width(it.text) }, 0].max)]
+
+      # [text, style] parts side by side in the width, each a segment.
+      def spread_segments(parts, width, event: nil)
+        parts.zip(spread(parts.map(&:first), width)).map { |(text, style), part| segment(text, style, width: part, event:) }
+      end
+
+      # The row's text, after its tag in the tag's style, or highlighted when it's code, unless the row's selected.
+      def row_parts(row, style, selected)
+        lead = " #{Text::INDENT * row.depth}"
+        return [[lead, style], *row.code] if row.code && !selected
+        return [["#{lead}#{row.text}", style]] unless row.tag
+
+        [["#{lead}#{row.tag.method} ", selected ? style : row.tag.style], [row.text, style]]
+      end
+
+      # The row's buttons, right of its text, unless they'd take more than half the pane.
+      def row_buttons(row, pane:, index:, selected:, cell_width:)
+        buttons = row.buttons.map do |label, event|
+          style = selected ? :"#{row_style(pane, row, true)}_button" : :button
+          segment(" #{label}", style, width: display_width(" #{label}"), event: Click.new(pane:, index:, action: event))
+        end
+        display_width(buttons.map(&:text).join) > cell_width / 2 ? [] : buttons
+      end
+
+      # The cursor's row is highlighted in the pane with the focus, and dimmer in the other, like the file a chart opened.
+      def row_style(pane, row, selected)
+        return row.kind unless selected
+
+        navigator.focus == pane ? :selected : :cursor
+      end
+    end
+  end
+end

data/lib/raindown/tui/search_overlay.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'events'
+require_relative 'text'
+
+module Raindown
+  module TUI
+    # The search, drawn over the screen's lines in a box below the title: what's typed, then the places that match it,
+    # each with where it is, and the selected one highlighted:
+    #    ┌─ Teleport ───────────────────────────────┐
+    #    │ / stp▏                                   │
+    #    │ ## Setup               guides/setup.md:3 │
+    #    │ ## Steps                     notes.md:12 │
+    #    └──────────────────────────────────────────┘
+    # Each place is clicked to open it.
+    class SearchOverlay
+      include Text
+
+      # The widest the box is, with its border.
+      MAX_WIDTH = 72
+
+      def initialize(navigator, width:)
+        @navigator = navigator
+        @box_width = [width - 4, MAX_WIDTH].min
+        @column = (width - @box_width) / 2
+      end
+
+      # The lines with the box drawn over them, from the line below the title.
+      def apply(lines)
+        box.each_with_index do |segments, offset|
+          row = offset + 1
+          lines[row] = overlay_segments(lines[row], segments, column: @column) if lines[row]
+        end
+        lines
+      end
+
+      private
+
+      # The columns inside the border, "│ " and " │".
+      def inner = @box_width - 4
+
+      def box
+        [edge('┌─ Teleport ', '┐'), boxed(segment("/ #{@navigator.query}▏", :menu, width: inner)), *results, edge('└', '┘')]
+      end
+
+      def results
+        matches = @navigator.matches
+        return [boxed(segment('No matches', :info, width: inner))] if matches.empty?
+
+        matches.each_with_index.map { |place, index| place_line(place, index) }
+      end
+
+      # The place's text, then where it is, on the right, both highlighted when it's selected.
+      def place_line(place, index)
+        text_style = :menu
+        where_style = :body
+        text_style = where_style = :selected if @navigator.match == index
+        event = Click.new(pane: :search, index:, action: :enter)
+        where = " #{place.where}"
+        where_width = [display_width(where), inner / 2].min
+
+        boxed(segment(place.text, text_style, width: inner - where_width, event:),
+              segment(where, where_style, width: where_width, event:))
+      end
+
+      def boxed(*segments) = [segment('│ ', :border, width: 2), *segments, segment(' │', :border, width: 2)]
+
+      def edge(left, right)
+        [segment("#{left}#{'─' * (@box_width - display_width(left) - 1)}#{right}", :border, width: @box_width)]
+      end
+    end
+  end
+end

data/lib/raindown/tui/terminal/input.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'curses'
+require 'unicode/display_width'
+
+require_relative '../events'
+
+module Raindown
+  module TUI
+    # Turns curses' keys and clicks into a Navigator's events.
+    module Input
+      KEYS = {
+        Curses::KEY_UP => :up, 'k' => :up, Curses::KEY_DOWN => :down, 'j' => :down,
+        Curses::KEY_LEFT => :left, 'h' => :left, Curses::KEY_RIGHT => :right, 'l' => :right,
+        "\t" => :tab, Curses::KEY_BTAB => :tab, "\r" => :enter, "\n" => :enter, Curses::KEY_ENTER => :enter,
+        ' ' => :toggle, 'x' => :execute, 'e' => :edit, 'w' => :write_back, 'r' => :reload, 'd' => :dashboard,
+        'p' => :projects, 'f' => :feelings, "\x14" => :celebrate, '/' => :search,
+        '1' => :bin1, '2' => :bin2, '3' => :bin3, '4' => :bin4, '5' => :bin5, '6' => :bin6, "\e" => :escape, 'q' => :quit
+      }.freeze
+      # While typing, like in the search, printable characters are typed, and only these keys do anything else.
+      TYPING_KEYS = {
+        Curses::KEY_UP => :up, Curses::KEY_DOWN => :down, "\r" => :enter, "\n" => :enter, Curses::KEY_ENTER => :enter,
+        "\e" => :escape, Curses::KEY_BACKSPACE => :backspace, "\x7F" => :backspace, "\b" => :backspace
+      }.freeze
+
+      module_function
+
+      # A key from getch, which is a string for a printable character and otherwise a number.
+      # Letters are the same with Shift, as the buttons show them as capitals, unless they're being typed.
+      def key_event(key, typing: false)
+        return typing_event(key) if typing
+
+        key = key.chr if key.is_a?(Integer) && key < 256
+        KEYS[key.is_a?(String) ? key.downcase : key]
+      end
+
+      def typing_event(key)
+        key = key.chr if key.is_a?(Integer) && key < 256
+        TYPING_KEYS.fetch(key) { Type.new(text: key) if key.is_a?(String) && key.match?(/\A[[:print:]]\z/) }
+      end
+
+      # The mouse buttons that click, which are the left button's. Scrolling does nothing, and since older ncurses,
+      # like macOS's, has no button for scrolling down, it can't be mistaken for a click.
+      CLICKS = Curses::BUTTON1_PRESSED | Curses::BUTTON1_CLICKED
+
+      # Moving the mouse, which terminals report once they're asked to, with any motion tracking.
+      MOTION = Curses::REPORT_MOUSE_POSITION
+      ANY_MOTION = "\e[?1003h"
+      NO_MOTION = "\e[?1003l"
+
+      # The terminal sends the app its mouse events, clicks and moves, so scrolling doesn't scroll the terminal either.
+      # ncurses only asks some terminals to report every move, so it's asked directly too, until untrack_mouse.
+      def track_mouse
+        Curses.mousemask(CLICKS | MOTION)
+        Curses.mouseinterval(0)
+        $stdout.write(ANY_MOTION)
+        $stdout.flush
+      end
+
+      def untrack_mouse
+        $stdout.write(NO_MOTION)
+        $stdout.flush
+      end
+
+      # A click sends the event of what's under it, and moving the mouse a Hover of it.
+      def mouse_event(event, zones)
+        target = click(zones, column: event.x, row: event.y)
+        return target if event.bstate.anybits?(CLICKS)
+
+        Hover.new(target:) if event.bstate.anybits?(MOTION)
+      end
+
+      # Where each of a Layout's segments with an event is on the screen, as [row, columns, event].
+      def zones(lines)
+        lines.each_with_index.flat_map do |segments, row|
+          column = 0
+          segments.filter_map do |segment|
+            width = Unicode::DisplayWidth.of(segment.text)
+            zone = [row, column...(column + width), segment.event] if segment.event
+            column += width
+            zone
+          end
+        end
+      end
+
+      def click(zones, column:, row:)
+        zones.find { |zone_row, columns, _event| zone_row == row && columns.cover?(column) }&.last
+      end
+    end
+  end
+end