Add wait-for-region-colour (appear/vanish)

Author: JE-Chen

.idea/workspace.xml

@@ -1,5 +1,11 @@
 # 本次更新 — AutoControl
 
+## 本次更新 (2026-06-23) — 等待区域颜色
+
+阻塞直到某颜色填满(或离开)屏幕区域。完整参考:[`docs/source/Zh/doc/new_features/v121_features_doc.rst`](../docs/source/Zh/doc/new_features/v121_features_doc.rst)。
+
+- **`wait_until_color`**(`AC_wait_color`):`wait_for_pixel` 精确比对单点、`wait_until_pixel_changes` 检测单点任何变化——两者都无法等「状态灯变绿」/「进度条填满」/「红色横幅消失」。本功能计数区域中接近 `target_rgb`(在 `tolerance` 内)的像素,当比例越过 `min_fraction`(或 `present=False` 时低于)即成功。可注入 sampler、无头可测。纯标准库。
+
 ## 本次更新 (2026-06-23) — 相对鼠标移动
 
 从当前位置将指针位移一个增量。完整参考:[`docs/source/Zh/doc/new_features/v120_features_doc.rst`](../docs/source/Zh/doc/new_features/v120_features_doc.rst)。

README/WHATS_NEW_zh-CN.md

@@ -1,5 +1,11 @@
 # 本次更新 — AutoControl
 
+## 本次更新 (2026-06-23) — 等待區域顏色
+
+阻塞直到某顏色填滿(或離開)螢幕區域。完整參考:[`docs/source/Zh/doc/new_features/v121_features_doc.rst`](../docs/source/Zh/doc/new_features/v121_features_doc.rst)。
+
+- **`wait_until_color`**(`AC_wait_color`):`wait_for_pixel` 精確比對單點、`wait_until_pixel_changes` 偵測單點任何變化——兩者都無法等「狀態燈變綠」/「進度條填滿」/「紅色橫幅消失」。本功能計數區域中接近 `target_rgb`(在 `tolerance` 內)的像素,當比例越過 `min_fraction`(或 `present=False` 時低於)即成功。可注入 sampler、無頭可測。純標準函式庫。
+
 ## 本次更新 (2026-06-23) — 相對滑鼠移動
 
 從目前位置將指標位移一個增量。完整參考:[`docs/source/Zh/doc/new_features/v120_features_doc.rst`](../docs/source/Zh/doc/new_features/v120_features_doc.rst)。

README/WHATS_NEW_zh-TW.md

@@ -1,5 +1,11 @@
 # What's New — AutoControl
 
+## What's new (2026-06-23) — Wait for Region Colour
+
+Block until a colour fills (or leaves) a screen region. Full reference: [`docs/source/Eng/doc/new_features/v121_features_doc.rst`](docs/source/Eng/doc/new_features/v121_features_doc.rst).
+
+- **`wait_until_color`** (`AC_wait_color`): `wait_for_pixel` matches one point exactly and `wait_until_pixel_changes` detects any change at one point — neither waits for "the status light turns green" / "the progress bar fills" / "the red banner is gone". This counts pixels within `tolerance` of `target_rgb` over a region and succeeds when that fraction crosses `min_fraction` (or drops below it, `present=False`). Injectable sampler, headless-testable. Pure-stdlib.
+
 ## What's new (2026-06-23) — Relative Mouse Movement
 
 Nudge the pointer by a delta from where it is. Full reference: [`docs/source/Eng/doc/new_features/v120_features_doc.rst`](docs/source/Eng/doc/new_features/v120_features_doc.rst).

WHATS_NEW.md

@@ -0,0 +1,39 @@
+Wait for Region Colour
+======================
+
+``wait_for_pixel`` matches a single point exactly and ``wait_until_pixel_changes``
+detects *any* change at one point — neither answers "wait until this status light
+turns green", "until the progress bar is mostly filled", or "until the red error
+banner is gone". This adds a region-colour wait to the ``smart_waits`` family.
+
+The pixel counting is a pure helper and :func:`wait_until_color` takes an
+injectable ``sampler``, so the loop is headless-testable without a real screen.
+Imports no ``PySide6``.
+
+Headless API
+------------
+
+.. code-block:: python
+
+    from je_auto_control import wait_until_color
+
+    # wait until ≥ 60% of the region is (near) green
+    wait_until_color(region=[10, 10, 210, 40], target_rgb=[0, 200, 0],
+                     tolerance=15, min_fraction=0.6, timeout_s=20)
+
+    # wait until a red banner disappears
+    wait_until_color(region=[0, 0, 800, 60], target_rgb=[200, 0, 0],
+                     present=False, timeout_s=10)
+
+Pixels within ``tolerance`` (per channel) of ``target_rgb`` are counted. With
+``present=True`` the wait succeeds once that fraction reaches ``min_fraction``;
+with ``present=False`` once it drops below it. The result is a ``WaitOutcome``
+(``succeeded`` / ``reason`` / ``elapsed_s`` / ``samples_taken``).
+
+Executor commands
+-----------------
+
+``AC_wait_color`` takes ``target_rgb`` (and optional ``region``) as JSON arrays
+plus ``tolerance`` / ``min_fraction`` / ``present`` / ``timeout_s`` /
+``poll_interval_s``, and returns the ``WaitOutcome`` dict. It is exposed as the
+MCP tool ``ac_wait_color`` and as a Script Builder command under **Flow**.

docs/source/Eng/doc/new_features/v121_features_doc.rst

