docs: describe link hints, text yanks and the Vim Mode escape hatch

List every new action in the example configs, cover hints, yanks and
caret/visual selection in the changelog, note that text in shadow roots is
not a caret anchor, and name the toggle shortcut as the always-available
way out of a page interaction.

commit: fea7b728696b0706b83bc25a0bb2004d268a7bf0
author: brice · 18d ago · 2026-10-04 16:12 UTC
committer: brice · 12d ago · 2026-10-10 08:28 UTC
parent: 75d2da2
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

3 files · +53 -1

M CHANGELOG.md +1 -1


@@ -9,7 +9,7 @@ All notable changes to this project will be documented in this file.
9	9		- Named browser windows: Added `dumber browse --instance <name>` to open or focus a stable named window in the current CEF profile host. Named windows share cookies, tokens, local storage, configuration, history, and favorites; use `--profile` for a separate persistent browser profile/host or `--ephemeral` for a temporary isolated profile/host.
10	10		- Omnibox visual styles: Added configurable `command`, `multiplexer`, and `minimal` GTK treatments. The terminal-inspired `command` palette is the default.
11	11		- Vim mode for keyboard-driven page navigation: Added configurable multi-key sequences for page scrolling, fast scrolling, page-input focus, and live heading navigation. Pressing `Enter` on a selected CEF heading opens its associated link before leaving Vim Mode. CEF accessibility data also provides the foundation for navigating structured page content such as headings, lists, paragraphs, and sections.
12		-	- Vim Mode caret and visual selection: `v` starts text-anchor hints (or uses a visible selection), places a visible caret, and `v`/`V` select characters or lines with Vim motions. `y` copies and returns to the caret. The mode indicator shows `HINTS`, `CARET`, `VISUAL`, or `VISUAL LINE`.
	12	+	- Vim Mode link hints, text yanks, and visual selection: `f` labels the visible links and controls and activates the one you pick, `F` opens a link in a new pane, and `yf` copies a link URL. `yah`, `yap`, `yac`, `yat`, and `yal` copy the current section or the first visible paragraph, code block, table, or list. `v` starts text-anchor hints (or uses a visible selection), places a visible caret, and `v`/`V` select characters or lines with Vim motions; `y` copies and returns to the caret. The mode indicator shows `HINTS`, `CARET`, `VISUAL`, or `VISUAL LINE`. While the page owns the keys, the Vim Mode toggle shortcut (`Ctrl+Y` by default) always leaves Vim Mode and ends the interaction.
13	13		- Native favorites sidebar: Added a keyboard-driven GTK sidebar toggled with `Ctrl+B`, including search, tag filtering, tag creation, favorite editing, shortcut assignment, deletion, and opening favorites in the current pane or a new split.
14	14		- WebP favicon decoding: Added safe WebP decoding for sites that publish WebP favicons.
15	15


@@ -9,7 +9,7 @@ All notable changes to this project will be documented in this file.
9		- Named browser windows: Added `dumber browse --instance <name>` to open or focus a stable named window in the current CEF profile host. Named windows share cookies, tokens, local storage, configuration, history, and favorites; use `--profile` for a separate persistent browser profile/host or `--ephemeral` for a temporary isolated profile/host.	9		- Named browser windows: Added `dumber browse --instance <name>` to open or focus a stable named window in the current CEF profile host. Named windows share cookies, tokens, local storage, configuration, history, and favorites; use `--profile` for a separate persistent browser profile/host or `--ephemeral` for a temporary isolated profile/host.
10		- Omnibox visual styles: Added configurable `command`, `multiplexer`, and `minimal` GTK treatments. The terminal-inspired `command` palette is the default.	10		- Omnibox visual styles: Added configurable `command`, `multiplexer`, and `minimal` GTK treatments. The terminal-inspired `command` palette is the default.
11		- Vim mode for keyboard-driven page navigation: Added configurable multi-key sequences for page scrolling, fast scrolling, page-input focus, and live heading navigation. Pressing `Enter` on a selected CEF heading opens its associated link before leaving Vim Mode. CEF accessibility data also provides the foundation for navigating structured page content such as headings, lists, paragraphs, and sections.	11		- Vim mode for keyboard-driven page navigation: Added configurable multi-key sequences for page scrolling, fast scrolling, page-input focus, and live heading navigation. Pressing `Enter` on a selected CEF heading opens its associated link before leaving Vim Mode. CEF accessibility data also provides the foundation for navigating structured page content such as headings, lists, paragraphs, and sections.
12	-	- Vim Mode caret and visual selection: `v` starts text-anchor hints (or uses a visible selection), places a visible caret, and `v`/`V` select characters or lines with Vim motions. `y` copies and returns to the caret. The mode indicator shows `HINTS`, `CARET`, `VISUAL`, or `VISUAL LINE`.	12	+	- Vim Mode link hints, text yanks, and visual selection: `f` labels the visible links and controls and activates the one you pick, `F` opens a link in a new pane, and `yf` copies a link URL. `yah`, `yap`, `yac`, `yat`, and `yal` copy the current section or the first visible paragraph, code block, table, or list. `v` starts text-anchor hints (or uses a visible selection), places a visible caret, and `v`/`V` select characters or lines with Vim motions; `y` copies and returns to the caret. The mode indicator shows `HINTS`, `CARET`, `VISUAL`, or `VISUAL LINE`. While the page owns the keys, the Vim Mode toggle shortcut (`Ctrl+Y` by default) always leaves Vim Mode and ends the interaction.
13		- Native favorites sidebar: Added a keyboard-driven GTK sidebar toggled with `Ctrl+B`, including search, tag filtering, tag creation, favorite editing, shortcut assignment, deletion, and opening favorites in the current pane or a new split.	13		- Native favorites sidebar: Added a keyboard-driven GTK sidebar toggled with `Ctrl+B`, including search, tag filtering, tag creation, favorite editing, shortcut assignment, deletion, and opening favorites in the current pane or a new split.
14		- WebP favicon decoding: Added safe WebP decoding for sites that publish WebP favicons.	14		- WebP favicon decoding: Added safe WebP decoding for sites that publish WebP favicons.
15			15

