notParsec / 문서전체 문서

설명·설계 문서

클립보드·드래그앤드롭·Immersive Mode

design/CLIPBOARD_AND_IMMERSIVE.ko.md

출처: 현재 작업 폴더 · 원문 다운로드

이 문서의 목차

2026-09-25 · progress-25 · F37 / F51 · Windows Parsec 150-104a 대조

게시한 Windows 빌드: 1790331224. 양쪽 PC를 업데이트하고 재접속한다. EXE SHA-256: e55e062bdc944c360476690e952223535644103e9f869134cb667318aef1895c.

텍스트·이미지 클립보드 전송과 Windows 콘텐츠/파일 드롭을 통합 앱에 연결했다. Ctrl+Shift+I는 저장한 Immersive 모드를 보존하며 일시적으로 끄거나 켠다. 기능 코드·자동 시험과 실제 Windows/Parsec 실행 대조는 구분한다. 원본 일치 완료 판정은 아직 아니다.

1. 기존에는 무엇이 빠져 있었나

항목 이전 상태 이번 처리
텍스트 클립보드 egui 로컬 입력창의 Copy/Paste만 있음 인증된 연결에서 양방향 UTF-8 전달, 상대 OS 클립보드에 쓰기
이미지 클립보드 원격 전송 없음 OS 이미지 → PNG → 상대 OS 이미지. 알파 포함 RGBA 시험
Ctrl+C / Ctrl+X UI 라이브러리가 별도 이벤트로 바꿔 원격 라우터가 놓침 원격 키 조합으로 전달
Ctrl+V 텍스트 Paste 이벤트와 이미지 전용 붙여넣기 누락 OS 데이터를 가져와 전달하고 상대 OS 쓰기 완료 후 붙여넣기
파일 드롭 원격 수신 경로 없음 로컬 파일을 호스트에 저장하고 Windows 파일 목록 클립보드로 붙여넣기
선택한 텍스트·이미지 드롭 기본 창 드롭은 파일만 처리 Windows OLE IDropTarget: Unicode text, PNG, DIB/DIBV5, 파일 목록 받기
Ctrl+Shift+I Mouse confinement의 pause만 바꿈. 기본 Off에서는 효과 없음 Off → 임시 Keyboard, 활성 모드 → Off, 다시 누르면 저장 모드 복구
Keyboard / Both 비활성 메뉴 Windows 포커스 범위의 시스템 키 hook 연결

이미지/파일 지원은 이번 명시 요청 E06에 근거한다. 원본의 전체 이미지/파일 지원을 확인했다는 뜻은 아니다. 예외 범위와 개발 현황은 이 차이를 그대로 남긴다.

2. 사용 방법과 적용 범위

양쪽 PC에 같은 최신 /9 앱을 설치하고 다시 연결한다. 이전 /8 앱과는 새 메시지를 교환할 수 없어, 인증 단계에서 호환 오류를 표시한다. Ubuntu 관리 서버는 암호화된 바이트를 전달하므로 새 클립보드 형식을 해석하지 않는다.

  1. Settings → Client → Copy and Paste를 켠다. 기본값은 켜짐이며, 이 PC의 접속·호스팅 모두 다음 연결부터 적용한다.
  2. 원격 화면을 한 번 클릭해 입력을 활성화한다. 텍스트나 이미지를 복사하고 Ctrl+V로 붙여넣는다. 호스트에서 복사한 내용도 접속 PC로 동기화된다.
  3. Windows에서 선택한 텍스트·이미지 또는 파일을 원격 화면의 대상 위치에 놓는다. 원격 위치에 포커스를 주고, 해당 콘텐츠를 클립보드에 적용한 뒤 붙여넣는다.
  4. 파일은 호스트의 Downloads/notParsec Received/received-…/파일명에 먼저 저장된다. Windows 탐색기는 파일 목록 붙여넣기를 받아 대상 폴더에 복사할 수 있다. 같은 이름의 기존 수신 파일은 덮어쓰지 않는다.
  5. 원격 플로팅 메뉴 → Immersive Mode → Off / Keyboard / Mouse / Both에서 기본 모드를 선택한다. Ctrl+Shift+I는 일시 전환이고 기본 선택은 유지한다.

Copy and Paste를 끄면 콘텐츠 동기화·파일 드롭을 거부한다. 접속 PC에서 이 설정을 끈 경우에도 원격 화면의 Ctrl+C/V는 호스트 자체 클립보드를 사용하는 키 입력으로 작동한다. 연결 전부터 들어 있던 내용을 무조건 상대 PC로 덮어쓰지는 않는다. 연결 후 변경을 동기화하고, 명시적인 붙여넣기 때 현재 로컬 내용을 읽어 전송한다.

