rakpak 1.0.0 → 1.2.0

data/lib/rakpak/modal.rb

@@ -4,8 +4,6 @@ require_relative "theme"
 require_relative "text"
 
 module Rakpak
-  # Base class for the centred overlay panels. Subclasses fill the body;
-  # geometry, frame, title and footer are handled here.
   class Modal
     attr_reader :result
 
@@ -15,7 +13,6 @@ module Rakpak
       @result = nil
     end
 
-    # Desired [width, height] given the screen.
     def dims(screen)
       [[screen.w - 6, 72].min, [screen.h - 4, 20].min]
     end
@@ -41,11 +38,9 @@ module Rakpak
 
     def body(screen, x, y, w, h); end
 
-    # :done, :cancel or nil
     def handle(_key) = nil
   end
 
-  # A vertical list of choices, some of which may be unavailable.
   class SelectModal < Modal
     Item = Struct.new(:label, :value, :blurb, :enabled, :why, keyword_init: true)
 
@@ -122,7 +117,6 @@ module Rakpak
     end
   end
 
-  # A form of mixed rows: cycling choices, numeric ranges and toggles.
   class FormModal < Modal
     Row = Struct.new(:kind, :label, :hint, :get, :set, :values, keyword_init: true)
 
@@ -214,7 +208,6 @@ module Rakpak
       end
     end
 
-    # The reason the current settings cannot be run, or nil.
     def unusable
       @rows.each do |row|
         next unless row.kind == :choice
@@ -269,8 +262,6 @@ module Rakpak
     end
   end
 
-  # Single-line text field with the editing keys people expect. `validate`
-  # is given the trimmed text and returns a reason to refuse it, or nil.
   class InputModal < Modal
     def initialize(title:, value: "", hint: "", footer: "enter accept · esc back", validate: nil)
       super(title: title, footer: footer)
@@ -294,11 +285,10 @@ module Rakpak
       field(screen, x, y + (@hint.empty? ? 0 : 2), w, active: true)
     end
 
-    # The text box on its own, for embedding in another panel.
     def field(screen, x, row, w, active: true)
       screen.fill(x, row, w, 1, " ", Theme::SEL_BG)
       width = w - 2
-      # Scroll so the cursor is visible, counting columns, not characters.
+      # Scroll by display columns, not characters.
       off = 0
       off += 1 while off < @cur && Text.width(@buf[off...@cur]) >= width
       shown = +""
@@ -342,7 +332,9 @@ module Rakpak
       when :ctrl_u then @buf.slice!(0, @cur) && (@cur = 0)
       when :ctrl_k then @buf.slice!(@cur..)
       when :ctrl_w
-        left = @buf[0, @cur].sub(/\S*\s*\z/, "")
+        left = @buf[0, @cur].rstrip
+        boundary = left.rindex(/\s/)
+        left = boundary ? left[0..boundary] : ""
         @buf = left + (@buf[@cur..] || "")
         @cur = left.length
       when :space then insert(" ")
@@ -359,13 +351,11 @@ module Rakpak
     end
   end
 
-  # Where the archive goes: two ready-made folders and a field for any
-  # other. Typing anything moves to the field; 1, 2 and 3 pick directly.
   class WhereModal < Modal
     attr_reader :index
 
-    def initialize(here:, home:, index: 0, text: "", validate: nil)
-      super(title: "save it where?", footer: "1-3 or ↑↓ pick · enter choose · esc back")
+    def initialize(here:, home:, index: 0, text: "", validate: nil, title: "save it where?")
+      super(title: title, footer: "1-3 or ↑↓ pick · enter choose · esc back")
       @choices = [["This directory", here], ["Home directory", home], ["Specify", nil]]
       @index = index
       @field = InputModal.new(title: "", value: text, validate: validate)
@@ -417,8 +407,6 @@ module Rakpak
       nil
     end
 
-    # Once the field is active, j, k and digits are text like anything
-    # else; arrows and tab still move between the choices.
     def field_key(key)
       @index = 2
       @field.handle(key)
@@ -444,9 +432,71 @@ module Rakpak
     end
   end
 
