# Migrating pre-release applications

YASL 0.1 has no stable source or binary compatibility promise. Rebuild all
consumers against matching public headers and the library after updating.
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`.
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.

Window state remains a `YASL_STATE_*` bitmask; `YASL_STATE_TILED` is reported
for tiled Wayland toplevels.

## Events

The core API and the runner now share one `struct yasl_event`, declared in
`<yasl/yasl.h>`. `yasl_surface_poll_event()` returns the same events that
`yasl_app_desc.event` receives, so input handling code works under both.

| Previous use | Replacement |
| --- | --- |
| `yasl_surface_input_poll()`, `struct yasl_input_event` | `yasl_surface_poll_event()`, `struct yasl_event` |
| `event.kind`, `YASL_INPUT_*` | `event.type`, `YASL_EVENT_*` |
| `YASL_INPUT_MOUSE` with `mouse.kind` | `YASL_EVENT_POINTER_DOWN`, `_UP`, `_MOTION`, `_SCROLL`, `_LEAVE` with `event.pointer` |
| Runner `YASL_EVENT_MOUSE_BUTTON` with `pressed` | `YASL_EVENT_POINTER_DOWN` / `_UP` |
| Integer `button` 0/1/2 | `YASL_BUTTON_PRIMARY`, `_MIDDLE`, `_SECONDARY`, `_BACK`, `_FORWARD` |
| `paste.text`, `drop_files.files`, `text.text` | `text.data` for `PASTE`, `DROP`, and `TEXT` |
| `YASL_INPUT_DROP_FILES` / `YASL_EVENT_DROP_FILES` | `YASL_EVENT_DROP` |
| `YASL_EVENT_WINDOW_FOCUS` | `YASL_EVENT_FOCUS` |
| `YASL_EVENT_WINDOW_SCALE_CHANGED` | `YASL_EVENT_WINDOW_RESIZE` with `resize.scale_changed` |
| `YASL_EVENT_WINDOW_CLOSE_REQUEST` | `YASL_EVENT_WINDOW_CLOSE` |
| `user.type` | `user.code` |
| `key.repeat` | `key.action == YASL_KEY_REPEAT` |
| `yasl_surface_set_mouse_mode()` | `yasl_surface_set_pointer_mode()` |

Every event carries a monotonic `time_ns`. Pointer motion carries `delta` on
both paths. Handle `YASL_EVENT_INPUT_RESET` by clearing held input and active
strokes.

## 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

| Previous use | Replacement |
| --- | --- |
| Linux keysym or Cocoa virtual keycode in `key.key` | Portable physical `YASL_KEY_*` identity |
| `key.base` | `key.native_code`, with explicit backend-specific encoding |
| `key.keypad` | Distinct `YASL_KEY_KP_*` identities |
| Advisory `key.text` character | `YASL_EVENT_TEXT` UTF-8 payload for insertion |
| Layout label from a keysym | Optional `key.codepoint` and `key.shifted` Unicode scalars |

Replace magic numbers and X11 symbols with named keys. For example, a quit
command checks `key.key == YASL_KEY_ESCAPE` on a press. `YASL_KEY_A` means the
US A position on every layout; use layout labels when a command should follow
the printed letter instead. Do not cast key identities to characters. Keypad
Enter and ordinary Enter now have distinct identities without a separate flag.

Text comes only from `YASL_EVENT_TEXT`. Handle its byte length, copy it when
retaining it after the next successful poll, and allow multiple characters per
commit. Cocoa sends key events through its text input manager; Wayland emits
ordinary XKB text and locale compose results in addition to IME commits.

## Scroll events

Replace `scroll_lines`, `scroll_delta`, and scroll button numbers with
`pointer.scroll.x` and `.y` for `YASL_EVENT_POINTER_SCROLL`. These double
values are fractional line offsets, positive right/down on every backend.
Do not infer scroll direction from `button`. One event may include both axes.
Remove backend-specific sign inversions and whole-line casts; multiply the
offset by your application's preferred pixels per line instead.

X11 still supplies whole wheel steps. Wayland high-resolution wheels and smooth
offsets, and Cocoa precise scrolling, preserve fractions. Device acceleration
and system preferences still affect the native offsets.