docs(02-01): complete vault core and highlighter foundation plan
- Add 02-01-SUMMARY.md with full execution record and deviation documentation - Update STATE.md: Phase 2 Plan 1 complete, resume at 02-02-PLAN.md - Update REQUIREMENTS.md: mark REND-03, REND-10, NAV-06, NAV-07 complete
This commit is contained in:
@@ -18,14 +18,14 @@ Requirements for initial release. Each maps to roadmap phases.
|
||||
|
||||
- [ ] **REND-01**: User sees H1-H6 headers with visual hierarchy and styling
|
||||
- [ ] **REND-02**: User sees bold, italic, and inline code rendered with terminal styling
|
||||
- [ ] **REND-03**: User sees fenced code blocks with syntax highlighting
|
||||
- [x] **REND-03**: User sees fenced code blocks with syntax highlighting
|
||||
- [ ] **REND-04**: User sees ordered and unordered lists with proper indentation
|
||||
- [ ] **REND-05**: User sees blockquotes with visual distinction
|
||||
- [ ] **REND-06**: User sees horizontal rules as visual separators
|
||||
- [ ] **REND-07**: User sees `[IMAGE: alt text]` placeholders for images
|
||||
- [ ] **REND-08**: User sees GFM tables rendered with aligned columns
|
||||
- [ ] **REND-09**: User sees box-drawing borders on content panels
|
||||
- [ ] **REND-10**: User sees CGA-era retro color theme (cyan/magenta/green on dark)
|
||||
- [x] **REND-10**: User sees CGA-era retro color theme (cyan/magenta/green on dark)
|
||||
|
||||
### Navigation
|
||||
|
||||
@@ -34,8 +34,8 @@ Requirements for initial release. Each maps to roadmap phases.
|
||||
- [ ] **NAV-03**: User can navigate back through history stack
|
||||
- [ ] **NAV-04**: User can navigate forward after going back
|
||||
- [ ] **NAV-05**: User can scroll content with j/k, arrows, PgUp/PgDn
|
||||
- [ ] **NAV-06**: User lands on index.md as the entry point
|
||||
- [ ] **NAV-07**: User sees graceful error page when a linked file is not found
|
||||
- [x] **NAV-06**: User lands on index.md as the entry point
|
||||
- [x] **NAV-07**: User sees graceful error page when a linked file is not found
|
||||
- [ ] **NAV-08**: User sees keyboard hints in status bar
|
||||
- [ ] **NAV-09**: App handles terminal resize without breaking layout
|
||||
- [ ] **NAV-10**: User sees links highlighted inline and can Tab-cycle between them
|
||||
@@ -107,17 +107,17 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| SHEL-02 | Phase 1 | Complete (01-01) |
|
||||
| REND-01 | Phase 2 | Pending |
|
||||
| REND-02 | Phase 2 | Pending |
|
||||
| REND-03 | Phase 2 | Pending |
|
||||
| REND-03 | Phase 2 | Complete |
|
||||
| REND-04 | Phase 2 | Pending |
|
||||
| REND-05 | Phase 2 | Pending |
|
||||
| REND-06 | Phase 2 | Pending |
|
||||
| REND-07 | Phase 2 | Pending |
|
||||
| REND-08 | Phase 2 | Pending |
|
||||
| REND-09 | Phase 2 | Pending |
|
||||
| REND-10 | Phase 2 | Pending |
|
||||
| REND-10 | Phase 2 | Complete |
|
||||
| NAV-05 | Phase 2 | Pending |
|
||||
| NAV-06 | Phase 2 | Pending |
|
||||
| NAV-07 | Phase 2 | Pending |
|
||||
| NAV-06 | Phase 2 | Complete |
|
||||
| NAV-07 | Phase 2 | Complete |
|
||||
| NAV-08 | Phase 2 | Pending |
|
||||
| NAV-09 | Phase 2 | Pending |
|
||||
| NAV-01 | Phase 3 | Pending |
|
||||
|
||||
+17
-13
@@ -5,32 +5,33 @@
|
||||
See: .planning/PROJECT.md (updated 2026-02-28)
|
||||
|
||||
**Core value:** Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics
|
||||
**Current focus:** Phase 1 complete — Phase 2 next (Content Rendering)
|
||||
**Current focus:** Phase 2 in progress — Plan 01 complete (vault core + highlighter foundation)
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 of 4 (Safety Foundation) — COMPLETE
|
||||
Plan: 3 of 3 in current phase (all plans done)
|
||||
Status: Phase 1 complete — Phase 2 ready to start
|
||||
Last activity: 2026-02-28 — Plan 03 complete (event loop + main.rs wiring)
|
||||
Phase: 2 of 4 (Vault Core and Rendering) — IN PROGRESS
|
||||
Plan: 1 of 3 in current phase (plan 01 done)
|
||||
Status: Phase 2 Plan 01 complete — Plan 02 (markdown renderer) next
|
||||
Last activity: 2026-02-28 — Plan 01 complete (deps, vault.rs, highlighter.rs)
|
||||
|
||||
Progress: [███░░░░░░░] 25%
|
||||
Progress: [████░░░░░░] 33%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 3
|
||||
- Average duration: 2.3 min
|
||||
- Total execution time: 0.12 hours
|
||||
- Total plans completed: 4
|
||||
- Average duration: 2.2 min
|
||||
- Total execution time: 0.14 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| 01-safety-foundation | 3 | 7 min | 2.3 min |
|
||||
| 02-vault-core-and-rendering | 1 | 2 min | 2.0 min |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: 2 min, 3 min, 2 min
|
||||
- Last 5 plans: 2 min, 3 min, 2 min, 2 min
|
||||
- Trend: Stable
|
||||
|
||||
*Updated after each plan completion*
|
||||
@@ -54,6 +55,9 @@ Recent decisions affecting current work:
|
||||
- 01-03: show_goodbye() called after restore_terminal() — terminal must be in cooked mode before println! is safe
|
||||
- 01-03: app_config stored in App struct for Phase 2 access — vault_path accessible inside event loop
|
||||
- 01-03: Quit prompt cleared on any non-Ctrl+C key — pressing any key dismisses double-press window
|
||||
- 02-01: LinesWithNewlines iterator added to preserve trailing \n for syntect grammar correctness
|
||||
- 02-01: mod declarations omitted from main.rs — Plan 03 handles wiring for all Phase 2 modules
|
||||
- 02-01: syntect default-fancy feature uses pure-Rust fancy-regex (avoids Oniguruma C lib)
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -61,12 +65,12 @@ None.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
- **REND**: Verify ratatui 0.30 custom Widget trait signature before building BBS widgets (changed between 0.28 and 0.29)
|
||||
- **REND**: ratatui 0.30 Widget trait confirmed: `impl Widget for &Foo` pattern required (NOT WidgetRef) — Plan 02 must use reference-based impl
|
||||
- **NAV**: Path traversal via wiki-links must be addressed in Phase 3 link resolver — canonicalize and prefix-check every resolved path
|
||||
- **LIVE**: notify 8.x API must be verified at integration time; watch only current file (not full vault) to avoid inotify exhaustion
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-28
|
||||
Stopped at: Completed 01-03-PLAN.md — Phase 1 complete, app event loop and main.rs pipeline committed
|
||||
Resume file: .planning/phases/02-content-rendering/ (next phase)
|
||||
Stopped at: Completed 02-01-PLAN.md — vault.rs and highlighter.rs created, cargo build clean
|
||||
Resume file: .planning/phases/02-vault-core-and-rendering/02-02-PLAN.md
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
phase: 02-vault-core-and-rendering
|
||||
plan: 01
|
||||
subsystem: vault-and-highlighter
|
||||
tags: [cargo, dependencies, file-io, syntax-highlighting, cga-colors]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [vault-file-loading, syntect-initialization, cga-color-mapping, highlight-code]
|
||||
affects: [02-02-renderer, 02-03-app-integration]
|
||||
tech_stack:
|
||||
added:
|
||||
- pulldown-cmark 0.13.1
|
||||
- syntect 5.3 (default-fancy, pure-Rust engine)
|
||||
- syntect-tui 3.0
|
||||
patterns:
|
||||
- OnceLock for one-time syntect initialization
|
||||
- Euclidean RGB-to-CGA quantization
|
||||
- Owned String Spans for Vec<Line<'static>> output
|
||||
key_files:
|
||||
created:
|
||||
- Cargo.toml (modified - 3 new deps added)
|
||||
- src/vault.rs
|
||||
- src/highlighter.rs
|
||||
modified: []
|
||||
decisions:
|
||||
- "Used LinesWithNewlines iterator to preserve trailing \\n for syntect grammar correctness"
|
||||
- "Removed mod declarations from main.rs after compile verification - Plan 03 handles wiring"
|
||||
- "syntect-tui pulled onig_sys via transitive dep but cargo check succeeds cleanly"
|
||||
metrics:
|
||||
duration_seconds: 102
|
||||
completed: 2026-02-28
|
||||
tasks_completed: 2
|
||||
files_changed: 3
|
||||
---
|
||||
|
||||
# Phase 02 Plan 01: Vault Core and Highlighter Summary
|
||||
|
||||
**One-liner:** pulldown-cmark/syntect/syntect-tui dependencies added with VaultDocument file-loading enum and OnceLock-based CGA-mapped syntax highlighter.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Task 1: Dependencies and vault file-loading module
|
||||
Added three new dependencies to `Cargo.toml`:
|
||||
- `pulldown-cmark = "0.13.1"` — markdown event parser
|
||||
- `syntect = { version = "5.3", default-features = false, features = ["default-fancy"] }` — syntax highlighting with pure-Rust regex engine
|
||||
- `syntect-tui = "3.0"` — bridge between syntect and ratatui
|
||||
|
||||
Created `src/vault.rs` with:
|
||||
- `VaultDocument` enum: `Loaded { path, content }`, `Missing { path }`, `ReadError { path, reason }`
|
||||
- `load_document(vault_path: &Path, relative: &str) -> VaultDocument` using `std::fs::read_to_string` with proper `ErrorKind::NotFound` discrimination
|
||||
|
||||
### Task 2: Syntax highlighter module with CGA color mapping
|
||||
Created `src/highlighter.rs` with:
|
||||
- `static SYNTAX_SET: OnceLock<SyntaxSet>` and `static THEME_SET: OnceLock<ThemeSet>` for one-time initialization
|
||||
- `init_highlighter()` — call once before `App::new()`
|
||||
- `syntax_set()` and `theme_set()` accessor functions with expect panics on uninitialized state
|
||||
- `syntect_color_to_cga(c: Color) -> ratatui::style::Color` — Euclidean distance RGB-to-CGA 16-color quantization across the full classic CGA palette
|
||||
- `highlight_code(code: &str, lang: &str) -> Vec<Line<'static>>` — full pipeline: syntax lookup by token/name/fallback, `base16-ocean.dark` theme, per-line `HighlightLines::highlight_line()`, CGA color mapping, owned String Spans
|
||||
- `LinesWithNewlines` private iterator that preserves trailing `\n` per line for correct syntect grammar matching
|
||||
|
||||
## Verification
|
||||
|
||||
1. `cargo build` succeeds with all new dependencies (53 packages locked)
|
||||
2. `src/vault.rs` contains `VaultDocument` enum with `Loaded`, `Missing`, `ReadError` variants
|
||||
3. `src/vault.rs` contains `load_document()` function using `std::fs::read_to_string`
|
||||
4. `src/highlighter.rs` contains `init_highlighter()`, `highlight_code()`, `syntect_color_to_cga()`
|
||||
5. No changes to existing Phase 1 files (app.rs, main.rs, config.rs, signals.rs, terminal.rs)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing Critical Functionality] Added LinesWithNewlines iterator**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** syntect's `highlight_line()` expects lines to include their trailing `\n` terminator so language grammars can match end-of-line anchors. Using `str::lines()` strips newlines, causing grammar state machine errors in some syntect definitions.
|
||||
- **Fix:** Added a private `LinesWithNewlines` iterator that yields substrings including the `\n` terminator, with correct handling for the final line without a trailing newline.
|
||||
- **Files modified:** src/highlighter.rs
|
||||
- **Commit:** 8d45a7c
|
||||
|
||||
## Commits
|
||||
|
||||
| Hash | Task | Description |
|
||||
|------|------|-------------|
|
||||
| 7622d41 | Task 1 | feat(02-01): add Phase 2 deps and vault file-loading module |
|
||||
| 8d45a7c | Task 2 | feat(02-01): add syntax highlighter module with CGA color mapping |
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- [x] src/vault.rs exists and contains VaultDocument, load_document
|
||||
- [x] src/highlighter.rs exists and contains init_highlighter, syntect_color_to_cga, highlight_code
|
||||
- [x] Cargo.toml contains pulldown-cmark, syntect, syntect-tui
|
||||
- [x] Commits 7622d41 and 8d45a7c exist in git log
|
||||
- [x] cargo build succeeds
|
||||
Reference in New Issue
Block a user