EnvelopeGenerator/SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md

Sender Editor PDF Component Migration Plan

This plan is prepared to remove the DevExpress PDF viewer dependency from EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeSenderEditorPage.razor and move to a new WASM-based PDF editor component while preserving the current page design.

0) Scope and Non-Negotiable Rules

• Scope: Only the PDF editor/viewer area will change; the page action bar, popups, receiver management, and overall visual language must remain intact.
• Render mode target: The /sender/editor flow will be implemented in EnvelopeGenerator.Server.Client and run in WebAssembly.
• Data compatibility: The final CreateEnvelopeCommand payload shape, field units (X, Y in inches), receiver-field mapping, and save/send behavior must stay unchanged.
• To be removed: esid query param + IMemoryCache-based editor session persistence will be removed completely.
• Library constraint: pdf.js and DevExpress PDF viewer will not be used. For PDF rasterization, first verify whether DevExpress provides a suitable capability; if not, use a reliable, popular MIT-licensed alternative.
• Server-side pattern rule: All new server-side work must follow the existing architecture; Clean Architecture layers and MediatR pattern must be preserved.
• Language rule (code side): All code and any code comments must always be in English.

---

1) Current Behavior Inventory (Parity Baseline)

Goal: Lock down all behaviors that must not break after migration.

Tasks

• List the current editor flow:
  • PDF upload,
  • receiver add,
  • signature field placement,
  • field clearing,
  • draft save,
  • send.
• Clarify current coordinate conversion:
  • Viewer click -> PDF points,
  • Save payload -> inches (pt / 72).
• Capture current validation messages and popup behavior.
• During this inventory phase, continuously add findings into this markdown under the relevant sections so it remains a living document.

Output

• A short “parity checklist” is prepared and used throughout development.

---

2) Architecture Decisions and Packaging

Goal: Define technical boundaries of the new solution.

Tasks

• Define the new reusable component:
  • Suggested name: SenderPdfImageEditor.
  • Location: EnvelopeGenerator.Server/EnvelopeGenerator.Server.Client/Components/PdfEditor/.
• Define PDF rasterization strategy:
  • Convert PDF -> image pages on the server side.
  • First confirm whether this conversion is possible with DevExpress.
  • If DevExpress does not provide a suitable solution, choose a popular MIT-licensed engine (e.g., Docnet.Core / PDFium-based).
  • Document license validation and production suitability.
• Draft API contract:
  • endpoint(s) returning page images after PDF upload/read,
  • page metadata (width/height in pt),
  • optional re-raster endpoint for higher zoom levels.

Output

• “Component contract + API contract” is finalized.

---

3) Copy /sender/editor to WASM Page

Goal: Run the editor in Server.Client using SPA behavior.

Tasks

• Create a new page:
  • EnvelopeGenerator.Server/EnvelopeGenerator.Server.Client/Pages/EnvelopeSenderEditorPage.razor
  • Temporary route: /sender/editor2
• Keep the existing server-side /sender/editor page during development; both pages run in parallel.
• Copy existing toolbar/receiver/popup markup as-is as much as possible.
• Integrate client services (EnvelopeService, auth checks, receiver suggestion calls).

Output

• WASM page is accessible, old UI layout is preserved, and PDF area works with a placeholder component.

---

4) Page-by-Page PDF to Image Conversion Service (With Priority Order)

Goal: Convert PDF into page-image list with near-identical visual fidelity.

Tasks

• Add new application/service layer:
  • PDF bytes input,
  • raster output per page (PNG preferred for stable quality/transparency).
• Evaluate client-side (WASM) rasterization feasibility if it is possible and does not hurt performance.
• Priority order:
  1. DevExpress feasibility,
  2. If not suitable, MIT-licensed alternative,
  3. If needed, client-side rasterization option.
• Return metadata:
  • page index,
  • image URL or base64,
  • page width/height (pt),
  • native image size in px.
• Performance:
  • reasonable initial DPI (e.g., 144),
  • lazy/high-res render option for higher zoom levels.

Output

• “PDF -> image pages + page metrics” endpoint/service is functional.

---

5) New Image-based PDF Viewer Features

Goal: Provide viewer UX similar to DevExpress viewer.

Tasks

• Implement two display modes in SenderPdfImageEditor:
  • Continuous mode: pages stacked vertically,
  • Single-page mode: one page with next/prev navigation.
• Add zoom controls:
  • zoom in/out,
  • fit width,
  • fit page.
• Add page navigation:
  • page selector (n / total),
  • keyboard shortcuts (optional, phase 2).
• Preserve UI consistency:
  • keep current sender editor color language and button style.

Output

• Image-based viewer is fully functional.

---

6) Signature Field Management via DOM Overlay

Goal: Manage signature fields in a movable DOM layer instead of burning them into PDF bytes.

Tasks

• Place an overlay layer on top of each page image.
• Signature box lifecycle:
  • add (by click),
  • drag (move),
  • remove.
• Normalize all interactions as page-relative coordinates.
• Rendering:
  • receiver color,
  • receiver name,
  • box/badge style close to current placeholder visuals.
• Preserve multi-receiver / multi-field support and receiver-field linkage.

Output

• Users can move and delete each signature field independently.

---

7) Coordinate and Payload Parity (Critical)

Goal: Keep backend data type/unit behavior exactly unchanged.

Tasks

• Convert overlay coordinates -> PDF points:
  • xPt = normalizedX * pageWidthPt
  • yPt = normalizedY * pageHeightPt
• Keep points -> inches conversion on save/send:
  • X = xPt / 72, Y = yPt / 72.
• Use the same DTO shape in CreateEnvelopeCommand.
• Keep existing validation rules unchanged.

Output

• Full backend contract parity with the old system.

---

8) Remove Session Cache Logic

Goal: Fully remove esid and memory cache dependency.

Tasks

• Remove SupplyParameterFromQuery(Name = "esid").
• Remove IMemoryCache injection and PersistSession flow.
• Manage editor state using component state + loaded envelope data only.
• Clarify reset behavior after successful save/send.

Output

• Session-id-based cache layer is removed completely.

---

9) Testing and Acceptance Criteria

Goal: Verify migration is complete and safe.

Critical manual tests

• PDF upload -> are pages visually accurate?
• Continuous/single-page mode transitions work correctly?
• Overlay boxes keep correct position across zoom levels?
• Add/drag/remove works stably on all pages?
• Draft save and send payload format remains identical?
• In edit mode (existing envelope), fields load and remain editable?

Definition of done

• DevExpress PDF viewer is fully removed from the editor.
• Users can edit signature box positions after placing them.
• Backend contract and coordinate units remain unchanged.

---

10) Suggested Implementation Sequence (Short Sprint Plan)

1. WASM page copy + route stabilization
2. PDF raster API + renderer integration
3. Image viewer (zoom + navigation + modes)
4. Overlay signature layer (add/drag/remove)
5. Save/Send payload parity verification
6. Session/cache removal cleanup
7. End-to-end testing and UI polish