viberoom-web/docs/session_brief.md

Session Brief

Last Updated: 2026-03-15

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

고정 규칙 (요약)

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

현재 우선순위

1. Paused Session Takeover Flow
2. Core Loop Alignment browser audit
3. Weekly Review recovery 집계 연결
4. Premium Ambience

최근 세션 상태

• /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는 factual summary에서 Weekly Review 1차 구조로 올라갔다.
  • hero snapshot, start quality, recovery quality, completion quality, carry forward 구조를 사용한다.
  • 기존 focus-summary 응답은 review view model로 변환해서 쓴다.
  • recovery는 API 집계가 아직 없을 때 limited state로 표시한다.
• /app에서 /stats로 들어가는 primary path 1차가 생겼다.
  • current session이 없고 최근 7일 데이터가 충분하면 hero 아래에 weekly review teaser가 보인다.
  • teaser는 /stats로 이동시키되, main start CTA보다 낮은 강조로 유지한다.
• /app Resume 상태에서도 weekly review entry가 보이게 정리했다.
  • review primary entry가 active session 상태에서 사라지지 않도록, resume card 안에 조용한 secondary review link를 추가했다.
• /stats 마지막 CTA의 /app return handoff가 연결됐다.
  • carry-forward CTA는 /app?review=weekly&carryHint=...로 돌아온다.
  • /app은 review-aware return hint를 먼저 보여주되, goal은 사용자가 직접 입력하게 유지한다.
• Weekly Review Entry Flow의 Pro personalized handoff까지 연결됐다.
  • Pro에서는 /stats carry-forward에 추천 ritual을 함께 보여준다.
  • /stats 마지막 CTA와 /app teaser / return hint가 더 구체적인 handoff 톤으로 바뀐다.
• /space complete 이후 secondary review teaser까지 연결됐다.
  • goal complete로 setup 상태로 돌아왔을 때만 setup drawer 아래에 작은 review teaser가 보인다.
  • full review 강제 이동 없이 /stats를 여는 secondary entry로만 동작한다.
  • 방금 끝낸 흐름을 반영한다고 과장하지 않는 카피로 정리했다.
  • 다음 구현은 weekly review의 실제 recovery 집계 연결이다.
• paused session 재진입 정책을 별도 source of truth로 고정했다.
  • running focus -> /space
  • running break -> /space
  • paused focus -> /app
  • /app의 explicit continue 이후 /space에서는 다시 start를 묻지 않고 자동 resume해야 한다.
  • paused session 위의 새 시작은 direct가 아니라 takeover flow로만 허용한다.
• Paused Session Re-entry의 Session Routing Contract를 1차 구현했다.
  • /app은 running session을 감지하면 hero를 보여주지 않고 즉시 /space로 보낸다.
  • /space는 paused session 상태에서 explicit handoff intent 없이 직접 열리면 /app으로 되돌린다.
  • /app의 이어서 들어가기는 다음 slice를 위해 /space?resume=continue handoff를 사용한다.
• Paused Resume Gate와 Auto-Resume Handoff를 구현했다.
  • paused 상태의 /app은 이어서 몰입하기, 한 조각 다시 잡기, quiet 주간 review 보기를 함께 보여준다.
  • 이어서 몰입하기는 /space?resume=continue로 들어간 뒤 자동 resume된다.
  • 한 조각 다시 잡기는 /space?resume=refocus로 들어간 뒤 refocus tray를 바로 연다.
• Product Alignment Audit 운영을 시작했다.
  • 16_product_alignment_audit_plan.md를 기준 문서로 추가했다.
  • 17_product_alignment_findings.md에 core loop의 P1/P2 mismatch를 수집하기 시작했다.
  • 다음 라운드는 route-flow matrix와 state contract matrix를 만드는 static audit이다.
• 유료화 포지셔닝을 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