public api refactor

1 files changed, 91 insertions, 58 deletions

diff --git a/docs/guide.md b/docs/guide.md
index 76279c4..1b64880 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -44,13 +44,21 @@ All examples include `<yasl/app.h>` and call `yasl_run()` with a
 which the runner creates before `init` with its first frame requested;
 `yasl_run()` returns an error if creation fails. Create further surfaces in the
 optional `init`, handle `YASL_EVENT_*` notifications in `event`, and render into
-`frame->cpu.pixels` in `frame`. Present with `yasl_frame_present_cpu(frame, NULL,
+`frame->target.pixels` in `frame`. Present with `yasl_frame_present(frame, NULL,
 0)` and return `YASL_APP_QUIT` from an event handler to exit. Without an `event`
-callback, closing any window stops the runner. The runner handles dispatch, input polling, resize redraws,
+callback, closing any window stops the runner. The runner handles dispatch, queued event delivery, resize redraws,
 and remaining surface/display cleanup. Display quit stops the runner; connection
 loss and dispatch failures return an error after cleanup. The runner delivers
-input exactly as `yasl_surface_poll_event()` returns it, plus
-`YASL_EVENT_WINDOW_RESIZE`, `YASL_EVENT_WINDOW_CLOSE`, and `YASL_EVENT_USER`.
+the same display-wide FIFO consumed by `yasl_display_poll_event()`, including
+window state, drag hover, composition, clipboard completion, and display lifecycle
+events. `event.sequence` increases in enqueue order across all windows; it is
+YASL capture order, not a claim about ordering between native producers.
+Return `YASL_APP_ERROR` on application failure, or call
+`yasl_app_exit(display, YASL_APP_ERROR)` from a frame, timer, or fd callback.
+Cleanup still runs, and `yasl_run()` returns failure. During `init`,
+`yasl_app_window(display)` exposes the optional initial window. Application data
+can be supplied in `window.userdata` or attached with
+`yasl_surface_set_userdata()`; it is independent of callback userdata.
 
 Unified pointer button and motion events retain `device` and `pen` axes,
 including erasers and pressure-only motion. Cancel held input or active strokes
@@ -62,7 +70,7 @@ For applications managing their own event loop, use the core API below.
 
 Open the display with application-wide options and notifications in
 `yasl_display_spec`. Create each toplevel with `yasl_window_spec`, including its
-title, logical size, optional `yasl_window_cbs` table in `cbs`, and userdata in
+title, `size_logical`, optional `yasl_window_cbs` table in `cbs`, and userdata in
 `ud`. One display can own multiple windows with separate callback tables.
 
 The window copies its callbacks during creation. Its callbacks cannot run before
@@ -75,6 +83,9 @@ installs popup callbacks; the setter does not invoke the callbacks.
 
 When using `yasl_run()`, its runner installs callbacks for windows on its display.
 Use `yasl_app_desc.event` and `.frame` rather than `yasl_window_spec.cbs` and `.ud`.
+Replacing callbacks on a runner-owned surface fails with `EBUSY`.
+With a manual loop, install just the draw callback and drain the display FIFO
+after dispatch; lifecycle and input share the same event handler logic.
 
 Read window state with `yasl_surface_state()`. Its `YASL_STATE_*` flags can
 coexist, and the `state` callback receives the same current bitmask. Wayland
@@ -114,7 +125,7 @@ saturates out-of-range finite results, and returns zero for a zero scale.
 
 ## Drawing and pacing
 
-`yasl_surface_schedule_redraw()` coalesces requests. `yasl_display_flush()`
+`yasl_surface_request_frame()` coalesces requests. `yasl_display_flush()`
 services them when the backend can draw. During a native resize, dispatch can
 also draw synchronously. Avoid assuming callbacks occur only in flush.
 
@@ -132,27 +143,27 @@ static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *u
     size_t count = (size_t)frame->target.size.x * frame->target.size.y;
     for (size_t i = 0; i < count; i++)
         frame->target.pixels[i] = 0xff306090;
-    struct yasl_damage_list damage = {.n = -1};
-    if (!yasl_surface_present(surface, &frame->target, &damage)) {
+    if (!yasl_frame_present(frame, NULL, 0)) {
         /* Arrange application error handling after returning. */
     }
 }
 ```
 
