[ai] Resolve box paint roots and capture popup menus

Task: 2026/08/28/add-box-root-and-popup-menu-helpers

Author: john-preston

Telegram/CMakeLists.txt

@@ -1969,8 +1969,12 @@ PRIVATE
     test/test_ink.h
     test/test_launch_fuse.cpp
     test/test_launch_fuse.h
+    test/test_layer_root.cpp
+    test/test_layer_root.h
     test/test_log.cpp
     test/test_log.h
+    test/test_menu.cpp
+    test/test_menu.h
     test/test_messages.cpp
     test/test_messages.h
     test/test_open_handoff.cpp

Telegram/SourceFiles/test/README.md

@@ -179,6 +179,8 @@ Choose the narrowest helper that captures the real paint owner:
 | Static visible widget or local rect | `CaptureWidget` / `CaptureRect` |
 | Rect expressed in a child or offscreen content widget's coordinates | `CaptureMappedRect` |
 | Full box, layer owner, animation, or asynchronously populated surface | `Runner::captureWidget` |
+| Full box inside a layer | `PaintingLayerRoot` + `Runner::captureWidget`, or `CaptureInLayerRoot` |
+| Open `Ui::PopupMenu` | `CapturePopupMenu` |
 | Exact accepted frame plus numeric/raster assertions | `Runner::captureAndInspect` |
 | Small target comparison | `Crop`, `Zoom`, `ContactSheet` |
 | Foreground colour, contrast, or painted-band measurement | `MeasurePaintedInk` and the helpers in `test_ink.h` |
@@ -246,11 +248,13 @@ clicking.
 | `test_log.h` | Absolute flushed logs, steps, notes, checks whose `details` are printed on the passing verdict as well as the failing one, tolerances, geometry, completion markers. |
 | `test_probe.h` | Append-only observation records read only through a declared window, each carrying the time it was recorded; keyed issue/answer rows correlated into one round trip by key rather than by list position, refusing every reading it cannot positively pair; and scans that must match a control before a zero counts as absence. |
 | `test_widgets.h` | Safe typed discovery, live object/action publication, input, and postponed-call settlement. |
-| `test_capture.h` | In-process grabs, paint-root validation, mapped rects, blank detection, crops, zoom, contact sheets. |
+| `test_capture.h` | In-process grabs, paint-root validation, mapped rects, blank detection, painting-layer-root resolution for boxes inside a layer, crops, zoom, contact sheets. |
+| `test_layer_root.h` | The painting-layer-root resolver's own self-test: a plain `Ui::GenericBox` accepted as its own render root beside one that cleared `Qt::WA_OpaquePaintEvent`, refused and then captured through its `Ui::BoxLayerWidget`. |
 | `test_hover.h` | The input helpers' own self-test: a clicked-then-dragged and a never-touched `Ui::RoundButton` measured against the two fills their style names, proving a completed synthetic click and drag leave no hover. |
 | `test_ink.h` | Derived paint bands, colour separation, ink scans, counts, and contrast reports. |
 | `test_style.h` | Wait for palette/style samples to stabilize and assert a recorded baseline still holds. |
 | `test_panel.h` | Distinguish a live `Ui::SeparatePanel` from its faded/squeezed show-animation cache. |
+| `test_menu.h` | Deterministic `Ui::PopupMenu` capture whose readiness is content identity only, its `showingContent` reading, and its own self-test. |
 | `test_messages.h` | Lifetime-owned watcher for a matching newly sent server message. |
 | `test_history_fixtures.h` | Inject a caller-supplied service action into a real history as a regular or (negative-control) local item, with a caller-owned lifetime that removes it, and log the menu-gating predicates. |
 | `test_custom_emoji.h` | Supply an always-ready `Ui::Text::CustomEmoji` that fills the large-emoji box with worst-case ink, handed out only for document ids the scenario itself registered. |
