Message APINPM Package/docs/workflows/revision/overview

Compare And Align Overview

Build a revision workspace that compares two drawing versions or interactively aligns them first, with NPM event-confirmed progress, results, errors, and save state.

Workflow Goal

Revision comparison uses an older background drawing and a newer overlay drawing to show changed, removed, and unchanged content. The operator should always know whether Canvas is ready, processing, waiting for alignment points, complete, failed, or saving output.

Reference Workspace

The reference UI is a dark engineering workspace: a small application header, a persistent action ribbon, a collapsible sidebar, a large Canvas viewport, and a footer status area. Preserve that information hierarchy in host UI while using only NPM SDK methods and events.

  • Ribbon: Compare Documents, Align Drawings, Save Comparison, and a compact status badge.
  • Sidebar: background and overlay sources, DPI, background/overlay/equal colors, output name, and result metadata after completion.
  • Canvas viewport: normal drawing surface, processing overlay, and a focused instruction while the operator picks interactive alignment points.
  • Footer or live region: current operation message and error feedback that remains available when the sidebar is collapsed.

Workflow Order

The host UI should advance only on documented events, not when a command has been clicked.

  • 1Mount the NPM viewer and register compare listeners.
  • 2Collect and validate distinct background and overlay sources plus rendering options.
  • 3Use Compare when the source coordinates already match.
  • 4Use interactive Align when the drawings are shifted, rotated, scaled, cropped, scanned, or exported differently.
  • 5Keep actions locked while Canvas processes or waits for point selection.
  • 6Show result metadata and enable Save after a result payload confirms completion.
  • 7Use error and save-complete events to unlock retry or show saved confirmation.
  • 8Unsubscribe and destroy the viewer when the route is left.

Compare Or Align

Coordinate agreement is the decision point. Direct compare can complete on offset drawings, but it creates a misleading diff because unchanged geometry appears changed.

  • Compare directly when page size, orientation, scale, margins, and layout coordinates are already equivalent.
  • Align interactively when the drawings do not share coordinates and an operator can select matching points in Canvas.
  • Do not call direct compare merely because both URLs are valid; visually verify whether the sources share the same coordinate system.

Required UI States

The revision setup is a stateful workspace. These states make the real operator workflow understandable and prevent premature success feedback.

  • 1Ready: Compare and Align are enabled; Save is disabled.
  • 2Processing: show progressStart message over Canvas and lock the action ribbon.
  • 3Pick points: an empty comparisonComplete from interactive align tells the operator to select matching points; remain locked.
  • 4Complete: a result payload shows metadata and enables Save.
  • 5Error: comparisonError displays recoverable feedback and returns Compare and Align to an enabled state.
  • 6Saved: compareSaveComplete confirms the output name; the completed result remains available.

Workflow Pages

React Setup

Copy the NPM React Compare and Align workspace, lifecycle hook, event states, and responsive UI.

Angular Setup

Mount and clean up the viewer through Angular lifecycle hooks.

Prepare Revisions

Validate sources and decide whether their coordinates permit direct comparison.

Align Revisions

Guide the operator through the intermediate point-picking state and final alignment result.

Compare Revisions

Run direct comparison and render event-confirmed progress, result, and retry states.

Error Handling

Map NPM comparison failures to visible and recoverable host UI states.

Verification Checklist

Verify progress, point selection, result confirmation, saving, error recovery, and cleanup.

Use these pages to implement and verify the workflow.

NPM References

Use component documentation for exact payload fields and event types.