gdharness 1.0.1 → 1.0.3

package/build/godot/addons/gdharness_runtime/runtime_input.gd

@@ -25,12 +25,31 @@ const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
 var _host: Node
 var _values: Values
 
+## Where the last injected pointer event put the pointer, once one has.
+##
+## Kept here rather than asked of the viewport: the root viewport answers get_mouse_position
+## from the operating system's pointer, which an injected event never moves, so on a desktop it
+## is wherever the user's mouse is, another monitor included, and every motion sent through the
+## bridge carried the distance from there. Only a headless run, with no pointer to read, followed
+## the injected events, which is why that reading measured right and a played game read it wrong.
+var _pointer: Vector2 = Vector2.ZERO
+var _pointer_placed: bool = false
+
 
 func _init(host: Node, values: Values) -> void:
 	_host = host
 	_values = values
 
 
+## The movement a pointer arriving at [param position] carries, which is the distance from where
+## the last injected event put it, and none at all for the first. The arrival is recorded.
+func _arrive(position: Vector2) -> Vector2:
+	var relative: Vector2 = position - _pointer if _pointer_placed else Vector2.ZERO
+	_pointer = position
+	_pointer_placed = true
+	return relative
+
+
 ## Presses [param params].action, and lets go of it again unless asked to hold it.
 ##
 ## The whole press by default, for the reason [method click] is the whole click: an action left
@@ -329,9 +348,19 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	var pressed: bool = Read.as_bool(params.get("pressed", true), true)
 	var double: bool = Read.as_bool(params.get("doubleClick", false))
 
+	# A button pressed somewhere puts the pointer there: the motion after a held press measures
+	# its drag from the press, which is where a real pointer would be.
+	var _moved: Vector2 = _arrive(position)
 	Input.parse_input_event(_button(position, button, pressed, double))
+	# A wheel step is a press and a release together, as a mouse sends one: there is no holding a
+	# wheel. A lone wheel press left the viewport's mouse focus on the control that took it, with
+	# the wheel's bit in the focus mask, and every click after it landed on that control rather
+	# than under the pointer, landing true and doing nothing, until a release was sent by hand.
+	var notch: bool = pressed and _mask_of(button) == 0
+	if notch:
+		Input.parse_input_event(_button(position, button, false, false))
 
