Skip to content

Drop in a screenshot and convert it to clean code (HTML/Tailwind/React/Vue)

Python

Refactor screenshot preview backend

Abi Raja887c0ec67332
diff --git a/README.md b/README.md
index ada0a63d..fb623ca8 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ Supported stacks:
Default AI models:
- Gemini 3 Flash Preview and Gemini 3.1 Pro Preview - the best models
-- GPT-5.5, GPT-5.2 Codex, and GPT-5.4 Mini
+- GPT-5.5 and GPT-5.4 Mini
- Claude Opus 4.6, Claude Opus 4.8
- z-image-turbo (using Replicate) for image generation
@@ -46,7 +46,7 @@ the best results and lets you compare multiple models per generation.
| Key | Required? | What it unlocks |
|-----|-----------|-----------------|
-| `OPENAI_API_KEY` | One of these three | GPT code-gen variants (GPT-5.5, GPT-5.2 Codex) |
+| `OPENAI_API_KEY` | One of these three | GPT code-gen variants (GPT-5.5, GPT-5.4 Mini) |
| `ANTHROPIC_API_KEY` | One of these three | Claude code-gen variants (Opus 4.8, Fable 5, Sonnet 4.6) |
| `GEMINI_API_KEY` | One of these three — **strongly recommended** | Gemini code-gen variants (3 Flash, 3.1 Pro); extracts real assets from the screenshot; required for video mode |
| `REPLICATE_API_KEY` | **Strongly recommended** | Image editing, background removal, and Replicate-backed image generation — without it, `edit_image` and `remove_background` are unavailable, and image generation falls back to OpenAI if configured |
diff --git a/backend/agent/tools/screenshot_preview.py b/backend/agent/tools/screenshot_preview.py
index dd109636..49aacf91 100644
--- a/backend/agent/tools/screenshot_preview.py
+++ b/backend/agent/tools/screenshot_preview.py
@@ -15,7 +15,7 @@ async def run_screenshot_preview(
*,
file_state: AgentFileState,
) -> ToolExecutionResult:
- """Render the current HTML in headless Chromium and return screenshots.
+ """Render the current HTML and return screenshots.
These previews are for *seeing*, not keeping: the model views them as
attached image bytes (multimodal parts) to verify its work and never
diff --git a/backend/preview_screenshot.py b/backend/preview_screenshot.py
deleted file mode 100644
index 6ed16381..00000000
--- a/backend/preview_screenshot.py
+++ /dev/null
@@ -1,111 +0,0 @@
-import asyncio
-from typing import Dict, Optional, Tuple
-
-from playwright.async_api import (
- Browser,
- Playwright,
- TimeoutError as PlaywrightTimeoutError,
- async_playwright,
-)
-
-VIEWPORT_SIZES: Dict[str, Tuple[int, int]] = {
- "desktop": (1280, 832),
- "mobile": (342, 684),
-}
-
-PAGE_LOAD_TIMEOUT_MS = 15000
-RENDER_SETTLE_MS = 250
-
-_playwright: Optional[Playwright] = None
-_browser: Optional[Browser] = None
-_browser_lock = asyncio.Lock()
-
-# Whether headless Chromium can actually launch on this host. None until the
-# first probe runs. Used to gate the screenshot_preview tool so it isn't
-# offered to the model when Playwright/Chromium isn't properly installed.
-_available: Optional[bool] = None
-
-
-async def probe_screenshot_preview() -> bool:
- """Check (once, cached) whether headless Chromium can launch here.
-
- Launches the shared browser so the result doubles as a warm-up. Catches
- every failure mode — missing browser binary, missing Linux system
- libraries, sandbox errors — and logs why it's disabled.
- """
- global _available
- if _available is not None:
- return _available
- try:
- await _get_browser()
- _available = True
- print("[screenshot_preview] Chromium available — tool enabled.")
- except Exception as exc:
- _available = False
- print(
- "[screenshot_preview] Chromium unavailable — tool disabled. "
- f"Install it with `playwright install chromium`. Cause: {exc}"
- )
- return _available
-
-
-def is_screenshot_preview_available() -> bool:
- """Synchronous accessor for the cached probe result.
-
- Defaults to True when the probe hasn't run yet so we never wrongly hide the
- tool before startup has checked; the runtime still fails safe if a call
- errors. In practice the startup probe sets this before any request.
- """
- return _available if _available is not None else True
-
-
-async def _get_browser() -> Browser:
- global _playwright, _browser
- async with _browser_lock:
- if _browser is None or not _browser.is_connected():
- if _playwright is None:
- _playwright = await async_playwright().start()
- # --no-sandbox: Chromium refuses to launch as root (the user in
- # most containers/hosted Linux) unless the sandbox is disabled.
- _browser = await _playwright.chromium.launch(
- headless=True,
- args=["--no-sandbox"],
- )
- return _browser
-
-
-async def capture_preview_screenshot(
- html: str,
- device: str = "desktop",
- full_page: bool = True,
-) -> bytes:
- """Render HTML in headless Chromium and return PNG bytes.
-
- Runs locally, so the page can load assets served from localhost
- (e.g. /local-assets/ URLs) that an external screenshot API cannot reach.
- """
- browser = await _get_browser()
- width, height = VIEWPORT_SIZES.get(device, VIEWPORT_SIZES["desktop"])
- page = await browser.new_page(
- viewport={"width": width, "height": height},
- device_scale_factor=1,
- )
- try:
- try:
- await page.set_content(
- html,
- wait_until="networkidle",
- timeout=PAGE_LOAD_TIMEOUT_MS,
- )
- except PlaywrightTimeoutError:
- # Content is already set; capture whatever rendered if the
- # network never settles (e.g. pages that poll).
- pass
- try:
- await page.evaluate("document.fonts.ready")
- except Exception:
- pass
- await page.wait_for_timeout(RENDER_SETTLE_MS)
- return await page.screenshot(full_page=full_page, type="png")
- finally:
- await page.close()
diff --git a/backend/preview_screenshot/__init__.py b/backend/preview_screenshot/__init__.py
new file mode 100644
index 00000000..38df4caa
--- /dev/null
+++ b/backend/preview_screenshot/__init__.py
@@ -0,0 +1,29 @@
+"""screenshot_preview rendering: a pluggable backend behind a stable API.
+
+Split for maintainability:
+- ``base`` — the ``ScreenshotBackend`` interface + shared viewports
+- ``playwright_backend`` — the default local-Chromium implementation
+- ``registry`` — the active backend + the functions the app calls
+
+Callers import everything they need straight from ``preview_screenshot``; the
+internal module layout is an implementation detail.
+"""
+
+from preview_screenshot.base import ScreenshotBackend, VIEWPORT_SIZES
+from preview_screenshot.playwright_backend import PlaywrightBackend
+from preview_screenshot.registry import (
+ capture_preview_screenshot,
+ is_screenshot_preview_available,
+ probe_screenshot_preview,
+ set_screenshot_backend,
+)
+
+__all__ = [
+ "ScreenshotBackend",
+ "VIEWPORT_SIZES",
+ "PlaywrightBackend",
+ "capture_preview_screenshot",
+ "is_screenshot_preview_available",
+ "probe_screenshot_preview",
+ "set_screenshot_backend",
+]
diff --git a/backend/preview_screenshot/base.py b/backend/preview_screenshot/base.py
new file mode 100644
index 00000000..6c9160f0
--- /dev/null
+++ b/backend/preview_screenshot/base.py
@@ -0,0 +1,26 @@
+from typing import Dict, Protocol, Tuple
+
+# Device viewports the screenshot_preview tool renders at. Shared by every
+# backend so previews are consistently sized regardless of how they're rendered.
+VIEWPORT_SIZES: Dict[str, Tuple[int, int]] = {
+ "desktop": (1280, 832),
+ "mobile": (342, 684),
+}
+
+
+class ScreenshotBackend(Protocol):
+ """A pluggable renderer for screenshot_preview.
+
+ The default is local Chromium (``PlaywrightBackend``); a deployment can
+ register an alternative — e.g. an external rendering API — via
+ ``set_screenshot_backend`` without the feature code knowing anything about
+ it. The screenshot_preview tool talks only to this interface.
+ """
+
+ async def capture(self, html: str, device: str, full_page: bool) -> bytes:
+ """Render ``html`` to PNG bytes at the given device viewport."""
+ ...
+
+ async def available(self) -> bool:
+ """Whether this backend can run here (warming it up if needed)."""
+ ...
diff --git a/backend/preview_screenshot/playwright_backend.py b/backend/preview_screenshot/playwright_backend.py
new file mode 100644
index 00000000..d31219c5
--- /dev/null
+++ b/backend/preview_screenshot/playwright_backend.py
@@ -0,0 +1,90 @@
+import asyncio
+from typing import Optional
+
+from playwright.async_api import (
+ Browser,
+ Playwright,
+ TimeoutError as PlaywrightTimeoutError,
+ async_playwright,
+)
+
+from preview_screenshot.base import VIEWPORT_SIZES
+
+PAGE_LOAD_TIMEOUT_MS = 15000
+RENDER_SETTLE_MS = 250
+
+
+class PlaywrightBackend:
+ """Default backend: renders in local headless Chromium.
+
+ Runs locally, so the page can load assets served from localhost
+ (e.g. /local-assets/ URLs) that an external screenshot API cannot reach.
+ Holds one shared browser, launched lazily and reused across captures.
+ """
+
+ def __init__(self) -> None:
+ self._playwright: Optional[Playwright] = None
+ self._browser: Optional[Browser] = None
+ self._lock = asyncio.Lock()
+
+ async def _get_browser(self) -> Browser:
+ async with self._lock:
+ if self._browser is None or not self._browser.is_connected():
+ if self._playwright is None:
+ self._playwright = await async_playwright().start()
+ # --no-sandbox: Chromium refuses to launch as root (the user in
+ # most containers/hosted Linux) unless the sandbox is disabled.
+ self._browser = await self._playwright.chromium.launch(
+ headless=True,
+ args=["--no-sandbox"],
+ )
+ return self._browser
+
+ async def available(self) -> bool:
+ """Launch (and warm up) Chromium; report whether it works.
+
+ Catches every failure mode — missing browser binary, missing Linux
+ system libraries, sandbox errors — and logs why it's disabled.
+ """
+ try:
+ await self._get_browser()
+ print("[screenshot_preview] Chromium available — tool enabled.")
+ return True
+ except Exception as exc:
+ print(
+ "[screenshot_preview] Chromium unavailable — tool disabled. "
+ f"Install it with `playwright install chromium`. Cause: {exc}"
+ )
+ return False
+
+ async def capture(
+ self,
+ html: str,
+ device: str = "desktop",
+ full_page: bool = True,
+ ) -> bytes:
+ browser = await self._get_browser()
+ width, height = VIEWPORT_SIZES.get(device, VIEWPORT_SIZES["desktop"])
+ page = await browser.new_page(
+ viewport={"width": width, "height": height},
+ device_scale_factor=1,
+ )
+ try:
+ try:
+ await page.set_content(
+ html,
+ wait_until="networkidle",
+ timeout=PAGE_LOAD_TIMEOUT_MS,
+ )
+ except PlaywrightTimeoutError:
+ # Content is already set; capture whatever rendered if the
+ # network never settles (e.g. pages that poll).
+ pass
+ try:
+ await page.evaluate("document.fonts.ready")
+ except Exception:
+ pass
+ await page.wait_for_timeout(RENDER_SETTLE_MS)
+ return await page.screenshot(full_page=full_page, type="png")
+ finally:
+ await page.close()
diff --git a/backend/preview_screenshot/registry.py b/backend/preview_screenshot/registry.py
new file mode 100644
index 00000000..09d08325
--- /dev/null
+++ b/backend/preview_screenshot/registry.py
@@ -0,0 +1,49 @@
+from typing import Optional
+
+from preview_screenshot.base import ScreenshotBackend
+from preview_screenshot.playwright_backend import PlaywrightBackend
+
+# The active backend. Defaults to local Chromium; a deployment can swap in an
+# alternative (e.g. an external rendering API) via set_screenshot_backend.
+_backend: ScreenshotBackend = PlaywrightBackend()
+
+# Cached result of the startup probe: whether _backend can run here. None until
+# the first probe runs. Used to gate the tool so it isn't offered when it can't.
+_available: Optional[bool] = None
+
+
+def set_screenshot_backend(backend: ScreenshotBackend) -> None:
+ """Install the screenshot backend (call once, before the startup probe)."""
+ global _backend
+ _backend = backend
+
+
+async def probe_screenshot_preview() -> bool:
+ """Check (once, cached) whether the active backend can run here."""
+ global _available
+ if _available is None:
+ _available = await _backend.available()
+ return _available
+
+
+def is_screenshot_preview_available() -> bool:
+ """Synchronous accessor for the cached probe result.
+
+ Defaults to True when the probe hasn't run yet so we never wrongly hide the
+ tool before startup has checked; the runtime still fails safe if a call
+ errors. In practice the startup probe sets this before any request.
+ """
+ return _available if _available is not None else True
+
+
+async def capture_preview_screenshot(
+ html: str,
+ device: str = "desktop",
+ full_page: bool = True,
+) -> bytes:
+ """Render HTML to PNG via the active backend.
+
+ The public entry point the screenshot_preview tool calls; the backend choice
+ is invisible to callers.
+ """
+ return await _backend.capture(html, device, full_page)