@liebstoeckel/engine 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liebstoeckel/engine",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "The compiler, React runtime, and single-file build pipeline at the core of liebstoeckel.",
   "keywords": [
     "liebstoeckel",

package/src/Deck.tsx

@@ -24,6 +24,8 @@ import { normalizeSlides, type SlideInput } from "./slides";
 import { resolveTransition, mobileTransitionsDisabled, type SlideDirection, type SlideTransition } from "./transitions";
 import type { Theme } from "@liebstoeckel/theme";
 import { useCoarsePointer } from "./useCoarsePointer";
+import { moveSelection, gridCols, type GridDir } from "./overview";
+import type { NavMode } from "./interaction";
 
 export type DeckProps = {
   slides: SlideInput[];
@@ -98,8 +100,34 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
   const [overview, setOverview] = useState(false);
   const [qr, setQr] = useState(false);
   const [jump, setJump] = useState("");
+  // Terminal "end of deck" screen: advancing past the final slide's last step shows
+  // a deliberate end state (like PowerPoint) instead of replaying the last slide's
+  // steps. Local to the driving window; cleared on any navigation away.
+  const [ended, setEnded] = useState(false);
+  // Keyboard selection within the overview grid (seeded to the current slide on open).
+  const [sel, setSel] = useState(0);
   const brand = brands[brandIdx % brands.length];
 
+  // The active interaction layer drives keyboard routing: a modal layer (overview,
+  // end) owns its keys so deck nav never leaks through it.
+  const mode: NavMode = overview ? "overview" : ended ? "end" : "slide";
+
+  // Refs mirror the composing state so the keyboard handlers stay stable and never
+  // read a stale closure when layers interact.
+  const overviewRef = useRef(overview);
+  overviewRef.current = overview;
+  const selRef = useRef(sel);
+  selRef.current = sel;
+  const jumpRef = useRef(jump);
+  jumpRef.current = jump;
+  const stepRef = useRef(step);
+  stepRef.current = step;
+  const totalRef = useRef(total);
+  totalRef.current = total;
+  const selectedThumbRef = useRef<HTMLButtonElement | null>(null);
+  // True while a Restart's masked crossfade-to-slide-1 is in flight (see onRestart).
+  const pendingRestartRef = useRef(false);
+
   useEffect(() => {
     document.body.dataset.brand = brand;
   }, [brand]);
@@ -113,33 +141,121 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
     return () => window.removeEventListener("contextmenu", onCtx);
   }, []);
 
+  // Overview open/close. Opening seeds the selection to the current slide and clears
+  // the end state + jump buffer — the modal layers are mutually exclusive.
+  const openOverview = useCallback(() => {
+    setEnded(false);
+    setJump("");
+    setSel(indexRef.current);
+    setOverview(true);
+  }, []);
+  const closeOverview = useCallback(() => {
+    setOverview(false);
+    setJump("");
+  }, []);
+  const toggleOverview = useCallback(() => {
+    if (overviewRef.current) closeOverview();
+    else openOverview();
+  }, [openOverview, closeOverview]);
+
+  // Numeric jump is layer-aware: in the overview it moves the live selection (the
+  // grid IS the jump surface); otherwise it drives the floating HUD and commits.
   const onDigit = useCallback(
     (key: string) => {
-      const r = accumulateDigits(jump, key);
+      if (overviewRef.current) {
+        const buffer = (jumpRef.current + key).slice(0, 3);
+        setJump(buffer);
+        const target = parseInt(buffer, 10) - 1;
+        if (!Number.isNaN(target)) setSel(Math.min(Math.max(target, 0), Math.max(count - 1, 0)));
+        return;
+      }
+      const r = accumulateDigits(jumpRef.current, key);
       setJump(r.buffer);
       if (r.commit != null) ctrl.setIndex(r.commit);
     },
-    [jump, ctrl],
+    [count, ctrl],
   );
 
+  // Overview keyboard: arrows move the selection, Enter opens it.
+  const onGridMove = useCallback(
+    (dir: GridDir) => {
+      setJump("");
+      const width = typeof window === "undefined" ? 1280 : window.innerWidth;
+      setSel((s) => moveSelection(s, count, gridCols(width), dir));
+    },
+    [count],
+  );
+  const onSelect = useCallback(() => {
+    ctrl.setIndex(selRef.current);
+    closeOverview();
+  }, [ctrl, closeOverview]);
+  // Esc / back: close the overview, otherwise leave the end screen.
+  const onExitModal = useCallback(() => {
+    if (overviewRef.current) closeOverview();
+    else setEnded(false);
+  }, [closeOverview]);
+  const onRestart = useCallback(() => {
+    // Restart to slide 1 without the last slide flashing into view. The end card is
+    // an opaque full-screen layer, so we keep it up (do NOT clear `ended`) while the
+    // slide layer crossfades to slide 1 *behind* it — masked — and drop the card only
+    // once that exit completes (AnimatePresence onExitComplete). `pendingRestartRef`
+    // makes the index-change effect skip its usual end-clear during that window.
+    if (indexRef.current === 0) {
+      setEnded(false); // already on slide 1 — nothing to mask
+      return;
+    }
+    pendingRestartRef.current = true;
+    ctrl.setIndex(0);
+    // Safety net: if onExitComplete never fires (interrupted animation), reveal anyway.
+    window.setTimeout(() => {
+      if (pendingRestartRef.current) {
+        pendingRestartRef.current = false;
+        setEnded(false);
+      }
+    }, 700);
+  }, [ctrl]);
+
+  // Advancing past the last slide's final step enters the end screen rather than
+  // calling ctrl.next (which would reset the last slide's step to 0 and replay it).
+  // Only the deck's driver gets it; a live viewer just follows. In a modal layer
+  // routeKey never yields "next", so this only fires while actually presenting.
+  const handleNext = useCallback(() => {
+    if (canDrive && indexRef.current >= count - 1 && stepRef.current >= totalRef.current) {
+      setEnded(true);
+      return;
+    }
+    ctrl.next();
+  }, [canDrive, count, ctrl]);
+  const handlePrev = useCallback(() => ctrl.prev(), [ctrl]);
+  // A jump elsewhere (overview select, numeric commit) clears the end state — except
+  // during a Restart, where the end card intentionally stays up to mask the crossfade.
+  useEffect(() => {
+    if (!pendingRestartRef.current) setEnded(false);
+  }, [index]);
+
   useDeckNav({
     count,
     setIndex: ctrl.setIndex,
-    onNext: ctrl.next,
-    onPrev: ctrl.prev,
+    mode,
+    onNext: handleNext,
+    onPrev: handlePrev,
     onToggleBrand: brands.length > 1 ? () => setBrandIdx((n) => n + 1) : undefined,
     onOpenPresenter: canDrive ? openPresenter : undefined,
     onToggleHelp: () => setHelp((v) => !v),
     onFullscreen: () => void toggleFullscreen(document.documentElement),
     onBlur: () => setBlurred((v) => !v),
-    onOverview: canDrive ? () => setOverview((v) => !v) : undefined,
+    onOverview: canDrive ? toggleOverview : undefined,
     onQr: () => setQr((v) => !v),
     onDigit,
+    onGridMove,
+    onSelect,
+    onExitModal,
+    onRestart,
   });
 
-  // Touch nav for everyone who drives their own deck (standalone + presenter); a
-  // live viewer follows the presenter, so it isn't bound for them.
-  useTouchNav({ enabled: role !== "viewer", onNext: ctrl.next, onPrev: ctrl.prev });
+  // Touch nav drives the deck only while presenting — suppressed under any modal
+  // layer so a swipe can't move the slide behind the overview / end screen.
+  useTouchNav({ enabled: role !== "viewer" && !overview && !ended, onNext: handleNext, onPrev: handlePrev });
 
   const Current = norm[index]?.Component ?? (() => null);
 
@@ -160,6 +276,12 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
     : (norm[index]?.transition ?? deckTransition);
   const slideTransition = resolveTransition(requested, !!reduceMotion);
 
+  // Keep the keyboard-selected overview thumbnail in view as you arrow through a
+  // long deck.
+  useEffect(() => {
+    if (overview) selectedThumbRef.current?.scrollIntoView({ block: "nearest", behavior: reduceMotion ? "auto" : "smooth" });
+  }, [sel, overview, reduceMotion]);
+
   return (
     <MDXProvider components={mdxComponents}>
       <PersistentProvider>
@@ -169,7 +291,17 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
        <div className="relative h-dvh w-screen overflow-hidden bg-bg">
         <ScaledStage className="absolute inset-0">
           <div data-deck-root className="absolute inset-0">
-            <AnimatePresence custom={direction}>
+            <AnimatePresence
+              custom={direction}
+              onExitComplete={() => {
+                // Restart kept the end card up to mask the crossfade to slide 1; the
+                // exiting last slide is now gone, so it's safe to drop the card.
+                if (pendingRestartRef.current) {
+                  pendingRestartRef.current = false;
+                  setEnded(false);
+                }
+              }}
+            >
               <motion.div
                 key={index}
                 custom={direction}
@@ -194,20 +326,6 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
                 slide, below chrome; non-interactive (live only, see ADR 0021) */}
             <PluginOverlays />
 
-            {/* jump-to-number buffer */}
-            <AnimatePresence>
-              {jump && (
-                <motion.div
-                  initial={{ opacity: 0, scale: 0.9 }}
-                  animate={{ opacity: 1, scale: 1 }}
-                  exit={{ opacity: 0 }}
-                  className="absolute left-1/2 top-8 -translate-x-1/2 rounded-xl border border-border bg-surface/80 px-5 py-2 font-mono text-2xl text-text backdrop-blur"
-                >
-                  → {jump}
-                </motion.div>
-              )}
-            </AnimatePresence>
-
             <HelpOverlay open={help} onClose={() => setHelp(false)} showBrand={brands.length > 1} role={role} ejectable={ejectable} />
             <PortraitHint />
           </div>
