viberoom-web/docs/session_brief.md

Session Brief

Last Updated: 2026-03-14

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

고정 규칙 (요약)

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

현재 우선순위

1. /space Refocus + Return 브라우저 QA
2. Weekly Review 상세 기획
3. Premium Ambience System 방향 정리

최근 세션 상태

• /space Refocus System 첫 slice를 구현했다.
  • pause 직후 바로 편집 시트가 아니라 작은 recovery prompt를 먼저 띄운다.
  • 여기서 한 조각 다시 잡기를 누르면 refocus tray로 들어간다.
  • paused 상태의 refocus는 적용하고 이어가기로 바로 resume까지 연결된다.
  • microStep 완료 후에는 checklist가 아니라 다음 한 조각이 있나요? prompt로만 이어진다.
  • recovery UI는 paused / refocus / next-beat / complete 중 하나만 열리도록 단일 overlay 상태로 묶였다.
• /space goal complete 종료 경로를 복구했다.
  • 여기까지 끝내기로 현재 목표를 다음 목표 입력 없이도 정상 완료 처리할 수 있다.
  • pause prompt의 이대로 이어가기는 단순 닫기가 아니라 실제 resume으로 연결된다.
• /space goal complete / next beat를 덜 form스럽게 정리했다.
  • goal complete는 처음부터 input을 요구하지 않고, 선택지를 먼저 보여준 뒤 다음 목표 이어가기를 선택했을 때만 입력이 열린다.
  • next-beat prompt는 현재 goal 문맥을 함께 보여줘서 사용자가 어떤 목표를 이어가는지 잃지 않게 했다.
• /space recovery tray material과 선택 위계를 같은 패밀리로 맞추기 시작했다.
  • pause / next-beat / complete tray가 공통 dark-glass shell을 공유한다.
  • inline 링크 중심이던 선택지를 quiet option row 구조로 바꿔, checklist보다 recovery decision처럼 읽히게 정리했다.
  • Goal Complete는 여기까지 끝내기 / 잠깐 쉬기 / 다음 목표 이어가기를 같은 tray 안의 선택 행으로 제시한다.
  • Refocus는 같은 shell 안에서 field / action 톤을 통일해 다른 tray와 같은 제품군처럼 보이게 맞추는 중이다.
• /space Away / Return Recovery를 구현했다.
  • visibilitychange, pagehide, sleep/wake gap 기반 감지를 추가했다.
  • 짧은 탭 전환에는 반응하지 않도록 hidden threshold를 둬 오탐을 줄였다.
  • 돌아왔을 때 focus가 계속 running이면 Return tray가 이어서 하기 / 한 조각 다시 잡기를 제안한다.
  • 자리를 비운 사이 focus가 끝나 break phase가 되었으면 standard break 대신 Return tray가 먼저 뜬다.
  • 이 경우 지금부터 쉬기 / 다음 목표 이어가기 / 한 조각 다시 잡기 중 하나를 고를 수 있다.
  • 다음 목표 이어가기는 goal complete next view로 바로 연결된다.
• pause tray의 visual polish를 진행했다.
  • tray 폭과 max-height를 늘려 한국어 제목/설명 잘림을 줄였다.
  • title/body line-height와 spacing을 다시 잡아 임시 패널 느낌을 줄였다.
  • option row의 radius, padding, chevron 정렬을 보정해 더 차분한 recovery panel처럼 읽히게 했다.
• Pause / Break / Return의 감정 톤 분리를 시작했다.
  • Return(break)은 focus 복귀 tray와 같은 재질을 쓰지 않고, 더 부드러운 emerald tint release tone으로 분리했다.
  • Goal Complete의 잠깐 쉬기 선택도 같은 release tone으로 연결했다.
  • timer HUD도 break phase에서는 더 가벼운 emerald 계열 material로 바뀌어 pause/focus와 다르게 읽히도록 정리 중이다.
• Pause / Break / Return의 카피와 CTA 위계를 2차로 분리했다.
  • Pause는 멈춘 이유보다 다시 시작할 한 줄에 집중하는 recovery tone으로 다시 썼다.
  • Return(focus)는 이어가기, Return(break)는 지금부터 쉬기 / 다음 블록 이어가기 중심으로 문구를 분리했다.
  • Goal Complete는 마무리 / 쉬기 / 이어가기의 선택 tray가 먼저 보이고, 다음 블록 입력은 이후 단계에서만 열리도록 더 선명해졌다.
• Pause / Break / Return의 motion polish 1차를 반영했다.
  • Pause는 빠르게 다시 붙잡는 recovery reveal로,
  • Return(focus)는 재진입에 맞는 짧은 settle motion으로,
  • Return(break)와 Goal Complete는 더 느슨한 release/closure reveal로 분리했다.
• /space 목표 카드를 collapsed / expanded 구조로 재설계했다.
  • idle에서는 goal 1줄만 남는 얇은 glass rail로 줄였다.
  • microStep과 이번 목표 완료는 expanded 상태에서만 드러난다.
  • recovery tray가 열리면 base card는 자동으로 collapsed 상태를 유지한다.
  • expanded rail은 outside click으로 접히지만, decision tray는 outside click으로 닫히지 않는다.
  • rail 클릭은 펼침/접힘만 담당하고, 수정은 expanded 상태의 수정 액션으로만 진입한다.
• /app을 single-goal commitment gate로 다시 줄였다.
  • 2-step ritual setup을 제거했다.
  • current session이 있으면 Resume UI만 보여주고, /space로 이어가기만 제안한다.
  • current session이 없으면 goal 1개 + optional microStep 1개 + 바로 시작만 남긴다.
  • scene/sound/timer는 기본 ritual로 시작하고 /space에서 바꾸게 둔다.
  • manage/list 성격의 affordance는 메인 진입 경로에서 제거했다.
• /space는 execution-only surface로 정리됐다.
  • setup drawer에서 Daily Plan / Ritual Library 섹션을 제거했다.
  • goal, scene, sound, timer만 확인하고 focus HUD로 진입한다.
• 목표 완료 후 다음 목표 즉시 실행 흐름이 backend contract와 연결됐다.
  • GoalCompleteSheet confirm 시 advance-goal endpoint를 사용한다.
  • 현재 세션 완료, linked plan item 완료, 새 current item 생성, 다음 세션 시작을 한 번에 처리한다.
  • 실패 시 시트를 닫지 않고 그대로 재시도할 수 있다.
• /stats는 해석형 review 화면이 아니라 factual summary로 정리됐다.
  • today / last7Days / trend만 유지한다.
  • started/completed/carried over/focus minutes 중심으로 표시한다.
• 유료화 포지셔닝을 Calm Session OS로 재정의했다.
  • Free는 기본 집중 시작, Pro는 더 잘 이어가기라는 메시지로 정리했다.
  • old Scene Packs / Sound Packs / Profiles 중심 카피를 Daily plan / Rituals / Weekly review 구조로 교체했다.
• /app은 더 이상 /space redirect가 아니다.
  • FocusDashboardWidget에서 goal only start와 plan-linked start를 모두 처리한다.
  • Free에서 두 번째 블록 추가 시도는 manage sheet 안에서 paywall로 진입한다.
• 플랜 tier를 route 간에 공유하도록 정리했다.
  • usePlanTier localStorage store를 추가해 /app, /space, /stats가 같은 Free/Pro 상태를 본다.
• Session OS mock 도메인을 추가했다.
  • FocusPlanItem, SessionTemplate, SessionOutcome, WeeklyReview, AsyncCheckIn 모델과 mock 데이터를 entities/session에 추가했다.
• /space stage 배경을 overscan으로 보정했다.
  • background layer를 -inset-8로 확장해 pan 애니메이션 중 가장자리 빈틈 노출을 줄였다.
• Gemini가 진행한 대형 파일 분리를 다시 점검했다.
  • SpaceWorkspaceWidget, SpaceToolsDockWidget, admin/page.tsx, shared/i18n/ko.ts 모두 500줄 기준 안으로 정리된 상태를 재확인했다.
  • 현재 주요 최대 파일은 AdminDashboardView.tsx 482줄, useSpaceWorkspaceSelection.ts 440줄 수준이다.
