pikl/docs/DEVPLAN.md

# pikl-menu: Development Plan

Implementation order, phase definitions, and the running
list of ideas. The DESIGN.md is the source of truth for
*what* pikl-menu is. This doc is the plan for *how and
when* we build it.

## Principles

- Get a working vertical slice before going wide on features
- pikl-core stays rendering-agnostic. No GUI or TUI deps
  in the library.
- Every feature gets tests in pikl-core before frontend work
- Ship something usable early, iterate from real usage
- Don't optimize until there's a reason to

## Phase 1: Core Loop (TUI) ✓

The minimum thing that works end-to-end.

**Deliverables:**
- pikl-core: Item store (accepts JSON lines on stdin,
  plain text fallback)
- pikl-core: Basic fuzzy filter on label
- pikl-core: Single selection, Enter to confirm, Escape
  to cancel
- pikl-core: Event bus with on-select and on-cancel hooks
  (shell commands)
- pikl-tui: ratatui list renderer
- pikl (CLI): Reads stdin, opens TUI, emits selected item
  as JSON on stdout
- Exit codes: 0 = selected, 1 = cancelled, 2 = error
- CI: Strict clippy, fmt, tests on Linux + macOS

**Done when:** `ls | pikl` works and prints the selected
item.

## Phase 1.5: Action-fd (Headless Mode) ✓

Scriptable, non-interactive mode for integration tests and
automation. Small enough to slot in before phase 2. It's
about 100 lines of new code plus the binary orchestration
for `show-ui`.

**Deliverables:**
- `--action-fd <N>`: read action script from file
  descriptor N
- Action protocol: plain text, one action per line
  (filter, move-up/down, confirm, cancel, etc.)
- `show-ui` / `show-tui` / `show-gui` actions for
  headless-to-interactive handoff
- Upfront validation pass: reject unknown actions,
  malformed args, actions after show-ui
- `--stdin-timeout <seconds>`: default 30s in action-fd
  mode, 0 in interactive mode
- Default viewport height of 50 in headless mode
- Binary integration tests: spawn pikl with piped stdin +
  action-fd, assert stdout

**Done when:** `echo -e "hello\nworld" | pikl --action-fd 3`
with `confirm` on fd 3 prints `"hello"` to stdout.

## Phase 2: Navigation & Filtering ✓

Make it feel like home for a vim user. The filter system
is the real star here: strategy prefixes, pipeline
chaining, incremental caching.

**Implementation order:**

1. Mode system in core (Insert/Normal, Ctrl+N/Ctrl+E
   to switch)
2. Normal mode vim nav (j/k/gg/G/Ctrl+D/U/Ctrl+F/B)
3. `/` in normal mode enters insert mode with filter
   focused
4. Filter strategy engine (prefix parsing: `'`, `!`, `!'`,
   `/pattern/`, `!/pattern/`)
5. `fancy-regex` integration for the regex strategy
6. Filter pipeline (`|` chaining between stages,
   incremental caching)

**Deliverables:**
- Insert mode / normal mode (Ctrl+N to normal, Ctrl+E
  to insert)
- Escape always cancels and exits, in any mode
- Normal mode: j/k, gg, G, Ctrl+D/U, Ctrl+F/B
- `/` in normal mode enters filter (insert) mode
- `--start-mode normal` flag
- Filter strategies via inline prefixes: fuzzy (default),
  exact (`'term`), inverse (`!term`, `!'term`), regex
  (`/pattern/`, `!/pattern/`)
- fancy-regex integration (unlimited capture groups,
  lookaround)
- Filter pipeline with `|`: each stage narrows the
  previous stage's output
- Incremental filter caching: each stage caches item
  indices, only recomputes from the edited stage forward
- Arrow keys to navigate within the filter text and edit
  earlier pipeline segments
- `\|` escapes a literal pipe in the query
- Case rules: fuzzy = smart case, exact =
  case-insensitive, regex = case-sensitive (use `(?i)`
  for insensitive)

**Deferred to later:**
- H/M/L (viewport-relative jumps): nice-to-have, not
  essential
- Filter syntax highlighting in the input field: deferred
  to theming work

