# Feature Specification: 화면 캡쳐 → 챗 첨부 (Screen Capture to Chat)

**Feature Branch**: `002-capture-to-chat`

**Created**: 2026-08-06

**Status**: Draft

**Input**: 화면 영역을 사각형으로 캡쳐해서 챗(snap) 입력창에 이미지 첨부로 넣는 기능. **v1은 캡쳐 파이프라인만** — 멀티모달 비전 분석·웹서치는 백엔드 붙는 다음 phase.

---

## 개요

작업 중 화면 어디든 전역 핫키로 사각형을 그려 그 영역을 캡쳐하면, 그 이미지가 곧바로 챗 입력창에 첨부로 붙는다. 나중에 "이미지 놓고 AI랑 얘기"하려는 건데, **이번 v1은 캡쳐해서 챗에 붙이는 데까지**만 한다. 실제 분석(비전 LLM)·웹서치는 백엔드가 준비되면 그 위에 얹는다.

**한 줄 흐름**: 새 대화 핫키(`Ctrl+Shift+9`) 또는 마지막 대화 핫키(`Ctrl+Shift+0`) → 화면에 캡쳐 오버레이 → 사각형 드래그 → 그 영역 이미지 → 선택한 챗 입력창에 이미지 첨부(썸네일+X) → (사용자가 질문 타이핑).

---

## User Scenarios & Testing *(mandatory)*

### User Story 1 - 화면 캡쳐해서 챗에 첨부 (Priority: P1)

에디터·브라우저·SAP GUI 등 아무 화면을 보다가 전역 핫키를 누르면 화면이 어둑해지며 캡쳐 모드가 뜬다. `Ctrl+Shift+9`는 새 대화, `Ctrl+Shift+0`은 마지막 기존 대화에 붙이고 기존 대화가 없으면 새 대화로 간다. 영역을 마우스로 드래그해 놓으면 앱 창이 앞으로 뜨고 선택한 대화 입력창에 캡쳐 이미지가 첨부돼 있다.

**Why this priority**: 이게 이 기능의 전부(v1). 캡쳐→첨부가 매끄럽게 되면 나중에 백엔드만 붙이면 "이미지로 AI와 대화"가 완성됨.

**Independent Test**: 핫키 → 오버레이 → 영역 드래그 → 놓기 → 챗 입력창에 그 영역 이미지가 첨부로 보이는지. 백엔드 없이 단독 검증 가능(전송·분석은 v1 밖).

**Acceptance Scenarios**:

1. **Given** 아무 창이 떠있음, **When** `Ctrl+Shift+9`, **Then** 모든 모니터를 덮는 어두운 캡쳐 오버레이가 뜬다.
2. **Given** 캡쳐 오버레이에서 영역을 드래그 중임, **When** 선택 사각형이 바뀜, **Then** 사각형 내부는 원래 화면 밝기로 보이고 바깥만 어둡게 유지된다.
3. **Given** 캡쳐 오버레이가 떠있음, **When** 영역을 드래그해 놓음, **Then** 오버레이가 닫히고 앱 창이 떠서 새 대화 화면으로 이동하며, 그 영역 이미지가 입력창에 썸네일 첨부로 붙는다.
4. **Given** 캡쳐 오버레이가 떠있음, **When** `Esc`(또는 드래그 없이 클릭만/영역 너무 작음), **Then** 아무것도 캡쳐하지 않고 오버레이만 닫힌다(부작용 없음).
5. **Given** 이미지가 첨부됨, **When** 첨부의 X를 누름, **Then** 그 첨부가 제거된다.
6. **Given** 모니터가 여러 개, **When** 보조 모니터 영역을 드래그, **Then** 그 모니터의 해당 영역이 정확히 캡쳐된다.
7. **Given** 이미 이미지가 첨부돼 있음, **When** 한 번 더 캡쳐, **Then** 새 이미지가 첨부로 추가된다(기존 것 유지).

---

### Edge Cases

- **드래그 없이 클릭만 / 너무 작은 영역**: 캡쳐 취소로 간주(오버레이만 닫힘).
- **`Esc`**: 언제든 캡쳐 취소.
- **앱 창이 숨겨진 상태에서 캡쳐**: 오버레이는 별개라 동작하고, 캡쳐 후 앱 창을 소환한다.
- **아주 큰 영역**: 이미지 용량이 커질 수 있음(전달 방식 최적화는 추후 — Assumptions 천장 참고).
- **고DPI/모니터별 배율 다름**: 좌표·크기 배율 보정이 필요할 수 있음(추후 — 천장 참고).
- **첨부를 다 지우거나 캡쳐를 취소해도** 챗은 그대로 쓸 수 있어야 한다.

---

