Merge develop into main: release v1.7.2

Author: Gnathonic

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.7.2] - 2026-06-13
+
+### Added
+
+- "Fill screen" zoom mode: fills one axis, overflows the other (#231)
+
+### Fixed
+
+- Keep Zoom and Original Size no longer pin pages to the top (#231)
+- Offset spreads button works again (#231)
+- "Zoom to fit" now works in continuous scroll mode (#231)
+- Night mode, invert, B&W, and OCR toggles show the correct state (#231)
+- WebDAV logins no longer silently fall back to anonymous (#229)
+
+### Changed
+
+- Continuous "Fit to width" is now "Fill screen" (#231)
+
 ## [1.7.1] - 2026-06-10
 
 ### Fixed

CLAUDE.md

@@ -215,13 +215,16 @@ Tracked per volume in the `volumes` store:
 - Time spent reading (tracked by Timer component)
 - Last read date and current page
 
-### Text Selection Handling
+### Reader Input Handling
 
-The reader has complex text selection logic to prevent interference with drag panning:
+All reader gesture handling (pan, pinch, tap, swipe, wheel, keyboard) goes
+through the shared modules in `src/lib/reader/input/` — see
+**`docs/INPUT-CONTRACTS.md`** for the architecture and the contracts that
+must not break. Highlights:
 
-- Pointer handlers skip pan initiation for `.textBox` targets (PagedViewport.svelte and the scroll readers), so text selection works inside boxes
-- Double-clicking text to select it does not trigger zoom (`.textBox` guard in Reader's onDoubleTap)
-- Text selection is only allowed within text boxes, not on background
+- `.textBox` is an input-routing protocol: double-tap there is the AnkiConnect capture gesture, mouse/pen drags are text selection (Yomitan/Migaku) — never pans, never zoom
+- Each surface owns its gestures via `PointerGestureTracker` config; Reader owns only keyboard + intent callbacks
+- Before starting any motion, handlers call their surface's `MotionGate` intent method instead of ad-hoc `finishNow()`/`stop()` combinations
 
 ### Modal Button Z-Index
 

docs/INPUT-CONTRACTS.md

@@ -0,0 +1,123 @@
+# Reader Input Contracts
+
+How user input flows through the reader, and the contracts every input
+handler must respect. The modules in `src/lib/reader/input/` are the
+load-bearing implementation of this document — their doc comments carry the
+details; this file is the map.
+
+## Architecture
+
+```
+                        ┌─────────────────────────────┐
+                        │   Reader.svelte             │
+                        │   keyboard shortcuts,       │
+                        │   page-flip + overlay       │
+                        │   intents, volume nav       │
+                        └─────────┬───────────────────┘
+              props (callbacks)   │   keyboard / $pagedZoom
+        ┌─────────────────────────┼─────────────────────────┐
+        ▼                         ▼                         ▼
+┌───────────────┐        ┌───────────────┐        ┌───────────────────┐
+│ PagedViewport │        │ VerticalScroll │       │ HorizontalScroll  │
+│               │        │ Reader         │       │ Reader            │
+└───────┬───────┘        └───────┬───────┘        └─────────┬─────────┘
+        │     each surface owns ALL of its pointer input    │
+        ▼                        ▼                          ▼
+   PointerGestureTracker · TapDiscriminator · classifySwipe · MotionGate
+                  (src/lib/reader/input/ — shared machinery)
+```
+
+Each reading surface owns every gesture that starts on it. Reader owns
+keyboard shortcuts and supplies intent callbacks (`onPageFlip`,
+`onOverlayToggle`); it never touches pointer events.
+
+## The shared machinery
+
+| Module               | Owns                                                                                                                                                 |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pointer-tracker.ts` | THE pointer state machine: pan threshold, pinch upgrade/downgrade/re-baseline, capture policy, leak-proof window-level release, `wasDrag`/`wasPinch` |
+| `gesture-target.ts`  | Element-role classification (`textbox` / `interactive` / `page`) and the keyboard-ignore guard                                                       |
+| `tap.ts`             | Tap vs double-tap timing (300 ms), deferred vs immediate commit, text-box dismissal swallowing                                                       |
+| `swipe.ts`           | Pure swipe-to-flip classification (edge gating #186, pinch suppression, thresholds)                                                                  |
+| `motion-gate.ts`     | The interrupt contract: what must stop before new motion starts (`beforeZoom` / `beforeManualPan` / `beforeAnimatedScroll` / `beforeNav`)            |
+
+Surfaces hold only **policy** (config objects) and **actuation** (scroll
+writes, camera moves); classification and lifecycle live in the shared
+modules.
+
+## Contracts that must not break
+
+### `.textBox` is an input-routing protocol, not styling
+
+OCR text boxes own their gestures (see `gesture-target.ts`):
+
+- **Double-tap on a text box is the AnkiConnect card-capture gesture.**
+  TextBoxes.svelte handles it and `stopPropagation()`s; surfaces must also
+  filter taps by role so pointer-based detection never zooms from a text
+  box. Breaking this breaks users' Anki mining flow.
+- Mouse/pen drags on a text box are **text selection** (Yomitan/Migaku
+  scanning) — never a pan. Single-finger **touch** is the exception: it
+  pans everywhere, because touch has no drag-selection gesture.
+- After interacting with a text box, the next tap outside is a
+  **dismissal** — it must not toggle the overlay
+  (`TapDiscriminator.noteTextBoxInteraction`).
+
+### Pinch always wins
+
+Two pointers upgrade to pinch no matter where they pressed (text box
+included). Pointer-set changes re-baseline; dropping to one pointer
+ends the pinch. The survivor continues as a pan only on surfaces with
+incremental deltas (`pinchSurvivorPans` — paged); absolute-baseline
+surfaces (scroll readers) require a fresh press.
+
+### Releases are window-level
+
+`pointerup`/`pointercancel` listen on the window, always. A release landing
+on an overlay or outside the browser must still clean the pointer map —
+phantom entries get misread as pinches (this was a live production bug).
+
+### One gesture at a time (MotionGate)
+
+Every handler that starts motion opens with the gate call matching its
+intent. Never call `finishNow`/`stop`/`stopPan` combinations inline — add
+to the gate if a new intent appears.
+
+### Swipe-to-flip is edge-gated (#186)
+
+A touch swipe flips the page only if no pannable content was hidden in the
+swipe's direction **when the gesture began**. Gestures that pinched never
+flip (`tracker.wasPinch`).
+
+### Tap timing differs by surface family — deliberately
+
+- Scroll readers: **deferred** — overlay toggles 300 ms late so a
+  double-tap (zoom) never flashes it.
+- Paged: **immediate** — overlay toggles instantly on every tap; a
+  double-tap toggles twice (net zero) and zooms, reproducing the native
+  click/click/dblclick sequence paged mode has always had.
+
+### Settle reasons gate progress reporting
+
+Zoom settles carry a `SettleReason` (`zoom-controller.ts`): only
+`'gesture'`/`'interrupt'` settles report reading progress; `'nav'` and
+`'reset'` settles are superseded by whatever caused them.
+
+## Per-surface policy matrix
+
+| Policy         | PagedViewport                     | Scroll readers                          |
+| -------------- | --------------------------------- | --------------------------------------- |
+| Capture        | deferred (at drag threshold)      | immediate (at pan press)                |
+| Pan deltas     | incremental → `camera.adjustView` | totals → absolute scroll from baselines |
+| Text-box pan   | suppressed for mouse/pen only     | suppressed for all pointer types        |
+| Pinch survivor | keeps panning                     | ignored until fresh press               |
+| Tap commit     | immediate                         | deferred (300 ms)                       |
+| Swipe-to-flip  | yes (mobile setting, edge-gated)  | no (panning is the scroll)              |
+| Wheel          | zoom or camera glide              | zoom or (native/strip) scroll           |
+
+## Testing
+
+Unit tests cover the shared machinery (`src/lib/reader/input/*.test.ts`,
+`src/lib/reader/page-nav.test.ts`); Playwright e2e covers zoom geometry
+(`e2e/zoom.spec.ts`). When changing gesture behavior, test manually with a
+Japanese-learning extension (Yomitan/Migaku) enabled and verify the Anki
+double-tap flow still captures.

e2e/zoom.spec.ts

@@ -574,6 +574,58 @@ test('paged keepZoom: effective scale survives a content swap (spread)', async (
   expect(r.effectiveAfter).toBeCloseTo(r.effectiveBefore, 3);
 });
 
+test('paged fillScreen: tall page fills the width and pans to the bottom; small pages center', async ({
+  page
+}) => {
+  await setupPagedWorld(page, { rtl: true, mode: 'zoomFillScreen' });
+  const r = await page.evaluate(async () => {
+    const z = (window as any).__paged;
+    // 1400x2000 page: taller than the viewport aspect → width must fill.
+    const rect0 = z.pageEl.getBoundingClientRect();
+    const widthFills = Math.abs(rect0.width - innerWidth) < 1.5;
+    const startsAtTop = Math.abs(rect0.top) < 1.5;
+
+    // The overflowing height is pannable all the way to the bottom edge.
+    z.camera.adjustView(0, rect0.height * 2); // grossly past the end — clamps
+    const rect1 = z.pageEl.getBoundingClientRect();
+    const bottomReachable = Math.abs(rect1.bottom - innerHeight) < 1.5;
+
+    // A page smaller than the viewport centers — never welded to the corner
+    // (the keepZoom/original top-pin bug class).
+    z.pageEl.style.width = '400px';
+    z.pageEl.style.height = '300px';
+    z.applyBase({ width: 400, height: 300 });
+    z.controller.snapToLevel(z.session.pagedLevels(z.state.baseScale, z.state.fitScale)[0]);
+    const rect2 = z.pageEl.getBoundingClientRect();
+    const centeredX = Math.abs(rect2.left - (innerWidth - rect2.width) / 2) < 1.5;
+    return { widthFills, startsAtTop, bottomReachable, centeredX, w: rect2.width };
+  });
+  expect(r.widthFills).toBe(true);
+  expect(r.startsAtTop).toBe(true);
+  expect(r.bottomReachable).toBe(true);
+  expect(r.centeredX).toBe(true);
+});
+
+test('paged zoomOriginal: a page smaller than the viewport centers and zooming out never pins it', async ({
+  page
+}) => {
+  await setupPagedWorld(page, { rtl: true, mode: 'zoomOriginal' });
+  const r = await page.evaluate(async () => {
+    const z = (window as any).__paged;
+    // Swap in a page smaller than the viewport at 1:1.
+    z.pageEl.style.width = '600px';
+    z.pageEl.style.height = '500px';
+    z.applyBase({ width: 600, height: 500 });
+    const rect = z.pageEl.getBoundingClientRect();
+    return {
+      cx: rect.left + rect.width / 2,
+      cy: rect.top + rect.height / 2
+    };
+  });
+  expect(r.cx).toBeCloseTo(1920 / 2, 0);
+  expect(r.cy).toBeCloseTo(1080 / 2, 0);
+});
+
 test('vertical fit-to-screen: side margins are not pannable while zoomed', async ({ page }) => {
   // Narrow fixed-size pages (560px in a 1920px viewport): at 2x the scaled
   // content (1120px) still fits, so there must be NO horizontal scroll range

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "mokuro-reader",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "private": true,
   "scripts": {
     "dev": "vite dev",

package.json

@@ -140,3 +140,12 @@ input[type='radio']:checked::after {
   display: none !important;
   content: none !important;
 }
+
+/* Scrollable reader strips hide their scrollbars (used by both scroll readers). */
+.scrollbar-hide {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}