# Librarian Refactor — Ticket Log (self-implemented)

## Context

`crates/librarian-app/src/main.rs` has grown to **4308 lines** — nearly half the
whole workspace in one file. Everything else is already reasonably modularized
(next-largest source file is 646 lines, and most of *that* is tests). The goal is
to break `main.rs` into ~9–10 focused modules following SRP, then a final DRY
pass to remove the repeated patterns the analysis found — **without changing any
behavior**.

You (not Claude) are implementing this to learn Rust, ticket by ticket, asking
questions as you go. The tickets are ordered **safest-first**: pure mechanical
moves you can verify with `cargo build` before anything that could change runtime
behavior. DRY consolidation is deliberately saved for the end (Phase 5) so every
earlier ticket is a "no behavior change" move.

Scope: `main.rs` + `tree.rs` (test relocation only). `librarian-win/icon.rs` is
out of scope.

---

## The 3 Rust mechanics you need (read this first)

Everything below uses one of three moves. Learn these and the tickets are
mechanical.

**1. Leaf module (for *pure functions* — no `self`).**
The styling functions, keyboard predicates, and column-math functions don't touch
the app struct. Move them to a new file, add `mod foo;` to `main.rs`, and call
them as `foo::bar(...)`. This is exactly how `metrics.rs` / `rows.rs` already
work. *Zero behavioral risk.*

**2. Split `impl` block (for *methods* — `&self` / `&mut self`).**
`view()`, `update()`, and all the `view_*` / handler methods take `self`. Rust
lets an `impl Librarian { … }` block live in **any file in the same crate**. So
you create `view.rs`, write `use crate::*;` then `impl Librarian { pub(crate) fn
view_toolbar(&self) -> … { … } }`, and the call site `self.view_toolbar()` in
`main.rs` is **unchanged**. You are physically moving the method, not rewriting
the call.

**3. The one visibility rule that will bite you.**
A child module (e.g. `view`) can freely *see* private items of `main.rs` —
descendants can read their ancestors' privates. But `main.rs` **cannot** see a
private item of its child. So:
- Any method/type you move *out* of `main.rs` must become **`pub(crate)`** (so
  `main.rs` and sibling modules can still call it).
- Anything that *stays* in `main.rs` (e.g. `recompute_rows`, the `Librarian`
  struct, the `Message` enum, constants) needs **no change** — the new child
  modules can already see it.

Rule of thumb: **the thing you move gets `pub(crate)`; the things it calls back
into don't.**

> Shrinking `update()` (a 600-line `match`): you can't split one `match` across
> files. Instead, move each complex arm's *body* into a `pub(crate)` handler
> method in the right module, and replace the arm with a one-liner, e.g.
> `Message::Delete => return self.delete_selected(),`. The `match` stays in
> `main.rs` but collapses to a dispatch table.

---

## Target module layout (`crates/librarian-app/src/`)

Existing (leave as-is): `columns config ellipsis icons metrics rows search
selection theme thumbs tree`.

New files this refactor adds:

| New file | Responsibility | Mechanism |
|---|---|---|
| `styles.rs` | All `*_style()` fns + tiny pure element helpers (dividers, tooltip, `loading_overlay`, `view_header`, `gap`) | Leaf |
| `keyboard.rs` | `key_to_message`, `is_input_shortcut`, `is_text_edit`, `clear_focus` | Leaf |
| `columns.rs` (extend) | `compute_col_px`, `measure_columns`, `sample_widest`, `width_bounds`, `sort_key_of` | Leaf (into existing) |
| `view.rs` | Window chrome: `view`, tabs, toolbar, status, command bar, tree view, context menu, empty-state | impl-split |
| `view_details.rs` | Details list: `view_details`, `view_list`, `view_row` | impl-split |
| `view_grid.rs` | Icon grid: `view_body`, `view_grid`, `view_tile` | impl-split |
| `grid_session.rs` | Thumbnail session coordination + `ThumbsCached/ThumbsLoaded` arms | impl-split |
| `tabs.rs` | `TabState` + snapshot/restore/switch/new/close + tab arms | impl-split + struct |
| `fileops.rs` | `dispatch_op`, file-op arms, selection-path helpers, `unique_folder_name` | impl-split + free fn |
| `navload.rs` | `load_current`/`navigate`, folder-load arms, dir-watch, tree building/reveal | impl-split + free fns |

