From 287b26279c57cb872250f96ab14860582ceed275 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 01:52:11 +0900
Subject: [PATCH 01/18] =?UTF-8?q?feat(rust):=20=EC=84=B8=EC=85=98=EC=97=90?=
 =?UTF-8?q?=20=EC=B5=9C=EA=B7=BC=20=ED=8C=8C=EC=9D=BC=20=EB=AA=A9=EB=A1=9D?=
 =?UTF-8?q?=EC=9D=84=20=EC=A0=80=EC=9E=A5=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

recent_files는 tabs[].path와 같은 규칙으로 걸러진다 — 파일만, 존재하는
경로만, 읽을 때 파일 단위 허용 루트로 등록. 필드가 없는 옛 session.json은
빈 목록으로 읽어 기존 세션을 잃지 않는다. 갱신 시점·상한 정책은
document-model.md#최근-파일이 소유한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/document-model.md          | 13 ++++-
 .claude/docs/rust-commands.md           |  4 ++
 apps/desktop/src-tauri/src/session.rs   | 75 +++++++++++++++++++++++++
 apps/desktop/src/shared/ipc/bindings.ts |  4 ++
 4 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index 5aa4e27..d64cd6b 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -41,7 +41,7 @@ interface WorkspaceState {
                              // 스토어가 별도 보유한다 — 영속화하지 않는다(접힘 영속화와 동일 원칙)
   tabs: Tab[];
   activeTabId: string | null;
-  recentFiles: string[];
+  recentFiles: string[];      // 최근에 연 파일 (→ #최근-파일)
 }
 ```
 
@@ -102,12 +102,21 @@ interface WorkspaceState {
 
 이 규칙은 표면 규칙과도 맞물린다. 창 최상단 띠는 유리(크롬)여야 하는데(→ [창 표면 계약](design/window-chrome.md)), 탭바가 사라지면 그 자리를 불투명한 종이가 차지해 유리가 끊긴다.
 
+## 최근 파일
+
+`recentFiles`는 최근에 연 파일의 canonical 경로 목록이다 — 최신이 앞이다.
+
+- **올리는 시점** — 사용자가 파일을 열 때(다이얼로그·트리·최근 파일 목록·프리뷰 링크) · Untitled가 첫 저장으로 경로를 얻을 때. 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
+- 이미 목록에 있는 경로는 맨 앞으로 옮긴다. **10개**를 넘으면 뒤에서 버린다.
+- 영속화는 `session.json`이다(→ [Rust 커맨드 계약](rust-commands.md#세션)). `load_session`이 지금 없는 경로를 걸러 돌려주고, 남은 경로를 파일 단위 허용 루트로 등록한다 — 재시작 뒤 다이얼로그 없이 다시 여는 근거다.
+- 표시 자리는 빈 상태 안내다(→ [빈 탭](#빈-탭--탭바는-비지-않는다)).
+
 ## 세션 복원
 
 마지막 세션을 재시작 때 되살린다. 저장 자리는 셋이다.
 
 ```text
-탭 목록·활성 탭·루트 폴더·탭별 자리   session.json — Rust가 소유(→ rust-commands.md#세션)
+탭 목록·활성 탭·루트 폴더·탭별 자리·최근 파일   session.json — Rust가 소유(→ rust-commands.md#세션)
 창 크기·위치                        plugin-window-state
 뷰 모드·사이드바 접힘                설정 파일(→ file-lifecycle.md#설정-저장)
 ```
diff --git a/.claude/docs/rust-commands.md b/.claude/docs/rust-commands.md
index 5c92b4a..03738d3 100644
--- a/.claude/docs/rust-commands.md
+++ b/.claude/docs/rust-commands.md
@@ -220,6 +220,9 @@ struct Session {
   root_dir: Option<String>,   // 사이드바 루트. 없으면 폴더를 열지 않은 세션
   tabs: Vec<SessionTab>,      // 경로 있는 탭만 — Untitled는 복원 대상이 아니다
   active: Option<u32>,        // 활성 탭의 tabs 인덱스
+  recent_files: Vec<String>,  // 최근 파일, 최신이 앞 — 갱신 시점·상한은
+                              //   document-model.md#최근-파일이 소유한다.
+                              //   필드가 없는 옛 세션 파일은 빈 목록으로 읽는다
 }
 
 struct SessionTab {
@@ -236,6 +239,7 @@ struct SessionTab {
 자리            종류        허용하면 열리는 범위
 root_dir        디렉터리    그 폴더 아래 전부
 tabs[].path     파일        그 파일 하나
+recent_files[]  파일        그 파일 하나
 ```
 
 `canonicalize` 후의 실제 종류로 판정한다 — 문서처럼 보이지만 디렉터리를 가리키는 심볼릭 링크도 탭 자리에서 거부된다.
diff --git a/apps/desktop/src-tauri/src/session.rs b/apps/desktop/src-tauri/src/session.rs
index 6745695..0410bb4 100644
--- a/apps/desktop/src-tauri/src/session.rs
+++ b/apps/desktop/src-tauri/src/session.rs
@@ -27,6 +27,9 @@ pub struct Session {
     pub root_dir: Option<String>,
     pub tabs: Vec<SessionTab>,
     pub active: Option<u32>,
+    /// 옛 세션 파일에는 이 필드가 없다(→ rust-commands.md#세션).
+    #[serde(default)]
+    pub recent_files: Vec<String>,
 }
 
 #[tauri::command]
@@ -99,10 +102,16 @@ fn remap(session: &Session, map: impl Fn(&str, PathKind) -> Option<String>) -> S
             ..tab.clone()
         });
     }
+    let recent_files = session
+        .recent_files
+        .iter()
+        .filter_map(|path| map(path, PathKind::File))
+        .collect();
     Session {
         root_dir,
         tabs,
         active,
+        recent_files,
     }
 }
 
@@ -166,6 +175,7 @@ mod tests {
             root_dir: Some(dir.path().to_string_lossy().into_owned()),
             tabs: vec![tab(doc.to_str().unwrap())],
             active: Some(0),
+            recent_files: vec![],
         };
 
         write_session(&scope, &file, &session).unwrap();
@@ -215,6 +225,7 @@ mod tests {
                 tab(kept.to_str().unwrap()),
             ],
             active: Some(1),
+            recent_files: vec![],
         };
         fs::write(&file, serde_json::to_vec(&stored).unwrap()).unwrap();
 
@@ -244,6 +255,7 @@ mod tests {
             root_dir: Some(doc.to_string_lossy().into_owned()),
             tabs: vec![tab(dir.path().to_str().unwrap())],
             active: Some(0),
+            recent_files: vec![],
         };
         fs::write(&file, serde_json::to_vec(&stored).unwrap()).unwrap();
 
@@ -274,6 +286,7 @@ mod tests {
                 tab(kept.to_str().unwrap()),
             ],
             active: Some(0),
+            recent_files: vec![],
         };
         fs::write(&file, serde_json::to_vec(&stored).unwrap()).unwrap();
 
@@ -285,11 +298,71 @@ mod tests {
             root_dir: None,
             tabs: vec![tab(kept.to_str().unwrap())],
             active: Some(9),
+            recent_files: vec![],
         };
         fs::write(&file, serde_json::to_vec(&out_of_range).unwrap()).unwrap();
         assert_eq!(read_session(&scope, &file).unwrap().active, None);
     }
 
+    // 집행: rust-commands.md#세션 — recent_files는 파일 경로만, 순서 보존, 허용 등록.
+    // 왜: 최근 파일은 재시작 뒤 다이얼로그 없이 다시 여는 통로다(→ document-model.md#최근-파일) —
+    //     허용 등록이 없으면 목록을 눌러도 Permission으로 거부된다.
+    // 보장: 왕복이 순서를 보존하고 각 경로가 허용된다. 없는 경로·디렉터리는 빠지고 허용되지 않는다.
+    // 경계: 상한·갱신 시점은 프론트가 강제한다(→ document-model.md#최근-파일).
+    #[test]
+    fn 최근_파일이_왕복하고_없는_경로와_디렉터리는_빠진다() {
+        let (dir, scope) = scoped_tempdir();
+        let first = dir.path().join("a.md");
+        let second = dir.path().join("b.md");
+        fs::write(&first, "본문").unwrap();
+        fs::write(&second, "본문").unwrap();
+        let file = dir.path().join(SESSION_FILE);
+        write_session(
+            &scope,
+            &file,
+            &Session {
+                root_dir: None,
+                tabs: vec![],
+                active: None,
+                recent_files: vec![
+                    first.to_string_lossy().into_owned(),
+                    second.to_string_lossy().into_owned(),
+                    dir.path().join("사라진.md").to_string_lossy().into_owned(),
+                    dir.path().to_string_lossy().into_owned(),
+                ],
+            },
+        )
+        .unwrap();
+
+        let fresh = FileScope::default();
+        let restored = read_session(&fresh, &file).expect("세션을 읽는다");
+
+        let canonical_first = fs::canonicalize(&first).unwrap();
+        let canonical_second = fs::canonicalize(&second).unwrap();
+        assert_eq!(
+            restored.recent_files,
+            vec![
+                canonical_first.to_string_lossy().into_owned(),
+                canonical_second.to_string_lossy().into_owned(),
+            ]
+        );
+        assert!(fresh.ensure_allowed(&canonical_first).is_ok());
+        assert!(fresh.ensure_allowed(&canonical_second).is_ok());
+    }
+
+    // 왜: recent_files 필드는 기존 사용자의 session.json에 없다 — 없다고 세션 전체를
+    //     버리면(read_session의 None) 재시작 때 열려 있던 탭을 잃는다.
+    // 보장: 필드가 없는 세션 파일도 읽히고 최근 파일은 빈 목록이다.
+    #[test]
+    fn 필드가_없는_옛_세션은_빈_목록으로_읽힌다() {
+        let (dir, scope) = scoped_tempdir();
+        let file = dir.path().join(SESSION_FILE);
+        fs::write(&file, r#"{"rootDir":null,"tabs":[],"active":null}"#).unwrap();
+
+        let restored = read_session(&scope, &file).expect("세션을 읽는다");
+        assert!(restored.recent_files.is_empty());
+    }
+
     // 집행: rust-commands.md#권한-capabilities — 허용 루트는 웹뷰가 선언하지 못한다.
     // 왜: 저장이 아무 경로나 받아 쓰면, 다음 부팅의 load_session이 그것을 허용해
     //     웹뷰가 전역 경로 접근을 얻는다(스코프 강제가 무너진다).
@@ -314,6 +387,7 @@ mod tests {
                     tab(inside.to_str().unwrap()),
                 ],
                 active: Some(1),
+                recent_files: vec![outside.to_string_lossy().into_owned()],
             },
         )
         .unwrap();
@@ -323,6 +397,7 @@ mod tests {
         assert_eq!(restored.tabs.len(), 1);
         assert_eq!(restored.active, Some(0));
         assert!(restored.root_dir.is_none());
+        assert!(restored.recent_files.is_empty());
         assert!(fresh
             .ensure_allowed(&fs::canonicalize(&outside).unwrap())
             .is_err());
diff --git a/apps/desktop/src/shared/ipc/bindings.ts b/apps/desktop/src/shared/ipc/bindings.ts
index b0a5fbb..a200f7f 100644
--- a/apps/desktop/src/shared/ipc/bindings.ts
+++ b/apps/desktop/src/shared/ipc/bindings.ts
@@ -21,6 +21,8 @@ export const commands = {
 	rootDir: string | null,
 	tabs: SessionTab[],
 	active: number | null,
+	/**  옛 세션 파일에는 이 필드가 없다(→ rust-commands.md#세션). */
+	recentFiles?: string[],
 } | null, AppError>(__TAURI_INVOKE("load_session")),
 	saveSession: (session: Session) => typedError<null, AppError>(__TAURI_INVOKE("save_session", { session })),
 };
@@ -67,6 +69,8 @@ export type Session = {
 	rootDir: string | null,
 	tabs: SessionTab[],
 	active: number | null,
+	/**  옛 세션 파일에는 이 필드가 없다(→ rust-commands.md#세션). */
+	recentFiles?: string[],
 };
 
 export type SessionTab = {

From 2f76f03132c057ac163a84c73a42634422428d63 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 01:54:30 +0900
Subject: [PATCH 02/18] =?UTF-8?q?feat(ipc):=20=EC=A0=80=EC=9E=A5=20?=
 =?UTF-8?q?=EB=8B=A4=EC=9D=B4=EC=96=BC=EB=A1=9C=EA=B7=B8=EA=B0=80=20?=
 =?UTF-8?q?=EC=97=B4=EB=A6=B0=20=ED=8F=B4=EB=8D=94=20=EB=A3=A8=ED=8A=B8?=
 =?UTF-8?q?=EC=97=90=EC=84=9C=20=EC=8B=9C=EC=9E=91=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

show_save_dialog에 start_dir를 추가한다. 존재하는 디렉터리면 다이얼로그
시작 위치로 쓰고, 아니면 OS 기본(마지막 사용 위치)이다. 웹뷰는 사이드바
rootDir를 넘기고, 폴더를 열지 않았으면 null이다. 시작 위치는 허용 루트
등록과 무관하다 — 등록은 사용자가 선택한 경로로만 한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/rust-commands.md                 |  5 ++++-
 apps/desktop/src-tauri/src/dialog_commands.rs | 11 +++++++---
 .../features/save-file/model/save-tab.test.ts | 21 +++++++++++++++++++
 .../src/features/save-file/model/save-tab.ts  |  3 +++
 apps/desktop/src/shared/ipc/bindings.ts       |  2 +-
 apps/desktop/src/shared/ipc/index.ts          |  3 ++-
 6 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/.claude/docs/rust-commands.md b/.claude/docs/rust-commands.md
index 03738d3..64eccee 100644
--- a/.claude/docs/rust-commands.md
+++ b/.claude/docs/rust-commands.md
@@ -174,9 +174,12 @@ async fn watch_tree(root: Option<String>) -> Result<(), AppError>;
 async fn show_open_dialog() -> Result<Option<String>, AppError>;
 
 #[tauri::command]
-async fn show_save_dialog(default_name: String) -> Result<Option<String>, AppError>;
+async fn show_save_dialog(default_name: String, start_dir: Option<String>) -> Result<Option<String>, AppError>;
 // 두 다이얼로그 모두 Markdown 필터(.md·.markdown — read_dir 필터와 동일 집합)를 걸고,
 // 취소하면 None을 반환한다. 선택된 경로는 허용 루트로 등록된다(→ 권한)
+// start_dir가 존재하는 디렉터리면 다이얼로그가 거기서 시작한다 — 아니면 OS가 정한 위치에서
+// 연다. 웹뷰는 사이드바 루트를 넘긴다(폴더를 열지 않았으면 None). 시작 위치일 뿐 허용과
+// 무관하다 — 허용 루트 등록은 사용자가 선택한 경로로만 한다
 
 #[tauri::command]
 async fn show_open_folder_dialog() -> Result<Option<String>, AppError>;
diff --git a/apps/desktop/src-tauri/src/dialog_commands.rs b/apps/desktop/src-tauri/src/dialog_commands.rs
index 599768d..9c7bc08 100644
--- a/apps/desktop/src-tauri/src/dialog_commands.rs
+++ b/apps/desktop/src-tauri/src/dialog_commands.rs
@@ -43,13 +43,18 @@ pub async fn show_save_dialog(
     app: AppHandle,
     scope: State<'_, FileScope>,
     default_name: String,
+    start_dir: Option<String>,
 ) -> Result<Option<String>, AppError> {
-    let picked = app
+    let mut dialog = app
         .dialog()
         .file()
         .add_filter("Markdown", MARKDOWN_EXTENSIONS)
-        .set_file_name(&default_name)
-        .blocking_save_file();
+        .set_file_name(&default_name);
+    // 존재하는 디렉터리일 때만 시작 위치로 쓴다(→ rust-commands.md#다이얼로그).
+    if let Some(dir) = start_dir.map(PathBuf::from).filter(|dir| dir.is_dir()) {
+        dialog = dialog.set_directory(dir);
+    }
+    let picked = dialog.blocking_save_file();
     let Some(file_path) = picked else {
         return Ok(None);
     };
diff --git a/apps/desktop/src/features/save-file/model/save-tab.test.ts b/apps/desktop/src/features/save-file/model/save-tab.test.ts
index f7c4b2f..b41262e 100644
--- a/apps/desktop/src/features/save-file/model/save-tab.test.ts
+++ b/apps/desktop/src/features/save-file/model/save-tab.test.ts
@@ -30,6 +30,7 @@ vi.mock("@tauri-apps/plugin-log", () => ({
 }));
 
 import { resetTabTextRegistry, setTabText, useDocumentStore } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
 import type { FileContent } from "@shared/ipc";
 import { IpcError } from "@shared/ipc";
 import { useConfirmStore, useNoticeStore } from "@shared/ui";
@@ -67,6 +68,7 @@ function openTab(path = "/vault/doc.md"): string {
 
 beforeEach(() => {
   useDocumentStore.setState({ tabs: [], activeTabId: null });
+  useWorkspaceStore.setState({ rootDir: null });
   useConflictStore.setState({ conflictTabIds: [] });
   useConfirmStore.setState({ pending: null });
   useNoticeStore.setState({ notices: [] });
@@ -418,4 +420,23 @@ describe("저장 경로 확정과 중복 탭 금지", () => {
       title: "새 문서.md",
     });
   });
+
+  // 집행: rust-commands.md#다이얼로그 — 웹뷰는 사이드바 루트를 시작 위치로 넘긴다.
+  // 왜: 사이드바 루트는 웹뷰만 안다 — 여기서 넘기지 않으면 Rust가 시작 위치로 쓸 수 없다.
+  // 보장: 폴더가 열려 있으면 rootDir가, 아니면 null이 start_dir로 전달된다.
+  // 경계: 존재하지 않는 디렉터리의 무시는 Rust가 맡는다(→ dialog_commands.rs).
+  it("저장 다이얼로그는 열린 폴더 루트를 시작 위치로 넘긴다", async () => {
+    useWorkspaceStore.setState({ rootDir: "/vault" });
+    const untitled = useDocumentStore.getState().addUntitledTab();
+    useDocumentStore.getState().setDirty(untitled, true);
+    showSaveDialog.mockResolvedValueOnce(null);
+
+    await saveTabNow(untitled);
+    expect(showSaveDialog).toHaveBeenCalledWith(expect.any(String), "/vault");
+
+    useWorkspaceStore.setState({ rootDir: null });
+    showSaveDialog.mockResolvedValueOnce(null);
+    await saveTabNow(untitled);
+    expect(showSaveDialog).toHaveBeenLastCalledWith(expect.any(String), null);
+  });
 });
diff --git a/apps/desktop/src/features/save-file/model/save-tab.ts b/apps/desktop/src/features/save-file/model/save-tab.ts
index c989613..3996639 100644
--- a/apps/desktop/src/features/save-file/model/save-tab.ts
+++ b/apps/desktop/src/features/save-file/model/save-tab.ts
@@ -6,6 +6,7 @@ import {
   useDocumentStore,
 } from "@entities/document";
 import type { Tab } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
 import { STRINGS } from "@shared/config";
 import { ipc, isIpcError } from "@shared/ipc";
 import { notifyIpcError, useConfirmStore, useNoticeStore } from "@shared/ui";
@@ -119,6 +120,8 @@ async function performSave(
     try {
       picked = await ipc.showSaveDialog(
         path === null ? STRINGS.untitledDefaultFileName : tab.title,
+        // 폴더가 열려 있으면 다이얼로그가 그 루트에서 시작한다(→ rust-commands.md#다이얼로그).
+        useWorkspaceStore.getState().rootDir,
       );
     } catch (error) {
       notifyIpcError(STRINGS.saveFailedTitle, error);
diff --git a/apps/desktop/src/shared/ipc/bindings.ts b/apps/desktop/src/shared/ipc/bindings.ts
index a200f7f..1fe0512 100644
--- a/apps/desktop/src/shared/ipc/bindings.ts
+++ b/apps/desktop/src/shared/ipc/bindings.ts
@@ -14,7 +14,7 @@ export const commands = {
 	watchPaths: (paths: string[]) => typedError<number, AppError>(__TAURI_INVOKE("watch_paths", { paths })),
 	watchTree: (root: string | null) => typedError<null, AppError>(__TAURI_INVOKE("watch_tree", { root })),
 	showOpenDialog: () => typedError<string | null, AppError>(__TAURI_INVOKE("show_open_dialog")),
-	showSaveDialog: (defaultName: string) => typedError<string | null, AppError>(__TAURI_INVOKE("show_save_dialog", { defaultName })),
+	showSaveDialog: (defaultName: string, startDir: string | null) => typedError<string | null, AppError>(__TAURI_INVOKE("show_save_dialog", { defaultName, startDir })),
 	showOpenFolderDialog: () => typedError<string | null, AppError>(__TAURI_INVOKE("show_open_folder_dialog")),
 	setWindowBlurRadius: (radius: number) => __TAURI_INVOKE<void>("set_window_blur_radius", { radius }),
 	loadSession: () => typedError<{
diff --git a/apps/desktop/src/shared/ipc/index.ts b/apps/desktop/src/shared/ipc/index.ts
index d8931c1..5df92c1 100644
--- a/apps/desktop/src/shared/ipc/index.ts
+++ b/apps/desktop/src/shared/ipc/index.ts
@@ -29,7 +29,8 @@ export const ipc = {
   watchPaths: (paths: string[]) => unwrapIpcResult(commands.watchPaths(paths)),
   watchTree: (root: string | null) => unwrapIpcResult(commands.watchTree(root)),
   showOpenDialog: () => unwrapIpcResult(commands.showOpenDialog()),
-  showSaveDialog: (defaultName: string) => unwrapIpcResult(commands.showSaveDialog(defaultName)),
+  showSaveDialog: (defaultName: string, startDir: string | null) =>
+    unwrapIpcResult(commands.showSaveDialog(defaultName, startDir)),
   showOpenFolderDialog: () => unwrapIpcResult(commands.showOpenFolderDialog()),
   // 결과를 돌려주지 않는다 — 흐림이 걸렸는지는 화면으로만 확인된다(→ design/window-chrome.md#검증).
   setWindowBlurRadius: (radius: number) => commands.setWindowBlurRadius(radius),

From 8445fa7a70cd91322b2fad1033ad224d966c62cd Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 01:59:38 +0900
Subject: [PATCH 03/18] =?UTF-8?q?feat(shared):=20=EC=B5=9C=EA=B7=BC=20?=
 =?UTF-8?q?=ED=8C=8C=EC=9D=BC=20=EB=AA=A9=EB=A1=9D=EC=9D=84=20=EC=84=B8?=
 =?UTF-8?q?=EC=85=98=EA=B3=BC=20=ED=95=A8=EA=BB=98=20=EC=A0=80=EC=9E=A5?=
 =?UTF-8?q?=C2=B7=EB=B3=B5=EC=9B=90=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

workspace 스토어에 recentFiles를 둔다 — 맨 앞 삽입, 중복은 앞으로 이동,
상한 10. 파일 열기(새 탭·기존 탭 합류)와 저장 다이얼로그의 새 경로 확정이
canonical 경로를 올린다. 세션 복원은 저장된 목록을 그대로 세우고 순서를
바꾸지 않는다. 표시(빈 상태 안내)는 다음 커밋이 맡는다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/document-model.md                |  2 +-
 .../src/app/lib/session-storage.test.ts       | 38 ++++++++++++++++++-
 apps/desktop/src/app/lib/session-storage.ts   | 13 ++++++-
 .../workspace/model/workspace-store.test.ts   | 34 ++++++++++++++++-
 .../workspace/model/workspace-store.ts        | 22 +++++++++++
 .../open-file/model/open-file.test.ts         | 21 ++++++++++
 .../src/features/open-file/model/open-file.ts |  5 +++
 .../features/save-file/model/save-tab.test.ts |  4 +-
 .../src/features/save-file/model/save-tab.ts  |  2 +
 apps/desktop/src/shared/config/index.ts       |  1 +
 apps/desktop/src/shared/config/session.ts     |  3 ++
 11 files changed, 139 insertions(+), 6 deletions(-)

diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index d64cd6b..1fcd5f6 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -106,7 +106,7 @@ interface WorkspaceState {
 
 `recentFiles`는 최근에 연 파일의 canonical 경로 목록이다 — 최신이 앞이다.
 
-- **올리는 시점** — 사용자가 파일을 열 때(다이얼로그·트리·최근 파일 목록·프리뷰 링크) · Untitled가 첫 저장으로 경로를 얻을 때. 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
+- **올리는 시점** — 사용자가 파일을 열 때(열기 다이얼로그·파일 트리·최근 파일 목록) · 저장 다이얼로그가 새 경로를 확정할 때(Untitled 첫 저장·다른 이름으로 저장). 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
 - 이미 목록에 있는 경로는 맨 앞으로 옮긴다. **10개**를 넘으면 뒤에서 버린다.
 - 영속화는 `session.json`이다(→ [Rust 커맨드 계약](rust-commands.md#세션)). `load_session`이 지금 없는 경로를 걸러 돌려주고, 남은 경로를 파일 단위 허용 루트로 등록한다 — 재시작 뒤 다이얼로그 없이 다시 여는 근거다.
 - 표시 자리는 빈 상태 안내다(→ [빈 탭](#빈-탭--탭바는-비지-않는다)).
diff --git a/apps/desktop/src/app/lib/session-storage.test.ts b/apps/desktop/src/app/lib/session-storage.test.ts
index ee8da9a..799bfd4 100644
--- a/apps/desktop/src/app/lib/session-storage.test.ts
+++ b/apps/desktop/src/app/lib/session-storage.test.ts
@@ -73,7 +73,7 @@ beforeEach(() => {
   loadSession.mockResolvedValue(null);
   openFile.mockImplementation(async (path: string) => fileContent(path));
   useDocumentStore.setState({ tabs: [], activeTabId: null });
-  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [] });
+  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [], recentFiles: [] });
   resetTabViewStates();
 });
 
@@ -98,10 +98,28 @@ describe("persistSessionOnChange", () => {
       rootDir: "/vault",
       tabs: [{ path: "/vault/a.md", cursorLine: 1, cursorColumn: 1, scrollLine: 1 }],
       active: 0,
+      recentFiles: [],
     });
     stop();
   });
 
+  // 집행: document-model.md#최근-파일 — 영속화는 session.json이다.
+  // 왜: 목록이 세션에 실리지 않으면 재시작 때 비고, 그 경로의 허용 등록 통로도 없다.
+  // 보장: 최근 파일만 바뀌어도 저장되고, 스냅숏에 목록이 담긴다.
+  // 경계: 목록의 삽입·상한 규칙은 workspace-store 테스트 소관.
+  it("최근 파일이 바뀌면 저장한다", async () => {
+    vi.useFakeTimers();
+    const stop = persistSessionOnChange();
+
+    useWorkspaceStore.getState().noteRecentFile("/vault/a.md");
+    await vi.advanceTimersByTimeAsync(SESSION_SAVE_DEBOUNCE_MS);
+
+    expect(saveSession).toHaveBeenCalledWith(
+      expect.objectContaining({ recentFiles: ["/vault/a.md"] }),
+    );
+    stop();
+  });
+
   it("탭별 자리를 함께 담는다", async () => {
     vi.useFakeTimers();
     const stop = persistSessionOnChange();
@@ -185,6 +203,24 @@ describe("restoreSessionWithin", () => {
     expect(useWorkspaceStore.getState().rootDir).toBe("/vault");
   });
 
+  // 집행: document-model.md#최근-파일 — "세션 복원은 목록을 바꾸지 않는다".
+  // 왜: 복원이 탭 열기를 최근으로 치면 재시작마다 목록이 열린 탭 순서로 뒤섞인다.
+  // 보장: 저장된 목록이 순서 그대로 스토어에 서고, 탭 복원이 끼어들지 않는다.
+  //       recentFiles가 없는 세션(옛 형식)은 빈 목록이다.
+  // 경계: 없는 경로의 필터링은 Rust가 한다(→ rust-commands.md#세션).
+  it("최근 파일을 저장된 순서 그대로 세운다 — 탭 복원이 목록을 바꾸지 않는다", async () => {
+    loadSession.mockResolvedValue({
+      rootDir: null,
+      tabs: [{ path: "/vault/b.md", cursorLine: 1, cursorColumn: 1, scrollLine: 1 }],
+      active: 0,
+      recentFiles: ["/vault/a.md", "/vault/b.md"],
+    });
+
+    await restoreSessionWithin();
+
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/vault/a.md", "/vault/b.md"]);
+  });
+
   it("열지 못한 탭은 건너뛰고 활성 탭은 그대로 그 문서를 가리킨다", async () => {
     openFile.mockImplementation(async (path: string) => {
       if (path === "/vault/깨진.md") {
diff --git a/apps/desktop/src/app/lib/session-storage.ts b/apps/desktop/src/app/lib/session-storage.ts
index 15e4b7a..78dfc79 100644
--- a/apps/desktop/src/app/lib/session-storage.ts
+++ b/apps/desktop/src/app/lib/session-storage.ts
@@ -32,6 +32,9 @@ async function restoreSession(): Promise<void> {
   if (!session) {
     return;
   }
+  // 최근 파일은 탭과 독립이라 본문 읽기를 기다리지 않는다. 복원은 목록을 바꾸지 않고
+  // 그대로 세운다(→ document-model.md#최근-파일).
+  useWorkspaceStore.getState().setRecentFiles(session.recentFiles ?? []);
 
   // 본문 읽기는 서로 독립이라 함께 나간다 — 창이 보이기 전이므로 직렬로 읽으면 그만큼 늦다.
   // 탭은 응답 순서가 아니라 저장된 순서로 세운다.
@@ -79,7 +82,7 @@ export async function restoreSessionWithin(timeoutMs = SESSION_RESTORE_TIMEOUT_M
 
 function snapshot(): Session {
   const { tabs, activeTabId } = useDocumentStore.getState();
-  const { rootDir } = useWorkspaceStore.getState();
+  const { rootDir, recentFiles } = useWorkspaceStore.getState();
   const saved = tabs.filter(
     (tab): tab is typeof tab & { filePath: string } => tab.filePath !== null,
   );
@@ -97,6 +100,7 @@ function snapshot(): Session {
       };
     }),
     active: active === -1 ? null : active,
+    recentFiles,
   };
 }
 
@@ -105,7 +109,12 @@ function snapshot(): Session {
  * (→ session-storage.test.ts "타이핑 중에는 쓰지 않는다").
  */
 function structureKey(session: Session): string {
-  return JSON.stringify([session.rootDir, session.active, session.tabs.map((tab) => tab.path)]);
+  return JSON.stringify([
+    session.rootDir,
+    session.active,
+    session.tabs.map((tab) => tab.path),
+    session.recentFiles,
+  ]);
 }
 
 let saveTimer: ReturnType<typeof setTimeout> | null = null;
diff --git a/apps/desktop/src/entities/workspace/model/workspace-store.test.ts b/apps/desktop/src/entities/workspace/model/workspace-store.test.ts
index 0b69440..5c2ae9c 100644
--- a/apps/desktop/src/entities/workspace/model/workspace-store.test.ts
+++ b/apps/desktop/src/entities/workspace/model/workspace-store.test.ts
@@ -13,7 +13,7 @@ function file(path: string): TreeNode {
 }
 
 beforeEach(() => {
-  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [] });
+  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [], recentFiles: [] });
 });
 
 // 집행: document-model.md#파일-트리-사이드바 — "read_dir(한 단계 목록) 결과를 프론트가
@@ -178,3 +178,35 @@ describe("펼침 상태", () => {
     expect(useWorkspaceStore.getState().expandedDirs).toEqual([]);
   });
 });
+
+// 집행: document-model.md#최근-파일 — "맨 앞 삽입, 중복은 앞으로 이동, 10개 초과분은
+//       뒤에서 버린다".
+// 왜: 목록 순서가 최근 여부를 표현한다 — 중복이 남으면 같은 파일이 두 번 표시되고,
+//     순서가 어긋나면 최근이 아닌 파일이 앞에 온다.
+// 보장: noteRecentFile의 삽입·이동·상한, setRecentFiles의 상한.
+// 경계: 어떤 동작이 올리는지(열기·경로 확정)는 feature 테스트가, 영속화는 세션 테스트가 다룬다.
+describe("최근 파일", () => {
+  it("맨 앞에 쌓이고 중복은 앞으로 이동한다", () => {
+    const store = useWorkspaceStore.getState();
+    store.noteRecentFile("/vault/a.md");
+    store.noteRecentFile("/vault/b.md");
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/vault/b.md", "/vault/a.md"]);
+
+    store.noteRecentFile("/vault/a.md");
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/vault/a.md", "/vault/b.md"]);
+  });
+
+  it("상한을 넘으면 가장 오래된 것이 밀려난다", () => {
+    const store = useWorkspaceStore.getState();
+    for (let index = 0; index < 11; index += 1) {
+      store.noteRecentFile(`/vault/${index}.md`);
+    }
+    const list = useWorkspaceStore.getState().recentFiles;
+    expect(list).toHaveLength(10);
+    expect(list[0]).toBe("/vault/10.md");
+    expect(list).not.toContain("/vault/0.md");
+
+    store.setRecentFiles(Array.from({ length: 12 }, (_, index) => `/x/${index}.md`));
+    expect(useWorkspaceStore.getState().recentFiles).toHaveLength(10);
+  });
+});
diff --git a/apps/desktop/src/entities/workspace/model/workspace-store.ts b/apps/desktop/src/entities/workspace/model/workspace-store.ts
index a2b2a8a..56c0c07 100644
--- a/apps/desktop/src/entities/workspace/model/workspace-store.ts
+++ b/apps/desktop/src/entities/workspace/model/workspace-store.ts
@@ -1,5 +1,6 @@
 import { create } from "zustand";
 
+import { RECENT_FILES_LIMIT } from "@shared/config";
 import type { TreeNode } from "@shared/ipc";
 
 // 파일 트리 상태 — 구조: .claude/docs/document-model.md#파일-트리-사이드바,
@@ -16,6 +17,8 @@ interface WorkspaceState {
   fileTree: FileTreeNode[];
   /** 펼쳐진 폴더 경로 — 에디터 표현 상태다. 영속화하지 않는다(→ editor-strategy.md 접힘 영속화와 동일 원칙). */
   expandedDirs: string[];
+  /** 최근에 연 파일 (→ document-model.md#최근-파일). */
+  recentFiles: string[];
 }
 
 interface WorkspaceActions {
@@ -29,6 +32,10 @@ interface WorkspaceActions {
    * (→ document-model.md#파일-트리-사이드바). dirPath가 rootDir이면 루트 레벨을 갱신한다.
    */
   refreshLevel(dirPath: string, entries: TreeNode[]): void;
+  /** 최근 파일에 올린다 — 규칙은 document-model.md#최근-파일. */
+  noteRecentFile(path: string): void;
+  /** 세션 복원 전용 — 목록을 통째로 세운다(→ document-model.md#최근-파일). */
+  setRecentFiles(paths: string[]): void;
 }
 
 export type WorkspaceStore = WorkspaceState & WorkspaceActions;
@@ -112,6 +119,7 @@ export const useWorkspaceStore = create<WorkspaceStore>()((set) => ({
   rootDir: null,
   fileTree: [],
   expandedDirs: [],
+  recentFiles: [],
 
   openRoot(rootDir, entries) {
     set({
@@ -146,6 +154,20 @@ export const useWorkspaceStore = create<WorkspaceStore>()((set) => ({
     });
   },
 
+  noteRecentFile(path) {
+    set((state) => {
+      if (state.recentFiles[0] === path) {
+        return state;
+      }
+      const rest = state.recentFiles.filter((entry) => entry !== path);
+      return { recentFiles: [path, ...rest].slice(0, RECENT_FILES_LIMIT) };
+    });
+  },
+
+  setRecentFiles(paths) {
+    set({ recentFiles: paths.slice(0, RECENT_FILES_LIMIT) });
+  },
+
   setExpanded(dirPath, expanded) {
     set((state) => {
       const isExpanded = state.expandedDirs.includes(dirPath);
diff --git a/apps/desktop/src/features/open-file/model/open-file.test.ts b/apps/desktop/src/features/open-file/model/open-file.test.ts
index 1368eb0..0164de5 100644
--- a/apps/desktop/src/features/open-file/model/open-file.test.ts
+++ b/apps/desktop/src/features/open-file/model/open-file.test.ts
@@ -26,6 +26,7 @@ vi.mock("@tauri-apps/plugin-log", () => ({
 }));
 
 import { getTabText, resetTabTextRegistry, setTabText, useDocumentStore } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
 import type { FileContent } from "@shared/ipc";
 import { IpcError } from "@shared/ipc";
 import { useConfirmStore, useNoticeStore } from "@shared/ui";
@@ -48,6 +49,7 @@ function fileContent(overrides: Partial<FileContent> = {}): FileContent {
 
 beforeEach(() => {
   useDocumentStore.setState({ tabs: [], activeTabId: null });
+  useWorkspaceStore.setState({ recentFiles: [] });
   useConfirmStore.setState({ pending: null });
   useNoticeStore.setState({ notices: [] });
   resetTabTextRegistry();
@@ -74,6 +76,25 @@ describe("openPathInTab", () => {
     expect(tabs.filter((tab) => tab.filePath !== null)).toHaveLength(1);
     expect(activeTabId).toBe(existing);
   });
+
+  // 집행: document-model.md#최근-파일 — 열기가 목록을 올리고, 경로는 canonical 값이다.
+  // 왜: 요청 문자열(별칭 표기)을 올리면 같은 파일이 목록에 두 항목으로 남는다.
+  // 보장: 새로 열기·기존 탭 합류 모두 최근 파일 맨 앞에 올라가고, 값은 열기 결과의 경로다.
+  // 경계: 삽입·이동·상한 규칙은 workspace-store 테스트가, 열기 실패는 목록을 바꾸지 않는
+  //       것을 아래에서 함께 본다.
+  it("열기는 canonical 경로를 최근 파일에 올리고, 실패는 올리지 않는다", async () => {
+    openFile.mockResolvedValueOnce(fileContent({ path: "/private/tmp/doc.md" }));
+    await openPathInTab("/tmp/doc.md");
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/private/tmp/doc.md"]);
+
+    // 이미 열린 파일 — IPC 없이 합류해도 목록은 갱신된다.
+    await openPathInTab("/private/tmp/doc.md");
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/private/tmp/doc.md"]);
+
+    openFile.mockRejectedValueOnce(new IpcError("io", "읽기 실패"));
+    await openPathInTab("/tmp/broken.md");
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/private/tmp/doc.md"]);
+  });
 });
 
 // 집행: file-lifecycle.md#인코딩-정책(수동 재해석) — 배너에서 다른 인코딩으로 다시 연다.
diff --git a/apps/desktop/src/features/open-file/model/open-file.ts b/apps/desktop/src/features/open-file/model/open-file.ts
index 80c8703..dc5f33f 100644
--- a/apps/desktop/src/features/open-file/model/open-file.ts
+++ b/apps/desktop/src/features/open-file/model/open-file.ts
@@ -1,4 +1,5 @@
 import { findTab, setTabText, useDocumentStore } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
 import { STRINGS } from "@shared/config";
 import { ipc } from "@shared/ipc";
 import { notifyIpcError, useConfirmStore } from "@shared/ui";
@@ -35,11 +36,15 @@ export async function openPathInTab(
   const existing = store.tabs.find((tab) => tab.filePath === path);
   if (existing) {
     store.activateTab(existing.id, focusEditor);
+    useWorkspaceStore.getState().noteRecentFile(path);
     return;
   }
   try {
     const file = await ipc.openFile(path);
     useDocumentStore.getState().openFileTab(file, focusEditor);
+    // 최근 파일은 canonical 경로다 — 요청 문자열이 아니라 열기 결과를 올린다
+    // (→ document-model.md#최근-파일).
+    useWorkspaceStore.getState().noteRecentFile(file.path);
   } catch (error) {
     // 바이너리·손상 파일의 열기 거부도 이 경로로 안내된다 — 파일은 건드리지 않았다.
     notifyIpcError(STRINGS.openFailedTitle, error);
diff --git a/apps/desktop/src/features/save-file/model/save-tab.test.ts b/apps/desktop/src/features/save-file/model/save-tab.test.ts
index b41262e..6e6ae34 100644
--- a/apps/desktop/src/features/save-file/model/save-tab.test.ts
+++ b/apps/desktop/src/features/save-file/model/save-tab.test.ts
@@ -68,7 +68,7 @@ function openTab(path = "/vault/doc.md"): string {
 
 beforeEach(() => {
   useDocumentStore.setState({ tabs: [], activeTabId: null });
-  useWorkspaceStore.setState({ rootDir: null });
+  useWorkspaceStore.setState({ rootDir: null, recentFiles: [] });
   useConflictStore.setState({ conflictTabIds: [] });
   useConfirmStore.setState({ pending: null });
   useNoticeStore.setState({ notices: [] });
@@ -419,6 +419,8 @@ describe("저장 경로 확정과 중복 탭 금지", () => {
       filePath: "/private/tmp/새 문서.md",
       title: "새 문서.md",
     });
+    // 경로 확정은 최근 파일에도 올라간다 — 값은 같은 canonical 경로다(→ document-model.md#최근-파일).
+    expect(useWorkspaceStore.getState().recentFiles).toEqual(["/private/tmp/새 문서.md"]);
   });
 
   // 집행: rust-commands.md#다이얼로그 — 웹뷰는 사이드바 루트를 시작 위치로 넘긴다.
diff --git a/apps/desktop/src/features/save-file/model/save-tab.ts b/apps/desktop/src/features/save-file/model/save-tab.ts
index 3996639..85318ca 100644
--- a/apps/desktop/src/features/save-file/model/save-tab.ts
+++ b/apps/desktop/src/features/save-file/model/save-tab.ts
@@ -163,6 +163,8 @@ async function performSave(
     // 탭 신원은 저장이 실제로 쓴 canonical 경로다(→ document-model.md#다중-탭-규칙).
     if (tab.filePath !== result.path) {
       useDocumentStore.getState().assignPath(tabId, result.path);
+      // 이 분기는 다이얼로그가 새 경로를 확정했을 때만 탄다(→ document-model.md#최근-파일).
+      useWorkspaceStore.getState().noteRecentFile(result.path);
     }
     commitSaveSuccess(tabId, tab, text, result.hash);
     return "saved";
diff --git a/apps/desktop/src/shared/config/index.ts b/apps/desktop/src/shared/config/index.ts
index 106b4db..a681897 100644
--- a/apps/desktop/src/shared/config/index.ts
+++ b/apps/desktop/src/shared/config/index.ts
@@ -3,6 +3,7 @@ export { EDITOR_COLORS } from "./editor-colors";
 export { BLUR_RADIUS_DEFAULT, BLUR_RADIUS_MAX, GLASS_OPACITY_DEFAULT } from "./glass";
 export {
   CLOSE_FLUSH_TIMEOUT_MS,
+  RECENT_FILES_LIMIT,
   SESSION_RESTORE_TIMEOUT_MS,
   SESSION_SAVE_DEBOUNCE_MS,
 } from "./session";
diff --git a/apps/desktop/src/shared/config/session.ts b/apps/desktop/src/shared/config/session.ts
index cc8fcdf..bae36ad 100644
--- a/apps/desktop/src/shared/config/session.ts
+++ b/apps/desktop/src/shared/config/session.ts
@@ -8,3 +8,6 @@ export const SESSION_RESTORE_TIMEOUT_MS = 3000;
 
 /** 종료 시 저장 플러시 상한(ms) — 답이 오지 않아도 창은 닫힌다. */
 export const CLOSE_FLUSH_TIMEOUT_MS = 3000;
+
+/** 최근 파일 상한 — 정책은 document-model.md#최근-파일이 소유한다. */
+export const RECENT_FILES_LIMIT = 10;

From 88d8875958c4bd53eb98d6086d6b5525aeda956b Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 02:02:03 +0900
Subject: [PATCH 04/18] =?UTF-8?q?refactor(shared):=20=EA=B2=BD=EB=A1=9C=20?=
 =?UTF-8?q?=EC=9D=B4=EB=A6=84=20=ED=97=AC=ED=8D=BC=202=EB=B2=8C=EC=9D=84?=
 =?UTF-8?q?=20entryNameOf=20=ED=95=98=EB=82=98=EB=A1=9C=20=ED=86=B5?=
 =?UTF-8?q?=ED=95=A9=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

document-store의 fileNameOf와 sidebar의 folderNameOf는 같은 구현이었다.
shared/lib(path-segments)로 옮겨 탭 제목·사이드바 헤더·최근 파일 목록이
같은 규칙으로 이름을 만들게 한다. 백로그의 해당 항목을 지운다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/implementation-plan.md            |  2 +-
 .../entities/document/model/document-store.ts  | 13 ++++---------
 apps/desktop/src/shared/lib/index.ts           |  2 +-
 .../src/shared/lib/path-segments.test.ts       | 18 +++++++++++++++++-
 apps/desktop/src/shared/lib/path-segments.ts   | 10 ++++++++++
 .../desktop/src/widgets/sidebar/ui/sidebar.tsx |  8 ++------
 6 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/.claude/docs/implementation-plan.md b/.claude/docs/implementation-plan.md
index 186b717..ca78bb9 100644
--- a/.claude/docs/implementation-plan.md
+++ b/.claude/docs/implementation-plan.md
@@ -88,7 +88,7 @@ norii의 구현 순서·**구현 상태**와 열린 결정의 단일 출처다.
 
 결정이 아니라 **실행만 남은** 작은 후속 작업을 추적한다 — 결정이 필요하면 위 [열린 결정](#열린-결정-open-decisions)으로, 마일스톤 규모면 [마일스톤](#마일스톤) 표로 간다. 완료하면 줄을 지운다. 항목은 방향만 적는다 — 상세 맥락은 화살표의 소유 문서·코드가 담당한다.
 
-- **중복 정리** — 경로→파일명 헬퍼 2벌(document-store·sidebar)을 `shared/lib`로 통합 · 테스트의 IpcError 목 6곳을 공용 헬퍼로 (→ [프론트엔드 아키텍처](frontend-architecture.md))
+- **중복 정리** — 테스트의 IpcError 목 6곳을 공용 헬퍼로 (→ [프론트엔드 아키텍처](frontend-architecture.md))
 - **들여쓰기 상수화** — 트리 들여쓰기 `12`/`8`px에 이름 부여 — M8 간격 토큰 확정과 함께
 - **이벤트 이름 상수화** — `dir-changed` 등 이벤트명이 Rust·프론트에 문자열로 중복 — 공유 상수 또는 바인딩 생성으로 (→ [Rust 커맨드 계약](rust-commands.md#이벤트-계약-rust--웹뷰))
 - **트리 감시 정리 신호** — 앱 셸 정리 함수가 `watchTree(null)`을 보내지 않는다 — 앱 수명과 같아 실영향 없음, 선언적 교체 계약의 완결용
diff --git a/apps/desktop/src/entities/document/model/document-store.ts b/apps/desktop/src/entities/document/model/document-store.ts
index fb53a33..f132ea1 100644
--- a/apps/desktop/src/entities/document/model/document-store.ts
+++ b/apps/desktop/src/entities/document/model/document-store.ts
@@ -1,6 +1,7 @@
 import { create } from "zustand";
 
 import { STRINGS } from "@shared/config";
+import { entryNameOf } from "@shared/lib";
 import type { FileContent } from "@shared/ipc";
 
 import { clearTabText, setInitialText } from "./text-access";
@@ -48,12 +49,6 @@ interface DocumentActions {
 
 export type DocumentStore = DocumentState & DocumentActions;
 
-function fileNameOf(path: string): string {
-  // Windows canonical 경로(\\?\C:\...)까지 고려해 양쪽 구분자를 다룬다(→ platform-strategy.md).
-  const name = path.split(/[/\\]/).at(-1);
-  return name && name.length > 0 ? name : path;
-}
-
 // 경로 구분자 경계에서만 하위로 친다 — 문자열 접두어로 보면 /vault/묶음2가 /vault/묶음의
 // 하위가 된다.
 function movedPath(filePath: string | null, oldPath: string, newPath: string): string | null {
@@ -87,7 +82,7 @@ export const useDocumentStore = create<DocumentStore>()((set, get) => ({
     const tab: Tab = {
       id,
       filePath: file.path,
-      title: fileNameOf(file.path),
+      title: entryNameOf(file.path),
       isDirty: false,
       sourceEncoding: file.encoding,
       hasBom: file.hasBom,
@@ -178,7 +173,7 @@ export const useDocumentStore = create<DocumentStore>()((set, get) => ({
 
   assignPath(tabId, path) {
     set((state) => ({
-      tabs: updateTab(state.tabs, tabId, { filePath: path, title: fileNameOf(path) }),
+      tabs: updateTab(state.tabs, tabId, { filePath: path, title: entryNameOf(path) }),
     }));
   },
 
@@ -206,7 +201,7 @@ export const useDocumentStore = create<DocumentStore>()((set, get) => ({
           return tab;
         }
         changed = true;
-        return { ...tab, filePath: moved, title: fileNameOf(moved) };
+        return { ...tab, filePath: moved, title: entryNameOf(moved) };
       });
       return changed ? { tabs } : state;
     });
diff --git a/apps/desktop/src/shared/lib/index.ts b/apps/desktop/src/shared/lib/index.ts
index f9dd12e..dfcfd88 100644
--- a/apps/desktop/src/shared/lib/index.ts
+++ b/apps/desktop/src/shared/lib/index.ts
@@ -2,7 +2,7 @@ export { hasWindowGlass, isMac, isPrimaryModifier } from "./platform";
 export { countChars } from "./char-count";
 export { logger } from "./logger";
 export { within } from "./within";
-export { pathSegmentsWithinRoot } from "./path-segments";
+export { entryNameOf, pathSegmentsWithinRoot } from "./path-segments";
 export {
   AA_NON_TEXT,
   AA_TEXT,
diff --git a/apps/desktop/src/shared/lib/path-segments.test.ts b/apps/desktop/src/shared/lib/path-segments.test.ts
index 5613ceb..e563dbd 100644
--- a/apps/desktop/src/shared/lib/path-segments.test.ts
+++ b/apps/desktop/src/shared/lib/path-segments.test.ts
@@ -1,6 +1,22 @@
 import { describe, expect, it } from "vitest";
 
-import { pathSegmentsWithinRoot } from "./path-segments";
+import { entryNameOf, pathSegmentsWithinRoot } from "./path-segments";
+
+// 왜: 탭 제목·사이드바 헤더·최근 파일 목록이 같은 규칙으로 이름을 만들어야 한다 —
+//     따로 구현하면 같은 파일이 자리마다 다른 이름으로 보일 수 있다.
+// 보장: 마지막 구분자 뒤가 이름이고, 양쪽 구분자(/·\)를 다루며, 이름이 비면 경로 그대로다.
+// 경계: 확장자 표시 여부는 사용처가 정한다 — 이 함수는 항목 이름만 만든다.
+describe("경로의 마지막 항목 이름", () => {
+  it("파일명과 폴더명을 돌려준다", () => {
+    expect(entryNameOf("/글/회고/회고.md")).toBe("회고.md");
+    expect(entryNameOf("/글/회고")).toBe("회고");
+    expect(entryNameOf("\\\\?\\C:\\글\\회고.md")).toBe("회고.md");
+  });
+
+  it("이름이 비면 경로 그대로 돌려준다", () => {
+    expect(entryNameOf("/")).toBe("/");
+  });
+});
 
 // 왜: 상태 바의 경로는 "연 폴더 안 어디"만 답한다. 기준이 없거나 맞지 않을 때 다른 규칙으로
 //     답하면 같은 표기가 상황마다 다른 뜻이 된다.
diff --git a/apps/desktop/src/shared/lib/path-segments.ts b/apps/desktop/src/shared/lib/path-segments.ts
index a2ee6d4..38285a7 100644
--- a/apps/desktop/src/shared/lib/path-segments.ts
+++ b/apps/desktop/src/shared/lib/path-segments.ts
@@ -1,3 +1,13 @@
+/**
+ * 경로의 마지막 항목 이름(파일명·폴더명).
+ *
+ * Windows canonical 경로(\\?\C:\...)까지 고려해 양쪽 구분자를 다룬다(→ platform-strategy.md).
+ */
+export function entryNameOf(path: string): string {
+  const name = path.split(/[/\\]/).at(-1);
+  return name && name.length > 0 ? name : path;
+}
+
 /**
  * 연 폴더와 파일 사이의 폴더 이름을 순서대로 돌려준다.
  *
diff --git a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
index 172db1f..81ba925 100644
--- a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
@@ -6,6 +6,7 @@ import { openPathInTab } from "@features/open-file";
 import { openFolderInteractive, toggleDir } from "@features/open-folder";
 import { SettingsButton } from "@features/toggle-settings";
 import { STRINGS } from "@shared/config";
+import { entryNameOf } from "@shared/lib";
 import { Button, FilePlusIcon, FolderPlusIcon, IconButton } from "@shared/ui";
 
 import { openEntryMenu, useContextMenuStore } from "../model/context-menu-store";
@@ -87,11 +88,6 @@ const emptyClass = css({
   textAlign: "center",
 });
 
-function folderNameOf(path: string): string {
-  const name = path.split(/[/\\]/).at(-1);
-  return name && name.length > 0 ? name : path;
-}
-
 // 정지점을 index로 옮기고 포커스한다(범위는 [0, 끝]으로 물린다).
 function focusAt(list: HTMLElement[], index: number): void {
   const el = list[Math.max(0, Math.min(index, list.length - 1))];
@@ -220,7 +216,7 @@ export function Sidebar() {
     <nav className={sidebarClass} aria-label={STRINGS.sidebarTreeLabel} data-testid="sidebar">
       <div className={headerClass}>
         <span className={headerNameClass} title={rootDir}>
-          {folderNameOf(rootDir)}
+          {entryNameOf(rootDir)}
         </span>
         <div className={headerActionsClass}>
           <IconButton

From 600d93e7773392cab4fe43f7c65e89afb685b33b Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 02:06:11 +0900
Subject: [PATCH 05/18] =?UTF-8?q?feat(editor):=20=EB=B9=88=20=EC=83=81?=
 =?UTF-8?q?=ED=83=9C=EB=A5=BC=20=EB=B2=84=ED=8A=BC=EA=B3=BC=20=EC=B5=9C?=
 =?UTF-8?q?=EA=B7=BC=20=ED=8C=8C=EC=9D=BC=20=EB=AA=A9=EB=A1=9D=EC=9C=BC?=
 =?UTF-8?q?=EB=A1=9C=20=EC=B1=84=EC=9A=B4=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

폴더를 열지 않고 앱을 켰을 때 이 화면에서 문서 작업을 시작한다. 폴더
열기 · 파일 열기 · 새 문서 버튼을 이 순서로 두고, 새 문서 버튼은 Cmd+N과
같은 Untitled 길을 탄다. 최근 파일 목록은 파일명으로 표시하고 누르면 그
파일을 연다 — 비면 표시하지 않는다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/document-model.md                |   9 +-
 apps/desktop/src/shared/config/strings.ts     |   7 +-
 .../widgets/editor-pane/ui/editor-pane.tsx    |  21 +--
 .../ui/empty-state.browser.test.tsx           | 132 ++++++++++++++++++
 .../widgets/editor-pane/ui/empty-state.tsx    | 113 +++++++++++++++
 5 files changed, 261 insertions(+), 21 deletions(-)
 create mode 100644 apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
 create mode 100644 apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx

diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index 1fcd5f6..4bedbcd 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -91,7 +91,14 @@ interface WorkspaceState {
 
 ### 빈 탭 — 탭바는 비지 않는다
 
-열린 문서가 하나도 없어도 **탭바는 "새 탭" 하나를 표시한다.** 그 탭의 내용 영역이 곧 빈 상태 안내(새 문서·파일 열기 단축키)이고, 문서를 열면 **그 자리를 새 문서가 차지한다.**
+열린 문서가 하나도 없어도 **탭바는 "새 탭" 하나를 표시한다.** 그 탭의 내용 영역이 곧 빈 상태 안내이고, 문서를 열면 **그 자리를 새 문서가 차지한다.**
+
+빈 상태 안내는 버튼과 최근 파일 목록으로 구성된다.
+
+- **버튼** — 폴더 열기 · 파일 열기 · 새 문서, 이 순서다. 파일 열기·새 문서에는 단축키를 병기한다.
+  - **새 문서 버튼은 `Cmd+N`과 같은 길이다** — 경로 없는 Untitled 탭을 만들고, 경로는 첫 저장 다이얼로그가 정한다(→ [다중 탭 규칙](#다중-탭-규칙)).
+  - 사이드바의 새 파일(실파일 즉시 생성)은 이 화면에 두지 않는다 — 폴더가 없으면 만들 대상 폴더가 없다.
+- **최근 파일 목록** — `recentFiles`(→ [최근 파일](#최근-파일))를 파일명으로 표시하고, 누르면 그 파일을 연다. 목록이 비면 표시하지 않는다.
 
 ```text
 문서 0개    탭바에 "새 탭" 하나(활성·닫기 없음) + 내용 영역에 빈 상태 안내
diff --git a/apps/desktop/src/shared/config/strings.ts b/apps/desktop/src/shared/config/strings.ts
index e144b70..5d066a2 100644
--- a/apps/desktop/src/shared/config/strings.ts
+++ b/apps/desktop/src/shared/config/strings.ts
@@ -12,7 +12,12 @@ export const STRINGS = {
   newTabTitle: "새 탭",
 
   emptyStateTitle: "열린 문서가 없습니다",
-  emptyStateHint: "⌘N 새 문서 · ⌘O 파일 열기",
+  // 버튼·최근 파일 목록의 구성은 document-model.md#빈-탭--탭바는-비지-않는다.
+  emptyStateOpenFileLabel: "파일 열기",
+  emptyStateNewDocLabel: "새 문서",
+  emptyStateOpenFileShortcut: "⌘O",
+  emptyStateNewDocShortcut: "⌘N",
+  recentFilesLabel: "최근 파일",
 
   dirtyIndicatorLabel: "저장 대기",
 
diff --git a/apps/desktop/src/widgets/editor-pane/ui/editor-pane.tsx b/apps/desktop/src/widgets/editor-pane/ui/editor-pane.tsx
index 40333b6..e0cf186 100644
--- a/apps/desktop/src/widgets/editor-pane/ui/editor-pane.tsx
+++ b/apps/desktop/src/widgets/editor-pane/ui/editor-pane.tsx
@@ -6,9 +6,9 @@ import { notifyDocChanged, useDocumentStore } from "@entities/document";
 import { noteDocumentChanged } from "@features/save-file";
 import { publishScroll, subscribeScroll } from "@features/scroll-sync";
 import { useViewModeStore } from "@features/switch-view-mode";
-import { STRINGS } from "@shared/config";
 
 import { createEditorController, type EditorController } from "../model/editor-controller";
+import { EmptyState } from "./empty-state";
 
 // 편집면은 종이다 — 불투명 배경을 **명시적으로** 칠한다. 유리가 켜져 있으므로(창이 투명하다)
 // 캔버스를 비쳐 쓰면 본문 뒤로 바탕화면이 그대로 지나간다(→ decisions/surface · window-chrome.md).
@@ -32,18 +32,6 @@ const hostClass = css({
   },
 });
 
-// 빈 상태(탭 0개)도 종이다 — 여기가 뚫리면 바탕화면 위에 글자가 뜬다.
-const emptyClass = css({
-  flex: 1,
-  display: "flex",
-  flexDirection: "column",
-  alignItems: "center",
-  justifyContent: "center",
-  gap: "3",
-  background: "bg.paper",
-  color: "text.muted",
-});
-
 // 에디터 패널 — 활성 탭의 CM6 뷰를 표시한다. 탭 전환 시 상태를 갈아끼우고,
 // docChanged를 dirty 추적·자동 저장 예약으로 연결한다(→ file-lifecycle.md).
 export function EditorPane() {
@@ -109,12 +97,7 @@ export function EditorPane() {
   );
 
   if (activeTabId === null) {
-    return (
-      <div className={emptyClass} data-testid="empty-state">
-        <strong>{STRINGS.emptyStateTitle}</strong>
-        <span>{STRINGS.emptyStateHint}</span>
-      </div>
-    );
+    return <EmptyState />;
   }
   return <div ref={hostRef} className={hostClass} data-testid="editor-pane" />;
 }
diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
new file mode 100644
index 0000000..7ec46bc
--- /dev/null
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
@@ -0,0 +1,132 @@
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// IPC는 모킹한다 — 대상은 실제 파일·다이얼로그가 아니라 "버튼이 어느 길로 연결되는가"다
+// (다이얼로그·열기의 실제 동작은 Rust 테스트·E2E 소관 → testing.md#레이어별).
+const { openFile, showOpenDialog, showOpenFolderDialog, readDir } = vi.hoisted(() => ({
+  openFile: vi.fn(),
+  showOpenDialog: vi.fn(),
+  showOpenFolderDialog: vi.fn(),
+  readDir: vi.fn(),
+}));
+
+vi.mock("@shared/ipc", () => {
+  class IpcError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string) {
+      super(message);
+      this.name = "IpcError";
+      this.kind = kind;
+    }
+  }
+  return {
+    IpcError,
+    isIpcError: (value: unknown) => value instanceof IpcError,
+    ipc: { openFile, showOpenDialog, showOpenFolderDialog, readDir, watchTree: vi.fn() },
+  };
+});
+vi.mock("@tauri-apps/plugin-log", () => ({
+  error: vi.fn(async () => {}),
+  warn: vi.fn(async () => {}),
+  info: vi.fn(async () => {}),
+}));
+
+import { resetTabTextRegistry, useDocumentStore } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
+import type { FileContent } from "@shared/ipc";
+
+import { EmptyState } from "./empty-state";
+
+function fileContent(path: string): FileContent {
+  return {
+    path,
+    text: "본문",
+    encoding: "utf-8",
+    hasBom: false,
+    eol: "lf",
+    eolMixed: false,
+    hash: "h",
+    mtime: 0,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  useDocumentStore.setState({ tabs: [], activeTabId: null });
+  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [], recentFiles: [] });
+  resetTabTextRegistry();
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+// 집행: document-model.md#빈-탭--탭바는-비지-않는다 — 버튼(폴더 열기가 첫 자리)과
+//       최근 파일 목록.
+// 왜: 폴더 없이 앱을 켜면 이 화면이 뜬다 — 버튼이 동작하지 않으면 새 문서·파일 열기는
+//     단축키로만 가능하다.
+// 보장: 버튼의 존재와 순서, 각 버튼이 규정된 길(다이얼로그·Untitled)로 연결됨.
+// 경계: 다이얼로그 이후의 열기·트리 표시는 open-file·open-folder feature 테스트 소관.
+describe("빈 상태 버튼", () => {
+  it("폴더 열기 · 파일 열기 · 새 문서 순서로 표시한다", () => {
+    const { getByTestId } = render(<EmptyState />);
+    const buttons = [...getByTestId("empty-state").querySelectorAll("button")];
+    expect(buttons.map((button) => button.dataset.testid)).toEqual([
+      "empty-open-folder",
+      "empty-open-file",
+      "empty-new-doc",
+    ]);
+  });
+
+  it("새 문서 버튼은 Cmd+N과 같은 길이다 — 경로 없는 Untitled 탭", () => {
+    const { getByTestId } = render(<EmptyState />);
+    fireEvent.click(getByTestId("empty-new-doc"));
+
+    const { tabs, activeTabId } = useDocumentStore.getState();
+    expect(tabs).toHaveLength(1);
+    expect(tabs[0]).toMatchObject({ filePath: null, title: "Untitled" });
+    expect(activeTabId).toBe(tabs[0]?.id);
+  });
+
+  it("파일 열기·폴더 열기 버튼은 다이얼로그를 연다", async () => {
+    showOpenDialog.mockResolvedValue(null);
+    showOpenFolderDialog.mockResolvedValue(null);
+    const { getByTestId } = render(<EmptyState />);
+
+    fireEvent.click(getByTestId("empty-open-file"));
+    fireEvent.click(getByTestId("empty-open-folder"));
+
+    await waitFor(() => {
+      expect(showOpenDialog).toHaveBeenCalledTimes(1);
+      expect(showOpenFolderDialog).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+// 집행: document-model.md#빈-탭--탭바는-비지-않는다 — "recentFiles를 파일명으로 표시하고,
+//       누르면 그 파일을 연다. 목록이 비면 표시하지 않는다".
+// 왜: 최근 파일을 표시하는 곳은 이 화면뿐이다 — 표시가 없으면 저장·복원(세션)만 있고
+//     쓰는 곳이 없다.
+// 보장: 목록의 파일명 표시(전체 경로는 title), 클릭 → 그 파일이 탭으로 열림, 빈 목록은 미표시.
+// 경계: 목록의 순서·상한은 workspace-store 테스트, 없는 경로의 필터링은 Rust 소관.
+describe("최근 파일 목록", () => {
+  it("파일명으로 표시하고 누르면 그 파일을 연다", async () => {
+    useWorkspaceStore.setState({ recentFiles: ["/vault/notes/회고.md", "/vault/할일.md"] });
+    openFile.mockResolvedValue(fileContent("/vault/notes/회고.md"));
+    const { getByTestId, getByTitle } = render(<EmptyState />);
+
+    const items = [...getByTestId("recent-files").querySelectorAll("button")];
+    expect(items.map((item) => item.textContent)).toEqual(["회고.md", "할일.md"]);
+    expect(getByTitle("/vault/notes/회고.md")).toBeTruthy();
+
+    fireEvent.click(items[0] as HTMLButtonElement);
+    await waitFor(() => {
+      expect(useDocumentStore.getState().tabs[0]?.filePath).toBe("/vault/notes/회고.md");
+    });
+  });
+
+  it("목록이 비면 표시하지 않는다", () => {
+    const { queryByTestId } = render(<EmptyState />);
+    expect(queryByTestId("recent-files")).toBeNull();
+  });
+});
diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
new file mode 100644
index 0000000..05017a7
--- /dev/null
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
@@ -0,0 +1,113 @@
+import { css } from "styled-system/css";
+
+import { useDocumentStore } from "@entities/document";
+import { useWorkspaceStore } from "@entities/workspace";
+import { openFileInteractive, openPathInTab } from "@features/open-file";
+import { openFolderInteractive } from "@features/open-folder";
+import { STRINGS } from "@shared/config";
+import { entryNameOf } from "@shared/lib";
+import { Button } from "@shared/ui";
+
+// 빈 상태(탭 0개) — 구성의 단일 출처: document-model.md#빈-탭--탭바는-비지-않는다.
+
+// 빈 상태도 종이다 — 여기가 뚫리면 바탕화면 위에 글자가 뜬다(→ decisions/surface).
+const emptyClass = css({
+  flex: 1,
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "6",
+  background: "bg.paper",
+  color: "text.muted",
+});
+
+const columnClass = css({
+  display: "flex",
+  flexDirection: "column",
+  gap: "2",
+  width: "60",
+});
+
+// 단축키를 오른쪽 끝에 둔다. 정렬은 안쪽 span이 맡는다 — recipe가 정한 justifyContent를
+// className으로 덮지 않는다(→ button.tsx).
+const actionClass = css({
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  width: "100%",
+});
+
+const shortcutClass = css({ color: "text.muted", fontSize: "xs" });
+
+const recentLabelClass = css({ fontSize: "xs", color: "text.muted" });
+
+const recentListClass = css({
+  display: "flex",
+  flexDirection: "column",
+  listStyle: "none",
+  margin: 0,
+  padding: 0,
+});
+
+// 목록 항목은 파일명만 표시하고 전체 경로는 title로 남긴다. 왼쪽 정렬은 안쪽 span이
+// 맡는다(→ actionClass와 같은 이유).
+const recentItemClass = css({
+  width: "100%",
+  "& span": {
+    width: "100%",
+    textAlign: "left",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+});
+
+export function EmptyState() {
+  const recentFiles = useWorkspaceStore((state) => state.recentFiles);
+  return (
+    <div className={emptyClass} data-testid="empty-state">
+      <strong>{STRINGS.emptyStateTitle}</strong>
+      <div className={columnClass}>
+        <Button data-testid="empty-open-folder" onClick={() => void openFolderInteractive()}>
+          {STRINGS.openFolderButtonLabel}
+        </Button>
+        <Button data-testid="empty-open-file" onClick={() => void openFileInteractive()}>
+          <span className={actionClass}>
+            {STRINGS.emptyStateOpenFileLabel}
+            <kbd className={shortcutClass}>{STRINGS.emptyStateOpenFileShortcut}</kbd>
+          </span>
+        </Button>
+        <Button
+          data-testid="empty-new-doc"
+          onClick={() => useDocumentStore.getState().addUntitledTab()}
+        >
+          <span className={actionClass}>
+            {STRINGS.emptyStateNewDocLabel}
+            <kbd className={shortcutClass}>{STRINGS.emptyStateNewDocShortcut}</kbd>
+          </span>
+        </Button>
+      </div>
+      {recentFiles.length > 0 && (
+        <div className={columnClass}>
+          <span className={recentLabelClass}>{STRINGS.recentFilesLabel}</span>
+          <ul className={recentListClass} data-testid="recent-files">
+            {recentFiles.map((path) => (
+              <li key={path}>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className={recentItemClass}
+                  title={path}
+                  onClick={() => void openPathInTab(path)}
+                >
+                  <span>{entryNameOf(path)}</span>
+                </Button>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

From 4f201a7d040ea81eaecee6c9c880536193f149c3 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Tue, 4 Aug 2026 02:11:10 +0900
Subject: [PATCH 06/18] =?UTF-8?q?test(desktop):=20=EB=B9=88=20=EC=83=81?=
 =?UTF-8?q?=ED=83=9C=20=EB=B2=84=ED=8A=BC=C2=B7=EC=B5=9C=EA=B7=BC=20?=
 =?UTF-8?q?=ED=8C=8C=EC=9D=BC=EC=9D=98=20=EC=8B=A4=EC=95=B1=20E2E=EB=A5=BC?=
 =?UTF-8?q?=20=EC=B6=94=EA=B0=80=ED=95=9C=EB=8B=A4=20(M9=20=EC=99=84?=
 =?UTF-8?q?=EB=A3=8C)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

빈 상태 행동 버튼 셋의 존재·순서, 새 문서 버튼의 Untitled 길(활성 탭
경로 없음), 닫은 파일이 최근 파일 목록에 남고 눌러 다시 열리는 흐름,
세션 파일의 recentFiles 기록을 실앱에서 검증한다(21/21 통과). 파일
열기·폴더 열기 버튼 클릭은 네이티브 다이얼로그라 수동 검증 대상이다.
구현 계획의 M9 상태와 문서 링크를 갱신한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/implementation-plan.md    |  4 +-
 apps/desktop/e2e/file-lifecycle.e2e.ts | 70 ++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/.claude/docs/implementation-plan.md b/.claude/docs/implementation-plan.md
index ca78bb9..b7f137c 100644
--- a/.claude/docs/implementation-plan.md
+++ b/.claude/docs/implementation-plan.md
@@ -17,7 +17,7 @@ norii의 구현 순서·**구현 상태**와 열린 결정의 단일 출처다.
 | M6. 실사용 채우기 | ✅ 완료 | **손으로 쓰는 데 필요한 것들.** **사이드바 파일 조작**(새 파일/폴더 · 이름 변경 · 휴지통 삭제 → [Rust 커맨드 계약](rust-commands.md)) · 사이드바 접근성(ARIA 트리 시맨틱과 키보드 탐색 — 반쪽 ARIA는 없느니만 못하므로 한 세트로) · **한글 IME QA**(→ [한글 IME](korean-ime.md)) · **설정 화면**(테마 선택 · 유리 불투명도 · 흐림 반경)과 설정 저장 · 탭 ⚠ 배지 색 | 트리에서 파일을 만들고 지우고, 고친 설정이 다음 실행에도 남는다 |
 | M7. 상태 유지 | ✅ 완료 | 세션 복원(탭 목록 · 활성 탭 · 루트 폴더 · 탭별 커서와 자리 → [문서 모델](document-model.md#세션-복원)) · 뷰 모드·사이드바 접힘 저장 · 자동 저장 간격(→ [파일 생명주기](file-lifecycle.md#자동-저장)) | 껐다 켜면 열려 있던 탭과 폴더가 읽던 자리로 돌아온다 · 자동 저장 간격을 고르거나 끌 수 있다 |
 | M8. 시각 완성도 | ✅ 완료 | **전체 UI 쇄신** — 창 모서리·배경·크롬(타이틀바·사이드바·탭바·상태바)을 한 벌로 다시 맞춘다 · 타이포·간격 스케일 확정 · 프리뷰 타이포/상호작용 · 스크롤바 전역 스타일 | 화면 전체가 한 벌로 읽히고, 크기와 간격이 한 스케일에서 나온다 |
-| M9. 폴더 없는 상태 | 예정 | **폴더를 열지 않았을 때 새 파일을 만드는 길을 정한다.** 새 파일은 연 폴더 안에 만드는데(→ [문서 모델](document-model.md#파일-트리-사이드바)) 폴더가 없으면 트리도 그 버튼도 없다 — `Cmd+N`이 여는 경로 없는 문서와 이 길의 관계를 정하고, 폴더를 열지 않은 화면에서 새 파일로 가는 길을 만든다 · **최근 파일**(`WorkspaceState.recentFiles`는 [문서 모델](document-model.md#상태-구조)이 규정하나 구현이 없다) — 그 화면에서 다시 열 곳을 보인다 | 폴더를 열지 않고 앱을 켜도 새 문서를 만들어 저장까지 가고, 최근에 연 파일을 그 자리에서 다시 연다 |
+| M9. 폴더 없는 상태 | ✅ 완료 | **폴더를 열지 않았을 때 새 파일을 만드는 길을 정한다.** 새 파일은 연 폴더 안에 만드는데(→ [문서 모델](document-model.md#파일-트리-사이드바)) 폴더가 없으면 트리도 그 버튼도 없다 — `Cmd+N`이 여는 경로 없는 문서와 이 길의 관계를 정하고, 폴더를 열지 않은 화면에서 새 파일로 가는 길을 만든다 · **최근 파일**(`WorkspaceState.recentFiles`는 [문서 모델](document-model.md#상태-구조)이 규정하나 구현이 없다) — 그 화면에서 다시 열 곳을 보인다 | 폴더를 열지 않고 앱을 켜도 새 문서를 만들어 저장까지 가고, 최근에 연 파일을 그 자리에서 다시 연다 |
 | M10. 성능·규모 | 예정 | 대형 폴더 트리 가상화(현재 미도입 → [문서 모델](document-model.md#파일-트리-사이드바)) · 프리뷰 렌더 후속(→ [프리뷰 전략](preview-strategy.md#디바운스)) | 파일이 수천 개인 폴더와 긴 문서에서도 즉시 반응한다 |
 | M11. 배포(mac) | 예정 | 코드 서명·공증 · 자동 업데이트 · 번들 크기 목표 확정 | 배포 가능한 서명된 mac 빌드 |
 | 이후 | — | Windows/Linux 확장 → (필요 시) 모바일 | — |
@@ -41,7 +41,7 @@ norii의 구현 순서·**구현 상태**와 열린 결정의 단일 출처다.
 - M6 → [디자인 시스템 — 테마](design/design-system.md#테마-라이트다크) · [창 표면 계약](design/window-chrome.md) · [파일 생명주기 — 설정 저장](file-lifecycle.md#설정-저장) · [Rust 커맨드 계약](rust-commands.md) · [에디터 전략 — 단축키 계약](editor-strategy.md#단축키-계약) · [한글 IME](korean-ime.md)
 - M7 → [문서 모델 — 세션 복원](document-model.md#세션-복원) · [파일 생명주기 — 자동 저장](file-lifecycle.md#자동-저장)
 - M8 → [타이포](design/decisions/typography.md) · [디자인 시스템](design/design-system.md) · [프리뷰 전략](preview-strategy.md)
-- M9 → [문서 모델 — 파일 트리](document-model.md#파일-트리-사이드바) · [프리뷰 전략 — 디바운스](preview-strategy.md#디바운스)
+- M9 → [문서 모델 — 빈 탭](document-model.md#빈-탭--탭바는-비지-않는다) · [문서 모델 — 최근 파일](document-model.md#최근-파일) · [Rust 커맨드 계약 — 세션·다이얼로그](rust-commands.md#세션)
 - M10 → [플랫폼 전략](platform-strategy.md#배포-경로--app-store는-비목표)
 
 ## 열린 결정 (Open Decisions)
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index ba9bab9..c4bd371 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -193,6 +193,70 @@ it("스모크 — 실제 앱이 뜨고 시작 화면(빈 상태)이 렌더된다
   expect(await emptyState.isExisting()).toBe(true);
 });
 
+// 합성 Cmd+W — 전역 핸들러 경유 탭 닫기(수정자 키 합성 불가 한계와 우회는 파일 머리).
+async function closeActiveTab(): Promise<void> {
+  await browser.execute(() => {
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "w", metaKey: true, bubbles: true, cancelable: true }),
+    );
+    return null;
+  });
+}
+
+// 집행: document-model.md#빈-탭--탭바는-비지-않는다 — 버튼(폴더 열기가 첫 자리),
+//       새 문서 버튼은 Cmd+N과 같은 길(경로 없는 Untitled 탭).
+// 왜: 버튼→feature→스토어 배선이 실앱에서 이어지는지는 여기서만 확인된다(브라우저 테스트는
+//     IPC를 모킹한다).
+// 보장: 버튼의 존재·순서, 새 문서 클릭 → Untitled 탭, 닫으면 빈 상태 복귀.
+// 경계: 파일 열기·폴더 열기 버튼은 네이티브 다이얼로그를 열므로 클릭하지 않는다(수동 검증) —
+//       같은 feature 경로(openFileInteractive·openFolderInteractive)의 다이얼로그 이후는
+//       E2E 훅 시나리오들이 덮는다. 첫 실행(세션 없음)이라 최근 파일 목록은 없어야 한다.
+it("빈 상태 — 버튼이 뜨고 새 문서 버튼이 Untitled 탭을 연다", async () => {
+  const ids = await browser.execute(() =>
+    [...document.querySelectorAll('[data-testid="empty-state"] button')].map(
+      (button) => (button as HTMLElement).dataset.testid ?? "",
+    ),
+  );
+  expect(ids.filter((id) => id.startsWith("empty-"))).toEqual([
+    "empty-open-folder",
+    "empty-open-file",
+    "empty-new-doc",
+  ]);
+  expect(await (await browser.$('[data-testid="recent-files"]')).isExisting()).toBe(false);
+
+  await (await browser.$('[data-testid="empty-new-doc"]')).click();
+  await (await browser.$('[role="tab"]*=Untitled')).waitForExist({ timeout: 5_000 });
+  // 경로 없는 문서다 — 활성 탭 경로가 비어 있어야 한다(실파일 즉시 생성이 아니다).
+  expect(await browser.execute(() => window.noriiE2e?.activeTabPath() ?? null)).toBeNull();
+
+  // 편집 전 Untitled는 확인 없이 닫힌다 — 빈 상태로 돌아온다.
+  await closeActiveTab();
+  await (await browser.$('[data-testid="empty-state"]')).waitForExist({ timeout: 5_000 });
+});
+
+// 집행: document-model.md#최근-파일 — 연 파일이 목록에 올라간다.
+//       document-model.md#빈-탭--탭바는-비지-않는다 — 파일명으로 표시하고 누르면 연다.
+// 왜: 저장(세션)·갱신(스토어)이 각자 옳아도, 빈 상태에서 목록 표시 → 클릭 → 다시 열기의
+//     끝단 배선은 실앱에서만 확인된다.
+// 보장: 파일을 열었다 닫으면 빈 상태에 그 파일명이 뜨고, 누르면 같은 파일이 다시 열린다.
+it("빈 상태 — 닫은 파일이 최근 파일에 남고 누르면 다시 열린다", async () => {
+  const filePath = path.join(SCOPE_ROOT, "recent-데모.md");
+  await writeFile(filePath, "# 최근 파일 데모\n", "utf8");
+
+  await openInApp(filePath);
+  await waitActiveTab(filePath);
+  await closeActiveTab(); // 편집하지 않았다 — 확인 없이 닫힌다.
+
+  await (await browser.$('[data-testid="empty-state"]')).waitForExist({ timeout: 5_000 });
+  // 자손 결합 + 부분 텍스트(`[…] button*=`)는 이 드라이버가 파싱하지 못한다 — 탭이 닫혀
+  // 이 이름은 최근 파일 목록에만 있으므로 버튼 텍스트만으로 잡는다.
+  const item = await browser.$("button*=recent-데모.md");
+  await item.waitForExist({ timeout: 5_000 });
+
+  await item.click();
+  await waitActiveTab(filePath);
+});
+
 // 집행: file-lifecycle.md#자동-저장 — 저장 대기가 생긴 시점부터 고른 간격에 저장한다.
 // 왜: 열기 → 편집 → 자동 저장 → 디스크 반영이 앱의 존재 이유다. 이 왕복이 깨지면 전부 무의미하다.
 // 보장: 실제 Rust 커맨드로 연 파일이 편집 후 자동 저장으로 디스크에 반영되고,
@@ -798,6 +862,12 @@ it("세션 복원 — 다시 띄우면 열려 있던 탭이 돌아온다", async
     },
     { timeout: 10_000, interval: 300, timeoutMsg: "세션 파일에 두 탭이 남지 않았다" },
   );
+  // 최근 파일도 같은 파일에 실린다(→ rust-commands.md#세션 recent_files).
+  {
+    const raw = await readFile(await appConfigFile("session.json"), "utf8");
+    const stored = JSON.parse(raw) as { recentFiles?: string[] };
+    expect(stored.recentFiles?.some((entry) => entry.endsWith("session-b.md"))).toBe(true);
+  }
 
   await browser.execute(() => {
     location.reload();

From 2169474824d66e4b7e88c520bcd7c3698f6e9320 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Thu, 6 Aug 2026 13:49:33 +0900
Subject: [PATCH 07/18] =?UTF-8?q?feat(editor):=20=EB=B9=88=20=EC=83=81?=
 =?UTF-8?q?=ED=83=9C=20=EB=B2=84=ED=8A=BC=EA=B3=BC=20=EB=8B=A8=EC=B6=95?=
 =?UTF-8?q?=ED=82=A4=20=ED=91=9C=EA=B8=B0=EB=A5=BC=20=EB=8B=A4=EB=93=AC?=
 =?UTF-8?q?=EB=8A=94=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

폴더 열기는 accent 버튼 하나로 남기고, 파일 열기·새 문서는 테두리 없는
ghost 행으로 바꾼다 — 이름은 왼쪽, 단축키는 오른쪽의 고정폭 칩이다.
최근 파일 행도 같은 ghost 행이고 카드 폭을 60에서 80으로 넓힌다. 모양을
서술하던 주석은 지우고 기능 제약(투명 창 배경)만 남긴다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../widgets/editor-pane/ui/empty-state.tsx    | 44 ++++++++++++++-----
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
index 05017a7..73dffe1 100644
--- a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
@@ -22,15 +22,17 @@ const emptyClass = css({
   color: "text.muted",
 });
 
+const headingClass = css({ fontSize: "md", fontWeight: "semibold", textAlign: "center" });
+
 const columnClass = css({
   display: "flex",
   flexDirection: "column",
-  gap: "2",
-  width: "60",
+  gap: "1",
+  width: "80",
 });
 
-// 단축키를 오른쪽 끝에 둔다. 정렬은 안쪽 span이 맡는다 — recipe가 정한 justifyContent를
-// className으로 덮지 않는다(→ button.tsx).
+const rowClass = css({ width: "100%" });
+
 const actionClass = css({
   display: "flex",
   alignItems: "center",
@@ -38,20 +40,27 @@ const actionClass = css({
   width: "100%",
 });
 
-const shortcutClass = css({ color: "text.muted", fontSize: "xs" });
+const shortcutClass = css({
+  fontFamily: "editor",
+  fontSize: "xs",
+  color: "text.muted",
+  paddingBlock: "0.5",
+  paddingInline: "1.5",
+  borderRadius: "sm",
+  background: "bg.hover",
+});
 
-const recentLabelClass = css({ fontSize: "xs", color: "text.muted" });
+const recentLabelClass = css({ fontSize: "xs", color: "text.muted", paddingInline: "2" });
 
 const recentListClass = css({
   display: "flex",
   flexDirection: "column",
+  gap: "1",
   listStyle: "none",
   margin: 0,
   padding: 0,
 });
 
-// 목록 항목은 파일명만 표시하고 전체 경로는 title로 남긴다. 왼쪽 정렬은 안쪽 span이
-// 맡는다(→ actionClass와 같은 이유).
 const recentItemClass = css({
   width: "100%",
   "& span": {
@@ -67,18 +76,31 @@ export function EmptyState() {
   const recentFiles = useWorkspaceStore((state) => state.recentFiles);
   return (
     <div className={emptyClass} data-testid="empty-state">
-      <strong>{STRINGS.emptyStateTitle}</strong>
+      <strong className={headingClass}>{STRINGS.emptyStateTitle}</strong>
       <div className={columnClass}>
-        <Button data-testid="empty-open-folder" onClick={() => void openFolderInteractive()}>
+        <Button
+          variant="accent"
+          data-testid="empty-open-folder"
+          onClick={() => void openFolderInteractive()}
+        >
           {STRINGS.openFolderButtonLabel}
         </Button>
-        <Button data-testid="empty-open-file" onClick={() => void openFileInteractive()}>
+        <Button
+          variant="ghost"
+          size="sm"
+          className={rowClass}
+          data-testid="empty-open-file"
+          onClick={() => void openFileInteractive()}
+        >
           <span className={actionClass}>
             {STRINGS.emptyStateOpenFileLabel}
             <kbd className={shortcutClass}>{STRINGS.emptyStateOpenFileShortcut}</kbd>
           </span>
         </Button>
         <Button
+          variant="ghost"
+          size="sm"
+          className={rowClass}
           data-testid="empty-new-doc"
           onClick={() => useDocumentStore.getState().addUntitledTab()}
         >

From 7ce3856498030265daa15b73752d8f74afe35749 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Thu, 6 Aug 2026 14:04:36 +0900
Subject: [PATCH 08/18] =?UTF-8?q?feat(editor):=20=EB=B9=88=20=EC=83=81?=
 =?UTF-8?q?=ED=83=9C=20=EB=8B=A8=EC=B6=95=ED=82=A4=EB=A5=BC=20=ED=82=A4?=
 =?UTF-8?q?=EB=B3=84=20=ED=82=A4=EC=BA=A1=EC=9C=BC=EB=A1=9C=20=ED=91=9C?=
 =?UTF-8?q?=EA=B8=B0=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

단축키를 악센트 배경의 키캡으로 그린다 — 아랫변 테두리만 2px라 눌린
깊이가 생기고, 한 글자가 키캡 하나다(문자열은 STRINGS 그대로, 렌더에서
나눈다). 키마다 최소 폭을 줘 글자가 달라도 크기가 균일하다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../widgets/editor-pane/ui/empty-state.tsx    | 32 +++++++++++++++----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
index 73dffe1..5283b48 100644
--- a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
@@ -40,14 +40,22 @@ const actionClass = css({
   width: "100%",
 });
 
-const shortcutClass = css({
+const shortcutGroupClass = css({ display: "flex", alignItems: "center", gap: "1" });
+
+const shortcutKeyClass = css({
   fontFamily: "editor",
   fontSize: "xs",
-  color: "text.muted",
+  color: "accent.fg",
   paddingBlock: "0.5",
-  paddingInline: "1.5",
+  paddingInline: "1",
+  minWidth: "5",
+  textAlign: "center",
   borderRadius: "sm",
-  background: "bg.hover",
+  background: "accent",
+  borderWidth: "1px",
+  borderStyle: "solid",
+  borderColor: "accent.pressed",
+  borderBottomWidth: "2px",
 });
 
 const recentLabelClass = css({ fontSize: "xs", color: "text.muted", paddingInline: "2" });
@@ -72,6 +80,18 @@ const recentItemClass = css({
   },
 });
 
+function ShortcutKeys({ keys }: { keys: string }) {
+  return (
+    <span className={shortcutGroupClass}>
+      {[...keys].map((key) => (
+        <kbd key={key} className={shortcutKeyClass}>
+          {key}
+        </kbd>
+      ))}
+    </span>
+  );
+}
+
 export function EmptyState() {
   const recentFiles = useWorkspaceStore((state) => state.recentFiles);
   return (
@@ -94,7 +114,7 @@ export function EmptyState() {
         >
           <span className={actionClass}>
             {STRINGS.emptyStateOpenFileLabel}
-            <kbd className={shortcutClass}>{STRINGS.emptyStateOpenFileShortcut}</kbd>
+            <ShortcutKeys keys={STRINGS.emptyStateOpenFileShortcut} />
           </span>
         </Button>
         <Button
@@ -106,7 +126,7 @@ export function EmptyState() {
         >
           <span className={actionClass}>
             {STRINGS.emptyStateNewDocLabel}
-            <kbd className={shortcutClass}>{STRINGS.emptyStateNewDocShortcut}</kbd>
+            <ShortcutKeys keys={STRINGS.emptyStateNewDocShortcut} />
           </span>
         </Button>
       </div>

From 54cd9d7c20c450a0f52b1d7d83814f1902578883 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Thu, 6 Aug 2026 18:10:58 +0900
Subject: [PATCH 09/18] =?UTF-8?q?feat(sidebar):=20=EC=B5=9C=EA=B7=BC=20?=
 =?UTF-8?q?=ED=8C=8C=EC=9D=BC=EC=9D=84=20=EC=82=AC=EC=9D=B4=EB=93=9C?=
 =?UTF-8?q?=EB=B0=94=20=EC=98=81=EC=97=AD=EC=9C=BC=EB=A1=9C=20=EC=98=AE?=
 =?UTF-8?q?=EA=B8=B4=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

사이드바를 파일 트리·최근 파일·설정 영역으로 나눈다. 최근 파일 영역은
헤더로 접고 펼치며, 접으면 헤더만 하단(설정 위)에 남고, 목록이 비면
표시하지 않는다. 목록은 Tab 정지점 하나이고 방향키·Home/End로 항목을
옮긴다(트리와 같은 규칙). 항목 버튼의 포커스 링이 스크롤 면 가장자리에서
잘리지 않게 목록 안쪽 여백을 링보다 넓게 둔다. 빈 상태 화면의 목록은
제거한다 — 표시 자리는 사이드바 한 곳이다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/document-model.md                |  18 ++-
 apps/desktop/e2e/file-lifecycle.e2e.ts        |  22 ++-
 .../ui/empty-state.browser.test.tsx           |  44 -----
 .../widgets/editor-pane/ui/empty-state.tsx    |  47 +-----
 .../sidebar/model/recent-section-store.ts     |  13 ++
 .../sidebar/ui/recent-files-section.tsx       | 152 ++++++++++++++++++
 .../sidebar/ui/sidebar.browser.test.tsx       |  78 ++++++++-
 .../src/widgets/sidebar/ui/sidebar.tsx        |   3 +
 8 files changed, 273 insertions(+), 104 deletions(-)
 create mode 100644 apps/desktop/src/widgets/sidebar/model/recent-section-store.ts
 create mode 100644 apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx

diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index 4bedbcd..40dde64 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -49,6 +49,7 @@ interface WorkspaceState {
 
 ## 파일 트리 (사이드바)
 
+- 사이드바는 위에서부터 **파일 트리 · 최근 파일 · 설정** 영역이다. 최근 파일 영역의 규칙은 [최근 파일](#최근-파일)이 소유한다.
 - 루트 폴더를 열면 Rust `read_dir`가 루트 **한 단계**를 반환하고, 폴더를 펼칠 때마다 그 폴더 한 단계를 다시 읽는다(레벨별 lazy — VS Code와 동일, → [Rust 커맨드 계약](rust-commands.md)).
 - 트리에는 **디렉터리 전부와 `.md`/`.markdown` 파일만** 표시한다. 필터·정렬·숨김·심볼릭 링크의 결정론적 규칙은 [Rust 커맨드 계약](rust-commands.md)의 `read_dir` 반환 규칙을 단일 출처로 둔다.
 - 중첩 폴더 = 중첩 페이지. 접기/펼치기.
@@ -93,12 +94,10 @@ interface WorkspaceState {
 
 열린 문서가 하나도 없어도 **탭바는 "새 탭" 하나를 표시한다.** 그 탭의 내용 영역이 곧 빈 상태 안내이고, 문서를 열면 **그 자리를 새 문서가 차지한다.**
 
-빈 상태 안내는 버튼과 최근 파일 목록으로 구성된다.
+빈 상태 안내는 버튼이다 — 폴더 열기 · 파일 열기 · 새 문서, 이 순서다. 파일 열기·새 문서에는 단축키를 병기한다.
 
-- **버튼** — 폴더 열기 · 파일 열기 · 새 문서, 이 순서다. 파일 열기·새 문서에는 단축키를 병기한다.
-  - **새 문서 버튼은 `Cmd+N`과 같은 길이다** — 경로 없는 Untitled 탭을 만들고, 경로는 첫 저장 다이얼로그가 정한다(→ [다중 탭 규칙](#다중-탭-규칙)).
-  - 사이드바의 새 파일(실파일 즉시 생성)은 이 화면에 두지 않는다 — 폴더가 없으면 만들 대상 폴더가 없다.
-- **최근 파일 목록** — `recentFiles`(→ [최근 파일](#최근-파일))를 파일명으로 표시하고, 누르면 그 파일을 연다. 목록이 비면 표시하지 않는다.
+- **새 문서 버튼은 `Cmd+N`과 같은 길이다** — 경로 없는 Untitled 탭을 만들고, 경로는 첫 저장 다이얼로그가 정한다(→ [다중 탭 규칙](#다중-탭-규칙)).
+- 사이드바의 새 파일(실파일 즉시 생성)은 이 화면에 두지 않는다 — 폴더가 없으면 만들 대상 폴더가 없다.
 
 ```text
 문서 0개    탭바에 "새 탭" 하나(활성·닫기 없음) + 내용 영역에 빈 상태 안내
@@ -116,7 +115,12 @@ interface WorkspaceState {
 - **올리는 시점** — 사용자가 파일을 열 때(열기 다이얼로그·파일 트리·최근 파일 목록) · 저장 다이얼로그가 새 경로를 확정할 때(Untitled 첫 저장·다른 이름으로 저장). 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
 - 이미 목록에 있는 경로는 맨 앞으로 옮긴다. **10개**를 넘으면 뒤에서 버린다.
 - 영속화는 `session.json`이다(→ [Rust 커맨드 계약](rust-commands.md#세션)). `load_session`이 지금 없는 경로를 걸러 돌려주고, 남은 경로를 파일 단위 허용 루트로 등록한다 — 재시작 뒤 다이얼로그 없이 다시 여는 근거다.
-- 표시 자리는 빈 상태 안내다(→ [빈 탭](#빈-탭--탭바는-비지-않는다)).
+
+표시 자리는 사이드바의 최근 파일 영역이다(→ [파일 트리](#파일-트리-사이드바)).
+
+- 파일명으로 표시하고, 누르면 그 파일을 연다. 목록이 비면 영역을 표시하지 않는다. 폴더를 열지 않아도 표시된다.
+- 헤더로 접고 펼친다. 접으면 헤더만 하단(설정 영역 위)에 남는다. 접힘은 영속화하지 않는다(트리 펼침과 동일 원칙).
+- 목록은 **하나의 Tab 정지점**이다(roving tabindex) — `↑↓`·`Home`/`End`로 항목을 옮기고 `Enter`로 연다.
 
 ## 세션 복원
 
@@ -131,7 +135,7 @@ interface WorkspaceState {
 **탭 경로가 Rust 파일에 사는 이유는 경로 스코프다**(→ [Rust 커맨드 계약 — 권한](rust-commands.md#권한-capabilities)). 세 자리 모두 `.md`가 아니라 앱 config다(→ [파일 생명주기 정책](file-lifecycle.md#앱-상태는-md에-넣지-않는다)).
 
 ```text
-쓰는 시점    탭·루트가 바뀔 때 디바운스 + 창을 닫기 전(→ file-lifecycle.md#종료-방어)
+쓰는 시점    탭·루트·최근 파일이 바뀔 때 디바운스 + 창을 닫기 전(→ file-lifecycle.md#종료-방어)
 읽는 시점    창을 보이기 전(→ design/window-chrome.md#부팅-순서--창은-언제-보이는가)
 빠지는 것    트리 펼침 상태 · 세션 파일이 걸러내는 것들(→ rust-commands.md#세션)
 활성 탭      저장된 활성 탭이 걸러졌으면 남은 첫 탭을 활성으로 만든다
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index c4bd371..a4470ff 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -235,11 +235,12 @@ it("빈 상태 — 버튼이 뜨고 새 문서 버튼이 Untitled 탭을 연다"
 });
 
 // 집행: document-model.md#최근-파일 — 연 파일이 목록에 올라간다.
-//       document-model.md#빈-탭--탭바는-비지-않는다 — 파일명으로 표시하고 누르면 연다.
-// 왜: 저장(세션)·갱신(스토어)이 각자 옳아도, 빈 상태에서 목록 표시 → 클릭 → 다시 열기의
+//       표시·클릭 열기 규칙도 같은 절이 소유한다.
+// 왜: 저장(세션)·갱신(스토어)이 각자 옳아도, 목록 표시 → 클릭 → 다시 열기의
 //     끝단 배선은 실앱에서만 확인된다.
-// 보장: 파일을 열었다 닫으면 빈 상태에 그 파일명이 뜨고, 누르면 같은 파일이 다시 열린다.
-it("빈 상태 — 닫은 파일이 최근 파일에 남고 누르면 다시 열린다", async () => {
+// 보장: 파일을 열었다 닫으면 사이드바 최근 파일 영역에 그 파일명이 뜨고, 누르면 같은
+//       파일이 다시 열린다.
+it("최근 파일 — 닫은 파일이 사이드바 목록에 남고 누르면 다시 열린다", async () => {
   const filePath = path.join(SCOPE_ROOT, "recent-데모.md");
   await writeFile(filePath, "# 최근 파일 데모\n", "utf8");
 
@@ -247,13 +248,22 @@ it("빈 상태 — 닫은 파일이 최근 파일에 남고 누르면 다시 열
   await waitActiveTab(filePath);
   await closeActiveTab(); // 편집하지 않았다 — 확인 없이 닫힌다.
 
-  await (await browser.$('[data-testid="empty-state"]')).waitForExist({ timeout: 5_000 });
+  await (await browser.$('[data-testid="recent-files"]')).waitForExist({ timeout: 5_000 });
   // 자손 결합 + 부분 텍스트(`[…] button*=`)는 이 드라이버가 파싱하지 못한다 — 탭이 닫혀
   // 이 이름은 최근 파일 목록에만 있으므로 버튼 텍스트만으로 잡는다.
   const item = await browser.$("button*=recent-데모.md");
   await item.waitForExist({ timeout: 5_000 });
 
-  await item.click();
+  // 합성 클릭 — 위 새 문서 버튼과 같은 우회(→ testing.md#성숙도-주의).
+  await browser.execute(() => {
+    const buttons = [...document.querySelectorAll('[data-testid="recent-files"] button')];
+    (
+      buttons.find((b) => b.textContent?.includes("recent-데모.md")) as
+        | HTMLButtonElement
+        | undefined
+    )?.click();
+    return null;
+  });
   await waitActiveTab(filePath);
 });
 
diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
index 7ec46bc..b5aa7a4 100644
--- a/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.browser.test.tsx
@@ -32,28 +32,12 @@ vi.mock("@tauri-apps/plugin-log", () => ({
 }));
 
 import { resetTabTextRegistry, useDocumentStore } from "@entities/document";
-import { useWorkspaceStore } from "@entities/workspace";
-import type { FileContent } from "@shared/ipc";
 
 import { EmptyState } from "./empty-state";
 
-function fileContent(path: string): FileContent {
-  return {
-    path,
-    text: "본문",
-    encoding: "utf-8",
-    hasBom: false,
-    eol: "lf",
-    eolMixed: false,
-    hash: "h",
-    mtime: 0,
-  };
-}
-
 beforeEach(() => {
   vi.clearAllMocks();
   useDocumentStore.setState({ tabs: [], activeTabId: null });
-  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [], recentFiles: [] });
   resetTabTextRegistry();
 });
 
@@ -102,31 +86,3 @@ describe("빈 상태 버튼", () => {
     });
   });
 });
-
-// 집행: document-model.md#빈-탭--탭바는-비지-않는다 — "recentFiles를 파일명으로 표시하고,
-//       누르면 그 파일을 연다. 목록이 비면 표시하지 않는다".
-// 왜: 최근 파일을 표시하는 곳은 이 화면뿐이다 — 표시가 없으면 저장·복원(세션)만 있고
-//     쓰는 곳이 없다.
-// 보장: 목록의 파일명 표시(전체 경로는 title), 클릭 → 그 파일이 탭으로 열림, 빈 목록은 미표시.
-// 경계: 목록의 순서·상한은 workspace-store 테스트, 없는 경로의 필터링은 Rust 소관.
-describe("최근 파일 목록", () => {
-  it("파일명으로 표시하고 누르면 그 파일을 연다", async () => {
-    useWorkspaceStore.setState({ recentFiles: ["/vault/notes/회고.md", "/vault/할일.md"] });
-    openFile.mockResolvedValue(fileContent("/vault/notes/회고.md"));
-    const { getByTestId, getByTitle } = render(<EmptyState />);
-
-    const items = [...getByTestId("recent-files").querySelectorAll("button")];
-    expect(items.map((item) => item.textContent)).toEqual(["회고.md", "할일.md"]);
-    expect(getByTitle("/vault/notes/회고.md")).toBeTruthy();
-
-    fireEvent.click(items[0] as HTMLButtonElement);
-    await waitFor(() => {
-      expect(useDocumentStore.getState().tabs[0]?.filePath).toBe("/vault/notes/회고.md");
-    });
-  });
-
-  it("목록이 비면 표시하지 않는다", () => {
-    const { queryByTestId } = render(<EmptyState />);
-    expect(queryByTestId("recent-files")).toBeNull();
-  });
-});
diff --git a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
index 5283b48..ba1256f 100644
--- a/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
+++ b/apps/desktop/src/widgets/editor-pane/ui/empty-state.tsx
@@ -1,11 +1,9 @@
 import { css } from "styled-system/css";
 
 import { useDocumentStore } from "@entities/document";
-import { useWorkspaceStore } from "@entities/workspace";
-import { openFileInteractive, openPathInTab } from "@features/open-file";
+import { openFileInteractive } from "@features/open-file";
 import { openFolderInteractive } from "@features/open-folder";
 import { STRINGS } from "@shared/config";
-import { entryNameOf } from "@shared/lib";
 import { Button } from "@shared/ui";
 
 // 빈 상태(탭 0개) — 구성의 단일 출처: document-model.md#빈-탭--탭바는-비지-않는다.
@@ -58,28 +56,6 @@ const shortcutKeyClass = css({
   borderBottomWidth: "2px",
 });
 
-const recentLabelClass = css({ fontSize: "xs", color: "text.muted", paddingInline: "2" });
-
-const recentListClass = css({
-  display: "flex",
-  flexDirection: "column",
-  gap: "1",
-  listStyle: "none",
-  margin: 0,
-  padding: 0,
-});
-
-const recentItemClass = css({
-  width: "100%",
-  "& span": {
-    width: "100%",
-    textAlign: "left",
-    overflow: "hidden",
-    textOverflow: "ellipsis",
-    whiteSpace: "nowrap",
-  },
-});
-
 function ShortcutKeys({ keys }: { keys: string }) {
   return (
     <span className={shortcutGroupClass}>
@@ -93,7 +69,6 @@ function ShortcutKeys({ keys }: { keys: string }) {
 }
 
 export function EmptyState() {
-  const recentFiles = useWorkspaceStore((state) => state.recentFiles);
   return (
     <div className={emptyClass} data-testid="empty-state">
       <strong className={headingClass}>{STRINGS.emptyStateTitle}</strong>
@@ -130,26 +105,6 @@ export function EmptyState() {
           </span>
         </Button>
       </div>
-      {recentFiles.length > 0 && (
-        <div className={columnClass}>
-          <span className={recentLabelClass}>{STRINGS.recentFilesLabel}</span>
-          <ul className={recentListClass} data-testid="recent-files">
-            {recentFiles.map((path) => (
-              <li key={path}>
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  className={recentItemClass}
-                  title={path}
-                  onClick={() => void openPathInTab(path)}
-                >
-                  <span>{entryNameOf(path)}</span>
-                </Button>
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
     </div>
   );
 }
diff --git a/apps/desktop/src/widgets/sidebar/model/recent-section-store.ts b/apps/desktop/src/widgets/sidebar/model/recent-section-store.ts
new file mode 100644
index 0000000..1e5e35c
--- /dev/null
+++ b/apps/desktop/src/widgets/sidebar/model/recent-section-store.ts
@@ -0,0 +1,13 @@
+import { create } from "zustand";
+
+// 접힘은 영속화하지 않는다(→ document-model.md#최근-파일).
+
+interface RecentSectionState {
+  collapsed: boolean;
+}
+
+export const useRecentSectionStore = create<RecentSectionState>()(() => ({ collapsed: false }));
+
+export function toggleRecentSection(): void {
+  useRecentSectionStore.setState((state) => ({ collapsed: !state.collapsed }));
+}
diff --git a/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx b/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx
new file mode 100644
index 0000000..f2b3be4
--- /dev/null
+++ b/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx
@@ -0,0 +1,152 @@
+import { useRef, useState } from "react";
+import { css } from "styled-system/css";
+
+import { useWorkspaceStore } from "@entities/workspace";
+import { openPathInTab } from "@features/open-file";
+import { STRINGS } from "@shared/config";
+import { entryNameOf } from "@shared/lib";
+import { Button, ChevronRightIcon } from "@shared/ui";
+
+import { toggleRecentSection, useRecentSectionStore } from "../model/recent-section-store";
+
+// 최근 파일 영역 — 규칙의 단일 출처: document-model.md#최근-파일.
+
+const sectionClass = css({
+  flexShrink: 0,
+  display: "flex",
+  flexDirection: "column",
+  minHeight: 0,
+  borderTopWidth: "1px",
+  borderTopStyle: "solid",
+  borderTopColor: "border",
+});
+
+const headerClass = css({
+  display: "flex",
+  alignItems: "center",
+  gap: "1",
+  width: "100%",
+  paddingX: "2",
+  height: "8",
+  flexShrink: 0,
+  border: "none",
+  background: "transparent",
+  fontSize: "xs",
+  color: "text.muted",
+  cursor: "pointer",
+  layerStyle: "focusInside",
+  _hover: { color: "text" },
+});
+
+const chevronClass = css({
+  flexShrink: 0,
+  width: "3.5",
+  height: "3.5",
+  transitionProperty: "transform",
+  transitionDuration: "fast",
+  '[aria-expanded="true"] > &': { transform: "rotate(90deg)" },
+});
+
+// 안쪽 여백은 포커스 링의 자리다 — overflow가 잘라내는 면이라 여백이 바깥 링보다
+// 좁으면 링이 가장자리에서 잘린다(링 크기 → panda.config layerStyles).
+const listClass = css({
+  margin: 0,
+  padding: "1.5",
+  listStyle: "none",
+  overflowY: "auto",
+});
+
+const itemClass = css({
+  width: "100%",
+  "& span": {
+    width: "100%",
+    textAlign: "left",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+});
+
+export function RecentFilesSection() {
+  const recentFiles = useWorkspaceStore((state) => state.recentFiles);
+  const collapsed = useRecentSectionStore((state) => state.collapsed);
+  const listRef = useRef<HTMLUListElement>(null);
+  const [current, setCurrent] = useState<string | null>(null);
+  if (recentFiles.length === 0) {
+    return null;
+  }
+  const stopPath = current !== null && recentFiles.includes(current) ? current : recentFiles[0];
+
+  // 키보드 탐색 규칙 → document-model.md#최근-파일.
+  // Enter 활성화는 버튼 기본 동작이라 여기 없다.
+  function onListKeyDown(event: React.KeyboardEvent): void {
+    const buttons = [...(listRef.current?.querySelectorAll<HTMLElement>("button") ?? [])];
+    if (buttons.length === 0) {
+      return;
+    }
+    const index = buttons.findIndex((button) => button === document.activeElement);
+    let next: number;
+    switch (event.key) {
+      case "ArrowDown":
+        next = Math.min(index + 1, buttons.length - 1);
+        break;
+      case "ArrowUp":
+        next = Math.max(index - 1, 0);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = buttons.length - 1;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    const target = buttons[next];
+    if (target) {
+      setCurrent(target.dataset.path ?? null);
+      target.focus();
+    }
+  }
+
+  return (
+    <section className={sectionClass} data-testid="recent-files-section">
+      <button
+        type="button"
+        className={headerClass}
+        aria-expanded={!collapsed}
+        data-testid="recent-files-toggle"
+        onClick={toggleRecentSection}
+      >
+        <ChevronRightIcon className={chevronClass} />
+        {STRINGS.recentFilesLabel}
+      </button>
+      {!collapsed && (
+        <ul
+          ref={listRef}
+          className={listClass}
+          data-testid="recent-files"
+          onKeyDown={onListKeyDown}
+        >
+          {recentFiles.map((path) => (
+            <li key={path}>
+              <Button
+                variant="ghost"
+                size="sm"
+                className={itemClass}
+                title={path}
+                data-path={path}
+                tabIndex={path === stopPath ? 0 : -1}
+                onFocus={() => setCurrent(path)}
+                onClick={() => void openPathInTab(path)}
+              >
+                <span>{entryNameOf(path)}</span>
+              </Button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
diff --git a/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx b/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
index af8b880..5efa4a2 100644
--- a/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
@@ -50,6 +50,7 @@ import type { FileContent, TreeNode } from "@shared/ipc";
 import { useConfirmStore } from "@shared/ui";
 
 import { useEntryEditStore } from "../model/entry-edit-store";
+import { useRecentSectionStore } from "../model/recent-section-store";
 import { resetTreeNav } from "../model/tree-nav-store";
 import { Sidebar } from "../index";
 
@@ -86,7 +87,8 @@ function fileContent(path: string): FileContent {
 }
 
 beforeEach(() => {
-  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [] });
+  useWorkspaceStore.setState({ rootDir: null, fileTree: [], expandedDirs: [], recentFiles: [] });
+  useRecentSectionStore.setState({ collapsed: false });
   useDocumentStore.setState({ tabs: [], activeTabId: null });
   resetTreeNav();
   resetTabTextRegistry();
@@ -456,3 +458,77 @@ describe("Sidebar 컨텍스트 메뉴", () => {
     expect(document.activeElement).toBe(items[1]);
   });
 });
+
+// 집행: document-model.md#최근-파일 — 파일명 표시·클릭 열기·접고 펼치기·
+//       빈 목록 미표시·폴더 없이도 표시.
+// 왜: 이 배선이 끊기면 최근 파일이 세션에 저장만 되고 화면에는 나오지 않는다.
+// 보장: 목록의 파일명 표시(전체 경로는 title), 클릭 → 탭 열림, 헤더 토글로 목록이
+//       숨고 다시 보임, 빈 목록은 영역 미표시, 트리가 있어도 영역이 뜬다.
+// 경계: 목록의 순서·상한은 workspace-store 테스트, 없는 경로의 필터링은 Rust 소관.
+//       접힘의 비영속은 스토어가 세션 저장에 실리지 않는 것으로 성립한다(별도 검증 없음).
+describe("최근 파일 영역", () => {
+  it("파일명으로 표시하고 누르면 그 파일을 연다", async () => {
+    useWorkspaceStore.setState({ recentFiles: ["/vault/notes/회고.md", "/vault/할일.md"] });
+    openFile.mockResolvedValue(fileContent("/vault/notes/회고.md"));
+    const { getByTestId, getByTitle } = render(<Sidebar />);
+
+    const items = [...getByTestId("recent-files").querySelectorAll("button")];
+    expect(items.map((item) => item.textContent)).toEqual(["회고.md", "할일.md"]);
+    expect(getByTitle("/vault/notes/회고.md")).toBeTruthy();
+
+    fireEvent.click(items[0] as HTMLButtonElement);
+    await waitFor(() => {
+      expect(useDocumentStore.getState().tabs[0]?.filePath).toBe("/vault/notes/회고.md");
+    });
+  });
+
+  it("헤더으로 접으면 목록이 숨고 다시 펼치면 돌아온다", () => {
+    useWorkspaceStore.setState({ recentFiles: ["/vault/a.md"] });
+    const { getByTestId, queryByTestId } = render(<Sidebar />);
+
+    const toggle = getByTestId("recent-files-toggle");
+    expect(toggle.getAttribute("aria-expanded")).toBe("true");
+
+    fireEvent.click(toggle);
+    expect(queryByTestId("recent-files")).toBeNull();
+    expect(getByTestId("recent-files-toggle").getAttribute("aria-expanded")).toBe("false");
+
+    fireEvent.click(getByTestId("recent-files-toggle"));
+    expect(queryByTestId("recent-files")).not.toBeNull();
+  });
+
+  // 집행: document-model.md#최근-파일 — "목록은 하나의 Tab 정지점이다(roving
+  //       tabindex) — ↑↓·Home/End로 항목을 옮기고 Enter로 연다".
+  // 왜: 항목마다 Tab 정지점이면 목록이 찰수록 트리(1 정지점)를 지나 설정까지 가는 Tab 횟수가
+  //     늘고, 바로 위 트리와 탐색 방식이 어긋난다.
+  // 보장: 정지점은 하나뿐이고 방향키·Home/End가 포커스를 옮긴다.
+  // 경계: Enter 활성화는 버튼 기본 동작(브라우저 소관)이라 클릭 테스트가 같은 경로를 덮는다.
+  it("목록은 Tab 정지점 하나이고 방향키로 항목을 옮긴다", () => {
+    useWorkspaceStore.setState({ recentFiles: ["/vault/a.md", "/vault/b.md", "/vault/c.md"] });
+    const { getByTestId } = render(<Sidebar />);
+
+    const buttons = [...getByTestId("recent-files").querySelectorAll("button")];
+    expect(buttons.map((button) => button.tabIndex)).toEqual([0, -1, -1]);
+
+    (buttons[0] as HTMLButtonElement).focus();
+    fireEvent.keyDown(buttons[0] as HTMLButtonElement, { key: "ArrowDown" });
+    expect(document.activeElement).toBe(buttons[1]);
+    expect((buttons[1] as HTMLButtonElement).tabIndex).toBe(0); // 정지점이 따라온다.
+
+    fireEvent.keyDown(buttons[1] as HTMLButtonElement, { key: "End" });
+    expect(document.activeElement).toBe(buttons[2]);
+    fireEvent.keyDown(buttons[2] as HTMLButtonElement, { key: "Home" });
+    expect(document.activeElement).toBe(buttons[0]);
+  });
+
+  it("목록이 비면 영역이 없고, 트리가 있어도 영역이 뜬다", () => {
+    const { queryByTestId, rerender, getByTestId } = render(<Sidebar />);
+    expect(queryByTestId("recent-files-section")).toBeNull();
+
+    useWorkspaceStore.getState().openRoot("/vault", [README_FILE]);
+    useWorkspaceStore.setState({ recentFiles: ["/vault/readme.md"] });
+    rerender(<Sidebar />);
+    expect(getByTestId("file-tree")).toBeTruthy();
+    expect(getByTestId("recent-files-section")).toBeTruthy();
+  });
+});
diff --git a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
index 81ba925..c725d3d 100644
--- a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
@@ -14,6 +14,7 @@ import { startCreate, useEntryEditStore } from "../model/entry-edit-store";
 import { EntryContextMenu } from "./entry-context-menu";
 import { setTreeNavCurrent, useTreeNavStore } from "../model/tree-nav-store";
 import { EntryNameInput } from "./entry-name-input";
+import { RecentFilesSection } from "./recent-files-section";
 import { TreeItem } from "./tree-item";
 
 // 사이드바는 유리(크롬)다 — 탭바·상태바와 같은 표면 역할(→ DESIGN.md 표면 표).
@@ -205,6 +206,7 @@ export function Sidebar() {
             {STRINGS.openFolderButtonLabel}
           </Button>
         </div>
+        <RecentFilesSection />
         <div className={footerClass}>
           <SettingsButton />
         </div>
@@ -264,6 +266,7 @@ export function Sidebar() {
         {edit?.mode === "create" && edit.dir === rootDir && <EntryNameInput edit={edit} />}
       </ul>
       {menu !== null && <EntryContextMenu key={menu.target?.path ?? ""} menu={menu} />}
+      <RecentFilesSection />
       <div className={footerClass}>
         <SettingsButton />
       </div>

From 20aed85d29f2f2e45e8e7cce3968c15114e3735a Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Thu, 6 Aug 2026 18:11:37 +0900
Subject: [PATCH 10/18] =?UTF-8?q?test(desktop):=20=EC=8B=A4=EC=95=B1=20E2E?=
 =?UTF-8?q?=EC=9D=98=20=ED=91=9C=EC=8B=9C=20=EB=8B=A8=EC=96=B8=EA=B3=BC=20?=
 =?UTF-8?q?=EB=A6=AC=EB=A1=9C=EB=93=9C=20=EB=8C=80=EA=B8=B0=EB=A5=BC=20?=
 =?UTF-8?q?=EC=95=88=EC=A0=95=ED=99=94=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

isDisplayed()가 긴 시퀀스 중 보이는 요소에 false를 주는 간헐 어긋남을
실측했다(DOM은 정상, 창 최상위·포커스·숨김 상태와 무관). 설정 창의 표시
단언을 DOM(hidden)으로 바꾼다. 세션 복원의 리로드 대기는 리로드 전
화면이 같은 단언을 만족해 그대로 통과하던 것을, 리로드 직전 표식을 심고
표식 없는 새 페이지에서 훅 존재까지 확인하는 방식으로 바꾼다. 두 한계는
testing.md#성숙도-주의가 소유한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/testing.md                |  9 ++++++++-
 apps/desktop/e2e/file-lifecycle.e2e.ts | 28 +++++++++++++++++++++-----
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/.claude/docs/testing.md b/.claude/docs/testing.md
index a0bcb58..10a5a8f 100644
--- a/.claude/docs/testing.md
+++ b/.claude/docs/testing.md
@@ -99,7 +99,14 @@ norii에서 가장 위험하고 고유한 것 — **한글 IME**와 **데이터
 
 ## 성숙도 주의
 
-**확인된 한계·우회(0.2.1 실측)**: 이 플러그인은 WebDriver 키 액션의 **수정자 키(Meta/Ctrl)를 매핑하지 않고**, `browser.keys()`의 일반 텍스트도 CM6에 닿지 않는다(**`element.addValue()`만** insertText로 전달됨). 동작 트리거는 dev 전용 훅(`window.noriiE2e`)·UI 클릭으로 구성한다. **단축키는 핸들러 층까지 E2E로 고정한다** — 앱 전역 핸들러(window keydown capture)가 `isTrusted`를 안 보므로 `browser.execute`로 **합성 `KeyboardEvent`를 디스패치**하면 핸들러+동작이 발동한다(frontmost 불필요 → CI 가능). 실제 OS 키가 그 핸들러로 라우팅되는지(메뉴 가로채기 등)만 수동이다 — `mise run dev`에서 실제 키보드로 [단축키 계약](editor-strategy.md#단축키-계약) 표를 확인한다.
+**확인된 한계·우회(0.2.1 실측)**:
+
+- **수정자 키(Meta/Ctrl)를 매핑하지 않는다.** `browser.keys()`의 일반 텍스트도 CM6에 닿지 않는다 — **`element.addValue()`만** insertText로 전달된다. 동작 트리거는 dev 전용 훅(`window.noriiE2e`)·UI 클릭으로 구성한다.
+- **단축키는 합성 `KeyboardEvent`로 핸들러 층까지 E2E로 고정한다** — 앱 전역 핸들러(window keydown capture)가 `isTrusted`를 안 보므로 `browser.execute` 디스패치로 핸들러+동작이 발동한다(frontmost 불필요 → CI 가능). 실제 OS 키가 그 핸들러로 라우팅되는지(메뉴 가로채기 등)만 수동이다 — `mise run dev`에서 실제 키보드로 [단축키 계약](editor-strategy.md#단축키-계약) 표를 확인한다.
+- **`isDisplayed()`는 간헐적으로 어긋난다.** 긴 시퀀스 중 보이는 요소에 false를 준다 — 설정 다이얼로그에서 재현: DOM은 `open`·`hidden` 아님·정상 좌표인데 false. 창의 최상위·포커스 잃음·숨김 상태와는 무관하다(상태별 반복 질의로 실측). 표시 여부 단언은 `isDisplayed()`가 아니라 DOM(`closest("[hidden]")` 등)으로 한다.
+- **`location.reload()` 뒤에는 새 페이지가 부팅됐음을 표식으로 확인한다.**
+  - 리로드 전 화면이 다음 단언을 이미 만족하면 대기가 리로드 전 페이지에서 통과하고, 이어지는 `execute`가 아직 리로드 중인 페이지에서 돌아 훅(`noriiE2e`)이 없다(실측: 세션 복원 시나리오의 간헐 실패).
+  - 리로드 직전 `window`에 표식을 심고, 표식이 사라진 페이지(= 새 페이지)에서 훅 존재까지 확인한 뒤 다음 단언으로 간다.
 
 **네이티브 층 입력(실측)**: AppleScript System Events의 실제 **키 입력은 WebDriver 웹뷰에 닿지 않지만, 실제 마우스 클릭·드래그와 CGEvent 키는 닿는다.** CGEvent 키는 입력기까지 지나므로 한글 조합도 실제로 만든다 — 손 타이핑과 같은 이벤트 시퀀스를 확인했다(→ [한글 IME](korean-ime.md)). `mise run verify-native`가 실제 입력 + WebDriver/접근성 단언으로 네 가지를 검증한다 — **표준 창 버튼 세로 중앙 정렬**(접근성 좌표), **드래그 불변식**(띠는 창을 끌고 본문은 안 끈다, CGEvent 실제 드래그), **전체화면 토글 클릭**(네이티브 띠 통과), **한글 조합 확정 Enter**(개행 하나 — 실행 전에 입력 소스를 한국어로 둔다). **유리 투과**는 `screencapture`로 캡처는 되나 균일한 바탕화면에서 glass-on/off를 픽셀로 구분하지 못해(통제 배경 필요) 아직 수동이다. 모두 frontmost·화면 좌표에 의존해 **헤드리스 CI가 아니라 로컬 스크립트 검증**이다 — 남은 유리 검증의 형식화는 [네이티브 E2E 열린 결정](implementation-plan.md)이 추적한다. **frontmost가 필요하므로 실행 전 사용자에게 알린다** — 앱을 최상위로 세우고 실제 입력을 보내는 동안 사용자가 마우스·키보드·창을 건드리면 좌표가 어긋나 실패한다. 무엇을·언제 하는지 전달하고 사용자가 화면을 비워둘 수 있게 한 뒤 돌린다.
 
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index a4470ff..dc40395 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -774,14 +774,20 @@ it("설정 창 — 메뉴로 분류를 바꾸고 고른 자동 저장 간격이
   await openSettings.click();
   await (await browser.$('[data-testid="settings-dialog"]')).waitForExist({ timeout: 10_000 });
 
+  // 표시 여부는 isDisplayed()가 아니라 DOM(hidden)으로 본다 — 간헐 어긋남의 우회
+  // (→ testing.md#성숙도-주의).
+  const panelHidden = (testId: string) =>
+    browser.execute(
+      (id: string) => document.querySelector(`[data-testid="${id}"]`)?.closest("[hidden]") !== null,
+      testId,
+    );
+
   // 여는 분류는 일반이다.
-  expect(await (await browser.$('[data-testid="settings-autosave"]')).isDisplayed()).toBe(true);
-  expect(await (await browser.$('[data-testid="settings-theme-system"]')).isDisplayed()).toBe(
-    false,
-  );
+  expect(await panelHidden("settings-autosave")).toBe(false);
+  expect(await panelHidden("settings-theme-system")).toBe(true);
 
   await (await browser.$('[data-testid="settings-nav-appearance"]')).click();
-  expect(await (await browser.$('[data-testid="settings-theme-system"]')).isDisplayed()).toBe(true);
+  expect(await panelHidden("settings-theme-system")).toBe(false);
 
   await (await browser.$('[data-testid="settings-nav-general"]')).click();
   await selectOption("settings-autosave", "30s");
@@ -879,10 +885,22 @@ it("세션 복원 — 다시 띄우면 열려 있던 탭이 돌아온다", async
     expect(stored.recentFiles?.some((entry) => entry.endsWith("session-b.md"))).toBe(true);
   }
 
+  // 리로드 전 화면도 아래 탭 단언을 이미 만족한다 — 표식 없이 기다리면 대기가 옛
+  // 페이지에서 통과하고, 다음 테스트의 execute가 아직 리로드 중인 페이지에서 돌아
+  // noriiE2e가 없다(실측: 간헐 실패, → testing.md#성숙도-주의).
   await browser.execute(() => {
+    (window as Window & { noriiOldPage?: boolean }).noriiOldPage = true;
     location.reload();
     return null;
   });
+  await browser.waitUntil(
+    async () =>
+      browser.execute(
+        () =>
+          !(window as Window & { noriiOldPage?: boolean }).noriiOldPage && Boolean(window.noriiE2e),
+      ),
+    { timeout: 20_000, interval: 500, timeoutMsg: "리로드된 새 페이지가 준비되지 않았다" },
+  );
 
   await browser.waitUntil(
     async () => {

From 27d5d030d536e70bed06fc18cbc919892ff09a97 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sat, 8 Aug 2026 18:09:34 +0900
Subject: [PATCH 11/18] =?UTF-8?q?feat(ds):=20=EC=83=81=ED=83=9C=20?=
 =?UTF-8?q?=EC=83=89=20=EC=A0=84=ED=99=98=EC=9D=84=20=EC=A0=81=EC=9A=A9?=
 =?UTF-8?q?=ED=95=98=EA=B3=A0=20=EB=AA=A8=EC=85=98=20=EA=B2=B0=EC=A0=95=20?=
 =?UTF-8?q?=EA=B8=B0=EB=A1=9D=EC=9D=84=20=EC=B6=94=EA=B0=80=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

버튼·탭의 배경/테두리/글자색에 fast·out 전환을 걸고, 동작 줄이기에서는 전환을 끈다.
적용된 모션의 종류·공통 규칙·예외는 decisions/motion.md가 소유하고 DESIGN.md가 링크한다.
"장식적 모션을 두지 않는다"는 "상태 변화를 설명하는 것만 둔다"와 같은 말이라 삭제한다.
탭 호버 테스트는 전환 도입으로 즉시 단언이 깨져 완료 대기로 바꾼다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/design/decisions/motion.md       | 28 +++++++++++++++++++
 DESIGN.md                                     |  3 +-
 apps/desktop/src/shared/ui/button.tsx         |  4 +++
 .../src/widgets/tab-bar/ui/tab-bar.tsx        |  4 +++
 .../tab-bar/ui/tab-hover.browser.test.tsx     |  7 +++--
 5 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 .claude/docs/design/decisions/motion.md

diff --git a/.claude/docs/design/decisions/motion.md b/.claude/docs/design/decisions/motion.md
new file mode 100644
index 0000000..c18599c
--- /dev/null
+++ b/.claude/docs/design/decisions/motion.md
@@ -0,0 +1,28 @@
+# 모션 — 상태 변화를 설명하는 전환만 둔다
+
+## 지금의 결정
+
+적용된 모션과 방식:
+
+- **상태의 색 전환** — 호버·눌림·선택에서 배경·테두리·글자색을 전환한다.
+- **접기/펼치기의 크기 전환** — 사이드바는 폭, 최근 파일 목록·트리 하위는 grid 행 높이를 전환한다.
+- **접기 셰브론 회전** — 펼침 상태에서 90° 회전한다.
+- **다이얼로그 진입·퇴장** — `dialogIn`·`dialogOut` 키프레임. 값은 `panda.config.ts`가 소유한다.
+
+공통 규칙:
+
+- 지속시간·이징은 토큰 `fast`·`out`만 쓴다.
+- **모든 모션은 `_motionReduce`로 끈다** — OS의 "동작 줄이기"에서는 전환 없이 즉시 상태를 보인다. 누락을 잡는 자동 검사는 없다 — 추가할 때 직접 확인한다.
+- 상호작용이 트리거일 때만 돈다 — 시간·스크롤에 반응해 스스로 도는 모션은 없다(idle 비용 0).
+- 흐림(backdrop-filter)·그림자는 전환하지 않는다(→ [작업 규칙 · 성능](../../../rules/project-rules.md#성능-규칙)).
+
+## 예외 — 그대로 구현하면 깨지는 지점
+
+- **접기/펼치기는 언마운트하지 않는다.** 언마운트하면 전환할 요소가 사라지고, 다시 펼칠 때 트리·목록 상태가 초기화된다. 크기를 0으로 두고 `visibility: hidden`·`aria-hidden`으로 포커스·스크린리더에서 뺀다. 다이얼로그 퇴장도 같다 — 전환이 끝난 뒤 `close()`와 언마운트를 한다.
+- **안쪽 여백은 접힘과 함께 0으로 전환한다** — 여백은 상자의 최소 높이로 남아, 두면 접힌 뒤에도 그만큼 빈 자리가 남는다.
+- **lazy로 읽힌 하위의 첫 펼침은 접힘으로 붙인 뒤 타이머로 펼친다** — 마운트와 펼침이 같은 프레임이면 전환이 시작점 없이 끝 상태로 그려진다. `requestAnimationFrame`이 아니라 타이머인 이유는 [테스트 전략 — 성숙도 주의](../../testing.md#성숙도-주의)가 소유한다.
+
+## 바뀐 것
+
+| 언제       | 무엇이                   | 왜      |
+| ---------- | ------------------------ | ------- |
diff --git a/DESIGN.md b/DESIGN.md
index a9aba9a..a48b56a 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -91,6 +91,8 @@
 
 ## 5. 모션 · 간격 · 모서리
 
+모션의 근거는 [모션](.claude/docs/design/decisions/motion.md)이 갖는다.
+
 **한다**
 
 - 모션은 상태 변화를 설명하는 것만 둔다.
@@ -99,7 +101,6 @@
 
 **하지 않는다**
 
-- 장식적 모션을 두지 않는다.
 - 스크롤하는 면 위에 흐림을 겹치지 않는다(→ [작업 규칙 · 성능](.claude/rules/project-rules.md#성능-규칙)).
 
 ## 6. 문서 지도
diff --git a/apps/desktop/src/shared/ui/button.tsx b/apps/desktop/src/shared/ui/button.tsx
index 7e92d60..37d1033 100644
--- a/apps/desktop/src/shared/ui/button.tsx
+++ b/apps/desktop/src/shared/ui/button.tsx
@@ -15,6 +15,10 @@ export const BUTTON_STYLES = {
     cursor: "pointer",
     whiteSpace: "nowrap",
     layerStyle: "focusOutside",
+    transitionProperty: "background-color, border-color, color",
+    transitionDuration: "fast",
+    transitionTimingFunction: "out",
+    _motionReduce: { transition: "none" },
     _disabled: {
       cursor: "not-allowed",
       background: "bg.hover",
diff --git a/apps/desktop/src/widgets/tab-bar/ui/tab-bar.tsx b/apps/desktop/src/widgets/tab-bar/ui/tab-bar.tsx
index aab85d0..7fe33de 100644
--- a/apps/desktop/src/widgets/tab-bar/ui/tab-bar.tsx
+++ b/apps/desktop/src/widgets/tab-bar/ui/tab-bar.tsx
@@ -46,6 +46,10 @@ const tabClass = css({
   borderColor: "transparent",
   borderRadius: "md",
   layerStyle: "focusInside",
+  transitionProperty: "background-color, border-color, box-shadow",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
   _hover: { background: "bg.hover" },
   '&[aria-selected="true"]': {
     background: "bg.paper",
diff --git a/apps/desktop/src/widgets/tab-bar/ui/tab-hover.browser.test.tsx b/apps/desktop/src/widgets/tab-bar/ui/tab-hover.browser.test.tsx
index 29d7241..0775c2b 100644
--- a/apps/desktop/src/widgets/tab-bar/ui/tab-hover.browser.test.tsx
+++ b/apps/desktop/src/widgets/tab-bar/ui/tab-hover.browser.test.tsx
@@ -1,4 +1,4 @@
-import { cleanup, render } from "@testing-library/react";
+import { cleanup, render, waitFor } from "@testing-library/react";
 import { userEvent } from "vitest/browser";
 import { afterEach, beforeEach, expect, it } from "vitest";
 
@@ -53,5 +53,8 @@ it("비활성 탭은 호버하면 배경이 바뀐다", async () => {
 
   await userEvent.hover(inactive);
 
-  expect(getComputedStyle(inactive).backgroundColor).not.toBe(before);
+  // 배경은 전환된다(→ decisions/motion.md) — 즉시 값이 아니라 전환 완료를 기다린다.
+  await waitFor(() => {
+    expect(getComputedStyle(inactive).backgroundColor).not.toBe(before);
+  });
 });

From c8f30cfec90a10da9e1fdaf53acf797773d08174 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sat, 8 Aug 2026 18:09:47 +0900
Subject: [PATCH 12/18] =?UTF-8?q?feat(sidebar):=20=EC=A0=91=EA=B8=B0=C2=B7?=
 =?UTF-8?q?=ED=8E=BC=EC=B9=98=EA=B8=B0=EC=97=90=20=ED=81=AC=EA=B8=B0=20?=
 =?UTF-8?q?=EC=A0=84=ED=99=98=EC=9D=84=20=EC=A0=81=EC=9A=A9=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

사이드바(폭)·최근 파일·트리 폴더(grid 행)를 언마운트 없이 크기 전환으로 여닫는다.
접힌 쪽은 숨김 상태(aria-hidden·visibility)로 두고 키보드 탐색·Tab 정지점에서 뺀다.
트리 폴더의 첫 펼침은 접힘으로 마운트한 뒤 타이머로 펼친다(예외 근거는 decisions/motion.md).
document-model.md에 접힌 children이 DOM에 남는 렌더 범위를 기록한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/document-model.md                |  2 +-
 .../editor/ui/editor-page.browser.test.tsx    | 19 ++++---
 .../src/pages/editor/ui/editor-page.tsx       |  4 +-
 .../sidebar/ui/recent-files-section.tsx       | 30 +++++++++-
 .../sidebar/ui/sidebar.browser.test.tsx       |  9 +--
 .../src/widgets/sidebar/ui/sidebar.tsx        | 39 +++++++++++--
 .../src/widgets/sidebar/ui/tree-item.tsx      | 55 ++++++++++++++++---
 7 files changed, 127 insertions(+), 31 deletions(-)

diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index 40dde64..c23ea5f 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -67,7 +67,7 @@ interface WorkspaceState {
   - 파일을 만들면 그 파일을 탭으로 연다. 폴더는 열지 않는다.
 - **전체 인덱싱이 아니라 단순 트리 표시**다 — 파일 내용을 읽어 색인하지 않는다. 이 선이 [비목표](../rules/non-goals.md)의 PKM/vault 인덱싱과 norii를 가른다.
 - 호출당 한 단계만 읽으므로 거대 트리에서도 초기 비용이 상수다. 트리 조립과 "아직 안 읽음" 상태는 프론트 모델(`children` 부재)이 담당한다.
-- 펼친 노드는 전부 렌더한다 — 가상화는 현재 두지 않는다.
+- 펼친 노드는 전부 렌더한다. 한 번 읽은 children은 접혀도 DOM에 남는다 — 숨김이라 포커스·키보드 탐색에서 빠진다(이유 → [모션](design/decisions/motion.md)). 가상화는 현재 두지 않는다.
 - **외부 생성/삭제는 폴더 감시가 반영한다.** 루트를 재귀 감시(`watch_tree`)하고, `dir-changed`를 받은 프론트는 **그 폴더를 이미 읽어 둔 경우에만**(children 보유) 그 한 단계를 `read_dir`로 다시 읽어 병합한다 — 안 읽은 폴더는 다음 펼침이 어차피 최신을 읽는다. 병합은 살아남은 폴더의 기존 children·펼침 상태를 경로 기준으로 보존하고(재읽기가 하위 트리를 접어버리지 않게), 사라진 폴더의 펼침 상태는 함께 정리한다(같은 이름으로 재생성되면 접힌 채 시작). 열린 파일의 watch(파일 내용)와 별개 문제다(→ [Rust 커맨드 계약](rust-commands.md) `watch_tree`).
 
 ## 다중 탭 규칙
diff --git a/apps/desktop/src/pages/editor/ui/editor-page.browser.test.tsx b/apps/desktop/src/pages/editor/ui/editor-page.browser.test.tsx
index 4e6a694..fca1391 100644
--- a/apps/desktop/src/pages/editor/ui/editor-page.browser.test.tsx
+++ b/apps/desktop/src/pages/editor/ui/editor-page.browser.test.tsx
@@ -248,25 +248,30 @@ describe("스크롤 동기화 (EditorPage 통합)", () => {
 
 // 집행: document-model.md#파일-트리-사이드바 — 접으면 화면에서 사라진다.
 //
-// 왜: 폭 0이나 숨김 속성으로 구현하면 빈 띠·잔여 테두리가 남는다. 사라짐을 DOM 부재로 못박는다.
-// 보장: 상태바 토글로 접으면 사이드바가 트리에서 사라지고, 다시 누르면 돌아온다.
+// 왜: 사이드바는 접혀도 DOM에서 사라지지 않고 숨김 속성(aria-hidden)으로 감춰진다
+//     (→ decisions/motion.md). 스토어 테스트는 토글이 스토어 값을 바꾸는 것까지만 보므로,
+//     그 값이 사이드바 요소의 숨김 속성으로 이어지는지는 렌더된 화면에서만 확인된다.
+// 보장: 상태바 토글로 접으면 사이드바가 숨김 상태(aria-hidden)가 되고, 다시 누르면 돌아온다.
 // 경계: 단축키(Cmd+B)는 앱 루트의 전역 리스너가 등록하므로 여기 범위가 아니다 —
 //       리스너는 toggleSidebar를 부를 뿐이고 그 전이는 sidebar-store 테스트가 고정한다.
+//       이 파일은 Panda 생성 CSS를 싣지 않아(→ 파일 머리) 접힌 뒤 폭·테두리가 실제로
+//       0이 되는지는 여기서 못 본다 — 그 단언(빈 띠·잔여 테두리 없음)은 실앱 E2E가 한다.
 describe("사이드바 접기 (EditorPage 배선)", () => {
-  it("타이틀 스트립 토글이 사이드바를 없앴다 되돌린다", async () => {
+  it("타이틀 스트립 토글이 사이드바를 숨겼다 되돌린다", async () => {
     useSidebarStore.setState({ visible: true });
-    const { getByTestId, queryByTestId } = render(<EditorPage />);
+    const { getByTestId } = render(<EditorPage />);
 
-    expect(queryByTestId("sidebar")).not.toBeNull();
+    const sidebar = getByTestId("sidebar");
+    expect(sidebar.getAttribute("aria-hidden")).toBe("false");
 
     fireEvent.click(getByTestId("sidebar-toggle"));
     await waitFor(() => {
-      expect(queryByTestId("sidebar")).toBeNull();
+      expect(sidebar.getAttribute("aria-hidden")).toBe("true");
     });
 
     fireEvent.click(getByTestId("sidebar-toggle"));
     await waitFor(() => {
-      expect(queryByTestId("sidebar")).not.toBeNull();
+      expect(sidebar.getAttribute("aria-hidden")).toBe("false");
     });
   });
 });
diff --git a/apps/desktop/src/pages/editor/ui/editor-page.tsx b/apps/desktop/src/pages/editor/ui/editor-page.tsx
index 21a0345..523f024 100644
--- a/apps/desktop/src/pages/editor/ui/editor-page.tsx
+++ b/apps/desktop/src/pages/editor/ui/editor-page.tsx
@@ -3,7 +3,6 @@ import { css } from "styled-system/css";
 import { useDocumentStore } from "@entities/document";
 import { ConflictBanner, MissingFileBanner } from "@features/save-file";
 import { useViewModeStore } from "@features/switch-view-mode";
-import { useSidebarStore } from "@features/toggle-sidebar";
 import { ConfirmDialog, NoticeBanner } from "@shared/ui";
 import { EditorPane } from "@widgets/editor-pane";
 import { NormalizationBanner } from "@widgets/normalization-banner";
@@ -55,12 +54,11 @@ export function EditorPage() {
   const mode = useViewModeStore((state) => state.mode);
   // 탭이 없으면 모드를 무시하고 빈 상태만 보인다(→ preview-strategy.md#뷰-모드).
   const hasTab = useDocumentStore((state) => state.activeTabId !== null);
-  const sidebarVisible = useSidebarStore((state) => state.visible);
   return (
     <div className={pageClass}>
       <TitleStrip />
       <div className={splitClass}>
-        {sidebarVisible && <Sidebar />}
+        <Sidebar />
         <div className={documentClass}>
           <TabBar />
           <NoticeBanner />
diff --git a/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx b/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx
index f2b3be4..5d1b6be 100644
--- a/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/recent-files-section.tsx
@@ -35,6 +35,10 @@ const headerClass = css({
   color: "text.muted",
   cursor: "pointer",
   layerStyle: "focusInside",
+  transitionProperty: "color",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
   _hover: { color: "text" },
 });
 
@@ -44,16 +48,38 @@ const chevronClass = css({
   height: "3.5",
   transitionProperty: "transform",
   transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
   '[aria-expanded="true"] > &': { transform: "rotate(90deg)" },
 });
 
+// 접기/펼치기 전환 규칙 → decisions/motion.md.
+const collapseClass = css({
+  display: "grid",
+  gridTemplateRows: "1fr",
+  minHeight: 0,
+  overflow: "hidden",
+  transitionProperty: "grid-template-rows, visibility",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
+  '&[data-collapsed="true"]': { gridTemplateRows: "0fr", visibility: "hidden" },
+});
+
 // 안쪽 여백은 포커스 링의 자리다 — overflow가 잘라내는 면이라 여백이 바깥 링보다
 // 좁으면 링이 가장자리에서 잘린다(링 크기 → panda.config layerStyles).
+// 여백은 상자의 최소 높이로 남는다(→ decisions/motion.md).
 const listClass = css({
   margin: 0,
   padding: "1.5",
   listStyle: "none",
+  minHeight: 0,
   overflowY: "auto",
+  transitionProperty: "padding",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
+  '[data-collapsed="true"] > &': { paddingBlock: 0 },
 });
 
 const itemClass = css({
@@ -122,7 +148,7 @@ export function RecentFilesSection() {
         <ChevronRightIcon className={chevronClass} />
         {STRINGS.recentFilesLabel}
       </button>
-      {!collapsed && (
+      <div className={collapseClass} data-collapsed={collapsed} aria-hidden={collapsed}>
         <ul
           ref={listRef}
           className={listClass}
@@ -146,7 +172,7 @@ export function RecentFilesSection() {
             </li>
           ))}
         </ul>
-      )}
+      </div>
     </section>
   );
 }
diff --git a/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx b/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
index 5efa4a2..fcfef27 100644
--- a/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/sidebar.browser.test.tsx
@@ -482,19 +482,20 @@ describe("최근 파일 영역", () => {
     });
   });
 
-  it("헤더으로 접으면 목록이 숨고 다시 펼치면 돌아온다", () => {
+  it("헤더로 접으면 목록이 숨고 다시 펼치면 돌아온다", () => {
     useWorkspaceStore.setState({ recentFiles: ["/vault/a.md"] });
-    const { getByTestId, queryByTestId } = render(<Sidebar />);
+    const { getByTestId } = render(<Sidebar />);
 
     const toggle = getByTestId("recent-files-toggle");
     expect(toggle.getAttribute("aria-expanded")).toBe("true");
 
     fireEvent.click(toggle);
-    expect(queryByTestId("recent-files")).toBeNull();
+    // 단언은 즉시 반영되는 상태 속성으로 한다(→ testing.md#성숙도-주의).
+    expect(getByTestId("recent-files").parentElement?.dataset.collapsed).toBe("true");
     expect(getByTestId("recent-files-toggle").getAttribute("aria-expanded")).toBe("false");
 
     fireEvent.click(getByTestId("recent-files-toggle"));
-    expect(queryByTestId("recent-files")).not.toBeNull();
+    expect(getByTestId("recent-files").parentElement?.dataset.collapsed).toBe("false");
   });
 
   // 집행: document-model.md#최근-파일 — "목록은 하나의 Tab 정지점이다(roving
diff --git a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
index c725d3d..076dbbe 100644
--- a/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/sidebar.tsx
@@ -5,6 +5,7 @@ import { useWorkspaceStore } from "@entities/workspace";
 import { openPathInTab } from "@features/open-file";
 import { openFolderInteractive, toggleDir } from "@features/open-folder";
 import { SettingsButton } from "@features/toggle-settings";
+import { useSidebarStore } from "@features/toggle-sidebar";
 import { STRINGS } from "@shared/config";
 import { entryNameOf } from "@shared/lib";
 import { Button, FilePlusIcon, FolderPlusIcon, IconButton } from "@shared/ui";
@@ -21,16 +22,23 @@ import { TreeItem } from "./tree-item";
 // 트리는 파일시스템의 위계를 보여줄 뿐이다 — 전체 인덱싱이 아니라 단순 트리 표시
 // (→ document-model.md#파일-트리-사이드바 · 비목표 경계).
 
+// 접기/펼치기 전환 규칙 → decisions/motion.md.
 const sidebarClass = css({
   display: "flex",
   flexDirection: "column",
   width: "60",
   flexShrink: 0,
   minHeight: 0,
+  overflow: "hidden",
   background: "bg.chrome",
   borderRightWidth: "1px",
   borderRightStyle: "solid",
   borderRightColor: "border",
+  transitionProperty: "width, border-right-width, visibility",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
+  '&[data-collapsed="true"]': { width: 0, borderRightWidth: 0, visibility: "hidden" },
 });
 
 const headerClass = css({
@@ -89,6 +97,13 @@ const emptyClass = css({
   textAlign: "center",
 });
 
+// 접힌 폴더의 하위는 DOM에 남지만 숨김이다(→ tree-item).
+function visibleTreeItems(root: HTMLElement | null): HTMLElement[] {
+  return [...(root?.querySelectorAll<HTMLElement>('[role="treeitem"]') ?? [])].filter(
+    (el) => el.closest('[data-collapsed="true"]') === null,
+  );
+}
+
 // 정지점을 index로 옮기고 포커스한다(범위는 [0, 끝]으로 물린다).
 function focusAt(list: HTMLElement[], index: number): void {
   const el = list[Math.max(0, Math.min(index, list.length - 1))];
@@ -102,7 +117,7 @@ function focusAt(list: HTMLElement[], index: number): void {
 // DOM 순서(곧 보이는 순서)로 알 수 있어, 노드마다 핸들러를 달지 않아도 이웃을 찾을 수 있다.
 function useTreeKeyboard(treeRef: React.RefObject<HTMLUListElement | null>) {
   return function onKeyDown(event: React.KeyboardEvent): void {
-    const list = [...(treeRef.current?.querySelectorAll<HTMLElement>('[role="treeitem"]') ?? [])];
+    const list = visibleTreeItems(treeRef.current);
     if (list.length === 0) {
       return;
     }
@@ -174,6 +189,7 @@ function useTreeKeyboard(treeRef: React.RefObject<HTMLUListElement | null>) {
 }
 
 export function Sidebar() {
+  const visible = useSidebarStore((state) => state.visible);
   const rootDir = useWorkspaceStore((state) => state.rootDir);
   const fileTree = useWorkspaceStore((state) => state.fileTree);
   const currentPath = useTreeNavStore((state) => state.currentPath);
@@ -185,11 +201,10 @@ export function Sidebar() {
   // Tab 정지점은 항상 하나여야 한다 — currentPath가 접혀 사라지거나 아직 없으면 첫 노드로
   // 자가 복구한다. 정지점이 이미 있으면 아무것도 하지 않아 반복되지 않는다.
   useEffect(() => {
-    const list = treeRef.current?.querySelectorAll<HTMLElement>('[role="treeitem"]');
-    if (!list || list.length === 0) {
+    const nodes = visibleTreeItems(treeRef.current);
+    if (nodes.length === 0) {
       return;
     }
-    const nodes = [...list];
     const hasStop = nodes.some((el) => el.tabIndex === 0);
     const first = nodes[0];
     if (!hasStop && first) {
@@ -199,7 +214,13 @@ export function Sidebar() {
 
   if (rootDir === null) {
     return (
-      <nav className={sidebarClass} aria-label={STRINGS.sidebarTreeLabel} data-testid="sidebar">
+      <nav
+        className={sidebarClass}
+        aria-label={STRINGS.sidebarTreeLabel}
+        aria-hidden={!visible}
+        data-collapsed={!visible}
+        data-testid="sidebar"
+      >
         <div className={emptyClass}>
           <span>{STRINGS.sidebarEmptyBody}</span>
           <Button data-testid="open-folder" onClick={() => void openFolderInteractive()}>
@@ -215,7 +236,13 @@ export function Sidebar() {
   }
 
   return (
-    <nav className={sidebarClass} aria-label={STRINGS.sidebarTreeLabel} data-testid="sidebar">
+    <nav
+      className={sidebarClass}
+      aria-label={STRINGS.sidebarTreeLabel}
+      aria-hidden={!visible}
+      data-collapsed={!visible}
+      data-testid="sidebar"
+    >
       <div className={headerClass}>
         <span className={headerNameClass} title={rootDir}>
           {entryNameOf(rootDir)}
diff --git a/apps/desktop/src/widgets/sidebar/ui/tree-item.tsx b/apps/desktop/src/widgets/sidebar/ui/tree-item.tsx
index f2f5a83..7b95624 100644
--- a/apps/desktop/src/widgets/sidebar/ui/tree-item.tsx
+++ b/apps/desktop/src/widgets/sidebar/ui/tree-item.tsx
@@ -1,4 +1,4 @@
-import { memo } from "react";
+import { memo, useEffect, useState } from "react";
 import { css } from "styled-system/css";
 
 import { useDocumentStore } from "@entities/document";
@@ -44,6 +44,10 @@ const rowClass = css({
   cursor: "pointer",
   whiteSpace: "nowrap",
   userSelect: "none",
+  transitionProperty: "background-color",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
   _hover: { background: "bg.hover" },
 });
 
@@ -53,12 +57,27 @@ const chevronClass = css({
   height: "3.5",
   transitionProperty: "transform",
   transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
   // 자기 li의 펼침만 본다 — `>` 사슬로 조상(펼친 부모)의 셰브론까지 도는 것을 막는다.
   '[aria-expanded="true"] > [data-row] > &': { transform: "rotate(90deg)" },
 });
 
 const nameClass = css({ overflow: "hidden", textOverflow: "ellipsis" });
 
+// 접기/펼치기 전환 규칙 → decisions/motion.md.
+const childrenCollapseClass = css({
+  display: "grid",
+  gridTemplateRows: "1fr",
+  minHeight: 0,
+  overflow: "hidden",
+  transitionProperty: "grid-template-rows, visibility",
+  transitionDuration: "fast",
+  transitionTimingFunction: "out",
+  _motionReduce: { transition: "none" },
+  '&[data-collapsed="true"]': { gridTemplateRows: "0fr", visibility: "hidden" },
+});
+
 const symlinkBadgeClass = css({ flexShrink: 0, fontSize: "xs", opacity: 0.7 });
 
 // 중첩 그룹은 왼쪽 세로 가이드 선으로 그 폴더의 자식 범위를 잇는다(시안 매칭). marginLeft가
@@ -69,6 +88,8 @@ const groupClass = css({
   margin: 0,
   padding: 0,
   marginLeft: "19px",
+  // 0fr 트랙이 내용 최소 높이 아래로 줄 수 있어야 접힘이 닫힌다(→ childrenCollapseClass).
+  minHeight: 0,
   borderLeftWidth: "1px",
   borderLeftStyle: "solid",
   borderLeftColor: "border.muted",
@@ -92,6 +113,18 @@ export const TreeItem = memo(function TreeItem({
   const edit = useEntryEditStore((state) => state.edit);
   const creatingHere = edit?.mode === "create" && edit.dir === node.path;
   const renamingThis = edit?.mode === "rename" && edit.path === node.path;
+  // lazy 첫 펼침 처리 → decisions/motion.md의 예외.
+  const hasChildren = node.children !== undefined;
+  const [childrenEntered, setChildrenEntered] = useState(false);
+  useEffect(() => {
+    if (!hasChildren) {
+      setChildrenEntered(false);
+      return;
+    }
+    const timer = setTimeout(() => setChildrenEntered(true), 0);
+    return () => clearTimeout(timer);
+  }, [hasChildren]);
+  const childrenCollapsed = !expanded || !childrenEntered;
 
   const onContextMenu = (event: React.MouseEvent): void => {
     event.preventDefault();
@@ -141,13 +174,19 @@ export const TreeItem = memo(function TreeItem({
           <span className={nameClass}>{node.name}</span>
           {symlinkBadge}
         </div>
-        {expanded && node.children !== undefined && (
-          <ul role="group" className={groupClass}>
-            {creatingHere && edit !== null && <EntryNameInput edit={edit} />}
-            {node.children.map((child) => (
-              <TreeItem key={child.path} node={child} depth={depth + 1} />
-            ))}
-          </ul>
+        {node.children !== undefined && (
+          <div
+            className={childrenCollapseClass}
+            data-collapsed={childrenCollapsed}
+            aria-hidden={childrenCollapsed}
+          >
+            <ul role="group" className={groupClass}>
+              {creatingHere && edit !== null && <EntryNameInput edit={edit} />}
+              {node.children.map((child) => (
+                <TreeItem key={child.path} node={child} depth={depth + 1} />
+              ))}
+            </ul>
+          </div>
         )}
       </li>
     );

From 001b5ced8aa014c32e855c480e68e5c1408455d5 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sat, 8 Aug 2026 18:09:55 +0900
Subject: [PATCH 13/18] =?UTF-8?q?feat(ds):=20=EB=8B=A4=EC=9D=B4=EC=96=BC?=
 =?UTF-8?q?=EB=A1=9C=EA=B7=B8=EC=97=90=20=EC=A7=84=EC=9E=85=C2=B7=ED=87=B4?=
 =?UTF-8?q?=EC=9E=A5=20=EB=AA=A8=EC=85=98=EC=9D=84=20=EC=A0=81=EC=9A=A9?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

닫힘은 dialogOut 전환이 끝난 뒤 close()·언마운트하고, animationend 유실은 타이머 상한으로
막는다. 동작 줄이기에서는 전환 없이 즉시 닫는다. 확인 다이얼로그는 닫힘 전환 동안 마지막
내용을 유지한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/desktop/panda.config.ts                  |  4 +-
 apps/desktop/src/shared/ui/confirm-dialog.tsx | 19 +++++--
 apps/desktop/src/shared/ui/dialog.tsx         | 56 +++++++++++++++----
 3 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/apps/desktop/panda.config.ts b/apps/desktop/panda.config.ts
index 6566d14..424445f 100644
--- a/apps/desktop/panda.config.ts
+++ b/apps/desktop/panda.config.ts
@@ -131,11 +131,13 @@ export default defineConfig({
         },
       },
 
-      // 다이얼로그 진입 — 상태 변화를 설명하는 모션만 둔다(→ DESIGN.md 모션).
       keyframes: {
         dialogIn: {
           from: { opacity: "0", transform: "translateY(6px) scale(0.99)" },
         },
+        dialogOut: {
+          to: { opacity: "0", transform: "translateY(4px) scale(0.99)" },
+        },
       },
 
       // 시맨틱 토큰 — "이 자리에 쓰는 의미". 라이트=base, 다크=_dark로 매핑.
diff --git a/apps/desktop/src/shared/ui/confirm-dialog.tsx b/apps/desktop/src/shared/ui/confirm-dialog.tsx
index fc6d54f..cf163ef 100644
--- a/apps/desktop/src/shared/ui/confirm-dialog.tsx
+++ b/apps/desktop/src/shared/ui/confirm-dialog.tsx
@@ -1,3 +1,4 @@
+import { useRef } from "react";
 import { css } from "styled-system/css";
 
 import { Button } from "./button";
@@ -21,28 +22,34 @@ const actionsClass = css({
 export function ConfirmDialog() {
   const pending = useConfirmStore((state) => state.pending);
   const settle = useConfirmStore((state) => state.settle);
+  // Dialog는 닫힘 전환이 끝날 때까지 마운트를 유지한다(→ ./dialog)
+  const lastPending = useRef(pending);
+  if (pending) {
+    lastPending.current = pending;
+  }
+  const shown = pending ?? lastPending.current;
 
-  if (!pending) {
+  if (!shown) {
     return null;
   }
   return (
     <Dialog
-      open
+      open={pending !== null}
       data-testid="confirm-dialog"
       aria-labelledby="confirm-dialog-title"
       aria-describedby="confirm-dialog-body"
       onCancel={() => settle(false)} // Esc — settle이 중복 호출을 무시하므로 close와 겹쳐도 안전.
     >
-      <strong id="confirm-dialog-title">{pending.title}</strong>
+      <strong id="confirm-dialog-title">{shown.title}</strong>
       <p id="confirm-dialog-body" className={bodyClass}>
-        {pending.body}
+        {shown.body}
       </p>
       <div className={actionsClass}>
         <Button data-testid="confirm-cancel" onClick={() => settle(false)}>
-          {pending.cancelLabel}
+          {shown.cancelLabel}
         </Button>
         <Button variant="accent" data-testid="confirm-accept" onClick={() => settle(true)}>
-          {pending.confirmLabel}
+          {shown.confirmLabel}
         </Button>
       </div>
     </Dialog>
diff --git a/apps/desktop/src/shared/ui/dialog.tsx b/apps/desktop/src/shared/ui/dialog.tsx
index e632f36..db94d02 100644
--- a/apps/desktop/src/shared/ui/dialog.tsx
+++ b/apps/desktop/src/shared/ui/dialog.tsx
@@ -1,5 +1,5 @@
 import type { DialogHTMLAttributes, ReactNode, RefObject } from "react";
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { cva, cx } from "styled-system/css";
 
 // 다이얼로그는 앱 위에 뜨지만 불투명하다 — 투명 창에서 backdrop-filter가 동작하지 않는다는 보고가
@@ -14,6 +14,8 @@ export const DIALOG_STYLES = {
     color: "text",
     boxShadow: "lg",
     animation: "dialogIn 0.16s ease",
+    // forwards — close() 전까지 끝 상태를 유지해야 한다.
+    '&[data-closing="true"]': { animation: "dialogOut 0.12s ease forwards" },
     _motionReduce: { animation: "none" },
     _backdrop: { background: "bg.scrim" },
   },
@@ -43,26 +45,56 @@ export interface DialogProps extends DialogHTMLAttributes<HTMLDialogElement> {
 export function Dialog({ open, size, className, dialogRef, children, ...rest }: DialogProps) {
   const fallbackRef = useRef<HTMLDialogElement>(null);
   const ref = dialogRef ?? fallbackRef;
+  // 닫힘 전환 동안 마운트를 유지한다(→ decisions/motion.md).
+  const [rendered, setRendered] = useState(open);
+  if (open && !rendered) {
+    setRendered(true);
+  }
 
   useEffect(() => {
-    if (!open) {
+    const dialog = ref.current;
+    if (!dialog) {
       return;
     }
-    // 닫을 때 <dialog>가 DOM에서 빠지므로 브라우저가 포커스를 돌려주지 않는다.
-    const opener = document.activeElement;
-    const dialog = ref.current;
-    if (dialog && !dialog.open) {
-      dialog.showModal();
+    if (open) {
+      // 닫을 때 <dialog>가 DOM에서 빠지므로 브라우저가 포커스를 돌려주지 않는다.
+      const opener = document.activeElement;
+      if (!dialog.open) {
+        delete dialog.dataset.closing;
+        dialog.showModal();
+      }
+      return () => {
+        // 그 사이 사라진 요소인지는 거르지 않는다 — 분리된 요소의 focus()는 아무 일도 하지 않는다.
+        if (opener instanceof HTMLElement) {
+          opener.focus();
+        }
+      };
+    }
+    if (!dialog.open) {
+      setRendered(false);
+      return;
     }
+    const finish = () => {
+      delete dialog.dataset.closing;
+      dialog.close();
+      setRendered(false);
+    };
+    // animation: none이면 animationend가 오지 않는다(동작 줄이기).
+    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      finish();
+      return;
+    }
+    dialog.dataset.closing = "true";
+    dialog.addEventListener("animationend", finish, { once: true });
+    // animationend 유실 대비 상한.
+    const timer = setTimeout(finish, 300);
     return () => {
-      // 그 사이 사라진 요소인지는 거르지 않는다 — 분리된 요소의 focus()는 아무 일도 하지 않는다.
-      if (opener instanceof HTMLElement) {
-        opener.focus();
-      }
+      clearTimeout(timer);
+      dialog.removeEventListener("animationend", finish);
     };
   }, [open, ref]);
 
-  if (!open) {
+  if (!open && !rendered) {
     return null;
   }
   return (

From 1e30c365972b53e9eab73841e68d5b5708528399 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sat, 8 Aug 2026 18:10:07 +0900
Subject: [PATCH 14/18] =?UTF-8?q?test(desktop):=20=EC=8B=A4=EC=95=B1=20E2E?=
 =?UTF-8?q?=EC=9D=98=20=ED=99=95=EC=A0=95=20=ED=82=A4=EC=99=80=20=EC=A0=84?=
 =?UTF-8?q?=ED=99=98=20=EB=8C=80=EA=B8=B0=EB=A5=BC=20=EC=95=88=EC=A0=95?=
 =?UTF-8?q?=ED=99=94=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

browser.keys()의 확정 Enter가 세션의 활성 요소로 가서 간헐 실패하던 것을 대상 요소에
합성 KeyboardEvent를 디스패치하는 방식으로 바꾼다. 렌더링되지 않는 창에서 CSS 전환이
진행되지 않아 완료 대기가 간헐 실패하던 것은 전환을 끄고 최종 상태(폭·테두리 0)를 즉시
단언한다. 두 실측 한계를 testing.md 성숙도 주의에 기록하고, 사이드바 접힘·다이얼로그
닫힘 대기를 시나리오에 추가한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/testing.md                |  2 +
 apps/desktop/e2e/file-lifecycle.e2e.ts | 93 ++++++++++++++++++++------
 2 files changed, 76 insertions(+), 19 deletions(-)

diff --git a/.claude/docs/testing.md b/.claude/docs/testing.md
index 10a5a8f..b167689 100644
--- a/.claude/docs/testing.md
+++ b/.claude/docs/testing.md
@@ -104,6 +104,8 @@ norii에서 가장 위험하고 고유한 것 — **한글 IME**와 **데이터
 - **수정자 키(Meta/Ctrl)를 매핑하지 않는다.** `browser.keys()`의 일반 텍스트도 CM6에 닿지 않는다 — **`element.addValue()`만** insertText로 전달된다. 동작 트리거는 dev 전용 훅(`window.noriiE2e`)·UI 클릭으로 구성한다.
 - **단축키는 합성 `KeyboardEvent`로 핸들러 층까지 E2E로 고정한다** — 앱 전역 핸들러(window keydown capture)가 `isTrusted`를 안 보므로 `browser.execute` 디스패치로 핸들러+동작이 발동한다(frontmost 불필요 → CI 가능). 실제 OS 키가 그 핸들러로 라우팅되는지(메뉴 가로채기 등)만 수동이다 — `mise run dev`에서 실제 키보드로 [단축키 계약](editor-strategy.md#단축키-계약) 표를 확인한다.
 - **`isDisplayed()`는 간헐적으로 어긋난다.** 긴 시퀀스 중 보이는 요소에 false를 준다 — 설정 다이얼로그에서 재현: DOM은 `open`·`hidden` 아님·정상 좌표인데 false. 창의 최상위·포커스 잃음·숨김 상태와는 무관하다(상태별 반복 질의로 실측). 표시 여부 단언은 `isDisplayed()`가 아니라 DOM(`closest("[hidden]")` 등)으로 한다.
+- **`browser.keys()`는 세션의 활성 요소로 간다 — 활성 요소는 창 상태에 좌우된다(실측).** 입력칸이 `focus()`를 받고도 활성 요소가 되지 못해 확정 Enter가 직전 클릭된 버튼으로 간 간헐 실패를 잡았다(입력값은 정상 — 사이드바 조작 시나리오). 확정 키는 `browser.keys()`가 아니라 대상 요소에 합성 `KeyboardEvent`를 디스패치한다.
+- **렌더링되지 않는(가려진·배경) 창에서는 CSS 전환과 `requestAnimationFrame`이 진행되지 않을 수 있다(실측)** — 전환 "완료"를 기다리는 단언은 창 상태에 좌우되어 간헐 실패한다(사이드바 접힘 폭 대기에서 재현). 최종 상태를 검증할 때는 전환을 끄고(`style.transition = "none"`) 즉시 단언한다. 앱 코드도 다음 프레임 신호가 필요하면 rAF가 아니라 타이머를 쓴다(트리 첫 펼침에서 rAF 고착 재현).
 - **`location.reload()` 뒤에는 새 페이지가 부팅됐음을 표식으로 확인한다.**
   - 리로드 전 화면이 다음 단언을 이미 만족하면 대기가 리로드 전 페이지에서 통과하고, 이어지는 `execute`가 아직 리로드 중인 페이지에서 돌아 훅(`noriiE2e`)이 없다(실측: 세션 복원 시나리오의 간헐 실패).
   - 리로드 직전 `window`에 표식을 심고, 표식이 사라진 페이지(= 새 페이지)에서 훅 존재까지 확인한 뒤 다음 단언으로 간다.
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index dc40395..4310ccf 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -116,6 +116,19 @@ async function selectOption(testId: string, value: string): Promise<void> {
   );
 }
 
+// keys()는 세션의 활성 요소로 가고, 활성 요소는 창 상태에 좌우된다
+// (→ testing.md#성숙도-주의) — 요소를 특정해 디스패치한다.
+async function pressEnterOn(testId: string): Promise<void> {
+  await browser.execute((id: string) => {
+    document
+      .querySelector(`[data-testid="${id}"]`)
+      ?.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Enter", bubbles: true, cancelable: true }),
+      );
+    return null;
+  }, testId);
+}
+
 /** 열기는 완료를 기다리지 않는다 — 활성 탭이 바뀐 뒤에 타이핑해야 직전 탭에 쳐지지 않는다. */
 async function waitActiveTab(filePath: string): Promise<void> {
   // 탭 신원은 canonical 경로다 — /tmp는 /private/tmp 링크라 그대로 비교하면 같아지지 않는다.
@@ -638,34 +651,61 @@ it("접기 — 거터 클릭으로 접히고 placeholder 클릭으로 펼쳐진
 
 // 집행: document-model.md#파일-트리-사이드바 · editor-strategy.md 단축키 계약 — 사이드바
 //       접기/열기. 타이틀 스트립 토글 버튼의 클릭 경로를 검증한다.
-// 왜: 접힘은 언마운트다 — 클릭으로 사이드바(트리)가 DOM에서 사라졌다 돌아오는 마운트/언마운트
-//     배선은 스토어 단위 테스트가 못 본다.
+// 왜: 접힘은 폭 전환 + 숨김이다(→ decisions/motion.md) — 클릭이 상태 속성(aria-hidden)까지
+//     반영되는 배선은 스토어 단위 테스트가 못 본다.
 // 경계: Cmd+B 단축키(수정자 키 합성 불가)·접힘 상태 영속화는 이 테스트 밖이다. 앞 사이드바
-//       시나리오가 연 트리를 전제로 이어받는다.
-it("사이드바 접기 — 토글 버튼으로 트리가 숨겨지고 다시 나타난다", async () => {
-  const tree = await browser.$('[data-testid="file-tree"]');
-  await tree.waitForExist({ timeout: 5_000 });
+//       시나리오가 연 트리를 전제로 이어받는다. 시각적 숨김 완료는 전환 뒤라 상태 속성으로
+//       단언한다.
+it("사이드바 접기 — 토글 버튼으로 숨겨지고 다시 나타난다", async () => {
+  const sidebarHidden = () =>
+    browser.execute(
+      () =>
+        document.querySelector('[data-testid="sidebar"]')?.getAttribute("aria-hidden") === "true",
+    );
+  expect(await sidebarHidden()).toBe(false);
 
   const toggle = await browser.$('[data-testid="sidebar-toggle"]');
   await toggle.click();
-  await tree.waitForExist({
-    reverse: true,
+  await browser.waitUntil(sidebarHidden, {
     timeout: 5_000,
-    timeoutMsg: "접기 후 트리가 사라지지 않았다",
+    timeoutMsg: "접기 후 사이드바가 숨겨지지 않았다",
+  });
+  // 접힘의 최종 상태는 빈 띠·잔여 테두리가 없어야 한다 — 폭·오른쪽 테두리 0.
+  // 전환 완료 대기는 창 상태에 좌우된다(→ testing.md#성숙도-주의) — 전환을 끄고 단언한다.
+  const residue = await browser.execute(() => {
+    const sidebar = document.querySelector('[data-testid="sidebar"]');
+    if (!(sidebar instanceof HTMLElement)) {
+      return null;
+    }
+    sidebar.style.transition = "none";
+    const result = {
+      width: sidebar.getBoundingClientRect().width,
+      border: getComputedStyle(sidebar).borderRightWidth,
+    };
+    sidebar.style.removeProperty("transition");
+    return result;
   });
+  expect(residue).toEqual({ width: 0, border: "0px" });
 
   await toggle.click();
-  await tree.waitForExist({ timeout: 5_000, timeoutMsg: "펼침 후 트리가 돌아오지 않았다" });
+  await browser.waitUntil(async () => !(await sidebarHidden()), {
+    timeout: 5_000,
+    timeoutMsg: "펼침 후 사이드바가 돌아오지 않았다",
+  });
 });
 
 // 집행: editor-strategy.md 단축키 계약 — 사이드바 접기/열기 `Cmd+B`.
 // 왜: 이 플러그인은 수정자 키를 합성 못 하지만, 앱 전역 핸들러(window keydown capture)가
 //     isTrusted를 안 봐 합성 KeyboardEvent로 발동한다 — 단축키의 핸들러+동작 배선을 실앱에서
 //     고정한다(실제 OS 키 라우팅만 수동, → testing.md#성숙도-주의).
-// 보장: Cmd(Meta)+B 합성 keydown으로 트리가 언마운트되고, 다시 누르면 돌아온다.
+// 보장: Cmd(Meta)+B 합성 keydown으로 사이드바가 숨겨지고, 다시 누르면 돌아온다.
 it("사이드바 접기 — Cmd+B(합성 keydown)로 여닫힌다", async () => {
-  const tree = await browser.$('[data-testid="file-tree"]');
-  await tree.waitForExist({ timeout: 5_000 });
+  const sidebarHidden = () =>
+    browser.execute(
+      () =>
+        document.querySelector('[data-testid="sidebar"]')?.getAttribute("aria-hidden") === "true",
+    );
+  expect(await sidebarHidden()).toBe(false);
 
   const cmdB = () =>
     browser.execute(() => {
@@ -676,14 +716,16 @@ it("사이드바 접기 — Cmd+B(합성 keydown)로 여닫힌다", async () =>
     });
 
   await cmdB();
-  await tree.waitForExist({
-    reverse: true,
+  await browser.waitUntil(sidebarHidden, {
     timeout: 5_000,
-    timeoutMsg: "Cmd+B로 트리가 사라지지 않았다",
+    timeoutMsg: "Cmd+B로 사이드바가 숨겨지지 않았다",
   });
 
   await cmdB();
-  await tree.waitForExist({ timeout: 5_000, timeoutMsg: "Cmd+B로 트리가 돌아오지 않았다" });
+  await browser.waitUntil(async () => !(await sidebarHidden()), {
+    timeout: 5_000,
+    timeoutMsg: "Cmd+B로 사이드바가 돌아오지 않았다",
+  });
 });
 
 // 집행: document-model.md#파일-트리-사이드바 — 사이드바 항목 조작(만들기·이름 변경·삭제)과
@@ -710,7 +752,7 @@ it("사이드바 조작 — 만들기·이름 변경·삭제가 실제 디스크
   await input.waitForExist({ timeout: 5_000 });
   await input.clearValue();
   await input.addValue("ops-회의록");
-  await browser.keys("Enter");
+  await pressEnterOn("entry-name-input");
 
   const createdPath = path.join(opsRoot, "ops-회의록.md");
   await browser.waitUntil(async () => existsSync(createdPath), {
@@ -733,7 +775,7 @@ it("사이드바 조작 — 만들기·이름 변경·삭제가 실제 디스크
   await renameInput.waitForExist({ timeout: 5_000 });
   await renameInput.clearValue();
   await renameInput.addValue("ops-결산");
-  await browser.keys("Enter");
+  await pressEnterOn("entry-name-input");
 
   const renamedPath = path.join(opsRoot, "ops-결산.md");
   await browser.waitUntil(async () => existsSync(renamedPath) && !existsSync(createdPath), {
@@ -803,6 +845,13 @@ it("설정 창 — 메뉴로 분류를 바꾸고 고른 자동 저장 간격이
   // 뒤 시나리오가 기다리는 시간 안에 저장이 나가도록 기본값으로 되돌린다.
   await selectOption("settings-autosave", "5s");
   await (await browser.$('[data-testid="settings-close"]')).click();
+  // 닫힘 전환이 끝나야 다이얼로그가 내려간다 — 다음 시나리오의 열기와 겹치지 않게 기다린다.
+  await (
+    await browser.$('[data-testid="settings-dialog"]')
+  ).waitForExist({
+    reverse: true,
+    timeout: 5_000,
+  });
 });
 
 // 집행: design/decisions/color-palette.md — 액센트는 테마와 무관하게 한 색이다.
@@ -850,6 +899,12 @@ it("색 — 테마를 바꿔도 액센트는 한 색이다", async () => {
 
   await (await browser.$('[data-testid="settings-theme-system"]')).click();
   await (await browser.$('[data-testid="settings-close"]')).click();
+  await (
+    await browser.$('[data-testid="settings-dialog"]')
+  ).waitForExist({
+    reverse: true,
+    timeout: 5_000,
+  });
 });
 
 // 집행: document-model.md#세션-복원 — "탭 목록·활성 탭·루트 폴더·탭별 자리"를 되살린다.

From 6a8238273593a79524a1b5ee4b169f62d8aac5a5 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sat, 8 Aug 2026 23:59:21 +0900
Subject: [PATCH 15/18] =?UTF-8?q?test(desktop):=20=EC=8B=A4=EC=95=B1=20E2E?=
 =?UTF-8?q?=EC=97=90=20=EB=8D=B0=EB=AA=A8=20=EA=B0=90=EC=86=8D=EA=B3=BC=20?=
 =?UTF-8?q?=EC=B5=9C=EA=B7=BC=20=ED=8C=8C=EC=9D=BC=20=EC=A0=91=EA=B8=B0=20?=
 =?UTF-8?q?=EB=8B=A8=EA=B3=84=EB=A5=BC=20=EC=B6=94=EA=B0=80=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

데모 녹화가 기계 속도라 사람이 볼 수 없어 NORII_E2E_SLOWMO_MS로 동작(클릭·입력·훅
트리거) 앞에서만 쉬게 한다 — 대기 폴링에는 걸지 않아 일반 실행은 그대로다.
최근 파일 헤더 접기는 새 표면인데 실앱 E2E 커버가 없어 기존 최근 파일 시나리오에
단계를 더한다. 전체 스위트 일반 속도 21/21 통과.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/development-commands.md   |  1 +
 apps/desktop/e2e/file-lifecycle.e2e.ts | 56 +++++++++++++++++++++++++-
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/.claude/docs/development-commands.md b/.claude/docs/development-commands.md
index 36265e0..f0792ec 100644
--- a/.claude/docs/development-commands.md
+++ b/.claude/docs/development-commands.md
@@ -90,6 +90,7 @@ mise run docs-drift   # 계약 문서 ↔ 코드 기계 대조 (scripts/docs-dri
 사용자에게 보이는 동작이 바뀐 PR에는 데모 영상을 붙인다(→ [/pr 커맨드](../commands/pr.md)). **E2E 시나리오를 그대로 녹화**하는 것이 규칙이다 — 별도 데모 스크립트를 두면 테스트와 데모가 따로 낡는다. E2E가 늘면 데모도 자동으로 풍부해진다.
 
 - `mise run demo`(`scripts/record-demo.sh`) — 앱 창을 논리 좌표에 배치하고 `mise run e2e`를 실행하며 그 화면을 녹화한다. **좌표 주의**: WebDriver의 창 크기는 Retina 픽셀이고 `screencapture -R`은 논리 좌표다 — 섞으면 창 밖이 찍힌다. 그래서 창 배치는 AppleScript(논리 좌표)로 한다.
+- `NORII_E2E_SLOWMO_MS=1000 mise run demo` — 동작(클릭·입력·훅 트리거)마다 지정 밀리초를 쉬어 사람이 볼 속도로 녹화한다. 대기 폴링에는 걸리지 않는다.
 - `mise run upload-demo <파일>`(`scripts/upload-attachment.sh`) — GitHub 자산 CDN에 올려 URL을 받는다. **리포에 영상 바이너리를 커밋하지 않기 위한 유일한 경로**다. 인증은 `agent-browser` 브라우저 프로필에 저장되며, 첫 실행에서 로그인이 없으면 스크립트가 한 줄 안내를 출력한다(이후 자동).
 - 전제: macOS **화면 기록 권한**(시스템 설정 → 개인정보 보호), `jq`, `agent-browser`. 권한·도구가 없으면 스크립트가 이유를 출력하고 멈춘다.
 
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index 4310ccf..1fd667c 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -27,6 +27,15 @@ import { afterAll, beforeAll, expect, it } from "vitest";
 const SCOPE_ROOT = process.env.NORII_E2E_SCOPE_ROOT ?? "/tmp/norii-e2e";
 const WEBDRIVER_PORT = Number(process.env.TAURI_WEBDRIVER_PORT ?? "4445");
 
+// 데모 녹화 감속(→ development-commands.md#pr-데모-영상-demo--upload-demo) — 동작 앞에서만
+// 쉬고 대기 폴링에는 걸지 않는다.
+const SLOWMO_MS = Number(process.env.NORII_E2E_SLOWMO_MS ?? "0");
+async function slowmo(): Promise<void> {
+  if (SLOWMO_MS > 0) {
+    await new Promise((resolve) => setTimeout(resolve, SLOWMO_MS));
+  }
+}
+
 // 사이드바 시나리오들이 공유하는 트리 루트 — 세 테스트가 같은 워크스페이스 상태를 이어받는다.
 const TREE_ROOT = path.join(SCOPE_ROOT, "tree");
 const TREE_NOTES = path.join(TREE_ROOT, "notes");
@@ -56,6 +65,24 @@ beforeAll(async () => {
     capabilities: {},
     logLevel: "error",
   });
+  if (SLOWMO_MS > 0) {
+    browser.overwriteCommand(
+      "click",
+      async function (origClick: () => Promise<void>) {
+        await slowmo();
+        return origClick();
+      },
+      true,
+    );
+    browser.overwriteCommand(
+      "addValue",
+      async function (origAddValue: (value: string) => Promise<void>, value: string) {
+        await slowmo();
+        return origAddValue(value);
+      },
+      true,
+    );
+  }
   // 세션 파일을 지운 뒤 리로드해야 탭 0개에서 출발한다(→ .claude/docs/testing.md).
   // 설정 파일은 여기서 못 지운다 — plugin-store가 값을 앱 프로세스 메모리에 들고 있어
   // 파일을 지워도 앱이 그대로 다시 쓴다. 앱을 띄우는 dev-webdriver가 미리 지운다.
@@ -84,6 +111,7 @@ afterAll(async () => {
 // execute 콜백은 항상 null을 반환한다 — 이 플러그인은 Promise·undefined 반환값을
 // 직렬화하지 못한다("unsupported type"). 열기 완료는 반환값이 아니라 DOM 변화로 기다린다.
 async function openInApp(filePath: string): Promise<void> {
+  await slowmo();
   await browser.execute((p: string) => {
     void window.noriiE2e?.openPath(p);
     return null;
@@ -91,6 +119,7 @@ async function openInApp(filePath: string): Promise<void> {
 }
 
 async function openFolderInApp(root: string): Promise<void> {
+  await slowmo();
   await browser.execute((p: string) => {
     void window.noriiE2e?.openFolder(p);
     return null;
@@ -100,6 +129,7 @@ async function openFolderInApp(root: string): Promise<void> {
 // WebDriver의 선택은 이 WebKit 드라이버에서 React의 onChange를 호출하지 않는다(합성 keydown과
 // 같은 한계 → 파일 머리).
 async function selectOption(testId: string, value: string): Promise<void> {
+  await slowmo();
   await browser.execute(
     (id: string, next: string) => {
       const element = document.querySelector(`[data-testid="${id}"]`) as HTMLSelectElement | null;
@@ -119,6 +149,7 @@ async function selectOption(testId: string, value: string): Promise<void> {
 // keys()는 세션의 활성 요소로 가고, 활성 요소는 창 상태에 좌우된다
 // (→ testing.md#성숙도-주의) — 요소를 특정해 디스패치한다.
 async function pressEnterOn(testId: string): Promise<void> {
+  await slowmo();
   await browser.execute((id: string) => {
     document
       .querySelector(`[data-testid="${id}"]`)
@@ -188,6 +219,7 @@ async function waitTreeItem(name: string): Promise<void> {
 // 만든 직후엔 트리가 watch_tree로 리렌더 중이라 한 번의 디스패치가 리렌더와 겹쳐 놓칠 수
 // 있다(진단으로 확인). 메뉴가 열릴 때까지 재디스패치한다.
 async function openMenuFor(name: string): Promise<void> {
+  await slowmo();
   await browser.waitUntil(
     async () => {
       await rightClickTreeItem(name);
@@ -208,6 +240,7 @@ it("스모크 — 실제 앱이 뜨고 시작 화면(빈 상태)이 렌더된다
 
 // 합성 Cmd+W — 전역 핸들러 경유 탭 닫기(수정자 키 합성 불가 한계와 우회는 파일 머리).
 async function closeActiveTab(): Promise<void> {
+  await slowmo();
   await browser.execute(() => {
     window.dispatchEvent(
       new KeyboardEvent("keydown", { key: "w", metaKey: true, bubbles: true, cancelable: true }),
@@ -252,7 +285,7 @@ it("빈 상태 — 버튼이 뜨고 새 문서 버튼이 Untitled 탭을 연다"
 // 왜: 저장(세션)·갱신(스토어)이 각자 옳아도, 목록 표시 → 클릭 → 다시 열기의
 //     끝단 배선은 실앱에서만 확인된다.
 // 보장: 파일을 열었다 닫으면 사이드바 최근 파일 영역에 그 파일명이 뜨고, 누르면 같은
-//       파일이 다시 열린다.
+//       파일이 다시 열린다. 헤더 버튼이 목록을 접고 다시 펼친다.
 it("최근 파일 — 닫은 파일이 사이드바 목록에 남고 누르면 다시 열린다", async () => {
   const filePath = path.join(SCOPE_ROOT, "recent-데모.md");
   await writeFile(filePath, "# 최근 파일 데모\n", "utf8");
@@ -278,6 +311,27 @@ it("최근 파일 — 닫은 파일이 사이드바 목록에 남고 누르면 
     return null;
   });
   await waitActiveTab(filePath);
+
+  // 집행: document-model.md#최근-파일 — 헤더로 접고 펼친다.
+  const recentExpanded = () =>
+    browser.execute(
+      () =>
+        document
+          .querySelector('[data-testid="recent-files-toggle"]')
+          ?.getAttribute("aria-expanded") === "true",
+    );
+  expect(await recentExpanded()).toBe(true);
+  const recentToggle = await browser.$('[data-testid="recent-files-toggle"]');
+  await recentToggle.click();
+  await browser.waitUntil(async () => !(await recentExpanded()), {
+    timeout: 5_000,
+    timeoutMsg: "헤더로 최근 파일이 접히지 않았다",
+  });
+  await recentToggle.click();
+  await browser.waitUntil(recentExpanded, {
+    timeout: 5_000,
+    timeoutMsg: "헤더로 최근 파일이 다시 펼쳐지지 않았다",
+  });
 });
 
 // 집행: file-lifecycle.md#자동-저장 — 저장 대기가 생긴 시점부터 고른 간격에 저장한다.

From 6c3cbc775b59724c13486d8121f239006eca37b7 Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sun, 9 Aug 2026 01:50:28 +0900
Subject: [PATCH 16/18] =?UTF-8?q?docs:=20=EA=B3=84=EC=95=BD=20=EB=AC=B8?=
 =?UTF-8?q?=EC=84=9C=20=EC=88=98=EB=8F=99=20=EB=8C=80=EC=A1=B0=EB=A5=BC=20?=
 =?UTF-8?q?PR=20=EC=98=AC=EB=A6=AC=EA=B8=B0=20=EC=A0=84=20=EC=A0=88?=
 =?UTF-8?q?=EC=B0=A8=EB=A1=9C=20=EB=AA=85=EC=8B=9C=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

수동 대조 시점이 "마일스톤 종료 시"로만 있어 PR 생성 때 수행하는지가 규정에 없었다.
모든 PR 전에 대조하고 어긋남 수정을 그 PR에 담는 것으로 정하고, /pr 커맨드 절차에
단계를 추가한다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/commands/pr.md         | 15 ++++++++-------
 .claude/rules/project-rules.md |  2 +-
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/.claude/commands/pr.md b/.claude/commands/pr.md
index ea8a2dd..58a3b48 100644
--- a/.claude/commands/pr.md
+++ b/.claude/commands/pr.md
@@ -15,26 +15,27 @@ argument-hint: "[base 브랜치 — 생략 시 main]"
    - `git log origin/<base>..HEAD --oneline` — 커밋들이 곧 의도다
    - `git diff origin/<base>..HEAD --stat` — 변경 파일
    - 커밋 본문과 `.claude` 문서 변경에서 결정·이탈을 읽는다
-3. **본문 작성** — `.github/pull_request_template.md`를 읽어 각 섹션을 diff·커밋을 근거로 채운다.
+3. **계약 문서 수동 대조** — 기계 대조 밖 계약을 코드와 대조한다. 대상·수정 처리는 [작업 규칙](../rules/project-rules.md)을 따른다.
+4. **본문 작성** — `.github/pull_request_template.md`를 읽어 각 섹션을 diff·커밋을 근거로 채운다.
    - 범위의 "의도적으로 안 한 것/후속"과 검증(값)은 **반드시** 채운다 — diff에 안 담기는 정보다
    - 확실치 않으면 추측하지 말고 사용자에게 묻는다
    - diff·커밋·`.claude` 문서에서 읽을 수 있는 것은 중복하지 않는다(의도·제외·검증 결과·이탈 위주)
-4. **다이어그램(mermaid)** — 다음 중 하나가 변경에 포함되면 본문에 넣는다. 없으면 넣지 않는다(그림을 위한 그림은 노이즈다).
+5. **다이어그램(mermaid)** — 다음 중 하나가 변경에 포함되면 본문에 넣는다. 없으면 넣지 않는다(그림을 위한 그림은 노이즈다).
    - **여러 층을 가로지르는 흐름** — 프론트·IPC·Rust를 관통하는 경로(예: 저장 파이프라인) → `sequenceDiagram`
    - **상태 기계** — 전이가 3개 이상이고 잘못된 전이가 버그가 되는 것(예: 탭 dirty·충돌) → `stateDiagram-v2`
    - **결정론적 분기 파이프라인** — 순서가 규칙인 것(예: 열기 인코딩 판정) → `flowchart`
    - **원칙**: 계약 문서에 이미 그림이 있으면 **링크**하고, PR에는 리뷰어가 diff 전에 방향을 잡아야 하는 **핵심 1개만 인라인**한다. 다이어그램의 단일 출처는 계약 문서다(→ [작업 규칙](../rules/project-rules.md)).
    - **넣지 않는 것**: 레이어 구조도(설계 문서에 이미 있음)·파일 나열형 그림 — diff와 중복이다.
-5. **제목** — 지배적 변경으로 type 결정. 형식·subject-case 등은 [커밋 컨벤션](../rules/commit-convention.md)을 따른다.
-6. **라벨** — 변경 유형에 맞는 라벨을 고른다(라벨 세트는 [커밋 컨벤션](../rules/commit-convention.md)).
-7. **검증 상태** — `mise run check` 결과를 본문에 값으로 적는다(못 돌리면 그 이유). 실앱 E2E·번들 크기는 mac 실기 항목이라 통과/미검증 상태만 표기한다.
-8. **데모 영상 (사용자에게 보이는 동작이 바뀐 PR이면 첨부)** — E2E 화면을 그대로 녹화해 붙인다. UI·동작 변경이 없는 PR(문서·리팩터링·내부 정리)은 건너뛴다.
+6. **제목** — 지배적 변경으로 type 결정. 형식·subject-case 등은 [커밋 컨벤션](../rules/commit-convention.md)을 따른다.
+7. **라벨** — 변경 유형에 맞는 라벨을 고른다(라벨 세트는 [커밋 컨벤션](../rules/commit-convention.md)).
+8. **검증 상태** — `mise run check` 결과를 본문에 값으로 적는다(못 돌리면 그 이유). 실앱 E2E·번들 크기는 mac 실기 항목이라 통과/미검증 상태만 표기한다.
+9. **데모 영상 (사용자에게 보이는 동작이 바뀐 PR이면 첨부)** — E2E 화면을 그대로 녹화해 붙인다. UI·동작 변경이 없는 PR(문서·리팩터링·내부 정리)은 건너뛴다.
    - 앱 실행: `mise run dev-webdriver` (다른 터미널, 백그라운드)
    - 녹화: `mise run demo` — E2E 시나리오를 실행하며 앱 창을 녹화한다(→ `scripts/record-demo.sh`)
    - 업로드: `mise run upload-demo <파일>` — GitHub CDN URL을 받는다(리포에 바이너리를 커밋하지 않는다, → `scripts/upload-attachment.sh`)
    - 받은 URL을 PR 본문의 "스크린샷 / 데모" 섹션에 그대로 넣는다(영상은 URL만 두면 GitHub이 플레이어로 렌더한다)
    - 첫 실행에서 GitHub 로그인이 없다고 나오면 스크립트가 안내하는 한 줄을 실행해 한 번만 로그인한다 — 이후는 프로필에 저장돼 자동이다
-9. **확인 후 생성** — 초안(제목·본문·라벨·담당자·데모 영상)을 사용자에게 보여주고 **승인받은 뒤에만** 실행한다:
+10. **확인 후 생성** — 초안(제목·본문·라벨·담당자·데모 영상)을 사용자에게 보여주고 **승인받은 뒤에만** 실행한다:
    - 브랜치가 원격에 없으면 먼저 `git push -u origin <branch>` (승인 후)
    - `gh pr create --base <base> --title "…" --body "…" --assignee @me` 후 `gh pr edit --add-label <label>`
    - 담당자는 `@me`(현재 인증 사용자)로 자동 배정한다 — 계정명을 하드코딩하지 않는다.
diff --git a/.claude/rules/project-rules.md b/.claude/rules/project-rules.md
index 748d6c8..9442cb8 100644
--- a/.claude/rules/project-rules.md
+++ b/.claude/rules/project-rules.md
@@ -19,7 +19,7 @@ norii에서 작업하는 사람과 에이전트가 따르는 필수 규칙이다
 
 - 규칙·설계를 바꿀 때는 코드보다 **문서(단일 출처)를 먼저 갱신**한다.
 - **문서 갱신은 완료 조건이다.** 문서가 규정한 동작을 바꾸는 변경은 문서를 **먼저, 늦어도 같은 커밋에서** 갱신한다. 문서 갱신 없이 들어간 동작 변경은 미완성이다.
-- **구현 세부는 계약 문서에만 둔다.** 계약 문서란 **앱의 런타임 동작을 규정하는, 코드와 1:1 대응되는 값·시그니처·정책을 담은 문서**다 — 현재 9곳: [Rust 커맨드 계약](../docs/rust-commands.md) · [문서 모델](../docs/document-model.md) · [에디터 전략 — 단축키 계약](../docs/editor-strategy.md#단축키-계약) · [한글 IME](../docs/korean-ime.md)(조합 확정 Enter 처리 창) · [기술 스택 버전 표](../docs/tech-stack.md) · [파일 생명주기 정책](../docs/file-lifecycle.md) · [보안 — CSP](../docs/security.md) · [프리뷰 전략](../docs/preview-strategy.md)(sanitize 정책·플러그인·mermaid securityLevel) · [창 표면 계약](../docs/design/window-chrome.md)(transparent·창 뒤 흐림 반경·폴백). 디자인 값(팔레트·타이포·간격 스케일)은 예외로 문서가 아니라 `panda.config.ts`가 소유한다 — 값을 문서에 복제하지 않는다(→ [디자인 시스템](../docs/design/design-system.md#이-문서의-경계)). 빌드 설정 서술(tsconfig 옵션·경로 별칭)은 제외한다 — 게이트가 실제 설정 파일로 돌므로 문서 드리프트가 동작 차이로 이어지지 않는다. 다른 문서는 링크만 한다. 이 기준을 충족하는 문서가 생기면 목록에 추가한다. 문서-코드 대조의 대상도 이 목록이다. 단 자동 검사(`docs-drift`)는 **기계 대조가 가능한 표면만** 돈다 — 나머지 계약은 마일스톤 종료 시 수동 대조한다(→ [개발 명령](../docs/development-commands.md), [테스트 전략](../docs/testing.md)).
+- **구현 세부는 계약 문서에만 둔다.** 계약 문서란 **앱의 런타임 동작을 규정하는, 코드와 1:1 대응되는 값·시그니처·정책을 담은 문서**다 — 현재 9곳: [Rust 커맨드 계약](../docs/rust-commands.md) · [문서 모델](../docs/document-model.md) · [에디터 전략 — 단축키 계약](../docs/editor-strategy.md#단축키-계약) · [한글 IME](../docs/korean-ime.md)(조합 확정 Enter 처리 창) · [기술 스택 버전 표](../docs/tech-stack.md) · [파일 생명주기 정책](../docs/file-lifecycle.md) · [보안 — CSP](../docs/security.md) · [프리뷰 전략](../docs/preview-strategy.md)(sanitize 정책·플러그인·mermaid securityLevel) · [창 표면 계약](../docs/design/window-chrome.md)(transparent·창 뒤 흐림 반경·폴백). 디자인 값(팔레트·타이포·간격 스케일)은 예외로 문서가 아니라 `panda.config.ts`가 소유한다 — 값을 문서에 복제하지 않는다(→ [디자인 시스템](../docs/design/design-system.md#이-문서의-경계)). 빌드 설정 서술(tsconfig 옵션·경로 별칭)은 제외한다 — 게이트가 실제 설정 파일로 돌므로 문서 드리프트가 동작 차이로 이어지지 않는다. 다른 문서는 링크만 한다. 이 기준을 충족하는 문서가 생기면 목록에 추가한다. 문서-코드 대조의 대상도 이 목록이다. 단 자동 검사(`docs-drift`)는 **기계 대조가 가능한 표면만** 돈다 — 나머지 계약은 **PR을 올리기 전에** 수동 대조한다 — 대조에서 나온 수정이 그 PR에 함께 들어가야 한다(→ [개발 명령](../docs/development-commands.md), [테스트 전략](../docs/testing.md)).
 - 각 문서는 한 주제의 단일 출처다. 같은 사실을 여러 문서에 복제하지 않고 링크한다.
 - **확정된 디자인 결정은 결정 기록으로 남긴다** — **한 주제에 한 파일**(`.claude/docs/design/decisions/<주제>.md`). 같은 주제가 다시 결정되면 새 파일을 만들지 않고 **그 파일을 고쳐 쓰고**, 무엇이 왜 바뀌었는지만 그 파일의 "바뀐 것" 표에 한 줄 남긴다 — 옛 전문은 git 히스토리가 갖는다. 미결정은 결정 기록이 아니라 열린 결정 목록이 추적한다(→ [결정 기록](../docs/design/decisions/)).
 - **문서 링크는 위에서 아래로만 건다.** 루트(`DESIGN.md`)가 상세를 링크하고, 상세는 루트를 링크하지 않는다 — 필요한 사실은 자기가 소유하거나 형제 문서를 가리킨다.

From 9e88ca317868301e4bbd4a331f64a7fdf40a33cf Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sun, 9 Aug 2026 01:50:48 +0900
Subject: [PATCH 17/18] =?UTF-8?q?docs:=20=EA=B3=84=EC=95=BD=20=EB=AC=B8?=
 =?UTF-8?q?=EC=84=9C=EB=A5=BC=20=EA=B5=AC=ED=98=84=EA=B3=BC=20=EB=8C=80?=
 =?UTF-8?q?=EC=A1=B0=ED=95=B4=20=EC=96=B4=EA=B8=8B=EB=82=9C=20=EC=84=9C?=
 =?UTF-8?q?=EC=88=A0=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR 전 수동 대조에서 확인한 불일치를 문서 쪽에서 수정한다(코드 변경 없음).

- rust-commands: 세션 커맨드 2개를 async fn으로, 미구현 plugin-window-state 행 제거
- document-model: 세션 저장 파일 표에서 창 크기·위치 행 제거(도입 여부는 열린 결정으로),
  재펼침은 캐시 사용, WorkspaceState를 실제 형태로(expandedDirs 필드, 탭은 별도 스토어),
  최근 파일 추가 시점에 사이드바 새 파일 만들기 경로 추가
- editor-strategy: 단축키 표에 3행 추가(탭 Delete/Backspace 닫기 · 탭바 방향키 전환 ·
  전체 접기/펼치기), 확인 다이얼로그 중 전역 단축키 정지 명시
- preview-strategy: 뷰 모드는 설정 파일에 저장·복원(열린 결정 문구 삭제), 복사 버튼
  노출 조건에 키보드 포커스·복사됨 상태 포함
- window-chrome: 36px의 _glass 한정 삭제, docs-drift 상수 대조와 모순되는 "자동 검사는
  이것뿐" 삭제, 렌더 검증은 Vitest Browser Mode로 가능함을 반영, 부팅 ①②는 Promise.all
- file-lifecycle: 충돌 UI를 배너로 통일, 상태 다이어그램에서 코드에 없는 error 상태 제거,
  접힘 상태는 저장하지 않음을 명시
- mise verify-native 설명에 한글 조합 확정 입력 포함

데이터를 물건처럼 쓰는 표현(버린다·올린다·되살린다·저장 자리)도 동작 서술로 고치고,
문서를 인용하는 주석 2곳(open-file·E2E 집행)을 같이 맞춘다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/design/window-chrome.md          | 12 +++++------
 .claude/docs/document-model.md                | 20 +++++++++----------
 .claude/docs/editor-strategy.md               |  5 ++++-
 .claude/docs/file-lifecycle.md                |  7 +++----
 .claude/docs/implementation-plan.md           |  1 +
 .claude/docs/preview-strategy.md              |  4 ++--
 .claude/docs/rust-commands.md                 |  5 ++---
 .mise.toml                                    |  2 +-
 apps/desktop/e2e/file-lifecycle.e2e.ts        |  2 +-
 .../src/features/open-file/model/open-file.ts |  2 +-
 10 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.claude/docs/design/window-chrome.md b/.claude/docs/design/window-chrome.md
index 22409f5..d935c69 100644
--- a/.claude/docs/design/window-chrome.md
+++ b/.claude/docs/design/window-chrome.md
@@ -61,7 +61,7 @@ TITLEBAR_CUTOUT_WIDTH = 32   그 영역의 폭(px). 높이는 띠 전체다.
 
 그 띠에서 눌린 마우스는 웹뷰를 거치지 않고 AppKit이 직접 처리하므로(`isMovableByWindowBackground`), IPC를 타지 않아 tauri#9503에 걸리지 않는다 — 네이티브 앱과 같은 경로다.
 
-**웹 쪽은 이 띠를 타이틀 스트립이 채운다.** `title-strip` 위젯이 창 최상단 full-width로 놓이고, `_glass`에서 높이 `36px`로 이 띠와 겹친다. 그 아래에 사이드바·탭바·본문이 온다. 스트립 높이와 위 상수는 같아야 하고, 위 상수가 단일 출처다(docs-drift가 대조).
+**웹 쪽은 이 띠를 타이틀 스트립이 채운다.** `title-strip` 위젯이 창 최상단 full-width로 놓이고, 높이 `36px`로 이 띠와 겹친다. 그 아래에 사이드바·탭바·본문이 온다. 스트립 높이와 위 상수는 같아야 하고, 위 상수가 단일 출처다(docs-drift가 대조).
 
 **스트립 안에는 앱 이름과 클릭 통과 영역 하나가 있다.** 앱 이름은 클릭을 받지 않는 글자다(`pointer-events: none`). 그 밖에 띠 안에서 눌리는 컨트롤을 두려면 **클릭 통과 영역**을 둬야 한다 — 띠의 `hitTest:`가 그 사각형 안에서 `nil`을 반환해 클릭이 웹뷰로 내려간다. 영역은 하나뿐이고 사이드바 토글이 쓴다. 그 자리는 드래그 손잡이가 아니다.
 
@@ -133,8 +133,8 @@ main.tsx   applyBootFlags()  →  createRoot(...).render(<App />)
 **창은 보이지 않는 상태로 만들고, 저장된 설정과 지난 세션을 적용한 뒤 보인다.** 읽기는 비동기라 위 절의 동기 경로(`applyBootFlags`)에 넣을 수 없고, 이펙트로 미루면 같은 한 프레임을 잃는다. 무엇을 저장하는지는 [파일 생명주기 정책](../file-lifecycle.md#설정-저장)과 [문서 모델](../document-model.md#세션-복원)이 소유한다.
 
 ```text
-main.tsx  ① 설정을 읽어 스토어에 넣는다 (await, 상한 있음)
-          ② 지난 세션의 탭·루트를 복원한다 (await, 상한 있음 — 탭 본문까지 읽는다)
+main.tsx  ①② 설정 읽기와 지난 세션의 탭·루트 복원을 동시에 기다린다 (Promise.all, 각자 상한 —
+             세션은 탭 본문까지 읽는다)
           ③ applyBootFlags() — 표식·CSS 변수를 심는다
           ④ createRoot(...).render(<App />)
           ⑤ 창을 보인다 — 권한 core:window:allow-show
@@ -148,12 +148,12 @@ main.tsx  ① 설정을 읽어 스토어에 넣는다 (await, 상한 있음)
 
 ```text
 자동  ① 크롬 틴트 대비 기준 — 토큰 값만으로 계산되는 순수 함수라 유닛 테스트가 막는다
-        (→ design-system.md 대비 게이트). **지금 도는 자동 검사는 이것뿐이다.**
+        (→ design-system.md 대비 게이트).
 
 미구현 ② 편집면이 불투명 배경을 칠하는가 (빈 상태·짧은 문서 포함)
       ③ 캔버스가 유리 표식에 따라 갈리는가
-      둘 다 렌더 결과를 봐야 하는데 vitest가 node 환경이라 돌릴 수 없다. 브라우저/DOM 환경
-      도입은 별도 결정이다(→ testing.md). 그때까지는 아래 수동 검증이 이 자리를 지킨다.
+      둘 다 렌더 결과를 봐야 하므로 Vitest Browser Mode로 검증한다(→ testing.md). 테스트를
+      작성하기 전까지는 아래 수동 검증으로 확인한다.
 
 수동  1. 창 뒤에 흰 창을, 다음엔 어두운 창을 두고 크롬 픽셀을 각각 잰다
      2. 두 값이 크게 벌어져야 한다 — 뒤가 비친다는 증거다
diff --git a/.claude/docs/document-model.md b/.claude/docs/document-model.md
index c23ea5f..e9690c9 100644
--- a/.claude/docs/document-model.md
+++ b/.claude/docs/document-model.md
@@ -37,12 +37,11 @@ interface TreeNode {
 interface WorkspaceState {
   rootDir: string | null;    // 사이드바에 표시할 루트 폴더 (다이얼로그가 반환한 canonical 경로)
   fileTree: TreeNode[];      // read_dir(한 단계 목록) 결과를 프론트가 조립한 트리
-                             // 폴더 펼침 상태는 트리 데이터가 아니라 에디터 표현 상태로
-                             // 스토어가 별도 보유한다 — 영속화하지 않는다(접힘 영속화와 동일 원칙)
-  tabs: Tab[];
-  activeTabId: string | null;
-  recentFiles: string[];      // 최근에 연 파일 (→ #최근-파일)
+  expandedDirs: string[];    // 펼쳐진 폴더 — 에디터 표현 상태라 영속화하지 않는다(접힘 영속화와 동일 원칙)
+  recentFiles: string[];     // 최근에 연 파일 (→ #최근-파일)
 }
+
+// 탭 목록·활성 탭(tabs·activeTabId)은 별도 스토어가 갖는다(→ #다중-탭-규칙)
 ```
 
 상태는 Zustand 스토어(`apps/desktop`)가 소유한다. **CM6의 `EditorState`는 스토어에 넣지 않는다** — 큰 불변 객체라 스토어에 두면 비용이 크다. 탭별 에디터 인스턴스가 자체 보유하고, 스토어는 메타데이터(dirty·경로·제목)만 추적한다.
@@ -50,7 +49,7 @@ interface WorkspaceState {
 ## 파일 트리 (사이드바)
 
 - 사이드바는 위에서부터 **파일 트리 · 최근 파일 · 설정** 영역이다. 최근 파일 영역의 규칙은 [최근 파일](#최근-파일)이 소유한다.
-- 루트 폴더를 열면 Rust `read_dir`가 루트 **한 단계**를 반환하고, 폴더를 펼칠 때마다 그 폴더 한 단계를 다시 읽는다(레벨별 lazy — VS Code와 동일, → [Rust 커맨드 계약](rust-commands.md)).
+- 루트 폴더를 열면 Rust `read_dir`가 루트 **한 단계**를 반환하고, 폴더를 처음 펼칠 때 그 폴더 한 단계를 읽는다 — 재펼침은 캐시를 쓴다(레벨별 lazy — VS Code와 동일, → [Rust 커맨드 계약](rust-commands.md)).
 - 트리에는 **디렉터리 전부와 `.md`/`.markdown` 파일만** 표시한다. 필터·정렬·숨김·심볼릭 링크의 결정론적 규칙은 [Rust 커맨드 계약](rust-commands.md)의 `read_dir` 반환 규칙을 단일 출처로 둔다.
 - 중첩 폴더 = 중첩 페이지. 접기/펼치기.
 - 파일 클릭 → 탭으로 연다. 활성 파일은 `aria-selected`로 표시한다. 클릭은 포커스를 트리에 남겨 방향키 탐색을 잇고, 편집 진입(에디터로 포커스)은 `Enter`가 맡는다.
@@ -112,8 +111,8 @@ interface WorkspaceState {
 
 `recentFiles`는 최근에 연 파일의 canonical 경로 목록이다 — 최신이 앞이다.
 
-- **올리는 시점** — 사용자가 파일을 열 때(열기 다이얼로그·파일 트리·최근 파일 목록) · 저장 다이얼로그가 새 경로를 확정할 때(Untitled 첫 저장·다른 이름으로 저장). 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
-- 이미 목록에 있는 경로는 맨 앞으로 옮긴다. **10개**를 넘으면 뒤에서 버린다.
+- **추가하는 시점** — 사용자가 파일을 열 때(열기 다이얼로그·파일 트리·최근 파일 목록·사이드바 새 파일 만들기) · 저장 다이얼로그가 새 경로를 확정할 때(Untitled 첫 저장·다른 이름으로 저장). 경로는 `open_file`/`save_file`이 반환한 canonical 값이다(탭 신원 규칙과 같다). **세션 복원은 목록을 바꾸지 않는다** — 재시작은 사용자가 파일을 연 것이 아니다.
+- 이미 목록에 있는 경로는 맨 앞으로 옮긴다. **10개**를 넘으면 마지막 항목을 제거한다.
 - 영속화는 `session.json`이다(→ [Rust 커맨드 계약](rust-commands.md#세션)). `load_session`이 지금 없는 경로를 걸러 돌려주고, 남은 경로를 파일 단위 허용 루트로 등록한다 — 재시작 뒤 다이얼로그 없이 다시 여는 근거다.
 
 표시 자리는 사이드바의 최근 파일 영역이다(→ [파일 트리](#파일-트리-사이드바)).
@@ -124,15 +123,14 @@ interface WorkspaceState {
 
 ## 세션 복원
 
-마지막 세션을 재시작 때 되살린다. 저장 자리는 셋이다.
+마지막 세션을 재시작 때 복원한다. 두 파일에 나눠 저장한다.
 
 ```text
 탭 목록·활성 탭·루트 폴더·탭별 자리·최근 파일   session.json — Rust가 소유(→ rust-commands.md#세션)
-창 크기·위치                        plugin-window-state
 뷰 모드·사이드바 접힘                설정 파일(→ file-lifecycle.md#설정-저장)
 ```
 
-**탭 경로가 Rust 파일에 사는 이유는 경로 스코프다**(→ [Rust 커맨드 계약 — 권한](rust-commands.md#권한-capabilities)). 세 자리 모두 `.md`가 아니라 앱 config다(→ [파일 생명주기 정책](file-lifecycle.md#앱-상태는-md에-넣지-않는다)).
+**탭 경로를 Rust가 소유하는 파일에 저장하는 이유는 경로 스코프다**(→ [Rust 커맨드 계약 — 권한](rust-commands.md#권한-capabilities)). 두 파일 모두 `.md`가 아니라 앱 config다(→ [파일 생명주기 정책](file-lifecycle.md#앱-상태는-md에-넣지-않는다)).
 
 ```text
 쓰는 시점    탭·루트·최근 파일이 바뀔 때 디바운스 + 창을 닫기 전(→ file-lifecycle.md#종료-방어)
diff --git a/.claude/docs/editor-strategy.md b/.claude/docs/editor-strategy.md
index 25ff9b3..023c2a0 100644
--- a/.claude/docs/editor-strategy.md
+++ b/.claude/docs/editor-strategy.md
@@ -34,11 +34,14 @@ norii의 편집기는 CodeMirror 6 기반 소스 뷰다. 이 문서는 확장 
 | 사이드바 접기/열기 | `Cmd+B` | `Ctrl+B` | 전역 keydown 리스너 |
 | 설정 열기 | `Cmd+,` | `Ctrl+,` | 전역 keydown 리스너 |
 | 다음/이전 탭 | `Ctrl+Tab` / `Ctrl+Shift+Tab` | 동일 | 전역 keydown 리스너 |
+| 탭 닫기 (탭에 포커스) | `Delete` / `Backspace` | 동일 | 탭바 keydown 리스너 |
+| 활성 탭 전환 (탭바에 포커스) | `←` / `→` | 동일 | 탭바 keydown 리스너 |
 | 문서 내 검색 | `Cmd+F` | `Ctrl+F` | `@codemirror/search` 기본 |
 | 접기/펼치기 | `Cmd+Alt+[` / `Cmd+Alt+]` | `Ctrl+Shift+[` / `Ctrl+Shift+]` | CM6 기본 `foldKeymap`(폴딩과 함께 등록) |
+| 전체 접기/펼치기 | `Ctrl+Alt+[` / `Ctrl+Alt+]` | 동일 | CM6 기본 `foldKeymap`(폴딩과 함께 등록) |
 | undo/redo | `Cmd+Z` / `Cmd+Shift+Z` | `Ctrl+Z` / `Ctrl+Y` | CM6 기본 `historyKeymap` |
 
-CM6가 기본 제공하는 키맵(`defaultKeymap`의 표준 편집 조작 · history · search, 폴딩 도입 시 fold)은 그대로 채택한다. 앱 전역 동작(저장·파일·탭)은 CM6 키맵이 **아니라 window keydown 리스너(capture)** 로 처리한다 — CM6 키맵은 에디터가 포커스를 가질 때만 듣지만, 이 동작들은 에디터 밖에 포커스가 있어도 발동해야 한다. capture 단계라 CM6·브라우저 기본 동작보다 먼저 가로채고, OS별 modifier 분기도 여기서 한다. 표에 없는 단축키를 추가할 때는 이 표를 먼저 갱신한다. 저장(`Cmd+S`)은 자동 저장의 예약을 기다리지 않는 **즉시 저장**이다(→ [파일 생명주기 정책 — 자동 저장](file-lifecycle.md#자동-저장)).
+CM6가 기본 제공하는 키맵(`defaultKeymap`의 표준 편집 조작 · history · search, 폴딩 도입 시 fold)은 그대로 채택한다. 앱 전역 동작(저장·파일·탭)은 CM6 키맵이 **아니라 window keydown 리스너(capture)** 로 처리한다 — CM6 키맵은 에디터가 포커스를 가질 때만 듣지만, 이 동작들은 에디터 밖에 포커스가 있어도 발동해야 한다. capture 단계라 CM6·브라우저 기본 동작보다 먼저 가로채고, OS별 modifier 분기도 여기서 한다. 확인 다이얼로그가 떠 있는 동안은 전역 단축키가 전부 멈춘다. 표에 없는 단축키를 추가할 때는 이 표를 먼저 갱신한다. 저장(`Cmd+S`)은 자동 저장의 예약을 기다리지 않는 **즉시 저장**이다(→ [파일 생명주기 정책 — 자동 저장](file-lifecycle.md#자동-저장)).
 
 ## 하이브리드 접기 (아웃라이너 대체)
 
diff --git a/.claude/docs/file-lifecycle.md b/.claude/docs/file-lifecycle.md
index b196389..e5b7030 100644
--- a/.claude/docs/file-lifecycle.md
+++ b/.claude/docs/file-lifecycle.md
@@ -26,7 +26,7 @@ Obsidian처럼 저장을 자동화하되, **자동 병합은 채택하지 않는
 - `Cmd+S`는 예약을 기다리지 않는 **즉시 저장**이고, 남아 있던 예약을 취소한다(→ [에디터 전략 — 단축키 계약](editor-strategy.md#단축키-계약)).
 - **Untitled 탭(`filePath=null`)은 자동 저장 대상이 아니다** — 저장할 경로가 없다. 첫 저장은 수동(`Cmd+S` → 다이얼로그)이며, [종료 방어](#종료-방어)에서 다이얼로그가 뜨는 유일한 평상 케이스다.
 - **정규화 승인 — 저장이 원본 바이트를 재작성하는 탭은 자동 저장이 꺼진 채 열린다.** 현재 두 경우다: ① 비UTF-8로 감지된 파일(`sourceEncoding ≠ 'utf-8'`, UTF-16 포함) — 저장 시 UTF-8로 변환됨, ② 개행이 재작성되는 파일(혼합 EOL·CR-only, `eolMixed`) — 저장 시 판정 EOL로 통일됨. 이런 탭은 배너가 "저장 시 무엇이 바뀌는지"를 알리고, **사용자가 배너에서 승인하거나 첫 수동 저장(`Cmd+S`)을 하면 정규화가 승인된다** — 전역 자동 저장 설정이 끄기가 아닌 경우 그때부터 이 탭도 자동 저장 대상이 된다(승인은 탭 상태이고, 자동 저장 활성은 전역 설정이다 — 승인이 꺼둔 설정을 뒤집지 않는다). 승인 전까지 자동 저장은 그 파일을 건드리지 않는다 — [인코딩 정책](#인코딩-정책)의 "저장 전까지 원본 불변" 안전망을 자동 저장에서도 지키는 규칙이다. 승인 후 첫 저장이 성공하면 탭 메타를 갱신한다(`sourceEncoding='utf-8'`·`eolMixed=false`, 배너 해제) — 변환은 1회로 끝난다. **일반 원칙**: 사용자가 입력하지 않은 바이트 변경을 저장이 수행하게 되는 기능이 향후 추가되면(예: 후행 공백 제거) 그것도 이 승인 대상에 편입한다.
-- **충돌 시 일시 중지**: 자동 저장이 `AppError::Conflict`를 받으면 해당 탭의 자동 저장을 일시 중지하고 충돌 다이얼로그를 띄운다. 사용자가 해소(디스크/편집 선택)하면 재개한다 — 자동 저장이 돌 때마다 다이얼로그가 반복되는 것을 막는다.
+- **충돌 시 일시 중지**: 자동 저장이 `AppError::Conflict`를 받으면 해당 탭의 자동 저장을 일시 중지하고 충돌 배너를 띄운다. 사용자가 해소(디스크/편집 선택)하면 재개한다 — 자동 저장이 돌 때마다 배너가 반복되는 것을 막는다.
 - **자동 병합은 하지 않는다.** Obsidian의 자동 병합(diff-match-patch)은 틀렸을 때 사용자 모르게 내용이 변형된 사례(노트 자가 삭제·내용 뒤섞임)가 보고돼 있다. 충돌은 항상 사용자가 명시적으로 선택한다(→ [외부 변경 처리](#외부-변경-처리)).
 - **실수 삭제 방어**: 자동 저장에서는 "저장 안 하면 그만"이라는 방어선이 사라진다. 세션 내 undo가 1차 방어이고, 주기 스냅샷(Obsidian File Recovery류) 도입은 열린 결정(→ [실제 구현 계획](implementation-plan.md)).
 
@@ -74,10 +74,9 @@ stateDiagram-v2
     saving --> clean: 성공
     saving --> dirty: 성공했지만 저장 중 또 편집됨
     saving --> conflict: 해시 불일치
-    saving --> error: 저장 실패
+    saving --> dirty: 저장 실패(알림)
     conflict --> saving: 내 편집 유지
     conflict --> clean: 디스크 버전 유지
-    error --> dirty: 재시도
 ```
 
 - `saving → dirty`(저장 중 추가 편집)가 **데이터 유실이 새던 자리**다 — 닫기·종료는 저장 성공 응답만 믿지 않고 dirty가 사라질 때까지 재저장한다(→ [종료 방어](#종료-방어)).
@@ -177,7 +176,7 @@ flowchart TD
 
 ## 앱 상태는 `.md`에 넣지 않는다
 
-세션 복원·접힘 상태 같은 UI 상태는 `.md` 본문이 아니라 앱 config/사이드카에 저장한다. `.md`에 메타데이터를 섞으면 파일이 지저분해지고 다른 에디터 호환이 깨진다. 이 경계는 [비목표](../rules/non-goals.md#접힘-상태-영속화의-경계)를 단일 출처로 둔다.
+세션 복원 같은 UI 상태는 `.md` 본문이 아니라 앱 config/사이드카에 저장한다. 접힘 상태는 저장하지 않는다. `.md`에 메타데이터를 섞으면 파일이 지저분해지고 다른 에디터 호환이 깨진다. 이 경계는 [비목표](../rules/non-goals.md#접힘-상태-영속화의-경계)를 단일 출처로 둔다.
 
 ### 설정 저장
 
diff --git a/.claude/docs/implementation-plan.md b/.claude/docs/implementation-plan.md
index b7f137c..1cbfa00 100644
--- a/.claude/docs/implementation-plan.md
+++ b/.claude/docs/implementation-plan.md
@@ -58,6 +58,7 @@ norii의 구현 순서·**구현 상태**와 열린 결정의 단일 출처다.
 ### 에디터 · 세션
 
 - **접힘 상태 영속화** — 사이드카 도입 시점 (→ [에디터 전략](editor-strategy.md) · [비목표](../rules/non-goals.md))
+- **창 크기·위치 복원** — 도입 여부와 방식 (→ [문서 모델](document-model.md#세션-복원))
 - **프리뷰 스크롤** — 프리뷰 자리를 탭별로 따로 기억할지 — 현재는 프리뷰가 편집면의 자리를 따라간다(→ [프리뷰 전략](preview-strategy.md#스크롤-동기화))
 - **심링크 폴더의 외부 변경** — 재귀 감시가 심링크를 넘지 않아 링크 하위의 외부 변경은 트리에 반영되지 않는다 — 계약의 알려진 한계로 명시할지, 링크별 감시 추가로 해소할지 (→ [Rust 커맨드 계약](rust-commands.md) `watch_tree` · [문서 모델](document-model.md#파일-트리-사이드바))
 
diff --git a/.claude/docs/preview-strategy.md b/.claude/docs/preview-strategy.md
index 46b5dad..e4321b6 100644
--- a/.claude/docs/preview-strategy.md
+++ b/.claude/docs/preview-strategy.md
@@ -6,7 +6,7 @@ norii는 소스 옆에 렌더된 프리뷰를 분할로 보여준다. 이 문서
 
 문서 칸은 세 모드로 그린다 — **에디터만 · 분할(기본) · 프리뷰만**. 전환 버튼은 문서 칸 위의 바에 있다.
 
-- 모드는 세션 한정 전역 상태다 — 저장 여부는 탭 세션 복원과 함께 정한다(→ [문서 모델](document-model.md#세션-복원) · [실제 구현 계획](implementation-plan.md)).
+- 모드는 전역 상태로 관리한다 — 바꾸면 설정 파일에 저장되고, 다음 실행이 그 모드로 시작한다(→ [파일 생명주기 정책 — 설정 저장](file-lifecycle.md#설정-저장)).
 - **전환은 패널을 언마운트하지 않고 숨긴다.** 에디터를 내리면 편집 상태(undo·커서)가 사라지므로, 프리뷰만 모드에서도 에디터는 DOM에 남는다.
 - **숨은 프리뷰는 렌더를 쉰다.** 보이지 않는 파싱·다이어그램 렌더에 키 입력마다 비용을 내지 않는다 — 다시 보일 때 한 번 렌더로 따라잡는다.
 - **탭이 없으면 모드와 무관하게 에디터의 빈 상태만 전체 폭으로 보인다.** 안내(⌘N·⌘O)가 모드에 가려 숨지 않고, 빈 프리뷰 칸도 남지 않는다.
@@ -144,7 +144,7 @@ mermaid                     다이어그램  플러그인 아님 — fence 렌
 프리뷰의 코드 블록에 마우스를 올리면 오른쪽 위에 복사 버튼이 뜨고, 누르면 코드가 클립보드에 들어간다.
 
 - **문서를 바꾸지 않는다.** 버튼은 파서가 아니라 소비 측이 프리뷰 DOM에 붙이는 UI다 — `.md`에는 아무것도 남지 않는다.
-- 버튼은 **코드 블록에 마우스를 올렸을 때만** 나타난다 — 읽는 동안에는 화면에 없다.
+- 버튼은 평소 숨겨져 있다 — 코드 블록에 마우스를 올렸을 때, 버튼이 키보드 포커스를 받았을 때, 복사됨 상태일 때만 보인다.
 - **프리뷰가 다시 렌더될 때마다 버튼은 사라진다** — 내용을 `innerHTML`로 통째로 교체하기 때문이다(→ [프리뷰 DOM은 React가 소유하지 않는다](#프리뷰-dom은-react가-소유하지-않는다)). 다이어그램 SVG와 같은 경로로 **삽입 뒤 다시 붙인다.** 버튼은 React 컴포넌트이고, 삽입 뒤 코드 블록을 다시 수집해 **포털로 꽂는다** — 비 React 내용 속에서 버튼만 예외로 React가 소유한다(아이콘·복사됨 상태·타이머 관리).
 - **코드 블록마다 네이티브 리스너를 달지 않는다** — 블록 수만큼 리스너가 생기고 매 렌더마다 다시 등록되기 때문이다. 포털 버튼의 클릭은 React 합성 이벤트(루트 위임 하나)를 탄다.
 - 복사할 원문은 렌더된 텍스트가 아니라 **코드 블록의 원문**이다.
diff --git a/.claude/docs/rust-commands.md b/.claude/docs/rust-commands.md
index 64eccee..8020532 100644
--- a/.claude/docs/rust-commands.md
+++ b/.claude/docs/rust-commands.md
@@ -206,7 +206,7 @@ fn set_window_blur_radius(window: tauri::WebviewWindow, radius: u32);
 
 ```rust
 #[tauri::command]
-fn load_session() -> Result<Option<Session>, AppError>;
+async fn load_session() -> Result<Option<Session>, AppError>;
 // 지난 세션을 읽고, 그 안의 경로(루트 폴더·탭)를 허용 루트로 등록한다 — 재시작 뒤에도
 // 다이얼로그 없이 그 파일을 열 수 있게 하는 유일한 통로다(→ 권한).
 // 파일이 없거나 JSON이 깨졌으면 None — 손으로 고칠 수 있는 파일이라 읽기 실패는 오류가 아니다.
@@ -215,7 +215,7 @@ fn load_session() -> Result<Option<Session>, AppError>;
 // 활성 탭이 걸러지면 active는 빈다 — 프론트가 남은 첫 탭을 활성으로 만든다(→ document-model.md#세션-복원).
 
 #[tauri::command]
-fn save_session(session: Session) -> Result<(), AppError>;
+async fn save_session(session: Session) -> Result<(), AppError>;
 // 지금 세션을 덮어쓴다(원자적 쓰기). 이미 허용된 경로만 기록한다 — 웹뷰가 넘긴 경로가
 // 다음 부팅의 허용 루트가 되는 길을 막는다.
 
@@ -296,7 +296,6 @@ encoding_rs          인코딩 변환 (레거시 → UTF-8, BOM)
 chardetng            인코딩 감지 (→ file-lifecycle.md 열기 파이프라인)
 plugin-dialog        show_open_dialog / show_save_dialog
 plugin-store         설정 저장(→ file-lifecycle.md#설정-저장)
-plugin-window-state  창 크기·위치 저장·복원 (→ document-model.md)
 plugin-log           통합 로깅 (→ error-handling.md)
 ```
 
diff --git a/.mise.toml b/.mise.toml
index ca1189a..f9443c7 100644
--- a/.mise.toml
+++ b/.mise.toml
@@ -94,7 +94,7 @@ dir = "apps/desktop"
 run = "pnpm test:e2e"
 
 [tasks.verify-native]
-description = "네이티브 검증(표준 창 버튼 중앙·드래그 불변식·전체화면 토글 클릭) — 실제 OS 입력이라 앱을 최상위로 세운다(dev-webdriver 필요, 로컬 전용)"
+description = "네이티브 검증(표준 창 버튼 중앙·드래그 불변식·전체화면 토글 클릭·한글 조합 확정 입력) — 실제 OS 입력이라 앱을 최상위로 세운다(dev-webdriver 필요, 로컬 전용)"
 dir = "apps/desktop"
 run = "node e2e/verify-native.mjs"
 
diff --git a/apps/desktop/e2e/file-lifecycle.e2e.ts b/apps/desktop/e2e/file-lifecycle.e2e.ts
index 1fd667c..3eb2e7a 100644
--- a/apps/desktop/e2e/file-lifecycle.e2e.ts
+++ b/apps/desktop/e2e/file-lifecycle.e2e.ts
@@ -280,7 +280,7 @@ it("빈 상태 — 버튼이 뜨고 새 문서 버튼이 Untitled 탭을 연다"
   await (await browser.$('[data-testid="empty-state"]')).waitForExist({ timeout: 5_000 });
 });
 
-// 집행: document-model.md#최근-파일 — 연 파일이 목록에 올라간다.
+// 집행: document-model.md#최근-파일 — 연 파일이 목록에 추가된다.
 //       표시·클릭 열기 규칙도 같은 절이 소유한다.
 // 왜: 저장(세션)·갱신(스토어)이 각자 옳아도, 목록 표시 → 클릭 → 다시 열기의
 //     끝단 배선은 실앱에서만 확인된다.
diff --git a/apps/desktop/src/features/open-file/model/open-file.ts b/apps/desktop/src/features/open-file/model/open-file.ts
index dc5f33f..b937f50 100644
--- a/apps/desktop/src/features/open-file/model/open-file.ts
+++ b/apps/desktop/src/features/open-file/model/open-file.ts
@@ -42,7 +42,7 @@ export async function openPathInTab(
   try {
     const file = await ipc.openFile(path);
     useDocumentStore.getState().openFileTab(file, focusEditor);
-    // 최근 파일은 canonical 경로다 — 요청 문자열이 아니라 열기 결과를 올린다
+    // 최근 파일은 canonical 경로다 — 요청 문자열이 아니라 열기 결과를 추가한다
     // (→ document-model.md#최근-파일).
     useWorkspaceStore.getState().noteRecentFile(file.path);
   } catch (error) {

From 8c1a9b38623fedf49a03cec77cdfde7a4624c9bd Mon Sep 17 00:00:00 2001
From: Bori-github <qhflrnfl4324@gmail.com>
Date: Sun, 9 Aug 2026 13:46:19 +0900
Subject: [PATCH 18/18] =?UTF-8?q?fix(rust):=20=EC=A0=80=EC=9E=A5=20?=
 =?UTF-8?q?=EB=8B=A4=EC=9D=B4=EC=96=BC=EB=A1=9C=EA=B7=B8=EA=B0=80=20?=
 =?UTF-8?q?=EC=97=B4=EB=A6=B0=20=ED=8F=B4=EB=8D=94=EC=97=90=EC=84=9C=20?=
 =?UTF-8?q?=EC=8B=9C=EC=9E=91=ED=95=98=EB=8F=84=EB=A1=9D=20rfd=20=EC=A0=9C?=
 =?UTF-8?q?=EC=95=BD=EC=9D=84=20=EC=9A=B0=ED=9A=8C=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

rfd가 set_directory와 set_file_name을 함께 받으면 시작 위치를 시작폴더/파일명으로 합쳐
존재하지 않는 경로로 만들어 무효화한다 — 그래서 폴더를 연 상태에서 저장 다이얼로그가
열린 폴더가 아니라 OS 마지막 위치에서 시작했다. 시작 위치를 줄 때는 파일명을 붙이지
않아 다이얼로그가 열린 폴더에서 시작하게 한다.

트레이드오프: start_dir이 있으면 파일명 기본값(default_name)이 제안되지 않는다. rfd가
둘을 동시에 받지 못하므로 시작 위치를 택했다. 근본 원인은 rfd에 있어 업스트림 수정 시
우회를 걷어낸다.

네이티브 저장 다이얼로그라 자동 검증이 불가해 실앱에서 수동 확인했다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/rust-commands.md                 |  7 ++++---
 apps/desktop/src-tauri/src/dialog_commands.rs | 10 ++++++----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/.claude/docs/rust-commands.md b/.claude/docs/rust-commands.md
index 8020532..d47330b 100644
--- a/.claude/docs/rust-commands.md
+++ b/.claude/docs/rust-commands.md
@@ -177,9 +177,10 @@ async fn show_open_dialog() -> Result<Option<String>, AppError>;
 async fn show_save_dialog(default_name: String, start_dir: Option<String>) -> Result<Option<String>, AppError>;
 // 두 다이얼로그 모두 Markdown 필터(.md·.markdown — read_dir 필터와 동일 집합)를 걸고,
 // 취소하면 None을 반환한다. 선택된 경로는 허용 루트로 등록된다(→ 권한)
-// start_dir가 존재하는 디렉터리면 다이얼로그가 거기서 시작한다 — 아니면 OS가 정한 위치에서
-// 연다. 웹뷰는 사이드바 루트를 넘긴다(폴더를 열지 않았으면 None). 시작 위치일 뿐 허용과
-// 무관하다 — 허용 루트 등록은 사용자가 선택한 경로로만 한다
+// start_dir가 존재하는 디렉터리면 다이얼로그가 거기서 시작하고, 이때 default_name은 파일명
+// 기본값으로 제안되지 않는다(rfd 제약 → dialog_commands.rs). start_dir이 없으면 OS가 정한
+// 위치에서 열고 default_name을 제안한다. 웹뷰는 사이드바 루트를 넘긴다(폴더를 열지 않았으면
+// None). 시작 위치일 뿐 허용과 무관하다 — 허용 루트 등록은 사용자가 선택한 경로로만 한다
 
 #[tauri::command]
 async fn show_open_folder_dialog() -> Result<Option<String>, AppError>;
diff --git a/apps/desktop/src-tauri/src/dialog_commands.rs b/apps/desktop/src-tauri/src/dialog_commands.rs
index 9c7bc08..bebc85c 100644
--- a/apps/desktop/src-tauri/src/dialog_commands.rs
+++ b/apps/desktop/src-tauri/src/dialog_commands.rs
@@ -48,11 +48,13 @@ pub async fn show_save_dialog(
     let mut dialog = app
         .dialog()
         .file()
-        .add_filter("Markdown", MARKDOWN_EXTENSIONS)
-        .set_file_name(&default_name);
+        .add_filter("Markdown", MARKDOWN_EXTENSIONS);
     // 존재하는 디렉터리일 때만 시작 위치로 쓴다(→ rust-commands.md#다이얼로그).
-    if let Some(dir) = start_dir.map(PathBuf::from).filter(|dir| dir.is_dir()) {
-        dialog = dialog.set_directory(dir);
+    // rfd가 set_directory와 set_file_name을 함께 받으면 시작 위치를 시작폴더/파일명으로
+    // 합쳐 무효화하므로, 시작 위치를 줄 때는 파일명을 붙이지 않는다.
+    match start_dir.map(PathBuf::from).filter(|dir| dir.is_dir()) {
+        Some(dir) => dialog = dialog.set_directory(dir),
+        None => dialog = dialog.set_file_name(&default_name),
     }
     let picked = dialog.blocking_save_file();
     let Some(file_path) = picked else {