webblackbox

webblackbox

Browser-side lite capture SDK — record, export, and embed WebBlackbox sessions in any web app.

The browser-side lite capture SDK for WebBlackbox. Embed session recording directly in your web application — no Chrome extension required. Captures user interactions, console logs, network requests, DOM mutations, storage operations, screenshots, and more, then exports portable .webblackbox archives compatible with the full WebBlackbox Player.

Installation

npm install webblackbox

Quick Start

import { WebBlackboxLiteSdk } from "webblackbox/lite-sdk";

const sdk = new WebBlackboxLiteSdk({
  showIndicator: true,
  storage: "memory"
});

await sdk.start();

// ... user interacts with the page ...

const exported = await sdk.export({ stopCapture: true });
sdk.downloadArchive(exported);
await sdk.dispose();

What's Included

Export	Description
WebBlackboxLiteSdk	Main SDK class — start/stop/flush/export .webblackbox archives in-page
LiteCaptureAgent	Reusable capture agent for input, DOM/storage snapshots, screenshots, and injected bridge
installInjectedLiteCaptureHooks	Runtime hooks for console/network/storage/error interception
materializeLiteRawEvent	Shared lite raw-event materialization pipeline

Entry Points

import { WebBlackboxLiteSdk } from "webblackbox/lite-sdk";
import { LiteCaptureAgent } from "webblackbox/lite-capture-agent";
import { installInjectedLiteCaptureHooks } from "webblackbox/injected-hooks";
import { materializeLiteRawEvent } from "webblackbox/lite-materializer";

Optional IndexedDB Cache Encryption

When using storage: "indexeddb", you can provide pipelineStorageEncryptionKey to encrypt cached chunk/blob payload bytes at rest.

import { derivePipelineStorageKey } from "@webblackbox/pipeline";
import { WebBlackboxLiteSdk } from "webblackbox/lite-sdk";

const derived = await derivePipelineStorageKey("cache-passphrase");

const sdk = new WebBlackboxLiteSdk({
  storage: "indexeddb",
  pipelineStorageEncryptionKey: derived.key
});

Persist derived.salt + derived.iterations using your own key-management policy if you need to reopen the same encrypted cache.

Default Safety Tuning

WebBlackboxLiteSdk applies lite-focused runtime defaults to reduce long-session freezes and archive bloat:

Setting	Default	Why
freezeOnError	true	Capture uncaught JS exceptions/rejections
freezeOnNetworkFailure	false	Avoid noisy freezes from transient network issues
freezeOnLongTaskSpike	false	Avoid freezes from expected long tasks
mousemoveHz	14	Lower frequency than full mode (20 Hz)
scrollHz	10	Lower frequency than full mode (15 Hz)
domFlushMs	160	Longer flush interval than full mode (100 ms)
bodyCaptureMaxBytes	0	Disabled — keeps lite sessions page-thread friendly

Override any of these through options.config.

Export Policy Defaults

Setting	Default
includeScreenshots	true
maxArchiveBytes	100 MB
recentWindowMs	20 minutes

Extension Reuse

The Chrome extension (apps/extension) reuses this package in lite capture mode:

• Content script → webblackbox/lite-capture-agent
• Injected script → webblackbox/injected-hooks

This keeps capture logic centralized and shared across the SDK and extension lite mode.

Testing

# Unit & integration tests
pnpm --filter webblackbox test

# End-to-end full-chain verification (extension → export → player)
pnpm --filter @webblackbox/extension e2e:fullchain:lite
pnpm --filter @webblackbox/extension e2e:fullchain:lite:reload
pnpm --filter @webblackbox/extension e2e:fullchain:full

License

MIT