-Present that exact target at most once during draw. Do not change its pointer,
-size, or generation, free it, or use it after callback return or surface
-destruction. A successful present consumes it. Invalid input returns false
-without consuming it. `damage.n = -1` means full target; `0` means no damaged
-rectangles; positive `n` uses the first `n` entries in `rects`. Extents must be
-nonnegative, and the core clips them to the target. `bounds` is a reserved hint
-and can be zero. Damage may reduce uploads, but every target must still contain
-complete valid content; backends may upload all pixels.
-
-To animate, schedule again from draw. With `YASL_CAP_FRAME_PACING`, the backend
-uses display/compositor signals to limit draws; tearing can bypass this. X11
-is unpaced: scheduling continuously will use CPU continuously. Use an application
-timer to limit redraws there. Suspended/hidden windows need not draw at each
-requested interval.
+Present the exact active frame at most once during its callback. Do not mutate
+the target identity or retain frame/pixel pointers after return. NULL rectangles
+with count zero mean full damage; a non-NULL array with zero count means no damage.
+All supplied extents must be nonnegative. Rectangles are clipped, and more than
+`YASL_DAMAGE_MAX` rectangles fall back to full damage after all are validated.
+Damage may reduce uploads, but every target must contain complete valid pixels.
+Native rendering uses the same frame, with a drawable queried in the extension.
+
+`yasl_surface_set_pacing()` works in either loop style. ON_DEMAND coalesces
+explicit requests and sleeps when idle. CONTINUOUS uses native display signals
+where available and a refresh-based timer otherwise, with about 60 Hz as a
+fallback estimate. It reports allocation/argument failures instead of silently
+ignoring surfaces outside the runner. Suspension can suppress actual drawing.
+Legacy `yasl_surface_present()` and `yasl_surface_schedule_redraw()` remain
+migration adapters; new code uses the frame presentation and request functions.
 
 `yasl_surface_read_pixels()` copies the last presented CPU frame, for example
 for a screenshot or a debugging tool. Call it outside draw callbacks. A frame
@@ -170,19 +181,20 @@ clock; it does not establish actual scanout time.
 
 ## Input, text, and payload lifetime
 
-Dispatch receives native input. `yasl_surface_poll_event()` only drains it and
-never waits. Poll every live surface queue until empty. Wayland routes popup
-pointer and keyboard events through the root parent's queue; inspect
-`event.surface` to identify the recipient. Do not assume it equals the object
-whose queue you polled.
-
-Read the union member selected by `event.type`; `time_ns` is a monotonic
-timestamp on the `yasl_loop_now_ns()` clock. Polling returns only input types,
-`YASL_EVENT_KEY` through `YASL_EVENT_INPUT_RESET`. Text, paste, and file-drop
-payloads share `event.text`: UTF-8 byte strings, NUL-terminated; `len` excludes
-the NUL. They remain valid until the
-next **successful** poll on the queue or queue destruction. Dispatch, flush,
-and unsuccessful polls do not invalidate them. Copy data to keep it longer.
+Dispatch receives native input; `yasl_display_poll_event()` drains the display
+FIFO without waiting. Drain it once for the whole display, including multiple
+windows and popup input. `event.surface` identifies the live recipient and
+`surface_id` is its stable identity. Destruction cancels undelivered recipient
+events. `yasl_surface_poll_event()` remains an input-only migration adapter and
+discards pending non-input notifications, which legacy callbacks already
+delivered. Do not mix the two polling styles.
+
+Read the union member selected by `event.type`. `time_ns` is monotonic and
+`sequence` orders capture across the display. TEXT and DROP use `.text`, PASTE
+uses `.paste`, and COMPOSITION uses `.composition`. Each string is copied when
+queued, NUL-terminated, and borrowed until the next successful display/surface
+poll or display close. Dispatch, unsuccessful polls, and recipient destruction
+do not invalidate the last polled string. Copy it to retain it longer.
 
 Use `YASL_EVENT_TEXT` for document text insertion, including committed IME text.
 It contains UTF-8 and can contain several characters. Key actions are for
