Message APINPM Package/docs/workflows/revision/compare

Compare Revisions

Run the comparison request, manage host UI state, and present the visual difference result safely.

Comparison Flow

Preconditions: The background and overlay files are prepared. If alignment is required, complete the align flow first. The viewer session is ready to receive commands.

  • 1Collect compare options from validated UI controls, including DPI and configured difference colors supported by the Revision API.
  • 2Lock the compare form before sending the request so the user cannot modify URLs or submit a duplicate job mid-flight.
  • 3Call viewer.compare.compare(...) with the prepared background and overlay targets.
  • 4Listen for viewer events until a terminal outcome is received.
  • 5On comparisonComplete, clear loading state, close transient dialogs, show success state, and display the returned comparison result.
  • 6On comparisonError, clear loading state, show a recoverable error message, keep inputs editable, and allow manual retry.
  • 7Keep retry scoped to the current inputs unless the user changes files, DPI, colors, or alignment path intentionally.

Host UI States

A robust implementation should make the current state obvious and prevent conflicting actions.

  • Idle: Inputs are editable and compare can be started when validation passes.
  • Processing: Inputs and submit actions are disabled while the viewer is working.
  • Success: The comparison result is visible and navigation, zoom, export, or download controls can be enabled as supported by the host application.
  • Failure: The error is visible, inputs are unlocked, and the user can correct the issue or retry.
  • Cancelled: Alignment or comparison-related transient UI is closed and no stale loading indicator remains.

Expected Result

The viewer displays a difference rendering that uses the configured comparison colors, and the host application has a clean success state with no pending loading locks.

Recovery

If comparison fails, translate the technical error into a user-facing message, preserve the entered files and settings, and give the user a next action such as retry, lower DPI, replace a file, refresh authorization, or run alignment first.

Low-Level Technical Specifications

Do not duplicate payload definitions in this workflow page. Use the component references for exact command names, fields, event names, and valid option values.