**Done when:** You can navigate and filter a large list
with vim muscle memory.
`'log | !temp | /[0-9]+/` works as a pipeline.

## Phase 3: Structured I/O & Hooks ✓

The structured data pipeline and the full hook system.

**Implementation order:**

1. Item model expansion (sublabel, meta, icon, group as
   explicit optional fields on Item, alongside the raw
   Value)
2. Output struct with action context (separate from the
   original item, no mutation)
3. HookHandler trait in pikl-core, HookEvent enum,
   HookResponse enum
4. Exec hooks in CLI: `--on-<event>-exec` flags, subprocess
   per event, stdout discarded
5. Debounce system: none / debounce(ms) / cancel-stale,
   configurable per hook via CLI flags
6. Handler hooks in CLI: `--on-<event>` flags, persistent
   process, stdin/stdout JSON line protocol
7. Handler protocol commands: add_items, replace_items,
   remove_items, set_filter, close
8. `--filter-fields` scoping (which fields the filter
   searches against)
9. `--format` template strings for display
   (`{label} - {sublabel}`)
10. Field filters in query syntax (`meta.res:3840`),
    integrated into the filter pipeline

**Deliverables:**
- Item model: sublabel, meta, icon, group as first-class
  optional fields
- Output: separate struct with action context (action,
  index) wrapping the original item
- Exec hooks (`--on-<event>-exec`): fire-and-forget,
  subprocess per event, item JSON on stdin
- Handler hooks (`--on-<event>`): persistent bidirectional
  process, JSON lines on stdin/stdout
- Handler protocol: add_items, replace_items, remove_items,
  set_filter, close
- Full lifecycle events: on-open, on-close, on-hover,
  on-select, on-cancel, on-filter
- Debounce: three modes (none, debounce, cancel-stale),
  per-hook CLI flags
- Default debounce: on-hover 200ms + cancel-stale,
  on-filter 200ms, others none
- HookHandler trait in pikl-core (core emits events, does
  not know what handlers do)
- `--filter-fields label,sublabel,meta.tags`
- `--format '{label} - {sublabel}'` template rendering
- Field filters: `meta.res:3840` in query text
- tracing for hook warnings (bad JSON, unknown actions,
  process exit)

**Done when:** The wallpaper picker use case works entirely
through hooks and structured I/O. A handler hook can
receive hover events and emit commands to modify menu
state.

## Phase 4: Multi-Select & Registers

Power selection features.

**Deliverables:**
- Space to toggle select, V for visual line mode
- Multi-select output (multiple JSON lines)
- Named registers (`"a` through `"z`)
- Marks (`m{a-z}`, `'{a-z}`)
- `--multi` flag to enable multi-select mode

**Done when:** You can select multiple items, store them
in registers, and get them all in the output.

## Phase 5: Table Mode & CSV

Columnar data display.

**Deliverables:**
- `--columns` flag for table layout
- Auto-alignment
- Column sorting keybinds
- `--input-format csv` and `--input-format tsv`
- Column-specific filtering

**Done when:** `ps aux | pikl --input-format tsv --columns 1,10,2`
renders a clean table.

## Phase 6: Sessions & IPC

Persistence and external control.

**Deliverables:**
- `--session name` for state persistence
- Session state: filter, scroll position, selections,
  marks, registers
- Session history log file
- Unix socket IPC while running
- IPC commands: push/remove/update items, set filter,
  read selection, close
- Protocol: newline-delimited JSON

**Done when:** You can close and reopen a session and find
your state intact. External scripts can push items into a
running pikl instance.

## Phase 7: Streaming & Watched Sources

Live, dynamic menus.

**Deliverables:**
- Async/streaming stdin (items arrive over time, list
  updates progressively)
- Streaming output (on-hover events emitted to stdout)
- `--watch path` for file/directory watching
- `--watch-extensions` filter
- notify crate integration (inotify on Linux, FSEvents
  on macOS)

**Done when:** `find / -name '*.log' | pikl` populates
progressively. A watched directory updates the list live.

## Phase 8: GUI Frontend (Wayland + X11)

The graphical overlay.

