## T-971 tests: AtlasAgentInterface — the observe/act named-intent channel.
## Every act() test asserts the intent reaches the SAME production state
## mutation the real click handler performs (spy at the handler seam: read
## the resulting screen/viewer state back, exactly as a real click's caller
## would observe it), never a synthesized _gui_input event. test_mode
## (SimBridge default outside SR_LIVE=1) means request_step_canvas() is a
## silent no-op — these tests exercise client-side state only, no live
## server needed, matching test_step_canvas_viewer.gd's own precedent.
class_name TestAtlasAgentInterface
extends GdUnitTestSuite

const AtlasAgentInterfaceScript := preload("res://ui/implant/apps/atlas/atlas_agent_interface.gd")
const StepCanvasTransport := preload("res://ui/implant/apps/atlas/step_canvas/step_canvas_transport.gd")

## AtlasApp._ready() unconditionally reloads the real app.tres manifest
## (`manifest = load("res://ui/implant/apps/atlas/app.tres")`), overwriting
## anything set before add_child() — so, unlike the generic ImplantApp
## lifecycle tests (which use a bare, manifest-injectable ImplantApp), a real
## AtlasApp instance ALWAYS registers under the production app_path. Tests
## drive HudGroups with THIS path, not a synthetic test-only one.
const TEST_APP_PATH := "implant/map"

const FIXTURE_SYSTEM := {
	"system_id": "GJ1",
	"proper_name": "Gliese J1",
	"hop_distance": 0,
	"orbit_bodies": [
		{
			"body_id": "GJ1b", "proper_name": "Barrenholt", "body_type": "planet",
			"orbit_index": 0, "terrain_reference": "GJ1b_heightmap",
		},
		{
			"body_id": "GJ1c", "proper_name": "Cindral", "body_type": "planet",
			"orbit_index": 1, "terrain_reference": null,
		},
	],
	"stations": [],
}


## Returns an AtlasApp instance (untyped — matches _make_app()'s own
## precedent in test_implant_app_lifecycle.gd, which keeps the return
## untyped there too for the same class_name parse-order reason). No manifest
## injection needed (unlike the generic ImplantApp lifecycle tests) —
## AtlasApp._ready() always loads the real production manifest itself.
func _make_app():
	var AppClass := load("res://ui/implant/apps/atlas/atlas_app.gd")
	var app = AppClass.new()
	add_child(app)  # fires _ready() -> on_install()
	return app


func after_test() -> void:
	HudGroups._active_app = ""
	HudGroups._active_mode = HudGroups.Mode.GAMEPLAY
	HudGroups._groups.erase(TEST_APP_PATH)
	HudGroups._groups.erase("implant/map")
	# PR #209 review (Tyre): every _make_app() call sets
	# AtlasAgentBridge.current_app to the (now freed) instance via on_install()
	# — clearing it here matches the HudGroups-reset discipline already above
	# and closes the latent footgun of a later test/consumer reading a stale,
	# freed-pending app reference.
	AtlasAgentBridge.current_app = null


# =============================================================================
# observe()
# =============================================================================


func test_observe_reports_current_screen_id() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	var result: Dictionary = AtlasAgentInterfaceScript.observe(app)
	assert_str(result.get("screen", "")).is_equal("reach")
	app.queue_free()


func test_observe_returns_error_for_null_app() -> void:
	var result: Dictionary = AtlasAgentInterfaceScript.observe(null)
	assert_bool(result.has("error")).is_true()


func test_observe_affordance_tree_includes_overlay_bar_buttons_on_regional() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	app.nav.push("regional", {"body": {"body_id": "GJ1b"}, "system": FIXTURE_SYSTEM})

	var result: Dictionary = AtlasAgentInterfaceScript.observe(app)
	var affordances: Array = result.get("affordances", [])
	assert_int(affordances.size()).is_greater(0)
	app.queue_free()


func test_observe_is_side_effect_free() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	var before: String = app.current_screen_id()
	AtlasAgentInterfaceScript.observe(app)
	assert_str(app.current_screen_id()).is_equal(before)
	app.queue_free()


# =============================================================================
# act() — reach screen intents
# =============================================================================


func test_select_system_reaches_reach_screen_selection_state() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	app.get_screen("reach").set_systems([FIXTURE_SYSTEM], {"GJ1": FIXTURE_SYSTEM})

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "select_system", {"system_id": "GJ1"})

	assert_bool(result.get("ok", false)).is_true()
	assert_bool(app.get_screen("reach").has_selection()).is_true()
	app.queue_free()


func test_open_system_reaches_atlas_app_nav_push() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	app.get_screen("reach").set_systems([FIXTURE_SYSTEM], {"GJ1": FIXTURE_SYSTEM})

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "open_system", {"system_id": "GJ1"})

	assert_bool(result.get("ok", false)).is_true()
	assert_str(app.current_screen_id()).is_equal("system")
	app.queue_free()


# =============================================================================
# act() — system screen intents
# =============================================================================


