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.

Deliverables:

• JSON line input parsing (label, sublabel, meta, icon, group)
• JSON output with action context
• Full hook lifecycle: on-open, on-close, on-hover, on-select, on-cancel, on-filter
• Hook debouncing
• Bidirectional hooks (hook stdout modifies menu state)
• --format template strings for display
• Field filters (meta.res:3840)
• Filter scoping (--filter-fields)

Done when: The wallpaper picker use case works entirely through hooks and structured I/O.

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.

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.