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.