Migrating from rrweb-based tools

Many replay tools are built on rrweb. Backstory’s Mirror engine is its own implementation with an rrweb-compatible import path, so most of what you know still applies.

Concepts that map directly

rrweb	Backstory
Full snapshot	Snapshot (checkpoint)
Incremental snapshot (mutation)	Mutation event
blockClass / maskTextClass	data-backstory-block / data-backstory-mask (selectors via privacy.blockSelector / maskSelector)
maskAllInputs	privacy.mode: "strict" (the default)
recordCanvas	canvas: { enabled, allowlist } with the visibility gate and quality ladder
checkoutEveryNms	recording.checkpointMinutes
Plugins for console/network	Built-in collectors (collectors.console, network.captureMeta)

What changes

• Recording runs in a Web Worker with a hard memory budget and a governor. There is no unbounded event array.
• Masking is capture-time only. There is no unmasked copy to un-mask later.
• Loss is explicit. When data is shed, the recording carries a gap marker and a new checkpoint. Replays never silently diverge.
• Sessions are visits and segments. No hard cap; 4-hour segments are stitched in the Player.
• Hidden canvases are never recorded. Only canvases attached, rendered, sized, near the viewport, on a visible page, and allowlisted.

Importing existing recordings

The Player accepts .backstorysession files. A converter for rrweb event arrays is available in the SDK package:

import { fromRrweb } from "@backstory/browser/import";
const session = fromRrweb(rrwebEvents, { url, userAgent });
// session is a protocol-v1 chunk list; upload with the API or open in the Player

Supported: full snapshots, mutation records, mouse and touch interactions, scroll, viewport, input, media, and custom events. Not converted: rrweb canvas plugin frames (re-record with the Backstory canvas ladder), and console/network plugin data outside the core event set.

Side-by-side period

You can run both SDKs during evaluation. Keep the combined recorder CPU under your budget by setting Backstory to conditional recording, which buffers healthy sessions without uploading them.