EnvelopeGenerator/RECEIVER_PDF_VIEWER_CONTEXT.md

EnvelopeGenerator — Receiver PDF Viewer Context

Purpose

This document summarizes the active receiver-side PDF viewing and signing experience so that other agents can understand the current implementation quickly without re-reading all related files.

This summary is based on the active host and current implementation in:

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeReceiverPage.razor
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/pdf-viewer.js
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/receiver-signature.js
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/css/envelope-viewer.css

---

Active Page

Primary receiver page:

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeReceiverPage.razor

Route:

• /envelope/{EnvelopeKey}

Render mode:

• InteractiveServer

This page is the active receiver PDF viewing and signing UI.

---

Core Architecture

The receiver experience is built from three layers:

1. Blazor page layer

EnvelopeReceiverPage.razor is responsible for:

• authorization flow
• loading receiver-specific document data
• loading signature placeholders
• loading and saving cached signature data
• UI state management
• toolbar interactions
• popup interactions
• JS interop orchestration

2. PDF rendering layer

The active implementation currently uses PDF.js for:

• rendering the active PDF page
• rendering thumbnails
• handling zoom and page navigation state

Referenced assets in the current implementation:

• https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js
• https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf_viewer.min.css

Planned target rendering layer

The main migration goal is to replace PDF.js in EnvelopeReceiverPage.razor with DxPdfViewer while preserving the complete receiver signing experience documented in this file.

This means DxPdfViewer must become the main document rendering surface without regressing:

• single active page viewing behavior
• page navigation behavior
• zoom behavior
• thumbnail sidebar behavior
• receiver-specific signature placeholder overlays
• applied signature overlays
• signature navigation across pages
• overlay repositioning and resizing after zoom/page changes

3. Custom enhancement layer

Extra behavior is implemented through custom JavaScript and CSS:

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/pdf-viewer.js
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/receiver-signature.js
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/css/envelope-viewer.css

These files extend the base PDF.js experience with receiver-specific features.

---

Main Functional Capabilities

1. Single-page PDF viewing in the main viewer

The page shows one active PDF page at a time in the main canvas.

Main viewer elements:

• pdf-canvas
• pdf-text-layer
• pdf-signature-layer

This means the page is not using a continuous full-document scroll layout in the main area. Instead, it behaves like a single active page viewer with controlled navigation.

---

2. Page navigation

The page supports multiple navigation methods:

• previous page button
• next page button
• direct page number input
• thumbnail click navigation
• signature navigation that may jump to another page automatically

Relevant Blazor methods include:

• PreviousPage()
• NextPage()
• OnPageInputChanged(...)
• GoToPageFromThumbnail(...)
• OnPageChangedBySignatureNav(...)

---

3. Zoom support

The page supports zooming in and out for the active PDF page.

Available zoom behavior:

• zoom in button
• zoom out button
• zoom slider
• programmatic scale setting
• fit-to-width helper exists in code

Relevant methods:

• ZoomIn()
• ZoomOut()
• SetZoom(int percentage)
• OnZoomSliderChanged(...)
• FitToWidth()
• OnZoomChanged(double scale)

Current zoom constraints in the page:

• minimum: 50%
• maximum: 300%

Important behavior:

• when zoom changes, signature placeholders and applied signature overlays are re-rendered/repositioned
• position and visual size are expected to stay synchronized with the current PDF scale

---

4. Thumbnail sidebar

The page has a thumbnail sidebar for document page previews.

Supported sidebar behavior:

• show/hide toggle
• click thumbnail to navigate to page
• highlight active page
• resizable width
• width persistence in localStorage

Relevant state:

• _showThumbnails
• _thumbnailWidth
• _isResizing

Relevant methods:

• ToggleThumbnails()
• RenderThumbnailsAsync()
• OnSplitterMouseDown(...)
• OnSplitterMouseMove(...)
• OnSplitterMouseUp()

Persistence key:

• envelopeViewer_thumbnailWidth

Important implementation detail:

• thumbnail rendering is done sequentially with delay to avoid overloading the browser

---

5. Signature placeholder buttons on top of the PDF

The page places clickable signature buttons over the PDF for receiver-specific signature fields.

Behavior:

• placeholders are loaded server-side
• placeholders are rendered on the client as overlay elements
• placeholders are shown for the current page
• clicking a placeholder applies the captured signature to that location

Relevant Blazor method:

• RenderSignatureButtonsAsync()

Relevant JS interop call:

• pdfViewer.renderSignatureButtons

Important note:

• this is an overlay workflow, not direct PDF stamping
• placeholders belong to the current authenticated receiver

---

6. Applying a real signature after clicking a placeholder

Once a receiver has a captured signature, clicking a signature placeholder applies the real signature overlay to the PDF viewer.

Applied signature data includes:

• signature image data URL
• signer full name
• signer position
• place

Relevant method:

• OnSignatureButtonClick(int signatureId)

Relevant JS interop call:

• pdfViewer.applySignature

Important note:

• the active implementation visually places the signature in the viewer layer
• the page is not currently doing final PDF binary stamping in this UI flow

---

7. Signature navigation across all signature fields

The toolbar supports fast navigation between signature fields.

Supported behavior:

• go to previous signature
• go to next signature
• maintain current signature index
• show signed / unsigned / total counts
• automatically move between pages if the next signature is on another page

Relevant methods:

• GoToPreviousSignature()
• GoToNextSignature()
• OnSignatureNavChanged()
• OnPageChangedBySignatureNav(int newPage)
• UpdateSignatureCounterAsync()

Relevant JS interop calls:

• pdfViewer.goToPreviousSignature
• pdfViewer.goToNextSignature
• pdfViewer.getSignatureNavState

Counter state maintained in Blazor:

• _totalSignatures
• _signedSignatures
• _unsignedSignatures
• _currentSignatureIndex

---

8. Automatic signature/button repositioning and resizing on zoom

A critical current feature is that zoom changes should keep overlay elements visually aligned with the document.

This applies to:

• signature placeholder buttons
• applied signature overlays

Expected behavior:

• position updates when zoom changes
• size updates when zoom changes
• re-render happens after page change and zoom change

This behavior is triggered from methods such as:

• OnZoomChanged(...)
• ZoomIn()
• ZoomOut()
• OnZoomSliderChanged(...)
• NextPage()
• PreviousPage()
• GoToPageFromThumbnail(...)
• OnPageChangedBySignatureNav(...)

In practice, the page repeatedly calls:

• RenderSignatureButtonsAsync()

This is one of the key behaviors other agents must preserve.

---

9. Signature capture popup

Signature creation is handled with a DxPopup.

Popup capabilities:

• draw signature
• create typed signature
• upload signature image
• capture required signer metadata
• validate required fields before save

Tabs:

• draw
• text
• image

Relevant constants:

• SignatureTabDraw
• SignatureTabText
• SignatureTabImage

Relevant canvas/input IDs:

• envelope-signature-pad
• envelope-typed-signature-pad
• envelope-signature-image-input
• envelope-image-signature-pad

---

10. Signature capture modes

The current UI supports three signature creation modes.

Draw mode

Receiver signs directly on a canvas.

Relevant JS usage:

• receiverSignature.initialize
• receiverSignature.clear
• receiverSignature.getDataUrl
• receiverSignature.loadExistingSignature

Text mode

Receiver enters a signature as text and chooses a font.

Relevant JS usage:

• receiverSignature.initializeTyped
• receiverSignature.renderTypedSignature
• receiverSignature.clearTyped
• receiverSignature.getTypedDataUrl

Image mode

Receiver uploads an image of their signature.

Relevant JS usage:

• receiverSignature.initializeImage
• receiverSignature.clearImage
• receiverSignature.getImageDataUrl

---

11. Signature metadata requirements

The popup captures extra metadata besides the signature image.

Required

• full name
• place

Optional

• position

Relevant bound fields:

• _signerFullName
• _signaturePlace
• _signerPosition

Validation behavior in SaveSignatureAsync():

• full name must not be empty
• place must not be empty
• signature image/data must not be empty

---

12. Cached signature reuse

The page attempts to load a previously cached signature for the receiver.

Behavior:

• if cache exists, the popup does not open automatically
• if cache does not exist, the popup opens on initial load
• saving a signature stores it back through the page data service

Relevant service usage:

• PageDataService.GetCachedSignatureAsync(...)
• PageDataService.SaveCachedSignatureAsync(...)

Related state:

• _capturedSignature
• _signaturePopupVisible

Important note:

• the active cache handling is server-side through distributed cache
• the receiver signature is not only in browser state

---

13. Signature change locking after signing starts

The current page prevents changing the captured signature after at least one signature has already been applied.

Behavior:

• signature change button becomes disabled when _signedSignatures > 0
• title explains the signature is locked
• reset requires restarting the signing session

Relevant methods:

• GetSignatureButtonTitle()
• HandleSignatureChangeClick()
• RestartSigning()

Important implication:

• once actual field signing begins, the selected/captured signature is treated as fixed for that session unless the page is reset

---

14. Reset/restart signing flow

The page includes a reset/restart behavior.

Current behavior:

• page reload is used to reset signing UI state
• this clears current in-view applied signatures and session UI state

Relevant method:

• RestartSigning()

Implementation detail:

• current reset behavior is based on Navigation.NavigateTo(Navigation.Uri, forceLoad: true)

---

15. PDF quality and rendering options

The page sends rendering options from .NET to JavaScript before viewer initialization.

Relevant options include:

• thumbnail base scale
• thumbnail HiDPI support
• thumbnail max DPR
• main canvas HiDPI support
• main canvas max DPR
• smooth zoom enablement
• zoom transition duration
• rendering opacity
• zoom step percentage

These come from:

• IOptions<PdfViewerOptions>

Relevant JS call:

• pdfViewer.setQualityOptions(...)

This means rendering quality and viewer performance are configurable from server-side options.

---

16. Local storage usage

The page currently uses localStorage at least for UI preferences.

Known usage:

• thumbnail sidebar width persistence

Known key:

• envelopeViewer_thumbnailWidth

This is UI preference storage, not the main signature cache mechanism.

---

17. Receiver authorization dependency

The page is not a public PDF viewer. It depends on receiver-specific authorization.

Before loading the document:

• ReceiverAuthorizationService.AuthorizeAsync(EnvelopeKey) is executed
• unauthorized users are redirected to /envelope/login/{EnvelopeKey}

Implication for other agents:

• viewer behavior is tied to authenticated receiver context
• placeholder loading and cached signature loading are receiver-specific

---

18. Receiver-specific data loading

The page loads its data through EnvelopeReceiverPageDataService.

Main server-side data loaded:

• document bytes
• signature placeholders
• receiver envelope data
• cached signature

Important domain behavior:

• signature placeholders are filtered for the authenticated receiver
• placeholder coordinates are converted to points before UI use

This matters for any future changes involving coordinate systems or overlay placement.

---

Important Non-Goals / Current Constraints

Not acceptable as a migration outcome

The migration is not successful if it results in:

• losing any receiver-side behavior documented in this file
• replacing the current workflow with a simplified read-only PDF viewer
• removing signature placeholder overlays or applied signature overlays
• removing cross-page signature navigation
• breaking zoom-time overlay synchronization
• falling back to legacy ReceiverUI as the main implementation target
• changing the flow into direct PDF binary stamping-only behavior in the main receiver UI

Current active model

The current implementation is based on:

• EnvelopeGenerator.Server
• EnvelopeReceiverPage.razor
• PDF.js
• custom overlay and JS interop behavior

Target model

The intended target model is:

• EnvelopeGenerator.Server
• EnvelopeReceiverPage.razor
• DxPdfViewer as the main PDF rendering component
• equivalent custom behavior for overlays, navigation, zoom synchronization, and receiver signing interactions
• preservation of the current receiver-specific authorization and page data loading flow

---

Key Behaviors Other Agents Must Preserve

If another agent modifies this area, these behaviors are important to keep intact:

1. Receiver authorization before document access
2. Single active page PDF viewing
3. Page navigation and thumbnail navigation
4. Zoom in/out with correct overlay synchronization
5. Signature placeholder rendering on the correct page
6. Clicking a placeholder applies the captured signature overlay
7. Fast previous/next signature navigation across pages
8. Automatic overlay position and size updates after zoom/page changes
9. Signature popup with draw/text/image modes
10. Required metadata validation for full name and place
11. Cached signature reuse
12. Signature lock after signing has started
13. Reset/restart signing behavior
14. Thumbnail width persistence

Migration Requirement

Any migration from PDF.js to DxPdfViewer in EnvelopeReceiverPage.razor must be treated as a rendering engine swap, not a workflow redesign.

The expected outcome is:

• DxPdfViewer replaces PDF.js as the main viewer technology
• the receiver authorization model remains unchanged
• the existing signature capture popup model remains unchanged
• signature placeholder rendering remains receiver-specific
• applied signature visuals remain aligned with the rendered document
• page navigation, zoom, thumbnails, and signature navigation continue to behave equivalently
• no documented feature in this file is dropped during the migration

---

Suggested Mental Model

A useful way to think about the page is:

• EnvelopeReceiverPage.razor = orchestration and state
• current rendering engine = PDF.js
• target rendering engine = DxPdfViewer
• current viewer behavior layer = pdf-viewer.js for overlays, navigation, thumbnails, resize logic
• receiver-signature.js = signature capture/creation logic
• server page data service = receiver-specific document and signature source

---

Detailed Technical Migration Plan: PDF.js -> DxPdfViewer

This section records the implementation plan for migrating the active receiver signing experience from PDF.js to DxPdfViewer without losing any workflow behavior.

1. Core migration principle

This migration must be treated as:

• a rendering engine replacement
• not a signing workflow redesign
• not a simplification to a read-only viewer
• not a direct PDF stamping rewrite

The page-level orchestration in EnvelopeReceiverPage.razor remains the source of truth for:

• receiver authorization
• document loading
• signature placeholder loading
• cached signature loading/saving
• popup and validation flow
• signature locking rules
• reset/restart behavior
• toolbar intent

The rendering layer must be swapped while preserving those behaviors.

2. Current implementation findings from code

Based on the current files:

• EnvelopeReceiverPage.razor
• wwwroot/js/pdf-viewer.js
• wwwroot/css/envelope-viewer.css
• EnvelopeReceiverPage_DxPdfViewer.razor

the current page is tightly coupled to a custom pdfViewer JavaScript object.

That object currently owns all viewer-engine behaviors:

• PDF load and initialization
• current page state
• page rendering
• zoom rendering
• thumbnail rendering
• resize listener attachment
• signature button rendering
• applied signature overlay rendering
• signature navigation state

This means the migration cannot be done by replacing only the Razor markup. The current JavaScript object is effectively both:

• a PDF.js adapter
• and a receiver-signing overlay controller

Those responsibilities must be separated conceptually during migration.

3. Verified coordinate and viewport behavior from PDF.js

Inspection of the PDF.js source comments and implementation confirms the following useful facts:

1. PageViewport is created from:

   • viewBox
   • scale
   • rotation
   • optional offsets

2. PDF.js explicitly documents that PageViewport creates a transform that converts:

   • PDF coordinate system
   • into normal canvas-like coordinates

3. PageViewportParameters.viewBox is documented as:

   • xMin, yMin, xMax, yMax

4. getViewport(...) is documented as returning an object containing:

   • width
   • height
   • transforms required for rendering

5. convertToViewportPoint(x, y) is documented as converting:

   • PDF coordinates
   • into viewport coordinates

6. convertToPdfPoint(x, y) is documented as converting:

   • viewport coordinates
   • back into PDF coordinates
   • specifically useful for converting canvas pixel locations into PDF coordinates

7. rawDims exposes unscaled page dimensions:

   • pageWidth
   • pageHeight
   • pageX
   • pageY

8. For rotation 0, PageViewport flips the Y axis into canvas-style coordinates unless dontFlip is used.

4. Practical meaning of the current overlay math

The current pdf-viewer.js implementation does not call convertToViewportPoint(...) directly. Instead, it uses this simplified mapping:

• xPx = sig.x * scale
• yPx = sig.y * scale

This works only because the current upstream data contract already prepares signature coordinates in a way that matches the displayed page layout used by this app.

From the wider workspace context, the receiver page data service already converts placeholder coordinates to UnitOfLength.Point before they reach the UI.

Therefore, the active overlay contract is effectively:

