feat(client): confrontation D-033 color shift (#521, D-063)

Entity renderer now tracks relationship per entity and tweens D-033
tint color over 0.7s when relationship changes (e.g. on confrontation
delivery). Uses manual lerp in _process() for testability instead of
SceneTree tweens. Cursor hover tint cascades automatically via
Constants.color_for_entity_kind().

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

client/scripts/constants.gd

@@ -59,13 +59,22 @@ const ENTITY_COLOR_HOSTILE: Color = Color("#d45d5d")    # Hostile/Dangerous —
 const ENTITY_COLOR_OBJECT: Color = Color("#8b8ba0")    # Static objects — muted grey
 const ENTITY_COLOR_PLAYER: Color = Color("#e0e8ff")    # Player character (detective)
 
-# D-033 color lookup by entity kind (Phase 1: defaults, Phase 2 #361: relationship-based)
+# D-033 color lookup by relationship string (#521)
+static func color_for_relationship(relationship: String) -> Color:
+	match relationship:
+		"Friendly": return ENTITY_COLOR_FRIENDLY
+		"PersonOfInterest": return ENTITY_COLOR_POI
+		"Hostile": return ENTITY_COLOR_HOSTILE
+		"Unknown": return ENTITY_COLOR_UNKNOWN
+		_: return ENTITY_COLOR_UNKNOWN
+
+# D-033 color lookup by entity data — uses relationship for NPCs (#521)
 static func color_for_entity_kind(entity_data: Dictionary) -> Color:
 	var kind_variant: String = entity_data.get("kind", {}).get("variant", "")
 	match kind_variant:
 		"Player": return ENTITY_COLOR_PLAYER
-		"Npc": return ENTITY_COLOR_UNKNOWN
 		"Object", "Terrain": return ENTITY_COLOR_OBJECT
+		"Npc": return color_for_relationship(entity_data.get("relationship", "Unknown"))
 		_: return ENTITY_COLOR_OBJECT
 
 # D-048/D-056: Insert-styled UI color palette

client/scripts/rendering/entity_renderer.gd

@@ -23,6 +23,11 @@ const LERP_SPEED: float = 12.0
 
 var entity_nodes: Dictionary = {}    # entity_id -> Node2D
 var _entity_targets: Dictionary = {} # entity_id -> Vector2 (target pixel position)
+var _entity_relationships: Dictionary = {}  # #521: entity_id -> String (last relationship)
+var _entity_tweens: Dictionary = {}  # #521: entity_id -> {target: Color, elapsed: float}
+
+# #521: Color transition duration in seconds (D-033/D-063: 0.5-1s spec, 0.7s chosen)
+const COLOR_FADE_DURATION: float = 0.7
 
 func _ready() -> void:
 	print("EntityRenderer: Initialized")
@@ -40,6 +45,22 @@ func _process(delta: float) -> void:
 		if not node.position.is_equal_approx(target):
 			node.position = node.position.lerp(target, weight)
 
+	# #521: Advance color transitions (manual lerp, testable without SceneTree)
+	var finished_ids: Array = []
+	for entity_id in _entity_tweens.keys():
+		if not entity_nodes.has(entity_id):
+			finished_ids.append(entity_id)
+			continue
+		var tween_data: Dictionary = _entity_tweens[entity_id]
+		tween_data.elapsed += delta
+		var t := clampf(tween_data.elapsed / COLOR_FADE_DURATION, 0.0, 1.0)
+		var node_c: ColorRect = entity_nodes[entity_id] as ColorRect
+		node_c.color = tween_data.from.lerp(tween_data.target, t)
+		if t >= 1.0:
+			finished_ids.append(entity_id)
+	for eid in finished_ids:
+		_entity_tweens.erase(eid)
+
 
 # Update entities from snapshot data
 func update_entities(entities: Array) -> void:
@@ -75,12 +96,12 @@ func _create_entity_node(entity_id: int, entity_data: Dictionary) -> void:
 	entity_node.size = Vector2(ENTITY_SIZE, ENTITY_SIZE)
 	entity_node.pivot_offset = Vector2(ENTITY_SIZE / 2.0, ENTITY_SIZE / 2.0)
 
-	# D-033 color by entity kind (Phase 1 default)
-	# TODO(#361): derive from RelationshipState via knowledge graph
+	# D-033 color by relationship (#521)
 	entity_node.color = _color_for_kind(entity_data)
 
 	add_child(entity_node)
 	entity_nodes[entity_id] = entity_node
+	_entity_relationships[entity_id] = entity_data.get("relationship", "Unknown")
 
 	# Add facing indicator for the player entity
 	if entity_id == GameState.player_entity_id:
@@ -112,6 +133,18 @@ func _update_entity_node(entity_id: int, entity_data: Dictionary) -> void:
 			floorf(entity_data.y) * TILE_SIZE + ENTITY_OFFSET
 		)
 
