# Repository Guidelines

## Project Structure & Module Organization

This standalone Winelib helper forwards Wine accessibility events and NVDA/Tolk requests to Cthulhu’s session D-Bus service. Root sources include `main.cpp` (RPC, MSAA, event forwarding), `list_view.cpp`, and native hooks in `menu_hook.c` and `edit_hook.c`. Shared contracts live in headers and `nvdaController.idl`; generated RPC files belong under `build/generated/`. `tests/` holds C/C++ fixtures and the Python integration runner. Arch packaging lives in `distro-packages/ArchLinux/wine-access-git/`.

## Build, Test, and Development Commands

Requirements: CMake 3.20+, Wine development tools, GLib/GIO, pkg-config, and x86_64 MinGW GCC.

```sh
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=winelib-toolchain.cmake
cmake --build build --parallel
xvfb-run -a ctest --test-dir build --output-on-failure
python3 tests/menu_integration.py --build-dir build
```

These configure, compile, run the MSAA state check, and exercise menus respectively. Integration tests require PyGObject, `dbus-run-session`, and a graphical display; use `xvfb-run -a` for a private display.

`./build.sh` builds and installs to `$HOME/.local`; optional arguments specify build directory and installation prefix. For local operation, run `build/cthulhu-wine-access.exe` with Cthulhu’s D-Bus service active. Keep the executable, `.exe.so` sidecar, and hook DLL together.

## Coding Style & Naming Conventions

Follow existing style: two-space C/C++ indentation, four-space Python indentation, snake_case helper functions, camelCase local variables, and PascalCase structs. Preserve Windows API signatures and LGPL SPDX headers. C++ uses C++20; native hooks compile as C11 with `-Wall -Wextra`. No formatter is configured. Run `shellcheck build.sh` when editing that script. Use Wine Unicode APIs rather than Linux libc wide-character routines: Wine’s `wchar_t` is 16-bit.

## Testing Guidelines

CTest runs `tests/msaa_states_test.cpp`; integration assertions live in `tests/menu_integration.py`. Follow existing `*_fixture.c` and `*_test.cpp` names. Choose `--fixture edit`, `notepad`, `list`, or `winforms` for affected controls. Exercise editor lifecycle flags and `--fixture list --32-bit` where relevant; the latter needs i686 MinGW GCC. Run Xvfb checks sequentially. No numeric coverage threshold is configured.

Recorded events do not prove audible speech or physical braille. Follow `tests/README.md` for live acceptance and regression procedures, including password exclusion and focus restoration.

## Commit & Pull Request Guidelines

Recent commits use short imperative subjects describing behavior. Keep changes scoped; describe the problem, fix, commands run, and remaining live checks. Link relevant issues when available. Read the README’s AI-assisted contributions policy, review the diff, and test affected existing workflows before submission. Human review and submission remain the contributor’s responsibility.

## Installation Guidance

When someone asks for installation help:

- Confirm their Linux distribution and version, and whether they want a user-local or system-wide installation, unless they have already provided that information.
- Identify any missing dependencies and the correct package names for their distribution.
- Ask the user to install missing system packages. If a command requires `sudo`, ask the user to run it.
- Provide installation instructions tailored to their distribution and chosen installation scope.