@@ -384,7 +388,7 @@ need them.
 | Assertion/crash in a stage action | `.run` dereferenced an async object or a raw pointer outlived its owner. | Use `actOnWidget`, `QPointer`, or live publication. |
 | Wrong custom widget/button found | Unsafe Qt typed search or ambiguous descendant order. | Use the RTTI finders; for repeated/layer-owned controls publish the exact object/action. |
 | Expected mismatch reported as timeout | Product outcome was put in `until`. | Wait only for propagation/generation; assert and log the outcome in `then`/`captureAndInspect`. |
-| Blank or partial screenshot | Wrong paint owner, animation cache, or viewport clipping. | Use prepared capture, `PanelShowSettled`, the owning ancestor, or `CaptureMappedRect`. |
+| Blank or partial screenshot | Wrong paint owner, animation cache, or viewport clipping. | Use prepared capture, `PanelShowSettled`, the owning ancestor, or `CaptureMappedRect`; for a box inside a layer, `Test::PaintingLayerRoot`; for a `Ui::PopupMenu`, `Test::CapturePopupMenu`. |
 | Old palette/colour sampled | Style had not settled or moved between reference and target. | Use `StyleSettled` and `StyleBaseline`. |
 | A clicked button's measured fill matches no style constant, or `DeriveBand` returns `ok=0` with no rows for a widget plainly on screen | The reading was taken while the widget was still hovered by an earlier synthetic click, so it painted `textBgOver` where the check named `textBg`; before the input helpers delivered a leave this latched for the whole process. | Take the reading through helpers that leave the target pointerless (`Click`/`Drag` deliver a `QEvent::Leave`), and when a hovered reading is what is wanted, set the hover deliberately and name the fill the state actually implies. Confirm the instrument with the `test_hover.h` self-test. |
 | Emoji split or custom entity absent | UTF-16 code units or the wrong editor event route were synthesized. | Use grapheme-safe `TypeText` or one `CommitText` on the raw editor. |
@@ -398,6 +402,9 @@ need them.
 | A sweep reports a confident `found=0` that no repair ever changes | The enumeration structurally cannot reach the subject, so the zero was guaranteed before the run started and measures nothing. | Count through `Test::DiscriminatingScan` and feed it a known-present control; `report()` refuses to certify a zero the walk cannot tell from absence. |
 | A green log that does not say what its checks were made against, so a passing run cannot be audited after the fact | The reading was handed to `Test::Check` as `details` back when `details` was written only on the failing branch, or worked around by folding it into `what` or by emitting a `Note` beside the check that a reader then has to re-correlate by position. | Pass the reading as `Check`'s third argument: it is printed on the passing verdict too, as `TEST_RESULT: PASS: <what> - <details>`. Keep only failure-only text behind `ok ? QString() : ...`, which still prints the bare passing line. |
 | A round trip reported as a negative or otherwise impossible number, or a pair count that does not match the issue count | Two lists were related by position - an issue list against an answer list, or a row list against a parallel `crl::time` vector indexed at `mark + i` - so one extra or missing element on either side paired a row with another row's time, and the reading was emitted as a `Note` that failed nothing. | Record both sides into one `Test::Probe` with `recordIssue`/`recordAnswer` and read them through `checkRoundTripSince(mark, key)`: it pairs by key, discards and names every answer not strictly later than its issue, and refuses as a FAIL carrying the tallies rather than reporting an interval it did not positively pair. Read a bare time through `timedRowsSince`, which carries each plain row's own time. |
+| A capture or `captureWidget` stage times out and its details carry `render root paints no background of its own: ... - grab N...BoxLayerWidget... instead (unpainted 0/1000)` | The render root was the box, and that box had cleared `Qt::WA_OpaquePaintEvent`. `Ui::BoxContent`'s constructor sets that attribute, so a plain box paints its own background and is accepted - but `setNoContentMargin(true)`, which 53 product call sites use, clears it again, and then the box paints no background of its own and `PreparedWidgetCapture::prepare()` refuses every frame it is offered; the poll can only end in a timeout. | Resolve the root with `Test::PaintingLayerRoot(box)` and capture the `Ui::BoxLayerWidget` it answers, or use `Test::CaptureInLayerRoot(box, name)` for a frame cropped to the box (it composes `CaptureMappedRect`, so a box that maps outside its layer is still a named FAIL). The refusal is naming the right widget - do not widen it. |
+| A menu capture times out with `showingContent=0` in its last state, or the popup vanishes mid-stage | The readiness waited on the inner `Ui::Menu`'s visibility. `Ui::PopupMenu::startShowAnimation()` calls `hideChildren()`, and the children come back only from the final `paintEvent`'s `Ui::PostponeCall` - a side effect no `-testagent` run is guaranteed to reach - so the wait can last until the popup dies of a focus-out. A one-shot grab in the turn that opened the menu is the opposite failure: it lands on a show-animation frame with nothing drawn. | Capture with `Test::CapturePopupMenu`: its readiness carries content identity only - the menu exists, is visible, has non-empty geometry and carries actions - and the prepared capture's own blank-frame refusal decides when the frame is good. `showingContent` belongs in the details, never in the gate. Do not use `Test::PaintingLayerRoot` on a popup: it sets `Qt::WA_NoSystemBackground`, so the blank-root refusal never applies, and it is its own window. |
+| A stage times out although its own details show every precondition met and the action already fired - for example `box=1 toggle=1 popups=0` after a click on a control in a freshly shown layer | One synthesized click on a control in a layer that is still settling intermittently does not land, and nothing observes that until the stage's 10-second timeout ends the whole scenario. The input helpers are not at fault: `Test::Click` and `Test::Drag` deliver press, release and a `QEvent::Leave` synchronously and drain every `Ui::PostponeCall` before returning. | Make the click self-correcting in the scenario, not in the helper: read the effect, click the same `QPointer`-guarded widget once more if it did not appear, and `Note` which attempt worked so the flake rate stays visible. Establish first, from the production callback, that a repeat is provably a no-op - the details-menu toggle's first statement is `if (*menu) { return; }`. |
 
 Classify a sound assertion against changed behavior as an implementation bug,
 not a test flaw. Classify a wrong fixture, target, readiness model, event
@@ -409,5 +416,6 @@ When a flaw's cause is the instrument idiom rather than this task's fixture,
 repair it here as well as in the overlay: add the missing helper, tighten an
 existing contract, or add its row to the table above, in the same run that
 diagnosed it. A diagnosis that stays in one task's notes is rediscovered by
-the next task, which is how the two rows above cost four runs each before
-they were written down.
+the next task, which is how the `Test::Probe` window row and the
+`Test::DiscriminatingScan` row above cost four runs each before they were
+written down.

Telegram/SourceFiles/test/test_capture.cpp

@@ -10,6 +10,7 @@ For license and copyright information please follow this link:
 #include "test/test_capture.h"
 
 #include "test/test_log.h"
+#include "ui/layers/box_layer_widget.h"
 #include "ui/ui_utility.h"
 
 #include "styles/palette.h"
@@ -24,6 +25,7 @@ constexpr auto kContactSheetGap = 8;
 constexpr auto kCoverageSamples = 32;
 constexpr auto kUnpaintedMinPermille = 100;
 constexpr auto kBackgroundOwnerHops = 6;
+constexpr auto kWalkedChainHead = 3;
 
 [[nodiscard]] QString WithPngExtension(const QString &name) {
 	return name.endsWith(u".png"_q, Qt::CaseInsensitive)
@@ -126,13 +128,6 @@ constexpr auto kBackgroundOwnerHops = 6;
 	return (1000 * unpainted) / int(points.size());
 }
 
