clack 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 731bb8423776790866c97bc0a19e5e20c872113a6bdde1d0b631991c7d96257d
-  data.tar.gz: 892738ddc556225ce2b85db29bc845b0a2665a05b3492d0f98392612247db0ca
+  metadata.gz: fa10e11143746ae1c817d66c8a10b8c0a3a261d8379bd29e71c1134b27560bbc
+  data.tar.gz: 925aad6ecb7cf502f56ab9584de97c7b23462121881232b76b09214ecabf7fed
 SHA512:
-  metadata.gz: 71463cbd46a0aa1a99a15853df6b840e96dbffa9a44e32a3370e89dcb98b4ff9cc0e1b427edbe67f034fe4b6f794b5030c4fa29f5f4e3a174899e37ee6cefae7
-  data.tar.gz: bae64d320b7ad71ee2db3ef3c49a7c97c041d76edf14996f0fb4fd4bf106edb266f8280d5f211f54692b0356d2cab12c8624c811e8c0ee726e25d6ecf3c14071
+  metadata.gz: ef8452b1824f9df76ffbd3b5d4f8ef35d9be69e83265369171caa5b60c95938f3b0f09b40bdd687d0bf07e555a52abac17a4ef0f1674271f2b9ed27297fb9bca
+  data.tar.gz: f5818dfc7b664ef7d25852671c8c3ec4778fca5131f9731fe6bb9be67daa3788d4572c1ab264d9401c1fc60537ebc21c6a4f46a5f0a338e99de73a5eff0cb7ef

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.7.0] - 2026-08-29
+
+### Added
+- `with_guide: false` is now honored everywhere (it was a documented no-op): all prompts, `intro`/`outro`/`cancel`/`handle_cancel`, `log`, `stream`, `note`, `box`, `spinner`/`spin`, `tasks`, and `task_log`. Every prompt and message helper (except `progress`, which never drew a rail) also accepts a per-call `with_guide:` override, matching upstream `withGuide`
+- Keyboard hint footer for `select` (`↑/↓ to navigate • Enter: confirm`), `autocomplete`, and `path`, using upstream wording; `show_instructions: false` per prompt and `Clack.update_settings(show_instructions: false)` hide it; `instructions:` (a String or an Array of Strings) replaces the text on any prompt, e.g. for localized CLIs
+- `Clack.settings` gains `:show_instructions` (default `true`); `Clack::Core::Settings.with_guide?` and the new `show_instructions?` take an optional per-call override
+- Option-based prompts (`select`, `multiselect`, `autocomplete`, `autocomplete_multiselect`, `select_key`) accept a Hash for `options:`: keys are the values, Hash values are labels or `{label:, hint:, disabled:}` specs (`{pg: "PostgreSQL"}` returns `:pg`)
+- `group_multiselect` accepts a Hash of `group label => options`, matching upstream's shape; each group's options accept the same `value => label` Hash
+- `validate:` now accepts a Regexp (`validate: /\A[a-z]+\z/`, fails with "Invalid format"), a built-in validator Symbol (`validate: :email`), an Array of validators (combined, first failure wins), a Hash of `Regexp`/`Symbol => message` (a `Clack::Warning` message makes the entry a soft check), or any object responding to `#call`. Resolved by the new `Clack::Validators.resolve`, mirroring `Transformers.resolve`
+- `Clack::Validators.combine` and `Clack::Validators.as_warning` accept the same shapes (`combine(:required, /\A\d+\z/)`, `as_warning(:email)`)
+- `Clack::Validators::SHORTCUTS` lists the built-ins addressable by Symbol
+- `confirm` accepts `vertical: true` to stack the Yes/No options on separate lines, matching upstream `@clack/prompts` 1.0.1
+- `select_key` accepts `case_sensitive: true` to match option keys exactly, matching upstream 1.0.1; by default `Y` and `y` are still interchangeable
+- `select_key` accepts `initial_value:` to highlight a default option; Enter submits it and CI mode returns it instead of `nil` (an unknown value warns on stderr and is ignored, like `initial_values` elsewhere)
+- Spinner `cancel_message:`, `error_message:`, and `on_cancel:` options, matching upstream `cancelMessage`/`errorMessage`/`onCancel`
+- `Clack.update_settings(messages: {cancel:, error:})` to localize the cancel/error text used by spinners and `Clack.handle_cancel`
+- `Spinner#running?`
+- `Clack::NotATerminalError` (an `IOError`) with an actionable message is raised when a prompt reads from a piped or redirected stdin with CI mode off, replacing a bare `Errno::ENOTTY` from deep inside the key reader
+- `Clack::Core::Settings::KEY_HOME` / `KEY_END` canonical key codes and `Settings.normalize_key`
+
+### Changed
+- The guide rail next to the active step is now cyan (the upstream look); the connector above it stays gray and error/warning rails stay yellow. The `help:` line follows the same rule (it was gray in every state), and option rows in `select`, `select_key`, `autocomplete`, and `path` now turn yellow on a validation error too (they stayed gray before). Color only: nothing changes when colors are disabled
+- `select`, `autocomplete`, and `path` frames gain one footer line of keyboard hints by default; snapshot tests of their output need updating (`show_instructions: false` restores the old line count)
+- `multiselect`, `group_multiselect`, and `autocomplete_multiselect` footers use the upstream wording and separator (`↑/↓ to navigate • Space: select • Enter: confirm`, ASCII `up/down` and ` | `) instead of three different dialects; `autocomplete_multiselect` no longer shows its hint line while an error or warning is displayed (the other two already hid it). `multiselect`'s `a`/`i` shortcuts still work but are documented in the README instead of the footer
+- `box` renders inside the guide gutter (a gray `│ ` on each line) when guides are on, matching upstream
+- `Spinner#cancel` and `Spinner#error` called without a message now show the configured cancel/error message ("Cancelled" / "Something went wrong") instead of echoing the in-progress text
+- A spinner still running when the process exits (`exit`, Ctrl+C, an uncaught exception) now prints its cancel line (or error line) before the `at_exit` blocks your program registered earlier, instead of leaving a half-drawn frame
+- `ci_mode: :auto` checks the prompt's own `input:` stream instead of `$stdin`, so a `StringIO` or other non-TTY input auto-submits defaults
+- Escape sequences are parsed up to their CSI final byte, so a key typed right after an arrow key is no longer swallowed into the sequence
+- Key codes are normalized before alias lookup, so custom `aliases:` must be keyed on the canonical codes (`"\e[A"`, `Settings::KEY_HOME`); the SS3 and tilde variants (`\eOA`, `\e[1~`) are folded before the lookup and cannot be aliased directly
+
+### Fixed
+- Passing a Hash as `options:` no longer returns `[key, label]` pairs as values (`select`, `multiselect`, `autocomplete`) or raises `TypeError` (`select_key`, `group_multiselect`)
+- `group_multiselect` raises `ArgumentError` naming the group when a group's `options:` is not an option list (`nil`, a String, an Integer), instead of `NoMethodError`
+- `group_multiselect` now renders `Clack.warning` validation results; previously the first Enter looked dead and the second submitted without ever showing the message
+- `validate:` given an unsupported value (an Integer, an unknown Symbol) now raises `ArgumentError` when the prompt is constructed, instead of `NoMethodError` at submit time after the user has typed
+- `Validators.combine` no longer crashes at call time on `nil` entries (they are skipped)
+- `confirm` coerces `initial_value:` to a Boolean, so `initial_value: nil` returns `false` on Enter instead of `nil` (interactive and CI mode), and truthy non-Boolean values return `true`
+- `select_key` now honors `validate:` and `transform:` (they were accepted and silently ignored) and renders validation errors and warnings in its footer like every other prompt
+- `select_key` no longer crashes on the first keypress when an option's `key:` is not a String
+- CI mode confirms a `Clack.warning` validation result the way a second Enter does, so `transform:` is applied; previously the untransformed value was returned with the prompt left in `:warning` state
+- `range` with a fractional `step` (0.1, 0.05, ...) now snaps exactly instead of accumulating Float error, so three 0.1 steps return and display `0.3` rather than `0.30000000000000004`; an `initial_value` exactly halfway between two steps now rounds up to the next step (`0.15` on a `0.1` grid is `0.2`)
+- `Clack.spin` no longer leaves the animation thread running (repainting over later output) when the block calls `exit`, raises `Interrupt` or a non-`StandardError`, or exits via `break`/`throw`; it prints the final line and re-raises
+- `Clack.tasks` finishes its spinner when a task calls `exit`, raises `Interrupt`, or throws
+- Arrow keys in application cursor mode (tmux, after vim/less) no longer type a literal `A`/`B`/`C`/`D`: SS3 sequences (`\eOA`) are assembled and normalized to `\e[A`
+- Home/End variants (`\e[H`, `\eOH`, `\e[1~`, `\e[7~` and the End equivalents) are normalized to one code per key
+- End of input on a piped or `StringIO` input now cancels the prompt instead of spinning the run loop at 100% CPU
+- `FORCE_COLOR=0` (and `FORCE_COLOR=false`) now disables colors, cursor sequences and Unicode symbols instead of forcing them on
+- An empty `NO_COLOR=` is treated as unset, per no-color.org; an empty `FORCE_COLOR=` is likewise ignored
+- Redrawing a frame whose lines soft-wrap in a narrow terminal (for example the keyboard hint footer below about 51 columns) no longer leaves orphaned rail lines above the prompt
+- A child created with a block-less `fork` inside `Clack.spin` no longer prints the parent's cancel line or runs `on_cancel` when it exits
+
+### Docs
+- README gains Troubleshooting, Validation Shorthands, Environment variables (`NO_COLOR`, `FORCE_COLOR`, `CLACK_UNICODE`, `CLACK_ESCAPE_TIMEOUT`), Guide rail, and Keyboard hints sections; ARCHITECTURE.md input, color, symbol, spinner, and chrome descriptions now match the code. The README screenshots predate the cyan rail and the `select` footer
+
 ## [0.6.2] - 2026-08-13
 
 ### Added

