gdharness 0.6.6 → 0.6.8

package/build/cli.js

@@ -15785,7 +15785,7 @@ var init_tool_definitions = __esm(() => {
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
         text: {
-          summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+          summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
           requires: []
         },
         find: {
@@ -15893,7 +15893,7 @@ var init_tool_definitions = __esm(() => {
         action: { summary: "press an action, or hold it", requires: ["action"] },
         key: { summary: "press a key, or hold it", requires: ["keycode"] },
         text: {
-          summary: "type a string wherever the focus is, a character at a time",
+          summary: "type a string into the field being edited, a character at a time, and say what it landed in",
           requires: ["text"]
         },
         mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
@@ -15905,14 +15905,17 @@ var init_tool_definitions = __esm(() => {
       description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, or a property reaching a value. Needs the game running with the runtime addon.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
-        frames: { type: "number", description: "frames: how many to let pass, 1 to 600." },
+        frames: {
+          type: "number",
+          description: "frames: how many to let pass, 1 to 600. More than that is refused."
+        },
         nodePath: { type: "string", description: "signal, until: the node." },
         signal: { type: "string", description: "signal: the signal name." },
         property: { type: "string", description: "until: the property name." },
         value: { description: "until: the value to wait for, fitted to the property's type." },
         timeoutMs: {
           type: "number",
-          description: "signal, until: how long to wait before answering anyway. Default 5000."
+          description: "signal, until: how long to wait before answering anyway, 1 to 120000. Default 5000."
         }
       },
       requires: [],
@@ -38827,7 +38830,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Where a control is, and whether it is visible | \`runtime_inspect\` \`find\`, \`rect\` |
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
-| Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` |
+| Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\`; a submitted field has to be clicked again |
 | Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
 | Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says |
 | Answer a dialog, or press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |

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

@@ -161,6 +161,11 @@ func inject_text(params: Dictionary) -> Dictionary:
 		return {"type": "error", "message": "text required"}
 
 	var viewport: Viewport = _host.get_tree().root
+	var focused: Control = viewport.gui_get_focus_owner()
+	var shut: String = _shut_to_typing(focused)
+	if not shut.is_empty():
+		return {"type": "error", "message": shut}
+
 	for index: int in text.length():
 		var down: InputEventKey = _typed(text.unicode_at(index))
 		viewport.push_input(down)
@@ -169,7 +174,41 @@ func inject_text(params: Dictionary) -> Dictionary:
 		up.pressed = false
 		viewport.push_input(up)
 
-	return {"type": "input_injected", "input_type": "text", "text": text, "characters": text.length()}
+	# Where it went, which is the one thing a caller cannot see from here. Null is a game reading
+	# keys for itself with nothing focused, which is a real thing to be typing at.
+	var into: Variant = null
+	if focused != null:
+		into = str(focused.get_path())
+
+	return {
+		"type": "input_injected",
+		"input_type": "text",
+		"text": text,
+		"characters": text.length(),
+		"into": into,
+	}
+
+
+## Why nothing typed would reach [param focused], or "" when it would.
+##
+## Having the focus is not the same as being edited. Since Godot 4.4 a field is focused and shut
+## until something opens it, which is what a click does and what submitting undoes: press Enter in
+## a box and it keeps the focus and drops every key that arrives afterwards. Typing into one
+## answered that the characters had gone in and put nothing anywhere, which is the shape a refusal
+## exists to prevent. Measured on a spin box in a real game: `has_focus` true, `is_editing` false,
+## three characters reported and the field unchanged.
+##
+## Only a [LineEdit] is refused: it is the one control the engine will say this about, since
+## [TextEdit] has no editing state of its own. A game reading keys for itself is typed at with
+## nothing focused at all, and that is not this tool's business to judge.
+static func _shut_to_typing(focused: Control) -> String:
+	var field: LineEdit = focused as LineEdit
+	if field == null or field.is_editing():
+		return ""
+	return (
+		"%s has the focus and is not being edited, so nothing typed lands in it. Click it first."
+		% focused.get_path()
+	)
 
 
 ## The key press that produces [param glyph], as a keyboard would send it.
@@ -299,6 +338,24 @@ static func _centre_of(control: Control) -> Vector2:
 ## the control within the outer one, so the outer has to be asked after the inner has finished
 ## moving it. A control with no ScrollContainer over it moves nothing and answers false, which is
 ## what keeps the refusal below saying the right thing about a control that is simply off screen.
+## Whether [param centre] is somewhere a click can reach it: inside the viewport, and inside every
+## ScrollContainer between the control and the root, each of which clips what it holds.
+static func _in_sight(control: Control, viewport: Viewport, centre: Vector2) -> bool:
+	if not viewport.get_visible_rect().has_point(centre):
+		return false
+	var walking: Node = control.get_parent()
+	while walking != null:
+		var holder: ScrollContainer = walking as ScrollContainer
+		# Carried into the same space the centre is in, which is the canvas rather than the
+		# container's own: the two are only the same while nothing above it is transformed.
+		if holder != null:
+			var seen: Rect2 = holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size)
+			if not seen.has_point(centre):
+				return false
+		walking = walking.get_parent()
+	return true
+
+
 static func _scroll_into_view(control: Control) -> bool:
 	var moved: bool = false
 	var walking: Node = control.get_parent()
@@ -341,12 +398,17 @@ func click(params: Dictionary) -> Dictionary:
 	var viewport: Viewport = _clicking_viewport(control)
 	var centre: Vector2 = _centre_of(control)
 
-	# A control below the fold of a ScrollContainer is not out of reach, it is one scroll away,
+	# A control out of sight inside a ScrollContainer is not out of reach, it is one scroll away,
 	# which is what a person does without thinking about it before they click. Refusing it
 	# instead sent callers to emit the button's own signal, which presses nothing, runs none of
 	# the input path and reports success.
+	#
+	# Out of sight against what it is clipped to rather than against the viewport: a row scrolled
+	# off the top of its container is inside the viewport, behind whatever is drawn up there, so
+	# the click went to that instead and said so. Measured on a hall whose staff panel had been
+	# scrolled past: the button was at y 69 and its container started at y 166.
 	var scrolled: bool = false
-	if not viewport.get_visible_rect().has_point(centre):
+	if not _in_sight(control, viewport, centre):
 		scrolled = _scroll_into_view(control)
 		if scrolled:
 			# A container moves its child on the next layout pass rather than inside the call.

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

@@ -174,19 +174,33 @@ func read_text(params: Dictionary) -> Dictionary:
 
 ## Walks [param node] depth first, which is the order the screen is laid out in and the order a
 ## person reads it.
+##
+## Internal children as well, because the number in a SpinBox is one: the field a player reads it
+## in is a LineEdit the engine builds inside the box and leaves out of `get_children()`, so a
+## screen full of forms answered with every label on it and none of the values in it. The hidden
+## check covers a [Window] for the same walk: a dropdown's popup is a child that is not drawn
+## until it is opened, and reading a closed menu would put every item on the screen.
 func _read_into(node: Node, include_hidden: bool, into: PackedStringArray) -> void:
 	if into.size() >= READ_LIMIT:
 		return
-	var control: CanvasItem = node as CanvasItem
-	if not include_hidden and control != null and not control.visible:
+	if not include_hidden and not _drawn(node):
 		return
 	var said: String = _said_by(node)
 	if not said.is_empty():
 		into.append(said)
-	for child: Node in node.get_children():
+	for child: Node in node.get_children(true):
 		_read_into(child, include_hidden, into)
 
 
+## Whether [param node] is on the screen at all, for the two kinds of thing that can be hidden.
+static func _drawn(node: Node) -> bool:
+	var control: CanvasItem = node as CanvasItem
+	if control != null:
+		return control.visible
+	var window: Window = node as Window
+	return window == null or window.visible
+
+
 ## What one node says, or "" for a node that says nothing. Anything with a `text` property, which
 ## is every label, button and field the interface is built out of.
 static func _said_by(node: Node) -> String:

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

@@ -9,6 +9,9 @@ const Values = preload("runtime_values.gd")
 ## since given up on the reply.
 const CEILING_MSEC: int = 120000
 
+## The most frames one wait may cover, which is about half a minute of a game drawing slowly.
+const MOST_FRAMES: int = 600
+
 var _host: Node
 var _values: Values
 
@@ -18,8 +21,21 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## Refuses [param asked] rather than bringing it inside [param least] to [param most].
+##
+## A number quietly brought inside the range is a wait that did not last as long as the caller
+## believes and a timeout that gave up sooner: asking for 900 frames and waiting 600 reads as 900
+## frames of the game having passed, and everything measured off it is out by that much.
+static func _out_of_range(named: String, asked: int, least: int, most: int) -> Dictionary:
+	return {
+		"type": "error", "message": "%s is %d, and %s takes %d to %d." % [named, asked, named, least, most]
+	}
+
+
 func wait_frames(params: Dictionary) -> Dictionary:
-	var frames: int = clampi(int(params.get("frames", 1)), 1, 600)
+	var frames: int = int(params.get("frames", 1))
+	if frames < 1 or frames > MOST_FRAMES:
+		return _out_of_range("frames", frames, 1, MOST_FRAMES)
 	var started: int = Time.get_ticks_msec()
 	for _frame: int in frames:
 		await _host.get_tree().process_frame
@@ -30,7 +46,9 @@ func wait_frames(params: Dictionary) -> Dictionary:
 func wait_signal(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var signal_name: String = str(params.get("signal", ""))
-	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	var timeout_ms: int = int(params.get("timeout_ms", 5000))
+	if timeout_ms < 1 or timeout_ms > CEILING_MSEC:
+		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
 	if node_path.is_empty() or signal_name.is_empty():
 		return {"type": "error", "message": "Node path and signal name required"}
 
@@ -65,7 +83,9 @@ func wait_signal(params: Dictionary) -> Dictionary:
 func wait_until(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
-	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	var timeout_ms: int = int(params.get("timeout_ms", 5000))
+	if timeout_ms < 1 or timeout_ms > CEILING_MSEC:
+		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
 	if node_path.is_empty() or property.is_empty():
 		return {"type": "error", "message": "Node path and property required"}
 	if not params.has("value"):

package/build/index.js

@@ -28339,7 +28339,7 @@ var TOOL_SPECS = [
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
       text: {
-        summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+        summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
         requires: []
       },
       find: {
@@ -28447,7 +28447,7 @@ var TOOL_SPECS = [
       action: { summary: "press an action, or hold it", requires: ["action"] },
       key: { summary: "press a key, or hold it", requires: ["keycode"] },
       text: {
-        summary: "type a string wherever the focus is, a character at a time",
+        summary: "type a string into the field being edited, a character at a time, and say what it landed in",
         requires: ["text"]
       },
       mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
@@ -28459,14 +28459,17 @@ var TOOL_SPECS = [
     description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, or a property reaching a value. Needs the game running with the runtime addon.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
-      frames: { type: "number", description: "frames: how many to let pass, 1 to 600." },
+      frames: {
+        type: "number",
+        description: "frames: how many to let pass, 1 to 600. More than that is refused."
+      },
       nodePath: { type: "string", description: "signal, until: the node." },
       signal: { type: "string", description: "signal: the signal name." },
       property: { type: "string", description: "until: the property name." },
       value: { description: "until: the value to wait for, fitted to the property's type." },
       timeoutMs: {
         type: "number",
-        description: "signal, until: how long to wait before answering anyway. Default 5000."
+        description: "signal, until: how long to wait before answering anyway, 1 to 120000. Default 5000."
       }
     },
     requires: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",