Commentary Review SDK

Browser SDK for Commentary Live Preview Reviews.

The SDK lets a preview app connect to Commentary, expose route changes, and let reviewers select UI elements for anchored comments. It is designed to run only in review or preview environments.

Framework Compatibility

The SDK does not depend on React, Next.js, Vue, Svelte, Angular, Astro, Vite, or any other frontend framework. It does require a real browser DOM with window, document, DOM events, selectors, element geometry, History or Hash routing events, child-frame support, and postMessage.

Use it in any preview app that can load the browser bundle and render selectable DOM elements. Canvas-only, WebGL-only, native mobile, or server-only surfaces need additional app-specific metadata before Commentary can anchor element comments usefully.

Install

npm install @commentary-dev/review-sdk

For CDN usage, load the browser bundle:

<script src="https://cdn.commentary.dev/review-sdk/latest/commentary-review-sdk.js"></script>

Usage

The browser bundle initializes itself when loaded. Configure the parent origin before the script for every deployed preview. The SDK rejects wildcard parent origins and ignores deployed-preview handshakes when no parent origin is configured.

<script>
  window.__COMMENTARY_PARENT_ORIGIN__ = "https://commentary.dev";
  window.__COMMENTARY_PARENT_ORIGINS__ = ["https://commentary.dev", "https://staging.commentary.dev"];
  window.__COMMENTARY_REVIEW_SETUP__ = { parentOrigins: ["https://commentary.dev"] };
  window.__COMMENTARY_BUILD_ID__ = "preview-123";
  window.__COMMENTARY_COMMIT_SHA__ = "abcdef123456";
</script>
<script src="https://cdn.commentary.dev/review-sdk/latest/commentary-review-sdk.js"></script>

Use stable element attributes for the best anchors:

<button data-commentary-id="Billing.save">Save changes</button>

Custom form renderers use the separate @commentary-dev/forms-sdk package and https://cdn.commentary.dev/forms-sdk/latest/commentary-forms-sdk.js.

Research Mode capabilities

Version 0.3.0 introduced standalone_overlay_v1; version 0.3.1 added same-tab reload recovery. Version 0.3.2 adds optional standalone_overlay_drag_v1: the isolated overlay can request bounded position deltas while the host SDK owns viewport clamping and ephemeral position state. Older SDKs keep the fixed bottom-right overlay. Normal embedded reviews remain compatible with older SDKs. Standalone delivery runs the reviewed site top-level, stores only its already-exposed single-use launch handle and exact Commentary origin in target-origin session storage, removes the opaque launch fragment immediately, and injects an isolated Commentary overlay iframe. Scoped credentials, comments, and participant controls stay inside the Commentary-origin frame, and the site must permit Commentary in its frame-src policy.

When the Research parent enables behavior telemetry, the SDK emits privacy-filtered discrete events and sampled pointer-path batches through the existing participant session API. Pointer movement is sampled at no more than 8 Hz, flushed every two seconds and at route/task/visibility/page-exit boundaries, limited to 16 points per batch, and capped at 18,000 points per task. After the budget is exhausted, discrete events continue.

The SDK never emits raw typed values. It ignores passwords, payment/autocomplete-sensitive fields, hidden controls, and content within data-commentary-private, data-commentary-ignore, or equivalent ignored regions. Pointer sampling pauses while the page is hidden or the pointer is over an excluded region. This telemetry is interaction evidence, not DOM or video session replay.

Package Outputs

• dist/commentary-review-sdk.js: self-initializing browser SDK.
• dist/index.d.ts: ambient browser configuration declarations.

Release

This package is published as @commentary-dev/review-sdk and mirrored to https://cdn.commentary.dev/review-sdk/.