radiantwave/Manual.md

# RadiantWave Kiosk — User Manual (Reference Draft)

> **Reference edition.** Every keybind, navigation path, screen behavior, and
> status message below is derived directly from the application source code.
> Use this as the checklist when writing the polished end-user manual.

**Input device:** physical keyboard only. No mouse or touchscreen. The cursor
is hidden. Text input uses the on-screen text-entry model (SDL text input).

---

## 0. Screen Map (UX Flow)

```
Power on
  └─ First-Run Walkthrough (if a prerequisite is missing)
       1. Internet reachable?  no  → WiFi Setup
       2. Email address set?   no  → Email Address
       3. License key set?     no  → License Key
       4. All satisfied            → Home
  └─ Home
       ├─ [Play] ────────────────────────────→ Scroller ──(ESC)──→ Home
       └─ [Settings] ────────────────────────→ Settings
             ├─ WiFi Setup            (ESC/TAB → Settings)
             ├─ Audio Options         (ESC/TAB → Settings)
             ├─ Time Zone Setup       (ESC/TAB → Settings)
             ├─ Proclamations         (ESC → Settings)   [license-gated]
             ├─ Email Address         (ESC/TAB → Settings)
             ├─ License Key           (ESC/TAB → Settings)
             ├─ Date Format           (ESC/TAB → Settings)
             ├─ View System Logs      (ESC/TAB → Settings)
             └─ Back to Home          → Home
```

When **Play** or **Proclamations** is selected but the license cannot be
verified, a **License Blocked** screen appears instead (ESC → Home).

The **Home** screen is the root of the whole UI. **TAB** is intended to return
to Home from anywhere (see the caveat in §12).

---

## 1. Global Controls

These binds are registered at startup (`main.cpp`) and are the only binds not
owned by a specific screen.

| Key | Action | Where it actually works |
| :--- | :--- | :--- |
| **`TAB`** | Return to the Home screen (pops every page on the stack and pushes a fresh Home). | Home; most screens also handle TAB locally (see per-screen tables) |
| **`UP` / `DOWN`** | Move the Home menu selection. **Both keys increment the same counter** — there is no separate "down" behavior; either key cycles Play ↔ Settings. | Home |

> **No key quits the application.** There is intentionally no quit keybind;
> the app is meant to run as a kiosk. (The underlying SDL window/system close
> path still exists, but no keyboard key triggers it.)

**Per-screen binds are checked before the screen sees key events.** A keybind
registered on the current screen is consumed by the keybind system; keys not
bound there fall through to the screen's own event handler.

---

## 2. Boot & First-Run Walkthrough

On every boot the app checks three prerequisites in a fixed order and shows the
**first** missing one (`provisioning.h`):

| # | Prerequisite | Screen shown if missing |
| :--- | :--- | :--- |
| 1 | Internet reachable (real connectivity probe — Ethernet, WiFi, or any OS link) | WiFi Setup |
| 2 | Email address saved | Email Address |
| 3 | License key saved | License Key |
| 4 | — | Home |

Walkthrough screens call "advance" when they finish or are backed out of, which
pops the current step and re-evaluates. Completing the WiFi page does **not**
re-run the internet probe (cached); the other steps only read the DB.

- A brand-new device (no internet, no email, no license) also raises an
  internal `firstRunWalkthrough` flag (a future welcome walkthrough; today it
  is only set and logged).
- If the database failed to open, the walkthrough is skipped entirely and the
  app goes straight to Home.
- On the WiFi page during the walkthrough, once the internet becomes reachable
  the page waits ~1.5 s ("Internet connected. Continuing setup...") and then
  advances automatically.
- On the Email and License pages, after a successful save the page waits ~1 s
  and then advances automatically.

---

## 3. Home

**Reached from:** app start, TAB, ESC on License Blocked, "Back to Home" in
Settings, ESC on the Scroller.

