autogui 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3511abdbcca45728263b40b8e8a42fe1ab6918e6f06c954b6a34556451d3732
+  data.tar.gz: a2342704323c625b631235faaf9125ffd408bbb343c71b278374c960574ced32
+SHA512:
+  metadata.gz: 0fce037dcb816025469d84cd34602d2c8d7d03d61bb2b8211583e6204844c5043427fe91b6368fb7b8e7ba3a17a3bd8cf0d7ccaf600139a51fef0c21f3778671
+  data.tar.gz: 153b87b1e059f94f4a2309acad12becef177f4e1ac8c5458d60325bfc75d6736301a112aa54f64c268be65b03961157033679b3dfd896072203e93dcca208145

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-09-03
+
+### Added
+
+- First public release: Ruby port of Python PyAutoGUI.
+- Mouse: move, drag, click, scroll, button down/up, tweens.
+- Keyboard: write, press, hotkey, hold, key down/up, Unicode on Windows.
+- Screenshots and locate (PNG/BMP, grayscale, confidence, region).
+- Message boxes: alert, confirm, prompt, password.
+- Window helpers on Windows (list, activate, move, resize, min/max/close).
+- Fail-safe corners, `PAUSE`, screenshot logging, `run` mini-language.
+- CLI: `autogui info|mouse|screenshot`.
+- Windows (Win32/`Fiddle`), macOS (`osascript`/`screencapture`), Linux (`xdotool` + screenshot tools).

