pctr 0.1.0__tar.gz

pctr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Space-lab515
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pctr-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: pctr
+Version: 0.1.0
+Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
+Author: Space-lab515
+License-Expression: MIT
+Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywinauto>=0.6.8; platform_system == "Windows"
+Requires-Dist: uiautomation>=2.0; platform_system == "Windows"
+Requires-Dist: pyautogui>=0.9.54; platform_system == "Windows"
+Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
+Dynamic: license-file
+
+# pctr
+
+Element-based Windows UI Automation CLI for AI agents.
+
+Instead of screenshotting and guessing pixel coordinates, `pctr` finds controls
+by their **name / control type / automation id** and acts on them. Window moves,
+DPI changes, and layout shifts don't break your script.
+
+Built on `pywinauto` (UI Automation) with `pyautogui` / `pydirectinput` for raw
+mouse and keyboard input.
+
+## Install
+
+```bash
+pip install pctr
+```
+
+Windows only.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `pctr windows [--filter RE]` | List top-level windows (`pid=… \| title`). |
+| `pctr tree --title RE [--limit N]` | Dump the UIA control tree of a window. |
+| `pctr find --title RE --name RE [--control-type T] [--auto-id ID]` | List matching elements. |
+| `pctr click --title RE --name RE [--method auto\|invoke\|mouse] [--dbl]` | Click an element. |
+| `pctr set --title RE --name RE --text S` | Set a field via the UIA ValuePattern. |
+| `pctr type [--title RE --name RE] --text S [--delay 0.03] [--chunk 1]` | Type literal text. |
+| `pctr keys --keys "{ENTER}"` | Send a global key combo. |
+| `pctr hotkey --keys win+shift+s` | Send a modifier combo. |
+| `pctr focus --title RE` | Bring a window to the foreground. |
+| `pctr wait --title RE --name RE [--timeout S]` | Wait until an element exists. |
+| `pctr shot [--title RE] --out PATH` | Screenshot the screen or a window. |
+| `pctr size` | Print primary screen size as `WxH`. |
+| `pctr move --x N --y N` | Move the cursor. |
+| `pctr down / up [--button left]` | Press / release a mouse button. |
+| `pctr hold --ms 1000 [--x N --y N]` | Press, hold, release. |
+| `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
+| `pctr keydown / keyup --key a` | Hold / release a keyboard key. |
+| `pctr keyhold --key w --ms 1500` | Hold a key for a duration. |
+
+Common filters: `--title` (regex), `--name` (regex), `--control-type`
+(`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
+
+## The loop
+
+```bash
+pctr tree  --title "Notepad" --limit 60      # see what's clickable
+pctr click --title "Notepad" --name "^File$"
+pctr set   --title "Notepad" --name "Text Editor" --text "hello"
+```
+
+## Notes
+
+- Prefer `set` (ValuePattern) over `type` for text fields - it can't drop or
+  reorder characters.
+- `type` is sent in small chunks (`--chunk 1 --delay 0.03`); raise the delay for
+  Qt/Electron apps that garble fast input.
+- Global `type` / `keys` go to the OS-focused window - `pctr focus` first.
+- Qt apps expose a rich tree including embedded webviews. Electron apps expose
+  only the window frame unless accessibility is enabled (use `focus` + `keys`).
+
+## License
+
+MIT

pctr-0.1.0/README.md

