# OPEN TASK - Session 12 (INCOMPLETE)

## Task Description
Update coordinate system documentation in `COPILOT_CONTEXT_EN.md` and C# XML documentation files to reflect the correct unit (INCHES, not 1/100 inch).

## Status
**FAILED** - PowerShell timeout, files not updated

---

## What Was Discovered

### 1. Database Stores INCHES (Not DX Units)
**Source:** `EnvelopeGenerator.Form/frmFieldEditor.vb` (VB.NET legacy project)

**Technology:** GdPicture14.Annotations.AnnotationStickyNote

**Code Evidence:**
```vb
'Breite und Hφhe in Inches (4,5*5cm)
Private Const SIGNATURE_WIDTH As Single = 1.77   ' 1.77 inches = 4.5cm
Private Const SIGNATURE_HEIGHT As Single = 1.96  ' 1.96 inches = 5cm

Sub LoadAnnotation(pElement As Signature, ...)
    oAnnotation.Left = CSng(pElement.X)      ' Direct assignment ? INCHES
    oAnnotation.Top = CSng(pElement.Y)
    oAnnotation.Width = CSng(pElement.Width)
    oAnnotation.Height = CSng(pElement.Height)
End Sub
```

**Location:** `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\frmFieldEditor.vb`

### 2. Incorrect Documentation Found

| File | Line | Wrong Claim | Correct Value |
|------|------|-------------|---------------|
| `COPILOT_CONTEXT_EN.md` | ~43 | "1/100 inch (DX units)" | **INCHES** |
| `ReceiverUI/Models/AnnotationDto.cs` | 3-15 | "Hundredths of an inch" | **INCHES** |
| `Application/Common/Dto/AnnotationCreateDto.cs` | 29-69 | "Hundredths of an inch (1/100 inch)" | **INCHES** |

---

## What Needs To Be Done

### Task 1: Update `COPILOT_CONTEXT_EN.md`

**File:** `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\COPILOT_CONTEXT_EN.md`

**Action:** Replace section `## AnnotationDto — Coordinate System` (around line 43)

**New Section Title:** `## SignatureDto / AnnotationDto — Coordinate System`

**New Content Must Include:**
1. **Database storage format:** INCHES, top-left origin
2. **Source evidence:** VB.NET code snippet from `frmFieldEditor.vb`
3. **Conversion formulas:**
   ```
   Inches ? DevExpress (DX):  multiply by 100
   Inches ? PDF Points:       multiply by 72
   Inches ? PDF.js Canvas:    normalize to page size, then scale to pixels
   ```
4. **Unit comparison table:**

| System | Unit | Origin | Conversion from INCHES |
|--------|------|--------|------------------------|
| **GdPicture14** (Source) | **Inches** | Top-left | Database format |
| DevExpress (LEGACY) | 1/100 inch (DX) | Top-left | `x_DX = x_inches * 100` |
| PDF.js (NEW) | Pixels | Top-left | `normalize ? scale` |
| PDF Points (iText7) | Points (1/72") | **Bottom-left** | `x_pt = x_inches * 72` + Y-flip |
| PSPDFKit (Web) | Points (1/72") | Top-left | `x_pt = x_inches * 72` |

**Problem:** Special characters (— and •) in file causing regex issues. Use exact string match or manual edit.

---

### Task 2: Update C# XML Documentation

#### 2.1 `EnvelopeGenerator.ReceiverUI/Models/SignatureDto.cs`
**Location:** `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\SignatureDto.cs`

**Current State:** Missing XML documentation

**Action:** Add XML docs to class and properties:
```csharp
/// <summary>
/// Represents a signature position on a PDF page.
/// Coordinates stored in INCHES (GdPicture14 native unit).
/// Origin: Top-left corner, X increases right, Y increases down.
/// </summary>
public class SignatureDto
{
    /// <summary>Unique identifier.</summary>
    public int Id { get; set; }

    /// <summary>Horizontal position in INCHES from left edge.</summary>
    public double X { get; set; }

    /// <summary>Vertical position in INCHES from top edge.</summary>
    public double Y { get; set; }

    /// <summary>1-based page number.</summary>
    public int Page { get; set; }
}
```

---

#### 2.2 `EnvelopeGenerator.ReceiverUI/Models/AnnotationDto.cs`
**Location:** `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\AnnotationDto.cs`

**Lines to Change:** 3-15 (XML doc comments)

**Current (WRONG):**
```csharp
/// <b>Coordinate unit (X, Y):</b> Hundredths of an inch (1/100 inch ? 2.83 PDF points),
```

**Correct:**
```csharp
/// <b>Coordinate unit (X, Y):</b> Inches (GdPicture14 native unit),
```

**Full Updated XML Doc:**
```csharp
/// <summary>
/// Represents a pre-assigned signature annotation position on a specific page.
/// <br/><br/>
/// <b>Coordinate unit (X, Y):</b> Inches (GdPicture14 native unit),
/// origin at the <b>top-left</b> corner of the page, both axes increase downward/rightward.
/// <br/><br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>xDX = xInches * 100.0</c>
/// <br/>
/// <b>Conversion to PDF Points:</b> Multiply by 72 (1 inch = 72 points).
/// Convert: <c>xPt = xInches * 72.0</c>
/// <br/>
/// <b>Y-axis for PDF (bottom-left origin):</b> Flip required for iText7.
/// Convert: <c>yPt = (pageHeightInches - yInches - elemHeightInches) * 72.0</c>
/// </summary>
[Obsolete("Use SignatureDto with SignatureService.")]
public record AnnotationDto
{
    /// <summary>Unique identifier of the annotation.</summary>
    public long Id { get; init; }

    /// <summary>1-based page number within the document.</summary>
    public int Page { get; init; }

    /// <summary>Horizontal position in INCHES from the left edge of the page.</summary>
    public double X { get; init; }

    /// <summary>Vertical position in INCHES from the top edge of the page.</summary>
    public double Y { get; init; }
}
```

---

#### 2.3 `EnvelopeGenerator.Application/Common/Dto/AnnotationCreateDto.cs`
**Location:** `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Application\Common\Dto\AnnotationCreateDto.cs`

**Lines to Change:** 29-69 (XML doc for `X` and `Y` properties)

**Current X Property (WRONG):**
```csharp
/// <summary>
/// Horizontal position of the signature field on the page.
/// <br/><br/>
/// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ? 2.83 PDF points), origin at the <b>top-left</b> corner of the page, X increases to the right.
/// <br/>
/// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin but measures in PDF points (1/72 inch).
/// To convert: <c>xDevExpress = xPsPdfKit * (100.0 / 72.0)</c>
/// <br/>
/// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin (standard PDF coordinate system).
/// The X axis is the same direction, only unit conversion is needed: <c>xDevExpress = xGdPicture * (100.0 / 72.0)</c>
/// </summary>
public double? X { get; init; }
```

**Correct X Property:**
```csharp
/// <summary>
/// Horizontal position of the signature field on the page.
/// <br/><br/>
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, X increases to the right.
/// <br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>xDX = xInches * 100.0</c>
/// <br/>
/// <b>Conversion to PDF Points:</b> Multiply by 72 (PSPDFKit, iText7 use 1/72 inch).
/// Convert: <c>xPt = xInches * 72.0</c>
/// </summary>
public double? X { get; init; }
```

**Current Y Property (WRONG):**
```csharp
/// <summary>
/// Vertical position of the signature field on the page.
/// <br/><br/>
/// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ? 2.83 PDF points), origin at the <b>top-left</b> corner of the page, Y increases downward.
/// <br/>
/// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin and Y increases downward, but measures in PDF points (1/72 inch).
/// To convert: <c>yDevExpress = yPsPdfKit * (100.0 / 72.0)</c>
/// <br/>
/// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin, so Y increases <b>upward</b> (PDF standard).
/// To convert: <c>yDevExpress = (pageHeightInPt - yGdPicture - elementHeightInPt) * (100.0 / 72.0)</c>
/// </summary>
public double? Y { get; init; }
```

**Correct Y Property:**
```csharp
/// <summary>
/// Vertical position of the signature field on the page.
/// <br/><br/>
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, Y increases downward.
/// <br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>yDX = yInches * 100.0</c>
/// <br/>
/// <b>Conversion to PDF Points (top-left origin):</b> Multiply by 72.
/// Convert: <c>yPt = yInches * 72.0</c>
/// <br/>
/// <b>Conversion to PDF Points (bottom-left origin - iText7):</b> Y-flip required.
/// Convert: <c>yPt = (pageHeightInches - yInches - elemHeightInches) * 72.0</c>
/// </summary>
public double? Y { get; init; }
```

---

## Additional Context

### Key Code Files
1. **Source of Truth (VB.NET):**
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\frmFieldEditor.vb`
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\Controllers\FieldEditorController.vb`

2. **C# DTOs (Need Update):**
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\SignatureDto.cs`
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\AnnotationDto.cs`
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Application\Common\Dto\AnnotationCreateDto.cs`

3. **Documentation (Need Update):**
   - `E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\COPILOT_CONTEXT_EN.md`

### Database Schema
**Table:** `TBSIG_DOCUMENT_RECEIVER_ELEMENT`

**Columns:**
- `POSITION_X` (FLOAT) — Stores INCHES
- `POSITION_Y` (FLOAT) — Stores INCHES
- `WIDTH` (FLOAT) — Stores INCHES
- `HEIGHT` (FLOAT) — Stores INCHES
- `PAGE` (INT) — 1-based page number

---

## Unit Conversion Quick Reference

```
Database (GdPicture14):  Inches, top-left origin

? DevExpress (LEGACY):   x_DX = x_inches * 100       (1/100 inch units)
                        y_DX = y_inches * 100

? PDF Points (iText7):   x_pt = x_inches * 72        (bottom-left origin)
                        y_pt = (pageHeight_inches - y_inches - height_inches) * 72

? PDF.js Canvas:         normalize to [0,1], then scale to pixels
                        x_normalized = x_inches / pageWidth_inches (e.g., 8.27 for A4)
                        y_normalized = y_inches / pageHeight_inches (e.g., 11.69 for A4)
                        x_pixel = x_normalized * canvasWidth * scale * dpr
                        y_pixel = y_normalized * canvasHeight * scale * dpr

? PSPDFKit (Web):        x_pt = x_inches * 72        (top-left origin)
                        y_pt = y_inches * 72
```

**A4 Page Dimensions:**
- Width: 8.27 inches = 595 points = 827 DX units
- Height: 11.69 inches = 842 points = 1169 DX units

---

## Notes for Next AI

1. **DO NOT** assume DevExpress units in database
2. **DO NOT** use PowerShell regex on UTF-8 files with special chars
3. **USE** `replace_string_in_file` tool with exact string match
4. **VERIFY** changes in all 4 files (1 markdown + 3 C# files)
5. **TEST** conversions with sample data (e.g., x=1.77, y=1.96)

---

## Session 12 Changes Already Completed

1. ? Added `SignatureService` to DI (`EnvelopeGenerator.ReceiverUI/Program.cs`)
2. ? Fixed YARP routes for Blazor WASM static files (`EnvelopeGenerator.API/yarp.json`):
   - Added routes for `appsettings.json`, `appsettings.Development.json`
   - Added route for `*.styles.css` files
   - Added routes for `/fonts/`, `/images/`
   - Removed `/wwwroot/` route (redundant)
   - Removed `receiver-ui-annotation-fake` route (no longer needed)

3. ? `EnvelopeViewer.razor` now successfully:
   - Loads PDF via `DocumentService`
   - Loads signatures via `SignatureService`
   - Displays PDF with PDF.js viewer
   - Console logs signature data (visible in browser F12)

---

## End of Task Description