`main.rs` keeps: the `Librarian` struct, the `Message` enum, shared small enums
(`Content`, `ViewMode`, `PaneKind`, `Nav`, …), constants, `new()`/`title()`/
`subscription()`, the `update()` dispatch `match`, and a handful of cross-cutting
orchestration methods (`recompute_rows`, `request_icons`, `settings`,
`apply_sort`, `scroll_to`, `ensure_visible`, `move_selection`, `on_click`,
`activate`). Target: **~600–800 lines**.

> Line numbers below are anchors from the current file and *will drift* as you
> edit. Navigate by **function name** (search), not by line number.

---

## Conventions to follow (match the existing code)

- Files `snake_case`; types `PascalCase`; free fns `snake_case`.
- One `mod foo;` per new file, alphabetically grouped with the others at the top
  of `main.rs`. Add `use crate::foo::{…}` imports next to the existing block.
- Modules don't define `Message` and don't take `&mut Librarian` as a *parameter*
  — instead they're either leaf free-fns or `impl Librarian` blocks (methods).
- Keep each module's doc-comment header (`//! …`) describing its one job, like
  `tree.rs` and `thumbs.rs` do.
- Colocate any moved `#[cfg(test)]` with its code.

---

## Phase 0 — Baseline (do once, before Ticket 1)

**T0. Establish a green baseline & checkpoint discipline.**
- Run `cargo build -p librarian-app`, `cargo clippy --workspace`,
  `cargo test --workspace`, and launch `cargo run -p librarian-app` once. Note the
  current warning count.
- Commit the clean state. **After every ticket: `cargo build` + `cargo clippy` +
  launch the app + commit.** A ticket isn't done until it builds clean and the app
  still looks/behaves identically.

---

## Phase 1 — Pure leaf extractions (lowest risk, do first)

These move *only* free functions. If it compiles, it's correct.

**T1. Extract `styles.rs`.**
Move the styling block (~`3029–3432`): every `*_style()` fn plus the small pure
element/builder helpers in that range — `gap`, `full_path_text`, `path_tooltip`,
`header_rule`, `tree_section_divider`, `column_divider`, `view_header`,
`loading_overlay`. Add `mod styles;`, mark each moved fn `pub(crate)`, add
`use crate::styles::*;` (or explicit names) in `main.rs`. Some take `&Theme` /
`spinner_frame: usize` — pass-through, no `self`.
*Verify:* compiles; app visuals identical (selection highlight, dividers, tabs,
loading overlay).

**T2. Extract `keyboard.rs`.**
Move `is_input_shortcut`, `is_text_edit`, `clear_focus`, `key_to_message`
(~`3556–3650`). All free fns over `&Message` / `Key`. Mark `pub(crate)`; fix the
call sites in `subscription()` and at the top of `update()`.
*Verify:* compiles; keyboard nav, Ctrl-shortcuts, and typing in the address/search
/rename fields all still work (the overlay-suppression check at `update` line
~1065 still calls `is_input_shortcut`/`is_text_edit`).

**T3. Consolidate column math into `columns.rs`.**
Move `compute_col_px`, `width_bounds`, `sort_key_of` (~`3815–3870`),
`measure_columns` (~`2167–2220`), and `sample_widest` out of `main.rs` into the
existing `columns.rs` (their natural home — they already operate on
`ColumnLayout`/`Column`). Make them `pub` in `columns.rs`. If any need
`measure_width`/`LIST_TEXT_SIZE`, import from `metrics` there.
*Verify:* compiles; column auto-fit, drag-resize, and header sort-arrow widths
behave identically.

---

## Phase 2 — View impl-split (low risk: moving `&self` methods)

Do **T1 first** — these call the now-`pub(crate)` style fns. Pure render methods,
no state mutation, so behavior can't change if it compiles; spot-check visuals.

**T4. Extract `view.rs` (chrome).**
Move methods: `view`, `view_tabs`, `view_tab`, `view_toolbar`, `view_status`,
`view_command_bar`, `view_tree`, `view_tree_row`, `view_context_menu`,
`empty_list_message`. Create `view.rs` with `use crate::*;` and `impl Librarian {
… }`; mark each `pub(crate)`. (`view` itself is required by the Iced `update`/`view`
wiring — confirm it's still found; if the framework needs it on the original impl,
keep just `view`'s signature delegating, or move it too and ensure the trait/inherent
lookup still resolves.)
*Verify:* compiles; toolbar, tabs, status bar, command bar, tree sidebar, and
right-click menu all render and respond.

