gdharness 1.3.67 → 1.3.68

package/build/godot/addons/gdharness_editor/bridge_client.gd

@@ -573,15 +573,17 @@ func _handle_message(json_string: String) -> void:
 
 ## Says [param tool_name] was not run because the editor is scanning or importing, for the server to
 ## ask again once that is over.
-func send_busy(request_id: String, tool_name: String) -> void:
+## [param doing] is what the editor is busy with, and [param mark] changes as it gets on with it.
+func send_busy(request_id: String, tool_name: String, doing: String, mark: String) -> void:
 	_send_message(
 		{
 			"type": "tool_result",
 			"id": request_id,
 			"success": false,
 			"busy": true,
-			"error":
-			"The editor is scanning or importing its files, so %s was not run." % tool_name,
+			"busyWith": doing,
+			"progress": mark,
+			"error": "The editor is %s, so %s was not run." % [doing, tool_name],
 		}
 	)
 

package/build/godot/addons/gdharness_editor/headless_check.gd

@@ -66,6 +66,16 @@ static func through_script(object: Object, names: Dictionary) -> bool:
 	return false
 
 
+## Sets [param name] on [param object] back to [param value]. A metadata entry put back to nothing
+## is removed. Set to null through its property, Godot keeps the entry holding null, and the saver
+## writes a line that erases what the node's script sets each time the scene loads.
+static func restore(object: Object, name: String, value: Variant) -> void:
+	if value == null and name.begins_with("metadata/"):
+		object.remove_meta(name.trim_prefix("metadata/"))
+		return
+	object.set(name, value)
+
+
 ## Whether [param object] still holds [param held] for [param name] once set to [param wanted]
 ## because the engine derives it, as it keeps layout_mode at Container under a container: an engine
 ## property, so no script code ran for the set, and an editor saves the same.
@@ -574,3 +584,45 @@ class GdhSaved:
 		path = at
 		before = held
 		resave = again
+
+
+## Every script that failed to compile while it is attached, as {file, line, message} in order.
+class GdhParseErrors:
+	extends Logger
+
+	var raised: Array[Dictionary] = []
+
+	func _log_message(_message: String, _error: bool) -> void:
+		pass
+
+	# The engine's own signature for a Logger, eight parameters and not this project's to shape.
+	# gdstyle:ignore=quality/max-parameters
+	func _log_error(
+		_function: String,
+		file: String,
+		line: int,
+		code: String,
+		_rationale: String,
+		_editor_notify: bool,
+		error_type: int,
+		_script_backtraces: Array[ScriptBacktrace],
+	) -> void:
+		if error_type == Logger.ERROR_TYPE_SCRIPT and code.begins_with("Parse Error: "):
+			raised.append(
+				{ "file": file, "line": line, "message": code.trim_prefix("Parse Error: ") }
+			)
+
+	## Why a write is refused for what was raised, or "" when nothing was.
+	func refusal(scene_path: String) -> String:
+		if raised.is_empty():
+			return ""
+		var first: Dictionary = raised[0]
+		return (
+			(
+				"%s does not compile in a headless engine (line %d: %s), and it loads with %s, "
+				+ "so the scene's scripts would not run as they do in the game. A class_name added "
+				+ "since the class cache was built is taken in by project_import refresh_classes. "
+				+ "Fix the script or refresh the classes, then ask again."
+			)
+			% [first["file"], first["line"], first["message"], scene_path]
+		)

package/build/godot/addons/gdharness_editor/plugin.gd

@@ -7,6 +7,7 @@ extends EditorPlugin
 const GdhBridgeClient = preload("bridge_client.gd")
 const GdhToolExecutor = preload("tool_executor.gd")
 const GdhReleaseExport = preload("release_export.gd")
