Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Move iOS jank documentation to code comments

Maximilian Roos8d830ebdde41
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index e7e3a482a..a327bae24 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -66,29 +66,7 @@ When either variable changes (including via media queries), all dependent values
3. **IntersectionObserver intercept** - Disables Juice's scroll-spy which conflicts with our TOC styling
4. **Logo preload** - Prevents flash when navigating between pages
5. **WCAG AA colors** - `--wt-color-text-soft` is #78716a for 4.5:1 contrast
-6. **iOS viewport polyfill** - Sets stable `--vh-full` variable for Firefox iOS and Chrome iOS
-
-### iOS mobile viewport jank (known issue)
-
-**Problem**: On Firefox iOS and Chrome iOS, scrolling causes the browser chrome (URL bar) to appear/disappear, which triggers viewport height changes. The modern CSS viewport units (`svh`, `lvh`) that should handle this are broken on these browsers - they behave like `dvh` (dynamic), causing visible "jank" where the hero section resizes during scroll.
-
-**Root cause**: Firefox iOS and Chrome iOS use WKWebView but haven't implemented the `minimumViewportInset`/`maximumViewportInset` WebKit APIs that make `svh`/`lvh` work correctly. See: https://github.com/mozilla-mobile/firefox-ios/issues/11574
-
-**Current workaround** (in `templates/base.html` and `sass/custom.scss`):
-1. JS captures `window.innerHeight` once on page load and sets `--vh-full` CSS variable
-2. JS only runs on iOS browsers (detected via user agent)
-3. JS only updates on `orientationchange`, never on scroll/resize
-4. CSS uses `var(--vh-full, 100lvh)` - iOS gets the stable JS value, other browsers get `lvh`
-
-**What we tried that didn't work**:
-- Pure `100lvh` without JS - janks on Firefox iOS (lvh is broken there too)
-- `-webkit-fill-available` in `@supports` block - either didn't help or was overridden by media queries
-- JS that updates on `resize`/`visualViewport.resize` - made jank WORSE by actively tracking the dynamic viewport
-- Complex polyfills with multiple height candidates - added complexity without benefit
-
-**What we'd prefer**: A simpler CSS-only solution. The current JS workaround is fragile and adds complexity. If a future browser update fixes `lvh` on Firefox iOS, or if a better CSS approach emerges, we should simplify.
-
-**Testing**: Safari iOS doesn't have this issue (its browser chrome doesn't appear/disappear on scroll the same way). Chrome iOS has the appearing chrome but our fix handles it. Firefox iOS is the most problematic.
+6. **iOS viewport polyfill** - Sets stable `--vh-full` variable for Firefox iOS/Chrome iOS (see `templates/base.html` for details on the jank issue and what we tried)
### Responsive breakpoints
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index 3fdbc8c07..e8bca7541 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -21,8 +21,8 @@ body {
line-height: 1.5;
color: var(--wt-color-text);
background-color: var(--wt-color-bg);
- // Override Juice theme's min-height: 100vh. Use lvh (large viewport height)
- // which is stable on Firefox iOS, unlike svh which behaves like dvh.
+ // iOS viewport jank fix: --vh-full is set by JS in base.html for iOS browsers.
+ // Fallback to 100lvh for other browsers. See base.html for full explanation.
min-height: var(--vh-full, 100lvh);
}
@@ -520,7 +520,7 @@ table {
border: 1px solid var(--wt-color-border-subtle);
border-top: 3px solid var(--wt-color-accent);
padding: 0.75rem 0 1rem;
- // Use lvh which is stable on Firefox iOS (svh behaves like dvh there)
+ // iOS jank fix: --vh-full set by JS, fallback to lvh. See base.html.
max-height: calc(var(--vh-full, 100lvh) - var(--wt-header-height) - var(--wt-main-padding-top) - 20px);
overflow-y: auto;
overscroll-behavior: contain; // Trap scroll events within TOC
@@ -660,9 +660,7 @@ footer {
background: radial-gradient(ellipse 80% 60% at 70% 40%, rgba(254, 243, 199, 0.7) 0%, transparent 60%),
radial-gradient(ellipse 50% 40% at 30% 70%, rgba(251, 243, 219, 0.5) 0%, transparent 50%),
var(--wt-color-bg-soft) !important;
- // Use lvh (large viewport height) which is stable on Firefox iOS.
- // Firefox iOS incorrectly implements svh as dvh, causing scroll jank.
- // See: https://github.com/mozilla-mobile/firefox-ios/issues/11574
+ // iOS jank fix: --vh-full set by JS, fallback to lvh. See base.html.
height: calc(var(--vh-full, 100lvh) - var(--wt-header-height) - env(safe-area-inset-top, 0px)) !important;
max-height: calc(var(--vh-full, 100lvh) - var(--wt-header-height) - env(safe-area-inset-top, 0px)) !important;
padding: 4rem 40px 3rem;
@@ -680,7 +678,7 @@ footer {
}
.hero-image {
- // Use lvh which is stable on Firefox iOS (svh behaves like dvh there)
+ // iOS jank fix: --vh-full set by JS, fallback to lvh. See base.html.
max-height: calc(var(--vh-full, 100lvh) * 0.55);
width: auto;
aspect-ratio: 1;
@@ -878,7 +876,7 @@ ul > li::marker {
top: calc(var(--wt-header-height) + env(safe-area-inset-top, 0px));
left: 0;
width: min(260px, 70vw);
- // Use lvh which is stable on Firefox iOS (svh behaves like dvh there)
+ // iOS jank fix: --vh-full set by JS, fallback to lvh. See base.html.
height: calc(var(--vh-full, 100lvh) - var(--wt-header-height) - env(safe-area-inset-top, 0px));
background: var(--wt-color-bg-elevated);
border-right: 1px solid var(--wt-color-border-subtle);
@@ -1010,8 +1008,7 @@ body.mobile-menu-open {
}
.hero {
- // Use lvh (large viewport height) which should be stable on Firefox iOS
- // unlike svh which incorrectly behaves like dvh
+ // iOS jank fix: --vh-full set by JS, fallback to lvh. See base.html.
height: calc(var(--vh-full, 100lvh) - var(--wt-header-height) - env(safe-area-inset-top, 0px));
padding: 2rem 20px;
flex-direction: column;
diff --git a/docs/templates/base.html b/docs/templates/base.html
index 0944b74db..b43349554 100644
--- a/docs/templates/base.html
+++ b/docs/templates/base.html
@@ -16,11 +16,20 @@
{# _variables.html is already included by the theme at line 12 of juice/templates/index.html #}
{# Zola resolves it to our custom templates/_variables.html, so no need to include it again #}
<script>
-// iOS viewport height fix: Capture a STABLE height once on page load.
-// Do NOT update on resize/scroll - that's what causes the jank!
-// On Firefox iOS and Chrome iOS, svh/lvh behave like dvh due to missing
-// minimumViewportInset/maximumViewportInset WebKit APIs.
-// See: https://github.com/mozilla-mobile/firefox-ios/issues/11574
+// iOS viewport jank fix: Firefox/Chrome iOS have broken svh/lvh units that
+// behave like dvh, causing the hero to resize when browser chrome appears.
+// Root cause: Missing WebKit minimumViewportInset/maximumViewportInset APIs.
+// https://github.com/mozilla-mobile/firefox-ios/issues/11574
+//
+// Solution: Capture height ONCE on load, set --vh-full CSS variable.
+// CSS uses var(--vh-full, 100lvh) so iOS gets stable pixels, others get lvh.
+//
+// What didn't work:
+// - Pure 100lvh: janks on Firefox iOS (lvh broken too)
+// - -webkit-fill-available: overridden by media queries / didn't help
+// - Updating on resize/visualViewport events: made jank WORSE
+//
+// TODO: Simplify if Firefox iOS ever fixes their WebKit wrapper.
(function() {
// Only run on iOS WebKit browsers
var isIOS = /iP(hone|ad|od)/.test(navigator.platform) ||