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.mdindex 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 values3. **IntersectionObserver intercept** - Disables Juice's scroll-spy which conflicts with our TOC styling4. **Logo preload** - Prevents flash when navigating between pages5. **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 breakpointsdiff --git a/docs/sass/custom.scss b/docs/sass/custom.scssindex 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.htmlindex 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 browsersvar isIOS = /iP(hone|ad|od)/.test(navigator.platform) ||