@vitrinka/web 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @vitrinka/web
+
+## 0.1.0
+
+- Initial release: the React DOM journey recorder (`@vitrinka/web/recorder`)
+  — rrweb DOM stream (chunked like the browser extension), DOM clicks,
+  navigation, `console.error` / uncaught errors, fetch/XHR with
+  `@vitrinka/redact`; the pill HUD in a top-layer shadow host with notes,
+  element/region annotations and keyboard shortcuts; `window.__vitrinkaRecorder`
+  control handle; `withVitrinkaRecorder` (`@vitrinka/web/next`) build guard.
+- Device link: no key needed — the pill links the device (`@vitrinka/link`),
+  stores the minted token under `vitrinka.recorder.link`; `recorderKey` is
+  for CI. The runtime strip is the URL alone.

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,177 @@
+# @vitrinka/web
+
+The vitrinka toolkit for React DOM apps — today, the **journey recorder**:
+record a manual-testing session straight from the app under test into a
+vitrinka board. The web sibling of [`@vitrinka/expo`](../expo) and of the
+browser extension: same wire protocol, same redaction engine, no extension
+to install.
+
+What a session carries: the **rrweb DOM stream** (the keyframe — no
+screenshots), **clicks** (selector, text, rect), **navigation**, **network**
+(fetch + XHR, headers + bodies redacted), **console errors**, and the
+**notes and annotations** you type in the pill. Everything is redacted by
+[`@vitrinka/redact`](../redact) before it is buffered; the full contract is
+[`docs/PROTOCOL.md`](../../docs/PROTOCOL.md).
+
+## Install
+
+```bash
+bun add @vitrinka/web rrweb
+# or: npm i @vitrinka/web rrweb
+```
+
+Peer deps: `react` ≥ 18, `react-dom` ≥ 18, `rrweb` ^2.
+
+## Mount (Next.js app router)
+
+```tsx
+// app/layout.tsx
+import { VitrinkaRecorderRoot, VitrinkaRecorderPill } from '@vitrinka/web/recorder';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <VitrinkaRecorderRoot
+          url={process.env.NEXT_PUBLIC_VITRINKA_URL}
+          recorderKey={process.env.NEXT_PUBLIC_VITRINKA_KEY}
+          appVersion={process.env.NEXT_PUBLIC_APP_VERSION}
+        >
+          {children}
+          <VitrinkaRecorderPill />
+        </VitrinkaRecorderRoot>
+      </body>
+    </html>
+  );
+}
+```
+
+`VitrinkaRecorderRoot` installs the capture lanes; `VitrinkaRecorderPill`
+renders the HUD into its own shadow host on `<html>` (top layer, never inside
+your DOM). **When `url` is empty the root renders its children and starts
+nothing** — a build without the URL carries an inert recorder.
+
+**No key is needed.** Dev/preview builds set only `NEXT_PUBLIC_VITRINKA_URL`;
+testers **link their device from the pill**: the pill shows **Link
+recorder**, the sheet shows a short code, **Open vitrinka** (approve on this
+device) and a QR (scan from your phone); once approved the server mints an
+ingest-only `vkr_` token, stored in `localStorage` under
+`vitrinka.recorder.link`, and recording starts. **Unlink** in the ⋯ menu
+forgets it — so does a 401 from the server. `recorderKey` (an admin-minted
+`vkr_` key) is for CI, e2e and unattended builds only; when passed it wins
+over the link. The prop is `recorderKey`, not `key`: React reserves `key`
+and never delivers it to a component.
+
+Navigation is observed through `history.pushState` / `replaceState` /
+`popstate`, which covers Next, React Router and friends. A router that
+navigates without History can feed its pathname instead:
+
+```tsx
+import { usePathname } from 'next/navigation';
+import { useRecorderRoute } from '@vitrinka/web/recorder';
+
+function RouteFeed() {
+  useRecorderRoute(usePathname());
+  return null;
+}
+```
+
+Vite and plain React work the same way — pass `url` / `recorderKey` from
+`import.meta.env` (the `NEXT_PUBLIC_*` fallback only applies where a
+bundler inlines `process.env`).
+
+### Env vars
+
+| Var | What |
+|---|---|
+| `NEXT_PUBLIC_VITRINKA_URL` | Your vitrinka server, e.g. `https://app.vitrinka.ai` |
+| `NEXT_PUBLIC_VITRINKA_KEY` | Optional — CI / unattended only. A **`vkr_` recorder key** minted in vitrinka under Settings → project → Recorder keys: project-pinned, origin-allowlisted, valid only on the session routes — never a `vkp_`/`vks_` API key. Testers link instead. |
+| `VITRINKA_RECORDER_LANE` | The build's lane for the guard below (`development`, `preview`, …) |
+
+### The build guard
+
+A production build must never ship the recorder by accident. Wrap your Next
+config:
+
+```js
+// next.config.js
+const { withVitrinkaRecorder } = require('@vitrinka/web/next');
+module.exports = withVitrinkaRecorder({ /* your config */ });
+```
+
+`next build` (`NODE_ENV=production`) then **refuses** when a baked
+`NEXT_PUBLIC_VITRINKA_KEY` is set and `VITRINKA_RECORDER_LANE` is not one of
+the allowed lanes — the URL alone is allowed everywhere (dev/preview builds
+set only the URL; testers link from the pill; a key is for CI) (default `development`, `preview`; override with
+`allowedLanes`, and the var names with `laneVar` / `keyVar`). Unset the key
+for the production lane, or set the lane on the preview one. The config is
+returned unchanged otherwise.
+
+## Using the pill
+
+Unlinked: **Link recorder** bottom-right. Linked and idle: a quiet dot — click to **start** (the session title is
+`document.title`, or the `title` prop). Recording: rec dot · timer · name ·
+sync glyph · controls (keycaps show on hover):
+
+| Control | Shortcut | What |
+|---|---|---|
+| ⏸ Pause / ▶ Resume | ⌥⇧P (Alt⇧P) | freezes the clock and capture |
+| ✎ Note | ⌥⇧N | the 360px sheet — Enter sends, ⇧Enter newline, Esc / ✕ / click-outside cancel (the draft survives a cancel) |
+| ⌖ Annotate | ⌥⇧A | click an element or drag a region, then describe it; `board` (an annotation on the board) or `task` (also filed as an intake draft) |
+| ⋯ | | **Open board** (the server-minted link) · **Stop recording** · **Unlink** |
+
+The sync glyph is honest: ✓ means the server confirmed it holds everything
+captured; a second line unfolds only for a backlog, an outage (`offline ·
+N held · retrying` — nothing is dropped, the tail is kept in `localStorage`)
+or a session the server closed. Stop drains first and refuses while the
+server is unreachable — stop again once online.
+
+The sheet renders inside the topmost open dialog when one exists, so a
+Radix focus trap or a `<dialog>.showModal()` never fights it, and nothing
+you do on the pill reaches the page (a "close on outside click" never fires
+because of the recorder).
+
+## Driving it from code
+
+`window.__vitrinkaRecorder` — for agents and tests:
+
+```ts
+await __vitrinkaRecorder.start({ title: 'checkout', tags: ['ai'] });
+__vitrinkaRecorder.note('price flashes on hover');
+const { boardUrl } = await __vitrinkaRecorder.stop();
+__vitrinkaRecorder.status(); // { recording, sessionId, elapsedMs, queued, synced, … }
+```
+
+## What is captured, exactly
+
+| Lane | Event `kind` | Payload |
+|---|---|---|
+| rrweb | `rrweb` | `{count}` + `blobKey` — the batch itself is uploaded as a chunk; inputs always masked, all text under a `maskAllText` policy |
+| clicks | `click` | `{selector, text, rect, route}` |
+| navigation | `nav` | `{url, route, spa}` |
+| network | `net` | `{method, url, status, ms, reqHeaders, resHeaders, reqBody, resBody, via}` — redacted, capped at 64 KiB per body; the recorder's own uploads are never recorded |
+| console | `console` | `{level: 'error', text}` |
+| notes | `note` | `{text, route}`; annotations add `{rect, selector, annotate: true, task?}` |
+
+Data goes to your vitrinka server only. Details, the redaction rules and the
+policy fetch: [`docs/PROTOCOL.md`](../../docs/PROTOCOL.md).
+
+## Storage
+
+The undelivered tail lives in `localStorage` (a recording survives a reload
+of its tab). Where that is unavailable (private mode, a storage-disabled
+profile) the recorder falls back to memory and says so once; plug your own
+synchronous driver with `configureRecorderStorage()` before mounting.
+
+## Development
+
+```bash
+bun run --filter '@vitrinka/redact' build   # the workspace dep resolves through build/
+bun run --filter '@vitrinka/web' typecheck
+bun run --filter '@vitrinka/web' test       # bun test src
+bun run test:e2e:web                        # one headless Chromium spec (packages/web/e2e)
+```
+
+A release is a tag: bump `version` here (and `RECORDER_VERSION` in
+`src/recorder/session.ts`), merge, then `git tag web-vX.Y.Z && git push
+origin web-vX.Y.Z`.

