From 5891c6fb88a79e49bb94095e6f3bbe698a74b9a5 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 17 May 2026 16:08:21 -0500
Subject: [PATCH 1/4] theme(fix[sidebar-logo]) Preload + fetchpriority=high for
 logo HTML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

why: Sidebar logo is the LCP element on every consumer docs site,
and the bundled templates were emitting `<link rel="prefetch" as="image">`
hints — a low-priority "future navigation" directive browsers defer
to idle. Web-Vitals recorded LCP timings of 2.7-6.7s instead of the
sub-second range fonts already achieve via preload.

what:
- gp-furo-theme/base.html: switch logo_prefetch_links to
  `rel="preload"` + `fetchpriority="high"` on the three logo URLs.
  Block name kept for downstream override compatibility.
- gp-furo-theme/sidebar/brand.html: add width="200" height="200"
  decoding="async" fetchpriority="high" to the three img variants
  so the standalone template matches sphinx-gp-theme's overlay.
- sphinx-gp-theme/sidebar/brand.html: add fetchpriority="high" to
  the three img variants; width/height/decoding already present.
---
 .../src/gp_furo_theme/theme/gp-furo/base.html         | 11 ++++++++---
 .../gp_furo_theme/theme/gp-furo/sidebar/brand.html    | 10 +++++++---
 .../src/sphinx_gp_theme/theme/sidebar/brand.html      |  6 +++---
 3 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/base.html b/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/base.html
index b4bf8331..740fa671 100644
--- a/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/base.html
+++ b/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/base.html
@@ -33,13 +33,18 @@
         <link rel="canonical" href="{{ pageurl|e }}">
         {%- endif %}
 
