feat: 상세 페이지 복귀 시 직전에 열었던 카드로 스크롤 복구

- sessionStorage 기반 returnFocus 유틸 추가 (rememberReturnFocus/takeReturnFocus)
- prefersReducedMotion 유틸 추가로 중복 코드 제거
- SeriesCard에 onBeforeNavigate prop 추가
- Library/Series 페이지에 rAF 기반 복귀 스크롤 적용
- StrictMode effect 재실행에서 storage 소비 방지
- ref 맵 cleanup 처리로 stale entry 제거
- Series.module.css dead CSS(.volumeCard 계열) 제거
- returnFocus/reducedMotion 단위 테스트 및 Library/Series 통합 테스트 추가

Author: aha-hyeong

web/src/components/SeriesCard.tsx

@@ -42,6 +42,7 @@ export interface SeriesCardProps {
   extensionBadgeText?: string | null;
   extensionBadgePlacement?: "thumbnail" | "meta";
   navigateTo?: string;
+  onBeforeNavigate?: () => void;
 }
 
 export function SeriesCard({
@@ -59,6 +60,7 @@ export function SeriesCard({
   extensionBadgeText = null,
   extensionBadgePlacement = "thumbnail",
   navigateTo,
+  onBeforeNavigate,
 }: SeriesCardProps) {
   const { t } = useTranslation();
   const navigate = useNavigate();
@@ -159,6 +161,8 @@ export function SeriesCard({
   const handleCardClick = (e: React.MouseEvent) => {
     if (e.defaultPrevented || window.getSelection()?.toString()) return;
 
+    onBeforeNavigate?.();
+
     if (navigateTo) {
       navigate(navigateTo);
       return;

web/src/pages/Library.test.tsx

@@ -5,6 +5,7 @@ import type { ReactNode } from "react";
 import type { Series } from "../types/series";
 import { LibraryPage } from "./Library";
 import styles from "./Library.module.css";
+import { rememberReturnFocus } from "../utils/returnFocus";
 
 const { mocks, libraryStoreState, authStoreState } = vi.hoisted(() => {
   const libraryGetMock = vi.fn();
@@ -138,6 +139,7 @@ vi.mock("../components/common/LoadingSpinner", () => ({
 }));
 
 const originalResizeObserver = globalThis.ResizeObserver;
+const originalMatchMediaDescriptor = Object.getOwnPropertyDescriptor(window, "matchMedia");
 const originalScrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(
   window.HTMLElement.prototype,
   "scrollIntoView",
@@ -272,6 +274,11 @@ describe("LibraryPage series index", () => {
   afterEach(() => {
     defaultRectSpy.mockRestore();
     globalThis.ResizeObserver = originalResizeObserver;
+    if (originalMatchMediaDescriptor) {
+      Object.defineProperty(window, "matchMedia", originalMatchMediaDescriptor);
+    } else {
+      Reflect.deleteProperty(window, "matchMedia");
+    }
     if (originalScrollIntoViewDescriptor) {
       Object.defineProperty(window.HTMLElement.prototype, "scrollIntoView", originalScrollIntoViewDescriptor);
     } else {
@@ -289,6 +296,38 @@ describe("LibraryPage series index", () => {
     }
   });
 
+  it("복귀한 라이브러리에서 직전에 열었던 시리즈 카드를 중앙에 맞춘다", async () => {
+    rememberReturnFocus("library", "library-1", "series-b");
+
+    renderLibraryPage();
+
+    await screen.findByText("Beta");
+    await waitFor(() => {
+      expect(window.HTMLElement.prototype.scrollIntoView).toHaveBeenCalledWith({
+        behavior: "smooth",
+        block: "center",
+      });
+    });
+  });
+
+  it("동작 줄이기 설정에서는 복귀 카드를 즉시 중앙에 맞춘다", async () => {
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      value: vi.fn(() => ({ matches: true })),
+    });
+    rememberReturnFocus("library", "library-1", "series-b");
+
+    renderLibraryPage();
+
+    await screen.findByText("Beta");
+    await waitFor(() => {
+      expect(window.HTMLElement.prototype.scrollIntoView).toHaveBeenCalledWith({
+        behavior: "auto",
+        block: "center",
+      });
+    });
+  });
+
   it("활성 목차 항목이 스크롤 영역 중앙에 오도록 이동한다", async () => {
     renderLibraryPage();
 

web/src/pages/Library.tsx

@@ -21,6 +21,8 @@ import {
   getSeriesDisplayName,
   getSeriesGroupKey,
 } from "../utils/librarySeries";
+import { rememberReturnFocus, takeReturnFocus } from "../utils/returnFocus";
+import { prefersReducedMotion } from "../utils/reducedMotion";
 import styles from "./Library.module.css";
 
 const POLL_INTERVAL_MS = 3000;
@@ -56,6 +58,7 @@ export function LibraryPage() {
   const loadSequenceRef = useRef(0);
   const lastFetchedIdRef = useRef<string | null>(null);
   const sectionRefs = useRef<Record<string, HTMLDivElement | null>>({});
+  const seriesCardRefs = useRef<Record<string, HTMLDivElement>>({});
   const indexButtonRefs = useRef<Record<string, HTMLButtonElement | null>>({});
   const scrollingToGroupRef = useRef<string | null>(null);
   const scrollReleaseTimeoutRef = useRef<number | null>(null);
@@ -139,6 +142,22 @@ export function LibraryPage() {
     }
   }, [id, refreshKey, loadData, fetchLibraries]);
 
+  useEffect(() => {
+    if (!id || isLoading) return;
+
+    // App의 전역 scroll-to-top effect가 끝난 다음 프레임에 복귀 스크롤을 적용한다.
+    // StrictMode의 effect 재실행에서도 취소된 프레임은 storage를 소비하지 않는다.
+    const frameId = window.requestAnimationFrame(() => {
+      const seriesId = takeReturnFocus("library", id);
+      const target = seriesId ? seriesCardRefs.current[seriesId] : null;
+      if (!target) return;
+
+      target.scrollIntoView({ behavior: prefersReducedMotion() ? "auto" : "smooth", block: "center" });
+    });
+
+    return () => window.cancelAnimationFrame(frameId);
+  }, [id, isLoading, seriesList]);
+
   // 스캔 중일 때 시리즈 목록 실시간 폴링
   // - isScanning: 이 페이지에서 직접 스캔 버튼을 눌렀을 때 (libraryAPI.scan은 동기 블로킹이므로 스토어 갱신 없음)
   // - currentLibraryScanStatus: 외부(다른 탭/스케줄러 등)에서 스캔이 시작된 경우
@@ -265,15 +284,12 @@ export function LibraryPage() {
     }
     const target = sectionRefs.current[groupKey];
     if (target) {
-      const prefersReducedMotion =
-        typeof window !== "undefined" &&
-        typeof window.matchMedia === "function" &&
-        window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-      target.scrollIntoView({ behavior: prefersReducedMotion ? "auto" : "smooth", block: "start" });
+      const reducedMotion = prefersReducedMotion();
+      target.scrollIntoView({ behavior: reducedMotion ? "auto" : "smooth", block: "start" });
       scrollReleaseTimeoutRef.current = window.setTimeout(() => {
         scrollingToGroupRef.current = null;
         scrollReleaseTimeoutRef.current = null;
-      }, prefersReducedMotion ? 0 : INDEX_SCROLL_LOCK_MS);
+      }, reducedMotion ? 0 : INDEX_SCROLL_LOCK_MS);
     } else {
       scrollingToGroupRef.current = null;
     }
@@ -668,6 +684,11 @@ export function LibraryPage() {
                         <div
                           key={series.id}
                           ref={(node) => {
+                            if (node) {
+                              seriesCardRefs.current[series.id] = node;
+                            } else {
+                              delete seriesCardRefs.current[series.id];
+                            }
                             if (index === 0) {
                               sectionRefs.current[group.key] = node;
                             }
@@ -681,6 +702,9 @@ export function LibraryPage() {
                             progressStyle="overlay"
                             showExtensionBadge
                             onStatusChange={loadData}
+                            onBeforeNavigate={() => {
+                              if (id) rememberReturnFocus("library", id, series.id);
+                            }}
                           />
                         </div>
                       );

web/src/pages/Series.module.css

@@ -24,101 +24,16 @@
   gap: 1rem;
 }
 
-.volumeCard {
+/* ref 콜백을 위한 래퍼. grid item으로 동작하며 내부 SeriesCard가 너비를 채운다. */
+.volumeCardAnchor {
   display: flex;
   flex-direction: column;
-  background: rgba(255, 255, 255, 0.03);
-  border: 1px solid rgba(255, 255, 255, 0.08);
-  border-radius: 12px;
-  overflow: hidden;
-  text-decoration: none;
-  color: inherit;
-  transition: all 0.2s;
-}
-
-.volumeCard:hover {
-  background: rgba(255, 255, 255, 0.06);
-  border-color: rgba(102, 126, 234, 0.4);
-  transform: translateY(-2px);
-}
-
-.volumeCover {
-  aspect-ratio: 5/8; /* 시리즈 카드와 동일하게 1:1.6 비율 */
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: linear-gradient(135deg, #1e3a5f 0%, #2d3748 100%);
-  color: #667eea;
-  overflow: hidden;
-  position: relative;
+  min-width: 0;
 }
 
-.volumeThumbnail {
+.volumeCardAnchor > * {
   width: 100%;
-  height: 100%;
-  object-fit: cover;
-  transition: transform 0.3s ease;
-}
-
-.volumeCard:hover .volumeThumbnail {
-  transform: scale(1.05);
-}
-
-/* 볼륨 카드 클릭 스타일 */
-.volumeCard {
-  cursor: pointer;
-}
-
-.volumeCard.loading {
-  pointer-events: none;
-  opacity: 0.7;
-}
-
-/* 재생 오버레이 */
-.volumePlayOverlay {
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: rgba(0, 0, 0, 0.4);
-  opacity: 0;
-  transition: opacity 0.2s ease;
-}
-
-.volumeCard:hover .volumePlayOverlay {
-  opacity: 1;
-}
-
-.volumePlayOverlay .loadingSpinner.small {
-  width: 24px;
-  height: 24px;
-  border-width: 2px;
-}
-
-.volumeInfo {
-  padding: 0.75rem;
-}
-
-.volumeTitle {
-  font-size: 0.9rem;
-  font-weight: 500;
-  margin: 0 0 0.25rem;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  line-clamp: 2;
-  -webkit-box-orient: vertical;
-}
-
-.volumeNumber {
-  font-size: 0.8rem;
-  color: #718096;
-  margin: 0;
+  flex: 1 1 auto;
 }
 
 /* 로딩 & 에러 */
@@ -157,17 +72,4 @@
     grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
     gap: 0.75rem;
   }
-
-  .volumeInfo {
-    padding: 0.5rem;
-  }
-
-  .volumeTitle {
-    font-size: 0.8rem;
-    margin-bottom: 0.1rem;
-  }
-
-  .volumeNumber {
-    font-size: 0.7rem;
-  }
 }