szn

Bug 505 — text_reflow.md references non-existent src/reflow.zig and omits libthai integration

505. Stale sources and missing documentation for dictionary-based reflow

Severity: LOW
Status: 🟢 FIXED
Files: docs/text_reflow.md:6-10, src/thai.zig:426-565, src/grid.zig:605-608

Problem

  1. Stale frontmatter sources: docs/text_reflow.md frontmatter lists: ```yaml sources:
    • src/reflow.zig
    • src/grid.zig
    • src/screen.zig ``` src/reflow.zig does not exist in the codebase. The reflow logic is split between src/grid.zig (line wrapping, cursor tracking, history scrollback), src/screen.zig (resize trigger), and src/thai.zig (Thai cluster detection and libthai word boundary integration).
  2. Missing libthai architectural documentation: Sections 3–5 of docs/text_reflow.md detail cluster boundary integrity and $O(1)$ look-ahead/backtracking heuristics, but make zero mention of the ~180-line libthai subsystem. In reality, src/grid.zig:605-608, 688-716 dynamically uses libthai word boundaries when available as the first-class wrapping mechanism prior to falling back to heuristics.
  3. Documentation nits:
    • In §4, $O(1)$ renders literally without math formatting; backtick code style `O(1)` is standard in the documentation bundle.
    • In §4, backtracking is described as scanning back to “typically a leading vowel”, but does not explain what happens when there is no leading vowel (the algorithm falls back to first_thai_idx, the start of the contiguous Thai word token).
    • In src/thai.zig:51-52, isThaiFollowingVowel docstring lacks a blank /// before an indented list, collapsing in Markdown renderers.

Proposed Fix

  1. In docs/text_reflow.md:
    • Replace src/reflow.zig with src/thai.zig in the frontmatter sources: list.
    • Add a section explaining the two-tier Thai wrapping architecture: Tier 1 dictionary-based word breaking via dynamic libthai integration, and Tier 2 fallback cluster and syllable backtracking heuristics.
    • Replace $O(1)$ with `O(1)`.
    • Clarify the backtracking fallback behavior when no leading vowel is present.
  2. In src/thai.zig, insert a blank /// line in isThaiFollowingVowel docstring.

Resolution