+        {#- The sidebar logo is the LCP element on most consumer docs sites.
+            `rel="preload"` (not `prefetch`) plus `fetchpriority="high"`
+            promotes it from idle-queue to critical-path, dropping LCP from
+            several seconds to sub-second. Block name is preserved for
+            backwards compatibility with downstream template overrides. -#}
         {%- block logo_prefetch_links %}
         {%- if logo_url %}
-        <link rel="prefetch" href="{{ logo_url }}" as="image">
+        <link rel="preload" href="{{ logo_url }}" as="image" fetchpriority="high">
         {%- endif %}
         {%- if theme_light_logo and theme_dark_logo %}
-        <link rel="prefetch" href="{{ pathto('_static/' + theme_light_logo, 1) }}" as="image">
-        <link rel="prefetch" href="{{ pathto('_static/' + theme_dark_logo, 1) }}" as="image">
+        <link rel="preload" href="{{ pathto('_static/' + theme_light_logo, 1) }}" as="image" fetchpriority="high">
+        <link rel="preload" href="{{ pathto('_static/' + theme_dark_logo, 1) }}" as="image" fetchpriority="high">
         {%- endif %}
         {%- endblock logo_prefetch_links %}
     {%- endblock linktags %}
diff --git a/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/sidebar/brand.html b/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/sidebar/brand.html
index 6e494b5e..7a180d24 100644
--- a/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/sidebar/brand.html
+++ b/packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/sidebar/brand.html
@@ -15,15 +15,19 @@
 <a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
   {%- block brand_content %}
   {#- Remember to update the prefetch logic in `block logo_prefetch_links` in base.html #}
+  {#- width/height + decoding + fetchpriority let the browser reserve
+      the box before bytes arrive (CLS = 0) and treat the logo as a
+      critical-path resource (LCP wins). Mirrors sphinx-gp-theme's
+      sidebar/brand.html overlay. -#}
   {%- if logo_url %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo" src="{{ logo_url }}" alt="Logo"/>
+    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Logo"/>
   </div>
   {%- endif %}
   {%- if theme_light_logo and theme_dark_logo %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="Light Logo"/>
-    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="Dark Logo"/>
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Dark Logo"/>
   </div>
   {%- endif %}
   {% if not theme_sidebar_hide_name %}
diff --git a/packages/sphinx-gp-theme/src/sphinx_gp_theme/theme/sidebar/brand.html b/packages/sphinx-gp-theme/src/sphinx_gp_theme/theme/sidebar/brand.html
index 7fe241c0..5bca4f72 100644
--- a/packages/sphinx-gp-theme/src/sphinx_gp_theme/theme/sidebar/brand.html
+++ b/packages/sphinx-gp-theme/src/sphinx_gp_theme/theme/sidebar/brand.html
@@ -2,13 +2,13 @@
   {%- block brand_content %}
   {%- if logo_url %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" alt="Logo"/>
+    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Logo"/>
   </div>
   {%- endif %}
   {%- if theme_light_logo and theme_dark_logo %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" alt="Light Logo"/>
-    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" alt="Dark Logo"/>
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Dark Logo"/>
   </div>
   {%- endif %}
   {% if not theme_sidebar_hide_name %}

From abd3421b280014b011dbe549124a16dcda04af69 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 17 May 2026 16:08:27 -0500
Subject: [PATCH 2/4] gp-furo-theme(fix[sidebar-logo]) Reserve square box via
 aspect-ratio

why: Belt-and-suspenders for consumers using gp-furo-theme without
sphinx-gp-theme's overlay. The img element's `width="200" height="200"`
attrs handle CLS protection when present; this CSS rule covers theme
customisations that strip them.

what:
- sidebar.css: add `aspect-ratio: 1 / 1` to .sidebar-logo-container
  and `height: auto` to .sidebar-logo so the box reserves the
  square regardless of whether HTML attrs survive customisation.
---
 .../gp-furo-theme/web/src/styles/components/sidebar.css   | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/gp-furo-theme/web/src/styles/components/sidebar.css b/packages/gp-furo-theme/web/src/styles/components/sidebar.css
index bce346ba..5e575982 100644
--- a/packages/gp-furo-theme/web/src/styles/components/sidebar.css
+++ b/packages/gp-furo-theme/web/src/styles/components/sidebar.css
@@ -31,12 +31,20 @@
 
   .sidebar-logo-container {
     margin: var(--sidebar-item-spacing-vertical) 0;
+    /* Reserve a square box before the SVG bytes arrive. The img
+       carries width="200" height="200" attrs (CLS protection comes
+       from that primarily); this rule is belt-and-suspenders for
+       any consumer that loses the HTML attrs. Every shipped logo
+       (tmuxp.svg, libtmux.svg, libvcs.svg, cihai.svg) has a 1:1
+       viewBox. */
+    aspect-ratio: 1 / 1;
   }
 
   .sidebar-logo {
     margin: 0 auto;
     display: block;
     max-width: 100%;
+    height: auto;
   }
 
   /* Search input (sidebar-mounted) */

From 484085c666adc883447c55ce241b51f59b874b9c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 17 May 2026 16:08:35 -0500
Subject: [PATCH 3/4] docs(CHANGES) Add 0.0.1a20 sidebar logo LCP fix entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

why: Document the user-visible LCP regression fix shipping in
0.0.1a20 alongside the visual-identity ship that already landed
on trunk.

what:
- Lead paragraph for 0.0.1a20 explaining the prefetch→preload
  switch and its critical-path priority impact.
- ### Fixes section with "Sidebar logo loads as a critical-path
  resource" deliverable covering the link directive switch, img
  fetchpriority attr, and CSS aspect-ratio fallback.
- Reorder so Fixes precedes Documentation per the CHANGES
  subheading order convention.
---
 CHANGES | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/CHANGES b/CHANGES
index 24ddf56a..2a8cc013 100644
--- a/CHANGES
+++ b/CHANGES
@@ -18,6 +18,39 @@ $ uv add gp-sphinx --prerelease allow
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+gp-sphinx 0.0.1a20 closes a Largest-Contentful-Paint regression on
+the sidebar logo across every consumer docs site. Web-Vitals reports
+recorded LCP timings of 2.7 to 6.7 seconds because the bundled theme
+emitted a `<link rel="prefetch" as="image">` hint for the logo URLs
+instead of a `<link rel="preload" as="image" fetchpriority="high">`;
+the prefetch directive is reserved for future-navigation hints that
+browsers defer to idle. Switching the directive to `preload` plus
+`fetchpriority="high"` promotes the logo to the same critical-path
+priority the bundled fonts already use.
+
+### Fixes
+
+#### Sidebar logo loads as a critical-path resource
+
+Sidebar logos were the Largest Contentful Paint element on every
+consumer docs site with timings of 2.7 to 6.7 seconds. The
+`gp-furo-theme` template emitted `<link rel="prefetch">` hints for
+the logo URLs — a low-priority "future navigation" directive that
+browsers defer until idle — even though the logo sits above the
+fold on first paint. The fix switches the directive to
+`<link rel="preload" as="image" fetchpriority="high">`, mirroring
+the pattern already used for the bundled font preloads, and adds a
+matching `fetchpriority="high"` attribute to the `<img>` tag.
+
+Cumulative Layout Shift was already zero on these sites — the
+`<img>` carries `width="200" height="200"` so the browser reserves
+the 200×200 box before bytes arrive. As belt-and-suspenders for any
+consumer using `gp-furo-theme` standalone (without
+`sphinx-gp-theme`'s overlay), the `.sidebar-logo-container` CSS
+gains `aspect-ratio: 1 / 1` and `.sidebar-logo` gains
+`height: auto`, so the box reserves the same square regardless of
+whether the HTML attrs make it through theme customisations. (#40)
+
 ### Documentation
 
 #### Visual identity for the gp-sphinx docs site

From 5be1d0f8ed685d64c11dc4497b21b6e178f3c223 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 17 May 2026 16:23:52 -0500
Subject: [PATCH 4/4] fix(docs[sidebar/brand]) Sync local override with theme's
 fetchpriority attr

why: Sphinx _templates/ overrides win over installed theme templates,
so the gp-sphinx docs site itself would otherwise miss the LCP fix
landing on every consumer site through sphinx-gp-theme. Same bleed
pattern that #39's Rocket Loader sync addressed for sidebar/projects.

what:
- docs/_templates/sidebar/brand.html: add `fetchpriority="high"` to
  the three sidebar-logo img tags (single-logo + light/dark variants)
  so the override stays at parity with sphinx-gp-theme's bundled
  sidebar/brand.html.
---
 docs/_templates/sidebar/brand.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/_templates/sidebar/brand.html b/docs/_templates/sidebar/brand.html
index 7fe241c0..5bca4f72 100644
--- a/docs/_templates/sidebar/brand.html
+++ b/docs/_templates/sidebar/brand.html
@@ -2,13 +2,13 @@
   {%- block brand_content %}
   {%- if logo_url %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" alt="Logo"/>
+    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Logo"/>
   </div>
   {%- endif %}
   {%- if theme_light_logo and theme_dark_logo %}
   <div class="sidebar-logo-container">
-    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" alt="Light Logo"/>
-    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" alt="Dark Logo"/>
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" fetchpriority="high" alt="Dark Logo"/>
   </div>
   {%- endif %}
   {% if not theme_sidebar_hide_name %}