Skip to content

: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.

3.1 KB
Raw Blame
/**
 * 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>
    }
}