Fix

Author: sheepla

e2e/specs/taurus-viewer.spec.ts

@@ -169,6 +169,14 @@ describe("TaurusViewer E2E Test Suite", () => {
     });
   }
 
+  async function pdfScrollTop(): Promise<number> {
+    return browser.execute(() => {
+      const first = document.querySelector('[data-page-index="0"]');
+      const container = first?.closest(".overflow-auto") as HTMLElement | null;
+      return container?.scrollTop ?? -1;
+    });
+  }
+
   async function getContainerPosition(): Promise<number> {
     return browser.execute(() => {
       const v = document.querySelector("foliate-view") as any;
@@ -652,4 +660,85 @@ describe("TaurusViewer E2E Test Suite", () => {
       },
     );
   });
+
+  it("should open the command palette via the palette button", async () => {
+    const paletteBtn = await $('button[aria-label="Open command palette"]');
+    await paletteBtn.click();
+    const paletteInput = await $('input[placeholder="Search open tabs or library documents..."]');
+    await expect(paletteInput).toBeDisplayed();
+  });
+
+  it("should open help via the help button and scroll it instead of the document", async () => {
+    await openPdf();
+    // Scroll the document a little so its position can be compared later.
+    await browser.keys(["j"]);
+    await browser.waitUntil(
+      async () => (await pdfScrollTop()) > 0,
+      { timeout: 5000, timeoutMsg: "j did not scroll the PDF document" },
+    );
+    const documentScrollBefore = await pdfScrollTop();
+
+    const helpBtn = await $('button[aria-label="Help"]');
+    await helpBtn.click();
+    await $("*=Keyboard shortcuts").waitForDisplayed({ timeout: 5000 });
+
+    // G scrolls the help content to its bottom.
+    await browser.keys(["G"]);
+    await browser.waitUntil(
+      async () =>
+        (await browser.execute(() => {
+          const el = document.querySelector("[data-help-scroll]");
+          return el ? (el as HTMLElement).scrollTop : -1;
+        })) > 0,
+      { timeout: 5000, timeoutMsg: "G did not scroll the help content" },
+    );
+
+    // The document must not have moved while the help modal was open.
+    expect(await pdfScrollTop()).toBe(documentScrollBefore);
+
+    // Close help and confirm the document scrolls again.
+    await browser.keys(["Escape"]);
+    await browser.waitUntil(
+      async () => !(await $("*=Keyboard shortcuts").isExisting()),
+      { timeout: 5000, timeoutMsg: "help modal did not close on Escape" },
+    );
+    await browser.keys(["j"]);
+    await browser.waitUntil(
+      async () => (await pdfScrollTop()) > documentScrollBefore,
+      { timeout: 5000, timeoutMsg: "document did not resume scrolling after help closed" },
+    );
+  });
+
+  it("should jump to the first/last page with g/G in PDF PAGES mode", async () => {
+    await openPdf();
+    await browser.keys(["s"]);
+    await browser.waitUntil(
+      async () => (await statusBarText()).includes("pages"),
+      { timeout: 5000, timeoutMsg: "s did not switch to PAGES mode" },
+    );
+    await browser.keys(["G"]);
+    await browser.waitUntil(
+      async () => (await statusBarText()).includes("Page 12 / 12"),
+      { timeout: 10000, timeoutMsg: "G did not jump to the last page in PAGES mode" },
+    );
+    await browser.keys(["g"]);
+    await browser.waitUntil(
+      async () => (await statusBarText()).includes("Page 1 / 12"),
+      { timeout: 10000, timeoutMsg: "g did not jump to the first page in PAGES mode" },
+    );
+  });
+
+  it("should go to the top/bottom of a PDF with g/G in SCROLL mode", async () => {
+    await openPdf();
+    await browser.keys(["G"]);
+    await browser.waitUntil(
+      async () => (await statusBarText()).includes("Page 12 / 12"),
+      { timeout: 10000, timeoutMsg: "G did not scroll to the document bottom" },
+    );
+    await browser.keys(["g"]);
+    await browser.waitUntil(
+      async () => (await statusBarText()).includes("Page 1 / 12"),
+      { timeout: 10000, timeoutMsg: "g did not scroll to the document top" },
+    );
+  });
 });