-	return {
+	var answer: Dictionary = {
 		"type": "input_injected",
 		"input_type": "mouse_click",
 		"position": [position.x, position.y],
@@ -339,22 +368,25 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 		"pressed": pressed,
 		"double": double
 	}
+	if notch:
+		answer["released"] = true
+	return answer
 
 
 ## Moves the pointer to a position, with the movement the event carries taken from where the
-## pointer last was unless the caller says otherwise.
+## last injected event put it unless the caller says otherwise.
 ##
 ## A real pointer never arrives without a `relative`, and a control that drags reads that field
 ## rather than the position, so a motion carrying none leaves a grip where it was however far the
-## position moved. The viewport remembers where the last motion put the pointer, injected or not,
-## so the difference from there is what a real move would have carried. A relative the caller gives
-## is kept, since a game may want to read a motion the position does not show.
+## position moved. The distance from where the bridge last put the pointer is what a real move
+## would have carried. A relative the caller gives is kept, since a game may want to read a motion
+## the position does not show.
 func inject_mouse_motion(params: Dictionary) -> Dictionary:
 	var point: Variant = _read_point(params, "x", "y", "position")
 	if point is String:
 		return {"type": "error", "message": point}
 	var position: Vector2 = point
-	var relative: Vector2 = position - _host.get_viewport().get_mouse_position()
+	var relative: Vector2 = _arrive(position)
 	if params.has("relativeX") or params.has("relativeY"):
 		relative = Vector2(
 			Read.as_float(params.get("relativeX", 0.0)), Read.as_float(params.get("relativeY", 0.0))
@@ -516,7 +548,7 @@ func click(params: Dictionary) -> Dictionary:
 	# Pushed into the viewport rather than through Input: Input accumulates events and flushes
 	# them at the next frame, so the hovered control read below would be the one from before
 	# the pointer moved. The viewport delivers it to the GUI the same way a real one arrives.
-	viewport.push_input(_motion(position, Vector2.ZERO))
+	viewport.push_input(_motion(position, _arrive(position)))
 	# What the engine itself thinks is under the pointer, which is the answer to "did it land",
 	# read before the press so the caller learns about a control on top rather than a click
 	# that went to it. Read in full here, path included, because nothing about that control
@@ -776,7 +808,7 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 		return _no_such_button(params.get("button"))
 	var double: bool = Read.as_bool(params.get("double", false))
 
-	viewport.push_input(_motion(position, Vector2.ZERO))
+	viewport.push_input(_motion(position, _arrive(position)))
 	# Read before the press, for the reason the Control click reads it: what the caller needs to
 	# know is whether a panel is sitting over the room, and the press is what would change it.
 	var hovered: Control = viewport.gui_get_hovered_control()
@@ -873,4 +905,7 @@ func _resolve_mouse_button(raw: Variant) -> int:
 				return MOUSE_BUTTON_WHEEL_DOWN
 			_:
 				return -1
-	return Read.as_int(raw, -1)
+	# The engine's buttons run from 1 to 9: 0 is MOUSE_BUTTON_NONE, which no event carries, and a
+	# number past the two extra buttons names nothing a mask bit can be made for.
+	var number: int = Read.as_int(raw, -1)
+	return number if number >= MOUSE_BUTTON_LEFT and number <= MOUSE_BUTTON_XBUTTON2 else -1

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -30,17 +30,33 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## The tree under a node, to a depth, with every stored property on each node when asked for all
+## of them or the named ones when a list is given.
+##
+## The list is the shape most questions about a screen take: the `text` of every label and
+## button under a panel. All of them for one row of a form answered seventy-six thousand
+## characters, and the same question as a find with one property answered two.
 func get_tree(params: Dictionary) -> Dictionary:
 	var root_path: String = str(params.get("root", "/root"))
 	var max_depth: int = Read.as_int(params.get("depth", 3), 3)
 	var include_properties: bool = Read.as_bool(params.get("include_properties", false))
+	var named: Array[String] = []
+	var listed: Variant = params.get("properties", [])
+	if listed is Array:
+		for each: Variant in listed:
+			named.append(str(each))
+	else:
+		return {"type": "error", "message": "properties must be a list of property names"}
 
 	var reached: Dictionary = Values.node_at(_host.get_tree().root, root_path)
 	if reached.has("message"):
 		return reached
 	var root: Node = reached["node"]
 
-	return {"type": "tree", "root": _serialize_node_tree(root, 0, max_depth, include_properties)}
+	return {
+		"type": "tree",
+		"root": _serialize_node_tree(root, 0, max_depth, include_properties, named),
+	}
 
 
 ## Nodes matching every filter given, as paths, so a caller can name what it wants without
@@ -91,7 +107,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 		var node: Node = pending.pop_front()
 		var rest: bool = _matches_apart_from_name(node, wanted)
 		if rest and _named(node, wanted["name"]):
-			if not include_hidden and not _shown(node):
+			if not include_hidden and not shown(node):
 				hidden += 1
 			elif found.size() >= limit:
 				truncated = true
@@ -144,8 +160,8 @@ func find_nodes(params: Dictionary) -> Dictionary:
 ## a plain Node sitting between a hidden panel and a label has no visibility to ask about, and the
 ## label answers that it is visible while nothing of it is on screen. Walking up is what makes a
 ## row hidden because the panel holding it is hidden, which is what somebody checking a screen is
-## asking about.
-static func _shown(node: Node) -> bool:
+## asking about. A wait on words asks the same, so it reads this too.
+static func shown(node: Node) -> bool:
 	var walk: Node = node
 	while walk != null:
 		if not _drawn(walk):
@@ -166,10 +182,10 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	if wanted_property.is_empty():
 		return entry
 	entry["property"] = wanted_property
-	# Through a path as well, for the reason [method _reached] gives. A step that is not there on
+	# Through a path as well, for the reason [method walk_to] gives. A step that is not there on
 	# this node reads as not having the property rather than as a refusal, which is the rule this
 	# whole function is written to: a find matches nodes of several classes on purpose.
-	var reached: Dictionary = _reached(node, str(entry["path"]), wanted_property)
+	var reached: Dictionary = walk_to(node, str(entry["path"]), wanted_property)
 	if reached.has("message"):
 		entry["has_property"] = false
 		return entry
@@ -178,7 +194,7 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	var has: bool = _can_read(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(_read(holder, named))
+		entry["value"] = _values.serialize(read_under(holder, named))
 	return entry
 
 
@@ -532,7 +548,7 @@ func get_property(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	var reached: Dictionary = _reached(node, node_path, property)
+	var reached: Dictionary = walk_to(node, node_path, property)
 	if reached.has("message"):
 		return reached
 
@@ -547,7 +563,7 @@ func get_property(params: Dictionary) -> Dictionary:
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(_read(holder, named)),
+		"value": _values.serialize(read_under(holder, named)),
 	}
 
 
@@ -563,10 +579,16 @@ func get_property(params: Dictionary) -> Dictionary:
 ## at a time rather than handed to that method, which answers null for a path that goes wrong
 ## halfway along and for one that ends on null.
 ##
+## A step written as a call, "get_viewport()", calls a method of that name that takes no arguments
+## and walks into what it returned. Some of what hangs off a node is only reachable by asking:
+## which control holds the focus is a question for the viewport a control is in, and the viewport
+## is a method's answer rather than a property. Spelled with the brackets so a reader sees a call
+## where one happens, and so a method can never shadow a property of the same name.
+##
 ## Answers with a `message` instead when a step along the way is not there or holds something that
 ## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
 ## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
-func _reached(node: Node, node_path: String, reaching: String) -> Dictionary:
+static func walk_to(node: Node, node_path: String, reaching: String) -> Dictionary:
 	var parts: PackedStringArray = reaching.split(":")
 	var holder: Variant = node
 	var called: String = node_path
@@ -574,7 +596,7 @@ func _reached(node: Node, node_path: String, reaching: String) -> Dictionary:
 		var named: String = parts[step]
 		if not _can_read(holder, named):
 			return {"type": "error", "message": _nothing_there(holder, named, called)}
-		holder = _read(holder, named)
+		holder = read_under(holder, named)
 		called = "%s:%s" % [called, named]
 		if not _can_hold(holder):
 			var wanted: String = parts[step + 1]
@@ -613,10 +635,33 @@ static func _can_read(holder: Variant, named: String) -> bool:
 		return map.has(named) or map.has(StringName(named))
 	if holder is Object:
 		var object: Object = holder
+		var method: String = _called(named)
+		if not method.is_empty():
+			return _arguments_required(object, method) == 0
 		return _has_property(object, named)
 	return false
 
 
+## The method a step written as a call names, "get_viewport()" being get_viewport, or "" for a
+## step that is a name.
+static func _called(named: String) -> String:
+	return named.trim_suffix("()") if named.ends_with("()") else ""
+
+
+## How many arguments [param method] on [param object] has to be given, or -1 when there is no such
+## method. Read off the method list rather than [method Object.has_method], because a path can only
+## call a method with nothing, and a method with a required argument called with nothing raises
+## inside the game rather than answering.
+static func _arguments_required(object: Object, method: String) -> int:
+	for entry: Dictionary in object.get_method_list():
+		if str(entry.get("name", "")) != method:
+			continue
+		var params: Array = entry.get("args", [])
+		var defaults: Array = entry.get("default_args", [])
+		return params.size() - defaults.size()
+	return -1
+
+
 ## Put [param value] where [param named] points. Only ever called once [method _can_read] agrees,
 ## and lists and maps are reference types, so writing into one reaches the game's own copy.
 static func _write(holder: Variant, named: String, value: Variant) -> void:
@@ -637,8 +682,9 @@ static func _write(holder: Variant, named: String, value: Variant) -> void:
 	object.set(named, value)
 
 
-## What [param holder] holds under [param named]. Only ever called once [method _can_read] agrees.
-static func _read(holder: Variant, named: String) -> Variant:
+## What [param holder] holds under [param named], or answers to it when [param named] is a call.
+## Only ever called once [method _can_read] agrees.
+static func read_under(holder: Variant, named: String) -> Variant:
 	if holder is Array:
 		var items: Array = holder
 		return items[_index_in(named, items.size())]
@@ -648,6 +694,9 @@ static func _read(holder: Variant, named: String) -> Variant:
 			return map[named]
 		return map[StringName(named)]
 	var object: Object = holder
+	var method: String = _called(named)
+	if not method.is_empty():
+		return object.call(method)
 	return object.get(named)
 
 
@@ -685,6 +734,23 @@ static func _nothing_there(holder: Variant, named: String, called: String) -> St
 		if keys.size() > 8:
 			rest = " and %d more" % [keys.size() - 8]
 		return "%s has no key %s; it is keyed by %s%s" % [called, named, ", ".join(some), rest]
+	var object: Object = holder
+	var method: String = _called(named)
+	if not method.is_empty():
+		var required: int = _arguments_required(object, method)
+		if required == -1:
+			return "%s has no method %s" % [called, method]
+		return (
+			"%s.%s takes %d argument%s, and a path can only call a method that takes none"
+			% [called, method, required, "" if required == 1 else "s"]
+		)
+	# A method spelled as a property is the likeliest thing behind a name the object has no property
+	# for, and the caller is one pair of brackets away from what they meant.
+	if object.has_method(named):
+		return (
+			"%s has no property %s; it has a method of that name, which a path calls as %s()"
+			% [called, named, named]
+		)
 	return "%s has no property %s" % [called, named]
 
 
@@ -710,18 +776,29 @@ func set_property(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	# Through a path as well, for the reason [method _reached] gives, and read back off the same
+	# Through a path as well, for the reason [method walk_to] gives, and read back off the same
 	# holder afterwards: a set that does not take says so by answering with the old value, which is
 	# how a typed container refusing a write is told from one accepting it.
-	var reached: Dictionary = _reached(node, node_path, property)
+	var reached: Dictionary = walk_to(node, node_path, property)
 	if reached.has("message"):
 		return reached
 
 	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
+	# A call can be walked through and read, and is not a place: what it returns is the method's
+	# to hand out, and writing "into" it would set nothing the game keeps.
+	if not _called(named).is_empty():
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s:%s is a call, and a call is not a place to write: name a property"
+				% [reached["called"], named]
+			)
+		}
 	if not _can_read(holder, named):
 		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
-	var old_value: Variant = _read(holder, named)
+	var old_value: Variant = read_under(holder, named)
 	# The same rule the call path holds: a value that cannot become what the property holds is
 	# refused rather than written. Writing it means the engine picks something, and what it picks
 	# for a word where a number goes is zero, which the answer then reports as the new value.
@@ -743,7 +820,7 @@ func set_property(params: Dictionary) -> Dictionary:
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(_read(holder, named))
+		"new_value": _values.serialize(read_under(holder, named))
 	}
 
 
@@ -760,10 +837,10 @@ func call_method(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	# Through a path as well, for the reason [method _reached] gives. What a game does hangs off its
+	# Through a path as well, for the reason [method walk_to] gives. What a game does hangs off its
 	# nodes as much as its state does, so reading `_game:run:day` while being unable to call
 	# `_game:run:advance` answers half of what a node holds and refuses the other half.
-	var reached: Dictionary = _reached(node, node_path, method)
+	var reached: Dictionary = walk_to(node, node_path, method)
 	if reached.has("message"):
 		return reached
 
@@ -782,6 +859,11 @@ func call_method(params: Dictionary) -> Dictionary:
 		}
 	var holder: Object = reached["holder"]
 	var named: String = reached["name"]
+	# The method a call ends on is the one being called whether or not it carries the brackets a
+	# step along the way would: "get_viewport():gui_get_focus_owner()" is the same call as without
+	# the last pair.
+	if not _called(named).is_empty():
+		named = _called(named)
 	if not holder.has_method(named):
 		return {"type": "error", "message": "%s has no method %s" % [reached["called"], named]}
 
@@ -846,8 +928,12 @@ func get_metrics(params: Dictionary) -> Dictionary:
 	return {"type": "metrics", "data": selected}
 
 
-func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_properties: bool) -> Dictionary:
+func _serialize_node_tree(
+	node: Node, depth: int, max_depth: int, include_properties: bool, named: Array[String]
+) -> Dictionary:
 	var result: Dictionary = _serialize_node(node, include_properties)
