trainlog/docs/tui.md

Desktop TUI

1. Purpose

The Trainlog desktop application is a C17/ncursesw interface for durable history, correction, analysis, visualization, direct data entry, and manual synchronization.

Desktop SQLite is the canonical long-term history.

2. Navigation

Large-layout primary navigation:

0 Accueil
1 Séance
2 Historique
3 Exercices
4 Corps
5 Sync

Direct shortcuts include the matching function keys where implemented.

Common controls:

↑ ↓            list navigation
Enter          open/activate
Tab            change focus on multi-zone pages
Esc / b        return or cancel
0 / Home       dashboard
q              quit from the application shell

Minimum terminal size:

72x20

Smaller terminals display a clear fallback instead of corrupt layout.

3. Visual rules

The TUI uses centralized semantic theme roles.

Color is not the sole state carrier.

Typical roles:

accent
success
warning
error
muted
graph series

Focused frames use the warning role for border/title without recoloring all content.

4. Exercise catalog

Exercise behavior is driven by:

recording_mode
tracking_mode
data_fields

No exercise-name heuristic determines an entry form.

Catalog identities are stable.

Unicode-aware normalized-name uniqueness prevents duplicate logical names.

5. Session entry

The TUI can record sessions directly.

Set-based entry supports planned targets and actual work.

For repetition work, compact actual-set input supports:

5x10
4,5,6,7,8,9,10,9,8,7,6,5,4
4..10..4

For timed work, the shared duration parser accepts forms such as:

90
90s
1:30
1m30
1m30s
2m

Persistent duration/rest units remain seconds.

Continuous exercise entry asks for duration and configured supplemental fields without set/rest/load prompts.

6. Session history and editing

History is keyboard navigable.

Enter opens full session detail.

Persisted session editing preserves the parent session identity and timestamps while replacing child exercise/set data transactionally.

Inside editable session exercise lists:

d   delete selected exercise from the session

A failed replacement rolls back completely.

Removing an exercise from one session does not remove the exercise from the catalog.

7. Body tracking

4 Corps / F4 provides:

• newest-first body observations;
• detail and correction;
• body trend visualization;
• normalized multi-metric overlay;
• left/right metric separation;
• no invented zero values for missing measurements.

Editing preserves observation identity, timestamp, and optional session link.

8. Dashboard

The dashboard includes a rolling 12-month normalized body graph.

Rules include:

• fixed calendar month slots;
• missing months remain empty;
• no zero fill;
• no interpolation;
• when multiple observations exist in one month, the last visible monthly value is used for the compact dashboard graph.

Detailed raw observations remain in Corps.

9. Exercise performance

Exercise detail exposes recorded performance history.

Representative comparison semantics:

load none
    greatest successful reps/duration

external
    greatest actual load
    tie -> greatest reps/duration

assistance
    lowest assistance
    tie -> greatest reps/duration

A best recorded set is not automatically a measured maximum.

10. Sync page

5 Sync / F5 uses the shared synchronization engine.

The page shows:

• connected MTP device status;
• storage availability;
• structured synchronization history.

Manual action:

s   run bidirectional synchronization
r   refresh device status

History behaves like a compact Git log:

↑ ↓       select run
Enter     open run detail

The detail view behaves like a compact git show and contains:

sync ID
trigger
time
status
request ID when applicable
Android -> PC counts
PC -> Android catalog count
summary
error when applicable

11. Shared sync engine

The TUI does not own a separate synchronization implementation.

It calls:

trainlog_sync_run(TRAINLOG_SYNC_TRIGGER_TUI, ...)

The Android-triggered daemon calls the same engine.

This keeps import/export, MTP publication, locking, history, and diagnostics in one implementation.

12. Direct MTP

Transport uses:

libudev -> exact physical USB device
libmtp  -> storage/object operations

No filesystem mount is required.

Raw libmtp output is suppressed while ncurses owns the terminal.

13. Error behavior

Input is validated before persistent mutation.

Escape cancels prompts without committing partial edits.

Synchronization failure displays a useful final diagnostic and records the structured run when a transaction actually begins.

14. Build and test

meson compile -C build
meson test -C build --print-errorlogs

Current normal suite:

19/19 PASS