Fix preview pane flickering by removing WebCache disabling#109
Merged
Fix preview pane flickering by removing WebCache disabling#109
Conversation
Comprehensive investigation covering: - Root cause: loadHTMLString destroys DOM causing 10-100ms flash - Failed approach 1: Dual-WebView double-buffering (4 commits) - Incompatible with WebKit's GPU compositor optimizations - Failed approach 2: Snapshot overlay (4 iterations, 7 bug fixes) - bitmapImageRepForCachingDisplayInRect cannot capture WebKit compositor layers - All fixes addressed overlay mechanics, but snapshot was grey/empty - Path forward: DOM updates with JavaScript re-initialization - Code already exists (lines 1091-1131, commented out) - Eliminates reload entirely, no flash possible This document preserves lessons learned from extensive debugging effort. Starting fresh branch to implement DOM update approach without broken code. Related to #9
Related to #9 The WebCache disabling code (using private API) was introduced to fix issue #747 (images not updating when changed on disk). However, disabling the cache forces WebKit to reload all resources on every preview update, including stylesheets and the base HTML document. This causes the preview pane to flash white/grey on every keystroke. This approach is based on PR #1288 from the original MacDown repository, which identified that the cache disabling is the root cause of the flickering issue affecting many users (77+ comments on issue #1104). Trade-off: - Fixes: Preview pane flickering during typing (high-impact UX issue) - Regresses: Images won't update when changed on disk (lower-impact issue) The flickering issue affects the core writing experience, while the image caching issue only affects specific workflows. This is an acceptable trade-off until migration to WKWebView can resolve both.
Contributor
Code Coverage ReportCurrent Coverage: 0.00% Coverage Details |
Related to #9 Comprehensive testing plan covering: - Core typing speed tests - Various content types (code, math, images, tables) - Document size variations - Window manipulation - Known regression verification (image caching) - Edge cases and stress tests Created by Zeppo for thorough validation of the fix.
This was referenced Nov 19, 2025
Related to #9 Updated investigation plan to document: - Successful fix: Removed WebCache disabling code (commit d54c20a) - Root cause: WebCache disabling forced resource reloads on every keystroke - Trade-off analysis: Fixed flickering, regressed image caching (#110) - Complete investigation history preserved as reference - Added lessons learned about code removal vs. complexity The document now serves as a comprehensive historical record showing the investigation journey from complex failed approaches to the simple successful solution.
Related to #9 Organized test documentation with other planning documents.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the preview pane flickering issue by removing the WebCache disabling code that was forcing WebKit to reload all resources on every keystroke.
Problem
The preview pane was flickering grey/white on every keystroke when typing in the editor. This severely impacted the user experience and made the application difficult to use for extended writing sessions.
Root Cause
Code in
MPMainController.m(lines 105-119) was using private API to disable WebView's cache. This was originally added to fix issue #747 (images not updating when changed on disk), but it caused WebKit to reload ALL resources (stylesheets, HTML, JavaScript) on every preview update, resulting in visible flickering.Solution
Removed the WebCache disabling code (15 lines deleted from
MPMainController.m).Technical Approach
This fix is based on PR #1288 from the original MacDown repository, which identified the cache disabling as the root cause of flickering affecting 77+ users in issues #1104 and #1057.
Testing
Trade-off
Fixes:
Regresses:
The flickering affects the core writing experience and occurs constantly during normal use. The image caching issue only affects users who modify external images on disk while editing. This is an acceptable trade-off that prioritizes the everyday user experience.
Future Work
Both issues can be properly resolved by migrating from deprecated WebView to modern WKWebView, which has proper cache control APIs.
Related Issues
Related to #9
Files Changed
MacDown/Code/Application/MPMainController.m: Removed WebCache disabling code (lines 105-119)Review Notes