CMakeLists.txt

# Copyright (c) 2026 Mark Liversedge (liversedge@gmail.com)
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 2 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc., 51
# Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

cmake_minimum_required(VERSION 3.16)

# ── Version: single source of truth is src/Core/version.h ─────────────────────
# Derive the CMake/CPack/Inno project version from version.h so the installer
# version and the in-app updaters never drift from the compiled version (Windows
# design §7). MAJOR.MINOR come from the macros; PATCH is the monotonic build number
# (PINPOINT_VERSION_BUILD) so the Inno AppVersion strictly increases every release
# and WinSparkle's compare key matches. Bump version.h only.
file(READ "${CMAKE_CURRENT_SOURCE_DIR}/src/Core/version.h" _pp_version_h)
string(REGEX MATCH "#define[ \t]+PINPOINT_VERSION_MAJOR[ \t]+([0-9]+)" _ "${_pp_version_h}")
set(_pp_ver_major "${CMAKE_MATCH_1}")
string(REGEX MATCH "#define[ \t]+PINPOINT_VERSION_MINOR[ \t]+([0-9]+)" _ "${_pp_version_h}")
set(_pp_ver_minor "${CMAKE_MATCH_1}")
string(REGEX MATCH "#define[ \t]+PINPOINT_VERSION_BUILD[ \t]+([0-9]+)" _ "${_pp_version_h}")
set(_pp_ver_build "${CMAKE_MATCH_1}")
# POSTFIX is the prerelease suffix ("-alpha3", "" for a clean release). Used for the
# human display version (macOS CFBundleShortVersionString / Sparkle shortVersionString).
string(REGEX MATCH "#define[ \t]+PINPOINT_VERSION_POSTFIX[ \t]+\"([^\"]*)\"" _ "${_pp_version_h}")
set(_pp_ver_postfix "${CMAKE_MATCH_1}")
# Compare against "" (not NOT), since a valid MAJOR of 0 is falsey to CMake's if().
if("${_pp_ver_major}" STREQUAL "" OR "${_pp_ver_minor}" STREQUAL "" OR "${_pp_ver_build}" STREQUAL "")
    message(FATAL_ERROR "Could not parse version from src/Core/version.h")
endif()

project(PinPointStudio
    VERSION ${_pp_ver_major}.${_pp_ver_minor}.${_pp_ver_build}
    LANGUAGES CXX)

# Standard install dirs (bin/, lib/, share/). Without this CMAKE_INSTALL_BINDIR is
# empty and install(TARGETS ... RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}) would
# place the executable at the install-prefix root while the DLLs (DESTINATION bin)
# land in bin/ — splitting the runtime tree. Including this pins BINDIR=bin.
include(GNUInstallDirs)

# ── Packaged-build marker ─────────────────────────────────────────────────────
# OFF for plain dev builds (QtCreator, run-from-build/); the packaging scripts
# configure with -DPINPOINT_INSTALLED=ON so the produced bundle/installer is
# marked as a real distributable. The in-app update engines key off this (plus a
# runtime check) to stay inert in a dev tree — the cross-platform analogue of the
# Linux "$APPIMAGE unset" guard. macOS design §3; Windows uses its installer's
# unins000.exe probe today, this is the portable knob.
option(PINPOINT_INSTALLED "Mark this as a packaged/installed build" OFF)

# ── Shipping-build assertion ─────────────────────────────────────────────────
# Separate from PINPOINT_INSTALLED on purpose. That one is a RUNTIME marker —
# it compiles a define in and the update engines key off it — and only the macOS
# script sets it, because flipping it on Linux/Windows would change how those
# builds decide whether they may update themselves. This one has no runtime
# effect whatsoever: it exists so a configure can be told "the output of this
# build is going to be handed to someone", and be checked.
#
# What it guards is a dependency we do not compile ourselves. libwrist is
# embedded (§ the block before qt_add_executable), so it is built with THIS
# project's CMAKE_BUILD_TYPE — there is no separate library build to get right,
# and its own `release` preset cannot apply to an add_subdirectory. Release is
# therefore what strips it, and the two ways that silently stops being true are
# a packaging path edited to RelWithDebInfo (-> 15 DWARF compile units and a
# 348 KB archive instead of 112 KB) and a configure with no build type at all,
# which is worse: no -O, no NDEBUG, and nothing warns. Both now fail loudly.
option(PP_SHIPPING_BUILD "This configure produces a distributable artefact — assert it is Release" OFF)

# The escape hatch for the PPCP assertion at the bottom of this file. A shipping
# build with no capture-device link is a decision someone has to make ON PURPOSE
# and write in the release notes, not something a missing -D does to them quietly.
# Declared here rather than beside the assertion so `cmake -LAH` answers "could a
# shipped PinPointStudio have no PPCP?" from the same place as the plaintext question.
option(PP_ALLOW_NO_PPCP
       "Permit a shipping build with NO PPCP transport (no phone pairing). Deliberate only."
       OFF)

# ══════════════════════════════════════════════════════════════════════════
# ⚠⚠⚠  PLAINTEXT PPCP.  OFF, AND A SHIPPING BUILD REFUSES TO TURN IT ON.  ⚠⚠⚠
#
# `PPCP-CONF` §2c drives the peer under test from outside, with `ppcp-sim` as
# the counterpart — and `ppcp-sim` has no TLS transport, so the conformance
# harness of work package H8 reaches this host over a PLAINTEXT loopback socket.
# `PPCP-RV` erratum E4 (RV 2c1) permits exactly that for a test harness, and
# `PPCP-CORE` §3.2's `direct` transport is conformant plaintext.
#
# It is declared HERE, in the application's configure, so that the answer to
# "could a shipped PinPointStudio listen without TLS?" is visible in this file
# and in `cmake -LAH`, rather than buried in a test directory.  The only thing
# that sets it ON is `src/Ppcp/tests/CMakeLists.txt`.  With it OFF, every
# plaintext branch in `src/Ppcp/ppcp_transport.cpp` is `#if`-ed out of
# existence: there is no code path to reach, which is the same way RV 5.2f's
# "never fall back to an unencrypted connection" is kept.
option(PP_PPCP_PLAINTEXT_HARNESS
       "Compile the PLAINTEXT conformance-harness listener (CONF 2c). NEVER in a release build."
       OFF)
if(PP_PPCP_PLAINTEXT_HARNESS AND PP_SHIPPING_BUILD)
    message(FATAL_ERROR
        "PP_PPCP_PLAINTEXT_HARNESS is ON in a shipping build. That would ship a listener "
        "that accepts unauthenticated, unencrypted PPCP connections. Refusing to configure.")
endif()
if(PP_PPCP_PLAINTEXT_HARNESS)
    add_compile_definitions(PP_PPCP_PLAINTEXT_HARNESS)
endif()

# ── RV-6's harness tap (H10) — the SAME shape and the SAME refusal ──────────
#
# `PPCP-RV` §11 is authenticated by a person comparing six digits on two
# screens.  RT-20c drives BOTH applications either side of the relay and has to
# be able to press the confirm button without a person in the room, so this
# compiles an entry that supplies THE TAP.
#
# ⛔⛔ IT SUPPLIES THE TAP AND NEVER THE COMPARISON, AND THE DIFFERENCE IS THE
# WHOLE SECURITY OF THE PATH (11.1d, trap 8).  Nothing behind this flag reads
# the six digits, receives the counterpart's, or decides whether they match; it
# operates the control a person would operate, and the decision it carries is a
# constant the harness was told to send.  A build that compared them in software
# would pass every static test in the document and authenticate nothing.
#
# ⛔ AND IT MUST NEVER SHIP.  A shipping build refuses to configure with it ON,
# exactly as the plaintext harness above does, and for a sharper reason: this
# one presses "yes, they match" on the user's behalf.
option(PP_PPCP_RV6_HARNESS
       "Compile the RV-6 guided-pairing harness tap (RT-20c). NEVER in a release build."
       OFF)
if(PP_PPCP_RV6_HARNESS AND PP_SHIPPING_BUILD)
    message(FATAL_ERROR
        "PP_PPCP_RV6_HARNESS is ON in a shipping build. That would ship an entry that "
        "affirms a guided pairing without a person having compared anything — RV 11.1d "
        "and 11.7c. Refusing to configure.")
endif()
if(PP_PPCP_RV6_HARNESS)
    add_compile_definitions(PP_PPCP_RV6_HARNESS)
endif()

if(NOT CMAKE_CONFIGURATION_TYPES AND NOT CMAKE_BUILD_TYPE)
    message(FATAL_ERROR
        "No CMAKE_BUILD_TYPE set.\n"
        "A single-config generator with an empty build type compiles everything — this "
        "project AND the embedded libwrist — with no optimisation and no NDEBUG, "
        "and nothing downstream reports it. Pass one explicitly:\n"
        "  -DCMAKE_BUILD_TYPE=Debug     for development\n"
        "  -DCMAKE_BUILD_TYPE=Release   for anything you intend to ship")
endif()

# The option must reach the SOURCES, not just this file: AppInfo::devBuild gates the
# dev-only QML probe hook on it, and an option that is only a configure-time assertion
# leaves every #ifdef PP_SHIPPING_BUILD in the tree silently dead-false.
if(PP_SHIPPING_BUILD)
    add_compile_definitions(PP_SHIPPING_BUILD)
endif()

if(PP_SHIPPING_BUILD AND NOT CMAKE_BUILD_TYPE STREQUAL "Release")
    message(FATAL_ERROR
        "PP_SHIPPING_BUILD=ON but CMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}, not Release.\n"
        "This build is packaged and handed to someone, so it must be Release: that is "
        "what builds the embedded libwrist the way its `release` preset does "
        "(-O3 -DNDEBUG, no -g). RelWithDebInfo ships the library's full DWARF and the "
        "source layout of this machine, and does so silently.\n"
        "To debug an optimised libwrist, build the LIBRARY on its own with its "
        "`rel` preset — do not change the build type of a shipping configure.")
endif()

# ── Windows runtime bundling helper ───────────────────────────────────────────
# Copy a list of DLLs/files next to the dev executable (POST_BUILD) AND register
# them for install/packaging under bin/, tagged with a CPack component. Windows
# only; assumes a flat layout next to the executable. The function body is
# evaluated lazily at call time, so it may be defined before the target exists.
function(pp_win_bundle_dll _component)
    if(NOT WIN32 OR NOT ARGN)
        return()
    endif()
    foreach(_f ${ARGN})
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_f}" "$<TARGET_FILE_DIR:PinPointStudio>"
            VERBATIM)
    endforeach()
    install(FILES ${ARGN} DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT ${_component})
endfunction()

# Build provenance recorded into saved shots (swing.json "capture.host"). The
# short git sha is captured at configure time — good enough for corpus
# provenance; reconfigure refreshes it.
execute_process(
    COMMAND git rev-parse --short HEAD
    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
    OUTPUT_VARIABLE PP_GIT_SHA
    OUTPUT_STRIP_TRAILING_WHITESPACE
    ERROR_QUIET
)
if(NOT PP_GIT_SHA)
    set(PP_GIT_SHA "unknown")
endif()
configure_file(cmake/pp_version.h.in "${CMAKE_BINARY_DIR}/generated/pp_version.h" @ONLY)

# Qt prefix. Shared with tests/cmake/PinPointTests.cmake so configuring the app
# and configuring a test suite land on the same Qt. Must precede find_package(Qt6):
# without it this project names no prefix at all, and CMake's ordinary search finds
# whatever Qt is on the box — on macOS the Homebrew one, which has no Quick3D, and
# the failure below then reads as a missing module rather than the wrong Qt.
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/PinPointQtPrefix.cmake)

# Qt GuiPrivate is used for QRhi (public API since Qt 6.6, accessed via GuiPrivate includes).
set(QT_NO_PRIVATE_MODULE_WARNING ON)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Quick QuickControls2 Quick3D SerialPort Bluetooth Multimedia Network WebSockets Concurrent ShaderTools GuiPrivate CorePrivate)

qt_standard_project_setup(REQUIRES 6.10)

include(FetchContent)

FetchContent_Declare(
  whisper
  GIT_REPOSITORY https://github.com/ggerganov/whisper.cpp.git
  GIT_TAG        v1.7.2
  GIT_SHALLOW    TRUE
)

