Let yasl_app_desc describe its initial window

A new optional yasl_app_desc.window spec makes yasl_run() create that
toplevel and request its first frame before init(), which is now
optional too. If creation fails, yasl_run() closes the display and
returns an error without calling init().

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

2 files changed, 8 insertions, 4 deletions

diff --git a/docs/guide.md b/docs/guide.md
index f195e5e..a65972f 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -40,8 +40,11 @@ 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_app_desc`. Set `window` to a `yasl_window_spec` for a single toplevel,
+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, 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
diff --git a/docs/migrating.md b/docs/migrating.md
index e1f5442..86804c8 100644
--- a/docs/migrating.md
+++ b/docs/migrating.md
@@ -6,8 +6,9 @@ See the [application guide](guide.md) for the full window and input workflow.
 
 ## Application callbacks
 
-All examples now use `<yasl/app.h>` and `yasl_run()`. Move window creation to
-`yasl_app_desc.init`, input handling to `.event`, and drawing to `.frame`.
+All examples now use `<yasl/app.h>` and `yasl_run()`. Describe a single window
+in `yasl_app_desc.window`, or create windows in `.init`; move input handling to
+`.event` and drawing to `.frame`.
 Replace manual dispatch/poll/flush loops with the runner and request redraws with
 `yasl_surface_request_frame()`. Present the frame context with
 `yasl_frame_present_cpu()`; the runner destroys remaining surfaces on exit.