@absolutejs/replay 0.0.1

package/LICENSE

@@ -0,0 +1,94 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/replay (https://github.com/absolutejs/replay)
+
+**Change Date:** June 24, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed error-tracking, exception-monitoring, crash-reporting, session-replay,
+   or real-user-monitoring (RUM) service that competes with hosted observability
+   offerings (including, but not limited to, Sentry, Datadog, LogRocket, Bugsnag,
+   Rollbar, Honeybadger, Airbrake, Raygun, TrackJS, AppSignal, New Relic Browser,
+   FullStory, Highlight, or any similar hosted offering whose primary value to its
+   users is capturing client-side errors, breadcrumbs, or sessions from end-user
+   browsers). This includes any product whose primary value to its users is the
+   functionality the Licensed Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/replay).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to capture errors from your own applications,
+  websites, internal tools, or SaaS products (whether commercial or non-
+  commercial), so long as the Licensed Work itself is not the primary product
+  you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing hosted observability
+  service of the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -0,0 +1,90 @@
+# @absolutejs/replay
+
+> Session replay for the AbsoluteJS observability stack. ~1 KB of glue;
+> [rrweb](https://github.com/rrweb-io/rrweb) is an optional, lazy-loaded peer.
+
+Records DOM sessions, chunks them, and uploads each chunk via a pluggable
+transport (wire [`@absolutejs/blob`](https://www.npmjs.com/package/@absolutejs/blob)).
+Exposes a `replayId` so [`@absolutejs/beacon`](https://www.npmjs.com/package/@absolutejs/beacon)
+can stamp every error with the session — cross-linking an issue to the **exact**
+DOM replay around it. Re-assembles chunks for a framework-agnostic player.
+
+## Design
+
+- **Zero hard dependencies.** DOM recording genuinely needs a heavy engine, so
+  the recorder wraps rrweb — but rrweb is an **optional peer**, lazy-imported
+  only when you start recording (and fully injectable). Replay is the one heavy
+  feature; its weight never lands on a page that isn't recording.
+- **Plain TS, not Effect** — like `beacon`, it's browser-first where bytes are
+  the cost. Replay's own code is ~1 KB gz.
+- **Private by default** — inputs are masked (`maskAllInputs: true`). Recording
+  user sessions is a real liability surface; keep masking on.
+
+## Install
+
+```sh
+bun add @absolutejs/replay rrweb
+```
+
+## Record
+
+```ts
+import { createRecorder } from "@absolutejs/replay";
+import { initBeacon } from "@absolutejs/beacon";
+
+const recorder = createRecorder({
+  project: "web",
+  release: import.meta.env.VITE_RELEASE,
+  upload: (chunk) =>
+    uploadToBlob(
+      `replays/${chunk.replayId}/${chunk.seq}.json`,
+      JSON.stringify(chunk),
+    ),
+  // privacy defaults: maskAllInputs: true, blockClass: 'rr-block', maskTextClass: 'rr-mask'
+});
+
+// Cross-link errors → this session:
+initBeacon({ project: "web", getReplayId: () => recorder.replayId });
+
+// On error, flush the tail so the replay around it is stored:
+window.addEventListener("error", () => void recorder.flush());
+```
+
+Add `class="rr-block"` to a node to skip recording it, or `class="rr-mask"` to
+mask its text. Use `maskAllText: true` for high-sensitivity apps.
+
+## Play back
+
+```ts
+import { assembleReplay, createReplayPlayer } from "@absolutejs/replay";
+
+const chunks = await loadChunksFromBlob(replayId); // your storage read
+const player = await createReplayPlayer({
+  target: document.getElementById("replay")!,
+  events: assembleReplay(chunks), // ordered + flattened
+});
+player.pause();
+player.play(0);
+```
+
+## API
+
+```ts
+createRecorder(options) => Recorder
+//   Recorder: { replayId, manifest(), flush(), stop() }
+//   options:  project, upload, release?, environment?, replayId?,
+//             chunkIntervalMs? (5000), chunkMaxEvents? (200),
+//             maskAllInputs? (true), maskAllText? (false), blockClass?, maskTextClass?,
+//             recordCanvas?, record? (inject rrweb), onError?
+
+assembleReplay(chunks) => ReplayEvent[]              // sort by seq, flatten
+createReplayPlayer({ target, events, Replayer?, autoplay?, speed? }) => Promise<ReplayPlayer>
+```
+
+SSR-safe: imported without a DOM, `createRecorder` returns a no-op handle (with
+a valid `replayId`/`manifest`).
+
+## License
+
+BSL-1.1 with a named carveout against hosted session-replay / observability
+SaaS (LogRocket, FullStory, Sentry Replay, Datadog). See `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @absolutejs/replay — session replay for the AbsoluteJS observability stack.
+ *
+ * DOM recording genuinely needs a heavy, hard-to-replicate engine, so the
+ * recorder wraps **rrweb** — but rrweb is an **optional, lazy-loaded peer**
+ * (and fully injectable), so:
+ *   - this package has ZERO hard dependencies; rrweb is only pulled when you
+ *     actually start recording, and only into the replay code path (opt-in
+ *     weight — replay is the one heavy feature, never on a page that isn't
+ *     recording).
+ *   - it's plain TS, NOT Effect — like @absolutejs/beacon, it's browser-first
+ *     where bytes are the cost; the server-side rigor lives in the ingest /
+ *     storage layers.
+ *
+ * Pipeline: rrweb emits events → buffered → chunked (by size/interval) →
+ * uploaded via a pluggable `upload` transport (wire `@absolutejs/blob`). A
+ * `replayId` is exposed synchronously so `@absolutejs/beacon`'s `getReplayId`
+ * seam can stamp every error with the session — cross-linking an issue to its
+ * exact DOM replay. Playback re-assembles chunks and feeds rrweb's `Replayer`.
+ *
+ * PRIVACY: inputs are masked by default (`maskAllInputs: true`). Recording user
+ * sessions is a real liability surface — keep masking on, add `blockClass` /
+ * `maskTextClass` to sensitive nodes, and use `maskAllText` for high-sensitivity
+ * apps.
+ */
+/** An rrweb event. Opaque to us — we only buffer/transport/replay it. */
+export type ReplayEvent = {
+    type: number;
+    timestamp: number;
+    data: unknown;
+};
+export type RecordConfig = {
+    emit: (event: ReplayEvent) => void;
+    maskAllInputs?: boolean;
+    maskTextSelector?: string;
+    blockClass?: string;
+    maskTextClass?: string;
+    recordCanvas?: boolean;
+};
+/** rrweb's `record` — returns a stop handler. */
+export type RrwebRecord = (config: RecordConfig) => (() => void) | undefined;
+export type RrwebReplayerInstance = {
+    play: (timeOffset?: number) => void;
+    pause: () => void;
+    destroy?: () => void;
+};
+/** rrweb's `Replayer` constructor. */
+export type RrwebReplayerConstructor = new (events: ReplayEvent[], config?: {
+    root?: Element;
+    speed?: number;
+}) => RrwebReplayerInstance;
+/** A contiguous slice of a session's events — the unit uploaded to storage. */
+export type ReplayChunk = {
+    replayId: string;
+    project: string;
+    /** Monotonic chunk index within the session (0-based). */
+    seq: number;
+    /** First event timestamp in this chunk. */
+    from: number;
+    /** Last event timestamp in this chunk. */
+    to: number;
+    events: ReplayEvent[];
+};
+/** Session-level metadata — pair with the chunk keys to locate a replay. */
+export type ReplayManifest = {
+    replayId: string;
+    project: string;
+    startedAt: number;
+    release?: string;
+    environment?: string;
+    chunkCount: number;
+    durationMs: number;
+};
+/** Persist one chunk — wire `@absolutejs/blob` (or any object store) here. */
+export type ChunkUpload = (chunk: ReplayChunk) => void | Promise<void>;
+export type RecorderOptions = {
+    project: string;
+    /** Called for each chunk as it's flushed. */
+    upload: ChunkUpload;
+    /** Override the generated session id. */
+    replayId?: string;
+    release?: string;
+    environment?: string;
+    /** Flush a chunk at least this often (ms). Default 5000. */
+    chunkIntervalMs?: number;
+    /** Flush once this many events buffer. Default 200. */
+    chunkMaxEvents?: number;
+    /** Mask all input values (privacy). Default **true**. */
+    maskAllInputs?: boolean;
+    /** Mask all text content (high-sensitivity). Default false. */
+    maskAllText?: boolean;
+    /** CSS class whose subtrees are not recorded. Default `'rr-block'`. */
+    blockClass?: string;
+    /** CSS class whose text is masked. Default `'rr-mask'`. */
+    maskTextClass?: string;
+    /** Record `<canvas>` (heavier). Default false. */
+    recordCanvas?: boolean;
+    /** Inject rrweb's `record` (default: lazy-imported). */
+    record?: RrwebRecord;
+    /** Override `Date.now()` for tests. */
+    clock?: () => number;
+    /** Hook for upload / recorder failures (best-effort; never throws to the app). */
+    onError?: (error: unknown) => void;
+};
+export type Recorder = {
+    /** The session id — feed to `@absolutejs/beacon`'s `getReplayId`. */
+    replayId: string;
+    /** Current session metadata snapshot. */
+    manifest: () => ReplayManifest;
+    /** Force-flush the buffered events as a chunk now. */
+    flush: () => Promise<void>;
+    /** Stop recording and flush the final chunk. */
+    stop: () => Promise<void>;
+};
+export declare const createRecorder: (options: RecorderOptions) => Recorder;
+/** Re-assemble a session's chunks into a single ordered event stream. */
+export declare const assembleReplay: (chunks: ReplayChunk[]) => ReplayEvent[];
+export type ReplayPlayerOptions = {
+    /** Element to mount the replay into. */
+    target: Element;
+    /** The assembled event stream (see `assembleReplay`). */
+    events: ReplayEvent[];
+    /** Inject rrweb's `Replayer` (default: lazy-imported). */
+    Replayer?: RrwebReplayerConstructor;
+    /** Start playing immediately. Default true. */
+    autoplay?: boolean;
+    speed?: number;
+};
+export type ReplayPlayer = {
+    play: (timeOffset?: number) => void;
+    pause: () => void;
+    destroy: () => void;
+};
+export declare const createReplayPlayer: (options: ReplayPlayerOptions) => Promise<ReplayPlayer>;

package/dist/index.js

@@ -0,0 +1,153 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+var newId = () => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+};
+var loadRrwebRecord = async () => {
+  try {
+    const mod = await import("rrweb");
+    return mod.record;
+  } catch (cause) {
+    throw new Error("[replay] rrweb is not installed. Run `bun add rrweb`, or pass `record` to createRecorder.", { cause });
+  }
+};
+var loadRrwebReplayer = async () => {
+  try {
+    const mod = await import("rrweb");
+    return mod.Replayer;
+  } catch (cause) {
+    throw new Error("[replay] rrweb is not installed. Run `bun add rrweb`, or pass `Replayer` to createReplayPlayer.", { cause });
+  }
+};
+var createRecorder = (options) => {
+  const replayId = options.replayId ?? newId();
+  const clock = options.clock ?? Date.now;
+  const startedAt = clock();
+  const baseManifest = (chunkCount2, durationMs) => ({
+    chunkCount: chunkCount2,
+    durationMs,
+    project: options.project,
+    replayId,
+    startedAt,
+    ...options.release !== undefined ? { release: options.release } : {},
+    ...options.environment !== undefined ? { environment: options.environment } : {}
+  });
+  if (typeof window === "undefined") {
+    return {
+      flush: async () => {},
+      manifest: () => baseManifest(0, 0),
+      replayId,
+      stop: async () => {}
+    };
+  }
+  const chunkMaxEvents = options.chunkMaxEvents ?? 200;
+  const chunkIntervalMs = options.chunkIntervalMs ?? 5000;
+  const onError = options.onError ?? (() => {});
+  let buffer = [];
+  let seq = 0;
+  let chunkCount = 0;
+  let lastTimestamp = startedAt;
+  let stopFn;
+  let stopped = false;
+  const flush = async () => {
+    if (buffer.length === 0)
+      return;
+    const events = buffer;
+    buffer = [];
+    const chunk = {
+      events,
+      from: events[0].timestamp,
+      project: options.project,
+      replayId,
+      seq: seq++,
+      to: events[events.length - 1].timestamp
+    };
+    chunkCount += 1;
+    try {
+      await options.upload(chunk);
+    } catch (error) {
+      onError(error);
+    }
+  };
+  const emit = (event) => {
+    buffer.push(event);
+    lastTimestamp = event.timestamp;
+    if (buffer.length >= chunkMaxEvents)
+      flush();
+  };
+  const config = {
+    blockClass: options.blockClass ?? "rr-block",
+    emit,
+    maskAllInputs: options.maskAllInputs ?? true,
+    maskTextClass: options.maskTextClass ?? "rr-mask",
+    ...options.maskAllText === true ? { maskTextSelector: "*" } : {},
+    ...options.recordCanvas === true ? { recordCanvas: true } : {}
+  };
+  const start = (record) => {
+    if (stopped)
+      return;
+    try {
+      stopFn = record(config) ?? undefined;
+    } catch (error) {
+      onError(error);
+    }
+  };
+  if (options.record !== undefined)
+    start(options.record);
+  else
+    loadRrwebRecord().then(start).catch(onError);
+  const timer = setInterval(() => {
+    flush();
+  }, chunkIntervalMs);
+  timer.unref?.();
+  return {
+    flush,
+    manifest: () => baseManifest(chunkCount, Math.max(0, lastTimestamp - startedAt)),
+    replayId,
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      if (stopFn !== undefined) {
+        try {
+          stopFn();
+        } catch (error) {
+          onError(error);
+        }
+      }
+      await flush();
+    }
+  };
+};
+var assembleReplay = (chunks) => [...chunks].sort((a, b) => a.seq - b.seq).flatMap((chunk) => chunk.events);
+var createReplayPlayer = async (options) => {
+  const Replayer = options.Replayer ?? await loadRrwebReplayer();
+  const replayer = new Replayer(options.events, {
+    root: options.target,
+    ...options.speed !== undefined ? { speed: options.speed } : {}
+  });
+  if (options.autoplay !== false)
+    replayer.play();
+  return {
+    destroy: () => replayer.destroy?.(),
+    pause: () => replayer.pause(),
+    play: (timeOffset) => replayer.play(timeOffset)
+  };
+};
+export {
+  createReplayPlayer,
+  createRecorder,
+  assembleReplay
+};
+
+//# debugId=5AEB3D7140DBAB4464756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/replay — session replay for the AbsoluteJS observability stack.\n *\n * DOM recording genuinely needs a heavy, hard-to-replicate engine, so the\n * recorder wraps **rrweb** — but rrweb is an **optional, lazy-loaded peer**\n * (and fully injectable), so:\n *   - this package has ZERO hard dependencies; rrweb is only pulled when you\n *     actually start recording, and only into the replay code path (opt-in\n *     weight — replay is the one heavy feature, never on a page that isn't\n *     recording).\n *   - it's plain TS, NOT Effect — like @absolutejs/beacon, it's browser-first\n *     where bytes are the cost; the server-side rigor lives in the ingest /\n *     storage layers.\n *\n * Pipeline: rrweb emits events → buffered → chunked (by size/interval) →\n * uploaded via a pluggable `upload` transport (wire `@absolutejs/blob`). A\n * `replayId` is exposed synchronously so `@absolutejs/beacon`'s `getReplayId`\n * seam can stamp every error with the session — cross-linking an issue to its\n * exact DOM replay. Playback re-assembles chunks and feeds rrweb's `Replayer`.\n *\n * PRIVACY: inputs are masked by default (`maskAllInputs: true`). Recording user\n * sessions is a real liability surface — keep masking on, add `blockClass` /\n * `maskTextClass` to sensitive nodes, and use `maskAllText` for high-sensitivity\n * apps.\n */\n\n// =============================================================================\n// rrweb structural types — declared locally so rrweb stays an optional peer\n// (no hard type dependency on the public surface).\n// =============================================================================\n\n/** An rrweb event. Opaque to us — we only buffer/transport/replay it. */\nexport type ReplayEvent = {\n  type: number;\n  timestamp: number;\n  data: unknown;\n};\n\nexport type RecordConfig = {\n  emit: (event: ReplayEvent) => void;\n  maskAllInputs?: boolean;\n  maskTextSelector?: string;\n  blockClass?: string;\n  maskTextClass?: string;\n  recordCanvas?: boolean;\n};\n\n/** rrweb's `record` — returns a stop handler. */\nexport type RrwebRecord = (config: RecordConfig) => (() => void) | undefined;\n\nexport type RrwebReplayerInstance = {\n  play: (timeOffset?: number) => void;\n  pause: () => void;\n  destroy?: () => void;\n};\n\n/** rrweb's `Replayer` constructor. */\nexport type RrwebReplayerConstructor = new (\n  events: ReplayEvent[],\n  config?: { root?: Element; speed?: number },\n) => RrwebReplayerInstance;\n\n// =============================================================================\n// Replay format\n// =============================================================================\n\n/** A contiguous slice of a session's events — the unit uploaded to storage. */\nexport type ReplayChunk = {\n  replayId: string;\n  project: string;\n  /** Monotonic chunk index within the session (0-based). */\n  seq: number;\n  /** First event timestamp in this chunk. */\n  from: number;\n  /** Last event timestamp in this chunk. */\n  to: number;\n  events: ReplayEvent[];\n};\n\n/** Session-level metadata — pair with the chunk keys to locate a replay. */\nexport type ReplayManifest = {\n  replayId: string;\n  project: string;\n  startedAt: number;\n  release?: string;\n  environment?: string;\n  chunkCount: number;\n  durationMs: number;\n};\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\nconst newId = (): string => {\n  if (\n    typeof crypto !== \"undefined\" &&\n    typeof crypto.randomUUID === \"function\"\n  ) {\n    return crypto.randomUUID();\n  }\n  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;\n};\n\nconst loadRrwebRecord = async (): Promise<RrwebRecord> => {\n  try {\n    const mod = (await import(\"rrweb\")) as unknown as { record: RrwebRecord };\n    return mod.record;\n  } catch (cause) {\n    throw new Error(\n      \"[replay] rrweb is not installed. Run `bun add rrweb`, or pass `record` to createRecorder.\",\n      { cause },\n    );\n  }\n};\n\nconst loadRrwebReplayer = async (): Promise<RrwebReplayerConstructor> => {\n  try {\n    const mod = (await import(\"rrweb\")) as unknown as {\n      Replayer: RrwebReplayerConstructor;\n    };\n    return mod.Replayer;\n  } catch (cause) {\n    throw new Error(\n      \"[replay] rrweb is not installed. Run `bun add rrweb`, or pass `Replayer` to createReplayPlayer.\",\n      { cause },\n    );\n  }\n};\n\n// =============================================================================\n// Recorder\n// =============================================================================\n\n/** Persist one chunk — wire `@absolutejs/blob` (or any object store) here. */\nexport type ChunkUpload = (chunk: ReplayChunk) => void | Promise<void>;\n\nexport type RecorderOptions = {\n  project: string;\n  /** Called for each chunk as it's flushed. */\n  upload: ChunkUpload;\n  /** Override the generated session id. */\n  replayId?: string;\n  release?: string;\n  environment?: string;\n  /** Flush a chunk at least this often (ms). Default 5000. */\n  chunkIntervalMs?: number;\n  /** Flush once this many events buffer. Default 200. */\n  chunkMaxEvents?: number;\n  /** Mask all input values (privacy). Default **true**. */\n  maskAllInputs?: boolean;\n  /** Mask all text content (high-sensitivity). Default false. */\n  maskAllText?: boolean;\n  /** CSS class whose subtrees are not recorded. Default `'rr-block'`. */\n  blockClass?: string;\n  /** CSS class whose text is masked. Default `'rr-mask'`. */\n  maskTextClass?: string;\n  /** Record `<canvas>` (heavier). Default false. */\n  recordCanvas?: boolean;\n  /** Inject rrweb's `record` (default: lazy-imported). */\n  record?: RrwebRecord;\n  /** Override `Date.now()` for tests. */\n  clock?: () => number;\n  /** Hook for upload / recorder failures (best-effort; never throws to the app). */\n  onError?: (error: unknown) => void;\n};\n\nexport type Recorder = {\n  /** The session id — feed to `@absolutejs/beacon`'s `getReplayId`. */\n  replayId: string;\n  /** Current session metadata snapshot. */\n  manifest: () => ReplayManifest;\n  /** Force-flush the buffered events as a chunk now. */\n  flush: () => Promise<void>;\n  /** Stop recording and flush the final chunk. */\n  stop: () => Promise<void>;\n};\n\nexport const createRecorder = (options: RecorderOptions): Recorder => {\n  const replayId = options.replayId ?? newId();\n  const clock = options.clock ?? Date.now;\n  const startedAt = clock();\n\n  const baseManifest = (\n    chunkCount: number,\n    durationMs: number,\n  ): ReplayManifest => ({\n    chunkCount,\n    durationMs,\n    project: options.project,\n    replayId,\n    startedAt,\n    ...(options.release !== undefined ? { release: options.release } : {}),\n    ...(options.environment !== undefined\n      ? { environment: options.environment }\n      : {}),\n  });\n\n  // SSR / non-DOM: a valid recorder handle that records nothing.\n  if (typeof window === \"undefined\") {\n    return {\n      flush: async () => {},\n      manifest: () => baseManifest(0, 0),\n      replayId,\n      stop: async () => {},\n    };\n  }\n\n  const chunkMaxEvents = options.chunkMaxEvents ?? 200;\n  const chunkIntervalMs = options.chunkIntervalMs ?? 5000;\n  const onError = options.onError ?? (() => {});\n\n  let buffer: ReplayEvent[] = [];\n  let seq = 0;\n  let chunkCount = 0;\n  let lastTimestamp = startedAt;\n  let stopFn: (() => void) | undefined;\n  let stopped = false;\n\n  const flush = async (): Promise<void> => {\n    if (buffer.length === 0) return;\n    const events = buffer;\n    buffer = [];\n    const chunk: ReplayChunk = {\n      events,\n      from: events[0]!.timestamp,\n      project: options.project,\n      replayId,\n      seq: seq++,\n      to: events[events.length - 1]!.timestamp,\n    };\n    chunkCount += 1;\n    try {\n      await options.upload(chunk);\n    } catch (error) {\n      onError(error);\n    }\n  };\n\n  const emit = (event: ReplayEvent): void => {\n    buffer.push(event);\n    lastTimestamp = event.timestamp;\n    if (buffer.length >= chunkMaxEvents) void flush();\n  };\n\n  const config: RecordConfig = {\n    blockClass: options.blockClass ?? \"rr-block\",\n    emit,\n    maskAllInputs: options.maskAllInputs ?? true,\n    maskTextClass: options.maskTextClass ?? \"rr-mask\",\n    ...(options.maskAllText === true ? { maskTextSelector: \"*\" } : {}),\n    ...(options.recordCanvas === true ? { recordCanvas: true } : {}),\n  };\n\n  const start = (record: RrwebRecord): void => {\n    if (stopped) return;\n    try {\n      stopFn = record(config) ?? undefined;\n    } catch (error) {\n      onError(error);\n    }\n  };\n\n  if (options.record !== undefined) start(options.record);\n  else loadRrwebRecord().then(start).catch(onError);\n\n  const timer = setInterval(() => {\n    void flush();\n  }, chunkIntervalMs);\n  (timer as { unref?: () => void }).unref?.();\n\n  return {\n    flush,\n    manifest: () =>\n      baseManifest(chunkCount, Math.max(0, lastTimestamp - startedAt)),\n    replayId,\n    stop: async () => {\n      stopped = true;\n      clearInterval(timer);\n      if (stopFn !== undefined) {\n        try {\n          stopFn();\n        } catch (error) {\n          onError(error);\n        }\n      }\n      await flush();\n    },\n  };\n};\n\n// =============================================================================\n// Playback\n// =============================================================================\n\n/** Re-assemble a session's chunks into a single ordered event stream. */\nexport const assembleReplay = (chunks: ReplayChunk[]): ReplayEvent[] =>\n  [...chunks].sort((a, b) => a.seq - b.seq).flatMap((chunk) => chunk.events);\n\nexport type ReplayPlayerOptions = {\n  /** Element to mount the replay into. */\n  target: Element;\n  /** The assembled event stream (see `assembleReplay`). */\n  events: ReplayEvent[];\n  /** Inject rrweb's `Replayer` (default: lazy-imported). */\n  Replayer?: RrwebReplayerConstructor;\n  /** Start playing immediately. Default true. */\n  autoplay?: boolean;\n  speed?: number;\n};\n\nexport type ReplayPlayer = {\n  play: (timeOffset?: number) => void;\n  pause: () => void;\n  destroy: () => void;\n};\n\nexport const createReplayPlayer = async (\n  options: ReplayPlayerOptions,\n): Promise<ReplayPlayer> => {\n  const Replayer = options.Replayer ?? (await loadRrwebReplayer());\n  const replayer = new Replayer(options.events, {\n    root: options.target,\n    ...(options.speed !== undefined ? { speed: options.speed } : {}),\n  });\n  if (options.autoplay !== false) replayer.play();\n  return {\n    destroy: () => replayer.destroy?.(),\n    pause: () => replayer.pause(),\n    play: (timeOffset) => replayer.play(timeOffset),\n  };\n};\n"
+  ],
+  "mappings": ";;;;;;;;;AA8FA,IAAM,QAAQ,MAAc;AAAA,EAC1B,IACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,YAC7B;AAAA,IACA,OAAO,OAAO,WAAW;AAAA,EAC3B;AAAA,EACA,OAAO,GAAG,KAAK,IAAI,EAAE,SAAS,EAAE,KAAK,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE;AAAA;AAG7E,IAAM,kBAAkB,YAAkC;AAAA,EACxD,IAAI;AAAA,IACF,MAAM,MAAO,MAAa;AAAA,IAC1B,OAAO,IAAI;AAAA,IACX,OAAO,OAAO;AAAA,IACd,MAAM,IAAI,MACR,6FACA,EAAE,MAAM,CACV;AAAA;AAAA;AAIJ,IAAM,oBAAoB,YAA+C;AAAA,EACvE,IAAI;AAAA,IACF,MAAM,MAAO,MAAa;AAAA,IAG1B,OAAO,IAAI;AAAA,IACX,OAAO,OAAO;AAAA,IACd,MAAM,IAAI,MACR,mGACA,EAAE,MAAM,CACV;AAAA;AAAA;AAoDG,IAAM,iBAAiB,CAAC,YAAuC;AAAA,EACpE,MAAM,WAAW,QAAQ,YAAY,MAAM;AAAA,EAC3C,MAAM,QAAQ,QAAQ,SAAS,KAAK;AAAA,EACpC,MAAM,YAAY,MAAM;AAAA,EAExB,MAAM,eAAe,CACnB,aACA,gBACoB;AAAA,IACpB;AAAA,IACA;AAAA,IACA,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA;AAAA,OACI,QAAQ,YAAY,YAAY,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AAAA,OAChE,QAAQ,gBAAgB,YACxB,EAAE,aAAa,QAAQ,YAAY,IACnC,CAAC;AAAA,EACP;AAAA,EAGA,IAAI,OAAO,WAAW,aAAa;AAAA,IACjC,OAAO;AAAA,MACL,OAAO,YAAY;AAAA,MACnB,UAAU,MAAM,aAAa,GAAG,CAAC;AAAA,MACjC;AAAA,MACA,MAAM,YAAY;AAAA,IACpB;AAAA,EACF;AAAA,EAEA,MAAM,iBAAiB,QAAQ,kBAAkB;AAAA,EACjD,MAAM,kBAAkB,QAAQ,mBAAmB;AAAA,EACnD,MAAM,UAAU,QAAQ,YAAY,MAAM;AAAA,EAE1C,IAAI,SAAwB,CAAC;AAAA,EAC7B,IAAI,MAAM;AAAA,EACV,IAAI,aAAa;AAAA,EACjB,IAAI,gBAAgB;AAAA,EACpB,IAAI;AAAA,EACJ,IAAI,UAAU;AAAA,EAEd,MAAM,QAAQ,YAA2B;AAAA,IACvC,IAAI,OAAO,WAAW;AAAA,MAAG;AAAA,IACzB,MAAM,SAAS;AAAA,IACf,SAAS,CAAC;AAAA,IACV,MAAM,QAAqB;AAAA,MACzB;AAAA,MACA,MAAM,OAAO,GAAI;AAAA,MACjB,SAAS,QAAQ;AAAA,MACjB;AAAA,MACA,KAAK;AAAA,MACL,IAAI,OAAO,OAAO,SAAS,GAAI;AAAA,IACjC;AAAA,IACA,cAAc;AAAA,IACd,IAAI;AAAA,MACF,MAAM,QAAQ,OAAO,KAAK;AAAA,MAC1B,OAAO,OAAO;AAAA,MACd,QAAQ,KAAK;AAAA;AAAA;AAAA,EAIjB,MAAM,OAAO,CAAC,UAA6B;AAAA,IACzC,OAAO,KAAK,KAAK;AAAA,IACjB,gBAAgB,MAAM;AAAA,IACtB,IAAI,OAAO,UAAU;AAAA,MAAqB,MAAM;AAAA;AAAA,EAGlD,MAAM,SAAuB;AAAA,IAC3B,YAAY,QAAQ,cAAc;AAAA,IAClC;AAAA,IACA,eAAe,QAAQ,iBAAiB;AAAA,IACxC,eAAe,QAAQ,iBAAiB;AAAA,OACpC,QAAQ,gBAAgB,OAAO,EAAE,kBAAkB,IAAI,IAAI,CAAC;AAAA,OAC5D,QAAQ,iBAAiB,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;AAAA,EAChE;AAAA,EAEA,MAAM,QAAQ,CAAC,WAA8B;AAAA,IAC3C,IAAI;AAAA,MAAS;AAAA,IACb,IAAI;AAAA,MACF,SAAS,OAAO,MAAM,KAAK;AAAA,MAC3B,OAAO,OAAO;AAAA,MACd,QAAQ,KAAK;AAAA;AAAA;AAAA,EAIjB,IAAI,QAAQ,WAAW;AAAA,IAAW,MAAM,QAAQ,MAAM;AAAA,EACjD;AAAA,oBAAgB,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO;AAAA,EAEhD,MAAM,QAAQ,YAAY,MAAM;AAAA,IACzB,MAAM;AAAA,KACV,eAAe;AAAA,EACjB,MAAiC,QAAQ;AAAA,EAE1C,OAAO;AAAA,IACL;AAAA,IACA,UAAU,MACR,aAAa,YAAY,KAAK,IAAI,GAAG,gBAAgB,SAAS,CAAC;AAAA,IACjE;AAAA,IACA,MAAM,YAAY;AAAA,MAChB,UAAU;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,IAAI,WAAW,WAAW;AAAA,QACxB,IAAI;AAAA,UACF,OAAO;AAAA,UACP,OAAO,OAAO;AAAA,UACd,QAAQ,KAAK;AAAA;AAAA,MAEjB;AAAA,MACA,MAAM,MAAM;AAAA;AAAA,EAEhB;AAAA;AAQK,IAAM,iBAAiB,CAAC,WAC7B,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,UAAU,MAAM,MAAM;AAoBpE,IAAM,qBAAqB,OAChC,YAC0B;AAAA,EAC1B,MAAM,WAAW,QAAQ,YAAa,MAAM,kBAAkB;AAAA,EAC9D,MAAM,WAAW,IAAI,SAAS,QAAQ,QAAQ;AAAA,IAC5C,MAAM,QAAQ;AAAA,OACV,QAAQ,UAAU,YAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA,EAChE,CAAC;AAAA,EACD,IAAI,QAAQ,aAAa;AAAA,IAAO,SAAS,KAAK;AAAA,EAC9C,OAAO;AAAA,IACL,SAAS,MAAM,SAAS,UAAU;AAAA,IAClC,OAAO,MAAM,SAAS,MAAM;AAAA,IAC5B,MAAM,CAAC,eAAe,SAAS,KAAK,UAAU;AAAA,EAChD;AAAA;",
+  "debugId": "5AEB3D7140DBAB4464756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@absolutejs/replay",
+  "version": "0.0.1",
+  "description": "Session replay for the AbsoluteJS observability stack. A tiny zero-hard-dependency recorder (rrweb is an optional, lazy-loaded peer) that chunks DOM recordings and uploads them via a pluggable transport (@absolutejs/blob), privacy-masking by default. Plus chunk assembly + a framework-agnostic player. Stamps a replayId for @absolutejs/beacon to cross-link errors to the exact session.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/absolutejs/replay.git"
+  },
+  "homepage": "https://github.com/absolutejs/replay",
+  "bugs": {
+    "url": "https://github.com/absolutejs/replay/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "license": "BSL-1.1",
+  "author": "Alex Kahn",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=browser --external rrweb && tsc --project tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"./**/*.{ts,json,md}\"",
+    "check:package": "bun run typecheck && bun run build && bun run test",
+    "release": "bun run format && bun run check:package && bun publish"
+  },
+  "keywords": [
+    "absolutejs",
+    "replay",
+    "session-replay",
+    "rrweb",
+    "browser",
+    "observability",
+    "rum",
+    "logrocket"
+  ],
+  "peerDependencies": {
+    "rrweb": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "rrweb": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "@types/bun": "^1.3.14",
+    "prettier": "^3.8.3",
+    "rrweb": "^2.0.1",
+    "typescript": "^5.9.0"
+  }
+}