Decode local paths from drop payloads

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 <noreply@anthropic.com>

1 files changed, 16 insertions, 2 deletions

diff --git a/docs/guide.md b/docs/guide.md
index 4949f88..76279c4 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -279,8 +279,22 @@ this is not a desktop-wide macOS select-to-copy convention.
 
 External file drag hover uses the surface `drop` callback; actual file URLs
 arrive as `YASL_EVENT_DROP`. `text.data` is a `text/uri-list` string separated by
-CRLF, not a list of native paths. Parse URL encoding, skip blank/comment lines,
-and decide which schemes/hosts your application accepts before opening files.
+CRLF, not a list of native paths. `yasl_drop_next_path()` walks it and decodes
+each local `file:` URL into a path. It skips comments, other schemes, remote
+hosts, and malformed lines:
+
+```c
+const char *cursor = event.text.data;
+char path[4096];
+size_t len;
+while ((len = yasl_drop_next_path(&cursor, path, sizeof(path))) != 0) {
+    if (len >= sizeof(path)) break; /* Too long; grow the buffer instead. */
+    /* Open path. */
+}
+```
+
+Decoded paths are raw bytes and may contain any character the file system
+allows, including newlines. Quote them before pasting into a shell.
 
 Use `yasl_surface_ime_preedit()` to draw the uncommitted composition. The borrowed
 pointer expires on the next dispatch or surface destruction; copy to keep it.