**Screen contents:**
- Centered "Radiant Wave" logo title.
- Two menu items: **Play** and **Settings** (white underline marks the
  selection).
- Bottom-right status footer (see §11).

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`UP`** | Cycle menu selection (Play → Settings → Play). |
| **`DOWN`** | Same as UP — cycles the selection the same way. |
| **`RETURN`** / **`ENTER`** | Activate the highlighted item. |
| **`TAB`** | Re-push Home (no visible change) (until a page is pushed on top of Home). |

> The **UP** and **DOWN** keys are wired identically (both increment the
> selection), so either arrow moves the highlight the same way; there is no
> dedicated "down" behavior. There is **no quit key** on Home.

**Behavior:**
- **Play** (item 0) with a confirmed-valid license → **Scroller**.
- **Play** with an invalid/unverifiable license → **License Blocked**.
- **Settings** (item 1) → replaces Home with **Settings**.
- The internet status refreshes automatically every 5 seconds while Home is
  shown. Play only unlocks when the license is valid (validated in the
  background; result shown in the footer).

---

## 4. Scroller (Play)

**Reached from:** Home → Play (license-gated).

**Screen contents:** full-screen, vertically scrolling proclamation text.
Proclamation text is never rendered as readable type — each glyph is permuted
into a scrambled tile by the Fibonacci affine map, so letterforms are
destroyed on screen. Lines follow the Fibonacci line-length pattern; colors
come from per-frequency palettes; audio crossfades between streams.

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`ESC`** | Exit back to Home. |

No other keys do anything on this screen. Scrolling speed ramps automatically
(up and down) with pauses at each extreme; there is no user speed control.

**Behavior:**
- Plays audio with a 5 s fade-in; on exit fades out over ~5 s.
- Dynamic Audio mode: the current stream's solfeggio-frequency track is
  crossfaded as proclamations change. Fixed-track mode: the configured track
  plays and never switches.
- If a stream's audio file is not on disk yet, playback falls back to the
  manual track rather than silence.

---

## 5. Settings

**Reached from:** Home → Settings. (Home is replaced, not stacked.)

**Screen contents:** title "Settings" and a 9-item menu:

| # | Item | Opens | License-gated? |
| :--- | :--- | :--- | :--- |
| 0 | WiFi Setup | WiFi Setup screen | no |
| 1 | Audio Options | Audio Options screen | no |
| 2 | Time Zone Setup | Time Zone Setup screen | no |
| 3 | Proclamations | Proclamation Options | **yes** (else License Blocked) |
| 4 | Email Address | Email Address screen | no |
| 5 | License Key | License Key screen | no |
| 6 | Date Format | Date Format screen | no |
| 7 | View System Logs | System Log Viewer | no |
| 8 | Back to Home | Home | — |

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`UP`** | Move selection up (wraps around). |
| **`DOWN`** | Move selection down (wraps around). |
| **`RETURN`** / **`ENTER`** | Open the highlighted item. |
| **`ESC`** | Return to Home (replaces Settings). |
| **`TAB`** | Return to Home. |

---

## 6. WiFi Setup

**Reached from:** Settings → WiFi Setup, or the First-Run walkthrough.

**Screen contents:**
- Title "WiFi Configuration".
- Status row: **WiFi: Connected/Disconnected** (green/red), **Network:
  \<SSID\>/None**, **Internet: Reachable/Unreachable** (green/red).
- Status message banner (blue-bordered): "Scanning for available
  networks...", "Connecting to \<SSID\>...", "Connected successfully!",
  "Connection failed: \<reason\>", "Password entry cancelled", etc.
- Network list (50 px rows). Color coding:
  - 🟢 **GREEN** — currently connected network.
  - 🟡 **YELLOW** — previously saved/remembered network.
  - ⚪ **WHITE** — new/unknown network.
  - Each row also shows a security badge `[Open]/[WPA/...]` and a signal
    strength percentage.