M docs/config/index.md +29 -0


@@ -467,10 +467,38 @@ desc = "Jump to previous heading"
467	467		keys = ["f"]
468	468		desc = "Show hints and follow a link or control"
469	469
	470	+	[workspace.vim_mode.actions.hint-follow-new]
	471	+	keys = ["F"]
	472	+	desc = "Show hints and open a link in a new pane"
	473	+
	474	+	[workspace.vim_mode.actions.hint-yank-url]
	475	+	keys = ["yf"]
	476	+	desc = "Show hints and yank a link URL"
	477	+
470	478		[workspace.vim_mode.actions.visual]
471	479		keys = ["v"]
472	480		desc = "Start visual selection (motions extend, y yanks)"
473	481
	482	+	[workspace.vim_mode.actions.yank-section]
	483	+	keys = ["yah"]
	484	+	desc = "Yank current section"
	485	+
	486	+	[workspace.vim_mode.actions.yank-paragraph]
	487	+	keys = ["yap"]
	488	+	desc = "Yank first visible paragraph"
	489	+
	490	+	[workspace.vim_mode.actions.yank-code]
	491	+	keys = ["yac"]
	492	+	desc = "Yank first visible code block"
	493	+
	494	+	[workspace.vim_mode.actions.yank-table]
	495	+	keys = ["yat"]
	496	+	desc = "Yank first visible table"
	497	+
	498	+	[workspace.vim_mode.actions.yank-list]
	499	+	keys = ["yal"]
	500	+	desc = "Yank first visible list"
	501	+
474	502		[workspace.vim_mode.actions.confirm]
475	503		keys = ["enter"]
476	504		desc = "Open selected heading link and exit mode"

@@ -487,6 +515,7 @@ Notes:
487	515		- `confirm` opens the first link inside the selected heading, or a link wrapping that heading, then exits Vim Mode. If the selected heading has no link, it only exits the mode.
488	516		- The default `timeout_ms = 0` means Vim Mode stays active until you exit it or focus moves into an editable/browser UI context. `Ctrl+Y` can still activate it when a page input is already focused.
489	517		- Arrow keys still use the browser engine's native page-navigation path while Vim Mode is active.
	518	+	- `f`, `F`, and `yf` label visible links; `yah`, `yap`, `yac`, `yat`, and `yal` copy a section, paragraph, code block, table, or list; `v` starts caret and visual selection. While a hint or visual interaction runs, the page owns every key except the activation shortcut (`activation_shortcut`, `Ctrl+Y` by default), which always leaves Vim Mode and ends the interaction, whatever the page does. These actions use the CEF engine path.
490	519		- `Tab` and `Shift+Tab` keep focus traversal inside the page while a page input is focused.
491	520		- Live input, heading, heading-link activation, and page-focus navigation currently use the CEF engine path; WebKit fallback supports the Vim scroll commands while equivalent semantic navigation is pending.
492	521		- Other app-level shortcuts stay suspended until Vim Mode exits, except for the Vim Mode toggle itself.


@@ -467,10 +467,38 @@ desc = "Jump to previous heading"
467	keys = ["f"]	467		keys = ["f"]
468	desc = "Show hints and follow a link or control"	468		desc = "Show hints and follow a link or control"
469		469
		470	+	[workspace.vim_mode.actions.hint-follow-new]
		471	+	keys = ["F"]
		472	+	desc = "Show hints and open a link in a new pane"
		473	+
		474	+	[workspace.vim_mode.actions.hint-yank-url]
		475	+	keys = ["yf"]
		476	+	desc = "Show hints and yank a link URL"
		477	+
470	[workspace.vim_mode.actions.visual]	478		[workspace.vim_mode.actions.visual]
471	keys = ["v"]	479		keys = ["v"]
472	desc = "Start visual selection (motions extend, y yanks)"	480		desc = "Start visual selection (motions extend, y yanks)"
473		481
		482	+	[workspace.vim_mode.actions.yank-section]
		483	+	keys = ["yah"]
		484	+	desc = "Yank current section"
		485	+
		486	+	[workspace.vim_mode.actions.yank-paragraph]
		487	+	keys = ["yap"]
		488	+	desc = "Yank first visible paragraph"
		489	+
		490	+	[workspace.vim_mode.actions.yank-code]
		491	+	keys = ["yac"]
		492	+	desc = "Yank first visible code block"
		493	+
		494	+	[workspace.vim_mode.actions.yank-table]
		495	+	keys = ["yat"]
		496	+	desc = "Yank first visible table"
		497	+
		498	+	[workspace.vim_mode.actions.yank-list]
		499	+	keys = ["yal"]
		500	+	desc = "Yank first visible list"
		501	+
474	[workspace.vim_mode.actions.confirm]	502		[workspace.vim_mode.actions.confirm]
475	keys = ["enter"]	503		keys = ["enter"]
476	desc = "Open selected heading link and exit mode"	504		desc = "Open selected heading link and exit mode"

@@ -487,6 +515,7 @@ Notes:
487	- `confirm` opens the first link inside the selected heading, or a link wrapping that heading, then exits Vim Mode. If the selected heading has no link, it only exits the mode.	515		- `confirm` opens the first link inside the selected heading, or a link wrapping that heading, then exits Vim Mode. If the selected heading has no link, it only exits the mode.
488	- The default `timeout_ms = 0` means Vim Mode stays active until you exit it or focus moves into an editable/browser UI context. `Ctrl+Y` can still activate it when a page input is already focused.	516		- The default `timeout_ms = 0` means Vim Mode stays active until you exit it or focus moves into an editable/browser UI context. `Ctrl+Y` can still activate it when a page input is already focused.
489	- Arrow keys still use the browser engine's native page-navigation path while Vim Mode is active.	517		- Arrow keys still use the browser engine's native page-navigation path while Vim Mode is active.
		518	+	- `f`, `F`, and `yf` label visible links; `yah`, `yap`, `yac`, `yat`, and `yal` copy a section, paragraph, code block, table, or list; `v` starts caret and visual selection. While a hint or visual interaction runs, the page owns every key except the activation shortcut (`activation_shortcut`, `Ctrl+Y` by default), which always leaves Vim Mode and ends the interaction, whatever the page does. These actions use the CEF engine path.
490	- `Tab` and `Shift+Tab` keep focus traversal inside the page while a page input is focused.	519		- `Tab` and `Shift+Tab` keep focus traversal inside the page while a page input is focused.
491	- Live input, heading, heading-link activation, and page-focus navigation currently use the CEF engine path; WebKit fallback supports the Vim scroll commands while equivalent semantic navigation is pending.	520		- Live input, heading, heading-link activation, and page-focus navigation currently use the CEF engine path; WebKit fallback supports the Vim scroll commands while equivalent semantic navigation is pending.
492	- Other app-level shortcuts stay suspended until Vim Mode exits, except for the Vim Mode toggle itself.	521		- Other app-level shortcuts stay suspended until Vim Mode exits, except for the Vim Mode toggle itself.

M docs/reference/keybindings.md +23 -0


@@ -72,6 +72,8 @@ In caret mode a large blinking accent cursor marks the position and motions move
72	72
73	73		Text-object yanks copy one block without selecting it: `yah` copies the current section (the heading nearest the top of the viewport through the next heading of the same or a higher level), and `yap`, `yac`, `yat`, and `yal` copy the first visible paragraph, code block, table, or list. The copied block flashes with the theme accent. Hints, visual selection, and yanks use the CEF engine path.
74	74
	75	+	While hints or visual selection are active, the page owns every key; the Vim Mode toggle shortcut (`Ctrl+Y` by default, or your `activation_shortcut`) is never forwarded to it. Pressing it always leaves Vim Mode and ends the interaction, so it is the way out even if a page misbehaves. Caret and visual selection anchor only to text in the page's main document: text inside shadow roots (some web components) is not offered as a caret position, while link hints and text-object yanks still reach into shadow DOM.
	76	+
