:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
/**
* Shared protocol between the headless replay player (HostBridge) and
* the rasterizer host (PlayerController).
*
* The player runs inside a Puppeteer-controlled browser and communicates
* with the rasterizer via:
* - A window global for config (rasterizer → player, injected before page load)
* - A DOM event to start playback (rasterizer → player)
* - An exposed function callback (player → rasterizer)
*
* This module defines the types, event names, and Window augmentation
* so both sides are compile-time checked against the same contract.
*/
// --- Constants ---
/** Height of the metadata footer. The rasterizer adds it to the capture viewport, so the recording keeps its full size. */
export const METADATA_FOOTER_HEIGHT_PX = 80
// --- Types ---
export interface ViewportEvent {
timestamp: number
width: number
height: number
}
export interface PlayerConfig {
teamId: number
sessionId: string
playbackSpeed: number
blockCount: number
skipInactivity?: boolean
startOffsetS?: number
endOffsetS?: number
mouseTail?: boolean
showMetadataFooter?: boolean
viewportEvents?: ViewportEvent[]
}
export interface PlayerError {
code: string
message: string
retryable: boolean
}
export interface InactivityPeriod {
ts_from_s: number
ts_to_s: number | null
active: boolean
}
export interface NavigationSample {
sample: number
/** Taken after any skip or tab switch, unlike the frame timeline, so it is the time the frame shows. */
session_ms: number
window_id: string
window_number: number
url: string
}
// --- Player → rasterizer messages ---
export type PlayerMessage =
| { type: 'loading_progress'; loaded: number; total: number }
| { type: 'started' }
| { type: 'ended' }
| { type: 'error'; code: string; message: string; retryable: boolean }
| { type: 'inactivity_periods'; periods: InactivityPeriod[] }
| { type: 'frame_timeline'; frameSessionMs: number[] }
export const PLAYER_EMIT_FN = '__posthog_player_emit__'
export const PLAYER_CONFIG_KEY = '__posthog_player_config__'
export const PLAYER_FRAME_TIMELINE_KEY = '__posthog_frame_timeline__'
export const PLAYER_NAVIGATION_KEY = '__posthog_navigation_timeline__'
// --- Event names (rasterizer → player) ---
export const PLAYER_START_EVENT = 'posthog-player-start'
// --- Block request API ---
//
// The in-browser data-loader fetches recording blocks via these paths
// (relative to the page origin). The rasterizer host intercepts them via
// Puppeteer request interception and proxies to the real recording-api,
// adding auth headers and implementation details (S3 keys, byte ranges,
// decompress flags) that the player doesn't need to know about.
/** GET /__blocks/:index → JSONL text */
export const BLOCK_REQUEST_PREFIX = '/__blocks/'
// --- Window augmentation ---
declare global {
interface Window {
// Config injected by rasterizer via evaluateOnNewDocument before page load
[PLAYER_CONFIG_KEY]?: PlayerConfig
// Player → rasterizer callback (installed by page.exposeFunction)
[PLAYER_EMIT_FN]?: (msg: PlayerMessage) => Promise<void>
}
}