120 lines
7.0 KiB
Markdown
120 lines
7.0 KiB
Markdown
---
|
|
phase: 04-bbs-polish-and-live-content
|
|
plan: 01
|
|
subsystem: ui
|
|
tags: [ansi-to-tui, notify, walkdir, ratatui, rust, splash-screen, file-metadata, status-bar]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 03-navigation-and-links
|
|
provides: "navigate_to/back/forward with link_records, breadcrumb status bar, draw_status_bar()"
|
|
provides:
|
|
- "src/splash.rs with load_splash() loading ANSI art from splash.txt via ansi-to-tui"
|
|
- "PageMeta struct and read_page_meta() with pure Gregorian date math in app.rs"
|
|
- "Splash prepend with link_record line_index offsetting in navigate_to/back/forward and initial load"
|
|
- "Status bar right side shows 'Last modified: Mon DD, YYYY | X.X KB' with graceful truncation"
|
|
- "All Phase 4 dependencies (notify=6.1, ansi-to-tui=8.0, walkdir=2.5) in Cargo.toml"
|
|
affects: [04-02-live-reload, 04-03-directory-listing]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added:
|
|
- "ansi-to-tui = 8.0 — ANSI SGR escape code parser targeting ratatui-core types"
|
|
- "notify = 6.1 — cross-platform filesystem watcher (for Phase 4 plan 02)"
|
|
- "walkdir = 2.5 — recursive directory traversal with depth tracking (for Phase 4 plan 03)"
|
|
patterns:
|
|
- "Splash prepend pattern: load_splash() returns Vec<Line<'static>>, prepend to markdown lines, offset link_records by splash_count + 1 (blank separator)"
|
|
- "Page metadata computed in App::new() and on every navigation from vault_path.join(current_path)"
|
|
- "Status bar graceful truncation: loop removing second-to-last right_part until left.len + right.len <= width"
|
|
|
|
key-files:
|
|
created:
|
|
- "src/splash.rs — load_splash() reading splash.txt as Vec<u8>, parsing via IntoText trait"
|
|
modified:
|
|
- "Cargo.toml — added notify, ansi-to-tui, walkdir dependencies"
|
|
- "src/app.rs — PageMeta struct, read_page_meta(), unix_secs_to_ymd(), is_leap(), format_file_size(), page_meta field in App, splash logic in navigate_to/back/forward/handle_resize, metadata in draw_status_bar"
|
|
- "src/main.rs — splash prepend in initial index.md load, mod splash declaration"
|
|
|
|
key-decisions:
|
|
- "App::new() computes page_meta internally from config.vault_path + current_path — keeps PageMeta private, no public type exposure needed"
|
|
- "splash_count = splash_lines.len() + 1 for the blank separator Line — all link_record line_index values offset by this amount to keep Tab-cycling correct"
|
|
- "Status bar truncation drops right_parts[hints_idx - 1] (the metadata item) progressively until bar fits — hints always kept as last item"
|
|
- "Hand-rolled Gregorian date math (unix_secs_to_ymd + is_leap) — avoids external time crate dependency, ~20 lines"
|
|
- "ratatui-core verified as single version via cargo tree — ansi-to-tui 8.0 unifies correctly with ratatui 0.30"
|
|
|
|
patterns-established:
|
|
- "Splash pattern: load bytes with std::fs::read, call .into_text().ok()?, return .lines — all owned, 'static lifetime"
|
|
- "Link offset pattern: splash_count = splash_lines.len() + 1; for record in &mut link_records { record.line_index += splash_count; }"
|
|
- "Metadata pattern: read_page_meta(&vault_path.join(vault_relative)) after successful VaultDocument::Loaded"
|
|
|
|
requirements-completed: [BBS-01, BBS-02]
|
|
|
|
# Metrics
|
|
duration: 4min
|
|
completed: 2026-02-28
|
|
---
|
|
|
|
# Phase 4 Plan 01: BBS Polish - Splash Screen and File Metadata Summary
|
|
|
|
**ANSI art splash screen loaded from splash.txt via ansi-to-tui 8.0 prepended to index.md, with file mtime and size in status bar using hand-rolled Gregorian date formatting**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 4 min
|
|
- **Started:** 2026-02-28T22:46:19Z
|
|
- **Completed:** 2026-02-28T22:50:00Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 4
|
|
|
|
## Accomplishments
|
|
|
|
- `src/splash.rs` module created with `load_splash()` that reads `splash.txt` as owned bytes, parses ANSI SGR codes via `IntoText` trait, returns `Vec<Line<'static>>` — gracefully returns `None` if file missing
|
|
- Splash prepend wired into all navigation paths (`navigate_to`, `navigate_back`, `navigate_forward`, initial load in `main.rs`, and `handle_resize`) with correct `link_record.line_index` offsetting so Tab-cycling still targets the right lines
|
|
- `PageMeta` struct and `read_page_meta()` added to `app.rs` — reads `std::fs::metadata()`, converts mtime to "Feb 25, 2026" format with pure Gregorian arithmetic, formats size as "X.X KB"
|
|
- Status bar right side now shows "Last modified: Mon DD, YYYY | X.X KB" with graceful truncation that drops metadata before hints when terminal is narrow
|
|
- All three Phase 4 crate dependencies (`notify = "6.1"`, `ansi-to-tui = "8.0"`, `walkdir = "2.5"`) added to `Cargo.toml` — verified single `ratatui-core v0.1.0` in dependency tree
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Add Phase 4 deps and create splash module** - `6aa5a94` (chore)
|
|
2. **Task 2: Wire splash prepend and file metadata to status bar** - `27139cf` (feat)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `src/splash.rs` - `load_splash()` reading vault root `splash.txt` via `IntoText` into `Vec<Line<'static>>`
|
|
- `Cargo.toml` - Added `notify = "6.1"`, `ansi-to-tui = "8.0"`, `walkdir = "2.5"`
|
|
- `src/app.rs` - `PageMeta`, `read_page_meta()`, `unix_secs_to_ymd()`, `is_leap()`, `format_file_size()`; `page_meta` field on `App`; splash prepend in all navigation paths; metadata display in `draw_status_bar()`
|
|
- `src/main.rs` - `mod splash` declaration; splash prepend with `link_record` offset in initial `index.md` load
|
|
|
|
## Decisions Made
|
|
|
|
- `App::new()` computes `page_meta` itself from `config.vault_path` + `current_path` — avoids making `PageMeta` pub while keeping initialization clean
|
|
- `splash_count = splash_lines.len() + 1` — the +1 accounts for the blank separator `Line::default()` between splash art and markdown content
|
|
- Status bar graceful truncation loops removing `right_parts[hints_idx - 1]` (the metadata string) progressively; hints always kept as the last item
|
|
- Hand-rolled Gregorian math in `unix_secs_to_ymd()` — clean ~20 lines, no chrono/gregorian dependency needed
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written. The plan's `App::new()` signature included `page_meta` as a parameter, but I instead computed it internally in `App::new()` to keep `PageMeta` private. This is a minor structural refinement that improves encapsulation without changing observable behavior.
|
|
|
|
## Issues Encountered
|
|
|
|
None. The `ansi-to-tui 8.0` + `ratatui 0.30` type unification worked correctly without needing an explicit `ratatui-core` pin — `cargo tree | grep ratatui-core` showed a single `v0.1.0` with `(*)` deduplication markers as expected.
|
|
|
|
## User Setup Required
|
|
|
|
Optional: Create `splash.txt` in the vault root containing ANSI art (CGA palette, block characters). If the file is absent, index.md renders normally with no error.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Phase 4 Plan 02 (live reload via `notify`) can now start — `notify = "6.1"` is already in `Cargo.toml`
|
|
- Phase 4 Plan 03 (directory listing via `walkdir`) can start — `walkdir = "2.5"` is in `Cargo.toml`
|
|
- `load_splash()` in `splash.rs` is pub and available for future plans
|
|
- All navigation paths already handle splash prepend consistently
|
|
|
|
---
|
|
*Phase: 04-bbs-polish-and-live-content*
|
|
*Completed: 2026-02-28*
|