Skip to content

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

Document iOS viewport jank issue and current workaround

Maximilian Roos278a2f854eff
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index b8853b358..e7e3a482a 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -68,6 +68,28 @@ When either variable changes (including via media queries), all dependent values
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.
+
### Responsive breakpoints
Variables are overridden in media queries to maintain definitional correctness: