Skip to content

feat(gp-sphinx[fonts]): default preload covers heading/italic/bold-code FOUT#34

Open
tony wants to merge 2 commits intomainfrom
sync-fonts
Open

feat(gp-sphinx[fonts]): default preload covers heading/italic/bold-code FOUT#34
tony wants to merge 2 commits intomainfrom
sync-fonts

Conversation

@tony
Copy link
Copy Markdown
Member

@tony tony commented May 7, 2026

Summary

  • Expand DEFAULT_SPHINX_FONT_PRELOAD from the existing trio (Sans 400, Sans 700, Mono 400) to cover every face Furo / furo-tw.css is observed to demand above the fold.
  • Eliminate first-paint FOUT on bold headings, italic body text, and bold inline code by default — downstream consumers no longer need to extend the list locally.

Why these specific faces

Face added Surface that needs it
Sans 500 normal h1h6, sidebar labels
Sans 600 normal blockquote.epigraph
Sans 400 italic <em> body text, announcement-bar emphasis
Mono 700 normal bold inline code (<strong><code>, MyST **\code`**`)

These were discovered while debugging first-paint FOUT on libtmux-mcp (tmux-python/libtmux-mcp#36). All four are pulled by Furo's own CSS, not project-specific code, so every gp-furo consumer that renders any of these surfaces ships the same FOUT until they extend the preload list themselves. Moving the additions upstream means new sites get correct first-paint behaviour for free.

Changes

  • packages/gp-sphinx/src/gp_sphinx/defaults.py: Append the four tuples; reorder so faces are grouped by family with weights ascending. Doctest len(DEFAULT_SPHINX_FONT_PRELOAD) bumped from 3 to 7. Docstring expanded to name each face's purpose so the constant explains itself.
  • tests/test_config.py: test_merge_sphinx_config_default_fonts length assertion bumped from 3 to 7 (matches the existing brittle-by-count style of nearby asserts).
  • docs/configuration.md: Font defaults table cell for the constant shortened to a one-line summary so it stays readable as the list grows.
  • CHANGES: New ### What's new entry under ## gp-sphinx 0.0.1 (unreleased) describing the FOUT impact.

What is NOT in scope

  • Adding more faces (Sans 300, Mono 500/600, more italics). The constant is intentionally minimal — every preload byte contends with critical CSS/HTML on the network. Only faces with documented above-the-fold use go in.
  • Promoting the constant from gp-sphinx defaults into sphinx-fonts itself. The current ownership (gp-sphinx ships the IBM-Plex-flavoured defaults; sphinx-fonts is theme-agnostic and registers the config option) is correct.
  • Editing libtmux-mcp's local override. That cleanup happens in libtmux-mcp once a gp-sphinx release ships these defaults.

Test plan

  • uv run ruff format . — formatting unchanged
  • uv run ruff check . --fix --show-fixes — lint clean
  • uv run mypy — types clean across 221 source files
  • uv run pytest --doctest-modules packages/gp-sphinx/src/gp_sphinx/defaults.py — doctest passes with new length
  • uv run pytest tests/test_config.py::test_merge_sphinx_config_default_fonts — assertion passes with == 7
  • uv run pytest — full suite green (1473 passed, 161 skipped)

tony added 2 commits May 6, 2026 19:07
…ading/italic/bold-code FOUT

The default trio (Sans 400/700 + Mono 400) covered body text and
plain code blocks, but Furo / furo-tw.css renders headings and
sidebar labels at Sans 500, blockquote.epigraph at Sans 600, em
above the fold at Sans 400 italic, and bold inline code at Mono
700. Without preload, those weights downloaded after first paint
and the affected text visibly popped in.

Add the four faces to the default list. Doctest length and the
test_config assertion that hardcoded 3 are bumped to 7. The
configuration.md entry for the constant is shortened so the table
cell stays readable as the list grows.
Heading/italic/bold-code FOUT no longer requires consumer overrides.
@codecov-commenter
Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.57%. Comparing base (6736f2a) to head (d3a40f3).

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #34   +/-   ##
=======================================
  Coverage   91.57%   91.57%           
=======================================
  Files         205      205           
  Lines       16814    16814           
=======================================
  Hits        15398    15398           
  Misses       1416     1416           

☔ View full report in Codecov by Sentry.
📢 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants