#ifndef DECK_NARRATIVE_H
#define DECK_NARRATIVE_H

#include <stddef.h>

/* Header-only dependency on the engine, same policy as significance.h -
 * see its comment for why. */
#include "../../engine/src/astro.h"

/* Generous upper bound on narrative_write()'s output (indent + house
 * framing + base + harmonious/discordant addendum + newline) across
 * every language this project ships a translation for - callers on
 * constrained platforms (the watch) are free to size their own stack
 * buffer smaller if they know their own strings are shorter; this is
 * just a safe default for a caller that doesn't want to think about it. */
#define NARRATIVE_TEXT_MAX 512

/* Condensed, public-domain descriptions of what each transiting planet
 * classically signifies, sourced from Sepharial's "Transits and
 * Planetary Periods" (1920, public domain - res/Transits_and_Planetary_
 * Periods.pdf), Chapter VIII "Effects of Transits" (pp. 60-61). The
 * chapter's own structure - a base description of the planet's transit,
 * plus a "well aspected"/"badly aspected" addendum - maps directly onto
 * transiting-planet + aspect-type, our existing Aspect fields, so no new
 * engine data is needed to use it.
 *
 * The Moon and Pluto aren't covered by that chapter (fast lunar transits
 * were outside a year-ahead-forecasting book's scope; Pluto wasn't
 * discovered until 1930, a decade after this book) - their text in
 * narrative.c is original, written for this project in a matching
 * voice, not drawn from Sepharial.
 *
 * Writes a narrative sentence for `aspect`'s transiting planet into
 * `buf` (a caller-supplied buffer of `buf_size` bytes, always left
 * null-terminated - NARRATIVE_TEXT_MAX is a safe size), indented with
 * `indent` and followed by a newline - or writes an empty string if the
 * source material has no text applicable to this planet/aspect
 * combination (e.g. an exactly neutral conjunction to a planet whose
 * only text is a "well/badly aspected" addendum, like the Sun). A
 * conjunction is treated as neutral - neither the "harmonious" nor the
 * "discordant" addendum is shown for it - since Sepharial's own text
 * says a conjunction "takes the nature of what it conjoins," something
 * this data doesn't model. Uses only snprintf() internally (never
 * fprintf/sprintf/vsnprintf, all of which Pebble's SDK blocks at compile
 * time), so this function links into the watch app unchanged.
 *
 * `transiting_house` is the whole-sign house (1-12) the transiting
 * planet currently occupies in the natal chart - i.e.
 * reading->transits.bodies[aspect->transiting_planet].house - and names
 * *which area of life* the transit is playing out in, the standard,
 * personalized way transits are read (see astro.h's own house-field
 * comment). Pass a value outside 1-12 (e.g. the "no data" sentinel `0`
 * used elsewhere - see reading_io.c's parse_bodies()) to omit that
 * framing and print the planet's narrative on its own.
 *
 * Every string here is looked up via i18n_get() under "narrative.*"
 * keys (engine/i18n's .lang files) before falling back to the English text
 * baked into narrative.c, the same catalog tarot_data.c uses - so this
 * text respects whatever --lang the caller loaded with i18n_load()/
 * i18n_load_table() (main.c does so before calling this). */
void narrative_write(char *buf, size_t buf_size, const char *indent, const Aspect *aspect,
                      int transiting_house);

#endif