set(WHISPER_BUILD_TESTS    OFF CACHE BOOL "" FORCE)
set(WHISPER_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(BUILD_SHARED_LIBS      OFF CACHE BOOL "" FORCE)

# ── GPU acceleration for whisper.cpp (Linux / Windows) ─────────────────────
# Vulkan works on NVIDIA, AMD, and Intel without proprietary drivers.
# CUDA is tried as a fallback when Vulkan headers are not present.
if(NOT APPLE)
    find_package(Vulkan QUIET)
    if(Vulkan_FOUND)
        set(GGML_VULKAN ON CACHE BOOL "" FORCE)
        set(_whisper_gpu_backend "Vulkan")
        message(STATUS "Whisper: Vulkan GPU acceleration enabled")
    else()
        # check_language(CUDA) is verbose even on failure; guard with a silent
        # find_program first so machines without nvcc don't get noisy output.
        find_program(_nvcc_path nvcc QUIET)
        if(_nvcc_path)
            include(CheckLanguage)
            check_language(CUDA)
        endif()
        if(CMAKE_CUDA_COMPILER)
            enable_language(CUDA)
            set(GGML_CUDA ON CACHE BOOL "" FORCE)
            # Target only the GPU(s) present; avoids compiling for old architectures
            # (e.g. compute_52) that CUDA 12.x dropped support for.
            set(CMAKE_CUDA_ARCHITECTURES native CACHE STRING "" FORCE)
            if(MSVC)
                # CUDA 13+ CCCL headers require the MSVC standard-conforming
                # preprocessor; the traditional one triggers a hard #error.
                string(APPEND CMAKE_CUDA_FLAGS " -Xcompiler /Zc:preprocessor")
            endif()
            # CUDA 13+ CUB/CCCL headers require C++17.
            set(CMAKE_CUDA_STANDARD 17 CACHE STRING "" FORCE)
            set(CMAKE_CUDA_STANDARD_REQUIRED ON CACHE BOOL "" FORCE)
            set(_whisper_gpu_backend "CUDA")
            message(STATUS "Whisper: CUDA GPU acceleration enabled")
        else()
            message(STATUS "Whisper: CPU only (install Vulkan SDK or CUDA Toolkit for GPU acceleration)")
        endif()
    endif()
endif()

FetchContent_MakeAvailable(whisper)

FetchContent_Declare(
  libsamplerate
  GIT_REPOSITORY https://github.com/libsndfile/libsamplerate.git
  GIT_TAG        0.2.2
  GIT_SHALLOW    TRUE
  PATCH_COMMAND
    ${CMAKE_COMMAND}
    "-DFILE=${CMAKE_BINARY_DIR}/_deps/libsamplerate-src/CMakeLists.txt"
    -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/PatchLibsamplerate.cmake"
)
set(LIBSAMPLERATE_EXAMPLES OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING          OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(libsamplerate)

# Eigen 3 (header-only) — required by the vendored ESKF orientation filter
# (third_party/imu_ekf). We only need the headers; EXCLUDE_FROM_ALL plus the
# disabled build options below keep Eigen's own tests/BLAS/doc targets out of
# the build. Fallback for offline builds: vendor the Eigen/ header tree under
# third_party/eigen/ and point the include path there instead.
set(EIGEN_BUILD_DOC       OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_TESTING   OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_PKGCONFIG OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING         OFF CACHE BOOL "" FORCE)
# ⚠ AND THE SPARSE BENCHMARKS, WHICH NO EIGEN OPTION TURNS OFF. Eigen's own CMakeLists adds
# bench/spbench under a bare `if(NOT WIN32)` (eigen CMakeLists.txt:548), and that directory
# creates spbenchsolver / spsolver / test_sparseLU unconditionally — EXCLUDE_FROM_ALL, so
# they never build, but they are configured targets all the same. They then hunt for
# CHOLMOD/UMFPACK/KLU/SuperLU and link whatever they find, which on a Homebrew machine is
# /opt/homebrew/lib — the same directory that carries Homebrew's Qt and breaks the app's
# plugin resolution under Qt Creator (see the long note at the OpenCV block). Refusing the
# find_packages leaves the three targets present but linking nothing out of there.
#
# They still appear in Qt Creator's run-configuration list. That is Eigen's doing, there is
# no switch for it, and patching a fetched dependency to tidy a menu is the worse trade.
foreach(_pp_no_find CHOLMOD UMFPACK KLU SuperLU PASTIX METIS)
    set(CMAKE_DISABLE_FIND_PACKAGE_${_pp_no_find} ON)
endforeach()
FetchContent_Declare(
  eigen
  GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
  GIT_TAG        3.4.0
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(eigen)

# ── libwrist — C11 sans-I/O driver for the HackMotion wG3 wrist sensor ───
# github.com/PinPoint-Golf/libwrist, MIT. A sister project:
# it owns no radio, thread, timer or clock — PinPoint supplies the BLE transport
# (BleImuTransport) and the host clock, and drains the library. See
# docs/implementation/hackmotion_integration_brief.md for what consumes it.
#
# Static, like whisper/samplerate/espeak-ng, courtesy of the global
# BUILD_SHARED_LIBS OFF above — so nothing has to be bundled by any of the three
# packaging paths. Placed here (before qt_add_executable) so wrist_SOURCE_DIR
# is resolved for the provenance block and the offline-target function below.
#
# ⚠ BUILD TYPE: the library's own CMakePresets.json — including its `release`
# preset — is INERT here. Presets apply to a top-level configure only, and this
# is an add_subdirectory, so the library compiles at whatever CMAKE_BUILD_TYPE
# this project was configured with. Release therefore already yields exactly what
# that preset yields: measured on this source, -O3 -DNDEBUG and no -g, 112 KB
# with zero DWARF compile units. Every path that produces a distributable passes
# -DCMAKE_BUILD_TYPE=Release — tools/package_macos.sh, tools/package_appimage.sh
# and packaging/build_installer.ps1, plus the direct configure in the Windows leg
# of .github/workflows/release.yml (its macOS and Linux legs run those scripts) —
# and PP_SHIPPING_BUILD now makes each of them assert it, so shipping the debug
# info takes a deliberate change. Do NOT switch a release
# path to RelWithDebInfo to get a symbolised stack: it lifts the archive to 348 KB
# / 15 compile units and the failure is silent. Build the LIBRARY standalone with
# its `rel` preset instead — that is the question that preset exists to answer.
#
# ⚠ SOURCE RESOLUTION: a sibling ../libwrist checkout WINS over GitHub.
# The library is under active co-development and its fixes are made and pushed
# from that clone, so the build follows it directly — CMake performs no download
# and no checkout when FETCHCONTENT_SOURCE_DIR_WRIST is set, which is the
# mechanism its own documentation points developers at. NEVER edit the fetched
# copy under build/*/_deps/wrist-src: it is a shallow clone, the update step
# overwrites local changes on reconfigure, and `rm -rf build` destroys them.
option(PP_LIBWRIST_LOCAL "Prefer a sibling ../libwrist checkout over GitHub" ON)

set(_wrist_local "${CMAKE_CURRENT_SOURCE_DIR}/../libwrist")
if(PP_LIBWRIST_LOCAL AND EXISTS "${_wrist_local}/CMakeLists.txt")
    get_filename_component(_wrist_local "${_wrist_local}" ABSOLUTE)
    set(FETCHCONTENT_SOURCE_DIR_WRIST "${_wrist_local}" CACHE PATH
        "Local libwrist checkout to build against instead of fetching" FORCE)
    set(_wrist_origin "local ${_wrist_local}")
else()
    # Clear the cache entry rather than merely not setting it. It was written
    # FORCE above, so a build dir that once resolved the sibling checkout still
    # carries the path — and FetchContent would keep honouring it, making
    # -DPP_LIBWRIST_LOCAL=OFF a silent no-op on an existing build dir. That
    # switch exists to check a local fix against upstream main, so it has to
    # actually reach upstream main.
    unset(FETCHCONTENT_SOURCE_DIR_WRIST CACHE)
    unset(_wrist_local)
    set(_wrist_origin "github main")
endif()

# Nothing to switch off: the library's tests, tools, FFI object, -Werror and
# install rules all default to its own top-level check, so embedding it yields
# the library and nothing else. Asking for the record module is the one positive
# statement we make — the offline targets below link it, so say so rather than
# inherit it.
set(WR_BUILD_RECORD ON CACHE BOOL "" FORCE)

FetchContent_Declare(
  wrist
  # ⚠ Deliberately tracking a BRANCH, not a tag: bugs are expected while the
  # integration lands, and FETCHCONTENT_UPDATES_DISCONNECTED is OFF by default so
  # every reconfigure picks up the latest main. Revert to a tag pin (GIT_TAG
  # v0.x.0) once the library stabilises — and note GIT_SHALLOW works with
  # branches and tags but NOT with a raw commit hash, so it must go if a SHA is
  # ever pinned. Ignored entirely when a sibling checkout was found above.
  GIT_REPOSITORY https://github.com/PinPoint-Golf/libwrist.git
  GIT_TAG        main
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)

FetchContent_MakeAvailable(wrist)

# Provenance. With a branch tracked upstream and a local checkout able to win,
# "which libwrist built this?" is a question the About box has to answer —
# it is how a capture gets traced back to a library build while chasing a bug.
file(STRINGS "${wrist_SOURCE_DIR}/include/wrist/version.h" _wrist_ver_line
     REGEX "^#define[ \t]+WR_VERSION_STRING")
string(REGEX REPLACE ".*\"([^\"]+)\".*" "\\1" PP_LIBWRIST_VERSION "${_wrist_ver_line}")
execute_process(
    COMMAND git rev-parse --short HEAD
    WORKING_DIRECTORY "${wrist_SOURCE_DIR}"
    OUTPUT_VARIABLE _wrist_sha OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
execute_process(
    COMMAND git status --porcelain
    WORKING_DIRECTORY "${wrist_SOURCE_DIR}"
    OUTPUT_VARIABLE _wrist_dirty OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
if(_wrist_sha)
    if(_wrist_dirty)
        string(APPEND _wrist_sha "-dirty")
    endif()
    if(_wrist_local)
        string(APPEND PP_LIBWRIST_VERSION " (${_wrist_sha}, local)")
    else()
        string(APPEND PP_LIBWRIST_VERSION " (${_wrist_sha})")
    endif()
endif()
message(STATUS "libwrist: ${PP_LIBWRIST_VERSION} — ${_wrist_origin}")
unset(_wrist_ver_line)
unset(_wrist_sha)
unset(_wrist_dirty)
unset(_wrist_local)

# ── libppcp — C11 sans-I/O implementation of the PinPoint Capture Protocol ───
# github.com/PinPoint-Golf/libppcp, MIT. Work package H0 of
# libppcp/docs/implementation/implementation-plan.md, and decision A4 there:
# PinPointStudio embeds libppcp EXACTLY as it embeds libwrist, so the block
# above is the pattern and this one deliberately does not invent a second.
#
# The same sister-project shape: it owns no socket, thread, timer, clock or file
# (plan ground rule 7). PinPointStudio supplies the transport — src/Ppcp, the
# block near the end of this file — the host clock and the storage, and drains
# the library. That split is what lets one MIT implementation serve both ends of
# the protocol without dragging a transport dependency into it (CORE A.3).
#
# ⚠ SOURCE RESOLUTION: a sibling ../libppcp checkout WINS over GitHub, for the
# same reason libwrist's does — the library is under active co-development and
# its fixes are made in that clone. NEVER edit the fetched copy under
# build/*/_deps/ppcp-src: the update step overwrites it on reconfigure.
#
# ⚠ PP_LIBPPCP_FETCH DEFAULTS OFF, AND THAT IS TEMPORARY. A4 says FetchContent
# from GitHub with the sibling overriding it, and that is what this block does —
# but the repository is not published yet, and a failed clone is a failed
# configure for everyone including people who do not care about PPCP. Flip this
# default to ON the day PinPoint-Golf/libppcp is pushed; nothing else changes.
option(PP_LIBPPCP_LOCAL "Prefer a sibling ../libppcp checkout over GitHub" ON)
option(PP_LIBPPCP_FETCH "Fetch libppcp from GitHub when no sibling checkout exists" OFF)

set(_ppcp_local "${CMAKE_CURRENT_SOURCE_DIR}/../libppcp")
set(_ppcp_origin "")
if(PP_LIBPPCP_LOCAL AND EXISTS "${_ppcp_local}/CMakeLists.txt")
    get_filename_component(_ppcp_local "${_ppcp_local}" ABSOLUTE)
    set(FETCHCONTENT_SOURCE_DIR_PPCP "${_ppcp_local}" CACHE PATH
        "Local libppcp checkout to build against instead of fetching" FORCE)
    set(_ppcp_origin "local ${_ppcp_local}")
elseif(PP_LIBPPCP_FETCH)
    # Written FORCE above, so clear it rather than merely not setting it — else
    # a build dir that once resolved the sibling keeps honouring the stale path
    # and -DPP_LIBPPCP_LOCAL=OFF becomes a silent no-op. Same trap as libwrist.
    unset(FETCHCONTENT_SOURCE_DIR_PPCP CACHE)
    unset(_ppcp_local)
    set(_ppcp_origin "github main")
else()
    unset(FETCHCONTENT_SOURCE_DIR_PPCP CACHE)
    unset(_ppcp_local)
endif()

if(_ppcp_origin)
    # Defensive, and no-ops if the library names its options differently: it is
    # expected to gate its own tests, tools and install rules on its top-level
    # check the way libwrist does, so embedding yields the library and nothing else.
    set(PPCP_BUILD_TESTS OFF CACHE BOOL "" FORCE)
    set(PPCP_BUILD_TOOLS OFF CACHE BOOL "" FORCE)

    FetchContent_Declare(
      ppcp
      # ⚠ Tracking a BRANCH, not a tag, while the protocol lands — the same
      # deliberate choice as libwrist above, and to be pinned once ppcp/1.0
      # freezes. GIT_SHALLOW works with branches and tags but NOT a raw SHA.
      GIT_REPOSITORY https://github.com/PinPoint-Golf/libppcp.git
      GIT_TAG        main
      GIT_SHALLOW    TRUE
      EXCLUDE_FROM_ALL
    )
    FetchContent_MakeAvailable(ppcp)

    # Provenance, for the same reason libwrist has it: a branch upstream and a
    # local checkout able to win means "which libppcp built this?" is a question
    # the About box has to answer, and a conformance claim is worthless without
    # the commit it was measured against.
    file(STRINGS "${ppcp_SOURCE_DIR}/include/ppcp/version.h" _ppcp_ver_line
         REGEX "^#define[ \t]+PPCP_LIB_VERSION_STRING")
    string(REGEX REPLACE ".*\"([^\"]+)\".*" "\\1" PP_LIBPPCP_VERSION "${_ppcp_ver_line}")
    execute_process(
        COMMAND git rev-parse --short HEAD
        WORKING_DIRECTORY "${ppcp_SOURCE_DIR}"
        OUTPUT_VARIABLE _ppcp_sha OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
    execute_process(
        COMMAND git status --porcelain
        WORKING_DIRECTORY "${ppcp_SOURCE_DIR}"
        OUTPUT_VARIABLE _ppcp_dirty OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
    if(_ppcp_sha)
        if(_ppcp_dirty)
            string(APPEND _ppcp_sha "-dirty")
        endif()
        if(_ppcp_local)
            string(APPEND PP_LIBPPCP_VERSION " (${_ppcp_sha}, local)")
        else()
            string(APPEND PP_LIBPPCP_VERSION " (${_ppcp_sha})")
        endif()
    endif()
    message(STATUS "libppcp: ${PP_LIBPPCP_VERSION} — ${_ppcp_origin}")
else()
    message(STATUS "libppcp: not embedded (no sibling ../libppcp and PP_LIBPPCP_FETCH is OFF)")
endif()
unset(_ppcp_ver_line)
unset(_ppcp_sha)
unset(_ppcp_dirty)
unset(_ppcp_local)
unset(_ppcp_origin)
unset(_wrist_origin)

# ── libgspro — C11 sans-I/O server for the GSPro Open Connect v1 protocol ────
# github.com/PinPoint-Golf/libgspro, MIT. The third sister project, embedded
# exactly as libwrist and libppcp are — the two blocks above are the pattern and
# this one deliberately does not invent a third.
#
# What it is FOR. Many launch monitors are reachable through a GSPro Open Connect
# client somebody else has already written — the library's survey found seventeen,
# five of them for the Garmin R10 alone, plus the Rapsodo MLM2PRO, a SkyTrak+ via
# OpenSkyPlus, a Foresight GC2's serial feed, an SLX proxy, and PiTrac and
# OpenFlight which are native clients. Speaking the SERVER side of that one
# protocol reaches all of them with no per-device work, which is why it is worth a
# dependency rather than a parser per device. It is the second Kind of launch
# monitor connector beside GcQuad — see the library's docs/design.md §6, which is
# written against THIS repository's LaunchMonitorBase / LaunchMonitorReading /
# ShotPairing.
#
# ⚠ IT DOES NOT REPLACE THE GCQUAD CONNECTOR. Uneekor, Bushnell and Foresight ship
# no Open Connect client at all — their connectors are closed and speak their own
# vendors' simulators — so a GCQuad is still reached by watching FSX2020's
# LastShot.CSV, and a Uneekor only by a third-party folder-watching bridge.
#
# ⚠ THE SAME SANS-I/O SPLIT, AND HERE IT IS THE POINT OF THE LIBRARY. It owns no
# socket, thread, timer, clock or file: PinPoint supplies the QTcpServer, the
# host clock and the storage, and drains the library. So the reference transport
# (GS_BUILD_NET) and the .gswire recorder (GS_BUILD_RECORD) are NOT asked for
# here — a Qt host has its own event loop and its own storage, and linking a
# select() loop into an application that already has one is the mistake the
# split exists to make impossible. Both default OFF when embedded; this comment
# is why they are not turned on rather than an oversight.
#
# ⚠ SOURCE RESOLUTION: a sibling ../libgspro checkout WINS over GitHub, for the
# same reason libwrist's and libppcp's do — the library is under active
# co-development and its fixes are made and pushed from that clone. NEVER edit
# the fetched copy under build/*/_deps/gspro-src: it is a shallow clone whose
# update step overwrites local changes on reconfigure.
#
# ⚠ Unlike libppcp there is no PP_LIBGSPRO_FETCH switch: the repository IS
# published, so a machine with no sibling checkout fetches it and the build works
# for someone who has never heard of the library. That is the libwrist shape.
option(PP_LIBGSPRO_LOCAL "Prefer a sibling ../libgspro checkout over GitHub" ON)

set(_gspro_local "${CMAKE_CURRENT_SOURCE_DIR}/../libgspro")
if(PP_LIBGSPRO_LOCAL AND EXISTS "${_gspro_local}/CMakeLists.txt")
    get_filename_component(_gspro_local "${_gspro_local}" ABSOLUTE)
    set(FETCHCONTENT_SOURCE_DIR_GSPRO "${_gspro_local}" CACHE PATH
        "Local libgspro checkout to build against instead of fetching" FORCE)
    set(_gspro_origin "local ${_gspro_local}")
else()
    # Cleared rather than merely not set: the branch above writes FORCE, so a
    # build dir that once resolved the sibling still carries the path and
    # -DPP_LIBGSPRO_LOCAL=OFF would be a silent no-op. Same trap as the two above.
    unset(FETCHCONTENT_SOURCE_DIR_GSPRO CACHE)
    unset(_gspro_local)
    set(_gspro_origin "github main")
endif()

FetchContent_Declare(
  gspro
  # ⚠ Tracking a BRANCH while the integration lands, as libwrist does; to be
  # pinned to a tag once the library stabilises. GIT_SHALLOW works with branches
  # and tags but NOT a raw SHA. Ignored entirely when the sibling was found.
  GIT_REPOSITORY https://github.com/PinPoint-Golf/libgspro.git
  GIT_TAG        main
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(gspro)

# Provenance, for the reason the other two have it: a branch upstream and a local
# checkout able to win means "which libgspro built this?" is a question the About
# box has to answer — and a launch monitor session traced back to a library build
# is the difference between a bug report and a guess.
file(STRINGS "${gspro_SOURCE_DIR}/include/gspro/version.h" _gspro_ver_line
     REGEX "^#define[ \t]+GSP_VERSION_STRING")
string(REGEX REPLACE ".*\"([^\"]+)\".*" "\\1" PP_LIBGSPRO_VERSION "${_gspro_ver_line}")
execute_process(
    COMMAND git rev-parse --short HEAD
    WORKING_DIRECTORY "${gspro_SOURCE_DIR}"
    OUTPUT_VARIABLE _gspro_sha OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
execute_process(
    COMMAND git status --porcelain
    WORKING_DIRECTORY "${gspro_SOURCE_DIR}"
    OUTPUT_VARIABLE _gspro_dirty OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
if(_gspro_sha)
    if(_gspro_dirty)
        string(APPEND _gspro_sha "-dirty")
    endif()
    if(_gspro_local)
        string(APPEND PP_LIBGSPRO_VERSION " (${_gspro_sha}, local)")
    else()
        string(APPEND PP_LIBGSPRO_VERSION " (${_gspro_sha})")
    endif()
endif()
message(STATUS "libgspro: ${PP_LIBGSPRO_VERSION} — ${_gspro_origin}")
unset(_gspro_ver_line)
unset(_gspro_sha)
unset(_gspro_dirty)
unset(_gspro_local)
unset(_gspro_origin)

# ── libppswing — the PinPoint swing file format (.ppsw) ──────────────────────
# github.com/PinPoint-Golf/libppswing, MIT. The fourth sister project, embedded
# the way libgspro is (the block above is the pattern). It reads and writes the
# per-swing document: swing.ppsw replaced swing.json as the written format in
# Phase 2 of docs/implementation/swing_storage_impl.md, and swing.json is still
# read, indefinitely. C++17, one vendored dependency (zstd), links nothing else.
#
# ⚠ THE APP NEVER INCLUDES A ppsw HEADER OUTSIDE src/Export/swing_store.cpp and
# ppsw_qt.cpp. Those two files are the pinpoint_swingstore library
# (cmake/PinPointSwingStore.cmake), and every target that touches a swing
# document links that one name. That is what keeps dozens of test link lines
# from each having to learn about this library.
#
# ⚠ SOURCE RESOLUTION: a sibling ../libppswing checkout WINS over GitHub, as for
# the other three. NEVER edit the fetched copy under build/*/_deps/ppswing-src.
# The repository is public, so there is no FETCH switch: a machine with no
# sibling fetches it, and the build works for someone who has never heard of it.
option(PP_LIBPPSWING_LOCAL "Prefer a sibling ../libppswing checkout over GitHub" ON)

set(_ppsw_local "${CMAKE_CURRENT_SOURCE_DIR}/../libppswing")
if(PP_LIBPPSWING_LOCAL AND EXISTS "${_ppsw_local}/CMakeLists.txt")
    get_filename_component(_ppsw_local "${_ppsw_local}" ABSOLUTE)
    set(FETCHCONTENT_SOURCE_DIR_PPSWING "${_ppsw_local}" CACHE PATH
        "Local libppswing checkout to build against instead of fetching" FORCE)
    set(_ppsw_origin "local ${_ppsw_local}")
else()
    # Cleared, not merely unset: same stale-cache trap as the three above.
    unset(FETCHCONTENT_SOURCE_DIR_PPSWING CACHE)
    unset(_ppsw_local)
    set(_ppsw_origin "github main")
endif()

# Embedded, the library already defaults its tests, tools, -Werror and install
# rules OFF (its top-level check); set them anyway so an embed never inherits a
# gate that is the library's own.
set(PPSW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(PPSW_BUILD_TOOLS OFF CACHE BOOL "" FORCE)

FetchContent_Declare(
  ppswing
  # ⚠ Tracking a BRANCH while the format is at 1.0 draft, as libgspro does; to
  # be pinned to a tag once the spec is final.
  GIT_REPOSITORY https://github.com/PinPoint-Golf/libppswing.git
  GIT_TAG        main
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(ppswing)

# Provenance, for the About box: the library has no version header, so the
# version is its project() line, plus the commit, as for the others.
file(STRINGS "${ppswing_SOURCE_DIR}/CMakeLists.txt" _ppsw_ver_line REGEX "^[ \t]*VERSION[ \t]+[0-9]")
string(REGEX REPLACE ".*VERSION[ \t]+([0-9.]+).*" "\\1" PP_LIBPPSWING_VERSION "${_ppsw_ver_line}")
execute_process(
    COMMAND git rev-parse --short HEAD
    WORKING_DIRECTORY "${ppswing_SOURCE_DIR}"
    OUTPUT_VARIABLE _ppsw_sha OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
execute_process(
    COMMAND git status --porcelain
    WORKING_DIRECTORY "${ppswing_SOURCE_DIR}"
    OUTPUT_VARIABLE _ppsw_dirty OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
if(_ppsw_sha)
    if(_ppsw_dirty)
        string(APPEND _ppsw_sha "-dirty")
    endif()
    if(_ppsw_local)
        string(APPEND PP_LIBPPSWING_VERSION " (${_ppsw_sha}, local)")
    else()
        string(APPEND PP_LIBPPSWING_VERSION " (${_ppsw_sha})")
    endif()
endif()
message(STATUS "libppswing: ${PP_LIBPPSWING_VERSION} — ${_ppsw_origin}")
unset(_ppsw_ver_line)
unset(_ppsw_sha)
unset(_ppsw_dirty)
unset(_ppsw_local)
unset(_ppsw_origin)

include(cmake/PinPointSwingStore.cmake)
pp_define_swingstore(${CMAKE_CURRENT_SOURCE_DIR})

# EventBuffer library — lock-free ring-buffer capture store
add_subdirectory(src/Buffer)

qt_add_executable(PinPointStudio
    src/Gui/main.cpp
    $<$<BOOL:${APPLE}>:${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/icons/PinPointStudio.icns>
    $<$<BOOL:${WIN32}>:${CMAKE_CURRENT_SOURCE_DIR}/PinPointStudio.rc>
    src/Gui/app/app_settings.h               src/Gui/app/app_settings.cpp
    src/Gui/settings/library_converter.h     src/Gui/settings/library_converter.cpp
    src/Gui/settings/archive_controller.h    src/Gui/settings/archive_controller.cpp
    src/Gui/app/notification_center.h        src/Gui/app/notification_center.cpp
    src/Gui/shot/ppcp_clip_filer.h           src/Gui/shot/ppcp_clip_filer.cpp
    src/Gui/imu/imu_manager.h                src/Gui/imu/imu_manager.cpp
    src/Gui/imu/imu_role_map.h               src/Gui/imu/imu_role_map.cpp
    src/Gui/imu/paced_connect_queue.h        src/Gui/imu/paced_connect_queue.cpp
    src/Analysis/segment_role.h
    src/Gui/imu/imu_instance.h               src/Gui/imu/imu_instance.cpp
    # imu_device.h carries Q_OBJECT and has no .cpp of its own, so AUTOMOC only
    # sees it if it is listed here — without the line, HmInstance links against
    # an ImuDeviceBase with no metaobject.
    src/Gui/imu/imu_device.h
    src/Gui/imu/hm_instance.h                src/Gui/imu/hm_instance.cpp
    src/Gui/media/transcription_controller.h src/Gui/media/transcription_controller.cpp
    src/Gui/media/tts_controller.h           src/Gui/media/tts_controller.cpp
    src/Gui/media/film_controller.h          src/Gui/media/film_controller.cpp
    src/Gui/athlete/athlete_controller.h     src/Gui/athlete/athlete_controller.cpp
    src/Gui/shell/navigation_controller.h    src/Gui/shell/navigation_controller.cpp
    src/Gui/monitor/resource_monitor_controller.h src/Gui/monitor/resource_monitor_controller.cpp
    src/Gui/monitor/profiler_controller.h         src/Gui/monitor/profiler_controller.cpp
    src/Gui/app/clipboard_helper.h
    src/Gui/app/app_log.h                    src/Gui/app/app_log.cpp
    src/Gui/session/session_controller.h       src/Gui/session/session_controller.cpp
    src/Gui/review/session_review_controller.h src/Gui/review/session_review_controller.cpp
    src/Gui/review/session_list_model.h        src/Gui/review/session_list_model.cpp
    src/Gui/review/session_summary.h
    src/Gui/shot/shot_arbiter.h
    src/Gui/shot/shot_controller.h          src/Gui/shot/shot_controller.cpp
    src/Gui/shot/shot_list_model.h          src/Gui/shot/shot_list_model.cpp
    src/Gui/shot/shot_processor.h           src/Gui/shot/shot_processor.cpp
    src/Gui/shot/shot_replay_controller.h   src/Gui/shot/shot_replay_controller.cpp
    src/Gui/shot/current_swing.h
    src/Gui/shot/reanalysis_controller.h    src/Gui/shot/reanalysis_controller.cpp
    src/Gui/markup/markup_truth.h           src/Gui/markup/markup_truth.cpp
    src/Gui/markup/markup_controller.h      src/Gui/markup/markup_controller.cpp
    src/Gui/markup/markup_image_provider.h
    src/Gui/shot/replay_source.h
    src/Gui/shot/disk_replay_source.h       src/Gui/shot/disk_replay_source.cpp
    src/Gui/shot/dtl_overlay_payload.h      src/Gui/shot/dtl_overlay_payload.cpp
    src/Gui/viz/live_wrist_angles.h         src/Gui/viz/live_wrist_angles.cpp
    src/IMU/imu_base.h        src/IMU/imu_base.cpp
    src/IMU/imu_capabilities.h
    src/IMU/iorientation_filter.h
    src/IMU/orientation_filter.h
    src/IMU/eskf_orientation_filter.h  src/IMU/eskf_orientation_filter.cpp
    src/IMU/imu_calibration.h
    src/IMU/impact_detector.h
    src/IMU/imu_factory.h     src/IMU/imu_factory.cpp
    src/IMU/wt9011dcl_base.h  src/IMU/wt9011dcl_base.cpp
    src/IMU/wt9011dcl.h       src/IMU/wt9011dcl.cpp
    src/IMU/ble_adapter_pool.h  src/IMU/ble_adapter_pool.cpp
    src/IMU/ble_imu_transport.h src/IMU/ble_imu_transport.cpp
    src/IMU/wt9011dcl_ble.h   src/IMU/wt9011dcl_ble.cpp
    src/IMU/imu_io_worker.h   src/IMU/imu_io_worker.cpp
    src/IMU/hm_session_types.h
    src/IMU/hm_session_worker.h  src/IMU/hm_session_worker.cpp
    src/LaunchMonitor/launch_monitor_reading.h   src/LaunchMonitor/launch_monitor_reading.cpp
    src/LaunchMonitor/launch_monitor_base.h      src/LaunchMonitor/launch_monitor_base.cpp
    src/LaunchMonitor/launch_monitor_factory.h   src/LaunchMonitor/launch_monitor_factory.cpp
    src/LaunchMonitor/shot_pairing.h
    src/LaunchMonitor/standalone_gate.h           src/LaunchMonitor/standalone_gate.cpp
    src/LaunchMonitor/gcquad_csv_parser.h        src/LaunchMonitor/gcquad_csv_parser.cpp
    src/LaunchMonitor/gcquad_monitor.h           src/LaunchMonitor/gcquad_monitor.cpp
    src/LaunchMonitor/gspro_reading.h            src/LaunchMonitor/gspro_reading.cpp
    src/LaunchMonitor/gspro_monitor.h            src/LaunchMonitor/gspro_monitor.cpp
    src/Gui/launchmonitor/launch_monitor_controller.h src/Gui/launchmonitor/launch_monitor_controller.cpp
    src/Audio/onset_detector.h
    src/Audio/acoustic_shot_detector.h src/Audio/acoustic_shot_detector.cpp
    src/Audio/audio_processor_base.h src/Audio/audio_processor_base.cpp
    src/Audio/audio_input_base.h     src/Audio/audio_input_base.cpp
    src/Audio/audio_input.h          src/Audio/audio_input.cpp
    src/Audio/audio_output_base.h    src/Audio/audio_output_base.cpp
    src/Audio/audio_output.h         src/Audio/audio_output.cpp
    src/Audio/audio_stream_saver.h   src/Audio/audio_stream_saver.cpp
    src/Video/camera_capabilities.h
    src/Video/video_input_base.h           src/Video/video_input_base.cpp
    src/Video/video_input.h                src/Video/video_input.cpp
    src/Video/video_input_factory.h        src/Video/video_input_factory.cpp
    src/Video/video_preprocessor_base.h   src/Video/video_preprocessor_base.cpp
    src/Video/video_overlay_base.h        src/Video/video_overlay_base.cpp
    src/Video/raw_video_frame.h            src/Video/raw_video_frame.cpp
    src/Video/frame_crop.h                 src/Video/frame_crop.cpp
    src/Pose/pose_estimator_base.h        src/Pose/pose_estimator_base.cpp
    src/Core/device_enumerator.h           src/Core/device_enumerator.cpp
    src/Video/VideoInputAravis.h           src/Video/VideoInputAravis.cpp
    src/Gui/cameras/camera_instance.h     src/Gui/cameras/camera_instance.cpp
    src/Gui/cameras/camera_manager.h      src/Gui/cameras/camera_manager.cpp
    src/Gui/cameras/camera_role_probe.h   src/Gui/cameras/camera_role_probe.cpp
    src/Gui/cameras/buffer_controller.h   src/Gui/cameras/buffer_controller.cpp
    src/STT/stt_processor.h          src/STT/stt_processor.cpp
    src/TTS/TTSEngine.h              src/TTS/TTSEngine.cpp
    src/TTS/TTSEngineFactory.h       src/TTS/TTSEngineFactory.cpp
    src/TTS/AzureTTSEngine.h         src/TTS/AzureTTSEngine.cpp
    src/TTS/KokoroTTSEngine.h        src/TTS/KokoroTTSEngine.cpp
    src/TTS/PhonemeTokenizer.h       src/TTS/PhonemeTokenizer.cpp
    src/TTS/TtsWorker.h              src/TTS/TtsWorker.cpp
    src/TTS/ModelDownloader.h        src/TTS/ModelDownloader.cpp
    src/LLM/LlmEngine.h              src/LLM/LlmEngine.cpp
    src/LLM/LocalLlmEngine.h         src/LLM/LocalLlmEngine.cpp
    src/LLM/GeminiLlmEngine.h        src/LLM/GeminiLlmEngine.cpp
    src/LLM/LlmWorker.h              src/LLM/LlmWorker.cpp
    src/Gui/media/llm_controller.h   src/Gui/media/llm_controller.cpp
)

target_include_directories(PinPointStudio PRIVATE
    src/Gui
    src/Gui/app src/Gui/shell src/Gui/athlete src/Gui/monitor src/Gui/cameras
    src/Gui/imu src/Gui/viz src/Gui/swing3d src/Gui/session src/Gui/shot src/Gui/review
    src/Gui/media src/Gui/calibration src/Gui/diagnostics src/Gui/markup src/Gui/charts src/Gui/trust
    src/Gui/characteristics src/Gui/diagnosticmodel src/Gui/launchmonitor src/Gui/print
    src/IMU src/LaunchMonitor src/Audio src/Video src/Pose src/STT src/TTS src/LLM src/Secrets src/Core src/Buffer
    src/Analysis src/Club src/Wrist src/Body src/Timeline src/Ball src/Kinematics src/Skeleton3d
    src/Coaching src/Metrics
    src/Diagnostics/engine src/Diagnostics/packs src/Diagnostics/norms src/Diagnostics/measures
    src/Update
    "${CMAKE_BINARY_DIR}/generated")

# The module's three lists — .qml files, which of them are singletons, and the C++ types —
# live in cmake/PinPointQmlModule.cmake because qml_ui_test declares the SAME module to press
# real components without building the app. One list, two consumers; see that file for why the
# singleton list in particular must not get separated from the other two.
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/PinPointQmlModule.cmake)

foreach(_pp_singleton IN LISTS PP_QML_SINGLETONS)
    set_source_files_properties(${_pp_singleton} PROPERTIES QT_QML_SINGLETON_TYPE TRUE)
endforeach()

qt_add_qml_module(PinPointStudio
    URI PinPointStudio
    OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml/PinPointStudio
    QML_FILES ${PP_QML_FILES}
    SOURCES   ${PP_QML_SOURCES}
)

qt6_add_shaders(PinPointStudio "debayer_shaders"
    BATCHABLE
    PRECOMPILE
    PREFIX "/shaders"
    FILES
        "src/Shaders/debayer.vert"
        "src/Shaders/debayer.frag"
)

qt6_add_shaders(PinPointStudio "bayer_demosaic_shaders"
    PRECOMPILE
    OPTIMIZED
    PREFIX "/shaders"
    FILES
        "src/Shaders/bayer_demosaic.vert"
        "src/Shaders/bayer_demosaic.frag"
)

qt6_add_shaders(PinPointStudio "topo_shaders"
    BATCHABLE
    PRECOMPILE
    OPTIMIZED
    PREFIX "/shaders"
    FILES
        "src/Shaders/topo.vert"
        "src/Shaders/topo.frag"
)

qt6_add_shaders(PinPointStudio "viewgain_shaders"
    BATCHABLE
    PRECOMPILE
    OPTIMIZED
    PREFIX "/shaders"
    FILES
        "src/Shaders/viewgain.vert"
        "src/Shaders/viewgain.frag"
)

target_compile_definitions(PinPointStudio PRIVATE
    QT_APPLICATION_NAME="PinPointStudio"
)

# ── PinPointStudio debug level ──────────────────────────────────────────────────────
# Controls pp_debug.h verbosity at compile time:
#   0 = silent   1 = warnings+errors only (default for all builds)
#   2 = startup info + warnings/errors    (pass -DPINPOINT_DEBUG_LEVEL=2)
#   3 = verbose debug + all of the above
if(NOT DEFINED PINPOINT_DEBUG_LEVEL)
    set(PINPOINT_DEBUG_LEVEL 1)
endif()
message(STATUS "PinPointStudio debug level: ${PINPOINT_DEBUG_LEVEL}")
target_compile_definitions(PinPointStudio PRIVATE PINPOINT_DEBUG_LEVEL=${PINPOINT_DEBUG_LEVEL})

# ── Resource profiler ───────────────────────────────────────────────────────
# Baseline tier ships in ALL builds (incl. release) through alpha/beta; flip OFF
# for GA. Deep tier is opt-in at compile time AND gated by a runtime toggle.
option(PINPOINT_PROFILE_BASELINE "Always-on baseline resource profiling" ON)
option(PINPOINT_PROFILE          "Deep, toggle-gated resource profiling"  OFF)
message(STATUS "PinPointStudio profiler: baseline=${PINPOINT_PROFILE_BASELINE} deep=${PINPOINT_PROFILE}")
target_compile_definitions(PinPointStudio PRIVATE
    PINPOINT_PROFILE_BASELINE=$<BOOL:${PINPOINT_PROFILE_BASELINE}>
    PINPOINT_PROFILE=$<BOOL:${PINPOINT_PROFILE}>)

target_sources(PinPointStudio PRIVATE
    src/Core/pp_debug.h
    src/Core/pp_debug.cpp
    src/Core/pp_log_stream.cpp
    src/Core/pp_colorspace_pin.h
    src/Core/pp_colorspace_pin.cpp
    src/Core/app_info.h
    src/Core/app_info.cpp
    src/Core/pp_settings.h
    src/Core/PpMessageLog.h
    src/Core/PpMessageLog.cpp
    src/Core/PpStatsLog.h
    src/Core/PpStatsLog.cpp
    src/Core/AnalysisProfileLog.h
    src/Core/AnalysisProfileLog.cpp
    src/Core/pp_profiler.h
    src/Core/pp_profiler.cpp
    src/Core/pp_os_metrics.h
    src/Core/pp_os_metrics.cpp
    src/Core/pp_gpu_metrics.h
    src/Core/pp_gpu_metrics.cpp
)

# ── Application icon ─────────────────────────────────────────────────────────
if(APPLE)
    set(MACOSX_BUNDLE_ICON_FILE PinPointStudio)
    set_source_files_properties(
        "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/icons/PinPointStudio.icns"
        PROPERTIES MACOSX_PACKAGE_LOCATION "Resources"
    )
endif()

set_target_properties(PinPointStudio PROPERTIES
    MACOSX_BUNDLE TRUE
    MACOSX_BUNDLE_ICON_FILE PinPointStudio
    WIN32_EXECUTABLE TRUE
)

# Packaged-build marker (see the option() above) — compiled in only when the
# packaging scripts pass -DPINPOINT_INSTALLED=ON.
if(PINPOINT_INSTALLED)
    target_compile_definitions(PinPointStudio PRIVATE PINPOINT_INSTALLED)
endif()

# ── Info.plist substitution variables (macOS) ────────────────────────────────
# Single source of truth is src/Core/version.h (parsed above). These feed the
# @VAR@ placeholders in Info.plist.in so the bundle version, the Sparkle compare
# key, and the appcast can never drift (macOS design §7).
#   • CFBundleShortVersionString = display version (e.g. 0.1-alpha3)
#   • CFBundleVersion            = monotonic build int (Sparkle's compare key)
set(PP_DISPLAY_VERSION "${_pp_ver_major}.${_pp_ver_minor}${_pp_ver_postfix}")
set(PP_VERSION_BUILD   "${_pp_ver_build}")

# Sparkle feed + pinned EdDSA public key (macOS design §4.1, §6). The feed URL is
# static (GitHub latest-release redirect); the key is read from the repo's pinned
# .pub so the generated Info.plist carries it as SUPublicEDKey. PLACEHOLDER until
# the offline key is generated — the macOS updater (Stage 2) refuses to arm while
# it is the placeholder, exactly as the Windows/Linux gates do.
#
# ONE FEED PER ARCHITECTURE. x86_64 and arm64 ship different ONNX Runtime major
# versions and different engines (arm64: ORT 1.26 + CoreML + ORT-GenAI; x86_64: ORT
# 1.20.1, CPU, no local LLM), so a single feed would offer each arch the other's DMG.
# Sparkle installs IN PLACE, so that is not a failed download — it is a working install
# replaced by one that cannot launch. Design §4.1: each architecture's binary only ever
# sees its own feed.
#
# Branch on CMAKE_SYSTEM_PROCESSOR — the SAME predicate the ORT package and the CoreML
# define already use above, so there is exactly one arch test in this file with one
# meaning. Note this deliberately does NOT set CMAKE_OSX_ARCHITECTURES: that would not
# move CMAKE_SYSTEM_PROCESSOR, so a cross-build would silently desync the ORT package,
# the CoreML define and this feed URL from the slice actually emitted. Host-native
# builds only.
#
#   !! THE x86_64 URL IS FROZEN !!  It is baked into the Info.plist of every Intel
#   install already in the field, and Sparkle re-reads it from the INSTALLED bundle.
#   Renaming it — even for symmetry with the arm64 name — permanently orphans every one
#   of them: they would poll a URL that 404s and silently never update again. Add feeds,
#   never rename this one.
if(APPLE AND CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64")
    set(PP_SU_FEED_URL "https://github.com/PinPoint-Golf/PinPointStudio/releases/latest/download/appcast-mac-arm64.xml")
else()
    set(PP_SU_FEED_URL "https://github.com/PinPoint-Golf/PinPointStudio/releases/latest/download/appcast-mac.xml")
endif()
if(APPLE)
    message(STATUS "Sparkle feed (${CMAKE_SYSTEM_PROCESSOR}): ${PP_SU_FEED_URL}")
endif()
set(_pp_mac_eddsa_pub "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/keys/pinpoint_release_mac_eddsa.pub")
if(EXISTS "${_pp_mac_eddsa_pub}")
    file(READ "${_pp_mac_eddsa_pub}" PP_SU_PUBLIC_ED_KEY)
    string(STRIP "${PP_SU_PUBLIC_ED_KEY}" PP_SU_PUBLIC_ED_KEY)
else()
    set(PP_SU_PUBLIC_ED_KEY "PLACEHOLDER")
endif()

# Qt's CMake infrastructure ignores MACOSX_BUNDLE_INFO_PLIST in some
# configurations.  Generate the plist at configure time (substituting @VAR@ only,
# so the XML's literal text is untouched) and copy it into the bundle with a
# POST_BUILD step so it always wins.
configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/Info.plist.in"
    "${CMAKE_CURRENT_BINARY_DIR}/Info.plist"
    @ONLY
)


# The shipped diagnostics content — the swing-characteristics pack, the norm set and the context
# tree. The files under src/Resources/diagnostics/ are the reviewable source of truth committed to
# the repo; this embeds them for runtime. Keep the two in step — there is no generation step, the
# files ARE the content, which is what lets a community contribution arrive as a pull request
# against readable JSON rather than a binary blob.
qt_add_resources(PinPointStudio "app_diagnostics"
    PREFIX "/diagnostics"
    BASE   "src/Resources/diagnostics"
    FILES
        src/Resources/diagnostics/core.json
        src/Resources/diagnostics/norms.json
        src/Resources/diagnostics/contexts.json
        src/Resources/diagnostics/screens.json
        src/Resources/diagnostics/drills.json
                src/Resources/diagnostics/references.json
)

qt_add_resources(PinPointStudio "app_icons"
    PREFIX "/icons"
    BASE   "src/Resources/icons"
    FILES
        src/Resources/icons/pinpointstudio_256.png
        src/Resources/icons/pinpointstudio_512.png
)

# Pinned release public keys for the in-app updaters' signature gates:
#   *.asc          → Linux AppImage GPG gate      (docs/design/linux_update.md §6)
#   *_win_eddsa.pub → Windows WinSparkle EdDSA gate (docs/design/windows_update.md §6)
#   *_mac_eddsa.pub → macOS Sparkle EdDSA gate     (docs/design/macos_update.md §6)
# PLACEHOLDERS until the real keys are generated — the gates refuse every update
# while the key is a placeholder.
#
# The Linux/Windows keys are compiled in as :/keys/ Qt resources (read by the
# updater code at runtime). The macOS key is NOT a Qt resource: Sparkle reads it
# from the bundle's Info.plist (SUPublicEDKey), which CMake fills from the .pub at
# configure time (see the PP_SU_PUBLIC_ED_KEY block above). The file is committed
# for transparency and as that single source of truth.
qt_add_resources(PinPointStudio "app_keys"
    PREFIX "/keys"
    BASE "src/Resources/keys"
    FILES
        src/Resources/keys/pinpoint_release_pubkey.asc
        src/Resources/keys/pinpoint_release_win_eddsa.pub
)

# The font list lives in cmake/PinPointFonts.cmake because qml_ui_test needs the SAME
# faces compiled into it — a layout test measuring a fallback face is measuring a font
# this application never renders with. See that file.
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/PinPointFonts.cmake)
qt_add_resources(PinPointStudio "app_fonts"
    PREFIX "/fonts"
    BASE "src/Resources/fonts"
    FILES ${PP_FONT_FILES}
)

qt_add_resources(PinPointStudio "app_tiles"
    PREFIX "/assets/tiles"
    BASE "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/tiles"
    FILES
        src/Resources/tiles/golfswing.png
        src/Resources/tiles/grip.png
        src/Resources/tiles/feet.png
        src/Resources/tiles/coach.png
)

qt_add_resources(PinPointStudio "app_body"
    PREFIX "/assets/body"
    BASE "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/body"
    FILES
        src/Resources/body/ybot.glb
        src/Resources/body/arm_LeftArm.glb
        src/Resources/body/arm_LeftForeArm.glb
        src/Resources/body/arm_LeftHand.glb
        src/Resources/body/arm_RightArm.glb
        src/Resources/body/arm_RightForeArm.glb
        src/Resources/body/arm_RightHand.glb
        src/Resources/body/body_Hips.glb
        src/Resources/body/body_Spine.glb
        src/Resources/body/body_Spine1.glb
        src/Resources/body/body_Spine2.glb
        src/Resources/body/body_Head.glb
        src/Resources/body/body_LeftShoulder.glb
        src/Resources/body/body_RightShoulder.glb
        src/Resources/body/body_LeftUpLeg.glb
        src/Resources/body/body_LeftLeg.glb
        src/Resources/body/body_LeftFoot.glb
        src/Resources/body/body_RightUpLeg.glb
        src/Resources/body/body_RightLeg.glb
        src/Resources/body/body_RightFoot.glb
)

# The 3-D swing panel's own figure — a smooth mannequin on the Y-bot's skeleton
# (tools/generate_swing3d_mannequin.py) — deliberately NOT the calibration views'
# src/Resources/body/ set (swing_3d_viz_design.md §6.1: no shared files).
qt_add_resources(PinPointStudio "app_swing3d"
    PREFIX "/assets/swing3d"
    BASE "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/swing3d"
    FILES
        src/Resources/swing3d/man_Hips.glb
        src/Resources/swing3d/man_Spine.glb
        src/Resources/swing3d/man_Spine1.glb
        src/Resources/swing3d/man_Spine2.glb
        src/Resources/swing3d/man_Neck.glb
        src/Resources/swing3d/man_Head.glb
        src/Resources/swing3d/man_LeftShoulder.glb
        src/Resources/swing3d/man_RightShoulder.glb
        src/Resources/swing3d/man_LeftArm.glb
        src/Resources/swing3d/man_LeftForeArm.glb
        src/Resources/swing3d/man_LeftHand.glb
        src/Resources/swing3d/man_RightArm.glb
        src/Resources/swing3d/man_RightForeArm.glb
        src/Resources/swing3d/man_RightHand.glb
        src/Resources/swing3d/man_LeftUpLeg.glb
        src/Resources/swing3d/man_LeftLeg.glb
        src/Resources/swing3d/man_LeftFoot.glb
        src/Resources/swing3d/man_RightUpLeg.glb
        src/Resources/swing3d/man_RightLeg.glb
        src/Resources/swing3d/man_RightFoot.glb
        src/Resources/swing3d/hull.glb
)

# The launch monitor panel's club heads, ball and impact patch, vendored from the PinPoint Golf
# Resources repo by tools/lm_art/vendor.sh — src/Gui/resources/lm/VENDORED.md records the commit
# and the size arithmetic. The list is the script's own files.cmake, so CMake never globs and a
# re-vendor arrives as one reviewable diff. Served at qrc:/lm/… and read through LmClubArt.
# qml_ui_test compiles the same list (src/Gui/CMakeLists.txt) so the panel draws there too.
include(${CMAKE_CURRENT_SOURCE_DIR}/src/Gui/resources/lm/files.cmake)
list(TRANSFORM PP_LM_ART_FILES PREPEND "src/Gui/resources/lm/" OUTPUT_VARIABLE _pp_lm_art_app)
qt_add_resources(PinPointStudio "app_lm_art"
    PREFIX "/lm"
    BASE   "${CMAKE_CURRENT_SOURCE_DIR}/src/Gui/resources/lm"
    FILES  ${_pp_lm_art_app}
)

# ── Linux: deploy icon + .desktop to user dirs on every build ────────────────
# GNOME's taskbar icon comes from the .desktop file, not setWindowIcon().
# Copying to ~/.local/share avoids requiring cmake --install or sudo.
if(UNIX AND NOT APPLE)
    set(_xdg_icon_dir "$ENV{HOME}/.local/share/icons/hicolor/256x256/apps")
    set(_xdg_apps_dir "$ENV{HOME}/.local/share/applications")

    file(GENERATE
        OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/pinpointstudio.desktop"
        CONTENT "[Desktop Entry]
Name=PinPoint Studio
Exec=$<TARGET_FILE:PinPointStudio>
Icon=pinpointstudio
Type=Application
Terminal=false
Categories=Sports;
StartupWMClass=PinPointStudio
"
    )

    add_custom_command(TARGET PinPointStudio POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E make_directory "${_xdg_icon_dir}"
        COMMAND ${CMAKE_COMMAND} -E copy
            "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/icons/pinpointstudio_256.png"
            "${_xdg_icon_dir}/pinpointstudio.png"
        COMMAND ${CMAKE_COMMAND} -E make_directory "${_xdg_apps_dir}"
        COMMAND ${CMAKE_COMMAND} -E copy
            "${CMAKE_CURRENT_BINARY_DIR}/pinpointstudio.desktop"
            "${_xdg_apps_dir}/pinpointstudio.desktop"
        COMMENT "Registering PinPointStudio icon and launcher in user dirs"
    )
endif()

target_link_libraries(PinPointStudio
    PRIVATE Qt6::Quick Qt6::QuickControls2 Qt6::Quick3D Qt6::SerialPort Qt6::Bluetooth Qt6::Multimedia Qt6::Network Qt6::WebSockets Qt6::Concurrent Qt6::GuiPrivate Qt6::CorePrivate
            pinpoint_buffer pinpoint_swingstore
)


target_sources(PinPointStudio PRIVATE
    src/Audio/AudioConverter.h
    src/Audio/AudioConverter.cpp
    src/STT/STTBackend.h
    src/STT/STTBackendFactory.h
    src/STT/STTBackendFactory.cpp
    src/STT/STTBackendWhisperCpp.h
    src/STT/STTBackendWhisperCpp.cpp
    src/STT/STTBackendAssemblyAI.h
    src/STT/STTBackendAssemblyAI.cpp
    src/STT/STTBackendAzure.h
    src/STT/STTBackendAzure.cpp
    src/STT/STTWorker.h
    src/STT/STTWorker.cpp
)

target_sources(PinPointStudio PRIVATE
    src/Secrets/SecretsManager.h
    src/Secrets/SecretsManager.cpp
    src/Secrets/SecretsBridge.h
    src/Secrets/SecretsBridge.cpp
)

# ── In-app update ─────────────────────────────────────────────────────────────
# UpdateController is the QML façade on ALL platforms; the platform engine behind
# it is one UpdateBackend chosen by makeUpdateBackend() (the sole #ifdef). See
# docs/design/{linux,windows,macos}_update.md.
target_sources(PinPointStudio PRIVATE
    src/Update/update_controller.h
    src/Update/update_controller.cpp
    src/Update/update_backend.h
    src/Update/update_backend_factory.h
    src/Update/update_backend_factory.cpp
    src/Update/inert_update_backend.h
    # (OS,CPU) target — arch-aware asset/feed selection; cheap, platform-agnostic.
    src/Update/platform_target.h
    src/Update/platform_target.cpp
    # Hardware-adaptive CUDA runtime offer (Windows; inert elsewhere) — design §4.4.
    src/Update/cuda_runtime_controller.h
    src/Update/cuda_runtime_controller.cpp
)

# Linux AppImage backend + its pure logic + the appimageupdatetool driver — the
# only backend that drives a full state machine. Compiled where the factory
# instantiates it (UNIX-non-Apple, matching the Q_OS_LINUX path). Pure Qt
# (Network/Concurrent/Process); no libappimageupdate/gpgme deps — design linux_update.md.
if(UNIX AND NOT APPLE)
    target_sources(PinPointStudio PRIVATE
        src/Update/linux_appimage_backend.h
        src/Update/linux_appimage_backend.cpp
        src/Update/linux_update_logic.h
        src/Update/linux_update_logic.cpp
        src/Update/appimage_update.h
        src/Update/appimage_update.cpp)
endif()

# ── WinSparkle (Windows in-app update engine) ─────────────────────────────────
# The WinSparkle/Sparkle analogue for Windows. See docs/design/windows_update.md.
# Prebuilt DLL + import lib fetched like the ORT package; linked and bundled into
# the "core" component so it travels with the small auto-update payload. EdDSA
# signature pinning requires WinSparkle >= 0.9.0.
if(WIN32)
    set(WINSPARKLE_VERSION "0.9.3")
    FetchContent_Declare(winsparkle
        URL "https://github.com/vslavik/winsparkle/releases/download/v${WINSPARKLE_VERSION}/WinSparkle-${WINSPARKLE_VERSION}.zip"
        URL_HASH SHA256=745985f41d2ab26b2d5a1cf87d76e4ed851039db19038e50610eb25ea0b73772
        DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
    FetchContent_MakeAvailable(winsparkle)

    # The archive keeps a top-level WinSparkle-<ver>/ dir; probe for the header in
    # case a CMake version strips it (mirrors the ORT root probe above).
    if(EXISTS "${winsparkle_SOURCE_DIR}/include/winsparkle.h")
        set(_ws_root "${winsparkle_SOURCE_DIR}")
    else()
        file(GLOB _ws_candidates LIST_DIRECTORIES true "${winsparkle_SOURCE_DIR}/WinSparkle-*")
        list(GET _ws_candidates 0 _ws_root)
    endif()

    target_include_directories(PinPointStudio PRIVATE "${_ws_root}/include")
    target_link_libraries(PinPointStudio PRIVATE "${_ws_root}/x64/Release/WinSparkle.lib")
    target_compile_definitions(PinPointStudio PRIVATE HAVE_WINSPARKLE)
    pp_win_bundle_dll(core "${_ws_root}/x64/Release/WinSparkle.dll")

    target_sources(PinPointStudio PRIVATE
        src/Update/win_sparkle_update.h
        src/Update/win_sparkle_update.cpp
        src/Update/win_sparkle_backend.h     # UpdateBackend over WinSparkleUpdater
        src/Update/win_sparkle_backend.cpp)
endif()

# ── Sparkle (macOS in-app update engine) ──────────────────────────────────────
# The macOS analogue of WinSparkle. See docs/design/macos_update.md. The prebuilt
# universal Sparkle.framework is fetched like the ORT/WinSparkle packages, linked,
# and (in tools/package_macos.sh §4e) embedded into Contents/Frameworks/ with its
# Autoupdate/Updater.app/XPCServices helpers and re-signed bottom-up. EdDSA
# verification + the XPC helpers require Sparkle >= 2.x. The .tar.xz also carries
# bin/generate_keys + bin/sign_update — the offline release-key + appcast tools.
if(APPLE)
    set(SPARKLE_VERSION "2.9.3")
    FetchContent_Declare(sparkle
        URL "https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
        URL_HASH SHA256=74a07da821f92b79310009954c0e15f350173374a3abe39095b4fc5096916be6
        DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
    FetchContent_MakeAvailable(sparkle)

    # The archive extracts Sparkle.framework at the top level; probe in case a CMake
    # version nests it (mirrors the ORT/WinSparkle root probes above).
    if(EXISTS "${sparkle_SOURCE_DIR}/Sparkle.framework/Headers/Sparkle.h")
        set(_sparkle_root "${sparkle_SOURCE_DIR}")
    else()
        file(GLOB _sparkle_candidates LIST_DIRECTORIES true "${sparkle_SOURCE_DIR}/Sparkle-*")
        list(GET _sparkle_candidates 0 _sparkle_root)
    endif()

    # -F<dir> so `#import <Sparkle/Sparkle.h>` resolves and `-framework Sparkle` links;
    # BUILD_RPATH so a dev build run from the build tree loads the framework straight
    # from _deps (its install name is @rpath/Sparkle.framework/...). The packaged build
    # gets @executable_path/../Frameworks from macdeployqt + the §4e embed step.
    target_compile_options(PinPointStudio PRIVATE "-F${_sparkle_root}")
    target_link_options(PinPointStudio PRIVATE "-F${_sparkle_root}")
    target_link_libraries(PinPointStudio PRIVATE "-framework Sparkle")
    set_property(TARGET PinPointStudio APPEND PROPERTY BUILD_RPATH "${_sparkle_root}")
    target_compile_definitions(PinPointStudio PRIVATE HAVE_SPARKLE)

    # Expose the framework + tool paths to the packaging script (read from the build
    # tree's CMakeCache) so it copies the exact fetched framework, not a guessed one.
    set(PP_SPARKLE_FRAMEWORK "${_sparkle_root}/Sparkle.framework" CACHE INTERNAL "")
    set(PP_SPARKLE_BIN "${_sparkle_root}/bin" CACHE INTERNAL "")

    target_sources(PinPointStudio PRIVATE
        src/Update/mac_sparkle_update.h
        src/Update/mac_sparkle_update.mm
        src/Update/mac_sparkle_backend.h     # UpdateBackend over MacSparkleUpdater
        src/Update/mac_sparkle_backend.cpp)  # plain C++ — Cocoa stays behind the shim
    # The shim manages two long-lived Cocoa objects via __bridge_retained/_transfer and
    # holds the postponed-relaunch block in a copy property — compile it under ARC.
    set_source_files_properties(src/Update/mac_sparkle_update.mm
        PROPERTIES COMPILE_OPTIONS "-fobjc-arc")
endif()

# ── Azure cloud STT fallback ──────────────────────────────────────────────────
# The Azure STT backend uses the same Cognitive Services Speech resource as the
# TTS backend, so AZURE_TTS_API_KEY is checked automatically as a fallback when
# AZURE_STT_API_KEY is not set.  Set either env var before the first launch and
# the value is saved to QSettings so the env var is not required on future runs.
message(STATUS "Azure STT: key supplied via AZURE_STT_API_KEY env var or shared AZURE_TTS_API_KEY")

# ── AssemblyAI cloud STT (kept for reference, not used as fallback) ───────────
# Pass -DASSEMBLYAI_API_KEY=<key> at cmake configure time to seed the key into
# QSettings on first run. The key can also be supplied via the
# ASSEMBLYAI_API_KEY environment variable (takes priority over QSettings).
set(ASSEMBLYAI_API_KEY "" CACHE STRING
    "AssemblyAI API key — written to QSettings on first run, not needed after that")
if(ASSEMBLYAI_API_KEY)
    target_compile_definitions(PinPointStudio PRIVATE
        ASSEMBLYAI_API_KEY_DEFAULT="${ASSEMBLYAI_API_KEY}")
    message(STATUS "AssemblyAI: API key provided (will be seeded to QSettings on first run)")
else()
    message(STATUS "AssemblyAI: no API key configured")
endif()

target_link_libraries(PinPointStudio PRIVATE whisper samplerate wrist gspro)
# libppcp, when it resolved (H0 above). Linked with nothing calling it yet: the
# peer engine lands in H2. Its include/ is PUBLIC on the target, so <ppcp/ppcp.h>
# resolves through the link and needs no include directory here — same as wrist.
# HAVE_PPCP means only "the library is linked", never a runtime feature gate.
if(TARGET ppcp)
    target_link_libraries(PinPointStudio PRIVATE ppcp)
    target_compile_definitions(PinPointStudio PRIVATE HAVE_PPCP)

    # H2, first half — the host's own `declare`. Needs the library's entity
    # vocabulary (L4) and nothing else: no socket, no peer engine, no OpenSSL.
    # It is therefore built whenever libppcp is embedded, even on a box with no
    # TLS, because CT-S3 and CT-I19 are about what the host SAYS about itself.
    target_sources(PinPointStudio PRIVATE
        src/Ppcp/ppcp_engine.h
        src/Ppcp/ppcp_source_declaration.h
        src/Ppcp/ppcp_source_declaration.cpp
        src/Ppcp/ppcp_host_inventory.cpp
        # The engine, built in ONE place so the socket path and the bundle path
        # get the identical peer (plan A10). Deliberately outside the OpenSSL
        # block below: a file is not a socket, and needing TLS to read one would
        # be this application inventing a requirement the specification has not.
        src/Ppcp/ppcp_host_engine.h        src/Ppcp/ppcp_host_engine.cpp
        # The engine's own dependency, moved here from the OpenSSL block for the
        # same reason as ppcp_host_engine.cpp itself: evaluate() decides accept/
        # reject on a peer_desc, touches no socket and no TLS, and ppcp_host_engine.cpp
        # calls it unconditionally — leaving it OpenSSL-gated meant a box with no
        # OpenSSL got ppcp_host_engine.cpp.obj with an unresolved external symbol
        # rather than a build that simply excludes it (observed 24 Aug, Debug kit).
        src/Ppcp/ppcp_ingest_policy.h      src/Ppcp/ppcp_ingest_policy.cpp
        # H3 — the bundle path. No OpenSSL and no socket: plan A10 says a file
        # transport feeds the SAME ingest path a socket does, and one that had
        # to link TLS to reach the sink would not be the same path.
        src/Ppcp/ppcp_bundle_transport.h   src/Ppcp/ppcp_bundle_transport.cpp
        src/Ppcp/ppcp_import_ledger.h      src/Ppcp/ppcp_import_ledger.cpp
        src/Ppcp/ppcp_import_sink.h        src/Ppcp/ppcp_import_sink.cpp
        src/Ppcp/ppcp_import_controller.h  src/Ppcp/ppcp_import_controller.cpp
        # H5 — the live Session and the arbitration bridge. NO OpenSSL here
        # either, for the third time in this block and for the same reason: a
        # Session is opened over a link and nothing about what it CARRIES
        # depends on that link being TLS. The socket owner lives in the block
        # below; these are what it drives.
        src/Ppcp/ppcp_live_session.h       src/Ppcp/ppcp_live_session.cpp
        src/Ppcp/ppcp_shot_bridge.h        src/Ppcp/ppcp_shot_bridge.cpp
        # H5 — the offer list. The user-facing half of the bundle engine above:
        # a connected device offers its Sessions and the host picks from an
        # in-screen list. There is no file picker anywhere in this application.
        src/Ppcp/ppcp_offer_controller.h   src/Ppcp/ppcp_offer_controller.cpp
        # H7 — Markup. Deliberately NOT reachable from src/Analysis, which is
        # I37 and is checked by a grep in ppcp_annotation_test.
        src/Ppcp/ppcp_annotation_store.h   src/Ppcp/ppcp_annotation_store.cpp
        # H4 — a connected peer's camera Source behind the camera factory.
        # In src/Video and not src/Ppcp because it IS a camera backend: it is a
        # peer of VideoInputAravis and VideoInputApple, not a special case the
        # consumers know about. No OpenSSL: a Source declared in a bundle is
        # the same Source, and needing TLS to describe a camera would be this
        # application inventing a requirement the specification has not.
        src/Video/VideoInputPpcp.h         src/Video/VideoInputPpcp.cpp
        src/Video/VideoInputPpcp_inventory.cpp
        # H6 — the QR encoder behind RV 4.1d.  Here and not in the transport
        # block because a pairing code is a picture of a URI and nothing about
        # drawing one needs a TLS stack.  Ours because the repository has none:
        # no qrencode, no ZXing, nothing vendored.
        src/Ppcp/ppcp_qr.h                 src/Ppcp/ppcp_qr.cpp)
    target_include_directories(PinPointStudio PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/Ppcp)
    # ⚠ THE PPCP_HAVE_PEER GUARD IS GONE, AND ITS ABSENCE IS THE RECORD THAT L6
    # LANDED. It read the header on disk and flipped with no edit here, exactly
    # as planned.h asks — "an undefined symbol at link time naming the function,
    # never a stub". <ppcp/peer.h> is now real, so the guard would only be a way
    # for a stale checkout to fail late instead of at the #include.
endif()
# No include directory needed — libwrist's include/ is PUBLIC on the target,
# so <wrist/wrist.h> resolves through the link. HAVE_WRIST means
# only "the library is linked"; the runtime feature gate is a separate setting.
target_compile_definitions(PinPointStudio PRIVATE HAVE_WRIST)
target_include_directories(PinPointStudio PRIVATE
    ${whisper_SOURCE_DIR}/include
    ${whisper_SOURCE_DIR}/ggml/include
    ${libsamplerate_SOURCE_DIR}/include
    # ESKF orientation filter: Eigen + the vendored hobbeshunter/IMU_EKF headers.
    # imu_ekf_compat must precede imu_ekf so the vendored Arduino-style
    # <Eigen.h>/<Wire.h> includes resolve to our desktop shims.
    ${eigen_SOURCE_DIR}
    ${CMAKE_CURRENT_SOURCE_DIR}/third_party/imu_ekf_compat
    ${CMAKE_CURRENT_SOURCE_DIR}/third_party/imu_ekf
)

# FFmpeg log capture — pp_debug.cpp reaches into every loaded libavutil
# instance at runtime to call av_log_set_callback() (Qt's bundled copy and the
# system/exporter package), routing FFmpeg log lines into the in-app message
# log.  No compile-time FFmpeg header/link dependency needed for this.
# UNIX uses dlopen()/dlsym() (needs libdl + this define); Windows uses
# GetModuleHandle()/GetProcAddress() guarded by _WIN32 directly in
# pp_debug.cpp — no define or extra library needed there.
if(UNIX)
    target_link_libraries(PinPointStudio PRIVATE dl)
    target_compile_definitions(PinPointStudio PRIVATE PP_HAS_DLSYM)
    message(STATUS "FFmpeg log capture: via dlsym (UNIX)")
endif()

# ── ONNX Runtime (auto-fetched prebuilt) ─────────────────────────────────────
# Three independent EP flags — each defaults ON; platform guards below control
# which ones are actually wired up and which GPU binary is downloaded.
# CPU EP is always the implicit fallback at runtime regardless of these flags.
option(WITH_CUDA       "Enable CUDA execution provider (Linux/Windows)"                        ON)
option(WITH_COREML     "Enable CoreML execution provider (macOS ARM64)"                        ON)
option(WITH_MEDIAPIPE  "Build with MediaPipe BlazePose pose estimator (requires Python + qai-hub-models)"  OFF)
option(WITH_VITPOSE    "Download and build ViTPose-B pose estimator (ONNX, all platforms)"     ON)

set(ORT_VERSION "1.26.0")

# Select prebuilt binary.
# Windows GPU packages (ORT 1.26+):
#   gpu package       — CUDA 12 + TensorRT
#   gpu_cuda13 package— CUDA 13 + TensorRT  (new in 1.26)
#   std package       — CPU only (DirectML NuGet discontinued after ORT 1.24)
# The CUDA provider DLL imports versioned CUDA DLLs (e.g. cublasLt64_12.dll /
# cublasLt64_13.dll) so the package must match the installed CUDA major version.
if(WIN32)
    if(WITH_CUDA)
        find_package(CUDAToolkit QUIET)
        if(CUDAToolkit_FOUND AND CUDAToolkit_VERSION_MAJOR EQUAL 12)
            message(STATUS "ORT CUDA EP: CUDA 12 — using GPU package")
            set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-win-x64-gpu-${ORT_VERSION}.zip")
        elseif(CUDAToolkit_FOUND AND CUDAToolkit_VERSION_MAJOR EQUAL 13)
            message(STATUS "ORT CUDA EP: CUDA 13 — using CUDA 13 GPU package")
            set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-win-x64-gpu_cuda13-${ORT_VERSION}.zip")
        else()
            if(CUDAToolkit_FOUND)
                message(STATUS "ORT CUDA EP: CUDA ${CUDAToolkit_VERSION} has no matching ORT package — falling back to CPU")
            endif()
            set(WITH_CUDA OFF CACHE BOOL "" FORCE)
            set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-win-x64-${ORT_VERSION}.zip")
        endif()
    else()
        set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-win-x64-${ORT_VERSION}.zip")
    endif()
elseif(APPLE)
    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64")
        set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-osx-arm64-${ORT_VERSION}.tgz")
        # CoreML is included in every macOS ARM64 prebuilt — no separate download needed.
    else()
        # ONNX Runtime 1.21+ dropped Intel macOS (x86_64) prebuilts; pin to the last available.
        set(ORT_VERSION "1.20.1")
        set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-osx-x86_64-${ORT_VERSION}.tgz")
        # CoreML is present in the x86_64 dylib but the Kokoro model has fully
        # dynamic sequence lengths throughout — CoreML on Intel rejects virtually
        # every subgraph ("unbounded dimension"), then hangs or fails to compile
        # what remains. CPU is faster and more correct here.
    endif()
else()  # Linux
    if(WITH_CUDA)
        set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-x64-gpu-${ORT_VERSION}.tgz")
    else()
        set(_ort_url "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-x64-${ORT_VERSION}.tgz")
    endif()
endif()

FetchContent_Declare(onnxruntime URL "${_ort_url}" DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
FetchContent_MakeAvailable(onnxruntime)

# The archive may or may not strip its top-level directory depending on the
# CMake version; probe for the headers to find the actual root.
if(EXISTS "${onnxruntime_SOURCE_DIR}/include/onnxruntime_cxx_api.h")
    set(_ort_root "${onnxruntime_SOURCE_DIR}")
else()
    file(GLOB _ort_candidates LIST_DIRECTORIES true "${onnxruntime_SOURCE_DIR}/onnxruntime-*")
    list(GET _ort_candidates 0 _ort_root)
endif()

target_include_directories(PinPointStudio PRIVATE "${_ort_root}/include")
target_compile_definitions(PinPointStudio PRIVATE HAVE_ONNXRUNTIME)

# Propagate each EP flag to C++ only on platforms where it is supported.
if(WITH_COREML AND APPLE AND CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64")
    target_compile_definitions(PinPointStudio PRIVATE WITH_COREML)
endif()
if(WITH_CUDA AND NOT APPLE)
    target_compile_definitions(PinPointStudio PRIVATE WITH_CUDA)
endif()

# DirectML NuGet was discontinued after ORT 1.24; standard Windows zip is CPU-only
# from ORT 1.20+. No WITH_DIRECTML define on Windows — CUDA EP covers GPU on this platform.

if(WIN32)
    target_link_libraries(PinPointStudio PRIVATE "${_ort_root}/lib/onnxruntime.lib")
    # Collect all ORT DLLs (main + any provider DLLs present in the package).
    # The CUDA/TensorRT provider DLLs are included here in the "core" component:
    # they are versioned with ONNX Runtime (i.e. with the app), not with the
    # NVIDIA toolkit, so they travel with every app update. Only the NVIDIA
    # toolkit + cuDNN DLLs go in the separately-packaged "cuda" component.
    file(GLOB _ort_all_dlls "${_ort_root}/lib/onnxruntime*.dll")
    pp_win_bundle_dll(core ${_ort_all_dlls})
elseif(APPLE)
    file(GLOB _ort_dylib "${_ort_root}/lib/libonnxruntime*.dylib")
    list(GET _ort_dylib 0 _ort_dylib_path)
    target_link_libraries(PinPointStudio PRIVATE "${_ort_dylib_path}")
else()
    target_link_libraries(PinPointStudio PRIVATE "${_ort_root}/lib/libonnxruntime.so")
endif()

# cuDNN: the NVIDIA Windows installer places DLLs under a versioned subdirectory
# that is not on PATH.  Glob by CUDA major version and copy next to the executable.
if(WIN32 AND WITH_CUDA)
    file(GLOB _cudnn_dlls
        "C:/Program Files/NVIDIA/CUDNN/*/bin/${CUDAToolkit_VERSION_MAJOR}.*/x64/cudnn*.dll")
    if(_cudnn_dlls)
        # cuDNN is part of the GPU runtime → "cuda" component. Keep the dev-tree
        # copy: unlike the CUDA toolkit DLLs, cuDNN's versioned install dir is not
        # on PATH, so the dev build needs them next to the executable.
        pp_win_bundle_dll(cuda ${_cudnn_dlls})
        message(STATUS "cuDNN DLLs: ${_cudnn_dlls}")
    else()
        message(WARNING "cuDNN DLLs not found under "
            "C:/Program Files/NVIDIA/CUDNN/*/bin/${CUDAToolkit_VERSION_MAJOR}.*/x64/ — "
            "CUDA EP will fail at runtime. Install cuDNN 9 and reconfigure.")
    endif()
endif()

# CUDA toolkit runtime: the ORT CUDA EP imports versioned cuBLAS/cuFFT/cudart DLLs
# the first time a model runs. On the dev box these are on the system (Machine)
# PATH, so they are NOT copied into the dev tree — but a target machine may have
# only the NVIDIA driver. Bundle them for packaging in the separately-distributed
# "cuda" component (install-only; cuDNN above completes that component). These are
# the large (~hundreds of MB each) libraries that change only with the CUDA
# version, so isolating them keeps routine app updates small.
if(WIN32 AND WITH_CUDA AND CUDAToolkit_FOUND)
    # CUDA 12 keeps these in bin/; CUDA 13 moved them to bin/x64/. Glob both.
    file(GLOB _cuda_rt_dlls
        "${CUDAToolkit_BIN_DIR}/cudart64_*.dll"
        "${CUDAToolkit_BIN_DIR}/cublas64_*.dll"
        "${CUDAToolkit_BIN_DIR}/cublasLt64_*.dll"
        "${CUDAToolkit_BIN_DIR}/cufft64_*.dll"
        "${CUDAToolkit_BIN_DIR}/x64/cudart64_*.dll"
        "${CUDAToolkit_BIN_DIR}/x64/cublas64_*.dll"
        "${CUDAToolkit_BIN_DIR}/x64/cublasLt64_*.dll"
        "${CUDAToolkit_BIN_DIR}/x64/cufft64_*.dll")
    if(_cuda_rt_dlls)
        install(FILES ${_cuda_rt_dlls}
                DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT cuda)
        message(STATUS "CUDA runtime (cuda component): ${_cuda_rt_dlls}")
    else()
        message(WARNING "CUDA runtime DLLs not found in ${CUDAToolkit_BIN_DIR} — "
            "the cuda component will be incomplete; GPU EP would rely on system PATH.")
    endif()
endif()

set(_ort_ep_list "CPU(fallback)")
if(WITH_COREML AND APPLE AND CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64")
    list(PREPEND _ort_ep_list "CoreML")
endif()
if(WITH_CUDA AND NOT APPLE)
    list(PREPEND _ort_ep_list "CUDA")
endif()
list(JOIN _ort_ep_list "+" _ort_ep_str)
message(STATUS "ONNX Runtime ${ORT_VERSION}: ${_ort_root} [EP=${_ort_ep_str}]")

# ── ONNX Runtime GenAI (local LLM engine) ────────────────────────────────────
# Separate from the main ORT download; ships its own bundled libonnxruntime.so
# (different version) which coexists safely due to distinct sonames.
option(WITH_ORTGENAI "Enable ONNX Runtime GenAI local LLM engine" ON)
if(APPLE AND NOT CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64" AND WITH_ORTGENAI)
    # ORT-GenAI dropped Intel macOS prebuilts after v0.11.4; v0.13.x is arm64-only.
    # LocalLlmEngine falls back to Gemini when built without HAVE_ORTGENAI.
    message(STATUS "ONNX Runtime GenAI: no Intel macOS prebuilt — disabling (local LLM falls back to Gemini)")
    set(WITH_ORTGENAI OFF CACHE BOOL "" FORCE)
endif()
if(WITH_ORTGENAI)
    set(ORTGENAI_VERSION "0.13.1")

    if(WIN32)
        if(WITH_CUDA)
            set(_ortgenai_url "https://github.com/microsoft/onnxruntime-genai/releases/download/v${ORTGENAI_VERSION}/onnxruntime-genai-${ORTGENAI_VERSION}-win-x64-cuda.zip")
        else()
            set(_ortgenai_url "https://github.com/microsoft/onnxruntime-genai/releases/download/v${ORTGENAI_VERSION}/onnxruntime-genai-${ORTGENAI_VERSION}-win-x64.zip")
        endif()
    elseif(APPLE)
        # No CUDA on macOS; CoreML acceleration is handled internally by ORT-GenAI.
        set(_ortgenai_url "https://github.com/microsoft/onnxruntime-genai/releases/download/v${ORTGENAI_VERSION}/onnxruntime-genai-${ORTGENAI_VERSION}-osx-arm64.tar.gz")
    else()  # Linux
        if(WITH_CUDA)
            set(_ortgenai_url "https://github.com/microsoft/onnxruntime-genai/releases/download/v${ORTGENAI_VERSION}/onnxruntime-genai-${ORTGENAI_VERSION}-linux-x64-cuda.tar.gz")
        else()
            set(_ortgenai_url "https://github.com/microsoft/onnxruntime-genai/releases/download/v${ORTGENAI_VERSION}/onnxruntime-genai-${ORTGENAI_VERSION}-linux-x64.tar.gz")
        endif()
    endif()

    FetchContent_Declare(onnxruntime_genai URL "${_ortgenai_url}" DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
    FetchContent_MakeAvailable(onnxruntime_genai)

    if(EXISTS "${onnxruntime_genai_SOURCE_DIR}/include/ort_genai.h")
        set(_ortgenai_root "${onnxruntime_genai_SOURCE_DIR}")
    else()
        file(GLOB _ortgenai_candidates LIST_DIRECTORIES true "${onnxruntime_genai_SOURCE_DIR}/onnxruntime-genai-*")
        if(_ortgenai_candidates)
            list(GET _ortgenai_candidates 0 _ortgenai_root)
        else()
            set(_ortgenai_root "${onnxruntime_genai_SOURCE_DIR}")
        endif()
    endif()

    target_include_directories(PinPointStudio PRIVATE "${_ortgenai_root}/include")
    target_compile_definitions(PinPointStudio PRIVATE HAVE_ORTGENAI)

    if(WIN32)
        target_link_libraries(PinPointStudio PRIVATE "${_ortgenai_root}/lib/onnxruntime-genai.lib")
        file(GLOB _ortgenai_dlls "${_ortgenai_root}/lib/onnxruntime-genai*.dll")
        pp_win_bundle_dll(core ${_ortgenai_dlls})
    elseif(APPLE)
        file(GLOB _ortgenai_dylib "${_ortgenai_root}/lib/libonnxruntime-genai*.dylib")
        list(GET _ortgenai_dylib 0 _ortgenai_dylib_path)
        target_link_libraries(PinPointStudio PRIVATE "${_ortgenai_dylib_path}")
    else()  # Linux
        target_link_libraries(PinPointStudio PRIVATE "${_ortgenai_root}/lib/libonnxruntime-genai.so")
        # Deploy ORT-GenAI's bundled ORT alongside the app (distinct soname from main ORT).
        file(GLOB _ortgenai_rt_libs "${_ortgenai_root}/lib/libonnxruntime*.so*")
        foreach(_lib ${_ortgenai_rt_libs})
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_if_different "${_lib}" "$<TARGET_FILE_DIR:PinPointStudio>"
            )
        endforeach()
        foreach(_lib ${_ortgenai_rt_libs})
            install(FILES "${_lib}" DESTINATION lib)
        endforeach()
    endif()

    message(STATUS "ONNX Runtime GenAI ${ORTGENAI_VERSION}: ${_ortgenai_root}")
endif()

# ── MoveNet (pose estimation via ONNX Runtime) ────────────────────────────────
# Downloads MoveNet Lightning (~9 MB, 192×192) and Thunder (~30 MB, 256×256)
# SinglePose ONNX models from Hugging Face.
# No additional inference library required — ONNX Runtime (above) handles it.
# Cached in _deps/movenet/ and reused across reconfigures; only lost on a full
# build-directory wipe.
#
# Lightning input:  [1, 192, 192, 3] int32 NHWC, raw pixel values [0, 255]
# Thunder  input:   [1, 256, 256, 3] int32 NHWC, raw pixel values [0, 255]
# Both outputs:     [1, 1, 17, 3]    float32, keypoints as (y, x, score)

set(_movenet_model_dir "${CMAKE_BINARY_DIR}/_deps/movenet")
file(MAKE_DIRECTORY "${_movenet_model_dir}")

# ── Lightning ────────────────────────────────────────────────────────────────
set(_movenet_lightning_file "movenet_singlepose_lightning.onnx")
set(_movenet_lightning_path "${_movenet_model_dir}/${_movenet_lightning_file}")

if(NOT EXISTS "${_movenet_lightning_path}")
    message(STATUS "MoveNet: downloading Lightning model (~9 MB)...")
    file(DOWNLOAD
        "https://huggingface.co/Xenova/movenet-singlepose-lightning/resolve/main/onnx/model.onnx"
        "${_movenet_lightning_path}"
        SHOW_PROGRESS
        TLS_VERIFY ON
        STATUS _movenet_dl_status
    )
    list(GET _movenet_dl_status 0 _movenet_dl_code)
    if(NOT _movenet_dl_code EQUAL 0)
        list(GET _movenet_dl_status 1 _movenet_dl_msg)
        message(WARNING "MoveNet: Lightning download failed (${_movenet_dl_msg}) -- pose estimation disabled")
        file(REMOVE "${_movenet_lightning_path}")
    endif()
endif()

# ── Thunder ──────────────────────────────────────────────────────────────────
set(_movenet_thunder_file "movenet_singlepose_thunder.onnx")
set(_movenet_thunder_path "${_movenet_model_dir}/${_movenet_thunder_file}")

if(NOT EXISTS "${_movenet_thunder_path}")
    message(STATUS "MoveNet: downloading Thunder model (~30 MB)...")
    file(DOWNLOAD
        "https://huggingface.co/Xenova/movenet-singlepose-thunder/resolve/main/onnx/model.onnx"
        "${_movenet_thunder_path}"
        SHOW_PROGRESS
        TLS_VERIFY ON
        STATUS _movenet_dl_status
    )
    list(GET _movenet_dl_status 0 _movenet_dl_code)
    if(NOT _movenet_dl_code EQUAL 0)
        list(GET _movenet_dl_status 1 _movenet_dl_msg)
        message(WARNING "MoveNet: Thunder download failed (${_movenet_dl_msg}) -- Thunder model unavailable")
        file(REMOVE "${_movenet_thunder_path}")
    endif()
endif()

# ── Enable pose estimation if Lightning is available ─────────────────────────
if(EXISTS "${_movenet_lightning_path}")
    message(STATUS "MoveNet Lightning: model ready (${_movenet_lightning_path})")
    target_compile_definitions(PinPointStudio PRIVATE
        HAVE_MOVENET
        MOVENET_LIGHTNING_FILE="${_movenet_lightning_file}"
    )

    if(EXISTS "${_movenet_thunder_path}")
        message(STATUS "MoveNet Thunder:   model ready (${_movenet_thunder_path})")
        target_compile_definitions(PinPointStudio PRIVATE
            HAVE_MOVENET_THUNDER
            MOVENET_THUNDER_FILE="${_movenet_thunder_file}"
        )
    else()
        message(STATUS "MoveNet Thunder:   model unavailable -- selector will show Lightning only")
    endif()

    # Copy model(s) into the platform-appropriate location alongside the executable.
    if(APPLE)
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E make_directory
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_movenet_lightning_path}"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/${_movenet_lightning_file}"
            COMMENT "Bundling MoveNet Lightning model into app"
        )
        if(EXISTS "${_movenet_thunder_path}")
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_if_different
                    "${_movenet_thunder_path}"
                    "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/${_movenet_thunder_file}"
                COMMENT "Bundling MoveNet Thunder model into app"
            )
        endif()
    else()
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E make_directory
                "$<TARGET_FILE_DIR:PinPointStudio>/models"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_movenet_lightning_path}"
                "$<TARGET_FILE_DIR:PinPointStudio>/models/${_movenet_lightning_file}"
            COMMENT "Copying MoveNet Lightning model to output directory"
        )
        install(FILES "${_movenet_lightning_path}"
                DESTINATION "${CMAKE_INSTALL_BINDIR}/models" COMPONENT core)
        if(EXISTS "${_movenet_thunder_path}")
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_if_different
                    "${_movenet_thunder_path}"
                    "$<TARGET_FILE_DIR:PinPointStudio>/models/${_movenet_thunder_file}"
                COMMENT "Copying MoveNet Thunder model to output directory"
            )
            install(FILES "${_movenet_thunder_path}"
                    DESTINATION "${CMAKE_INSTALL_BINDIR}/models" COMPONENT core)
        endif()
    endif()
else()
    message(STATUS "MoveNet: Lightning model unavailable -- pose estimation disabled")
endif()

if(WITH_MEDIAPIPE)
# ── MediaPipe Pose (two-model BlazePose pipeline from Qualcomm AI Hub) ────────
# The ONNX models cannot be downloaded directly (Qualcomm distributes them as
# device-specific compiled artefacts, not as plain HTTP files).  cmake exports
# them locally via the qai-hub-models Python package.
#
# cmake will try this automatically if Python3 + qai-hub-models are importable
# in the current environment (including an active venv).  If not, it writes a
# helper script and prints instructions:
#
#   python3 -m venv .venv
#   source .venv/bin/activate          # Windows: .venv\Scripts\activate
#   pip install qai-hub-models torch onnxscript
#   python3 <build>/_deps/mediapipe/export_mediapipe_pose.py \
#           <build>/_deps/mediapipe
#   cmake ..      ← re-run to pick up the exported models
#
# Detector input:  [1, 3, 128, 128] float32 NCHW, RGB, normalised [0,1]
# Detector output: 4 tensors — scores×2 + boxes×2, split by stride level
#   [1, 512, 1], [1, 384, 1] scores; [1, 512, 12], [1, 384, 12] boxes
#   896 total anchors (512 at stride-8, 384 at stride-16)
#
# Landmark input:  [1, 3, 256, 256] float32 NCHW, RGB, normalised [0,1]
# Landmark output: flag [1] + landmarks [1, 31, 4] (x,y,z,vis normalised [0,1])
#   + heatmap [1, 128, 128] (ignored)

set(_mediapipe_model_dir "${CMAKE_BINARY_DIR}/_deps/mediapipe")
file(MAKE_DIRECTORY "${_mediapipe_model_dir}")

set(_mediapipe_detector_file "MediaPipePoseDetector.onnx")
set(_mediapipe_landmark_file "MediaPipePoseLandmarkDetector.onnx")
set(_mediapipe_detector_path "${_mediapipe_model_dir}/${_mediapipe_detector_file}")
set(_mediapipe_landmark_path "${_mediapipe_model_dir}/${_mediapipe_landmark_file}")

# ── Write the export helper so the user can run it manually if cmake can't. ──
set(_mediapipe_export_script "${_mediapipe_model_dir}/export_mediapipe_pose.py")
file(WRITE "${_mediapipe_export_script}" [=[
#!/usr/bin/env python3
"""
Export MediaPipe BlazePose detector + landmark models to ONNX.

Usage:
    python3 export_mediapipe_pose.py <output_dir>

Requirements:
    pip install qai-hub-models torch onnxscript
    (Python >=3.10, <3.14 required by qai-hub-models)

Output shapes (confirmed from qai_hub_models 0.53.x):
  Detector  input : [1, 3, 128, 128]
  Detector  output: 4 tensors — [1,512,12], [1,384,12] boxes,
                                [1,512,1],  [1,384,1]  scores
  Landmark  input : [1, 3, 256, 256]
  Landmark  output: flag [1], landmarks [1,31,4] (x,y,z,vis), heatmap [1,128,128]
"""
import builtins
import sys
import pathlib
import traceback


def main() -> int:
    output_dir = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
    output_dir.mkdir(parents=True, exist_ok=True)

    det_path = output_dir / "MediaPipePoseDetector.onnx"
    lm_path  = output_dir / "MediaPipePoseLandmarkDetector.onnx"

    if det_path.exists() and lm_path.exists():
        print(f"Models already present in {output_dir}")
        return 0

    # ── Check dependencies ────────────────────────────────────────────────────
    try:
        import torch
    except ImportError:
        print("ERROR: torch not installed.  Run: pip install torch", file=sys.stderr)
        return 1

    try:
        import onnxscript  # noqa: F401  required by newer torch.onnx
    except ImportError:
        print("ERROR: onnxscript not installed.  Run: pip install onnxscript",
              file=sys.stderr)
        return 1

    try:
        from qai_hub_models.models.mediapipe_pose.model import (
            PoseDetector, PoseLandmarkDetector)
    except ImportError:
        print("ERROR: qai_hub_models not installed.", file=sys.stderr)
        print("  Run: pip install qai-hub-models", file=sys.stderr)
        return 1

    # ── Download weights ──────────────────────────────────────────────────────
    # qai-hub-models may interactively ask permission to clone MediaPipePyTorch.
    # Auto-accept by patching builtins.input before the import/load calls.
    _real_input = builtins.input
    builtins.input = lambda *a, **kw: "y"

    print("Loading MediaPipe Pose weights (may clone a repo + download on first run)...")
    try:
        det_model = PoseDetector.from_pretrained()
        lm_model  = PoseLandmarkDetector.from_pretrained()
    except Exception as exc:
        builtins.input = _real_input
        print(f"ERROR: from_pretrained() failed: {exc}", file=sys.stderr)
        traceback.print_exc(file=sys.stderr)
        return 1
    finally:
        builtins.input = _real_input

    # The qai_hub_models wrappers expose the raw PyTorch model as .detector.
    detector = det_model.detector
    landmark = lm_model.detector
    detector.eval()
    landmark.eval()

    # torch.onnx.export with the new exporter (PyTorch >= 2.x) writes an
    # external .data sidecar when the model is large.  We immediately merge
    # it back into a single self-contained file using onnx.save_model so
    # cmake only needs to copy one file per model.
    try:
        import onnx as _onnx
    except ImportError:
        print("ERROR: onnx not installed.  Run: pip install onnx onnxscript",
              file=sys.stderr)
        return 1

    def _export_and_merge(net, dummy_input, out_path):
        torch.onnx.export(
            net, dummy_input, str(out_path),
            opset_version=18,
            input_names=["image"],
            do_constant_folding=True,
        )
        # Merge external data sidecar (if any) into a single self-contained file.
        data_file = out_path.parent / (out_path.name + ".data")
        if data_file.exists():
            model = _onnx.load(str(out_path))
            _onnx.save_model(model, str(out_path), save_as_external_data=False)
            data_file.unlink()
        print(f"  -> {out_path}  ({out_path.stat().st_size // 1024} KB, self-contained)")

    # ── Export detector [1,3,128,128] ─────────────────────────────────────────
    print("Exporting detector (BlazePose person detector, 128x128 input)...")
    try:
        _export_and_merge(detector, torch.zeros(1, 3, 128, 128), det_path)
    except Exception as exc:
        print(f"ERROR: detector export failed: {exc}", file=sys.stderr)
        traceback.print_exc(file=sys.stderr)
        return 1

    # ── Export landmark detector [1,3,256,256] ────────────────────────────────
    print("Exporting landmark detector (BlazePose landmark, 256x256 input)...")
    try:
        _export_and_merge(landmark, torch.zeros(1, 3, 256, 256), lm_path)
    except Exception as exc:
        print(f"ERROR: landmark export failed: {exc}", file=sys.stderr)
        traceback.print_exc(file=sys.stderr)
        return 1

    print("Export complete.")
    return 0


if __name__ == "__main__":
    sys.exit(main())
]=])

# ── Try the automatic export if the models are not already present ────────────
if(NOT EXISTS "${_mediapipe_detector_path}" OR NOT EXISTS "${_mediapipe_landmark_path}")

    # qai-hub-models requires Python >=3.10, <3.14.
    # Search order: active venv → in-tree venv → specific minor versions (so a
    # compatible version is preferred over an incompatible system python3) →
    # bare python3/python fallback.
    find_program(_mp_python
        NAMES python3.13 python3.12 python3.11 python3.10 python3 python
        HINTS
            "$ENV{VIRTUAL_ENV}/bin"
            "$ENV{VIRTUAL_ENV}/Scripts"
            "${CMAKE_SOURCE_DIR}/.venv/bin"
            "${CMAKE_SOURCE_DIR}/.venv/Scripts"
            "${CMAKE_SOURCE_DIR}/venv/bin"
            "${CMAKE_SOURCE_DIR}/venv/Scripts"
            "${CMAKE_BINARY_DIR}/.venv/bin"
            "${CMAKE_BINARY_DIR}/.venv/Scripts"
            "${CMAKE_BINARY_DIR}/venv/bin"
            "${CMAKE_BINARY_DIR}/venv/Scripts"
        NO_DEFAULT_PATH
    )
    if(NOT _mp_python)
        find_program(_mp_python
            NAMES python3.13 python3.12 python3.11 python3.10 python3 python)
    endif()

    if(_mp_python)
        # Get the version string for diagnostic messages.
        execute_process(
            COMMAND "${_mp_python}" --version
            OUTPUT_VARIABLE _py_ver_stdout  OUTPUT_STRIP_TRAILING_WHITESPACE
            ERROR_VARIABLE  _py_ver_stderr  ERROR_STRIP_TRAILING_WHITESPACE
        )
        if(_py_ver_stdout)
            set(_py_ver "${_py_ver_stdout}")
        else()
            set(_py_ver "${_py_ver_stderr}")  # Python <3.4 printed to stderr
        endif()

        # Check compatibility: qai-hub-models requires >=3.10, <3.14.
        execute_process(
            COMMAND "${_mp_python}" -c
                "import sys; v=sys.version_info; sys.exit(0 if (3,10)<=v<(3,14) else 1)"
            RESULT_VARIABLE _py_compat
            OUTPUT_QUIET ERROR_QUIET
        )

        if(NOT _py_compat EQUAL 0)
            message(STATUS "MediaPipe: ${_py_ver} at ${_mp_python} is not compatible")
            message(STATUS "  qai-hub-models requires Python >=3.10, <3.14")
            message(STATUS "  Install a compatible Python then create a venv and re-run cmake:")
            message(STATUS "    # Ubuntu/Debian:")
            message(STATUS "    sudo add-apt-repository ppa:deadsnakes/ppa")
            message(STATUS "    sudo apt install python3.12 python3.12-venv")
            message(STATUS "    python3.12 -m venv .venv && source .venv/bin/activate")
            message(STATUS "    pip install qai-hub-models torch onnxscript && cmake ..")
            message(STATUS "    # macOS:  brew install python@3.12")
            message(STATUS "    # Windows: winget install Python.Python.3.12")
        else()
            # Version is compatible — check whether qai_hub_models is importable.
            execute_process(
                COMMAND "${_mp_python}" -c "import qai_hub_models"
                RESULT_VARIABLE _qhm_available
                OUTPUT_QUIET ERROR_QUIET
            )

            if(_qhm_available EQUAL 0)
                message(STATUS
                    "MediaPipe: exporting via qai-hub-models using ${_py_ver}"
                    " (may download ~150 MB on first run)...")
                execute_process(
                    COMMAND "${_mp_python}" "${_mediapipe_export_script}"
                            "${_mediapipe_model_dir}"
                    RESULT_VARIABLE _mp_result
                    OUTPUT_VARIABLE _mp_out
                    ERROR_VARIABLE  _mp_err
                )
                if(_mp_result EQUAL 0)
                    message(STATUS "MediaPipe: export succeeded")
                    if(_mp_out)
                        message(STATUS "${_mp_out}")
                    endif()
                else()
                    message(WARNING
                        "MediaPipe: export failed (exit ${_mp_result}).\n"
                        "${_mp_err}\n"
                        "Fix the error above then run manually:\n"
                        "  ${_mp_python} ${_mediapipe_export_script}"
                        " ${_mediapipe_model_dir}\n"
                        "and re-run cmake."
                    )
                endif()
            else()
                message(STATUS
                    "MediaPipe: qai-hub-models not installed in ${_py_ver}"
                    " — skipping auto-export")
                message(STATUS
                    "  Activate a venv (or install into ${_mp_python}) and re-run cmake:")
                message(STATUS
                    "    pip install qai-hub-models torch onnxscript && cmake ..")
                message(STATUS "  Or create a fresh venv first:")
                message(STATUS
                    "    python3.11 -m venv .venv && source .venv/bin/activate"
                    "  # Windows: .venv\\Scripts\\activate")
                message(STATUS
                    "    pip install qai-hub-models torch onnxscript && cmake ..")
            endif()
        endif()
    else()
        message(STATUS "MediaPipe: no Python found — skipping auto-export")
        message(STATUS "  Install Python 3.12 (or 3.10–3.13) and re-run cmake:")
        message(STATUS "    # Ubuntu/Debian:")
        message(STATUS "    sudo add-apt-repository ppa:deadsnakes/ppa")
        message(STATUS "    sudo apt install python3.12 python3.12-venv")
        message(STATUS "    python3.12 -m venv .venv && source .venv/bin/activate")
        message(STATUS "    pip install qai-hub-models torch onnxscript && cmake ..")
        message(STATUS "    # macOS:  brew install python@3.12 && ...")
        message(STATUS "    # Windows: winget install Python.Python.3.12 && ...")
    endif()

endif() # NOT EXISTS both models

if(EXISTS "${_mediapipe_detector_path}" AND EXISTS "${_mediapipe_landmark_path}")
    message(STATUS "MediaPipe Pose: models ready")
    target_compile_definitions(PinPointStudio PRIVATE
        HAVE_MEDIAPIPE
        MEDIAPIPE_DETECTOR_FILE="${_mediapipe_detector_file}"
        MEDIAPIPE_LANDMARK_FILE="${_mediapipe_landmark_file}"
    )

    if(APPLE)
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_mediapipe_detector_path}"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/${_mediapipe_detector_file}"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_mediapipe_landmark_path}"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/${_mediapipe_landmark_file}"
            COMMENT "Bundling MediaPipe Pose models into app"
        )
    else()
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_mediapipe_detector_path}"
                "$<TARGET_FILE_DIR:PinPointStudio>/models/${_mediapipe_detector_file}"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_mediapipe_landmark_path}"
                "$<TARGET_FILE_DIR:PinPointStudio>/models/${_mediapipe_landmark_file}"
            COMMENT "Copying MediaPipe Pose models to output directory"
        )
        install(FILES "${_mediapipe_detector_path}" "${_mediapipe_landmark_path}"
                DESTINATION "${CMAKE_INSTALL_BINDIR}/models" COMPONENT core)
    endif()
else()
    message(STATUS "MediaPipe Pose: models unavailable -- MediaPipe option disabled")
endif()

endif() # WITH_MEDIAPIPE

# ── Person segmenter (background suppression before MoveNet) ─────────────────
# Downloads the MediaPipe Selfie Segmentation ONNX model (~480 KB).
# Runs before MoveNet in the Film tab to isolate the subject so background
# people do not corrupt the pose estimate.
#
# Input:  [1, 3, 320, 320] float32 NCHW, ImageNet-normalised
# Output: 7 side outputs; "d0" is the final salient-object mask [0,1]

set(_seg_model_dir  "${CMAKE_BINARY_DIR}/_deps/segmenter")
set(_seg_model_file "u2netp.onnx")
set(_seg_model_path "${_seg_model_dir}/${_seg_model_file}")
file(MAKE_DIRECTORY "${_seg_model_dir}")

if(NOT EXISTS "${_seg_model_path}")
    message(STATUS "Segmenter: downloading u2netp person segmentation model (~4.7 MB)...")
    file(DOWNLOAD
        "https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2netp.onnx"
        "${_seg_model_path}"
        SHOW_PROGRESS TLS_VERIFY ON STATUS _seg_dl_status)
    list(GET _seg_dl_status 0 _seg_dl_code)
    if(NOT _seg_dl_code EQUAL 0)
        list(GET _seg_dl_status 1 _seg_dl_msg)
        message(WARNING "Segmenter: download failed (${_seg_dl_msg}) -- background suppression disabled")
        file(REMOVE "${_seg_model_path}")
    endif()
endif()

if(EXISTS "${_seg_model_path}")
    message(STATUS "Segmenter: model ready (${_seg_model_path})")
    target_compile_definitions(PinPointStudio PRIVATE
        HAVE_SEGMENTER
        SEGMENTER_MODEL_FILE="${_seg_model_file}"
    )
    if(APPLE)
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_seg_model_path}"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/${_seg_model_file}"
            COMMENT "Bundling segmenter model into app"
        )
    else()
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_seg_model_path}"
                "$<TARGET_FILE_DIR:PinPointStudio>/models/${_seg_model_file}"
            COMMENT "Copying segmenter model to output directory"
        )
        install(FILES "${_seg_model_path}"
                DESTINATION "${CMAKE_INSTALL_BINDIR}/models" COMPONENT core)
    endif()
    # The segmenter stands alone (the address-marks stage reads it with or without MoveNet).
    target_sources(PinPointStudio PRIVATE
        src/Pose/person_segmenter.h
        src/Pose/person_segmenter.cpp
    )
    message(STATUS "PersonSegmenter: enabled")
else()
    message(STATUS "Segmenter: model unavailable -- background suppression disabled")
endif()

# ── ViTPose-B (whole-body ONNX model) ────────────────────────────────────────
# Downloads the JunkyByte/easy_ViTPose whole-body model (~330 MB) at configure
# time, cached in _deps/vitpose/ so reconfigures do not re-download.
#
# Model I/O (confirmed from easy_ViTPose source):
#   Input:  [1, 3, 256, 192] float32 NCHW, RGB, ImageNet-normalised
#   Output: [1, 133, 64, 48] float32 heatmaps — COCO-WholeBody 133-keypoint format
#
# The C++ estimator currently consumes only the first 17 COCO body channels.
# See pose_estimator_vitpose.cpp for the note about 133-keypoint future support.

if(WITH_VITPOSE)
    set(_vitpose_model_dir  "${CMAKE_BINARY_DIR}/_deps/vitpose")
    set(_vitpose_model_file "vitpose-b-wholebody.onnx")
    set(_vitpose_model_path "${_vitpose_model_dir}/${_vitpose_model_file}")
    file(MAKE_DIRECTORY "${_vitpose_model_dir}")

    if(NOT EXISTS "${_vitpose_model_path}")
        message(STATUS "ViTPose: downloading vitpose-b-wholebody model (~330 MB)...")
        file(DOWNLOAD
            "https://huggingface.co/JunkyByte/easy_ViTPose/resolve/main/onnx/wholebody/vitpose-b-wholebody.onnx"
            "${_vitpose_model_path}"
            SHOW_PROGRESS TLS_VERIFY ON STATUS _vtp_dl_status)
        list(GET _vtp_dl_status 0 _vtp_dl_code)
        if(NOT _vtp_dl_code EQUAL 0)
            list(GET _vtp_dl_status 1 _vtp_dl_msg)
            message(WARNING "ViTPose: download failed (${_vtp_dl_msg}) -- ViTPose estimator disabled")
            file(REMOVE "${_vitpose_model_path}")
        endif()
    endif()

    if(EXISTS "${_vitpose_model_path}")
        message(STATUS "ViTPose: model ready (${_vitpose_model_path})")
        target_compile_definitions(PinPointStudio PRIVATE
            HAVE_VITPOSE
            VITPOSE_MODEL_FILE="${_vitpose_model_file}"
        )
        # The fp16 twin (tools/pose/convert_fp16.py writes it beside the fp32 file) rides along
        # when it exists: the Mac's CoreML MLProgram path runs fp16 by default
        # (pp_tuned_constants.h pose::kModelFp16) and falls back to fp32 with a log line without it.
        set(_vitpose_models "${_vitpose_model_path}")
        string(REGEX REPLACE "\\.onnx$" ".fp16.onnx" _vitpose_fp16_path "${_vitpose_model_path}")
        if(EXISTS "${_vitpose_fp16_path}")
            list(APPEND _vitpose_models "${_vitpose_fp16_path}")
            message(STATUS "ViTPose: fp16 model found, bundling it too")
        endif()
        if(APPLE)
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_if_different
                    ${_vitpose_models}
                    "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/"
                COMMENT "Bundling ViTPose model(s) into app"
            )
        else()
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_if_different
                    ${_vitpose_models}
                    "$<TARGET_FILE_DIR:PinPointStudio>/models/"
                COMMENT "Copying ViTPose model(s) to output directory"
            )
            install(FILES ${_vitpose_models}
                    DESTINATION "${CMAKE_INSTALL_BINDIR}/models" COMPONENT core)
        endif()
    else()
        message(STATUS "ViTPose: model unavailable -- estimator disabled")
    endif()
endif() # WITH_VITPOSE

# ── Whisper model (ggml-base.en.bin) ─────────────────────────────────────────
# Downloaded at configure time, cached in _deps/whisper-models/ so it survives
# reconfigures without re-downloading.  Copied to models/whisper/ next to the
# executable so STTProcessor finds it without any user setup.

set(_whisper_model_dir  "${CMAKE_BINARY_DIR}/_deps/whisper-models")
set(_whisper_model_file "ggml-base.en.bin")
set(_whisper_model_path "${_whisper_model_dir}/${_whisper_model_file}")
file(MAKE_DIRECTORY "${_whisper_model_dir}")

if(NOT EXISTS "${_whisper_model_path}")
    message(STATUS "Whisper: downloading ggml-base.en model (~148 MB)...")
    file(DOWNLOAD
        "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin"
        "${_whisper_model_path}"
        SHOW_PROGRESS
        TLS_VERIFY ON
        STATUS _whisper_dl_status
    )
    list(GET _whisper_dl_status 0 _whisper_dl_code)
    if(NOT _whisper_dl_code EQUAL 0)
        list(GET _whisper_dl_status 1 _whisper_dl_msg)
        message(WARNING "Whisper: model download failed (${_whisper_dl_msg}) — STT will use cloud fallback")
        file(REMOVE "${_whisper_model_path}")
    endif()
endif()

if(EXISTS "${_whisper_model_path}")
    message(STATUS "Whisper: model ready (${_whisper_model_path})")
    if(APPLE)
        # macOS: data must live under Resources/, NOT MacOS/ — a data file in
        # Contents/MacOS/ makes codesign treat it as unsigned nested code and the
        # bundle fails to sign/notarize. Mirrors the other models' Apple branches;
        # the STT resolver checks ../Resources/models/whisper/ (stt_processor.cpp).
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E make_directory
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/whisper"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_whisper_model_path}"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/models/whisper/${_whisper_model_file}"
            COMMENT "Bundling Whisper model into app (Resources/models/whisper)"
        )
    else()
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E make_directory
                "$<TARGET_FILE_DIR:PinPointStudio>/models/whisper"
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
                "${_whisper_model_path}"
                "$<TARGET_FILE_DIR:PinPointStudio>/models/whisper/${_whisper_model_file}"
            COMMENT "Copying Whisper model to output directory"
        )
        install(FILES "${_whisper_model_path}"
                DESTINATION "${CMAKE_INSTALL_BINDIR}/models/whisper" COMPONENT core)
    endif()
