Client-Side Revision Review

Integration mode: NPM SDK. The revision-review React example uses viewer.clientCompare in one Canvas viewer. Wait for mount and readiness, then prepare an original and revised source. The comparison remains in Canvas and returns viewer file contexts; use the server comparison workflow when a generated comparison file is required.

Run from the workflow-examples repository root. The standalone example reads VITE_CANVAS_URL for a compatible Canvas deployment. Install its own dependencies; the README describes a temporary dependency link in the author workspace, which is unnecessary for a fresh checkout. The package manifest declares @rasterex/viewer ^2.1.3.

git clone https://github.com/Rasterex-Software/workflow-examples.git
cd workflow-examples
npm --prefix revision-review install
npm --prefix revision-review run dev

The source sidebar has Original and Revised selectors, sample revisions, alignment, revision balance, and common-geometry controls. The central drawing shows the overlay, legend, pending feedback, point-selection instructions, and Close comparison. The review register holds manual findings, owners, resolution status, reviewer identity, inspection confirmation, and handoff notes.

• 1Mount and await readiness; register alignComplete, failed, and closed listeners before commands.
• 2Prepare one source per role. Selecting a URL only prepares input; clientCompare.create loads the URL pair.
• 3For uploads, use the Canvas-resolved identity supported by the installed document API. Use URLs when that identity cannot be verified.
• 4Await comparison creation before enabling appearance and alignment.
• 5Inspect, optionally align, and enter manual findings in the host register.
• 6Record a review decision only after inspection confirmation and reviewer input; unresolved findings require follow-up.
• 7Close comparison for cancellation or source replacement, and clean up subscriptions and the viewer on route exit.

backgroundUrl and overlayUrl below are validated host-selected HTTP or HTTPS sources. Provide one URL or Canvas-resolved filename for each role, and ensure distinct revision identities. Keep duplicate requests locked and preserve the selected pair on failure.

const comparison = await viewer.clientCompare.create({
  backgroundUrl,
  overlayUrl,
  backgroundColor: "#E86767",
  overlayColor: "#0E3BD8"
});
await viewer.clientCompare.setOpacity(50);
await viewer.clientCompare.setCommonLevel(5);

States are connecting, ready to prepare, creating, comparison ready, aligning, failed, and closed. Await viewer.clientCompare.startAlign() for the start acknowledgement, then retain the aligning state until viewer.clientCompare.on("alignComplete", handleAlignComplete) or viewer.clientCompare.on("failed", handleFailed) advances it.

During alignment, disable creation and appearance controls, show matching-point instructions, and retain Cancel & close comparison. Await viewer.clientCompare.close() before retrying. Source documents remain open. Keep subscriptions installed throughout point selection.

Opacity accepts finite values from 0 to 100: 0 fades the original background and 100 fades the revision overlay. Common level accepts 1 to 10, from near white to black. Keep requested slider values distinct from confirmed command results.

The reference stores manual findings and review decisions in localStorage keyed by the source URL or Canvas-filename pair, and exports JSON. Findings are host records; they are not automatically detected differences or linked Canvas annotations. Review completion is a host decision, not formal engineering approval.

If storage is unavailable, expose Export review before leaving. Preserve sources for comparison retry, invalidate pending UI state on source changes, and offer reconnect after readiness failure. Clear timers, abort pending readiness where supported, unsubscribe, and destroy the viewer on cleanup.

• Initial controls remain unavailable until readiness; slow connection exposes useful feedback and reconnect.
• URL selection prepares inputs; comparison controls become ready only after the correlated create result.
• Appearance controls enforce their documented ranges and handle rejection.
• Alignment remains pending after start acknowledgement and completes only after both matching points.
• Cancel closes comparison and permits a fresh attempt; failure preserves valid sources.
• Review records are scoped to the source pair; storage failure offers export.
• Complete review requires inspection, reviewer identity, and no open findings; follow-up handles outstanding findings.
• Controls support keyboard access, accessible labels and status, and usable small-screen layout.
• Route cleanup removes timers and subscriptions and destroys the viewer without late state updates.