package/build/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @vitrinka/web — the vitrinka toolkit for React DOM apps.
+ *
+ * The root export carries only the wire protocol types; the tools live on
+ * subpaths so an app bundles exactly what it imports:
+ *
+ *   @vitrinka/web/recorder   journey recorder (VitrinkaRecorderRoot, VitrinkaRecorderPill)
+ *   @vitrinka/web/next       withVitrinkaRecorder (next.config.js build guard, Node-only)
+ *   @vitrinka/web/protocol   recorder↔server wire types
+ */
+export type * from './protocol';

package/build/index.js

@@ -0,0 +1 @@
+export {};

package/build/next.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `withVitrinkaRecorder` — the build guard for Next apps (`next.config.js`).
+ * Node-only, no React import.
+ *
+ * The recorder ships in any build whose env carries the key; this guard is
+ * the safety boundary: a PRODUCTION build (`NODE_ENV=production`) that has
+ * the key var set must also declare an allowed lane in `VITRINKA_RECORDER_LANE`
+ * (default: `development` or `preview`), or the build refuses with a clear
+ * error. The URL alone is allowed everywhere (testers link from the pill); the
+ * config is returned unchanged otherwise.
+ */
+export interface WithVitrinkaRecorderOptions {
+    /** Lanes a production build may carry the recorder key in. */
+    allowedLanes?: readonly string[];
+    /** Env var naming the build's lane. */
+    laneVar?: string;
+    /** Env var carrying the recorder key. */
+    keyVar?: string;
+    /** Env var carrying the vitrinka URL (informational — only the key gates). */
+    urlVar?: string;
+}
+export declare const DEFAULT_ALLOWED_LANES: readonly string[];
+export declare function withVitrinkaRecorder<T>(nextConfig: T, opts?: WithVitrinkaRecorderOptions): T;

