fix: make clear recent history actually persist

Prevent the player and session restore from re-writing history after a clear by wiping last session and cached audio, and suppressing history writes until the user plays something new.

Author: bgwastu

src/components/HistoryList.tsx

@@ -18,7 +18,6 @@ import { useAppContext } from "@/context/AppContext";
 import type { HistoryItem } from "@/interfaces";
 import { historyItemSourceUrl, resolveCachedMedia } from "@/lib/playFromCache";
 import { timeAgo } from "@/utils";
-import { clearMediaCache } from "@/utils/cache";
 
 interface HistoryListProps {
   onPlay?: () => void;
@@ -31,7 +30,7 @@ export default function HistoryList({
   maxHeight,
   showClear = true,
 }: HistoryListProps) {
-  const { history, setHistory, openPlayer } = useAppContext();
+  const { history, clearHistory, openPlayer } = useAppContext();
   const [confirmOpen, setConfirmOpen] = useState(false);
   const theme = useMantineTheme();
 
@@ -97,9 +96,7 @@ export default function HistoryList({
           <Button
             color="red"
             onClick={() => {
-              void clearMediaCache();
-              setHistory([]);
-              setConfirmOpen(false);
+              void clearHistory().finally(() => setConfirmOpen(false));
             }}
           >
             Clear all

src/components/Player.tsx

@@ -149,7 +149,13 @@ export function Player({
 }) {
   const theme = useMantineTheme();
   const isMobile = useMediaQuery("(max-width: 1024px)");
-  const { media: contextMedia, setMedia, setHistory, setTheme } = useAppContext();
+  const {
+    media: contextMedia,
+    setMedia,
+    setHistory,
+    setTheme,
+    isHistoryWriteAllowed,
+  } = useAppContext();
   const isMini = mode === "mini";
 
   // Phase management: extracting while URL is being resolved, then playing
@@ -350,6 +356,7 @@ export function Player({
 
   // Persist history once media is playable; refresh cover/title when extraction completes
   useEffect(() => {
+    if (!isHistoryWriteAllowed()) return;
     if (!media?.sourceUrl || !media.fileUrl) return;
     // Local uploads are session-only — never write them to history
     if (media.sourceUrl.startsWith("local:")) return;
@@ -390,7 +397,7 @@ export function Player({
       next[existingIdx] = nextItem;
       return next;
     });
-  }, [media, setHistory]);
+  }, [media, setHistory, isHistoryWriteAllowed]);
 
   // Use sourceUrl from media state
   const sourceUrl = media?.sourceUrl ?? url ?? "";
@@ -880,7 +887,7 @@ export function Player({
           advancedStretch,
           lyrics: lyricsSettings,
         });
-        if (!sourceUrl.startsWith("local:")) {
+        if (!sourceUrl.startsWith("local:") && isHistoryWriteAllowed()) {
           patchLastSession(sourceUrl, { positionSeconds: currentTime });
         }
       }
@@ -913,17 +920,19 @@ export function Player({
     customSemitones,
     lyricsSettings,
     currentTime,
+    isHistoryWriteAllowed,
   ]);
 
   // Throttled progress persistence while the track is active
   useEffect(() => {
+    if (!isHistoryWriteAllowed()) return;
     if (!sourceUrl || sourceUrl.startsWith("local:") || !stateLoaded) return;
     if (!Number.isFinite(currentTime) || currentTime < 0) return;
     const id = window.setTimeout(() => {
       patchLastSession(sourceUrl, { positionSeconds: currentTime });
     }, 1500);
     return () => window.clearTimeout(id);
-  }, [sourceUrl, currentTime, stateLoaded]);
+  }, [sourceUrl, currentTime, stateLoaded, isHistoryWriteAllowed]);
 
   // Modal controls
   const [modalOpened, { open: openModal, close: closeModal }] = useDisclosure(false);

src/context/AppContext.tsx

@@ -15,6 +15,7 @@ import { clearLastSession, loadLastSession, saveLastSession } from "@/lib/lastSe
 import { mediaFromLocalCache } from "@/lib/playFromCache";
 import { playerPathForMedia, softReplaceUrl } from "@/lib/playerNavigation";
 import { appTheme } from "@/lib/theme";
+import { clearMediaCache } from "@/utils/cache";
 
 const HISTORY_STORAGE_KEY = "moonlit-history";
 
@@ -42,6 +43,8 @@ export interface OpenPlayerOptions {
   autoPlay?: boolean;
   /** Resume playback head (seconds). Used by session restore. */
   resumePosition?: number;
+  /** When false, do not resume history writes (session restore). Default true. */
+  recordHistory?: boolean;
 }
 
 interface AppContextValue {
@@ -64,7 +67,8 @@ interface AppContextValue {
   // History state (persisted to localStorage)
   history: HistoryItem[];
   setHistory: React.Dispatch<React.SetStateAction<HistoryItem[]>>;
-  clearHistory: () => void;
+  clearHistory: () => Promise<void>;
+  isHistoryWriteAllowed: () => boolean;
 
   // Theme state
   theme: MantineThemeOverride;
@@ -88,6 +92,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
   const mediaRef = useRef(media);
   const playerUrlRef = useRef(playerUrl);
   const restoredRef = useRef(false);
+  const skipHistoryWritesRef = useRef(false);
 
   useEffect(() => {
     mediaRef.current = media;
@@ -136,15 +141,28 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
     [],
   );
 
-  const clearHistory = useCallback(() => {
+  const clearHistory = useCallback(async () => {
+    skipHistoryWritesRef.current = true;
     setHistoryState([]);
+    try {
+      localStorage.removeItem(HISTORY_STORAGE_KEY);
+    } catch (e) {
+      console.error("Failed to clear history:", e);
+    }
+    clearLastSession();
+    await clearMediaCache();
   }, []);
 
+  const isHistoryWriteAllowed = useCallback(() => !skipHistoryWritesRef.current, []);
+
   const setMedia = useCallback((next: Media | null) => {
     setMediaState(next);
   }, []);
 
   const openPlayer = useCallback((options: OpenPlayerOptions = {}) => {
+    if (options.recordHistory !== false) {
+      skipHistoryWritesRef.current = false;
+    }
     const expand = options.expand !== false;
     setPlayerAutoPlay(options.autoPlay !== false);
     setPlayerResumeAt(
@@ -244,6 +262,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
             autoPlay: false,
             syncUrl: true,
             resumePosition: session.positionSeconds ?? 0,
+            recordHistory: false,
           });
           return;
         }
@@ -254,6 +273,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
           autoPlay: false,
           syncUrl: true,
           resumePosition: session.positionSeconds ?? 0,
+          recordHistory: false,
         });
       })();
     }, 0);
@@ -263,6 +283,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
   // Persist last session while a remote track is active
   useEffect(() => {
     if (!isHydrated) return;
+    if (skipHistoryWritesRef.current) return;
     if (playerMode === "hidden") return;
     const sourceUrl = playerUrl || media?.sourceUrl;
     if (!sourceUrl) return;
@@ -296,6 +317,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
         history,
         setHistory,
         clearHistory,
+        isHistoryWriteAllowed,
         theme,
         setTheme,
       }}