## Requirements *(mandatory)*

### Functional Requirements

**캡쳐 트리거·오버레이**
- **FR-001**: 전역 핫키 `Ctrl+Shift+9`로 화면 캡쳐 모드를 켤 수 있어야 한다. 기존 핫키(스니펫 `Ctrl+Shift+7`, 챗 `Ctrl+Shift+8`)와 별개다.
- **FR-002**: 캡쳐 모드는 **모든 모니터를 덮는** 어두운 오버레이를 띄우고, 마우스 드래그 중 선택 사각형 내부는 원래 화면 밝기로 투명하게 보여준다.
- **FR-003**: `Esc`, 또는 유효하지 않은 선택(드래그 없이 클릭/너무 작은 영역)이면 아무것도 캡쳐하지 않고 오버레이를 닫는다.

**캡쳐·전달**
- **FR-004**: 드래그로 확정된 영역의 화면 픽셀을 이미지로 캡쳐한다.
- **FR-005**: 캡쳐 완료 시 앱 창을 앞으로 소환하고, 사용한 핫키에 맞는 대화로 이동시킨 뒤 그 이미지를 챗 입력창에 전달한다.
- **FR-005a**: `Ctrl+Shift+9`는 새 대화, `Ctrl+Shift+0`은 마지막 기존 대화를 대상으로 하며 기존 대화가 없으면 새 대화로 대체한다.

**챗 첨부(끝점)**
- **FR-006**: 전달된 이미지는 챗 입력창에 **썸네일 첨부**로 표시된다.
- **FR-007**: 각 이미지 첨부는 **X로 제거**할 수 있다.
- **FR-008**: 캡쳐를 여러 번 하면 이미지 첨부가 **누적**된다(기존 첨부 유지).
- **FR-009**: v1에서 이미지 첨부는 **표시·제거만** 한다. 메시지 전송은 기존 텍스트 전송 그대로이며, 이미지를 백엔드로 보내거나 분석하지 않는다.

### Key Entities

- **캡쳐 이미지**: 선택 영역의 화면 스냅샷 한 장. 챗 입력창에 붙는 첨부 단위(썸네일로 표시, X로 제거). v1에선 전송·분석에 쓰이지 않음(표시용).

---

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 핫키를 누른 뒤 한 번의 드래그로 이미지가 챗에 첨부되기까지 몇 초 안에 끝난다.
- **SC-002**: 첨부된 이미지가 사용자가 드래그로 고른 영역과 내용·경계가 일치한다.
- **SC-003**: 모니터가 여러 개여도 어느 모니터의 영역이든 캡쳐된다.
- **SC-004**: `Esc`·무효 선택 시 100% 취소되고 챗·클립보드 등에 아무 부작용이 없다.
- **SC-005**: 캡쳐~챗 첨부 표시까지 흐름이 끊기지 않고(오버레이 닫힘→앱 소환→첨부) 자연스럽게 이어진다.

---

## Assumptions

- **v1 범위 = 캡쳐 파이프라인만.** 이미지를 실은 메시지를 멀티모달 LLM 백엔드로 보내 **비전 분석·응답**하는 것, **웹서치** 툴은 다음 phase(백엔드 계약 나올 때). **전송-with-이미지 payload 배선도 v1 밖** — v1의 전송은 기존 텍스트 그대로.
- **캡쳐 도착지**: `Ctrl+Shift+9`는 새 대화, `Ctrl+Shift+0`은 마지막 기존 대화. 캡쳐 메시지에 대상 route를 실어 해당 Composer만 이미지를 소비한다.
- **재사용**: 기존 멀티핫키 등록, C#→JS 브릿지(SendToWeb/PostWebMessageAsJson), 팔레트 창 소환·navigate, 브릿지 이벤트 패턴(pasteTarget/bridgeNavigate 식 — 마운트 레이스 대비 모듈 보관+이벤트), Composer의 첨부 칩 UI 패턴을 최대한 얹는다. 캡쳐 오버레이 창과 캡쳐 로직만 실질 신규.
- **현재 이미지 처리와의 관계**: 지금 이미지 붙여넣기는 클립보드 이력 사이드바로만 감(챗에 "보내는 첨부" 개념 없음). 이 기능이 **챗 입력창 이미지 첨부**를 처음 도입한다.
- **ponytail 천장(추후 보완)**: ① 고DPI/모니터별 배율 좌표 보정, ② 큰 영역 캡쳐 시 base64가 커지면 임시파일/blob 전달로 최적화.

## Out of Scope (v1)

- 이미지 비전 분석·AI 판단·응답(멀티모달 백엔드).
- 웹서치.
- 캡쳐 이미지 편집(자르기·주석), 캡쳐 히스토리.