@@ -265,19 +277,22 @@ device interruptions; ignoring it can leave application input stuck.
 
 ## Clipboard, file drops, and IME
 
-`yasl_display_copy()` copies a NUL-terminated UTF-8 string during the call.
-`yasl_display_paste()` requests delivery to the original target as
-`YASL_EVENT_PASTE`; destroying the target cancels delivery. There is no transfer
-ID or error callback, so unavailable or failed transfers may produce no event.
-Wayland selection offers can require a recent input serial. X11 currently does
-not implement incremental (`INCR`) selection transfers and may reject large
-transfers. X11 converts legacy `STRING` data between Latin-1 and UTF-8; it only
-offers that legacy format when the copied text fits Latin-1. Malformed UTF-8
-clipboard transfers are discarded. Unsupported primary selection does nothing
-and never aliases the clipboard. Cocoa uses a YASL named pasteboard to emulate primary selection;
-this is not a desktop-wide macOS select-to-copy convention.
-
-External file drag hover uses the surface `drop` callback; actual file URLs
+`yasl_clipboard_set(display, selection, text)` copies a NUL-terminated UTF-8
+offer and reports failure through its return and errno. Wayland may require a
+recent input serial. `yasl_clipboard_request(surface, selection)` returns a
+nonzero request ID, or zero with errno when rejected. Each accepted request
+produces one `YASL_EVENT_PASTE` carrying `.paste.request_id`, `.status`, `.data`,
+and `.len`, unless its target/display is destroyed. OK includes empty text;
+UNAVAILABLE means no text offer, and FAILED means transfer/decoding failure.
+External Linux transfers have a 30-second timeout. X11 does not implement INCR
+and reports unsupported large transfers as FAILED. Legacy STRING uses Latin-1
+conversion. Malformed UTF-8 completes as failure.
+
+Unsupported primary selection reports ENOTSUP and never aliases the clipboard.
+Cocoa uses a YASL named pasteboard for primary selection. Legacy copy/paste calls
+remain adapters; legacy paste completions carry request ID zero.
+
+External file drag hover uses `YASL_EVENT_DROP_HOVER`; actual file URLs
 arrive as `YASL_EVENT_DROP`. `text.data` is a `text/uri-list` string separated by
 CRLF, not a list of native paths. `yasl_drop_next_path()` walks it and decodes
 each local `file:` URL into a path. It skips comments, other schemes, remote