-  # Read-only panel: the exact commands, warnings, and a go/no-go. Only
-  # enter runs it: a single letter is too easy to hit while meaning
-  # something else, and b in particular reads as "back".
+  # Result is the typed names, or :tag to go mark exclusions in the file view.
+  class ExcludeModal < Modal
+    def initialize(text:, marked:)
+      super(title: "exclude", footer: "↑↓ pick · enter continue · esc back")
+      @field = InputModal.new(title: "", value: text)
+      @marked = marked
+      @index = 0
+    end
+
+    def text = @field.text
+
+    def dims(screen)
+      [[[screen.w - 6, 84].min, 44].max, [9 + [@marked.size, 1].max, screen.h - 2].min]
+    end
+
+    def body(screen, x, y, w, h)
+      choice(screen, x, y, w, "1. Names", 0)
+      @field.field(screen, x + 12, y, w - 12, active: @index.zero?)
+      screen.put(x + 3, y + 1, Text.fit("commas between; each matches at any depth, with all it holds", w - 3),
+                 Theme::MODAL_BG + Theme::DIM)
+      choice(screen, x, y + 2, w, "2. Tag files and directories", 1)
+      if @marked.empty?
+        screen.put(x, y + 4, "nothing marked", Theme::MODAL_BG + Theme::FAINT)
+        return
+      end
+      screen.put(x, y + 4, "marked", Theme::MODAL_BG + Theme::TITLE)
+      rows = h - 5
+      return if rows < 1
+
+      shown = @marked.size > rows ? @marked.first(rows - 1) : @marked
+      shown.each_with_index do |m, i|
+        screen.put(x + 3, y + 5 + i, Text.fit_left(m, w - 3), Theme::MODAL_BG + Theme::NORMAL)
+      end
+      return if shown.size == @marked.size
+
+      screen.put(x + 3, y + 5 + shown.size, "… #{@marked.size - shown.size} more", Theme::MODAL_BG + Theme::FAINT)
+    end
+
+    def choice(screen, x, y, w, label, i)
+      sel = i == @index
+      bg = sel ? Theme::CUR_BG : Theme::MODAL_BG
+      screen.fill(x - 1, y, w + 2, 1, " ", bg)
+      screen.put(x, y, label, bg + (sel ? "\e[1;38;5;231m" : Theme::NORMAL))
+    end
+
+    def handle(key)
+      case key
+      when :esc then return :cancel
+      when :enter
+        @result = @index.zero? ? text : :tag
+        return :done
+      when :up, :down, :tab then @index = 1 - @index
+      else
+        # On row 2, j/k move; anything else is typing, so it lands in the field.
+        if @index == 1 && %w[j k].include?(key) then @index = 0
+        else
+          @index = 0
+          @field.handle(key)
+        end
+      end
+      nil
+    end
+  end
+
+  # Only enter runs it: a single letter (b reads as "back") is too easy to hit by mistake.
   class ConfirmModal < Modal
     def initialize(title:, lines:, warnings: [], errors: [], footer: nil)
       super(title: title,
@@ -462,8 +512,7 @@ module Rakpak
       [w, [h, screen.h - 2].min]
     end
 
-    # Commands are wrapped rather than clipped: the whole point of this
-    # panel is that you can read exactly what will run.
+    # Wrap, don't clip: the user must see exactly what will run.
     def laid_out(w)
       @lines.flat_map do |style, text|
         if style == :cmd
@@ -514,8 +563,6 @@ module Rakpak
     end
   end
 
-  # Transient notice panel. Scrolls when the content is taller than the
-  # terminal, which the key list usually is on a short screen.
   class MessageModal < Modal
     def initialize(title:, lines:, style: Theme::ERR)
       super(title: title, footer: "any key to dismiss")

data/lib/rakpak/plan.rb

@@ -1,21 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "formats"
+require_relative "text"
 
 module Rakpak
-  # Turns a set of tagged paths plus the wizard's answers into one concrete
-  # command. Nothing here shells out; commands are spawned without a shell,
-  # so spaces and quotes in filenames are never a hazard.
-  #
-  # Three shapes of output, one file each:
-  #   :both   tar, then compress            name.tar.gz, name.tar.zst, ...
-  #   :tar    plain tar, no compression     name.tar
-  #   :zip    compression only              name.zip, or name.txt.gz for one file
+  # :both tar then compress, :tar plain tar, :zip compress only (name.zip, or name.txt.gz for one file)
   class Plan
     TARGETS = %i[both tar zip].freeze
 
-    attr_reader :paths
-    attr_accessor :outdir, :basename, :target
+    attr_reader :paths, :excluded
+    attr_accessor :outdir, :basename, :target, :excludes
     attr_accessor :tar_codec, :tar_level, :tar_flags, :compressor, :comp_level, :zip_flags
 
     def initialize(paths:, outdir:, basename: "archive", target: :both)
@@ -23,7 +17,8 @@ module Rakpak
       @outdir = outdir
       @basename = basename
       @target = target
-      # gzip is the one every system can read; anything else is opt-in.
+      @excludes = []
+      @excluded = []
       @tar_codec = TAR_CODECS.find { |c| c.id == :gzip && c.available? } || tar_codec_fallback
       @tar_level = @tar_codec.default
       @tar_flags = Rakpak.tar_flags
@@ -32,12 +27,8 @@ module Rakpak
       @zip_flags = Rakpak.zip_flags
     end
 
-    # Drop anything already covered by another selection: tagging ~/docs and
-    # then ~/docs/notes would otherwise store notes twice, silently.
     def self.prune(paths)
-      # Sorting by path components puts every descendant right after its
-      # ancestor ("a/b" before "a-x"), so one pass with a stack of accepted
-      # ancestors is enough, however many paths there are.
+      # Sorting by components puts descendants right after their ancestor ("a/b" before "a-x").
       sorted = paths.map { |p| File.expand_path(p) }.uniq.sort_by { |p| p.split("/") }
       kept = []
       stack = []
@@ -55,15 +46,29 @@ module Rakpak
       path.start_with?(dir == "/" ? "/" : "#{dir}/")
     end
 
-    # "none" needs no tool so it is always available; it is the last
-    # resort, not the first pick, when gzip is missing.
+    def self.parse_excludes(text)
+      slash = "/".ord
+      text.split(",").map do |name|
+        name = name.strip
+        finish = name.bytesize
+        finish -= 1 while finish.positive? && name.getbyte(finish - 1) == slash
+        name.byteslice(0, finish)
+      end.reject(&:empty?).uniq
+    end
+
+    # Marked paths are exact, so glob characters in them must not match.
+    def self.literal(path) = path.gsub(/[\\*?\[\]]/) { |c| "\\#{c}" }
+
+    # Only marks strictly inside a packed folder count; a packed item itself is untagged instead.
+    def excluded=(list)
+      @excluded = list.map { |p| File.expand_path(p) }.uniq.sort
+                      .select { |x| @paths.any? { |p| Plan.inside?(x, p) } }
+    end
+
     def tar_codec_fallback
       TAR_CODECS.find { |c| c.bin && c.available? } || Rakpak.tar_codec(:none)
     end
 
-    # One format's knobs behind a uniform face, so the option form does not
-    # need to know whether it is editing tar or compressor settings. Picking
-    # a codec resets the level to that codec's default.
     class Side
       attr_reader :options, :flags
 
@@ -82,7 +87,7 @@ module Rakpak
         @plan.public_send("#{@level_attr}=", v)
       end
 
-      # [label, id, enabled, why] rows for the form's choice list.
+      # [label, id, enabled, why] rows.
       def choices = @plan.public_send(@choices)
 
       def codec=(id)
@@ -102,13 +107,10 @@ module Rakpak
                      flags: @zip_flags, choices: :compress_choices)
     end
 
