UX Spec — 에디터 화면 설계

파이프라인 4단계(Design) 산출물 · 2026-09-16 · rev.1(UX 리뷰 UR-01~15 · 흐름 순열 Critical E-C1~3 · Important 규칙 반영) · rev.1a(2라운드 UR-16 필수 + UR-17~19 권고 반영) 권위: docs/seed-spec-fullstack-code-editor.md v1.1.1 LOCKED. 파생: docs/prd-fullstack-code-editor.md(FR · U 표) · docs/bdd-fullstack-code-editor.md · docs/architecture-fullstack-code-editor.md(rev.3, ED-01~16) · docs/flow-permutation-fullstack-code-editor.md(FP-E · E-C/E-I/E-N). 동일 단계 입력: 상위 docs/ux-spec-cocode.md(§2.1 골격 · §2.2 진입점 · §2.4 상태바 · §2.5 빈 상태 · §6 CoUI 매핑 · §8 K1~K4 · UX-D-18 I1~I3 · UX-D-31) · docs/coui-inventory-cocode.md §1 · §3 · §4 · cc-coui 스킬(tabs · empty-state · alert · banner · button · menubar · dialog · tooltip · text-field · listing · status · dropdown-menu). 이 문서는 상위 ux-spec 의 결정(UX-D-01~31)을 그대로 전제하고, 에디터 모듈이 더하는 화면과 결정(UX-E-nn)만 적는다.

0. 표기 규칙 (상위 §0.2 승계)

• [경계] Seed/PRD 문면 · [도출] 상위 규약에서 판정 없이 연역 · [규약] 조직 스킬 · [UX-E-nn] 이 문서가 새로 정하는 결정(§9 전량).
• 수치는 출처가 있을 때만 — 셸 비율 · 치수는 cocode_density.dart(navigation 0.2 · workbench 0.55 · inspector 0.25 · editor 0.7 · rowHeight 24 · statusBar 28 · toolbar 32 · pointer 44)를 그대로 쓴다. 와이어프레임 안의 파일명 · 건수 · 시각은 전부 예시다. 지연 시간 · 개수 상한 값은 쓰지 않는다.
• 문구는 승인 주체가 정해질 때까지 «자리표시자» 표기(상위 UX-D-31). 팔레트 라벨 형식도 같다.
• CoUI 표기는 스킬 표기를 따른다: Alert.info(...) · Alert.destructive(...) · Banner(variant: .destructive) · EmptyState.compact(...) · Button(variant: ghost, shape: square).

1. 설계 원칙 (상위 5개 위에 더하는 2개)

2. 화면 구조 — 상위 §2.1 골격 안에서 채우는 곳