@@ -0,0 +1,66 @@
+# pctr
+
+Element-based Windows UI Automation CLI for AI agents.
+
+Instead of screenshotting and guessing pixel coordinates, `pctr` finds controls
+by their **name / control type / automation id** and acts on them. Window moves,
+DPI changes, and layout shifts don't break your script.
+
+Built on `pywinauto` (UI Automation) with `pyautogui` / `pydirectinput` for raw
+mouse and keyboard input.
+
+## Install
+
+```bash
+pip install pctr
+```
+
+Windows only.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `pctr windows [--filter RE]` | List top-level windows (`pid=… \| title`). |
+| `pctr tree --title RE [--limit N]` | Dump the UIA control tree of a window. |
+| `pctr find --title RE --name RE [--control-type T] [--auto-id ID]` | List matching elements. |
+| `pctr click --title RE --name RE [--method auto\|invoke\|mouse] [--dbl]` | Click an element. |
+| `pctr set --title RE --name RE --text S` | Set a field via the UIA ValuePattern. |
+| `pctr type [--title RE --name RE] --text S [--delay 0.03] [--chunk 1]` | Type literal text. |
+| `pctr keys --keys "{ENTER}"` | Send a global key combo. |
+| `pctr hotkey --keys win+shift+s` | Send a modifier combo. |
+| `pctr focus --title RE` | Bring a window to the foreground. |
+| `pctr wait --title RE --name RE [--timeout S]` | Wait until an element exists. |
+| `pctr shot [--title RE] --out PATH` | Screenshot the screen or a window. |
+| `pctr size` | Print primary screen size as `WxH`. |
+| `pctr move --x N --y N` | Move the cursor. |
+| `pctr down / up [--button left]` | Press / release a mouse button. |
+| `pctr hold --ms 1000 [--x N --y N]` | Press, hold, release. |
+| `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
+| `pctr keydown / keyup --key a` | Hold / release a keyboard key. |
+| `pctr keyhold --key w --ms 1500` | Hold a key for a duration. |
+
+Common filters: `--title` (regex), `--name` (regex), `--control-type`
+(`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
+
+## The loop
+
+```bash
+pctr tree  --title "Notepad" --limit 60      # see what's clickable
+pctr click --title "Notepad" --name "^File$"
+pctr set   --title "Notepad" --name "Text Editor" --text "hello"
+```
+
+## Notes
+
+- Prefer `set` (ValuePattern) over `type` for text fields - it can't drop or
+  reorder characters.
+- `type` is sent in small chunks (`--chunk 1 --delay 0.03`); raise the delay for
+  Qt/Electron apps that garble fast input.
+- Global `type` / `keys` go to the OS-focused window - `pctr focus` first.
+- Qt apps expose a rich tree including embedded webviews. Electron apps expose
+  only the window frame unless accessibility is enabled (use `focus` + `keys`).
+
+## License
+
+MIT

pctr-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pctr"
+version = "0.1.0"
+description = "Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Space-lab515" }]
+keywords = ["automation", "windows", "uia", "pywinauto", "desktop", "agent", "computer-use", "rpa"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Win32 (MS Windows)",
+  "Intended Audience :: Developers",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+  "Topic :: System :: Networking",
+]
+dependencies = [
+  "pywinauto>=0.6.8; platform_system == 'Windows'",
+  "uiautomation>=2.0; platform_system == 'Windows'",
+  "pyautogui>=0.9.54; platform_system == 'Windows'",
+  "pydirectinput>=1.0.4; platform_system == 'Windows'",
+]
+
+[project.scripts]
+pctr = "pctr.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

pctr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pctr-0.1.0/src/pctr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pctr-0.1.0/src/pctr/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

pctr-0.1.0/src/pctr/cli.py

