plotruler 0.1.3__tar.gz

plotruler-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

plotruler-0.1.3/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+# PyInstaller work dir and its generated artifacts live under build/; keep
+# the source (spec, entry, icon, version info) tracked.
+build/plotruler/
+build/__pycache__/
+build/*.toc
+build/*.pkg
+build/*.zip
+*.egg-info/

plotruler-0.1.3/.opencode/opencode.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}

plotruler-0.1.3/.opencode/scripts/check.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Offscreen smoke test: import the overlay (which pulls in the Qt-free
+// core, storage, format, tray, hotkey) without showing a window. Catches
+// broken imports and mismatched Qt enums before launching the GUI.
+import { spawnSync } from "node:child_process";
+
+const python = process.env.PYTHON || "python";
+const snippet =
+  "import os;" +
+  "os.environ['QT_QPA_PLATFORM']='offscreen';" +
+  "from plotruler.overlay import OverlayWindow;" +
+  "from plotruler import format, storage;" +
+  "print('imports OK')";
+
+const res = spawnSync(python, ["-c", snippet], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+process.exit(res.status ?? 1);

plotruler-0.1.3/.opencode/scripts/relaunch.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Kill any running PlotRuler dev instance and relaunch it.
+//
+// Never blanket-kill python: only processes whose command line mentions
+// 'plotruler' are stopped. The relaunch then starts the app in the
+// foreground. The tray-resident app never exits, so this script blocks
+// until the shell times out — that is expected, not a crash.
+import { spawn, spawnSync } from "node:child_process";
+
+const python = process.env.PYTHON || "python";
+
+function killPlotRuler() {
+  const plat = process.platform;
+  let list;
+  if (plat === "win32") {
+    // PowerShell's CIM query returns process ids to kill.
+    const ps = spawnSync(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-Command",
+        "Get-CimInstance Win32_Process -Filter \"Name = 'python.exe'\" | " +
+          "Where-Object { $_.CommandLine -match 'plotruler' } | " +
+          "ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
+      ],
+      { stdio: "inherit" },
+    );
+    return ps.status ?? 0;
+  }
+  // Non-Windows: pkill matching the package path.
+  const res = spawnSync("pkill", ["-f", "plotruler"], { stdio: "ignore" });
+  // pkill returns 1 when nothing matched, which is fine.
+  return 0;
+}
+
+killPlotRuler();
+// Give the OS a moment to release the socket/process before relaunching.
+const wait = spawnSync("node", ["-e", "setTimeout(()=>{}, 1000)"], {
+  stdio: "inherit",
+});
+const app = spawn(python, ["-m", "plotruler"], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+app.on("exit", (code) => process.exit(code ?? 0));

plotruler-0.1.3/.opencode/scripts/verify.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Lint, format-check, and run the test suite. Exits nonzero on failure.
+import { spawnSync } from "node:child_process";
+
+const steps = [
+  ["ruff lint", ["-m", "ruff", "check", "."]],
+  ["ruff format check", ["-m", "ruff", "format", "--check", "."]],
+  ["pytest", ["-m", "pytest", "-q"]],
+];
+
+// Run the conda env's python as-is (assuming it is already active).
+const python = process.env.PYTHON || "python";
+
+let ok = true;
+for (const [label, args] of steps) {
+  const res = spawnSync(python, args, { stdio: "inherit", cwd: process.cwd() });
+  if (res.status !== 0) {
+    console.error(`\nFAILED: ${label} (exit ${res.status})`);
+    ok = false;
+    break;
+  }
+}
+process.exit(ok ? 0 : 1);

plotruler-0.1.3/AGENTS.md

@@ -0,0 +1,80 @@
+# PlotRuler
+
+PlotRuler is a **cross-platform** desktop overlay for reading (X, Y) values off a graph shown on screen. Calibrate once against a known plot (click two points per axis, type their values), then hover to read coordinates and click to copy.
+
+The graph itself is **never rendered by PlotRuler** — it is whatever other app is on screen underneath the overlay (a browser, a PDF viewer, a plotting window). PlotRuler is a **live translucent overlay** that sits on top and reads through it, not a screenshot/frozen-image workflow. Calibration persists to disk across sessions and across hide/show.
+
+Stack: Python 3.14 (conda env `plotruler`) · PySide6 6.11.2 (Qt) · pytest. The app is tray-resident; **Win+Alt+P** toggles the overlay.
+
+## Quick commands
+
+```sh
+conda activate plotruler
+python -m plotruler        # run the app
+pytest                     # run tests
+ruff check .               # lint
+ruff format .              # auto-format
+python build/build.py      # build dist/PlotRuler.exe (requires pyinstaller)
+```
+
+## Environment
+
+- Work only in the conda env `plotruler` (Python 3.14). Never touch the system Python.
+- Dependencies and tool config live in **`pyproject.toml`** (PEP 621, hatchling build backend). No `requirements.txt`.
+- Windows is the primary platform, but the app is meant to be **cross-platform and useful to other people**. Keep the math and calibration model platform-agnostic; the overlay/tray/hotkey shell is Windows-first and may use small Win32 shims where needed.
+
+## Code conventions
+
+- **No type hints.** The owner prefers plain old-school Python. Clarity, simple names, and docstrings over annotations. (The codebase is read by humans, not type-checked.)
+- Comments explain **why**, not what. If a comment would just restate the code, rewrite the code to be clearer instead. Never delete or omit comments while editing.
+- Line length 79 (PEP8), enforced by ruff.
+- Pythonic and simple. Write code a reader can follow without mental gymnastics; favor the clear, straightforward approach over clever one-liners and premature optimization.
+- Architecture: the pixel→value calibration math must stay **Qt-free** (importable without PySide6) so it stays unit-testable and portable. Everything else (overlay, calibration UI, tray, hotkeys) is ordinary Qt code. No artificial core/shell package split beyond that.
+
+## GUI conventions
+
+- One frameless translucent window. Title bar, crosshair, readout, and instruction box are custom-painted with QPainter — there are no native widgets.
+- Calibration is stored in **absolute screen coordinates** (physical pixels). Moving or resizing the overlay never invalidates a calibration.
+- DPI-aware: Qt high-DPI scaling is on, and the math must stay correct at 100% and 150% display scaling. This silently corrupting values would be the worst failure mode.
+
+## Testing
+
+- pytest covers the math (`tests/test_*.py`). Every test function needs a docstring stating what behavior it verifies and why. New functions get tests; bug fixes get regression tests.
+- The GUI is **not unit-tested** — translucent always-on-top overlays are interaction- heavy and don't test well without a running event loop. Keep widgets thin (logic in testable functions), and verify the GUI by running it. pytest-qt can be added later if a real need shows up.
+- Give testing instructions to the user *before* running the program. 
+
+## Hotkey
+
+- **Win+Alt+P** is the default summon/toggle hotkey (P for PlotRuler). It is configurable — this is required, not optional. It is unclaimed on stock Windows; the only known collision is PowerToys' optional "Mouse Pointer Crosshairs", and Win+Ctrl+P is a free alternative if that matters. Avoid plain Ctrl+Alt+Space — Visual Studio and ReSharper both bind it, so IDE users would have to remap.
+- **Ctrl+N** (new calibration) and **Esc** (hide) are in-app keys, not global.
+
+## Commits
+
+- Conventional Commits: `feat:`, `fix:`, `test:`, `refactor:`, `docs:`, `chore:`.
+- Small, atomic commits: one coherent idea plus its tests and docs — nothing else.
+- Comprehensive messages: subject summarizes; body explains the problem, the approach, and any trade-offs.
+- Add the trailer `Co-authored-by: opencode <opencode@anomalyco.ai>` to every commit.
+- Never commit agent-generated scratch files (summary notes, session dumps, chat exports).
+
+## Versioning
+
+- **Semantic Versioning** (MAJOR.MINOR.PATCH). Bump MAJOR on breaking changes, MINOR on new features, PATCH on fixes; pre-release tags (`-rc1`, etc.) are allowed when preparing a release.
+- The version lives in **three places** that must be bumped together in the same commit:
+  - `pyproject.toml` → `[project] version`
+  - `plotruler/__init__.py` → `__version__`
+  - `build/version_info.txt` → the `filevers`/`prodvers` tuples and the `FileVersion`/`ProductVersion` strings
+- Docstring on the entry point or README may mention the version, but only as a mirror of these three.
+- The version in the code is the source of truth; tag a release with a matching `vX.Y.Z` when cutting one.
+
+## Docs
+
+- Update the README when user-visible behavior changes.
+- Update this AGENTS.md when the development guidelines change.
+
+## Scope (current)
+
+MVP is: live translucent overlay; linear-rectangle calibration only (X axis then Y axis, two click-points each); hover-to-read; click-to-copy with "copied" confirmation; custom always-visible translucent title bar with resize handles; calibration + window position persistence; tray icon and global hotkey.
+
+Deferred: corner/homography mode, log axes, X-only/Y-only modes, pins/slope readout, CSV digitizing.
+
+`spec.md` is the product reference. When it conflicts with decisions recorded here, this file wins — the spec was AI-written and worded more rigidly than the product actually is.

plotruler-0.1.3/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 endolith
+
+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.
+

plotruler-0.1.3/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: plotruler
+Version: 0.1.3
+Summary: Read (X, Y) values off an on-screen graph with a translucent overlay
+Project-URL: Homepage, https://github.com/endolith/plotruler
+Project-URL: Repository, https://github.com/endolith/plotruler
+Project-URL: Issues, https://github.com/endolith/plotruler/issues
+Project-URL: Changelog, https://github.com/endolith/plotruler/releases
+Author: endolith
+Maintainer: endolith
+License: MIT License
+        
+        Copyright (c) 2026 endolith
+        
+        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.
+        
+License-File: LICENSE
+Keywords: calibration,digitize,digitizer,graph,overlay,plot,readout
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: pyside6==6.11.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PlotRuler
+
+A translucent desktop overlay for accurately reading (X, Y) values off a graph
+shown on screen. Calibrate once against the known plot coordinates (click at two
+points on each axis, and type their labeled values), then hover to read
+coordinates anywhere else, and click to copy.
+
+The graph itself is not rendered by PlotRuler — it is whatever other app is on
+screen underneath the overlay (a browser, a PDF viewer, a plotting window, etc.)
+PlotRuler is a **live translucent overlay** that reads through it, not a
+screenshot workflow.
+
+## How it works
+
+Calibration and readout all live in **absolute screen coordinates** (physical
+pixels), not coordinates relative to the overlay window. That is what makes the
+overlay feel stable: you can drag or resize the window and the calibrated graph
+box stays glued to the graph underneath wherever it sits on screen. Windows and
+macOS get this natively; Linux/X11 uses the same absolute-coordinate model.
+
+Each axis is calibrated independently with two reference points — click once at
+a known pixel on the axis, type its labeled value, then repeat for a second
+point. PlotRuler fits a line through those pairs (linear by default, optional
+log), so it works for any graph where the scale is straight-line or log.
+Everything persists to disk (calibration, window position, number format), so
+the overlay reopens already calibrated.
+
+## Features
+
+- **Hover to read** — a crosshair and a (X, Y) readout follow the cursor once
+  calibrated, showing the values under it.
+- **Click to copy** — a click copies the hovered coordinate as e.g.
+  `(12.5, 4.0)` and flashes a confirmation.
+- **Number formats** — plain, scientific, engineering, E-notation, SI
+  (auto/1..6 via the number keys, or the tray menu).
+- **Calibration** — Ctrl+N starts a fresh one; Ctrl+Z undoes a step; Esc
+  cancels. Each axis gets its own linear/log choice.
+- **Custom frameless title bar** — translucent, with minimize, maximize, and
+  (on no-tray systems) a close button.
+- **Tray resident** — sits in the system tray; tray click toggles the overlay.
+
+## Platform comparison
+
+| | Windows | macOS | Linux/X11 |
+|---|---|---|---|
+| Absolute screen coordinates | ✅ native | ✅ native | ✅ (same model) |
+| Overlay readout through the graph | ✅ | ✅ | ✅ |
+| Move / resize the window | ✅ native | ✅ native | ✅ Qt-driven |
+| Calibration survives window move/resize | ✅ | ✅ | ✅ |
+| Global hotkey (Win+Alt+P / Cmd+Alt+P) | ✅ RegisterHotKey | ⏳ | ⏳ deferred (XGrabKey) |
+| System tray | ✅ | ✅ | ⚠️ depends on DE |
+| Build/ship | .exe (PyInstaller) | ⏳ untested | pip / PyPI wheel |
+
+**Wayland is not supported yet.** Wayland forbids absolute screen coordinates by
+design and GNOME refuses the workarounds, so the overlay model cannot work there
+without a window-relative rewrite. Linux requires an **X11** session for now;
+see `LINUX_PLAN.md`.
+
+Notes on the platform table:
+- **macOS is untested.** The architecture is OS-portable (absolute screen
+  coordinates, Qt overlay), and Qt provides a native macOS path, but no macOS
+  build or hotkey code exists in this repo yet. Treat the macOS column as a
+  design feature, not a shipped one.
+- **Global hotkey** — Windows-only today. On Linux the tray (or Ctrl+N/Esc and
+  the title-bar buttons) are the controls; an X11 `XGrabKey` hotkey is a
+  follow-up.
+- **System tray** — always present on Windows; on Linux it depends on the
+  desktop environment. GNOME has no tray by default unless the *AppIndicator
+  and KStatusNotifier* extension is installed. When no tray exists, PlotRuler
+  shows a close button and quits on minimize/close/Esc rather than hiding into
+  an unreachable state.
+
+## Development
+
+```sh
+conda activate plotruler
+python -m plotruler        # run the app
+pytest                     # run tests
+ruff check .               # lint
+ruff format .              # auto-format
+```
+
+## Linux
+
+Linux requires an X11 session (Wayland is deferred — see above). Qt 6.5+
+also needs the `xcb-cursor` system library for the X11 backend, which pip
+cannot install:
+
+```sh
+# Debian / Ubuntu
+sudo apt install libxcb-cursor0
+# Fedora / RHEL
+sudo dnf install xcb-util-cursor
+# Arch
+sudo pacman -S xcb-util-cursor
+```
+
+Install and run (no frozen binary on Linux):
+
+```sh
+pip install plotruler       # or, from source: pip install -e . then plotruler
+plotruler
+```
+
+> PyPI/wheels cannot install system libraries like `libxcb-cursor`; without it
+> the app aborts at first launch. Install it first (commands above). The
+> `build/install_linux.sh` helper also checks for it and fails fast with your
+> distro's package name.
+
+## Releases & publishing
+
+PlotRuler ships through **two channels**:
+
+| Channel | Artifact | Who uses it |
+|---|---|---|
+| **PyPI** (`pip install plotruler`) | wheel (`.whl`) | everyone, all platforms; the Linux and pip path |
+| **GitHub Releases** | `PlotRuler.exe` | Windows users who don't want pip |
+
+Publish a Python release to PyPI:
+
+```sh
+pip install build twine
+./build/publish_pypi.sh --check   # first: upload to TestPyPI and verify
+./build/publish_pypi.sh           # then: upload to PyPI
+```
+
+Requires `TWINE_USERNAME`/`TWINE_PASSWORD` (or a `~/.pypirc`), and an account
+with upload rights for the `plotruler` name. The package supports Python 3.10+
+(down to PySide6 6.11's own floor).
+
+The Windows `.exe` is separate and must be built on Windows.
+
+## Build a stand-alone Windows executable
+
+```sh
+python -m pip install pyinstaller
+python build/build.py
+```
+
+Produces a single-file, windowed `dist/PlotRuler.exe` with a tray icon and
+version metadata. The app bundles Qt, so the exe is ~46 MB but needs no Python
+install to run. This is the artifact you attach to a GitHub release.
+
+See `AGENTS.md` for development conventions.
+
+## License
+
+MIT License (see `LICENSE`).
+
+(This was generated almost entirely by AI under human direction, so likely lacks the human authorship required for copyright in the US and is therefore in the public domain.  MIT license applies anywhere else.)

plotruler-0.1.3/README.md

@@ -0,0 +1,150 @@
+# PlotRuler
+
+A translucent desktop overlay for accurately reading (X, Y) values off a graph
+shown on screen. Calibrate once against the known plot coordinates (click at two
+points on each axis, and type their labeled values), then hover to read
+coordinates anywhere else, and click to copy.
+
+The graph itself is not rendered by PlotRuler — it is whatever other app is on
+screen underneath the overlay (a browser, a PDF viewer, a plotting window, etc.)
+PlotRuler is a **live translucent overlay** that reads through it, not a
+screenshot workflow.
+
+## How it works
+
+Calibration and readout all live in **absolute screen coordinates** (physical
+pixels), not coordinates relative to the overlay window. That is what makes the
+overlay feel stable: you can drag or resize the window and the calibrated graph
+box stays glued to the graph underneath wherever it sits on screen. Windows and
+macOS get this natively; Linux/X11 uses the same absolute-coordinate model.
+
+Each axis is calibrated independently with two reference points — click once at
+a known pixel on the axis, type its labeled value, then repeat for a second
+point. PlotRuler fits a line through those pairs (linear by default, optional
+log), so it works for any graph where the scale is straight-line or log.
+Everything persists to disk (calibration, window position, number format), so
+the overlay reopens already calibrated.
+
+## Features
+
+- **Hover to read** — a crosshair and a (X, Y) readout follow the cursor once
+  calibrated, showing the values under it.
+- **Click to copy** — a click copies the hovered coordinate as e.g.
+  `(12.5, 4.0)` and flashes a confirmation.
+- **Number formats** — plain, scientific, engineering, E-notation, SI
+  (auto/1..6 via the number keys, or the tray menu).
+- **Calibration** — Ctrl+N starts a fresh one; Ctrl+Z undoes a step; Esc
+  cancels. Each axis gets its own linear/log choice.
+- **Custom frameless title bar** — translucent, with minimize, maximize, and
+  (on no-tray systems) a close button.
+- **Tray resident** — sits in the system tray; tray click toggles the overlay.
+
+## Platform comparison
+
+| | Windows | macOS | Linux/X11 |
+|---|---|---|---|
+| Absolute screen coordinates | ✅ native | ✅ native | ✅ (same model) |
+| Overlay readout through the graph | ✅ | ✅ | ✅ |
+| Move / resize the window | ✅ native | ✅ native | ✅ Qt-driven |
+| Calibration survives window move/resize | ✅ | ✅ | ✅ |
+| Global hotkey (Win+Alt+P / Cmd+Alt+P) | ✅ RegisterHotKey | ⏳ | ⏳ deferred (XGrabKey) |
+| System tray | ✅ | ✅ | ⚠️ depends on DE |
+| Build/ship | .exe (PyInstaller) | ⏳ untested | pip / PyPI wheel |
+
+**Wayland is not supported yet.** Wayland forbids absolute screen coordinates by
+design and GNOME refuses the workarounds, so the overlay model cannot work there
+without a window-relative rewrite. Linux requires an **X11** session for now;
+see `LINUX_PLAN.md`.
+
+Notes on the platform table:
+- **macOS is untested.** The architecture is OS-portable (absolute screen
+  coordinates, Qt overlay), and Qt provides a native macOS path, but no macOS
+  build or hotkey code exists in this repo yet. Treat the macOS column as a
+  design feature, not a shipped one.
+- **Global hotkey** — Windows-only today. On Linux the tray (or Ctrl+N/Esc and
+  the title-bar buttons) are the controls; an X11 `XGrabKey` hotkey is a
+  follow-up.
+- **System tray** — always present on Windows; on Linux it depends on the
+  desktop environment. GNOME has no tray by default unless the *AppIndicator
+  and KStatusNotifier* extension is installed. When no tray exists, PlotRuler
+  shows a close button and quits on minimize/close/Esc rather than hiding into
+  an unreachable state.
+
+## Development
+
+```sh
+conda activate plotruler
+python -m plotruler        # run the app
+pytest                     # run tests
+ruff check .               # lint
+ruff format .              # auto-format
+```
+
+## Linux
+
+Linux requires an X11 session (Wayland is deferred — see above). Qt 6.5+
+also needs the `xcb-cursor` system library for the X11 backend, which pip
+cannot install:
+
+```sh
+# Debian / Ubuntu
+sudo apt install libxcb-cursor0
+# Fedora / RHEL
+sudo dnf install xcb-util-cursor
+# Arch
+sudo pacman -S xcb-util-cursor
+```
+
+Install and run (no frozen binary on Linux):
+
+```sh
+pip install plotruler       # or, from source: pip install -e . then plotruler
+plotruler
+```
+
+> PyPI/wheels cannot install system libraries like `libxcb-cursor`; without it
+> the app aborts at first launch. Install it first (commands above). The
+> `build/install_linux.sh` helper also checks for it and fails fast with your
+> distro's package name.
+
+## Releases & publishing
+
+PlotRuler ships through **two channels**:
+
+| Channel | Artifact | Who uses it |
+|---|---|---|
+| **PyPI** (`pip install plotruler`) | wheel (`.whl`) | everyone, all platforms; the Linux and pip path |
+| **GitHub Releases** | `PlotRuler.exe` | Windows users who don't want pip |
+
+Publish a Python release to PyPI:
+
+```sh
+pip install build twine
+./build/publish_pypi.sh --check   # first: upload to TestPyPI and verify
+./build/publish_pypi.sh           # then: upload to PyPI
+```
+
+Requires `TWINE_USERNAME`/`TWINE_PASSWORD` (or a `~/.pypirc`), and an account
+with upload rights for the `plotruler` name. The package supports Python 3.10+
+(down to PySide6 6.11's own floor).
+
+The Windows `.exe` is separate and must be built on Windows.
+
+## Build a stand-alone Windows executable
+
+```sh
+python -m pip install pyinstaller
+python build/build.py
+```
+
+Produces a single-file, windowed `dist/PlotRuler.exe` with a tray icon and
+version metadata. The app bundles Qt, so the exe is ~46 MB but needs no Python
+install to run. This is the artifact you attach to a GitHub release.
+
+See `AGENTS.md` for development conventions.
+
+## License
+
+MIT License (see `LICENSE`).
+
+(This was generated almost entirely by AI under human direction, so likely lacks the human authorship required for copyright in the US and is therefore in the public domain.  MIT license applies anywhere else.)

plotruler-0.1.3/build/build.py

@@ -0,0 +1,46 @@
+"""Build the PlotRuler executable.
+
+Regenerates the multi-size .ico from the tray icon, then runs PyInstaller
+with the project's spec. Run from the repo root:
+
+    python build/build.py
+
+Requires PyInstaller installed in the active environment:
+    python -m pip install pyinstaller
+"""
+
+import os
+import subprocess
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BUILD = os.path.join(ROOT, "build")
+sys.path.insert(0, ROOT)
+
+import make_ico  # noqa: E402  (regenerate the .ico first)
+
+
+def main():
+    # Render the .ico (needs a QApplication) before delegating to PyInstaller.
+    from PySide6.QtWidgets import QApplication
+
+    app = QApplication([])
+    make_ico.build_ico(app, os.path.join(BUILD, "plotruler.ico"))
+    app.quit()
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        "--noconfirm",
+        "--clean",
+        "--distpath",
+        os.path.join(ROOT, "dist"),
+        os.path.join(BUILD, "plotruler.spec"),
+    ]
+    print("running:", " ".join(cmd))
+    subprocess.run(cmd, cwd=ROOT, check=True)
+
+
+if __name__ == "__main__":
+    main()