-    # "both" means compressed, so "none" is not on offer there.
     def tar_choices
       TAR_CODECS.reject { |c| c.id == :none }.map { |c| [c.label, c.id, c.available?, c.why_not] }
     end
 
-    # Single-file compressors only make sense for exactly one file; zip can
-    # take anything.
     def compress_choices
       COMPRESSORS.map do |c|
         ok = c.available? && (c.container? || single_file?)
@@ -119,13 +121,8 @@ module Rakpak
 
     def single_file? = @paths.size == 1 && File.file?(@paths.first)
 
-    # True when the output is a bare compressed file (notes.txt.gz), where
-    # the original name should be kept whole.
     def single_compress? = @target == :zip && !@compressor.container?
 
-    # Deepest directory containing every tagged path. Members are stored
-    # relative to it, so the archive has a sane shape no matter how far
-    # apart the selections were.
     def base
       @base ||= begin
         dirs = @paths.map { |p| File.dirname(p) }
@@ -141,11 +138,11 @@ module Rakpak
       end
     end
 
-    def members
-      @paths.map do |p|
-        rel = p.delete_prefix(base == "/" ? "/" : "#{base}/")
-        rel.empty? ? File.basename(p) : rel
-      end
+    def members = @paths.map { |p| relative(p) }
+
+    def relative(path)
+      rel = path.delete_prefix(base == "/" ? "/" : "#{base}/")
+      rel.empty? ? File.basename(path) : rel
     end
 
     def ext