src/components/HeaderBar.tsx

@@ -1,7 +1,9 @@
 import { useState, useEffect } from "react";
-import { Columns2, LayoutList, Minus, Plus, ScrollText, Settings, Square } from "lucide-react";
+import { CircleHelp, Columns2, Command, LayoutList, Minus, Plus, ScrollText, Settings, Square } from "lucide-react";
 import { useTabStore } from "@/features/tabs/TabStore";
 import { useSettingsModalStore } from "./settingsModalStore";
+import { useCommandPaletteStore } from "@/features/command-mode/CommandPalette";
+import { useHelpModalStore } from "./HelpModal";
 import { ThemeToggle } from "./theme-toggle";
 import type { ColumnCount, ViewMode } from "../shared/types";
 import {
@@ -93,6 +95,17 @@ export function HeaderBar() {
         {title}
       </span>
       <div className="flex shrink-0 items-center gap-2">
+        {/* Command Palette (leftmost) */}
+        <button
+          type="button"
+          onClick={() => useCommandPaletteStore.getState().open()}
+          aria-label="Open command palette"
+          title="Command palette (Ctrl+K)"
+          className="flex h-7 w-7 items-center justify-center rounded-md border border-border bg-background text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+        >
+          <Command size={15} />
+        </button>
+
         {/* View Mode Dropdown */}
         <DropdownMenu>
           <DropdownMenuTrigger asChild>
@@ -202,6 +215,17 @@ export function HeaderBar() {
 
         {/* Theme Toggle (Right end) */}
         <ThemeToggle />
+
+        {/* Help (rightmost) */}
+        <button
+          type="button"
+          onClick={() => useHelpModalStore.getState().open()}
+          aria-label="Help"
+          title="Help (?)"
+          className="flex h-7 w-7 items-center justify-center rounded-md border border-border bg-background text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+        >
+          <CircleHelp size={15} />
+        </button>
       </div>
     </div>
   );

src/components/HelpModal.tsx

@@ -20,7 +20,7 @@ export function HelpModal() {
     <Dialog open={isOpen} onOpenChange={(open) => !open && close()}>
       <DialogContent className="max-w-lg">
         <DialogHeader><DialogTitle>Keyboard shortcuts</DialogTitle></DialogHeader>
-        <div className="max-h-96 overflow-y-auto text-sm">
+        <div data-help-scroll className="max-h-96 overflow-y-auto text-sm">
           {KEYBINDINGS.map((binding) => (
             <div key={`${binding.mode}-${binding.key}`} className="grid grid-cols-[7rem_1fr] gap-3 border-b py-2 last:border-0">
               <code>{binding.key}</code>

src/components/theme-toggle.tsx

@@ -18,7 +18,7 @@ export function ThemeToggle() {
           type="button"
           aria-label="Toggle theme"
           title="Toggle theme"
-          className="relative flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          className="relative flex h-7 w-7 items-center justify-center rounded-md border border-border bg-background text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
         >
           <Sun className="h-4 w-4 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
           <Moon className="absolute h-4 w-4 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />

src/features/epub-viewer/EpubViewerHandle.ts

@@ -12,6 +12,7 @@ import type {
   PageTarget,
   PageTurn,
   ScrollDelta,
+  ScrollEdge,
   SearchHit,
   TabViewState,
   Unsubscribe,
@@ -32,6 +33,7 @@ import {
 } from "../../shared/overscroll";
 import type {
   DocumentViewerHandle,
+  PanDirection,
   ViewerCapabilities,
 } from "../../shared/viewer-handle";
 
@@ -69,6 +71,10 @@ type FoliateView = View & {
 
 const FORWARDED_KEY_ATTRIBUTE = "data-taurus-key-forwarding";
 const FORWARDED_WHEEL_ATTRIBUTE = "data-taurus-wheel-forwarding";
+/** Initial vertical step size (px) for the j/k hold-to-pan gesture. */
+const EPUB_PAN_STEP = 240;
+/** Continuous pan speed in px/s while a pan key is held. */
+const EPUB_PAN_VELOCITY = 1200;
 const APP_KEYS = new Set([
   "ArrowDown",
   "ArrowLeft",
@@ -119,6 +125,9 @@ export class EpubViewerHandle implements DocumentViewerHandle {
   private viewModeListeners: Set<(mode: ViewMode) => void> = new Set();
   private columnListeners: Set<(cols: ColumnCount) => void> = new Set();
   private readonly overscroll = new OverscrollController();
+  /** Active smooth pan loop (while a pan key is held). */
+  private panLoop: { raf: number; last: number; direction: PanDirection } | null =
+    null;
 
   constructor(private filePath: string) {
     this.view = document.createElement("foliate-view") as FoliateView;
@@ -166,7 +175,42 @@ export class EpubViewerHandle implements DocumentViewerHandle {
     }
   }
 
-  navigate(target: PageTarget | ScrollDelta | PageTurn): void {
+  startPan(direction: PanDirection): boolean {
+    const renderer = this.view.renderer;
+    if (!renderer || renderer.scrolled !== true) return false;
+    if (direction === "left" || direction === "right") return false;
+    if (renderer.containerPosition === undefined) return false;
+    this.stopPan();
+    const sign = direction === "up" ? -1 : 1;
+    renderer.containerPosition += sign * EPUB_PAN_STEP;
+    const last = performance.now();
+    this.panLoop = {
+      raf: requestAnimationFrame((now) => this.panFrame(direction, last, now)),
+      last,
+      direction,
+    };
+    return true;
+  }
+
+  private panFrame(direction: PanDirection, last: number, now: number): void {
+    const loop = this.panLoop;
+    const renderer = this.view.renderer;
+    if (!loop || !renderer || renderer.containerPosition === undefined) return;
+    const dt = Math.min(50, now - last);
+    const sign = direction === "up" ? -1 : 1;
+    renderer.containerPosition += (sign * EPUB_PAN_VELOCITY * dt) / 1000;
+    loop.last = now;
+    loop.raf = requestAnimationFrame((t) => this.panFrame(direction, now, t));
+  }
+
+  stopPan(): void {
+    if (this.panLoop) {
+      cancelAnimationFrame(this.panLoop.raf);
+      this.panLoop = null;
+    }
+  }
+
+  navigate(target: PageTarget | ScrollDelta | PageTurn | ScrollEdge): void {
     debug(`[EpubViewerHandle] navigate: ${JSON.stringify(target)}`);
     console.log(`[EpubViewerHandle] NAVIGATE CALLED: ${JSON.stringify(target)}`);
     const renderer = this.view.renderer;
@@ -175,6 +219,18 @@ export class EpubViewerHandle implements DocumentViewerHandle {
       case "page":
         this.view.goTo({ fraction: target.index }).catch((err) => warn(`[EpubViewerHandle] goTo failed: ${err}`));
         break;
+      case "edge":
+        if (scrolled) {
+          renderer!.containerPosition =
+            target.edge === "start"
+              ? 0
+              : Math.max(0, (renderer!.viewSize ?? 0) - (renderer!.size ?? 0));
+        } else {
+          this.view
+            .goTo({ fraction: target.edge === "start" ? 0 : 1 })
+            .catch((err) => warn(`[EpubViewerHandle] goTo failed: ${err}`));
+        }
+        break;
       case "scroll":
         if (scrolled && renderer.containerPosition !== undefined) {
           // A section is one long page: scroll it directly. Native clamping
@@ -532,6 +588,7 @@ export class EpubViewerHandle implements DocumentViewerHandle {
   }
 
   dispose(): void {
+    this.stopPan();
     try {
       if (this.view && typeof this.view.close === "function") {
         this.view.close();

src/features/library/LibraryView.tsx

@@ -255,7 +255,7 @@ export function LibraryView() {
         </div>
       </div>
 
-      <div ref={contentRef} className="flex-1 overflow-y-auto p-4">
+      <div ref={contentRef} data-library-scroll className="flex-1 overflow-y-auto p-4">
         {entries.length === 0 ? (
           <div className="flex h-64 flex-col items-center justify-center text-muted-foreground text-sm">
             <p className="mb-2">No documents in library.</p>

src/features/pdf-viewer/PdfViewerHandle.test.ts

@@ -179,6 +179,7 @@ describe("PdfViewerHandle", () => {
   it("reports the true page index when windowed pages do not start at zero", async () => {
     const handle = await makeHandle(20);
     const container = document.createElement("div");
+    Object.defineProperty(container, "clientHeight", { configurable: true, value: 1000 });
     handle.attachScrollContainer(container);
 
     const positions: DocumentPosition[] = [];
@@ -200,4 +201,85 @@ describe("PdfViewerHandle", () => {
     expect(handle.getCurrentPosition()).toMatchObject({ pageIndex: 10 });
     expect(positions[positions.length - 1]).toMatchObject({ pageIndex: 10 });
   });
+
+  it("scrolls to the top/bottom edges in SCROLL mode", async () => {
+    const handle = await makeHandle();
+    const el = document.createElement("div");
+    Object.defineProperty(el, "scrollHeight", { configurable: true, value: 4000 });
+    const scrollTopSetter = vi.fn();
+    Object.defineProperty(el, "scrollTop", {
+      configurable: true,
+      set: scrollTopSetter,
+      get: () => 0,
+    });
+    handle.attachScrollContainer(el);
+
+    handle.navigate({ kind: "edge", edge: "end" });
+    expect(scrollTopSetter).toHaveBeenLastCalledWith(4000);
+    handle.navigate({ kind: "edge", edge: "start" });
+    expect(scrollTopSetter).toHaveBeenLastCalledWith(0);
+  });
+
+  it("jumps to the first/last page in PAGES mode via edge navigation", async () => {
+    const handle = await makeHandle();
+    handle.setViewMode("pages");
+    handle.navigate({ kind: "edge", edge: "end" });
+    expect(handle.getCurrentPosition()).toMatchObject({ pageIndex: 4 });
+    handle.navigate({ kind: "edge", edge: "start" });
+    expect(handle.getCurrentPosition()).toMatchObject({ pageIndex: 0 });
+  });
+
+  it("does not start a pan in PAGES mode", async () => {
+    const handle = await makeHandle();
+    handle.setViewMode("pages");
+    const el = document.createElement("div");
+    handle.attachScrollContainer(el);
+    expect(handle.startPan?.("down")).toBe(false);
+    expect(handle.startPan?.("right")).toBe(false);
+  });
+
+  it("starts a horizontal pan only when the container overflows", async () => {
+    const handle = await makeHandle();
+    const overflow = document.createElement("div");
+    Object.defineProperty(overflow, "scrollWidth", { configurable: true, value: 2000 });
+    Object.defineProperty(overflow, "clientWidth", { configurable: true, value: 800 });
+    const scrollBy = vi.fn();
+    (overflow as unknown as { scrollBy: unknown }).scrollBy = scrollBy;
+    handle.attachScrollContainer(overflow);
+    expect(handle.startPan?.("right")).toBe(true);
+
+    const noOverflow = document.createElement("div");
+    const scrollBy2 = vi.fn();
+    (noOverflow as unknown as { scrollBy: unknown }).scrollBy = scrollBy2;
+    handle.attachScrollContainer(noOverflow);
+    expect(handle.startPan?.("right")).toBe(false);
+  });
+
+  it("starts and stops a smooth vertical pan in SCROLL mode", async () => {
+    vi.useFakeTimers();
+    try {
+      const handle = await makeHandle();
+      const el = document.createElement("div");
+      const scrollBy = vi.fn();
+      (el as unknown as { scrollBy: unknown }).scrollBy = scrollBy;
+      handle.attachScrollContainer(el);
+
+      expect(handle.startPan?.("down")).toBe(true);
+      const callsAfterStart = scrollBy.mock.calls.length;
+      expect(callsAfterStart).toBeGreaterThanOrEqual(1);
+
+      vi.advanceTimersByTime(200);
+      const callsAfterAdvance = scrollBy.mock.calls.length;
+      expect(callsAfterAdvance).toBeGreaterThan(callsAfterStart);
+      const topDeltas = scrollBy.mock.calls.map((c) => c[0].top);
+      expect(topDeltas.every((d) => typeof d === "number" && d >= 0)).toBe(true);
+
+      handle.stopPan?.();
+      const callsAfterStop = scrollBy.mock.calls.length;
+      vi.advanceTimersByTime(200);
+      expect(scrollBy.mock.calls.length).toBe(callsAfterStop);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });