feat(macos): Apple Silicon support via libmpv render API

[tcconnally]

What

Apple Silicon / Intel macOS support for Hyperwall. Windows path is byte-identical — every change is behind a platform branch.

The constraint that shaped it

mpv's Swift macOS backend does not support --wid window embedding (mpv-examples#29, maintainer-confirmed; IPTVnator hit the same black-video-surface failure). The only supported embed on macOS is the libmpv render API (vo=libmpv + OpenGL FBO) — the IINA/IPTVnator architecture.

Changes

• hyperwall/macembed.py (new) — MpvGLWidget: per-cell QOpenGLWidget + mpv render context (python-mpv MpvRenderContext). render.h rules honored: update callback = bare queued signal emit; all mpv_render_* on the GUI thread with GL current; ctx freed before mpv.terminate(); block_for_target_time=False + video-timing-offset=0 so N cells never serialize-block the GUI thread on the audio clock.
• constants.py — mpv_opts_for_platform(): darwin → vo=libmpv, hwdec=videotoolbox, ao=coreaudio,null, no gpu_api; linux → auto-safe; Windows unchanged. native_wid() confines the 32-bit HWND mask to win32 (it would truncate a 64-bit NSView pointer).
• cell.py — darwin branch: GL surface, MPV without wid, render ctx released pre-terminate.
• app.py — 3.2 core-profile QSurfaceFormat default on darwin; platform-aware libmpv-missing guidance.
• nvidia.py / soak.py — relaunch/G-Sync no-op off Windows; POSIX soak sampler (ru_maxrss is bytes on macOS, KiB on Linux).
• bootstrap.sh / launch.sh (new) — brew install mpv + venv + deps + libmpv binding verification; launcher exports DYLD_FALLBACK_LIBRARY_PATH before exec (setting it from inside Python is a no-op).
• tests/test_platform.py (new) — platform opts matrix + wid-masking guards. python tests/run_all.py → all suites green.
• README macOS quick start; CLAUDE.md gains a Platforms section with the new rules.

Verification status

• Full headless suite green (logic, opts matrix, imports, POSIX paths)
• On-device playback on Apple Silicon — pending. The GL render path can only run on a Mac. First-launch checklist: cells render (not black), hwdec-current: videotoolbox in the S overlay, control pills paint above video. Fallback if black cells + audio: HYPERWALL_HWDEC=videotoolbox-copy ./launch.sh.

Run it

./bootstrap.sh   # needs Homebrew; installs mpv, venv, verifies libmpv
# edit config.ini
./launch.sh

[tcconnally]

First on-device run: root cause found & fixed

Crash signature from the M5 Air: SIGSEGV at 0x48 in mpv_set_option_string, on first MPV() construction (wizard fine → crash at playback start).

Root cause: mpv_create() returns NULL when LC_NUMERIC is not C/C.UTF-8 — mpv player/main.c check_locale(). POSIX CPython calls setlocale(LC_ALL, "") at startup, so a normal en_US.UTF-8 macOS shell makes the first MPV() segfault dereferencing the NULL handle (lock_core(ctx) reads ctx->mpctx at offset 0x48). The Windows CRT keeps LC_NUMERIC=C, which is why this never showed on Windows.

Fix (3bf9aa8):

• app.py forces setlocale(LC_NUMERIC, "C") on POSIX early in main()
• launch.sh exports LC_NUMERIC=C (defense-in-depth)
• bootstrap.sh now runs a headless mpv_create probe (vo=null) — a bare import can't catch NULL-create failures; it will fail at bootstrap, not at first playback
• CLAUDE.md documents the rule + the 0x48 segfault signature

Also confirmed while in there: python-mpv declares mpv_render_context_create with ec_errcheck, so any render-context failure raises a catchable Python exception instead of crashing.

Next verification step on the M5: git pull && ./bootstrap.sh && ./launch.sh — bootstrap's probe should print [OK] mpv player created: ..., then watch cells render + hwdec-current in the S overlay.