• incoming signature coordinates are already normalized for the receiver UI
• JavaScript currently assumes a top-left, page-relative, point-based overlay space
• visual pixel placement is obtained by multiplying by current display scale

This is extremely important for the migration:

• do not casually reinterpret existing signature coordinates as raw PDF bottom-left coordinates
• do not assume DxPdfViewer uses the same visible page coordinate origin
• preserve the effective contract already used by the receiver workflow

5. Why the migration is technically hard

Although both viewers display PDFs, they are fundamentally different integration surfaces.

Current PDF.js model

• low-level canvas rendering
• direct access to viewport scale
• direct control over single page rendering
• page DOM is owned by our code
• overlays are placed over known custom elements:
  • pdf-canvas
  • pdf-text-layer
  • pdf-signature-layer

Target DxPdfViewer model

• component-driven render surface
• internal DOM is owned by DevExpress
• page layout lifecycle is controlled by the component
• zoom/page events may differ from PDF.js
• overlay host placement must be rediscovered or reintroduced

So the migration is not a canvas -> component rename. It is a viewer capability remapping problem.

6. Technical target architecture

The target architecture should be treated as four cooperating layers.

6.1 Blazor orchestration layer

Owned by EnvelopeReceiverPage.razor.

Remains responsible for:

• auth and redirect
• data loading
• signature popup state
• signature metadata validation
• cached signature reuse
• signed/unsigned counts
• restart behavior
• toolbar user intent

6.2 Viewer host layer

Main display surface becomes DxPdfViewer.

This layer must provide equivalents for:

• document load
• current page tracking
• total pages tracking
• page navigation
• zoom control
• layout change detection

6.3 Overlay adapter layer

Custom layer that translates page/zoom/layout information into overlay placement.

This layer must handle:

• signature placeholder buttons
• applied signature overlays
• page-relative visibility
• redraw after page/zoom/layout changes

6.4 Thumbnail/navigation support layer

Custom or hybrid support for:

• left sidebar thumbnails
• active page highlight
• width persistence
• signature previous/next navigation

7. Mandatory first implementation step: extract the current viewer contract

Before changing behavior, the following current pdfViewer capabilities must be listed and then mapped one-by-one to the target implementation:

• initialize
• getTotalPages
• getCurrentPage
• nextPage
• previousPage
• goToPage
• zoomIn
• zoomOut
• setScale
• getScale
• fitToWidth
• renderThumbnail
• attachResizeListeners
• startResize
• renderSignatureButtons
• applySignature
• getSignatureNavState
• goToNextSignature
• goToPreviousSignature
• dispose

The migration should preserve this capability contract at the page level even if the internal engine changes.

8. Planned migration strategy

Phase 1 — Confirm the DxPdfViewer integration surface

Use EnvelopeReceiverPage_DxPdfViewer.razor as a reference and determine exactly what DxPdfViewer exposes for:

• document content binding
• page navigation
• current page reading
• page change events
• zoom setting
• zoom change events
• page layout readiness
• DOM surface that can host overlays

Key question:

• can we reliably obtain visible page geometry from the live DxPdfViewer DOM?

If yes, overlays can be positioned relative to the rendered page. If no, a wrapper-based approximation or alternative integration is required.

Phase 2 — Replace the main render surface in EnvelopeReceiverPage.razor

The current custom canvas + text layer + signature layer block should be replaced with a DxPdfViewer host region while keeping:

• the same page route
• the same page state
• the same toolbar
• the same popup
• the same thumbnail sidebar shell

At this stage, only the main document display needs to work. Signature overlays may temporarily be disabled while the host geometry is established.

Phase 3 — Introduce a dedicated overlay host above DxPdfViewer

The new viewer surface should be wrapped with a custom page container.

Planned structure:

• outer frame
• thumbnail sidebar
• splitter
• main viewer wrapper
• DxPdfViewer
• absolute-positioned custom overlay layer

The overlay layer must be independently controlled by our code and not depend on internal PDF.js DOM ids.

Phase 4 — Rebuild page/zoom geometry acquisition

Because the current implementation derives position using only sig.x * scale, the target implementation must determine:

• currently visible page rectangle
• page top-left origin inside the wrapper
• effective display scale relative to logical point coordinates
• current page number

At redraw time, the adapter must produce page-relative pixel coordinates for:

• placeholder buttons
• applied signature blocks

This should be centralized in one geometry function rather than scattered across multiple viewer actions.

Phase 5 — Move signature overlay state to a canonical model

The current JavaScript keeps runtime state in:

• signatureButtons
• appliedSignatures
• appliedSignatureElements
• _allSignatures
• _lastViewedSignatureId

This must remain stable across redraws.

Preferably:

• Blazor continues to own the authoritative business state
• JavaScript owns transient rendered DOM state only

If necessary, applied signature state should be re-sendable from .NET after viewer redraw. That prevents losing visual signatures when page layout changes.

Phase 6 — Re-implement signature placeholder rendering on top of DxPdfViewer

The current implementation filters placeholders by:

• current page
• not already applied

That same behavior must remain.

Rendering rules to preserve:

• only placeholders for the active page are shown
• already applied placeholders are hidden as buttons
• button size grows/shrinks with zoom
• button click invokes .NET callback OnSignatureButtonClick

The existing scaling behavior uses baseScale = 1.5 as the visual reference. That visual convention should be preserved initially unless a new normalized sizing model is intentionally introduced.

Phase 7 — Re-implement applied signature rendering on top of DxPdfViewer

The current applied signature overlay includes:

• signature image
• horizontal separator line
• signer full name
• optional position
• place and date

The same visual block must be retained.

Required behavior:

• clicking a placeholder converts it to an applied signature overlay
• applied signature remains visible on the correct page
• applied signature rescales with zoom
• applied signature repositions on page/zoom changes
• applied signature is hidden when the user navigates to a different page

Phase 8 — Re-implement page navigation through a central page-change pipeline

The following actions must all converge into a single page navigation routine:

• previous page button
• next page button
• direct page number input
• thumbnail click
• signature previous/next navigation when target is on another page

That routine must do all of the following in order:

1. instruct viewer to change page
2. update canonical current page state
3. wait for rendered page surface readiness if needed
4. redraw placeholder overlays
5. refresh signature navigation counter state

Phase 9 — Re-implement zoom through a central zoom-change pipeline

The following actions must converge into one zoom update path:

• toolbar zoom in
• toolbar zoom out
• slider change
• fit-to-width
• viewer-native zoom events if the user triggers zoom through gestures

That routine must:

1. clamp to 50% - 300%
2. update canonical zoom state
3. wait for layout/render completion if needed
4. redraw placeholder overlays
5. rescale applied signatures

The current implementation already treats redraw after zoom as mandatory. That must remain true.

Phase 10 — Preserve signature navigation independently from the viewer engine

Current navigation logic is driven by the global ordered signature list and not by PDF rendering internals alone.

This behavior must remain engine-independent:

• previous/next traverses the full signature list
• traversal wraps around at the edges
• if the target signature is on another page, the viewer jumps first
• after page jump, the target element is scrolled into view
• toolbar counters reflect total/signed/unsigned/current index

If DxPdfViewer changes scrolling mechanics, the scrollToElement / scrollToButton logic must be adapted, but the traversal rules must remain unchanged.

Phase 11 — Thumbnail sidebar should remain custom unless DxPdfViewer can match all current behavior

The current sidebar is not just decorative. It also provides:

• show/hide toggle
• click navigation
• active page highlight
• resizable width
• width persistence in localStorage
• progressive rendering strategy

Because of that, the safest plan is:

• keep the custom sidebar shell and resize behavior
• only replace the source of main document rendering

If DxPdfViewer cannot provide matching thumbnails directly, a hybrid solution is acceptable:

• main document rendered by DxPdfViewer
• thumbnails still generated through a separate custom preview pipeline

This still satisfies the requirement that DxPdfViewer becomes the main viewer technology.

Phase 12 — Keep signature capture popup unchanged unless integration forces a minimal adjustment

receiver-signature.js and the popup flow should remain mostly untouched.

Preserve exactly:

• draw tab
• text tab
• image tab
• full name required
• place required
• signature data required
• cached signature reuse
• signature change lock after signing starts

This area is low-risk and should not be refactored unnecessarily during the viewer migration.

9. File-by-file execution plan

EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeReceiverPage.razor

Planned work:

• remove PDF.js CDN asset dependency from the active receiver page
• replace the custom canvas-based main surface with a DxPdfViewer host
• preserve toolbar, popup, auth, state and receiver-specific loading logic
• redirect viewer method calls through a new or adapted JS interop surface
• preserve current state fields wherever possible to minimize workflow regressions

EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/pdf-viewer.js

Planned work:

• split engine-specific logic from workflow-specific logic
• remove dependency on direct pdf-canvas rendering for the main viewer path
• introduce DxPdfViewer-compatible geometry and overlay placement helpers
• preserve signature navigation logic semantics
• preserve overlay rendering semantics
• preserve resize integration for sidebar handling

This file will likely become a viewer adapter rather than a pure PDF.js implementation.

EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/css/envelope-viewer.css

Planned work:

• keep page shell, toolbar, thumbnails, splitter and popup-related styles
• replace canvas/text-layer specific assumptions with viewer-wrapper styles
• introduce overlay host styles for the DxPdfViewer surface
• ensure z-index ordering still makes signature buttons clickable
• avoid CSS leaking into DevExpress internal DOM more than necessary

EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeReceiverPage_DxPdfViewer.razor

Planned role:

• reference only
• used to understand document binding and minimal DxPdfViewer setup
• not the primary delivery target unless portions are borrowed into the main receiver page

10. Risks that must be explicitly tested during implementation

1. DxPdfViewer may not expose visible page geometry directly.
2. DxPdfViewer may render asynchronously in a way that requires delayed overlay redraw.
3. Built-in zoom/page state may not map 1:1 to current custom toolbar assumptions.
4. Sidebar width changes may require explicit overlay recalculation.
5. Applied signatures may visually drift if scaling math is not centralized.
6. Signature navigation may fail if target DOM nodes are created later than expected.
7. Built-in viewer scrolling may differ from the current wrapper scrolling model.

11. Acceptance checklist for the migration

The migration is only acceptable if all of the following still work in the active page:

• receiver authorization before document access
• document load for the authenticated receiver
• single active page viewing
• previous/next page navigation
• direct page input navigation
• thumbnail click navigation
• zoom in/out and slider zoom
• overlay alignment after zoom changes
• signature placeholder rendering on the correct page
• placeholder click applying signature overlay
• previous/next signature navigation across pages
• signed/unsigned counters updating correctly
• cached signature reuse
• signature popup validation
• signature change lock after signing starts
• restart signing behavior
• thumbnail width persistence

12. Final implementation guidance

The correct technical approach is:

• keep EnvelopeReceiverPage.razor as the receiver workflow orchestrator
• treat DxPdfViewer as the new main rendering engine
• rebuild overlay placement as a viewer-agnostic custom layer
• preserve the current receiver-specific state machine
• preserve signature navigation rules
• preserve thumbnail/sidebar interaction model where practical

In short:

• replace the renderer
• preserve the workflow
• rebuild the overlay adapter
• do not redesign the signing experience

---

Files Most Likely Relevant For Future Work

Main page

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/Components/Pages/EnvelopeReceiverPage.razor

JavaScript

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/pdf-viewer.js
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/js/receiver-signature.js

CSS

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/wwwroot/css/envelope-viewer.css

Data/auth services

• EnvelopeGenerator.Server/EnvelopeGenerator.Server/Services/EnvelopeReceiverAuthorizationService.cs
• EnvelopeGenerator.Server/EnvelopeGenerator.Server/Services/EnvelopeReceiverPageDataService.cs

---

Summary

The active receiver document experience is currently a PDF.js-based, server-orchestrated, overlay-signing workflow in EnvelopeGenerator.Server.

It supports:

• single-page PDF display
• page navigation
• zoom
• thumbnails
• receiver-specific signature placeholders
• actual signature overlay placement
• fast signature navigation across pages
• overlay rescaling/repositioning during zoom
• signature capture via draw/text/image
• cached signature reuse

The current migration goal is to move this experience to DxPdfViewer in EnvelopeReceiverPage.razor without losing any of the capabilities listed above.

Any future changes in this area should be made with the assumption that this is a custom receiver signing experience whose rendering engine may change, but whose functional behavior must remain intact; it is not a basic document embed and not a direct PDF stamping pipeline.