**Deliverables:**
- pikl-gui crate with iced
- Wayland: layer-shell overlay via iced_layershell
- X11: override-redirect window or EWMH hints
- Auto-detection of Wayland vs X11 vs fallback to TUI
- `--mode gui` / `--mode tui` override
- Theming (TOML-based, a few built-in themes)
- Image/icon rendering in item list
- Preview pane (text + images)

**Done when:** pikl looks and feels like a native Wayland
overlay with keyboard-first interaction.

## Phase 9: Drill-Down & Groups

Hierarchical navigation.

**Deliverables:**
- `on-select` hook returning
  `{"action": "replace", "items": [...]}` for drill-down
- Backspace / `h` in normal mode to go back
- Navigation history stack
- Item groups with headers
- Tab to cycle groups
- `za` to collapse/expand groups

**Done when:** A file browser built on pikl-menu can
navigate directories without spawning new processes.

## Open Design Notes

- **Viewport cursor preservation on filter change.** When
  the filter narrows and the highlighted item is still in
  the result set, keep it highlighted (like fzf/rofi).
  When it's gone, fall back to the top. Needs the filter
  to report whether a specific original index survived the
  query, or the viewport to do a lookup after each filter
  pass.

- **Confirm-with-arguments (Shift+Enter).** Select an item
  and also pass free-text arguments alongside it. Primary
  use case: app launcher where you select `ls` and want to
  pass `-la` to it. The output would include both the
  selected item and the user-supplied arguments.

  Open questions:
  - UX flow: does the filter text become the args on
    Shift+Enter? Or does Shift+Enter open a second input
    field for args after selection? The filter-as-args
    approach is simpler but conflates filtering and
    argument input. A two-step flow (select, then type
    args) is cleaner but adds a mode.
  - Output format: separate field in the JSON output
    (`"args": "-la"`)? Second line on stdout? Appended to
    the label? Needs to be unambiguous for scripts.
  - Should regular Enter with a non-empty filter that
    matches exactly one item just confirm that item (current
    behaviour), or should it also treat any "extra" text
    as args? Probably not, too implicit.
  - Keybind: Shift+Enter is natural, but some terminals
    don't distinguish it from Enter. May need a fallback
    like Ctrl+Enter or a normal-mode keybind.

  This is a core feature (new keybind, new output field),
  not just a launcher script concern. Fits naturally after
  phase 4 (multi-select) since it's another selection
  mode variant. The launcher script would assemble
  `{selected} {args}` for execution.

## Future Ideas (Unscheduled)

These are things we've talked about or thought of. No
commitment, no order.

- Lua scripting frontend (mlua + LuaJIT): stateful/
  conditional automation, natural follow-on to action-fd
  and IPC. Lua runtime is just another frontend pushing
  Actions and subscribing to MenuEvents. Deliberately
  deferred until after IPC (phase 6) so the event/action
  API is battle-tested before exposing it to a scripting
  language. See "Scripting Ladder" in DESIGN.md.
- WASM plugin system for custom filter strategies
- `pcre2` feature flag for JIT-compiled regex
- Frecency sorting (track selection frequency, boost
  common picks)
- Manifest file format for reusable pikl configurations
- Sixel / kitty graphics protocol support in TUI mode
- Custom action keybinds (Ctrl+1 through Ctrl+9) with
  distinct exit codes
- Accessibility / screen reader support
- Sections as a first-class concept separate from groups
- Network input sources (HTTP, WebSocket)
- Shell completion generation (bash, zsh, fish)
- Man page generation
- Homebrew formula + AUR PKGBUILD
- App launcher use case: global hotkey opens pikl as GUI
  overlay, fuzzy-filters PATH binaries, launches selection
  (optionally into a tmux session). Needs GUI frontend
  (phase 8) and frecency sorting.
  See `docs/use-cases/app-launcher.md`.
  Setup guides: `docs/guides/app-launcher.md`.
- App description indexing: a tool or subcommand that
  builds a local cache of binary descriptions from man
  pages (`whatis`), .desktop file Comment fields, and
  macOS Info.plist data. Solves the "whatis is too slow
  to run per-keystroke" problem for the app launcher.
  Could be a `pikl index` subcommand or a standalone
  helper script.