Skip to content

Screenshot replay: capture a window that is one full-screen web view with WKWebView.takeSnapshot #1029

Open

Description

@Jaltaire

Problem Statement

Some apps' entire UI is one full-screen WKWebView: hybrid apps, and apps that render in WebGL inside a web view. In screenshot mode, every capture runs drawHierarchy on the key window on the main thread. For a window that is just a web view, that means the render server draws the web view again and UIKit copies the result into a bitmap while the main thread waits, and anything animating in the page stalls for that long.

What WebKit offers

WebKit already has an API for this: WKWebView.takeSnapshot(with:completionHandler:). With afterScreenUpdates = true, WebKit waits for the web view's next presentation update and has the render server draw the web view into an sRGB IOSurface. The call returns at once, the image arrives in a completion handler, and it can be read while it is encoded, off the main thread.

Measurements

Setup.

  • App. PostHogExample on current main (29d7d86), Release, on an iPhone Air simulator (iOS 27.0, 420×912 pt at 3x).
  • Local patch, not committed.
    • The root view is one full-screen, opaque WKWebView playing a WebGL shader.
    • Screenshot replay runs against a local mock server, with maskAllTextInputs and maskAllImages off.
    • A 1 s timer asks the key window for a layout pass, so replay captures about once a second.
    • A CADisplayLink on the main thread counts missed frames.
Main-thread render per capture Frames dropped per second Frames kept per second
main (drawHierarchy), 3 runs of 60 s 37–39 ms median 2.19–2.36 ~1
WKWebView.takeSnapshot (proposed), the 11 clean runs of 60–90 s call returns at once; WebKit renders later on main 0.07–0.19 ~1

