Migrate from WebView to WKWebView

[schuyler]

Overview

MacDown currently uses the deprecated WebView class for rendering the Markdown preview. This should be migrated to the modern WKWebView API.

Why This Is Important

1. WebView is Deprecated

• WebView was deprecated in macOS 10.14 (Mojave)
• Apple recommends migrating to WKWebView for all new development
• Future macOS versions may remove WebView support entirely

2. Technical Benefits

• Better performance: WKWebView uses a separate process for rendering
• Modern web standards: Better JavaScript, CSS, and HTML5 support
• Improved security: Better sandboxing and security features
• Proper cache control: No need for private API hacks
• Better rendering: More accurate rendering of modern web content

3. Fixes Multiple Issues

Migrating to WKWebView could potentially resolve:

• Issue Images do not update when changed on disk #110: Images not updating when changed on disk (proper cache control APIs)
• Issue Preview pane flickers when typing/updating #9: Preview flickering (better rendering architecture, already fixed but could prevent future issues)
• Better handling of JavaScript libraries (MathJax, Prism, etc.)

Current WebView Usage

Locations in the codebase:

• MPDocument.m: Main preview WebView instance
• MPMainController.m: Previously had WebCache disabling code (removed in PR Fix preview pane flickering by removing WebCache disabling #109)
• Various WebView delegate methods throughout the codebase

Migration Challenges

API Differences

WebView	WKWebView	Notes
loadHTMLString:baseURL:	loadHTMLString:baseURL:	Similar API
stringByEvaluatingJavaScriptFromString:	evaluateJavaScript:completionHandler:	Async in WKWebView
WebFrameLoadDelegate	WKNavigationDelegate	Different delegate pattern
mainFrame.DOMDocument	No direct DOM access	Need JavaScript bridge
Synchronous JS execution	Asynchronous JS execution	Requires code changes

Key Changes Required

1. Asynchronous JavaScript Execution

   • All stringByEvaluatingJavaScriptFromString: calls need to be converted to async
   • May require significant refactoring of code that depends on JS results

2. No Direct DOM Access

   • The commented-out DOM update code (lines 1072-1112 in MPDocument.m) uses DOMDocument
   • Would need to use JavaScript instead: document.documentElement.innerHTML = newHTML

3. Delegate Method Migration

   • Convert WebFrameLoadDelegate methods to WKNavigationDelegate
   • Update method signatures and behavior

4. Cache Control

   • Replace private WebCache API with WKWebsiteDataStore
   • Proper cache management for images

5. Testing

   • Thorough testing of all Markdown features
   • Verify JavaScript libraries work correctly (MathJax, Prism, Mermaid, etc.)
   • Test scroll position preservation
   • Verify all delegate callbacks work correctly

Implementation Plan

Phase 1: Research and Planning

• Audit all WebView usage in the codebase
• Document all WebView delegate methods used
• Identify all JavaScript execution points
• Research WKWebView cache management APIs
• Create migration design document

Phase 2: Core Migration

• Replace WebView with WKWebView in MPDocument
• Migrate delegate methods to WKNavigationDelegate
• Convert synchronous JS calls to async
• Implement proper cache control using WKWebsiteDataStore

Phase 3: JavaScript Library Integration

• Verify MathJax works correctly
• Verify Prism syntax highlighting works
• Verify Mermaid diagram rendering works
• Verify Graphviz/Viz rendering works
• Test task list functionality

Phase 4: Testing and Polish

• Test all Markdown features
• Test with large documents
• Verify scroll position preservation
• Test image loading and caching
• Performance testing
• Edge case testing

Phase 5: Image Cache Management

• Implement proper image cache invalidation (fixes Images do not update when changed on disk #110)
• Add manual refresh command if needed
• Test image update scenarios

Success Criteria

• ✅ All existing functionality works with WKWebView
• ✅ No performance regression
• ✅ Images update when changed on disk (issue Images do not update when changed on disk #110 fixed)
• ✅ No preview flickering (issue Preview pane flickers when typing/updating #9 remains fixed)
• ✅ All tests pass
• ✅ JavaScript libraries work correctly

Priority

Medium-High - Not urgent since WebView still works, but important for:

• Future-proofing the application
• Fixing issue Images do not update when changed on disk #110 properly
• Better user experience with modern web standards

Estimated Effort

Large - This is a significant refactoring:

• Multiple files affected
• Async/await pattern changes required
• Extensive testing needed
• Potential for subtle bugs

Estimate: 1-2 weeks of focused development + 1 week of testing

References

• WKWebView Documentation
• Migrating from WebView to WKWebView
• WKWebsiteDataStore Documentation
• Issue Preview pane flickers when typing/updating #9: Preview pane flickering
• Issue Images do not update when changed on disk #110: Images not updating when changed on disk
• PR Fix preview pane flickering by removing WebCache disabling #109: Removed WebCache disabling code

[schuyler]

A complete inventory of the legacy-WebKit surface now exists in plans/dependency-overhaul-survey.md §1 (branch claude/dependencies-overhaul-planning-hw3lms), with the decision register (…-decisions.md D-6/D-7/D-8) on top. The issue body's Phase 1 ("audit all WebView usage") is done — highlights that change the plan:

Scope is narrower than feared. Exactly one legacy WebView exists (MPDocument.m:227 + MPDocument.xib:430-439). macdown-cmd and MacDownCore have no WebKit, and MacDownQuickLook/PreviewViewController.m is already fully WKWebView — an in-repo reference for the delegate shape (MPPreviewViewControllerTests.m already tests it).

The hard cases are not the delegates — they're the synchronous reads (survey §1.9, ranked):

1. Scroll sync reads updateHeaderLocations.js return arrays synchronously via the mainframe JSContext (MPDocument.m:2908) on every scroll and render
2. Word count is a native DOM tree walk (MPDocument.m:3488 + the DOMNode+Text category, which ceases to exist under WKWebView; the pure-string MPTextCountForString path survives for selection counts)
3. Copy-as-HTML uses selectedDOMRange.markupString via the editing delegate (:1426) — WKWebView has neither
4. Divider tinting does a sync getComputedStyle read (:100-111)

Recommended architecture (D-6): one push-based message channel, designed once. Porting each site to nested evaluateJavaScript: completions invents races (e.g. scroll sync reading mid-DOM-replacement). Instead: a single WKScriptMessageHandler channel; injected JS pushes page state (header ys/kinds, word counts, body background) on mutation/idle; native caches and reads the cache synchronously — the scroll cluster consumes it exactly as today. MPMathJaxListener (windowScriptObject, :1303/:1679) folds into the same channel.

Prototype the resource loading first (D-7) — highest uncertainty. WKWebView restricts file:// subresources, and users reference out-of-tree images. A custom WKURLSchemeHandler is recommended because it replaces three mechanisms at once: the MathJax CDN-swap delegate (:1268-1281 — WKWebView has no per-resource hook anyway), the #110/#318 cache-busting (resourceTimestamps), and file-access policy (route through MPURLSecurityPolicy, which is pure Foundation and survives unchanged — CVE-2019-12138/12173 guards at :1406, :3564, :3589). This design depends on the sandbox stance — see #506, which should be decided first. Also re-evaluate whether previewSafeBaseURL: (:1758-1773, macOS 26 sentinel workaround) is still needed.

Decisions to make inside this milestone, not mid-flight (D-8): MathJax (see #509 — the 2.x CDN-swap and Hub.Queue machinery die here regardless; don't port them just to rewrite again); PDF export (deployment target is 11.0, so WKWebView.printOperationWithPrintInfo:/createPDF are available — porting the old frameView pipeline as-is preserves #504's broken links); private zoom API → public pageZoom (:2848, delete WebView+WebViewPrivateHeaders.h); copy-as-HTML becomes async.

One discipline note: do NOT fix the editor-side header-detection heuristic (#375) in this train — cmark-gfm sourcepos replaces it in v3000.1.1. Port the mechanism, not the heuristic.

Exit gates: parser golden corpus byte-identical (the parser didn't change); a new rendered-DOM smoke corpus green (post-Prism/tasklist DOM assertions — this milestone is where it's built, since it tests the new machinery); the 3 web-view-dependent test files converted off silent-skip (#476).

---

Generated by Claude Code