@vitrinka/web 0.1.0

package/build/recorder/session.js

@@ -0,0 +1,246 @@
+import { api, fetchPolicy, permanentStatus, VitrinkaApiError } from './api';
+import { setRedactionPolicy } from './capture/redact';
+import { recorderConfig } from './config';
+import { armReconcile, capturesSettled, disarmReconcile, drainBuffer, getState, pushEvent, queuedCount, resetHealth, resetIdle, resetQueues, setState, } from './queue';
+import { currentRoute, notify } from './state';
+export { currentRoute, notify, subscribe } from './state';
+/** Sent as `meta.recorder`; bumped with the package version. */
+export const RECORDER_VERSION = '0.1.0';
+export const RECORDER_ID = `web/${RECORDER_VERSION}`;
+/**
+ * Re-apply a RECOVERED session's redaction policy after a reload — and
+ * re-FETCH it when the original fetch never settled (`policy === undefined`).
+ */
+let policyRecoveryInFlight = false;
+export function recoverRedactionPolicy() {
+    const rec = getState();
+    if (!rec)
+        return;
+    setRedactionPolicy(rec.policy ?? null);
+    if (rec.policy !== undefined)
+        return;
+    if (policyRecoveryInFlight)
+        return;
+    policyRecoveryInFlight = true;
+    void fetchPolicy()
+        .then((policy) => {
+        const live = getState();
+        if (live?.sessionId !== rec.sessionId)
+            return;
+        if (live.policy !== undefined)
+            return;
+        setRedactionPolicy(policy);
+        setState({ ...live, policy });
+    })
+        .finally(() => {
+        policyRecoveryInFlight = false;
+    });
+}
+export function elapsedOf(rec) {
+    if (!rec)
+        return 0;
+    let ms = rec.activeMs || 0;
+    if (!rec.paused && rec.resumeAt)
+        ms += Date.now() - Date.parse(rec.resumeAt);
+    return ms;
+}
+/** The document's host — the create's `host`, the same field the extension sends. */
+function pageHost() {
+    try {
+        return globalThis.location?.host ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+export async function startSession(opts = {}) {
+    const cfg = recorderConfig();
+    // The safe defaults apply from the first captured byte; the workspace
+    // policy (fetched in parallel — fetchPolicy never rejects) can only ADD
+    // rules or, self-host only, fullFidelity.
+    setRedactionPolicy(null);
+    const policyPromise = fetchPolicy();
+    const environment = opts.environment ?? cfg.environment;
+    const ses = await api('POST', '/api/v1/sessions', {
+        host: pageHost(),
+        title: opts.title || '',
+        ...(environment ? { environment } : {}),
+        meta: {
+            recorder: RECORDER_ID,
+            userAgent: globalThis.navigator?.userAgent ?? '',
+            platform: 'web',
+            ...(cfg.appVersion ? { appVersion: cfg.appVersion } : {}),
+            ...(opts.driver ? { driver: opts.driver } : {}),
+        },
+    });
+    void policyPromise.then((policy) => {
+        const rec = getState();
+        if (rec?.sessionId !== ses.id)
+            return;
+        setRedactionPolicy(policy);
+        setState({ ...rec, policy });
+    });
+    setState({
+        sessionId: ses.id,
+        project: ses.project,
+        environment: ses.environment,
+        title: ses.title,
+        ...(ses.boardUrl ? { boardUrl: ses.boardUrl } : {}),
+        seq: 0,
+        paused: false,
+        activeMs: 0,
+        resumeAt: new Date().toISOString(),
+    });
+    resetQueues();
+    resetHealth();
+    resetIdle();
+    await attachTags(ses.id, opts.tags);
+    armReconcile();
+    pushEvent('nav', { url: currentUrl(), route: currentRoute.pathname }, { tabId: currentRoute.tabId, tabHost: currentRoute.tabHost });
+    notify();
+    return getState();
+}
+function currentUrl() {
+    try {
+        return globalThis.location?.href ?? currentRoute.pathname;
+    }
+    catch {
+        return currentRoute.pathname;
+    }
+}
+async function attachTags(sessionId, tags) {
+    if (!tags?.length)
+        return;
+    try {
+        await api('POST', `/api/v1/sessions/${sessionId}/tags`, { tags });
+    }
+    catch (e) {
+        console.warn(`vitrinka: could not tag session ${sessionId} with ${tags.join(', ')}`, e);
+    }
+}
+export async function togglePause() {
+    const rec = getState();
+    if (!rec || rec.dead)
+        return false;
+    rec.paused = !rec.paused;
+    if (rec.paused) {
+        rec.activeMs = (rec.activeMs || 0) + (rec.resumeAt ? Date.now() - Date.parse(rec.resumeAt) : 0);
+        rec.resumeAt = null;
+    }
+    else {
+        rec.resumeAt = new Date().toISOString();
+    }
+    setState(rec);
+    notify();
+    await api('PATCH', `/api/v1/sessions/${rec.sessionId}`, {
+        status: rec.paused ? 'paused' : 'recording',
+    }).catch((e) => console.warn('vitrinka: pause PATCH failed', e));
+    return rec.paused;
+}
+const route = () => ({ tabId: currentRoute.tabId, tabHost: currentRoute.tabHost });
+/** A plain note — `{text, route}`, the extension's shape. */
+export function addNote(text) {
+    pushEvent('note', { text, route: currentRoute.pathname }, route());
+}
+/** Scale a viewport rect to device pixels — the extension's `imageRect` space. */
+export function imagePixels(r) {
+    const s = globalThis.devicePixelRatio || 1;
+    return {
+        x: Math.round(r.x * s),
+        y: Math.round(r.y * s),
+        w: Math.round(r.w * s),
+        h: Math.round(r.h * s),
+    };
+}
+/**
+ * An annotation — the extension's annotate-note `{text, rect, selector,
+ * annotate: true}` (+ `task` when the tester chose the task destination);
+ * vitrinka projects it into a board annotation. `selector` is '' for a free
+ * region. The rect is in device pixels. An empty note is still a valid
+ * annotation, matching the extension.
+ */
+export function addAnnotation(text, rect, selector, opts = {}) {
+    pushEvent('note', {
+        text,
+        rect: imagePixels(rect),
+        selector,
+        annotate: true,
+        route: currentRoute.pathname,
+        ...(opts.task ? { task: true } : {}),
+    }, route());
+}
+/**
+ * Hooks that run at the top of Stop, before the drain snapshot — the rrweb
+ * lane ships its sub-2s tail here so the last DOM events make the session.
+ */
+const beforeStopHooks = new Set();
+export function onBeforeStop(fn) {
+    beforeStopHooks.add(fn);
+    return () => beforeStopHooks.delete(fn);
+}
+/**
+ * Stop the session. Throws with the queued-item count when the server is
+ * unreachable — the durable tail is NEVER deleted; capture freezes paused and
+ * a later Stop finishes the job once online.
+ */
+export async function stopSession() {
+    const rec = getState();
+    if (!rec)
+        return null;
+    disarmReconcile();
+    for (const fn of beforeStopHooks) {
+        try {
+            fn();
+        }
+        catch (e) {
+            console.warn('vitrinka: before-stop hook failed', e);
+        }
+    }
+    const completeDeadStop = (reason) => {
+        const kept = queuedCount();
+        setState(null);
+        setRedactionPolicy(null);
+        resetQueues();
+        notify();
+        throw new Error(`${reason || 'session rejected by the server'} — recording ended locally` +
+            (kept ? `; ${kept} undelivered item(s) discarded` : ''));
+    };
+    if (rec.dead)
+        completeDeadStop(rec.deadReason);
+    if (!(await capturesSettled())) {
+        console.warn('vitrinka: stopping with unsettled captures — a late event may not make this session');
+    }
+    if (!(await drainBuffer())) {
+        const held = getState();
+        if (held?.dead)
+            completeDeadStop(held.deadReason);
+        if (held && !held.paused) {
+            held.activeMs = elapsedOf(held);
+            held.paused = true;
+            held.resumeAt = null;
+            setState(held);
+        }
+        armReconcile();
+        notify();
+        throw new Error(`server unreachable — ${queuedCount()} item(s) kept; stop again once online`);
+    }
+    let done = null;
+    try {
+        done = await api('PATCH', `/api/v1/sessions/${rec.sessionId}`, { status: 'done' });
+    }
+    catch (e) {
+        if (e instanceof VitrinkaApiError && permanentStatus(e.status)) {
+            console.warn('vitrinka: stop rejected permanently — clearing local session', e);
+        }
+        else {
+            console.warn('vitrinka: stop PATCH failed — session kept', e);
+            armReconcile();
+            throw e;
+        }
+    }
+    setState(null);
+    setRedactionPolicy(null);
+    resetQueues();
+    notify();
+    return done;
+}

package/build/recorder/state.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared recorder state with NO DOM or React imports, so the capture layers
+ * and the queue stay unit-testable under bun and `session.ts` can re-export
+ * it as the one import site for callers.
+ */
+/**
+ * Where the recorder believes the user is. Mirrors the browser extension's
+ * lane vocabulary: `tabId` is a per-tab id (one timeline lane per browser
+ * tab), `tabHost` the page host; the route itself rides in event payloads.
+ */
+export declare const currentRoute: {
+    tabId: string;
+    tabHost: string;
+    pathname: string;
+};
+/** Set the tab identity once per document (provider mount). */
+export declare function setTabIdentity(tabId: string, tabHost: string): void;
+/** Update the current pathname; returns true when it actually changed. */
+export declare function setCurrentPath(pathname: string): boolean;
+/** Annotate mode (element pick / region marquee); chip and overlay share it. */
+export declare const annotateState: {
+    active: boolean;
+};
+export declare function setAnnotating(active: boolean): void;
+export declare function subscribe(fn: () => void): () => void;
+export declare function notify(): void;

package/build/recorder/state.js

@@ -0,0 +1,42 @@
+/**
+ * Shared recorder state with NO DOM or React imports, so the capture layers
+ * and the queue stay unit-testable under bun and `session.ts` can re-export
+ * it as the one import site for callers.
+ */
+/**
+ * Where the recorder believes the user is. Mirrors the browser extension's
+ * lane vocabulary: `tabId` is a per-tab id (one timeline lane per browser
+ * tab), `tabHost` the page host; the route itself rides in event payloads.
+ */
+export const currentRoute = { tabId: 'root', tabHost: '/', pathname: '/' };
+/** Set the tab identity once per document (provider mount). */
+export function setTabIdentity(tabId, tabHost) {
+    currentRoute.tabId = tabId;
+    currentRoute.tabHost = tabHost;
+}
+/** Update the current pathname; returns true when it actually changed. */
+export function setCurrentPath(pathname) {
+    if (currentRoute.pathname === pathname)
+        return false;
+    currentRoute.pathname = pathname;
+    notify();
+    return true;
+}
+/** Annotate mode (element pick / region marquee); chip and overlay share it. */
+export const annotateState = { active: false };
+export function setAnnotating(active) {
+    if (annotateState.active === active)
+        return;
+    annotateState.active = active;
+    notify();
+}
+// -- change subscription (the HUD re-renders off this) -----------------------
+const listeners = new Set();
+export function subscribe(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+}
+export function notify() {
+    for (const fn of listeners)
+        fn();
+}

package/build/recorder/storage/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pluggable durable KV storage for the recorder's queue and session state.
+ *
+ * The queue's correctness leans on SYNCHRONOUS reads/writes: every
+ * read-modify-write completes in one JS tick, so no async mutex is needed and
+ * delivery-ack bookkeeping stays race-free. Any driver plugged in here MUST be
+ * synchronous — which is why the default is `localStorage` and not IndexedDB.
+ *
+ * When `localStorage` is unavailable or throws on first touch (Safari private
+ * mode, a sandboxed iframe, a storage-disabled profile) the recorder falls
+ * back to the in-memory driver: capture still works for the life of the
+ * document, only the reload-survival guarantee is lost — and it says so once.
+ */
+export interface RecorderStorage {
+    /** Read a value; null/undefined when the key was never written. */
+    getString(key: string): string | null | undefined;
+    /** Write a value durably before returning. */
+    set(key: string, value: string): void;
+    /** Delete a key; a no-op when absent. */
+    remove(key: string): void;
+}
+/**
+ * Install a storage driver. Call before the recorder mounts; calling after
+ * first use throws — silently switching stores mid-session would strand the
+ * durable tail in the old one.
+ */
+export declare function configureRecorderStorage(driver: RecorderStorage): void;
+/** The active driver; lazily falls back to localStorage, then memory. */
+export declare function getRecorderStorage(): RecorderStorage;
+/** `localStorage` driver, or null when the API is absent or refuses a write. */
+export declare function localRecorderStorage(): RecorderStorage | null;
+/** In-memory driver — for tests and as the last-resort non-durable fallback. */
+export declare function memoryRecorderStorage(): RecorderStorage;
+/** Test-only: forget the configured driver and the first-use latch. */
+export declare function __resetStorageForTests(): void;

package/build/recorder/storage/index.js

@@ -0,0 +1,69 @@
+/**
+ * Pluggable durable KV storage for the recorder's queue and session state.
+ *
+ * The queue's correctness leans on SYNCHRONOUS reads/writes: every
+ * read-modify-write completes in one JS tick, so no async mutex is needed and
+ * delivery-ack bookkeeping stays race-free. Any driver plugged in here MUST be
+ * synchronous — which is why the default is `localStorage` and not IndexedDB.
+ *
+ * When `localStorage` is unavailable or throws on first touch (Safari private
+ * mode, a sandboxed iframe, a storage-disabled profile) the recorder falls
+ * back to the in-memory driver: capture still works for the life of the
+ * document, only the reload-survival guarantee is lost — and it says so once.
+ */
+// Keys land as `vitrinka.recorder.<key>`: rec · buffer · chunks · link.
+const PREFIX = 'vitrinka.recorder.';
+let current = null;
+let used = false;
+/**
+ * Install a storage driver. Call before the recorder mounts; calling after
+ * first use throws — silently switching stores mid-session would strand the
+ * durable tail in the old one.
+ */
+export function configureRecorderStorage(driver) {
+    if (used && current !== driver) {
+        throw new Error('vitrinka: configureRecorderStorage() must run before the recorder first touches storage');
+    }
+    current = driver;
+}
+/** The active driver; lazily falls back to localStorage, then memory. */
+export function getRecorderStorage() {
+    if (!current)
+        current = localRecorderStorage() ?? memoryRecorderStorage();
+    used = true;
+    return current;
+}
+/** `localStorage` driver, or null when the API is absent or refuses a write. */
+export function localRecorderStorage() {
+    try {
+        const ls = globalThis.localStorage;
+        if (!ls)
+            return null;
+        const probe = `${PREFIX}probe`;
+        ls.setItem(probe, '1');
+        ls.removeItem(probe);
+        return {
+            getString: (k) => ls.getItem(PREFIX + k),
+            set: (k, v) => ls.setItem(PREFIX + k, v),
+            remove: (k) => ls.removeItem(PREFIX + k),
+        };
+    }
+    catch {
+        console.warn('vitrinka: localStorage unavailable — the recorder queue will not survive a reload');
+        return null;
+    }
+}
+/** In-memory driver — for tests and as the last-resort non-durable fallback. */
+export function memoryRecorderStorage() {
+    const m = new Map();
+    return {
+        getString: (k) => m.get(k) ?? null,
+        set: (k, v) => void m.set(k, v),
+        remove: (k) => void m.delete(k),
+    };
+}
+/** Test-only: forget the configured driver and the first-use latch. */
+export function __resetStorageForTests() {
+    current = null;
+    used = false;
+}

package/build/recorder/storage/memory.d.ts

@@ -0,0 +1,2 @@
+/** The in-memory driver on its own import path (mirrors expo's layout). */
+export { memoryRecorderStorage } from './index';

package/build/recorder/storage/memory.js

@@ -0,0 +1,2 @@
+/** The in-memory driver on its own import path (mirrors expo's layout). */
+export { memoryRecorderStorage } from './index';

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@vitrinka/web",
+  "version": "0.1.0",
+  "description": "vitrinka toolkit for React DOM apps — the journey recorder: capture manual-testing sessions (rrweb DOM stream, clicks, navigation, network, console, notes) straight into vitrinka boards.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/henderson-tech/vitrinka-kit.git",
+    "directory": "packages/web"
+  },
+  "type": "module",
+  "source": "src/index.ts",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./recorder": {
+      "types": "./build/recorder/index.d.ts",
+      "default": "./build/recorder/index.js"
+    },
+    "./protocol": {
+      "types": "./build/protocol/index.d.ts",
+      "default": "./build/protocol/index.js"
+    },
+    "./next": {
+      "types": "./build/next.d.ts",
+      "default": "./build/next.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src",
+    "test:e2e": "playwright test -c playwright.config.ts --workers 1",
+    "prepublishOnly": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@vitrinka/link": "^0.1.0",
+    "@vitrinka/redact": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "rrweb": "^2.0.0"
+  },
+  "devDependencies": {
+    "@rrweb/types": "^2.0.0",
+    "@types/bun": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "^19.2.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "rrweb": "^2.0.0",
+    "typescript": "~6.0.3"
+  },
+  "keywords": [
+    "vitrinka",
+    "react",
+    "nextjs",
+    "recorder",
+    "rrweb",
+    "testing",
+    "devtools",
+    "session-recording"
+  ]
+}