-[[nodiscard]] QString WidgetDescription(not_null<QWidget*> widget) {
-	const auto &instance = *widget;
-	return u"%1 %2"_q.arg(
-		QString::fromUtf8(typeid(instance).name()),
-		RectText(widget->geometry()));
-}
-
 [[nodiscard]] QString BackgroundOwnerDetails(
 		not_null<QWidget*> widget,
 		const QRect &logicalRect) {
@@ -145,9 +140,12 @@ constexpr auto kBackgroundOwnerHops = 6;
 		if (!mapped.isEmpty()) {
 			const auto unpainted = UnpaintedPermille(ancestor, mapped);
 			if (unpainted < kUnpaintedMinPermille) {
-				return u"grab %1 instead (unpainted %2/1000)"_q
+				return u"grab %1 instead (unpainted %2/1000)%3"_q
 					.arg(WidgetDescription(ancestor))
-					.arg(unpainted);
+					.arg(unpainted)
+					.arg(dynamic_cast<Ui::BoxLayerWidget*>(ancestor)
+						? u" - Test::PaintingLayerRoot() resolves it"_q
+						: QString());
 			}
 		}
 		ancestor = (ancestor == top) ? nullptr : ancestor->parentWidget();
@@ -195,8 +193,31 @@ constexpr auto kBackgroundOwnerHops = 6;
 		.arg(BackgroundOwnerDetails(widget, logicalRect));
 }
 
+// The walk a refusal prints always names the window it stopped at, and never
+// more than kWalkedChainHead entries before it, so a target buried deep in a
+// widget tree cannot turn one refusal into a multi-kilobyte log line.
+[[nodiscard]] QString ElidedChain(const QStringList &walked) {
+	if (walked.size() <= kWalkedChainHead + 1) {
+		return walked.join(u" < "_q);
+	}
+	auto shown = QStringList();
+	for (auto i = 0; i != kWalkedChainHead; ++i) {
+		shown.push_back(walked[i]);
+	}
+	shown.push_back(u"\u2026"_q);
+	shown.push_back(walked.back());
+	return shown.join(u" < "_q);
+}
+
 } // namespace
 
+QString WidgetDescription(not_null<QWidget*> widget) {
+	const auto &instance = *widget;
+	return u"%1 %2"_q.arg(
+		QString::fromUtf8(typeid(instance).name()),
+		RectText(widget->geometry()));
+}
+
 QImage GrabWidget(not_null<QWidget*> widget) {
 	return Ui::GrabWidgetToImage(widget, QRect(), st::windowBg->c);
 }
@@ -371,6 +392,40 @@ bool CaptureMappedRect(
 		name);
 }
 