@@ -159,17 +156,41 @@ module Rakpak
     def output = File.join(@outdir, ensure_ext(@basename, ext))
     def outputs = [output]
 
-    # Extensions a user might type that we would otherwise double up.
+    def prepare; end
+    def commit; end
+    def rollback; end
+
+    def gerund = "archiving"
+
+    def outcome
+      outputs.map { |o| "#{File.basename(o)} #{Text.bytes(file_size(o))}" }.join(" · ")
+    end
+
+    def report_note = Text.bytes(file_size(output))
+
+    def file_size(path)
+      File.size(path)
+    rescue StandardError
+      nil
+    end
+
+    # Excluded files are inside the count, so a total would stall the bar; show the count alone.
+    def total_members(sizer)
+      return nil if @excludes.any? || @excluded.any?
+
+      files = sizer.total(@paths).files
+      files.positive? ? files : nil
+    end
+
+    def clobbers_output? = true
+
     ARCHIVE_EXTS = (TAR_CODECS.map(&:ext) + TAR_CODECS.map(&:single_ext) + %w[.tgz .tbz2 .txz .zip])
                    .reject(&:empty?).uniq.sort_by { |e| -e.length }.freeze
 
     def ensure_ext(name, ext)
       return name if name.downcase.end_with?(ext)
-      # backup.tar gzipped on its own is backup.tar.gz; the name is the
-      # point, so nothing is stripped from it.
       return "#{name}#{ext}" if single_compress?
 
-      # Strip a competing archive extension the user may have typed.
       typed = ARCHIVE_EXTS.find { |e| name.downcase.end_with?(e) }
       stripped = typed ? name[0...-typed.length] : name
       stripped = name if stripped.empty?
@@ -182,10 +203,36 @@ module Rakpak
         argv += ["--use-compress-program", filter]
       end
       @tar_flags.each { |f| argv.concat(f.args) if f.on }
+      argv += tar_exclude_args
       argv += ["-f", output, "-C", base, "--"]
       argv + members
     end
 
+    # Names match at any depth. Marks are anchored: GNU tar takes --anchored, bsdtar a leading ^,
+    # busybox has neither (warnings says so).
+    def tar_exclude_args
+      args = @excludes.map { |n| "--exclude=#{n}" }
+      marked = @excluded.map { |p| Plan.literal(relative(p)) }
+      return args if marked.empty?
+
+      case Tools.tar_flavor
+      when *GNU then args + ["--anchored"] + marked.map { |m| "--exclude=#{m}" }
+      when :bsd then args + marked.map { |m| "--exclude=^#{m}" }
+      else args + marked.map { |m| "--exclude=#{m}" }
+      end
+    end
+
+    # zip matches -x against whole member paths, so a name needs each depth spelled out.
+    def zip_exclude_args
+      names = @excludes.map { |n| zipsafe(n) }.flat_map { |n| [n, "#{n}/*", "*/#{n}", "*/#{n}/*"] }
+      marks = @excluded.map { |p| zipsafe(Plan.literal(relative(p))) }.flat_map { |m| [m, "#{m}/*"] }
+      pats = names + marks
+      pats.empty? ? [] : ["-x", *pats]
+    end
+
+    # zip would read a leading dash as an option; [-] matches the same name.
+    def zipsafe(pat) = pat.start_with?("-") ? "[-]#{pat[1..]}" : pat
+
     def zip_argv
       argv = ["zip", "-r"]
       argv << (zip_verbose? ? "-v" : "-q")
@@ -198,11 +245,9 @@ module Rakpak
         argv.concat(f.args) if f.on
       end
       argv << output
-      argv + members.map { |m| dashsafe(m) }
+      argv + members.map { |m| dashsafe(m) } + zip_exclude_args
     end
 
-    # gzip and friends read one file and write to stdout; the job redirects
-    # that into the output path.
     def single_argv
       @compressor.argv(@comp_level) + [dashsafe(members.first)]
     end
@@ -230,8 +275,7 @@ module Rakpak
       end
     end
 
-    # Display form of the command. Execution never goes through a shell, so
-    # this is for the reader's benefit; quote only what needs it.
+    # Display only; execution never goes through a shell.
     def self.show_arg(arg)
       arg.match?(%r{\A[\w@%+=:,./-]+\z}) ? arg : "'#{arg.gsub("'", %q('"'"'))}'"
     end