package/build/next.js

@@ -0,0 +1,27 @@
+/**
+ * `withVitrinkaRecorder` — the build guard for Next apps (`next.config.js`).
+ * Node-only, no React import.
+ *
+ * The recorder ships in any build whose env carries the key; this guard is
+ * the safety boundary: a PRODUCTION build (`NODE_ENV=production`) that has
+ * the key var set must also declare an allowed lane in `VITRINKA_RECORDER_LANE`
+ * (default: `development` or `preview`), or the build refuses with a clear
+ * error. The URL alone is allowed everywhere (testers link from the pill); the
+ * config is returned unchanged otherwise.
+ */
+export const DEFAULT_ALLOWED_LANES = ['development', 'preview'];
+export function withVitrinkaRecorder(nextConfig, opts = {}) {
+    const allowed = opts.allowedLanes ?? DEFAULT_ALLOWED_LANES;
+    const laneVar = opts.laneVar ?? 'VITRINKA_RECORDER_LANE';
+    const keyVar = opts.keyVar ?? 'NEXT_PUBLIC_VITRINKA_KEY';
+    const env = process.env;
+    if (env.NODE_ENV === 'production' && env[keyVar]) {
+        const lane = env[laneVar] ?? '';
+        if (!allowed.includes(lane)) {
+            throw new Error(`vitrinka: ${keyVar} is set on a production build but ${laneVar}=${JSON.stringify(lane)} ` +
+                `is not an allowed recorder lane (${allowed.join(', ')}). ` +
+                `Unset ${keyVar} for this build, or set ${laneVar} to one of the allowed lanes.`);
+        }
+    }
+    return nextConfig;
+}

