feat(keys): j/k walk the feed, s finds the search box, g jumps to a module

A feed card cost ~10 Tab stops, so the tenth card sat ~135 Tabs from the top of the page, and the
only keyboard focus ring (a 60% accent outline on the thumbnail) all but vanished on the dark glass.
First slice of the E11 keyboard layer (S4a); Home, Plex and the tables follow in S4b/S4c.

- `lib/listNav`: one window listener over every registered list, walked in document order. `j`/`k`
  step item to item (on into the next list — owner decision D4), the arrows move around a grid, Enter
  clicks the item's own `data-nav-open` element, so it opens exactly like a click. An item root is
  never a Tab stop: it gets `tabindex=-1` only while the keyboard is on it, and keeps it until the next
  item takes it, so the player's focus restore lands back on the card. The first `j` takes the first
  card you can see, not the top of the list.
- `VirtualGrid` takes part with `keyboardNav` (column count + scrolling an unmounted row in);
  `VirtualFeed` turns it on, so the feed, the library and the channel page all have it.
- Keymap: two-step sequences (`g h`) whose pending step belongs to the scope that started it; the
  page-level scopes (`page`, `search`, `list`) are quiet while a layer that owns the keyboard is open,
  enforced in `dispatch`. A test pins the owner's rule that none of them needs a modifier on the
  Hungarian layout.
- `g h/f/c/p/x/n/m/d/s/,` jump to a module this account can reach; `s` focuses the header search box
  and selects the old query; Escape in it hands the keyboard back to the page (Plex's typeahead spends
  its first Escape on its panel).
- Hover popovers are passive layers: an open tooltip still takes Escape first but no longer silences
  the page keys.
- Focus ring (owner decision D2 = B): solid 2px accent around the whole item; the app-wide button/
  link/row ring goes from 60% to solid too. The item keeps a transparent resting outline because the
  video card transitions `all` — without it every `j` flashed a 3px white ring (measured in Chrome).
- Help sheet: the new keys, in a fixed order after the surface's own; a `g` chord only for a reachable
  module; opened over a player or dialog it leaves out the page-level keys and the context-menu key,
  which nothing can reach there (the latter pre-existing since E10).
- CLAUDE.md: a canonical-patterns row for list/grid keys (`useListNav` + `navItemAttrs` +
  `data-nav-open`, not a private arrow-key handler).

frontend/src/components/ui/AnchoredPopover.tsx

