Why Google Docs looked blurry in my WKWebView (and the two-part fix)

Building Orbit for Mac, a native multi-account Gmail client, I hit a bug that only showed up in Google Docs and Sheets, never in Gmail. Here's what was actually going on.

A user emailed me on launch day: "Docs and Sheets look blurry, but Gmail is crisp." Same app, same window, same account. Gmail sharp, Docs fuzzy. That "only some pages" detail is the whole clue, so let me walk through why.

The setup

Orbit shows the real Google web apps inside WKWebView, one per account, each with its own WKWebsiteDataStore for session isolation. Gmail, Calendar, Drive, Docs, Sheets, all the same web content in the same kind of view. So a rendering bug that hits Docs but not Gmail can't be "WKWebView is blurry." Something is different about how Docs draws.

The clue: how each app renders text

Here's the thing I didn't appreciate until I dug in:

• Gmail draws text as DOM text. WebKit rasterizes real text on demand, so at any zoom level it re-renders crisply. Scale it, and it stays sharp.
• Docs and Sheets draw text onto a <canvas>. The document is painted as a bitmap. And a bitmap has a fixed resolution, the moment you display it at any non-integer scale, it gets resampled, and resampled bitmaps look soft.

So "blurry Docs" wasn't a text-rendering bug. It was a bitmap being drawn at a fractional zoom.

Where the fractional zoom came from

Two independent sources, which is why it was annoying to pin down:

1. A stray trackpad pinch. WKWebView has allowsMagnification. One accidental two-finger pinch sets magnification to something like 1.03, and now the canvas bitmap is being resampled forever. Invisible in Gmail (DOM text re-rasterizes), obvious in Docs.

2. Inherited zoom state from the pool. Orbit keeps a pool of webviews alive per account so switching accounts is instant (no reload, no re-login). But a pooled, reused view can carry over stale pageZoom from a previous session. Again: harmless for Gmail, visible in Docs.

The fix for this half was boring but necessary, pin both to 1.0 on creation so no canvas app ever inherits a fractional scale:

wv.pageZoom = 1.0
wv.magnification = 1.0

(And ⌘0 / resetZoom() as the manual escape hatch when someone does pinch.)

The other half: the User-Agent

Fixing zoom helped, but Docs still wasn't as sharp as Safari. The second lever was the User-Agent string.

Google serves different rendering paths depending on what browser it thinks it's talking to. For the Docs family specifically, presenting a proper Safari User-Agent gets you the rendering path Google actually tuned for Apple's WebKit, including how it handles the canvas on Retina displays, instead of a more generic fallback.

So Orbit sends a Docs-specific Safari UA only for the Docs/Sheets/Slides family, and a normal one everywhere else:

private static func userAgent(for service: GoogleService) -> String {
    return service.isDocsFamily ? docsSafariUserAgent : safeSafariUserAgent
}

Two services, two rendering realities: the same canvas that looked soft under the generic path renders crisp under the Safari path.

The takeaway

If you're embedding third-party web apps in WKWebView and some of them look blurry while others are fine, don't reach for a global "make it sharp" setting. Ask which pages render to <canvas> versus DOM. Canvas pages are bitmap pages, and bitmaps hate two things: fractional zoom and the wrong rendering path. Pin the zoom, match the User-Agent the site expects, and the fuzz goes away.

It took a user's one-line report ("Gmail is crisp, Docs isn't") to make the pattern obvious. That's been the theme of building Orbit in public: the bug reports are better than any test suite.