Rasterex APINPM Package/docs/workflows/live-sync-review/overview

Synchronize Multiple Viewspaces

Coordinate two drawing viewers, synchronize their navigation, and record discipline findings with the NPM SDK.

Scope and prerequisites

GitHub example

Read the Discipline Coordination README and source.

Viewers Sync API

Snapshot, ordered relay, results, and lifecycle contracts.

Collaboration API

Participant identity and document-specific collaboration.

Integration mode: NPM SDK. The live-sync-review React example creates two independent viewers with @rasterex/viewer. Configure a compatible Canvas deployment supporting view synchronization and the collaboration bridge. Each viewer must finish readiness and document loading before synchronization is enabled.

The reference coordinates two panes. Additional panes require host routing to every eligible sibling, independent readiness, and sequence tracking for every source.

Run the React example

Run these commands from the workflow-examples repository root. VITE_CANVAS_URL is an example host setting read by App.tsx; set it to your compatible Canvas deployment when required. The package manifest declares @rasterex/viewer ^2.1.3; verify the installed version and deployment against the linked API references.

git clone https://github.com/Rasterex-Software/workflow-examples.git
cd workflow-examples
npm --prefix live-sync-review install
npm --prefix live-sync-review run dev
Run the React example

Operator workspace

Two drawing panes have independent discipline selectors, file controls, annotation toolbars, loading feedback, and Save markups actions. The shared toolbar contains participant identity and Enable sync & collaboration. A collapsible review register holds findings with title, description, assignee, priority, and status.

The reference permits drawing-level findings as well as findings linked to a confirmed annotation GUID. Selecting a linked finding targets its annotation only while the matching document is open. Findings remain in browser-session memory.

Implementation order and current state

  • 1Create, mount, and ready each viewer independently; register subscriptions before exposing actions.
  • 2Open a drawing in each pane and confirm document readiness. Validate HTTP or HTTPS URLs and a non-empty participant name.
  • 3Keep relay disabled and configure the same groupId with a distinct instanceId for each viewer.
  • 4Capture the first viewer snapshot and await its application to the second.
  • 5Await participant identity results and check success before enabling synchronization.
  • 6Enable the configured viewers, request collaboration, then allow accepted navigation changes to relay.
  • 7Stop relay and disable synchronization and collaboration before replacing a drawing. Reset source sequence tracking and repeat alignment.

Confirmed synchronization and collaboration

Use viewer.viewSync.configure({ groupId, instanceId, mode: "panAndZoom", enabled: false }), viewer.viewSync.getSnapshot({ groupId }), and target.viewSync.applySnapshot(snapshot) for initial alignment. Their results establish whether setup succeeded. Compatible pages, viewer geometry, and coordinates are required; unrelated discipline drawings may fail snapshot alignment.

Subscribe with viewer.viewSync.on("changed", handleChanged), viewer.viewSync.on("applied", handleApplied), and viewer.viewSync.on("failed", handleFailed). Forward fresh changes using sibling.viewSync.apply(change, { pan, zoom }); this sends immediately, so remote success comes from the applied or failed event.

Accept only the configured group and locally originating instance, drop duplicate or older sequences, and never relay to the source. Preserve operation order. Call viewer.collaboration.setUser({ username, displayName }) and inspect success before viewer.collaboration.enable(). Enable is fire-and-forget: show collaboration as requested. Default rooms are document-specific; use the same document for shared annotations.

Failure, cancellation, and persistence

On setup or relay failure, stop forwarding immediately, disable the group, keep documents available, and offer Enable sync & collaboration again after fresh snapshot alignment. Disabling synchronization leaves both files open.

Save markups awaits viewer.annotations.save() and checks success. This does not persist the host findings register. Store findings through your own backend if required. On unmount, stop relay, unsubscribe every listener, and destroy both viewers.

Verification checklist

  • Sync remains unavailable until both documents are ready and identity input is valid.
  • Setup shows pending feedback and stays disabled if snapshot application fails.
  • Pan and zoom reach each sibling once, in order, with no feedback loop; stale and wrong-group events are ignored.
  • Collaboration status says requested until a documented connection condition is available.
  • File replacement and Disable stop relay; retry establishes a fresh snapshot.
  • Findings and annotation saves report their own persistence state.
  • Keyboard controls, status announcements, modal focus, cancellation, and small-screen pane layout remain usable.
  • Route exit removes subscriptions and destroys both viewers; remount does not duplicate relay.