• /admin 분리 과정의 placeholder 회귀를 복구했다.
  • 로그인 후 Dashboard is under construction만 보이던 상태를 제거했다.
  • 실제 scene/sound 업로드 폼을 AdminDashboardView로 복원해 AdminConsoleWidget은 조합만 담당하도록 되돌렸다.
• 인증 전역 저장소 위치를 정리했다.
  • src/store/useAuthStore.ts를 제거했다.
  • 인증 상태 저장소를 entities/auth/model/useAuthStore.ts로 이동해 feature가 루트 store를 직접 참조하지 않도록 정리했다.
• /space 배경 asset 해석을 보강했다.
  • media manifest scene key를 alias-aware 하게 정규화해 green-forest와 forest를 같은 scene asset으로 읽는다.
  • scene/sound asset에 source(fallback|remote) 메타를 추가해 remote asset 사용 여부를 코드에서 바로 식별할 수 있다.
  • remote manifest load 실패와 scene fallback 사용 시 /space에서 진단 로그를 남기도록 보강했다.
• Focus 피드백 채널을 상단 중앙 1곳으로 통합했다.
  • HUD 내부 status line 제거
  • Notes/Goal/잠금 피드백이 동일 위치 토스트로 표시
• 기본 기능 잠금을 해소했다.
  • Time 90/20을 Free로 개방
  • 기본 Sound 잠금 제거
• Pro 잠금 구조를 Session OS 중심으로 재구성했다.
  • Daily Focus Plan / Rituals / Weekly Review 요약 카드 추가
  • 기본 Scene/Time/Sound는 잠금 없이 선택 가능
• Paywall 시트는 잠금 카드 클릭에서만 열리도록 바꿨다.
  • Plan Pill(FREE) 클릭은 즉시 결제창 오픈 대신 상태 안내만 노출
  • Paywall 카피를 3개 가치 포인트 + 2개 CTA로 간결화
• Focus-First 구조로 전환했다.
  • Quick Controls의 모드 전환 토글(기본/몰입)을 제거했다.
  • HUD는 외부 모드 상태 없이 기본 몰입 톤으로 유지한다.
  • 컨트롤 노출은 패널 열림 상태에서만 보이도록 단순화했다.
• Quick Controls 패널 내부에 표시 정책 옵션을 추가했다.
  • 옵션: 컨트롤 자동 숨김
  • ON 상태에서 Control Center가 8초 무입력이면 자동 닫힘 처리
• /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, goal, override(sound/timer)
  • 복원 우선순위: 쿼리 파라미터 > 저장 상태 > Scene 추천
• /space 진입 시 Resume CTA를 추가했다.
  • 저장된 목표가 있고 쿼리 오버라이드가 없으면 지난 한 조각 이어서를 1회 노출
  • 이어서 시작은 즉시 Focus 진입, 새로 시작은 목표를 비운 새 세션으로 전환
• 세션 복구용 문서/템플릿/스크립트가 준비되어 있다.
• 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를 기준으로 실행한다.

리스크

• Session OS 데이터는 아직 mock 기반이므로 실제 저장/동기화 API 없이도 화면이 그럴듯하게만 보일 수 있다.
• empty state에서 CTA는 유지하지만 실제 시작 전에 입력 포커스가 먼저 필요하므로, 첫 진입 사용성은 브라우저 확인이 필요하다.
• current item이 아닌 preview row 선택은 ad-hoc start로 처리되므로, 큐 재정렬을 기대하는 사용자와 정신 모델 차이가 날 수 있다.
• /space paywall 전환 진입점은 /app / /stats 중심이라 execution 화면만 본 사용자에게는 업그레이드 맥락이 약할 수 있다.
• stage background overscan으로 좁은 화면에서 배경 crop 체감이 조금 더 커질 수 있다.
• remote manifest 실패 시 원인 진단은 가능하지만, 사용자용 복구 CTA는 아직 없다.
• /admin 업로드 콘솔은 타입/구조상 복구됐지만 실제 브라우저 업로드 스모크는 아직 필요하다.
• alias 목록에 없는 legacy scene id가 다시 들어오면 scene fallback 문제가 재발할 수 있다.
• 네트워크 제한 환경에서는 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