@lunardinos/browser 0.2.0

package/dist/src/persistence.d.ts

@@ -0,0 +1,16 @@
+export type PersistenceMode = "cookie" | "cookieless";
+export interface PersistenceAdapter {
+    getVisitorId(): string | null;
+    getSessionId(): string | null;
+    setVisitorId(id: string): void;
+    setSessionId(id: string): void;
+    /** Touch the session cookie to extend its rolling expiry. */
+    touchSession(): void;
+    /** Delete all persisted state (cookies/storage). */
+    clear(): void;
+    readonly mode: PersistenceMode;
+}
+export declare function createCookiePersistence(): PersistenceAdapter;
+export declare function createCookielessPersistence(): PersistenceAdapter;
+export declare function createPersistence(mode: PersistenceMode): PersistenceAdapter;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/src/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,YAAY,CAAA;AAErD,MAAM,WAAW,kBAAkB;IACjC,YAAY,IAAI,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,IAAI,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,6DAA6D;IAC7D,YAAY,IAAI,IAAI,CAAA;IACpB,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAAA;IACb,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAC/B;AA6BD,wBAAgB,uBAAuB,IAAI,kBAAkB,CA8B5D;AAID,wBAAgB,2BAA2B,IAAI,kBAAkB,CAUhE;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB,CAE3E"}

package/dist/src/persistence.js

