diff --git a/SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md b/SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md new file mode 100644 index 00000000..dc8ee9d3 --- /dev/null +++ b/SENDER_EDITOR_WASM_PDF_EDITOR_IMPLEMENTATION_PLAN_en.md @@ -0,0 +1,212 @@ +# 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**