+	if not named.is_empty():
+		result["properties"] = _named_properties_of(node, str(result["path"]), named)
 
 	if depth < max_depth:
 		var children: Array = []
@@ -856,12 +942,28 @@ func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_proper
 		# it is wrong, and it is what sends somebody looking for another way to press the button.
 		# `depth` is what keeps the answer a size worth reading.
 		for child: Node in node.get_children(true):
-			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties))
+			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties, named))
 		result["children"] = children
 
 	return result
 
 
+## The named properties a node has, read the way a find reads its one: through a colon path as
+## well, and a name this node has not got is left out rather than answered null, since a tree
+## holds nodes of every class and a label's `text` is not a container's.
+func _named_properties_of(node: Node, path: String, named: Array[String]) -> Dictionary:
+	var properties: Dictionary = {}
+	for wanted: String in named:
+		var reached: Dictionary = walk_to(node, path, wanted)
+		if reached.has("message"):
+			continue
+		var holder: Variant = reached["holder"]
+		var name: String = reached["name"]
+		if _can_read(holder, name):
+			properties[wanted] = _values.serialize(read_under(holder, name))
+	return properties
+
+
 func _serialize_node(node: Node, include_properties: bool) -> Dictionary:
 	var result: Dictionary = {"name": node.name, "type": node.get_class(), "path": str(node.get_path())}
 