75	77		\| Action \| Keys \|
76	78		\|--------\|------\|
77	79		\| Scroll left \| `H` \|

@@ -241,9 +243,30 @@ keys = ["[["]
241	243		[workspace.vim_mode.actions.hint-follow]
242	244		keys = ["f"]
243	245
	246	+	[workspace.vim_mode.actions.hint-follow-new]
	247	+	keys = ["F"]
	248	+
	249	+	[workspace.vim_mode.actions.hint-yank-url]
	250	+	keys = ["yf"]
	251	+
244	252		[workspace.vim_mode.actions.visual]
245	253		keys = ["v"]
246	254
	255	+	[workspace.vim_mode.actions.yank-section]
	256	+	keys = ["yah"]
	257	+
	258	+	[workspace.vim_mode.actions.yank-paragraph]
	259	+	keys = ["yap"]
	260	+
	261	+	[workspace.vim_mode.actions.yank-code]
	262	+	keys = ["yac"]
	263	+
	264	+	[workspace.vim_mode.actions.yank-table]
	265	+	keys = ["yat"]
	266	+
	267	+	[workspace.vim_mode.actions.yank-list]
	268	+	keys = ["yal"]
	269	+
247	270		[workspace.shortcuts.actions.close-pane]
248	271		keys = ["ctrl+w"]
249	272


@@ -72,6 +72,8 @@ In caret mode a large blinking accent cursor marks the position and motions move
72		72
73	Text-object yanks copy one block without selecting it: `yah` copies the current section (the heading nearest the top of the viewport through the next heading of the same or a higher level), and `yap`, `yac`, `yat`, and `yal` copy the first visible paragraph, code block, table, or list. The copied block flashes with the theme accent. Hints, visual selection, and yanks use the CEF engine path.	73		Text-object yanks copy one block without selecting it: `yah` copies the current section (the heading nearest the top of the viewport through the next heading of the same or a higher level), and `yap`, `yac`, `yat`, and `yal` copy the first visible paragraph, code block, table, or list. The copied block flashes with the theme accent. Hints, visual selection, and yanks use the CEF engine path.
74		74
		75	+	While hints or visual selection are active, the page owns every key; the Vim Mode toggle shortcut (`Ctrl+Y` by default, or your `activation_shortcut`) is never forwarded to it. Pressing it always leaves Vim Mode and ends the interaction, so it is the way out even if a page misbehaves. Caret and visual selection anchor only to text in the page's main document: text inside shadow roots (some web components) is not offered as a caret position, while link hints and text-object yanks still reach into shadow DOM.
		76	+
75	\| Action \| Keys \|	77		\| Action \| Keys \|
76	\|--------\|------\|	78		\|--------\|------\|
77	\| Scroll left \| `H` \|	79		\| Scroll left \| `H` \|

@@ -241,9 +243,30 @@ keys = ["[["]
241	[workspace.vim_mode.actions.hint-follow]	243		[workspace.vim_mode.actions.hint-follow]
242	keys = ["f"]	244		keys = ["f"]
243		245
		246	+	[workspace.vim_mode.actions.hint-follow-new]
		247	+	keys = ["F"]
		248	+
		249	+	[workspace.vim_mode.actions.hint-yank-url]
		250	+	keys = ["yf"]
		251	+
244	[workspace.vim_mode.actions.visual]	252		[workspace.vim_mode.actions.visual]
245	keys = ["v"]	253		keys = ["v"]
246		254
		255	+	[workspace.vim_mode.actions.yank-section]
		256	+	keys = ["yah"]
		257	+
		258	+	[workspace.vim_mode.actions.yank-paragraph]
		259	+	keys = ["yap"]
		260	+
		261	+	[workspace.vim_mode.actions.yank-code]
		262	+	keys = ["yac"]
		263	+
		264	+	[workspace.vim_mode.actions.yank-table]
		265	+	keys = ["yat"]
		266	+
		267	+	[workspace.vim_mode.actions.yank-list]
		268	+	keys = ["yal"]
		269	+
247	[workspace.shortcuts.actions.close-pane]	270		[workspace.shortcuts.actions.close-pane]
248	keys = ["ctrl+w"]	271		keys = ["ctrl+w"]
249		272