dsh-gui-control 0.0.0-stage → 0.1.0

package/lib/scripts/DshGui.cs

@@ -0,0 +1,267 @@
+using System;
+using System.Text;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+
+// Native wrapper for mouse / keyboard / window / cursor.
+// Compiled to .build\DshGui.dll and loaded by GuiControl.ps1.
+// Keep this file ASCII-only: Windows PowerShell 5.1 may read sources as ANSI.
+public static class DshGui
+{
+    [StructLayout(LayoutKind.Sequential)] public struct POINT { public int X; public int Y; }
+    [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+    [StructLayout(LayoutKind.Sequential)] public struct MOUSEINPUT { public int dx, dy; public uint mouseData, dwFlags, time; public IntPtr dwExtraInfo; }
+    [StructLayout(LayoutKind.Sequential)] public struct KEYBDINPUT { public ushort wVk, wScan; public uint dwFlags, time; public IntPtr dwExtraInfo; }
+
+    [StructLayout(LayoutKind.Explicit, Size = 40)]
+    public struct INPUT
+    {
+        [FieldOffset(0)] public uint type;
+        [FieldOffset(8)] public MOUSEINPUT mi;
+        [FieldOffset(8)] public KEYBDINPUT ki;
+    }
+
+    public const uint INPUT_MOUSE = 0, INPUT_KEYBOARD = 1;
+    public const uint MOVE = 0x0001, LEFTDOWN = 0x0002, LEFTUP = 0x0004,
+        RIGHTDOWN = 0x0008, RIGHTUP = 0x0010, MIDDLEDOWN = 0x0020, MIDDLEUP = 0x0040,
+        WHEEL = 0x0800, HWHEEL = 0x1000, ABSOLUTE = 0x8000, VIRTUALDESK = 0x4000;
+    public const uint KEYUP = 0x0002, UNICODE = 0x0004;
+
+    [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+    [DllImport("user32.dll")] public static extern int GetSystemMetrics(int n);
+    [DllImport("user32.dll")] public static extern bool GetCursorPos(out POINT p);
+    [DllImport("user32.dll")] public static extern uint SendInput(uint n, INPUT[] inputs, int size);
+    [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
+    [DllImport("user32.dll")] public static extern int GetWindowTextLength(IntPtr h);
+    [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetClassName(IntPtr h, StringBuilder s, int n);
+    [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
+    [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+    [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int cmd);
+    [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+    [DllImport("user32.dll")] public static extern void SwitchToThisWindow(IntPtr h, bool alt);
+    [DllImport("user32.dll")] public static extern bool MoveWindow(IntPtr h, int x, int y, int w, int hh, bool repaint);
+
+    public delegate bool EnumProc(IntPtr h, IntPtr p);
+    [DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, IntPtr p);
+
+    public static int Init()
+    {
+        try { SetProcessDPIAware(); } catch { }
+        return Marshal.SizeOf(typeof(INPUT));
+    }
+
+    public static void MoveAbs(int x, int y)
+    {
+        int vx = GetSystemMetrics(76), vy = GetSystemMetrics(77), vw = GetSystemMetrics(78), vh = GetSystemMetrics(79);
+        if (vw <= 0 || vh <= 0) { vw = GetSystemMetrics(0); vh = GetSystemMetrics(1); vx = 0; vy = 0; }
+        long nx = (long)(x - vx) * 65535 / Math.Max(1, vw - 1);
+        long ny = (long)(y - vy) * 65535 / Math.Max(1, vh - 1);
+        INPUT[] a = new INPUT[1];
+        a[0].type = INPUT_MOUSE;
+        a[0].mi.dx = (int)Math.Round((double)nx);
+        a[0].mi.dy = (int)Math.Round((double)ny);
+        a[0].mi.dwFlags = MOVE | ABSOLUTE | VIRTUALDESK;
+        SendInput(1, a, 40);
+    }
+
+    public static void Mouse(uint flag, int data)
+    {
+        INPUT[] a = new INPUT[1];
+        a[0].type = INPUT_MOUSE;
+        a[0].mi.dwFlags = flag;
+        a[0].mi.mouseData = (uint)data;
+        SendInput(1, a, 40);
+    }
+
+    // Named ScrollWheel, not Wheel: a public const WHEEL already exists and PowerShell
+    // resolves members case-insensitively, so Wheel() would be shadowed by the field.
+    public static void ScrollWheel(int delta)
+    {
+        INPUT[] a = new INPUT[1];
+        a[0].type = INPUT_MOUSE;
+        a[0].mi.dwFlags = WHEEL;
+        a[0].mi.mouseData = (uint)delta;
+        SendInput(1, a, 40);
+    }
+
+    public static void Key(ushort vk, bool up)
+    {
+        INPUT[] a = new INPUT[1];
+        a[0].type = INPUT_KEYBOARD;
+        a[0].ki.wVk = vk;
+        a[0].ki.dwFlags = up ? KEYUP : 0;
+        SendInput(1, a, 40);
+    }
+
+    public static void Char(ushort ch)
+    {
+        INPUT[] a = new INPUT[2];
+        a[0].type = INPUT_KEYBOARD; a[0].ki.wScan = ch; a[0].ki.dwFlags = UNICODE;
+        a[1].type = INPUT_KEYBOARD; a[1].ki.wScan = ch; a[1].ki.dwFlags = UNICODE | KEYUP;
+        SendInput(2, a, 40);
+    }
+
+    public static List<IntPtr> TopWindows()
+    {
+        List<IntPtr> list = new List<IntPtr>();
+        EnumWindows(new EnumProc(delegate (IntPtr h, IntPtr p) { list.Add(h); return true; }), IntPtr.Zero);
+        return list;
+    }
+
+    public static string Title(IntPtr h)
+    {
+        int n = GetWindowTextLength(h);
+        StringBuilder sb = new StringBuilder(Math.Max(2, n + 2));
+        GetWindowText(h, sb, sb.Capacity);
+        return sb.ToString();
+    }
+
+    public static string ClassName(IntPtr h)
+    {
+        StringBuilder sb = new StringBuilder(256);
+        GetClassName(h, sb, sb.Capacity);
+        return sb.ToString();
+    }
+
+    public static POINT Cursor()
+    {
+        POINT p;
+        GetCursorPos(out p);
+        return p;
+    }
+
+    // Screen position of the window's client area origin (excludes caption/border).
+    [DllImport("user32.dll")] public static extern bool ClientToScreen(IntPtr h, ref POINT p);
+    public static POINT ClientOrigin(IntPtr h)
+    {
+        POINT p = new POINT();
+        p.X = 0; p.Y = 0;
+        ClientToScreen(h, ref p);
+        return p;
+    }
+
+    // One-pixel color sample, packed as 0xRRGGBB.
+    public static int Pixel(int x, int y)
+    {
+        using (Bitmap bmp = new Bitmap(1, 1, PixelFormat.Format32bppArgb))
+        {
+            using (Graphics g = Graphics.FromImage(bmp))
+            {
+                g.CopyFromScreen(x, y, 0, 0, new Size(1, 1), CopyPixelOperation.SourceCopy);
+            }
+            Color c = bmp.GetPixel(0, 0);
+            return (c.R << 16) | (c.G << 8) | c.B;
+        }
+    }
+
+    // Virtual desktop bounds in physical pixels (call Init() first for DPI awareness).
+    public static RECT VirtualScreen()
+    {
+        RECT r;
+        r.Left = GetSystemMetrics(76);
+        r.Top = GetSystemMetrics(77);
+        r.Right = r.Left + GetSystemMetrics(78);
+        r.Bottom = r.Top + GetSystemMetrics(79);
+        if (r.Right <= r.Left || r.Bottom <= r.Top)
+        {
+            r.Left = 0; r.Top = 0;
+            r.Right = GetSystemMetrics(0); r.Bottom = GetSystemMetrics(1);
+        }
+        return r;
+    }
+
+    public static void Shot(int left, int top, int w, int h, string path)
+    {
+        using (Bitmap bmp = new Bitmap(w, h, PixelFormat.Format32bppArgb))
+        {
+            using (Graphics g = Graphics.FromImage(bmp))
+            {
+                g.CopyFromScreen(left, top, 0, 0, new Size(w, h), CopyPixelOperation.SourceCopy);
+            }
+            bmp.Save(path, ImageFormat.Png);
+        }
+    }
+
+    // Downscaled capture: vision tokens scale with pixel area, so 0.5x costs a quarter.
+    public static void ShotScaled(int left, int top, int w, int h, double scale, string path)
+    {
+        if (scale <= 0 || scale > 1) scale = 1;
+        int tw = Math.Max(1, (int)(w * scale));
+        int th = Math.Max(1, (int)(h * scale));
+        using (Bitmap full = new Bitmap(w, h, PixelFormat.Format32bppArgb))
+        {
+            using (Graphics g = Graphics.FromImage(full))
+            {
+                g.CopyFromScreen(left, top, 0, 0, new Size(w, h), CopyPixelOperation.SourceCopy);
+            }
+            using (Bitmap small = new Bitmap(tw, th, PixelFormat.Format32bppArgb))
+            {
+                using (Graphics g2 = Graphics.FromImage(small))
+                {
+                    g2.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+                    g2.DrawImage(full, 0, 0, tw, th);
+                }
+                small.Save(path, ImageFormat.Png);
+            }
+        }
+    }
+
+    // Capture with screen-coordinate rulers. The model reads tick labels instead of
+    // multiplying preview pixels by a scale factor, which is where clicks go wrong.
+    public static void ShotRuled(int left, int top, int w, int h, double scale, int step, string path, string note)
+    {
+        if (scale <= 0 || scale > 1) scale = 1;
+        if (step < 50) step = 200;
+        int tw = Math.Max(1, (int)(w * scale));
+        int th = Math.Max(1, (int)(h * scale));
+        int padL = 66, padT = 24, padB = 22;
+
+        using (Bitmap full = new Bitmap(w, h, PixelFormat.Format32bppArgb))
+        {
+            using (Graphics g = Graphics.FromImage(full))
+            {
+                g.CopyFromScreen(left, top, 0, 0, new Size(w, h), CopyPixelOperation.SourceCopy);
+            }
+            using (Bitmap small = new Bitmap(tw, th, PixelFormat.Format32bppArgb))
+            {
+                using (Graphics g2 = Graphics.FromImage(small))
+                {
+                    g2.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+                    g2.DrawImage(full, 0, 0, tw, th);
+                }
+                using (Bitmap canvas = new Bitmap(tw + padL, th + padT + padB, PixelFormat.Format32bppArgb))
+                {
+                    using (Graphics c = Graphics.FromImage(canvas))
+                    {
+                        c.Clear(Color.FromArgb(255, 18, 18, 18));
+                        c.DrawImage(small, padL, padT);
+                        using (Font f = new Font("Consolas", 9f))
+                        using (Brush ink = new SolidBrush(Color.FromArgb(255, 235, 235, 235)))
+                        using (Pen tick = new Pen(Color.FromArgb(255, 255, 170, 60)))
+                        {
+                            for (int x = 0; x < w; x += step)
+                            {
+                                int px = padL + (int)(x * scale);
+                                c.DrawLine(tick, px, padT - 5, px, padT);
+                                c.DrawString((left + x).ToString(), f, ink, px + 1, 2);
+                            }
+                            for (int y = 0; y < h; y += step)
+                            {
+                                int py = padT + (int)(y * scale);
+                                c.DrawLine(tick, padL - 5, py, padL, py);
+                                c.DrawString((top + y).ToString(), f, ink, 2, py - 7);
+                            }
+                            if (!string.IsNullOrEmpty(note)) c.DrawString(note, f, ink, padL + 2, padT + th + 1);
+                        }
+                    }
+                    canvas.Save(path, ImageFormat.Png);
+                }
+            }
+        }
+    }
+}

package/lib/scripts/DshUia.cs

@@ -0,0 +1,212 @@
+using System;
+using System.Collections.Generic;
+using System.Windows.Automation;
+
+// UI Automation access: find controls by name, invoke them without a single mouse event.
+// Works for Win32 / WinForms / WPF / UWP apps. CEF apps (bilibili client, Electron) usually
+// expose nothing here, which is exactly why gui-ocr.ps1 exists as the fallback.
+// ASCII only.
+public static class DshUia
+{
+    public static AutomationElement FindWindow(string titleContains)
+    {
+        var root = AutomationElement.RootElement;
+        if (root == null) return null;
+        var exact = new PropertyCondition(AutomationElement.NameProperty, titleContains);
+        var w = root.FindFirst(TreeScope.Children, exact);
+        if (w != null) return w;
+
+        var kids = root.FindAll(TreeScope.Children, Condition.TrueCondition);
+        foreach (AutomationElement e in kids)
+        {
+            try
+            {
+                string n = e.Current.Name;
+                if (!string.IsNullOrEmpty(n) && n.IndexOf(titleContains, StringComparison.OrdinalIgnoreCase) >= 0) return e;
+            }
+            catch { }
+        }
+        return null;
+    }
+
+    // Substring match on the accessible Name, optionally limited to one control type
+    // (e.g. "Button"), which also keeps the search fast on large trees.
+    public static List<AutomationElement> Find(AutomationElement scope, string contains, string controlType, int max)
+    {
+        var res = new List<AutomationElement>();
+        if (scope == null) return res;
+        Condition cond = Condition.TrueCondition;
+        if (!string.IsNullOrEmpty(controlType))
+        {
+            ControlType ct = null;
+            switch (controlType.ToLower())
+            {
+                case "button": ct = ControlType.Button; break;
+                case "edit": ct = ControlType.Edit; break;
+                case "text": ct = ControlType.Text; break;
+                case "listitem": ct = ControlType.ListItem; break;
+                case "tabitem": ct = ControlType.TabItem; break;
+                case "menuitem": ct = ControlType.MenuItem; break;
+                case "checkbox": ct = ControlType.CheckBox; break;
+                case "radiobutton": ct = ControlType.RadioButton; break;
+                case "combobox": ct = ControlType.ComboBox; break;
+                case "hyperlink": ct = ControlType.Hyperlink; break;
+                case "treeitem": ct = ControlType.TreeItem; break;
+                case "dataitem": ct = ControlType.DataItem; break;
+                case "image": ct = ControlType.Image; break;
+                case "group": ct = ControlType.Group; break;
+            }
+            if (ct != null) cond = new PropertyCondition(AutomationElement.ControlTypeProperty, ct);
+        }
+        AutomationElementCollection all;
+        try { all = scope.FindAll(TreeScope.Descendants, cond); }
+        catch { return res; }
+        foreach (AutomationElement e in all)
+        {
+            if (res.Count >= max) break;
+            try
+            {
+                string n = e.Current.Name;
+                if (!string.IsNullOrEmpty(n) && n.IndexOf(contains, StringComparison.OrdinalIgnoreCase) >= 0) res.Add(e);
+            }
+            catch { }
+        }
+        return res;
+    }
+
+    public static string Name(AutomationElement e) { try { return e.Current.Name; } catch { return ""; } }
+    public static string AutoId(AutomationElement e) { try { return e.Current.AutomationId; } catch { return ""; } }
+    public static bool IsPassword(AutomationElement e) { try { return e.Current.IsPassword; } catch { return false; } }
+
+    public static string Value(AutomationElement e)
+    {
+        try
+        {
+            object p;
+            if (e.TryGetCurrentPattern(ValuePattern.Pattern, out p))
+                return ((ValuePattern)p).Current.Value;
+            return "";
+        }
+        catch { return ""; }
+    }
+
+    public static string ClassOf(AutomationElement e) { try { return e.Current.ClassName; } catch { return ""; } }
+    public static string TypeOf(AutomationElement e) { try { return e.Current.ControlType.ProgrammaticName.Replace("ControlType.", ""); } catch { return ""; } }
+
+    public static double[] Rect(AutomationElement e)
+    {
+        // Off-screen / collapsed elements report +/-Infinity here, which cannot be cast to
+        // int. Clamp to -1 so callers can treat them as "no usable rectangle".
+        try
+        {
+            var r = e.Current.BoundingRectangle;
+            double x = r.X, y = r.Y, w = r.Width, h = r.Height;
+            if (double.IsNaN(x) || double.IsInfinity(x)) { x = -1; w = 0; }
+            if (double.IsNaN(y) || double.IsInfinity(y)) { y = -1; h = 0; }
+            if (double.IsNaN(w) || double.IsInfinity(w)) { w = 0; }
+            if (double.IsNaN(h) || double.IsInfinity(h)) { h = 0; }
+            if (x < -10000 || y < -10000) { return new double[] { -1, -1, 0, 0 }; }
+            return new double[] { x, y, w, h };
+        }
+        catch { return new double[] { -1, -1, 0, 0 }; }
+    }
+
+    // Prefer the accessibility action over simulating a click: works even when the window
+    // is behind another window, and cannot miss by a few pixels.
+    public static string Activate(AutomationElement e)
+    {
+        object p;
+        try
+        {
+            if (e.TryGetCurrentPattern(InvokePattern.Pattern, out p))
+            {
+                ((InvokePattern)p).Invoke();
+                return "invoke";
+            }
+            if (e.TryGetCurrentPattern(SelectionItemPattern.Pattern, out p))
+            {
+                ((SelectionItemPattern)p).Select();
+                return "select";
+            }
+            if (e.TryGetCurrentPattern(TogglePattern.Pattern, out p))
+            {
+                ((TogglePattern)p).Toggle();
+                return "toggle";
+            }
+        }
+        catch (Exception ex) { return "error:" + ex.Message; }
+        return "none";
+    }
+
+    public static string SetText(AutomationElement e, string value)
+    {
+        object p;
+        try
+        {
+            if (e.TryGetCurrentPattern(ValuePattern.Pattern, out p))
+            {
+                ((ValuePattern)p).SetValue(value);
+                return "value";
+            }
+        }
+        catch (Exception ex) { return "error:" + ex.Message; }
+        return "none";
+    }
+
+    public static string GetText(AutomationElement e)
+    {
+        object p;
+        try
+        {
+            if (e.TryGetCurrentPattern(ValuePattern.Pattern, out p)) return ((ValuePattern)p).Current.Value;
+            if (e.TryGetCurrentPattern(TextPattern.Pattern, out p)) return ((TextPattern)p).DocumentRange.GetText(4096);
+        }
+        catch { }
+        try { return e.Current.Name; } catch { return ""; }
+    }
+
+    // Selected state for radio / checkbox / tab items. Needed to verify a pick landed.
+    public static bool IsSelected(AutomationElement e)
+    {
+        object p;
+        try
+        {
+            if (e.TryGetCurrentPattern(SelectionItemPattern.Pattern, out p))
+                return ((SelectionItemPattern)p).Current.IsSelected;
+            if (e.TryGetCurrentPattern(TogglePattern.Pattern, out p))
+                return ((TogglePattern)p).Current.ToggleState == ToggleState.On;
+        }
+        catch { }
+        return false;
+    }
+
+    // The web page root inside a Chromium window. Everything a web task needs hangs here.
+    public static AutomationElement DocumentOf(AutomationElement win)
+    {
+        if (win == null) return null;
+        var cond = new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Document);
+        try
+        {
+            var d = win.FindFirst(TreeScope.Descendants, cond);
+            if (d != null) return d;
+        }
+        catch { }
+        return win;
+    }
+
+    // Flat dump of a subtree in tree order. Chromium pages are big, so callers cap it.
+    public static List<AutomationElement> Descendants(AutomationElement scope, int max)
+    {
+        var res = new List<AutomationElement>();
+        if (scope == null) return res;
+        AutomationElementCollection all;
+        try { all = scope.FindAll(TreeScope.Descendants, Condition.TrueCondition); }
+        catch { return res; }
+        foreach (AutomationElement e in all)
+        {
+            if (res.Count >= max) break;
+            res.Add(e);
+        }
+        return res;
+    }
+}

package/lib/scripts/gui-anchors.ps1

@@ -0,0 +1,146 @@
+#requires -Version 5.1
+# Anchor resolution layer: named targets instead of hardcoded pixels.
+#
+# An anchor is resolved with a fixed priority chain, first hit wins:
+#   uia      -> accessibility element (exact, position independent)
+#   ocr      -> exact label found by OCR             (survives resize/move)
+#   ocr_any  -> any text inside a band               (survives placeholder -> value swap)
+#   derive   -> bounding box of OCR lines matching a regex (survives layout changes)
+#   point    -> fraction of the window               (last resort, no text available)
+#
+# Profiles live in apps\<name>.json. All coordinates in a profile are fractions of the
+# target window (0..1), so moving/resizing the window cannot invalidate them.
+# ASCII only.
+$script:GuiRoot = $PSScriptRoot
+
+function Get-AppProfile([string]$app) {
+    $p = Join-Path (Join-Path $script:GuiRoot 'apps') ($app + '.json')
+    if (-not (Test-Path $p)) { throw ('profile not found: ' + $app) }
+    return (Get-Content -Raw -Encoding UTF8 $p | ConvertFrom-Json)
+}
+
+function Get-FracRect($win, $f) {
+    # f = [rx, ry, rw, rh] as fractions of the window frame
+    return @{
+        x = [int]($win.Left + $win.Width * [double]$f[0])
+        y = [int]($win.Top + $win.Height * [double]$f[1])
+        w = [int]($win.Width * [double]$f[2])
+        h = [int]($win.Height * [double]$f[3])
+    }
+}
+
+function Get-AnchorScope($anchor, $win) {
+    if ($null -eq $anchor.scope) { return $null }
+    return Get-FracRect $win $anchor.scope
+}
+
+# OCR the window (or a sub-rect) through the normal op pipeline.
+function Get-Lines([hashtable]$rect) {
+    $op = @{ op = 'ocr' }
+    if ($null -ne $rect) { $op.x = $rect.x; $op.y = $rect.y; $op.w = $rect.w; $op.h = $rect.h }
+    $r = Invoke-GuiOp $op
+    if (-not $r.ok) { return @() }
+    return @($r.result)
+}
+
+function Resolve-Anchor([string]$app, [string]$name, [string]$winMatch = '') {
+    $prof = Get-AppProfile $app
+    $anchor = $prof.anchors.$name
+    if ($null -eq $anchor) { throw ('anchor not found: ' + $app + '.' + $name) }
+
+    if ([string]::IsNullOrEmpty($winMatch)) { $winMatch = $prof.window_match }
+    $win = Resolve-Win $winMatch
+    $frame = @{ Left = [double]$win.Left; Top = [double]$win.Top
+        Width = [double]($win.Right - $win.Left); Height = [double]($win.Bottom - $win.Top) }
+
+    # 1) uia
+    if ($null -ne $anchor.uia) {
+        try {
+            $scope = [DshUia]::FindWindow($winMatch)
+            $els = [DshUia]::Find($scope, $anchor.uia.name, $anchor.uia.type, 5)
+            if ($els.Count -ge 1) {
+                $rr = [DshUia]::Rect($els[0])
+                return @{ how = 'uia'; x = [int]$rr[0]; y = [int]$rr[1]; w = [int]$rr[2]; h = [int]$rr[3]
+                    cx = [int]($rr[0] + $rr[2] / 2); cy = [int]($rr[1] + $rr[3] / 2) }
+            }
+        }
+        catch { }
+    }
+
+    # 2) ocr (exact label)
+    if ($anchor.ocr) {
+        $scope = Get-AnchorScope $anchor $frame
+        try {
+            $op = @{ op = 'findtext'; text = $anchor.ocr }
+            if ($null -ne $scope) { $op += $scope } else { $op.win = $winMatch }
+            $r = Invoke-GuiOp $op
+            if ($r.ok -and @($r.result).Count -ge 1) {
+                $h = @($r.result)[0]
+                return @{ how = 'ocr'; x = $h.x; y = $h.y; w = $h.w; h = $h.h; cx = $h.cx; cy = $h.cy; text = $h.text }
+            }
+        }
+        catch { }
+    }
+
+    # 3) ocr_any (any text inside the band - the search box keeps either placeholder or value)
+    if ($anchor.ocr_any) {
+        $scope = Get-AnchorScope $anchor $frame
+        if ($null -ne $scope) {
+            $lines = @(Get-Lines $scope | Where-Object { ((($_.text -replace '\s+', ''))).Length -ge 2 })
+            if ($lines.Count -ge 1) {
+                $l = $lines[0]
+                return @{ how = 'ocr_any'; x = $l.x; y = $l.y; w = $l.w; h = $l.h; cx = $l.cx; cy = $l.cy; text = $l.text }
+            }
+        }
+    }
+
+    # 4) derive (bounding box of matching rows)
+    if ($anchor.derive) {
+        $scan = Get-FracRect $frame $anchor.scan
+        $lines = @(Get-Lines $scan | Where-Object { ($_.text -replace '\s+', '') -match $anchor.derive })
+        if ($lines.Count -ge 1) {
+            $pad = 0; if ($null -ne $anchor.pad) { $pad = [int]$anchor.pad }
+            $minX = ($lines | Measure-Object -Property x -Minimum).Minimum
+            $minY = ($lines | Measure-Object -Property y -Minimum).Minimum
+            $maxX = ($lines | ForEach-Object { $_.x + $_.w } | Measure-Object -Maximum).Maximum
+            $maxY = ($lines | ForEach-Object { $_.y + $_.h } | Measure-Object -Maximum).Maximum
+            $x = [int]($minX - $pad); $y = [int]($minY - $pad)
+            $w = [int]($maxX - $minX + 2 * $pad); $h = [int]($maxY - $minY + 2 * $pad)
+            return @{ how = 'derive'; x = $x; y = $y; w = $w; h = $h
+                cx = [int]($x + $w / 2); cy = [int]($y + $h / 2); rows = $lines.Count }
+        }
+    }
+
+    # 5) rect / point fallback
+    if ($anchor.rect) {
+        $r = Get-FracRect $frame $anchor.rect
+        return @{ how = 'rect'; x = $r.x; y = $r.y; w = $r.w; h = $r.h
+            cx = [int]($r.x + $r.w / 2); cy = [int]($r.y + $r.h / 2) }
+    }
+    if ($anchor.point) {
+        $pt = Get-FracRect $frame @($anchor.point[0], $anchor.point[1], 0, 0)
+        return @{ how = 'point'; x = $pt.x; y = $pt.y; w = 0; h = 0; cx = $pt.x; cy = $pt.y }
+    }
+
+    throw ('anchor unresolvable: ' + $app + '.' + $name)
+}
+
+# Discovery helper: dump every OCR line of a window with fractional coordinates, so a new
+# app profile can be authored by copy-paste instead of trial and error.
+function Get-AnchorDump([string]$app) {
+    $prof = Get-AppProfile $app
+    $win = Resolve-Win $prof.window_match
+    $frame = @{ Left = [double]$win.Left; Top = [double]$win.Top
+        Width = [double]($win.Right - $win.Left); Height = [double]($win.Bottom - $win.Top) }
+    $lines = @(Get-Lines @{ x = [int]$frame.Left; y = [int]$frame.Top; w = [int]$frame.Width; h = [int]$frame.Height })
+    $out = @()
+    foreach ($l in $lines) {
+        $out += @{
+            text = ($l.text -replace '\s+', '')
+            rx = [math]::Round(($l.cx - $frame.Left) / $frame.Width, 3)
+            ry = [math]::Round(($l.cy - $frame.Top) / $frame.Height, 3)
+            abs = ('{0},{1}' -f $l.cx, $l.cy)
+        }
+    }
+    return @{ window = $win.Title; size = ('{0}x{1}' -f $frame.Width, $frame.Height); lines = $out }
+}