From 1e91dffd8b6d454870a19d76d9b9c24e059da389 Mon Sep 17 00:00:00 2001
From: Aviral Shukla <aviral.shukla2122000@gmail.com>
Date: Tue, 7 Jul 2026 21:29:44 +0530
Subject: [PATCH 1/2] refactor(keyboard-nav): share a single nav instance via
 KeyboardNavProvider

Splits useKeyboardNav into createKeyboardNav (constructor) and useKeyboardNav
(context consumer) so descendant panels can share one focus ring instead of
each panel spinning up its own. main-ui wraps its tool + preview subtree in the
new provider. Adds a persistent field to FocusableElement so consumers can
keep long-lived focusable elements registered across effect reruns
(clearElements now only drops non-persistent entries).

Callers outside the provider fall through to a fresh instance, preserving
current behavior for standalone components.
---
 src/components/main-ui.tsx           | 55 +++++++++++++++-------------
 src/hooks/useKeyboardNav.ts          | 15 +++++---
 src/model/models.ts                  |  1 +
 src/provider/keyboardNavProvider.tsx |  9 +++++
 4 files changed, 49 insertions(+), 31 deletions(-)
 create mode 100644 src/provider/keyboardNavProvider.tsx

diff --git a/src/components/main-ui.tsx b/src/components/main-ui.tsx
index 004011d..ddd8e8b 100644
--- a/src/components/main-ui.tsx
+++ b/src/components/main-ui.tsx
@@ -13,6 +13,7 @@ import { OrganiseUI } from "./organise";
 import { HeaderLayout } from "./header-layout";
 import { PDFPreviewPane } from "./pdf-preview";
 import { useFileListContext } from "../provider/fileListProvider";