현재 제한

구분 구현 범위·한도
텍스트 UTF-8 최대 100 KiB. 한글·다국어·개행. HTML/RTF 서식은 전송하지 않음
이미지 PNG 최대 16 MiB, 최대 16,777,216픽셀, 한 변 8,192 이하. RGBA 8-bit. HDR/ICC 색상 일치 별도 미검증
파일 한 번에 한 파일, 64 MiB 이하, 한 연결에서 수신 합계 256 MiB. 폴더·다중 파일 묶음·이어받기 없음
드롭 형식 Windows HGLOBAL Unicode/PNG/DIB/파일 목록. 브라우저가 HTML·URL 또는 가상 파일만 제공하면 콘텐츠 드롭 미지원; 복사 후 붙여넣기를 사용
전송 방향 텍스트·이미지 동기화는 양방향. 파일 드롭은 접속 PC → 호스트. 호스트 파일을 창 밖으로 끌어오는 기능 없음
드롭의 의미 수신 앱의 클립보드 붙여넣기로 처리. 원격 앱과 native OLE DragEnter/Drop를 협상하는 것은 아님. 붙여넣기를 받지 않는 앱에서는 파일이 저장돼도 화면상 삽입되지 않을 수 있음
Windows 키 Alt+Tab, Windows 키 조합, Ctrl/Alt+Esc 등을 포커스가 있는 원격 창에서 전달. Ctrl+Alt+Del/SAS와 관리자/UAC 화면은 이 경로로 처리하지 않음
다른 OS X11 클립보드 실제 시험. Linux 파일 수신은 폴더 저장까지이며 파일 목록 자동 붙여넣기 미지원. Mac 전체 앱·OS 간 조합은 미검증

위 크기·시간·저장 위치는 notParsec의 독립 구현 한도다. Parsec에서 복구한 제품 사양으로 표시하지 않는다.

3. 기본 개념: 키 입력과 클립보드는 다른 데이터다

Ctrl+C는 운영체제에 현재 선택을 복사하라는 키 입력이다. 그 키를 다른 PC에 보낸다고 로컬 클립보드가 함께 이동하지는 않는다. 텍스트·이미지 바이트를 별도로 전송하고 상대 PC의 OS 클립보드에 넣어야 한다. 그 다음 Ctrl+V가 상대 앱에 적용돼야 한다.

이미지는 OS마다 비트맵 표현과 픽셀 순서가 다를 수 있다. 이 구현은 전송 시 PNG로 통일하고, 수신 시 크기를 검증한 뒤 RGBA로 복원해 OS에 쓴다. 파일 목록 클립보드에는 파일 본문 대신 그 PC에 실제로 존재하는 경로가 들어간다. 따라서 로컬 경로 문자열만 원격으로 전달하지 않고 파일 바이트를 먼저 호스트에 저장한다. Windows의 CF_UNICODETEXT, CF_DIB/CF_DIBV5, CF_HDROP 정의는 Microsoft 표준 클립보드 형식을 따른다.

전송·붙여넣기 순서는 다음과 같다.

로컬 Copy/Paste 또는 Drop
  → OS 작업 스레드가 읽기·이미지 변환·크기 검사
  → Begin → 최대 12 KiB씩 Chunk → End
  → 기존 인증·암호화된 Direct UDP / WSS 세션
  → 호스트 작업 스레드가 순서·길이·형식을 검증
  → OS 클립보드 쓰기 / 파일 저장
  → 요청한 경우 입력 큐에 Paste를 넘김
  → 입력 처리 시 호스트에 맞는 Ctrl+V / Cmd+V
  → 적용 결과를 송신 측에 응답

End 전에 붙여넣으면 이전 클립보드 내용이 들어간다. 그래서 OS 쓰기 완료와 입력 큐 사이에 순서 조건을 둔다. Paste는 하나의 입력 동작으로 처리하며, 누르고 있던 Ctrl/Shift/Alt/Win 상태를 잠시 해제했다가 복원한다. 늦게 끝난 자동 동기화 응답이 새 파일 전송 완료로 표시되지 않도록 명시 요청 ID도 구별한다.

4. 프레임·입력 지연을 키우지 않기 위한 처리

