diff --git a/Cargo.lock b/Cargo.lock
index 9b7c309..a8fc97b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -198,7 +198,7 @@ version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
]
[[package]]
@@ -209,7 +209,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
]
[[package]]
@@ -407,6 +407,12 @@ version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+[[package]]
+name = "base64"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
+
[[package]]
name = "base64"
version = "0.22.1"
@@ -1146,7 +1152,7 @@ dependencies = [
"wasm-bindgen",
"wasm-bindgen-futures",
"web-time",
- "windows-sys 0.61.2",
+ "windows-sys 0.59.0",
]
[[package]]
@@ -1817,6 +1823,12 @@ version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2ec7c5eb7a16992b1904d76c517d170ab353b0e0b3d5a0c81a8a0cd1037893cf"
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
[[package]]
name = "colorchoice"
version = "1.0.5"
@@ -2185,7 +2197,7 @@ dependencies = [
"libc",
"option-ext",
"redox_users",
- "windows-sys 0.61.2",
+ "windows-sys 0.59.0",
]
[[package]]
@@ -2320,7 +2332,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
]
[[package]]
@@ -2483,6 +2495,15 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+[[package]]
+name = "font-types"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39a654f404bbcbd48ea58c617c2993ee91d1cb63727a37bf2323a4edeed1b8c5"
+dependencies = [
+ "bytemuck",
+]
+
[[package]]
name = "font-types"
version = "0.11.3"
@@ -2506,7 +2527,7 @@ dependencies = [
"objc2-core-text",
"objc2-foundation 0.3.2",
"parlance",
- "read-fonts",
+ "read-fonts 0.39.2",
"roxmltree",
"smallvec",
"windows",
@@ -2672,6 +2693,16 @@ dependencies = [
"wasip3",
]
+[[package]]
+name = "gif"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
[[package]]
name = "gl_generator"
version = "0.14.0"
@@ -2714,10 +2745,13 @@ version = "1.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e3ce1918195723ce6ac74e80542c5a96a40c2b26162c1957a5cd70799b8cacf7"
dependencies = [
+ "base64 0.13.1",
"byteorder",
"gltf-json",
+ "image",
"lazy_static",
"serde_json",
+ "urlencoding",
]
[[package]]
@@ -2828,7 +2862,7 @@ checksum = "d12c7c642d4ce8c2e784b4751a6634bd89583912265add4a679a8882d123fbcd"
dependencies = [
"bitflags 2.13.0",
"bytemuck",
- "read-fonts",
+ "read-fonts 0.39.2",
"smallvec",
]
@@ -3067,10 +3101,25 @@ checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
dependencies = [
"bytemuck",
"byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
"moxcms",
"num-traits",
"png",
"tiff",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
]
[[package]]
@@ -3636,7 +3685,7 @@ version = "0.50.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.59.0",
]
[[package]]
@@ -4056,7 +4105,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d8fae84b431384b68627d0f9b3b1245fcf9f46f6c0e3dc902e9dce64edd1967"
dependencies = [
"libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
]
[[package]]
@@ -4142,7 +4191,7 @@ dependencies = [
"linebender_resource_handle",
"parlance",
"parley_data",
- "skrifa",
+ "skrifa 0.42.1",
]
[[package]]
@@ -4712,10 +4761,13 @@ dependencies = [
"bevy",
"clap",
"etcetera",
+ "gltf",
"image",
+ "libc",
"parley_ratatui",
"portable-pty",
"ratatui",
+ "rio-graphics",
"rio-vt",
"rust-embed",
"serde",
@@ -4745,6 +4797,16 @@ dependencies = [
"objc2-quartz-core 0.3.2",
]
+[[package]]
+name = "read-fonts"
+version = "0.35.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6717cf23b488adf64b9d711329542ba34de147df262370221940dfabc2c91358"
+dependencies = [
+ "bytemuck",
+ "font-types 0.10.1",
+]
+
[[package]]
name = "read-fonts"
version = "0.39.2"
@@ -4752,7 +4814,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c4ed38b89c2c77ff968c524145ad65fb010f38af5c7a224b53b81d47ac2daa81"
dependencies = [
"bytemuck",
- "font-types",
+ "font-types 0.11.3",
]
[[package]]
@@ -4836,9 +4898,8 @@ checksum = "19b30a45b0cd0bcca8037f3d0dc3421eaf95327a17cad11964fb8179b4fc4832"
[[package]]
name = "rio-grapheme-width"
-version = "0.5.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8748a230342b653830718978aa78fc7e4887bcf2d1292228ea1e033dd0207151"
+version = "0.5.20"
+source = "git+https://github.com/gold-silver-copper/rio?rev=535495772f8548e2cbf9a840938c8eca21714888#535495772f8548e2cbf9a840938c8eca21714888"
dependencies = [
"phf 0.13.1",
"ucd-trie",
@@ -4846,24 +4907,32 @@ dependencies = [
[[package]]
name = "rio-graphics"
-version = "0.5.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "150067cf37f1468cffffae9cbfd40e106adc5f8451239b5b0a7fa660b6a5a91c"
+version = "0.5.20"
+source = "git+https://github.com/gold-silver-copper/rio?rev=535495772f8548e2cbf9a840938c8eca21714888#535495772f8548e2cbf9a840938c8eca21714888"
dependencies = [
+ "image",
+ "parking_lot",
"rustc-hash 2.1.3",
+ "skrifa 0.37.0",
"tracing",
+ "web-time",
]
+[[package]]
+name = "rio-unicode"
+version = "0.1.0"
+source = "git+https://github.com/gold-silver-copper/rio?rev=535495772f8548e2cbf9a840938c8eca21714888#535495772f8548e2cbf9a840938c8eca21714888"
+
[[package]]
name = "rio-vt"
-version = "0.5.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82bb771ed37480c3bec80684513a5d136a7cd5a32a86c0bf13a6d7cb0239b600"
+version = "0.5.20"
+source = "git+https://github.com/gold-silver-copper/rio?rev=535495772f8548e2cbf9a840938c8eca21714888#535495772f8548e2cbf9a840938c8eca21714888"
dependencies = [
"base64 0.23.0",
"bitflags 2.13.0",
"cursor-icon",
"flate2",
+ "image",
"libc",
"memchr",
"parking_lot",
@@ -4871,12 +4940,13 @@ dependencies = [
"regex-automata",
"rio-grapheme-width",
"rio-graphics",
+ "rio-unicode",
"rustc-hash 2.1.3",
"serde",
"simdutf",
"smallvec",
"tracing",
- "unicode-width-16",
+ "web-time",
"windows-sys 0.61.2",
]
@@ -4981,7 +5051,7 @@ dependencies = [
"errno",
"libc",
"linux-raw-sys 0.12.1",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
]
[[package]]
@@ -5274,6 +5344,16 @@ version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b2aa850e253778c88a04c3d7323b043aeda9d3e30d5971937c1855769763678e"
+[[package]]
+name = "skrifa"
+version = "0.37.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c31071dedf532758ecf3fed987cdb4bd9509f900e026ab684b4ecb81ea49841"
+dependencies = [
+ "bytemuck",
+ "read-fonts 0.35.0",
+]
+
[[package]]
name = "skrifa"
version = "0.42.1"
@@ -5281,7 +5361,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c34617370ae968efb7161bb2beb517d9084659aae19e24b89e3db25b46e4564"
dependencies = [
"bytemuck",
- "read-fonts",
+ "read-fonts 0.39.2",
]
[[package]]
@@ -5429,7 +5509,7 @@ version = "0.2.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0811b01ca2c4e8718760713911feaf4675c24f94e50530a015ec646cfb622f7c"
dependencies = [
- "skrifa",
+ "skrifa 0.42.1",
"yazi",
"zeno",
]
@@ -5497,7 +5577,7 @@ dependencies = [
"parking_lot",
"rustix 1.1.4",
"signal-hook",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
]
[[package]]
@@ -5968,18 +6048,18 @@ version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
-[[package]]
-name = "unicode-width-16"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9eba15036aa0f5bf8ed6cd12a624ddb61fd50b0779b1c05d89b663bcaed7b5c2"
-
[[package]]
name = "unicode-xid"
version = "0.2.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
+[[package]]
+name = "urlencoding"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
+
[[package]]
name = "utf8_iter"
version = "1.0.4"
@@ -6033,7 +6113,7 @@ dependencies = [
"log",
"peniko",
"png",
- "skrifa",
+ "skrifa 0.42.1",
"static_assertions",
"thiserror 2.0.18",
"vello_encoding",
@@ -6050,7 +6130,7 @@ dependencies = [
"bytemuck",
"guillotiere 0.7.0",
"peniko",
- "skrifa",
+ "skrifa 0.42.1",
"smallvec",
]
@@ -6621,7 +6701,7 @@ version = "0.1.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
]
[[package]]
diff --git a/Cargo.toml b/Cargo.toml
index 019d8d2..cdf3195 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -41,11 +41,14 @@ bevy = { version = "0.19.0", default-features = false, features = [
] }
clap = { version = "4.5", features = ["derive"] }
etcetera = "0.11"
+gltf = "1.4"
image = { version = "0.25", default-features = false, features = ["png", "ico"] }
+libc = "0.2"
parley_ratatui = "0.3.4"
portable-pty = "0.8"
ratatui = "0.30"
-rio-vt = { version = "0.5.19", default-features = false }
+rio-graphics = { git = "https://github.com/gold-silver-copper/rio", rev = "535495772f8548e2cbf9a840938c8eca21714888" }
+rio-vt = { git = "https://github.com/gold-silver-copper/rio", rev = "535495772f8548e2cbf9a840938c8eca21714888", default-features = false, features = ["graphics"] }
rust-embed = "8.5"
serde = { version = "1.0", features = ["derive"] }
shellexpand = "3.1"
diff --git a/README.md b/README.md
index 60c0e61..345583a 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ Inspired by TempleOS | Built with Rust & Ratatui
- Spinning rat cursor ([customizable](#changing-the-cursor))
- Traditional 2D and [new 3D mode](#3d-mode)!
- [Inline 3D objects](#inline-3d-objects)
+- [Inline 2D bitmap surfaces](#inline-2d-bitmap-surfaces)
- [GPU-backed text rendering](#rendering-pipeline)
- Image support (via Kitty Graphics Protocol >:\()
@@ -233,6 +234,96 @@ A blazingly fast serial monitor with plotter TUI and 3D telemetry
+## Inline 2D bitmap surfaces
+
+Ratty's [Bitmap Surface Protocol](protocols/bitmap.md) lets terminal applications
+register a PNG once, place it in terminal-cell space, and update its crop,
+destination, fit, filtering, or opacity without uploading the image again.
+Applications can also replace the pixels with fixed-size RGBA8 frames for video
+or screen-share rendering.
+
+Query support before using the protocol:
+
+```text
+ESC _ ratty;i;s ESC \
+```
+
+Ratty replies with:
+
+```text
+ESC _ ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1 ESC \
+```
+
+If no reply arrives, treat bitmap surfaces as unsupported and use another render
+path or a text fallback. See the protocol specification for the complete wire
+format, validation rules, and lifecycle.
+
+Try interactive pan, zoom, fit, filtering, and opacity with a PNG:
+
+```bash
+cargo run --example bitmap_pan_zoom --
+```
+
+Try generated RGBA8 frames at 15 FPS for 10 seconds:
+
+```bash
+cargo run --example bitmap_frames -- --fps 15 --duration 10 --width 320 --height 180
+```
+
+`bitmap_frames` accepts `--fps`, `--duration`, `--width`, and `--height`; their
+defaults are `15`, `10`, `320`, and `180`. Both examples register one bitmap,
+create one placement, update that stable bitmap or placement, and delete both on
+exit. Multiple placements can share the same bitmap and Bevy image handle.
+
+Ratty owns APC parsing, PNG registration, raw RGBA8 frame validation and upload,
+stable image and placement state, and rendering. The application owns capture,
+network transport, codec choices such as VP8, and decoding compressed video to
+RGBA8 before sending frames to Ratty.
+
+The `[bitmap]` configuration section bounds registered bitmap and placement
+counts, image dimensions, bytes per decoded bitmap, total decoded bytes across
+registered bitmaps, retained bytes across incomplete transfers, and the number
+of concurrent incomplete transfers. See
+[`config/ratty.toml`](config/ratty.toml) for the default limits.
+
+Current v1 boundaries:
+
+- live frames are full, fixed-dimension RGBA8; frame resizing is rejected
+- no live-frame compression, delta updates, or dirty rectangles
+- no codec decoding, VP8 handling, capture, or networking in Ratty
+
+### Kitty graphics
+
+Kitty Graphics Protocol handling is native to `rio-vt`: Ratty forwards complete
+Kitty APC frames unchanged and owns only the Bevy image assets and draw
+entities created from rio-vt's graphics updates and placement geometry. This
+keeps Kitty parsing, replies, image lifetime, direct placement mutation,
+Unicode-placeholder cells, scrollback, reflow, and alternate-screen behavior
+in the terminal state machine.
+
+The renderer supports direct RGB/RGBA and PNG transfers, padded or unpadded
+standard base64, `o=z` zlib compression, multi-APC chunking, crop and cell
+spans, pixel offsets, z-index, retransmission, and deletion. Unicode
+placeholders remain ordinary terminal cells, so scrolling, resizing, reflow,
+and erasure naturally change which image slices are visible. Current `kitten
+icat --transfer-mode=stream` and its `--unicode-placeholder` mode use these
+paths.
+
+Ordinary negative Kitty z-index placements currently render below Ratty's
+combined terminal texture, so non-default cell backgrounds can obscure them.
+Extreme-negative/default-background placement and image-to-image z ordering
+remain supported.
+
+Ratty deliberately permits only Kitty's direct PTY-stream medium. File,
+temporary-file, and shared-memory media are disabled and capability queries for
+them fail. The `[bitmap]` limits also configure Kitty's encoded, decoded,
+decompressed, dimension, resident-byte, placement, and incomplete-transfer
+budgets. Incomplete transfers expire after ten seconds, malformed or
+interleaved transfers abort without replacing valid pixels, and an unterminated
+APC is discarded once it reaches its configured encoded bound. Ratty reports
+`OK` only after the configured parser, storage, placement, and render path can
+honor the request.
+
## Architecture
### Rendering pipeline
diff --git a/config/ratty.toml b/config/ratty.toml
index 5f31c56..859631e 100644
--- a/config/ratty.toml
+++ b/config/ratty.toml
@@ -12,6 +12,16 @@ default_rows = 32
scrollback = 2000
mouse_scroll_lines = 3
+[bitmap]
+max_bitmaps = 1024
+max_placements = 4096
+max_image_width = 8192
+max_image_height = 8192
+max_bitmap_bytes = 67108864
+max_total_bitmap_bytes = 268435456
+max_pending_bytes = 67108864
+max_pending_transfers = 16
+
# [shell]
# program = "/bin/bash"
# args = []
diff --git a/examples/bitmap_frames.rs b/examples/bitmap_frames.rs
new file mode 100644
index 0000000..16f09ad
--- /dev/null
+++ b/examples/bitmap_frames.rs
@@ -0,0 +1,676 @@
+use std::{
+ io::{self, Stdout, Write},
+ thread,
+ time::{Duration, Instant},
+};
+
+use anyhow::{Context, Result, ensure};
+use base64::Engine as _;
+use clap::Parser;
+use image::ImageEncoder as _;
+use ratatui::crossterm::{
+ cursor::{Hide, MoveTo, Show},
+ execute, queue,
+ style::Print,
+ terminal::{
+ self, Clear, ClearType, EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode,
+ enable_raw_mode,
+ },
+};
+
+const BITMAP_ID: u32 = 42;
+const PLACEMENT_ID: u32 = 7;
+const MAX_BASE64_CHUNK: usize = 4096;
+const APC_PREFIX: &str = "\u{1b}_ratty;i;";
+const APC_END: &str = "\u{1b}\\";
+
+#[derive(Parser)]
+#[command(about = "Stream generated RGBA8 frames through Ratty's bitmap surface protocol")]
+struct Args {
+ /// Frames per second.
+ #[arg(long, default_value_t = 15)]
+ fps: u32,
+
+ /// Run duration in seconds.
+ #[arg(long, default_value_t = 10.0)]
+ duration: f64,
+
+ /// Bitmap width in pixels.
+ #[arg(long, default_value_t = 320)]
+ width: u32,
+
+ /// Bitmap height in pixels.
+ #[arg(long, default_value_t = 180)]
+ height: u32,
+}
+
+fn encode_registration(bitmap_id: u32, encoded_png: &str) -> Vec> {
+ debug_assert_eq!(MAX_BASE64_CHUNK % 4, 0);
+ let chunks: Vec<_> = encoded_png.as_bytes().chunks(MAX_BASE64_CHUNK).collect();
+ let last = chunks.len().saturating_sub(1);
+
+ chunks
+ .into_iter()
+ .enumerate()
+ .map(|(index, payload)| {
+ let payload = std::str::from_utf8(payload).expect("base64 is ASCII");
+ let more = u8::from(index != last);
+ if index == 0 {
+ encode_command(format!(
+ "r;id={bitmap_id};fmt=png;source=payload;more={more};{payload}"
+ ))
+ } else {
+ encode_command(format!("r;id={bitmap_id};more={more};{payload}"))
+ }
+ })
+ .collect()
+}
+
+fn encode_placement(
+ bitmap_id: u32,
+ placement_id: u32,
+ row: u16,
+ col: u16,
+ columns: u32,
+ rows: u32,
+) -> Vec {
+ // row/col are visible coordinates now; Ratty attaches the resulting
+ // placement to this alternate-screen content for later scroll/reflow.
+ encode_command(format!(
+ "p;id={bitmap_id};pid={placement_id};row={row};col={col};w={columns};h={rows};fit=contain;filter=linear;opacity=1"
+ ))
+}
+
+fn encode_frame(
+ bitmap_id: u32,
+ sequence: u32,
+ width: u32,
+ height: u32,
+ rgba: &[u8],
+) -> Result>> {
+ ensure!(width > 0 && height > 0, "frame dimensions must be nonzero");
+ let expected_len = width
+ .checked_mul(height)
+ .and_then(|pixels| pixels.checked_mul(4))
+ .and_then(|bytes| usize::try_from(bytes).ok())
+ .context("frame dimensions overflow")?;
+ ensure!(
+ rgba.len() == expected_len,
+ "RGBA8 frame length does not match its dimensions"
+ );
+
+ let encoded = base64::engine::general_purpose::STANDARD.encode(rgba);
+ debug_assert_eq!(MAX_BASE64_CHUNK % 4, 0);
+ let chunks: Vec<_> = encoded.as_bytes().chunks(MAX_BASE64_CHUNK).collect();
+ let last = chunks.len().saturating_sub(1);
+
+ Ok(chunks
+ .into_iter()
+ .enumerate()
+ .map(|(index, payload)| {
+ let payload = std::str::from_utf8(payload).expect("base64 is ASCII");
+ let more = u8::from(index != last);
+ if index == 0 {
+ encode_command(format!(
+ "f;id={bitmap_id};seq={sequence};fmt=rgba8;w={width};h={height};more={more};{payload}"
+ ))
+ } else {
+ encode_command(format!(
+ "f;id={bitmap_id};seq={sequence};more={more};{payload}"
+ ))
+ }
+ })
+ .collect())
+}
+
+fn encode_deletion(bitmap_id: u32, placement_id: u32) -> [Vec; 2] {
+ [
+ encode_command(format!("d;pid={placement_id}")),
+ encode_command(format!("d;id={bitmap_id}")),
+ ]
+}
+
+fn encode_command(body: String) -> Vec {
+ format!("{APC_PREFIX}{body}{APC_END}").into_bytes()
+}
+
+struct LatestFrameScheduler {
+ interval: Duration,
+ next_sequence: Option,
+}
+
+impl LatestFrameScheduler {
+ const fn new(interval: Duration) -> Self {
+ Self {
+ interval,
+ next_sequence: Some(1),
+ }
+ }
+
+ fn due_sequence(&mut self, elapsed: Duration) -> Option {
+ let next_sequence = self.next_sequence?;
+ let latest_tick = elapsed.as_nanos() / self.interval.as_nanos();
+ let latest_tick = u32::try_from(latest_tick).unwrap_or(u32::MAX);
+ if latest_tick < next_sequence {
+ return None;
+ }
+
+ self.next_sequence = latest_tick.checked_add(1);
+ Some(latest_tick)
+ }
+
+ fn next_deadline(&self) -> Duration {
+ self.next_sequence.map_or(Duration::MAX, |sequence| {
+ self.interval.saturating_mul(sequence)
+ })
+ }
+}
+
+#[derive(Debug)]
+struct TimingConfig {
+ interval: Duration,
+ run_duration: Duration,
+}
+
+fn validate_timing(fps: u32, duration_seconds: f64) -> Result {
+ ensure!(fps > 0, "--fps must be greater than zero");
+ ensure!(
+ duration_seconds.is_finite() && duration_seconds > 0.0,
+ "--duration must be a finite positive number"
+ );
+
+ let interval = Duration::try_from_secs_f64(1.0 / f64::from(fps))
+ .context("--fps cannot be represented as a frame interval")?;
+ ensure!(!interval.is_zero(), "--fps is too large");
+ let run_duration = Duration::try_from_secs_f64(duration_seconds)
+ .context("--duration is too large to represent")?;
+
+ // The loop emits only while elapsed < run_duration. At nanosecond
+ // resolution, this is the largest tick that can become due.
+ let maximum_due_tick = run_duration.as_nanos().saturating_sub(1) / interval.as_nanos();
+ ensure!(
+ maximum_due_tick <= u128::from(u32::MAX),
+ "--fps and --duration can exceed the u32 frame sequence capacity"
+ );
+
+ Ok(TimingConfig {
+ interval,
+ run_duration,
+ })
+}
+
+fn generate_frame(width: u32, height: u32, sequence: u32) -> Result> {
+ let len = width
+ .checked_mul(height)
+ .and_then(|pixels| pixels.checked_mul(4))
+ .and_then(|bytes| usize::try_from(bytes).ok())
+ .context("frame dimensions overflow")?;
+ let mut rgba = vec![0; len];
+ let square_size = (width.min(height) / 5).max(1);
+ let travel = width.saturating_sub(square_size).saturating_add(1);
+ let square_x = sequence.wrapping_mul(6) % travel;
+ let square_y = height.saturating_sub(square_size) / 2;
+
+ for y in 0..height {
+ for x in 0..width {
+ let offset = usize::try_from((y * width + x) * 4).expect("validated frame fits usize");
+ rgba[offset] = ((u64::from(x) * 255) / u64::from(width)) as u8;
+ rgba[offset + 1] = ((u64::from(y) * 255) / u64::from(height)) as u8;
+ rgba[offset + 2] = sequence.wrapping_mul(3) as u8;
+ rgba[offset + 3] = 255;
+
+ if x >= square_x
+ && x < square_x + square_size
+ && y >= square_y
+ && y < square_y + square_size
+ {
+ rgba[offset..offset + 4].copy_from_slice(&[255, 240, 32, 255]);
+ }
+ }
+ }
+
+ Ok(rgba)
+}
+
+fn encode_png(width: u32, height: u32, rgba: &[u8]) -> Result> {
+ let mut png = Vec::new();
+ image::codecs::png::PngEncoder::new(&mut png)
+ .write_image(rgba, width, height, image::ExtendedColorType::Rgba8)
+ .context("failed to encode initial PNG")?;
+ Ok(png)
+}
+
+trait TerminalBackend {
+ fn enable_raw(&mut self) -> io::Result<()>;
+ fn enter_alternate(&mut self) -> io::Result<()>;
+ fn hide_cursor(&mut self) -> io::Result<()>;
+ fn prepare_screen(&mut self) -> io::Result<()>;
+ fn show_cursor(&mut self) -> io::Result<()>;
+ fn leave_alternate(&mut self) -> io::Result<()>;
+ fn disable_raw(&mut self) -> io::Result<()>;
+}
+
+#[derive(Default)]
+struct TerminalSetupState {
+ raw_enabled: bool,
+ alternate_entered: bool,
+ cursor_hidden: bool,
+}
+
+fn setup_terminal(backend: &mut impl TerminalBackend) -> io::Result {
+ let mut state = TerminalSetupState {
+ raw_enabled: true,
+ ..TerminalSetupState::default()
+ };
+ if let Err(error) = backend.enable_raw() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ state.alternate_entered = true;
+ if let Err(error) = backend.enter_alternate() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ state.cursor_hidden = true;
+ if let Err(error) = backend.hide_cursor() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ if let Err(error) = backend.prepare_screen() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ Ok(state)
+}
+
+fn restore_terminal(backend: &mut impl TerminalBackend, state: &mut TerminalSetupState) {
+ if std::mem::take(&mut state.cursor_hidden) {
+ let _ = backend.show_cursor();
+ }
+ if std::mem::take(&mut state.alternate_entered) {
+ let _ = backend.leave_alternate();
+ }
+ if std::mem::take(&mut state.raw_enabled) {
+ let _ = backend.disable_raw();
+ }
+}
+
+struct CrosstermBackend {
+ stdout: Stdout,
+}
+
+impl TerminalBackend for CrosstermBackend {
+ fn enable_raw(&mut self) -> io::Result<()> {
+ enable_raw_mode()
+ }
+
+ fn enter_alternate(&mut self) -> io::Result<()> {
+ execute!(self.stdout, EnterAlternateScreen)
+ }
+
+ fn hide_cursor(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Hide)
+ }
+
+ fn prepare_screen(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Clear(ClearType::All), MoveTo(0, 0))
+ }
+
+ fn show_cursor(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Show)
+ }
+
+ fn leave_alternate(&mut self) -> io::Result<()> {
+ execute!(self.stdout, LeaveAlternateScreen)
+ }
+
+ fn disable_raw(&mut self) -> io::Result<()> {
+ disable_raw_mode()
+ }
+}
+
+struct TerminalSession {
+ backend: CrosstermBackend,
+ setup: TerminalSetupState,
+ bitmap_id: u32,
+ placement_id: u32,
+}
+
+impl TerminalSession {
+ fn enter(bitmap_id: u32, placement_id: u32) -> io::Result {
+ let mut backend = CrosstermBackend {
+ stdout: io::stdout(),
+ };
+ let setup = setup_terminal(&mut backend)?;
+ Ok(Self {
+ backend,
+ setup,
+ bitmap_id,
+ placement_id,
+ })
+ }
+
+ fn write_commands(&mut self, commands: I) -> io::Result<()>
+ where
+ I: IntoIterator- >,
+ {
+ for command in commands {
+ self.backend.stdout.write_all(&command)?;
+ }
+ self.backend.stdout.flush()
+ }
+
+ fn draw_status(&mut self, sequence: u32, fps: u32) -> io::Result<()> {
+ queue!(
+ self.backend.stdout,
+ MoveTo(0, 0),
+ Clear(ClearType::CurrentLine),
+ Print(format!(
+ "Ratty RGBA8 bitmap stream | target {fps} FPS | sequence {sequence}"
+ ))
+ )?;
+ self.backend.stdout.flush()
+ }
+}
+
+impl Drop for TerminalSession {
+ fn drop(&mut self) {
+ for command in encode_deletion(self.bitmap_id, self.placement_id) {
+ let _ = self.backend.stdout.write_all(&command);
+ }
+ let _ = self.backend.stdout.flush();
+ restore_terminal(&mut self.backend, &mut self.setup);
+ }
+}
+
+fn main() -> Result<()> {
+ let args = Args::parse();
+ ensure!(
+ args.width > 0 && args.height > 0,
+ "--width and --height must be greater than zero"
+ );
+
+ let timing = validate_timing(args.fps, args.duration)?;
+ let initial_rgba = generate_frame(args.width, args.height, 0)?;
+ let png = encode_png(args.width, args.height, &initial_rgba)?;
+ let encoded_png = base64::engine::general_purpose::STANDARD.encode(png);
+
+ let mut terminal =
+ TerminalSession::enter(BITMAP_ID, PLACEMENT_ID).context("failed to enter terminal mode")?;
+ terminal.write_commands(encode_registration(BITMAP_ID, &encoded_png))?;
+ let (columns, rows) = terminal::size().context("failed to read terminal size")?;
+ terminal.write_commands([encode_placement(
+ BITMAP_ID,
+ PLACEMENT_ID,
+ 1,
+ 0,
+ u32::from(columns.max(1)),
+ u32::from(rows.saturating_sub(1).max(1)),
+ )])?;
+ terminal.draw_status(0, args.fps)?;
+
+ let started = Instant::now();
+ let mut scheduler = LatestFrameScheduler::new(timing.interval);
+ loop {
+ let elapsed = started.elapsed();
+ if elapsed >= timing.run_duration {
+ break;
+ }
+
+ if let Some(sequence) = scheduler.due_sequence(elapsed) {
+ let rgba = generate_frame(args.width, args.height, sequence)?;
+ terminal.write_commands(encode_frame(
+ BITMAP_ID,
+ sequence,
+ args.width,
+ args.height,
+ &rgba,
+ )?)?;
+ terminal.draw_status(sequence, args.fps)?;
+ continue;
+ }
+
+ let wait = scheduler
+ .next_deadline()
+ .saturating_sub(elapsed)
+ .min(timing.run_duration.saturating_sub(elapsed));
+ thread::sleep(wait);
+ }
+
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const APC_END: &str = "\u{1b}\\";
+
+ fn command_text(commands: &[Vec]) -> Vec<&str> {
+ commands
+ .iter()
+ .map(|command| {
+ std::str::from_utf8(command).expect("valid example test input should succeed")
+ })
+ .collect()
+ }
+
+ fn payload(command: &str) -> &str {
+ command
+ .strip_suffix(APC_END)
+ .expect("valid example test input should succeed")
+ .rsplit_once(';')
+ .expect("valid example test input should succeed")
+ .1
+ }
+
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+ enum TerminalAction {
+ EnableRaw,
+ EnterAlternate,
+ HideCursor,
+ PrepareScreen,
+ ShowCursor,
+ LeaveAlternate,
+ DisableRaw,
+ }
+
+ struct MockTerminalBackend {
+ fail_at: TerminalAction,
+ actions: Vec,
+ }
+
+ impl MockTerminalBackend {
+ fn new(fail_at: TerminalAction) -> Self {
+ Self {
+ fail_at,
+ actions: Vec::new(),
+ }
+ }
+
+ fn record(&mut self, action: TerminalAction) -> io::Result<()> {
+ self.actions.push(action);
+ if action == self.fail_at {
+ Err(io::Error::other("injected terminal failure"))
+ } else {
+ Ok(())
+ }
+ }
+ }
+
+ impl TerminalBackend for MockTerminalBackend {
+ fn enable_raw(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::EnableRaw)
+ }
+
+ fn enter_alternate(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::EnterAlternate)
+ }
+
+ fn hide_cursor(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::HideCursor)
+ }
+
+ fn prepare_screen(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::PrepareScreen)
+ }
+
+ fn show_cursor(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::ShowCursor)
+ }
+
+ fn leave_alternate(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::LeaveAlternate)
+ }
+
+ fn disable_raw(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::DisableRaw)
+ }
+ }
+
+ #[test]
+ fn partial_terminal_setup_attempts_reverse_cleanup() {
+ let mut backend = MockTerminalBackend::new(TerminalAction::HideCursor);
+
+ assert!(setup_terminal(&mut backend).is_err());
+
+ assert_eq!(
+ backend.actions,
+ vec![
+ TerminalAction::EnableRaw,
+ TerminalAction::EnterAlternate,
+ TerminalAction::HideCursor,
+ TerminalAction::ShowCursor,
+ TerminalAction::LeaveAlternate,
+ TerminalAction::DisableRaw,
+ ]
+ );
+ }
+
+ #[test]
+ fn lifecycle_registers_and_places_once_then_sends_monotonic_rgba_frames_and_deletes() {
+ let mut commands = encode_registration(BITMAP_ID, &"A".repeat(4100));
+ commands.push(encode_placement(BITMAP_ID, PLACEMENT_ID, 2, 1, 80, 24));
+ commands.extend(
+ encode_frame(BITMAP_ID, 1, 2, 2, &[0; 16])
+ .expect("valid example test input should succeed"),
+ );
+ commands.extend(
+ encode_frame(BITMAP_ID, 3, 2, 2, &[1; 16])
+ .expect("valid example test input should succeed"),
+ );
+ commands.extend(encode_deletion(BITMAP_ID, PLACEMENT_ID));
+
+ let commands = command_text(&commands);
+ assert_eq!(
+ commands
+ .iter()
+ .filter(|command| command.contains(";r;id=") && command.contains("fmt=png"))
+ .count(),
+ 1
+ );
+ assert_eq!(
+ commands
+ .iter()
+ .filter(|command| command.contains(";p;"))
+ .count(),
+ 1
+ );
+ assert_eq!(
+ commands
+ .iter()
+ .filter(|command| command.contains(";f;") && command.contains("fmt=rgba8"))
+ .map(|command| *command)
+ .collect::>(),
+ vec![
+ "\u{1b}_ratty;i;f;id=42;seq=1;fmt=rgba8;w=2;h=2;more=0;AAAAAAAAAAAAAAAAAAAAAA==\u{1b}\\",
+ "\u{1b}_ratty;i;f;id=42;seq=3;fmt=rgba8;w=2;h=2;more=0;AQEBAQEBAQEBAQEBAQEBAQ==\u{1b}\\",
+ ]
+ );
+ assert!(commands[commands.len() - 2].contains(";d;pid=7"));
+ assert!(commands[commands.len() - 1].contains(";d;id=42"));
+ }
+
+ #[test]
+ fn frame_chunks_base64_on_aligned_4096_character_boundaries() {
+ let rgba = vec![7; 3_075];
+
+ let chunks = encode_frame(BITMAP_ID, 9, 1, 3_075 / 4, &rgba)
+ .expect_err("invalid example test input should be rejected");
+ assert!(chunks.to_string().contains("length"));
+
+ let rgba = vec![7; 4_096 * 3 / 4 + 4];
+ let chunks = encode_frame(BITMAP_ID, 9, 1, rgba.len() as u32 / 4, &rgba)
+ .expect("valid example test input should succeed");
+ assert_eq!(chunks.len(), 2);
+ for (index, command) in command_text(&chunks).iter().enumerate() {
+ assert!(payload(command).len() <= 4096);
+ assert_eq!(payload(command).len() % 4, 0);
+ assert_eq!(command.contains("fmt=rgba8;w=1;h=769"), index == 0);
+ assert_eq!(command.contains("more=0"), index == 1);
+ if index == 1 {
+ assert!(command.starts_with("\u{1b}_ratty;i;f;id=42;seq=9;more=0;"));
+ }
+ }
+ }
+
+ #[test]
+ fn scheduler_skips_obsolete_ticks_instead_of_bursting() {
+ let mut scheduler = LatestFrameScheduler::new(std::time::Duration::from_millis(100));
+
+ assert_eq!(
+ scheduler.due_sequence(std::time::Duration::from_millis(99)),
+ None
+ );
+ assert_eq!(
+ scheduler.due_sequence(std::time::Duration::from_millis(100)),
+ Some(1)
+ );
+ assert_eq!(
+ scheduler.due_sequence(std::time::Duration::from_millis(450)),
+ Some(4)
+ );
+ assert_eq!(
+ scheduler.due_sequence(std::time::Duration::from_millis(451)),
+ None
+ );
+ assert_eq!(
+ scheduler.next_deadline(),
+ std::time::Duration::from_millis(500)
+ );
+ }
+
+ #[test]
+ fn timing_validation_rejects_duration_conversion_overflow() {
+ let error =
+ validate_timing(15, 1e300).expect_err("invalid example test input should be rejected");
+
+ assert!(error.to_string().contains("--duration"));
+ }
+
+ #[test]
+ fn timing_validation_rejects_sequence_capacity_overflow_and_accepts_boundary() {
+ let overflow = f64::from(u32::MAX) + 2.0;
+ let boundary = f64::from(u32::MAX) + 1.0;
+
+ assert!(validate_timing(1, overflow).is_err());
+ assert!(validate_timing(1, boundary).is_ok());
+ }
+
+ #[test]
+ fn scheduler_emits_u32_max_at_most_once() {
+ let mut scheduler = LatestFrameScheduler::new(std::time::Duration::from_nanos(1));
+ let saturated = std::time::Duration::from_nanos(u64::from(u32::MAX));
+
+ assert_eq!(scheduler.due_sequence(saturated), Some(u32::MAX));
+ assert_eq!(
+ scheduler.due_sequence(saturated.saturating_add(std::time::Duration::from_secs(1))),
+ None
+ );
+ assert_eq!(scheduler.next_deadline(), std::time::Duration::MAX);
+ }
+}
diff --git a/examples/bitmap_pan_zoom.rs b/examples/bitmap_pan_zoom.rs
new file mode 100644
index 0000000..53c7a28
--- /dev/null
+++ b/examples/bitmap_pan_zoom.rs
@@ -0,0 +1,650 @@
+use std::{
+ env, fs,
+ io::{self, Stdout, Write},
+};
+
+use anyhow::{Context, Result};
+use base64::Engine as _;
+use image::GenericImageView as _;
+use ratatui::crossterm::{
+ cursor::{Hide, MoveTo, Show},
+ event::{self, Event, KeyCode},
+ execute, queue,
+ style::Print,
+ terminal::{
+ self, Clear, ClearType, EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode,
+ enable_raw_mode,
+ },
+};
+
+const BITMAP_ID: u32 = 42;
+const PLACEMENT_ID: u32 = 7;
+const MAX_BASE64_CHUNK: usize = 4096;
+const APC_PREFIX: &str = "\u{1b}_ratty;i;";
+const APC_END: &str = "\u{1b}\\";
+
+#[derive(Clone, Copy)]
+struct Destination {
+ row: u16,
+ col: u16,
+ columns: u32,
+ rows: u32,
+}
+
+impl Destination {
+ const fn new(row: u16, col: u16, columns: u32, rows: u32) -> Self {
+ Self {
+ row,
+ col,
+ columns,
+ rows,
+ }
+ }
+}
+
+#[derive(Clone, Copy, Debug)]
+enum Fit {
+ Contain,
+ Cover,
+ Fill,
+}
+
+impl Fit {
+ const fn protocol_value(self) -> &'static str {
+ match self {
+ Self::Contain => "contain",
+ Self::Cover => "cover",
+ Self::Fill => "fill",
+ }
+ }
+}
+
+#[derive(Clone, Copy, Debug)]
+enum Filter {
+ Nearest,
+ Linear,
+}
+
+impl Filter {
+ const fn protocol_value(self) -> &'static str {
+ match self {
+ Self::Nearest => "nearest",
+ Self::Linear => "linear",
+ }
+ }
+}
+
+#[derive(Clone, Copy)]
+enum Zoom {
+ In,
+ Out,
+}
+
+#[derive(Clone, Copy)]
+struct ViewState {
+ bitmap_width: u32,
+ bitmap_height: u32,
+ x: u32,
+ y: u32,
+ width: u32,
+ height: u32,
+ fit: Fit,
+ filter: Filter,
+ opacity: f32,
+}
+
+impl ViewState {
+ fn new(bitmap_width: u32, bitmap_height: u32) -> Self {
+ Self {
+ bitmap_width,
+ bitmap_height,
+ x: 0,
+ y: 0,
+ width: bitmap_width,
+ height: bitmap_height,
+ fit: Fit::Contain,
+ filter: Filter::Linear,
+ opacity: 1.0,
+ }
+ }
+
+ fn pan(&mut self, horizontal: i64, vertical: i64) {
+ self.x = offset_clamped(
+ self.x,
+ horizontal,
+ self.bitmap_width.saturating_sub(self.width),
+ );
+ self.y = offset_clamped(
+ self.y,
+ vertical,
+ self.bitmap_height.saturating_sub(self.height),
+ );
+ }
+
+ fn zoom(&mut self, direction: Zoom) {
+ let (new_width, new_height) = match direction {
+ Zoom::In => ((self.width / 2).max(1), (self.height / 2).max(1)),
+ Zoom::Out => (
+ self.width.saturating_mul(2).min(self.bitmap_width),
+ self.height.saturating_mul(2).min(self.bitmap_height),
+ ),
+ };
+ let center_x = self.x.saturating_add(self.width / 2);
+ let center_y = self.y.saturating_add(self.height / 2);
+ self.width = new_width;
+ self.height = new_height;
+ self.x = center_x
+ .saturating_sub(new_width / 2)
+ .min(self.bitmap_width.saturating_sub(new_width));
+ self.y = center_y
+ .saturating_sub(new_height / 2)
+ .min(self.bitmap_height.saturating_sub(new_height));
+ }
+
+ fn cycle_fit(&mut self) {
+ self.fit = match self.fit {
+ Fit::Contain => Fit::Cover,
+ Fit::Cover => Fit::Fill,
+ Fit::Fill => Fit::Contain,
+ };
+ }
+}
+
+fn offset_clamped(current: u32, delta: i64, maximum: u32) -> u32 {
+ let next = i64::from(current).saturating_add(delta);
+ next.clamp(0, i64::from(maximum)) as u32
+}
+
+fn encode_registration(bitmap_id: u32, encoded_png: &str) -> Vec> {
+ debug_assert_eq!(MAX_BASE64_CHUNK % 4, 0);
+ let chunks: Vec<_> = encoded_png.as_bytes().chunks(MAX_BASE64_CHUNK).collect();
+ let last = chunks.len().saturating_sub(1);
+
+ chunks
+ .into_iter()
+ .enumerate()
+ .map(|(index, payload)| {
+ let payload = std::str::from_utf8(payload).expect("base64 is ASCII");
+ let more = u8::from(index != last);
+ if index == 0 {
+ encode_command(format!(
+ "r;id={bitmap_id};fmt=png;source=payload;more={more};{payload}"
+ ))
+ } else {
+ encode_command(format!("r;id={bitmap_id};more={more};{payload}"))
+ }
+ })
+ .collect()
+}
+
+fn encode_placement(bitmap_id: u32, placement_id: u32, destination: Destination) -> Vec {
+ // row/col are visible coordinates now; Ratty attaches the resulting
+ // placement to this alternate-screen content for later scroll/reflow.
+ encode_command(format!(
+ "p;id={bitmap_id};pid={placement_id};row={};col={};w={};h={};fit=contain;filter=linear;opacity=1",
+ destination.row, destination.col, destination.columns, destination.rows
+ ))
+}
+
+fn encode_update(placement_id: u32, view: ViewState) -> Vec {
+ encode_command(format!(
+ "u;pid={placement_id};src_x={};src_y={};src_w={};src_h={};fit={};filter={};opacity={:.3}",
+ view.x,
+ view.y,
+ view.width,
+ view.height,
+ view.fit.protocol_value(),
+ view.filter.protocol_value(),
+ view.opacity
+ ))
+}
+
+fn encode_deletion(bitmap_id: u32, placement_id: u32) -> [Vec; 2] {
+ [
+ encode_command(format!("d;pid={placement_id}")),
+ encode_command(format!("d;id={bitmap_id}")),
+ ]
+}
+
+fn encode_command(body: String) -> Vec {
+ format!("{APC_PREFIX}{body}{APC_END}").into_bytes()
+}
+
+trait TerminalBackend {
+ fn enable_raw(&mut self) -> io::Result<()>;
+ fn enter_alternate(&mut self) -> io::Result<()>;
+ fn hide_cursor(&mut self) -> io::Result<()>;
+ fn prepare_screen(&mut self) -> io::Result<()>;
+ fn show_cursor(&mut self) -> io::Result<()>;
+ fn leave_alternate(&mut self) -> io::Result<()>;
+ fn disable_raw(&mut self) -> io::Result<()>;
+}
+
+#[derive(Default)]
+struct TerminalSetupState {
+ raw_enabled: bool,
+ alternate_entered: bool,
+ cursor_hidden: bool,
+}
+
+fn setup_terminal(backend: &mut impl TerminalBackend) -> io::Result {
+ let mut state = TerminalSetupState {
+ raw_enabled: true,
+ ..TerminalSetupState::default()
+ };
+ if let Err(error) = backend.enable_raw() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ state.alternate_entered = true;
+ if let Err(error) = backend.enter_alternate() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ state.cursor_hidden = true;
+ if let Err(error) = backend.hide_cursor() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ if let Err(error) = backend.prepare_screen() {
+ restore_terminal(backend, &mut state);
+ return Err(error);
+ }
+
+ Ok(state)
+}
+
+fn restore_terminal(backend: &mut impl TerminalBackend, state: &mut TerminalSetupState) {
+ if std::mem::take(&mut state.cursor_hidden) {
+ let _ = backend.show_cursor();
+ }
+ if std::mem::take(&mut state.alternate_entered) {
+ let _ = backend.leave_alternate();
+ }
+ if std::mem::take(&mut state.raw_enabled) {
+ let _ = backend.disable_raw();
+ }
+}
+
+struct CrosstermBackend {
+ stdout: Stdout,
+}
+
+impl TerminalBackend for CrosstermBackend {
+ fn enable_raw(&mut self) -> io::Result<()> {
+ enable_raw_mode()
+ }
+
+ fn enter_alternate(&mut self) -> io::Result<()> {
+ execute!(self.stdout, EnterAlternateScreen)
+ }
+
+ fn hide_cursor(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Hide)
+ }
+
+ fn prepare_screen(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Clear(ClearType::All), MoveTo(0, 0))
+ }
+
+ fn show_cursor(&mut self) -> io::Result<()> {
+ execute!(self.stdout, Show)
+ }
+
+ fn leave_alternate(&mut self) -> io::Result<()> {
+ execute!(self.stdout, LeaveAlternateScreen)
+ }
+
+ fn disable_raw(&mut self) -> io::Result<()> {
+ disable_raw_mode()
+ }
+}
+
+struct TerminalSession {
+ backend: CrosstermBackend,
+ setup: TerminalSetupState,
+ bitmap_id: u32,
+ placement_id: u32,
+}
+
+impl TerminalSession {
+ fn enter(bitmap_id: u32, placement_id: u32) -> io::Result {
+ let mut backend = CrosstermBackend {
+ stdout: io::stdout(),
+ };
+ let setup = setup_terminal(&mut backend)?;
+ Ok(Self {
+ backend,
+ setup,
+ bitmap_id,
+ placement_id,
+ })
+ }
+
+ fn write_commands(&mut self, commands: I) -> io::Result<()>
+ where
+ I: IntoIterator
- >,
+ {
+ for command in commands {
+ self.backend.stdout.write_all(&command)?;
+ }
+ self.backend.stdout.flush()
+ }
+
+ fn draw_help(&mut self, view: ViewState) -> io::Result<()> {
+ queue!(
+ self.backend.stdout,
+ MoveTo(0, 0),
+ Clear(ClearType::CurrentLine),
+ Print("arrows pan | +/- zoom | f fit | n/l filter | [/] opacity | q quit"),
+ MoveTo(0, 1),
+ Clear(ClearType::CurrentLine),
+ Print(format!(
+ "crop {}x{}+{},{} | fit {} | filter {} | opacity {:.1}",
+ view.width,
+ view.height,
+ view.x,
+ view.y,
+ view.fit.protocol_value(),
+ view.filter.protocol_value(),
+ view.opacity
+ ))
+ )?;
+ self.backend.stdout.flush()
+ }
+}
+
+impl Drop for TerminalSession {
+ fn drop(&mut self) {
+ for command in encode_deletion(self.bitmap_id, self.placement_id) {
+ let _ = self.backend.stdout.write_all(&command);
+ }
+ let _ = self.backend.stdout.flush();
+ restore_terminal(&mut self.backend, &mut self.setup);
+ }
+}
+
+fn main() -> Result<()> {
+ let path = env::args_os()
+ .nth(1)
+ .context("usage: cargo run --example bitmap_pan_zoom -- ")?;
+ let png = fs::read(&path)
+ .with_context(|| format!("failed to read PNG from {}", path.to_string_lossy()))?;
+ let image = image::load_from_memory_with_format(&png, image::ImageFormat::Png)
+ .context("input is not a valid PNG")?;
+ let (bitmap_width, bitmap_height) = image.dimensions();
+ drop(image);
+ let encoded_png = base64::engine::general_purpose::STANDARD.encode(&png);
+
+ let mut terminal = TerminalSession::enter(BITMAP_ID, PLACEMENT_ID)
+ .context("failed to enter interactive terminal mode")?;
+ let mut view = ViewState::new(bitmap_width, bitmap_height);
+ terminal.draw_help(view)?;
+ terminal.write_commands(encode_registration(BITMAP_ID, &encoded_png))?;
+ let (columns, rows) = terminal::size().context("failed to read terminal size")?;
+ terminal.write_commands([encode_placement(
+ BITMAP_ID,
+ PLACEMENT_ID,
+ Destination::new(
+ 2,
+ 1,
+ u32::from(columns.saturating_sub(2).max(1)),
+ u32::from(rows.saturating_sub(3).max(1)),
+ ),
+ )])?;
+
+ loop {
+ let Event::Key(key) = event::read().context("failed to read terminal input")? else {
+ continue;
+ };
+ if !key.is_press() {
+ continue;
+ }
+
+ let pan_x = i64::from((view.width / 20).max(1));
+ let pan_y = i64::from((view.height / 20).max(1));
+ let changed = match key.code {
+ KeyCode::Char('q') => break,
+ KeyCode::Left => {
+ view.pan(-pan_x, 0);
+ true
+ }
+ KeyCode::Right => {
+ view.pan(pan_x, 0);
+ true
+ }
+ KeyCode::Up => {
+ view.pan(0, -pan_y);
+ true
+ }
+ KeyCode::Down => {
+ view.pan(0, pan_y);
+ true
+ }
+ KeyCode::Char('+') | KeyCode::Char('=') => {
+ view.zoom(Zoom::In);
+ true
+ }
+ KeyCode::Char('-') => {
+ view.zoom(Zoom::Out);
+ true
+ }
+ KeyCode::Char('f') => {
+ view.cycle_fit();
+ true
+ }
+ KeyCode::Char('n') => {
+ view.filter = Filter::Nearest;
+ true
+ }
+ KeyCode::Char('l') => {
+ view.filter = Filter::Linear;
+ true
+ }
+ KeyCode::Char('[') => {
+ view.opacity = (view.opacity - 0.1).max(0.0);
+ true
+ }
+ KeyCode::Char(']') => {
+ view.opacity = (view.opacity + 0.1).min(1.0);
+ true
+ }
+ _ => false,
+ };
+
+ if changed {
+ terminal.write_commands([encode_update(PLACEMENT_ID, view)])?;
+ terminal.draw_help(view)?;
+ }
+ }
+
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const APC_END: &str = "\u{1b}\\";
+
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+ enum TerminalAction {
+ EnableRaw,
+ EnterAlternate,
+ HideCursor,
+ PrepareScreen,
+ ShowCursor,
+ LeaveAlternate,
+ DisableRaw,
+ }
+
+ struct MockTerminalBackend {
+ fail_at: TerminalAction,
+ actions: Vec,
+ }
+
+ impl MockTerminalBackend {
+ fn new(fail_at: TerminalAction) -> Self {
+ Self {
+ fail_at,
+ actions: Vec::new(),
+ }
+ }
+
+ fn record(&mut self, action: TerminalAction) -> io::Result<()> {
+ self.actions.push(action);
+ if action == self.fail_at {
+ Err(io::Error::other("injected terminal failure"))
+ } else {
+ Ok(())
+ }
+ }
+ }
+
+ impl TerminalBackend for MockTerminalBackend {
+ fn enable_raw(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::EnableRaw)
+ }
+
+ fn enter_alternate(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::EnterAlternate)
+ }
+
+ fn hide_cursor(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::HideCursor)
+ }
+
+ fn prepare_screen(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::PrepareScreen)
+ }
+
+ fn show_cursor(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::ShowCursor)
+ }
+
+ fn leave_alternate(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::LeaveAlternate)
+ }
+
+ fn disable_raw(&mut self) -> io::Result<()> {
+ self.record(TerminalAction::DisableRaw)
+ }
+ }
+
+ #[test]
+ fn enter_alternate_mutation_followed_by_error_still_attempts_reverse_cleanup() {
+ let mut backend = MockTerminalBackend::new(TerminalAction::EnterAlternate);
+
+ assert!(setup_terminal(&mut backend).is_err());
+
+ assert_eq!(
+ backend.actions,
+ vec![
+ TerminalAction::EnableRaw,
+ TerminalAction::EnterAlternate,
+ TerminalAction::LeaveAlternate,
+ TerminalAction::DisableRaw,
+ ]
+ );
+ }
+
+ #[test]
+ fn hide_cursor_mutation_followed_by_error_still_attempts_reverse_cleanup() {
+ let mut backend = MockTerminalBackend::new(TerminalAction::HideCursor);
+
+ assert!(setup_terminal(&mut backend).is_err());
+
+ assert_eq!(
+ backend.actions,
+ vec![
+ TerminalAction::EnableRaw,
+ TerminalAction::EnterAlternate,
+ TerminalAction::HideCursor,
+ TerminalAction::ShowCursor,
+ TerminalAction::LeaveAlternate,
+ TerminalAction::DisableRaw,
+ ]
+ );
+ }
+
+ #[test]
+ fn registration_chunks_base64_on_aligned_4096_character_boundaries() {
+ let encoded = "A".repeat(4096 * 2 + 8);
+
+ let chunks = encode_registration(BITMAP_ID, &encoded);
+
+ assert_eq!(chunks.len(), 3);
+ for (index, chunk) in chunks.iter().enumerate() {
+ let command =
+ std::str::from_utf8(chunk).expect("valid example test input should succeed");
+ let payload = command
+ .strip_suffix(APC_END)
+ .expect("valid example test input should succeed")
+ .rsplit_once(';')
+ .expect("valid example test input should succeed")
+ .1;
+ assert!(payload.len() <= 4096);
+ assert_eq!(payload.len() % 4, 0);
+ assert_eq!(command.contains("fmt=png;source=payload"), index == 0);
+ assert_eq!(command.contains("more=0"), index == 2);
+ }
+ }
+
+ #[test]
+ fn lifecycle_registers_and_places_once_then_only_updates_before_deletion() {
+ let mut commands = encode_registration(BITMAP_ID, "QUJDRA==");
+ commands.push(encode_placement(
+ BITMAP_ID,
+ PLACEMENT_ID,
+ Destination::new(2, 1, 80, 24),
+ ));
+ let mut view = ViewState::new(640, 480);
+ view.zoom(Zoom::In);
+ commands.push(encode_update(PLACEMENT_ID, view));
+ view.pan(16, 8);
+ commands.push(encode_update(PLACEMENT_ID, view));
+ view.cycle_fit();
+ commands.push(encode_update(PLACEMENT_ID, view));
+ view.filter = Filter::Nearest;
+ commands.push(encode_update(PLACEMENT_ID, view));
+ view.opacity = 0.5;
+ commands.push(encode_update(PLACEMENT_ID, view));
+ commands.extend(encode_deletion(BITMAP_ID, PLACEMENT_ID));
+
+ let commands: Vec<_> = commands
+ .iter()
+ .map(|command| {
+ std::str::from_utf8(command).expect("valid example test input should succeed")
+ })
+ .collect();
+ assert_eq!(
+ commands
+ .iter()
+ .filter(|command| command.contains(";r;id=") && command.contains("fmt=png"))
+ .count(),
+ 1
+ );
+ assert_eq!(
+ commands
+ .iter()
+ .filter(|command| command.contains(";p;"))
+ .count(),
+ 1
+ );
+ assert!(
+ commands[2..commands.len() - 2]
+ .iter()
+ .all(|command| command.contains(";u;pid="))
+ );
+ assert!(commands[2].contains("src_w=320;src_h=240"));
+ assert!(commands[3].contains("src_x=176;src_y=128"));
+ assert!(commands[4].contains("fit=cover"));
+ assert!(commands[5].contains("filter=nearest"));
+ assert!(commands[6].contains("opacity=0.500"));
+ assert!(commands[7].contains(";d;pid=7"));
+ assert!(commands[8].contains(";d;id=42"));
+ }
+}
diff --git a/protocols/bitmap.md b/protocols/bitmap.md
new file mode 100644
index 0000000..27a4880
--- /dev/null
+++ b/protocols/bitmap.md
@@ -0,0 +1,392 @@
+# Ratty Bitmap Surface Protocol
+
+Ratty Bitmap Surface is a terminal protocol for registering 2D bitmap assets,
+placing them in terminal cell space, changing placement and crop properties
+without re-uploading pixels, and replacing live pixels without changing the
+bitmap identity.
+
+Version 1 uses the `ratty;i` APC namespace. It supports PNG registration and
+full-frame RGBA8 replacement only.
+
+## Transport and framing
+
+Commands use APC (Application Program Command) framing:
+
+```text
+ESC _ ratty;i;[;...][;] ESC \
+```
+
+Both the two-byte `ESC \` string terminator and the single-byte C1 ST
+terminator are accepted. Header fields are semicolon-separated. A command with
+a payload places its base64 data after the header fields as the final
+semicolon-separated item.
+
+Each individual `r` or `f` APC chunk may decode to at most 64 MiB. Ratty
+preflights the encoded payload length before base64 decoding. The v1 encoded
+APC bound is derived as
+`len(ESC _ ratty;i;) + 4096 + 4 * ceil(64 MiB / 3) + len(ESC \)`: 4096 bytes
+are reserved for the verb, fields, and separators, and the two-byte terminator
+is the larger accepted terminator. The verb, fields, and separators may occupy
+at most those 4096 bytes. For `r` and `f`, the header extends through the final
+semicolon that separates the payload, so semicolon runs in an alleged payload
+cannot bypass the header limit. A client must split a transfer before any
+individual command reaches the complete APC bound.
+
+If an unterminated bitmap APC reaches the encoded bound, Ratty discards bytes
+through the next `ESC \` or C1 ST without retaining or displaying them, then
+resumes normal terminal parsing after the terminator. This bound applies only
+to the `ratty;i` namespace; it does not change RGP or Kitty limits.
+
+Ratty also applies configurable resource limits before PNG decoding and while
+retaining protocol state. The distributed defaults are:
+
+- maximum registered bitmaps: 1024
+- maximum active placements: 4096
+- maximum image width and height: 8192 pixels each
+- maximum decoded RGBA8 bytes per bitmap: 64 MiB
+- maximum decoded RGBA8 bytes across all registered bitmaps: 256 MiB
+- maximum decoded payload bytes across incomplete registrations and frames: 64 MiB
+- maximum concurrent incomplete registrations and frames: 16
+
+PNG decoding receives the configured dimension and allocation limits directly.
+Ratty also calculates `width * height * 4` with checked arithmetic before
+accepting a decoded bitmap. Exceeding any limit rejects the operation instead
+of evicting unrelated existing bitmaps or transfers. Registered-byte accounting
+remains active after pixel data is uploaded to the GPU and is released when the
+bitmap is deleted.
+
+Bitmap IDs, placement IDs, sequence numbers, source coordinates, and dimensions
+are unsigned decimal `u32` values on the wire. Destination `row` and `col` are
+unsigned decimal values limited to the `u16` range `0..=65535`. A bitmap ID is
+written as `id`; a placement ID is written as `pid`. Bitmap and placement IDs
+each belong to a single global namespace of their kind. Destination `w` and
+`h`, source `src_w` and `src_h`, and frame `w` and `h` must be nonzero; IDs,
+coordinates, and sequence numbers have no additional nonzero constraint.
+Opacity is a finite decimal floating-point value whose effective value is in
+`[0,1]`; finite input outside that range is clamped to the nearest endpoint.
+
+The verbs are:
+
+- `s`: query support
+- `r`: register a bitmap
+- `p`: create a placement
+- `u`: update a placement
+- `f`: replace a bitmap frame
+- `d`: delete a placement or bitmap
+
+## Support discovery
+
+A client queries support with:
+
+```text
+ESC _ ratty;i;s ESC \
+```
+
+Ratty replies with exactly:
+
+```text
+ESC _ ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1 ESC \
+```
+
+The reply advertises protocol version 1, PNG payload registration, RGBA8 frame
+replacement, chunked transfers, independently addressable placements, source
+cropping, the three fit modes, the two filter modes, and opacity. If no reply
+arrives, the client must assume that Ratty Bitmap Surface is unsupported.
+Support queries are the only version 1 commands that produce a reply.
+
+## Coordinate systems and placement model
+
+A registered bitmap owns one pixel image and one stable bitmap identity. It may
+have multiple placements, and each placement has a globally unique `pid`.
+Registration and frame replacement operate on the shared bitmap; placement and
+update commands operate on one placement.
+
+Destination `row`, `col`, `w`, and `h` are measured in terminal cells.
+`row,col` is the top-left placement anchor, `w` is the number of columns, and
+`h` is the number of rows. Source `src_x`, `src_y`, `src_w`, and `src_h` are
+measured in source pixels from the bitmap's top-left origin.
+
+When no source rectangle is specified, the full bitmap is used. A supplied
+source rectangle is clamped to the bitmap bounds. The command is rejected if
+the clamped intersection is empty. Source and destination widths and heights
+must be nonzero.
+
+### Terminal attachment and mutation rules
+
+Wire `row,col` values are interpreted as visible-cell coordinates on the
+active screen at the exact point where the placement or row update occurs in
+the PTY stream. Ratty converts that row to rio-vt's signed absolute grid space;
+the placement is then attached to terminal content rather than to a fixed
+viewport pixel. Normal terminal bytes before and after an APC in the same PTY
+read therefore affect it in wire order.
+
+Each globally unique `pid` is owned by exactly one screen at a time. A new
+placement, or an update containing `row`, attaches it to the currently active
+main or alternate screen. A `col`, span, crop, fit, filter, or opacity-only
+update retains the placement's existing screen and absolute row. Main and
+alternate placement sets are isolated: switching screens renders only the
+active set, and entering a fresh 1049 alternate screen clears old alternate
+placements without clearing main-screen placements. A placement ID is still
+global, so explicitly moving the same `pid` on the other screen transfers its
+ownership rather than duplicating it.
+
+Content-attached placements follow the grid mutation that owns their rows:
+
+- Full-screen upward scroll caused by LF, IND, or SU carries the placement into
+ retained main-screen history. It reappears when the user views that history
+ and expires only when its entire remaining row range has been evicted from
+ the history ring. Downward RI and SD move placements with their content.
+- With DECSTBM/page margins, a placement moves only when its entire current row
+ range is inside the affected scrolling region. A placement wholly outside
+ the region, or crossing either margin before the mutation, stays fixed.
+ When a moved placement crosses the top or bottom margin, the escaped rows are
+ clipped and its source-row offset advances as needed. If no rows remain, the
+ placement expires.
+- IL and DL apply the same rule to the cursor-to-bottom subregion: wholly
+ contained placements move down or up with inserted or deleted lines, while
+ outside or margin-crossing placements remain fixed. Counts are clamped to
+ the affected region; a move may clip or expire the placement completely.
+- A top-anchored partial region can grow history while rows below its bottom
+ margin remain visually fixed. rio-vt adjusts absolute row space at the grid
+ mutation boundary, so those fixed placements do not drift.
+- Resize and reflow remap a content-attached placement's top row through the
+ same row mapping as terminal text. Viewport geometry and clipping are then
+ recomputed for the new dimensions. A placement whose anchor content is
+ dropped by truncation expires.
+
+Ordinary text writes, overwrites, EL, ED, and other text erasure do not delete
+bitmap placements; bitmap placement and pixel lifetime are controlled by the
+`d` verb. Clearing retained history can nevertheless expire a placement whose
+entire row range is discarded. A full terminal reset (RIS) clears placement
+records on both screens but leaves no stale renderer entity; registered bitmap
+pixels remain available until bitmap deletion or process teardown.
+
+## Register bitmap (`r`)
+
+Registration carries a base64-encoded PNG payload. A one-chunk registration is:
+
+```text
+ESC _ ratty;i;r;id=42;fmt=png;source=payload;more=0; ESC \
+```
+
+The first chunk requires:
+
+- `id`: the bitmap ID
+- `fmt=png`: the version 1 registration format
+- `source=payload`: the version 1 registration source
+- `more`: `1` when more chunks follow or `0` on the final chunk
+- a base64 payload item
+
+`name` is optional diagnostic metadata. For a multi-chunk registration, later
+chunks use the same `id`, include `more`, and carry the next base64 payload
+item. `fmt`, `source`, and `name` may be repeated after the first chunk only
+when their values exactly match the first chunk.
+
+```text
+ESC _ ratty;i;r;id=42;fmt=png;source=payload;more=1;name=photo.png; ESC \
+ESC _ ratty;i;r;id=42;more=1; ESC \
+ESC _ ratty;i;r;id=42;more=0; ESC \
+```
+
+After the per-chunk size preflight, Ratty base64-decodes each chunk and retains
+decoded bytes while `more=1`.
+`more=0` finalizes the transfer: Ratty decodes the accumulated PNG exactly
+once, creates the bitmap, and clears the pending transfer. The bitmap becomes
+visible to placement commands only after successful finalization.
+
+A pending registration may contain at most 64 MiB of decoded payload bytes,
+subject to the configured aggregate pending-byte and transfer-count budgets. If
+a chunk would exceed a limit, Ratty rejects the chunk and discards the affected
+pending registration. An invalid PNG on finalization also clears the pending
+transfer and does not register a bitmap. Other malformed chunks make no state
+change.
+
+Registering an `id` that is already registered or would exceed the configured
+global bitmap limit is rejected and never replaces the existing bitmap or its
+placements. Deleting a registered bitmap releases its bitmap-count slot.
+
+## Place bitmap (`p`)
+
+A placement refers to an already registered bitmap and receives its own
+globally unique placement ID:
+
+```text
+ESC _ ratty;i;p;id=42;pid=7;row=4;col=2;w=80;h=30;fit=contain;filter=linear;opacity=1 ESC \
+```
+
+Required fields are `id`, `pid`, `row`, `col`, `w`, and `h`. The destination
+dimensions must be nonzero. The optional placement fields are:
+
+- the complete `src_x`, `src_y`, `src_w`, `src_h` source rectangle
+- `fit=contain|cover|fill`, default `contain`
+- `filter=nearest|linear`, default `linear`
+- `opacity`, default `1`
+
+A source rectangle, when present, must contain all four source fields. Opacity
+must be finite and is clamped to the inclusive range `[0,1]`.
+
+Placement fails without mutation when the bitmap does not exist, `pid` is
+already in use, or the configured global placement limit has been reached.
+Multiple distinct placements may share a bitmap within that limit.
+
+## Update placement (`u`)
+
+An update changes an existing placement without re-registering the bitmap or
+changing its bitmap ID:
+
+```text
+ESC _ ratty;i;u;pid=7;src_x=300;src_y=120;src_w=900;src_h=600 ESC \
+```
+
+`pid` and at least one mutable field are required. Mutable fields are:
+
+- `row` or `col`, independently
+- `w` and `h`, as a complete pair
+- `src_x`, `src_y`, `src_w`, and `src_h`, as a complete quartet
+- `fit`
+- `filter`
+- `opacity`
+
+Updated destination dimensions must be nonzero. Updated source rectangles use
+the same clamping and nonempty-intersection rules as placement. Updated opacity
+must be finite and is clamped to `[0,1]`.
+
+Updates are transactional. A partial `w/h` pair, partial source quartet,
+unknown placement, invalid value, or failed validation rejects the whole
+command and leaves the placement unchanged.
+
+When `row` is present, its new value is resolved in visible coordinates on the
+active screen and moves the placement there. Without `row`, the update retains
+the terminal-owned absolute anchor and screen even if `col`, `w`, or `h`
+changes.
+
+## Replace frame (`f`)
+
+Frame replacement changes the pixels of a registered bitmap while retaining
+its identity and every placement:
+
+```text
+ESC _ ratty;i;f;id=42;seq=123;fmt=rgba8;w=1280;h=720;more=0; ESC \
+```
+
+The first chunk requires `id`, `seq`, `fmt=rgba8`, `w`, `h`, `more`, and a
+base64 payload item. The dimensions must exactly match the registered bitmap's
+dimensions. Continuation chunks require `id`, `seq`, `more`, and the next
+payload item. If `fmt`, `w`, or `h` is repeated on a continuation, it must
+exactly match the first chunk.
+
+Chunks are assembled by `(id, seq)`. `seq` is mandatory and must increase for
+each bitmap. When a newer sequence begins, Ratty discards any incomplete older
+sequence for that bitmap. A stale sequence never replaces displayed pixels.
+
+Ratty calculates the expected byte length as `w * h * 4` using checked
+arithmetic. Arithmetic overflow rejects the frame. If accumulated decoded data
+ever exceeds that expected length, Ratty immediately rejects the chunk and
+discards the affected pending `(id, seq)` frame instead of retaining excess
+data.
+
+On the final `more=0` chunk, the decoded payload length must equal the expected
+byte length. Pixels are tightly packed RGBA8 in row-major order from the
+top-left. After all validation succeeds, Ratty atomically replaces the pixels
+of the existing bitmap. Its bitmap ID, underlying image handle, dimensions,
+and all placements remain unchanged.
+
+Invalid base64, inconsistent continuation metadata, an oversized accumulated
+payload, or a final length mismatch discards the affected pending `(id, seq)`
+frame. Missing metadata, zero or mismatched dimensions, arithmetic overflow,
+stale sequencing, or any other malformed frame is rejected. Every frame error
+preserves the last valid displayed pixels and all placements.
+
+## Delete (`d`)
+
+Delete one placement with:
+
+```text
+ESC _ ratty;i;d;pid=7 ESC \
+```
+
+Delete one bitmap with:
+
+```text
+ESC _ ratty;i;d;id=42 ESC \
+```
+
+Exactly one of `pid` or `id` is required. A command with neither ID or both IDs
+is malformed and does not delete anything. Deleting an unknown placement or
+bitmap is an idempotent no-op. In particular, deleting an unknown bitmap ID
+does not cancel a pending registration for that ID. Bitmap deletion cascades
+only when the bitmap is already registered.
+
+Deleting a placement does not affect its bitmap or sibling placements.
+Deleting a bitmap atomically deletes all placements that refer to it.
+
+## Fit and filtering rules
+
+Fit is resolved from the selected source rectangle into the destination:
+
+- `fill`: map the full source rectangle to the full destination; aspect ratio
+ may change.
+- `contain`: preserve aspect ratio, center the image, and leave transparent
+ letterboxing in the unused destination area.
+- `cover`: preserve aspect ratio and fill the destination by applying a
+ symmetric crop to the source.
+
+`nearest` selects nearest-neighbor sampling. `linear` selects linear sampling.
+Filtering belongs to the placement, so placements that share a bitmap may use
+different filter modes.
+
+## Errors and mutation rules
+
+Ratty consumes commands in the `ratty;i` namespace even when they are
+malformed or unsupported. It logs a warning and sends no error reply. A
+malformed or unsupported command makes no state change, except that a failed or
+overflowed pending transfer is discarded as described above.
+
+Unknown verbs do nothing. Duplicate keys, unsupported values, missing required
+fields, invalid base64, and invalid numeric values are malformed. Only a valid
+support query generates output.
+
+Registration, placement, and frame state are separate. Placement changes never
+create or replace bitmap pixels. Frame changes never alter placement records.
+No version 1 operation accepts filesystem paths, compressed image formats other
+than registration PNG, dirty rectangles, codecs, or network sources.
+
+## Complete example
+
+Query support:
+
+```text
+ESC _ ratty;i;s ESC \
+ESC _ ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1 ESC \
+```
+
+Register a PNG bitmap, potentially using repeated chunks with the same ID:
+
+```text
+ESC _ ratty;i;r;id=42;fmt=png;source=payload;more=0; ESC \
+```
+
+Place it in terminal cell space:
+
+```text
+ESC _ ratty;i;p;id=42;pid=7;row=4;col=2;w=80;h=30;fit=contain;filter=linear;opacity=1 ESC \
+```
+
+Change the placement's source crop without uploading the PNG again:
+
+```text
+ESC _ ratty;i;u;pid=7;src_x=300;src_y=120;src_w=900;src_h=600 ESC \
+```
+
+Replace the bitmap's pixels with a sequenced, fixed-dimension RGBA8 frame:
+
+```text
+ESC _ ratty;i;f;id=42;seq=123;fmt=rgba8;w=1280;h=720;more=0; ESC \
+```
+
+Delete the placement and then the bitmap:
+
+```text
+ESC _ ratty;i;d;pid=7 ESC \
+ESC _ ratty;i;d;id=42 ESC \
+```
diff --git a/protocols/graphics.md b/protocols/graphics.md
index fffbcb9..bfe805a 100644
--- a/protocols/graphics.md
+++ b/protocols/graphics.md
@@ -3,6 +3,9 @@
Ratty Graphics Protocol (RGP) is a custom terminal protocol for inserting
3D objects into the terminal as first-class inline objects.
+The `ratty;g` namespace is 3D and object-oriented. The separate `ratty;i`
+namespace is 2D and bitmap/texture-oriented.
+
The goal is to attach a semantic graphics object to terminal cells,
so it becomes part of the terminal surface rather than an external overlay.
@@ -145,7 +148,7 @@ Fields:
- `more`: continuation flag
- `1`: more register chunks follow for this object id
- `0`: this is the final chunk and registration can be finalized
-- `name`: optional source name for diagnostics and temporary asset naming
+- `name`: optional source name for diagnostics
- `normalize`: optional OBJ normalization flag on the first payload chunk, defaults to `1`
The terminal accumulates chunks for the same `id` until it receives the final
@@ -155,6 +158,22 @@ normally.
Path-based and payload-based registration are additive modes of the same `r` verb.
Clients may continue using `path=...` exactly as before.
+RGP registrations share the configured bitmap safety budgets: one encoded
+source is limited by `max_bitmap_bytes`, registered object count by
+`max_bitmaps`, total retained encoded/decoded mesh bytes by
+`max_total_bitmap_bytes`, and incomplete payloads by the pending byte,
+transfer-count, and ten-second inactivity limits. Path sources are resolved to
+canonical regular files and read through the same per-object byte limit;
+devices, FIFOs, directories, and oversized files are rejected. RGP GLB is
+restricted to exactly one self-contained BIN buffer, scene, node, mesh, and
+triangle primitive with an identity node transform, explicit float POSITION
+and NORMAL attributes, and optional U16/U32 triangle indices. Materials,
+nested nodes, animations, skins, cameras, morph targets, extensions, external
+buffers, images, samplers, and textures are rejected. JSON `.gltf` is
+rejected. The GLB JSON DOM, accessors, and render copies are bounded before
+parsing; accepted geometry is synchronously decoded into Ratty-owned mesh data
+from the exact validated bytes, without a mutable runtime asset path.
+
### 3. Place Object
Places a previously registered object into terminal cell space.
@@ -183,6 +202,44 @@ Fields:
Clients that only send the original v1 fields still work unchanged.
+#### Terminal attachment and mutation rules
+
+RGP's `row,col` is a center anchor in visible cell coordinates on the active
+screen at the exact point where the `p` APC occurs. Ratty derives the
+placement's top-left cell from that center and span, then registers a signed
+absolute, content-attached placement with rio-vt. Terminal text and RGP APCs
+within one PTY read are applied strictly in wire order.
+
+An object has at most one placed instance and one owning screen. Placing the
+same object ID again transfers its placement to the active main or alternate
+screen; it does not duplicate the object. Different object IDs may remain on
+their independently owned screens. Entering a fresh 1049 alternate screen
+clears stale alternate placements while preserving main-screen placements and
+registered object assets.
+
+The terminal, not Ratty's RGP parser, mutates the anchor:
+
+- Full-screen LF/IND/SU and RI/SD move it with content. Main-screen objects can
+ enter retained scrollback, reappear during scrollback navigation, and expire
+ only after their complete remaining row range is evicted.
+- Under DECSTBM/page margins, only an object placement wholly contained in the
+ affected region moves. Outside and pre-mutation margin-crossing placements
+ stay fixed. A contained placement's terminal-owned visible/source geometry
+ is clipped when movement carries rows past a margin and expires if no rows
+ remain. Ratty preserves the original 3D transform for a partial result; exact
+ fragment clipping at an interior margin is not yet implemented, so model
+ fragments can overdraw that margin until the placement fully expires.
+- IL/DL use the same rule for their cursor-to-bottom mutation region, including
+ clipped or expired results for large counts.
+- Resize and reflow map the anchor row through rio-vt's text reflow mapping and
+ recompute visible geometry. A dropped anchor expires.
+
+Text writes, overwrites, and erase commands do not delete an RGP placement.
+The `d` verb deletes it deliberately. RIS clears placements on both screens;
+the registered asset can be placed again unless it is deleted through RGP.
+The `u` verb changes only RGP presentation style and never moves the
+terminal-owned anchor.
+
### 4. Update Object
Updates the styling or transform of a previously placed object without changing
diff --git a/src/bitmap.rs b/src/bitmap.rs
new file mode 100644
index 0000000..e0bb97a
--- /dev/null
+++ b/src/bitmap.rs
@@ -0,0 +1,2680 @@
+//! Ratty Bitmap Surface protocol parsing.
+
+use std::{
+ collections::HashMap,
+ fmt,
+ io::Cursor,
+ time::{Duration, Instant},
+};
+
+use base64::Engine as _;
+use bevy::prelude::{Handle, Image};
+
+use crate::config::BitmapConfig;
+
+/// Ratty Bitmap Surface APC prefix.
+pub const BITMAP_APC_START: &[u8] = b"\x1b_ratty;i;";
+const ST: &[u8] = b"\x1b\\";
+const C1_ST: u8 = 0x9c;
+const SUPPORT_REPLY: &[u8] = b"\x1b_ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1\x1b\\";
+pub(crate) const MAX_BITMAP_CHUNK_DECODED_BYTES: usize = 64 * 1024 * 1024;
+pub(crate) const BITMAP_APC_HEADER_ALLOWANCE: usize = 4 * 1024;
+const MAX_BITMAP_CHUNK_BASE64_BYTES: usize = MAX_BITMAP_CHUNK_DECODED_BYTES.div_ceil(3) * 4;
+pub(crate) const MAX_BITMAP_APC_BYTES: usize =
+ BITMAP_APC_START.len() + BITMAP_APC_HEADER_ALLOWANCE + MAX_BITMAP_CHUNK_BASE64_BYTES + ST.len();
+const MAX_REGISTRATION_BYTES: usize = 64 * 1024 * 1024;
+const BITMAP_INCOMPLETE_TIMEOUT: Duration = Duration::from_secs(10);
+const CHUNK_PAYLOAD_TOO_LARGE: &str = "bitmap APC chunk payload exceeds 64 MiB";
+const HEADER_TOO_LARGE: &str = "bitmap APC header exceeds 4 KiB";
+type BitmapConsumeResult = Option>), BitmapProtocolError>>;
+
+/// Returns the largest base64 representation of a decoded byte budget.
+pub(crate) fn max_base64_encoded_bytes(max_decoded_bytes: u64) -> usize {
+ usize::try_from(max_decoded_bytes)
+ .unwrap_or(usize::MAX)
+ .checked_add(2)
+ .map(|bytes| bytes / 3)
+ .and_then(|groups| groups.checked_mul(4))
+ .unwrap_or(usize::MAX)
+}
+
+/// How source pixels are fitted into a placement's destination rectangle.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BitmapFit {
+ /// Preserve aspect ratio and letterbox the unused destination area.
+ Contain,
+ /// Preserve aspect ratio and crop symmetrically to fill the destination.
+ Cover,
+ /// Stretch the source to fill the destination.
+ Fill,
+}
+
+/// Texture filtering for a bitmap placement.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BitmapFilter {
+ /// Select the nearest source pixel.
+ Nearest,
+ /// Interpolate between neighboring source pixels.
+ Linear,
+}
+
+/// A rectangle in source-pixel coordinates.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct SourceRect {
+ /// Horizontal offset from the bitmap's left edge.
+ pub x: u32,
+ /// Vertical offset from the bitmap's top edge.
+ pub y: u32,
+ /// Source width in pixels.
+ pub width: u32,
+ /// Source height in pixels.
+ pub height: u32,
+}
+
+/// One decoded chunk of a bitmap registration transfer.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BitmapRegisterChunk {
+ /// Bitmap identifier.
+ pub bitmap_id: u32,
+ /// Registration format metadata, present on the first chunk.
+ pub format: Option,
+ /// Registration source metadata, present on the first chunk.
+ pub source: Option,
+ /// Optional diagnostic payload name.
+ pub name: Option,
+ /// Whether additional chunks follow.
+ pub more: bool,
+ /// Decoded payload bytes for this chunk.
+ pub data: Vec,
+}
+
+/// A complete bitmap placement request.
+#[derive(Clone, Debug, PartialEq)]
+pub struct BitmapPlacement {
+ /// Bitmap identifier.
+ pub bitmap_id: u32,
+ /// Globally unique placement identifier.
+ pub placement_id: u32,
+ /// Destination row in terminal cells.
+ pub row: u16,
+ /// Destination column in terminal cells.
+ pub col: u16,
+ /// Destination width in terminal cells.
+ pub columns: u32,
+ /// Destination height in terminal cells.
+ pub rows: u32,
+ /// Optional source-pixel crop.
+ pub source: Option,
+ /// Fit mode.
+ pub fit: BitmapFit,
+ /// Filtering mode.
+ pub filter: BitmapFilter,
+ /// Clamped placement opacity.
+ pub opacity: f32,
+}
+
+/// Transactional changes to an existing bitmap placement.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct BitmapPlacementUpdate {
+ /// Optional destination row.
+ pub row: Option,
+ /// Optional destination column.
+ pub col: Option,
+ /// Optional destination width, paired with `rows`.
+ pub columns: Option,
+ /// Optional destination height, paired with `columns`.
+ pub rows: Option,
+ /// Optional complete source-pixel crop.
+ pub source: Option,
+ /// Optional fit mode.
+ pub fit: Option,
+ /// Optional filtering mode.
+ pub filter: Option,
+ /// Optional clamped opacity.
+ pub opacity: Option,
+}
+
+/// One decoded chunk of a sequenced RGBA8 frame transfer.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BitmapFrameChunk {
+ /// Bitmap identifier.
+ pub bitmap_id: u32,
+ /// Per-bitmap frame sequence number.
+ pub sequence: u32,
+ /// Frame format metadata, present on the first chunk.
+ pub format: Option,
+ /// Frame width metadata, present on the first chunk.
+ pub width: Option,
+ /// Frame height metadata, present on the first chunk.
+ pub height: Option,
+ /// Whether additional chunks follow.
+ pub more: bool,
+ /// Decoded RGBA8 payload bytes for this chunk.
+ pub data: Vec,
+}
+
+/// A parsed Ratty Bitmap Surface operation.
+#[derive(Clone, Debug, PartialEq)]
+pub enum BitmapOperation {
+ /// Query protocol support.
+ SupportQuery,
+ /// Register a PNG bitmap transfer chunk.
+ Register(BitmapRegisterChunk),
+ /// Create a placement.
+ Place(BitmapPlacement),
+ /// Update an existing placement.
+ Update {
+ /// Placement identifier.
+ placement_id: u32,
+ /// Fields to update transactionally.
+ update: BitmapPlacementUpdate,
+ },
+ /// Replace bitmap pixels with a frame transfer chunk.
+ Frame(BitmapFrameChunk),
+ /// Delete one placement.
+ DeletePlacement(u32),
+ /// Delete one bitmap and its placements.
+ DeleteBitmap(u32),
+ /// Consume an unknown protocol verb without mutation.
+ Ignored,
+}
+
+/// An error in a command within the Ratty Bitmap Surface namespace.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BitmapProtocolError {
+ message: &'static str,
+ cleanup: Option,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum BitmapErrorCleanup {
+ DiscardPendingRegistration {
+ bitmap_id: u32,
+ },
+ DiscardPendingFrame {
+ bitmap_id: u32,
+ sequence: u32,
+ format: Option,
+ width: Option,
+ height: Option,
+ },
+}
+
+impl BitmapProtocolError {
+ fn new(message: &'static str) -> Self {
+ Self {
+ message,
+ cleanup: None,
+ }
+ }
+
+ fn frame_payload(
+ message: &'static str,
+ bitmap_id: u32,
+ sequence: u32,
+ format: Option,
+ width: Option,
+ height: Option,
+ ) -> Self {
+ Self {
+ message,
+ cleanup: Some(BitmapErrorCleanup::DiscardPendingFrame {
+ bitmap_id,
+ sequence,
+ format,
+ width,
+ height,
+ }),
+ }
+ }
+
+ fn registration_payload(message: &'static str, bitmap_id: u32) -> Self {
+ Self {
+ message,
+ cleanup: Some(BitmapErrorCleanup::DiscardPendingRegistration { bitmap_id }),
+ }
+ }
+}
+
+impl fmt::Display for BitmapProtocolError {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str(self.message)
+ }
+}
+
+impl std::error::Error for BitmapProtocolError {}
+
+type Fields<'a> = HashMap<&'a str, &'a str>;
+
+/// Consumes a complete Ratty Bitmap Surface APC sequence.
+pub fn consume_sequence(sequence: &[u8]) -> Option> {
+ if !sequence.starts_with(BITMAP_APC_START) {
+ return None;
+ }
+
+ Some(parse_sequence(sequence))
+}
+
+/// Returns the exact v1 support-discovery response.
+pub fn support_reply() -> Vec {
+ SUPPORT_REPLY.to_vec()
+}
+
+fn parse_sequence(sequence: &[u8]) -> Result {
+ parse_sequence_with_payload_limit(sequence, MAX_BITMAP_CHUNK_DECODED_BYTES)
+}
+
+fn parse_sequence_with_payload_limit(
+ sequence: &[u8],
+ payload_limit: usize,
+) -> Result {
+ parse_sequence_with_limits(sequence, payload_limit, BITMAP_APC_HEADER_ALLOWANCE)
+}
+
+fn parse_sequence_with_limits(
+ sequence: &[u8],
+ payload_limit: usize,
+ header_limit: usize,
+) -> Result {
+ let content_end = if sequence.ends_with(&[C1_ST]) {
+ sequence.len() - 1
+ } else if sequence.ends_with(ST) {
+ sequence.len() - ST.len()
+ } else {
+ return Err(BitmapProtocolError::new("invalid bitmap APC terminator"));
+ };
+ let content = std::str::from_utf8(&sequence[BITMAP_APC_START.len()..content_end])
+ .map_err(|_| BitmapProtocolError::new("bitmap APC is not valid UTF-8"))?;
+ if bitmap_header_extent(content) > header_limit {
+ return Err(BitmapProtocolError::new(HEADER_TOO_LARGE));
+ }
+ let mut parts: Vec<_> = content.split(';').collect();
+ let verb = parts
+ .first()
+ .copied()
+ .ok_or_else(|| BitmapProtocolError::new("missing bitmap verb"))?;
+ if verb.is_empty() {
+ return Err(BitmapProtocolError::new("missing bitmap verb"));
+ }
+ parts.remove(0);
+
+ match verb {
+ "s" => parse_support(&parts),
+ "r" => parse_register(&parts, payload_limit),
+ "p" => parse_place(&parts),
+ "u" => parse_update(&parts),
+ "f" => parse_frame(&parts, payload_limit),
+ "d" => parse_delete(&parts),
+ _ => Ok(BitmapOperation::Ignored),
+ }
+}
+
+fn bitmap_header_extent(content: &str) -> usize {
+ if content.starts_with("r;") || content.starts_with("f;") {
+ content
+ .rfind(';')
+ .map_or(content.len(), |separator| separator + 1)
+ } else {
+ content.len()
+ }
+}
+
+fn parse_support(parts: &[&str]) -> Result {
+ if parts.is_empty() {
+ Ok(BitmapOperation::SupportQuery)
+ } else {
+ Err(BitmapProtocolError::new(
+ "support query does not accept fields",
+ ))
+ }
+}
+
+fn parse_register(
+ parts: &[&str],
+ payload_limit: usize,
+) -> Result {
+ let (payload, header) = split_payload(parts)?;
+ let fields = parse_fields(header, &["id", "fmt", "source", "more", "name"])?;
+ let format = optional_string(&fields, "fmt");
+ let source = optional_string(&fields, "source");
+ if format.is_some() != source.is_some() {
+ return Err(BitmapProtocolError::new(
+ "registration format and source must be provided together",
+ ));
+ }
+ if format.as_deref().is_some_and(|value| value != "png") {
+ return Err(BitmapProtocolError::new("unsupported bitmap format"));
+ }
+ if source.as_deref().is_some_and(|value| value != "payload") {
+ return Err(BitmapProtocolError::new(
+ "unsupported bitmap registration source",
+ ));
+ }
+
+ let bitmap_id = required_u32(&fields, "id")?;
+ let data = decode_payload(payload, payload_limit).map_err(|error| {
+ if error.message == CHUNK_PAYLOAD_TOO_LARGE {
+ BitmapProtocolError::registration_payload(error.message, bitmap_id)
+ } else {
+ error
+ }
+ })?;
+
+ Ok(BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id,
+ format,
+ source,
+ name: optional_string(&fields, "name"),
+ more: required_bool(&fields, "more")?,
+ data,
+ }))
+}
+
+fn parse_place(parts: &[&str]) -> Result {
+ let fields = parse_fields(
+ parts,
+ &[
+ "id", "pid", "row", "col", "w", "h", "src_x", "src_y", "src_w", "src_h", "fit",
+ "filter", "opacity",
+ ],
+ )?;
+ let columns = required_nonzero_u32(&fields, "w")?;
+ let rows = required_nonzero_u32(&fields, "h")?;
+
+ Ok(BitmapOperation::Place(BitmapPlacement {
+ bitmap_id: required_u32(&fields, "id")?,
+ placement_id: required_u32(&fields, "pid")?,
+ row: required_u16(&fields, "row")?,
+ col: required_u16(&fields, "col")?,
+ columns,
+ rows,
+ source: parse_source(&fields)?,
+ fit: parse_fit(fields.get("fit").copied())?.unwrap_or(BitmapFit::Contain),
+ filter: parse_filter(fields.get("filter").copied())?.unwrap_or(BitmapFilter::Linear),
+ opacity: parse_opacity(fields.get("opacity").copied())?.unwrap_or(1.0),
+ }))
+}
+
+fn parse_update(parts: &[&str]) -> Result {
+ let fields = parse_fields(
+ parts,
+ &[
+ "pid", "row", "col", "w", "h", "src_x", "src_y", "src_w", "src_h", "fit", "filter",
+ "opacity",
+ ],
+ )?;
+ let placement_id = required_u32(&fields, "pid")?;
+ let columns = optional_nonzero_u32(&fields, "w")?;
+ let rows = optional_nonzero_u32(&fields, "h")?;
+ if columns.is_some() != rows.is_some() {
+ return Err(BitmapProtocolError::new(
+ "update width and height must be provided together",
+ ));
+ }
+ let update = BitmapPlacementUpdate {
+ row: optional_u16(&fields, "row")?,
+ col: optional_u16(&fields, "col")?,
+ columns,
+ rows,
+ source: parse_source(&fields)?,
+ fit: parse_fit(fields.get("fit").copied())?,
+ filter: parse_filter(fields.get("filter").copied())?,
+ opacity: parse_opacity(fields.get("opacity").copied())?,
+ };
+ if update == BitmapPlacementUpdate::default() {
+ return Err(BitmapProtocolError::new(
+ "placement update contains no mutable fields",
+ ));
+ }
+
+ Ok(BitmapOperation::Update {
+ placement_id,
+ update,
+ })
+}
+
+fn parse_frame(
+ parts: &[&str],
+ payload_limit: usize,
+) -> Result {
+ let (payload, header) = split_payload(parts)?;
+ let fields = parse_fields(header, &["id", "seq", "fmt", "w", "h", "more"])?;
+ let format = optional_string(&fields, "fmt");
+ let width = optional_nonzero_u32(&fields, "w")?;
+ let height = optional_nonzero_u32(&fields, "h")?;
+ let metadata_count = usize::from(format.is_some())
+ + usize::from(width.is_some())
+ + usize::from(height.is_some());
+ if metadata_count != 0 && metadata_count != 3 {
+ return Err(BitmapProtocolError::new(
+ "frame format and dimensions must be provided together",
+ ));
+ }
+ if format.as_deref().is_some_and(|value| value != "rgba8") {
+ return Err(BitmapProtocolError::new("unsupported bitmap frame format"));
+ }
+ let bitmap_id = required_u32(&fields, "id")?;
+ let sequence = required_u32(&fields, "seq")?;
+ let more = required_bool(&fields, "more")?;
+ let data = decode_payload(payload, payload_limit).map_err(|error| {
+ BitmapProtocolError::frame_payload(
+ error.message,
+ bitmap_id,
+ sequence,
+ format.clone(),
+ width,
+ height,
+ )
+ })?;
+
+ Ok(BitmapOperation::Frame(BitmapFrameChunk {
+ bitmap_id,
+ sequence,
+ format,
+ width,
+ height,
+ more,
+ data,
+ }))
+}
+
+fn parse_delete(parts: &[&str]) -> Result {
+ let fields = parse_fields(parts, &["id", "pid"])?;
+ match (fields.get("id"), fields.get("pid")) {
+ (Some(id), None) => Ok(BitmapOperation::DeleteBitmap(parse_u32(id)?)),
+ (None, Some(placement_id)) => {
+ Ok(BitmapOperation::DeletePlacement(parse_u32(placement_id)?))
+ }
+ _ => Err(BitmapProtocolError::new(
+ "delete requires exactly one bitmap or placement ID",
+ )),
+ }
+}
+
+fn split_payload<'a>(
+ parts: &'a [&'a str],
+) -> Result<(&'a str, &'a [&'a str]), BitmapProtocolError> {
+ let (payload, header) = parts
+ .split_last()
+ .ok_or_else(|| BitmapProtocolError::new("missing bitmap payload"))?;
+ if payload.is_empty() {
+ return Err(BitmapProtocolError::new("missing bitmap payload"));
+ }
+ Ok((payload, header))
+}
+
+fn parse_fields<'a>(
+ parts: &'a [&'a str],
+ allowed: &[&str],
+) -> Result, BitmapProtocolError> {
+ let mut fields = HashMap::new();
+ for part in parts {
+ let (key, value) = part
+ .split_once('=')
+ .ok_or_else(|| BitmapProtocolError::new("malformed bitmap field"))?;
+ if !allowed.contains(&key) {
+ return Err(BitmapProtocolError::new("unknown bitmap field"));
+ }
+ if fields.insert(key, value).is_some() {
+ return Err(BitmapProtocolError::new("duplicate bitmap field"));
+ }
+ }
+ Ok(fields)
+}
+
+fn required_u32(fields: &Fields<'_>, key: &str) -> Result {
+ fields
+ .get(key)
+ .ok_or_else(|| BitmapProtocolError::new("missing required bitmap field"))
+ .and_then(|value| parse_u32(value))
+}
+
+fn parse_u32(value: &str) -> Result {
+ value
+ .parse()
+ .map_err(|_| BitmapProtocolError::new("invalid unsigned bitmap integer"))
+}
+
+fn required_nonzero_u32(fields: &Fields<'_>, key: &str) -> Result {
+ let value = required_u32(fields, key)?;
+ if value == 0 {
+ Err(BitmapProtocolError::new(
+ "bitmap dimensions must be nonzero",
+ ))
+ } else {
+ Ok(value)
+ }
+}
+
+fn optional_nonzero_u32(
+ fields: &Fields<'_>,
+ key: &str,
+) -> Result, BitmapProtocolError> {
+ fields
+ .get(key)
+ .map(|value| {
+ let value = parse_u32(value)?;
+ if value == 0 {
+ Err(BitmapProtocolError::new(
+ "bitmap dimensions must be nonzero",
+ ))
+ } else {
+ Ok(value)
+ }
+ })
+ .transpose()
+}
+
+fn required_u16(fields: &Fields<'_>, key: &str) -> Result {
+ fields
+ .get(key)
+ .ok_or_else(|| BitmapProtocolError::new("missing required bitmap field"))?
+ .parse()
+ .map_err(|_| BitmapProtocolError::new("invalid terminal-cell coordinate"))
+}
+
+fn optional_u16(fields: &Fields<'_>, key: &str) -> Result, BitmapProtocolError> {
+ fields
+ .get(key)
+ .map(|value| {
+ value
+ .parse()
+ .map_err(|_| BitmapProtocolError::new("invalid terminal-cell coordinate"))
+ })
+ .transpose()
+}
+
+fn required_bool(fields: &Fields<'_>, key: &str) -> Result {
+ match fields.get(key).copied() {
+ Some("0") => Ok(false),
+ Some("1") => Ok(true),
+ Some(_) => Err(BitmapProtocolError::new("invalid bitmap boolean")),
+ None => Err(BitmapProtocolError::new("missing required bitmap field")),
+ }
+}
+
+fn optional_string(fields: &Fields<'_>, key: &str) -> Option {
+ fields.get(key).map(|value| (*value).to_owned())
+}
+
+fn parse_source(fields: &Fields<'_>) -> Result, BitmapProtocolError> {
+ let values = ["src_x", "src_y", "src_w", "src_h"].map(|key| fields.get(key).copied());
+ let [x, y, width, height] = match values {
+ [None, None, None, None] => return Ok(None),
+ [Some(x), Some(y), Some(width), Some(height)] => [x, y, width, height],
+ _ => {
+ return Err(BitmapProtocolError::new(
+ "source rectangle requires all four fields",
+ ));
+ }
+ };
+ let width = parse_u32(width)?;
+ let height = parse_u32(height)?;
+ if width == 0 || height == 0 {
+ return Err(BitmapProtocolError::new(
+ "source dimensions must be nonzero",
+ ));
+ }
+ Ok(Some(SourceRect {
+ x: parse_u32(x)?,
+ y: parse_u32(y)?,
+ width,
+ height,
+ }))
+}
+
+fn parse_fit(value: Option<&str>) -> Result, BitmapProtocolError> {
+ match value {
+ None => Ok(None),
+ Some("contain") => Ok(Some(BitmapFit::Contain)),
+ Some("cover") => Ok(Some(BitmapFit::Cover)),
+ Some("fill") => Ok(Some(BitmapFit::Fill)),
+ Some(_) => Err(BitmapProtocolError::new("unsupported bitmap fit mode")),
+ }
+}
+
+fn parse_filter(value: Option<&str>) -> Result, BitmapProtocolError> {
+ match value {
+ None => Ok(None),
+ Some("nearest") => Ok(Some(BitmapFilter::Nearest)),
+ Some("linear") => Ok(Some(BitmapFilter::Linear)),
+ Some(_) => Err(BitmapProtocolError::new("unsupported bitmap filter mode")),
+ }
+}
+
+fn parse_opacity(value: Option<&str>) -> Result, BitmapProtocolError> {
+ value
+ .map(|value| {
+ let opacity: f32 = value
+ .parse()
+ .map_err(|_| BitmapProtocolError::new("invalid bitmap opacity"))?;
+ if !opacity.is_finite() {
+ return Err(BitmapProtocolError::new("bitmap opacity must be finite"));
+ }
+ Ok(opacity.clamp(0.0, 1.0))
+ })
+ .transpose()
+}
+
+fn decode_payload(payload: &str, payload_limit: usize) -> Result, BitmapProtocolError> {
+ let estimated_len = estimated_decoded_payload_len(payload)
+ .ok_or_else(|| BitmapProtocolError::new("bitmap payload length overflow"))?;
+ if estimated_len > payload_limit {
+ return Err(BitmapProtocolError::new(CHUNK_PAYLOAD_TOO_LARGE));
+ }
+ base64::engine::general_purpose::STANDARD
+ .decode(payload)
+ .map_err(|_| BitmapProtocolError::new("invalid bitmap payload base64"))
+}
+
+fn estimated_decoded_payload_len(payload: &str) -> Option {
+ let len = payload.len();
+ let remainder_bytes = match len % 4 {
+ 0 => 0,
+ 2 => 1,
+ 3 => 2,
+ _ => 3,
+ };
+ let padding = if len.is_multiple_of(4) {
+ payload
+ .as_bytes()
+ .iter()
+ .rev()
+ .take(2)
+ .take_while(|byte| **byte == b'=')
+ .count()
+ } else {
+ 0
+ };
+ (len / 4)
+ .checked_mul(3)?
+ .checked_add(remainder_bytes)?
+ .checked_sub(padding)
+}
+
+/// A decoded bitmap and its eventual stable Bevy image handle.
+pub struct RegisteredBitmap {
+ width: u32,
+ height: u32,
+ decoded_bytes: u64,
+ rgba: Vec,
+ handle: Option>,
+}
+
+impl RegisteredBitmap {
+ /// Returns the bitmap width in pixels.
+ pub(crate) fn width(&self) -> u32 {
+ self.width
+ }
+
+ /// Returns the bitmap height in pixels.
+ pub(crate) fn height(&self) -> u32 {
+ self.height
+ }
+
+ /// Returns the stable Bevy image handle after the renderer uploads the bitmap.
+ pub(crate) fn handle(&self) -> Option<&Handle> {
+ self.handle.as_ref()
+ }
+
+ /// Moves pixels that have not yet been synchronized into the Bevy image asset.
+ pub(crate) fn take_pending_rgba(&mut self) -> Option> {
+ (!self.rgba.is_empty()).then(|| std::mem::take(&mut self.rgba))
+ }
+
+ /// Records the stable Bevy image handle created by the renderer.
+ pub(crate) fn set_handle(&mut self, handle: Handle) {
+ debug_assert!(
+ self.handle
+ .as_ref()
+ .is_none_or(|current| current == &handle)
+ );
+ self.handle = Some(handle);
+ }
+}
+
+/// The validated state of one independently addressable bitmap placement.
+#[derive(Clone, Debug, PartialEq)]
+pub struct BitmapPlacementState {
+ generation: u64,
+ bitmap_id: u32,
+ row: i64,
+ col: u16,
+ columns: u32,
+ rows: u32,
+ source: Option,
+ fit: BitmapFit,
+ filter: BitmapFilter,
+ opacity: f32,
+}
+
+impl BitmapPlacementState {
+ /// Returns this placement lifetime's monotonically increasing generation.
+ pub(crate) fn generation(&self) -> u64 {
+ self.generation
+ }
+
+ /// Returns the registered bitmap used by this placement.
+ pub(crate) fn bitmap_id(&self) -> u32 {
+ self.bitmap_id
+ }
+
+ /// Returns the placement's terminal row.
+ pub(crate) fn row(&self) -> i64 {
+ self.row
+ }
+
+ /// Returns the placement's terminal column.
+ pub(crate) fn col(&self) -> u16 {
+ self.col
+ }
+
+ /// Returns the placement width in terminal columns.
+ pub(crate) fn columns(&self) -> u32 {
+ self.columns
+ }
+
+ /// Returns the placement height in terminal rows.
+ pub(crate) fn rows(&self) -> u32 {
+ self.rows
+ }
+
+ /// Returns the validated source crop, if present.
+ pub(crate) fn source(&self) -> Option {
+ self.source
+ }
+
+ /// Returns the placement fit mode.
+ pub(crate) fn fit(&self) -> BitmapFit {
+ self.fit
+ }
+
+ /// Returns the placement filtering mode.
+ pub(crate) fn filter(&self) -> BitmapFilter {
+ self.filter
+ }
+
+ /// Returns the clamped placement opacity.
+ pub(crate) fn opacity(&self) -> f32 {
+ self.opacity
+ }
+}
+
+struct PendingBitmapTransfer {
+ format: String,
+ source: String,
+ name: Option,
+ data: Vec,
+ last_touched: Instant,
+}
+
+struct PendingBitmapFrame {
+ sequence: u32,
+ format: String,
+ width: u32,
+ height: u32,
+ expected_len: usize,
+ data: Vec,
+ last_touched: Instant,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct BitmapLimits {
+ pub(crate) max_bitmaps: usize,
+ pub(crate) max_placements: usize,
+ pub(crate) max_image_width: u32,
+ pub(crate) max_image_height: u32,
+ pub(crate) max_bitmap_bytes: u64,
+ pub(crate) max_total_bitmap_bytes: u64,
+ pub(crate) max_pending_bytes: u64,
+ pub(crate) max_pending_transfers: usize,
+}
+
+impl Default for BitmapLimits {
+ fn default() -> Self {
+ Self::from(&BitmapConfig::default())
+ }
+}
+
+impl BitmapLimits {
+ pub(crate) fn decoder_limits(self) -> image::Limits {
+ let mut limits = image::Limits::default();
+ limits.max_image_width = Some(self.max_image_width);
+ limits.max_image_height = Some(self.max_image_height);
+ limits.max_alloc = Some(self.max_bitmap_bytes);
+ limits
+ }
+}
+
+impl From<&BitmapConfig> for BitmapLimits {
+ fn from(config: &BitmapConfig) -> Self {
+ Self {
+ max_bitmaps: config.max_bitmaps,
+ max_placements: config.max_placements,
+ max_image_width: config.max_image_width,
+ max_image_height: config.max_image_height,
+ max_bitmap_bytes: config.max_bitmap_bytes,
+ max_total_bitmap_bytes: config.max_total_bitmap_bytes,
+ max_pending_bytes: config.max_pending_bytes,
+ max_pending_transfers: config.max_pending_transfers,
+ }
+ }
+}
+
+/// In-memory lifecycle state for registered bitmaps, frames, and placements.
+#[derive(Default)]
+pub struct BitmapSurfaceState {
+ limits: BitmapLimits,
+ pending_registrations: HashMap,
+ pending_frames: HashMap,
+ bitmaps: HashMap,
+ placements: HashMap,
+ latest_frame_sequences: HashMap,
+ next_placement_generation: u64,
+ resident_bitmap_bytes: u64,
+ dirty: bool,
+}
+
+impl BitmapSurfaceState {
+ pub(crate) fn with_limits(limits: BitmapLimits) -> Self {
+ Self {
+ limits,
+ ..Self::default()
+ }
+ }
+
+ /// Parses and applies one complete bitmap APC sequence, including parser-directed cleanup.
+ #[cfg(test)]
+ pub(crate) fn consume_and_apply(
+ &mut self,
+ sequence: &[u8],
+ ) -> Option>, BitmapProtocolError>> {
+ let parsed = consume_sequence(sequence)?;
+ Some(match parsed {
+ Ok(operation) => self.apply(operation),
+ Err(error) => {
+ self.apply_error_cleanup(&error);
+ Err(error)
+ }
+ })
+ }
+
+ /// Parses and applies one command while returning the exact operation
+ /// whose terminal placement mutation must be committed at the same wire
+ /// boundary.
+ pub(crate) fn consume_apply_and_return(&mut self, sequence: &[u8]) -> BitmapConsumeResult {
+ let parsed = consume_sequence(sequence)?;
+ Some(match parsed {
+ Ok(operation) => {
+ let applied = operation.clone();
+ self.apply(operation).map(|reply| (applied, reply))
+ }
+ Err(error) => {
+ self.apply_error_cleanup(&error);
+ Err(error)
+ }
+ })
+ }
+
+ /// Applies one parsed bitmap protocol operation transactionally.
+ pub fn apply(
+ &mut self,
+ operation: BitmapOperation,
+ ) -> Result>, BitmapProtocolError> {
+ self.evict_stale_pending_transfers();
+ match operation {
+ BitmapOperation::SupportQuery => Ok(Some(support_reply())),
+ BitmapOperation::Register(chunk) => {
+ self.apply_registration(chunk)?;
+ Ok(None)
+ }
+ BitmapOperation::Place(placement) => {
+ self.apply_placement(placement)?;
+ Ok(None)
+ }
+ BitmapOperation::Update {
+ placement_id,
+ update,
+ } => {
+ self.apply_placement_update(placement_id, update)?;
+ Ok(None)
+ }
+ BitmapOperation::Frame(chunk) => {
+ self.apply_frame(chunk)?;
+ Ok(None)
+ }
+ BitmapOperation::DeletePlacement(placement_id) => {
+ if self.placements.remove(&placement_id).is_some() {
+ self.dirty = true;
+ }
+ Ok(None)
+ }
+ BitmapOperation::DeleteBitmap(bitmap_id) => {
+ self.delete_bitmap(bitmap_id);
+ Ok(None)
+ }
+ BitmapOperation::Ignored => Ok(None),
+ }
+ }
+
+ /// Returns a registered bitmap without allowing map mutation.
+ pub(crate) fn bitmap(&self, bitmap_id: u32) -> Option<&RegisteredBitmap> {
+ self.bitmaps.get(&bitmap_id)
+ }
+
+ /// Returns a registered bitmap for renderer-owned upload bookkeeping.
+ pub(crate) fn bitmap_mut(&mut self, bitmap_id: u32) -> Option<&mut RegisteredBitmap> {
+ self.bitmaps.get_mut(&bitmap_id)
+ }
+
+ /// Iterates registered bitmaps without exposing mutable map access.
+ pub(crate) fn bitmaps(&self) -> impl Iterator
- {
+ self.bitmaps.iter()
+ }
+
+ /// Returns a placement without allowing map mutation.
+ pub(crate) fn placement(&self, placement_id: u32) -> Option<&BitmapPlacementState> {
+ self.placements.get(&placement_id)
+ }
+
+ /// Iterates placements without exposing mutable map access.
+ pub(crate) fn placements(&self) -> impl Iterator
- {
+ self.placements.iter()
+ }
+
+ /// Reports whether visible bitmap state changed since the last dirty reset.
+ pub(crate) fn is_dirty(&self) -> bool {
+ self.dirty
+ }
+
+ /// Returns and clears the visible-state dirty flag.
+ pub(crate) fn take_dirty(&mut self) -> bool {
+ std::mem::take(&mut self.dirty)
+ }
+
+ fn apply_registration(
+ &mut self,
+ chunk: BitmapRegisterChunk,
+ ) -> Result<(), BitmapProtocolError> {
+ if self.bitmaps.contains_key(&chunk.bitmap_id) {
+ return Err(BitmapProtocolError::new("bitmap ID is already registered"));
+ }
+
+ let bitmap_id = chunk.bitmap_id;
+ let had_pending = self.pending_registrations.contains_key(&bitmap_id);
+ if !had_pending && self.bitmaps.len() >= self.limits.max_bitmaps {
+ return Err(BitmapProtocolError::new(
+ "registered bitmap count limit exceeded",
+ ));
+ }
+ let mut pending = match self.pending_registrations.remove(&bitmap_id) {
+ Some(pending) => {
+ if chunk
+ .format
+ .as_deref()
+ .is_some_and(|value| value != pending.format)
+ || chunk
+ .source
+ .as_deref()
+ .is_some_and(|value| value != pending.source)
+ || chunk
+ .name
+ .as_ref()
+ .is_some_and(|value| Some(value) != pending.name.as_ref())
+ {
+ self.pending_registrations.insert(bitmap_id, pending);
+ return Err(BitmapProtocolError::new(
+ "registration continuation metadata does not match",
+ ));
+ }
+ pending
+ }
+ None => PendingBitmapTransfer {
+ format: chunk
+ .format
+ .clone()
+ .filter(|value| value == "png")
+ .ok_or_else(|| {
+ BitmapProtocolError::new("first registration chunk requires PNG format")
+ })?,
+ source: chunk
+ .source
+ .clone()
+ .filter(|value| value == "payload")
+ .ok_or_else(|| {
+ BitmapProtocolError::new("first registration chunk requires payload source")
+ })?,
+ name: chunk.name.clone(),
+ data: Vec::new(),
+ last_touched: Instant::now(),
+ },
+ };
+
+ let new_len = pending
+ .data
+ .len()
+ .checked_add(chunk.data.len())
+ .filter(|length| *length <= MAX_REGISTRATION_BYTES)
+ .ok_or_else(|| {
+ BitmapProtocolError::new("bitmap registration payload exceeds 64 MiB")
+ })?;
+ self.ensure_pending_budget(new_len, chunk.more && !had_pending)?;
+ pending.data.extend_from_slice(&chunk.data);
+ pending.last_touched = Instant::now();
+
+ if chunk.more {
+ self.pending_registrations.insert(bitmap_id, pending);
+ return Ok(());
+ }
+ if self.bitmaps.len() >= self.limits.max_bitmaps {
+ return Err(BitmapProtocolError::new(
+ "registered bitmap count limit exceeded",
+ ));
+ }
+
+ let decoder_limits = self.limits.decoder_limits();
+ let mut dimension_reader =
+ image::ImageReader::with_format(Cursor::new(&pending.data), image::ImageFormat::Png);
+ dimension_reader.limits(decoder_limits.clone());
+ let (width, height) = dimension_reader
+ .into_dimensions()
+ .map_err(|_| BitmapProtocolError::new("invalid or oversized PNG bitmap payload"))?;
+ let decoded_bytes = decoded_rgba_bytes(width, height)?;
+ if decoded_bytes > self.limits.max_bitmap_bytes {
+ return Err(BitmapProtocolError::new(
+ "decoded bitmap exceeds the per-bitmap byte limit",
+ ));
+ }
+ let next_resident_bytes = self
+ .resident_bitmap_bytes
+ .checked_add(decoded_bytes)
+ .filter(|bytes| *bytes <= self.limits.max_total_bitmap_bytes)
+ .ok_or_else(|| {
+ BitmapProtocolError::new("decoded bitmap exceeds the total bitmap byte budget")
+ })?;
+
+ let mut reader =
+ image::ImageReader::with_format(Cursor::new(&pending.data), image::ImageFormat::Png);
+ reader.limits(decoder_limits);
+ let decoded = reader
+ .decode()
+ .map_err(|_| BitmapProtocolError::new("invalid or oversized PNG bitmap payload"))?
+ .to_rgba8();
+ if u64::try_from(decoded.as_raw().len()).ok() != Some(decoded_bytes) {
+ return Err(BitmapProtocolError::new(
+ "decoded bitmap byte length does not match its dimensions",
+ ));
+ }
+ self.bitmaps.insert(
+ bitmap_id,
+ RegisteredBitmap {
+ width,
+ height,
+ decoded_bytes,
+ rgba: decoded.into_raw(),
+ handle: None,
+ },
+ );
+ self.resident_bitmap_bytes = next_resident_bytes;
+ self.dirty = true;
+ Ok(())
+ }
+
+ fn apply_placement(&mut self, placement: BitmapPlacement) -> Result<(), BitmapProtocolError> {
+ if self.placements.contains_key(&placement.placement_id) {
+ return Err(BitmapProtocolError::new("placement ID is already in use"));
+ }
+ if self.placements.len() >= self.limits.max_placements {
+ return Err(BitmapProtocolError::new(
+ "bitmap placement count limit exceeded",
+ ));
+ }
+ let bitmap = self
+ .bitmaps
+ .get(&placement.bitmap_id)
+ .ok_or_else(|| BitmapProtocolError::new("placement bitmap is not registered"))?;
+ if placement.columns == 0 || placement.rows == 0 {
+ return Err(BitmapProtocolError::new(
+ "placement dimensions must be nonzero",
+ ));
+ }
+ let opacity = validate_opacity(placement.opacity)?;
+ let source = clamp_source(placement.source, bitmap.width, bitmap.height)?;
+ let generation = self
+ .next_placement_generation
+ .checked_add(1)
+ .ok_or_else(|| BitmapProtocolError::new("bitmap placement generation overflow"))?;
+ self.next_placement_generation = generation;
+ self.placements.insert(
+ placement.placement_id,
+ BitmapPlacementState {
+ generation,
+ bitmap_id: placement.bitmap_id,
+ row: i64::from(placement.row),
+ col: placement.col,
+ columns: placement.columns,
+ rows: placement.rows,
+ source,
+ fit: placement.fit,
+ filter: placement.filter,
+ opacity,
+ },
+ );
+ self.dirty = true;
+ Ok(())
+ }
+
+ fn apply_placement_update(
+ &mut self,
+ placement_id: u32,
+ update: BitmapPlacementUpdate,
+ ) -> Result<(), BitmapProtocolError> {
+ if update == BitmapPlacementUpdate::default() {
+ return Err(BitmapProtocolError::new(
+ "placement update contains no fields",
+ ));
+ }
+ if update.columns.is_some() != update.rows.is_some() {
+ return Err(BitmapProtocolError::new(
+ "placement width and height must be updated together",
+ ));
+ }
+ let current = self
+ .placements
+ .get(&placement_id)
+ .ok_or_else(|| BitmapProtocolError::new("placement does not exist"))?;
+ let bitmap = self
+ .bitmaps
+ .get(¤t.bitmap_id)
+ .ok_or_else(|| BitmapProtocolError::new("placement bitmap is not registered"))?;
+ let mut next = current.clone();
+ if let Some(row) = update.row {
+ next.row = i64::from(row);
+ }
+ if let Some(col) = update.col {
+ next.col = col;
+ }
+ if let (Some(columns), Some(rows)) = (update.columns, update.rows) {
+ if columns == 0 || rows == 0 {
+ return Err(BitmapProtocolError::new(
+ "placement dimensions must be nonzero",
+ ));
+ }
+ next.columns = columns;
+ next.rows = rows;
+ }
+ if let Some(source) = update.source {
+ next.source = clamp_source(Some(source), bitmap.width, bitmap.height)?;
+ }
+ if let Some(fit) = update.fit {
+ next.fit = fit;
+ }
+ if let Some(filter) = update.filter {
+ next.filter = filter;
+ }
+ if let Some(opacity) = update.opacity {
+ next.opacity = validate_opacity(opacity)?;
+ }
+ self.placements.insert(placement_id, next);
+ self.dirty = true;
+ Ok(())
+ }
+
+ fn apply_frame(&mut self, chunk: BitmapFrameChunk) -> Result<(), BitmapProtocolError> {
+ let bitmap = self
+ .bitmaps
+ .get(&chunk.bitmap_id)
+ .ok_or_else(|| BitmapProtocolError::new("frame bitmap is not registered"))?;
+ let bitmap_dimensions = (bitmap.width, bitmap.height);
+ let latest = self.latest_frame_sequences.get(&chunk.bitmap_id).copied();
+ if latest.is_some_and(|latest| chunk.sequence <= latest) {
+ return Err(BitmapProtocolError::new("stale bitmap frame sequence"));
+ }
+
+ let bitmap_id = chunk.bitmap_id;
+ let had_pending = self.pending_frames.contains_key(&bitmap_id);
+ let mut pending = match self.pending_frames.remove(&bitmap_id) {
+ Some(pending) if chunk.sequence < pending.sequence => {
+ self.pending_frames.insert(bitmap_id, pending);
+ return Err(BitmapProtocolError::new("stale bitmap frame sequence"));
+ }
+ Some(pending) if chunk.sequence == pending.sequence => {
+ if chunk
+ .format
+ .as_deref()
+ .is_some_and(|value| value != pending.format)
+ || chunk.width.is_some_and(|value| value != pending.width)
+ || chunk.height.is_some_and(|value| value != pending.height)
+ {
+ return Err(BitmapProtocolError::new(
+ "frame continuation metadata does not match",
+ ));
+ }
+ pending
+ }
+ Some(previous) => match new_pending_frame(&chunk, bitmap_dimensions) {
+ Ok(next) => next,
+ Err(error) => {
+ self.pending_frames.insert(bitmap_id, previous);
+ return Err(error);
+ }
+ },
+ None => new_pending_frame(&chunk, bitmap_dimensions)?,
+ };
+
+ let new_len = match pending.data.len().checked_add(chunk.data.len()) {
+ Some(length) if length <= pending.expected_len => length,
+ _ => {
+ return Err(BitmapProtocolError::new(
+ "bitmap frame payload is too large",
+ ));
+ }
+ };
+ self.ensure_pending_budget(new_len, chunk.more && !had_pending)?;
+ pending.data.reserve(new_len - pending.data.len());
+ pending.data.extend_from_slice(&chunk.data);
+ pending.last_touched = Instant::now();
+ if chunk.more {
+ self.pending_frames.insert(bitmap_id, pending);
+ return Ok(());
+ }
+ if pending.data.len() != pending.expected_len {
+ return Err(BitmapProtocolError::new(
+ "bitmap frame payload length does not match",
+ ));
+ }
+
+ self.bitmaps
+ .get_mut(&bitmap_id)
+ .expect("bitmap existence checked above")
+ .rgba = pending.data;
+ self.latest_frame_sequences
+ .insert(bitmap_id, chunk.sequence);
+ self.dirty = true;
+ Ok(())
+ }
+
+ fn delete_bitmap(&mut self, bitmap_id: u32) {
+ self.pending_registrations.remove(&bitmap_id);
+ self.pending_frames.remove(&bitmap_id);
+ if !self.bitmaps.contains_key(&bitmap_id) {
+ return;
+ }
+ self.latest_frame_sequences.remove(&bitmap_id);
+ if let Some(bitmap) = self.bitmaps.remove(&bitmap_id) {
+ self.resident_bitmap_bytes -= bitmap.decoded_bytes;
+ self.placements
+ .retain(|_, placement| placement.bitmap_id != bitmap_id);
+ self.dirty = true;
+ }
+ }
+
+ /// Abort every incomplete bitmap registration/frame after outer APC
+ /// framing has discarded bytes that the protocol parser never saw.
+ pub(crate) fn abort_all_pending_transfers(&mut self) {
+ self.pending_registrations.clear();
+ self.pending_frames.clear();
+ }
+
+ fn ensure_pending_budget(
+ &self,
+ transfer_bytes: usize,
+ adds_transfer: bool,
+ ) -> Result<(), BitmapProtocolError> {
+ let transfer_bytes = u64::try_from(transfer_bytes)
+ .map_err(|_| BitmapProtocolError::new("pending bitmap byte count overflow"))?;
+ self.pending_registrations
+ .values()
+ .map(|pending| pending.data.len())
+ .chain(
+ self.pending_frames
+ .values()
+ .map(|pending| pending.data.len()),
+ )
+ .try_fold(transfer_bytes, |total, bytes| {
+ let bytes = u64::try_from(bytes).ok()?;
+ total.checked_add(bytes)
+ })
+ .filter(|total| *total <= self.limits.max_pending_bytes)
+ .ok_or_else(|| BitmapProtocolError::new("pending bitmap byte budget exceeded"))?;
+
+ self.pending_registrations
+ .len()
+ .checked_add(self.pending_frames.len())
+ .and_then(|total| total.checked_add(usize::from(adds_transfer)))
+ .filter(|total| *total <= self.limits.max_pending_transfers)
+ .ok_or_else(|| BitmapProtocolError::new("pending bitmap transfer limit exceeded"))?;
+ Ok(())
+ }
+
+ fn evict_stale_pending_transfers(&mut self) {
+ let now = Instant::now();
+ self.pending_registrations.retain(|_, pending| {
+ now.saturating_duration_since(pending.last_touched) <= BITMAP_INCOMPLETE_TIMEOUT
+ });
+ self.pending_frames.retain(|_, pending| {
+ now.saturating_duration_since(pending.last_touched) <= BITMAP_INCOMPLETE_TIMEOUT
+ });
+ }
+
+ fn apply_error_cleanup(&mut self, error: &BitmapProtocolError) {
+ if let Some(BitmapErrorCleanup::DiscardPendingRegistration { bitmap_id }) =
+ error.cleanup.as_ref()
+ {
+ self.pending_registrations.remove(bitmap_id);
+ return;
+ }
+ let Some(BitmapErrorCleanup::DiscardPendingFrame {
+ bitmap_id,
+ sequence,
+ format,
+ width,
+ height,
+ }) = error.cleanup.as_ref()
+ else {
+ return;
+ };
+ let should_discard = self.pending_frames.get(bitmap_id).is_some_and(|pending| {
+ if *sequence < pending.sequence {
+ return false;
+ }
+ if *sequence == pending.sequence {
+ return true;
+ }
+ self.bitmaps.get(bitmap_id).is_some_and(|bitmap| {
+ format.as_deref() == Some("rgba8")
+ && *width == Some(bitmap.width)
+ && *height == Some(bitmap.height)
+ })
+ });
+ if should_discard {
+ self.pending_frames.remove(bitmap_id);
+ }
+ }
+}
+
+fn decoded_rgba_bytes(width: u32, height: u32) -> Result {
+ u64::from(width)
+ .checked_mul(u64::from(height))
+ .and_then(|pixels| pixels.checked_mul(4))
+ .ok_or_else(|| BitmapProtocolError::new("decoded bitmap dimensions overflow"))
+}
+
+fn new_pending_frame(
+ chunk: &BitmapFrameChunk,
+ bitmap_dimensions: (u32, u32),
+) -> Result {
+ let format = chunk
+ .format
+ .clone()
+ .filter(|value| value == "rgba8")
+ .ok_or_else(|| BitmapProtocolError::new("first frame chunk requires RGBA8 format"))?;
+ let width = chunk
+ .width
+ .ok_or_else(|| BitmapProtocolError::new("first frame chunk requires width"))?;
+ let height = chunk
+ .height
+ .ok_or_else(|| BitmapProtocolError::new("first frame chunk requires height"))?;
+ let expected_len = width
+ .checked_mul(height)
+ .and_then(|pixels| pixels.checked_mul(4))
+ .and_then(|bytes| usize::try_from(bytes).ok())
+ .ok_or_else(|| BitmapProtocolError::new("bitmap frame dimensions overflow"))?;
+ if (width, height) != bitmap_dimensions {
+ return Err(BitmapProtocolError::new(
+ "bitmap frame dimensions must match registered bitmap",
+ ));
+ }
+ Ok(PendingBitmapFrame {
+ sequence: chunk.sequence,
+ format,
+ width,
+ height,
+ expected_len,
+ data: Vec::new(),
+ last_touched: Instant::now(),
+ })
+}
+
+fn clamp_source(
+ source: Option,
+ bitmap_width: u32,
+ bitmap_height: u32,
+) -> Result, BitmapProtocolError> {
+ let Some(source) = source else {
+ return Ok(None);
+ };
+ if source.width == 0 || source.height == 0 {
+ return Err(BitmapProtocolError::new(
+ "source dimensions must be nonzero",
+ ));
+ }
+ let end_x = source.x.saturating_add(source.width).min(bitmap_width);
+ let end_y = source.y.saturating_add(source.height).min(bitmap_height);
+ let start_x = source.x.min(bitmap_width);
+ let start_y = source.y.min(bitmap_height);
+ if end_x <= start_x || end_y <= start_y {
+ return Err(BitmapProtocolError::new(
+ "source rectangle is outside bitmap bounds",
+ ));
+ }
+ Ok(Some(SourceRect {
+ x: start_x,
+ y: start_y,
+ width: end_x - start_x,
+ height: end_y - start_y,
+ }))
+}
+
+fn validate_opacity(opacity: f32) -> Result {
+ if !opacity.is_finite() {
+ return Err(BitmapProtocolError::new("bitmap opacity must be finite"));
+ }
+ Ok(opacity.clamp(0.0, 1.0))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const SUPPORT_REPLY: &[u8] = b"\x1b_ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1\x1b\\";
+ const PNG_2X2: &[u8] = &[
+ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+ 0x52, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x02, 0x08, 0x06, 0x00, 0x00, 0x00, 0x72,
+ 0xb6, 0x0d, 0x24, 0x00, 0x00, 0x00, 0x12, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0xf8,
+ 0xcf, 0xc0, 0xf0, 0x1f, 0x0c, 0x81, 0x34, 0x18, 0x00, 0x00, 0x49, 0xc8, 0x09, 0xf7, 0xf9,
+ 0xab, 0xb6, 0x0d, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+ ];
+ const RGBA_2X2: &[u8] = &[
+ 255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255,
+ ];
+
+ fn parse(command: &[u8]) -> Result {
+ consume_sequence(command).expect("bitmap namespace should be consumed")
+ }
+
+ fn register_chunk(bitmap_id: u32, data: &[u8], more: bool) -> BitmapOperation {
+ BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id,
+ format: Some("png".into()),
+ source: Some("payload".into()),
+ name: None,
+ more,
+ data: data.to_vec(),
+ })
+ }
+
+ fn registration_continuation(bitmap_id: u32, data: &[u8], more: bool) -> BitmapOperation {
+ BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id,
+ format: None,
+ source: None,
+ name: None,
+ more,
+ data: data.to_vec(),
+ })
+ }
+
+ fn placement(bitmap_id: u32, placement_id: u32) -> BitmapOperation {
+ BitmapOperation::Place(BitmapPlacement {
+ bitmap_id,
+ placement_id,
+ row: 1,
+ col: 2,
+ columns: 8,
+ rows: 4,
+ source: None,
+ fit: BitmapFit::Contain,
+ filter: BitmapFilter::Linear,
+ opacity: 1.0,
+ })
+ }
+
+ fn frame_chunk(bitmap_id: u32, sequence: u32, data: &[u8], more: bool) -> BitmapOperation {
+ BitmapOperation::Frame(BitmapFrameChunk {
+ bitmap_id,
+ sequence,
+ format: Some("rgba8".into()),
+ width: Some(2),
+ height: Some(2),
+ more,
+ data: data.to_vec(),
+ })
+ }
+
+ fn frame_continuation(
+ bitmap_id: u32,
+ sequence: u32,
+ data: &[u8],
+ more: bool,
+ ) -> BitmapOperation {
+ BitmapOperation::Frame(BitmapFrameChunk {
+ bitmap_id,
+ sequence,
+ format: None,
+ width: None,
+ height: None,
+ more,
+ data: data.to_vec(),
+ })
+ }
+
+ fn registered_state() -> BitmapSurfaceState {
+ let mut state = BitmapSurfaceState::default();
+ state
+ .apply(register_chunk(1, PNG_2X2, false))
+ .expect("valid bitmap test fixture should succeed");
+ state.take_dirty();
+ state
+ }
+
+ #[test]
+ fn accepts_both_string_terminators() {
+ assert_eq!(
+ parse(b"\x1b_ratty;i;s\x1b\\").expect("valid bitmap test fixture should succeed"),
+ BitmapOperation::SupportQuery
+ );
+ assert_eq!(
+ parse(b"\x1b_ratty;i;s\x9c").expect("valid bitmap test fixture should succeed"),
+ BitmapOperation::SupportQuery
+ );
+ }
+
+ #[test]
+ fn returns_exact_support_reply() {
+ assert_eq!(support_reply(), SUPPORT_REPLY);
+ }
+
+ #[test]
+ fn parses_one_shot_registration() {
+ let operation = parse(
+ b"\x1b_ratty;i;r;id=42;fmt=png;source=payload;more=0;name=photo.png;aGVsbG8=\x1b\\",
+ )
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id: 42,
+ format: Some("png".into()),
+ source: Some("payload".into()),
+ name: Some("photo.png".into()),
+ more: false,
+ data: b"hello".to_vec(),
+ })
+ );
+ }
+
+ #[test]
+ fn parses_registration_continuation_chunk() {
+ let operation = parse(b"\x1b_ratty;i;r;id=42;more=1;AQID\x9c")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id: 42,
+ format: None,
+ source: None,
+ name: None,
+ more: true,
+ data: vec![1, 2, 3],
+ })
+ );
+ }
+
+ #[test]
+ fn parses_placement_defaults() {
+ let operation = parse(b"\x1b_ratty;i;p;id=42;pid=7;row=4;col=2;w=80;h=30\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Place(BitmapPlacement {
+ bitmap_id: 42,
+ placement_id: 7,
+ row: 4,
+ col: 2,
+ columns: 80,
+ rows: 30,
+ source: None,
+ fit: BitmapFit::Contain,
+ filter: BitmapFilter::Linear,
+ opacity: 1.0,
+ })
+ );
+ }
+
+ #[test]
+ fn parses_explicit_placement_fields_and_clamps_opacity() {
+ let operation = parse(b"\x1b_ratty;i;p;id=42;pid=7;row=4;col=2;w=80;h=30;src_x=3;src_y=5;src_w=20;src_h=10;fit=cover;filter=nearest;opacity=2.5\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Place(BitmapPlacement {
+ bitmap_id: 42,
+ placement_id: 7,
+ row: 4,
+ col: 2,
+ columns: 80,
+ rows: 30,
+ source: Some(SourceRect {
+ x: 3,
+ y: 5,
+ width: 20,
+ height: 10,
+ }),
+ fit: BitmapFit::Cover,
+ filter: BitmapFilter::Nearest,
+ opacity: 1.0,
+ })
+ );
+ }
+
+ #[test]
+ fn parses_full_placement_update() {
+ let operation = parse(b"\x1b_ratty;i;u;pid=7;row=8;col=9;w=40;h=20;src_x=3;src_y=5;src_w=20;src_h=10;fit=fill;filter=nearest;opacity=-0.2\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Update {
+ placement_id: 7,
+ update: BitmapPlacementUpdate {
+ row: Some(8),
+ col: Some(9),
+ columns: Some(40),
+ rows: Some(20),
+ source: Some(SourceRect {
+ x: 3,
+ y: 5,
+ width: 20,
+ height: 10,
+ }),
+ fit: Some(BitmapFit::Fill),
+ filter: Some(BitmapFilter::Nearest),
+ opacity: Some(0.0),
+ },
+ }
+ );
+ }
+
+ #[test]
+ fn parses_one_shot_frame() {
+ let operation =
+ parse(b"\x1b_ratty;i;f;id=42;seq=123;fmt=rgba8;w=1;h=1;more=0;AQIDBA==\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Frame(BitmapFrameChunk {
+ bitmap_id: 42,
+ sequence: 123,
+ format: Some("rgba8".into()),
+ width: Some(1),
+ height: Some(1),
+ more: false,
+ data: vec![1, 2, 3, 4],
+ })
+ );
+ }
+
+ #[test]
+ fn parses_frame_continuation_chunk() {
+ let operation = parse(b"\x1b_ratty;i;f;id=42;seq=123;more=1;AQID\x9c")
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ operation,
+ BitmapOperation::Frame(BitmapFrameChunk {
+ bitmap_id: 42,
+ sequence: 123,
+ format: None,
+ width: None,
+ height: None,
+ more: true,
+ data: vec![1, 2, 3],
+ })
+ );
+ }
+
+ #[test]
+ fn parses_both_delete_targets() {
+ assert_eq!(
+ parse(b"\x1b_ratty;i;d;pid=7\x1b\\").expect("valid bitmap test fixture should succeed"),
+ BitmapOperation::DeletePlacement(7)
+ );
+ assert_eq!(
+ parse(b"\x1b_ratty;i;d;id=42\x1b\\").expect("valid bitmap test fixture should succeed"),
+ BitmapOperation::DeleteBitmap(42)
+ );
+ }
+
+ #[test]
+ fn leaves_other_namespaces_unconsumed() {
+ assert_eq!(consume_sequence(b"\x1b_ratty;g;s\x1b\\"), None);
+ assert_eq!(consume_sequence(b"plain text"), None);
+ }
+
+ #[test]
+ fn consumes_unknown_verbs_as_ignored() {
+ assert_eq!(
+ parse(b"\x1b_ratty;i;x;id=1\x1b\\").expect("valid bitmap test fixture should succeed"),
+ BitmapOperation::Ignored
+ );
+ }
+
+ #[test]
+ fn rejects_empty_bitmap_verb() {
+ assert!(parse(b"\x1b_ratty;i;\x1b\\").is_err());
+ }
+
+ #[test]
+ fn rejects_invalid_base64_and_duplicate_keys() {
+ assert!(parse(b"\x1b_ratty;i;r;id=1;fmt=png;source=payload;more=0;%%%\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;p;id=1;id=2;pid=3;row=0;col=0;w=1;h=1\x1b\\").is_err());
+ }
+
+ #[test]
+ fn preflights_registration_payload_size_before_base64_decode() {
+ let error = parse_sequence_with_payload_limit(
+ b"\x1b_ratty;i;r;id=1;fmt=png;source=payload;more=0;%%%%\x1b\\",
+ 2,
+ )
+ .expect_err("three decoded bytes must exceed a two-byte chunk limit");
+
+ assert_eq!(error.to_string(), CHUNK_PAYLOAD_TOO_LARGE);
+ assert_eq!(
+ error.cleanup,
+ Some(BitmapErrorCleanup::DiscardPendingRegistration { bitmap_id: 1 })
+ );
+ }
+
+ #[test]
+ fn rejects_overlong_non_payload_header_before_field_collection() {
+ let error = parse_sequence_with_limits(
+ b"\x1b_ratty;i;p;id=1;pid=2;row=0;col=0;w=1;h=1\x1b\\",
+ MAX_BITMAP_CHUNK_DECODED_BYTES,
+ 8,
+ )
+ .expect_err("the complete placement content exceeds the test header limit");
+
+ assert_eq!(error.to_string(), "bitmap APC header exceeds 4 KiB");
+ }
+
+ #[test]
+ fn rejects_register_and_frame_semicolon_amplification_as_header() {
+ for command in [
+ b"\x1b_ratty;i;r;;;;;;;;;;;;payload\x1b\\".as_slice(),
+ b"\x1b_ratty;i;f;;;;;;;;;;;;payload\x1b\\".as_slice(),
+ ] {
+ let error = parse_sequence_with_limits(command, MAX_BITMAP_CHUNK_DECODED_BYTES, 8)
+ .expect_err("the final payload separator places semicolon runs in the header");
+
+ assert_eq!(error.to_string(), "bitmap APC header exceeds 4 KiB");
+ }
+ }
+
+ #[test]
+ fn accepts_header_at_injected_boundary() {
+ assert_eq!(
+ parse_sequence_with_limits(b"\x1b_ratty;i;s\x1b\\", MAX_BITMAP_CHUNK_DECODED_BYTES, 1,)
+ .expect("one-byte support header equals the test limit"),
+ BitmapOperation::SupportQuery
+ );
+ }
+
+ #[test]
+ fn preflights_frame_payload_size_with_sequence_cleanup_metadata() {
+ let error = parse_sequence_with_payload_limit(
+ b"\x1b_ratty;i;f;id=7;seq=9;fmt=rgba8;w=1;h=1;more=0;%%%%\x1b\\",
+ 2,
+ )
+ .expect_err("three decoded bytes must exceed a two-byte chunk limit");
+
+ assert_eq!(error.to_string(), CHUNK_PAYLOAD_TOO_LARGE);
+ assert_eq!(
+ error.cleanup,
+ Some(BitmapErrorCleanup::DiscardPendingFrame {
+ bitmap_id: 7,
+ sequence: 9,
+ format: Some("rgba8".into()),
+ width: Some(1),
+ height: Some(1),
+ })
+ );
+ }
+
+ #[test]
+ fn oversized_frame_chunk_preflight_discards_matching_pending_sequence() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 9, &[1, 2], true))
+ .expect("first frame chunk should remain pending");
+ let error =
+ parse_sequence_with_payload_limit(b"\x1b_ratty;i;f;id=1;seq=9;more=0;%%%%\x1b\\", 2)
+ .expect_err("estimated decoded payload exceeds the test chunk limit");
+
+ state.apply_error_cleanup(&error);
+
+ assert!(!state.pending_frames.contains_key(&1));
+ }
+
+ #[test]
+ fn rejects_missing_ids() {
+ assert!(parse(b"\x1b_ratty;i;r;fmt=png;source=payload;more=0;AQ==\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;p;id=1;row=0;col=0;w=1;h=1\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;u;row=1\x1b\\").is_err());
+ }
+
+ #[test]
+ fn rejects_zero_dimensions_and_non_finite_opacity() {
+ assert!(parse(b"\x1b_ratty;i;p;id=1;pid=2;row=0;col=0;w=0;h=1\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;u;pid=2;w=1;h=0\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;p;id=1;pid=2;row=0;col=0;w=1;h=1;opacity=NaN\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;u;pid=2;opacity=inf\x1b\\").is_err());
+ }
+
+ #[test]
+ fn rejects_partial_source_and_destination_groups() {
+ assert!(parse(b"\x1b_ratty;i;p;id=1;pid=2;row=0;col=0;w=1;h=1;src_x=0\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;u;pid=2;src_x=0;src_y=0;src_w=1\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;u;pid=2;w=1\x1b\\").is_err());
+ }
+
+ #[test]
+ fn rejects_missing_first_frame_metadata() {
+ assert!(parse(b"\x1b_ratty;i;f;id=1;seq=2;fmt=rgba8;w=1;more=0;AQIDBA==\x1b\\").is_err());
+ assert!(
+ parse(b"\x1b_ratty;i;f;id=1;seq=2;fmt=rgba8;w=0;h=1;more=0;AQIDBA==\x1b\\").is_err()
+ );
+ }
+
+ #[test]
+ fn rejects_empty_update_and_ambiguous_delete() {
+ assert!(parse(b"\x1b_ratty;i;u;pid=2\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;d\x1b\\").is_err());
+ assert!(parse(b"\x1b_ratty;i;d;id=1;pid=2\x1b\\").is_err());
+ }
+
+ #[test]
+ fn rejects_bad_terminator_inside_bitmap_namespace() {
+ assert!(parse(b"\x1b_ratty;i;s").is_err());
+ assert!(parse(b"\x1b_ratty;i;s\x1bX").is_err());
+ }
+
+ #[test]
+ fn decodes_one_shot_png_registration_and_replies_only_to_support() {
+ let mut state = BitmapSurfaceState::default();
+
+ assert_eq!(
+ state
+ .apply(BitmapOperation::SupportQuery)
+ .expect("valid bitmap test fixture should succeed"),
+ Some(support_reply())
+ );
+ assert!(!state.is_dirty());
+ assert_eq!(
+ state
+ .apply(register_chunk(1, PNG_2X2, false))
+ .expect("valid bitmap test fixture should succeed"),
+ None
+ );
+
+ let bitmap = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!((bitmap.width, bitmap.height), (2, 2));
+ assert_eq!(bitmap.rgba, RGBA_2X2);
+ assert!(bitmap.handle.is_none());
+ assert!(state.is_dirty());
+ }
+
+ #[test]
+ fn assembles_chunked_png_and_requires_matching_metadata() {
+ let mut state = BitmapSurfaceState::default();
+ let split = 31;
+ state
+ .apply(register_chunk(1, &PNG_2X2[..split], true))
+ .expect("valid bitmap test fixture should succeed");
+ let mismatched = BitmapOperation::Register(BitmapRegisterChunk {
+ bitmap_id: 1,
+ format: Some("png".into()),
+ source: Some("payload".into()),
+ name: Some("different.png".into()),
+ more: true,
+ data: vec![9],
+ });
+ assert!(state.apply(mismatched).is_err());
+ state
+ .apply(registration_continuation(1, &PNG_2X2[split..], false))
+ .expect("valid bitmap test fixture should succeed");
+
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ RGBA_2X2
+ );
+ assert!(state.pending_registrations.is_empty());
+ }
+
+ #[test]
+ fn invalid_png_and_registration_overflow_discard_pending_transfer() {
+ let mut state = BitmapSurfaceState::default();
+ state
+ .apply(register_chunk(1, b"not ", true))
+ .expect("valid bitmap test fixture should succeed");
+ assert!(
+ state
+ .apply(registration_continuation(1, b"png", false))
+ .is_err()
+ );
+ assert!(!state.pending_registrations.contains_key(&1));
+ assert!(state.bitmap(1).is_none());
+
+ let oversized = vec![0; MAX_REGISTRATION_BYTES + 1];
+ assert!(state.apply(register_chunk(2, &oversized, true)).is_err());
+ assert!(!state.pending_registrations.contains_key(&2));
+ assert!(state.bitmap(2).is_none());
+ }
+
+ #[test]
+ fn duplicate_bitmap_id_does_not_mutate_existing_state() {
+ let mut state = registered_state();
+ let before = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba
+ .clone();
+
+ assert!(
+ state
+ .apply(register_chunk(1, b"replacement", false))
+ .is_err()
+ );
+
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ before
+ );
+ assert!(!state.is_dirty());
+ }
+
+ #[test]
+ fn placement_requires_bitmap_supports_siblings_and_rejects_duplicate_id() {
+ let mut state = registered_state();
+ assert!(state.apply(placement(99, 10)).is_err());
+ state
+ .apply(placement(1, 10))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(placement(1, 11))
+ .expect("valid bitmap test fixture should succeed");
+ let before = state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .clone();
+
+ assert!(state.apply(placement(1, 10)).is_err());
+
+ assert_eq!(state.placements().count(), 2);
+ assert_eq!(state.placement(10), Some(&before));
+ }
+
+ #[test]
+ fn placement_generations_advance_only_for_successful_new_lifetimes() {
+ let mut state = registered_state();
+ state
+ .apply(placement(1, 10))
+ .expect("valid bitmap test fixture should succeed");
+ let first_generation = state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .generation();
+
+ state
+ .apply(BitmapOperation::Update {
+ placement_id: 10,
+ update: BitmapPlacementUpdate {
+ opacity: Some(0.5),
+ ..BitmapPlacementUpdate::default()
+ },
+ })
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .generation(),
+ first_generation
+ );
+ assert!(state.apply(placement(1, 10)).is_err());
+
+ state
+ .apply(BitmapOperation::DeletePlacement(10))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(placement(1, 10))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .generation(),
+ first_generation + 1
+ );
+ }
+
+ #[test]
+ fn placement_clamps_source_rect_and_rejects_empty_intersection() {
+ let mut state = registered_state();
+ let mut clamped = match placement(1, 10) {
+ BitmapOperation::Place(value) => value,
+ _ => unreachable!(),
+ };
+ clamped.source = Some(SourceRect {
+ x: 1,
+ y: 1,
+ width: u32::MAX,
+ height: 20,
+ });
+ state
+ .apply(BitmapOperation::Place(clamped))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .source,
+ Some(SourceRect {
+ x: 1,
+ y: 1,
+ width: 1,
+ height: 1
+ })
+ );
+
+ let mut empty = match placement(1, 11) {
+ BitmapOperation::Place(value) => value,
+ _ => unreachable!(),
+ };
+ empty.source = Some(SourceRect {
+ x: 2,
+ y: 0,
+ width: 1,
+ height: 1,
+ });
+ assert!(state.apply(BitmapOperation::Place(empty)).is_err());
+ assert!(state.placement(11).is_none());
+ }
+
+ #[test]
+ fn placement_update_is_transactional_and_clamps_opacity() {
+ let mut state = registered_state();
+ state
+ .apply(placement(1, 10))
+ .expect("valid bitmap test fixture should succeed");
+ state.take_dirty();
+ let before = state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .clone();
+
+ let invalid = BitmapPlacementUpdate {
+ row: Some(9),
+ columns: Some(0),
+ rows: Some(5),
+ ..Default::default()
+ };
+ assert!(
+ state
+ .apply(BitmapOperation::Update {
+ placement_id: 10,
+ update: invalid
+ })
+ .is_err()
+ );
+ assert_eq!(state.placement(10), Some(&before));
+ assert!(!state.is_dirty());
+
+ let valid = BitmapPlacementUpdate {
+ row: Some(9),
+ opacity: Some(4.0),
+ ..Default::default()
+ };
+ state
+ .apply(BitmapOperation::Update {
+ placement_id: 10,
+ update: valid,
+ })
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .row,
+ 9
+ );
+ assert_eq!(
+ state
+ .placement(10)
+ .expect("valid bitmap test fixture should succeed")
+ .opacity,
+ 1.0
+ );
+ assert!(
+ state
+ .apply(BitmapOperation::Update {
+ placement_id: 404,
+ update: Default::default()
+ })
+ .is_err()
+ );
+ }
+
+ #[test]
+ fn applies_one_shot_and_chunked_rgba8_frames() {
+ let mut state = registered_state();
+ let first = [7; 16];
+ state
+ .apply(frame_chunk(1, 1, &first, false))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ first
+ );
+
+ let second = [8; 16];
+ state
+ .apply(frame_chunk(1, 2, &second[..7], true))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(frame_continuation(1, 2, &second[7..], false))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ second
+ );
+ assert!(state.pending_frames.is_empty());
+ }
+
+ #[test]
+ fn frame_validates_exact_length_dimensions_and_checked_expected_size() {
+ let mut state = registered_state();
+ let original = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba
+ .clone();
+ assert!(state.apply(frame_chunk(1, 1, &[1; 15], false)).is_err());
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ original
+ );
+
+ let mut wrong_dimensions = match frame_chunk(1, 2, &[2; 16], false) {
+ BitmapOperation::Frame(value) => value,
+ _ => unreachable!(),
+ };
+ wrong_dimensions.width = Some(3);
+ assert!(
+ state
+ .apply(BitmapOperation::Frame(wrong_dimensions))
+ .is_err()
+ );
+
+ let overflow = BitmapFrameChunk {
+ bitmap_id: 1,
+ sequence: 3,
+ format: Some("rgba8".into()),
+ width: Some(u32::MAX),
+ height: Some(u32::MAX),
+ more: true,
+ data: vec![],
+ };
+ assert!(state.apply(BitmapOperation::Frame(overflow)).is_err());
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ original
+ );
+ }
+
+ #[test]
+ fn newer_frame_cancels_incomplete_older_and_rejects_stale_sequences() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(frame_chunk(1, 11, &[2; 16], false))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ [2; 16]
+ );
+ assert!(
+ state
+ .apply(frame_continuation(1, 10, &[1; 12], false))
+ .is_err()
+ );
+ assert!(state.apply(frame_chunk(1, 11, &[3; 16], false)).is_err());
+ assert!(state.apply(frame_chunk(1, 9, &[4; 16], false)).is_err());
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ [2; 16]
+ );
+ }
+
+ #[test]
+ fn malformed_newer_frame_does_not_cancel_an_incomplete_valid_frame() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(
+ state
+ .apply(frame_continuation(1, 11, &[2; 4], true))
+ .is_err()
+ );
+ state
+ .apply(frame_continuation(1, 10, &[1; 12], false))
+ .expect("valid bitmap test fixture should succeed");
+
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ [1; 16]
+ );
+ }
+
+ #[test]
+ fn invalid_base64_continuation_discards_matching_pending_frame() {
+ let mut state = registered_state();
+ let original = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba
+ .clone();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ let result = state
+ .consume_and_apply(b"\x1b_ratty;i;f;id=1;seq=10;more=0;%%%\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(result.is_err());
+ assert!(!state.pending_frames.contains_key(&1));
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ original
+ );
+ }
+
+ #[test]
+ fn invalid_base64_newer_first_chunk_cancels_older_pending_frame() {
+ let mut state = registered_state();
+ let original = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba
+ .clone();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ let result = state
+ .consume_and_apply(b"\x1b_ratty;i;f;id=1;seq=11;fmt=rgba8;w=2;h=2;more=0;%%%\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(result.is_err());
+ assert!(!state.pending_frames.contains_key(&1));
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ original
+ );
+ }
+
+ #[test]
+ fn invalid_base64_newer_chunk_without_metadata_preserves_older_pending_frame() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ let result = state
+ .consume_and_apply(b"\x1b_ratty;i;f;id=1;seq=11;more=0;%%%\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(result.is_err());
+ assert_eq!(
+ state
+ .pending_frames
+ .get(&1)
+ .expect("valid bitmap test fixture should succeed")
+ .sequence,
+ 10
+ );
+ }
+
+ #[test]
+ fn invalid_base64_newer_chunk_with_wrong_dimensions_preserves_older_pending_frame() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 10, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ let result = state
+ .consume_and_apply(b"\x1b_ratty;i;f;id=1;seq=11;fmt=rgba8;w=3;h=2;more=0;%%%\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(result.is_err());
+ assert_eq!(
+ state
+ .pending_frames
+ .get(&1)
+ .expect("valid bitmap test fixture should succeed")
+ .sequence,
+ 10
+ );
+ }
+
+ #[test]
+ fn invalid_base64_stale_frame_does_not_cancel_newer_pending_frame() {
+ let mut state = registered_state();
+ state
+ .apply(frame_chunk(1, 11, &[1; 4], true))
+ .expect("valid bitmap test fixture should succeed");
+
+ let result = state
+ .consume_and_apply(b"\x1b_ratty;i;f;id=1;seq=10;more=0;%%%\x1b\\")
+ .expect("valid bitmap test fixture should succeed");
+
+ assert!(result.is_err());
+ assert_eq!(
+ state
+ .pending_frames
+ .get(&1)
+ .expect("valid bitmap test fixture should succeed")
+ .sequence,
+ 11
+ );
+ }
+
+ #[test]
+ fn corrupt_frame_discards_transfer_and_preserves_last_valid_pixels() {
+ let mut state = registered_state();
+ let original = state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba
+ .clone();
+ state
+ .apply(frame_chunk(1, 1, &[1; 12], true))
+ .expect("valid bitmap test fixture should succeed");
+ assert!(
+ state
+ .apply(frame_continuation(1, 1, &[2; 8], true))
+ .is_err()
+ );
+
+ assert!(!state.pending_frames.contains_key(&1));
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ original
+ );
+ state
+ .apply(frame_chunk(1, 2, &[3; 16], false))
+ .expect("valid bitmap test fixture should succeed");
+ assert_eq!(
+ state
+ .bitmap(1)
+ .expect("valid bitmap test fixture should succeed")
+ .rgba,
+ [3; 16]
+ );
+ }
+
+ #[test]
+ fn deletes_are_idempotent_and_bitmap_delete_cascades() {
+ let mut state = registered_state();
+ state
+ .apply(placement(1, 10))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(placement(1, 11))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(BitmapOperation::DeletePlacement(10))
+ .expect("valid bitmap test fixture should succeed");
+ assert!(state.placement(10).is_none());
+ assert!(state.placement(11).is_some());
+ assert!(state.bitmap(1).is_some());
+
+ state
+ .apply(BitmapOperation::DeletePlacement(404))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(BitmapOperation::DeleteBitmap(404))
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(BitmapOperation::Ignored)
+ .expect("valid bitmap test fixture should succeed");
+ state
+ .apply(BitmapOperation::DeleteBitmap(1))
+ .expect("valid bitmap test fixture should succeed");
+ assert!(state.bitmap(1).is_none());
+ assert!(state.placement(11).is_none());
+ assert_eq!(state.bitmaps().count(), 0);
+ assert_eq!(state.placements().count(), 0);
+ }
+
+ #[test]
+ fn deleting_unknown_bitmap_aborts_its_pending_registration() {
+ let mut state = BitmapSurfaceState::default();
+ state
+ .apply(register_chunk(42, &PNG_2X2[..20], true))
+ .expect("first registration chunk should remain pending");
+
+ state
+ .apply(BitmapOperation::DeleteBitmap(42))
+ .expect("deleting an unknown bitmap is a no-op");
+
+ assert!(!state.pending_registrations.contains_key(&42));
+ assert!(
+ state
+ .apply(registration_continuation(42, &PNG_2X2[20..], false))
+ .is_err()
+ );
+ state
+ .apply(register_chunk(42, PNG_2X2, false))
+ .expect("a fresh registration should recover the slot");
+ assert!(state.bitmap(42).is_some());
+ }
+
+ #[test]
+ fn stale_pending_bitmap_transfer_expires_and_releases_its_slot() {
+ let mut state = BitmapSurfaceState::default();
+ state.limits.max_pending_transfers = 1;
+ state
+ .apply(register_chunk(42, &PNG_2X2[..20], true))
+ .expect("first registration chunk should remain pending");
+ state
+ .pending_registrations
+ .get_mut(&42)
+ .expect("registration chunk must remain pending")
+ .last_touched = Instant::now() - BITMAP_INCOMPLETE_TIMEOUT - Duration::from_secs(1);
+
+ state
+ .apply(BitmapOperation::SupportQuery)
+ .expect("support query should trigger expiration without failing");
+ assert!(state.pending_registrations.is_empty());
+ state
+ .apply(register_chunk(7, &PNG_2X2[..20], true))
+ .expect("expired transfer must release its slot");
+ }
+
+ #[test]
+ fn rejects_png_dimensions_above_configured_limit() {
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_image_width: 1,
+ ..BitmapLimits::default()
+ });
+
+ assert!(state.apply(register_chunk(1, PNG_2X2, false)).is_err());
+ assert!(state.bitmap(1).is_none());
+
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_image_height: 1,
+ ..BitmapLimits::default()
+ });
+ assert!(state.apply(register_chunk(2, PNG_2X2, false)).is_err());
+ assert!(state.bitmap(2).is_none());
+ }
+
+ #[test]
+ fn rejects_png_above_configured_decoded_byte_limit() {
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_bitmap_bytes: 15,
+ ..BitmapLimits::default()
+ });
+
+ assert!(state.apply(register_chunk(1, PNG_2X2, false)).is_err());
+ assert!(state.bitmap(1).is_none());
+ }
+
+ #[test]
+ fn resident_budget_survives_upload_and_recovers_after_delete() {
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_total_bitmap_bytes: 16,
+ ..BitmapLimits::default()
+ });
+ state
+ .apply(register_chunk(1, PNG_2X2, false))
+ .expect("first bitmap should fit the resident budget");
+ assert!(
+ state
+ .bitmap_mut(1)
+ .expect("registered bitmap")
+ .take_pending_rgba()
+ .is_some()
+ );
+
+ assert!(state.apply(register_chunk(2, PNG_2X2, false)).is_err());
+ assert!(state.bitmap(2).is_none());
+
+ state
+ .apply(BitmapOperation::DeleteBitmap(1))
+ .expect("bitmap deletion should release its resident budget");
+ state
+ .apply(register_chunk(2, PNG_2X2, false))
+ .expect("released resident budget should be reusable");
+ }
+
+ #[test]
+ fn bitmap_count_limit_recovers_after_delete() {
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_bitmaps: 1,
+ ..BitmapLimits::default()
+ });
+ state
+ .apply(register_chunk(1, PNG_2X2, false))
+ .expect("first bitmap should fit the count limit");
+
+ assert!(state.apply(register_chunk(2, PNG_2X2, false)).is_err());
+ assert!(state.bitmap(2).is_none());
+
+ state
+ .apply(BitmapOperation::DeleteBitmap(1))
+ .expect("bitmap deletion should release the count limit");
+ state
+ .apply(register_chunk(2, PNG_2X2, false))
+ .expect("released bitmap slot should be reusable");
+ }
+
+ #[test]
+ fn placement_count_limit_recovers_after_delete() {
+ let mut state = BitmapSurfaceState::with_limits(BitmapLimits {
+ max_placements: 1,
+ ..BitmapLimits::default()
+ });
+ state
+ .apply(register_chunk(1, PNG_2X2, false))
+ .expect("bitmap registration should succeed");
+ state
+ .apply(placement(1, 1))
+ .expect("first placement should fit the count limit");
+
+ assert!(state.apply(placement(1, 2)).is_err());
+ assert!(state.placement(2).is_none());
+
+ state
+ .apply(BitmapOperation::DeletePlacement(1))
+ .expect("placement deletion should release the count limit");
+ state
+ .apply(placement(1, 2))
+ .expect("released placement slot should be reusable");
+ }
+
+ #[test]
+ fn pending_byte_budget_is_shared_across_registrations_and_frames() {
+ let mut state = registered_state();
+ state.limits.max_pending_bytes = 7;
+ state
+ .apply(frame_chunk(1, 1, &[1; 4], true))
+ .expect("first pending frame should fit the byte budget");
+
+ assert!(state.apply(register_chunk(2, &[2; 4], true)).is_err());
+ assert!(!state.pending_registrations.contains_key(&2));
+ assert!(state.pending_frames.contains_key(&1));
+ }
+
+ #[test]
+ fn pending_transfer_cap_is_shared_and_recovers_after_completion() {
+ let mut state = registered_state();
+ state.limits.max_pending_transfers = 2;
+ state
+ .apply(frame_chunk(1, 1, &[1; 4], true))
+ .expect("first pending transfer should fit");
+ state
+ .apply(register_chunk(2, &[2; 4], true))
+ .expect("second pending transfer should fit");
+
+ assert!(state.apply(register_chunk(3, &[3; 4], true)).is_err());
+ state
+ .apply(frame_continuation(1, 1, &[1; 12], false))
+ .expect("completing a frame should release one transfer slot");
+ state
+ .apply(register_chunk(3, &[3; 4], true))
+ .expect("released transfer slot should be reusable");
+ }
+}
diff --git a/src/bitmap_material.rs b/src/bitmap_material.rs
new file mode 100644
index 0000000..6ccc8ae
--- /dev/null
+++ b/src/bitmap_material.rs
@@ -0,0 +1,264 @@
+//! Rendering material and layout math for bitmap-surface placements.
+
+use bevy::asset::uuid_handle;
+use bevy::math::{UVec2, Vec2};
+use bevy::prelude::{Asset, Handle, Image, TypePath};
+use bevy::render::render_resource::{AsBindGroup, ShaderType};
+use bevy::shader::{Shader, ShaderRef};
+use bevy::sprite_render::{AlphaMode2d, Material2d};
+
+use crate::bitmap::{BitmapFit, SourceRect};
+
+/// Handle for the embedded bitmap-surface shader.
+pub(crate) const BITMAP_SURFACE_SHADER: Handle =
+ uuid_handle!("226f825e-49b6-4cae-bfc4-a03efadfb255");
+
+/// A material for one bitmap placement.
+///
+/// Placements keep independent parameters while sharing the same `Image`
+/// handle, including when their filtering modes differ.
+#[derive(Asset, TypePath, AsBindGroup, Clone)]
+pub struct BitmapSurfaceMaterial {
+ /// Shared bitmap image.
+ #[texture(0)]
+ pub image: Handle,
+ /// Crop, fit, filtering, and opacity parameters for this placement.
+ #[uniform(1)]
+ pub params: BitmapSurfaceUniform,
+}
+
+/// Shader parameters resolved for one bitmap placement.
+#[derive(Clone, Copy, Debug, PartialEq, ShaderType)]
+pub struct BitmapSurfaceUniform {
+ /// Top-left normalized source coordinate.
+ pub uv_min: Vec2,
+ /// Bottom-right normalized source coordinate.
+ pub uv_max: Vec2,
+ /// Placement opacity in the inclusive range `[0, 1]`.
+ pub opacity: f32,
+ /// `0` for nearest-neighbor filtering or `1` for linear filtering.
+ pub filter_mode: u32,
+ /// Top-left normalized destination content bound.
+ pub content_min: Vec2,
+ /// Bottom-right normalized destination content bound.
+ pub content_max: Vec2,
+ /// Top-left normalized terminal-viewport clip bound.
+ pub clip_min: Vec2,
+ /// Bottom-right normalized terminal-viewport clip bound.
+ pub clip_max: Vec2,
+}
+
+impl Material2d for BitmapSurfaceMaterial {
+ fn fragment_shader() -> ShaderRef {
+ BITMAP_SURFACE_SHADER.into()
+ }
+
+ fn alpha_mode(&self) -> AlphaMode2d {
+ AlphaMode2d::Blend
+ }
+}
+
+/// Resolved normalized crop and destination-content bounds.
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct ResolvedBitmapLayout {
+ /// Top-left normalized source coordinate.
+ pub uv_min: Vec2,
+ /// Bottom-right normalized source coordinate.
+ pub uv_max: Vec2,
+ /// Top-left normalized destination content bound.
+ pub content_min: Vec2,
+ /// Bottom-right normalized destination content bound.
+ pub content_max: Vec2,
+}
+
+/// Resolves source cropping and fit into normalized shader coordinates.
+///
+/// Source rectangles are clamped to the bitmap bounds. Protocol state rejects
+/// empty sources and destinations before calling this function; zero-sized
+/// input defensively resolves to an empty layout.
+pub fn resolve_bitmap_layout(
+ bitmap_size: UVec2,
+ source: Option,
+ destination_pixels: Vec2,
+ fit: BitmapFit,
+) -> ResolvedBitmapLayout {
+ if bitmap_size.x == 0
+ || bitmap_size.y == 0
+ || destination_pixels.x <= 0.0
+ || destination_pixels.y <= 0.0
+ {
+ return ResolvedBitmapLayout::default();
+ }
+
+ let (source_min, source_max) = clamped_source(bitmap_size, source);
+ let source_size = source_max - source_min;
+ if source_size.x <= 0.0 || source_size.y <= 0.0 {
+ return ResolvedBitmapLayout::default();
+ }
+
+ let bitmap_size = bitmap_size.as_vec2();
+ let mut layout = ResolvedBitmapLayout {
+ uv_min: source_min / bitmap_size,
+ uv_max: source_max / bitmap_size,
+ content_min: Vec2::ZERO,
+ content_max: Vec2::ONE,
+ };
+
+ match fit {
+ BitmapFit::Fill => {}
+ BitmapFit::Contain => {
+ let scale =
+ (destination_pixels.x / source_size.x).min(destination_pixels.y / source_size.y);
+ let content_size = source_size * scale / destination_pixels;
+ layout.content_min = (Vec2::ONE - content_size) * 0.5;
+ layout.content_max = layout.content_min + content_size;
+ }
+ BitmapFit::Cover => {
+ let scale =
+ (destination_pixels.x / source_size.x).max(destination_pixels.y / source_size.y);
+ let visible_source_size = destination_pixels / scale;
+ let crop = (source_size - visible_source_size) * 0.5;
+ layout.uv_min = (source_min + crop) / bitmap_size;
+ layout.uv_max = (source_max - crop) / bitmap_size;
+ }
+ }
+
+ layout
+}
+
+fn clamped_source(bitmap_size: UVec2, source: Option) -> (Vec2, Vec2) {
+ let Some(source) = source else {
+ return (Vec2::ZERO, bitmap_size.as_vec2());
+ };
+
+ let min_x = source.x.min(bitmap_size.x);
+ let min_y = source.y.min(bitmap_size.y);
+ let max_x = source.x.saturating_add(source.width).min(bitmap_size.x);
+ let max_y = source.y.saturating_add(source.height).min(bitmap_size.y);
+ (
+ Vec2::new(min_x as f32, min_y as f32),
+ Vec2::new(max_x as f32, max_y as f32),
+ )
+}
+
+#[cfg(test)]
+mod tests {
+ use bevy::math::{UVec2, Vec2};
+
+ use super::*;
+ use crate::bitmap::{BitmapFit, SourceRect};
+
+ fn assert_vec2(actual: Vec2, expected: Vec2) {
+ assert!(
+ actual.abs_diff_eq(expected, 1.0e-6),
+ "expected {expected:?}, got {actual:?}"
+ );
+ }
+
+ #[test]
+ fn fill_maps_the_selected_source_to_the_entire_destination() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(400, 200),
+ None,
+ Vec2::new(300.0, 300.0),
+ BitmapFit::Fill,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::ZERO);
+ assert_vec2(layout.uv_max, Vec2::ONE);
+ assert_vec2(layout.content_min, Vec2::ZERO);
+ assert_vec2(layout.content_max, Vec2::ONE);
+ }
+
+ #[test]
+ fn contain_letterboxes_landscape_content_vertically() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(400, 200),
+ None,
+ Vec2::new(300.0, 300.0),
+ BitmapFit::Contain,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::ZERO);
+ assert_vec2(layout.uv_max, Vec2::ONE);
+ assert_vec2(layout.content_min, Vec2::new(0.0, 0.25));
+ assert_vec2(layout.content_max, Vec2::new(1.0, 0.75));
+ }
+
+ #[test]
+ fn contain_letterboxes_portrait_content_horizontally() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(200, 400),
+ None,
+ Vec2::new(300.0, 300.0),
+ BitmapFit::Contain,
+ );
+
+ assert_vec2(layout.content_min, Vec2::new(0.25, 0.0));
+ assert_vec2(layout.content_max, Vec2::new(0.75, 1.0));
+ }
+
+ #[test]
+ fn cover_crops_landscape_content_symmetrically() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(400, 200),
+ None,
+ Vec2::new(300.0, 300.0),
+ BitmapFit::Cover,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::new(0.25, 0.0));
+ assert_vec2(layout.uv_max, Vec2::new(0.75, 1.0));
+ assert_vec2(layout.content_min, Vec2::ZERO);
+ assert_vec2(layout.content_max, Vec2::ONE);
+ }
+
+ #[test]
+ fn cover_crops_portrait_content_symmetrically() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(200, 400),
+ None,
+ Vec2::new(300.0, 300.0),
+ BitmapFit::Cover,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::new(0.0, 0.25));
+ assert_vec2(layout.uv_max, Vec2::new(1.0, 0.75));
+ }
+
+ #[test]
+ fn explicit_crop_is_normalized_against_the_full_bitmap() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(400, 200),
+ Some(SourceRect {
+ x: 100,
+ y: 50,
+ width: 200,
+ height: 100,
+ }),
+ Vec2::new(200.0, 100.0),
+ BitmapFit::Fill,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::new(0.25, 0.25));
+ assert_vec2(layout.uv_max, Vec2::new(0.75, 0.75));
+ }
+
+ #[test]
+ fn source_crop_is_clamped_to_bitmap_bounds() {
+ let layout = resolve_bitmap_layout(
+ UVec2::new(400, 200),
+ Some(SourceRect {
+ x: 300,
+ y: 100,
+ width: 500,
+ height: 500,
+ }),
+ Vec2::new(100.0, 100.0),
+ BitmapFit::Fill,
+ );
+
+ assert_vec2(layout.uv_min, Vec2::new(0.75, 0.5));
+ assert_vec2(layout.uv_max, Vec2::ONE);
+ }
+}
diff --git a/src/config.rs b/src/config.rs
index 2ec5c0e..36b2404 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -30,6 +30,8 @@ pub struct AppConfig {
pub window: WindowConfig,
/// Terminal grid settings.
pub terminal: TerminalConfig,
+ /// Bitmap surface resource limits.
+ pub bitmap: BitmapConfig,
/// Shell spawning settings.
pub shell: ShellConfig,
/// Extra environment variables.
@@ -44,6 +46,43 @@ pub struct AppConfig {
pub cursor: CursorConfig,
}
+/// Bitmap surface resource limits.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(default)]
+pub struct BitmapConfig {
+ /// Maximum number of registered bitmaps.
+ pub max_bitmaps: usize,
+ /// Maximum number of active bitmap placements.
+ pub max_placements: usize,
+ /// Maximum decoded bitmap width in pixels.
+ pub max_image_width: u32,
+ /// Maximum decoded bitmap height in pixels.
+ pub max_image_height: u32,
+ /// Maximum decoded bytes owned by one bitmap.
+ pub max_bitmap_bytes: u64,
+ /// Maximum decoded bytes owned by all registered bitmaps.
+ pub max_total_bitmap_bytes: u64,
+ /// Maximum decoded payload bytes retained across incomplete transfers.
+ pub max_pending_bytes: u64,
+ /// Maximum number of incomplete registrations and frames.
+ pub max_pending_transfers: usize,
+}
+
+impl Default for BitmapConfig {
+ fn default() -> Self {
+ Self {
+ max_bitmaps: 1_024,
+ max_placements: 4_096,
+ max_image_width: 8_192,
+ max_image_height: 8_192,
+ max_bitmap_bytes: 64 * 1024 * 1024,
+ max_total_bitmap_bytes: 256 * 1024 * 1024,
+ max_pending_bytes: 64 * 1024 * 1024,
+ max_pending_transfers: 16,
+ }
+ }
+}
+
impl AppConfig {
/// Loads the application configuration.
///
@@ -614,4 +653,31 @@ action = "Toggle3DMode"
slots.sort_unstable();
assert_eq!(slots, (0..10).collect::>());
}
+
+ #[test]
+ fn parses_bitmap_resource_limits() {
+ let config: AppConfig = toml::from_str(
+ r#"
+[bitmap]
+max_bitmaps = 12
+max_placements = 34
+max_image_width = 1024
+max_image_height = 768
+max_bitmap_bytes = 4194304
+max_total_bitmap_bytes = 16777216
+max_pending_bytes = 2097152
+max_pending_transfers = 3
+"#,
+ )
+ .expect("bitmap resource limits should deserialize");
+
+ assert_eq!(config.bitmap.max_bitmaps, 12);
+ assert_eq!(config.bitmap.max_placements, 34);
+ assert_eq!(config.bitmap.max_image_width, 1024);
+ assert_eq!(config.bitmap.max_image_height, 768);
+ assert_eq!(config.bitmap.max_bitmap_bytes, 4_194_304);
+ assert_eq!(config.bitmap.max_total_bitmap_bytes, 16_777_216);
+ assert_eq!(config.bitmap.max_pending_bytes, 2_097_152);
+ assert_eq!(config.bitmap.max_pending_transfers, 3);
+ }
}
diff --git a/src/inline.rs b/src/inline.rs
index a6d6e45..e9a05e5 100644
--- a/src/inline.rs
+++ b/src/inline.rs
@@ -1,25 +1,50 @@
//! Inline object state and APC handling.
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
use std::path::Path;
+use std::time::{Duration, Instant};
use bevy::prelude::*;
+use crate::bitmap::{
+ BITMAP_APC_HEADER_ALLOWANCE, BitmapLimits, BitmapOperation, BitmapSurfaceState,
+ MAX_BITMAP_APC_BYTES, max_base64_encoded_bytes,
+};
+use crate::bitmap_material::{BitmapSurfaceMaterial, BitmapSurfaceUniform};
use crate::camera::{OptionalVec3, TerminalCameraUpdate};
-use crate::kitty::{KittyOperation, KittyParserState, refresh_kitty_placeholder_anchors};
+use crate::kitty::KittyRenderCache;
use crate::model::{
- ObjectLoadOptions, load_object_source_from_bytes_with_options, load_object_source_with_options,
+ ObjectLoadOptions, ObjectSource, load_rgp_object_source_from_bytes_with_options,
+ load_rgp_object_source_with_options, object_source_resident_bytes,
+ remove_rgp_materialized_source,
};
+use crate::paths::runtime_asset_root;
use crate::rgp::{
- RgpOperation, RgpPlacementStyle, RgpPlacementUpdate, RgpRegisterSource,
- consume_sequence as consume_rgp_sequence, support_reply,
+ RGP_APC_START, RGP_CONTROL_HEADER_LIMIT, RgpOperation, RgpPlacementStyle, RgpPlacementUpdate,
+ RgpRegisterSource, consume_sequence_with_payload_limit as consume_rgp_sequence, support_reply,
};
use crate::runtime::TerminalRuntime;
-use crate::vt::{self, VtTerminal};
+use crate::vt::VtTerminal;
+use rio_vt::crosswords::external_placement::{
+ ExternalPlacement, ExternalPlacementErasePolicy, ExternalPlacementScreen,
+ ExternalPlacementScrollPolicy,
+};
const APC_START: &[u8] = b"\x1b_";
+const KITTY_APC_START: &[u8] = b"\x1b_G";
const ST: &[u8] = b"\x1b\\";
const C1_ST: u8 = 0x9c;
+const BITMAP_PLACEMENT_NAMESPACE: u64 = 1 << 63;
+const RGP_PLACEMENT_NAMESPACE: u64 = 1 << 62;
+const RGP_INCOMPLETE_TIMEOUT: Duration = Duration::from_secs(10);
+
+fn forwarded_kitty_apc_limit(max_decoded_bytes: u64) -> usize {
+ KITTY_APC_START
+ .len()
+ .saturating_add(BITMAP_APC_HEADER_ALLOWANCE)
+ .saturating_add(max_base64_encoded_bytes(max_decoded_bytes))
+ .saturating_add(ST.len())
+}
/// Marker for 2D inline object sprites.
#[derive(Component)]
@@ -40,24 +65,14 @@ pub(crate) struct InlineKittyPlaneLayout {
pub local_width: f32,
/// Normalized height within the terminal plane.
pub local_height: f32,
+ /// Signed offset from the terminal surface derived from Kitty z-index.
+ pub depth_offset: f32,
/// Horizontal mesh subdivision count.
pub x_segments: u32,
/// Vertical mesh subdivision count.
pub y_segments: u32,
}
-/// Cached GPU assets for a Kitty image plane attached to the terminal surface.
-pub(crate) struct KittyPlaneCache {
- /// Cached horizontal mesh subdivision count.
- pub x_segments: u32,
- /// Cached vertical mesh subdivision count.
- pub y_segments: u32,
- /// Cached plane mesh handle.
- pub mesh: Handle,
- /// Cached plane material handle.
- pub material: Handle,
-}
-
/// Marker for RGP-backed inline objects.
#[derive(Component)]
pub struct TerminalRgpObject {
@@ -65,21 +80,108 @@ pub struct TerminalRgpObject {
pub object_id: u32,
}
+/// Marker identifying one rendered bitmap-surface placement.
+#[derive(Component, Clone, Copy, Debug, PartialEq, Eq)]
+pub struct TerminalBitmapPlacement {
+ /// Globally unique placement identifier.
+ pub placement_id: u32,
+ /// Registered bitmap identifier shared by this placement.
+ pub bitmap_id: u32,
+}
+
+/// Stable Bevy assets owned by one bitmap placement.
+pub(crate) struct BitmapPlacementRenderCache {
+ /// Placement lifetime rendered by this cache entry.
+ pub(crate) generation: u64,
+ /// Registered bitmap used by the placement.
+ pub(crate) bitmap_id: u32,
+ /// Stable render entity.
+ pub(crate) entity: Entity,
+ /// Stable destination quad mesh.
+ pub(crate) mesh: Handle,
+ /// Stable per-placement material.
+ pub(crate) material: Handle,
+ /// Last values synchronized into the stable render objects.
+ pub(crate) state: BitmapPlacementRenderState,
+}
+
+/// Render-facing placement values used to avoid dirtying unchanged Bevy assets.
+#[derive(Clone)]
+pub(crate) struct BitmapPlacementRenderState {
+ pub(crate) image: Handle,
+ pub(crate) destination: Vec2,
+ pub(crate) transform: Transform,
+ pub(crate) uniform: BitmapSurfaceUniform,
+}
+
+/// Renderer-side identities retained across protocol updates.
+#[derive(Default)]
+pub(crate) struct BitmapRenderCache {
+ /// Stable image handles keyed by bitmap ID.
+ pub(crate) images: HashMap>,
+ /// Stable entity and material handles keyed by placement ID.
+ pub(crate) placements: HashMap,
+}
+
/// Inline object registry and anchor state.
#[derive(Resource, Default)]
pub struct TerminalInlineObjects {
pending_bytes: Vec,
+ discarding_oversized_bitmap_apc: bool,
+ bitmap_discard_saw_escape: bool,
+ forwarded_kitty_apc_limit: Option,
+ discarding_oversized_forwarded_kitty_apc: bool,
+ forwarded_kitty_discard_saw_escape: bool,
+ rgp_apc_limit: Option,
+ discarding_oversized_rgp_apc: bool,
+ rgp_discard_saw_escape: bool,
+ rgp_max_payload_bytes: Option,
+ rgp_max_pending_bytes: Option,
+ rgp_max_pending_transfers: Option,
+ rgp_max_objects: Option,
+ rgp_max_total_bytes: Option,
pending_rgp_payloads: HashMap,
- kitty: KittyParserState,
+ rgp_object_bytes: HashMap,
+ pub(crate) dirty_rgp_objects: HashSet,
+ pub(crate) bitmap: BitmapSurfaceState,
+ pub(crate) bitmap_render: BitmapRenderCache,
+ pub(crate) kitty_render: KittyRenderCache,
dirty: bool,
last_viewport_size: Vec2,
last_cols: u16,
last_rows: u16,
+ last_external_revision: u64,
+ last_external_viewport_top: i64,
+ last_external_screen: Option,
pub(crate) objects: HashMap,
pub(crate) anchors: HashMap,
}
impl TerminalInlineObjects {
+ pub(crate) fn with_bitmap_limits(limits: BitmapLimits) -> Self {
+ let forwarded_kitty_apc_limit = forwarded_kitty_apc_limit(limits.max_bitmap_bytes);
+ let rgp_max_payload_bytes = usize::try_from(limits.max_bitmap_bytes).unwrap_or(usize::MAX);
+ let rgp_max_pending_bytes = usize::try_from(limits.max_pending_bytes).unwrap_or(usize::MAX);
+ let rgp_apc_limit = RGP_APC_START
+ .len()
+ .saturating_add(RGP_CONTROL_HEADER_LIMIT)
+ .saturating_add(max_base64_encoded_bytes(limits.max_bitmap_bytes))
+ .saturating_add(ST.len());
+ Self {
+ bitmap: BitmapSurfaceState::with_limits(limits),
+ forwarded_kitty_apc_limit: Some(forwarded_kitty_apc_limit),
+ rgp_apc_limit: Some(rgp_apc_limit),
+ rgp_max_payload_bytes: Some(rgp_max_payload_bytes),
+ rgp_max_pending_bytes: Some(rgp_max_pending_bytes),
+ rgp_max_pending_transfers: Some(limits.max_pending_transfers),
+ rgp_max_objects: Some(limits.max_bitmaps),
+ rgp_max_total_bytes: Some(
+ usize::try_from(limits.max_total_bitmap_bytes).unwrap_or(usize::MAX),
+ ),
+ ..Self::default()
+ }
+ }
+
/// Consumes PTY output and extracts inline object control sequences.
pub fn consume_pty_output(
&mut self,
@@ -88,7 +190,144 @@ impl TerminalInlineObjects {
camera_updates: &mut Vec,
terminal_output: &mut bool,
) -> Vec> {
- self.pending_bytes.extend_from_slice(chunk);
+ self.consume_pty_output_with_limit(
+ chunk,
+ runtime,
+ camera_updates,
+ terminal_output,
+ MAX_BITMAP_APC_BYTES,
+ )
+ }
+
+ #[cfg(test)]
+ fn consume_pty_output_with_bitmap_limit(
+ &mut self,
+ chunk: &[u8],
+ runtime: &mut TerminalRuntime,
+ bitmap_apc_limit: usize,
+ ) -> Vec> {
+ let mut camera_updates = Vec::new();
+ let mut terminal_output = false;
+ self.consume_pty_output_with_limit(
+ chunk,
+ runtime,
+ &mut camera_updates,
+ &mut terminal_output,
+ bitmap_apc_limit,
+ )
+ }
+
+ fn consume_pty_output_with_limit(
+ &mut self,
+ mut chunk: &[u8],
+ runtime: &mut TerminalRuntime,
+ camera_updates: &mut Vec,
+ terminal_output: &mut bool,
+ bitmap_apc_limit: usize,
+ ) -> Vec> {
+ const INGEST_BLOCK_BYTES: usize = 64 * 1024;
+ let forwarded_kitty_apc_limit = self
+ .forwarded_kitty_apc_limit
+ .unwrap_or(MAX_BITMAP_APC_BYTES);
+ let rgp_apc_limit = self.rgp_apc_limit.unwrap_or(MAX_BITMAP_APC_BYTES);
+
+ self.evict_stale_rgp_payloads();
+
+ let mut replies = Vec::new();
+ while !chunk.is_empty() {
+ if self.discarding_oversized_bitmap_apc {
+ let Some(consumed) = self.discard_oversized_bitmap_bytes(chunk) else {
+ return replies;
+ };
+ self.discarding_oversized_bitmap_apc = false;
+ self.bitmap_discard_saw_escape = false;
+ chunk = &chunk[consumed..];
+ continue;
+ }
+ if self.discarding_oversized_forwarded_kitty_apc {
+ let Some(consumed) = self.discard_oversized_forwarded_kitty_bytes(chunk) else {
+ return replies;
+ };
+ self.discarding_oversized_forwarded_kitty_apc = false;
+ self.forwarded_kitty_discard_saw_escape = false;
+ chunk = &chunk[consumed..];
+ continue;
+ }
+ if self.discarding_oversized_rgp_apc {
+ let Some(consumed) = self.discard_oversized_rgp_bytes(chunk) else {
+ return replies;
+ };
+ self.discarding_oversized_rgp_apc = false;
+ self.rgp_discard_saw_escape = false;
+ chunk = &chunk[consumed..];
+ continue;
+ }
+
+ let block_limit = if self
+ .pending_bytes
+ .starts_with(crate::bitmap::BITMAP_APC_START)
+ {
+ bitmap_apc_limit.saturating_sub(self.pending_bytes.len())
+ } else if self.pending_bytes.starts_with(KITTY_APC_START) {
+ forwarded_kitty_apc_limit.saturating_sub(self.pending_bytes.len())
+ } else if self.pending_bytes.starts_with(RGP_APC_START) {
+ rgp_apc_limit.saturating_sub(self.pending_bytes.len())
+ } else {
+ INGEST_BLOCK_BYTES
+ .min(bitmap_apc_limit.max(1))
+ .min(forwarded_kitty_apc_limit.max(1))
+ .min(rgp_apc_limit.max(1))
+ };
+ if block_limit == 0 {
+ if self.pending_bytes.starts_with(KITTY_APC_START) {
+ self.begin_oversized_forwarded_kitty_discard();
+ runtime
+ .term
+ .graphics
+ .kitty_chunking_state
+ .clear_incomplete_transfers();
+ } else if self.pending_bytes.starts_with(RGP_APC_START) {
+ self.begin_oversized_rgp_discard();
+ } else {
+ self.begin_oversized_bitmap_discard();
+ }
+ continue;
+ }
+ let take = chunk.len().min(INGEST_BLOCK_BYTES).min(block_limit);
+ self.pending_bytes.extend_from_slice(&chunk[..take]);
+ chunk = &chunk[take..];
+ replies.extend(self.process_pending_bytes(runtime, camera_updates, terminal_output));
+
+ if self
+ .pending_bytes
+ .starts_with(crate::bitmap::BITMAP_APC_START)
+ && self.pending_bytes.len() >= bitmap_apc_limit
+ {
+ self.begin_oversized_bitmap_discard();
+ } else if self.pending_bytes.starts_with(KITTY_APC_START)
+ && self.pending_bytes.len() >= forwarded_kitty_apc_limit
+ {
+ self.begin_oversized_forwarded_kitty_discard();
+ runtime
+ .term
+ .graphics
+ .kitty_chunking_state
+ .clear_incomplete_transfers();
+ } else if self.pending_bytes.starts_with(RGP_APC_START)
+ && self.pending_bytes.len() >= rgp_apc_limit
+ {
+ self.begin_oversized_rgp_discard();
+ }
+ }
+ replies
+ }
+
+ fn process_pending_bytes(
+ &mut self,
+ runtime: &mut TerminalRuntime,
+ camera_updates: &mut Vec,
+ terminal_output: &mut bool,
+ ) -> Vec> {
let mut replies = Vec::new();
let mut cursor = 0;
@@ -101,7 +340,8 @@ impl TerminalInlineObjects {
let keep_from = pending_apc_prefix_start(&self.pending_bytes, cursor);
if cursor < keep_from {
*terminal_output = true;
- runtime.process(&self.pending_bytes[cursor..keep_from]);
+ let terminal_bytes = self.pending_bytes[cursor..keep_from].to_vec();
+ self.forward_to_terminal(&terminal_bytes, runtime, &mut replies);
}
if keep_from < pending_len {
self.pending_bytes.drain(..keep_from);
@@ -113,7 +353,8 @@ impl TerminalInlineObjects {
let start = cursor + start_offset;
if cursor < start {
*terminal_output = true;
- runtime.process(&self.pending_bytes[cursor..start]);
+ let terminal_bytes = self.pending_bytes[cursor..start].to_vec();
+ self.forward_to_terminal(&terminal_bytes, runtime, &mut replies);
}
let payload_start = start + APC_START.len();
@@ -122,76 +363,158 @@ impl TerminalInlineObjects {
return replies;
};
let sequence = self.pending_bytes[start..end].to_vec();
- let (handled, reply) = self.handle_apc_sequence(
- &sequence,
- vt::cursor_position(&runtime.term),
- camera_updates,
- );
+ let (handled, reply) = self.handle_apc_sequence(&sequence, runtime, camera_updates);
if let Some(reply) = reply {
replies.push(reply);
}
if !handled {
*terminal_output = true;
- runtime.process(&sequence);
+ self.forward_to_terminal(&sequence, runtime, &mut replies);
}
cursor = end;
}
}
+ fn forward_to_terminal(
+ &mut self,
+ bytes: &[u8],
+ runtime: &mut TerminalRuntime,
+ replies: &mut Vec>,
+ ) {
+ runtime.process(bytes);
+ replies.extend(runtime.take_replies());
+ self.kitty_render
+ .queue_updates(runtime.take_graphics_updates());
+ self.dirty = true;
+ }
+
+ fn begin_oversized_bitmap_discard(&mut self) {
+ warn!("discarding oversized Ratty Bitmap Surface APC sequence");
+ self.bitmap.abort_all_pending_transfers();
+ self.bitmap_discard_saw_escape = self.pending_bytes.last() == Some(&ST[0]);
+ self.pending_bytes.clear();
+ self.discarding_oversized_bitmap_apc = true;
+ }
+
+ fn discard_oversized_bitmap_bytes(&mut self, bytes: &[u8]) -> Option {
+ for (index, byte) in bytes.iter().copied().enumerate() {
+ if self.bitmap_discard_saw_escape && byte == ST[1] {
+ return Some(index + 1);
+ }
+ if byte == C1_ST {
+ return Some(index + 1);
+ }
+ self.bitmap_discard_saw_escape = byte == ST[0];
+ }
+ None
+ }
+
+ fn begin_oversized_forwarded_kitty_discard(&mut self) {
+ warn!("discarding oversized forwarded Kitty APC sequence");
+ self.forwarded_kitty_discard_saw_escape = self.pending_bytes.last() == Some(&ST[0]);
+ self.pending_bytes.clear();
+ self.discarding_oversized_forwarded_kitty_apc = true;
+ }
+
+ fn discard_oversized_forwarded_kitty_bytes(&mut self, bytes: &[u8]) -> Option {
+ for (index, byte) in bytes.iter().copied().enumerate() {
+ if self.forwarded_kitty_discard_saw_escape && byte == ST[1] {
+ return Some(index + 1);
+ }
+ if byte == C1_ST {
+ return Some(index + 1);
+ }
+ self.forwarded_kitty_discard_saw_escape = byte == ST[0];
+ }
+ None
+ }
+
+ fn begin_oversized_rgp_discard(&mut self) {
+ warn!("discarding oversized Ratty Graphics Protocol APC sequence");
+ self.pending_rgp_payloads.clear();
+ self.rgp_discard_saw_escape = self.pending_bytes.last() == Some(&ST[0]);
+ self.pending_bytes.clear();
+ self.discarding_oversized_rgp_apc = true;
+ }
+
+ fn discard_oversized_rgp_bytes(&mut self, bytes: &[u8]) -> Option {
+ for (index, byte) in bytes.iter().copied().enumerate() {
+ if self.rgp_discard_saw_escape && byte == ST[1] {
+ return Some(index + 1);
+ }
+ if byte == C1_ST {
+ return Some(index + 1);
+ }
+ self.rgp_discard_saw_escape = byte == ST[0];
+ }
+ None
+ }
+
/// Returns whether inline objects need synchronization.
- pub fn needs_sync(&self, viewport_size: Vec2, cols: u16, rows: u16) -> bool {
+ pub fn needs_sync(&self, viewport_size: Vec2, cols: u16, rows: u16, term: &VtTerminal) -> bool {
+ let viewport_top = external_viewport_top(term);
self.dirty
+ || self.bitmap.is_dirty()
+ || self.kitty_render.is_dirty()
|| self.last_viewport_size != viewport_size
|| self.last_cols != cols
|| self.last_rows != rows
+ || self.last_external_revision != term.external_placements_revision()
+ || self.last_external_viewport_top != viewport_top
+ || self.last_external_screen != Some(term.active_external_placement_screen())
}
/// Marks synchronization as complete.
- pub fn finish_sync(&mut self, viewport_size: Vec2, cols: u16, rows: u16) {
+ pub fn finish_sync(&mut self, viewport_size: Vec2, cols: u16, rows: u16, term: &VtTerminal) {
self.dirty = false;
+ self.dirty_rgp_objects.clear();
+ self.bitmap.take_dirty();
+ self.kitty_render.take_dirty();
self.last_viewport_size = viewport_size;
self.last_cols = cols;
self.last_rows = rows;
+ self.last_external_revision = term.external_placements_revision();
+ self.last_external_viewport_top = external_viewport_top(term);
+ self.last_external_screen = Some(term.active_external_placement_screen());
}
- /// Applies upward scroll to anchored objects.
- pub fn apply_scroll(&mut self, rows_scrolled: u16) {
- if rows_scrolled == 0 || self.anchors.is_empty() {
- return;
- }
-
- self.anchors.retain(|object_id, anchor| {
- if self
- .objects
- .get(object_id)
- .is_some_and(|object| !object.scrolls_with_text())
- {
- return true;
- }
- let new_row = anchor.row as i32 - rows_scrolled as i32;
- if new_row + anchor.rows as i32 <= 0 {
- return false;
- }
- anchor.row = new_row.max(0) as u16;
- true
- });
- self.dirty = true;
+ /// Marks only bitmap protocol changes as synchronized.
+ pub(crate) fn finish_bitmap_sync(&mut self) {
+ self.bitmap.take_dirty();
}
- /// Returns whether any anchors need scroll tracking.
- pub fn has_scroll_tracked_anchors(&self) -> bool {
- self.anchors.keys().any(|object_id| {
- self.objects
- .get(object_id)
- .is_some_and(InlineObject::scrolls_with_text)
+ /// Drop renderer-side placement state after the terminal has expired or
+ /// reset its authoritative placement record.
+ pub(crate) fn reconcile_terminal_placements(&mut self, term: &VtTerminal) {
+ let terminal_ids = [
+ ExternalPlacementScreen::Main,
+ ExternalPlacementScreen::Alternate,
+ ]
+ .into_iter()
+ .flat_map(|screen| {
+ term.external_placements(screen)
+ .map(|placement| placement.id)
})
- }
+ .collect::>();
- /// Refreshes placeholder-derived Kitty anchors.
- pub fn refresh_placeholder_anchors(&mut self, term: &VtTerminal) {
- if refresh_kitty_placeholder_anchors(&self.objects, &mut self.anchors, term) {
- self.dirty = true;
+ let stale_bitmaps = self
+ .bitmap
+ .placements()
+ .filter_map(|(placement_id, _)| {
+ (!terminal_ids.contains(&bitmap_external_id(*placement_id)))
+ .then_some(*placement_id)
+ })
+ .collect::>();
+ for placement_id in stale_bitmaps {
+ let _ = self
+ .bitmap
+ .apply(BitmapOperation::DeletePlacement(placement_id));
}
+
+ let before = self.anchors.len();
+ self.anchors
+ .retain(|object_id, _| terminal_ids.contains(&rgp_external_id(*object_id)));
+ self.dirty |= self.anchors.len() != before;
}
fn set_anchor(&mut self, object_id: u32, anchor: InlineAnchor) {
@@ -200,99 +523,198 @@ impl TerminalInlineObjects {
}
fn remove_object(&mut self, object_id: u32) {
- self.objects.remove(&object_id);
+ if let Some(object) = self.objects.remove(&object_id) {
+ remove_materialized_inline_object(&object, None);
+ }
+ self.rgp_object_bytes.remove(&object_id);
self.anchors.remove(&object_id);
self.pending_rgp_payloads.remove(&object_id);
+ self.dirty_rgp_objects.insert(object_id);
self.dirty = true;
}
fn clear_objects(&mut self) {
- self.objects.clear();
+ for (_, object) in self.objects.drain() {
+ remove_materialized_inline_object(&object, None);
+ }
+ self.rgp_object_bytes.clear();
self.anchors.clear();
self.pending_rgp_payloads.clear();
+ self.dirty_rgp_objects.clear();
self.dirty = true;
}
fn handle_apc_sequence(
&mut self,
sequence: &[u8],
- cursor_position: (u16, u16),
+ runtime: &mut TerminalRuntime,
camera_updates: &mut Vec,
) -> (bool, Option>) {
- if let Some(reply) = self.handle_rgp_sequence(sequence, camera_updates) {
- return (true, reply);
+ if let Some(result) = self.bitmap.consume_apply_and_return(sequence) {
+ debug!(bytes = sequence.len(), "received bitmap surface command");
+ return match result {
+ Ok((operation, reply)) => {
+ self.sync_bitmap_operation(&operation, &mut runtime.term);
+ if reply.is_some() {
+ info!("bitmap support query answered: v1");
+ }
+ (true, reply)
+ }
+ Err(error) => {
+ warn!("failed to apply bitmap surface command: {error}");
+ (true, None)
+ }
+ };
}
- let Some(operation) = self.kitty.consume_sequence(sequence, cursor_position) else {
- return (false, None);
- };
+ if let Some(reply) = self.handle_rgp_sequence(sequence, camera_updates, &mut runtime.term) {
+ return (true, reply);
+ }
+ // Kitty and every other terminal APC are forwarded byte-for-byte to
+ // rio-vt, which owns framing, chunk state, replies, image lifetime,
+ // placement mutation, and Unicode-placeholder metadata.
+ (false, None)
+ }
+ pub(crate) fn sync_bitmap_operation(
+ &mut self,
+ operation: &BitmapOperation,
+ term: &mut VtTerminal,
+ ) {
match operation {
- KittyOperation::Pending | KittyOperation::Ignored => (true, None),
- KittyOperation::TransmitOnly { object_id, image } => {
- self.objects
- .insert(object_id, InlineObject::KittyImage(image.rasterize()));
- self.dirty = true;
- (true, None)
+ BitmapOperation::Place(placement) => {
+ self.register_bitmap_placement(placement.placement_id, true, true, term);
}
- KittyOperation::TransmitAndPlace {
- object_id,
- image,
- anchor,
- } => {
- self.remove_objects_at(&InlineAnchor {
- row: anchor.row,
- col: anchor.col,
- columns: anchor.columns,
- rows: anchor.rows,
- style: InlineStyle::default(),
- });
- self.objects
- .insert(object_id, InlineObject::KittyImage(image.rasterize()));
- self.set_anchor(
- object_id,
- InlineAnchor {
- row: anchor.row,
- col: anchor.col,
- columns: anchor.columns,
- rows: anchor.rows,
- style: InlineStyle::default(),
- },
+ BitmapOperation::Update {
+ placement_id,
+ update,
+ } if update.row.is_some()
+ || update.col.is_some()
+ || update.columns.is_some()
+ || update.rows.is_some() =>
+ {
+ self.register_bitmap_placement(
+ *placement_id,
+ update.row.is_some(),
+ update.columns.is_some(),
+ term,
);
- (true, None)
}
- KittyOperation::PlaceExisting { object_id, anchor } => {
- if self.objects.contains_key(&object_id) {
- self.set_anchor(
- object_id,
- InlineAnchor {
- row: anchor.row,
- col: anchor.col,
- columns: anchor.columns,
- rows: anchor.rows,
- style: InlineStyle::default(),
- },
- );
- }
- (true, None)
+ BitmapOperation::DeletePlacement(placement_id) => {
+ remove_external_from_both_screens(term, bitmap_external_id(*placement_id));
}
- KittyOperation::Delete { object_id } => {
- if let Some(object_id) = object_id {
- self.remove_object(object_id);
- } else {
- self.clear_objects();
+ BitmapOperation::DeleteBitmap(_) => {
+ for screen in [
+ ExternalPlacementScreen::Main,
+ ExternalPlacementScreen::Alternate,
+ ] {
+ let stale = term
+ .external_placements(screen)
+ .filter_map(|placement| {
+ bitmap_placement_id(placement.id).filter(|placement_id| {
+ self.bitmap.placement(*placement_id).is_none()
+ })
+ })
+ .collect::>();
+ for placement_id in stale {
+ term.remove_external_placement(screen, bitmap_external_id(placement_id));
+ }
}
- (true, None)
}
+ _ => {}
+ }
+ }
+
+ fn register_bitmap_placement(
+ &self,
+ placement_id: u32,
+ row_was_explicit: bool,
+ span_was_explicit: bool,
+ term: &mut VtTerminal,
+ ) {
+ let Some(placement) = self.bitmap.placement(placement_id) else {
+ return;
+ };
+ let id = bitmap_external_id(placement_id);
+ let active_screen = term.active_external_placement_screen();
+ let existing = [
+ ExternalPlacementScreen::Main,
+ ExternalPlacementScreen::Alternate,
+ ]
+ .into_iter()
+ .find_map(|screen| {
+ term.external_placement(screen, id)
+ .cloned()
+ .map(|placement| (screen, placement))
+ });
+ if !row_was_explicit && !span_was_explicit {
+ let Some((_screen, mut existing)) = existing else {
+ return;
+ };
+ existing.col = usize::from(placement.col());
+ if existing.col.checked_add(existing.columns).is_none() {
+ warn!(
+ placement_id,
+ "bitmap placement column overflows terminal coordinates"
+ );
+ return;
+ }
+ term.register_external_placement(existing);
+ return;
}
+
+ let (screen, abs_row) = if row_was_explicit {
+ (
+ active_screen,
+ term.external_placement_absolute_row(placement.row()),
+ )
+ } else {
+ let Some((screen, existing)) = existing else {
+ return;
+ };
+ let Ok(source_row) = i64::try_from(existing.source_row) else {
+ warn!(
+ placement_id,
+ "bitmap placement source row does not fit signed coordinates"
+ );
+ return;
+ };
+ (screen, existing.abs_row.saturating_sub(source_row))
+ };
+ let Some(external) = ExternalPlacement::new(
+ id,
+ screen,
+ abs_row,
+ usize::from(placement.col()),
+ placement.columns() as usize,
+ placement.rows() as usize,
+ ExternalPlacementScrollPolicy::Content,
+ ExternalPlacementErasePolicy::Preserve,
+ ) else {
+ warn!(
+ placement_id,
+ "bitmap placement does not fit terminal coordinates"
+ );
+ return;
+ };
+ if row_was_explicit {
+ remove_external_from_both_screens(term, id);
+ }
+ term.register_external_placement(external);
}
fn handle_rgp_sequence(
&mut self,
sequence: &[u8],
camera_updates: &mut Vec,
+ term: &mut VtTerminal,
) -> Option>> {
- let operation = consume_rgp_sequence(sequence)?;
+ self.evict_stale_rgp_payloads();
+ let defaults = BitmapLimits::default();
+ let max_payload_bytes = self
+ .rgp_max_payload_bytes
+ .unwrap_or_else(|| usize::try_from(defaults.max_bitmap_bytes).unwrap_or(usize::MAX));
+ let operation = consume_rgp_sequence(sequence, max_payload_bytes)?;
Some(match operation {
RgpOperation::SupportQuery => Some(support_reply()),
RgpOperation::Camera {
@@ -327,16 +749,34 @@ impl TerminalInlineObjects {
match source {
RgpRegisterSource::Path { path } => {
self.pending_rgp_payloads.remove(&object_id);
- match load_object_source_with_options(Path::new(&path), load_options) {
- Ok((source, source_data)) => {
- info!("registered RGP object {} from {}", object_id, source);
- self.objects.insert(object_id, source_data.into());
- self.dirty = true;
- None
- }
- Err(error) => {
- warn!("failed to load RGP object {object_id}: {error:#}");
- None
+ if !self.can_register_rgp_id(object_id) {
+ warn!(object_id, "RGP object count limit reached");
+ None
+ } else {
+ match load_rgp_object_source_with_options(
+ object_id,
+ Path::new(&path),
+ load_options,
+ max_payload_bytes,
+ ) {
+ Ok((source, source_data, encoded_bytes, resident_bytes)) => {
+ if self.register_rgp_object(
+ object_id,
+ source_data,
+ encoded_bytes,
+ resident_bytes,
+ ) {
+ info!(
+ "registered RGP object {} from {}",
+ object_id, source
+ );
+ }
+ None
+ }
+ Err(error) => {
+ warn!("failed to load RGP object {object_id}: {error:#}");
+ None
+ }
}
}
}
@@ -354,22 +794,32 @@ impl TerminalInlineObjects {
}
RgpOperation::Place { object_id, anchor } => {
if self.objects.contains_key(&object_id) {
- let row = anchor
- .row
- .saturating_sub(anchor.rows.saturating_sub(1).div_ceil(2) as u16);
- let col = anchor
- .col
- .saturating_sub(anchor.columns.saturating_sub(1).div_ceil(2) as u16);
+ let row = i64::from(anchor.row)
+ - i64::from(anchor.rows.saturating_sub(1).div_ceil(2));
+ let col = usize::from(anchor.col).saturating_sub(
+ usize::try_from(anchor.columns.saturating_sub(1).div_ceil(2))
+ .unwrap_or(usize::MAX),
+ );
self.set_anchor(
object_id,
InlineAnchor {
- row,
- col,
- columns: anchor.columns,
- rows: anchor.rows,
style: anchor.style.into(),
},
);
+ let abs_row = term.external_placement_absolute_row(row);
+ if let Some(placement) = ExternalPlacement::new(
+ rgp_external_id(object_id),
+ term.active_external_placement_screen(),
+ abs_row,
+ col,
+ anchor.columns as usize,
+ anchor.rows as usize,
+ ExternalPlacementScrollPolicy::Content,
+ ExternalPlacementErasePolicy::Preserve,
+ ) {
+ remove_external_from_both_screens(term, rgp_external_id(object_id));
+ term.register_external_placement(placement);
+ }
}
None
}
@@ -380,6 +830,7 @@ impl TerminalInlineObjects {
|| update.brightness.is_some();
apply_rgp_update(&mut anchor.style, update);
if needs_respawn {
+ self.dirty_rgp_objects.insert(object_id);
self.dirty = true;
}
}
@@ -388,8 +839,22 @@ impl TerminalInlineObjects {
RgpOperation::Delete { object_id } => {
if let Some(object_id) = object_id {
self.remove_object(object_id);
+ remove_external_from_both_screens(term, rgp_external_id(object_id));
} else {
self.clear_objects();
+ for screen in [
+ ExternalPlacementScreen::Main,
+ ExternalPlacementScreen::Alternate,
+ ] {
+ let ids = term
+ .external_placements(screen)
+ .filter(|placement| is_rgp_external_id(placement.id))
+ .map(|placement| placement.id)
+ .collect::>();
+ for id in ids {
+ term.remove_external_placement(screen, id);
+ }
+ }
}
None
}
@@ -397,35 +862,6 @@ impl TerminalInlineObjects {
})
}
- fn remove_objects_at(&mut self, new_anchor: &InlineAnchor) {
- let row_start = new_anchor.row as i32;
- let row_end = row_start + new_anchor.rows as i32;
- let col_start = new_anchor.col as i32;
- let col_end = col_start + new_anchor.columns as i32;
-
- let overlapping_ids = self
- .anchors
- .iter()
- .filter_map(|(object_id, anchor)| {
- let anchor_row_start = anchor.row as i32;
- let anchor_row_end = anchor_row_start + anchor.rows as i32;
- let anchor_col_start = anchor.col as i32;
- let anchor_col_end = anchor_col_start + anchor.columns as i32;
-
- (anchor_row_start < row_end
- && anchor_row_end > row_start
- && anchor_col_start < col_end
- && anchor_col_end > col_start)
- .then_some(*object_id)
- })
- .collect::>();
-
- for object_id in overlapping_ids {
- self.objects.remove(&object_id);
- self.anchors.remove(&object_id);
- }
- }
-
// Buffers chunked payload registrations until the final chunk arrives, then loads and registers the object.
fn handle_rgp_payload_chunk(
&mut self,
@@ -436,6 +872,48 @@ impl TerminalInlineObjects {
data: Vec,
options: ObjectLoadOptions,
) -> Option> {
+ self.evict_stale_rgp_payloads();
+ let defaults = BitmapLimits::default();
+ let max_payload_bytes = self
+ .rgp_max_payload_bytes
+ .unwrap_or_else(|| usize::try_from(defaults.max_bitmap_bytes).unwrap_or(usize::MAX));
+ let max_pending_bytes = self
+ .rgp_max_pending_bytes
+ .unwrap_or_else(|| usize::try_from(defaults.max_pending_bytes).unwrap_or(usize::MAX));
+ let max_pending_transfers = self
+ .rgp_max_pending_transfers
+ .unwrap_or(defaults.max_pending_transfers);
+
+ if data.len() > max_payload_bytes {
+ self.pending_rgp_payloads.remove(&object_id);
+ warn!(object_id, "RGP payload chunk exceeds configured byte limit");
+ return None;
+ }
+ if !self.pending_rgp_payloads.contains_key(&object_id)
+ && self.pending_rgp_payloads.len() >= max_pending_transfers
+ {
+ warn!(object_id, "too many incomplete RGP payload transfers");
+ return None;
+ }
+ let previous_len = self
+ .pending_rgp_payloads
+ .get(&object_id)
+ .map_or(0, |pending| pending.data.len());
+ let Some(next_len) = previous_len.checked_add(data.len()) else {
+ self.pending_rgp_payloads.remove(&object_id);
+ return None;
+ };
+ let total_without_current = self
+ .pending_rgp_payload_bytes()
+ .saturating_sub(previous_len);
+ if next_len > max_payload_bytes
+ || total_without_current.saturating_add(next_len) > max_pending_bytes
+ {
+ self.pending_rgp_payloads.remove(&object_id);
+ warn!(object_id, "RGP pending payload byte limit exceeded");
+ return None;
+ }
+
let pending = self
.pending_rgp_payloads
.entry(object_id)
@@ -444,18 +922,26 @@ impl TerminalInlineObjects {
name: name.clone(),
data: Vec::new(),
options,
+ last_touched: Instant::now(),
});
if pending.format != format {
warn!(
"ignoring RGP payload chunk for object {} due to format mismatch ({} vs {})",
object_id, pending.format, format
);
+ self.pending_rgp_payloads.remove(&object_id);
return None;
}
if pending.name.is_none() {
pending.name = name;
}
+ if pending.data.try_reserve(data.len()).is_err() {
+ self.pending_rgp_payloads.remove(&object_id);
+ warn!(object_id, "failed to reserve bounded RGP payload storage");
+ return None;
+ }
pending.data.extend_from_slice(&data);
+ pending.last_touched = Instant::now();
info!(
"received RGP payload chunk for object {} (format={}, accumulated={} bytes, more={})",
object_id,
@@ -474,16 +960,27 @@ impl TerminalInlineObjects {
pending.format,
pending.data.len()
);
- match load_object_source_from_bytes_with_options(
+ if !self.can_register_rgp_id(object_id) {
+ warn!(object_id, "RGP object count limit reached");
+ return None;
+ }
+ match load_rgp_object_source_from_bytes_with_options(
+ object_id,
&pending.format,
pending.name.as_deref(),
&pending.data,
pending.options,
+ max_payload_bytes,
) {
- Ok((source, source_data)) => {
- info!("registered RGP object {} from {}", object_id, source);
- self.objects.insert(object_id, source_data.into());
- self.dirty = true;
+ Ok((source, source_data, resident_bytes)) => {
+ if self.register_rgp_object(
+ object_id,
+ source_data,
+ pending.data.len(),
+ resident_bytes,
+ ) {
+ info!("registered RGP object {} from {}", object_id, source);
+ }
None
}
Err(error) => {
@@ -492,6 +989,114 @@ impl TerminalInlineObjects {
}
}
}
+
+ fn pending_rgp_payload_bytes(&self) -> usize {
+ self.pending_rgp_payloads
+ .values()
+ .map(|pending| pending.data.len())
+ .fold(0usize, usize::saturating_add)
+ }
+
+ fn can_register_rgp_id(&self, object_id: u32) -> bool {
+ let max_objects = self
+ .rgp_max_objects
+ .unwrap_or_else(|| BitmapLimits::default().max_bitmaps);
+ self.objects.contains_key(&object_id) || self.objects.len() < max_objects
+ }
+
+ fn register_rgp_object(
+ &mut self,
+ object_id: u32,
+ source: ObjectSource,
+ encoded_bytes: usize,
+ decoded_bytes: usize,
+ ) -> bool {
+ let defaults = BitmapLimits::default();
+ let max_object_bytes = self
+ .rgp_max_payload_bytes
+ .unwrap_or_else(|| usize::try_from(defaults.max_bitmap_bytes).unwrap_or(usize::MAX));
+ let max_total_bytes = self.rgp_max_total_bytes.unwrap_or_else(|| {
+ usize::try_from(defaults.max_total_bitmap_bytes).unwrap_or(usize::MAX)
+ });
+ let resident_bytes = decoded_bytes
+ .max(object_source_resident_bytes(&source))
+ .max(encoded_bytes);
+ let previous_bytes = self.rgp_object_bytes.get(&object_id).copied().unwrap_or(0);
+ let current_bytes = self
+ .rgp_object_bytes
+ .values()
+ .copied()
+ .fold(0usize, usize::saturating_add);
+ let next_total = current_bytes
+ .saturating_sub(previous_bytes)
+ .saturating_add(resident_bytes);
+ if resident_bytes > max_object_bytes
+ || next_total > max_total_bytes
+ || !self.can_register_rgp_id(object_id)
+ {
+ warn!(
+ object_id,
+ resident_bytes, next_total, "RGP resident object budget exceeded"
+ );
+ remove_rgp_materialized_source(&source);
+ return false;
+ }
+
+ let replacement_path = match &source {
+ ObjectSource::Gltf(path) => Some(path.clone()),
+ _ => None,
+ };
+ if let Some(previous) = self.objects.insert(object_id, source.into()) {
+ remove_materialized_inline_object(&previous, replacement_path.as_deref());
+ }
+ self.rgp_object_bytes.insert(object_id, resident_bytes);
+ self.dirty_rgp_objects.insert(object_id);
+ self.dirty = true;
+ true
+ }
+
+ fn evict_stale_rgp_payloads(&mut self) {
+ let now = Instant::now();
+ self.pending_rgp_payloads.retain(|object_id, pending| {
+ let keep =
+ now.saturating_duration_since(pending.last_touched) <= RGP_INCOMPLETE_TIMEOUT;
+ if !keep {
+ warn!(
+ object_id = *object_id,
+ "discarding stale incomplete RGP payload transfer"
+ );
+ }
+ keep
+ });
+ }
+}
+
+pub(crate) fn bitmap_external_id(placement_id: u32) -> u64 {
+ BITMAP_PLACEMENT_NAMESPACE | u64::from(placement_id)
+}
+
+fn bitmap_placement_id(id: u64) -> Option {
+ ((id & BITMAP_PLACEMENT_NAMESPACE) != 0)
+ .then(|| u32::try_from(id & u64::from(u32::MAX)).ok())
+ .flatten()
+}
+
+pub(crate) fn rgp_external_id(object_id: u32) -> u64 {
+ RGP_PLACEMENT_NAMESPACE | u64::from(object_id)
+}
+
+fn is_rgp_external_id(id: u64) -> bool {
+ id & (BITMAP_PLACEMENT_NAMESPACE | RGP_PLACEMENT_NAMESPACE) == RGP_PLACEMENT_NAMESPACE
+}
+
+fn remove_external_from_both_screens(term: &mut VtTerminal, id: u64) {
+ term.remove_external_placement(ExternalPlacementScreen::Main, id);
+ term.remove_external_placement(ExternalPlacementScreen::Alternate, id);
+}
+
+fn external_viewport_top(term: &VtTerminal) -> i64 {
+ term.external_placement_absolute_row(0)
+ .saturating_sub(i64::try_from(term.display_offset()).unwrap_or(i64::MAX))
}
struct PendingRgpPayload {
@@ -499,6 +1104,7 @@ struct PendingRgpPayload {
name: Option,
data: Vec,
options: ObjectLoadOptions,
+ last_touched: Instant,
}
fn pending_apc_prefix_start(bytes: &[u8], cursor: usize) -> usize {
@@ -528,34 +1134,10 @@ fn apc_end(bytes: &[u8], payload_start: usize) -> Option {
/// Registered inline object.
pub enum InlineObject {
- /// Kitty image object.
- KittyImage(KittyInlineObject),
/// Ratty graphics object.
RgpObject(RgpInlineObject),
}
-/// Raster image payload.
-pub struct RasterObject {
- /// Image width in pixels.
- pub width: u32,
- /// Image height in pixels.
- pub height: u32,
- /// RGBA image bytes.
- pub rgba: Vec,
- /// Uploaded image handle.
- pub handle: Option>,
-}
-
-/// Kitty-backed inline object.
-pub struct KittyInlineObject {
- /// Raster image payload.
- pub raster: RasterObject,
- /// Indicates placeholder-driven placement.
- pub uses_placeholders: bool,
- /// Cached plane mesh and material for 3D presentation.
- pub(crate) plane: Option,
-}
-
/// RGP-backed inline object.
pub enum RgpInlineObject {
/// STL mesh payload.
@@ -581,25 +1163,18 @@ pub enum RgpInlineObject {
},
}
-impl InlineObject {
- fn scrolls_with_text(&self) -> bool {
- match self {
- InlineObject::KittyImage(object) => !object.uses_placeholders,
- InlineObject::RgpObject(_) => true,
- }
+fn remove_materialized_inline_object(object: &InlineObject, preserve: Option<&str>) {
+ let InlineObject::RgpObject(RgpInlineObject::Gltf { asset_path, .. }) = object else {
+ return;
+ };
+ if preserve == Some(asset_path.as_str()) || !Path::new(asset_path).starts_with("objects/rgp") {
+ return;
}
+ let _ = std::fs::remove_file(runtime_asset_root().join(asset_path));
}
-/// Inline object anchor.
+/// Renderer-only style for a terminal-owned RGP placement.
pub struct InlineAnchor {
- /// Anchor row.
- pub row: u16,
- /// Anchor column.
- pub col: u16,
- /// Object width in cells.
- pub columns: u32,
- /// Object height in cells.
- pub rows: u32,
/// Inline styling.
pub style: InlineStyle,
}
@@ -672,3 +1247,895 @@ fn apply_vec3_update(target: &mut Vec3, update: [Option; 3]) {
target.z = z;
}
}
+
+#[cfg(test)]
+mod tests {
+ use base64::Engine as _;
+
+ use super::*;
+ use crate::vt;
+
+ const BITMAP_SUPPORT_REPLY: &[u8] = b"\x1b_ratty;i;s;v=1;fmt=png;frame=rgba8;payload=1;chunk=1;placement=1;crop=1;fit=contain|cover|fill;filter=nearest|linear;opacity=1\x1b\\";
+
+ fn minimal_rgp_glb(marker: u8) -> Vec {
+ let mut bin = Vec::new();
+ for value in [0.0f32, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0] {
+ bin.extend_from_slice(&value.to_le_bytes());
+ }
+ for value in [0.0f32, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0] {
+ bin.extend_from_slice(&value.to_le_bytes());
+ }
+ for index in [0u16, 1, 2] {
+ bin.extend_from_slice(&index.to_le_bytes());
+ }
+ let bin_len = bin.len();
+ while bin.len() % 4 != 0 {
+ bin.push(0);
+ }
+
+ let mut json = format!(
+ r#"{{"asset":{{"version":"2.0","generator":"ratty-test-{marker}"}},"scene":0,"scenes":[{{"nodes":[0]}}],"nodes":[{{"mesh":0}}],"meshes":[{{"primitives":[{{"attributes":{{"POSITION":0,"NORMAL":1}},"indices":2}}]}}],"buffers":[{{"byteLength":{bin_len}}}],"bufferViews":[{{"buffer":0,"byteOffset":0,"byteLength":36,"target":34962}},{{"buffer":0,"byteOffset":36,"byteLength":36,"target":34962}},{{"buffer":0,"byteOffset":72,"byteLength":6,"target":34963}}],"accessors":[{{"bufferView":0,"componentType":5126,"count":3,"type":"VEC3","min":[0,0,0],"max":[1,1,0]}},{{"bufferView":1,"componentType":5126,"count":3,"type":"VEC3"}},{{"bufferView":2,"componentType":5123,"count":3,"type":"SCALAR"}}]}}"#
+ )
+ .into_bytes();
+ while json.len() % 4 != 0 {
+ json.push(b' ');
+ }
+
+ let total_len = 12usize
+ .checked_add(8 + json.len())
+ .and_then(|len| len.checked_add(8 + bin.len()))
+ .expect("test GLB length should fit");
+ let mut glb = Vec::with_capacity(total_len);
+ glb.extend_from_slice(b"glTF");
+ glb.extend_from_slice(&2u32.to_le_bytes());
+ glb.extend_from_slice(
+ &u32::try_from(total_len)
+ .expect("test GLB length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(
+ &u32::try_from(json.len())
+ .expect("test JSON length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(&0x4E4F_534Au32.to_le_bytes());
+ glb.extend_from_slice(&json);
+ glb.extend_from_slice(
+ &u32::try_from(bin.len())
+ .expect("test BIN length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(&0x004E_4942u32.to_le_bytes());
+ glb.extend_from_slice(&bin);
+ glb
+ }
+ const RATATUI_IMAGE_KITTY_QUERY: &[u8] = b"\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\";
+ const PNG_2X2: &[u8] = &[
+ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+ 0x52, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x02, 0x08, 0x06, 0x00, 0x00, 0x00, 0x72,
+ 0xb6, 0x0d, 0x24, 0x00, 0x00, 0x00, 0x12, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0xf8,
+ 0xcf, 0xc0, 0xf0, 0x1f, 0x0c, 0x81, 0x34, 0x18, 0x00, 0x00, 0x49, 0xc8, 0x09, 0xf7, 0xf9,
+ 0xab, 0xb6, 0x0d, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+ ];
+
+ fn parser() -> TerminalRuntime {
+ TerminalRuntime::for_test(24, 80)
+ }
+
+ fn contents(runtime: &TerminalRuntime) -> String {
+ vt::visible_row_texts(&runtime.term)
+ .join("\n")
+ .trim_end()
+ .to_owned()
+ }
+
+ fn consume(
+ objects: &mut TerminalInlineObjects,
+ chunk: &[u8],
+ parser: &mut TerminalRuntime,
+ ) -> Vec> {
+ let mut camera_updates = Vec::new();
+ let mut terminal_output = false;
+ objects.consume_pty_output(chunk, parser, &mut camera_updates, &mut terminal_output)
+ }
+
+ fn register_bitmap(objects: &mut TerminalInlineObjects, parser: &mut TerminalRuntime) {
+ let payload = base64::engine::general_purpose::STANDARD.encode(PNG_2X2);
+ let command = format!("\x1b_ratty;i;r;id=7;fmt=png;source=payload;more=0;{payload}\x1b\\");
+ assert!(consume(objects, command.as_bytes(), parser).is_empty());
+ }
+
+ fn scroll_one_row() -> Vec {
+ b"x\r\n".repeat(24)
+ }
+
+ #[test]
+ fn consumes_bitmap_apc_without_leaking_it_into_mixed_terminal_text() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(&mut objects, b"left\x1b_ratty;i;s\x1b\\right", &mut parser);
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert_eq!(contents(&parser), "leftright");
+ }
+
+ #[test]
+ fn kitty_query_reports_support_without_storing_an_image() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(&mut objects, RATATUI_IMAGE_KITTY_QUERY, &mut parser);
+
+ assert_eq!(replies, [b"\x1b_Gi=31;OK\x1b\\".to_vec()]);
+ assert!(objects.objects.is_empty());
+ assert!(objects.anchors.is_empty());
+ }
+
+ #[test]
+ fn invalid_kitty_query_reports_error_without_mutating_state() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(
+ &mut objects,
+ b"\x1b_Gi=9,s=2,v=2,a=q,t=d,f=24;AAAA\x1b\\",
+ &mut parser,
+ );
+
+ assert_eq!(replies, [b"\x1b_Gi=9;EINVAL: invalid data\x1b\\".to_vec()]);
+ assert!(objects.objects.is_empty());
+ assert!(objects.anchors.is_empty());
+ }
+
+ #[test]
+ fn kitty_query_quiet_levels_suppress_the_requested_reply_class() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let ok_replies = consume(
+ &mut objects,
+ b"\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24,q=1;AAAA\x1b\\",
+ &mut parser,
+ );
+ let error_replies = consume(
+ &mut objects,
+ b"\x1b_Gi=9,s=2,v=2,a=q,t=d,f=24,q=2;AAAA\x1b\\",
+ &mut parser,
+ );
+ let fully_quiet_ok_replies = consume(
+ &mut objects,
+ b"\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24,q=2;AAAA\x1b\\",
+ &mut parser,
+ );
+
+ assert!(ok_replies.is_empty());
+ assert!(error_replies.is_empty());
+ assert!(fully_quiet_ok_replies.is_empty());
+ assert!(objects.objects.is_empty());
+ assert!(objects.anchors.is_empty());
+ }
+
+ #[test]
+ fn buffers_fragmented_bitmap_apc_until_its_terminator_arrives() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ assert!(consume(&mut objects, b"before\x1b_ratty;i;", &mut parser).is_empty());
+ assert_eq!(contents(&parser), "before");
+ let replies = consume(&mut objects, b"s\x1b\\after", &mut parser);
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert_eq!(contents(&parser), "beforeafter");
+ }
+
+ #[test]
+ fn bounds_and_discards_oversized_fragmented_bitmap_apc_then_recovers_after_split_st() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ let limit = 32;
+
+ objects.consume_pty_output_with_bitmap_limit(
+ b"before\x1b_ratty;i;r;id=1;",
+ &mut parser,
+ limit,
+ );
+ objects.consume_pty_output_with_bitmap_limit(b"AAAAAAAAAAAAAAAA", &mut parser, limit);
+ assert!(objects.pending_bytes.len() <= limit);
+ assert!(objects.discarding_oversized_bitmap_apc);
+
+ objects.consume_pty_output_with_bitmap_limit(b"discarded\x1b", &mut parser, limit);
+ let replies = objects.consume_pty_output_with_bitmap_limit(
+ b"\\after\x1b_ratty;i;s\x1b\\",
+ &mut parser,
+ limit,
+ );
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert_eq!(contents(&parser), "beforeafter");
+ assert!(!objects.discarding_oversized_bitmap_apc);
+ assert!(objects.pending_bytes.len() <= limit);
+ }
+
+ #[test]
+ fn discards_oversized_bitmap_apc_until_c1_st_then_recovers() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ let limit = 24;
+
+ objects.consume_pty_output_with_bitmap_limit(
+ b"\x1b_ratty;i;r;id=1;AAAAAAAA",
+ &mut parser,
+ limit,
+ );
+ let replies = objects.consume_pty_output_with_bitmap_limit(
+ b"discarded\x9ctail\x1b_ratty;i;s\x9c",
+ &mut parser,
+ limit,
+ );
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert_eq!(contents(&parser), "tail");
+ assert!(!objects.discarding_oversized_bitmap_apc);
+ }
+
+ #[test]
+ fn oversized_bitmap_middle_chunk_aborts_pending_registration() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ objects.consume_pty_output_with_bitmap_limit(
+ b"\x1b_ratty;i;r;id=41;fmt=png;source=payload;more=1;AQID\x1b\\",
+ &mut parser,
+ 128,
+ );
+
+ objects.consume_pty_output_with_bitmap_limit(
+ format!("\x1b_ratty;i;r;id=41;more=1;{}\x1b\\", "A".repeat(128)).as_bytes(),
+ &mut parser,
+ 40,
+ );
+ objects.consume_pty_output_with_bitmap_limit(
+ b"\x1b_ratty;i;r;id=41;more=0;BA==\x1b\\",
+ &mut parser,
+ 128,
+ );
+
+ assert!(objects.bitmap.bitmap(41).is_none());
+ }
+
+ #[test]
+ fn bounds_forwarded_kitty_apc_and_recovers_after_split_st() {
+ let mut objects = TerminalInlineObjects {
+ forwarded_kitty_apc_limit: Some(40),
+ ..TerminalInlineObjects::default()
+ };
+ let mut parser = parser();
+
+ let replies = consume(
+ &mut objects,
+ b"before\x1b_Ga=t,f=24,s=1,v=1;AAAAAAAAAAAAAAAAAAAAAAAA",
+ &mut parser,
+ );
+ assert!(replies.is_empty());
+ assert!(objects.pending_bytes.len() <= 40);
+ assert!(objects.discarding_oversized_forwarded_kitty_apc);
+ assert_eq!(contents(&parser), "before");
+
+ assert!(consume(&mut objects, b"discarded\x1b", &mut parser).is_empty());
+ let replies = consume(
+ &mut objects,
+ b"\\after\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\",
+ &mut parser,
+ );
+
+ assert_eq!(replies, [b"\x1b_Gi=31;OK\x1b\\".to_vec()]);
+ assert_eq!(contents(&parser), "beforeafter");
+ assert!(!objects.discarding_oversized_forwarded_kitty_apc);
+ assert!(objects.pending_bytes.len() <= 40);
+ }
+
+ #[test]
+ fn bitmap_and_rgp_have_independent_framing_limits() {
+ let mut objects = TerminalInlineObjects {
+ rgp_apc_limit: Some(64),
+ ..TerminalInlineObjects::default()
+ };
+ let mut parser = parser();
+ let limit = 8;
+
+ objects.consume_pty_output_with_bitmap_limit(b"\x1b_ratty;g;", &mut parser, limit);
+ let replies = objects.consume_pty_output_with_bitmap_limit(b"s\x1b\\", &mut parser, limit);
+
+ assert_eq!(replies, vec![crate::rgp::support_reply()]);
+ assert!(contents(&parser).is_empty());
+ }
+
+ #[test]
+ fn bounds_fragmented_rgp_apc_and_recovers_after_split_st() {
+ let mut objects = TerminalInlineObjects {
+ rgp_apc_limit: Some(40),
+ ..TerminalInlineObjects::default()
+ };
+ let mut parser = parser();
+
+ assert!(
+ consume(
+ &mut objects,
+ b"before\x1b_ratty;g;r;id=1;fmt=obj;source=payload;AAAAAAAA",
+ &mut parser,
+ )
+ .is_empty()
+ );
+ assert!(objects.pending_bytes.len() <= 40);
+ assert!(objects.discarding_oversized_rgp_apc);
+ assert_eq!(contents(&parser), "before");
+
+ assert!(consume(&mut objects, b"discarded\x1b", &mut parser).is_empty());
+ let replies = consume(&mut objects, b"\\after\x1b_ratty;g;s\x1b\\", &mut parser);
+ assert_eq!(replies, vec![crate::rgp::support_reply()]);
+ assert_eq!(contents(&parser), "beforeafter");
+ assert!(!objects.discarding_oversized_rgp_apc);
+ assert!(objects.pending_bytes.len() <= 40);
+ }
+
+ #[test]
+ fn oversized_rgp_middle_chunk_aborts_pending_payload() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ let first = base64::engine::general_purpose::STANDARD.encode(b"v 0 0 0\nv 1 ");
+ let final_chunk =
+ base64::engine::general_purpose::STANDARD.encode(b"0 0\nv 0 1 0\nf 1 2 3\n");
+ consume(
+ &mut objects,
+ format!("\x1b_ratty;g;r;id=55;fmt=obj;source=payload;more=1;{first}\x1b\\").as_bytes(),
+ &mut parser,
+ );
+ assert!(objects.pending_rgp_payloads.contains_key(&55));
+
+ objects.rgp_apc_limit = Some(48);
+ consume(
+ &mut objects,
+ format!(
+ "\x1b_ratty;g;r;id=55;fmt=obj;source=payload;more=1;{}\x1b\\",
+ "A".repeat(128)
+ )
+ .as_bytes(),
+ &mut parser,
+ );
+ assert!(objects.pending_rgp_payloads.is_empty());
+
+ objects.rgp_apc_limit = None;
+ consume(
+ &mut objects,
+ format!("\x1b_ratty;g;r;id=55;fmt=obj;source=payload;more=0;{final_chunk}\x1b\\")
+ .as_bytes(),
+ &mut parser,
+ );
+ assert!(!objects.objects.contains_key(&55));
+ }
+
+ #[test]
+ fn bounds_rgp_decoded_chunks_pending_bytes_and_transfer_count() {
+ let mut objects = TerminalInlineObjects {
+ rgp_max_payload_bytes: Some(8),
+ rgp_max_pending_bytes: Some(6),
+ rgp_max_pending_transfers: Some(2),
+ ..TerminalInlineObjects::default()
+ };
+ let mut parser = parser();
+ let chunk =
+ |id| format!("\x1b_ratty;g;r;id={id};fmt=obj;source=payload;more=1;YWJjZA==\x1b\\");
+
+ consume(&mut objects, chunk(1).as_bytes(), &mut parser);
+ assert_eq!(objects.pending_rgp_payload_bytes(), 4);
+ consume(&mut objects, chunk(2).as_bytes(), &mut parser);
+ assert!(objects.pending_rgp_payloads.contains_key(&1));
+ assert!(!objects.pending_rgp_payloads.contains_key(&2));
+ assert_eq!(objects.pending_rgp_payload_bytes(), 4);
+
+ objects.rgp_max_pending_bytes = Some(16);
+ objects.rgp_max_pending_transfers = Some(1);
+ consume(&mut objects, chunk(2).as_bytes(), &mut parser);
+ assert!(!objects.pending_rgp_payloads.contains_key(&2));
+
+ // One decoded chunk above the per-object cap is rejected before it
+ // can create an incomplete transfer.
+ objects.rgp_max_payload_bytes = Some(3);
+ consume(&mut objects, chunk(3).as_bytes(), &mut parser);
+ assert!(!objects.pending_rgp_payloads.contains_key(&3));
+ }
+
+ #[test]
+ fn bounds_finalized_rgp_object_count_and_resident_bytes_with_reuse() {
+ let triangle = b"v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n".to_vec();
+ let mut objects = TerminalInlineObjects {
+ rgp_max_payload_bytes: Some(4_096),
+ rgp_max_total_bytes: Some(4_096),
+ rgp_max_objects: Some(1),
+ ..TerminalInlineObjects::default()
+ };
+ objects.handle_rgp_payload_chunk(
+ 1,
+ "obj",
+ None,
+ false,
+ triangle.clone(),
+ ObjectLoadOptions::default(),
+ );
+ assert!(objects.objects.contains_key(&1));
+ assert_eq!(objects.rgp_object_bytes.len(), 1);
+
+ objects.handle_rgp_payload_chunk(
+ 2,
+ "obj",
+ None,
+ false,
+ triangle.clone(),
+ ObjectLoadOptions::default(),
+ );
+ assert!(!objects.objects.contains_key(&2));
+
+ // Reusing the existing ID replaces its budget entry rather than
+ // consuming another object slot.
+ objects.handle_rgp_payload_chunk(
+ 1,
+ "obj",
+ Some("replacement.obj".to_string()),
+ false,
+ triangle,
+ ObjectLoadOptions { normalize: false },
+ );
+ assert_eq!(objects.objects.len(), 1);
+
+ let resident = objects.rgp_object_bytes[&1];
+ objects.rgp_max_objects = Some(2);
+ objects.rgp_max_total_bytes = Some(resident);
+ objects.handle_rgp_payload_chunk(
+ 2,
+ "obj",
+ None,
+ false,
+ b"v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n".to_vec(),
+ ObjectLoadOptions::default(),
+ );
+ assert!(!objects.objects.contains_key(&2));
+ }
+
+ #[test]
+ fn rgp_glb_decodes_in_memory_and_replaces_without_runtime_asset() {
+ let mut objects = TerminalInlineObjects {
+ rgp_max_payload_bytes: Some(4_096),
+ rgp_max_total_bytes: Some(4_096),
+ rgp_max_objects: Some(2),
+ ..TerminalInlineObjects::default()
+ };
+ let first_payload = minimal_rgp_glb(1);
+ objects.handle_rgp_payload_chunk(
+ 7,
+ "glb",
+ None,
+ false,
+ first_payload,
+ ObjectLoadOptions::default(),
+ );
+ match objects
+ .objects
+ .get(&7)
+ .expect("first GLB payload should create an object")
+ {
+ InlineObject::RgpObject(RgpInlineObject::Obj { meshes, .. }) => {
+ assert_eq!(meshes.len(), 1);
+ assert_eq!(meshes[0].count_vertices(), 3);
+ }
+ _ => panic!("RGP GLB payload must decode into an owned mesh"),
+ }
+
+ objects.handle_rgp_payload_chunk(
+ 7,
+ "glb",
+ None,
+ false,
+ minimal_rgp_glb(2),
+ ObjectLoadOptions::default(),
+ );
+ match objects
+ .objects
+ .get(&7)
+ .expect("replacement GLB payload should create an object")
+ {
+ InlineObject::RgpObject(RgpInlineObject::Obj { meshes, .. }) => {
+ assert_eq!(meshes.len(), 1);
+ assert_eq!(meshes[0].count_vertices(), 3);
+ }
+ _ => panic!("replacement RGP GLB must remain an owned mesh"),
+ }
+
+ objects.remove_object(7);
+ assert!(!objects.objects.contains_key(&7));
+ assert!(!objects.rgp_object_bytes.contains_key(&7));
+ }
+
+ #[test]
+ fn oversized_forwarded_kitty_chunk_aborts_rio_partial_transfer() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ consume(
+ &mut objects,
+ b"\x1b_Ga=t,f=32,s=1,v=1,i=77,m=1;AAE=\x1b\\",
+ &mut parser,
+ );
+ objects.forwarded_kitty_apc_limit = Some(48);
+ let oversized = format!("\x1b_Gm=1;{}\x1b\\", "A".repeat(128));
+ consume(&mut objects, oversized.as_bytes(), &mut parser);
+ consume(&mut objects, b"\x1b_Gm=0;AgM=\x1b\\", &mut parser);
+
+ assert!(parser.term.graphics.get_kitty_image(77).is_none());
+ }
+
+ #[test]
+ fn stale_rgp_payload_transfer_expires_and_next_command_recovers() {
+ let mut objects = TerminalInlineObjects {
+ rgp_max_payload_bytes: Some(8),
+ rgp_max_pending_bytes: Some(8),
+ rgp_max_pending_transfers: Some(1),
+ ..TerminalInlineObjects::default()
+ };
+ let mut parser = parser();
+ consume(
+ &mut objects,
+ b"\x1b_ratty;g;r;id=1;fmt=obj;source=payload;more=1;YWJjZA==\x1b\\",
+ &mut parser,
+ );
+ objects
+ .pending_rgp_payloads
+ .get_mut(&1)
+ .expect("first RGP transfer should be pending")
+ .last_touched = Instant::now() - RGP_INCOMPLETE_TIMEOUT - Duration::from_secs(1);
+
+ let replies = consume(&mut objects, b"\x1b_ratty;g;s\x1b\\", &mut parser);
+ assert!(objects.pending_rgp_payloads.is_empty());
+ assert_eq!(replies, vec![crate::rgp::support_reply()]);
+ }
+
+ #[test]
+ fn accepts_c1_st_for_bitmap_support_query() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(&mut objects, b"\x1b_ratty;i;s\x9c", &mut parser);
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert!(contents(&parser).is_empty());
+ }
+
+ #[test]
+ fn dispatches_adjacent_bitmap_and_rgp_sequences_in_wire_order() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(
+ &mut objects,
+ b"\x1b_ratty;i;s\x1b\\\x1b_ratty;g;s\x1b\\",
+ &mut parser,
+ );
+
+ assert_eq!(
+ replies,
+ vec![BITMAP_SUPPORT_REPLY.to_vec(), crate::rgp::support_reply()]
+ );
+ assert!(contents(&parser).is_empty());
+ }
+
+ #[test]
+ fn dispatches_bitmap_before_adjacent_kitty_and_keeps_bitmap_state_isolated() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+
+ let replies = consume(
+ &mut objects,
+ b"\x1b_ratty;i;s\x1b\\\x1b_Ga=d;\x1b\\\x1b_ratty;g;d\x1b\\",
+ &mut parser,
+ );
+
+ assert_eq!(replies, vec![BITMAP_SUPPORT_REPLY.to_vec()]);
+ assert!(objects.bitmap.bitmap(7).is_some());
+ assert!(contents(&parser).is_empty());
+ }
+
+ #[test]
+ fn malformed_bitmap_sequences_are_consumed_without_terminal_output() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+
+ let replies = consume(
+ &mut objects,
+ b"before\x1b_ratty;i;p;id=broken\x1b\\after",
+ &mut parser,
+ );
+
+ assert!(replies.is_empty());
+ assert_eq!(contents(&parser), "beforeafter");
+ }
+
+ #[test]
+ fn bitmap_placements_keep_payload_state_static_while_terminal_geometry_scrolls() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;p;id=7;pid=9;row=5;col=2;w=8;h=3\x1b\\",
+ &mut parser,
+ );
+
+ assert!(objects.needs_sync(Vec2::ZERO, 0, 0, &parser.term));
+ objects.finish_sync(Vec2::ZERO, 0, 0, &parser.term);
+ assert!(!objects.needs_sync(Vec2::ZERO, 0, 0, &parser.term));
+
+ let mut scroll = scroll_one_row();
+ scroll.extend(b"x\r\n");
+ consume(&mut objects, &scroll, &mut parser);
+
+ assert_eq!(
+ objects
+ .bitmap
+ .placement(9)
+ .expect("bitmap placement should exist")
+ .row(),
+ 5,
+ "Ratty keeps only immutable protocol payload/style state"
+ );
+ let geometry = parser
+ .term
+ .external_placement_geometries()
+ .into_iter()
+ .find(|geometry| geometry.id == bitmap_external_id(9))
+ .expect("terminal should own the placement geometry");
+ assert_eq!(geometry.row, 3);
+ assert!(objects.needs_sync(Vec2::ZERO, 0, 0, &parser.term));
+ }
+
+ #[test]
+ fn placement_before_scrolling_text_moves_in_wire_order() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+ let mut chunk = b"\x1b_ratty;i;p;id=7;pid=9;row=5;col=2;w=8;h=3\x1b\\".to_vec();
+ chunk.extend(scroll_one_row());
+
+ consume(&mut objects, &chunk, &mut parser);
+
+ assert_eq!(
+ objects
+ .bitmap
+ .placement(9)
+ .expect("placement should survive one row of scrolling")
+ .row(),
+ 5
+ );
+ let geometry = parser
+ .term
+ .external_placement_geometries()
+ .into_iter()
+ .find(|geometry| geometry.id == bitmap_external_id(9))
+ .expect("terminal should retain the placement");
+ assert_eq!(geometry.row, 4);
+ }
+
+ #[test]
+ fn placement_after_scrolling_text_is_not_moved_retroactively() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;p;id=7;pid=8;row=10;col=2;w=8;h=3\x1b\\",
+ &mut parser,
+ );
+ let mut chunk = scroll_one_row();
+ chunk.extend(b"\x1b_ratty;i;p;id=7;pid=9;row=5;col=2;w=8;h=3\x1b\\");
+
+ consume(&mut objects, &chunk, &mut parser);
+
+ let geometries = parser
+ .term
+ .external_placement_geometries()
+ .into_iter()
+ .map(|geometry| (geometry.id, geometry.row))
+ .collect::>();
+ assert_eq!(geometries[&bitmap_external_id(8)], 9);
+ assert_eq!(geometries[&bitmap_external_id(9)], 5);
+ assert_eq!(
+ objects
+ .bitmap
+ .placement(8)
+ .expect("payload state remains registered")
+ .row(),
+ 10
+ );
+ }
+
+ #[test]
+ fn bitmap_and_rgp_geometry_follow_partial_margin_scroll_in_wire_order() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = TerminalRuntime::for_test(6, 20);
+ register_bitmap(&mut objects, &mut parser);
+ for object_id in [101, 102, 103, 104] {
+ objects.objects.insert(
+ object_id,
+ InlineObject::RgpObject(RgpInlineObject::Gltf {
+ asset_path: format!("fixture-{object_id}.glb"),
+ handle: None,
+ }),
+ );
+ }
+
+ let wire = concat!(
+ "\x1b_ratty;i;p;id=7;pid=11;row=1;col=2;w=2;h=2\x1b\\",
+ "\x1b_ratty;i;p;id=7;pid=12;row=4;col=2;w=2;h=1\x1b\\",
+ "\x1b_ratty;i;p;id=7;pid=13;row=0;col=2;w=2;h=2\x1b\\",
+ "\x1b_ratty;g;p;id=101;row=2;col=3;w=2;h=2\x1b\\",
+ "\x1b_ratty;g;p;id=102;row=4;col=3;w=2;h=1\x1b\\",
+ "\x1b_ratty;g;p;id=103;row=1;col=3;w=2;h=2\x1b\\",
+ "\x1b[2;4r\x1b[4;1H\n",
+ "\x1b_ratty;i;p;id=7;pid=14;row=1;col=2;w=2;h=1\x1b\\",
+ "\x1b_ratty;g;p;id=104;row=1;col=3;w=2;h=1\x1b\\",
+ );
+ assert!(consume(&mut objects, wire.as_bytes(), &mut parser).is_empty());
+
+ let geometries = parser
+ .term
+ .external_placement_geometries()
+ .into_iter()
+ .map(|geometry| (geometry.id, geometry))
+ .collect::>();
+ for id in [bitmap_external_id(11), rgp_external_id(101)] {
+ let geometry = geometries[&id];
+ assert_eq!(
+ (geometry.row, geometry.rows, geometry.source_row),
+ (1, 1, 1)
+ );
+ }
+ for id in [bitmap_external_id(12), rgp_external_id(102)] {
+ let geometry = geometries[&id];
+ assert_eq!(
+ (geometry.row, geometry.rows, geometry.source_row),
+ (4, 1, 0)
+ );
+ }
+ for id in [bitmap_external_id(13), rgp_external_id(103)] {
+ let geometry = geometries[&id];
+ assert_eq!(
+ (geometry.row, geometry.rows, geometry.source_row),
+ (0, 2, 0)
+ );
+ }
+ for id in [bitmap_external_id(14), rgp_external_id(104)] {
+ let geometry = geometries[&id];
+ assert_eq!(
+ (geometry.row, geometry.rows, geometry.source_row),
+ (1, 1, 0)
+ );
+ }
+
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;u;pid=11;col=7\x1b\\",
+ &mut parser,
+ );
+ let geometry = parser
+ .term
+ .external_placement_geometries()
+ .into_iter()
+ .find(|geometry| geometry.id == bitmap_external_id(11))
+ .expect("column-only update must retain terminal placement state");
+ assert_eq!(
+ (
+ geometry.row,
+ geometry.col,
+ geometry.rows,
+ geometry.source_row
+ ),
+ (1, 7, 1, 1),
+ "column-only updates must not revive rows clipped by a terminal mutation"
+ );
+ }
+
+ #[test]
+ fn wide_rgp_placement_centers_without_truncating_the_half_width() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = TerminalRuntime::for_test(6, 20);
+ objects.objects.insert(
+ 77,
+ InlineObject::RgpObject(RgpInlineObject::Gltf {
+ asset_path: "fixture-77.glb".to_string(),
+ handle: None,
+ }),
+ );
+
+ assert!(
+ consume(
+ &mut objects,
+ b"\x1b_ratty;g;p;id=77;row=1;col=10;w=131074;h=1\x1b\\",
+ &mut parser,
+ )
+ .is_empty()
+ );
+
+ let placement = parser
+ .term
+ .external_placement(ExternalPlacementScreen::Main, rgp_external_id(77))
+ .expect("wide RGP placement");
+ assert_eq!(placement.col, 0);
+ assert_eq!(placement.columns, 131_074);
+ }
+
+ #[test]
+ fn bitmap_placements_are_screen_owned_and_pruned_after_alt_screen_reset() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;p;id=7;pid=21;row=2;col=2;w=2;h=1\x1b\\",
+ &mut parser,
+ );
+ consume(&mut objects, b"\x1b[?1049h", &mut parser);
+ assert!(parser.term.external_placement_geometries().is_empty());
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;p;id=7;pid=22;row=3;col=2;w=2;h=1\x1b\\",
+ &mut parser,
+ );
+ assert_eq!(
+ parser.term.external_placement_geometries()[0].id,
+ bitmap_external_id(22)
+ );
+
+ consume(&mut objects, b"\x1b[?1049l", &mut parser);
+ assert_eq!(
+ parser.term.external_placement_geometries()[0].id,
+ bitmap_external_id(21)
+ );
+ consume(&mut objects, b"\x1b[?1049h", &mut parser);
+ objects.reconcile_terminal_placements(&parser.term);
+ assert!(parser.term.external_placement_geometries().is_empty());
+ assert!(objects.bitmap.placement(22).is_none());
+ assert!(objects.bitmap.placement(21).is_some());
+
+ consume(&mut objects, b"\x1b[?1049l", &mut parser);
+ assert_eq!(
+ parser.term.external_placement_geometries()[0].id,
+ bitmap_external_id(21)
+ );
+ }
+
+ #[test]
+ fn scrolled_bitmap_reappears_from_history_then_expires_with_the_ring() {
+ let mut objects = TerminalInlineObjects::default();
+ let mut parser = parser();
+ register_bitmap(&mut objects, &mut parser);
+ consume(
+ &mut objects,
+ b"\x1b_ratty;i;p;id=7;pid=31;row=0;col=2;w=2;h=1\x1b\\",
+ &mut parser,
+ );
+ consume(&mut objects, &scroll_one_row(), &mut parser);
+ assert_eq!(parser.term.external_placement_geometries()[0].row, -1);
+
+ vt::set_scrollback(&mut parser.term, 1);
+ assert_eq!(parser.term.external_placement_geometries()[0].row, 0);
+ vt::set_scrollback(&mut parser.term, 0);
+
+ consume(&mut objects, &b"x\r\n".repeat(1_100), &mut parser);
+ objects.reconcile_terminal_placements(&parser.term);
+ assert!(
+ parser
+ .term
+ .external_placement(ExternalPlacementScreen::Main, bitmap_external_id(31))
+ .is_none()
+ );
+ assert!(objects.bitmap.placement(31).is_none());
+ }
+}
diff --git a/src/kitty.rs b/src/kitty.rs
index 6cd7324..c95f412 100644
--- a/src/kitty.rs
+++ b/src/kitty.rs
@@ -1,363 +1,394 @@
-//! Kitty graphics protocol parsing.
+//! Renderer-side integration for rio-vt's native Kitty graphics state.
+//!
+//! Ratty deliberately does not parse Kitty APCs here. Complete APC frames are
+//! forwarded unchanged to rio-vt; this module only owns Bevy asset handles and
+//! converts rio-vt's direct/Unicode-placeholder placement geometry into draw
+//! records.
use std::collections::HashMap;
-use base64::Engine as _;
+use bevy::prelude::*;
+use rio_graphics::GraphicData;
+use rio_vt::ansi::graphics::{OverlayViewport, UpdateQueues, kitty_overlay_geometry};
+use rio_vt::ansi::kitty_virtual::{IncompletePlacement, PlaceholderRun, compute_run_geometry};
use rio_vt::crosswords::pos::Column;
-use crate::inline::{InlineAnchor, InlineObject, InlineStyle, KittyInlineObject, RasterObject};
-use crate::vt::{self, CellColor, VtTerminal};
+use crate::bitmap_material::BitmapSurfaceMaterial;
+use crate::vt::{self, VtTerminal};
-/// Kitty graphics APC prefix.
-pub const KITTY_APC_START: &[u8] = b"\x1b_G";
-const ST: &[u8] = b"\x1b\\";
-const C1_ST: u8 = 0x9c;
+/// Marker for one native Kitty draw entity.
+#[derive(Component)]
+pub struct TerminalKittyPlacement;
-/// Parser state for Kitty graphics sequences.
-#[derive(Default)]
-pub struct KittyParserState {
- transfer: Option,
- next_object_id: u32,
+/// Stable Bevy image asset for one Kitty protocol image id.
+pub(crate) struct KittyImageAsset {
+ pub(crate) handle: Handle,
+ pub(crate) width: u32,
+ pub(crate) height: u32,
}
-impl KittyParserState {
- /// Consumes a Kitty graphics APC sequence.
- pub fn consume_sequence(
- &mut self,
- sequence: &[u8],
- cursor_position: (u16, u16),
- ) -> Option {
- if !sequence.starts_with(KITTY_APC_START) {
- return None;
- }
-
- let content_end = if sequence.ends_with(&[C1_ST]) {
- sequence.len() - 1
- } else if sequence.ends_with(ST) {
- sequence.len() - 2
- } else {
- return None;
- };
- let content = &sequence[KITTY_APC_START.len()..content_end];
- let separator = content.iter().position(|byte| *byte == b';')?;
- let header = std::str::from_utf8(&content[..separator]).ok()?;
- let payload = &content[separator + 1..];
+/// Renderer-owned state. Pixel lifetime and placement truth remain in rio-vt.
+#[derive(Default)]
+pub(crate) struct KittyRenderCache {
+ pub(crate) images: HashMap,
+ /// Final queued frontend action per image id. Replacements coalesce so a
+ /// burst of retransmissions cannot retain one decoded pixel buffer per APC.
+ pub(crate) pending_updates: HashMap>,
+ pub(crate) meshes: Vec>,
+ pub(crate) sprite_materials: Vec>,
+ pub(crate) plane_materials: Vec>,
+ dirty: bool,
+}
- let mut params = HashMap::new();
- for part in header.split(',').filter(|part| !part.is_empty()) {
- let Some((key, value)) = part.split_once('=') else {
- continue;
- };
- params.insert(key, value);
+impl KittyRenderCache {
+ pub(crate) fn queue_updates(&mut self, updates: impl IntoIterator
- ) {
+ let mut changed = false;
+ for update in updates {
+ for key in update.remove_queue {
+ let Ok(image_id) = u32::try_from(key) else {
+ continue;
+ };
+ self.pending_updates.insert(image_id, None);
+ changed = true;
+ }
+ for (image_id, graphic) in update.pending_images {
+ self.pending_updates.insert(image_id, Some(graphic));
+ changed = true;
+ }
}
+ self.dirty |= changed;
+ }
- let action = params.get("a").copied().unwrap_or("T");
- match action {
- "T" | "t" => {
- let starts_new_transfer = self.transfer.is_none()
- || params.contains_key("a")
- || params.contains_key("f")
- || params.contains_key("s")
- || params.contains_key("v")
- || params.contains_key("i");
- if starts_new_transfer {
- let object_id = params
- .get("i")
- .and_then(|value| value.parse().ok())
- .unwrap_or(self.next_object_id.max(1));
- self.next_object_id = self.next_object_id.max(object_id + 1);
- self.transfer = Some(KittyTransfer {
- action: action.to_owned(),
- object_id,
- format: params
- .get("f")
- .and_then(|value| value.parse().ok())
- .unwrap_or(100),
- width: params.get("s").and_then(|value| value.parse().ok()),
- height: params.get("v").and_then(|value| value.parse().ok()),
- columns: params.get("c").and_then(|value| value.parse().ok()),
- rows: params.get("r").and_then(|value| value.parse().ok()),
- uses_placeholders: params.get("U").copied() == Some("1"),
- anchor_row: cursor_position.0,
- anchor_col: cursor_position.1,
- bytes: Vec::new(),
- });
- }
-
- let transfer = self.transfer.as_mut()?;
- let chunk = base64::engine::general_purpose::STANDARD
- .decode(payload)
- .ok()?;
- transfer.bytes.extend_from_slice(&chunk);
+ pub(crate) fn is_dirty(&self) -> bool {
+ self.dirty || !self.pending_updates.is_empty()
+ }
- if params.get("m").copied().unwrap_or("0") == "1" {
- return Some(KittyOperation::Pending);
- }
+ pub(crate) fn take_dirty(&mut self) -> bool {
+ std::mem::take(&mut self.dirty)
+ }
- let transfer = self.transfer.take()?;
- let image = transfer.finalize()?;
- if transfer.action == "T" {
- return Some(KittyOperation::TransmitAndPlace {
- object_id: transfer.object_id,
- image,
- anchor: KittyAnchor {
- row: transfer.anchor_row,
- col: transfer.anchor_col,
- columns: transfer.columns.unwrap_or(1),
- rows: transfer.rows.unwrap_or(1),
- },
- });
- }
- Some(KittyOperation::TransmitOnly {
- object_id: transfer.object_id,
- image,
- })
- }
- "p" => Some(KittyOperation::PlaceExisting {
- object_id: params.get("i")?.parse().ok()?,
- anchor: KittyAnchor {
- row: cursor_position.0,
- col: cursor_position.1,
- columns: params
- .get("c")
- .and_then(|value| value.parse().ok())
- .unwrap_or(1),
- rows: params
- .get("r")
- .and_then(|value| value.parse().ok())
- .unwrap_or(1),
- },
- }),
- "d" => Some(match params.get("i").and_then(|value| value.parse().ok()) {
- Some(object_id) => KittyOperation::Delete {
- object_id: Some(object_id),
- },
- None => KittyOperation::Delete { object_id: None },
- }),
- _ => Some(KittyOperation::Ignored),
- }
+ pub(crate) fn mark_dirty(&mut self) {
+ self.dirty = true;
}
}
-/// Decoded Kitty image payload.
-#[derive(Default)]
-pub struct KittyImage {
- /// Image width in pixels.
- pub width: u32,
- /// Image height in pixels.
- pub height: u32,
- /// RGBA image bytes.
- pub rgba: Vec,
- /// Indicates placeholder mode.
- pub uses_placeholders: bool,
+/// One resolved native Kitty quad in terminal-local top-left pixel space.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub(crate) struct KittyDraw {
+ pub(crate) image_id: u32,
+ pub(crate) x: f32,
+ pub(crate) y: f32,
+ pub(crate) width: f32,
+ pub(crate) height: f32,
+ pub(crate) source_rect: [f32; 4],
+ pub(crate) z_index: i32,
+ /// Resolved Bevy depth after sorting by the Kitty `(z, image_id)` rule.
+ pub(crate) depth: f32,
}
-impl KittyImage {
- /// Converts the decoded image into an inline object.
- pub fn rasterize(self) -> KittyInlineObject {
- KittyInlineObject {
- raster: RasterObject {
- width: self.width,
- height: self.height,
- rgba: self.rgba,
- handle: None,
- },
- uses_placeholders: self.uses_placeholders,
- plane: None,
- }
+/// Resolves all active-screen direct and Unicode-placeholder placements.
+pub(crate) fn collect_draws(
+ term: &VtTerminal,
+ cache: &KittyRenderCache,
+ cell_width: f32,
+ cell_height: f32,
+ viewport_width: f32,
+ viewport_height: f32,
+) -> Vec {
+ if cell_width <= 0.0 || cell_height <= 0.0 {
+ return Vec::new();
}
-}
-/// Kitty object anchor.
-#[derive(Clone, Copy)]
-pub struct KittyAnchor {
- /// Anchor row.
- pub row: u16,
- /// Anchor column.
- pub col: u16,
- /// Object width in cells.
- pub columns: u32,
- /// Object height in cells.
- pub rows: u32,
-}
+ let viewport = OverlayViewport {
+ cell_width,
+ cell_height,
+ origin_x: 0.0,
+ origin_y: 0.0,
+ history_size: i64::try_from(term.lines_evicted()).unwrap_or(i64::MAX)
+ + i64::try_from(term.history_size()).unwrap_or(i64::MAX),
+ display_offset: i64::try_from(term.display_offset()).unwrap_or(i64::MAX),
+ screen_lines: i64::try_from(term.screen_lines()).unwrap_or(i64::MAX),
+ };
+ let mut draws = Vec::new();
-/// Parsed Kitty graphics operation.
-pub enum KittyOperation {
- /// Indicates a multipart transfer is still pending.
- Pending,
- /// Indicates the sequence was ignored.
- Ignored,
- /// Image registration without placement.
- TransmitOnly {
- /// Object identifier.
- object_id: u32,
- /// Decoded image.
- image: KittyImage,
- },
- /// Image registration with placement.
- TransmitAndPlace {
- /// Object identifier.
- object_id: u32,
- /// Decoded image.
- image: KittyImage,
- /// Placement anchor.
- anchor: KittyAnchor,
- },
- /// Placement of a previously registered image.
- PlaceExisting {
- /// Object identifier.
- object_id: u32,
- /// Placement anchor.
- anchor: KittyAnchor,
- },
- /// Image deletion.
- Delete {
- /// Optional object identifier.
- object_id: Option,
- },
-}
+ for placement in term.graphics.kitty_placements.values() {
+ let Some(image) = cache.images.get(&placement.image_id) else {
+ continue;
+ };
+ let Some(geometry) = kitty_overlay_geometry(
+ placement,
+ image.width as usize,
+ image.height as usize,
+ &viewport,
+ ) else {
+ continue;
+ };
+ let mut draw = KittyDraw {
+ image_id: placement.image_id,
+ x: geometry.x,
+ y: geometry.y,
+ width: geometry.width,
+ height: geometry.height,
+ source_rect: geometry.source_rect,
+ z_index: placement.z_index,
+ depth: 0.0,
+ };
+ if clip_draw(&mut draw, viewport_width, viewport_height) {
+ draws.push(draw);
+ }
+ }
-struct KittyTransfer {
- action: String,
- object_id: u32,
- format: u32,
- width: Option,
- height: Option,
- columns: Option,
- rows: Option,
- uses_placeholders: bool,
- anchor_row: u16,
- anchor_col: u16,
- bytes: Vec,
+ collect_placeholder_draws(
+ term,
+ cache,
+ cell_width,
+ cell_height,
+ viewport_width,
+ viewport_height,
+ &mut draws,
+ );
+ resolve_stack_depths(&mut draws);
+ draws
}
-impl KittyTransfer {
- fn finalize(&self) -> Option {
- let (width, height, rgba) = match self.format {
- 100 => {
- let image =
- image::load_from_memory_with_format(&self.bytes, image::ImageFormat::Png)
- .ok()?;
- let rgba = image.to_rgba8();
- (rgba.width(), rgba.height(), rgba.into_raw())
- }
- 24 => {
- let width = self.width?;
- let height = self.height?;
- let expected = width as usize * height as usize * 3;
- if self.bytes.len() != expected {
- return None;
- }
- let mut rgba = Vec::with_capacity(width as usize * height as usize * 4);
- for rgb in self.bytes.chunks_exact(3) {
- rgba.extend_from_slice(&[rgb[0], rgb[1], rgb[2], 255]);
- }
- (width, height, rgba)
- }
- 32 => {
- let width = self.width?;
- let height = self.height?;
- let expected = width as usize * height as usize * 4;
- if self.bytes.len() != expected {
- return None;
- }
- (width, height, self.bytes.clone())
- }
- _ => return None,
- };
-
- Some(KittyImage {
- width,
- height,
- rgba,
- uses_placeholders: self.uses_placeholders,
- })
+fn resolve_stack_depths(draws: &mut [KittyDraw]) {
+ draws.sort_by_key(|draw| (draw.z_index, draw.image_id));
+ let negative_count = draws.iter().take_while(|draw| draw.z_index < 0).count();
+ for (index, draw) in draws[..negative_count].iter_mut().enumerate() {
+ draw.depth = distributed_depth(-1.5, index, negative_count);
+ }
+ let nonnegative_count = draws.len().saturating_sub(negative_count);
+ for (index, draw) in draws[negative_count..].iter_mut().enumerate() {
+ draw.depth = distributed_depth(1.5, index, nonnegative_count);
}
}
-/// Refreshes placeholder-backed Kitty anchors from the terminal grid.
-pub fn refresh_kitty_placeholder_anchors(
- objects: &HashMap,
- anchors: &mut HashMap,
- term: &VtTerminal,
-) -> bool {
- let placeholder_ids = objects
- .iter()
- .filter_map(|(object_id, object)| match object {
- InlineObject::KittyImage(object) => object.uses_placeholders.then_some(*object_id),
- InlineObject::RgpObject(_) => None,
- })
- .collect::>();
- if placeholder_ids.is_empty() {
- return false;
+fn distributed_depth(center: f32, index: usize, count: usize) -> f32 {
+ if count <= 1 {
+ return center;
}
- let placeholder_lookup = placeholder_ids
- .iter()
- .map(|object_id| (object_id & 0x00ff_ffff, *object_id))
- .collect::>();
+ center - 0.4 + 0.8 * index as f32 / (count - 1) as f32
+}
- let mut bounds = HashMap::::new();
- let rows = u16::try_from(term.screen_lines()).unwrap_or(u16::MAX);
- let cols = u16::try_from(term.columns()).unwrap_or(u16::MAX);
+fn collect_placeholder_draws(
+ term: &VtTerminal,
+ cache: &KittyRenderCache,
+ cell_width: f32,
+ cell_height: f32,
+ viewport_width: f32,
+ viewport_height: f32,
+ draws: &mut Vec,
+) {
let styles = vt::styles(term);
- for row in 0..rows {
+ let columns = term.columns();
+ for screen_line in 0..term.screen_lines() {
+ let Ok(row) = u16::try_from(screen_line) else {
+ break;
+ };
let Some(grid_row) = vt::visible_row(term, row) else {
continue;
};
- // rio-vt flags rows holding a U+10EEEE placeholder, so rows without one
- // skip the per-cell scan entirely.
if !grid_row.kitty_virtual_placeholder {
continue;
}
- for col in 0..cols {
- let square = grid_row[Column(usize::from(col))];
- if square.c() != '\u{10EEEE}' {
+
+ let mut current: Option<(IncompletePlacement, usize)> = None;
+ for col in 0..columns {
+ let square = grid_row[Column(col)];
+ if square.c() != rio_vt::ansi::graphics::KITTY_PLACEHOLDER {
+ flush_placeholder_run(
+ term,
+ cache,
+ current.take(),
+ screen_line,
+ cell_width,
+ cell_height,
+ viewport_width,
+ viewport_height,
+ draws,
+ );
continue;
}
- let (fg, _, _) = vt::cell_attributes(styles, square);
- let CellColor::Rgb(r, g, b) = fg else {
- continue;
- };
- let placeholder_id = ((r as u32) << 16) | ((g as u32) << 8) | (b as u32);
- let Some(object_id) = placeholder_lookup.get(&placeholder_id).copied() else {
- continue;
- };
- bounds
- .entry(object_id)
- .and_modify(|(top, left, bottom, right)| {
- *top = (*top).min(row);
- *left = (*left).min(col);
- *bottom = (*bottom).max(row);
- *right = (*right).max(col);
- })
- .or_insert((row, col, row, col));
+
+ let style = styles
+ .get(usize::from(square.style_id()))
+ .copied()
+ .unwrap_or_default();
+ let combining = square
+ .extras_id()
+ .and_then(|id| term.grid.extras_table.get(id))
+ .map_or(&[][..], |extras| extras.zerowidth.as_slice());
+ let next = IncompletePlacement::from_cell(style.fg, style.underline_color, combining);
+ match current.as_mut() {
+ Some((run, _)) if run.can_append(&next) => run.append(),
+ _ => {
+ flush_placeholder_run(
+ term,
+ cache,
+ current.take(),
+ screen_line,
+ cell_width,
+ cell_height,
+ viewport_width,
+ viewport_height,
+ draws,
+ );
+ current = Some((next, col));
+ }
+ }
}
+ flush_placeholder_run(
+ term,
+ cache,
+ current,
+ screen_line,
+ cell_width,
+ cell_height,
+ viewport_width,
+ viewport_height,
+ draws,
+ );
}
+}
- let mut changed = false;
- for object_id in placeholder_ids {
- if let Some((top, left, bottom, right)) = bounds.get(&object_id).copied() {
- let columns = u32::from(right - left + 1);
- let rows = u32::from(bottom - top + 1);
- let new_anchor = InlineAnchor {
- row: top,
- col: left,
- columns,
- rows,
- style: InlineStyle::default(),
- };
- changed |= anchors
- .insert(object_id, new_anchor)
- .is_none_or(|old_anchor| {
- old_anchor.row != top
- || old_anchor.col != left
- || old_anchor.columns != columns
- || old_anchor.rows != rows
- });
- } else {
- changed |= anchors.remove(&object_id).is_some();
- }
+#[allow(clippy::too_many_arguments)]
+fn flush_placeholder_run(
+ term: &VtTerminal,
+ cache: &KittyRenderCache,
+ current: Option<(IncompletePlacement, usize)>,
+ screen_line: usize,
+ cell_width: f32,
+ cell_height: f32,
+ viewport_width: f32,
+ viewport_height: f32,
+ draws: &mut Vec,
+) {
+ let Some((incomplete, start_col)) = current else {
+ return;
+ };
+ let run: PlaceholderRun = incomplete.complete();
+ let Some(placement) = term
+ .graphics
+ .kitty_virtual_placements
+ .get(&(run.image_id, run.placement_id))
+ else {
+ return;
+ };
+ let Some(image) = cache.images.get(&run.image_id) else {
+ return;
+ };
+ let Some(geometry) = compute_run_geometry(
+ &run,
+ placement.columns,
+ placement.rows,
+ image.width,
+ image.height,
+ (placement.x, placement.y, placement.width, placement.height),
+ cell_width,
+ cell_height,
+ 0.0,
+ 0.0,
+ screen_line,
+ start_col,
+ ) else {
+ return;
+ };
+ let mut draw = KittyDraw {
+ image_id: run.image_id,
+ x: geometry.x,
+ y: geometry.y,
+ width: geometry.width,
+ height: geometry.height,
+ source_rect: geometry.source_rect,
+ z_index: placement.z_index,
+ depth: 0.0,
+ };
+ if clip_draw(&mut draw, viewport_width, viewport_height) {
+ draws.push(draw);
}
+}
- changed
+fn clip_draw(draw: &mut KittyDraw, width: f32, height: f32) -> bool {
+ if draw.width <= 0.0 || draw.height <= 0.0 {
+ return false;
+ }
+ let x0 = draw.x;
+ let y0 = draw.y;
+ let x1 = x0 + draw.width;
+ let y1 = y0 + draw.height;
+ let clipped_x0 = x0.max(0.0);
+ let clipped_y0 = y0.max(0.0);
+ let clipped_x1 = x1.min(width);
+ let clipped_y1 = y1.min(height);
+ if clipped_x1 <= clipped_x0 || clipped_y1 <= clipped_y0 {
+ return false;
+ }
+ let [u0, v0, u1, v1] = draw.source_rect;
+ let left = (clipped_x0 - x0) / draw.width;
+ let right = (clipped_x1 - x0) / draw.width;
+ let top = (clipped_y0 - y0) / draw.height;
+ let bottom = (clipped_y1 - y0) / draw.height;
+ draw.source_rect = [
+ u0 + (u1 - u0) * left,
+ v0 + (v1 - v0) * top,
+ u0 + (u1 - u0) * right,
+ v0 + (v1 - v0) * bottom,
+ ];
+ draw.x = clipped_x0;
+ draw.y = clipped_y0;
+ draw.width = clipped_x1 - clipped_x0;
+ draw.height = clipped_y1 - clipped_y0;
+ true
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn viewport_clipping_adjusts_geometry_and_uv_together() {
+ let mut draw = KittyDraw {
+ image_id: 1,
+ x: -10.0,
+ y: -5.0,
+ width: 20.0,
+ height: 20.0,
+ source_rect: [0.0, 0.0, 1.0, 1.0],
+ z_index: 0,
+ depth: 0.0,
+ };
+ assert!(clip_draw(&mut draw, 100.0, 100.0));
+ assert_eq!(
+ (draw.x, draw.y, draw.width, draw.height),
+ (0.0, 0.0, 10.0, 15.0)
+ );
+ assert_eq!(draw.source_rect, [0.5, 0.25, 1.0, 1.0]);
+ }
+
+ #[test]
+ fn stacking_uses_z_then_image_id_and_keeps_text_boundary() {
+ let draw = |image_id, z_index| KittyDraw {
+ image_id,
+ x: 0.0,
+ y: 0.0,
+ width: 1.0,
+ height: 1.0,
+ source_rect: [0.0, 0.0, 1.0, 1.0],
+ z_index,
+ depth: 0.0,
+ };
+ let mut draws = vec![draw(9, 0), draw(5, -1), draw(3, 0), draw(1, -2)];
+ resolve_stack_depths(&mut draws);
+
+ assert_eq!(
+ draws
+ .iter()
+ .map(|draw| (draw.z_index, draw.image_id))
+ .collect::>(),
+ vec![(-2, 1), (-1, 5), (0, 3), (0, 9)]
+ );
+ assert!(draws.windows(2).all(|pair| pair[0].depth < pair[1].depth));
+ assert!(draws[1].depth < 0.0);
+ assert!(draws[2].depth > 0.0);
+ }
}
diff --git a/src/lib.rs b/src/lib.rs
index dec3810..b3b3821 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -6,6 +6,8 @@
#![warn(missing_docs)]
#![warn(clippy::unwrap_used)]
+pub mod bitmap;
+pub mod bitmap_material;
pub mod camera;
pub mod cli;
pub mod config;
diff --git a/src/model.rs b/src/model.rs
index 615148d..640d545 100644
--- a/src/model.rs
+++ b/src/model.rs
@@ -1,6 +1,6 @@
//! Cursor and object asset loading.
-use std::io::Cursor;
+use std::io::{Cursor, Read};
use std::path::{Component, Path, PathBuf};
use anyhow::{Context, bail, ensure};
@@ -289,6 +289,51 @@ pub fn load_object_source_with_options(
}
}
+/// Loads an RGP path source through a regular-file and encoded-byte boundary.
+///
+/// Unlike trusted application cursor assets, paths arriving from a PTY must
+/// never block on a FIFO/device or read an unbounded file. GLB/GLTF inputs are
+/// decoded synchronously into terminal-owned mesh data before registration.
+pub(crate) fn load_rgp_object_source_with_options(
+ _object_id: u32,
+ path: &Path,
+ options: ObjectLoadOptions,
+ max_encoded_bytes: usize,
+) -> anyhow::Result<(String, ObjectSource, usize, usize)> {
+ let expanded_path = expand_path(path);
+ let (display, extension, bytes) = if expanded_path.exists() {
+ let extension = file_extension(&expanded_path)?;
+ let (canonical, bytes) = read_regular_file_bounded(&expanded_path, max_encoded_bytes)?;
+ (canonical.display().to_string(), extension, bytes)
+ } else {
+ let candidate = object_asset_path(path)?;
+ let extension = file_extension(Path::new(&candidate))?;
+ if let Some(file_name) = Path::new(&candidate)
+ .file_name()
+ .and_then(|name| name.to_str())
+ && let Some(file) = EmbeddedObjects::get(file_name)
+ {
+ ensure!(
+ file.data.len() <= max_encoded_bytes,
+ "RGP object exceeds configured byte limit"
+ );
+ (
+ format!("embedded:{file_name}"),
+ extension,
+ file.data.to_vec(),
+ )
+ } else {
+ let runtime_path = runtime_asset_root().join(&candidate);
+ let (canonical, bytes) = read_regular_file_bounded(&runtime_path, max_encoded_bytes)?;
+ (canonical.display().to_string(), extension, bytes)
+ }
+ };
+ let encoded_bytes = bytes.len();
+ let (source, resident_bytes) =
+ load_rgp_object_bytes(&display, &extension, &bytes, options, max_encoded_bytes)?;
+ Ok((display, source, encoded_bytes, resident_bytes))
+}
+
/// Loads an object source from inline bytes.
///
/// # Errors
@@ -352,6 +397,558 @@ pub fn load_object_source_from_bytes_with_options(
}
}
+/// Loads an inline RGP payload into terminal-owned mesh data.
+pub(crate) fn load_rgp_object_source_from_bytes_with_options(
+ _object_id: u32,
+ format: &str,
+ name: Option<&str>,
+ bytes: &[u8],
+ options: ObjectLoadOptions,
+ max_resident_bytes: usize,
+) -> anyhow::Result<(String, ObjectSource, usize)> {
+ let display_name = name.unwrap_or(match format {
+ "obj" => "payload.obj",
+ "stl" => "payload.stl",
+ "glb" | "gltf" => "payload.glb",
+ _ => "payload",
+ });
+ let (source, resident_bytes) =
+ load_rgp_object_bytes(display_name, format, bytes, options, max_resident_bytes)?;
+ Ok((format!("payload:{display_name}"), source, resident_bytes))
+}
+
+fn load_rgp_object_bytes(
+ display_name: &str,
+ format: &str,
+ bytes: &[u8],
+ options: ObjectLoadOptions,
+ max_resident_bytes: usize,
+) -> anyhow::Result<(ObjectSource, usize)> {
+ let source = match format {
+ "stl" => {
+ validate_rgp_stl_budget(bytes, max_resident_bytes)?;
+ ObjectSource::Stl(load_stl_meshes_from_bytes(bytes)?)
+ }
+ "obj" => {
+ validate_rgp_obj_budget(bytes, max_resident_bytes)?;
+ ObjectSource::Obj(load_obj_meshes_from_bytes(
+ display_name,
+ bytes,
+ options.normalize,
+ )?)
+ }
+ "glb" => {
+ let validated_bytes = validate_rgp_glb_budget(bytes, max_resident_bytes)?;
+ let source = ObjectSource::Obj(vec![load_rgp_glb_mesh_from_bytes(bytes)?]);
+ let resident_bytes = validated_bytes.max(object_source_resident_bytes(&source));
+ ensure!(
+ resident_bytes <= max_resident_bytes,
+ "RGP decoded object exceeds configured byte limit"
+ );
+ return Ok((source, resident_bytes));
+ }
+ "gltf" => bail!("RGP JSON glTF is not accepted; use a self-contained texture-free GLB"),
+ _ => bail!("unsupported object format for {display_name}"),
+ };
+ let resident_bytes = object_source_resident_bytes(&source);
+ ensure!(
+ resident_bytes <= max_resident_bytes,
+ "RGP decoded object exceeds configured byte limit"
+ );
+ Ok((source, resident_bytes))
+}
+
+fn checked_budget_add(total: &mut usize, bytes: usize, limit: usize) -> anyhow::Result<()> {
+ *total = total
+ .checked_add(bytes)
+ .context("RGP decoded object byte count overflow")?;
+ ensure!(
+ *total <= limit,
+ "RGP decoded object exceeds configured byte limit"
+ );
+ Ok(())
+}
+
+/// Bound the allocations `tobj` can derive from OBJ records before invoking it.
+///
+/// `triangulate + single_index` can turn one long polygon into many indices and
+/// duplicate a vertex for each distinct face corner. Counting those records up
+/// front avoids allocating the expanded mesh and only then discovering it is
+/// over budget.
+fn validate_rgp_obj_budget(bytes: &[u8], max_bytes: usize) -> anyhow::Result<()> {
+ // tobj retains both positions and optional inline vertex colors. Charge
+ // both vectors even when a particular `v` record omits RGB so a stream of
+ // colored, unreferenced vertices cannot amplify before mesh validation.
+ const SOURCE_VERTEX_BYTES: usize = 6 * std::mem::size_of::();
+ const SOURCE_NORMAL_BYTES: usize = 3 * std::mem::size_of::();
+ const SOURCE_TEXCOORD_BYTES: usize = 2 * std::mem::size_of::();
+ // Conservatively cover tobj's single-index mesh, its deduplication map,
+ // Bevy's converted vertex buffers, and transient source copies. The
+ // render-lifetime extrusion bound is checked again on the decoded Mesh.
+ const PARSED_RECORD_BYTES: usize = 256;
+ const EXPANDED_CORNER_BYTES: usize = 192;
+
+ let mut estimated = 0usize;
+ for raw_line in bytes.split(|byte| *byte == b'\n') {
+ let line = raw_line
+ .split(|byte| *byte == b'#')
+ .next()
+ .unwrap_or_default();
+ let mut fields = line
+ .split(|byte| byte.is_ascii_whitespace())
+ .filter(|field| !field.is_empty());
+ let Some(record) = fields.next() else {
+ continue;
+ };
+ // tobj first stores private parsed records (including malformed or
+ // ignored faces) before exporting its final mesh. Bound that staging
+ // collection for every nonempty directive, not just rendered data.
+ checked_budget_add(&mut estimated, PARSED_RECORD_BYTES, max_bytes)?;
+ match record {
+ b"v" => checked_budget_add(&mut estimated, SOURCE_VERTEX_BYTES, max_bytes)?,
+ b"vn" => checked_budget_add(&mut estimated, SOURCE_NORMAL_BYTES, max_bytes)?,
+ b"vt" => checked_budget_add(&mut estimated, SOURCE_TEXCOORD_BYTES, max_bytes)?,
+ b"f" => {
+ let corners = fields.count();
+ if corners < 3 {
+ continue;
+ }
+ let corner_bytes = corners
+ .checked_mul(EXPANDED_CORNER_BYTES)
+ .context("RGP OBJ corner byte count overflow")?;
+ checked_budget_add(&mut estimated, corner_bytes, max_bytes)?;
+ let index_bytes = corners
+ .saturating_sub(2)
+ .checked_mul(3)
+ .and_then(|indices| indices.checked_mul(std::mem::size_of::()))
+ .context("RGP OBJ index byte count overflow")?;
+ checked_budget_add(&mut estimated, index_bytes, max_bytes)?;
+ }
+ b"l" | b"p" => bail!("RGP OBJ line and point records are not permitted"),
+ _ => {}
+ }
+ }
+ Ok(())
+}
+
+/// Bound STL parsing and the renderer's expanded per-face mesh before parsing.
+fn validate_rgp_stl_budget(bytes: &[u8], max_bytes: usize) -> anyhow::Result<()> {
+ // stl_io retains indexed vertices, faces, and a deduplication map while
+ // Ratty constructs duplicated per-face Bevy buffers.
+ const EXPANDED_TRIANGLE_BYTES: usize = 384;
+
+ // Match stl_io's probe: only a valid UTF-8 first line beginning with
+ // `solid ` selects its ASCII reader. Every other input is binary, where
+ // the declared face count must describe the complete payload. In
+ // particular, trailing bytes must not make a large binary file fall back
+ // to the allocation-free ASCII estimate while stl_io still parses it as
+ // binary.
+ let first_line_end = bytes
+ .iter()
+ .position(|byte| *byte == b'\n')
+ .map_or(bytes.len(), |index| index.saturating_add(1));
+ let is_ascii = std::str::from_utf8(&bytes[..first_line_end])
+ .is_ok_and(|header| header.starts_with("solid "));
+ let triangle_count = if is_ascii {
+ // ASCII STL contains exactly three `vertex` records per triangle.
+ bytes
+ .split(|byte| *byte == b'\n')
+ .filter(|line| {
+ line.split(|byte| byte.is_ascii_whitespace())
+ .find(|field| !field.is_empty())
+ == Some(b"vertex".as_ref())
+ })
+ .count()
+ .div_ceil(3)
+ } else {
+ let count = bytes.get(80..84).context("RGP binary STL header missing")?;
+ let count = u32::from_le_bytes([count[0], count[1], count[2], count[3]]) as usize;
+ let expected = count
+ .checked_mul(50)
+ .and_then(|bytes| bytes.checked_add(84))
+ .context("RGP binary STL byte count overflow")?;
+ ensure!(
+ expected == bytes.len(),
+ "RGP binary STL length does not match declared face count"
+ );
+ count
+ };
+ let resident_bytes = triangle_count
+ .checked_mul(EXPANDED_TRIANGLE_BYTES)
+ .context("RGP STL decoded byte count overflow")?;
+ ensure!(
+ resident_bytes <= max_bytes,
+ "RGP decoded object exceeds configured byte limit"
+ );
+ Ok(())
+}
+
+/// Validate GLB allocation shape before synchronously decoding it into a Bevy
+/// mesh. RGP accepts self-contained geometry only: external buffers, JSON
+/// glTF, materials, and textures are rejected because their decoded lifetime
+/// cannot be charged safely to the terminal's object budget.
+fn validate_rgp_glb_budget(bytes: &[u8], max_bytes: usize) -> anyhow::Result {
+ validate_rgp_glb_container_before_parse(bytes, max_bytes)?;
+ let glb = gltf::Gltf::from_slice(bytes).context("failed to parse RGP GLB")?;
+ let mut buffers = glb.document.buffers();
+ let buffer = buffers.next().context("RGP GLB BIN buffer missing")?;
+ let blob = glb.blob.as_ref().context("RGP GLB BIN chunk missing")?;
+ ensure!(
+ buffers.next().is_none()
+ && matches!(buffer.source(), gltf::buffer::Source::Bin)
+ && blob.len() >= buffer.length()
+ && blob.len().saturating_sub(buffer.length()) <= 3,
+ "RGP GLB must contain exactly one self-contained BIN buffer"
+ );
+ ensure!(
+ glb.document.images().next().is_none()
+ && glb.document.textures().next().is_none()
+ && glb.document.samplers().next().is_none()
+ && glb.document.materials().next().is_none()
+ && glb.document.extensions_used().next().is_none(),
+ "RGP GLB materials, textures, samplers, and extensions are not permitted"
+ );
+
+ // Keep the accepted GLB shape intentionally small and auditable. Bevy
+ // creates meshes per primitive/use (not per unique accessor) and may
+ // synthesize normals or widen index types, so a generic accessor sum is
+ // not a safe allocation bound for hostile input.
+ ensure!(
+ glb.document.scenes().count() == 1
+ && glb.document.nodes().count() == 1
+ && glb.document.meshes().count() == 1
+ && glb.document.animations().next().is_none()
+ && glb.document.skins().next().is_none()
+ && glb.document.cameras().next().is_none(),
+ "RGP GLB must contain exactly one scene, node, and mesh without animation or skins"
+ );
+ let scene = glb
+ .document
+ .scenes()
+ .next()
+ .context("RGP GLB scene missing")?;
+ let node = glb
+ .document
+ .nodes()
+ .next()
+ .context("RGP GLB node missing")?;
+ let (translation, rotation, scale) = node.transform().decomposed();
+ ensure!(
+ scene.nodes().count() == 1
+ && node.children().next().is_none()
+ && node.camera().is_none()
+ && node.mesh().is_some()
+ && translation == [0.0, 0.0, 0.0]
+ && rotation == [0.0, 0.0, 0.0, 1.0]
+ && scale == [1.0, 1.0, 1.0],
+ "RGP GLB scene must contain one identity-transformed non-nested mesh node"
+ );
+ let mesh = glb
+ .document
+ .meshes()
+ .next()
+ .context("RGP GLB mesh missing")?;
+ let mut primitives = mesh.primitives();
+ let primitive = primitives.next().context("RGP GLB primitive missing")?;
+ ensure!(
+ primitives.next().is_none()
+ && primitive.mode() == gltf::mesh::Mode::Triangles
+ && primitive.material().index().is_none()
+ && primitive.morph_targets().next().is_none(),
+ "RGP GLB must contain one unmaterialed triangle primitive without morph targets"
+ );
+
+ let position = primitive
+ .get(&gltf::mesh::Semantic::Positions)
+ .context("RGP GLB POSITION accessor missing")?;
+ let normal = primitive
+ .get(&gltf::mesh::Semantic::Normals)
+ .context("RGP GLB NORMAL accessor missing")?;
+ ensure!(
+ primitive.attributes().count() == 2
+ && position.data_type() == gltf::accessor::DataType::F32
+ && normal.data_type() == gltf::accessor::DataType::F32
+ && position.dimensions() == gltf::accessor::Dimensions::Vec3
+ && normal.dimensions() == gltf::accessor::Dimensions::Vec3
+ && position.count() == normal.count()
+ && position.count() > 0
+ && position.sparse().is_none()
+ && normal.sparse().is_none(),
+ "RGP GLB accepts only matching non-sparse float POSITION and NORMAL attributes"
+ );
+
+ let position_count = position.count();
+ let mut resident_bytes = bytes.len();
+ for accessor in [position, normal] {
+ let accessor_bytes = accessor
+ .count()
+ .checked_mul(accessor.size())
+ // Parsed source, Bevy CPU asset/staging, and GPU allocation.
+ .and_then(|bytes| bytes.checked_mul(4))
+ .context("RGP GLB vertex byte count overflow")?;
+ checked_budget_add(&mut resident_bytes, accessor_bytes, max_bytes)?;
+ }
+ if let Some(indices) = primitive.indices() {
+ ensure!(
+ matches!(
+ indices.data_type(),
+ gltf::accessor::DataType::U16 | gltf::accessor::DataType::U32
+ ) && indices.dimensions() == gltf::accessor::Dimensions::Scalar
+ && indices.sparse().is_none()
+ && indices.count() % 3 == 0,
+ "RGP GLB indices must be non-sparse U16/U32 triangles"
+ );
+ let index_bytes = indices
+ .count()
+ .checked_mul(indices.size())
+ .and_then(|bytes| bytes.checked_mul(4))
+ .context("RGP GLB index byte count overflow")?;
+ checked_budget_add(&mut resident_bytes, index_bytes, max_bytes)?;
+ } else {
+ ensure!(
+ position_count % 3 == 0,
+ "RGP GLB unindexed vertex count must form triangles"
+ );
+ }
+ Ok(resident_bytes)
+}
+
+/// Decode the already validated single-primitive GLB directly from the exact
+/// bytes that passed the RGP limits. No runtime path or asynchronous asset
+/// lookup remains for a PTY child to replace after validation.
+fn load_rgp_glb_mesh_from_bytes(bytes: &[u8]) -> anyhow::Result {
+ let glb = gltf::Gltf::from_slice(bytes).context("failed to parse RGP GLB")?;
+ let blob = glb.blob.as_deref().context("RGP GLB BIN chunk missing")?;
+ let primitive = glb
+ .document
+ .meshes()
+ .next()
+ .and_then(|mesh| mesh.primitives().next())
+ .context("RGP GLB primitive missing")?;
+ let reader = primitive.reader(|buffer| (buffer.index() == 0).then_some(blob));
+ let positions = reader
+ .read_positions()
+ .context("RGP GLB POSITION data missing")?
+ .collect::>();
+ let normals = reader
+ .read_normals()
+ .context("RGP GLB NORMAL data missing")?
+ .collect::>();
+ ensure!(
+ positions.len() == normals.len()
+ && positions
+ .iter()
+ .chain(&normals)
+ .all(|values| values.iter().all(|value| value.is_finite())),
+ "RGP GLB geometry contains invalid values"
+ );
+ let indices = reader
+ .read_indices()
+ .map(|indices| indices.into_u32().collect::>());
+ if let Some(indices) = indices.as_ref() {
+ ensure!(
+ indices
+ .iter()
+ .all(|index| (*index as usize) < positions.len()),
+ "RGP GLB index is outside the vertex buffer"
+ );
+ }
+
+ let mut mesh = Mesh::new(
+ PrimitiveTopology::TriangleList,
+ RenderAssetUsages::default(),
+ );
+ mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
+ mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
+ if let Some(indices) = indices {
+ mesh.insert_indices(Indices::U32(indices));
+ }
+ Ok(mesh)
+}
+
+const MAX_RGP_GLB_JSON_BYTES: usize = 64 * 1024;
+
+/// Bound the DOM that `gltf::Gltf::from_slice` can allocate before invoking
+/// serde/gltf. Accepted RGP GLBs have one deliberately small geometry shape,
+/// so a large JSON chunk is always hostile or outside the supported subset.
+fn validate_rgp_glb_container_before_parse(bytes: &[u8], max_bytes: usize) -> anyhow::Result<()> {
+ ensure!(
+ bytes.len() <= max_bytes,
+ "RGP GLB exceeds configured byte limit"
+ );
+ ensure!(bytes.len() >= 20, "RGP GLB header is truncated");
+ ensure!(&bytes[..4] == b"glTF", "RGP GLB magic is invalid");
+ let version = u32::from_le_bytes(bytes[4..8].try_into().expect("fixed GLB version slice"));
+ ensure!(version == 2, "RGP GLB version is unsupported");
+ let declared_len =
+ u32::from_le_bytes(bytes[8..12].try_into().expect("fixed GLB length slice")) as usize;
+ ensure!(declared_len == bytes.len(), "RGP GLB length is invalid");
+
+ let json_len =
+ u32::from_le_bytes(bytes[12..16].try_into().expect("fixed JSON length slice")) as usize;
+ let json_type = u32::from_le_bytes(bytes[16..20].try_into().expect("fixed JSON type slice"));
+ ensure!(json_type == 0x4E4F_534A, "RGP GLB JSON chunk is missing");
+ ensure!(
+ json_len <= MAX_RGP_GLB_JSON_BYTES.min(max_bytes),
+ "RGP GLB JSON chunk exceeds supported allocation limit"
+ );
+ let json_end = 20usize
+ .checked_add(json_len)
+ .context("RGP GLB JSON chunk length overflow")?;
+ let bin_header_end = json_end
+ .checked_add(8)
+ .context("RGP GLB BIN header length overflow")?;
+ ensure!(
+ bin_header_end <= bytes.len(),
+ "RGP GLB BIN chunk is missing"
+ );
+ let bin_len = u32::from_le_bytes(
+ bytes[json_end..json_end + 4]
+ .try_into()
+ .expect("fixed BIN length slice"),
+ ) as usize;
+ let bin_type = u32::from_le_bytes(
+ bytes[json_end + 4..bin_header_end]
+ .try_into()
+ .expect("fixed BIN type slice"),
+ );
+ ensure!(bin_type == 0x004E_4942, "RGP GLB BIN chunk is missing");
+ let bin_end = bin_header_end
+ .checked_add(bin_len)
+ .context("RGP GLB BIN chunk length overflow")?;
+ ensure!(
+ bin_end == bytes.len(),
+ "RGP GLB must contain exactly one JSON and one BIN chunk"
+ );
+ Ok(())
+}
+
+fn file_extension(path: &Path) -> anyhow::Result {
+ let extension = path
+ .extension()
+ .and_then(|ext| ext.to_str())
+ .map(str::to_ascii_lowercase)
+ .unwrap_or_default();
+ ensure!(
+ matches!(extension.as_str(), "obj" | "stl" | "glb" | "gltf"),
+ "unsupported object format for {}",
+ path.display()
+ );
+ Ok(extension)
+}
+
+fn read_regular_file_bounded(path: &Path, max_bytes: usize) -> anyhow::Result<(PathBuf, Vec)> {
+ let canonical = std::fs::canonicalize(path)
+ .with_context(|| format!("failed to resolve {}", path.display()))?;
+ let path_metadata = std::fs::metadata(&canonical)
+ .with_context(|| format!("failed to inspect {}", canonical.display()))?;
+ ensure!(
+ path_metadata.file_type().is_file(),
+ "RGP path is not a regular file: {}",
+ canonical.display()
+ );
+ let file = open_rgp_regular_file(&canonical)
+ .with_context(|| format!("failed to open {}", canonical.display()))?;
+ let metadata = file
+ .metadata()
+ .with_context(|| format!("failed to inspect {}", canonical.display()))?;
+ ensure!(
+ metadata.file_type().is_file(),
+ "RGP path is not a regular file: {}",
+ canonical.display()
+ );
+ ensure!(
+ metadata.len() <= max_bytes as u64,
+ "RGP object exceeds configured byte limit"
+ );
+ let mut bytes = Vec::new();
+ file.take((max_bytes as u64).saturating_add(1))
+ .read_to_end(&mut bytes)
+ .with_context(|| format!("failed to read {}", canonical.display()))?;
+ ensure!(
+ bytes.len() <= max_bytes,
+ "RGP object exceeds configured byte limit"
+ );
+ Ok((canonical, bytes))
+}
+
+#[cfg(unix)]
+fn open_rgp_regular_file(path: &Path) -> std::io::Result {
+ use std::os::unix::fs::OpenOptionsExt;
+
+ // `O_NONBLOCK` prevents a raced FIFO from wedging the terminal between
+ // the path metadata check and the descriptor-level fstat check. `O_NOFOLLOW`
+ // rejects a raced final-component symlink; regular files ignore NONBLOCK.
+ std::fs::OpenOptions::new()
+ .read(true)
+ .custom_flags(libc::O_NONBLOCK | libc::O_NOFOLLOW | libc::O_CLOEXEC)
+ .open(path)
+}
+
+#[cfg(not(unix))]
+fn open_rgp_regular_file(path: &Path) -> std::io::Result {
+ std::fs::File::open(path)
+}
+
+/// Approximate persistent CPU/GPU source bytes retained for one decoded RGP object.
+pub(crate) fn object_source_resident_bytes(source: &ObjectSource) -> usize {
+ fn mesh_bytes(mesh: &Mesh) -> usize {
+ let indices = match mesh.indices() {
+ Some(Indices::U16(values)) => values.len().saturating_mul(std::mem::size_of::()),
+ Some(Indices::U32(values)) => values.len().saturating_mul(std::mem::size_of::()),
+ None => 0,
+ };
+ mesh.get_vertex_buffer_size().saturating_add(indices)
+ }
+ fn bounded_render_bytes(mesh: &Mesh) -> usize {
+ let source_bytes = mesh_bytes(mesh);
+ let Some(VertexAttributeValues::Float32x3(positions)) =
+ mesh.attribute(Mesh::ATTRIBUTE_POSITION)
+ else {
+ return source_bytes.saturating_mul(2);
+ };
+ let index_count = mesh.indices().map_or(0, |indices| indices.len());
+ let (min_z, max_z) = positions
+ .iter()
+ .map(|position| position[2])
+ .fold((f32::INFINITY, f32::NEG_INFINITY), |(min, max), z| {
+ (min.min(z), max.max(z))
+ });
+ if (max_z - min_z).abs() > 1e-4 {
+ return source_bytes.saturating_mul(2);
+ }
+
+ // `extrude_mesh` clones the source, duplicates front/back vertices,
+ // builds an edge-count HashMap, and can emit side vertices for every
+ // triangle edge. These conservative factors include the retained
+ // source plus transient and GPU copies.
+ source_bytes
+ .saturating_mul(2)
+ .saturating_add(positions.len().saturating_mul(128))
+ .saturating_add(index_count.saturating_mul(256))
+ }
+ match source {
+ ObjectSource::Obj(meshes) => meshes
+ .iter()
+ .map(bounded_render_bytes)
+ .fold(0usize, usize::saturating_add),
+ ObjectSource::Stl(mesh) => bounded_render_bytes(mesh),
+ ObjectSource::Gltf(path) => std::fs::metadata(runtime_asset_root().join(path))
+ .ok()
+ .and_then(|metadata| usize::try_from(metadata.len()).ok())
+ .unwrap_or(0),
+ }
+}
+
+/// Remove a runtime file materialized exclusively for an RGP GLB/GLTF source.
+pub(crate) fn remove_rgp_materialized_source(source: &ObjectSource) {
+ if let ObjectSource::Gltf(path) = source
+ && Path::new(path).starts_with("objects/rgp")
+ {
+ let _ = std::fs::remove_file(runtime_asset_root().join(path));
+ }
+}
+
fn ensure_scene_asset_path(
candidate: &str,
embedded: Option<(&str, &[u8])>,
@@ -569,3 +1166,177 @@ fn build_meshes(
ensure!(!output.is_empty(), "no mesh content inside {source}");
Ok(output)
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn glb_with_json_and_bin(json: &str, bin: &[u8]) -> Vec {
+ let mut json = json.as_bytes().to_vec();
+ while !json.len().is_multiple_of(4) {
+ json.push(b' ');
+ }
+ let mut bin = bin.to_vec();
+ while !bin.len().is_multiple_of(4) {
+ bin.push(0);
+ }
+ let total_len = 12usize
+ .checked_add(8)
+ .and_then(|len| len.checked_add(json.len()))
+ .and_then(|len| {
+ if bin.is_empty() {
+ Some(len)
+ } else {
+ len.checked_add(8 + bin.len())
+ }
+ })
+ .expect("test GLB length should fit");
+ let mut glb = Vec::with_capacity(total_len);
+ glb.extend_from_slice(b"glTF");
+ glb.extend_from_slice(&2u32.to_le_bytes());
+ glb.extend_from_slice(
+ &u32::try_from(total_len)
+ .expect("test GLB length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(
+ &u32::try_from(json.len())
+ .expect("test JSON length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(&0x4E4F_534Au32.to_le_bytes());
+ glb.extend_from_slice(&json);
+ if !bin.is_empty() {
+ glb.extend_from_slice(
+ &u32::try_from(bin.len())
+ .expect("test BIN length should fit u32")
+ .to_le_bytes(),
+ );
+ glb.extend_from_slice(&0x004E_4942u32.to_le_bytes());
+ glb.extend_from_slice(&bin);
+ }
+ glb
+ }
+
+ fn glb_with_json(json: &str) -> Vec {
+ glb_with_json_and_bin(json, &[])
+ }
+
+ #[test]
+ fn rgp_path_loader_rejects_non_regular_and_oversized_files() {
+ let root = std::env::temp_dir().join(format!("ratty-rgp-path-test-{}", std::process::id()));
+ let directory = root.join("special.glb");
+ std::fs::create_dir_all(&directory).expect("test directory should be creatable");
+ assert!(
+ load_rgp_object_source_with_options(1, &directory, ObjectLoadOptions::default(), 16,)
+ .is_err()
+ );
+
+ let oversized = root.join("oversized.obj");
+ std::fs::write(&oversized, b"v 0 0 0\n").expect("test model should be writable");
+ assert!(
+ load_rgp_object_source_with_options(2, &oversized, ObjectLoadOptions::default(), 4,)
+ .is_err()
+ );
+ let _ = std::fs::remove_file(oversized);
+ let _ = std::fs::remove_dir(directory);
+ let _ = std::fs::remove_dir(root);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn rgp_path_loader_rejects_fifo_without_blocking() {
+ use std::os::unix::ffi::OsStrExt;
+
+ let root = std::env::temp_dir().join(format!(
+ "ratty-rgp-fifo-test-{}-{}",
+ std::process::id(),
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .expect("system clock should follow the Unix epoch")
+ .as_nanos()
+ ));
+ std::fs::create_dir_all(&root).expect("FIFO test directory should be creatable");
+ let fifo = root.join("object.obj");
+ let fifo_path = std::ffi::CString::new(fifo.as_os_str().as_bytes())
+ .expect("temporary FIFO path must not contain NUL");
+ // SAFETY: `fifo_path` is a valid, NUL-terminated path and the mode is
+ // restricted to the current user.
+ let status = unsafe { libc::mkfifo(fifo_path.as_ptr(), 0o600) };
+ assert_eq!(status, 0, "test FIFO should be creatable");
+
+ assert!(
+ load_rgp_object_source_with_options(1, &fifo, ObjectLoadOptions::default(), 1_024)
+ .is_err()
+ );
+ let _ = std::fs::remove_file(fifo);
+ let _ = std::fs::remove_dir(root);
+ }
+
+ #[test]
+ fn rgp_obj_triangulation_expansion_is_rejected_before_parsing() {
+ let mut obj = b"v 0 0 0\n".to_vec();
+ obj.extend_from_slice(b"f");
+ for _ in 0..128 {
+ obj.extend_from_slice(b" 1");
+ }
+ obj.push(b'\n');
+
+ assert!(validate_rgp_obj_budget(&obj, 1_024).is_err());
+ }
+
+ #[test]
+ fn rgp_obj_colored_vertices_are_charged_without_faces() {
+ let obj = b"v 0 0 0 1 0 0\nv 1 0 0 0 1 0\n";
+ assert!(validate_rgp_obj_budget(obj, 2 * 256 + 47).is_err());
+ }
+
+ #[test]
+ fn rgp_obj_one_corner_faces_cannot_amplify_parser_staging() {
+ let obj = b"f 1\n".repeat(8);
+ assert!(validate_rgp_obj_budget(&obj, 7 * 256).is_err());
+ assert!(validate_rgp_obj_budget(b"l 1 2\n", usize::MAX).is_err());
+ }
+
+ #[test]
+ fn rgp_binary_stl_with_trailing_byte_cannot_bypass_triangle_budget() {
+ let triangle_count = 4u32;
+ let mut stl = vec![0u8; 84 + triangle_count as usize * 50];
+ stl[80..84].copy_from_slice(&triangle_count.to_le_bytes());
+ stl.push(0);
+
+ assert!(validate_rgp_stl_budget(&stl, 3 * 384).is_err());
+ }
+
+ #[test]
+ fn rgp_glb_rejects_sparse_expansion_and_textures_before_bevy_load() {
+ let sparse_expansion = glb_with_json(
+ r#"{"asset":{"version":"2.0"},"accessors":[{"componentType":5126,"count":1000000,"type":"VEC3"}]}"#,
+ );
+ assert!(validate_rgp_glb_budget(&sparse_expansion, 1_024).is_err());
+
+ let texture = glb_with_json(
+ r#"{"asset":{"version":"2.0"},"images":[{"uri":"data:image/png;base64,iVBORw0KGgo="}]}"#,
+ );
+ assert!(validate_rgp_glb_budget(&texture, 1_024).is_err());
+ }
+
+ #[test]
+ fn rgp_glb_rejects_multiple_uri_less_buffers_before_bevy_clone() {
+ let json = r#"{"asset":{"version":"2.0"},"scene":0,"scenes":[{"nodes":[0]}],"nodes":[{"mesh":0}],"meshes":[{"primitives":[{"attributes":{"POSITION":0,"NORMAL":1},"indices":2}]}],"buffers":[{"byteLength":78},{"byteLength":78}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":36},{"buffer":0,"byteOffset":36,"byteLength":36},{"buffer":0,"byteOffset":72,"byteLength":6}],"accessors":[{"bufferView":0,"componentType":5126,"count":3,"type":"VEC3","min":[0,0,0],"max":[0,0,0]},{"bufferView":1,"componentType":5126,"count":3,"type":"VEC3"},{"bufferView":2,"componentType":5123,"count":3,"type":"SCALAR"}]}"#;
+ let glb = glb_with_json_and_bin(json, &[0; 78]);
+ assert!(validate_rgp_glb_budget(&glb, 4_096).is_err());
+ }
+
+ #[test]
+ fn rgp_glb_rejects_oversized_json_structure_before_dom_parse() {
+ let nodes = (0..25_000).map(|_| "{}").collect::>().join(",");
+ let json = format!(r#"{{"asset":{{"version":"2.0"}},"nodes":[{nodes}]}}"#);
+ assert!(json.len() > MAX_RGP_GLB_JSON_BYTES);
+ let glb = glb_with_json_and_bin(&json, &[0; 4]);
+
+ let error = validate_rgp_glb_budget(&glb, glb.len())
+ .expect_err("oversized GLB JSON must fail before DOM parsing");
+ assert!(error.to_string().contains("JSON chunk exceeds"));
+ }
+}
diff --git a/src/plugin.rs b/src/plugin.rs
index bd3a1a2..c6648ea 100644
--- a/src/plugin.rs
+++ b/src/plugin.rs
@@ -1,7 +1,12 @@
//! Bevy plugin wiring for the terminal application.
+use bevy::asset::load_internal_asset;
use bevy::prelude::*;
+use bevy::shader::Shader;
+use bevy::sprite_render::Material2dPlugin;
+use crate::bitmap::BitmapLimits;
+use crate::bitmap_material::{BITMAP_SURFACE_SHADER, BitmapSurfaceMaterial};
use crate::camera::{
ActivateTerminalCameraPreset, TerminalCameraSlots, TerminalCameraSystemSet,
TerminalCameraUpdate, activate_terminal_camera_presets, apply_terminal_camera_updates,
@@ -22,7 +27,8 @@ use crate::systems::{
animate_terminal_plane_warp, apply_inline_objects, apply_instance_brightness,
finish_terminal_model_load, handle_window_resize, pump_pty_output, render_terminal_widget,
request_exit_on_primary_window_close, shutdown_terminal_runtime_on_exit,
- sync_asset_to_terminal_cursor, sync_inline_objects, sync_rgp_objects, sync_terminal_materials,
+ sync_asset_to_terminal_cursor, sync_bitmap_placements, sync_inline_objects, sync_rgp_objects,
+ sync_terminal_materials,
};
use crate::terminal::TerminalRedrawState;
@@ -42,8 +48,20 @@ pub struct TerminalPlugin;
impl Plugin for TerminalPlugin {
fn build(&self, app: &mut App) {
- app.init_resource::()
- .init_resource::()
+ let bitmap_limits = app
+ .world()
+ .get_resource::()
+ .map_or_else(BitmapLimits::default, |config| {
+ BitmapLimits::from(&config.bitmap)
+ });
+ load_internal_asset!(
+ app,
+ BITMAP_SURFACE_SHADER,
+ "shaders/bitmap_surface.wgsl",
+ Shader::from_wgsl
+ );
+ app.insert_resource(TerminalInlineObjects::with_bitmap_limits(bitmap_limits))
+ .init_resource::()
.init_resource::()
.init_resource::()
.init_resource::()
@@ -52,7 +70,7 @@ impl Plugin for TerminalPlugin {
.add_message::()
.add_systems(Startup, setup_scene)
.add_systems(Update, request_exit_on_primary_window_close)
- .add_systems(Update, pump_pty_output)
+ .add_systems(Update, pump_pty_output.after(handle_window_resize))
.configure_sets(
Update,
(
@@ -136,8 +154,14 @@ impl Plugin for TerminalPlugin {
)
.add_systems(
Update,
- sync_inline_objects
+ sync_bitmap_placements
.after(TerminalRedrawSet)
+ .after(TerminalCameraSystemSet::Transition),
+ )
+ .add_systems(
+ Update,
+ sync_inline_objects
+ .after(sync_bitmap_placements)
// Deterministic vs the Transition set: on the frame a
// Mobius exit finishes, spawned inline entities must see
// the restored mode, not race it.
@@ -173,6 +197,7 @@ impl Plugin for TerminalPlugin {
.run_if(|config: Res| config.cursor.model.visible),
)
.add_systems(Last, shutdown_terminal_runtime_on_exit)
+ .add_plugins(Material2dPlugin::::default())
.add_plugins(DirectTerminalRenderPlugin)
.add_plugins(TerminalPresentPlugin);
}
diff --git a/src/rgp.rs b/src/rgp.rs
index 92e6d4e..5dd032f 100644
--- a/src/rgp.rs
+++ b/src/rgp.rs
@@ -7,6 +7,8 @@ use crate::scene::TerminalPresentationMode;
/// Ratty Graphics Protocol APC prefix.
pub const RGP_APC_START: &[u8] = b"\x1b_ratty;g;";
+/// Maximum encoded control-header bytes accepted before any RGP payload.
+pub(crate) const RGP_CONTROL_HEADER_LIMIT: usize = 16 * 1024;
const ST: &[u8] = b"\x1b\\";
const C1_ST: u8 = 0x9c;
@@ -105,6 +107,14 @@ impl Default for RgpRegisterOptions {
/// Consumes an RGP APC sequence.
pub fn consume_sequence(sequence: &[u8]) -> Option {
+ consume_sequence_with_payload_limit(sequence, usize::MAX)
+}
+
+/// Consumes an RGP APC sequence while bounding one decoded payload chunk.
+pub(crate) fn consume_sequence_with_payload_limit(
+ sequence: &[u8],
+ max_payload_bytes: usize,
+) -> Option {
if !sequence.starts_with(RGP_APC_START) {
return None;
}
@@ -116,9 +126,15 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
} else {
return None;
};
- let content = std::str::from_utf8(&sequence[RGP_APC_START.len()..content_end]).ok()?;
+ let content_bytes = &sequence[RGP_APC_START.len()..content_end];
+ let payload_start = rgp_payload_start(content_bytes);
+ if payload_start.unwrap_or(content_bytes.len()) > RGP_CONTROL_HEADER_LIMIT {
+ return Some(RgpOperation::Ignored);
+ }
+ let content = std::str::from_utf8(content_bytes).ok()?;
let mut parts = content.split(';');
let verb = parts.next()?;
+ let mut part_offset = verb.len().saturating_add(1);
let mut id = None;
let mut format = None;
let mut path = None;
@@ -128,6 +144,7 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
let mut name = None;
let mut set = None;
let mut invalid_camera_field = false;
+ let mut invalid_style_field = false;
let mut row = None;
let mut col = None;
let mut width = None;
@@ -149,15 +166,21 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
let mut sz = None;
let mut normalize = None;
let mut payload = None;
- for part in parts.filter(|part| !part.is_empty()) {
+ for part in parts {
+ let part_start = part_offset;
+ part_offset = part_offset.saturating_add(part.len()).saturating_add(1);
+ if part.is_empty() {
+ continue;
+ }
+ if payload_start == Some(part_start) {
+ payload = Some(part.to_string());
+ break;
+ }
let Some((key, value)) = part.split_once('=') else {
- if verb == "r" && source.as_deref() == Some("payload") {
- payload = Some(part.to_string());
- break;
- }
// A value-less token in a camera command is a truncated or broken
// emitter; reject the whole command instead of partially applying.
invalid_camera_field |= verb == "c";
+ invalid_style_field |= matches!(verb, "p" | "u");
continue;
};
match key {
@@ -183,47 +206,65 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
"scale" => {
scale = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && scale.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && scale.is_none();
}
"fov" => {
// Degrees on the wire; radians everywhere past this point.
fov = parse_finite_f32(value).map(f32::to_radians);
invalid_camera_field |= verb == "c" && fov.is_none();
}
- "depth" => depth = value.parse().ok(),
+ "depth" => {
+ depth = parse_finite_f32(value);
+ invalid_style_field |= matches!(verb, "p" | "u") && depth.is_none();
+ }
"color" | "tint" => color = parse_color(value),
- "brightness" => brightness = value.parse().ok(),
+ "brightness" => {
+ brightness = parse_finite_f32(value);
+ invalid_style_field |= matches!(verb, "p" | "u") && brightness.is_none();
+ }
"px" => {
px = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && px.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && px.is_none();
}
"py" => {
py = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && py.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && py.is_none();
}
"pz" => {
pz = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && pz.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && pz.is_none();
}
"rx" => {
rx = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && rx.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && rx.is_none();
}
"ry" => {
ry = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && ry.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && ry.is_none();
}
"rz" => {
rz = parse_finite_f32(value);
invalid_camera_field |= verb == "c" && rz.is_none();
+ invalid_style_field |= matches!(verb, "p" | "u") && rz.is_none();
}
- "sx" => sx = value.parse().ok(),
- "sy" => sy = value.parse().ok(),
- "sz" => sz = value.parse().ok(),
- "normalize" => normalize = parse_bool(value),
- _ if verb == "r" && source.as_deref() == Some("payload") => {
- payload = Some(part.to_string());
- break;
+ "sx" => {
+ sx = parse_finite_f32(value);
+ invalid_style_field |= matches!(verb, "p" | "u") && sx.is_none();
+ }
+ "sy" => {
+ sy = parse_finite_f32(value);
+ invalid_style_field |= matches!(verb, "p" | "u") && sy.is_none();
+ }
+ "sz" => {
+ sz = parse_finite_f32(value);
+ invalid_style_field |= matches!(verb, "p" | "u") && sz.is_none();
}
+ "normalize" => normalize = parse_bool(value),
_ => {}
}
}
@@ -269,9 +310,21 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
if source.as_deref() != Some("payload") {
return None;
}
+ let payload = payload.unwrap_or_default();
+ let max_encoded_bytes = max_payload_bytes
+ .checked_add(2)
+ .map(|bytes| bytes / 3)
+ .and_then(|groups| groups.checked_mul(4))
+ .unwrap_or(usize::MAX);
+ if payload.len() > max_encoded_bytes {
+ return Some(RgpOperation::Ignored);
+ }
let data = base64::engine::general_purpose::STANDARD
- .decode(payload.unwrap_or_default())
+ .decode(payload)
.ok()?;
+ if data.len() > max_payload_bytes {
+ return Some(RgpOperation::Ignored);
+ }
RgpRegisterSource::Payload {
name,
more: more.unwrap_or(false),
@@ -279,6 +332,7 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
}
},
}),
+ "p" if invalid_style_field => Some(RgpOperation::Ignored),
"p" => Some(RgpOperation::Place {
object_id: id?,
anchor: RgpAnchor {
@@ -298,6 +352,7 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
},
},
}),
+ "u" if invalid_style_field => Some(RgpOperation::Ignored),
"u" => Some(RgpOperation::Update {
object_id: id?,
update: RgpPlacementUpdate {
@@ -316,6 +371,101 @@ pub fn consume_sequence(sequence: &[u8]) -> Option {
}
}
+fn rgp_payload_start(content: &[u8]) -> Option {
+ let mut tokens = content.split(|byte| *byte == b';');
+ if tokens.next() != Some(b"r".as_slice()) {
+ return None;
+ }
+ let mut offset = 2usize;
+
+ let mut source_is_payload = false;
+ for token in tokens {
+ let token_start = offset;
+ offset = offset.saturating_add(token.len()).saturating_add(1);
+ if token.is_empty() {
+ continue;
+ }
+ if source_is_payload
+ && (!is_known_rgp_control_field(token) || is_standard_base64_token(token))
+ {
+ return Some(token_start);
+ }
+ if let Some(value) = token.strip_prefix(b"source=") {
+ source_is_payload = value == b"payload";
+ }
+ }
+
+ None
+}
+
+fn is_known_rgp_control_field(token: &[u8]) -> bool {
+ let Some(separator) = token.iter().position(|byte| *byte == b'=') else {
+ return false;
+ };
+ matches!(
+ &token[..separator],
+ b"id"
+ | b"fmt"
+ | b"path"
+ | b"type"
+ | b"source"
+ | b"more"
+ | b"name"
+ | b"set"
+ | b"row"
+ | b"col"
+ | b"w"
+ | b"h"
+ | b"animate"
+ | b"scale"
+ | b"fov"
+ | b"depth"
+ | b"color"
+ | b"tint"
+ | b"brightness"
+ | b"px"
+ | b"py"
+ | b"pz"
+ | b"rx"
+ | b"ry"
+ | b"rz"
+ | b"sx"
+ | b"sy"
+ | b"sz"
+ | b"normalize"
+ )
+}
+
+fn is_standard_base64_token(token: &[u8]) -> bool {
+ if token.is_empty() {
+ return true;
+ }
+
+ let mut padding = 0usize;
+ let mut saw_padding = false;
+ for byte in token {
+ if byte.is_ascii_alphanumeric() || matches!(*byte, b'+' | b'/') {
+ if saw_padding {
+ return false;
+ }
+ } else if *byte == b'=' {
+ saw_padding = true;
+ padding = padding.saturating_add(1);
+ if padding > 2 {
+ return false;
+ }
+ } else {
+ return false;
+ }
+ }
+
+ if padding > 0 {
+ token.len().is_multiple_of(4)
+ } else {
+ token.len() % 4 != 1
+ }
+}
+
/// RGP anchor placement.
#[derive(Clone, Copy)]
pub struct RgpAnchor {
@@ -405,7 +555,10 @@ fn parse_bool(value: &str) -> Option {
}
fn parse_finite_f32(value: &str) -> Option {
- value.parse::().ok().filter(|value| value.is_finite())
+ value
+ .parse::()
+ .ok()
+ .filter(|value| value.is_finite() && value.abs() <= 1_000_000.0)
}
#[cfg(test)]
@@ -487,4 +640,87 @@ mod camera_tests {
assert_eq!(settings.camera_type, Some(expected));
}
}
+
+ #[test]
+ fn rejects_non_finite_and_extreme_object_style_floats() {
+ for body in [
+ "p;id=1;row=1;col=1;w=1;h=1;depth=NaN",
+ "p;id=1;row=1;col=1;w=1;h=1;sx=inf",
+ "u;id=1;brightness=-inf",
+ "u;id=1;scale=1000001",
+ ] {
+ let sequence = format!("\x1b_ratty;g;{body}\x1b\\");
+ assert!(
+ matches!(
+ consume_sequence(sequence.as_bytes()),
+ Some(RgpOperation::Ignored)
+ ),
+ "{body}"
+ );
+ }
+ }
+
+ #[test]
+ fn rejects_an_oversized_control_header_before_string_materialization() {
+ let sequence = format!(
+ "\x1b_ratty;g;r;id=1;fmt=obj;path={}\x1b\\",
+ "a".repeat(RGP_CONTROL_HEADER_LIMIT)
+ );
+ assert!(matches!(
+ consume_sequence_with_payload_limit(sequence.as_bytes(), usize::MAX),
+ Some(RgpOperation::Ignored)
+ ));
+ }
+
+ #[test]
+ fn permits_a_payload_larger_than_the_control_header_limit() {
+ let encoded = "A".repeat(RGP_CONTROL_HEADER_LIMIT + 4);
+ let sequence = format!("\x1b_ratty;g;r;id=1;fmt=obj;source=payload;more=0;{encoded}\x1b\\");
+ let Some(RgpOperation::Register {
+ source: RgpRegisterSource::Payload { data, .. },
+ ..
+ }) = consume_sequence_with_payload_limit(sequence.as_bytes(), RGP_CONTROL_HEADER_LIMIT)
+ else {
+ panic!("expected a bounded payload registration");
+ };
+ assert_eq!(data.len(), (RGP_CONTROL_HEADER_LIMIT + 4) / 4 * 3);
+ }
+
+ #[test]
+ fn parses_a_padded_payload_that_looks_like_a_control_field() {
+ let expected = base64::engine::general_purpose::STANDARD
+ .decode("row=")
+ .expect("test payload");
+ for controls in ["", "row=1;"] {
+ let sequence =
+ format!("\x1b_ratty;g;r;id=1;fmt=obj;source=payload;{controls}row=\x1b\\");
+ let Some(RgpOperation::Register {
+ source: RgpRegisterSource::Payload { data, .. },
+ ..
+ }) = consume_sequence_with_payload_limit(sequence.as_bytes(), 16)
+ else {
+ panic!("expected padded payload after {controls:?}");
+ };
+ assert_eq!(
+ data.as_slice(),
+ expected.as_slice(),
+ "controls: {controls:?}"
+ );
+ }
+ }
+
+ #[test]
+ fn duplicate_source_fields_cannot_hide_an_oversized_header() {
+ let content = format!(
+ "r;id=1;fmt=obj;source=payload;source=path;A;name={}",
+ "a".repeat(RGP_CONTROL_HEADER_LIMIT)
+ );
+ assert_eq!(rgp_payload_start(content.as_bytes()), None);
+
+ let sequence = format!("\x1b_ratty;g;{content}\x1b\\");
+ assert!(matches!(
+ consume_sequence_with_payload_limit(sequence.as_bytes(), usize::MAX),
+ Some(RgpOperation::Ignored)
+ ));
+ }
}
diff --git a/src/runtime.rs b/src/runtime.rs
index c745cc0..64df8f0 100644
--- a/src/runtime.rs
+++ b/src/runtime.rs
@@ -16,7 +16,8 @@ use rio_vt::crosswords::{Crosswords, CrosswordsSize};
use rio_vt::event::WindowId;
use rio_vt::performer::handler::Processor;
-use crate::config::AppConfig;
+use crate::bitmap::max_base64_encoded_bytes;
+use crate::config::{AppConfig, BitmapConfig};
use crate::vt::{TerminalEventSink, VtTerminal};
/// Command-line runtime overrides.
@@ -28,6 +29,12 @@ pub struct RuntimeOptions {
pub working_dir: Option,
}
+fn apply_terminal_identity(command: &mut CommandBuilder) {
+ command.env("RATTY_SESSION", "1");
+ command.env("TERM_PROGRAM", "ratty");
+ command.env("TERM_PROGRAM_VERSION", env!("CARGO_PKG_VERSION"));
+}
+
/// Running PTY and parser state.
///
/// The `!Sync` PTY handles (the output channel receiver and the master) live
@@ -125,6 +132,41 @@ fn find_git_bash() -> Option {
}
impl TerminalRuntime {
+ #[cfg(test)]
+ pub(crate) fn for_test(rows: u16, cols: u16) -> Self {
+ let (_tx, rx) = mpsc::channel::>();
+ let sink = TerminalEventSink::default();
+ let mut term = Crosswords::new(
+ CrosswordsSize::new_with_dimensions(
+ usize::from(cols.max(1)),
+ usize::from(rows.max(1)),
+ u32::from(cols.max(1)),
+ u32::from(rows.max(1)),
+ 1,
+ 1,
+ ),
+ CursorShape::Block,
+ sink.clone(),
+ WindowId::from(0),
+ 0,
+ 1000,
+ );
+ configure_kitty_graphics(&mut term, &BitmapConfig::default());
+
+ Self {
+ rx: SyncCell::new(rx),
+ writer: Arc::new(Mutex::new(None)),
+ master: SyncCell::new(None),
+ child: None,
+ reader_thread: None,
+ term,
+ processor: Processor::default(),
+ sink,
+ pty_disconnected: false,
+ shutdown_started: false,
+ }
+ }
+
/// Spawns the shell PTY runtime.
///
/// # Errors
@@ -173,6 +215,7 @@ impl TerminalRuntime {
for (key, value) in &config.env {
cmd.env(key, value);
}
+ apply_terminal_identity(&mut cmd);
let child = pair
.slave
@@ -207,8 +250,15 @@ impl TerminalRuntime {
});
let sink = TerminalEventSink::default();
- let term = Crosswords::new(
- CrosswordsSize::new(usize::from(cols.max(1)), usize::from(rows.max(1))),
+ let mut term = Crosswords::new(
+ CrosswordsSize::new_with_dimensions(
+ usize::from(cols.max(1)),
+ usize::from(rows.max(1)),
+ u32::from(cols.max(1)),
+ u32::from(rows.max(1)),
+ 1,
+ 1,
+ ),
CursorShape::Block,
sink.clone(),
// Route and window ids are Rio's multiplexer bookkeeping; ratty
@@ -217,6 +267,7 @@ impl TerminalRuntime {
0,
config.terminal.scrollback,
);
+ configure_kitty_graphics(&mut term, &config.bitmap);
Ok(Self {
rx: SyncCell::new(rx),
@@ -242,6 +293,11 @@ impl TerminalRuntime {
self.sink.take_replies()
}
+ /// Drains rio-vt graphics uploads and removals in parser order.
+ pub fn take_graphics_updates(&mut self) -> Vec {
+ self.sink.take_graphics_updates()
+ }
+
/// Receives pending PTY output without blocking.
pub fn try_recv(&mut self) -> Result, TryRecvError> {
self.rx.get().try_recv()
@@ -278,8 +334,18 @@ impl TerminalRuntime {
// rio-vt reflows content and resets the scrolling region natively, so
// the grid resize is the whole operation — no snapshot and replay.
- self.term
- .resize(CrosswordsSize::new(usize::from(cols), usize::from(rows)));
+ let pixel_width = u32::from(pw);
+ let pixel_height = u32::from(ph);
+ let cell_width = pixel_width.div_ceil(u32::from(cols));
+ let cell_height = pixel_height.div_ceil(u32::from(rows));
+ self.term.resize(CrosswordsSize::new_with_dimensions(
+ usize::from(cols),
+ usize::from(rows),
+ pixel_width,
+ pixel_height,
+ cell_width,
+ cell_height,
+ ));
}
/// Returns the active kitty keyboard enhancement flags.
@@ -321,8 +387,101 @@ impl TerminalRuntime {
}
}
+fn configure_kitty_graphics(term: &mut VtTerminal, bitmap: &BitmapConfig) {
+ let max_bitmap_bytes = usize::try_from(bitmap.max_bitmap_bytes).unwrap_or(usize::MAX);
+ let max_total_bytes = usize::try_from(bitmap.max_total_bitmap_bytes).unwrap_or(usize::MAX);
+ let max_total_incomplete_bytes =
+ usize::try_from(bitmap.max_pending_bytes).unwrap_or(usize::MAX);
+ let max_encoded_bytes = max_base64_encoded_bytes(bitmap.max_bitmap_bytes);
+ term.set_kitty_graphics_config(rio_vt::ansi::kitty_graphics_protocol::KittyGraphicsConfig {
+ max_encoded_bytes,
+ max_decoded_bytes: max_bitmap_bytes,
+ max_decompressed_bytes: max_bitmap_bytes,
+ max_width: bitmap.max_image_width,
+ max_height: bitmap.max_image_height,
+ max_total_bytes,
+ max_placements: bitmap.max_placements,
+ max_incomplete_transfers: bitmap.max_pending_transfers,
+ max_total_incomplete_bytes,
+ incomplete_timeout: rio_vt::time::Duration::from_secs(10),
+ // Ratty only trusts bytes carried by the PTY stream itself. File,
+ // temp-file, and shared-memory media would let an untrusted child
+ // make the terminal process read or unlink out-of-band resources.
+ allow_direct: true,
+ allow_file: false,
+ allow_temp_file: false,
+ allow_shared_memory: false,
+ });
+}
+
impl Drop for TerminalRuntime {
fn drop(&mut self) {
self.shutdown();
}
}
+
+#[cfg(test)]
+mod tests {
+ use std::ffi::OsStr;
+
+ use super::*;
+
+ #[test]
+ fn ratty_child_environment_identifies_the_terminal() {
+ let mut command = CommandBuilder::new("rchat-tui");
+
+ apply_terminal_identity(&mut command);
+
+ assert_eq!(command.get_env("RATTY_SESSION"), Some(OsStr::new("1")));
+ assert_eq!(command.get_env("TERM_PROGRAM"), Some(OsStr::new("ratty")));
+ assert_eq!(
+ command.get_env("TERM_PROGRAM_VERSION"),
+ Some(OsStr::new(env!("CARGO_PKG_VERSION")))
+ );
+ }
+
+ #[test]
+ fn initial_cell_size_query_has_a_nonzero_fallback() {
+ let mut runtime = TerminalRuntime::for_test(24, 80);
+
+ runtime.process(b"\x1b[16t");
+
+ assert_eq!(runtime.take_replies(), [b"\x1b[6;1;1t".to_vec()]);
+ }
+
+ #[test]
+ fn kitty_limits_and_media_policy_follow_bitmap_configuration() {
+ let mut runtime = TerminalRuntime::for_test(24, 80);
+ let bitmap = BitmapConfig {
+ max_bitmaps: 7,
+ max_placements: 11,
+ max_image_width: 101,
+ max_image_height: 202,
+ max_bitmap_bytes: 303,
+ max_total_bitmap_bytes: 404,
+ max_pending_bytes: 505,
+ max_pending_transfers: 6,
+ };
+
+ configure_kitty_graphics(&mut runtime.term, &bitmap);
+ let config = runtime.term.graphics.kitty_chunking_state.config();
+
+ assert_eq!(config.max_encoded_bytes, 404);
+ assert_eq!(config.max_decoded_bytes, 303);
+ assert_eq!(config.max_decompressed_bytes, 303);
+ assert_eq!(config.max_width, 101);
+ assert_eq!(config.max_height, 202);
+ assert_eq!(config.max_total_bytes, 404);
+ assert_eq!(config.max_placements, 11);
+ assert_eq!(config.max_incomplete_transfers, 6);
+ assert_eq!(config.max_total_incomplete_bytes, 505);
+ assert_eq!(
+ config.incomplete_timeout,
+ rio_vt::time::Duration::from_secs(10)
+ );
+ assert!(config.allow_direct);
+ assert!(!config.allow_file);
+ assert!(!config.allow_temp_file);
+ assert!(!config.allow_shared_memory);
+ }
+}
diff --git a/src/shaders/bitmap_surface.wgsl b/src/shaders/bitmap_surface.wgsl
new file mode 100644
index 0000000..59cf37e
--- /dev/null
+++ b/src/shaders/bitmap_surface.wgsl
@@ -0,0 +1,64 @@
+// Renders one bitmap placement with independent crop, fit, filtering, and opacity.
+#import bevy_sprite::mesh2d_vertex_output::VertexOutput
+
+struct BitmapSurfaceUniform {
+ uv_min: vec2,
+ uv_max: vec2,
+ opacity: f32,
+ filter_mode: u32,
+ content_min: vec2,
+ content_max: vec2