MACOS
-----

GETTING IT TO START (do this first): a zip made on Windows cannot carry the
"this file is a program" permission macOS requires, and macOS additionally
quarantines everything downloaded from the internet - so a freshly
extracted build will NOT open by double-clicking. It looks like the app
simply doesn't load; nothing appears at all. From Terminal, in the folder
you extracted, run:

    cd path/path/ProTrackerDatabase-osx-x64/osx-x64

    bash macos-start.sh

(Use "bash macos-start.sh" rather than "./macos-start.sh" the first time -
the script's own execute permission is lost to the same Windows-zip
limitation. It fixes its own permission for next time. Safe to run more
than once - every time you get a new build, this is still the only command
you need.)

That one command restores the executable's permissions, clears the
quarantine flag so Gatekeeper allows the launch, sets up the OCR libraries
via Homebrew if it's installed (encounter detection needs them; the app
runs without them), and starts the app.

Manual fallback, if you'd rather do it by hand - from Terminal, inside the
folder that contains "ProTrackerDatabase.Avalonia":

    chmod +x ProTrackerDatabase.Avalonia
    xattr -dr com.apple.quarantine .
    ./ProTrackerDatabase.Avalonia

If macOS still refuses with an "unidentified developer" / "Apple could not
verify" message, approve it under System Settings > Privacy & Security >
"Open Anyway", then run it again. (This app isn't notarized with Apple -
that's what macOS is objecting to, not anything actually wrong with it.)

Intel vs Apple Silicon: use the build matching the Mac - osx-x64 for Intel
Macs, osx-arm64 for Apple Silicon (M1/M2/M3/M4). An arm64 build cannot run
on an Intel Mac at all. The Intel build does run on Apple Silicon through
Rosetta, if Rosetta is installed ("softwareupdate --install-rosetta").

If the app STILL doesn't start: it may be crashing while starting up
rather than being blocked from launching. In that case it writes a crash
log - send the newest file from
~/Library/Application Support/ProTracker/Logs/ to the developer, plus
whatever the Terminal printed. If no such folder/file exists, the app was
never allowed to run at all - re-check the steps above.

ONCE IT RUNS: no extra packages are needed for window capture - macOS
ships everything this app's capture backend needs out of the box. Instead,
two one-time PERMISSION grants are needed (System Settings > Privacy &
Security):

  - "Automation" - lets the app read the PRO client window's position/size
    by asking System Events for it.
  - "Screen Recording" - lets the app actually capture pixels from that
    window. Without this, captures come back black/blank rather than
    showing a clear error, so if tracking silently isn't picking anything
    up, this is the first thing to check.

The app needs to appear (and be checked) in both lists, not just one.

Known limitation: capture on macOS grabs a region of the screen, not the
window's own buffer directly - if another window overlaps the PRO client
while it's scanning, the capture will show whatever's on top instead. Move
the PRO client window to the front/unobstructed if detection seems to be
missing things intermittently.



REPORTING A PROBLEM (EITHER PLATFORM)
----------------------------------------
Click "Report a Problem" in the app's menu bar (next to Appearance). It
saves a screenshot and a log file to your Downloads folder - send both of
those to the developer along with what you were doing at the time. See
README-Tracking-and-OCR.txt for more on that.

When reporting a Linux/macOS-specific issue, it's especially helpful to
also mention:
  - Linux: your distro, and whether you're on X11 or Wayland (see above).
  - macOS: whether you've granted both permissions above, and whether
    anything else was on top of the PRO window at the time.