CODE_ASSISTANT/specs/002-capture-to-chat/spec.md

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 판단·응답(멀티모달 백엔드).
• 웹서치.
• 캡쳐 이미지 편집(자르기·주석), 캡쳐 히스토리.