vt100wasm 0.1.0__tar.gz

vt100wasm-0.1.0/.envrc

@@ -0,0 +1,8 @@
+# shellsheck shell=bash
+set -euo pipefail
+
+if ! has nix_direnv_version || ! nix_direnv_version 3.0.6; then
+  source_url https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.6/direnvrc sha256-RYcUJaRMf8oF5LznDrlCXbkOQrywm0HDv1VjYGaJGdM=
+fi
+use flake .
+PATH_add bin

vt100wasm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Build WASM binary
+        run: |
+          nix build
+          cp result/_vt100.wasm src/vt100wasm/_vt100.wasm
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build, install, and test
+        run: |
+          uv build --wheel
+          uv run --with dist/*.whl --with pytest --no-project pytest tests/

vt100wasm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Build WASM binary
+        run: |
+          nix build
+          cp result/_vt100.wasm src/vt100wasm/_vt100.wasm
+
+      - name: Set version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Run tests
+        run: |
+          uv run --with dist/*.whl --with pytest --no-project pytest tests/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Publish to PyPI
+        run: uv publish dist/*

vt100wasm-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+/target
+/result
+/dist
+__pycache__
+*.egg-info
+.direnv
+src/vt100wasm/_vt100.wasm

vt100wasm-0.1.0/Cargo.lock

@@ -0,0 +1,55 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
+[[package]]
+name = "vt100"
+version = "0.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "054ff75fb8fa83e609e685106df4faeffdf3a735d3c74ebce97ec557d5d36fd9"
+dependencies = [
+ "itoa",
+ "unicode-width",
+ "vte",
+]
+
+[[package]]
+name = "vt100wasm"
+version = "0.1.0"
+dependencies = [
+ "vt100",
+]
+
+[[package]]
+name = "vte"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5924018406ce0063cd67f8e008104968b74b563ee1b85dde3ed1f7cb87d3dbd"
+dependencies = [
+ "arrayvec",
+ "memchr",
+]

vt100wasm-0.1.0/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "vt100wasm"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+vt100 = "0.16"
+
+[profile.release]
+opt-level = "s"
+lto = true

vt100wasm-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: vt100wasm
+Version: 0.1.0
+Summary: Python bindings for vt100 terminal state processing via WASM
+Requires-Python: <3.13,>=3.10
+Requires-Dist: wasmtime>=20.0.0

vt100wasm-0.1.0/README.md

@@ -0,0 +1,30 @@
+# vt100wasm
+
+Python bindings for the Rust [vt100](https://crates.io/crates/vt100) terminal emulator, compiled to WebAssembly.
+
+Provides efficient terminal state tracking (apply deltas, extract screen contents) without native compilation -- the WASM binary is bundled in the wheel.
+
+## Install
+
+```
+pip install vt100wasm
+```
+
+## Usage
+
+```python
+from vt100wasm import apply_delta, screen_contents, screen_contents_formatted
+
+state = apply_delta(None, b"hello world\r\n$ ", rows=24, cols=80)
+print(screen_contents(state))
+
+state2 = apply_delta(state, b"\x1b[31mred text\x1b[0m", rows=24, cols=80)
+formatted = screen_contents_formatted(state2)
+```
+
+## Building the WASM binary
+
+```
+cargo build --target wasm32-wasip1 --release
+cp target/wasm32-wasip1/release/vt100wasm.wasm src/vt100wasm/_vt100.wasm
+```

vt100wasm-0.1.0/bin/build

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+nix build
+cp result/_vt100.wasm src/vt100wasm/_vt100.wasm
+uv build

vt100wasm-0.1.0/bin/publish

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+uv publish dist/*

vt100wasm-0.1.0/bin/test

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+uv run --with dist/*.whl --with pytest --no-project pytest tests/ "$@"

vt100wasm-0.1.0/flake.lock

@@ -0,0 +1,64 @@
+{
+  "nodes": {
+    "crane": {
+      "locked": {
+        "lastModified": 1773189535,
+        "narHash": "sha256-E1G/Or6MWeP+L6mpQ0iTFLpzSzlpGrITfU2220Gq47g=",
+        "owner": "ipetkov",
+        "repo": "crane",
+        "rev": "6fa2fb4cf4a89ba49fc9dd5a3eb6cde99d388269",
+        "type": "github"
+      },
+      "original": {
+        "owner": "ipetkov",
+        "repo": "crane",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1773476965,
+        "narHash": "sha256-Laaj25PvGeoP5SPhMfMGxvWqM6ZjZ6LdUeEhP6b3czY=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "f82ce7af0b79ac154b12e27ed800aeb97413723c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "crane": "crane",
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1773457417,
+        "narHash": "sha256-waABTSxPdbxml4BhcabHhyQF02Qnj27qRU4ard0mTQo=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "055977c30249484010750e03074c744dcdaa0d23",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

vt100wasm-0.1.0/flake.nix

@@ -0,0 +1,75 @@
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    crane.url = "github:ipetkov/crane";
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    {
+      nixpkgs,
+      crane,
+      rust-overlay,
+      ...
+    }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
+      pkgsFor =
+        system:
+        import nixpkgs {
+          inherit system;
+          overlays = [ rust-overlay.overlays.default ];
+        };
+    in
+    {
+      packages = forAllSystems (
+        system:
+        let
+          pkgs = pkgsFor system;
+          rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+            targets = [ "wasm32-wasip1" ];
+          };
+          craneLib = (crane.mkLib pkgs).overrideToolchain rustToolchain;
+          src = craneLib.cleanCargoSource ./.;
+        in
+        {
+          default = craneLib.buildPackage {
+            inherit src;
+            CARGO_BUILD_TARGET = "wasm32-wasip1";
+            doCheck = false;
+            installPhaseCommand = ''
+              mkdir -p $out
+              cp target/wasm32-wasip1/release/vt100wasm.wasm $out/_vt100.wasm
+            '';
+          };
+        }
+      );
+
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = pkgsFor system;
+          rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+            targets = [ "wasm32-wasip1" ];
+          };
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              rustToolchain
+              pkgs.uv
+            ];
+          };
+        }
+      );
+    };
+}

vt100wasm-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "vt100wasm"
+version = "0.1.0"
+description = "Python bindings for vt100 terminal state processing via WASM"
+requires-python = ">=3.10,<3.13"
+dependencies = [
+    "wasmtime>=20.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vt100wasm"]
+
+[tool.hatch.build]
+artifacts = ["src/vt100wasm/_vt100.wasm"]

vt100wasm-0.1.0/src/lib.rs

@@ -0,0 +1,175 @@
+use std::alloc::{alloc, dealloc, Layout};
+use std::slice;
+
+const HEADER_LEN: usize = 5;
+
+#[unsafe(no_mangle)]
+pub extern "C" fn wasm_alloc(size: u32) -> u32 {
+    if size == 0 {
+        return 0;
+    }
+    let layout = Layout::from_size_align(size as usize, 1).unwrap();
+    unsafe { alloc(layout) as u32 }
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn wasm_dealloc(ptr: u32, size: u32) {
+    if ptr == 0 || size == 0 {
+        return;
+    }
+    let layout = Layout::from_size_align(size as usize, 1).unwrap();
+    unsafe { dealloc(ptr as *mut u8, layout) }
+}
+
+fn parse_header(state: &[u8]) -> (u16, u16, u8) {
+    let rows = u16::from_le_bytes([state[0], state[1]]);
+    let cols = u16::from_le_bytes([state[2], state[3]]);
+    let flags = state[4];
+    (rows, cols, flags)
+}
+
+fn make_header(rows: u16, cols: u16, flags: u8) -> [u8; HEADER_LEN] {
+    let mut hdr = [0u8; HEADER_LEN];
+    hdr[0..2].copy_from_slice(&rows.to_le_bytes());
+    hdr[2..4].copy_from_slice(&cols.to_le_bytes());
+    hdr[4] = flags;
+    hdr
+}
+
+fn restore_parser(state: &[u8], rows: u16, cols: u16) -> vt100::Parser {
+    let mut parser = vt100::Parser::new(rows, cols, 0);
+    if state.len() <= HEADER_LEN {
+        return parser;
+    }
+
+    let flags = state[4];
+    if flags & 1 != 0 && state.len() > HEADER_LEN + 4 {
+        // Alt screen was active: [header][main_len:4][main_state][alt_state]
+        let main_len =
+            u32::from_le_bytes([state[5], state[6], state[7], state[8]]) as usize;
+        let main_start = HEADER_LEN + 4;
+        let main_end = main_start + main_len;
+
+        if main_len > 0 && main_end <= state.len() {
+            parser.process(&state[main_start..main_end]);
+        }
+        parser.process(b"\x1b[?1049h");
+        if main_end < state.len() {
+            parser.process(&state[main_end..]);
+        }
+    } else {
+        parser.process(&state[HEADER_LEN..]);
+    }
+
+    parser
+}
+
+fn pack_result(ptr: u32, len: u32) -> u64 {
+    ((ptr as u64) << 32) | (len as u64)
+}
+
+fn return_bytes(data: &[u8]) -> u64 {
+    let len = data.len() as u32;
+    if len == 0 {
+        return 0;
+    }
+    let ptr = wasm_alloc(len);
+    if ptr != 0 {
+        unsafe {
+            std::ptr::copy_nonoverlapping(data.as_ptr(), ptr as *mut u8, data.len());
+        }
+    }
+    pack_result(ptr, len)
+}
+
+fn serialize_state(parser: &mut vt100::Parser, rows: u16, cols: u16) -> Vec<u8> {
+    let is_alt = parser.screen().alternate_screen();
+    let flags: u8 = if is_alt { 1 } else { 0 };
+    let hdr = make_header(rows, cols, flags);
+
+    if is_alt {
+        let alt_formatted = parser.screen().state_formatted();
+        parser.process(b"\x1b[?1049l");
+        let main_formatted = parser.screen().state_formatted();
+        let main_len = (main_formatted.len() as u32).to_le_bytes();
+
+        let mut out =
+            Vec::with_capacity(HEADER_LEN + 4 + main_formatted.len() + alt_formatted.len());
+        out.extend_from_slice(&hdr);
+        out.extend_from_slice(&main_len);
+        out.extend_from_slice(&main_formatted);
+        out.extend_from_slice(&alt_formatted);
+        out
+    } else {
+        let formatted = parser.screen().state_formatted();
+        let mut out = Vec::with_capacity(HEADER_LEN + formatted.len());
+        out.extend_from_slice(&hdr);
+        out.extend_from_slice(&formatted);
+        out
+    }
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn apply_delta(
+    state_ptr: u32,
+    state_len: u32,
+    delta_ptr: u32,
+    delta_len: u32,
+    rows: u32,
+    cols: u32,
+) -> u64 {
+    let rows = rows as u16;
+    let cols = cols as u16;
+
+    let state: Option<&[u8]> = if state_ptr == 0 || (state_len as usize) < HEADER_LEN {
+        None
+    } else {
+        Some(unsafe { slice::from_raw_parts(state_ptr as *const u8, state_len as usize) })
+    };
+
+    let delta = if delta_ptr == 0 || delta_len == 0 {
+        &[]
+    } else {
+        unsafe { slice::from_raw_parts(delta_ptr as *const u8, delta_len as usize) }
+    };
+
+    let mut parser = match state {
+        Some(s) => {
+            let (prev_rows, prev_cols, _) = parse_header(s);
+            let mut p = restore_parser(s, prev_rows, prev_cols);
+            if prev_rows != rows || prev_cols != cols {
+                p.screen_mut().set_size(rows, cols);
+            }
+            p
+        }
+        None => vt100::Parser::new(rows, cols, 0),
+    };
+
+    parser.process(delta);
+
+    return_bytes(&serialize_state(&mut parser, rows, cols))
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn screen_contents(state_ptr: u32, state_len: u32) -> u64 {
+    if state_ptr == 0 || (state_len as usize) < HEADER_LEN {
+        return 0;
+    }
+    let state = unsafe { slice::from_raw_parts(state_ptr as *const u8, state_len as usize) };
+    let (rows, cols, _) = parse_header(state);
+    let parser = restore_parser(state, rows, cols);
+    let contents = parser.screen().contents();
+    return_bytes(contents.as_bytes())
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn screen_contents_formatted(state_ptr: u32, state_len: u32) -> u64 {
+    if state_ptr == 0 || (state_len as usize) < HEADER_LEN {
+        return 0;
+    }
+    let state = unsafe { slice::from_raw_parts(state_ptr as *const u8, state_len as usize) };
+    let (rows, cols, _) = parse_header(state);
+    let parser = restore_parser(state, rows, cols);
+    let formatted = parser.screen().contents_formatted();
+    return_bytes(&formatted)
+}

vt100wasm-0.1.0/src/vt100wasm/__init__.py

@@ -0,0 +1,96 @@
+import ctypes
+from pathlib import Path
+
+from wasmtime import Engine, Linker, Module, Store, WasiConfig
+
+_WASM_PATH = Path(__file__).parent / "_vt100.wasm"
+
+_engine = Engine()
+_module = Module.from_file(_engine, str(_WASM_PATH))
+
+
+def _unpack_result(packed: int) -> tuple[int, int]:
+    ptr = (packed >> 32) & 0xFFFFFFFF
+    length = packed & 0xFFFFFFFF
+    return ptr, length
+
+
+class _Runtime:
+    def __init__(self) -> None:
+        self._store = Store(_engine)
+        config = WasiConfig()
+        self._store.set_wasi(config)
+        linker = Linker(_engine)
+        linker.define_wasi()
+        instance = linker.instantiate(self._store, _module)
+        exports = instance.exports(self._store)
+        self._memory = exports["memory"]
+        self._alloc_fn = exports["wasm_alloc"]
+        self._dealloc_fn = exports["wasm_dealloc"]
+        self._apply_delta_fn = exports["apply_delta"]
+        self._screen_contents_fn = exports["screen_contents"]
+        self._screen_contents_formatted_fn = exports["screen_contents_formatted"]
+
+    def _write_bytes(self, data: bytes) -> tuple[int, int]:
+        size = len(data)
+        if size == 0:
+            return 0, 0
+        ptr = self._alloc_fn(self._store, size)
+        if ptr == 0:
+            raise MemoryError(f"WASM allocation failed for {size} bytes")
+        self._memory.write(self._store, data, ptr)
+        return ptr, size
+
+    def _read_result(self, packed: int) -> bytes:
+        ptr, length = _unpack_result(packed)
+        if ptr == 0 or length == 0:
+            return b""
+        base = ctypes.addressof(self._memory.data_ptr(self._store).contents)
+        result = (ctypes.c_char * length).from_address(base + ptr).raw
+        self._dealloc_fn(self._store, ptr, length)
+        return result
+
+    def apply_delta(self, state: bytes | None, delta: bytes, rows: int, cols: int) -> bytes:
+        if state is not None:
+            s_ptr, s_len = self._write_bytes(state)
+        else:
+            s_ptr, s_len = 0, 0
+        d_ptr, d_len = self._write_bytes(delta)
+        packed = self._apply_delta_fn(self._store, s_ptr, s_len, d_ptr, d_len, rows, cols)
+        if s_ptr:
+            self._dealloc_fn(self._store, s_ptr, s_len)
+        if d_ptr:
+            self._dealloc_fn(self._store, d_ptr, d_len)
+        return self._read_result(packed)
+
+    def screen_contents(self, state: bytes) -> str:
+        s_ptr, s_len = self._write_bytes(state)
+        packed = self._screen_contents_fn(self._store, s_ptr, s_len)
+        if s_ptr:
+            self._dealloc_fn(self._store, s_ptr, s_len)
+        return self._read_result(packed).decode("utf-8")
+
+    def screen_contents_formatted(self, state: bytes) -> bytes:
+        s_ptr, s_len = self._write_bytes(state)
+        packed = self._screen_contents_formatted_fn(self._store, s_ptr, s_len)
+        if s_ptr:
+            self._dealloc_fn(self._store, s_ptr, s_len)
+        return self._read_result(packed)
+
+
+_runtime = _Runtime()
+
+
+def apply_delta(state: bytes | None, delta: bytes, rows: int, cols: int) -> bytes:
+    return _runtime.apply_delta(state, delta, rows, cols)
+
+
+def screen_contents(state: bytes) -> str:
+    return _runtime.screen_contents(state)
+
+
+def screen_contents_formatted(state: bytes) -> bytes:
+    return _runtime.screen_contents_formatted(state)
+
+
+__all__ = ["apply_delta", "screen_contents", "screen_contents_formatted"]

vt100wasm-0.1.0/tests/test_vt100.py

@@ -0,0 +1,265 @@
+from vt100wasm import apply_delta, screen_contents, screen_contents_formatted
+
+
+class TestApplyDelta:
+    def test_initial_state_from_none(self):
+        state = apply_delta(None, b"hello", 24, 80)
+        assert isinstance(state, bytes)
+        assert len(state) > 5
+        assert screen_contents(state).startswith("hello")
+
+    def test_incremental_update(self):
+        s1 = apply_delta(None, b"hello", 24, 80)
+        s2 = apply_delta(s1, b" world", 24, 80)
+        assert "hello world" in screen_contents(s2)
+
+    def test_empty_delta_preserves_state(self):
+        s1 = apply_delta(None, b"hello", 24, 80)
+        s2 = apply_delta(s1, b"", 24, 80)
+        assert screen_contents(s1) == screen_contents(s2)
+
+    def test_newline_handling(self):
+        state = apply_delta(None, b"line1\r\nline2\r\nline3", 24, 80)
+        contents = screen_contents(state)
+        assert "line1" in contents
+        assert "line2" in contents
+        assert "line3" in contents
+
+    def test_ansi_escape_codes(self):
+        state = apply_delta(None, b"\x1b[31mred\x1b[0m normal", 24, 80)
+        contents = screen_contents(state)
+        assert "red" in contents
+        assert "normal" in contents
+
+    def test_header_encodes_dimensions(self):
+        state = apply_delta(None, b"x", 30, 120)
+        rows = int.from_bytes(state[0:2], "little")
+        cols = int.from_bytes(state[2:4], "little")
+        assert rows == 30
+        assert cols == 120
+
+    def test_utf8_content(self):
+        state = apply_delta(None, b"hello world", 24, 80)
+        contents = screen_contents(state)
+        assert "hello" in contents
+
+    def test_large_output(self):
+        data = (b"x" * 79 + b"\r\n") * 100
+        state = apply_delta(None, data, 24, 80)
+        assert isinstance(state, bytes)
+        assert len(state) > 4
+
+
+class TestResize:
+    def test_resize_changes_dimensions(self):
+        s1 = apply_delta(None, b"hello", 24, 80)
+        s2 = apply_delta(s1, b"", 40, 120)
+        rows = int.from_bytes(s2[0:2], "little")
+        cols = int.from_bytes(s2[2:4], "little")
+        assert rows == 40
+        assert cols == 120
+
+    def test_resize_preserves_content(self):
+        s1 = apply_delta(None, b"hello", 24, 80)
+        s2 = apply_delta(s1, b"", 40, 120)
+        assert "hello" in screen_contents(s2)
+
+
+class TestScreenContents:
+    def test_empty_state(self):
+        assert screen_contents(b"") == ""
+
+    def test_short_state(self):
+        assert screen_contents(b"\x00\x00") == ""
+
+    def test_plain_text(self):
+        state = apply_delta(None, b"hello world", 24, 80)
+        assert screen_contents(state).startswith("hello world")
+
+
+class TestScreenContentsFormatted:
+    def test_empty_state(self):
+        assert screen_contents_formatted(b"") == b""
+
+    def test_short_state(self):
+        assert screen_contents_formatted(b"\x00\x00") == b""
+
+    def test_roundtrip(self):
+        state = apply_delta(None, b"hello\r\nworld", 24, 80)
+        formatted = screen_contents_formatted(state)
+        assert isinstance(formatted, bytes)
+        assert len(formatted) > 0
+        roundtrip = apply_delta(None, formatted, 24, 80)
+        assert screen_contents(roundtrip) == screen_contents(state)
+
+    def test_ansi_preserved_in_formatted(self):
+        state = apply_delta(None, b"\x1b[1mbold\x1b[0m", 24, 80)
+        formatted = screen_contents_formatted(state)
+        assert b"bold" in formatted
+
+
+class TestCursorMovement:
+    def test_cursor_home(self):
+        state = apply_delta(None, b"overwrite\x1b[Hnew", 24, 80)
+        contents = screen_contents(state)
+        assert contents.startswith("newrwrite")
+
+    def test_cursor_absolute_position(self):
+        state = apply_delta(None, b"\x1b[3;5Hx", 24, 80)
+        lines = screen_contents(state).split("\n")
+        assert lines[2][4] == "x"
+
+    def test_cursor_up(self):
+        state = apply_delta(None, b"first\r\nsecond\x1b[1A\r\ninserted", 24, 80)
+        contents = screen_contents(state)
+        assert "inserted" in contents
+        assert "first" in contents
+
+    def test_cursor_forward_and_back(self):
+        # cursor back 3 from end of "abcdef" lands on 'd', forward 1 lands on 'e'
+        state = apply_delta(None, b"abcdef\x1b[3D\x1b[1CXYZ", 24, 80)
+        contents = screen_contents(state)
+        assert "abcdXYZ" in contents
+
+
+class TestEraseOperations:
+    def test_erase_to_end_of_line(self):
+        state = apply_delta(None, b"hello world\x1b[H\x1b[5C\x1b[K", 24, 80)
+        contents = screen_contents(state)
+        assert "hello" in contents
+        assert "world" not in contents
+
+    def test_erase_entire_line(self):
+        state = apply_delta(None, b"delete me\x1b[2K", 24, 80)
+        first_line = screen_contents(state).split("\n")[0]
+        assert first_line.strip() == ""
+
+    def test_erase_display(self):
+        state = apply_delta(None, b"line1\r\nline2\r\nline3\x1b[2J", 24, 80)
+        contents = screen_contents(state)
+        assert contents.strip() == ""
+
+    def test_erase_to_beginning_of_line(self):
+        state = apply_delta(None, b"hello world\x1b[6G\x1b[1K", 24, 80)
+        first_line = screen_contents(state).split("\n")[0]
+        assert "world" in first_line
+        assert not first_line.startswith("hello")
+
+
+class TestScrolling:
+    def test_scroll_down_past_bottom(self):
+        lines = b"".join(f"line{i}\r\n".encode() for i in range(30))
+        state = apply_delta(None, lines, 24, 80)
+        contents = screen_contents(state)
+        assert "line29" in contents
+        assert "line0" not in contents
+
+    def test_scroll_region(self):
+        state = apply_delta(None, b"\x1b[5;10r\x1b[10;1H\n\n\n", 24, 80)
+        assert isinstance(screen_contents(state), str)
+
+    def test_reverse_index_scrolls_up(self):
+        state = apply_delta(None, b"\x1b[1;1H\x1bM", 24, 80)
+        assert isinstance(screen_contents(state), str)
+
+
+class TestTextAttributes:
+    def test_sgr_bold_in_formatted(self):
+        state = apply_delta(None, b"\x1b[1mbold text\x1b[0m", 24, 80)
+        formatted = screen_contents_formatted(state)
+        assert b"\x1b[1m" in formatted
+        assert b"bold text" in formatted
+
+    def test_sgr_colors_in_formatted(self):
+        state = apply_delta(None, b"\x1b[31mred\x1b[32mgreen\x1b[0m", 24, 80)
+        formatted = screen_contents_formatted(state)
+        assert b"red" in formatted
+        assert b"green" in formatted
+
+    def test_sgr_256_color(self):
+        state = apply_delta(None, b"\x1b[38;5;196mred256\x1b[0m", 24, 80)
+        contents = screen_contents(state)
+        assert "red256" in contents
+        formatted = screen_contents_formatted(state)
+        assert b"\x1b[38;5;196m" in formatted
+
+    def test_sgr_24bit_color(self):
+        state = apply_delta(None, b"\x1b[38;2;255;0;0mtrue red\x1b[0m", 24, 80)
+        contents = screen_contents(state)
+        assert "true red" in contents
+
+    def test_multiple_attributes(self):
+        state = apply_delta(None, b"\x1b[1;4;31mbold underline red\x1b[0m", 24, 80)
+        formatted = screen_contents_formatted(state)
+        assert b"bold underline red" in formatted
+
+    def test_reset_clears_attributes(self):
+        state = apply_delta(None, b"\x1b[1;31mcolored\x1b[0m plain", 24, 80)
+        contents = screen_contents(state)
+        assert "colored" in contents
+        assert "plain" in contents
+
+
+class TestTabsAndSpecialChars:
+    def test_tab_stop(self):
+        state = apply_delta(None, b"a\tb", 24, 80)
+        contents = screen_contents(state)
+        assert "a" in contents
+        assert "b" in contents
+        first_line = contents.split("\n")[0]
+        assert first_line.index("b") >= 8
+
+    def test_backspace(self):
+        state = apply_delta(None, b"ab\x08c", 24, 80)
+        contents = screen_contents(state)
+        assert "ac" in contents
+
+    def test_carriage_return(self):
+        state = apply_delta(None, b"old text\rnew", 24, 80)
+        contents = screen_contents(state)
+        assert "new" in contents
+        assert not contents.startswith("old")
+
+
+class TestAlternateScreen:
+    def test_switch_to_alt_clears(self):
+        state = apply_delta(None, b"main screen\x1b[?1049h", 24, 80)
+        contents_alt = screen_contents(state)
+        assert "main screen" not in contents_alt
+
+    def test_alt_screen_content(self):
+        s1 = apply_delta(None, b"\x1b[?1049halt content", 24, 80)
+        assert "alt content" in screen_contents(s1)
+
+    def test_switch_to_alt_and_back(self):
+        s1 = apply_delta(None, b"main screen\x1b[?1049h", 24, 80)
+        s2 = apply_delta(s1, b"\x1b[?1049l", 24, 80)
+        assert "main screen" in screen_contents(s2)
+
+    def test_alt_screen_preserves_main_across_deltas(self):
+        s1 = apply_delta(None, b"main content\x1b[?1049h", 24, 80)
+        s2 = apply_delta(s1, b"alt content", 24, 80)
+        assert "alt content" in screen_contents(s2)
+        assert "main content" not in screen_contents(s2)
+        s3 = apply_delta(s2, b"\x1b[?1049l", 24, 80)
+        assert "main content" in screen_contents(s3)
+
+    def test_alt_flag_in_header(self):
+        s_main = apply_delta(None, b"hello", 24, 80)
+        assert s_main[4] == 0
+        s_alt = apply_delta(None, b"\x1b[?1049h", 24, 80)
+        assert s_alt[4] == 1
+
+
+class TestLineWrapping:
+    def test_auto_wrap(self):
+        state = apply_delta(None, b"x" * 85, 24, 80)
+        contents = screen_contents(state)
+        assert "x" * 85 in contents
+
+    def test_wrap_preserves_all_chars(self):
+        text = b"".join(bytes([ord("a") + (i % 26)]) for i in range(85))
+        state = apply_delta(None, text, 24, 80)
+        contents = screen_contents(state)
+        joined = "".join(line.rstrip() for line in contents.split("\n"))
+        assert joined == text.decode()