docs(page-mode): align scrolling and mode feedback

commit: c8b70f38f54991af6bb9959f1eb7fde282937333
author: brice · 2mo ago · 2026-07-29 05:04 UTC
parent: e70f71d
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

3 files · +10 -6

M docs/config/index.md +3 -2


@@ -448,7 +448,7 @@ Notes:
448	448		- Arrow keys still use the browser engine's native page-navigation path while Page Mode is active.
449	449		- Other app-level shortcuts stay suspended until Page Mode exits, except for the Page Mode toggle itself.
450	450		- `workspace.styling.pane_mode_color`, `workspace.styling.transition_duration`, and `workspace.styling.mode_indicator_toaster_enabled` control the pane-local Page Mode visuals.
451		-	- Scroll execution depends on the engine: CEF uses native Chromium key events (arrow keys, Page Up/Down) for all six scroll commands; WebKit falls back to JavaScript scroll delta injection.
	451	+	- Scroll execution: CEF and WebKit both use the shared `BuildScrollByJS` resolver when the page is ready. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. The application repeater owns held-key cadence; each engine executes one immediate scroll step per tick. Cross-origin frame contents remain best-effort. CEF may use native precision-wheel input only as a pre-frame fallback before the browser/main frame is ready.
452	452
453	453		### Resize Mode
454	454

@@ -585,10 +585,11 @@ desc = "Open floating pane on GitHub"
585	585		\| `workspace.styling.tab_mode_color` \| string \| `"#FFA500"` \| Tab mode color (orange) - used for border and toaster \|
586	586		\| `workspace.styling.session_mode_color` \| string \| `"#9B59B6"` \| Session mode color (purple) - used for border and toaster \|
587	587		\| `workspace.styling.resize_mode_color` \| string \| `"#00D4AA"` \| Resize mode color (teal) - used for border and toaster \|
588		-	\| `workspace.styling.mode_indicator_toaster_enabled` \| bool \| `true` \| Show toaster notification when modal modes are active; Page mode uses it only as brief secondary feedback \|
	588	+	\| `workspace.styling.mode_indicator_toaster_enabled` \| bool \| `true` \| Show bottom-left mode toaster when modal modes are active; Page Mode keeps a persistent `PAGE MODE` indicator until exit or toggle off \|
589	589		\| `workspace.styling.transition_duration` \| int \| `120` \| Border and pulse transition duration (ms) \|
590	590
591	591		Example:
	592	+
