feat(querychat): inline Altair charts in visualize_query tool results

Add VisualizeQueryResult subclass that embeds Altair charts directly in
chat tool result cards via shinywidgets register_widget/output_widget.
Includes e2e Playwright tests for inline rendering and fullscreen.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpsievert

pkg-py/examples/10-viz-app.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+from querychat import QueryChat
+from querychat.data import titanic
+
+from shiny import App, render, ui
+
+greeting = Path(__file__).parent / "greeting.md"
+
+qc = QueryChat(
+    titanic(),
+    "titanic",
+    greeting=greeting,
+    tools=("update", "query", "visualize_query"),
+)
+
+app_ui = ui.page_sidebar(
+    qc.sidebar(),
+    ui.card(
+        ui.card_header(ui.output_text("title")),
+        ui.output_data_frame("data_table"),
+        fill=True,
+    ),
+    fillable=True,
+)
+
+
+def server(input, output, session):
+    qc_vals = qc.server()
+
+    @render.data_frame
+    def data_table():
+        return qc_vals.df()
+
+    @render.text
+    def title():
+        return qc_vals.title() or "Titanic Dataset"
+
+
+app = App(app_ui, server)

pkg-py/src/querychat/tools.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Protocol, TypedDict, runtime_checkable
+from uuid import uuid4
 
 import chevron
 from chatlas import ContentToolResult, Tool
@@ -309,6 +310,42 @@ def tool_query(data_source: DataSource) -> Tool:
     )
 
 
