From d30f86670dfd1928fece2367b13b22cc572bd009 Mon Sep 17 00:00:00 2001
From: Hisanari Kikuchi <hisanari.kikuchi.dev@gmail.com>
Date: Sat, 22 Aug 2026 15:20:09 +0900
Subject: [PATCH] docs: document the split-window fan-out workaround for show()

PR #51 (issue #10, multi-location placement fan-out) added the
underlying primitive but never updated README/doc/blit.txt, despite
docs/review-checklist.md's Tests & Docs category requiring vimdoc and
README updates for user-facing behavior. Document the one concrete,
user-actionable consequence: calling show() again with the same path
reuses the already-transmitted image data and is the way to place the
same image into a second window after :split/:vsplit today, since
show() still binds one handle to one window and doesn't auto-detect
splits.
---
 README.md    | 10 ++++++++++
 doc/blit.txt |  8 ++++++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 49dd34c..558edd0 100644
--- a/README.md
+++ b/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),
diff --git a/doc/blit.txt b/doc/blit.txt
index 20541bf..33db9d2 100644
--- a/doc/blit.txt
+++ b/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()|.