Simplify surface state, examples, and library installation

1 files changed, 25 insertions, 1 deletions

diff --git a/docs/guide.md b/docs/guide.md
index adcacc8..1bd1aef 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -39,6 +39,22 @@ it advertises CSD. Check each result and provide an application fallback.
 
 ## Window creation and callbacks
 
+All examples include `<yasl/app.h>` and call `yasl_run()` with a
+`yasl_app_desc`. Create surfaces in `init`, handle `YASL_EVENT_*` notifications
+in `event`, and render into `frame->cpu.pixels` in `frame`. Present with
+`yasl_frame_present_cpu(frame, NULL, 0)` and return `YASL_APP_QUIT` from an event
+handler to exit. The runner handles dispatch, input polling, resize redraws,
+and remaining surface/display cleanup. Display quit stops the runner; connection
+loss and dispatch failures return an error after cleanup.
+
+Unified pointer button and motion events retain `device` and `pen` axes,
+including erasers and pressure-only motion. Cancel held input or active strokes
+on `YASL_EVENT_INPUT_RESET`, pointer leave, or focus loss. Reset also starts the
+next motion delta from zero. [hello.c](../examples/hello.c) shows the minimal
+lifecycle; [tablet.c](../examples/tablet.c) demonstrates device-aware drawing.
+
+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
@@ -55,6 +71,14 @@ 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`.
 
+Read window state with `yasl_surface_state()`. Its `YASL_STATE_*` flags can
+coexist, and the `state` callback receives the same current bitmask. Wayland
+also reports `YASL_STATE_TILED` when any window edge is tiled; X11 and Cocoa
+currently leave that flag unset. Unsupported flags are absent. On Wayland, an
+ordinary floating toplevel has fullscreen, maximized, and tiled all absent.
+`YASL_STATE_SUSPENDED` describes repaint suspension rather than minimization;
+there is no portable minimized flag.
+
 ## Geometry and scaling
 
 | Value | Units |
@@ -301,7 +325,7 @@ signals the loop pipe but is not a portable cross-thread event-posting API.
 
 Portable CPU drawing needs no native headers. Opt into `<yasl/native.h>` and
 `<yasl/native/wayland.h>`, `<yasl/native/x11.h>`, or `<yasl/native/cocoa.h>` when
-integrating a platform API. Typed headers and functions are installed only for
+integrating a platform API. Typed native functions are exported only for
 built backends. Accessors return borrowed handles and zero/NULL for the wrong
 backend. Do not pass freed objects, destroy borrowed handles, independently
 dispatch native connections, or change surface roles and buffer ownership.