rename and simplification

1 files changed, 17 insertions, 2 deletions

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