#pragma once
// gamebook — "livre dont vous êtes le héros" mode for the Freenove master.
//
// Reads /sdcard/gamebook/gamebook.json (built by tools/gamebook/build_gamebook.py),
// plays each passage's WAV narration from the SD via media_manager, shows the
// passage title + choice menu on the display, and navigates with the 5-way pad
// (it installs a display_ui key hook so it owns the buttons while active).
// Fully local: no model, no gateway.
//
// JSON shape:
//   { "title": "...", "start": "intro",
//     "passages": { "intro": { "wav": "intro.wav", "screen": "...",
//                              "menu": "[OK] ... | [<>] ...",
//                              "choices": [ {"key": 1, "goto": "machine"}, ... ] },
//                   ... } }
// key codes match the 5-way pad: 1=SELECT 2=DOWN 3=MENU 4=LEFT/RIGHT 5=UP.
// MENU (3) always quits the gamebook.

#include "esp_err.h"
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

// Install the display_ui key hook. Call once at boot, after display_ui_init().
void gamebook_init(void);

// Load /sdcard/gamebook/gamebook.json and enter the start passage (show text +
// play its WAV). Returns ESP_ERR_* if the SD/JSON is missing or malformed.
esp_err_t gamebook_start(void);

// Leave gamebook mode: stop playback, release the JSON, hand the pad back to
// the shell. Idempotent.
void gamebook_stop(void);

// True while a gamebook is running (used by the key hook to claim the pad).
bool gamebook_active(void);

#ifdef __cplusplus
}
#endif
