# Public API policy

YASL 0.1 is pre-release. The headers under `include/yasl/` are the public API; implementation
headers under `src/` are private even when their symbols appear in a static
archive. The shared library exports only declarations from public headers.
Native backend accessors are exported only for built backends. Installation
copies only the shared and static libraries; use matching source-tree headers.

There is currently no stable ABI promise and no versioned shared-library SONAME.
Rebuild consumers against the exact headers/library pair they ship. Source and
binary compatibility can change before 1.0. Do not assume struct layout is stable
across releases, mix headers and binaries from different revisions, or persist
public structs as a file/network format. The release version is declared in
`meson.build`.

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
unsupported result over backend names in portable application logic. Native
rendering and handles belong in the extension headers. Avoid adding engine,
widget, renderer, or application policy to the surface layer.

Every public addition or behavior change needs:

- A header contract describing arguments, result, units, lifetime, threading,
  callback timing, and unsupported behavior where applicable.
- An update to the guide and its backend limits when observable behavior changes.
- A runnable example when the new workflow cannot be understood from an isolated
  call, and meaningful regression coverage for ownership or behavior changes.
- A check that shared exports and consumers of the installed library still work.

Functions documenting errno set it on failure. Other booleans report acceptance
or availability without a guaranteed errno; void setters are best effort.
Callbacks and successful returns do not imply confirmed screen presentation.
See `yasl_timing.source` for provenance. Future changes that strengthen error
reporting must preserve these distinctions in documentation.