@@ -0,0 +1,453 @@
+import argparse
+import re
+import sys
+import time
+
+for _stream in (sys.stdout, sys.stderr):
+    _reconf = getattr(_stream, "reconfigure", None)
+    if _reconf is not None:
+        try:
+            _reconf(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+from pywinauto import Desktop
+
+DESCRIPTION = "Element-based Windows UI Automation CLI for AI agents."
+
+
+def _iter_windows():
+    return Desktop(backend="uia").windows()
+
+
+def _find_window(title_re, process=None, timeout=5.0, index=0):
+    desktop = Desktop(backend="uia")
+    deadline = time.time() + timeout
+    last = None
+    while time.time() < deadline:
+        matches = []
+        for w in desktop.windows():
+            try:
+                t = w.window_text()
+            except Exception:
+                continue
+            if title_re and not re.search(title_re, t, re.I):
+                continue
+            if process is not None and w.process_id() != process:
+                continue
+            matches.append(w)
+        if len(matches) > index:
+            return matches[index]
+        last = matches
+        time.sleep(0.25)
+    raise SystemExit(
+        "window not found: title_re=%r process=%r (saw %d match(es))"
+        % (title_re, process, len(last or []))
+    )
+
+
+def _matches(win, name=None, control_type=None, auto_id=None):
+    out = []
+    for el in win.descendants():
+        try:
+            info = el.element_info
+        except Exception:
+            continue
+        if name is not None:
+            n = info.name or ""
+            if re.search(name, n, re.I) is None:
+                continue
+        if control_type is not None:
+            c = (info.control_type or "")
+            if c.lower() != control_type.lower():
+                continue
+        if auto_id is not None:
+            a = (info.automation_id or "")
+            if a != auto_id:
+                continue
+        out.append(el)
+    return out
+
+
+def _describe(el):
+    info = el.element_info
+    r = info.rectangle
+    return "%s | type=%s | id=%s | rect=%d,%d,%d,%d" % (
+        info.name,
+        info.control_type,
+        info.automation_id,
+        r.left,
+        r.top,
+        r.right,
+        r.bottom,
+    )
+
+
+def _get_element(args):
+    win = _find_window(args.title, getattr(args, "process", None), getattr(args, "timeout", 5.0))
+    els = _matches(win, args.name, getattr(args, "control_type", None), getattr(args, "auto_id", None))
+    onscreen = [e for e in els if e.element_info.rectangle.right > 0 and e.element_info.rectangle.bottom > 0]
+    if onscreen:
+        els = onscreen
+    if not els:
+        raise SystemExit("no element matched name=%r type=%r id=%r" % (
+            getattr(args, "name", None), getattr(args, "control_type", None), getattr(args, "auto_id", None)))
+    idx = getattr(args, "nth", 0)
+    if idx >= len(els):
+        raise SystemExit("matched %d element(s); nth=%d out of range" % (len(els), idx))
+    return win, els[idx], len(els)
+
+
+def cmd_windows(args):
+    for w in _iter_windows():
+        t = ""
+        try:
+            t = w.window_text()
+        except Exception:
+            pass
+        if args.filter and re.search(args.filter, t, re.I) is None:
+            continue
+        print("pid=%s | %s" % (w.process_id(), t))
+
+
+def cmd_tree(args):
+    win = _find_window(args.title, args.process, args.timeout)
+    print("WINDOW: %s (pid=%s)" % (win.window_text(), win.process_id()))
+    count = 0
+    for el in win.descendants():
+        try:
+            el.element_info
+        except Exception:
+            continue
+        print("  %s" % _describe(el))
+        count += 1
+        if count >= args.limit:
+            print("... (limit %d reached)" % args.limit)
+            break
+
+
+def cmd_find(args):
+    win = _find_window(args.title, args.process, args.timeout)
+    els = _matches(win, args.name, args.control_type, args.auto_id)
+    if not els:
+        print("no matches")
+        return
+    print("WINDOW: %s" % win.window_text())
+    for i, el in enumerate(els):
+        print("[%d] %s" % (i, _describe(el)))
+
+
+def cmd_click(args):
+    win, el, n = _get_element(args)
+    print("target: %s  (%d match(es))" % (_describe(el), n))
+    if args.method == "invoke" or (args.method == "auto" and hasattr(el, "invoke")):
+        try:
+            el.invoke()
+            print("invoked")
+            return
+        except Exception as e:
+            print("invoke failed (%s), falling back to mouse" % e)
+    el.click_input(button=args.button)
+    if args.dbl:
+        el.click_input(button=args.button)
+    print("clicked")
+
+
+def cmd_set(args):
+    win, el, n = _get_element(args)
+    print("target: %s" % _describe(el))
+    try:
+        el.set_edit_text(args.text)
+        print("set via ValuePattern")
+    except Exception:
+        el.click_input()
+        el.type_keys("^a{BACKSPACE}")
+        el.type_keys(args.text, with_spaces=True, with_newlines=True)
+        print("set via type_keys")
+
+
+def _chunks(text, size):
+    return [text[i:i + size] for i in range(0, len(text), size)]
+
+
+def cmd_type(args):
+    delay = getattr(args, "delay", 0.02)
+    chunk = max(1, getattr(args, "chunk", 10))
+    if args.title:
+        win, el, n = _get_element(args)
+        for part in _chunks(args.text, chunk):
+            el.type_keys(part, with_spaces=True, with_newlines=True)
+            time.sleep(delay)
+    else:
+        import pyautogui
+        pyautogui.write(args.text, interval=delay)
+    print("typed")
+
+
+def cmd_keys(args):
+    from pywinauto.keyboard import send_keys
+    send_keys(args.keys, with_spaces=True)
+    print("sent keys: %s" % args.keys)
+
+
+def cmd_focus(args):
+    win = _find_window(args.title, args.process, args.timeout)
+    win.set_focus()
+    print("focused: %s" % win.window_text())
+
+
+def cmd_wait(args):
+    deadline = time.time() + args.timeout
+    while time.time() < deadline:
+        try:
+            win = _find_window(args.title, args.process, timeout=1.0)
+            if _matches(win, args.name, args.control_type, args.auto_id):
+                print("found")
+                return
+        except SystemExit:
+            pass
+        time.sleep(0.4)
+    raise SystemExit("timed out waiting for element")
+
+
+def cmd_shot(args):
+    import pyautogui
+    if args.title:
+        win = _find_window(args.title, args.process, args.timeout)
+        r = win.rectangle()
+        img = pyautogui.screenshot(region=(r.left, r.top, r.width(), r.height()))
+    else:
+        img = pyautogui.screenshot()
+    img.save(args.out)
+    print("saved %s (%dx%d)" % (args.out, img.width, img.height))
+
+
+def _mouse_backend(args):
+    if getattr(args, "direct", False):
+        import pydirectinput
+        pydirectinput.PAUSE = 0.01
+        return pydirectinput
+    import pyautogui
+    pyautogui.FAILSAFE = False
+    return pyautogui
+
+
+def _parse_pair(text):
+    x, y = text.split(",")
+    return int(float(x)), int(float(y))
+
+
+def cmd_move(args):
+    m = _mouse_backend(args)
+    m.moveTo(args.x, args.y, duration=getattr(args, "duration", 0.0))
+    print("moved to %d,%d" % (args.x, args.y))
+
+
+def cmd_down(args):
+    m = _mouse_backend(args)
+    m.mouseDown(button=args.button)
+    print("mouse down (%s)" % args.button)
+
+
+def cmd_up(args):
+    m = _mouse_backend(args)
+    m.mouseUp(button=args.button)
+    print("mouse up (%s)" % args.button)
+
+
+def cmd_hold(args):
+    m = _mouse_backend(args)
+    if args.x is not None and args.y is not None:
+        m.moveTo(args.x, args.y, duration=0.0)
+    m.mouseDown(button=args.button)
+    print("holding %s for %dms..." % (args.button, args.ms))
+    time.sleep(args.ms / 1000.0)
+    m.mouseUp(button=args.button)
+    print("released")
+
+
+def cmd_keydown(args):
+    m = _mouse_backend(args)
+    m.keyDown(args.key)
+    print("key down: %s" % args.key)
+
+
+def cmd_keyup(args):
+    m = _mouse_backend(args)
+    m.keyUp(args.key)
+    print("key up: %s" % args.key)
+
+
+def cmd_keyhold(args):
+    m = _mouse_backend(args)
+    m.keyDown(args.key)
+    print("holding key %s for %dms..." % (args.key, args.ms))
+    time.sleep(args.ms / 1000.0)
+    m.keyUp(args.key)
+    print("released")
+
+
+def cmd_hotkey(args):
+    m = _mouse_backend(args)
+    keys = [k.strip() for k in args.keys.split("+") if k.strip()]
+    for k in keys:
+        m.keyDown(k)
+    for k in reversed(keys):
+        m.keyUp(k)
+    print("hotkey: %s" % "+".join(keys))
+
+
+def cmd_size(args):
+    import pyautogui
+    w, h = pyautogui.size()
+    print("%dx%d" % (w, h))
+
+
+def cmd_drag(args):
+    m = _mouse_backend(args)
+    x1, y1 = _parse_pair(args.start)
+    x2, y2 = _parse_pair(args.end)
+    m.moveTo(x1, y1, duration=0.0)
+    m.mouseDown(button=args.button)
+    m.moveTo(x2, y2, duration=getattr(args, "duration", 0.3))
+    m.mouseUp(button=args.button)
+    print("dragged %d,%d -> %d,%d" % (x1, y1, x2, y2))
+
+
+def add_target(p, require_name=False):
+    p.add_argument("--title", required=require_name, help="Window title regex")
+    p.add_argument("--process", type=int, default=None, help="Filter by process id")
+    p.add_argument("--timeout", type=float, default=5.0)
+    p.add_argument("--name", required=require_name, help="Element name regex")
+    p.add_argument("--control-type", default=None, help="Exact UIA control type (Button, Edit, ...)")
+    p.add_argument("--auto-id", default=None)
+    p.add_argument("--nth", type=int, default=0)
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(prog="pctr", description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    w = sub.add_parser("windows", help="List top-level windows")
+    w.add_argument("--filter", default=None)
+    w.set_defaults(func=cmd_windows)
+
+    t = sub.add_parser("tree", help="Dump UIA tree")
+    add_target(t)
+    t.add_argument("--depth", type=int, default=99)
+    t.add_argument("--limit", type=int, default=400)
+    t.set_defaults(func=cmd_tree)
+
+    f = sub.add_parser("find", help="Find elements")
+    add_target(f)
+    f.set_defaults(func=cmd_find)
+
+    c = sub.add_parser("click", help="Click an element")
+    add_target(c, require_name=True)
+    c.add_argument("--method", choices=["auto", "invoke", "mouse"], default="auto")
+    c.add_argument("--button", default="left")
+    c.add_argument("--dbl", action="store_true")
+    c.set_defaults(func=cmd_click)
+
+    s = sub.add_parser("set", help="Set text on an element")
+    add_target(s, require_name=True)
+    s.add_argument("--text", required=True)
+    s.set_defaults(func=cmd_set)
+
+    ty = sub.add_parser("type", help="Send keystrokes")
+    ty.add_argument("--title", default=None)
+    ty.add_argument("--name", default=None)
+    ty.add_argument("--control-type", default=None)
+    ty.add_argument("--auto-id", default=None)
+    ty.add_argument("--nth", type=int, default=0)
+    ty.add_argument("--process", type=int, default=None)
+    ty.add_argument("--timeout", type=float, default=5.0)
+    ty.add_argument("--delay", type=float, default=0.03, help="Seconds between chars/chunks")
+    ty.add_argument("--chunk", type=int, default=1, help="Chunk size when typing into an element")
+    ty.add_argument("--text", required=True)
+    ty.set_defaults(func=cmd_type)
+
+    k = sub.add_parser("keys", help="Send a key combo globally")
+    k.add_argument("--keys", required=True, help="pywinauto send_keys syntax, e.g. {ENTER} or ^s")
+    k.set_defaults(func=cmd_keys)
+
+    fo = sub.add_parser("focus", help="Focus a window")
+    fo.add_argument("--title", required=True)
+    fo.add_argument("--process", type=int, default=None)
+    fo.add_argument("--timeout", type=float, default=5.0)
+    fo.set_defaults(func=cmd_focus)
+
+    wa = sub.add_parser("wait", help="Wait for an element")
+    add_target(wa, require_name=True)
+    wa.set_defaults(func=cmd_wait)
+
+    sh = sub.add_parser("shot", help="Screenshot")
+    sh.add_argument("--out", required=True)
+    sh.add_argument("--title", default=None)
+    sh.add_argument("--process", type=int, default=None)
+    sh.add_argument("--timeout", type=float, default=5.0)
+    sh.set_defaults(func=cmd_shot)
+
+    mv = sub.add_parser("move", help="Move the cursor")
+    mv.add_argument("--x", type=int, required=True)
+    mv.add_argument("--y", type=int, required=True)
+    mv.add_argument("--duration", type=float, default=0.0)
+    mv.add_argument("--direct", action="store_true", help="Use pydirectinput (games)")
+    mv.set_defaults(func=cmd_move)
+
+    dn = sub.add_parser("down", help="Press and hold a mouse button")
+    dn.add_argument("--button", default="left")
+    dn.add_argument("--direct", action="store_true")
+    dn.set_defaults(func=cmd_down)
+
+    up = sub.add_parser("up", help="Release a mouse button")
+    up.add_argument("--button", default="left")
+    up.add_argument("--direct", action="store_true")
+    up.set_defaults(func=cmd_up)
+
+    ho = sub.add_parser("hold", help="Press, hold for --ms, then release")
+    ho.add_argument("--ms", type=int, default=1000)
+    ho.add_argument("--button", default="left")
+    ho.add_argument("--x", type=int, default=None)
+    ho.add_argument("--y", type=int, default=None)
+    ho.add_argument("--direct", action="store_true")
+    ho.set_defaults(func=cmd_hold)
+
+    kd = sub.add_parser("keydown", help="Press and hold a keyboard key")
+    kd.add_argument("--key", required=True)
+    kd.add_argument("--direct", action="store_true")
+    kd.set_defaults(func=cmd_keydown)
+
+    ku = sub.add_parser("keyup", help="Release a keyboard key")
+    ku.add_argument("--key", required=True)
+    ku.add_argument("--direct", action="store_true")
+    ku.set_defaults(func=cmd_keyup)
+
+    kh = sub.add_parser("keyhold", help="Press, hold for --ms, then release a key")
+    kh.add_argument("--key", required=True)
+    kh.add_argument("--ms", type=int, default=1000)
+    kh.add_argument("--direct", action="store_true")
+    kh.set_defaults(func=cmd_keyhold)
+
+    hk = sub.add_parser("hotkey", help="Send a key combo, e.g. --keys win+shift+s")
+    hk.add_argument("--keys", required=True, help="Combo joined by +, e.g. ctrl+shift+t")
+    hk.add_argument("--direct", action="store_true")
+    hk.set_defaults(func=cmd_hotkey)
+
+    sz = sub.add_parser("size", help="Print primary screen size as WxH")
+    sz.set_defaults(func=cmd_size)
+
+    dr = sub.add_parser("drag", help="Drag from --start to --end (x,y pairs)")
+    dr.add_argument("--start", required=True, help="x,y")
+    dr.add_argument("--end", required=True, help="x,y")
+    dr.add_argument("--button", default="left")
+    dr.add_argument("--duration", type=float, default=0.3)
+    dr.add_argument("--direct", action="store_true")
+    dr.set_defaults(func=cmd_drag)
+
+    return ap
+
+
+def main():
+    args = build_parser().parse_args()
+    args.func(args)

pctr-0.1.0/src/pctr.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: pctr
+Version: 0.1.0
+Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
+Author: Space-lab515
+License-Expression: MIT
+Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywinauto>=0.6.8; platform_system == "Windows"
+Requires-Dist: uiautomation>=2.0; platform_system == "Windows"
+Requires-Dist: pyautogui>=0.9.54; platform_system == "Windows"
+Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
+Dynamic: license-file
+
+# pctr
+
+Element-based Windows UI Automation CLI for AI agents.
+
+Instead of screenshotting and guessing pixel coordinates, `pctr` finds controls
+by their **name / control type / automation id** and acts on them. Window moves,
+DPI changes, and layout shifts don't break your script.
+
+Built on `pywinauto` (UI Automation) with `pyautogui` / `pydirectinput` for raw
+mouse and keyboard input.
+
+## Install
+
+```bash
+pip install pctr
+```
+
+Windows only.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `pctr windows [--filter RE]` | List top-level windows (`pid=… \| title`). |
+| `pctr tree --title RE [--limit N]` | Dump the UIA control tree of a window. |
+| `pctr find --title RE --name RE [--control-type T] [--auto-id ID]` | List matching elements. |
+| `pctr click --title RE --name RE [--method auto\|invoke\|mouse] [--dbl]` | Click an element. |
+| `pctr set --title RE --name RE --text S` | Set a field via the UIA ValuePattern. |
+| `pctr type [--title RE --name RE] --text S [--delay 0.03] [--chunk 1]` | Type literal text. |
+| `pctr keys --keys "{ENTER}"` | Send a global key combo. |
+| `pctr hotkey --keys win+shift+s` | Send a modifier combo. |
+| `pctr focus --title RE` | Bring a window to the foreground. |
+| `pctr wait --title RE --name RE [--timeout S]` | Wait until an element exists. |
+| `pctr shot [--title RE] --out PATH` | Screenshot the screen or a window. |
+| `pctr size` | Print primary screen size as `WxH`. |
+| `pctr move --x N --y N` | Move the cursor. |
+| `pctr down / up [--button left]` | Press / release a mouse button. |
+| `pctr hold --ms 1000 [--x N --y N]` | Press, hold, release. |
+| `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
+| `pctr keydown / keyup --key a` | Hold / release a keyboard key. |
+| `pctr keyhold --key w --ms 1500` | Hold a key for a duration. |
+
+Common filters: `--title` (regex), `--name` (regex), `--control-type`
+(`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
+
+## The loop
+
+```bash
+pctr tree  --title "Notepad" --limit 60      # see what's clickable
+pctr click --title "Notepad" --name "^File$"
+pctr set   --title "Notepad" --name "Text Editor" --text "hello"
+```
+
+## Notes
+
+- Prefer `set` (ValuePattern) over `type` for text fields - it can't drop or
+  reorder characters.
+- `type` is sent in small chunks (`--chunk 1 --delay 0.03`); raise the delay for
+  Qt/Electron apps that garble fast input.
+- Global `type` / `keys` go to the OS-focused window - `pctr focus` first.
+- Qt apps expose a rich tree including embedded webviews. Electron apps expose
+  only the window frame unless accessibility is enabled (use `focus` + `keys`).
+
+## License
+
+MIT

pctr-0.1.0/src/pctr.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/pctr/__init__.py
+src/pctr/__main__.py
+src/pctr/cli.py
+src/pctr.egg-info/PKG-INFO
+src/pctr.egg-info/SOURCES.txt
+src/pctr.egg-info/dependency_links.txt
+src/pctr.egg-info/entry_points.txt
+src/pctr.egg-info/requires.txt
+src/pctr.egg-info/top_level.txt

pctr-0.1.0/src/pctr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pctr-0.1.0/src/pctr.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pctr = pctr.cli:main

pctr-0.1.0/src/pctr.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[:platform_system == "Windows"]
+pywinauto>=0.6.8
+uiautomation>=2.0
+pyautogui>=0.9.54
+pydirectinput>=1.0.4

pctr-0.1.0/src/pctr.egg-info/top_level.txt

@@ -0,0 +1 @@
+pctr