@sentryqa/runtime

Framework-independent visual QA runtime: mounts the SentryQA toolbar, markers, panel, and interactions inside the browser using Shadow DOM.

Recommended Installation

In a React + Vite application, do not install it directly. Run npx sentryqa init and let @sentryqa/vite inject it only during vite serve.

Install it directly only if you have a compatible custom bridge or are creating an advanced integration:

npm install @sentryqa/runtime

Minimal Advanced Workflow

The runtime requires a browser Document and a local endpoint that understands the issue protocol. The Vite plugin normally generates and provides the nonce.

import { mountSentryQa } from '@sentryqa/runtime';

const controller = mountSentryQa({
  apiBase: '/__sentryqa/issues',
  nonce: 'nonce-entregado-por-tu-bridge',
});

controller.pause();
controller.resume();
await controller.reload();
controller.unmount();

In addition to mountSentryQa, the public entry point exports createApiClient, context capture, markers, overlays, live authoring, review, wireframes, route monitoring, store, and FrameworkAdapter for custom integrations.

Canonical captures

Canonical v2 saves require a canonicalCapture adapter. @sentryqa/vite provides it automatically during local Vite development. Advanced integrations must provide actual current-app viewport pixels and a PNG encoder; capture errors intentionally block the save. The runtime does not substitute synthetic pixels or rewrite v1/v2 persisted issues.

Live Authoring

Layout Mode's additive live-authoring producer renders inert modal, form, input, button, and card ghosts over the current page. Each asset keeps a stable #number; deleted numbers remain tombstoned. Authored overlay geometry is never replaced by observed host geometry. Selecting an asset and clicking a host element captures only bounded locator, geometry, route, viewport, scroll, and nearby summaries. Runtime nodes, values, credentials, storage, network, console data, screenshots, and private text are excluded.

Unresolved or ambiguous anchors require explicit confirmation before save. Layout files use the existing .sentryqa/layouts revision and stale-write conflict lifecycle; live artifacts remain separate from Overlay and Wireframe artifacts.

Relationship to the Other Packages

• @sentryqa/vite prepares the bridge, nonce, and automatic runtime injection.
• @sentryqa/react can provide component metadata through FrameworkAdapter.
• @sentryqa/core contains the shared models and codecs.
• sentryqa configures the Vite plugin; it does not configure the runtime directly.

When Not to Use It

Do not add it to a production build or mount it without an authorized bridge. It is intended for local development, requires a Document, and does not depend on React components from the host application.