fix: 배경색 저장 실패 시 초안 유지와 재시도 지원

[lee-sihun]

개요

스프라이트·요소 회전·편집 저장 안정화의 검증 체크리스트 36항목을 확인하고, 배경색 저장 실패 시 입력값이 사라지던 문제를 수정함. 저장된 화면 배경은 복원하면서 편집 초안은 유지하고, 쓰기 가능 상태로 복구한 뒤 재입력 없이 다시 저장할 수 있게 함

체크리스트 기대와 실제 동작이 다른 항목은 코드·주석·커밋으로 기존 의도를 확인했다. 오버레이 표시·기준점·창 고정과 스프라이트 트리거 연결은 기존 정책을 유지하고 검사 기준과 문서를 정정

변경 내용

배경색 저장

• 편집 초안과 저장된 배경 상태를 분리해 저장 실패 시 입력값 유지
• 팝업 안에 실패 안내와 ‘다시 저장’ 버튼 표시
• 팝업을 닫았다 다시 열어도 실패한 초안과 안내 유지
• 재저장 중 버튼 중복 실행을 막고 성공하면 오류 해제
• 이전 요청의 실패가 이후 입력이나 외부 배경색 변경을 덮지 않도록 기존 보호 유지

문서

• 배경색 저장 실패·재시도 동작을 한글·영문 가이드에 반영
• 첫 실행의 오버레이 닫힘과 이후 표시 상태 복원 정책 설명
• 창 모서리 고정과 기존 요소의 화면 위치를 유지하는 fixed-position의 차이 설명
• 설정 타입과 오버레이 API 문서에 누락된 fixed-position 추가

체크리스트 검증 결과

총 36항목 통과. 아래 통과 판정에는 기존 정책에 맞게 기대값을 정정한 항목이 포함된다

• 3·6·26번은 직접 실기 확인
• 나머지는 실제 앱·OBS 조작, 저장 데이터와 자산 대조, 자동화 검사로 확인. 데이터 준비와 일부 설정에는 IPC, 자동화 키 입력에는 합성 입력 사용
• 수정 후 1·2·8·10·18·24번의 관련 동작을 재검증하고 전체 자동 테스트 실행. 나머지 실기 항목은 앞선 검사 결과 유지

번호	결과	확인 내용
1	통과·기대값 정정	공식 2.0.2 저장 데이터의 요소·탭·매핑·그룹·플러그인 보존. 이미지·사운드 해시 일치. 원점 보정용 overlayLastContentLeftOffset 추가 허용
2	통과·기대값 정정	빈 데이터 첫 실행은 오버레이 닫힘. 표시 상태를 바꾼 뒤 재시작하면 마지막 상태 복원
3	통과·직접 확인	앱을 켠 채 로그아웃·재시작하는 검사에서 문제없음 확인
4	통과	이미지 선택창과 PNG/JPG/WebP/GIF/BMP/SVG/ICO/AVIF 로딩, 한글·공백·긴 경로 확인
5	통과	큰 이미지와 이미지 20개·각 자세 3개 구성의 임포트 및 재시작 로딩 확인. 이미지 22/22 로드, 재시작 준비 약 2.092초, 로딩 후 작업 집합 합계 502.9MB
6	통과·직접 확인	실제 키보드로 스프라이트 담당 키 지정과 유지·해제·단발·조합 입력 동작 확인
7	통과	기준점 편집과 연결·독립 전환 후 캔버스·오버레이의 이미지 변환·원점·배치 일치
8	통과·조건 정정	fixed-position에서 넘침 전후 기존 키의 화면 이동량 X/Y 모두 0. top-left는 창 모서리를 고정하는 기존 정책 유지
9	통과	비율 고정 리사이즈, 최소 크기, 스프라이트 포함 그룹의 동일 배율 리사이즈 확인
10	통과·정책 정정	복제 고스트·배치와 새 ID 발급 확인. 교차 탭에서 동일 매핑의 유일 후보만 연결하고, 불일치·중복 후보는 원본 참조와 자세 보존
11	통과	삭제한 이미지의 trash 격리와 남은 참조 이미지 보존 확인
12	통과	5종 요소 회전, 곡선 커서, Shift 스냅, Escape 취소, 핸들 밖에서 놓은 뒤 기본 커서 복귀 확인
13	통과	음수·소수·경계 회전값 직접 입력, 스크럽, 실행 취소와 오버레이 반영 확인
14	통과	그룹 안팎의 혼합 선택에서 공통 중심 회전과 동일 배율 리사이즈 확인
15	통과	회전 키의 노트 방향·시작선·그라데이션·글로우·테두리 확인
16	통과	바깥 카운터의 회전 추종과 입력 횟수 표시 확인
17	통과	회전 요소가 많은 탭의 유휴 상태에서 CPU가 지속적으로 상승하지 않음 확인
18	통과·조건 정정	창 고정 ON은 얼굴·빈 모서리 모두 클릭 통과. OFF는 얼굴만 오버레이가 받고 빈 모서리는 뒤 앱이 수신
19	통과	이동·리사이즈 후 클릭 영역 추종 확인. 회전 키에 주입한 기하 애니메이션 중에도 얼굴·빈 모서리 수신 구분 확인
20	통과	읽기 전용 저장 실패 시 요소 편집값과 미저장 안내 유지. 쓰기 복구 후 재시도 성공
21	통과	파일 잠금 상태의 이미지 정리 실패가 경고로 남고 앱·파일 보존. 잠금 해제 후 trash 이동 확인
22	통과	스크럽 도중 닫기 동작 후 저장값과 재시작 값 일치
23	통과	분리 패널 편집의 실행 취소·다시 실행과 메인 종료 후 저장 확인
24	수정 후 통과	배경색 저장 실패 후 초안 유지·팝업 재열기·재시도·재시작 보존 확인. 이름·노트 설정의 초안 유지와 플러그인의 저장값 복원 계약 확인
25	통과	하단바·목록의 탭 순서 변경과 커스텀 탭 이름 변경·삭제 확인
26	통과·직접 확인	분리 패널 이동 시 떨림·커서 어긋남 문제없음 확인
27	통과	웹 폰트 편집 시트 열기·편집기 마운트·취소 후 목록 복귀 확인
28	통과	키 매핑 변경과 카운터 초기화의 오버레이 반영 확인
29	통과	기존 2.0.2 윈도우 캡처 소스의 캡처 실패 재현. 새 오버레이 클래스 재선택 후 복구 확인
30	통과	OBS 브라우저 소스의 스프라이트 이미지·입력 반응·위치 동기화와 BMP/ICO/AVIF 표시 확인
31	통과	OBS의 회전 키·노트 방향·시작선·그라데이션·글로우·테두리 확인. 픽셀 단위 동일성 판정은 제외
32	통과	OBS 소스 크기가 고정된 상태에서 넘침에 따른 레이아웃 이동 확인
33	통과	스프라이트·회전·그룹 프리셋의 이미지 내장과 절대 경로 없음 확인
34	통과	빈 데이터에 프리셋을 불러와 이미지·자세·기준점·회전·트리거·그룹 복원 확인
35	통과	같은 프리셋을 공식 2.0.2에 불러오면 오류 없이 스프라이트·회전만 제외되고 나머지 요소·그룹 유지
36	통과	타입·린트·포맷·빌드 및 자동 테스트 통과. 상세 수치는 아래 기록

