clack 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fbbb7aa9fa9b375b70b10c7a7c17124f1187d2fe1443a9cad6358087570e876
-  data.tar.gz: 006b53ead379e5b550e5da0735a8085224c1531937db9de750128d9f25ced3a8
+  metadata.gz: 01366d1d6cc81f2514adc5c7bbdc726b3dec22d6697ae2bf26077c2db84efa1b
+  data.tar.gz: e1e96b35ef913ee377ed38c0fd98612aa1d758760991ee39ba27ac1cf8dc6136
 SHA512:
-  metadata.gz: 49dfca31d9b51ea57e5e68c74fe48fa217e5cba22c9db94529eae50f39edbb2488021559285641e943f9e1445964fc7ca02a7b59a026ae36da630cb1cc4e3576
-  data.tar.gz: d0e77aaaa330de1b4bace456d082ae7b93b024c293c51db4a4d4647cef3ed4939145ea89e52817c4e6220225860bdfde95e527e96281da6a5cce8e49c4ee90d4
+  metadata.gz: ac79a1a3887e261b9d2f14b989381430c35796a1acac47a449e44c773314bcea8985b294880a646213c53bd004900e9e749f9a0d69db55a19dfecd2b4d6eab34
+  data.tar.gz: 891cea3cc9b0047602a627396c40950c4397a968aa2ca021b4e2f71719ce40463d62b01db19c3b59ea92fd9efd9e0807b9120afa6cfacbbe5df90fcb391d328a

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.6.1] - 2026-06-21
+
+### Added
+- `CLACK_ESCAPE_TIMEOUT` env var to tune the Escape-sequence detection window (milliseconds) for high-latency links like slow SSH, where arrow keys could otherwise be misread as a standalone Escape
+
+### Changed
+- `multiselect`, `group_multiselect`, and `autocomplete_multiselect` now warn on stderr when `initial_values` contains values that don't match any option (still dropped, but no longer silently)
+
+## [0.6.0] - 2026-05-30
+
+### Added
+- `Option`, `SelectKeyOption`, `GroupHeader`, and `GroupOption` value objects for normalized prompt options
+- Hash-style `[]` access on option value objects for compatibility with existing custom autocomplete filters
+- Display-width coverage for CJK, fullwidth forms, Hangul, emoji, ZWJ emoji sequences, flag emoji, combining marks, and ANSI-colored text
+
+### Changed
+- Option-based prompts now normalize strings, symbols, and hashes into typed value objects instead of bare hashes
+- Autocomplete and multiselect filtering now operate on normalized option objects while preserving `opt[:key]` access patterns
+- Text wrapping, truncation, box titles, and note layout now measure terminal display columns instead of Ruby string length
+- Progress rendering skips duplicate intermediate frames during rapid updates
+
+### Fixed
+- CJK, emoji, combining characters, and ANSI sequences no longer throw off prompt alignment, wrapping, truncation, note padding, or box title width
+- `Tasks#run` restores cursor visibility even when task execution raises
+- `SelectKey` option normalization resolves the value object through the correct namespace
+
 ## [0.5.0] - 2026-03-27
 
 ### Breaking

data/README.md

@@ -7,6 +7,9 @@
   <i>CLI prompts for Ruby. Zero dependencies.</i>
   <br>
   <br>
+  <sub>A faithful Ruby port of <a href="https://github.com/bombshell-dev/clack"><code>@clack/prompts</code></a>.</sub>
+  <br>
+  <br>
   <a href="https://rubygems.org/gems/clack"><img src="https://img.shields.io/gem/v/clack?style=flat-square&color=cc342d" alt="Gem Version"></a>
   <a href="https://github.com/swhitt/clackrb/actions"><img src="https://img.shields.io/github/actions/workflow/status/swhitt/clackrb/ci.yml?style=flat-square&label=tests" alt="Tests"></a>
   <a href="https://www.ruby-lang.org"><img src="https://img.shields.io/badge/ruby-3.2%2B-cc342d?style=flat-square" alt="Ruby 3.2+"></a>
@@ -238,7 +241,8 @@ color = Clack.autocomplete(
   max_items: 5  # Default; scrollable via up/down arrows
 )
 
-# Custom filter logic (receives option hash and query string)
+# Custom filter logic (receives the option and query string).
+# The option is a value object; opt.label and opt[:label] both work.
 cmd = Clack.autocomplete(
   message: "Select command",
   options: commands,
@@ -781,7 +785,7 @@ COVERAGE=true bundle exec rake spec  # With coverage
 
 ## Credits
 
-This is a Ruby port of [Clack](https://github.com/bombshell-dev/clack), created by [Nate Moore](https://github.com/natemoo-re) and the [Astro](https://astro.build) team.
+This is a Ruby port of [`@clack/prompts`](https://github.com/bombshell-dev/clack), created by [Nate Moore](https://github.com/natemoo-re) and the [Astro](https://astro.build) team.
 
 ## License
 

data/lib/clack/box.rb

@@ -39,10 +39,10 @@ module Clack
         format_border ||= ->(text) { Colors.gray(text) }
         symbols = corner_symbols(rounded).map(&format_border)
         lines = message.to_s.lines.map(&:chomp)
-        box_width = calculate_width(lines, title.length, title_padding, content_padding, width)
+        box_width = calculate_width(lines, Clack::Utils.visible_length(title), title_padding, content_padding, width)
         inner_width = box_width - 2
         max_title_len = inner_width - (title_padding * 2)
-        display_title = (title.length > max_title_len) ? "#{title[0, max_title_len - 3]}..." : title
+        display_title = Clack::Utils.truncate(title, max_title_len)
 
         {
           symbols: symbols,
@@ -56,7 +56,7 @@ module Clack
 
       def render_content_lines(output, ctx, content_align, content_padding)
         ctx[:lines].each do |line|
-          left_pad, right_pad = padding_for_line(line.length, ctx[:inner_width], content_padding, content_align)
+          left_pad, right_pad = padding_for_line(Clack::Utils.visible_length(line), ctx[:inner_width], content_padding, content_align)
           output.puts "#{ctx[:v_symbol]}#{" " * left_pad}#{line}#{" " * right_pad}#{ctx[:v_symbol]}"
         end
       end
@@ -82,8 +82,8 @@ module Clack
       def calculate_width(lines, title_len, title_padding, content_padding, width)
         return width + 2 if width.is_a?(Integer) # Add 2 for borders
 
-        # Auto width: fit to content
-        max_line = lines.map(&:length).max || 0
+        # Auto width: fit to content using display width
+        max_line = lines.map { |l| Clack::Utils.visible_length(l) }.max || 0
         title_with_padding = title_len + (title_padding * 2)
         content_with_padding = max_line + (content_padding * 2)
 
@@ -94,7 +94,7 @@ module Clack
         if title.empty?
           "#{symbols[0]}#{h_symbol * inner_width}#{symbols[1]}"
         else
-          left_pad, right_pad = padding_for_line(title.length, inner_width, title_padding, title_align)
+          left_pad, right_pad = padding_for_line(Clack::Utils.visible_length(title), inner_width, title_padding, title_align)
           "#{symbols[0]}#{h_symbol * left_pad}#{title}#{h_symbol * right_pad}#{symbols[1]}"
         end
       end

data/lib/clack/core/fuzzy_matcher.rb

@@ -109,10 +109,10 @@ module Clack
 
         def best_score(opt, query, q_down)
           scores = [
-            score(query, opt[:label], q_down: q_down),
-            score(query, opt[:value].to_s, q_down: q_down)
+            score(query, opt.label, q_down: q_down),
+            score(query, opt.value.to_s, q_down: q_down)
           ]
-          scores << score(query, opt[:hint], q_down: q_down) if opt[:hint]
+          scores << score(query, opt.hint, q_down: q_down) if opt.hint
           scores.max
         end
       end

data/lib/clack/core/key_reader.rb

@@ -6,15 +6,10 @@ module Clack
   module Core
     # Reads single keystrokes from the terminal in raw mode.
     # Handles escape sequences for arrow keys and other special keys.
+    #
+    # The Escape detection window is tunable via the +CLACK_ESCAPE_TIMEOUT+
+    # env var (see {Environment.escape_timeout}) for high-latency links.
     module KeyReader
-      # Timeout for detecting if Escape is part of a sequence (50ms).
-      # If no follow-up character arrives, treat Escape as a standalone key.
-      ESCAPE_TIMEOUT = 0.05
-
-      # Timeout for reading additional characters in a CSI sequence (10ms).
-      # Short because subsequent bytes in a sequence arrive almost instantly.
-      SEQUENCE_TIMEOUT = 0.01
-
       class << self
         # Read a single keystroke in raw mode.
         # When input is an IO backed by a console, uses raw mode.
@@ -42,14 +37,20 @@ module Clack
           return char if char.nil? # EOF
           return char unless char == "\e"
 
+          escape_timeout = Environment.escape_timeout
+          # Subsequent bytes in a sequence normally arrive almost instantly, so
+          # the inter-byte wait stays much shorter, but it scales with the
+          # escape timeout so high-latency links still assemble full sequences.
+          sequence_timeout = escape_timeout / 5.0
+
           # Check for escape sequence - wait briefly for follow-up
-          return char unless io.respond_to?(:wait_readable) && io.wait_readable(ESCAPE_TIMEOUT)
+          return char unless io.respond_to?(:wait_readable) && io.wait_readable(escape_timeout)
 
           seq = io.getc.to_s
           return "\e#{seq}" unless seq == "["
 
           # Read CSI sequence until no more characters arrive
-          while io.respond_to?(:wait_readable) && io.wait_readable(SEQUENCE_TIMEOUT)
+          while io.respond_to?(:wait_readable) && io.wait_readable(sequence_timeout)
             seq += io.getc.to_s
           end
           "\e[#{seq[1..]}"

data/lib/clack/core/options_helper.rb

@@ -2,6 +2,31 @@
 
 module Clack
   module Core
+    # Value object for normalized select-style options.
+    Option = Data.define(:value, :label, :hint, :disabled) do
+      def to_s = label.to_s
+
+      # Hash-style read access for backward compatibility with code (e.g.
+      # custom autocomplete filters) written against the old option hashes.
+      def [](key) = to_h[key]
+    end
+
+    # Value object for select_key options (includes :key).
+    SelectKeyOption = Data.define(:value, :label, :key, :hint) do
+      def to_s = label.to_s
+      def [](key) = to_h[key]
+    end
+
+    # Value objects for group_multiselect flat list (replaces :type discriminator hashes).
+    # GroupOption carries extra fields only used within GroupMultiselect for layout.
+    GroupHeader = Data.define(:label, :options) do
+      def [](key) = to_h[key]
+    end
+    GroupOption = Data.define(:value, :label, :hint, :disabled, :group, :last_in_group) do
+      def to_s = label.to_s
+      def [](key) = to_h[key]
+    end
+
     # Shared functionality for option-based prompts (Select, Multiselect, Autocomplete, etc.).
     # Handles option normalization, cursor navigation, and scrolling.
     #
@@ -25,20 +50,20 @@ module Clack
         options.map { |opt| OptionsHelper.normalize_option(opt) }
       end
 
-      # Normalize a single option to a consistent hash format.
+      # Normalize a single option to an Option value object.
       # @param opt [Hash, String, Symbol] Raw option
-      # @return [Hash] Normalized option hash
+      # @return [Option] Normalized option
       def self.normalize_option(opt)
         case opt
         when Hash
-          {
+          Option.new(
             value: opt[:value],
             label: opt[:label] || opt[:value].to_s,
             hint: opt[:hint],
             disabled: opt[:disabled] || false
-          }
+          )
         else
-          {value: opt, label: opt.to_s, hint: nil, disabled: false}
+          Option.new(value: opt, label: opt.to_s, hint: nil, disabled: false)
         end
       end
 
@@ -54,7 +79,7 @@ module Clack
         idx = (from + delta) % max
 
         max.times do
-          return idx unless items[idx][:disabled]
+          return idx unless items[idx].disabled
 
           idx = (idx + delta) % max
         end
@@ -120,11 +145,11 @@ module Clack
 
         if initial_value.nil?
           # Start at first enabled option
-          return items[0][:disabled] ? first_enabled_index : 0
+          return items[0].disabled ? first_enabled_index : 0
         end
 
-        idx = items.find_index { |o| o[:value] == initial_value }
-        (idx && !items[idx][:disabled]) ? idx : first_enabled_index
+        idx = items.find_index { |o| o.value == initial_value }
+        (idx && !items[idx].disabled) ? idx : first_enabled_index
       end
 
       # The list of items to navigate. Override in subclasses that use

data/lib/clack/core/selection_manager.rb

@@ -11,6 +11,24 @@ module Clack
     module SelectionManager
       REQUIRED_ERROR = "Please select at least one option. Press %s to select, %s to submit"
 
+      # Resolve requested pre-selections against the selectable option values.
+      #
+      # Values that don't match any current option are dropped and reported on
+      # stderr, since they're almost always a typo in +initial_values+ rather
+      # than an intentional no-op.
+      #
+      # @param initial_values [Array] the requested pre-selections
+      # @param valid_values [Set] the set of selectable option values
+      # @return [Set] the subset of initial_values that map to real options
+      def resolve_initial_selection(initial_values, valid_values)
+        requested = Set.new(initial_values)
+        unknown = requested - valid_values
+        unless unknown.empty?
+          warn "[clack] ignoring unknown initial_values: #{unknown.to_a.inspect}"
+        end
+        requested & valid_values
+      end
+
       # Toggle a value in the selection set.
       # @param value [Object] the value to toggle
       def toggle_value(value)
@@ -42,7 +60,7 @@ module Clack
       # @param all_options [Array<Hash>] the full options list to match against
       # @return [String] comma-separated labels
       def selected_labels(all_options)
-        all_options.select { |o| @selected.include?(o[:value]) }.map { |o| o[:label] }.join(", ")
+        all_options.select { |o| @selected.include?(o.value) }.map { |o| o.label }.join(", ")
       end
     end
   end

data/lib/clack/environment.rb

@@ -6,6 +6,9 @@ module Clack
   # Environment detection utilities for cross-platform compatibility
   # and CI/terminal environment awareness.
   module Environment
+    # Default Escape-sequence detection timeout, in seconds.
+    DEFAULT_ESCAPE_TIMEOUT = 0.05
+
     class << self
       # Check if running on Windows
       # @return [Boolean]
@@ -127,6 +130,29 @@ module Clack
         end
       end
 
+      # Escape-sequence detection timeout, in seconds.
+      #
+      # After an Escape byte arrives, the key reader waits this long for a
+      # follow-up byte to decide whether it's a standalone Escape or the start
+      # of an arrow-key / CSI sequence. The 50ms default is fine locally but too
+      # tight over high-latency links (slow SSH, mosh), where the follow-up
+      # bytes lag and arrow keys get misread as a bare Escape (cancelling the
+      # prompt). Override with the +CLACK_ESCAPE_TIMEOUT+ env var, in
+      # milliseconds, e.g. +CLACK_ESCAPE_TIMEOUT=250+ for a slow connection.
+      #
+      # Invalid or non-positive values fall back to the default.
+      #
+      # @return [Float] timeout in seconds
+      def escape_timeout
+        raw = ENV["CLACK_ESCAPE_TIMEOUT"]
+        return DEFAULT_ESCAPE_TIMEOUT unless raw
+
+        ms = Float(raw, exception: false)
+        return DEFAULT_ESCAPE_TIMEOUT unless ms&.positive?
+
+        ms / 1000.0
+      end
+
       # Reset cached environment checks (useful for testing)
       def reset!
         remove_instance_variable(:@windows) if defined?(@windows)

data/lib/clack/note.rb

@@ -14,14 +14,15 @@ module Clack
         lines = message.to_s.lines.map(&:chomp)
         # Add empty lines at start and end like original
         lines = ["", *lines, ""]
-        title_len = title&.length || 0
+        title_len = Clack::Utils.visible_length(title)
         width = calculate_width(lines, title_len)
 
         output.puts Colors.gray(Symbols::S_BAR)
         output.puts build_top_border(title, title_len, width)
 
         lines.each do |line|
-          padded = line.ljust(width)
+          pad = width - Clack::Utils.visible_length(line)
+          padded = pad.positive? ? line + (" " * pad) : line
           output.puts "#{Colors.gray(Symbols::S_BAR)}  #{Colors.dim(padded)}#{Colors.gray(Symbols::S_BAR)}"
         end
 
@@ -31,7 +32,7 @@ module Clack
       private
 
       def calculate_width(lines, title_len)
-        max_line = lines.map(&:length).max || 0
+        max_line = lines.map { |line| Clack::Utils.visible_length(line) }.max || 0
         [max_line, title_len].max + 2
       end
 

data/lib/clack/prompts/autocomplete.rb

@@ -29,7 +29,7 @@ module Clack
     #   Clack.autocomplete(
     #     message: "Select command",
     #     options: commands,
-    #     filter: ->(opt, query) { opt[:label].start_with?(query) }
+    #     filter: ->(opt, query) { opt.label.start_with?(query) }
     #   )
     #
     class Autocomplete < Core::Prompt
@@ -102,7 +102,7 @@ module Clack
           return
         end
 
-        @value = @filtered[@option_index][:value]
+        @value = @filtered[@option_index].value
         submit
       end
 
@@ -127,7 +127,7 @@ module Clack
         lines.join
       end
 
-      def final_display = @filtered[@option_index]&.[](:label) || @value
+      def final_display = @filtered[@option_index]&.label || @value
 
       private
 
@@ -142,11 +142,11 @@ module Clack
       def navigable_items = @filtered
 
       def option_display(opt, active)
-        hint = (opt[:hint] && active) ? Colors.dim(" (#{opt[:hint]})") : ""
+        hint = (opt.hint && active) ? Colors.dim(" (#{opt.hint})") : ""
         if active
-          "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{opt[:label]}#{hint}"
+          "#{Colors.green(Symbols::S_RADIO_ACTIVE)} #{opt.label}#{hint}"
         else
-          "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(opt[:label])}"
+          "#{Colors.dim(Symbols::S_RADIO_INACTIVE)} #{Colors.dim(opt.label)}"
         end
       end
     end

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -55,8 +55,8 @@ module Clack
         @cursor = 0
         @option_index = 0
         @scroll_offset = 0
-        valid_values = Set.new(@all_options.map { |o| o[:value] })
-        @selected = Set.new(initial_values) & valid_values
+        valid_values = Set.new(@all_options.map { |o| o.value })
+        @selected = resolve_initial_selection(initial_values, valid_values)
         update_filtered
       end
 
@@ -88,9 +88,9 @@ module Clack
         return if @filtered.empty?
 
         opt = @filtered[@option_index]
-        return if opt[:disabled]
+        return if opt.disabled
 
-        toggle_value(opt[:value])
+        toggle_value(opt.value)
       end
 
       def submit
@@ -169,15 +169,15 @@ module Clack
       def navigable_items = @filtered
 
       def option_display(opt, active)
-        selected = @selected.include?(opt[:value])
+        selected = @selected.include?(opt.value)
         checkbox = if selected
           Colors.green(Symbols::S_CHECKBOX_SELECTED)
         else
           Colors.dim(Symbols::S_CHECKBOX_INACTIVE)
         end
 
-        label = active ? opt[:label] : Colors.dim(opt[:label])
-        hint = (opt[:hint] && active) ? Colors.dim(" (#{opt[:hint]})") : ""
+        label = active ? opt.label : Colors.dim(opt.label)
+        hint = (opt.hint && active) ? Colors.dim(" (#{opt.hint})") : ""
 
         "#{checkbox} #{label}#{hint}"
       end

data/lib/clack/prompts/group_multiselect.rb

@@ -60,8 +60,8 @@ module Clack
         super(message:, **opts)
         @groups = normalize_groups(options)
         @flat_items = build_flat_items
-        valid_values = Set.new(@flat_items.select { |item| item[:type] == :option }.map { |item| item[:value] })
-        @selected = Set.new(initial_values) & valid_values
+        valid_values = Set.new(@flat_items.select { |item| item.is_a?(Core::GroupOption) }.map(&:value))
+        @selected = resolve_initial_selection(initial_values, valid_values)
         @required = required
         @selectable_groups = selectable_groups
         @group_spacing = group_spacing
@@ -93,8 +93,8 @@ module Clack
 
         prev_was_group = false
         @flat_items.each_with_index do |item, idx|
-          is_group = item[:type] == :group
-          is_last_in_group = item[:last_in_group]
+          is_group = item.is_a?(Core::GroupHeader)
+          is_last_in_group = item.is_a?(Core::GroupOption) ? item.last_in_group : false
 
           # Add group spacing before groups (except first)
           if is_group && !prev_was_group && idx.positive? && @group_spacing.positive?
@@ -117,7 +117,7 @@ module Clack
         lines.join
       end
 
-      def final_display = selected_options.map { |o| o[:label] }.join(", ")
+      def final_display = selected_options.map(&:label).join(", ")
 
       private
 
@@ -137,30 +137,29 @@ module Clack
       def build_flat_items = @groups.flat_map { |group| flatten_group(group) }
 
       def flatten_group(group)
-        group_item = {type: :group, label: group[:label], options: group[:options]}
+        group_item = Core::GroupHeader.new(label: group[:label], options: group[:options])
         option_items = group[:options].each_with_index.map do |opt, idx|
-          {
-            type: :option,
-            value: opt[:value],
-            label: opt[:label],
-            hint: opt[:hint],
-            disabled: opt[:disabled],
+          Core::GroupOption.new(
+            value: opt.value,
+            label: opt.label,
+            hint: opt.hint,
+            disabled: opt.disabled,
             group: group,
             last_in_group: idx == group[:options].length - 1
-          }
+          )
         end
         [group_item, *option_items]
       end
 
       def selected_options
-        @flat_items.select { |item| item[:type] == :option && @selected.include?(item[:value]) }
+        @flat_items.select { |item| item.is_a?(Core::GroupOption) && @selected.include?(item.value) }
       end
 
       def find_initial_cursor(cursor_at)
         return 0 if @flat_items.empty?
 
         if cursor_at
-          idx = @flat_items.find_index { |item| item[:value] == cursor_at }
+          idx = @flat_items.find_index { |item| item.respond_to?(:value) && item.value == cursor_at }
           return idx if idx
         end
 
@@ -168,8 +167,8 @@ module Clack
       end
 
       def can_select?(item)
-        return false if item[:disabled]
-        return @selectable_groups if item[:type] == :group
+        return false if item.is_a?(Core::GroupOption) && item.disabled
+        return @selectable_groups if item.is_a?(Core::GroupHeader)
 
         true
       end
@@ -191,7 +190,7 @@ module Clack
         item = @flat_items[@option_index]
         return unless can_select?(item)
 
-        if item[:type] == :group
+        if item.is_a?(Core::GroupHeader)
           toggle_group(item)
         else
           toggle_option(item)
@@ -200,7 +199,7 @@ module Clack
       end
 
       def toggle_group(group_item)
-        group_values = group_item[:options].reject { |o| o[:disabled] }.map { |o| o[:value] }
+        group_values = group_item.options.reject { |o| o.disabled }.map(&:value)
         all_selected = group_values.all? { |v| @selected.include?(v) }
 
         if all_selected
@@ -211,41 +210,41 @@ module Clack
       end
 
       def toggle_option(item)
-        toggle_value(item[:value])
+        toggle_value(item.value)
       end
 
       def update_value = update_selection_value
 
       def group_display(item, active)
         if @selectable_groups
-          all_selected = item[:options].reject { |o| o[:disabled] }.all? { |o| @selected.include?(o[:value]) }
+          all_selected = item.options.reject { |o| o.disabled }.all? { |o| @selected.include?(o.value) }
           checkbox = all_selected ? Colors.green(Symbols::S_CHECKBOX_SELECTED) : Colors.dim(Symbols::S_CHECKBOX_INACTIVE)
-          label = active ? item[:label] : Colors.dim(item[:label])
+          label = active ? item.label : Colors.dim(item.label)
           "#{active_bar}  #{checkbox} #{label}\n"
         else
-          "#{active_bar}  #{Colors.dim(item[:label])}\n"
+          "#{active_bar}  #{Colors.dim(item.label)}\n"
         end
       end
 
       def option_display(item, active, is_last)
-        selected = @selected.include?(item[:value])
+        selected = @selected.include?(item.value)
         prefix = if @selectable_groups
           "#{is_last ? Symbols::S_BAR_END : Symbols::S_BAR} "
         else
           "  "
         end
-        hint = (item[:hint] && active) ? " #{Colors.dim("(#{item[:hint]})")}" : ""
+        hint = (item.hint && active) ? " #{Colors.dim("(#{item.hint})")}" : ""
 
-        if item[:disabled]
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.strikethrough(Colors.dim(item[:label]))}\n"
+        if item.disabled
+          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.strikethrough(Colors.dim(item.label))}\n"
         elsif active && selected
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{item[:label]}#{hint}\n"
+          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{item.label}#{hint}\n"
         elsif active
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.cyan(Symbols::S_CHECKBOX_ACTIVE)} #{item[:label]}#{hint}\n"
+          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.cyan(Symbols::S_CHECKBOX_ACTIVE)} #{item.label}#{hint}\n"
         elsif selected
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{Colors.dim(item[:label])}\n"
+          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.green(Symbols::S_CHECKBOX_SELECTED)} #{Colors.dim(item.label)}\n"
         else
-          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.dim(item[:label])}\n"
+          "#{active_bar}  #{Colors.dim(prefix)}#{Colors.dim(Symbols::S_CHECKBOX_INACTIVE)} #{Colors.dim(item.label)}\n"
         end
       end
     end

data/lib/clack/prompts/multiselect.rb

@@ -44,8 +44,8 @@ module Clack
         end
         super(message:, **opts)
         @options = normalize_options(options)
-        valid_values = Set.new(@options.map { |o| o[:value] })
-        @selected = Set.new(initial_values) & valid_values
+        valid_values = Set.new(@options.map { |o| o.value })
+        @selected = resolve_initial_selection(initial_values, valid_values)
         @required = required
         @max_items = max_items
         @scroll_offset = 0
@@ -110,14 +110,14 @@ module Clack
 
       def toggle_current
         opt = @options[@option_index]
-        return if opt[:disabled]
+        return if opt.disabled
 
-        toggle_value(opt[:value])
+        toggle_value(opt.value)
         update_selection_value
       end
 
       def toggle_all
-        enabled = @options.reject { |o| o[:disabled] }.map { |o| o[:value] }
+        enabled = @options.reject { |o| o.disabled }.map { |o| o.value }
         if enabled.all? { |v| @selected.include?(v) }
           @selected.clear
         else
@@ -128,9 +128,9 @@ module Clack
 
       def invert_selection
         @options.each do |opt|
-          next if opt[:disabled]
+          next if opt.disabled
 
-          toggle_value(opt[:value])
+          toggle_value(opt.value)
         end
         update_selection_value
       end
@@ -146,22 +146,22 @@ module Clack
 
       def option_display(opt, idx)
         active = idx == @option_index
-        selected = @selected.include?(opt[:value])
+        selected = @selected.include?(opt.value)
 
         symbol, label = option_parts(opt, active, selected)
         "#{symbol} #{label}"
       end
 
       def option_parts(opt, active, selected)
-        if opt[:disabled]
+        if opt.disabled
           return [Colors.dim(Symbols::S_CHECKBOX_INACTIVE),
-            Colors.strikethrough(Colors.dim(opt[:label]))]
+            Colors.strikethrough(Colors.dim(opt.label))]
         end
-        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), opt[:label]] if active && selected
-        return [Colors.cyan(Symbols::S_CHECKBOX_ACTIVE), opt[:label]] if active
-        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), Colors.dim(opt[:label])] if selected
+        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), opt.label] if active && selected
+        return [Colors.cyan(Symbols::S_CHECKBOX_ACTIVE), opt.label] if active
+        return [Colors.green(Symbols::S_CHECKBOX_SELECTED), Colors.dim(opt.label)] if selected
 
-        [Colors.dim(Symbols::S_CHECKBOX_INACTIVE), Colors.dim(opt[:label])]
+        [Colors.dim(Symbols::S_CHECKBOX_INACTIVE), Colors.dim(opt.label)]
       end
     end
   end

data/lib/clack/prompts/progress.rb

@@ -36,6 +36,7 @@ module Clack
         @output = output
         @started = false
         @width = 40
+        @last_frame = nil
       end
 
       # Start displaying the progress bar.
@@ -105,8 +106,11 @@ module Clack
       def render
         return unless @started
 
-        @output.print "\r\e[2K"  # Return to start of line and clear it
-        @output.print "#{symbol}  #{progress_bar} #{percentage}#{message_text}"
+        frame = "#{symbol}  #{progress_bar} #{percentage}#{message_text}"
+        return if frame == @last_frame
+
+        @last_frame = frame
+        @output.print "\r\e[2K#{frame}"
         @output.flush
       end
 

data/lib/clack/prompts/select.rb

@@ -55,7 +55,7 @@ module Clack
         end
       end
 
-      def can_submit? = !current_option[:disabled]
+      def can_submit? = !current_option.disabled
 
       def build_frame
         option_lines = visible_options.each_with_index.map do |opt, idx|
@@ -66,7 +66,7 @@ module Clack
         "#{frame_header}#{option_lines}#{frame_footer}"
       end
 
-      def final_display = current_option[:label]
+      def final_display = current_option.label
 
       private
 
@@ -75,12 +75,12 @@ module Clack
         update_value
       end
 
