Merge branch 'backend-selection' into main

- Implement runtime backend selection (Wayland, X11, Cocoa)
- Add native X11 backend with clipboard, keyboard, mouse, and placement
- Integrate multi-backend integration tests running under Weston and Xwayland
- Retain zero-hole struct packing, branchless ALU/LUT primitives, and paced event loop

1 files changed, 74 insertions, 0 deletions

diff --git a/README.md b/README.md
index ee061b9..7a5f06d 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,61 @@ It provides window creation, frame pacing, high-DPI scaling, and input routing w
   - Self-contained event queue.
   - No terminal-specific telemetry or hardcoded application names.
 
+## Backend selection
+
+YASL selects the native window backend at runtime.
+Leave `yasl_display_spec.backend` at zero to use this mode.
+`YASL_BACKEND_AUTO` has the same effect.
+You can also pass NULL as the display spec.
+
+On Linux, YASL tries Wayland first in a Wayland session.
+It uses `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, and `XDG_SESSION_TYPE` to detect that session.
+In other sessions, it tries X11 first.
+If the first backend cannot open, it tries the other built backend.
+On macOS, it uses Cocoa.
+
+Set `backend` to request one backend:
+
+```c
+struct yasl_display_spec spec = {
+    .app_id = "org.example.app",
+    .backend = YASL_BACKEND_X11,
+};
+struct yasl_display *display = yasl_display_open(loop, &spec);
+```
+
+Use `YASL_BACKEND_WAYLAND` to request Wayland.
+Use `YASL_BACKEND_COCOA` to request Cocoa.
+An explicit request never falls back to another backend.
+Open returns NULL if the requested backend cannot open.
+It sets `errno` to `ENOSYS` for a backend that was not built.
+It sets `errno` to `EINVAL` for an invalid backend value.
+
+Call `yasl_display_backend(display)` to read the selected backend.
+All surfaces on a display use that backend.
+Open separate displays to use Wayland and X11 in one process.
+The public API needs no window system headers.
+Use `yasl_display_caps()` to check optional features.
+
+X11 supports CPU pixel buffers, keyboard and pointer input, and clipboard transfer.
+It supports the primary selection and window placement.
+It does not yet support YASL popups, drag operations, or IME preedit text.
+Those features return their normal unsupported result.
+
+The surface spec needs no native graphics device for CPU drawing.
+On Cocoa, YASL creates its own Metal device for this mode.
+An app that renders with Metal can supply its device through `graphics_device`.
+That app submits and presents the native drawable.
+
+The native display handle is a `wl_display *` on Wayland.
+It is a `Display *` on X11.
+The native surface handle is a `wl_surface *` on Wayland.
+On X11, convert it to `Window` through `uintptr_t`.
+On Cocoa, the native surface handle is the content `NSView *`.
+
 ## Building
 
+Use a C23 compiler and Meson 1.6 or later.
 Build with Meson and Ninja:
 
 ```sh
@@ -34,6 +87,27 @@ ninja -C build
 ninja -C build test
 ```
 
+Linux builds include each backend whose dependencies are installed.
+Wayland needs `wayland-client`, `wayland-cursor`, and `xkbcommon`.
+X11 needs `x11` and `xkbcommon`.
+Use `-Dwayland=enabled` or `-Dx11=enabled` to require a backend.
+Use `-Dwayland=disabled` or `-Dx11=disabled` to omit a backend.
+At least one backend must be built.
+
+To run the Linux window tests, install Weston and Xwayland.
+Then run:
+
+```sh
+meson setup build-test -Dintegration_tests=true
+meson test -C build-test --print-errorlogs
+```
+
+The tests start isolated display servers.
+They test explicit requests, automatic selection, and fallback.
+They also test both backends in one process.
+On macOS, the same option runs native Cocoa window tests.
+These tests need a desktop session.
+
 ## Quick Example
 
 ```c