docs: add wsap_term gaps report

1 files changed, 137 insertions, 0 deletions

diff --git a/yasl-gaps-report.md b/yasl-gaps-report.md
new file mode 100644
index 0000000..36386a5
--- /dev/null
+++ b/yasl-gaps-report.md
@@ -0,0 +1,137 @@
+# yasl gaps for wsap_term
+
+Date: 2026-10-12
+yasl head checked: `97e5cc6` (same commit on `https://git.wsap.dev/yasl.git/`)
+wsap_term state: the project builds and all 89 non-fuzz tests pass.
+
+## Summary
+
+The project already uses the new yasl API. Drag start, carry, and the
+source-side end work on X11 and Cocoa. Some drag and input features are
+still missing on some backends. Most of the gaps are in yasl. A few are in
+this project.
+
+## Drag and drop
+
+### 1. X11 and Cocoa never send drop-target events (yasl)
+
+yasl has these target events:
+
+- `YASL_DRAG_OVER`, `YASL_DRAG_LEAVE`, `YASL_DRAG_DROP` (surface `drag` callback)
+- `YASL_DROP_OVER`, `YASL_DROP_LEAVE` (surface `drop` callback)
+
+Only the Wayland backend sends them:
+
+- `src/wayland/clipboard.c`
+- `src/wayland/drag.c`
+
+X11 and Cocoa send only the source-side end (`YASL_DRAG_DROPPED` or
+`YASL_DRAG_CANCELLED`).
+
+Effect in wsap_term: a tab dragged onto another window's tab bar gets no
+hover and no drop on X11 or macOS. The tab falls back to a new window
+(`flight_end` in `src/window/terminal/transfer.c`).
+
+Needed in yasl: send the target events from the X11 and Cocoa drag code.
+
+### 2. Drag images are ignored on X11 and Cocoa (yasl)
+
+- X11: `drag_start` in `src/x11/window.c` has `(void)image;`.
+- Cocoa: `cocoa_display_drag_start` in `src/cocoa/window.m` has `(void)image;`.
+
+Effect: the drag image is not shown. The project does not use the image on
+these backends today, because they report `YASL_CAP_DRAG_CARRY`. The
+project uses the image only when carry is missing. That path runs on
+Wayland without toplevel-drag.
+
+Needed in yasl: draw the image, or document that it is unsupported.
+
+## Input and file drops
+
+### 3. X11 does not send file drops (yasl)
+
+`YASL_INPUT_DROP_FILES` is sent only by:
+
+- `src/common/input.c` (helper)
+- `src/cocoa/window.m`
+- `src/wayland/pointer.c`
+
+Effect: dropping files onto a terminal window does nothing on X11.
+
+Needed in yasl: XDND file-drop handling for X11.
+
+### 4. IME preedit is missing on X11 (yasl)
+
+The X11 input context uses `XIMPreeditNothing`. The yasl README already
+says X11 does not support IME preedit text.
+
+Effect: composed text (for example CJK input) does not show inline on X11.
+
+## Popups, selection, and caps
+
+### 5. Cocoa has no popups (yasl)
+
+`cocoa_surface_create_popup` and `cocoa_surface_popup_reposition` are
+stubs that return NULL or false. `cocoa_display_caps` does not set
+`YASL_CAP_POPUPS`.
+
+Effect: the project's native menu popup is off on macOS. `open_popup` in
+`src/window/ui/ui_menu.c` returns false, so the menu stays in the window.
+
+### 6. X11 has no popups (yasl)
+
+`caps()` in `src/x11/window.c` does not set `YASL_CAP_POPUPS`.
+
+Effect: same as item 5. Menus stay in the window on X11.
+
+### 7. Cocoa has no primary selection (yasl)
+
+`cocoa_display_caps` does not set `YASL_CAP_PRIMARY_SELECTION`. yasl says an
+unsupported primary selection is a no-op.
+
+Effect: select-to-copy and middle-click paste do nothing on macOS. The
+terminal calls these in `src/window/terminal/view.c` (`window_copy` and
+`window_paste` with `YASL_PRIMARY`).
+
+### 8. X11 and Cocoa have no CSD or frame pacing flags (yasl)
+
+These caps are set on Wayland only. Cocoa sets `YASL_CAP_FRAME_PACING`.
+X11 sets neither. The project does not read these flags for drawing
+decisions in the current code. Check this before you rely on pacing on
+X11.
+
+## Project-side gaps (wsap_term)
+
+### 9. Reset does not clear pointer buttons
+
+yasl's `YASL_INPUT_RESET` says the app must clear held keys and buttons,
+and composition state.
+
+`window_native_input` in `src/window/native_input.c` clears only keyboard
+state. Pointer presses are tracked by the UI widgets, so a press that a
+reset interrupts can stay stuck until the next press or release.
+
+Suggested fix: send a pointer-release-like event to the UI, or add a
+UI-level reset.
+
+## What is already fine
+
+- Cursor: now uses `YASL_CURSOR_HIDDEN` (`src/window/ui/ui_route.c`).
+- Accessibility on macOS: uses the typed view handle
+  (`src/window/ui/accessibility/accessibility.m`). This file compiles only
+  on macOS. It was not compiled here.
+- Pen input: pressure and tilt fields match yasl's contract.
+- Mouse buttons: 0 is primary, 1 is middle, 2 is secondary. This matches
+  the project.
+- Drag and carry: wired to the caps. Used on X11 and Cocoa with no code
+  change.
+
+## Suggested order
+
+1. Drop-target events on X11 and Cocoa (item 1). This unblocks tab merge.
+2. X11 file drops (item 3).
+3. Cocoa primary selection (item 7). Affects everyday terminal use on macOS.
+4. Popups on X11 and Cocoa (items 5 and 6), if menus need them.
+5. Project reset fix (item 9).
+6. Drag images (item 2), IME preedit (item 4), and frame-pacing caps (item 8)
+   as lower priority.