chore!: remove experimental screenshotModeBackgroundCapture

[turnipdabeets]

Stacked on #873 (iOS 4.0).

💡 Motivation and Context

PostHogSessionReplayConfig.screenshotModeBackgroundCapture was added in #594 as an opt-in workaround. It rendered replay screenshots off the main thread because drawHierarchy on main was too slow to keep up. UIKit documents drawHierarchy as main-thread-only, so the flag shipped as experimental, with Main Thread Checker warnings and a possible freeze on the first capture. It also needed its own capture path: sample the masks, render off-main, sample again, then mask the union of both samples (#786).

The main-thread cost it worked around has since been dealt with, so we don't need the flag in 4.0:

• fix: improve session replay screenshot performance #578 by @ioannisj replaced UIGraphicsImageRenderer with a lightweight CoreGraphics renderer. That cut main-thread screenshot cost by about 92% on an iPhone XR (about 135 ms to about 11 ms per snapshot).
• feat: experimental GPU screenshot capture and screenshotScale for session replay #911 by @ioannisj (open, experimental) goes further: GPU capture that stays on the main thread but splits the work into slices short enough to fit inside a frame (longest slice 67.9 ms → 5.4 ms on an iPhone 17 Pro).
• chore!: iOS Major Release 4.0 #873 removed wireframe capture, so masked screenshots are now the only replay mode. That leaves the main-thread settle-then-shoot path as the capture path every app uses, and this flag as the only way to opt out of it. The wireframe changeset had a bullet saying this flag "now applies without setting screenshotMode". This PR drops that bullet.

Changes

• Remove the public screenshotModeBackgroundCapture property and its branch in snapshot(), so every capture goes through scheduleSettledCapture.
• Remove performBracketedBackgroundCapture and the sweptRects helper, which only it used, plus the 8 sweptRects tests and their test-audit rows.
• Update stale comments that referred to background capture, and the public API snapshot.
• Add a major changeset.

💚 How did you test it?

• make testOniOSSimulator: 1527 tests passed.
• make test (macOS): 1124 tests ran. 2 app-group storage tests failed with a group-container permission error (NSCocoaErrorDomain 513). They fail the same way on the base branch, so they're specific to this machine and unrelated to this change.
• make buildSdk: iOS, macOS, Mac Catalyst, tvOS, watchOS, visionOS and SPM (with and without traits) all built.
• swiftlint and swiftformat --lint on the changed files: no new findings.
• make apiCheck: the only change from this PR is the removed screenshotModeBackgroundCapture line. The check still fails, because the base branch's snapshot is missing the @Sendable closure signatures from the sendable-callbacks change. That needs a scripts/check-public-api.sh --update on chore!: iOS Major Release 4.0 #873.

Follow-ups outside this repo

• posthog-react-native-session-replay sets this flag in ios/PosthogReactNativeSessionReplay.swift from posthog-js's screenshotModeBackgroundCapture option. It pins posthog-ios ~> 3.x today, so nothing breaks yet, but that line has to go when it moves to 4.0.
• posthog.com docs mention the flag in session-replay/_snippets/ios-installation.mdx and session-replay/installation/react-native.mdx. They suggest it for jank on 120 Hz iPhones, so the docs need updating when 4.0 ships.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Claude Opus 5.5) wrote the removal and ran the validation. No tests were added because this only removes code. The 8 deleted tests covered sweptRects, which nothing calls after the background path is gone. I kept the defensive main-thread hop in UIView.toImage and only updated its comment, to keep the change small. The 2 macOS storage failures and the API snapshot drift were checked against the base branch before they were attributed to it.

🤖 Generated with Claude Code

[github-actions]

posthog-ios Compliance Report

Date: 2026-10-09 23:06:39 UTC
Duration: 221013ms

⚠️ Some Tests Failed

44/45 tests passed, 1 failed

---

Capture Tests

⚠️ 28/29 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	3326ms
Format Validation.Event Has Uuid	✅	2873ms
Format Validation.Event Has Lib Properties	✅	2760ms
Format Validation.Distinct Id Is String	✅	2826ms
Format Validation.Token Is Present	✅	2938ms
Format Validation.Custom Properties Preserved	✅	2982ms
Format Validation.Event Has Timestamp	✅	2997ms
Retry Behavior.Retries On 503	✅	11836ms
Retry Behavior.Does Not Retry On 400	✅	4908ms
Retry Behavior.Does Not Retry On 401	✅	4756ms
Retry Behavior.Respects Retry After Header	✅	7815ms
Retry Behavior.Implements Backoff	✅	21683ms
Retry Behavior.Retries On 500	✅	9393ms
Retry Behavior.Retries On 502	✅	9267ms
Retry Behavior.Retries On 504	✅	9350ms
Retry Behavior.Max Retries Respected	❌	19213ms
Deduplication.Generates Unique Uuids	✅	3144ms
Deduplication.Preserves Uuid On Retry	✅	5520ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10441ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7907ms
Deduplication.No Duplicate Events In Batch	✅	2989ms
Deduplication.Different Events Have Different Uuids	✅	2974ms
Compression.Sends Gzip When Enabled	✅	2797ms
Batch Format.Uses Proper Batch Structure	✅	2833ms
Batch Format.Flush With No Events Sends Nothing	✅	269ms
Batch Format.Multiple Events Batched Together	✅	2862ms
Error Handling.Does Not Retry On 403	✅	4804ms
Error Handling.Does Not Retry On 413	✅	2351ms
Error Handling.Retries On 408	✅	9120ms

Failures

retry_behavior.max_retries_respected

Expected 4 requests, got 6

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	2831ms
Request Payload.Flags Request Uses V2 Query Param	✅	2831ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	2737ms
Request Payload.Flags Request Omits Authorization Header	✅	2722ms
Request Payload.Token In Flags Body Matches Init	✅	2991ms
Request Payload.Groups Round Trip	✅	2745ms
Request Payload.Groups Default To Empty Object	✅	2877ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	3001ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	2829ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	2730ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	2848ms
Request Lifecycle.No Flags Request On Init Alone	✅	129ms
Request Lifecycle.No Flags Request On Normal Capture	✅	466ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	5623ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	2800ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	3163ms