#ifndef DECK_NARRATIVE_H
#define DECK_NARRATIVE_H

#include <stdio.h>

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

/* 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.
 *
 * Prints a narrative sentence for `aspect`'s transiting planet to `out`,
 * indented with `indent` and followed by a newline - or prints nothing
 * 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.
 *
 * `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()
 * (main.c does so before calling this). */
void narrative_print(FILE *out, const char *indent, const Aspect *aspect,
                      int transiting_house);

#endif