else()
    message(STATUS "Whisper: model unavailable — STT will use cloud fallback")
endif()

# ── yt-dlp (bundled binary for YouTube download in Film tab) ──────────────────
# Downloads the correct single-file yt-dlp binary for this platform at cmake
# configure time.  Cached in _deps/ytdlp/ so it survives reconfigures.
# The app locates it via YTDLP_BINARY_NAME next to the executable.

set(_ytdlp_dir "${CMAKE_BINARY_DIR}/_deps/ytdlp")
file(MAKE_DIRECTORY "${_ytdlp_dir}")

if(APPLE)
    set(_ytdlp_name "yt-dlp_macos")
    set(_ytdlp_url  "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos")
elseif(WIN32)
    set(_ytdlp_name "yt-dlp.exe")
    set(_ytdlp_url  "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe")
else()
    set(_ytdlp_name "yt-dlp")
    set(_ytdlp_url  "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp")
endif()
set(_ytdlp_path "${_ytdlp_dir}/${_ytdlp_name}")

if(NOT EXISTS "${_ytdlp_path}")
    message(STATUS "yt-dlp: downloading binary...")
    file(DOWNLOAD "${_ytdlp_url}" "${_ytdlp_path}"
        SHOW_PROGRESS TLS_VERIFY ON STATUS _ytdlp_dl_status)
    list(GET _ytdlp_dl_status 0 _ytdlp_dl_code)
    if(NOT _ytdlp_dl_code EQUAL 0)
        list(GET _ytdlp_dl_status 1 _ytdlp_dl_msg)
        message(WARNING "yt-dlp: download failed (${_ytdlp_dl_msg}) -- Film tab download unavailable")
        file(REMOVE "${_ytdlp_path}")
    elseif(NOT WIN32)
        file(CHMOD "${_ytdlp_path}"
            PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE
                        GROUP_READ GROUP_EXECUTE
                        WORLD_READ WORLD_EXECUTE)
    endif()