@@ -239,21 +357,36 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
           {overview && (
             <motion.div
               className="absolute inset-0 z-40 overflow-auto bg-bg/95 p-[4%] backdrop-blur-xl"
-              initial={{ opacity: 0 }}
+              // Mount already opaque (no fade-in): opening from the end screen, the
+              // overview must cover the last slide *immediately* while the end card
+              // fades out on top, otherwise the slide flashes through the gap.
+              initial={{ opacity: 1 }}
               animate={{ opacity: 1 }}
               exit={{ opacity: 0 }}
+              transition={reduceMotion ? { duration: 0 } : undefined}
             >
-              <div className="mb-6 font-mono text-sm uppercase tracking-[0.3em] text-muted">Overview · tap or type a number</div>
+              <div className="mb-6 flex items-baseline justify-between gap-4">
+                <div className="font-mono text-sm uppercase tracking-[0.3em] text-muted">
+                  Overview · ←↑↓→ move · Enter open · or type a number
+                </div>
+                {jump && <div className="font-mono text-sm text-text">→ {jump}</div>}
+              </div>
               <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4 lg:gap-5">
                 {norm.map((s, i) => (
                   <button
                     key={i}
+                    ref={i === sel ? selectedThumbRef : undefined}
                     onClick={() => {
                       ctrl.setIndex(i);
-                      setOverview(false);
+                      closeOverview();
                     }}
-                    className={`relative aspect-video overflow-hidden rounded-xl border text-left transition ${
-                      i === index ? "border-primary" : "border-border hover:border-text"
+                    aria-current={i === index ? "true" : undefined}
+                    className={`relative aspect-video overflow-hidden rounded-xl border text-left outline-none transition ${
+                      i === sel
+                        ? "border-primary ring-2 ring-primary"
+                        : i === index
+                          ? "border-primary"
+                          : "border-border hover:border-text"
                     }`}
                   >
                     <DeckThumb Component={s.Component} src={thumbs?.get(i)} alt={`Slide ${i + 1}`} />
@@ -265,6 +398,49 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
           )}
         </AnimatePresence>
 
+        {/* terminal end-of-deck card (advancing past the last slide) — a calm,
+            deliberate stop, NOT a wrap; covers the slide + ambient motion. Tapping the
+            backdrop goes back; the action row offers Back / Overview / Restart. */}
+        <AnimatePresence>
+          {ended && (
+            <motion.div
+              className="absolute inset-0 z-50 flex flex-col items-center justify-center gap-6 bg-bg text-center"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              transition={reduceMotion ? { duration: 0 } : { duration: 0.3 }}
+              onClick={() => setEnded(false)}
+            >
+              <div className="space-y-2">
+                <div className="font-mono text-sm uppercase tracking-[0.3em] text-muted">End of deck</div>
+                <div className="font-mono text-xs text-muted/60">{count} {count === 1 ? "slide" : "slides"}</div>
+              </div>
+              <div className="flex flex-wrap items-center justify-center gap-3" onClick={(e) => e.stopPropagation()}>
+                <button onClick={() => setEnded(false)} className="rounded-lg border border-border px-4 py-2 font-mono text-sm text-text transition hover:border-text">← Back</button>
+                <button onClick={openOverview} className="rounded-lg border border-border px-4 py-2 font-mono text-sm text-text transition hover:border-text">Overview</button>
+                <button onClick={onRestart} className="rounded-lg border border-border px-4 py-2 font-mono text-sm text-text transition hover:border-text">↺ Restart</button>
+              </div>
+              <div className="font-mono text-[0.7rem] text-muted/50">← back · O overview · R restart · type a number to jump</div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        {/* numeric-jump HUD — a single top layer above EVERY overlay (device scale), so
+            typing a number reads correctly in slide and end modes. In the overview the
+            buffer renders in its header instead (the grid is the jump surface). */}
+        <AnimatePresence>
+          {jump && !overview && (
+            <motion.div
+              initial={{ opacity: 0, scale: 0.9 }}
+              animate={{ opacity: 1, scale: 1 }}
+              exit={{ opacity: 0 }}
+              className="pointer-events-none absolute left-1/2 top-8 z-[60] -translate-x-1/2 rounded-xl border border-border bg-surface/80 px-5 py-2 font-mono text-2xl text-text backdrop-blur"
+            >
+              → {jump}
+            </motion.div>
+          )}
+        </AnimatePresence>
+
         {/* chrome at DEVICE scale, pinned to the real viewport (outside the scaled
             canvas) so the help + plugin buttons stay tappable on a phone. On touch
             the help affordance becomes a ⋮ action menu (fullscreen, overview, …). */}
@@ -276,7 +452,7 @@ export function Deck({ slides, persistent = [], brands = ["default"], transition
           canDrive={canDrive}
           viewerUrl={liveCtx?.viewerUrl}
           onHelp={() => setHelp(true)}
-          onOverview={() => setOverview((v) => !v)}
+          onOverview={toggleOverview}
           onQr={() => setQr((v) => !v)}
         />
        </div>

package/src/HelpOverlay.tsx

@@ -10,7 +10,7 @@ const EDIT_DOCS_URL = "https://docs.liebstoeckel.app/guides/editing-a-built-deck
 function Kbd({ children, dim }: { children: string; dim?: boolean }) {
   return (
     <kbd
-      className={`inline-flex min-w-[1.9rem] items-center justify-center rounded-md border px-2 py-1 font-mono text-sm shadow-sm ${
+      className={`inline-flex min-w-[1.6rem] items-center justify-center rounded-md border px-1.5 py-0.5 font-mono text-xs shadow-sm ${
         dim ? "border-border/50 bg-bg/40 text-muted" : "border-border bg-bg text-text"
       }`}
     >
@@ -83,10 +83,10 @@ export function HelpOverlay({
             animate={{ opacity: 1, scale: 1, y: 0 }}
             exit={{ opacity: 0, scale: 0.97, y: 8 }}
             transition={{ type: "spring", stiffness: 260, damping: 24 }}
-            className="relative w-[440px] rounded-2xl border border-border bg-surface/90 p-7 shadow-[0_30px_80px_-20px_rgba(0,0,0,0.85)]"
+            className="relative max-h-[88%] w-[400px] overflow-auto rounded-2xl border border-border bg-surface/90 p-6 shadow-[0_30px_80px_-20px_rgba(0,0,0,0.85)]"
           >
-            <div className="mb-5 flex items-baseline justify-between">
-              <span className="font-heading text-2xl font-semibold text-text">Shortcuts</span>
+            <div className="mb-4 flex items-baseline justify-between">
+              <span className="font-heading text-xl font-semibold text-text">Shortcuts</span>
               {role ? (
                 <span className="font-mono text-[11px] uppercase tracking-[0.25em] text-accent">
                   ● live · {role}
@@ -101,7 +101,7 @@ export function HelpOverlay({
                 navigation. You can still interact (e.g. vote).
               </p>
             )}
-            <ul className="space-y-3">
+            <ul className="space-y-1.5">
               {shortcuts.map((s) => {
                 const disabled = isViewer && s.presenterOnly;
                 return (
@@ -110,7 +110,7 @@ export function HelpOverlay({
                     className={`flex items-center justify-between gap-4 ${disabled ? "opacity-40" : ""}`}
                     title={disabled ? "Presenter only" : undefined}
                   >
-                    <span className="font-body text-lg text-text/85">
+                    <span className="font-body text-sm text-text/85">
                       {s.label}
                       {disabled && <span className="ml-2 font-mono text-[10px] uppercase tracking-wider text-muted">presenter</span>}
                     </span>
@@ -127,8 +127,8 @@ export function HelpOverlay({
               })}
             </ul>
             {ejectable && (
-              <div className="mt-6 border-t border-border pt-4">
-                <p className="font-body text-sm text-text/80">
+              <div className="mt-4 border-t border-border pt-3">
+                <p className="font-body text-[13px] text-text/80">
                   This deck embeds its own source, recover it with{" "}
                   <code className="rounded bg-bg/60 px-1.5 py-0.5 font-mono text-[13px] text-text">
                     liebstoeckel eject
@@ -145,7 +145,7 @@ export function HelpOverlay({
                 </p>
               </div>
             )}
-            <div className="mt-6 border-t border-border pt-4 text-center font-mono text-[11px] uppercase tracking-[0.25em] text-muted">
+            <div className="mt-4 border-t border-border pt-3 text-center font-mono text-[11px] uppercase tracking-[0.25em] text-muted">
               right-click anywhere to toggle
             </div>
           </motion.div>

package/src/interaction.ts

@@ -0,0 +1,99 @@
+// Pure keyboard routing for the deck. Given the active interaction *layer* and a
+// key, decide the action — so a modal layer (overview, end) captures its keys and
+// deck navigation never leaks through it. No DOM; unit-testable (key × layer → action).
+import type { GridDir } from "./overview";
+
+export type NavMode = "slide" | "overview" | "end";
+
+export type NavAction =
+  | "next"
+  | "prev"
+  | "first"
+  | "last"
+  | "select"
+  | "exitModal"
+  | "restart"
+  | "toggleBrand"
+  | "presenter"
+  | "fullscreen"
+  | "blur"
+  | "overview"
+  | "qr"
+  | "help"
+  | { grid: GridDir }
+  | { digit: string }
+  | null;
+
+const ARROW_GRID: Record<string, GridDir> = {
+  ArrowLeft: "left",
+  ArrowRight: "right",
+  ArrowUp: "up",
+  ArrowDown: "down",
+};
+
+const isDigit = (key: string) => /^[0-9]$/.test(key);
+
+/** Keys whose browser default (page scroll) we suppress when they map to an action. */
+export function preventsDefault(key: string): boolean {
+  return key in ARROW_GRID || key === " " || key === "PageDown" || key === "PageUp";
+}
+
+export function routeKey(mode: NavMode, key: string): NavAction {
+  // Overview: a modal grid picker. Arrows move the selection, Enter opens it,
+  // digits build a jump, Esc/o close. Everything else is swallowed (no deck nav).
+  if (mode === "overview") {
+    if (key in ARROW_GRID) return { grid: ARROW_GRID[key] };
+    if (key === "Enter") return "select";
+    if (key === "Escape") return "exitModal";
+    if (key === "o") return "overview";
+    if (isDigit(key)) return { digit: key };
+    if (key === "f") return "fullscreen";
+    if (key === "q") return "qr";
+    if (key === "?" || key === "h") return "help";
+    return null;
+  }
+  // End screen: a terminal card. ←/Esc/Backspace go back, o opens the overview,
+  // r/Home restart, digits/Enter jump. Forward keys are swallowed (no replay).
+  if (mode === "end") {
+    if (key === "ArrowLeft" || key === "Escape" || key === "Backspace") return "exitModal";
+    if (key === "o") return "overview";
+    if (key === "r" || key === "Home") return "restart";
+    if (isDigit(key) || key === "Enter") return { digit: key };
+    if (key === "f") return "fullscreen";
+    if (key === "q") return "qr";
+    if (key === "?" || key === "h") return "help";
+    return null;
+  }
+  // Slide (default) — the normal presenting controls.
+  switch (key) {
+    case "ArrowRight":
+    case " ":
+    case "PageDown":
+      return "next";
+    case "ArrowLeft":
+    case "PageUp":
+      return "prev";
+    case "Home":
+      return "first";
+    case "End":
+      return "last";
+    case "t":
+      return "toggleBrand";
+    case "p":
+      return "presenter";
+    case "f":
+      return "fullscreen";
+    case "b":
+      return "blur";
+    case "o":
+      return "overview";
+    case "q":
+      return "qr";
+    case "?":
+    case "h":
+      return "help";
+    default:
+      if (isDigit(key) || key === "Enter" || key === "Escape") return { digit: key };
+      return null;
+  }
+}

package/src/nav.ts

@@ -1,5 +1,7 @@
 import { useEffect } from "react";
 import { resolveTouchGesture, NO_NAV_SELECTOR } from "./mobile";
+import { routeKey, preventsDefault, type NavMode } from "./interaction";
+import type { GridDir } from "./overview";
 
 /** Touch navigation: horizontal swipe + edge tap-zones, resolved by the pure
  *  `resolveTouchGesture`. Reuses `onNext`/`onPrev` so step-reveals still run before
@@ -62,11 +64,15 @@ export function isEditableTarget(target: EventTarget | null): boolean {
   }
 }
 
-// Keyboard navigation. `onNext`/`onPrev` let the deck intercept for step reveals;
-// they fall back to slide nav. Slide index lives in the deck controller (synced).
+// Keyboard navigation, routed by the active interaction layer (`mode`). In a modal
+// layer (overview, end) the layer owns its keys and deck nav never leaks through —
+// the routing is the pure `routeKey` (key × mode → action); this hook just dispatches.
+// `onNext`/`onPrev` let the deck intercept for step reveals; they fall back to slide nav.
 export function useDeckNav(opts: {
   count: number;
   setIndex: (updater: (n: number) => number | number) => void;
+  /** Active interaction layer. Defaults to "slide". */
+  mode?: NavMode;
   onNext?: () => void;
   onPrev?: () => void;
   onToggleBrand?: () => void;
@@ -77,10 +83,19 @@ export function useDeckNav(opts: {
   onOverview?: () => void;
   onQr?: () => void;
   onDigit?: (key: string) => void;
+  /** Overview grid selection move (← → ↑ ↓ while the overview is open). */
+  onGridMove?: (dir: GridDir) => void;
+  /** Confirm the overview selection (Enter). */
+  onSelect?: () => void;
+  /** Close the top modal / go back (Esc, or ← on the end screen). */
+  onExitModal?: () => void;
+  /** Restart to the first slide (R / Home on the end screen). */
+  onRestart?: () => void;
 }) {
   const {
     count,
     setIndex,
+    mode = "slide",
     onNext,
     onPrev,
     onToggleBrand,
@@ -91,6 +106,10 @@ export function useDeckNav(opts: {
     onOverview,
     onQr,
     onDigit,
+    onGridMove,
+    onSelect,
+    onExitModal,
+    onRestart,
   } = opts;
 
   useEffect(() => {
@@ -99,51 +118,33 @@ export function useDeckNav(opts: {
     const onKey = (e: KeyboardEvent) => {
       // don't hijack typing in a plugin's input (Q&A box, etc.)
       if (isEditableTarget(e.target)) return;
-      switch (e.key) {
-        case "ArrowRight":
-        case " ":
-        case "PageDown":
-          e.preventDefault();
-          next();
-          break;
-        case "ArrowLeft":
-        case "PageUp":
-          e.preventDefault();
-          prev();
-          break;
-        case "Home":
-          setIndex(() => 0);
-          break;
-        case "End":
-          setIndex(() => count - 1);
-          break;
-        case "t":
-          onToggleBrand?.();
-          break;
-        case "p":
-          onOpenPresenter?.();
-          break;
-        case "f":
-          onFullscreen?.();
-          break;
-        case "b":
-          onBlur?.();
-          break;
-        case "o":
-          onOverview?.();
-          break;
-        case "q":
-          onQr?.();
-          break;
-        case "?":
-        case "h":
-          onToggleHelp?.();
-          break;
-        default:
-          if (onDigit && (/^[0-9]$/.test(e.key) || e.key === "Enter" || e.key === "Escape")) onDigit(e.key);
+      const action = routeKey(mode, e.key);
+      if (action == null) return;
+      if (preventsDefault(e.key)) e.preventDefault();
+      if (typeof action === "object") {
+        if ("grid" in action) onGridMove?.(action.grid);
+        else onDigit?.(action.digit);
+        return;
+      }
+      switch (action) {
+        case "next": next(); break;
+        case "prev": prev(); break;
+        case "first": setIndex(() => 0); break;
+        case "last": setIndex(() => count - 1); break;
+        case "select": onSelect?.(); break;
+        case "exitModal": onExitModal?.(); break;
+        case "restart": onRestart?.(); break;
+        case "toggleBrand": onToggleBrand?.(); break;
+        case "presenter": onOpenPresenter?.(); break;
+        case "fullscreen": onFullscreen?.(); break;
+        case "blur": onBlur?.(); break;
+        case "overview": onOverview?.(); break;
+        case "qr": onQr?.(); break;
+        case "help": onToggleHelp?.(); break;
       }
     };
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
-  }, [count, setIndex, onNext, onPrev, onToggleBrand, onOpenPresenter, onToggleHelp, onFullscreen, onBlur, onOverview, onQr, onDigit]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count, setIndex, mode, onNext, onPrev, onToggleBrand, onOpenPresenter, onToggleHelp, onFullscreen, onBlur, onOverview, onQr, onDigit, onGridMove, onSelect, onExitModal, onRestart]);
 }

package/src/overview.ts

@@ -0,0 +1,32 @@
+// Pure helpers for the overview grid's keyboard selection. No DOM — unit-testable.
+
+export type GridDir = "left" | "right" | "up" | "down";
+
+/** Columns the overview grid renders at a given viewport width — mirrors the
+ *  Tailwind breakpoints on the grid (`grid-cols-2` base, `sm:grid-cols-3`,
+ *  `lg:grid-cols-4`). Used to make ↑/↓ move by a row. */
+export function gridCols(width: number): number {
+  if (width >= 1024) return 4;
+  if (width >= 640) return 3;
+  return 2;
+}
+
+/** Move a 0-based selection within a `count`-item, `cols`-wide grid by an arrow
+ *  direction, clamped to [0, count-1]. ←/→ step linearly (so you can traverse the
+ *  whole deck, crossing row boundaries); ↑/↓ step by a full row and stop at the
+ *  edges rather than wrapping. */
+export function moveSelection(sel: number, count: number, cols: number, dir: GridDir): number {
+  if (count <= 0) return 0;
+  const c = Math.max(1, cols);
+  const clamp = (n: number) => Math.min(Math.max(n, 0), count - 1);
+  switch (dir) {
+    case "left":
+      return clamp(sel - 1);
+    case "right":
+      return clamp(sel + 1);
+    case "up":
+      return sel - c >= 0 ? sel - c : sel;
+    case "down":
+      return sel + c <= count - 1 ? sel + c : sel;
+  }
+}