feat(timeline): add keyboard navigation with shortcut overlay

- Arrow left/right scrolls the timeline by 1 day (Shift: 1 week)
- Delete/Backspace deletes selected allocations
- ? toggles a keyboard shortcut overlay
- Floating ? button in bottom-right corner provides persistent access
- (Del) hint added to the FloatingActionBar delete button

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/web/src/components/timeline/FloatingActionBar.tsx

@@ -55,7 +55,9 @@ export function FloatingActionBar({
             "disabled:opacity-40 disabled:cursor-not-allowed",
           )}
         >
-          {isDeleting ? "Deleting\u2026" : "Delete"}
+          {isDeleting ? "Deleting\u2026" : (
+            <>Delete <span className="opacity-60 text-[10px]">(Del)</span></>
+          )}
         </button>
       )}
 

apps/web/src/components/timeline/KeyboardShortcutOverlay.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+const SHORTCUTS: { keys: string; description: string }[] = [
+  { keys: "← / →", description: "Scroll timeline 1 day" },
+  { keys: "Shift + ← / →", description: "Scroll timeline 1 week" },
+  { keys: "Delete / Backspace", description: "Delete selected allocations" },
+  { keys: "Ctrl / Cmd + Z", description: "Undo last action" },
+  { keys: "Ctrl / Cmd + Shift + Z", description: "Redo" },
+  { keys: "Shift + Wheel", description: "Horizontal scroll" },
+  { keys: "ESC", description: "Close popover / clear selection" },
+  { keys: "?", description: "Toggle this overlay" },
+];
+
+interface KeyboardShortcutOverlayProps {
+  onClose: () => void;
+}
+
+export function KeyboardShortcutOverlay({ onClose }: KeyboardShortcutOverlayProps) {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40" onClick={onClose}>
+      <div
+        className="bg-white dark:bg-gray-800 rounded-2xl shadow-2xl border border-gray-200 dark:border-gray-700 w-full max-w-sm mx-4 overflow-hidden"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-100 dark:border-gray-700">
+          <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100">Keyboard Shortcuts</h2>
+          <button
+            onClick={onClose}
+            className="text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-300 text-lg leading-none"
+          >
+            &times;
+          </button>
+        </div>
+        <ul className="divide-y divide-gray-50 dark:divide-gray-700/50">
+          {SHORTCUTS.map((s) => (
+            <li key={s.keys} className="flex items-center justify-between gap-4 px-5 py-2.5">
+              <span className="text-xs text-gray-500 dark:text-gray-400">{s.description}</span>
+              <kbd className="shrink-0 rounded-md border border-gray-200 dark:border-gray-600 bg-gray-50 dark:bg-gray-900 px-2 py-0.5 font-mono text-[11px] text-gray-700 dark:text-gray-300">
+                {s.keys}
+              </kbd>
+            </li>
+          ))}
+        </ul>
+        <div className="px-5 py-3 border-t border-gray-100 dark:border-gray-700 text-[11px] text-gray-400 dark:text-gray-500 text-center">
+          Press <kbd className="font-mono">?</kbd> to toggle
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/src/components/timeline/TimelineView.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { MILLISECONDS_PER_DAY } from "@capakraken/shared";
 import { clsx } from "clsx";
 import { useSession } from "next-auth/react";
 import { useEffect, useMemo, useRef, useState } from "react";
@@ -35,6 +36,9 @@ import { TimelineProjectPanel, type OpenDemandAssignment } from "./TimelineProje
 import { ProjectColorLegend } from "./ProjectColorLegend.js";
 import { useMultiSelectIntersection } from "~/hooks/useMultiSelectIntersection.js";
 import type { TimelineVisualOverrides } from "./allocationVisualState.js";
+import { SuccessToast } from "~/components/ui/SuccessToast.js";
+import { useTimelineKeyboard } from "~/hooks/useTimelineKeyboard.js";
+import { KeyboardShortcutOverlay } from "./KeyboardShortcutOverlay.js";
 
 // ─── Entry point ────────────────────────────────────────────────────────────
 // Two-layer mount: the outer shell creates drag state + project context,
@@ -86,6 +90,8 @@ export function TimelineView() {
     onSuccess: invalidateTimeline,
   });
 
+  const [dragErrorToast, setDragErrorToast] = useState<string | null>(null);
+
   const {
     dragState,
     allocDragState,
@@ -156,6 +162,7 @@ export function TimelineView() {
         clearMultiSelect();
       }
     },
+    onMutationError: (message) => setDragErrorToast(message),
   });
 
   const [openPanelProjectId, setOpenPanelProjectId] = useState<string | null>(null);
@@ -164,6 +171,13 @@ export function TimelineView() {
   const { contextResourceIds, contextAllocations } = useProjectDragContext(contextProjectId, canManageTimeline);
 
   return (
+    <>
+    <SuccessToast
+      show={dragErrorToast !== null}
+      message={dragErrorToast ?? ""}
+      variant="warning"
+      onDone={() => setDragErrorToast(null)}
+    />
     <TimelineProvider
       isDragging={dragState.isDragging}
       contextAllocations={contextAllocations as TimelineAssignmentEntry[]}
@@ -209,6 +223,7 @@ export function TimelineView() {
         redo={redo}
       />
     </TimelineProvider>
+    </>
   );
 }
 
@@ -368,6 +383,20 @@ function TimelineViewContent({
 
   const { CELL_WIDTH, dates, totalCanvasWidth, toLeft, toWidth, gridLines, monthGroups, xToDate } =
     useTimelineLayout(viewStart, viewDays, filters.zoom, filters.showWeekends, today);
+
+  const { showShortcuts, setShowShortcuts } = useTimelineKeyboard({
+    scrollContainerRef,
+    cellWidth: CELL_WIDTH,
+    selectedAllocationIds: multiSelectState.selectedAllocationIds,
+    onDeleteSelected: () => {
+      if (multiSelectState.selectedAllocationIds.length === 0) return;
+      const msg = `Delete ${multiSelectState.selectedAllocationIds.length} allocation(s)? This cannot be undone.`;
+      if (window.confirm(msg)) {
+        batchDeleteMutation.mutate({ ids: multiSelectState.selectedAllocationIds });
+      }
+    },
+  });
+
   const hasActivePointerOverlay =
     dragState.isDragging || allocDragState.isActive || rangeState.isSelecting || multiSelectState.isMultiDragging;
 
@@ -896,7 +925,7 @@ function TimelineViewContent({
               rangeState.startDate <= end
                 ? [rangeState.startDate, end]
                 : [end, rangeState.startDate];
-            const days = Math.round((e.getTime() - s.getTime()) / 86400000) + 1;
+            const days = Math.round((e.getTime() - s.getTime()) / MILLISECONDS_PER_DAY) + 1;
             return `${days} day${days !== 1 ? "s" : ""}`;
           })()}
         </div>
@@ -1066,6 +1095,19 @@ function TimelineViewContent({
           onClose={() => setResourceHover(null)}
         />
       )}
+
+      {/* Keyboard shortcut overlay */}
+      {showShortcuts && <KeyboardShortcutOverlay onClose={() => setShowShortcuts(false)} />}
+
+      {/* Keyboard shortcut hint button */}
+      <button
+        type="button"
+        onClick={() => setShowShortcuts((prev) => !prev)}
+        title="Keyboard shortcuts (?)"
+        className="fixed bottom-6 right-6 z-40 rounded-full w-8 h-8 flex items-center justify-center bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 shadow text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200 text-sm font-medium"
+      >
+        ?
+      </button>
     </div>
   );
 }

apps/web/src/hooks/useTimelineKeyboard.ts

@@ -0,0 +1,88 @@
+import React, { useEffect, useRef, useState } from "react";
+import type { RefObject } from "react";
+
+interface UseTimelineKeyboardOptions {
+  scrollContainerRef: RefObject<HTMLElement | null>;
+  cellWidth: number;
+  selectedAllocationIds: string[];
+  onDeleteSelected: () => void;
+}
+
+export interface UseTimelineKeyboardResult {
+  showShortcuts: boolean;
+  setShowShortcuts: React.Dispatch<React.SetStateAction<boolean>>;
+}
+
+function isTypingTarget(el: Element | null): boolean {
+  if (!el) return false;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "input" || tag === "textarea" || tag === "select") return true;
+  if ((el as HTMLElement).isContentEditable) return true;
+  return false;
+}
+
+export function useTimelineKeyboard({
+  scrollContainerRef,
+  cellWidth,
+  selectedAllocationIds,
+  onDeleteSelected,
+}: UseTimelineKeyboardOptions): UseTimelineKeyboardResult {
+  const [showShortcuts, setShowShortcuts] = useState(false);
+
+  // Keep stable refs so the handler closure doesn't need to be re-registered on every render
+  const onDeleteRef = useRef(onDeleteSelected);
+  onDeleteRef.current = onDeleteSelected;
+  const selectedCountRef = useRef(selectedAllocationIds.length);
+  selectedCountRef.current = selectedAllocationIds.length;
+  const cellWidthRef = useRef(cellWidth);
+  cellWidthRef.current = cellWidth;
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (isTypingTarget(document.activeElement)) return;
+
+      const isMac = navigator.platform.toUpperCase().includes("MAC");
+      const modKey = isMac ? e.metaKey : e.ctrlKey;
+      const dayPx = cellWidthRef.current;
+      const el = scrollContainerRef.current;
+
+      switch (e.key) {
+        case "?":
+          e.preventDefault();
+          setShowShortcuts((prev) => !prev);
+          break;
+
+        case "ArrowLeft":
+          if (el) {
+            e.preventDefault();
+            el.scrollLeft -= (e.shiftKey ? 7 : 1) * dayPx;
+          }
+          break;
+
+        case "ArrowRight":
+          if (el) {
+            e.preventDefault();
+            el.scrollLeft += (e.shiftKey ? 7 : 1) * dayPx;
+          }
+          break;
+
+        case "Delete":
+        case "Backspace":
+          if (modKey) break; // let browser handle Cmd+Backspace etc.
+          if (selectedCountRef.current > 0) {
+            e.preventDefault();
+            onDeleteRef.current();
+          }
+          break;
+
+        default:
+          break;
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [scrollContainerRef]); // stable — uses refs for everything that changes
+
+  return { showShortcuts, setShowShortcuts };
+}