package/build/protocol/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MIRROR of `packages/expo/src/protocol/index.ts` — platform-first packages
+ * each own their copy, and this one MUST stay byte-compatible with expo's
+ * (same shapes, same field names): the vitrinka server pins ONE ingest
+ * contract and both recorders ride it. Edit expo's first, then re-mirror.
+ */
+/**
+ * The recorder↔server wire contract — `@vitrinka/web/protocol` (mirrors `@vitrinka/expo/protocol`).
+ *
+ * Everything the recorders send rides these shapes over four routes:
+ *
+ *   POST  /api/v1/sessions            SessionCreateRequest → SessionCreateResponse
+ *   POST  /api/v1/sessions/:id/events { events: RecorderEvent[] }
+ *   POST  /api/v1/sessions/:id/shot?seq=N   (image body; the event stream
+ *                                            carries a matching 'shot' event)
+ *   PATCH /api/v1/sessions/:id        { status: SessionStatus }
+ *
+ * This module is types-only and dependency-free on purpose: the vitrinka
+ * server pins its ingest contract against it, so a change here is a change to
+ * the wire — version it deliberately.
+ */
+/** One captured event in a session's ordered stream. */
+export interface RecorderEvent {
+    /** Recorder-allocated, strictly increasing; the delivery-ack unit. */
+    seq: number;
+    /** ISO timestamp at capture. */
+    ts: string;
+    /** Timeline lane (tab/section grouping). */
+    tabId: string;
+    /** Full pathname/host context the event happened on. */
+    tabHost: string;
+    /** Event kind: 'nav' | 'click' | 'shot' | 'note' | 'net' | 'console' | … */
+    kind: string;
+    payload?: Record<string, unknown>;
+    /** Server blob reference for 'shot' events (set after upload). */
+    blobKey?: string;
+}
+export interface SessionCreateRequest {
+    /** App id the server resolves project+environment from. */
+    app: string;
+    title: string;
+    /** Explicit server lane; omitted = the server's app-id rule decides. */
+    environment?: string;
+    meta?: {
+        /** Recorder implementation + protocol revision, e.g. 'vitrinka-expo/1'. */
+        recorder?: string;
+        platform?: string;
+        appVersion?: string;
+        /** 'ai' marks a machine-driven run. */
+        driver?: string;
+        [key: string]: unknown;
+    };
+}
+export interface SessionCreateResponse {
+    id: string;
+    project: string;
+    environment: string;
+    title: string;
+}
+export type SessionStatus = 'recording' | 'paused' | 'done';
+/** GET /api/v1/sessions/:id — the reconcile poll's answer. */
+export interface SessionReconcileResponse {
+    /** Highest seq the server actually holds. */
+    maxSeq?: number;
+    status?: string;
+    deletedAt?: string | null;
+}
+/** PATCH response when a session completes (board projection). */
+export interface SessionDone {
+    boardSlug?: string;
+    board?: {
+        url?: string;
+    };
+}

package/build/protocol/index.js

@@ -0,0 +1,22 @@
+/**
+ * MIRROR of `packages/expo/src/protocol/index.ts` — platform-first packages
+ * each own their copy, and this one MUST stay byte-compatible with expo's
+ * (same shapes, same field names): the vitrinka server pins ONE ingest
+ * contract and both recorders ride it. Edit expo's first, then re-mirror.
+ */
+/**
+ * The recorder↔server wire contract — `@vitrinka/web/protocol` (mirrors `@vitrinka/expo/protocol`).
+ *
+ * Everything the recorders send rides these shapes over four routes:
+ *
+ *   POST  /api/v1/sessions            SessionCreateRequest → SessionCreateResponse
+ *   POST  /api/v1/sessions/:id/events { events: RecorderEvent[] }
+ *   POST  /api/v1/sessions/:id/shot?seq=N   (image body; the event stream
+ *                                            carries a matching 'shot' event)
+ *   PATCH /api/v1/sessions/:id        { status: SessionStatus }
+ *
+ * This module is types-only and dependency-free on purpose: the vitrinka
+ * server pins its ingest contract against it, so a change here is a change to
+ * the wire — version it deliberately.
+ */
+export {};

