feat(M01): add explicit streaming focus

Work-Package: M01-RND-STREAMING-FOCUS-001

Agent: sindo-main-codex

src/tools/capture_render_checkpoints.gd

@@ -64,7 +64,7 @@ func _capture_async() -> void:
 	camera.far = 50000.0
 	camera.position = _vector3(first.get("camera", [0.0, 0.0, 0.0]))
 	(world as Node3D).add_child(camera)
-	world.set("camera_path", NodePath("CheckpointCamera"))
+	world.set("streaming_focus_source_path", NodePath("CheckpointCamera"))
 	world.set("debug_streaming", true)
 	world.set("runtime_stats_enabled", true)
 	get_root().add_child(world)
@@ -126,8 +126,8 @@ func _capture_async() -> void:
 			if player != null:
 				player.global_position = _vector3(checkpoint.get("player", checkpoint.get("target", [0.0, 0.0, 0.0])))
 			_set_sky_time(world, float(checkpoint.get("time_hours", 13.0)))
-			if world.has_method("_refresh_streaming_targets_at"):
-				world.call("_refresh_streaming_targets_at", camera.global_position, true)
+			if world.has_method("refresh_streaming_focus"):
+				world.call("refresh_streaming_focus", true)
 
 			if dry_run:
 				print("RENDER_CHECKPOINT dry_run name=%s coverage=%s camera=%s target=%s yaw_offset=%.2f pitch_offset=%.2f time=%.2f" % [

src/tools/probe_render_camera_occluders.gd

@@ -28,7 +28,7 @@ func _run_async() -> void:
 	camera.name = "OccluderProbeCamera"
 	camera.current = true
 	world.add_child(camera)
-	world.set("camera_path", NodePath(camera.name))
+	world.set("streaming_focus_source_path", NodePath(camera.name))
 	world.set("debug_streaming", false)
 	get_root().add_child(world)
 	await process_frame
@@ -47,8 +47,8 @@ func _run_async() -> void:
 		var camera_position := _vector3(checkpoint.get("camera", []))
 		var target_position := _vector3(checkpoint.get("target", []))
 		camera.global_position = camera_position
-		if world.has_method("_refresh_streaming_targets_at"):
-			world.call("_refresh_streaming_targets_at", camera_position, true)
+		if world.has_method("refresh_streaming_focus"):
+			world.call("refresh_streaming_focus", true)
 		await create_timer(maxf(0.1, wait_seconds)).timeout
 		var geometry_nodes: Array[Node3D] = []
 		_collect_geometry_nodes(world, geometry_nodes)

src/tools/probe_render_terrain_height.gd

@@ -36,7 +36,7 @@ func _run_async() -> void:
 	var camera := Camera3D.new()
 	camera.current = true
 	world.add_child(camera)
-	world.set("camera_path", NodePath(camera.name))
+	world.set("streaming_focus_source_path", NodePath(camera.name))
 	world.set("debug_streaming", false)
 	get_root().add_child(world)
 	await process_frame
@@ -53,8 +53,8 @@ func _run_async() -> void:
 			continue
 		var camera_position := _vector3(checkpoint.get("camera", []))
 		camera.global_position = camera_position
-		if world.has_method("_refresh_streaming_targets_at"):
-			world.call("_refresh_streaming_targets_at", camera_position, true)
+		if world.has_method("refresh_streaming_focus"):
+			world.call("refresh_streaming_focus", true)
 		await create_timer(maxf(0.1, wait_seconds)).timeout
 		var terrain_sample := _sample_terrain(world, camera_position)
 		terrain_sample["name"] = checkpoint.get("name", "checkpoint")

src/tools/verify_streaming_focus.gd

@@ -0,0 +1,101 @@
+extends SceneTree
+
+## Headless M01 contract and wiring regression for camera-independent streaming.
+
+const StreamingFocusScript = preload("res://src/domain/streaming/streaming_focus.gd")
+const GodotWorldPositionScript = preload("res://src/domain/coordinates/godot_world_position.gd")
+
+const LOADER_PATH := "res://src/scenes/streaming/streaming_world_loader.gd"
+const RUNTIME_SCENE_PATHS: Array[String] = [
+	"res://src/scenes/streaming/eastern_kingdoms_streaming.tscn",
+	"res://src/scenes/streaming/kalimdor_streaming.tscn",
+]
+const CAPTURE_TOOL_PATHS: Array[String] = [
+	"res://src/tools/capture_render_checkpoints.gd",
+	"res://src/tools/probe_render_camera_occluders.gd",
+	"res://src/tools/probe_render_terrain_height.gd",
+]
+
+
+func _initialize() -> void:
+	var failures: Array[String] = []
+	_verify_scene_free_focus_value(failures)
+	_verify_loader_boundary(failures)
+	_verify_runtime_scene_wiring(failures)
+	_verify_capture_tool_wiring(failures)
+
+	if not failures.is_empty():
+		for failure in failures:
+			push_error("STREAMING_FOCUS: %s" % failure)
+		quit(1)
+		return
+
+	print("STREAMING_FOCUS PASS contract=1 runtime_scenes=2 capture_tools=3")
+	quit(0)
+
+
+func _verify_scene_free_focus_value(failures: Array[String]) -> void:
+	var position = GodotWorldPositionScript.new(17199.159666667, 83.5312, 26016.616666667)
+	var focus = StreamingFocusScript.new(position)
+	_expect_true(focus.world_position == position, "focus retains typed position", failures)
+	_expect_near(focus.world_position.x_units, 17199.159666667, "focus X", failures)
+	_expect_near(focus.world_position.y_units, 83.5312, "focus Y", failures)
+	_expect_near(focus.world_position.z_units, 26016.616666667, "focus Z", failures)
+
+	var focus_source := _read_text("res://src/domain/streaming/streaming_focus.gd", failures)
+	_expect_true(not focus_source.contains("extends Node"), "focus does not inherit Node", failures)
+	_expect_true(not focus_source.contains("extends Resource"), "focus does not inherit Resource", failures)
+	_expect_true(not focus_source.contains("Vector3"), "focus does not expose Vector3", failures)
+
+
+func _verify_loader_boundary(failures: Array[String]) -> void:
+	var loader_source := _read_text(LOADER_PATH, failures)
+	for required_text in [
+		"@export var streaming_focus_source_path: NodePath",
+		"func set_streaming_focus(streaming_focus: StreamingFocus) -> void:",
+		"func refresh_streaming_focus(force: bool = false) -> bool:",
+	]:
+		_expect_true(loader_source.contains(required_text), "loader contains %s" % required_text, failures)
+
+	for forbidden_text in [
+		"get_viewport().get_camera_3d()",
+		"child is Camera3D and child.current",
+		"func _get_stream_camera()",
+	]:
+		_expect_true(not loader_source.contains(forbidden_text), "loader omits %s" % forbidden_text, failures)
+
+
+func _verify_runtime_scene_wiring(failures: Array[String]) -> void:
+	for scene_path in RUNTIME_SCENE_PATHS:
+		var scene_source := _read_text(scene_path, failures)
+		_expect_true(
+			scene_source.contains('streaming_focus_source_path = NodePath("ThirdPersonPlayer")'),
+			"%s uses player focus" % scene_path,
+			failures
+		)
+
+
+func _verify_capture_tool_wiring(failures: Array[String]) -> void:
+	for tool_path in CAPTURE_TOOL_PATHS:
+		var tool_source := _read_text(tool_path, failures)
+		_expect_true(tool_source.contains('world.set("streaming_focus_source_path"'), "%s sets explicit focus source" % tool_path, failures)
+		_expect_true(tool_source.contains('world.call("refresh_streaming_focus", true)'), "%s uses public refresh" % tool_path, failures)
+		_expect_true(not tool_source.contains('world.call("_refresh_streaming_targets_at"'), "%s avoids private refresh" % tool_path, failures)
+
+
+func _read_text(path: String, failures: Array[String]) -> String:
+	var file := FileAccess.open(path, FileAccess.READ)
+	if file == null:
+		failures.append("cannot open %s" % path)
+		return ""
+	return file.get_as_text()
+
+
+func _expect_near(actual_value: float, expected_value: float, label: String, failures: Array[String]) -> void:
+	if absf(actual_value - expected_value) > 0.000001:
+		failures.append("%s expected %.9f, got %.9f" % [label, expected_value, actual_value])
+
+
+func _expect_true(actual_value: bool, label: String, failures: Array[String]) -> void:
+	if not actual_value:
+		failures.append("%s expected true" % label)

src/tools/verify_streaming_focus.gd.uid

@@ -0,0 +1 @@
+uid://b7ayw5a0bn1lq