Session Replay: attach app-captured snapshots/images to a recording timeline

Summary

Allow products that already capture high-quality screenshots (e.g. WebGL/Cesium map views on user selection) to attach those images to an active Session Replay at a specific timestamp, so they appear in the replay player alongside DOM/canvas recording.

Problem

We build a 3D map product (Cesium / Google Photorealistic 3D Tiles). DOM-based Session Replay shows UI chrome but a blank/black map. Continuous canvas recording helps somewhat, but:

1. It’s low-FPS / lossy and expensive for large WebGL canvases
2. We already capture sharper, intentional snapshots at meaningful moments (point click, area selection, “what the user was looking at”)
3. There is no API to inject those snapshots into the recording stream — only separate analytics events

So the most useful visual evidence of user intent lives outside Session Replay.

Proposed API (sketch)

Something like:

posthog.captureReplaySnapshot({
  image: blobOrDataUrlOrHttpsUrl,
  timestamp?: number, // default: now
  label?: string,     // e.g. "P1 · focus region"
  properties?: Record<string, unknown>,
})

In the player: a marker on the timeline; clicking it shows the image (picture-in-picture or side panel), optionally linked to a normal analytics event.

Why not only custom events?

Events with image URLs work for debugging, but support/product folks live in the replay player. Having snapshots in the recording keeps one workflow: watch session → see exactly what was selected on the map at that moment.

Use case

Drone mission planning: user drops map pins / draws regions; we snapshot the camera view at selection time. We want those frames in PostHog Session Replay next to chat and clicks, correlated with our app session id.

Alternatives considered

• Canvas recording (captureCanvas) — useful background context, not precise enough for selection moments
• Custom events with image URLs — workable audit trail, but not in-player
• Temporarily injecting <img> into the DOM so rrweb records it — hacky / unreliable

Happy to beta-test or share more product context.

The issue names no repository files, tests, or entry points. Begin by locating the Session Replay capture and player implementation, plus the existing canvas-recording and custom-event paths; done means an agreed API can attach timestamped images and display them in the replay timeline.