refactor: simplify public API and isolate native extensions

Separate loop/timer and native interoperability APIs from the portable surface header. Unify dispatch, geometry queries, and timer callbacks; keep framebuffer bookkeeping and frame clocks private, and hide implementation symbols.

Update backends, documentation, examples, and API/integration coverage. Verify exports, strict C/C++ installed consumers, and normal plus ASan/UBSan suites.

1 files changed, 33 insertions, 8 deletions

diff --git a/README.md b/README.md
index 6fc8848..4b961ef 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,25 @@ 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.
 
+## Public API
+
+Include `<yasl/yasl.h>` for surface creation, drawing, input, and display dispatch.
+`yasl_surface_geometry()` returns device-pixel size and scale together.
+`yasl_display_dispatch(display, timeout_ms)` polls with zero, waits indefinitely
+with a negative timeout, or waits up to a positive number of milliseconds.
+Pending input or redraw work returns immediately; call `yasl_display_flush()`
+after processing input and scheduling redraws.
+
+Include `<yasl/loop.h>` to use the optional event loop, file watches, or timers.
+Timers use one callback model and nanoseconds throughout; use `YASL_MS_TO_NS(5)`
+for a five-millisecond interval. Add application timers to
+`yasl_display_loop(display)`. Add surface timers with `yasl_surface_add_timer()`
+when they should be canceled automatically on surface destruction.
+
+Include `<yasl/native.h>` for platform handles and application-managed native
+rendering. These extensions are separate from the portable CPU drawing API.
+`<yasl/timing.h>` contains the public timing result types.
+
 ## Backend selection
 
 YASL selects the native window backend at runtime.
@@ -58,6 +77,8 @@ 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.
+Shared libraries export only the functions declared in the installed YASL headers.
+Input queues, frame clocks, backend entry points, and protocol helpers are private implementation details.
 Use `yasl_display_caps()` to check optional features.
 
 X11 supports CPU pixel buffers, keyboard and pointer input, and clipboard transfer.
@@ -67,14 +88,18 @@ 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.
+An app that renders with Metal includes `<yasl/native.h>` and calls
+`yasl_surface_create_native(display, &spec, device)`. During its draw callback,
+`yasl_surface_get_native_frame()` returns the current Metal drawable. The app
+submits and presents it, then calls `yasl_surface_present()` to record submission.
 
 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 *`.
+On Cocoa, the native display handle is `NSApplication *` and the surface handle
+is `NSWindow *`. Access its view through `window.contentView`. Native getters
+are declared only in `<yasl/native.h>`; handles are borrowed until destruction.
 
 ## Ownership and backend contracts
 
@@ -104,10 +129,10 @@ On Cocoa, the native surface handle is the content `NSView *`.
 - Present only the current draw callback's target, at most once. Targets expire
   when the callback returns; preserve the opaque `generation` when copying a
   target. Damage is required, clipped to the target, and validated uniformly. Backends may upload the whole frame despite damage hints.
-- A non-NULL `graphics_device` requires `YASL_CAP_NATIVE_GRAPHICS` (currently
-  Cocoa); other backends reject it with `ENOTSUP`. In native Metal mode the app
-  submits and presents the drawable, then calls `yasl_surface_present()` to
-  record that submission.
+- `yasl_surface_create_native()` requires `YASL_CAP_NATIVE_GRAPHICS` (currently
+  Cocoa) and a non-NULL graphics device; other backends return `ENOTSUP`. Native
+  drawable queries are valid only for the current draw target and expire on
+  successful present, callback return, or surface destruction.
 - `YASL_CAP_FRAME_PACING` distinguishes compositor/display-driven draws from
   X11's unpaced flush-driven draws. `yasl_timing.source` distinguishes submission
   estimates, frame callbacks, and confirmed presentation feedback. Refresh and
@@ -191,7 +216,7 @@ int main(void)
     yasl_surface_schedule_redraw(s);
 
     while (running) {
-        yasl_display_dispatch(d);
+        yasl_display_dispatch(d, -1);
         struct yasl_input_event ev;
         while (yasl_surface_input_poll(s, &ev)) {
             if (ev.kind == YASL_INPUT_KEY && ev.key.action == YASL_KEY_PRESS) {