From 6d411f174335e887ec58c46f2a7ee021720e15fe Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Thu, 5 Sep 2024 00:37:18 -0700
Subject: [PATCH 1/9] miscellaneous a11y improvements

- set role="application" on toolbar and sidebar to force
screen readers to use focus mode in those areas since
reading mode is not applicable here and one should not have
to manually switch to focus mode
- made outline values visible to screen readers
- improved aria-live message announced during search navigation
to include the page number as well as the snippet of the
result
- added role="navigation" to start containers of epub ranges
so that screen readers indicate when one moves to a new page.
It also enabled navigation via d/shift-d for NVDA and r/shift-r
for JAWS to go to next/previous page as with PDFs.
- added a state variable a11yVirtualCursorTarget to record
which node the screen readers should place its virtual cursor
on next time the focus enters the reader.
It forces virtual cursor to be moved onto that node, as
opposed to landing in the beginning of the document.
It is currently used to make sure screen readers begin reading
the chapter/section selected in the outline, as well as to
place virtual cursor on the last search result. On scroll,
a11yVirtualCursorTarget is cleared to not interfere with
mouse navigation. To make sure that scroll events of document
that fire when outline is navigated don't clear the a11yVirtualCursorTarget
that was just set, we wait for scrolling to finish and do
not allow a11yVirtualCursorTarget to be cleared if it was added
within the last 0.5 second.
---
 src/common/components/sidebar/outline-view.js | 28 +++---
 src/common/components/sidebar/sidebar.js      |  4 +-
 src/common/components/toolbar.js              |  2 +-
 src/common/reader.js                          | 94 +++++++++++++++----
 src/dom/common/dom-view.tsx                   |  6 ++
 src/dom/common/lib/range.ts                   |  3 +
 src/dom/epub/epub-view.ts                     | 48 ++++++++++
 src/dom/snapshot/snapshot-view.ts             | 34 ++++++-
 src/pdf/pdf-view.js                           | 32 +++++++
 9 files changed, 217 insertions(+), 34 deletions(-)

diff --git a/src/common/components/sidebar/outline-view.js b/src/common/components/sidebar/outline-view.js
index 0e782945..2208d12d 100644
--- a/src/common/components/sidebar/outline-view.js
+++ b/src/common/components/sidebar/outline-view.js
@@ -43,7 +43,7 @@ function Item({ item, id, children, onOpenLink, onUpdate, onSelect }) {
 	let { expanded, active } = item;
 
 	return (
-		<li>
+		<li id={`outline-${id}`} aria-label={item.title}>
 			<div
 				className={cx('item', { expandable: !!item.items?.length, expanded, active })}
 				data-id={id}
@@ -76,20 +76,20 @@ function OutlineView({ outline, onNavigate, onOpenLink, onUpdate}) {
 		}
 	}
 
-	function handleKeyDown(event) {
-		let { key } = event;
-
-		let list = [];
-		function flatten(items) {
-			for (let item of items) {
-				list.push(item);
-				if (item.items && item.expanded) {
-					flatten(item.items);
-				}
+	function flatten(items, list = []) {
+		for (let item of items) {
+			list.push(item);
+			if (item.items && item.expanded) {
+				flatten(item.items, list);
 			}
 		}
+		return list;
+	}
+	
+	function handleKeyDown(event) {
+		let { key } = event;
 
-		flatten(outline);
+		let list = flatten(outline);
 
 		let currentIndex = list.findIndex(x => x.active);
 		let currentItem = list[currentIndex];
@@ -166,6 +166,7 @@ function OutlineView({ outline, onNavigate, onOpenLink, onUpdate}) {
 		);
 	}
 
+	let active = flatten(outline || []).findIndex(item => item.active);
 	return (
 		<div
 			ref={containerRef}
@@ -173,9 +174,10 @@ function OutlineView({ outline, onNavigate, onOpenLink, onUpdate}) {
 			data-tabstop="1"
 			tabIndex={-1}
 			id="outlineView"
-			role="tabpanel"
+			role="listbox"
 			aria-labelledby="viewOutline"
 			onKeyDown={handleKeyDown}
+			aria-activedescendant={active !== -1 ? `outline-${active}` : null}
 		>
 			{outline === null ? <div className="spinner"/> : renderItems(outline)}
 		</div>
diff --git a/src/common/components/sidebar/sidebar.js b/src/common/components/sidebar/sidebar.js
index dfd51e0f..66a533e3 100644
--- a/src/common/components/sidebar/sidebar.js
+++ b/src/common/components/sidebar/sidebar.js
@@ -19,7 +19,7 @@ function Sidebar(props) {
 	}
 
 	return (
-		<div id="sidebarContainer" className="sidebarOpen">
+		<div id="sidebarContainer" className="sidebarOpen" role="application">
 			<div className="sidebar-toolbar">
 				<div className="start" data-tabstop={1} role="tablist">
 					{props.type === 'pdf' &&
@@ -72,7 +72,7 @@ function Sidebar(props) {
 				<div id="annotationsView" role="tabpanel" aria-labelledby="viewAnnotations" className={cx("viewWrapper", { hidden: props.view !== 'annotations'})}>
 					{props.annotationsView}
 				</div>
-				<div className={cx("viewWrapper", { hidden: props.view !== 'outline'})}>
+				<div className={cx("viewWrapper", { hidden: props.view !== 'outline' })} role="tabpanel">
 					{props.outlineView}
 				</div>
 			</div>
diff --git a/src/common/components/toolbar.js b/src/common/components/toolbar.js
index d491ddeb..ca1a4ddf 100644
--- a/src/common/components/toolbar.js
+++ b/src/common/components/toolbar.js
@@ -73,7 +73,7 @@ function Toolbar(props) {
 	}
 
 	return (
-		<div className="toolbar" data-tabstop={1}>
+		<div className="toolbar" data-tabstop={1} role="application">
 			<div className="start">
 				<button
 					id="sidebarToggle"
diff --git a/src/common/reader.js b/src/common/reader.js
index 31ecc2fa..6e6b3322 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -186,6 +186,10 @@ class Reader {
 				entireWord: false,
 				result: null
 			},
+			a11yVirtualCursorTarget: {
+				node: null,
+				ts: null
+			}
 		};
 
 		if (options.secondaryViewState) {
@@ -655,23 +659,11 @@ class Reader {
 		this._onTextSelectionAnnotationModeChange(mode);
 	}
 
-	// Announce the index of current search result to screen readers
-	setA11ySearchResultMessage(primaryView) {
-		let result = (primaryView ? this._state.primaryViewFindState : this._state.secondaryViewFindState).result;
-		if (!result) return;
-		let searchIndex = `${this._getString("pdfReader.searchResultIndex")}: ${result.index + 1}`;
-		let totalResults = `${this._getString("pdfReader.searchResultTotal")}: ${result.total}`;
-		this.setA11yMessage(`${searchIndex}. ${totalResults}`);
-	}
-
 	findNext(primary) {
 		if (primary === undefined) {
 			primary = this._lastViewPrimary;
 		}
 		(primary ? this._primaryView : this._secondaryView).findNext();
-		setTimeout(() => {
-			this.setA11ySearchResultMessage(primary);
-		});
 	}
 
 	findPrevious(primary) {
@@ -679,9 +671,6 @@ class Reader {
 			primary = this._lastViewPrimary;
 		}
 		(primary ? this._primaryView : this._secondaryView).findPrevious();
-		setTimeout(() => {
-			this.setA11ySearchResultMessage(primary);
-		});
 	}
 
 	toggleEPUBAppearancePopup({ open }) {
@@ -797,6 +786,7 @@ class Reader {
 			this.focusView(primary);
 			// A workaround for Firefox/Zotero because iframe focusing doesn't trigger 'focusin' event
 			this._focusManager._closeFindPopupIfEmpty();
+			this.placeA11yVirtualCursor();
 		};
 
 		let onRequestPassword = () => {
@@ -862,6 +852,35 @@ class Reader {
 			this.setA11yMessage(annotationContent);
 		}
 
+		// Add page number as aria-label to provided node to improve screen reader navigation
+		let setA11yNavContent = (node, pageIndex) => {
+			node.setAttribute('aria-label', `${this._getString("pdfReader.page")}: ${pageIndex}`);
+		};
+
+		// Set which node should receive focus when the focus enters the reader to
+		// help screen readers place virtual cursor at the right location
+		let setA11yVirtualCursorTarget = (node) => {
+			if (node && node !== this._state.a11yVirtualCursorTarget.node) {
+				this._updateState({ a11yVirtualCursorTarget: { node, ts: Date.now() } });
+			}
+			// Clear the cursor only half a second after it was set. It ensures the
+			// target is not cleared by scrolling of the document during outline navigation.
+			// Particularly important for snapshots where a random scroll event would fire after
+			// debounceUntilScrollFinishes is done. In all other instances of scrolling,
+			// the virtual cursor target is cleared
+			if (node === null && Date.now() - this._state.a11yVirtualCursorTarget.ts > 500) {
+				this._updateState({ a11yVirtualCursorTarget: { node: null, ts: null } });
+			}
+		};
+
+		// Announce the search index, page and snippet of the search result
+		let a11yAnnounceSearchMessage = (index, total, pageLabel, snippet) => {
+			let searchIndex = `${this._getString("pdfReader.searchResultIndex")}: ${index + 1}.`;
+			let totalResults = `${this._getString("pdfReader.searchResultTotal")}: ${total}.`;
+			let page = pageLabel !== null ? `${this._getString("pdfReader.page")}: ${pageLabel}.` : "";
+			this.setA11yMessage(`${searchIndex} ${totalResults} ${snippet || ""} ${page}`);
+		};
+
 		let data;
 		if (this._type === 'pdf') {
 			data = this._data;
@@ -908,7 +927,9 @@ class Reader {
 			onTabOut,
 			onKeyDown,
 			onKeyUp,
-			onFocusAnnotation
+			onFocusAnnotation,
+			setA11yVirtualCursorTarget,
+			a11yAnnounceSearchMessage
 		};
 
 		if (this._type === 'pdf') {
@@ -939,6 +960,7 @@ class Reader {
 				fontFamily: this._state.fontFamily,
 				hyphenate: this._state.hyphenate,
 				onEPUBEncrypted,
+				setA11yNavContent,
 			});
 		} else if (this._type === 'snapshot') {
 			view = new SnapshotView({
@@ -965,6 +987,46 @@ class Reader {
 		document.getElementById("a11yAnnouncement").innerText = a11yMessage;
 	}
 
+	// Make a11yVirtualCursorTarget node set previously focusable and
+	// focus it to help screen readers understand where the virtual cursor needs to
+	// be positioned. This is required because screen readers are not aware of
+	// scroll positioning, so without this, the virtual cursor will always land
+	// at the start of the document.
+	placeA11yVirtualCursor() {
+		let target = this._state.a11yVirtualCursorTarget.node;
+		let doc = this._lastView._iframe.contentDocument;
+		// If the target is a text node, use its parent (e.g. <p> or <h>)
+		if (target?.nodeType === Node.TEXT_NODE) {
+			target = target.parentNode;
+		}
+		if (!target || !doc.contains(target)) return;
+		// Make it temporarily focusable
+		target.setAttribute("tabindex", "-1");
+		target.focus();
+
+		// On blur or keypress, blur it
+		if (doc.activeElement == target) {
+			target.addEventListener("blur", (_) => {
+				target.removeAttribute("tabindex");
+			});
+			target.addEventListener("keydown", (_) => {
+				target.blur();
+			});
+			// Keypress may not fire if screen reader is being used, in which
+			// case remove tabindex next time the page content is scrolled
+			let cleanUpOnScroll = (_) => {
+				target.blur();
+				doc.removeEventListener("scroll", cleanUpOnScroll);
+			};
+			doc.addEventListener("scroll", cleanUpOnScroll);
+		}
+		// If the focus didn't take, make sure temp tabindex is removed
+		else {
+			target.removeAttribute("tabindex");
+		}
+		this._updateState({ a11yVirtualCursorTarget: { node: null, ts: null } });
+	}
+
 	getUnsavedAnnotations() {
 
 	}
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 9d2c4e23..97d0ad20 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -1138,6 +1138,9 @@ abstract class DOMView<State extends DOMViewState, Data> {
 			this._renderAnnotations();
 			this._repositionPopups();
 		});
+		// Clear whatever node we may have planned to focus for screen readers
+		// to not interfere with mouse navigation
+		this._options.setA11yVirtualCursorTarget(null);
 	}
 
 	protected _handleScrollCapture(event: Event) {
@@ -1412,6 +1415,9 @@ export type DOMViewOptions<State extends DOMViewState, Data> = {
 	onKeyUp: (event: KeyboardEvent) => void;
 	onKeyDown: (event: KeyboardEvent) => void;
 	onEPUBEncrypted: () => void;
+	setA11yVirtualCursorTarget: (node: Node | null) => void;
+	setA11yNavContent: (node: Node, pageIndex: string) => void;
+	a11yAnnounceSearchMessage: (index: number, total: number, pageLabel: string | null, snippet: string) => void;
 	data: Data & {
 		buf?: Uint8Array,
 		url?: string
diff --git a/src/dom/common/lib/range.ts b/src/dom/common/lib/range.ts
index 4e1945b5..64845040 100644
--- a/src/dom/common/lib/range.ts
+++ b/src/dom/common/lib/range.ts
@@ -15,11 +15,14 @@ export class PersistentRange {
 
 	endOffset: number;
 
+	collapsed: boolean;
+
 	constructor(range: AbstractRange) {
 		this.startContainer = range.startContainer;
 		this.startOffset = range.startOffset;
 		this.endContainer = range.endContainer;
 		this.endOffset = range.endOffset;
+		this.collapsed = range.collapsed;
 	}
 
 	toRange(): Range {
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 5aff68ed..9b76b141 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -22,6 +22,7 @@ import Epub, {
 	NavItem,
 } from "epubjs";
 import {
+	getStartElement,
 	moveRangeEndsIntoTextNodes,
 	PersistentRange,
 	splitRangeToTextNodes
@@ -42,6 +43,7 @@ import SectionRenderer from "./section-renderer";
 import Section from "epubjs/types/section";
 import {
 	closestElement,
+	getVisibleTextNodes,
 	getContainingBlock
 } from "../common/lib/nodes";
 import { StyleScoper } from "./lib/sanitize-and-render";
@@ -56,6 +58,7 @@ import {
 	ScrolledFlow
 } from "./flow";
 import { DEFAULT_EPUB_APPEARANCE, RTL_SCRIPTS } from "./defines";
+import { debounceUntilScrollFinishes } from "../../common/lib/utilities";
 
 class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 	protected _find: EPUBFindProcessor | null = null;
@@ -177,6 +180,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		this._sectionsContainer.hidden = false;
 		this.pageMapping = this._initPageMapping(viewState.savedPageMapping);
 		this._initOutline();
+		this._addAriaNavigationLandmarks();
 
 		// Validate viewState and its properties
 		// Also make sure this doesn't trigger _updateViewState
@@ -342,6 +346,24 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		}
 	}
 
+	// Add landmarks with page labels for screen reader navigation
+	private async _addAriaNavigationLandmarks() {
+		for (let [key, value] of this.pageMapping.tree.entries()) {
+			let node = key.startContainer;
+			let containingElement = closestElement(node);
+
+			if (!containingElement) continue;
+
+			// This is semantically not correct, as we are assigning
+			// navigation role to <p> and <h> nodes but this is the
+			// best solution to avoid adding nodes into the DOM, which
+			// will break CFIs.
+			containingElement.setAttribute("role", "navigation");
+
+			this._options.setA11yNavContent(containingElement, value);
+		}
+	}
+
 	override toSelector(range: Range): FragmentSelector | null {
 		range = moveRangeEndsIntoTextNodes(range);
 		let cfi = this.getCFI(range);
@@ -911,6 +933,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			let result = await processor.next();
 			if (result) {
 				this.flow.scrollIntoView(result.range);
+				this.a11yHandleSearchResultUpdate(result.range);
 			}
 			this._renderAnnotations();
 		}
@@ -923,11 +946,30 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			let result = await processor.prev();
 			if (result) {
 				this.flow.scrollIntoView(result.range);
+				this.a11yHandleSearchResultUpdate(result.range);
 			}
 			this._renderAnnotations();
 		}
 	}
 
+	// After the search result is switched to, record which node the
+	// search result is in to place screen readers' virtual cursor on it
+	// + announce the result.
+	async a11yHandleSearchResultUpdate(range: PersistentRange) {
+		await debounceUntilScrollFinishes(this._iframeDocument);
+
+		let searchResult = getStartElement(range);
+		let currentPageLabel = this.pageMapping.getPageLabel(range);
+		if (!searchResult || !this._findState?.result || !currentPageLabel) return;
+
+		this._options.setA11yVirtualCursorTarget(searchResult);
+
+		let { index, total } = this._findState.result;
+		
+		let snippet = this._findState.result.snippets[this._findState.result.index];
+		this._options.a11yAnnounceSearchMessage(index, total, currentPageLabel, snippet);
+	}
+
 	protected _setScale(scale: number) {
 		this._keepPosition(() => {
 			this.scale = scale;
@@ -994,6 +1036,12 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 					return;
 				}
 				this.flow.scrollIntoView(view.container, options);
+				// Once scrolling is done, tell screen readers to focus the first textual element of
+				// the section. Used when you navigate to a new section via outline in the sidebar.
+				let firstText = getVisibleTextNodes(view.body)[0];
+				debounceUntilScrollFinishes(this._iframeDocument).then(() => {
+					this._options.setA11yVirtualCursorTarget(firstText || view.body);
+				});
 			}
 		}
 		else {
diff --git a/src/dom/snapshot/snapshot-view.ts b/src/dom/snapshot/snapshot-view.ts
index 2f13b7f8..218b75d1 100644
--- a/src/dom/snapshot/snapshot-view.ts
+++ b/src/dom/snapshot/snapshot-view.ts
@@ -9,7 +9,8 @@ import {
 } from "../../common/types";
 import {
 	getInnerText,
-	getStartElement
+	getStartElement,
+	PersistentRange
 } from "../common/lib/range";
 import {
 	CssSelector,
@@ -33,6 +34,7 @@ import injectCSS from './stylesheets/inject.scss';
 // @ts-expect-error
 import darkReaderJS from '!!raw-loader!darkreader/darkreader';
 import { DynamicThemeFix } from "darkreader";
+import { debounceUntilScrollFinishes } from "../../common/lib/utilities";
 
 class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 	protected _find: DefaultFindProcessor | null = null;
@@ -312,7 +314,15 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 	protected _navigateToSelector(selector: Selector, options: NavigateOptions = {}) {
 		let range = this.toDisplayedRange(selector);
 		if (range) {
-			getStartElement(range)?.scrollIntoView(options);
+			let elem = getStartElement(range);
+			if (!elem) return;
+			elem.scrollIntoView(options);
+			// Remember which node was navigated to for screen readers to place
+			// virtual cursor on it later. Used for navigating between sections in the outline.
+			this._options.setA11yVirtualCursorTarget(elem);
+			debounceUntilScrollFinishes(this._iframeDocument).then(() => {
+				this._options.setA11yVirtualCursorTarget(elem);
+			});
 		}
 		else {
 			console.warn('Not a valid snapshot selector', selector);
@@ -434,6 +444,7 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			let result = this._find.next();
 			if (result) {
 				getStartElement(result.range)?.scrollIntoView({ block: 'center' });
+				this.a11yHandleSearchResultUpdate(result.range);
 			}
 			this._renderAnnotations();
 		}
@@ -445,11 +456,30 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			let result = this._find.prev();
 			if (result) {
 				getStartElement(result.range)?.scrollIntoView({ block: 'center' });
+				this.a11yHandleSearchResultUpdate(result.range);
 			}
 			this._renderAnnotations();
 		}
 	}
 
+
+	// After the search result is switched to, record which node the
+	// search result is in to place screen readers' virtual cursor on it
+	// + announce the result.
+	async a11yHandleSearchResultUpdate(range: PersistentRange) {
+		await debounceUntilScrollFinishes(this._iframeDocument);
+
+		let searchResult = getStartElement(range);
+		if (!searchResult || !this._findState?.result) return;
+
+		this._options.setA11yVirtualCursorTarget(searchResult);
+
+		let { index, total } = this._findState.result;
+		
+		let snippet = this._findState.result.snippets[this._findState.result.index];
+		this._options.a11yAnnounceSearchMessage(index, total, null, snippet);
+	}
+
 	protected _setScale(scale: number) {
 		this.scale = scale;
 
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index e15ee5a0..f281cb3c 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -216,6 +216,9 @@ class PDFView {
 							this._onSetSelectionPopup({ ...this._selectionPopup, rect });
 						}
 					}
+					// Clear whichever node we wanted to focus for screen reader virtual cursor
+					// navigation to not interfere with mouse interface.
+					this._options.setA11yVirtualCursorTarget(null);
 				});
 
 				this._iframeWindow.addEventListener('focus', (event) => {
@@ -519,6 +522,8 @@ class PDFView {
 		for (let page of this._pages) {
 			if (!pageIndexes || pageIndexes.includes(page.pageIndex)) {
 				page.render();
+				// Aria label with page index set by pdf.js is off by one, so fix it here
+				page.originalPage.div.dataset.l10nArgs = JSON.stringify({ page: this._getPageLabel(page.pageIndex) });
 			}
 		}
 	}
@@ -658,6 +663,8 @@ class PDFView {
 					findPrevious: false
 				});
 			}
+			// Make sure the state is updated regardless to have last _findState.result value
+			this._findState = state;
 		}
 		else {
 			this._findState = state;
@@ -675,6 +682,7 @@ class PDFView {
 			highlightAll: this._findState.highlightAll,
 			findPrevious: false
 		});
+		this.a11yHandleSearchResultUpdate();
 	}
 
 	findPrevious() {
@@ -688,6 +696,30 @@ class PDFView {
 			highlightAll: this._findState.highlightAll,
 			findPrevious: true
 		});
+		this.a11yHandleSearchResultUpdate();
+	}
+
+
+	// After the search result is switched to, record which node the
+	// search result is in to place screen readers' virtual cursor on it
+	// + announce the result.
+	async a11yHandleSearchResultUpdate() {
+		await debounceUntilScrollFinishes(this._iframeWindow.document);
+		let searchResult = this._iframeWindow.document.querySelector(".highlight.selected.appended");
+		if (!searchResult || !this._findState.result) return;
+
+		this._options.setA11yVirtualCursorTarget(searchResult.parentNode);
+
+		let { index, total } = this._findState.result;
+		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
+		let pageLabel = this._getPageLabel(currentPageNumber - 1);
+
+		let span = searchResult.parentNode;
+		let previousSpanText = span.previousSibling?.textContent || "";
+		let nextSpanText = span.nextSibling?.textContent || "";
+		let snippet = previousSpanText + span.textContent + nextSpanText;
+
+		this._options.a11yAnnounceSearchMessage(index, total, pageLabel, snippet);
 	}
 
 	setSelectedAnnotationIDs(ids) {

From 8ae110505de4de25df81954e15c5fd94f5cf2d17 Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Thu, 5 Sep 2024 17:31:07 -0700
Subject: [PATCH 2/9] move virtual cursor when page is set in toolbar

So that screen reader users land on the right page
after changing the page number in the input or via
buttons next to it. Once the input is changed,
Escape keypress re-focuses the reader and it will
focus an element at the top of the page for virtual
cursor to move.
---
 src/dom/epub/epub-view.ts | 21 +++++++++++++++++++++
 src/pdf/pdf-view.js       | 14 ++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 9b76b141..7d2e1f0a 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -970,6 +970,24 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		this._options.a11yAnnounceSearchMessage(index, total, currentPageLabel, snippet);
 	}
 
+	// Place virtual cursor to the top of the current page. Used after the page
+	// input value is changed in the toolbar
+	async a11yWillPlaceVirtCursorOnTop() {
+		if (!this.flow.startRange) return;
+		let counter = 0;
+		let initialStartContainer = this.flow.startRange.startContainer;
+		// Wait to be scrolled to the new page and for the flow to be updated.
+		// Used instead of debounceUntilScrollFinishes which returns before the flow is changed.
+		while (initialStartContainer == this.flow.startRange.startContainer && counter < 100) {
+			await new Promise(resolve => setTimeout(resolve, 100));
+			// ensure we are not stuck in an infinite loop is something goes wrong
+			counter += 1;
+		}
+		let node = this.flow.startRange.startContainer;
+		let containingElement = closestElement(node);
+		this._options.setA11yVirtualCursorTarget(containingElement);
+	}
+
 	protected _setScale(scale: number) {
 		this._keepPosition(() => {
 			this.scale = scale;
@@ -1001,6 +1019,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 				console.error('Unable to find range');
 				return;
 			}
+			this.a11yWillPlaceVirtCursorOnTop();
 			this.flow.scrollIntoView(range, options);
 		}
 		else if (location.href) {
@@ -1067,10 +1086,12 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 
 	navigateToPreviousPage() {
 		this.flow.navigateToPreviousPage();
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToNextPage() {
 		this.flow.navigateToNextPage();
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	canNavigateToPreviousSection() {
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index f281cb3c..69c39a46 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -722,6 +722,17 @@ class PDFView {
 		this._options.a11yAnnounceSearchMessage(index, total, pageLabel, snippet);
 	}
 
+	// Record the top of the current page as the element that the virtual cursor
+	// should land on when focus enters the content. Used after the page
+	// input value is changed in the toolbar
+	async a11yWillPlaceVirtCursorOnTop() {
+		await debounceUntilScrollFinishes(this._iframeWindow.document, 500);
+		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
+		let page = this._iframeWindow.PDFViewerApplication.pdfViewer._pages[currentPageNumber - 1];
+		let pageTop = page.div.querySelector("span");
+		this._options.setA11yVirtualCursorTarget(pageTop);
+	}
+
 	setSelectedAnnotationIDs(ids) {
 		this._selectedAnnotationIDs = ids;
 		this._setSelectionRanges();
@@ -836,6 +847,7 @@ class PDFView {
 			let pageIndex = this._pageLabels.findIndex(x => x === location.pageNumber);
 			if (pageIndex !== -1) {
 				this._iframeWindow.PDFViewerApplication.pdfViewer.scrollPageIntoView({ pageNumber: pageIndex + 1 });
+				this.a11yWillPlaceVirtCursorOnTop();
 			}
 			else {
 				let pageIndex = parseInt(location.pageNumber) - 1;
@@ -859,10 +871,12 @@ class PDFView {
 
 	navigateToNextPage() {
 		this._iframeWindow.PDFViewerApplication.pdfViewer.nextPage();
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToPreviousPage() {
 		this._iframeWindow.PDFViewerApplication.pdfViewer.previousPage();
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToFirstPage() {

From e8f1a15c2678e59616260ee3c477adf002543caf Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Fri, 6 Sep 2024 12:27:31 -0700
Subject: [PATCH 3/9] move virtualCursor handling into views

Except for placeA11yVirtualCursor which has the logic
shared by all view types but it now fetches the node to
focus from the view.
---
 src/common/reader.js              | 33 ++++++-------------------------
 src/dom/common/dom-view.tsx       | 28 +++++++++++++++++++++++++-
 src/dom/epub/epub-view.ts         |  6 +++---
 src/dom/snapshot/snapshot-view.ts |  5 ++---
 src/pdf/pdf-view.js               | 31 ++++++++++++++++++++++++++---
 5 files changed, 66 insertions(+), 37 deletions(-)

diff --git a/src/common/reader.js b/src/common/reader.js
index 6e6b3322..a6576802 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -185,10 +185,6 @@ class Reader {
 				caseSensitive: false,
 				entireWord: false,
 				result: null
-			},
-			a11yVirtualCursorTarget: {
-				node: null,
-				ts: null
 			}
 		};
 
@@ -786,7 +782,7 @@ class Reader {
 			this.focusView(primary);
 			// A workaround for Firefox/Zotero because iframe focusing doesn't trigger 'focusin' event
 			this._focusManager._closeFindPopupIfEmpty();
-			this.placeA11yVirtualCursor();
+			this.placeA11yVirtualCursor(primary);
 		};
 
 		let onRequestPassword = () => {
@@ -857,22 +853,6 @@ class Reader {
 			node.setAttribute('aria-label', `${this._getString("pdfReader.page")}: ${pageIndex}`);
 		};
 
-		// Set which node should receive focus when the focus enters the reader to
-		// help screen readers place virtual cursor at the right location
-		let setA11yVirtualCursorTarget = (node) => {
-			if (node && node !== this._state.a11yVirtualCursorTarget.node) {
-				this._updateState({ a11yVirtualCursorTarget: { node, ts: Date.now() } });
-			}
-			// Clear the cursor only half a second after it was set. It ensures the
-			// target is not cleared by scrolling of the document during outline navigation.
-			// Particularly important for snapshots where a random scroll event would fire after
-			// debounceUntilScrollFinishes is done. In all other instances of scrolling,
-			// the virtual cursor target is cleared
-			if (node === null && Date.now() - this._state.a11yVirtualCursorTarget.ts > 500) {
-				this._updateState({ a11yVirtualCursorTarget: { node: null, ts: null } });
-			}
-		};
-
 		// Announce the search index, page and snippet of the search result
 		let a11yAnnounceSearchMessage = (index, total, pageLabel, snippet) => {
 			let searchIndex = `${this._getString("pdfReader.searchResultIndex")}: ${index + 1}.`;
@@ -928,7 +908,6 @@ class Reader {
 			onKeyDown,
 			onKeyUp,
 			onFocusAnnotation,
-			setA11yVirtualCursorTarget,
 			a11yAnnounceSearchMessage
 		};
 
@@ -992,14 +971,15 @@ class Reader {
 	// be positioned. This is required because screen readers are not aware of
 	// scroll positioning, so without this, the virtual cursor will always land
 	// at the start of the document.
-	placeA11yVirtualCursor() {
-		let target = this._state.a11yVirtualCursorTarget.node;
-		let doc = this._lastView._iframe.contentDocument;
+	placeA11yVirtualCursor(primary) {
+		let view = primary ? this._primaryView : this._secondaryView;
+		let doc = view._iframe.contentDocument;
+		let target = view.getA11yVirtualCursorTarget();
 		// If the target is a text node, use its parent (e.g. <p> or <h>)
 		if (target?.nodeType === Node.TEXT_NODE) {
 			target = target.parentNode;
 		}
-		if (!target || !doc.contains(target)) return;
+		if (!target) return;
 		// Make it temporarily focusable
 		target.setAttribute("tabindex", "-1");
 		target.focus();
@@ -1024,7 +1004,6 @@ class Reader {
 		else {
 			target.removeAttribute("tabindex");
 		}
-		this._updateState({ a11yVirtualCursorTarget: { node: null, ts: null } });
 	}
 
 	getUnsavedAnnotations() {
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 97d0ad20..4a44f5bc 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -132,6 +132,8 @@ abstract class DOMView<State extends DOMViewState, Data> {
 
 	protected _resizing = false;
 
+	protected _a11yVirtualCursorTarget: { node: Node | null, ts: number | null };
+
 	scale = 1;
 
 	protected constructor(options: DOMViewOptions<State, Data>) {
@@ -152,6 +154,10 @@ abstract class DOMView<State extends DOMViewState, Data> {
 			onUpdate: () => this._updateViewStats(),
 			onNavigate: location => this.navigate(location, { skipHistory: true, behavior: 'auto' }),
 		});
+		this._a11yVirtualCursorTarget = {
+			node: null,
+			ts: null
+		};
 
 		this._iframe = document.createElement('iframe');
 		this._iframe.sandbox.add('allow-same-origin', 'allow-modals');
@@ -1140,7 +1146,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		});
 		// Clear whatever node we may have planned to focus for screen readers
 		// to not interfere with mouse navigation
-		this._options.setA11yVirtualCursorTarget(null);
+		this._setA11yVirtualCursorTarget(null);
 	}
 
 	protected _handleScrollCapture(event: Event) {
@@ -1219,6 +1225,26 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		return rectContains(selectionBoundingRect, x, y);
 	}
 
+	// Set which node should receive focus when the focus enters the reader to
+	// help screen readers place virtual cursor at the right location
+	protected _setA11yVirtualCursorTarget(node: Node | null) {
+		if (node && node !== this._a11yVirtualCursorTarget.node) {
+			this._a11yVirtualCursorTarget = { node, ts: Date.now() };
+		}
+		if (node === null && Date.now() - (this._a11yVirtualCursorTarget?.ts || 0) > 500) {
+			this._a11yVirtualCursorTarget = { node: null, ts: null };
+		}
+	}
+
+	// Return the virtual cursor and, unless specified otherwise, clear the state
+	getA11yVirtualCursorTarget(retain = false) {
+		let node = this._a11yVirtualCursorTarget.node;
+		if (!retain) {
+			this._a11yVirtualCursorTarget = { node: null, ts: null };
+		}
+		return node;
+	}
+
 	destroy() {
 		this._overlayPopupDelayer.destroy();
 	}
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 7d2e1f0a..7b36298f 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -962,7 +962,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		let currentPageLabel = this.pageMapping.getPageLabel(range);
 		if (!searchResult || !this._findState?.result || !currentPageLabel) return;
 
-		this._options.setA11yVirtualCursorTarget(searchResult);
+		this._setA11yVirtualCursorTarget(searchResult);
 
 		let { index, total } = this._findState.result;
 		
@@ -985,7 +985,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		}
 		let node = this.flow.startRange.startContainer;
 		let containingElement = closestElement(node);
-		this._options.setA11yVirtualCursorTarget(containingElement);
+		this._setA11yVirtualCursorTarget(containingElement);
 	}
 
 	protected _setScale(scale: number) {
@@ -1059,7 +1059,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 				// the section. Used when you navigate to a new section via outline in the sidebar.
 				let firstText = getVisibleTextNodes(view.body)[0];
 				debounceUntilScrollFinishes(this._iframeDocument).then(() => {
-					this._options.setA11yVirtualCursorTarget(firstText || view.body);
+					this._setA11yVirtualCursorTarget(firstText || view.body);
 				});
 			}
 		}
diff --git a/src/dom/snapshot/snapshot-view.ts b/src/dom/snapshot/snapshot-view.ts
index 218b75d1..a48d09e7 100644
--- a/src/dom/snapshot/snapshot-view.ts
+++ b/src/dom/snapshot/snapshot-view.ts
@@ -319,9 +319,8 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			elem.scrollIntoView(options);
 			// Remember which node was navigated to for screen readers to place
 			// virtual cursor on it later. Used for navigating between sections in the outline.
-			this._options.setA11yVirtualCursorTarget(elem);
 			debounceUntilScrollFinishes(this._iframeDocument).then(() => {
-				this._options.setA11yVirtualCursorTarget(elem);
+				this._setA11yVirtualCursorTarget(elem);
 			});
 		}
 		else {
@@ -472,7 +471,7 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 		let searchResult = getStartElement(range);
 		if (!searchResult || !this._findState?.result) return;
 
-		this._options.setA11yVirtualCursorTarget(searchResult);
+		this._setA11yVirtualCursorTarget(searchResult);
 
 		let { index, total } = this._findState.result;
 		
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index 69c39a46..19346e35 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -128,6 +128,11 @@ class PDFView {
 		this.initializedPromise = new Promise(resolve => this._resolveInitializedPromise = resolve);
 		this._pageLabelsPromise = new Promise(resolve => this._resolvePageLabelsPromise = resolve);
 
+		this._a11yVirtualCursorTarget = {
+			node: null,
+			ts: null
+		};
+
 		let setOptions = () => {
 			if (!this._iframeWindow?.PDFViewerApplicationOptions) {
 				return;
@@ -218,7 +223,7 @@ class PDFView {
 					}
 					// Clear whichever node we wanted to focus for screen reader virtual cursor
 					// navigation to not interfere with mouse interface.
-					this._options.setA11yVirtualCursorTarget(null);
+					this._setA11yVirtualCursorTarget(null);
 				});
 
 				this._iframeWindow.addEventListener('focus', (event) => {
@@ -708,7 +713,7 @@ class PDFView {
 		let searchResult = this._iframeWindow.document.querySelector(".highlight.selected.appended");
 		if (!searchResult || !this._findState.result) return;
 
-		this._options.setA11yVirtualCursorTarget(searchResult.parentNode);
+		this._setA11yVirtualCursorTarget(searchResult.parentNode);
 
 		let { index, total } = this._findState.result;
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
@@ -730,7 +735,27 @@ class PDFView {
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
 		let page = this._iframeWindow.PDFViewerApplication.pdfViewer._pages[currentPageNumber - 1];
 		let pageTop = page.div.querySelector("span");
-		this._options.setA11yVirtualCursorTarget(pageTop);
+		this._setA11yVirtualCursorTarget(pageTop);
+	}
+
+	// Set which node should receive focus when the focus enters the reader to
+	// help screen readers place virtual cursor at the right location
+	_setA11yVirtualCursorTarget(node) {
+		if (node && node !== this._a11yVirtualCursorTarget.node) {
+			this._a11yVirtualCursorTarget = { node, ts: Date.now() };
+		}
+		if (node === null && Date.now() - this._a11yVirtualCursorTarget.ts > 500) {
+			this._a11yVirtualCursorTarget = { node: null, ts: null };
+		}
+	}
+
+	// Return the virtual cursor and, unless specified otherwise, clear the state
+	getA11yVirtualCursorTarget(retain = false) {
+		let node = this._a11yVirtualCursorTarget.node;
+		if (!retain) {
+			this._a11yVirtualCursorTarget = { node: null, ts: null };
+		}
+		return node;
 	}
 
 	setSelectedAnnotationIDs(ids) {

From 577a916e577ec5a06b62bcea2cd65e89e106cd7b Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Fri, 6 Sep 2024 14:36:21 -0700
Subject: [PATCH 4/9] record top page to focus in _updateViewStats

- Update the target node to focus for in _updateViewStats
which triggers on every view scroll update. It allows
us to have one place where we record which page to
refocus, as opposed to doing it for every navigation
method
- To make sure our updates don't run too often and
are not cleared by the scroll listener right after
they are set, a11yWillPlaceVirtCursorOnTop runs
through a debounce which will set the node when
view updates are all finished.
- Removed timestamp of what the target was recorded
since it's irrelevant now
- Instead, added allowUpdates variable which will
not allow the node of _a11yVirtualCursorTarget to be
updated. It is needed for search results to not get
overriden by the a11yWillPlaceVirtCursorOnTop when
scrolling is done
---
 src/common/defines.js       |  2 ++
 src/dom/common/dom-view.tsx | 14 +++++---------
 src/dom/epub/defines.ts     |  2 ++
 src/dom/epub/epub-view.ts   | 34 +++++++++++-----------------------
 src/pdf/pdf-view.js         | 31 ++++++++++++++-----------------
 5 files changed, 34 insertions(+), 49 deletions(-)

diff --git a/src/common/defines.js b/src/common/defines.js
index 77a64db7..f55b05c8 100644
--- a/src/common/defines.js
+++ b/src/common/defines.js
@@ -28,3 +28,5 @@ export const MIN_IMAGE_ANNOTATION_SIZE = 10; // pt
 export const DEBOUNCE_STATE_CHANGE = 300; // ms
 export const DEBOUNCE_STATS_CHANGE = 100; // ms
 export const DEBOUNCE_FIND_POPUP_INPUT = 500; // ms
+
+export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 500; // ms
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 4a44f5bc..7375509b 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -132,7 +132,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 
 	protected _resizing = false;
 
-	protected _a11yVirtualCursorTarget: { node: Node | null, ts: number | null };
+	protected _a11yVirtualCursorTarget: { node: Node | null, allowUpdates: boolean };
 
 	scale = 1;
 
@@ -156,7 +156,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		});
 		this._a11yVirtualCursorTarget = {
 			node: null,
-			ts: null
+			allowUpdates: true
 		};
 
 		this._iframe = document.createElement('iframe');
@@ -1228,19 +1228,15 @@ abstract class DOMView<State extends DOMViewState, Data> {
 	// Set which node should receive focus when the focus enters the reader to
 	// help screen readers place virtual cursor at the right location
 	protected _setA11yVirtualCursorTarget(node: Node | null) {
-		if (node && node !== this._a11yVirtualCursorTarget.node) {
-			this._a11yVirtualCursorTarget = { node, ts: Date.now() };
-		}
-		if (node === null && Date.now() - (this._a11yVirtualCursorTarget?.ts || 0) > 500) {
-			this._a11yVirtualCursorTarget = { node: null, ts: null };
-		}
+		if (!this._a11yVirtualCursorTarget.allowUpdates) return;
+		this._a11yVirtualCursorTarget.node = node;
 	}
 
 	// Return the virtual cursor and, unless specified otherwise, clear the state
 	getA11yVirtualCursorTarget(retain = false) {
 		let node = this._a11yVirtualCursorTarget.node;
 		if (!retain) {
-			this._a11yVirtualCursorTarget = { node: null, ts: null };
+			this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
 		}
 		return node;
 	}
diff --git a/src/dom/epub/defines.ts b/src/dom/epub/defines.ts
index 8aedefa5..81985849 100644
--- a/src/dom/epub/defines.ts
+++ b/src/dom/epub/defines.ts
@@ -28,3 +28,5 @@ export const DEFAULT_EPUB_APPEARANCE: EPUBAppearance = Object.freeze({
 	pageWidth: PageWidth.Normal,
 	useOriginalFont: false,
 });
+
+export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 500;
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 7b36298f..0f973746 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -57,8 +57,9 @@ import {
 	PaginatedFlow,
 	ScrolledFlow
 } from "./flow";
-import { DEFAULT_EPUB_APPEARANCE, RTL_SCRIPTS } from "./defines";
+import { DEFAULT_EPUB_APPEARANCE, RTL_SCRIPTS, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH } from "./defines";
 import { debounceUntilScrollFinishes } from "../../common/lib/utilities";
+import { debounce } from '../../common/lib/debounce';
 
 class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 	protected _find: EPUBFindProcessor | null = null;
@@ -648,6 +649,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			spreadMode: this.spreadMode,
 		};
 		this._options.onChangeViewStats(viewStats);
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	protected override _handleViewUpdate() {
@@ -962,7 +964,10 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		let currentPageLabel = this.pageMapping.getPageLabel(range);
 		if (!searchResult || !this._findState?.result || !currentPageLabel) return;
 
+		// Make sure that the search results are not overriden by a11yWillPlaceVirtCursorOnTop 
+		this._a11yVirtualCursorTarget.allowUpdates = true;
 		this._setA11yVirtualCursorTarget(searchResult);
+		this._a11yVirtualCursorTarget.allowUpdates = false;
 
 		let { index, total } = this._findState.result;
 		
@@ -970,23 +975,15 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		this._options.a11yAnnounceSearchMessage(index, total, currentPageLabel, snippet);
 	}
 
-	// Place virtual cursor to the top of the current page. Used after the page
-	// input value is changed in the toolbar
-	async a11yWillPlaceVirtCursorOnTop() {
+	// Place virtual cursor to the top of the current page.
+	// Debounce is needed to make sure that the value is set
+	// when scrolling is finished because it clears the cursor target.
+	protected a11yWillPlaceVirtCursorOnTop = debounce(() => {
 		if (!this.flow.startRange) return;
-		let counter = 0;
-		let initialStartContainer = this.flow.startRange.startContainer;
-		// Wait to be scrolled to the new page and for the flow to be updated.
-		// Used instead of debounceUntilScrollFinishes which returns before the flow is changed.
-		while (initialStartContainer == this.flow.startRange.startContainer && counter < 100) {
-			await new Promise(resolve => setTimeout(resolve, 100));
-			// ensure we are not stuck in an infinite loop is something goes wrong
-			counter += 1;
-		}
 		let node = this.flow.startRange.startContainer;
 		let containingElement = closestElement(node);
 		this._setA11yVirtualCursorTarget(containingElement);
-	}
+	}, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH);
 
 	protected _setScale(scale: number) {
 		this._keepPosition(() => {
@@ -1019,7 +1016,6 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 				console.error('Unable to find range');
 				return;
 			}
-			this.a11yWillPlaceVirtCursorOnTop();
 			this.flow.scrollIntoView(range, options);
 		}
 		else if (location.href) {
@@ -1055,12 +1051,6 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 					return;
 				}
 				this.flow.scrollIntoView(view.container, options);
-				// Once scrolling is done, tell screen readers to focus the first textual element of
-				// the section. Used when you navigate to a new section via outline in the sidebar.
-				let firstText = getVisibleTextNodes(view.body)[0];
-				debounceUntilScrollFinishes(this._iframeDocument).then(() => {
-					this._setA11yVirtualCursorTarget(firstText || view.body);
-				});
 			}
 		}
 		else {
@@ -1086,12 +1076,10 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 
 	navigateToPreviousPage() {
 		this.flow.navigateToPreviousPage();
-		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToNextPage() {
 		this.flow.navigateToNextPage();
-		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	canNavigateToPreviousSection() {
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index 19346e35..a6c72c9d 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -44,7 +44,7 @@ import {
 } from '../common/lib/utilities';
 import { AutoScroll } from './lib/auto-scroll';
 import { PDFThumbnails } from './pdf-thumbnails';
-import { DEFAULT_TEXT_ANNOTATION_FONT_SIZE, MIN_IMAGE_ANNOTATION_SIZE, PDF_NOTE_DIMENSIONS } from '../common/defines';
+import { DEFAULT_TEXT_ANNOTATION_FONT_SIZE, MIN_IMAGE_ANNOTATION_SIZE, PDF_NOTE_DIMENSIONS, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH } from '../common/defines';
 import PDFRenderer from './pdf-renderer';
 import { drawAnnotationsOnCanvas } from './lib/render';
 import PopupDelayer from '../common/lib/popup-delayer';
@@ -55,6 +55,7 @@ import {
 	smoothPath
 } from './lib/path';
 import { History } from '../common/lib/history';
+import { debounce } from '../common/lib/debounce';
 
 class PDFView {
 	constructor(options) {
@@ -130,7 +131,7 @@ class PDFView {
 
 		this._a11yVirtualCursorTarget = {
 			node: null,
-			ts: null
+			allowUpdates: null
 		};
 
 		let setOptions = () => {
@@ -713,7 +714,9 @@ class PDFView {
 		let searchResult = this._iframeWindow.document.querySelector(".highlight.selected.appended");
 		if (!searchResult || !this._findState.result) return;
 
+		this._a11yVirtualCursorTarget.allowUpdates = true;
 		this._setA11yVirtualCursorTarget(searchResult.parentNode);
+		this._a11yVirtualCursorTarget.allowUpdates = false;
 
 		let { index, total } = this._findState.result;
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
@@ -728,32 +731,28 @@ class PDFView {
 	}
 
 	// Record the top of the current page as the element that the virtual cursor
-	// should land on when focus enters the content. Used after the page
-	// input value is changed in the toolbar
-	async a11yWillPlaceVirtCursorOnTop() {
-		await debounceUntilScrollFinishes(this._iframeWindow.document, 500);
+	// should land on when focus enters the content. Debounce is needed to
+	// make sure that the value is set when scrolling is finished because it
+	// clears the cursor target.
+	a11yWillPlaceVirtCursorOnTop = debounce(() => {
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
 		let page = this._iframeWindow.PDFViewerApplication.pdfViewer._pages[currentPageNumber - 1];
 		let pageTop = page.div.querySelector("span");
 		this._setA11yVirtualCursorTarget(pageTop);
-	}
+	}, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH);
 
 	// Set which node should receive focus when the focus enters the reader to
 	// help screen readers place virtual cursor at the right location
 	_setA11yVirtualCursorTarget(node) {
-		if (node && node !== this._a11yVirtualCursorTarget.node) {
-			this._a11yVirtualCursorTarget = { node, ts: Date.now() };
-		}
-		if (node === null && Date.now() - this._a11yVirtualCursorTarget.ts > 500) {
-			this._a11yVirtualCursorTarget = { node: null, ts: null };
-		}
+		if (!this._a11yVirtualCursorTarget.allowUpdates) return;
+		this._a11yVirtualCursorTarget.node = node;
 	}
 
 	// Return the virtual cursor and, unless specified otherwise, clear the state
 	getA11yVirtualCursorTarget(retain = false) {
 		let node = this._a11yVirtualCursorTarget.node;
 		if (!retain) {
-			this._a11yVirtualCursorTarget = { node: null, ts: null };
+			this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
 		}
 		return node;
 	}
@@ -872,7 +871,6 @@ class PDFView {
 			let pageIndex = this._pageLabels.findIndex(x => x === location.pageNumber);
 			if (pageIndex !== -1) {
 				this._iframeWindow.PDFViewerApplication.pdfViewer.scrollPageIntoView({ pageNumber: pageIndex + 1 });
-				this.a11yWillPlaceVirtCursorOnTop();
 			}
 			else {
 				let pageIndex = parseInt(location.pageNumber) - 1;
@@ -896,12 +894,10 @@ class PDFView {
 
 	navigateToNextPage() {
 		this._iframeWindow.PDFViewerApplication.pdfViewer.nextPage();
-		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToPreviousPage() {
 		this._iframeWindow.PDFViewerApplication.pdfViewer.previousPage();
-		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	navigateToFirstPage() {
@@ -2446,6 +2442,7 @@ class PDFView {
 			scrollMode,
 			spreadMode
 		});
+		this.a11yWillPlaceVirtCursorOnTop();
 	}
 
 	_handleContextMenu(event) {

From a4af150a8b6d4a51722a494df9cf5381b17c19a9 Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Mon, 9 Sep 2024 22:38:38 -0700
Subject: [PATCH 5/9] don't alter aria-label of the page

Have pdfjs handle it
---
 src/pdf/pdf-view.js | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index a6c72c9d..e367c619 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -528,8 +528,6 @@ class PDFView {
 		for (let page of this._pages) {
 			if (!pageIndexes || pageIndexes.includes(page.pageIndex)) {
 				page.render();
-				// Aria label with page index set by pdf.js is off by one, so fix it here
-				page.originalPage.div.dataset.l10nArgs = JSON.stringify({ page: this._getPageLabel(page.pageIndex) });
 			}
 		}
 	}

From 9ad399f11e959aee2171a2b0cddffed9b59c31d5 Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Wed, 11 Sep 2024 13:02:27 -0700
Subject: [PATCH 6/9] move placeA11yVirtualCursor into utilities.js

So that views can share it without keeping it in
the reader.js.

Also, clear the virtual cursor target on mousedown
instead of during scroll - it also fixes the issue of
focus jumping to focused element on click after
scroll after an outline entry is selected. But it
also allows us to avoid multiple processes fighting
to set or clear virtual cursor and reduce debounce timeout
as a result.
---
 src/common/defines.js       |  2 +-
 src/common/lib/utilities.js | 36 ++++++++++++++++++++++++++++++++
 src/common/reader.js        | 41 -------------------------------------
 src/dom/common/dom-view.tsx | 26 +++++++++++------------
 src/dom/epub/defines.ts     |  2 +-
 src/dom/epub/epub-view.ts   |  5 ++++-
 src/pdf/pdf-view.js         | 26 +++++++++++------------
 7 files changed, 68 insertions(+), 70 deletions(-)

diff --git a/src/common/defines.js b/src/common/defines.js
index f55b05c8..9eeb9740 100644
--- a/src/common/defines.js
+++ b/src/common/defines.js
@@ -29,4 +29,4 @@ export const DEBOUNCE_STATE_CHANGE = 300; // ms
 export const DEBOUNCE_STATS_CHANGE = 100; // ms
 export const DEBOUNCE_FIND_POPUP_INPUT = 500; // ms
 
-export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 500; // ms
+export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 100; // ms
diff --git a/src/common/lib/utilities.js b/src/common/lib/utilities.js
index e481c909..5ec43f35 100644
--- a/src/common/lib/utilities.js
+++ b/src/common/lib/utilities.js
@@ -332,3 +332,39 @@ if (!Array.prototype.findLastIndex) {
 		return -1;
 	};
 }
+
+/**
+ * Explicitly focus a given node within the view to force screen readers to move
+ * their virtual cursors to that element. Screen readers just look at rendered content
+ * so without this any navigation done via outline/Find in/page input in toolbar gets
+ * undone by virtual cursor either remaining where it was or even jumping to the beginning of content.
+ * @param target - node to focus from the view. Views keep track of it in  _a11yVirtualCursorTarget obj.
+ */
+export async function placeA11yVirtualCursor(target) {
+	// Can't focus a textnode, so grab its parent (e.g. <p>)
+	if (target?.nodeType === Node.TEXT_NODE) {
+		target = target.parentNode;
+	}
+	if (!target) return;
+	let doc = target.ownerDocument;
+	// Make it temporarily focusable
+	target.setAttribute("tabindex", "-1");
+	target.setAttribute("a11y-cursor-target", true);
+	target.focus();
+	// If focus didn't take, remove tabindex and stop
+	if (doc.activeElement != target) {
+		target.removeAttribute("tabindex");
+		return;
+	}
+	// Remove focus when element looses focus
+	target.addEventListener("blur", (_) => {
+		target.removeAttribute("tabindex");
+		target.removeAttribute("a11y-cursor-target");
+	});
+	// Blur the target on any keypress so that one can still scroll content with
+	// arrowUp/Down. Otherwise, all keydown events land on the target and
+	// nothing happens
+	target.addEventListener("keydown", (_) => {
+		target.blur();
+	});
+}
diff --git a/src/common/reader.js b/src/common/reader.js
index a6576802..968505e0 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -782,7 +782,6 @@ class Reader {
 			this.focusView(primary);
 			// A workaround for Firefox/Zotero because iframe focusing doesn't trigger 'focusin' event
 			this._focusManager._closeFindPopupIfEmpty();
-			this.placeA11yVirtualCursor(primary);
 		};
 
 		let onRequestPassword = () => {
@@ -966,46 +965,6 @@ class Reader {
 		document.getElementById("a11yAnnouncement").innerText = a11yMessage;
 	}
 
-	// Make a11yVirtualCursorTarget node set previously focusable and
-	// focus it to help screen readers understand where the virtual cursor needs to
-	// be positioned. This is required because screen readers are not aware of
-	// scroll positioning, so without this, the virtual cursor will always land
-	// at the start of the document.
-	placeA11yVirtualCursor(primary) {
-		let view = primary ? this._primaryView : this._secondaryView;
-		let doc = view._iframe.contentDocument;
-		let target = view.getA11yVirtualCursorTarget();
-		// If the target is a text node, use its parent (e.g. <p> or <h>)
-		if (target?.nodeType === Node.TEXT_NODE) {
-			target = target.parentNode;
-		}
-		if (!target) return;
-		// Make it temporarily focusable
-		target.setAttribute("tabindex", "-1");
-		target.focus();
-
-		// On blur or keypress, blur it
-		if (doc.activeElement == target) {
-			target.addEventListener("blur", (_) => {
-				target.removeAttribute("tabindex");
-			});
-			target.addEventListener("keydown", (_) => {
-				target.blur();
-			});
-			// Keypress may not fire if screen reader is being used, in which
-			// case remove tabindex next time the page content is scrolled
-			let cleanUpOnScroll = (_) => {
-				target.blur();
-				doc.removeEventListener("scroll", cleanUpOnScroll);
-			};
-			doc.addEventListener("scroll", cleanUpOnScroll);
-		}
-		// If the focus didn't take, make sure temp tabindex is removed
-		else {
-			target.removeAttribute("tabindex");
-		}
-	}
-
 	getUnsavedAnnotations() {
 
 	}
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 7375509b..61966375 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -38,7 +38,7 @@ import {
 import { getSelectionRanges } from "./lib/selection";
 import { FindProcessor } from "./lib/find";
 import { SELECTION_COLOR } from "../../common/defines";
-import { debounceUntilScrollFinishes, isMac, isSafari } from "../../common/lib/utilities";
+import { debounceUntilScrollFinishes, isMac, isSafari, placeA11yVirtualCursor } from "../../common/lib/utilities";
 import {
 	closestElement,
 	isElement
@@ -1064,6 +1064,9 @@ abstract class DOMView<State extends DOMViewState, Data> {
 
 		this._options.onSetOverlayPopup();
 
+		// If we marked a node as future focus target for screen readers, clear it to avoid scrolling to it
+		this._setA11yVirtualCursorTarget(null);
+
 		// Create note annotation on pointer down event, if note tool is active.
 		// The note tool will be automatically deactivated in reader.js,
 		// because this is what we do in PDF reader
@@ -1144,9 +1147,11 @@ abstract class DOMView<State extends DOMViewState, Data> {
 			this._renderAnnotations();
 			this._repositionPopups();
 		});
-		// Clear whatever node we may have planned to focus for screen readers
-		// to not interfere with mouse navigation
-		this._setA11yVirtualCursorTarget(null);
+		// If there exists a focused node for screen readers, make sure it gets blurred
+		let cursorTarget = this._iframeDocument.querySelector("[a11y-cursor-target]");
+		if (cursorTarget) {
+			(cursorTarget as HTMLElement).blur();
+		}
 	}
 
 	protected _handleScrollCapture(event: Event) {
@@ -1203,6 +1208,10 @@ abstract class DOMView<State extends DOMViewState, Data> {
 
 	private _handleFocus() {
 		this._options.onFocus();
+
+		// Help screen readers understand where to place virtual cursor
+		placeA11yVirtualCursor(this._a11yVirtualCursorTarget.node);
+		this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
 	}
 
 	private _preventNextClickEvent() {
@@ -1232,15 +1241,6 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		this._a11yVirtualCursorTarget.node = node;
 	}
 
-	// Return the virtual cursor and, unless specified otherwise, clear the state
-	getA11yVirtualCursorTarget(retain = false) {
-		let node = this._a11yVirtualCursorTarget.node;
-		if (!retain) {
-			this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
-		}
-		return node;
-	}
-
 	destroy() {
 		this._overlayPopupDelayer.destroy();
 	}
diff --git a/src/dom/epub/defines.ts b/src/dom/epub/defines.ts
index 81985849..4456b130 100644
--- a/src/dom/epub/defines.ts
+++ b/src/dom/epub/defines.ts
@@ -29,4 +29,4 @@ export const DEFAULT_EPUB_APPEARANCE: EPUBAppearance = Object.freeze({
 	useOriginalFont: false,
 });
 
-export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 500;
+export const A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH = 100;
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 0f973746..4c464bb4 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -964,7 +964,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		let currentPageLabel = this.pageMapping.getPageLabel(range);
 		if (!searchResult || !this._findState?.result || !currentPageLabel) return;
 
-		// Make sure that the search results are not overriden by a11yWillPlaceVirtCursorOnTop 
+		// Make sure that the search results are not overriden by a11yWillPlaceVirtCursorOnTop
 		this._a11yVirtualCursorTarget.allowUpdates = true;
 		this._setA11yVirtualCursorTarget(searchResult);
 		this._a11yVirtualCursorTarget.allowUpdates = false;
@@ -980,6 +980,9 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 	// when scrolling is finished because it clears the cursor target.
 	protected a11yWillPlaceVirtCursorOnTop = debounce(() => {
 		if (!this.flow.startRange) return;
+		// If the focus is within the document, do nothing to avoid unnecessarily moving
+		// the cursor to the top of the page if the window is blurred and then re-focused.
+		if (this._iframeDocument.hasFocus()) return;
 		let node = this.flow.startRange.startContainer;
 		let containingElement = closestElement(node);
 		this._setA11yVirtualCursorTarget(containingElement);
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index e367c619..053f62a6 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -32,7 +32,7 @@ import {
 	normalizeDegrees,
 	getRectsAreaSize
 } from './lib/utilities';
-import { debounceUntilScrollFinishes, normalizeKey } from '../common/lib/utilities';
+import { debounceUntilScrollFinishes, normalizeKey, placeA11yVirtualCursor } from '../common/lib/utilities';
 import {
 	getAffectedAnnotations,
 	isFirefox,
@@ -222,13 +222,15 @@ class PDFView {
 							this._onSetSelectionPopup({ ...this._selectionPopup, rect });
 						}
 					}
-					// Clear whichever node we wanted to focus for screen reader virtual cursor
-					// navigation to not interfere with mouse interface.
-					this._setA11yVirtualCursorTarget(null);
+					// If there exists a focused node for screen readers, make sure it gets blurred
+					this._iframeWindow.document.querySelector("[a11y-cursor-target]")?.blur();
 				});
 
 				this._iframeWindow.addEventListener('focus', (event) => {
 					options.onFocus();
+					// Help screen readers understand where to place virtual cursor
+					placeA11yVirtualCursor(this._a11yVirtualCursorTarget.node);
+					this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
 				});
 			});
 		});
@@ -733,6 +735,9 @@ class PDFView {
 	// make sure that the value is set when scrolling is finished because it
 	// clears the cursor target.
 	a11yWillPlaceVirtCursorOnTop = debounce(() => {
+		// If the focus is within the document, do nothing to avoid unnecessarily moving
+		// the cursor to the top of the page if the window is blurred and then re-focused.
+		if (this._iframeWindow.document.hasFocus()) return;
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
 		let page = this._iframeWindow.PDFViewerApplication.pdfViewer._pages[currentPageNumber - 1];
 		let pageTop = page.div.querySelector("span");
@@ -742,19 +747,12 @@ class PDFView {
 	// Set which node should receive focus when the focus enters the reader to
 	// help screen readers place virtual cursor at the right location
 	_setA11yVirtualCursorTarget(node) {
+		console.log("Trying to set cursor at ", node);
 		if (!this._a11yVirtualCursorTarget.allowUpdates) return;
+		console.log("-- Set!");
 		this._a11yVirtualCursorTarget.node = node;
 	}
 
-	// Return the virtual cursor and, unless specified otherwise, clear the state
-	getA11yVirtualCursorTarget(retain = false) {
-		let node = this._a11yVirtualCursorTarget.node;
-		if (!retain) {
-			this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
-		}
-		return node;
-	}
-
 	setSelectedAnnotationIDs(ids) {
 		this._selectedAnnotationIDs = ids;
 		this._setSelectionRanges();
@@ -1609,6 +1607,8 @@ class PDFView {
 		// Prevents showing focus box after pressing Enter and de-selecting annotation which was select with mouse
 		this._lastFocusedObject = null;
 
+		// If we marked a node as future focus target for screen readers, clear it to avoid scrolling to it
+		this._setA11yVirtualCursorTarget(null);
 		if (!event.target.closest('#viewerContainer')) {
 			return;
 		}

From cadc0ee81843f16133ddbe486fe6e1c818b34c6e Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Wed, 11 Sep 2024 17:15:22 -0700
Subject: [PATCH 7/9] move a11y search message handling to reader.js

General refactoring to handle search result announcements
from top-level Reader. a11yAnnounceSearchMessage
adds readers currentSnippet and currentPageLabel from
findState result if provided. Those don't exist for pdfs yet.

Added currentSnippet and currentPageLabel to be included
in epub and snapshot search results, so those are announced.

More refactoring to avoid different event handlers fighting
over who gets to set _a11yVirtualCursorTarget. It will
just not be set by the navigation handler during search mode,
which allows us to remove extraneous .allowUpdates field.

Removed a11yHandleSearchResultUpdate from all views since
messages are handler in Reader and curtorTargets can now be just
set directly in findNext/findPrevious.

Added a11yWillPlaceVirtCursorOnSearchResult specifically for pdf-view
to update virtual cursor target, since findNext does not fire on
first result, so we call a11yWillPlaceVirtCursorOnSearchResult
when findState is updated.
---
 src/common/reader.js              | 24 ++++++++------
 src/common/types.ts               |  5 ++-
 src/dom/common/dom-view.tsx       | 22 +++----------
 src/dom/common/lib/find/index.ts  |  5 ++-
 src/dom/epub/epub-view.ts         | 29 +++--------------
 src/dom/epub/find.ts              |  4 +++
 src/dom/snapshot/snapshot-view.ts | 24 ++------------
 src/pdf/pdf-view.js               | 53 ++++++++-----------------------
 8 files changed, 52 insertions(+), 114 deletions(-)

diff --git a/src/common/reader.js b/src/common/reader.js
index 968505e0..de8b3a9c 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -655,6 +655,18 @@ class Reader {
 		this._onTextSelectionAnnotationModeChange(mode);
 	}
 
+	// Announce info about current search result to screen readers.
+	// FindState is updated multiple times while navigating between results
+	// so debounce is used to fire only after the last update.
+	a11yAnnounceSearchMessage = debounce((findStateResult) => {
+		if (!findStateResult) return;
+		let { index, total, currentPageLabel, currentSnippet } = findStateResult;
+		let searchIndex = `${this._getString("pdfReader.searchResultIndex")}: ${index + 1}.`;
+		let totalResults = `${this._getString("pdfReader.searchResultTotal")}: ${total}.`;
+		let page = currentPageLabel ? `${this._getString("pdfReader.page")}: ${currentPageLabel}.` : "";
+		this.setA11yMessage(`${searchIndex} ${totalResults} ${currentSnippet || ""} ${page}`);
+	}, 100);
+
 	findNext(primary) {
 		if (primary === undefined) {
 			primary = this._lastViewPrimary;
@@ -813,6 +825,7 @@ class Reader {
 
 		let onSetFindState = (params) => {
 			this._updateState({ [primary ? 'primaryViewFindState' : 'secondaryViewFindState']: params });
+			this.a11yAnnounceSearchMessage(params.result);
 		};
 
 		let onSelectAnnotations = (ids, triggeringEvent) => {
@@ -852,14 +865,6 @@ class Reader {
 			node.setAttribute('aria-label', `${this._getString("pdfReader.page")}: ${pageIndex}`);
 		};
 
-		// Announce the search index, page and snippet of the search result
-		let a11yAnnounceSearchMessage = (index, total, pageLabel, snippet) => {
-			let searchIndex = `${this._getString("pdfReader.searchResultIndex")}: ${index + 1}.`;
-			let totalResults = `${this._getString("pdfReader.searchResultTotal")}: ${total}.`;
-			let page = pageLabel !== null ? `${this._getString("pdfReader.page")}: ${pageLabel}.` : "";
-			this.setA11yMessage(`${searchIndex} ${totalResults} ${snippet || ""} ${page}`);
-		};
-
 		let data;
 		if (this._type === 'pdf') {
 			data = this._data;
@@ -906,8 +911,7 @@ class Reader {
 			onTabOut,
 			onKeyDown,
 			onKeyUp,
-			onFocusAnnotation,
-			a11yAnnounceSearchMessage
+			onFocusAnnotation
 		};
 
 		if (this._type === 'pdf') {
diff --git a/src/common/types.ts b/src/common/types.ts
index ac848fe2..39d1d6b5 100644
--- a/src/common/types.ts
+++ b/src/common/types.ts
@@ -147,7 +147,10 @@ export type FindState = {
 		total: number,
 		index: number,
 		// Mobile app lists all results in a popup
-		snippets: string[]
+		snippets: string[],
+		// Used for a11y notifications
+		currentSnippet: string,
+		currentPageLabel: string
 	} | null;
 };
 
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 61966375..08e25137 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -132,7 +132,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 
 	protected _resizing = false;
 
-	protected _a11yVirtualCursorTarget: { node: Node | null, allowUpdates: boolean };
+	protected _a11yVirtualCursorTarget: Node | null;
 
 	scale = 1;
 
@@ -154,10 +154,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 			onUpdate: () => this._updateViewStats(),
 			onNavigate: location => this.navigate(location, { skipHistory: true, behavior: 'auto' }),
 		});
-		this._a11yVirtualCursorTarget = {
-			node: null,
-			allowUpdates: true
-		};
+		this._a11yVirtualCursorTarget = null;
 
 		this._iframe = document.createElement('iframe');
 		this._iframe.sandbox.add('allow-same-origin', 'allow-modals');
@@ -1065,7 +1062,7 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		this._options.onSetOverlayPopup();
 
 		// If we marked a node as future focus target for screen readers, clear it to avoid scrolling to it
-		this._setA11yVirtualCursorTarget(null);
+		this._a11yVirtualCursorTarget = null;
 
 		// Create note annotation on pointer down event, if note tool is active.
 		// The note tool will be automatically deactivated in reader.js,
@@ -1210,8 +1207,8 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		this._options.onFocus();
 
 		// Help screen readers understand where to place virtual cursor
-		placeA11yVirtualCursor(this._a11yVirtualCursorTarget.node);
-		this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
+		placeA11yVirtualCursor(this._a11yVirtualCursorTarget);
+		this._a11yVirtualCursorTarget = null;
 	}
 
 	private _preventNextClickEvent() {
@@ -1234,13 +1231,6 @@ abstract class DOMView<State extends DOMViewState, Data> {
 		return rectContains(selectionBoundingRect, x, y);
 	}
 
-	// Set which node should receive focus when the focus enters the reader to
-	// help screen readers place virtual cursor at the right location
-	protected _setA11yVirtualCursorTarget(node: Node | null) {
-		if (!this._a11yVirtualCursorTarget.allowUpdates) return;
-		this._a11yVirtualCursorTarget.node = node;
-	}
-
 	destroy() {
 		this._overlayPopupDelayer.destroy();
 	}
@@ -1437,9 +1427,7 @@ export type DOMViewOptions<State extends DOMViewState, Data> = {
 	onKeyUp: (event: KeyboardEvent) => void;
 	onKeyDown: (event: KeyboardEvent) => void;
 	onEPUBEncrypted: () => void;
-	setA11yVirtualCursorTarget: (node: Node | null) => void;
 	setA11yNavContent: (node: Node, pageIndex: string) => void;
-	a11yAnnounceSearchMessage: (index: number, total: number, pageLabel: string | null, snippet: string) => void;
 	data: Data & {
 		buf?: Uint8Array,
 		url?: string
diff --git a/src/dom/common/lib/find/index.ts b/src/dom/common/lib/find/index.ts
index 14930e07..43edd009 100644
--- a/src/dom/common/lib/find/index.ts
+++ b/src/dom/common/lib/find/index.ts
@@ -246,12 +246,15 @@ class DefaultFindProcessor implements FindProcessor {
 	private _setFindState() {
 		if (this._cancelled) return;
 		if (this._onSetFindState) {
+			let snippets = this.getSnippets();
 			this._onSetFindState({
 				...this.findState,
 				result: {
 					total: this._buf.length,
 					index: this._pos === null ? 0 : this._pos,
-					snippets: this.getSnippets(),
+					snippets: snippets,
+					currentPageLabel: "",
+					currentSnippet: this._pos === null ? "" : snippets[this._pos]
 				}
 			});
 		}
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 4c464bb4..0497cc07 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -935,7 +935,7 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			let result = await processor.next();
 			if (result) {
 				this.flow.scrollIntoView(result.range);
-				this.a11yHandleSearchResultUpdate(result.range);
+				this._a11yVirtualCursorTarget = getStartElement(result.range);
 			}
 			this._renderAnnotations();
 		}
@@ -948,33 +948,12 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			let result = await processor.prev();
 			if (result) {
 				this.flow.scrollIntoView(result.range);
-				this.a11yHandleSearchResultUpdate(result.range);
+				this._a11yVirtualCursorTarget = getStartElement(result.range);
 			}
 			this._renderAnnotations();
 		}
 	}
 
-	// After the search result is switched to, record which node the
-	// search result is in to place screen readers' virtual cursor on it
-	// + announce the result.
-	async a11yHandleSearchResultUpdate(range: PersistentRange) {
-		await debounceUntilScrollFinishes(this._iframeDocument);
-
-		let searchResult = getStartElement(range);
-		let currentPageLabel = this.pageMapping.getPageLabel(range);
-		if (!searchResult || !this._findState?.result || !currentPageLabel) return;
-
-		// Make sure that the search results are not overriden by a11yWillPlaceVirtCursorOnTop
-		this._a11yVirtualCursorTarget.allowUpdates = true;
-		this._setA11yVirtualCursorTarget(searchResult);
-		this._a11yVirtualCursorTarget.allowUpdates = false;
-
-		let { index, total } = this._findState.result;
-		
-		let snippet = this._findState.result.snippets[this._findState.result.index];
-		this._options.a11yAnnounceSearchMessage(index, total, currentPageLabel, snippet);
-	}
-
 	// Place virtual cursor to the top of the current page.
 	// Debounce is needed to make sure that the value is set
 	// when scrolling is finished because it clears the cursor target.
@@ -983,9 +962,11 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 		// If the focus is within the document, do nothing to avoid unnecessarily moving
 		// the cursor to the top of the page if the window is blurred and then re-focused.
 		if (this._iframeDocument.hasFocus()) return;
+		// Do not interfere with marking search results as virtual cursor targets
+		if (this._findState?.active) return;
 		let node = this.flow.startRange.startContainer;
 		let containingElement = closestElement(node);
-		this._setA11yVirtualCursorTarget(containingElement);
+		this._a11yVirtualCursorTarget = containingElement;
 	}, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH);
 
 	protected _setScale(scale: number) {
diff --git a/src/dom/epub/find.ts b/src/dom/epub/find.ts
index 72083539..b61e759b 100644
--- a/src/dom/epub/find.ts
+++ b/src/dom/epub/find.ts
@@ -178,12 +178,16 @@ export class EPUBFindProcessor implements FindProcessor {
 				}
 				snippets.push(...processor.getSnippets());
 			}
+			let current = this._selectedProcessor?.current;
+			let currentPage = current ? this.view.pageMapping.getPageLabel(current.range) : "";
 			this._onSetFindState({
 				...this.findState,
 				result: {
 					total: this._totalResults,
 					index,
 					snippets,
+					currentPageLabel: currentPage || "",
+					currentSnippet: snippets[index]
 				}
 			});
 		}
diff --git a/src/dom/snapshot/snapshot-view.ts b/src/dom/snapshot/snapshot-view.ts
index a48d09e7..5b5ef11d 100644
--- a/src/dom/snapshot/snapshot-view.ts
+++ b/src/dom/snapshot/snapshot-view.ts
@@ -320,7 +320,7 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			// Remember which node was navigated to for screen readers to place
 			// virtual cursor on it later. Used for navigating between sections in the outline.
 			debounceUntilScrollFinishes(this._iframeDocument).then(() => {
-				this._setA11yVirtualCursorTarget(elem);
+				this._a11yVirtualCursorTarget = elem;
 			});
 		}
 		else {
@@ -443,7 +443,7 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			let result = this._find.next();
 			if (result) {
 				getStartElement(result.range)?.scrollIntoView({ block: 'center' });
-				this.a11yHandleSearchResultUpdate(result.range);
+				this._a11yVirtualCursorTarget = getStartElement(result.range);
 			}
 			this._renderAnnotations();
 		}
@@ -455,30 +455,12 @@ class SnapshotView extends DOMView<SnapshotViewState, SnapshotViewData> {
 			let result = this._find.prev();
 			if (result) {
 				getStartElement(result.range)?.scrollIntoView({ block: 'center' });
-				this.a11yHandleSearchResultUpdate(result.range);
+				this._a11yVirtualCursorTarget = getStartElement(result.range);
 			}
 			this._renderAnnotations();
 		}
 	}
 
-
-	// After the search result is switched to, record which node the
-	// search result is in to place screen readers' virtual cursor on it
-	// + announce the result.
-	async a11yHandleSearchResultUpdate(range: PersistentRange) {
-		await debounceUntilScrollFinishes(this._iframeDocument);
-
-		let searchResult = getStartElement(range);
-		if (!searchResult || !this._findState?.result) return;
-
-		this._setA11yVirtualCursorTarget(searchResult);
-
-		let { index, total } = this._findState.result;
-		
-		let snippet = this._findState.result.snippets[this._findState.result.index];
-		this._options.a11yAnnounceSearchMessage(index, total, null, snippet);
-	}
-
 	protected _setScale(scale: number) {
 		this.scale = scale;
 
diff --git a/src/pdf/pdf-view.js b/src/pdf/pdf-view.js
index 053f62a6..515ec375 100644
--- a/src/pdf/pdf-view.js
+++ b/src/pdf/pdf-view.js
@@ -129,10 +129,7 @@ class PDFView {
 		this.initializedPromise = new Promise(resolve => this._resolveInitializedPromise = resolve);
 		this._pageLabelsPromise = new Promise(resolve => this._resolvePageLabelsPromise = resolve);
 
-		this._a11yVirtualCursorTarget = {
-			node: null,
-			allowUpdates: null
-		};
+		this._a11yVirtualCursorTarget = null;
 
 		let setOptions = () => {
 			if (!this._iframeWindow?.PDFViewerApplicationOptions) {
@@ -229,8 +226,8 @@ class PDFView {
 				this._iframeWindow.addEventListener('focus', (event) => {
 					options.onFocus();
 					// Help screen readers understand where to place virtual cursor
-					placeA11yVirtualCursor(this._a11yVirtualCursorTarget.node);
-					this._a11yVirtualCursorTarget = { node: null, allowUpdates: true };
+					placeA11yVirtualCursor(this._a11yVirtualCursorTarget);
+					this._a11yVirtualCursorTarget = null;
 				});
 			});
 		});
@@ -671,6 +668,7 @@ class PDFView {
 			}
 			// Make sure the state is updated regardless to have last _findState.result value
 			this._findState = state;
+			this.a11yWillPlaceVirtCursorOnSearchResult();
 		}
 		else {
 			this._findState = state;
@@ -688,7 +686,6 @@ class PDFView {
 			highlightAll: this._findState.highlightAll,
 			findPrevious: false
 		});
-		this.a11yHandleSearchResultUpdate();
 	}
 
 	findPrevious() {
@@ -702,33 +699,16 @@ class PDFView {
 			highlightAll: this._findState.highlightAll,
 			findPrevious: true
 		});
-		this.a11yHandleSearchResultUpdate();
 	}
 
 
 	// After the search result is switched to, record which node the
-	// search result is in to place screen readers' virtual cursor on it
-	// + announce the result.
-	async a11yHandleSearchResultUpdate() {
-		await debounceUntilScrollFinishes(this._iframeWindow.document);
+	// search result is in to place screen readers' virtual cursor on it.
+	a11yWillPlaceVirtCursorOnSearchResult = debounce(() => {
 		let searchResult = this._iframeWindow.document.querySelector(".highlight.selected.appended");
 		if (!searchResult || !this._findState.result) return;
-
-		this._a11yVirtualCursorTarget.allowUpdates = true;
-		this._setA11yVirtualCursorTarget(searchResult.parentNode);
-		this._a11yVirtualCursorTarget.allowUpdates = false;
-
-		let { index, total } = this._findState.result;
-		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
-		let pageLabel = this._getPageLabel(currentPageNumber - 1);
-
-		let span = searchResult.parentNode;
-		let previousSpanText = span.previousSibling?.textContent || "";
-		let nextSpanText = span.nextSibling?.textContent || "";
-		let snippet = previousSpanText + span.textContent + nextSpanText;
-
-		this._options.a11yAnnounceSearchMessage(index, total, pageLabel, snippet);
-	}
+		this._a11yVirtualCursorTarget = searchResult.parentNode;
+	}, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH);
 
 	// Record the top of the current page as the element that the virtual cursor
 	// should land on when focus enters the content. Debounce is needed to
@@ -738,21 +718,14 @@ class PDFView {
 		// If the focus is within the document, do nothing to avoid unnecessarily moving
 		// the cursor to the top of the page if the window is blurred and then re-focused.
 		if (this._iframeWindow.document.hasFocus()) return;
+		// Do not interfere with marking search results as virtual cursor targets
+		if (this._findState?.active) return;
 		let { currentPageNumber } = this._iframeWindow.PDFViewerApplication.pdfViewer;
 		let page = this._iframeWindow.PDFViewerApplication.pdfViewer._pages[currentPageNumber - 1];
-		let pageTop = page.div.querySelector("span");
-		this._setA11yVirtualCursorTarget(pageTop);
+		let pageTop = page.div.querySelector(".textLayer span");
+		this._a11yVirtualCursorTarget = pageTop;
 	}, A11Y_VIRT_CURSOR_DEBOUNCE_LENGTH);
 
-	// Set which node should receive focus when the focus enters the reader to
-	// help screen readers place virtual cursor at the right location
-	_setA11yVirtualCursorTarget(node) {
-		console.log("Trying to set cursor at ", node);
-		if (!this._a11yVirtualCursorTarget.allowUpdates) return;
-		console.log("-- Set!");
-		this._a11yVirtualCursorTarget.node = node;
-	}
-
 	setSelectedAnnotationIDs(ids) {
 		this._selectedAnnotationIDs = ids;
 		this._setSelectionRanges();
@@ -1608,7 +1581,7 @@ class PDFView {
 		this._lastFocusedObject = null;
 
 		// If we marked a node as future focus target for screen readers, clear it to avoid scrolling to it
-		this._setA11yVirtualCursorTarget(null);
+		this._a11yVirtualCursorTarget = null;
 		if (!event.target.closest('#viewerContainer')) {
 			return;
 		}

From f28c24c826d1ce7c6129e6b4df9815e48b5ede53 Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Mon, 16 Sep 2024 15:36:55 -0700
Subject: [PATCH 8/9] remove setA11yNavContent

Set aria-label on epub paragraphs directly
---
 src/common/reader.js        | 6 ------
 src/dom/common/dom-view.tsx | 1 -
 src/dom/epub/epub-view.ts   | 3 ++-
 3 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/common/reader.js b/src/common/reader.js
index de8b3a9c..98572d89 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -860,11 +860,6 @@ class Reader {
 			this.setA11yMessage(annotationContent);
 		}
 
-		// Add page number as aria-label to provided node to improve screen reader navigation
-		let setA11yNavContent = (node, pageIndex) => {
-			node.setAttribute('aria-label', `${this._getString("pdfReader.page")}: ${pageIndex}`);
-		};
-
 		let data;
 		if (this._type === 'pdf') {
 			data = this._data;
@@ -942,7 +937,6 @@ class Reader {
 				fontFamily: this._state.fontFamily,
 				hyphenate: this._state.hyphenate,
 				onEPUBEncrypted,
-				setA11yNavContent,
 			});
 		} else if (this._type === 'snapshot') {
 			view = new SnapshotView({
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 08e25137..2dae24b3 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -1427,7 +1427,6 @@ export type DOMViewOptions<State extends DOMViewState, Data> = {
 	onKeyUp: (event: KeyboardEvent) => void;
 	onKeyDown: (event: KeyboardEvent) => void;
 	onEPUBEncrypted: () => void;
-	setA11yNavContent: (node: Node, pageIndex: string) => void;
 	data: Data & {
 		buf?: Uint8Array,
 		url?: string
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index 0497cc07..af4133e0 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -361,7 +361,8 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			// will break CFIs.
 			containingElement.setAttribute("role", "navigation");
 
-			this._options.setA11yNavContent(containingElement, value);
+			// Todo: add localization
+			containingElement.setAttribute('aria-label', `Page: ${value}`);
 		}
 	}
 

From 2bd6260c31bf445916d3731363d3fd0284f3e5a0 Mon Sep 17 00:00:00 2001
From: Bogdan Abaev <bogdan@zotero.org>
Date: Mon, 16 Sep 2024 15:51:09 -0700
Subject: [PATCH 9/9] expose getLocalizeString to views

And use it to get localized page label for epub
---
 src/common/reader.js        | 5 ++++-
 src/dom/common/dom-view.tsx | 1 +
 src/dom/epub/epub-view.ts   | 4 ++--
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/common/reader.js b/src/common/reader.js
index 98572d89..d86ed0e8 100644
--- a/src/common/reader.js
+++ b/src/common/reader.js
@@ -860,6 +860,8 @@ class Reader {
 			this.setA11yMessage(annotationContent);
 		}
 
+		let getLocalizedString = (name) => this._getString(name);
+
 		let data;
 		if (this._type === 'pdf') {
 			data = this._data;
@@ -906,7 +908,8 @@ class Reader {
 			onTabOut,
 			onKeyDown,
 			onKeyUp,
-			onFocusAnnotation
+			onFocusAnnotation,
+			getLocalizedString
 		};
 
 		if (this._type === 'pdf') {
diff --git a/src/dom/common/dom-view.tsx b/src/dom/common/dom-view.tsx
index 2dae24b3..380e44e0 100644
--- a/src/dom/common/dom-view.tsx
+++ b/src/dom/common/dom-view.tsx
@@ -1427,6 +1427,7 @@ export type DOMViewOptions<State extends DOMViewState, Data> = {
 	onKeyUp: (event: KeyboardEvent) => void;
 	onKeyDown: (event: KeyboardEvent) => void;
 	onEPUBEncrypted: () => void;
+	getLocalizedString: (name: string) => string;
 	data: Data & {
 		buf?: Uint8Array,
 		url?: string
diff --git a/src/dom/epub/epub-view.ts b/src/dom/epub/epub-view.ts
index af4133e0..454d20f2 100644
--- a/src/dom/epub/epub-view.ts
+++ b/src/dom/epub/epub-view.ts
@@ -361,8 +361,8 @@ class EPUBView extends DOMView<EPUBViewState, EPUBViewData> {
 			// will break CFIs.
 			containingElement.setAttribute("role", "navigation");
 
-			// Todo: add localization
-			containingElement.setAttribute('aria-label', `Page: ${value}`);
+			let localizedLabel = `${this._options.getLocalizedString("pdfReader.page")}: ${value}`;
+			containingElement.setAttribute('aria-label', localizedLabel);
 		}
 	}