@@ -245,7 +289,6 @@ module Rakpak
       steps.map { |(label, argv, _, stdout)| [label, Plan.show_cmd(argv, stdout)] }
     end
 
-    # Problems worth blocking on, checked right before the run.
     def problems
       errs = []
       errs << "nothing selected" if @paths.empty?
@@ -267,7 +310,6 @@ module Rakpak
       errs.compact.uniq
     end
 
-    # Non-blocking things the confirm screen should say out loud.
     def warnings
       warn = []
       o = output
@@ -275,6 +317,14 @@ module Rakpak
       if @paths.any? { |p| Plan.inside?(o, p) }
         warn << "output sits inside a selected folder, so it may archive itself"
       end
+      @paths.each do |p|
+        name = File.basename(p)
+        hit = @excludes.find { |pat| File.fnmatch?(pat, name, File::FNM_DOTMATCH) }
+        warn << "#{name} matches #{hit}, so it is left out entirely" if hit
+      end
+      if @excluded.any? && @target != :zip && Tools.tar_flavor == :busybox
+        warn << "busybox tar cannot pin a mark to one spot; same-named paths deeper in go too"
+      end
       warn
     end
   end

data/lib/rakpak/screen.rb

@@ -4,8 +4,6 @@ require_relative "text"
 require_relative "theme"
 
 module Rakpak
-  # A character grid. Everything draws into cells, so modals overlay the
-  # browser cleanly and the whole frame ships in one write.
   class Screen
     attr_reader :w, :h
 
@@ -25,7 +23,6 @@ module Rakpak
       @st.fill(style)
     end
 
-    # Writes `text` at (x, y). Returns the column just past the text.
     def put(x, y, text, style = nil)
       return x if y.negative? || y >= @h
 
@@ -50,17 +47,14 @@ module Rakpak
       cx
     end
 
-    # A double-width glyph owns two cells: itself and an empty marker after
-    # it. Writing over either half must blank the other, or the row renders
-    # one column too wide and the terminal wraps it.
+    # A wide glyph owns two cells; overwriting either half must blank the other or the row wraps.
     def clear_halves(idx)
       col = idx % @w
       @ch[idx - 1] = " " if @ch[idx] == "" && col.positive? && Text.gw(@ch[idx - 1]) == 2
       @ch[idx + 1] = " " if col < @w - 1 && @ch[idx + 1] == "" && Text.gw(@ch[idx]) == 2
     end
 
