viberoom-web/docs/session_brief.md

# Session Brief

Last Updated: 2026-03-05

세션 시작 시 항상 읽는 초소형 스냅샷 문서.

## 고정 규칙 (요약)

- 구현 범위는 UI 목업 + 더미 데이터 + 토스트로 제한한다.
- `page.tsx`는 조합만 담당한다.
- 비즈니스 로직은 `features/entities`로 이동한다.
- 파일이 500줄 이상이면 분리한다.
- 커밋은 주제별 1커밋, 한국어 Conventional Commit으로 작성한다.

## 현재 우선순위

1. Scene 추천 매핑 품질 점검(공간별 사운드/타이머 추천값 보정)
2. override 정책(수동 선택 후 Scene 변경 시 유지)의 사용자 기대치 검증
3. 터치 환경 도구 레일 발견성(미니 핸들 UX) 보완 여부 결정

## 최근 세션 상태

- Quick Controls 모드 전환 UI를 헤더에서 제거하고 패널 바디 첫 섹션으로 이동했다.
  - 헤더는 Plan + 닫기만 유지
  - 바디에는 `기본/몰입` segmented pill + 설명 1줄을 배치
  - 모드 상태는 Focus HUD 톤과 연동되도록 workspace 경로에 연결했다.
- `/space`에 Scene 추천 자동 적용 규칙을 도입했다.
  - Room 데이터에 `recommendedSoundPresetId`, `recommendedTimerPresetId`를 추가했다.
  - 초기 진입/Scene 변경 시 override가 없는 항목만 추천값으로 자동 반영된다.
- `/space`에 override 상태(`sound`, `timer`)를 추가했다.
  - 사용자가 직접 고른 사운드/타이머는 Scene 변경에도 자동 덮어쓰지 않는다.
  - `추천으로 되돌리기(더미)` 액션으로 override 초기화 + 추천값 즉시 복원이 가능하다.
- Control Center를 Scene/Time 중심으로 단순화했다.
  - Sound/Preset Packs 섹션 제거
  - 추천 정보 1줄 + `추천으로 되돌리기`만 유지
- 우하단 Sound Quick 선택 경로를 `onQuickSoundSelect`로 분리해 override.sound 규칙을 명시했다.
- `/space` 선택 상태 로컬 저장/복원을 추가했다.
  - 저장: `sceneId`, `timerPresetId`, `soundPresetId`, `override(sound/timer)`
  - 복원 우선순위: 쿼리 파라미터 > 저장 상태 > Scene 추천
- 세션 복구용 문서/템플릿/스크립트가 준비되어 있다.
- `workFlow.md`는 토큰 절약 모드를 사용한다.
- `/space` 하단 사운드 바를 제거하고 오른쪽 `🎧 Sound` 시트로 이동했다.
- `/space` 헤더 프레임을 축소하고 HUD를 하단 safe-area 기준으로 더 밀착시켰다.
- 상단 우측 나가기 액션을 클릭형에서 1초 롱프레스형으로 전환했다.
  - 0.05초에 진행률 20%까지 빠르게 상승하는 가속 진행을 적용했다.
  - 몰입 OFF는 bar, 몰입 ON은 ring 형태로 진행률을 표시한다.
- 롱프레스 bar 진행 표시를 CSS keyframes 기반으로 교체해 즉시 가시성을 개선했다.
  - 완료 후 fill이 0으로 역방향 축소되는 현상을 제거했다.
  - fill 끝단은 직선 형태로 정리했다.
- 30초 복귀 액션을 감성 라운지 톤으로 리브랜딩했다.
  - 버튼 라벨을 `숨 고르기 30초`로 변경했다.
  - HUD 모드 라벨은 진입 시 `BREATHE`로 표시된다.
  - 클릭 시 저자극 안내 문구를 HUD 미니 안내 + 토스트로 노출한다.
- `/landing` 이후 앱 플로우 배경을 밝은 톤으로 조정했다.
  - `/app` 허브/룸 카드 오버레이를 완화해 배경 노출을 늘렸다.
  - `/space` 오버레이/비네팅 강도를 낮춰 전체 명도를 올렸다.
  - `/stats`, `/settings`는 라이트 팔레트 기반 패널로 전환했다.
- `/app` 룸 카드 hydration 에러를 수정했다.
  - `RoomPreviewCard`의 중첩 `<button>` 구조를 제거했다.
  - 카드 내부 칩을 비인터랙티브 태그로 바꿔 콘솔 에러를 해소했다.
- `/app` 배경과 카드 가시성을 함께 보정했다.
  - 허브 배경에 blur + 밝기 보정 + 저채도 필터를 적용해 배경 복잡도를 낮췄다.
  - 전역 오버레이를 밝은 워시 중심으로 조정하고 그레인 강도를 낮췄다.
  - `RoomPreviewCard` 내부에 반투명 정보 패널을 추가해 텍스트 대비를 안정화했다.
- 커스텀 입장 모달을 허브 톤과 맞춰 밝게 정리했다.
  - `공간/사운드/타이머` 탭 콘텐츠 영역을 고정 높이로 바꿔 전환 시 모달 크기 변화가 없게 했다.
  - 탭/옵션/입력 필드 스타일을 밝은 팔레트 기준으로 통일했다.
- `/app`의 핵심 카드 2개를 라이트 카드 톤으로 전환했다.
  - `지금, 몰입을 시작해요`와 `오늘의 공간` 컨테이너를 흰 표면 + 어두운 텍스트로 정리했다.
  - 허브 배경 블러를 강화해 카드 외곽은 가상 공간 배경이 부드럽게 보이도록 조정했다.
