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.