endif()

if(EXISTS "${_ytdlp_path}")
    message(STATUS "yt-dlp: ready (${_ytdlp_path})")
    target_compile_definitions(PinPointStudio PRIVATE
        HAVE_YTDLP
        YTDLP_BINARY_NAME="${_ytdlp_name}"
    )
    add_custom_command(TARGET PinPointStudio POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${_ytdlp_path}" "$<TARGET_FILE_DIR:PinPointStudio>/${_ytdlp_name}"
        COMMENT "Copying yt-dlp to output directory"
    )
    # install(PROGRAMS) sets the executable bit on non-Windows targets.
    install(PROGRAMS "${_ytdlp_path}"
            DESTINATION "${CMAKE_INSTALL_BINDIR}" RENAME "${_ytdlp_name}" COMPONENT core)
    if(NOT WIN32)
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND chmod +x "$<TARGET_FILE_DIR:PinPointStudio>/${_ytdlp_name}"
            COMMENT "Setting yt-dlp executable bit"
        )
    endif()
else()
    message(STATUS "yt-dlp: unavailable -- Film tab download disabled")
endif()

# ── espeak-ng ────────────────────────────────────────────────────────────────
find_package(PkgConfig QUIET)
if(PkgConfig_FOUND)
    pkg_check_modules(ESPEAK QUIET espeak-ng)
