refactor(ui): unify context menus into a shared menu system

Five hand-rolled context menu implementations (image tiles, sidebar
folders, sidebar albums, title bar theme switcher, plus duplicated
close-listener effects in Gallery/Timeline) are replaced by shared
primitives in src/components/menu/:

- useDismissable: one outside-pointerdown + Escape dismissal hook
- Menu.tsx: MenuPanel chrome, MenuItem (danger/disabled/checked/hint),
  MenuSeparator, MenuLabel, and SubMenu with viewport edge-flipping
- ContextMenu: portal-rendered wrapper that measures and clamps to the
  viewport, fixing menus rendering off-screen and the latent
  fixed-inside-transform bug under framer-motion Reorder items

The image right-click menu moves to ImageContextMenu.tsx, shared by
Gallery and Timeline.

CHANGELOG.md

@@ -59,6 +59,9 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Changed
 
+- **Consistent right-click menus** — the folder, album, image, and theme menus
+  now share one look and behavior: they stay inside the window instead of
+  spilling off the edge, close on Escape, and support proper submenus.
 - **Neater lightbox details** — image and video metadata now sits in two columns,
   so the info panel shows more at a glance with less scrolling.
 - **Faster Explore revisits** — returning to a folder's visual clusters should

src/components/Gallery.tsx

@@ -2,6 +2,7 @@ import { useEffect, useLayoutEffect, useRef, useCallback, useMemo, useState } fr
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { ImageRecord, parseSearchValue, tileSizeForZoom, useGalleryStore } from "../store";
 import { BulkActionBar } from "./BulkActionBar";
+import { ImageContextMenu } from "./ImageContextMenu";
 import { Tooltip } from "./Tooltip";
 import { mediaSrc } from "../lib/mediaSrc";
 
@@ -19,94 +20,6 @@ function formatDuration(durationMs: number | null): string | null {
   return `${minutes}:${seconds.toString().padStart(2, "0")}`;
 }
 
-export function ContextMenu({
-  x,
-  y,
-  image,
-  onClose,
-}: {
-  x: number;
-  y: number;
-  image: ImageRecord;
-  onClose: () => void;
-}) {
-  const openImage = useGalleryStore((state) => state.openImage);
-  const updateImageDetails = useGalleryStore((state) => state.updateImageDetails);
-  const findSimilar = useGalleryStore((state) => state.findSimilar);
-  const canFindSimilar = image.embedding_status === "ready";
-
-  return (
-    <div
-      data-gallery-context-menu
-      className="fixed z-40 min-w-52 rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl backdrop-blur"
-      style={{ left: x, top: y }}
-      onClick={(event) => event.stopPropagation()}
-    >
-      <button
-        className="w-full rounded-lg px-3 py-2 text-left text-sm text-gray-200 hover:bg-white/5 hover:text-white transition-colors"
-        onClick={() => { openImage(image); onClose(); }}
-      >
-        Open Preview
-      </button>
-      <button
-        className="w-full rounded-lg px-3 py-2 text-left text-sm text-gray-200 hover:bg-white/5 hover:text-white transition-colors"
-        onClick={async () => { await updateImageDetails(image.id, { favorite: !image.favorite }); onClose(); }}
-      >
-        {image.favorite ? "Remove Favorite" : "Add to Favorites"}
-      </button>
-      <button
-        className={`w-full rounded-lg px-3 py-2 text-left text-sm transition-colors ${
-          canFindSimilar
-            ? "text-gray-200 hover:bg-white/5 hover:text-white"
-            : "text-gray-600 cursor-not-allowed"
-        }`}
-        onClick={() => {
-          if (!canFindSimilar) return;
-          findSimilar(image.id, image.folder_id);
-          onClose();
-        }}
-        disabled={!canFindSimilar}
-      >
-        {canFindSimilar ? "Find Similar" : "Embeddings not ready"}
-      </button>
-      <div className="my-1 h-px bg-white/[0.06]" />
-      <div className="px-3 py-1 text-[10px] uppercase tracking-[0.18em] text-gray-600">Rating</div>
-      <div className="flex items-center gap-0.5 px-2 pb-1.5">
-        {Array.from({ length: 5 }, (_, index) => {
-          const rating = index + 1;
-          return (
-            <Tooltip key={rating} label={`Set ${rating} star rating`} followCursor>
-              <button
-                className="rounded-md p-1 transition-colors hover:bg-white/5"
-                onClick={async () => { await updateImageDetails(image.id, { rating }); onClose(); }}
-              >
-                <svg
-                  className={`h-4 w-4 ${rating <= image.rating ? "text-amber-300" : "text-white/20 hover:text-white/40"}`}
-                  fill="currentColor" viewBox="0 0 20 20"
-                >
-                  <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
-                </svg>
-              </button>
-            </Tooltip>
-          );
-        })}
-        {image.rating > 0 ? (
-          <Tooltip label="Remove rating" followCursor>
-            <button
-              className="ml-1 rounded-md p-1 text-gray-600 hover:bg-white/5 hover:text-gray-300 transition-colors"
-              onClick={async () => { await updateImageDetails(image.id, { rating: 0 }); onClose(); }}
-            >
-              <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-              </svg>
-            </button>
-          </Tooltip>
-        ) : null}
-      </div>
-    </div>
-  );
-}
-
 export function ImageTile({
   image,
   onClick,
@@ -395,22 +308,6 @@ export function Gallery() {
     return () => el.removeEventListener("scroll", handleScroll);
   }, [handleScroll]);
 
-  useEffect(() => {
-    const close = (event: PointerEvent) => {
-      if ((event.target as HTMLElement | null)?.closest("[data-gallery-context-menu]")) return;
-      setContextMenu(null);
-    };
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") setContextMenu(null);
-    };
-    window.addEventListener("pointerdown", close);
-    window.addEventListener("keydown", handleKeyDown);
-    return () => {
-      window.removeEventListener("pointerdown", close);
-      window.removeEventListener("keydown", handleKeyDown);
-    };
-  }, []);
-
   return (
     <div className="relative flex-1 min-h-0">
     <div ref={parentRef} className="absolute inset-0 overflow-y-auto overflow-x-hidden bg-gray-950">
@@ -515,7 +412,7 @@ export function Gallery() {
       ) : null}
 
       {contextMenu ? (
-        <ContextMenu
+        <ImageContextMenu
           x={contextMenu.x}
           y={contextMenu.y}
           image={contextMenu.image}

src/components/ImageContextMenu.tsx

@@ -0,0 +1,70 @@
+import { ImageRecord, useGalleryStore } from "../store";
+import { ContextMenu, MenuItem, MenuLabel, MenuSeparator } from "./menu";
+import { Tooltip } from "./Tooltip";
+
+/** Right-click menu for an image tile. Shared by the Gallery grid and the Timeline. */
+export function ImageContextMenu({
+  x,
+  y,
+  image,
+  onClose,
+}: {
+  x: number;
+  y: number;
+  image: ImageRecord;
+  onClose: () => void;
+}) {
+  const openImage = useGalleryStore((state) => state.openImage);
+  const updateImageDetails = useGalleryStore((state) => state.updateImageDetails);
+  const findSimilar = useGalleryStore((state) => state.findSimilar);
+  const canFindSimilar = image.embedding_status === "ready";
+
+  return (
+    <ContextMenu x={x} y={y} onClose={onClose}>
+      <MenuItem label="Open Preview" onSelect={() => openImage(image)} />
+      <MenuItem
+        label={image.favorite ? "Remove Favorite" : "Add to Favorites"}
+        onSelect={() => void updateImageDetails(image.id, { favorite: !image.favorite })}
+      />
+      <MenuItem
+        label={canFindSimilar ? "Find Similar" : "Embeddings not ready"}
+        disabled={!canFindSimilar}
+        onSelect={() => findSimilar(image.id, image.folder_id)}
+      />
+      <MenuSeparator />
+      <MenuLabel>Rating</MenuLabel>
+      <div className="flex items-center gap-0.5 px-2 pb-1.5">
+        {Array.from({ length: 5 }, (_, index) => {
+          const rating = index + 1;
+          return (
+            <Tooltip key={rating} label={`Set ${rating} star rating`} followCursor>
+              <button
+                className="rounded-md p-1 transition-colors hover:bg-white/5"
+                onClick={async () => { await updateImageDetails(image.id, { rating }); onClose(); }}
+              >
+                <svg
+                  className={`h-4 w-4 ${rating <= image.rating ? "text-amber-300" : "text-white/20 hover:text-white/40"}`}
+                  fill="currentColor" viewBox="0 0 20 20"
+                >
+                  <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.176 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81H7.03a1 1 0 00.951-.69l1.07-3.292z" />
+                </svg>
+              </button>
+            </Tooltip>
+          );
+        })}
+        {image.rating > 0 ? (
+          <Tooltip label="Remove rating" followCursor>
+            <button
+              className="ml-1 rounded-md p-1 text-gray-600 hover:bg-white/5 hover:text-gray-300 transition-colors"
+              onClick={async () => { await updateImageDetails(image.id, { rating: 0 }); onClose(); }}
+            >
+              <svg className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </Tooltip>
+        ) : null}
+      </div>
+    </ContextMenu>
+  );
+}

src/components/Sidebar.tsx

@@ -3,88 +3,13 @@ import { Reorder, useDragControls } from "framer-motion";
 import { open } from "@tauri-apps/plugin-dialog";
 import { useGalleryStore, Folder, Album, IndexProgress } from "../store";
 import { ThemedDropdown } from "./ThemedDropdown";
+import { ContextMenu, MenuItem, MenuSeparator } from "./menu";
 import { mediaSrc } from "../lib/mediaSrc";
 import { Tooltip } from "./Tooltip";
 
-interface ContextMenuState {
-  folderId: number;
-  x: number;
-  y: number;
-}
-
 type LibrarySort = "az" | "za" | "custom";
 const LIBRARY_SORT_KEY = "phokus-library-sort";
 
-function FolderContextMenu({
-  menu,
-  folder,
-  isMuted,
-  isPausedAll,
-  onClose,
-  onRename,
-  onReindex,
-  onLocate,
-  onToggleMute,
-  onTogglePauseAll,
-  onRemove,
-}: {
-  menu: ContextMenuState;
-  folder: Folder;
-  isMuted: boolean;
-  isPausedAll: boolean;
-  onClose: () => void;
-  onRename: () => void;
-  onReindex: () => void;
-  onLocate: () => void;
-  onToggleMute: () => void;
-  onTogglePauseAll: () => void;
-  onRemove: () => void;
-}) {
-  const ref = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const handleDown = (e: MouseEvent) => {
-      if (ref.current && !ref.current.contains(e.target as Node)) onClose();
-    };
-    const handleKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
-    document.addEventListener("mousedown", handleDown);
-    document.addEventListener("keydown", handleKey);
-    return () => {
-      document.removeEventListener("mousedown", handleDown);
-      document.removeEventListener("keydown", handleKey);
-    };
-  }, [onClose]);
-
-  const item = (label: string, onClick: () => void, danger = false) => (
-    <button
-      className={`w-full text-left px-3 py-1.5 text-[12px] rounded-md transition-colors ${
-        danger
-          ? "text-red-400 hover:bg-red-500/15 hover:text-red-300"
-          : "text-gray-300 hover:bg-white/8 hover:text-white"
-      }`}
-      onClick={() => { onClick(); onClose(); }}
-    >
-      {label}
-    </button>
-  );
-
-  return (
-    <div
-      ref={ref}
-      className="fixed z-50 min-w-[160px] py-1 px-1 rounded-lg bg-gray-900 border border-white/10 shadow-xl shadow-black/50"
-      style={{ left: menu.x, top: menu.y }}
-    >
-      {item("Reindex", onReindex)}
-      {item("Rename", onRename)}
-      {item(isPausedAll ? "Resume background work" : "Pause background work", onTogglePauseAll)}
-      {item(isMuted ? "Unmute notifications" : "Mute notifications", onToggleMute)}
-      {folder.scan_error && item("Locate Folder", onLocate)}
-      <div className="my-1 border-t border-white/[0.06]" />
-      {item("Remove from app", onRemove, true)}
-    </div>
-  );
-}
-
 function FolderItem({
   folder,
   selected,
@@ -116,7 +41,7 @@ function FolderItem({
   const isIndexing = progress && !progress.done;
   const isMissing = !!folder.scan_error && !isIndexing;
 
-  const [contextMenu, setContextMenu] = useState<ContextMenuState | null>(null);
+  const [contextMenu, setContextMenu] = useState<{ x: number; y: number } | null>(null);
   const [renaming, setRenaming] = useState(false);
   const [renameValue, setRenameValue] = useState(folder.name);
   const [confirmingRemoval, setConfirmingRemoval] = useState(false);
@@ -132,10 +57,7 @@ function FolderItem({
   const handleContextMenu = (e: React.MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
-    // Keep menu inside viewport
-    const x = Math.min(e.clientX, window.innerWidth - 180);
-    const y = Math.min(e.clientY, window.innerHeight - 160);
-    setContextMenu({ folderId: folder.id, x, y });
+    setContextMenu({ x: e.clientX, y: e.clientY });
   };
 
   const handleLocateFolder = async () => {
@@ -325,84 +247,27 @@ function FolderItem({
         </div>
       )}
 
-      {contextMenu && contextMenu.folderId === folder.id && (
-        <FolderContextMenu
-          menu={contextMenu}
-          folder={folder}
-          isMuted={isMuted}
-          isPausedAll={isPausedAll}
-          onClose={() => setContextMenu(null)}
-          onRename={() => setRenaming(true)}
-          onReindex={() => void reindexFolder(folder.id)}
-          onLocate={() => void handleLocateFolder()}
-          onToggleMute={() => toggleMutedFolder(folder.id)}
-          onTogglePauseAll={() => setAllWorkersPaused(folder.id, !isPausedAll)}
-          onRemove={() => setConfirmingRemoval(true)}
-        />
+      {contextMenu && (
+        <ContextMenu x={contextMenu.x} y={contextMenu.y} size="sm" onClose={() => setContextMenu(null)}>
+          <MenuItem label="Reindex" onSelect={() => void reindexFolder(folder.id)} />
+          <MenuItem label="Rename" onSelect={() => setRenaming(true)} />
+          <MenuItem
+            label={isPausedAll ? "Resume background work" : "Pause background work"}
+            onSelect={() => setAllWorkersPaused(folder.id, !isPausedAll)}
+          />
+          <MenuItem
+            label={isMuted ? "Unmute notifications" : "Mute notifications"}
+            onSelect={() => toggleMutedFolder(folder.id)}
+          />
+          {folder.scan_error ? <MenuItem label="Locate Folder" onSelect={() => void handleLocateFolder()} /> : null}
+          <MenuSeparator />
+          <MenuItem label="Remove from app" danger onSelect={() => setConfirmingRemoval(true)} />
+        </ContextMenu>
       )}
     </Reorder.Item>
   );
 }
 
-function AlbumContextMenu({
-  x,
-  y,
-  onClose,
-  onRename,
-  onDelete,
-}: {
-  x: number;
-  y: number;
-  onClose: () => void;
-  onRename: () => void;
-  onDelete: () => void;
-}) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const handleDown = (e: MouseEvent) => {
-      if (ref.current && !ref.current.contains(e.target as Node)) onClose();
-    };
-    const handleKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose();
-    };
-    document.addEventListener("mousedown", handleDown);
-    document.addEventListener("keydown", handleKey);
-    return () => {
-      document.removeEventListener("mousedown", handleDown);
-      document.removeEventListener("keydown", handleKey);
-    };
-  }, [onClose]);
-
-  const item = (label: string, onClick: () => void, danger = false) => (
-    <button
-      className={`w-full text-left px-3 py-1.5 text-[12px] rounded-md transition-colors ${
-        danger
-          ? "text-red-400 hover:bg-red-500/15 hover:text-red-300"
-          : "text-gray-300 hover:bg-white/8 hover:text-white"
-      }`}
-      onClick={(event) => {
-        event.stopPropagation();
-        onClick();
-        onClose();
-      }}
-    >
-      {label}
-    </button>
-  );
-
-  return (
-    <div
-      ref={ref}
-      className="fixed z-50 min-w-[160px] py-1 px-1 rounded-lg bg-gray-900 border border-white/10 shadow-xl shadow-black/50"
-      style={{ left: x, top: y }}
-    >
-      {item("Rename", onRename)}
-      <div className="my-1 border-t border-white/[0.06]" />
-      {item("Delete album", onDelete, true)}
-    </div>
-  );
-}
-
 function AlbumItem({
   album,
   manageMode = false,
@@ -485,7 +350,7 @@ function AlbumItem({
         if (manageMode) return;
         e.preventDefault();
         e.stopPropagation();
-        setMenu({ x: Math.min(e.clientX, window.innerWidth - 180), y: Math.min(e.clientY, window.innerHeight - 120) });
+        setMenu({ x: e.clientX, y: e.clientY });
       }}
     >
       {/* Manage-mode selection checkbox */}
@@ -578,13 +443,11 @@ function AlbumItem({
       ) : null}
 
       {menu ? (
-        <AlbumContextMenu
-          x={menu.x}
-          y={menu.y}
-          onClose={() => setMenu(null)}
-          onRename={() => setRenaming(true)}
-          onDelete={() => setConfirmingRemoval(true)}
-        />
+        <ContextMenu x={menu.x} y={menu.y} size="sm" onClose={() => setMenu(null)}>
+          <MenuItem label="Rename" onSelect={() => setRenaming(true)} />
+          <MenuSeparator />
+          <MenuItem label="Delete album" danger onSelect={() => setConfirmingRemoval(true)} />
+        </ContextMenu>
       ) : null}
     </div>
   );

src/components/Timeline.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { ImageRecord, tileSizeForZoom, useGalleryStore } from "../store";
-import { ContextMenu, ImageTile } from "./Gallery";
+import { ImageTile } from "./Gallery";
+import { ImageContextMenu } from "./ImageContextMenu";
 import { Tooltip } from "./Tooltip";
 
 const GAP = 6;
@@ -204,22 +205,6 @@ export function Timeline() {
     return () => el.removeEventListener("scroll", handleScroll);
   }, [handleScroll]);
 
-  useEffect(() => {
-    const close = (e: PointerEvent) => {
-      if ((e.target as HTMLElement | null)?.closest("[data-gallery-context-menu]")) return;
-      setContextMenu(null);
-    };
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setContextMenu(null);
-    };
-    window.addEventListener("pointerdown", close);
-    window.addEventListener("keydown", onKey);
-    return () => {
-      window.removeEventListener("pointerdown", close);
-      window.removeEventListener("keydown", onKey);
-    };
-  }, []);
-
   const scrollToGroup = useCallback(
     (groupIndex: number) => {
       const row = groupFirstRowRef.current[groupIndex] ?? 0;
@@ -353,7 +338,7 @@ export function Timeline() {
       ) : null}
 
       {contextMenu ? (
-        <ContextMenu
+        <ImageContextMenu
           x={contextMenu.x}
           y={contextMenu.y}
           image={contextMenu.image}

src/components/TitleBar.tsx

@@ -1,6 +1,7 @@
 import { useState, useEffect, useRef } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { useGalleryStore, AppTheme } from "../store";
+import { ContextMenu, MenuItem, MenuLabel } from "./menu";
 import { PhokusMark } from "./PhokusMark";
 import { Tooltip } from "./Tooltip";
 
@@ -57,28 +58,13 @@ export function TitleBar() {
   // Right-clicking the settings cog opens a quick theme switcher, anchored under
   // the cog so it never overflows the right edge of the window.
   const settingsBtnRef = useRef<HTMLButtonElement>(null);
-  const themeMenuRef = useRef<HTMLDivElement>(null);
-  const [themeMenu, setThemeMenu] = useState<{ top: number; right: number } | null>(null);
-
-  useEffect(() => {
-    if (!themeMenu) return;
-    const handleDown = (e: MouseEvent) => {
-      if (themeMenuRef.current && !themeMenuRef.current.contains(e.target as Node)) setThemeMenu(null);
-    };
-    const handleKey = (e: KeyboardEvent) => { if (e.key === "Escape") setThemeMenu(null); };
-    document.addEventListener("mousedown", handleDown);
-    document.addEventListener("keydown", handleKey);
-    return () => {
-      document.removeEventListener("mousedown", handleDown);
-      document.removeEventListener("keydown", handleKey);
-    };
-  }, [themeMenu]);
+  const [themeMenu, setThemeMenu] = useState<{ x: number; y: number } | null>(null);
 
   const handleSettingsContextMenu = (e: React.MouseEvent) => {
     e.preventDefault();
     const rect = settingsBtnRef.current?.getBoundingClientRect();
     if (!rect) return;
-    setThemeMenu({ top: rect.bottom + 4, right: window.innerWidth - rect.right });
+    setThemeMenu({ x: rect.right, y: rect.bottom + 4 });
   };
 
   useEffect(() => {
@@ -188,32 +174,17 @@ export function TitleBar() {
 
       {/* Quick theme switcher — opened by right-clicking the settings cog. */}
       {themeMenu && (
-        <div
-          ref={themeMenuRef}
-          className="fixed z-50 min-w-[170px] py-1 px-1 rounded-lg bg-gray-900 border border-white/10 shadow-xl shadow-black/50"
-          style={{ top: themeMenu.top, right: themeMenu.right, WebkitAppRegion: "no-drag" } as React.CSSProperties}
-        >
-          <div className="px-3 pt-1 pb-1 text-[10px] font-semibold uppercase tracking-wide text-gray-500">Theme</div>
-          {THEME_OPTIONS.map((opt) => {
-            const active = theme === opt.value;
-            return (
-              <button
-                key={opt.value}
-                className={`flex w-full items-center justify-between gap-3 rounded-md px-3 py-1.5 text-left text-[12px] transition-colors ${
-                  active ? "bg-white/8 text-white" : "text-gray-300 hover:bg-white/8 hover:text-white"
-                }`}
-                onClick={() => { setTheme(opt.value); setThemeMenu(null); }}
-              >
-                {opt.label}
-                {active && (
-                  <svg className="h-3.5 w-3.5 text-sky-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
-                  </svg>
-                )}
-              </button>
-            );
-          })}
-        </div>
+        <ContextMenu x={themeMenu.x} y={themeMenu.y} size="sm" align="end" onClose={() => setThemeMenu(null)}>
+          <MenuLabel>Theme</MenuLabel>
+          {THEME_OPTIONS.map((opt) => (
+            <MenuItem
+              key={opt.value}
+              label={opt.label}
+              checked={theme === opt.value}
+              onSelect={() => setTheme(opt.value)}
+            />
+          ))}
+        </ContextMenu>
       )}
     </div>
   );

src/components/menu/ContextMenu.tsx

@@ -0,0 +1,67 @@
+import { ReactNode, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { MenuCloseContext, MenuPanel, MenuSize } from "./Menu";
+import { useDismissable } from "./useDismissable";
+
+/**
+ * Positioned floating menu. Renders through a portal so it is never caught
+ * inside transformed ancestors (framer-motion drag/layout items), and clamps
+ * itself to the viewport after measuring its real size.
+ *
+ * `align="start"` puts the panel's top-left at (x, y) — right-click menus.
+ * `align="end"` puts the top-right at (x, y) — menus anchored under a
+ * right-edge button.
+ */
+export function ContextMenu({
+  x,
+  y,
+  onClose,
+  size = "md",
+  align = "start",
+  className,
+  children,
+}: {
+  x: number;
+  y: number;
+  onClose: () => void;
+  size?: MenuSize;
+  align?: "start" | "end";
+  className?: string;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [pos, setPos] = useState<{ left: number; top: number } | null>(null);
+
+  useDismissable(ref, onClose);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const margin = 8;
+    const rect = el.getBoundingClientRect();
+    const desiredLeft = align === "end" ? x - rect.width : x;
+    setPos({
+      left: Math.max(margin, Math.min(desiredLeft, window.innerWidth - rect.width - margin)),
+      top: Math.max(margin, Math.min(y, window.innerHeight - rect.height - margin)),
+    });
+  }, [x, y, align]);
+
+  return createPortal(
+    <div
+      ref={ref}
+      className="fixed z-50"
+      // Render hidden at the raw coordinates for the measuring pass; the
+      // layout effect swaps in the clamped position before paint.
+      style={pos ?? { left: x, top: y, visibility: "hidden" }}
+      onClick={(event) => event.stopPropagation()}
+      onContextMenu={(event) => event.preventDefault()}
+    >
+      <MenuCloseContext.Provider value={onClose}>
+        <MenuPanel size={size} className={className}>
+          {children}
+        </MenuPanel>
+      </MenuCloseContext.Provider>
+    </div>,
+    document.body,
+  );
+}

src/components/menu/Menu.tsx

@@ -0,0 +1,198 @@
+import {
+  ReactNode,
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+
+export type MenuSize = "sm" | "md";
+
+/** Provided by ContextMenu so any nested MenuItem (submenus included) can close the whole menu. */
+export const MenuCloseContext = createContext<() => void>(() => {});
+const MenuSizeContext = createContext<MenuSize>("md");
+
+function itemClass(size: MenuSize, danger: boolean, disabled: boolean): string {
+  const base =
+    size === "sm"
+      ? "w-full rounded-md px-3 py-1.5 text-[12px]"
+      : "w-full rounded-lg px-3 py-2 text-sm";
+  const tone = disabled
+    ? "text-gray-600 cursor-not-allowed"
+    : danger
+      ? "text-red-400 hover:bg-red-500/15 hover:text-red-300"
+      : "text-gray-200 hover:bg-white/[0.06] hover:text-white";
+  return `${base} ${tone} transition-colors`;
+}
+
+/**
+ * The panel chrome shared by every menu surface. Size defaults to the
+ * enclosing menu's size so submenu panels match their parent automatically.
+ */
+export function MenuPanel({
+  size,
+  className = "",
+  children,
+}: {
+  size?: MenuSize;
+  className?: string;
+  children: ReactNode;
+}) {
+  const inherited = useContext(MenuSizeContext);
+  const resolved = size ?? inherited;
+  return (
+    <MenuSizeContext.Provider value={resolved}>
+      <div
+        className={`${resolved === "sm" ? "min-w-40" : "min-w-52"} rounded-xl border border-white/10 bg-gray-950/98 p-1 shadow-2xl shadow-black/40 backdrop-blur light-theme:border-gray-700/50 ${className}`}
+      >
+        {children}
+      </div>
+    </MenuSizeContext.Provider>
+  );
+}
+
+export function MenuItem({
+  label,
+  onSelect,
+  danger = false,
+  disabled = false,
+  checked,
+  hint,
+  keepOpen = false,
+}: {
+  label: ReactNode;
+  onSelect?: () => void;
+  danger?: boolean;
+  disabled?: boolean;
+  /** Renders a trailing check mark; use for exclusive-choice menus (themes, sort orders). */
+  checked?: boolean;
+  hint?: ReactNode;
+  /** Skip the automatic menu close after selecting. */
+  keepOpen?: boolean;
+}) {
+  const size = useContext(MenuSizeContext);
+  const close = useContext(MenuCloseContext);
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      className={`${itemClass(size, danger, disabled)} flex items-center justify-between gap-3`}
+      onClick={() => {
+        if (disabled) return;
+        onSelect?.();
+        if (!keepOpen) close();
+      }}
+    >
+      <span className="min-w-0 flex-1 truncate text-left">{label}</span>
+      {hint != null ? (
+        <span className={`shrink-0 ${size === "sm" ? "text-[10px]" : "text-xs"} text-gray-500`}>{hint}</span>
+      ) : null}
+      {checked ? (
+        <svg className="h-3.5 w-3.5 shrink-0 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
+        </svg>
+      ) : null}
+    </button>
+  );
+}
+
+export function MenuSeparator() {
+  return <div className="my-1 h-px bg-white/[0.06]" />;
+}
+
+export function MenuLabel({ children }: { children: ReactNode }) {
+  return (
+    <div className="px-3 py-1 text-[10px] uppercase tracking-[0.18em] text-gray-600">{children}</div>
+  );
+}
+
+/**
+ * A nested menu panel that opens beside its row on hover (or click, for
+ * touch). Flips to the left edge and shifts up when it would leave the
+ * viewport. Items inside close the entire menu tree via MenuCloseContext.
+ */
+export function SubMenu({
+  label,
+  disabled = false,
+  children,
+  panelClassName = "",
+}: {
+  label: ReactNode;
+  disabled?: boolean;
+  children: ReactNode;
+  panelClassName?: string;
+}) {
+  const size = useContext(MenuSizeContext);
+  const [open, setOpen] = useState(false);
+  const [placement, setPlacement] = useState({ flipX: false, shiftY: 0 });
+  const panelRef = useRef<HTMLDivElement>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    },
+    [],
+  );
+
+  const openNow = () => {
+    if (disabled) return;
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+    setOpen(true);
+  };
+  // Grace delay so the pointer can cross the small gap to the panel.
+  const closeSoon = () => {
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    closeTimer.current = setTimeout(() => setOpen(false), 140);
+  };
+
+  useLayoutEffect(() => {
+    if (!open) {
+      setPlacement({ flipX: false, shiftY: 0 });
+      return;
+    }
+    const panel = panelRef.current;
+    if (!panel) return;
+    const margin = 8;
+    const rect = panel.getBoundingClientRect();
+    const overflowY = rect.bottom - (window.innerHeight - margin);
+    setPlacement({
+      flipX: rect.right > window.innerWidth - margin,
+      shiftY: overflowY > 0 ? -overflowY : 0,
+    });
+  }, [open]);
+
+  return (
+    <div className="relative" onPointerEnter={openNow} onPointerLeave={closeSoon}>
+      <button
+        type="button"
+        disabled={disabled}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        className={`${itemClass(size, false, disabled)} flex items-center justify-between gap-3`}
+        // Open-only (no toggle): hover already opened it for mouse users, so a
+        // toggle would close the panel on the very click meant to open it.
+        onClick={openNow}
+      >
+        <span className="min-w-0 flex-1 truncate text-left">{label}</span>
+        <svg className="h-3 w-3 shrink-0 text-gray-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+        </svg>
+      </button>
+      {open ? (
+        <div
+          ref={panelRef}
+          className={`absolute top-0 -mt-1 z-10 ${placement.flipX ? "right-full mr-0.5" : "left-full ml-0.5"}`}
+          style={placement.shiftY !== 0 ? { transform: `translateY(${placement.shiftY}px)` } : undefined}
+        >
+          <MenuPanel className={panelClassName}>{children}</MenuPanel>
+        </div>
+      ) : null}
+    </div>
+  );
+}

src/components/menu/index.ts

@@ -0,0 +1,4 @@
+export { ContextMenu } from "./ContextMenu";
+export { MenuItem, MenuLabel, MenuPanel, MenuSeparator, SubMenu } from "./Menu";
+export type { MenuSize } from "./Menu";
+export { useDismissable } from "./useDismissable";

src/components/menu/useDismissable.ts

@@ -0,0 +1,28 @@
+import { RefObject, useEffect } from "react";
+
+/**
+ * Closes a floating element on pointer-down outside `ref` or on Escape.
+ * The single shared dismissal behavior for menus, dropdowns, and popovers.
+ */
+export function useDismissable<T extends HTMLElement>(
+  ref: RefObject<T | null>,
+  onClose: () => void,
+  enabled = true,
+) {
+  useEffect(() => {
+    if (!enabled) return;
+    const handlePointerDown = (event: PointerEvent) => {
+      const el = ref.current;
+      if (el && !el.contains(event.target as Node)) onClose();
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+    };
+    window.addEventListener("pointerdown", handlePointerDown);
+    window.addEventListener("keydown", handleKeyDown);
+    return () => {
+      window.removeEventListener("pointerdown", handlePointerDown);
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [ref, onClose, enabled]);
+}