data/README.md

@@ -115,6 +115,8 @@ Clack.outro "You're all set!"
 
 All prompts return the user's input, or `Clack::CANCEL` if the user pressed Escape/Ctrl+C.
 
+> The demo GIF and the screenshots below were recorded before 0.7.0, so they still show a gray rail next to the active step and no keyboard hint footer under `select`. See [Guide rail](#guide-rail) and [Keyboard hints](#keyboard-hints) for the current look.
+
 ### Text
 
 Single-line text input with placeholders, defaults, validation, and tab completion.
@@ -188,9 +190,27 @@ proceed = Clack.confirm(
 )
 ```
 
+Long labels read better stacked. Pass `vertical: true` to put each option on its own line (up/down, left/right, and `y`/`n` all still work):
+
+```ruby
+Clack.confirm(
+  message: "Overwrite ~/.zshrc?",
+  active: "Yes, back it up and replace it",
+  inactive: "No, keep my existing file",
+  initial_value: false,
+  vertical: true
+)
+# ◆  Overwrite ~/.zshrc?
+# │  ○ Yes, back it up and replace it
+# │  ● No, keep my existing file
+# └
+```
+
+`initial_value:` is coerced to a Boolean, so `nil` (for example an unset CLI flag) starts on "No" and the prompt returns `true`, `false`, or `Clack::CANCEL` (unless you pass a `transform:`).
+
 ### Select
 
-Pick one from a list. Navigate with arrow keys or `hjkl`.
+Pick one from a list. Navigate with arrow keys or `hjkl`. A footer of keyboard hints (key names dimmed) lists the keys (`↑/↓ to navigate • Enter: confirm`); pass `show_instructions: false` to hide it.
 
 <img src="examples/images/select.svg" alt="Select prompt">
 
@@ -207,6 +227,31 @@ db = Clack.select(
 )
 ```
 
+#### Option shorthands
+
+Every option-based prompt also accepts a Hash instead of an Array. For `select`, `multiselect`, `autocomplete`, `autocomplete_multiselect`, and `select_key`, keys are the values you get back, Hash values are the labels, and insertion order is the display order:
+
+```ruby
+db = Clack.select(message: "Choose a database", options: {pg: "PostgreSQL", mysql: "MySQL", sqlite: "SQLite"})
+# => :pg
+
+# Use a nested Hash when you need a hint or a disabled entry
+editor = Clack.select(
+  message: "Editor?",
+  options: {
+    nvim: { label: "Neovim", hint: "recommended" },
+    vim: "Vim",
+    nano: { label: "nano", disabled: true }
+  }
+)
+
+features = Clack.multiselect(message: "Features", options: {api: "API", auth: "Auth"}, initial_values: [:api])
+```
+
+`group_multiselect` takes `group label => options` at the top level; each group's options follow the same `value => label` rule (see [Group Multiselect](#group-multiselect)).
+
+The orientation is always `value => label`. A `label => value` Hash (the Rails `options_for_select` shape) is not detected; flip it with `.invert` first. Arrays of `[label, value]` pairs are not detected either, since Array-valued options are legal; use `.to_h` to build a Hash instead. A single `{ value:, label: }` option Hash must still be wrapped in an Array; passed bare, it is read as two `value => label` pairs.
+
 ### Multiselect
 
 Pick many. Toggle with Space. Select all with `a`. Invert with `i`.
@@ -227,7 +272,7 @@ features = Clack.multiselect(
 )
 ```
 
-**Shortcuts:** `Space` toggle | `a` all | `i` invert
+**Shortcuts:** `Space` select | `a` all | `i` invert | `Enter` confirm (the footer lists `Space` and `Enter`; `a` and `i` are extras not shown there; `show_instructions: false` hides the footer)
 
 ### Autocomplete
 
@@ -267,7 +312,7 @@ colors = Clack.autocomplete_multiselect(
 )
 ```
 
-**Shortcuts:** `Space` toggle | `Enter` confirm
+**Shortcuts:** `Space` select | `Enter` confirm | type to search
 
 > The `a` (select all), `i` (invert), and `j`/`k`/`h`/`l` shortcuts from Multiselect are not available here -- all keyboard input feeds into the search field instead. Use arrow keys to navigate.
 
@@ -283,7 +328,7 @@ project_dir = Clack.path(
 )
 ```
 
-**Navigation:** Type to filter | `Tab` to autocomplete | up/down arrows to select
+**Navigation:** Type to filter | `Tab` to complete | `↑/↓` to select (all listed in the footer)
 
 ### Date
 
@@ -315,8 +360,13 @@ volume = Clack.range(
   initial_value: 50
 )
 # Navigate with arrow keys or hjkl
+
+# Fractional steps snap exactly: three steps from 0 is 0.3, not 0.30000000000000004
+opacity = Clack.range(message: "Opacity", min: 0, max: 1, step: 0.1)
 ```
 
+Returns an `Integer` when `min` and `step` are both integers, otherwise a `Float`.
+
 ### Select Key
 
 Instant selection via keyboard shortcuts. No arrow key navigation needed.
@@ -332,6 +382,36 @@ action = Clack.select_key(
 )
 ```
 
+Keys match regardless of case by default. Pass `case_sensitive: true` to tell `Y` and `y` apart, and `initial_value:` to highlight a default that Enter accepts (it is also what CI mode returns). The highlight is a color effect, so when colors are off (`NO_COLOR`, piped output) mark the default in that option's `hint:` as well. `validate:` and `transform:` work like everywhere else.
+
+```ruby
+answer = Clack.select_key(
+  message: "Apply migration?",
+  options: [
+    { value: :yes_all, label: "Yes to all", key: "Y" },
+    { value: :yes, label: "Yes", key: "y" },
+    { value: :no, label: "No", key: "n", hint: "default" }
+  ],
+  case_sensitive: true,
+  initial_value: :no,
+  validate: ->(v) { "Not on Fridays" if v == :yes_all && Date.today.friday? }
+)
+```
+
+With the Hash shorthand the key defaults to the first character of the value. Pass a nested Hash to set it explicitly (`initial_value:` and `case_sensitive:` work the same way):
+
+```ruby
+action = Clack.select_key(
+  message: "What would you like to do?",
+  options: {
+    create: { label: "Create new project", key: "c" },
+    open: "Open existing",   # key "o"
+    quit: "Quit"             # key "q"
+  },
+  initial_value: :open
+)
+```
+
 ### Group Multiselect
 
 Multiselect with options organized into named categories.
@@ -360,6 +440,19 @@ features = Clack.group_multiselect(
 )
 ```
 
+Groups can also be a Hash of `group label => options`, and each group's options accept the same `value => label` shorthand (or a plain Array):
+
+```ruby
+addons = Clack.group_multiselect(
+  message: "Add-ons",
+  options: {
+    "Observability" => { prom: "Prometheus", dd: "Datadog" },
+    "Storage" => { s3: "S3", gcs: "GCS" }
+  }
+)
+# => [:prom, :s3]
+```
+
 ### Spinner
 
 Non-blocking animated indicator for async work.
@@ -395,6 +488,27 @@ Clack.spin("Working...") do |s|
 end
 ```
 
+**Cancel and error messages** -- `cancel`/`error` with no argument, Ctrl+C, and `exit` use these instead of the in-progress text:
+
+```ruby
+s = Clack.spinner(
+  cancel_message: "Deploy aborted",     # default: "Cancelled"
+  error_message: "Deploy failed",       # default: "Something went wrong"
+  on_cancel: -> { release_lock }        # runs once after a cancel, no arguments
+)
+s.start("Deploying")
+s.cancel   # => "■  Deploy aborted", on_cancel runs
+```
+
+Inside `Clack.spin`, an exception raised by the block prints `error:` or the exception message; `error_message:` only applies to a bare `s.error` or an uncaught crash at process exit.
+
+**Ctrl+C and `exit` are safe.** A spinner that is still running when the process exits (Ctrl+C, `exit`, an uncaught error) prints its cancel or error line and stops animating before the `at_exit` blocks your program registered earlier, instead of leaving a half-drawn frame. `Clack.spin` does the same when its block exits early (`exit`, `break`, `throw`, `Interrupt`):
+
+```ruby
+Clack.spin("Building", cancel_message: "Build cancelled") { exit 2 }
+# ■  Build cancelled          (then the process exits with status 2)
+```
+
 ### Progress
 
 A visual progress bar for measurable operations.
@@ -446,22 +560,22 @@ Clack.tasks(tasks: [
 |--------|--------|-------------|----------|
 | Text | `Clack.text` | `placeholder:`, `default_value:`, `initial_value:`, `completions:` | -- |
 | Password | `Clack.password` | `mask:`, `validate:` | `mask: "▪"` |
-| Confirm | `Clack.confirm` | `active:`, `inactive:`, `initial_value:` | `active: "Yes"`, `inactive: "No"`, `initial_value: true` |
-| Select | `Clack.select` | `options:`, `initial_value:`, `max_items:` | -- |
-| Multiselect | `Clack.multiselect` | `options:`, `initial_values:`, `required:`, `cursor_at:` | `required: true` |
+| Confirm | `Clack.confirm` | `active:`, `inactive:`, `initial_value:`, `vertical:` | `active: "Yes"`, `inactive: "No"`, `initial_value: true`, `vertical: false` |
+| Select | `Clack.select` | `options:` (Array or Hash), `initial_value:`, `max_items:`, `show_instructions:` | -- |
+| Multiselect | `Clack.multiselect` | `options:`, `initial_values:`, `required:`, `cursor_at:`, `show_instructions:` | `required: true` |
 | Group Multiselect | `Clack.group_multiselect` | `options:` (nested), `selectable_groups:`, `group_spacing:` | `selectable_groups: false` |
 | Autocomplete | `Clack.autocomplete` | `options:`, `placeholder:`, `filter:`, `max_items:` | `max_items: 5` |
 | Autocomplete Multiselect | `Clack.autocomplete_multiselect` | `options:`, `required:`, `initial_values:`, `filter:` | `required: true`, `max_items: 5` |
-| Select Key | `Clack.select_key` | `options:` (with `:key`) | -- |
+| Select Key | `Clack.select_key` | `options:` (with `:key`), `case_sensitive:`, `initial_value:` | `case_sensitive: false` |
 | Path | `Clack.path` | `root:`, `only_directories:` | `root: "."` |
 | Date | `Clack.date` | `format:`, `initial_value:`, `min:`, `max:` | `format: :iso` |
 | Range | `Clack.range` | `min:`, `max:`, `step:`, `initial_value:` | `min: 0`, `max: 100`, `step: 1` |
 | Multiline Text | `Clack.multiline_text` | `initial_value:`, `validate:` | Submit with **Ctrl+D** |
-| Spinner | `Clack.spinner` / `Clack.spin` | block form auto-handles success/error | -- |
+| Spinner | `Clack.spinner` / `Clack.spin` | `indicator:`, `cancel_message:`, `error_message:`, `on_cancel:` | `indicator: :dots` |
 | Tasks | `Clack.tasks` | `tasks:` (`{title:, task:, enabled:}`) | `enabled: true` |
 | Progress | `Clack.progress` | `total:`, `message:` | -- |
 
-All prompts accept `message:`, `validate:`, `help:`, and return `Clack::CANCEL` on Escape/Ctrl+C.
+All prompts accept `message:`, `validate:` (a proc, Regexp, Symbol, Array, or Hash; see [Validation Shorthands](#validation-shorthands)), `help:`, `with_guide:`, `instructions:`, and return `Clack::CANCEL` on Escape/Ctrl+C.
 
 </details>
 
@@ -479,6 +593,8 @@ exit 1 if Clack.handle_cancel(result)
 
 # With a custom message
 exit 1 if Clack.handle_cancel(result, "Aborted by user")
+
+# The default "Cancelled" text follows `Clack.update_settings(messages: {cancel: ...})`
 ```
 
 ---
@@ -523,6 +639,51 @@ file = Clack.text(
 )
 ```
 
+### Validation Shorthands
+
+`validate:` takes more than a lambda. Everything below is normalized by `Clack::Validators.resolve` when the prompt is built, so a typo raises `ArgumentError` immediately instead of crashing after the user has typed.
+
+```ruby
+# Regexp: fails with "Invalid format" unless the whole value matches
+slug = Clack.text(message: "Slug?", validate: /\A[a-z0-9-]+\z/)
+
+# Symbol: a zero-argument built-in validator
+email = Clack.text(message: "Email?", validate: :email)
+
+# Hash: pattern (or symbol) => custom message, checked in order
+user = Clack.text(
+  message: "Username?",
+  validate: {
+    required: "Username is required",
+    /\A[a-z0-9_]+\z/ => "Lowercase letters, numbers, and underscores only"
+  }
+)
+
+# Array: combine validators, first failure wins (nil or false entries are skipped)
+handle = Clack.text(
+  message: "Handle?",
+  validate: [:required, /\A\w+\z/, ->(v) { "Taken" if TAKEN.include?(v) }]
+)
+
+# Anything that responds to #call: procs, Method objects, service objects
+port = Clack.text(message: "Port?", validate: method(:check_port))
+```
+
+Symbols available as shorthands: `:required`, `:email`, `:url`, `:integer` (any text-style prompt); `:path_exists`, `:directory_exists`, `:file_exists_warning` (a path string, so `text` or `path`); `:future_date`, `:past_date` (a `Date`, so the `date` prompt). They run against the prompt's raw value, so `:future_date` on a text prompt raises at submit. Built-ins that take arguments (`min_length`, `in_range`, `one_of`, ...) are called explicitly and mixed in: `validate: [:required, Clack::Validators.min_length(3)]`.
+
+Regexps are checked with `match?` against `value.to_s`, so anchor with `\A` and `\z` (not `^`/`$`) unless you want per-line matching. A Regexp always means "the value must match"; to soften the check, use a `Clack::Warning` as the Hash message: `{/\A[a-z0-9-]+\z/ => Clack.warning("Unusual characters, continue?")}` warns instead of blocking when the value doesn't match. The same works for symbol keys: `{file_exists_warning: Clack.warning("Overwrite?")}`.
+
+`Clack::Validators.combine` and `Clack::Validators.as_warning` accept the same shapes: `combine(:required, /\A\d+\z/)`, `as_warning(:email)`.
+
+Using a schema library? Wrap it in a lambda that returns the first error message:
+
+```ruby
+contract = SignupContract.new  # dry-validation
+Clack.text(message: "Email?", validate: ->(v) { contract.call(email: v).errors[:email]&.first })
+```
+
+Don't pass the contract itself: its `call` returns a Result object, which is always truthy, so the prompt would treat every submit as an error.
+
 ### Built-in Validators
 
 ```ruby
@@ -545,6 +706,10 @@ Clack::Validators.combine(v1, v2)       # First error/warning wins
 # Warning validators -- allow user to confirm or edit
 Clack::Validators.file_exists_warning   # For file overwrite confirmations
 Clack::Validators.as_warning(validator) # Convert any validator to warning
+
+# Zero-argument validators above also work as bare symbols or Hash keys:
+Clack.text(message: "Email?", validate: :email)
+Clack.text(message: "Email?", validate: {email: "That doesn't look right"})
 ```
 
 ### Built-in Transformers
@@ -602,6 +767,8 @@ Clack.log.step("Running migrations")
 Clack.log.message("Custom message")
 ```
 
+`Clack.log.*` and `Clack.stream.*` accept `with_guide: false` (or follow the global setting). The level symbol stays on the first line; only the continuation rail goes away.
+
 ### Stream
 
 Stream output from iterables, enumerables, or shell commands:
@@ -648,6 +815,8 @@ Clack.box(
 )
 ```
 
+Boxes sit inside the guide rail (a gray `│ ` on every line) so they line up with the prompts around them; pass `with_guide: false` to render one flush left.
+
 ### Task Log
 
 Streaming log that clears on success and shows full output on failure. Great for build output:
@@ -676,6 +845,8 @@ Clack.outro("Done!")        # └ Done!
 
 # Or on error:
 Clack.cancel("Aborted")     # └ Aborted (red)
+
+# with_guide: false drops the ┌ │ └ symbols on all three
 ```
 
 ---
@@ -686,17 +857,80 @@ Clack.cancel("Aborted")     # └ Aborted (red)
 # Add custom key bindings (merged with defaults)
 Clack.update_settings(aliases: { "y" => :enter, "n" => :cancel })
 
-# Disable guide bars
+# Hide the guide rail everywhere (per-call with_guide: overrides this)
 Clack.update_settings(with_guide: false)
 
+# Hide the keyboard hint footer under list prompts
+Clack.update_settings(show_instructions: false)
+
+# Localize the cancel/error text used by spinners and Clack.handle_cancel
+Clack.update_settings(messages: { cancel: "Abgebrochen", error: "Etwas ging schief" })
+
 # CI / non-interactive mode (prompts auto-submit with defaults)
 Clack.update_settings(ci_mode: true)       # Always on
-Clack.update_settings(ci_mode: :auto)      # Auto-detect (non-TTY or CI env vars)
+Clack.update_settings(ci_mode: :auto)      # Auto-detect (piped/non-TTY input or CI env vars)
 ```
 
-When CI mode is active, prompts immediately submit with their default values instead of waiting for input. Useful for CI pipelines and scripted environments where stdin is not a TTY.
+When CI mode is active, prompts immediately submit with their default values instead of waiting for input. Useful for CI pipelines and scripted environments where stdin is not a TTY. With `:auto`, detection looks at the prompt's own `input:` stream (stdin by default), so a `StringIO` input auto-submits as well.
 
-Clack also warns when terminal width is below 40 columns, since prompts may not render cleanly in very narrow terminals.
+Without CI mode, prompting on a piped or redirected stdin raises `Clack::NotATerminalError` (see [Troubleshooting](#troubleshooting)).
+
+Clack also warns when terminal width is below 40 columns, since prompts may not render cleanly in very narrow terminals. Keyboard hint footers soft-wrap below roughly 51 columns rather than corrupting the frame; pass `show_instructions: false` or a shorter `instructions:` to avoid the wrap.
+
+### Environment variables
+
+Color, cursor and symbol output are auto-detected from the terminal. Override with the usual variables:
+
+| Variable | Effect |
+|---|---|
+| `NO_COLOR=1` | Disable ANSI colors and cursor sequences, use ASCII symbols. Any non-empty value works; an empty value is ignored (per [no-color.org](https://no-color.org)). |
+| `FORCE_COLOR=1` | Enable colors even when output is piped or `TERM=dumb`, e.g. to keep colors in a CI log. `NO_COLOR` still wins. |
+| `FORCE_COLOR=0` | Disable colors everywhere, same as `NO_COLOR=1`. `false` works too. |
+| `CLACK_UNICODE=1` / `0` | Force Unicode or ASCII symbols regardless of color detection. |
+| `CLACK_ESCAPE_TIMEOUT=250` | Escape-key detection window in milliseconds, for slow SSH links where arrow keys get misread as Escape. |
+
+```bash
+FORCE_COLOR=0 ruby my_cli.rb                  # plain text in a real terminal
+FORCE_COLOR=1 ruby my_cli.rb 2>&1 | tee run.log  # keep colors in a captured log
+```
+
+### Guide rail
+
+Every prompt and message helper except `progress` draws the gray rail (`│`, `┌`, `└`) that ties a session together. The rail next to the step you are answering is cyan; it turns yellow on a validation error. Turn the rail off globally or per call:
+
+```ruby
+Clack.update_settings(with_guide: false)              # everywhere
+Clack.select(message: "DB?", options: dbs, with_guide: true)   # per-call override wins
+Clack.log.info("plain", with_guide: false)
+```
+
+With guides off the connector lines disappear and content starts flush left:
+
+```
+◆  Choose a database          instead of      │
+● PostgreSQL                                  ◆  Choose a database
+○ MySQL                                       │  ● PostgreSQL
+↑/↓ to navigate • Enter: confirm              │  ○ MySQL
+                                              │  ↑/↓ to navigate • Enter: confirm
+                                              └
+```
+
+`Clack.log.*` and `Clack.stream.*` keep their level symbol (`●`, `▲`, `■`) with guides off; only the rail goes away.
+
+### Keyboard hints
+
+`select`, `multiselect`, `group_multiselect`, `autocomplete`, `autocomplete_multiselect`, and `path` end with a line of keyboard hints (key names dimmed). Hide it per prompt with `show_instructions: false`, everywhere with `Clack.update_settings(show_instructions: false)`, or replace the text (for localized CLIs) with `instructions:`, a String or an Array of Strings joined with ` • `:
+
+```ruby
+Clack.multiselect(
+  message: "Funktionen",
+  options: features,
+  instructions: ["Leertaste: wählen", "a: alle", "i: umkehren", "Enter: bestätigen"]
+)
+
+# instructions: works on any prompt, even ones without built-in hints
+Clack.text(message: "Slug?", instructions: "lowercase, digits and dashes")
+```
 
 ---
 
@@ -735,6 +969,39 @@ The `PromptDriver` yielded to the block provides these methods:
 | `ctrl_d` | Press Ctrl+D (submit multiline text) |
 | `key(sym_or_char)` | Press an arbitrary key by symbol (e.g. `:escape`) or raw character |
 
+Any object that responds to `getc` works as `input:`, so a plain `StringIO` is enough for simple cases. When the input runs out (EOF) the prompt cancels and returns `Clack::CANCEL`, so end scripted input with `"\r"` to submit (or `"\u0004"`, Ctrl+D, for `multiline_text`):
+
+```ruby
+Clack.select(message: "Pick", options: %w[a b c], input: StringIO.new("j\r"), output: StringIO.new)
+# => "b"
+```
+
+Arrow keys do not work in a `StringIO`: it cannot be probed for follow-up bytes, so an escape sequence such as `"\e[B"` is read as a bare Escape (which cancels the prompt) followed by `[` and `B`. Use the vim keys (`j`/`k`/`h`/`l`) in scripted input, or `Clack::Testing.simulate` / `Clack::Testing::KeyQueue`, which deliver whole key codes, for arrow navigation.
+
+If your app sets `ci_mode: :auto`, reset it in test setup (`Clack::Core::Settings.reset!`): a simulated input is not a TTY, so `:auto` would auto-submit instead of following your script.
+
+---
+
+## Troubleshooting
+
+### `Clack::NotATerminalError: stdin is not an interactive terminal`
+
+Prompts read keystrokes in raw mode, which needs a real terminal. You will see this when stdin is a pipe or a file (`echo y | ruby app.rb`, `ruby app.rb < answers.txt`, a cron job, a CI step). Either run the script from a terminal, or opt in to non-interactive runs so prompts submit their defaults:
+
+```ruby
+Clack.update_settings(ci_mode: :auto)   # auto-submit defaults when input is not a TTY or a CI env var is set
+```
+
+To answer prompts from a script rather than skip them, pass the answers as `input:` (see [Testing](#testing)). The error is an `IOError`, so a top-level `rescue IOError` catches it.
+
+### Prompt exits with `CANCEL` as soon as piped input runs out
+
+End of input is treated like Ctrl+C. Terminate each answer with `"\r"` (Enter), and for `multiline_text` finish with `"\u0004"` (Ctrl+D).
+
+### Arrow keys type letters, or do nothing, in tmux or after vim
+
+Terminals in application cursor mode send `ESC O A` instead of `ESC [ A` for Up. Clack 0.7.0 understands both, and also folds the various Home/End encodings into one. If arrows still misbehave over a slow SSH or mosh link, raise the Escape detection window: `CLACK_ESCAPE_TIMEOUT=250` (milliseconds, default 50).
+
 ---
 
 ## Try It

data/examples/migration_from_tty_prompt.rb

@@ -149,18 +149,27 @@ Clack.log.info "Language: #{lang}"
 #   email = prompt.ask("Email?", validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\z/i)
 #   age   = prompt.ask("Age?") { |q| q.validate(->(v) { v.to_i > 0 }, "Must be positive") }
 #
-# Clack uses a validate lambda that returns nil (pass) or an error string:
+# Clack takes the same Regexp directly (or :email for the common case).
+# A Hash gives the pattern a custom message. Lambdas return nil (pass)
+# or an error string:
 
 email = Clack.text(
   message: "Email?",
-  validate: ->(v) {
-    "Invalid email" unless v.match?(/\A[\w+\-.]+@[a-z\d-]+(\.[a-z]+)*\z/i)
-  }
+  validate: {/\A[\w+\-.]+@[a-z\d-]+(\.[a-z]+)*\z/i => "Invalid email"}
 )
 exit 0 if Clack.cancel?(email)
 
 Clack.log.info "Email: #{email}"
 
+age = Clack.text(
+  message: "Age?",
+  validate: ->(v) { "Must be positive" unless v.to_i.positive? },
+  transform: :to_integer
+)
+exit 0 if Clack.cancel?(age)
+
+Clack.log.info "Age: #{age}"
+
 # ─────────────────────────────────────────────
 # 8. Collecting multiple prompts (group)
 # ─────────────────────────────────────────────

data/lib/clack/box.rb

@@ -13,7 +13,10 @@ module Clack
       # @param title_padding [Integer] Padding around title
       # @param content_padding [Integer] Padding around content
       # @param rounded [Boolean] Use rounded corners (default: true)
-      # @param format_border [Proc] Optional proc to format border characters
+      # @param format_border [Proc] Optional proc to format border characters (the guide
+      #   gutter in front of each line is not passed through it)
+      # @param with_guide [Boolean, nil] Prefix every line with the gray guide rail so the box
+      #   lines up with the prompts around it (default: Clack.settings[:with_guide])
       # @param output [IO] Output stream
       def render(
         message = "",
@@ -25,12 +28,15 @@ module Clack
         content_padding: 2,
         rounded: true,
         format_border: nil,
+        with_guide: nil,
         output: $stdout
       )
         ctx = build_context(message, title, title_padding, content_padding, width, rounded, format_border)
-        output.puts build_top_border(ctx[:display_title], ctx[:inner_width], title_padding, title_align, ctx[:symbols], ctx[:h_symbol])
+        ctx[:line_prefix] = Core::Settings.with_guide?(with_guide) ? "#{Colors.gray(Symbols::S_BAR)} " : ""
+        top = build_top_border(ctx[:display_title], ctx[:inner_width], title_padding, title_align, ctx[:symbols], ctx[:h_symbol])
+        output.puts "#{ctx[:line_prefix]}#{top}"
         render_content_lines(output, ctx, content_align, content_padding)
-        output.puts "#{ctx[:symbols][2]}#{ctx[:h_symbol] * ctx[:inner_width]}#{ctx[:symbols][3]}"
+        output.puts "#{ctx[:line_prefix]}#{ctx[:symbols][2]}#{ctx[:h_symbol] * ctx[:inner_width]}#{ctx[:symbols][3]}"
       end
 
       private
@@ -57,7 +63,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(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]}"
+          output.puts "#{ctx[:line_prefix]}#{ctx[:v_symbol]}#{" " * left_pad}#{line}#{" " * right_pad}#{ctx[:v_symbol]}"
         end
       end
 
@@ -83,7 +89,7 @@ module Clack
         return width + 2 if width.is_a?(Integer) # Add 2 for borders
 
         # Auto width: fit to content using display width
-        max_line = lines.map { |l| Clack::Utils.visible_length(l) }.max || 0
+        max_line = lines.map { |line| Clack::Utils.visible_length(line) }.max || 0
         title_with_padding = title_len + (title_padding * 2)
         content_with_padding = max_line + (content_padding * 2)
 

data/lib/clack/colors.rb

@@ -2,12 +2,17 @@
 
 module Clack
   # ANSI color codes for terminal output styling.
-  # Colors are automatically disabled when:
-  # - Output is not a TTY (piped/redirected)
-  # - NO_COLOR environment variable is set
-  # - FORCE_COLOR environment variable forces colors on
+  #
+  # Colors are enabled when {Environment.colors_supported?} says so: on a TTY
+  # that is not +TERM=dumb+, or anywhere when +FORCE_COLOR+ is set to a
+  # non-empty value other than +0+ / +false+. A non-empty +NO_COLOR+ or
+  # +FORCE_COLOR=0+ disables them everywhere. When disabled every method
+  # returns the plain text unchanged.
   module Colors
     class << self
+      # Whether ANSI styling is currently active for +$stdout+.
+      # Delegates to {Environment.colors_supported?} on every call.
+      # @return [Boolean]
       def enabled? = Environment.colors_supported?
 
       # @!group Foreground Colors (standard)