@@ -282,8 +282,9 @@ export function useAnchoredPopover(opts: AnchoredPopoverOptions) {
   // underneath defers to it. Hover popovers register too (an open tooltip/hover-card should take
   // Escape before the surface beneath it — and, when it is a player's own overlay card, keep the
   // player alive). An invisible (referenceHidden) surface is NOT a layer: it must not silently eat
-  // an Escape the user aimed at whatever is actually on screen.
-  useLayer(opts.open && !referenceHidden, () => opts.onOpenChange(false));
+  // an Escape the user aimed at whatever is actually on screen. A hover surface is a PASSIVE layer:
+  // it does not own the keyboard, so the page's own keys keep working under a resting pointer.
+  useLayer(opts.open && !referenceHidden, () => opts.onOpenChange(false), { passive: isHover });
 
   return {
     nodeId,

frontend/src/components/ui/KeyboardHelp.dom.test.tsx

@@ -14,6 +14,7 @@ import {
   useKeyScope,
   type KeyScope,
 } from "../../lib/keymap";
+import { pushLayer, removeLayer } from "../../lib/layerStack";
 
 vi.mock("react-i18next", async (importOriginal) => {
   const actual = await importOriginal<typeof import("react-i18next")>();
@@ -27,9 +28,11 @@ afterEach(() => {
   closeKeyboardHelp();
 });
 
-/** App's job: it binds the `global` scope (h / Mod+K / Shift+W) once for the whole tree. */
+/** App's job: it binds the `global` scope (h / Mod+K / Shift+W) and the `page` scope (the `g` chords)
+ *  once for the whole tree. Home is the one module this stand-in account reaches, so the page block
+ *  is the single `G H` chord, sharing Shift+W's line. */
 function Host({ children }: { children?: React.ReactNode }) {
-  useGlobalKeymap(true, () => {});
+  useGlobalKeymap(true, () => {}, ["home"]);
   return (
     <>
       {children}
@@ -81,15 +84,16 @@ describe("KeyboardHelp", () => {
     );
     pressH();
     const rows = descriptions();
-    // A plexPlayer row first, the app-wide rows last — the reading order the reader wants.
+    // A plexPlayer row first, the app-wide rows last — the reading order the reader wants. (Home's
+    // line comes from the page block, which sits between the two; Shift+W joins it there.)
     expect(rows[0]).toBe("keys.playPause");
-    expect(rows.slice(-3)).toEqual(["keys.palette", "keys.help", "keys.home"]);
+    expect(rows.slice(-3)).toEqual(["keys.home", "keys.palette", "keys.help"]);
   });
 
   it("lists only the app-wide keys when no surface is registered", () => {
     render(<Host />);
     pressH();
-    expect(descriptions()).toEqual(["keys.palette", "keys.help", "keys.home"]);
+    expect(descriptions()).toEqual(["keys.home", "keys.palette", "keys.help"]);
   });
 
   // The context menu is NOT app-wide: it has its own scope, registered by `useContextMenu`, so the
@@ -120,6 +124,24 @@ describe("KeyboardHelp", () => {
     expect(descriptions()).not.toContain("keys.contextMenu");
   });
 
+  // Opened over a player, Shift+F10 has nothing to reach — focus is inside the player, not on a row.
+  it("drops the context-menu key from a sheet opened over a keyboard-owning layer", () => {
+    function WithMenu() {
+      useContextMenu<string>();
+      return null;
+    }
+    render(
+      <Host>
+        <WithMenu />
+      </Host>,
+    );
+    const id = pushLayer();
+    pressH();
+    removeLayer(id);
+    expect(descriptions()).not.toContain("keys.contextMenu");
+    expect(descriptions()).toContain("keys.help");
+  });
+
   // Two live context menus (the Playlists page mounts one, its rail another) must not double the row.
   it("lists the context-menu chords once however many surfaces register", () => {
     function WithMenu() {

frontend/src/components/ui/KeyboardHelp.tsx

@@ -5,9 +5,12 @@ import {
   closeKeyboardHelp,
   formatChord,
   helpLines,
+  isPageLevelScope,
   useActiveScopes,
   useHelpConditionValues,
   useKeyboardHelpOpen,
+  useKeyboardHelpOverLayer,
+  useNavigablePages,
 } from "../../lib/keymap";
 
 // The app's one keyboard cheat sheet. Mounted once by App; the global `h` that opens it lives in
@@ -29,11 +32,21 @@ export default function KeyboardHelp() {
   const open = useKeyboardHelpOpen();
   const scopes = useActiveScopes();
   const conditions = useHelpConditionValues();
+  const overLayer = useKeyboardHelpOverLayer();
+  const pages = useNavigablePages();
 
   if (!open) return null;
   // A `when` row is listed only where it applies — "Previous / next episode" inside a movie would be
   // a promise the player does not keep.
-  const lines = helpLines(scopes).filter((l) => !l.when || !!conditions[l.when]);
+  // Opened over a player or a dialog, the page-level keys (`s`, `g …`, `j`/`k`) are quiet — listing
+  // them there would promise keys that do nothing until the overlay closes. And a `g` chord is listed
+  // only for a module this account can actually reach.
+  // The context-menu key goes too: every `useContextMenu` is a page list, and with an overlay up the
+  // focus Shift+F10 needs is inside the overlay (pre-existing since E10, found in S4 UAT).
+  const live = overLayer
+    ? scopes.filter((s) => !isPageLevelScope(s) && s !== "contextMenu")
+    : scopes;
+  const lines = helpLines(live, pages).filter((l) => !l.when || !!conditions[l.when]);
   return (
     <Modal title={t("keys.title")} onClose={closeKeyboardHelp} maxWidth="max-w-md">
       <dl className="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2.5 text-sm">

frontend/src/components/ui/Tooltip.layer.dom.test.tsx

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+//
+// E11 S4: a hover surface (tooltip, hover card) is a PASSIVE layer. It still sits on the layer stack —
+// Escape closes it before the surface beneath — but it does not own the keyboard, so the page-level
+// keys (`j`/`k`, `s`, the `g` chords) keep working while one happens to be open under a resting pointer.
+// Without the flag, hovering any hinted icon silently disabled keyboard navigation.
+//
+// jsdom lays nothing out, and floating-ui's `hide` middleware then reports the reference as scrolled
+// out of view — and an invisible surface is deliberately NOT a layer (AnchoredPopover). A test on that
+// would pass without the flag, so the reference and the viewport get real boxes first, and the test
+// proves the surface is a layer (Escape closes it) before trusting the "not blocking" half.
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import Tooltip from "./Tooltip";
+import { anyBlockingLayer } from "../../lib/layerStack";
+
+const box = { x: 200, y: 200, top: 200, left: 200, width: 60, height: 24, right: 260, bottom: 224 };
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({
+    ...box,
+    toJSON: () => box,
+  } as DOMRect);
+  for (const [prop, value] of [
+    ["clientWidth", 1280],
+    ["clientHeight", 800],
+  ] as const) {
+    Object.defineProperty(document.documentElement, prop, { configurable: true, value });
+  }
+});
+afterAll(() => vi.restoreAllMocks());
+afterEach(cleanup);
+
+describe("an open tooltip", () => {
+  it("is a layer Escape reaches, but does not block the page keys", async () => {
+    render(
+      <Tooltip hint="A hint" always>
+        <button>icon</button>
+      </Tooltip>,
+    );
+    const trigger = screen.getByText("icon").parentElement as HTMLElement;
+    act(() => {
+      fireEvent.pointerEnter(trigger);
+      fireEvent.mouseEnter(trigger);
+      fireEvent.mouseMove(trigger);
+    });
+    const surface = await screen.findByRole("tooltip");
+    await waitFor(() => expect(surface.style.visibility).not.toBe("hidden"));
+
+    expect(anyBlockingLayer()).toBe(false);
+
+    act(() => {
+      fireEvent.keyDown(document, { key: "Escape" });
+    });
+    await waitFor(() => expect(screen.queryByRole("tooltip")).toBeNull());
+  });
+});

frontend/src/components/ui/VirtualGrid.tsx

@@ -8,6 +8,7 @@ import {
   type ReactNode,
 } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
+import { useListNav } from "../../lib/listNav";
 import { GRID_GAP, columnsFor, itemWidthFor } from "./gridColumns";
 import { shouldPrefetchNext } from "./readAhead";
 
@@ -66,8 +67,13 @@ export interface VirtualGridProps<T> {
   rowEst: number;
   /** Renders one item. `itemWidth` is the measured px width of one cell — for width-derived
    * layouts (e.g. a one-line row that drops columns as it narrows); ignore it otherwise, and to
-   * protect a memo'd item from re-rendering on every resize frame, pass a stable value down. */
-  renderItem: (item: T, itemWidth: number) => ReactNode;
+   * protect a memo'd item from re-rendering on every resize frame, pass a stable value down.
+   * `index` is the item's position in `items` — what `navItemAttrs` wants on the item's root. */
+  renderItem: (item: T, itemWidth: number, index: number) => ReactNode;
+  /** Take part in page keyboard navigation (`lib/listNav`): `j`/`k`/arrows/Enter over the items.
+   * The grid supplies the column count and scrolls an unmounted item's row in; the item must spread
+   * `navItemAttrs(index)` on its root and mark its "open" element `data-nav-open`. */
+  keyboardNav?: boolean;
   /** Infinite scroll — omit all three for a finite client-side list. */
   hasNextPage?: boolean;
   isFetchingNextPage?: boolean;
@@ -85,6 +91,7 @@ export default function VirtualGrid<T>({
   hasNextPage = false,
   isFetchingNextPage = false,
   fetchNextPage,
+  keyboardNav = false,
 }: VirtualGridProps<T>) {
   const listRef = useRef<HTMLDivElement>(null);
   const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null);
@@ -139,6 +146,15 @@ export default function VirtualGrid<T>({
 
   const virtualRows = virtualizer.getVirtualItems();
 
+  // Only ~a screen of rows (plus overscan) is mounted, so a key that moves further — or past the
+  // overscan at the edge — has to scroll the row in before the item exists to be focused.
+  useListNav(listRef, {
+    enabled: keyboardNav,
+    count: items.length,
+    cols: colCount,
+    reveal: (index) => virtualizer.scrollToIndex(Math.floor(index / colCount), { align: "auto" }),
+  });
+
   // Infinite-scroll read-ahead: pull the next page once the last rendered row is within the
   // read-ahead window of the loaded end (see readAhead.ts — the window scales with the rendered row
   // count, clamped so a tall window doesn't prefetch unboundedly). A no-op for finite lists (no
@@ -159,6 +175,7 @@ export default function VirtualGrid<T>({
       {virtualRows.map((vr) => {
         const row = rows[vr.index];
         if (!row) return null;
+        const first = vr.index * colCount;
         return (
           <div
             key={vr.key}
@@ -185,8 +202,8 @@ export default function VirtualGrid<T>({
               {/* A transparent Fragment carries React's key so the rendered item stays the DIRECT
                   grid/column child — some cards rely on that (e.g. `h-full` stretch, actions pinned
                   to the bottom edge), which a wrapper element would silently break. */}
-              {row.map((item) => (
-                <Fragment key={getKey(item)}>{renderItem(item, itemWidth)}</Fragment>
+              {row.map((item, i) => (
+                <Fragment key={getKey(item)}>{renderItem(item, itemWidth, first + i)}</Fragment>
               ))}
             </div>
           </div>