+class VisualizeQueryResult(ContentToolResult):
+    """Tool result that embeds an Altair chart inline via shinywidgets."""
+
+    def __init__(
+        self,
+        chart: Any,
+        ggsql_str: str,
+        title: str | None,
+        row_count: int,
+        col_count: int,
+        **kwargs: Any,
+    ):
+        from shinywidgets import output_widget, register_widget
+
+        widget_id = f"querychat_viz_{uuid4().hex[:8]}"
+        register_widget(widget_id, chart)
+
+        title_display = f" - {title}" if title else ""
+        markdown = f"```sql\n{ggsql_str}\n```"
+        markdown += f"\n\nVisualization created{title_display}."
+        markdown += f"\n\nData: {row_count} rows, {col_count} columns."
+
+        extra = {
+            "display": ToolResultDisplay(
+                html=output_widget(widget_id),
+                title=title or "Query Visualization",
+                show_request=False,
+                open=True,
+                full_screen=True,
+                icon=bs_icon("graph-up"),
+            ),
+        }
+
+        super().__init__(value=markdown, extra=extra, **kwargs)
+
+
 def _visualize_query_impl(
     data_source: DataSource,
     update_fn: Callable[[VisualizeQueryData], None],
@@ -334,41 +371,31 @@ def visualize_query(
                     "Use querychat_query for queries without visualization."
                 )
 
-            # Execute the SQL and validate by rendering
+            # Execute the SQL and render the visualization
             spec = execute_ggsql(data_source, ggsql)
-            spec_to_altair(spec)
+            chart = spec_to_altair(spec)
 
-            # Extract title from spec if not provided
             if title is None:
                 title = extract_title(spec)
             metadata = spec.metadata()
             row_count = metadata["rows"]
             col_count = len(metadata["columns"])
 
-            # Store just the ggsql - rendering happens on display
             update_fn(
                 {
                     "ggsql": ggsql,
                     "title": title,
                 }
             )
 
-            # Format success message with data summary
-            title_display = f" - {title}" if title else ""
-            markdown += f"\n\nVisualization created{title_display}."
-            markdown += f"\n\nData: {row_count} rows, {col_count} columns."
-
-            return ContentToolResult(
-                value=markdown,
-                extra={
-                    "display": ToolResultDisplay(
-                        markdown=markdown,
-                        title=title or "Query Visualization",
-                        show_request=False,
-                        open=querychat_tool_starts_open("visualize_query"),
-                        icon=bs_icon("graph-up"),
-                    ),
-                },
+            chart = chart.properties(height=300, width="container")
+
+            return VisualizeQueryResult(
+                chart=chart,
+                ggsql_str=ggsql,
+                title=title,
+                row_count=row_count,
+                col_count=col_count,
             )
 
         except Exception as e:

pkg-py/tests/playwright/conftest.py

@@ -592,3 +592,31 @@ def dash_cleanup(_thread, server):
         yield url
     finally:
         _stop_dash_server(server)
+
+
+@pytest.fixture(scope="module")
+def app_10_viz() -> Generator[str, None, None]:
+    """Start the 10-viz-app.py Shiny server for testing."""
+    app_path = str(EXAMPLES_DIR / "10-viz-app.py")
+
+    def start_factory():
+        port = _find_free_port()
+        url = f"http://localhost:{port}"
+        return url, lambda: _start_shiny_app_threaded(app_path, port)
+
+    def shiny_cleanup(_thread, server):
+        _stop_shiny_server(server)
+
+    url, _thread, server = _start_server_with_retry(
+        start_factory, shiny_cleanup, timeout=30.0
+    )
+    try:
+        yield url
+    finally:
+        _stop_shiny_server(server)
+
+
+@pytest.fixture
+def chat_10_viz(page: Page) -> ChatControllerType:
+    """Create a ChatController for the 10-viz-app chat component."""
+    return _create_chat_controller(page, "titanic")

pkg-py/tests/playwright/test_10_viz_inline.py

@@ -0,0 +1,123 @@
+"""
+Playwright tests for inline visualization and fullscreen behavior.
+
+These tests verify that:
+1. The visualize_query tool renders Altair charts inline in tool result cards
+2. The fullscreen toggle button appears on visualization tool results
+3. Fullscreen mode works (expand and collapse via button and Escape key)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from playwright.sync_api import expect
+
+if TYPE_CHECKING:
+    from playwright.sync_api import Page
+    from shinychat.playwright import ChatController
+
+
+class TestInlineVisualization:
+    """Tests for inline chart rendering in tool result cards."""
+
+    @pytest.fixture(autouse=True)
+    def setup(
+        self, page: Page, app_10_viz: str, chat_10_viz: ChatController
+    ) -> None:
+        """Navigate to the viz app before each test."""
+        page.goto(app_10_viz)
+        page.wait_for_selector("table", timeout=30000)
+        self.page = page
+        self.chat = chat_10_viz
+
+    def test_app_loads_with_query_plot_tab(self) -> None:
+        """VIZ-INIT: App with visualize_query has a Query Plot tab."""
+        expect(self.page.get_by_role("tab", name="Query Plot")).to_be_visible()
+
+    def test_viz_tool_renders_inline_chart(self) -> None:
+        """VIZ-INLINE: Visualization tool result contains an inline chart widget."""
+        self.chat.set_user_input(
+            "Create a scatter plot of age vs fare for the titanic passengers"
+        )
+        self.chat.send_user_input(method="click")
+
+        # Wait for a tool result card with full-screen attribute (viz results have it)
+        tool_card = self.page.locator("shiny-tool-result[full-screen]")
+        expect(tool_card).to_be_visible(timeout=90000)
+
+        # The card should contain a widget output (Altair chart)
+        widget_output = tool_card.locator(".jupyter-widgets")
+        expect(widget_output).to_be_visible(timeout=10000)
+
+    def test_fullscreen_button_visible_on_viz_card(self) -> None:
+        """VIZ-FS-BTN: Fullscreen toggle button appears on visualization cards."""
+        self.chat.set_user_input(
+            "Make a bar chart showing count of passengers by class"
+        )
+        self.chat.send_user_input(method="click")
+
+        # Wait for viz tool result
+        tool_card = self.page.locator("shiny-tool-result[full-screen]")
+        expect(tool_card).to_be_visible(timeout=90000)
+
+        # Fullscreen toggle should be visible
+        fs_button = tool_card.locator(".tool-fullscreen-toggle")
+        expect(fs_button).to_be_visible()
+
+    def test_fullscreen_toggle_expands_card(self) -> None:
+        """VIZ-FS-EXPAND: Clicking fullscreen button expands the card."""
+        self.chat.set_user_input(
+            "Plot a histogram of passenger ages from the titanic data"
+        )
+        self.chat.send_user_input(method="click")
+
+        # Wait for viz tool result
+        tool_result = self.page.locator("shiny-tool-result[full-screen]")
+        expect(tool_result).to_be_visible(timeout=90000)
+
+        # Click fullscreen toggle
+        fs_button = tool_result.locator(".tool-fullscreen-toggle")
+        fs_button.click()
+
+        # The .shiny-tool-card inside should now have fullscreen attribute
+        card = tool_result.locator(".shiny-tool-card[fullscreen]")
+        expect(card).to_be_visible()
+
+    def test_escape_closes_fullscreen(self) -> None:
+        """VIZ-FS-ESC: Pressing Escape closes fullscreen mode."""
+        self.chat.set_user_input(
+            "Create a visualization of survival rate by passenger class"
+        )
+        self.chat.send_user_input(method="click")
+
+        # Wait for viz tool result
+        tool_result = self.page.locator("shiny-tool-result[full-screen]")
+        expect(tool_result).to_be_visible(timeout=90000)
+
+        # Enter fullscreen
+        fs_button = tool_result.locator(".tool-fullscreen-toggle")
+        fs_button.click()
+
+        card = tool_result.locator(".shiny-tool-card[fullscreen]")
+        expect(card).to_be_visible()
+
+        # Press Escape
+        self.page.keyboard.press("Escape")
+
+        # Fullscreen should be removed
+        expect(card).not_to_be_visible()
+
+    def test_non_viz_tool_results_have_no_fullscreen(self) -> None:
+        """VIZ-NO-FS: Non-visualization tool results don't have fullscreen."""
+        self.chat.set_user_input("Show me passengers who survived")
+        self.chat.send_user_input(method="click")
+
+        # Wait for a tool result (any)
+        tool_result = self.page.locator("shiny-tool-result").first
+        expect(tool_result).to_be_visible(timeout=90000)
+
+        # Non-viz tool results should NOT have full-screen attribute
+        fs_results = self.page.locator("shiny-tool-result[full-screen]")
+        expect(fs_results).to_have_count(0)

pkg-py/tests/test_viz_tools.py

@@ -9,6 +9,7 @@
 from querychat._datasource import DataFrameSource
 from querychat.tools import (
     VisualizeQueryData,
+    VisualizeQueryResult,
     tool_visualize_query,
 )
 
@@ -67,16 +68,19 @@ def update_fn(data: VisualizeQueryData):
         assert tool.name == "querychat_visualize_query"
 
     @ggsql_render_works
-    def test_tool_executes_sql_and_renders(self, data_source):
+    def test_tool_executes_sql_and_renders(self, data_source, monkeypatch):
         callback_data = {}
 
         def update_fn(data: VisualizeQueryData):
             callback_data.update(data)
 
+        monkeypatch.setattr("shinywidgets.register_widget", lambda _widget_id, _chart: None)
+        monkeypatch.setattr("shinywidgets.output_widget", lambda widget_id: widget_id)
+
         tool = tool_visualize_query(data_source, update_fn)
         impl = tool.func
 
-        impl(
+        result = impl(
             ggsql="SELECT x, y FROM test_data WHERE x > 2 VISUALISE x, y DRAW point",
             title="Filtered Scatter",
         )
@@ -85,6 +89,11 @@ def update_fn(data: VisualizeQueryData):
         assert "title" in callback_data
         assert callback_data["title"] == "Filtered Scatter"
 
+        assert isinstance(result, VisualizeQueryResult)
+        display = result.extra["display"]
+        assert display.full_screen is True
+        assert display.open is True
+
     @ggsql_render_works
     def test_tool_handles_query_without_visualise(self, data_source):
         callback_data = {}