c-vt-snapshot/src/main.c

Encode a terminal's full state and restore it three ways: in one shot, with scrollback kept compressed, and page by page. The page by page path gives you a terminal you can draw before the old history arrives.

#include <assert.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <ghostty/vt.h>

typedef struct {
  const uint8_t *data;
  size_t len;
  size_t offset;
} BufferReader;
 
// GhosttyReader callbacks are synchronous. A successful zero-byte read is
// permanent EOF; returning false would report an I/O error.
static bool buffer_read(void *userdata,
                        uint8_t *buffer,
                        size_t capacity,
                        size_t *out_read) {
  BufferReader *reader = userdata;
  size_t remaining = reader->len - reader->offset;
  size_t count = remaining < capacity ? remaining : capacity;
 
  // Deliberately return short reads to demonstrate that the decoder retries.
  if (count > 64) count = 64;
  memcpy(buffer, reader->data + reader->offset, count);
  reader->offset += count;
  *out_read = count;
  return true;
}
 
int main(void) {
  GhosttyResult result;

  GhosttyTerminal source = NULL;
  // A wide, shallow screen fills backing pages quickly enough to leave older
  // PAGE records after READY for the incremental decoder to demonstrate.
  result = ghostty_terminal_new(NULL, &source, 215, 2);
  assert(result == GHOSTTY_SUCCESS);
 
  // Snapshot encoding requires continuation tracking if the input can stop
  // partway through a sequence, and it has to be enabled before feeding
  // input. The limit bounds unfinished VT sequence retention.
  const size_t continuation_limit = 1024;
  result = ghostty_terminal_set(
      source,
      GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES,
      &continuation_limit);
  assert(result == GHOSTTY_SUCCESS);
 
  // Keep enough scrollback to demonstrate incremental history restoration.
  size_t unlimited = SIZE_MAX;
  result = ghostty_terminal_set(
      source, GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES, &unlimited);
  assert(result == GHOSTTY_SUCCESS);
 
  const char *line = "snapshot history line\r\n";
  for (size_t i = 0; i < 1000; i++) {
    ghostty_terminal_vt_write(
        source, (const uint8_t *)line, strlen(line));
  }
 
  // Leave an SGR sequence unfinished so its continuation is snapshotted too.
  const char *unfinished = "\x1b[31";
  ghostty_terminal_vt_write(
      source, (const uint8_t *)unfinished, strlen(unfinished));
 
  uint8_t *snapshot = NULL;
  size_t snapshot_len = 0;
  result = ghostty_snapshot_encode_alloc(
      source, NULL, &snapshot, &snapshot_len);
  assert(result == GHOSTTY_SUCCESS);
  printf("encoded %zu snapshot bytes\n", snapshot_len);

  GhosttySnapshotDecoder full_decoder = NULL;
  result = ghostty_snapshot_decoder_new_buf(
      NULL, &full_decoder, snapshot, snapshot_len);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyTerminal full_terminal = NULL;
  result = ghostty_snapshot_decoder_decode(full_decoder, &full_terminal);
  assert(result == GHOSTTY_SUCCESS);
 
  ghostty_snapshot_decoder_free(full_decoder);
  ghostty_terminal_free(full_terminal);

  GhosttySnapshotDecoder compressed_decoder = NULL;
  result = ghostty_snapshot_decoder_new_buf(
      NULL, &compressed_decoder, snapshot, snapshot_len);
  assert(result == GHOSTTY_SUCCESS);
 
  // Options must be set before decoding starts. With this set, each history
  // page is compressed as soon as it is restored, so the full scrollback is
  // never held uncompressed in memory.
  const bool compress_history = true;
  result = ghostty_snapshot_decoder_set(
      compressed_decoder,
      GHOSTTY_SNAPSHOT_DECODER_OPT_COMPRESS_HISTORY,
      &compress_history);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyTerminal compressed_terminal = NULL;
  result = ghostty_snapshot_decoder_decode(
      compressed_decoder, &compressed_terminal);
  assert(result == GHOSTTY_SUCCESS);
 
  ghostty_snapshot_decoder_free(compressed_decoder);
  ghostty_terminal_free(compressed_terminal);

  BufferReader reader_state = {
      .data = snapshot,
      .len = snapshot_len,
      .offset = 0,
  };
  GhosttyReader reader = {
      .read = buffer_read,
      .userdata = &reader_state,
  };
 
  GhosttySnapshotDecoder incremental_decoder = NULL;
  result = ghostty_snapshot_decoder_new(
      NULL, &incremental_decoder, reader);
  assert(result == GHOSTTY_SUCCESS);
 
  // READY returns a validated, renderable terminal before old history.
  GhosttyTerminal incremental_terminal = NULL;
  result = ghostty_snapshot_decoder_ready(
      incremental_decoder, &incremental_terminal);
  assert(result == GHOSTTY_SUCCESS);
 
  uint64_t history_rows = 0;
  result = ghostty_snapshot_decoder_get(
      incremental_decoder,
      GHOSTTY_SNAPSHOT_DECODER_DATA_HISTORY_ROWS_PRIMARY,
      &history_rows);
  assert(result == GHOSTTY_SUCCESS);
  printf("snapshot advertises %llu primary history rows\n",
         (unsigned long long)history_rows);
 
  size_t page_count = 0;
  while ((result = ghostty_snapshot_decoder_next(incremental_decoder)) ==
         GHOSTTY_SUCCESS) {
    // Each call decodes either a history page or the pixels of one Kitty
    // graphics image. This terminal has no images, but a real client should
    // check the kind before reading the page values.
    GhosttySnapshotDecoderProgressKind kind;
    result = ghostty_snapshot_decoder_get(
        incremental_decoder,
        GHOSTTY_SNAPSHOT_DECODER_DATA_PROGRESS_KIND,
        &kind);
    assert(result == GHOSTTY_SUCCESS);
    if (kind == GHOSTTY_SNAPSHOT_DECODER_PROGRESS_KIND_IMAGE) {
      uint32_t image_id = 0;
      result = ghostty_snapshot_decoder_get(
          incremental_decoder,
          GHOSTTY_SNAPSHOT_DECODER_DATA_PROGRESS_IMAGE_ID,
          &image_id);
      assert(result == GHOSTTY_SUCCESS);
      printf("restored the pixels of image %u\n", image_id);
      continue;
    }
 
    GhosttyTerminalScreen screen;
    size_t rows = 0;
    uint32_t remaining = 0;
    const GhosttySnapshotDecoderData keys[] = {
        GHOSTTY_SNAPSHOT_DECODER_DATA_PROGRESS_SCREEN,
        GHOSTTY_SNAPSHOT_DECODER_DATA_PROGRESS_ROWS,
        GHOSTTY_SNAPSHOT_DECODER_DATA_PROGRESS_REMAINING,
    };
    void *values[] = {&screen, &rows, &remaining};
    size_t written = 0;
    result = ghostty_snapshot_decoder_get_multi(
        incremental_decoder,
        sizeof(keys) / sizeof(keys[0]),
        keys,
        values,
        &written);
    assert(result == GHOSTTY_SUCCESS);
    assert(written == sizeof(keys) / sizeof(keys[0]));
 
    printf("restored %zu rows to screen %d (%u pages remain)\n",
           rows, (int)screen, remaining);
    page_count++;
  }
 
  // NO_VALUE means FINISH validated successfully and is idempotent.
  assert(result == GHOSTTY_NO_VALUE);
  assert(page_count > 0);
  assert(ghostty_snapshot_decoder_next(incremental_decoder) ==
         GHOSTTY_NO_VALUE);
 
  ghostty_snapshot_decoder_free(incremental_decoder);
  ghostty_terminal_free(incremental_terminal);
 
  ghostty_free(NULL, snapshot, snapshot_len);
  ghostty_terminal_free(source);
  return 0;
}