better public interface and doxygen

1 files changed, 156 insertions, 0 deletions

diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..d01b82c
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,156 @@
+# Testing and examples
+
+Configure isolated Linux display-server integration tests with Weston and
+Xwayland installed:
+
+```sh
+meson setup build-test -Dintegration_tests=true
+meson test -C build-test --print-errorlogs
+```
+
+The harness starts and cleans up its own servers. It checks explicit requests,
+automatic selection, fallback, both backends in one process, frame lifetimes,
+callback copying, clipboard ownership, and timers. It also runs the beginner
+and tablet examples on both backends. On macOS the option enables native window,
+input ownership, keyboard/text/scroll, cursor, tablet, and example tests; these
+require a desktop session. Linux results do not verify Cocoa behavior.
+
+For memory/undefined-behavior checks use a separate build:
+
+```sh
+meson setup build-sanitize -Db_sanitize=address,undefined -Dintegration_tests=true
+meson test -C build-sanitize --print-errorlogs
+```
+
+Default tests need no desktop connection. C++ header coverage is built when a
+C++ compiler is available. On Linux and macOS, the shared-export test ensures
+only installed API declarations are exported. Test disabled-backend configurations separately with
+`-Dwayland=disabled` or `-Dx11=disabled`; the combined integration harness needs
+both backends.
+
+Keyboard tests check physical identities, distinct keypad/modifier keys, layout
+labels, Shift/Caps Lock, shortcut text suppression, AltGr, dead-key composition,
+repeat, and composition reset. The X11 integration test changes and restores
+the isolated server's keymap to verify that labels change while physical keys
+retain their identity. The X11 text fallback is also checked without an input
+method, including Latin-1, Cyrillic, and non-BMP characters encoded as UTF-8.
+Scroll tests cover both axes, fractional Wayland offsets,
+duplicate protocol representations, and X11 core/XInput wheel directions.
+Cocoa integration tests cover UTF-16 labels, modifier-only events, native text
+commit routing, and diagonal precise scrolling. Native IME interaction and
+hardware gestures still need testing on the target desktop.
+Clipboard tests cover Latin-1 interoperability, empty transfers, and rejection
+of malformed UTF-8 on Linux.
+
+## Cocoa validation
+
+On macOS 14 or newer, use a logged-in desktop session with a Metal-capable
+device. Configure `-Dintegration_tests=true`, compile, and run the full suite.
+Cross-compiling with an Apple SDK checks compilation and linking; run
+`meson test -C build-macos public-exports` to check the dylib's exports on the
+build machine. A cross file should provide an `nm` that can read Mach-O, such
+as `llvm-nm`. These checks do not execute the native window and input tests.
+
+To move an already compiled, unsanitized Cocoa suite to another Mac without
+rebuilding it:
+
+```sh
+python3 tests/helpers/package_cocoa_tests.py build-macos cocoa-tests.tar.gz
+```
+
+On the matching Mac, extract the archive and run:
+
+```sh
+tar -xzf cocoa-tests.tar.gz
+python3 yasl-cocoa-tests/run.py
+```
+
+The bundle includes the dylib, every executable test registered by Meson, and
+the license. The build-machine export check is separate. The runner checks file
+hashes, enforces each test's timeout, saves output under `logs/`, and writes
+`results.json`. A nonzero exit means validation failed. `--list` lists the
+bundled tests without running them. Use Python 3.8 or newer and a bundle matching
+its architecture; Apple Silicon uses `aarch64`, Intel uses `x86_64`.
+
+## Tablet drawing example
+
+Build and run the same C application on Wayland, X11, or Cocoa:
+
+```sh
+meson setup build
+meson compile -C build
+./build/yasl-tablet
+./build/yasl-tablet --backend wayland
+./build/yasl-tablet --backend x11
+# On macOS:
+./build/yasl-tablet --backend cocoa
+```
+
+Draw with the pen tip: pressure controls brush width. Flip to the eraser to
+remove ink. The window shows the selected backend, tool, contact state, raw
+pressure (0..65535), percentage, and tilt in degrees, with a live pressure bar,
+brush outline, and tilt vector. The system cursor is hidden so the brush overlay
+serves as the drawing cursor. Mouse drawing uses a fixed width. Press C or
+Space to clear and Escape to quit. Resizing and display scale changes preserve
+the drawing. `--smoke-test` presents one frame and exits for automated checks.
+
+[`examples/tablet.c`](../examples/tablet.c) includes only `<yasl/yasl.h>` and the C
+standard library. It uses CPU framebuffers and `yasl_surface_input_poll()` on
+every backend. Tablet events arrive as `YASL_INPUT_MOUSE`, distinguished by
+`mouse.device == YASL_PTR_DEV_PEN` or `YASL_PTR_DEV_ERASER`; `mouse.pen` contains
+pressure and signed tilt. Button 0 is tip contact on every backend. Track tip
+press/release events: zero pressure alone does not mean release. Hover and side
+buttons do not paint, and focus loss, leave, or `YASL_INPUT_RESET` cancels a stroke.
+Stationary pressure changes arrive as motion events and update the brush too.
+
+The example uses portable physical keys: C and Space clear, Escape exits.
+Letter names describe US positions, so the clear key follows the C position
+when the user selects another layout.
+
+`YASL_CAP_TABLET` indicates backend/protocol support, not whether a tablet is
+plugged in or which axes it has. Missing axes are zero. Wayland requires the
+compositor's `zwp_tablet_manager_v2`; X11 requires XInput 2 and driver-provided
+`Abs Pressure`/`Abs Tilt X`/`Abs Tilt Y` valuators. Cocoa handles both tablet mouse
+subtypes and native tablet point/proximity events. X11 identifies erasers by
+the Wacom tool property or the driver's device name. Hardware and driver
+support determine which readings are available. The example displays a message
+when the server has no tablet protocol and still allows mouse drawing.
+
+The test suite checks synthetic Wayland/XInput samples and the drawing behavior
+without hardware, including pressure-only changes, sparse axes, eraser input,
+hover, release, reset, and scale changes. Linux integration tests launch the
+example on isolated Wayland and X11 servers; macOS integration tests also check
+Cocoa tablet event translation. Physical tablet testing is still needed to
+validate a particular device/driver combination.
+
+For an end-to-end X11 pressure test without hardware, install Xorg's `dummy`
+video driver and `inputtest` input driver, then run:
+
+```sh
+meson configure build -Dx11_tablet_tests=true
+meson test -C build tablet-x11-native --print-errorlogs
+```
+
+This starts an isolated Xorg server with virtual pen and eraser devices, sends
+real driver samples, checks YASL's shared events through the example, and verifies
+its presented window pixels. It checks stationary pressure changes, release
+without valuators, and eraser identification through the driver's tool property.
+The test disables automatic physical input/GPU attachment and cleans up its
+server. Set `YASL_XORG_MODULE_PATH` to a comma-separated module search path if
+the test drivers are outside Xorg's default directories.
+
+## Benchmarks
+
+`yasl-benchmark` measures queue, timer, and surface-operation costs. Results
+depend on the build, backend, and display server; they do not measure confirmed
+screen presentation latency.
+
+```sh
+# Run via meson test runner
+meson test -C build --benchmark --verbose
+
+# Or invoke the executable directly
+ninja -C build tests/yasl-benchmark
+./build/tests/yasl-benchmark
+```
+