# 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**