Server-Side Notebook to PDF/SVG Converter

[allenporter]

Summary & Context

Existing Capabilities: Our codebase already implements the underlying PDF converter engine (supernote/notebook/converter.py) and the official Supernote device OpenAPI endpoint (POST /api/file/note/to/pdf).

Scope of Issue #166

This issue builds on top of our existing converter logic to provide user-facing filesystem exports and direct web downloads:

1. Automated Background Export on Sync: Automatically trigger PDF conversion during background note processing, outputting flattened PDFs into user-facing filesystem targets (/Export/ or WebDAV /Export/).
2. Simplified Web UI Download Route: Add GET /api/web/files/{id}/export/pdf for direct 1-click browser downloads (bypassing the multi-step OpenAPI blob handshake).
3. Vector SVG Export Endpoint: Add GET /api/web/files/{id}/export/svg?page={n} for single-page vector SVG rendering.

[allenporter]

Detailed Technical Implementation Plan

1. User Journeys & Example Use Cases

• Journey A: One-Click PDF Export from Web UI

  • Scenario: User recorded handwritten notes and diagrams in a .note notebook. They need to share a PDF copy with colleagues.
  • Workflow:
    1. Open Supernote Web UI.
    2. Click on notebook -> select "Export as PDF".
    3. Browser downloads a crisp, multi-page vector-rendered PDF document.
  • Outcome: Notebook is rendered into a standard PDF with pressure-sensitive strokes and background templates intact.

• Journey B: Automated PDF Backup & Export Folder

  • Scenario: User wants all synced notebooks auto-converted into PDFs inside an /Export/ directory.
  • Workflow: Background processor runs PDFExportModule upon sync completion, maintaining up-to-date PDF copies.

---

2. Requirements & Technical Specifications

A. Converter Engine (supernote/server/services/pdf_export.py)

• Leverage existing stroke parsing modules and :

  class PDFExportService:
      async def convert_note_to_pdf(self, note_path: str, output_stream: BinaryIO) -> None:
          # 1. Parse .note binary pages and stroke data
          # 2. Render background template grids
          # 3. Draw vector pen strokes using reportlab.pdfgen.canvas.Canvas
          # 4. Save multi-page PDF document

B. API Endpoints (supernote/server/routes/extended.py)

• GET /api/web/files/{id}/export/pdf: Generate and stream PDF document (Content-Type: application/pdf).
• GET /api/web/files/{id}/export/svg?page={n}: Return vector SVG render for a specific page (Content-Type: image/svg+xml).

---

3. Verification & Testing Plan

• Automated Unit Tests (tests/server/test_pdf_export.py):
  • Test vector stroke parsing and multi-page PDF generation.
  • Verify output buffer starts with valid PDF header (%PDF-1.4).
  • Verify endpoint returns 200 with application/pdf content type.

[allenporter]

💡 Clarification & Alignment with Existing Codebase

Note on Existing Capabilities:
Our server already implements the lower-level PDF converter engine (supernote/notebook/converter.py) and the official Supernote Private Cloud OpenAPI endpoint (POST /api/file/note/to/pdf).

What Issue #166 Specifically Adds:

1. Automated Background Export on Sync: Automatically trigger PDF conversion during background note processing, outputting flattened PDFs into user-facing filesystem targets (/Export/ or WebDAV).
2. Simplified Web UI Download Route: Add GET /api/web/files/{id}/export/pdf for direct 1-click browser downloads (bypassing the multi-step OpenAPI blob handshake).
3. Vector SVG Export Endpoint: Add GET /api/web/files/{id}/export/svg?page={n} for single-page vector SVG rendering.