fix: resolve blank slides and broken links in server-side PDF export (#10501)

Author: Jacopos311

marimo/_export/exporter.py

@@ -686,6 +686,14 @@ async def export_as_slides_pdf(
         import nbformat
 
         notebook = nbformat.reads(ipynb_json_str, as_version=4)  # type: ignore[no-untyped-call]
+
+        # Inline virtual file references in cell outputs so that plot images
+        # and other media served via marimo's virtual file system are resolved
+        # to data URIs before nbconvert renders the reveal.js HTML. Without this
+        # step, image src attributes like `./@file/12345-plot.png` become broken
+        # links when Playwright loads the HTML from a temporary file:// URI.
+        self._inline_virtual_files_in_notebook(notebook)
+
         if request.png_fallbacks:
             from marimo._export._nbformat_png_fallbacks import (
                 inject_png_fallbacks_into_notebook,
@@ -704,6 +712,54 @@ async def export_as_slides_pdf(
             notebook, request.options.include_inputs
         )
 
+    @staticmethod
+    def _inline_virtual_files_in_notebook(notebook: Any) -> None:
+        """Replace virtual file URLs with data URIs in all cell outputs.
+
+        Iterates over every code cell in an nbformat notebook and replaces
+        `./@file/...` references found in `text/html` output data with
+        inline base64 data URIs. This is necessary before passing the notebook
+        to nbconvert exporters that produce standalone HTML (e.g. `SlidesExporter`),
+        because the generated HTML is served from a temporary directory or file://
+        URI where virtual file paths cannot be resolved.
+
+        Operates in-place on the notebook object.
+        """
+        from marimo._convert.common.dom_traversal import (
+            replace_virtual_files_with_data_uris,
+        )
+
+        cells = notebook.get("cells", [])
+        if not isinstance(cells, list):
+            return
+
+        for cell in cells:
+            if not isinstance(cell, dict) or cell.get("cell_type") != "code":
+                continue
+            outputs = cell.get("outputs", [])
+            if not isinstance(outputs, list):
+                continue
+            for output in outputs:
+                if not isinstance(output, dict):
+                    continue
+                data = output.get("data")
+                if not isinstance(data, dict):
+                    continue
+                for mime_type, content in list(data.items()):
+                    if mime_type != "text/html" or not isinstance(
+                        content, str
+                    ):
+                        continue
+                    if "./@file/" not in content:
+                        continue
+                    processed, _ = replace_virtual_files_with_data_uris(
+                        content,
+                        allowed_tags=VIRTUAL_FILE_ALLOWED_TAGS,
+                        allowed_attributes=VIRTUAL_FILE_ALLOWED_ATTRIBUTES,
+                        max_inline_bytes=MAX_VIRTUAL_FILE_INLINE_BYTES,
+                    )
+                    data[mime_type] = processed
+
     @staticmethod
     def _to_file_uri(path: str) -> str:
         import os
@@ -734,6 +790,14 @@ async def _export_slides_as_pdf(
 
         from nbconvert import SlidesExporter
 
+        # Explicitly check for Playwright up-front so users get a clear message
+        # instead of a bare ModuleNotFoundError from the lazy import below.
+        from marimo._dependencies.dependencies import DependencyManager
+
+        DependencyManager.playwright.require(
+            "for slides PDF export (Playwright renders the reveal.js HTML to PDF)"
+        )
+
         # Add slideshow metadata so each cell becomes a slide.
         for cell in notebook.cells:
             if "slideshow" not in cell.metadata:

marimo/_server/api/endpoints/export.py

@@ -37,6 +37,7 @@
     IPYNBExportRequest,
     MarkdownExportRequest,
     PDFExportRequest,
+    PDFRasterizationRequest,
     ScriptExportRequest,
 )
 from marimo._export.serialization import serialize_notebook_snapshot
@@ -59,6 +60,7 @@
     SERVER_EXPORT_FORMATS,
     IPYNBExportOptions,
     MarkdownExportOptions,
+    PDFRasterizationOptions,
 )
 from marimo._server.api.deps import AppState
 from marimo._server.api.utils import (
@@ -637,10 +639,45 @@ async def export_as_pdf(*, request: Request) -> Response:
             detail="File must have a name before exporting",
         )
 
+    # Collect PNG fallbacks for interactive/plot outputs when Playwright
+    # is available, so that marimo components and Vega specs that cannot
+    # render in nbconvert are replaced with captured screenshots.
+    png_fallbacks = None
+    if body.include_outputs and session.session_view is not None:
+        try:
+            from marimo._export._pdf_raster import (
+                collect_pdf_png_fallbacks,
+            )
+
+            png_fallbacks = await collect_pdf_png_fallbacks(
+                PDFRasterizationRequest(
+                    app=session.app_file_manager.app,
+                    session_view=session.session_view,
+                    filename=session.app_file_manager.filename,
+                    filepath=session.app_file_manager.filename,
+                    options=PDFRasterizationOptions(
+                        enabled=True,
+                        scale=4.0,
+                        server_mode="static",
+                    ),
+                )
+            )
+        except Exception:
+            # If Playwright / Chromium is not installed or rasterization
+            # fails for any other reason, proceed without fallbacks.
+            # nbconvert will still render whatever it can (e.g. raw
+            # image/png outputs).
+            LOGGER.info(
+                "Rasterization unavailable for PDF export; "
+                "proceeding without PNG fallbacks.",
+                exc_info=True,
+            )
+
     export_request = PDFExportRequest(
         app=session.app_file_manager.app,
         session_view=session.session_view if body.include_outputs else None,
         options=to_pdf_export_options(body),
+        png_fallbacks=png_fallbacks,
     )
     pdf_data = await render_pdf(export_request)
     if pdf_data is None:

tests/_export/test_exporter.py

@@ -2664,6 +2664,181 @@ def slide_2():
                 sys.modules.pop("playwright.async_api", None)
 
 
+@pytest.mark.skipif(
+    not DependencyManager.nbformat.has(),
+    reason="nbformat not installed",
+)
+async def test_export_as_slides_pdf_with_png_fallbacks(
+    session_view: SessionView,
+) -> None:
+    """Test slides PDF injection of PNG fallbacks alongside virtual file inlining."""
+    app = App()
+
+    @app.cell()
+    def slide_1():
+        return "slide 1"
+
+    file_manager = AppFileManager.from_app(InternalApp(app))
+    exporter = Exporter()
+
+    mock_slides_exporter_instance = MagicMock()
+    mock_slides_exporter_instance.from_notebook_node.return_value = (
+        "<html>mock slides html</html>",
+        {},
+    )
+    mock_slides_exporter_cls = MagicMock(
+        return_value=mock_slides_exporter_instance
+    )
+
+    mock_page = AsyncMock()
+    mock_page.pdf.return_value = b"mock_slides_pdf_data"
+    mock_browser = AsyncMock()
+    mock_browser.new_page.return_value = mock_page
+    mock_playwright_instance = AsyncMock()
+    mock_playwright_instance.chromium.launch.return_value = mock_browser
+    mock_playwright_cm = AsyncMock()
+    mock_playwright_cm.__aenter__.return_value = mock_playwright_instance
+    mock_playwright_cm.__aexit__.return_value = False
+    mock_async_playwright = MagicMock(return_value=mock_playwright_cm)
+
+    mock_nbconvert = MagicMock()
+    mock_nbconvert.SlidesExporter = mock_slides_exporter_cls
+    mock_playwright_async = MagicMock()
+    mock_playwright_async.async_playwright = mock_async_playwright
+
+    orig_nbconvert = sys.modules.get("nbconvert")
+    orig_playwright = sys.modules.get("playwright.async_api")
+
+    try:
+        sys.modules["nbconvert"] = mock_nbconvert
+        sys.modules["playwright.async_api"] = mock_playwright_async
+
+        png_fallbacks = {
+            "HbolJK": "data:image/png;base64,iVBORw0KGgo=",
+        }
+
+        with (
+            patch.object(
+                DependencyManager.nbconvert, "has", return_value=True
+            ),
+            patch.object(
+                DependencyManager.playwright, "has", return_value=True
+            ),
+        ):
+            events: list[PDFExportStatusEvent] = []
+            result = await exporter.export_as_slides_pdf(
+                _pdf_export_request(
+                    app=file_manager.app,
+                    session_view=session_view,
+                    png_fallbacks=png_fallbacks,
+                    status_callback=events.append,
+                    preset="slides",
+                )
+            )
+
+        assert result == b"mock_slides_pdf_data"
+        assert [(event.phase, event.message) for event in events] == [
+            ("render", "rendering slides PDF..."),
+        ]
+
+        # Verify the notebook passed to SlidesExporter has the injected
+        # PNG fallback in its cell outputs.
+        notebook = (
+            mock_slides_exporter_instance.from_notebook_node.call_args[0][
+                0
+            ]
+        )
+        found_png = False
+        for cell in notebook.cells:
+            for output in cell.get("outputs", []):
+                data = output.get("data", {})
+                if "image/png" in data:
+                    found_png = True
+                    break
+        assert found_png, (
+            "Expected PNG fallback data in notebook cell outputs"
+        )
+
+    finally:
+        if orig_nbconvert is not None:
+            sys.modules["nbconvert"] = orig_nbconvert
+        else:
+            sys.modules.pop("nbconvert", None)
+        if orig_playwright is not None:
+            sys.modules["playwright.async_api"] = orig_playwright
+        else:
+            sys.modules.pop("playwright.async_api", None)
+
+@pytest.mark.skipif(
+    not DependencyManager.nbformat.has(),
+    reason="nbformat not installed",
+)
+def test_inline_virtual_files_in_notebook() -> None:
+    """Test that _inline_virtual_files_in_notebook resolves virtual file
+    references in cell output HTML to data URIs."""
+    import nbformat
+
+    notebook = nbformat.v4.new_notebook()
+    cell = nbformat.v4.new_code_cell(
+        "print('hi')",
+        id="cell-1",
+    )
+    cell.outputs = [
+        nbformat.v4.new_output(
+            "display_data",
+            data={
+                "text/html": '<img src="./@file/12345-test.png" alt="plot" />',
+                "text/plain": "test",
+            },
+        ),
+    ]
+    notebook.cells = [cell]
+
+    # The virtual file doesn't exist on disk, so the replacement will
+    # log a warning and leave the original value. We verify no crash.
+    Exporter._inline_virtual_files_in_notebook(notebook)
+
+    output_data = notebook.cells[0].outputs[0]["data"]
+    assert "text/html" in output_data
+    assert "text/plain" in output_data
+
+
+@pytest.mark.skipif(
+    not DependencyManager.nbformat.has(),
+    reason="nbformat not installed",
+)
+def test_inline_virtual_files_in_notebook_skips_non_html() -> None:
+    """Test that non-HTML outputs (image/png, text/plain) are never
+    sent through the HTML parser, preserving their raw content."""
+    import nbformat
+
+    notebook = nbformat.v4.new_notebook()
+    cell = nbformat.v4.new_code_cell(
+        "print('hi')",
+        id="cell-1",
+    )
+    cell.outputs = [
+        nbformat.v4.new_output(
+            "display_data",
+            data={
+                "image/png": "iVBORw0KGgo=",
+                "text/plain": "plain text with ./@file/ in content",
+            },
+        ),
+    ]
+    notebook.cells = [cell]
+    original_png = cell.outputs[0]["data"]["image/png"]
+    original_text = cell.outputs[0]["data"]["text/plain"]
+
+    Exporter._inline_virtual_files_in_notebook(notebook)
+
+    output_data = notebook.cells[0].outputs[0]["data"]
+    # image/png must remain untouched
+    assert output_data["image/png"] == original_png
+    # text/plain with "./@file/" must remain untouched (not text/html)
+    assert output_data["text/plain"] == original_text
+
+
 @pytest.mark.skipif(
     sys.platform == "win32",
     reason="Unix permission bits not supported on Windows",