tuile 0.12.0 → 0.14.0

data/lib/tuile/screen_pane.rb

@@ -5,10 +5,15 @@ module Tuile
   #
   # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
   # invalidation set). All actual UI lives under a {ScreenPane}: the tiled
-  # {#content}, the modal {#popups} stack, and the bottom {#status_bar}.
-  # Putting them under a single Component parent gives focus traversal a real
-  # root, makes {Component#attached?} a one-liner, and lets popup-focus repair
-  # fall out of the standard {Component#on_child_removed} hook.
+  # {#content} and the {#popups} stack. Putting them under a single Component
+  # parent gives focus traversal a real root, makes {Component#attached?} a
+  # one-liner, and lets popup-focus repair fall out of the standard
+  # {Component#on_child_removed} hook.
+  #
+  # The pane owns no chrome of its own — no status bar, no reserved row.
+  # {#content} gets the full pane rect, and an app that wants a status line
+  # builds one into its own layout and drives it from
+  # {Screen#on_focus_changed=} (`D_status_bar`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -22,20 +27,15 @@ module Tuile
       # user was, instead of falling through to {#content} and getting
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
-      @status_bar = Component::Label.new
-      # Added first and never removed, so it is always the last child — which is
-      # the anchor `add_popup` inserts against.
-      add_child(@status_bar)
     end
 
     # @return [Component, nil] the tiled content component.
     attr_reader :content
-    # @return [Array<Component>] overlay popups in stacking order; last is
-    #   topmost. Holds both modal popups and non-modal overlays
-    #   ({Component::Popup#modal?}). The array must not be mutated by callers.
+    # @return [Array<Component::Overlay>] the open overlays in stacking order;
+    #   last is topmost. Holds both {Component::Popup} modals and bare
+    #   {Component::Overlay}s ({Component::Overlay#modal?}). The array must not
+    #   be mutated by callers.
     attr_reader :popups
-    # @return [Component::Label] the bottom status bar.
-    attr_reader :status_bar
 
     def focusable? = false
 
@@ -55,26 +55,26 @@ module Tuile
       layout
     end
 
-    # Adds a popup and invalidates it for repaint. A modal popup is centered
-    # and grabs focus; a non-modal overlay ({Component::Popup#modal?} false) is
-    # left wherever the caller positions it and does *not* take focus, so the
-    # component that was focused keeps the cursor and keeps receiving keys —
-    # the overlay floats above the content, driven from app code.
+    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
+    # centered and grabs focus; a bare {Component::Overlay} is left wherever
+    # the caller positioned it and does *not* take focus, so the component that
+    # was focused keeps the cursor and keeps receiving keys — the overlay
+    # floats above the content, driven from app code.
     #
-    # The *whole subtree* is invalidated, not just the popup wrapper (which
+    # The *whole subtree* is invalidated, not just the overlay wrapper (which
     # paints nothing on its own): a reopened popup may land on cells that the
     # tiled content has since overpainted, and if its rect is unchanged from
     # last time its content components won't re-invalidate themselves — so
-    # without this the popup's contents would stay blank on reopen.
-    # @param window [Component::Popup]
+    # without this the overlay's contents would stay blank on reopen.
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def add_popup(window)
-      raise TypeError, "expected Popup, got #{window.inspect}" unless window.is_a? Component::Popup
+      raise TypeError, "expected Overlay, got #{window.inspect}" unless window.is_a? Component::Overlay
       raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
 
       @popup_prior_focus[window] = screen.focused
       @popups << window
-      add_child(window, at: @children.index(@status_bar))
+      add_child(window) # appended: popups paint over the tiled content
       if window.modal?
         window.center
         screen.focused = window
@@ -124,11 +124,11 @@ module Tuile
     # @return [Boolean] true if this pane currently hosts the popup.
     def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
 