endif()

if(NOT ESPEAK_FOUND AND APPLE)
    # pkg-config is often absent on macOS; probe the Homebrew prefix directly.
    execute_process(
        COMMAND brew --prefix espeak-ng
        OUTPUT_VARIABLE _brew_espeak
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_QUIET
        RESULT_VARIABLE _brew_result
    )
    if(_brew_result EQUAL 0 AND EXISTS "${_brew_espeak}/lib/libespeak-ng.dylib")
        set(ESPEAK_FOUND     TRUE)
        set(ESPEAK_INCLUDE_DIRS "${_brew_espeak}/include")
        set(ESPEAK_LIBRARY_DIRS "${_brew_espeak}/lib")
        set(ESPEAK_LIBRARIES    "espeak-ng")
        set(ESPEAK_VERSION      "Homebrew")
    endif()
endif()

if(ESPEAK_FOUND)
    target_include_directories(PinPointStudio PRIVATE ${ESPEAK_INCLUDE_DIRS})
    target_link_libraries(PinPointStudio PRIVATE ${ESPEAK_LIBRARIES})
    target_link_directories(PinPointStudio PRIVATE ${ESPEAK_LIBRARY_DIRS})
    target_compile_definitions(PinPointStudio PRIVATE HAVE_ESPEAK_NG)
    message(STATUS "espeak-ng ${ESPEAK_VERSION}: system")

    if(APPLE)
        # PhonemeTokenizer.cpp passes <bundle>/Contents/Resources to espeak_Initialize
        # unconditionally on macOS, so the phoneme tables must be there even when we
        # link the *system* library — otherwise espeak fails with
        # "Error processing file '.../Resources/phontab'" and TTS never initialises.
        # Homebrew keeps them in <prefix>/share/espeak-ng-data; the source-built path
        # below does the equivalent copy from ${espeak_ng_BINARY_DIR}.
        find_path(ESPEAK_NG_DATA_DIR
            NAMES phontab
            HINTS "${ESPEAK_PREFIX}" "${_brew_espeak}" "${ESPEAK_LIBRARY_DIRS}/.."
            PATH_SUFFIXES espeak-ng-data share/espeak-ng-data
        )
        if(ESPEAK_NG_DATA_DIR)
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_directory
                    "${ESPEAK_NG_DATA_DIR}"
                    "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/espeak-ng-data"
                COMMENT "Bundling system espeak-ng data into app"
            )
            message(STATUS "espeak-ng data: ${ESPEAK_NG_DATA_DIR}")
        else()
            message(WARNING
                "espeak-ng data (phontab) not found near ${ESPEAK_PREFIX} — TTS will fail "
                "at runtime with \"Error processing file '.../Resources/phontab'\". "
                "Set -DESPEAK_NG_DATA_DIR=<dir containing phontab>.")
        endif()
    endif()
