* Add `start` and `load` events alongside `change`
Introduce `start` and `load` bindable events, mirroring the existing
`change` event, so `--bind start:<action>` and `--bind load:<action>`
work.
To avoid scattering magic high-F-key literals (`F(255)` for `change`),
add a `SkimEvent` enum in `binds.rs` with `Start`, `Load` and `Change`
variants that transparently convert to the reserved `KeyEvent`s used to
route them through the keymap. `parse_key` now accepts the friendly
names `start`, `load` and `change` via `SkimEvent::from_name`. The keymap
key type stays `KeyEvent`, so the public API is unchanged.
Firing:
- `change` is emitted by `on_query_changed` (now via the named variant).
- `start` fires exactly once when skim enters its event loop
(`Skim::fire_start_event`).
- `load` fires once the reader has finished AND the freshly-read items
have been rendered into the list, so a `load` binding acts on a
fully-populated, stable list. It is re-armed on `reload`.
Add unit coverage for the event-name round-trip and integration tests
for `start` and `load` bindings, and document the events in
ARCHITECTURE.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QKxusGbxLxqWdYyeqrb68
* Add result/focus/zero/one events and action follow-up bindings
Extend the bindable-event set and generalise binding so that actions can
themselves be bound.
New finder events (fired from the post-draw `Event::Render` path, so a
binding sees a stable, up-to-date list):
- `result` — filtering for the current query completed
- `focus` — the focused item changed (cursor move or result update)
- `zero` — a completed search has no matches
- `one` — a completed search has exactly one match
`zero`/`one` read `MatcherControl::get_num_matched()` rather than the
rendered list count, which can briefly lag the matcher.
Actions as events: any action can be bound as if it were an event, so a
follow-up chain runs after it (e.g. `reload:first`, `first:last`). This is
parsed by `parse_action_binds` into `SkimOptions::action_binds` (keyed by
`Action::name`) and applied in `handle_action`, which now wraps the
per-variant `dispatch_action`.
- Keys win: a name shared by a key and an action binds the key; use an
`act-` prefix to target the action (`act-up:down`).
- New `skip` action suppresses the triggering action's own behaviour, so
`act-up:skip+down` remaps the up action to down and `up:skip` disables
the up key.
Also fixes `parse_key` so a non-numeric `f…` name (e.g. `focus`, `first`)
falls through to name/event matching instead of erroring on the function-
key branch.
Adds unit and snapshot tests and documents everything in ARCHITECTURE.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QKxusGbxLxqWdYyeqrb68
* Rename skip action to suppress and document it in the manpage
Rename the `skip` action to `suppress`, which more clearly conveys that
it cancels the triggering action's default behaviour. Add it to the
manpage actions list, noting that when bound to an action it suppresses
that action's default (so the rest of the chain runs in its place), and
when bound to a key it is equivalent to `ignore`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QKxusGbxLxqWdYyeqrb68
* Fire finder events from callbacks instead of the render path
Move the synthetic finder events off the per-render check:
- `focus` now rides along with `App::on_selection_changed` (via a small
`take_focus_event` helper), firing only when the focused item actually
changes on cursor movement.
- `load`/`result`/`zero`/`one` track async reader/matcher completion, which
has no synchronous callback, so `App::poll_completion_events` edge-triggers
them from the `Heartbeat` handler rather than the render path. A `Render`
is queued just before them so a list-inspecting binding (e.g. `load:first`)
still sees the finished results.
This removes the branching that previously ran on every render tick and
keeps the event logic out of the unrelated `dispatch_action` arms.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QKxusGbxLxqWdYyeqrb68
* misc tweaks incl. noremap
* fixes
* docs: document new binds
* coderabbit review
* fix: address Copilot review comments on action binds
- Split `--bind` specs with top-level comma splitting in `SkimOptions::build`
so commas inside parenthesized action arguments (e.g.
`act-up:execute(echo a,b)`) no longer garble follow-up bindings. Reuses the
existing `split_top_level` helper (now `pub(crate)`), matching
`KeyMap::add_keymaps_str`.
- Correct the misleading `load` event comment in `check_reader`: the event is
fired from `App::poll_completion_events` (the heartbeat handler), not the
render path.
- Add a unit test covering commas inside action arguments.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pxems1gNKKezFcxtZfURJp
* fix: harden action-trigger binds (logging, runtime bind/unbind, API surface)
Address three review findings on the action-trigger feature:
- Log dropped `--bind` specs: an unknown trigger name or an invalid
follow-up chain in parse_action_binds is now reported via debug!
instead of vanishing silently, matching the keymap path's behavior.
- Make the runtime `bind`/`unbind` actions manage action triggers as
well as keys: `bind(act-up:last)` merges into action_binds and
`unbind(act-up)` removes the trigger, with the same keys-win
precedence as `--bind`. Trigger-name resolution is shared through a
new binds::action_trigger_name helper.
- Narrow the new App fields (reader_done, load_event_fired,
result_pending) to pub(crate): they are a Skim<->App coordination
protocol, not public API.
Update the manpage (regenerated sk.1) and ARCHITECTURE.md accordingly,
and cover the new behavior with unit tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TgSqqsXn1GfQRZhQWAWi7t
* fix: don't abort the event loop on an invalid if-* branch chain
`if-*` branch chains are stored unparsed by `parse_action`, so an invalid
action name only surfaces when the binding fires. `dispatch_conditional`
propagated that parse error out of `App::handle_event`, killing the whole
finder mid-session on a bind typo. Log and skip the chain instead,
matching the invalid-chain handling of `parse_action_binds`.
Also refresh the stale line numbers in the ARCHITECTURE.md
cross-reference table.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TgSqqsXn1GfQRZhQWAWi7t
* fix: make sure to render before start in sync mode
* chore: push snaps
* fix: misc
* fix: address review comments on start event, if-* logging and docs
- skim.rs: retry the one-shot `start` event from `tick()` so a momentarily
full bounded `event_tx` at the `start()`/`enter()` call sites can no longer
drop it permanently. Idempotent via the `start_fired` guard.
- app.rs: log an invalid `if-*` conditional action chain at `warn!` instead of
`debug!` so a misconfigured binding is discoverable by default.
- ARCHITECTURE.md: clarify that `Skim::check_reader` only records `reader_done`;
`App::poll_completion_events` owns and emits `load`/`result`/`zero`/`one`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QKxusGbxLxqWdYyeqrb68
* chore: minor formatting
---------
Co-authored-by: Claude <noreply@anthropic.com>
* fix(tui): stop input reader and give execute() children their own tty
Interactive/ncurses programs run via an `execute()` action (e.g. `ncdu`)
would freeze after a few keystrokes. Two independent problems caused it:
1. skim's background input reader (the `EventStream` task started in
`Tui::start`) kept reading the terminal while the child ran, so skim and
the child raced for keystrokes on the same tty — roughly half the keys
were stolen from the child.
2. The child inherited skim's stdin (fd 0), which is a pipe whenever items
are piped in (`find | sk`). An interactive child then had no keyboard
source at all.
Fix both:
- Add `Tui::stop_and_join`, which cancels the event-pump task and blocks
until it has dropped its `EventStream`, guaranteeing skim has released the
terminal before the child starts. `run_foreground` calls it before running
the child and `Tui::start` after.
- Give the child its own stdin opened from the controlling terminal
(`/dev/tty`, or `CONIN$` on Windows), falling back to inheriting skim's
stdin if that fails.
Because running a foreground process needs the `Tui` (which `handle_action`
does not have), `Execute` now only expands the command and returns a new
`Event::RunExecute`, which `handle_event` runs via `run_foreground`. This
mirrors the existing `RunPreview` pattern. `execute-silent` is unchanged.
Update ARCHITECTURE.md (event dispatch table, terminal lifecycle, and
cross-reference line numbers) and add tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QBQ1chjHyN3JNTWqMMED44
* test(execute): add tmux e2e test; fix reader restart and post-execute repaint
Add a tmux-based integration test (tests/execute.rs, unix-gated so it runs
on the Linux and macOS CI legs) that drives an interactive child through an
`execute` action and asserts it keeps receiving keystrokes, then that skim
is interactive again once the child exits. It covers both the fullscreen and
inline (`--height`) layouts.
Writing the test surfaced two bugs in the execute reader-suspend work that
unit tests could not catch:
1. Reader never resumed. `Tui::stop_and_join` cancels the shared
`CancellationToken`, but `Tui::start` reused that same token — and a
cancelled token stays cancelled — so the respawned reader observed the
cancellation immediately and exited without reading input. `start` now
installs a fresh token on every call (also fixing the latent
restart-while-running path).
2. Post-execute repaint hung when stdout was redirected. The repaint went
through `Event::Redraw` → `tui.clear()`, and ratatui's `Terminal::clear`
queries the cursor position, which crossterm writes to stdout via
`ESC [ 6 n`. skim renders to stderr and its stdout is routinely redirected
(`sk > file`), so the query reached no terminal, got no reply, and stalled
the UI for seconds before erroring out. Replace it with
`Tui::force_full_redraw`, which resets ratatui's diff buffers for a full
repaint with no cursor query and works for both fullscreen and inline
viewports.
Update ARCHITECTURE.md and the cross-reference table accordingly.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QBQ1chjHyN3JNTWqMMED44
* ci: fix matrix
* fix: pop kitty keyboard flag before entering execute
* chore: remove duplication in backend.rs
* chore: refactor
* fix: kitty maintains a different set of flags in alt screen
---------
Co-authored-by: Claude <noreply@anthropic.com>
* feat: add `bind` and `unbind` actions
Add two new actions that allow programmatic (re)binding of keys at
runtime, both through `--bind` keybindings and the IPC/listen socket:
- `bind(key:action[+action][,key:action…])` adds one or more bindings,
reusing the same parsing/merging logic as the `--bind` CLI option.
Existing bindings for the same key are replaced.
- `unbind(key[,key…])` removes the bindings for a comma-separated list
of keys, mirroring fzf's `unbind(...)` semantics.
Because the `Action` enum derives serde when the `listen` feature is
enabled, both actions are drivable over the IPC socket for free.
Covered by unit tests for parsing (`event_tests.rs`) and dispatch
(`app_tests.rs`), plus IPC integration tests (`listen.rs`). Manpage and
ARCHITECTURE.md updated with the new actions.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JYqqomFjYqqXd5NvkVxfbQ
* feat: add `bind` and `unbind` actions
* chore: generate files
* fixes
* fixes
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Add --hide-nth flag to hide fields while keeping them searchable
Introduce a `--hide-nth <fieldspec>` option that takes the same
comma-separated field index expressions as `--nth`/`--with-nth`. The
listed fields are removed from the displayed line but remain part of the
text used for matching, so a query can still match them. Characters in
the hidden fields are ignored for match highlighting and horizontal
scrolling.
Implementation:
- Resolve the fieldspec to byte ranges in the same coordinate space as
the matching/display text and store them as `hidden_ranges` in
DefaultSkimItem metadata, exposed via a new `SkimItem::hidden_ranges()`
trait method. text()/output() keep the full text so hidden fields stay
searchable and are preserved on output.
- DefaultSkimItem::display() removes hidden characters and remaps match
highlight positions into visible coordinates (project_visible_text /
project_match_indices); this path takes precedence over ANSI styling.
- ItemRenderer::render_item applies the same projection to derive the
visible sub-line text and hscroll match range, so hidden characters are
ignored for horizontal scrolling.
Add unit tests for range normalization/projection and item behavior,
plus insta snapshot tests covering display removal, searchability, and
hscroll. Update ARCHITECTURE.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BCunXeAFMYAFduTc8SNjSM
* Preserve ANSI colors for surviving text under --hide-nth
Previously the hidden-field rendering path was applied ahead of the ANSI
display branch and rebuilt the line from the ANSI-stripped text, so
combining --hide-nth with --ansi dropped the colors of the visible
fields.
Integrate hidden-field removal into the ANSI branch instead: after
parsing the styled spans, drop the hidden characters while preserving
each span's style (retain_visible_spans) and remap the match positions
into the resulting visible coordinate space, then run the normal
highlighting. The plain (non-ANSI) branch keeps its project-and-to_line
handling. Surviving characters now keep their ANSI colors while hidden
fields stay searchable.
Add unit tests for ANSI color preservation and remapped highlighting,
plus ANSI color-snapshot integration tests. Update ARCHITECTURE.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BCunXeAFMYAFduTc8SNjSM
* Set hidden fields via builder instead of DefaultSkimItem::new param
Remove the `hidden_fields` parameter from `DefaultSkimItem::new` and set
the hidden fields through a `hidden_fields(&[FieldRange], &Regex)`
builder method instead. The builder resolves the fields against the
item's own `text()` (the same coordinate space `new` would have used),
so the result is identical while keeping `new`'s signature unchanged for
its many existing call sites.
The reader chains `.hidden_fields(&opt.hidden_fields, &opt.delimiter)`
onto construction. Revert the extra `&[]` argument at the other call
sites (selector, fuzz target, tests) and update the hide-nth tests to
use the builder. Update ARCHITECTURE.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BCunXeAFMYAFduTc8SNjSM
* chore: generate files
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Shrink binary: trim image decoders and swap color-eyre for eyre
Two dependency changes that cut the default `sk` binary from 13.6 MiB to
8.55 MiB (-5.06 MiB, -37%) with no loss of core functionality:
- image: build the `image` crate with only the common decoders (png,
jpeg, gif, webp) instead of its full default format set, and drop
ratatui-image's `image-defaults`. This removes AVIF encoding (ravif,
avif-serialize), OpenEXR (exr), TIFF, QOI and other decoders that are
irrelevant to terminal image previews. Previewing those formats now
falls back to the normal command preview.
- error handling: replace color-eyre with plain eyre. color-eyre only
provided colored panic/error backtraces; skim used none of its
Section/Help extension APIs. This drops the backtrace/gimli/addr2line/
color-spantrace stack. `color_eyre::install()` is no longer needed.
Tests, benches and examples are migrated from color_eyre to eyre so the
crate is fully removed from the dependency graph.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQtxeCS4gM7dumghqmNgST
* chore: fmt
* docs: ARCHITECTURE.md
* chore(flake): add cargo-bloat
---------
Co-authored-by: Claude <noreply@anthropic.com>
* feat!: feature-gate listen and image to allow opting out
This is breaking since disabling the default features now also disables
those. It is NOT breaking for cli users, only for library ones.
* fix: add warn on listener transfer failure
* feat(theme): add a themeable scrollbar color for the item list
The item-list scrollbar was the only rendered UI element without a
ColorTheme entry. ratatui's Scrollbar defaults thumb_style to an empty
Style, so the thumb merged nothing onto the cells it drew over and
inherited their fg/bg — most visibly the current-line highlight, which
the thumb adopted as the cursor scrolled past it.
Add a `scrollbar` color to ColorTheme, parse it from `--color`
(`scrollbar:<spec>`), default it per theme to the border color (the four
catppuccin themes use their muted `overlay0` instead), and pass it as the
Scrollbar thumb style. The thumb now reads as uniform chrome instead of
tracking whatever row sits under it. The colorless `none` theme leaves it
unset, so NO_COLOR still renders no thumb styling.
Documented in the README color table and the manpage; covered by theme
unit tests and @snap_color integration tests (default border color and a
custom --color=scrollbar override, both over the highlighted current line).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: generate-files & misc
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Loric ANDRE <loric.andre@pm.me>
* chore: deps: Only use frizbee on x86_64 and aarch64
* chore: update docs for frizbee support
* chore: docs [skip ci]
---------
Co-authored-by: LoricAndre <57358788+LoricAndre@users.noreply.github.com>