package/build/recorder/RecorderProvider.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Recorder root — mounted ONLY when `url` + `key` are present (see index.ts).
+ * Installs the capture lanes once per document, recovers a session that
+ * survived a reload, and keeps the rrweb lane in step with the session.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import { type RecorderConfig } from './config';
+export declare function RecorderProvider({ config, children, }: {
+    config: RecorderConfig;
+    children?: ReactNode;
+}): ReactElement;
+/**
+ * Feed the recorder a router's pathname (Next: `usePathname()`). The default
+ * History wrap already sees `pushState`; this hook exists for routers that
+ * navigate without it and is idempotent alongside it.
+ */
+export declare function useRecorderRoute(pathname: string | null | undefined): void;

package/build/recorder/RecorderProvider.js

@@ -0,0 +1,126 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Recorder root — mounted ONLY when `url` + `key` are present (see index.ts).
+ * Installs the capture lanes once per document, recovers a session that
+ * survived a reload, and keeps the rrweb lane in step with the session.
+ */
+import { useEffect } from 'react';
+import { installClickLane } from './capture/click';
+import { patchConsole, unpatchConsole } from './capture/console';
+import { installNavLane, noteNavigation, primeNavigation } from './capture/nav';
+import { patchNetwork, unpatchNetwork } from './capture/net';
+import { checkoutRRWeb, flushRRWeb, startRRWeb, stopRRWeb } from './capture/rrweb';
+import { configureRecorder } from './config';
+import { installControl } from './control';
+import { installUnauthorizedHandler } from './link';
+import { insideHud } from './hud/host';
+import { armReconcile, flush, getState, persistNow, reconcile, scheduleFlush } from './queue';
+import { onBeforeStop, recoverRedactionPolicy } from './session';
+import { annotateState, setTabIdentity, subscribe } from './state';
+const TAB_KEY = 'vitrinka.tab';
+/** One lane per browser tab: a per-tab id kept in sessionStorage (survives reloads). */
+function tabId() {
+    try {
+        const ss = globalThis.sessionStorage;
+        const have = ss.getItem(TAB_KEY);
+        if (have)
+            return have;
+        const id = Math.random().toString(36).slice(2, 10);
+        ss.setItem(TAB_KEY, id);
+        return id;
+    }
+    catch {
+        return 'root';
+    }
+}
+export function RecorderProvider({ config, children, }) {
+    configureRecorder(config);
+    useEffect(() => {
+        configureRecorder(config);
+    }, [config]);
+    useEffect(() => {
+        setTabIdentity(tabId(), location.host);
+        primeNavigation();
+        // The fetch/XHR and console patches are idempotent (a globalThis mark)
+        // and UNINSTALLED on unmount below, so the recorder never outlives its
+        // tree; the History wrap is idempotent too and stays (a nav event with no
+        // session is dropped at the queue, so it costs nothing).
+        patchNetwork();
+        patchConsole();
+        installNavLane();
+        const uninstallClicks = installClickLane({
+            ignore: (t) => annotateState.active || insideHud(t),
+        });
+        const uninstallControl = installControl();
+        const uninstall401 = installUnauthorizedHandler();
+        // Keep the rrweb lane in step with the session: start on record, a fresh
+        // checkout on resume, ship-and-stop on stop.
+        let wasRecording = false;
+        let wasPaused = false;
+        const syncLanes = () => {
+            const rec = getState();
+            const recording = rec !== null && !rec.dead;
+            if (recording && !wasRecording)
+                startRRWeb();
+            else if (!recording && wasRecording)
+                stopRRWeb();
+            else if (recording && wasPaused && !rec.paused)
+                checkoutRRWeb();
+            wasRecording = recording;
+            wasPaused = rec?.paused ?? false;
+        };
+        const unsubscribe = subscribe(syncLanes);
+        const offBeforeStop = onBeforeStop(flushRRWeb);
+        // A reload mid-session: the durable tail needs a drain, the reconcile
+        // poll re-arming, the policy re-applying, and the new document is a nav.
+        scheduleFlush();
+        if (getState()) {
+            recoverRedactionPolicy();
+            armReconcile();
+            noteNavigation();
+        }
+        syncLanes();
+        // Leaving the document: ship the rrweb tail, persist, and try a keepalive
+        // flush of a small events batch so the last steps ride out.
+        const onPageHide = () => {
+            flushRRWeb();
+            persistNow();
+            void flush({ keepalive: true });
+        };
+        const onVisible = () => {
+            if (document.visibilityState === 'visible' && getState()) {
+                void flush();
+                void reconcile();
+            }
+        };
+        addEventListener('pagehide', onPageHide);
+        document.addEventListener('visibilitychange', onVisible);
+        return () => {
+            removeEventListener('pagehide', onPageHide);
+            document.removeEventListener('visibilitychange', onVisible);
+            unsubscribe();
+            offBeforeStop();
+            uninstallClicks();
+            uninstallControl();
+            uninstall401();
+            stopRRWeb();
+            unpatchNetwork();
+            unpatchConsole();
+        };
+        // The lanes install once per mount; config changes are handled above.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Feed the recorder a router's pathname (Next: `usePathname()`). The default
+ * History wrap already sees `pushState`; this hook exists for routers that
+ * navigate without it and is idempotent alongside it.
+ */
+export function useRecorderRoute(pathname) {
+    useEffect(() => {
+        if (pathname == null)
+            return;
+        noteNavigation();
+    }, [pathname]);
+}

package/build/recorder/api-status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Transport-status vocabulary — ONE copy lives in `@vitrinka/link` (the
+ * zero-dependency package every recorder already depends on); this module
+ * keeps the import path stable for `api.ts` and the tests.
+ */
+export { permanentStatus, VitrinkaApiError } from '@vitrinka/link';

package/build/recorder/api-status.js

@@ -0,0 +1,6 @@
+/**
+ * Transport-status vocabulary — ONE copy lives in `@vitrinka/link` (the
+ * zero-dependency package every recorder already depends on); this module
+ * keeps the import path stable for `api.ts` and the tests.
+ */
+export { permanentStatus, VitrinkaApiError } from '@vitrinka/link';

package/build/recorder/api.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Vitrinka API client for the web journey recorder.
+ *
+ * Ingest contract, shared with the Expo recorder and the browser extension:
+ *   GET   /api/v1/recorder/policy          workspace redaction policy
+ *   POST  /api/v1/sessions                 {host, title, environment?, meta} → session
+ *   POST  /api/v1/sessions/:id/events      {events: [...]}
+ *   POST  /api/v1/sessions/:id/chunk?seq=N (rrweb batch body, application/json)
+ *   POST  /api/v1/sessions/:id/tags        {tags}  (non-fatal)
+ *   GET   /api/v1/sessions/:id             reconcile
+ *   PATCH /api/v1/sessions/:id             {status: recording|paused|done}
+ *
+ * Every call: `authorization: Bearer <key>`, `credentials: "omit"` (the key
+ * IS the credential; cookies never ride), `mode: "cors"`.
+ */
+import type { RedactionPolicy } from '@vitrinka/redact';
+export { permanentStatus, VitrinkaApiError } from './api-status';
+export declare function onUnauthorized(fn: () => void): () => void;
+/**
+ * Fetch the workspace redaction policy at session start. NEVER rejects: null
+ * (server too old, network down, 4xx) means the engine's safe defaults — fail
+ * closed, never capture-everything.
+ */
+export declare function fetchPolicy(): Promise<RedactionPolicy | null>;
+export interface ApiOptions {
+    /**
+     * Survive page unload (the pagehide flush). Browsers cap keepalive bodies at
+     * 64 KiB — callers pass it only for a small tail batch.
+     */
+    keepalive?: boolean;
+}
+export declare function api<T = Record<string, unknown>>(method: string, path: string, body?: unknown, opts?: ApiOptions): Promise<T>;
+/**
+ * Upload one rrweb chunk (an already-serialized JSON array of rrweb events)
+ * under a pre-allocated seq. Returns the server's blobKey — the matching
+ * `rrweb` event row carries it.
+ */
+export declare function uploadChunk(sessionId: string, seq: number, body: string): Promise<{
+    blobKey?: string;
+}>;