This document outlines the architectural design and migration plan to transition szn from coordinate-based sixel overlays to a cell-allocated grid registry model.
The current coordinate-based sixel model (sixel_images coordinate list) has the following limitations:
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:
cell.char (21 bits): Unique Sixel Image ID.cell.comb1 (13 bits): Horizontal cell offset (dx) from the top-left of the image.cell.comb2 (13 bits): Vertical cell offset (dy) from the top-left of the image.This allows any cell to dynamically specify:
(x - dx, y - dy).To avoid complex reference counting hooks during GridLine allocation and pruning, we use a fixed-capacity Sixel Registry (capacity of 64 images per pane):
Screen owns the registry storing [64]?SixelImage.SixelImage contains its unique id and the raw data (DCS bytes).id.id % 64 is checked. If it is empty or its image is no longer referenced in the grid/history, it is used.attr.sixel = true, char = id, and their local coordinate offsets (dx, dy).findSixelImage/findSixelImageSlot) rather than assuming id % 64 directly, preventing collisions and preserving copy-mode/scrollback graphics.During the render cycle:
Display.renderAll copies cells to the merged_screen as usual.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.Display.renderSixelImages scans the visible cells in the viewport:
attr.sixel == true:
image_id and the offsets (dx, dy).image_id has not been drawn in the current frame:
abs_col = col - dx and abs_row = row - dy.abs_row >= 0, we move the cursor to (abs_col, abs_row), render the DCS bytes verbatim, and mark the image_id as drawn.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.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:
" ") 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.yazi or ranger) that manage their own layouts and handle window redrawing, while maintaining layout safety for multiplexer split-panes.