package/build/godot/addons/gdharness_runtime/runtime_waits.gd

@@ -115,7 +115,8 @@ func wait_until(params: Dictionary) -> Dictionary:
 			)
 		}
 	if not says.is_empty():
-		return await _wait_until_said(node_path, says, timeout_ms)
+		var include_hidden: bool = Read.as_bool(params.get("include_hidden", false))
+		return await _wait_until_said(node_path, says, timeout_ms, include_hidden)
 	if property.is_empty():
 		return {"type": "error", "message": "A property and a value, or says, are required"}
 	if not params.has("value"):
@@ -127,44 +128,15 @@ func wait_until(params: Dictionary) -> Dictionary:
 	# met" after the whole timeout, which is what a game that never reached the state answers too,
 	# so a mistyped name and a condition that did not happen read the same. The property read
 	# refuses that typo in one call, and two tools disagreeing about it is the fault.
-	var missing: String = Queries.nothing_under(node, property, node_path)
-	if not missing.is_empty():
-		return {"type": "error", "message": missing}
+	var watched: Dictionary = _watched(node, node_path, property)
+	if watched.has("message"):
+		return watched
 
-	var current: Variant = node.get(property)
+	var current: Variant = watched["value"]
 	var wanted: Variant = _values.fitted(params["value"], typeof(current))
