docs(widgets): survive non-HTML Sphinx builders in the highlight filter

``make_highlight_filter`` dereferenced ``env.app.builder.highlighter``
at filter-registration time, but that attribute only exists on
``StandaloneHTMLBuilder`` and its subclasses. Running
``sphinx-build -b text|linkcheck|gettext|man`` on a page that uses the
``{mcp-install}`` directive crashed with ``AttributeError: 'TextBuilder'
object has no attribute 'highlighter'`` because ``SphinxDirective.run()``
executes during doctree construction for every builder.

The prior comment ("Callers are guaranteed an HTML builder by the
``builder.format == 'html'`` guard in ``install_widget_assets``") was
wrong -- that guard protects only the asset-copy hook, not the render
path.

Fix: narrow via ``isinstance(builder, StandaloneHTMLBuilder)`` (which
also covers DirectoryHTMLBuilder + SingleFileHTMLBuilder). For non-HTML
builders, fall back to an HTML-escaped ``<pre>`` block. The isinstance
narrow eliminates the ``# type: ignore[attr-defined]`` that previously
covered the bare attribute access.

Adds ``test_widget_renders_with_text_builder`` which drives the text
builder end-to-end and would AttributeError before this fix.

Author: tony

docs/_ext/widgets/_base.py

@@ -10,6 +10,7 @@
 import jinja2
 import markupsafe
 from docutils import nodes
+from sphinx.builders.html import StandaloneHTMLBuilder
 
 if t.TYPE_CHECKING:
     from sphinx.environment import BuildEnvironment
@@ -112,24 +113,33 @@ def make_highlight_filter(env: BuildEnvironment) -> HighlightFilter:
     r"""Return a Jinja filter that runs Sphinx's Pygments highlighter.
 
     Output matches ``sphinx.writers.html5.HTML5Translator.visit_literal_block``
-    byte-for-byte (sphinx/writers/html5.py:604-630): the inner ``highlight_block``
-    call already returns ``<div class="highlight"><pre>...</pre></div>\n``; we
-    wrap it with the ``<div class="highlight-{lang} notranslate">...</div>\n``
-    starttag Sphinx produces. This means sphinx-copybutton's default selector
+    byte-for-byte: the inner ``highlight_block`` call already returns
+    ``<div class="highlight"><pre>...</pre></div>\n``; we wrap it with the
+    ``<div class="highlight-{lang} notranslate">...</div>\n`` starttag Sphinx
+    produces. This means sphinx-copybutton's default selector
     (``div.highlight pre``) matches and the prompt-strip regex from gp-sphinx's
     ``DEFAULT_COPYBUTTON_PROMPT_TEXT`` works automatically.
+
+    ``highlighter`` is declared on ``StandaloneHTMLBuilder`` and its subclasses
+    (``DirectoryHTMLBuilder``, ``SingleFileHTMLBuilder``), not on the ``Builder``
+    base. For non-HTML builders (``text``, ``linkcheck``, ``gettext``, ``man``,
+    ...), fall back to an HTML-escaped ``<pre>`` block; it still flows through
+    the ``nodes.raw("html", ...)`` output path and is harmlessly ignored by
+    non-HTML writers.
     """
-    # ``highlighter`` is declared on StandaloneHTMLBuilder
-    # (sphinx/builders/html/__init__.py:246), not on the Builder base mypy
-    # sees here -- hence the type-ignore. Callers are guaranteed an HTML
-    # builder by the ``builder.format == "html"`` guard in
-    # ``install_widget_assets``.
-    highlighter = env.app.builder.highlighter  # type: ignore[attr-defined]
-
-    def _highlight(code: str, language: str = "default") -> markupsafe.Markup:
-        inner = highlighter.highlight_block(code, language)
-        return markupsafe.Markup(
-            f'<div class="highlight-{language} notranslate">{inner}</div>\n'
-        )
+    builder = env.app.builder
+    if isinstance(builder, StandaloneHTMLBuilder):
+        highlighter = builder.highlighter
+
+        def _highlight(code: str, language: str = "default") -> markupsafe.Markup:
+            inner = highlighter.highlight_block(code, language)
+            return markupsafe.Markup(
+                f'<div class="highlight-{language} notranslate">{inner}</div>\n'
+            )
+    else:
+
+        def _highlight(code: str, language: str = "default") -> markupsafe.Markup:
+            escaped = markupsafe.escape(code)
+            return markupsafe.Markup(f"<pre>{escaped}</pre>\n")
 
     return _highlight

tests/docs/test_widgets.py

@@ -200,6 +200,21 @@ def test_widget_dependency_noted(
     assert any("mcp-install" in d and "widget.html" in d for d in dep_strs)
 
 
+def test_widget_renders_with_text_builder(
+    make_app: MakeApp,
+    real_widget_srcdir: pathlib.Path,
+) -> None:
+    """``{mcp-install}`` must not crash under non-HTML builders (text)."""
+    (real_widget_srcdir / "index.md").write_text(
+        "# Home\n\n```{mcp-install}\n```\n",
+        encoding="utf-8",
+    )
+    app = make_app("text", srcdir=real_widget_srcdir, freshenv=True)
+    app.build()  # would AttributeError before the highlight-filter isinstance fix
+    assert app.statuscode == 0
+    assert (pathlib.Path(app.outdir) / "index.txt").is_file()
+
+
 # ---------- parity: highlight filter vs. Sphinx native literal_block ------