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, and opt-in screenshots, 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) | | screenshotIdleMs | 0 | Disabled unless explicitly enabled | | bodyCaptureMaxBytes | 0 | Disabled — keeps lite sessions page-thread friendly |

Override any of these through options.config.

Export Policy Defaults

| Setting | Default | | -------------------- | ---------- | | includeScreenshots | false | | 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