# yasl gaps for wsap_term

Date: 2026-10-13
yasl head checked: `83c2180`
wsap_term state: `3a1439b`. The project builds, all 111 meson tests pass, and
the include-graph check reports no violations.

## Summary

All the earlier yasl gaps are closed in code. Drag targets, drag images, and
file drops now exist on every backend. They were checked by reading code, not at
runtime on X11 or macOS.

The wsap_term audit of `83c2180` asked for six pieces of yasl API. All six
are implemented; see "Requests from the wsap_term audit" below. One gap
remains on the project side.

## Resolved in yasl

### 1. Drop-target events on X11 and Cocoa

Status: **Resolved**. Both backends now send the target events.

- X11: `drag_set_hover`, `drag_leave_hover`, and `drag_end` in
  `src/platform/x11/window.c` send `YASL_DRAG_OVER`, `YASL_DRAG_LEAVE`, and
  `YASL_DRAG_DROP`. The XDND target code sends `YASL_DROP_OVER` and
  `YASL_DROP_LEAVE`.
- Cocoa: `src/platform/cocoa/window.m` sends all five target events.

### 2. Drag images on X11 and Cocoa

Status: **Resolved**. X11 shows the image in an override-redirect window that
follows the pointer (`drag_start` in `src/platform/x11/window.c`). Cocoa shows it
in a borderless image window. No backend ignores the image now.

### 3. X11 file drops

Status: **Resolved**. X11 accepts XDND drops of `text/uri-list` and sends
`YASL_EVENT_DROP` (`src/platform/x11/window.c`).

### 4. IME preedit on X11

Status: **Resolved**. `XNSpotLocation` places the candidate window through
`yasl_surface_set_ime_caret`. Preedit text and its cursor are available through
`yasl_surface_ime_preedit` and `yasl_surface_ime_preedit_cursor`.

### 5. Cocoa popups

Status: **Resolved** in commit `b20263c`. Child-window popups are implemented,
and `YASL_CAP_POPUPS` is advertised.

### 6. X11 popups

Status: **Resolved** in commit `b20263c`. Override-redirect popups are
implemented, and `YASL_CAP_POPUPS` is advertised.

### 7. Cocoa primary selection

Status: **Resolved** in commit `b20263c`. A dedicated pasteboard emulates the
primary selection, and `YASL_CAP_PRIMARY_SELECTION` is advertised.

### 8. X11 and Cocoa CSD and frame-pacing flags

Status: **Resolved**.

- Cocoa advertises `YASL_CAP_CSD` and `YASL_CAP_FRAME_PACING`.
- X11 advertises `YASL_CAP_CSD`, with `_NET_WM_MOVERESIZE` move and resize and
  `_GTK_SHOW_WINDOW_MENU`.
- `yasl_run` paces continuous X11 surfaces at about 16 ms to avoid a spin loop.

## Project-side gaps (wsap_term)

### 9. Reset does not clear the UI pointer press

yasl's `YASL_EVENT_INPUT_RESET` says the app must clear held keys, buttons,
strokes, and composition state.

The adapter (`src/ui/yasl/native_input.c`) now clears keyboard and held-button
state. The UI still keeps the press active (`ui_route.c:116-119`,
`selection.c:79`). A press can stay stuck after an X11 device removal, a queue
allocation failure, or a Wayland text allocation failure.

Suggested fix: send a pointer release to the UI on reset, or add a UI-level
reset.

## Requests from the wsap_term audit

All six requests are implemented. Linux paths are built and tested on Wayland
and X11. No Cocoa code was built or run.

### 1.1 Signal watching

Status: **Done** in `efca84e`.

`yasl_loop_watch_signals()` and `yasl_loop_unwatch_signals()` deliver signals
to a callback on the loop thread. The contract the audit asked for:

- Thread masks: YASL changes no thread's mask. Each signal gets a process-wide
  handler with `SA_RESTART` and an empty handler mask. The handler may run on
  any thread; it only records the signal and wakes the loop. A signal blocked
  in every thread is never delivered.
- Platforms: the same handler-based design runs on Linux and macOS. There is
  no `signalfd` path.
- `SIGCHLD`: callbacks run on the loop thread. Stopped and continued children
  also raise it.
- One loop can watch a given signal at a time; another loop gets `EBUSY`.
  Unwatch restores the saved actions.

### 1.2 Cross-thread wake or post

Status: **Done** in `efca84e`.

- `yasl_loop_kick()` is documented as safe from any thread and from a signal
  handler.
- `yasl_loop_post()` runs a function on the loop thread from any thread, in
  posting order, with a plain `yasl_loop`.
- Cocoa dispatch did not wake for kicks, posts, or fd watches while waiting
  for AppKit events. It now mirrors the loop's descriptors in a kqueue while
  it waits. This also fixes `yasl_post_event()` wakeups under `yasl_run()` on
  Cocoa.

### 1.3 Native double-click interval

Status: **Done** in `ac6f9f5`.

`yasl_display_double_click_ms()` reads XSETTINGS `Net/DoubleClickTime` on X11,
the KDE `DoubleClickInterval` or GNOME `double-click` setting through the
Settings portal on Wayland (and on X11 without XSETTINGS), and
`NSEvent.doubleClickInterval` on Cocoa. It falls back to 400 ms.

### 1.4 Held pointer buttons

Status: **Done** in `cbd1fc7`.

Every pointer event now has `buttons`, a `YASL_BUTTON_BIT()` mask of the
buttons held after the event. `INPUT_RESET` clears it. Wayland also clears it
on leave, because no release follows. X11 and Cocoa keep it across leave and
still deliver the release.

### 1.5 Desktop helpers

Status: **Done** in `d4d13e6`, with protocol code in `305a341`.

`<yasl/desktop.h>` has `yasl_display_open_uri()`, `yasl_display_notify()`,
`yasl_display_appearance()`, `yasl_surface_bell()`, `yasl_executable_path()`,
`yasl_resource_dir()`, and `yasl_default_locale()`.

- Linux opens URIs with `xdg-open` in a new session, with default signal
  dispositions and no inherited descriptors.
- Notifications and appearance use libdbus-1, an optional dependency behind
  `-Ddbus`. With it, the app no longer needs GIO for notifications.
- The bell uses xdg-system-bell on Wayland, the XKB bell on X11, and `NSBeep`.
- `yasl_display_open_uri()` checks only the URI syntax. Scheme policy, such as
  `str_url_scheme_allowed`, stays in the app.
- `yasl_default_locale()` on Linux reads `LC_ALL`, `LC_CTYPE`, then `LANG`.
  The app's Linux code always returns `en_US.UTF-8` today.

### 1.6 Smaller items

Status: **Done**.

- Drop URIs: `yasl_drop_next_path()` decodes local paths from a drop payload
  (`0437815`).
- Framebuffer readback: `yasl_surface_read_pixels()` copies the last presented
  CPU frame (`b7944e4`).
- `strndup` warning: IME text is copied with `strlen` and a cap. An LTO release
  build is warning-free (`6603122`).
- `yasl_loop_kick` threading: documented with 1.2 (`efca84e`).

The extra-button encoding in the term subproject belongs to that project, not
to yasl.

## Not verified

- Runtime behavior of items 1–3 on X11 and Cocoa.
- Any Cocoa path, including the dispatch wake, desktop services, double-click
  interval, readback, and bell. Cocoa needs a macOS build and test.
- Notifications and the bell were not shown on a real desktop. The desktop
  test checks the D-Bus messages against a fake service on a private bus.