xiaoxue_admin
/
orca
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
orca/docs/image-viewer-pinch-zoom.md

9.6 KiB
Raw Blame History

Image Viewer Pinch Zoom

Problem

  • src/renderer/src/components/editor/ImageViewer.tsx:27 stores viewer zoom and exposes toolbar zoom controls.
  • src/renderer/src/components/editor/ImageViewer.tsx:106 renders the inline image surface without a wheel handler.
  • src/renderer/src/components/editor/ImageViewer.tsx:198 renders the popup image surface without a wheel handler.
  • On Chromium/Electron, trackpad pinch gestures arrive as wheel events with ctrlKey: true; the viewer does not intercept them, so users cannot pinch to zoom the image in or out.

Root Cause

ImageViewer only changes zoom through button clicks. The image surfaces let ctrl-wheel events bubble/default, so pinch gestures never update zoom and may be consumed by Chromium-level page zoom instead. The inline surface is scrollable only in fill layout; in intrinsic layout it is overflow-visible, so the fix must not depend on scrollability.

Non-goals

  • Do not redesign the image viewer chrome or add new controls.
  • Do not change PDF handling; application/pdf still delegates to PdfViewer.
  • Do not implement pan/drag or persistent per-file zoom.
  • Do not change image loading, file IPC, or SSH/runtime preview fetching.

Design

  1. Add pure zoom helpers in a concrete renderer module such as image-viewer-zoom.ts so the math can be tested under the repo's node-based Vitest setup:
    • clampZoom(next) clamps to the existing MIN_ZOOM and MAX_ZOOM.
    • shouldHandleImageZoomWheel(eventLike) returns true only for ctrl-wheel input.
    • getPinchZoomFactor(deltaY, deltaMode) normalizes pixel/line/page wheel deltas and returns a bounded multiplier; deltaY === 0 should not change zoom.
    • getNextWheelZoom(currentZoom, deltaY, deltaMode) applies the factor and clamp without touching React state.
  2. Add an applyZoomChange(fn) wrapper inside ImageViewer that uses functional setZoom, and reset zoom to 1 when filePath, mimeType, or cleanedContent changes. EditorContent can reuse the same ImageViewer component position across image files, so local zoom must not accidentally carry across file switches or external reloads.
  3. Add refs for the inline image surface and popup image surface. Bind native wheel listeners with { passive: false }, not React onWheel; this repo already uses native non-passive wheel listeners where Chromium default prevention must be reliable. Keep the listener callback stable enough that it is not rebound on every zoom tick.
  4. The wheel handler must:
    • ignore ordinary wheel/trackpad scroll;
    • handle only event.ctrlKey wheel events, which Chromium/Electron uses for trackpad pinch and Ctrl+wheel zoom;
    • call preventDefault() and stopPropagation() for every handled ctrl-wheel event, including when already clamped, so browser/app zoom does not also change;
    • map negative deltaY to zoom in and positive deltaY to zoom out;
    • use the bounded delta-scaled multiplier instead of applying the full toolbar ZOOM_STEP once per wheel event.
  5. Attach the listener to both image surfaces, not to document or window, so editor/terminal/browser panes outside the image viewer keep their existing wheel behavior. The popup listener must attach after the Radix dialog content mounts and clean up when it unmounts; a callback ref or an effect keyed by isPopupOpen is acceptable.
  6. Keep existing toolbar buttons wired through the same clamp helper.

Data Flow

  • Trackpad pinch over image surface
  • Chromium emits WheelEvent with ctrlKey
  • Native non-passive wheel listener intercepts it
  • zoom state updates
  • Existing inline and popup image transforms render at the new scale
  • Footer percent updates from zoomPercent
  • When the rendered file changes, zoom resets to 1 while object URL creation/revocation stays on the existing path

Edge Cases

  • Ordinary scrolling without ctrlKey must still scroll the image surface.
  • Pinch gestures at MIN_ZOOM or MAX_ZOOM must stay clamped.
  • Ctrl-wheel at MIN_ZOOM or MAX_ZOOM must still prevent default browser zoom.
  • Popup and inline surfaces within one ImageViewer must stay in sync because they share one zoom state.
  • Image diff panes each mount their own ImageViewer; pinch over one side should only zoom that side. Do not introduce cross-pane sync in this fix.
  • layout="intrinsic" must receive pinch events even though the inline surface is not an overflow scroller.
  • Ctrl-wheel over the footer toolbar should keep existing button behavior and not become a hidden zoom target; the listener belongs on the image surface only.
  • PDF previews must remain unaffected.
  • The behavior must work for local and SSH-backed images because it is renderer-only after bytes are loaded.
  • Windows/Linux touchpads that also surface pinch as ctrlKey wheel events should work without platform-specific branches.
  • File switches, file reloads, external file mutations, and multi-window sessions should not add shared state: zoom remains local to the mounted viewer, resets for new loaded image content, object URL cleanup remains unchanged, and native wheel listeners must be removed on unmount/remount.
  • Existing CSS transform zoom does not resize the scrollable layout box. Do not try to solve transform-origin panning or full-image scroll extents in this change; keep pinch behavior consistent with the existing toolbar zoom.