func _enter_orbital(app) -> void:
	app.get_screen("system").set_systems([FIXTURE_SYSTEM])
	app.nav.push("system", {"mode": "orbital", "system": FIXTURE_SYSTEM})


func test_select_body_reaches_system_screen_body_panel_state() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "select_body", {"body_id": "GJ1c"})

	assert_bool(result.get("ok", false)).is_true()
	assert_bool(app.get_screen("system").has_body_panel_open()).is_true()
	app.queue_free()


func test_open_body_reaches_atlas_app_nav_push_to_regional() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "open_body", {"body_id": "GJ1b"})

	assert_bool(result.get("ok", false)).is_true()
	assert_str(app.current_screen_id()).is_equal("regional")
	app.queue_free()


func test_open_body_returns_structured_error_for_unrecognized_id() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app, "open_body", {"body_id": "does_not_exist"}
	)

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	assert_str(app.current_screen_id()).is_equal("system")
	app.queue_free()


## PR #209 review (Hoshe finding 3, lead ruling): open_body must reject a
## RECOGNIZED body with no terrain_reference — this is the pre-existing
## click/Enter divergence the PR formalizes and fixes. Structured error, not
## a silent no-op, and no navigation must occur.
func test_open_body_rejects_a_body_with_no_terrain_reference() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "open_body", {"body_id": "GJ1c"})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	assert_str(app.current_screen_id()).override_failure_message(
		"open_body must not navigate for a body with no terrain_reference"
	).is_equal("system")
	app.queue_free()


## The positive case alongside the guard above: a body WITH a
## terrain_reference still opens normally (GJ1b in the fixture) — this is
## test_open_body_reaches_atlas_app_nav_push_to_regional() above, kept as its
## own assertion here too so the guard test and the "terrain body opens" test
## sit next to each other per the review's own test list.
func test_open_body_opens_a_body_with_a_terrain_reference() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "open_body", {"body_id": "GJ1b"})

	assert_bool(result.get("ok", false)).is_true()
	assert_str(app.current_screen_id()).is_equal("regional")
	app.queue_free()


# =============================================================================
# act() — regional/step-canvas intents
# =============================================================================


func _enter_regional(app) -> void:
	app.nav.push("regional", {"body": {"body_id": "GJ1b", "body_radius_km": 6371.0}, "system": FIXTURE_SYSTEM})


func test_scroll_rung_reaches_step_canvas_viewer_rung_transport() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "scroll_rung", {"direction": 1})

	assert_bool(result.get("ok", false)).is_true()
	assert_str(result.get("rung", "")).is_equal(StepCanvasTransport.RUNG_REGION)
	app.queue_free()


func test_reset_view_reaches_step_canvas_viewer_reset() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)
	AtlasAgentInterfaceScript.act(app, "scroll_rung", {"direction": 1})
	AtlasAgentInterfaceScript.act(app, "scroll_rung", {"direction": 1})

	AtlasAgentInterfaceScript.act(app, "reset_view", {})

	var viewer: Variant = app.get_screen("regional").get_viewer()
	assert_str(viewer.get_held_rung()).is_equal(StepCanvasTransport.RUNG_GLOBAL)
	app.queue_free()


func test_set_overlay_reaches_step_canvas_viewer_overlay_state() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)

	AtlasAgentInterfaceScript.act(
		app, "set_overlay", {"overlay_id": "gen_dw_temp", "visible": true}
	)

	var viewer: Variant = app.get_screen("regional").get_viewer()
	assert_bool(viewer.is_overlay_visible("gen_dw_temp")).is_true()
	app.queue_free()


func test_back_reaches_nav_pop() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	AtlasAgentInterfaceScript.act(app, "back", {})

	assert_str(app.current_screen_id()).is_equal("reach")
	app.queue_free()


# =============================================================================
# jump_to_center — key-discipline test (T-971 highest-value intent)
# =============================================================================


## The core guarantee this intent exists for: jumping to a center and
## scrolling to the SAME center must produce the SAME request key (same
## body/rung/center/extent) — jump_to() must go through the identical
## _fire_request()/_request_extent() path, never a parallel one. Verified via
## the request object's own held state (StepCanvasRequest's private _center/
## _rung fields aren't public, so this compares the PUBLIC echo surface:
## held_rung + world_center, which is exactly what a cache-key comparison
## downstream would use).
func test_jump_to_center_produces_the_same_request_key_as_an_equivalent_scroll() -> void:
	var app_a = _make_app()
	app_a._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app_a)
	var viewer_a: Variant = app_a.get_screen("regional").get_viewer()
	viewer_a._scroll_rung(1, Vector2(400.0, 300.0))
	var scrolled_center: Vector2 = viewer_a.get_world_center()
	var scrolled_rung: String = viewer_a.get_held_rung()
	app_a.queue_free()

	var app_b = _make_app()
	app_b._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app_b)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app_b,
		"jump_to_center",
		{"world_center": [scrolled_center.x, scrolled_center.y], "rung": scrolled_rung}
	)

	assert_bool(result.get("ok", false)).is_true()
	var viewer_b: Variant = app_b.get_screen("regional").get_viewer()
	assert_str(viewer_b.get_held_rung()).is_equal(scrolled_rung)
	assert_that(viewer_b.get_world_center()).is_equal(scrolled_center)
	app_b.queue_free()


