# Desktop TUI ## 1. Purpose The Trainlog desktop application is a C17/Notcurses interface for durable history, correction, analysis, visualization, direct data entry, and manual synchronization. Desktop SQLite is the canonical long-term history. ## 2. APP_SHELL_V1 navigation The persistent shell has seven root sections: ```text Accueil | Séances | Exercices | Équipements | Statistiques | Synchronisation | Paramètres ``` `Séances` contains **Séance en cours**, **Programmer une séance**, **Nouvelle séance manuelle**, and **Séances effectuées**. The latter replaces the former top-level Historique entry. Existing mensurations, body graphs/analysis, exercise performance and explicit MAX views are reached through `Statistiques`; this relocation adds no statistic or analytical interpretation. The geometry policy is exact: ```text under 72x20 small-terminal fallback 72x20 or larger usable compact shell with temporary Navigation control 100x26 or larger visible sidebar 120x32 or larger expanded sidebar ``` The terminal owns a run-scoped application context with persistent header, content, sidebar when present, and two-line footer planes. It has a single event loop; planes are rendering resources, not application state. Resize recomputes the layout and preserves the route, stable list selection and a visible equivalent focus target. A sidebar focus becomes the compact Navigation control when the sidebar disappears. Common controls: ```text ↑ ↓ list navigation Enter open/activate Tab / Shift+Tab cycle rendered focus targets F6 open Navigation F7 open the route's action registry Esc / b return, cancel, or close/restore an overlay 0 / Home Accueil 1/F1 … 5/F5 manual session, completed sessions, exercises, equipment, mensurations 6 Synchronisation q quit from the application shell ``` The root aliases and contextual actions are built from one action registry: the footer and F7 therefore advertise the same enabled actions that dispatch. The intentional APP_SHELL_V1 shortcut changes are the replacement of the old top-level Historique/Corps aliases by `2/F2 Séances effectuées` and `5/F5 Mensurations`, F6 Navigation and F7 Actions, as approved in design §13. A route alias is ignored while an overlay is active; a local editor owns its keys before shell aliases. On an exercise detail, `F7 Actions` exposes `Fusionner avec…`. The current exercise is the source; a bounded UTF-8 search overlay selects the canonical target. A second overlay previews the explicit source → canonical direction and the occurrence-owned data preserved by the transaction. Profile or primary-zone conflicts leave both exercises untouched and show a specific result. After success, the canonical target remains selected. Minimum terminal size: ```text 72x20 ``` Smaller terminals display a clear fallback instead of corrupt layout. ## 3. Visual rules The TUI uses centralized semantic theme roles. Notcurses provides a true-color Catppuccin-derived dark palette: background `#1E1E2E`, surface `#181825`, text `#CDD6F4`, and semantic accent, success, warning, error, muted, and graph roles. Unicode frames and visible selection markers enhance presentation without becoming application semantics. The backend owns run-scoped planes, translates terminal input into Trainlog-owned keys, and accepts complete UTF-8 code points in bounded shell editors without a runtime parser or `ncreader`. Search/form storage is capped at 200 UTF-8 bytes plus NUL, rejects invalid or partial code points without partial mutation, and keeps grapheme boundaries while moving or deleting. Escape clears a non-empty search before closing an empty search. Filtered lists retain selection by stable ID and report bounded page availability. Input lifecycle is handled at that boundary: legacy/unknown terminal events, Notcurses PRESS events, and deliberate auto-REPEAT events become one logical Trainlog action; Notcurses RELEASE events are consumed and never reach screen navigation or prompt handling. This prevents extended terminal keyboard protocols from applying one physical keypress twice. Color is not the sole state carrier. Typical roles: ```text accent success warning error muted graph series ``` Focused frames use the focus semantic role without recoloring all content. The palette uses synchronized semantic RGB role tokens; an optional Nerd Font may improve symbols, while text fallbacks are mandatory. ## 4. Exercise catalog Exercise behavior is driven by: ```text 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. `3 Exercices` also owns Body Zones V1. Creation opens a keyboard-only manifest selector: `p` chooses the sole primary, Space toggles secondaries, `n` selects the explicit unclassified state and clears all relations, Enter validates and Escape cancels without mutation. Only French display names are shown; stable IDs such as `chest` remain internal. New set-based exercises require a primary zone. The exercise list supports `/` prefix search and `z` cycling through all manifest zones plus **Non renseignés**; `x` clears search and zone filter. Parent filters include descendants, so **Membres supérieurs** finds direct chest/back/ shoulders/arms relations without stored parent rows. Search and filter combine. Exercise detail displays the primary, ordered secondaries and the primary's derived group. `e` edits name and zones transactionally; Escape at either edit prompt leaves the durable row unchanged. ## 5. Session entry The TUI can record sessions directly. Set-based entry supports planned targets and actual work. Planned target values remain planning metadata: they are never copied into an actual performed set. For a normal `SETS` occurrence, creation collects planning metadata only: it does not accept a compact performed-repetitions expression, a performed set count, sequential performed durations, or a pre-table performed load. It starts with zero actual rows, then opens the ordered, keyboard-first actual-set table as the sole path for creating actual work. Each row contains its actual repetitions (or duration) and, when the occurrence has a load mode, its independently optional Charge or Assistance value. The table uses: ```text Up/Down select a row Left/Right/Tab select metric or load cell Enter edit the selected cell a append a row and enter its required actual metric d/Delete delete the selected set Escape cancel the active cell, or leave the table f/b finish the table ``` Adding a row requires an explicit actual repetitions/duration value and creates no actual load; an empty load cell remains absent rather than inheriting the target. An entered actual load is finite and non-negative; the planned target remains a separate, strictly positive planning value. The current-session summary is assembled from each actual row, so mixed repetitions, optional loads and assistance values are not collapsed into one target value. Finishing a normal `SETS` draft with zero actual rows is blocked with an explicit diagnostic. This guard does not apply to `MAX` or continuous entries, whose distinct persistence contracts contain no performed-set rows. For timed work, the shared duration parser accepts forms such as: ```text 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. ### Session generator On the dashboard, `g` opens the generator. It selects a policy BODY ZONE, goal and duration, captures one explicit reference time, and renders a SQLite-free preview containing target sets/repetitions, optional observed load/source, rest, equipment, primary zone, patterns, exposure and shortage reasons. Preview, resize and cancel write nothing. A generator result with no exercise cannot enter persistence; a nonempty partial result remains editable with its warnings visible. Accepting a preview builds the ordinary normal session draft with zero actual rows and enters the existing editor. The existing completion guard still requires actual rows for every SETS exercise. The preview and ordinary plan editor preserve direct kg and no-target entry and also expose a `%MAX` calculator. It accepts only integers 1..100 and only the chronologically latest explicit MAX for the exact exercise/equipment external- resistance context. Assistance is unavailable. The formula is `MAX × percentage / 100`; it is not a recommendation, and only the resulting `target_weight_kg` is retained when the draft is accepted. In the generator, `u` restores automatic V1 load qualification, `%` selects the calculator and `x` selects no numeric target. The preview labels these outcomes `user_selected_max_percentage` or `compatible_max_unavailable` and clears a calculated target if its equipment context changes. Generator duration is labelled as a target alongside the estimate. A meaningful shortfall is reported without padding, and V1 states explicitly that it generates neither warm-up nor cool-down. Multi-session/program work remains future `SESSION_GENERATOR_V2`; it is not implemented by these controls. ## 6. Session history and editing History is keyboard navigable. `Enter` opens full session detail. For set-based occurrences, detail displays an ordered, scrollable table of the persisted rows with series number, repetitions or duration, and Charge or Assistance. It exposes every stored per-set value, including absent loads, rather than only a compact aggregate. Persisted session editing preserves the parent session identity and timestamps while replacing child exercise/set data transactionally. Inside editable session exercise lists: ```text 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. Equipment `Équipements` (direct alias `4/F4`) provides supplied-equipment browsing, search, detail, and custom-equipment creation and selection. Supplied definitions are generated from `catalog/equipment-v1.json`; user-created definitions persist in desktop SQLite and synchronize separately through definitions V1. Equipment can be selected while editing an exercise occurrence. Session detail, exercise history, and historical occurrence views resolve an `equipment_id` against the supplied manifest or a local custom definition. If an historic ID is no longer resolvable, the view shows that unknown reference explicitly. Session detail displays the selected occurrence's stable `entry_id` together with its resolved equipment, so repeated appearances of one exercise remain visibly distinct; `i` opens the resolved equipment detail. ## 8. Body tracking `Statistiques → Mensurations` (direct alias `5/F5`) 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. ## 9. Statistics and dashboard The rolling 12-month normalized body graph has moved from the dashboard to `Statistiques → Mensurations`; its data rules are unchanged. 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 twelve-month graph. Detailed raw observations remain in `Statistiques → Mensurations`. ## 10. Exercise performance Exercise detail exposes recorded performance history. Representative comparison semantics: ```text 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. ## 11. Sync page `6 Sync` uses the shared synchronization engine. The supported shortcut is the numeric `6` key. The page shows: - connected MTP device status; - storage availability; - structured synchronization history. Manual action: ```text a run Android -> PC synchronization p run PC -> Android synchronization b run bidirectional synchronization r refresh device status ``` `a` imports definitions V1, mobile V3, the body-zone companion and associations V2 only. `p` publishes definitions V1, catalog V1, the body-zone companion, mobile V3 (including body observations), and associations V2 only. `b` completes that inbound sequence before beginning the outbound sequence. The direction keys are direct actions: pressing `a`, `p`, or `b` opens one confirmation for that exact direction; there is no separate mode-selection step. `Enter` accepts the pending action and can invoke the shared engine only once. `Esc` cancels a pending confirmation without an operation; when no confirmation is pending, `Esc` returns from Sync. `r` only refreshes connected device status. The former `s` synchronization shortcut is retired and inert. The footer states the same contract in both layouts. At 100 columns or wider it reads `a Android→PC p PC→Android b PC↔Android r actualiser Échap retour`; the compact footer uses `a A→PC p PC→A b A↔PC r act. Échap retour` without changing any action or direction. Before a confirmed run, Sync identifies the selected direction in its progress feedback. It then shows the completed run summary on success, or a direction-prefixed diagnostic on failure. Each structured local history run persists its selected `a`, `p`, or `b` direction, and the history list displays that direction label alongside its summary. `direction inconnue` is used only for a legacy entry whose direction was never recorded, rather than being guessed. History behaves like a compact Git log: ```text ↑ ↓ select run Enter open run detail ``` The detail view behaves like a compact `git show` and contains: ```text sync ID trigger time status request ID when applicable Android -> PC counts PC -> Android catalog count summary error when applicable ``` ## 12. Shared sync engine The TUI does not own a separate synchronization implementation. It calls: ```text 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. ## 13. Direct MTP Transport uses: ```text libudev -> exact physical USB device libmtp -> storage/object operations ``` No filesystem mount is required. Raw libmtp output is suppressed while Notcurses owns the terminal. ## 14. 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. Conflict diagnostics identify the stable affected identity, the source artifact/direction, and a concise source summary. They preserve existing session, body-observation, association, and definition data rather than silently overwriting it. ## 15. Build and test ```bash meson compile -C build meson test -C build --print-errorlogs ``` Validated current normal suite: ```text 39/39 Meson tests PASS ``` ## 16. Measured max view Creating or editing a `Test de max` session uses the existing exercise search and optional equipment selector, then asks only for `Poids max (kg)`. It does not prompt for sets or repetitions and persists the value in `max_results`. The history detail for a max-test session is a compact selectable table: ```text Exercice Machine Max Pec Fly Rear Delt / Pec Fly 100 kg Rear Delt Fly Rear Delt / Pec Fly 86 kg ``` Equipment is occurrence context. The rows remain distinct by movement and stable `entry_id`; no machine-level maximum is calculated. A preserved non-MAX entry, such as continuous warm-up, remains visible with `—` in the MAX column. From `3 Exercices`, the selected exercise exposes: ```text Enter ordinary performance history m measured max ``` The measured-max page is deliberately separate from ordinary best-set history. It shows: - count of explicit max-test sessions; - newest successful measured result; - best historical result using the same load mode; - dedicated max-test graph; - max-test history; - external-load working percentages at 60%, 70%, 80%, and 90%. For external load, `r` cycles practical rounding increments: ```text 0.5 kg 1.0 kg 2.5 kg 5.0 kg ``` Working percentages are display calculations only. Assistance remains inverse-direction: ```text less assistance = better ``` No percentage-of-max working load is produced for assistance or no-load performance. ## 17. Body analytics `Statistiques → Mensurations` adds: ```text v analyse corporelle ``` The analytics view has two pages: ```text Composition et tendance Proportions et symétrie ``` `p` configures a desktop-only estimation profile containing height and the circumference-formula branch. Composition can display: - circumference-based body-fat estimate; - estimated fat mass when body weight is present; - estimated lean mass when body weight is present; - weight change from the oldest available weight; - waist change from the oldest available waist; - body-fat estimate change when comparable observations exist. Proportions can display: - waist/hip ratio; - shoulder/waist ratio; - chest/waist ratio; - left/right asymmetry for arms, forearms, thighs, and calves. All estimates are explicitly labeled as estimates. No result is converted into a medical or diagnostic classification. ## 18. Training knowledge infrastructure The desktop core includes immutable `training_knowledge.h` catalog access and read-only `training_context.h` composition. The context uses real persisted IDs and returns persisted zones, optional science, compatible equipment, latest explicit MAX and bounded chronological history; it does not write data. The TUI provides a UTF-8 cell-aware scrolling knowledge screen, tested at the 72x20 minimum terminal. V1 provides no prescription, generator or scoring flow. Its lifecycle is `TRAINING_KNOWLEDGE_V1=PASS`. Its occurrence and latest-MAX readers use the settled temporal contract: exact instant/fraction ordering, bytewise stable-ID ties, exclusive source-text cursors, bounded selection before hydration, and one read snapshot per call. Malformed cursors and matching stored timestamps fail explicitly. The full-tranche audit repair chain and independent verification passed. See [Training knowledge system V1](domain/knowledge_system.md).