592	593		```toml
593	594		[workspace.styling]
594	595		border_width = 1


@@ -448,7 +448,7 @@ Notes:
448		- Arrow keys still use the browser engine's native page-navigation path while Page Mode is active.	448		- Arrow keys still use the browser engine's native page-navigation path while Page Mode is active.
449		- Other app-level shortcuts stay suspended until Page Mode exits, except for the Page Mode toggle itself.	449		- Other app-level shortcuts stay suspended until Page Mode exits, except for the Page Mode toggle itself.
450		- `workspace.styling.pane_mode_color`, `workspace.styling.transition_duration`, and `workspace.styling.mode_indicator_toaster_enabled` control the pane-local Page Mode visuals.	450		- `workspace.styling.pane_mode_color`, `workspace.styling.transition_duration`, and `workspace.styling.mode_indicator_toaster_enabled` control the pane-local Page Mode visuals.
451	-	- Scroll execution depends on the engine: CEF uses native Chromium key events (arrow keys, Page Up/Down) for all six scroll commands; WebKit falls back to JavaScript scroll delta injection.	451	+	- Scroll execution: CEF and WebKit both use the shared `BuildScrollByJS` resolver when the page is ready. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. The application repeater owns held-key cadence; each engine executes one immediate scroll step per tick. Cross-origin frame contents remain best-effort. CEF may use native precision-wheel input only as a pre-frame fallback before the browser/main frame is ready.
452			452
453		### Resize Mode	453		### Resize Mode
454			454

@@ -585,10 +585,11 @@ desc = "Open floating pane on GitHub"
585		\| `workspace.styling.tab_mode_color` \| string \| `"#FFA500"` \| Tab mode color (orange) - used for border and toaster \|	585		\| `workspace.styling.tab_mode_color` \| string \| `"#FFA500"` \| Tab mode color (orange) - used for border and toaster \|
586		\| `workspace.styling.session_mode_color` \| string \| `"#9B59B6"` \| Session mode color (purple) - used for border and toaster \|	586		\| `workspace.styling.session_mode_color` \| string \| `"#9B59B6"` \| Session mode color (purple) - used for border and toaster \|
587		\| `workspace.styling.resize_mode_color` \| string \| `"#00D4AA"` \| Resize mode color (teal) - used for border and toaster \|	587		\| `workspace.styling.resize_mode_color` \| string \| `"#00D4AA"` \| Resize mode color (teal) - used for border and toaster \|
588	-	\| `workspace.styling.mode_indicator_toaster_enabled` \| bool \| `true` \| Show toaster notification when modal modes are active; Page mode uses it only as brief secondary feedback \|	588	+	\| `workspace.styling.mode_indicator_toaster_enabled` \| bool \| `true` \| Show bottom-left mode toaster when modal modes are active; Page Mode keeps a persistent `PAGE MODE` indicator until exit or toggle off \|
589		\| `workspace.styling.transition_duration` \| int \| `120` \| Border and pulse transition duration (ms) \|	589		\| `workspace.styling.transition_duration` \| int \| `120` \| Border and pulse transition duration (ms) \|
590			590
591		Example:	591		Example:
			592	+
592		```toml	593		```toml
593		[workspace.styling]	594		[workspace.styling]
594		border_width = 1	595		border_width = 1

M docs/getting-started.md +6 -3


@@ -40,9 +40,12 @@ Page Mode stays local to the active pane and automatically leaves the mode when
40	40		6. Press `Escape` or `Enter` to leave the mode
41	41		7. If a page input or editor is already focused, `Ctrl+Y` is passed through instead of stealing the keypress
42	42
43		-	> Engine behavior: CEF sends native arrow key and Page Up/Down events for
44		-	> scroll execution, matching Chromium's built-in scroll behaviour. WebKit uses
45		-	> JavaScript scroll delta injection as a fallback.
	43	+	> Engine behavior: CEF and WebKit execute Page Mode scroll steps with the
	44	+	> shared `BuildScrollByJS` resolver (viewport-center start, nested-scroller
	45	+	> handoff, document fallback). The application repeater owns held-key cadence;
	46	+	> each engine runs one immediate step per tick. Cross-origin frames are
	47	+	> best-effort. CEF may use native precision-wheel input only before the browser
	48	+	> frame is ready.
46	49
47	50		## Omnibox
48	51

 6. Press `Escape` or `Enter` to leave the mode
 7. If a page input or editor is already focused, `Ctrl+Y` is passed through instead of stealing the keypress
-> **Engine behavior**: CEF sends native arrow key and Page Up/Down events for
+> **Engine behavior**: CEF and WebKit execute Page Mode scroll steps with the
-> scroll execution, matching Chromium's built-in scroll behaviour. WebKit uses
+> shared `BuildScrollByJS` resolver (viewport-center start, nested-scroller
-> JavaScript scroll delta injection as a fallback.
+> handoff, document fallback). The application repeater owns held-key cadence;
+> each engine runs one immediate step per tick. Cross-origin frames are
+> best-effort. CEF may use native precision-wheel input only before the browser
+> frame is ready.
 ## Omnibox

M docs/reference/keybindings.md +1 -1


@@ -55,7 +55,7 @@ Keybinding tables use uppercase letters as visual labels for unshifted letter ke
55	55
56	56		## Page Mode (`Ctrl+Y`)
57	57
58		-	Page Mode is an explicit page-scrolling mode for the active pane only. It shows a local `PAGE` indicator on the owning pane, uses `workspace.styling.pane_mode_color` for the local accent, and exits automatically when focus moves into the omnibox, find bar, overlays, or an editable element inside the page. The default `timeout_ms` is `0`, so Page Mode does not auto-time out unless you configure one. Arrow keys continue to flow through the browser engine's native page-navigation path while Page Mode is active, while other app-level shortcuts stay suspended until you leave the mode.
	58	+	Page Mode is an explicit page-scrolling mode for the active pane only. It applies a pane-local accent from `workspace.styling.pane_mode_color`, and when `workspace.styling.mode_indicator_toaster_enabled` is true, shows a persistent bottom-left `PAGE MODE` toaster while the mode is active; the toaster hides on exit, when the mode is toggled off, or when the toaster is disabled in config. The mode exits automatically when focus moves into the omnibox, find bar, overlays, or an editable element inside the page. The default `timeout_ms` is `0`, so Page Mode does not auto-time out unless you configure one. Arrow keys continue to flow through the browser engine's native page-navigation path while Page Mode is active, while other app-level shortcuts stay suspended until you leave the mode.
59	59
60	60		CEF and WebKit execute Page Mode scroll commands (`h/j/k/l`, `Shift+J/K`) with the shared `BuildScrollByJS` resolver. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. Cross-origin frame contents remain best-effort.
61	61


@@ -55,7 +55,7 @@ Keybinding tables use uppercase letters as visual labels for unshifted letter ke
55			55
56		## Page Mode (`Ctrl+Y`)	56		## Page Mode (`Ctrl+Y`)
57			57
58	-	Page Mode is an explicit page-scrolling mode for the active pane only. It shows a local `PAGE` indicator on the owning pane, uses `workspace.styling.pane_mode_color` for the local accent, and exits automatically when focus moves into the omnibox, find bar, overlays, or an editable element inside the page. The default `timeout_ms` is `0`, so Page Mode does not auto-time out unless you configure one. Arrow keys continue to flow through the browser engine's native page-navigation path while Page Mode is active, while other app-level shortcuts stay suspended until you leave the mode.	58	+	Page Mode is an explicit page-scrolling mode for the active pane only. It applies a pane-local accent from `workspace.styling.pane_mode_color`, and when `workspace.styling.mode_indicator_toaster_enabled` is true, shows a persistent bottom-left `PAGE MODE` toaster while the mode is active; the toaster hides on exit, when the mode is toggled off, or when the toaster is disabled in config. The mode exits automatically when focus moves into the omnibox, find bar, overlays, or an editable element inside the page. The default `timeout_ms` is `0`, so Page Mode does not auto-time out unless you configure one. Arrow keys continue to flow through the browser engine's native page-navigation path while Page Mode is active, while other app-level shortcuts stay suspended until you leave the mode.
59			59
60		CEF and WebKit execute Page Mode scroll commands (`h/j/k/l`, `Shift+J/K`) with the shared `BuildScrollByJS` resolver. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. Cross-origin frame contents remain best-effort.	60		CEF and WebKit execute Page Mode scroll commands (`h/j/k/l`, `Shift+J/K`) with the shared `BuildScrollByJS` resolver. Each step starts under the viewport center, walks up through ancestors that can move in the requested direction, and hands scrolling to the document when a nested container reaches its boundary. Cross-origin frame contents remain best-effort.
61			61