yasl.git/docs/guide.md, branch main

delete pre-release docs

2026-10-14T09:55:14+00:00

Remove deprecated Cocoa OpenGL and private compatibility APIs

2026-10-14T06:38:31+00:00

Simplify the public event and CPU API

2026-10-13T20:41:31+00:00

Applications now need far less ceremony: hello.c is a 20-line loop that handles REFRESH, CLOSE and QUIT and draws into the surface's own pixels. - Fold GEOMETRY, STATE and FOCUS into one WINDOW event carrying size, scale and state; unchanged values send nothing. - Guarantee REFRESH once a window has a size and after every resize, never at size zero. - Merge DROP_HOVER into DROP with over/leave/data actions and give drag and drop actions enums. - Keep event strings valid until the next wait and drop yasl_event_release; empty or failed waits report NONE. - Replace copy-in presentation with a lent pixel buffer: yasl_cpu_pixels and yasl_cpu_present. - Remove yasl_poll_event, yasl_cpu_read_pixels, unused event fields and comments that restated names. - Wayland: resize floating windows in request_size instead of reporting it unsupported, and stop marking new GPU surfaces as Vulkan so yasl_vulkan_create_surface no longer fails with NATIVE_WINDOW_IN_USE. Also includes the in-progress public API refactor that was uncommitted in the tree (removal of the app/loop layer, new surface, GL and Vulkan entry points). Co-Authored-By: Claude Opus 5.5

public api refactor

2026-10-13T18:23:03+00:00

Decode local paths from drop payloads

2026-10-13T14:13:17+00:00

Drops arrive as a CRLF-separated text/uri-list of file URLs, so every consumer percent-decodes them; wsap_term does it in its own drop code. yasl_drop_next_path() walks the list and returns one decoded local path at a time. It accepts file:///, file:/, and file://localhost or this machine's name, ends the path at '?' or '#', and skips comments, other schemes, remote hosts, malformed escapes, and escaped NUL bytes. A buffer that is too small leaves the cursor in place, like the other functions that fill a buffer. Co-Authored-By: Claude Opus 5.5

Read back the last presented CPU frame

2026-10-13T14:12:10+00:00

wsap_term writes PNG screenshots for its debug server and keeps its own copy of the frame because YASL had no readback. yasl_surface_read_pixels() copies the frame from the last successful present, or reports its extent when the buffer is too small. X11 and Cocoa keep it in their single CPU target until the next draw starts; X11 now also forgets it when a resize replaces the target, and Cocoa records the presented extent because a resize can change the size before the next draw. Wayland remembers which buffer it committed and forgets it when a draw reuses that buffer. The backend test checks the copy on Wayland and X11, and that draws that never present do not show through. The Cocoa path is not built or run here. Co-Authored-By: Claude Opus 5.5

Report the system double-click interval

2026-10-13T14:08:48+00:00

wsap_term hardcodes 400 ms in three places to count clicks. yasl_display_double_click_ms() reads the interval from the system. X11 parses Net/DoubleClickTime from the XSETTINGS owner's property. Wayland has no protocol for it, so it asks the Settings portal for KDE's DoubleClickInterval, which KDE sends as a string and which exists only when the user set it, then GNOME's double-click. X11 without XSETTINGS asks the portal too. Cocoa reads NSEvent.doubleClickInterval. Missing or implausible values give YASL_DOUBLE_CLICK_MS_DEFAULT, 400 ms. The X11 state test covers the XSETTINGS parser in both byte orders and with truncation. The Xwayland test owns the settings selection. The desktop test serves both portal keys. The Cocoa path is not built or run here. Co-Authored-By: Claude Opus 5.5

Add desktop services: open URI, notify, appearance, bell, and paths

2026-10-13T14:05:59+00:00

wsap_term keeps per-platform code for opening links, notifications, the bell, high-contrast detection, the executable and bundle paths, and the default locale. These now live behind . On Linux, src/platform/freedesktop serves both backends. Opening a URI runs xdg-open from PATH through a double fork, so the opener gets default signal dispositions, an empty mask, a new session, and none of the application's descriptors. Notifications and the Settings portal use the session bus through libdbus-1, an optional dependency behind -Ddbus. Appearance falls back to GTK_THEME without a portal. The bell uses xdg-system-bell on Wayland and the XKB bell on X11. Cocoa implements the same calls with NSWorkspace, UserNotifications, the effective appearance, NSBeep, the bundle, and CFLocale. That code is not built or run here; it needs a macOS check. The desktop test runs under dbus-run-session against a fake notification server and portal, and uses a fake xdg-open to check argument passing, signal state, and descriptor inheritance. Co-Authored-By: Claude Opus 5.5

Report held pointer buttons on every pointer event

2026-10-13T13:57:59+00:00

Pointer events set button only on press and release, so wsap_term tracked held buttons itself to tell a drag from a hover. yasl_pointer_event.buttons now holds a YASL_BUTTON_BIT() mask of the buttons held after each event. The common input queue tracks it from the DOWN and UP events it queues, and clears it on INPUT_RESET and on allocation failure. Wayland also clears it on leave, since the compositor sends leave during a press only when it takes the pointer and no release follows. X11 and Cocoa keep it, because they deliver motion and the release to the pressed window after leave. Co-Authored-By: Claude Opus 5.5

Wake and post to loops from any thread, and watch signals

2026-10-13T13:55:45+00:00

wsap_term runs its own eventfds to wake the loop from its pty worker and accessibility threads, and its own signalfd or self-pipe per platform. yasl_loop_kick() is now documented as safe from any thread and from a signal handler. yasl_loop_post() queues a function to run on the owning thread during a later step. yasl_loop_watch_signals() installs a process-wide SA_RESTART handler per signal that records the signal and kicks the loop, so callbacks run on the loop thread on every platform without touching thread masks. Cocoa dispatch waited only for AppKit events, so kicks, posts, and fd watches could not end an indefinite wait, and yasl_post_event() did not wake yasl_run(). While waiting, Cocoa now mirrors the loop's descriptors in a kqueue whose run loop source posts a wake event. If kqueue rejects a descriptor, the wait is bounded to 10 ms. The Cocoa change is not built or run here; it needs a macOS check. Co-Authored-By: Claude Opus 5.5