기대값 정정 근거

• 1번: a86c6434에서 추가한 저장 필드는 가로 원점 보정에 사용됨. 기존 데이터 보존을 확인하되 내부 필드 추가 자체를 실패로 판정하지 않음
• 2번: 4c9301bd와 기본값의 overlay_visible: false에 따라 첫 실행은 닫힘, 이후 마지막 표시 상태 복원
• 8번: b6542974와 원점 보정 구현에 따라 화면 위치 보존 검사는 fixed-position을 기준으로 수행
• 10번: e068f03e와 poseIdentity.ts 주석에 따라 동일 매핑이 정확히 하나일 때만 연결. 단일 L과 D/L 조합은 자동 치환하지 않음
• 18번: f719b729와 visible && !locked 조건에 따라 얼굴·빈 공간 구분 검사는 창 고정 OFF로 수행
• 24번: 4fe06e27의 배경색 초안 유지 의도에 맞춰 입력값 유실 수정. 플러그인은 392314d0의 저장값 복원·패널 종료·false 반환 계약 유지

개발 게이트

• npm run type-check 및 최종 코드의 npx tsc --noEmit 통과
• npm run lint 오류 0, 기존 SoundTrimModal 의존성 경고 1건 유지
• npm run format, git diff --check 통과
• 전체 Vitest 440개 파일·4,649개 테스트 통과, 18개 스킵
• 최종 배경색 훅 테스트 4개 별도 재실행 통과
• 프론트 프로덕션 빌드와 release-fast 실행 파일 빌드 통과
• Rust는 앞선 검사에서 1,151개 통과·4개 ignored. 이번 수정에는 Rust 코드 변경 없음

알려진 동작

• 실패한 배경색 초안은 앱 실행 중 팝업 재열기까지 유지하며 앱 종료 후에는 보존하지 않음
• 스프라이트 자세 이미지의 클릭 영역은 움직이는 이미지가 아닌 활동 상자 기준
• 기존 OBS 윈도우 캡처 소스는 새 오버레이 클래스를 다시 선택해야 함
• OBS 브라우저 소스에서는 왼쪽·위쪽 넘침에 따라 레이아웃이 밀릴 수 있음
• 새 프리셋을 2.0.2에서 열면 스프라이트와 회전 값이 제외됨