┌──────────────────────────────────────────────────────────────────────────────┐
                    │ File   Edit   View   Delegate   Run   Help                        [Menubar]  │  ← 순서는 상위 §2.1 목업 그대로
                    ├───────────────┬──────────────────────────────────────┬───────────────────────┤
                    │ [탐색][위임][검색] │ lib/a.dart ●  b.dart ×  server.dart ×│ Task Inspector (상위)  │
                    │               ├──────────────────────────────────────┤                       │
                    │ ▾ app/mobile  │ ▲ 작업 T-042 편집 대상 — 저장은 막히지 않습니다  [작업 보기][닫기] │
                    │   ▾ lib       │  1  import 'package:flutter/...';    │                       │
                    │     a.dart ●  │  2                                   │                       │
                    │ ▾ backend/    │  3  class LoginPage extends ... {    │                       │
                    │   ▾ server    │  4    @override   ⚠                  │                       │
                    │     server.d  │                                      │                       │
                    │ ▸ build (숨김)│        [ CocodeEditorView ]            │                       │
                    │               ├──────────────────────────────────────┤                       │
                    │               │ [터미널 ▾2] [문제 3] [검증 로그]  [+ ▾] │                       │
                    │               │ ● Serverpod 풀스택 실행   ○ zsh(0)   │                       │
                    │               │ $ serverpod start                    │                       │
                    ├───────────────┴──────────────────────────────────────┴───────────────────────┤
                    │ unibook │ 실행중 2 · 승인대기 3 · 실패 1 │ 잠금 1 │ Dart LS ● │ 저장됨       │
                    └──────────────────────────────────────────────────────────────────────────────┘
                    

• 페인 비율 · 접기 · 리사이즈는 상위 UX-D-02/03 그대로 — 이 모듈은 새 페인을 만들지 않는다 [도출].

3. 명령 표 (정본) · 화면 인벤토리

3.1 1급 동작 명령 표 — K1 커버리지의 정본 [UX-E-03]

CocodePaletteCoverage 테스트는 이 표로 판정한다. 팔레트 라벨은 «자리표시자»(라벨의 첫 단어는 사용자가 떠올릴 동사 — 상위 K1 주석). K4 = Enter 기본 활성화 없음.

3.2 화면 인벤토리 (신설 · 확장)

4. 표면별 명세

4.1 에디터 탭 스트립 · 본문 (S-E01) — AC-01 · AC-03

• 탭 = 파일 이름 + dirty 점(●) + 닫기(×) — CoreTabItem 의 label 이 Widget 슬롯이므로 합성(사다리 ③, UR-07). 탭 재정렬은 TabPane 계약(드래그 재정렬 실재). 오버플로는 FadeScroll/OverflowMarquee.
• 읽는 중: 파일 선택 직후 본문 자리에 CoUI Loading(탭은 즉시 생성). 읽기 실패(권한 없음 · U-12 바이너리 거부): 탭은 열리되 본문 자리에 Alert.destructive(사유 «자리표시자») + 편집 불가, 탭 × 로 닫기 [UX-E-04](E-I2).
• 활성 탭 재클릭은 디스크를 다시 읽지 않는다(flutter_ide §6-b5 교훈) [도출 AC-03].
• 활성 탭이 닫힌 뒤 활성 탭 = 직전 활성 탭(MRU), 없으면 왼쪽 이웃 [UX-E-05](E-I6).
• 탭 닫기: dirty 면 S-E02(단일). 중간 클릭 닫기 · "다른 탭 닫기"는 첫 릴리스 밖 [UX-E-06].
• 편집 그룹 · 화면 분할(D-084 · D-085): 탭을 끌어 탭 줄에 놓으면 그 자리에 끼운다(좌/우 반쪽이 앞/뒤 — 세로 선으로 미리 보인다, 빈 자리는 끝). 본문 가장자리 25% 띠에 놓으면 그 쪽에 새 그룹이 서고(놓을 반쪽이 미리 칠해진다), 가운데에 놓으면 그 그룹 끝으로 옮긴다. ⌥(Option)를 누른 채 놓으면 복사다 — 떠난 그룹에도 남고, 끄는 탭 그림에 + 가 붙는다. «오른쪽으로 분할»(⌘\)은 활성 탭을 복제해 오른쪽 새 그룹에 연다. 같은 축으로 거듭 나누면 한 줄에 선다(「A | B | C」). 그룹이 비면 걷히고(마지막 그룹은 남는다) 분할이 접힌다.
• 같은 문서를 여러 그룹에(D-085): 한 그룹 안에서는 한 번이다. 트리 · 검색 · 문제에서 여는 파일은 다른 그룹에 열려 있어도 활성 그룹에 선다(모두 바꾸기는 탭을 불리지 않게 열린 탭을 쓴다). 그룹마다 Monaco 모델이 따로지만 정본은 버퍼 하나이고, 한쪽 편집은 다른 쪽에 실행 취소가 되는 구간 교체로 비친다(커서 · 스크롤 유지). 탭 닫기는 그 문서의 마지막 탭일 때만 처분(S-E02)을 묻는다 — 다른 그룹에 남아 있으면 탭만 걷힌다.
• 실행 취소 이력은 그룹을 따라간다(D-085): 탭을 다른 그룹으로 옮기거나 복제하면 Monaco 의 실행 취소 · 다시 실행 단계가 새 그룹 편집기로 이어진다(단계 경계는 Monaco 의 것 그대로 — 한글 조합 묶음 포함, 앞뒤 각 300단계까지).
• 분할선 비율(D-085): 구조가 바뀌어도 남은 칸끼리의 비율을 지킨다 — 칸이 더해지면 새 칸이 1/n, 원래 칸들은 서로의 비율대로 나머지를 나눈다. 칸이 빠지면 남은 칸들이 비율대로 나눈다. 트리 · 검색 · 문제에서 여는 파일과 Cmd+S · Cmd+W 는 활성 그룹으로 가고(탭 줄 · 본문을 누르거나 Monaco 가 포커스를 받으면 그 그룹이 활성), 나뉘어 있을 때 활성 그룹 탭 줄 위에 2 px 강조선이 선다. 활성 탭이 닫히면 같은 그룹 안에서 직전 활성(MRU)을 고른다. 탭을 떼어 별도 창으로 분리하는 것은 후속(D-084 · Flutter 실험 windowing).
• 빈 상태: 파일 0 → EmptyState.compact(상위 §2.5 ⓐ행과 같은 계약) — 제목 «열린 파일 없음», 동작 [파일 열기…] → 탐색 탭 포커스.
• 외부 변경 대기(external_change_pending): 탭에 ⟳ 배지 + 본문 상단 인라인 Banner(variant: .warning) («디스크에서 바뀜/삭제됨») — 다이얼로그가 아니라 배너인 이유: I3(조합 중 포커스 이동 금지)와 P1 [UX-E-07]. 선택 [디스크에서 다시 읽기](K4) [내 편집 유지] — CoUI Banner 의 action 슬롯은 하나이므로 두 버튼은 그 슬롯 안에 Row 로 합성한다(UR-18).
• 저장 실패(HumanWriteFailed): 같은 자리에 Banner(variant: .destructive) («저장 실패: 사유» + [다시 시도]) + 상태바 «저장 실패», 버퍼는 dirty 유지. 토스트를 쓰지 않는다(상위 UX-D-08 — 이 문서의 화면 계약은 Toast 를 쓰지 않는다) [UX-E-37].
• path_key 정규화 충돌(대소문자 폴딩 볼륨에서 A.dart/a.dart)의 표시 이름은 처음 연 이름을 유지 [UX-E-08](E-I4).

4.2 dirty · 프로세스 처분 다이얼로그 (S-E02) — AC-03 · E-C1 · E-C2

• [UX-E-18] 종료 · 닫기 시 실행 중 프로세스 처분(E-C1): 일괄 다이얼로그가 실행 중 세션(사용자 셸 · 실행 구성)을 반드시 나열하고, "계속" 선택 시에만 terminate({grace}) 로 전부 종료한 뒤 진행한다. 언어 서버는 앱 소유 프로세스라 목록에 없고 무조건 종료된다(architecture ED-16). 고아 프로세스 0 — 닫기 완료 전에 TerminalSessionManager 가 exited 를 확인한다.
• [UX-E-19] 일괄 저장 부분 실패(E-C2): [모두 저장하고 계속] 중 한 파일이라도 실패하면 진행하지 않는다 — 다이얼로그가 실패 목록(파일 · 사유)을 남기고 성공한 파일은 clean 으로 바뀐 채 유지된다. 사용자는 [다시 시도] [실패분 폐기하고 계속](K4) [취소] 중 하나를 고른다. Seed 불변식 (2) — 처분 없는 소멸은 없다.
• 저장 진행 중 상태: 버튼 비활성 + Loading. CoUI Dialog + Button(destructive) 그대로(사다리 ①). 포커스 트랩은 Dialog 에만(K3).
• 닫기 단계 순서(E-I29): 이 다이얼로그 → 검색 취소 → 언어 서버 종료 → 세션 종료 → 감시 해제 → 버퍼 해제(architecture ED-16). 취소는 다이얼로그 단계에서만 가능하고 그 뒤 단계는 되돌리지 않는다 [UX-E-26].

4.3 검색 패널 (S-E03) — AC-06

• 입력: 검색어 TextField + 토글 버튼 3개 [Aa](대소문자) [ab](단어 단위) [.*](정규식) — 에디터 찾기(Monaco)와 같은 순서 · 같은 판정 — Button(variant: ghost, shape: square) + pressed 상태(UR-06; CoUI Toggle 은 스위치라 쓰지 않는다) [UX-E-10]. 단어 단위는 D-083 로 범위에 들어왔다 — 경계는 Monaco wordSeparators 판정이라 한글은 단어 글자다.
• 제외할 파일(D-083): 쉼표로 가른 glob — .gitignore 한 줄 문법(트리 무시 규칙과 같은 해석기 · build/ 는 어느 깊이든 · /gen/ 은 루트 고정 · ! 부정, 단 제외된 디렉터리 아래는 되살리지 않는다). Enter 로 실행한다. 해석되지 않는 glob 은 제외 입력 아래 인라인 오류(검색 미실행, 정규식 오류와 다른 칸). 요약에 «N개 파일 제외». [검색어 지우기] 는 토글 · 제외 glob 을 남긴다. 포함할 파일(include) glob 은 범위 밖.
• 빈 검색어(공백만 포함)는 실행하지 않는다 — Enter 무시 · 검색 버튼 비활성 [UX-E-11](E-I10).
• 검색 시작: Enter. 실행 중: Loading + [검색 중지](중지 시 부분 결과 유지). 결과: CocodeVirtualList 행 = 경로:행 — 미리보기(일치 구간 강조), 파일별 그룹 접기. 결과 0: EmptyState.compact(«일치 없음», 동작 [검색어 지우기] — UX-D-31 세 칸 충족, UR-08).
• 정규식 오류: 입력 필드 아래 인라인 오류(검색 미실행).
• 결과 선택 규칙 [UX-E-12](UR-10): 화살표 이동 · 단일 클릭 = 에디터에 미리보기 열기(포커스는 패널에 남는다, K2) · Enter · 더블클릭 = 열고 에디터로 포커스 이동. 결과 행의 파일이 그 사이 삭제되면 행에 «삭제됨» 표시 + 열기 시 Alert.destructive(E-I12).
• 치환: 치환 필드 + [AB](대소문자 보존 — 맞은 자리마다 대소문자 모양을 따른다, VS Code 판정 · D-083) + [모두 바꾸기](K4). 치환 문자열은 글자 그대로다 — 정규식 캡처 참조($1)는 해석하지 않는다. 확인 다이얼로그 없음 — 사람 편집이며 각 버퍼의 실행 취소로 되돌린다 [UX-E-13]. 치환 기준은 버퍼 내용(dirty 버퍼도 버퍼 기준, E-I14) · 저장 부분 실패 시 실패 파일 목록을 패널 상단 Alert.destructive 로, 성공분은 유지 [UX-E-14](E-I15).
• 한글 조합 중 Enter 는 조합 확정만(I2, 상위 소관).

4.4 문제 패널 (S-E04) — AC-07

• 상단 상태 줄: «시작 중» / Status(dot) ● «실행 중» / ○ «없음 — 실행 파일을 찾을 수 없음» / ○ «종료됨(코드 N)» + [언어 서버 다시 시작]. 자동 재기동 없음(ED-10). 다시 시작 실패(부재 · 즉시 종료)는 같은 줄에 사유(E-I16).
• 목록: CocodeProblemsList(CocodeVirtualList 위) 행 = 심각도 아이콘(+ Semantics 라벨) · 파일 · 행:열 · 메시지. 선택 → 에디터 이동(포커스 이동). 필터는 첫 릴리스 밖.
• 표시 범위 [UX-E-22](E-I18): 언어 서버가 보낸 진단은 파일이 열려 있든 아니든 전부 목록에 표시된다(서버가 정본). 파일을 닫아도 유지되고, 서버가 빈 목록을 보내면 제거된다. 재시작 중 도착한 진단은 새 서버의 것으로 교체된다.
• 진단 0: EmptyState.compact(«문제 없음», 동작 없음 — 의도적 무동작, UX-E-17).
• 탭 라벨 배지 [문제 3] = 오류 + 경고 개수(정보 제외) [UX-E-15].
• 거터: 오류 ⛔ · 경고 ⚠ 표식, hover 툴팁 = 메시지(CoUI Tooltip).
• Dart 이외 파일: 상태 줄은 워크스페이스 단위 — "이 파일에는 언어 서버가 없다"를 표시하지 않는다(AC-07 후단).

4.5 세션 탭 바 + 터미널 (S-E05) — AC-08 · AC-09

• CocodeSessionTabBar: 세션 탭 = Status(dot, semanticLabel)(running ● / exited ○ + 종료 코드) + 이름(origin: 실행 구성 이름 또는 셸 이름; 같은 구성의 두 번째 실행은 «이름 #2», UX-E-24) + ×. [+] = 새 터미널(PTY), [+ ▾] = DropdownMenu(실행 구성 목록, UR-07). 탭 순서 = 생성 순, 재정렬 없음 [UX-E-16](UR-13).
• running 세션의 × 는 비활성이다 — 종료는 툴바 [터미널 종료]/[중지](K4)로만 하고, exited 뒤에 × 로 탭을 닫는다 [UX-E-20](E-C3). 비활성 × 에는 Tooltip + Semantics 라벨 «실행 중 — 먼저 종료하세요» 를 둔다(UR-19). 툴바는 Button(ghost, square) + Divider 클러스터(CoUI 에 Toolbar 컴포넌트 없음, UR-07).
• 세션 0: EmptyState.compact(«터미널 없음») + [새 터미널]. PTY 기동 중: 탭 생성 + 본문 Loading.
• 실행 구성 세션: 탭 앞 ▶ + 툴바 [중지](running) / [다시 실행](exited) — 다시 실행 = 이전(exited) 세션 탭을 닫고 같은 자리에 새 세션을 만든다 [UX-E-23](E-I20). 이전 출력이 사라지는 것은 「닫기」의 결과이므로 AC-09 「닫기 전까지 남는다」 문면과 어긋나지 않는다(UR-19). 사용자 셸 세션: [터미널 종료](running) / [닫기](exited). 종료된 세션의 출력은 닫기 전까지 남는다(AC-09).
• 전제 미충족 · 기동 실패 · PTY 실패 · 셸 즉시 종료: 세션 자리에 Alert.destructive(사유 «자리표시자» + [닫기]) — 세션이 만들어지지 않은 경우(전제 미충족)도 같은 자리에 한 번 표시 [UX-E-21]. 즉시 종료는 exited(code) 로 남고 사유 = 종료 코드(E-I21).
• scrollback 상한 도달: 표시 없음(오래된 줄 폐기 — AC-09). 값은 kCocodeDefaultScrollbackLines 현행 5000 을 설정으로 노출(architecture §10 U-2).
• IME: I1 preedit 밑줄 · I2 조합 중 전송 0바이트(기존 CocodeTerminalImeConnection) · I3 포커스 유지. 판정은 상위 cocode/AC-16(분리).

4.6 작업 대상 배너 (S-E07) — AC-10

• CocodeTaskFileBanner(taskIds, titles): 에디터 본문 상단 1줄 스트립 — 상위 CocodeFailureBanner 와 같은 조립인 CoUI Banner(cocode_failure_banner.dart:87-89 는 Banner(variant: .destructive); 이 배너는 variant: .info)(UR-01). 문구 «작업 T-042 가 이 파일을 편집하는 중입니다 — 저장은 막히지 않습니다» + [작업 보기] + [닫기].
• 두 작업 이상이 같은 파일에 스냅샷을 남겼으면 전부 나열 [UX-E-25](E-I28). 작업이 종결(완료 · 실패 · 롤백됨 · 거부됨 · 중지됨)되면 배너는 즉시 제거되고, 다른 실행 중 작업이 남아 있으면 그 목록으로 갱신 [UX-E-27](E-I27).
• 닫으면 그 세션 동안 같은 작업 · 같은 파일에 재표시하지 않는다 [UX-E-28].
• 트리 배지: 탐색 탭의 파일 행에 작업 배지(CocodeFileTree.badgeBuilder) — 상위 🔒(리스) 배지와 다른 기호 ◐ + Semantics 라벨 [UX-E-29].
• 저장 시 어떤 경고 · 확인도 띄우지 않는다(E1).

4.7 실행 구성 (S-E06) — AC-08

• 진입점 3개(상위 §2.2 원칙): Run 메뉴 · 팔레트(«실행: <이름>») · 세션 탭 바 [+ ▾] [UX-E-30].
• 목록 항목 = 이름 · template_kind 아이콘 · working_dir 상대 경로. 프로젝트 디렉터리 0 → EmptyState.compact(«실행할 프로젝트 없음», 동작 [실행 구성 JSON 열기] — UX-D-31 세 칸, UR-08).
• 전제 검사 중: 항목에 Loading. 전제 미충족: 실행하지 않고 §4.5 의 Alert 로 사유 + (serverpodStart 4.x 미충족 시) [Serverpod 3.x 서버 실행으로 대신 실행] [UX-E-31].
• flutterRun 디바이스 미지정 [UX-E-32](E-I23): flutter devices --machine 결과를 CoUI Dialog + Listing 으로 제시 → 선택 시 그 디바이스로 실행 · 취소 시 미실행. 선택은 그 실행에만 쓰이고 저장하지 않는다(저장은 JSON 편집으로). 목록은 화살표 이동 + Enter 선택 · Esc 취소(K2, 첫 항목에 초기 포커스, UR-19).
• working_dir 소실(E-I24): 실행 거부 + 사유(§4.5 Alert). JSON 손상(E-I25): 목록 상단 Alert.destructive(«실행 구성 파일을 읽을 수 없음») + [JSON 열기] — 기본 템플릿을 덮어쓰거나 재생성하지 않는다(사용자 파일 보호) [UX-E-33].
• 같은 구성 중복 실행은 허용 — 새 세션(«이름 #2») [UX-E-24](E-I26).
• 실행 구성 편집은 첫 릴리스에서 JSON 파일 열기(.cocode/editor/run_configurations.json 을 에디터 탭으로) — 전용 폼은 이후 [UX-E-34]. 저장 시 목록을 다시 읽는다(architecture ED-07 두 쓰기 주체 규칙).

5. 사용자 흐름 (PRD §4 흐름 1~6 + 교차 흐름 7)

6. CoUI 매핑 (사다리 위치)

7. 접근성 · 키보드 · IME

• K1: §3.1 명령 표 전부 팔레트 등재 — CocodePaletteCoverage 테스트의 정본.
• K2: 포커스 순환에 [검색] 탭과 세션 탭 바를 포함(좌 → 중 → 우 → 하단 → 순환). K3: 트랩은 Dialog · Command 만. K4: §3.1 의 K4 열(search.replaceAll · run.stop · terminal.kill · editor.reloadFromDisk)과 S-E02 의 [폐기] [모두 폐기하고 계속] [실패분 폐기하고 계속] [모두 저장하고 계속](프로세스 종료 동반) [UX-E-35].
• 키 조합 표: 상위 UX-D-16 대로 정하지 않는다 — Breakdown 이슈(U-11).
• Semantics · 이중화 [UX-E-36](UR-09): 신설 글리프는 색 + 텍스트/라벨로 이중화한다 — ● dirty → «저장되지 않음», ⟳ → «디스크에서 바뀜», ◐ → «작업 편집 대상», ▶ → «실행 구성 세션», 세션 ●/○ → Status.semanticLabel «실행 중»/«종료됨(코드 N)», 거터 ⛔/⚠ → «오류»/«경고». UI 크롬 대비는 상위 §8.3(4.5:1 / 3:1) · 구문색 대비는 CocodeSyntaxScheme WCAG AA 검사.
• IME I1~I3: 검색 입력 · 치환 입력 · 팔레트 입력 · 실행 구성 JSON(에디터) · 터미널은 같은 규약. 판정은 상위 cocode/AC-16 재생 프로브에 표면 추가(architecture §6).
• 히트영역 44dp(CocodeTouchTarget.pointer) · 고정폭 CocodeMonoFont.

8. 빈 상태 표 (상위 §2.5 · UX-D-31 세 칸 형식)

9. 이 문서가 새로 정한 결정 (UX-E 목록)

10. 값이 없어 정하지 않은 것

문구 전부(«자리표시자») · 키 조합 표(U-11) · scrollback 기본값 근거(U-2) · 아이콘 세트(파일 타입 아이콘은 상위 규약의 raw Color 예외 범주 — Design 후속) · terminate grace 값(architecture §10).

11. Seed · PRD · 상위 ux-spec 과의 어긋남 / 공백 (숨기지 않고 적는다)

Generated by cc-product Design stage (UX Designer) · 2026-09-16 · rev.1a