The live-page bridge protocol

The live bridge runs inside a website that explicitly integrates it. Studio embeds that site's actual development-server URL. The site's scripts, CSS, native links, framework rendering and router continue to run on its own origin.

Add the bridge to the site's development entry point#

import { connectVoiceStudio } from '@voice/review';

const connection = connectVoiceStudio({
  studioOrigin: 'http://127.0.0.1:4188'
});

// Dispose when the development integration is unloaded (e.g. HMR cleanup).
// connection.dispose();

For plain HTML, serve the built dist/voice-review.js from the target site's own development assets and load it normally:

<script src="/dev/voice-review.js"></script>
<script>
  const voiceConnection = VoiceReview.connectVoiceStudio({
    studioOrigin: 'http://127.0.0.1:4188'
  });
</script>

Keep this opt-in integration in development mode. Use the Studio's exact origin: localhost and 127.0.0.1 are different origins, as are different ports. No wildcard is accepted. The bridge receives only review data and sends selections, annotation IDs, mapping diagnostics and the current page location. It never receives the local backend pairing token or provider credentials.

Connect the live DOM to the source#

Explicit data-voice-unit attributes are preferred. The identifier must match the source adapter's TextUnit.id, and its eligible DOM text must match that unit's text exactly. A framework/i18n application needs a source adapter that identifies its actual template or translation string. A rendered route is not itself a source filename, and translated runtime text is not interchangeable with a different-language fallback in an HTML file.

Without an explicit identifier, the bridge can temporarily mark one unique, exact visible element-text occurrence. It chooses the deepest element when an element and its only text-bearing descendant represent the same occurrence. Repeated text, duplicate unassigned source units, mismatched explicit IDs and ambiguous matches remain unmapped. It does not trim/collapse text, guess from similar wording or wrap native text nodes. Inline source fragments that do not correspond to a complete element need explicit adapter support.

Only temporary data-voice-unit attributes are added; they are restored when the review is replaced or disconnected. Native nodes, links and event handlers are preserved. Code, hidden regions, editable controls and data-voice-exclude regions are excluded. Normal DOM updates trigger remapping; refresh() is available for host-specific rendering lifecycles.

Protocol version 1#

The exported VoiceStudioParentMessage and VoiceStudioChildMessage types are the transport contract. The parent uses postMessage with the target site's exact origin and checks message origin and event.source itself. The bridge accepts only its explicitly configured Studio origin and its actual parent or opener window; after connection it retains that peer.

1. Parent sends voice-studio:connect with a fresh random sessionId (16-128 ASCII letters, digits, _ or -; crypto.randomUUID() is suitable).
2. Child replies voice-studio:ready with sessionId, protocolVersion: 1, current url and title.
3. Parent resolves the correct source document, then sends voice-studio:review with sessionId, a fresh reviewId, exact pageUrl, units, findings and feedback. pageUrl includes query and fragment. All spans remain UTF-16.
4. Child returns voice-studio:mapping with reviewId and diagnostics. Selection replies carry selection; annotation clicks return findingId or feedbackId, under voice-studio:selection, voice-studio:finding and voice-studio:feedback. Parent ignores stale session/review IDs.
5. SPA history changes, hash/popstate events and location changes send voice-studio:location. URL changes immediately clear old review anchors. Parent resolves and sends a new review for the new exact page URL.
6. Parent can send voice-studio:select-finding with sessionId, reviewId and findingId (or null) to focus a report finding, or voice-studio:navigate with sessionId and action: 'back' | 'forward' | 'reload' for native history.
7. voice-studio:disconnect clears the review and session. A full page reload creates a new bridge instance and requires a fresh connection handshake.

Malformed reviews or a review for an outdated page URL produce a scoped voice-studio:error; messages from other origins, windows or sessions are ignored.

The Studio host currently uses an iframe. The target site's CSP/frame headers must allow the Studio origin to embed it and its development CSP must allow the bridge asset and annotation styles. An external page opened with noopener has no connected Studio opener; opening it separately is ordinary browsing, not a connected review fallback. Remote pages without this opt-in bridge, closed shadow roots, unsupported source adapters and iframe-blocking headers remain explicit limitations. Live review never grants a page authority to write source files: persistence and reviewed diffs remain in the Studio backend.