looper/client/PLAN.md

Plan: Refactor TUI into Standalone FIFO‑Client Binary

Goal

Extract the TUI from the existing monolithic codebase into a separate looper-client binary that communicates with the engine only via the FIFO pipe (/tmp/looper_cmd).
The TUI must not link to any engine source files (engine.c, dispatcher.c, carla.c, etc.) or use their headers beyond shared type definitions (e.g., command.h). All state is maintained by the engine; the TUI sends commands and assumes they succeed.

Background

• The looper engine runs as a separate JACK client and listens for commands on:
  • FIFO pipe (/tmp/looper_cmd) – text‑based commands
  • looper:control – MIDI note‑on events
• The current TUI uses a local Engine / AppState / dispatcher that does not talk to the real looper. It was designed for unit testing.

Task 1 – Create a new client/ directory structure

• Keep existing client/src/tui.c and client/src/tui.h.
• Remove all #include directives that reference engine internal headers:
  • engine.h
  • dispatcher.h
  • wav_io.h
  • transport.h
  • carla.h
• Remove any Engine*, AppState, DispatchFn, Clip, MidiClip usage.
• Keep the FuzzySearch struct, draw_rack_view(), handle_rack_view(), list_wav_files(), load_sample_callback, mouse handling, etc. – they are not removed.
  However, every call to engine internals (e.g., carla_get_available_plugins, dispatcher_get_state, g_dispatch, carla.h functions) must be replaced with a stub that does nothing (or prints a debug message) until the engine implements the corresponding FIFO commands.
  This keeps the UI code compilable and preserves the structure for future implementation.

Task 2 – Implement send_command() and open FIFO

• Add a function:

  int send_command(const char *cmd_line);
  

  This function:

  • Opens /tmp/looper_cmd with O_WRONLY.
  • Writes the command string (e.g., "record 0\n").
  • Appends a newline if missing.
  • Closes the file descriptor.
  • Returns 0 on success, -1 on error (prints diagnostic to stderr).

• The TUI should call send_command() for every user action that should affect the engine.

Task 3 – Map TUI keys to FIFO commands

Replace each g_dispatch(action) with a direct FIFO command string.

Proposed mapping (simplified – can be refined later):

TUI key/action	FIFO command
't' (trigger clip at selected cell)	record <channel>\n (channel = selected_col)
'd' (reset clip)	stop\n (global stop)
's' (trigger scene – current row)	"scene_next\n" (or "scene_add\n"? TBD)
' ' (toggle transport play/pause)	No corresponding FIFO command yet. Omit for now.
'S' (stop transport)	"stop\n"
'q' (cycle quantize)	No FIFO equivalent – ignore.
'x' (reset transport)	"stop\n"
'N' (play next scene)	"scene_next\n"
'P' (play previous scene)	"scene_prev\n"
'u' (undo)	No FIFO equivalent – ignore.
Ctrl+R (redo)	Ignore.
'v', 'V' (visual mode)	Keep visual selection logic but send commands only for 'd' and 'y' actions.
'y' (yank)	Do nothing (local clipboard only).
'p' (paste)	For each pasted cell send "record <ch>\n".
'm' (move mode)	No effect on engine – local navigation.
'z' (zoom grid selector)	Local navigation only.
'G' (toggle audio/MIDI grid)	No FIFO command – ignore.
'-' / '=' (volume)	No FIFO command – ignore.
\t (switch to rack view)	Remove entirely.
':' command mode	Keep for :q (quit) and :rack commands (the latter can be removed).
Escape / 'Q'	Quit the TUI (no command sent).

Channel binding:

• When the user moves selection to a new column, send "bind <col>\n" to ensure subsequent commands affect the correct channel. This can be done in the navigation switch cases.

Task 4 – Remove all references to Engine and dispatcher

• Delete the lines:
  • static Engine *g_engine = NULL;
  • static DispatchFn g_dispatch = NULL;
• Replace calls like g_dispatch(action) with send_command(formatted_string).
• Remove dispatcher_get_state() calls – the TUI will no longer query the engine state. Update draw_cell() to display only static info (clip index) or a fixed colour (e.g., all green). The state‑dependent colouring is not available without feedback from the engine. For now, show all cells as idle (white) or use a placeholder.
• Remove the line AppState state; dispatcher_get_state(&state); inside draw functions.

Task 5 – Simplify the tui.h header

• Replace the function signatures:

  void tui_init(void);          // no Engine* argument
  void tui_run(void);           // no Engine* argument
  void tui_cleanup(void);
  

• Remove #include "engine.h" and #include "dispatcher.h".

• Remove the Engine* parameter from the init and run functions.

Task 6 – Create client/main.c

• Write a simple main() that:
  • Optionally opens the FIFO for writing just to check it exists.
  • Calls tui_init().
  • Calls tui_run().
  • Calls tui_cleanup().
  • Returns 0.

Task 7 – Write client/makefile

• Target looper-client:
  • Compile src/tui.c and src/main.c (or src/client.c if split).
  • Do not link to any engine .o files.
  • Link only with -lncurses (and -lm if needed).
  • Example:

    CC ?= gcc
    CFLAGS ?= -Wall -Wextra -g -I../engine/src
    LDFLAGS ?= -lncurses -lm
    
    looper-client: src/tui.c src/main.c
    	$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS)
    

Task 8 – Remove dead code and unnecessary helpers

• Delete utils.c / utils.h if they existed only for TUI – but keep all WAV‑related, rack‑related, and fuzzy‑search code (they are now stubs).
• Remove clip_state_to_string(), transport_state_to_string(), quantize_mode_to_string(), clock_source_to_string() – they are no longer used for display because we have no AppState.
  Replace them with static strings that show placeholder text (e.g., "N/A").
• Remove state_to_color() – instead use a fixed colour pair (e.g., all cells white) or remove colour entirely, because we have no clip state.
• Remove the mouse callback if it relied on dispatcher_get_state – but keep the function body as a no‑op.

Task 9 – Test the new client

• Build looper-client and verify it compiles without engine object files.
• Start the engine (./looper in engine/).
• Run ./looper-client and press keys that should generate FIFO commands. Use cat /tmp/looper_cmd in another terminal to verify output.
• Check that commands like record 2, stop, bind 3 appear.

Notes / Future Improvements

• State feedback: The TUI currently shows clip state colours. To restore that, a separate FIFO (or shared memory) for engine‑>client status could be added. Not part of this plan.
• MIDI grid / rack view: These depend on engine features not yet exposed via FIFO. They are removed; can be re‑added later.
• Transport commands: The engine does not have a dedicated transport play/pause command via FIFO; it relies on MIDI notes. Future FIFO extension needed.

This plan produces a clean, minimal client that interfaces only through the named pipe.