@@ -296,12 +311,12 @@ while ((len = yasl_drop_next_path(&cursor, path, sizeof(path))) != 0) {
 Decoded paths are raw bytes and may contain any character the file system
 allows, including newlines. Quote them before pasting into a shell.
 
-Use `yasl_surface_ime_preedit()` to draw the uncommitted composition. The borrowed
-pointer expires on the next dispatch or surface destruction; copy to keep it.
-Set the candidate-window caret with `yasl_surface_set_ime_caret()` in device
-pixels. X11 has no inline preedit. Cocoa supplies preedit text but currently no
-cursor range. On Wayland, `yasl_surface_ime_preedit_cursor()` returns UTF-8 byte
-offsets when a range is available. A false result leaves outputs unchanged.
+Handle `YASL_EVENT_COMPOSITION` for immutable UTF-8 preedit snapshots, byte
+selection offsets, and composition ending. Missing selection information uses
+-1 offsets. Insert only committed `YASL_EVENT_TEXT` into the document. Set the
+candidate-window caret with `yasl_surface_set_ime_caret()` in device pixels.
+X11 uses XIM preedit callbacks when offered; fallback input methods may provide
+no inline composition. The old preedit getters remain migration helpers.
 
 ## Popups and surface drags
 
@@ -315,8 +330,8 @@ serial to grab a popup, and older protocols may reject repositioning. Destroy
 children before parents. The close callback requests application destruction;
 it does not automatically free the popup.
 
-The surface `drag` callback handles a YASL surface drag; `drop` handles external
-data hover. `yasl_display_drag_start()` is intended for window/tab tear-off
+`YASL_EVENT_DRAG` handles a YASL surface drag; `YASL_EVENT_DROP_HOVER` handles
+external data hover. Legacy callbacks remain migration adapters. `yasl_display_drag_start()` is intended for window/tab tear-off
 workflows, not arbitrary MIME data sources. Keep transferred application state
 in your own registry. Start from a recent pointer press, and check the boolean
 result even when `YASL_CAP_DRAG` is present. Supply an optional copied image and
@@ -367,7 +382,7 @@ Every backend's dispatch wakes when a loop descriptor becomes ready. Cocoa
 waits for native events and mirrors the loop's descriptors in a kqueue while it
 waits. If kqueue rejects a descriptor, Cocoa bounds the wait to 10 ms instead.
 
-Two calls work from any thread. `yasl_loop_kick()` only wakes the loop, and it
+Loop wake and post calls work from any thread. `yasl_loop_kick()` only wakes the loop, and it
 is also safe in a signal handler. `yasl_loop_post()` queues a function to run
 on the owning thread during a later step or dispatch. Use it to hand results
 from worker threads to the loop:
@@ -387,6 +402,24 @@ and restores the previous action on unwatch. YASL leaves thread signal masks
 alone: a watched signal must stay unblocked in at least one thread. Only one
 loop can watch a given signal at a time.
 
+## Worker messages and window requests
+
+Capture `yasl_surface_id(surface)` on the display thread and pass that value to
+workers. `yasl_display_post(display, &message)` accepts an identity instead of a
+borrowed surface pointer. Zero targets the display. On success, optional
+`message.release(payload)` runs exactly once on the display thread after delivery
+or cancellation, including shutdown. It may post messages but must not poll,
+dispatch, or destroy YASL objects. Failed posting leaves ownership with the caller.
+Stop and join producers before closing the display. The same API works with a
+manual loop and with the runner; `yasl_post_event()` is a legacy adapter.
+
+Toplevel requests `yasl_surface_set_size(surface, logical_size)`,
+`yasl_surface_set_fullscreen`, `yasl_surface_set_maximized`, and
+`yasl_surface_minimize` return acceptance with errno on failure. Confirm actual
+geometry/state through queued events. Popup targets are invalid. Wayland cannot
+request an arbitrary live size and returns ENOTSUP for that operation; fullscreen,
+maximize, and minimize use xdg-shell requests. X11 and Cocoa implement all four.
+
 ## Desktop services
 
 Include `<yasl/desktop.h>` for services that sit next to windowing. Display and
@@ -436,7 +469,7 @@ dispatch native connections, or change surface roles and buffer ownership.
 Application-managed native drawing currently supports Cocoa/Metal. Use
 `yasl_surface_create_native()` with a non-NULL Metal device, which YASL retains.
 During draw, query `yasl_surface_get_native_frame()` for a borrowed drawable,
-encode and present with your renderer, then call `yasl_surface_present()` to
+encode and present with your renderer, then call `yasl_frame_present()` to
 record submission. The drawable expires on successful present, callback return,
 or surface destruction. Do not infer GPU completion from the boolean result.
 Other backends return NULL with `errno = ENOTSUP` for native creation; having a