szn

Text Reflow in szn

This document explains the design, algorithms, and engineering implementation of the Text Reflow system in szn.


1. Overview

When a terminal pane is resized (e.g., when the user drags the mouse or splits the screen), standard terminal behavior simply truncates or pads lines with trailing spaces. szn implements a smart Text Reflow system that dynamically wraps and unwraps text to fit the new width while preserving context, spacing, and script integrity.

graph TD
    A[Grid Resize Event] --> B[Identify Active Text Range]
    B --> C[Flatten Physical Lines into Logical Lines]
    C --> D[Rewrap Logical Lines to New Width]
    D --> E[Reconstruct Grid Lines & Scrollback History]

2. Reconstructing Logical Lines (Soft-Wrap Tracking)

To reconstruct the original stream of text (logical lines) from the grid’s raw physical rows, szn tracks soft-wraps on each physical line:


3. Thai & Lao (Tai) Text Cluster Integrity

Unlike Latin-based scripts where characters are rendered sequentially side-by-side, Tai scripts (Thai U+0E00–U+0E7F and Lao U+0E80–U+0EFF) use vertically and horizontally combining glyphs to form a single visual cluster (or syllable core).

Splitting a Thai or Lao cluster across line boundaries makes the text unreadable and corrupts the script.

Anatomy of a Tai Cluster

A single Thai or Lao character cell is defined as a base consonant that may contain up to two combining marks (stored inside comb1 and comb2 of the Cell struct). A cluster spans across a sequence of cells matching this syntax:

[Leading Vowel]? ➔ Base Consonant [รร]? ➔ [Following Vowels]* ➔ [Right-Attaching Marks]*
  1. Leading Vowels (Thai U+0E40–U+0E44: เ, แ, โ, ใ, ไ; Lao U+0EC0–U+0EC4: ເ, ແ, ໂ, ໃ, ໄ): Width 1, placed before the base.
  2. Base Consonant (Thai U+0E01–U+0E2E; Lao U+0E81–U+0EAE): Width 1. Can optionally be followed by Ro Han (รร) in Thai (two consecutive U+0E23 characters), which function as a vowel sound and are consumed as part of the base consonant’s cluster to prevent split lines.
  3. Following Vowels:
    • Thai U+0E30 SARA A, U+0E32 SARA AA, U+0E33 SARA AM, U+0E45 LAKKHANGYAO; Lao U+0EB0 SARA A, U+0EB2 SARA AA, U+0EB3 SARA AM: Width 1.
    • Thai U+0E31 MAI HAN AKAT / Lao U+0EB1 MAI KAN: Width 0 (combining mark functionally acting as a following vowel to ensure correct cluster integrity).
    • Compound Vowels: Compound vowels such as เ-าะ / ເ-າະ (e.g., เกาะ / ເກາະ, เฉพาะ, เหมาะ) contain multiple consecutive following vowels (า/າ + ะ/ະ). findThaiClusterEnd consumes all consecutive following vowels into the syllable cluster to prevent illegal wraps such as เกา|ะ or ເກາ|ະ.
    • SARA AM Display Coherence: SARA AM (Thai U+0E33, Lao U+0EB3) occupies its own width-1 cell in the grid, but terminal font shapers (HarfBuzz) visually project its upper circle onto the preceding consonant. Terminal rendering diff coherence for this shaped pair is maintained by Display.renderContent’s row pre-pass (src/server/render.zig).
  4. Right-Attaching Marks (Thai U+0E2F PAIYANNOI ฯ, U+0E46 MAI YAMOK ๆ; Lao U+0EAF ELLIPSIS ຯ, U+0EC6 KO LA ໆ): Width 1.
  5. Combining Marks (SARA U ◌ุ/◌ຸ, MAI EK ◌่/◌່, SARA I ◌ิ/◌ິ, Lao MAI KON ◌ົ, Thanthakhat ◌์/◌໌, etc.): Stored directly inside the cell attributes of the base or following vowel, occupying 0 additional cells.

The function findThaiClusterEnd identifies these boundary rules to ensure that a cluster is treated as an indivisible unit during wrapping for both Thai and Lao scripts.


4. Two-Tier Thai Word & Syllable Breaking

Thai orthography does not insert spaces between words. To keep words readable without awkward hyphenation or mid-word splits, szn implements a two-tier line-breaking architecture:

Tier 1: Dictionary-Based Word Breaking via libthai

When Thai characters are detected in a logical line, szn consults libthai (dynamically loaded at runtime from standard system paths like /opt/homebrew/lib/ or /usr/lib/ via getLibThai):

  1. thai.findWordBreaks maps the logical line’s UTF-32 codepoints into libthai’s word-breaking engine (th_brk_wc_find_breaks).
  2. The break positions returned by libthai are translated back to terminal cell indices.
  3. During rewrapping in src/grid.zig, the algorithm prioritizes breaking at these dictionary-confirmed word boundaries whenever a line overflows new_width.
  4. Spaces bordering Thai words are also recognized as valid word break boundaries.

Tier 2: Fallback Syllable Look-Ahead & Backtracking Heuristic

If libthai is not installed on the host system or a token is absent from the dictionary, szn falls back to phonetic syllable boundary detection to prevent orphan consonants:


5. The Unified Reflow Algorithm

Instead of separate grow and shrink logic, szn runs a unified, lossless, three-step reflow loop:

Step 1: Flattening to Logical Lines

Step 2: Rewrapping

Step 3: Layout Reconstruction


6. Number Wrap & Comma-Breaking Heuristics

In addition to linguistic script clustering, szn prevents breaking numbers across line boundaries in awkward positions:

The Short Number Wrapping Rule

Comma-Breaking for Long Numbers


7. Key Edge Cases Solved


8. Forcing Reflow Manually

To optimize performance and maintain compatibility with interactive fullscreen applications (which expect standard character-by-character VT100-style wrapping limits at the right margin), szn only executes the full text reflow algorithm automatically during window or pane resize events.

To apply smart wrapping rules retrospectively to stream output (e.g., after displaying a text document with cat), users can manually trigger a forced reflow of the current active pane at its current width.

Key Binding

Command Mode