vimdoc.diff

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index f929b9e4c..0fe02ac94 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.2.  Last change: 2026 Apr 14
+*builtin.txt*	For Vim version 9.2.  Last change: 2026 Apr 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -13354,8 +13354,6 @@ vtp			Compiled for vcon support |+vtp| (check vcon to find
 			out if it works in the current console).
 wayland			Compiled with Wayland protocol support.
 wayland_clipboard	Compiled with support for Wayland clipboard.
-wayland_focus_steal	Compiled with support for Wayland clipboard focus
-			stealing.
 wildignore		Compiled with 'wildignore' option.
 wildmenu		Compiled with 'wildmenu' option.
 win16			old version for MS-Windows 3.1 (always false)
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 2670535fb..c02d40eaa 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1,4 +1,4 @@
-*options.txt*	For Vim version 9.2.  Last change: 2026 Apr 17
+*options.txt*	For Vim version 9.2.  Last change: 2026 Apr 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -10669,11 +10669,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 				*'wlsteal'* *'wst'* *'nowlsteal'* *'nowst'*
 'wlsteal' 'wst'		boolean  (default off)
 			global
-			{only when the |+wayland_focus_steal| feature is
-			included}
+	DEPRECATED: This option is no longer used; changing it has no effect.
+
 	When enabled, then allow Vim to steal focus by creating a temporary
-	surface, in order to access the clipboard.  For more information see
-	|wayland-focus-steal|.
+	surface, in order to access the clipboard.
 
 						*'wltimeoutlen'* *'wtm'*
 'wltimeoutlen' 'wtm'	number	(default 500)
@@ -10686,9 +10685,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 	some cases.  On the other hand, it may also mean you receive errors
 	when the compositor takes more time to respond than usual.
 
-	Additionally, this option is also used as the maximum timeout when
-	waiting for a surface to gain focus, see |wayland-focus-steal|.
-
 						*'wrap'* *'nowrap'*
 'wrap'			boolean	(default on)
 			local to window
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 880feb634..1a625b350 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -1,4 +1,4 @@
-*various.txt*	For Vim version 9.2.  Last change: 2026 Apr 06
+*various.txt*	For Vim version 9.2.  Last change: 2026 Apr 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -529,9 +529,6 @@ T  *+vreplace*		|gR| and |gr|
    *+vtp*		on MS-Windows console: support for 'termguicolors'
 N  *+wayland*		Unix only: support for the Wayland protocol.
 N  *+wayland_clipboard*	Unix only: support for Wayland selections/clipboard.
-N  *+wayland_focus_steal*
-			Unix only: support for Wayland clipboard on
-			compositors without a data control protocol
 T  *+wildignore*	'wildignore'  Always enabled since 9.0.0278
 T  *+wildmenu*		'wildmenu'  Always enabled since 9.0.0279
 T  *+windows*		more than one window; Always enabled since 8.0.1118.
diff --git a/runtime/doc/version9.txt b/runtime/doc/version9.txt
index 7fa53f87d..12d46cffb 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -1,4 +1,4 @@
-*version9.txt*	For Vim version 9.2.  Last change: 2026 Apr 16
+*version9.txt*	For Vim version 9.2.  Last change: 2026 Apr 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -41954,7 +41954,7 @@ Vim Arguments: ~
 
 Configure Switches: ~
 --with-wayland			Enable the |wayland| feature.
---enable-wayland-focus-steal	Enable the |wayland-focus-steal| feature.
+--enable-wayland-focus-steal	Enable the wayland-focus-steal feature.
 --enable-socketserver		Enable the |socketserver-clientserver|
 				feature.
 
@@ -52636,6 +52636,9 @@ Changed ~
   are moved to the resulting joined line instead of being dropped.
 - Only a few whitelisted options are allowed to be set by a modeline to
   improve overall security, see for details: 'modelinestrict'
+- Removed the Wayland focus steal feature 'wlsteal', since it causes too many
+  issues and can now be re-implemted using the |clipboard-providers| feature
+  if needed, see |wayland-primary-selection| for an example.
 
 							*added-9.3*
 Added ~
diff --git a/runtime/doc/wayland.txt b/runtime/doc/wayland.txt
index 8d352bde9..af491064d 100644
--- a/runtime/doc/wayland.txt
+++ b/runtime/doc/wayland.txt
@@ -1,4 +1,4 @@
-*wayland.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
+*wayland.txt*	For Vim version 9.2.  Last change: 2026 Apr 20
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -54,15 +54,12 @@ try connecting again.
 2. Wayland Selections					*wayland-selections*
 
 Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
