Files
joke-app/docs/07-ui-ux.md
EJClaw 65c56d3ae7 채팅: 가리기 삭제, 100줄이 찬 뒤에도 맨 아래 고정(+새 메시지 수), 이름 줄과 말풍선으로 이름·내용 구분
- 공통 ChatMessage(이름 줄 + 말풍선, 내 말은 오른쪽, 이어 말하면 이름 한 번) — 방 채팅·마피아·라이어 게임, 그림 맞히기 이름 표시
- useStickToBottom: 개수 대신 목록 내용 변화를 보고 맨 아래 유지, 위로 올려 읽는 중엔 그대로, 보내면 다시 맨 아래
- 휴대폰 채팅 버튼의 새 메시지 수도 100줄 뒤에 0이 되던 문제(마지막 본 id 기준으로)
- e2e/chat.e2e.ts: PC 대기실·게임 옆 칸·휴대폰 시트

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 03:49:03 +09:00

211 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 07. UI/UX 설계
## 1. 디자인 원칙
1. **한 화면에 할 일 하나.** 지금 눌러야 하는 버튼이 가장 크고 진하다.
2. **글자 + 아이콘.** 아이콘만 있는 버튼 금지(닫기 ✕ 제외).
3. **지금 상황을 문장으로.** 화면 맨 위에 "내 차례예요. 돌을 놓을 곳을 눌러 주세요."
4. **할 수 있는 것만 누를 수 있게.** 둘 수 있는 곳·낼 수 있는 카드만 밝게, 나머지는 흐리게. 잘못 누르면 짧게 흔들리고 이유를 한 줄로("같은 색 카드만 낼 수 있어요").
5. **실수 방지.** 큰 결정(기권, 나가기, 올인, 다이)은 확인. 단, 매 턴 확인창은 금지(느려짐) — 대신 "두 번 눌러 확정" 옵션(바둑·오목 오착 방지, 기본 켜짐: 첫 탭은 미리보기 돌, 같은 곳을 다시 탭하면 착수).
6. **기다림을 보여 준다.** 남은 시간 링, "OO님이 생각 중…", 연결 상태.
7. **가볍게.** 장식 이미지 최소, 애니메이션은 짧게(150~250ms), `prefers-reduced-motion` 존중.
8. **한눈에 들어오게 (2026-10-09, "한 화면에 정보가 너무 많다" 피드백).** 참고: NN/g 점진적 공개(자주 쓰는 것만 첫 단계, 나머지는 이름이 분명한 두 번째 단계, 최대 2단계), 토스 "한 화면 한 가지", Board Game Arena 화면 지침(판이 가운데, 정보는 묶어서, 드문 정보는 버튼·접기 뒤로), Hick의 법칙(고를 것이 많으면 묶음 탭으로 나눈다).
- 같은 정보를 두 곳에 두지 않는다(방 안에서는 사이트 메뉴를 숨기고 방 막대 한 줄만, 대기실의 규칙 전문은 [📖 규칙]으로).
- 목록 카드는 이름 + 한 줄 정보만. 설명·난이도는 들어간 다음 화면에서.
- 지금 필요 없는 것은 숨긴다(자리가 다 차면 초대 카드, 처음부터 펼친 해시값 같은 세부 정보).
- 버튼은 화면마다 진한 것 하나. 나머지는 한 줄에 묶어 덜 진하게.
- 경고·안내 문구는 한 줄로 줄인다(전문은 처음 한 번, 로그인·이름 정하기·/me에서).
## 2. 디자인 토큰
### 2.1 색 (밝은 테마 / 어두운 테마)
| 토큰 | 밝게 | 어둡게 | 용도 |
|---|---|---|---|
| `--bg` | #F7F5F0 | #16181D | 배경(따뜻한 미색) |
| `--surface` | #FFFFFF | #20232A | 카드, 패널 |
| `--text` | #1C1E21 | #F2F3F5 | 본문(명암비 15:1 이상) |
| `--text-sub` | #4A4F57 | #B8BCC4 | 보조 글(4.5:1 이상) |
| `--primary` | #2563EB | #5B8DEF | 주요 버튼(파랑) |
| `--primary-text` | #FFFFFF | #0B1020 | 주요 버튼 글자 |
| `--success` | #15803D | #4ADE80 | 준비, 성공 |
| `--warning` | #B45309 | #FBBF24 | 시간 부족, 연결 불안정 |
| `--danger` | #B91C1C | #F87171 | 기권, 나가기 |
| `--felt` | #1F6B4A | #17513A | 카드 게임 테이블 |
| `--wood` | #E3B76B | #B98C45 | 바둑판·오목판·장기판 |
| `--focus` | #F59E0B | #F59E0B | 키보드 포커스 테두리 3px |
- 색만으로 정보를 전달하지 않는다(내 차례 = 색 + 글자 + 테두리). 색약 모드: 카드 무늬에 모양 추가(♦에 빗금 등), 팀 색을 파랑/주황 조합으로.
### 2.2 글자
- 글꼴: Pretendard Variable(자체 호스팅, KS X 1001 서브셋 + 필요한 문자).
- 크기 단계(기본 "보통"): 본문 17px, 작은 글 15px(최소), 버튼 18px, 제목 22/28px. 줄 간격 1.5.
- 글자 크기 설정: 보통(100%) / 크게(120%) / 아주 크게(140%). 루트 `font-size`만 바꾸고 모든 크기는 `rem`으로.
- 굵기: 본문 500, 버튼·제목 700. 300 이하 금지.
### 2.3 크기·간격
- 터치 영역 최소 48×48px, 주요 버튼 높이 56px, 버튼 사이 간격 최소 8px.
- 간격 단위 4px(4/8/12/16/24/32).
- 모서리 둥글기 12px(버튼), 16px(카드).
- 바둑판처럼 칸이 작은 보드: 칸 크기가 32px 미만이면 "확대 보기" 버튼 + 두 손가락 확대 지원, "두 번 눌러 확정" 기본 켜짐.
## 3. 화면 틀 — PC 중심 (2026-10-04 결정)
사용자 요청으로 **PC 화면을 기준으로 설계**한다. 휴대폰·태블릿은 같은 화면을 세로로 접어서 지원한다.
### 3.1 화면 폭 구간
| 구간 | 폭 | 배치 |
|---|---|---|
| PC (기준) | 1100px 이상 (설계 기준 1280~1920) | 상단 메뉴 + 여러 칸 배치, 채팅·기보 항상 보임 |
| 태블릿 | 720~1099px | 두 칸 → 한 칸으로 접힘, 오른쪽 패널은 판 아래로 |
| 휴대폰 | 720px 미만 | 한 칸, 채팅은 버튼으로 여는 시트, 주요 버튼은 아래 고정 |
### 3.2 공통 상단 메뉴 (PC)
```
┌──────────────────────────────────────────────────────────────────────────┐
│ ● 같이 놀자 보드게임 홈 게임 목록 [🌙] 👤 닉네임 ▾ │ 64px
└──────────────────────────────────────────────────────────────────────────┘
```
- 오른쪽에 테마 버튼(🌙/☀️)을 둔다. 누를 때마다 밝은 화면 ↔ 어두운 화면으로 바뀌고, `/me`의 '화면 색' 설정과 같은 값을 쓴다('자동'이면 지금 보이는 색의 반대로). 코드로 참여는 홈의 [🔢 코드로 참여](→ `/j`)로 한다.
- 오른쪽 끝: 로그인 전에는 [로그인](→ `/login`: 큰 [디스코드로 로그인], 아래 [게스트로 시작하기] → `/login/guest`에서 계정 이름 정하기). 로그인 뒤에는 닉네임(디스코드로 가입했으면 디스코드 이름)을 보이고, 누르면 [⚙️ 설정](→ `/me`)·[🚪 로그아웃] 메뉴가 열린다. 테마 버튼 말고 글자 크기·소리 같은 설정은 `/me`에 있다.
- 내용 폭은 최대 1280px, 가운데 정렬. 게임 화면만 화면 전체 폭을 쓴다.
- 한 줄로 읽고 입력하는 화면(게임 소개 `/g/:id`, 코드로 참여 `/j`, 규칙 `/rules/:id`)은 PC에서 가운데 768px 칸만 쓴다. 휴대폰용 한 줄 배치를 1,200px로 늘리면 버튼·입력칸·글 줄이 너무 길어져 오히려 흩어져 보인다(2026-10-09). 페이지 위 [← 뒤로] 줄도 같은 폭(`TopBar width`).
- 설정(`/me`)은 PC에서 1080px 두 칸: 왼쪽 프로필·로그아웃(따라 내려옴), 오른쪽 화면 설정·기록. 휴대폰은 한 줄이고 로그아웃은 맨 아래.
### 3.3 홈 (PC)
```
┌ 상단 메뉴 ───────────────────────────────────────────────────────────────┐
│ [▶ 하던 게임으로 돌아가기] (있을 때만) │
│ [+ 방 만들기 (파란 큰 버튼)] [🔢 코드로 참여 → /j] [🤖 컴퓨터와 연습] │
├──────────────────────────────────────────────────────────────────────────┤
│ 🎮 게임 고르기 [전체] [판·주사위] [카드·패] [여럿이 파티] ← 제목과 종류 탭 한 줄 │
│ 게임 타일 격자 (PC 자동 열, 휴대폰 3열. 타일 = 아이콘·이름·"2명 · 5~15분") │
└──────────────────────────────────────────────────────────────────────────┘
```
- 첫 화면에 다 넣지 않는다. 설명 글은 버튼 아래 한 줄만, 나머지는 탭이나 버튼을 눌러 들어간다.
- 게임 한 줄 소개와 난이도는 게임 소개(`/g/:id`)에만 둔다. 휴대폰에서 26개가 세 화면 남짓에 들어온다.
- 휴대폰: [+ 방 만들기]는 한 줄 전체, [코드로 참여]·[컴퓨터와 연습]은 그 아래 나란히.
- PC·태블릿: 큰 버튼 3개는 아이콘을 왼쪽에 둔 낮은 가로 카드. 1440×900에서 게임 26개가 스크롤 없이 한 화면에 들어온다. [방 만들기]·[컴퓨터와 연습]의 게임 고르기 창은 두 줄로 나란히.
### 3.4 대기실 (PC)
```
┌──────────────────────────────────────────────┬──────────────────────┐
│ 초대 카드 한 줄(빈자리 있을 때만): 코드 | [링크 복사][초대글 복사] │ 게임 설정 │
│ 자리 카드(2명 방은 2칸, 5명 넘으면 3칸씩) │ (펼쳐서 바로 수정 — 방장) │
│ [🤖 컴퓨터 넣기] [관전으로 바꾸기] │ │
│ [▶ 게임 시작] / [준비하기] (가운데 420px) │ │
│ 채팅 │ │
└──────────────────────────────────────────────┴──────────────────────┘
```
- 사람에 관한 것(초대 → 자리 → 시작 → 채팅)은 넓은 왼쪽 칸에 위에서 아래로, 가끔 보는 게임 설정은 오른쪽 400px 칸. 오른쪽 칸에 자리 카드를 두 칸씩 넣으면 이름이 한 글자씩 꺾여서(2026-10-09) 자리를 넓은 칸으로 옮겼다.
- 태블릿·휴대폰은 한 줄: 초대 → 자리 → 게임 설정, 시작 버튼은 아래(휴대폰은 화면 아래 고정).
### 3.5 게임 화면 (PC)
```
┌ 상단 메뉴(얇게 48px: 게임명·코드·메뉴) ─────────────────────────────────────┐
│ │ 상태: 내 차례예요 ◔ 23초 │
│ │ 상대 정보 · 시계 │
│ 게임 판 (화면 높이에 맞춤) │ 내 정보 · 시계 │
│ │ [무르기][무승부][기권] │
│ │ 기보(수 목록) │
│ │ 채팅 + 반응 버튼 │
└──────────────────────────────────────────────┴──────────────────────────────┘
```
- 오른쪽 패널 폭 360px, 판은 남은 공간에서 가장 큰 정사각형.
- 카드 게임: 판 자리에 원형 테이블, 나는 항상 아래, 내 패는 판 아래쪽 넓게.
- 다른 사람 자리 줄(구십구·원카드·도블): PC·태블릿(720px 이상)에서는 사람이 많아도 옆으로 스크롤하지 않고 판 위 빈 공간에 여러 줄로 쌓는다. 한 줄에 들어가면 한 줄, 넘치면 줄마다 고르게 나눈다(9명 → 5 + 4, 8 + 1이 아님). 한 줄에 몇 칸 들어가는지는 화면 폭이 아니라 게임 칸의 실제 폭으로 정한다(`lib/seat-rows.ts`). 휴대폰은 세로 공간이 모자라서 한 줄 그대로 옆으로 밀어 본다(2026-10-11).
- PC 조작: 마우스를 올리면 미리 보기 돌(반투명), 클릭 한 번에 착수(기본값). "두 번 눌러 확정"은 터치 기기의 기본값이고 설정에서 바꿀 수 있다.
- 단축키: `Enter` 채팅 입력, `Esc` 창 닫기, 방향키+`Enter` 판 조작.
- 방 막대 버튼은 마우스 환경에서 40px(막대 52px 안에 여유), 터치 기기에서는 48px.
- 방 안(대기실·게임·결과)에서는 사이트 상단 메뉴를 숨기고 방 막대(← 홈 · 게임 이름 · 🔗 방 코드 · 📖 규칙 · ⚙️ 설정 · 🚪 나가기) 한 줄만 둔다. 판이 그만큼 커진다. 높이 계산은 CSS 변수 `--site-h`(방 안에서는 0)를 쓴다.
- 채팅의 빠른 반응(이모지·짧은 말)은 한 줄. 넘치면 옆으로 밀어 본다.
- 채팅 한 줄은 이름(작은 글씨, 사람마다 다른 색)과 말풍선(내용)을 위아래로 나눠 보여 준다. 내 말은 오른쪽, 같은 사람이 이어서 말하면 이름은 한 번만. 목록은 늘 맨 아래(새 말)에 붙어 있고, 위로 올려 읽는 중에는 움직이지 않다가 내가 보내거나 아래로 내려오면 다시 붙는다(2026-10-13). 사람별 채팅 가리기는 없앴다(사용자 요청, 2026-10-13. 필요하면 방장이 내보내기).
- 결과 창: 진한 버튼은 [🔁 한 판 더] 하나(누르면 그 방 대기실로 돌아간다, docs/06 §결과). [판 보기]·[▶ 다시 보기]는 한 줄에 나란히, [방 나가기]는 글자 버튼, 공정성 확인은 접어 둔다.
### 3.6 관리자 (PC)
왼쪽 사이드바(220px)에 메뉴, 오른쪽에 내용. 표는 PC에서 표 형태, 좁은 화면에서는 카드 목록.
## 4. 공통 컴포넌트
| 컴포넌트 | 동작 |
|---|---|
| `BigButton` | 56px, 종류 primary/secondary/danger, 로딩 표시, 두 번 눌림 방지 |
| `CodeDisplay` | `123 456` 큰 글씨 + 복사 |
| `CopyButton` | 복사 후 1.5초 "복사했어요 ✓", 실패하면 텍스트 선택 상태로 보여 줌 |
| `ShareButton` | `navigator.share` 있으면 공유 시트, 없으면 링크 복사 |
| `QrModal` | QR 크게 + 코드 |
| `CodeInput` | 6칸, 숫자 키패드, 붙여넣기 감지, 다 채우면 자동 제출 |
| `Seat` | 프로필, 이름, 방장/준비/연결 상태 |
| `TurnTimer` | 원형 링, 10초 남으면 주황 + 똑딱 소리(설정), 5초 남으면 빨강 + 진동 |
| `Toast` | 위에서 내려오는 짧은 알림(3초), 스크린리더 `aria-live` |
| `ConfirmSheet` | 아래에서 올라오는 확인창(큰 버튼 두 개) |
| `Card` | 트럼프/화투/게임 카드 공용 SVG, 크기 3단계 |
| `RulesSheet` | 게임 중 규칙 요약(그림), 현재 상황 도움말 |
| `ConnectionBanner` | "다시 연결하는 중…" 띠, 인터넷이 끊기면 방 밖에서도 "인터넷 연결이 없어요" 띠 |
## 5. 초보자 도움
- 처음 하는 게임이면(기기 기준) 시작할 때 "30초 규칙 요약" 카드 3장(그림 위주), [건너뛰기].
- 구현: 게임이 진행 중인 화면을 이 기기에서 처음 볼 때(시작하거나 진행 중인 방에 들어올 때, 관전 포함) 카드 3장을 띄운다. [다음]·[건너뛰기], 마지막 장은 [시작하기]. 본 게임은 `localStorage` `bg:qs:<게임id>`에 기억한다. 규칙 페이지의 [30초 요약 보기], 게임 중 [?]의 [30초 요약 다시 보기]로 언제든 다시 본다.
- 그림은 이미지 파일 없이 기존 카드 컴포넌트(트럼프·화투·마작패 등)나 작은 인라인 SVG·이모지로 그리고, 그림마다 대체 글(`alt`)을 단다.
- 게임 중 [?] → 지금 상황에서 할 수 있는 것 설명("지금은 낼 카드를 고르는 차례예요. 밝게 보이는 카드만 낼 수 있어요").
- 구현: 차례 안내 줄 오른쪽의 [? 도움] → "지금 할 수 있는 것" 시트. 게임마다 지금 화면(view)만 보고 문장을 만든다(숨은 정보는 쓰지 않음). 시트에서 [전체 규칙 보기](그 게임의 규칙 설명을 펼침)와 [30초 요약 다시 보기]로 이어진다. 관전자에게는 "구경하고 있어요"를 먼저 알려 준다.
- 내용은 게임별 `apps/web/src/games/<id>/quick.tsx`(카드 3장)·`help.ts`(`helpNow`)에 있고 게임 화면 묶음과 함께 필요할 때만 내려받는다.
- 족보·점수가 복잡한 게임(섯다, 포커, 고스톱, 마작)은 내 패 옆에 현재 족보 이름 표시("지금: 7끗", "투페어"), 족보표 버튼.
- 구현 확인: 섯다·포커는 "지금: <족보>"(방 설정 힌트가 켜졌을 때)와 족보표, 고스톱은 내 점수 내역(광·열끗·띠·피 진행, 점수 항목, 고 횟수)과 족보표, 마작은 대기패·버리면 텐파이 표시(초보 모드)와 역 목록. [?] 설명에도 지금 족보·점수·대기패를 함께 보여 준다.
- 힌트 옵션(방 설정): 끄면 하이라이트만, 켜면 추천 수 표시(초보 방).
## 6. 소리·진동
- 짧은 효과음만(돌 놓기, 카드 넘기기, 내 차례 알림, 시간 경고, 승리). 합쳐서 100KB 이하, 처음 사용자 조작 후에만 재생(브라우저 정책).
- 내 차례가 되었는데 탭이 백그라운드면: 탭 제목 깜빡임("● 내 차례예요") + 소리(설정).
- 진동(`navigator.vibrate`): 내 차례, 시간 5초 남음.
## 7. 접근성
- 키보드만으로 모든 조작 가능(보드는 방향키로 칸 이동 + Enter). 포커스 테두리 항상 보이게.
- 스크린리더: 보드 칸에 `aria-label`("가로 8, 세로 8, 빈칸"), 상대의 수를 `aria-live`로 읽어 줌("상대가 H8에 두었어요").
- 명암비 기준 WCAG 2.2 AA 이상, 큰 글자 모드에서 화면이 깨지지 않는지 테스트.
- 시스템 글자 크기·확대 존중(`user-scalable` 막지 않음).
## 8. 성능 예산
| 항목 | 예산 |
|---|---|
| 첫 화면 JS | 150KB gzip 이하 (React + 라우터 + 홈) |
| 게임 화면 하나 | 추가 80KB gzip 이하(lazy) |
| 글꼴 | 서브셋 woff2 2개(500/700) 합 400KB 이하, `font-display: swap` |
| 이미지 | 게임 카드 썸네일은 SVG 또는 WebP 10KB 이하 |
| 외부 요청 | 0개(디스코드 아바타 제외) |
## 9. 문구 규칙
- 존댓말 해요체, 짧게. "~하시겠습니까?" 대신 "~할까요?".
- 어려운 말 금지: "테이블" → "방", "세션" → 쓰지 않음, "로비" → "홈".
- 오류 문구는 원인 + 할 일: "방을 찾을 수 없어요. 코드를 다시 확인해 주세요."
## 10. 화면 목록과 상태 (구현 체크용)
- 홈(로그인 전/후, 진행 중 게임 있음)
- 닉네임 입력(게스트 시작 / 링크 입장)
- 코드 입력
- 게임 상세
- 대기실(방장/참가자/관전자, 인원 부족/가득 참)
- 게임 화면(내 차례/남의 차례/연결 끊김/자리 비움/일시 정지)
- 결과 화면(승/패/무승부, 한 판 더 → 대기실, ▶ 다시 보기)
- 계정(게스트/디스코드, 내 게임 기록 목록 + [다시 보기])
- 다시 보기(`/replay/:gamePk`: 판은 읽기 전용, 처음/이전/재생·멈춤/다음/끝 + 슬라이더. PC는 오른쪽 칸, 폰은 아래 고정 막대. 못 보는 게임은 안내 문구, docs/09 §8)
- 오류(방 없음, 방 가득 참, 서버 업데이트, 오프라인)
## 11. PWA (홈 화면 추가·오프라인 안내)
- 매니페스트 `/manifest.webmanifest`: 이름 "같이 놀자 보드게임", 짧은 이름 "같이 놀자", `lang: ko`, 시작 `/`, `display: standalone`, 테마·배경 `#F7F5F0`(`--bg`). 아이콘은 "게임천국" 느낌의 게임패드 + 천사 고리 + 반짝이(보라→분홍→주황 배경). `public/icons/`: 192·512(favicon 그대로, 둥근 모서리), 512 maskable(가득 채움, 그림은 가운데 안전 영역 안), apple-touch-icon 180. favicon.svg와 PNG 모두 `bun scripts/pwa-icons.ts`가 한 디자인에서 만든다(Chrome으로 그림).
- 서비스 워커: 손으로 쓴 `apps/web/sw.js`를 빌드 때 Vite 플러그인이 빌드 ID(파일 이름 해시 기준)를 넣어 `dist/sw.js`로 낸다. 배포 빌드에서만 등록한다(개발 서버에서는 등록 안 함).
| 요청 | 처리 |
|---|---|
| 페이지 이동(navigate) | 네트워크 먼저, 저장하지 않음. 네트워크 오류면 `/offline.html` |
| `/assets/*` (해시 파일) | 캐시 먼저(`bg-assets-v1`, 200개까지, 오래된 것부터 지움). 200 응답이고 HTML이 아닐 때만 저장(없는 파일은 서버가 index.html을 돌려주므로) |
| `/api/*`(관리자 API 포함), `/ws`, `/healthz`, `/internal/*`, 다른 출처, GET 아닌 요청 | 손대지 않음(저장 안 함) |
- 캐시: `bg-shell-<빌드ID>`(오프라인 안내 페이지 하나)와 `bg-assets-v1`. 새 워커는 바로 활성화(`skipWaiting` + `clients.claim`)하고, 활성화할 때 이 둘이 아닌 `bg-*` 캐시를 지운다. index.html은 어디에도 저장하지 않으므로 온라인이면 새 배포가 바로 보인다. 해시 파일은 내용이 바뀌지 않아 배포 뒤에도 남겨 둔다. 워커의 저장 방식을 바꾸면 `bg-assets-v1`의 숫자를 올린다.
- 오프라인 안내 페이지: 다른 파일 없이 혼자 그려지는 HTML(인라인 스타일, 밝게/어둡게). 스크립트는 없다(CSP가 인라인 스크립트를 막음). [다시 시도]는 같은 주소를 다시 연다. 자동 새로고침(meta refresh)은 접근성 검사(axe) 위반이라 쓰지 않는다.
- 앱 안: 인터넷이 끊기면 `ConnectionBanner`가 위쪽 띠로 알린다(방 안에서는 기존 재연결 문구).
- 홈 화면에 추가: 홈 아래쪽 카드. `beforeinstallprompt`를 잡아 [추가하기] 버튼을 보이고, iOS(이 이벤트 없음)는 "공유 버튼 → [홈 화면에 추가]" 안내만. 이미 앱으로 열었거나(standalone) [닫기]를 누르면(기기에 기억) 안 보인다.
- 서버: `/sw.js`·`/manifest.webmanifest`·`/offline.html`은 index.html과 같이 `no-cache`, manifest는 `application/manifest+json`(Bun 기본). CSP `default-src 'self'`가 워커·매니페스트를 허용해 따로 넣은 것은 없다.
- 확인: `apps/web/src/sw.test.ts`(캐시 규칙), `bun e2e/pwa.e2e.ts`(매니페스트·아이콘, 워커 활성화, 오프라인 띠·안내 페이지, 다시 온라인, 설치 카드, 업데이트 팝업).
### 11.1 업데이트 알림 (2026-10-11)
- 사이트가 업데이트되면 열려 있는 페이지 위쪽 가운데에 카드가 뜬다: "업데이트 내용이 있습니다." [지금 새로고침하기] [✕]. ✕를 누르면 닫히고, 그다음 업데이트가 나올 때까지 다시 뜨지 않는다(새로고침하면 새 빌드라 안 뜸). 모든 화면에 보인다(`UpdateBanner`, `apps/web/src/lib/update.ts`).
- 빌드 ID: 빌드할 때 Vite 플러그인(`buildId`, vite.config.ts)이 만든 파일 이름들의 해시 12자리를 index.html의 `<meta name="bg-build">`에 넣는다. 스크립트·스타일이 하나라도 바뀌면 달라지고, 서버 코드만 바뀐 배포에는 뜨지 않는다.
- 서버는 시작할 때 dist/index.html에서 그 값을 읽어(`webBuildId`) `GET /api/version`(`no-store`)과 소켓 `welcome.build`로 알린다. 페이지는 5분마다, 탭이 다시 보일 때, 소켓이 (다시) 연결될 때 비교한다. 배포로 서버가 다시 켜지면 소켓이 다시 연결되면서 바로 뜬다.
- 프로토콜 번호가 다를 때(예전 방 화면의 "새 버전이 있어요")도 같은 카드를 쓴다. 개발 서버에는 빌드 ID가 없어 뜨지 않는다.