+const GdhSceneFile = preload("scene_file.gd")
 ## The tools answered while the editor scans or imports, because none of them saves a file: the
 ## ones a caller waits on a scan with, and the ones that only read or stop a played game.
 const ANSWERED_WHILE_SCANNING: Array[String] = [
@@ -17,11 +18,29 @@ const ANSWERED_WHILE_SCANNING: Array[String] = [
 	"stop_playing",
 	"profile_read",
 ]
+## The tools answered inside a task of the editor's progress dialog, because none of them writes
+## anything the editor's task could be in the middle of.
+const ANSWERED_DURING_A_TASK: Array[String] = [
+	"scan_status",
+	"playing_status",
+	"stop_playing",
+	"profile_read",
+]
+## What an editor opened to quit once a process has gone carries after `--`, with that pid after it.
+## Kept in step with `UNTIL_MARK` in src/launch.ts.
+const UNTIL_MARK: String = "--gdharness-until="
+## Where the holder of such an editor asks it to save and quit, a file named for its pid. Kept in
+## step with `QUITS_FOLDER` in src/editor-open.ts.
+const QUITS_FOLDER: String = "res://.godot/gdharness-editor-quits/"
+## How often such an editor looks for the request, in seconds.
+const QUIT_LOOK_S: float = 1.0
 
 var _client: GdhBridgeClient
 var _tool_executor: GdhToolExecutor
 var _status_label: Label
 var _release_export: GdhReleaseExport
+var _quit_look: Timer
+var _loaded_at: int = 0
 
 
 func _enter_tree() -> void:
@@ -43,6 +62,7 @@ func _enter_tree() -> void:
 
 	_setup_status_indicator()
 	_client.connect_to_server()
+	_look_for_a_quit_request()
 
 
 func _exit_tree() -> void:
@@ -71,6 +91,41 @@ func _exit_tree() -> void:
 		_status_label = null
 
 
+## Looks for its holder's request once a second, in an editor opened to quit once a process has
+## gone. Godot cannot watch that process itself, since `OS.is_process_running` answers false for any
+## pid it did not start, so a gdharness holder outside the editor watches it and writes the request.
+func _look_for_a_quit_request() -> void:
+	var held: bool = false
+	for arg: String in OS.get_cmdline_user_args():
+		held = held or arg.begins_with(UNTIL_MARK)
+	if not held:
+		return
+	_loaded_at = int(Time.get_unix_time_from_system())
+	_quit_look = Timer.new()
+	_quit_look.wait_time = QUIT_LOOK_S
+	_quit_look.autostart = true
+	_listen(_quit_look.timeout, _on_quit_look)
+	add_child(_quit_look)
+
+
+## Saves and quits on a request written since this addon loaded, as quit_editor does. One older
+## than that was written for an earlier process with this pid. Not while the editor scans, imports
+## or runs a task, which every save waits out.
+func _on_quit_look() -> void:
+	var request: String = ProjectSettings.globalize_path(QUITS_FOLDER + str(OS.get_process_id()))
+	if not FileAccess.file_exists(request) or FileAccess.get_modified_time(request) < _loaded_at:
+		return
+	if turned_away("quit_editor"):
+		return
+	_quit_look.stop()
+	var answer: Dictionary = await _tool_executor.execute_tool("quit_editor", {})
+	if answer.get("ok", false) != true:
+		push_warning(
+			"gdharness: the process holding this editor has gone, and it stays open: %s"
+			% str(answer.get("error", ""))
+		)
+
+
 # A failed connect is a mistake in this plugin rather than anything the editor did, so it goes to
 # the error stream instead of being dropped: a project holding return_value_discarded at error level
 # refuses to compile a script that throws the answer away.
@@ -107,16 +162,38 @@ func _on_disconnected() -> void:
 ## scan updates the file list the scan's thread is writing out (see SceneFile.scan_later), and an
 ## import can run frames of the editor from inside itself, the one handling this call among them.
 ## Every call waits out a capture, which shows a scene for frames before it reads the view.
+##
+## A task in the editor's progress dialog runs frames of the editor from inside itself at every
+## step, so a call handled then runs in the middle of that task. A save there asked for the script
+## classes again while the editor was registering them, and the two registrations walked one list,
+## which crashed the editor at its next scan.
 func turned_away(tool_name: String) -> bool:
 	if _tool_executor != null and _tool_executor.capturing():
 		return true
+	if not ANSWERED_DURING_A_TASK.has(tool_name) and GdhSceneFile.in_a_task():
+		return true
 	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
 	return (
 		not ANSWERED_WHILE_SCANNING.has(tool_name)
-		and (filesystem.is_scanning() or filesystem.is_importing())
+		and (GdhSceneFile.scan_unfinished(filesystem) or filesystem.is_importing())
 	)
 
 
+## What the editor is doing that turns calls away, and a mark that changes as it gets on with it,
+## as [what, mark]. The server keeps asking while the mark changes: registering forty classes in a
+## hidden editor took over thirty seconds, every one of them a step.
+func busy_with() -> Array[String]:
+	if _tool_executor != null and _tool_executor.capturing():
+		return ["capturing its view", ""]
+	var labels: Array[String] = GdhSceneFile.task_labels()
+	if not labels.is_empty():
+		return ["running its task \"%s\"" % labels[0].trim_suffix("..."), "\n".join(labels)]
+	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
+	if filesystem.is_importing():
+		return ["importing its files", ""]
+	return ["scanning its files", str(filesystem.get_scanning_progress())]
+
+
 func _on_tool_requested(request_id: String, tool_name: String, args: Dictionary) -> void:
 	if _tool_executor == null or _client == null:
 		return
@@ -124,7 +201,8 @@ func _on_tool_requested(request_id: String, tool_name: String, args: Dictionary)
 	# Turned away rather than held, so the server asks again: a call held here could run after the
 	# server had given up on it.
 	if turned_away(tool_name):
-		_client.send_busy(request_id, tool_name)
+		var busy: Array[String] = busy_with()
+		_client.send_busy(request_id, tool_name, busy[0], busy[1])
 		return
 
 	var result: Dictionary = await _tool_executor.execute_tool(tool_name, args)

package/build/godot/addons/gdharness_editor/scene_file.gd

@@ -30,6 +30,7 @@ const PUTTING_BACK_PASSES: int = 4
 const GdhRead = preload("reading.gd")
 const GdhSame = preload("same_values.gd")
 const GdhSerialisation = preload("serialisation.gd")
+const GdhSceneFile = preload("scene_file.gd")
 const GdhSceneUids = preload("scene_uids.gd")
 
 ## Whether a scan asked for through [method scan_later] is still to start, which a caller waiting
@@ -41,6 +42,10 @@ static var also_saved: Array[Dictionary] = []
 ## What a write said of the connections it kept in the file though the engine cannot make them,
 ## gathered for that call's answer as [member also_saved] is.
 static var unmade_note: String = ""
+## The editor's progress dialog, which Godot keeps for the editor's whole life and exposes no other
+## way. Looked for once, and again only if it has gone.
+static var _progress: Node = null
+static var _progress_sought: bool = false
 
 var root: Node = null
 var path: String = ""
@@ -102,12 +107,21 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 		var missing: String = missing_said(path, FileAccess.get_file_as_string(path))
 		if not missing.is_empty():
 			return { "ok": false, "error": missing }
+	# A script the scene's scripts load that fails to compile names no node, so nothing else sees
+	# it.
+	var failed: GdhHeadlessCheck.GdhParseErrors = GdhHeadlessCheck.GdhParseErrors.new()
+	var watching: bool = for_writing and not Engine.is_editor_hint()
+	if watching:
+		OS.add_logger(failed)
 	var packed: PackedScene = (
 		ResourceLoader.load(path, "PackedScene", ResourceLoader.CACHE_MODE_IGNORE) as PackedScene
 	)
+	if packed != null:
+		root = packed.instantiate(PackedScene.GEN_EDIT_STATE_MAIN)
+	if watching:
+		OS.remove_logger(failed)
 	if packed == null:
 		return { "ok": false, "error": "Failed to load %s as a scene" % path }
-	root = packed.instantiate(PackedScene.GEN_EDIT_STATE_MAIN)
 	if root == null:
 		return { "ok": false, "error": "Failed to instantiate " + path }
 	_state = packed.get_state()
@@ -124,6 +138,8 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 		if for_writing:
 			_text = FileAccess.get_file_as_string(path)
 		var unsettled: String = settle()
+		if unsettled.is_empty() and for_writing:
+			unsettled = failed.refusal(path)
 		if not unsettled.is_empty():
 			return refuse(("Nothing was written: " if for_writing else "Not read: ") + unsettled)
 	return {}
@@ -416,6 +432,64 @@ func copied(copies: Dictionary) -> void:
 		_copied_from[copy.get_instance_id()] = original.get_instance_id()
 
 
+## A scene to write at [param branch_path] whose root is [param top], a node of this one about to be
+## taken out of it, keeping what this file stores on each node of [param top] and what the tool
+## asked of them. A connection the engine could not make goes with it when both its ends are in
+## [param top]. One with a single end there is taken out of this scene's and answered, that end
+## given as its path from [param top] under sourceBelow or targetBelow, for [method rejoin_unmade].
+## Answers [scene, those connections].
+func split_off(top: Node, branch_path: String) -> Array:
+	var branch: GdhSceneFile = GdhSceneFile.new()
+	branch.root = top
+	branch.path = branch_path
+	branch._text = _text
+	branch._reached = _reached.duplicate()
+	var nodes: Array[Node] = [top]
+	nodes.append_array(top.find_children("*", "", true, false))
+	for node: Node in nodes:
+		var id: int = node.get_instance_id()
+		if _filed.has(id):
+			branch._filed[id] = _filed[id]
+		if _asked.has(id):
+			branch._asked[id] = _asked[id]
+		if _before.has(id):
+			branch._before[id] = _before[id]
+	var crossing: Array[Dictionary] = []
+	var still: Array[Dictionary] = []
+	for held: Dictionary in _unmade:
+		var source_in: bool = _within(held["source"], top)
+		var target_in: bool = _within(held["target"], top)
+		if source_in and target_in:
+			branch._unmade.append(held)
+			continue
+		if not source_in and not target_in:
+			still.append(held)
+			continue
+		var end: String = "source" if source_in else "target"
+		var below: Node = held[end]
+		held[end + "Below"] = str(top.get_path_to(below))
+		crossing.append(held)
+	_unmade = still
+	return [branch, crossing]
+
+
+## Puts back each of [param crossing], from [method split_off], among the connections a write keeps,
+## its end below the branch now on the node at that path below [param instance].
+func rejoin_unmade(crossing: Array[Dictionary], instance: Node) -> void:
+	for held: Dictionary in crossing:
+		for end: String in ["source", "target"]:
+			if held.has(end + "Below"):
+				held[end] = instance.get_node_or_null(NodePath(str(held[end + "Below"])))
+		_unmade.append(held)
+
+
+static func _within(held: Variant, top: Node) -> bool:
+	if not is_instance_valid(held) or not held is Node:
+		return false
+	var node: Node = held
+	return node == top or top.is_ancestor_of(node)
+
+
 ## Why [param scene_path] cannot be written while the editor has it open, or "".
 static func unsaved_in_editor(scene_path: String) -> String:
 	if not Engine.is_editor_hint() or not EditorInterface.get_unsaved_scenes().has(scene_path):
@@ -1075,23 +1149,63 @@ static func scan_later() -> void:
 	_start_scan.call_deferred()
 
 
-## [method EditorFileSystem.scan] does nothing, and says nothing, while the thread of the scan
-## before it is still to be joined, which is a frame or two after that scan stops reporting itself,
-## so a scan that leaves the editor not scanning is asked for once more once that is over. Asked of
-## a scan that ended within the call, the second costs one more scan.
+## It waits out a task of the progress dialog too, whose every step runs a frame of the editor from
+## inside itself. A scan's end registers the classes it found in such a task (4.7.2's
+## [code]EditorFileSystem::_notification[/code]). A scan started from that frame ran beside the end
+## of the one before, which crashed the editor or left it scanning.
 static func _start_scan() -> void:
 	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
 	var tree: SceneTree = Engine.get_main_loop()
-	while filesystem.is_scanning() or filesystem.is_importing():
+	while scan_unfinished(filesystem) or filesystem.is_importing() or in_a_task():
 		await tree.process_frame
 	filesystem.scan()
-	if not filesystem.is_scanning():
-		await tree.process_frame
-		await tree.process_frame
-		filesystem.scan()
 	scan_due = false
 
 
+## Whether the editor scans its files, counting the frames after a scan stops reporting itself and
+## before the editor handles its end. That end swaps in the new file list and registers the classes
+## the scan found, from a frame of the editor. A save in those frames registered the classes as
+## well,
+## inside its own task, and the editor crashed or logged "Task 'update_scripts_classes' already
+## exists". [method EditorFileSystem.scan] also does nothing then, without a word. The editor
+## processes from the start of a scan until it has handled the end (4.7.2's
+## [code]EditorFileSystem::scan[/code] and [code]_notification[/code]).
+static func scan_unfinished(filesystem: EditorFileSystem) -> bool:
+	return filesystem.is_scanning() or filesystem.is_processing()
+
+
+## Whether the editor's progress dialog is showing, which it does for as long as a task is open.
+static func in_a_task() -> bool:
+	if _progress != null and not is_instance_valid(_progress):
+		_progress = null
+		_progress_sought = false
+	if not _progress_sought:
+		_progress_sought = true
+		_progress = _found_progress((Engine.get_main_loop() as SceneTree).root)
+	return _progress is CanvasItem and (_progress as CanvasItem).visible
+
+
+## The labels of the progress dialog's open tasks, each task's title then the step it is on, which
+## change as the task goes on. Empty when no task is open.
+static func task_labels() -> Array[String]:
+	var labels: Array[String] = []
+	if not in_a_task():
+		return labels
+	for label: Node in _progress.find_children("*", "Label", true, false):
+		labels.append(str(label.get("text")))
+	return labels
+
+
+static func _found_progress(top: Node) -> Node:
+	var pending: Array[Node] = [top]
+	while not pending.is_empty():
+		var node: Node = pending.pop_back()
+		if node.is_class("ProgressDialog"):
+			return node
+		pending.append_array(node.get_children(true))
+	return null
+
+
 ## Whether the editor holds unsaved changes to [param scene_path], for a read to say that the file
 ## it answers from is not what the editor shows.
 static func unsaved(scene_path: String) -> bool:
@@ -1123,7 +1237,7 @@ func _settled(packed: PackedScene) -> Array:
 			var name: String = found[1]
 			var wanted: Variant = found[3] if found[2] else _unset_value(node, name)
 			var held: Variant = node.get(name)
-			node.set(name, wanted)
+			GdhHeadlessCheck.restore(node, name, wanted)
 			if GdhHeadlessCheck.kept_by_engine(node, name, wanted, held):
 				_engine_kept["%d:%s" % [node.get_instance_id(), name]] = true
 		for found: Array in moved:
@@ -1131,7 +1245,9 @@ func _settled(packed: PackedScene) -> Array:
 			var before: Dictionary = _before[node.get_instance_id()]
 			var restored: Dictionary = restored_by_write.get_or_add(node.get_instance_id(), {})
 			for name: String in found[1]:
-				node.set(name, before.get(name, GdhHeadlessCheck.default_of(node, name)))
+				GdhHeadlessCheck.restore(
+					node, name, before.get(name, GdhHeadlessCheck.default_of(node, name))
+				)
 				restored[name] = true
 		current = PackedScene.new()
 		var packing: Error = current.pack(root)

package/build/godot/addons/gdharness_editor/tool_executor.gd

@@ -118,6 +118,7 @@ func _init_tools() -> void:
 		"delete_node": [_scene_tools, "delete_node"],
 		"duplicate_node": [_scene_tools, "duplicate_node"],
 		"reparent_node": [_scene_tools, "reparent_node"],
+		"save_branch": [_scene_tools, "save_branch"],
 		"set_node_properties": [_scene_tools, "set_node_properties"],
 		"get_node_properties": [_scene_tools, "get_node_properties"],
 		"bake_navigation": [_scene_tools, "bake_navigation"],

package/build/godot/addons/gdharness_editor/tools/class_tools.gd

@@ -21,6 +21,8 @@ extends Node
 ## A file the scan skipped is either missing from the tree or recorded with no class name against
 ## it, and both come back as a class the editor does not have, which is the whole of the question.
 
+const GdhSceneFile = preload("../scene_file.gd")
+
 var _editor_plugin: EditorPlugin = null
 
 
@@ -282,7 +284,7 @@ func global_classes(_args: Dictionary) -> Dictionary:
 	return {
 		"ok": true,
 		"classes": names,
-		"scanning": filesystem.is_scanning(),
+		"scanning": GdhSceneFile.scan_unfinished(filesystem),
 		"importing": filesystem.is_importing(),
 	}
 

package/build/godot/addons/gdharness_editor/tools/filesystem_tools.gd

@@ -55,7 +55,7 @@ func rescan_filesystem(args: Dictionary) -> Dictionary:
 	# Not over a scan or an import the editor is already running: a scan asked for then starts a
 	# second reimport over the first, and the editor logs "Task 'reimport' already exists" and two
 	# conditions from its progress dialog. Declined and said, so the caller waits and asks again.
-	var busy: bool = filesystem.is_scanning() or filesystem.is_importing()
+	var busy: bool = GdhSceneFile.scan_unfinished(filesystem) or filesystem.is_importing()
 	var started: bool = false
 	var completed_before: int = _scans_completed
 	var uids: Dictionary = { "reread": [], "duplicated": [] }
@@ -71,13 +71,9 @@ func rescan_filesystem(args: Dictionary) -> Dictionary:
 			for path: Variant in paths:
 				filesystem.update_file(str(path))
 		filesystem.scan()
-		# Whether the scan ran, read off the editor rather than assumed. `scan()` returns without
-		# a word while the thread of the scan before is still to be joined, which is a frame or
-		# more after that scan stops reporting itself, and that scan then signals as it is joined.
-		# Taken as started, the answer came from a scan begun before the files were written:
-		# downstream, a rescan after 698 files were rewritten answered finished in 1.5s and the
-		# one changed file stayed on its old import. A threaded scan reports itself from inside
-		# the call, and one run on this thread has finished and signalled before it returns.
+		# Whether the scan ran, read off the editor rather than assumed. A threaded scan reports
+		# itself from inside the call, and one run on this thread has finished and signalled before
+		# it returns.
 		started = filesystem.is_scanning() or _scans_completed != completed_before
 
 	# Importing is reported separately from scanning, and a class is not registered until
@@ -87,7 +83,7 @@ func rescan_filesystem(args: Dictionary) -> Dictionary:
 	return {
 		"ok": true,
 		"started": started,
-		"scanning": filesystem.is_scanning(),
+		"scanning": GdhSceneFile.scan_unfinished(filesystem),
 		"importing": filesystem.is_importing(),
 		"scansCompletedBefore": completed_before,
 		"scansCompleted": _scans_completed,
@@ -179,7 +175,7 @@ func scan_status(_args: Dictionary) -> Dictionary:
 		"openScenes": open,
 		"editedScene": "" if shown == null else shown.scene_file_path,
 		"unsavedScenes": unsaved,
-		"scanning": filesystem.is_scanning(),
+		"scanning": GdhSceneFile.scan_unfinished(filesystem),
 		"importing": filesystem.is_importing(),
 		"pending": GdhSceneFile.scan_due,
 		"sinceScanFinishedMs":
@@ -210,13 +206,13 @@ func reimport_files(args: Dictionary) -> Dictionary:
 	if paths.is_empty():
 		return { "ok": false, "error": "reimport_files needs paths" }
 	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
-	var busy: bool = filesystem.is_scanning() or filesystem.is_importing()
+	var busy: bool = GdhSceneFile.scan_unfinished(filesystem) or filesystem.is_importing()
 	if not busy:
 		_reimport.call_deferred(PackedStringArray(paths))
 	return {
 		"ok": true,
 		"started": not busy,
-		"scanning": filesystem.is_scanning(),
+		"scanning": GdhSceneFile.scan_unfinished(filesystem),
 		"importing": filesystem.is_importing(),
 		"reimportsCompletedBefore": _reimports_completed,
 	}
@@ -290,7 +286,7 @@ func files_moved(args: Dictionary) -> Dictionary:
 func _reimport(paths: PackedStringArray) -> void:
 	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
 	# A scan can begin between the answer and this frame, and its import would refuse this one.
-	while filesystem.is_scanning() or filesystem.is_importing():
+	while GdhSceneFile.scan_unfinished(filesystem) or filesystem.is_importing():
 		await get_tree().process_frame
 	filesystem.reimport_files(paths)
 	_reimports_completed += 1

package/build/godot/addons/gdharness_editor/tools/scene_kin.gd

@@ -180,19 +180,7 @@ static func follow(
 ) -> Dictionary:
 	var texts: Dictionary = {}
 	_read_scenes("res://", texts)
-	var kin: Array[String] = [changed]
-	var grew: bool = true
-	while grew:
-		grew = false
-		for scene_path: String in texts:
-			if kin.has(scene_path):
-				continue
-			var text: String = texts[scene_path]
-			for one: String in kin:
-				if text.contains(' path="%s"' % one):
-					kin.append(scene_path)
-					grew = true
-					break
+	var kin: Array[String] = _kin_of(changed, texts)
 	var followed: Array[String] = []
 	var not_followed: Array[Dictionary] = []
 	for scene_path: String in kin:
@@ -247,6 +235,92 @@ static func follow(
 	return answer
 
 
+## Marks the instance a branch at [param at] in [param changed] became editable in every other
+## .tscn that instances or inherits [param changed] at any depth, wherever that scene keeps values
+## on a node inside it or adds one below it. Those still load, and the next save of that scene
+## dropped them, since the packer skips every node under an instance whose children are not
+## editable. Answers followed, the scenes marked, and notFollowed, each left with why, each only
+## when it names any.
+static func enclose(changed: String, at: String) -> Dictionary:
+	var texts: Dictionary = {}
+	_read_scenes("res://", texts)
+	var followed: Array[String] = []
+	var not_followed: Array[Dictionary] = []
+	for scene_path: String in _kin_of(changed, texts):
+		if scene_path == changed:
+			continue
+		var moves: Dictionary = {}
+		if _inherits(scene_path, changed, texts):
+			moves[at] = at
+		var read: Dictionary = GdhFileReads.scene_tree(scene_path, -1, false, false)
+		if not read.get("ok", false):
+			not_followed.append({ "scenePath": scene_path, "reason": str(read.get("error", "")) })
+			continue
+		var tree: Dictionary = read["tree"]
+		_instances_of(tree, changed, at, at, moves)
+		var text: String = texts[scene_path]
+		var marks: PackedStringArray = []
+		for path: String in moves:
+			var mark: String = '[editable path="%s"]' % path
+			if not text.contains(mark) and _holds_below(text, path):
+				var _marked: bool = marks.append(mark)
+		if marks.is_empty():
+			continue
+		var unsaved: String = GdhSceneFile.unsaved_in_editor(scene_path)
+		if not unsaved.is_empty():
+			not_followed.append({ "scenePath": scene_path, "reason": unsaved })
+			continue
+		var file: FileAccess = FileAccess.open(scene_path, FileAccess.WRITE)
+		if (file == null
+				or not file.store_string(text.rstrip("\n") + "\n\n" + "\n".join(marks) + "\n")):
+			not_followed.append(
+				{ "scenePath": scene_path, "reason": error_string(FileAccess.get_open_error()) }
+			)
+			continue
+		file.close()
+		GdhSceneFile.refresh(scene_path)
+		followed.append(scene_path)
+	var answer: Dictionary = {}
+	if not followed.is_empty():
+		answer["followed"] = followed
+	if not not_followed.is_empty():
+		answer["notFollowed"] = not_followed
+	return answer
+
+
+## Whether [param text], a scene's file, has a node entry below [param path], one setting values on
+## a node there or adding one.
+static func _holds_below(text: String, path: String) -> bool:
+	for line: String in text.split("\n"):
+		if not line.begins_with("[node "):
+			continue
+		var parent: String = _attribute(line, "parent")
+		if parent.is_empty():
+			continue
+		var full: String = _under(parent, _attribute(line, "name"))
+		if full.begins_with(path + "/"):
+			return true
+	return false
+
+
+## [param changed] and every scene in [param texts] that instances or inherits it at any depth.
+static func _kin_of(changed: String, texts: Dictionary) -> Array[String]:
+	var kin: Array[String] = [changed]
+	var grew: bool = true
+	while grew:
+		grew = false
+		for scene_path: String in texts:
+			if kin.has(scene_path):
+				continue
+			var text: String = texts[scene_path]
+			for one: String in kin:
+				if text.contains(' path="%s"' % one):
+					kin.append(scene_path)
+					grew = true
+					break
+	return kin
+
+
 ## The text of every .tscn under [param directory] into [param texts], keyed by res:// path, leaving
 ## out the engine's own folder and hidden ones.
 static func _read_scenes(directory: String, texts: Dictionary) -> void: