feat: improve reading layout and translation behavior

Add optional paragraph gap compaction and reading-ahead translation scheduling. Preserve cropped canvas clarity and annotation visibility, improve external application handoff, and refine settings navigation and controls.

Author: reycn

electron/main/ipc/preferences-ipc.mjs

@@ -23,6 +23,7 @@ const SETTINGS_PREFERENCES = [
   'reduceResourceUsage',
   'restoreDocuments',
   'interactionMode',
+  'optimizeParagraphGaps',
   'language',
   'sourceLanguage',
   'concurrency',

electron/main/menus/application-menu.mjs

@@ -68,12 +68,18 @@ export function createApplicationMenu({
         const receiver = target || focusedWindow();
         const currentPath = documentPath(receiver);
         if (!currentPath) return;
+        const source = registry.stateFor(receiver)?.unkeyedAnnotationSource;
+        const stillCurrent = () =>
+          !receiver.isDestroyed() &&
+          documentPath(receiver) === currentPath &&
+          registry.stateFor(receiver)?.unkeyedAnnotationSource === source;
         try {
           await validateSystemPDF(currentPath);
-          if (documentPath(receiver) !== currentPath || receiver.isDestroyed()) return;
+          if (!stillCurrent()) return;
           await receiver.webContents.executeJavaScript('window.previewSaveReadingView?.()');
-          if (documentPath(receiver) !== currentPath || receiver.isDestroyed()) return;
+          if (!stillCurrent()) return;
           await pdfApplications.open(choice, currentPath);
+          if (stillCurrent()) receiver.webContents.send('reader:action', 'close-document');
         } catch (error) {
           dialog.showErrorBox('PDFMathReader', error.message);
         }

electron/main/services/preferences.mjs

@@ -24,11 +24,12 @@ const DEFAULT_PREFERENCES = Object.freeze({
   columns: 1,
   fit: 'width',
   zoom: 1,
-  translationMode: 'reading',
+  translationMode: 'reading-ahead',
   autoCheckUpdates: true,
   cacheLimitMB: null,
   documentOpenMode: 'translation',
   interactionMode: 'reading',
+  optimizeParagraphGaps: false,
   restoreDocuments: true,
   formulaOcrEnabled: false,
   translationErrorDismissals: [],
@@ -232,6 +233,7 @@ const VALIDATORS = {
   cacheLimitMB: (value) => value === null || [512, 1024, 2048, 5120, 10240].includes(value),
   documentOpenMode: (value) => ['translation', 'original', 'manual'].includes(value),
   restoreDocuments: (value) => typeof value === 'boolean',
+  optimizeParagraphGaps: (value) => typeof value === 'boolean',
   reduceResourceUsage: (value) => typeof value === 'boolean',
   reduceBackgroundFrameRate: (value) => typeof value === 'boolean',
   reuseTranslations: (value) => typeof value === 'boolean',
@@ -249,7 +251,7 @@ const VALIDATORS = {
   columns: (value) => [1, 2, 4].includes(value),
   fit: (value) => ['width', 'height', 'manual'].includes(value),
   zoom: isValidZoom,
-  translationMode: (value) => ['full', 'reading'].includes(value),
+  translationMode: (value) => ['full', 'reading', 'reading-ahead'].includes(value),
   interactionMode: (value) => ['reading', 'comparison'].includes(value),
   interfaceStyle: (value) => ['default', 'liquid-glass'].includes(value),
   appearance: (value) => ['light', 'dark', 'system'].includes(value),
@@ -278,6 +280,7 @@ const VALIDATORS = {
 const VALIDATION_MESSAGES = {
   documentOpenMode: 'Invalid document opening mode',
   restoreDocuments: 'Invalid document restoration preference',
+  optimizeParagraphGaps: 'Invalid paragraph gap optimization preference',
   reuseTranslations: 'Invalid translation reuse preference',
   translationMode: 'Invalid translation mode',
   interactionMode: 'Invalid interaction mode',

src/App.vue

@@ -119,6 +119,7 @@ const {
   openRecent,
   openSearch,
   openSettings,
+  optimizeParagraphGaps,
   pageConcurrency,
   pageCrop,
   pageEntry,
@@ -528,6 +529,7 @@ const copyToastDetail = computed(() =>
       v-model:error="error"
       v-model:document-open-mode="documentOpenMode"
       v-model:interaction-mode="interactionMode"
+      v-model:optimize-paragraph-gaps="optimizeParagraphGaps"
       v-model:restore-documents="restoreDocuments"
       v-model:auto-hide-header="autoHideHeader"
       v-model:emphasize-topic-sentences="emphasizeTopicSentences"

src/app/useReaderWindow.mjs

@@ -1,3 +1,7 @@
+import {
+  createParagraphCompaction,
+  mapCompactY,
+} from '../features/reader/paragraph-compaction.mjs';
 import { installRenderDiagnostics } from '../features/reader/render-diagnostics.mjs';
 import { installReaderViewObservers } from '../features/reader/view-observers.mjs';
 import { installReaderPreferenceObservers } from '../features/settings/preference-observers.mjs';
@@ -59,6 +63,7 @@ export function useReaderWindow() {
     layoutVisible,
     reuseTranslations,
     interactionMode,
+    optimizeParagraphGaps,
     restoreDocuments,
     documentOpenMode,
     defaultPageCropEnabled,
@@ -327,6 +332,7 @@ export function useReaderWindow() {
     viewportPages: featureActions.viewportPages,
     scheduleViewport: featureActions.scheduleViewport,
     scheduleReadingSave: featureActions.scheduleReadingSave,
+    mapDisplayPage: (p) => displayedPage(p),
     importFile: featureActions.importFile,
     ensurePDF: featureActions.ensurePDF,
     active,
@@ -347,7 +353,7 @@ export function useReaderWindow() {
     searchPages,
     searchPageCount,
     searchHit,
-    displayedPage,
+    displayedPage: searchedPage,
     openSearch,
     closeSearch,
     scheduleSearch,
@@ -431,6 +437,44 @@ export function useReaderWindow() {
 
   // Display-only, total fraction removed symmetrically from each axis.
   const pageCrop = ref({ x: 0, y: 0 });
+  const compactParagraphPage = createParagraphCompaction({
+    enabled: computed(
+      () =>
+        preferences.optimizeParagraphGaps.value &&
+        direction.value === 'vertical' &&
+        columns.value === 1 &&
+        interactionMode.value === 'reading' &&
+        showTranslations.value,
+    ),
+    pages,
+    sourceDocument: () => session.pdf,
+    getDocument: (options) => session.getDocument(options),
+    changing: (page, result) => {
+      const el = reader.value,
+        number = active.value;
+      const host = renderState.pageEls.get(number);
+      if (!el || !host) return () => {};
+      const top = el.getBoundingClientRect().top;
+      const offset = top - host.getBoundingClientRect().top;
+      const mapped =
+        page.number === number
+          ? mapCompactY(offset / zoom.value, result.cuts) * zoom.value
+          : offset;
+      return () => {
+        const current = renderState.pageEls.get(number);
+        if (current && reader.value === el)
+          el.scrollTop += current.getBoundingClientRect().top + mapped - top;
+      };
+    },
+    changed: (restore) =>
+      nextTick(() => {
+        restore?.();
+        featureActions.renderPages(false, true);
+      }),
+  });
+  function displayedPage(p) {
+    return compactParagraphPage(searchedPage(p));
+  }
   // Read geometry only: spreading a reactive page subscribes the full-document
   // layout to visibility, translation and annotation updates on every scroll.
 
@@ -482,6 +526,11 @@ export function useReaderWindow() {
       labelKey: 'translation.reading',
       descriptionKey: 'translation.readingDescription',
     },
+    {
+      id: 'reading-ahead',
+      labelKey: 'translation.readingAhead',
+      descriptionKey: 'translation.readingAheadDescription',
+    },
   ];
 
   watch(translationMode, () => {
@@ -808,6 +857,7 @@ export function useReaderWindow() {
       emphasizeTopicSentences,
       showKernelToolbarShortcut,
       autoHideHeader,
+      optimizeParagraphGaps,
       kernelAdvancedOptions,
       translationServices,
       glossaries,
@@ -1013,6 +1063,7 @@ export function useReaderWindow() {
     informationCategories,
     informationCategorySettings,
     interactionMode,
+    optimizeParagraphGaps,
     kernelAdvancedOptions,
     kernelErrorVisible,
     kernelFailure,

src/app/window-lifecycle.mjs

@@ -116,7 +116,11 @@ export function installWindowLifecycle({ bindings, lifecycle }) {
       bindings.direction.value = saved.direction || 'vertical';
       bindings.columns.value = saved.columns || 1;
       bindings.fitMode.value = saved.fit;
-      bindings.translationMode.value = saved.translationMode || 'reading';
+      bindings.translationMode.value = ['full', 'reading', 'reading-ahead'].includes(
+        saved.translationMode,
+      )
+        ? saved.translationMode
+        : 'reading-ahead';
       if (saved.fit === 'manual') {
         bindings.zoom.value = saved.zoom;
         bindings.zoomEntry.value = formatPercentValue(bindings.zoom.value);

src/features/annotations/ReadingAnnotations.vue

@@ -33,6 +33,7 @@ function updatePopupLayout() {
 const props = defineProps({
   host: Function,
   page: Object,
+  crop: { type: Object, default: () => ({ x: 0, y: 0 }) },
   zoom: Number,
   annotations: Array,
   translated: Boolean,
@@ -154,7 +155,7 @@ const noteRail = computed(() => {
           : b.sourceBox) || b;
       right = Math.max(right, box.x + box.width);
     }
-  return annotationRailX(props.page.width, right, props.zoom);
+  return annotationRailX(props.page.width, right, props.zoom, props.crop);
 });
 watch(noteRail, (x) => emit('rail', x), { immediate: true });
 function baseNoteRect(a) {
@@ -163,13 +164,15 @@ function baseNoteRect(a) {
     box = translated ? b?.translatedBox || b : b?.sourceBox || b;
   const line = a.rects[0],
     anchor = box || line,
-    markerSize = 34 / props.zoom;
+    markerSize = 34 / props.zoom,
+    top = (props.page.height * props.crop.y) / 2,
+    bottom = props.page.height - top;
   return {
     x: noteRail.value,
     y: Math.max(
-      0,
+      top,
       Math.min(
-        props.page.height - markerSize,
+        bottom - markerSize,
         anchor.y + (Math.min(line.height, anchor.height) - markerSize) / 2,
       ),
     ),
@@ -189,6 +192,7 @@ const notePositions = computed(() =>
       .map((a) => ({ id: a.id, y: baseNoteRect(a).y })),
     props.page.height,
     props.zoom,
+    props.crop.y,
   ),
 );
 function noteRect(a) {

src/features/annotations/annotation-display.mjs

@@ -30,28 +30,32 @@ export function annotationLineRects(rects) {
 }
 
 // Keep every marker on the same page rail, with a screen-space edge inset.
-export function annotationRailX(pageWidth, textRight, zoom) {
+export function annotationRailX(pageWidth, textRight, zoom, crop = { x: 0, y: 0 }) {
   const size = 34 / zoom,
     gap = 8 / zoom,
-    limit = Math.max(0, pageWidth - size - gap);
-  return Math.max(0, Math.min(limit, textRight + gap));
+    left = (pageWidth * crop.x) / 2,
+    right = pageWidth - left,
+    limit = Math.max(left, right - size - gap);
+  return crop.x ? limit : Math.max(left, Math.min(limit, textRight + gap));
 }
 
 // Pack markers down the shared rail, then pull back from the page bottom.
-export function annotationNotePositions(notes, pageHeight, zoom) {
+export function annotationNotePositions(notes, pageHeight, zoom, cropY = 0) {
   const sorted = notes
     .map((n) => ({ ...n }))
     .sort((a, b) => a.y - b.y || String(a.id).localeCompare(String(b.id)));
   const size = 34 / zoom,
-    gap = 6 / zoom;
+    gap = 6 / zoom,
+    top = (pageHeight * cropY) / 2,
+    bottom = pageHeight - top;
   for (let i = 0; i < sorted.length; i++)
-    sorted[i].y = Math.max(sorted[i].y, i ? sorted[i - 1].y + size + gap : 0);
+    sorted[i].y = Math.max(sorted[i].y, i ? sorted[i - 1].y + size + gap : top);
   if (sorted.length) {
-    sorted.at(-1).y = Math.min(sorted.at(-1).y, Math.max(0, pageHeight - size));
+    sorted.at(-1).y = Math.min(sorted.at(-1).y, Math.max(top, bottom - size));
     for (let i = sorted.length - 2; i >= 0; i--)
       sorted[i].y = Math.min(sorted[i].y, sorted[i + 1].y - size - gap);
   }
-  return new Map(sorted.map((n) => [n.id, Math.max(0, n.y)]));
+  return new Map(sorted.map((n) => [n.id, Math.max(top, n.y)]));
 }
 
 // Shared search and annotation spacing in screen pixels.

src/features/developer/DeveloperOptions.vue

@@ -88,12 +88,17 @@ async function toggleDeveloper(enabled) {
         />
       </div>
       <p class="muted">{{ dt('developerHint') }}</p>
-      <AppButton v-if="developerEnabled" :disabled="developerBusy" @click="toggleDeveloper(true)">{{
-        dt('openWindow')
-      }}</AppButton>
-      <AppButton class="install-guide-trigger" @click="openInstallGuide">{{
-        zh() ? '调试安装引导…' : 'Debug installation guide…'
-      }}</AppButton>
+      <div class="developer-entry-actions">
+        <AppButton
+          v-if="developerEnabled"
+          :disabled="developerBusy"
+          @click="toggleDeveloper(true)"
+          >{{ dt('openWindow') }}</AppButton
+        >
+        <AppButton class="install-guide-trigger" @click="openInstallGuide">{{
+          zh() ? '调试安装引导…' : 'Debug installation guide…'
+        }}</AppButton>
+      </div>
       <Teleport to="body">
         <dialog
           ref="installDialog"
@@ -146,8 +151,18 @@ async function toggleDeveloper(enabled) {
   margin-bottom: 8px;
   border-bottom: 1px solid color-mix(in srgb, currentColor 12%, transparent);
 }
-.install-guide-trigger {
-  margin-top: 8px;
+.developer-entry-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding-block: 4px;
+}
+.developer-entry-actions > :deep(*) {
+  flex: 0 1 auto;
+  width: auto;
+  max-width: 100%;
+  margin: 0;
 }
 .install-guide-dialog {
   width: min(560px, calc(100vw - 40px));

src/features/reader/FormulaOcrRegion.vue

@@ -1,9 +1,10 @@
 <script setup>
-import { inject, ref, computed, onBeforeUnmount } from 'vue';
+import { inject, ref, computed, onBeforeUnmount, useId } from 'vue';
 import { formulaOcrLabel } from './formula-ocr-labels.mjs';
 const props = defineProps({ source: Function, box: Object, zoom: Number });
 const ocr = inject('formulaOcr', null);
 const busy = ref(false);
+const hintId = useId();
 const enabled = computed(() => ocr?.enabled.value === true);
 const controller = new AbortController();
 let rendering,
@@ -65,7 +66,7 @@ onBeforeUnmount(() => {
       <button
         class="formula-ocr-button"
         :disabled="busy"
-        :title="formulaOcrLabel('recognize')"
+        :aria-describedby="hintId"
         :aria-label="formulaOcrLabel(busy ? 'recognizing' : 'recognize')"
         :aria-busy="busy"
         @click.stop="recognize"
@@ -79,6 +80,9 @@ onBeforeUnmount(() => {
           aria-hidden="true"
         ></span>
       </button>
+      <span :id="hintId" class="formula-ocr-hint" role="tooltip">
+        {{ formulaOcrLabel(busy ? 'recognizing' : 'recognize') }}
+      </span>
     </div>
   </div>
 </template>
@@ -123,6 +127,29 @@ onBeforeUnmount(() => {
   cursor: pointer;
   pointer-events: auto;
 }
+.formula-ocr-hint {
+  position: absolute;
+  right: 3px;
+  top: 39px;
+  z-index: 1;
+  padding: 5px 9px;
+  border: 1px solid var(--separator, #8883);
+  border-radius: 7px;
+  background: var(--surface, #f5f5f5);
+  color: var(--text);
+  box-shadow: 0 3px 12px #0002;
+  font-size: 12px;
+  line-height: 1.4;
+  white-space: nowrap;
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+}
+.formula-ocr-button:hover + .formula-ocr-hint,
+.formula-ocr-button:focus-visible + .formula-ocr-hint {
+  opacity: 1;
+  visibility: visible;
+}
 .formula-ocr-button progress {
   width: 19px;
   height: 5px;