rename and simplification

4 files changed, 42 insertions, 7 deletions

diff --git a/docs/api-policy.md b/docs/api-policy.md
index d5c7159..0c8f040 100644
--- a/docs/api-policy.md
+++ b/docs/api-policy.md
@@ -12,8 +12,8 @@ across releases, mix headers and binaries from different revisions, or persist
 public structs as a file/network format. The package version is available through
 `pkg-config --modversion yasl`.
 
-See [migration notes](migrating.md) for the portable keyboard and fractional
-scroll API changes.
+See [migration notes](migrating.md) for window creation, portable keyboard, and
+fractional scroll API changes.
 
 API changes should keep ordinary CPU drawing usable with only `<yasl/yasl.h>`
 and the C standard library. Prefer an explicit capability and an ordinary
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ff40a9b..d21c9bd 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -78,9 +78,11 @@ can be included from C++11 or newer; the library itself builds as C23.
 
 1. Open a display with `yasl_display_open(NULL, &spec)`. NULL creates a loop owned
    by the display. Supply your own loop only when you need shared loop ownership.
-2. Create a toplevel with a positive **logical-pixel** size and install callbacks.
+2. Create a toplevel with `yasl_window_spec`: supply a positive **logical-pixel**
+   size, a `yasl_window_cbs` table in `cbs`, and callback userdata in `ud`.
    Zero-initialize every option and callback struct. Callback tables are copied;
-   userdata must remain alive. Registration can call back synchronously.
+   userdata must remain alive. The new window's callbacks start after creation
+   returns. Read initial geometry with `yasl_surface_geometry()`.
 3. Schedule the initial redraw. `draw` receives a borrowed target. Fill every
    pixel with premultiplied `0xAARRGGBB`, then present that exact target, once.
 4. Dispatch, drain input for every live surface queue, update application state,
diff --git a/docs/guide.md b/docs/guide.md
index 43a7a1e..adcacc8 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -37,11 +37,29 @@ server. A capability does not guarantee every related action: Cocoa currently
 returns false for interactive resize and window-menu requests even though
 it advertises CSD. Check each result and provide an application fallback.
 
+## Window creation and callbacks
+
+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
+`ud`. One display can own multiple windows with separate callback tables.
+
+The window copies its callbacks during creation. Its callbacks cannot run before
+creation returns, so the application can store the returned surface first.
+Userdata stays borrowed until callbacks are replaced or the surface is destroyed.
+Read initial geometry with `yasl_surface_geometry()`; creation does not guarantee
+an initial `configure` notification. Request the first redraw once application
+state is ready. `yasl_surface_set_callbacks()` replaces callbacks later and also
+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`.
+
 ## Geometry and scaling
 
 | Value | Units |
 | --- | --- |
-| Toplevel `yasl_surface_spec.size` | Logical pixels |
+| Toplevel `yasl_window_spec.size` | Logical pixels |
 | `yasl_geometry.size`, framebuffer size | Device pixels |
 | Pointer position, caret, window-menu position | Device pixels, relative to the surface |
 | Damage rectangles | Device pixels, relative to the draw target |
diff --git a/docs/migrating.md b/docs/migrating.md
index d224cd4..da4e591 100644
--- a/docs/migrating.md
+++ b/docs/migrating.md
@@ -2,8 +2,23 @@
 
 YASL 0.1 has no stable source or binary compatibility promise. Rebuild all
 consumers against the matching installed headers and library after updating.
-The following changes replace backend-specific input fields with a common
-contract. See the [application guide](guide.md) for the full input workflow.
+See the [application guide](guide.md) for the full window and input workflow.
+
+## Window creation
+
+Rename `struct yasl_surface_spec` to `struct yasl_window_spec` and
+`struct yasl_surface_cbs` to `struct yasl_window_cbs`. Surface handles and
+functions retain their names. Supply the window's callback table in `spec.cbs`
+and its userdata in `spec.ud` when calling `yasl_surface_create_toplevel()` or
+`yasl_surface_create_native()`. Callback tables are copied, and userdata is
+borrowed. The new window's callbacks cannot run before creation returns; read
+initial geometry with `yasl_surface_geometry()` and request the first redraw
+after initializing application state.
+
+`yasl_surface_set_callbacks()` remains available to replace callbacks after
+creation and to configure popups. A NULL `spec.cbs` creates a window without
+callbacks. Displays owned by `yasl_run()` use the runner's callbacks instead;
+provide application notifications through `yasl_app_desc.event` and `.frame`.
 
 ## Keyboard events