- `/app` 오늘의 공간 카드를 룸별 단색 팔레트로 전환했다.
  - `entities/room`에 `hubColor`를 추가해 카드별 고유 단색을 분리했다.
  - 허브 배경도 선택 룸의 같은 색으로 동기화해 톤 연결성을 높였다.
- `/app` 오늘의 공간 카드에 실제 사진(임시 외부 URL)을 연결했다.
  - `entities/room`에 `cardPhotoUrl`, `googleImageSearchUrl`, `managedCardPhotoUrl`를 추가했다.
  - Google 이미지 검색 링크를 룸별로 보관하고, 추후 자가 이미지 경로로 전환 가능한 fallback 구조를 적용했다.
- `/app` 허브 배경을 선택 카드 사진 기반 블러로 조정했다.
  - 첫 진입 시 첫 카드가 선택된 상태를 명시해 배경/선택 테두리 기준을 고정했다.
- `/app` 헤더와 프로필 트리거를 정리했다.
  - 로고 왼쪽 `V` 원형 배지를 제거했다.
  - 사용자 이름 왼쪽에 멤버십 등급 배지(`PRO`/`NORMAL`/`TEAM`)를 추가했다.
- `/app` 헤더 톤을 시작 카드와 동일한 라이트 표면으로 재정렬했다.
  - 헤더 배경/보더/텍스트를 `지금, 몰입을 시작해요` 카드 톤(`bg-white/78`, `text-brand-dark`)과 맞췄다.
  - 멤버십 등급 배지는 프로필 트리거 내부가 아닌, 프로필 왼쪽의 독립 뷰로 분리했다.
- `/app` 멤버십 등급 배지의 프리미엄 표현을 강화했다.
  - 배지 텍스트를 `text-xs` 이상으로 상향하고 칩 높이/패딩을 키워 가독성과 존재감을 높였다.
  - `PRO MEMBER` 기준으로 조용한 그라데이션 표면/내부 하이라이트/미세 그림자를 적용해 저자극 프리미엄 톤을 맞췄다.
  - `NORMAL`/`TEAM`도 등급별 표면 톤과 점 마커를 분리해 위계를 명확히 했다.
- `/app` 멤버십 배지를 Quiet Premium 톤으로 2차 정리했다.
  - 등급 칩 높이를 `h-9`로 올리고 최소폭/자간을 통일해 배지가 독립 오브젝트처럼 보이도록 보정했다.
  - `PRO`는 모바일에서 짧은 라벨, 데스크톱에서 `PRO MEMBER`를 노출해 밀집을 줄이면서 위계를 유지했다.
  - 헤더 우측에서 배지와 프로필 사이 간격을 넓혀( `gap-3` ) 프리미엄 배지의 존재감을 안정화했다.
- 공간 카드 높이를 고정해 사진 사이즈를 통일하고, 배경 전환 시 resize처럼 보이던 애니메이션 느낌을 완화했다.
- 몰입 모드 ON 시 상단 룸 블록 숨김, 레일 미니화, HUD 저대비, 비네팅 강화가 적용된다.
- 이후 작업은 `docs/work.md`를 기준으로 실행한다.

## 리스크

- 네트워크 제한 환경에서는 `npm run build` 시 Google Fonts fetch 실패 가능
- localStorage 저장 포맷 변경 시 이전 세션 데이터와의 호환성 이슈가 생길 수 있음
- Scene 추천값이 사용자 선호와 어긋나면 자동 추천 체감 품질이 낮을 수 있음
- 터치 환경에서 레일 미니 상태가 발견성 낮을 수 있어 UX 보완이 필요할 수 있음
- safe-area가 작은 기기에서는 HUD 하단 간격 체감이 과도할 수 있어 미세 조정이 필요할 수 있음
- 롱프레스 인터랙션은 신규 사용자에게 즉시 인지되지 않을 수 있어 보조 카피가 필요할 수 있음
- bar/ring 진행 구현 방식이 달라 향후 진행 규칙 변경 시 회귀 확인이 필요함
- HUD 안내 문구와 목표 문구가 교체 노출되므로 정보 우선순위 점검이 필요함
- 밝은 배경 구간에서 white 텍스트 대비가 낮아질 수 있어 기기별 시인성 점검이 필요함
- 배경 blur/filter 적용으로 저사양 환경에서 렌더링 비용이 소폭 증가할 수 있음
- 모달 고정 높이로 인해 작은 화면에서는 탭 본문 내부 스크롤 사용 빈도가 늘 수 있음
- 룸 프리뷰 카드의 이미지 기반 다크 톤과 라이트 컨테이너 사이 미세한 톤 차이가 남을 수 있음
- 단색 팔레트가 일부 디스플레이에서 유사하게 보일 수 있어 기기별 색 분리도 점검이 필요함
- 외부 이미지 URL 의존으로 소스 만료/속도 이슈 가능성이 있어 자가 호스팅 전환이 필요함
- 배경 블러 강도 증가로 저사양 환경에서 GPU 부담이 늘 수 있어 체감 성능 확인이 필요함
- 밝은 배경 사진과 라이트 헤더가 겹칠 때 상단 요소 경계 인지가 약해질 수 있어 점검 필요함
- 등급 칩 최소폭 증가로 초소형 화면에서 헤더 가로 여유가 줄어들 수 있어 실기기 점검이 필요함

## 상세 원문 위치

- 장문 상세 상태: `docs/90_current_state.md`
- 구조 규칙 상세: `docs/02_arch_fsd_rules.md`
- 커밋 규칙 상세: `docs/06_commit_convention.md`