-	# Refused before anything is evaluated, because the evaluation is what does the damage: an
-	# object compared against anything else is a hard error in GDScript, raised inside the game,
-	# which holds it at a debugger break. Both types are named because the caller cannot see either
-	# from where they are standing.
-	if not Values.comparable(current, wanted):
-		return {
-			"type": "error",
-			"message":
-			(
-				(
-					"%s.%s holds %s and the value to wait for is %s. Those cannot be compared, and"
-					+ " waiting on it would stop the game rather than answer about it."
-				)
-				% [node_path, property, type_string(typeof(current)), type_string(typeof(wanted))]
-			)
-		}
-	# And a value that cannot become what the property holds, which lands worse than the halt: a
-	# word where a number goes became 0.0, 0.0 already equalled the property, and the wait answered
-	# met the instant it started, about a state nobody asked about, with the real value beside it.
-	# A refusal is read and a met is acted on.
-	if not Values.acceptable(wanted, typeof(current)):
-		return {
-			"type": "error",
-			"message":
-			(
-				(
-					"%s.%s holds %s and the value to wait for is %s, which cannot become one:"
-					+ " waiting on it would answer about a state nobody asked for."
-				)
-				% [node_path, property, type_string(typeof(current)), type_string(typeof(wanted))]
-			)
-		}
+	var refused: String = _not_comparable(current, wanted, node_path, property)
+	if not refused.is_empty():
+		return {"type": "error", "message": refused}
 
 	var started: int = Time.get_ticks_msec()
 	# The type is checked every time round, not only at the top: a property that holds an object a
@@ -177,7 +149,10 @@ func wait_until(params: Dictionary) -> Dictionary:
 		await _host.get_tree().process_frame
 		if not is_instance_valid(node):
 			return {"type": "error", "message": "%s was freed while waiting" % node_path}
-		current = node.get(property)
+		watched = _watched(node, node_path, property)
+		if watched.has("message"):
+			return watched
+		current = watched["value"]
 
 	return {
 		"type": "condition",
@@ -189,6 +164,60 @@ func wait_until(params: Dictionary) -> Dictionary:
 	}
 
 
