[tony]

Not to be merged yet. The [DO NOT MERGE] Deploy docs/libtmux-top-bar commit adds this branch to the docs workflow so the build deploys to https://libtmux.git-pull.com for review. Drop that commit before merging, and squash the later fix commits into the header commits.

What this adds

The two bars from https://libtmux.org, on every page of the Sphinx docs.

Top bar

• the libtmux wordmark, linking to https://libtmux.org/en/
• the port picker (16 ports in five families, plus the tmux CLI entry) with its search box; entries link to https://libtmux.org/en/<port>/latest/core/, and Kotlin, Scala and F# are listed as having no matching page, as on libtmux.org
• GitHub and PyPI chips, and the Packages menu with libtmux.org's ten rows
• a Search chip that opens this site's own Sphinx search
• the Auto / Light / Dark switch, which becomes one cycle button at 40rem and below
• the Menu panel below 48rem

Documentation bar (new in this update)

• the documentation picker, showing Core Library with its 0.x badge and the current section, Home. It opens "Choose documentation" with the count badge, the "Find documentation…" search, a Home row, and Core Library, MCP and Workspace Manager with their sections in two columns, the current product highlighted and open, and the "Python · latest · en" footer. Every entry links to the libtmux.org pages the reference uses (/en/py/latest/...)
• the version selector ("latest") and the language selector ("English"), each offering that single choice, with the reference's controls
• the status badges and their toggletip cards
• below 40rem the controls shrink as on libtmux.org; at 24rem and below they sit behind the settings button
• the two navigation buttons, wired to Furo's sidebar and contents drawers; Furo's own mobile header and theme toggles are hidden, so each control exists once

As on libtmux.org, the documentation bar scrolls away and the top bar stays. The two bars' heights are written to --site-header-height and --site-context-height; Furo's sticky sidebar and contents start below the top bar, and the drawers Furo fixes to the viewport open below whatever part of the two bars is on screen.

The version and locale switchers of the top bar are left out, as before.

GitHub and PyPI chips

The chips point at this project (tmux-python/libtmux and libtmux on PyPI). Labels and appearance are identical to libtmux.org; only the URLs differ. libtmux.org shows the libtmux pair on every Python page because its chips are port-wide. The Packages panel keeps libtmux.org's ten rows, and its footer names this repository.

How it fits the theme

• docs/_templates/site-header.html holds the top bar and, in its first three lines, the only per-site data: repository, package and current product. It includes docs/_templates/site-context.html, the documentation bar. page.html includes the first.
• docs/_static/css/site-bars.css is plain CSS scoped to the two bars. Lengths are px, because Furo scales the root font size above 1280px and the bars must keep libtmux.org's size. Colours are the Python brand's, for light and dark. The documentation bar's rules are taken from libtmux.org's built CSS.
• docs/_static/js/site-bars.js is vanilla JS: the pickers (search, group filter, arrow keys, Escape, placement), the toggletips, the compact settings, the drawer buttons and the colour-scheme control.
• The top bar is a div role="banner", not a <header>, so Furo's scroll-spy offset still finds its own header. The switch writes Furo's body[data-theme] and localStorage.theme.
• The CSS and JS are named site-bars.* because the docs host's cache ignores the query string Sphinx adds and is invalidated for three paths only; a republished site-header.* kept serving the earlier files.

Pixel comparison against https://libtmux.org/en/py/latest/core/

Headless Chromium, animations off, fonts loaded, scrollbars hidden, light and dark. The top bar and its panels were captured at 375, 768, 1100, 1280 and 1600px; the documentation bar and its picker at those widths plus 320 and 430px.

State	Differing pixels
Top bar, closed	0 at every width and scheme
Documentation bar, closed	0 at every width and scheme, 320 to 1600px
Documentation picker panel	118 to 164
Language panel	88 to 102
Port picker panel	22 to 60
Menu panel	0 to 54
Packages panel (768 and up)	libtmux

The open-panel counts are the rounded corners of each panel, where the page behind it differs from the reference page. One difference remains by decision: libtmux.org fills the version panel from its release list ("Releases: v0.62.0", "Development: latest"); here it offers only "latest". The language selector does not open at 375px in either page, because the settings button holds it at 24rem and below.

Computed styles and rects of both bars match the reference element by element. Screenshot pairs and diffs are kept outside the repo.

Test plan

• uv run ruff format --check ., uv run ruff check ., uv run mypy
• sphinx-build -b dirhtml (as just html runs it) builds
• Pixel comparison as above
• Colour switch sets body[data-theme] and localStorage.theme; Search opens the local search page; the bars survive in-page navigation; the picker filter, Escape, toggletips and the 320px settings button work; at 430px the two buttons open Furo's drawers below the bars
• Deployed to https://libtmux.git-pull.com: both bars present at 1280px, light and dark. Pages cached before the deploy keep their old markup until the cache expires

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.37%. Comparing base (d3d9d88) to head (a33476c).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #846   +/-   ##
=======================================
  Coverage   52.37%   52.37%           
=======================================
  Files          26       26           
  Lines        3729     3729           
  Branches      747      747           
=======================================
  Hits         1953     1953           
  Misses       1472     1472           
  Partials      304      304           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.