@loopcheck/qa-sdk 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# QA SDK architecture
+
+```
+CUSTOMER APP
+     │
+     ▼
+┌──────────────┐
+│  QA SDK      │
+│              │
+│ Element ID   │
+│ Recording    │
+│ Metadata     │
+└──────┬───────┘
+       │
+       ▼
+Recording API  →  Automation IR  →  Source Resolver  →  ID injection PR
+```
+
+## Package layout
+
+| Module | Responsibility |
+|---|---|
+| `core` | `QAClient`, event bus, lifecycle |
+| `identity` | explicit IDs, a11y, fingerprints, duplicates |
+| `instrumentation` | delegated events, MutationObserver, SPA navigation |
+| `recorder` | session + semantic normalization |
+| `privacy` | redaction / sensitive-field detection |
+| `transport` | HTTP, batching, bounded offline retry |
+| `react` | `QAProvider`, `useQA`, `useQAElement` |
+
+The runtime is framework-agnostic. React is an adapter. Vue/Angular can call `new QAClient(config)` later.
+
+## Identity resolution order
+
+1. explicit `data-qa-id`
+2. SDK-stamped metadata (`useQAElement`)
+3. accessibility name/role
+4. semantic HTML
+5. stable attributes (`name`, `type`, non-React `id`)
+6. `data-qa-source` (compiler-injected)
+7. deterministic fingerprint
+
+## Compiler boundary
+
+A future `@loopcheck/qa-sdk-instrumentation` plugin may inject:
+
+```html
+<button data-qa-source="src/checkout/Checkout.tsx:42">
+```
+
+The runtime only **reads** that attribute. It does not depend on source maps or React internals.
+
+## Conflicts with this repo
+
+- Loopcheck already uses pnpm workspaces + Turbo + `@loopcheck/*`. The SDK follows that; it is **not** `@company/qa-sdk`.
+- The API uses Jest; this package uses Vitest + Playwright because it is a browser SDK.
+- The Loopcheck web app is the **platform**, not the customer app. The example lives under `packages/qa-sdk/example` so the dashboard is not instrumented by default.
+- No privileged env vars are read. Recording ingest is `POST /v1/sdk/events`. Publishable-key session create is `POST /v1/sdk/sessions`.
+- Durable keys are `lc_pk_…` (`PUBLISHABLE`). One-shot extension tokens remain `lc_pub_…` (`SESSION`) and are revoked when that recording stops.

package/README.md

@@ -0,0 +1,131 @@
+# @loopcheck/qa-sdk
+
+Browser instrumentation for Loopcheck. The SDK answers two questions:
+
+1. **What did the user interact with?**
+2. **How do we identify that element stably?**
+
+It does **not** generate Playwright tests — that belongs to the Loopcheck automation engine.
+
+## Installation
+
+```bash
+pnpm add @loopcheck/qa-sdk
+```
+
+Peer dependency: `react` >= 18 (only if you use `@loopcheck/qa-sdk/react`).
+
+## Quick start (publishable key)
+
+1. In Loopcheck → **Project settings** → **Publishable keys**, create a key (`lc_pk_…`).
+2. Wrap your app. The SDK stays **inert** until you call `startRecording()` (safe behind a login wall).
+
+```tsx
+"use client";
+
+import { QAProvider, useQA } from "@loopcheck/qa-sdk/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QAProvider
+      config={{
+        apiUrl: "https://api.loopcheck.dev", // your Loopcheck API origin
+        publishableKey: process.env.NEXT_PUBLIC_LOOPCHECK_KEY!,
+        // default: inert until startRecording()
+        startOn: "manual",
+      }}
+    >
+      {children}
+    </QAProvider>
+  );
+}
+
+function RecordToolbar() {
+  const { startRecording, stopRecording, isRecording } = useQA();
+  return (
+    <button
+      type="button"
+      onClick={() => void (isRecording ? stopRecording() : startRecording())}
+    >
+      {isRecording ? "Stop" : "Record"}
+    </button>
+  );
+}
+```
+
+`startRecording()`:
+
+1. `POST /v1/sdk/sessions` with the publishable key (no Loopcheck login cookie).
+2. Attaches listeners and posts events to `/v1/sdk/events`.
+
+### Auth gate
+
+Keep the provider mounted for all visitors. Call `startRecording()` only after the user is logged into **your** app (or from an internal QA toolbar). Until then the SDK does not attach listeners or make network calls.
+
+To arm from the URL instead:
+
+```tsx
+<QAProvider
+  config={{
+    apiUrl: "https://api.loopcheck.dev",
+    publishableKey: process.env.NEXT_PUBLIC_LOOPCHECK_KEY!,
+    startOn: "query", // starts when ?lc_record=1
+  }}
+>
+```
+
+## Configuration
+
+| Field | Default | Purpose |
+|---|---|---|
+| `publishableKey` | — | Durable browser key (`lc_pk_…`) from project settings |
+| `apiUrl` | `""` | Loopcheck API origin |
+| `projectId` | resolved on session create | Optional; filled from the key response |
+| `sessionId` | — | Pre-minted session (extension / dashboard flow) |
+| `publicClientToken` | — | Alias / legacy session token (`lc_pub_…`) |
+| `startOn` | `manual` | `manual` \| `query` (`?lc_record=1`) |
+| `enabled` | `true` | Master switch |
+| `mode` | inert for key-only installs | `disabled` \| `observe` \| `record` |
+| `debug` | `false` | Inspector overlay (Alt+Shift+hover) |
+| `recordInputValues` | `false` | Values are `[REDACTED]` unless true **and** not sensitive |
+| `transport` | HTTP | Replaceable `QATransport` |
+
+All config is passed explicitly. The SDK never reads `DATABASE_URL`, `SESSION_SECRET`, or other server secrets.
+
+## React helpers
+
+```tsx
+import { QAProvider, useQA, useQAElement, QAButton } from "@loopcheck/qa-sdk/react";
+
+function CheckoutButton() {
+  const ref = useQAElement("checkout.continue");
+  return <button ref={ref}>Continue</button>;
+}
+```
+
+Or stamp the DOM yourself:
+
+```html
+<button data-qa-id="checkout.continue">Continue</button>
+```
+
+## Privacy
+
+Always redacted: passwords, `data-qa-sensitive`, card/CVV-like fields, and `redactSelectors`. Fetch uses `credentials: "omit"`. Cookies and authorization headers are never collected.
+
+## Extension / dashboard recording
+
+The Chrome extension and Loopcheck record UI still mint one-shot `lc_pub_…` session tokens via `recordings.create`. That path is unchanged. Prefer publishable keys for embedding the SDK in a customer app.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Empty recordings | Call `startRecording()` after login, or set `startOn: "query"` with `?lc_record=1` |
+| `401` on session create | Check the publishable key and optional origin allowlist |
+| Hydration warnings | Keep `QAProvider` in a Client Component |
+| Network errors in console | Swallowed by default; use `onError` |
+
+## License
+
+Proprietary — UNLICENSED. Not open source.

package/dist/config/normalize.d.ts

@@ -0,0 +1,6 @@
+import { type QAConfig, type QAMode, type QAStartOn, type ResolvedQAConfig } from '../types';
+export declare function findPrivilegedConfigKeys(config: QAConfig): string[];
+export declare function normalizeConfig(input: QAConfig): ResolvedQAConfig;
+export declare function effectiveMode(config: ResolvedQAConfig): QAMode;
+export declare function shouldArmFromQuery(startOn: QAStartOn): boolean;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/config/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/config/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,UAAU,CAAC;AAYlB,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAOnE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,gBAAgB,CAgDjE;AAcD,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAK9D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAS9D"}

package/dist/config/normalize.js