+## Why [param wanted] cannot be waited for against [param current], or "" when it can.
+##
+## Refused before anything is evaluated, because the evaluation is what does the damage: an object
+## compared against anything else is a hard error in GDScript, raised inside the game, which holds
+## it at a debugger break. Both types are named because the caller cannot see either from where
+## they are standing.
+##
+## And a value that cannot become what the property holds, which lands worse than the halt: a word
+## where a number goes became 0.0, 0.0 already equalled the property, and the wait answered met the
+## instant it started, about a state nobody asked about, with the real value beside it. A refusal
+## is read and a met is acted on.
+static func _not_comparable(current: Variant, wanted: Variant, node_path: String, property: String) -> String:
+	var types: Array[String] = [
+		node_path, property, type_string(typeof(current)), type_string(typeof(wanted))
+	]
+	if not Values.comparable(current, wanted):
+		return (
+			(
+				"%s.%s holds %s and the value to wait for is %s. Those cannot be compared, and"
+				+ " waiting on it would stop the game rather than answer about it."
+			)
+			% types
+		)
+	if not Values.acceptable(wanted, typeof(current)):
+		return (
+			(
+				"%s.%s holds %s and the value to wait for is %s, which cannot become one:"
+				+ " waiting on it would answer about a state nobody asked for."
+			)
+			% types
+		)
+	return ""
+
+
+## What [param property] reads as on [param node] right now, under `value`, or a `message` saying
+## why it cannot be read.
+##
+## Through the same walk as the property read, so a wait can watch what a node holds,
+## "_game:run:day", and what a call answers, "get_viewport():gui_get_focus_owner()". Walked from the
+## node every time rather than read off the holder found at the start, because a game replaces what
+## its nodes hold: a run object built afresh each day would leave a wait watching the day before. A
+## step that has gone in the meantime ends the wait with what went.
+static func _watched(node: Node, node_path: String, property: String) -> Dictionary:
+	var reached: Dictionary = Queries.walk_to(node, node_path, property)
+	if reached.has("message"):
+		return reached
+	var holder: Variant = reached["holder"]
+	var named: String = reached["name"]
+	var missing: String = Queries.nothing_under(holder, named, str(reached["called"]))
+	if not missing.is_empty():
+		return {"type": "error", "message": missing}
+	return {"value": Queries.read_under(holder, named)}
+
+
 ## Waits until something under [param node_path] has [param said] written on it.
 ##
 ## A screen rather than one node, because a panel following a clock builds its labels again every
@@ -196,34 +225,40 @@ func wait_until(params: Dictionary) -> Dictionary:
 ## on a node that was freed a frame later, and that is what it answered: the date along the top of a
 ## hall could not be waited on at all. What a caller is watching for is a word arriving on a screen,
 ## and the screen is the part that stays put.
-func _wait_until_said(node_path: String, said: String, timeout_ms: int) -> Dictionary:
+##
+## On the screen, which is to say shown: a control carrying the words while hidden satisfied the
+## wait at once, so a duel screen whose "Carry on" button exists hidden through the whole sweep
+## answered met in two milliseconds while the sweep was still animating, and every wait on that
+## screen fell back to counting frames. [param include_hidden] asks the other question, for a
+## caller waiting on words a hidden node holds.
+func _wait_until_said(node_path: String, said: String, timeout_ms: int, include_hidden: bool) -> Dictionary:
 	var started: int = Time.get_ticks_msec()
 	var words: String = Queries.as_said(said)
-	var found: bool = _anything_says(node_path, words)
+	var found: bool = _anything_says(node_path, words, include_hidden)
 	while not found and Time.get_ticks_msec() - started < timeout_ms:
 		await _host.get_tree().process_frame
-		found = _anything_says(node_path, words)
+		found = _anything_says(node_path, words, include_hidden)
 
 	return {
 		"type": "condition",
 		"path": node_path,
 		"says": said,
 		"met": found,
+		"include_hidden": include_hidden,
 		"elapsed_ms": Time.get_ticks_msec() - started,
 	}
 
 
-## Whether anything under [param node_path] says [param said], the node itself included. Hidden
-## nodes count, for the reason a find answers off them: a caller may be waiting for a dialog that
-## is built before it is shown.
-func _anything_says(node_path: String, said: String) -> bool:
+## Whether anything under [param node_path] says [param said], the node itself included, and shown
+## unless hidden ones are wanted too.
+func _anything_says(node_path: String, said: String, include_hidden: bool) -> bool:
 	var root: Node = _host.get_tree().root.get_node_or_null(node_path)
 	if root == null:
 		return false
 	var pending: Array[Node] = [root]
 	while not pending.is_empty():
 		var node: Node = pending.pop_back()
-		if Queries.said_by(node).containsn(said):
+		if Queries.said_by(node).containsn(said) and (include_hidden or Queries.shown(node)):
 			return true
 		pending.append_array(node.get_children(true))
 	return false