+	# #521: Detect relationship change → fade D-033 color (0.7s via _process)
+	var new_rel: String = entity_data.get("relationship", "Unknown")
+	var old_rel: String = _entity_relationships.get(entity_id, "Unknown")
+	if new_rel != old_rel:
+		_entity_relationships[entity_id] = new_rel
+		var new_color := _color_for_kind(entity_data)
+		_entity_tweens[entity_id] = {
+			"from": entity_node.color,
+			"target": new_color,
+			"elapsed": 0.0,
+		}
+
 	# v2: Peripheral vision dimming (D-015)
 	# null visibility (v1 backward compat) defaults to full alpha
 	var visibility: Variant = entity_data.get("visibility")
@@ -137,6 +170,8 @@ func _remove_entity_node(entity_id: int) -> void:
 	entity_node.queue_free()
 	entity_nodes.erase(entity_id)
 	_entity_targets.erase(entity_id)
+	_entity_relationships.erase(entity_id)
+	_entity_tweens.erase(entity_id)
 
 # D-033 color by entity kind — delegates to Constants.color_for_entity_kind
 static func _color_for_kind(entity_data: Dictionary) -> Color:

client/tests/test_color_shift.gd

@@ -0,0 +1,338 @@
+## #521: Confrontation D-033 color shift — QA test suite
+## Spec refs: D-033 (entity color = relationship), D-063 (confrontation same box)
+## Sprint Completion Proof (joint.md):
+##   - Entity tint fades 0.5-1s to new relationship color on confrontation delivery
+##   - Cursor hover tint also updates to match relationship
+##   - Palette matches D-033 exactly
+##
+## Tests are structured in layers:
+##   1. D-033 color palette constants — always pass (no implementation dependency)
+##   2. Relationship-to-color mapping — tests the lookup function
+##   3. Entity renderer relationship coloring — tests that entities USE relationship
+##   4. Tween on relationship change — tests fade behavior (0.5-1s)
+##   5. Protocol/GameState passthrough — tests data pipeline integrity
+class_name TestColorShift
+extends GdUnitTestSuite
+
+var EntityRendererScript: GDScript = load("res://scripts/rendering/entity_renderer.gd")
+var ConstantsScript: GDScript = load("res://scripts/constants.gd")
+
+# -- Test data -----------------------------------------------------------------
+
+# Entity with relationship field (v4 protocol format)
+func _make_entity(entity_id: int, kind: String, relationship: String, x: float = 5.0, y: float = 5.0) -> Dictionary:
+	return {
+		"entity_id": entity_id,
+		"x": x, "y": y, "z": 0,
+		"kind": {"variant": kind, "data": null},
+		"visibility": "Forward",
+		"relationship": relationship,
+		"observation": "Visible",
+	}
+
+func _make_entity_renderer() -> Node2D:
+	var renderer: Node2D = Node2D.new()
+	renderer.set_script(EntityRendererScript)
+	add_child(renderer)
+	return renderer
+
+
+func before_test() -> void:
+	GameState.player_entity_id = 1
+
+
+# ==============================================================================
+# Layer 1: D-033 Color Palette Constants
+# These tests verify the palette is defined correctly. No implementation needed.
+# ==============================================================================
+
+func test_d033_unknown_teal() -> void:
+	assert_that(Constants.ENTITY_COLOR_UNKNOWN).is_equal(Color("#4a9ebb"))
+
+func test_d033_friendly_green() -> void:
+	assert_that(Constants.ENTITY_COLOR_FRIENDLY).is_equal(Color("#6bc9a6"))
+
+func test_d033_poi_amber() -> void:
+	assert_that(Constants.ENTITY_COLOR_POI).is_equal(Color("#e8c547"))
+
+func test_d033_hostile_red() -> void:
+	assert_that(Constants.ENTITY_COLOR_HOSTILE).is_equal(Color("#d45d5d"))
+
+func test_d033_object_grey() -> void:
+	assert_that(Constants.ENTITY_COLOR_OBJECT).is_equal(Color("#8b8ba0"))
+
+func test_d033_player_cool_white() -> void:
+	assert_that(Constants.ENTITY_COLOR_PLAYER).is_equal(Color("#e0e8ff"))
+
+func test_d033_palette_all_distinct() -> void:
+	# All 6 D-033 colors must be distinct from each other
+	var colors: Array[Color] = [
+		Constants.ENTITY_COLOR_UNKNOWN,
+		Constants.ENTITY_COLOR_FRIENDLY,
+		Constants.ENTITY_COLOR_POI,
+		Constants.ENTITY_COLOR_HOSTILE,
+		Constants.ENTITY_COLOR_OBJECT,
+		Constants.ENTITY_COLOR_PLAYER,
+	]
+	for i in range(colors.size()):
+		for j in range(i + 1, colors.size()):
+			assert_that(colors[i] != colors[j]).is_true()
+
+
+# ==============================================================================
+# Layer 2: Relationship-to-Color Mapping
+# Tests the lookup function that maps relationship strings to D-033 colors.
+# Depends on #521 adding color_for_relationship() to Constants.
+# Uses ConstantsScript method list to skip gracefully if not yet implemented.
+# ==============================================================================
+
+func _has_color_for_relationship() -> bool:
+	# Check if the Constants script has a color_for_relationship method.
+	for method in ConstantsScript.get_script_method_list():
+		if method.name == "color_for_relationship":
+			return true
+	return false
+
+func test_relationship_color_unknown() -> void:
+	if not _has_color_for_relationship():
+		push_warning("TestColorShift: color_for_relationship not implemented yet — awaiting #521")
+		return
+	var color: Color = Constants.color_for_relationship("Unknown")
+	assert_that(color).is_equal(Constants.ENTITY_COLOR_UNKNOWN)
+
+func test_relationship_color_friendly() -> void:
+	if not _has_color_for_relationship():
+		return
+	var color: Color = Constants.color_for_relationship("Friendly")
+	assert_that(color).is_equal(Constants.ENTITY_COLOR_FRIENDLY)
+
+func test_relationship_color_person_of_interest() -> void:
+	if not _has_color_for_relationship():
+		return
+	var color: Color = Constants.color_for_relationship("PersonOfInterest")
+	assert_that(color).is_equal(Constants.ENTITY_COLOR_POI)
+
+func test_relationship_color_hostile() -> void:
+	if not _has_color_for_relationship():
+		return
+	var color: Color = Constants.color_for_relationship("Hostile")
+	assert_that(color).is_equal(Constants.ENTITY_COLOR_HOSTILE)
+
+func test_relationship_color_fallback() -> void:
+	if not _has_color_for_relationship():
+		return
+	var color: Color = Constants.color_for_relationship("SomethingWeird")
+	assert_that(color).is_equal(Constants.ENTITY_COLOR_UNKNOWN)
+
+
+# ==============================================================================
+# Layer 3: Entity Renderer — Relationship-Based Coloring
+# Tests that entity_renderer uses the relationship field for NPC colors.
+# Player and Object entities should remain unaffected by relationship field.
+# ==============================================================================
+
+func test_npc_uses_relationship_color_unknown() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(2, "Npc", "Unknown")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	# Unknown -> teal (both Phase 1 and Phase 2 produce the same result)
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_UNKNOWN)
+	renderer.queue_free()
+
+func test_npc_uses_relationship_color_friendly() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(2, "Npc", "Friendly")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	if not _entity_uses_relationship(renderer):
+		push_warning("TestColorShift: entity renderer not yet using relationship for color — awaiting #521")
+		renderer.queue_free()
+		return
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_FRIENDLY)
+	renderer.queue_free()
+
+func test_npc_uses_relationship_color_poi() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(2, "Npc", "PersonOfInterest")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	if not _entity_uses_relationship(renderer):
+		renderer.queue_free()
+		return
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_POI)
+	renderer.queue_free()
+
+func test_npc_uses_relationship_color_hostile() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(2, "Npc", "Hostile")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	if not _entity_uses_relationship(renderer):
+		renderer.queue_free()
+		return
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_HOSTILE)
+	renderer.queue_free()
+
+func test_player_color_ignores_relationship() -> void:
+	# Player entity always uses ENTITY_COLOR_PLAYER regardless of relationship
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(1, "Player", "Hostile")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[1] as ColorRect
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_PLAYER)
+	renderer.queue_free()
+
+func test_object_color_ignores_relationship() -> void:
+	# Object entities always use ENTITY_COLOR_OBJECT
+	var renderer: Node2D = _make_entity_renderer()
+	var entities: Array = [_make_entity(3, "Object", "Friendly")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[3] as ColorRect
+	assert_that(node.color).is_equal(Constants.ENTITY_COLOR_OBJECT)
+	renderer.queue_free()
+
+
+# ==============================================================================
+# Layer 4: Tween on Relationship Change
+# Tests that color transitions use a 0.5-1s fade, not an instant flip.
+# D-033: "Color shifts smoothly (0.5s fade) when relationship state changes."
+# D-063: "entity D-033 color may fade" on confrontation delivery.
+# ==============================================================================
+
+func test_color_shift_not_instant() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	var entities_before: Array = [_make_entity(2, "Npc", "Friendly")]
+	renderer.update_entities(entities_before)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	if not _entity_uses_relationship(renderer):
+		renderer.queue_free()
+		return
+	# Change relationship to Hostile
+	var entities_after: Array = [_make_entity(2, "Npc", "Hostile")]
+	renderer.update_entities(entities_after)
+	# Immediately after update, color should NOT yet be the target
+	var color_after_immediate: Color = node.color
+	if not _renderer_has_tween_support(renderer):
+		push_warning("TestColorShift: tween on relationship change not implemented yet — awaiting #521")
+		renderer.queue_free()
+		return
+	# The color should NOT be exactly the target yet (tween in progress)
+	assert_that(color_after_immediate != Constants.ENTITY_COLOR_HOSTILE).is_true()
+	renderer.queue_free()
+
+func test_color_shift_reaches_target() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	if not _entity_uses_relationship(renderer):
+		renderer.queue_free()
+		return
+	if not _renderer_has_tween_support(renderer):
+		renderer.queue_free()
+		return
+	renderer.update_entities([_make_entity(2, "Npc", "Friendly")])
+	renderer.update_entities([_make_entity(2, "Npc", "Hostile")])
+	# Simulate time passing: ~1.5 seconds of frames
+	var elapsed: float = 0.0
+	while elapsed < 1.5:
+		renderer._process(1.0 / 60.0)
+		elapsed += 1.0 / 60.0
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	assert_that(node.color.is_equal_approx(Constants.ENTITY_COLOR_HOSTILE)).is_true()
+	renderer.queue_free()
+
+func test_color_shift_same_relationship_no_tween() -> void:
+	var renderer: Node2D = _make_entity_renderer()
+	if not _entity_uses_relationship(renderer):
+		renderer.queue_free()
+		return
+	var entities: Array = [_make_entity(2, "Npc", "Unknown")]
+	renderer.update_entities(entities)
+	var node: ColorRect = renderer.entity_nodes[2] as ColorRect
+	var color_first: Color = node.color
+	renderer.update_entities(entities)
+	var color_second: Color = node.color
+	assert_that(color_first).is_equal(color_second)
+	renderer.queue_free()
+
+
+# ==============================================================================
+# Layer 5: Protocol — Relationship Field Round-Trip
+# ==============================================================================
+
+func test_protocol_entity_relationship_decoded() -> void:
+	var raw: Dictionary = {
+		"entity_id": 5,
+		"x": 10.0, "y": 10.0, "z": 0,
+		"kind": "Npc",
+		"relationship": "PersonOfInterest",
+		"visibility": "Forward",
+		"observation": "Visible",
+	}
+	var decoded: Variant = Protocol._decode_entity(raw)
+	assert_that(decoded).is_not_null()
+	assert_that(decoded.relationship).is_equal("PersonOfInterest")
+
+func test_protocol_entity_relationship_defaults_unknown() -> void:
+	var raw: Dictionary = {
+		"entity_id": 5,
+		"x": 10.0, "y": 10.0, "z": 0,
+		"kind": "Npc",
+	}
+	var decoded: Variant = Protocol._decode_entity(raw)
+	assert_that(decoded).is_not_null()
+	assert_that(decoded.relationship).is_equal("Unknown")
+
+func test_protocol_entity_all_relationship_values() -> void:
+	var relationships: Array[String] = ["Unknown", "Friendly", "PersonOfInterest", "Hostile"]
+	for rel in relationships:
+		var raw: Dictionary = {
+			"entity_id": 5,
+			"x": 10.0, "y": 10.0, "z": 0,
+			"kind": "Npc",
+			"relationship": rel,
+		}
+		var decoded: Variant = Protocol._decode_entity(raw)
+		assert_that(decoded).is_not_null()
+		assert_that(decoded.relationship).is_equal(rel)
+
+
+# ==============================================================================
+# Layer 6: GameState — Relationship Data Passthrough
+# ==============================================================================
+
+func test_game_state_preserves_relationship() -> void:
+	var snapshot: Dictionary = {
+		"tick": 1,
+		"entities": [_make_entity(2, "Npc", "Friendly")],
+	}
+	GameState.apply_snapshot(snapshot)
+	assert_that(GameState.visible_entities.size()).is_equal(1)
+	assert_that(GameState.visible_entities[0].relationship).is_equal("Friendly")
+
+func test_game_state_relationship_changes_between_snapshots() -> void:
+	GameState.apply_snapshot({"tick": 1, "entities": [_make_entity(2, "Npc", "Friendly")]})
+	assert_that(GameState.visible_entities[0].relationship).is_equal("Friendly")
+	GameState.apply_snapshot({"tick": 2, "entities": [_make_entity(2, "Npc", "PersonOfInterest")]})
+	assert_that(GameState.visible_entities[0].relationship).is_equal("PersonOfInterest")
+
+
+# ==============================================================================
+# Helpers
+# ==============================================================================
+
+func _entity_uses_relationship(renderer: Node2D) -> bool:
+	var friendly: Dictionary = _make_entity(10, "Npc", "Friendly", 3.0, 3.0)
+	var hostile: Dictionary = _make_entity(11, "Npc", "Hostile", 5.0, 5.0)
+	renderer.update_entities([friendly, hostile])
+	if not renderer.entity_nodes.has(10) or not renderer.entity_nodes.has(11):
+		return false
+	var f_node: ColorRect = renderer.entity_nodes[10] as ColorRect
+	var h_node: ColorRect = renderer.entity_nodes[11] as ColorRect
+	var f_color: Color = f_node.color
+	var h_color: Color = h_node.color
+	var uses_rel: bool = not f_color.is_equal_approx(h_color)
+	renderer.update_entities([])
+	return uses_rel
+
+func _renderer_has_tween_support(renderer: Node2D) -> bool:
+	return renderer.get("_entity_tweens") != null