# Every function in src/ allowed to call fadeblack(), one per line, with how
# many fades it makes and the reason it owns them. Checked by
# scripts/check_fadeblack_sites.sh, which is a build dependency of
# og_interface and og_platform_sdl — an unclassified fade fails the build, and
# so does a fade added beside an existing one (the count changes).
#
# A key is "<path>::<enclosing function>=<count>", never a line number, so
# unrelated edits do not rot this list. The count is the number of fadeblack()
# calls in that function: a door-site fade planted next to a classified
# teardown fade is exactly the shape the ownership rule forbids, and a
# per-function count is what makes it fail to build.
#
# The ownership rule (#237): whoever fades in fades out, at its own exit, while
# its last frame is still the render buffer. Menu screens get that for free
# from ScreenFadeScope / LegacyMenuFade, so a new entry here should be rare and
# is either the fade engine itself or a boundary the runner does not cover
# (process start, the gameplay/menu boundary).

# --- the definition: screen::fadeblack delegates to the video layer ---
# (sdl_video::fadeblack, the implementation, calls FadeBetween and makes no
# fadeblack() call of its own, so it has no key.)
src/interface/screen.cpp::screen::fadeblack=1   # the delegate to video_impl_->fadeblack

# --- the fade engine: the runner's own entry and exit brackets ---
src/interface/ui/menu_screen_runner.cpp::~ScreenFadeScope=1              # exit-owned fade-out; every return path out of run_menu_screen
src/interface/ui/menu_screen_runner.cpp::run_menu_screen=3               # entry fade-out, cold first-frame fade-in, loop fade-in after a nested door
src/interface/ui/menu_screen_runner.cpp::LegacyMenuFade::LegacyMenuFade=1  # entry fade-out for screens outside the runner (campaign select, results, editor)
src/interface/ui/menu_screen_runner.cpp::LegacyMenuFade::present_first=1   # the paired fade-in, presenting the legacy screen's first composed frame
src/interface/ui/menu_screen_runner.cpp::LegacyMenuFade::end=1             # the paired exit fade-out (also runs from the destructor, and for fade_out_at_exit)

# --- process start: the intro sequence owns its own pages ---
src/interface/ui/intro.cpp::intro_main=1   # fade the cold-start loading dialog out before the first intro page composes
src/interface/ui/intro.cpp::show=2         # per-page fade-in and fade-out; both returns honour the -1 key abort
src/interface/ui/intro.cpp::cleanup=1      # fades an aborted page out so the main menu's entry only ever fades in
src/platform/sdl/glad.cpp::bootstrap_runtime=1  # the intro-skipped web start: the loading dialog exits here, so it fades out here

# --- the gameplay/menu boundary: outside every menu runner ---
src/platform/sdl/glad_gameplay.cpp::glad_init=2          # technical teardown: fade the picker out (a no-op after Base Camp's exit fade), then fade the first composed gameplay frame in
src/interface/ui/picker_team_build.cpp::go_menu=1        # native return-from-game; fades whichever canvas gameplay last presented
src/interface/ui/picker.cpp::picker_reinit_after_game=1  # the same return-from-game fade on the Emscripten state-machine path
src/interface/ui/results_screen.cpp::results_screen=1    # the mission's tail (last frame + dismissed ending popup) exits here: fade it out before the results panel's entry
