@reactra/behaviours 0.1.0-alpha.0

package/dist/replayable.js

@@ -0,0 +1,735 @@
+// @reactra/behaviours/replayable — session-recording runtime for `uses replayable`.
+//
+// Owner spec: reactra-replay-spec.md §3 (format) / §4 (emission) / §5 (runtime) /
+// §7 (dev-vs-prod gating). `uses replayable` is a compiler-native behaviour: Pass 9
+// emits an inner-body preamble (`useReplayChannel` + a mount/unmount effect), an
+// `action` + post-body `state_snapshot` emit per action, and a status `useEffect`
+// per resource (Compiler §4 Pass 9.1). This module is the runtime those emitted
+// calls drive — NOT a higher-order wrapper.
+//
+// Recording is OFF by default (§7): the channel is a no-op until
+// `configureReplay({ enabled: true })`. The instrumentation is always emitted
+// (never conditional — no Rules-of-Hooks violation); only the *recording* is
+// gated, here, at the channel level. Node-portable: pure JS + React hooks,
+// `performance.now()`, `Date.now()`. No browser- or Bun-only APIs.
+import { useEffect, useRef } from "react";
+const DEFAULT_CONFIG = {
+    enabled: false,
+    redactKeys: [],
+    maxEvents: 10_000,
+    excludeActions: [],
+    excludeComponents: [],
+    includeStateKeys: [],
+    coalesceMs: 0,
+    sample: 1,
+    maxEventsPerSecond: 0,
+    keyframeEvery: 20,
+};
+let config = DEFAULT_CONFIG;
+const routeGlobal = globalThis;
+/** Synthetic instance id for the route snapshot — shared with devtools. */
+const ROUTE_ID = "Route#1";
+const ROUTE_NAME = "Route";
+/**
+ * Receive a router transition and record it as a `Route#1` keyframe snapshot
+ * (§5, C1/C3). Flattens `params`/`query` to top-level so a user's existing
+ * `redactKeys` match by param name; runs the whole object through the same
+ * `filterState` + `warnUnredactedPII` path every snapshot uses; and — when a
+ * param/query value is redacted out — scrubs that raw value from the stored
+ * `path` string too (the raw URL must not leak a value `filterState` removed).
+ * Gated on `recordingSession() !== null`, so the drive's own `navigate()` (which
+ * runs in replay mode) never records a feedback route event.
+ */
+const receiveRoute = (route) => {
+    // Suppress during replay mode / when paused / sampled out — reuse the shared
+    // gate, identical to `emit`. Without this the drive's navigate() would record
+    // a feedback route event (the devtools scrub-nav-leak race).
+    if (recordingSession() === null)
+        return;
+    // §5 C4: exclusion is enforced here (the receiver bypasses the channel that
+    // normally checks it) — `excludeComponents:["Route"]` turns the tap off.
+    if (config.excludeComponents.includes(ROUTE_NAME))
+        return;
+    const path = route.pathname + (route.search ? `?${route.search}` : "");
+    // Flatten params + query to top-level for redaction matching, keeping the
+    // structured `path`/`pathname`/`params`/`query` for fidelity + the drive side.
+    const flat = { path, pathname: route.pathname };
+    for (const [k, v] of Object.entries(route.params))
+        flat[k] = v;
+    for (const [k, v] of Object.entries(route.query))
+        flat[k] = v;
+    flat.params = route.params;
+    flat.query = route.query;
+    const filtered = filterState(flat);
+    // Any flattened param/query key that `filterState` dropped is redacted — scrub
+    // its raw value from EVERY surviving string surface (`path`, `pathname`) and
+    // from the structured `params`/`query` copies, so a value redaction removed
+    // never leaks through the raw URL or a sibling field.
+    const redactedValues = [];
+    const safeParams = { ...route.params };
+    const safeQuery = { ...route.query };
+    for (const key of Object.keys(route.params)) {
+        if (key in filtered)
+            continue;
+        redactedValues.push(route.params[key]);
+        delete safeParams[key];
+    }
+    for (const key of Object.keys(route.query)) {
+        if (key in filtered)
+            continue;
+        const v = route.query[key];
+        for (const part of Array.isArray(v) ? v : [v])
+            redactedValues.push(part);
+        delete safeQuery[key];
+    }
+    const scrub = (s) => redactedValues.reduce(scrubValueFromPath, s);
+    if (typeof filtered.path === "string")
+        filtered.path = scrub(filtered.path);
+    if (typeof filtered.pathname === "string")
+        filtered.pathname = scrub(filtered.pathname);
+    if ("params" in filtered)
+        filtered.params = safeParams;
+    if ("query" in filtered)
+        filtered.query = safeQuery;
+    emit({ type: "state_snapshot", componentId: ROUTE_ID, state: filtered, timestamp: Date.now(), keyframe: true }, ROUTE_NAME);
+};
+/** Replace every occurrence of a raw redacted value in the URL string with `[redacted]`. */
+const scrubValueFromPath = (path, value) => {
+    if (value === "")
+        return path;
+    const candidates = new Set([value, encodeURIComponent(value)]);
+    let out = path;
+    for (const c of candidates) {
+        if (c === "")
+            continue;
+        out = out.split(c).join("[redacted]");
+    }
+    return out;
+};
+/**
+ * Enable/configure session recording (Replay spec §5). `enabled` defaults to
+ * `false` — keep it off in production unless behind a sampling flag or a
+ * "report a bug" action. v1.5 adds the recording controls: exclusion
+ * (`excludeActions`/`excludeComponents`/`includeStateKeys`), coalescing
+ * (`coalesceMs`), session sampling (`sample`), and the per-second rate guard
+ * (`maxEventsPerSecond` → `gap` events).
+ */
+export const configureReplay = (opts) => {
+    // §5 v1.5: allowlist and blocklist snapshot modes are mutually exclusive —
+    // both NON-EMPTY is a config error (explicit empty arrays are fine).
+    if ((opts.redactKeys?.length ?? 0) > 0 && (opts.includeStateKeys?.length ?? 0) > 0) {
+        throw new Error(`[reactra:replay] configureReplay: \`redactKeys\` (blocklist) and \`includeStateKeys\` ` +
+            `(allowlist) are mutually exclusive — set one or the other. (Replay §5 v1.5.)`);
+    }
+    config = {
+        enabled: opts.enabled ?? DEFAULT_CONFIG.enabled,
+        redactKeys: opts.redactKeys ?? DEFAULT_CONFIG.redactKeys,
+        maxEvents: opts.maxEvents ?? DEFAULT_CONFIG.maxEvents,
+        sink: opts.sink,
+        excludeActions: opts.excludeActions ?? DEFAULT_CONFIG.excludeActions,
+        excludeComponents: opts.excludeComponents ?? DEFAULT_CONFIG.excludeComponents,
+        includeStateKeys: opts.includeStateKeys ?? DEFAULT_CONFIG.includeStateKeys,
+        coalesceMs: opts.coalesceMs ?? DEFAULT_CONFIG.coalesceMs,
+        sample: opts.sample ?? DEFAULT_CONFIG.sample,
+        maxEventsPerSecond: opts.maxEventsPerSecond ?? DEFAULT_CONFIG.maxEventsPerSecond,
+        keyframeEvery: opts.keyframeEvery ?? DEFAULT_CONFIG.keyframeEvery,
+        meta: opts.meta,
+    };
+    // Reconfiguring starts a fresh session — a bundle that straddled a config
+    // change (e.g. redaction toggled mid-stream) would be inconsistent. Any
+    // pending coalesced pairs belong to the old generation: DISCARD them
+    // (cancel timers) rather than flush into the fresh session.
+    discardAllPendings();
+    session = null;
+    // §5: the warn-once sets (PII + sink error) are per configuration generation,
+    // and replay mode resets too (configureReplay's reset-everything semantics).
+    warnedPIIKeys = new Set();
+    warnedSinkError = false;
+    warnedSetterDriftKeys = new Set();
+    replayMode = false;
+    // Install/uninstall the route tap (§5). Only own the global while enabled;
+    // never clobber a receiver another consumer installed.
+    if (config.enabled) {
+        routeGlobal.__REACTRA_REPLAY_ROUTE__ = receiveRoute;
+    }
+    else if (routeGlobal.__REACTRA_REPLAY_ROUTE__ === receiveRoute) {
+        delete routeGlobal.__REACTRA_REPLAY_ROUTE__;
+    }
+};
+const liveInstances = new Map();
+let replayMode = false;
+/**
+ * Suspend recording while a replay is being driven (§5). Without the gate,
+ * driving setters would pollute a session with feedback events — the driven
+ * state fires the per-resource status effects. Explicit pair: the mode
+ * outlives a single drive call while the user scrubs.
+ */
+export const enterReplayMode = () => {
+    replayMode = true;
+};
+/** Resume recording after a replay drive (§5). */
+export const exitReplayMode = () => {
+    replayMode = false;
+};
+/**
+ * Streamed-mode ring trimming (§5 v1.6 — Stage R2). The TRANSPORT calls this
+ * with a durability watermark when the server acks: events at or below the
+ * watermark are dropped from the local ring, EXCEPT the newest keyframe per
+ * instance ≤ the watermark is retained as the local fold-start. An instance
+ * with no keyframe at/below the watermark keeps its oldest in-ring keyframe
+ * (above it) untrimmed naturally — its tail-start (C2). `finalizeReplay()`
+ * afterwards returns the TAIL bundle; the server is the durable store. The
+ * runtime stays ack-agnostic: this is a timestamp, never protocol detail.
+ */
+export const acknowledgeReplay = (uptoTimestamp) => {
+    if (session === null)
+        return;
+    const s = session;
+    const live = s.events.slice(s.head);
+    // Newest keyframe ≤ watermark, per instance.
+    const retain = new Map();
+    for (const e of live) {
+        if (e.timestamp > uptoTimestamp)
+            break;
+        if (e.type === "state_snapshot" && e.keyframe)
+            retain.set(e.componentId, e);
+    }
+    const kept = [...retain.values()];
+    for (const e of live) {
+        if (e.timestamp > uptoTimestamp)
+            kept.push(e);
+    }
+    s.events = kept;
+    s.head = 0;
+};
+/**
+ * Drive every currently mounted instance of `componentName` to `state` through
+ * its registered setters (§5). Keys without a registered setter are ignored
+ * (cross-version bundles degrade gracefully); React 19 auto-batches the set
+ * calls into one re-render. Returns the number of instances driven.
+ *
+ * Per-key setter-drift warn (B4 §5): when a MOUNTED instance has no setter for
+ * a bundle key, the key silently won't re-drive — the recorded session is from a
+ * different component shape (renamed/removed `state`). We surface that per (component,
+ * key) once per session, dev-only. The whole-component zero-drive case is already
+ * surfaced by the caller via the returned count (timeTravel.ts), so this catches the
+ * partial-drift case: the component drives but a SUBSET of its keys have no setter.
+ */
+export const applyReplayState = (state, componentName) => {
+    let driven = 0;
+    for (const inst of liveInstances.values()) {
+        if (inst.componentName !== componentName)
+            continue;
+        for (const [key, value] of Object.entries(state)) {
+            const setter = inst.setters[key];
+            if (setter)
+                setter(value);
+            else
+                warnSetterDrift(componentName, key);
+        }
+        driven++;
+    }
+    return driven;
+};
+/**
+ * True only in a CONFIRMED production build. Bundlers (Vite/webpack) statically
+ * replace the `process.env.NODE_ENV` literal at build time, so we reference that
+ * literal directly — a browser bundle has no runtime `process`, and a
+ * `typeof process` guard (the prior form) stays a runtime check that resolves to
+ * "undefined" in the browser, which silently suppressed the warn in the exact
+ * environment replay re-drive runs in. The try/catch covers a bundler that
+ * leaves the literal un-replaced (no `process` global): treat unknown as
+ * non-production so the dev signal is emitted rather than swallowed.
+ */
+const isProductionEnv = () => {
+    try {
+        return process.env.NODE_ENV === "production";
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Dev-gated, warn-once-per-(component,key)-per-session signal that a re-drive key
+ * has no registered setter on a mounted instance (B4 §5). Suppressed only in a
+ * confirmed production build (see {@link isProductionEnv}) so it surfaces in dev
+ * AND in the browser dev bundle (where replay re-drive actually runs). Resets
+ * with the session in `configureReplay` (per-configuration generation). Plain
+ * `console.warn` — no error-code prefix (matches the DVT001/DVT005 warn style).
+ */
+const warnSetterDrift = (componentName, key) => {
+    if (isProductionEnv())
+        return;
+    const id = `${componentName}.${key}`;
+    if (warnedSetterDriftKeys.has(id))
+        return;
+    warnedSetterDriftKeys.add(id);
+    console.warn(`[reactra:replay] applyReplayState: "${componentName}" has no setter for key "${key}" — ` +
+        `the recorded session is from a different component shape (renamed/removed state). ` +
+        `That key will not re-drive. (Replay spec §5.)`);
+};
+let warnedSetterDriftKeys = new Set();
+let warnedSinkError = false;
+/** Swallow a sink failure — a broken transport must not break the app or the recording (§5). */
+const guardSink = (fn) => {
+    try {
+        fn();
+    }
+    catch (err) {
+        if (warnedSinkError)
+            return;
+        warnedSinkError = true;
+        console.warn(`[reactra:replay] the configured sink threw — events are still recorded locally, but the ` +
+            `transport is broken (warned once per configureReplay): ${String(err)}`);
+    }
+};
+// ---------------------------------------------------------------------------
+// PII-convention warning (§5/§11 — runtime, warn-once). Segment-equality
+// matching: `cardNumber` → ["card","number"] warns; `cardinality` does not.
+// The list is shared with RLIM-01's planned Phase-2 auto-redact.
+// ---------------------------------------------------------------------------
+const PII_SEGMENTS = ["password", "token", "secret", "card", "ssn", "cvv"];
+/** Split a field name on underscores + camelCase boundaries, lowercased (§5). */
+const nameSegments = (name) => name
+    .split(/[_\s-]+|(?=[A-Z])/)
+    .map((s) => s.toLowerCase())
+    .filter((s) => s.length > 0);
+const looksLikePII = (key) => nameSegments(key).some((seg) => PII_SEGMENTS.includes(seg));
+let warnedPIIKeys = new Set();
+/**
+ * Warn once per offending key when a recorded snapshot carries a field whose
+ * name segment-matches the PII convention list (§5). Runs on the post-redaction
+ * object, so a `redactKeys` field never reaches it.
+ */
+const warnUnredactedPII = (state) => {
+    for (const key of Object.keys(state)) {
+        if (warnedPIIKeys.has(key) || !looksLikePII(key))
+            continue;
+        warnedPIIKeys.add(key);
+        console.warn(`[reactra:replay] BHV005: state field "${key}" looks like PII (segment match against ` +
+            `[${PII_SEGMENTS.join(", ")}]) but is not in redactKeys — it is being recorded. ` +
+            `Add it to configureReplay({ redactKeys: [...] }) to drop it from snapshots. (Replay §5/§11.)`);
+    }
+};
+let session = null;
+/**
+ * Pending coalesced-pair flushers, one per channel holding a pair (§5 v1.5
+ * `coalesceMs`). `finalizeReplay` flushes them synchronously (C1a);
+ * `configureReplay` discards them (a fresh generation).
+ */
+const pendingFlushes = new Map(); // flush -> discard
+const flushAllPendings = () => {
+    for (const flush of [...pendingFlushes.keys()])
+        flush();
+};
+const discardAllPendings = () => {
+    for (const discard of [...pendingFlushes.values()])
+        discard();
+    pendingFlushes.clear();
+};
+/** Monotonic per-component-name instance counter — mints the `Name#N` ids (§4.3 rule 1). */
+const instanceCounts = new Map();
+const mintInstanceId = (componentName) => {
+    const next = (instanceCounts.get(componentName) ?? 0) + 1;
+    instanceCounts.set(componentName, next);
+    return `${componentName}#${next}`;
+};
+const mintSessionId = () => `ses_${Math.random().toString(36).slice(2, 11)}`;
+/** Lazily start a session on the first emit while enabled (the first `mount()` in practice). */
+const ensureSession = () => {
+    if (session === null) {
+        session = {
+            startTime: Date.now(),
+            sessionId: mintSessionId(),
+            events: [],
+            head: 0,
+            components: new Set(),
+            lastAction: new Map(),
+            // §5 v1.5: session-level sampling, decided exactly once per session.
+            sampled: config.sample >= 1 || Math.random() < config.sample,
+            rate: { epoch: -1, count: 0, dropped: 0, droppedBy: "" },
+            meta: config.meta,
+        };
+    }
+    return session;
+};
+/**
+ * The recording gate shared by the emit path and the coalescing accumulator
+ * (§5 v1.5 C1b: a sampled-out session must never accumulate pending pairs or
+ * timers). Returns the live session, or null when nothing should record.
+ */
+const recordingSession = () => {
+    if (!config.enabled || replayMode)
+        return null;
+    const s = ensureSession();
+    return s.sampled ? s : null;
+};
+/** Ring push with O(1) drop-oldest (head index + periodic compaction). */
+const pushRing = (s, event) => {
+    s.events.push(event);
+    if (s.events.length - s.head > config.maxEvents)
+        s.head++;
+    // Compact once the dead prefix dominates — amortized O(1) per push.
+    if (s.head > 1024 && s.head * 2 > s.events.length) {
+        s.events = s.events.slice(s.head);
+        s.head = 0;
+    }
+};
+/** Push an event when recording is enabled; ring-cap to `maxEvents` (drop oldest). No-op when disabled, replay-driving, or sampled out (§5). */
+const emit = (event, componentName) => {
+    const s = recordingSession();
+    if (s === null)
+        return false;
+    // §5 v1.5 rate guard — fixed-epoch per-second budget (C5). `gap` markers
+    // themselves never consume budget.
+    if (config.maxEventsPerSecond > 0 && event.type !== "gap") {
+        const epoch = Math.floor(event.timestamp / 1000);
+        if (epoch !== s.rate.epoch) {
+            if (s.rate.dropped > 0) {
+                emit({ type: "gap", componentId: s.rate.droppedBy, dropped: s.rate.dropped, timestamp: event.timestamp }, componentName);
+            }
+            s.rate.epoch = epoch;
+            s.rate.count = 0;
+            s.rate.dropped = 0;
+        }
+        if (s.rate.count >= config.maxEventsPerSecond) {
+            s.rate.dropped++;
+            s.rate.droppedBy = "componentId" in event ? event.componentId : "";
+            return false;
+        }
+        s.rate.count++;
+    }
+    // Both snapshot paths (channel + useReplayCapture) funnel through here with
+    // an already-filtered object — surviving keys are by definition recorded.
+    if (event.type === "state_snapshot")
+        warnUnredactedPII(event.state);
+    s.components.add(componentName);
+    pushRing(s, event);
+    // §5 sink tap (v1.3): synchronous, post-redaction, after the ring push.
+    // Session identity is stable for the whole session — the transport's
+    // boundary signal is a CHANGED sessionId, not a callback. (v1.5: a
+    // COALESCED pair reaches here only at its flush — the documented deferred-
+    // delivery carve-out.)
+    if (config.sink) {
+        const sink = config.sink;
+        guardSink(() => sink.event(event, { sessionId: s.sessionId, startTime: s.startTime, meta: s.meta }));
+    }
+    return true;
+};
+/**
+ * Snapshot filtering (§3/§5): allowlist mode records ONLY `includeStateKeys`;
+ * otherwise blocklist mode drops `redactKeys`. The two are mutually exclusive
+ * by configureReplay's guard.
+ */
+const filterState = (state) => {
+    if (config.includeStateKeys.length > 0) {
+        const out = {};
+        for (const k of config.includeStateKeys) {
+            if (k in state)
+                out[k] = state[k];
+        }
+        return out;
+    }
+    if (config.redactKeys.length === 0)
+        return state;
+    const out = {};
+    for (const [k, v] of Object.entries(state)) {
+        if (!config.redactKeys.includes(k))
+            out[k] = v;
+    }
+    return out;
+};
+const makeChannel = (componentId, componentName) => {
+    // §5 v1.5 recording controls — per-instance state. `excludedPending` marks
+    // "the next snapshot belongs to an excluded action, skip it"; `pending`
+    // holds at most one coalesced action+snapshot pair.
+    let excludedPending = false;
+    let pending = null;
+    // §5 v1.6 deltas — the per-instance diff base (the last RECORDED state) and
+    // the per-session snapshot count for keyframe minting. Reset on session
+    // change (a delta against a previous session's state would be wrong).
+    let deltaBase = null;
+    let snapshotCount = 0;
+    let deltaSessionId = null;
+    let txCount = 0; // per-instance command-transaction counter (txId minting)
+    // Exclusion is checked AT CALL TIME (config may change between renders).
+    const componentExcluded = () => config.excludeComponents.includes(componentName);
+    /**
+     * Record a committed FULL filtered snapshot as a keyframe or a delta (§3
+     * v1.6). The diff base advances ONLY when the event actually records —
+     * a rate-guard drop leaves the base untouched, so the dropped change is
+     * absorbed into the NEXT delta instead of lost.
+     */
+    const emitSnapshot = (full, timestamp) => {
+        const s = recordingSession();
+        if (s === null)
+            return;
+        if (s.sessionId !== deltaSessionId) {
+            deltaBase = null;
+            snapshotCount = 0;
+            deltaSessionId = s.sessionId;
+        }
+        const isKeyframe = deltaBase === null || snapshotCount % config.keyframeEvery === 0;
+        let event;
+        if (isKeyframe) {
+            event = { type: "state_snapshot", componentId, state: full, timestamp, keyframe: true };
+        }
+        else {
+            // Shallow !== — immutable updates always produce new references; errs
+            // toward recording MORE, never less (§3 v1.6).
+            const delta = {};
+            for (const [k, v] of Object.entries(full)) {
+                if (deltaBase[k] !== v)
+                    delta[k] = v;
+            }
+            if (Object.keys(delta).length === 0)
+                return; // nothing changed — record nothing
+            event = { type: "state_snapshot", componentId, state: delta, timestamp };
+        }
+        if (emit(event, componentName)) {
+            deltaBase = full;
+            snapshotCount++;
+        }
+    };
+    const discardPending = () => {
+        if (pending === null)
+            return;
+        clearTimeout(pending.timer);
+        pending = null;
+        pendingFlushes.delete(flushPending);
+    };
+    /** Commit the held pair — in order, through the fully-gated emit path. */
+    const flushPending = () => {
+        if (pending === null)
+            return;
+        const { action, snapshot } = pending;
+        discardPending();
+        emit(action, componentName);
+        if (snapshot)
+            emitSnapshot(snapshot.state, snapshot.timestamp);
+    };
+    return {
+        mount(setters) {
+            // Live-drive registration (§5 v1.4) happens regardless of the recording
+            // gate AND of recording exclusion — exclusion governs recording, not
+            // playback (§5 v1.5).
+            if (setters)
+                liveInstances.set(componentId, { componentName, setters });
+            if (componentExcluded())
+                return;
+            flushPending(); // a real event boundary breaks any coalescing window
+            emit({ type: "mount", componentId, phase: "mount", timestamp: Date.now() }, componentName);
+        },
+        unmount() {
+            liveInstances.delete(componentId);
+            if (componentExcluded())
+                return;
+            flushPending();
+            emit({ type: "mount", componentId, phase: "unmount", timestamp: Date.now() }, componentName);
+        },
+        action(name, payload, writes) {
+            if (componentExcluded())
+                return;
+            // The exclusion mark clears at the start of every action — pure actions
+            // have no trailing snapshot to consume it (§5 v1.5).
+            excludedPending = false;
+            if (config.excludeActions.includes(name)) {
+                // C2a: an excluded action is still an event BOUNDARY — flush any
+                // pending coalesced pair first, then record nothing for itself.
+                flushPending();
+                excludedPending = true;
+                return;
+            }
+            // Payload redaction (§5): blocklist hit, OR — in allowlist mode — a
+            // write-set DISJOINT from the allowlist (every non-listed key is treated
+            // as redacted on BOTH surfaces, v1.5). Whole-payload replacement: params
+            // can't be soundly mapped to the fields they flow into.
+            const allowlist = config.includeStateKeys;
+            const redact = writes !== undefined &&
+                (writes.some((w) => config.redactKeys.includes(w)) ||
+                    (allowlist.length > 0 && !writes.some((w) => allowlist.includes(w))));
+            const event = {
+                type: "action",
+                name,
+                payload: redact ? ["[redacted]"] : payload,
+                ...(redact ? { payloadRedacted: true } : {}),
+                componentId,
+                timestamp: Date.now(),
+                duration: 0,
+            };
+            if (config.coalesceMs > 0) {
+                // C1b: never accumulate for a disabled / replay-mode / sampled-out
+                // session — the same gate emit() applies.
+                if (recordingSession() === null)
+                    return;
+                if (pending !== null &&
+                    pending.action.name === name &&
+                    event.timestamp - pending.action.timestamp <= config.coalesceMs) {
+                    // Same-(instance, action) burst: keep the LAST occurrence.
+                    clearTimeout(pending.timer);
+                    pending.action = event;
+                    pending.snapshot = undefined;
+                    pending.timer = setTimeout(flushPending, config.coalesceMs);
+                    return;
+                }
+                flushPending();
+                pending = { action: event, timer: setTimeout(flushPending, config.coalesceMs) };
+                pendingFlushes.set(flushPending, discardPending);
+                return;
+            }
+            emit(event, componentName);
+            // Remember it so the post-body `snapshot(_, t0)` can fill the real duration.
+            if (config.enabled && session !== null)
+                session.lastAction.set(componentId, event);
+        },
+        snapshot(state, t0) {
+            if (componentExcluded())
+                return;
+            if (excludedPending) {
+                // The paired snapshot of an excluded action — consume and skip.
+                excludedPending = false;
+                return;
+            }
+            const filtered = filterState(state);
+            if (pending !== null) {
+                // The held pair's snapshot — replaces any earlier one in the window.
+                // Stored as FULL filtered state; delta conversion happens at commit.
+                pending.action.duration = performance.now() - t0;
+                pending.snapshot = { state: filtered, timestamp: Date.now() };
+                return;
+            }
+            const last = session?.lastAction.get(componentId);
+            if (last)
+                last.duration = performance.now() - t0;
+            emitSnapshot(filtered, Date.now());
+        },
+        resource(name, status) {
+            if (componentExcluded())
+                return;
+            flushPending(); // event boundary
+            emit({ type: "resource", name, status, componentId, timestamp: Date.now() }, componentName);
+        },
+        begin(name, payload, _base) {
+            // Excluded component: a no-op transaction (recording off, drive still works).
+            if (componentExcluded()) {
+                return { mark() { }, commit() { }, rollback() { } };
+            }
+            flushPending(); // event boundary (like resource)
+            const txId = `${componentId}~c${++txCount}`;
+            // Record the command invocation. (Payload redaction for `command` is a
+            // future refinement — the settled STATE is PII-filtered below regardless.)
+            emit({ type: "action", name, payload, componentId, timestamp: Date.now(), duration: 0 }, componentName);
+            const txMark = (phase, state) => {
+                emit({ type: "tx_mark", componentId, txId, phase, state: filterState(state), timestamp: Date.now() }, componentName);
+            };
+            return {
+                // optimistic apply: a NON-FOLDING tx_mark only — never a state_snapshot,
+                // so statesAt can never return the optimistic transient.
+                mark(state) {
+                    txMark("optimistic", state);
+                },
+                // settle success: the committed marker + the real (foldable) snapshot.
+                commit(state) {
+                    txMark("committed", state);
+                    emitSnapshot(filterState(state), Date.now());
+                },
+                // settle failure: the rolled-back marker + a snapshot at base. When base
+                // equals the last recorded state the delta is empty → emitSnapshot records
+                // nothing (correct: a failed transaction adds no committed stop).
+                rollback(state) {
+                    txMark("rolledback", state);
+                    emitSnapshot(filterState(state), Date.now());
+                },
+            };
+        },
+    };
+};
+/**
+ * Create a replay channel bound to a freshly-minted `Name#N` instance id — the
+ * non-hook primitive `useReplayChannel` wraps. Useful for imperative/non-React
+ * contexts and for testing the recording pieces without a renderer.
+ */
+export const createReplayChannel = (componentName) => makeChannel(mintInstanceId(componentName), componentName);
+/**
+ * Bind a per-instance replay channel (Replay spec §4.1). The compiler emits
+ * `const __replay = useReplayChannel("<ComponentName>")`; the runtime mints the
+ * stable `Name#N` instance id (the compiler never emits the instance suffix —
+ * §4.3 rule 1). The channel is created once per mounted instance (`useRef`), so
+ * the mount/unmount `useEffect` (emitted with `[]` deps) captures a stable handle.
+ */
+export const useReplayChannel = (componentName) => {
+    const ref = useRef(null);
+    if (ref.current === null)
+        ref.current = createReplayChannel(componentName);
+    return ref.current;
+};
+/**
+ * Finalize the active session into a `SessionBundle` for upload/inspection
+ * (Replay spec §2/§5), then end it. Returns `null` when recording is disabled or
+ * no session was started — the documented "disabled = no bundle" contract
+ * (§8, RP-05). User-callable from `cleanup { … }` or a "report a bug" handler.
+ */
+export const finalizeReplay = async () => {
+    // §5 v1.5 C1a: synchronously flush + cancel every pending coalesced pair
+    // BEFORE building the bundle, so a burst followed by an immediate finalize
+    // loses nothing.
+    flushAllPendings();
+    if (!config.enabled || session === null)
+        return null;
+    const s = session;
+    session = null;
+    // §5 v1.5 `sample`: a sampled-out session recorded nothing — the existing
+    // "disabled = no bundle" shape (RP-05).
+    if (!s.sampled)
+        return null;
+    const bundle = {
+        version: "2.1",
+        mode: "state-snapshot",
+        startTime: s.startTime,
+        duration: Date.now() - s.startTime,
+        sessionId: s.sessionId,
+        components: [...s.components],
+        events: s.head > 0 ? s.events.slice(s.head) : s.events,
+    };
+    // §5 sink tap (v1.3): the transport's end-of-session signal. Recording
+    // semantics are unchanged — the bundle is still returned to the caller.
+    if (config.sink?.finalize) {
+        const sink = config.sink;
+        guardSink(() => sink.finalize?.(bundle));
+    }
+    return bundle;
+};
+/**
+ * Register plain-React state (held outside the DSL) with the active session so
+ * it appears in snapshots (Replay spec §6). Ordinary user-called hook code built
+ * from `useEffect` — emits a `state_snapshot` of the non-redacted fields whenever
+ * a captured value changes (no-op while recording is disabled). Fields marked
+ * `redact` (or matching `redactKeys`) are excluded.
+ */
+export const useReplayCapture = (fields) => {
+    const ref = useRef(null);
+    if (ref.current === null)
+        ref.current = mintInstanceId("PlainReact");
+    const componentId = ref.current;
+    useEffect(() => {
+        if (!config.enabled)
+            return;
+        const state = {};
+        for (const f of fields) {
+            if (f.redact || config.redactKeys.includes(f.name))
+                continue;
+            state[f.name] = f.value;
+        }
+        emit({ type: "state_snapshot", componentId, state: filterState(state), timestamp: Date.now(), keyframe: true }, "PlainReact");
+    }, 
+    // Re-emit when any captured value changes (the standard interop pattern).
+    fields.map((f) => f.value));
+};
+/**
+ * Identity HOF kept for type-level `uses` resolution. `uses replayable` is
+ * compiler-native (inner-body emission — Replay spec §4), so this wrapper is NOT
+ * applied to the component; the real runtime is `useReplayChannel` above.
+ */
+export const replayable = (component) => component;
+export default replayable;
+//# sourceMappingURL=replayable.js.map