- Empty state: "No WiFi networks found. Press F5 to scan."
- Footer: `[UP/DOWN] Select   [ENTER] Connect   [F5] Rescan Networks   [ESC/TAB] Back`.

**Keybinds (normal mode):**

| Key | Action |
| :--- | :--- |
| **`UP`** | Select previous network. |
| **`DOWN`** | Select next network. |
| **`RETURN`** / **`ENTER`** | Connect. Open network → connects immediately. Secured network → opens the password box. |
| **`F5`** | Re-scan for networks. |
| **`ESC`** | Back (Settings, or walkthrough advance). |
| **`TAB`** | Back (same as ESC). |

**Password box (modal):**

| Key | Action |
| :--- | :--- |
| **type any keys** | Type the password (shown in plain text, unmasked, with a cursor). |
| **`BACKSPACE`** | Delete the last character. |
| **`RETURN`** / **`ENTER`** | Submit password and connect. |
| **`ESC`** | Cancel password entry (returns to the network list). |

Password modal footer: `[ENTER] Submit Password     [ESC] Cancel`.

**Behavior:**
- Connect is asynchronous. On completion: "Connected successfully!" or
  "Connection failed: \<error\>" (falls back to "Authentication or signal
  error").
- While a connection is in progress the list is locked.
- **Walkthrough only:** once internet is reachable, auto-advances after ~1.5 s.

---

## 7. Audio Options

**Reached from:** Settings → Audio Options.

**Screen contents:** title "Audio Configuration"; status row **Audio:
Enabled/Disabled** (green/red) and **Device: \<name\>**; status banner; 5-item
menu:

| # | Item | Interaction |
| :--- | :--- | :--- |
| 0 | Volume: `[▓▓▓▓▓▓▓▓░░] 80%` | LEFT/RIGHT step −/+ 5% (0–100, clamps). |
| 1 | Output Device: `[\<name\>]` | ENTER opens the Device selector modal. |
| 2 | Audio Track: `[\<name\>]` | ENTER opens the Track selector modal. |
| 3 | Audio Status: `[ON]`/`[OFF]` | ENTER toggles audio system-wide on/off. |
| 4 | Back to Settings | ENTER pops back to Settings. |

Footer: `[UP/DOWN] Select   [LEFT/RIGHT] Volume   [ENTER] Confirm   [ESC/TAB] Back`.

**Keybinds (main menu):**

| Key | Action |
| :--- | :--- |
| **`UP`** | Select previous item. |
| **`DOWN`** | Select next item. |
| **`LEFT`** | Volume −5% (only when Volume is highlighted). |
| **`RIGHT`** | Volume +5% (only when Volume is highlighted). |
| **`RETURN`** / **`ENTER`** | Open device/track modal, toggle audio, or Back. |
| **`ESC`** | Back to Settings (closes a modal first if one is open). |
| **`TAB`** | Back to Settings (only when no modal is open). |

**Device selector modal** — "Select Output Device":

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Move selection. |
| **`PAGE UP`** / **`PAGE DOWN`** | Jump selection by 8. |
| **`RETURN`** / **`ENTER`** | Switch to the highlighted device. |
| **`ESC`** | Cancel (no change). |

**Track selector modal** — "Select Audio Track":

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Move selection. |
| **`PAGE UP`** / **`PAGE DOWN`** | Jump selection by 8. |
| **`RETURN`** / **`ENTER`** | Select the highlighted option. |
| **`ESC`** | Cancel (no change). |

Modal footer: `[UP/DOWN] Select   [ENTER] Confirm   [ESC] Cancel`.

**Behavior:**
- The track list always leads with **Dynamic Audio** (cyan; "audio follows the
  displayed proclamation"), then **Original Audio** pinned first, then every
  other track sorted alphabetically. Up to 8 rows visible; the list scrolls
  and stays centered on the selection.
- Choosing a fixed track turns Dynamic Audio **off**. Choosing Dynamic Audio
  turns it on (status: "Dynamic Audio mode enabled - audio follows the
  displayed proclamation"). Choosing a track shows "Fixed track selected".
  Playback itself starts when the Scroller plays, not here.
- Device and track lists refresh automatically every 1 second.

---

## 8. Time Zone Setup

**Reached from:** Settings → Time Zone Setup.

**Screen contents:** title "Time Zone Configuration"; **Configured Timezone:
\<code\>** (yellow) and a live **Local Time:** sample (green); status banner;
then either a **country list** or a **timezone list** for the chosen country.
Green rows mark the currently configured country/zone; the white underline
marks the selection.

**Country step:**

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Select country/region. |
| **`RETURN`** / **`ENTER`** | Show that country's timezone list ("Select timezone for \<Country\>"). |
| **`ESC`** / **`TAB`** / **`BACKSPACE`** | Back to Settings. |

**Timezone step:**

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Select a timezone. |
| **`RETURN`** / **`ENTER`** | Save the timezone (status "Timezone set to \<code\>") and return to the country list. |
| **`ESC`** / **`BACKSPACE`** / **`TAB`** | Back to the country list. |

Footers:
- Country: `[UP/DOWN] Select Country    [ENTER] Choose    [ESC/TAB] Back to Settings`
- Timezone: `[UP/DOWN] Select Timezone    [ENTER] Apply Timezone    [ESC/BACKSPACE] Back to Countries`

**Behavior:** the saved timezone is written to the live config immediately;
logs and the Home clock use it right away.

---

## 9. Proclamations

**Reached from:** Settings → Proclamations (license-gated; else License
Blocked).

**Screen contents:** title "Proclamation Options"; status line (sync result +
"Selected: N"); an optional **search bar** while searching; a collapsible
category tree (or a flat search-result list); footer hints.

**Colors:** categories blue; selected proclamations orange; the always-on
top-level proclamation orange; locked (above your subscription) rows flash
**red**; search text yellow.

**Keybinds (browse mode):**

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Move highlight. |
| **`RETURN`** / **`ENTER`** | Toggle the highlighted row: expand/collapse a category, or select/deselect a proclamation. |
| **`LEFT`** | Collapse the highlighted category; if the row is a sub-item, jump to its parent. |
| **`RIGHT`** | Expand the highlighted category. |
| **`PAGE UP`** / **`PAGE DOWN`** | Scroll by a page. |
| **`CTRL` + `D`** | Clear all selections (the top-level proclamation stays on). |
| **type any printable character** | Enter search mode. |
| **`ESC`** | Back to Settings. |

**Search mode:**

| Key | Action |
| :--- | :--- |
| **type any printable character** | Add to the search query (word-prefix match on title + content). |
| **`BACKSPACE`** | Delete the last query character; when the query empties, search mode closes. |
| **`UP`** / **`DOWN`** | Move highlight. |
| **`RETURN`** / **`ENTER`** | Toggle the highlighted result. |
| **`ESC`** | Cancel search and return to the browse tree. |

Footers:
- Browse: `[UP/DOWN] Move    [ENTER] Toggle    [Type to Search]    [LEFT/RIGHT] Expand/Collapse    [CTRL+D] Clear All    [ESC] Back`
- Search: `[UP/DOWN] Move    [ENTER] Select    [BACKSPACE] Edit    [ESC] Cancel Search`

**Behavior:**
- On open the app syncs the list with the server: "Synced with server" or
  "Offline - showing saved proclamations". The "Selected: N" count on the
  status line excludes the always-on top-level proclamation.
- The top-level proclamation ("Synchronize, Harmonize & Energize") is **always
  on** and cannot be deselected ("The top-level proclamation is always on").
- Selecting a proclamation whose required subscription level is above the one
  attached to your license key is rejected: the row flashes red and a status
  line explains it's "available on \<Level\> systems".
- A bare **SPACE** does not open search and never selects anything; in search
  mode SPACE types a space into the query.
- **TAB is NOT handled on this screen** — use ESC to go back.

---

## 10. Email Address, License Key, Date Format

### 10.1 Email Address

**Reached from:** Settings → Email Address, or the walkthrough.

**Screen contents:** title "Email Address"; "Saved: \<address\>" (gray = not
set, yellow = set); input box with cursor; status line; footer.

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **type any keys** | Type/edit the email (up to 254 chars). |
| **`BACKSPACE`** | Delete the last character. |
| **`RETURN`** / **`ENTER`** | Save. Empty input clears the saved address ("Cleared"). Invalid address shows "Invalid email address". Valid save shows "Saved". |
| **`ESC`** | Back without saving (Settings, or walkthrough advance). |
| **`TAB`** | Back (same as ESC). |

- After a successful save/clear, the page auto-exits after ~1 s.
- Footer: `[Type] Enter email    [ENTER] Save    [BACKSPACE] Delete    [ESC/TAB] Back`.

### 10.2 License Key

**Reached from:** Settings → License Key, or the walkthrough.

**Screen contents:** title "License Key"; "Saved: \<key\>" (gray/yellow); input
box showing the key formatted `XXXX-XXXX-XXXX-XXXX`; status line; footer.

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **type any keys** | Type the key. Only alphanumerics are accepted (uppercased); max 16 characters. Dashes are added automatically for display. |
| **`BACKSPACE`** | Delete the last character. |
| **`RETURN`** / **`ENTER`** | Save and validate. |
| **`ESC`** | Back without saving (Settings, or walkthrough advance). |
| **`TAB`** | Back (same as ESC). |

**Validation statuses on ENTER:**
- Fewer than 16 characters → "License key must be 16 characters
  (XXXX-XXXX-XXXX-XXXX)".
- Save failed → "Failed to save license key".
- Server validated → "License validated (\<level\>)".
- Missing email → "Saved - add your email address to validate the license".
- Invalid → "License check failed: \<reason\>".
- No network → "License saved, but the server could not be reached to
  validate".

- Auto-exits after ~1 s once saved.
- Footer: `[Type] Enter key (dashes added automatically)    [ENTER] Save    [BACKSPACE] Delete    [ESC/TAB] Back`.

### 10.3 Date Format

**Reached from:** Settings → Date Format.

**Screen contents:** title "Date Format"; "Today looks like: \<example\>"
(yellow); 7 format options each with a live sample date; status line; footer.

**Format options:** Month/Day/Year, Day/Month/Year, Year-Month-Day,
Month.Day.Year, Day.Month.Year, "Month Day, Year", "Day Month Year".

> The option currently in use is shown in yellow, the others in white; every
> option's live sample date is gray.

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Choose a format. |
| **`RETURN`** / **`ENTER`** | Apply the format and return to Settings ("Date format saved"). |
| **`ESC`** | Back without saving. |
| **`TAB`** | Back (same as ESC). |

- Footer: `[UP/DOWN] Choose    [ENTER] Apply & Back    [ESC/TAB] Back`.

---

## 11. System Log Viewer

**Reached from:** Settings → View System Logs.

**Screen contents:** title "System Event Log Viewer"; header bar showing
**Filter: \<level\> | Sort: Newest/Oldest First | Entries: N | TZ: \<code\>**;
word-wrapped log lines (color-coded by severity) with local-time timestamps;
footer.

**Log line colors:** DEBUG gray, INFO white, WARNING yellow, ERROR red,
FATAL magenta/pink.

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`UP`** / **`DOWN`** | Scroll one line. |
| **`PAGE UP`** / **`PAGE DOWN`** | Scroll 10 lines. |
| **`L`** or **`F2`** or **`RIGHT`** | Cycle the filter level forward: ALL → DEBUG → INFO → WARNING → ERROR → FATAL. |
| **`LEFT`** | Cycle the filter level backward. |
| **`S`** or **`F3`** | Toggle sort order: Newest First ↔ Oldest First. |
| **`C`** | Clear all log history. |
| **`ESC`** | Back to Settings. |
| **`TAB`** | Back (same as ESC). |

- Footer: `[UP/DOWN] Scroll   [L/F2] Filter Level   [S/F3] Sort Order   [C] Clear Logs   [ESC/TAB] Back`.
- The log list auto-refreshes every 0.25 s while the screen is open.

---

## 12. License Blocked Screen

**Reached from:** Play or Settings → Proclamations when the license cannot be
verified.

**Screen contents:** centered message "License could not be verified",
instruction text ("Please check that you are connected to the internet, and
double check your license key and email address."), and "Press ESC to return."

**Keybinds:**

| Key | Action |
| :--- | :--- |
| **`ESC`** | Return to Home (pops every page and pushes a fresh Home). |

---

## 13. Home Status Footer (legend)

The bottom-right corner of Home shows a two-column readout:

| Field | Meaning / values |
| :--- | :--- |
| **License:** | `OK` (green) · `Invalid` (red, bold) · `Checking...` · `Unknown` |
| **Key:** | saved license key, or `Not set` |
| **Email:** | saved email, or `Not set` |
| **Subscription:** | subscription level name from the license, or `Not set` |
| **WiFi:** | current SSID, or `Not connected` |
| **Internet:** | `Connected` / `Offline` |
| **Audio:** | audio-downloader status string, or `Idle` |
| **Date:** | formatted per the selected date format |
| **Time:** | `HH:MM:SS` (24-hour) |

Internet status refreshes every 5 s while Home is shown; the license check
re-runs in the background each time Home appears.

---

## 14. Data & Configuration (background)

- **`~/.local/radiantwave/config.yaml`** — settings (audio volume, output
  device, current track, dynamic audio, timezone, proclamation font size).
  Saved automatically. **Hot-reloaded live**: editing it while the app runs
  applies immediately without a restart.
- **`~/.local/radiantwave/radiantwave.db`** (SQLite, WAL) — email, license key,
  subscription level, license last-verified timestamp, proclamation/category
  data, audio file records, system log history.
- **Audio assets** (`.wav` files) are downloaded in the background on first
  connect and stored under `~/.local/radiantwave/audio/`; they are not part of
  the app install.
- License checks run online; a known-good license stays valid for a **7-day
  offline grace window**.

---

## 15. Implementation Notes / Caveats (for the manual author)

These are behaviors visible in the source that differ from the "intended"
controls, so you can decide how to document or fix them:

1. **TAB (Home) is registered once at startup and is removed whenever any page
   pauses** (every page calls `keybinds.unbindAll()` in `onPause`, and Home
   only re-binds UP/DOWN in `onResume`). In practice **TAB returns Home
   reliably only on the Home screen, and only until you first push a page on
   top of it — popping back to Home does not restore it**. Screens that handle
   TAB locally (Settings, WiFi, Audio, Email, License, Date Format, Log
   Viewer) keep working; the Scroller, Proclamations, and License Blocked do
   not respond to TAB.
2. **Home's UP and DOWN both move the selection the same direction** — both
   call `(x+1)%2`. There is no down-only arrow behavior.
3. **Proclamation page and Scroller have no TAB handler** — only ESC returns
   from the Proclamation page / Scroller.
4. **TAB on the Time Zone page behaves differently per step**: in the
   country list it exits to Settings; in the timezone list it returns to the
   country list.
5. The walkthrough's WiFi page auto-advances as soon as internet is reachable
   (≈1.5 s), and the Email/License pages auto-advance ≈1 s after a successful
   save — the walkthrough can never be completed by pressing Enter alone on a
   connected device.