+import { KeyboardNavProvider } from "../provider/keyboardNavProvider";
 import { Button } from "./ui/button";
 
 interface MainUIProps {
@@ -50,33 +51,35 @@ export function MainUI(props: MainUIProps) {
 
   return (
     <HeaderLayout toolName={props.toolName} onBack={props.onBack}>
-      <box flexDirection="row">
-        <box flexGrow={3}>
-          <Dynamic component={toolComponents[props.selectedTool]} />
-        </box>
-        <Show when={props.selectedTool !== "organise" && props.selectedTool !== "decrypt"}>
-          <box flexGrow={2} width={isPreviewOpen() && fl.fileCount() > 0 ? "30%" : 6}>
-            <Show
-              when={isPreviewOpen() && fl.fileCount() > 0}
-              fallback={
-                <box alignItems="flex-start" paddingTop={2}>
-                  <Button
-                    disabled={!fl.selectedFile()}
-                    color="yellow"
-                    label="◀"
-                    onClick={() => setIsPreviewOpen(true)}
-                  />
-                </box>
-              }
-            >
-              <PDFPreviewPane
-                onOpen={() => setIsPreviewOpen(true)}
-                onClose={() => setIsPreviewOpen(false)}
-              />
-            </Show>
+      <KeyboardNavProvider>
+        <box flexDirection="row">
+          <box flexGrow={3}>
+            <Dynamic component={toolComponents[props.selectedTool]} />
           </box>
-        </Show>
-      </box>
+          <Show when={props.selectedTool !== "organise" && props.selectedTool !== "decrypt"}>
+            <box flexGrow={2} width={isPreviewOpen() && fl.fileCount() > 0 ? "30%" : 6}>
+              <Show
+                when={isPreviewOpen() && fl.fileCount() > 0}
+                fallback={
+                  <box alignItems="flex-start" paddingTop={2}>
+                    <Button
+                      disabled={!fl.selectedFile()}
+                      color="yellow"
+                      label="◀"
+                      onClick={() => setIsPreviewOpen(true)}
+                    />
+                  </box>
+                }
+              >
+                <PDFPreviewPane
+                  onOpen={() => setIsPreviewOpen(true)}
+                  onClose={() => setIsPreviewOpen(false)}
+                />
+              </Show>
+            </box>
+          </Show>
+        </box>
+      </KeyboardNavProvider>
     </HeaderLayout>
   );
 }
diff --git a/src/hooks/useKeyboardNav.ts b/src/hooks/useKeyboardNav.ts
index 9555354..0103ba5 100644
--- a/src/hooks/useKeyboardNav.ts
+++ b/src/hooks/useKeyboardNav.ts
@@ -1,10 +1,10 @@
-import { createSignal, createMemo } from "solid-js";
+import { createSignal, createMemo, createContext, useContext } from "solid-js";
 import { useBindings } from "@opentui/keymap/solid";
 import type { FocusableElement } from "../model/models";
 
 export type { FocusableElement };
 
-export function useKeyboardNav() {
+export function createKeyboardNav() {
   const [focusIndex, setFocusIndex] = createSignal(0);
   const [elements, setElements] = createSignal<FocusableElement[]>([]);
   const [isInputMode, setIsInputMode] = createSignal(false);
@@ -62,7 +62,7 @@ export function useKeyboardNav() {
   const getFocusedId = () => focusedElement()?.id ?? null;
 
   const clearElements = () => {
-    setElements([]);
+    setElements((prev) => prev.filter((e) => e.persistent));
     setFocusIndex(0);
   };
 
@@ -70,11 +70,10 @@ export function useKeyboardNav() {
     priority: 100,
     bindings: isInputMode()
       ? [
-          // Let escape bubble to the app-level double-esc handler in src/index.tsx
           {
             key: "escape",
             cmd: () => setIsInputMode(false),
-            preventDefault: false,
+            preventDefault: false, // Let escape bubble to the app-level double-esc handler in src/index.tsx
           },
           {
             key: "tab",
@@ -114,3 +113,9 @@ export function useKeyboardNav() {
     setIsInputMode,
   };
 }
+
+export const KeyboardNavContext = createContext<ReturnType<typeof createKeyboardNav>>();
+
+export function useKeyboardNav() {
+  return useContext(KeyboardNavContext) ?? createKeyboardNav();
+}
diff --git a/src/model/models.ts b/src/model/models.ts
index 97174d9..4918dd3 100644
--- a/src/model/models.ts
+++ b/src/model/models.ts
@@ -9,6 +9,7 @@ export interface FocusableElement {
   onEnter?: () => void;
   canFocus?: () => boolean;
   onMouseDown?: () => void;
+  persistent?: boolean; // keeps element registered across clearElements calls
 }
 
 export interface Status {
diff --git a/src/provider/keyboardNavProvider.tsx b/src/provider/keyboardNavProvider.tsx
new file mode 100644
index 0000000..24f2453
--- /dev/null
+++ b/src/provider/keyboardNavProvider.tsx
@@ -0,0 +1,9 @@
+import { type ParentComponent } from "solid-js";
+import { KeyboardNavContext, createKeyboardNav } from "../hooks/useKeyboardNav";
+
+// Provides a single keyboard-nav instance so descendant panels (the active tool
+// and the PDF preview) share one focus ring instead of competing rings.
+export const KeyboardNavProvider: ParentComponent = (props) => {
+  const nav = createKeyboardNav();
+  return <KeyboardNavContext.Provider value={nav}>{props.children}</KeyboardNavContext.Provider>;
+};

From 4b78f00e19e827b4886ac301412d3de62146530c Mon Sep 17 00:00:00 2001
From: Aviral Shukla <aviral.shukla2122000@gmail.com>
Date: Tue, 7 Jul 2026 23:31:09 +0530
Subject: [PATCH 2/2] feat(pdf-preview): navigate pages with arrow keys and
 hjkl

Registers the prev/next page buttons as persistent focusable
elements and adds left/right (and h/l) key bindings so users
can flip through a previewed PDF without the mouse.

Suppressed while a text input has focus or when no file is
selected.
---
 src/components/pdf-preview.tsx | 62 +++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/src/components/pdf-preview.tsx b/src/components/pdf-preview.tsx
index 78ae82e..a432f7c 100644
--- a/src/components/pdf-preview.tsx
+++ b/src/components/pdf-preview.tsx
@@ -1,5 +1,6 @@
 import { TextAttributes, type BoxRenderable, type CliRenderer } from "@opentui/core";
 import { onResize, useRenderer } from "@opentui/solid";
+import { useBindings } from "@opentui/keymap/solid";
 import { Show, createEffect, createMemo, createResource, createSignal, onCleanup } from "solid-js";
 import {
   clearPDFPreview,
@@ -12,6 +13,7 @@ import { useFileListContext } from "../provider/fileListProvider";
 import { Button } from "./ui/button";
 import { PreviewButton } from "./ui/preview-button";
 import { PDFPreviewFrame } from "./ui/index";
+import { useKeyboardNav } from "../hooks/useKeyboardNav";
 
 type RendererCapabilities = CliRenderer["capabilities"];
 
@@ -21,6 +23,8 @@ const hasKittyGraphics = (capabilities: RendererCapabilities | null) =>
 export function PDFPreviewPane(props: { onOpen: () => void; onClose: () => void }) {
   const renderer = useRenderer();
   const fl = useFileListContext();
+  const nav = useKeyboardNav();
+
   const selectedFile = fl.selectedFile;
   const initialKittySupport = hasKittyGraphics(renderer.capabilities ?? null);
 
@@ -46,12 +50,15 @@ export function PDFPreviewPane(props: { onOpen: () => void; onClose: () => void
   let layoutRefreshTimer: ReturnType<typeof setTimeout> | null = null;
 
   const totalPages = () => Math.max(pageCount() ?? 0, 1);
+
   const canGoPrev = () => page() > 1;
   const canGoNext = () => page() < totalPages();
+  const goToPrevPage = () => setPage((value) => Math.max(1, value - 1));
+  const goToNextPage = () => setPage((value) => Math.min(totalPages(), value + 1));
+
   const showSupportProbe = () =>
     Boolean(selectedFile()) && !supported() && !capabilityProbeExpired();
   const showUnsupported = () => Boolean(selectedFile()) && !supported() && capabilityProbeExpired();
-  // const showLoading = () => Boolean(selectedFile()) && supported() && isLoading();
   const showError = () =>
     Boolean(selectedFile()) && supported() && !isLoading() && Boolean(error());
 
@@ -222,12 +229,63 @@ export function PDFPreviewPane(props: { onOpen: () => void; onClose: () => void
     }
   });
 
+  createEffect(() => {
+    nav.registerElement({
+      id: "prev-page",
+      type: "button",
+      persistent: true,
+      onEnter: () => setPage((value) => Math.max(1, value - 1)),
+    });
+
+    nav.registerElement({
+      id: "next-page",
+      type: "button",
+      persistent: true,
+      onEnter: () => setPage((value) => Math.min(totalPages(), value + 1)),
+    });
+  });
+
+  useBindings(() => ({
+    priority: 100,
+    bindings:
+      nav.isInputMode() || !selectedFile()
+        ? []
+        : [
+            {
+              key: "left",
+              cmd: () => {
+                if (canGoPrev()) goToPrevPage();
+              },
+            },
+            {
+              key: "h",
+              cmd: () => {
+                if (canGoPrev()) goToPrevPage();
+              },
+            },
+            {
+              key: "right",
+              cmd: () => {
+                if (canGoNext()) goToNextPage();
+              },
+            },
+            {
+              key: "l",
+              cmd: () => {
+                if (canGoNext()) goToNextPage();
+              },
+            },
+          ],
+  }));
+
   onCleanup(() => {
     renderer.off("capabilities", handleCapabilitiesChange);
     cancelPendingPreviewRender();
     clearCapabilityProbeTimer();
     clearLayoutRefreshTimer();
     clearActivePreview();
+    nav.unregisterElement("prev-page");
+    nav.unregisterElement("next-page");
   });
 
   return (
@@ -262,6 +320,7 @@ export function PDFPreviewPane(props: { onOpen: () => void; onClose: () => void
             label="◀"
             disabled={!canGoPrev()}
             onClick={() => setPage((value) => Math.max(1, value - 1))}
+            focused={nav.isFocused("prev-page")}
           />
           <box paddingBottom={1}>
             <text
@@ -273,6 +332,7 @@ export function PDFPreviewPane(props: { onOpen: () => void; onClose: () => void
             label="▶"
             disabled={!canGoNext()}
             onClick={() => setPage((value) => Math.min(totalPages(), value + 1))}
+            focused={nav.isFocused("next-page")}
           />
         </box>
       </Show>