**T5. Extract `view_details.rs`.**
Move `view_details`, `view_list`, `view_row` (~`2547–2587`, `2729–2844`). These
call `compute_col_px`/`measure_columns` (now in `columns.rs` from T3) and styles
(T1) — import them.
*Verify:* details list renders; virtualization (scroll), inline rename field, and
per-column ellipsis all intact.

**T6. Extract `view_grid.rs`.**
Move `view_body`, `view_grid`, `view_tile` (~`2594–2597`, `2850–2953`).
*Verify:* all icon-grid sizes (Tiny→ExtraLarge) render; thumbnails appear; tile
rename field works.

---

## Phase 3 — Stateful impl-split (moves `&mut self` methods + update arms)

Higher care: these mutate state and own update-arm logic. Move the methods, then
collapse each related `update` arm to a one-line delegating call.

**T7. Extract `grid_session.rs` (thumbnail coordination).**
Move `begin_grid_session`, `prefetch_thumbs`, `retain_visible_misses`,
`extract_full_task`, `seed_background`, `next_background_chunk`,
`visible_thumb_keys` (~`2243–2366`) and the `thumb_key` free fn. Add a
`pub(crate) fn handle_thumbs_cached/loaded(...)` and move the `ThumbsCached` /
`ThumbsLoaded` arm bodies (~`1335–1397`) into them; replace arms with delegating
calls. Keep `ThumbKind` where it's referenced (move to this module as `pub(crate)`
if only used here).
*Verify:* switch to a grid view in an image folder — loading overlay raises/clears,
viewport thumbs load first, background pre-cache fills in on scroll.

**T8. Extract `tabs.rs`.**
Move `TabState` (~`745–819`) and `snapshot_flat`/`restore_flat`/`reset_flat`/
`show_active`/`switch_tab`/`new_tab`/`close_tab`. Move the tab arm bodies
(`NewTab`/`SelectTab`/`CloseTab`/`CloseActiveTab`/`NextTab`/`PrevTab`/
`OpenInNewTab`, ~`1401–1430`) into `pub(crate)` handler methods. `TabState` and its
fields used by `main.rs` become `pub(crate)`.
*Note:* the active tab's state lives directly on `Librarian`; only parked tabs are
`Some(TabState)`. Preserve that exactly — `snapshot_flat`/`restore_flat` are the
only places that convert between the two.
*Verify:* open/close/switch/cycle tabs; each tab restores its own folder, scroll,
selection, columns.

**T9. Extract `fileops.rs`.**
Move `dispatch_op` and the file-op arm bodies (`OpenSelected`, `NewFolder`,
`DeleteSelected`, `Copy`, `Cut`, `Paste`, `RenameStart/Changed/Commit`,
`OpFinished`, ~`1560–1657`) into `pub(crate)` handler methods; move
`unique_folder_name` (~`3544–3554`), `selected_paths`, `current_dir`, `lead_path`,
`restore_selection`, `begin_pending_rename`. Keep calling `librarian-win`
(`copy_items`, `move_items`, `delete_to_recycle`, `rename`, `create_folder`) from
here — that's the right layering.
*Verify:* create folder (+ auto-rename), rename, delete-to-recycle, cut/copy/paste,
open — and the listing auto-refreshes after each (`OpFinished`).

**T10. Extract `navload.rs` (navigation + async loading + dir watch + tree build).**
Move `load_current`/`navigate`/reset helpers (~`1754–1831`), the load arm bodies
(`ThisPcLoaded`, `WslLoaded`, `Loaded`, `Reloaded`, `DirChanged`, ~`1192–1313`),
`watch_stream` (~`3684–3725`), and the tree-building free fns + factories
(`fetch_tree_roots`, `fetch_tree_children`, `home/this_pc/wsl_tree_child`,
`tree_child_from_*`, ~`3444–3542`) plus tree arm bodies (`TreeToggle`,
`TreeNavigate`, `TreeChildrenLoaded`, `PaneResized`, ~`1432–1473`) and
`load_tree_roots`/`load_tree_children`/`drive_reveal`.
*This is the biggest stateful ticket — consider splitting into T10a (folder load +
watch) and T10b (tree build/reveal) if it feels too large.*
*Verify:* navigate via address bar, tree clicks, back/forward/up; This PC + WSL
listings; external file changes auto-refresh; revealing a deep path expands the
tree.

