framebuffer

Documentation

Overview

Package framebuffer provides Mosh-style terminal state diffing.

This package implements the core State Synchronization Protocol (SSP) algorithm inspired by Mosh (Mobile Shell). Instead of sending complete terminal states, it generates minimal ANSI escape sequences that transform an old framebuffer state into a new one.

Key Design Principles (from Mosh):

1. Generate minimal escape sequences, not cell-by-cell diffs
2. Use smart cursor positioning (relative vs absolute)
3. Batch consecutive cells with the same style
4. Skip unchanged rows entirely (fast pointer comparison first)
5. Preserve correctness over any terminal emulator (pure ANSI output)

Index

• type DiffGenerator
  • func NewDiffGenerator() *DiffGenerator
  • func (g *DiffGenerator) GenerateDiff(old, new *session.TerminalState) *DiffResult
• type DiffResult
• type Segment

Types

type DiffGenerator

type DiffGenerator struct {
	// contains filtered or unexported fields
}

DiffGenerator generates minimal ANSI diffs between terminal states

func NewDiffGenerator

func NewDiffGenerator() *DiffGenerator

NewDiffGenerator creates a new diff generator

func (*DiffGenerator) GenerateDiff

func (g *DiffGenerator) GenerateDiff(old, new *session.TerminalState) *DiffResult

GenerateDiff generates minimal ANSI escape sequences to transform old state to new state. This is the main entry point for Mosh-style state synchronization.

Algorithm overview:

1. Handle dimension changes (requires full redraw)
2. Compare row by row using fast generation counter check
3. For changed rows, find contiguous changed segments
4. Emit minimal cursor movements and character writes
5. Position cursor at final location and set visibility

type DiffResult

type DiffResult struct {
	// DiffBytes contains the minimal ANSI escape sequences to transform old → new
	DiffBytes []byte

	// FromSequence is the sequence number of the old state
	FromSequence uint64

	// ToSequence is the sequence number of the new state
	ToSequence uint64

	// FullRedraw indicates this is a complete redraw (no dependency on old state)
	FullRedraw bool

	// ChangedCells is the count of cells that changed (for metrics)
	ChangedCells int

	// UnchangedCells is the count of cells that didn't change (for metrics)
	UnchangedCells int
}

DiffResult contains the generated diff and metadata

type Segment

type Segment struct {
	StartCol int
	EndCol   int // Inclusive
}

Segment represents a contiguous range of changed cells in a row