1 files changed, 77 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..23f4811
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# YASL (Yet Another Surface Library)
+
+YASL is a minimal, modern, and high-performance desktop window surface library written in C.
+
+It provides window creation, frame pacing, high-DPI scaling, and input routing without bundling audio, physics, or game engine components.
+
+## Features
+
+- **Lean Core**: No audio, no font rendering, and no widget toolkit overhead.
+- **Wayland Protocol Coverage**:
+  - `xdg-shell` toplevels and hierarchical popups (`xdg_popup` + `xdg_positioner`).
+  - Fractional scaling via `wp_fractional_scale_v1` and `wp_viewporter`.
+  - Presentation feedback and refresh rate timing via `wp_presentation` and `wp_fifo_v1`.
+  - Cursor shapes via `wp_cursor_shape_device_v1`.
+  - Graphics tablets and stylus input via `zwp_tablet_v2` (pressure, tilt, eraser).
+  - Text Input Method (IME) composition via `zwp_text_input_v3`.
+  - Primary selection and clipboard transfers via `wl_data_device` and `zwp_primary_selection_v1`.
+  - Interactive client-side window move and resize triggers (`xdg_toplevel_move`, `xdg_toplevel_resize`).
+- **macOS Cocoa & Metal**:
+  - Native `NSWindow` and `CAMetalLayer` presentation.
+  - Vsync pacing via `CADisplayLink`.
+- **Zero Framework Leaks**:
+  - Self-contained UTF-8 validation.
+  - Self-contained event queue.
+  - No terminal-specific telemetry or hardcoded application names.
+
+## Building
+
+Build with Meson and Ninja:
+
+```sh
+meson setup build
+ninja -C build
+ninja -C build test
+```
+
+## Quick Example
+
+```c
+#include <yasl/yasl.h>
+
+static void on_draw(struct yasl_surface *s, struct yasl_frame *frame, void *ud)
+{
+    /* Present frame target */
+    struct yasl_damage_list dmg = { .n = -1 };
+    yasl_surface_present(s, &frame->target, &dmg);
+}
+
+int main(void)
+{
+    struct yasl_loop *loop = yasl_loop_create();
+    struct yasl_display_spec dspec = { .app_id = "org.example.app" };
+    struct yasl_display *d = yasl_display_open(loop, &dspec);
+
+    struct yasl_surface_spec sspec = {
+        .title = "YASL Application",
+        .size = { .x = 800, .y = 600 },
+    };
+    struct yasl_surface *s = yasl_surface_create_toplevel(d, &sspec);
+    struct yasl_surface_cbs cbs = { .draw = on_draw };
+    yasl_surface_set_callbacks(s, &cbs, NULL);
+    yasl_surface_schedule_redraw(s);
+
+    while (true) {
+        yasl_display_dispatch(d);
+        struct yasl_input_event ev;
+        while (yasl_surface_input_poll(s, &ev)) {
+            /* Handle input */
+        }
+        yasl_display_flush(d);
+    }
+}
+```
+
+## License
+
+MIT License.