Centralize env handling for screenshots

README.md

@@ -110,6 +110,7 @@ Containers that only specify `webterm-theme` are still included and use the defa
 **Environment Variables:**
 - `WEBTERM_DOCKER_USERNAME` - Set to run Docker exec sessions as a specific user (default: root)
 - `WEBTERM_DOCKER_AUTO_COMMAND` - Override the default `auto` command (default: `/bin/bash`). Supports `{container}` placeholder for the container name.
+- `WEBTERM_SCREENSHOT_FORCE_REDRAW` - When set to `true`, send a SIGWINCH-style redraw before generating screenshots (default: false).
 
 Example: Start containers and exec into them as `developer` user:
 ```bash

src/webterm/constants.py

@@ -21,10 +21,12 @@ def get_environ_bool(name: str) -> bool:
         name: Name of environment variable.
 
     Returns:
-        `True` if the env var is "1", otherwise `False`.
+        `True` if the env var is a truthy value, otherwise `False`.
     """
-    has_environ = get_environ(name) == "1"
+    value = get_environ(name)
-    return has_environ
+    if value is None:
+        return False
+    return value.strip().lower() in {"1", "true", "yes", "on"}
 
 
 def get_environ_int(name: str, default: int) -> int:
@@ -49,3 +51,6 @@ def get_environ_int(name: str, default: int) -> int:
 
 DEBUG: Final = get_environ_bool("DEBUG")
 """Enable debug mode."""
+
+SCREENSHOT_FORCE_REDRAW_ENV: Final = "WEBTERM_SCREENSHOT_FORCE_REDRAW"
+"""Environment variable to force redraw before screenshots."""

src/webterm/local_server.py

@@ -42,6 +42,7 @@ DEFAULT_TERMINAL_SIZE = (132, 45)
 
 SCREENSHOT_CACHE_SECONDS = 0.3
 SCREENSHOT_MAX_CACHE_SECONDS = 20.0
+SCREENSHOT_FORCE_REDRAW = constants.get_environ_bool(constants.SCREENSHOT_FORCE_REDRAW_ENV)
 WS_SEND_QUEUE_MAX = 256
 WS_SEND_TIMEOUT = 2.0
 
@@ -843,6 +844,9 @@ class LocalServer:
                 if cached_response is not None:
                     return cached_response
 
+            if SCREENSHOT_FORCE_REDRAW and hasattr(session_process, "force_redraw"):
+                await session_process.force_redraw()  # type: ignore[union-attr]
+
             # Use non-mutating snapshot method to avoid affecting terminal state
             (
                 screen_width,