+PaintingLayerRootResult PaintingLayerRoot(QWidget *box) {
+	if (!box) {
+		return {
+			.refusal = u"no widget was handed to the painting layer root "
+				u"resolver"_q,
+		};
+	}
+	auto walked = QStringList();
+	for (auto widget = box; widget; widget = widget->parentWidget()) {
+		if (const auto layer = dynamic_cast<Ui::BoxLayerWidget*>(widget)) {
+			return { .widget = layer };
+		}
+		walked.push_back(WidgetDescription(widget));
+		if (widget == widget->window()) {
+			break;
+		}
+	}
+	return {
+		.refusal = u"no Ui::BoxLayerWidget between the target and its own "
+			u"window, so it is not a box inside a layer and has no painting "
+			u"layer root; walked %1 widget(s) and stopped at the window: "
+			u"[%2]"_q.arg(walked.size()).arg(ElidedChain(walked)),
+	};
+}
+
+bool CaptureInLayerRoot(not_null<QWidget*> box, const QString &name) {
+	const auto root = PaintingLayerRoot(box);
+	if (!root.resolved()) {
+		Fail(u"capture %1"_q.arg(name), root.refusal);
+		return false;
+	}
+	return CaptureMappedRect(root.widget, box, box->rect(), name);
+}
+
 QImage Crop(const QImage &image, const QRect &pixelRect) {
 	const auto bounded = pixelRect.intersected(image.rect());
 	return bounded.isEmpty() ? QImage() : image.copy(bounded);

Telegram/SourceFiles/test/test_capture.h

@@ -26,6 +26,12 @@ namespace Test {
 	not_null<QWidget*> widget,
 	const QRect &logicalRect);
 
+// The harness's one widget-identity formatter: the typeid name of the live
+// instance plus its "x,y WxH" geometry. Every refusal here prints identities
+// through it, so two logs name the same widget the same way and stay
+// comparable line by line.
+[[nodiscard]] QString WidgetDescription(not_null<QWidget*> widget);
+
 // Near-uniform images are capture failures, never evidence.
 [[nodiscard]] bool LooksBlank(const QImage &image);
 
@@ -76,6 +82,55 @@ bool CaptureMappedRect(
 	const QRect &logicalRect,
 	const QString &name);
 
+// The one render root a capture of a box inside a layer may use.
+//
+// Ui::BoxContent's constructor sets Qt::WA_OpaquePaintEvent
+// (ui/layers/box_content.h:117-119) and BoxContent::paintEvent fills with the
+// delegate's style().bg only while that attribute is set
+// (ui/layers/box_content.cpp:450-459), so a plain Ui::GenericBox paints its
+// own background and the blank-root refusal short-circuits on it: a plain box
+// is NOT refused. setNoContentMargin(true) clears the attribute again
+// (box_content.h:224-230), which is what 53 call sites under
+// Telegram/SourceFiles/ do, and that is the only shape the refusal fires for.
+// Such a box paints no background of its own, and the Ui::BoxLayerWidget the
+// layer stack wrapped it in is what paints instead
+// (ui/layers/box_layer_widget.cpp:120-141), with the box as its direct child
+// (:46) - so the walk is normally one hop, but it is written as a walk
+// because a scenario resolves from a descendant just as often.
+//
+// Run 1 of 2026/08/28/complete-server-history-details-hash-and-paging handed
+// the bare box to Runner::captureAndInspect: PreparedWidgetCapture::prepare()
+// refused every frame it was offered and the stage could only end in a
+// timeout, although the refusal it printed already named the widget to grab -
+// "grab N2Ui14BoxLayerWidgetE 14,72 364x413 instead (unpainted 0/1000)".
+// This answers that once instead of leaving every call site to hand-roll it.
+//
+// The walk stops at widget->window() and refuses there, so it never leaves
+// the target's own window looking for a layer. That is also why it must never
+// be used on a Ui::PopupMenu: a popup is its own window, so the walk refuses
+// on its first hop, and Ui::PopupMenu::init() sets Qt::WA_NoSystemBackground
+// (ui/widgets/popup_menu.cpp:126), so the blank-root refusal never applies to
+// it and it needs no layer root at all.
+//
+// |widget| is non-null exactly when |refusal| is empty: a caller cannot take
+// the pointer without being handed the reason there is none.
+struct PaintingLayerRootResult {
+	QWidget *widget = nullptr;
+	QString refusal;
+
+	[[nodiscard]] bool resolved() const {
+		return widget != nullptr;
+	}
+};
+
+[[nodiscard]] PaintingLayerRootResult PaintingLayerRoot(QWidget *box);
+
+// Saves the box's own rect, grabbed out of the Ui::BoxLayerWidget that paints
+// it. An unresolved root is a logged FAIL carrying the refusal above, never a
+// null the caller has to re-check before CaptureMappedRect, which this
+// composes and which takes not_null<QWidget*>.
+bool CaptureInLayerRoot(not_null<QWidget*> box, const QString &name);
+
 [[nodiscard]] QImage Crop(const QImage &image, const QRect &pixelRect);
 
 // Nearest-neighbor upscale for readable small-target evidence.