@@ -0,0 +1,62 @@
+// ── Cookie helpers ──────────────────────────────────────────────────
+const VISITOR_COOKIE = "__ld_vid";
+const SESSION_COOKIE = "__ld_sid";
+/** 1 year in seconds */
+const VISITOR_MAX_AGE = 365 * 24 * 60 * 60;
+/** 30 minutes in seconds */
+const SESSION_MAX_AGE = 30 * 60;
+function getCookie(name) {
+    const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+    return match?.[1] ? decodeURIComponent(match[1]) : null;
+}
+function setCookie(name, value, maxAge) {
+    // biome-ignore lint/suspicious/noDocumentCookie: intentional cookie API usage for session tracking
+    document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=${maxAge};SameSite=Lax`;
+}
+function deleteCookie(name) {
+    // biome-ignore lint/suspicious/noDocumentCookie: intentional cookie API usage for session tracking
+    document.cookie = `${name}=;path=/;max-age=0;SameSite=Lax`;
+}
+// ── Cookie Persistence ──────────────────────────────────────────────
+export function createCookiePersistence() {
+    return {
+        mode: "cookie",
+        getVisitorId() {
+            return getCookie(VISITOR_COOKIE);
+        },
+        getSessionId() {
+            return getCookie(SESSION_COOKIE);
+        },
+        setVisitorId(id) {
+            setCookie(VISITOR_COOKIE, id, VISITOR_MAX_AGE);
+        },
+        setSessionId(id) {
+            setCookie(SESSION_COOKIE, id, SESSION_MAX_AGE);
+        },
+        touchSession() {
+            const sid = getCookie(SESSION_COOKIE);
+            if (sid)
+                setCookie(SESSION_COOKIE, sid, SESSION_MAX_AGE);
+        },
+        clear() {
+            deleteCookie(VISITOR_COOKIE);
+            deleteCookie(SESSION_COOKIE);
+        },
+    };
+}
+// ── Cookieless Persistence (no-op, in-memory only) ──────────────────
+export function createCookielessPersistence() {
+    return {
+        mode: "cookieless",
+        getVisitorId: () => null,
+        getSessionId: () => null,
+        setVisitorId: () => { },
+        setSessionId: () => { },
+        touchSession: () => { },
+        clear: () => { },
+    };
+}
+// ── Factory ─────────────────────────────────────────────────────────
+export function createPersistence(mode) {
+    return mode === "cookie" ? createCookiePersistence() : createCookielessPersistence();
+}

package/dist/src/recorder-core.d.ts

@@ -0,0 +1,72 @@
+import { type PersistenceMode } from "./persistence";
+export type { PersistenceMode } from "./persistence";
+interface RecorderConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Ingestion endpoint (defaults to https://ingest.lunardinos.com) */
+    endpoint?: string;
+    /** rrweb record options (inlineStylesheet, inlineImages, etc.) */
+    rrwebOptions?: Record<string, unknown>;
+    /** Batching interval in ms (default 2000) */
+    batchInterval?: number;
+    /** Initial persistence mode: 'cookie' (default) or 'cookieless'. Can be changed at runtime via setPersistence(). */
+    defaultPersistence?: PersistenceMode;
+}
+interface PageEventPayload {
+    href: string;
+    title: string;
+    routePattern: string | null;
+    params: Record<string, string> | null;
+    referrer?: string | null;
+}
+export interface IdentifyPayload {
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+        role?: string;
+        [key: string]: unknown;
+    };
+    account?: {
+        id: string;
+        name?: string;
+        onboarded?: boolean;
+        [key: string]: unknown;
+    };
+    plan?: {
+        id: string;
+        name?: string;
+        [key: string]: unknown;
+    };
+}
+export interface StartOptions {
+    sessionId?: string;
+    /** Page metadata to attach to the initial snapshot (avoids a separate emitPageEvent call). */
+    pageMetadata?: PageEventPayload;
+}
+export interface Recorder {
+    start: (options?: string | StartOptions) => string;
+    stop: () => void;
+    /** Flush buffered events. Pass `{ beacon: true }` during page unload for reliable delivery. */
+    flush: (options?: {
+        beacon?: boolean;
+    }) => void;
+    getSessionId: () => string | null;
+    getVisitorId: () => string | null;
+    isRecording: () => boolean;
+    /** Emit a page event with route metadata (called by the SDK, not internally). */
+    emitPageEvent: (payload: PageEventPayload) => void;
+    /** Tag the current session with account/user identity for B2B analytics. */
+    identify: (payload: IdentifyPayload) => void;
+    /** Switch persistence mode at runtime (for cookie consent integration). */
+    setPersistence: (mode: PersistenceMode) => void;
+}
+/**
+ * Creates a recorder instance that wraps rrweb's `record()`.
+ *
+ * Handles event buffering and batching. Navigation detection is delegated
+ * to the framework SDK (e.g. recorder-next). Trigger attribution is done
+ * server-side by correlating click events with page views.
+ */
+export declare function createLunarDinosRecorder(config: RecorderConfig): Recorder;
+//# sourceMappingURL=recorder-core.d.ts.map

package/dist/src/recorder-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder-core.d.ts","sourceRoot":"","sources":["../../src/recorder-core.ts"],"names":[],"mappings":"AACA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAEhG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAIpD,UAAU,cAAc;IACtB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oHAAoH;IACpH,kBAAkB,CAAC,EAAE,eAAe,CAAA;CACrC;AA4BD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,OAAO,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAuCD,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,gBAAgB,CAAA;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,KAAK,MAAM,CAAA;IAClD,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,+FAA+F;IAC/F,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/C,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,WAAW,EAAE,MAAM,OAAO,CAAA;IAC1B,iFAAiF;IACjF,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAClD,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC5C,2EAA2E;IAC3E,cAAc,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;CAChD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA0bzE"}

package/dist/src/recorder-core.js

@@ -0,0 +1,470 @@
+import record from "@lunardinos/rrweb-record";
+import { createPersistence } from "./persistence";
+const DEFAULT_ENDPOINT = "https://ingest.lunardinos.com";
+/** Compress a string via the CompressionStream API (gzip). Returns null if unavailable or on error. */
+async function gzipCompress(input) {
+    try {
+        if (typeof CompressionStream === "undefined")
+            return null;
+        const blob = new Blob([input]);
+        const stream = blob.stream().pipeThrough(new CompressionStream("gzip"));
+        return await new Response(stream).blob();
+    }
+    catch {
+        return null;
+    }
+}
+const INTERACTIVE_TAGS = new Set(["a", "button", "input", "select", "textarea"]);
+/** Walk up the DOM to find the nearest interactive ancestor (or the target itself). */
+function findInteractiveElement(target) {
+    let el = target;
+    while (el && el !== document.body) {
+        if (INTERACTIVE_TAGS.has(el.tagName.toLowerCase()) || el.getAttribute("role")) {
+            return el;
+        }
+        el = el.parentElement;
+    }
+    return target;
+}
+/** Get direct/shallow text content, avoiding concatenation of all descendant text. */
+function getDirectText(el) {
+    const text = el.innerText?.trim().slice(0, 80);
+    return text || null;
+}
+/** Truncate text to a reasonable label length. */
+function truncateText(text) {
+    if (!text)
+        return null;
+    return text.length > 40 ? `${text.slice(0, 37)}...` : text;
+}
+/** Extract UTM parameters from the current URL. */
+function extractUtmParams() {
+    const params = new URLSearchParams(window.location.search);
+    const utm = {};
+    for (const key of ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"]) {
+        const val = params.get(key);
+        if (val)
+            utm[key] = val;
+    }
+    return utm;
+}
+/**
+ * Creates a recorder instance that wraps rrweb's `record()`.
+ *
+ * Handles event buffering and batching. Navigation detection is delegated
+ * to the framework SDK (e.g. recorder-next). Trigger attribution is done
+ * server-side by correlating click events with page views.
+ */
+export function createLunarDinosRecorder(config) {
+    const { apiKey, endpoint = DEFAULT_ENDPOINT, rrwebOptions = {}, batchInterval = 2000 } = config;
+    // Always inline images so they display correctly in replay (the replay
+    // iframe is on a different origin and can't fetch original URLs).
+    const defaultRrwebOptions = {
+        inlineImages: true,
+    };
+    const url = `${endpoint}/api/events`;
+    let persistence = createPersistence(config.defaultPersistence ?? "cookie");
+    /** Build the beacon URL with auth + mode encoded as query params. */
+    function beaconUrl() {
+        const u = new URL(url);
+        u.searchParams.set("key", apiKey);
+        if (persistence.mode === "cookieless")
+            u.searchParams.set("cookieless", "1");
+        return u.toString();
+    }
+    function send(body, headers) {
+        const reqHeaders = {
+            ...headers,
+            Authorization: `Bearer ${apiKey}`,
+        };
+        // Signal cookieless mode to the server so it can generate server-side identity
+        if (persistence.mode === "cookieless") {
+            reqHeaders["X-LD-Cookieless"] = "1";
+        }
+        fetch(url, {
+            method: "POST",
+            headers: reqHeaders,
+            body,
+        }).catch(() => { });
+    }
+    /** Send via navigator.sendBeacon — reliable during page unload, no custom headers. */
+    function sendViaBeacon(json) {
+        try {
+            // Use text/plain to avoid CORS preflight during page unload.
+            // application/json triggers an OPTIONS preflight that the browser may not
+            // complete before the page is torn down, causing silent delivery failure.
+            const blob = new Blob([json], { type: "text/plain" });
+            const sent = navigator.sendBeacon(beaconUrl(), blob);
+            if (sent)
+                return;
+            // sendBeacon rejected (payload too large) — fall through to fetch+keepalive
+        }
+        catch {
+            // sendBeacon threw — fall through to fetch+keepalive
+        }
+        // Fallback: try fetch with keepalive
+        try {
+            fetch(beaconUrl(), {
+                method: "POST",
+                body: json,
+                headers: { "Content-Type": "application/json" },
+                keepalive: true,
+            }).catch(() => { });
+        }
+        catch {
+            /* truly lost — accept it */
+        }
+    }
+    let events = [];
+    let sessionId = null;
+    let visitorId = null;
+    let stopFn = null;
+    let intervalId = null;
+    let recording = false;
+    // Click enrichment state
+    let pendingClickContext = null;
+    // Input enrichment state
+    let pendingInputContext = null;
+    /** Capture form submit events for analytics. */
+    function captureSubmit(e) {
+        if (!recording)
+            return;
+        const form = e.target;
+        const formName = form.getAttribute("name") ??
+            form.getAttribute("id") ??
+            form.getAttribute("aria-label") ??
+            null;
+        const formAction = form.getAttribute("action") ?? null;
+        try {
+            record.addCustomEvent("submit", { formName, formAction });
+        }
+        catch {
+            /* not recording yet */
+        }
+    }
+    /** Capture tag/name from input/select/textarea elements for analytics. */
+    function captureInputContext(e) {
+        const el = e.target;
+        const tag = el.tagName?.toLowerCase();
+        if (tag !== "input" && tag !== "select" && tag !== "textarea")
+            return;
+        const inputEl = el;
+        const inputName = inputEl.getAttribute("name") ??
+            inputEl.getAttribute("id") ??
+            inputEl.getAttribute("aria-label") ??
+            (tag !== "select" ? inputEl.getAttribute("placeholder") : null) ??
+            (() => {
+                const id = inputEl.id;
+                if (id) {
+                    const label = document.querySelector(`label[for="${id}"]`);
+                    if (label)
+                        return truncateText(label.textContent?.trim() ?? null);
+                }
+                const parentLabel = inputEl.closest("label");
+                return truncateText(parentLabel?.textContent?.trim() ?? null);
+            })() ??
+            null;
+        pendingInputContext = { inputTag: tag, inputName };
+    }
+    /** Capture tag/role/name from clicked element for analytics. */
+    function captureClickContext(e) {
+        const raw = e.target;
+        const clicked = findInteractiveElement(raw);
+        const tag = clicked.tagName?.toLowerCase() ?? "unknown";
+        const TAG_ROLES = {
+            button: "button",
+            a: "link",
+            input: "textbox",
+            select: "combobox",
+            textarea: "textbox",
+        };
+        const role = clicked.getAttribute("role") ?? TAG_ROLES[tag] ?? null;
+        const name = clicked.getAttribute("aria-label") ??
+            clicked.getAttribute("name") ??
+            clicked.getAttribute("title") ??
+            truncateText(getDirectText(clicked)) ??
+            clicked.querySelector("[aria-label]")?.getAttribute("aria-label") ??
+            null;
+        const href = tag === "a"
+            ? clicked.getAttribute("href")
+            : (clicked.closest("a")?.getAttribute("href") ?? null);
+        pendingClickContext = { clickTag: tag, clickRole: role, clickName: name, clickHref: href };
+    }
+    function flush(options) {
+        if (events.length === 0 || !sessionId)
+            return;
+        const batch = events.splice(0);
+        const id = sessionId;
+        const vid = visitorId;
+        const payload = { sessionId: id, events: batch };
+        if (vid)
+            payload.visitorId = vid;
+        const json = JSON.stringify(payload);
+        // Extend rolling session cookie on each flush
+        persistence.touchSession();
+        // During page unload (beforeunload / MPA navigation), use sendBeacon
+        // for guaranteed delivery. No async compression — page may tear down.
+        if (options?.beacon) {
+            sendViaBeacon(json);
+            return;
+        }
+        // Normal flush: try async gzip compression, fall back to uncompressed.
+        gzipCompress(json).then((compressed) => {
+            if (compressed && compressed.size < json.length) {
+                send(compressed, {
+                    "Content-Type": "application/json",
+                    "Content-Encoding": "gzip",
+                });
+            }
+            else {
+                send(json, { "Content-Type": "application/json" });
+            }
+        });
+    }
+    function identify(payload) {
+        if (!recording)
+            return;
+        try {
+            record.addCustomEvent("identify", payload);
+        }
+        catch {
+            /* not recording yet */
+        }
+        flush();
+    }
+    function emitPageEvent(payload) {
+        if (!recording)
+            return;
+        try {
+            // Single Pageview event carries both DOM snapshot and route metadata
+            record.takePageviewSnapshot({
+                href: payload.href,
+                title: payload.title,
+                routePattern: payload.routePattern ?? undefined,
+                params: payload.params,
+                referrer: payload.referrer ?? externalReferrer(),
+            });
+        }
+        catch {
+            /* recorder may not be fully initialized yet */
+        }
+    }
+    /** Capture unhandled JS errors for analytics. */
+    function captureError(e) {
+        if (!recording)
+            return;
+        try {
+            record.addCustomEvent("error", {
+                message: e.message ?? "Unknown error",
+                source: e.filename ?? null,
+            });
+        }
+        catch {
+            /* not recording yet */
+        }
+    }
+    /** Capture unhandled promise rejections for analytics. */
+    function captureRejection(e) {
+        if (!recording)
+            return;
+        try {
+            const message = e.reason instanceof Error ? e.reason.message : String(e.reason ?? "Unhandled rejection");
+            record.addCustomEvent("error", {
+                message,
+                source: null,
+            });
+        }
+        catch {
+            /* not recording yet */
+        }
+    }
+    /** Return the external referrer, or null if it's same-origin (internal navigation). */
+    function externalReferrer() {
+        const ref = document.referrer;
+        if (!ref)
+            return null;
+        try {
+            return new URL(ref).origin === window.location.origin ? null : ref;
+        }
+        catch {
+            return ref;
+        }
+    }
+    /** Emit a session:meta event with referrer and UTM params (once per session start). */
+    function emitSessionMeta() {
+        try {
+            const utm = extractUtmParams();
+            record.addCustomEvent("session:meta", {
+                referrer: externalReferrer(),
+                landingPage: window.location.pathname,
+                ...utm,
+            });
+        }
+        catch {
+            /* not recording yet */
+        }
+    }
+    function start(optionsOrSessionId) {
+        if (recording)
+            return sessionId;
+        const startOpts = typeof optionsOrSessionId === "string"
+            ? { sessionId: optionsOrSessionId }
+            : (optionsOrSessionId ?? {});
+        const existingSessionId = startOpts.sessionId;
+        // Resolve session ID.
+        // Cookie mode: persisted cookie > sessionStorage (MPA fallback) > provided arg > new UUID
+        // Cookieless mode: always a fresh per-page-load ID (no client storage = consent-free)
+        const SESSION_STORAGE_KEY = "__ld_sid";
+        let isNewSession = false;
+        if (persistence.mode === "cookie") {
+            const persistedSession = persistence.getSessionId();
+            const storedSession = typeof sessionStorage !== "undefined" ? sessionStorage.getItem(SESSION_STORAGE_KEY) : null;
+            isNewSession = !persistedSession && !storedSession;
+            sessionId = persistedSession || storedSession || existingSessionId || crypto.randomUUID();
+            persistence.setSessionId(sessionId);
+            if (typeof sessionStorage !== "undefined") {
+                sessionStorage.setItem(SESSION_STORAGE_KEY, sessionId);
+            }
+        }
+        else {
+            // Cookieless: each page load is an independent recording.
+            // The server stitches page recordings into sessions using visitor hash + referrer + timing.
+            sessionId = existingSessionId || crypto.randomUUID();
+        }
+        // Resolve visitor ID from cookie (only set in cookie mode)
+        visitorId = persistence.getVisitorId();
+        if (!visitorId && persistence.mode === "cookie") {
+            visitorId = crypto.randomUUID();
+            persistence.setVisitorId(visitorId);
+        }
+        events = [];
+        recording = true;
+        // Listen for clicks/inputs in capture phase to grab context before rrweb sees it
+        document.addEventListener("click", captureClickContext, true);
+        document.addEventListener("input", captureInputContext, true);
+        document.addEventListener("change", captureInputContext, true);
+        document.addEventListener("submit", captureSubmit, true);
+        window.addEventListener("error", captureError);
+        window.addEventListener("unhandledrejection", captureRejection);
+        stopFn = record({
+            ...defaultRrwebOptions,
+            ...rrwebOptions,
+            initialPageMetadata: startOpts.pageMetadata
+                ? {
+                    href: startOpts.pageMetadata.href,
+                    title: startOpts.pageMetadata.title,
+                    routePattern: startOpts.pageMetadata.routePattern ?? undefined,
+                    params: startOpts.pageMetadata.params,
+                    referrer: startOpts.pageMetadata.referrer ?? undefined,
+                }
+                : undefined,
+            emit(event) {
+                const ev = event;
+                // Attach click context to rrweb click events
+                if (ev.type === 3 && ev.data?.source === 2 && ev.data?.type === 2 && pendingClickContext) {
+                    const d = ev.data;
+                    d.clickTag = pendingClickContext.clickTag;
+                    d.clickRole = pendingClickContext.clickRole;
+                    d.clickName = pendingClickContext.clickName;
+                    d.clickHref = pendingClickContext.clickHref;
+                    pendingClickContext = null;
+                }
+                // Attach input context to rrweb input events (type=3, source=5)
+                if (ev.type === 3 && ev.data?.source === 5 && pendingInputContext) {
+                    const d = ev.data;
+                    d.inputTag = pendingInputContext.inputTag;
+                    d.inputName = pendingInputContext.inputName;
+                    pendingInputContext = null;
+                }
+                events.push(event);
+            },
+        });
+        // Emit session metadata (referrer, UTM).
+        // In cookieless mode: every page load is a new recording, always emit.
+        // In cookie mode: only for genuinely new sessions (not MPA reloads with existing session).
+        if (persistence.mode === "cookieless" || isNewSession) {
+            emitSessionMeta();
+        }
+        // Flush immediately so the pageview snapshot (which can exceed sendBeacon's
+        // ~64 KB limit) is delivered via regular fetch before the user navigates away.
+        flush();
+        intervalId = setInterval(flush, batchInterval);
+        return sessionId;
+    }
+    function stop() {
+        if (!recording)
+            return;
+        document.removeEventListener("click", captureClickContext, true);
+        document.removeEventListener("input", captureInputContext, true);
+        document.removeEventListener("change", captureInputContext, true);
+        document.removeEventListener("submit", captureSubmit, true);
+        window.removeEventListener("error", captureError);
+        window.removeEventListener("unhandledrejection", captureRejection);
+        try {
+            record.addCustomEvent("session:end", {});
+        }
+        catch {
+            /* not recording */
+        }
+        flush();
+        if (intervalId) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+        stopFn?.();
+        stopFn = null;
+        recording = false;
+        sessionId = null;
+        visitorId = null;
+        events = [];
+        pendingClickContext = null;
+        pendingInputContext = null;
+    }
+    function setPersistence(mode) {
+        const oldMode = persistence.mode;
+        if (oldMode === mode)
+            return;
+        if (oldMode === "cookieless" && mode === "cookie") {
+            // Transitioning from cookieless → cookie: generate cookie-based visitor ID
+            // and emit a link event so the server can merge the server-hash identity
+            persistence.clear();
+            persistence = createPersistence("cookie");
+            const newVisitorId = crypto.randomUUID();
+            persistence.setVisitorId(newVisitorId);
+            if (sessionId)
+                persistence.setSessionId(sessionId);
+            const oldVisitorId = visitorId;
+            visitorId = newVisitorId;
+            // Tell the server to link the old (server-generated) identity to the new cookie identity
+            if (recording && oldVisitorId !== newVisitorId) {
+                try {
+                    record.addCustomEvent("visitor:link", {
+                        previousVisitorId: oldVisitorId,
+                        newVisitorId,
+                    });
+                }
+                catch {
+                    /* not recording */
+                }
+            }
+        }
+        else if (oldMode === "cookie" && mode === "cookieless") {
+            // Transitioning from cookie → cookieless: delete cookies, keep in-memory session
+            persistence.clear();
+            persistence = createPersistence("cookieless");
+            // visitorId becomes null — server will assign hash-based ID
+            visitorId = null;
+        }
+    }
+    return {
+        start,
+        stop,
+        flush,
+        getSessionId: () => sessionId,
+        getVisitorId: () => visitorId,
+        isRecording: () => recording,
+        emitPageEvent,
+        identify,
+        setPersistence,
+    };
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lunardinos/browser",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/recorder-core.js",
+      "types": "./dist/src/recorder-core.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/recorder-core.ts --outdir dist --format esm --external react && rm -f dist/*.css && bunx tsc -b tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@lunardinos/rrweb-record": "0.1.0"
+  }
+}