-      def update_value = @value = current_option[:value]
+      def update_value = @value = current_option.value
 
       def current_option = @options[@option_index]
 
       def option_display(opt, active)
-        return disabled_option_display(opt) if opt[:disabled]
+        return disabled_option_display(opt) if opt.disabled
         return active_option_display(opt) if active
 
         inactive_option_display(opt)
@@ -88,19 +88,19 @@ module Clack
 
       def disabled_option_display(opt)
         symbol = Colors.dim(Symbols::S_RADIO_INACTIVE)
-        label = Colors.strikethrough(Colors.dim(opt[:label]))
+        label = Colors.strikethrough(Colors.dim(opt.label))
         "#{symbol} #{label}"
       end
 
       def active_option_display(opt)
         symbol = Colors.green(Symbols::S_RADIO_ACTIVE)
-        hint = opt[:hint] ? " #{Colors.dim("(#{opt[:hint]})")}" : ""
-        "#{symbol} #{opt[:label]}#{hint}"
+        hint = opt.hint ? " #{Colors.dim("(#{opt.hint})")}" : ""
+        "#{symbol} #{opt.label}#{hint}"
       end
 
       def inactive_option_display(opt)
         symbol = Colors.dim(Symbols::S_RADIO_INACTIVE)
-        "#{symbol} #{Colors.dim(opt[:label])}"
+        "#{symbol} #{Colors.dim(opt.label)}"
       end
     end
   end

data/lib/clack/prompts/select_key.rb

@@ -41,10 +41,10 @@ module Clack
         when :cancel
           @state = :cancel
         else
-          opt = @options.find { |o| o[:key]&.downcase == key&.downcase }
+          opt = @options.find { |o| o.key&.downcase == key&.downcase }
           return unless opt
 
-          @value = opt[:value]
+          @value = opt.value
           @state = :submit
         end
       end
@@ -63,25 +63,25 @@ module Clack
         lines.join
       end
 
-      def final_display = @options.find { |o| o[:value] == @value }&.dig(:label).to_s
+      def final_display = @options.find { |o| o.value == @value }&.label.to_s
 
       private
 
       def normalize_options(options)
         options.map do |opt|
-          {
+          Clack::Core::SelectKeyOption.new(
             value: opt[:value],
             label: opt[:label] || opt[:value].to_s,
             key: opt[:key] || opt[:value].to_s[0],
             hint: opt[:hint]
-          }
+          )
         end
       end
 
       def option_display(opt)
-        key_display = Colors.cyan("[#{opt[:key]}]")
-        hint = opt[:hint] ? " #{Colors.dim("(#{opt[:hint]})")}" : ""
-        "#{key_display} #{opt[:label]}#{hint}"
+        key_display = Colors.cyan("[#{opt.key}]")
+        hint = opt.hint ? " #{Colors.dim("(#{opt.hint})")}" : ""
+        "#{key_display} #{opt.label}#{hint}"
       end
     end
   end

data/lib/clack/prompts/tasks.rb

@@ -87,8 +87,13 @@ module Clack
 
           run_task(task)
         end
-        @output.print Core::Cursor.show
         @results
+      ensure
+        begin
+          @output.print Core::Cursor.show
+        rescue IOError, SystemCallError
+          # output stream already closed
+        end
       end
 
       private

data/lib/clack/utils.rb

@@ -11,11 +11,28 @@ module Clack
         text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
       end
 
-      # Get visible length of text (excluding ANSI codes)
-      # @param text [String] Text potentially containing ANSI codes
-      # @return [Integer] Visible character count
+      # Get visible length (display width in columns) of text after stripping ANSI.
+      # Uses display_width to correctly measure CJK, emoji, combining chars.
+      # @param text [String]
+      # @return [Integer] display columns
       def visible_length(text)
-        strip_ansi(text).length
+        display_width(strip_ansi(text))
+      end
+
+      # Calculate the terminal display width (columns) of a string.
+      # ASCII and most chars: width 1. CJK ideographs, fullwidth forms, common emoji: width 2.
+      # Zero-width joiners, combining marks, variation selectors: width 0.
+      # @param string [String]
+      # @return [Integer]
+      def display_width(string)
+        str = string.to_s
+        return 0 if str.empty?
+
+        width = 0
+        str.grapheme_clusters.each do |cluster|
+          width += grapheme_width(cluster)
+        end
+        width
       end
 
       # Wrap text to a specified width, preserving ANSI codes
@@ -54,7 +71,7 @@ module Clack
       def truncate(text, width, ellipsis: "...")
         return text if visible_length(text) <= width
 
-        target = width - ellipsis.length
+        target = width - visible_length(ellipsis)
         return ellipsis if target <= 0
 
         # Handle ANSI codes: we need to truncate visible chars while preserving codes
@@ -98,38 +115,105 @@ module Clack
 
       def break_long_word(word, width)
         lines = []
-        stripped = strip_ansi(word)
-        position = 0
-
-        while position < stripped.length
-          lines << stripped[position, width]
-          position += width
+        clusters = strip_ansi(word).grapheme_clusters
+
+        chunk = +""
+        chunk_width = 0
+        clusters.each do |gc|
+          gw = grapheme_width(gc)
+          if chunk_width + gw > width && !chunk.empty?
+            lines << chunk
+            chunk = +""
+            chunk_width = 0
+          end
+          chunk << gc
+          chunk_width += gw
+          # Force include first grapheme even if its width exceeds limit
+          if gw > width && chunk_width == gw
+            lines << chunk
+            chunk = +""
+            chunk_width = 0
+          end
         end
+        lines << chunk unless chunk.empty?
 
         lines
       end
 
       def truncate_visible(text, target_len)
-        result = ""
-        visible_count = 0
+        result = +""
+        visible_width = 0
         position = 0
+        ansi_re = /\A\e\[[0-9;]*[a-zA-Z]/
 
-        while position < text.length && visible_count < target_len
-          if text[position] == "\e" && (match = text[position..].match(/\A\e\[[0-9;]*[a-zA-Z]/))
-            # ANSI sequence - include it but don't count
-            result += match[0]
+        while position < text.length && visible_width < target_len
+          if text[position] == "\e" && (match = text[position..].match(ansi_re))
+            result << match[0]
             position += match[0].length
           else
-            result += text[position]
-            visible_count += 1
-            position += 1
+            # Extract the grapheme cluster starting at this position
+            gc = text[position..].grapheme_clusters.first
+            break unless gc
+
+            gw = grapheme_width(gc)
+            break if visible_width + gw > target_len
+            result << gc
+            visible_width += gw
+            position += gc.length
           end
         end
 
-        # Add reset if we have unclosed ANSI codes
-        result += "\e[0m" if result.include?("\e[") && !result.end_with?("\e[0m")
+        result << "\e[0m" if result.include?("\e[") && !result.end_with?("\e[0m")
         result
       end
+
+      # Width of a grapheme cluster: the max char_width among its codepoints.
+      # Handles ZWJ emoji sequences, combining marks, and flag sequences correctly.
+      def grapheme_width(cluster)
+        max_w = 0
+        cluster.each_char do |char|
+          w = char_width(char)
+          max_w = w if w > max_w
+        end
+        max_w
+      end
+
+      def char_width(char)
+        code = char.ord
+        return 0 if zero_width_code?(code)
+        return 2 if wide_char_code?(code)
+        1
+      end
+
+      def zero_width_code?(code)
+        return true if (0x0300..0x036F).cover?(code)
+        return true if (0x1AB0..0x1AFF).cover?(code)
+        return true if (0x20D0..0x20FF).cover?(code)
+        return true if [0x200B, 0x200C, 0x200D, 0xFEFF].include?(code)
+        return true if (0xFE00..0xFE0F).cover?(code)
+        false
+      end
+
+      def wide_char_code?(code)
+        # CJK Unified + extensions + compatibility
+        return true if (0x4E00..0x9FFF).cover?(code)
+        return true if (0x3400..0x4DBF).cover?(code)
+        return true if (0xF900..0xFAFF).cover?(code)
+        # Korean Hangul syllables
+        return true if (0xAC00..0xD7AF).cover?(code)
+        # Japanese kana
+        return true if (0x3040..0x309F).cover?(code)
+        return true if (0x30A0..0x30FF).cover?(code)
+        # Fullwidth and wide punctuation
+        return true if (0x3000..0x303F).cover?(code)
+        return true if (0xFF01..0xFF5E).cover?(code)
+        return true if (0xFFE0..0xFFE6).cover?(code)
+        # Common emoji / symbols blocks that render as wide
+        return true if (0x1F000..0x1F9FF).cover?(code)
+        return true if (0x2600..0x26FF).cover?(code)
+        return true if (0x2700..0x27BF).cover?(code)
+        false
+      end
     end
   end
 end

data/lib/clack/version.rb

@@ -2,5 +2,5 @@
 
 module Clack
   # Current gem version.
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Steve Whittaker
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Beautiful, minimal CLI prompts
 test_files: []