else()
    # 1.52.0 is the first espeak-ng release with a CMake build system.
    # PATCH_COMMAND changes the espeak-include link from PUBLIC to PRIVATE so
    # its compat/ shim directory does not leak into PinPointStudio's include path and
    # shadow system <wctype.h> on macOS.
    # EXCLUDE_FROM_ALL limits compilation to the library target only.
    FetchContent_Declare(
        espeak_ng
        GIT_REPOSITORY https://github.com/espeak-ng/espeak-ng.git
        GIT_TAG        1.52.0
        GIT_SHALLOW    TRUE
        EXCLUDE_FROM_ALL
        PATCH_COMMAND
            ${CMAKE_COMMAND}
            "-DFILE1=${CMAKE_BINARY_DIR}/_deps/espeak_ng-src/src/CMakeLists.txt"
            "-DFILE2=${CMAKE_BINARY_DIR}/_deps/espeak_ng-src/src/libespeak-ng/CMakeLists.txt"
            "-DFILE3=${CMAKE_BINARY_DIR}/_deps/espeak_ng-src/CMakeLists.txt"
            -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/PatchEspeakNg.cmake"
    )
    set(ESPEAK_BUILD_MANPAGES OFF CACHE BOOL "" FORCE)
    FetchContent_MakeAvailable(espeak_ng)
    target_link_libraries(PinPointStudio PRIVATE espeak-ng)
    target_include_directories(PinPointStudio PRIVATE "${espeak_ng_SOURCE_DIR}/src/include")
    target_compile_definitions(PinPointStudio PRIVATE HAVE_ESPEAK_NG)

    # espeak-ng's own `data` target (defined in cmake/data.cmake) compiles the
    # phoneme tables and language dictionaries using espeak-ng-bin as a
    # build-time tool.  Depending on it directly avoids cross-directory
    # custom-command scoping issues.
    add_dependencies(PinPointStudio data)

    if(APPLE)
        # Bundle the compiled data (+ lang/ and voices/ copied at configure time
        # by data.cmake) into the macOS app so espeak_Initialize can find it.
        add_custom_command(TARGET PinPointStudio POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_directory
                "${espeak_ng_BINARY_DIR}/espeak-ng-data"
                "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/espeak-ng-data"
            COMMENT "Bundling espeak-ng data into app"
        )
    else()
        # On Linux (and Windows) building from source, the compiled-in PKGDATADIR
        # won't match the build tree.  Pass the actual build-dir path so
        # espeak_Initialize can find the phoneme tables at runtime (dev fallback).
        target_compile_definitions(PinPointStudio PRIVATE
            ESPEAK_DATA_PATH="${espeak_ng_BINARY_DIR}")

        if(WIN32)
            # ESPEAK_DATA_PATH points into the build tree, which does not exist on
            # an installed machine. Copy espeak-ng-data next to the executable so
            # the runtime (PhonemeTokenizer) can resolve it relative to the exe,
            # and install it for packaging. The `data` target dependency above
            # guarantees the compiled tables exist before this POST_BUILD copy.
            add_custom_command(TARGET PinPointStudio POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E copy_directory
                    "${espeak_ng_BINARY_DIR}/espeak-ng-data"
                    "$<TARGET_FILE_DIR:PinPointStudio>/espeak-ng-data"
                COMMENT "Copying espeak-ng data next to the executable"
            )
            install(DIRECTORY "${espeak_ng_BINARY_DIR}/espeak-ng-data"
                    DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT core)
        endif()
    endif()

    message(STATUS "espeak-ng 1.52.0: built from source")
endif()

# ── Aravis (Industrial Camera Support) ──────────────────────────────────────
find_package(PkgConfig QUIET)
if(PkgConfig_FOUND)
    pkg_check_modules(ARAVIS aravis-0.8)
endif()

if(NOT ARAVIS_FOUND)
    if(APPLE)
        # Probe Homebrew directly as a fallback
        execute_process(
            COMMAND brew --prefix aravis
            OUTPUT_VARIABLE _brew_aravis
            OUTPUT_STRIP_TRAILING_WHITESPACE
            ERROR_QUIET
            RESULT_VARIABLE _brew_result
        )
        if(_brew_result EQUAL 0 AND EXISTS "${_brew_aravis}/lib/libaravis-0.8.dylib")
            set(ARAVIS_FOUND        TRUE)
            set(ARAVIS_INCLUDE_DIRS "${_brew_aravis}/include/aravis-0.8")
            set(ARAVIS_LIBRARY_DIRS "${_brew_aravis}/lib")
            set(ARAVIS_LIBRARIES    "aravis-0.8")
            set(ARAVIS_VERSION      "Homebrew")
        endif()
    elseif(WIN32)
        # Manual search fallback for Windows
        find_path(ARAVIS_INCLUDE_DIRS NAMES arv.h PATH_SUFFIXES aravis-0.8 HINTS ${ARAVIS_ROOT} $ENV{ARAVIS_ROOT})
        find_library(ARAVIS_LIBRARIES NAMES aravis-0.8 HINTS ${ARAVIS_ROOT} $ENV{ARAVIS_ROOT})
        if(ARAVIS_INCLUDE_DIRS AND ARAVIS_LIBRARIES)
            set(ARAVIS_FOUND TRUE)
            set(ARAVIS_VERSION "Manual")
        endif()
    endif()
endif()

if(ARAVIS_FOUND)
    message(STATUS "Aravis ${ARAVIS_VERSION}: found")
    target_compile_definitions(PinPointStudio PRIVATE HAVE_ARAVIS)
    target_include_directories(PinPointStudio PRIVATE ${ARAVIS_INCLUDE_DIRS})
    target_link_libraries(PinPointStudio PRIVATE ${ARAVIS_LIBRARIES})
    if(ARAVIS_LIBRARY_DIRS)
        target_link_directories(PinPointStudio PRIVATE ${ARAVIS_LIBRARY_DIRS})
    endif()
    
    # Aravis depends on GLib, GObject, and GIO. pkg-config usually handles this,
    # but for manual/brew fallbacks we need to ensure they are available.
    if(PkgConfig_FOUND)
        pkg_check_modules(GLIB REQUIRED glib-2.0 gobject-2.0 gio-2.0)
        target_include_directories(PinPointStudio PRIVATE ${GLIB_INCLUDE_DIRS})
        target_link_libraries(PinPointStudio PRIVATE ${GLIB_LIBRARIES})
    endif()
else()
    message(STATUS "Aravis 0.8: not found (industrial camera support disabled)")
endif()

# ── Spinnaker (High-Speed Camera Support, Windows Only) ──────────────────────
if(WIN32)
    set(SPINNAKER_ROOT "C:/Program Files/Teledyne/Spinnaker")
    find_path(SPINNAKER_INCLUDE_DIRS NAMES Spinnaker.h HINTS ${SPINNAKER_ROOT}/include)
    find_library(SPINNAKER_LIBRARIES NAMES Spinnaker_v140 HINTS ${SPINNAKER_ROOT}/lib64/vs2015)

    if(SPINNAKER_INCLUDE_DIRS AND SPINNAKER_LIBRARIES)
        message(STATUS "Spinnaker: found at ${SPINNAKER_ROOT} (build-time headers + import lib; delay-loaded, not redistributed)")
        target_compile_definitions(PinPointStudio PRIVATE HAVE_SPINNAKER)
        target_include_directories(PinPointStudio PRIVATE ${SPINNAKER_INCLUDE_DIRS})
        target_link_libraries(PinPointStudio PRIVATE ${SPINNAKER_LIBRARIES})

        target_sources(PinPointStudio PRIVATE
            src/Video/VideoInputSpinnaker.h
            src/Video/VideoInputSpinnaker.cpp
            src/Video/spinnaker_runtime.h
            src/Video/spinnaker_runtime.cpp
            src/Video/spinnaker_settings.h
            src/Video/spinnaker_settings.cpp
        )

        # The Spinnaker SDK is proprietary and its EULA forbids redistributing it in
        # an installer, so we ship NONE of its DLLs. Instead the sole imported DLL is
        # delay-loaded: the build links the import lib (Spinnaker_v140.lib) for symbols,
        # but the DLL is only touched on first use. At runtime spinnaker_runtime.cpp
        # discovers a user-installed SDK, preloads Spinnaker_v140.dll (which pulls in
        # its GenICam/runtime siblings from the SDK folder), and gates every Spinnaker
        # entry point on that — so a machine without the SDK simply runs without the
        # high-speed camera backend instead of failing to launch. /DELAYLOAD auto-links
        # delayimp.lib (MSVC). Only Spinnaker_v140.dll is directly imported; its
        # dependencies load transitively.
        target_link_options(PinPointStudio PRIVATE "/DELAYLOAD:Spinnaker_v140.dll")
        target_link_libraries(PinPointStudio PRIVATE delayimp.lib)
    else()
        message(STATUS "Spinnaker: not found (high-speed camera support disabled)")
    endif()
endif()

# ── libudev (Linux V4L2 serial number lookup) ────────────────────────────────
if(UNIX AND NOT APPLE)
    if(PkgConfig_FOUND)
        pkg_check_modules(UDEV libudev)
    endif()
    if(NOT UDEV_FOUND)
        find_path(UDEV_INCLUDE_DIRS NAMES libudev.h)
        find_library(UDEV_LIBRARIES NAMES udev)
        if(UDEV_INCLUDE_DIRS AND UDEV_LIBRARIES)
            set(UDEV_FOUND TRUE)
        endif()
    endif()
    if(UDEV_FOUND)
        message(STATUS "libudev: found (V4L2 camera serial number lookup enabled)")
        target_compile_definitions(PinPointStudio PRIVATE HAVE_LIBUDEV)
        target_include_directories(PinPointStudio PRIVATE ${UDEV_INCLUDE_DIRS})
        target_link_libraries(PinPointStudio PRIVATE ${UDEV_LIBRARIES})
    else()
        message(STATUS "libudev: not found (V4L2 cameras will use device path as identifier)")
    endif()
endif()

if(WIN32)
    # cfgmgr32: device tree traversal to extract USB serial numbers for Qt Multimedia cameras.
    # dxgi:    per-process / per-adapter VRAM query for pp_gpu_metrics (IDXGIAdapter3).
    target_link_libraries(PinPointStudio PRIVATE cfgmgr32 dxgi)
endif()

# ── OpenCV ───────────────────────────────────────────────────────────────────
# macOS: inject Homebrew prefix so CMake can locate OpenCVConfig.cmake.
#
# The escape hatch for an OpenCV somewhere else: -DPP_OPENCV_NO_PIN=ON leaves OpenCV_DIR
# alone so -DOpenCV_DIR= is honoured. Without it the pin below wins on macOS, deliberately
# — a stale cache pointing into /opt/homebrew/lib is exactly the state that has to be
# repaired without anyone knowing to clear it.
option(PP_OPENCV_NO_PIN "Do not pin OpenCV_DIR to the Homebrew formula prefix (macOS)" OFF)
#
# Try the VERSIONED formula first. Homebrew's plain `opencv` formula is now 5.x, which
# reorganises calib3d into separate 3d/calib modules; this project targets 4.x and does
# not build against it. The version guard below only rejects < 3.0, so an OpenCV 5 prefix
# sails past configure and fails later at compile time, which is a much worse place to
# find out. opencv@4 is keg-only, so `brew --prefix opencv` cannot see it — it has to be
# asked for by name.
if(APPLE)
    foreach(_brew_formula opencv@4 opencv)
        execute_process(
            COMMAND brew --prefix ${_brew_formula}
            OUTPUT_VARIABLE _brew_opencv
            OUTPUT_STRIP_TRAILING_WHITESPACE
            ERROR_QUIET
            RESULT_VARIABLE _brew_result
        )
        if(_brew_result EQUAL 0 AND EXISTS "${_brew_opencv}")
            list(APPEND CMAKE_PREFIX_PATH "${_brew_opencv}")
            # ⚠ PINNED TO THE FORMULA'S OWN CONFIG DIR, NOT LEFT TO THE PREFIX SEARCH, AND THIS
            # IS NOT TIDINESS. Appending the prefix above is only a hint: find_package still
            # searches every prefix, and where opencv@4 has been linked into Homebrew's shared
            # lib tree it resolves to /opt/homebrew/lib/cmake/opencv4. OpenCV's config computes
            # its own prefix relative to that file, so every imported library then points at
            # /opt/homebrew/lib/libopencv_*.dylib — and THAT is what puts /opt/homebrew/lib on
            # this target's link line.
            #
            # Why a link directory matters at RUN time: Qt Creator derives DYLD_FRAMEWORK_PATH
            # for the run environment from the target's link libraries, and DYLD_FRAMEWORK_PATH
            # OUTRANKS the rpath baked into the binary. /opt/homebrew/lib also holds 63 Qt
            # frameworks — Homebrew's own Qt, pulled in as a dependency of opencv@4 and vtk, and
            # the SAME 6.11.1 version, so it loads happily rather than failing an ABI check.
            # QLibraryInfo then reports Homebrew's prefix and every plugin lookup goes there,
            # where there is no QtQuick3D and no QtMultimedia backend. It presents as
            #     module "QtQuick3D" plugin "qquick3dplugin" not found
            #     No QtMultimedia backends found
            # which names neither OpenCV nor a link path and reads as a broken Qt install.
            #
            # ⚠ AND IT IS INVISIBLE FROM A SHELL — launched directly the rpath wins and the app
            # is perfectly clean, so a terminal run cannot reproduce it. Bisected to this one
            # directory 2026-08-20; every other entry on that path was harmless.
            #
            # Pinning to <formula prefix>/lib/cmake/opencv4 keeps the resolved libraries inside
            # the formula's own tree, so /opt/homebrew/lib never reaches the link line and
            # Homebrew's Qt is never on the search path. -DPP_OPENCV_NO_PIN=ON opts out.
            if(NOT PP_OPENCV_NO_PIN AND EXISTS "${_brew_opencv}/lib/cmake/opencv4")
                set(OpenCV_DIR "${_brew_opencv}/lib/cmake/opencv4" CACHE PATH
                    "OpenCV config dir, pinned to the Homebrew formula (see CMakeLists)" FORCE)
                message(STATUS "OpenCV: pinned OpenCV_DIR to ${OpenCV_DIR} "
                               "(keeps /opt/homebrew/lib, and Homebrew's Qt, off the link line)")
            endif()
            message(STATUS "OpenCV: using Homebrew formula '${_brew_formula}' at ${_brew_opencv}")
            break()
        endif()
    endforeach()
endif()

# Windows: probe common install locations; user can override with -DOpenCV_DIR=
if(WIN32 AND NOT OpenCV_DIR)
    file(GLOB _opencv_candidates LIST_DIRECTORIES true "C:/opencv/build" "C:/tools/opencv/build")
    if(_opencv_candidates)
        list(GET _opencv_candidates 0 OpenCV_DIR)
    endif()
endif()

find_package(OpenCV REQUIRED)
if(OpenCV_VERSION VERSION_GREATER_EQUAL "5.0")
    message(FATAL_ERROR
        "OpenCV ${OpenCV_VERSION} found, but this project targets 4.x. OpenCV 5 moves calib3d "
        "into separate 3d/calib modules and the code does not build against it. On macOS: "
        "`brew install opencv@4` (it is keg-only, so plain `brew --prefix opencv` will not find "
        "it — this file asks for opencv@4 by name). Or point -DOpenCV_DIR= at a 4.x install.")
endif()
if(OpenCV_VERSION VERSION_LESS "3.0")
    message(FATAL_ERROR "OpenCV 3.0 or higher is required (found ${OpenCV_VERSION})")
endif()
message(STATUS "OpenCV ${OpenCV_VERSION}: found")

# Link ONLY the OpenCV modules the code actually uses (core, imgproc, imgcodecs —
# verified: those are the only opencv2/ headers included anywhere in the tree). The
# full ${OpenCV_LIBS} from a modular OpenCV (e.g. Homebrew) lists every module,
# including opencv_viz — which links the entire VTK tree (hundreds of MB of dylibs
# the app never calls). Pulling viz into the link makes macdeployqt bundle VTK,
# bloating the macOS .app/.dmg ~3-4x. Linking just the three modules keeps VTK out
# of the dependency graph entirely. Falls back to opencv_world (monolithic Windows
# builds) or the full set if the modular imported targets aren't present.
if(TARGET opencv_world)
    set(PP_OPENCV_LIBS opencv_world)
elseif(TARGET opencv_core AND TARGET opencv_imgproc AND TARGET opencv_imgcodecs)
    # opencv_videoio is needed by the offline re-analysis MP4 fallback (SwingDiskSource
    # in swing_reanalyzer.cpp) when a swing has no raw sidecar. It pulls FFmpeg backends,
    # NOT VTK (that's opencv_viz, still omitted), so the macOS-bundle bloat concern that
    # drove the modular link does not apply. No-op on monolithic opencv_world.
    set(PP_OPENCV_LIBS opencv_core opencv_imgproc opencv_imgcodecs
        $<TARGET_NAME_IF_EXISTS:opencv_videoio>)
else()
    set(PP_OPENCV_LIBS ${OpenCV_LIBS})
    message(WARNING "OpenCV: modular targets (opencv_core/imgproc/imgcodecs) not found "
                    "— linking the full ${OpenCV_LIBS}; the bundle may pull in VTK and be large.")
endif()
message(STATUS "OpenCV link set: ${PP_OPENCV_LIBS}")

target_compile_definitions(PinPointStudio PRIVATE HAVE_OPENCV)
target_include_directories(PinPointStudio PRIVATE ${OpenCV_INCLUDE_DIRS})
target_link_libraries(PinPointStudio PRIVATE ${PP_OPENCV_LIBS})

# Windows OpenCV runtime: previously resolved only from the dev PATH (e.g.
# C:\tools\opencv\build\x64\vc16\bin) — nothing was copied or installed. Bundle
# the world DLL (config-aware via the imported target). The app no longer uses
# OpenCV's videoio, so its loose FFmpeg backend DLL is not bundled here (the
# swinglab_run tool, which does use videoio, bundles it under its own target).
if(WIN32)
    set(_opencv_runtime_files "")
    if(TARGET opencv_world)
        list(APPEND _opencv_runtime_files "$<TARGET_FILE:opencv_world>")
    else()
        message(WARNING "OpenCV: 'opencv_world' target not found — modular OpenCV "
            "build? The world DLL will not be bundled; installer may be incomplete.")
    endif()
    if(_opencv_runtime_files)
        pp_win_bundle_dll(core ${_opencv_runtime_files})
        message(STATUS "OpenCV runtime: bundling ${_opencv_runtime_files}")
    else()
        message(WARNING "OpenCV runtime DLLs not located under ${OpenCV_DIR} — "
            "installer may be incomplete (set OpenCV_DIR to the build/ or lib/ dir).")
    endif()
endif()
target_sources(PinPointStudio PRIVATE
    src/Video/video_preprocessor_opencv.h
    src/Video/video_preprocessor_opencv.cpp
    src/Video/video_overlay_pose.h
    src/Video/video_overlay_pose.cpp
    src/Video/frame_throttle.h
    src/Video/frame_throttle.cpp
    src/Pose/ball_detector.h
    src/Pose/ball_detector.cpp
    src/Pose/pose_backend.h
    src/Pose/pose_backend.cpp
    src/Pose/motion_capture_probe.h
    src/Pose/motion_capture_probe.cpp
)
if(EXISTS "${_movenet_lightning_path}")
    target_sources(PinPointStudio PRIVATE
        src/Pose/pose_estimator_movenet.h
        src/Pose/pose_estimator_movenet.cpp
    )
    message(STATUS "MoveNet pose estimator: enabled")
endif()

if(WITH_MEDIAPIPE AND EXISTS "${_mediapipe_detector_path}" AND EXISTS "${_mediapipe_landmark_path}")
    target_sources(PinPointStudio PRIVATE
        src/Pose/pose_estimator_mediapipe.h
        src/Pose/pose_estimator_mediapipe.cpp
    )
    message(STATUS "MediaPipe pose estimator: enabled")
endif()

if(WITH_VITPOSE AND EXISTS "${_vitpose_model_path}")
    target_sources(PinPointStudio PRIVATE
        src/Pose/pose_estimator_vitpose.h
        src/Pose/pose_estimator_vitpose.cpp
    )
    message(STATUS "ViTPose-B pose estimator: enabled")
endif()

