Developing Web UI

웹 UI 개발

프론트엔드 구조

packages/web/src/
├── pages/           # 페이지 컴포넌트
├── components/
│   ├── card/        # ContentRenderer, ContentPreview, DiffViewer, SplitPreviewCard
│   ├── help/        # HelpTooltip
│   ├── layout/      # Layout, Sidebar
│   ├── ui/          # shadcn/ui 스타일 (button, card, popover, select, table,
│   │                #   dialog, model-badge, bottom-sheet, compact-selector)
│   ├── validation/  # ValidationPanel
│   ├── ErrorFallback.tsx
│   ├── RouteError.tsx
│   └── SyncStatusBadge.tsx
├── hooks/           # TanStack Query 훅 + 유틸 훅
│   ├── useCards.ts         # useCards, useCardDetail
│   ├── useBackups.ts       # useBackups, useRollback (정규 위치)
│   ├── useDecks.ts         # useDecks, useDeckStats
│   ├── useDifficultCards.ts # useDifficultCards
│   ├── useHistory.ts       # useHistoryList, useHistoryDetail, useHistorySyncHealth
│   ├── useMediaQuery.ts    # useMediaQuery, useIsMobile
│   ├── usePrompts.ts       # usePromptVersions, usePromptVersion, useActivePrompt,
│   │                       #   useSystemPrompt, useActivatePrompt, useSaveSystemPrompt,
│   │                       #   useExperiments, useExperiment, useCreateExperiment,
│   │                       #   useCompleteExperiment
│   ├── useSplit.ts         # useLLMModels, useSplitPreview, useSplitApply,
│   │                       #   useSplitReject, getCachedSplitPreview
│   └── useValidationCache.ts
└── lib/
    ├── api.ts               # API 클라이언트 (fetch wrapper)
    ├── query-keys.ts        # TanStack Query 키 팩토리
    ├── markdown-renderer.ts # Anki 카드 렌더링 파이프라인
    ├── constants.ts         # 상수 정의
    ├── sync-status.ts       # 동기화 상태 타입/유틸
    ├── view-transition.ts   # View Transition API 래퍼
    ├── helpContent.ts       # HelpTooltip 콘텐츠 정의
    └── utils.ts             # cn() 등 공용 유틸

훅 위치 참조

useBackups, useRollback는 useBackups.ts에만 정의. useCards.ts는 useCards, useCardDetail만 포함.

페이지 목록

핵심 컴포넌트

ContentRenderer & ContentPreview

Markdown + Cloze 렌더링. markdown-it 기반 (lib/markdown-renderer.ts).

처리 순서 (renderAnkiContent 함수 기준):

1. preprocessAnkiHtml: HTML 엔티티 + <br> -> \n 변환
2. processCloze: Cloze 구문 -> <span class="cloze"> 변환
3. processNidLinks: nid 링크 -> <a class="nid-link"> 변환 (마크다운 파싱 전에 처리)
4. md.render(): markdown-it 렌더링 (컨테이너 플러그인 포함, highlight.js 코드 하이라이팅)
5. processImages: 이미지 경로를 API 프록시(/api/media/)로 변환

KaTeX 단계는 없다. rehype-katex가 package.json에 레거시 의존성으로 남아 있지만, 실제 렌더링 파이프라인에서 KaTeX 처리를 수행하지 않는다. Anki 템플릿 측에서 KaTeX가 이미 HTML로 렌더링된 상태로 들어오므로 html: true 옵션으로 통과시킨다.

ContentPreview는 토글 없이 렌더링만 수행하는 컴팩트 버전.

DiffViewer & SplitPreviewCard

둘 다 components/card/DiffViewer.tsx에 위치 (단독 파일 아님).

• DiffViewer: 분할 전후 라인 기반 diff 비교 (메인 카드 변경 + 서브 카드 목록)
• SplitPreviewCard: 분할 미리보기 개별 카드 (ContentRenderer + Raw/Rendered 토글 + 메인/번호 배지)

SplitWorkspace (3단 레이아웃)

• 왼쪽 (3/12): 분할 후보 목록 + Cloze 수 뱃지
• 중앙 (5/12): 원본 카드 (ContentRenderer + 검증 패널)
• 오른쪽 (4/12): 분할 미리보기 + LLM 모델 선택 (ModelBadge) + 적용/반려 버튼

ValidationPanel

4종 검증 결과 표시. validating-cards 스킬 참조.

토스트 알림 (sonner)

sonner 라이브러리의 Toaster 컴포넌트를 App.tsx에 전역 마운트. 페이지에서 import { toast } from "sonner"로 직접 호출.

toast.success("분할이 적용되었습니다");
toast.error(`분석 실패: ${message}`);
toast.warning("히스토리 세션이 없습니다");
toast.info("분할 결과가 반려되었습니다");

설정: position="bottom-right", richColors, duration={4000}.

TanStack Query 패턴

// 훅 구조
export function useCards(deckName: string, options: CardOptions) {
  return useQuery({
    queryKey: queryKeys.cards.byDeck(deckName, options),
    queryFn: () => api.cards.list(deckName, options),
    enabled: !!deckName,
    staleTime: 30 * 1000,
  });
}

// 캐시 무효화 (분할 적용 후)
queryClient.invalidateQueries({ queryKey: queryKeys.cards.all });
queryClient.invalidateQueries({ queryKey: queryKeys.backups.all });

주요 staleTime 값

CSS 주의사항

• .container 충돌: Tailwind의 .container 유틸리티와 충돌 -> .callout로 변경
• flex 스크롤: 부모에 min-h-0 + overflow-hidden 필수
• 타이포 토큰 사용: 페이지 헤더/본문은 typo-h1, typo-h2, typo-body 등 디자인 시스템 유틸 우선 사용
• 모바일 Drawer 전환: Sidebar는 translate-x + backdrop opacity 전환으로 열림/닫힘 애니메이션 보장

자주 발생하는 문제

• <br> 태그 미처리: preprocessAnkiHtml에서 <br> -> \n 변환
• 스크롤 안 됨: flex 컨테이너에 min-h-0 누락
• 분할 미리보기 캐싱: React Query setQueryData로 카드별 독립 캐시
• Shadcn 파일 casing 충돌: Button.tsx/button.tsx 혼용 시 TS 중복 포함 오류 -> 소문자 import 경로 통일

테스트 패턴

• 컴포넌트 테스트: packages/web/tests/components/*.test.tsx (Vitest + Testing Library)
• E2E 스모크: packages/web/tests/e2e/smoke.spec.ts (Playwright)
• 실행 명령:
  • bun run --cwd packages/web test
  • bun run --cwd packages/web test:e2e (packages/web/playwright.config.ts의 webServer가 bun run preview를 자동 실행하므로 별도 dev 서버 기동 불필요)

상세 참조

• references/pages.md -- 7개 페이지 역할 상세
• references/components.md -- ContentRenderer, DiffViewer, ValidationPanel 상세
• references/query-patterns.md -- TanStack Query 훅, 캐싱 전략
• references/troubleshooting.md -- CSS 충돌, 렌더링 문제