React ChessSandbox는 서버가 렌더링한 공통 앱 셸의 chess-ui-root에 마운트됨. 모바일에는 공통 상단 메뉴바와 드로어가 표시되고, 폭 1500px(chessWide) 이상 PC에서는 헤더 아래 Chess 3열 작업 영역만 viewport 높이를 사용해 페이지 전체 스크롤 없이 영역별 목록 스크롤을 유지함.
API 요청은 /api/chess/* 상대 경로를 사용하며 개발 환경에서는 Vite proxy가 API 18002로 전달함.
Vite는 Chess WebSocket URL이나 실시간 상태를 주입하지 않음. 실시간 이벤트는 Chess API의 HTTP NDJSON 스트림으로 수신함.
공통 jb-panel, jb-button, jb-chip, jb-chess-* 자산을 사용함. 버튼은 shared-ui의 공통 Button·ToggleButton과 compact 수정자를 사용함. 새 대국·대국 생성·무승부 제안·거절은 흰색, 기권·무승부 수락은 노랑, 연동 해제는 빨강, 보조 조작은 검정이며 대국 설정의 상대·색·시간 선택은 ToggleButton의 choice 변형을 사용함. Chess 전용 버튼 CSS는 두지 않음.
Chess는 공통 PC/모바일 전환 기준(1440px)의 예외이며 전용 단계 chessSplit(900px)·chessWide(1500px)를 breakpoints.json에서 관리함. 이 값은 Chess 전용 CSS에서만 참조하고 다른 화면은 사용하지 않음. 공통 앱 셸 헤더만 공통 기준(1440px)에 따라 전환됨.
폭 900px(chessSplit) 미만의 단일 열에서는 jb-main의 공통 모바일 본문 폭과 --jb-mobile-content-gutter를 사용함. Chess 셸은 카드 바깥 좌우 여백을 중복 적용하지 않음.
좌측 계정·대국 목록, 중앙 보드, 우측 수별 분석의 3열 책임을 섞지 않음.
긴 대국·분석 목록은 각 패널 내부에서 스크롤하고 데스크톱 화면 전체는 고정 작업 영역으로 유지함.
사용자 노출 문장형 문구는 소스에 한국어로 직접 작성하며 하십시오체와 문장 끝 마침표를 사용함.
Tabulator는 공통 운영 그리드에 사용할 수 있으나 Chess 복기 목록과 수별 분석은 React 카드 목록으로 렌더링함.
복기 API 오류는 오류 본문을 표시함. 실시간 스트림 오류는 연결 상태와 함께 표시하고 재연결·진행 중 대국 복구 흐름으로 처리함.
좌측 상단은 연결 계정 상태, 연동 또는 연동 해제, PGN 업로드, 새로고침, 업로드 정책 안내를 고정 표시함. 별도의 완료·실시간 모드 선택 버튼은 없음.
미연동 상태에서는 GET /api/chess/oauth/connect로 이동하는 계정 연동 버튼을 표시함.
연동 상태에서는 DELETE /api/chess/account를 호출하는 연동 해제 버튼과 board:play 권한을 다시 승인받는 권한 재연동 링크를 표시함. 새로고침은 shared-ui의 IconRefresh 아이콘 버튼으로 표시하고 접근성 이름은 새로고침이며, 완료·진행 중 대국 목록을 각각 다시 조회함.
PGN 업로드는 .pgn 파일을 POST /api/chess/games/upload-pgn의 pgn_file로 전송함. 성공하면 목록을 새로고침하고 업로드 게임을 선택함.
계정 영역 아래의 단일 내부 스크롤 목록은 진행 중 대국을 위에, 완료 대국을 아래에 구분해 표시함. 진행 중 표준 대국은 Lichess nowPlaying 순서로 최대 20건, 완료 대국은 등록 시각 최신순 첫 20건을 표시함.
진행 중 대국 행은 상대 또는 AI 단계, 진행 상태, 차례, 속도, 내 색상, 남은 시간을 표시함. 완료 대국 행은 상대, 결과, 종료 시각, 내 색상 또는 관전 상태, 엔진 분석 상태를 표시함.
선택한 완료 대국의 목록 카드 안에 AI 복기 상태·저장된 코칭 수/전체 대상 수·진행률·오류·수동 요청 버튼을 표시함. 관전 대국과 실시간 대국에는 AI 복기 조작을 표시하지 않음.
대국 행을 선택하면 해당 게임 ID의 실시간 보드 또는 저장된 완료 복기를 표시함. 페이지 초기 진입에서는 진행 중 대국이 있으면 첫 대국을 선택하고, 없으면 첫 완료 대국을 선택함. 진행 중 대국이 새로 시작되어도 사용자의 기존 선택을 임의로 바꾸지 않음.
목록 상단 새 대국은 현재 선택 대국과 무관하게 대국 설정 모달을 열 수 있음. 매칭 대기 중에는 새 대국 버튼을 비활성화함. 종료 후 완료 대국 수집이 아직 끝나지 않은 선택 대국은 임시 카드로 표시함.
ChessSandbox가 선택 대국의 게임 ID·모드, 보드 표시 방식·방향을 소유하고, 복기 상태와 실시간 스트림 상태를 표시 방식과 분리함.
중앙 보드의 일반/터미널 토글은 react-chessboard와 TerminalBoard에 같은 현재 포지션을 전달함. 마지막 선택은 localStorage의 junkbox.chess.board-view에 저장함.
보드 상단 공통 컨트롤 패널의 첫 줄은 표시 방식과 판 회전, 복기 모드의 둘째 줄은 실제 진행·최선 수·PV 재생·이전 수·다음 수를 같은 폭의 타일로 배치함. AI 복기 버튼과 상태는 보드 상단에 두지 않음.
보드 렌더러만 교체하며 복기 ply, 수순 탐색, 실시간 연결, 남은 시간은 유지함. 판 회전은 두 렌더러에 공통 적용함.
두 렌더러는 같은 정사각 보드 viewport를 사용하며, 수순·평가 등 보드 하단 메타의 위치와 영역은 렌더러에 따라 바뀌지 않음.
터미널 보드는 어두운 8×8 문자 격자, 양옆의 행 번호, 백 대문자·흑 소문자와 서로 다른 색, 마지막 착수·선택 칸 강조를 제공함. 위아래 열 문자 행과 격자 상하 구분선은 표시하지 않음. 실시간 모드에서는 칸 클릭 이동을 지원하고 복기 모드에서는 기존 ply 탐색을 사용함. 터미널 내부에는 포지션·상태 헤더와 UCI 입력·전송 폼이 없으며 문자 격자를 정사각 보드 viewport의 중앙에 배치함.
선택된 게임의 내 색상을 board orientation으로 사용함. 관전 대국은 백 방향을 사용함.
기본 실제 진행 모드는 선택한 ply의 fen_after를 보드 position으로 사용함.
최선 수 비교 모드는 선택한 ply의 fen_before를 사용하고, 초록 화살표로 엔진 최선 UCI 수, 빨강 화살표로 실제 UCI 수를 함께 표시함.
PV 재생 모드는 fen_before에서 principal variation을 단계별 적용하며 이전·다음 버튼으로 보드 position을 변경함.
비교·PV 안내 영역은 보드 아래에 둠. 데스크톱에서는 모드 전환 시 보드 위치가 변하지 않도록 영역을 확보하고, 모바일에서는 내용이 없을 때 빈 영역을 숨김.
복기에서는 보드 착수를 허용하지 않으며 수별 분석 선택과 이전·다음 수 버튼으로 ply를 변경함.
보드 하단은 수순, 실제 평가, 평가 손실, 현재 차례·체크 상태를 요약함. PC/FHD 기준 4칸 한 줄, 모바일 기준 2열 grid를 사용함.
Lichess 원본 대국 링크는 game id를 이용해 생성함.
목록 카드의 AI 복기 분석은 요청 접수 중에 공통 LoadingModal을 표시함. 접수 후에는 백그라운드 진행 단계와 확정된 코칭 수를 상태 API로 조회함. 중간 오류가 나면 저장된 결과와 실패 문구를 함께 표시하고 버튼을 다시 활성화함. 자동 재요청은 하지 않으며 화면을 나가도 시작된 서버 실행은 계속됨.
useLiveGame은 보드 렌더러와 별도로 이벤트·게임 NDJSON 스트림, 진행 중 대국, 착수 전송, 재연결 상태를 관리함. 빈 keepalive 줄을 허용하고 연결이 끊어지면 다시 연결해 서버 상태를 기준으로 동기화함.
페이지 새로고침 시 진행 중 대국 목록을 조회해 복구함. 선택한 진행 중 대국 하나에만 게임 스트림을 연결하고 다른 대국을 선택하면 해당 스트림으로 교체함. 계정 이벤트 스트림은 대국 선택과 독립적으로 유지되며, 보드 표시 방식 전환은 스트림 연결을 재생성하지 않음. 새 대국을 누르면 기존 대국 선택을 해제하고 게임 스트림을 닫음.
진행 중 목록은 초기 조회, 명시적 새로고침, 페이지 재표시, 대국 시작·종료 이벤트, 이벤트 스트림 재연결 시 갱신함. 선택한 대국의 착수·시계는 게임 스트림 상태로 목록에도 반영함. 선택하지 않은 대국의 차례·남은 시간은 마지막 목록 조회 시점의 값임.
새 대국 또는 실시간 화면의 대국 설정 액션은 모달을 열고 공개 매칭 또는 Lichess AI 대국을 선택하게 함. 공개 매칭은 레이팅 여부와 지원 시간 규칙을 선택함. AI 대국은 1~8단계 슬라이더, 내 진영, 시간 규칙을 선택함. 진행 중인 다른 대국이 있어도 새 대국 생성 요청을 보낼 수 있음.
매칭 대기 취소, 연결 상태·오류, 양측 남은 시간, 무승부 제안·응답, 기권, 대국 종료 상태를 표시함. 종료 후 저장된 완료 대국 복기로 진입할 수 있음.
대국 제목과 양측 시계의 선수 표기는 name이 있으면 이를 사용하고, 없으면 aiLevel에 따른 Lichess AI 레벨 N, id, 상대 순서로 대체함. 내 진영을 확인하기 전의 대국 제목은 실시간 대국으로 표시함.
실시간 착수는 현재 차례와 합법 수를 확인한 뒤 UCI로 전송함. 프로모션은 승격 기물 선택을 제공함.
Game: game id, 내 색상, 상대명, 결과, 시작·종료 시각, engine_status를 가짐. 관전 대국은 result='OBSERVED'임.
Detail: 게임 메타, PGN, engine_status, Move[]를 가짐.
Move: ply, turn number, 색상, SAN, UCI, fen_before, fen_after, 내 수 여부, 엔진 평가·최선 수·PV, 코칭 필드를 가짐.
복기 타입과 별도로 실시간 게임의 시작 정보, 게임 상태, 수순, 차례, 양측 시계, 연결 상태를 관리함. Lichess 게임 스트림이 실시간 포지션과 종료 상태의 최종 기준임.
LivePlayer.name은 선택 필드이며 AI 상대의 이름이 게임 스트림에 없을 수 있음. aiLevel과 id를 화면 표기 대체값으로 사용함.
PlayingGame은 Lichess 진행 중 대국의 gameId, 내 색상, 표준 variant, 상대명·AI 단계, 속도, 내 차례 여부, 내 남은 초를 사용함. UI는 GET /api/chess/live/playing의 nowPlaying 중 표준 대국만 목록에 표시함.
Chess 자체 엔진·코칭·표시 상태와 연결·매칭 상태는 대문자 코드로 판정하고 표시함. Lichess 실시간 스트림의 started와 진영·속도·variant는 외부 계약 표기를 유지함. 수 판정의 대문자 severity는 한국어 라벨에 매핑하고 CSS 판정 클래스에는 소문자로 변환해 적용함.