# v0.2.8 — 인앱 파일 탐색기 + 세션 윈도우 하드닝

릴리즈 일자: 2026-05-12
이전 버전: v0.2.7

## 요약 (TL;DR)

프로젝트 상세 화면에 **Files 탭**이 새로 생겼다. OS 파일 매니저를 열지 않고도 폴더 트리를 탐색하고 텍스트/이미지/PDF/오디오/비디오를 인라인으로 미리볼 수 있다. 또한 세션 윈도우의 워크스페이스 전환·페이스트·드래그 흐름 전반에 걸친 결함을 정리했다 — 최소화 칩이 프로젝트 이동 후에도 사라지지 않고, 돌아왔을 때 윈도우가 정상 복원되며, 화면 버퍼가 깨지던 PTY 사이즈 레이스와 한 번의 페이스트로 이미지가 두 번 들어가던 버그가 모두 해결됐다.

## 주요 변경

### 인앱 파일 탐색기 (Files 탭)

프로젝트 상세 페이지의 **Files** 탭에서 폴더 트리를 직접 탐색할 수 있다. **읽기 전용** — 수정/스테이징은 기존 Git 탭이 계속 담당한다.

- 좌측 lazy 트리 + 우측 인라인 미리보기. 가운데 분할바는 드래그로 조절 가능하고 너비는 영속화된다.
- 텍스트 파일은 최대 2MB까지 인라인으로 표시 (NUL byte 검출 시 바이너리로 자동 폴백).
- 이미지 / PDF / 오디오 / 비디오 (최대 50MB)는 `<img>` / `<iframe>` / `<audio>` / `<video>`로 직접 렌더링.
- 알 수 없는 바이너리는 다운로드 링크.
- `.git` / `node_modules` / `.worktrees` / `.DS_Store`는 기본 hide. `Show hidden files` 토글로 dot-prefix 파일 노출. `Copy path` 단축.
- 좁은 뷰포트에서도 가로 스크롤 없이 접근하도록 탭 바 맨 앞에 배치.
- 서버는 `path.resolve()` 후 root prefix 검사로 traversal을 차단해 프로젝트 폴더 바깥은 절대 노출되지 않는다.

### 크로스-프로젝트 최소화 도크 트레이

세션 윈도우의 최소화 칩이 이제 **앱 레벨 트레이**에 표시된다 — 다른 프로젝트로 이동해도 칩이 사라지지 않고, 거기서 칩을 클릭하면 원래 프로젝트로 자동 이동하면서 윈도우가 복원된다. 같은 프로젝트 안에서의 복원/닫기는 기존의 confirm 프롬프트 + 안전 종료 경로를 그대로 거친다.

### 워크스페이스 전환 시 세션 윈도우 복원

프로젝트 A → B → A 왕복 후 윈도우가 복원되지 않거나, 복원된 직후 윈도우를 리사이즈하면 화면 버퍼가 깨지던 두 결함을 모두 수정했다.

- 마운트 직후 첫 렌더에서 동기적으로 localStorage를 읽어 들이므로, 영속화된 상태가 누락 없이 그대로 복원된다.
- 복원된 running 세션은 portal/container가 안정될 때까지 기다렸다가 실제 뷰포트 dims로 PTY에 사이즈를 통보한다. 이전에는 transient 0×0 측정으로 PTY를 SIGWINCH 해 직후 진짜 사이즈로 또 재조정되면서 버퍼가 망가졌다.
- 중단된 드래그/리사이즈로 0×0 또는 오프스크린에 묶인 윈도우 상태도 자동 클램프해 invisible-but-clickable 형태로 페이지 클릭을 가로채는 사고를 막는다.

### 이미지 페이스트: 중복 입력 + 동시 페이스트 레이스 수정

한 번의 Ctrl/Cmd+V로 이미지가 `[Image #1]`에 이어 `[Image #2]`로 두 번 들어가거나, 두 개의 페이스트가 거의 동시에 들어왔을 때 두 번째 이미지의 비트맵이 첫 번째 자리에 새던 버그를 수정했다.

- 키보드 핸들러가 제스처를 클레임해 같은 Ctrl/Cmd+V에 대해 발화하는 컨테이너 `paste` 이벤트가 작업을 중복 수행하지 않는다.
- 서버가 OS 클립보드 쓰기와 PTY로의 ESC+v 주입을 같은 트랜잭션에서 처리한다. 두 페이스트가 동시에 들어와도 비트맵이 섞이지 않는다.

### 드래그/리사이즈/스플리터/탭 드래그 어보트 처리

윈도우 드래그, 8방향 리사이즈, 스플리터 드래그, 탭 드래그가 alt-tab / 탭 hide / Escape로 중단되면 글로벌 listener와 `pointer-events: none` wrapper 상태가 잔존해 페이지가 클릭을 잃는 사고가 있었다. 모든 제스처에 blur / Escape / visibilitychange abort 핸들러를 추가해 깔끔히 정리한다.

### 숨겨진 탭의 포커스 탈취 방지

VS Code 스타일 탭 그룹에서 숨겨진(`display: none`) 세션 pane이 마운트 시점에 form input의 포커스를 빼앗아 타이핑이 끊기던 문제를 수정했다. 이제 visible 탭만 mount-time 포커스를 가져가고, body가 아닌 어떤 입력 요소에 포커스가 있으면 절대 가로채지 않는다.

## 설치 / 업데이트

```bash
npm i -g clitrigger@0.2.8
```

데스크탑 앱: GitHub Release 자산의 `.exe` / `.dmg` / `.AppImage` 사용.

## 전체 커밋 목록

- 16e72dc WIP(docs): scope update-docs skill away from CLAUDE.md by default
- ea31c5c WIP(docs): sync CLAUDE.md + changelog for files tab and session hardening
- 2c930d7 feat(ui): move Files tab to front of project tab bar
- ca064d7 feat(session): app-level minimized tray + workspace-switch fixes
- 64f95bf fix(session): close duplicate image paste and concurrent paste race
- a7649bd WIP(session): harden drag/resize abort paths and gate terminal autofocus
- 5709a84 feat: add in-app project file explorer tab
- fd4731b Include badges for license and npm package status

## 관련 문서

- [상세 changelog](../changelog/) — 날짜별 기술 결정 기록
