A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: code-mode .screenshot() api (#9232)
Myles Scolnickece866051c5e
diff --git a/marimo/_code_mode/_context.py b/marimo/_code_mode/_context.pyindex 1a5b92ae4d..a4bf79acd9 100644--- a/marimo/_code_mode/_context.py+++ b/marimo/_code_mode/_context.py@@ -88,11 +88,13 @@ from marimo._utils.formatter import DefaultFormatterif TYPE_CHECKING:from collections.abc import Iterator, Sequence+ from os import PathLikefrom types import TracebackTypefrom typing_extensions import Selffrom marimo._ast.cell_manager import CellManager+ from marimo._code_mode.screenshot import _ScreenshotSessionfrom marimo._runtime.dataflow import DirectedGraphfrom marimo._runtime.runtime import Kernel@@ -614,6 +616,7 @@ class AsyncCodeModeContext:self._ui_updates: list[tuple[UIElementId, Any]] = []self._cells_to_run: set[CellId_t] = set()self._entered = False+ self._screenshot_session: _ScreenshotSession | None = Nonedef _require_entered(self) -> None:if not self._entered:@@ -671,6 +674,8 @@ class AsyncCodeModeContext:self._ui_updates = []self._cells_to_run = set()+ await self.close_screenshot_session()+if exc_type is not None:self._packages._reset()return # let exception propagate, discard queued ops@@ -1199,6 +1204,197 @@ class AsyncCodeModeContext:)self._cells_to_run.add(cell_id)+ # ------------------------------------------------------------------+ # Screenshot+ # ------------------------------------------------------------------++ async def screenshot(+ self,+ target: int | str | NotebookCell | None = None,+ *,+ timeout_ms: int = 30_000,+ as_data_url: bool = False,+ save_to: str | PathLike[str] | None = None,+ ) -> bytes | str:+ """Capture a cell's rendered output as a PNG screenshot.++ Launches a headless Chromium browser (reused across calls)+ connected to this server in kiosk mode.++ Requires ``playwright`` + its Chromium binary::++ ctx.install_packages("playwright")+ # then once: python -m playwright install chromium++ Does **not** require ``async with``.++ Args:+ target: Cell to screenshot.++ - ``None`` — last cell.+ - ``int`` — cell index (negative OK).+ - ``str`` — cell ID or name.+ - ``NotebookCell`` — e.g. ``ctx.cells[0]``.++ For an object defined by a cell, resolve first::++ cid = ctx.find_cell_defining_object(chart)+ img = await ctx.screenshot(cid)++ timeout_ms: Max wait (ms) for the output to be visible.+ as_data_url: Return ``data:image/png;base64,...`` str+ instead of raw bytes.+ save_to: Also write the PNG to this path.++ Returns:+ ``bytes`` (PNG), or ``str`` (data URL) if *as_data_url*.++ Raises:+ ScreenshotError: Missing playwright, missing browser,+ unknown cell, empty output, or invisible element.+ """+ from pathlib import Path++ from marimo._code_mode.screenshot import (+ ScreenshotError,+ _ScreenshotSession,+ _to_data_url,+ )+ from marimo._messaging.context import HTTP_REQUEST_CTX++ cell_id = self._resolve_screenshot_target(target)++ # Resolve server URL from the current HTTP request context.+ request = HTTP_REQUEST_CTX.get(None)+ if request is None:+ raise ScreenshotError(+ "Cannot take screenshots: no HTTP request context "+ "available. screenshot() must be called during cell "+ "execution (e.g. from code-mode)."+ )+ # Read trusted server URL and auth token injected by the+ # /execute endpoint (from server config, not request headers).+ server_url: str | None = request.meta.get("screenshot_server_url")+ if server_url is None:+ raise ScreenshotError(+ "Cannot take screenshots: screenshot_server_url not "+ "found in request.meta. This endpoint may not "+ "support screenshots."+ )+ screenshot_auth_token: str | None = request.meta.get(+ "screenshot_auth_token"+ )++ # Lazy-init the screenshot session (browser reuse).+ if self._screenshot_session is None:+ self._screenshot_session = _ScreenshotSession(+ server_url,+ screenshot_auth_token=screenshot_auth_token,+ )++ image = await self._screenshot_session.capture(+ cell_id, timeout_ms=timeout_ms+ )++ if save_to is not None:+ # Screenshot writes are infrequent and small; a sync write+ # keeps the API simple without meaningful blocking cost.+ Path(save_to).write_bytes(image) # noqa: ASYNC240++ if as_data_url:+ return _to_data_url(image)+ return image++ async def close_screenshot_session(self) -> None:+ """Close the Playwright browser opened by :meth:`screenshot`.++ Called automatically in ``__aexit__``. Call this explicitly+ when using ``screenshot()`` outside ``async with`` to avoid+ leaking a headless browser process.+ """+ if self._screenshot_session is not None:+ try:+ await self._screenshot_session.close()+ except Exception:+ LOGGER.debug(+ "Failed to close screenshot session", exc_info=True+ )+ self._screenshot_session = None++ def _resolve_screenshot_target(+ self,+ target: int | str | NotebookCell | None,+ ) -> CellId_t:+ """Resolve a screenshot *target* to a cell ID."""+ from marimo._code_mode.screenshot import ScreenshotError++ if target is None:+ if len(self.cells) == 0:+ raise ScreenshotError(+ "Notebook has no cells. Create and run a cell first."+ )+ return self.cells[-1].id++ if isinstance(target, bool):+ # Guard before the ``int`` branch — ``bool`` subclasses+ # ``int`` in Python, and ``ctx.screenshot(True)`` almost+ # certainly reflects a caller mistake.+ raise TypeError(+ "screenshot target cannot be a bool; pass a cell ID, "+ "cell name, integer index, or NotebookCell."+ )++ if isinstance(target, int):+ try:+ return self.cells[target].id+ except IndexError as exc:+ raise ScreenshotError(+ f"Cell index {target} out of range "+ f"(notebook has {len(self.cells)} cells)."+ ) from exc++ if isinstance(target, str):+ try:+ return self.cells._resolve(target)+ except KeyError as exc:+ raise ScreenshotError(+ f"Unknown cell ID or name: {target!r}."+ ) from exc++ if isinstance(target, NotebookCell):+ return target.id++ raise TypeError(+ f"Unsupported screenshot target type: {type(target).__name__}. "+ "Pass a cell ID (str), cell name (str), integer index, "+ "or NotebookCell."+ )++ def find_cell_defining_object(self, obj: Any) -> CellId_t | None:+ """Return the cell ID whose ``defs`` include a variable bound to *obj*.++ Uses identity (``is``) matching against kernel globals.+ Returns ``None`` if no cell defines *obj*.++ Example::++ cell_id = ctx.find_cell_defining_object(chart)+ if cell_id is not None:+ image = await ctx.screenshot(cell_id)+ """+ globals_map = self.globals+ names = [name for name, value in globals_map.items() if value is obj]+ if not names:+ return None++ graph_cells = self.graph.cells++ name_set = set(names)+ for cell_id, cell_impl in graph_cells.items():+ if name_set & getattr(cell_impl, "defs", set()):+ return cell_id+ return None+# ------------------------------------------------------------------# Apply queued operations# ------------------------------------------------------------------diff --git a/marimo/_code_mode/screenshot.py b/marimo/_code_mode/screenshot.pynew file mode 100644index 0000000000..3648dd5c5f--- /dev/null+++ b/marimo/_code_mode/screenshot.py@@ -0,0 +1,413 @@+# Copyright 2026 Marimo. All rights reserved.+"""Headless Chromium screenshot session for cell outputs.++Lazily launches a browser connected to the running notebook server+in kiosk mode and reuses it across captures.+"""++from __future__ import annotations++import asyncio+import base64+import time+from typing import TYPE_CHECKING, Any++from marimo import _loggers+from marimo._server.export._pdf_raster import (+ WAIT_FOR_NEXT_PAINT,+ WAIT_FOR_PAGE_READY,+)++if TYPE_CHECKING:+ from marimo._types.ids import CellId_t++LOGGER = _loggers.marimo_logger()++_READINESS_TIMEOUT_MS = 90_000+_NETWORK_IDLE_TIMEOUT_MS = 10_000+_VIEWPORT_WIDTH = 1440+_VIEWPORT_HEIGHT = 1000+_DEVICE_SCALE_FACTOR = 2.0++# Minimum slice of `timeout_ms` budget to spend looking for the cell+# container in the DOM. If the container never attaches, we fail fast+# with a clear error (rather than letting the locator consume the full+# user-provided timeout on a branch that will never succeed).+_ATTACH_TIMEOUT_MS = 5_000++# When the container exists but we're probing selector variants for the+# output element, each candidate selector gets a short wait before we+# move on to the next one.+_SELECTOR_PROBE_TIMEOUT_MS = 1_000+++def _suppress() -> Any:+ """contextlib.suppress(Exception) without the import."""+ import contextlib++ return contextlib.suppress(Exception)+++class ScreenshotError(RuntimeError):+ """A cell screenshot could not be captured.++ Messages include actionable hints (available cell IDs,+ install commands, likely misconfigurations).+ """+++def _to_data_url(image: bytes) -> str:+ """Convert raw PNG bytes to a ``data:image/png;base64,...`` string."""+ encoded = base64.b64encode(image).decode("ascii")+ return f"data:image/png;base64,{encoded}"+++def _require_playwright() -> Any:+ """Import ``async_playwright``, raising :class:`ScreenshotError` if missing."""+ from marimo._dependencies.dependencies import DependencyManager++ if not DependencyManager.playwright.has():+ raise ScreenshotError(+ "Playwright is not installed.\n"+ "Fix:\n"+ " 1. pip install playwright\n"+ " 2. python -m playwright install chromium"+ )++ from playwright.async_api import ( # type: ignore[import-not-found]+ async_playwright,+ )++ return async_playwright+++def _raise_browser_missing(err: Exception) -> None:+ """Raise :class:`ScreenshotError` for a missing Chromium binary."""+ raise ScreenshotError(+ "Chromium browser binary is not installed.\n"+ "Fix: python -m playwright install chromium\n"+ f"Underlying error: {err}"+ ) from err+++class _ScreenshotSession:+ """Reusable Playwright browser session for cell screenshots.++ Lazily launches on first :meth:`capture`, reuses across calls.+ Call :meth:`close` to release resources.+ """++ def __init__(+ self, server_url: str, screenshot_auth_token: str | None = None+ ) -> None:+ self._server_url = server_url+ self._screenshot_auth_token = screenshot_auth_token+ self._playwright: Any = None+ self._browser: Any = None+ self._page: Any = None+ self._init_lock = asyncio.Lock()++ async def _ensure_ready(self) -> None:+ """Launch browser and navigate to the notebook if not already done."""+ if self._page is not None:+ return++ async with self._init_lock:+ # Re-check after acquiring the lock.+ if self._page is not None:+ return+ await self._init_browser()++ async def _init_browser(self) -> None:+ """Start Playwright + Chromium and navigate to the kiosk page.++ On failure, any partially-created resources are cleaned up+ before re-raising.+ """+ async_playwright = _require_playwright()++ LOGGER.debug("Screenshot session: launching browser")+ pw = await async_playwright().start()+ browser: Any = None+ page: Any = None+ try:+ try:+ browser = await pw.chromium.launch()+ except Exception as err:+ msg = str(err).lower()+ if (+ "executable doesn't exist" in msg+ or "looks like playwright" in msg+ ):+ _raise_browser_missing(err)+ raise++ context = await browser.new_context(+ viewport={+ "width": _VIEWPORT_WIDTH,+ "height": _VIEWPORT_HEIGHT,+ },+ device_scale_factor=_DEVICE_SCALE_FACTOR,+ )+ page = await context.new_page()+ await page.emulate_media(reduced_motion="reduce")++ # Commit only after full success.+ self._playwright = pw+ self._browser = browser+ self._page = page+ await self._navigate(initial=True)+ LOGGER.debug("Screenshot session: ready")+ except BaseException:+ # Clean up partially-created resources.+ if browser is not None:+ with _suppress():+ await browser.close()+ with _suppress():+ await pw.stop()+ raise++ async def _navigate(self, *, initial: bool) -> None:+ """Navigate (initial=True) or reload (initial=False) the kiosk page."""+ assert self._page is not None++ params = "kiosk=true"+ if self._screenshot_auth_token:+ params += f"&access_token={self._screenshot_auth_token}"+ page_url = f"{self._server_url}?{params}"+ if initial:+ LOGGER.debug(+ "Screenshot session: navigating to %s", self._server_url+ )+ await self._page.goto(page_url, wait_until="domcontentloaded")+ else:+ LOGGER.debug("Screenshot session: reloading page")+ await self._page.reload(wait_until="domcontentloaded")++ try:+ await self._page.wait_for_function(+ WAIT_FOR_PAGE_READY, timeout=_READINESS_TIMEOUT_MS+ )+ except Exception:+ LOGGER.warning(+ "Screenshot session: page readiness check timed out"+ )++ try:+ await self._page.wait_for_load_state(+ "networkidle", timeout=_NETWORK_IDLE_TIMEOUT_MS+ )+ except Exception:+ pass++ async def capture(+ self,+ cell_id: CellId_t,+ *,+ timeout_ms: int = 30_000,+ ) -> bytes:+ """Screenshot a cell's output and return PNG bytes.++ Raises :class:`ScreenshotError` if the cell container is+ missing, has no content, or no output element becomes visible.+ """+ await self._ensure_ready()+ assert self._page is not None++ LOGGER.debug("Screenshot: capturing cell %s", cell_id)++ # Step 1: find the cell container in the DOM. The page is+ # cached, so if a cell was added after launch we reload once.+ container_selector = f"#output-{cell_id}"+ attach_timeout = min(_ATTACH_TIMEOUT_MS, timeout_ms)+ try:+ await self._wait_for_container(+ container_selector, timeout=attach_timeout+ )+ except Exception:+ LOGGER.debug(+ "Screenshot: container %s missing, reloading page once",+ container_selector,+ )+ try:+ await self._navigate(initial=False)+ except Exception:+ # If reload itself blows up, fall through to the+ # original error path — we still want to surface the+ # missing-container hints to the caller.+ LOGGER.warning("Screenshot: page reload failed")+ try:+ await self._wait_for_container(+ container_selector, timeout=attach_timeout+ )+ except Exception as err:+ available = await self._list_cell_ids()+ raise ScreenshotError(+ self._format_missing_container_error(cell_id, available)+ ) from err++ # Step 2: container exists but may be empty (cell not run, or+ # returned None).+ if not await self._container_has_content(container_selector):+ raise ScreenshotError(+ f"Cell {cell_id!r} has no rendered content.\n"+ "Fix: run the cell first (`ctx.run_cell(...)`) and "+ "ensure its last expression is not None."+ )++ # Step 3: resolve the screenshottable element via prioritised+ # selector list (.output, .vega-embed, .plotly, etc.).+ target = await self._resolve_output_locator(+ container_selector, timeout_ms=timeout_ms+ )++ await target.scroll_into_view_if_needed(timeout=timeout_ms)+ await self._page.evaluate(WAIT_FOR_NEXT_PAINT)+ image: bytes = await target.screenshot(+ type="png",+ animations="disabled",+ timeout=timeout_ms,+ )+ LOGGER.debug(+ "Screenshot: captured cell %s (%d bytes)", cell_id, len(image)+ )+ return image++ async def _resolve_output_locator(+ self,+ container_selector: str,+ *,+ timeout_ms: int,+ ) -> Any:+ """Return the first visible locator from a prioritised selector list."""+ assert self._page is not None++ # Most-specific → most-general, then the container itself.+ candidates: list[str] = [+ f"{container_selector} > .output",+ f"{container_selector} > .vega-embed",+ f"{container_selector} > .plotly",+ f"{container_selector} > .anywidget",+ f"{container_selector} > div",+ container_selector,+ ]++ # Track a hard deadline so total probing never exceeds timeout_ms.+ deadline = time.monotonic() + timeout_ms / 1000.0++ last_error: Exception | None = None+ for selector in candidates:+ remaining_ms = max(0, int((deadline - time.monotonic()) * 1000))+ if remaining_ms == 0:+ break+ probe = min(_SELECTOR_PROBE_TIMEOUT_MS, remaining_ms)+ locator = self._page.locator(selector).first+ try:+ await locator.wait_for(state="visible", timeout=probe)+ LOGGER.debug(+ "Screenshot: resolved output via selector %s", selector+ )+ return locator+ except Exception as err:+ last_error = err+ continue++ # Every candidate failed.+ dom_snapshot = await self._describe_container(container_selector)+ raise ScreenshotError(+ f"No visible output element under {container_selector!r}.\n"+ f"Tried: {candidates}\n"+ f"Container: {dom_snapshot}\n"+ "Fix: increase `timeout_ms`, or ensure the output is "+ "not hidden (display:none)."+ ) from last_error++ async def _wait_for_container(+ self, container_selector: str, *, timeout: int+ ) -> None:+ """Wait for a cell output container to attach to the DOM."""+ assert self._page is not None+ await self._page.locator(container_selector).first.wait_for(+ state="attached", timeout=timeout+ )++ async def _list_cell_ids(self) -> list[str]:+ """Return the cell IDs currently rendered on the page."""+ assert self._page is not None+ try:+ ids: list[str] = await self._page.eval_on_selector_all(+ "[id^='output-']",+ "els => els.map(e => e.id.replace(/^output-/, ''))",+ )+ return ids+ except Exception:+ return []++ async def _container_has_content(self, container_selector: str) -> bool:+ """Whether the cell container has any rendered children."""+ assert self._page is not None+ try:+ return bool(+ await self._page.eval_on_selector(+ container_selector,+ "el => el.children.length > 0 "+ "|| el.textContent.trim().length > 0",+ )+ )+ except Exception:+ return False++ async def _describe_container(self, container_selector: str) -> str:+ """Human-readable snapshot of the container for error messages."""+ assert self._page is not None+ try:+ info = await self._page.eval_on_selector(+ container_selector,+ """el => ({+ childCount: el.children.length,+ firstChildTag: el.children[0]?.tagName ?? null,+ firstChildClass: el.children[0]?.className ?? null,+ innerLen: el.innerHTML.length,+ visible: el.offsetParent !== null,+ })""",+ )+ return str(info)+ except Exception as err:+ return f"<failed to inspect container: {err}>"++ @staticmethod+ def _format_missing_container_error(+ cell_id: CellId_t, available: list[str]+ ) -> str:+ """Compose the error raised when the cell container is absent."""+ if available:+ # Keep the list digestible when there are many cells.+ shown = available[:20]+ truncated = (+ f" (+{len(available) - len(shown)} more)"+ if len(available) > len(shown)+ else ""+ )+ available_line = f"Cells currently on the page: {shown}{truncated}"+ else:+ available_line = (+ "No cell output containers are on the page at all."+ )+ return (+ f"Cell {cell_id!r} not found on the page.\n"+ f"{available_line}\n"+ "Fix: verify the cell ID/name/index, and ensure the "+ "context manager has exited (which flushes new cells "+ "to the frontend)."+ )++ async def close(self) -> None:+ """Release browser resources."""+ if self._browser is not None:+ await self._browser.close()+ self._browser = None+ if self._playwright is not None:+ await self._playwright.stop()+ self._playwright = None+ self._page = None+ LOGGER.debug("Screenshot session: closed")diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex 74dda0c48d..638585f86e 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -301,10 +301,24 @@ async def execute_code(listener = ScratchCellListener()with session.scoped(listener):async with session.scratchpad_lock:+ http_req = HTTPRequest.from_request(request)+ # Inject trusted server URL and auth token for+ # code-mode screenshot support. We use the+ # server's own host/port (from config) rather+ # than the request's Host header to prevent+ # header-spoofing attacks.+ http_req.meta["screenshot_auth_token"] = str(+ app_state.session_manager.auth_token+ )+ base_url = app_state.base_url.rstrip("/")+ scheme = request.url.scheme or "http"+ http_req.meta["screenshot_server_url"] = (+ f"{scheme}://{app_state.host}:{app_state.port}{base_url}"+ )session.put_control_request(ExecuteScratchpadCommand(code=body.code,- request=HTTPRequest.from_request(request),+ request=http_req,notebook_cells=tuple(session.document.cells),),from_consumer_id=None,diff --git a/tests/_code_mode/test_screenshot.py b/tests/_code_mode/test_screenshot.pynew file mode 100644index 0000000000..06718de3d7--- /dev/null+++ b/tests/_code_mode/test_screenshot.py@@ -0,0 +1,183 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import base64+from types import SimpleNamespace+from typing import TYPE_CHECKING++import pytest++from marimo._ast.cell import CellConfig+from marimo._code_mode._context import (+ AsyncCodeModeContext,+ NotebookCell,+)+from marimo._code_mode.screenshot import (+ ScreenshotError,+ _ScreenshotSession,+ _to_data_url,+)+from marimo._messaging.notebook.document import (+ NotebookCell as _DocNotebookCell,+)+from marimo._types.ids import CellId_t++if TYPE_CHECKING:+ from typing import Any+++class TestToDataUrl:+ def test_round_trip(self) -> None:+ payload = b"\x89PNG\r\n\x1a\n"+ result = _to_data_url(payload)+ assert result.startswith("data:image/png;base64,")+ decoded = base64.b64decode(result.split(",", 1)[1])+ assert decoded == payload++ def test_empty(self) -> None:+ result = _to_data_url(b"")+ assert result == "data:image/png;base64,"+++class TestScreenshotSessionAuthUrl:+ def test_url_without_auth(self) -> None:+ session = _ScreenshotSession("http://localhost:1234")+ assert session._server_url == "http://localhost:1234"+ assert session._screenshot_auth_token is None++ def test_url_with_auth(self) -> None:+ session = _ScreenshotSession(+ "http://localhost:1234", screenshot_auth_token="tok123"+ )+ assert session._screenshot_auth_token == "tok123"++ def test_page_url_includes_screenshot_auth_token(self) -> None:+ """The kiosk page URL must include the access_token query param."""+ session = _ScreenshotSession(+ "http://localhost:9999", screenshot_auth_token="secret"+ )+ # Replicate the URL-building logic from _ensure_ready.+ params = "kiosk=true"+ if session._screenshot_auth_token:+ params += f"&access_token={session._screenshot_auth_token}"+ page_url = f"{session._server_url}?{params}"++ assert "access_token=secret" in page_url+ assert "kiosk=true" in page_url++ def test_page_url_omits_token_when_none(self) -> None:+ session = _ScreenshotSession("http://localhost:9999")+ params = "kiosk=true"+ if session._screenshot_auth_token:+ params += f"&access_token={session._screenshot_auth_token}"+ page_url = f"{session._server_url}?{params}"++ assert "access_token" not in page_url+ assert page_url == "http://localhost:9999?kiosk=true"+++class _FakeCells:+ """Minimal stand-in for ``_CellsView`` used by the resolver tests.++ Supports the operations ``_resolve_screenshot_target`` actually+ calls — ``__len__``, integer indexing, and ``_resolve(str)`` — so+ the resolver can run without a live kernel/document.+ """++ def __init__(+ self,+ cell_ids: list[str],+ names: dict[str, str] | None = None,+ ) -> None:+ self._ids = [CellId_t(cid) for cid in cell_ids]+ self._names = names or {}++ def __len__(self) -> int:+ return len(self._ids)++ def __getitem__(self, idx: int) -> Any:+ return SimpleNamespace(id=self._ids[idx])++ def _resolve(self, target: str) -> CellId_t:+ if target in self._ids:+ return CellId_t(target)+ for cid, name in self._names.items():+ if name == target:+ return CellId_t(cid)+ raise KeyError(target)+++def _fake_ctx(cell_ids: list[str], names: dict[str, str] | None = None) -> Any:+ """Build an object usable as ``self`` for the resolver method."""+ return SimpleNamespace(cells=_FakeCells(cell_ids, names))+++def _resolve(ctx: Any, target: Any) -> CellId_t:+ return AsyncCodeModeContext._resolve_screenshot_target(ctx, target)+++class TestResolveScreenshotTarget:+ def test_none_with_empty_notebook_raises(self) -> None:+ with pytest.raises(ScreenshotError, match="no cells"):+ _resolve(_fake_ctx([]), None)++ def test_none_returns_last_cell(self) -> None:+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])+ assert _resolve(ctx, None) == CellId_t("cell-c")++ def test_bool_raises_type_error(self) -> None:+ # ``bool`` is a subclass of ``int``; guard before the int branch+ # so ``ctx.screenshot(True)`` surfaces as a caller mistake.+ ctx = _fake_ctx(["cell-a"])+ with pytest.raises(TypeError, match="bool"):+ _resolve(ctx, True)+ with pytest.raises(TypeError, match="bool"):+ _resolve(ctx, False)++ def test_int_positive_index(self) -> None:+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])+ assert _resolve(ctx, 0) == CellId_t("cell-a")+ assert _resolve(ctx, 1) == CellId_t("cell-b")++ def test_int_negative_index(self) -> None:+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])+ assert _resolve(ctx, -1) == CellId_t("cell-c")+ assert _resolve(ctx, -3) == CellId_t("cell-a")++ def test_int_out_of_range_raises(self) -> None:+ ctx = _fake_ctx(["cell-a"])+ with pytest.raises(ScreenshotError, match="out of range"):+ _resolve(ctx, 5)+ with pytest.raises(ScreenshotError, match="out of range"):+ _resolve(ctx, -2)++ def test_str_resolves_cell_id(self) -> None:+ ctx = _fake_ctx(["cell-a", "cell-b"])+ assert _resolve(ctx, "cell-a") == CellId_t("cell-a")++ def test_str_resolves_cell_name(self) -> None:+ ctx = _fake_ctx(["cell-a", "cell-b"], names={"cell-b": "my_cell"})+ assert _resolve(ctx, "my_cell") == CellId_t("cell-b")++ def test_str_unknown_raises(self) -> None:+ ctx = _fake_ctx(["cell-a"])+ with pytest.raises(ScreenshotError, match="Unknown cell ID or name"):+ _resolve(ctx, "does-not-exist")++ def test_notebook_cell_target(self) -> None:+ doc_cell = _DocNotebookCell(+ id=CellId_t("cell-x"),+ code="x = 1",+ name="",+ config=CellConfig(),+ )+ nb_cell = NotebookCell(doc_cell, cell_impl=None)+ ctx = _fake_ctx(["cell-a"]) # cell-x deliberately not in view+ assert _resolve(ctx, nb_cell) == CellId_t("cell-x")++ def test_unsupported_type_raises(self) -> None:+ ctx = _fake_ctx(["cell-a"])+ with pytest.raises(TypeError, match="Unsupported"):+ _resolve(ctx, 3.14)+ with pytest.raises(TypeError, match="Unsupported"):+ _resolve(ctx, object())diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.pyindex adce1b573a..8d5e28be7a 100644--- a/tests/_server/api/endpoints/test_execution.py+++ b/tests/_server/api/endpoints/test_execution.py@@ -4,7 +4,7 @@ from __future__ import annotationsimport jsonimport sysimport time-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKINGimport pytest@@ -159,6 +159,58 @@ class TestExecutionRoutes_EditMode:assert response.headers["content-type"] == "application/json"assert "success" in response.json()+ @staticmethod+ @with_session(SESSION_ID)+ def test_execute_injects_screenshot_meta(client: TestClient) -> None:+ """`/api/kernel/execute` injects a trusted server URL + auth token+ into ``HTTPRequest.meta`` so ``ctx.screenshot()`` can authenticate+ Playwright against this server. Regression guard: deleting either+ injection line in the endpoint should fail this test.+ """+ from unittest.mock import patch++ from marimo._runtime.commands import ExecuteScratchpadCommand+ from marimo._server import scratchpad as scratchpad_mod++ session = get_session_manager(client).get_session(SESSION_ID)+ assert session is not None++ captured: list[object] = []++ def capture(req: object, from_consumer_id: object) -> None: # noqa: ARG001+ captured.append(req)++ async def empty_stream(self: object): # noqa: ARG001+ if False:+ yield "" # makes this an async generator that yields nothing++ with (+ patch.object(session, "put_control_request", side_effect=capture),+ patch.object(+ scratchpad_mod.ScratchCellListener,+ "stream",+ empty_stream,+ ),+ ):+ response = client.post(+ "/api/kernel/execute",+ headers=HEADERS,+ json={"code": "x = 1"},+ )++ assert response.status_code == 200, response.text++ scratchpad_cmds = [+ c for c in captured if isinstance(c, ExecuteScratchpadCommand)+ ]+ assert len(scratchpad_cmds) == 1, (+ f"expected one ExecuteScratchpadCommand, got {captured!r}"+ )+ meta = scratchpad_cmds[0].request.meta+ assert meta["screenshot_auth_token"] == "fake-token"+ # Mock server uses host="localhost", port=1234, base_url=""+ assert meta["screenshot_server_url"] == "http://localhost:1234"+@staticmethod@with_session(SESSION_ID)def test_takeover_no_file_key(client: TestClient) -> None:@@ -399,7 +451,7 @@ class TestExecutionRoutes_RunMode:def get_printed_object(client: TestClient, cell_id: CellId_t-) -> dict[str, Any]:+) -> dict[str, object]:session = get_session_manager(client).get_session(SESSION_ID)assert session