Test Plan

  • Unit tests: cover the extracted zoom helpers under the existing node Vitest config; this repo does not currently include jsdom, happy-dom, or Testing Library, so do not promise DOM component tests unless that tooling is deliberately added.
  • Unit tests: assert negative/positive/zero deltaY, pixel/line/page deltaMode normalization, min/max clamping, and bounded per-event zoom factors.
  • Unit tests: assert the wheel decision helper ignores non-ctrl wheel events and treats ctrl-wheel as handled even when the resulting zoom is already clamped or deltaY is 0.
  • Electron validation: open a PNG in Orca, dispatch a cancelable WheelEvent with ctrlKey on the inline image surface, verify the displayed percent and visual scale change, and verify an ordinary wheel still scrolls where applicable.
  • Electron validation: open popup and repeat after the dialog mounts; close/reopen the popup and repeat once to catch duplicate or stale native listeners.
  • Electron validation: open an image diff and verify ctrl-wheel on one pane changes only that pane's percent.
  • Electron validation: switch from one image file to another or reload changed image content and verify zoom returns to 100%.

UI Quality Bar

Pinch zoom should feel like an existing viewer capability rather than a new UI surface: no layout shift, no new visible controls, footer percent remains stable, ordinary scrolling remains available, zoom changes are not jumpy under high-frequency trackpad events, and the popup chrome matches the current image viewer styling.

Review Screenshots

  1. Inline image viewer at default 100%.
  2. Inline image viewer after pinch zoom in, showing a higher footer percent.
  3. Popup image viewer after pinch zoom out/in, showing the same percent as the inline viewer for that ImageViewer.
  4. Image diff viewer after pinch zooming only one pane, showing the other pane unchanged.
  5. Adjacent smoke state: normal editor/file surface still renders after closing the popup.

Rollout

  1. Add wheel/pinch zoom handling to ImageViewer.
  2. Add focused tests for the pinch handler behavior.
  3. Run typecheck, lint, and relevant renderer tests.
  4. Validate in Electron and capture screenshots.

Lightweight Eng Review

  • Scope: kept to ImageViewer gesture handling and focused tests; no new viewer state model, persistence, or chrome changes.
  • Architecture/data flow: renderer-only DOM wheel handling updates existing zoom state; no main-process, IPC, SSH, runtime, or persistence boundary changes.
  • Failure modes covered:
    • ordinary wheel scroll accidentally blocked;
    • browser/app zoom also responding to pinch;
    • zoom exceeding existing min/max;
    • popup and inline surfaces diverging;
    • diff panes being accidentally synchronized;
    • native listener leaks or duplicate listeners after popup open/close;
    • stale zoom state under rapid wheel event bursts;
    • accidental zoom carryover across image file switches or external reloads;
    • PDF previews accidentally receiving image gesture behavior.
  • Test coverage required:
    • node unit tests for extracted zoom math and wheel-decision helpers;
    • Electron validation for native listener default-prevention behavior, popup wheel handling, diff-pane isolation, and zoom reset on image content changes;
    • screenshot validation for inline default, inline zoomed, popup zoomed, image-diff isolation, and adjacent editor state.
  • Performance/blast radius: low but not free; trackpads emit many wheel events, so the handler must do O(1) work, use functional state updates, avoid layout reads, and avoid document/window listeners. Blast radius stays inside mounted ImageViewer instances.
  • UI quality bar: no new visible UI; existing footer percent and scrollable image surface should remain visually stable.
  • Required review screenshots:
    1. Inline image viewer at 100%.
    2. Inline image viewer after pinch-equivalent zoom in.
    3. Popup image viewer after pinch-equivalent zoom.
    4. Image diff viewer after pinch-equivalent zoom on one pane only.
    5. Editor/file surface after closing popup.
  • Residual risks: automated Electron validation can dispatch cancelable ctrl-wheel DOM events against the listener, but it does not fully prove OS-level physical trackpad pinch behavior or Chromium's browser-zoom default path. A manual trackpad smoke test is still the final confidence check when hardware is available.