---

## Phase 4 — `tree.rs` (test relocation only)

**T11. Move `tree.rs` tests into `src/tree/tests.rs`.**
`tree.rs` logic (lines 1–371) is already SRP-clean — **leave it alone.** Only the
275-line `#[cfg(test)] mod tests` block (372–646) inflates it. Replace that block
in `tree.rs` with `#[cfg(test)] mod tests;`, create `src/tree/tests.rs`, paste the
test bodies there with `use super::*;` at the top. (A file-module `tree.rs` can own
a child module file at `src/tree/tests.rs` — no `mod.rs` needed.)
*Verify:* `cargo test -p librarian-app` runs the same tree tests, all green.

---

## Phase 5 — DRY consolidation (separate final phase)

Now that concerns live in the right modules, remove the repeated patterns the
analysis found. **These change code paths**, so do them one at a time with a build
+ run between each. Each becomes a small helper on `Librarian` (or a free fn)
placed in the owning module.

**T12. `recompute_rows` + status string (4×).** Sites: load/reload arms
(~`1196`, `1205`, `1221`, `1289`). Extract `fn refresh_listing_status(&mut self)`
that does `recompute_rows()` + `self.status = format!("{n} items")`.

**T13. Selection preserve/restore (2×).** Sites ~`1154`, `1288`. Extract
`fn recompute_preserving_selection(&mut self)` wrapping
`selected_paths` → `recompute_rows` → `restore_selection`.

**T14. Icon+thumbnail warm batches (5×).** Sites ~`1095`, `1158`, `1178`, `1199`,
`1224`. Extract small helpers like `warm_content(lock)` / `warm_after_search()`
returning the `Task::batch([...])` so handlers read intent, not wiring. (Land this
in `grid_session.rs`.)

**T15. File-op status strings (3×).** Sites ~`1582/1590/1598`. Extract
`fn op_label(verb: &str, count: usize) -> String` (uses existing `plural`). Lives
in `fileops.rs`.

**T16. Icon-or-placeholder render (2×).** Sites `view_tree_row` ~`2469`, `view_row`
~`2766`. Extract `fn icon_element(&self, key, size) -> Element<'_, Message>`.

**T17. Inline rename field (2×).** Sites `view_row` ~`2775`, `view_tile` ~`2923`.
Extract `fn rename_field(value) -> Element` (free fn; uses `RENAME_ID`,
`RenameChanged`, `RenameCommit`).

**T18. Tree-child factories (3×).** `tree_child_from_drive/distro/known`
(~`3527–3542`) are identical `row → TreeChild::lazy(label, icon, target)`. Collapse
to one `tree_child_from_row(row: Row) -> TreeChild`. Lives in `navload.rs`.

**T19. (Optional / stretch) Async token-supersession guard (9×).** The
`if token != self.X_token { return Task::none() }` pattern recurs in every async
arm. A macro or `fn is_stale(token, current) -> bool` helper trims it, but each
arm checks a *different* token field — only worth it if it reads cleaner to you.
Skip if it feels forced.

---

## Global verification

After **each** ticket:
1. `cargo build -p librarian-app` — clean.
2. `cargo clippy --workspace` — no new warnings vs. the T0 baseline.
3. `cargo test --workspace` — all green (esp. after T3, T10, T11).
4. `cargo run -p librarian-app` — exercise the area the ticket touched (see each
   ticket's *Verify*).
5. `git commit` — one commit per ticket, so any regression is trivially bisectable.

At the end: `main.rs` should be ~600–800 lines and read as *struct + Message +
dispatch*, with each feature's logic one `mod` away. Confirm the full app still
behaves identically to the T0 baseline (navigation, tabs, search, grid/details,
file ops, rename, tree reveal, WSL, external-change refresh).

---

## Suggested order & dependencies

`T0 → T1 → T2 → T3` (independent leaf moves; T1 before Phase 2) `→ T4 → T5 → T6`
(views; need T1/T3) `→ T7 → T8 → T9 → T10` (stateful; independent of each other,
any order) `→ T11` (tree tests; independent — can be done anytime) `→ Phase 5`
(T12–T19; after their owning module exists).

Lowest-risk first stop if you want a quick early win and a feel for the pattern:
**T1 (styles)** removes ~400 lines with zero behavioral risk.