자동 동기화는 변경된 내용을 보내지만, 상대가 보낸 내용을 OS에 쓴 직후 이를 다시 읽어 돌려보내면 무한 왕복이 된다. Windows의 sequence와 적용 후 실제 OS 내용의 digest를 기록해 이를 막는다. 이 digest는 내용 비교에만 사용하고 클립보드 본문을 로그로 남기지 않는다. 두 사용자가 동시에 서로 다른 내용을 복사하는 충돌 정책과 OS 클립보드 잠금 재시도는 추가 대조가 필요하다.

5. 원본에서 확인한 것과 확인하지 못한 것

기준 코어 DLL SHA-256: 8c8c4299ddf503b2c25c0905b0a0820f3e8238c252e9ace37bf25964ef4a8f6f.

근거 확인된 내용 이번 구현과의 관계
FUN_18004ada0 GetClipboardSequenceNumber, CF_UNICODETEXT(0x0d), UTF-16→UTF-8, 0x19000 버퍼 경로 텍스트/변경 감지의 근거. 전체 제품의 크기 정책까지 복원됐다고 보지 않음
FUN_18004af20 GlobalAlloc/EmptyClipboard/SetClipboardData(0x0d), 쓴 뒤 sequence 갱신 OS 쓰기와 echo 억제 대응
FUN_18004b030, 18004b0a0 WM_CLIPBOARDUPDATE, 숨은 창/listener·타이머 경로 notParsec은 별도 worker와 250ms 변경 확인. 정확히 같은 감시 구조는 아님
FUN_180023110 Off=0, Both=1, Keyboard=2, Mouse=3. 저장 layer와 임시 layer 토글. Off에서 임시 Keyboard 이번 Off/Keyboard/Mouse/Both 및 Ctrl+Shift+I 상태 전이 대응
app_copy_paste 설정 기본 true인 등록값과 참조 함수 notParsec의 다음 연결 적용 설정. 원본의 UI 위치·모든 권한 조건은 미검증
이미지/파일·native OLE 위 텍스트 함수만으로 지원 여부 확정 불가 이번 명시 요청 E06 확장. 원본 wire나 Parsec 서버 호환 구현 아님

보관 자료는 디컴파일 의사 코드이며 원본 소스가 아니다. 새 Rust 모듈은 이를 참고한 독립 구현이다. 최신 Parsec Immersive Mode 안내와 기본 특수 키 전달 안내는 Ctrl+Shift+I를 설명하지만, 보관한 150-104a와 같은 실행 검증으로 간주하지 않는다.

6. Immersive Mode 동작

저장한 모드 평상시 Ctrl+Shift+I 한 번 다시 누름
Off 일반 입력 임시 Keyboard Off
Keyboard 시스템 키 전달 임시 Off Keyboard
Mouse 커서 가둠 임시 Off Mouse
Both 시스템 키 전달 + 커서 가둠 임시 Off Both

저장된 선택과 세션 임시 상태를 분리한다. 메뉴에서 새 모드를 선택하면 임시 override를 없애고 그 선택을 저장한다. 키를 누르고 있을 때 발생하는 OS 반복 입력으로 계속 토글되지 않게 한다. Ctrl+Shift+I, Ctrl+Shift+M, Ctrl+Shift+W는 로컬 메뉴 동작으로 처리해 원격으로 그대로 전달하지 않는다.

Windows low-level keyboard hook는 앞에 있는 원격 HWND와 활성 화면 입력만 대상으로 한다. 다른 프로그램, 로컬 설정창, overlay, 포커스를 잃은 원격 창에는 적용하지 않는다. 주입된 키는 다시 잡지 않아 동일 앱의 호스팅/접속이 순환하지 않게 한다. 메뉴·포커스 해제·종료에서는 보낸 키를 해제한다. Ctrl+Alt+Z는 마우스 가두기를 일시 해제하고 원격 화면을 다시 클릭하면 복귀한다. 실제 Windows에서 hook/입력·메뉴·여러 창의 세부 상태 대조는 남아 있다.

7. 검증과 다음 대조

기계 판독 가능한 검증·게시 기록에 최종 빌드 번호·해시와 실행 결과를 남긴다.

다음 대조는 두 PC에서 메모장 텍스트·Paint 이미지·탐색기 파일 드롭, 한글/개행/알파, 클립보드 잠금과 전송 실패, 다중 화면/DPI, Alt+Tab/Win/Ctrl+Shift+I/Ctrl+Alt+Z/포커스 복귀 순서다. F37과 F51은 진행 중이며 전체 완료 수를 올리지 않았다.