-    # Last line of defence: a single binary byte reaching @ch would make the
-    # whole frame fail to concatenate and take the app down mid-render.
+    # One binary byte in @ch would break frame concatenation mid-render.
     def printable(text)
       str = text.to_s
       str = str.dup.force_encoding(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
@@ -104,8 +98,6 @@ module Rakpak
       end
     end
 
-    # Flatten everything to a faint monochrome so a modal reads as the
-    # foreground layer.
     def veil(style = Theme::FAINT)
       @st.fill(style)
     end

data/lib/rakpak/sizer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # Walks tagged directories on a worker thread so the UI can show a real
-  # byte total and file count without ever blocking on a huge tree.
   class Sizer
     Result = Struct.new(:bytes, :files, :partial)
 
-    BUDGET = 4.0 # seconds per path before we report a partial figure
+    BUDGET = 4.0 # seconds per path before reporting a partial figure
 
     def initialize
       @cache = {}
@@ -40,7 +38,6 @@ module Rakpak
       Result.new(bytes, files, known.any?(&:nil?) || known.compact.any?(&:partial))
     end
 
-    # Drops the figure, and any measurement in flight for it.
     def forget(path)
       @lock.synchronize do
         @cache.delete(path)
@@ -60,8 +57,7 @@ module Rakpak
     def work(path, token)
       res = measure(path)
       @lock.synchronize do
-        # Forgotten, invalidated, or re-requested while we were walking:
-        # only the walk that the current request started may answer it.
+        # Only the walk the current request started may answer it.
         next unless @pending[path].equal?(token)
 
         @pending.delete(path)

data/lib/rakpak/term.rb

@@ -3,7 +3,6 @@
 require "io/console"
 
 module Rakpak
-  # Raw-mode terminal control and key decoding.
   module Term
     ARROWS = { "A" => :up, "B" => :down, "C" => :right, "D" => :left,
                "H" => :home, "F" => :end }.freeze
@@ -52,8 +51,7 @@ module Rakpak
       $stdout.flush
     end
 
-    # Blocks up to `timeout` seconds. Returns a key symbol, a printable
-    # String, or nil on timeout.
+    # Returns a key symbol, a printable String, or nil on timeout.
     def wait_key(timeout = nil)
       return nil unless IO.select([$stdin], nil, nil, timeout)
 
@@ -78,10 +76,7 @@ module Rakpak
       end
     end
 
-    # Under a C locale getc yields one byte at a time, and under UTF-8 a
-    # stray byte arrives as a one-byte invalid string. Gather the rest of
-    # the sequence when there is one; if the result is still not valid
-    # text, the key is dropped rather than raised on later.
+    # C locale getc yields single bytes; gather the sequence and drop it if still invalid.
     def complete_utf8(c)
       s = c.dup.force_encoding(Encoding::UTF_8)
       return s if s.valid_encoding?
@@ -109,9 +104,7 @@ module Rakpak
       nil
     end
 
-    # An arrow key arrives as several bytes. Over a slow link they can be
-    # split across reads, so allow a generous window before concluding the
-    # user pressed a bare Esc. The delay is only ever paid on a real Esc.
+    # Escape sequences can split across reads on slow links; only a real Esc pays this wait.
     ESC_WINDOW = 0.05
 
     def read_escape
@@ -139,7 +132,6 @@ module Rakpak
           :esc
         end
       else
-        # Alt-<char>: the whole sequence is the character.
         :"alt_#{seq}"
       end
     end

data/lib/rakpak/text.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # Grapheme-aware width math. Just enough Unicode to keep columns honest.
   module Text
     WIDE = [
       0x1100..0x115F, 0x2E80..0x303E, 0x3041..0x33FF, 0x3400..0x4DBF,
@@ -14,12 +13,10 @@ module Rakpak
 
     module_function
 
-    # Display width of a single grapheme cluster.
     def gw(cluster)
       cp = cluster.ord
-      return 1 if cp >= 0x20 && cp < 0x7F # the common case, checked first
-      # C0, DEL and the C1 controls: a UTF-8 terminal executes U+009B as
-      # CSI, so these must never reach the frame.
+      return 1 if cp >= 0x20 && cp < 0x7F
+      # C0, DEL and C1: a UTF-8 terminal executes U+009B as CSI.
       return 0 if cp < 0x20 || cp == 0x7F || (cp >= 0x80 && cp <= 0x9F)
       return 0 if ZERO.any? { |r| r.cover?(cp) }
       return 2 if WIDE.any? { |r| r.cover?(cp) }
@@ -35,7 +32,6 @@ module Rakpak
       w
     end
 
-    # Truncate to `max` columns, appending an ellipsis when something was cut.
     def fit(str, max)
       return "" if max <= 0
       return str if width(str) <= max
@@ -52,7 +48,6 @@ module Rakpak
       out << "…"
     end
 
-    # Keep the tail of a path visible instead of the head.
     def fit_left(str, max)
       return "" if max <= 0
       return str if width(str) <= max
@@ -75,7 +70,6 @@ module Rakpak
       w >= max ? str : str + (" " * (max - w))
     end
 
-    # Greedy wrap on spaces, with a hanging indent for continuations.
     def wrap(str, max, indent = 0)
       return [str] if max <= indent + 4 || width(str) <= max
 
@@ -84,7 +78,6 @@ module Rakpak
       out = []
       line = +""
       words = str[lead.length..].to_s.split(" ").flat_map do |word|
-        # A path with no spaces can still be wider than the panel; break it.
         limit = max - indent
         next word if width(word) <= limit || limit < 8
 
@@ -103,7 +96,6 @@ module Rakpak
       out
     end
 
-    # /home/me/x → ~/x. Only a real prefix counts: /home/me2 is left alone.
     def tilde(path)
       home = Dir.home
       return path if home.nil? || home.empty? || home == "/"
@@ -112,8 +104,7 @@ module Rakpak
       path.start_with?("#{home}/") ? "~#{path[home.length..]}" : path
     end
 
-    # For text that goes to the terminal without passing through Screen:
-    # control and C1 bytes could otherwise be executed as escape sequences.
+    # Control and C1 bytes could be executed as escape sequences.
     def plain(str)
       str.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?").gsub(/[\u0000-\u001f\u007f-\u009f]/, "?")
     end

data/lib/rakpak/theme.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # SGR fragments. Every style is emitted after a reset, so they compose by
-  # concatenation without needing to be self-contained.
+  # Every style is emitted after a reset, so fragments needn't be self-contained.
   module Theme
     RESET     = "\e[0m"