Uploads are 420×912 in both cases. In my separate color-space PR (#1028), drawHierarchy drops to about 22 ms and 1 frame per capture on this setup, so the snapshot path would still save most of a frame per capture.

Caveats.

  • Where the cost goes. WebKit's snapshot isn't free on the main thread. With afterScreenUpdates, WebKit runs [CATransaction synchronize] and CARenderServerSnapshot synchronously on main, in a block it dispatches after the next commit (WKWebView.mm, WKWebViewIOS.mm). It just costs much less than drawHierarchy here.
  • Two failures in 13 runs with the snapshot path. They were the 1st and 5th runs. Neither happened in 13 drawHierarchy runs, and the 8 snapshot runs after the second were clean. A watchdog that samples the app when it stalls caught nothing in the later runs, so I have no stack for either, and both were on a simulator.
    • In one run, the app went silent for the last 17 s of the run, until the host terminated it. There were no display-link ticks or timer fires (both on the main thread) and no network activity, while the simulator's other processes carried on.
    • In another, WebKit never completed a single snapshot, although the page had loaded. Every capture hit the 5 s timeout, so that session recorded nothing.
    • These are part of why I'd keep this opt-in and experimental. A drawn fallback after a timeout is an open question for the implementation.

Solution Brainstorm

Proposed API

An opt-in, experimental flag on PostHogSessionReplayConfig, next to screenshotModeBackgroundCapture:

/// Capture a window that shows nothing but one web view with WebKit's own snapshot of that web view,
/// when `screenshotMode` is enabled.
///
/// Experimental.
/// Default: false
@objc public var screenshotModeWebViewSnapshot: Bool = false

Behaviour when it's on:

  • Which windows. It applies only when the window's frontmost visible view is one WKWebView that covers the window exactly (within half a pixel), paints opaquely (isOpaque, or an opaque background color), and isn't faded, masked, or clipped by itself or any ancestor. Any other window is drawn exactly as today. That includes a window with an alert, a toast, or any native view in front of the web view.
  • Masking. Mask rects are collected exactly as for a drawn window and painted onto the snapshot on the replay queue. With maskAllTextInputs or maskAllImages on, today's rule still masks the whole web view.
  • In-flight gate. The gate stays held until WebKit hands over the image, so captures that arrive in the meantime are skipped, not queued.
  • Timeout. WebKit never completes a snapshot it deferred until an animated resize ends if the web view goes away first. The capture is therefore given up after 5 s, and a late image is dropped.
  • Paths it leaves alone. It has no effect with screenshotModeBackgroundCapture, or on a bridge episode's first frame.

Alternatives considered

  • Turn it on by default for eligible windows. That needs no API, but it changes how many hybrid apps are captured, so opt-in seemed the safer first step. Tell me if you'd rather have it on by default.
  • Fix the cost inside drawHierarchy. Part of the cost is a color conversion, which a separate PR addresses without new API (perf(replay): draw screenshots in the screen's color space and convert off the main thread #1028). The render server's redraw of the window remains, and for a web view WebKit's own snapshot avoids it.

Implementation

A complete implementation with tests (eligibility rules, the snapshotter's timeout and exactly-once delivery, and an integration suite through captureBridgeSnapshot) is on Jaltaire:feat/replay-web-view-snapshot. Following CONTRIBUTING, I'll open the PR once we've agreed on the API shape here. I'm happy to rename the option, fold it into another one, or drop the flag.


This issue was drafted with Claude Code (Claude Opus 5.5), directed by @Jaltaire.

Activity

  1. posthog commented on Nov 5, 2026

    @posthog
    Contributor

    PostHog self-driving picked up this issue and researched it. Somebody may already be working on it, so ask before you start a fix.

    Report (team access only): https://us.posthog.com/project/2/inbox/reports/01a1a92b-e0b3-73c8-bd21-65b1367e825d?link_source=github_comment

  2. Jaltaire commented on Nov 5, 2026

    @Jaltaire
    ContributorAuthor

    An update on the snapshot path, after chasing the two failed runs in the issue. In short: afterScreenUpdates = true was the wrong choice. It gives WebKit several ways to hold the main thread or never answer, and the timeout couldn't cover them. Asking for afterScreenUpdates = false, and drawing the window whenever WebKit can't answer during the call, removes every wait. That's what the branch should become.

    What afterScreenUpdates = true waits on

    Reading -[WKWebView takeSnapshotWithConfiguration:completionHandler:] (WKWebView.mm) and _snapshotRectAfterScreenUpdates: (WKWebViewIOS.mm) on WebKit's main branch:

    1. WebPageProxy::callAfterNextPresentationUpdate sends DrawingArea::DispatchAfterEnsuringDrawing to the web process. The web process adds the callback to its next layer tree commit and schedules a rendering update. While its rendering is suspended (m_isRenderingSuspended, a frozen layer tree), or while it waits for the UI process to display its last commit, that commit doesn't come, and neither does the snapshot.
    2. On that commit, WebKit opens an implicit CATransaction and adds a commit handler. The handler dispatches a block to the main queue.
    3. That block calls _snapshotRectAfterScreenUpdates:YES. During a live or animated resize, this parks the request in _callbacksDeferredDuringResize (retaining the web view) until the resize ends. Otherwise it runs [CATransaction synchronize] and then CARenderServerSnapshot, both synchronously on the main thread.

    The 5 s timeout I proposed is a main-queue asyncAfter. It can't fire while the main thread sits in step 3, and in steps 1 and 2 it only releases our in-flight gate. The next capture asks again, so a page whose presentation update never comes queues one request every timeout and records nothing. That's the run where no snapshot ever completed.

    What afterScreenUpdates = false does

    takeSnapshotWithConfiguration: calls _snapshotRectAfterScreenUpdates:NO at once. For a web view in a window on a screen, that's CARenderServerSnapshot into an sRGB IOSurface, and the completion handler runs before takeSnapshot returns. There's no presentation update, no commit handler, and no synchronize. The only other paths are the resize deferral above, and a software snapshot through the web process for a web view outside a window, both of which answer later.

    So the snapshotter now:

    • asks with afterScreenUpdates = false;
    • uses the image only if it arrives during the call;
    • otherwise draws the window exactly as main does;
    • never asks WebKit again while an earlier request is unanswered, and stops waiting once that web view is gone.

    Nothing waits on the main thread, so the timer and the timeout are gone. The cost is the synchronous render-server snapshot, the same kind of call drawHierarchy already makes, without the bitmap copy and colour conversion.

    Measurements

    These are from an app whose whole interface is one WKWebView playing a WebGL scene, with one capture a second: an iPhone Air simulator on iOS 27.0, and an iPhone 15 Pro Max on iOS 27.2 running a release build.

    • afterScreenUpdates = true (the branch as it stands), three sessions of 7–8 minutes on the simulator. Each one played, went to the background and back, rotated, and reopened screens. All 1,231 snapshots arrived, but none during the call, typically 36–40 ms later. Every rotation stopped the main thread for 259–359 ms, ending within 50 ms of a snapshot that took 507–560 ms (23 such stalls). Neither of the issue's failures came back in these runs, but this is the same wait, smaller.
    • afterScreenUpdates = false with the drawn fallback, on the simulator. Every one of 562 snapshots arrived during the call, so none had to be drawn. The call held the main thread for 8–11 ms at the median and 13–15 ms at p90, and rotation stalled nothing, the same as with replay off. On the simulator, each capture still costs about one display frame, which is the render server's floor there.
    • On the Pro Max, with the release build and false, two 25 s recordings with replay on had no frame gap over 33 ms. The worst gap within 50 ms of a capture had a median of 16.7 ms, a single frame at 60 fps. The same capture times laid over two replay-off recordings gave 25 ms.

    What I'd change in the proposal

    • Behaviour. Same option and eligibility rules, but no timeout and no asynchronous delivery. A window whose web view doesn't answer during the capture is drawn, so every capture still records a frame.
    • The failures in the issue. I couldn't catch a stack for the 17 s freeze, so I can't say which of the waits in step 3 it was. The fixed path makes none of them, though.

    I'll update the branch to this before opening the PR, unless you'd rather keep afterScreenUpdates and add a drawn fallback after a timeout instead.


    This comment was drafted with Claude Code (Claude Opus 5.5), directed by @Jaltaire.

  3. ioannisj commented on Nov 5, 2026

    @ioannisj
    Contributor

    Thank you @Jaltaire for all the context here! will have a look and consider soon

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions