feat: add synchronized reading progress for bookmarks

.husky/pre-commit

@@ -1,3 +1,4 @@
 pnpm preflight
 pnpm exec sherif
 pnpm run --filter @karakeep/open-api check
+pnpm run --filter @karakeep/shared check:webview-js

apps/mobile/components/bookmarks/BookmarkLinkPreview.tsx

@@ -1,7 +1,7 @@
-import { useState } from "react";
-import { Pressable, View } from "react-native";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AppState, Pressable, View } from "react-native";
 import ImageView from "react-native-image-viewing";
-import WebView from "react-native-webview";
+import WebView, { WebViewMessageEvent } from "react-native-webview";
 import { WebViewSourceUri } from "react-native-webview/lib/WebViewTypes";
 import { Text } from "@/components/ui/Text";
 import { useAssetUrl } from "@/lib/hooks";
@@ -10,6 +10,11 @@ import { api } from "@/lib/trpc";
 import { useColorScheme } from "@/lib/useColorScheme";
 
 import { BookmarkTypes, ZBookmark } from "@karakeep/shared/types/bookmarks";
+import {
+  PERIODIC_SAVE_INTERVAL_MS,
+  SCROLL_THROTTLE_MS,
+} from "@karakeep/shared/utils/reading-progress-core";
+import { READING_PROGRESS_WEBVIEW_JS } from "@karakeep/shared/utils/reading-progress-webview.generated";
 
 import FullPageError from "../FullPageError";
 import FullPageSpinner from "../ui/FullPageSpinner";
@@ -34,6 +39,73 @@ export function BookmarkLinkBrowserPreview({
   );
 }
 
+/**
+ * Builds the reading progress injection script for WebView.
+ *
+ * Uses shared reading progress functions from @karakeep/shared to ensure
+ * consistent behavior between web and mobile. The shared code includes
+ * whitespace normalization and anchor text support for reliable position tracking.
+ *
+ * @param initialOffset - The saved reading position offset to restore
+ * @param initialAnchor - The saved anchor text for position verification
+ * @returns JavaScript string to inject into WebView
+ */
+function buildReadingProgressScript(
+  initialOffset: number,
+  initialAnchor: string | null,
+): string {
+  return `
+    (function() {
+      // Core reading progress functions from @karakeep/shared (bundled IIFE)
+      // These are shared with the web implementation for consistency
+      ${READING_PROGRESS_WEBVIEW_JS}
+
+      // Extract functions from the IIFE global
+      var getReadingPosition = __readingProgress.getReadingPosition;
+      var scrollToReadingPosition = __readingProgress.scrollToReadingPosition;
+
+      // Report current position to React Native
+      function reportProgress() {
+        var position = getReadingPosition(document.body);
+        if (position && position.offset > 0) {
+          window.ReactNativeWebView.postMessage(JSON.stringify({
+            type: 'SCROLL_PROGRESS',
+            offset: position.offset,
+            anchor: position.anchor,
+            percent: position.percent
+          }));
+        }
+      }
+
+      // Restore position immediately (no setTimeout needed for inline HTML -
+      // DOM is ready when injectedJavaScript runs)
+      var initialOffset = ${initialOffset};
+      var initialAnchor = ${JSON.stringify(initialAnchor)};
+      if (initialOffset && initialOffset > 0) {
+        scrollToReadingPosition(document.body, initialOffset, 'instant', initialAnchor);
+      }
+      // Show content after scroll restoration (or immediately if no scroll needed)
+      document.body.style.opacity = '1';
+
+      // Report on scroll (throttled to prevent jank from expensive DOM operations)
+      var lastScrollTime = 0;
+      window.addEventListener('scroll', function() {
+        var now = Date.now();
+        if (now - lastScrollTime < ${SCROLL_THROTTLE_MS}) {
+          return;
+        }
+        lastScrollTime = now;
+        reportProgress();
+      });
+
+      // Also report periodically as backup
+      setInterval(reportProgress, ${PERIODIC_SAVE_INTERVAL_MS});
+
+      true; // Required for injectedJavaScript
+    })();
+  `;
+}
+
 export function BookmarkLinkPdfPreview({ bookmark }: { bookmark: ZBookmark }) {
   if (bookmark.content.type !== BookmarkTypes.LINK) {
     throw new Error("Wrong content type rendered");
@@ -65,6 +137,12 @@ export function BookmarkLinkReaderPreview({
 }) {
   const { isDarkColorScheme: isDark } = useColorScheme();
   const { settings: readerSettings } = useReaderSettings();
+  const lastSavedOffset = useRef<number | null>(null);
+  const currentPosition = useRef<{
+    offset: number;
+    anchor: string;
+    percent: number;
+  } | null>(null);
 
   const {
     data: bookmarkWithContent,
@@ -76,6 +154,66 @@ export function BookmarkLinkReaderPreview({
     includeContent: true,
   });
 
+  const apiUtils = api.useUtils();
+  const { mutate: updateProgress } =
+    api.bookmarks.updateReadingProgress.useMutation({
+      onSuccess: () => {
+        apiUtils.bookmarks.getBookmark.invalidate({ bookmarkId: bookmark.id });
+      },
+      onError: (error) => {
+        console.error("[ReadingProgress] Failed to save progress:", error);
+      },
+    });
+
+  // Save progress function
+  const saveProgress = useCallback(() => {
+    if (currentPosition.current === null) return;
+
+    const { offset, anchor, percent } = currentPosition.current;
+
+    // Only save if offset has changed
+    if (lastSavedOffset.current !== offset) {
+      lastSavedOffset.current = offset;
+      updateProgress({
+        bookmarkId: bookmark.id,
+        readingProgressOffset: offset,
+        readingProgressAnchor: anchor,
+        readingProgressPercent: percent,
+      });
+    }
+  }, [bookmark.id, updateProgress]);
+
+  // Handle messages from WebView
+  const handleMessage = useCallback((event: WebViewMessageEvent) => {
+    try {
+      const data = JSON.parse(event.nativeEvent.data);
+      if (data.type === "SCROLL_PROGRESS" && typeof data.offset === "number") {
+        currentPosition.current = {
+          offset: data.offset,
+          anchor: typeof data.anchor === "string" ? data.anchor : "",
+          percent: typeof data.percent === "number" ? data.percent : 0,
+        };
+      }
+    } catch (error) {
+      console.warn("[ReadingProgress] Failed to parse WebView message:", error);
+    }
+  }, []);
+
+  // Save on AppState change (app going to background)
+  useEffect(() => {
+    const subscription = AppState.addEventListener("change", (status) => {
+      if (status === "background" || status === "inactive") {
+        saveProgress();
+      }
+    });
+
+    return () => {
+      // Save on unmount
+      saveProgress();
+      subscription.remove();
+    };
+  }, [saveProgress]);
+
   if (isLoading) {
     return <FullPageSpinner />;
   }
@@ -92,6 +230,14 @@ export function BookmarkLinkReaderPreview({
   const fontSize = readerSettings.fontSize;
   const lineHeight = readerSettings.lineHeight;
 
+  // Get initial position for restoration
+  const initialOffset = bookmarkWithContent.content.readingProgressOffset ?? 0;
+  const initialAnchor =
+    bookmarkWithContent.content.readingProgressAnchor ?? null;
+
+  // Build the reading progress script with initial position
+  const injectedJS = buildReadingProgressScript(initialOffset, initialAnchor);
+
   return (
     <View className="flex-1 bg-background">
       <WebView
@@ -111,6 +257,7 @@ export function BookmarkLinkReaderPreview({
                       margin: 0;
                       padding: 16px;
                       background: ${isDark ? "#000000" : "#ffffff"};
+                      ${initialOffset > 0 ? "opacity: 0;" : ""}
                     }
                     p { margin: 0 0 1em 0; }
                     h1, h2, h3, h4, h5, h6 { margin: 1.5em 0 0.5em 0; line-height: 1.2; }
@@ -156,6 +303,8 @@ export function BookmarkLinkReaderPreview({
         showsVerticalScrollIndicator={false}
         showsHorizontalScrollIndicator={false}
         decelerationRate={0.998}
+        injectedJavaScript={injectedJS}
+        onMessage={handleMessage}
       />
     </View>
   );

apps/web/app/reader/[bookmarkId]/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Suspense, useState } from "react";
+import { Suspense, useCallback, useRef, useState } from "react";
 import { useParams, useRouter } from "next/navigation";
 import HighlightCard from "@/components/dashboard/highlights/HighlightCard";
 import ReaderSettingsPopover from "@/components/dashboard/preview/ReaderSettingsPopover";
@@ -12,6 +12,7 @@ import { useReaderSettings } from "@/lib/readerSettings";
 import { HighlighterIcon as Highlight, Printer, X } from "lucide-react";
 import { useSession } from "next-auth/react";
 
+import { useReadingProgress } from "@karakeep/shared-react/hooks/reading-progress";
 import { api } from "@karakeep/shared-react/trpc";
 import { BookmarkTypes } from "@karakeep/shared/types/bookmarks";
 import { READER_FONT_FAMILIES } from "@karakeep/shared/types/readers";
@@ -20,6 +21,7 @@ import { getBookmarkTitle } from "@karakeep/shared/utils/bookmarkUtils";
 export default function ReaderViewPage() {
   const params = useParams<{ bookmarkId: string }>();
   const bookmarkId = params.bookmarkId;
+  const contentRef = useRef<HTMLDivElement>(null);
   const { data: highlights } = api.highlights.getForBookmark.useQuery({
     bookmarkId,
   });
@@ -33,6 +35,29 @@ export default function ReaderViewPage() {
   const [showHighlights, setShowHighlights] = useState(false);
   const isOwner = session?.user?.id === bookmark?.userId;
 
+  // Track when content is ready for reading progress restoration
+  const [contentReady, setContentReady] = useState(false);
+  const handleContentReady = useCallback(() => setContentReady(true), []);
+
+  // Get initial reading progress from bookmark content
+  const initialOffset =
+    bookmark?.content.type === BookmarkTypes.LINK
+      ? bookmark.content.readingProgressOffset
+      : null;
+  const initialAnchor =
+    bookmark?.content.type === BookmarkTypes.LINK
+      ? bookmark.content.readingProgressAnchor
+      : null;
+
+  // Auto-save reading progress on page unload/visibility change
+  const { isReady: isReadingPositionReady } = useReadingProgress({
+    bookmarkId,
+    initialOffset,
+    initialAnchor,
+    containerRef: contentRef,
+    contentReady,
+  });
+
   const onClose = () => {
     if (window.history.length > 1) {
       router.back();
@@ -122,14 +147,20 @@ export default function ReaderViewPage() {
                 <Suspense fallback={<FullPageSpinner />}>
                   <div className="overflow-x-hidden">
                     <ReaderView
-                      className="prose prose-neutral max-w-none break-words dark:prose-invert [&_code]:break-all [&_img]:h-auto [&_img]:max-w-full [&_pre]:overflow-x-auto [&_table]:block [&_table]:overflow-x-auto"
+                      ref={contentRef}
+                      className="prose prose-neutral max-w-none break-words dark:prose-invert [&_blockquote]:scroll-mt-16 [&_code]:break-all [&_h1]:scroll-mt-16 [&_h2]:scroll-mt-16 [&_h3]:scroll-mt-16 [&_h4]:scroll-mt-16 [&_h5]:scroll-mt-16 [&_h6]:scroll-mt-16 [&_img]:h-auto [&_img]:max-w-full [&_li]:scroll-mt-16 [&_p]:scroll-mt-16 [&_pre]:overflow-x-auto [&_table]:block [&_table]:overflow-x-auto"
                       style={{
                         fontFamily: READER_FONT_FAMILIES[settings.fontFamily],
                         fontSize: `${settings.fontSize}px`,
                         lineHeight: settings.lineHeight,
+                        // Hide content until reading position is restored to prevent flicker
+                        visibility: isReadingPositionReady
+                          ? "visible"
+                          : "hidden",
                       }}
                       bookmarkId={bookmarkId}
                       readOnly={!isOwner}
+                      onContentReady={handleContentReady}
                     />
                   </div>
                 </Suspense>

apps/web/components/dashboard/preview/BookmarkHtmlHighlighter.tsx

@@ -1,4 +1,10 @@
-import React, { useEffect, useRef, useState } from "react";
+import React, {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
 import { ActionButton } from "@/components/ui/action-button";
 import { Button } from "@/components/ui/button";
 import { Popover, PopoverContent } from "@/components/ui/popover";
@@ -142,17 +148,26 @@ interface HTMLHighlighterProps {
   onDeleteHighlight?: (highlight: Highlight) => void;
 }
 
-function BookmarkHTMLHighlighter({
-  htmlContent,
-  className,
-  style,
-  highlights = [],
-  readOnly = false,
-  onHighlight,
-  onUpdateHighlight,
-  onDeleteHighlight,
-}: HTMLHighlighterProps) {
+const BookmarkHTMLHighlighter = forwardRef<
+  HTMLDivElement,
+  HTMLHighlighterProps
+>(function BookmarkHTMLHighlighter(
+  {
+    htmlContent,
+    className,
+    style,
+    highlights = [],
+    readOnly = false,
+    onHighlight,
+    onUpdateHighlight,
+    onDeleteHighlight,
+  },
+  ref,
+) {
   const contentRef = useRef<HTMLDivElement>(null);
+
+  // Expose the content div ref to parent components
+  useImperativeHandle(ref, () => contentRef.current!, []);
   const [menuPosition, setMenuPosition] = useState<{
     x: number;
     y: number;
@@ -408,6 +423,6 @@ function BookmarkHTMLHighlighter({
       />
     </div>
   );
-}
+});
 
 export default BookmarkHTMLHighlighter;

apps/web/components/dashboard/preview/BookmarkPreview.tsx

@@ -217,16 +217,13 @@ export default function BookmarkPreview({
           {detailsSection}
         </div>
       </div>
-
       {/* Render tabbed layout for narrow/vertical screens */}
       <Tabs
         value={activeTab}
         onValueChange={setActiveTab}
         className="flex h-full w-full flex-col overflow-hidden lg:hidden"
       >
-        <TabsList
-          className={`sticky top-0 z-10 grid h-auto w-full grid-cols-2`}
-        >
+        <TabsList className="sticky top-0 z-10 grid h-auto w-full grid-cols-2">
           <TabsTrigger value="content">{t("preview.tabs.content")}</TabsTrigger>
           <TabsTrigger value="details">{t("preview.tabs.details")}</TabsTrigger>
         </TabsList>