6ef13b2cc8a6
screenshots.rs
use super::geometry::{CaptureGeometry, UNSUPPORTED_SECONDARY_WINDOW_ERROR};
use super::{CaptureSlot, Sender, Value, WordApp, json};
/// A page rendered by the engine, as base64 PNG in the reply (the same shape as the headless
/// MCP server's `ui.render`).
pub(super) fn render_png(session: &wordcraft_engine::Session, page: u64, scale: f32) -> Result<Value, String> {
let page = usize::try_from(page.max(1)).unwrap_or(usize::MAX).saturating_sub(1);
let l = session.export_layout();
let pg = l.pages.get(page).ok_or_else(|| format!("no page {}", page.saturating_add(1)))?;
let img = wordcraft_render::render_page(&session.doc, pg, scale.clamp(0.1, 8.0), &Default::default());
let png = img.to_png();
Ok(json!({"png": wordcraft_engine::cmd::insert::base64_encode(&png), "width": img.width, "height": img.height, "pages": l.pages.len()}))
}
/// The bounded admission policy for `ui.screenshot` captures. This is the screenshot queue;
/// the engine's 64-entry UI-intent queue is unrelated. The per-image and aggregate limits are
/// working-set limits, not just raw RGBA: encoding a PNG and base64-encoding it for a reply can
/// briefly need several times the raw pixel buffer.
pub(crate) const SCREENSHOT_MAX_REQUESTS: usize = 4;
pub(crate) const SCREENSHOT_MAX_IMAGE_BYTES: usize = 128 * 1024 * 1024;
pub(crate) const SCREENSHOT_MAX_AGGREGATE_BYTES: usize = 256 * 1024 * 1024;
pub(crate) const SCREENSHOT_MAX_RETRIES: u32 = 2;
/// An incompressible PNG of `raw` RGBA bytes. Deflate's stored-block worst case adds five bytes
/// per 64 KiB block; zlib/PNG framing and the encoder's small internal buffers get 64 KiB more.
/// Checked, because every byte count here comes from a hostile window size.
pub(super) fn png_upper_bound(raw: usize) -> Option<usize> {
let blocks = raw.div_ceil(65_535);
raw.checked_add(blocks.checked_mul(5)?)?.checked_add(64 * 1024)
}
/// The length of the base64 text for `bytes`, rounded up, as `base64_encode` produces it.
pub(super) fn base64_upper_bound(bytes: usize) -> Option<usize> {
bytes.div_ceil(3).checked_mul(4)
}
/// Peak memory of one screenshot, in bytes: the completed `ColorImage`, the one straight-alpha
/// RGBA copy handed to the PNG encoder, the PNG buffer, and (for a reply without a path) the
/// base64 string. All of these can be live at once, so admission reserves their sum rather than
/// only the raw pixels or a PNG-only estimate. Checked throughout: a hostile surface size must
/// result in an error, never a wrapped budget.
pub(super) fn working_set(raw: usize, inline_reply: bool) -> Option<usize> {
let png = png_upper_bound(raw)?;
let mut peak = raw.checked_add(raw)?.checked_add(png)?;
if inline_reply {
peak = peak.checked_add(base64_upper_bound(png)?)?;
}
Some(peak)
}
/// One admitted capture. The request owns its token, path, deadline, immutable document identity,
/// geometry and reservation; the shared slot owns the image and its weak callback.
pub(crate) struct Shot {
pub(crate) token: u64,
pub(crate) path: Option<String>,
pub(crate) reply: Sender<Value>,
/// One monotonic deadline for the whole request, including retries.
pub(crate) deadline: f64,
pub(crate) ready_at: f64,
pub(crate) frames: u32,
pub(crate) issued: bool,
pub(crate) retries: u32,
/// The document the request was admitted for. It never changes; a document switch cancels.
pub(crate) document: u64,
/// The viewport of the window the request was admitted for. It never changes; bringing
/// another window forward cancels.
pub(crate) viewport: egui::ViewportId,
pub(crate) geometry: CaptureGeometry,
pub(crate) epoch: u64,
pub(crate) expected: [usize; 2],
/// Admission reservation, including the encoding working set.
pub(crate) bytes: usize,
pub(crate) slot: Option<CaptureSlot>,
pub(crate) callback: Option<egui::ScreenshotCallback>,
}
/// All outstanding `ui.screenshot` requests.
#[derive(Default)]
pub(crate) struct Shots {
pub(crate) token: u64,
pub(crate) requests: Vec<Shot>,
}
impl Shots {
/// Whether any screenshot request is outstanding.
pub(crate) fn in_flight(&self) -> bool {
!self.requests.is_empty()
}
/// Sums, saturating, the admission bytes reserved by outstanding screenshot requests.
fn reserved(&self) -> usize {
self.requests.iter().fold(0usize, |sum, shot| sum.saturating_add(shot.bytes))
}
}
/// Builds a screenshot error reply carrying the request token.
fn error_reply(token: u64, message: impl std::fmt::Display) -> Value {
json!({"ok": false, "error": message.to_string(), "request": token})
}
/// Sends one screenshot error reply, ignoring a disconnected receiver.
fn reject_shot(reply: Sender<Value>, token: u64, message: impl std::fmt::Display) {
let _ = reply.send(error_reply(token, message));
}
/// Advances the screenshot token, wrapping and skipping zero so every request has a non-zero
/// token.
fn next_token(app: &mut WordApp) -> u64 {
let mut token = app.shots.token.wrapping_add(1);
if token == 0 {
token = 1;
}
app.shots.token = token;
token
}
/// Admit one screenshot request against the count and byte budgets **before** a capture is
/// issued. A rejected request gets one error reply, with its request token, and never evicts an
/// earlier request.
pub(crate) fn admit_screenshot(app: &mut WordApp, ctx: &egui::Context, path: Option<String>, reply: Sender<Value>) {
let token = next_token(app);
// An earlier request in this batch may have brought another window forward.
app.refresh_capture_geometry(ctx);
let Some(geometry) = app.capture_geometry.map(|g| CaptureGeometry { document: app.session.document_id(), ..g }) else {
reject_shot(reply, token, "screenshot failed: the window geometry is not known yet");
return;
};
if geometry.viewport != egui::ViewportId::ROOT {
let msg = match app.root_window_info() {
Some((root_key, _doc_id, root_title)) if !root_title.is_empty() => format!(
"screenshot failed: {UNSUPPORTED_SECONDARY_WINDOW_ERROR}. Select the root window first (view.switchWindows {{\"window\": {root_key}}}) for {root_title:?}."
),
Some((root_key, ..)) => format!(
"screenshot failed: {UNSUPPORTED_SECONDARY_WINDOW_ERROR}. Select the root window first (view.switchWindows {{\"window\": {root_key}}})."
),
None => format!("screenshot failed: {UNSUPPORTED_SECONDARY_WINDOW_ERROR}."),
};
reject_shot(reply, token, msg);
return;
}
if let Some(reason) = geometry.unavailable_reason() {
reject_shot(reply, token, format!("screenshot failed: {reason}"));
return;
}
let Some(expected) = geometry.expected_size() else {
reject_shot(reply, token, "screenshot failed: the window has no capturable size");
return;
};
if let Some(reason) = geometry.oversize_reason() {
reject_shot(reply, token, reason);
return;
}
let inline_reply = path.is_none();
let Some(bytes) = geometry.reserved_bytes(inline_reply) else {
reject_shot(reply, token, "screenshot failed: the window size overflows the screenshot budget");
return;
};
if bytes > SCREENSHOT_MAX_IMAGE_BYTES {
reject_shot(
reply,
token,
format!(
"screenshot budget exceeded: {bytes} bytes reserved for one {}×{} image, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit",
expected[0], expected[1]
),
);
return;
}
if app.shots.requests.len() >= SCREENSHOT_MAX_REQUESTS {
reject_shot(
reply,
token,
format!("screenshot budget exceeded: {} requests are already outstanding (limit {SCREENSHOT_MAX_REQUESTS})", app.shots.requests.len()),
);
return;
}
let reserved = app.shots.reserved().saturating_add(bytes);
if reserved > SCREENSHOT_MAX_AGGREGATE_BYTES {
reject_shot(
reply,
token,
format!("screenshot budget exceeded: {reserved} bytes reserved, over the {SCREENSHOT_MAX_AGGREGATE_BYTES}-byte aggregate limit"),
);
return;
}
let (slot, callback) = CaptureSlot::new(ctx, ctx.viewport_id(), SCREENSHOT_MAX_IMAGE_BYTES);
let now = crate::now_ms();
app.shots.requests.push(Shot {
token,
path,
reply,
deadline: now + 8000.0,
ready_at: now + 120.0,
frames: 0,
issued: false,
retries: 0,
document: geometry.document(),
viewport: geometry.viewport,
geometry,
epoch: app.capture_epoch,
expected,
bytes,
slot: Some(slot),
callback: Some(callback),
});
// The capture command is issued from `ui`; while hidden, logic keeps asking for a painted
// frame until it gets there.
ctx.request_repaint();
}
/// Issued only from `ui`, after the layout has settled. Counts one frame per host frame on the
/// first pass, revalidates geometry and the byte reservation, and sends one callback command.
/// `current_pass_index() == 0` is meaningful here because this function is already in a UI pass.
pub(crate) fn issue_screenshots(app: &mut WordApp, ctx: &egui::Context) {
let now = crate::now_ms();
let first_pass = ctx.current_pass_index() == 0;
let mut failures: Vec<(usize, String)> = Vec::new();
for i in 0..app.shots.requests.len() {
let (issued, ready_at, frames) = {
let shot = &app.shots.requests[i];
(shot.issued, shot.ready_at, shot.frames)
};
// Each window issues its own captures, from a pass that drew its layout.
if issued || app.shots.requests[i].viewport != ctx.viewport_id() {
continue;
}
let frames = if first_pass { frames.saturating_add(1) } else { frames };
app.shots.requests[i].frames = frames;
if now < ready_at || frames < 3 {
continue;
}
let Some(current) = app.capture_geometry.map(|g| CaptureGeometry { document: app.session.document_id(), ..g }) else {
failures.push((i, "screenshot failed: the window geometry is not known yet".into()));
continue;
};
if let Some(reason) = current.unavailable_reason() {
failures.push((i, format!("screenshot failed: {reason} while the capture was queued")));
continue;
}
if let Some(reason) = current.moved_reason(app.shots.requests[i].viewport, app.shots.requests[i].document) {
failures.push((i, reason.into()));
continue;
}
let Some(expected) = current.expected_size() else {
failures.push((i, "screenshot failed: the window size overflows the screenshot budget".into()));
continue;
};
if let Some(reason) = current.oversize_reason() {
failures.push((i, reason));
continue;
}
let inline_reply = app.shots.requests[i].path.is_none();
let Some(bytes) = current.reserved_bytes(inline_reply) else {
failures.push((i, "screenshot failed: the window size overflows the screenshot budget".into()));
continue;
};
if bytes > SCREENSHOT_MAX_IMAGE_BYTES {
failures.push((
i,
format!(
"screenshot budget exceeded: {bytes} bytes reserved for one image, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit"
),
));
continue;
}
let others = app.shots.requests.iter().enumerate().filter(|(j, _)| *j != i).fold(0usize, |sum, (_, shot)| sum.saturating_add(shot.bytes));
if others.saturating_add(bytes) > SCREENSHOT_MAX_AGGREGATE_BYTES {
failures.push((i, format!("screenshot budget exceeded: outstanding requests would reserve over {SCREENSHOT_MAX_AGGREGATE_BYTES} bytes")));
continue;
}
let epoch = app.capture_epoch;
let shot = &mut app.shots.requests[i];
shot.geometry = current;
shot.expected = expected;
shot.bytes = bytes;
shot.epoch = epoch;
if let Some(callback) = shot.callback.take() {
ctx.send_viewport_cmd_to(shot.viewport, egui::ViewportCommand::Screenshot(callback));
shot.issued = true;
}
}
for (i, message) in failures.into_iter().rev() {
let shot = app.shots.requests.remove(i);
if let Some(slot) = shot.slot {
slot.cancel();
}
reject_shot(shot.reply, shot.token, message);
}
if app.shots.in_flight() {
ctx.request_repaint_after(std::time::Duration::from_millis(16));
}
}
/// A completed image is either stale because the surface changed (safe to retry once within the
/// deadline) or invalid for this request (report it at once; retrying cannot help).
pub(super) enum ImageCheck {
Stale(String),
Invalid(String),
}
/// The callback's physical size is the host surface texture's extent, rounded independently of
/// the expected `round(logical points × pixels_per_point)`. One physical pixel on each axis is
/// therefore the same surface seen through a different rounding boundary, not a resize.
pub(super) fn dimensions_are_a_rounded_variant(expected: [usize; 2], actual: [usize; 2]) -> bool {
// Both axes are derived from the same logical viewport and the same pixels-per-point; each
// may round at a boundary one pixel away, but a larger change on either axis is a resize.
expected[0].abs_diff(actual[0]) <= 1 && expected[1].abs_diff(actual[1]) <= 1
}
/// Rejects an empty, overflowing, underfilled or oversized image. A size one pixel away from the
/// expected surface is accepted as a rounding variant; a larger difference is stale.
pub(super) fn validate_image(image: &egui::ColorImage, expected: [usize; 2]) -> Result<(), ImageCheck> {
let [width, height] = image.size;
if width == 0 || height == 0 {
return Err(ImageCheck::Invalid("the screenshot has no pixels".to_string()));
}
// A screenshot is issued for one exact logical viewport. Exact equality would reject a valid
// fractional-DPI capture whose callback rounds by one pixel; a larger difference, or a
// different aspect, is a different surface.
if !dimensions_are_a_rounded_variant(expected, [width, height]) {
return Err(ImageCheck::Stale(format!(
"screenshot is {width}×{height} pixels, expected {}×{}: the window changed size while it was captured",
expected[0], expected[1]
)));
}
let pixels = width.checked_mul(height).ok_or_else(|| ImageCheck::Invalid("screenshot dimensions overflow".to_string()))?;
if image.pixels.len() != pixels {
return Err(ImageCheck::Invalid(format!("screenshot has {} pixels for its {width}×{height} dimensions", image.pixels.len())));
}
// The largest image allowed by the one-pixel rounding allowance. The reservation was made for
// the expected size; a sibling one pixel wider or taller is still the same surface.
let largest = expected[0]
.checked_add(1)
.and_then(|w| expected[1].checked_add(1).and_then(|h| w.checked_mul(h)))
.ok_or_else(|| ImageCheck::Invalid("screenshot dimensions overflow".to_string()))?;
if pixels > largest {
return Err(ImageCheck::Invalid(format!("screenshot has {pixels} pixels, over the {largest} allowed by its reservation")));
}
Ok(())
}
/// What one pass over an outstanding screenshot request decides.
enum ShotAction {
Keep,
Remove(Value),
Restart,
}
/// Classify one pending request: deadline first, then admission state, then the completed slot.
fn take_screenshot_action(app: &mut WordApp, index: usize, now: f64, current: Option<CaptureGeometry>, epoch: u64) -> ShotAction {
let completed = {
let shot = &mut app.shots.requests[index];
if now >= shot.deadline {
if let Some(slot) = shot.slot.take() {
slot.cancel();
}
return ShotAction::Remove(error_reply(shot.token, "no frame was presented before the screenshot timeout"));
}
// Before the issue check: a window that closed never draws to issue its capture.
if let Some(reason) = current.and_then(|geometry| geometry.moved_reason(shot.viewport, shot.document)) {
if let Some(slot) = shot.slot.take() {
slot.cancel();
}
return ShotAction::Remove(error_reply(shot.token, reason));
}
if !shot.issued {
return ShotAction::Keep;
}
if let Some(reason) = current.and_then(CaptureGeometry::unavailable_reason) {
if let Some(slot) = shot.slot.take() {
slot.cancel();
}
return ShotAction::Remove(error_reply(shot.token, format!("screenshot failed: {reason} while the capture was pending")));
}
shot.slot.as_ref().and_then(|slot| slot.take())
};
match completed {
None => ShotAction::Keep,
Some(Err(error)) => ShotAction::Remove(error_reply(app.shots.requests[index].token, error)),
Some(Ok(image)) => completed_screenshot_action(app, index, image, current, epoch),
}
}
/// Judge one taken image: its geometry and epoch identity first, then the image's own validity.
fn completed_screenshot_action(
app: &mut WordApp,
index: usize,
image: std::sync::Arc<egui::ColorImage>,
current: Option<CaptureGeometry>,
epoch: u64,
) -> ShotAction {
let shot = &app.shots.requests[index];
let stale = current != Some(shot.geometry) || epoch != shot.epoch;
if stale {
if shot.retries < SCREENSHOT_MAX_RETRIES {
return ShotAction::Restart;
}
return ShotAction::Remove(error_reply(shot.token, "screenshot geometry changed while it was captured; no image was written"));
}
match validate_image(&image, shot.expected) {
Err(ImageCheck::Stale(_)) if shot.retries < SCREENSHOT_MAX_RETRIES => ShotAction::Restart,
Err(ImageCheck::Stale(message) | ImageCheck::Invalid(message)) => ShotAction::Remove(error_reply(shot.token, message)),
Ok(()) => ShotAction::Remove(save_screenshot(image.as_ref(), shot.path.as_deref(), shot.token)),
}
}
/// Drop one request at `index` with its reply, cancelling any slot still held.
fn remove_shot(app: &mut WordApp, index: usize, value: Value) {
let shot = app.shots.requests.remove(index);
if let Some(slot) = shot.slot {
slot.cancel();
}
let _ = shot.reply.send(value);
}
/// Drop one request at `index` and send an error reply for it.
fn reject_removed_shot(app: &mut WordApp, index: usize, message: impl std::fmt::Display) {
let shot = app.shots.requests.remove(index);
if let Some(slot) = shot.slot {
slot.cancel();
}
reject_shot(shot.reply, shot.token, message);
}
/// Reissue the request at `index` against the current geometry. Returns whether it was reissued:
/// a request removed for a refusal keeps `index` for the request that slides into its place.
fn restart_shot(app: &mut WordApp, ctx: &egui::Context, index: usize, now: f64, current: Option<CaptureGeometry>, epoch: u64) -> bool {
let Some(current) = current else {
reject_removed_shot(app, index, "screenshot failed: the window geometry is not known");
return false;
};
let Some(expected) = current.expected_size() else {
reject_removed_shot(app, index, "screenshot failed: the window size overflows the screenshot budget");
return false;
};
if let Some(reason) = current.oversize_reason() {
reject_removed_shot(app, index, reason);
return false;
}
let inline_reply = app.shots.requests[index].path.is_none();
let Some(bytes) = current.reserved_bytes(inline_reply) else {
reject_removed_shot(app, index, "screenshot failed: the window size overflows the screenshot budget");
return false;
};
let others = app.shots.requests.iter().enumerate().filter(|(j, _)| *j != index).fold(0usize, |sum, (_, shot)| sum.saturating_add(shot.bytes));
if bytes > SCREENSHOT_MAX_IMAGE_BYTES || others.saturating_add(bytes) > SCREENSHOT_MAX_AGGREGATE_BYTES {
reject_removed_shot(app, index, "screenshot budget exceeded while retrying after a resize");
return false;
}
let (slot, callback) = CaptureSlot::new(ctx, ctx.viewport_id(), SCREENSHOT_MAX_IMAGE_BYTES);
let shot = &mut app.shots.requests[index];
shot.slot = Some(slot);
shot.callback = Some(callback);
shot.issued = false;
shot.ready_at = now + 120.0;
shot.frames = 0;
shot.retries = shot.retries.saturating_add(1);
shot.geometry = current;
shot.expected = expected;
shot.bytes = bytes;
shot.epoch = epoch;
true
}
/// Called from `logic`: take each completed slot once, check the deadline **before** writing,
/// validate request/document/geometry identity, and only then encode and reply. A late, stale or
/// oversized image is dropped without a file; a document switch cancels instead of rebinding.
pub(crate) fn drain_screenshots(app: &mut WordApp, ctx: &egui::Context) {
let now = crate::now_ms();
let current = app.capture_geometry.map(|g| CaptureGeometry { document: app.session.document_id(), ..g });
let epoch = app.capture_epoch;
let mut i = 0;
while i < app.shots.requests.len() {
match take_screenshot_action(app, i, now, current, epoch) {
ShotAction::Keep => i += 1,
ShotAction::Remove(value) => remove_shot(app, i, value),
ShotAction::Restart => {
if restart_shot(app, ctx, i, now, current, epoch) {
i += 1;
}
}
}
}
if app.shots.in_flight() {
ctx.request_repaint_after(std::time::Duration::from_millis(16));
}
}
/// The screenshot as a straight-alpha PNG, using one RGBA copy rather than the extra full-image
/// copy [`wordcraft_render::Rendered::to_png`] makes for its premultiplied input. The callback's
/// `ColorImage` is premultiplied; PNG stores straight alpha.
fn screenshot_png(image: &egui::ColorImage) -> Option<Vec<u8>> {
let [width, height] = image.size;
if width == 0 || height == 0 {
return None;
}
let pixels = width.checked_mul(height)?;
if image.pixels.len() != pixels {
return None;
}
let mut rgba = Vec::with_capacity(pixels.checked_mul(4)?);
for color in &image.pixels {
let [r, g, b, a] = color.to_array();
if a == 0 || a == 255 {
rgba.extend_from_slice(&[r, g, b, a]);
} else {
let straight = |c: u8| ((u32::from(c) * 255 + u32::from(a) / 2) / u32::from(a)).min(255) as u8;
rgba.extend_from_slice(&[straight(r), straight(g), straight(b), a]);
}
}
let img = image::RgbaImage::from_raw(u32::try_from(width).ok()?, u32::try_from(height).ok()?, rgba)?;
wordcraft_geom::picture::encode_png(&image::DynamicImage::ImageRgba8(img)).ok()
}
/// The window screenshot: written to `path` when one was given, else base64 PNG in the reply
/// (never a fixed name in the shared temporary folder). Every reply carries the request token so
/// a client can correlate it with the admission, timeout and error replies.
pub fn save_screenshot(image: &egui::ColorImage, path: Option<&str>, token: u64) -> Value {
let [w, h] = image.size;
let Some(raw) = w.checked_mul(h).and_then(|pixels| pixels.checked_mul(4)) else {
return error_reply(token, "screenshot dimensions overflow the byte count");
};
let inline_reply = path.is_none();
let Some(peak) = working_set(raw, inline_reply) else {
return error_reply(token, "screenshot working set overflows the byte count");
};
if peak > SCREENSHOT_MAX_IMAGE_BYTES {
return error_reply(
token,
format!("screenshot needs {peak} bytes of working set, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit"),
);
}
let Some(png) = screenshot_png(image) else {
return error_reply(token, "screenshot PNG encoding failed");
};
if png.len() > SCREENSHOT_MAX_IMAGE_BYTES {
return error_reply(token, format!("screenshot PNG uses {} bytes, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit", png.len()));
}
let Some(path) = path else {
let encoded = wordcraft_engine::cmd::insert::base64_encode(&png);
if encoded.len() > SCREENSHOT_MAX_IMAGE_BYTES {
return error_reply(
token,
format!("screenshot base64 reply uses {} bytes, over the {SCREENSHOT_MAX_IMAGE_BYTES}-byte per-image limit", encoded.len()),
);
}
return json!({"ok": true, "request": token, "result": {"png": encoded, "width": w, "height": h}});
};
#[cfg(target_arch = "wasm32")]
let _ = (&png, path);
#[cfg(not(target_arch = "wasm32"))]
{
if !path.to_ascii_lowercase().ends_with(".png") {
return error_reply(token, format!("{path}: a screenshot path must end in .png"));
}
if let Err(e) = wordcraft_engine::io::write_file(path, &png) {
return error_reply(token, e);
}
}
json!({"ok": true, "request": token, "result": {"path": path, "width": w, "height": h}})
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.