From 85ccde8fe216f507a96418a0041f2e2b3f2ed9b5 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 09:45:02 -0500
Subject: [PATCH 1/9] mermaid(feat[responsive]): Add diagram policy

why: Responsive diagram behavior needs an author-facing contract so
Sphinx pages can choose between scaled diagrams and intrinsic-width
scrolling without adding client-side Mermaid runtime behavior.

what:
- Add fit and preserve responsive policies to the mermaid directive
- Emit responsive classes and data attributes on rendered figures
- Split CSS behavior for scaled and preserved SVG diagrams
- Document responsive authoring guidance and cover the markup in tests
---
 docs/_ext/mermaid_examples.py                 |  9 +-
 docs/packages/sphinx-gp-mermaid/how-to.md     | 32 ++++++-
 packages/sphinx-gp-mermaid/README.md          |  7 ++
 .../src/sphinx_gp_mermaid/__init__.py         | 88 +++++++++++++++++--
 .../_static/css/sphinx_gp_mermaid.css         | 19 ++--
 .../__snapshots__/test_integration.ambr       |  2 +-
 tests/ext/mermaid/test_css.py                 | 32 +++++++
 tests/ext/mermaid/test_examples_page.py       |  2 +-
 tests/ext/mermaid/test_integration.py         | 21 ++++-
 tests/ext/mermaid/test_mermaid.py             | 72 ++++++++++++++-
 10 files changed, 262 insertions(+), 22 deletions(-)
 create mode 100644 tests/ext/mermaid/test_css.py

diff --git a/docs/_ext/mermaid_examples.py b/docs/_ext/mermaid_examples.py
index 23bcbe06..255f64c9 100644
--- a/docs/_ext/mermaid_examples.py
+++ b/docs/_ext/mermaid_examples.py
@@ -56,7 +56,9 @@ def _figure_markup(light: str, dark: str, *, alt: str) -> str:
     ``body[data-theme]`` rules toggle the committed variants with no script.
 
     >>> markup = _figure_markup("<svg/>", "<svg/>", alt="A flow")
-    >>> 'class="gp-sphinx-mermaid"' in markup
+    >>> 'class="gp-sphinx-mermaid gp-sphinx-mermaid--fit"' in markup
+    True
+    >>> 'data-mermaid-responsive="fit"' in markup
     True
     >>> markup.count("gp-sphinx-mermaid__variant--theme-")
     2
@@ -68,7 +70,10 @@ def _figure_markup(light: str, dark: str, *, alt: str) -> str:
     aria = f' aria-label="{html.escape(alt, quote=True)}"'
     return "".join(
         [
-            '<figure class="gp-sphinx-mermaid">',
+            (
+                '<figure class="gp-sphinx-mermaid gp-sphinx-mermaid--fit" '
+                'data-mermaid-responsive="fit">'
+            ),
             (
                 '<div class="gp-sphinx-mermaid__variant '
                 f'gp-sphinx-mermaid__variant--theme-light" role="img"{aria}>'
diff --git a/docs/packages/sphinx-gp-mermaid/how-to.md b/docs/packages/sphinx-gp-mermaid/how-to.md
index b6067498..e10f09b6 100644
--- a/docs/packages/sphinx-gp-mermaid/how-to.md
+++ b/docs/packages/sphinx-gp-mermaid/how-to.md
@@ -9,16 +9,44 @@ Write a diagram in a MyST fence — it renders to inline SVG at build time, so i
 ```markdown
 :::{mermaid}
 :caption: How a request flows.
+:alt: browser request through the CDN to the origin
+:name: request-flow
+:responsive: fit
 
 flowchart LR
     browser --> cdn --> origin
 :::
 ```
 
-`:caption:`, `:alt:`, and `:name:` are the directive's options; `:name:` gives the figure a cross-reference target. When you build through {py:func}`~gp_sphinx.config.merge_sphinx_config` with the extension in `extra_extensions`, plain {rst:dir}`mermaid` fences route to the same directive automatically (it sets `myst_fence_as_directive = ["mermaid"]`).
+`:caption:`, `:alt:`, `:name:`, `:class:`, and `:responsive:` are the directive's options; `:name:` gives the figure a cross-reference target. When you build through {py:func}`~gp_sphinx.config.merge_sphinx_config` with the extension in `extra_extensions`, plain {rst:dir}`mermaid` fences route to the same directive automatically (it sets `myst_fence_as_directive = ["mermaid"]`).
 
 See {ref}`sphinx-gp-mermaid-reference` for the full option and config list.
 
+## Choose the responsive policy
+
+Every rendered diagram sits in a scrollable figure. The `:responsive:` option decides what the SVG itself does inside that figure:
+
+- `fit` is the default. It keeps the SVG's build-time aspect ratio but lets the browser scale the diagram down to the content column.
+- `preserve` keeps the SVG at its intrinsic Mermaid-rendered width. If the diagram is wider than the column, the figure scrolls horizontally.
+
+Use `fit` for diagrams that remain readable when scaled: small flows, state diagrams, and short sequence diagrams. Use `preserve` for diagrams where scale-down would make labels unreadable, such as dense architecture maps or compatibility matrices.
+
+```markdown
+:::{mermaid}
+:caption: Dense architecture map.
+:alt: subsystem ownership and data flow
+:name: architecture-map
+:responsive: preserve
+
+flowchart LR
+    api --> planner --> executor --> sinks
+    planner --> cache
+    executor --> audit
+:::
+```
+
+`fit` and `preserve` do not rewrite the Mermaid graph. If a wide `flowchart LR` turns into a hard-to-read strip on phones, split it into smaller diagrams or use a top-to-bottom layout. Reach for `preserve` when the wide view is the useful artifact.
+
 ## Install the renderer
 
 Rendering shells out to [`mmdc`](https://github.com/mermaid-js/mermaid-cli), so the docs toolchain needs Node. Install it as a dev dependency:
@@ -33,6 +61,6 @@ In a container, set `PUPPETEER_EXECUTABLE_PATH` to your Chrome (the generated pu
 
 ## How rendering behaves
 
-Each diagram renders twice — a light and a dark SVG — and CSS on `body[data-theme]` shows the matching one, so the theme toggle works with no JavaScript and no layout shift. Rendered SVGs are cached by content hash under `<confdir>/_mermaid_cache`, which lives outside `_build` and survives `rm -rf docs/_build`, so a clean rebuild re-renders nothing unchanged.
+Each diagram renders twice — a light and a dark SVG — and CSS on `body[data-theme]` shows the matching one, so the theme toggle works with no JavaScript and no layout shift. The HTML figure carries `gp-sphinx-mermaid--fit` or `gp-sphinx-mermaid--preserve`, plus `data-mermaid-responsive`, `data-mermaid-width`, and `data-mermaid-height` attributes for downstream styling or audits. Rendered SVGs are cached by content hash under `<confdir>/_mermaid_cache`, which lives outside `_build` and survives `rm -rf docs/_build`, so a clean rebuild re-renders nothing unchanged.
 
 If `mmdc` is missing or fails, the build still succeeds: the diagram degrades to its escaped source text with a single warning, and non-HTML builders emit a `[diagram: <alt>]` stand-in.
diff --git a/packages/sphinx-gp-mermaid/README.md b/packages/sphinx-gp-mermaid/README.md
index d33eb09f..0cba7b15 100644
--- a/packages/sphinx-gp-mermaid/README.md
+++ b/packages/sphinx-gp-mermaid/README.md
@@ -37,12 +37,19 @@ Author diagrams as MyST fences:
 ````markdown
 :::{mermaid}
 :caption: How it flows.
+:alt: a request flowing through two steps
+:name: request-flow
+:responsive: fit
 
 flowchart LR
     a --> b
 :::
 ````
 
+`fit` is the default responsive policy: the rendered SVG scales down to the
+content column. Use `:responsive: preserve` when a dense diagram should keep
+its intrinsic width and scroll horizontally instead of shrinking labels.
+
 ## Renderer toolchain
 
 Rendering shells out to `mmdc`, resolved from the `mermaid_cmd` config value,
diff --git a/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/__init__.py b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/__init__.py
index 9576cb48..c0520db3 100644
--- a/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/__init__.py
+++ b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/__init__.py
@@ -19,6 +19,7 @@
 
     :::{mermaid}
     :caption: How it flows.
+    :responsive: fit
 
     flowchart LR
         a --> b
@@ -85,6 +86,13 @@
 _THEME_LIGHT = "light"
 _THEME_DARK = "dark"
 
+#: Author-facing responsive policies. ``fit`` scales the SVG down to the
+#: available column; ``preserve`` keeps its intrinsic width and lets the figure
+#: scroll horizontally.
+_RESPONSIVE_FIT = "fit"
+_RESPONSIVE_PRESERVE = "preserve"
+_RESPONSIVE_POLICIES = (_RESPONSIVE_FIT, _RESPONSIVE_PRESERVE)
+
 #: System font stack matching gp-furo's body font (gp-furo-tokens --font-stack).
 _FONT_STACK = (
     "-apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif"
@@ -254,6 +262,22 @@ def _svg_element_id(digest: str, theme: str, *, occurrence: int = 0) -> str:
     return f"mermaid-{digest[:12]}{suffix}-{theme}"
 
 
+def _svg_dimensions(svg: str) -> tuple[str, str] | None:
+    """Return root SVG ``viewBox`` width and height, if available.
+
+    >>> _svg_dimensions('<svg viewBox="0 0 120 40"></svg>')
+    ('120', '40')
+    >>> _svg_dimensions('<svg viewBox="-5 -97 148 194"></svg>')
+    ('148', '194')
+    >>> _svg_dimensions("<svg></svg>") is None
+    True
+    """
+    match = _VIEWBOX_RE.search(svg)
+    if match is None:
+        return None
+    return match.group(1), match.group(2)
+
+
 def _normalize_svg(svg: str, *, svg_id: str) -> str:
     """Make an ``mmdc`` SVG safe to inline: unique id, explicit size, no max-width.
 
@@ -267,8 +291,8 @@ def _normalize_svg(svg: str, *, svg_id: str) -> str:
     2. The root ``width="100%"`` (mermaid emits no ``height``) is replaced with
        explicit ``width``/``height`` taken from the ``viewBox``, so the browser
        reserves the diagram's box in the first layout pass — before any script.
-    3. The inline ``max-width: NNpx`` is stripped; paired with the stylesheet's
-       ``max-width: 100%; height: auto`` the diagram scales without reflow.
+    3. The inline ``max-width: NNpx`` is stripped so the stylesheet, not
+       mermaid's inline style, controls the figure's responsive policy.
 
     >>> svg = (
     ...     '<svg id="my-svg" width="100%" '
@@ -308,16 +332,46 @@ def _normalize_svg(svg: str, *, svg_id: str) -> str:
     True
     """
     svg = _MERMAID_ID_TOKEN_RE.sub(rf"\g<1>{svg_id}", svg)
-    match = _VIEWBOX_RE.search(svg)
-    if match is not None:
-        width, height = match.group(1), match.group(2)
+    dimensions = _svg_dimensions(svg)
+    if dimensions is not None:
+        width, height = dimensions
         svg = re.sub(r'(<svg\b[^>]*?)\s+width="[^"]*"', r"\1", svg, count=1)
         svg = re.sub(r"<svg\b", f'<svg width="{width}" height="{height}"', svg, count=1)
     return re.sub(r"\s*max-width:\s*[\d.]+px;?", "", svg, count=1)
 
 
+def _responsive_policy(argument: str) -> str:
+    """Validate a Mermaid diagram responsive policy.
+
+    >>> _responsive_policy("fit")
+    'fit'
+    >>> _responsive_policy("PRESERVE")
+    'preserve'
+    >>> _responsive_policy("auto")
+    Traceback (most recent call last):
+    ...
+    ValueError: "auto" unknown; choose from "fit", or "preserve"
+    """
+    return directives.choice(argument, _RESPONSIVE_POLICIES)
+
+
 class MermaidDirective(SphinxDirective):
-    """Stash a mermaid fence's source on a node for the write phase to render."""
+    """Stash a mermaid fence's source on a node for the write phase to render.
+
+    Options
+    -------
+    caption : str
+        Optional figure caption.
+    alt : str
+        Accessible label for the rendered figure. Falls back to ``caption``.
+    name : str
+        Cross-reference target for the figure.
+    class : str
+        Extra CSS class or classes on the outer ``<figure>``.
+    responsive : {"fit", "preserve"}
+        ``fit`` scales the SVG down to the column; ``preserve`` keeps the
+        intrinsic SVG width and scrolls horizontally when needed.
+    """
 
     has_content = True
     required_arguments = 0
@@ -326,6 +380,8 @@ class MermaidDirective(SphinxDirective):
         "caption": directives.unchanged,
         "alt": directives.unchanged,
         "name": directives.unchanged,
+        "class": directives.class_option,
+        "responsive": _responsive_policy,
     }
 
     def run(self) -> list[nodes.Node]:
@@ -340,6 +396,8 @@ def run(self) -> list[nodes.Node]:
         node["mermaid_source"] = "\n".join(self.content)
         node["caption"] = self.options.get("caption", "")
         node["alt"] = self.options.get("alt", "")
+        node["responsive"] = self.options.get("responsive", _RESPONSIVE_FIT)
+        node["classes"].extend(self.options.get("class", []))
         self.add_name(node)
         self.set_source_info(node)
         return [node]
@@ -559,9 +617,25 @@ def html_visit_mermaid_inline(self: HTML5Translator, node: mermaid_inline) -> No
     caption: str = node.get("caption", "")
     alt = node.get("alt", "") or caption
     aria = f' aria-label="{html.escape(alt, quote=True)}"' if alt else ""
+    responsive: str = node.get("responsive", _RESPONSIVE_FIT)
+    attrs = {
+        "data-mermaid-responsive": responsive,
+    }
+    dimensions = _svg_dimensions(light)
+    if dimensions is not None:
+        width, height = dimensions
+        attrs["data-mermaid-width"] = width
+        attrs["data-mermaid-height"] = height
+    starttag = t.cast("t.Any", self.starttag)
 
     parts = [
-        f'<figure class="gp-sphinx-mermaid"{fig_id}>',
+        starttag(
+            node,
+            "figure",
+            "",
+            CLASS=f"gp-sphinx-mermaid gp-sphinx-mermaid--{responsive}",
+            **attrs,
+        ),
         (
             '<div class="gp-sphinx-mermaid__variant '
             f'gp-sphinx-mermaid__variant--theme-light" role="img"{aria}>{light}</div>'
diff --git a/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css
index dffc7e22..698dc1d4 100644
--- a/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css
+++ b/packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css
@@ -9,20 +9,27 @@
 
 .gp-sphinx-mermaid {
   margin: 1.5rem 0;
-  /* Wide diagrams scroll within the column instead of overflowing it. */
+  /* Preserve-mode diagrams scroll within the column instead of overflowing it. */
   overflow-x: auto;
 }
 
 .gp-sphinx-mermaid__variant svg {
-  /* Intrinsic width/height/viewBox are set at build time; these let the
-     diagram scale down on narrow columns while keeping its aspect ratio,
-     so there is no layout shift. */
-  max-width: 100%;
-  height: auto;
+  /* Intrinsic width/height/viewBox are set at build time so the browser can
+     reserve geometry before paint. Responsive policy rules below decide
+     whether the SVG scales to the column or keeps that intrinsic width. */
   display: block;
   margin: 0 auto;
 }
 
+.gp-sphinx-mermaid--fit .gp-sphinx-mermaid__variant svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.gp-sphinx-mermaid--preserve .gp-sphinx-mermaid__variant svg {
+  max-width: none;
+}
+
 .gp-sphinx-mermaid > figcaption {
   text-align: center;
   font-size: 0.9em;
diff --git a/tests/ext/mermaid/__snapshots__/test_integration.ambr b/tests/ext/mermaid/__snapshots__/test_integration.ambr
index 29bfdc43..a5dd86e8 100644
--- a/tests/ext/mermaid/__snapshots__/test_integration.ambr
+++ b/tests/ext/mermaid/__snapshots__/test_integration.ambr
@@ -1,4 +1,4 @@
 # serializer version: 1
 # name: test_figure_markup_snapshot
-  '<figure class="gp-sphinx-mermaid" id="flow-diagram"><div class="gp-sphinx-mermaid__variant gp-sphinx-mermaid__variant--theme-light" role="img" aria-label="a to b"><svg width="200" height="80" id="mermaid-66ed0c9ec615-light" style=" background-color: transparent;" viewBox="0 0 200 80" role="graphics-document document"><style>#mermaid-66ed0c9ec615-light{fill:#f8f9fb;}</style><g class="node">a</g><path marker-end="url(#mermaid-66ed0c9ec615-light_flowchart-pointEnd)"></path></svg></div><div class="gp-sphinx-mermaid__variant gp-sphinx-mermaid__variant--theme-dark" role="img" aria-hidden="true"><svg width="200" height="80" id="mermaid-66ed0c9ec615-dark" style=" background-color: transparent;" viewBox="0 0 200 80" role="graphics-document document"><style>#mermaid-66ed0c9ec615-dark{fill:#1a1c1e;}</style><g class="node">a</g><path marker-end="url(#mermaid-66ed0c9ec615-dark_flowchart-pointEnd)"></path></svg></div><figcaption>How it flows.</figcaption></figure>'
+  '<figure class="event-flow gp-sphinx-mermaid gp-sphinx-mermaid--preserve" data-mermaid-height="80" data-mermaid-responsive="preserve" data-mermaid-width="200" id="flow-diagram"><div class="gp-sphinx-mermaid__variant gp-sphinx-mermaid__variant--theme-light" role="img" aria-label="a to b"><svg width="200" height="80" id="mermaid-66ed0c9ec615-light" style=" background-color: transparent;" viewBox="0 0 200 80" role="graphics-document document"><style>#mermaid-66ed0c9ec615-light{fill:#f8f9fb;}</style><g class="node">a</g><path marker-end="url(#mermaid-66ed0c9ec615-light_flowchart-pointEnd)"></path></svg></div><div class="gp-sphinx-mermaid__variant gp-sphinx-mermaid__variant--theme-dark" role="img" aria-hidden="true"><svg width="200" height="80" id="mermaid-66ed0c9ec615-dark" style=" background-color: transparent;" viewBox="0 0 200 80" role="graphics-document document"><style>#mermaid-66ed0c9ec615-dark{fill:#1a1c1e;}</style><g class="node">a</g><path marker-end="url(#mermaid-66ed0c9ec615-dark_flowchart-pointEnd)"></path></svg></div><figcaption>How it flows.</figcaption></figure>'
 # ---
diff --git a/tests/ext/mermaid/test_css.py b/tests/ext/mermaid/test_css.py
new file mode 100644
index 00000000..dfbace01
--- /dev/null
+++ b/tests/ext/mermaid/test_css.py
@@ -0,0 +1,32 @@
+"""CSS regression tests for sphinx-gp-mermaid responsive policies."""
+
+from __future__ import annotations
+
+import pathlib
+
+_MERMAID_CSS = pathlib.Path(
+    "packages/sphinx-gp-mermaid/src/sphinx_gp_mermaid/_static/css/sphinx_gp_mermaid.css"
+)
+
+
+def test_fit_policy_scales_svg_to_column() -> None:
+    """The default fit policy keeps the existing scale-down behavior."""
+    css = _MERMAID_CSS.read_text(encoding="utf-8")
+
+    assert (
+        ".gp-sphinx-mermaid--fit .gp-sphinx-mermaid__variant svg {\n"
+        "  max-width: 100%;\n"
+        "  height: auto;\n"
+        "}"
+    ) in css
+
+
+def test_preserve_policy_keeps_intrinsic_svg_width() -> None:
+    """The preserve policy lets wide diagrams scroll at intrinsic width."""
+    css = _MERMAID_CSS.read_text(encoding="utf-8")
+
+    assert (
+        ".gp-sphinx-mermaid--preserve .gp-sphinx-mermaid__variant svg {\n"
+        "  max-width: none;\n"
+        "}"
+    ) in css
diff --git a/tests/ext/mermaid/test_examples_page.py b/tests/ext/mermaid/test_examples_page.py
index 9f38ae08..614fa809 100644
--- a/tests/ext/mermaid/test_examples_page.py
+++ b/tests/ext/mermaid/test_examples_page.py
@@ -84,7 +84,7 @@ def test_examples_page_embeds_every_diagram(examples_page_html: str) -> None:
     """One dual-theme figure per committed source."""
     count = len(_EXAMPLE_STEMS)
     assert count >= 10
-    assert examples_page_html.count('<figure class="gp-sphinx-mermaid"') == count
+    assert examples_page_html.count('data-mermaid-responsive="fit"') == count
     assert examples_page_html.count("gp-sphinx-mermaid__variant--theme-light") == count
     assert examples_page_html.count("gp-sphinx-mermaid__variant--theme-dark") == count
 
diff --git a/tests/ext/mermaid/test_integration.py b/tests/ext/mermaid/test_integration.py
index 8bf5f9de..0da3511f 100644
--- a/tests/ext/mermaid/test_integration.py
+++ b/tests/ext/mermaid/test_integration.py
@@ -96,6 +96,8 @@ def main() -> None:
     :caption: How it flows.
     :alt: a to b
     :name: flow-diagram
+    :class: event-flow
+    :responsive: preserve
 
     flowchart TD
         a --> b
@@ -141,7 +143,7 @@ def test_build_does_not_degrade(
 
 def test_both_fence_spellings_render_figures(mermaid_html: str) -> None:
     """The plain ```mermaid fence and :::{mermaid} both produce figures."""
-    assert mermaid_html.count('<figure class="gp-sphinx-mermaid"') == 2
+    assert mermaid_html.count("gp-sphinx-mermaid__variant--theme-light") == 2
 
 
 def test_dual_variants_carry_theme_fills(mermaid_html: str) -> None:
@@ -168,9 +170,21 @@ def test_caption_alt_and_name_flow_through(mermaid_html: str) -> None:
     assert "<figcaption>How it flows.</figcaption>" in mermaid_html
     assert 'aria-label="a to b"' in mermaid_html
     assert 'id="flow-diagram"' in mermaid_html
+    assert (
+        'class="event-flow gp-sphinx-mermaid gp-sphinx-mermaid--preserve"'
+        in mermaid_html
+    )
     assert mermaid_html.count('aria-hidden="true"') == 2
 
 
+def test_responsive_policy_markup_flows_through(mermaid_html: str) -> None:
+    """Each rendered figure carries responsive mode classes and metadata."""
+    assert mermaid_html.count('data-mermaid-responsive="fit"') == 1
+    assert mermaid_html.count('data-mermaid-responsive="preserve"') == 1
+    assert 'data-mermaid-width="200"' in mermaid_html
+    assert 'data-mermaid-height="80"' in mermaid_html
+
+
 def test_stylesheet_ships_with_the_package(
     mermaid_html_build: SharedSphinxResult,
     mermaid_html: str,
@@ -196,7 +210,10 @@ def test_figure_markup_snapshot(
 ) -> None:
     """The named figure's full markup is stable across runs."""
     match = re.search(
-        r'<figure class="gp-sphinx-mermaid" id="flow-diagram">.*?</figure>',
+        (
+            r'<figure class="event-flow gp-sphinx-mermaid '
+            r'gp-sphinx-mermaid--preserve" .*?id="flow-diagram">.*?</figure>'
+        ),
         mermaid_html,
         flags=re.DOTALL,
     )
diff --git a/tests/ext/mermaid/test_mermaid.py b/tests/ext/mermaid/test_mermaid.py
index 871a54b3..6cd7a702 100644
--- a/tests/ext/mermaid/test_mermaid.py
+++ b/tests/ext/mermaid/test_mermaid.py
@@ -235,7 +235,49 @@ def _make_translator(tmp_path: pathlib.Path) -> types.SimpleNamespace:
     )
     app = types.SimpleNamespace(confdir=str(tmp_path), config=config)
     builder = types.SimpleNamespace(app=app)
-    return types.SimpleNamespace(builder=builder, body=[])
+
+    def attval(value: str) -> str:
+        return (
+            value.replace("&", "&amp;")
+            .replace('"', "&quot;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+        )
+
+    def starttag(
+        node: nodes.Element,
+        tagname: str,
+        suffix: str = "\n",
+        empty: bool = False,
+        **attributes: object,
+    ) -> str:
+        atts = {name.lower(): value for name, value in attributes.items()}
+        node_classes = t.cast("list[str]", node.get("classes", []))
+        classes = [str(c) for c in node_classes]
+        extra_classes = t.cast("str", atts.pop("class", ""))
+        classes.extend(extra_classes.split())
+        if classes:
+            atts["class"] = " ".join(classes)
+        ids = list(t.cast("list[str]", node.get("ids", [])))
+        if ids:
+            atts["id"] = ids[0]
+        infix = " /" if empty else ""
+        rendered = "".join(
+            f' {name}="{attval(str(value))}"' for name, value in sorted(atts.items())
+        )
+        return f"<{tagname}{rendered}{infix}>{suffix}"
+
+    return types.SimpleNamespace(builder=builder, body=[], starttag=starttag)
+
+
+def test_responsive_option_accepts_fit_and_preserve() -> None:
+    """The directive exposes the two supported responsive policies."""
+    converter = sgm.MermaidDirective.option_spec["responsive"]
+
+    assert converter("fit") == "fit"
+    assert converter("preserve") == "preserve"
+    with pytest.raises(ValueError):
+        converter("auto")
 
 
 def test_visitor_emits_dual_themed_svg(
@@ -269,6 +311,34 @@ def fake_render_cached(app: object, source: str, theme: str) -> str:
     assert html.count('viewBox="0 0 200 80"') == 2
 
 
+def test_visitor_emits_responsive_policy_markup(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: pathlib.Path,
+) -> None:
+    """Responsive policy, dimensions, and author classes reach the figure."""
+    monkeypatch.setattr(
+        sgm,
+        "_render_cached",
+        lambda app, source, theme: _FAKE_MMDC_SVG,
+    )
+    translator = _make_translator(tmp_path)
+    node = sgm.mermaid_inline()
+    node["mermaid_source"] = "flowchart LR a-->b"
+    node["caption"] = ""
+    node["alt"] = ""
+    node["responsive"] = "preserve"
+    node["classes"] = ["wide-flow"]
+
+    with pytest.raises(nodes.SkipNode):
+        sgm.html_visit_mermaid_inline(t.cast("t.Any", translator), node)
+
+    html = "".join(translator.body)
+    assert 'class="wide-flow gp-sphinx-mermaid gp-sphinx-mermaid--preserve"' in html
+    assert 'data-mermaid-responsive="preserve"' in html
+    assert 'data-mermaid-width="200"' in html
+    assert 'data-mermaid-height="80"' in html
+
+
 class DuplicateDiagramCase(t.NamedTuple):
     """Sources visited on one page and the id uniqueness they must yield."""
 

From 6cc297e317406dd34d9c4b42b9dc7e530c48b528 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 11:06:03 -0500
Subject: [PATCH 2/9] highlighting(feat): Add Sphinx highlighter

why: Downstream projects need reusable highlighting for directory-tree
code blocks and inline command/path literals without copying local
Sphinx and Pygments glue into each docs tree.

what:
- Add the sphinx-gp-highlighting workspace package
- Register directory-tree lexers, inline roles, and safe literal transforms
- Wire package docs, navigation, redirects, CI smoke, and coverage tests
---
 docs/_ext/package_reference.py                |   6 +
 docs/conf.py                                  |   2 +
 docs/index.md                                 |   4 +
 docs/packages/index.md                        |   6 +
 .../packages/sphinx-gp-highlighting/how-to.md |  52 ++++
 docs/packages/sphinx-gp-highlighting/index.md |   6 +
 .../sphinx-gp-highlighting/reference.md       |  38 +++
 docs/redirects.txt                            |   1 +
 packages/sphinx-gp-highlighting/README.md     |  30 ++
 .../sphinx-gp-highlighting/pyproject.toml     |  46 +++
 .../src/sphinx_gp_highlighting/__init__.py    | 100 +++++++
 .../_static/css/sphinx_gp_highlighting.css    |  12 +
 .../src/sphinx_gp_highlighting/inline.py      | 274 ++++++++++++++++++
 .../src/sphinx_gp_highlighting/lexers.py      |  75 +++++
 pyproject.toml                                |   3 +
 scripts/ci/package_tools.py                   |  22 ++
 tests/docs/test_cluster_toctree.py            |  29 +-
 .../test_workspace_package_grid_groups.py     |   7 +-
 tests/ext/highlighting/test_inline.py         | 158 ++++++++++
 tests/ext/highlighting/test_tree_lexer.py     | 112 +++++++
 tests/test_package_reference.py               |   1 +
 uv.lock                                       |  21 ++
 22 files changed, 1000 insertions(+), 5 deletions(-)
 create mode 100644 docs/packages/sphinx-gp-highlighting/how-to.md
 create mode 100644 docs/packages/sphinx-gp-highlighting/index.md
 create mode 100644 docs/packages/sphinx-gp-highlighting/reference.md
 create mode 100644 packages/sphinx-gp-highlighting/README.md
 create mode 100644 packages/sphinx-gp-highlighting/pyproject.toml
 create mode 100644 packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/__init__.py
 create mode 100644 packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
 create mode 100644 packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
 create mode 100644 packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
 create mode 100644 tests/ext/highlighting/test_inline.py
 create mode 100644 tests/ext/highlighting/test_tree_lexer.py

diff --git a/docs/_ext/package_reference.py b/docs/_ext/package_reference.py
index 5d8b06b0..024b5988 100644
--- a/docs/_ext/package_reference.py
+++ b/docs/_ext/package_reference.py
@@ -202,6 +202,7 @@ class PackageDocsRecord:
     "sphinx-ux-badges": "ux",
     "sphinx-ux-autodoc-layout": "ux",
     "sphinx-gp-mermaid": "ux",
+    "sphinx-gp-highlighting": "highlighting",
     "sphinx-vite-builder": "build-seo",
     "sphinx-gp-opengraph": "build-seo",
     "sphinx-gp-sitemap": "build-seo",
@@ -945,6 +946,11 @@ def maturity_badge(maturity: str) -> str:
         "Badge primitives, layout presenters, and other shared "
         "rendering helpers consumed by the autodoc family.",
     ),
+    (
+        "highlighting",
+        "Highlighting",
+        "Pygments lexers and inline literal helpers for code-heavy docs.",
+    ),
     (
         "build-seo",
         "Build & SEO",
diff --git a/docs/conf.py b/docs/conf.py
index dd7e58ca..2ef0c7d8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -59,6 +59,7 @@
     str(project_root / "packages" / "sphinx-autodoc-typehints-gp" / "src"),
 )
 sys.path.insert(0, str(project_root / "packages" / "sphinx-gp-mermaid" / "src"))
+sys.path.insert(0, str(project_root / "packages" / "sphinx-gp-highlighting" / "src"))
 sys.path.insert(0, str(cwd / "_ext"))  # docs demo modules
 
 import gp_sphinx  # noqa: E402
@@ -102,6 +103,7 @@
         "sphinx_autodoc_argparse.exemplar",
         "sphinx_ux_autodoc_layout",
         "sphinx_gp_mermaid",
+        "sphinx_gp_highlighting",
         "mermaid_examples",
     ],
     fastmcp_tool_modules=["fastmcp_demo_tools"],
diff --git a/docs/index.md b/docs/index.md
index 67cbb6fd..e2601086 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -115,6 +115,10 @@ GitHub <https://github.com/git-pull/gp-sphinx>
 :caption: Theme & coordinator
 ```
 
+```{cluster-toctree} highlighting
+:caption: Highlighting
+```
+
 ```{cluster-toctree} build-seo
 :caption: Build & SEO
 ```
diff --git a/docs/packages/index.md b/docs/packages/index.md
index 09f9171f..56bdf0b3 100644
--- a/docs/packages/index.md
+++ b/docs/packages/index.md
@@ -20,6 +20,12 @@ The rendering pipeline every autodoc extension consumes, plus shared page primit
 - [`sphinx-fonts`](sphinx-fonts/index.md) — IBM Plex font preloading
 - [`sphinx-gp-mermaid`](sphinx-gp-mermaid/index.md) — build-time mermaid diagrams as dual-theme inline SVG
 
+## Code highlighting
+
+Pygments lexers and inline literal helpers for code-heavy documentation:
+
+- [`sphinx-gp-highlighting`](sphinx-gp-highlighting/index.md) — directory-tree code blocks and inline command/path highlighting
+
 ## Autodoc extensions
 
 Domain-specific [autodoc extensions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) — each adds directives that generate documentation from a particular source-construct family (Python APIs, argparse parsers, pytest fixtures, etc.):
diff --git a/docs/packages/sphinx-gp-highlighting/how-to.md b/docs/packages/sphinx-gp-highlighting/how-to.md
new file mode 100644
index 00000000..0d27bb99
--- /dev/null
+++ b/docs/packages/sphinx-gp-highlighting/how-to.md
@@ -0,0 +1,52 @@
+(sphinx-gp-highlighting-how-to)=
+
+# How to
+
+## Highlight a directory tree
+
+Use the `tree` lexer for static directory layouts. It highlights connector glyphs, directory names, filenames, and trailing comments without treating the snippet as a shell transcript:
+
+````markdown
+```tree
+python_module
+├── tmuxp_plugin_my_plugin_module
+│   ├── __init__.py
+│   └── plugin.py
+└── pyproject.toml  # Python project configuration file
+```
+````
+
+The aliases `directory-tree` and `dir-tree` are equivalent.
+
+## Mark up inline commands and paths
+
+Use explicit roles when the prose knows what the literal is:
+
+```markdown
+Run {cmd}`tmuxp freeze my-session`, then edit {path}`~/.config/tmuxp/config.yaml`.
+Store plugin modules under {dir}`./plugins/`.
+```
+
+The `{cmd}` role uses Sphinx's inline Pygments path with Bash highlighting. The `{path}` and `{dir}` roles keep ordinary inline-code styling and add package-owned classes for path-specific CSS.
+
+## Enable safe automatic inline highlighting
+
+Automatic highlighting of ordinary backtick literals is opt-in:
+
+```python
+gp_highlighting_inline_literals = "safe"
+gp_highlighting_inline_commands = ["tmuxp", "agentgrep", "unihan-etl"]
+```
+
+Safe mode only catches shell prompts, configured command names with arguments, and clear filesystem paths or directories. Literals such as `module_name` and `PackageClass` stay unchanged.
+
+## Use MyST inline language attributes
+
+MyST's `attrs_inline` extension can still request a lexer directly:
+
+```markdown
+Inline Python code `value = 1`{l=python}
+```
+
+`sphinx-gp-highlighting` leaves literals that already carry a language alone, so explicit MyST language attributes and the package's safe auto-detection can coexist.
+
diff --git a/docs/packages/sphinx-gp-highlighting/index.md b/docs/packages/sphinx-gp-highlighting/index.md
new file mode 100644
index 00000000..f3f9dd60
--- /dev/null
+++ b/docs/packages/sphinx-gp-highlighting/index.md
@@ -0,0 +1,6 @@
+(sphinx-gp-highlighting)=
+
+# sphinx-gp-highlighting
+
+```{package-landing} sphinx-gp-highlighting
+```
diff --git a/docs/packages/sphinx-gp-highlighting/reference.md b/docs/packages/sphinx-gp-highlighting/reference.md
new file mode 100644
index 00000000..74a59edc
--- /dev/null
+++ b/docs/packages/sphinx-gp-highlighting/reference.md
@@ -0,0 +1,38 @@
+(sphinx-gp-highlighting-reference)=
+
+# Reference
+
+[`sphinx_gp_highlighting/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/__init__.py).
+
+## Registered surface
+
+```{package-reference} sphinx-gp-highlighting
+```
+
+## Lexers
+
+`sphinx-gp-highlighting` registers these Pygments aliases:
+
+| Alias | Purpose |
+| --- | --- |
+| `tree` | Preferred directory-tree fence name |
+| `directory-tree` | Explicit directory-tree alias |
+| `dir-tree` | Short directory-tree alias |
+
+## Config values
+
+.. autoconfigvalues:: sphinx_gp_highlighting
+
+## Roles
+
+.. autoroles:: sphinx_gp_highlighting
+
+## API
+
+.. autofunction:: sphinx_gp_highlighting.setup
+
+.. autoclass:: sphinx_gp_highlighting.lexers.DirectoryTreeLexer
+
+.. autofunction:: sphinx_gp_highlighting.inline.classify_inline_literal
+
+.. autofunction:: sphinx_gp_highlighting.inline.build_highlighted_literal
diff --git a/docs/redirects.txt b/docs/redirects.txt
index a65d799e..f8bc1234 100644
--- a/docs/redirects.txt
+++ b/docs/redirects.txt
@@ -2,6 +2,7 @@ extensions/sphinx-gp-opengraph packages/sphinx-gp-opengraph
 extensions/sphinx-gp-sitemap packages/sphinx-gp-sitemap
 extensions/sphinx-gp-llms packages/sphinx-gp-llms
 extensions/sphinx-gp-mermaid packages/sphinx-gp-mermaid
+extensions/sphinx-gp-highlighting packages/sphinx-gp-highlighting
 extensions/gp-sphinx packages/gp-sphinx
 extensions/index packages/index
 extensions/sphinx-autodoc-argparse packages/sphinx-autodoc-argparse
diff --git a/packages/sphinx-gp-highlighting/README.md b/packages/sphinx-gp-highlighting/README.md
new file mode 100644
index 00000000..9da83ca8
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/README.md
@@ -0,0 +1,30 @@
+# sphinx-gp-highlighting
+
+Reusable Sphinx highlighting helpers for git-pull documentation. The package
+ships Pygments lexers for documentation-oriented blocks and Sphinx inline
+literal helpers for commands, paths, and directories.
+
+## Install
+
+```console
+$ pip install sphinx-gp-highlighting
+```
+
+## Usage
+
+Enable the extension in `conf.py`:
+
+```python
+extensions = ["sphinx_gp_highlighting"]
+```
+
+Use the `tree` lexer for directory layouts:
+
+````markdown
+```tree
+python_module
+├── package
+│   └── __init__.py
+└── pyproject.toml
+```
+````
diff --git a/packages/sphinx-gp-highlighting/pyproject.toml b/packages/sphinx-gp-highlighting/pyproject.toml
new file mode 100644
index 00000000..05257f91
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/pyproject.toml
@@ -0,0 +1,46 @@
+[project]
+name = "sphinx-gp-highlighting"
+version = "0.0.1a32"
+description = "Reusable Pygments lexers and inline highlighting for Sphinx"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+  "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["sphinx", "pygments", "highlighting", "documentation"]
+dependencies = [
+  "docutils",
+  "pygments",
+  "sphinx>=8.1",
+]
+
+[project.entry-points."pygments.lexers"]
+"directory-tree" = "sphinx_gp_highlighting.lexers:DirectoryTreeLexer"
+
+[project.urls]
+Repository = "https://github.com/git-pull/gp-sphinx"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_gp_highlighting"]
diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/__init__.py b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/__init__.py
new file mode 100644
index 00000000..dfc93285
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/__init__.py
@@ -0,0 +1,100 @@
+"""Reusable Sphinx highlighting helpers.
+
+Registers documentation-oriented Pygments lexers and inline literal
+helpers for Sphinx projects.
+
+Examples
+--------
+>>> from sphinx_gp_highlighting import setup
+>>> callable(setup)
+True
+"""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import typing as t
+
+from sphinx.util.logging import getLogger
+
+from sphinx_gp_highlighting.inline import (
+    HighlightingInlineTransform,
+    cmd_role,
+    dir_role,
+    path_role,
+)
+from sphinx_gp_highlighting.lexers import DirectoryTreeLexer
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+_EXTENSION_VERSION = "0.0.1a32"
+_TREE_ALIASES: tuple[str, ...] = ("tree", "directory-tree", "dir-tree")
+
+logger = getLogger(__name__)
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["DirectoryTreeLexer", "HighlightingInlineTransform", "setup"]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Register the package lexers with Sphinx.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance.
+
+    Returns
+    -------
+    ExtensionMetadata
+        Extension metadata with version and parallel-build flags.
+
+    Examples
+    --------
+    >>> from sphinx_gp_highlighting import setup
+    >>> callable(setup)
+    True
+    """
+    for alias in _TREE_ALIASES:
+        app.add_lexer(alias, DirectoryTreeLexer)
+    app.add_config_value(
+        "gp_highlighting_inline_literals",
+        default="off",
+        rebuild="env",
+        types=frozenset({str}),
+        description=(
+            "Inline literal auto-highlighting mode. Use ``'safe'`` to "
+            "highlight configured commands and clear path/directory literals."
+        ),
+    )
+    app.add_config_value(
+        "gp_highlighting_inline_commands",
+        default=[],
+        rebuild="env",
+        types=frozenset({list, tuple}),
+        description=(
+            "Command names eligible for safe inline literal highlighting "
+            "when ``gp_highlighting_inline_literals`` is ``'safe'``."
+        ),
+    )
+    app.add_role("cmd", cmd_role)
+    app.add_role("path", path_role)
+    app.add_role("dir", dir_role)
+    app.add_transform(HighlightingInlineTransform)
+
+    static_dir = str(pathlib.Path(__file__).parent / "_static")
+
+    def _add_static_path(app: Sphinx) -> None:
+        if static_dir not in app.config.html_static_path:
+            app.config.html_static_path.append(static_dir)
+
+    app.connect("builder-inited", _add_static_path)
+    app.add_css_file("css/sphinx_gp_highlighting.css")
+    return {
+        "version": _EXTENSION_VERSION,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
new file mode 100644
index 00000000..a6e43009
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
@@ -0,0 +1,12 @@
+.gp-sphinx-highlighting-inline {
+  white-space: nowrap;
+}
+
+.gp-sphinx-highlighting-inline--kind-path,
+.gp-sphinx-highlighting-inline--kind-dir {
+  color: var(--color-api-name, inherit);
+}
+
+.gp-sphinx-highlighting-inline--kind-dir::after {
+  color: var(--color-foreground-muted, currentColor);
+}
diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
new file mode 100644
index 00000000..b5940d03
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
@@ -0,0 +1,274 @@
+"""Inline literal roles and transforms for Sphinx highlighting."""
+
+from __future__ import annotations
+
+import re
+import typing as t
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+if t.TYPE_CHECKING:
+    from docutils.parsers.rst.states import Inliner
+
+InlineLiteralKind: t.TypeAlias = t.Literal["command", "shell-session", "path", "dir"]
+
+_BASE_CLASS = "gp-sphinx-highlighting-inline"
+_COMMAND_LANGUAGE = "bash"
+_SHELL_SESSION_LANGUAGE = "console"
+_SHELL_SESSION_RE = re.compile(r"^\$ \S")
+_PATH_RE = re.compile(r"^(?:~|/|\.{1,2}/)[^\s`]+$")
+_PATH_WITH_SEPARATOR_RE = re.compile(r"^(?:[\w.-]+/)+[\w.-]+/?$")
+
+
+def classify_inline_literal(
+    text: str,
+    *,
+    commands: t.Iterable[str] = (),
+) -> InlineLiteralKind | None:
+    """Classify a literal that is safe to highlight automatically.
+
+    Parameters
+    ----------
+    text : str
+        Literal text.
+    commands : iterable of str
+        Command names eligible for bare command highlighting.
+
+    Returns
+    -------
+    InlineLiteralKind | None
+        The safe literal kind, or ``None`` when the text should remain
+        an ordinary inline literal.
+
+    Examples
+    --------
+    >>> classify_inline_literal("tmuxp freeze my-session", commands=["tmuxp"])
+    'command'
+    >>> classify_inline_literal("~/.config/tmuxp/")
+    'dir'
+    >>> classify_inline_literal("module_name") is None
+    True
+    """
+    candidate = text.strip()
+    if not candidate or "\n" in candidate:
+        return None
+    if _SHELL_SESSION_RE.match(candidate):
+        return "shell-session"
+    first_word = candidate.split(maxsplit=1)[0]
+    if first_word in set(commands) and " " in candidate:
+        return "command"
+    if _is_path_like(candidate):
+        return "dir" if candidate.endswith("/") else "path"
+    return None
+
+
+def build_highlighted_literal(text: str, kind: InlineLiteralKind) -> nodes.literal:
+    """Build a literal node with package highlighting classes.
+
+    Parameters
+    ----------
+    text : str
+        Literal text.
+    kind : InlineLiteralKind
+        Highlighting kind.
+
+    Returns
+    -------
+    nodes.literal
+        Literal node ready for the Sphinx HTML writer.
+
+    Examples
+    --------
+    >>> node = build_highlighted_literal("tmuxp freeze my-session", "command")
+    >>> node["language"]
+    'bash'
+    >>> "gp-sphinx-highlighting-inline--kind-command" in node["classes"]
+    True
+    >>> "language" in build_highlighted_literal("~/.config/tmuxp/", "dir")
+    False
+    """
+    node = nodes.literal(
+        text,
+        text,
+        classes=[_BASE_CLASS, f"{_BASE_CLASS}--kind-{kind}"],
+    )
+    if kind in {"command", "shell-session"}:
+        node["classes"].extend(["code", "highlight"])
+        node["language"] = (
+            _SHELL_SESSION_LANGUAGE if kind == "shell-session" else _COMMAND_LANGUAGE
+        )
+    return node
+
+
+def cmd_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline shell commands.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = cmd_role(
+    ...     "cmd", "{cmd}`tmuxp freeze x`", "tmuxp freeze x", 1, None
+    ... )
+    >>> messages
+    []
+    >>> nodes_[0]["language"]
+    'bash'
+    """
+    return [build_highlighted_literal(text, "command")], []
+
+
+def path_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline filesystem paths.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = path_role("path", "{path}`~/x.py`", "~/x.py", 1, None)
+    >>> messages
+    []
+    >>> "gp-sphinx-highlighting-inline--kind-path" in nodes_[0]["classes"]
+    True
+    """
+    return [build_highlighted_literal(text, "path")], []
+
+
+def dir_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner | None,
+    options: dict[str, t.Any] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Role for inline filesystem directories.
+
+    Parameters
+    ----------
+    name : str
+        Role name.
+    rawtext : str
+        Full role markup.
+    text : str
+        Role content.
+    lineno : int
+        Source line number.
+    inliner : Inliner | None
+        Docutils inliner.
+    options : dict | None
+        Role options.
+    content : list | None
+        Role content lines.
+
+    Returns
+    -------
+    tuple[list[nodes.Node], list[nodes.system_message]]
+        Role output nodes and messages.
+
+    Examples
+    --------
+    >>> nodes_, messages = dir_role("dir", "{dir}`~/x/`", "~/x/", 1, None)
+    >>> messages
+    []
+    >>> "gp-sphinx-highlighting-inline--kind-dir" in nodes_[0]["classes"]
+    True
+    """
+    return [build_highlighted_literal(text, "dir")], []
+
+
+class HighlightingInlineTransform(Transform):
+    """Highlight safe inline literals when configured."""
+
+    default_priority = 120
+
+    def apply(self) -> None:
+        """Rewrite safe inline literals to highlighted literal nodes."""
+        env = getattr(self.document.settings, "env", None)
+        if env is None:
+            return
+        config = env.app.config
+        if getattr(config, "gp_highlighting_inline_literals", "off") != "safe":
+            return
+        commands = tuple(getattr(config, "gp_highlighting_inline_commands", ()))
+        for literal in list(self.document.findall(nodes.literal)):
+            if _should_skip_literal(literal):
+                continue
+            kind = classify_inline_literal(literal.astext(), commands=commands)
+            if kind is None:
+                continue
+            replacement = build_highlighted_literal(literal.astext(), kind)
+            replacement.source = literal.source
+            replacement.line = literal.line
+            literal.replace_self(replacement)
+
+
+def _is_path_like(text: str) -> bool:
+    """Return whether ``text`` looks like a filesystem path."""
+    return bool(_PATH_RE.match(text) or _PATH_WITH_SEPARATOR_RE.match(text))
+
+
+def _should_skip_literal(node: nodes.literal) -> bool:
+    """Return whether a literal should not be rewritten."""
+    classes: set[str] = set(node.get("classes", ()))
+    if _BASE_CLASS in classes:
+        return True
+    return bool("language" in node or "code" in classes)
diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
new file mode 100644
index 00000000..b82982e3
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
@@ -0,0 +1,75 @@
+"""Pygments lexers for documentation-focused code blocks."""
+
+from __future__ import annotations
+
+import re
+import typing as t
+
+from pygments.lexer import RegexLexer
+from pygments.token import Comment, Name, Punctuation, Text, Whitespace
+
+
+class DirectoryTreeLexer(RegexLexer):
+    r"""Lexer for ``tree(1)``-style directory listings.
+
+    The lexer targets documentation snippets that show project layouts
+    with box-drawing connectors. It deliberately uses standard Pygments
+    token types so existing Sphinx styles can colour the output without
+    package-specific token CSS.
+
+    Examples
+    --------
+    >>> from pygments.token import Token
+    >>> lexer = DirectoryTreeLexer()
+    >>> tokens = list(lexer.get_tokens("root\\n└── pyproject.toml  # config\\n"))
+    >>> (Token.Punctuation, '└──') in tokens
+    True
+    >>> (Token.Name, 'pyproject.toml') in tokens
+    True
+    >>> (Token.Comment.Single, '# config') in tokens
+    True
+    """
+
+    name = "Directory tree"
+    aliases = ["tree", "directory-tree", "dir-tree"]  # noqa: RUF012
+    filenames: t.ClassVar[list[str]] = []
+    mimetypes = ["text/x-directory-tree"]  # noqa: RUF012
+
+    tokens = {  # noqa: RUF012
+        "root": [
+            (r"\n", Whitespace),
+            (r"[ \t]+", Whitespace),
+            (r"(?:├──|└──|│)", Punctuation),
+            (r"#.*$", Comment.Single),
+            (r"[^/\s#]+/", Name.Namespace),
+            (r"[^/\s#.]+\.[^/\s#]+", Name),
+            (r"[^/\s#]+", Name.Namespace),
+            (r".", Text),
+        ],
+    }
+
+    @staticmethod
+    def analyse_text(text: str) -> float:
+        r"""Return a confidence score for tree-like text.
+
+        Parameters
+        ----------
+        text : str
+            Source text to inspect.
+
+        Returns
+        -------
+        float
+            ``0.7`` when box-drawing tree connectors are present,
+            otherwise ``0.0``.
+
+        Examples
+        --------
+        >>> DirectoryTreeLexer.analyse_text("root\\n└── pyproject.toml\\n")
+        0.7
+        >>> DirectoryTreeLexer.analyse_text("plain text")
+        0.0
+        """
+        if re.search(r"(?m)^[│ \t]*(?:├──|└──)\s+\S", text):
+            return 0.7
+        return 0.0
diff --git a/pyproject.toml b/pyproject.toml
index 1a3d12a1..951930ed 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -32,6 +32,7 @@ sphinx-gp-opengraph = { workspace = true }
 sphinx-gp-sitemap = { workspace = true }
 sphinx-gp-llms = { workspace = true }
 sphinx-gp-mermaid = { workspace = true }
+sphinx-gp-highlighting = { workspace = true }
 gp-furo-theme = { workspace = true }
 gp-sphinx = { workspace = true }
 sphinx-vite-builder = { workspace = true }
@@ -55,6 +56,7 @@ dev = [
   "sphinx-gp-sitemap",
   "sphinx-gp-llms",
   "sphinx-gp-mermaid",
+  "sphinx-gp-highlighting",
   "gp-furo-theme",
   "sphinx-vite-builder",
   # Docs
@@ -185,6 +187,7 @@ known-first-party = [
   "sphinx_gp_sitemap",
   "sphinx_gp_llms",
   "sphinx_gp_mermaid",
+  "sphinx_gp_highlighting",
 ]
 combine-as-imports = true
 required-imports = [
diff --git a/scripts/ci/package_tools.py b/scripts/ci/package_tools.py
index 6fb18936..d8d208a9 100644
--- a/scripts/ci/package_tools.py
+++ b/scripts/ci/package_tools.py
@@ -751,6 +751,27 @@ def smoke_sphinx_gp_mermaid(dist_dir: pathlib.Path, version: str) -> None:
         )
 
 
+def smoke_sphinx_gp_highlighting(dist_dir: pathlib.Path, version: str) -> None:
+    """Verify the sphinx-gp-highlighting extension and lexer entry point."""
+    with tempfile.TemporaryDirectory() as tmp:
+        python_path = _create_venv(pathlib.Path(tmp))
+        _install_into_venv(
+            python_path,
+            *_workspace_wheel_requirements(dist_dir),
+        )
+        _run_python(
+            python_path,
+            (
+                "from pygments.lexers import get_lexer_by_name; "
+                "import sphinx_gp_highlighting; "
+                "from sphinx_gp_highlighting import setup; "
+                "lexer = get_lexer_by_name('tree'); "
+                "assert lexer.__class__.__name__ == 'DirectoryTreeLexer'; "
+                "assert callable(setup)"
+            ),
+        )
+
+
 def smoke_sphinx_autodoc_fastmcp(dist_dir: pathlib.Path, version: str) -> None:
     """Verify the autodoc-fastmcp extension installs and imports cleanly."""
     with tempfile.TemporaryDirectory() as tmp:
@@ -882,6 +903,7 @@ def smoke_sphinx_vite_builder(dist_dir: pathlib.Path, version: str) -> None:
     "sphinx-gp-sitemap": smoke_sphinx_gp_sitemap,
     "sphinx-gp-llms": smoke_sphinx_gp_llms,
     "sphinx-gp-mermaid": smoke_sphinx_gp_mermaid,
+    "sphinx-gp-highlighting": smoke_sphinx_gp_highlighting,
     "gp-sphinx": smoke_gp_sphinx,
     "sphinx-autodoc-argparse": smoke_sphinx_autodoc_argparse,
     "sphinx-autodoc-api-style": smoke_sphinx_autodoc_api_style,
diff --git a/tests/docs/test_cluster_toctree.py b/tests/docs/test_cluster_toctree.py
index 6053a00a..9021afa3 100644
--- a/tests/docs/test_cluster_toctree.py
+++ b/tests/docs/test_cluster_toctree.py
@@ -96,6 +96,17 @@ def test_cluster_toctree_includes_shipped_js_packages() -> None:
     assert "packages/@gp-sphinx/furo-tokens/index" in leaves
 
 
+def test_cluster_toctree_includes_highlighting_package() -> None:
+    """The highlighting cluster includes code-highlighting helpers."""
+    rendered = package_reference._cluster_toctree_markdown(
+        "highlighting",
+        caption=None,
+        titlesonly=False,
+    )
+    leaves = _toctree_lines(rendered)
+    assert leaves == ["packages/sphinx-gp-highlighting/index"]
+
+
 def test_cluster_toctree_skips_emerging_packages() -> None:
     """No Emerging package appears in any cluster's toctree."""
     emerging_names = {
@@ -106,7 +117,14 @@ def test_cluster_toctree_skips_emerging_packages() -> None:
     if not emerging_names:
         pytest.skip("no Emerging packages in workspace; nothing to assert")
 
-    for cluster in ("theme-coordinator", "tokens", "autodoc", "ux", "build-seo"):
+    for cluster in (
+        "theme-coordinator",
+        "tokens",
+        "autodoc",
+        "ux",
+        "highlighting",
+        "build-seo",
+    ):
         rendered = package_reference._cluster_toctree_markdown(
             cluster,
             caption=None,
@@ -130,7 +148,14 @@ def test_cluster_toctree_leaves_are_alphabetical() -> None:
 
 def test_cluster_toctree_every_shipped_package_classified() -> None:
     """Every Shipped package falls into one of the recognized clusters."""
-    expected_clusters = {"theme-coordinator", "tokens", "autodoc", "ux", "build-seo"}
+    expected_clusters = {
+        "theme-coordinator",
+        "tokens",
+        "autodoc",
+        "ux",
+        "highlighting",
+        "build-seo",
+    }
     seen: set[str] = set()
     for cluster in expected_clusters:
         rendered = package_reference._cluster_toctree_markdown(
diff --git a/tests/docs/test_workspace_package_grid_groups.py b/tests/docs/test_workspace_package_grid_groups.py
index 9feeaf75..b5162ca6 100644
--- a/tests/docs/test_workspace_package_grid_groups.py
+++ b/tests/docs/test_workspace_package_grid_groups.py
@@ -39,6 +39,7 @@ def test_by_cluster_grid_emits_per_cluster_heading_and_prose() -> None:
         "## Tokens",
         "## Autodoc extensions",
         "## UX components",
+        "## Highlighting",
         "## Build & SEO",
     ]
     for heading in expected_headings:
@@ -50,9 +51,9 @@ def test_by_cluster_grid_emits_one_grid_per_nonempty_cluster() -> None:
     rendered = package_reference.workspace_package_grid_markdown(
         groups="by-cluster",
     )
-    # 5 clusters all populated (tokens, autodoc, ux, theme-coordinator,
-    # build-seo) -> 5 grids today.
-    assert rendered.count("::::{grid}") == 5
+    # 6 clusters all populated (tokens, autodoc, ux, theme-coordinator,
+    # highlighting, build-seo) -> 6 grids today.
+    assert rendered.count("::::{grid}") == 6
 
 
 def test_by_cluster_grid_includes_shipped_js_packages() -> None:
diff --git a/tests/ext/highlighting/test_inline.py b/tests/ext/highlighting/test_inline.py
new file mode 100644
index 00000000..9a15e7d0
--- /dev/null
+++ b/tests/ext/highlighting/test_inline.py
@@ -0,0 +1,158 @@
+"""Tests for ``sphinx-gp-highlighting`` inline literal helpers."""
+
+from __future__ import annotations
+
+import textwrap
+import typing as t
+
+import pytest
+
+from sphinx_gp_highlighting.inline import (
+    InlineLiteralKind,
+    build_highlighted_literal,
+    classify_inline_literal,
+)
+from tests._sphinx_scenarios import (
+    ScenarioFile,
+    SharedSphinxResult,
+    SphinxScenario,
+    build_shared_sphinx_result,
+    read_output,
+)
+
+
+class InlineClassificationFixture(t.NamedTuple):
+    """Case for safe inline literal classification."""
+
+    test_id: str
+    text: str
+    commands: tuple[str, ...]
+    expected: InlineLiteralKind | None
+
+
+_INLINE_CLASSIFICATION_FIXTURES: list[InlineClassificationFixture] = [
+    InlineClassificationFixture(
+        test_id="configured_command",
+        text="tmuxp freeze my-session",
+        commands=("tmuxp",),
+        expected="command",
+    ),
+    InlineClassificationFixture(
+        test_id="shell_session",
+        text="$ tmuxp freeze my-session",
+        commands=(),
+        expected="shell-session",
+    ),
+    InlineClassificationFixture(
+        test_id="home_dir",
+        text="~/.config/tmuxp/",
+        commands=(),
+        expected="dir",
+    ),
+    InlineClassificationFixture(
+        test_id="home_file",
+        text="~/.config/tmuxp/config.yaml",
+        commands=(),
+        expected="path",
+    ),
+    InlineClassificationFixture(
+        test_id="relative_dir",
+        text="./docs/",
+        commands=(),
+        expected="dir",
+    ),
+    InlineClassificationFixture(
+        test_id="plain_python_name",
+        text="module_name",
+        commands=("tmuxp",),
+        expected=None,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(InlineClassificationFixture._fields),
+    _INLINE_CLASSIFICATION_FIXTURES,
+    ids=[case.test_id for case in _INLINE_CLASSIFICATION_FIXTURES],
+)
+def test_classify_inline_literal_safe_shapes(
+    test_id: str,
+    text: str,
+    commands: tuple[str, ...],
+    expected: InlineLiteralKind | None,
+) -> None:
+    """Only safe command/path shapes are classified."""
+    assert classify_inline_literal(text, commands=commands) == expected, test_id
+
+
+def test_build_highlighted_literal_sets_language_for_commands() -> None:
+    """Command literals use Sphinx's inline Pygments path."""
+    node = build_highlighted_literal("tmuxp freeze my-session", "command")
+    assert "gp-sphinx-highlighting-inline" in node["classes"]
+    assert "gp-sphinx-highlighting-inline--kind-command" in node["classes"]
+    assert "code" in node["classes"]
+    assert node["language"] == "bash"
+
+
+def test_build_highlighted_literal_leaves_paths_unlanguaged() -> None:
+    """Path literals get semantic classes without pretending to be code."""
+    node = build_highlighted_literal("~/.config/tmuxp/", "dir")
+    assert "gp-sphinx-highlighting-inline--kind-dir" in node["classes"]
+    assert "language" not in node
+
+
+_CONF_PY = textwrap.dedent(
+    """\
+    extensions = ["myst_parser", "sphinx_gp_highlighting"]
+    gp_highlighting_inline_literals = "safe"
+    gp_highlighting_inline_commands = ["tmuxp"]
+    """
+)
+
+_INDEX_MD = textwrap.dedent(
+    """\
+    # Inline highlighting
+
+    Auto command: `tmuxp freeze my-session`
+
+    Auto dir: `~/.config/tmuxp/`
+
+    Plain literal: `module_name`
+
+    Explicit command: {cmd}`tmuxp freeze my-session`
+
+    Explicit path: {path}`~/.config/tmuxp/config.yaml`
+
+    Explicit dir: {dir}`~/.config/tmuxp/`
+    """
+)
+
+
+@pytest.fixture(scope="module")
+def highlighting_inline_result(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> SharedSphinxResult:
+    """Build a minimal Sphinx project with inline highlighting enabled."""
+    cache_root = tmp_path_factory.mktemp("highlighting-inline")
+    scenario = SphinxScenario(
+        files=(
+            ScenarioFile("conf.py", _CONF_PY),
+            ScenarioFile("index.md", _INDEX_MD),
+        ),
+    )
+    return build_shared_sphinx_result(cache_root, scenario)
+
+
+@pytest.mark.integration
+def test_inline_roles_and_safe_literals_render_classes(
+    highlighting_inline_result: SharedSphinxResult,
+) -> None:
+    """Explicit roles and safe backtick literals render package classes."""
+    html = read_output(highlighting_inline_result, "index.html")
+
+    assert "gp-sphinx-highlighting-inline--kind-command" in html
+    assert "gp-sphinx-highlighting-inline--kind-path" in html
+    assert "gp-sphinx-highlighting-inline--kind-dir" in html
+    assert "highlight-bash" in html
+    assert "module_name</span>" in html
+    assert "sphinx_gp_highlighting.css" in html
diff --git a/tests/ext/highlighting/test_tree_lexer.py b/tests/ext/highlighting/test_tree_lexer.py
new file mode 100644
index 00000000..040a9ca5
--- /dev/null
+++ b/tests/ext/highlighting/test_tree_lexer.py
@@ -0,0 +1,112 @@
+"""Tests for the ``sphinx-gp-highlighting`` directory tree lexer."""
+
+from __future__ import annotations
+
+import importlib
+import typing as t
+
+import pytest
+from pygments.token import Comment, Name, Punctuation
+
+from sphinx_gp_highlighting.lexers import DirectoryTreeLexer
+from tests._sphinx_scenarios import (
+    ScenarioFile,
+    SharedSphinxResult,
+    SphinxScenario,
+    build_shared_sphinx_result,
+    read_output,
+)
+
+
+class TreeAliasFixture(t.NamedTuple):
+    """Alias case for :class:`DirectoryTreeLexer` registration."""
+
+    test_id: str
+    alias: str
+
+
+_TREE_ALIAS_FIXTURES: list[TreeAliasFixture] = [
+    TreeAliasFixture(test_id="short_alias", alias="tree"),
+    TreeAliasFixture(test_id="directory_tree_alias", alias="directory-tree"),
+    TreeAliasFixture(test_id="dir_tree_alias", alias="dir-tree"),
+]
+
+
+@pytest.mark.parametrize(
+    list(TreeAliasFixture._fields),
+    _TREE_ALIAS_FIXTURES,
+    ids=[case.test_id for case in _TREE_ALIAS_FIXTURES],
+)
+def test_directory_tree_alias_resolves_to_lexer(test_id: str, alias: str) -> None:
+    """Each public tree alias resolves to the package lexer."""
+    get_lexer_by_name = t.cast(
+        t.Callable[[str], object],
+        getattr(importlib.import_module("pygments.lexers"), "get_lexer_by_name"),
+    )
+    lexer = get_lexer_by_name(alias)
+    assert isinstance(lexer, DirectoryTreeLexer), test_id
+
+
+def test_directory_tree_lexer_tokenizes_connectors_names_and_comments() -> None:
+    """Tree output receives structural tokens instead of generic console output."""
+    source = (
+        "python_module\n"
+        "├── tmuxp_plugin_my_plugin_module\n"
+        "│   ├── __init__.py\n"
+        "│   └── plugin.py\n"
+        "└── pyproject.toml  # Python project configuration file\n"
+    )
+
+    tokens = list(DirectoryTreeLexer().get_tokens(source))
+
+    assert (Name.Namespace, "python_module") in tokens
+    assert (Punctuation, "├──") in tokens
+    assert (Punctuation, "│") in tokens
+    assert (Punctuation, "└──") in tokens
+    assert (Name.Namespace, "tmuxp_plugin_my_plugin_module") in tokens
+    assert (Name, "__init__.py") in tokens
+    assert (Name, "pyproject.toml") in tokens
+    assert (Comment.Single, "# Python project configuration file") in tokens
+
+
+_CONF_PY = """\
+extensions = ["myst_parser", "sphinx_gp_highlighting"]
+"""
+
+_INDEX_MD = """\
+# Tree block
+
+```tree
+python_module
+├── tmuxp_plugin_my_plugin_module
+│   ├── __init__.py
+│   └── plugin.py
+└── pyproject.toml  # Python project configuration file
+```
+"""
+
+
+@pytest.fixture(scope="module")
+def highlighting_tree_result(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> SharedSphinxResult:
+    """Build a minimal Sphinx project with a ``tree`` fence."""
+    cache_root = tmp_path_factory.mktemp("highlighting-tree")
+    scenario = SphinxScenario(
+        files=(
+            ScenarioFile("conf.py", _CONF_PY),
+            ScenarioFile("index.md", _INDEX_MD),
+        ),
+    )
+    return build_shared_sphinx_result(cache_root, scenario)
+
+
+@pytest.mark.integration
+def test_tree_fence_renders_with_tree_highlight_class(
+    highlighting_tree_result: SharedSphinxResult,
+) -> None:
+    """A MyST ``tree`` fence renders through the package lexer."""
+    html = read_output(highlighting_tree_result, "index.html")
+    assert "highlight-tree" in html
+    assert '<span class="p">├──</span>' in html
+    assert '<span class="c1"># Python project configuration file</span>' in html
diff --git a/tests/test_package_reference.py b/tests/test_package_reference.py
index 8823d597..e6f3007f 100644
--- a/tests/test_package_reference.py
+++ b/tests/test_package_reference.py
@@ -24,6 +24,7 @@ def test_workspace_packages_lists_publishable_packages() -> None:
         "sphinx-gp-sitemap",
         "sphinx-gp-llms",
         "sphinx-gp-mermaid",
+        "sphinx-gp-highlighting",
         "gp-sphinx",
         "sphinx-autodoc-argparse",
         "sphinx-autodoc-api-style",
diff --git a/uv.lock b/uv.lock
index f02c343e..2b87a6de 100644
--- a/uv.lock
+++ b/uv.lock
@@ -27,6 +27,7 @@ members = [
     "sphinx-autodoc-sphinx",
     "sphinx-autodoc-typehints-gp",
     "sphinx-fonts",
+    "sphinx-gp-highlighting",
     "sphinx-gp-llms",
     "sphinx-gp-mermaid",
     "sphinx-gp-opengraph",
@@ -536,6 +537,7 @@ dev = [
     { name = "sphinx-autodoc-fastmcp" },
     { name = "sphinx-autodoc-pytest-fixtures" },
     { name = "sphinx-autodoc-sphinx" },
+    { name = "sphinx-gp-highlighting" },
     { name = "sphinx-gp-llms" },
     { name = "sphinx-gp-mermaid" },
     { name = "sphinx-gp-opengraph" },
@@ -577,6 +579,7 @@ dev = [
     { name = "sphinx-autodoc-fastmcp", editable = "packages/sphinx-autodoc-fastmcp" },
     { name = "sphinx-autodoc-pytest-fixtures", editable = "packages/sphinx-autodoc-pytest-fixtures" },
     { name = "sphinx-autodoc-sphinx", editable = "packages/sphinx-autodoc-sphinx" },
+    { name = "sphinx-gp-highlighting", editable = "packages/sphinx-gp-highlighting" },
     { name = "sphinx-gp-llms", editable = "packages/sphinx-gp-llms" },
     { name = "sphinx-gp-mermaid", editable = "packages/sphinx-gp-mermaid" },
     { name = "sphinx-gp-opengraph", editable = "packages/sphinx-gp-opengraph" },
@@ -1818,6 +1821,24 @@ dependencies = [
 [package.metadata]
 requires-dist = [{ name = "sphinx", specifier = ">=8.1" }]
 
+[[package]]
+name = "sphinx-gp-highlighting"
+version = "0.0.1a32"
+source = { editable = "packages/sphinx-gp-highlighting" }
+dependencies = [
+    { name = "docutils" },
+    { name = "pygments" },
+    { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "docutils" },
+    { name = "pygments" },
+    { name = "sphinx", specifier = ">=8.1" },
+]
+
 [[package]]
 name = "sphinx-gp-llms"
 version = "0.0.1a32"

From 654fdbc1e056637a2dc1cd0135bb9d0ecdcaee55 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 11:09:18 -0500
Subject: [PATCH 3/9] highlighting(docs): Add live examples page

why: The highlighting reference must render generated API sections, and
users need a visible examples page that demonstrates the new tree lexer
and inline literal roles.

what:
- Wrap reference autodoc directives in eval-rst blocks
- Add live tree and inline highlighting examples
- Opt the package landing into the examples page
---
 .../sphinx-gp-highlighting/examples.md        | 56 +++++++++++++++++++
 .../sphinx-gp-highlighting/reference.md       |  6 ++
 .../sphinx-gp-highlighting/pyproject.toml     |  3 +
 tests/test_docs_package_pages.py              |  1 +
 4 files changed, 66 insertions(+)
 create mode 100644 docs/packages/sphinx-gp-highlighting/examples.md

diff --git a/docs/packages/sphinx-gp-highlighting/examples.md b/docs/packages/sphinx-gp-highlighting/examples.md
new file mode 100644
index 00000000..1f0bd443
--- /dev/null
+++ b/docs/packages/sphinx-gp-highlighting/examples.md
@@ -0,0 +1,56 @@
+(sphinx-gp-highlighting-examples)=
+
+# Examples
+
+## Directory trees
+
+Use `tree` for static project layouts. It highlights connector glyphs,
+directory names, filenames, and comments without pretending the snippet
+is a shell transcript.
+
+```tree
+python_module
+├── tmuxp_plugin_my_plugin_module
+│   ├── __init__.py
+│   └── plugin.py
+└── pyproject.toml  # Python project configuration file
+```
+
+The longer aliases render the same way:
+
+```directory-tree
+docs/
+├── conf.py
+├── index.md
+└── packages/
+```
+
+```dir-tree
+src/
+└── package_name/
+    └── __init__.py
+```
+
+## Inline literals
+
+Explicit roles let prose declare intent while keeping the familiar
+inline-code shape:
+
+Run {cmd}`tmuxp freeze my-session`, then edit
+{path}`~/.config/tmuxp/config.yaml`.
+
+Store plugin modules under {dir}`./plugins/`.
+
+## Safe automatic highlighting
+
+Safe automatic highlighting is opt-in and command allow-list based:
+
+```python
+gp_highlighting_inline_literals = "safe"
+gp_highlighting_inline_commands = ["tmuxp", "agentgrep"]
+```
+
+With that configuration, ordinary backtick literals such as
+`tmuxp freeze my-session`, `agentgrep search mermaid`, and
+`~/.config/tmuxp/` can receive the same package-owned inline classes,
+while names such as `module_name` stay unchanged.
diff --git a/docs/packages/sphinx-gp-highlighting/reference.md b/docs/packages/sphinx-gp-highlighting/reference.md
index 74a59edc..fff0d218 100644
--- a/docs/packages/sphinx-gp-highlighting/reference.md
+++ b/docs/packages/sphinx-gp-highlighting/reference.md
@@ -21,14 +21,19 @@
 
 ## Config values
 
+```{eval-rst}
 .. autoconfigvalues:: sphinx_gp_highlighting
+```
 
 ## Roles
 
+```{eval-rst}
 .. autoroles:: sphinx_gp_highlighting
+```
 
 ## API
 
+```{eval-rst}
 .. autofunction:: sphinx_gp_highlighting.setup
 
 .. autoclass:: sphinx_gp_highlighting.lexers.DirectoryTreeLexer
@@ -36,3 +41,4 @@
 .. autofunction:: sphinx_gp_highlighting.inline.classify_inline_literal
 
 .. autofunction:: sphinx_gp_highlighting.inline.build_highlighted_literal
+```
diff --git a/packages/sphinx-gp-highlighting/pyproject.toml b/packages/sphinx-gp-highlighting/pyproject.toml
index 05257f91..99d85c38 100644
--- a/packages/sphinx-gp-highlighting/pyproject.toml
+++ b/packages/sphinx-gp-highlighting/pyproject.toml
@@ -44,3 +44,6 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/sphinx_gp_highlighting"]
+
+[tool.gp-sphinx.docs]
+showcase = ["examples"]
diff --git a/tests/test_docs_package_pages.py b/tests/test_docs_package_pages.py
index 8ebe85d4..92739eab 100644
--- a/tests/test_docs_package_pages.py
+++ b/tests/test_docs_package_pages.py
@@ -59,6 +59,7 @@ def _autodoc_and_ux_package_paths() -> list[pathlib.Path]:
 PACKAGE_PAGES = _autodoc_and_ux_package_paths()
 LIVE_DEMO_MARKERS = (
     "```{eval-rst}",
+    "```tree",
     "```{gp-sphinx-badge-demo}",
     ":::{auto-pytest-plugin}",
     "```{argparse}",

From 51c5fd956e122e3cb409497e539d7e0560ccb69c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 11:18:48 -0500
Subject: [PATCH 4/9] highlighting(fix): Narrow inline paths

why: Safe inline highlighting should not turn every slash-containing
literal into a filesystem path. Downstream docs include MIME types,
MCP method names, option aliases, and HTTP routes that should remain
plain inline literals.

what:
- Restrict automatic path detection to home, dot-relative, common
  absolute filesystem roots, Windows paths, and clear relative
  directory/file shapes
- Add classifier regression cases for slash-containing non-path
  literals seen in downstream docs builds
---
 .../src/sphinx_gp_highlighting/inline.py      | 84 ++++++++++++++++++-
 tests/ext/highlighting/test_inline.py         | 30 +++++++
 2 files changed, 110 insertions(+), 4 deletions(-)

diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
index b5940d03..b47895e4 100644
--- a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/inline.py
@@ -17,8 +17,35 @@
 _COMMAND_LANGUAGE = "bash"
 _SHELL_SESSION_LANGUAGE = "console"
 _SHELL_SESSION_RE = re.compile(r"^\$ \S")
-_PATH_RE = re.compile(r"^(?:~|/|\.{1,2}/)[^\s`]+$")
-_PATH_WITH_SEPARATOR_RE = re.compile(r"^(?:[\w.-]+/)+[\w.-]+/?$")
+_HOME_OR_DOT_PATH_RE = re.compile(r"^(?:~|\.{1,2}/)[^\s`]*$")
+_WINDOWS_PATH_RE = re.compile(r"^[A-Za-z]:[\\/][^\s`]+$")
+_RELATIVE_DIR_RE = re.compile(r"^(?:[\w.-]+/)+$")
+_RELATIVE_FILE_RE = re.compile(r"^(?:[\w.-]+/)+[\w.-]+\.[A-Za-z0-9][\w.-]*$")
+_ABSOLUTE_PATH_ROOTS = frozenset(
+    {
+        "Applications",
+        "Library",
+        "Users",
+        "bin",
+        "dev",
+        "etc",
+        "home",
+        "lib",
+        "lib64",
+        "mnt",
+        "opt",
+        "proc",
+        "root",
+        "run",
+        "sbin",
+        "srv",
+        "sys",
+        "tmp",
+        "usr",
+        "var",
+        "Volumes",
+    }
+)
 
 
 def classify_inline_literal(
@@ -262,8 +289,57 @@ def apply(self) -> None:
 
 
 def _is_path_like(text: str) -> bool:
-    """Return whether ``text`` looks like a filesystem path."""
-    return bool(_PATH_RE.match(text) or _PATH_WITH_SEPARATOR_RE.match(text))
+    """Return whether ``text`` looks like a filesystem path.
+
+    Examples
+    --------
+    >>> _is_path_like("~/.config/tmuxp/")
+    True
+    >>> _is_path_like("/mnt/c/Users/example")
+    True
+    >>> _is_path_like("application/json")
+    False
+    """
+    return bool(
+        _HOME_OR_DOT_PATH_RE.match(text)
+        or _WINDOWS_PATH_RE.match(text)
+        or _is_absolute_filesystem_path(text)
+        or _is_relative_filesystem_path(text)
+    )
+
+
+def _is_absolute_filesystem_path(text: str) -> bool:
+    """Return whether ``text`` starts with a common absolute path root.
+
+    Examples
+    --------
+    >>> _is_absolute_filesystem_path("/proc/version")
+    True
+    >>> _is_absolute_filesystem_path("/api/pull")
+    False
+    """
+    if not text.startswith("/"):
+        return False
+    first_component = text.removeprefix("/").split("/", maxsplit=1)[0]
+    return first_component in _ABSOLUTE_PATH_ROOTS
+
+
+def _is_relative_filesystem_path(text: str) -> bool:
+    """Return whether ``text`` is a conservative bare relative path.
+
+    Examples
+    --------
+    >>> _is_relative_filesystem_path("docs/conf.py")
+    True
+    >>> _is_relative_filesystem_path("resources/read")
+    False
+    """
+    if text.startswith(("/", "~", "./", "../")):
+        return False
+    first_component = text.split("/", maxsplit=1)[0]
+    if "." in first_component and not first_component.startswith("."):
+        return False
+    return bool(_RELATIVE_DIR_RE.match(text) or _RELATIVE_FILE_RE.match(text))
 
 
 def _should_skip_literal(node: nodes.literal) -> bool:
diff --git a/tests/ext/highlighting/test_inline.py b/tests/ext/highlighting/test_inline.py
index 9a15e7d0..255d47d2 100644
--- a/tests/ext/highlighting/test_inline.py
+++ b/tests/ext/highlighting/test_inline.py
@@ -61,6 +61,36 @@ class InlineClassificationFixture(t.NamedTuple):
         commands=(),
         expected="dir",
     ),
+    InlineClassificationFixture(
+        test_id="wsl_absolute_path",
+        text="/mnt/c/Users/example/AppData/Roaming",
+        commands=(),
+        expected="path",
+    ),
+    InlineClassificationFixture(
+        test_id="mime_type",
+        text="application/json",
+        commands=(),
+        expected=None,
+    ),
+    InlineClassificationFixture(
+        test_id="mcp_method",
+        text="resources/read",
+        commands=(),
+        expected=None,
+    ),
+    InlineClassificationFixture(
+        test_id="cli_option_pair",
+        text="-0/--print0",
+        commands=(),
+        expected=None,
+    ),
+    InlineClassificationFixture(
+        test_id="http_api_endpoint",
+        text="/api/pull",
+        commands=(),
+        expected=None,
+    ),
     InlineClassificationFixture(
         test_id="plain_python_name",
         text="module_name",

From 19c6f6c0cce54cc8070d56ff90f57dcb3adc6008 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 13:35:44 -0500
Subject: [PATCH 5/9] highlighting(fix): Add typed marker

why: The package advertises typed inline annotations, so installed
wheels need the PEP 561 marker for downstream type checkers.

what:
- Add the sphinx_gp_highlighting py.typed marker
---
 .../sphinx-gp-highlighting/src/sphinx_gp_highlighting/py.typed   | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/py.typed

diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/py.typed b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/py.typed
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/py.typed
@@ -0,0 +1 @@
+

From ee9d9580a6b0d5e76b9ef34347d7b2efca332663 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 13:40:27 -0500
Subject: [PATCH 6/9] highlighting(fix): Repair tree doctest

why: The tree lexer examples must run when the package source is
collected by the normal doctest gate.

what:
- Use multiline doctest input with real newlines
- Keep raw docstrings compatible with ruff D301
---
 .../src/sphinx_gp_highlighting/lexers.py              | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
index b82982e3..2759257e 100644
--- a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/lexers.py
@@ -21,7 +21,11 @@ class DirectoryTreeLexer(RegexLexer):
     --------
     >>> from pygments.token import Token
     >>> lexer = DirectoryTreeLexer()
-    >>> tokens = list(lexer.get_tokens("root\\n└── pyproject.toml  # config\\n"))
+    >>> source = '''\
+    ... root
+    ... └── pyproject.toml  # config
+    ... '''
+    >>> tokens = list(lexer.get_tokens(source))
     >>> (Token.Punctuation, '└──') in tokens
     True
     >>> (Token.Name, 'pyproject.toml') in tokens
@@ -65,7 +69,10 @@ def analyse_text(text: str) -> float:
 
         Examples
         --------
-        >>> DirectoryTreeLexer.analyse_text("root\\n└── pyproject.toml\\n")
+        >>> DirectoryTreeLexer.analyse_text('''\
+        ... root
+        ... └── pyproject.toml
+        ... ''')
         0.7
         >>> DirectoryTreeLexer.analyse_text("plain text")
         0.0

From b1f287f7f24849f933bd8434d3ca00d8e6443c26 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 13:42:12 -0500
Subject: [PATCH 7/9] test(highlighting): Collect doctests

why: The standard pytest gate should cover the new highlighting package
source just like the other workspace packages.

what:
- Add sphinx-gp-highlighting source to pytest testpaths
---
 pyproject.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pyproject.toml b/pyproject.toml
index 951930ed..cf9d05cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -249,6 +249,7 @@ testpaths = [
   "packages/sphinx-ux-badges/src",
   "packages/sphinx-gp-opengraph/src",
   "packages/sphinx-gp-sitemap/src",
+  "packages/sphinx-gp-highlighting/src",
   "packages/sphinx-gp-llms/src",
   "packages/sphinx-gp-mermaid/src",
   "packages/sphinx-vite-builder/src",

From 951375edd477bfed4e9a6204c04e5c2b8b93898e Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 14:37:16 -0500
Subject: [PATCH 8/9] highlighting(fix): Style command kinds

why: The highlighting package emits command and shell-session modifier
classes, so its own CSS must target those package-owned hooks for
standalone consumers.

what:
- Add CSS selectors for command and shell-session inline modifiers
- Cover emitted inline modifier classes with a focused regression test
---
 .../_static/css/sphinx_gp_highlighting.css    |  5 ++
 tests/ext/highlighting/test_inline.py         | 61 +++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
index a6e43009..e230d5af 100644
--- a/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
+++ b/packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/sphinx_gp_highlighting.css
@@ -2,6 +2,11 @@
   white-space: nowrap;
 }
 
+.gp-sphinx-highlighting-inline--kind-command,
+.gp-sphinx-highlighting-inline--kind-shell-session {
+  color: var(--color-code-foreground, inherit);
+}
+
 .gp-sphinx-highlighting-inline--kind-path,
 .gp-sphinx-highlighting-inline--kind-dir {
   color: var(--color-api-name, inherit);
diff --git a/tests/ext/highlighting/test_inline.py b/tests/ext/highlighting/test_inline.py
index 255d47d2..06aaf6ce 100644
--- a/tests/ext/highlighting/test_inline.py
+++ b/tests/ext/highlighting/test_inline.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import pathlib
 import textwrap
 import typing as t
 
@@ -20,6 +21,11 @@
     read_output,
 )
 
+_HIGHLIGHTING_CSS = pathlib.Path(
+    "packages/sphinx-gp-highlighting/src/sphinx_gp_highlighting/_static/css/"
+    "sphinx_gp_highlighting.css"
+)
+
 
 class InlineClassificationFixture(t.NamedTuple):
     """Case for safe inline literal classification."""
@@ -100,6 +106,38 @@ class InlineClassificationFixture(t.NamedTuple):
 ]
 
 
+class InlineCssTargetFixture(t.NamedTuple):
+    """Case for CSS self-containment of emitted inline classes."""
+
+    test_id: str
+    text: str
+    kind: InlineLiteralKind
+
+
+_INLINE_CSS_TARGET_FIXTURES: list[InlineCssTargetFixture] = [
+    InlineCssTargetFixture(
+        test_id="command",
+        text="tmuxp freeze my-session",
+        kind="command",
+    ),
+    InlineCssTargetFixture(
+        test_id="shell_session",
+        text="$ tmuxp freeze my-session",
+        kind="shell-session",
+    ),
+    InlineCssTargetFixture(
+        test_id="path",
+        text="~/.config/tmuxp/config.yaml",
+        kind="path",
+    ),
+    InlineCssTargetFixture(
+        test_id="dir",
+        text="~/.config/tmuxp/",
+        kind="dir",
+    ),
+]
+
+
 @pytest.mark.parametrize(
     list(InlineClassificationFixture._fields),
     _INLINE_CLASSIFICATION_FIXTURES,
@@ -131,6 +169,29 @@ def test_build_highlighted_literal_leaves_paths_unlanguaged() -> None:
     assert "language" not in node
 
 
+@pytest.mark.parametrize(
+    list(InlineCssTargetFixture._fields),
+    _INLINE_CSS_TARGET_FIXTURES,
+    ids=[case.test_id for case in _INLINE_CSS_TARGET_FIXTURES],
+)
+def test_emitted_inline_modifiers_are_targeted_by_css(
+    test_id: str,
+    text: str,
+    kind: InlineLiteralKind,
+) -> None:
+    """Package CSS targets every emitted inline modifier class."""
+    css = _HIGHLIGHTING_CSS.read_text(encoding="utf-8")
+    node = build_highlighted_literal(text, kind)
+    modifiers = [
+        cls
+        for cls in node["classes"]
+        if cls.startswith("gp-sphinx-highlighting-inline--kind-")
+    ]
+    assert modifiers, test_id
+    for modifier in modifiers:
+        assert f".{modifier}" in css, test_id
+
+
 _CONF_PY = textwrap.dedent(
     """\
     extensions = ["myst_parser", "sphinx_gp_highlighting"]

From 23bd84f751a63c6b84f7e3dbe1b11a2061c67e7b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 5 Jul 2026 15:46:15 -0500
Subject: [PATCH 9/9] docs(fix[changelog]): Focus PR entry

why: The unreleased changelog entry should describe the PR's user-facing
impact without reading like release-prep prose.

what:
- Add product-focused notes for responsive Mermaid diagrams
- Add product-focused notes for reusable code highlighting
---
 CHANGES | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/CHANGES b/CHANGES
index baa55c88..675cbef4 100644
--- a/CHANGES
+++ b/CHANGES
@@ -18,6 +18,25 @@ $ uv add gp-sphinx --prerelease allow
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+### What's new
+
+#### Responsive Mermaid diagrams
+
+Mermaid diagrams gain a `:responsive:` option with `fit` and
+`preserve` policies. Use `fit` when a diagram should scale to the
+content column, and `preserve` when a dense architecture map or matrix
+should keep its readable width and scroll horizontally instead.
+See {ref}`sphinx-gp-mermaid-how-to` for authoring guidance. (#64)
+
+#### Code highlighting for trees, commands, and paths
+
+`sphinx-gp-highlighting` gives docs a dedicated `tree` lexer for
+directory layout snippets plus inline roles for commands, paths, and
+directories. Projects can opt in to safe automatic highlighting for
+shell prompts, allow-listed commands, and clear filesystem literals
+while ordinary code names stay unchanged. See
+{ref}`sphinx-gp-highlighting` for setup and examples. (#64)
+
 ## gp-sphinx 0.0.1a32 (2026-07-04)
 
 ### What's new
@@ -791,4 +810,3 @@ build cleanly. Section IDs are now namespaced per program so
 (#16)
 
 [Furo]: https://github.com/pradyunsg/furo
-