docs: document the split-window fan-out workaround for show()

README.md

@@ -43,6 +43,16 @@ See `AGENTS.md` for the full set of project constraints and architecture.
 
 ## Known Issues
 
+- **A buffer split into a second window shows blank space, not the image.**
+  `show()` binds a placement to one specific window; if the same buffer is
+  also open in another window (`:split`/`:vsplit`), that window renders the
+  reserved blank `virt_lines` rows with no image in them — `show()` doesn't
+  auto-detect the split and place into it. Work around this today by calling
+  `show()` again with `opts.win` set to the second window and the same
+  `path`: blit reuses the already-transmitted image data instead of
+  re-sending it, adding an independent placement for the new window at no
+  extra transmission cost ([#10](https://github.com/optiflowic/blit.nvim/issues/10)).
+
 - **WezTerm: process crash under sustained fast scrolling** ([#31](https://github.com/optiflowic/blit.nvim/issues/31)).
   Scrolling quickly and continuously with an image anchored away from the top
   of the buffer can crash the WezTerm process itself (not just the pane),

doc/blit.txt

@@ -84,6 +84,14 @@ show({path}, {opts})
     for its real cell-pixel size, so this is an approximation; when both
     {width} and {height} are supplied, they pass through unvalidated.
 
+    Calling |blit.show()| again for the same {path} (matching file content,
+    by `(path, mtime)`) reuses the already-transmitted image data instead of
+    re-sending it, adding an independent placement rather than a redundant
+    copy. This is also how to display the same image in more than one
+    window at once — e.g. after `:split` — since one handle is bound to one
+    {win}: call |blit.show()| a second time with {opts.win} set to the
+    second window and the same {path}.
+
                                                               *blit.clear()*
 clear({handle})
     Remove the placement and extmark for a handle returned by |blit.show()|.