data/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) Al Sweigart
+Copyright (c) 2026 AutoGUI contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,431 @@
+# AutoGUI
+
+[![Gem Version](https://badge.fury.io/rb/autogui.svg)](https://rubygems.org/gems/autogui)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+Ruby library for desktop GUI automation: mouse, keyboard, screenshots, image search, message boxes, and window control.
+
+It is a Ruby port of Python [PyAutoGUI](https://pyautogui.readthedocs.io/). Call `AutoGUI` after `require "autogui"`. Snake_case is the Ruby API (`move_to`, `left_click`). CamelCase aliases match Python (`moveTo`, `leftClick`).
+
+**No runtime gem dependencies.** Ruby 2.7+ and the standard library are enough.
+
+> **Fail-safe:** moving the mouse into a corner of the primary screen raises `AutoGUI::FailSafeException` and stops the script. Leave `AutoGUI.FAILSAFE = true` unless you have a very good reason not to.
+
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Safety](#safety)
+- [Coordinates](#coordinates)
+- [Mouse](#mouse)
+- [Keyboard](#keyboard)
+- [Screenshots and image search](#screenshots-and-image-search)
+- [Message boxes](#message-boxes)
+- [Windows](#windows)
+- [Settings](#settings)
+- [Tweens](#tweens)
+- [Mini-language](#mini-language)
+- [CLI](#cli)
+- [Platforms](#platforms)
+- [Exceptions](#exceptions)
+- [API reference](#api-reference)
+- [Development](#development)
+- [License](#license)
+
+Full method tables live in [docs/api.md](docs/api.md). A longer walkthrough is in [docs/guide.md](docs/guide.md).
+
+## Install
+
+### RubyGems
+
+```
+gem install autogui
+```
+
+```ruby
+require "autogui"
+
+p AutoGUI.size
+# => Size(width=1920, height=1080)
+```
+
+### Bundler
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "autogui"
+```
+
+```
+bundle install
+```
+
+### From GitHub (before / besides RubyGems)
+
+```ruby
+# Gemfile
+gem "autogui", git: "https://github.com/pardeep2690/autogui.git"
+```
+
+Or build a `.gem` from the repo:
+
+```
+git clone https://github.com/pardeep2690/autogui.git
+cd autogui
+gem build autogui.gemspec
+gem install autogui-1.0.0.gem
+```
+
+### Platform extras
+
+| OS | Mouse / keyboard | Screenshots | Notes |
+| --- | --- | --- | --- |
+| **Windows** | Win32 via stdlib `Fiddle` | GDI | Works out of the box |
+| **macOS** | `osascript` | `screencapture` | Grant Accessibility to Terminal / Ruby |
+| **Linux** | `xdotool` | `scrot`, ImageMagick `import`, or `grim` | Install those tools |
+
+```
+# Debian / Ubuntu
+sudo apt-get install xdotool scrot
+```
+
+## Quick start
+
+```ruby
+require "autogui"
+
+AutoGUI.PAUSE = 0.25
+AutoGUI.FAILSAFE = true
+
+width, height = AutoGUI.size
+x, y = AutoGUI.position
+
+AutoGUI.move_to(width / 2, height / 2, duration: 0.4)
+AutoGUI.click
+AutoGUI.write("Hello from AutoGUI", interval: 0.02)
+AutoGUI.press("enter")
+AutoGUI.hotkey("ctrl", "s")
+
+img = AutoGUI.screenshot("desktop.png")
+box = AutoGUI.locate_on_screen("button.png")
+AutoGUI.click(box) if box
+```
+
+Give yourself a moment before the script takes over:
+
+```ruby
+AutoGUI.countdown(3)   # prints 3 2 1
+AutoGUI.click(100, 200)
+```
+
+## Safety
+
+Every public action (move, click, type, …) does two things:
+
+1. **Fail-safe check** — if the cursor is on a corner listed in `AutoGUI.FAILSAFE_POINTS`, it raises `AutoGUI::FailSafeException`.
+2. **Pause** — sleeps `AutoGUI.PAUSE` seconds (default `0.1`) so you can yank the mouse to a corner.
+
+```ruby
+AutoGUI.FAILSAFE = true     # default; do not disable in production scripts
+AutoGUI.PAUSE = 0.1         # seconds after each call
+```
+
+Corners of the primary monitor are registered at load time. Do not `move_to(0, 0)` while fail-safe is on.
+
+Rescue it if you want a clean shutdown:
+
+```ruby
+begin
+  AutoGUI.move_to(500, 500)
+  AutoGUI.click
+rescue AutoGUI::FailSafeException
+  warn "aborted: mouse in a screen corner"
+end
+```
+
+## Coordinates
+
+Origin is the **top-left** of the primary display. `x` increases to the right, `y` increases downward.
+
+```ruby
+AutoGUI.size        # Size(width:, height:) — also AutoGUI.resolution
+AutoGUI.position    # Point(x:, y:) of the cursor
+AutoGUI.on_screen(100, 200)          # true / false
+AutoGUI.on_screen([100, 200])
+```
+
+`Point`, `Size`, and `Box` unpack like arrays:
+
+```ruby
+x, y = AutoGUI.position
+w, h = AutoGUI.size
+left, top, width, height = box
+```
+
+Most mouse methods accept:
+
+| Argument | Meaning |
+| --- | --- |
+| no args | current cursor position |
+| `x, y` | absolute pixel |
+| `[x, y]` | same |
+| `[left, top, width, height]` or a `Box` | center of that box |
+| `"needle.png"` | center of that image on screen (`locate_on_screen`) |
+| `x: nil, y: 80` | keep current x, set y (and the reverse) |
+
+## Mouse
+
+Buttons: `"left"`, `"middle"`, `"right"`, `"primary"`, `"secondary"` (or `1` / `2` / `3`). `"primary"` is left unless the OS has swapped buttons.
+
+```ruby
+AutoGUI.move_to(100, 150)
+AutoGUI.move_to(100, 150, duration: 1.0, tween: AutoGUI.method(:easeInOutQuad))
+AutoGUI.move(0, 10)                 # relative; aliases: move_rel
+AutoGUI.drag_to(300, 400, duration: 0.5, button: "left")
+AutoGUI.drag(50, 0)                 # relative drag
+
+AutoGUI.click
+AutoGUI.click(200, 220, clicks: 2, interval: 0.1, button: "right")
+AutoGUI.left_click
+AutoGUI.right_click
+AutoGUI.middle_click
+AutoGUI.double_click
+AutoGUI.triple_click
+
+AutoGUI.mouse_down(button: "left")
+AutoGUI.mouse_up(button: "left")
+
+AutoGUI.scroll(3)                   # positive = up, negative = down
+AutoGUI.hscroll(-2)                 # horizontal where the OS supports it
+AutoGUI.vscroll(3)
+```
+
+`duration:` below `AutoGUI.MINIMUM_DURATION` (0.1s) is treated as instant.
+
+## Keyboard
+
+Keys go to whatever window has focus.
+
+```ruby
+AutoGUI.write("Hello world!", interval: 0.05)
+AutoGUI.write(["a", "b", "left", "enter"])   # alias: typewrite
+AutoGUI.press("enter")
+AutoGUI.press("f1", presses: 3, interval: 0.2)
+AutoGUI.press(["up", "up", "down"])
+AutoGUI.hotkey("ctrl", "c")                  # alias: shortcut
+AutoGUI.hold("shift") { AutoGUI.press(["left", "left"]) }
+AutoGUI.key_down("ctrl")
+AutoGUI.key_up("ctrl")
+AutoGUI.valid_key?("esc")                    # => true
+```
+
+`hold` **requires a block**; the key is released in `ensure`.
+
+Common names (full list: `AutoGUI::KEYBOARD_KEYS`):
+
+`enter` `return` `esc` `tab` `space` `backspace` `delete` `shift` `ctrl` `alt` `win` `command` `option` `up` `down` `left` `right` `home` `end` `pageup` `pagedown` `f1`…`f24` plus printable characters.
+
+On Windows, non-ASCII characters in `write` are sent as Unicode.
+
+## Screenshots and image search
+
+```ruby
+img = AutoGUI.screenshot                         # AutoGUI::Image
+img.save("desktop.png")
+AutoGUI.screenshot("desktop.png")                # capture and save
+AutoGUI.screenshot("crop.png", region: [0, 0, 300, 400])  # left, top, width, height
+
+r, g, b = AutoGUI.pixel(100, 200)
+AutoGUI.pixel_matches_color(100, 200, [255, 255, 255], tolerance: 10)
+
+box = AutoGUI.locate_on_screen("button.png")     # Box or nil
+# Box(left:, top:, width:, height:)
+pt  = AutoGUI.locate_center_on_screen("button.png")  # Point or nil
+AutoGUI.click(box) if box
+
+AutoGUI.locate_all_on_screen("icon.png").each { |b| p b }
+AutoGUI.locate("needle.png", "haystack.png")
+AutoGUI.center([10, 20, 40, 30])                 # Point at the box center
+```
+
+Needle files may be **PNG or BMP**. Matching is pure Ruby (no OpenCV).
+
+```ruby
+AutoGUI.locate_on_screen("needle.png", grayscale: true, confidence: 0.9)
+AutoGUI.locate_on_screen("needle.png", region: [0, 0, 800, 600], minSearchTime: 5)
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `grayscale:` | `false` | compare luminance only |
+| `confidence:` | `nil` (exact pixels) | `0.0`–`1.0` mean-absolute-error score |
+| `region:` | full screen | `[left, top, width, height]` |
+| `minSearchTime:` | `0` | keep retrying that many seconds |
+
+By default a miss returns `nil`. To raise instead:
+
+```ruby
+AutoGUI.use_image_not_found_exception!(true)
+AutoGUI.locate_on_screen("missing.png")
+# raises AutoGUI::ImageNotFoundException
+```
+
+`AutoGUI::Image` supports `getpixel`, `putpixel`, `crop`, `grayscale`, `save`, and `Image.open(path)`.
+
+## Message boxes
+
+```ruby
+AutoGUI.alert("Done.")
+choice = AutoGUI.confirm("Continue?")            # "OK" or "Cancel"
+name   = AutoGUI.prompt("Your name?", "Title", "guest")
+secret = AutoGUI.password("Password")            # nil if cancelled
+```
+
+On Windows these use Win32 / VBScript dialogs. Elsewhere they use `osascript` or `zenity` when present.
+
+## Windows
+
+Window helpers are implemented for **Windows**. They return empty / `nil` on other OSes.
+
+```ruby
+AutoGUI.get_all_titles
+AutoGUI.get_all_windows
+AutoGUI.get_active_window
+AutoGUI.get_active_window_title
+AutoGUI.get_windows_with_title("Notepad")        # substring, case-insensitive
+AutoGUI.get_windows_at(400, 300)
+
+win = AutoGUI.get_windows_with_title("Notepad").first
+win&.activate
+win&.move_to(40, 40)
+win&.resize_to(800, 600)
+win&.minimize
+win&.maximize
+win&.restore
+win&.close
+win.title
+win.left
+win.top
+win.width
+win.height
+win.visible?
+```
+
+CamelCase aliases exist (`getAllTitles`, `getActiveWindow`, …).
+
+## Settings
+
+| Setting | Default | Role |
+| --- | --- | --- |
+| `AutoGUI.PAUSE` | `0.1` | seconds to sleep after each public call |
+| `AutoGUI.FAILSAFE` | `true` | abort when the cursor is on a fail-safe point |
+| `AutoGUI.FAILSAFE_POINTS` | four corners | `Point` list checked before actions |
+| `AutoGUI.MINIMUM_DURATION` | `0.1` | shorter `duration:` moves are instant |
+| `AutoGUI.MINIMUM_SLEEP` | `0.05` | floor between tween steps |
+| `AutoGUI.DARWIN_CATCH_UP_TIME` | `0.01` | extra delay after macOS events |
+| `AutoGUI.LOG_SCREENSHOTS` | `false` | save a PNG on each action |
+| `AutoGUI.LOG_SCREENSHOTS_LIMIT` | `10` | rotate old log screenshots |
+
+```ruby
+AutoGUI.print_info
+# Platform, Ruby version, AutoGUI version, executable, resolution, timestamp
+```
+
+## Tweens
+
+Pass any callable that maps `0.0..1.0` → `0.0..1.0` as `tween:`:
+
+```ruby
+AutoGUI.move_to(800, 400, duration: 1.2, tween: AutoGUI.method(:easeInOutQuad))
+```
+
+Built-ins: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeInQuint`, `easeOutQuint`, `easeInOutQuint`, `easeInSine`, `easeOutSine`, `easeInOutSine`, `easeInExpo`, `easeOutExpo`, `easeInOutExpo`, `easeInCirc`, `easeOutCirc`, `easeInOutCirc`, `easeInElastic`, `easeOutElastic`, `easeInOutElastic`, `easeInBack`, `easeOutBack`, `easeInOutBack`, `easeInBounce`, `easeOutBounce`, `easeInOutBounce`.
+
+## Mini-language
+
+```ruby
+AutoGUI.run("c c g 100, 200 c")
+```
+
+| Token | Action |
+| --- | --- |
+| `c` `l` `m` `r` | click primary / left / middle / right |
+| `su` `sd` | scroll up / down |
+| `ss` | screenshot `screenshotN.png` |
+| `gX,Y` / `g+X,-Y` | `move_to` / relative `move` |
+| `dX,Y` / `d+X,-Y` | `drag_to` / relative `drag` |
+| `k'enter'` | `press` |
+| `w'hello'` | `write` |
+| `h'ctrl,c'` | `hotkey` |
+| `a'hi'` | `alert` |
+| `s0.5` | `sleep` |
+| `p0.2` | set `PAUSE` for the rest of this `run` (restored after) |
+| `f3(cc)` | repeat inner commands 3 times |
+
+Whitespace is ignored. Quotes must be single quotes.
+
+## CLI
+
+After `gem install autogui` the `autogui` executable is on your PATH:
+
+```
+autogui info
+autogui mouse                 # live X/Y/RGB; Ctrl-C to quit
+autogui screenshot out.png
+```
+
+From a git checkout: `ruby bin/autogui info`.
+
+## Platforms
+
+- **Windows** — `user32` / `gdi32` through `Fiddle`. DPI-aware. Unicode typing via `SendInput`. Window enumeration via `EnumWindows`.
+- **macOS** — System Events through `osascript`; captures with `screencapture`. Enable Accessibility for the process running Ruby.
+- **Linux** — `xdotool` for input; `scrot` / `import` / `grim` for captures.
+
+## Exceptions
+
+| Class | When |
+| --- | --- |
+| `AutoGUI::AutoGUIException` | invalid arguments, missing tools, bad images |
+| `AutoGUI::FailSafeException` | cursor on a fail-safe corner |
+| `AutoGUI::ImageNotFoundException` | locate\* miss *and* exceptions enabled |
+
+## API reference
+
+See **[docs/api.md](docs/api.md)** for every method, alias, return type, and option.
+
+See **[docs/guide.md](docs/guide.md)** for recipes, coordinate details, and the command language.
+
+See **[CHANGELOG.md](CHANGELOG.md)** for releases.
+
+## Development
+
+```
+git clone https://github.com/pardeep2690/autogui.git
+cd autogui
+ruby -Ilib:test test/test_autogui.rb
+```
+
+Live mouse tests stay skipped unless you opt in:
+
+```
+# Unix
+AUTOGUI_LIVE=1 ruby -Ilib:test test/test_autogui.rb
+
+# Windows PowerShell
+$env:AUTOGUI_LIVE=1; ruby -Ilib:test test/test_autogui.rb
+```
+
+Examples:
+
+```
+ruby -Ilib examples/hello.rb
+ruby -Ilib examples/locate_demo.rb path/to/needle.png
+```
+
+Publishing this gem to RubyGems is documented in [docs/publishing.md](docs/publishing.md).
+
+## License
+
+BSD 3-Clause. API and behavior follow [PyAutoGUI](https://github.com/asweigart/pyautogui) (Al Sweigart).

data/bin/autogui

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "autogui"
+
+case ARGV[0]
+when "info", nil
+  AutoGUI.printInfo
+when "mouse", "mouseinfo", "position"
+  AutoGUI.displayMousePosition
+when "screenshot"
+  path = ARGV[1] || "screenshot.png"
+  AutoGUI.screenshot(path)
+  puts "saved #{path}"
+else
+  warn "usage: autogui [info|mouse|screenshot [file.png]]"
+  exit 1
+end

data/docs/api.md

@@ -0,0 +1,186 @@
+# AutoGUI API reference
+
+All methods below live on the `AutoGUI` module unless noted. Snake_case is canonical. CamelCase aliases are listed in the Alias column.
+
+Return values that unpack (`Point`, `Size`, `Box`) also respond to `to_a`, `[]`, and named readers.
+
+---
+
+## Screen and cursor
+
+| Method | Alias | Returns | Notes |
+| --- | --- | --- | --- |
+| `size` | `resolution` | `Size` | Primary monitor width × height |
+| `position(x = nil, y = nil)` | | `Point` | Override x and/or y if passed |
+| `on_screen(x, y = nil)` | `onScreen` | `true`/`false` | Also accepts `[x, y]` |
+| `pixel(x, y)` | | `[r, g, b]` | 0–255 each |
+| `pixel_matches_color(x, y, rgb, tolerance: 0)` | `pixelMatchesColor` | `true`/`false` | `rgb` is `[r, g, b]` |
+| `print_info(dont_print = false)` | `printInfo` | `String` | Also prints unless `dont_print` |
+| `get_info` | `getInfo` | Array | platform, Ruby, version, executable, size, timestamp |
+| `sleep(seconds)` | | `nil` | `Kernel.sleep` |
+| `countdown(seconds)` | | `nil` | Prints `3 2 1` |
+| `fail_safe_check` | `failSafeCheck` | `nil` or raises | Used internally |
+
+---
+
+## Mouse
+
+Shared keywords on movement/click helpers: `duration:` (seconds), `tween:` (callable), `logScreenshot:` (`true`/`false`/`nil`), `_pause:` (internal).
+
+`x` / `y` follow [coordinate rules](guide.md#coordinates): numbers, `[x, y]`, a `Box`, or an image filename.
+
+| Method | Alias | Notes |
+| --- | --- | --- |
+| `move_to(x = nil, y = nil, duration: 0)` | `moveTo` | Absolute move |
+| `move(x = nil, y = nil, duration: 0)` | `move_rel`, `moveRel` | Relative move |
+| `drag_to(x = nil, y = nil, duration: 0, button: "primary", mouseDownUp: true)` | `dragTo` | Drag while holding `button` |
+| `drag(x = 0, y = 0, ...)` | `drag_rel`, `dragRel` | Relative drag |
+| `click(x = nil, y = nil, clicks: 1, interval: 0, button: "primary", duration: 0)` | | |
+| `left_click(...)` | `leftClick` | |
+| `right_click(...)` | `rightClick` | |
+| `middle_click(...)` | `middleClick` | |
+| `double_click(..., button: "left")` | `doubleClick` | |
+| `triple_click(..., button: "left")` | `tripleClick` | |
+| `mouse_down(x = nil, y = nil, button: "primary")` | `mouseDown` | |
+| `mouse_up(x = nil, y = nil, button: "primary")` | `mouseUp` | |
+| `scroll(clicks, x = nil, y = nil)` | | Positive = up |
+| `hscroll(clicks, x = nil, y = nil)` | | Horizontal |
+| `vscroll(clicks, x = nil, y = nil)` | | Vertical (same as `scroll` on Windows) |
+| `display_mouse_position(x_offset = 0, y_offset = 0)` | `displayMousePosition`, `mouseInfo`, `mouse_info` | Live HUD; Ctrl-C to quit |
+
+Buttons: `"left"` `"middle"` `"right"` `"primary"` `"secondary"` or `1` `2` `3`. On Linux, `4`–`7` are extra buttons.
+
+---
+
+## Keyboard
+
+| Method | Alias | Notes |
+| --- | --- | --- |
+| `write(message, interval: 0)` | `typewrite` | String of chars, or array of key names |
+| `press(keys, presses: 1, interval: 0)` | | String or array of key names |
+| `hotkey(*keys, interval: 0)` | `shortcut` | Down in order, up in reverse |
+| `hold(keys) { ... }` | | Requires a block; releases in `ensure` |
+| `key_down(key)` | `keyDown` | |
+| `key_up(key)` | `keyUp` | |
+| `valid_key?(key)` | `isValidKey`, `is_valid_key` | |
+| `shift_character?(ch)` | `isShiftCharacter` | Uppercase or `~!@#$…` |
+
+`keys` / `key` values are strings from `AutoGUI::KEYBOARD_KEYS` (also `AutoGUI::KEY_NAMES`).
+
+Modifier aliases: `ctrl` = left ctrl, `alt` = left alt, `shift` = left shift, `win` / `command` = left Super/Cmd.
+
+---
+
+## Screenshots and locate
+
+| Method | Alias | Returns |
+| --- | --- | --- |
+| `screenshot(path = nil, region: nil)` | `grab` | `Image`; saves if `path` given |
+| `locate_on_screen(image, grayscale: false, confidence: nil, region: nil, minSearchTime: 0)` | `locateOnScreen` | `Box` or `nil` |
+| `locate_center_on_screen(...)` | `locateCenterOnScreen` | `Point` or `nil` |
+| `locate_all_on_screen(...)` | `locateAllOnScreen` | Enumerator of `Box` |
+| `locate(needle, haystack, grayscale: false, confidence: nil)` | | `Box` or `nil` |
+| `locate_all(needle, haystack, ...)` | `locateAll` | Enumerator of `Box` |
+| `locate_on_window(image, title, ...)` | `locateOnWindow` | `Box` in that window |
+| `center(box)` | | `Point` |
+| `use_image_not_found_exception!(value = true)` | `useImageNotFoundException` | miss raises instead of `nil` |
+
+`region` is `[left, top, width, height]`. `image` / `needle` / `haystack` may be a path or an `AutoGUI::Image`.
+
+### `AutoGUI::Image`
+
+| Method | Notes |
+| --- | --- |
+| `Image.open(path)` | PNG or uncompressed BMP |
+| `Image.from_pixels(w, h, [[r,g,b], ...])` | |
+| `#width` `#height` `#data` | RGB bytes, top-down |
+| `#getpixel(x, y)` | `[r, g, b]` |
+| `#putpixel(x, y, [r, g, b])` | |
+| `#crop(left, top, width, height)` | new `Image` |
+| `#grayscale` | new `Image` |
+| `#save(path)` | `.png` or `.bmp` from extension |
+| `#to_png` `#to_bmp` | binary strings |
+
+---
+
+## Dialogs
+
+| Method | Returns |
+| --- | --- |
+| `alert(text = "", title = "", button = "OK")` | button label |
+| `confirm(text = "", title = "", buttons = ["OK", "Cancel"])` | chosen label |
+| `prompt(text = "", title = "", default = "")` | string or `nil` |
+| `password(text = "", title = "", default = "", mask = "*")` | string or `nil` |
+
+---
+
+## Window objects (Windows OS)
+
+Module functions:
+
+| Method | Alias |
+| --- | --- |
+| `get_all_windows` | `getAllWindows` |
+| `get_all_titles` | `getAllTitles` |
+| `get_active_window` | `getActiveWindow` |
+| `get_active_window_title` | `getActiveWindowTitle` |
+| `get_windows_with_title(title)` | `getWindowsWithTitle` |
+| `get_windows_at(x, y)` | `getWindowsAt` |
+
+`AutoGUI::Window` instance:
+
+| Method | Notes |
+| --- | --- |
+| `#title` `#hwnd` | |
+| `#left` `#top` `#width` `#height` `#right` `#bottom` `#box` | |
+| `#visible?` `#minimized?` `#maximized?` | |
+| `#activate` `#minimize` `#maximize` `#restore` `#hide` `#close` | chainable |
+| `#move_to(x, y)` | alias `moveTo` |
+| `#resize_to(w, h)` | alias `resizeTo` |
+
+---
+
+## Geometry
+
+```ruby
+AutoGUI::Point.new(x, y)           # #x #y
+AutoGUI::Size.new(width, height)   # #width #height
+AutoGUI::Box.new(left, top, width, height)
+```
+
+All three implement `#to_a`, `#to_ary` (so `x, y = point` works), `#[]`, and `#==` against arrays.
+
+---
+
+## Tweens
+
+`AutoGUI.linear(n)` and `AutoGUI.easeInQuad(n)` … `AutoGUI.easeInOutBounce(n)` — see the README. `n` must be in `0.0..1.0` or `AutoGUIException` is raised.
+
+`get_point_on_line(x1, y1, x2, y2, n)` → `[x, y]` (`getPointOnLine`).
+
+---
+
+## Mini-language
+
+`AutoGUI.run(command_string)` — tokens documented in the README and [guide.md](guide.md#mini-language).
+
+---
+
+## Constants
+
+| Name | Value |
+| --- | --- |
+| `AutoGUI::VERSION` | gem version string |
+| `AutoGUI::LEFT` `MIDDLE` `RIGHT` `PRIMARY` `SECONDARY` | button names |
+| `AutoGUI::KEYBOARD_KEYS` | array of valid key strings (`KEY_NAMES`) |
+| `AutoGUI::QWERTY` `QWERTZ` | layout strings |
+
+---
+
+## Exceptions
+
+```ruby
+AutoGUI::AutoGUIException          # StandardError
+AutoGUI::FailSafeException         # < AutoGUIException
+AutoGUI::ImageNotFoundException    # < AutoGUIException
+```