@@ -0,0 +1,88 @@
+import { DEFAULT_INTERACTIVE_SELECTORS, } from '../types';
+const FORBIDDEN_CONFIG_KEYS = new Set([
+    'DATABASE_URL',
+    'SECRET_KEY',
+    'AUTH_SECRET',
+    'PRIVATE_API_KEY',
+    'GITHUB_APP_PRIVATE_KEY',
+    'ENCRYPTION_MASTER_KEY',
+    'SESSION_SECRET',
+]);
+export function findPrivilegedConfigKeys(config) {
+    return Object.keys(config).filter((key) => {
+        if (key === 'publicClientToken' || key === 'publishableKey') {
+            return false;
+        }
+        return FORBIDDEN_CONFIG_KEYS.has(key) || /secret|private.?key|password/i.test(key);
+    });
+}
+export function normalizeConfig(input) {
+    const enabled = input.enabled !== false;
+    const environment = input.environment ?? 'development';
+    const publishableKey = input.publishableKey ?? undefined;
+    const publicClientToken = input.publicClientToken ?? publishableKey;
+    const startOn = input.startOn ?? 'manual';
+    const hasSession = Boolean(input.sessionId);
+    const keyedWithoutSession = Boolean(publicClientToken) && !hasSession;
+    // Publishable-key installs stay inert until startRecording() / ?lc_record=1.
+    // Extension / dashboard bootstraps pass sessionId + mode: 'record'.
+    let defaultMode;
+    if (keyedWithoutSession && input.mode === undefined) {
+        defaultMode = 'disabled';
+    }
+    else if (environment.toLowerCase() === 'production') {
+        defaultMode = 'disabled';
+    }
+    else {
+        defaultMode = 'observe';
+    }
+    const mode = !enabled ? 'disabled' : (input.mode ?? defaultMode);
+    const extraSelectors = (input.interactiveSelectors ?? []).filter((selector) => typeof selector === 'string' && selector.trim().length > 0);
+    return {
+        projectId: input.projectId ?? '',
+        sessionId: input.sessionId,
+        environment,
+        apiUrl: input.apiUrl ?? '',
+        publishableKey,
+        publicClientToken,
+        enabled,
+        mode,
+        startOn,
+        debug: Boolean(input.debug),
+        interactiveSelectors: Array.from(new Set([...DEFAULT_INTERACTIVE_SELECTORS, ...extraSelectors])),
+        redactSelectors: (input.redactSelectors ?? []).filter(Boolean),
+        allowUnstableIds: Boolean(input.allowUnstableIds),
+        recordHover: Boolean(input.recordHover),
+        recordInputValues: Boolean(input.recordInputValues),
+        flushIntervalMs: clampNumber(input.flushIntervalMs, 250, 5000, 500),
+        maxBatchSize: clampNumber(input.maxBatchSize, 1, 100, 25),
+        maxQueueSize: clampNumber(input.maxQueueSize, 20, 500, 200),
+        maxStorageBytes: clampNumber(input.maxStorageBytes, 4_096, 64_000, 32_000),
+        transport: input.transport,
+        onError: input.onError,
+    };
+}
+function clampNumber(value, min, max, fallback) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, value));
+}
+export function effectiveMode(config) {
+    if (!config.enabled) {
+        return 'disabled';
+    }
+    return config.mode;
+}
+export function shouldArmFromQuery(startOn) {
+    if (startOn !== 'query' || typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        return new URLSearchParams(window.location.search).get('lc_record') === '1';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=normalize.js.map

package/dist/config/normalize.js.map

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

package/dist/core/QAClient.d.ts

@@ -0,0 +1,53 @@
+import type { QAClientEventMap, QAConfig, QAElementResolution, QAListener, QARecording, ResolvedQAConfig } from '../types';
+export interface QASnapshot {
+    isRecording: boolean;
+    isPaused: boolean;
+    mode: ResolvedQAConfig['mode'];
+}
+export declare class QAClient {
+    readonly config: ResolvedQAConfig;
+    private readonly bus;
+    private readonly subscribers;
+    private session;
+    private registry;
+    private observer;
+    private delegator;
+    private navigation;
+    private queue;
+    private normalizer;
+    private started;
+    private snapshot;
+    private prefillTimer;
+    private prefillRaf;
+    private sessionBootstrap;
+    private queryArmed;
+    constructor(input: QAConfig);
+    start(): void;
+    /**
+     * Call after mount for publishable-key installs with `startOn: "query"`.
+     * Arms when the URL contains `?lc_record=1`.
+     */
+    maybeArmFromQuery(): void;
+    shutdown(): Promise<void>;
+    startRecording(): Promise<void>;
+    /** Synchronous arming once a session (or local transport) is ready. */
+    private beginRecording;
+    stopRecording(): QARecording | null;
+    pauseRecording(): void;
+    resumeRecording(): void;
+    get isRecording(): boolean;
+    get isPaused(): boolean;
+    resolveElement(element: Element): QAElementResolution;
+    on<K extends keyof QAClientEventMap>(event: K, listener: QAListener<QAClientEventMap[K]>): () => void;
+    subscribe: (onStoreChange: () => void) => (() => void);
+    getSnapshot: () => QASnapshot;
+    static getServerSnapshot: () => QASnapshot;
+    private attachInstrumentation;
+    private ensureSession;
+    private schedulePrefillHarvest;
+    private clearPrefillHarvest;
+    private emitEvent;
+    private setSnapshot;
+    private report;
+}
+//# sourceMappingURL=QAClient.d.ts.map

package/dist/core/QAClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QAClient.d.ts","sourceRoot":"","sources":["../../src/core/QAClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,mBAAmB,EAEnB,UAAU,EACV,WAAW,EACX,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAqBlB,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CAChC;AAQD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,UAAU,CAAS;gBAEf,KAAK,EAAE,QAAQ;IAgB3B,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAQnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBzB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC,uEAAuE;IACvE,OAAO,CAAC,cAAc;IAiCtB,aAAa,IAAI,WAAW,GAAG,IAAI;IAqBnC,cAAc,IAAI,IAAI;IAQtB,eAAe,IAAI,IAAI;IAQvB,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB;IAOrD,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACjC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,IAAI;IAIb,SAAS,GAAI,eAAe,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAKnD;IAEF,WAAW,QAAO,UAAU,CAAkB;IAE9C,MAAM,CAAC,iBAAiB,QAAO,UAAU,CAAkB;IAE3D,OAAO,CAAC,qBAAqB;YAsDf,aAAa;IAyC3B,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,MAAM;CAOf"}

package/dist/core/QAClient.js

@@ -0,0 +1,318 @@
+import { effectiveMode, findPrivilegedConfigKeys, normalizeConfig, shouldArmFromQuery, } from '../config/normalize';
+import { QAEventBus } from './QAEventBus';
+import { ElementRegistry } from '../instrumentation/ElementRegistry';
+import { DOMObserver } from '../instrumentation/DOMObserver';
+import { EventDelegator } from '../instrumentation/EventDelegator';
+import { NavigationObserver } from '../instrumentation/NavigationObserver';
+import { EventNormalizer, RecordingSession, buildEvent } from '../recorder/EventNormalizer';
+import { BatchQueue } from '../transport/BatchQueue';
+import { createSdkSession } from '../transport/HTTPTransport';
+import { isBrowser } from '../utils/id';
+import { asQAError, swallow } from '../utils/safe';
+import { attachDebugger, detachDebugger } from '../debug/Debugger';
+import { resolveElement } from '../identity/ElementResolver';
+import { PREFILL_HARVEST_MS } from '../instrumentation/FormHarvest';
+const IDLE_SNAPSHOT = {
+    isRecording: false,
+    isPaused: false,
+    mode: 'disabled',
+};
+export class QAClient {
+    config;
+    bus = new QAEventBus();
+    subscribers = new Set();
+    session = null;
+    registry = null;
+    observer = null;
+    delegator = null;
+    navigation = null;
+    queue = null;
+    normalizer = null;
+    started = false;
+    snapshot = IDLE_SNAPSHOT;
+    prefillTimer;
+    prefillRaf;
+    sessionBootstrap = null;
+    queryArmed = false;
+    constructor(input) {
+        const privileged = findPrivilegedConfigKeys(input);
+        this.config = normalizeConfig(input);
+        if (privileged.length > 0) {
+            this.report({
+                name: 'QAConfigError',
+                message: `Ignored privileged config keys: ${privileged.join(', ')}`,
+            });
+        }
+        this.snapshot = {
+            isRecording: false,
+            isPaused: false,
+            mode: effectiveMode(this.config),
+        };
+    }
+    start() {
+        swallow(() => {
+            if (this.started || !isBrowser() || effectiveMode(this.config) === 'disabled') {
+                return;
+            }
+            this.attachInstrumentation();
+            if (this.config.mode === 'record') {
+                void this.beginRecording();
+            }
+        }, (error) => this.report(error));
+    }
+    /**
+     * Call after mount for publishable-key installs with `startOn: "query"`.
+     * Arms when the URL contains `?lc_record=1`.
+     */
+    maybeArmFromQuery() {
+        if (this.queryArmed || !shouldArmFromQuery(this.config.startOn)) {
+            return;
+        }
+        this.queryArmed = true;
+        void this.startRecording();
+    }
+    async shutdown() {
+        this.clearPrefillHarvest();
+        this.normalizer?.dispose();
+        this.delegator?.stop();
+        this.observer?.stop();
+        this.navigation?.stop();
+        detachDebugger();
+        await this.queue?.shutdown();
+        this.started = false;
+        this.registry = null;
+        this.observer = null;
+        this.delegator = null;
+        this.navigation = null;
+        this.queue = null;
+        this.normalizer = null;
+    }
+    async startRecording() {
+        try {
+            if (!isBrowser() || this.config.enabled === false) {
+                return;
+            }
+            await this.ensureSession();
+            this.beginRecording();
+        }
+        catch (error) {
+            this.report(asQAError(error));
+        }
+    }
+    /** Synchronous arming once a session (or local transport) is ready. */
+    beginRecording() {
+        swallow(() => {
+            if (!isBrowser() || this.config.enabled === false) {
+                return;
+            }
+            this.config.mode = 'record';
+            this.config.enabled = true;
+            if (!this.started) {
+                this.attachInstrumentation();
+            }
+            if (this.session && !this.session.recording.endedAt) {
+                this.session.resume();
+                this.setSnapshot({ isRecording: true, isPaused: false, mode: 'record' });
+                this.bus.emit('recording:resume', null);
+                return;
+            }
+            this.session = new RecordingSession(window.location.href);
+            this.setSnapshot({ isRecording: true, isPaused: false, mode: 'record' });
+            this.bus.emit('recording:start', this.session.recording);
+            this.emitEvent(buildEvent('navigation', {
+                page: {
+                    url: window.location.href,
+                    pathname: window.location.pathname || '/',
+                    title: document.title || undefined,
+                },
+            }));
+            this.schedulePrefillHarvest();
+        }, (error) => this.report(error));
+    }
+    stopRecording() {
+        let result = null;
+        swallow(() => {
+            this.clearPrefillHarvest();
+            this.delegator?.harvestPrefills('prefilled');
+            this.normalizer?.flushInput();
+            if (!this.session) {
+                return;
+            }
+            result = this.session.stop();
+            this.session = null;
+            this.setSnapshot({
+                isRecording: false,
+                isPaused: false,
+                mode: this.config.mode === 'record' ? 'observe' : this.config.mode,
+            });
+            this.bus.emit('recording:stop', result);
+        }, (error) => this.report(error));
+        return result;
+    }
+    pauseRecording() {
+        swallow(() => {
+            this.session?.pause();
+            this.setSnapshot({ isPaused: true });
+            this.bus.emit('recording:pause', null);
+        }, (error) => this.report(error));
+    }
+    resumeRecording() {
+        swallow(() => {
+            this.session?.resume();
+            this.setSnapshot({ isPaused: false });
+            this.bus.emit('recording:resume', null);
+        }, (error) => this.report(error));
+    }
+    get isRecording() {
+        return this.snapshot.isRecording;
+    }
+    get isPaused() {
+        return this.snapshot.isPaused;
+    }
+    resolveElement(element) {
+        if (!this.registry) {
+            return resolveElement(element, { allowUnstableIds: this.config.allowUnstableIds });
+        }
+        return this.registry.resolve(element);
+    }
+    on(event, listener) {
+        return this.bus.on(event, listener);
+    }
+    subscribe = (onStoreChange) => {
+        this.subscribers.add(onStoreChange);
+        return () => {
+            this.subscribers.delete(onStoreChange);
+        };
+    };
+    getSnapshot = () => this.snapshot;
+    static getServerSnapshot = () => IDLE_SNAPSHOT;
+    attachInstrumentation() {
+        if (this.started || !isBrowser()) {
+            return;
+        }
+        this.started = true;
+        this.registry = new ElementRegistry(this.config, (hits) => {
+            for (const hit of hits) {
+                this.bus.emit('duplicate-id', hit);
+                if (this.config.debug || this.config.environment !== 'production') {
+                    console.warn(`Duplicate QA ID detected:\n${hit.qaId}\nElements:\n${hit.sources.map((source, index) => `${index + 1}. ${source}`).join('\n')}`);
+                }
+            }
+        }, (resolution) => this.bus.emit('element:resolved', resolution));
+        this.observer = new DOMObserver(this.config, this.registry);
+        this.observer.start(document);
+        this.navigation = new NavigationObserver((url, pathname) => {
+            this.normalizer?.flushInput();
+            this.emitEvent(buildEvent('navigation', {
+                page: { url, pathname, title: document.title || undefined },
+            }));
+            void this.queue?.flush();
+        });
+        this.navigation.start();
+        this.normalizer = new EventNormalizer((partial) => {
+            this.emitEvent(buildEvent(partial.type, {
+                target: partial.target,
+                metadata: partial.metadata,
+                page: partial.page,
+            }));
+        });
+        this.delegator = new EventDelegator(this.config, this.registry, this.normalizer, () => this.isRecording && !this.isPaused);
+        this.delegator.start();
+        this.queue = new BatchQueue(this.config);
+        this.queue.start();
+        if (this.config.debug) {
+            attachDebugger(this);
+        }
+    }
+    async ensureSession() {
+        if (this.config.sessionId) {
+            return;
+        }
+        const key = this.config.publishableKey ?? this.config.publicClientToken;
+        if (!key) {
+            // Local / memory transport path — no remote session required.
+            return;
+        }
+        if (!this.config.apiUrl) {
+            throw new Error('apiUrl is required to create a recording session');
+        }
+        if (!this.sessionBootstrap) {
+            this.sessionBootstrap = (async () => {
+                const created = await createSdkSession({
+                    apiUrl: this.config.apiUrl,
+                    publishableKey: key,
+                    initialUrl: window.location.href,
+                    projectId: this.config.projectId || undefined,
+                });
+                this.config.sessionId = created.sessionId;
+                this.config.projectId = created.projectId;
+                if (created.apiUrl) {
+                    this.config.apiUrl = created.apiUrl;
+                }
+                this.queue?.updateSession({
+                    sessionId: created.sessionId,
+                    projectId: created.projectId,
+                    apiUrl: this.config.apiUrl,
+                    publicClientToken: key,
+                });
+            })();
+        }
+        try {
+            await this.sessionBootstrap;
+        }
+        catch (error) {
+            this.sessionBootstrap = null;
+            throw error;
+        }
+    }
+    schedulePrefillHarvest() {
+        this.clearPrefillHarvest();
+        const run = () => {
+            this.prefillTimer = setTimeout(() => {
+                this.prefillTimer = undefined;
+                this.delegator?.harvestPrefills('prefilled');
+            }, PREFILL_HARVEST_MS);
+        };
+        if (typeof requestAnimationFrame === 'function') {
+            this.prefillRaf = requestAnimationFrame(() => {
+                this.prefillRaf = undefined;
+                run();
+            });
+        }
+        else {
+            run();
+        }
+    }
+    clearPrefillHarvest() {
+        if (this.prefillRaf !== undefined && typeof cancelAnimationFrame === 'function') {
+            cancelAnimationFrame(this.prefillRaf);
+            this.prefillRaf = undefined;
+        }
+        if (this.prefillTimer) {
+            clearTimeout(this.prefillTimer);
+            this.prefillTimer = undefined;
+        }
+    }
+    emitEvent(event) {
+        if (!this.snapshot.isRecording || this.snapshot.isPaused) {
+            return;
+        }
+        this.session?.push(event);
+        this.bus.emit('event', event);
+        this.queue?.enqueue(event);
+    }
+    setSnapshot(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const subscriber of this.subscribers) {
+            subscriber();
+        }
+    }
+    report(error) {
+        this.config.onError?.(error);
+        this.bus.emit('error', error);
+        if (this.config.debug) {
+            console.warn('[loopcheck-qa]', error.message);
+        }
+    }
+}
+//# sourceMappingURL=QAClient.js.map