# ── FFmpeg (swing export encoder) ────────────────────────────────────────────
# Real link dependency on libavcodec/libavformat/libavutil/libswscale for the
# swing export H.264 encoder.  Distinct from the dlsym-based log suppression in
# pp_debug.cpp, which targets Qt Multimedia's *bundled* libavutil and needs no
# link.  GPL builds of FFmpeg (libx264) are fine: the project is GPLv2+.
# macOS: inject Homebrew prefix so pkg-config can locate the .pc files
if(APPLE)
    execute_process(
        COMMAND brew --prefix ffmpeg
        OUTPUT_VARIABLE _brew_ffmpeg
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_QUIET
        RESULT_VARIABLE _brew_ffmpeg_result
    )
    if(_brew_ffmpeg_result EQUAL 0 AND EXISTS "${_brew_ffmpeg}")
        set(ENV{PKG_CONFIG_PATH} "${_brew_ffmpeg}/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
    endif()
endif()

# Windows: probe common install locations; user can override with -DFFMPEG_DIR=
if(WIN32 AND NOT FFMPEG_DIR)
    file(GLOB _ffmpeg_candidates LIST_DIRECTORIES true "C:/ffmpeg" "C:/tools/ffmpeg")
    if(_ffmpeg_candidates)
        list(GET _ffmpeg_candidates 0 FFMPEG_DIR)
    endif()
endif()
if(WIN32 AND FFMPEG_DIR)
    set(ENV{PKG_CONFIG_PATH} "${FFMPEG_DIR}/lib/pkgconfig;$ENV{PKG_CONFIG_PATH}")
endif()

# Export module sources are always compiled; the FFmpeg-backed encoder is added
# only when the libraries are found.  Without FFmpeg the app still builds and
# runs — makeVideoEncoder() returns nullptr and swing export is disabled.
target_sources(PinPointStudio PRIVATE
    src/Export/video_encoder.h
    src/Export/video_encoder.cpp
    src/Export/swing_paths.h
    src/Export/swing_paths.cpp
    src/Export/frame_decode.h
    src/Export/frame_decode.cpp
    src/Export/swing_exporter.h
    src/Export/swing_exporter.cpp
    src/Export/swing_zip_exporter.h
    src/Export/swing_zip_exporter.cpp
    src/Export/swing_doc.h
    src/Export/swing_doc.cpp
    src/Export/session_archiver.h
    src/Export/session_archiver.cpp
    src/Analysis/swing_analysis.h
    src/Analysis/analysis_stage.h
    src/Wrist/wrist_angles.h
    src/Wrist/metric_extractor.h
    src/Wrist/metric_extractor.cpp
    src/IMU/imu_vision_fuser.h
    src/IMU/imu_vision_fuser.cpp
    src/Analysis/stream_trim.h
    src/IMU/hm_binding_recon.h
    src/Timeline/phase_segmenter.h
    src/Timeline/phase_segmenter.cpp
    src/Timeline/phase_signals.h
    src/Timeline/phase_signals.cpp
    src/Club/shaft_tracker_math.h
    src/Club/shaft_tracker_math.cpp
    src/Club/shaft_track_assembly.h
    src/Club/shaft_track_assembly.cpp
    src/Club/shaft_track_shared.h
    src/Club/shaft_frame_io.h
    # Down-the-line shaft tracker (dtl_shaft_tracker_design.md). Run in the app by
    # DtlShaftStage (analysis_pipeline.cpp) and by swinglab_run --dtl, through the one
    # witness builder and the one clubDtl/1 writer.
    src/Club/dtl_shaft_track.h
    src/Club/dtl_shaft_types.h
    src/Body/dtl_posture.h
    src/Club/shaft_fusion.h
    src/Club/shaft_fusion_json.h
    src/Club/dtl_face_on_witness.h
    src/Club/dtl_face_on_witness.cpp
    src/Club/dtl_shaft_json.h
    src/Club/dtl_shaft_json.cpp
    src/Club/dtl_shaft_config.h
    src/Club/dtl_shaft_decide.h
    src/Club/dtl_shaft_decide.cpp
    src/Club/dtl_shaft_post.h
    src/Club/dtl_shaft_post.cpp
    src/Club/dtl_shaft_tracker.h
    src/Club/dtl_shaft_tracker.cpp
    src/Club/clubhead_track.h
    src/Club/clubhead_track.cpp
    src/Pose/pose_smoother.h
    src/Pose/pose_smoother.cpp
    src/Body/head_track.h
    src/Body/head_track.cpp
    src/Body/foot_metrics.h
    src/Body/foot_metrics.cpp
    src/Body/lower_body_metrics.cpp
    src/Metrics/metric_channel.h
    src/Metrics/series_reduce.h
    src/Metrics/series_reduce_metric.h
    src/Body/upper_body_metrics.h
    src/Body/upper_body_metrics.cpp
    src/Body/body_rotation.h
    src/Body/body_rotation.cpp
    src/Kinematics/angular_rate.h
    src/Kinematics/kinematic_sequence.h
    src/Kinematics/kinematic_sequence_json.h
    src/Kinematics/segment_rates.h
    src/Kinematics/segment_rates.cpp
    src/Analysis/recorded_products.h
    src/Analysis/recorded_products.cpp
    src/Club/club_delivery.h
    src/Club/club_delivery.cpp
    src/Ball/ball_position.h
    src/Ball/ball_position.cpp
    src/Timeline/tempo_metrics.h
    src/Timeline/tempo_metrics.cpp
    src/Pose/hand_axis.h
    src/Wrist/pose_wrist_angle_source.h
    src/Wrist/pose_wrist_angle_source.cpp
    src/Club/shaft_tracker.h
    src/Club/shaft_tracker.cpp
    src/Club/ball_anchor.h
    src/Club/ball_anchor.cpp
    src/Timeline/event_refine.h
    src/Timeline/event_refine.cpp
    src/Analysis/swing_scorer.h
    src/Analysis/swing_scorer.cpp
    src/Wrist/wrist_resemblance.h
    src/Wrist/wrist_resemblance.cpp
    src/Wrist/score_uncertainty.h
    src/Wrist/score_uncertainty.cpp
    src/Analysis/analysis_pipeline.h
    src/Analysis/analysis_pipeline.cpp
    src/Skeleton3d/ybot_rig.h
    src/Skeleton3d/skeleton3d_rig.h
    src/Skeleton3d/skeleton3d_fit.h
    src/Skeleton3d/skeleton3d_fit.cpp
    src/Skeleton3d/skeleton3d_json.h
    src/Analysis/analysis_profiling.h
    src/Analysis/analysis_profiling.cpp
    src/Kinematics/kinematic_series.h
    src/Kinematics/kinematic_series.cpp
    src/Pose/pose_runner.h
    src/Pose/pose_runner.cpp
    src/Ball/ball_runner.h
    src/Ball/ball_runner.cpp
    src/Analysis/frame_store.h
    src/Analysis/frame_store.cpp
    src/Ball/impact_runner.h
    src/Ball/impact_runner.cpp
    src/Ball/ball_baseline_io.h
    src/Analysis/shot_analyzer.h
    src/Analysis/shot_analyzer.cpp
    src/Analysis/swing_reanalyzer.h
    src/Analysis/swing_reanalyzer.cpp
    src/Analysis/mp4_frame_reader.h
    src/Analysis/mp4_frame_reader.cpp
    src/Metrics/metric_type.h
    src/Metrics/metric_descriptor.h
    src/Metrics/metric_provider.h
    src/Metrics/metric_catalogue.h
    src/Metrics/metric_catalogue.cpp
    src/Metrics/metric_resolver.h
    src/Metrics/metric_resolver.cpp
    src/Metrics/metric_catalogue_manifest.cpp
    src/Metrics/metric_providers.h
    src/Metrics/metric_providers.cpp
)
find_package(PkgConfig QUIET)
if(PkgConfig_FOUND)
    pkg_check_modules(FFMPEG IMPORTED_TARGET libavcodec libavformat libavutil libswscale)
endif()
if(FFMPEG_FOUND)
    target_compile_definitions(PinPointStudio PRIVATE HAVE_FFMPEG)
    target_link_libraries(PinPointStudio PRIVATE PkgConfig::FFMPEG)
    target_sources(PinPointStudio PRIVATE
        src/Export/ffmpeg_video_encoder.h
        src/Export/ffmpeg_video_encoder.cpp
    )
    if(WIN32)
        # POST_BUILD: copy the linked FFmpeg DLLs (and swresample, a runtime
        # dependency of avcodec) next to the executable, same as ORT above.
        # FFMPEG_LIBDIR is only set for single-module pkg_check_modules calls;
        # FFMPEG_LIBRARY_DIRS is the one populated for multi-module checks.
        list(GET FFMPEG_LIBRARY_DIRS 0 _ffmpeg_libdir)
        file(GLOB _ffmpeg_dlls
            "${_ffmpeg_libdir}/../bin/avcodec-*.dll"
            "${_ffmpeg_libdir}/../bin/avformat-*.dll"
            "${_ffmpeg_libdir}/../bin/avutil-*.dll"
            "${_ffmpeg_libdir}/../bin/swscale-*.dll"
            "${_ffmpeg_libdir}/../bin/swresample-*.dll")
        # NOTE: windeployqt (wired in at the CPack/install-deploy stage) ships Qt's
        # own LGPL FFmpeg DLLs under the same names — those lack libx264 and break
        # swing export. The install-deploy script must re-copy these BtbN GPL DLLs
        # *after* windeployqt runs so they win. See packaging step.
        pp_win_bundle_dll(core ${_ffmpeg_dlls})
    endif()
    message(STATUS "FFmpeg ${FFMPEG_libavcodec_VERSION}: found — swing export enabled")
else()
    message(STATUS "FFmpeg: not found — swing export disabled")
endif()

if(APPLE)
    # The Bluetooth permission plugin is a static library that must be explicitly
    # imported; without this, checkPermission(QBluetoothPermission{}) always
    # returns Denied even when the OS has granted access.
    qt_import_plugins(PinPointStudio INCLUDE Qt6::QDarwinBluetoothPermissionPlugin)

    target_sources(PinPointStudio PRIVATE
        src/Gui/app/macos_permissions.h
        src/Gui/app/macos_permissions.mm
        src/STT/STTBackendApple.h
        src/STT/STTBackendApple.mm
        src/Video/VideoInputApple.h
        src/Video/VideoInputApple.mm
        src/Core/pp_gpu_metrics_mac.mm
    )
    # ARC manages the MTLDevice returned by MTLCreateSystemDefaultDevice().
    set_source_files_properties(src/Core/pp_gpu_metrics_mac.mm
        PROPERTIES COMPILE_OPTIONS "-fobjc-arc")
    add_custom_command(TARGET PinPointStudio POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy
            "${CMAKE_CURRENT_BINARY_DIR}/Info.plist"
            "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Info.plist"
        COMMENT "Installing Info.plist into bundle"
    )
    add_custom_command(TARGET PinPointStudio POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/icons/PinPointStudio.icns"
            "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Resources/PinPointStudio.icns"
        COMMENT "Installing PinPointStudio.icns into app bundle"
    )

    # The POST_BUILD copy above only fires when the executable actually
    # relinks.  Qt's bundle finalisation regenerates Contents/Info.plist with
    # its own (wrong) CFBundleIdentifier, and on an incremental build where
    # only Info.plist.in changed — no source relink — that stale, Qt-generated
    # plist survives.  This is the perennial "bundle id / usage strings don't
    # update until a clean build" bug.
    #
    # A custom target with no output is *always* considered out of date, so it
    # runs on every build invocation.  Making it part of ALL and depending on
    # the app target guarantees it executes as the final step, after Qt has
    # finalised the bundle, force-copying the configured plist in last so the
    # bundle's Info.plist can never go stale.  (configure_file() above re-runs
    # CMake automatically when Info.plist.in changes, refreshing the source.)
    add_custom_target(PinPointStudio_force_plist ALL
        COMMAND ${CMAKE_COMMAND} -E copy
            "${CMAKE_CURRENT_BINARY_DIR}/Info.plist"
            "$<TARGET_BUNDLE_CONTENT_DIR:PinPointStudio>/Info.plist"
        COMMENT "Force-installing Info.plist into bundle (runs every build)"
        VERBATIM
    )
    add_dependencies(PinPointStudio_force_plist PinPointStudio)

    # Sign the finished bundle with a stable self-signed identity so macOS TCC
    # retains the camera / microphone / speech / Bluetooth grants across rebuilds
    # (see cmake/DevCodesign.cmake).  This is the LAST thing to touch the bundle:
    # it depends on PinPointStudio_force_plist so the plist copy lands before the
    # signature, and like that target it is always out of date so it re-signs on
    # every build (the plist copy would otherwise invalidate a prior seal).
    set(PINPOINT_DEV_CODESIGN_IDENTITY "PinPoint Dev" CACHE STRING
        "Keychain identity used to sign the dev bundle so TCC permission grants persist across rebuilds")
    add_custom_target(PinPointStudio_codesign ALL
        COMMAND ${CMAKE_COMMAND}
            "-DBUNDLE=$<TARGET_BUNDLE_DIR:PinPointStudio>"
            "-DIDENTITY=${PINPOINT_DEV_CODESIGN_IDENTITY}"
            -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/DevCodesign.cmake"
        COMMENT "Signing dev bundle with '${PINPOINT_DEV_CODESIGN_IDENTITY}' (TCC-stable identity)"
        VERBATIM
    )
    add_dependencies(PinPointStudio_codesign PinPointStudio_force_plist)

    target_link_libraries(PinPointStudio PRIVATE
        "-framework AVFoundation"
        "-framework CoreMedia"
        "-framework CoreVideo"
        "-framework Accelerate"
        "-framework Speech"
        "-framework CoreGraphics"  # pp_colorspace_pin.cpp — CGColorSpace lifetime
        "-framework Metal"        # pp_gpu_metrics_mac.mm — MTLDevice memory query
        "-framework Foundation"
    )
endif()

if(UNIX AND NOT APPLE)
    find_package(Threads REQUIRED)
    target_link_libraries(PinPointStudio PRIVATE Threads::Threads)

endif()

if(MSVC)
    target_compile_definitions(PinPointStudio PRIVATE _CRT_SECURE_NO_WARNINGS)
    # M_PI and friends: MSVC only exposes them from <cmath>/<math.h> when
    # _USE_MATH_DEFINES is defined *before* that header is first included. The
    # vendored imu_ekf sources (third_party/imu_ekf) rely on M_PI, but by the
    # time their <Eigen.h> compat shim defines it, MSVC's <memory> has already
    # pulled in <cmath> and set its include guard. Define it on the command
    # line so it is in effect before any header is parsed.
    target_compile_definitions(PinPointStudio PRIVATE _USE_MATH_DEFINES)
endif()

install(TARGETS PinPointStudio
    BUNDLE  DESTINATION . COMPONENT core
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT core
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT core
)

# ── Qt deployment (windeployqt) at install time ──────────────────────────────
# The POST_BUILD steps above make the *build* tree runnable from the dev PATH, but
# Qt itself (Qt6 DLLs, platform/imageformats/multimedia/tls plugins, QML modules)
# is never copied. Run windeployqt against the *installed* exe to pull Qt into the
# install tree. Runs as part of the "core" component, after install(TARGETS) above
# so the exe it inspects already exists.
#
# We invoke windeployqt directly via install(CODE) rather than
# qt_generate_deploy_qml_app_script: the latter pre-copies the QML plugin DLLs into
# the tree and then has windeployqt overwrite them, which fails deterministically
# here with "Cannot remove existing file …plugind.dll: being used by another
# process" (the just-written DLL is briefly locked, e.g. by AV real-time scan).
# windeployqt deploying into a clean tree never overwrites, so it is reliable.
if(WIN32)
    get_filename_component(_qt_prefix "${Qt6_DIR}/../../.." ABSOLUTE)
    find_program(WINDEPLOYQT_EXECUTABLE windeployqt HINTS "${_qt_prefix}/bin" REQUIRED)
    # Do NOT pass --force. windeployqt reaches some QML plugins via multiple import
    # paths and maps each plugin DLL to read its dependency table. With --force it
    # then removes-and-recopies that same still-mapped file, hitting "Cannot remove
    # existing file …plugind.dll: being used by another process" (it locks its own
    # file). Without --force it simply skips already-current files. The retry is a
    # belt for genuine transient AV locks on freshly written DLLs.
    install(CODE "
        set(_wdq_ok FALSE)
        foreach(_try RANGE 1 4)
            message(STATUS \"Deploying Qt (windeployqt) attempt \${_try} into \${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}\")
            execute_process(
                COMMAND \"${WINDEPLOYQT_EXECUTABLE}\"
                        --qmldir \"${CMAKE_CURRENT_SOURCE_DIR}\"
                        --compiler-runtime
                        --no-translations
                        \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}/PinPointStudio.exe\"
                RESULT_VARIABLE _wdq_rc)
            if(_wdq_rc EQUAL 0)
                set(_wdq_ok TRUE)
                break()
            endif()
            message(STATUS \"  windeployqt attempt \${_try} failed (exit \${_wdq_rc}); retrying after 3s\")
            execute_process(COMMAND \"${CMAKE_COMMAND}\" -E sleep 3)
        endforeach()
        if(NOT _wdq_ok)
            message(FATAL_ERROR \"windeployqt failed after 4 attempts.\")
        endif()
    " COMPONENT core)

    # windeployqt ships Qt Multimedia's own LGPL FFmpeg DLLs under the SAME names
    # as our BtbN GPL build — but Qt's lack libx264, breaking swing export. They
    # were installed earlier (via pp_win_bundle_dll), then clobbered by windeployqt
    # just above. Re-copy the BtbN DLLs LAST so they win. install() runs in
    # declaration order, so this must come *after* the deploy install(CODE).
    if(FFMPEG_FOUND AND _ffmpeg_dlls)
        install(FILES ${_ffmpeg_dlls}
                DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT core)
    endif()
endif()

# ── Linux: install hicolor PNG icons + .desktop file ─────────────────────────
if(UNIX AND NOT APPLE)
    foreach(_sz 16 32 48 64 128 256)
        install(FILES
            "${CMAKE_CURRENT_SOURCE_DIR}/src/Resources/icons/pinpointstudio_${_sz}.png"
            DESTINATION "share/icons/hicolor/${_sz}x${_sz}/apps"
            RENAME "pinpointstudio.png"
        )
    endforeach()
    install(FILES
        "${CMAKE_CURRENT_SOURCE_DIR}/PinPointStudio.desktop"
        DESTINATION "share/applications"
    )
endif()

# ── Launch monitor row repair ────────────────────────────────────────────────
# lm_repair rebuilds the `lm.*` metric rows in a swing.json from the raw
# `launchMonitor` block already in the file, by handing it back to the production
# emitter (SwingDocWriter::updateLaunchMonitor). Recovery for documents written
# before writeSwingJson carried the rows across a re-analysis.
#
# Its own option rather than PINPOINT_BUILD_TOOLS: it needs the swing.json writer
# and the reading table and NOTHING else — the same three-source link swing_doc_test
# uses — so gating it behind the SwingLab set would drag OpenCV, ONNX Runtime and the
# ViTPose model into a build that touches none of them.
option(PINPOINT_BUILD_LM_REPAIR "Build the launch-monitor metric repair tool" OFF)
if(PINPOINT_BUILD_LM_REPAIR)
    add_executable(lm_repair
        tools/launchmonitor/lm_repair.cpp
        src/Export/swing_doc.cpp
        # SwingDocReader's session-directory helpers call SwingPaths::sanitise. The tool
        # never walks a library that way, but they are in the same translation unit.
        src/Export/swing_paths.cpp
        src/LaunchMonitor/launch_monitor_reading.cpp
        # NOT src/Core/pp_debug.cpp — it includes whisper.h and would pull ggml and FFmpeg
        # into a tool that rewrites one JSON file. lm_repair.cpp provides PpLogStream itself
        # and routes it to stderr; see the note there.
    )
    target_include_directories(lm_repair PRIVATE
        src/Buffer src/Export src/LaunchMonitor src/Core)
    target_link_libraries(lm_repair PRIVATE Qt6::Core Qt6::Gui pinpoint_swingstore)
    message(STATUS "Launch monitor tools: lm_repair enabled")
endif()

# pps_convert_library converts JSON-era swings to swing.ppsw, proving each before the JSON goes
# (docs/implementation/swing_storage_impl.md, Phase 2). Built by default: it is four translation
# units on Qt Core — the swing.json writer's own link line plus the real log — and it is the tool
# a library conversion is RUN with, so a build that can capture should always be able to run it.
option(PINPOINT_BUILD_STORAGE_TOOLS "Build the swing-library storage tools" ON)
if(PINPOINT_BUILD_STORAGE_TOOLS)
    add_executable(pps_convert_library
        tools/storage/pps_convert_library.cpp
        src/Export/swing_doc.cpp
        src/Export/swing_paths.cpp
        src/LaunchMonitor/launch_monitor_reading.cpp
        # The real log: swing_paths reports through ppWarn, and a line a conversion says on the
        # way past must reach whoever runs it. Standalone now — no whisper, no ggml.
        src/Core/pp_log_stream.cpp
        src/Core/PpMessageLog.cpp
    )
    target_include_directories(pps_convert_library PRIVATE
        src/Buffer src/Export src/LaunchMonitor src/Core)
    target_link_libraries(pps_convert_library PRIVATE Qt6::Core Qt6::Gui pinpoint_swingstore)
    message(STATUS "Storage tools: pps_convert_library enabled")
endif()

# ── SwingLab offline tools (docs/implementation/swinglab_impl.md) ─────────────
# swinglab_run replays a recorded swing dir through the PRODUCTION analysis
# pipeline (same sources, same configs) with JSON-injectable tuning params and
# per-frame trace dumps. Built only on request — it shares the app's heavy
# dependency set (OpenCV incl. videoio, ONNX Runtime, ViTPose model).
# The skeleton3d solver (Skeleton3DStage) is dense small-matrix Eigen: unoptimised it is ~20×
# slower, which a Debug app tree would feel on every shot. Optimised and assert-free in every
# configuration on the compilers that allow it per file (MSVC's /RTC1 forbids /O2 alongside).
set_source_files_properties(src/Skeleton3d/skeleton3d_fit.cpp PROPERTIES
    COMPILE_DEFINITIONS "EIGEN_NO_DEBUG"
    COMPILE_OPTIONS "$<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-O2>")

option(PINPOINT_BUILD_TOOLS "Build the SwingLab offline analysis tools" OFF)
if(PINPOINT_BUILD_TOOLS)
    # Shared offline reconstruction + analysis sources (the disk → SwingWindow →
    # analyzer stack), used by both the SwingLab runner and the parity test. The
    # parity test additionally compiles the exporter to build its fixture.
    set(_pinpoint_offline_sources
        src/Analysis/swing_reanalyzer.cpp
        src/Analysis/mp4_frame_reader.cpp   # the MP4 reader it builds (decode.*)
        src/Analysis/shot_analyzer.cpp
        src/Analysis/analysis_pipeline.cpp
        src/Skeleton3d/skeleton3d_fit.cpp
        src/Analysis/analysis_profiling.cpp
        src/Kinematics/kinematic_series.cpp
        src/IMU/imu_vision_fuser.cpp
        src/Timeline/phase_segmenter.cpp
        src/Timeline/phase_signals.cpp
        src/Wrist/metric_extractor.cpp
        src/Analysis/swing_scorer.cpp
        src/Wrist/wrist_resemblance.cpp
        src/Wrist/score_uncertainty.cpp
        # Tier-2 wrist assessment (offline known-groups, ShotAnalysisJob::runAssessment)
        src/Wrist/wrist_analysis_adapter.cpp
        src/Wrist/wrist_assessment_engine.cpp
        src/Wrist/assessment_rules.cpp
        src/Wrist/reference_bands.cpp
        # reference_bands.cpp hosts NormBandProvider — the corridors it used to compile in are now
        # content in src/Resources/diagnostics/norms.json, so the offline stack needs the norm
        # stack too. Omit these and swinglab_run / in-app re-analyse fail at link time.
        src/Diagnostics/engine/pack_io.cpp
        src/Diagnostics/norms/norm.cpp
        src/Diagnostics/norms/norm_pack.cpp
        src/Diagnostics/norms/context_tree.cpp
        src/Diagnostics/packs/characteristic_pack.cpp
        src/Diagnostics/engine/characteristic.cpp
        src/Diagnostics/measures/measure_facets.cpp
        src/Diagnostics/measures/anatomy_vocabulary.cpp
        src/Diagnostics/norms/resource_norm_provider.cpp
        src/Diagnostics/norms/file_norm_provider.cpp
        src/Diagnostics/norms/merged_norm_provider.cpp
        # screens.json and drills.json are embedded into every offline target by
        # pinpoint_add_diagnostics_resources below, so their loaders belong here too — otherwise the
        # offline binaries carry two reference sets no code in them can read, which looks like
        # content that failed to load rather than content nothing asked for.
        #
        # Nothing offline CALLS them yet, so the linker drops the code and the binaries do not grow.
        # What this buys is that the day a diagnosis runs in swinglab_run — where a
        # TestRecommendation has to resolve its screenRef to a protocol — the link does not fail.
        src/Diagnostics/packs/screen_pack.cpp
        src/Diagnostics/packs/drill_pack.cpp
        src/Diagnostics/packs/reference_pack.cpp
        src/Pose/pose_runner.cpp
        src/Ball/ball_runner.cpp
        src/Analysis/frame_store.cpp
        src/Ball/impact_runner.cpp
        src/Club/shaft_tracker.cpp
        src/Club/ball_anchor.cpp
        src/Timeline/event_refine.cpp
        src/Club/shaft_tracker_math.cpp
        src/Club/shaft_track_assembly.cpp
        # DTL shaft tracker — DtlShaftStage and swinglab_run --dtl (§5.11).
        src/Club/dtl_face_on_witness.cpp
        src/Club/dtl_shaft_json.cpp
        src/Club/dtl_shaft_decide.cpp
        src/Club/dtl_shaft_post.cpp
        src/Club/dtl_shaft_tracker.cpp
        src/Club/clubhead_track.cpp
        src/Pose/pose_smoother.cpp
        src/Body/head_track.cpp
        src/Body/foot_metrics.cpp
        src/Body/lower_body_metrics.cpp
        src/Body/upper_body_metrics.cpp
        src/Body/body_rotation.cpp
        src/Kinematics/segment_rates.cpp
        src/Analysis/recorded_products.cpp
        src/Club/club_delivery.cpp
        src/Ball/ball_position.cpp
        src/Timeline/tempo_metrics.cpp
        src/Wrist/pose_wrist_angle_source.cpp
        src/Metrics/metric_catalogue.cpp
        src/Metrics/metric_resolver.cpp
        src/Metrics/metric_catalogue_manifest.cpp
        src/Metrics/metric_providers.cpp
        src/Export/frame_decode.cpp
        src/Export/swing_doc.cpp
        src/Export/swing_paths.cpp
        # swing_doc.cpp writes the launchMonitor block by walking lm::fieldDefs(),
        # so the offline tools need the table itself, not just its header. The
        # PARSER and the monitor stay out: an offline tool replays a recorded
        # swing.json, it never reads a LastShot.CSV or talks to a device.
        src/LaunchMonitor/launch_monitor_reading.cpp
        src/Pose/pose_estimator_base.cpp
        src/Pose/pose_estimator_vitpose.cpp
        src/Core/pp_debug.cpp
        src/Core/pp_log_stream.cpp
        src/Core/PpMessageLog.cpp
        src/Core/PpStatsLog.cpp
        src/Core/AnalysisProfileLog.cpp
        src/Core/pp_profiler.cpp
        src/Core/pp_os_metrics.cpp
    )

    # Common include/define/link wiring for an offline tool target.
    function(pinpoint_configure_offline_target tgt)
        target_include_directories(${tgt} PRIVATE
            src/Buffer src/Analysis src/Metrics src/Export src/Pose src/Core src/IMU
            src/Club src/Wrist src/Body src/Timeline src/Ball src/Kinematics src/Skeleton3d src/Coaching
            # src/Export/swing_doc.h includes launch_monitor_reading.h, so every
            # consumer of it needs this — the app target got it when the reading
            # was added, these offline targets did not.
            src/LaunchMonitor
            "${_ort_root}/include"
            # skeleton3d_fit.cpp (the Skeleton3DStage's solver) is Eigen.
            ${eigen_SOURCE_DIR}
            ${OpenCV_INCLUDE_DIRS}
            ${whisper_SOURCE_DIR}/include
            ${whisper_SOURCE_DIR}/ggml/include
        )
        target_compile_definitions(${tgt} PRIVATE
            HAVE_OPENCV HAVE_ONNXRUNTIME
            $<$<BOOL:${_vitpose_model_file}>:HAVE_VITPOSE>
            $<$<BOOL:${_vitpose_model_file}>:VITPOSE_MODEL_FILE="${_vitpose_model_file}">
        )
        # The person segmenter (AddressMarksStage reads it: the coach lines' body edges). Same
        # model file the app bundles; the bare exe finds it under _deps/segmenter through
        # pinpoint::modelFilePath, like the pose models.
        if(EXISTS "${_seg_model_path}")
            target_compile_definitions(${tgt} PRIVATE HAVE_SEGMENTER SEGMENTER_MODEL_FILE="${_seg_model_file}")
            # The segmenter reports its VRAM through pp_gpu_metrics (the app compiles it at ~line 927;
            # the Metal query on macOS is the .mm with the ARC flag set beside the app's sources).
            target_sources(${tgt} PRIVATE src/Pose/person_segmenter.cpp src/Core/pp_gpu_metrics.cpp)
            if(APPLE)
                target_sources(${tgt} PRIVATE src/Core/pp_gpu_metrics_mac.mm)
            endif()
        endif()
        # Same platform-guarded EP defines as the app target (~line 951ff);
        # without them the offline pose pass is compile-time pinned to CPU even
        # on the CUDA studio box. The EP cascade try/catches registration at
        # runtime, so a GPU-less machine still degrades safely to CPU.
        if(WITH_CUDA AND NOT APPLE)
            target_compile_definitions(${tgt} PRIVATE WITH_CUDA)
        endif()
        if(WITH_COREML AND APPLE AND CMAKE_SYSTEM_PROCESSOR STREQUAL "arm64")
            target_compile_definitions(${tgt} PRIVATE WITH_COREML)
        endif()
        target_link_libraries(${tgt} PRIVATE
            Qt6::Core Qt6::Gui Qt6::Multimedia
            pinpoint_buffer pinpoint_swingstore whisper
            # wrist_record is the .wrwire wire container and the reconciliation
            # that reads a capture back — what an offline target needs to replay a
            # recorded HackMotion session. Nothing offline CALLS it yet, so the
            # linker drops the code and the binaries do not grow; what it buys is
            # that the day swinglab_run replays one, the link does not fail. Same
            # argument as screen_pack/drill_pack above.
            wrist wrist_record
            ${PP_OPENCV_LIBS}   # same core/imgproc/imgcodecs subset — no viz/VTK (see above)
            # The offline tools read recorded MP4s via cv::VideoCapture — pull in
            # opencv_videoio (no-op on monolithic opencv_world via TARGET_NAME_IF_EXISTS).
            $<TARGET_NAME_IF_EXISTS:opencv_videoio>
        )
        if(WIN32)
            target_link_libraries(${tgt} PRIVATE "${_ort_root}/lib/onnxruntime.lib")
        elseif(APPLE)
            target_link_libraries(${tgt} PRIVATE "${_ort_dylib_path}")
        else()
            target_link_libraries(${tgt} PRIVATE "${_ort_root}/lib/libonnxruntime.so")
        endif()
    endfunction()

    # The shipped diagnostics content, embedded in every offline target too.
    #
    # This is NOT optional and it is NOT shared with the app's copy: qt_add_resources attaches to
    # ONE target, so an offline binary that omits it starts with an empty norm set. Since the wrist
    # corridors are content now rather than a compiled table, that would leave every band absent —
    # swinglab_run and in-app re-analyse would grey the whole wrist grid and produce no findings,
    # silently, with no error to notice. wrist_norm_render_test guards the same failure in the
    # test suite; this is the build-side half of it.
    function(pinpoint_add_diagnostics_resources tgt)
        qt_add_resources(${tgt} "${tgt}_diagnostics"
            PREFIX "/diagnostics"
            BASE   "src/Resources/diagnostics"
            FILES
                src/Resources/diagnostics/core.json
                src/Resources/diagnostics/norms.json
                src/Resources/diagnostics/contexts.json
                src/Resources/diagnostics/screens.json
                src/Resources/diagnostics/drills.json
                src/Resources/diagnostics/references.json
        )
    endfunction()

    add_executable(swinglab_run tools/swinglab/src/swinglab_run.cpp ${_pinpoint_offline_sources})
    pinpoint_configure_offline_target(swinglab_run)
    pinpoint_add_diagnostics_resources(swinglab_run)
    # The runner resolves the ViTPose model next to its own binary, same as the app.
    message(STATUS "SwingLab tools: swinglab_run enabled")

    # RAM-vs-disk SwingWindow parity test — builds its fixture with the real
    # exporter, so it additionally compiles the Export encoder stack + FFmpeg.
    add_executable(swing_window_parity_test
        src/Analysis/tests/swing_window_parity_test.cpp
        ${_pinpoint_offline_sources}
        src/Export/swing_exporter.cpp
        src/Export/video_encoder.cpp
    )
    pinpoint_configure_offline_target(swing_window_parity_test)
    pinpoint_add_diagnostics_resources(swing_window_parity_test)
    if(FFMPEG_FOUND)
        target_sources(swing_window_parity_test PRIVATE src/Export/ffmpeg_video_encoder.cpp)
        target_compile_definitions(swing_window_parity_test PRIVATE HAVE_FFMPEG)
        target_link_libraries(swing_window_parity_test PRIVATE PkgConfig::FFMPEG)
    endif()
    add_test(NAME swing_window_parity COMMAND swing_window_parity_test)
    message(STATUS "SwingLab tools: swing_window_parity_test enabled")

    # raw_reencode — re-encode a swing's face-on camera from its .raw at a chosen CRF, through the
    # production SwingExporter (swing_storage_impl.md Phase 2, stage 4: the CRF 18/12 study). Same
    # encoder stack as the parity test above; needs FFmpeg, or there is nothing to encode with.
    if(FFMPEG_FOUND)
        add_executable(raw_reencode
            tools/swinglab/src/raw_reencode.cpp
            ${_pinpoint_offline_sources}
            src/Export/swing_exporter.cpp
            src/Export/video_encoder.cpp
            src/Export/ffmpeg_video_encoder.cpp
        )
        pinpoint_configure_offline_target(raw_reencode)
        pinpoint_add_diagnostics_resources(raw_reencode)
        target_compile_definitions(raw_reencode PRIVATE HAVE_FFMPEG)
        target_link_libraries(raw_reencode PRIVATE PkgConfig::FFMPEG)
        message(STATUS "SwingLab tools: raw_reencode enabled")
    endif()
endif()

# The offscreen QML UI suite USED TO BE HERE, and was the only suite in the app build.
# It moved to src/Gui/tests/CMakeLists.txt: it now declares the PinPointStudio QML module
# itself (from cmake/PinPointQmlModule.cmake, the same lists this file feeds to
# qt_add_qml_module above) rather than borrowing the app's through a staged, prefer-stripped
# copy, so it depends on no app target and runs under the umbrella with every other suite:
#
#   ctest --test-dir build/tests -R qml_ui --output-on-failure
#
# That is what puts it in the Linux, macOS and Windows release gates, which all run the
# umbrella and none of which ran this. cmake/StripQmlPrefer.cmake went with it.
#
# ── AND ITS OUTPUTS HAVE TO BE SWEPT UP, BECAUSE CMAKE WILL NOT ──────────────
#
# Deleting a target stops it PRODUCING anything; it does not remove what it already
# produced. Every build directory that built the app before that change still holds
# `qml-test-imports/PinPointStudio/qmldir` — a stale, prefer-STRIPPED duplicate of this
# app's own QML module — sitting beside the real one in `qml/PinPointStudio/`, plus a
# stale qml_ui_test binary. Pulling does not clear them and neither does rebuilding.
#
# ⚠ TWO PinPointStudio MODULES IN ONE BUILD TREE IS NOT INERT. Qt Creator scans the build
# directory to assemble QML_IMPORT_PATH for the run environment, so a second copy of this
# module — one whose qmldir has had its `prefer` line removed, pointing the engine at
# on-disk files instead of the resources compiled into the binary — is on the import path
# ahead of anything else. It surfaced as the app failing to load Main.qml with
# "module QtQuick3D plugin qquick3dplugin not found" and "No QtMultimedia backends found",
# which name neither QML nor this directory and read as a broken Qt install.
#
# ⚠ AND IT IS INVISIBLE FROM A SHELL. Running the binary directly resolves modules and
# plugins from the Qt installation and is perfectly clean — the fault needs Qt Creator's
# scanned environment to appear at all, so "it works when I run it" does not clear it.
#
# So the sweep happens at CONFIGURE time, here, rather than in a runbook step somebody has
# to remember on each of four platforms. It is idempotent, costs nothing once the
# directory is gone, and can be deleted from this file once every build directory in use
# predates nothing.
foreach(_pp_orphan qml-test-imports qml_ui_test qml_ui_test_autogen CMakeFiles/qml_ui_test.dir)
    if(EXISTS "${CMAKE_CURRENT_BINARY_DIR}/${_pp_orphan}")
        message(STATUS "Removing orphaned qml_ui_test output: ${_pp_orphan} "
                       "(the suite moved to src/Gui/tests; see the note above)")
        file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/${_pp_orphan}")
    endif()
endforeach()

# ── PPCP transport — TLS-PSK over two TCP channels (src/Ppcp, package H1) ────
# The host half of the PinPoint Capture Protocol transport. Nothing calls it
# yet; H2 wraps it around libppcp's peer engine.
#
# WHY OpenSSL AND NOT Qt Network, which is already linked: PPCP-RV §5 needs a
# TLS EXTERNAL pre-shared key, and RV §8 states that the PSK interfaces in
# common toolkits — identity hints, RFC 4279 ciphersuite selection — do not
# reach TLS 1.3 external PSKs at all. QSslPreSharedKeyAuthenticator is one of
# those. See cmake/PinPointOpenSSL.cmake for the locate routine, which the
# standalone test suite in src/Ppcp/tests shares.
#
# ⚠ OPTIONAL AT BUILD TIME, NEVER AT RUN TIME. A box without OpenSSL headers
# configures as it always did and gets an app with no PPCP transport, said out
# loud. That is not the plaintext fallback RV 5.2f forbids — there is no code
# path in src/Ppcp that produces an unencrypted connection, so the choice is
# "PPCP or no PPCP", never "PPCP in the clear".
#
# ⚠ AND libppcp IS NOW A SECOND HARD REQUIREMENT OF THIS BLOCK. Since erratum
# E1 the transport sends and reads `link_bind` (ENC 2.1) through libppcp's own
# frame, CBOR and envelope writers rather than hand-rolling the wire format —
# ground rule 1: if two repositories need the same thing it belongs in libppcp.
# So the transport needs the library as well as OpenSSL, and a box with neither
# gets the same honest "no PPCP" as a box with no OpenSSL.
include(cmake/PinPointOpenSSL.cmake)
pp_find_openssl()
if(PP_OPENSSL_FOUND AND TARGET ppcp)
    target_sources(PinPointStudio PRIVATE
        src/Ppcp/ppcp_transport.h     src/Ppcp/ppcp_transport.cpp
        # The USB tunnel of the wired transport (docs/design/wired_transport_design.md
        # §4).  Beside the transport because it exists to fill exactly one field of
        # ConnectorConfig — `dial` — and has no other purpose.  Qt-free and
        # OpenSSL-free; it is in this block because the thing it feeds is.
        src/Ppcp/ppcp_usbmux.h        src/Ppcp/ppcp_usbmux.cpp
        # ppcp_ingest_policy.{h,cpp} moved to the unconditional TARGET-ppcp block
        # above — ppcp_host_engine.cpp (bundle path) calls evaluate() too and is
        # itself unconditional, so gating the policy on OpenSSL left that call
        # unresolved on a box with no OpenSSL.
        src/Ppcp/ppcp_host_peer.h     src/Ppcp/ppcp_host_peer.cpp
        # H6 — PPCP-RV, host side.  In the TRANSPORT block because the code's
        # whole purpose is to authenticate a TLS handshake: the resolver is
        # installed on H1's Listener and the derived K_tls is that handshake's
        # external PSK.  A rendezvous with no socket to hand it to would be a
        # key generator.
        src/Ppcp/ppcp_rendezvous.h    src/Ppcp/ppcp_rendezvous.cpp
        src/Ppcp/ppcp_pairing_store.cpp
        src/Ppcp/ppcp_discovery.h     src/Ppcp/ppcp_discovery.cpp
        # W4, second cut — the native mDNS engine (Windows only at runtime;
        # ppcp_mdns_wire.cpp is pure codec and compiles everywhere, so it is
        # unconditional here rather than adding a third per-platform source
        # list). No Bonjour SDK dependency: see ppcp_mdns_native.h for why.
        src/Ppcp/ppcp_mdns_wire.h     src/Ppcp/ppcp_mdns_wire.cpp
        src/Ppcp/ppcp_mdns_native.h   src/Ppcp/ppcp_mdns_native.cpp
        # H10 — RV-6 guided pairing, the INITIATOR half.  In the TRANSPORT
        # block for the same reason the rendezvous is: what a guided pairing
        # produces is a `PRK`, and §5's TLS handshake is the only thing that
        # consumes one.  ⛔ Three of CR-01's nine traps live in this file and
        # none of them is visible on the wire — read its header before touching
        # it, and in particular before adding anything that dials more than one
        # discovered window or compares six digits in software.
        src/Ppcp/ppcp_bootstrap.h     src/Ppcp/ppcp_bootstrap.cpp
        # H-compose — THE OWNER.  Until this file, nothing in this application
        # constructed a PpcpHostPeer and three joins named in the code had no
        # caller.  It is its own translation unit and not lines in main.cpp so
        # that ppcp-tests can compile it (see the ppcp_app_tu_syntax row).
        # Phase 1 of the wired transport — the orchestration above the tunnel:
        # the usbmux device watch, the presence-record reader (contract C3) and
        # the dial thread.  Its own translation unit rather than more lines in
        # ppcp_host_service.cpp, which is already the largest file here.
        src/Ppcp/ppcp_wired_link.h    src/Ppcp/ppcp_wired_link.cpp
        src/Ppcp/ppcp_host_service.h  src/Ppcp/ppcp_host_service.cpp)

    target_include_directories(PinPointStudio PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/Ppcp)
    target_link_libraries(PinPointStudio PRIVATE OpenSSL::SSL OpenSSL::Crypto)
    # ⚠ Security.framework and CoreFoundation were linked here for the macOS
    # keychain pairing store.  RV 7.2c became a SHOULD (libppcp erratum E56,
    # 25 August 2026) and the PRK moved into the application's own settings on
    # every platform, so nothing reaches Security.framework any more.
    if(WIN32)
        # ppcp_rendezvous.cpp's Windows branch: GetAdaptersAddresses (RV 4.3d's
        # endpoint enumeration) needs iphlpapi, BCryptGenRandom (RV 7.2a's
        # CSPRNG) needs bcrypt. ws2_32 comes in transitively via Qt6::Network.
        target_link_libraries(PinPointStudio PRIVATE iphlpapi bcrypt)

        # OpenSSL is linked shared here (vcpkg's default triplet, and most
        # system installs) but nothing above copies its DLLs next to the exe —
        # unlike FFmpeg/ORT/CUDA, this dependency is new enough that no such
        # step existed yet. Same trick as FFmpeg's: walk from the import
        # library CMake actually found back to its sibling bin/.
        get_filename_component(_openssl_libdir "${OPENSSL_SSL_LIBRARY}" DIRECTORY)
        file(GLOB _openssl_dlls
            "${_openssl_libdir}/../bin/libssl-*.dll"
            "${_openssl_libdir}/../bin/libcrypto-*.dll")
        pp_win_bundle_dll(core ${_openssl_dlls})
    endif()
    # ── DNS-SD for RV §3 reconnection discovery ──────────────────────────
    # ⚠ THE FIRST DISCOVERY-LIBRARY DEPENDENCY IN THIS TREE.  On macOS the
    # `DNSService*` symbols come free from libSystem, so `ppcp_discovery.cpp`
    # has never needed a link line and none exists above.  Everywhere else they
    # have to come from somewhere.
    #
    # On Linux that somewhere is Avahi's Bonjour compatibility layer, which
    # exposes the SAME `dns_sd.h` API — so this buys the whole of
    # `BonjourBrowser` and `BonjourAdvertiser` with no second backend.  Measured
    # 29 Aug 2026 against libavahi-compat-libdnssd1 0.8: `DNSServiceUpdateRecord`
    # rotates the TXT record IN PLACE and the instance name does not move, which
    # is what RV 3.2d requires and what `ppcp_discovery.h:302-308` feared might
    # be missing.  See the Phase 2L log in the implementation plan.
    #
    # ⛔ ABSENCE IS NOT AN ERROR.  With no shim the define is not set, both
    # factories keep returning null, and the host behaves exactly as it does
    # today: no reconnection discovery, and RV 3.6b makes that silent because
    # the pairing code carries its own endpoints.  A STATUS line, never a
    # warning — this is a capability, not a prerequisite.
    #
    # ✅ Windows (W4, second cut): no probe needed here at all — the native
    # engine (src/Ppcp/ppcp_mdns_native.cpp, added to the source list above)
    # is pure Winsock, always present on Windows, and carries no external
    # dependency to find or fail to find. The Bonjour SDK for Windows path
    # this replaced is gone: Apple's runtime registers a Winsock namespace
    # provider (mdnsNSP.dll) that fails modern Windows Code Integrity /
    # LSA-protection signing checks — visibly, a "blocked from loading into
    # the Local Security Authority" popup on every boot — on every machine
    # that has it installed, whether or not this application ever runs.
    if(WIN32)
        message(STATUS "PPCP discovery: native mDNS engine (no Bonjour SDK dependency)")
    elseif(NOT APPLE)
        find_package(PkgConfig QUIET)
        if(PkgConfig_FOUND)
            pkg_check_modules(DNSSD QUIET avahi-compat-libdns_sd)
        endif()
        if(NOT DNSSD_FOUND)
            # No .pc file (or no pkg-config at all) — look for the pieces.
            find_path(DNSSD_INCLUDE_DIR dns_sd.h
                      PATH_SUFFIXES avahi-compat-libdns_sd)
            find_library(DNSSD_LIBRARY dns_sd)
            if(DNSSD_INCLUDE_DIR AND DNSSD_LIBRARY)
                set(DNSSD_INCLUDE_DIRS "${DNSSD_INCLUDE_DIR}")
                set(DNSSD_LIBRARIES    "${DNSSD_LIBRARY}")
                set(DNSSD_FOUND TRUE)
            endif()
        endif()
        if(DNSSD_FOUND)
            target_include_directories(PinPointStudio PRIVATE ${DNSSD_INCLUDE_DIRS})
            target_link_libraries(PinPointStudio PRIVATE ${DNSSD_LIBRARIES})
            target_compile_definitions(PinPointStudio PRIVATE PP_HAVE_DNS_SD)
            message(STATUS "PPCP discovery: DNS-SD via ${DNSSD_LIBRARIES}")
        else()
            message(STATUS
                "PPCP discovery: no DNS-SD library — reconnection discovery is off. "
                "Pairing by code still works (RV 3.6b). "
                "Debian/Ubuntu: apt install libavahi-compat-libdnssd-dev.")
        endif()
    endif()

    target_compile_definitions(PinPointStudio PRIVATE HAVE_PPCP_TRANSPORT)
    message(STATUS "PPCP transport: OpenSSL ${PP_OPENSSL_VERSION}, libppcp ${PP_LIBPPCP_VERSION}")
else()
    # ⚠ A DEVELOPER'S BOX WARNS.  A DISTRIBUTABLE ARTEFACT REFUSES.  (2026-09-22)
    #
    # The two branches below are not fatal on their own, and that is deliberate — the
    # argument is in cmake/PinPointOpenSSL.cmake and it still holds: a box without
    # libssl-dev, or without a libppcp checkout, configures exactly as it always did.
    # Nothing here is a runtime downgrade; there is no plaintext fallback to reach.
    #
    # But an artefact built FOR OTHER PEOPLE is a different object, and this is the one
    # failure this project has actually shipped: v0.1-beta1 went out with no PPCP and no
    # pairing because packaging configured without -DOPENSSL_ROOT_DIR. The warning below
    # was printed. It scrolled past in a long configure log, the installer was published,
    # and it had to be pulled and re-uploaded (fixed in packaging/build_installer.ps1 on
    # 2026-09-03, which now passes the root).
    #
    # A warning is the wrong instrument for that, because the symptom is an ABSENCE: the
    # build succeeds, the app starts, and the only tell is a feature nobody exercises
    # until a phone is in front of it. So a shipping build asserts instead, and someone
    # who genuinely wants a transport-less artefact says PP_ALLOW_NO_PPCP=ON and owns it.
    if(PP_SHIPPING_BUILD AND NOT PP_ALLOW_NO_PPCP)
        if(NOT PP_OPENSSL_FOUND)
            message(FATAL_ERROR
                "PP_SHIPPING_BUILD=ON but OpenSSL was not found, so this artefact would "
                "ship with NO PPCP transport — no phone pairing, no capture-device link. "
                "That is exactly how v0.1-beta1 shipped and had to be pulled.\n"
                "  Windows:       -DOPENSSL_ROOT_DIR=<vcpkg>/vcpkg_installed/x64-windows\n"
                "  macOS:         brew install openssl@3\n"
                "  Debian/Ubuntu: apt install libssl-dev\n"
                "If a transport-less artefact is genuinely intended, configure with "
                "-DPP_ALLOW_NO_PPCP=ON and say so in the release notes.")
        else()
            message(FATAL_ERROR
                "PP_SHIPPING_BUILD=ON but libppcp is not embedded, so this artefact would "
                "ship with NO PPCP transport — no phone pairing, no capture-device link.\n"
                "Check out github.com/PinPoint-Golf/libppcp beside this repository, or "
                "configure with -DPP_LIBPPCP_FETCH=ON.\n"
                "If a transport-less artefact is genuinely intended, configure with "
                "-DPP_ALLOW_NO_PPCP=ON and say so in the release notes.")
        endif()
    endif()
    if(NOT PP_OPENSSL_FOUND)
        message(WARNING
            "PPCP transport NOT built — OpenSSL development headers not found. "
            "The app will have no capture-device link. "
            "macOS: brew install openssl@3.  Debian/Ubuntu: apt install libssl-dev. "
            "Windows: vcpkg install openssl, or -DOPENSSL_ROOT_DIR=<path>.")
    else()
        message(WARNING
            "PPCP transport NOT built — libppcp is not embedded. "
            "Check out github.com/PinPoint-Golf/libppcp beside this repository, or "
            "configure with -DPP_LIBPPCP_FETCH=ON once it is public.")
    endif()
endif()

# ── Dependency version header for the About box ──────────────────────────────
# Generated LAST so every find_package / FetchContent version variable above is
# already resolved (the pp_version.h configure at the top runs too early for
# these). Feeds src/Core/app_info.cpp -> the About dialog's library list. Tag-
# pinned deps with no version variable are supplied as literals here (kept in
# lockstep with their FetchContent GIT_TAG above).
set(PP_WHISPER_VERSION    "1.7.2")   # whisper FetchContent GIT_TAG v1.7.2
set(PP_EIGEN_VERSION      "3.4.0")   # eigen  FetchContent GIT_TAG 3.4.0
set(PP_SAMPLERATE_VERSION "0.2.2")   # libsamplerate FetchContent GIT_TAG 0.2.2
configure_file(cmake/pp_deps.h.in "${CMAKE_BINARY_DIR}/generated/pp_deps.h" @ONLY)

# ── Windows installer packaging (CPack + Inno Setup) ─────────────────────────
# Must come last: include(CPack) snapshots the CPACK_* variables and component
# definitions set inside, and all install() rules must already be declared.
include(cmake/PinPointPackaging.cmake)