npm - @vitrinka/web - Versions diffs - 0.1.0 - Mend

@vitrinka/web 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

package/CHANGELOG.md +13 -0
package/LICENSE +93 -0
package/README.md +177 -0
package/build/index.d.ts +11 -0
package/build/index.js +1 -0
package/build/next.d.ts +23 -0
package/build/next.js +27 -0
package/build/protocol/index.d.ts +74 -0
package/build/protocol/index.js +22 -0
package/build/recorder/RecorderProvider.d.ts +17 -0
package/build/recorder/RecorderProvider.js +126 -0
package/build/recorder/api-status.d.ts +6 -0
package/build/recorder/api-status.js +6 -0
package/build/recorder/api.d.ts +40 -0
package/build/recorder/api.js +84 -0
package/build/recorder/capture/click.d.ts +17 -0
package/build/recorder/capture/click.js +77 -0
package/build/recorder/capture/console.d.ts +3 -0
package/build/recorder/capture/console.js +89 -0
package/build/recorder/capture/nav.d.ts +8 -0
package/build/recorder/capture/nav.js +54 -0
package/build/recorder/capture/net.d.ts +22 -0
package/build/recorder/capture/net.js +506 -0
package/build/recorder/capture/redact.d.ts +38 -0
package/build/recorder/capture/redact.js +54 -0
package/build/recorder/capture/rrweb.d.ts +10 -0
package/build/recorder/capture/rrweb.js +76 -0
package/build/recorder/config.d.ts +50 -0
package/build/recorder/config.js +100 -0
package/build/recorder/control.d.ts +29 -0
package/build/recorder/control.js +63 -0
package/build/recorder/hud/AnnotateOverlay.d.ts +25 -0
package/build/recorder/hud/AnnotateOverlay.js +122 -0
package/build/recorder/hud/Hud.d.ts +12 -0
package/build/recorder/hud/Hud.js +190 -0
package/build/recorder/hud/LinkSheet.d.ts +26 -0
package/build/recorder/hud/LinkSheet.js +15 -0
package/build/recorder/hud/RecorderPill.d.ts +36 -0
package/build/recorder/hud/RecorderPill.js +73 -0
package/build/recorder/hud/Sheet.d.ts +20 -0
package/build/recorder/hud/Sheet.js +36 -0
package/build/recorder/hud/host.d.ts +27 -0
package/build/recorder/hud/host.js +170 -0
package/build/recorder/hud/icons.d.ts +15 -0
package/build/recorder/hud/icons.js +40 -0
package/build/recorder/hud/styles.d.ts +13 -0
package/build/recorder/hud/styles.js +111 -0
package/build/recorder/index.d.ts +46 -0
package/build/recorder/index.js +61 -0
package/build/recorder/link.d.ts +18 -0
package/build/recorder/link.js +37 -0
package/build/recorder/queue.d.ts +163 -0
package/build/recorder/queue.js +642 -0
package/build/recorder/session.d.ts +73 -0
package/build/recorder/session.js +246 -0
package/build/recorder/state.d.ts +26 -0
package/build/recorder/state.js +42 -0
package/build/recorder/storage/index.d.ts +35 -0
package/build/recorder/storage/index.js +69 -0
package/build/recorder/storage/memory.d.ts +2 -0
package/build/recorder/storage/memory.js +2 -0
package/package.json +77 -0

package/build/recorder/index.js ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * Vitrinka journey recorder for React DOM apps — `@vitrinka/web/recorder`.
+ *
+ * The runtime strip: when `url` is empty, `VitrinkaRecorderRoot` renders its
+ * children and starts NOTHING, and `VitrinkaRecorderPill` renders null. Auth
+ * is a device link minted from the pill (`@vitrinka/link`) or, for CI and
+ * unattended builds, an explicit `recorderKey`; `withVitrinkaRecorder`
+ * (`@vitrinka/web/next`) refuses a production build that carries a baked key
+ * outside an allowed lane.
+ */
+import { createElement, Fragment, useEffect, useRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { envConfig, vitrinkaConfigured } from './config';
+import { createHudHost } from './hud/host';
+import { Hud } from './hud/Hud';
+import { RecorderProvider, useRecorderRoute } from './RecorderProvider';
+export { useRecorderRoute };
+export { configureRecorderStorage } from './storage';
+/** Wrap the app root. Starts the capture lanes only when `url` + `key` are present. */
+export function VitrinkaRecorderRoot(props) {
+    const env = envConfig();
+    const url = props.url ?? env.url;
+    const key = props.recorderKey ?? env.key;
+    // The strip: the URL alone enables the recorder; auth is a key or the device link.
+    if (!url)
+        return createElement(Fragment, null, props.children);
+    return createElement(RecorderProvider, {
+        config: { url, key, appVersion: props.appVersion, environment: props.environment, label: props.label },
+    }, createElement(RouteFeed, { route: props.route }), props.children);
+}
+function RouteFeed({ route }) {
+    useRecorderRoute(route);
+    return null;
+}
+/**
+ * The HUD — mount it anywhere under the root (it renders into its own shadow
+ * host on `<html>`, never into the app's DOM). Renders null when the root is
+ * inert.
+ */
+export function VitrinkaRecorderPill(props) {
+    const rootRef = useRef(null);
+    const titleRef = useRef(props.title);
+    titleRef.current = props.title;
+    useEffect(() => {
+        if (!vitrinkaConfigured())
+            return;
+        const host = createHudHost();
+        const root = createRoot(host.mount);
+        rootRef.current = root;
+        root.render(createElement(Hud, {
+            hostMount: host.mount,
+            defaultTitle: () => titleRef.current ?? document.title,
+        }));
+        return () => {
+            root.unmount();
+            host.destroy();
+            rootRef.current = null;
+        };
+    }, []);
+    return null;
+}

package/build/recorder/link.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * The device link, wired to the recorder: start a code, poll for approval,
+ * store the token; forget it on Unlink or when a session door answers 401.
+ */
+import { type Linked, type LinkStart } from '@vitrinka/link';
+export { LinkExpired } from '@vitrinka/link';
+export interface DeviceLink {
+    start: LinkStart;
+    /** Resolves once the tester approved; rejects with LinkExpired / AbortError. */
+    linked: Promise<Linked>;
+    cancel: () => void;
+}
+/** Ask for a code and poll until approved. The token is stored on success. */
+export declare function linkDevice(): Promise<DeviceLink>;
+/** Forget the stored link; a live session ends locally (its tail is dropped). */
+export declare function forgetLink(): void;
+/** Register the 401 → unlinked transition. Returns the uninstaller. */
+export declare function installUnauthorizedHandler(): () => void;

package/build/recorder/link.js ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * The device link, wired to the recorder: start a code, poll for approval,
+ * store the token; forget it on Unlink or when a session door answers 401.
+ */
+import { pollLink, startLink } from '@vitrinka/link';
+import { onUnauthorized } from './api';
+import { clearLink, defaultLinkLabel, recorderConfig, storeLink } from './config';
+import { getState, resetQueues, setState } from './queue';
+import { notify } from './state';
+export { LinkExpired } from '@vitrinka/link';
+/** Ask for a code and poll until approved. The token is stored on success. */
+export async function linkDevice() {
+    const { url } = recorderConfig();
+    const start = await startLink(url, { label: defaultLinkLabel() });
+    const ac = new AbortController();
+    const linked = pollLink(url, start.device_code, { interval: start.interval, signal: ac.signal }).then((l) => {
+        storeLink(l);
+        return l;
+    });
+    return { start, linked, cancel: () => ac.abort() };
+}
+/** Forget the stored link; a live session ends locally (its tail is dropped). */
+export function forgetLink() {
+    clearLink();
+    if (getState()) {
+        setState(null);
+        resetQueues();
+    }
+    notify();
+}
+/** Register the 401 → unlinked transition. Returns the uninstaller. */
+export function installUnauthorizedHandler() {
+    return onUnauthorized(() => {
+        console.warn('vitrinka: recorder token rejected (401) — link the device again');
+        forgetLink();
+    });
+}

package/build/recorder/queue.d.ts ADDED Viewed

@@ -0,0 +1,163 @@
+/**
+ * Durable event queue — a port of the Expo recorder's queue (itself a port of
+ * the browser extension's design), adapted to the browser:
+ *
+ * - A synchronous KV store (./storage — localStorage by default, memory when
+ *   that is unavailable) holds the session record and the event buffer:
+ *   reads/writes complete in one JS tick, so no async mutex is needed. Only
+ *   flush() needs single-flight guarding (its POST is async) and it removes
+ *   exactly the sent seqs on return.
+ * - rrweb batches ride as CHUNKS the way the extension sends them: each batch
+ *   is serialized once, split under the server's chunk cap, uploaded to
+ *   `/chunk?seq=N` under a pre-allocated seq, and only then does its `rrweb`
+ *   event row (payload {count}, blobKey) join the event stream — keeping its
+ *   originally allocated seq (gap-fill), retried oldest-first AHEAD of the
+ *   event flush. Chunks are kept in memory (they can be megabytes; the KV
+ *   store is small) and persisted best-effort under a byte budget.
+ * - A permanent server verdict (4xx minus 408/429) drops the item loudly;
+ *   transient failures stop the pass and the next flush retries.
+ * - A reload keeps the undelivered event tail (KV store is durable).
+ * - Reconciliation (extension D5/D9): a 10s poll asks the server what it
+ *   actually holds (`serverMaxSeq`) and whether the session still exists.
+ *   Only the SERVER's verdict (404 / done / deleted / permanent events
+ *   rejection) marks a session dead — flushing then stops instead of
+ *   retrying into a session that can never accept another event.
+ * - health() (extension D4): honest by construction — "synced" means the
+ *   server confirmed it holds everything this recorder allocated, not
+ *   merely "my last POST returned 200".
+ */
+import type { RedactionPolicy } from '@vitrinka/redact';
+import type { RecorderEvent } from '../protocol';
+/** How often a live session reconciles against the server (extension D5). */
+export declare const RECONCILE_MS = 10000;
+export interface SessionState {
+    sessionId: string;
+    project: string;
+    environment: string;
+    title: string;
+    /** Server-minted board link; "Open board" uses it verbatim. */
+    boardUrl?: string;
+    seq: number;
+    paused: boolean;
+    /** Active-time bookkeeping: elapsed = activeMs + (now - resumeAt while running). */
+    activeMs: number;
+    resumeAt: string | null;
+    /**
+     * The SERVER will not accept this session's events any more (extension D9):
+     * 404 / done / deleted from the reconcile poll, or a permanent verdict on
+     * the events POST. Capture and flushing stop; Stop completes locally.
+     * Durable so a reload cannot resurrect the pointless retry loop.
+     */
+    dead?: boolean;
+    deadReason?: string;
+    /**
+     * The workspace redaction policy fetched at session start (null = fetch
+     * failed ⇒ the engine's safe defaults). Durable WITH the session so a
+     * reload re-applies the same rules instead of silently reverting.
+     */
+    policy?: RedactionPolicy | null;
+}
+export type { RecorderEvent };
+/**
+ * The LIVE session record — a mutable alias of the cache, not a copy. Treat it
+ * as READ-ONLY unless you pass the object you mutated straight to `setState()`
+ * in the same tick.
+ */
+export declare function getState(): SessionState | null;
+export declare function setState(rec: SessionState | null): void;
+/** Write the in-memory buffer (and the pending chunks) to storage NOW. */
+export declare function persistNow(): void;
+export declare function queuedCount(): number;
+/** Fresh-session baseline; called by startSession before capture begins. */
+export declare function resetHealth(baseSeq?: number): void;
+export type RecorderHealthState = 'idle' | 'ok' | 'backlog' | 'offline' | 'dead';
+export interface RecorderHealth {
+    state: RecorderHealthState;
+    queued: number;
+    failures: number;
+    error: string;
+    sinceSyncMs: number | null;
+    localSeq: number;
+    serverMaxSeq: number;
+    /** The reconciliation itself: the server accounts for every allocated seq. */
+    synced: boolean;
+    deadReason: string;
+}
+export declare function health(): RecorderHealth;
+/**
+ * Record that the SERVER will not accept this session's events any more
+ * (extension D9). Freezes the HUD clock and stops the retry loop; the durable
+ * tail stays until Stop.
+ */
+export declare function markSessionDead(reason: string): void;
+/** Ask the server what it actually holds (extension D5/D9). */
+export declare function reconcile(): Promise<void>;
+export declare function armReconcile(): void;
+export declare function disarmReconcile(): void;
+/** Allocate `count` consecutive seqs without emitting events; null when not capturing. */
+export declare function allocSeq(count?: number): {
+    seq: number;
+    sessionId: string;
+} | null;
+export declare function trackCapture(p: Promise<void>): Promise<void>;
+export declare const CAPTURES_SETTLE_MS = 5000;
+/** Wait for in-flight captures, bounded; false when stragglers were abandoned. */
+export declare function capturesSettled(deadlineMs?: number): Promise<boolean>;
+/** Is `id` the session currently in state AND still accepting capture? */
+export declare function isSessionLive(id: string): boolean;
+/**
+ * Append an event to the durable buffer (drops when no live session or
+ * paused). `tabId`/`tabHost`/`ts`/`seq` are filled here; capture layers pass
+ * kind+payload plus the route they observed. Returns the stamped ts (null
+ * when dropped).
+ */
+export declare function pushEvent(kind: string, payload: Record<string, unknown> | undefined, route: {
+    tabId: string;
+    tabHost: string;
+}): string | null;
+/** Push a fully-formed event (chunk rows carry a pre-allocated seq). */
+export declare function pushRawEvent(ev: RecorderEvent): void;
+export declare function idleMs(): number;
+export declare function resetIdle(): void;
+/**
+ * Split a batch of rrweb events into size-bounded, in-order parts (extension
+ * `splitRRWebEvents`). Returns the serialized bodies and the byte sizes of
+ * events that are alone beyond the wire cap (undeliverable).
+ */
+export declare function splitRRWebEvents(events: readonly unknown[], packBytes?: number, hardBytes?: number): {
+    parts: {
+        count: number;
+        body: string;
+    }[];
+    dropped: number[];
+};
+/**
+ * Queue a batch of rrweb events as chunks under pre-allocated seqs. Dropped
+ * (undeliverable) events surface as a ⚠ note on the timeline, as the
+ * extension does. Returns the number of chunks queued (0 when not capturing).
+ */
+export declare function pushRRWebBatch(events: readonly unknown[], route: {
+    tabId: string;
+    tabHost: string;
+}): number;
+export declare function scheduleFlush(): void;
+/** Single-flight flush; true when the events POST succeeded (or nothing to send). */
+export declare function flush(opts?: {
+    keepalive?: boolean;
+}): Promise<boolean>;
+/** Drain until buffer + chunks are empty or the deadline passes. */
+export declare function drainBuffer(deadlineMs?: number): Promise<boolean>;
+/** Reset buffers for a fresh session. */
+export declare function resetQueues(): void;
+/** Test-only: drop all module state so suites cannot leak into each other. */
+export declare function __resetForTests(): void;
+/** Test-only: the recorded events currently buffered (in order). */
+export declare function __bufferForTests(): RecorderEvent[];
+/** Test-only: the pending chunks (in order). */
+export declare function __chunksForTests(): {
+    seq: number;
+    count: number;
+    sessionId: string;
+}[];
+/** Test-only: drop the in-memory caches while LEAVING storage intact (a reload). */
+export declare function __dropCachesForTests(): void;