Use AI findings in your application

Pass validated model findings to @voice/review to display them on the page and let a person review the affected text. Your application runs the model and owns the source adapter, review UI and persistence. The Library draws the findings and returns native text selections.

Prepare the model input#

Capture the source version and its mapped text units before starting a review. Supply the model with those units, the page's purpose, approved claims and the specific questions to assess. Keep the original source version on the result.

Validate the returned JSON before displaying it. Each inline finding needs the fields in Finding: its rule/category/severity, explanation, unit ID, exact quote and range. Ranges use zero-based, half-open UTF-16 offsets within the unit. Convert explicitly if your model adapter returns code-point offsets. A claim without a usable text anchor belongs in the host's report rather than a guessed underline. Record omissions and missing evidence in that report.

Display a checked result#

The following TypeScript function takes a result whose JSON shape your host has already validated. It also checks the source version and quote before mounting. root must contain the adapter's matching data-voice-unit elements; their eligible DOM text must equal TextUnit.text.

import {
  mountVoiceReview,
  type Finding, type SelectionTarget, type TextUnit,
} from '@voice/review';

type Snapshot = { version: string; units: readonly TextUnit[] };
type CheckedResult = { sourceVersion: string; findings: readonly Finding[] };

export function showModelReview(
  root: HTMLElement,
  snapshot: Snapshot,
  result: CheckedResult,
  onSelect: (selection: SelectionTarget) => void,
) {
  if (result.sourceVersion !== snapshot.version) {
    throw new Error('Reload the source before reviewing this result.');
  }
  for (const finding of result.findings) {
    const unit = snapshot.units.find(item => item.id === finding.unitId);
    if (!unit || !Number.isInteger(finding.start) || !Number.isInteger(finding.end)
      || finding.start < 0 || finding.end <= finding.start
      || finding.end > unit.text.length
      || unit.text.slice(finding.start, finding.end) !== finding.quote) {
      throw new Error('A finding does not match the reviewed source.');
    }
  }
  return mountVoiceReview({
    root, units: snapshot.units, findings: result.findings, feedback: [], onSelect,
  });
}

Use the returned controller's getDiagnostics() to inspect unmapped units and stale anchors. Call update({ findings, feedback }) when the same view receives new review data. Call dispose() on route teardown or iframe replacement. Provide an accessible findings list alongside the marks. The typed integration guide covers package setup and complete TypeScript/JavaScript examples.

Connect a running website to Studio#

For a site reviewed inside Studio, install the built Library and call connectVoiceStudio({ studioOrigin: 'http://127.0.0.1:5188' }) behind your application's development and review opt-in guard. Configure the route's source file and related renderer files in voice.config.json. The bridge guide defines origin checks, route changes and disposal. The website needs an explicit integration and framing permission for the local Studio origin.

Studio supplies the review controller through this bridge; do not mount another one over the same page. Backend tokens belong in the Studio host session and are not sent to the website.

Save feedback or propose an edit#

An authorized host can use createReviewClient for getDocument and saveFeedback. Pass the current in-memory token through its token getter and carry expectedVersion, expectedReviewRevision and requestId unchanged. Use the same request ID for a retry of the same payload. On a conflict, preserve the draft and review it against the refreshed source.

Studio's backend also provides keep decisions, generated alternatives, semantic file reviews and source tasks. Their endpoints and version checks are described in the workflow and Runner guide. Choosing an alternative prepares a diff; applying it is a separate action. Model execution needs an explicitly configured Runner route and a start request.

A task for the integration agent#

Add opt-in Voice review to [application/route].

Map the rendered text to [source file] with exact TextUnit IDs and UTF-16 ranges.
Use the built @voice/review package and [exact local Studio origin].
Keep model execution in the host; validate results against the captured source.
Provide an accessible findings list, native selection and review callbacks.
Save feedback through the backend with source/review preconditions.
Dispose the integration on teardown and clear stale anchors on navigation.

Verify inline markup, an emoji before the selected text, native links/buttons,
missing mappings, reload/disposal and a narrow and wide viewport.
Return the changed files, source/build identity, results and remaining gaps.
Use the task's existing authorization for model starts and source/Git changes.