feat(kebab-tui): P9-1 Ratatui shell + Library pane

새 crate `kebab-tui` 가 §8 facade rule 따라 `kebab-app` 만 import.
Ratatui 0.28 + crossterm 0.28 기반 shell 이 다음을 제공:

- `App` 구조체: config + focus + library + 3 Option sub-state slot
  (search/ask/inspect — p9-2/3/4 가 자기 모듈에서 채우는 parallel-safety
  contract). p9-1 외에 App 정의 손대지 않음.
- `Pane` enum (Library/Search/Ask/Inspect/Jobs).
- `KeyOutcome` (Continue/Quit/SwitchPane/Refresh).
- `LibraryState` + 내부 inner: docs / list_state / filter / filter_edit /
  needs_refresh / loading / pending_g.
- `render_library` (Frame, area, &App) — heading/body, filter overlay
  toggleable, Korean/wide-char 너비는 unicode-width 로 계산.
- `handle_key_library`: j/k/Down/Up 이동, gg/G 끝, f 필터 overlay,
  /=>Search ?=>Ask Enter=>Inspect, q/Esc 종료. error overlay 가 켜
  있으면 어떤 키든 dismiss.
- 필터 overlay: tags_any (CSV) + lang 두 필드, Tab cycle, Enter
  apply→Refresh, Esc cancel.
- `ErrorOverlay`: anyhow chain 캡쳐 후 popup 렌더 (Clear + 빨간 border).
- 터미널 lifecycle: `TuiTerminal` 가 enter raw mode + alt screen,
  Drop 이 종료 시 (panic 포함) restore — 사용자 쉘 깨지지 않게.
- 비동기 없음: facade 호출은 main thread 동기. v1 의 brief hang 수용.

CLI: `kebab tui` 서브커맨드 추가, --config 받아 App::new + run.

테스트 10건 (`tests/library.rs`, TestBackend 사용):
- 빈 library / 3-doc render / q,Esc quit / / Search 전환 / ? Ask 전환
- Enter 빈 list 무동작 / Enter Inspect 전환 / j 이동 (3-step clamp) /
  f 필터 overlay → 입력 → Enter Refresh.

Test seam: `App::populate_library_for_testing` (#[doc(hidden)]) 가
`pub(crate)` inner 를 우회. spec parallel-safety contract 그대로 유지.

Spec deviation (HOTFIXES `2026-05-02 P9-1`):
- `render_library` 의 `<B: Backend>` generic 제거 — ratatui 0.28 의 Frame
  이 backend-agnostic.
- `populate_library_for_testing` 추가 (test seam, 공식 API 아님).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/kebab-tui/tests/library.rs

@@ -0,0 +1,217 @@
+//! Unit + snapshot tests for the Library pane.
+//!
+//! Snapshot tests use `ratatui::backend::TestBackend` so the run loop
+//! is bypassed entirely — we drive `render_library` directly against
+//! a synthetic `App`.
+
+use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+use kebab_config::Config;
+use kebab_core::{
+    ChunkerVersion, DocSummary, DocumentId, Lang, ParserVersion, SourceType, TrustLevel,
+    WorkspacePath,
+};
+use kebab_tui::{App, KeyOutcome, Pane, render_library};
+use ratatui::Terminal;
+use ratatui::backend::TestBackend;
+use ratatui::layout::Rect;
+use time::OffsetDateTime;
+
+fn make_doc(path: &str, title: &str, tags: Vec<&str>) -> DocSummary {
+    DocSummary {
+        doc_id: DocumentId(format!("{:0<32}", path.chars().filter(|c| c.is_alphanumeric()).collect::<String>())),
+        doc_path: WorkspacePath::new(path.into()).unwrap(),
+        title: title.into(),
+        lang: Lang("en".into()),
+        tags: tags.into_iter().map(String::from).collect(),
+        trust_level: TrustLevel::Primary,
+        source_type: SourceType::Note,
+        byte_len: 1024,
+        chunk_count: 4,
+        created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+        updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+        parser_version: ParserVersion("test-parser".into()),
+        chunker_version: ChunkerVersion("test-chunker".into()),
+    }
+}
+
+fn app_with_docs(docs: Vec<DocSummary>) -> App {
+    let mut config = Config::defaults();
+    // Storage paths point at /tmp so any accidental facade call
+    // would not touch the user's real KB. Tests below use the
+    // `populate_library_for_testing` test seam, never the facade.
+    config.storage.data_dir = "/tmp/kebab-tui-tests-noop".to_string();
+    let mut app = App::new(config).expect("App::new must succeed with defaults");
+    app.populate_library_for_testing(docs);
+    app
+}
+
+#[test]
+fn empty_library_renders_block_only_no_panic() {
+    let app = app_with_docs(vec![]);
+    let backend = TestBackend::new(80, 20);
+    let mut terminal = Terminal::new(backend).unwrap();
+    terminal
+        .draw(|f| {
+            let area = Rect::new(0, 0, 80, 20);
+            render_library(f, area, &app);
+        })
+        .unwrap();
+    let buffer = terminal.backend().buffer().clone();
+    let rendered: String = (0..buffer.area.height)
+        .map(|y| {
+            (0..buffer.area.width)
+                .map(|x| buffer[(x, y)].symbol())
+                .collect::<String>()
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    assert!(
+        rendered.contains("Library"),
+        "rendered frame must show Library header: {rendered}"
+    );
+    assert!(
+        rendered.contains("no docs") || rendered.contains("Library"),
+        "empty state hint should appear in the header line"
+    );
+}
+
+#[test]
+fn handle_key_library_q_quits() {
+    let mut app = app_with_docs(vec![]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::Quit);
+}
+
+#[test]
+fn handle_key_library_esc_quits_when_no_overlay() {
+    let mut app = app_with_docs(vec![]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::Quit);
+}
+
+#[test]
+fn handle_key_library_slash_switches_to_search() {
+    let mut app = app_with_docs(vec![]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('/'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::SwitchPane(Pane::Search));
+}
+
+#[test]
+fn handle_key_library_question_switches_to_ask() {
+    let mut app = app_with_docs(vec![]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('?'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::SwitchPane(Pane::Ask));
+}
+
+#[test]
+fn handle_key_library_enter_does_not_switch_when_empty() {
+    let mut app = app_with_docs(vec![]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::Continue);
+}
+
+#[test]
+fn library_with_docs_renders_titles() {
+    let app = app_with_docs(vec![
+        make_doc("notes/foo.md", "Foo", vec!["alpha"]),
+        make_doc("notes/bar.md", "Bar", vec!["beta", "gamma"]),
+        make_doc("notes/baz.md", "Baz Title", vec![]),
+    ]);
+    let backend = TestBackend::new(80, 10);
+    let mut terminal = Terminal::new(backend).unwrap();
+    terminal
+        .draw(|f| {
+            let area = Rect::new(0, 0, 80, 10);
+            render_library(f, area, &app);
+        })
+        .unwrap();
+    let buffer = terminal.backend().buffer().clone();
+    let rendered: String = (0..buffer.area.height)
+        .map(|y| {
+            (0..buffer.area.width)
+                .map(|x| buffer[(x, y)].symbol())
+                .collect::<String>()
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    for title in &["Foo", "Bar", "Baz Title"] {
+        assert!(
+            rendered.contains(title),
+            "rendered must contain {title}, got:\n{rendered}"
+        );
+    }
+}
+
+#[test]
+fn handle_key_library_arrow_down_moves_selection() {
+    let mut app = app_with_docs(vec![
+        make_doc("a.md", "A", vec![]),
+        make_doc("b.md", "B", vec![]),
+        make_doc("c.md", "C", vec![]),
+    ]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('j'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::Continue);
+    let outcome2 = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('j'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome2, KeyOutcome::Continue);
+    // Third j hits the bottom; clamp must not panic / overflow.
+    let outcome3 = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('j'), KeyModifiers::NONE),
+    );
+    assert_eq!(outcome3, KeyOutcome::Continue);
+}
+
+#[test]
+fn handle_key_library_enter_inspects_when_docs_present() {
+    let mut app = app_with_docs(vec![make_doc("a.md", "A", vec![])]);
+    let outcome = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE),
+    );
+    assert_eq!(outcome, KeyOutcome::SwitchPane(Pane::Inspect));
+}
+
+#[test]
+fn handle_key_library_f_opens_filter_overlay_then_enter_refreshes() {
+    let mut app = app_with_docs(vec![make_doc("a.md", "A", vec![])]);
+    // Open filter.
+    let o1 = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Char('f'), KeyModifiers::NONE),
+    );
+    assert_eq!(o1, KeyOutcome::Continue);
+    // Type into tags buffer.
+    for ch in "foo".chars() {
+        kebab_tui::handle_key_library(
+            &mut app,
+            KeyEvent::new(KeyCode::Char(ch), KeyModifiers::NONE),
+        );
+    }
+    // Enter commits + refreshes.
+    let o2 = kebab_tui::handle_key_library(
+        &mut app,
+        KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE),
+    );
+    assert_eq!(o2, KeyOutcome::Refresh);
+}