Simplify the public event and CPU API

Applications now need far less ceremony: hello.c is a 20-line loop that
handles REFRESH, CLOSE and QUIT and draws into the surface's own pixels.

- Fold GEOMETRY, STATE and FOCUS into one WINDOW event carrying size,
  scale and state; unchanged values send nothing.
- Guarantee REFRESH once a window has a size and after every resize,
  never at size zero.
- Merge DROP_HOVER into DROP with over/leave/data actions and give drag
  and drop actions enums.
- Keep event strings valid until the next wait and drop
  yasl_event_release; empty or failed waits report NONE.
- Replace copy-in presentation with a lent pixel buffer:
  yasl_cpu_pixels and yasl_cpu_present.
- Remove yasl_poll_event, yasl_cpu_read_pixels, unused event fields and
  comments that restated names.
- Wayland: resize floating windows in request_size instead of reporting
  it unsupported, and stop marking new GPU surfaces as Vulkan so
  yasl_vulkan_create_surface no longer fails with NATIVE_WINDOW_IN_USE.

Also includes the in-progress public API refactor that was uncommitted
in the tree (removal of the app/loop layer, new surface, GL and Vulkan
entry points).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 23 insertions, 143 deletions

diff --git a/docs/testing.md b/docs/testing.md
index bd3f2f0..ce2082f 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,156 +1,36 @@
-# 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 public 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:
+# Tests
 
 ```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
+meson test -C build --print-errorlogs
 ```
 
-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 `<yasl/app.h>` and the C
-standard library. It uses `yasl_run()`, frame callbacks, and unified input events
-on every backend. Tablet button and motion events retain `device`, which is
-`YASL_PTR_DEV_PEN` or `YASL_PTR_DEV_ERASER`; their `pen` member 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_EVENT_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.
+Tests cover public static/shared C and C++11 consumers, exact shared exports,
+queue ownership/order/destruction, UTF-8, GL attributes, private native event loops,
+clipboard, IME editing, pointer/pen coherence, cursor, and popup positioning. Native
+unit fixtures deliberately use private implementation headers; applications must use
+installed public headers.
 
-`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:
+For private Linux display servers and actual GPU presentation, install Weston,
+Xwayland, EGL/wayland-egl, and Vulkan/Mesa software drivers, then:
 
 ```sh
-meson configure build -Dx11_tablet_tests=true
-meson test -C build tablet-x11-native --print-errorlogs
+meson configure build -Dintegration_tests=true
+meson compile -C build
+meson test -C build --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
+The integration harness starts its own headless GL Weston and Xwayland, runs public
+surface ownership/CPU damage/wakeup/refresh checks, GL drawing/readback/context-sharing/
+resize, Vulkan swapchain clear/present, and example smoke tests. It selects Mesa
+software rendering and Lavapipe when available. It needs permission to create local
+Unix sockets. A sandbox blocking those sockets is not a backend test result.
 
-`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
-```
+`-Dx11_tablet_tests=true` additionally uses Xorg dummy/inputtest drivers for pen input
+without physical hardware. These are separate from the compositor-free native unit
+fixtures. Cocoa integration tests run only on macOS and need the native SDK/display.
+Linux results do not validate Cocoa compilation or runtime.
 
+For memory/undefined-behavior checks use a separate build with `-Db_sanitize=address,undefined`
+and run the same suites. Keep sanitizer builds isolated from the normal build.