From 690367794103201e9b78ecab99e81c0dfdb10faa Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 02:14:56 +0200 Subject: [PATCH 01/19] fix: keep page swipes continuous across chapters and PDFs --- lib/src/engine/epub/epub_viewport.dart | 247 ++++++++++------ lib/src/engine/pdf/pdf_facade.dart | 321 +++++++++++++++++++-- lib/src/engine/pdf/pdf_reader_engine.dart | 1 + test/engine/epub_reader_engine_test.dart | 3 +- test/presentation/epub_page_turn_test.dart | 87 +++++- test/presentation/epub_selection_test.dart | 6 +- test/presentation/pdf_tools_test.dart | 119 ++++++++ 7 files changed, 656 insertions(+), 128 deletions(-) diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index 2fda631..f2b69ba 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -37,9 +37,9 @@ final class _EpubViewportState extends State { TextDirection _direction = TextDirection.ltr; int _fontRevision = 0; final Map _layoutCache = {}; - List? _turnPages; - int _turnDirection = 0; - int? _turnSpine; + Future? _boundaryCommit; + bool _commandTurning = false; + int get _leadingPages => widget.engine.locator.spineIndex > 0 ? 1 : 0; static const _spreadsAhead = 5; static const _spreadsBehind = 3; final Set _warmingImages = {}; @@ -59,7 +59,6 @@ final class _EpubViewportState extends State { widget.engine.preferences.pageTurnAnimation && !(MediaQuery.maybeOf(context)?.disableAnimations ?? false); - int _startPage = 0; double _startScroll = 0; bool _restoring = false; bool _busy = false; @@ -312,9 +311,7 @@ final class _EpubViewportState extends State { if (widget.engine.preferences.layoutMode == ReaderLayoutMode.paginated) { final previous = _pagesController; _pagesController = PageController( - initialPage: _turnPages == null - ? _pageIndex - : (_turnDirection > 0 ? 0 : 1), + initialPage: _pageIndex + _leadingPages, keepPage: false, ); WidgetsBinding.instance.addPostFrameCallback((_) => previous.dispose()); @@ -357,31 +354,7 @@ final class _EpubViewportState extends State { _restoring = true; if (widget.engine.preferences.layoutMode == ReaderLayoutMode.paginated) { if (_pagesController.hasClients) { - if (_turnPages != null) { - final controller = _pagesController; - await controller.animateToPage( - _turnDirection > 0 ? 1 : 0, - duration: _turnDuration, - curve: Curves.easeOutCubic, - ); - - if (!mounted || !identical(_pagesController, controller)) return; - final replacement = PageController( - initialPage: _pageIndex, - keepPage: false, - ); - setState(() { - _turnPages = null; - _pagesController = replacement; - }); - WidgetsBinding.instance.addPostFrameCallback( - (_) => controller.dispose(), - ); - await WidgetsBinding.instance.endOfFrame; - if (!mounted || !identical(_pagesController, replacement)) return; - } else { - _pagesController.jumpToPage(_pageIndex); - } + _pagesController.jumpToPage(_pageIndex + _leadingPages); } } else if (_scrollController.hasClients && _scrollOffsets.isNotEmpty) { var pixels = _scrollOffsets[target]; @@ -423,6 +396,7 @@ final class _EpubViewportState extends State { } Future _move(int direction) async { + await _boundaryCommit; while (_busy && mounted) { final ready = _layoutReady; if (ready == null) return true; @@ -457,34 +431,46 @@ final class _EpubViewportState extends State { final count = (_pages.length / _columns).ceil(); if (next < 0 || next >= count) { - final index = widget.engine.locator.spineIndex + direction; - if (index < 0 || index >= widget.engine.chapterCount) return false; - final animate = _animateTurns; - final from = _pageIndex * _columns; - final outgoing = _pages.sublist( - from, - math.min(from + _columns, _pages.length), - ); final spine = widget.engine.locator.spineIndex; - - // Prepare first, keeping the committed page interactive while work yields. - await widget.engine.goTo( - EpubReaderLocator( - spineIndex: index, - localProgression: direction < 0 ? 1 : 0, - totalProgression: widget.engine.locator.totalProgression, - ), + final neighbor = spine + direction; + if (neighbor < 0 || neighbor >= widget.engine.chapterCount) return false; + final chapter = await widget.engine.chapterContent(neighbor); + await _measure( + neighbor, + EpubContentBlocks(chapter['blocks'] as List), + toEnd: direction < 0, ); - if (!mounted) return true; - _turnPages = animate ? outgoing : null; - _turnDirection = direction; - _turnSpine = spine; + if (!mounted || widget.engine.locator.spineIndex != spine) return true; + setState(() {}); await WidgetsBinding.instance.endOfFrame; - await _layoutReady?.future; + if (!mounted) return true; + final controller = _pagesController; + if (!controller.hasClients) return true; + final target = next + _leadingPages; + _commandTurning = true; + try { + if (_animateTurns) { + await controller.animateToPage( + target, + duration: _turnDuration, + curve: Curves.easeOutCubic, + ); + } else { + controller.jumpToPage(target); + } + } finally { + _commandTurning = false; + } + if (mounted && + identical(controller, _pagesController) && + controller.hasClients && + (controller.page! - target).abs() < .001) { + await _commitBoundary(direction); + } return true; } - if (next >= _pageViewCount) { + if (next + _leadingPages >= _pageViewCount) { // A prepared page may not yet be included in the PageView's scroll extent. setState(() {}); await WidgetsBinding.instance.endOfFrame; @@ -498,10 +484,10 @@ final class _EpubViewportState extends State { } if (!_animateTurns) { - controller.jumpToPage(next); + controller.jumpToPage(next + _leadingPages); } else { await controller.animateToPage( - next, + next + _leadingPages, duration: _turnDuration, curve: Curves.easeOutCubic, ); @@ -515,19 +501,65 @@ final class _EpubViewportState extends State { final page = controller.page; if (page != null) { - _publishPage(page.round()); + _publishPage(page.round() - _leadingPages); } } return true; } + Future _commitBoundary(int direction) { + return _boundaryCommit ??= _changeChapter( + direction, + ).whenComplete(() => _boundaryCommit = null); + } + + Future _changeChapter(int direction) async { + await widget.engine.goTo( + EpubReaderLocator( + spineIndex: widget.engine.locator.spineIndex + direction, + localProgression: direction < 0 ? 1 : 0, + totalProgression: widget.engine.locator.totalProgression, + ), + ); + if (!mounted) return; + await WidgetsBinding.instance.endOfFrame; + await _layoutReady?.future; + } + + void _settledPage() { + if (!mounted || + _busy || + _restoring || + _commandTurning || + !_pagesController.hasClients || + _pagesController.position.isScrollingNotifier.value) { + return; + } + final page = _pagesController.page! - _leadingPages; + final count = (_pages.length / _columns).ceil(); + if (page >= 0 && page < count) return; + unawaited( + _commitBoundary(page < 0 ? -1 : 1).catchError((Object error) { + if (!mounted) return; + _pagesController.jumpToPage(_pageIndex + _leadingPages); + ScaffoldMessenger.maybeOf( + context, + )?.showSnackBar(SnackBar(content: Text(error.toString()))); + }), + ); + } + void _publishPage( int index, { int? restoredOffset, bool schedulePrefetch = true, }) { - if (_restoring || _busy || _pages.isEmpty) { + if (_restoring || + _busy || + _pages.isEmpty || + index < 0 || + index >= (_pages.length / _columns).ceil()) { return; } @@ -659,7 +691,6 @@ final class _EpubViewportState extends State { layout.dispose(); } _layoutCache.clear(); - _turnPages = null; } Future> _measure( @@ -828,6 +859,7 @@ final class _EpubViewportState extends State { prefetch: generation, ); if (_prefetchCancelled(generation)) return; + setState(() {}); _warmImages( pages, direction < 0 ? pages.length - _spreadsBehind * _columns : 0, @@ -1105,36 +1137,63 @@ final class _EpubViewportState extends State { ), ); } else { - final outgoing = _turnPages; - _pageViewCount = outgoing == null - ? (pages.length / columns).ceil() - : 2; - content = PageView.builder( - key: ValueKey(_pagesController), - controller: _pagesController, - physics: _animateTurns - ? null - : const NeverScrollableScrollPhysics(), - onPageChanged: _publishPage, - itemCount: _pageViewCount, - itemBuilder: (context, index) { - if (outgoing != null) { - final oldPage = index == (_turnDirection > 0 ? 0 : 1); + final leading = _leadingPages; + final count = (pages.length / columns).ceil(); + final hasNext = + _layoutCache[_layoutKey]?.complete == true && + widget.engine.locator.spineIndex + 1 < + widget.engine.chapterCount; + _pageViewCount = leading + count + (hasNext ? 1 : 0); + content = NotificationListener( + onNotification: (notification) { + if (notification.depth == 0 && + !_commandTurning && + !_restoring && + !_busy) { + scheduleMicrotask(_settledPage); + } + return false; + }, + child: PageView.builder( + key: ValueKey(_pagesController), + controller: _pagesController, + physics: _animateTurns + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + onPageChanged: (index) => _publishPage(index - leading), + itemCount: _pageViewCount, + itemBuilder: (context, index) { + final local = index - leading; + if (local < 0 || local >= count) { + final direction = local < 0 ? -1 : 1; + final spine = + widget.engine.locator.spineIndex + direction; + final neighbor = + _layoutCache[(spine, _geometryKey)]; + if (neighbor == null || + neighbor.pages.isEmpty || + (direction < 0 && !neighbor.complete)) { + return const ReaderLoading(); + } + return _spread( + neighbor.pages, + direction > 0 + ? 0 + : (neighbor.pages.length / columns).ceil() - + 1, + columns, + displayPreferences, + spine: spine, + ); + } return _spread( - oldPage ? outgoing : pages, - oldPage ? 0 : _pageIndex, + pages, + local, columns, displayPreferences, - spine: oldPage ? _turnSpine : null, ); - } - return _spread( - pages, - index, - columns, - displayPreferences, - ); - }, + }, + ), ); } final surface = ReaderHighlightInteraction( @@ -1143,7 +1202,6 @@ final class _EpubViewportState extends State { child: Listener( onPointerDown: (event) { _swipe.start(event); - _startPage = _pageIndex; _startScroll = _scrollController.hasClients ? _scrollController.offset : 0; @@ -1179,14 +1237,11 @@ final class _EpubViewportState extends State { _requestTurn(-1); } } else { - if (drag < 0 && - (!_animateTurns || - _startPage == - (pages.length / columns).ceil() - 1)) { + if (drag < 0 && !_animateTurns) { _requestTurn(1); } - if (drag > 0 && (!_animateTurns || _startPage == 0)) { + if (drag > 0 && !_animateTurns) { _requestTurn(-1); } } @@ -1225,10 +1280,7 @@ final class _EpubViewportState extends State { return Stack( fit: StackFit.expand, children: [ - IgnorePointer( - ignoring: !ready || _turnPages != null, - child: surface, - ), + IgnorePointer(ignoring: !ready, child: surface), if (!ready && _showLoading && !snapshot.hasError) const PositionedDirectional( top: 8, @@ -1267,6 +1319,11 @@ final class _EpubViewportState extends State { ReaderPreferences preferences, { int? spine, }) => Row( + key: ValueKey(( + 'epub-spread', + spine ?? widget.engine.locator.spineIndex, + pages[index * columns].offset, + )), crossAxisAlignment: CrossAxisAlignment.stretch, children: [ for (var column = 0; column < columns; column++) diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index f56185a..2df20a0 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -46,6 +46,7 @@ final class PdfViewportConfiguration { required this.layoutMode, required this.onPageChanged, this.highlightLinks = true, + this.pageTurnAnimation = true, this.onPositionChanged, this.onVisiblePagesChanged, this.onContentReadyChanged, @@ -54,6 +55,7 @@ final class PdfViewportConfiguration { final int pageIndex; final bool facingPages; final bool highlightLinks; + final bool pageTurnAnimation; final Color backgroundColor; final Brightness brightness; final ReaderLayoutMode layoutMode; @@ -449,7 +451,18 @@ final class _PdfrxFacade extends PdfReaderTools } final PdfViewerController _controller = PdfViewerController(); - int _pageIndex = 0; + int _currentPageIndex = 0; + int get _pageIndex => _currentPageIndex; + set _pageIndex(int value) { + if (_currentPageIndex == value) return; + _currentPageIndex = value; + final pages = _pagesController; + if (pages != null && pages.hasClients) { + pages.jumpToPage(value ~/ _spreadStep); + } + notifyListeners(); + } + double _pageOffset = 0; final VoidCallback? _releaseDocument; PdfViewportConfiguration? _configuration; @@ -461,6 +474,15 @@ final class _PdfrxFacade extends PdfReaderTools DateTime? _lastWheelTurn; final _swipe = ReaderSwipeTracker(); bool _textSelected = false; + PageController? _pagesController; + GlobalKey _viewerKey = GlobalKey(); + PdfDocument? _previewDocument; + PdfPageLayout? _previewLayout; + Drag? _pageDrag; + bool _pagingEnabled = false; + final Set _pagePointers = {}; + bool _multiTouch = false; + int get _spreadStep => _configuration?.facingPages == true ? 2 : 1; @override final int pageCount; @@ -473,6 +495,10 @@ final class _PdfrxFacade extends PdfReaderTools final previous = _captureView(); _pageIndex = pageIndex; _pageOffset = pageOffset; + final pages = _pagesController; + if (pages != null && pages.hasClients) { + pages.jumpToPage(pageIndex ~/ _spreadStep); + } if (_controller.isReady && !_restoring) { _savedView = null; _restoring = true; @@ -546,7 +572,7 @@ final class _PdfrxFacade extends PdfReaderTools } } - void _turnSpread(int direction) { + Future _turnSpread(int direction) async { final config = _configuration; if (_disposed || _restoring || config == null || !_controller.isReady) { return; @@ -554,12 +580,71 @@ final class _PdfrxFacade extends PdfReaderTools final step = config.facingPages ? 2 : 1; final target = (_pageIndex ~/ step) * step + direction * step; if (target < 0 || target >= pageCount) return; - unawaited( - showPage(target, 0).then((_) { - if (_disposed) return; - config.onPositionChanged?.call(target, 0); - if (config.onPositionChanged == null) config.onPageChanged(target); - }), + await showPage(target, 0); + if (_disposed) return; + config.onPositionChanged?.call(target, 0); + if (config.onPositionChanged == null) config.onPageChanged(target); + } + + Widget _spreadPreview(BuildContext context, int index, Size size) { + final document = _previewDocument; + final layout = _previewLayout; + if (document == null || layout == null) return const SizedBox.expand(); + final config = _configuration!; + final step = config.facingPages ? 2 : 1; + final spread = pdfSpreadRect(layout, index, config.facingPages); + final scale = switch (_fitMode) { + PdfFitMode.custom => _controller.currentZoom, + PdfFitMode.width => size.width / spread.width, + _ => min(size.width / spread.width, size.height / spread.height), + }; + final params = buildPdfViewerParams( + config, + searchPainter: _searcher.pageTextMatchPaintCallback, + highlights: + ReaderInteractionScope.maybeOf(context)?.highlights ?? const [], + ); + + return ColoredBox( + color: params.backgroundColor, + child: Center( + child: SizedBox( + width: spread.width * scale, + height: spread.height * scale, + child: Stack( + children: [ + for ( + var page = index; + page < min(index + step, pageCount); + page++ + ) + Positioned.fromRect( + rect: Rect.fromLTWH( + (layout.pageLayouts[page].left - spread.left) * scale, + (layout.pageLayouts[page].top - spread.top) * scale, + layout.pageLayouts[page].width * scale, + layout.pageLayouts[page].height * scale, + ), + child: PdfPageView( + document: document, + pageNumber: page + 1, + decorationBuilder: (context, size, page, image) => + ColoredBox( + color: Colors.white, + child: CustomPaint( + foregroundPainter: _PdfPreviewPainter( + page, + params.pagePaintCallbacks ?? const [], + ), + child: image ?? const SizedBox.expand(), + ), + ), + ), + ), + ], + ), + ), + ), ); } @@ -625,25 +710,50 @@ final class _PdfrxFacade extends PdfReaderTools : PdfFitMode.width; } _configuration = configuration; - return LayoutBuilder( - builder: (context, constraints) { - final size = Size(constraints.maxWidth, constraints.maxHeight); - final key = (configuration.layoutMode, configuration.facingPages, size); - if (_viewKey != key) { - _viewKey = key; - _viewerRevision++; - _restoring = true; + return ListenableBuilder( + listenable: this, + builder: (context, _) => LayoutBuilder( + builder: (context, constraints) { + final size = Size(constraints.maxWidth, constraints.maxHeight); + final key = ( + configuration.layoutMode, + configuration.facingPages, + size, + ); + if (_viewKey != key) { + _viewKey = key; + _previewLayout = null; + _viewerKey = GlobalKey(); + final previous = _pagesController; + _pagesController = + configuration.layoutMode == ReaderLayoutMode.paginated + ? PageController( + initialPage: _pageIndex ~/ _spreadStep, + keepPage: false, + ) + : null; + WidgetsBinding.instance.addPostFrameCallback( + (_) => previous?.dispose(), + ); + _viewerRevision++; + _restoring = true; + final revision = _viewerRevision; + WidgetsBinding.instance.addPostFrameCallback((_) { + if (!_disposed && _restoring && revision == _viewerRevision) { + _configuration?.onContentReadyChanged?.call(false); + } + }); + } final revision = _viewerRevision; - WidgetsBinding.instance.addPostFrameCallback((_) { - if (!_disposed && _restoring && revision == _viewerRevision) { - _configuration?.onContentReadyChanged?.call(false); - } - }); - } - final revision = _viewerRevision; - return applyPdfBrightness( - preserveColors ? Brightness.light : configuration.brightness, - Listener( + _pagingEnabled = + configuration.layoutMode == ReaderLayoutMode.paginated && + configuration.pageTurnAnimation && + !MediaQuery.disableAnimationsOf(context) && + !_restoring && + _atFit && + !_textSelected && + !_multiTouch; + final viewer = Listener( onPointerSignal: (event) { if (configuration.layoutMode != ReaderLayoutMode.paginated || event is! PointerScrollEvent || @@ -687,6 +797,9 @@ final class _PdfrxFacade extends PdfReaderTools }, onPointerCancel: (event) { _swipe.cancel(event); + _pageDrag?.cancel(); + _pageDrag = null; + _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); _cancelLinkTap(event); }, onPointerUp: (event) { @@ -694,6 +807,8 @@ final class _PdfrxFacade extends PdfReaderTools final offset = _swipe.end(event); if (configuration.layoutMode == ReaderLayoutMode.paginated && + (!configuration.pageTurnAnimation || + MediaQuery.disableAnimationsOf(context)) && offset != null && !_restoring && _atFit && @@ -742,12 +857,15 @@ final class _PdfrxFacade extends PdfReaderTools saveSelection: _saveSelection, child: PdfViewer( _documentRef, - key: ValueKey(key), + key: _viewerKey, controller: _controller, initialPageNumber: _pageIndex + 1, params: buildPdfViewerParams( configuration, viewportSize: size, + onInteractionStart: _startPageDrag, + onInteractionUpdate: _updatePageDrag, + onInteractionEnd: _endPageDrag, viewerController: _controller, searchPainter: _searcher.pageTextMatchPaintCallback, viewerOverlayBuilder: (_, _, handleLinkTap) { @@ -824,6 +942,8 @@ final class _PdfrxFacade extends PdfReaderTools currentPageIndex: () => _pageIndex, onViewerReady: (_, _) async { if (_disposed || revision != _viewerRevision) return; + _previewDocument = _controller.document; + _previewLayout = _controller.layout; try { await _restorePage(); } finally { @@ -838,12 +958,128 @@ final class _PdfrxFacade extends PdfReaderTools ), ), ), - ), - ); - }, + ); + final pages = _pagesController; + return applyPdfBrightness( + preserveColors ? Brightness.light : configuration.brightness, + pages == null + ? viewer + : Listener( + onPointerDown: _pagePointerDown, + onPointerUp: _pagePointerEnded, + onPointerCancel: _pagePointerEnded, + child: NotificationListener( + onNotification: (notification) { + if (notification.depth == 0) { + scheduleMicrotask(_settlePage); + } + return false; + }, + child: PageView.builder( + key: ValueKey(pages), + controller: pages, + allowImplicitScrolling: true, + physics: _pagingEnabled + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + itemCount: (pageCount / _spreadStep).ceil(), + itemBuilder: (context, index) => SizedBox.expand( + key: ValueKey(('pdf-spread', index)), + child: index == _pageIndex ~/ _spreadStep + ? viewer + : _spreadPreview( + context, + index * _spreadStep, + size, + ), + ), + ), + ), + ), + ); + }, + ), ); } + void _pagePointerDown(PointerDownEvent event) { + _pagePointers.add(event.pointer); + if (_pagePointers.length > 1 && !_multiTouch) { + _multiTouch = true; + _pageDrag?.cancel(); + _pageDrag = null; + _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); + notifyListeners(); + } + } + + void _pagePointerEnded(PointerEvent event) { + _pagePointers.remove(event.pointer); + if (_pagePointers.isEmpty && _multiTouch) { + _multiTouch = false; + notifyListeners(); + } + } + + void _startPageDrag(ScaleStartDetails details) { + final pages = _pagesController; + if (!_pagingEnabled || + pages == null || + !pages.hasClients || + details.pointerCount != 1) { + return; + } + _pageDrag = pages.position.drag( + DragStartDetails(globalPosition: details.focalPoint), + () => _pageDrag = null, + ); + } + + void _updatePageDrag(ScaleUpdateDetails details) { + final drag = _pageDrag; + if (drag == null) return; + if (details.pointerCount != 1 || (details.scale - 1).abs() > .001) { + drag.cancel(); + _pageDrag = null; + _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); + return; + } + drag.update( + DragUpdateDetails( + globalPosition: details.focalPoint, + delta: Offset(details.focalPointDelta.dx, 0), + primaryDelta: details.focalPointDelta.dx, + ), + ); + } + + void _endPageDrag(ScaleEndDetails details) { + final drag = _pageDrag; + _pageDrag = null; + drag?.end( + DragEndDetails( + velocity: Velocity( + pixelsPerSecond: Offset(details.velocity.pixelsPerSecond.dx, 0), + ), + primaryVelocity: details.velocity.pixelsPerSecond.dx, + ), + ); + } + + void _settlePage() { + final pages = _pagesController; + if (_disposed || + _restoring || + pages == null || + !pages.hasClients || + pages.position.isScrollingNotifier.value) { + return; + } + final target = pages.page!.round() * _spreadStep; + if (target == (_pageIndex ~/ _spreadStep) * _spreadStep) return; + unawaited(showPage(target, 0)); + } + int _centerPageIndex() { final center = _controller.visibleRect.center; final pages = _controller.layout.pageLayouts; @@ -908,6 +1144,8 @@ final class _PdfrxFacade extends PdfReaderTools _saveTimer?.cancel(); if (_savedView != null) onViewChanged?.call(_savedView!); _disposed = true; + _pageDrag?.cancel(); + _pagesController?.dispose(); _searcher.dispose(); _controller.removeListener(_positionChanged); _releaseDocument?.call(); @@ -960,6 +1198,23 @@ ReaderHighlightTarget? pdfHighlightAt( return null; } +final class _PdfPreviewPainter extends CustomPainter { + const _PdfPreviewPainter(this.page, this.painters); + + final PdfPage page; + final List painters; + + @override + void paint(Canvas canvas, Size size) { + for (final painter in painters) { + painter(canvas, Offset.zero & size, page); + } + } + + @override + bool shouldRepaint(_PdfPreviewPainter oldDelegate) => true; +} + PdfViewerParams buildPdfViewerParams( PdfViewportConfiguration configuration, { PdfViewerController? viewerController, @@ -974,11 +1229,17 @@ PdfViewerParams buildPdfViewerParams( ValueChanged? onLink, PdfViewerOverlaysBuilder? viewerOverlayBuilder, PdfViewerGeneralTapHandler? onGeneralTap, + GestureScaleStartCallback? onInteractionStart, + GestureScaleUpdateCallback? onInteractionUpdate, + GestureScaleEndCallback? onInteractionEnd, }) { final paginated = configuration.layoutMode == ReaderLayoutMode.paginated; final handles = PdfSelectionHandles(viewerController); return PdfViewerParams( pageDropShadow: null, + onInteractionStart: onInteractionStart, + onInteractionUpdate: onInteractionUpdate, + onInteractionEnd: onInteractionEnd, viewerOverlayBuilder: viewerOverlayBuilder, onGeneralTap: onGeneralTap, customizeContextMenuItems: customizeContextMenuItems, diff --git a/lib/src/engine/pdf/pdf_reader_engine.dart b/lib/src/engine/pdf/pdf_reader_engine.dart index 5ab631a..64dd16b 100644 --- a/lib/src/engine/pdf/pdf_reader_engine.dart +++ b/lib/src/engine/pdf/pdf_reader_engine.dart @@ -431,6 +431,7 @@ final class PdfReaderEngine extends ReaderEngine { brightness: _preferences.brightness, layoutMode: _preferences.layoutMode, highlightLinks: _preferences.highlightLinks, + pageTurnAnimation: _preferences.pageTurnAnimation, onPageChanged: _visiblePageChanged, onPositionChanged: _visiblePositionChanged, onVisiblePagesChanged: _visiblePagesChanged, diff --git a/test/engine/epub_reader_engine_test.dart b/test/engine/epub_reader_engine_test.dart index a970042..60e6ede 100644 --- a/test/engine/epub_reader_engine_test.dart +++ b/test/engine/epub_reader_engine_test.dart @@ -614,7 +614,8 @@ void main() { await tester.pumpAndSettle(); var pageView = tester.widget(find.byType(PageView)); - final pageCount = pageView.childrenDelegate.estimatedChildCount!; + // The trailing item is the first page of the following chapter. + final pageCount = pageView.childrenDelegate.estimatedChildCount! - 1; expect(pageView.controller, isNotNull); expect( pageView.controller!.page, diff --git a/test/presentation/epub_page_turn_test.dart b/test/presentation/epub_page_turn_test.dart index 5133d35..7c737b8 100644 --- a/test/presentation/epub_page_turn_test.dart +++ b/test/presentation/epub_page_turn_test.dart @@ -6,6 +6,91 @@ import '../support/in_process_epub_worker.dart'; import '../support/synthetic_epub.dart'; void main() { + for (final facing in [false, true]) { + testWidgets( + 'chapter edges follow the finger in both directions, facing $facing', + (tester) async { + await tester.binding.setSurfaceSize(Size(facing ? 1000 : 600, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'drag-boundaries', + format: ReaderFormat.epub, + loadBytes: () async => + syntheticEpub(firstChapterBody: '

First page.

'), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + + Finder spread(int spine) => + find.byKey(ValueKey(('epub-spread', spine, 0))); + for (final direction in [1, -1]) { + final viewport = find.byType(PageView); + final before = engine.snapshot.locator; + final bounds = tester.getRect(viewport); + final outgoing = spread(direction > 0 ? 0 : 1); + final incoming = spread(direction > 0 ? 1 : 0); + final gesture = await tester.startGesture(bounds.center); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + for (final distance in [80.0, 90.0, 70.0]) { + final oldLeft = tester.getTopLeft(outgoing).dx; + await gesture.moveBy(Offset(-distance * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + final current = tester.getRect(outgoing); + final next = tester.getRect(incoming); + expect( + tester.getRect(viewport), + bounds, + reason: 'The viewport itself must never translate', + ); + expect(current.left, closeTo(oldLeft - distance * direction, 1)); + expect( + direction > 0 ? current.right : next.right, + closeTo(direction > 0 ? next.left : current.left, .01), + reason: + 'Adjacent pages share one edge throughout the drag, with no overlap', + ); + expect(current.width, bounds.width); + expect(next.width, bounds.width); + expect(engine.snapshot.locator, before); + } + await gesture.moveBy(Offset(240.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + await gesture.up(); + await tester.pumpAndSettle(); + expect(tester.getRect(outgoing), bounds); + expect(engine.snapshot.locator, before); + + final turn = await tester.startGesture(bounds.center); + await turn.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await turn.moveBy(Offset(-bounds.width * .65 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect(engine.snapshot.locator, before); + await turn.up(); + await tester.pump(); + await tester.pump(const Duration(milliseconds: 16)); + expect(engine.snapshot.locator, before); + await tester.pumpAndSettle(); + expect( + (engine.snapshot.locator as EpubReaderLocator).spineIndex, + direction > 0 ? 1 : 0, + ); + expect(tester.getRect(incoming), bounds); + } + + expect(tester.takeException(), isNull); + }, + ); + } + testWidgets('instant turns do not slide on commands or touch drags', ( tester, ) async { @@ -216,7 +301,7 @@ void main() { ); expect(engine.locator.spineIndex, 1); expect(engine.locator.textOffset, greaterThan(0)); - expect(tester.widget(find.byType(PageView)).controller!.page, 2); + expect(tester.widget(find.byType(PageView)).controller!.page, 3); expect(tester.takeException(), isNull); }); diff --git a/test/presentation/epub_selection_test.dart b/test/presentation/epub_selection_test.dart index e1615e1..c28e9ae 100644 --- a/test/presentation/epub_selection_test.dart +++ b/test/presentation/epub_selection_test.dart @@ -370,7 +370,11 @@ void main() { ), ); await tester.pumpAndSettle(); - await tester.dragFrom(const Offset(500, 400), const Offset(-200, 0)); + await tester.flingFrom( + const Offset(500, 400), + const Offset(-200, 0), + 1000, + ); await tester.pumpAndSettle(); expect(engine.locator.spineIndex, 1); await tester.pumpWidget(const SizedBox.shrink()); diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index c67c3c8..a838682 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -74,6 +74,125 @@ Future _ready(WidgetTester tester, PdfReaderTools tools) async { } void main() { + for (final animation in [true, false]) { + for (final facing in [false, true]) { + testWidgets( + 'PDF touch turns track the finger, animation $animation, facing $facing', + (tester) async { + await tester.binding.setSurfaceSize(const Size(800, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(_document); + await tester.runAsync(initializePdfiumForTest); + final facade = await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'drag-pdf'), + ); + final tools = facade! as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + var page = 0; + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: facing, + pageTurnAnimation: animation, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (value) => page = value, + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + final viewport = find.byType(PageView); + final bounds = tester.getRect(viewport); + Finder spread(int index) => + find.byKey(ValueKey(('pdf-spread', index))); + for (final direction in [1, -1]) { + final oldPage = page; + final outgoing = spread(direction > 0 ? 0 : 1); + final incoming = spread(direction > 0 ? 1 : 0); + final gesture = await tester.startGesture(bounds.center); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + for (final distance in [80.0, 90.0, 70.0]) { + final oldLeft = tester.getTopLeft(outgoing).dx; + await gesture.moveBy(Offset(-distance * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + final current = tester.getRect(outgoing); + expect(tester.getRect(viewport), bounds); + if (animation) { + final next = tester.getRect(incoming); + expect( + current.left, + closeTo(oldLeft - distance * direction, 1), + ); + expect( + direction > 0 ? current.right : next.right, + closeTo(direction > 0 ? next.left : current.left, .01), + reason: 'PDF spreads must remain adjacent, never overlap', + ); + } else { + expect(current, bounds); + } + expect(page, oldPage); + } + if (animation) { + await gesture.cancel(); + await tester.pumpAndSettle(); + expect(page, oldPage); + expect(tester.getRect(outgoing), bounds); + final turn = await tester.startGesture(bounds.center); + await turn.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await turn.moveBy(Offset(-bounds.width * .65 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect(page, oldPage); + await turn.up(); + } else { + await gesture.up(); + } + await tester.pumpAndSettle(); + expect(page, direction > 0 ? (facing ? 2 : 1) : 0); + expect(tester.getRect(incoming), bounds); + } + if (animation) { + final fittedZoom = tools.zoom; + final left = await tester.startGesture( + bounds.center - const Offset(60, 0), + pointer: 41, + ); + final right = await tester.startGesture( + bounds.center + const Offset(60, 0), + pointer: 42, + ); + await tester.pump(); + await left.moveBy(const Offset(-30, 0)); + await right.moveBy(const Offset(30, 0)); + await tester.pump(const Duration(milliseconds: 30)); + await left.moveBy(const Offset(-30, 0)); + await right.moveBy(const Offset(30, 0)); + await tester.pump(const Duration(milliseconds: 30)); + expect( + tools.zoom, + greaterThan(fittedZoom), + reason: 'Pinching at fit size must zoom instead of paging', + ); + await left.up(); + await right.up(); + await tester.pumpAndSettle(); + expect(page, 0); + } + + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + } + for (final explicit in [false, true]) { testWidgets( explicit From 6dbff6f7314a636e4bbdae5ac1e3413a7ee43a3c Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 17:33:18 +0200 Subject: [PATCH 02/19] fix: retain PDF rendering through swipe settlement --- docs/ARCHITECTURE.md | 4 + lib/src/engine/pdf/pdf_facade.dart | 639 ++++++++++++++------------ test/presentation/pdf_tools_test.dart | 311 +++++++++---- 3 files changed, 587 insertions(+), 367 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 007f574..88f76b5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -70,6 +70,10 @@ view center survive viewport/layout changes; fit modes adapt to the available space. Paginated slots isolate spreads even when zoomed out. pdfrx owns rendering, selection, and bounded text search. `PdfReaderTools` exposes zoom, fit, page entry, search, and a bounded return history to the shell without exposing PDFium types. +Each paginated spread retains its viewer and rendered images through a swipe and +settlement. Neighboring viewers mount lazily and release their resources when +evicted from the page cache. Search results belong to the document; navigation and +keyboard focus follow the active spread. The host persists the synchronized locator separately from `PdfViewState`, which is device-local view configuration. `ReaderDocument.initialPdfView` and diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index 2df20a0..5e4f81f 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -197,8 +197,8 @@ final class _PdfrxFacade extends PdfReaderTools _savedView = initialView, _preferInitialLocator = preferInitialLocator, _fitMode = initialView?.fitMode { - _controller.addListener(_positionChanged); - _searcher = PdfTextSearchSession(_controller)..addListener(_searchChanged); + _searcher = _PdfSearchSession(() => _controller) + ..addListener(_searchChanged); } final PdfDocumentRef _documentRef; @@ -285,13 +285,17 @@ final class _PdfrxFacade extends PdfReaderTools if (!isReady || index < 0 || index >= _searcher.matches.length) return; final previous = _captureView(); final match = _searcher.matches[index]; - _pageIndex = match.pageNumber - 1; + if (!await _activatePage(match.pageNumber - 1)) return; _fitMode = PdfFitMode.custom; final rect = _controller.calcRectForRectInsidePage( pageNumber: match.pageNumber, rect: match.bounds, ); - await _controller.setZoom(rect.center, zoom, duration: Duration.zero); + await _controller.setZoom( + rect.center, + previous?.zoom ?? zoom, + duration: Duration.zero, + ); await _searcher.goToMatchOfIndex(index); _rememberLocation(previous); _positionChanged(); @@ -321,7 +325,7 @@ final class _PdfrxFacade extends PdfReaderTools final target = source.last; _savedView = target; _fitMode = target.fitMode; - _pageIndex = target.pageIndex; + if (!await _activatePage(target.pageIndex)) return; await _restorePage(restoreLocation: true); source.removeLast(); destination.add(current); @@ -373,7 +377,7 @@ final class _PdfrxFacade extends PdfReaderTools return; } final previous = _captureView(); - _pageIndex = destination.pageNumber - 1; + if (!await _activatePage(destination.pageNumber - 1)) return; _fitMode = PdfFitMode.custom; await _controller.goToDest(destination, duration: Duration.zero); _rememberLocation(previous); @@ -383,7 +387,7 @@ final class _PdfrxFacade extends PdfReaderTools } } - PdfViewerHandleLinkTap? _handleLinkTap; + PdfViewerHandleLinkTap? get _handleLinkTap => _activeSpread.handleLinkTap; final Set _linkPointers = {}; PointerDownEvent? _linkStart; bool _linkTapHandled = false; @@ -450,7 +454,40 @@ final class _PdfrxFacade extends PdfReaderTools ); } - final PdfViewerController _controller = PdfViewerController(); + final Map _spreads = {}; + PdfViewerController get _controller => _activeSpread.controller; + int get _spreadIndex => _configuration?.layoutMode == ReaderLayoutMode.scroll + ? 0 + : _pageIndex ~/ _spreadStep; + _PdfSpread get _activeSpread => _spreadFor(_spreadIndex); + + _PdfSpread _spreadFor(int index) => _spreads.putIfAbsent(index, () { + final spread = _PdfSpread(); + spread.controller.addListener(() { + if (!_disposed && identical(spread, _activeSpread)) _positionChanged(); + }); + return spread; + }); + + Future _activatePage(int index) async { + final hadFocus = + _controller.isReady && (_controller.focusNode?.hasFocus ?? false); + _pageIndex = index; + if (_viewKey == null) return !_disposed; + final revision = _viewerRevision; + await _activeSpread.ready.future; + + if (_disposed || revision != _viewerRevision || _pageIndex != index) { + return false; + } + + if (hadFocus && _controller.isReady) { + _controller.requestFocus(); + } + + return true; + } + int _currentPageIndex = 0; int get _pageIndex => _currentPageIndex; set _pageIndex(int value) { @@ -475,9 +512,6 @@ final class _PdfrxFacade extends PdfReaderTools final _swipe = ReaderSwipeTracker(); bool _textSelected = false; PageController? _pagesController; - GlobalKey _viewerKey = GlobalKey(); - PdfDocument? _previewDocument; - PdfPageLayout? _previewLayout; Drag? _pageDrag; bool _pagingEnabled = false; final Set _pagePointers = {}; @@ -493,8 +527,8 @@ final class _PdfrxFacade extends PdfReaderTools @override Future showPage(int pageIndex, double pageOffset) async { final previous = _captureView(); - _pageIndex = pageIndex; _pageOffset = pageOffset; + if (!await _activatePage(pageIndex)) return; final pages = _pagesController; if (pages != null && pages.hasClients) { pages.jumpToPage(pageIndex ~/ _spreadStep); @@ -503,7 +537,7 @@ final class _PdfrxFacade extends PdfReaderTools _savedView = null; _restoring = true; try { - await _restorePage(); + await _restorePage(zoomOverride: previous?.zoom); } finally { _restoring = false; } @@ -532,13 +566,20 @@ final class _PdfrxFacade extends PdfReaderTools PdfFitMode.custom => _savedView?.zoom ?? zoom, }; - Future _restorePage({bool restoreLocation = false}) async { + Future _restorePage({ + bool restoreLocation = false, + double? zoomOverride, + }) async { final config = _configuration; if (config == null) return; _fitMode ??= config.layoutMode == ReaderLayoutMode.paginated ? PdfFitMode.page : PdfFitMode.width; - final scale = _zoomFor(_fitMode!).clamp(.1, 8.0); + final scale = + (_fitMode == PdfFitMode.custom && zoomOverride != null + ? zoomOverride + : _zoomFor(_fitMode!)) + .clamp(.1, 8.0); final page = _controller.layout.pageLayouts[_pageIndex]; final saved = _savedView; final Offset center; @@ -586,66 +627,30 @@ final class _PdfrxFacade extends PdfReaderTools if (config.onPositionChanged == null) config.onPageChanged(target); } - Widget _spreadPreview(BuildContext context, int index, Size size) { - final document = _previewDocument; - final layout = _previewLayout; - if (document == null || layout == null) return const SizedBox.expand(); - final config = _configuration!; - final step = config.facingPages ? 2 : 1; - final spread = pdfSpreadRect(layout, index, config.facingPages); + Future _prepareSpread( + _PdfSpread spread, + int firstPage, + Size size, + ) async { + final controller = spread.controller; + final rect = pdfSpreadRect( + controller.layout, + firstPage, + _configuration!.facingPages, + ); final scale = switch (_fitMode) { - PdfFitMode.custom => _controller.currentZoom, - PdfFitMode.width => size.width / spread.width, - _ => min(size.width / spread.width, size.height / spread.height), + PdfFitMode.custom => zoom, + PdfFitMode.width => size.width / rect.width, + _ => min(size.width / rect.width, size.height / rect.height), }; - final params = buildPdfViewerParams( - config, - searchPainter: _searcher.pageTextMatchPaintCallback, - highlights: - ReaderInteractionScope.maybeOf(context)?.highlights ?? const [], - ); + final center = _fitMode == PdfFitMode.page + ? rect.center + : Offset(rect.center.dx, rect.top + size.height / (2 * scale)); + final matrix = controller.calcMatrixFor(center, zoom: scale); - return ColoredBox( - color: params.backgroundColor, - child: Center( - child: SizedBox( - width: spread.width * scale, - height: spread.height * scale, - child: Stack( - children: [ - for ( - var page = index; - page < min(index + step, pageCount); - page++ - ) - Positioned.fromRect( - rect: Rect.fromLTWH( - (layout.pageLayouts[page].left - spread.left) * scale, - (layout.pageLayouts[page].top - spread.top) * scale, - layout.pageLayouts[page].width * scale, - layout.pageLayouts[page].height * scale, - ), - child: PdfPageView( - document: document, - pageNumber: page + 1, - decorationBuilder: (context, size, page, image) => - ColoredBox( - color: Colors.white, - child: CustomPaint( - foregroundPainter: _PdfPreviewPainter( - page, - params.pagePaintCallbacks ?? const [], - ), - child: image ?? const SizedBox.expand(), - ), - ), - ), - ), - ], - ), - ), - ), - ); + if (controller.value != matrix) { + await controller.goTo(matrix, duration: Duration.zero); + } } Future _saveSelection( @@ -722,8 +727,10 @@ final class _PdfrxFacade extends PdfReaderTools ); if (_viewKey != key) { _viewKey = key; - _previewLayout = null; - _viewerKey = GlobalKey(); + for (final spread in _spreads.values) { + spread.finish(); + } + _spreads.clear(); final previous = _pagesController; _pagesController = configuration.layoutMode == ReaderLayoutMode.paginated @@ -753,217 +760,260 @@ final class _PdfrxFacade extends PdfReaderTools _atFit && !_textSelected && !_multiTouch; - final viewer = Listener( - onPointerSignal: (event) { - if (configuration.layoutMode != ReaderLayoutMode.paginated || - event is! PointerScrollEvent || - _restoring || - !_atFit || - HardwareKeyboard.instance.isControlPressed || - HardwareKeyboard.instance.isMetaPressed) { - return; - } - final delta = - event.scrollDelta.dy.abs() >= event.scrollDelta.dx.abs() - ? event.scrollDelta.dy - : event.scrollDelta.dx; - if (delta.abs() < 10) return; - final now = DateTime.now(); - if (_lastWheelTurn != null && - now.difference(_lastWheelTurn!).inMilliseconds < 250) { - return; - } - _lastWheelTurn = now; - // Let pdfrx finish handling the wheel before snapping to the next row. + Widget buildViewer(int index) { + final spread = _spreadFor(index); + final controller = spread.controller; + final paginated = + configuration.layoutMode == ReaderLayoutMode.paginated; + final firstPage = paginated ? index * _spreadStep : _pageIndex; + bool active() => identical(spread, _activeSpread); + + if (!active() && spread.ready.isCompleted) { WidgetsBinding.instance.addPostFrameCallback((_) { - if (!_disposed && revision == _viewerRevision) { + if (!_disposed && + revision == _viewerRevision && + identical(_spreads[index], spread) && + !active()) { + unawaited(_prepareSpread(spread, firstPage, size)); + } + }); + } + + final viewer = Listener( + onPointerSignal: (event) { + if (configuration.layoutMode != ReaderLayoutMode.paginated || + event is! PointerScrollEvent || + _restoring || + !_atFit || + HardwareKeyboard.instance.isControlPressed || + HardwareKeyboard.instance.isMetaPressed) { + return; + } + final delta = + event.scrollDelta.dy.abs() >= event.scrollDelta.dx.abs() + ? event.scrollDelta.dy + : event.scrollDelta.dx; + if (delta.abs() < 10) return; + final now = DateTime.now(); + if (_lastWheelTurn != null && + now.difference(_lastWheelTurn!).inMilliseconds < 250) { + return; + } + _lastWheelTurn = now; + // Let pdfrx finish handling the wheel before snapping to the next row. + WidgetsBinding.instance.addPostFrameCallback((_) { + if (!_disposed && revision == _viewerRevision) { + final turn = ReaderInteractionScope.maybeOf( + context, + )?.onTurn; + if (turn != null) { + turn(delta > 0 ? 1 : -1); + } else { + _turnSpread(delta > 0 ? 1 : -1); + } + } + }); + WidgetsBinding.instance.scheduleFrame(); + }, + onPointerDown: (event) { + _swipe.start(event); + _startLinkTap(event); + }, + onPointerMove: (event) { + _swipe.update(event); + _moveLinkTap(event); + }, + onPointerCancel: (event) { + _swipe.cancel(event); + _pageDrag?.cancel(); + _pageDrag = null; + _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); + _cancelLinkTap(event); + }, + onPointerUp: (event) { + _endLinkTap(event); + final offset = _swipe.end(event); + + if (configuration.layoutMode == ReaderLayoutMode.paginated && + (!configuration.pageTurnAnimation || + MediaQuery.disableAnimationsOf(context)) && + offset != null && + !_restoring && + _atFit && + offset.dx.abs() > 70 && + offset.dx.abs() > offset.dy.abs()) { + final direction = offset.dx < 0 ? 1 : -1; final turn = ReaderInteractionScope.maybeOf(context)?.onTurn; + if (turn != null) { - turn(delta > 0 ? 1 : -1); + turn(direction); } else { - _turnSpread(delta > 0 ? 1 : -1); + _turnSpread(direction); } } - }); - WidgetsBinding.instance.scheduleFrame(); - }, - onPointerDown: (event) { - _swipe.start(event); - _startLinkTap(event); - }, - onPointerMove: (event) { - _swipe.update(event); - _moveLinkTap(event); - }, - onPointerCancel: (event) { - _swipe.cancel(event); - _pageDrag?.cancel(); - _pageDrag = null; - _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); - _cancelLinkTap(event); - }, - onPointerUp: (event) { - _endLinkTap(event); - final offset = _swipe.end(event); - - if (configuration.layoutMode == ReaderLayoutMode.paginated && - (!configuration.pageTurnAnimation || - MediaQuery.disableAnimationsOf(context)) && - offset != null && - !_restoring && - _atFit && - offset.dx.abs() > 70 && - offset.dx.abs() > offset.dy.abs()) { - final direction = offset.dx < 0 ? 1 : -1; - final turn = ReaderInteractionScope.maybeOf(context)?.onTurn; - - if (turn != null) { - turn(direction); - } else { - _turnSpread(direction); - } - } - }, - child: ReaderHighlightInteraction( - isSelecting: () => _textSelected, - hitTest: (position) { - if (!_controller.isReady) return null; - final documentPosition = _controller.globalToDocument(position); - if (documentPosition == null) return null; - final target = pdfHighlightAt( - documentPosition, - _controller.layout.pageLayouts, - ReaderInteractionScope.maybeOf(context)?.highlights ?? - const [], - ); - if (target == null) return null; - final visible = target.bounds.intersect( - _controller.visibleRect, - ); - final topLeft = _controller.documentToGlobal(visible.topLeft); - final bottomRight = _controller.documentToGlobal( - visible.bottomRight, - ); - if (visible.isEmpty || topLeft == null || bottomRight == null) { - return null; - } - return ( - highlight: target.highlight, - bounds: Rect.fromPoints(topLeft, bottomRight), - ); }, - child: PdfSelectionToolbar( - controller: _controller, - saveSelection: _saveSelection, - child: PdfViewer( - _documentRef, - key: _viewerKey, - controller: _controller, - initialPageNumber: _pageIndex + 1, - params: buildPdfViewerParams( - configuration, - viewportSize: size, - onInteractionStart: _startPageDrag, - onInteractionUpdate: _updatePageDrag, - onInteractionEnd: _endPageDrag, - viewerController: _controller, - searchPainter: _searcher.pageTextMatchPaintCallback, - viewerOverlayBuilder: (_, _, handleLinkTap) { - _handleLinkTap = handleLinkTap; - return const []; - }, - onGeneralTap: (_, _, _) { - final handled = _linkTapHandled; - _linkTapHandled = false; - return handled; - }, - onLink: (link) { - // Consume the later classified tap after an immediate jump. - if (_linkTapHandled) { + child: ReaderHighlightInteraction( + isSelecting: () => _textSelected, + hitTest: (position) { + if (!controller.isReady) return null; + final documentPosition = controller.globalToDocument( + position, + ); + if (documentPosition == null) return null; + final target = pdfHighlightAt( + documentPosition, + controller.layout.pageLayouts, + ReaderInteractionScope.maybeOf(context)?.highlights ?? + const [], + ); + if (target == null) return null; + final visible = target.bounds.intersect( + controller.visibleRect, + ); + final topLeft = controller.documentToGlobal(visible.topLeft); + final bottomRight = controller.documentToGlobal( + visible.bottomRight, + ); + if (visible.isEmpty || + topLeft == null || + bottomRight == null) { + return null; + } + return ( + highlight: target.highlight, + bounds: Rect.fromPoints(topLeft, bottomRight), + ); + }, + child: PdfSelectionToolbar( + controller: controller, + saveSelection: _saveSelection, + child: PdfViewer( + _documentRef, + key: ValueKey((revision, index)), + controller: controller, + initialPageNumber: firstPage + 1, + params: buildPdfViewerParams( + configuration, + viewportSize: size, + onInteractionStart: _startPageDrag, + onInteractionUpdate: _updatePageDrag, + onInteractionEnd: _endPageDrag, + viewerController: controller, + searchPainter: _searcher.pageTextMatchPaintCallback, + viewerOverlayBuilder: (_, _, handleLinkTap) { + spread.handleLinkTap = handleLinkTap; + return const []; + }, + onGeneralTap: (_, _, _) { + final handled = _linkTapHandled; _linkTapHandled = false; - return; - } - - ReaderInteractionScope.maybeOf(context)?.suppressTap(); - unawaited( - _openLink(link).catchError((Object error) { - if (context.mounted) { - ScaffoldMessenger.maybeOf(context)?.showSnackBar( - const SnackBar( - content: Text('Could not open this link.'), + return handled; + }, + onLink: (link) { + // Consume the later classified tap after an immediate jump. + if (_linkTapHandled) { + _linkTapHandled = false; + return; + } + + ReaderInteractionScope.maybeOf(context)?.suppressTap(); + unawaited( + _openLink(link).catchError((Object error) { + if (context.mounted) { + ScaffoldMessenger.maybeOf(context)?.showSnackBar( + const SnackBar( + content: Text('Could not open this link.'), + ), + ); + } + }), + ); + }, + customizeContextMenuItems: (params, items) { + if (!params.textSelectionDelegate.hasSelectedText || + !params.textSelectionDelegate.isCopyAllowed) { + return; + } + + final interactions = ReaderInteractionScope.maybeOf( + context, + ); + + for (final entry in [ + ('Annotate', interactions?.onAnnotate), + ('Add note', interactions?.onNote), + ]) { + final action = entry.$2; + + if (action != null) { + items.add( + ContextMenuButtonItem( + label: entry.$1, + onPressed: () { + params.dismissContextMenu(); + _saveSelection( + params.textSelectionDelegate, + action, + ); + }, ), ); } - }), - ); - }, - customizeContextMenuItems: (params, items) { - if (!params.textSelectionDelegate.hasSelectedText || - !params.textSelectionDelegate.isCopyAllowed) { - return; - } - - final interactions = ReaderInteractionScope.maybeOf( - context, - ); - - for (final entry in [ - ('Annotate', interactions?.onAnnotate), - ('Add note', interactions?.onNote), - ]) { - final action = entry.$2; - - if (action != null) { - items.add( - ContextMenuButtonItem( - label: entry.$1, - onPressed: () { - params.dismissContextMenu(); - _saveSelection( - params.textSelectionDelegate, - action, - ); - }, - ), - ); } - } - }, - highlights: - ReaderInteractionScope.maybeOf(context)?.highlights ?? - const [], - onTextSelectionChange: (selection) { - _textSelected = selection.hasSelectedText; - _swipe.selectionChanged(selection.hasSelectedText); - ReaderInteractionScope.maybeOf( - context, - )?.onSelectionChanged(selection.hasSelectedText); - }, - currentPageIndex: () => _pageIndex, - onViewerReady: (_, _) async { - if (_disposed || revision != _viewerRevision) return; - _previewDocument = _controller.document; - _previewLayout = _controller.layout; - try { - await _restorePage(); - } finally { - if (!_disposed && revision == _viewerRevision) { - _restoring = false; - _positionChanged(); + }, + highlights: + ReaderInteractionScope.maybeOf(context)?.highlights ?? + const [], + onTextSelectionChange: (selection) { + if (!active()) return; + _textSelected = selection.hasSelectedText; + _swipe.selectionChanged(selection.hasSelectedText); + ReaderInteractionScope.maybeOf( + context, + )?.onSelectionChanged(selection.hasSelectedText); + }, + currentPageIndex: () => + paginated ? firstPage : _pageIndex, + onViewerReady: (_, _) async { + if (_disposed || revision != _viewerRevision) return; + if (active()) { + try { + await _restorePage(); + } finally { + if (!_disposed && revision == _viewerRevision) { + _restoring = false; + spread.finish(); + _positionChanged(); + } + } + } else { + await _prepareSpread(spread, firstPage, size); + spread.finish(); } - } - }, - onPageChanged: (_) => _positionChanged(), + }, + onPageChanged: (_) { + if (active()) _positionChanged(); + }, + ), ), ), ), - ), - ); + ); + return _PdfSpreadLifetime( + key: ValueKey((revision, index)), + onDispose: () { + spread.finish(); + if (identical(_spreads[index], spread)) _spreads.remove(index); + }, + child: IgnorePointer(ignoring: !active(), child: viewer), + ); + } + final pages = _pagesController; return applyPdfBrightness( preserveColors ? Brightness.light : configuration.brightness, pages == null - ? viewer + ? buildViewer(0) : Listener( onPointerDown: _pagePointerDown, onPointerUp: _pagePointerEnded, @@ -985,13 +1035,7 @@ final class _PdfrxFacade extends PdfReaderTools itemCount: (pageCount / _spreadStep).ceil(), itemBuilder: (context, index) => SizedBox.expand( key: ValueKey(('pdf-spread', index)), - child: index == _pageIndex ~/ _spreadStep - ? viewer - : _spreadPreview( - context, - index * _spreadStep, - size, - ), + child: buildViewer(index), ), ), ), @@ -1147,7 +1191,9 @@ final class _PdfrxFacade extends PdfReaderTools _pageDrag?.cancel(); _pagesController?.dispose(); _searcher.dispose(); - _controller.removeListener(_positionChanged); + for (final spread in _spreads.values) { + spread.finish(); + } _releaseDocument?.call(); _configuration = null; super.dispose(); @@ -1198,21 +1244,50 @@ ReaderHighlightTarget? pdfHighlightAt( return null; } -final class _PdfPreviewPainter extends CustomPainter { - const _PdfPreviewPainter(this.page, this.painters); +final class _PdfSpread { + final controller = PdfViewerController(); + final ready = Completer(); + PdfViewerHandleLinkTap? handleLinkTap; + + void finish() { + if (!ready.isCompleted) ready.complete(); + } +} - final PdfPage page; - final List painters; +// Search results belong to the document, while navigation follows the active spread. +final class _PdfSearchSession extends PdfTextSearchSession { + _PdfSearchSession(this.activeController) : super(PdfViewerController()); + final PdfViewerController Function() activeController; @override - void paint(Canvas canvas, Size size) { - for (final painter in painters) { - painter(canvas, Offset.zero & size, page); - } + PdfViewerController? get controller { + final current = activeController(); + return current.isReady ? current : null; + } +} + +final class _PdfSpreadLifetime extends StatefulWidget { + const _PdfSpreadLifetime({ + super.key, + required this.child, + required this.onDispose, + }); + final Widget child; + final VoidCallback onDispose; + + @override + State<_PdfSpreadLifetime> createState() => _PdfSpreadLifetimeState(); +} + +final class _PdfSpreadLifetimeState extends State<_PdfSpreadLifetime> { + @override + void dispose() { + widget.onDispose(); + super.dispose(); } @override - bool shouldRepaint(_PdfPreviewPainter oldDelegate) => true; + Widget build(BuildContext context) => widget.child; } PdfViewerParams buildPdfViewerParams( diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index a838682..1d0c05d 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -1,7 +1,9 @@ import 'dart:async'; +import 'dart:ui' as ui; import 'package:flutter/foundation.dart'; import 'package:flutter/material.dart'; +import 'package:flutter/rendering.dart'; import 'package:flutter/gestures.dart'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; @@ -73,7 +75,135 @@ Future _ready(WidgetTester tester, PdfReaderTools tools) async { expect(tools.isReady, isTrue); } +Future _navigate(WidgetTester tester, Future operation) async { + var completed = false; + final pending = operation.whenComplete(() => completed = true); + for (var attempt = 0; attempt < 100 && !completed; attempt++) { + await tester.pumpAndSettle(); + await tester.runAsync( + () => Future.delayed(const Duration(milliseconds: 20)), + ); + } + expect( + completed, + isTrue, + reason: 'PDF navigation must finish after the destination mounts', + ); + await pending; +} + void main() { + for (final initialZoom in [null, .5]) { + testWidgets('PDF page pixels survive settling at zoom $initialZoom', ( + tester, + ) async { + await tester.binding.setSurfaceSize(const Size(800, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final document = pw.Document(); + + for (final color in [ + const pdf.PdfColor(1, 0, 0), + const pdf.PdfColor(0, 0, 1), + ]) { + document.addPage( + pw.Page( + pageTheme: pw.PageTheme( + buildBackground: (_) => pw.FullPage( + ignoreMargins: true, + child: pw.Container(color: color), + ), + ), + build: (_) => pw.Text('Rendered page'), + ), + ); + } + + final bytes = await tester.runAsync(document.save); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'settling-pdf'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + final boundaryKey = GlobalKey(); + await tester.pumpWidget( + MaterialApp( + home: RepaintBoundary( + key: boundaryKey, + child: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), + ), + ), + ), + ); + await _ready(tester, tools); + if (initialZoom != null) { + await tools.setZoom(initialZoom); + await tester.pumpAndSettle(); + } + + Future> centerPixel() async { + final boundary = + boundaryKey.currentContext!.findRenderObject()! + as RenderRepaintBoundary; + return (await tester.runAsync(() async { + final image = await boundary.toImage(); + final data = (await image.toByteData( + format: ui.ImageByteFormat.rawRgba, + ))!; + final offset = + (image.width * (image.height ~/ 2) + image.width ~/ 2) * 4; + final pixel = data.buffer.asUint8List(offset, 3).toList(); + image.dispose(); + return pixel; + }))!; + } + + Future waitForPixel(List expected) async { + for (var attempt = 0; attempt < 100; attempt++) { + if (listEquals(await centerPixel(), expected)) return; + await tester.runAsync( + () => Future.delayed(const Duration(milliseconds: 20)), + ); + await tester.pump(const Duration(milliseconds: 20)); + } + expect(await centerPixel(), expected); + } + + await waitForPixel([255, 0, 0]); + for (final direction in [1, -1]) { + final expected = direction > 0 ? [0, 0, 255] : [255, 0, 0]; + final gesture = await tester.startGesture(const Offset(400, 300)); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await gesture.moveBy(Offset(-720.0 * direction, 0)); + await tester.pump(); + await waitForPixel(expected); + await gesture.up(); + + for (var frame = 0; frame < 90; frame++) { + await tester.pump(const Duration(milliseconds: 16)); + expect( + await centerPixel(), + expected, + reason: 'direction $direction, settling frame $frame', + ); + } + + expect(tools.pageNumber, direction > 0 ? 2 : 1); + if (initialZoom != null) expect(tools.zoom, closeTo(initialZoom, .001)); + } + await tester.pumpWidget(const SizedBox.shrink()); + }); + } + for (final animation in [true, false]) { for (final facing in [false, true]) { testWidgets( @@ -112,6 +242,7 @@ void main() { find.byKey(ValueKey(('pdf-spread', index))); for (final direction in [1, -1]) { final oldPage = page; + State? incomingState; final outgoing = spread(direction > 0 ? 0 : 1); final incoming = spread(direction > 0 ? 1 : 0); final gesture = await tester.startGesture(bounds.center); @@ -150,6 +281,9 @@ void main() { await turn.moveBy(Offset(-bounds.width * .65 * direction, 0)); await tester.pump(const Duration(milliseconds: 16)); expect(page, oldPage); + incomingState = tester.state( + find.descendant(of: incoming, matching: find.byType(PdfViewer)), + ); await turn.up(); } else { await gesture.up(); @@ -157,6 +291,17 @@ void main() { await tester.pumpAndSettle(); expect(page, direction > 0 ? (facing ? 2 : 1) : 0); expect(tester.getRect(incoming), bounds); + if (incomingState != null) { + expect( + tester.state( + find.descendant( + of: incoming, + matching: find.byType(PdfViewer), + ), + ), + same(incomingState), + ); + } } if (animation) { final fittedZoom = tools.zoom; @@ -250,20 +395,19 @@ void main() { } await _ready(tester, controller.pdfTools!); - final viewer = tester - .widget(find.byType(PdfViewer)) - .controller!; - final page = viewer.layout.pageLayouts[1]; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; + final page = viewer().layout.pageLayouts[1]; expect(controller.pdfTools!.zoom, closeTo(1.8, .001)); expect((controller.snapshot.locator as PdfReaderLocator).pageIndex, 1); if (explicit) { expect( - (viewer.visibleRect.top - page.top) / page.height, + (viewer().visibleRect.top - page.top) / page.height, closeTo(.55, .001), ); } else { expect( - (viewer.visibleRect.center.dy - page.top) / page.height, + (viewer().visibleRect.center.dy - page.top) / page.height, closeTo(.2, .001), ); } @@ -333,10 +477,9 @@ void main() { ), ); await _ready(tester, tools); - final viewer = tester - .widget(find.byType(PdfViewer)) - .controller!; - final page = viewer.document.pages.first; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; + final page = viewer().document.pages.first; final links = (await tester.runAsync(() => page.loadLinks()))!; final link = links.firstWhere((link) => link.dest != null); for (var frame = 0; frame < 10; frame++) { @@ -351,14 +494,14 @@ void main() { } final controls = find.byTooltip('Reading settings'); expect(controls, findsNothing); - await tools.goToPage(1); + await _navigate(tester, tools.goToPage(1)); await tester.pumpAndSettle(); final linkRect = link.rects.first.toRectInDocument( page: page, - pageRect: viewer.layout.pageLayouts.first, + pageRect: viewer().layout.pageLayouts.first, ); final drag = await tester.startGesture( - viewer.documentToGlobal(linkRect.center)!, + viewer().documentToGlobal(linkRect.center)!, kind: kind, ); await drag.moveBy(const Offset(0, 40)); @@ -367,30 +510,30 @@ void main() { await tester.pump(const Duration(milliseconds: 350)); expect(tools.pageNumber, 1); expect(controls, findsNothing); - await viewer.textSelectionDelegate.clearTextSelection(); + await viewer().textSelectionDelegate.clearTextSelection(); await tester.pump(const Duration(milliseconds: 350)); for (final initiallyVisible in [false, true]) { - await tools.goToPage(1); + await _navigate(tester, tools.goToPage(1)); await tester.pumpAndSettle(); final rect = link.rects.first.toRectInDocument( page: page, - pageRect: viewer.layout.pageLayouts.first, + pageRect: viewer().layout.pageLayouts.first, ); - final original = viewer.visibleRect; + final original = viewer().visibleRect; await tester.tapAt( - viewer.documentToGlobal(rect.center)!, + viewer().documentToGlobal(rect.center)!, kind: kind, ); await tester.pump(const Duration(milliseconds: 16)); expect(tools.pageNumber, samePage ? 1 : 2); if (samePage) { - expect(viewer.visibleRect.top, greaterThan(original.top + 100)); + expect(viewer().visibleRect.top, greaterThan(original.top + 100)); } - final destination = viewer.visibleRect; + final destination = viewer().visibleRect; await tester.pump(const Duration(milliseconds: 350)); await tester.pumpAndSettle(); - expect(viewer.visibleRect, destination); + expect(viewer().visibleRect, destination); expect(controls, initiallyVisible ? findsOneWidget : findsNothing); final blank = tester.getCenter(find.byType(PdfViewer)) + const Offset(0, 100); @@ -398,10 +541,10 @@ void main() { await tester.pump(const Duration(milliseconds: 350)); await tester.pumpAndSettle(); expect(controls, initiallyVisible ? findsNothing : findsOneWidget); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); expect( - (viewer.visibleRect.center - original.center).distance, + (viewer().visibleRect.center - original.center).distance, lessThan(.001), ); } @@ -446,21 +589,22 @@ void main() { await _ready(tester, tools); await tools.setZoom(1.37); await tester.pumpAndSettle(); - final viewer = tester.widget(find.byType(PdfViewer)).controller!; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; for (final key in [ LogicalKeyboardKey.arrowRight, LogicalKeyboardKey.arrowLeft, ]) { await tester.sendKeyEvent(key); await tester.pumpAndSettle(); - final top = viewer.visibleRect.top; + final top = viewer().visibleRect.top; await tester.sendKeyEvent(LogicalKeyboardKey.arrowDown); await tester.pumpAndSettle(); - expect(viewer.visibleRect.top, greaterThan(top)); - final scrolledTop = viewer.visibleRect.top; + expect(viewer().visibleRect.top, greaterThan(top)); + final scrolledTop = viewer().visibleRect.top; await tester.sendKeyEvent(LogicalKeyboardKey.arrowUp); await tester.pumpAndSettle(); - expect(viewer.visibleRect.top, lessThan(scrolledTop)); + expect(viewer().visibleRect.top, lessThan(scrolledTop)); } await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); @@ -470,23 +614,23 @@ void main() { expect(tools.zoom, closeTo(1.42, .001)); await tester.sendKeyEvent(LogicalKeyboardKey.escape); await tester.pumpAndSettle(); - final beforeScrolling = viewer.visibleRect.top; + final beforeScrolling = viewer().visibleRect.top; await tester.sendKeyDownEvent(LogicalKeyboardKey.arrowDown); await tester.pumpAndSettle(); await tester.sendKeyRepeatEvent(LogicalKeyboardKey.arrowDown); await tester.pumpAndSettle(); await tester.sendKeyUpEvent(LogicalKeyboardKey.arrowDown); - expect(viewer.visibleRect.top, closeTo(beforeScrolling + 50, .001)); + expect(viewer().visibleRect.top, closeTo(beforeScrolling + 50, .001)); // Pointer interaction may instead leave focus in pdfrx's own key handler. - viewer.requestFocus(); + viewer().requestFocus(); await tester.pump(); await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight); await tester.pumpAndSettle(); - final beforeViewerScroll = viewer.visibleRect.top; + final beforeViewerScroll = viewer().visibleRect.top; await tester.sendKeyEvent(LogicalKeyboardKey.arrowDown); await tester.pumpAndSettle(); - expect(viewer.visibleRect.top, greaterThan(beforeViewerScroll)); + expect(viewer().visibleRect.top, greaterThan(beforeViewerScroll)); final toolbar = find.byKey(const ValueKey('reader-toolbar')); final progress = find.byKey(const ValueKey('reader-progress-controls')); @@ -505,8 +649,8 @@ void main() { .linkHandlerParams!; links.customPainter!( _NoPaintCanvas(), - viewer.layout.pageLayouts.first, - viewer.document.pages.first, + viewer().layout.pageLayouts.first, + viewer().document.pages.first, [ PdfLink(const [ PdfRect(0, 100, 100, 0), @@ -530,10 +674,10 @@ void main() { findsOneWidget, ); expect(events.last.visible, isFalse); - final beforeInputArrow = viewer.visibleRect; + final beforeInputArrow = viewer().visibleRect; await tester.sendKeyEvent(LogicalKeyboardKey.arrowDown); await tester.pumpAndSettle(); - expect(viewer.visibleRect, beforeInputArrow); + expect(viewer().visibleRect, beforeInputArrow); final panelRect = tester.getRect(find.byType(ReaderPdfSearchPanel)); expect( tester.widget(find.byType(EditableText)).focusNode.hasFocus, @@ -636,10 +780,9 @@ void main() { await tester.pumpAndSettle(); await tools.scrollVertically(100); await tester.pumpAndSettle(); - final viewer = tester - .widget(find.byType(PdfViewer)) - .controller!; - final original = viewer.visibleRect; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; + final original = viewer().visibleRect; expect(tools.canReturn, isFalse); for (final page in [2, 3]) { @@ -659,7 +802,7 @@ void main() { } expect(tools.canReturn, isFalse); expect( - (viewer.visibleRect.center - original.center).distance, + (viewer().visibleRect.center - original.center).distance, lessThan(.001), ); expect(tools.zoom, closeTo(1.5, .001)); @@ -672,48 +815,48 @@ void main() { expect(tools.canGoForward, isFalse); // An unchanged page entry must not add a duplicate history item. - await tools.goToPage(3); + await _navigate(tester, tools.goToPage(3)); await tester.pumpAndSettle(); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); expect(tools.pageNumber, 2); expect(tools.canGoForward, isTrue); - await tools.goToPage(2); + await _navigate(tester, tools.goToPage(2)); await tester.pumpAndSettle(); expect(tools.canGoForward, isTrue); // A new progress/contents/bookmark jump replaces the forward branch. - await controller.goToProgress(0); + await _navigate(tester, controller.goToProgress(0)); await tester.pumpAndSettle(); expect(tools.pageNumber, 1); expect(tools.canGoForward, isFalse); - final beforeLink = viewer.visibleRect; + final beforeLink = viewer().visibleRect; final params = tester.widget(find.byType(PdfViewer)).params; for (final page in [1, 3]) { params.linkHandlerParams!.onLinkTap( PdfLink([], dest: PdfDest(page, PdfDestCommand.xyz, [100, 400, 2])), ); await tester.pumpAndSettle(); - final destination = viewer.visibleRect; + final destination = viewer().visibleRect; expect(tools.pageNumber, page); expect(tools.zoom, closeTo(2, .001)); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); expect(tools.pageNumber, 1); expect( - (viewer.visibleRect.center - beforeLink.center).distance, + (viewer().visibleRect.center - beforeLink.center).distance, lessThan(.001), ); expect(tools.zoom, closeTo(1.5, .001)); - await tools.goForward(); + await _navigate(tester, tools.goForward()); await tester.pumpAndSettle(); expect(tools.pageNumber, page); expect( - (viewer.visibleRect.center - destination.center).distance, + (viewer().visibleRect.center - destination.center).distance, lessThan(.001), ); expect(tools.zoom, closeTo(2, .001)); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); } @@ -778,32 +921,31 @@ void main() { await _ready(tester, tools); await tools.fitPage(); await tester.pumpAndSettle(); - final viewer = tester - .widget(find.byType(PdfViewer)) - .controller!; - final fitted = viewer.visibleRect; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; + final fitted = viewer().visibleRect; expect( tools.zoom, closeTo(viewportSize.height == 600 ? 1.5 : .8, .000001), ); expect( fitted.center.dx, - closeTo(viewer.layout.pageLayouts.first.center.dx, .001), + closeTo(viewer().layout.pageLayouts.first.center.dx, .001), ); expect( fitted.center.dy, - closeTo(viewer.layout.pageLayouts.first.center.dy, .001), + closeTo(viewer().layout.pageLayouts.first.center.dy, .001), ); for (final distance in [25.0, -25.0]) { await tools.scrollVertically(distance); await tester.pumpAndSettle(); - expect(viewer.visibleRect.top, closeTo(fitted.top, .001)); - expect(viewer.visibleRect.bottom, closeTo(fitted.bottom, .001)); + expect(viewer().visibleRect.top, closeTo(fitted.top, .001)); + expect(viewer().visibleRect.bottom, closeTo(fitted.bottom, .001)); await tester.drag(find.byType(PdfViewer), Offset(0, distance * 4)); await tester.pumpAndSettle(); - expect(viewer.visibleRect.top, closeTo(fitted.top, .001)); - expect(viewer.visibleRect.bottom, closeTo(fitted.bottom, .001)); + expect(viewer().visibleRect.top, closeTo(fitted.top, .001)); + expect(viewer().visibleRect.bottom, closeTo(fitted.bottom, .001)); } } }, skip: kIsWeb); @@ -849,9 +991,8 @@ void main() { ); await tester.pumpWidget(viewport()); await _ready(tester, tools); - final viewer = tester - .widget(find.byType(PdfViewer)) - .controller!; + PdfViewerController viewer() => + tester.widget(find.byType(PdfViewer)).controller!; await tools.setZoom(1.37); await tester.pumpAndSettle(); expect(tools.zoom, closeTo(1.37, .001)); @@ -883,16 +1024,16 @@ void main() { expect(tools.pageNumber, 1); await tools.setZoom(1.37); await tester.pumpAndSettle(); - final center = viewer.visibleRect.center; + final center = viewer().visibleRect.center; await tools.setZoom(1.42); await tester.pumpAndSettle(); expect(tools.zoom, closeTo(1.42, .001)); - expect((viewer.visibleRect.center - center).distance, lessThan(1)); - await tools.goToPage(2); + expect((viewer().visibleRect.center - center).distance, lessThan(1)); + await _navigate(tester, tools.goToPage(2)); await tester.pumpAndSettle(); expect(visiblePage, 1); expect(tools.zoom, closeTo(1.42, .001)); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); expect(tools.pageNumber, 1); width = 640; @@ -906,12 +1047,12 @@ void main() { await tester.pumpAndSettle(); expect( tools.zoom, - closeTo(640 / viewer.layout.pageLayouts.first.width, .000001), + closeTo(640 / viewer().layout.pageLayouts.first.width, .000001), ); - final fittedPage = viewer.layout.pageLayouts.first; - final fittedTop = viewer.visibleRect.top; - expect(viewer.visibleRect.left, closeTo(fittedPage.left, .001)); - expect(viewer.visibleRect.right, closeTo(fittedPage.right, .001)); + final fittedPage = viewer().layout.pageLayouts.first; + final fittedTop = viewer().visibleRect.top; + expect(viewer().visibleRect.left, closeTo(fittedPage.left, .001)); + expect(viewer().visibleRect.right, closeTo(fittedPage.right, .001)); for (final direction in [-1.0, 1.0]) { await tester.drag( @@ -919,17 +1060,17 @@ void main() { Offset(100 * direction, -40), ); await tester.pumpAndSettle(); - expect(viewer.visibleRect.left, closeTo(fittedPage.left, .001)); - expect(viewer.visibleRect.right, closeTo(fittedPage.right, .001)); + expect(viewer().visibleRect.left, closeTo(fittedPage.left, .001)); + expect(viewer().visibleRect.right, closeTo(fittedPage.right, .001)); } - expect(viewer.visibleRect.top, greaterThan(fittedTop)); + expect(viewer().visibleRect.top, greaterThan(fittedTop)); await tools.setZoom(tools.zoom * 1.5); await tester.pumpAndSettle(); - final zoomedLeft = viewer.visibleRect.left; + final zoomedLeft = viewer().visibleRect.left; await tester.drag(find.byType(PdfViewer), const Offset(-60, 0)); await tester.pumpAndSettle(); - expect(viewer.visibleRect.left, greaterThan(zoomedLeft)); + expect(viewer().visibleRect.left, greaterThan(zoomedLeft)); await tools.setZoom(1.37); await tester.pumpAndSettle(); @@ -950,19 +1091,19 @@ void main() { await selecting; expect(tools.pageNumber, 3); expect(tools.currentMatch, 2); - final searchLocation = viewer.visibleRect; - await tools.returnToPrevious(); + final searchLocation = viewer().visibleRect; + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); expect(tools.pageNumber, 1); expect(tools.zoom, closeTo(1.37, .001)); - await tools.goForward(); + await _navigate(tester, tools.goForward()); await tester.pumpAndSettle(); expect(tools.pageNumber, 3); expect( - (viewer.visibleRect.center - searchLocation.center).distance, + (viewer().visibleRect.center - searchLocation.center).distance, lessThan(.001), ); - await tools.returnToPrevious(); + await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); final params = tester.widget(find.byType(PdfViewer)).params; params.linkHandlerParams!.onLinkTap( From e5a13fa7e2ca0572f1872a6482ee495b26ef6abb Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 17:58:25 +0200 Subject: [PATCH 03/19] fix: allow interruptible PDF swipes and defer cache work --- docs/ARCHITECTURE.md | 5 + lib/src/engine/pdf/pdf_facade.dart | 153 +++++++++++++++++++++++--- test/presentation/pdf_tools_test.dart | 84 +++++++++++++- tool/browser/package.json | 2 +- tool/browser/pdf_swipes.mjs | 115 +++++++++++++++++++ 5 files changed, 343 insertions(+), 16 deletions(-) create mode 100644 tool/browser/pdf_swipes.mjs diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 88f76b5..4ba67cf 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -74,6 +74,11 @@ Each paginated spread retains its viewer and rendered images through a swipe and settlement. Neighboring viewers mount lazily and release their resources when evicted from the page cache. Search results belong to the document; navigation and keyboard focus follow the active spread. +Speculative viewers initialize while paging is stationary; visible destinations +can load immediately. Paginated viewers share layout until viewport or page +dimensions change, and preview images use stable resolution steps sized for the +screen, up to the renderer's one-pass limit. Holding an in-flight turn does not +commit or snap its location. The host persists the synchronized locator separately from `PdfViewState`, which is device-local view configuration. `ReaderDocument.initialPdfView` and diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index 5e4f81f..ea7e8c6 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -455,6 +455,8 @@ final class _PdfrxFacade extends PdfReaderTools } final Map _spreads = {}; + PdfPageLayout? _pageLayout; + StreamSubscription? _documentEvents; PdfViewerController get _controller => _activeSpread.controller; int get _spreadIndex => _configuration?.layoutMode == ReaderLayoutMode.scroll ? 0 @@ -727,6 +729,7 @@ final class _PdfrxFacade extends PdfReaderTools ); if (_viewKey != key) { _viewKey = key; + _pageLayout = null; for (final spread in _spreads.values) { spread.finish(); } @@ -895,6 +898,18 @@ final class _PdfrxFacade extends PdfReaderTools params: buildPdfViewerParams( configuration, viewportSize: size, + layoutPages: paginated + ? (pages, params) => + _pageLayout ??= buildPaginatedPdfLayout( + [ + for (final page in pages) + Size(page.width, page.height), + ], + viewportSize: size, + facingPages: configuration.facingPages, + margin: params.margin, + ) + : null, onInteractionStart: _startPageDrag, onInteractionUpdate: _updatePageDrag, onInteractionEnd: _endPageDrag, @@ -976,6 +991,13 @@ final class _PdfrxFacade extends PdfReaderTools paginated ? firstPage : _pageIndex, onViewerReady: (_, _) async { if (_disposed || revision != _viewerRevision) return; + _documentEvents ??= controller.document.events.listen(( + event, + ) { + if (event is PdfDocumentPageStatusChangedEvent) { + _pageLayout = null; + } + }); if (active()) { try { await _restorePage(); @@ -1001,6 +1023,7 @@ final class _PdfrxFacade extends PdfReaderTools ); return _PdfSpreadLifetime( key: ValueKey((revision, index)), + keepAlive: active(), onDispose: () { spread.finish(); if (identical(_spreads[index], spread)) _spreads.remove(index); @@ -1035,7 +1058,11 @@ final class _PdfrxFacade extends PdfReaderTools itemCount: (pageCount / _spreadStep).ceil(), itemBuilder: (context, index) => SizedBox.expand( key: ValueKey(('pdf-spread', index)), - child: buildViewer(index), + child: _PdfSpreadLoader( + pages: pages, + index: index, + builder: (_) => buildViewer(index), + ), ), ), ), @@ -1114,12 +1141,17 @@ final class _PdfrxFacade extends PdfReaderTools final pages = _pagesController; if (_disposed || _restoring || + _pagePointers.isNotEmpty || pages == null || !pages.hasClients || pages.position.isScrollingNotifier.value) { return; } - final target = pages.page!.round() * _spreadStep; + final page = pages.page!; + // A new touch ends the ballistic activity before its next drag starts. + // That pause is not a completed turn and must never snap the held page. + if ((page - page.round()).abs() > .000001) return; + final target = page.round() * _spreadStep; if (target == (_pageIndex ~/ _spreadStep) * _spreadStep) return; unawaited(showPage(target, 0)); } @@ -1191,6 +1223,7 @@ final class _PdfrxFacade extends PdfReaderTools _pageDrag?.cancel(); _pagesController?.dispose(); _searcher.dispose(); + _documentEvents?.cancel(); for (final spread in _spreads.values) { spread.finish(); } @@ -1271,15 +1304,29 @@ final class _PdfSpreadLifetime extends StatefulWidget { super.key, required this.child, required this.onDispose, + required this.keepAlive, }); final Widget child; final VoidCallback onDispose; + final bool keepAlive; @override State<_PdfSpreadLifetime> createState() => _PdfSpreadLifetimeState(); } -final class _PdfSpreadLifetimeState extends State<_PdfSpreadLifetime> { +final class _PdfSpreadLifetimeState extends State<_PdfSpreadLifetime> + with AutomaticKeepAliveClientMixin { + @override + bool get wantKeepAlive => widget.keepAlive; + + @override + void didUpdateWidget(_PdfSpreadLifetime oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.keepAlive != widget.keepAlive) { + updateKeepAlive(); + } + } + @override void dispose() { widget.onDispose(); @@ -1287,7 +1334,74 @@ final class _PdfSpreadLifetimeState extends State<_PdfSpreadLifetime> { } @override - Widget build(BuildContext context) => widget.child; + Widget build(BuildContext context) { + super.build(context); + return widget.child; + } +} + +/// Warm nearby viewers while stationary. Building a new PDF viewer for an +/// off-screen cache slot during a turn competes with the browser's animation. +final class _PdfSpreadLoader extends StatefulWidget { + const _PdfSpreadLoader({ + required this.pages, + required this.index, + required this.builder, + }); + + final PageController pages; + final int index; + final WidgetBuilder builder; + + @override + State<_PdfSpreadLoader> createState() => _PdfSpreadLoaderState(); +} + +final class _PdfSpreadLoaderState extends State<_PdfSpreadLoader> { + bool _loaded = false; + late final _scrolling = widget.pages.position.isScrollingNotifier; + + bool get _shouldLoad { + final page = widget.pages.page ?? widget.pages.initialPage.toDouble(); + final visible = (widget.index - page).abs() < 1; + final settled = !_scrolling.value && (page - page.round()).abs() < .000001; + return visible || settled; + } + + @override + void initState() { + super.initState(); + widget.pages.addListener(_changed); + _scrolling.addListener(_changed); + } + + void _changed() { + if (!_loaded && _shouldLoad) { + setState(() => _loaded = true); + _stopListening(); + } + } + + void _stopListening() { + widget.pages.removeListener(_changed); + _scrolling.removeListener(_changed); + } + + @override + void dispose() { + _stopListening(); + super.dispose(); + } + + @override + Widget build(BuildContext context) { + if (!_loaded && _shouldLoad) { + _loaded = true; + _stopListening(); + } + + return _loaded ? widget.builder(context) : const SizedBox.expand(); + } } PdfViewerParams buildPdfViewerParams( @@ -1297,6 +1411,7 @@ PdfViewerParams buildPdfViewerParams( PdfViewerTextSelectionChangeCallback? onTextSelectionChange, ValueChanged? onPageChanged, Size viewportSize = const Size(800, 600), + PdfPageLayoutFunction? layoutPages, int Function()? currentPageIndex, PdfViewerContextMenuUpdateMenuItemsFunction? customizeContextMenuItems, List highlights = const [], @@ -1312,6 +1427,14 @@ PdfViewerParams buildPdfViewerParams( final handles = PdfSelectionHandles(viewerController); return PdfViewerParams( pageDropShadow: null, + // Round screen resolution up to stable buckets so fitting a new spread + // doesn't immediately replace its image. Keep pdfrx's cap for zoomed tiles. + getPageRenderingScale: (context, page, controller, estimatedScale) { + final scale = + controller.currentZoom * MediaQuery.devicePixelRatioOf(context); + final imageScale = pow(2, (log(scale) / ln2).ceil()).toDouble(); + return min(estimatedScale, imageScale); + }, onInteractionStart: onInteractionStart, onInteractionUpdate: onInteractionUpdate, onInteractionEnd: onInteractionEnd, @@ -1394,16 +1517,18 @@ PdfViewerParams buildPdfViewerParams( // The layout's outer margin separates pages vertically, but must not add // horizontal travel beyond the document edges when fitting its width. boundaryMargin: const EdgeInsets.symmetric(horizontal: -8), - layoutPages: paginated - ? (pages, params) => buildPaginatedPdfLayout( - [for (final page in pages) Size(page.width, page.height)], - viewportSize: viewportSize, - facingPages: configuration.facingPages, - margin: params.margin, - ) - : configuration.facingPages - ? _facingLayout - : null, + layoutPages: + layoutPages ?? + (paginated + ? (pages, params) => buildPaginatedPdfLayout( + [for (final page in pages) Size(page.width, page.height)], + viewportSize: viewportSize, + facingPages: configuration.facingPages, + margin: params.margin, + ) + : configuration.facingPages + ? _facingLayout + : null), // Scroll physics operate on the entire document. Paginated panning is // bounded to the active spread instead, with discrete wheel/touch turns. scrollPhysics: paginated ? null : const ClampingScrollPhysics(), diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index 1d0c05d..8c422fa 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -21,9 +21,10 @@ Future _document({ pdf.PdfPageFormat? pageFormat, bool withLink = false, bool samePageLink = false, + int pageCount = 3, }) async { final document = pw.Document(); - for (var page = 1; page <= 3; page++) { + for (var page = 1; page <= pageCount; page++) { document.addPage( pw.Page( pageFormat: pageFormat ?? pdf.PdfPageFormat.a4, @@ -93,6 +94,87 @@ Future _navigate(WidgetTester tester, Future operation) async { } void main() { + for (final direction in [1, -1]) { + testWidgets( + 'PDF swipes can catch and continue a settling turn, direction $direction', + (tester) async { + await tester.binding.setSurfaceSize(const Size(800, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(() => _document(pageCount: 6)); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'repeat-swipes'), + ))!; + final tools = facade as PdfReaderTools; + final initialPage = direction > 0 ? 0 : 5; + await facade.showPage(initialPage, 0); + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: initialPage, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + var newViewers = 0; + debugOnRebuildDirtyWidget = (element, builtOnce) { + if (!builtOnce && element.widget is PdfViewer) newViewers++; + }; + addTearDown(() => debugOnRebuildDirtyWidget = null); + final pages = tester + .widget(find.byType(PageView)) + .controller!; + final first = await tester.startGesture(const Offset(400, 300)); + await first.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await first.moveBy(Offset(-480.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 80)); + expect( + newViewers, + 0, + reason: 'Speculative viewers must not initialize during a swipe', + ); + await first.up(); + await tester.pump(const Duration(milliseconds: 60)); + expect(pages.position.isScrollingNotifier.value, isTrue); + final beforeCatch = pages.position.pixels; + final second = await tester.startGesture(const Offset(400, 300)); + await tester.pump(const Duration(milliseconds: 16)); + expect( + pages.position.pixels, + closeTo(beforeCatch, 1), + reason: 'Touching a moving page must not snap it to an endpoint', + ); + await second.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + final beforeDrag = pages.position.pixels; + await second.moveBy(Offset(-120.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect(pages.position.pixels, closeTo(beforeDrag + 120 * direction, 1)); + await second.moveBy(Offset(-650.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 80)); + await second.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, direction > 0 ? 3 : 4); + expect(tools.canReturn, isTrue); + await _navigate(tester, tools.returnToPrevious()); + await tester.pumpAndSettle(); + expect(tools.pageNumber, initialPage + 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + for (final initialZoom in [null, .5]) { testWidgets('PDF page pixels survive settling at zoom $initialZoom', ( tester, diff --git a/tool/browser/package.json b/tool/browser/package.json index 5c267e8..d386f75 100644 --- a/tool/browser/package.json +++ b/tool/browser/package.json @@ -2,6 +2,6 @@ "name": "papyrus-reader-browser-checks", "private": true, "type": "module", - "scripts": { "test": "node smoke.mjs" }, + "scripts": { "test": "node smoke.mjs && node pdf_swipes.mjs", "test:pdf-swipes": "node pdf_swipes.mjs" }, "devDependencies": { "playwright": "1.63.0" } } diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs new file mode 100644 index 0000000..78e381c --- /dev/null +++ b/tool/browser/pdf_swipes.mjs @@ -0,0 +1,115 @@ +// Release-build touch regression. PAPYRUS_PDF_PAGES and PAPYRUS_PDF_CPU_RATE +// increase the fixture size and apply Chromium CPU throttling for local profiling. +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { dirname, extname, resolve, sep } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { chromium } from 'playwright'; + +const reader = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); +const dist = process.env.PAPYRUS_PDF_DIST ?? resolve(reader, 'example/build/web'); +const types = { '.html': 'text/html', '.js': 'text/javascript', '.json': 'application/json', + '.wasm': 'application/wasm', '.ttf': 'font/ttf' }; +const server = createServer(async (request, response) => { + const path = resolve(dist, `.${decodeURIComponent(new URL(request.url, 'http://local').pathname)}`); + if (path !== dist && !path.startsWith(dist + sep)) { response.writeHead(403).end(); return; } + try { + const file = path === dist ? resolve(dist, 'index.html') : path; + response.writeHead(200, { 'Content-Type': types[extname(file)] ?? 'application/octet-stream' }); + response.end(await readFile(file)); + } catch { response.writeHead(404).end(); } +}); +await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); +const browser = await chromium.launch({ executablePath: process.env.PAPYRUS_CHROME_EXECUTABLE }); +const temp = await mkdtemp(resolve(tmpdir(), 'papyrus-pdf-swipes-')); + +function fixture(pageCount) { + const objects = ['<< /Type /Catalog /Pages 2 0 R >>', '', '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>']; + const kids = []; + for (let page = 1; page <= pageCount; page++) { + const id = objects.length + 1; + kids.push(`${id} 0 R`); + objects.push(`<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Resources << /Font << /F1 3 0 R >> >> /Contents ${id + 1} 0 R >>`); + let content = `BT /F1 22 Tf 50 780 Td (Swipe page ${page}.) Tj ET\n`; + for (let i = 0; i < 600; i++) { + content += `${(i % 7) / 8} ${(page % 5) / 6} ${(i % 3) / 4} rg ${40 + (i % 25) * 20} ${60 + Math.floor(i / 25) * 27} 16 22 re f\n`; + } + objects.push(`<< /Length ${Buffer.byteLength(content)} >>\nstream\n${content}endstream`); + } + objects[1] = `<< /Type /Pages /Count ${pageCount} /Kids [${kids.join(' ')}] >>`; + let pdf = '%PDF-1.4\n'; + const offsets = [0]; + objects.forEach((object, index) => { + offsets.push(Buffer.byteLength(pdf)); + pdf += `${index + 1} 0 obj\n${object}\nendobj\n`; + }); + const xref = Buffer.byteLength(pdf); + pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`; + for (const offset of offsets.slice(1)) pdf += `${String(offset).padStart(10, '0')} 00000 n \n`; + return pdf + `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`; +} + +try { + const page = await browser.newPage({ viewport: { width: 800, height: 700 }, hasTouch: true }); + page.setDefaultTimeout(15000); + const errors = []; + page.on('pageerror', error => errors.push(error.message)); + await page.goto(`http://127.0.0.1:${server.address().port}`); + await page.locator('flt-semantics-placeholder').evaluate(element => element.click()); + const book = resolve(temp, 'swipes.pdf'); + await writeFile(book, fixture(Number(process.env.PAPYRUS_PDF_PAGES ?? 40))); + const chooser = page.waitForEvent('filechooser'); + await page.getByRole('button', { name: 'Open a book', exact: true }).click(); + await (await chooser).setFiles(book); + await page.getByText('Swipe page 1.', { exact: true }).waitFor(); + await page.waitForTimeout(1500); + const cdp = await page.context().newCDPSession(page); + await cdp.send('Emulation.setCPUThrottlingRate', { rate: Number(process.env.PAPYRUS_PDF_CPU_RATE ?? 1) }); + const swipe = async (direction = 1) => { + const x = direction > 0 ? 720 : 80; + const point = offset => [{ x: x - direction * offset, y: 350, id: 1 }]; + await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: point(0) }); + for (let step = 1; step <= 18; step++) { + await cdp.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: point(step * 35) }); + await page.waitForTimeout(12); + } + await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] }); + }; + await page.evaluate(() => { + window.swipeMetrics = { gaps: [], tasks: [] }; + let last; + const tick = now => { + if (last !== undefined) window.swipeMetrics.gaps.push(now - last); + last = now; + window.swipeFrame = requestAnimationFrame(tick); + }; + window.swipeFrame = requestAnimationFrame(tick); + window.swipeObserver = new PerformanceObserver(list => { + window.swipeMetrics.tasks.push(...list.getEntries().map(entry => entry.duration)); + }); + window.swipeObserver.observe({ type: 'longtask', buffered: false }); + }); + for (let turn = 0; turn < 4; turn++) { + await swipe(); + await page.waitForTimeout(70); + } + await page.waitForTimeout(1000); + const metrics = await page.evaluate(() => { + cancelAnimationFrame(window.swipeFrame); + window.swipeObserver.disconnect(); + const { gaps, tasks } = window.swipeMetrics; + gaps.sort((left, right) => left - right); + return { frames: gaps.length, p99FrameGapMs: gaps[Math.floor(gaps.length * .99)], + maxFrameGapMs: gaps.at(-1), framesOver50Ms: gaps.filter(gap => gap > 50).length, + longTaskCount: tasks.length, maxLongTaskMs: Math.max(0, ...tasks) }; + }); + await page.getByText('Swipe page 5.', { exact: true }).waitFor(); + assert.deepEqual(errors, []); + console.log(JSON.stringify({ ...metrics, reachedPage: 5 })); +} finally { + await browser.close(); + await new Promise(resolve => server.close(resolve)); + await rm(temp, { recursive: true, force: true }); +} From cba01398d5e42ef744b9507039c1465f484c0254 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 18:14:49 +0200 Subject: [PATCH 04/19] fix: keep desktop PDF mouse swipes interruptible --- lib/src/engine/pdf/pdf_facade.dart | 41 ++-- test/presentation/pdf_tools_test.dart | 268 ++++++++++++++++++-------- tool/browser/pdf_swipes.mjs | 162 ++++++++++------ 3 files changed, 327 insertions(+), 144 deletions(-) diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index ea7e8c6..c599768 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -1048,20 +1048,30 @@ final class _PdfrxFacade extends PdfReaderTools } return false; }, - child: PageView.builder( - key: ValueKey(pages), - controller: pages, - allowImplicitScrolling: true, - physics: _pagingEnabled - ? const ClampingScrollPhysics() - : const NeverScrollableScrollPhysics(), - itemCount: (pageCount / _spreadStep).ceil(), - itemBuilder: (context, index) => SizedBox.expand( - key: ValueKey(('pdf-spread', index)), - child: _PdfSpreadLoader( - pages: pages, - index: index, - builder: (_) => buildViewer(index), + child: ScrollConfiguration( + behavior: ScrollConfiguration.of(context).copyWith( + // The incoming viewer is inactive until settlement. + // Its parent must still accept a mouse drag mid-turn. + dragDevices: { + ...ScrollConfiguration.of(context).dragDevices, + PointerDeviceKind.mouse, + }, + ), + child: PageView.builder( + key: ValueKey(pages), + controller: pages, + allowImplicitScrolling: true, + physics: _pagingEnabled + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + itemCount: (pageCount / _spreadStep).ceil(), + itemBuilder: (context, index) => SizedBox.expand( + key: ValueKey(('pdf-spread', index)), + child: _PdfSpreadLoader( + pages: pages, + index: index, + builder: (_) => buildViewer(index), + ), ), ), ), @@ -1090,6 +1100,9 @@ final class _PdfrxFacade extends PdfReaderTools _multiTouch = false; notifyListeners(); } + // A mouse press can outlast the ballistic turn. ScrollEnd then runs while + // the pointer is down, so release must retry committing the visible page. + if (_pagePointers.isEmpty) scheduleMicrotask(_settlePage); } void _startPageDrag(ScaleStartDetails details) { diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index 8c422fa..5cbde7c 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -94,86 +94,202 @@ Future _navigate(WidgetTester tester, Future operation) async { } void main() { - for (final direction in [1, -1]) { - testWidgets( - 'PDF swipes can catch and continue a settling turn, direction $direction', - (tester) async { - await tester.binding.setSurfaceSize(const Size(800, 600)); - addTearDown(() => tester.binding.setSurfaceSize(null)); - final bytes = await tester.runAsync(() => _document(pageCount: 6)); - await tester.runAsync(initializePdfiumForTest); - final facade = (await tester.runAsync( - () => createPdfrxFacade(bytes!, sourceName: 'repeat-swipes'), - ))!; - final tools = facade as PdfReaderTools; - final initialPage = direction > 0 ? 0 : 5; - await facade.showPage(initialPage, 0); - addTearDown(() => (facade as DisposablePdfFacade).dispose()); - await tester.pumpWidget( - MaterialApp( - home: facade.buildViewport( - PdfViewportConfiguration( - pageIndex: initialPage, - facingPages: false, - backgroundColor: Colors.white, - brightness: Brightness.light, - layoutMode: ReaderLayoutMode.paginated, - onPageChanged: (_) {}, + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + for (final direction in [1, -1]) { + testWidgets( + 'PDF $kind swipes can catch and continue a settling turn, direction $direction', + (tester) async { + final width = kind == PointerDeviceKind.mouse ? 1440.0 : 800.0; + await tester.binding.setSurfaceSize(Size(width, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(() => _document(pageCount: 6)); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'repeat-swipes'), + ))!; + final tools = facade as PdfReaderTools; + final initialPage = direction > 0 ? 0 : 5; + await facade.showPage(initialPage, 0); + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: initialPage, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), ), ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + var newViewers = 0; + debugOnRebuildDirtyWidget = (element, builtOnce) { + if (!builtOnce && element.widget is PdfViewer) newViewers++; + }; + addTearDown(() => debugOnRebuildDirtyWidget = null); + final pages = tester + .widget(find.byType(PageView)) + .controller!; + final first = await tester.startGesture( + Offset(width / 2, 300), + kind: kind, + ); + await first.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await first.moveBy(Offset(-width * .6 * direction, 0)); + await tester.pump(const Duration(milliseconds: 80)); + expect( + newViewers, + 0, + reason: 'Speculative viewers must not initialize during a swipe', + ); + await first.up(); + await tester.pump(const Duration(milliseconds: 60)); + expect(pages.position.isScrollingNotifier.value, isTrue); + final beforeCatch = pages.position.pixels; + final second = await tester.startGesture( + Offset(width / 2, 300), + kind: kind, + ); + await tester.pump(const Duration(milliseconds: 16)); + expect( + pages.position.pixels, + closeTo(beforeCatch, 1), + reason: 'Touching a moving page must not snap it to an endpoint', + ); + await second.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + final beforeDrag = pages.position.pixels; + await second.moveBy(Offset(-120.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect( + pages.position.pixels, + closeTo(beforeDrag + 120 * direction, 1), + ); + await second.moveBy(Offset(-width * .82 * direction, 0)); + await tester.pump(const Duration(milliseconds: 80)); + await second.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, direction > 0 ? 3 : 4); + expect(tools.canReturn, isTrue); + await _navigate(tester, tools.returnToPrevious()); + await tester.pumpAndSettle(); + expect(tools.pageNumber, initialPage + 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + } + + testWidgets( + 'PDF mouse hold and release keeps navigation and selection alive', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(() => _document()); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'mouse-hold'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + final first = await tester.startGesture( + const Offset(1250, 450), + kind: PointerDeviceKind.mouse, + ); + await first.moveBy(const Offset(-30, 0)); + await tester.pump(); + await first.moveBy(const Offset(-900, 0)); + await tester.pump(const Duration(milliseconds: 80)); + await first.up(); + await tester.pump(const Duration(milliseconds: 60)); + final held = await tester.startGesture( + const Offset(1000, 450), + kind: PointerDeviceKind.mouse, + ); + await tester.pump(const Duration(seconds: 1)); + await held.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 2); + + final viewer = tester + .widgetList(find.byType(PdfViewer)) + .singleWhere((viewer) => viewer.initialPageNumber == 2); + final controller = viewer.controller!; + for ( + var attempt = 0; + attempt < 100 && !controller.document.pages[1].isLoaded; + attempt++ + ) { + await tester.runAsync( + () => Future.delayed(const Duration(milliseconds: 20)), ); - await _ready(tester, tools); - await tester.pumpAndSettle(); - var newViewers = 0; - debugOnRebuildDirtyWidget = (element, builtOnce) { - if (!builtOnce && element.widget is PdfViewer) newViewers++; - }; - addTearDown(() => debugOnRebuildDirtyWidget = null); - final pages = tester - .widget(find.byType(PageView)) - .controller!; - final first = await tester.startGesture(const Offset(400, 300)); - await first.moveBy(Offset(-30.0 * direction, 0)); - await tester.pump(); - await first.moveBy(Offset(-480.0 * direction, 0)); - await tester.pump(const Duration(milliseconds: 80)); - expect( - newViewers, - 0, - reason: 'Speculative viewers must not initialize during a swipe', - ); - await first.up(); - await tester.pump(const Duration(milliseconds: 60)); - expect(pages.position.isScrollingNotifier.value, isTrue); - final beforeCatch = pages.position.pixels; - final second = await tester.startGesture(const Offset(400, 300)); - await tester.pump(const Duration(milliseconds: 16)); - expect( - pages.position.pixels, - closeTo(beforeCatch, 1), - reason: 'Touching a moving page must not snap it to an endpoint', - ); - await second.moveBy(Offset(-30.0 * direction, 0)); - await tester.pump(); - final beforeDrag = pages.position.pixels; - await second.moveBy(Offset(-120.0 * direction, 0)); - await tester.pump(const Duration(milliseconds: 16)); - expect(pages.position.pixels, closeTo(beforeDrag + 120 * direction, 1)); - await second.moveBy(Offset(-650.0 * direction, 0)); - await tester.pump(const Duration(milliseconds: 80)); - await second.up(); - await tester.pumpAndSettle(); - expect(tools.pageNumber, direction > 0 ? 3 : 4); - expect(tools.canReturn, isTrue); - await _navigate(tester, tools.returnToPrevious()); - await tester.pumpAndSettle(); - expect(tools.pageNumber, initialPage + 1); - expect(tester.takeException(), isNull); - await tester.pumpWidget(const SizedBox.shrink()); - }, - ); - } + await tester.pump(const Duration(milliseconds: 20)); + } + final page = controller.document.pages[1]; + expect(page.isLoaded, isTrue); + final text = (await tester.runAsync(() => page.loadText()))!; + Offset character(int index) => controller.documentToGlobal( + text.charRects[index].center.toOffsetInDocument( + page: page, + pageRect: controller.layout.pageLayouts[1], + ), + )!; + final selection = await tester.startGesture( + character(0), + kind: PointerDeviceKind.mouse, + ); + await selection.moveTo(character(12)); + await tester.pump(); + await selection.up(); + await tester.pumpAndSettle(); + expect(controller.textSelectionDelegate.hasSelectedText, isTrue); + expect( + tools.pageNumber, + 2, + reason: 'Selecting text must not turn the page', + ); + await tester.tapAt( + const Offset(1200, 450), + kind: PointerDeviceKind.mouse, + ); + await tester.pumpAndSettle(); + final reverse = await tester.startGesture( + const Offset(190, 450), + kind: PointerDeviceKind.mouse, + ); + await reverse.moveBy(const Offset(30, 0)); + await tester.pump(); + await reverse.moveBy(const Offset(900, 0)); + await reverse.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); for (final initialZoom in [null, .5]) { testWidgets('PDF page pixels survive settling at zoom $initialZoom', ( diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index 78e381c..575dc48 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -1,4 +1,4 @@ -// Release-build touch regression. PAPYRUS_PDF_PAGES and PAPYRUS_PDF_CPU_RATE +// Release-build touch and desktop mouse regressions. PAPYRUS_PDF_PAGES and PAPYRUS_PDF_CPU_RATE // increase the fixture size and apply Chromium CPU throttling for local profiling. import assert from 'node:assert/strict'; import { createServer } from 'node:http'; @@ -52,62 +52,116 @@ function fixture(pageCount) { } try { - const page = await browser.newPage({ viewport: { width: 800, height: 700 }, hasTouch: true }); - page.setDefaultTimeout(15000); - const errors = []; - page.on('pageerror', error => errors.push(error.message)); - await page.goto(`http://127.0.0.1:${server.address().port}`); - await page.locator('flt-semantics-placeholder').evaluate(element => element.click()); - const book = resolve(temp, 'swipes.pdf'); - await writeFile(book, fixture(Number(process.env.PAPYRUS_PDF_PAGES ?? 40))); - const chooser = page.waitForEvent('filechooser'); - await page.getByRole('button', { name: 'Open a book', exact: true }).click(); - await (await chooser).setFiles(book); - await page.getByText('Swipe page 1.', { exact: true }).waitFor(); - await page.waitForTimeout(1500); - const cdp = await page.context().newCDPSession(page); - await cdp.send('Emulation.setCPUThrottlingRate', { rate: Number(process.env.PAPYRUS_PDF_CPU_RATE ?? 1) }); - const swipe = async (direction = 1) => { - const x = direction > 0 ? 720 : 80; - const point = offset => [{ x: x - direction * offset, y: 350, id: 1 }]; - await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: point(0) }); - for (let step = 1; step <= 18; step++) { - await cdp.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: point(step * 35) }); - await page.waitForTimeout(12); - } - await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] }); - }; - await page.evaluate(() => { - window.swipeMetrics = { gaps: [], tasks: [] }; - let last; - const tick = now => { - if (last !== undefined) window.swipeMetrics.gaps.push(now - last); - last = now; - window.swipeFrame = requestAnimationFrame(tick); + for (const input of ['touch', 'mouse']) { + const width = input === 'mouse' ? 1440 : 800; + const page = await browser.newPage({ viewport: { width, height: 900 }, hasTouch: input === 'touch' }); + page.setDefaultTimeout(15000); + const errors = []; + page.on('pageerror', error => errors.push(error.message)); + await page.goto(`http://127.0.0.1:${server.address().port}`); + await page.locator('flt-semantics-placeholder').evaluate(element => element.click()); + const book = resolve(temp, 'swipes.pdf'); + await writeFile(book, fixture(Number(process.env.PAPYRUS_PDF_PAGES ?? 40))); + const chooser = page.waitForEvent('filechooser'); + await page.getByRole('button', { name: 'Open a book', exact: true }).click(); + await (await chooser).setFiles(book); + await page.getByText('Swipe page 1.', { exact: true }).waitFor(); + await page.waitForTimeout(1500); + const cdp = await page.context().newCDPSession(page); + await cdp.send('Emulation.setCPUThrottlingRate', { rate: Number(process.env.PAPYRUS_PDF_CPU_RATE ?? 1) }); + const swipe = async (direction = 1) => { + const x = direction > 0 ? width * .97 : width * .03; + const point = offset => [{ x: x - direction * offset, y: 350, id: 1 }]; + if (input === 'mouse') { + await page.mouse.move(x, 350); + await page.mouse.down(); + } else { + await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: point(0) }); + } + for (let step = 1; step <= 18; step++) { + const offset = step * width * .94 / 18; + if (input === 'mouse') { + await page.mouse.move(x - direction * offset, 350); + } else { + await cdp.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: point(offset) }); + } + await page.waitForTimeout(12); + } + if (input === 'mouse') { + await page.mouse.up(); + } else { + await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] }); + } }; - window.swipeFrame = requestAnimationFrame(tick); - window.swipeObserver = new PerformanceObserver(list => { - window.swipeMetrics.tasks.push(...list.getEntries().map(entry => entry.duration)); + await page.evaluate(() => { + window.swipeMetrics = { gaps: [], tasks: [] }; + let last; + const tick = now => { + if (last !== undefined) window.swipeMetrics.gaps.push(now - last); + last = now; + window.swipeFrame = requestAnimationFrame(tick); + }; + window.swipeFrame = requestAnimationFrame(tick); + window.swipeObserver = new PerformanceObserver(list => { + window.swipeMetrics.tasks.push(...list.getEntries().map(entry => entry.duration)); + }); + window.swipeObserver.observe({ type: 'longtask', buffered: false }); }); - window.swipeObserver.observe({ type: 'longtask', buffered: false }); - }); - for (let turn = 0; turn < 4; turn++) { - await swipe(); - await page.waitForTimeout(70); + for (let turn = 0; turn < 4; turn++) { + await swipe(); + await page.waitForTimeout(70); + } + await page.waitForTimeout(1000); + const metrics = await page.evaluate(() => { + cancelAnimationFrame(window.swipeFrame); + window.swipeObserver.disconnect(); + const { gaps, tasks } = window.swipeMetrics; + gaps.sort((left, right) => left - right); + return { frames: gaps.length, p99FrameGapMs: gaps[Math.floor(gaps.length * .99)], + maxFrameGapMs: gaps.at(-1), framesOver50Ms: gaps.filter(gap => gap > 50).length, + longTaskCount: tasks.length, maxLongTaskMs: Math.max(0, ...tasks) }; + }); + const assertPage = async number => { + if (await page.getByRole('button', { name: 'Back', exact: true }).count() === 0) { + await page.keyboard.press('Escape'); + } + try { + await page.getByRole('button', { name: `Page ${number} of ${Number(process.env.PAPYRUS_PDF_PAGES ?? 40)}. Go to page`, exact: true }).waitFor(); + } catch (error) { + throw new Error(`Expected active PDF page ${number}:\n${await page.locator('body').ariaSnapshot()}`, { cause: error }); + } + await page.keyboard.press('Escape'); + await page.waitForTimeout(300); + }; + await assertPage(5); + assert.deepEqual(errors, []); + console.log(JSON.stringify({ input, width, ...metrics, reachedPage: 5 })); + if (input === 'mouse') { + await swipe(); + await page.waitForTimeout(70); + await page.mouse.move(width * .7, 350); + await page.mouse.down(); + await page.waitForTimeout(700); + await page.mouse.up(); + await page.waitForTimeout(700); + await assertPage(6); + const text = await page.getByText('Swipe page 6.', { exact: true }).boundingBox(); + assert.ok(text); + await page.mouse.move(text.x + 2, text.y + text.height / 2); + await page.mouse.down(); + await page.mouse.move(text.x + text.width - 2, text.y + text.height / 2, { steps: 12 }); + await page.mouse.up(); + await page.getByRole('button', { name: 'Copy', exact: true }).waitFor(); + await page.mouse.click(width * .9, 450); + await page.waitForTimeout(400); + await swipe(-1); + await page.waitForTimeout(700); + await assertPage(5); + assert.deepEqual(errors, []); + console.log('PASS: desktop mouse hold, text selection, and reverse swipe'); + } + await page.close(); } - await page.waitForTimeout(1000); - const metrics = await page.evaluate(() => { - cancelAnimationFrame(window.swipeFrame); - window.swipeObserver.disconnect(); - const { gaps, tasks } = window.swipeMetrics; - gaps.sort((left, right) => left - right); - return { frames: gaps.length, p99FrameGapMs: gaps[Math.floor(gaps.length * .99)], - maxFrameGapMs: gaps.at(-1), framesOver50Ms: gaps.filter(gap => gap > 50).length, - longTaskCount: tasks.length, maxLongTaskMs: Math.max(0, ...tasks) }; - }); - await page.getByText('Swipe page 5.', { exact: true }).waitFor(); - assert.deepEqual(errors, []); - console.log(JSON.stringify({ ...metrics, reachedPage: 5 })); } finally { await browser.close(); await new Promise(resolve => server.close(resolve)); From a00fcb38d079feed26c2de268c81aaf9838b6333 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 18:29:56 +0200 Subject: [PATCH 05/19] feat: support mouse page drags in text book formats --- docs/ARCHITECTURE.md | 3 + lib/src/engine/epub/epub_viewport.dart | 88 ++-- .../presentation/reader_mouse_page_drag.dart | 111 +++++ test/presentation/epub_page_turn_test.dart | 387 ++++++++++-------- tool/browser/formats.mjs | 37 +- 5 files changed, 412 insertions(+), 214 deletions(-) create mode 100644 lib/src/presentation/reader_mouse_page_drag.dart diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4ba67cf..b8c0f73 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -98,6 +98,9 @@ Controls and panels overlay the reading viewport so visibility changes do not repaginate content. Page-tap toggles exclude selections, links and competing pointer gestures. Keyboard focus survives chapter replacement without stealing focus from an open panel. Reduced motion changes transitions, not layout. +In paginated text formats, mouse drags starting in blank space turn pages; +drags starting on rendered text remain selection gestures. Mouse turns use the +same page controller as touch and can interrupt an unfinished turn. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index f2b69ba..fdb86ca 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -11,6 +11,7 @@ import '../../domain/reader_preferences.dart'; import '../../presentation/reader_interaction_scope.dart'; import '../../presentation/reader_loading.dart'; import '../../presentation/reader_swipe_tracker.dart'; +import '../../presentation/reader_mouse_page_drag.dart'; import '../../presentation/reader_highlight_interaction.dart'; import '../../presentation/reader_text_toolbar.dart'; import 'epub_reader_engine.dart'; @@ -537,6 +538,8 @@ final class _EpubViewportState extends State { return; } final page = _pagesController.page! - _leadingPages; + // Catching an unfinished turn also ends its current scroll activity. + if ((page - page.round()).abs() > .000001) return; final count = (_pages.length / _columns).ceil(); if (page >= 0 && page < count) return; unawaited( @@ -1154,45 +1157,64 @@ final class _EpubViewportState extends State { } return false; }, - child: PageView.builder( - key: ValueKey(_pagesController), + child: ReaderMousePageDrag( controller: _pagesController, - physics: _animateTurns - ? const ClampingScrollPhysics() - : const NeverScrollableScrollPhysics(), - onPageChanged: (index) => _publishPage(index - leading), - itemCount: _pageViewCount, - itemBuilder: (context, index) { - final local = index - leading; - if (local < 0 || local >= count) { - final direction = local < 0 ? -1 : 1; - final spine = - widget.engine.locator.spineIndex + direction; - final neighbor = - _layoutCache[(spine, _geometryKey)]; - if (neighbor == null || - neighbor.pages.isEmpty || - (direction < 0 && !neighbor.complete)) { - return const ReaderLoading(); + animate: _animateTurns, + onTurn: _requestTurn, + canStart: (position) => + _selectedText.isEmpty && + !_fragments.any( + (fragment) => fragment + .rectangles( + 0, + fragment.widget.fragment.end - + fragment.widget.fragment.start, + ) + .any( + (rectangle) => rectangle.contains(position), + ), + ), + child: PageView.builder( + key: ValueKey(_pagesController), + controller: _pagesController, + physics: _animateTurns + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + onPageChanged: (index) => + _publishPage(index - leading), + itemCount: _pageViewCount, + itemBuilder: (context, index) { + final local = index - leading; + if (local < 0 || local >= count) { + final direction = local < 0 ? -1 : 1; + final spine = + widget.engine.locator.spineIndex + direction; + final neighbor = + _layoutCache[(spine, _geometryKey)]; + if (neighbor == null || + neighbor.pages.isEmpty || + (direction < 0 && !neighbor.complete)) { + return const ReaderLoading(); + } + return _spread( + neighbor.pages, + direction > 0 + ? 0 + : (neighbor.pages.length / columns).ceil() - + 1, + columns, + displayPreferences, + spine: spine, + ); } return _spread( - neighbor.pages, - direction > 0 - ? 0 - : (neighbor.pages.length / columns).ceil() - - 1, + pages, + local, columns, displayPreferences, - spine: spine, ); - } - return _spread( - pages, - local, - columns, - displayPreferences, - ); - }, + }, + ), ), ); } diff --git a/lib/src/presentation/reader_mouse_page_drag.dart b/lib/src/presentation/reader_mouse_page_drag.dart new file mode 100644 index 0000000..37c73b1 --- /dev/null +++ b/lib/src/presentation/reader_mouse_page_drag.dart @@ -0,0 +1,111 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/widgets.dart'; + +/// Mouse drags in blank page space participate before the enclosing selection +/// area. Drags starting on text stay with selection, including across lines. +final class ReaderMousePageDrag extends StatefulWidget { + const ReaderMousePageDrag({ + required this.controller, + required this.animate, + required this.canStart, + required this.onTurn, + required this.child, + super.key, + }); + + final PageController controller; + final bool animate; + final bool Function(Offset position) canStart; + final ValueChanged onTurn; + final Widget child; + + @override + State createState() => _ReaderMousePageDragState(); +} + +final class _ReaderMousePageDragState extends State { + ScrollHoldController? _hold; + Drag? _drag; + double _distance = 0; + + void _down(DragDownDetails details) { + _distance = 0; + if (widget.animate && widget.controller.hasClients) { + _hold = widget.controller.position.hold(() => _hold = null); + } + } + + void _start(DragStartDetails details) { + if (widget.animate && widget.controller.hasClients) { + _drag = widget.controller.position.drag(details, () => _drag = null); + } + } + + void _update(DragUpdateDetails details) { + _distance += details.primaryDelta!; + _drag?.update(details); + } + + void _end(DragEndDetails details) { + final drag = _drag; + _drag = null; + drag?.end(details); + _hold?.cancel(); + _hold = null; + if (!widget.animate && _distance.abs() > 70) { + widget.onTurn(_distance < 0 ? 1 : -1); + } + } + + void _cancel() { + _drag?.cancel(); + _drag = null; + _hold?.cancel(); + _hold = null; + } + + @override + void didUpdateWidget(ReaderMousePageDrag oldWidget) { + super.didUpdateWidget(oldWidget); + if (oldWidget.controller != widget.controller || + oldWidget.animate != widget.animate) { + _cancel(); + } + } + + @override + void dispose() { + _cancel(); + super.dispose(); + } + + @override + Widget build(BuildContext context) => RawGestureDetector( + behavior: HitTestBehavior.opaque, + gestures: { + _BlankPageMouseDrag: + GestureRecognizerFactoryWithHandlers<_BlankPageMouseDrag>( + _BlankPageMouseDrag.new, + (recognizer) => recognizer + ..canStart = widget.canStart + ..dragStartBehavior = DragStartBehavior.down + ..onDown = _down + ..onStart = _start + ..onUpdate = _update + ..onEnd = _end + ..onCancel = _cancel, + ), + }, + child: widget.child, + ); +} + +final class _BlankPageMouseDrag extends HorizontalDragGestureRecognizer { + _BlankPageMouseDrag() : super(supportedDevices: {PointerDeviceKind.mouse}); + + late bool Function(Offset position) canStart; + + @override + bool isPointerAllowed(PointerEvent event) => + super.isPointerAllowed(event) && canStart(event.position); +} diff --git a/test/presentation/epub_page_turn_test.dart b/test/presentation/epub_page_turn_test.dart index 7c737b8..9519c04 100644 --- a/test/presentation/epub_page_turn_test.dart +++ b/test/presentation/epub_page_turn_test.dart @@ -1,4 +1,5 @@ import 'package:flutter/material.dart'; +import 'package:flutter/gestures.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:papyrus_reader/papyrus_reader.dart'; @@ -6,143 +7,163 @@ import '../support/in_process_epub_worker.dart'; import '../support/synthetic_epub.dart'; void main() { - for (final facing in [false, true]) { - testWidgets( - 'chapter edges follow the finger in both directions, facing $facing', - (tester) async { - await tester.binding.setSurfaceSize(Size(facing ? 1000 : 600, 600)); - addTearDown(() => tester.binding.setSurfaceSize(null)); - final engine = testEpubEngine(); - addTearDown(engine.dispose); - await engine.load( - ReaderDocument( - id: 'drag-boundaries', - format: ReaderFormat.epub, - loadBytes: () async => - syntheticEpub(firstChapterBody: '

First page.

'), - ), - preferences: const ReaderPreferences(), - ); - await tester.pumpWidget( - MaterialApp(home: Builder(builder: engine.buildViewport)), - ); - await tester.pumpAndSettle(); + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + for (final facing in [false, true]) { + testWidgets( + 'chapter edges follow $kind in both directions, facing $facing', + (tester) async { + await tester.binding.setSurfaceSize(Size(facing ? 1000 : 600, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'drag-boundaries', + format: ReaderFormat.epub, + loadBytes: () async => + syntheticEpub(firstChapterBody: '

First page.

'), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); - Finder spread(int spine) => - find.byKey(ValueKey(('epub-spread', spine, 0))); - for (final direction in [1, -1]) { - final viewport = find.byType(PageView); - final before = engine.snapshot.locator; - final bounds = tester.getRect(viewport); - final outgoing = spread(direction > 0 ? 0 : 1); - final incoming = spread(direction > 0 ? 1 : 0); - final gesture = await tester.startGesture(bounds.center); - await gesture.moveBy(Offset(-30.0 * direction, 0)); - await tester.pump(); - for (final distance in [80.0, 90.0, 70.0]) { - final oldLeft = tester.getTopLeft(outgoing).dx; - await gesture.moveBy(Offset(-distance * direction, 0)); + Finder spread(int spine) => + find.byKey(ValueKey(('epub-spread', spine, 0))); + for (final direction in [1, -1]) { + final viewport = find.byType(PageView); + final before = engine.snapshot.locator; + final bounds = tester.getRect(viewport); + final outgoing = spread(direction > 0 ? 0 : 1); + final incoming = spread(direction > 0 ? 1 : 0); + final gesture = await tester.startGesture( + bounds.center, + kind: kind, + ); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + for (final distance in [80.0, 90.0, 70.0]) { + final oldLeft = tester.getTopLeft(outgoing).dx; + await gesture.moveBy(Offset(-distance * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + final current = tester.getRect(outgoing); + final next = tester.getRect(incoming); + expect( + tester.getRect(viewport), + bounds, + reason: 'The viewport itself must never translate', + ); + expect(current.left, closeTo(oldLeft - distance * direction, 1)); + expect( + direction > 0 ? current.right : next.right, + closeTo(direction > 0 ? next.left : current.left, .01), + reason: + 'Adjacent pages share one edge throughout the drag, with no overlap', + ); + expect(current.width, bounds.width); + expect(next.width, bounds.width); + expect(engine.snapshot.locator, before); + } + await gesture.moveBy(Offset(240.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + await gesture.up(); + await tester.pumpAndSettle(); + expect(tester.getRect(outgoing), bounds); + expect(engine.snapshot.locator, before); + + final turn = await tester.startGesture(bounds.center, kind: kind); + await turn.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await turn.moveBy(Offset(-bounds.width * .65 * direction, 0)); await tester.pump(const Duration(milliseconds: 16)); - final current = tester.getRect(outgoing); - final next = tester.getRect(incoming); + expect(engine.snapshot.locator, before); + await turn.up(); + await tester.pump(); + await tester.pump(const Duration(milliseconds: 16)); + expect(engine.snapshot.locator, before); + final held = await tester.startGesture(bounds.center, kind: kind); + await tester.pump(const Duration(milliseconds: 100)); expect( - tester.getRect(viewport), - bounds, - reason: 'The viewport itself must never translate', + engine.snapshot.locator, + before, + reason: 'Holding a partially turned chapter must not commit it', ); - expect(current.left, closeTo(oldLeft - distance * direction, 1)); + await held.up(); + await tester.pumpAndSettle(); expect( - direction > 0 ? current.right : next.right, - closeTo(direction > 0 ? next.left : current.left, .01), - reason: - 'Adjacent pages share one edge throughout the drag, with no overlap', + (engine.snapshot.locator as EpubReaderLocator).spineIndex, + direction > 0 ? 1 : 0, ); - expect(current.width, bounds.width); - expect(next.width, bounds.width); - expect(engine.snapshot.locator, before); + expect(tester.getRect(incoming), bounds); } - await gesture.moveBy(Offset(240.0 * direction, 0)); - await tester.pump(const Duration(milliseconds: 16)); - await gesture.up(); - await tester.pumpAndSettle(); - expect(tester.getRect(outgoing), bounds); - expect(engine.snapshot.locator, before); - final turn = await tester.startGesture(bounds.center); - await turn.moveBy(Offset(-30.0 * direction, 0)); - await tester.pump(); - await turn.moveBy(Offset(-bounds.width * .65 * direction, 0)); - await tester.pump(const Duration(milliseconds: 16)); - expect(engine.snapshot.locator, before); - await turn.up(); - await tester.pump(); - await tester.pump(const Duration(milliseconds: 16)); - expect(engine.snapshot.locator, before); - await tester.pumpAndSettle(); - expect( - (engine.snapshot.locator as EpubReaderLocator).spineIndex, - direction > 0 ? 1 : 0, - ); - expect(tester.getRect(incoming), bounds); - } - - expect(tester.takeException(), isNull); - }, - ); + expect(tester.takeException(), isNull); + }, + ); + } } - testWidgets('instant turns do not slide on commands or touch drags', ( - tester, - ) async { - final engine = testEpubEngine(); - await engine.load( - ReaderDocument( - id: 'instant', - format: ReaderFormat.epub, - loadBytes: () async => syntheticEpub(longChapter: true), - ), - preferences: const ReaderPreferences(), - ); - await tester.pumpWidget( - MaterialApp(home: Builder(builder: engine.buildViewport)), - ); - await tester.pumpAndSettle(); - await pumpReaderCommand(tester, engine.goNext()); - final controller = tester - .widget(find.byType(PageView)) - .controller!; - final location = engine.locator; - final revision = engine.restorationRevision; - await engine.updatePreferences( - engine.preferences.copyWith(pageTurnAnimation: false), - ); - await tester.pump(); - expect(engine.restorationRevision, revision); - expect(engine.locator, location); - expect( - tester.widget(find.byType(PageView)).controller, - same(controller), - ); - final next = engine.goNext(); - await tester.pump(); - expect(controller.page, 2); - await next; - final gesture = await tester.startGesture( - tester.getCenter(find.byType(PageView)), - ); - await gesture.moveBy(const Offset(-150, 0)); - await tester.pump(const Duration(milliseconds: 16)); - expect(controller.page, 2, reason: 'No sliding while a finger is down'); - await gesture.up(); - await tester.pump(); - expect(controller.page, 3); - await tester.pumpAndSettle(); - await tester.drag(find.byType(PageView), const Offset(150, 0)); - await tester.pump(); - expect(controller.page, 2); - await tester.pumpAndSettle(); - expect(tester.takeException(), isNull); - }); + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + testWidgets('instant turns do not slide on commands or $kind drags', ( + tester, + ) async { + final engine = testEpubEngine(); + await engine.load( + ReaderDocument( + id: 'instant', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub(longChapter: true), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + await pumpReaderCommand(tester, engine.goNext()); + final controller = tester + .widget(find.byType(PageView)) + .controller!; + final location = engine.locator; + final revision = engine.restorationRevision; + await engine.updatePreferences( + engine.preferences.copyWith(pageTurnAnimation: false), + ); + await tester.pump(); + expect(engine.restorationRevision, revision); + expect(engine.locator, location); + expect( + tester.widget(find.byType(PageView)).controller, + same(controller), + ); + final next = engine.goNext(); + await tester.pump(); + expect(controller.page, 2); + await next; + final gesture = await tester.startGesture( + tester.getBottomLeft(find.byType(PageView)) + const Offset(10, -10), + kind: kind, + ); + await gesture.moveBy(const Offset(-150, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect(controller.page, 2, reason: 'No sliding while a finger is down'); + await gesture.up(); + await tester.pump(); + expect(controller.page, 3); + await tester.pumpAndSettle(); + await tester.dragFrom( + tester.getBottomLeft(find.byType(PageView)) + const Offset(10, -10), + const Offset(150, 0), + kind: kind, + ); + await tester.pump(); + expect(controller.page, 2); + await tester.pumpAndSettle(); + expect(tester.takeException(), isNull); + }); + } for (final (reducedMotion, pageTurnAnimation) in [ (false, true), @@ -218,59 +239,65 @@ void main() { ); } - for (final direction in [-1, 1]) { - testWidgets( - 'interrupted page animation records the visible page (direction $direction)', - (tester) async { - final engine = testEpubEngine(); - await engine.load( - ReaderDocument( - id: 'interrupted-turn', - format: ReaderFormat.epub, - loadBytes: () async => syntheticEpub(longChapter: true), - ), - preferences: const ReaderPreferences(), - ); - await tester.pumpWidget( - MaterialApp(home: Builder(builder: engine.buildViewport)), - ); - await tester.pumpAndSettle(); - await pumpReaderCommand(tester, engine.goNext()); - final controller = tester - .widget(find.byType(PageView)) - .controller!; - expect(controller.page, 1); - final before = engine.snapshot; - final turn = direction > 0 ? engine.goNext() : engine.goPrevious(); - await tester.pump(); - await tester.pump(); - await tester.pump(const Duration(milliseconds: 16)); - expect(controller.page, isNot(1)); - expect((controller.page! - 1).abs(), lessThan(.5)); - final gesture = await tester.startGesture( - tester.getCenter(find.byType(PageView)), - ); - await gesture.moveBy(Offset(40.0 * direction, 0)); - await tester.pump(const Duration(milliseconds: 200)); - await gesture.up(); - await pumpReaderCommand(tester, turn); - expect(controller.page, 1); - expect(engine.snapshot.locator, before.locator); - expect(engine.snapshot.locationLabel, before.locationLabel); - expect( - engine.snapshot.coverage.single.start, - before.coverage.single.start, - ); - expect(engine.snapshot.coverage.single.end, before.coverage.single.end); - await pumpReaderCommand(tester, engine.goNext()); - expect( - controller.page, - 2, - reason: 'The next command must not skip a page', - ); - expect(tester.takeException(), isNull); - }, - ); + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + for (final direction in [-1, 1]) { + testWidgets( + 'interrupted $kind page animation records the visible page (direction $direction)', + (tester) async { + final engine = testEpubEngine(); + await engine.load( + ReaderDocument( + id: 'interrupted-turn', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub(longChapter: true), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + await pumpReaderCommand(tester, engine.goNext()); + final controller = tester + .widget(find.byType(PageView)) + .controller!; + expect(controller.page, 1); + final before = engine.snapshot; + final turn = direction > 0 ? engine.goNext() : engine.goPrevious(); + await tester.pump(); + await tester.pump(); + await tester.pump(const Duration(milliseconds: 16)); + expect(controller.page, isNot(1)); + expect((controller.page! - 1).abs(), lessThan(.5)); + final gesture = await tester.startGesture( + tester.getBottomLeft(find.byType(PageView)) + const Offset(10, -10), + kind: kind, + ); + await gesture.moveBy(Offset(40.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 200)); + await gesture.up(); + await pumpReaderCommand(tester, turn); + expect(controller.page, 1); + expect(engine.snapshot.locator, before.locator); + expect(engine.snapshot.locationLabel, before.locationLabel); + expect( + engine.snapshot.coverage.single.start, + before.coverage.single.start, + ); + expect( + engine.snapshot.coverage.single.end, + before.coverage.single.end, + ); + await pumpReaderCommand(tester, engine.goNext()); + expect( + controller.page, + 2, + reason: 'The next command must not skip a page', + ); + expect(tester.takeException(), isNull); + }, + ); + } } testWidgets('queued turns continue visually into a multipage destination', ( diff --git a/tool/browser/formats.mjs b/tool/browser/formats.mjs index 543469f..e9c0016 100644 --- a/tool/browser/formats.mjs +++ b/tool/browser/formats.mjs @@ -101,6 +101,41 @@ export async function checkFormats(browser, origin, reader) { } assert.ok(await next.isVisible(), `${format} reader did not become ready: ${await page.locator('body').innerText()}`); assert.ok(await next.isEnabled(), `${format} must have a readable next page`); + const previous = page.getByRole('button', { name: 'Previous', exact: true }); + const mouseSwipe = async direction => { + await page.mouse.click(20, 400); + await next.waitFor({ state: 'hidden' }); + await page.waitForTimeout(300); + // Start in the page margin so text selection retains its normal drag. + await page.mouse.move(direction > 0 ? 930 : 170, 400); + await page.mouse.down(); + await page.mouse.move(direction > 0 ? 170 : 930, 400, { steps: 18 }); + await page.mouse.up(); + await page.waitForTimeout(700); + await page.mouse.click(20, 400); + await previous.waitFor(); + }; + const location = async () => { + const counter = page.getByRole('button', { name: /^Page \d+ of \d+\. Go to page$/ }); + if (await counter.count()) { + const label = await counter.evaluate(element => element.getAttribute('aria-label') || element.textContent); + return `:${label.match(/Page (\d+) of/)[1]}`; + } + return page.getByRole('group').evaluateAll(elements => { + for (const element of elements) { + const label = element.getAttribute('aria-label') || element.textContent || ''; + const match = label.match(/^(?:Chapter (\d+) of .*? · )?Page (\d+) of/); + if (match) return `${match[1] ?? ''}:${match[2]}`; + } + return null; + }); + }; + const initial = await location(); + assert.ok(initial, `${format} must expose its committed location`); + await mouseSwipe(1); + assert.notEqual(await location(), initial, `${format} mouse drag must advance the committed page`); + await mouseSwipe(-1); + assert.equal(await location(), initial, `${format} reverse mouse drag must restore the initial page`); await next.click({ force: true }); await page.waitForTimeout(500); assert.ok(await page.getByRole('button', { name: 'Previous', exact: true }).isEnabled()); @@ -108,7 +143,7 @@ export async function checkFormats(browser, origin, reader) { await mkdir(process.env.PAPYRUS_SCREENSHOT_DIR, { recursive: true }); await page.screenshot({ path: resolve(process.env.PAPYRUS_SCREENSHOT_DIR, `format-${fixture?.replaceAll('/', '-') ?? format}.png`) }); } - console.log(`PASS: ${fixture ?? format} rendered viewport and navigation`); + console.log(`PASS: ${fixture ?? format} rendered viewport, mouse swipes, and navigation`); } assert.deepEqual(errors, []); } finally { await page.close(); } From 57a8375a9c87c5860d43339a2a0e8dd00998930f Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 18:39:15 +0200 Subject: [PATCH 06/19] fix: accept EPUB mouse swipes from outer window margins --- docs/ARCHITECTURE.md | 3 +- lib/src/engine/epub/epub_viewport.dart | 437 ++++++++++----------- test/presentation/epub_page_turn_test.dart | 54 +++ tool/browser/formats.mjs | 6 +- 4 files changed, 276 insertions(+), 224 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b8c0f73..b7b9cb3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -98,7 +98,8 @@ Controls and panels overlay the reading viewport so visibility changes do not repaginate content. Page-tap toggles exclude selections, links and competing pointer gestures. Keyboard focus survives chapter replacement without stealing focus from an open panel. Reduced motion changes transitions, not layout. -In paginated text formats, mouse drags starting in blank space turn pages; +In paginated text formats, mouse drags starting in blank space, including the +outer window margins, turn pages; drags starting on rendered text remain selection gestures. Mouse turns use the same page controller as touch and can interrupt an unfinished turn. diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index fdb86ca..f90e467 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -1050,82 +1050,78 @@ final class _EpubViewportState extends State { ) : SynchronousFuture(cached.pages); } - return Center( - child: SizedBox( - width: width, - child: FutureBuilder>( - future: _layout, - builder: (context, snapshot) { - if (snapshot.hasError && _pages.isEmpty) { - if (_layoutReady?.isCompleted == false) { - _layoutReady!.complete(); - } - _busy = false; - return ColoredBox( - color: preferences.backgroundColor, - child: Center( - child: Column( - mainAxisSize: MainAxisSize.min, - children: [ - Text( - 'Could not prepare these pages.', - style: TextStyle( - color: preferences.foregroundColor, - ), - ), - const SizedBox(height: 12), - FilledButton( - onPressed: () => - setState(() => _layoutKey = null), - child: const Text('Try again'), - ), - ], + return FutureBuilder>( + future: _layout, + builder: (context, snapshot) { + if (snapshot.hasError && _pages.isEmpty) { + if (_layoutReady?.isCompleted == false) { + _layoutReady!.complete(); + } + _busy = false; + return ColoredBox( + color: preferences.backgroundColor, + child: Center( + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Text( + 'Could not prepare these pages.', + style: TextStyle(color: preferences.foregroundColor), ), - ), - ); - } - final ready = - snapshot.connectionState == ConnectionState.done && - snapshot.hasData && - snapshot.data!.isNotEmpty; - - if (!ready && _pages.isEmpty) { - return const ReaderLoading(); - } - if (ready) { - _displayPreferences = preferences; - _displayColumns = _columns; - _restore(snapshot.data!, width); - } else if (snapshot.hasError) { - _busy = false; - _loadingTimer?.cancel(); - if (_layoutReady?.isCompleted == false) { - _layoutReady!.complete(); - } - } - - final pages = ready ? snapshot.data! : _pages; - final displayPreferences = ready - ? preferences - : _displayPreferences!; - final columns = ready ? _columns : _displayColumns; - Widget content; - if (displayPreferences.layoutMode == - ReaderLayoutMode.scroll) { - final heights = [ - for (final page in pages) - _pageHeight(page, displayPreferences), - ]; - var cumulative = 0.0; - _scrollOffsets = [ - for (final height in heights) - (() { - final start = cumulative; - cumulative += height; - return start; - })(), - ]; - content = ListView.custom( + const SizedBox(height: 12), + FilledButton( + onPressed: () => setState(() => _layoutKey = null), + child: const Text('Try again'), + ), + ], + ), + ), + ); + } + final ready = + snapshot.connectionState == ConnectionState.done && + snapshot.hasData && + snapshot.data!.isNotEmpty; + + if (!ready && _pages.isEmpty) { + return const ReaderLoading(); + } + if (ready) { + _displayPreferences = preferences; + _displayColumns = _columns; + _restore(snapshot.data!, width); + } else if (snapshot.hasError) { + _busy = false; + _loadingTimer?.cancel(); + if (_layoutReady?.isCompleted == false) { + _layoutReady!.complete(); + } + } + + final pages = ready ? snapshot.data! : _pages; + final displayPreferences = ready + ? preferences + : _displayPreferences!; + final columns = ready ? _columns : _displayColumns; + Widget content; + if (displayPreferences.layoutMode == ReaderLayoutMode.scroll) { + final heights = [ + for (final page in pages) + _pageHeight(page, displayPreferences), + ]; + var cumulative = 0.0; + _scrollOffsets = [ + for (final height in heights) + (() { + final start = cumulative; + cumulative += height; + return start; + })(), + ]; + content = Center( + child: SizedBox( + width: width, + child: ListView.custom( key: ValueKey(_scrollController), controller: _scrollController, itemExtentBuilder: (index, _) => heights[index], @@ -1138,42 +1134,45 @@ final class _EpubViewportState extends State { childCount: pages.length, extent: cumulative, ), - ); - } else { - final leading = _leadingPages; - final count = (pages.length / columns).ceil(); - final hasNext = - _layoutCache[_layoutKey]?.complete == true && - widget.engine.locator.spineIndex + 1 < - widget.engine.chapterCount; - _pageViewCount = leading + count + (hasNext ? 1 : 0); - content = NotificationListener( - onNotification: (notification) { - if (notification.depth == 0 && - !_commandTurning && - !_restoring && - !_busy) { - scheduleMicrotask(_settledPage); - } - return false; - }, - child: ReaderMousePageDrag( - controller: _pagesController, - animate: _animateTurns, - onTurn: _requestTurn, - canStart: (position) => - _selectedText.isEmpty && - !_fragments.any( - (fragment) => fragment - .rectangles( - 0, - fragment.widget.fragment.end - - fragment.widget.fragment.start, - ) - .any( - (rectangle) => rectangle.contains(position), - ), - ), + ), + ), + ); + } else { + final leading = _leadingPages; + final count = (pages.length / columns).ceil(); + final hasNext = + _layoutCache[_layoutKey]?.complete == true && + widget.engine.locator.spineIndex + 1 < + widget.engine.chapterCount; + _pageViewCount = leading + count + (hasNext ? 1 : 0); + content = NotificationListener( + onNotification: (notification) { + if (notification.depth == 0 && + !_commandTurning && + !_restoring && + !_busy) { + scheduleMicrotask(_settledPage); + } + return false; + }, + child: ReaderMousePageDrag( + controller: _pagesController, + animate: _animateTurns, + onTurn: _requestTurn, + canStart: (position) => + _selectedText.isEmpty && + !_fragments.any( + (fragment) => fragment + .rectangles( + 0, + fragment.widget.fragment.end - + fragment.widget.fragment.start, + ) + .any((rectangle) => rectangle.contains(position)), + ), + child: Center( + child: SizedBox( + width: width, child: PageView.builder( key: ValueKey(_pagesController), controller: _pagesController, @@ -1216,118 +1215,116 @@ final class _EpubViewportState extends State { }, ), ), - ); - } - final surface = ReaderHighlightInteraction( - hitTest: _highlightAt, - isSelecting: () => _selectedText.isNotEmpty, - child: Listener( - onPointerDown: (event) { - _swipe.start(event); - _startScroll = _scrollController.hasClients - ? _scrollController.offset - : 0; - }, - onPointerMove: _swipe.update, - onPointerCancel: _swipe.cancel, - onPointerUp: (event) { - final offset = _swipe.end(event); - - if (offset == null) { - return; - } - - final scrolling = - displayPreferences.layoutMode == - ReaderLayoutMode.scroll; - final drag = scrolling ? offset.dy : offset.dx; - final crossAxis = scrolling ? offset.dx : offset.dy; - - if (drag.abs() < 70 || drag.abs() <= crossAxis.abs()) { - return; - } - - if (scrolling && _scrollController.hasClients) { - final position = _scrollController.position; - - if (drag < 0 && - _startScroll >= position.maxScrollExtent - 1) { - _requestTurn(1); - } - - if (drag > 0 && _startScroll <= 1) { - _requestTurn(-1); - } - } else { - if (drag < 0 && !_animateTurns) { - _requestTurn(1); - } - - if (drag > 0 && !_animateTurns) { - _requestTurn(-1); - } - } - }, - child: - Localizations.of( - context, - MaterialLocalizations, - ) == - null - ? content - : SelectionArea( - key: _selectionKey, - contextMenuBuilder: _selectionMenu, - onSelectionChanged: (selection) { - final selected = - selection?.plainText.isNotEmpty ?? false; - _selectedText = selection?.plainText ?? ''; - if (!selected) { - _menuRevision++; - _menuBounds = null; - _selectionMenuController.remove(); - } - _swipe.selectionChanged(selected); - ReaderInteractionScope.maybeOf( - context, - )?.onSelectionChanged(selected); - }, - child: _SelectionStatusObserver( - onChanged: _selectionStatusChanged, - child: content, - ), - ), ), - ); - return Stack( - fit: StackFit.expand, - children: [ - IgnorePointer(ignoring: !ready, child: surface), - if (!ready && _showLoading && !snapshot.hasError) - const PositionedDirectional( - top: 8, - end: 8, - child: SizedBox( - width: 16, - height: 16, - child: CircularProgressIndicator(strokeWidth: 2), - ), - ), - if (snapshot.hasError) - Align( - alignment: Alignment.bottomCenter, - child: FilledButton( - onPressed: () => setState(() => _layoutKey = null), - child: const Text( - 'Could not prepare pages. Try again', - ), + ), + ); + } + final surface = ReaderHighlightInteraction( + hitTest: _highlightAt, + isSelecting: () => _selectedText.isNotEmpty, + child: Listener( + onPointerDown: (event) { + _swipe.start(event); + _startScroll = _scrollController.hasClients + ? _scrollController.offset + : 0; + }, + onPointerMove: _swipe.update, + onPointerCancel: _swipe.cancel, + onPointerUp: (event) { + final offset = _swipe.end(event); + + if (offset == null) { + return; + } + + final scrolling = + displayPreferences.layoutMode == + ReaderLayoutMode.scroll; + final drag = scrolling ? offset.dy : offset.dx; + final crossAxis = scrolling ? offset.dx : offset.dy; + + if (drag.abs() < 70 || drag.abs() <= crossAxis.abs()) { + return; + } + + if (scrolling && _scrollController.hasClients) { + final position = _scrollController.position; + + if (drag < 0 && + _startScroll >= position.maxScrollExtent - 1) { + _requestTurn(1); + } + + if (drag > 0 && _startScroll <= 1) { + _requestTurn(-1); + } + } else { + if (drag < 0 && !_animateTurns) { + _requestTurn(1); + } + + if (drag > 0 && !_animateTurns) { + _requestTurn(-1); + } + } + }, + child: + Localizations.of( + context, + MaterialLocalizations, + ) == + null + ? content + : SelectionArea( + key: _selectionKey, + contextMenuBuilder: _selectionMenu, + onSelectionChanged: (selection) { + final selected = + selection?.plainText.isNotEmpty ?? false; + _selectedText = selection?.plainText ?? ''; + if (!selected) { + _menuRevision++; + _menuBounds = null; + _selectionMenuController.remove(); + } + _swipe.selectionChanged(selected); + ReaderInteractionScope.maybeOf( + context, + )?.onSelectionChanged(selected); + }, + child: _SelectionStatusObserver( + onChanged: _selectionStatusChanged, + child: content, ), ), - ], - ); - }, - ), - ), + ), + ); + return Stack( + fit: StackFit.expand, + children: [ + IgnorePointer(ignoring: !ready, child: surface), + if (!ready && _showLoading && !snapshot.hasError) + const PositionedDirectional( + top: 8, + end: 8, + child: SizedBox( + width: 16, + height: 16, + child: CircularProgressIndicator(strokeWidth: 2), + ), + ), + if (snapshot.hasError) + Align( + alignment: Alignment.bottomCenter, + child: FilledButton( + onPressed: () => setState(() => _layoutKey = null), + child: const Text('Could not prepare pages. Try again'), + ), + ), + ], + ); + }, ); }, ), diff --git a/test/presentation/epub_page_turn_test.dart b/test/presentation/epub_page_turn_test.dart index 9519c04..95a9075 100644 --- a/test/presentation/epub_page_turn_test.dart +++ b/test/presentation/epub_page_turn_test.dart @@ -7,6 +7,60 @@ import '../support/in_process_epub_worker.dart'; import '../support/synthetic_epub.dart'; void main() { + for (final animation in [true, false]) { + testWidgets( + 'EPUB mouse turns start in outer window margins, animation $animation', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'outer-margins', + format: ReaderFormat.epub, + loadBytes: () async => + syntheticEpub(firstChapterBody: '

First page.

'), + ), + preferences: ReaderPreferences(pageTurnAnimation: animation), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + final bounds = tester.getRect(find.byType(PageView)); + expect(bounds.width, 800); + for (final direction in [1, -1]) { + final before = engine.locator; + final start = Offset(direction > 0 ? 1360 : 80, 450); + expect(bounds.contains(start), isFalse); + final gesture = await tester.startGesture( + start, + kind: PointerDeviceKind.mouse, + ); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + final pages = tester + .widget(find.byType(PageView)) + .controller!; + final position = pages.position.pixels; + await gesture.moveBy(Offset(-120.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect( + pages.position.pixels, + closeTo(position + (animation ? 120 * direction : 0), 1), + ); + expect(tester.getRect(find.byType(PageView)), bounds); + await gesture.moveBy(Offset(-450.0 * direction, 0)); + await gesture.up(); + await tester.pumpAndSettle(); + expect(engine.locator.spineIndex, before.spineIndex + direction); + } + expect(tester.takeException(), isNull); + }, + ); + } + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { for (final facing in [false, true]) { testWidgets( diff --git a/tool/browser/formats.mjs b/tool/browser/formats.mjs index e9c0016..4b6ffac 100644 --- a/tool/browser/formats.mjs +++ b/tool/browser/formats.mjs @@ -106,10 +106,10 @@ export async function checkFormats(browser, origin, reader) { await page.mouse.click(20, 400); await next.waitFor({ state: 'hidden' }); await page.waitForTimeout(300); - // Start in the page margin so text selection retains its normal drag. - await page.mouse.move(direction > 0 ? 930 : 170, 400); + // Start in the outer window margins, beyond the centered text column. + await page.mouse.move(direction > 0 ? 1040 : 60, 400); await page.mouse.down(); - await page.mouse.move(direction > 0 ? 170 : 930, 400, { steps: 18 }); + await page.mouse.move(direction > 0 ? 60 : 1040, 400, { steps: 18 }); await page.mouse.up(); await page.waitForTimeout(700); await page.mouse.click(20, 400); From 2602f5d85cfb963cf7908e38bd081385abef587f Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 19:57:31 +0200 Subject: [PATCH 07/19] feat: turn paginated books instantly with the scroll wheel --- docs/ARCHITECTURE.md | 4 + lib/src/engine/epub/epub_reader_engine.dart | 14 +- lib/src/engine/epub/epub_viewport.dart | 17 ++- lib/src/engine/pdf/pdf_facade.dart | 123 +++++++----------- lib/src/presentation/reader_page_wheel.dart | 92 +++++++++++++ test/presentation/epub_page_turn_test.dart | 52 ++++++++ test/presentation/pdf_tools_test.dart | 77 +++++++++++ test/presentation/reader_page_wheel_test.dart | 64 +++++++++ tool/browser/formats.mjs | 9 +- tool/browser/smoke.mjs | 13 +- 10 files changed, 377 insertions(+), 88 deletions(-) create mode 100644 lib/src/presentation/reader_page_wheel.dart create mode 100644 test/presentation/reader_page_wheel_test.dart diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b7b9cb3..adcc18f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -102,6 +102,10 @@ In paginated text formats, mouse drags starting in blank space, including the outer window margins, turn pages; drags starting on rendered text remain selection gestures. Mouse turns use the same page controller as touch and can interrupt an unfinished turn. +Wheel input turns paginated pages immediately without changing the animation +preference. Small nonzero deltas count as a turn; same-direction bursts are +limited to one turn per 120 ms, while reversing direction responds immediately. +Continuous readers, zoomed PDFs, and modifier-key zoom retain native wheel input. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_reader_engine.dart b/lib/src/engine/epub/epub_reader_engine.dart index be72e2a..a67eaff 100644 --- a/lib/src/engine/epub/epub_reader_engine.dart +++ b/lib/src/engine/epub/epub_reader_engine.dart @@ -72,7 +72,7 @@ final class EpubReaderEngine extends ReaderEngine { /// The viewport owns page turns, including transitions across spine items. /// The engine handles boundaries when no paginated viewport is mounted. - Future Function(int direction)? moveViewport; + Future Function(int direction, {required bool animate})? moveViewport; String get currentChapterHtml => _currentChapterHtml; List get blocks => _blocks; @@ -385,12 +385,12 @@ final class EpubReaderEngine extends ReaderEngine { } @override - Future goNext() => _queueTurn(1); + Future goNext() => turnPage(1); @override - Future goPrevious() => _queueTurn(-1); + Future goPrevious() => turnPage(-1); - Future _queueTurn(int direction) { - final turn = _turnQueue.then((_) => _move(direction)); + Future turnPage(int direction, {bool animate = true}) { + final turn = _turnQueue.then((_) => _move(direction, animate: animate)); _turnQueue = turn.catchError((Object _) {}); return turn; } @@ -446,14 +446,14 @@ final class EpubReaderEngine extends ReaderEngine { return chapter; } - Future _move(int direction) async { + Future _move(int direction, {required bool animate}) async { if (_locator == null) { throw const ReaderException( ReaderErrorCode.engineUnavailable, 'No EPUB document is loaded.', ); } - if (await moveViewport?.call(direction) ?? false) return; + if (await moveViewport?.call(direction, animate: animate) ?? false) return; final index = _locator!.spineIndex + direction; if (index < 0 || index >= _chapterCount) { throw const ReaderException( diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index f90e467..18dd17e 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -12,6 +12,7 @@ import '../../presentation/reader_interaction_scope.dart'; import '../../presentation/reader_loading.dart'; import '../../presentation/reader_swipe_tracker.dart'; import '../../presentation/reader_mouse_page_drag.dart'; +import '../../presentation/reader_page_wheel.dart'; import '../../presentation/reader_highlight_interaction.dart'; import '../../presentation/reader_text_toolbar.dart'; import 'epub_reader_engine.dart'; @@ -396,7 +397,7 @@ final class _EpubViewportState extends State { }); } - Future _move(int direction) async { + Future _move(int direction, {required bool animate}) async { await _boundaryCommit; while (_busy && mounted) { final ready = _layoutReady; @@ -450,7 +451,7 @@ final class _EpubViewportState extends State { final target = next + _leadingPages; _commandTurning = true; try { - if (_animateTurns) { + if (animate && _animateTurns) { await controller.animateToPage( target, duration: _turnDuration, @@ -484,7 +485,7 @@ final class _EpubViewportState extends State { return true; } - if (!_animateTurns) { + if (!animate || !_animateTurns) { controller.jumpToPage(next + _leadingPages); } else { await controller.animateToPage( @@ -1219,6 +1220,16 @@ final class _EpubViewportState extends State { ), ); } + content = ReaderPageWheel( + canTurn: () => + ready && + displayPreferences.layoutMode == ReaderLayoutMode.paginated, + onTurn: (direction) { + _selectionKey.currentState?.selectableRegion.clearSelection(); + return widget.engine.turnPage(direction, animate: false); + }, + child: content, + ); final surface = ReaderHighlightInteraction( hitTest: _highlightAt, isSelecting: () => _selectedText.isNotEmpty, diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index c599768..009d878 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -9,6 +9,7 @@ import 'package:pdfrx/pdfrx.dart'; import '../../domain/reader_types.dart'; import '../../domain/reader_selection.dart'; import '../../domain/reader_locator.dart'; +import '../../presentation/reader_page_wheel.dart'; import '../../presentation/reader_interaction_scope.dart'; import '../../presentation/reader_swipe_tracker.dart'; import '../../presentation/reader_highlight_interaction.dart'; @@ -510,7 +511,6 @@ final class _PdfrxFacade extends PdfReaderTools bool _disposed = false; Object? _viewKey; int _viewerRevision = 0; - DateTime? _lastWheelTurn; final _swipe = ReaderSwipeTracker(); bool _textSelected = false; PageController? _pagesController; @@ -623,6 +623,7 @@ final class _PdfrxFacade extends PdfReaderTools final step = config.facingPages ? 2 : 1; final target = (_pageIndex ~/ step) * step + direction * step; if (target < 0 || target >= pageCount) return; + await _controller.textSelectionDelegate.clearTextSelection(); await showPage(target, 0); if (_disposed) return; config.onPositionChanged?.call(target, 0); @@ -783,41 +784,6 @@ final class _PdfrxFacade extends PdfReaderTools } final viewer = Listener( - onPointerSignal: (event) { - if (configuration.layoutMode != ReaderLayoutMode.paginated || - event is! PointerScrollEvent || - _restoring || - !_atFit || - HardwareKeyboard.instance.isControlPressed || - HardwareKeyboard.instance.isMetaPressed) { - return; - } - final delta = - event.scrollDelta.dy.abs() >= event.scrollDelta.dx.abs() - ? event.scrollDelta.dy - : event.scrollDelta.dx; - if (delta.abs() < 10) return; - final now = DateTime.now(); - if (_lastWheelTurn != null && - now.difference(_lastWheelTurn!).inMilliseconds < 250) { - return; - } - _lastWheelTurn = now; - // Let pdfrx finish handling the wheel before snapping to the next row. - WidgetsBinding.instance.addPostFrameCallback((_) { - if (!_disposed && revision == _viewerRevision) { - final turn = ReaderInteractionScope.maybeOf( - context, - )?.onTurn; - if (turn != null) { - turn(delta > 0 ? 1 : -1); - } else { - _turnSpread(delta > 0 ? 1 : -1); - } - } - }); - WidgetsBinding.instance.scheduleFrame(); - }, onPointerDown: (event) { _swipe.start(event); _startLinkTap(event); @@ -1033,50 +999,57 @@ final class _PdfrxFacade extends PdfReaderTools } final pages = _pagesController; - return applyPdfBrightness( - preserveColors ? Brightness.light : configuration.brightness, - pages == null - ? buildViewer(0) - : Listener( - onPointerDown: _pagePointerDown, - onPointerUp: _pagePointerEnded, - onPointerCancel: _pagePointerEnded, - child: NotificationListener( - onNotification: (notification) { - if (notification.depth == 0) { - scheduleMicrotask(_settlePage); - } - return false; - }, - child: ScrollConfiguration( - behavior: ScrollConfiguration.of(context).copyWith( - // The incoming viewer is inactive until settlement. - // Its parent must still accept a mouse drag mid-turn. - dragDevices: { - ...ScrollConfiguration.of(context).dragDevices, - PointerDeviceKind.mouse, - }, - ), - child: PageView.builder( - key: ValueKey(pages), - controller: pages, - allowImplicitScrolling: true, - physics: _pagingEnabled - ? const ClampingScrollPhysics() - : const NeverScrollableScrollPhysics(), - itemCount: (pageCount / _spreadStep).ceil(), - itemBuilder: (context, index) => SizedBox.expand( - key: ValueKey(('pdf-spread', index)), - child: _PdfSpreadLoader( - pages: pages, - index: index, - builder: (_) => buildViewer(index), + return ReaderPageWheel( + canTurn: () => + configuration.layoutMode == ReaderLayoutMode.paginated && + !_restoring && + _atFit, + onTurn: _turnSpread, + child: applyPdfBrightness( + preserveColors ? Brightness.light : configuration.brightness, + pages == null + ? buildViewer(0) + : Listener( + onPointerDown: _pagePointerDown, + onPointerUp: _pagePointerEnded, + onPointerCancel: _pagePointerEnded, + child: NotificationListener( + onNotification: (notification) { + if (notification.depth == 0) { + scheduleMicrotask(_settlePage); + } + return false; + }, + child: ScrollConfiguration( + behavior: ScrollConfiguration.of(context).copyWith( + // The incoming viewer is inactive until settlement. + // Its parent must still accept a mouse drag mid-turn. + dragDevices: { + ...ScrollConfiguration.of(context).dragDevices, + PointerDeviceKind.mouse, + }, + ), + child: PageView.builder( + key: ValueKey(pages), + controller: pages, + allowImplicitScrolling: true, + physics: _pagingEnabled + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + itemCount: (pageCount / _spreadStep).ceil(), + itemBuilder: (context, index) => SizedBox.expand( + key: ValueKey(('pdf-spread', index)), + child: _PdfSpreadLoader( + pages: pages, + index: index, + builder: (_) => buildViewer(index), + ), ), ), ), ), ), - ), + ), ); }, ), diff --git a/lib/src/presentation/reader_page_wheel.dart b/lib/src/presentation/reader_page_wheel.dart new file mode 100644 index 0000000..f522514 --- /dev/null +++ b/lib/src/presentation/reader_page_wheel.dart @@ -0,0 +1,92 @@ +import 'dart:async'; + +import 'package:flutter/gestures.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter/widgets.dart'; + +import '../domain/reader_exception.dart'; + +/// Claims page-turn wheel signals before nested scrolling or PDF panning. +final class ReaderPageWheel extends StatefulWidget { + const ReaderPageWheel({ + required this.canTurn, + required this.onTurn, + required this.child, + super.key, + }); + + final bool Function() canTurn; + final Future Function(int direction) onTurn; + final Widget child; + + @override + State createState() => _ReaderPageWheelState(); +} + +final class _ReaderPageWheelState extends State { + Timer? _cooldown; + int? _direction; + Future _pending = Future.value(); + + void _signal(PointerSignalEvent event) { + if (event is! PointerScrollEvent || + !widget.canTurn() || + HardwareKeyboard.instance.isControlPressed || + HardwareKeyboard.instance.isMetaPressed) { + return; + } + + final delta = event.scrollDelta.dy.abs() >= event.scrollDelta.dx.abs() + ? event.scrollDelta.dy + : event.scrollDelta.dx; + if (delta == 0) return; + + GestureBinding.instance.pointerSignalResolver.register(event, (_) { + final direction = delta > 0 ? 1 : -1; + if (_cooldown?.isActive == true && direction == _direction) return; + _direction = direction; + _cooldown?.cancel(); + _cooldown = Timer(const Duration(milliseconds: 120), () {}); + _pending = _pending + .then((_) async { + if (mounted && widget.canTurn()) await widget.onTurn(direction); + }) + .catchError((Object error, StackTrace stack) { + if (error is ReaderException && + error.code == ReaderErrorCode.navigationBoundary) { + return; + } + FlutterError.reportError( + FlutterErrorDetails( + exception: error, + stack: stack, + library: 'papyrus_reader', + context: ErrorDescription( + 'while turning a page with the scroll wheel', + ), + ), + ); + }); + }); + } + + @override + void dispose() { + _cooldown?.cancel(); + super.dispose(); + } + + @override + Widget build(BuildContext context) => Stack( + fit: StackFit.expand, + children: [ + widget.child, + Positioned.fill( + child: Listener( + behavior: HitTestBehavior.translucent, + onPointerSignal: _signal, + ), + ), + ], + ); +} diff --git a/test/presentation/epub_page_turn_test.dart b/test/presentation/epub_page_turn_test.dart index 95a9075..d2a1afc 100644 --- a/test/presentation/epub_page_turn_test.dart +++ b/test/presentation/epub_page_turn_test.dart @@ -7,6 +7,58 @@ import '../support/in_process_epub_worker.dart'; import '../support/synthetic_epub.dart'; void main() { + testWidgets( + 'small EPUB wheel turns cross chapters instantly with animations enabled', + (tester) async { + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'wheel-chapters', + format: ReaderFormat.epub, + loadBytes: () async => + syntheticEpub(firstChapterBody: '

First page.

'), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + await tester.sendEventToBinding( + const PointerScrollEvent( + position: Offset(400, 300), + scrollDelta: Offset(0, -1), + ), + ); + await tester.pumpAndSettle(); + expect(engine.locator.spineIndex, 0); + expect(tester.takeException(), isNull); + for (final direction in [1, -1]) { + await tester.sendEventToBinding( + PointerScrollEvent( + position: const Offset(400, 300), + scrollDelta: Offset(0, direction.toDouble()), + ), + ); + for (var frame = 0; frame < 20; frame++) { + await tester.pump(const Duration(milliseconds: 16)); + final pages = tester + .widget(find.byType(PageView)) + .controller!; + expect( + pages.page, + closeTo(pages.page!.roundToDouble(), .000001), + reason: 'Wheel turns must never animate', + ); + } + expect(engine.locator.spineIndex, direction > 0 ? 1 : 0); + expect(engine.preferences.pageTurnAnimation, isTrue); + } + expect(tester.takeException(), isNull); + }, + ); + for (final animation in [true, false]) { testWidgets( 'EPUB mouse turns start in outer window margins, animation $animation', diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index 5cbde7c..5fd89ba 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -94,6 +94,83 @@ Future _navigate(WidgetTester tester, Future operation) async { } void main() { + testWidgets( + 'PDF wheel turns respond to a one-pixel delta and preserve zoomed panning', + (tester) async { + final bytes = await tester.runAsync(() => _document()); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'wheel-pdf'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + final original = tester + .widgetList(find.byType(PdfViewer)) + .firstWhere((viewer) => viewer.initialPageNumber == 1) + .controller!; + final page = original.document.pages.first; + final text = (await tester.runAsync(() => page.loadText()))!; + await tester.runAsync( + () => original.textSelectionDelegate.selectWord( + text.charRects.first.center.toOffsetInDocument( + page: page, + pageRect: original.layout.pageLayouts.first, + ), + ), + ); + await tester.pump(); + expect(original.textSelectionDelegate.hasSelectedText, isTrue); + for (final direction in [1, -1]) { + await tester.sendEventToBinding( + PointerScrollEvent( + position: const Offset(400, 300), + scrollDelta: Offset(0, direction.toDouble()), + ), + ); + await tester.pumpAndSettle(); + await _ready(tester, tools); + expect(tools.pageNumber, direction > 0 ? 2 : 1); + expect(original.textSelectionDelegate.hasSelectedText, isFalse); + expect( + tester.widget(find.byType(PageView)).physics, + isNot(isA()), + ); + expect( + tester.widget(find.byType(PageView)).controller!.page, + direction > 0 ? 1 : 0, + ); + } + await tools.setZoom(tools.zoom * 2); + await tester.pumpAndSettle(); + await tester.sendEventToBinding( + const PointerScrollEvent( + position: Offset(400, 300), + scrollDelta: Offset(0, 120), + ), + ); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { for (final direction in [1, -1]) { testWidgets( diff --git a/test/presentation/reader_page_wheel_test.dart b/test/presentation/reader_page_wheel_test.dart new file mode 100644 index 0000000..deb28a5 --- /dev/null +++ b/test/presentation/reader_page_wheel_test.dart @@ -0,0 +1,64 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:papyrus_reader/src/presentation/reader_page_wheel.dart'; + +void main() { + testWidgets( + 'small wheel turns win once, reverse promptly, and release zoom signals', + (tester) async { + final turns = []; + var nativeSignals = 0; + var canTurn = true; + await tester.pumpWidget( + MaterialApp( + home: ReaderPageWheel( + canTurn: () => canTurn, + onTurn: (direction) async => turns.add(direction), + child: Listener( + behavior: HitTestBehavior.opaque, + onPointerSignal: (event) => GestureBinding + .instance + .pointerSignalResolver + .register(event, (_) => nativeSignals++), + child: const SizedBox.expand(), + ), + ), + ), + ); + Future wheel(Offset delta) async { + await tester.sendEventToBinding( + PointerScrollEvent( + position: const Offset(400, 300), + scrollDelta: delta, + ), + ); + await tester.pump(); + } + + await wheel(const Offset(0, 1)); + await wheel(const Offset(0, 1)); + expect(turns, [1]); + expect(nativeSignals, 0); + await wheel(const Offset(0, -1)); + expect(turns, [1, -1]); + await tester.pump(const Duration(milliseconds: 120)); + await wheel(const Offset(-1, 0)); + expect(turns, [1, -1, -1]); + for (final key in [ + LogicalKeyboardKey.controlLeft, + LogicalKeyboardKey.metaLeft, + ]) { + await tester.sendKeyDownEvent(key); + await wheel(const Offset(0, 1)); + await tester.sendKeyUpEvent(key); + } + canTurn = false; + await wheel(const Offset(0, 1)); + expect(turns, [1, -1, -1]); + expect(nativeSignals, 3); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); +} diff --git a/tool/browser/formats.mjs b/tool/browser/formats.mjs index 4b6ffac..fede446 100644 --- a/tool/browser/formats.mjs +++ b/tool/browser/formats.mjs @@ -136,6 +136,13 @@ export async function checkFormats(browser, origin, reader) { assert.notEqual(await location(), initial, `${format} mouse drag must advance the committed page`); await mouseSwipe(-1); assert.equal(await location(), initial, `${format} reverse mouse drag must restore the initial page`); + await page.mouse.move(550, 400); + await page.mouse.wheel(0, 1); + await page.waitForTimeout(500); + assert.notEqual(await location(), initial, `${format} a small wheel movement must turn the page`); + await page.mouse.wheel(0, -1); + await page.waitForTimeout(500); + assert.equal(await location(), initial, `${format} reverse wheel input must restore the initial page`); await next.click({ force: true }); await page.waitForTimeout(500); assert.ok(await page.getByRole('button', { name: 'Previous', exact: true }).isEnabled()); @@ -143,7 +150,7 @@ export async function checkFormats(browser, origin, reader) { await mkdir(process.env.PAPYRUS_SCREENSHOT_DIR, { recursive: true }); await page.screenshot({ path: resolve(process.env.PAPYRUS_SCREENSHOT_DIR, `format-${fixture?.replaceAll('/', '-') ?? format}.png`) }); } - console.log(`PASS: ${fixture ?? format} rendered viewport, mouse swipes, and navigation`); + console.log(`PASS: ${fixture ?? format} rendered viewport, mouse swipes, wheel turns, and navigation`); } assert.deepEqual(errors, []); } finally { await page.close(); } diff --git a/tool/browser/smoke.mjs b/tool/browser/smoke.mjs index 3439a6d..c51fe28 100644 --- a/tool/browser/smoke.mjs +++ b/tool/browser/smoke.mjs @@ -195,12 +195,21 @@ try { 'A page turn keeps its place, while emphasis and meaning remain part of the story. ' + 'Resize the window or change the typeface to try reflow.', { exact: true }).first(); const beforeWheel = await paragraph.boundingBox(); + const location = page.getByRole('group', { name: /^Chapter \d+ of/ }).first(); + const beforeWheelLocation = await location.getAttribute('aria-label'); await page.mouse.move(160, 300); - await page.mouse.wheel(0, 600); + await page.mouse.wheel(0, 1); + await page.waitForFunction(previous => + document.querySelector('[aria-label^="Chapter "]')?.getAttribute('aria-label') !== previous, + beforeWheelLocation); + await page.mouse.wheel(0, -1); + await page.waitForFunction(previous => + document.querySelector('[aria-label^="Chapter "]')?.getAttribute('aria-label') === previous, + beforeWheelLocation); await settle(); const afterWheel = await paragraph.boundingBox(); assert.ok(beforeWheel && afterWheel && Math.abs(beforeWheel.y - afterWheel.y) < 1, - 'A normal paginated column must fit without hidden vertical overflow'); + 'A wheel turn and reversal must restore the same page geometry'); await openSettings(); await select('Slide', 'None'); await screenshot('desktop-instant-turns'); From 9fd9eefaf3c68b4bdede91ffafbab41f497bfc0d Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 20:23:50 +0200 Subject: [PATCH 08/19] fix: turn zoomed PDF pages at scroll boundaries --- docs/ARCHITECTURE.md | 5 +- lib/src/engine/epub/epub_viewport.dart | 2 +- lib/src/engine/pdf/pdf_facade.dart | 60 ++++++++-- lib/src/presentation/reader_page_wheel.dart | 8 +- test/presentation/pdf_tools_test.dart | 104 ++++++++++++++++++ test/presentation/reader_page_wheel_test.dart | 2 +- tool/browser/pdf_swipes.mjs | 35 ++++++ 7 files changed, 199 insertions(+), 17 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index adcc18f..4e246fe 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -105,7 +105,10 @@ same page controller as touch and can interrupt an unfinished turn. Wheel input turns paginated pages immediately without changing the animation preference. Small nonzero deltas count as a turn; same-direction bursts are limited to one turn per 120 ms, while reversing direction responds immediately. -Continuous readers, zoomed PDFs, and modifier-key zoom retain native wheel input. +Zoomed PDFs pan within the current spread; scrolling outward at its top or bottom +turns the page without animation. Forward turns open at the top, backward turns +at the bottom, preserving zoom. Horizontal zoomed panning, continuous readers, +and modifier-key zoom retain native wheel input. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index 18dd17e..86a852b 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -1221,7 +1221,7 @@ final class _EpubViewportState extends State { ); } content = ReaderPageWheel( - canTurn: () => + canTurn: (_) => ready && displayPreferences.layoutMode == ReaderLayoutMode.paginated, onTurn: (direction) { diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index 009d878..7eacd8d 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -527,7 +527,14 @@ final class _PdfrxFacade extends PdfReaderTools final List outline; @override - Future showPage(int pageIndex, double pageOffset) async { + Future showPage(int pageIndex, double pageOffset) => + _showPage(pageIndex, pageOffset); + + Future _showPage( + int pageIndex, + double pageOffset, { + bool alignBottom = false, + }) async { final previous = _captureView(); _pageOffset = pageOffset; if (!await _activatePage(pageIndex)) return; @@ -539,7 +546,10 @@ final class _PdfrxFacade extends PdfReaderTools _savedView = null; _restoring = true; try { - await _restorePage(zoomOverride: previous?.zoom); + await _restorePage( + zoomOverride: previous?.zoom, + alignBottom: alignBottom, + ); } finally { _restoring = false; } @@ -562,6 +572,23 @@ final class _PdfrxFacade extends PdfReaderTools bool get _atFit => _controller.isReady && _controller.currentZoom <= _fitZoom * 1.02; + bool _canTurnWithWheel(Offset delta) { + if (_disposed || + _restoring || + _configuration?.layoutMode != ReaderLayoutMode.paginated || + !_controller.isReady) { + return false; + } + if (_atFit) return true; + if (delta.dy.abs() <= delta.dx.abs()) return false; + + final visible = _controller.visibleRect; + final tolerance = 1 / zoom; + return delta.dy < 0 + ? visible.top <= _spread.top + tolerance + : visible.bottom >= _spread.bottom - tolerance; + } + double _zoomFor(PdfFitMode mode) => switch (mode) { PdfFitMode.page => _fitZoom, PdfFitMode.width => _controller.viewSize.width / _spread.width, @@ -571,6 +598,7 @@ final class _PdfrxFacade extends PdfReaderTools Future _restorePage({ bool restoreLocation = false, double? zoomOverride, + bool alignBottom = false, }) async { final config = _configuration; if (config == null) return; @@ -585,7 +613,12 @@ final class _PdfrxFacade extends PdfReaderTools final page = _controller.layout.pageLayouts[_pageIndex]; final saved = _savedView; final Offset center; - if (!_preferInitialLocator && + if (alignBottom) { + center = Offset( + _spread.center.dx, + _spread.bottom - _controller.viewSize.height / (2 * scale), + ); + } else if (!_preferInitialLocator && saved != null && saved.pageIndex == _pageIndex && (restoreLocation || _fitMode != PdfFitMode.page)) { @@ -615,7 +648,7 @@ final class _PdfrxFacade extends PdfReaderTools } } - Future _turnSpread(int direction) async { + Future _turnSpread(int direction, {bool fromWheel = false}) async { final config = _configuration; if (_disposed || _restoring || config == null || !_controller.isReady) { return; @@ -624,9 +657,17 @@ final class _PdfrxFacade extends PdfReaderTools final target = (_pageIndex ~/ step) * step + direction * step; if (target < 0 || target >= pageCount) return; await _controller.textSelectionDelegate.clearTextSelection(); - await showPage(target, 0); + final alignBottom = fromWheel && direction < 0 && !_atFit; + await _showPage(target, 0, alignBottom: alignBottom); if (_disposed) return; - config.onPositionChanged?.call(target, 0); + final page = _controller.layout.pageLayouts[target]; + final offset = alignBottom + ? ((_controller.visibleRect.top - page.top) / page.height).clamp( + 0.0, + 1.0, + ) + : 0.0; + config.onPositionChanged?.call(target, offset); if (config.onPositionChanged == null) config.onPageChanged(target); } @@ -1000,11 +1041,8 @@ final class _PdfrxFacade extends PdfReaderTools final pages = _pagesController; return ReaderPageWheel( - canTurn: () => - configuration.layoutMode == ReaderLayoutMode.paginated && - !_restoring && - _atFit, - onTurn: _turnSpread, + canTurn: _canTurnWithWheel, + onTurn: (direction) => _turnSpread(direction, fromWheel: true), child: applyPdfBrightness( preserveColors ? Brightness.light : configuration.brightness, pages == null diff --git a/lib/src/presentation/reader_page_wheel.dart b/lib/src/presentation/reader_page_wheel.dart index f522514..56f34bd 100644 --- a/lib/src/presentation/reader_page_wheel.dart +++ b/lib/src/presentation/reader_page_wheel.dart @@ -15,7 +15,7 @@ final class ReaderPageWheel extends StatefulWidget { super.key, }); - final bool Function() canTurn; + final bool Function(Offset delta) canTurn; final Future Function(int direction) onTurn; final Widget child; @@ -30,7 +30,7 @@ final class _ReaderPageWheelState extends State { void _signal(PointerSignalEvent event) { if (event is! PointerScrollEvent || - !widget.canTurn() || + !widget.canTurn(event.scrollDelta) || HardwareKeyboard.instance.isControlPressed || HardwareKeyboard.instance.isMetaPressed) { return; @@ -49,7 +49,9 @@ final class _ReaderPageWheelState extends State { _cooldown = Timer(const Duration(milliseconds: 120), () {}); _pending = _pending .then((_) async { - if (mounted && widget.canTurn()) await widget.onTurn(direction); + if (mounted && widget.canTurn(event.scrollDelta)) { + await widget.onTurn(direction); + } }) .catchError((Object error, StackTrace stack) { if (error is ReaderException && diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index 5fd89ba..0ade33d 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -171,6 +171,110 @@ void main() { }, ); + for (final facingPages in [false, true]) { + testWidgets( + 'zoomed PDF wheel pans and turns at spread edges, facing $facingPages', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(() => _document(pageCount: 5)); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'zoomed-wheel'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + var reportedOffset = 0.0; + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: facingPages, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + onPositionChanged: (_, offset) => reportedOffset = offset, + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + await tools.setZoom(tools.zoom * 3); + await tester.pumpAndSettle(); + final zoom = tools.zoom; + PdfViewerController controller() => tester + .widgetList(find.byType(PdfViewer)) + .firstWhere( + (viewer) => viewer.initialPageNumber == tools.pageNumber, + ) + .controller!; + Rect spread() => pdfSpreadRect( + controller().layout, + tools.pageNumber - 1, + facingPages, + ); + Future wheel(Offset delta) async { + await tester.sendEventToBinding( + PointerScrollEvent( + position: const Offset(720, 450), + scrollDelta: delta, + ), + ); + await tester.pumpAndSettle(); + await _ready(tester, tools); + await tester.pump(const Duration(milliseconds: 120)); + } + + Future pan(double distance) async { + await tools.scrollVertically(distance); + await tester.pumpAndSettle(); + } + + final before = controller().visibleRect.top; + await wheel(const Offset(0, 40)); + expect(tools.pageNumber, 1); + expect(controller().visibleRect.top, greaterThan(before)); + await pan(-100000); + await wheel(const Offset(0, -1)); + expect(tools.pageNumber, 1, reason: 'The first page is a boundary'); + await pan(100000); + await wheel(const Offset(40, 0)); + expect( + tools.pageNumber, + 1, + reason: 'Horizontal zoomed input still pans', + ); + await wheel(const Offset(0, 1)); + expect(tools.pageNumber, facingPages ? 3 : 2); + expect(tools.zoom, closeTo(zoom, .001)); + expect(controller().visibleRect.top, closeTo(spread().top, .01)); + expect(reportedOffset, closeTo(0, .001)); + await wheel(const Offset(0, -1)); + expect(tools.pageNumber, 1); + expect(tools.zoom, closeTo(zoom, .001)); + expect(controller().visibleRect.bottom, closeTo(spread().bottom, .01)); + expect(reportedOffset, greaterThan(0)); + final bottom = controller().visibleRect.top; + await wheel(const Offset(0, -40)); + expect( + tools.pageNumber, + 1, + reason: 'Reverse input pans into the previous page', + ); + expect(controller().visibleRect.top, lessThan(bottom)); + await _navigate(tester, facade.showPage(4, 0)); + await pan(100000); + await wheel(const Offset(0, 1)); + expect(tools.pageNumber, 5, reason: 'The last page is a boundary'); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { for (final direction in [1, -1]) { testWidgets( diff --git a/test/presentation/reader_page_wheel_test.dart b/test/presentation/reader_page_wheel_test.dart index deb28a5..bf338a5 100644 --- a/test/presentation/reader_page_wheel_test.dart +++ b/test/presentation/reader_page_wheel_test.dart @@ -14,7 +14,7 @@ void main() { await tester.pumpWidget( MaterialApp( home: ReaderPageWheel( - canTurn: () => canTurn, + canTurn: (_) => canTurn, onTurn: (direction) async => turns.add(direction), child: Listener( behavior: HitTestBehavior.opaque, diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index 575dc48..e8f9490 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -160,6 +160,41 @@ try { assert.deepEqual(errors, []); console.log('PASS: desktop mouse hold, text selection, and reverse swipe'); } + await page.keyboard.press('Escape'); + const zoomControl = page.getByRole('button', { name: /^Zoom \d+ percent\. Set zoom$/ }); + await zoomControl.waitFor(); + await page.waitForTimeout(300); + const zoomBounds = await zoomControl.boundingBox(); + assert.ok(zoomBounds); + // Flutter's canvas routes the pointer past overlapping semantics nodes. + await page.mouse.click(zoomBounds.x + zoomBounds.width / 2, zoomBounds.y + zoomBounds.height / 2); + await page.getByRole('textbox', { name: 'Zoom percentage' }).fill('200'); + await page.getByRole('button', { name: 'Apply', exact: true }).click(); + await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + await page.keyboard.press('Escape'); + await page.mouse.move(width / 2, 450); + const wheel = async delta => { + await page.mouse.wheel(0, delta); + await page.waitForTimeout(400); + }; + await wheel(40); + await assertPage(5); + await wheel(100000); + await assertPage(5); + await wheel(1); + await assertPage(6); + await wheel(-1); + await assertPage(5); + await wheel(-40); + await assertPage(5); + await wheel(-100000); + await assertPage(5); + await wheel(-1); + await assertPage(4); + await page.keyboard.press('Escape'); + await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + assert.deepEqual(errors, []); + console.log(`PASS: ${width}px zoomed PDF wheel pans within pages and turns at both edges`); await page.close(); } } finally { From cae0fce23b60039eda08a0426c1ddc429b6eb1a3 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 20:30:37 +0200 Subject: [PATCH 09/19] fix: allow mouse page swipes in zoomed PDFs --- docs/ARCHITECTURE.md | 5 +- lib/src/engine/pdf/pdf_facade.dart | 31 ++- test/presentation/pdf_tools_test.dart | 259 ++++++++++++++++---------- tool/browser/pdf_swipes.mjs | 32 +++- 4 files changed, 219 insertions(+), 108 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4e246fe..db7e603 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -78,7 +78,10 @@ Speculative viewers initialize while paging is stationary; visible destinations can load immediately. Paginated viewers share layout until viewport or page dimensions change, and preview images use stable resolution steps sized for the screen, up to the renderer's one-pass limit. Holding an in-flight turn does not -commit or snap its location. +commit or snap its location. Horizontal mouse drags turn pages at custom zoom, +while vertical drags pan and text drags select. During a mouse turn the PDF keeps +its horizontal position inside the moving spread; the viewer does not also pan. +Zoomed touch gestures retain document panning and pinch zoom. The host persists the synchronized locator separately from `PdfViewState`, which is device-local view configuration. `ReaderDocument.initialPdfView` and diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index 7eacd8d..a84c18d 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -337,6 +337,7 @@ final class _PdfrxFacade extends PdfReaderTools Future setZoom(double value) async { if (!isReady || !value.isFinite) return; _fitMode = PdfFitMode.custom; + _mousePanX = null; await _controller.setZoom( _controller.visibleRect.center, value.clamp(minimumZoom, maximumZoom), @@ -473,6 +474,7 @@ final class _PdfrxFacade extends PdfReaderTools }); Future _activatePage(int index) async { + _mousePanX = null; final hadFocus = _controller.isReady && (_controller.focusNode?.hasFocus ?? false); _pageIndex = index; @@ -517,6 +519,8 @@ final class _PdfrxFacade extends PdfReaderTools Drag? _pageDrag; bool _pagingEnabled = false; final Set _pagePointers = {}; + PointerDownEvent? _pagePointerStart; + double? _mousePanX; bool _multiTouch = false; int get _spreadStep => _configuration?.facingPages == true ? 2 : 1; @@ -602,6 +606,7 @@ final class _PdfrxFacade extends PdfReaderTools }) async { final config = _configuration; if (config == null) return; + _mousePanX = null; _fitMode ??= config.layoutMode == ReaderLayoutMode.paginated ? PdfFitMode.page : PdfFitMode.width; @@ -802,7 +807,6 @@ final class _PdfrxFacade extends PdfReaderTools configuration.pageTurnAnimation && !MediaQuery.disableAnimationsOf(context) && !_restoring && - _atFit && !_textSelected && !_multiTouch; Widget buildViewer(int index) { @@ -917,6 +921,8 @@ final class _PdfrxFacade extends PdfReaderTools margin: params.margin, ) : null, + panX: () => + active() && !_applyingView ? _mousePanX : null, onInteractionStart: _startPageDrag, onInteractionUpdate: _updatePageDrag, onInteractionEnd: _endPageDrag, @@ -1049,6 +1055,7 @@ final class _PdfrxFacade extends PdfReaderTools ? buildViewer(0) : Listener( onPointerDown: _pagePointerDown, + onPointerSignal: (_) => _mousePanX = null, onPointerUp: _pagePointerEnded, onPointerCancel: _pagePointerEnded, child: NotificationListener( @@ -1063,7 +1070,8 @@ final class _PdfrxFacade extends PdfReaderTools // The incoming viewer is inactive until settlement. // Its parent must still accept a mouse drag mid-turn. dragDevices: { - ...ScrollConfiguration.of(context).dragDevices, + if (!_restoring && _atFit) + ...ScrollConfiguration.of(context).dragDevices, PointerDeviceKind.mouse, }, ), @@ -1096,6 +1104,10 @@ final class _PdfrxFacade extends PdfReaderTools void _pagePointerDown(PointerDownEvent event) { _pagePointers.add(event.pointer); + if (_pagePointers.length == 1) { + _pagePointerStart = event; + _mousePanX = null; + } if (_pagePointers.length > 1 && !_multiTouch) { _multiTouch = true; _pageDrag?.cancel(); @@ -1117,6 +1129,10 @@ final class _PdfrxFacade extends PdfReaderTools } void _startPageDrag(ScaleStartDetails details) { + final start = _pagePointerStart; + final mouse = + details.pointerCount == 1 && start?.kind == PointerDeviceKind.mouse; + _mousePanX = null; final pages = _pagesController; if (!_pagingEnabled || pages == null || @@ -1124,6 +1140,14 @@ final class _PdfrxFacade extends PdfReaderTools details.pointerCount != 1) { return; } + // The page controller owns horizontal mouse motion, including its fling. + // Keep the zoomed document still inside its moving page slot. + _mousePanX = mouse ? _controller.visibleRect.center.dx : null; + if (!_atFit) { + if (!mouse) return; + final delta = details.focalPoint - start!.position; + if (delta.dx.abs() <= delta.dy.abs()) return; + } _pageDrag = pages.position.drag( DragStartDetails(globalPosition: details.focalPoint), () => _pageDrag = null, @@ -1443,6 +1467,7 @@ PdfViewerParams buildPdfViewerParams( ValueChanged? onLink, PdfViewerOverlaysBuilder? viewerOverlayBuilder, PdfViewerGeneralTapHandler? onGeneralTap, + double? Function()? panX, GestureScaleStartCallback? onInteractionStart, GestureScaleUpdateCallback? onInteractionUpdate, GestureScaleEndCallback? onInteractionEnd, @@ -1581,7 +1606,7 @@ PdfViewerParams buildPdfViewerParams( return controller.calcMatrixFor( Offset( clampCenter( - visible.center.dx, + panX?.call() ?? visible.center.dx, rect.left, rect.right, viewSize.width / (2 * zoom), diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index 0ade33d..f2f6a5f 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -233,6 +233,34 @@ void main() { await tester.pumpAndSettle(); } + for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + await pan(-100000); + final top = controller().visibleRect.top; + final drag = await tester.startGesture( + const Offset(720, 450), + kind: kind, + ); + await tester.pump(); + await drag.moveBy(const Offset(0, -30)); + await tester.pump(); + await drag.moveBy(const Offset(0, -100)); + await tester.pump(); + expect(tools.pageNumber, 1); + expect(controller().visibleRect.top, greaterThan(top)); + await drag.up(); + await tester.pumpAndSettle(); + } + final left = controller().visibleRect.left; + final touch = await tester.startGesture(const Offset(720, 450)); + await touch.moveBy(const Offset(-30, 0)); + await tester.pump(); + await touch.moveBy(const Offset(-100, 0)); + await tester.pump(); + expect(tools.pageNumber, 1, reason: 'Zoomed touch drags still pan'); + expect(controller().visibleRect.left, greaterThan(left)); + await touch.up(); + await tester.pumpAndSettle(); + await pan(-100000); final before = controller().visibleRect.top; await wheel(const Offset(0, 40)); expect(tools.pageNumber, 1); @@ -275,10 +303,14 @@ void main() { ); } - for (final kind in [PointerDeviceKind.touch, PointerDeviceKind.mouse]) { + for (final (kind, zoomed) in [ + (PointerDeviceKind.touch, false), + (PointerDeviceKind.mouse, false), + (PointerDeviceKind.mouse, true), + ]) { for (final direction in [1, -1]) { testWidgets( - 'PDF $kind swipes can catch and continue a settling turn, direction $direction', + 'PDF $kind swipes can catch and continue a settling turn, direction $direction, zoomed $zoomed', (tester) async { final width = kind == PointerDeviceKind.mouse ? 1440.0 : 800.0; await tester.binding.setSurfaceSize(Size(width, 600)); @@ -308,6 +340,18 @@ void main() { ); await _ready(tester, tools); await tester.pumpAndSettle(); + if (zoomed) { + await tools.setZoom(tools.zoom * 3); + await tester.pumpAndSettle(); + } + final initialZoom = tools.zoom; + final original = tester + .widgetList(find.byType(PdfViewer)) + .firstWhere( + (viewer) => viewer.initialPageNumber == initialPage + 1, + ) + .controller!; + final originalCenter = original.visibleRect.center; var newViewers = 0; debugOnRebuildDirtyWidget = (element, builtOnce) { if (!builtOnce && element.widget is PdfViewer) newViewers++; @@ -329,6 +373,12 @@ void main() { 0, reason: 'Speculative viewers must not initialize during a swipe', ); + if (zoomed) { + expect( + original.visibleRect.center.dx, + closeTo(originalCenter.dx, .01), + ); + } await first.up(); await tester.pump(const Duration(milliseconds: 60)); expect(pages.position.isScrollingNotifier.value, isTrue); @@ -357,6 +407,7 @@ void main() { await second.up(); await tester.pumpAndSettle(); expect(tools.pageNumber, direction > 0 ? 3 : 4); + expect(tools.zoom, closeTo(initialZoom, .001)); expect(tools.canReturn, isTrue); await _navigate(tester, tools.returnToPrevious()); await tester.pumpAndSettle(); @@ -368,109 +419,115 @@ void main() { } } - testWidgets( - 'PDF mouse hold and release keeps navigation and selection alive', - (tester) async { - await tester.binding.setSurfaceSize(const Size(1440, 900)); - addTearDown(() => tester.binding.setSurfaceSize(null)); - final bytes = await tester.runAsync(() => _document()); - await tester.runAsync(initializePdfiumForTest); - final facade = (await tester.runAsync( - () => createPdfrxFacade(bytes!, sourceName: 'mouse-hold'), - ))!; - final tools = facade as PdfReaderTools; - addTearDown(() => (facade as DisposablePdfFacade).dispose()); - await tester.pumpWidget( - MaterialApp( - home: facade.buildViewport( - PdfViewportConfiguration( - pageIndex: 0, - facingPages: false, - backgroundColor: Colors.white, - brightness: Brightness.light, - layoutMode: ReaderLayoutMode.paginated, - onPageChanged: (_) {}, + for (final zoomed in [false, true]) { + testWidgets( + 'PDF mouse hold and release keeps navigation and selection alive, zoomed $zoomed', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(() => _document()); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'mouse-hold'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), ), ), - ), - ); - await _ready(tester, tools); - await tester.pumpAndSettle(); - final first = await tester.startGesture( - const Offset(1250, 450), - kind: PointerDeviceKind.mouse, - ); - await first.moveBy(const Offset(-30, 0)); - await tester.pump(); - await first.moveBy(const Offset(-900, 0)); - await tester.pump(const Duration(milliseconds: 80)); - await first.up(); - await tester.pump(const Duration(milliseconds: 60)); - final held = await tester.startGesture( - const Offset(1000, 450), - kind: PointerDeviceKind.mouse, - ); - await tester.pump(const Duration(seconds: 1)); - await held.up(); - await tester.pumpAndSettle(); - expect(tools.pageNumber, 2); + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + if (zoomed) { + await tools.setZoom(tools.zoom * 2); + await tester.pumpAndSettle(); + } + final first = await tester.startGesture( + const Offset(1250, 450), + kind: PointerDeviceKind.mouse, + ); + await first.moveBy(const Offset(-30, 0)); + await tester.pump(); + await first.moveBy(const Offset(-900, 0)); + await tester.pump(const Duration(milliseconds: 80)); + await first.up(); + await tester.pump(const Duration(milliseconds: 60)); + final held = await tester.startGesture( + const Offset(1000, 450), + kind: PointerDeviceKind.mouse, + ); + await tester.pump(const Duration(seconds: 1)); + await held.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 2); - final viewer = tester - .widgetList(find.byType(PdfViewer)) - .singleWhere((viewer) => viewer.initialPageNumber == 2); - final controller = viewer.controller!; - for ( - var attempt = 0; - attempt < 100 && !controller.document.pages[1].isLoaded; - attempt++ - ) { - await tester.runAsync( - () => Future.delayed(const Duration(milliseconds: 20)), + final viewer = tester + .widgetList(find.byType(PdfViewer)) + .singleWhere((viewer) => viewer.initialPageNumber == 2); + final controller = viewer.controller!; + for ( + var attempt = 0; + attempt < 100 && !controller.document.pages[1].isLoaded; + attempt++ + ) { + await tester.runAsync( + () => Future.delayed(const Duration(milliseconds: 20)), + ); + await tester.pump(const Duration(milliseconds: 20)); + } + final page = controller.document.pages[1]; + expect(page.isLoaded, isTrue); + final text = (await tester.runAsync(() => page.loadText()))!; + Offset character(int index) => controller.documentToGlobal( + text.charRects[index].center.toOffsetInDocument( + page: page, + pageRect: controller.layout.pageLayouts[1], + ), + )!; + final selection = await tester.startGesture( + character(0), + kind: PointerDeviceKind.mouse, ); - await tester.pump(const Duration(milliseconds: 20)); - } - final page = controller.document.pages[1]; - expect(page.isLoaded, isTrue); - final text = (await tester.runAsync(() => page.loadText()))!; - Offset character(int index) => controller.documentToGlobal( - text.charRects[index].center.toOffsetInDocument( - page: page, - pageRect: controller.layout.pageLayouts[1], - ), - )!; - final selection = await tester.startGesture( - character(0), - kind: PointerDeviceKind.mouse, - ); - await selection.moveTo(character(12)); - await tester.pump(); - await selection.up(); - await tester.pumpAndSettle(); - expect(controller.textSelectionDelegate.hasSelectedText, isTrue); - expect( - tools.pageNumber, - 2, - reason: 'Selecting text must not turn the page', - ); - await tester.tapAt( - const Offset(1200, 450), - kind: PointerDeviceKind.mouse, - ); - await tester.pumpAndSettle(); - final reverse = await tester.startGesture( - const Offset(190, 450), - kind: PointerDeviceKind.mouse, - ); - await reverse.moveBy(const Offset(30, 0)); - await tester.pump(); - await reverse.moveBy(const Offset(900, 0)); - await reverse.up(); - await tester.pumpAndSettle(); - expect(tools.pageNumber, 1); - expect(tester.takeException(), isNull); - await tester.pumpWidget(const SizedBox.shrink()); - }, - ); + await selection.moveTo(character(12)); + await tester.pump(); + await selection.up(); + await tester.pumpAndSettle(); + expect(controller.textSelectionDelegate.hasSelectedText, isTrue); + expect( + tools.pageNumber, + 2, + reason: 'Selecting text must not turn the page', + ); + await tester.tapAt( + const Offset(1200, 450), + kind: PointerDeviceKind.mouse, + ); + await tester.pumpAndSettle(); + final reverse = await tester.startGesture( + const Offset(190, 450), + kind: PointerDeviceKind.mouse, + ); + await reverse.moveBy(const Offset(30, 0)); + await tester.pump(); + await reverse.moveBy(const Offset(900, 0)); + await reverse.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } for (final initialZoom in [null, .5]) { testWidgets('PDF page pixels survive settling at zoom $initialZoom', ( diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index e8f9490..9a71572 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -69,8 +69,8 @@ try { await page.waitForTimeout(1500); const cdp = await page.context().newCDPSession(page); await cdp.send('Emulation.setCPUThrottlingRate', { rate: Number(process.env.PAPYRUS_PDF_CPU_RATE ?? 1) }); - const swipe = async (direction = 1) => { - const x = direction > 0 ? width * .97 : width * .03; + const swipe = async (direction = 1, inside = false) => { + const x = direction > 0 ? width * (inside ? .8 : .97) : width * (inside ? .2 : .03); const point = offset => [{ x: x - direction * offset, y: 350, id: 1 }]; if (input === 'mouse') { await page.mouse.move(x, 350); @@ -79,7 +79,7 @@ try { await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: point(0) }); } for (let step = 1; step <= 18; step++) { - const offset = step * width * .94 / 18; + const offset = step * width * (inside ? .7 : .94) / 18; if (input === 'mouse') { await page.mouse.move(x - direction * offset, 350); } else { @@ -195,6 +195,32 @@ try { await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); assert.deepEqual(errors, []); console.log(`PASS: ${width}px zoomed PDF wheel pans within pages and turns at both edges`); + if (input === 'mouse') { + await page.keyboard.press('Escape'); + for (let turn = 0; turn < 3; turn++) { + await swipe(1, true); + await page.waitForTimeout(70); + } + await page.waitForTimeout(700); + await assertPage(7); + await swipe(-1, true); + await page.waitForTimeout(700); + await assertPage(6); + const text = await page.getByText('Swipe page 6.', { exact: true }).boundingBox(); + assert.ok(text); + await page.mouse.move(text.x + 2, text.y + text.height / 2); + await page.mouse.down(); + await page.mouse.move(text.x + text.width - 2, text.y + text.height / 2, { steps: 12 }); + await page.mouse.up(); + await page.getByRole('button', { name: 'Copy', exact: true }).waitFor(); + await page.mouse.click(width * .9, 450); + await page.waitForTimeout(300); + await assertPage(6); + await page.keyboard.press('Escape'); + await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + assert.deepEqual(errors, []); + console.log('PASS: zoomed PDF rapid mouse drags, reverse turn, retained zoom, and text selection'); + } await page.close(); } } finally { From cf3cdae6ed3e637ba3a53ac1d75f48a628de3971 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 20:41:05 +0200 Subject: [PATCH 10/19] ui: show page appearance before link highlighting --- .../presentation/reader_settings_panel.dart | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/lib/src/presentation/reader_settings_panel.dart b/lib/src/presentation/reader_settings_panel.dart index 01c5471..6a1fe81 100644 --- a/lib/src/presentation/reader_settings_panel.dart +++ b/lib/src/presentation/reader_settings_panel.dart @@ -203,33 +203,6 @@ final class ReaderSettingsPanel extends StatelessWidget { : null, ), ], - if (capabilities.supportsLinkHighlighting) ...[ - const SizedBox(height: 12), - Theme( - data: Theme.of(context).copyWith( - splashFactory: NoSplash.splashFactory, - highlightColor: Colors.transparent, - hoverColor: Colors.transparent, - ), - child: SwitchListTile( - contentPadding: EdgeInsets.zero, - title: const Text('Highlight links'), - value: preferences.highlightLinks, - overlayColor: WidgetStateProperty.resolveWith((states) { - if (states.contains(WidgetState.pressed) || - !states.contains(WidgetState.focused)) { - return Colors.transparent; - } - - return null; - }), - onChanged: enabled - ? (value) => - _update(preferences.copyWith(highlightLinks: value)) - : null, - ), - ), - ], const SizedBox(height: 20), Text('Page appearance', style: Theme.of(context).textTheme.titleMedium), const SizedBox(height: 8), @@ -268,6 +241,33 @@ final class ReaderSettingsPanel extends StatelessWidget { ), ], ), + if (capabilities.supportsLinkHighlighting) ...[ + const SizedBox(height: 12), + Theme( + data: Theme.of(context).copyWith( + splashFactory: NoSplash.splashFactory, + highlightColor: Colors.transparent, + hoverColor: Colors.transparent, + ), + child: SwitchListTile( + contentPadding: EdgeInsets.zero, + title: const Text('Highlight links'), + value: preferences.highlightLinks, + overlayColor: WidgetStateProperty.resolveWith((states) { + if (states.contains(WidgetState.pressed) || + !states.contains(WidgetState.focused)) { + return Colors.transparent; + } + + return null; + }), + onChanged: enabled + ? (value) => + _update(preferences.copyWith(highlightLinks: value)) + : null, + ), + ), + ], ], ); final accessibleContent = Semantics( From dc59aad692b89b346dc9154b7a248e406c20066e Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 20:44:52 +0200 Subject: [PATCH 11/19] ui: choose page appearance from a dropdown --- .../presentation/reader_settings_panel.dart | 132 ++++++------------ test/presentation/papyrus_reader_test.dart | 36 +---- tool/browser/smoke.mjs | 9 +- 3 files changed, 55 insertions(+), 122 deletions(-) diff --git a/lib/src/presentation/reader_settings_panel.dart b/lib/src/presentation/reader_settings_panel.dart index 6a1fe81..6d0090f 100644 --- a/lib/src/presentation/reader_settings_panel.dart +++ b/lib/src/presentation/reader_settings_panel.dart @@ -35,6 +35,14 @@ final class ReaderSettingsPanel extends StatelessWidget { Widget build(BuildContext context) { final capabilities = snapshot.capabilities ?? const ReaderCapabilities(); final preferences = snapshot.preferences; + final appearance = switch (preferences) { + _ when preferences.brightness == Brightness.dark => _PageAppearance.night, + _ when preferences.backgroundColor == const Color(0xfff4ecd8) => + _PageAppearance.sepia, + _ when preferences.backgroundColor == const Color(0xffffffff) => + _PageAppearance.light, + _ => null, + }; final content = ListView( controller: scrollController, @@ -203,43 +211,33 @@ final class ReaderSettingsPanel extends StatelessWidget { : null, ), ], - const SizedBox(height: 20), - Text('Page appearance', style: Theme.of(context).textTheme.titleMedium), - const SizedBox(height: 8), - Wrap( - spacing: 8, - runSpacing: 8, - children: [ - _AppearancePreset( - label: 'Light', - selected: - preferences.brightness == Brightness.light && - preferences.backgroundColor == const Color(0xffffffff), - background: const Color(0xffffffff), - foreground: const Color(0xff1b1b1b), - brightness: Brightness.light, - enabled: enabled, - onSelected: _applyAppearance, - ), - _AppearancePreset( - label: 'Sepia', - selected: preferences.backgroundColor == const Color(0xfff4ecd8), - background: const Color(0xfff4ecd8), - foreground: const Color(0xff3d3527), - brightness: Brightness.light, - enabled: enabled, - onSelected: _applyAppearance, - ), - _AppearancePreset( - label: 'Night', - selected: preferences.brightness == Brightness.dark, - background: const Color(0xff151719), - foreground: const Color(0xffece7de), - brightness: Brightness.dark, - enabled: enabled, - onSelected: _applyAppearance, - ), + const SizedBox(height: 12), + DropdownButtonFormField<_PageAppearance>( + key: ValueKey(('reader-appearance', appearance)), + initialValue: appearance, + isExpanded: true, + decoration: const InputDecoration( + labelText: 'Page appearance', + border: OutlineInputBorder(), + ), + hint: const Text('Custom'), + items: [ + for (final preset in _PageAppearance.values) + DropdownMenuItem(value: preset, child: Text(preset.label)), ], + onChanged: enabled + ? (value) { + if (value != null) { + _update( + preferences.copyWith( + backgroundColor: value.background, + foregroundColor: value.foreground, + brightness: value.brightness, + ), + ); + } + } + : null, ), if (capabilities.supportsLinkHighlighting) ...[ const SizedBox(height: 12), @@ -292,20 +290,6 @@ final class ReaderSettingsPanel extends StatelessWidget { void _update(ReaderPreferences preferences) { onUpdatePreferences(preferences); } - - void _applyAppearance( - Color background, - Color foreground, - Brightness brightness, - ) { - _update( - snapshot.preferences.copyWith( - backgroundColor: background, - foregroundColor: foreground, - brightness: brightness, - ), - ); - } } final class _SettingSlider extends StatefulWidget { @@ -399,48 +383,20 @@ final class _SettingSliderState extends State<_SettingSlider> { } } -typedef _AppearanceChanged = - void Function(Color background, Color foreground, Brightness brightness); +enum _PageAppearance { + light('Light', Color(0xffffffff), Color(0xff1b1b1b), Brightness.light), + sepia('Sepia', Color(0xfff4ecd8), Color(0xff3d3527), Brightness.light), + night('Night', Color(0xff151719), Color(0xffece7de), Brightness.dark); -final class _AppearancePreset extends StatelessWidget { - const _AppearancePreset({ - required this.label, - required this.selected, - required this.background, - required this.foreground, - required this.brightness, - required this.enabled, - required this.onSelected, - }); + const _PageAppearance( + this.label, + this.background, + this.foreground, + this.brightness, + ); final String label; - final bool selected; final Color background; final Color foreground; final Brightness brightness; - final bool enabled; - final _AppearanceChanged onSelected; - - @override - Widget build(BuildContext context) { - final colors = Theme.of(context).colorScheme; - return ChoiceChip( - label: Text(label), - labelStyle: TextStyle( - color: selected ? colors.onSecondaryContainer : colors.onSurface, - ), - color: WidgetStateProperty.resolveWith( - (states) => states.contains(WidgetState.selected) - ? colors.secondaryContainer - : colors.surfaceContainerLow, - ), - checkmarkColor: colors.onSecondaryContainer, - side: BorderSide(color: colors.outlineVariant), - selected: selected, - avatar: CircleAvatar(backgroundColor: background), - onSelected: enabled - ? (_) => onSelected(background, foreground, brightness) - : null, - ); - } } diff --git a/test/presentation/papyrus_reader_test.dart b/test/presentation/papyrus_reader_test.dart index bbc7fc0..84c4c81 100644 --- a/test/presentation/papyrus_reader_test.dart +++ b/test/presentation/papyrus_reader_test.dart @@ -559,6 +559,7 @@ void main() { ('System', 'Monospace'), ('Paginated', 'Continuous scroll'), ('Single', 'Double'), + (brightness == Brightness.dark ? 'Night' : 'Light', 'Sepia'), ]) { await tester.ensureVisible(find.text(pair.$1).first); await tester.tap(find.text(pair.$1).first); @@ -622,10 +623,6 @@ void main() { theme.brightness, brightness == Brightness.light ? Brightness.dark : Brightness.light, ); - final rich = tester.widget( - find.descendant(of: label, matching: find.byType(RichText)), - ); - expect(rich.text.style!.color, theme.textTheme.titleMedium!.color); final dropdown = find.text('Paginated'); final dropdownText = tester.widget( find @@ -636,26 +633,6 @@ void main() { dropdownText.text.style!.color, theme.textTheme.titleMedium!.color, ); - for (final chip in tester.widgetList( - find.byType(ChoiceChip), - )) { - final label = find.text((chip.label as Text).data!); - final text = tester.widget( - find.descendant(of: label, matching: find.byType(RichText)).first, - ); - final foreground = text.text.style!.color!.computeLuminance(); - final background = chip.color!.resolve({ - if (chip.selected) WidgetState.selected, - })!.computeLuminance(); - final contrast = - (math.max(foreground, background) + .05) / - (math.min(foreground, background) + .05); - expect( - contrast, - greaterThanOrEqualTo(4.5), - reason: 'Every appearance option must stay readable', - ); - } await tester.pumpWidget(const SizedBox.shrink()); controller.dispose(); } @@ -677,17 +654,16 @@ void main() { await tester.pumpAndSettle(); await tester.tap(find.byTooltip('Reading settings')); await tester.pumpAndSettle(); - await tester.ensureVisible(find.text('Night')); - await tester.tap(find.text('Night')); + await tester.ensureVisible(find.text('Light').first); + await tester.tap(find.text('Light').first); + await tester.pumpAndSettle(); + await tester.tap(find.text('Night').last); await tester.pumpAndSettle(); final label = find.text('Page appearance'); final theme = Theme.of(tester.element(label)); expect(theme.brightness, Brightness.light); expect(controller.preferences.brightness, Brightness.dark); - final rich = tester.widget( - find.descendant(of: label, matching: find.byType(RichText)), - ); - expect(rich.text.style!.color, theme.textTheme.titleMedium!.color); + expect(find.text('Night'), findsWidgets); expect(tester.takeException(), isNull); }, ); diff --git a/tool/browser/smoke.mjs b/tool/browser/smoke.mjs index c51fe28..001eb44 100644 --- a/tool/browser/smoke.mjs +++ b/tool/browser/smoke.mjs @@ -158,10 +158,11 @@ try { await settle(); }; const appearance = async name => { - const chip = page.getByLabel(name, { exact: true }); - await click(chip); - await chip.waitForFunction(element => ['aria-checked', 'aria-pressed', 'aria-selected'] - .some(attribute => element.getAttribute(attribute) === 'true')); + await click(page.getByRole('button', { name: /Page appearance/ })); + const option = page.getByRole('menuitem', { name, exact: true }); + await click(option); + await option.waitFor({ state: 'hidden' }); + await page.getByRole('button', { name: new RegExp(`${name}.*Page appearance|Page appearance.*${name}`, 's') }).waitFor(); await settle(); }; const select = async (current, target) => { From 5bddd3b438cad65cd027c3e67b66c69a49b4906d Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 20:57:54 +0200 Subject: [PATCH 12/19] fix: repair continuous EPUB layout and chapter scrolling --- docs/ARCHITECTURE.md | 4 + lib/src/engine/epub/epub_rich_layout.dart | 28 +++- lib/src/engine/epub/epub_viewport.dart | 73 +++++---- test/presentation/epub_scroll_test.dart | 187 ++++++++++++++++++++++ tool/browser/smoke.mjs | 35 ++++ 5 files changed, 294 insertions(+), 33 deletions(-) create mode 100644 test/presentation/epub_scroll_test.dart diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index db7e603..a59a5a2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -112,6 +112,10 @@ Zoomed PDFs pan within the current spread; scrolling outward at its top or botto turns the page without animation. Forward turns open at the top, backward turns at the bottom, preserving zoom. Horizontal zoomed panning, continuous readers, and modifier-key zoom retain native wheel input. +Continuous EPUB uses a full-width scroll surface with centered text and a viewport-edge +scrollbar. Its chunk extents use the rendered fragment heights, including text reshaping +at paragraph cuts. Outward wheel input at a chapter edge opens the adjacent chapter; +backward navigation restores its bottom. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_rich_layout.dart b/lib/src/engine/epub/epub_rich_layout.dart index b7387e5..fedadbe 100644 --- a/lib/src/engine/epub/epub_rich_layout.dart +++ b/lib/src/engine/epub/epub_rich_layout.dart @@ -6,6 +6,7 @@ import 'package:flutter/widgets.dart'; import 'package:flutter/rendering.dart'; import '../../domain/reader_preferences.dart'; +import '../../domain/reader_types.dart'; import '../../domain/reader_selection.dart'; import '../../domain/reader_locator.dart'; import '../../presentation/reader_interaction_scope.dart'; @@ -224,6 +225,25 @@ Stream paginateEpub( textDirection: direction, textScaler: textScaler, )..layout(maxWidth: width); + EpubPageFragment fragment(int start, int end, double height) { + if (preferences.layoutMode != ReaderLayoutMode.scroll) { + return EpubPageFragment(block, start, end, height); + } + // A split paragraph is laid out as a new Text widget. Its final newline + // or reshaped runs can add a line that was absent from the original cut. + // Scroll extents must describe that rendered fragment, not the estimate. + final measured = TextPainter( + text: block.span(preferences, start: start, end: end), + textDirection: direction, + textScaler: textScaler, + )..layout(maxWidth: width); + try { + return EpubPageFragment(block, start, end, measured.height); + } finally { + measured.dispose(); + } + } + try { final lines = painter.computeLineMetrics(); final text = span.toPlainText(); @@ -253,9 +273,7 @@ Stream paginateEpub( ) .start; if (boundary > start) { - fragments.add( - EpubPageFragment(block, start, boundary, segmentHeight), - ); + fragments.add(fragment(start, boundary, segmentHeight)); start = boundary; } if (fragments.isNotEmpty) { @@ -267,9 +285,7 @@ Stream paginateEpub( segmentHeight += lineHeight; } if (start < text.length) { - fragments.add( - EpubPageFragment(block, start, text.length, segmentHeight), - ); + fragments.add(fragment(start, text.length, segmentHeight)); used += segmentHeight + spacing; } } finally { diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index 86a852b..c6b1d3e 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -668,6 +668,25 @@ final class _EpubViewportState extends State { ); } + bool _canTurnWithWheel(Offset delta) { + if (_busy || _restoring) return false; + if (widget.engine.preferences.layoutMode == ReaderLayoutMode.paginated) { + return true; + } + if (!_scrollController.hasClients || delta.dy.abs() <= delta.dx.abs()) { + return false; + } + final position = _scrollController.position; + return delta.dy < 0 + ? position.pixels <= position.minScrollExtent + 1 + : position.pixels >= position.maxScrollExtent - 1; + } + + Future _turnWithWheel(int direction) { + _selectionKey.currentState?.selectableRegion.clearSelection(); + return widget.engine.turnPage(direction, animate: false); + } + void _requestTurn(int direction) { final request = ReaderInteractionScope.maybeOf(context)?.onTurn; @@ -953,15 +972,19 @@ final class _EpubViewportState extends State { WidgetsBinding.instance.addPostFrameCallback((_) { if (mounted) widget.engine.viewportCoverageChanged(0, 0); }); - return EpubScrollViewport( - xhtml: widget.engine.currentChapterHtml, - preferences: preferences, - localProgression: widget.engine.locator.localProgression, - restorationRevision: widget.engine.restorationRevision, - renderer: widget.engine.renderer!, - controller: _scrollController, - onProgressChanged: (value) => - widget.engine.viewportPositionChanged(value), + return ReaderPageWheel( + canTurn: _canTurnWithWheel, + onTurn: _turnWithWheel, + child: EpubScrollViewport( + xhtml: widget.engine.currentChapterHtml, + preferences: preferences, + localProgression: widget.engine.locator.localProgression, + restorationRevision: widget.engine.restorationRevision, + renderer: widget.engine.renderer!, + controller: _scrollController, + onProgressChanged: (value) => + widget.engine.viewportPositionChanged(value), + ), ); } return ColoredBox( @@ -1119,23 +1142,24 @@ final class _EpubViewportState extends State { return start; })(), ]; - content = Center( - child: SizedBox( - width: width, - child: ListView.custom( - key: ValueKey(_scrollController), - controller: _scrollController, - itemExtentBuilder: (index, _) => heights[index], - childrenDelegate: _EpubScrollDelegate( - (context, index) => _page( + content = ListView.custom( + key: ValueKey(_scrollController), + controller: _scrollController, + itemExtentBuilder: (index, _) => heights[index], + childrenDelegate: _EpubScrollDelegate( + (context, index) => Align( + alignment: Alignment.topCenter, + child: SizedBox( + width: width, + child: _page( pages[index], displayPreferences, scroll: true, ), - childCount: pages.length, - extent: cumulative, ), ), + childCount: pages.length, + extent: cumulative, ), ); } else { @@ -1221,13 +1245,8 @@ final class _EpubViewportState extends State { ); } content = ReaderPageWheel( - canTurn: (_) => - ready && - displayPreferences.layoutMode == ReaderLayoutMode.paginated, - onTurn: (direction) { - _selectionKey.currentState?.selectableRegion.clearSelection(); - return widget.engine.turnPage(direction, animate: false); - }, + canTurn: (delta) => ready && _canTurnWithWheel(delta), + onTurn: _turnWithWheel, child: content, ); final surface = ReaderHighlightInteraction( diff --git a/test/presentation/epub_scroll_test.dart b/test/presentation/epub_scroll_test.dart new file mode 100644 index 0000000..55837b5 --- /dev/null +++ b/test/presentation/epub_scroll_test.dart @@ -0,0 +1,187 @@ +import 'dart:io'; + +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:papyrus_reader/papyrus_reader.dart'; +import 'package:papyrus_reader/src/engine/epub/worker/epub_processor.dart'; + +import '../support/in_process_epub_worker.dart'; +import '../support/synthetic_epub.dart'; + +void main() { + testWidgets('continuous EPUB scrolls in margins and crosses chapter edges', ( + tester, + ) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'continuous-chapters', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub(longChapter: true), + ), + preferences: const ReaderPreferences(layoutMode: ReaderLayoutMode.scroll), + ); + await tester.pumpWidget( + MaterialApp( + theme: ThemeData(platform: TargetPlatform.macOS), + home: Builder(builder: engine.buildViewport), + ), + ); + await tester.pumpAndSettle(); + ScrollController controller() => + tester.widget(find.byType(ListView)).controller!; + Future wheel(double delta, {double x = 20}) async { + await tester.sendEventToBinding( + PointerScrollEvent( + position: Offset(x, 450), + scrollDelta: Offset(0, delta), + ), + ); + await tester.pumpAndSettle(); + await tester.pump(const Duration(milliseconds: 120)); + } + + expect(tester.getSize(find.byType(ListView)).width, 1440); + expect(tester.getSize(find.byType(Scrollbar)).width, 1440); + await wheel(-1); + expect(engine.locator.spineIndex, 0); + await wheel(80); + expect(controller().offset, greaterThan(0)); + final before = controller().offset; + await wheel(80, x: 1420); + expect(controller().offset, greaterThan(before)); + expect(engine.locator.spineIndex, 0); + for (var chapter = 1; chapter < 3; chapter++) { + controller().jumpTo(controller().position.maxScrollExtent); + await tester.pumpAndSettle(); + await wheel(1, x: 1420); + expect(engine.locator.spineIndex, chapter); + expect(controller().offset, closeTo(0, 1)); + } + controller().jumpTo(controller().position.maxScrollExtent); + await tester.pumpAndSettle(); + await wheel(1); + expect(engine.locator.spineIndex, 2); + for (var chapter = 1; chapter >= 0; chapter--) { + controller().jumpTo(0); + await tester.pumpAndSettle(); + await wheel(-1); + expect(engine.locator.spineIndex, chapter); + expect( + controller().offset, + closeTo(controller().position.maxScrollExtent, 1), + ); + } + expect(tester.takeException(), isNull); + }); + + for (final scale in [1.0, 1.6]) { + testWidgets( + 'continuous line-break paragraphs do not overflow at scale $scale', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 700)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + final lines = List.generate( + 100, + (index) => + 'Line $index with italic text and more words.
', + ).join(); + await engine.load( + ReaderDocument( + id: 'continuous-line-breaks', + format: ReaderFormat.epub, + loadBytes: () async => + syntheticEpub(firstChapterBody: '

$lines

'), + ), + preferences: const ReaderPreferences( + layoutMode: ReaderLayoutMode.scroll, + fontSize: 24, + ), + ); + await tester.pumpWidget( + MaterialApp( + home: MediaQuery( + data: MediaQueryData(textScaler: TextScaler.linear(scale)), + child: Builder(builder: engine.buildViewport), + ), + ), + ); + await tester.pumpAndSettle(); + final controller = tester + .widget(find.byType(ListView)) + .controller!; + for ( + var offset = 0.0; + offset < controller.position.maxScrollExtent; + offset += 400 + ) { + controller.jumpTo(offset); + await tester.pumpAndSettle(); + expect(tester.takeException(), isNull); + } + }, + ); + } + + testWidgets( + 'Alice arithmetic and poem remain readable in continuous scroll', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 700)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = File( + 'test/fixtures/gutenberg/alice.epub', + ).readAsBytesSync(); + final processor = EpubProcessor(); + final metadata = await processor.dispatch('open', bytes); + int? chapter; + for (var index = 0; index < (metadata['count'] as int); index++) { + final content = await processor.dispatch('chapter', index); + if (content.toString().contains('four times five')) { + chapter = index; + break; + } + } + expect(chapter, isNotNull); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'alice-scroll', + format: ReaderFormat.epub, + loadBytes: () async => bytes, + ), + initialLocator: EpubReaderLocator( + spineIndex: chapter!, + localProgression: 0, + totalProgression: 0, + ), + preferences: const ReaderPreferences( + layoutMode: ReaderLayoutMode.scroll, + fontSize: 24, + ), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + final controller = tester + .widget(find.byType(ListView)) + .controller!; + for ( + var offset = 0.0; + offset < controller.position.maxScrollExtent; + offset += 450 + ) { + controller.jumpTo(offset); + await tester.pumpAndSettle(); + expect(tester.takeException(), isNull); + } + }, + ); +} diff --git a/tool/browser/smoke.mjs b/tool/browser/smoke.mjs index 001eb44..c2b5626 100644 --- a/tool/browser/smoke.mjs +++ b/tool/browser/smoke.mjs @@ -295,6 +295,41 @@ try { await page.getByRole('button', { name: 'Back', exact: true }).waitFor(); await settle(); await backToLibrary(); + const continuousBook = resolve(temp, 'continuous-scroll.epub'); + await writeFile(continuousBook, await readFile(resolve(reader, 'example/assets/reading_lab.epub'))); + await openFile(continuousBook); + await showInitialControls(page.getByText('At the Gate', { exact: true }).first()); + await openSettings(); + await select('Paginated', 'Continuous scroll'); + await closeSettings(); + await screenshot('epub-continuous-initial'); + const continuousParagraph = page.getByText(/^At the Gate/).first(); + let paragraphBounds = await continuousParagraph.boundingBox(); + assert.ok(paragraphBounds); + for (const x of [20, 1260]) { + await page.mouse.move(x, 450); + await page.mouse.wheel(0, 60); + await page.waitForTimeout(250); + await settle(); + const moved = await continuousParagraph.boundingBox(); + assert.ok(moved && moved.y + moved.height < paragraphBounds.y + paragraphBounds.height, + 'Wheel input in either outer margin must scroll the EPUB text'); + paragraphBounds = moved; + } + await screenshot('epub-continuous-full-width'); + await page.mouse.wheel(0, 100000); + await settle(); + await page.waitForTimeout(150); + await page.mouse.wheel(0, 1); + await page.getByRole('group', { name: /^Chapter 2 of 2/ }).first().waitFor(); + await settle(); + await page.mouse.wheel(0, -1); + await page.getByRole('group', { name: /^Chapter 1 of 2/ }).first().waitFor(); + await settle(); + await page.mouse.wheel(0, 1); + await page.getByRole('group', { name: /^Chapter 2 of 2/ }).first().waitFor(); + await settle(); + await backToLibrary(); await page.setViewportSize({ width: 700, height: 360 }); await click(page.getByRole('button', { name: 'Read PDF', exact: true })); From c01f6abc3253ff7f6e160c60c4293923239b6328 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 21:03:45 +0200 Subject: [PATCH 13/19] fix: cross continuous EPUB chapter edges with touch --- docs/ARCHITECTURE.md | 5 +- lib/src/engine/epub/epub_viewport.dart | 89 ++++++++++++++------ test/engine/epub_reader_engine_test.dart | 6 +- test/presentation/epub_scroll_test.dart | 101 +++++++++++++++++++++++ tool/browser/epub_scroll.mjs | 70 ++++++++++++++++ tool/browser/smoke.mjs | 2 + 6 files changed, 246 insertions(+), 27 deletions(-) create mode 100644 tool/browser/epub_scroll.mjs diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a59a5a2..977fa47 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -115,7 +115,10 @@ and modifier-key zoom retain native wheel input. Continuous EPUB uses a full-width scroll surface with centered text and a viewport-edge scrollbar. Its chunk extents use the rendered fragment heights, including text reshaping at paragraph cuts. Outward wheel input at a chapter edge opens the adjacent chapter; -backward navigation restores its bottom. +backward navigation restores its bottom. Touch drags can reach and continue beyond +an edge in one gesture, including under bouncing physics. Only a completed, +unselected single-touch gesture commits the adjacent chapter; inertial scrolling +and cancelled gestures do not trigger a chapter turn. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index c6b1d3e..7812a4a 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -62,6 +62,8 @@ final class _EpubViewportState extends State { !(MediaQuery.maybeOf(context)?.disableAnimations ?? false); double _startScroll = 0; + double _scrollBoundaryDrag = 0; + static const _scrollBoundaryThreshold = 48.0; bool _restoring = false; bool _busy = false; Completer? _layoutReady; @@ -410,6 +412,10 @@ final class _EpubViewportState extends State { if (widget.engine.preferences.layoutMode == ReaderLayoutMode.scroll) { if (!_scrollController.hasClients) return true; final position = _scrollController.position; + if ((direction > 0 && position.pixels >= position.maxScrollExtent - 1) || + (direction < 0 && position.pixels <= position.minScrollExtent + 1)) { + return false; + } final next = (position.pixels + direction * position.viewportDimension * .85) .clamp(0.0, position.maxScrollExtent); @@ -668,6 +674,28 @@ final class _EpubViewportState extends State { ); } + bool _trackScrollBoundary(ScrollNotification notification) { + if (notification.depth != 0 || notification.metrics.axis != Axis.vertical) { + return false; + } + if (notification is OverscrollNotification && + notification.dragDetails != null) { + final delta = notification.overscroll; + if (_scrollBoundaryDrag.sign != delta.sign) _scrollBoundaryDrag = 0; + _scrollBoundaryDrag += delta; + } else if (notification is ScrollUpdateNotification && + notification.dragDetails != null) { + final metrics = notification.metrics; + _scrollBoundaryDrag = + metrics.pixels - + metrics.pixels.clamp( + metrics.minScrollExtent, + metrics.maxScrollExtent, + ); + } + return false; + } + bool _canTurnWithWheel(Offset delta) { if (_busy || _restoring) return false; if (widget.engine.preferences.layoutMode == ReaderLayoutMode.paginated) { @@ -1142,24 +1170,28 @@ final class _EpubViewportState extends State { return start; })(), ]; - content = ListView.custom( - key: ValueKey(_scrollController), - controller: _scrollController, - itemExtentBuilder: (index, _) => heights[index], - childrenDelegate: _EpubScrollDelegate( - (context, index) => Align( - alignment: Alignment.topCenter, - child: SizedBox( - width: width, - child: _page( - pages[index], - displayPreferences, - scroll: true, + content = NotificationListener( + onNotification: _trackScrollBoundary, + child: ListView.custom( + key: ValueKey(_scrollController), + physics: const AlwaysScrollableScrollPhysics(), + controller: _scrollController, + itemExtentBuilder: (index, _) => heights[index], + childrenDelegate: _EpubScrollDelegate( + (context, index) => Align( + alignment: Alignment.topCenter, + child: SizedBox( + width: width, + child: _page( + pages[index], + displayPreferences, + scroll: true, + ), ), ), + childCount: pages.length, + extent: cumulative, ), - childCount: pages.length, - extent: cumulative, ), ); } else { @@ -1255,12 +1287,16 @@ final class _EpubViewportState extends State { child: Listener( onPointerDown: (event) { _swipe.start(event); + _scrollBoundaryDrag = 0; _startScroll = _scrollController.hasClients ? _scrollController.offset : 0; }, onPointerMove: _swipe.update, - onPointerCancel: _swipe.cancel, + onPointerCancel: (event) { + _swipe.cancel(event); + _scrollBoundaryDrag = 0; + }, onPointerUp: (event) { final offset = _swipe.end(event); @@ -1281,14 +1317,19 @@ final class _EpubViewportState extends State { if (scrolling && _scrollController.hasClients) { final position = _scrollController.position; - if (drag < 0 && - _startScroll >= position.maxScrollExtent - 1) { - _requestTurn(1); - } - - if (drag > 0 && _startScroll <= 1) { - _requestTurn(-1); - } + final next = + drag < 0 && + (_scrollBoundaryDrag >= _scrollBoundaryThreshold || + (_startScroll >= position.maxScrollExtent - 1 && + position.pixels >= + position.maxScrollExtent - 1)); + final previous = + drag > 0 && + (_scrollBoundaryDrag <= -_scrollBoundaryThreshold || + (_startScroll <= position.minScrollExtent + 1 && + position.pixels <= + position.minScrollExtent + 1)); + if (next || previous) _requestTurn(next ? 1 : -1); } else { if (drag < 0 && !_animateTurns) { _requestTurn(1); diff --git a/test/engine/epub_reader_engine_test.dart b/test/engine/epub_reader_engine_test.dart index 60e6ede..448c0d8 100644 --- a/test/engine/epub_reader_engine_test.dart +++ b/test/engine/epub_reader_engine_test.dart @@ -740,7 +740,8 @@ void main() { await tester.pumpWidget(viewport()); await tester.pumpAndSettle(); - await tester.drag(find.byType(ListView), const Offset(0, -100000)); + final scroll = tester.widget(find.byType(ListView)).controller!; + scroll.jumpTo(scroll.position.maxScrollExtent); await tester.pumpAndSettle(); var locator = await engine.currentLocator() as EpubReaderLocator; @@ -757,7 +758,8 @@ void main() { await tester.pumpWidget(viewport()); await tester.pumpAndSettle(); - await tester.drag(find.byType(ListView), const Offset(0, -100000)); + final last = tester.widget(find.byType(ListView)).controller!; + last.jumpTo(last.position.maxScrollExtent); await tester.pumpAndSettle(); locator = await engine.currentLocator() as EpubReaderLocator; diff --git a/test/presentation/epub_scroll_test.dart b/test/presentation/epub_scroll_test.dart index 55837b5..beb072f 100644 --- a/test/presentation/epub_scroll_test.dart +++ b/test/presentation/epub_scroll_test.dart @@ -79,6 +79,107 @@ void main() { expect(tester.takeException(), isNull); }); + for (final platform in [TargetPlatform.android, TargetPlatform.iOS]) { + for (final short in [false, true]) { + testWidgets( + 'continuous EPUB touch crosses edges on $platform, short $short', + (tester) async { + await tester.binding.setSurfaceSize(const Size(390, 844)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'touch-chapters', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub( + longChapter: !short, + firstChapterBody: short ? '

Short first chapter.

' : null, + secondChapterBody: short + ? '

Short second chapter.

' + : null, + ), + ), + preferences: const ReaderPreferences( + layoutMode: ReaderLayoutMode.scroll, + ), + ); + await tester.pumpWidget( + MaterialApp( + theme: ThemeData(platform: platform), + home: Builder(builder: engine.buildViewport), + ), + ); + await tester.pumpAndSettle(); + ScrollController controller() => + tester.widget(find.byType(ListView)).controller!; + Future swipe(int direction, {bool cancel = false}) async { + final before = engine.locator.spineIndex; + final gesture = await tester.startGesture( + Offset(195, direction > 0 ? 600 : 250), + ); + for (final distance in [30.0, 100.0, 180.0]) { + await gesture.moveBy(Offset(0, -distance * direction)); + await tester.pump(const Duration(milliseconds: 40)); + } + expect( + engine.locator.spineIndex, + before, + reason: 'Only a completed gesture changes chapter', + ); + if (cancel) { + await gesture.cancel(); + } else { + await gesture.up(); + } + await tester.pumpAndSettle(); + } + + final maximum = controller().position.maxScrollExtent; + if (!short) { + controller().jumpTo(maximum - 300); + await tester.pumpAndSettle(); + await tester.fling( + find.byType(ListView), + const Offset(0, -100), + 2500, + ); + await tester.pumpAndSettle(); + expect( + engine.locator.spineIndex, + 0, + reason: 'Inertia alone must not skip a chapter', + ); + } + controller().jumpTo(short ? 0 : maximum - 80); + await tester.pumpAndSettle(); + await swipe(1); + expect(engine.locator.spineIndex, 1); + expect(controller().offset, closeTo(0, 1)); + controller().jumpTo(short ? 0 : 80); + await tester.pumpAndSettle(); + await swipe(-1); + expect(engine.locator.spineIndex, 0); + expect( + controller().offset, + closeTo(controller().position.maxScrollExtent, 1), + ); + await swipe(1, cancel: true); + expect(engine.locator.spineIndex, 0); + controller().jumpTo(0); + await tester.pumpAndSettle(); + await swipe(-1); + expect( + engine.locator.spineIndex, + 0, + reason: 'The beginning of the book stays in place', + ); + expect(tester.takeException(), isNull); + }, + ); + } + } + for (final scale in [1.0, 1.6]) { testWidgets( 'continuous line-break paragraphs do not overflow at scale $scale', diff --git a/tool/browser/epub_scroll.mjs b/tool/browser/epub_scroll.mjs new file mode 100644 index 0000000..47bf416 --- /dev/null +++ b/tool/browser/epub_scroll.mjs @@ -0,0 +1,70 @@ +import assert from 'node:assert/strict'; + +export async function checkMobileEpubScroll(browser, origin) { + const page = await browser.newPage({ + viewport: { width: 390, height: 844 }, + hasTouch: true, + isMobile: true, + }); + page.setDefaultTimeout(10000); + const errors = []; + page.on('pageerror', error => errors.push(error.message)); + try { + await page.goto(origin); + await page.locator('flt-semantics-placeholder').evaluate(element => element.click()); + const click = async control => { + await control.waitFor(); + await control.scrollIntoViewIfNeeded(); + await page.waitForTimeout(250); + const bounds = await control.boundingBox(); + assert.ok(bounds); + await page.touchscreen.tap(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2); + }; + await click(page.getByRole('button', { name: 'Explore layouts', exact: true })); + await page.getByText('At the Gate', { exact: true }).first().waitFor(); + await page.waitForTimeout(500); + await page.touchscreen.tap(195, 420); + const more = page.getByRole('button', { name: 'More reader actions', exact: true }); + if (await more.isVisible()) await click(more); + await click(page.getByRole('button', { name: 'Reading settings', exact: true })); + await click(page.getByRole('button', { name: /Paginated/ })); + await click(page.getByRole('menuitem', { name: 'Continuous scroll', exact: true })); + await click(page.getByRole('button', { name: 'Close panel', exact: true })); + const chapter = number => page.getByRole('group', { name: new RegExp(`^Chapter ${number} of 2`) }).first(); + await chapter(1).waitFor(); + const cdp = await page.context().newCDPSession(page); + const swipe = async (direction, cancel = false) => { + const start = direction > 0 ? 660 : 240; + const points = distance => [{ x: 195, y: start - direction * distance, id: 1 }]; + await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: points(0) }); + for (let step = 1; step <= 12; step++) { + await cdp.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: points(step * 28) }); + await page.waitForTimeout(20); + } + await cdp.send('Input.dispatchTouchEvent', { type: cancel ? 'touchCancel' : 'touchEnd', touchPoints: [] }); + await page.waitForTimeout(500); + }; + // Set up just inside each boundary; the chapter change itself must use touch. + await page.mouse.move(20, 420); + await page.mouse.wheel(0, 100000); + await page.waitForTimeout(300); + await page.mouse.wheel(0, -80); + await page.waitForTimeout(300); + await swipe(1); + await chapter(2).waitFor(); + await page.mouse.wheel(0, 80); + await page.waitForTimeout(300); + await swipe(-1); + await chapter(1).waitFor(); + await swipe(1, true); + await chapter(1).waitFor(); + await swipe(1); + await chapter(2).waitFor(); + assert.deepEqual(errors, []); + console.log('PASS: mobile EPUB touch crosses chapter edges, reverses, and ignores cancellation'); + } catch (error) { + throw new Error(`${error.message}\n${await page.locator('body').ariaSnapshot()}`, { cause: error }); + } finally { + await page.close(); + } +} diff --git a/tool/browser/smoke.mjs b/tool/browser/smoke.mjs index c2b5626..9727790 100644 --- a/tool/browser/smoke.mjs +++ b/tool/browser/smoke.mjs @@ -6,6 +6,7 @@ import { dirname, extname, resolve, sep } from 'node:path'; import { fileURLToPath } from 'node:url'; import { chromium } from 'playwright'; import { checkFormats } from './formats.mjs'; +import { checkMobileEpubScroll } from './epub_scroll.mjs'; const reader = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); const dist = resolve(reader, 'example/build/web'); @@ -472,6 +473,7 @@ try { await backToLibrary(); await page.getByRole('button', { name: 'Use light theme', exact: true }).waitFor(); assert.deepEqual(errors, []); + await checkMobileEpubScroll(browser, origin); await checkFormats(browser, origin, reader); console.log('Browser checks passed: worker protocol, focus mode and chapter keyboard focus, responsive settings, local files, cleanup, PDF pagination/scroll, column/appearance refitting and opened menus under opposite app themes.'); } finally { From 0d65af25c9c3550e134bb2740ce4b8c6cb3c2cde Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 21:12:49 +0200 Subject: [PATCH 14/19] fix: preserve reader gestures with custom renderers and reduced motion --- docs/ARCHITECTURE.md | 6 +- .../engine/epub/epub_content_renderer.dart | 1 + lib/src/engine/epub/epub_viewport.dart | 179 +++++++++--------- lib/src/engine/pdf/pdf_facade.dart | 32 +++- test/engine/epub_content_renderer_test.dart | 58 ++++++ test/presentation/pdf_tools_test.dart | 77 ++++++++ tool/browser/pdf_swipes.mjs | 11 ++ 7 files changed, 273 insertions(+), 91 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 977fa47..e9787c8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -81,7 +81,8 @@ screen, up to the renderer's one-pass limit. Holding an in-flight turn does not commit or snap its location. Horizontal mouse drags turn pages at custom zoom, while vertical drags pan and text drags select. During a mouse turn the PDF keeps its horizontal position inside the moving spread; the viewer does not also pan. -Zoomed touch gestures retain document panning and pinch zoom. +Zoomed touch gestures retain document panning and pinch zoom. With animation disabled +or reduced motion enabled, mouse turns commit instantly on release. The host persists the synchronized locator separately from `PdfViewState`, which is device-local view configuration. `ReaderDocument.initialPdfView` and @@ -118,7 +119,8 @@ at paragraph cuts. Outward wheel input at a chapter edge opens the adjacent chap backward navigation restores its bottom. Touch drags can reach and continue beyond an edge in one gesture, including under bouncing physics. Only a completed, unselected single-touch gesture commits the adjacent chapter; inertial scrolling -and cancelled gestures do not trigger a chapter turn. +and cancelled gestures do not trigger a chapter turn. Custom scrolling renderers +share the same chapter boundary gestures. Internal presentation modules are not public API. Host customization uses `ReaderUiBuilders` and exported builder contexts. A `compactPanelRoute` factory diff --git a/lib/src/engine/epub/epub_content_renderer.dart b/lib/src/engine/epub/epub_content_renderer.dart index d4271a6..6d0081a 100644 --- a/lib/src/engine/epub/epub_content_renderer.dart +++ b/lib/src/engine/epub/epub_content_renderer.dart @@ -23,6 +23,7 @@ final class FlutterHtmlEpubContentRenderer implements EpubContentRenderer { return ColoredBox( color: preferences.backgroundColor, child: SingleChildScrollView( + physics: const AlwaysScrollableScrollPhysics(), controller: controller, padding: preferences.pageMargins, child: DefaultTextStyle( diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index 7812a4a..5f6aa91 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -617,7 +617,8 @@ final class _EpubViewportState extends State { } void _scrollChanged() { - if (_restoring || + if (widget.engine.renderer != null || + _restoring || _busy || !_scrollController.hasClients || _pages.isEmpty) { @@ -696,6 +697,67 @@ final class _EpubViewportState extends State { return false; } + Widget _withSwipes({required bool scrolling, required Widget child}) { + return Listener( + onPointerDown: (event) { + _swipe.start(event); + _scrollBoundaryDrag = 0; + _startScroll = _scrollController.hasClients + ? _scrollController.offset + : 0; + }, + onPointerMove: _swipe.update, + onPointerCancel: (event) { + _swipe.cancel(event); + _scrollBoundaryDrag = 0; + }, + onPointerUp: (event) { + final offset = _swipe.end(event); + + if (offset == null) { + return; + } + + final drag = scrolling ? offset.dy : offset.dx; + final crossAxis = scrolling ? offset.dx : offset.dy; + + if (drag.abs() < 70 || drag.abs() <= crossAxis.abs()) { + return; + } + + if (scrolling && _scrollController.hasClients) { + final position = _scrollController.position; + + final next = + drag < 0 && + (_scrollBoundaryDrag >= _scrollBoundaryThreshold || + (_startScroll >= position.maxScrollExtent - 1 && + position.pixels >= position.maxScrollExtent - 1)); + final previous = + drag > 0 && + (_scrollBoundaryDrag <= -_scrollBoundaryThreshold || + (_startScroll <= position.minScrollExtent + 1 && + position.pixels <= position.minScrollExtent + 1)); + if (next || previous) _requestTurn(next ? 1 : -1); + } else { + if (drag < 0 && !_animateTurns) { + _requestTurn(1); + } + + if (drag > 0 && !_animateTurns) { + _requestTurn(-1); + } + } + }, + child: scrolling + ? NotificationListener( + onNotification: _trackScrollBoundary, + child: child, + ) + : child, + ); + } + bool _canTurnWithWheel(Offset delta) { if (_busy || _restoring) return false; if (widget.engine.preferences.layoutMode == ReaderLayoutMode.paginated) { @@ -1003,15 +1065,18 @@ final class _EpubViewportState extends State { return ReaderPageWheel( canTurn: _canTurnWithWheel, onTurn: _turnWithWheel, - child: EpubScrollViewport( - xhtml: widget.engine.currentChapterHtml, - preferences: preferences, - localProgression: widget.engine.locator.localProgression, - restorationRevision: widget.engine.restorationRevision, - renderer: widget.engine.renderer!, - controller: _scrollController, - onProgressChanged: (value) => - widget.engine.viewportPositionChanged(value), + child: _withSwipes( + scrolling: true, + child: EpubScrollViewport( + xhtml: widget.engine.currentChapterHtml, + preferences: preferences, + localProgression: widget.engine.locator.localProgression, + restorationRevision: widget.engine.restorationRevision, + renderer: widget.engine.renderer!, + controller: _scrollController, + onProgressChanged: (value) => + widget.engine.viewportPositionChanged(value), + ), ), ); } @@ -1170,28 +1235,25 @@ final class _EpubViewportState extends State { return start; })(), ]; - content = NotificationListener( - onNotification: _trackScrollBoundary, - child: ListView.custom( - key: ValueKey(_scrollController), - physics: const AlwaysScrollableScrollPhysics(), - controller: _scrollController, - itemExtentBuilder: (index, _) => heights[index], - childrenDelegate: _EpubScrollDelegate( - (context, index) => Align( - alignment: Alignment.topCenter, - child: SizedBox( - width: width, - child: _page( - pages[index], - displayPreferences, - scroll: true, - ), + content = ListView.custom( + key: ValueKey(_scrollController), + physics: const AlwaysScrollableScrollPhysics(), + controller: _scrollController, + itemExtentBuilder: (index, _) => heights[index], + childrenDelegate: _EpubScrollDelegate( + (context, index) => Align( + alignment: Alignment.topCenter, + child: SizedBox( + width: width, + child: _page( + pages[index], + displayPreferences, + scroll: true, ), ), - childCount: pages.length, - extent: cumulative, ), + childCount: pages.length, + extent: cumulative, ), ); } else { @@ -1284,62 +1346,9 @@ final class _EpubViewportState extends State { final surface = ReaderHighlightInteraction( hitTest: _highlightAt, isSelecting: () => _selectedText.isNotEmpty, - child: Listener( - onPointerDown: (event) { - _swipe.start(event); - _scrollBoundaryDrag = 0; - _startScroll = _scrollController.hasClients - ? _scrollController.offset - : 0; - }, - onPointerMove: _swipe.update, - onPointerCancel: (event) { - _swipe.cancel(event); - _scrollBoundaryDrag = 0; - }, - onPointerUp: (event) { - final offset = _swipe.end(event); - - if (offset == null) { - return; - } - - final scrolling = - displayPreferences.layoutMode == - ReaderLayoutMode.scroll; - final drag = scrolling ? offset.dy : offset.dx; - final crossAxis = scrolling ? offset.dx : offset.dy; - - if (drag.abs() < 70 || drag.abs() <= crossAxis.abs()) { - return; - } - - if (scrolling && _scrollController.hasClients) { - final position = _scrollController.position; - - final next = - drag < 0 && - (_scrollBoundaryDrag >= _scrollBoundaryThreshold || - (_startScroll >= position.maxScrollExtent - 1 && - position.pixels >= - position.maxScrollExtent - 1)); - final previous = - drag > 0 && - (_scrollBoundaryDrag <= -_scrollBoundaryThreshold || - (_startScroll <= position.minScrollExtent + 1 && - position.pixels <= - position.minScrollExtent + 1)); - if (next || previous) _requestTurn(next ? 1 : -1); - } else { - if (drag < 0 && !_animateTurns) { - _requestTurn(1); - } - - if (drag > 0 && !_animateTurns) { - _requestTurn(-1); - } - } - }, + child: _withSwipes( + scrolling: + displayPreferences.layoutMode == ReaderLayoutMode.scroll, child: Localizations.of( context, diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index a84c18d..a0b3db1 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -518,6 +518,8 @@ final class _PdfrxFacade extends PdfReaderTools PageController? _pagesController; Drag? _pageDrag; bool _pagingEnabled = false; + bool _pageSwipeEnabled = false; + Offset? _instantMouseDrag; final Set _pagePointers = {}; PointerDownEvent? _pagePointerStart; double? _mousePanX; @@ -802,13 +804,15 @@ final class _PdfrxFacade extends PdfReaderTools }); } final revision = _viewerRevision; - _pagingEnabled = + _pageSwipeEnabled = configuration.layoutMode == ReaderLayoutMode.paginated && - configuration.pageTurnAnimation && - !MediaQuery.disableAnimationsOf(context) && !_restoring && !_textSelected && !_multiTouch; + _pagingEnabled = + _pageSwipeEnabled && + configuration.pageTurnAnimation && + !MediaQuery.disableAnimationsOf(context); Widget buildViewer(int index) { final spread = _spreadFor(index); final controller = spread.controller; @@ -839,6 +843,7 @@ final class _PdfrxFacade extends PdfReaderTools }, onPointerCancel: (event) { _swipe.cancel(event); + _instantMouseDrag = null; _pageDrag?.cancel(); _pageDrag = null; _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); @@ -1105,11 +1110,13 @@ final class _PdfrxFacade extends PdfReaderTools void _pagePointerDown(PointerDownEvent event) { _pagePointers.add(event.pointer); if (_pagePointers.length == 1) { + _instantMouseDrag = null; _pagePointerStart = event; _mousePanX = null; } if (_pagePointers.length > 1 && !_multiTouch) { _multiTouch = true; + _instantMouseDrag = null; _pageDrag?.cancel(); _pageDrag = null; _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); @@ -1134,7 +1141,7 @@ final class _PdfrxFacade extends PdfReaderTools details.pointerCount == 1 && start?.kind == PointerDeviceKind.mouse; _mousePanX = null; final pages = _pagesController; - if (!_pagingEnabled || + if (!_pageSwipeEnabled || pages == null || !pages.hasClients || details.pointerCount != 1) { @@ -1148,6 +1155,10 @@ final class _PdfrxFacade extends PdfReaderTools final delta = details.focalPoint - start!.position; if (delta.dx.abs() <= delta.dy.abs()) return; } + if (!_pagingEnabled) { + if (mouse) _instantMouseDrag = details.focalPoint - start!.position; + return; + } _pageDrag = pages.position.drag( DragStartDetails(globalPosition: details.focalPoint), () => _pageDrag = null, @@ -1155,6 +1166,12 @@ final class _PdfrxFacade extends PdfReaderTools } void _updatePageDrag(ScaleUpdateDetails details) { + if (_instantMouseDrag != null) { + _instantMouseDrag = + details.pointerCount == 1 && (details.scale - 1).abs() <= .001 + ? _instantMouseDrag! + details.focalPointDelta + : null; + } final drag = _pageDrag; if (drag == null) return; if (details.pointerCount != 1 || (details.scale - 1).abs() > .001) { @@ -1173,6 +1190,13 @@ final class _PdfrxFacade extends PdfReaderTools } void _endPageDrag(ScaleEndDetails details) { + final instant = _instantMouseDrag; + _instantMouseDrag = null; + if (instant != null && + instant.dx.abs() > 70 && + instant.dx.abs() > instant.dy.abs()) { + unawaited(_turnSpread(instant.dx < 0 ? 1 : -1)); + } final drag = _pageDrag; _pageDrag = null; drag?.end( diff --git a/test/engine/epub_content_renderer_test.dart b/test/engine/epub_content_renderer_test.dart index aea6798..f085c98 100644 --- a/test/engine/epub_content_renderer_test.dart +++ b/test/engine/epub_content_renderer_test.dart @@ -47,6 +47,64 @@ void main() { } }); + for (final initiallyPaginated in [false, true]) { + testWidgets( + 'custom EPUB renderer crosses chapter edges with touch, initially paginated $initiallyPaginated', + (tester) async { + final renderer = _TrackingRenderer(); + final engine = EpubReaderEngine( + renderer: renderer, + workerFactory: () async => InProcessEpubWorker(), + ); + addTearDown(engine.dispose); + await engine.load( + ReaderDocument( + id: 'custom-touch', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub(), + ), + preferences: ReaderPreferences( + layoutMode: initiallyPaginated + ? ReaderLayoutMode.paginated + : ReaderLayoutMode.scroll, + ), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + if (initiallyPaginated) { + await engine.updatePreferences( + engine.preferences.copyWith(layoutMode: ReaderLayoutMode.scroll), + ); + await tester.pumpAndSettle(); + } + for (final direction in [1, -1]) { + final position = renderer.controller.position; + renderer.controller.jumpTo( + direction > 0 ? position.maxScrollExtent - 40 : 40, + ); + await tester.pumpAndSettle(); + final before = engine.locator.spineIndex; + await tester.dragFrom( + const Offset(400, 300), + Offset(0, -250.0 * direction), + ); + await tester.pumpAndSettle(); + expect(engine.locator.spineIndex, before + direction); + expect( + renderer.controller.offset, + closeTo( + direction > 0 ? 0 : renderer.controller.position.maxScrollExtent, + 1, + ), + ); + } + expect(tester.takeException(), isNull); + }, + ); + } + testWidgets('programmatic restoration does not publish progress', ( tester, ) async { diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index f2f6a5f..c1c4f72 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -640,6 +640,83 @@ void main() { }); } + for (final reducedMotion in [false, true]) { + for (final zoomed in [false, true]) { + testWidgets( + 'PDF instant mouse turns, reduced motion $reducedMotion, zoomed $zoomed', + (tester) async { + await tester.binding.setSurfaceSize(const Size(1440, 900)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(_document); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'instant-mouse'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: MediaQuery( + data: MediaQueryData(disableAnimations: reducedMotion), + child: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + pageTurnAnimation: reducedMotion, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + if (zoomed) { + await tools.setZoom(tools.zoom * 2); + await tester.pumpAndSettle(); + } + final zoom = tools.zoom; + final pages = tester + .widget(find.byType(PageView)) + .controller!; + for (final direction in [1, -1]) { + final before = tools.pageNumber; + final gesture = await tester.startGesture( + const Offset(720, 450), + kind: PointerDeviceKind.mouse, + ); + await gesture.moveBy(Offset(-30.0 * direction, 0)); + await tester.pump(); + await gesture.moveBy(Offset(-200.0 * direction, 0)); + await tester.pump(const Duration(milliseconds: 100)); + expect(tools.pageNumber, before); + expect(pages.page, before - 1); + await gesture.up(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, before + direction); + expect(tools.zoom, closeTo(zoom, .001)); + } + final cancelled = await tester.startGesture( + const Offset(720, 450), + kind: PointerDeviceKind.mouse, + ); + await cancelled.moveBy(const Offset(-30, 0)); + await tester.pump(); + await cancelled.moveBy(const Offset(-200, 0)); + await tester.pump(); + await cancelled.cancel(); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 1); + expect(tester.takeException(), isNull); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + } + for (final animation in [true, false]) { for (final facing in [false, true]) { testWidgets( diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index 9a71572..d885229 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -220,6 +220,17 @@ try { await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); assert.deepEqual(errors, []); console.log('PASS: zoomed PDF rapid mouse drags, reverse turn, retained zoom, and text selection'); + await page.emulateMedia({ reducedMotion: 'reduce' }); + await page.keyboard.press('Escape'); + await page.waitForTimeout(300); + await swipe(1, true); + await page.waitForTimeout(300); + await assertPage(7); + await swipe(-1, true); + await page.waitForTimeout(300); + await assertPage(6); + assert.deepEqual(errors, []); + console.log('PASS: reduced-motion PDF mouse turns in both directions at 200% zoom'); } await page.close(); } From f389b7f773d2e1e2b508ed6696753a1563111a39 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 21:21:31 +0200 Subject: [PATCH 15/19] test: observe PDF controls after selection before checking zoom --- tool/browser/pdf_swipes.mjs | 39 ++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index d885229..10c8664 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -121,17 +121,32 @@ try { maxFrameGapMs: gaps.at(-1), framesOver50Ms: gaps.filter(gap => gap > 50).length, longTaskCount: tasks.length, maxLongTaskMs: Math.max(0, ...tasks) }; }); - const assertPage = async number => { - if (await page.getByRole('button', { name: 'Back', exact: true }).count() === 0) { + const setControlsVisible = async visible => { + const back = page.getByRole('button', { name: 'Back', exact: true }); + // Escape can first dismiss a PDF selection. Observe the controls before + // sending another key so selection cleanup cannot invert the next check. + for (let attempt = 0; attempt < 3 && await back.isVisible() !== visible; attempt++) { await page.keyboard.press('Escape'); + await page.waitForTimeout(300); } + await back.waitFor({ state: visible ? 'visible' : 'hidden' }); + }; + const assertPage = async number => { + await setControlsVisible(true); try { await page.getByRole('button', { name: `Page ${number} of ${Number(process.env.PAPYRUS_PDF_PAGES ?? 40)}. Go to page`, exact: true }).waitFor(); } catch (error) { throw new Error(`Expected active PDF page ${number}:\n${await page.locator('body').ariaSnapshot()}`, { cause: error }); } - await page.keyboard.press('Escape'); - await page.waitForTimeout(300); + await setControlsVisible(false); + }; + const assertZoom = async (showControls = false) => { + if (showControls) await setControlsVisible(true); + try { + await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + } catch (error) { + throw new Error(`Expected zoom controls at 200%:\n${await page.locator('body').ariaSnapshot()}`, { cause: error }); + } }; await assertPage(5); assert.deepEqual(errors, []); @@ -160,7 +175,7 @@ try { assert.deepEqual(errors, []); console.log('PASS: desktop mouse hold, text selection, and reverse swipe'); } - await page.keyboard.press('Escape'); + await setControlsVisible(true); const zoomControl = page.getByRole('button', { name: /^Zoom \d+ percent\. Set zoom$/ }); await zoomControl.waitFor(); await page.waitForTimeout(300); @@ -170,8 +185,8 @@ try { await page.mouse.click(zoomBounds.x + zoomBounds.width / 2, zoomBounds.y + zoomBounds.height / 2); await page.getByRole('textbox', { name: 'Zoom percentage' }).fill('200'); await page.getByRole('button', { name: 'Apply', exact: true }).click(); - await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); - await page.keyboard.press('Escape'); + await assertZoom(); + await setControlsVisible(false); await page.mouse.move(width / 2, 450); const wheel = async delta => { await page.mouse.wheel(0, delta); @@ -191,12 +206,11 @@ try { await assertPage(5); await wheel(-1); await assertPage(4); - await page.keyboard.press('Escape'); - await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + await assertZoom(true); assert.deepEqual(errors, []); console.log(`PASS: ${width}px zoomed PDF wheel pans within pages and turns at both edges`); if (input === 'mouse') { - await page.keyboard.press('Escape'); + await setControlsVisible(false); for (let turn = 0; turn < 3; turn++) { await swipe(1, true); await page.waitForTimeout(70); @@ -216,12 +230,11 @@ try { await page.mouse.click(width * .9, 450); await page.waitForTimeout(300); await assertPage(6); - await page.keyboard.press('Escape'); - await page.getByRole('button', { name: 'Zoom 200 percent. Set zoom', exact: true }).waitFor(); + await assertZoom(true); assert.deepEqual(errors, []); console.log('PASS: zoomed PDF rapid mouse drags, reverse turn, retained zoom, and text selection'); await page.emulateMedia({ reducedMotion: 'reduce' }); - await page.keyboard.press('Escape'); + await setControlsVisible(false); await page.waitForTimeout(300); await swipe(1, true); await page.waitForTimeout(300); From 3f7c8a7a4fe0d30348919171d0148e70e0ee72c6 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 21:38:13 +0200 Subject: [PATCH 16/19] fix: ignore clipped EPUB text when starting margin drags --- lib/src/engine/epub/epub_viewport.dart | 33 ++++++++---- test/presentation/epub_page_turn_test.dart | 59 ++++++++++++++++++++++ 2 files changed, 81 insertions(+), 11 deletions(-) diff --git a/lib/src/engine/epub/epub_viewport.dart b/lib/src/engine/epub/epub_viewport.dart index 5f6aa91..e574d76 100644 --- a/lib/src/engine/epub/epub_viewport.dart +++ b/lib/src/engine/epub/epub_viewport.dart @@ -68,6 +68,7 @@ final class _EpubViewportState extends State { bool _busy = false; Completer? _layoutReady; List _scrollOffsets = const []; + final _pageViewportKey = GlobalKey(); final _selectionKey = GlobalKey(); final _selectionMenuController = ContextMenuController(); int _menuRevision = 0; @@ -88,6 +89,25 @@ final class _EpubViewportState extends State { return fragments; } + bool _canStartMouseDrag(Offset position) { + if (_selectedText.isNotEmpty) return false; + final viewport = + _pageViewportKey.currentContext?.findRenderObject() as RenderBox?; + if (viewport == null) return false; + final bounds = viewport.localToGlobal(Offset.zero) & viewport.size; + // Neighbour pages may remain mounted while clipped. Their text rectangles + // must not claim pointer input in the blank margins outside the PageView. + if (!bounds.contains(position)) return true; + return !_fragments.any( + (fragment) => fragment + .rectangles( + 0, + fragment.widget.fragment.end - fragment.widget.fragment.start, + ) + .any((rectangle) => rectangle.contains(position)), + ); + } + Rect? _visibleBounds(Iterable rectangles) { final box = context.findRenderObject() as RenderBox; final viewport = box.localToGlobal(Offset.zero) & box.size; @@ -1278,19 +1298,10 @@ final class _EpubViewportState extends State { controller: _pagesController, animate: _animateTurns, onTurn: _requestTurn, - canStart: (position) => - _selectedText.isEmpty && - !_fragments.any( - (fragment) => fragment - .rectangles( - 0, - fragment.widget.fragment.end - - fragment.widget.fragment.start, - ) - .any((rectangle) => rectangle.contains(position)), - ), + canStart: _canStartMouseDrag, child: Center( child: SizedBox( + key: _pageViewportKey, width: width, child: PageView.builder( key: ValueKey(_pagesController), diff --git a/test/presentation/epub_page_turn_test.dart b/test/presentation/epub_page_turn_test.dart index d2a1afc..0f75625 100644 --- a/test/presentation/epub_page_turn_test.dart +++ b/test/presentation/epub_page_turn_test.dart @@ -2,6 +2,7 @@ import 'package:flutter/material.dart'; import 'package:flutter/gestures.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:papyrus_reader/papyrus_reader.dart'; +import 'package:papyrus_reader/src/engine/epub/epub_rich_layout.dart'; import '../support/in_process_epub_worker.dart'; import '../support/synthetic_epub.dart'; @@ -59,6 +60,64 @@ void main() { }, ); + testWidgets('clipped EPUB text cannot block a reverse drag in the margin', ( + tester, + ) async { + await tester.binding.setSurfaceSize(const Size(1100, 800)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final engine = testEpubEngine(); + await engine.load( + ReaderDocument( + id: 'clipped-margin', + format: ReaderFormat.epub, + loadBytes: () async => syntheticEpub(longChapter: true), + ), + preferences: const ReaderPreferences(), + ); + await tester.pumpWidget( + MaterialApp(home: Builder(builder: engine.buildViewport)), + ); + await tester.pumpAndSettle(); + final viewport = find.byType(PageView); + final pages = tester.widget(viewport).controller!; + final bounds = tester.getRect(viewport); + pages.jumpTo(bounds.width * .9); + await tester.pump(); + final margin = Rect.fromLTRB(0, 0, bounds.left, 800); + final clippedText = tester + .stateList( + find.byType(EpubSelectionFragment), + ) + .expand( + (fragment) => fragment.rectangles( + 0, + fragment.widget.fragment.end - fragment.widget.fragment.start, + ), + ) + .map((rectangle) => rectangle.intersect(margin)) + .where((rectangle) => !rectangle.isEmpty); + expect( + clippedText, + isNotEmpty, + reason: 'The previous page extends behind the clipped left margin', + ); + final gesture = await tester.startGesture( + clippedText.first.center, + kind: PointerDeviceKind.mouse, + ); + await gesture.moveBy(const Offset(30, 0)); + await tester.pump(); + final before = pages.position.pixels; + await gesture.moveBy(const Offset(150, 0)); + await tester.pump(const Duration(milliseconds: 16)); + expect(pages.position.pixels, closeTo(before - 150, 1)); + await gesture.moveBy(const Offset(450, 0)); + await gesture.up(); + await tester.pumpAndSettle(); + expect(pages.page, 0); + expect(tester.takeException(), isNull); + }); + for (final animation in [true, false]) { testWidgets( 'EPUB mouse turns start in outer window margins, animation $animation', From 5aea0a07675a8b9c77e8dc6004b21e97252f4acd Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 21:52:12 +0200 Subject: [PATCH 17/19] fix: prevent decelerating mouse turns from flinging backwards --- .../presentation/reader_mouse_page_drag.dart | 20 ++++- .../reader_mouse_page_drag_test.dart | 74 +++++++++++++++++++ 2 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 test/presentation/reader_mouse_page_drag_test.dart diff --git a/lib/src/presentation/reader_mouse_page_drag.dart b/lib/src/presentation/reader_mouse_page_drag.dart index 37c73b1..4709fb3 100644 --- a/lib/src/presentation/reader_mouse_page_drag.dart +++ b/lib/src/presentation/reader_mouse_page_drag.dart @@ -27,9 +27,11 @@ final class _ReaderMousePageDragState extends State { ScrollHoldController? _hold; Drag? _drag; double _distance = 0; + double _lastDelta = 0; void _down(DragDownDetails details) { _distance = 0; + _lastDelta = 0; if (widget.animate && widget.controller.hasClients) { _hold = widget.controller.position.hold(() => _hold = null); } @@ -42,14 +44,28 @@ final class _ReaderMousePageDragState extends State { } void _update(DragUpdateDetails details) { - _distance += details.primaryDelta!; + final delta = details.primaryDelta!; + _distance += delta; + if (delta != 0) _lastDelta = delta; _drag?.update(details); } void _end(DragEndDetails details) { final drag = _drag; _drag = null; - drag?.end(details); + // A quadratic velocity fit can point backwards after a decelerating drag, + // especially with uneven browser event timestamps. Settle where the pointer + // left the page instead of flinging against its final movement. + final velocity = details.primaryVelocity ?? 0; + drag?.end( + velocity * _lastDelta < 0 + ? DragEndDetails( + primaryVelocity: 0, + globalPosition: details.globalPosition, + localPosition: details.localPosition, + ) + : details, + ); _hold?.cancel(); _hold = null; if (!widget.animate && _distance.abs() > 70) { diff --git a/test/presentation/reader_mouse_page_drag_test.dart b/test/presentation/reader_mouse_page_drag_test.dart new file mode 100644 index 0000000..eb84e91 --- /dev/null +++ b/test/presentation/reader_mouse_page_drag_test.dart @@ -0,0 +1,74 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:papyrus_reader/src/presentation/reader_mouse_page_drag.dart'; + +void main() { + for (final direction in [-1, 1]) { + testWidgets('decelerating mouse drag cannot fling backwards, $direction', ( + tester, + ) async { + final pages = PageController(initialPage: 1); + addTearDown(pages.dispose); + await tester.pumpWidget( + MaterialApp( + home: ReaderMousePageDrag( + controller: pages, + animate: true, + canStart: (_) => true, + onTurn: (_) {}, + child: PageView( + controller: pages, + children: const [ + SizedBox.expand(), + SizedBox.expand(), + SizedBox.expand(), + ], + ), + ), + ), + ); + final start = Offset(direction > 0 ? 50 : 750, 300); + final gesture = await tester.startGesture( + start, + kind: PointerDeviceKind.mouse, + ); + for (final sample in [ + (10, 100), + (20, 300), + (30, 500), + (60, 600), + (80, 601), + (100, 602), + ]) { + await gesture.moveTo( + start + Offset(sample.$2 * direction.toDouble(), 0), + timeStamp: Duration(milliseconds: sample.$1), + ); + await tester.pump(); + } + expect(pages.page, closeTo(1 - direction * 602 / 800, .001)); + await gesture.up(timeStamp: const Duration(milliseconds: 101)); + await tester.pumpAndSettle(); + expect(pages.page, 1 - direction); + + // A real reversal at release must still fling back to the starting page. + pages.jumpToPage(1); + await tester.pumpAndSettle(); + final reverse = await tester.startGesture( + start, + kind: PointerDeviceKind.mouse, + ); + for (final sample in [(10, 30), (20, 600), (50, 550), (60, 500)]) { + await reverse.moveTo( + start + Offset(sample.$2 * direction.toDouble(), 0), + timeStamp: Duration(milliseconds: sample.$1), + ); + await tester.pump(); + } + await reverse.up(timeStamp: const Duration(milliseconds: 61)); + await tester.pumpAndSettle(); + expect(pages.page, 1); + }); + } +} From c2bb9d737b8b9e160bd25e8f409d91dd8ac3b494 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 22:14:54 +0200 Subject: [PATCH 18/19] fix: preserve PDF swipe direction when releasing moving pages --- lib/src/engine/pdf/pdf_facade.dart | 54 ++++++++----- test/presentation/pdf_tools_test.dart | 108 ++++++++++++++++++++++++++ tool/browser/pdf_swipes.mjs | 6 +- 3 files changed, 145 insertions(+), 23 deletions(-) diff --git a/lib/src/engine/pdf/pdf_facade.dart b/lib/src/engine/pdf/pdf_facade.dart index a0b3db1..cc0810c 100644 --- a/lib/src/engine/pdf/pdf_facade.dart +++ b/lib/src/engine/pdf/pdf_facade.dart @@ -10,6 +10,7 @@ import '../../domain/reader_types.dart'; import '../../domain/reader_selection.dart'; import '../../domain/reader_locator.dart'; import '../../presentation/reader_page_wheel.dart'; +import '../../presentation/reader_mouse_page_drag.dart'; import '../../presentation/reader_interaction_scope.dart'; import '../../presentation/reader_swipe_tracker.dart'; import '../../presentation/reader_highlight_interaction.dart'; @@ -517,6 +518,7 @@ final class _PdfrxFacade extends PdfReaderTools bool _textSelected = false; PageController? _pagesController; Drag? _pageDrag; + double _lastPageDragDelta = 0; bool _pagingEnabled = false; bool _pageSwipeEnabled = false; Offset? _instantMouseDrag; @@ -1072,28 +1074,33 @@ final class _PdfrxFacade extends PdfReaderTools }, child: ScrollConfiguration( behavior: ScrollConfiguration.of(context).copyWith( - // The incoming viewer is inactive until settlement. - // Its parent must still accept a mouse drag mid-turn. dragDevices: { if (!_restoring && _atFit) ...ScrollConfiguration.of(context).dragDevices, - PointerDeviceKind.mouse, - }, + }..remove(PointerDeviceKind.mouse), ), - child: PageView.builder( - key: ValueKey(pages), + // Inactive incoming viewers ignore pointers. Keep their + // mouse drags on the same guarded release path as EPUB. + child: ReaderMousePageDrag( controller: pages, - allowImplicitScrolling: true, - physics: _pagingEnabled - ? const ClampingScrollPhysics() - : const NeverScrollableScrollPhysics(), - itemCount: (pageCount / _spreadStep).ceil(), - itemBuilder: (context, index) => SizedBox.expand( - key: ValueKey(('pdf-spread', index)), - child: _PdfSpreadLoader( - pages: pages, - index: index, - builder: (_) => buildViewer(index), + animate: _pagingEnabled, + canStart: (_) => _pageSwipeEnabled, + onTurn: (direction) => _turnSpread(direction), + child: PageView.builder( + key: ValueKey(pages), + controller: pages, + allowImplicitScrolling: true, + physics: _pagingEnabled + ? const ClampingScrollPhysics() + : const NeverScrollableScrollPhysics(), + itemCount: (pageCount / _spreadStep).ceil(), + itemBuilder: (context, index) => SizedBox.expand( + key: ValueKey(('pdf-spread', index)), + child: _PdfSpreadLoader( + pages: pages, + index: index, + builder: (_) => buildViewer(index), + ), ), ), ), @@ -1136,6 +1143,7 @@ final class _PdfrxFacade extends PdfReaderTools } void _startPageDrag(ScaleStartDetails details) { + _lastPageDragDelta = 0; final start = _pagePointerStart; final mouse = details.pointerCount == 1 && start?.kind == PointerDeviceKind.mouse; @@ -1180,6 +1188,8 @@ final class _PdfrxFacade extends PdfReaderTools _pagesController?.jumpToPage(_pageIndex ~/ _spreadStep); return; } + final delta = details.focalPointDelta.dx; + if (delta != 0) _lastPageDragDelta = delta; drag.update( DragUpdateDetails( globalPosition: details.focalPoint, @@ -1199,12 +1209,14 @@ final class _PdfrxFacade extends PdfReaderTools } final drag = _pageDrag; _pageDrag = null; + // Decelerating pointer samples can produce an estimated velocity opposite + // to the final movement. Do not let that fling the page backwards. + final estimate = details.velocity.pixelsPerSecond.dx; + final velocity = estimate * _lastPageDragDelta < 0 ? 0.0 : estimate; drag?.end( DragEndDetails( - velocity: Velocity( - pixelsPerSecond: Offset(details.velocity.pixelsPerSecond.dx, 0), - ), - primaryVelocity: details.velocity.pixelsPerSecond.dx, + velocity: Velocity(pixelsPerSecond: Offset(velocity, 0)), + primaryVelocity: velocity, ), ); } diff --git a/test/presentation/pdf_tools_test.dart b/test/presentation/pdf_tools_test.dart index c1c4f72..50f56b5 100644 --- a/test/presentation/pdf_tools_test.dart +++ b/test/presentation/pdf_tools_test.dart @@ -419,6 +419,114 @@ void main() { } } + for (final zoomed in [false, true]) { + testWidgets( + 'PDF decelerating mouse swipe keeps its direction, zoomed $zoomed', + (tester) async { + await tester.binding.setSurfaceSize(const Size(800, 600)); + addTearDown(() => tester.binding.setSurfaceSize(null)); + final bytes = await tester.runAsync(_document); + await tester.runAsync(initializePdfiumForTest); + final facade = (await tester.runAsync( + () => createPdfrxFacade(bytes!, sourceName: 'decelerating-mouse'), + ))!; + final tools = facade as PdfReaderTools; + addTearDown(() => (facade as DisposablePdfFacade).dispose()); + await tester.pumpWidget( + MaterialApp( + home: facade.buildViewport( + PdfViewportConfiguration( + pageIndex: 0, + facingPages: false, + backgroundColor: Colors.white, + brightness: Brightness.light, + layoutMode: ReaderLayoutMode.paginated, + onPageChanged: (_) {}, + ), + ), + ), + ); + await _ready(tester, tools); + await tester.pumpAndSettle(); + if (zoomed) { + await tools.setZoom(tools.zoom * 2); + await tester.pumpAndSettle(); + } + final pages = tester + .widget(find.byType(PageView)) + .controller!; + for (final direction in [1, -1]) { + final before = tools.pageNumber; + final start = Offset(direction > 0 ? 700 : 100, 300); + final gesture = await tester.startGesture( + start, + kind: PointerDeviceKind.mouse, + ); + for (final sample in [ + (10, 100), + (20, 300), + (30, 500), + (60, 600), + (80, 601), + (100, 602), + ]) { + await gesture.moveTo( + start - Offset(sample.$2 * direction.toDouble(), 0), + timeStamp: Duration(milliseconds: sample.$1), + ); + await tester.pump(); + } + expect(pages.page, closeTo(before - 1 + direction * .7525, .001)); + await gesture.up(timeStamp: const Duration(milliseconds: 101)); + await tester.pumpAndSettle(); + expect(tools.pageNumber, before + direction); + } + // Deliberately reversing before release still returns to this page. + final reverse = await tester.startGesture( + const Offset(700, 300), + kind: PointerDeviceKind.mouse, + ); + for (final sample in [(10, 30), (20, 600), (50, 550), (60, 500)]) { + await reverse.moveTo( + Offset(700 - sample.$2.toDouble(), 300), + timeStamp: Duration(milliseconds: sample.$1), + ); + await tester.pump(); + } + await reverse.up(timeStamp: const Duration(milliseconds: 61)); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 1); + // Catch the incoming, inactive viewer before the current turn settles. + // Its mouse recognizer must use the same release direction guard. + pages.jumpTo(600); + await tester.pump(); + final incoming = await tester.startGesture( + const Offset(700, 300), + kind: PointerDeviceKind.mouse, + ); + for (final sample in [ + (10, 100), + (20, 300), + (30, 500), + (60, 600), + (80, 601), + (100, 602), + ]) { + await incoming.moveTo( + Offset(700 - sample.$2.toDouble(), 300), + timeStamp: Duration(milliseconds: sample.$1), + ); + await tester.pump(); + } + expect(pages.page, closeTo(1.5025, .001)); + await incoming.up(timeStamp: const Duration(milliseconds: 101)); + await tester.pumpAndSettle(); + expect(tools.pageNumber, 3); + await tester.pumpWidget(const SizedBox.shrink()); + }, + ); + } + for (final zoomed in [false, true]) { testWidgets( 'PDF mouse hold and release keeps navigation and selection alive, zoomed $zoomed', diff --git a/tool/browser/pdf_swipes.mjs b/tool/browser/pdf_swipes.mjs index 10c8664..50f08ae 100644 --- a/tool/browser/pdf_swipes.mjs +++ b/tool/browser/pdf_swipes.mjs @@ -70,7 +70,7 @@ try { const cdp = await page.context().newCDPSession(page); await cdp.send('Emulation.setCPUThrottlingRate', { rate: Number(process.env.PAPYRUS_PDF_CPU_RATE ?? 1) }); const swipe = async (direction = 1, inside = false) => { - const x = direction > 0 ? width * (inside ? .8 : .97) : width * (inside ? .2 : .03); + const x = direction > 0 ? width * (inside ? .9 : .97) : width * (inside ? .1 : .03); const point = offset => [{ x: x - direction * offset, y: 350, id: 1 }]; if (input === 'mouse') { await page.mouse.move(x, 350); @@ -79,7 +79,7 @@ try { await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: point(0) }); } for (let step = 1; step <= 18; step++) { - const offset = step * width * (inside ? .7 : .94) / 18; + const offset = step * width * (inside ? .85 : .94) / 18; if (input === 'mouse') { await page.mouse.move(x - direction * offset, 350); } else { @@ -211,6 +211,8 @@ try { console.log(`PASS: ${width}px zoomed PDF wheel pans within pages and turns at both edges`); if (input === 'mouse') { await setControlsVisible(false); + // Each interrupted drag must cover enough distance to pass the next + // midpoint even when CPU throttling leaves no estimated release velocity. for (let turn = 0; turn < 3; turn++) { await swipe(1, true); await page.waitForTimeout(70); From d52e5f46710361e401cccf8cee9b868b9f066497 Mon Sep 17 00:00:00 2001 From: Karolis Strazdas Date: Sat, 14 Nov 2026 22:30:43 +0200 Subject: [PATCH 19/19] test: keep format mouse swipes within one page of travel --- tool/browser/formats.mjs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tool/browser/formats.mjs b/tool/browser/formats.mjs index fede446..2593b8b 100644 --- a/tool/browser/formats.mjs +++ b/tool/browser/formats.mjs @@ -106,10 +106,12 @@ export async function checkFormats(browser, origin, reader) { await page.mouse.click(20, 400); await next.waitFor({ state: 'hidden' }); await page.waitForTimeout(300); - // Start in the outer window margins, beyond the centered text column. + // Start beyond the centered text column. Keep the stroke shorter than + // its 800px page but longer than half the 1100px PDF viewport, so + // release velocity cannot turn a one-page assertion into a two-page fling. await page.mouse.move(direction > 0 ? 1040 : 60, 400); await page.mouse.down(); - await page.mouse.move(direction > 0 ? 60 : 1040, 400, { steps: 18 }); + await page.mouse.move(direction > 0 ? 340 : 760, 400, { steps: 18 }); await page.mouse.up(); await page.waitForTimeout(700); await page.mouse.click(20, 400);