@@ -143,6 +143,7 @@ Comprehensive guides for all AutoControl features.
    doc/new_features/v118_features_doc
    doc/new_features/v119_features_doc
    doc/new_features/v120_features_doc
+   doc/new_features/v121_features_doc
    doc/ocr_backends/ocr_backends_doc
    doc/observability/observability_doc
    doc/operations_layer/operations_layer_doc

docs/source/Eng/eng_index.rst

@@ -0,0 +1,35 @@
+等待區域顏色
+============
+
+``wait_for_pixel`` 精確比對單一點,``wait_until_pixel_changes`` 偵測單點的*任何*變化——兩者都無法回答
+「等到狀態燈變綠」、「等到進度條大致填滿」或「等到紅色錯誤橫幅消失」。本功能為 ``smart_waits`` 家族加入
+區域顏色等待。
+
+像素計數為純函式輔助,:func:`wait_until_color` 接受可注入的 ``sampler``,因此迴圈可在無真實螢幕下測試。
+不匯入 ``PySide6``。
+
+無頭 API
+--------
+
+.. code-block:: python
+
+    from je_auto_control import wait_until_color
+
+    # 等到區域中 ≥ 60% 為(接近)綠色
+    wait_until_color(region=[10, 10, 210, 40], target_rgb=[0, 200, 0],
+                     tolerance=15, min_fraction=0.6, timeout_s=20)
+
+    # 等到紅色橫幅消失
+    wait_until_color(region=[0, 0, 800, 60], target_rgb=[200, 0, 0],
+                     present=False, timeout_s=10)
+
+在 ``tolerance``(各通道)內接近 ``target_rgb`` 的像素會被計數。``present=True`` 時,當該比例達到
+``min_fraction`` 即成功;``present=False`` 時,當其低於該值即成功。結果為 ``WaitOutcome``
+(``succeeded`` / ``reason`` / ``elapsed_s`` / ``samples_taken``)。
+
+執行器命令
+----------
+
+``AC_wait_color`` 接受 ``target_rgb``(與選用的 ``region``)為 JSON 陣列,以及 ``tolerance`` / ``min_fraction`` /
+``present`` / ``timeout_s`` / ``poll_interval_s``,並回傳 ``WaitOutcome`` dict。它以 MCP 工具 ``ac_wait_color``
+以及 Script Builder 中 **Flow** 分類下的命令提供。

docs/source/Zh/doc/new_features/v121_features_doc.rst

@@ -143,6 +143,7 @@ AutoControl 所有功能的完整使用指南。
    doc/new_features/v118_features_doc
    doc/new_features/v119_features_doc
    doc/new_features/v120_features_doc
+   doc/new_features/v121_features_doc
    doc/ocr_backends/ocr_backends_doc
    doc/observability/observability_doc
    doc/operations_layer/operations_layer_doc

docs/source/Zh/zh_index.rst

@@ -610,10 +610,11 @@
 )
 # Smart waits (frame-diff replacements for time.sleep)
 from je_auto_control.utils.smart_waits import (
-    WaitOutcome, wait_until_clipboard_changes, wait_until_file,
-    wait_until_gone, wait_until_image_gone, wait_until_pixel_changes,
-    wait_until_port, wait_until_process, wait_until_region_idle,
-    wait_until_screen_stable, wait_until_text_gone, wait_until_window_closed,
+    WaitOutcome, wait_until_clipboard_changes, wait_until_color,
+    wait_until_file, wait_until_gone, wait_until_image_gone,
+    wait_until_pixel_changes, wait_until_port, wait_until_process,
+    wait_until_region_idle, wait_until_screen_stable, wait_until_text_gone,
+    wait_until_window_closed,
 )
 # Visual regression (golden-image comparison)
 from je_auto_control.utils.visual_regression import (
@@ -1242,6 +1243,7 @@ def start_autocontrol_gui(*args, **kwargs):
     "wait_until_clipboard_changes", "wait_until_window_closed",
     "wait_until_file", "wait_until_port", "wait_until_process",
     "wait_until_gone", "wait_until_image_gone", "wait_until_text_gone",
+    "wait_until_color",
     # Visual regression + state machine
     "take_golden", "compare_to_golden", "image_difference",
     "DiffResult", "MaskRegion",

je_auto_control/__init__.py

@@ -478,6 +478,22 @@ def _add_flow_specs(specs: List[CommandSpec]) -> None:
         ),
         description="Block until on-screen text (OCR) disappears.",
     ))
+    specs.append(CommandSpec(
+        "AC_wait_color", "Flow", "Wait for Region Colour",
+        fields=(
+            FieldSpec("target_rgb", FieldType.STRING, placeholder="[0, 200, 0]"),
+            FieldSpec("region", FieldType.STRING, optional=True,
+                      placeholder="[left, top, right, bottom]"),
+            FieldSpec("tolerance", FieldType.INT, optional=True, default=10),
+            FieldSpec("min_fraction", FieldType.FLOAT, optional=True,
+                      default=0.5, min_value=0.0, max_value=1.0),
+            FieldSpec("present", FieldType.BOOL, optional=True, default=True),
+            FieldSpec("timeout_s", FieldType.FLOAT, optional=True, default=10.0),
+            FieldSpec("poll_interval_s", FieldType.FLOAT, optional=True,
+                      default=0.2, min_value=0.01),
+        ),
+        description="Block until a colour fills (or leaves) a screen region.",
+    ))
     specs.append(CommandSpec(
         "AC_loop", "Flow", "Loop (N times)",
         fields=(