func test_jump_to_center_requires_world_center_param() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "jump_to_center", {})

	assert_bool(result.get("ok", false)).is_false()
	app.queue_free()


func test_jump_to_center_keeps_current_rung_when_rung_param_omitted() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)
	var viewer: Variant = app.get_screen("regional").get_viewer()
	viewer._scroll_rung(1, Vector2(400.0, 300.0))  # now at Region

	AtlasAgentInterfaceScript.act(app, "jump_to_center", {"world_center": [1000.0, 2000.0]})

	assert_str(viewer.get_held_rung()).is_equal(StepCanvasTransport.RUNG_REGION)
	app.queue_free()


# =============================================================================
# open_atlas / close_atlas
# =============================================================================


func test_open_atlas_reaches_hud_groups_open_app() -> void:
	var app = _make_app()
	# AtlasApp._ready() already registers itself under "implant/map" via
	# HudGroups.register() (see ImplantApp._ready()) — no manual registration
	# needed here, unlike a bare ImplantApp fixture.

	AtlasAgentInterfaceScript.act(app, "open_atlas", {})

	assert_bool(HudGroups.is_app_active("implant/map")).is_true()
	app.queue_free()


func test_close_atlas_reaches_hud_groups_close_app() -> void:
	var app = _make_app()
	HudGroups.open_app("implant/map")

	AtlasAgentInterfaceScript.act(app, "close_atlas", {})

	assert_bool(HudGroups.is_app_active("implant/map")).is_false()
	app.queue_free()


# =============================================================================
# PR #209 review (Hoshe finding 1) — off-screen intent dispatch. Every
# screen-targeted intent must reject when its expected screen is NOT the
# current one, with the structured {"ok": false, "error": ...} shape, and
# must NOT mutate the off-screen screen/viewer as a side effect.
# =============================================================================


## The explicitly-called-out case: scroll_rung while "reach" is showing must
## not silently mutate the (registered but off-screen) regional viewer — the
## exact bug this whole guard exists to close. Verifies both the structured
## error AND the absence of a side effect (the off-screen viewer's held rung
## is unchanged from its "regional" was never entered" default).
func test_scroll_rung_from_reach_screen_returns_structured_error_and_does_not_mutate_viewer() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	assert_str(app.current_screen_id()).override_failure_message(
		"test setup: app must default to the reach screen"
	).is_equal("reach")

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "scroll_rung", {"direction": 1})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	var viewer: Variant = app.get_screen("regional").get_viewer()
	assert_str(viewer.get_held_rung()).override_failure_message(
		"scroll_rung from an off-screen 'reach' must not mutate the regional viewer"
	).is_equal(StepCanvasTransport.RUNG_GLOBAL)
	app.queue_free()


func test_jump_to_center_from_system_screen_returns_structured_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app, "jump_to_center", {"world_center": [1.0, 2.0]}
	)

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()


func test_reset_view_from_reach_screen_returns_structured_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "reset_view", {})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()


func test_set_overlay_from_system_screen_returns_structured_error_and_does_not_mutate_viewer() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app, "set_overlay", {"overlay_id": "gen_dw_temp", "visible": true}
	)

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	var viewer: Variant = app.get_screen("regional").get_viewer()
	assert_bool(viewer.is_overlay_visible("gen_dw_temp")).override_failure_message(
		"set_overlay from an off-screen 'system' must not mutate the regional viewer"
	).is_false()
	app.queue_free()


func test_select_system_from_system_screen_returns_structured_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_orbital(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app, "select_system", {"system_id": "GJ1"}
	)

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()


func test_open_system_from_regional_screen_returns_structured_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)
	_enter_regional(app)

	var result: Dictionary = AtlasAgentInterfaceScript.act(
		app, "open_system", {"system_id": "GJ1"}
	)

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()


func test_select_body_from_reach_screen_returns_structured_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "select_body", {"body_id": "GJ1c"})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()


func test_open_body_from_reach_screen_returns_structured_error_and_does_not_navigate() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "open_body", {"body_id": "GJ1b"})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	assert_str(app.current_screen_id()).override_failure_message(
		"open_body from an off-screen 'reach' must not navigate"
	).is_equal("reach")
	app.queue_free()


# =============================================================================
# Unknown intent
# =============================================================================


func test_unknown_intent_returns_ok_false_with_error() -> void:
	var app = _make_app()
	app._internal_app_changed(TEST_APP_PATH, HudGroups.Mode.FULLSCREEN)

	var result: Dictionary = AtlasAgentInterfaceScript.act(app, "not_a_real_intent", {})

	assert_bool(result.get("ok", true)).is_false()
	assert_bool(result.has("error")).is_true()
	app.queue_free()