@uptimizr/replay 0.1.0

package/dist/drivers/playcanvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playcanvas.js","sourceRoot":"","sources":["../../src/drivers/playcanvas.ts"],"names":[],"mappings":"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"}

package/dist/drivers/three.d.ts

@@ -0,0 +1,127 @@
+import type { CustomPropValue } from "@uptimizr/schema";
+import type { ReplayDriver } from "../types.js";
+/**
+ * Structural view of the three.js objects this driver writes to. Kept minimal and
+ * structural so `three` stays an **optional peer dependency** — the driver never
+ * imports three at runtime; the host page owns the scene and the real objects.
+ */
+interface ThreeReplayCamera {
+    position: {
+        set(x: number, y: number, z: number): void;
+    };
+    /** `Object3D.lookAt(x, y, z)` — for a camera, orients so it looks at the point. */
+    lookAt(x: number, y: number, z: number): void;
+    /** Present on `PerspectiveCamera`. */
+    isPerspectiveCamera?: boolean;
+    /** Vertical FOV in **degrees** (three.js convention). */
+    fov?: number;
+    updateProjectionMatrix?: () => void;
+}
+interface ThreeReplayScene {
+    /** three exposes the active camera per-render, not on the scene; pass it explicitly. */
+    [key: string]: unknown;
+}
+/** A three.js node a replay can drive (an `Object3D` — mesh, group, etc.). */
+export type ThreeReplayNode = object;
+export interface ThreeReplayDriverOptions {
+    /** Scene to re-drive (read/write only — never emits analytics events). */
+    scene: ThreeReplayScene;
+    /** Camera to move. three has no `scene.activeCamera`, so this is required. */
+    camera: ThreeReplayCamera;
+    /** Called for each replayed pointer event, so the host can render a marker. */
+    onPointer?: (screen: [number, number] | undefined, hitPoint: [number, number, number] | undefined, hitMesh: string | undefined, type: "pointer_move" | "pointer_click" | "pointer_down" | "pointer_up") => void;
+    /** Called for each replayed mesh interaction, so the host can highlight it. */
+    onMeshInteraction?: (mesh: string, kind: string, point: [number, number, number] | undefined) => void;
+    /**
+     * Scene-actor resolvers for `node_transform` drive-back (ADR 0027). Maps a
+     * recorded `nodeId` to the live three `Object3D` to re-drive — a direct
+     * reference or a `() => node` resolver. Tier-1 (world-frame) samples are
+     * converted canonical → three and applied to the node's local transform
+     * (correct for root actors). Tier-2 bone samples drive the matching named
+     * `Bone` of the node's `skeleton` (a `SkinnedMesh`) in its local frame; every
+     * sample is also forwarded via {@link onNodeTransform}.
+     */
+    nodes?: Record<string, ThreeReplayNode | (() => ThreeReplayNode | null | undefined)>;
+    /**
+     * Called for **every** replayed `node_transform` (Tier 1 and Tier 2), after any
+     * node drive-back. The position/rotation are converted into three's
+     * right-handed frame; `boneId` is set for Tier-2 samples.
+     */
+    onNodeTransform?: (nodeId: string, transform: {
+        boneId: string | undefined;
+        childPath: string | undefined;
+        position: [number, number, number];
+        rotation: [number, number, number, number];
+        scale: [number, number, number] | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed developer-defined `custom` event. The driver can't
+     * know how to render an arbitrary domain event, so it forwards the name, props,
+     * and timestamp for the host to visualize (marker, toast, log, ...).
+     */
+    onCustom?: (name: string, props: Record<string, CustomPropValue> | undefined, ts: number) => void;
+    /**
+     * Called for each replayed `input_action` (discrete keyboard/gamepad action,
+     * ADR 0023). Forwarded with the action, raw `code`/`button`, source, and
+     * timestamp so a replay UI can annotate the timeline.
+     */
+    onInputAction?: (input: {
+        action: string;
+        code: string | undefined;
+        button: number | undefined;
+        pressed: boolean | undefined;
+        source: string | undefined;
+    }, ts: number) => void;
+    /**
+     * Called for each replayed browser/engine lifecycle event (viewport resize, tab
+     * visibility, window focus, GPU context loss/restore). The driver doesn't
+     * re-drive these — it forwards them so a replay UI can annotate the timeline.
+     */
+    onLifecycle?: (event: {
+        type: "viewport_resize";
+        width: number;
+        height: number;
+        dpr: number | undefined;
+    } | {
+        type: "visibility_change";
+        state: "visible" | "hidden";
+    } | {
+        type: "focus_change";
+        focused: boolean;
+    } | {
+        type: "context_lost";
+    } | {
+        type: "context_restored";
+    }, ts: number) => void;
+    /**
+     * Called for each replayed `runtime_error` event (opt-in capture, ADR 0013).
+     * Forwarded so a replay UI can mark where a JS error or unhandled rejection
+     * interrupted the session.
+     */
+    onError?: (error: {
+        kind: "error" | "unhandledrejection";
+        message: string;
+        source: string | undefined;
+        lineno: number | undefined;
+        colno: number | undefined;
+        stack: string | undefined;
+    }, ts: number) => void;
+}
+/**
+ * three.js replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own three.js scene.
+ *
+ * ## Coordinate frame (canonical → three)
+ * Events arrive in the canonical **left-handed, y-up** frame (ADR 0018); three is
+ * **right-handed**, so world-space data is converted back with the shared
+ * `fromCanonical*` helpers (the Z-negation reflection is its own inverse). Camera
+ * orientation is applied via `camera.lookAt(target)` — `lookAt` resolves three's
+ * −Z-forward convention internally, so the driver does **not** re-derive a forward
+ * axis from the recorded direction (avoiding the orientation trap documented in
+ * sdk-core `coordinates.ts`).
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export declare function createThreeReplayDriver(options: ThreeReplayDriverOptions): ReplayDriver;
+export {};
+//# sourceMappingURL=three.d.ts.map

package/dist/drivers/three.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three.d.ts","sourceRoot":"","sources":["../../src/drivers/three.ts"],"names":[],"mappings":"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"}

package/dist/drivers/three.js

@@ -0,0 +1,194 @@
+import { fromCanonicalDirection, fromCanonicalPosition, fromCanonicalQuat, } from "@uptimizr/sdk-core";
+/**
+ * Walk a `/`-separated {@link NodeTransformEvent.childPath} from a resolved root
+ * actor to the descendant node, matching each segment against direct children by
+ * `name` (ADR 0033). Returns `null` if any segment is missing.
+ */
+function resolveChildByPath(root, childPath) {
+    let cur = root;
+    for (const segment of childPath.split("/")) {
+        if (!segment)
+            continue;
+        const children = cur?.children;
+        if (!Array.isArray(children))
+            return null;
+        cur = children.find((c) => c.name === segment) ?? null;
+        if (!cur)
+            return null;
+    }
+    return cur;
+}
+/** Resolve a node entry (direct ref or `() => node`) to a live node, or `null`. */
+function resolveReplayNode(entry) {
+    if (!entry)
+        return null;
+    if (typeof entry === "function") {
+        return entry() ?? null;
+    }
+    return entry;
+}
+/**
+ * three.js replay driver. Re-drives camera pose (and surfaces pointer/mesh events
+ * to host callbacks) in the user's own three.js scene.
+ *
+ * ## Coordinate frame (canonical → three)
+ * Events arrive in the canonical **left-handed, y-up** frame (ADR 0018); three is
+ * **right-handed**, so world-space data is converted back with the shared
+ * `fromCanonical*` helpers (the Z-negation reflection is its own inverse). Camera
+ * orientation is applied via `camera.lookAt(target)` — `lookAt` resolves three's
+ * −Z-forward convention internally, so the driver does **not** re-derive a forward
+ * axis from the recorded direction (avoiding the orientation trap documented in
+ * sdk-core `coordinates.ts`).
+ *
+ * It only reads/writes the scene — it never emits analytics events (ADR 0006).
+ */
+export function createThreeReplayDriver(options) {
+    return {
+        reset() {
+            // Camera state is fully determined by the next camera_sample, so there is
+            // nothing to restore; host-rendered markers are the host's responsibility.
+        },
+        apply(event) {
+            switch (event.type) {
+                case "camera_sample": {
+                    const cam = options.camera;
+                    if (!cam)
+                        return;
+                    // Position: canonical → three (Z-negated).
+                    const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                    cam.position.set(px, py, pz);
+                    // Look target: an explicit recorded target, else position + direction —
+                    // both converted to three's frame. lookAt handles the −Z forward axis.
+                    let tx;
+                    let ty;
+                    let tz;
+                    if (event.target) {
+                        [tx, ty, tz] = fromCanonicalPosition(event.target, "right");
+                    }
+                    else {
+                        const [dx, dy, dz] = fromCanonicalDirection(event.direction, "right");
+                        tx = px + dx;
+                        ty = py + dy;
+                        tz = pz + dz;
+                    }
+                    cam.lookAt(tx, ty, tz);
+                    // three's perspective FOV is in degrees; the wire carries radians.
+                    if (cam.isPerspectiveCamera && typeof event.fov === "number") {
+                        cam.fov = (event.fov * 180) / Math.PI;
+                        cam.updateProjectionMatrix?.();
+                    }
+                    break;
+                }
+                case "pointer_move":
+                case "pointer_click":
+                case "pointer_down":
+                case "pointer_up": {
+                    // Convert the world-space hit point back into three's frame so a host
+                    // marker lands correctly; screen coords are engine-independent.
+                    const hitPoint = event.hitPoint
+                        ? fromCanonicalPosition(event.hitPoint, "right")
+                        : undefined;
+                    options.onPointer?.(event.screen, hitPoint, event.hitMesh, event.type);
+                    break;
+                }
+                case "mesh_interaction": {
+                    const point = event.point ? fromCanonicalPosition(event.point, "right") : undefined;
+                    options.onMeshInteraction?.(event.mesh, event.kind, point);
+                    break;
+                }
+                case "custom":
+                    options.onCustom?.(event.name, event.props, event.ts);
+                    break;
+                case "input_action":
+                    options.onInputAction?.({
+                        action: event.action,
+                        code: event.code,
+                        button: event.button,
+                        pressed: event.pressed,
+                        source: event.source,
+                    }, event.ts);
+                    break;
+                case "viewport_resize":
+                    options.onLifecycle?.({ type: "viewport_resize", width: event.width, height: event.height, dpr: event.dpr }, event.ts);
+                    break;
+                case "visibility_change":
+                    options.onLifecycle?.({ type: "visibility_change", state: event.state }, event.ts);
+                    break;
+                case "focus_change":
+                    options.onLifecycle?.({ type: "focus_change", focused: event.focused }, event.ts);
+                    break;
+                case "context_lost":
+                    options.onLifecycle?.({ type: "context_lost" }, event.ts);
+                    break;
+                case "context_restored":
+                    options.onLifecycle?.({ type: "context_restored" }, event.ts);
+                    break;
+                case "runtime_error":
+                    options.onError?.({
+                        kind: event.kind,
+                        message: event.message,
+                        source: event.source,
+                        lineno: event.lineno,
+                        colno: event.colno,
+                        stack: event.stack,
+                    }, event.ts);
+                    break;
+                case "camera_gesture":
+                    // Derived navigation annotation (ADR 0025); the camera trajectory is
+                    // reconstructed from camera_sample, so replay intentionally ignores it.
+                    break;
+                case "node_transform": {
+                    const node = resolveReplayNode(options.nodes?.[event.nodeId]);
+                    if (node) {
+                        if (event.boneId !== undefined) {
+                            // Tier 2: drive the named bone's parent-relative LOCAL pose. The
+                            // canonical reflection conjugates a local transform the same way it
+                            // does a world one, so the same convert applies (ADR 0027).
+                            const bone = node.skeleton?.bones?.find((b) => b.name === event.boneId);
+                            if (bone) {
+                                const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                                bone.position?.set(px, py, pz);
+                                const [qx, qy, qz, qw] = fromCanonicalQuat(event.rotation, "right");
+                                bone.quaternion?.set(qx, qy, qz, qw);
+                                if (event.scale) {
+                                    bone.scale?.set(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                            }
+                        }
+                        else {
+                            // Tier 1: the declared root (no childPath) or a subtree child
+                            // resolved by its relative path (ADR 0033). Both carry a world-frame
+                            // pose; canonical → three (Z-negated position + reflected quat).
+                            const target = event.childPath === undefined ? node : resolveChildByPath(node, event.childPath);
+                            if (target) {
+                                const [px, py, pz] = fromCanonicalPosition(event.position, "right");
+                                target.position?.set(px, py, pz);
+                                const [qx, qy, qz, qw] = fromCanonicalQuat(event.rotation, "right");
+                                target.quaternion?.set(qx, qy, qz, qw);
+                                if (event.scale) {
+                                    target.scale?.set(event.scale[0], event.scale[1], event.scale[2]);
+                                }
+                            }
+                        }
+                    }
+                    // Forward the (frame-converted) sample so the host can render a proxy
+                    // marker or annotate the timeline; `boneId` is set for Tier-2 samples,
+                    // `childPath` for Tier-1 subtree children (ADR 0033).
+                    const fwdPos = fromCanonicalPosition(event.position, "right");
+                    const fwdRot = fromCanonicalQuat(event.rotation, "right");
+                    options.onNodeTransform?.(event.nodeId, {
+                        boneId: event.boneId,
+                        childPath: event.childPath,
+                        position: fwdPos,
+                        rotation: fwdRot,
+                        scale: event.scale,
+                    }, event.ts);
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+    };
+}
+//# sourceMappingURL=three.js.map

package/dist/drivers/three.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"three.js","sourceRoot":"","sources":["../../src/drivers/three.ts"],"names":[],"mappings":"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"}

package/dist/fetchSession.d.ts

@@ -0,0 +1,43 @@
+import { type AnyEvent } from "@uptimizr/schema";
+export interface FetchSessionOptions {
+    /** Collector base URL, e.g. `https://collect.example.com`. */
+    endpoint: string;
+    /** Project API key (sent as `x-api-key`). */
+    apiKey: string;
+    /** Session id to fetch. */
+    sessionId: string;
+    /** Override the global `fetch` (for testing or non-browser hosts). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch the ordered event stream for a session from the collector's replay
+ * endpoint (`GET /api/v1/sessions/:id/events`). Validates the payload against the
+ * schema and returns events sorted by timestamp, ready for {@link ReplayPlayer}.
+ */
+export declare function fetchSessionEvents(options: FetchSessionOptions): Promise<AnyEvent[]>;
+/** Optional hooks for the streaming fetch. */
+export interface StreamSessionOptions extends FetchSessionOptions {
+    /**
+     * Called for each line that fails to parse/validate (skipped, not fatal), so
+     * callers can surface or count malformed rows. The count is cumulative.
+     */
+    onMalformedLine?: (count: number) => void;
+}
+/**
+ * Streaming counterpart to {@link fetchSessionEvents}: yields events as they
+ * arrive instead of buffering the whole session, so playback can start before
+ * the full stream has downloaded and neither side holds the entire session at
+ * once (ADR 0015).
+ *
+ * Negotiates NDJSON via `Accept: application/x-ndjson` (and a `?format=ndjson`
+ * hint). A collector that supports it streams one event per line, validated
+ * per-line — a malformed line is skipped (and reported via `onMalformedLine`)
+ * rather than failing the whole fetch. A collector that does **not** support
+ * NDJSON returns the buffered JSON array, which is transparently parsed and
+ * yielded, so this works against old and new servers alike.
+ *
+ * Events are yielded in server order (`ts ASC`); {@link ReplayPlayer} also sorts
+ * defensively, so ordering is guaranteed regardless of transport.
+ */
+export declare function fetchSessionEventsStream(options: StreamSessionOptions): AsyncGenerator<AnyEvent>;
+//# sourceMappingURL=fetchSession.d.ts.map

package/dist/fetchSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchSession.d.ts","sourceRoot":"","sources":["../src/fetchSession.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAY1F;AAED,8CAA8C;AAC9C,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAuB,wBAAwB,CAC7C,OAAO,EAAE,oBAAoB,GAC5B,cAAc,CAAC,QAAQ,CAAC,CAkE1B"}

package/dist/fetchSession.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { anyEventSchema } from "@uptimizr/schema";
+const sessionPayloadSchema = z.array(anyEventSchema);
+/**
+ * Fetch the ordered event stream for a session from the collector's replay
+ * endpoint (`GET /api/v1/sessions/:id/events`). Validates the payload against the
+ * schema and returns events sorted by timestamp, ready for {@link ReplayPlayer}.
+ */
+export async function fetchSessionEvents(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const url = `${options.endpoint}/api/v1/sessions/${encodeURIComponent(options.sessionId)}/events`;
+    const res = await fetchImpl(url, { headers: { "x-api-key": options.apiKey } });
+    if (!res.ok) {
+        throw new Error(`replay fetch failed: ${res.status}`);
+    }
+    const parsed = sessionPayloadSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error("replay fetch returned an invalid session payload");
+    }
+    return parsed.data.sort((a, b) => a.ts - b.ts);
+}
+/**
+ * Streaming counterpart to {@link fetchSessionEvents}: yields events as they
+ * arrive instead of buffering the whole session, so playback can start before
+ * the full stream has downloaded and neither side holds the entire session at
+ * once (ADR 0015).
+ *
+ * Negotiates NDJSON via `Accept: application/x-ndjson` (and a `?format=ndjson`
+ * hint). A collector that supports it streams one event per line, validated
+ * per-line — a malformed line is skipped (and reported via `onMalformedLine`)
+ * rather than failing the whole fetch. A collector that does **not** support
+ * NDJSON returns the buffered JSON array, which is transparently parsed and
+ * yielded, so this works against old and new servers alike.
+ *
+ * Events are yielded in server order (`ts ASC`); {@link ReplayPlayer} also sorts
+ * defensively, so ordering is guaranteed regardless of transport.
+ */
+export async function* fetchSessionEventsStream(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const base = `${options.endpoint}/api/v1/sessions/${encodeURIComponent(options.sessionId)}/events`;
+    const res = await fetchImpl(`${base}?format=ndjson`, {
+        headers: { "x-api-key": options.apiKey, accept: "application/x-ndjson" },
+    });
+    if (!res.ok) {
+        throw new Error(`replay fetch failed: ${res.status}`);
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    // Fallback: a server that ignored the negotiation returned the JSON array.
+    if (!contentType.includes("application/x-ndjson")) {
+        const parsed = sessionPayloadSchema.safeParse(await res.json());
+        if (!parsed.success) {
+            throw new Error("replay fetch returned an invalid session payload");
+        }
+        for (const event of parsed.data.sort((a, b) => a.ts - b.ts)) {
+            yield event;
+        }
+        return;
+    }
+    if (!res.body) {
+        throw new Error("replay stream returned no body");
+    }
+    let malformed = 0;
+    const reportMalformed = () => options.onMalformedLine?.(++malformed);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const handleLine = function* (line) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let json;
+        try {
+            json = JSON.parse(trimmed);
+        }
+        catch {
+            reportMalformed();
+            return;
+        }
+        const parsed = anyEventSchema.safeParse(json);
+        if (parsed.success) {
+            yield parsed.data;
+        }
+        else {
+            reportMalformed();
+        }
+    };
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            yield* handleLine(line);
+            newline = buffer.indexOf("\n");
+        }
+    }
+    // Flush any trailing line without a final newline.
+    yield* handleLine(buffer);
+}
+//# sourceMappingURL=fetchSession.js.map

package/dist/fetchSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchSession.js","sourceRoot":"","sources":["../src/fetchSession.ts"],"names":[],"mappings":"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"}

package/dist/global.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Global (IIFE) entry for `@uptimizr/replay` — exposes `window.UptimizrReplay`
+ * for `<script>`-tag use (e.g. on playground.babylonjs.com), mirroring the
+ * collector's `window.Uptimizr`.
+ *
+ * Unlike the npm entry (where `@babylonjs/core` is a peer dependency the host app
+ * provides), this build bundles the small `Vector3` value the Babylon driver
+ * constructs to push camera pose. The host page's Babylon still owns the scene;
+ * we only hand it plain `{x,y,z}` vectors, so a separately-bundled `Vector3` is
+ * interchangeable.
+ */
+import type { Camera, Scene } from "@babylonjs/core";
+import { createBabylonReplayDriver, type BabylonReplayDriverOptions } from "./drivers/babylon.js";
+import { fetchSessionEvents, fetchSessionEventsStream } from "./fetchSession.js";
+import { ReplayPlayer } from "./player.js";
+import type { ReplayHandle } from "./types.js";
+/** One-call replay: fetch a session and re-drive it in the given Babylon scene. */
+export interface ReplayInSceneOptions {
+    /** Scene to re-drive. */
+    scene: Scene;
+    /** Collector base URL, e.g. `https://collect.example.com`. */
+    endpoint: string;
+    /** Project API key (sent as `x-api-key`). */
+    apiKey: string;
+    /** Session id to replay. */
+    sessionId: string;
+    /** Camera to move. Defaults to `scene.activeCamera`. */
+    camera?: Camera;
+    /** Playback speed multiplier. Default 1. */
+    speed?: number;
+    /** Per pointer event, so the host can render a cursor/marker. */
+    onPointer?: BabylonReplayDriverOptions["onPointer"];
+    /** Per mesh interaction, so the host can highlight a mesh. */
+    onMeshInteraction?: BabylonReplayDriverOptions["onMeshInteraction"];
+    /** Per developer-defined `custom` event. */
+    onCustom?: BabylonReplayDriverOptions["onCustom"];
+    /** Per browser/engine lifecycle event (resize, visibility, focus, context loss). */
+    onLifecycle?: BabylonReplayDriverOptions["onLifecycle"];
+    /** Per captured `runtime_error` event (opt-in capture). */
+    onError?: BabylonReplayDriverOptions["onError"];
+    /** Progress callback (clamped elapsed and total duration, in ms). */
+    onProgress?: (elapsedMs: number, durationMs: number) => void;
+    /** Called once when playback reaches the end. */
+    onComplete?: () => void;
+    /** Log each step (fetch, event counts, play, progress, complete) to the console. */
+    debug?: boolean;
+}
+/**
+ * Fetch a captured session from the collector and play it back in `scene`,
+ * starting immediately. Returns the {@link ReplayHandle} so callers can
+ * pause/seek/stop. The collector must have raw-session retention enabled for the
+ * session-events endpoint to return data (ADR 0003).
+ *
+ * Emits a concise console summary (and, with `debug: true`, per-step logs) so it
+ * is clear whether playback is running. The common "nothing happens" causes —
+ * an empty session, a session with no `camera_sample` events, or a scene with no
+ * active camera — are surfaced as console warnings.
+ */
+export declare function replayInScene(options: ReplayInSceneOptions): Promise<ReplayHandle>;
+export { createBabylonReplayDriver, fetchSessionEvents, fetchSessionEventsStream, ReplayPlayer };
+export type { BabylonReplayDriverOptions, ReplayHandle };
+//# sourceMappingURL=global.d.ts.map

package/dist/global.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,KAAK,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,0BAA0B,CAAC,WAAW,CAAC,CAAC;IACpD,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;IACpE,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,0BAA0B,CAAC,UAAU,CAAC,CAAC;IAClD,oFAAoF;IACpF,WAAW,CAAC,EAAE,0BAA0B,CAAC,aAAa,CAAC,CAAC;IACxD,2DAA2D;IAC3D,OAAO,CAAC,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;IAChD,qEAAqE;IACrE,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyFxF;AAED,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,YAAY,EAAE,CAAC;AACjG,YAAY,EAAE,0BAA0B,EAAE,YAAY,EAAE,CAAC"}