-    # @return [Component::Popup, nil] the topmost *modal* popup, or nil when
-    #   only non-modal overlays (or no popups) are open. This is the "modal
-    #   owner": the popup that scopes key dispatch, blocks mouse clicks, owns
-    #   the status bar, and confines Tab cycling. Non-modal overlays are
-    #   excluded — they float above the content without capturing input.
+    # @return [Component::Popup, nil] the topmost modal overlay, or nil when
+    #   only bare {Component::Overlay}s (or none) are open. This is the "modal
+    #   owner": the popup that scopes key dispatch, blocks mouse clicks, and
+    #   confines Tab cycling. Bare overlays are excluded — they float above the
+    #   content without capturing input.
     def modal_popup = @popups.reverse_each.find(&:modal?)
 
     # Re-lays out children whenever the pane's own rect changes.
@@ -139,18 +139,17 @@ module Tuile
       layout
     end
 
-    # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Each popup re-resolves its {Component::Popup#size} against
-    # the new screen via {Component::Popup#reposition} — so a {Fraction} size
-    # tracks resize — repositioning itself (modal popups recenter; non-modal
-    # overlays keep the top-left their owner assigned).
+    # Gives {#content} the whole pane rect — the pane reserves nothing for
+    # itself. Each popup re-resolves its {Component::Popup#declared_size} against the new
+    # screen via {Component::Popup#reposition} — so a {Fraction} size tracks
+    # resize — repositioning itself (modal popups recenter; non-modal overlays
+    # keep the top-left their owner assigned).
     # @return [void]
     def layout
       return if rect.empty?
 
-      @content.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height - 1, 0].max) unless @content.nil?
+      @content&.rect = rect
       @popups.each(&:reposition)
-      @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
     end
 
     # Pane paints nothing itself; its children paint over the entire rect.
@@ -181,18 +180,67 @@ module Tuile
       bubble_key(key, scope)
     end
 
+    # Delivers pasted text along the same focus chain {#handle_key} bubbles
+    # along, and with the same scoping — first {Component#handle_paste}
+    # returning true wins.
+    # @param text [String]
+    # @return [Boolean] true if the text was consumed.
+    def handle_paste(text)
+      scope = modal_popup || @content
+      return false if scope.nil?
+
+      chain = focus_chain(scope)
+      return false if chain.nil?
+
+      chain.each { |c| return true if c.handle_paste(text) }
+      false
+    end
+
     # Mouse events check popups in reverse stacking order (topmost first), and
     # fall through to content only when no popup is hit *and* no modal popup is
     # open. This preserves modal click-blocking — an open modal eats clicks
     # even outside its rect — while a non-modal overlay blocks nothing: clicks
     # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
     # content beneath.
+    #
+    # A left click also *dismisses* the open popups it landed outside of that
+    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
+    # second thing happening on a click, but not a second dispatch: the click is
+    # still delivered exactly once, down one chain, and a dismissed popup is
+    # closed rather than told.
+    #
+    # "Outside" is measured against the {Component::Overlay#owner} chain, not
+    # against one rect and not against stacking order: the popup the click hit
+    # is kept, and so is every popup that one *belongs to*, transitively. That
+    # is what stops a dialog being dismissed by a click on a dropdown its own
+    # field opened, and a menu cascade being dismissed by a click on one of its
+    # own deeper panels. Order carries no meaning here — between unrelated
+    # overlays it is merely the order they opened in — so ownership is declared
+    # rather than inferred from the stack.
+    #
+    # Two halves of the ordering are load-bearing, and both are specced:
+    #
+    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    #   not be in the set (it would immediately dismiss itself — every
+    #   {Component::Select} would be unopenable by mouse).
+    # - **Close after routing.** A widget toggling its own overlay from a click
+    #   on its face closes it during delivery, and {Component::Popup#close} is
+    #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
+    #   a shut overlay and reopens it — a Select's dropdown could then never be
+    #   dismissed by clicking the Select.
+    #
+    # The snapshot is a fresh array for a third reason: a handler may close
+    # further popups, and `@popups` must not be mutated mid-iteration.
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      clicked = @content if clicked.nil? && modal_popup.nil?
+      hit = @popups.reverse_each.find { _1.rect.contains?(event.point) }
+      dismissable = event.button == :left ? @popups - kept_by(hit) : []
+
+      clicked = hit || (@content if modal_popup.nil?)
       clicked&.handle_mouse(event)
+
+      dismissable.each { _1.close if _1.close_on_outside_click? }
     end
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
@@ -231,6 +279,33 @@ module Tuile
 
     private
 
+    # The overlays a click counts as landing *inside*: the one it hit, plus
+    # every overlay that one belongs to, up the {Component::Overlay#owner}
+    # chain. An owner is any component, so it is resolved to the overlay
+    # enclosing it (an overlay resolves to itself) — which keeps the
+    # relationship a live tree question rather than one frozen when the overlay
+    # opened. The `include?` guard makes a mis-wired cycle terminate instead of
+    # hanging the UI thread.
+    # @param hit [Component::Overlay, nil] the overlay the click landed in, if any.
+    # @return [Array<Component::Overlay>]
+    def kept_by(hit)
+      kept = []
+      overlay = hit
+      while overlay && !kept.include?(overlay)
+        kept << overlay
+        overlay = enclosing_popup(overlay.owner)
+      end
+      kept
+    end
+
+    # @param component [Component, nil]
+    # @return [Component::Overlay, nil] `component` itself when it is an
+    #   overlay, else the nearest overlay above it, else nil.
+    def enclosing_popup(component)
+      component = component.parent until component.nil? || component.is_a?(Component::Overlay)
+      component
+    end
+
     # Delivers `key` to {Screen#focused} and bubbles it up the ancestor chain,
     # stopping at (and including) `scope`. Delivers to no one — returning false
     # — when focus is nil or sits outside `scope`; the latter is what makes an
@@ -240,6 +315,18 @@ module Tuile
     # @param scope [Component] the modal scope root (topmost popup or content).
     # @return [Boolean] true if some component on the chain handled the key.
     def bubble_key(key, scope)
+      chain = focus_chain(scope)
+      return false if chain.nil?
+
+      chain.each { |c| return true if c.handle_key(key) }
+      false
+    end
+
+    # {Screen#focused} and its ancestors up to and including `scope`.
+    # @param scope [Component] the modal scope root (topmost popup or content).
+    # @return [Array<Component>, nil] the chain, innermost first; nil when
+    #   focus is nil or sits outside `scope`.
+    def focus_chain(scope)
       chain = []
       cursor = screen.focused
       until cursor.nil?
@@ -248,10 +335,7 @@ module Tuile
 
         cursor = cursor.parent
       end
-      return false unless chain.last.equal?(scope)
-
-      chain.each { |c| return true if c.handle_key(key) }
-      false
+      chain.last.equal?(scope) ? chain : nil
     end
 
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling

data/lib/tuile/styled_string.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
   # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
-  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile
+  # `underline`, `strikethrough`, `inverse`). Spans are non-overlapping and fully tile
   # the string — every character has exactly one resolved style, no overlay
   # layers to merge, so the style at any column is just its span's `style`
   # rather than a replay of the SGR state machine. The book's chapter 9 is
@@ -34,7 +34,7 @@ module Tuile
   # ## Parser
   #
   # {.parse} is strict by default — it recognizes only the SGR codes for
-  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough/inverse) and
   # raises {ParseError} on anything else, keeping the `parse(to_ansi(x)) == x`
   # round-trip honest. Pass `lenient: true` to instead discard everything it
   # can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep
@@ -62,17 +62,22 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] strikethrough
     #   @return [Boolean]
-    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough)
+    # @!attribute [r] inverse
+    #   @return [Boolean] swap the fg/bg *in effect* at the cell (SGR 7) —
+    #     including terminal defaults, which `fg`/`bg` can't name.
+    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough, :inverse)
       # @param fg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bold [Boolean]
       # @param italic [Boolean]
       # @param underline [Boolean]
       # @param strikethrough [Boolean]
+      # @param inverse [Boolean]
       # @return [Style]
       # @raise [ArgumentError] when a color is not one of the accepted forms.
-      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false, strikethrough: false)
-        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:)
+      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false, strikethrough: false,
+                   inverse: false)
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:, inverse:)
       end
 
       # The style with no color and no attributes — what the terminal shows
@@ -104,6 +109,7 @@ module Tuile
         codes << (other.italic ? 3 : 23) if italic != other.italic
         codes << (other.underline ? 4 : 24) if underline != other.underline
         codes << (other.strikethrough ? 9 : 29) if strikethrough != other.strikethrough
+        codes << (other.inverse ? 7 : 27) if inverse != other.inverse
         codes.concat(color_codes(other.fg, target: :fg)) if fg != other.fg
         codes.concat(color_codes(other.bg, target: :bg)) if bg != other.bg
         return "" if codes.empty?
@@ -282,6 +288,8 @@ module Tuile
           when 23 then @style = @style.merge(italic: false)
           when 4 then @style = @style.merge(underline: true)
           when 24 then @style = @style.merge(underline: false)
+          when 7 then @style = @style.merge(inverse: true)
+          when 27 then @style = @style.merge(inverse: false)
           when 9 then @style = @style.merge(strikethrough: true)
           when 29 then @style = @style.merge(strikethrough: false)
           when 30..37 then @style = @style.merge(fg: STANDARD_COLORS[code - 30])
@@ -405,7 +413,7 @@ module Tuile
     # the parts of anything else. That is the one setting never wrong in the
     # dangerous direction: under-measuring lets a glyph overrun its cell, which
     # shifts the rest of the row, desyncs the cursor and escapes the component's
-    # rect, while over-measuring leaves a blank column. `D-cluster-width` has the
+    # rect, while over-measuring leaves a blank column. `D_cluster_width` has the
     # per-setting reasoning.
     # @return [Symbol]
     EMOJI_WIDTH = :rgi
@@ -605,6 +613,10 @@ module Tuile
     # so a log line keeps its red error-level bg while its plain text picks up an
     # inherited panel tint.
     #
+    # An `inverse` span counts as backgrounded and is skipped even when its `bg`
+    # member is nil: SGR 7 swaps the pair in effect, so a bg filled under it
+    # would recolor the span's *glyphs*, not the ground behind them.
+    #
     # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background color,
     #   coerced via {Color.coerce}. `nil` returns `self` unchanged.
     # @return [StyledString]
@@ -613,7 +625,11 @@ module Tuile
 
       bg = Color.coerce(bg)
       self.class.new(@spans.map do |span|
-        span.style.bg.nil? ? Span.new(text: span.text, style: span.style.merge(bg: bg)) : span
+        if span.style.bg.nil? && !span.style.inverse
+          Span.new(text: span.text, style: span.style.merge(bg: bg))
+        else
+          span
+        end
       end)
     end
 
@@ -630,6 +646,63 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
     end
 
+    # Returns a new {StyledString} with `bold` applied to every span, preserving
+    # each span's text and other style attributes (`fg`, `bg`, `italic`,
+    # `underline`, `strikethrough`). The bold-attribute counterpart of
+    # {#with_bg} / {#with_fg}: it emphasizes a whole run of app-authored,
+    # possibly multi-span content — a widget marking one caption out of several
+    # as selected, where the caption may already carry its own colors.
+    #
+    # There is deliberately no `under_bold` (the fill-unset counterpart
+    # {#under_bg} provides for backgrounds): a background is inherited down the
+    # component tree, so a span with none has a meaningful "unset" state to
+    # fill, while `bold` is a plain per-span attribute that is either on or
+    # off. Pass `bold: false` to clear it.
+    #
+    # @param bold [Boolean] whether the spans should be bold.
+    # @return [StyledString]
+    def with_bold(bold: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bold:)) })
+    end
+
+    # Returns a new {StyledString} with `underline` applied to every span,
+    # preserving each span's text and other style attributes (`fg`, `bg`,
+    # `bold`, `italic`, `strikethrough`). Slice and rejoin to underline *part*
+    # of a string, which is what a one-character cue needs:
+    #
+    #   cap = StyledString.parse("File")
+    #   cap.slice(0, 1).with_underline + cap.slice(1, cap.display_width - 1)
+    #   # => "File" with the F underlined — a menu mnemonic
+    #
+    # Note {#slice} counts **columns**, not characters, so a caption with a
+    # wide glyph before the cue needs the prefix measured rather than counted.
+    #
+    # There is deliberately no `under_underline`, for the reason {#with_bold}
+    # spells out. Pass `underline: false` to clear it.
+    #
+    # @param underline [Boolean] whether the spans should be underlined.
+    # @return [StyledString]
+    def with_underline(underline: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(underline:)) })
+    end
+
+    # Returns a new {StyledString} with `inverse` applied to every span,
+    # preserving each span's text and other style attributes. Inverse swaps
+    # whatever fg/bg are actually in effect at each cell — terminal defaults
+    # included — so a focus chip built with it reads as "backgrounded" on any
+    # terminal palette without picking a single color:
+    #
+    #   StyledString.plain(" 1 VMs ").with_inverse   # the inverted-chip idiom
+    #
+    # There is deliberately no `under_inverse`, for the reason {#with_bold}
+    # spells out. Pass `inverse: false` to clear it.
+    #
+    # @param inverse [Boolean] whether the spans should be inverted.
+    # @return [StyledString]
+    def with_inverse(inverse: true)
+      self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(inverse:)) })
+    end
+
     # @return [String]
     def inspect
       "#<#{self.class.name} #{to_s.inspect}>"

data/lib/tuile/terminal_background.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Tuile
-  # Detects whether the terminal background is light or dark, so {Screen}
-  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  # Detects the terminal's background color — both the light/dark scheme
+  # {Screen} picks {Theme::LIGHT} or {Theme::DARK} from, and, when the
+  # terminal answers the query, the actual RGB behind it.
   #
   # Two mechanisms, in order of reliability:
   #
@@ -15,14 +16,34 @@ module Tuile
   #    bounded by a short timeout.
   # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
   #    indices. Less reliable (stale across SSH/tmux, often unset); used
-  #    only when OSC 11 yields nothing.
+  #    only when OSC 11 yields nothing. Palette indices carry no RGB, so
+  #    this path fills in {Result#scheme} and leaves {Result#color} nil.
   #
   # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
   # must complete before {EventQueue#start_key_thread} owns stdin —
   # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
   # calls {.detect} from its constructor, which apps run before
   # {Screen#run_event_loop}; don't call this after the event loop started.
+  #
+  # Once the loop *is* running the query is still available, from the other
+  # side: {Screen} writes {QUERY} on every OS appearance flip and the key
+  # thread — which owns stdin by then — reads the reply back through
+  # {Keys.getkey} and {.parse}. See {Screen#background_color}.
   module TerminalBackground
+    # What a detection found: the light/dark `scheme`, and the background
+    # `color` when a terminal actually reported one.
+    #
+    # `color` is nil whenever the scheme came from the `COLORFGBG`
+    # fallback, so a consumer deriving a tint from the background must
+    # handle nil — plenty of terminals answer neither query.
+    #
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    # @!attribute [r] color
+    #   @return [Color, nil] the reported background as 24-bit RGB, or nil
+    #     when only `COLORFGBG` answered.
+    Result = Data.define(:scheme, :color)
+
     # How long to wait for the OSC 11 reply. Generous for a local
     # terminal; bounded so unsupporting terminals (which never reply)
     # don't stall startup.
@@ -54,35 +75,63 @@ module Tuile
       # Detects the terminal background. Queries OSC 11 when both `input`
       # and `output` are TTYs, falling back to `COLORFGBG`.
       #
+      #   TerminalBackground.detect
+      #   # => #<data Result scheme=:dark, color=#<Tuile::Color [30, 30, 46]>>
+      #
       # @param input [IO] where the OSC 11 reply arrives (the TTY input).
       # @param output [IO] where the query is written (the TTY output).
       # @param env [Hash{String => String}] environment for the `COLORFGBG`
       #   fallback; defaults to `ENV` (which duck-types the `[]` lookup).
       # @param timeout [Numeric] max seconds to wait for the OSC 11 reply.
-      # @return [Symbol, nil] `:light`, `:dark`, or nil when undetectable.
+      # @return [Result, nil] nil when the background is undetectable —
+      #   neither mechanism answered.
       def detect(input: $stdin, output: $stdout, env: ENV, timeout: QUERY_TIMEOUT)
         osc = query_osc11(input, output, timeout) if input.tty? && output.tty?
-        osc || from_colorfgbg(env["COLORFGBG"])
+        return osc if osc
+
+        scheme = from_colorfgbg(env["COLORFGBG"])
+        scheme && Result.new(scheme: scheme, color: nil)
+      end
+
+      # Parses an OSC 11 reply — the terminal's answer to {QUERY}, matched
+      # anywhere in `reply`.
+      #
+      #   TerminalBackground.parse("\e]11;rgb:1e1e/1e1e/2e2e\a").color
+      #   # => #<Tuile::Color [30, 30, 46]>
+      #
+      # Public because a reply also arrives *mid-session*, long after
+      # {.detect}'s own bounded read: once the key thread owns stdin, a
+      # whole reply surfaces as one "key" from {Keys.getkey}.
+      #
+      # @param reply [String] raw terminal output that may contain a reply.
+      # @return [Result, nil] nil when `reply` holds no OSC 11 reply.
+      def parse(reply)
+        match = REPLY.match(reply)
+        return nil unless match
+
+        # Components arrive as 1–4 hex digits (terminals vary), so each is
+        # scaled by its own width: "ab" and "abab" are both ~0.67.
+        components = match.captures.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        Result.new(scheme: classify(components), color: to_color(components))
       end
 
       private
 
-      # Writes the OSC 11 query and classifies the reply. The whole
-      # exchange runs with `input` in raw mode: the reply has no trailing
-      # newline, so a canonical-mode read would block past the timeout,
-      # and echo would smear the reply bytes onto the screen.
+      # Writes the OSC 11 query and parses the reply. The whole exchange
+      # runs with `input` in raw mode: the reply has no trailing newline,
+      # so a canonical-mode read would block past the timeout, and echo
+      # would smear the reply bytes onto the screen.
       # @param input [IO]
       # @param output [IO]
       # @param timeout [Numeric]
-      # @return [Symbol, nil]
+      # @return [Result, nil]
       def query_osc11(input, output, timeout)
         reply = input.raw do
           output.write(QUERY)
           output.flush
           read_reply(input, timeout)
         end
-        match = REPLY.match(reply)
-        match && classify(match.captures)
+        parse(reply)
       rescue SystemCallError, IOError
         nil
       end
@@ -107,16 +156,25 @@ module Tuile
         buffer
       end
 
-      # Relative luminance of the reported background, scaled per
-      # component hex width (xterm replies 4 digits per channel, others 2).
-      # @param components [Array<String>] three hex strings.
+      # Light or dark, by relative luminance against a 0.5 threshold.
+      # @param components [Array<Float>] red, green and blue, each 0.0..1.0.
       # @return [Symbol] `:light` or `:dark`.
       def classify(components)
-        r, g, b = components.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        r, g, b = components
         luminance = (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
         luminance > 0.5 ? :light : :dark
       end
 
+      # The reported background as a 24-bit {Color}. Quantizing xterm's
+      # 16-bit-per-channel reply down to 8 loses nothing a terminal can
+      # display, and keeps the exposed value in the type the rest of Tuile
+      # paints with.
+      # @param components [Array<Float>] red, green and blue, each 0.0..1.0.
+      # @return [Color]
+      def to_color(components)
+        Color.rgb(*components.map { (_1 * 255).round })
+      end
+
       # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
       # ANSI palette indices. White-ish backgrounds — 7 (white) and the
       # bright range 9–15 — read as light; 0–6 and 8 as dark; anything

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.12.0"
+  VERSION = "0.14.0"
 end