270 lines
8.6 KiB
Markdown
270 lines
8.6 KiB
Markdown
# 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`.
|