-protocols, for accessing the current Wayland selection.  These are the best
-case scenario protocols, see |wayland-focus-steal|.  Selection in this case
+protocols, for accessing the current Wayland selection. Selection in this case
 essentially means the "clipboard."  You can check if your Wayland compositor
 supports either of these protocols by running the wayland-info command, which
 should be bundled with libwayland on your system: >
 	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
 <If grep finds a match, then you have either or both protocols on your system.
-If you don't get any match, then please see |wayland-focus-steal| for more
-information.
 
 Some compositors that are known to support either or both protocols:
     1. KWin (KDE)
@@ -90,39 +87,65 @@ Vim determines which one to use when accessing the clipboard using the
 
 						*wayland-primary-selection*
 If you find X11 style primary selections useful, Wayland also implements this
-behaviour in its own protocols:
-
-- The primary selection protocol is the most widely supported, but requires
-  focus in order to be used, see |wayland-focus-steal|.
-
-- Data control protocol available on your system, such as the ext or wlr
-  protocols, then primary selection is also supported.  This is unless you are
-  using version 1 (not the same as the 'v1' in the protocol name), of the
-  wlr-data-control protocol.  Then the primary selection protocol will be used
-  as a fallback.
-
-					*wayland-focus-steal* *wayland-gnome*
-If you are using the GNOME desktop environment on Wayland, as of this writing,
-there is no method of accessing/modifying the clipboard for external clients
-such as Vim without being focused.  Focused in this case means the client has
-received some sort of input event, such as a window being focused.  This is
-what the wlr-data-control-unstable-v1 and ext-data-control-v1 protocols solve.
-If your Wayland compositor does not support the above protocols, then the
-above explanation applies.
-
-To solve this problem, Vim implements a way of gaining focus in order to
-access the clipboard, by creating a temporary transparent top-level surface.
-This is by default disabled and can be enabled via the 'wlsteal' option.
-Moreover, a seat that has a keyboard is also required, see 'wlseat', and the
-xdg-shell protocol must be available.  Additionally, Vim must be compiled with
-the |+wayland_focus_steal| feature.
-
-Note that this method can have several side effects from the result of focus
-stealing.  For example, if you have a taskbar that shows currently opened apps
-in your desktop environment, then when Vim attempts to steal focus, it may
-"flicker," as if a window was opened then immediately closed after.
-Additionally, if you are in fullscreen mode, this focus stealing won't work,
-because the created surface won't ever gain focus.  If this happens, Vim will
-seem to freeze temporarily, see 'wltimeoutlen' for more information.
+feature using the protocols that Vim supports.  This is unless you are using
+version 1 (not the same as the 'v1' in the protocol name), of the
+wlr-data-control protocol, then primary selection will not be supported. You
+can check this using >
+	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
+If the "version:" entry for "zwlr_data_control_manager_v1" is "2" or greater,
+then primary selection is supported.  If you also get
+"ext_data_control_manager_v1", then Vim will use that protocol instead, which
+has primary selection support builtin into it.
+
+If your Wayland compositor does not support the wlr-data-control-v1 or the
+ext-data-control-v1 protocol, Vim cannot access the clipboard directly through
+the Wayland protocol.  External tools such as wl-clipboard can be used instead
+via a user-defined |clipboard-providers|.
+
+Example: define a provider that shells out to `wl-copy` and `wl-paste`: >vim9
+
+    vim9script
+
+    def Available(): bool
+	return executable('wl-copy') && executable('wl-paste')
+    enddef
+
+    def Copy(reg: string, type: string, str: list<string>)
+	var args = "wl-copy"
+
+	if reg == "*"
+	    args ..= " -p"
+	endif
+
+	system(args, str)
+    enddef
+
+    def Paste(reg: string): tuple<string, list<string>>
+	var args = "wl-paste --type text/plain;charset=utf-8"
+
+	if reg == "*"
+	    args ..= " -p"
+	endif
+
+	return ("", systemlist(args))
+    enddef
+
+    v:clipproviders["wl_clipboard"] = {
+	available: Available,
+	copy: {
+	    "+": Copy,
+	    "*": Copy
+	},
+	paste: {
+	    "+": Paste,
+	    "*": Paste
+	}
+    }
+
+    set clipmethod=wl_clipboard
+
+
+This relies on the wl-clipboard package being installed
+(https://github.com/bugaevc/wl-clipboard).
 
  vim:tw=78:ts=8:noet:ft=help:norl