szn

Design Document: Sixel Grid Allocation & Registry Model

This document outlines the architectural design and migration plan to transition szn from coordinate-based sixel overlays to a cell-allocated grid registry model.

1. Problem Statement

The current coordinate-based sixel model (sixel_images coordinate list) has the following limitations:


2. Proposed Architecture

A. Cell-Level Metadata Mapping

Instead of storing raw sixel data in cells, the 128-bit Cell structure will hold a lightweight reference to an image in a screen-level registry.

When a cell has the attribute attr.sixel = true, its standard fields are remapped:

This allows any cell to dynamically specify:

B. Bounded Sixel Registry (Reference-Aware Ring Buffer)

To avoid complex reference counting hooks during GridLine allocation and pruning, we use a fixed-capacity Sixel Registry (capacity of 64 images per pane):

C. Viewport Diffing & Rendering

During the render cycle:

  1. Display.renderAll copies cells to the merged_screen as usual.
  2. Display.renderContent compares the viewport with last_cells. If a cell changes from attr.sixel = true to false (meaning the graphic scrolled away), last_cells diffing automatically force-redraws that cell with space characters, clearing the sixel pixels.
  3. Display.renderSixelImages scans the visible cells in the viewport:
    • When it encounters a cell with attr.sixel == true:
      • It extracts the image_id and the offsets (dx, dy).
      • If the image_id has not been drawn in the current frame:
        • The top-left anchor is calculated as abs_col = col - dx and abs_row = row - dy.
        • If abs_row >= 0, we move the cursor to (abs_col, abs_row), render the DCS bytes verbatim, and mark the image_id as drawn.
        • If abs_row < 0 (partially scrolled off the top), we skip redrawing it, letting the terminal’s native viewport scrolling handle display of the remaining visible bottom pixels.

3. Benefits


4. Limitations

Due to the cell-based grid updates of a terminal multiplexer and the lack of a pixel-level sixel encoder/decoder, the following constraints apply:

  1. Viewport Boundaries & Clipping: Since we cannot crop the raw sixel DCS bytes, an image must fit entirely within the vertical and horizontal boundaries of its pane. If any portion of the image exceeds the pane boundaries (e.g., because the pane was split or resized, or the image’s top edge scrolls past the top of the viewport), the image is hidden and its cells are erased. This prevents the graphic from breaking layout bounds and corrupting other panes.
  2. Terminal Erasure Quirks: Sixel graphics are managed on a separate overlay layer by terminal emulators. Transparent space characters (" ") do not overwrite sixel pixels in most terminals, and CSI X (Erase Character) operates only on the text grid — it cannot clear the sixel overlay. To guarantee clean removal when an image scrolls or is hidden, szn tracks the last-drawn anchor of every registry slot (Screen.sixel_last_anchor) and, each frame, emits a DECSIXEL erase-below operation (ESC P 1 q ESC \) at the previous anchor for any image that moved or disappeared, before redrawing the still-visible images at their current anchors (see bug #195). This clears the overlay instead of leaving a smear/ghost as the image scrolls. Note that the sixel erase operation clears a rectangular region relative to the cursor, so (as with all terminal sixel implementations) an erase may also clear unrelated overlay pixels that happen to lie below/right of the old anchor.
  3. Optimized for Full-Screen TUIs: This architecture is optimized for full-screen applications (like yazi or ranger) that manage their own layouts and handle window redrawing, while maintaining layout safety for multiplexer split-panes.