From b8c29fce5f9b1a5d63717a39871a2ba1f2aaae41 Mon Sep 17 00:00:00 2001 From: Sparsh Sam <110058692+sparshsam@users.noreply.github.com> Date: Sun, 8 Nov 2026 17:24:20 -0500 Subject: [PATCH 1/4] feat(v1.3.0): port PDF form intelligence onto v1.2.8 Integrate the preserved form work from wip/v1.3.0-form-intelligence onto the released v1.2.8 architecture, leaving the backup branch untouched: - pure AcroForm engine (pdfreader_lib/form_fields.py): normalized fields, type detection, advisory validation, local form-state store - native Qt overlays for text, multiline, checkbox, radio, combo and listbox fields, with Tab navigation and accessible names - Form Navigator dock, completion workflow, autosave/recovery - form save / Save As, dirty tracking, close prompts - five MCP form tools mirrored in the standalone package (19 tools total) - adapt form overlays and highlights to the virtualized continuous renderer: attach on page render, detach on pixmap release/teardown All 224 tests pass (18 skipped). Co-Authored-By: Claude Code --- AGENTS.md | 6 +- CHANGELOG.md | 11 + CLAUDE.md | 18 +- README.md | 2 +- docs/Architecture.md | 4 +- ...2026-08-02-pdf-form-intelligence-design.md | 196 +++ main.py | 1197 ++++++++++++++++- packages/mcp-server/pyproject.toml | 2 +- .../src/openreader_mcp/_form_fields.py | 774 +++++++++++ .../mcp-server/src/openreader_mcp/server.py | 206 +++ packaging/msix/AppInstaller.xml | 2 +- packaging/msix/AppxManifest.xml | 2 +- pdfreader_lib/form_fields.py | 774 +++++++++++ pdfreader_lib/mcp_server.py | 238 ++++ tests/_form_fixtures.py | 124 ++ tests/test_form_fields.py | 305 +++++ tests/test_form_gui.py | 118 ++ tests/test_mcp_server.py | 87 +- tests/test_reliability.py | 4 +- 19 files changed, 4043 insertions(+), 27 deletions(-) create mode 100644 docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md create mode 100644 packages/mcp-server/src/openreader_mcp/_form_fields.py create mode 100644 pdfreader_lib/form_fields.py create mode 100644 tests/_form_fixtures.py create mode 100644 tests/test_form_fields.py create mode 100644 tests/test_form_gui.py diff --git a/AGENTS.md b/AGENTS.md index bbee4a0..0ffd73a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This repository is a local-first desktop PDF utility. Keep maintenance changes b ## Product Boundaries -**Current version:** v1.2.8 (2026-11-08) — virtualized continuous scrolling and the unified Fluent toolbar +**Current version:** v1.3.0 (2026-11-08) — Fill, Edit & Sign: native AcroForm filling, freeform text, visual signatures, and image placement (v1.2.8 continuous scrolling and toolbar retained) - Do not add new user-facing PDF features unless the task explicitly asks for them. - Do not change the local-first privacy philosophy. @@ -54,9 +54,11 @@ This repository is a local-first desktop PDF utility. Keep maintenance changes b The repository ships two MCP server entry points: -1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app. 14 tools, stdio + SSE transport. +1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app. 19 tools, stdio + SSE transport. 2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`. +**v1.3.0 (August 2026):** added five AcroForm tools — `form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate` — in both the bundled server and the standalone package. They share the form engine (`pdfreader_lib/form_fields.py` / `packages/mcp-server/src/openreader_mcp/_form_fields.py`) with the GUI's interactive form overlays. + **Improvements made (June 2026):** - All 14 tool descriptions rewritten as AI-optimized sentences (what it does, what it returns, when to use vs alternatives). - Error messages tiered by type: validation errors, file-not-found, missing params, unexpected errors — each tells the agent what to fix. diff --git a/CHANGELOG.md b/CHANGELOG.md index 22aeef1..f33379f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## v1.3.0 — PDF Form Intelligence — 2026-08-02 + +- **Version:** Bumped `__version__` to `1.3.0`, MSIX version to `1.3.0.0`; aligned the MCP package version. +- **Added (v1.3.0 — Interactive Forms):** AcroForm fields are detected automatically and rendered as native editable controls overlaid on the page — text, multiline text, checkboxes, radio groups, dropdowns (combo) and list boxes. Existing field values are preserved and seeded into the controls. Read-only fields are shown but never editable; required, max-length and password rules are respected (including combing). Fillable areas are highlighted on the page so blank forms stay discoverable. +- **Added:** Keyboard and accessible navigation — Tab/Shift+Tab move between fields in document order, arrow keys move within a radio group, and every control exposes its field name to screen readers via the Qt accessibility bridge. +- **Added:** Save behaviour — Save (Ctrl+S) writes completed values into the PDF (regenerating appearance streams so they render in any viewer) via incremental save; new **Save As…** (Ctrl+Shift+S) writes a completed copy. Closing a tab or the window with unsaved form work prompts **Save / Discard / Cancel**. +- **Added (v1.3.1 — Field Type Intelligence):** Field types are detected from PDF formatting rules (explicit) and from field names / nearby labels (inferred) — date, time, phone, ZIP/postal, email, currency, numeric. Inferred types are always advisory: an inferred date field is still fully editable as plain text and shows a picker + validation rather than enforcing. Users can override a field's type via its context menu; overrides persist outside the PDF. A date-picker button appears next to detected date fields. Advisory validation produces clear messages (e.g. "Expected a phone number like +1 555 123 4567") that never block input and tolerate legitimate international formats. +- **Added (v1.3.2 — Completion Workflow):** **Form Navigator** dock (View/Form menu) lists every field with status — filled / empty / required / invalid — grouped by page; clicking one scrolls to and focuses it. **Next/Previous Field** (Ctrl+Down/Ctrl+Up), **Clear Field**, **Clear Form**, and **Review & Complete** (a completion summary that highlights missing required and invalid fields). Required-but-empty fields get an amber outline. Unsaved form work is autosaved locally and **restored on reopen** with a prompt; the recent-files menu marks documents that contain fillable forms. +- **MCP Server:** Five new tools — `form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate` — mirroring the GUI's form engine (shared `pdfreader_lib/form_fields.py`), in both the bundled server and the standalone `openreader-mcp` package (19 tools total). Per-field success/failure reporting; read-only fields are respected. +- **Fixed:** A debounced render could fire after a document was closed (rendering a closed PDF raised `ValueError: document closed`); `_do_render` now bails out and the render timer is stopped on close. Removed a redundant `_perf_end` in `_render_continuous` that referenced an undefined local. +- **Verification:** New shared-module test suite (44 tests: normalization, flags, radio grouping, read/write round-trips, incremental-save persistence, type detection explicit-vs-inferred, international-tolerant validation, form-state store), 15 new MCP form-tool tests, and 4 offscreen GUI smoke tests (overlay creation, dirty tracking, persistence, validation messaging). ## v1.2.8 — Continuous Reading & Toolbar Redesign — 2026-11-08 - **Fixed (continuous scrolling):** The continuous view no longer renders a sliding window around the current page. Every page now gets a correctly sized placeholder in one persistent document layout, so the scrollbar spans the whole PDF — a 76-page document exposes all 76 pages instead of roughly six. Pixmaps are rendered lazily for the viewport plus a small overscan and released once they leave the cache window, so memory stays bounded for very long documents. diff --git a/CLAUDE.md b/CLAUDE.md index 001a00c..9b19985 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ ## Overview -**Latest update:** v1.2.8 — virtualized continuous scrolling, unified Fluent toolbar, light/dark redesign (2026-11-08) +**Latest update:** v1.3.0 — Fill, Edit & Sign: native form filling, freeform text objects, visual signatures, image placement (2026-11-08) Privacy-first, local-only desktop PDF utility for Windows. macOS experimental; Linux unsupported. @@ -11,6 +11,7 @@ macOS experimental; Linux unsupported. | Version | Date | Summary | |---------|------|---------| +| v1.3.0 | 2026-11-08 | Fill, Edit & Sign — AcroForm filling, freeform text objects, visual signatures, image placement; 5 new MCP form tools | | v1.2.8 | 2026-11-08 | Continuous scrolling rebuilt as a virtualized full-document layout; unified 44 px Fluent toolbar with vector icons; light/dark chrome redesign; tab page-controls fix | | v1.2.7 | 2026-08-02 | Store-aware updates — install-source detection, channel-aware Software Updates dialog, persisted skip + last-checked | | v1.2.6 | 2026-08-02 | Default Reader Experience — Windows UserChoice detection, Settings dialog, first-launch default prompt | @@ -106,13 +107,14 @@ python -m pytest tests/ -v The repository ships two MCP server entry points: -1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app source. 14 tools, stdio + SSE transport. +1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app source. 19 tools, stdio + SSE transport. - All tool descriptions rewritten as AI-optimized sentences (what, returns, when-to-use). - Error messages are tiered: validation, file-not-found, missing params, unexpected errors. - - Tests at `tests/test_mcp_server.py` — 43 tests covering registration, validation, output shape, error handling. + - Tests at `tests/test_mcp_server.py` — 58 tests covering registration, validation, output shape, error handling. + - Form tools (`form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate`) added in v1.3.0 — they share the AcroForm engine with the GUI via `pdfreader_lib/form_fields.py`. 2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`. - - Mirrors the bundled server but imports bundled `_search_index` and `_comparison` modules. + - Mirrors the bundled server but imports bundled `_search_index`, `_comparison`, and `_form_fields` modules. - `pyproject.toml` defines metadata. Update whenever `pdfreader_lib/mcp_server.py` gains new tools. ### Rules @@ -123,6 +125,14 @@ The repository ships two MCP server entry points: - When adding a tool to the bundled server, add it to `packages/mcp-server/` too. - Agent config uses `"args": ["-m", "openreader_mcp"]` (standalone) or `"args": ["-m", "pdfreader_lib.mcp_server"]` (bundled). +## PDF Form Intelligence (v1.3.0+) + +- **Shared engine:** `pdfreader_lib/form_fields.py` is pure logic (no PySide6 imports) and is consumed by both the GUI and the MCP server. Keep GUI form logic out of the module. +- **GUI:** native Qt overlay widgets are positioned over AcroForm field rects per page (Approach A), managed per-tab by `_FormController` in `main.py`. Overlays are rebuilt on every render (`detach_all()` before continuous-mode rebuilds). +- **Type detection** (`FormTypeDetector`) distinguishes explicit (PDF formatting rule) from inferred (name/label) types — inference is always advisory, never enforced. User overrides persist outside the PDF via `FormStateStore`. +- **Validation** (`FormValidator`) is advisory and international-tolerant; it writes `validation_message`, never blocks input. +- **Rules:** when adding a new form operation, mirror it in the bundled server and `packages/mcp-server/` (copy `_form_fields.py` too). See `docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md` for the full spec. + ## Design Playbooks Three canonical playbooks govern all design and architecture decisions. Loaded at `docs/playbooks/`: diff --git a/README.md b/README.md index d99946b..5315376 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ | **Semantic search** — TF-IDF cosine similarity — meaning-based matching, no external ML. | **Compare** — Side-by-side diff with color-coded changes and structured summary. | | **Multi-tab** — Open several documents in one window with movable tabs. | **Dark mode** — System-aware theme with Auto/Light/Dark toggle. | | **PDF tools** — Merge, split, extract page ranges, compress. | **OCR fallback** — Automatic OCR on scanned/image-based pages when Tesseract is available. | -| **Session restore** — Remembers open documents and page positions across restarts. | **AI agent integration** — Built-in MCP server with 14 tools for automated PDF workflows. | +| **Session restore** — Remembers open documents and page positions across restarts. | **AI agent integration** — Built-in MCP server with 19 tools for automated PDF workflows, including AcroForm filling. | --- diff --git a/docs/Architecture.md b/docs/Architecture.md index 1ed6c23..7cd3436 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -18,6 +18,7 @@ OpenReader is a local-first desktop PDF utility built with Python and PySide6 (Q │ │ pdfreader_lib/ │ │ │ │ ├── search_index.py │ │ │ │ ├── comparison.py │ │ +│ │ ├── form_fields.py │ │ │ │ └── mcp_server.py │ │ │ └─────────────────────────────────┘ │ │ ┌─────────────────────────────────┐ │ @@ -38,7 +39,8 @@ OpenReader is a local-first desktop PDF utility built with Python and PySide6 (Q | PDF Engine | — | PyMuPDF (MuPDF bindings) for rendering, text extraction, annotation | | Search | `pdfreader_lib/search_index.py` | SQLite FTS5 keyword index + TF-IDF semantic search | | Comparison | `pdfreader_lib/comparison.py` | Page-by-page text diff with color-coded output | -| MCP Server | `pdfreader_lib/mcp_server.py` | Model Context Protocol server for AI agent integration (14 tools) | +| Forms | `pdfreader_lib/form_fields.py` | AcroForm field model, value read/write, type detection & advisory validation (v1.3.0+) | +| MCP Server | `pdfreader_lib/mcp_server.py` | Model Context Protocol server for AI agent integration (19 tools) | ## Key Architecture Decisions diff --git a/docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md b/docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md new file mode 100644 index 0000000..43e3923 --- /dev/null +++ b/docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md @@ -0,0 +1,196 @@ +# Phase 2 — PDF Form Intelligence (v1.3.0 / v1.3.1 / v1.3.2) — Design + +> **Status:** Approved (approach + architecture) by Sparsh, 2026-08-02. +> **Build constraint:** local only — no commit, no push. Version bumps applied in code now, tags/PRs at release time. +> **Milestones:** v1.3.0 Interactive PDF Forms → v1.3.1 Field Type Intelligence → v1.3.2 Form Completion Workflow. + +## Goal + +Let users complete PDFs that already contain structured AcroForm fields: detect fields, render +them as native editable controls, preserve existing values, respect field rules, save values back +into the PDF, warn before closing a modified form, provide keyboard + accessible navigation, add +type intelligence, and make long-form completion manageable. Also expose form filling to the MCP +server so AI agents can drive the same engine. + +## Architecture + +All form logic lives in a **pure, Qt-free module**; the GUI and MCP server are thin consumers. + +``` +pdfreader_lib/form_fields.py NEW — pure logic, no PySide6 imports + FormField dataclass: normalized view of a fitz.Widget + FieldType normalized enum (text, multiline, checkbox, radio, + combo, listbox, signature, button) + iter_page_fields(page, page_index) -> list[FormField] + build_field_index(doc) -> list[FormField] + set_field_value(doc, page_index, field, value) (radio/checkbox/choices aware) + get_field_value(widget) + FormValidator (v1.3.1) per-type, international-tolerant, advisory + FormTypeDetector (v1.3.1) explicit vs inferred, never presented as certainty + FormStateStore (v1.3.2) autosave + user overrides, JSON on local disk + +main.py GUI layer — Approach A native Qt overlays + FormController per-tab lifecycle: overlay widgets on page labels, + highlight painting, dirty flag, save/save-as wiring + _TextFormWidget / _CheckFormWidget / _RadioFormWidget / _ComboFormWidget + QLineEdit / QTextEdit / QCheckBox / QRadioButton / QComboBox + FormNavigatorDock (v1.3.2) sidebar field list + status + Completion summary, close warning, restore, recent indicators (v1.3.2) + +pdfreader_lib/mcp_server.py +5 tools, same module + form_list_fields, form_get_field, form_set_value, form_fill, form_validate +``` + +### Why Qt-free + +The MCP server runs standalone (STDIO/SSE) without Qt in scope, so `form_fields.py` must never +import PySide6. The GUI layer stays in `main.py` (a large monolith, consistent with how annotation +and selection code already live there). Overlays anchor to the existing per-page QLabels used by +continuous and single-page rendering. + +## v1.3.0 — Interactive PDF Forms + +### Detection (shared module) + +PyMuPDF exposes AcroForm widgets natively; `FormField` is a defensive normalization of `fitz.Widget`: + +| Widget | `field_type` | Normalized | Notes | +|--------|-------------|------------|-------| +| Text | `fitz.PDF_WIDGET_TYPE_TEXT` (7) | `text` / `multiline` | multiline via `PDF_WIDGET_IS_MULTILINE` flag; `max_len` for `/MaxLen` | +| Checkbox | 2 | `checkbox` | `button_state` on/off | +| Radio | 5 | `radio` | grouped by shared `field_name`; `on_state()` enumerates choices | +| Combo | 3 | `combo` | editable or not per flags; `choice_values` from `/Opt` | +| Listbox | 4 | `listbox` | multi-select supported by flags | +| Signature | 8 | `signature` | render-only marker, never editable | +| Pushbutton | 6 | `button` | render-only marker | + +Flags honored: `PDF_WIDGET_IS_READONLY` (1), `PDF_WIDGET_IS_REQUIRED` (2), `PDF_WIDGET_IS_MULTILINE`, +`PDF_WIDGET_IS_PASSWORD`, `PDF_WIDGET_IS_COMB`, `PDF_WIDGET_IS_NO_TOGGLE_TO_OFF` (radio). + +Defensive normalization: nameless fields get `field__`; malformed choices degrade to text; +iteration never raises on a bad widget. + +### Rendering & editing (GUI, Approach A) + +- On every render (`_do_render`), after the pixmap is set on a page QLabel, the `FormController`: + 1. paints a subtle field-rect highlight onto the pixmap (`rect × zoom`) so fillable areas are + visible even when the PDF ships no appearance stream; + 2. creates/repositions native overlay widgets at `(rect − page_rect) × zoom`. +- Text → `QLineEdit` (or `QTextEdit` for multiline), `setMaxLength` from `/MaxLen`, + `setReadOnly` from flags, `echoMode=Password` for password fields. +- Checkbox → `QCheckBox`; radio → a `QRadioButton` group sharing the widget's state; combo/listbox + → `QComboBox` (editable per flags) populated from `/Opt`. +- Signature/pushbutton → painted marker, no editor (respect read-only). +- Existing values are seeded into overlays on open (**preserve existing field values**). +- Each overlay carries `setAccessibleName(field.name)` so screen readers see labeled fields. +- Focus highlight: focused field gets a stronger accent border. + +### Keyboard & accessibility + +- `Tab` / `Shift+Tab` move between editable fields (native Qt focus chain over overlay widgets). +- Arrow keys move within a radio group (native). +- Overlays are real Qt widgets → focus-visible, accessible via the Qt a11y bridge. + +### Persistence + +- Dirty flag per tab set on any field change. +- Save (`Ctrl+S`, File > Save): for each dirty field `set_field_value(...)` then + `widget.update()` (regenerates the appearance stream so values render in any viewer), then + `doc.save(incremental=True)` with a full-save fallback — reusing `_save_document_annotations` + semantics. +- Save As: full save to a new path (`doc.save(new_path, garbage=1, deflate=True)`), updates tab + path + recent list. +- **Close warning** (v1.3.0): if a tab is dirty (form or annotation edits), prompt + Save / Discard / Cancel before closing the tab or the window. + +## v1.3.1 — Field Type Intelligence + +### Detection pipeline (`FormTypeDetector`) + +Given a `FormField` (formatting rule + name + nearby label text + page text near rect): + +- **Explicit type** — from PDF metadata/formatting rule (e.g. `text_format == 2` → date). Authoritative. +- **Inferred type** — heuristic from field name/labels (e.g. "dob", "date of birth" → date; + "phone", "telephone" → phone; "zip"/"postal" → zip; "email" → email; "$"/"amount"/"price" → + currency; "qty"/"number"/"count" → numeric). Always tentative. +- `FormField` carries `field_type` (editing type), `explicit_type`, `inferred_type`, + `type_confidence`, and `is_inferred: bool` so the UI can mark inference subtly. + +**Never present inference as certainty**: inferred-type fields remain fully editable as plain text; +the inference only offers affordances (e.g. a date picker) and an advisory validation hint. +A clear message in the navigator/tooltip ("Inferred type: date — you can still type any text"). + +### Editing affordances + +- Date → `QDateEdit`-style picker shown on focus, but free text still accepted. +- Phone / ZIP / email / currency / numeric → validation on focus-out (non-blocking). + +### Override + +- Context menu on a field: "Set field type → {Date, Phone, ZIP, Email, Currency, Number, Text}". +- Overrides persist **outside the PDF** (in `FormStateStore`), keyed by `(path, page, field_name)` + so the PDF is never mutated by preference alone. + +### Validation (`FormValidator`) + +- Per-type rules, tolerant of legitimate international formats: + phone accepts `+`, digits, spaces, dashes, parens; ZIP allows international alphanumeric + (4–6+ chars); email pragmatic; currency optional symbol + comma + decimals; numeric optional + sign + decimal. +- Advisory only — never blocks input; writes `validation_message` shown inline in the navigator + and as a tooltip on focus-out ("Expected a phone number like +1 555 123 4567"). + +## v1.3.2 — Form Completion Workflow + +- **FormNavigatorDock**: dockable sidebar listing all fields with status — ✓ filled, ○ empty, + ● required, ⚠ invalid — grouped by page; click scrolls to + focuses the field. +- **Next Field / Previous Field** controls (toolbar + `Ctrl+Down` / `Ctrl+Up`), document order. +- **Completion summary** before export: counts of filled / empty / required-empty / invalid with + jump-to links; launched from "Review & Complete" before Save As. +- **Highlight missing required fields**: required-empty fields get a warning tint + navigator dot. +- **Clear**: per-field ("Clear Field") and whole-form ("Clear Form", skipping read-only). +- **Autosave & crash recovery**: dirty field values are debounced (≈1 s) into `FormStateStore` + (JSON in the app data dir, keyed by path hash). On reopen, offer "Restore unsaved form data?" + (with "Don't ask again"). +- **Restore on session reopen**: session entries (already written in `closeEvent`) gain form + values + overrides. +- **Form-specific recent indicators**: recent-files menu marks documents that have AcroForm fields. + +## MCP tools (same module) + +All operate on an absolute local path with the existing safety validation, opening in memory and +saving incrementally to the original or to a supplied `output` path: + +- `form_list_fields(path)` → JSON array: name, page, type, flags (readonly/required), value, + choices, rect, inferred type + confidence. +- `form_get_field(path, field)` → single field detail incl. format rule. +- `form_set_value(path, field, value, output?)` → set one value, save. +- `form_fill(path, values: {field: value}, output?)` → set many, per-field success/failure. +- `form_validate(path, field, value)` → run `FormValidator`, return ok + message. + +MCP uses on-demand inference; GUI overrides live only in `FormStateStore`. + +## Error handling + +- Encrypted docs: existing open flow applies; saving falls back to full save; surface existing + save-failure path and offer Save As. +- Signed forms: signature fields are read-only markers; digital signing is out of scope. +- Malformed forms: normalized defensively, never crash on iteration. +- Read-only file on disk: reuse existing save error surface, offer Save As. +- Huge forms: navigator renders lazily; overlay count bounded by page. + +## Testing + +- Fixture PDFs built with PyMuPDF in `tests/` covering: text, multiline, checkbox, radio group, + combo, listbox, readonly, required, `max_len`, `text_format` date, password, signed marker. +- Module unit tests: normalization, flag mapping, radio grouping, value set/get round-trip, + incremental save → reopen → values present and visible. +- `FormValidator`: international formats accepted; wrong formats advisory; explicit vs inferred. +- `FormTypeDetector`: name/label heuristics, confidence, no false certainty. +- MCP: `form_list_fields` / `form_fill` / `form_set_value` round-trip; non-PDF path rejected. +- GUI smoke (offscreen): overlay creation for a fixture page — widget types + positions. + +## Version alignment + +`main.py __version__ = "1.3.0"`, `packages/mcp-server/pyproject.toml = "1.3.0"`, +`packaging/msix/AppxManifest.xml` + `AppInstaller.xml` = `1.3.0.0`. diff --git a/main.py b/main.py index e25aa56..5581a76 100644 --- a/main.py +++ b/main.py @@ -11,15 +11,19 @@ from pathlib import Path import fitz -from PySide6.QtCore import QByteArray, QEvent, QPoint, QPointF, QRect, QRectF, QSettings, QSize, QTimer, Qt, QUrl, Signal +from PySide6.QtCore import QByteArray, QEvent, QObject, QPoint, QPointF, QRect, QRectF, QSettings, QSize, QStandardPaths, QTimer, Qt, QUrl, Signal from PySide6.QtGui import QAction, QColor, QDesktopServices, QIcon, QImage, QKeySequence, QPainter, QPainterPath, QPalette, QPen, QPixmap, QShortcut from PySide6.QtNetwork import QLocalServer, QLocalSocket, QNetworkAccessManager, QNetworkReply, QNetworkRequest from PySide6.QtWidgets import ( QAbstractSpinBox, QApplication, + QButtonGroup, + QCalendarWidget, QCheckBox, + QComboBox, QDialog, QDialogButtonBox, + QDockWidget, QFileDialog, QFrame, QGroupBox, @@ -35,6 +39,7 @@ QMessageBox, QProgressDialog, QPushButton, + QRadioButton, QScrollArea, QScrollBar, QSizePolicy, @@ -47,12 +52,14 @@ QTextEdit, QToolBar, QToolButton, + QTreeWidget, + QTreeWidgetItem, QVBoxLayout, QWidget, ) -__version__ = "1.2.8" +__version__ = "1.3.0" GITHUB_REPO = "sparshsam/openreader" IPC_SERVER_NAME = "OpenReader-IPC" RECENT_FILES_MAX = 10 @@ -109,6 +116,9 @@ def _perf_end(start: float, label: str) -> None: # Install-source detection for channel-aware updates (stdlib only). from pdfreader_lib import install_source +# AcroForm field intelligence (Phase 2) — shared with the MCP server. +from pdfreader_lib import form_fields as _ff + # --------------------------------------------------------------------------- # Per-tab state container @@ -1255,6 +1265,662 @@ def _make_empty_state_icon(dark_mode: bool, size: int = 60) -> QPixmap: return pixmap +# --------------------------------------------------------------------------- +# AcroForm overlays — Phase 2 PDF Form Intelligence (v1.3.0 / 1.3.1 / 1.3.2) +# --------------------------------------------------------------------------- +# +# The FormController owns one tab's AcroForm state: native Qt overlay widgets +# positioned over each fillable field rect (Approach A), a dirty flag, advisory +# validation, autosave/recovery via FormStateStore, and the data feeding the +# Form Navigator dock. All field logic lives in pdfreader_lib.form_fields. + + +class _FormLineEdit(QLineEdit): + """Single-line text field overlay.""" + + def __init__(self, controller, field): + super().__init__() + self._controller = controller + self._field = field + if field.password: + self.setEchoMode(QLineEdit.Password) + if field.max_length: + self.setMaxLength(field.max_length) + self.textEdited.connect(lambda _t: controller.on_edited(field)) + self.editingFinished.connect(lambda: controller.on_commit(field, self.text())) + + def focusInEvent(self, event): + super().focusInEvent(event) + self._controller.on_focus(self._field) + + +class _FormMultilineEdit(QTextEdit): + """Multiline text field overlay.""" + + def __init__(self, controller, field): + super().__init__() + self._controller = controller + self._field = field + self.setFrameShape(QFrame.NoFrame) + self.setTabChangesFocus(True) # Tab moves between fields, not tabs + if field.max_length: + self.textChanged.connect(lambda: self._enforce_max_length()) + + def _enforce_max_length(self): + text = self.toPlainText() + limit = self._field.max_length + if limit and len(text) > limit: + cursor = self.textCursor() + pos = cursor.position() + self.blockSignals(True) + self.setPlainText(text[:limit]) + cursor.setPosition(min(pos, limit)) + self.setTextCursor(cursor) + self.blockSignals(False) + + def focusInEvent(self, event): + super().focusInEvent(event) + self._controller.on_focus(self._field) + + +class _FormCheck(QCheckBox): + """Checkbox overlay.""" + + def __init__(self, controller, field): + super().__init__() + self._controller = controller + self._field = field + self.toggled.connect(lambda checked: controller.on_toggled(field, checked)) + + def focusInEvent(self, event): + super().focusInEvent(event) + self._controller.on_focus(self._field) + + +class _FormCombo(QComboBox): + """Combo/listbox overlay.""" + + def __init__(self, controller, field): + super().__init__() + self._controller = controller + self._field = field + for choice in field.choices: + self.addItem(choice) + self.setEditable(bool(field.editable_choice)) + self.currentTextChanged.connect(lambda _t: controller.on_edited(field)) + + def focusInEvent(self, event): + super().focusInEvent(event) + self._controller.on_focus(self._field) + + +# Overlay colors — brand accent #ff255F for focus, blue accent for fillables. +_FORM_FILLABLE_BORDER = (37, 99, 235, 150) +_FORM_FILLABLE_FILL = (37, 99, 235, 26) +_FORM_READONLY_BORDER = (150, 150, 150, 130) +_FORM_REQUIRED_EMPTY_BORDER = (245, 158, 11, 200) +_FORM_FOCUS_BORDER = (255, 37, 95) + + +class _FormController(QObject): + """Owns one tab's AcroForm overlays, dirty tracking and autosave.""" + + def __init__(self, window, tab_id: int): + super().__init__(window) + self.window = window + self.tab_id = tab_id + self.fields: list = [] + self._by_name: dict = {} + self._widgets: dict = {} # QWidget -> FormField + self._field_widgets: dict = {} # field.name -> list[QWidget] + self._radio_buttons: dict = {} # QRadioButton -> (field, caption) + self._radio_groups: dict = {} # field.name -> QButtonGroup + self._button_group = None + self.dirty = False + self._dirty_names: set = set() + self._seeding = 0 + self._current_index = -1 + self._user_overrides: dict = {} # "page:name" -> detected_type + self._state_store = None + self._autosave_timer = QTimer(self) + self._autosave_timer.setSingleShot(True) + self._autosave_timer.setInterval(1200) + self._autosave_timer.timeout.connect(self._autosave_now) + + # ------------------------------------------------------------------ + # Lifecycle + # ------------------------------------------------------------------ + + def load(self, doc, path) -> int: + """Build the field index for a document. Returns the field count.""" + self.fields = _ff.build_field_index(doc) + _ff.annotate_field_types(self.fields, doc) + self._by_name = {f.name: f for f in self.fields} + self.dirty = False + self._dirty_names = set() + self._current_index = -1 + self._user_overrides = {} + self._state_store = getattr(self.window, "_form_store", None) + self._apply_stored_state(path) + return len(self.fields) + + @property + def editable_fields(self): + return [f for f in self.fields if f.is_editable()] + + def detach_all(self): + """Remove every overlay widget from the UI.""" + for widget in list(self._widgets.keys()): + widget.setParent(None) + widget.deleteLater() + self._widgets = {} + self._field_widgets = {} + self._radio_buttons = {} + self._radio_groups = {} + self._button_group = None + + def detach_page(self, label): + """Remove overlay widgets attached to a single page label.""" + self._clear_overlays(label) + + # ------------------------------------------------------------------ + # Overlay rendering + # ------------------------------------------------------------------ + + def attach_page(self, label, page_index, zoom, page_rect): + """Create/reposition overlay widgets for one rendered page label.""" + self._clear_overlays(label) + if not self.fields: + return + page_fields = [f for f in self.fields if f.page_index == page_index] + if not page_fields: + return + style = self._overlay_style(bool(getattr(self.window, "_dark_mode", False))) + self._seeding += 1 + try: + for field in page_fields: + if not field.is_editable(): + continue + if field.field_type == _ff.FieldType.RADIO: + self._attach_radio(label, field, zoom, page_rect, style) + continue + widget = self._make_widget(field) + widget.setParent(label) + widget.setStyleSheet(style) + widget.setGeometry( + round((field.rect[0] - page_rect.x0) * zoom), + round((field.rect[1] - page_rect.y0) * zoom), + max(8, round((field.rect[2] - field.rect[0]) * zoom)), + max(8, round((field.rect[3] - field.rect[1]) * zoom)), + ) + widget.show() + self._register_widget(widget, field) + self._seed_widget(widget, field) + # v1.3.1 — visible date-picker affordance on detected date fields. + if ( + field.detected_type == _ff.TYPE_DATE + and field.field_type in (_ff.FieldType.TEXT, _ff.FieldType.MULTILINE) + ): + self._attach_date_button(label, field, zoom, page_rect) + finally: + self._seeding -= 1 + self._set_tab_order(page_fields) + + def _make_widget(self, field): + ftype = field.field_type + if ftype == _ff.FieldType.MULTILINE: + widget = _FormMultilineEdit(self, field) + widget.textChanged.connect(lambda: self.on_edited(field)) + elif ftype == _ff.FieldType.CHECKBOX: + widget = _FormCheck(self, field) + elif ftype in (_ff.FieldType.COMBO, _ff.FieldType.LISTBOX): + widget = _FormCombo(self, field) + else: + widget = _FormLineEdit(self, field) + widget.setAccessibleName(field.display_name()) + widget.setToolTip(self._tooltip_for(field)) + widget.setContextMenuPolicy(Qt.CustomContextMenu) + widget.customContextMenuRequested.connect( + lambda pos, w=widget, f=field: self._on_context_menu(w, f, pos) + ) + return widget + + def _attach_radio(self, label, field, zoom, page_rect, style): + group = QButtonGroup(label) + group.setExclusive(True) + for caption, opt_rect in zip(field.choices, field.option_rects): + rb = QRadioButton(label) + rb.setText("") + rb.setToolTip(caption) + rb.setAccessibleName(f"{field.display_name()} — {caption}") + rb.setGeometry( + round((opt_rect[0] - page_rect.x0) * zoom), + round((opt_rect[1] - page_rect.y0) * zoom), + max(8, round((opt_rect[2] - opt_rect[0]) * zoom)), + max(8, round((opt_rect[3] - opt_rect[1]) * zoom)), + ) + rb.setStyleSheet(style) + if field.value == caption: + rb.setChecked(True) + group.addButton(rb) + rb.clicked.connect(lambda _c, f=field, cap=caption: self.on_radio(f, cap)) + self._widgets[rb] = field + self._field_widgets.setdefault(field.name, []).append(rb) + self._radio_buttons[rb] = (field, caption) + rb.show() + self._button_group = group + self._radio_groups[field.name] = group + + def _attach_date_button(self, label, field, zoom, page_rect): + """Small calendar button to the right of a detected date field.""" + button = QToolButton(label) + button.setText("📅") + button.setToolTip("Pick a date") + button.setAccessibleName(f"Pick a date for {field.display_name()}") + button.setGeometry( + round((field.rect[2] - page_rect.x0) * zoom), + round((field.rect[1] - page_rect.y0) * zoom), + max(16, round((field.rect[3] - field.rect[1]) * zoom)), + max(16, round((field.rect[3] - field.rect[1]) * zoom)), + ) + button.clicked.connect(lambda _c, f=field: self._open_date_picker(f)) + button.show() + # Keep it above the field widget so clicks reach it. + button.raise_() + + def _open_date_picker(self, field): + dialog = QDialog(self.window) + dialog.setWindowTitle(f"Pick a date — {field.display_name()}") + layout = QVBoxLayout(dialog) + calendar = QCalendarWidget() + layout.addWidget(calendar) + buttons = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel) + buttons.accepted.connect(dialog.accept) + buttons.rejected.connect(dialog.reject) + layout.addWidget(buttons) + if dialog.exec() == QDialog.Accepted: + iso = calendar.selectedDate().toString("yyyy-MM-dd") + self._set_widget_value(field, iso) + self._mark_dirty(field) + self.on_commit(field, iso) + + def _register_widget(self, widget, field): + self._widgets[widget] = field + self._field_widgets.setdefault(field.name, []).append(widget) + + def _seed_widget(self, widget, field): + value = field.value + ftype = field.field_type + if ftype in (_ff.FieldType.TEXT, _ff.FieldType.MULTILINE): + if isinstance(widget, QTextEdit): + widget.setPlainText(str(value)) + else: + widget.setText(str(value)) + elif ftype == _ff.FieldType.CHECKBOX: + widget.setChecked(bool(value)) + elif ftype in (_ff.FieldType.COMBO, _ff.FieldType.LISTBOX): + index = widget.findText(str(value)) + if index >= 0: + widget.setCurrentIndex(index) + + def _clear_overlays(self, label): + for widget in list(self._widgets.keys()): + if widget.parent() is label: + widget.setParent(None) + widget.deleteLater() + self._widgets.pop(widget, None) + self._field_widgets = {} + for widget, field in self._widgets.items(): + self._field_widgets.setdefault(field.name, []).append(widget) + self._radio_buttons = { + rb: pair for rb, pair in self._radio_buttons.items() if rb.parent() is not label + } + for name, group in list(self._radio_groups.items()): + if group.parent() is label: + del self._radio_groups[name] + if self._button_group is not None and self._button_group.parent() is label: + self._button_group = None + + def _set_tab_order(self, page_fields): + widgets = [] + for field in page_fields: + widgets.extend(self._field_widgets.get(field.name, [])) + for a, b in zip(widgets, widgets[1:]): + QWidget.setTabOrder(a, b) + + @staticmethod + def _overlay_style(dark: bool) -> str: + if dark: + return ( + "QLineEdit, QTextEdit, QComboBox { background: rgba(30,34,48,150); color: #e8e8f0;" + " border: 1px solid rgba(120,150,255,150); border-radius: 2px; }" + "QLineEdit:focus, QTextEdit:focus, QComboBox:focus { border: 1px solid #ff255f; }" + ) + return ( + "QLineEdit, QTextEdit, QComboBox { background: rgba(255,255,255,175); color: #1a1a1a;" + " border: 1px solid rgba(37,99,235,140); border-radius: 2px; }" + "QLineEdit:focus, QTextEdit:focus, QComboBox:focus { border: 1px solid #ff255f; }" + ) + + # ------------------------------------------------------------------ + # Value handling + # ------------------------------------------------------------------ + + def current_value(self, field): + widgets = self._field_widgets.get(field.name) + if not widgets: + return field.value + widget = widgets[0] + ftype = field.field_type + if ftype == _ff.FieldType.CHECKBOX: + return widget.isChecked() + if ftype == _ff.FieldType.RADIO: + for rb, (fld, caption) in self._radio_buttons.items(): + if fld.name == field.name and rb.isChecked(): + return caption + return "" + if ftype in (_ff.FieldType.COMBO, _ff.FieldType.LISTBOX): + return widget.currentText() + if isinstance(widget, QTextEdit): + return widget.toPlainText() + return widget.text() + + def _set_widget_value(self, field, value): + self._seeding += 1 + try: + widgets = self._field_widgets.get(field.name) + if not widgets: + return + widget = widgets[0] + ftype = field.field_type + if ftype == _ff.FieldType.CHECKBOX: + widget.setChecked(bool(value)) + elif ftype == _ff.FieldType.RADIO: + group = self._radio_groups.get(field.name) + if group is not None: + group.setExclusive(False) # allow clearing the whole group + try: + for rb, (fld, caption) in self._radio_buttons.items(): + if fld.name == field.name: + rb.setChecked(caption == value) + finally: + if group is not None: + group.setExclusive(True) + elif ftype in (_ff.FieldType.COMBO, _ff.FieldType.LISTBOX): + index = widget.findText(str(value)) + widget.setCurrentIndex(index if index >= 0 else -1) + elif isinstance(widget, QTextEdit): + widget.setPlainText(str(value)) + else: + widget.setText(str(value)) + finally: + self._seeding -= 1 + + def clear_field(self, field): + if not field.is_editable(): + return + empty = False if field.field_type == _ff.FieldType.CHECKBOX else "" + self._set_widget_value(field, empty) + self._mark_dirty(field) + + def clear_form(self): + for field in self.editable_fields: + self.clear_field(field) + + # ------------------------------------------------------------------ + # Editing / focus signals + # ------------------------------------------------------------------ + + def on_edited(self, field): + if self._seeding: + return + self._mark_dirty(field) + + def on_toggled(self, field, _checked): + if self._seeding: + return + self._mark_dirty(field) + + def on_radio(self, field, _caption): + if self._seeding: + return + self._mark_dirty(field) + + def on_focus(self, field): + self._current_index = self._index_of(field) + self.window._on_form_focus(field) + + def on_commit(self, field, text): + if field.detected_type and text: + ok, message = _ff.FormValidator.validate(field, text) + field.validation_message = "" if ok else message + self.window._on_form_validation(field, field.validation_message) + self.window._update_navigator_item(field) + + def _mark_dirty(self, field): + self.dirty = True + self._dirty_names.add(field.name) + self.window._on_form_dirty(self.tab_id) + self._autosave_timer.start() + + def _index_of(self, field): + for i, candidate in enumerate(self.editable_fields): + if candidate.name == field.name: + return i + return -1 + + # ------------------------------------------------------------------ + # Navigation + # ------------------------------------------------------------------ + + def focus_next(self, forward: bool = True): + fields = self.editable_fields + if not fields: + return + count = len(fields) + index = self._current_index + index = -1 if index < 0 else index + self._current_index = (index + (1 if forward else -1)) % count + self.focus_field(fields[self._current_index]) + + def focus_field(self, field): + self.window._jump_to_page(field.page_index) + widgets = self._field_widgets.get(field.name) + if widgets: + widget = widgets[0] + widget.show() + widget.setFocus(Qt.OtherFocusReason) + self.window._ensure_field_visible(field) + + # ------------------------------------------------------------------ + # Context menu (type override, clear) + # ------------------------------------------------------------------ + + def _on_context_menu(self, widget, field, pos): + menu = QMenu(self.window) + if field.detected_type: + marker = " (inferred)" if field.is_inferred else "" + menu.addSection(f"Detected: {field.detected_type}{marker}") + type_menu = menu.addMenu("Set field type") + for label, ftype in [ + ("Text", None), + ("Date", _ff.TYPE_DATE), + ("Phone", _ff.TYPE_PHONE), + ("ZIP / Postal code", _ff.TYPE_ZIP), + ("Email", _ff.TYPE_EMAIL), + ("Currency", _ff.TYPE_CURRENCY), + ("Number", _ff.TYPE_NUMERIC), + ]: + action = type_menu.addAction(label) + action.triggered.connect(lambda _c, t=ftype, f=field: self._apply_override(f, t)) + if field.detected_type == _ff.TYPE_DATE and field.is_editable(): + date_action = menu.addAction("Pick a date…") + date_action.triggered.connect(lambda _c, f=field: self._open_date_picker(f)) + menu.addSeparator() + clear_action = menu.addAction("Clear field") + clear_action.triggered.connect(lambda: self.clear_field(field)) + menu.exec(widget.mapToGlobal(pos)) + + def _apply_override(self, field, ftype): + field.detected_type = ftype + field.is_inferred = False + field.validation_message = "" + key = f"{field.page_index}:{field.name}" + if ftype: + self._user_overrides[key] = ftype + else: + self._user_overrides.pop(key, None) + self.window._on_form_validation(field, "Field type overridden." if ftype else "Field type cleared.") + self.window._update_navigator_item(field) + widgets = self._field_widgets.get(field.name) + if widgets: + widgets[0].setToolTip(self._tooltip_for(field)) + self.on_commit(field, str(self.current_value(field))) + + # ------------------------------------------------------------------ + # Tooltips / status helpers + # ------------------------------------------------------------------ + + def _tooltip_for(self, field) -> str: + parts = [] + if field.label and field.label != field.name: + parts.append(field.label) + parts.append(field.name) + if field.required: + parts.append("Required") + if field.detected_type: + parts.append(f"Type: {field.detected_type}{' (inferred)' if field.is_inferred else ''}") + if field.validation_message: + parts.append(field.validation_message) + return " • ".join(parts) + + # ------------------------------------------------------------------ + # Persistence + # ------------------------------------------------------------------ + + def save(self, doc, path) -> bool: + """Write dirty field values into the PDF and persist incrementally.""" + if not self.dirty: + return True + for name in self._dirty_names: + field = self._by_name.get(name) + if field is None or not field.is_editable(): + continue + try: + _ff.set_field_value(doc, field, self.current_value(field)) + except Exception: + continue + self._persist(doc, path) + self.dirty = False + self._dirty_names = set() + if self._state_store is not None: + self._state_store.clear(path) + return True + + def save_as(self, doc, new_path): + doc.save(str(new_path), garbage=1, deflate=True) + self.dirty = False + self._dirty_names = set() + if self._state_store is not None: + self._state_store.clear(new_path) + + @staticmethod + def _persist(doc, path): + try: + doc.save(str(path), incremental=True, encryption=0) + except Exception: + doc.save(str(path), garbage=1, deflate=True) + + def _autosave_now(self): + if not self.dirty or self._state_store is None: + return + path = getattr(self.window, "current_path", None) + if not path: + return + values = {} + for field in self.fields: + if field.is_editable(): + values[f"{field.page_index}:{field.name}"] = self.current_value(field) + self._state_store.save(path, values, dict(self._user_overrides)) + + def discard_autosave(self, path): + if self._state_store is not None: + self._state_store.clear(path) + + def _apply_stored_state(self, path): + if self._state_store is None or not self._state_store.has_state(path): + return + data = self._state_store.load(path) + values = data.get("values", {}) + overrides = data.get("overrides", {}) + for field in self.fields: + key = f"{field.page_index}:{field.name}" + if overrides.get(key): + field.detected_type = overrides[key] + field.is_inferred = False + self._user_overrides[key] = overrides[key] + if key in values: + field.value = values[key] + elif field.name in values: + field.value = values[field.name] + # Restored state is unsaved form work → mark the tab dirty. + if values: + self.dirty = True + + # ------------------------------------------------------------------ + # Navigator / summary data + # ------------------------------------------------------------------ + + def field_status(self, field) -> str: + if not field.is_editable(): + return "readonly" + value = self.current_value(field) + empty = value is None or value == "" or (isinstance(value, bool) and not value) + if field.validation_message: + return "invalid" + if field.required and empty: + return "required" + if not empty: + return "filled" + return "empty" + + def _summary_value(self, field) -> str: + value = self.current_value(field) + if isinstance(value, bool): + return "✓" if value else "" + text = str(value or "") + return text if len(text) <= 40 else text[:37] + "…" + + def navigator_rows(self): + rows = [] + for field in self.fields: + rows.append( + { + "page": field.page_index, + "name": field.display_name(), + "field_type": field.field_type, + "status": self.field_status(field), + "value": self._summary_value(field), + "validation": field.validation_message, + } + ) + return rows + + def completion_summary(self): + counts = {"filled": 0, "empty": 0, "required": 0, "invalid": 0} + for field in self.fields: + status = self.field_status(field) + if status == "filled": + counts["filled"] += 1 + elif status == "required": + counts["required"] += 1 + elif status == "invalid": + counts["invalid"] += 1 + elif status == "empty": + counts["empty"] += 1 + return counts + + # --------------------------------------------------------------------------- # Main Window # --------------------------------------------------------------------------- @@ -1312,6 +1978,8 @@ class PdfReaderWindow(QMainWindow): ("fit_width", "Ctrl+0"), ("close_tab", "Ctrl+W"), ("new_tab", "Ctrl+T"), + ("next_field", "Ctrl+Down"), + ("previous_field", "Ctrl+Up"), ) def __init__(self, ipc_server: QLocalServer | None = None): @@ -1375,6 +2043,13 @@ def __init__(self, ipc_server: QLocalServer | None = None): self.tab_counter = 0 self.current_tab_id: int | None = None + # ---- AcroForm controllers (Phase 2) ---- + self._form_controllers: dict[int, _FormController] = {} + _app_data = QStandardPaths.writableLocation(QStandardPaths.AppDataLocation) + self._form_store = _ff.FormStateStore(base_dir=Path(_app_data)) + self._form_menu = None + self._navigator_action = None + # ---- Dark mode ---- self._theme = self.settings.value("theme", self.THEME_AUTO, int) self._dark_mode = self._compute_dark_mode() @@ -1534,6 +2209,31 @@ def _build_ui(self): self._content_stack = {None: self.empty_state_widget} self._current_content = None + self._build_navigator_dock() + + def _build_navigator_dock(self): + """Right-hand dock listing form fields and their status.""" + self.form_dock = QDockWidget("Form Navigator", self) + self.form_dock.setObjectName("formNavigatorDock") + self.form_dock.setAllowedAreas(Qt.LeftDockWidgetArea | Qt.RightDockWidgetArea) + self.form_tree = QTreeWidget() + self.form_tree.setHeaderLabels(["Field", "Status", "Value"]) + self.form_tree.setColumnWidth(0, 170) + self.form_tree.setColumnWidth(1, 70) + self.form_tree.setRootIsDecorated(True) + self.form_tree.setUniformRowHeights(True) + self.form_tree.itemClicked.connect(self._on_navigator_item_clicked) + self.form_tree.setContextMenuPolicy(Qt.CustomContextMenu) + self.form_dock.setWidget(self.form_tree) + self.addDockWidget(Qt.RightDockWidgetArea, self.form_dock) + self.form_dock.hide() + + # Debounce navigator rebuilds (fires on every keystroke in a field). + self._navigator_rebuild_timer = QTimer(self) + self._navigator_rebuild_timer.setSingleShot(True) + self._navigator_rebuild_timer.setInterval(250) + self._navigator_rebuild_timer.timeout.connect(self._rebuild_navigator) + def _build_actions(self): """Build the single, unified application toolbar. @@ -1787,6 +2487,8 @@ def _build_shortcuts(self): "fit_width": self._fit_width_shortcut, "close_tab": self._close_current_tab, "new_tab": self.new_tab, + "next_field": self._form_next_field, + "previous_field": self._form_previous_field, } for shortcut_id, sequence in self.REGISTERED_SHORTCUTS: shortcut = QShortcut(QKeySequence(sequence), self) @@ -1910,6 +2612,10 @@ def _build_menus(self): file_save.triggered.connect(self._save_document) file_menu.addAction(file_save) + file_save_as = QAction(self._menu_label("Save As…", "Ctrl+Shift+S"), self) + file_save_as.triggered.connect(self._save_document_as) + file_menu.addAction(file_save_as) + file_menu.addSeparator() settings_action = QAction("Settings…", self) @@ -2008,6 +2714,27 @@ def _build_menus(self): tools_menu.addAction("Compare PDFs", self._open_compare_dialog) tools_menu.addAction("Library Search", self._open_library_dialog) + # ── Form (Phase 2 — PDF Form Intelligence) ── + form_menu = menubar.addMenu("Form") + self._form_menu = form_menu + + self.navigator_action = QAction("Form Navigator", self, checkable=True) + self.navigator_action.triggered.connect(self._toggle_navigator) + form_menu.addAction(self.navigator_action) + + form_menu.addSeparator() + form_menu.addAction(self._menu_label("Next Field", "Ctrl+Down"), self._form_next_field) + form_menu.addAction(self._menu_label("Previous Field", "Ctrl+Up"), self._form_previous_field) + form_menu.addSeparator() + form_menu.addAction("Clear Field", self._form_clear_field) + form_menu.addAction("Clear Form", self._form_clear_all) + form_menu.addSeparator() + form_menu.addAction("Review & Complete…", self._form_review_complete) + self._form_menu_actions = [] + for action in form_menu.actions(): + self._form_menu_actions.append(action) + self._update_form_menu_state() + # ── Help ── help_menu = menubar.addMenu("Help") self.update_action = QAction("Check for Updates", self) @@ -2138,6 +2865,9 @@ def _update_recent_menu(self): label = entry.name if len(label) > 50: label = label[:47] + "..." + # Mark documents that contain fillable AcroForm fields (Phase 2). + if self._is_recent_form_doc(p): + label = f"📝 {label}" action = self._recent_menu.addAction(label) action.setToolTip(str(entry)) action.triggered.connect(lambda _=False, path=p: self._open_recent(path)) @@ -2228,6 +2958,10 @@ def _on_tab_switch(self, index: int): self.statusBar().clearMessage() self.render_page() self._update_controls() + # Refresh form-related chrome for the newly selected tab (Phase 2). + self._update_window_title_dirty() + self._update_form_menu_state() + self._navigator_rebuild_timer.start() def _save_current_tab_controls(self): pass @@ -2305,6 +3039,9 @@ def _close_current_tab(self): def _close_tab(self, tab_id: int): if tab_id not in self.tabs: return + # Warn before discarding unsaved form work (Phase 2). + if not self._confirm_discard_form(tab_id): + return tab = self.tabs[tab_id] was_current = tab_id == self.current_tab_id if was_current: @@ -2316,6 +3053,7 @@ def _close_tab(self, tab_id: int): fallback_id = remaining_ids[-1] if tab.document is not None: tab.document.close() + self._drop_form_controller(tab_id) self.tab_bar.blockSignals(True) try: for i in range(self.tab_bar.count()): @@ -2565,6 +3303,10 @@ def load_pdf(self, file_name): break self.setWindowTitle(f"{self.APP_NAME} - {name}") + + # Build AcroForm overlays (Phase 2) before the first render. + self._init_form() + self.render_page() self._update_controls() self.statusBar().showMessage(f"Opened {name}", 5000) @@ -2635,15 +3377,15 @@ def render_page(self): def _do_render(self): """Perform the actual page render (called by debounce timer).""" _t = _perf_start() - if self.document is None: - self._teardown_continuous_layout() - # Show empty state if not already - if self.scroll_area.widget() is not self.empty_state_widget: - self.scroll_area.takeWidget() - empty_parent = self.empty_state_widget.parent() - self.scroll_area.setWidget(self.empty_state_widget) - self.scroll_area.setWidgetResizable(True) - self._update_controls() + if self.document is None or getattr(self.document, "is_closed", False): + if self.document is None: + self._teardown_continuous_layout() + # Show empty state if not already + if self.scroll_area.widget() is not self.empty_state_widget: + self.scroll_area.takeWidget() + self.scroll_area.setWidget(self.empty_state_widget) + self.scroll_area.setWidgetResizable(True) + self._update_controls() return # Switch to page label if showing empty state @@ -2686,6 +3428,7 @@ def _render_single_page(self): self._paint_highlights(image, page, highlight_rects, render_zoom) if self.selected_rects: self._paint_selection(image, page, self.selected_rects, render_zoom) + self._paint_form_highlights(image, page, self.current_page, render_zoom) except Exception as exc: self._show_error("Render Error", "Unable to render this page.", exc) return @@ -2699,6 +3442,12 @@ def _render_single_page(self): qp = QPixmap.fromImage(image) qp.setDevicePixelRatio(dpr) self.page_label.setPixmap(qp) + # Drop overlay widgets left over from continuous mode, then attach + # this page's native form controls. + current_form = self._form_for_current() + if current_form is not None: + current_form.detach_all() + self._attach_form_overlays(self.page_label, self.current_page, zoom) self.page_label.adjustSize() self.page_spin.blockSignals(True) self.page_spin.setValue(self.current_page + 1) @@ -2807,6 +3556,9 @@ def _build_continuous_layout(self, zoom: float, page_count: int): def _teardown_continuous_layout(self): self._continuous_render_timer.stop() self._pending_scroll_page = None + form = self._form_for_current() + if form is not None: + form.detach_all() # Clear the page list before detaching the widget so scroll events # raised by the swap are ignored. self._continuous_pages = [] @@ -2828,6 +3580,9 @@ def _release_all_continuous_pixmaps(self): self._release_pixmap(index) def _release_pixmap(self, page_index: int): + form = self._form_for_current() + if form is not None and 0 <= page_index < len(self._continuous_pages): + form.detach_page(self._continuous_pages[page_index]) if 0 <= page_index < len(self._continuous_pages): self._continuous_pages[page_index].clear() self._continuous_rendered.discard(page_index) @@ -2906,6 +3661,7 @@ def _render_continuous_page(self, page_index: int): pixmap.stride, QImage.Format_RGB888, ) + self._paint_form_highlights(image, page, page_index, render_zoom) if page_index == self.current_page: highlight_rects = self._active_highlight_rects() if highlight_rects: @@ -2914,6 +3670,9 @@ def _render_continuous_page(self, page_index: int): qp.setDevicePixelRatio(dpr) self._continuous_pages[page_index].setPixmap(qp) self._continuous_rendered.add(page_index) + self._attach_form_overlays( + self._continuous_pages[page_index], page_index, layout_zoom + ) except Exception: # Leave the placeholder in place — one unrenderable page must not # take the rest of the document down with it. @@ -3324,16 +4083,416 @@ def _save_document_annotations(self): self.statusBar().showMessage(f"Could not save annotations: {exc}", 5000) def _save_document(self): - """Explicit full save via File > Save.""" + """Explicit save via File > Save (form values + annotations).""" if self.current_path is None or self.document is None: self.statusBar().showMessage("No document open", 3000) return + form = self._form_for_current() + if form is not None and form.dirty: + try: + form.save(self.document, self.current_path) + self._update_window_title_dirty() + self._update_navigator_item_for_tab(self.current_tab_id) + self.statusBar().showMessage("Document saved", 3000) + return + except Exception as exc: + self.statusBar().showMessage(f"Save failed: {exc}", 5000) + return try: self.document.save(self.current_path, garbage=1, deflate=True) self.statusBar().showMessage("Document saved", 3000) except Exception as exc: self.statusBar().showMessage(f"Save failed: {exc}", 5000) + def _save_document_as(self): + """Save As — full save to a new path, updating the tab.""" + if self.document is None or self.current_path is None: + self.statusBar().showMessage("No document open", 3000) + return + default_name = f"{Path(self.current_path).stem}_completed.pdf" + new_path, _ = QFileDialog.getSaveFileName( + self, + "Save As", + str(Path(self.current_path).with_name(default_name)), + "PDF files (*.pdf)", + ) + if not new_path: + return + if not new_path.lower().endswith(".pdf"): + new_path += ".pdf" + try: + form = self._form_for_current() + if form is not None: + self._write_dirty_form_values(form) + form.save_as(self.document, new_path) + else: + self.document.save(new_path, garbage=1, deflate=True) + self.current_path = new_path + if self.current_tab_id in self.tabs: + self.tabs[self.current_tab_id].path = new_path + self._add_recent_file(new_path) + self._update_window_title_dirty() + self.statusBar().showMessage(f"Saved as {Path(new_path).name}", 4000) + except Exception as exc: + self.statusBar().showMessage(f"Save As failed: {exc}", 5000) + + def _write_dirty_form_values(self, form): + for name in form._dirty_names: + field = form._by_name.get(name) + if field is None or not field.is_editable(): + continue + try: + _ff.set_field_value(self.document, field, form.current_value(field)) + except Exception: + continue + + # ------------------------------------------------------------------ + # AcroForm — Phase 2 (v1.3.0 / 1.3.1 / 1.3.2) + # ------------------------------------------------------------------ + + def _init_form(self): + """Build the FormController for the current tab if the doc has fields.""" + if self.current_tab_id is None or self.document is None or self.current_path is None: + return None + controllers = getattr(self, "_form_controllers", {}) + stale = controllers.pop(self.current_tab_id, None) + if stale is not None: + stale.detach_all() + controller = _FormController(self, self.current_tab_id) + controller.load(self.document, self.current_path) + controllers[self.current_tab_id] = controller + count = len(controller.fields) + if count and _ff.has_form_fields(self.document): + self._mark_recent_form_doc(self.current_path) + self.statusBar().showMessage( + f"Form detected — {len(controller.editable_fields)} fillable field(s). " + "Click a field to complete it.", + 7000, + ) + self._rebuild_navigator() + self._update_form_menu_state() + return controller + + def _form_for_current(self): + if self.current_tab_id is None: + return None + return getattr(self, "_form_controllers", {}).get(self.current_tab_id) + + def _drop_form_controller(self, tab_id): + controller = getattr(self, "_form_controllers", {}).pop(tab_id, None) + if controller is not None: + controller.detach_all() + + def _on_form_dirty(self, tab_id): + self._update_window_title_dirty() + self._update_form_menu_state() + self._update_navigator_item_for_tab(tab_id) + + def _update_window_title_dirty(self): + if self.current_path: + base = f"{self.APP_NAME} - {Path(self.current_path).name}" + else: + base = self.APP_NAME + form = self._form_for_current() + dirty = form is not None and form.dirty + self.setWindowTitle(("● " if dirty else "") + base) + + def _on_form_focus(self, field): + if field.validation_message: + self.statusBar().showMessage(field.validation_message, 6000) + else: + hint = field.display_name() + if field.detected_type: + hint += f" ({field.detected_type}{' inferred' if field.is_inferred else ''})" + if field.required: + hint += " [Required]" + self.statusBar().showMessage(hint, 6000) + self._select_navigator_field(field) + + def _on_form_validation(self, field, message): + if message: + self.statusBar().showMessage(message, 6000) + + # -- highlight painting ------------------------------------------------ + + def _paint_form_highlights(self, image, page, page_index, zoom): + form = self._form_for_current() + if form is None or not form.fields: + return + painter = QPainter(image) + try: + for field in form.fields: + if field.page_index != page_index: + continue + self._paint_field_highlight(painter, field, page, zoom) + finally: + painter.end() + + def _paint_field_highlight(self, painter, field, page, zoom): + if field.field_type == _ff.FieldType.RADIO: + for opt in field.option_rects: + x = int((opt[0] - page.rect.x0) * zoom) + y = int((opt[1] - page.rect.y0) * zoom) + w = int((opt[2] - opt[0]) * zoom) + h = int((opt[3] - opt[1]) * zoom) + if w > 0 and h > 0: + painter.setPen(QColor(*_FORM_FILLABLE_BORDER)) + painter.setBrush(QColor(*_FORM_FILLABLE_FILL)) + painter.drawRect(x, y, w, h) + return + rx = field.rect + x = int((rx[0] - page.rect.x0) * zoom) + y = int((rx[1] - page.rect.y0) * zoom) + w = int((rx[2] - rx[0]) * zoom) + h = int((rx[3] - rx[1]) * zoom) + if w <= 0 or h <= 0: + return + if field.is_editable(): + painter.setPen(QColor(*_FORM_FILLABLE_BORDER)) + painter.setBrush(QColor(*_FORM_FILLABLE_FILL)) + else: + painter.setPen(QPen(QColor(*_FORM_READONLY_BORDER), 1, Qt.DashLine)) + painter.setBrush(Qt.NoBrush) + painter.drawRect(x, y, w, h) + # Required-but-empty (or invalid) fields get an amber outline. + if field.required and field.is_editable(): + status = self._form_for_current().field_status(field) + if status in ("required", "invalid"): + painter.setPen(QColor(*_FORM_REQUIRED_EMPTY_BORDER)) + painter.setBrush(Qt.NoBrush) + painter.drawRect(x - 1, y - 1, w + 2, h + 2) + + def _attach_form_overlays(self, label, page_index, zoom): + form = self._form_for_current() + if form is None: + return + try: + page = self.document.load_page(page_index) + except Exception: + return + form.attach_page(label, page_index, zoom, page.rect) + + # -- field navigation ------------------------------------------------- + + def _form_next_field(self): + form = self._form_for_current() + if form is not None: + form.focus_next(forward=True) + + def _form_previous_field(self): + form = self._form_for_current() + if form is not None: + form.focus_next(forward=False) + + def _jump_to_page(self, page_index): + if self.document is None: + return + target = max(0, min(page_index, self.document.page_count - 1)) + if target != self.current_page: + self.current_page = target + self.clear_text_selection(render=False) + self._sync_search_result_to_page() + self.render_page() + else: + self.render_page() # re-attach overlays for this page window + + def _ensure_field_visible(self, field): + controller = self._form_for_current() + if controller is None: + return + widgets = controller._field_widgets.get(field.name) + if widgets: + self.scroll_area.ensureWidgetVisible(widgets[0], 40, 40) + + # -- Form Navigator ---------------------------------------------------- + + def _toggle_navigator(self, checked=None): + if self.navigator_action.isChecked(): + self.form_dock.show() + self._rebuild_navigator() + else: + self.form_dock.hide() + + def _rebuild_navigator(self): + if not hasattr(self, "form_tree"): + return + form = self._form_for_current() + self.form_tree.clear() + if form is None or not form.fields: + self.form_dock.hide() + if self.navigator_action.isChecked(): + self.navigator_action.setChecked(False) + return + pages: dict = {} + for row in form.navigator_rows(): + pages.setdefault(row["page"], []).append(row) + for page_index in sorted(pages): + page_item = QTreeWidgetItem(self.form_tree) + page_item.setText(0, f"Page {page_index + 1}") + page_item.setData(0, Qt.UserRole, None) + for row in pages[page_index]: + item = QTreeWidgetItem(page_item) + item.setText(0, row["name"]) + item.setText(1, row["status"].capitalize()) + item.setText(2, row["value"]) + item.setData(0, Qt.UserRole, {"page": page_index, "name": row["name"]}) + if row["validation"]: + item.setToolTip(0, f"{row['name']}\n{row['validation']}") + status = row["status"] + if status == "required": + item.setForeground(0, QColor(245, 158, 11)) + elif status == "invalid": + item.setForeground(0, QColor(220, 38, 38)) + page_item.setExpanded(True) + self.form_tree.expandAll() + + def _update_navigator_item_for_tab(self, tab_id): + if tab_id == self.current_tab_id: + self._navigator_rebuild_timer.start() + + def _update_navigator_item(self, field): + self._navigator_rebuild_timer.start() + + def _select_navigator_field(self, field): + if not hasattr(self, "form_tree"): + return + root = self.form_tree.invisibleRootItem() + for i in range(root.childCount()): + page_item = root.child(i) + for j in range(page_item.childCount()): + item = page_item.child(j) + if item.data(0, Qt.UserRole) == {"page": field.page_index, "name": field.name}: + self.form_tree.setCurrentItem(item) + self.form_tree.scrollToItem(item) + return + + def _on_navigator_item_clicked(self, item, _column): + data = item.data(0, Qt.UserRole) + if not data: + return + form = self._form_for_current() + if form is None: + return + for field in form.fields: + if field.page_index == data["page"] and field.name == data["name"]: + form.focus_field(field) + break + + # -- completion workflow ------------------------------------------------ + + def _form_clear_field(self): + form = self._form_for_current() + if form is None or not form.fields: + self.statusBar().showMessage("No form fields open", 3000) + return + editable = form.editable_fields + if 0 <= form._current_index < len(editable): + form.clear_field(editable[form._current_index]) + self._update_navigator_item_for_tab(self.current_tab_id) + else: + self.statusBar().showMessage("Focus a field first, then clear it", 3000) + + def _form_clear_all(self): + form = self._form_for_current() + if form is None or not form.fields: + self.statusBar().showMessage("No form fields open", 3000) + return + answer = QMessageBox.question( + self, + "Clear Form", + "Clear all fillable fields? Read-only fields are kept.", + QMessageBox.Yes | QMessageBox.No, + QMessageBox.No, + ) + if answer == QMessageBox.Yes: + form.clear_form() + self._update_navigator_item_for_tab(self.current_tab_id) + self.statusBar().showMessage("Form cleared", 3000) + + def _form_review_complete(self): + form = self._form_for_current() + if form is None or not form.fields: + self.statusBar().showMessage("No form fields open", 3000) + return + counts = form.completion_summary() + problems = [row for row in form.navigator_rows() if row["status"] in ("required", "invalid")] + lines = [ + f"Fields filled: {counts['filled']}", + f"Fields empty: {counts['empty']}", + f"Required missing: {counts['required']}", + f"Invalid values: {counts['invalid']}", + ] + if problems: + lines.append("") + lines.append("Needs attention:") + for row in problems[:10]: + tag = "required" if row["status"] == "required" else "invalid" + lines.append(f" • {tag} — {row['name']} (page {row['page'] + 1})") + if len(problems) > 10: + lines.append(f" … and {len(problems) - 10} more") + box = QMessageBox(self) + box.setWindowTitle("Review & Complete") + box.setText("\n".join(lines)) + box.setStandardButtons(QMessageBox.Ok | QMessageBox.Save) + box.button(QMessageBox.Save).setText("Save Form") + if box.exec() == QMessageBox.Save: + self._save_document() + + # -- close warning ------------------------------------------------------ + + def _confirm_discard_form(self, tab_id) -> bool: + """If the tab has unsaved form edits, ask. Returns True to proceed.""" + controller = getattr(self, "_form_controllers", {}).get(tab_id) + if controller is None or not controller.dirty: + return True + tab = self.tabs.get(tab_id) + answer = QMessageBox.question( + self, + "Unsaved Form", + "This form has unsaved changes. Save before closing?", + QMessageBox.Save | QMessageBox.Discard | QMessageBox.Cancel, + QMessageBox.Save, + ) + if answer == QMessageBox.Save: + if tab is not None and tab.document is not None and tab.path: + try: + controller.save(tab.document, tab.path) + except Exception: + pass + return True + if answer == QMessageBox.Discard: + path = tab.path if tab is not None and tab.path else getattr(self, "current_path", None) + if path and controller._state_store is not None: + controller._state_store.clear(path) + return True + return False + + # -- recent-file form markers -------------------------------------------- + + def _mark_recent_form_doc(self, path): + try: + current = set(self.settings.value("formDocs", [], list)) + current.add(str(Path(path).resolve())) + self.settings.setValue("formDocs", list(current)) + except Exception: + pass + + def _is_recent_form_doc(self, path) -> bool: + try: + return str(Path(path).resolve()) in set(self.settings.value("formDocs", [], list)) + except Exception: + return False + + def _update_form_menu_state(self): + if not self._form_menu: + return + form = self._form_for_current() + has_form = form is not None and bool(form.fields) + for action in self._form_menu_actions: + if action is self.navigator_action: + continue # navigator toggle always available + action.setEnabled(has_form) + # ------------------------------------------------------------------ # Navigation # ------------------------------------------------------------------ @@ -4302,6 +5461,13 @@ def _toggle_auto_restore(self, checked): self.settings.setValue("autoRestore", checked) def closeEvent(self, event): + # A debounced render must not fire after the docs are closed below. + self._render_timer.stop() + # Warn before discarding unsaved form work (Phase 2). + for tab_id in list(self.tabs.keys()): + if not self._confirm_discard_form(tab_id): + event.ignore() + return try: self._save_current_state() except Exception: @@ -4315,6 +5481,12 @@ def closeEvent(self, event): self.settings.setValue("session", session) except Exception: pass # best-effort session save # nosec B110 + # Flush form autosaves + detach overlays before closing docs. + for tab_id, controller in getattr(self, "_form_controllers", {}).items(): + try: + controller.detach_all() + except Exception: + pass # Close docs for tab_id, tab in self.tabs.items(): if tab.document is not None: @@ -4323,6 +5495,7 @@ def closeEvent(self, event): except Exception: pass # best-effort document close # nosec B110 self.tabs.clear() + self._form_controllers.clear() super().closeEvent(event) # ------------------------------------------------------------------ diff --git a/packages/mcp-server/pyproject.toml b/packages/mcp-server/pyproject.toml index c31372b..3be01c6 100644 --- a/packages/mcp-server/pyproject.toml +++ b/packages/mcp-server/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "openreader-mcp" -version = "1.2.8" +version = "1.3.0" description = "AI assistant tools for PDFs — read, search, compare, merge, split, compress, and index PDFs locally." readme = "README.md" license = { text = "AGPL-3.0-or-later" } diff --git a/packages/mcp-server/src/openreader_mcp/_form_fields.py b/packages/mcp-server/src/openreader_mcp/_form_fields.py new file mode 100644 index 0000000..7dd89fe --- /dev/null +++ b/packages/mcp-server/src/openreader_mcp/_form_fields.py @@ -0,0 +1,774 @@ +"""AcroForm field intelligence — shared by the GUI and the MCP server. + +Pure-logic module: it must never import PySide6 so it can run inside the +standalone MCP server process and be unit-tested without a Qt platform. + +Responsibilities +--------------- +* v1.3.0 — enumerate AcroForm widgets into a normalized ``FormField`` model, + read and write field values (including radio groups / checkboxes / choices), + respect read-only and max-length rules. +* v1.3.1 — infer and validate field types (date, phone, ZIP, email, currency, + numeric) from PDF formatting rules, field names and nearby labels. Inference + is advisory and is never presented as certainty. +* v1.3.2 — ``FormStateStore`` persists unsaved form values and user type + overrides to local JSON for autosave / crash recovery. +""" + +from __future__ import annotations + +import hashlib +import json +import re +from dataclasses import dataclass, field +from pathlib import Path +from typing import Optional + +import fitz + + +# --------------------------------------------------------------------------- +# Normalized field types +# --------------------------------------------------------------------------- + + +class FieldType: + """Normalized AcroForm field types (independent of PyMuPDF constants).""" + + TEXT = "text" + MULTILINE = "multiline" + CHECKBOX = "checkbox" + RADIO = "radio" + COMBO = "combo" + LISTBOX = "listbox" + SIGNATURE = "signature" + PUSHBUTTON = "button" + UNKNOWN = "unknown" + + +EDITABLE_TYPES = { + FieldType.TEXT, + FieldType.MULTILINE, + FieldType.CHECKBOX, + FieldType.RADIO, + FieldType.COMBO, + FieldType.LISTBOX, +} + +# Detected "field intelligence" types used for affordances + validation. +TYPE_DATE = "date" +TYPE_TIME = "time" +TYPE_PHONE = "phone" +TYPE_ZIP = "zip" +TYPE_EMAIL = "email" +TYPE_CURRENCY = "currency" +TYPE_NUMERIC = "numeric" + +# --------------------------------------------------------------------------- +# Widget flag bits (PDF spec — ISO 32000 Ff entries) +# --------------------------------------------------------------------------- + +FLAG_READONLY = 0x1 +FLAG_REQUIRED = 0x2 +FLAG_NO_EXPORT = 0x4 +FLAG_MULTILINE = 0x1000 +FLAG_PASSWORD = 0x2000 +FLAG_NO_TOGGLE_TO_OFF = 0x4000 +FLAG_RADIO = 0x8000 +FLAG_PUSHBUTTON = 0x10000 +FLAG_COMBO = 0x20000 +FLAG_EDIT = 0x40000 +FLAG_COMB = 0x100000 +FLAG_MULTISELECT = 0x200000 + +# PyMuPDF text_format values → explicit detected types. +_EXPLICIT_BY_TEXT_FORMAT = { + fitz.PDF_WIDGET_TX_FORMAT_DATE: TYPE_DATE, # 3 + fitz.PDF_WIDGET_TX_FORMAT_TIME: TYPE_TIME, # 4 + fitz.PDF_WIDGET_TX_FORMAT_NUMBER: TYPE_NUMERIC, # 1 +} + + +# --------------------------------------------------------------------------- +# FormField model +# --------------------------------------------------------------------------- + + +@dataclass +class FormField: + """Normalized, defensive view of one AcroForm field.""" + + name: str + page_index: int + rect: tuple = (0.0, 0.0, 0.0, 0.0) # PDF points (x0, y0, x1, y1) + field_type: str = FieldType.TEXT + # Display label (from /TU) when present, else the field name. + label: str = "" + + # Field rules + readonly: bool = False + required: bool = False + multiline: bool = False + password: bool = False + comb: bool = False + max_length: int = 0 + hidden: bool = False + + # Choice fields + editable_choice: bool = False + choices: list = field(default_factory=list) + + # Button widgets + button_caption: Optional[str] = None + on_state: str = "Yes" + radio_group_xref: int = -1 + # Parallel to ``choices``: the PDF rect of each radio option (for overlays). + option_rects: list = field(default_factory=list) + + # Formatting + text_format: int = 0 + + # Current value in the normalized model: + # text/multiline/combo/listbox → str + # checkbox → bool + # radio → str (selected option caption/on-state) or "" + value: object = "" + + # Type intelligence (v1.3.1) + explicit_type: Optional[str] = None + inferred_type: Optional[str] = None + detected_type: Optional[str] = None + type_confidence: float = 0.0 + is_inferred: bool = False + validation_message: str = "" + + # Back-reference used to find the live widget(s) when writing. + widget_xref: int = -1 + + # ------------------------------------------------------------------ + def to_dict(self) -> dict: + """Serializable dict for the MCP server / tool output.""" + return { + "name": self.name, + "label": self.label, + "page": self.page_index + 1, + "page_index": self.page_index, + "rect": [round(v, 2) for v in self.rect], + "type": self.field_type, + "detected_type": self.detected_type, + "explicit_type": self.explicit_type, + "inferred_type": self.inferred_type, + "is_inferred": self.is_inferred, + "type_confidence": round(self.type_confidence, 2), + "readonly": self.readonly, + "required": self.required, + "max_length": self.max_length, + "password": self.password, + "choices": list(self.choices), + "option_rects": [[round(v, 2) for v in r] for r in self.option_rects], + "value": self.value, + "validation_message": self.validation_message, + } + + def is_editable(self) -> bool: + return self.field_type in EDITABLE_TYPES and not self.readonly and not self.hidden + + def display_name(self) -> str: + return self.label or self.name or "(unnamed field)" + + +# --------------------------------------------------------------------------- +# Widget → FormField mapping helpers +# --------------------------------------------------------------------------- + + +def _normalize_type(widget) -> str: + wtype = widget.field_type + if wtype == fitz.PDF_WIDGET_TYPE_TEXT: + return FieldType.MULTILINE if (widget.field_flags & FLAG_MULTILINE) else FieldType.TEXT + if wtype == fitz.PDF_WIDGET_TYPE_CHECKBOX: + return FieldType.CHECKBOX + if wtype == fitz.PDF_WIDGET_TYPE_COMBOBOX: + return FieldType.COMBO + if wtype == fitz.PDF_WIDGET_TYPE_LISTBOX: + return FieldType.LISTBOX + if wtype == fitz.PDF_WIDGET_TYPE_RADIOBUTTON: + return FieldType.RADIO + if wtype == fitz.PDF_WIDGET_TYPE_SIGNATURE: + return FieldType.SIGNATURE + if wtype == fitz.PDF_WIDGET_TYPE_BUTTON: + return FieldType.PUSHBUTTON + return FieldType.UNKNOWN + + +def _safe_on_state(widget) -> str: + """On-state name of a checkbox/radio widget, defaulting to 'Yes'.""" + try: + state = widget.on_state() + if isinstance(state, str) and state: + return state + if state is True: + return "Yes" + except Exception: + pass + return "Yes" + + +def _clean_field_name(widget, page_index: int) -> str: + name = getattr(widget, "field_name", None) + if name: + return name + return f"field_{page_index}_{widget.xref}" + + +def _widget_value(widget): + """Normalized current value of a non-grouped widget.""" + value = widget.field_value + if value is None: + return "" + if widget.field_type == fitz.PDF_WIDGET_TYPE_CHECKBOX: + return str(value) != "Off" and bool(value) + return str(value) + + +def _from_widget(widget, page_index: int) -> FormField: + flags = widget.field_flags + field_type = _normalize_type(widget) + name = _clean_field_name(widget, page_index) + label = getattr(widget, "field_label", None) or name + rect = (widget.rect.x0, widget.rect.y0, widget.rect.x1, widget.rect.y1) + text_format = int(getattr(widget, "text_format", 0) or 0) + return FormField( + name=name, + page_index=page_index, + rect=rect, + field_type=field_type, + label=label, + readonly=bool(flags & FLAG_READONLY), + required=bool(flags & FLAG_REQUIRED), + multiline=bool(flags & FLAG_MULTILINE), + password=bool(flags & FLAG_PASSWORD), + comb=bool(flags & FLAG_COMB), + max_length=int(getattr(widget, "text_maxlen", 0) or 0), + hidden=int(getattr(widget, "field_display", 0) or 0) == 1, + editable_choice=bool(flags & FLAG_EDIT), + choices=list(getattr(widget, "choice_values", None) or []), + button_caption=getattr(widget, "button_caption", None), + on_state=_safe_on_state(widget), + radio_group_xref=int(getattr(widget, "rb_parent", None) or -1), + text_format=text_format, + value=_widget_value(widget), + widget_xref=widget.xref, + ) + + +def _from_radio_group(kids, page_index: int) -> FormField: + """Collapse the widgets of one radio group into a single FormField.""" + first = kids[0] + flags = first.field_flags + name = _clean_field_name(first, page_index) + choices = [] + option_rects = [] + selected = "" + for w in kids: + on = _safe_on_state(w) + caption = getattr(w, "button_caption", None) or on + if caption not in choices: + choices.append(caption) + option_rects.append((w.rect.x0, w.rect.y0, w.rect.x1, w.rect.y1)) + value = w.field_value + if value and str(value) != "Off": + selected = caption + rect = (first.rect.x0, first.rect.y0, first.rect.x1, first.rect.y1) + return FormField( + name=name, + page_index=page_index, + rect=rect, + field_type=FieldType.RADIO, + label=getattr(first, "field_label", None) or name, + readonly=bool(flags & FLAG_READONLY), + required=bool(flags & FLAG_REQUIRED), + choices=choices, + option_rects=option_rects, + radio_group_xref=int(getattr(first, "rb_parent", None) or -1), + value=selected, + widget_xref=first.xref, + ) + + +# --------------------------------------------------------------------------- +# Index building +# --------------------------------------------------------------------------- + + +def build_field_index(doc) -> list: + """Enumerate every AcroForm field in a document. + + Radio button groups are collapsed into a single ``FormField`` per group + (the widgets that share a ``/Parent``). + """ + fields: list = [] + radio_groups: dict = {} # rb_parent xref -> (page_index, [widgets]) + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + widgets = list(page.widgets()) + except Exception: + widgets = [] + for w in widgets: + if w.field_type == fitz.PDF_WIDGET_TYPE_RADIOBUTTON: + rbp = int(getattr(w, "rb_parent", None) or -1) + entry = radio_groups.setdefault(rbp, [page_index, []]) + entry[1].append(w) + else: + fields.append(_from_widget(w, page_index)) + for rbp, (page_index, kids) in radio_groups.items(): + fields.append(_from_radio_group(kids, page_index)) + fields.sort(key=lambda f: (f.page_index, f.rect[1], f.rect[0])) + return fields + + +def form_field_count(doc) -> int: + return len(build_field_index(doc)) + + +def has_form_fields(doc) -> bool: + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + if next(page.widgets(), None) is not None: + return True + except Exception: + continue + return False + + +def field_by_name(fields, name) -> Optional[FormField]: + for f in fields: + if f.name == name: + return f + return None + + +# --------------------------------------------------------------------------- +# Reading / writing values +# --------------------------------------------------------------------------- + + +def _widget_for_field(doc, field: FormField): + """Return ``(page, widget)`` backing a (non-radio-group) FormField. + + The page is returned too so the caller keeps a strong reference — a Widget's + annotation is bound to its page via a weakref, and PyMuPDF raises "Annot is + not bound to a page" if the page is garbage-collected before ``update()``. + """ + try: + page = doc.load_page(field.page_index) + except Exception: + return None, None + try: + for w in page.widgets(): + if w.xref == field.widget_xref: + return page, w + except Exception: + pass + return None, None + + +def _iter_radio_kids(doc, group_xref: int): + """Yield ``(page, widget)`` for every radio in a group.""" + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + for w in page.widgets(): + if int(getattr(w, "rb_parent", None) or -1) == group_xref: + yield page, w + except Exception: + continue + + +def get_field_value(doc, field: FormField): + """Re-read the current value of a field straight from the PDF.""" + if field.field_type == FieldType.RADIO: + for _page, w in _iter_radio_kids(doc, field.radio_group_xref): + value = w.field_value + if value and str(value) != "Off": + on = _safe_on_state(w) + return getattr(w, "button_caption", None) or on + return "" + _page, widget = _widget_for_field(doc, field) + if widget is None: + return field.value + return _widget_value(widget) + + +def _as_bool(value) -> bool: + """Coerce bool-ish values (agents may pass "true"/"false" strings).""" + if isinstance(value, bool): + return value + if isinstance(value, str): + return value.strip().lower() not in ("", "0", "false", "off", "no") + return bool(value) + + +def set_field_value(doc, field: FormField, value) -> bool: + """Write ``value`` into the PDF for ``field``. + + Respects read-only rules and max lengths. Returns ``True`` on success. + The value is stored via PyMuPDF's ``update()``, which regenerates the + appearance stream so the value renders in any PDF viewer. + """ + if not field.is_editable(): + return False + if field.field_type == FieldType.RADIO: + return _set_radio_value(doc, field, value) + if field.field_type == FieldType.CHECKBOX: + return _set_checkbox_value(doc, field, _as_bool(value)) + if field.field_type in (FieldType.COMBO, FieldType.LISTBOX): + return _set_choice_value(doc, field, value) + return _set_text_value(doc, field, value) + + +def _set_text_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + text = str(value) if value is not None else "" + maxlen = int(getattr(widget, "text_maxlen", 0) or 0) + if maxlen > 0: + text = text[:maxlen] + try: + widget.field_value = text + widget.update() + except Exception: + return False + return True + + +def _set_checkbox_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + on = _safe_on_state(widget) + try: + widget.field_value = on if value else "Off" + widget.update() + except Exception: + return False + return True + + +def _set_choice_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + text = str(value) if value is not None else "" + choices = list(getattr(widget, "choice_values", None) or []) + if text not in choices and not field.editable_choice: + return False + try: + widget.field_value = text + widget.update() + except Exception: + return False + return True + + +def _set_radio_value(doc, field: FormField, value) -> bool: + kids = list(_iter_radio_kids(doc, field.radio_group_xref)) + if not kids: + return False + text = str(value) if value is not None else "" + target = None + for _page, w in kids: + caption = getattr(w, "button_caption", None) or _safe_on_state(w) + if caption == text: + target = w + break + # Turn every option off first — setting a radio to "" resets the group. + for _page, w in kids: + try: + w.field_value = "" + w.update() + except Exception: + continue + if target is not None: + try: + target.field_value = _safe_on_state(target) + target.update() + except Exception: + return False + return True + + +# --------------------------------------------------------------------------- +# v1.3.1 — Field type intelligence +# --------------------------------------------------------------------------- + + +class FormTypeDetector: + """Detect field types from formatting rules, names and nearby labels. + + Two tiers are always kept distinct: + * ``explicit_type`` — authoritative, from the PDF's own formatting rule. + * ``inferred_type`` — heuristic, from the field name / nearby label. + Inference is advisory; callers must never present it as certainty. + """ + + # (regex, detected type, confidence) + NAME_PATTERNS = [ + (re.compile(r"(?i)(^|[_\- .])(date|dob|birth|born|birthday)([_\- .]|$)"), TYPE_DATE, 0.9), + (re.compile(r"(?i)(^|[_\- .])(ph|phone|tel|telephone|mobile|cell|fax)([_\- .]|$)"), TYPE_PHONE, 0.9), + (re.compile(r"(?i)(^|[_\- .])(zip|postal|postcode|pincode)([_\- .]|$)"), TYPE_ZIP, 0.9), + (re.compile(r"(?i)(^|[_\- .])(email|e-?mail)([_\- .]|$)"), TYPE_EMAIL, 0.95), + (re.compile(r"(?i)(^|[_\- .])(amount|price|cost|fee|salary|total|balance|currency|payment)([_\- .]|$)"), TYPE_CURRENCY, 0.85), + (re.compile(r"(?i)(^|[_\- .])(qty|quantity|count|number|num|age|year|weight|height)([_\- .]|$)"), TYPE_NUMERIC, 0.7), + ] + + # Simple label fragment heuristics (word-ish matches), lower confidence. + LABEL_PATTERNS = [ + (re.compile(r"(?i)\bdate\b|\bdob\b|\bbirth\b|\bborn\b"), TYPE_DATE, 0.6), + (re.compile(r"(?i)\bphone\b|\btelephone\b|\bmobile\b|\bcell\b"), TYPE_PHONE, 0.6), + (re.compile(r"(?i)\bzip\b|\bpostal\b|\bpostcode\b|\bpin\b"), TYPE_ZIP, 0.6), + (re.compile(r"(?i)\bemail\b|\be-?mail\b"), TYPE_EMAIL, 0.7), + (re.compile(r"(?i)\b(amount|price|cost|fee|salary|total|balance)\b|\$"), TYPE_CURRENCY, 0.6), + (re.compile(r"(?i)\b(quantity|qty|count|age|year)\b"), TYPE_NUMERIC, 0.55), + ] + + def detect(self, field: FormField, label_text: str = "") -> None: + """Populate the explicit / inferred / detected type fields in place.""" + explicit = None + if field.field_type in (FieldType.TEXT, FieldType.MULTILINE): + explicit = _EXPLICIT_BY_TEXT_FORMAT.get(field.text_format) + inferred = None + confidence = 0.0 + # Normalize camelCase ("postalCode" -> "postal_Code") so word-boundary + # patterns match common form naming conventions. + normalized_name = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", field.name or "") + for regex, ftype, conf in self.NAME_PATTERNS: + if regex.search(normalized_name): + inferred, confidence = ftype, conf + break + if inferred is None and label_text: + for regex, ftype, conf in self.LABEL_PATTERNS: + if regex.search(label_text): + inferred, confidence = ftype, conf + break + detected = explicit or inferred + field.explicit_type = explicit + field.inferred_type = inferred + field.detected_type = detected + field.type_confidence = confidence if detected == inferred else 1.0 + field.is_inferred = bool(inferred) and not explicit + + +def annotate_field_types(fields, doc) -> None: + """Run the type detector over every field, pulling nearby labels from the PDF.""" + detector = FormTypeDetector() + for f in fields: + label_text = _nearby_label_text(doc, f) if f.field_type in (FieldType.TEXT, FieldType.MULTILINE) else "" + detector.detect(f, label_text) + + +def _nearby_label_text(doc, field: FormField) -> str: + """Best-effort label text to the left / above a text field.""" + try: + page = doc.load_page(field.page_index) + words = page.get_text("words") + except Exception: + return "" + rx0, ry0, rx1, ry1 = field.rect + collected = [] + for word in words: + wx0, wy0, wx1, wy1, text, *_ = word + # Left of the field on the same line band, or directly above it. + left_of = wx1 <= rx0 + 2 and wy0 < ry1 and wy1 > ry0 - 6 and rx0 - wx1 < 220 + above = wy1 <= ry0 + 2 and wy1 >= ry0 - 40 and wx0 < rx1 and wx1 > rx0 - 60 + if left_of or above: + collected.append(text) + return " ".join(collected) + + +# --------------------------------------------------------------------------- +# v1.3.1 — Validation +# --------------------------------------------------------------------------- + + +class FormValidator: + """Advisory, international-tolerant validation for detected field types. + + Validation never blocks input — it only produces a message the UI can + surface. Values that do not match still save. + """ + + _EMAIL = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") + + @classmethod + def validate(cls, field: FormField, value) -> tuple: + """Return ``(ok: bool, message: str)`` for ``value`` on ``field``.""" + text = str(value or "").strip() + if not text or not field.detected_type: + return True, "" + rule = { + TYPE_DATE: cls._validate_date, + TYPE_TIME: cls._validate_time, + TYPE_PHONE: cls._validate_phone, + TYPE_ZIP: cls._validate_zip, + TYPE_EMAIL: cls._validate_email, + TYPE_CURRENCY: cls._validate_currency, + TYPE_NUMERIC: cls._validate_numeric, + }.get(field.detected_type) + if rule is None: + return True, "" + return rule(text) + + # -- individual rules ------------------------------------------------ + + @staticmethod + def _validate_date(text: str) -> tuple: + # Tolerates ISO, slash, dash, dotted and month-name dates. + tokens = re.split(r"[-/., ]+", text.strip()) + if len(tokens) < 3: + return False, "Expected a date like 2026-08-03." + if not all(tok.isdigit() or tok[:1].isalpha() for tok in tokens): + return False, "Expected a date like 2026-08-03." + year = None + for tok in tokens: + if len(tok) == 4 and tok.isdigit(): + year = int(tok) + break + months = { + "jan": 1, "feb": 2, "mar": 3, "apr": 4, "may": 5, "jun": 6, + "jul": 7, "aug": 8, "sep": 9, "oct": 10, "nov": 11, "dec": 12, + } + month_ok = any(tok.lower()[:3] in months for tok in tokens) + day_ok = any(tok.isdigit() and 1 <= int(tok) <= 31 for tok in tokens) + if year is not None and (month_ok or day_ok): + return True, "" + if month_ok and day_ok: + return True, "" + return False, "Expected a date like 2026-08-03." + + @staticmethod + def _validate_time(text: str) -> tuple: + if re.match(r"^\d{1,2}:\d{2}(:\d{2})?(\s*[AaPp][Mm])?$", text.strip()): + return True, "" + return False, "Expected a time like 14:30." + + @staticmethod + def _validate_phone(text: str) -> tuple: + digits = re.sub(r"[^\d]", "", text) + if text.lstrip().startswith("+"): + digits = digits.lstrip() or "" + cleaned = re.sub(r"[\s\-()./]", "", text) + if cleaned.startswith("+"): + cleaned = cleaned[1:] + if cleaned.isdigit() and 6 <= len(cleaned) <= 15: + return True, "" + return False, "Expected a phone number like +1 555 123 4567." + + @staticmethod + def _validate_zip(text: str) -> tuple: + cleaned = re.sub(r"[\s\-]", "", text) + # International postal codes are alphanumeric and 3–10 characters. + if cleaned.isalnum() and 3 <= len(cleaned) <= 10: + return True, "" + return False, "Expected a postal code (letters and digits)." + + @staticmethod + def _validate_email(text: str) -> tuple: + if FormValidator._EMAIL.match(text.strip()): + return True, "" + return False, "Expected an email address like name@example.com." + + @staticmethod + def _validate_currency(text: str) -> tuple: + cleaned = text.strip().replace(",", "") + cleaned = re.sub(r"^[$£€₹¥]|[$£€₹¥]$", "", cleaned) + if re.match(r"^\d+(\.\d{1,2})?$", cleaned) and cleaned.replace(".", "").isdigit(): + return True, "" + return False, "Expected an amount like 1,234.56." + + @staticmethod + def _validate_numeric(text: str) -> tuple: + cleaned = text.strip().replace(",", "") + if re.match(r"^[+-]?\d+(\.\d+)?$", cleaned): + return True, "" + return False, "Expected a number." + + +# --------------------------------------------------------------------------- +# v1.3.2 — Form state store (autosave / crash recovery / overrides) +# --------------------------------------------------------------------------- + + +class FormStateStore: + """Persist unsaved form values and user type overrides to local JSON. + + Keyed by document path hash so form work survives app restarts. The GUI + owns the file location; this class is deliberately dumb and Qt-free. + """ + + STATE_VERSION = 1 + FILE_PREFIX = "formstate_" + + def __init__(self, base_dir=None): + self.base_dir = Path(base_dir) if base_dir else None + + # -- key / path helpers ---------------------------------------------- + + def _dir(self) -> Path: + return self.base_dir + + @staticmethod + def key_for_path(path) -> str: + return hashlib.sha256(str(path).encode("utf-8")).hexdigest() + + def _file_for(self, path) -> Path: + return self._dir() / f"{self.FILE_PREFIX}{self.key_for_path(path)}.json" + + # -- read / write ---------------------------------------------------- + + def load(self, path) -> dict: + try: + data = json.loads(self._file_for(path).read_text(encoding="utf-8")) + if isinstance(data, dict) and data.get("version") == self.STATE_VERSION: + return data + except Exception: + pass + return {} + + def save(self, path, values: dict, overrides: Optional[dict] = None) -> None: + data = { + "version": self.STATE_VERSION, + "values": values or {}, + "overrides": overrides or {}, + } + try: + self._dir().mkdir(parents=True, exist_ok=True) + tmp = self._file_for(path).with_suffix(".tmp") + tmp.write_text(json.dumps(data, indent=2), encoding="utf-8") + tmp.replace(self._file_for(path)) + except Exception: + pass # best-effort autosave must never crash the app + + def clear(self, path) -> None: + try: + self._file_for(path).unlink(missing_ok=True) + except Exception: + pass + + def has_state(self, path) -> bool: + try: + return self._file_for(path).exists() + except Exception: + return False diff --git a/packages/mcp-server/src/openreader_mcp/server.py b/packages/mcp-server/src/openreader_mcp/server.py index c7c281f..fe3d74c 100644 --- a/packages/mcp-server/src/openreader_mcp/server.py +++ b/packages/mcp-server/src/openreader_mcp/server.py @@ -39,6 +39,7 @@ IndexProgress, ) from ._comparison import compare_pdfs as _lib_compare_pdfs, generate_diff_summary +from . import _form_fields as _ff # --------------------------------------------------------------------------- # Safety limits @@ -314,6 +315,126 @@ def _search_single_pdf(path_str: str, query: str) -> list[dict]: from mcp.types import Tool, TextContent +def _form_fields(path_str: str) -> list[dict]: + """Enumerate AcroForm fields with type intelligence, as dicts.""" + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + return [f.to_dict() for f in fields] + finally: + doc.close() + + +def _find_form_field(fields: list, field_ref: str) -> Any: + for f in fields: + if f.name == field_ref or f.label == field_ref: + return f + return None + + +def _save_form_doc(doc, src_path: Path, output_path: str | None) -> str: + """Incremental save to the original, or a full save to ``output_path``.""" + if output_path: + out = str(Path(output_path).expanduser().resolve()) + doc.save(out, garbage=1, deflate=True) + return out + try: + doc.save(str(src_path), incremental=True, encryption=0) + except Exception: + doc.save(str(src_path), garbage=1, deflate=True) + return str(src_path) + + +def _form_get_field(path_str: str, field_ref: str) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + return field.to_dict() + finally: + doc.close() + + +def _form_set_value(path_str: str, field_ref: str, value, output_path: str | None = None) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + if not field.is_editable(): + raise ValueError(f"Field '{field_ref}' is read-only or not editable.") + if not _ff.set_field_value(doc, field, value): + raise ValueError(f"Could not write value to field '{field_ref}'.") + saved = _save_form_doc(doc, p, output_path) + return { + "field": field.name, + "value": _ff.get_field_value(doc, field), + "saved_to": saved, + } + finally: + doc.close() + + +def _form_fill(path_str: str, values: dict, output_path: str | None = None) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + by_name = {f.name: f for f in fields} + results = [] + for ref, value in (values or {}).items(): + field = by_name.get(ref) + if field is None: + results.append({"field": ref, "ok": False, "error": "field not found"}) + continue + if not field.is_editable(): + results.append({"field": ref, "ok": False, "error": "read-only or unsupported"}) + continue + ok = _ff.set_field_value(doc, field, value) + results.append( + { + "field": ref, + "ok": ok, + "value": _ff.get_field_value(doc, field) if ok else None, + "error": None if ok else "write failed", + } + ) + saved = _save_form_doc(doc, p, output_path) if any(r["ok"] for r in results) else None + return {"results": results, "saved_to": saved} + finally: + doc.close() + + +def _form_validate(path_str: str, field_ref: str, value) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + ok, message = _ff.FormValidator.validate(field, value) + return { + "field": field.name, + "detected_type": field.detected_type, + "ok": ok, + "message": message, + } + finally: + doc.close() + + TOOLS: list[Tool] = [ Tool( name="extract_text", @@ -482,6 +603,73 @@ def _search_single_pdf(path_str: str, query: str) -> list[dict]: "properties": {}, }, ), + Tool( + name="form_list_fields", + description="List all AcroForm fields in a PDF with their metadata — name, page, type, required/readonly flags, max length, choices, current value, and any detected field type (date, phone, ZIP, email, currency, numeric). Use this to discover what a PDF form contains before filling it.", + inputSchema={ + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the PDF file"} + }, + "required": ["path"], + }, + ), + Tool( + name="form_get_field", + description="Get full details about a single AcroForm field by name, including formatting rule, detected type, choices, and current value.", + inputSchema={ + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the PDF file"}, + "field": {"type": "string", "description": "The field name (or label) to inspect"}, + }, + "required": ["path", "field"], + }, + ), + Tool( + name="form_set_value", + description="Set the value of a single AcroForm field and save the PDF (incrementally to the original, or to output_path). Respects read-only fields and max lengths. Checkboxes accept true/false, radios accept the option label, combo/listbox fields accept one of their choices.", + inputSchema={ + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the PDF file"}, + "field": {"type": "string", "description": "The field name (or label) to set"}, + "value": {"type": "string", "description": "The value to write"}, + "output_path": {"type": "string", "description": "Optional path to save a copy to"}, + }, + "required": ["path", "field", "value"], + }, + ), + Tool( + name="form_fill", + description="Fill multiple AcroForm fields at once from a mapping of field name to value, then save once. Returns a per-field success/failure report. Saves incrementally to the original by default, or to output_path.", + inputSchema={ + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the PDF file"}, + "values": { + "type": "object", + "additionalProperties": {"type": "string"}, + "description": "Mapping of field name to value", + }, + "output_path": {"type": "string", "description": "Optional path to save a copy to"}, + }, + "required": ["path", "values"], + }, + ), + Tool( + name="form_validate", + description="Validate a value against a field's detected type (date, phone, ZIP, email, currency, numeric) without saving. Advisory only — returns ok/message and never blocks input.", + inputSchema={ + "type": "object", + "properties": { + "path": {"type": "string", "description": "Path to the PDF file"}, + "field": {"type": "string", "description": "The field name (or label) whose value should be validated"}, + "value": {"type": "string", "description": "The value to validate"}, + }, + "required": ["path", "field", "value"], + }, + ), ] @@ -583,6 +771,24 @@ async def _handle_call(name: str, args: dict) -> list[TextContent]: ], indent=2), )] + case "form_list_fields": + return [TextContent(type="text", text=json.dumps(_form_fields(args["path"]), indent=2))] + + case "form_get_field": + return [TextContent(type="text", text=json.dumps(_form_get_field(args["path"], args["field"]), indent=2))] + + case "form_set_value": + result = _form_set_value(args["path"], args["field"], args["value"], args.get("output_path")) + return [TextContent(type="text", text=json.dumps(result, indent=2))] + + case "form_fill": + result = _form_fill(args["path"], args["values"], args.get("output_path")) + return [TextContent(type="text", text=json.dumps(result, indent=2))] + + case "form_validate": + result = _form_validate(args["path"], args["field"], args["value"]) + return [TextContent(type="text", text=json.dumps(result, indent=2))] + case _: return [TextContent(type="text", text=f"Unknown tool: {name}")] diff --git a/packaging/msix/AppInstaller.xml b/packaging/msix/AppInstaller.xml index 358a296..481facb 100644 --- a/packaging/msix/AppInstaller.xml +++ b/packaging/msix/AppInstaller.xml @@ -18,7 +18,7 @@ diff --git a/packaging/msix/AppxManifest.xml b/packaging/msix/AppxManifest.xml index 0dc8a55..0d948dd 100644 --- a/packaging/msix/AppxManifest.xml +++ b/packaging/msix/AppxManifest.xml @@ -24,7 +24,7 @@ + Version="1.3.0.0" /> OpenReader diff --git a/pdfreader_lib/form_fields.py b/pdfreader_lib/form_fields.py new file mode 100644 index 0000000..7dd89fe --- /dev/null +++ b/pdfreader_lib/form_fields.py @@ -0,0 +1,774 @@ +"""AcroForm field intelligence — shared by the GUI and the MCP server. + +Pure-logic module: it must never import PySide6 so it can run inside the +standalone MCP server process and be unit-tested without a Qt platform. + +Responsibilities +--------------- +* v1.3.0 — enumerate AcroForm widgets into a normalized ``FormField`` model, + read and write field values (including radio groups / checkboxes / choices), + respect read-only and max-length rules. +* v1.3.1 — infer and validate field types (date, phone, ZIP, email, currency, + numeric) from PDF formatting rules, field names and nearby labels. Inference + is advisory and is never presented as certainty. +* v1.3.2 — ``FormStateStore`` persists unsaved form values and user type + overrides to local JSON for autosave / crash recovery. +""" + +from __future__ import annotations + +import hashlib +import json +import re +from dataclasses import dataclass, field +from pathlib import Path +from typing import Optional + +import fitz + + +# --------------------------------------------------------------------------- +# Normalized field types +# --------------------------------------------------------------------------- + + +class FieldType: + """Normalized AcroForm field types (independent of PyMuPDF constants).""" + + TEXT = "text" + MULTILINE = "multiline" + CHECKBOX = "checkbox" + RADIO = "radio" + COMBO = "combo" + LISTBOX = "listbox" + SIGNATURE = "signature" + PUSHBUTTON = "button" + UNKNOWN = "unknown" + + +EDITABLE_TYPES = { + FieldType.TEXT, + FieldType.MULTILINE, + FieldType.CHECKBOX, + FieldType.RADIO, + FieldType.COMBO, + FieldType.LISTBOX, +} + +# Detected "field intelligence" types used for affordances + validation. +TYPE_DATE = "date" +TYPE_TIME = "time" +TYPE_PHONE = "phone" +TYPE_ZIP = "zip" +TYPE_EMAIL = "email" +TYPE_CURRENCY = "currency" +TYPE_NUMERIC = "numeric" + +# --------------------------------------------------------------------------- +# Widget flag bits (PDF spec — ISO 32000 Ff entries) +# --------------------------------------------------------------------------- + +FLAG_READONLY = 0x1 +FLAG_REQUIRED = 0x2 +FLAG_NO_EXPORT = 0x4 +FLAG_MULTILINE = 0x1000 +FLAG_PASSWORD = 0x2000 +FLAG_NO_TOGGLE_TO_OFF = 0x4000 +FLAG_RADIO = 0x8000 +FLAG_PUSHBUTTON = 0x10000 +FLAG_COMBO = 0x20000 +FLAG_EDIT = 0x40000 +FLAG_COMB = 0x100000 +FLAG_MULTISELECT = 0x200000 + +# PyMuPDF text_format values → explicit detected types. +_EXPLICIT_BY_TEXT_FORMAT = { + fitz.PDF_WIDGET_TX_FORMAT_DATE: TYPE_DATE, # 3 + fitz.PDF_WIDGET_TX_FORMAT_TIME: TYPE_TIME, # 4 + fitz.PDF_WIDGET_TX_FORMAT_NUMBER: TYPE_NUMERIC, # 1 +} + + +# --------------------------------------------------------------------------- +# FormField model +# --------------------------------------------------------------------------- + + +@dataclass +class FormField: + """Normalized, defensive view of one AcroForm field.""" + + name: str + page_index: int + rect: tuple = (0.0, 0.0, 0.0, 0.0) # PDF points (x0, y0, x1, y1) + field_type: str = FieldType.TEXT + # Display label (from /TU) when present, else the field name. + label: str = "" + + # Field rules + readonly: bool = False + required: bool = False + multiline: bool = False + password: bool = False + comb: bool = False + max_length: int = 0 + hidden: bool = False + + # Choice fields + editable_choice: bool = False + choices: list = field(default_factory=list) + + # Button widgets + button_caption: Optional[str] = None + on_state: str = "Yes" + radio_group_xref: int = -1 + # Parallel to ``choices``: the PDF rect of each radio option (for overlays). + option_rects: list = field(default_factory=list) + + # Formatting + text_format: int = 0 + + # Current value in the normalized model: + # text/multiline/combo/listbox → str + # checkbox → bool + # radio → str (selected option caption/on-state) or "" + value: object = "" + + # Type intelligence (v1.3.1) + explicit_type: Optional[str] = None + inferred_type: Optional[str] = None + detected_type: Optional[str] = None + type_confidence: float = 0.0 + is_inferred: bool = False + validation_message: str = "" + + # Back-reference used to find the live widget(s) when writing. + widget_xref: int = -1 + + # ------------------------------------------------------------------ + def to_dict(self) -> dict: + """Serializable dict for the MCP server / tool output.""" + return { + "name": self.name, + "label": self.label, + "page": self.page_index + 1, + "page_index": self.page_index, + "rect": [round(v, 2) for v in self.rect], + "type": self.field_type, + "detected_type": self.detected_type, + "explicit_type": self.explicit_type, + "inferred_type": self.inferred_type, + "is_inferred": self.is_inferred, + "type_confidence": round(self.type_confidence, 2), + "readonly": self.readonly, + "required": self.required, + "max_length": self.max_length, + "password": self.password, + "choices": list(self.choices), + "option_rects": [[round(v, 2) for v in r] for r in self.option_rects], + "value": self.value, + "validation_message": self.validation_message, + } + + def is_editable(self) -> bool: + return self.field_type in EDITABLE_TYPES and not self.readonly and not self.hidden + + def display_name(self) -> str: + return self.label or self.name or "(unnamed field)" + + +# --------------------------------------------------------------------------- +# Widget → FormField mapping helpers +# --------------------------------------------------------------------------- + + +def _normalize_type(widget) -> str: + wtype = widget.field_type + if wtype == fitz.PDF_WIDGET_TYPE_TEXT: + return FieldType.MULTILINE if (widget.field_flags & FLAG_MULTILINE) else FieldType.TEXT + if wtype == fitz.PDF_WIDGET_TYPE_CHECKBOX: + return FieldType.CHECKBOX + if wtype == fitz.PDF_WIDGET_TYPE_COMBOBOX: + return FieldType.COMBO + if wtype == fitz.PDF_WIDGET_TYPE_LISTBOX: + return FieldType.LISTBOX + if wtype == fitz.PDF_WIDGET_TYPE_RADIOBUTTON: + return FieldType.RADIO + if wtype == fitz.PDF_WIDGET_TYPE_SIGNATURE: + return FieldType.SIGNATURE + if wtype == fitz.PDF_WIDGET_TYPE_BUTTON: + return FieldType.PUSHBUTTON + return FieldType.UNKNOWN + + +def _safe_on_state(widget) -> str: + """On-state name of a checkbox/radio widget, defaulting to 'Yes'.""" + try: + state = widget.on_state() + if isinstance(state, str) and state: + return state + if state is True: + return "Yes" + except Exception: + pass + return "Yes" + + +def _clean_field_name(widget, page_index: int) -> str: + name = getattr(widget, "field_name", None) + if name: + return name + return f"field_{page_index}_{widget.xref}" + + +def _widget_value(widget): + """Normalized current value of a non-grouped widget.""" + value = widget.field_value + if value is None: + return "" + if widget.field_type == fitz.PDF_WIDGET_TYPE_CHECKBOX: + return str(value) != "Off" and bool(value) + return str(value) + + +def _from_widget(widget, page_index: int) -> FormField: + flags = widget.field_flags + field_type = _normalize_type(widget) + name = _clean_field_name(widget, page_index) + label = getattr(widget, "field_label", None) or name + rect = (widget.rect.x0, widget.rect.y0, widget.rect.x1, widget.rect.y1) + text_format = int(getattr(widget, "text_format", 0) or 0) + return FormField( + name=name, + page_index=page_index, + rect=rect, + field_type=field_type, + label=label, + readonly=bool(flags & FLAG_READONLY), + required=bool(flags & FLAG_REQUIRED), + multiline=bool(flags & FLAG_MULTILINE), + password=bool(flags & FLAG_PASSWORD), + comb=bool(flags & FLAG_COMB), + max_length=int(getattr(widget, "text_maxlen", 0) or 0), + hidden=int(getattr(widget, "field_display", 0) or 0) == 1, + editable_choice=bool(flags & FLAG_EDIT), + choices=list(getattr(widget, "choice_values", None) or []), + button_caption=getattr(widget, "button_caption", None), + on_state=_safe_on_state(widget), + radio_group_xref=int(getattr(widget, "rb_parent", None) or -1), + text_format=text_format, + value=_widget_value(widget), + widget_xref=widget.xref, + ) + + +def _from_radio_group(kids, page_index: int) -> FormField: + """Collapse the widgets of one radio group into a single FormField.""" + first = kids[0] + flags = first.field_flags + name = _clean_field_name(first, page_index) + choices = [] + option_rects = [] + selected = "" + for w in kids: + on = _safe_on_state(w) + caption = getattr(w, "button_caption", None) or on + if caption not in choices: + choices.append(caption) + option_rects.append((w.rect.x0, w.rect.y0, w.rect.x1, w.rect.y1)) + value = w.field_value + if value and str(value) != "Off": + selected = caption + rect = (first.rect.x0, first.rect.y0, first.rect.x1, first.rect.y1) + return FormField( + name=name, + page_index=page_index, + rect=rect, + field_type=FieldType.RADIO, + label=getattr(first, "field_label", None) or name, + readonly=bool(flags & FLAG_READONLY), + required=bool(flags & FLAG_REQUIRED), + choices=choices, + option_rects=option_rects, + radio_group_xref=int(getattr(first, "rb_parent", None) or -1), + value=selected, + widget_xref=first.xref, + ) + + +# --------------------------------------------------------------------------- +# Index building +# --------------------------------------------------------------------------- + + +def build_field_index(doc) -> list: + """Enumerate every AcroForm field in a document. + + Radio button groups are collapsed into a single ``FormField`` per group + (the widgets that share a ``/Parent``). + """ + fields: list = [] + radio_groups: dict = {} # rb_parent xref -> (page_index, [widgets]) + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + widgets = list(page.widgets()) + except Exception: + widgets = [] + for w in widgets: + if w.field_type == fitz.PDF_WIDGET_TYPE_RADIOBUTTON: + rbp = int(getattr(w, "rb_parent", None) or -1) + entry = radio_groups.setdefault(rbp, [page_index, []]) + entry[1].append(w) + else: + fields.append(_from_widget(w, page_index)) + for rbp, (page_index, kids) in radio_groups.items(): + fields.append(_from_radio_group(kids, page_index)) + fields.sort(key=lambda f: (f.page_index, f.rect[1], f.rect[0])) + return fields + + +def form_field_count(doc) -> int: + return len(build_field_index(doc)) + + +def has_form_fields(doc) -> bool: + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + if next(page.widgets(), None) is not None: + return True + except Exception: + continue + return False + + +def field_by_name(fields, name) -> Optional[FormField]: + for f in fields: + if f.name == name: + return f + return None + + +# --------------------------------------------------------------------------- +# Reading / writing values +# --------------------------------------------------------------------------- + + +def _widget_for_field(doc, field: FormField): + """Return ``(page, widget)`` backing a (non-radio-group) FormField. + + The page is returned too so the caller keeps a strong reference — a Widget's + annotation is bound to its page via a weakref, and PyMuPDF raises "Annot is + not bound to a page" if the page is garbage-collected before ``update()``. + """ + try: + page = doc.load_page(field.page_index) + except Exception: + return None, None + try: + for w in page.widgets(): + if w.xref == field.widget_xref: + return page, w + except Exception: + pass + return None, None + + +def _iter_radio_kids(doc, group_xref: int): + """Yield ``(page, widget)`` for every radio in a group.""" + for page_index in range(doc.page_count): + try: + page = doc.load_page(page_index) + except Exception: + continue + try: + for w in page.widgets(): + if int(getattr(w, "rb_parent", None) or -1) == group_xref: + yield page, w + except Exception: + continue + + +def get_field_value(doc, field: FormField): + """Re-read the current value of a field straight from the PDF.""" + if field.field_type == FieldType.RADIO: + for _page, w in _iter_radio_kids(doc, field.radio_group_xref): + value = w.field_value + if value and str(value) != "Off": + on = _safe_on_state(w) + return getattr(w, "button_caption", None) or on + return "" + _page, widget = _widget_for_field(doc, field) + if widget is None: + return field.value + return _widget_value(widget) + + +def _as_bool(value) -> bool: + """Coerce bool-ish values (agents may pass "true"/"false" strings).""" + if isinstance(value, bool): + return value + if isinstance(value, str): + return value.strip().lower() not in ("", "0", "false", "off", "no") + return bool(value) + + +def set_field_value(doc, field: FormField, value) -> bool: + """Write ``value`` into the PDF for ``field``. + + Respects read-only rules and max lengths. Returns ``True`` on success. + The value is stored via PyMuPDF's ``update()``, which regenerates the + appearance stream so the value renders in any PDF viewer. + """ + if not field.is_editable(): + return False + if field.field_type == FieldType.RADIO: + return _set_radio_value(doc, field, value) + if field.field_type == FieldType.CHECKBOX: + return _set_checkbox_value(doc, field, _as_bool(value)) + if field.field_type in (FieldType.COMBO, FieldType.LISTBOX): + return _set_choice_value(doc, field, value) + return _set_text_value(doc, field, value) + + +def _set_text_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + text = str(value) if value is not None else "" + maxlen = int(getattr(widget, "text_maxlen", 0) or 0) + if maxlen > 0: + text = text[:maxlen] + try: + widget.field_value = text + widget.update() + except Exception: + return False + return True + + +def _set_checkbox_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + on = _safe_on_state(widget) + try: + widget.field_value = on if value else "Off" + widget.update() + except Exception: + return False + return True + + +def _set_choice_value(doc, field: FormField, value) -> bool: + _page, widget = _widget_for_field(doc, field) + if widget is None: + return False + text = str(value) if value is not None else "" + choices = list(getattr(widget, "choice_values", None) or []) + if text not in choices and not field.editable_choice: + return False + try: + widget.field_value = text + widget.update() + except Exception: + return False + return True + + +def _set_radio_value(doc, field: FormField, value) -> bool: + kids = list(_iter_radio_kids(doc, field.radio_group_xref)) + if not kids: + return False + text = str(value) if value is not None else "" + target = None + for _page, w in kids: + caption = getattr(w, "button_caption", None) or _safe_on_state(w) + if caption == text: + target = w + break + # Turn every option off first — setting a radio to "" resets the group. + for _page, w in kids: + try: + w.field_value = "" + w.update() + except Exception: + continue + if target is not None: + try: + target.field_value = _safe_on_state(target) + target.update() + except Exception: + return False + return True + + +# --------------------------------------------------------------------------- +# v1.3.1 — Field type intelligence +# --------------------------------------------------------------------------- + + +class FormTypeDetector: + """Detect field types from formatting rules, names and nearby labels. + + Two tiers are always kept distinct: + * ``explicit_type`` — authoritative, from the PDF's own formatting rule. + * ``inferred_type`` — heuristic, from the field name / nearby label. + Inference is advisory; callers must never present it as certainty. + """ + + # (regex, detected type, confidence) + NAME_PATTERNS = [ + (re.compile(r"(?i)(^|[_\- .])(date|dob|birth|born|birthday)([_\- .]|$)"), TYPE_DATE, 0.9), + (re.compile(r"(?i)(^|[_\- .])(ph|phone|tel|telephone|mobile|cell|fax)([_\- .]|$)"), TYPE_PHONE, 0.9), + (re.compile(r"(?i)(^|[_\- .])(zip|postal|postcode|pincode)([_\- .]|$)"), TYPE_ZIP, 0.9), + (re.compile(r"(?i)(^|[_\- .])(email|e-?mail)([_\- .]|$)"), TYPE_EMAIL, 0.95), + (re.compile(r"(?i)(^|[_\- .])(amount|price|cost|fee|salary|total|balance|currency|payment)([_\- .]|$)"), TYPE_CURRENCY, 0.85), + (re.compile(r"(?i)(^|[_\- .])(qty|quantity|count|number|num|age|year|weight|height)([_\- .]|$)"), TYPE_NUMERIC, 0.7), + ] + + # Simple label fragment heuristics (word-ish matches), lower confidence. + LABEL_PATTERNS = [ + (re.compile(r"(?i)\bdate\b|\bdob\b|\bbirth\b|\bborn\b"), TYPE_DATE, 0.6), + (re.compile(r"(?i)\bphone\b|\btelephone\b|\bmobile\b|\bcell\b"), TYPE_PHONE, 0.6), + (re.compile(r"(?i)\bzip\b|\bpostal\b|\bpostcode\b|\bpin\b"), TYPE_ZIP, 0.6), + (re.compile(r"(?i)\bemail\b|\be-?mail\b"), TYPE_EMAIL, 0.7), + (re.compile(r"(?i)\b(amount|price|cost|fee|salary|total|balance)\b|\$"), TYPE_CURRENCY, 0.6), + (re.compile(r"(?i)\b(quantity|qty|count|age|year)\b"), TYPE_NUMERIC, 0.55), + ] + + def detect(self, field: FormField, label_text: str = "") -> None: + """Populate the explicit / inferred / detected type fields in place.""" + explicit = None + if field.field_type in (FieldType.TEXT, FieldType.MULTILINE): + explicit = _EXPLICIT_BY_TEXT_FORMAT.get(field.text_format) + inferred = None + confidence = 0.0 + # Normalize camelCase ("postalCode" -> "postal_Code") so word-boundary + # patterns match common form naming conventions. + normalized_name = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", field.name or "") + for regex, ftype, conf in self.NAME_PATTERNS: + if regex.search(normalized_name): + inferred, confidence = ftype, conf + break + if inferred is None and label_text: + for regex, ftype, conf in self.LABEL_PATTERNS: + if regex.search(label_text): + inferred, confidence = ftype, conf + break + detected = explicit or inferred + field.explicit_type = explicit + field.inferred_type = inferred + field.detected_type = detected + field.type_confidence = confidence if detected == inferred else 1.0 + field.is_inferred = bool(inferred) and not explicit + + +def annotate_field_types(fields, doc) -> None: + """Run the type detector over every field, pulling nearby labels from the PDF.""" + detector = FormTypeDetector() + for f in fields: + label_text = _nearby_label_text(doc, f) if f.field_type in (FieldType.TEXT, FieldType.MULTILINE) else "" + detector.detect(f, label_text) + + +def _nearby_label_text(doc, field: FormField) -> str: + """Best-effort label text to the left / above a text field.""" + try: + page = doc.load_page(field.page_index) + words = page.get_text("words") + except Exception: + return "" + rx0, ry0, rx1, ry1 = field.rect + collected = [] + for word in words: + wx0, wy0, wx1, wy1, text, *_ = word + # Left of the field on the same line band, or directly above it. + left_of = wx1 <= rx0 + 2 and wy0 < ry1 and wy1 > ry0 - 6 and rx0 - wx1 < 220 + above = wy1 <= ry0 + 2 and wy1 >= ry0 - 40 and wx0 < rx1 and wx1 > rx0 - 60 + if left_of or above: + collected.append(text) + return " ".join(collected) + + +# --------------------------------------------------------------------------- +# v1.3.1 — Validation +# --------------------------------------------------------------------------- + + +class FormValidator: + """Advisory, international-tolerant validation for detected field types. + + Validation never blocks input — it only produces a message the UI can + surface. Values that do not match still save. + """ + + _EMAIL = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") + + @classmethod + def validate(cls, field: FormField, value) -> tuple: + """Return ``(ok: bool, message: str)`` for ``value`` on ``field``.""" + text = str(value or "").strip() + if not text or not field.detected_type: + return True, "" + rule = { + TYPE_DATE: cls._validate_date, + TYPE_TIME: cls._validate_time, + TYPE_PHONE: cls._validate_phone, + TYPE_ZIP: cls._validate_zip, + TYPE_EMAIL: cls._validate_email, + TYPE_CURRENCY: cls._validate_currency, + TYPE_NUMERIC: cls._validate_numeric, + }.get(field.detected_type) + if rule is None: + return True, "" + return rule(text) + + # -- individual rules ------------------------------------------------ + + @staticmethod + def _validate_date(text: str) -> tuple: + # Tolerates ISO, slash, dash, dotted and month-name dates. + tokens = re.split(r"[-/., ]+", text.strip()) + if len(tokens) < 3: + return False, "Expected a date like 2026-08-03." + if not all(tok.isdigit() or tok[:1].isalpha() for tok in tokens): + return False, "Expected a date like 2026-08-03." + year = None + for tok in tokens: + if len(tok) == 4 and tok.isdigit(): + year = int(tok) + break + months = { + "jan": 1, "feb": 2, "mar": 3, "apr": 4, "may": 5, "jun": 6, + "jul": 7, "aug": 8, "sep": 9, "oct": 10, "nov": 11, "dec": 12, + } + month_ok = any(tok.lower()[:3] in months for tok in tokens) + day_ok = any(tok.isdigit() and 1 <= int(tok) <= 31 for tok in tokens) + if year is not None and (month_ok or day_ok): + return True, "" + if month_ok and day_ok: + return True, "" + return False, "Expected a date like 2026-08-03." + + @staticmethod + def _validate_time(text: str) -> tuple: + if re.match(r"^\d{1,2}:\d{2}(:\d{2})?(\s*[AaPp][Mm])?$", text.strip()): + return True, "" + return False, "Expected a time like 14:30." + + @staticmethod + def _validate_phone(text: str) -> tuple: + digits = re.sub(r"[^\d]", "", text) + if text.lstrip().startswith("+"): + digits = digits.lstrip() or "" + cleaned = re.sub(r"[\s\-()./]", "", text) + if cleaned.startswith("+"): + cleaned = cleaned[1:] + if cleaned.isdigit() and 6 <= len(cleaned) <= 15: + return True, "" + return False, "Expected a phone number like +1 555 123 4567." + + @staticmethod + def _validate_zip(text: str) -> tuple: + cleaned = re.sub(r"[\s\-]", "", text) + # International postal codes are alphanumeric and 3–10 characters. + if cleaned.isalnum() and 3 <= len(cleaned) <= 10: + return True, "" + return False, "Expected a postal code (letters and digits)." + + @staticmethod + def _validate_email(text: str) -> tuple: + if FormValidator._EMAIL.match(text.strip()): + return True, "" + return False, "Expected an email address like name@example.com." + + @staticmethod + def _validate_currency(text: str) -> tuple: + cleaned = text.strip().replace(",", "") + cleaned = re.sub(r"^[$£€₹¥]|[$£€₹¥]$", "", cleaned) + if re.match(r"^\d+(\.\d{1,2})?$", cleaned) and cleaned.replace(".", "").isdigit(): + return True, "" + return False, "Expected an amount like 1,234.56." + + @staticmethod + def _validate_numeric(text: str) -> tuple: + cleaned = text.strip().replace(",", "") + if re.match(r"^[+-]?\d+(\.\d+)?$", cleaned): + return True, "" + return False, "Expected a number." + + +# --------------------------------------------------------------------------- +# v1.3.2 — Form state store (autosave / crash recovery / overrides) +# --------------------------------------------------------------------------- + + +class FormStateStore: + """Persist unsaved form values and user type overrides to local JSON. + + Keyed by document path hash so form work survives app restarts. The GUI + owns the file location; this class is deliberately dumb and Qt-free. + """ + + STATE_VERSION = 1 + FILE_PREFIX = "formstate_" + + def __init__(self, base_dir=None): + self.base_dir = Path(base_dir) if base_dir else None + + # -- key / path helpers ---------------------------------------------- + + def _dir(self) -> Path: + return self.base_dir + + @staticmethod + def key_for_path(path) -> str: + return hashlib.sha256(str(path).encode("utf-8")).hexdigest() + + def _file_for(self, path) -> Path: + return self._dir() / f"{self.FILE_PREFIX}{self.key_for_path(path)}.json" + + # -- read / write ---------------------------------------------------- + + def load(self, path) -> dict: + try: + data = json.loads(self._file_for(path).read_text(encoding="utf-8")) + if isinstance(data, dict) and data.get("version") == self.STATE_VERSION: + return data + except Exception: + pass + return {} + + def save(self, path, values: dict, overrides: Optional[dict] = None) -> None: + data = { + "version": self.STATE_VERSION, + "values": values or {}, + "overrides": overrides or {}, + } + try: + self._dir().mkdir(parents=True, exist_ok=True) + tmp = self._file_for(path).with_suffix(".tmp") + tmp.write_text(json.dumps(data, indent=2), encoding="utf-8") + tmp.replace(self._file_for(path)) + except Exception: + pass # best-effort autosave must never crash the app + + def clear(self, path) -> None: + try: + self._file_for(path).unlink(missing_ok=True) + except Exception: + pass + + def has_state(self, path) -> bool: + try: + return self._file_for(path).exists() + except Exception: + return False diff --git a/pdfreader_lib/mcp_server.py b/pdfreader_lib/mcp_server.py index 8166444..fbd07e1 100644 --- a/pdfreader_lib/mcp_server.py +++ b/pdfreader_lib/mcp_server.py @@ -45,6 +45,7 @@ IndexProgress, ) from .comparison import compare_pdfs as _lib_compare_pdfs, generate_diff_summary +from . import form_fields as _ff # --------------------------------------------------------------------------- @@ -383,6 +384,126 @@ def _search_single_pdf( HAVE_MCP = False +def _form_fields(path_str: str) -> list[dict]: + """Enumerate AcroForm fields with type intelligence, as dicts.""" + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + return [f.to_dict() for f in fields] + finally: + doc.close() + + +def _find_form_field(fields: list, field_ref: str) -> Any: + for f in fields: + if f.name == field_ref or f.label == field_ref: + return f + return None + + +def _save_form_doc(doc, src_path: Path, output_path: str | None) -> str: + """Incremental save to the original, or a full save to ``output_path``.""" + if output_path: + out = str(Path(output_path).expanduser().resolve()) + doc.save(out, garbage=1, deflate=True) + return out + try: + doc.save(str(src_path), incremental=True, encryption=0) + except Exception: + doc.save(str(src_path), garbage=1, deflate=True) + return str(src_path) + + +def _form_get_field(path_str: str, field_ref: str) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + return field.to_dict() + finally: + doc.close() + + +def _form_set_value(path_str: str, field_ref: str, value, output_path: str | None = None) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + if not field.is_editable(): + raise ValueError(f"Field '{field_ref}' is read-only or not editable.") + if not _ff.set_field_value(doc, field, value): + raise ValueError(f"Could not write value to field '{field_ref}'.") + saved = _save_form_doc(doc, p, output_path) + return { + "field": field.name, + "value": _ff.get_field_value(doc, field), + "saved_to": saved, + } + finally: + doc.close() + + +def _form_fill(path_str: str, values: dict, output_path: str | None = None) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + by_name = {f.name: f for f in fields} + results = [] + for ref, value in (values or {}).items(): + field = by_name.get(ref) + if field is None: + results.append({"field": ref, "ok": False, "error": "field not found"}) + continue + if not field.is_editable(): + results.append({"field": ref, "ok": False, "error": "read-only or unsupported"}) + continue + ok = _ff.set_field_value(doc, field, value) + results.append( + { + "field": ref, + "ok": ok, + "value": _ff.get_field_value(doc, field) if ok else None, + "error": None if ok else "write failed", + } + ) + saved = _save_form_doc(doc, p, output_path) if any(r["ok"] for r in results) else None + return {"results": results, "saved_to": saved} + finally: + doc.close() + + +def _form_validate(path_str: str, field_ref: str, value) -> dict: + p = _validate_pdf(path_str) + doc = fitz.open(str(p)) + try: + fields = _ff.build_field_index(doc) + _ff.annotate_field_types(fields, doc) + field = _find_form_field(fields, field_ref) + if field is None: + raise ValueError(f"Field not found: {field_ref}") + ok, message = _ff.FormValidator.validate(field, value) + return { + "field": field.name, + "detected_type": field.detected_type, + "ok": ok, + "message": message, + } + finally: + doc.close() + + def _make_tool( name: str, description: str, @@ -581,6 +702,94 @@ def _err_validation(detail: str) -> list[TextContent]: "List all PDF documents currently in the library search index with metadata including file name, path, page count, and character count. Run this to see what documents are available for searching before using search_library or search_semantic. Returns an empty list if index_folder has not been run yet.", {}, ), + _make_tool( + "form_list_fields", + "List all AcroForm fields in a PDF with their metadata — name, page, type, required/readonly flags, max length, choices, current value, and any detected field type (date, phone, ZIP, email, currency, numeric). Use this to discover what a PDF form contains before filling it.", + { + "path": { + "type": "string", + "description": "Absolute or relative path to the PDF file on the local filesystem", + } + }, + required=["path"], + ), + _make_tool( + "form_get_field", + "Get full details about a single AcroForm field by name, including formatting rule, detected type, choices, and current value. Use this to inspect a specific field before setting its value.", + { + "path": { + "type": "string", + "description": "Absolute or relative path to the PDF file on the local filesystem", + }, + "field": { + "type": "string", + "description": "The field name (or label) to inspect", + }, + }, + required=["path", "field"], + ), + _make_tool( + "form_set_value", + "Set the value of a single AcroForm field and save the PDF. Saves incrementally to the original file by default, or to an output_path if provided. Respects read-only fields and max lengths. Checkboxes accept true/false, radios accept the option label, combo/listbox fields accept one of their choices. Returns the saved value and destination path.", + { + "path": { + "type": "string", + "description": "Absolute or relative path to the PDF file on the local filesystem", + }, + "field": { + "type": "string", + "description": "The field name (or label) to set", + }, + "value": { + "type": "string", + "description": "The value to write (checkbox: true/false, radio: option label, choice: one of the field's choices, text: the string)", + }, + "output_path": { + "type": "string", + "description": "Optional path to save a copy to instead of the original file", + }, + }, + required=["path", "field", "value"], + ), + _make_tool( + "form_fill", + "Fill multiple AcroForm fields at once from a mapping of field name to value, then save once. Returns a per-field success/failure report (missing fields and read-only fields are reported, not fatal). Saves incrementally to the original by default, or to output_path. Use this to complete an entire form in one call.", + { + "path": { + "type": "string", + "description": "Absolute or relative path to the PDF file on the local filesystem", + }, + "values": { + "type": "object", + "additionalProperties": {"type": "string"}, + "description": "Mapping of field name to value to write", + }, + "output_path": { + "type": "string", + "description": "Optional path to save a copy to instead of the original file", + }, + }, + required=["path", "values"], + ), + _make_tool( + "form_validate", + "Validate a value against a field's detected type (date, phone, ZIP, email, currency, numeric) without saving. Advisory only — returns ok/message and never blocks input. Use this to check a value before committing it to a form.", + { + "path": { + "type": "string", + "description": "Absolute or relative path to the PDF file on the local filesystem", + }, + "field": { + "type": "string", + "description": "The field name (or label) whose value should be validated", + }, + "value": { + "type": "string", + "description": "The value to validate against the field's detected type", + }, + }, + required=["path", "field", "value"], + ), ] @@ -745,6 +954,35 @@ async def _handle_call( ) ) + case "form_list_fields": + fields = _form_fields(args["path"]) + return _ok(json.dumps(fields, indent=2)) + + case "form_get_field": + field = _form_get_field(args["path"], args["field"]) + return _ok(json.dumps(field, indent=2)) + + case "form_set_value": + result = _form_set_value( + args["path"], + args["field"], + args["value"], + args.get("output_path"), + ) + return _ok(json.dumps(result, indent=2)) + + case "form_fill": + result = _form_fill( + args["path"], + args["values"], + args.get("output_path"), + ) + return _ok(json.dumps(result, indent=2)) + + case "form_validate": + result = _form_validate(args["path"], args["field"], args["value"]) + return _ok(json.dumps(result, indent=2)) + case _: return _err(f"Unknown tool: {name}") diff --git a/tests/_form_fixtures.py b/tests/_form_fixtures.py new file mode 100644 index 0000000..e0731c1 --- /dev/null +++ b/tests/_form_fixtures.py @@ -0,0 +1,124 @@ +"""Shared AcroForm fixture builders for the form-intelligence tests.""" + +from __future__ import annotations + +import fitz + +# Widget flag bits (mirror pdfreader_lib.form_fields). +FLAG_READONLY = 0x1 +FLAG_REQUIRED = 0x2 +FLAG_MULTILINE = 0x1000 +FLAG_PASSWORD = 0x2000 +FLAG_COMB = 0x100000 + + +def _make_stream(doc, data: bytes = b"") -> int: + xref = doc.get_new_xref() + doc.update_object( + xref, "<< /Type /XObject /Subtype /Form /BBox [0 0 20 20] /Length 0 >>" + ) + doc.update_stream(xref, data) + return xref + + +def add_radio_group(doc, page, field_name, options, rects, selected=None) -> int: + """Build a real radio group (/Parent + /Kids) via raw xref objects.""" + kids = [] + for caption, rect in zip(options, rects): + on = "".join(ch for ch in str(caption) if ch.isalnum()) or "Yes" + kid = doc.get_new_xref() + doc.update_object(kid, "<< >>") + for key, value in { + "Type": "/Annot", + "Subtype": "/Widget", + "FT": "/Btn", + "Ff": "32768", + "F": "4", + "Rect": f"[{rect.x0} {rect.y0} {rect.x1} {rect.y1}]", + "AS": "/" + (on if caption == selected else "Off"), + "MK": f"<< /CA ({caption}) >>", + }.items(): + doc.xref_set_key(kid, key, value) + off_x, on_x = _make_stream(doc), _make_stream(doc) + doc.xref_set_key(kid, "AP", f"<>>>") + kids.append(kid) + parent = doc.get_new_xref() + doc.update_object(parent, "<< >>") + doc.xref_set_key(parent, "FT", "/Btn") + doc.xref_set_key(parent, "Ff", "32768") + doc.xref_set_key(parent, "T", f"({field_name})") + doc.xref_set_key(parent, "Kids", "[" + " ".join(f"{k} 0 R" for k in kids) + "]") + sel_on = "".join(ch for ch in str(selected) if ch.isalnum()) if selected else None + doc.xref_set_key(parent, "V", "/" + (sel_on or "Off")) + for kid in kids: + doc.xref_set_key(kid, "Parent", f"{parent} 0 R") + annots = doc.xref_get_key(page.xref, "Annots")[1] + kids_str = " ".join(f"{k} 0 R" for k in kids) + if annots == "null": + doc.xref_set_key(page.xref, "Annots", f"[{kids_str}]") + else: + inner = annots.strip()[1:-1].strip() + doc.xref_set_key(page.xref, "Annots", f"[{inner} {kids_str}]") + return parent + + +def _add_text(page, name, rect, *, flags=0, max_len=0, label=None): + widget = fitz.Widget() + widget.field_type = fitz.PDF_WIDGET_TYPE_TEXT + widget.field_name = name + widget.rect = fitz.Rect(rect) + widget.field_flags = flags + if max_len: + widget.text_maxlen = max_len + if label: + widget.field_label = label + page.add_widget(widget) + + +def make_form_fixture(path) -> str: + """Build a PDF exercising every field type and rule. Returns the path.""" + doc = fitz.open() + page = doc.new_page() + + _add_text(page, "fullname", (100, 100, 300, 125), max_len=40) + _add_text(page, "comments", (100, 140, 300, 200), flags=FLAG_MULTILINE) + _add_text(page, "ref", (100, 300, 300, 325), flags=FLAG_READONLY) + _add_text(page, "phone", (100, 340, 300, 365), flags=FLAG_REQUIRED, label="Phone number") + _add_text(page, "pin", (100, 380, 300, 405), flags=FLAG_PASSWORD) + _add_text(page, "code", (100, 420, 300, 445), flags=FLAG_COMB, max_len=6) + # "dob" with a nearby label to the left -> label-based inference. + _add_text(page, "dob", (220, 460, 420, 485)) + page.insert_text((40, 478), "Date of Birth:", fontsize=11) + + checkbox = fitz.Widget() + checkbox.field_type = fitz.PDF_WIDGET_TYPE_CHECKBOX + checkbox.field_name = "agree" + checkbox.rect = fitz.Rect(100, 220, 120, 240) + page.add_widget(checkbox) + + combo = fitz.Widget() + combo.field_type = fitz.PDF_WIDGET_TYPE_COMBOBOX + combo.field_name = "country" + combo.rect = fitz.Rect(100, 260, 300, 285) + combo.choice_values = ["US", "CA", "UK"] + page.add_widget(combo) + + listbox = fitz.Widget() + listbox.field_type = fitz.PDF_WIDGET_TYPE_LISTBOX + listbox.field_name = "tags" + listbox.rect = fitz.Rect(100, 620, 300, 680) + listbox.choice_values = ["a", "b", "c"] + page.add_widget(listbox) + + add_radio_group( + doc, + page, + "gender", + ["M", "F"], + [fitz.Rect(100, 500, 120, 520), fitz.Rect(100, 530, 120, 550)], + selected="F", + ) + + doc.save(path, garbage=4, deflate=True) + doc.close() + return path diff --git a/tests/test_form_fields.py b/tests/test_form_fields.py new file mode 100644 index 0000000..4b1a61a --- /dev/null +++ b/tests/test_form_fields.py @@ -0,0 +1,305 @@ +"""Tests for pdfreader_lib.form_fields (Phase 2 — PDF Form Intelligence). + +Covers the shared form module used by both the GUI and the MCP server: +field enumeration/normalization, radio grouping, value read/write round-trips, +incremental-save persistence, type detection (explicit vs inferred), advisory +validation, and the local form-state store. +""" + +from __future__ import annotations + +import shutil +from pathlib import Path + +import fitz +import pytest + +from pdfreader_lib import form_fields as ff + +from tests._form_fixtures import make_form_fixture + +# Ensure fixtures land in a temp dir (tests should not write to the repo). +FIXTURE_PATH = Path(__file__).parent / "fixtures" / "form_test.pdf" + + +@pytest.fixture(scope="module") +def form_doc(): + FIXTURE_PATH.parent.mkdir(parents=True, exist_ok=True) + make_form_fixture(str(FIXTURE_PATH)) + doc = fitz.open(str(FIXTURE_PATH)) + yield doc + doc.close() + FIXTURE_PATH.unlink(missing_ok=True) + + +# --------------------------------------------------------------------------- +# v1.3.0 — enumeration & normalization +# --------------------------------------------------------------------------- + + +def test_build_index_types(form_doc): + fields = ff.build_field_index(form_doc) + by_name = {f.name: f for f in fields} + assert by_name["fullname"].field_type == ff.FieldType.TEXT + assert by_name["comments"].field_type == ff.FieldType.MULTILINE + assert by_name["agree"].field_type == ff.FieldType.CHECKBOX + assert by_name["gender"].field_type == ff.FieldType.RADIO + assert by_name["country"].field_type == ff.FieldType.COMBO + assert by_name["tags"].field_type == ff.FieldType.LISTBOX + + +def test_flags_are_mapped(form_doc): + by_name = {f.name: f for f in ff.build_field_index(form_doc)} + assert by_name["ref"].readonly is True + assert by_name["phone"].required is True + assert by_name["comments"].multiline is True + assert by_name["pin"].password is True + assert by_name["fullname"].max_length == 40 + assert by_name["country"].choices == ["US", "CA", "UK"] + + +def test_radio_group_is_collapsed(form_doc): + fields = ff.build_field_index(form_doc) + radios = [f for f in fields if f.field_type == ff.FieldType.RADIO] + assert len(radios) == 1 + radio = radios[0] + assert radio.name == "gender" + assert radio.choices == ["M", "F"] + assert radio.value == "F" + + +def test_has_form_fields(form_doc): + assert ff.has_form_fields(form_doc) is True + empty = fitz.open() + empty.new_page() + assert ff.has_form_fields(empty) is False + empty.close() + + +def test_readonly_field_not_editable(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "ref") + assert field.readonly + assert field.is_editable() is False + + +# --------------------------------------------------------------------------- +# v1.3.0 — value read / write round-trips +# --------------------------------------------------------------------------- + + +def test_set_get_roundtrip(form_doc): + fields = ff.build_field_index(form_doc) + cases = { + "fullname": "Alice Smith", + "comments": "Multi\nline\ntext", + "agree": True, + "country": "UK", + "tags": "c", + "gender": "M", + } + for name, value in cases.items(): + field = ff.field_by_name(fields, name) + assert ff.set_field_value(form_doc, field, value) is True + assert ff.get_field_value(form_doc, field) == value + + +def test_checkbox_toggle_off(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "agree") + assert ff.set_field_value(form_doc, field, False) is True + assert ff.get_field_value(form_doc, field) is False + + +def test_radio_clear(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "gender") + assert ff.set_field_value(form_doc, field, "M") is True + assert ff.set_field_value(form_doc, field, "") is True + assert ff.get_field_value(form_doc, field) == "" + + +def test_readonly_write_refused(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "ref") + assert ff.set_field_value(form_doc, field, "HACK") is False + assert ff.get_field_value(form_doc, field) == "" + + +def test_max_length_truncated(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "fullname") + assert ff.set_field_value(form_doc, field, "x" * 100) is True + assert len(ff.get_field_value(form_doc, field)) == 40 + + +def test_invalid_choice_refused(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "country") + assert ff.set_field_value(form_doc, field, "NotAChoice") is False + + +def test_incremental_save_persists_values(tmp_path): + src = tmp_path / "form_inc.pdf" + make_form_fixture(str(src)) + doc = fitz.open(str(src)) + fields = ff.build_field_index(doc) + for name, value in { + "fullname": "Alice Smith", + "agree": True, + "gender": "M", + "country": "CA", + }.items(): + assert ff.set_field_value(doc, ff.field_by_name(fields, name), value) is True + doc.save(str(src), incremental=True, encryption=0) + doc.close() + + # Reopen — values must be present and re-readable. + doc = fitz.open(str(src)) + fields = ff.build_field_index(doc) + assert ff.get_field_value(doc, ff.field_by_name(fields, "fullname")) == "Alice Smith" + assert ff.get_field_value(doc, ff.field_by_name(fields, "agree")) is True + assert ff.get_field_value(doc, ff.field_by_name(fields, "gender")) == "M" + assert ff.get_field_value(doc, ff.field_by_name(fields, "country")) == "CA" + doc.close() + + +# --------------------------------------------------------------------------- +# v1.3.1 — type detection (explicit vs inferred) +# --------------------------------------------------------------------------- + + +def _field(**kwargs) -> ff.FormField: + return ff.FormField(name=kwargs.pop("name", "field"), page_index=0, **kwargs) + + +def test_explicit_type_from_format(): + field = _field(name="some_value", text_format=fitz.PDF_WIDGET_TX_FORMAT_DATE) + ff.FormTypeDetector().detect(field) + assert field.explicit_type == ff.TYPE_DATE + assert field.detected_type == ff.TYPE_DATE + assert field.is_inferred is False + + +def test_explicit_type_wins_over_inference(): + field = _field(name="dob", text_format=fitz.PDF_WIDGET_TX_FORMAT_NUMBER) + ff.FormTypeDetector().detect(field) + assert field.detected_type == ff.TYPE_NUMERIC + assert field.explicit_type == ff.TYPE_NUMERIC + assert field.is_inferred is False + + +def test_inferred_from_name(): + cases = { + "dob": ff.TYPE_DATE, + "home_phone": ff.TYPE_PHONE, + "postalCode": ff.TYPE_ZIP, + "email_address": ff.TYPE_EMAIL, + "total_amount": ff.TYPE_CURRENCY, + "quantity": ff.TYPE_NUMERIC, + } + for name, expected in cases.items(): + field = _field(name=name) + ff.FormTypeDetector().detect(field) + assert field.inferred_type == expected, name + assert field.detected_type == expected + assert field.is_inferred is True + + +def test_inferred_from_label_text(): + field = _field(name="field_7") + ff.FormTypeDetector().detect(field, label_text="Date of Birth:") + assert field.inferred_type == ff.TYPE_DATE + assert field.is_inferred is True + + +def test_no_detection_for_plain_field(): + field = _field(name="notes") + ff.FormTypeDetector().detect(field, label_text="") + assert field.detected_type is None + assert field.is_inferred is False + + +def test_annotate_field_types_uses_nearby_labels(form_doc): + fields = ff.build_field_index(form_doc) + ff.annotate_field_types(fields, form_doc) + by_name = {f.name: f for f in fields} + assert by_name["dob"].detected_type == ff.TYPE_DATE + + +# --------------------------------------------------------------------------- +# v1.3.1 — validation (advisory, international-tolerant) +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "ftype,value,expected_ok", + [ + (ff.TYPE_DATE, "2026-08-03", True), + (ff.TYPE_DATE, "03/08/2026", True), + (ff.TYPE_DATE, "3 Aug 2026", True), + (ff.TYPE_DATE, "not-a-date", False), + (ff.TYPE_TIME, "14:30", True), + (ff.TYPE_TIME, "2:30 PM", True), + (ff.TYPE_TIME, "late afternoon", False), + (ff.TYPE_PHONE, "+1 555 123 4567", True), + (ff.TYPE_PHONE, "020 7946 0958", True), + (ff.TYPE_PHONE, "(212) 555-0199", True), + (ff.TYPE_PHONE, "123", False), + (ff.TYPE_ZIP, "90210", True), + (ff.TYPE_ZIP, "SW1A 1AA", True), + (ff.TYPE_ZIP, "12", False), + (ff.TYPE_EMAIL, "name@example.com", True), + (ff.TYPE_EMAIL, "not-an-email", False), + (ff.TYPE_CURRENCY, "$1,234.56", True), + (ff.TYPE_CURRENCY, "€99", True), + (ff.TYPE_CURRENCY, "free", False), + (ff.TYPE_NUMERIC, "-12.5", True), + (ff.TYPE_NUMERIC, "3,000", True), + (ff.TYPE_NUMERIC, "twelve", False), + (None, "anything", True), # no detected type -> always ok + ], +) +def test_validator_rules(ftype, value, expected_ok): + ok, message = ff.FormValidator.validate(_field(detected_type=ftype), value) + assert ok is expected_ok, message + + +def test_validation_never_blocks_editing(form_doc): + field = ff.field_by_name(ff.build_field_index(form_doc), "dob") + assert field.is_editable() is True + # An inferred date field still accepts any text. + assert ff.set_field_value(form_doc, field, "ordinary text") is True + + +# --------------------------------------------------------------------------- +# v1.3.2 — form state store +# --------------------------------------------------------------------------- + + +def test_state_store_roundtrip(tmp_path): + store = ff.FormStateStore(tmp_path) + path = tmp_path / "doc.pdf" + store.save(path, {"fullname": "Alice", "agree": True}, {"dob": ff.TYPE_DATE}) + data = store.load(path) + assert data["values"] == {"fullname": "Alice", "agree": True} + assert data["overrides"] == {"dob": ff.TYPE_DATE} + assert store.has_state(path) is True + + +def test_state_store_isolation(tmp_path): + store = ff.FormStateStore(tmp_path) + a = tmp_path / "a.pdf" + b = tmp_path / "b.pdf" + store.save(a, {"x": "1"}) + store.save(b, {"y": "2"}) + assert store.load(a)["values"] == {"x": "1"} + assert store.load(b)["values"] == {"y": "2"} + store.clear(a) + assert store.has_state(a) is False + assert store.has_state(b) is True + + +def test_checkbox_string_boolean_coercion(form_doc): + """Agents may pass "true"/"false" strings — they must coerce correctly.""" + field = ff.field_by_name(ff.build_field_index(form_doc), "agree") + assert ff.set_field_value(form_doc, field, "true") is True + assert ff.get_field_value(form_doc, field) is True + assert ff.set_field_value(form_doc, field, "false") is True + assert ff.get_field_value(form_doc, field) is False + assert ff.set_field_value(form_doc, field, "off") is True + assert ff.get_field_value(form_doc, field) is False diff --git a/tests/test_form_gui.py b/tests/test_form_gui.py new file mode 100644 index 0000000..d0150a9 --- /dev/null +++ b/tests/test_form_gui.py @@ -0,0 +1,118 @@ +"""Offscreen GUI smoke tests for the AcroForm overlay feature (Phase 2). + +These exercise the FormController without a display: field-index building, +overlay widget creation, dirty tracking, and save→reopen persistence. They +skip cleanly when a Qt platform (e.g. offscreen) is unavailable. +""" + +from __future__ import annotations + +import os +import sys +from pathlib import Path + +import pytest + +from pdfreader_lib import form_fields as ff +from tests._form_fixtures import make_form_fixture + +os.environ.setdefault("QT_QPA_PLATFORM", "offscreen") +try: + from PySide6.QtWidgets import QApplication, QMessageBox +except Exception: # pragma: no cover - Qt not importable + QApplication = None # type: ignore + +pytestmark = pytest.mark.skipif(QApplication is None, reason="PySide6 not available") + +if QApplication is not None: + from main import PdfReaderWindow + + # Blocking dialogs never render during tests. Discard = let close proceed. + QMessageBox.question = staticmethod(lambda *a, **k: QMessageBox.Discard) + # Session restore shows a modal prompt 100 ms after window creation; the + # offscreen test driver cannot answer it, so neutralize it. + PdfReaderWindow._restore_session = lambda self, force=False: None + PdfReaderWindow._do_restore_session = lambda self: None + + +@pytest.fixture(scope="module") +def qapp(): + app = QApplication.instance() or QApplication([]) + app.setApplicationName("OpenReader-Test") + yield app + + +@pytest.fixture +def form_window(qapp, tmp_path): + from main import PdfReaderWindow + + path = tmp_path / "form.pdf" + make_form_fixture(str(path)) + win = PdfReaderWindow() + win.show() + win.open_pdf(str(path)) + win._do_render() # synchronous render (bypasses the debounce timer) + qapp.processEvents() + yield win, path + win.close() + qapp.processEvents() + + +def test_form_controller_built(form_window): + win, _path = form_window + controller = win._form_for_current() + assert controller is not None + assert len(controller.fields) >= 9 + assert len(controller.editable_fields) >= 9 + + +def test_overlay_widgets_attached(form_window): + win, _path = form_window + controller = win._form_for_current() + assert controller._widgets, "expected overlay widgets on the rendered page" + + +def test_editing_marks_dirty_and_persists(form_window, qapp): + win, path = form_window + controller = win._form_for_current() + + for name, value in {"fullname": "Alice Smith", "country": "UK", "gender": "M"}.items(): + field = next(f for f in controller.fields if f.name == name) + widget = controller._field_widgets.get(field.name)[0] + if field.field_type == ff.FieldType.RADIO: + controller._set_widget_value(field, value) + controller.on_radio(field, value) + elif field.field_type in (ff.FieldType.COMBO, ff.FieldType.LISTBOX): + controller._set_widget_value(field, value) + controller.on_edited(field) + else: + widget.setText(value) + widget.textEdited.emit(value) + assert controller.dirty is True + + win._save_document() + assert controller.dirty is False + + # The values must be written into the PDF on disk (appearance + value). + # Read the file back with the shared module (no second window needed). + import fitz + + doc = fitz.open(str(path)) + try: + fields = ff.build_field_index(doc) + for name, expected in {"fullname": "Alice Smith", "country": "UK", "gender": "M"}.items(): + field = next(f for f in fields if f.name == name) + assert ff.get_field_value(doc, field) == expected, name + finally: + doc.close() + + +def test_required_validation_message(form_window): + win, _path = form_window + controller = win._form_for_current() + dob = next(f for f in controller.fields if f.name == "dob") + widget = controller._field_widgets.get(dob.name)[0] + widget.setText("not-a-date") + controller.on_commit(dob, widget.text()) + assert dob.validation_message + assert "date" in dob.validation_message.lower() diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py index eb3d166..6a94275 100644 --- a/tests/test_mcp_server.py +++ b/tests/test_mcp_server.py @@ -2,7 +2,7 @@ Tests for the OpenReader MCP server. Covers input validation, output shape, and error handling -for all 14 tools, following the MCP Build Guide test patterns. +for all 19 tools, following the MCP Build Guide test patterns. """ from __future__ import annotations @@ -26,9 +26,16 @@ _split_every_page, _extract_pages, _parse_page_ranges, + _form_fields, + _form_get_field, + _form_set_value, + _form_fill, + _form_validate, TOOLS, ) +from tests._form_fixtures import make_form_fixture + # ═══════════════════════════════════════════════════════════════ # Helpers @@ -114,9 +121,11 @@ def test_tool_descriptions_are_sentences(self): "search_pdf", "compare_pdfs", "merge_pdfs", "split_pdf", "extract_pages", "compress_pdf", "index_folder", "search_library", "search_semantic", "list_indexed_docs", + "form_list_fields", "form_get_field", "form_set_value", + "form_fill", "form_validate", ]) def test_known_tools_exist(self, tool_name): - """All 14 expected tools are registered.""" + """All 19 expected tools are registered.""" names = [t.name for t in TOOLS] assert tool_name in names, f"Expected tool '{tool_name}' not found in TOOLS" @@ -299,3 +308,77 @@ def test_extract_pages_invalid_ranges(self, sample_pdf, output_dir): """Invalid page range raises error.""" with pytest.raises(ValueError, match="outside valid range"): _extract_pages(str(sample_pdf), "1-999", str(output_dir / "bad.pdf")) + + +# ═══════════════════════════════════════════════════════════════ +# Form tools (Phase 2 — PDF Form Intelligence) +# ═══════════════════════════════════════════════════════════════ + + +@pytest.fixture +def form_pdf(tmp_path) -> Path: + """A PDF exercising every AcroForm field type.""" + path = tmp_path / "form.pdf" + make_form_fixture(str(path)) + return path + + +class TestFormTools: + def test_form_list_fields(self, form_pdf): + fields = _form_fields(str(form_pdf)) + by_name = {f["name"]: f for f in fields} + assert len(fields) >= 9 + assert by_name["fullname"]["type"] == "text" + assert by_name["gender"]["type"] == "radio" + assert by_name["gender"]["choices"] == ["M", "F"] + assert by_name["ref"]["readonly"] is True + assert by_name["phone"]["required"] is True + + def test_form_get_field(self, form_pdf): + field = _form_get_field(str(form_pdf), "gender") + assert field["type"] == "radio" + assert field["value"] == "F" + + def test_form_get_field_not_found(self, form_pdf): + with pytest.raises(ValueError, match="not found"): + _form_get_field(str(form_pdf), "nope") + + def test_form_set_value_roundtrip(self, form_pdf): + result = _form_set_value(str(form_pdf), "fullname", "Alice Smith") + assert result["value"] == "Alice Smith" + assert result["saved_to"] == str(form_pdf) + + def test_form_set_value_to_output(self, form_pdf, tmp_path): + out = tmp_path / "copy.pdf" + result = _form_set_value(str(form_pdf), "country", "UK", str(out)) + assert result["value"] == "UK" + assert result["saved_to"] == str(out) + assert out.exists() + + def test_form_set_value_readonly_refused(self, form_pdf): + with pytest.raises(ValueError, match="read-only"): + _form_set_value(str(form_pdf), "ref", "HACK") + + def test_form_fill(self, form_pdf): + result = _form_fill(str(form_pdf), {"country": "CA", "agree": True, "gender": "M"}) + by_field = {r["field"]: r for r in result["results"]} + assert by_field["country"]["ok"] is True + assert by_field["agree"]["ok"] is True + assert by_field["gender"]["value"] == "M" + assert result["saved_to"] == str(form_pdf) + + def test_form_fill_missing_field_reported(self, form_pdf): + result = _form_fill(str(form_pdf), {"ghost": "x"}) + assert result["results"][0]["ok"] is False + assert result["results"][0]["error"] == "field not found" + + def test_form_validate(self, form_pdf): + bad = _form_validate(str(form_pdf), "dob", "not-a-date") + assert bad["detected_type"] == "date" + assert bad["ok"] is False + good = _form_validate(str(form_pdf), "dob", "2026-08-03") + assert good["ok"] is True + + def test_form_tool_invalid_path(self): + with pytest.raises(FileNotFoundError): + _form_fields("/does/not/exist.pdf") diff --git a/tests/test_reliability.py b/tests/test_reliability.py index 2f1b049..589641b 100644 --- a/tests/test_reliability.py +++ b/tests/test_reliability.py @@ -287,9 +287,9 @@ def test_tab_data_defaults_to_fit_on_open(self): assert tab.fit_to_window is True assert tab.zoom == 1.25 - def test_version_is_1_2_8(self): + def test_version_is_1_3_0(self): import main as m - assert m.__version__ == "1.2.8" + assert m.__version__ == "1.3.0" class TestZoomUi: From 31ed61afd12dc5056c9472b15d6feb6d2a41a41a Mon Sep 17 00:00:00 2001 From: Sparsh Sam <110058692+sparshsam@users.noreply.github.com> Date: Sun, 8 Nov 2026 20:13:17 -0500 Subject: [PATCH 2/4] feat(v1.3.0): freeform text, signatures, images and editing UI Complete the Fill, Edit & Sign release on top of the v1.2.8 reader. Editing model (Qt-free, pdfreader_lib/edit_objects.py): - text stored as native FreeText annotations carrying OpenReaderData metadata (re-editable after save/reopen, selectable in other viewers) - signatures/images stored as page-content image XObjects with the same metadata, unique per placement - atomic save, Save As, flattened export via Document.bake on a copy, signature detection, encrypted/read-only and rotated-page safety Editing UI (pdfreader_lib/edit_gui.py): - per-tab EditController with overlays on the persistent continuous page labels, so editing works without leaving continuous scrolling - inline multiline text editor, contextual formatting bar (font, size, color, bold/italic/underline, alignment, 90-degree rotation), drag, resize, duplicate, copy/paste, delete and snapshot undo/redo - signature dialog with draw, type (local fonts) and import methods - local-only signature library (pdfreader_lib/signature_store.py) Window integration: - Fill | Add Text | Sign | Image toolbar actions, stable contextual bar with a selection hint, dirty tab/window indicators and close prompts - editing survives zoom, scrolling, window resize and tab switches; clear error handling for closed documents and read-only files Tests: 16 model, 5 signature-store and 16 offscreen editing GUI tests (inline Ctrl+Enter commit, formatting, images/signatures, undo/redo, Save As, flatten, coordinate mapping, continuous mode, rotated pages, themes). Full suite: 261 passed, 18 skipped. Co-Authored-By: Claude Code --- main.py | 1130 +++++++++++++++++++++++-- pdfreader_lib/edit_gui.py | 1314 ++++++++++++++++++++++++++++++ pdfreader_lib/edit_objects.py | 640 +++++++++++++++ pdfreader_lib/signature_store.py | 154 ++++ tests/test_edit_gui.py | 399 +++++++++ tests/test_edit_objects.py | 367 +++++++++ tests/test_signature_store.py | 74 ++ 7 files changed, 4021 insertions(+), 57 deletions(-) create mode 100644 pdfreader_lib/edit_gui.py create mode 100644 pdfreader_lib/edit_objects.py create mode 100644 pdfreader_lib/signature_store.py create mode 100644 tests/test_edit_gui.py create mode 100644 tests/test_edit_objects.py create mode 100644 tests/test_signature_store.py diff --git a/main.py b/main.py index 5581a76..6a6fd65 100644 --- a/main.py +++ b/main.py @@ -11,8 +11,8 @@ from pathlib import Path import fitz -from PySide6.QtCore import QByteArray, QEvent, QObject, QPoint, QPointF, QRect, QRectF, QSettings, QSize, QStandardPaths, QTimer, Qt, QUrl, Signal -from PySide6.QtGui import QAction, QColor, QDesktopServices, QIcon, QImage, QKeySequence, QPainter, QPainterPath, QPalette, QPen, QPixmap, QShortcut +from PySide6.QtCore import QBuffer, QByteArray, QEvent, QObject, QPoint, QPointF, QRect, QRectF, QSettings, QSize, QStandardPaths, QTimer, Qt, QUrl, Signal +from PySide6.QtGui import QAction, QColor, QDesktopServices, QIcon, QImage, QKeySequence, QPainter, QPainterPath, QPalette, QPen, QPixmap, QPolygonF, QShortcut from PySide6.QtNetwork import QLocalServer, QLocalSocket, QNetworkAccessManager, QNetworkReply, QNetworkRequest from PySide6.QtWidgets import ( QAbstractSpinBox, @@ -20,6 +20,7 @@ QButtonGroup, QCalendarWidget, QCheckBox, + QColorDialog, QComboBox, QDialog, QDialogButtonBox, @@ -118,6 +119,9 @@ def _perf_end(start: float, label: str) -> None: # AcroForm field intelligence (Phase 2) — shared with the MCP server. from pdfreader_lib import form_fields as _ff +from pdfreader_lib import edit_gui as edit_ui +from pdfreader_lib import edit_objects as eo +from pdfreader_lib import signature_store as sig_store # --------------------------------------------------------------------------- @@ -140,6 +144,7 @@ class TabData: selected_rects: list = field(default_factory=list) ocr_text_pages: OrderedDict = field(default_factory=OrderedDict) ocr_warning_shown: bool = False + encrypted: bool = False # --------------------------------------------------------------------------- @@ -296,6 +301,41 @@ class TabData: QToolBar#MainToolbar QToolButton#SemanticToggle:disabled { color: #aaabb2; } +QToolBar#ContextToolbar { + background-color: #fbfbfc; + border: none; + border-bottom: 1px solid #e8e8ec; + padding: 4px 10px; + spacing: 4px; +} +QToolBar#ContextToolbar QToolButton#CtxButton { + background: transparent; + border: 1px solid transparent; + border-radius: 5px; + padding: 3px 8px; + color: #1b1b1f; + font-size: 12px; +} +QToolBar#ContextToolbar QToolButton#CtxButton:hover { + background-color: rgba(0, 0, 0, 0.05); +} +QToolBar#ContextToolbar QToolButton#CtxButton:checked { + background-color: rgba(255, 37, 95, 0.10); + border-color: rgba(255, 37, 95, 0.30); +} +QToolBar#ContextToolbar QLabel#CtxLabel { + color: #6e6f76; + font-size: 12px; +} +QToolBar#ContextToolbar QComboBox#CtxCombo, +QToolBar#ContextToolbar QSpinBox#CtxSpin { + background-color: #ffffff; + color: #1b1b1f; + border: 1px solid #dfe0e4; + border-radius: 5px; + padding: 3px 6px; + min-height: 22px; +} QTabBar { background: transparent; } @@ -674,6 +714,41 @@ class TabData: QToolBar#MainToolbar QToolButton#SemanticToggle:disabled { color: #55565e; } +QToolBar#ContextToolbar { + background-color: #222327; + border: none; + border-bottom: 1px solid #2b2c31; + padding: 4px 10px; + spacing: 4px; +} +QToolBar#ContextToolbar QToolButton#CtxButton { + background: transparent; + border: 1px solid transparent; + border-radius: 5px; + padding: 3px 8px; + color: #ececed; + font-size: 12px; +} +QToolBar#ContextToolbar QToolButton#CtxButton:hover { + background-color: rgba(255, 255, 255, 0.06); +} +QToolBar#ContextToolbar QToolButton#CtxButton:checked { + background-color: rgba(255, 77, 122, 0.14); + border-color: rgba(255, 77, 122, 0.40); +} +QToolBar#ContextToolbar QLabel#CtxLabel { + color: #9b9ca4; + font-size: 12px; +} +QToolBar#ContextToolbar QComboBox#CtxCombo, +QToolBar#ContextToolbar QSpinBox#CtxSpin { + background-color: #2a2b30; + color: #ececed; + border: 1px solid #3a3b42; + border-radius: 5px; + padding: 3px 6px; + min-height: 22px; +} QTabBar { background: transparent; } @@ -1183,6 +1258,57 @@ def _draw_close_icon(p: QPainter, s: float, c: dict[str, str]): p.drawLine(QPointF(12.8, 5.2), QPointF(5.2, 12.8)) +def _draw_fill_icon(p: QPainter, s: float, c: dict[str, str]): + p.setPen(_icon_pen(c["stroke"], 1.5)) + p.setBrush(Qt.BrushStyle.NoBrush) + p.drawRoundedRect(QRectF(3.0, 3.5, 8.2, 11.0), 1.5, 1.5) + p.setPen(_icon_pen(c["muted"], 1.2)) + p.drawLine(QPointF(4.8, 6.2), QPointF(9.2, 6.2)) + p.drawLine(QPointF(4.8, 8.6), QPointF(8.4, 8.6)) + p.setPen(_icon_pen(c["accent"], 1.7)) + p.drawLine(QPointF(10.0, 7.2), QPointF(14.4, 11.6)) + p.drawLine(QPointF(14.4, 11.6), QPointF(14.4, 14.0)) + p.drawLine(QPointF(14.4, 14.0), QPointF(12.0, 14.0)) + + +def _draw_text_icon(p: QPainter, s: float, c: dict[str, str]): + p.setPen(_icon_pen(c["stroke"], 1.8)) + p.drawLine(QPointF(4.0, 4.2), QPointF(14.0, 4.2)) + p.drawLine(QPointF(9.0, 4.2), QPointF(9.0, 14.6)) + p.drawLine(QPointF(6.2, 14.6), QPointF(11.8, 14.6)) + + +def _draw_signature_icon(p: QPainter, s: float, c: dict[str, str]): + p.setPen(_icon_pen(c["stroke"], 1.6)) + p.setBrush(Qt.BrushStyle.NoBrush) + path = QPainterPath() + path.moveTo(3.4, 13.8) + path.cubicTo(6.2, 10.4, 8.4, 4.4, 11.6, 4.4) + path.cubicTo(14.4, 4.4, 12.6, 9.6, 8.6, 12.4) + p.drawPath(path) + p.setPen(Qt.PenStyle.NoPen) + p.setBrush(QColor(c["accent"])) + nib = QPolygonF([QPointF(13.0, 3.2), QPointF(15.2, 5.4), QPointF(13.2, 7.4), QPointF(11.0, 5.2)]) + p.drawPolygon(nib) + + +def _draw_image_icon(p: QPainter, s: float, c: dict[str, str]): + p.setPen(_icon_pen(c["stroke"], 1.5)) + p.setBrush(Qt.BrushStyle.NoBrush) + p.drawRoundedRect(QRectF(2.8, 3.8, 12.4, 10.4), 1.5, 1.5) + p.setPen(Qt.PenStyle.NoPen) + p.setBrush(QColor(c["accent"])) + p.drawEllipse(QPointF(6.3, 7.0), 1.2, 1.2) + p.setPen(_icon_pen(c["muted"], 1.35)) + path = QPainterPath() + path.moveTo(3.4, 13.0) + path.lineTo(7.0, 9.4) + path.lineTo(9.4, 11.8) + path.lineTo(11.3, 9.9) + path.lineTo(14.4, 13.0) + p.drawPath(path) + + _TOOLBAR_ICONS = { "open": _draw_open_icon, "save": _draw_save_icon, @@ -1200,6 +1326,10 @@ def _draw_close_icon(p: QPainter, s: float, c: dict[str, str]): "sticky": _draw_sticky_icon, "search": _draw_search_icon, "close": _draw_close_icon, + "fill": _draw_fill_icon, + "text": _draw_text_icon, + "signature": _draw_signature_icon, + "image": _draw_image_icon, } @@ -1377,6 +1507,7 @@ def __init__(self, window, tab_id: int): self._radio_groups: dict = {} # field.name -> QButtonGroup self._button_group = None self.dirty = False + self.readonly = False self._dirty_names: set = set() self._seeding = 0 self._current_index = -1 @@ -1500,6 +1631,7 @@ def _attach_radio(self, label, field, zoom, page_rect, style): max(8, round((opt_rect[3] - opt_rect[1]) * zoom)), ) rb.setStyleSheet(style) + rb.setEnabled(not self.readonly) if field.value == caption: rb.setChecked(True) group.addButton(rb) @@ -1547,6 +1679,8 @@ def _open_date_picker(self, field): def _register_widget(self, widget, field): self._widgets[widget] = field self._field_widgets.setdefault(field.name, []).append(widget) + if self.readonly: + widget.setEnabled(False) def _seed_widget(self, widget, field): value = field.value @@ -1808,7 +1942,7 @@ def save(self, doc, path) -> bool: continue try: _ff.set_field_value(doc, field, self.current_value(field)) - except Exception: + except Exception: # nosec B112 continue self._persist(doc, path) self.dirty = False @@ -1986,8 +2120,8 @@ def __init__(self, ipc_server: QLocalServer | None = None): _perf_start_t = _perf_start() super().__init__() self.setWindowTitle(self.APP_NAME) - self.resize(1100, 820) - self.setMinimumSize(720, 480) + self.resize(1240, 840) + self.setMinimumSize(900, 560) # ---- IPC server for single-instance tab routing ---- self._ipc_server = ipc_server @@ -2047,6 +2181,18 @@ def __init__(self, ipc_server: QLocalServer | None = None): self._form_controllers: dict[int, _FormController] = {} _app_data = QStandardPaths.writableLocation(QStandardPaths.AppDataLocation) self._form_store = _ff.FormStateStore(base_dir=Path(_app_data)) + + # ---- Editing: Fill / Add Text / Sign / Image (v1.3.0) ---- + self._edit_controllers: dict[int, edit_ui.EditController] = {} + self._edit_tool_buttons: dict[str, QToolButton] = {} + self._edit_tool: str | None = None + self._context_toolbar = None + self._ctx_updating = False + self._ctx_color_value = "#000000" + self._signed_warning_tabs: set[int] = set() + self._signature_store = sig_store.SignatureStore( + Path(_app_data) / "signatures" + ) self._form_menu = None self._navigator_action = None @@ -2379,6 +2525,39 @@ def icon_button( ): toolbar.addWidget(annotation_button) + # ── Edit: Fill / Add Text / Sign / Image (v1.3.0) ── + toolbar.addSeparator() + self.fill_button = icon_button( + "fill", "Fill form fields", "Fill form fields" + ) + self.fill_button.clicked.connect(self._focus_first_form_field) + self.text_button = icon_button( + "text", "Add text", "Add text", checkable=True + ) + self.text_button.clicked.connect( + lambda checked: self._activate_edit_tool("text", checked) + ) + self.sign_button = icon_button( + "signature", "Add signature", "Add signature", checkable=True + ) + self.sign_button.clicked.connect(self._choose_signature) + self.image_button = icon_button( + "image", "Insert image", "Insert image", checkable=True + ) + self.image_button.clicked.connect(self._choose_image) + self._edit_tool_buttons = { + "text": self.text_button, + "sign": self.sign_button, + "image": self.image_button, + } + for edit_button in ( + self.fill_button, + self.text_button, + self.sign_button, + self.image_button, + ): + toolbar.addWidget(edit_button) + # Keep search anchored to the right edge of the toolbar. spacer = QWidget(toolbar) spacer.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Preferred) @@ -2451,6 +2630,7 @@ def icon_button( toolbar.addWidget(self.semantic_cb) self._refresh_toolbar_icons() + self._build_context_toolbar() def _refresh_toolbar_icons(self): """Re-render every toolbar icon for the active theme.""" @@ -2469,6 +2649,670 @@ def _refresh_toolbar_icons(self): if getattr(self, "_empty_icon_label", None) is not None: self._empty_icon_label.setPixmap(_make_empty_state_icon(self._dark_mode)) + # ------------------------------------------------------------------ + # Editing: Fill / Add Text / Sign / Image (v1.3.0) + # ------------------------------------------------------------------ + + def _build_context_toolbar(self): + self.addToolBarBreak(Qt.TopToolBarArea) + bar = QToolBar("Context Toolbar", self) + bar.setObjectName("ContextToolbar") + bar.setMovable(False) + bar.setFloatable(False) + bar.setIconSize(QSize(16, 16)) + self.addToolBar(Qt.TopToolBarArea, bar) + self.context_toolbar = bar + + self._ctx_font = QComboBox(bar) + self._ctx_font.setObjectName("CtxCombo") + for label, pdf_name in eo.TEXT_FONTS: + self._ctx_font.addItem(label, pdf_name) + self._ctx_font.setFixedWidth(150) + self._ctx_font.currentIndexChanged.connect(self._on_context_style_changed) + + self._ctx_size = QSpinBox(bar) + self._ctx_size.setObjectName("CtxSpin") + self._ctx_size.setRange(6, 96) + self._ctx_size.setValue(14) + self._ctx_size.setFixedWidth(58) + self._ctx_size.valueChanged.connect(self._on_context_style_changed) + + self._ctx_color = QToolButton(bar) + self._ctx_color.setObjectName("CtxButton") + self._ctx_color.setText("A") + self._ctx_color.setToolTip("Text color") + self._ctx_color.clicked.connect(self._choose_text_color) + self._update_color_button() + + def toggle(label, tooltip, *, bold=False, italic=False, underline=False): + button = QToolButton(bar) + button.setObjectName("CtxButton") + button.setText(label) + button.setToolTip(tooltip) + button.setCheckable(True) + font = button.font() + font.setBold(bold) + font.setItalic(italic) + font.setUnderline(underline) + button.setFont(font) + button.clicked.connect(self._on_context_style_changed) + return button + + self._ctx_bold = toggle("B", "Bold", bold=True) + self._ctx_italic = toggle("I", "Italic", italic=True) + self._ctx_underline = toggle("U", "Underline", underline=True) + + self._ctx_align_group = QButtonGroup(self) + self._ctx_align_group.setExclusive(True) + self._ctx_align_left = toggle("L", "Align left") + self._ctx_align_center = toggle("C", "Align center") + self._ctx_align_right = toggle("R", "Align right") + for button in ( + self._ctx_align_left, + self._ctx_align_center, + self._ctx_align_right, + ): + self._ctx_align_group.addButton(button) + self._ctx_align_left.setChecked(True) + + self._ctx_rotate = QToolButton(bar) + self._ctx_rotate.setObjectName("CtxButton") + self._ctx_rotate.setText("Rotate 90°") + self._ctx_rotate.setToolTip("Rotate the selected object by 90 degrees") + self._ctx_rotate.clicked.connect(self._context_rotate) + + self._ctx_duplicate = QToolButton(bar) + self._ctx_duplicate.setObjectName("CtxButton") + self._ctx_duplicate.setText("Duplicate") + self._ctx_duplicate.setToolTip("Duplicate the selected object") + self._ctx_duplicate.clicked.connect(self._context_duplicate) + + self._ctx_delete = QToolButton(bar) + self._ctx_delete.setObjectName("CtxButton") + self._ctx_delete.setText("Delete") + self._ctx_delete.setToolTip("Delete the selected object") + self._ctx_delete.clicked.connect(self._context_delete) + + self._ctx_done = QToolButton(bar) + self._ctx_done.setObjectName("CtxButton") + self._ctx_done.setText("Done") + self._ctx_done.setToolTip("Finish editing this text") + self._ctx_done.clicked.connect(self._context_done) + + self._ctx_hint = QLabel("Select text or an object to format", bar) + self._ctx_hint.setObjectName("CtxLabel") + self._ctx_hint_action = bar.addWidget(self._ctx_hint) + + self._ctx_text_actions = [] + text_label = QLabel("Text", bar) + text_label.setObjectName("CtxLabel") + self._ctx_text_actions.append(bar.addWidget(text_label)) + for widget in ( + self._ctx_font, + self._ctx_size, + self._ctx_color, + self._ctx_bold, + self._ctx_italic, + self._ctx_underline, + ): + self._ctx_text_actions.append(bar.addWidget(widget)) + self._ctx_text_actions.append(bar.addSeparator()) + for widget in ( + self._ctx_align_left, + self._ctx_align_center, + self._ctx_align_right, + ): + self._ctx_text_actions.append(bar.addWidget(widget)) + bar.addSeparator() + for widget in ( + self._ctx_rotate, + self._ctx_duplicate, + self._ctx_delete, + ): + bar.addWidget(widget) + self._ctx_done_action = bar.addWidget(self._ctx_done) + self._ctx_text_widgets = [ + text_label, + self._ctx_font, + self._ctx_size, + self._ctx_color, + self._ctx_bold, + self._ctx_italic, + self._ctx_underline, + self._ctx_align_left, + self._ctx_align_center, + self._ctx_align_right, + ] + for control in ( + self._ctx_font, + self._ctx_size, + self._ctx_color, + self._ctx_bold, + self._ctx_italic, + self._ctx_underline, + self._ctx_align_left, + self._ctx_align_center, + self._ctx_align_right, + self._ctx_rotate, + self._ctx_duplicate, + self._ctx_delete, + self._ctx_done, + ): + control.setFixedHeight(28) + bar.hide() + + def _update_color_button(self): + self._ctx_color.setStyleSheet( + f"QToolButton#CtxButton {{ color: {self._ctx_color_value}; font-weight: 700; }}" + ) + + def _on_context_style_changed(self, *args): + if self._ctx_updating: + return + controller = self._edit_for_current() + obj = controller.selected_object() if controller else None + if obj is None or obj.kind != eo.TEXT_KIND: + return + align = ( + "left" + if self._ctx_align_left.isChecked() + else "center" + if self._ctx_align_center.isChecked() + else "right" + ) + style = eo.TextStyle( + font_family=self._ctx_font.currentData() or "Helvetica", + font_size=float(self._ctx_size.value()), + color=self._ctx_color_value, + bold=self._ctx_bold.isChecked(), + italic=self._ctx_italic.isChecked(), + underline=self._ctx_underline.isChecked(), + align=align, + ) + controller.apply_style(style) + + def _choose_text_color(self): + color = QColorDialog.getColor( + QColor(self._ctx_color_value), self, "Text Color" + ) + if color.isValid(): + self._ctx_color_value = color.name() + self._update_color_button() + self._on_context_style_changed() + + def _context_rotate(self): + controller = self._edit_for_current() + if controller is not None: + controller.rotate_selected(90) + self._on_edit_selection_changed(controller.selected_object()) + + def _context_duplicate(self): + controller = self._edit_for_current() + if controller is not None: + controller.duplicate_selected() + + def _context_delete(self): + controller = self._edit_for_current() + if controller is not None: + controller.delete_selected() + + def _context_done(self): + controller = self._edit_for_current() + if controller is not None: + controller._finish_text_edit() + + def _on_edit_selection_changed(self, obj): + if not getattr(self, "context_toolbar", None): + return + if obj is None: + if self.document is None: + self.context_toolbar.hide() + return + self._ctx_updating = True + try: + for action in getattr(self, "_ctx_text_actions", []): + action.setVisible(False) + for widget in self._ctx_text_widgets: + widget.setVisible(False) + if getattr(self, "_ctx_done_action", None) is not None: + self._ctx_done_action.setVisible(False) + self._ctx_done.setVisible(False) + if getattr(self, "_ctx_hint_action", None) is not None: + self._ctx_hint_action.setVisible(True) + self._ctx_hint.setVisible(True) + for control in ( + self._ctx_rotate, + self._ctx_duplicate, + self._ctx_delete, + ): + control.setEnabled(False) + finally: + self._ctx_updating = False + self.context_toolbar.show() + return + controller = self._edit_for_current() + self._ctx_updating = True + try: + if getattr(self, "_ctx_hint_action", None) is not None: + self._ctx_hint_action.setVisible(False) + self._ctx_hint.setVisible(False) + for control in ( + self._ctx_rotate, + self._ctx_duplicate, + self._ctx_delete, + ): + control.setEnabled(True) + is_text = obj.kind == eo.TEXT_KIND + for action in getattr(self, "_ctx_text_actions", []): + action.setVisible(is_text) + for widget in self._ctx_text_widgets: + widget.setVisible(is_text) + editing = bool( + is_text + and controller is not None + and getattr(controller, "_editor", None) is not None + ) + if getattr(self, "_ctx_done_action", None) is not None: + self._ctx_done_action.setVisible(editing) + self._ctx_done.setVisible(editing) + if is_text: + style = obj.style.normalized() + index = self._ctx_font.findData(style.font_family) + self._ctx_font.setCurrentIndex(index if index >= 0 else 0) + self._ctx_size.setValue(int(round(style.font_size))) + self._ctx_color_value = style.color + self._update_color_button() + self._ctx_bold.setChecked(style.bold) + self._ctx_italic.setChecked(style.italic) + self._ctx_underline.setChecked(style.underline) + self._ctx_align_left.setChecked(style.align == "left") + self._ctx_align_center.setChecked(style.align == "center") + self._ctx_align_right.setChecked(style.align == "right") + finally: + self._ctx_updating = False + self.context_toolbar.show() + + def _on_edit_tool_changed(self, tool): + for name, button in getattr(self, "_edit_tool_buttons", {}).items(): + button.blockSignals(True) + button.setChecked(name == tool) + button.blockSignals(False) + self._edit_tool = tool + controller = self._edit_for_current() + self._on_edit_selection_changed( + controller.selected_object() if controller is not None else None + ) + + def _init_edit(self): + if self.current_tab_id is None or self.document is None or self.current_path is None: + return None + old = self._edit_controllers.pop(self.current_tab_id, None) + if old is not None: + old.detach_all() + tab_id = self.current_tab_id + controller = edit_ui.EditController(self, tab_id) + controller.selectionChanged.connect(self._on_edit_selection_changed) + controller.statusMessage.connect( + lambda message: self.statusBar().showMessage(message, 6000) + ) + controller.dirtyChanged.connect( + lambda _dirty, tid=tab_id: self._on_edit_dirty(tid) + ) + controller.toolChanged.connect(self._on_edit_tool_changed) + controller.load(self.document, self.current_path) + self._edit_controllers[self.current_tab_id] = controller + self._edit_tool = None + return controller + + def _edit_for_current(self): + if self.current_tab_id is None: + return None + return self._edit_controllers.get(self.current_tab_id) + + def _drop_edit_controller(self, tab_id): + controller = self._edit_controllers.pop(tab_id, None) + if controller is not None: + controller.detach_all() + if tab_id == self.current_tab_id: + self._edit_tool = None + self._on_edit_selection_changed(None) + + def _on_edit_dirty(self, tab_id): + self._update_window_title_dirty() + self._refresh_tab_dirty(tab_id) + + def _refresh_tab_dirty(self, tab_id): + form = self._form_controllers.get(tab_id) + edit = self._edit_controllers.get(tab_id) + dirty = bool( + (form is not None and form.dirty) + or (edit is not None and edit.is_dirty()) + ) + tab = self.tabs.get(tab_id) + if tab is None: + return + for index in range(self.tab_bar.count()): + if self.tab_bar.tabData(index) == tab_id: + self.tab_bar.setTabText( + index, ("● " if dirty else "") + tab.name + ) + break + + def _document_dirty(self, tab_id) -> bool: + form = self._form_controllers.get(tab_id) + edit = self._edit_controllers.get(tab_id) + return bool( + (form is not None and form.dirty) + or (edit is not None and edit.is_dirty()) + ) + + def _current_document_encrypted(self) -> bool: + tab = self.tabs.get(self.current_tab_id) if self.current_tab_id else None + return bool(getattr(tab, "encrypted", False)) + + def _focus_first_form_field(self): + form = self._form_for_current() + if form is not None: + self.form_dock.show() + self._rebuild_navigator() + if form.editable_fields: + form.focus_next(forward=True) + self.statusBar().showMessage( + "Form fields are editable — click any field.", 6000 + ) + return + self.statusBar().showMessage( + "This document has no interactive form fields; use Add Text instead.", + 6000, + ) + + def _activate_edit_tool(self, tool: str, checked: bool): + if not checked: + if self._edit_tool == tool: + self._deactivate_edit_tool() + return + controller = self._edit_for_current() + if controller is None or self.document is None: + self._uncheck_edit_tools() + return + if not eo.document_allows_editing(self.document): + self._uncheck_edit_tools() + self.statusBar().showMessage( + "This document is read-only or encrypted and cannot be edited.", 6000 + ) + return + if not self._confirm_edit_on_signed(): + self._uncheck_edit_tools() + return + controller.set_tool(tool) + self._edit_tool = tool + if tool == "text": + self.statusBar().showMessage( + "Click on the page to add text. Escape to cancel.", 6000 + ) + + def _uncheck_edit_tools(self): + for button in self._edit_tool_buttons.values(): + button.blockSignals(True) + button.setChecked(False) + button.blockSignals(False) + self._edit_tool = None + + def _deactivate_edit_tool(self): + controller = self._edit_for_current() + if controller is not None: + controller.set_tool(None) + self._uncheck_edit_tools() + self._edit_tool = None + self._on_edit_selection_changed(None) + + def _choose_signature(self): + controller = self._edit_for_current() + if controller is None or self.document is None: + self.sign_button.setChecked(False) + return + if not eo.document_allows_editing(self.document): + self.sign_button.setChecked(False) + self.statusBar().showMessage( + "This document cannot be edited.", 5000 + ) + return + if not self._confirm_edit_on_signed(): + self.sign_button.setChecked(False) + return + dialog = edit_ui.SignatureDialog(self._signature_store, self) + if dialog.exec() and dialog.result_png: + controller.set_pending_image( + "signature", dialog.result_png, dialog.result_name + ) + self._edit_tool = "sign" + self.statusBar().showMessage( + "Click on the page to place the signature. Escape to cancel.", + 6000, + ) + else: + self._uncheck_edit_tools() + controller.set_tool(None) + + def _choose_image(self): + controller = self._edit_for_current() + if controller is None or self.document is None: + self.image_button.setChecked(False) + return + if not eo.document_allows_editing(self.document): + self.image_button.setChecked(False) + self.statusBar().showMessage("This document cannot be edited.", 5000) + return + if not self._confirm_edit_on_signed(): + self.image_button.setChecked(False) + return + path, _ = QFileDialog.getOpenFileName( + self, + "Insert Image", + str(Path.home()), + "Images (*.png *.jpg *.jpeg *.bmp *.webp *.gif)", + ) + if not path: + self._uncheck_edit_tools() + return + image = QImage(path) + if image.isNull(): + self.image_button.setChecked(False) + self.statusBar().showMessage("That image could not be read.", 5000) + return + image = image.convertToFormat(QImage.Format_RGBA8888) + buffer = QBuffer() + buffer.open(QBuffer.OpenModeFlag.WriteOnly) + image.save(buffer, "PNG") + png = bytes(buffer.data()) + buffer.close() + controller.set_pending_image("image", png, Path(path).name) + self._edit_tool = "image" + self.statusBar().showMessage( + "Click on the page to place the image. Escape to cancel.", 6000 + ) + + def _confirm_edit_on_signed(self) -> bool: + if self.document is None or not eo.document_has_signatures(self.document): + return True + if self.current_tab_id in self._signed_warning_tabs: + return True + box = QMessageBox(self) + box.setWindowTitle("Digital Signature Detected") + box.setIcon(QMessageBox.Icon.Warning) + box.setText( + "This PDF contains a digital signature.\n\n" + "Editing it will invalidate the existing signature. " + "OpenReader uses visual electronic signatures only and does not " + "create certificate-based digital signatures." + ) + continue_button = box.addButton("Continue Editing", QMessageBox.ButtonRole.DestructiveRole) + box.addButton("Cancel", QMessageBox.ButtonRole.RejectRole) + box.exec() + if box.clickedButton() is continue_button: + self._signed_warning_tabs.add(self.current_tab_id) + return True + return False + + def _confirm_save_signed(self) -> bool: + if not self._document_dirty(self.current_tab_id): + return True + if self.document is None or not eo.document_has_signatures(self.document): + return True + box = QMessageBox(self) + box.setWindowTitle("Signed Document") + box.setIcon(QMessageBox.Icon.Warning) + box.setText( + "Saving changes to this signed document will invalidate its " + "existing digital signature." + ) + save_button = box.addButton("Save Anyway", QMessageBox.ButtonRole.DestructiveRole) + copy_button = box.addButton("Save As Copy…", QMessageBox.ButtonRole.ActionRole) + box.addButton("Cancel", QMessageBox.ButtonRole.RejectRole) + box.exec() + if box.clickedButton() is save_button: + return True + if box.clickedButton() is copy_button: + self._save_document_as() + return False + return False + + def _edit_undo(self) -> bool: + controller = self._edit_for_current() + if controller is not None: + focus = QApplication.focusWidget() + if controller._editor is not None and focus is controller._editor: + controller._editor.undo() + return True + if controller.undo(): + return True + focus = QApplication.focusWidget() + if isinstance(focus, (QLineEdit, QTextEdit)): + focus.undo() + return True + return False + + def _edit_redo(self) -> bool: + controller = self._edit_for_current() + if controller is not None: + focus = QApplication.focusWidget() + if controller._editor is not None and focus is controller._editor: + controller._editor.redo() + return True + if controller.redo(): + return True + focus = QApplication.focusWidget() + if isinstance(focus, (QLineEdit, QTextEdit)): + focus.redo() + return True + return False + + def _edit_escape(self) -> bool: + controller = self._edit_for_current() + if controller is None: + return False + if controller._editor is not None: + controller._cancel_text_edit() + return True + if controller.tool is not None: + self._deactivate_edit_tool() + return True + if controller.selected_object() is not None: + controller.select(None) + controller.set_tool(None) + return True + return False + + def _edit_delete_key(self) -> bool: + focus = QApplication.focusWidget() + if isinstance(focus, (QLineEdit, QTextEdit, QSpinBox, QComboBox)): + return False + controller = self._edit_for_current() + if controller is not None and controller.selected_object() is not None: + controller.delete_selected() + return True + return False + + def _edit_paste_shortcut(self) -> bool: + focus = QApplication.focusWidget() + if isinstance(focus, (QLineEdit, QTextEdit)): + return False + controller = self._edit_for_current() + return bool(controller is not None and controller.paste()) + + def _page_index_for_label(self, obj): + if obj is self.page_label: + return self.current_page + labels = getattr(self, "_continuous_pages", []) + try: + return labels.index(obj) + except ValueError: + return None + + def _export_flattened(self): + if self.document is None or self.current_path is None: + self.statusBar().showMessage("No document open", 3000) + return + controller = self._edit_for_current() + if controller is not None: + controller._finish_text_edit() + form = self._form_for_current() + if form is not None: + self._write_dirty_form_values(form) + default_name = f"{Path(self.current_path).stem}_flattened.pdf" + target, _ = QFileDialog.getSaveFileName( + self, + "Export Flattened PDF", + str(Path(self.current_path).with_name(default_name)), + "PDF files (*.pdf)", + ) + if not target: + return + if not target.lower().endswith(".pdf"): + target += ".pdf" + try: + eo.export_flattened(self.document, target) + self.statusBar().showMessage( + f"Flattened copy saved as {Path(target).name}", 5000 + ) + except Exception as exc: + self.statusBar().showMessage(f"Export failed: {exc}", 6000) + + def _save_tab(self, tab_id) -> bool: + tab = self.tabs.get(tab_id) + if tab is None or tab.document is None or not tab.path: + return False + form = self._form_controllers.get(tab_id) + edit = self._edit_controllers.get(tab_id) + try: + if form is not None and form.dirty: + for name in form._dirty_names: + field = form._by_name.get(name) + if field is None or not field.is_editable(): + continue + try: + _ff.set_field_value( + tab.document, field, form.current_value(field) + ) + except Exception: # nosec B112 + continue + if edit is not None: + edit._finish_text_edit() + eo.save_document(tab.document, tab.path) + if edit is not None: + edit.mark_saved() + if form is not None: + form.dirty = False + form._dirty_names = set() + if getattr(form, "_state_store", None) is not None: + form._state_store.clear(tab.path) + self._refresh_tab_dirty(tab_id) + self._update_window_title_dirty() + return True + except Exception as exc: + self.statusBar().showMessage(f"Save failed: {exc}", 6000) + return False + @staticmethod def _menu_label(label: str, shortcut: str) -> str: return f"{label}\t{shortcut}" @@ -2497,6 +3341,21 @@ def _build_shortcuts(self): self._app_shortcuts.append(shortcut) def eventFilter(self, obj, event): + # Editing tools capture a click on a rendered page to place an object. + if event.type() == QEvent.MouseButtonPress and event.button() == Qt.LeftButton: + if self._edit_tool in ("text", "sign", "image"): + page_index = self._page_index_for_label(obj) + if page_index is not None: + edit = self._edit_for_current() + zoom = ( + self._continuous_layout_zoom + if self._continuous_mode + else self.current_render_zoom + ) + if edit is not None and edit.handle_page_click( + page_index, obj, event.position().toPoint(), zoom or 1.0 + ): + return True # Ctrl + Mouse Wheel zoom on the scroll area viewport if (event.type() == QEvent.Wheel and obj is self.scroll_area.viewport() @@ -2523,10 +3382,27 @@ def _handle_shortcut_key_event(self, event) -> bool: if key == Qt.Key_PageDown: self.next_page() return True + if key == Qt.Key_Escape: + return self._edit_escape() + if key in (Qt.Key_Delete, Qt.Key_Backspace): + return self._edit_delete_key() + return False + if modifiers == (Qt.ControlModifier | Qt.ShiftModifier): + if key == Qt.Key_Z: + return self._edit_redo() return False if modifiers != Qt.ControlModifier: return False + if key in (Qt.Key_Z, Qt.Key_Y): + return self._edit_undo() if key == Qt.Key_Z else self._edit_redo() + if key == Qt.Key_V: + focus = QApplication.focusWidget() + if isinstance(focus, (QLineEdit, QTextEdit)): + return False + controller = self._edit_for_current() + return bool(controller is not None and controller.paste()) + ctrl_handlers = { Qt.Key_O: self.open_pdf, Qt.Key_T: self.new_tab, @@ -2560,6 +3436,14 @@ def _copy_shortcut(self): if isinstance(focus, QTextEdit) and focus.textCursor().hasSelection(): focus.copy() return + if not isinstance(focus, (QLineEdit, QTextEdit)): + controller = self._edit_for_current() + if ( + controller is not None + and controller.selected_object() is not None + and controller.copy_selected() + ): + return self.copy_selected_text() def _fit_width_shortcut(self): @@ -2616,6 +3500,10 @@ def _build_menus(self): file_save_as.triggered.connect(self._save_document_as) file_menu.addAction(file_save_as) + file_export = QAction("Export Flattened PDF…", self) + file_export.triggered.connect(self._export_flattened) + file_menu.addAction(file_export) + file_menu.addSeparator() settings_action = QAction("Settings…", self) @@ -2950,14 +3838,24 @@ def _on_tab_switch(self, index: int): new_tab_id = self.tab_bar.tabData(index) if new_tab_id is None or new_tab_id == self.current_tab_id: return + old_edit = self._edit_for_current() + if old_edit is not None: + old_edit.detach_all() self._save_current_state() self._save_current_tab_controls() self._restore_state(new_tab_id) self._restore_current_tab_controls() + if ( + self.current_tab_id not in self._edit_controllers + and self.document is not None + and self.current_path is not None + ): + self._init_edit() self.clear_text_selection(render=False) self.statusBar().clearMessage() self.render_page() self._update_controls() + self._refresh_tab_dirty(new_tab_id) # Refresh form-related chrome for the newly selected tab (Phase 2). self._update_window_title_dirty() self._update_form_menu_state() @@ -3054,6 +3952,7 @@ def _close_tab(self, tab_id: int): if tab.document is not None: tab.document.close() self._drop_form_controller(tab_id) + self._drop_edit_controller(tab_id) self.tab_bar.blockSignals(True) try: for i in range(self.tab_bar.count()): @@ -3114,12 +4013,24 @@ def _close_tab(self, tab_id: int): def _close_all_tabs(self): tab_ids = list(self.tabs.keys()) + for tab_id in tab_ids: + if not self._confirm_discard_form(tab_id): + return + for controller in getattr(self, "_form_controllers", {}).values(): + controller.detach_all() + for controller in getattr(self, "_edit_controllers", {}).values(): + controller.detach_all() for tid in tab_ids: if tid in self.tabs: tab = self.tabs[tid] if tab.document is not None: tab.document.close() self.tabs.clear() + self._form_controllers.clear() + self._edit_controllers.clear() + self._edit_tool = None + if getattr(self, "context_toolbar", None): + self.context_toolbar.hide() self.tab_bar.clear() self._sync_tab_strip() self.current_tab_id = None @@ -3267,6 +4178,12 @@ def load_pdf(self, file_name): if self.current_tab_id is not None and self.current_tab_id in self.tabs: self.tabs[self.current_tab_id].document = document self.tabs[self.current_tab_id].path = file_name + try: + self.tabs[self.current_tab_id].encrypted = bool( + document.needs_pass or document.is_encrypted + ) + except Exception: + self.tabs[self.current_tab_id].encrypted = False self.document = document self.current_path = file_name @@ -3306,6 +4223,7 @@ def load_pdf(self, file_name): # Build AcroForm overlays (Phase 2) before the first render. self._init_form() + self._init_edit() self.render_page() self._update_controls() @@ -3448,6 +4366,9 @@ def _render_single_page(self): if current_form is not None: current_form.detach_all() self._attach_form_overlays(self.page_label, self.current_page, zoom) + edit = self._edit_for_current() + if edit is not None: + edit.attach_page(self.page_label, self.current_page, zoom) self.page_label.adjustSize() self.page_spin.blockSignals(True) self.page_spin.setValue(self.current_page + 1) @@ -3559,6 +4480,9 @@ def _teardown_continuous_layout(self): form = self._form_for_current() if form is not None: form.detach_all() + edit = self._edit_for_current() + if edit is not None: + edit.detach_all() # Clear the page list before detaching the widget so scroll events # raised by the swap are ignored. self._continuous_pages = [] @@ -3583,6 +4507,9 @@ def _release_pixmap(self, page_index: int): form = self._form_for_current() if form is not None and 0 <= page_index < len(self._continuous_pages): form.detach_page(self._continuous_pages[page_index]) + edit = self._edit_for_current() + if edit is not None and 0 <= page_index < len(self._continuous_pages): + edit.detach_page(self._continuous_pages[page_index]) if 0 <= page_index < len(self._continuous_pages): self._continuous_pages[page_index].clear() self._continuous_rendered.discard(page_index) @@ -3673,6 +4600,11 @@ def _render_continuous_page(self, page_index: int): self._attach_form_overlays( self._continuous_pages[page_index], page_index, layout_zoom ) + edit = self._edit_for_current() + if edit is not None: + edit.attach_page( + self._continuous_pages[page_index], page_index, layout_zoom + ) except Exception: # Leave the placeholder in place — one unrenderable page must not # take the rest of the document down with it. @@ -3683,7 +4615,11 @@ def _render_continuous_page(self, page_index: int): def _on_continuous_scrolled(self, value: int): if not self._continuous_mode: return - if self.document is None or not self._continuous_pages: + if ( + self.document is None + or getattr(self.document, "is_closed", False) + or not self._continuous_pages + ): return if self._continuous_syncing_scroll or self._pending_scroll_page is not None: return @@ -3714,6 +4650,9 @@ def _scroll_to_page(self, page_index: int): def _apply_pending_scroll(self): page_index = self._pending_scroll_page + if self.document is None or getattr(self.document, "is_closed", False): + self._pending_scroll_page = None + return if page_index is None or not self._continuous_pages: return if page_index >= len(self._continuous_pages): @@ -3734,7 +4673,7 @@ def _apply_pending_scroll(self): self._update_page_controls() def _update_page_controls(self): - if self.document is None: + if self.document is None or getattr(self.document, "is_closed", False): return self.page_spin.blockSignals(True) self.page_spin.setValue(self.current_page + 1) @@ -4082,33 +5021,45 @@ def _save_document_annotations(self): except Exception as exc: self.statusBar().showMessage(f"Could not save annotations: {exc}", 5000) - def _save_document(self): - """Explicit save via File > Save (form values + annotations).""" + def _save_document(self) -> bool: + """Explicit save via File > Save (form values, edits, annotations).""" if self.current_path is None or self.document is None: self.statusBar().showMessage("No document open", 3000) - return + return False + edit = self._edit_for_current() + if edit is not None: + edit._finish_text_edit() + if not self._confirm_save_signed(): + return False form = self._form_for_current() - if form is not None and form.dirty: - try: - form.save(self.document, self.current_path) - self._update_window_title_dirty() - self._update_navigator_item_for_tab(self.current_tab_id) - self.statusBar().showMessage("Document saved", 3000) - return - except Exception as exc: - self.statusBar().showMessage(f"Save failed: {exc}", 5000) - return try: - self.document.save(self.current_path, garbage=1, deflate=True) - self.statusBar().showMessage("Document saved", 3000) + if form is not None and form.dirty: + self._write_dirty_form_values(form) + eo.save_document(self.document, self.current_path) except Exception as exc: - self.statusBar().showMessage(f"Save failed: {exc}", 5000) + self.statusBar().showMessage(f"Save failed: {exc}", 6000) + return False + if edit is not None: + edit.mark_saved() + if form is not None: + form.dirty = False + form._dirty_names = set() + if getattr(form, "_state_store", None) is not None: + form._state_store.clear(self.current_path) + self._update_window_title_dirty() + self._refresh_tab_dirty(self.current_tab_id) + self._update_navigator_item_for_tab(self.current_tab_id) + self.statusBar().showMessage("Document saved", 3000) + return True - def _save_document_as(self): - """Save As — full save to a new path, updating the tab.""" + def _save_document_as(self) -> bool: + """Save As — atomic full save to a new path, updating the tab.""" if self.document is None or self.current_path is None: self.statusBar().showMessage("No document open", 3000) - return + return False + edit = self._edit_for_current() + if edit is not None: + edit._finish_text_edit() default_name = f"{Path(self.current_path).stem}_completed.pdf" new_path, _ = QFileDialog.getSaveFileName( self, @@ -4117,24 +5068,34 @@ def _save_document_as(self): "PDF files (*.pdf)", ) if not new_path: - return + return False if not new_path.lower().endswith(".pdf"): new_path += ".pdf" + form = self._form_for_current() try: - form = self._form_for_current() if form is not None: self._write_dirty_form_values(form) - form.save_as(self.document, new_path) - else: - self.document.save(new_path, garbage=1, deflate=True) - self.current_path = new_path - if self.current_tab_id in self.tabs: - self.tabs[self.current_tab_id].path = new_path - self._add_recent_file(new_path) - self._update_window_title_dirty() - self.statusBar().showMessage(f"Saved as {Path(new_path).name}", 4000) + eo.save_document(self.document, new_path) except Exception as exc: - self.statusBar().showMessage(f"Save As failed: {exc}", 5000) + self.statusBar().showMessage(f"Save As failed: {exc}", 6000) + return False + if edit is not None: + edit.mark_saved() + edit.path = new_path + if form is not None: + form.dirty = False + form._dirty_names = set() + if getattr(form, "_state_store", None) is not None: + form._state_store.clear(new_path) + self.current_path = new_path + if self.current_tab_id in self.tabs: + self.tabs[self.current_tab_id].path = new_path + self.tabs[self.current_tab_id].name = Path(new_path).name + self._add_recent_file(new_path) + self._update_window_title_dirty() + self._refresh_tab_dirty(self.current_tab_id) + self.statusBar().showMessage(f"Saved as {Path(new_path).name}", 4000) + return True def _write_dirty_form_values(self, form): for name in form._dirty_names: @@ -4143,7 +5104,7 @@ def _write_dirty_form_values(self, form): continue try: _ff.set_field_value(self.document, field, form.current_value(field)) - except Exception: + except Exception: # nosec B112 continue # ------------------------------------------------------------------ @@ -4160,8 +5121,16 @@ def _init_form(self): stale.detach_all() controller = _FormController(self, self.current_tab_id) controller.load(self.document, self.current_path) + controller.readonly = not eo.document_allows_editing( + self.document, encrypted=self._current_document_encrypted() + ) controllers[self.current_tab_id] = controller count = len(controller.fields) + if controller.readonly and count: + self.statusBar().showMessage( + "This document is read-only; form fields are displayed but cannot be edited.", + 7000, + ) if count and _ff.has_form_fields(self.document): self._mark_recent_form_doc(self.current_path) self.statusBar().showMessage( @@ -4187,6 +5156,7 @@ def _on_form_dirty(self, tab_id): self._update_window_title_dirty() self._update_form_menu_state() self._update_navigator_item_for_tab(tab_id) + self._refresh_tab_dirty(tab_id) def _update_window_title_dirty(self): if self.current_path: @@ -4194,7 +5164,11 @@ def _update_window_title_dirty(self): else: base = self.APP_NAME form = self._form_for_current() - dirty = form is not None and form.dirty + edit = self._edit_for_current() + dirty = bool( + (form is not None and form.dirty) + or (edit is not None and edit.is_dirty()) + ) self.setWindowTitle(("● " if dirty else "") + base) def _on_form_focus(self, field): @@ -4441,29 +5415,35 @@ def _form_review_complete(self): # -- close warning ------------------------------------------------------ def _confirm_discard_form(self, tab_id) -> bool: - """If the tab has unsaved form edits, ask. Returns True to proceed.""" - controller = getattr(self, "_form_controllers", {}).get(tab_id) - if controller is None or not controller.dirty: + """If the tab has unsaved form or edit changes, ask. True to proceed.""" + form = getattr(self, "_form_controllers", {}).get(tab_id) + edit = getattr(self, "_edit_controllers", {}).get(tab_id) + form_dirty = form is not None and form.dirty + edit_dirty = edit is not None and edit.is_dirty() + if not form_dirty and not edit_dirty: return True tab = self.tabs.get(tab_id) answer = QMessageBox.question( self, - "Unsaved Form", - "This form has unsaved changes. Save before closing?", + "Unsaved Changes", + "This document has unsaved changes. Save before closing?", QMessageBox.Save | QMessageBox.Discard | QMessageBox.Cancel, QMessageBox.Save, ) if answer == QMessageBox.Save: - if tab is not None and tab.document is not None and tab.path: - try: - controller.save(tab.document, tab.path) - except Exception: - pass - return True + return self._save_tab(tab_id) if answer == QMessageBox.Discard: - path = tab.path if tab is not None and tab.path else getattr(self, "current_path", None) - if path and controller._state_store is not None: - controller._state_store.clear(path) + path = ( + tab.path + if tab is not None and tab.path + else getattr(self, "current_path", None) + ) + if ( + path + and form is not None + and getattr(form, "_state_store", None) is not None + ): + form._state_store.clear(path) return True return False @@ -4474,7 +5454,7 @@ def _mark_recent_form_doc(self, path): current = set(self.settings.value("formDocs", [], list)) current.add(str(Path(path).resolve())) self.settings.setValue("formDocs", list(current)) - except Exception: + except Exception: # nosec B110 pass def _is_recent_form_doc(self, path) -> bool: @@ -4915,7 +5895,10 @@ def compress_pdf(self): # ------------------------------------------------------------------ def _update_controls(self): - has_document = self.document is not None + has_document = bool( + self.document is not None + and not getattr(self.document, "is_closed", False) + ) can_go_previous = has_document and self.current_page > 0 can_go_next = has_document and self.current_page < self.document.page_count - 1 has_matches = bool(self.search_results) @@ -4938,12 +5921,38 @@ def _update_controls(self): self.search_prev_button.setEnabled(has_document and has_matches) self.search_next_button.setEnabled(has_document and has_matches) self.semantic_cb.setEnabled(has_document and HAS_LIB_MODULES) + can_edit = bool( + has_document + and self.document is not None + and eo.document_allows_editing( + self.document, encrypted=self._current_document_encrypted() + ) + ) + for edit_button in ( + getattr(self, "fill_button", None), + getattr(self, "text_button", None), + getattr(self, "sign_button", None), + getattr(self, "image_button", None), + ): + if edit_button is not None: + edit_button.setEnabled(can_edit) if hasattr(self, "zoom_label"): if has_document: self.zoom_label.setText(f"{int(round(self.current_render_zoom * 100))}%") else: self.zoom_label.setText("—") self.zoom_label.setEnabled(has_document) + if getattr(self, "context_toolbar", None) is not None: + if has_document: + self.context_toolbar.show() + controller = self._edit_for_current() + self._on_edit_selection_changed( + controller.selected_object() + if controller is not None + else None + ) + else: + self.context_toolbar.hide() # ------------------------------------------------------------------ # Events @@ -5485,7 +6494,12 @@ def closeEvent(self, event): for tab_id, controller in getattr(self, "_form_controllers", {}).items(): try: controller.detach_all() - except Exception: + except Exception: # nosec B110 + pass + for controller in getattr(self, "_edit_controllers", {}).values(): + try: + controller.detach_all() + except Exception: # nosec B110 pass # Close docs for tab_id, tab in self.tabs.items(): @@ -5496,6 +6510,8 @@ def closeEvent(self, event): pass # best-effort document close # nosec B110 self.tabs.clear() self._form_controllers.clear() + self._edit_controllers.clear() + self._edit_tool = None super().closeEvent(event) # ------------------------------------------------------------------ diff --git a/pdfreader_lib/edit_gui.py b/pdfreader_lib/edit_gui.py new file mode 100644 index 0000000..a87fd22 --- /dev/null +++ b/pdfreader_lib/edit_gui.py @@ -0,0 +1,1314 @@ +"""Qt editing layer for OpenReader v1.3.0 Fill / Edit / Sign. + +The document model and persistence live in ``edit_objects`` (Qt-free). This +module owns the interactive overlays, the inline text editor, the signature +creator and the per-tab editing controller. + +The controller is attached to the window's persistent page QLabels used by +both single-page and virtualized continuous rendering, so editing works in +continuous-scroll mode without switching modes. +""" + +from __future__ import annotations + +import io +import uuid +from pathlib import Path + +from PySide6.QtCore import QBuffer, QPoint, QPointF, QRect, QRectF, QSize, Qt, QTimer, Signal, QObject +from PySide6.QtGui import ( + QColor, + QFont, + QFontDatabase, + QFontMetrics, + QImage, + QPainter, + QPen, + QPixmap, + QPolygonF, +) +from PySide6.QtWidgets import ( + QCheckBox, + QComboBox, + QDialog, + QDialogButtonBox, + QFileDialog, + QFormLayout, + QHBoxLayout, + QLabel, + QLineEdit, + QListWidget, + QListWidgetItem, + QMessageBox, + QPushButton, + QSpinBox, + QTabWidget, + QTextEdit, + QToolButton, + QVBoxLayout, + QWidget, +) + +from . import edit_objects as eo +from . import signature_store as ss + +HANDLE = 7 +MIN_SIZE = 16 +CONTENT_OFFSET = 1 + + +def _qt_font_family(pdf_family: str) -> str: + return { + "Helvetica": "Arial", + "Times-Roman": "Times New Roman", + "Courier": "Courier New", + }.get(pdf_family, pdf_family) + + +def _pdf_rect_to_label( + rect: tuple[float, float, float, float], + page_rect, + zoom: float, +) -> QRect: + x0 = round((rect[0] - page_rect.x0) * zoom) + CONTENT_OFFSET + y0 = round((rect[1] - page_rect.y0) * zoom) + CONTENT_OFFSET + x1 = round((rect[2] - page_rect.x0) * zoom) + CONTENT_OFFSET + y1 = round((rect[3] - page_rect.y0) * zoom) + CONTENT_OFFSET + return QRect(x0, y0, max(1, x1 - x0), max(1, y1 - y0)) + + +def _label_rect_to_pdf( + rect: QRect, + page_rect, + zoom: float, +) -> tuple[float, float, float, float]: + if zoom <= 0: + zoom = 1.0 + x0 = page_rect.x0 + (rect.x() - CONTENT_OFFSET) / zoom + y0 = page_rect.y0 + (rect.y() - CONTENT_OFFSET) / zoom + x1 = page_rect.x0 + (rect.x() + rect.width() - CONTENT_OFFSET) / zoom + y1 = page_rect.y0 + (rect.y() + rect.height() - CONTENT_OFFSET) / zoom + return (x0, y0, x1, y1) + + +class TextEditOverlay(QTextEdit): + """Inline multiline editor anchored over a text object.""" + + committed = Signal(str) + cancelled = Signal() + + def __init__(self, text: str, style: eo.TextStyle, parent=None): + super().__init__(parent) + self.setPlainText(text) + self.setAcceptRichText(False) + self.setTabChangesFocus(False) + self.setObjectName("InlineTextEditor") + self._apply_style(style) + self.setStyleSheet( + "QTextEdit#InlineTextEditor {" + " background: #ffffff; color: #111111;" + " border: 1.5px solid #ff255f; border-radius: 2px;" + " padding: 2px; }" + ) + self.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) + self.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) + + def _apply_style(self, style: eo.TextStyle) -> None: + style = style.normalized() + font = QFont(_qt_font_family(style.font_family)) + font.setPointSizeF(max(1.0, style.font_size)) + font.setBold(style.bold) + font.setItalic(style.italic) + font.setUnderline(style.underline) + self.setFont(font) + self.setTextColor(QColor(style.color)) + if style.align == "center": + self.setAlignment(Qt.AlignmentFlag.AlignHCenter) + elif style.align == "right": + self.setAlignment(Qt.AlignmentFlag.AlignRight) + else: + self.setAlignment(Qt.AlignmentFlag.AlignLeft) + + def keyPressEvent(self, event): + if event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter) and ( + event.modifiers() & Qt.KeyboardModifier.ControlModifier + ): + self.committed.emit(self.toPlainText()) + event.accept() + return + if event.key() == Qt.Key.Key_Escape: + self.cancelled.emit() + event.accept() + return + super().keyPressEvent(event) + + +class EditObjectWidget(QWidget): + """Transparent selection/resize handle over a rendered PDF object.""" + + selected = Signal(str) + geometryCommitted = Signal(str, object) + editRequested = Signal(str) + + def __init__(self, controller, obj: eo.EditObject, page_rect, zoom: float, parent): + super().__init__(parent) + self.controller = controller + self.obj = obj + self.page_rect = page_rect + self.zoom = zoom + self._hover = False + self._selected = False + self._mode = None + self._handle = None + self._start_pos = QPoint() + self._start_rect = QRect() + self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True) + self.setMouseTracking(True) + self.setFocusPolicy(Qt.FocusPolicy.NoFocus) + self.setGeometry(_pdf_rect_to_label(obj.rect, page_rect, zoom)) + + def set_selected(self, selected: bool) -> None: + self._selected = selected + self.update() + + def set_geometry_from_object(self) -> None: + self.setGeometry(_pdf_rect_to_label(self.obj.rect, self.page_rect, self.zoom)) + + # -- painting ------------------------------------------------------ + + def paintEvent(self, event): + if not (self._selected or self._hover): + return + painter = QPainter(self) + painter.setRenderHint(QPainter.RenderHint.Antialiasing, True) + accent = QColor("#ff255f") + pen = QPen(accent, 1.4, Qt.PenStyle.DashLine) + painter.setPen(pen) + painter.drawRect(self.rect().adjusted(1, 1, -1, -1)) + if self._selected: + painter.setPen(QPen(QColor("#ffffff"), 1.0)) + painter.setBrush(accent) + for point in self._handle_points(): + painter.drawRect( + QRect( + point.x() - HANDLE // 2, + point.y() - HANDLE // 2, + HANDLE, + HANDLE, + ) + ) + painter.end() + + def _handle_points(self) -> list[QPoint]: + r = self.rect() + return [ + QPoint(r.left(), r.top()), + QPoint(r.center().x(), r.top()), + QPoint(r.right(), r.top()), + QPoint(r.left(), r.center().y()), + QPoint(r.right(), r.center().y()), + QPoint(r.left(), r.bottom()), + QPoint(r.center().x(), r.bottom()), + QPoint(r.right(), r.bottom()), + ] + + def _handle_at(self, pos: QPoint): + if not self._selected: + return None + for index, point in enumerate(self._handle_points()): + if (pos - point).manhattanLength() <= HANDLE + 4: + return index + return None + + # -- interaction --------------------------------------------------- + + def enterEvent(self, event): + self._hover = True + self.update() + super().enterEvent(event) + + def leaveEvent(self, event): + self._hover = False + self.update() + super().leaveEvent(event) + + def mousePressEvent(self, event): + if event.button() != Qt.MouseButton.LeftButton: + event.ignore() + return + self.selected.emit(self.obj.oid) + self._start_pos = event.position().toPoint() + self._start_rect = self.geometry() + self._handle = self._handle_at(self._start_pos) + self._mode = "resize" if self._handle is not None else "move" + event.accept() + + def mouseMoveEvent(self, event): + pos = event.position().toPoint() + if self._mode is None: + handle = self._handle_at(pos) + if handle is not None: + self.setCursor(self._cursor_for_handle(handle)) + elif self.obj.kind == eo.TEXT_KIND: + self.setCursor(Qt.CursorShape.IBeamCursor) + else: + self.setCursor(Qt.CursorShape.SizeAllCursor) + event.accept() + return + delta = pos - self._start_pos + rect = QRect(self._start_rect) + if self._mode == "move": + rect.translate(delta) + else: + rect = self._resized_rect(self._start_rect, self._handle, delta) + self.setGeometry(self._clamped_rect(rect)) + event.accept() + + def mouseReleaseEvent(self, event): + if self._mode is None: + event.ignore() + return + self._mode = None + self._handle = None + pdf_rect = _label_rect_to_pdf(self.geometry(), self.page_rect, self.zoom) + self.geometryCommitted.emit(self.obj.oid, pdf_rect) + event.accept() + + def mouseDoubleClickEvent(self, event): + if self.obj.kind == eo.TEXT_KIND and event.button() == Qt.MouseButton.LeftButton: + self.editRequested.emit(self.obj.oid) + event.accept() + return + super().mouseDoubleClickEvent(event) + + def wheelEvent(self, event): + event.ignore() + + def _resized_rect(self, start: QRect, handle, delta: QPoint) -> QRect: + rect = QRect(start) + left, top = rect.left(), rect.top() + right, bottom = rect.right(), rect.bottom() + if handle in (0, 3, 5): + left += delta.x() + if handle in (2, 4, 7): + right += delta.x() + if handle in (0, 1, 2): + top += delta.y() + if handle in (5, 6, 7): + bottom += delta.y() + if right - left < MIN_SIZE: + right = left + MIN_SIZE + if bottom - top < MIN_SIZE: + bottom = top + MIN_SIZE + rect = QRect(QPoint(left, top), QPoint(right, bottom)) + if self.obj.kind != eo.TEXT_KIND: + aspect = max(0.01, self._start_rect.width() / max(1, self._start_rect.height())) + if abs(rect.width() / max(1, rect.height()) - aspect) > 0.001: + height = max(MIN_SIZE, int(rect.width() / aspect)) + if handle in (0, 2): + rect.setTop(rect.bottom() - height) + else: + rect.setBottom(rect.top() + height) + return rect + + def _clamped_rect(self, rect: QRect) -> QRect: + bounds = self.parent().rect() + rect = rect.normalized() + if rect.left() < 0: + rect.moveLeft(0) + if rect.top() < 0: + rect.moveTop(0) + if rect.right() > bounds.right(): + rect.moveRight(bounds.right()) + if rect.bottom() > bounds.bottom(): + rect.moveBottom(bounds.bottom()) + return rect + + @staticmethod + def _cursor_for_handle(handle) -> Qt.CursorShape: + return { + 0: Qt.CursorShape.SizeFDiagCursor, + 1: Qt.CursorShape.SizeVerCursor, + 2: Qt.CursorShape.SizeBDiagCursor, + 3: Qt.CursorShape.SizeHorCursor, + 4: Qt.CursorShape.SizeHorCursor, + 5: Qt.CursorShape.SizeBDiagCursor, + 6: Qt.CursorShape.SizeVerCursor, + 7: Qt.CursorShape.SizeFDiagCursor, + }.get(handle, Qt.CursorShape.SizeAllCursor) + + +class EditController(QObject): + """Per-tab editing state for text, signatures and images.""" + + selectionChanged = Signal(object) + statusMessage = Signal(str) + dirtyChanged = Signal(bool) + toolChanged = Signal(object) + + def __init__(self, window, tab_id: int): + super().__init__(window) + self.window = window + self.tab_id = tab_id + self.doc = None + self.path = None + self.objects: list[eo.EditObject] = [] + self.history: list[list[eo.EditObject]] = [] + self.history_index = 0 + self.saved_index = 0 + self.tool: str | None = None + self.pending_kind: str | None = None + self.pending_png: bytes = b"" + self.pending_name = "" + self.selected_oid: str | None = None + self._overlays: dict[str, EditObjectWidget] = {} + self._labels_by_page: dict[int, QWidget] = {} + self._editor: TextEditOverlay | None = None + self._editing_oid: str | None = None + self._editing_original = "" + self._clipboard: eo.EditObject | None = None + self._active = False + + # -- lifecycle ----------------------------------------------------- + + def load(self, doc, path) -> None: + self.doc = doc + self.path = path + self.objects = eo.list_objects(doc) if doc is not None else [] + self.history = [[o.copy() for o in self.objects]] + self.history_index = 0 + self.saved_index = 0 + self.selected_oid = None + self.tool = None + self._active = False + self._detach_overlays() + + def mark_saved(self) -> None: + self.saved_index = self.history_index + self.dirtyChanged.emit(self.is_dirty()) + + def is_dirty(self) -> bool: + return self.history_index != self.saved_index + + def selected_object(self) -> eo.EditObject | None: + return self.object_by_oid(self.selected_oid) if self.selected_oid else None + + def object_by_oid(self, oid: str | None) -> eo.EditObject | None: + if not oid: + return None + for obj in self.objects: + if obj.oid == oid: + return obj + return None + + # -- tools --------------------------------------------------------- + + def set_tool(self, tool: str | None) -> None: + if tool not in (None, "fill", "text", "sign", "image"): + return + if tool != self.tool: + self._finish_text_edit() + self.tool = tool + self._active = tool is not None + if tool is None: + self.pending_kind = None + self.pending_png = b"" + self.pending_name = "" + self._set_page_cursors() + self.toolChanged.emit(tool) + if self._active: + self.refresh_visible() + else: + self._detach_overlays() + if tool != "fill": + self.select(None) + + def set_pending_image(self, kind: str, png_bytes: bytes, name: str = "") -> None: + self.pending_kind = kind + self.pending_png = png_bytes + self.pending_name = name + self.set_tool("sign" if kind == eo.SIGNATURE_KIND else "image") + + def refresh_visible(self) -> None: + if ( + not self._active + or self.doc is None + or getattr(self.doc, "is_closed", False) + ): + self._detach_overlays() + return + labels = list(getattr(self.window, "_continuous_pages", []) or []) + for page_index, label in enumerate(labels): + if not self._is_label_rendered(label): + self.detach_page(label) + continue + zoom = getattr(self.window, "_continuous_layout_zoom", None) + if zoom: + self.attach_page(label, page_index, zoom) + if not getattr(self.window, "_continuous_mode", True): + label = getattr(self.window, "page_label", None) + if label is not None and self.doc is not None: + zoom = getattr(self.window, "current_render_zoom", 1.0) + self.attach_page(label, self._current_page(), zoom) + + def _is_label_rendered(self, label) -> bool: + try: + return bool(label.pixmap()) + except Exception: + return True + + def _current_page(self) -> int: + return int(getattr(self.window, "current_page", 0) or 0) + + def _set_page_cursors(self) -> None: + cursor = Qt.CursorShape.CrossCursor if self.tool else Qt.CursorShape.ArrowCursor + for label in getattr(self.window, "_continuous_pages", []) or []: + label.setCursor(cursor) + page_label = getattr(self.window, "page_label", None) + if page_label is not None: + page_label.setCursor(cursor) + + # -- overlays ------------------------------------------------------ + + def attach_page(self, label, page_index: int, zoom: float) -> None: + if ( + not self._active + or self.doc is None + or getattr(self.doc, "is_closed", False) + ): + return + self._labels_by_page[page_index] = label + for oid, widget in list(self._overlays.items()): + if widget.parent() is label and self.object_by_oid(oid) is None: + widget.setParent(None) + widget.deleteLater() + self._overlays.pop(oid, None) + try: + page = self.doc[page_index] + except Exception: + return + for obj in self.objects: + if obj.page_index != page_index: + continue + widget = self._overlays.get(obj.oid) + if widget is None or widget.parent() is not label: + if widget is not None: + widget.setParent(None) + widget.deleteLater() + widget = EditObjectWidget(self, obj, page.rect, zoom, label) + widget.selected.connect(self.select) + widget.geometryCommitted.connect(self._on_geometry_committed) + widget.editRequested.connect(self.begin_text_edit) + self._overlays[obj.oid] = widget + widget.obj = obj + widget.page_rect = page.rect + widget.zoom = zoom + widget.setGeometry(_pdf_rect_to_label(obj.rect, page.rect, zoom)) + widget.show() + widget.set_selected(obj.oid == self.selected_oid) + + def detach_page(self, label) -> None: + for oid, widget in list(self._overlays.items()): + if widget.parent() is label: + widget.setParent(None) + widget.deleteLater() + self._overlays.pop(oid, None) + + def detach_all(self) -> None: + # Never lose an in-progress text edit when the layout is rebuilt, + # the tab changes or the document is saved. + if self._editor is not None: + try: + self._finish_text_edit() + except Exception: + pass + self._close_editor() + self._detach_overlays() + + def _detach_overlays(self) -> None: + for widget in list(self._overlays.values()): + widget.setParent(None) + widget.deleteLater() + self._overlays.clear() + self._labels_by_page.clear() + + def _refresh_selection_overlays(self) -> None: + for oid, widget in self._overlays.items(): + widget.set_selected(oid == self.selected_oid) + + def select(self, oid: str | None) -> None: + if self._editor is not None and oid != self._editing_oid: + self._finish_text_edit() + self.selected_oid = oid + self._refresh_selection_overlays() + obj = self.object_by_oid(oid) + self.selectionChanged.emit(obj) + + # -- input --------------------------------------------------------- + + def handle_page_click(self, page_index: int, label, pos, zoom: float) -> bool: + if not self._active or self.doc is None: + return False + if self.tool == "fill": + return False + try: + page = self.doc[page_index] + except Exception: + return True + if not eo.page_allows_editing(page): + self.statusMessage.emit("Editing rotated pages is not supported in this release.") + return True + if not self._ensure_editable(): + return True + pdf_x = page.rect.x0 + (pos.x() - CONTENT_OFFSET) / max(0.001, zoom) + pdf_y = page.rect.y0 + (pos.y() - CONTENT_OFFSET) / max(0.001, zoom) + if self.tool == "text": + self.add_text_at(page_index, pdf_x, pdf_y, label, zoom) + return True + if self.tool in ("sign", "image") and self.pending_png: + self.add_image_at(page_index, pdf_x, pdf_y, label, zoom) + return True + return False + + def add_text_at(self, page_index: int, x: float, y: float, label, zoom: float) -> None: + if self.doc is None: + return + page = self.doc[page_index] + width = min(220.0, max(80.0, page.rect.width - (x - page.rect.x0) - 8)) + rect = (x, y, x + width, min(page.rect.y1 - 4, y + 30)) + obj = eo.EditObject( + oid=uuid.uuid4().hex, + kind=eo.TEXT_KIND, + page_index=page_index, + rect=rect, + text="", + style=eo.TextStyle(), + z=self._next_z(), + ) + try: + obj = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not add text: {exc}") + return + self.objects.append(obj) + self._record() + self.select(obj.oid) + self.window.render_page() + QTimer.singleShot(0, lambda: self.begin_text_edit(obj.oid)) + self.statusMessage.emit( + "Text added. Drag or resize it, or use the formatting bar." + ) + self.tool = None + self.pending_kind = None + self.toolChanged.emit(None) + self._set_page_cursors() + + def add_image_at(self, page_index: int, x: float, y: float, label, zoom: float) -> None: + if self.doc is None or not self.pending_png: + return + page = self.doc[page_index] + width = min(180.0, max(60.0, page.rect.width - (x - page.rect.x0) - 8)) + height = eo.aspect_size(width, self.pending_png) + if y + height > page.rect.y1 - 4: + y = max(page.rect.y0 + 4, page.rect.y1 - height - 4) + rect = (x, y, x + width, y + height) + obj = eo.EditObject( + oid=uuid.uuid4().hex, + kind=self.pending_kind or eo.IMAGE_KIND, + page_index=page_index, + rect=rect, + image_png=self.pending_png, + name=self.pending_name, + z=self._next_z(), + ) + try: + obj = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not place image: {exc}") + return + self.objects.append(obj) + self._record() + self.select(obj.oid) + self.window.render_page() + self.statusMessage.emit( + "Signature placed." + if obj.kind == eo.SIGNATURE_KIND + else "Image placed." + ) + self.tool = None + self.pending_kind = None + self.pending_png = b"" + self.pending_name = "" + self.toolChanged.emit(None) + self._set_page_cursors() + + def _on_geometry_committed(self, oid: str, pdf_rect) -> None: + obj = self.object_by_oid(oid) + if obj is None or self.doc is None: + return + obj.rect = tuple(pdf_rect) + try: + eo.remove_object(self.doc, obj) + refreshed = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not update object: {exc}") + return + self._replace_object(refreshed) + self._record() + self.window.render_page() + QTimer.singleShot(0, self.refresh_visible) + + # -- text editing -------------------------------------------------- + + def begin_text_edit(self, oid: str) -> None: + obj = self.object_by_oid(oid) + if obj is None or obj.kind != eo.TEXT_KIND or self.doc is None: + return + if self._editor is not None: + self._finish_text_edit() + page_index = obj.page_index + label = self._labels_by_page.get(page_index) + if label is None: + labels = getattr(self.window, "_continuous_pages", []) or [] + if getattr(self.window, "_continuous_mode", True) and 0 <= page_index < len(labels): + label = labels[page_index] + else: + label = getattr(self.window, "page_label", None) + if label is None: + self.statusMessage.emit("Scroll to the text object and try again.") + return + try: + page = self.doc[page_index] + except Exception: + return + zoom = ( + getattr(self.window, "_continuous_layout_zoom", None) + or getattr(self.window, "current_render_zoom", 1.0) + ) + rect = _pdf_rect_to_label(obj.rect, page.rect, zoom) + editor = TextEditOverlay(obj.text, obj.style, label) + editor.setGeometry(rect.adjusted(-4, -4, 4, 4)) + editor.committed.connect(lambda text, o=obj.oid: self._commit_text_edit(o, text)) + editor.cancelled.connect(self._cancel_text_edit) + editor.show() + editor.setFocus() + editor.selectAll() + self._editor = editor + self._editing_oid = obj.oid + self._editing_original = obj.text + self.selectionChanged.emit(obj) + + def _auto_grow_text(self, obj: eo.EditObject, text: str) -> None: + """Grow a text box vertically so multiline content is not clipped.""" + if self.doc is None or obj.kind != eo.TEXT_KIND: + return + try: + font = QFont(_qt_font_family(obj.style.font_family)) + font.setPointSizeF(max(1.0, float(obj.style.font_size))) + metrics = QFontMetrics(font) + x0, y0, x1, y1 = obj.rect + width = max(24.0, x1 - x0) + lines = 0 + for paragraph in (text or " ").split("\n"): + advance = metrics.horizontalAdvance(paragraph or " ") + lines += max(1, int(advance / width) + 1) + needed = max(28.0, lines * (metrics.height() + 2) + 8) + if (y1 - y0) < needed: + page = self.doc[obj.page_index] + obj.rect = ( + x0, + y0, + x1, + min(page.rect.y1 - 2, y0 + needed), + ) + except Exception: + pass + + def _commit_text_edit(self, oid: str, text: str) -> None: + obj = self.object_by_oid(oid) + if obj is None or self.doc is None: + self._close_editor() + return + if not text.strip() and not obj.text.strip(): + self._delete_object(obj) + self._close_editor() + return + self._auto_grow_text(obj, text) + self._apply_text(obj, text=text) + self._close_editor() + self.selectionChanged.emit(self.selected_object()) + + def _cancel_text_edit(self) -> None: + obj = self.object_by_oid(self._editing_oid) if self._editing_oid else None + if obj is not None and not obj.text.strip() and not self._editing_original.strip(): + self._delete_object(obj) + self._close_editor() + self.selectionChanged.emit(self.selected_object()) + + def _finish_text_edit(self) -> None: + if self._editor is not None: + self._commit_text_edit(self._editing_oid or "", self._editor.toPlainText()) + + def _close_editor(self) -> None: + if self._editor is not None: + self._editor.hide() + self._editor.setParent(None) + self._editor.deleteLater() + self._editor = None + self._editing_oid = None + self._editing_original = "" + + def _apply_text(self, obj: eo.EditObject, text: str | None = None, + style: eo.TextStyle | None = None, rotation: int | None = None) -> None: + if self.doc is None: + return + if text is not None: + obj.text = text + if style is not None: + obj.style = style.normalized() + if rotation is not None: + obj.rotation = int(rotation) % 360 + try: + eo.remove_object(self.doc, obj) + refreshed = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not update text: {exc}") + return + self._replace_object(refreshed) + self._record() + self.window.render_page() + QTimer.singleShot(0, self._refresh_after_change) + + def apply_style(self, style: eo.TextStyle) -> None: + obj = self.selected_object() + if obj is None: + return + if obj.kind == eo.TEXT_KIND: + self._apply_text(obj, style=style) + if self._editor is not None: + self._editor._apply_style(style) + else: + self.statusMessage.emit("Formatting applies to text objects.") + + def rotate_selected(self, delta: int = 90) -> None: + obj = self.selected_object() + if obj is None or self.doc is None: + return + if not self._ensure_editable(): + return + if obj.kind == eo.TEXT_KIND: + new_rotation = (obj.rotation + int(delta)) % 360 + if int(delta) % 180 != 0: + x0, y0, x1, y1 = obj.rect + cx, cy = (x0 + x1) / 2, (y0 + y1) / 2 + width, height = x1 - x0, y1 - y0 + obj.rect = ( + cx - height / 2, + cy - width / 2, + cx + height / 2, + cy + width / 2, + ) + self._apply_text(obj, rotation=new_rotation) + return + try: + rotated = eo.rotated_png(obj.image_png, delta) + except Exception as exc: + self.statusMessage.emit(f"Could not rotate image: {exc}") + return + old = obj.rect + cx = (old[0] + old[2]) / 2 + cy = (old[1] + old[3]) / 2 + width = max(old[2] - old[0], old[3] - old[1]) + height = eo.aspect_size(width, rotated) + obj.image_png = rotated + obj.rect = (cx - width / 2, cy - height / 2, cx + width / 2, cy + height / 2) + obj.rotation = (obj.rotation + int(delta)) % 360 + try: + eo.remove_object(self.doc, obj) + refreshed = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not rotate image: {exc}") + return + self._replace_object(refreshed) + self._record() + self.window.render_page() + QTimer.singleShot(0, self._refresh_after_change) + + # -- object operations --------------------------------------------- + + def delete_selected(self) -> None: + obj = self.selected_object() + if obj is not None: + self._delete_object(obj) + + def _delete_object(self, obj: eo.EditObject) -> None: + if self.doc is None: + return + try: + eo.remove_object(self.doc, obj) + except Exception: + pass + self.objects = [o for o in self.objects if o.oid != obj.oid] + self.selected_oid = None + self._record() + self.selectionChanged.emit(None) + self.window.render_page() + QTimer.singleShot(0, self.refresh_visible) + + def duplicate_selected(self) -> None: + obj = self.selected_object() + if obj is None or self.doc is None: + return + if not self._ensure_editable(): + return + duplicate = obj.copy() + duplicate.oid = uuid.uuid4().hex + duplicate.rect = ( + obj.rect[0] + 12, + obj.rect[1] + 12, + obj.rect[2] + 12, + obj.rect[3] + 12, + ) + duplicate.z = self._next_z() + try: + duplicate = eo.add_object(self.doc, duplicate) + except Exception as exc: + self.statusMessage.emit(f"Could not duplicate: {exc}") + return + self.objects.append(duplicate) + self._record() + self.select(duplicate.oid) + self.window.render_page() + QTimer.singleShot(0, self._refresh_after_change) + + def copy_selected(self) -> bool: + obj = self.selected_object() + if obj is None: + return False + self._clipboard = obj.copy() + self.statusMessage.emit("Object copied.") + return True + + def paste(self) -> bool: + if self._clipboard is None or self.doc is None: + return False + if not self._ensure_editable(): + return False + obj = self._clipboard.copy() + obj.oid = uuid.uuid4().hex + obj.page_index = self._current_page() + obj.rect = ( + obj.rect[0] + 16, + obj.rect[1] + 16, + obj.rect[2] + 16, + obj.rect[3] + 16, + ) + obj.z = self._next_z() + try: + obj = eo.add_object(self.doc, obj) + except Exception as exc: + self.statusMessage.emit(f"Could not paste: {exc}") + return False + self.objects.append(obj) + self._record() + self.select(obj.oid) + self.window.render_page() + QTimer.singleShot(0, self._refresh_after_change) + return True + + # -- undo / redo --------------------------------------------------- + + def undo(self) -> bool: + if self.history_index <= 0 or self.doc is None: + return False + self.history_index -= 1 + self._apply_history_state() + return True + + def redo(self) -> bool: + if self.history_index >= len(self.history) - 1 or self.doc is None: + return False + self.history_index += 1 + self._apply_history_state() + return True + + def _record(self) -> None: + self.history = self.history[: self.history_index + 1] + self.history.append([o.copy() for o in self.objects]) + self.history_index = len(self.history) - 1 + self.dirtyChanged.emit(self.is_dirty()) + + def _apply_history_state(self) -> None: + if self.doc is None: + return + state = self.history[self.history_index] + try: + eo.apply_objects(self.doc, state) + except Exception as exc: + self.statusMessage.emit(f"Could not restore edit state: {exc}") + return + self.objects = eo.list_objects(self.doc) + self.selected_oid = None + self._close_editor() + self.selectionChanged.emit(None) + self.dirtyChanged.emit(self.is_dirty()) + self.window.render_page() + QTimer.singleShot(0, self._refresh_after_change) + + # -- helpers ------------------------------------------------------- + + def _refresh_after_change(self) -> None: + self.refresh_visible() + self._refresh_selection_overlays() + + def _replace_object(self, refreshed: eo.EditObject) -> None: + for index, obj in enumerate(self.objects): + if obj.oid == refreshed.oid: + self.objects[index] = refreshed + break + else: + self.objects.append(refreshed) + + def _next_z(self) -> int: + return max((o.z for o in self.objects), default=0) + 1 + + def _ensure_editable(self) -> bool: + if self.doc is None: + return False + encrypted = False + checker = getattr(self.window, "_current_document_encrypted", None) + if checker is not None: + try: + encrypted = bool(checker()) + except Exception: + encrypted = False + if not eo.document_allows_editing(self.doc, encrypted=encrypted): + self.statusMessage.emit( + "This document is read-only or encrypted and cannot be edited." + ) + return False + checker = getattr(self.window, "_confirm_edit_on_signed", None) + if checker is not None and not checker(): + return False + return True + + +# --------------------------------------------------------------------------- +# Signature creation +# --------------------------------------------------------------------------- + + +class SignatureCanvas(QWidget): + """Smooth freehand signature canvas.""" + + def __init__(self, parent=None): + super().__init__(parent) + self.setMinimumHeight(180) + self.setAttribute(Qt.WidgetAttribute.WA_AcceptTouchEvents, True) + self._strokes: list[list[QPointF]] = [] + self._current: list[QPointF] = [] + + def clear(self) -> None: + self._strokes = [] + self._current = [] + self.update() + + def has_content(self) -> bool: + return any(len(stroke) > 1 for stroke in self._strokes) or len(self._current) > 1 + + def paintEvent(self, event): + painter = QPainter(self) + painter.fillRect(self.rect(), QColor("#ffffff")) + painter.setRenderHint(QPainter.RenderHint.Antialiasing, True) + painter.setPen(QPen(QColor("#dfe0e4"), 1, Qt.PenStyle.DashLine)) + baseline = int(self.height() * 0.78) + painter.drawLine(12, baseline, self.width() - 12, baseline) + pen = QPen(QColor("#111111"), 2.6, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin) + painter.setPen(pen) + for stroke in self._strokes + ([self._current] if self._current else []): + if len(stroke) == 1: + painter.drawPoint(stroke[0]) + continue + path = self._stroke_path(stroke) + painter.drawPath(path) + painter.end() + + def _stroke_path(self, points: list[QPointF]): + from PySide6.QtGui import QPainterPath + + path = QPainterPath(points[0]) + for index in range(1, len(points)): + mid = (points[index - 1] + points[index]) / 2.0 + path.quadTo(points[index - 1], mid) + path.lineTo(points[-1]) + return path + + def mousePressEvent(self, event): + if event.button() == Qt.MouseButton.LeftButton: + self._current = [event.position()] + self.update() + event.accept() + + def mouseMoveEvent(self, event): + if self._current: + self._current.append(event.position()) + self.update() + event.accept() + + def mouseReleaseEvent(self, event): + if self._current: + if len(self._current) > 1: + self._strokes.append(self._current) + self._current = [] + self.update() + event.accept() + + def to_png(self) -> bytes: + scale = 3 + image = QImage( + max(1, self.width()) * scale, + max(1, self.height()) * scale, + QImage.Format.Format_ARGB32_Premultiplied, + ) + image.fill(Qt.GlobalColor.transparent) + painter = QPainter(image) + painter.setRenderHint(QPainter.RenderHint.Antialiasing, True) + painter.scale(scale, scale) + painter.setPen(QPen(QColor("#111111"), 2.6, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin)) + for stroke in self._strokes: + if len(stroke) == 1: + painter.drawPoint(stroke[0]) + else: + painter.drawPath(self._stroke_path(stroke)) + painter.end() + buffer = QBuffer() + buffer.open(QBuffer.OpenModeFlag.WriteOnly) + image.save(buffer, "PNG") + return bytes(buffer.data()) + + +def _image_to_png(image: QImage) -> bytes: + buffer = QBuffer() + buffer.open(QBuffer.OpenModeFlag.WriteOnly) + image.save(buffer, "PNG") + return bytes(buffer.data()) + + +def _typed_signature_png(name: str, family: str) -> bytes: + font = QFont(family) + font.setPointSize(42) + font.setItalic(True) + metrics = QFontMetrics(font) + width = max(320, metrics.horizontalAdvance(name) + 80) + height = max(120, metrics.height() + 60) + image = QImage(width, height, QImage.Format.Format_ARGB32_Premultiplied) + image.fill(Qt.GlobalColor.transparent) + painter = QPainter(image) + painter.setRenderHint(QPainter.RenderHint.Antialiasing, True) + painter.setFont(font) + painter.setPen(QColor("#111111")) + painter.drawText(image.rect(), Qt.AlignmentFlag.AlignCenter, name) + painter.end() + return _image_to_png(image) + + +class SignatureDialog(QDialog): + """Draw, type or import a visual signature; optionally save it locally.""" + + def __init__(self, store: ss.SignatureStore, parent=None): + super().__init__(parent) + self.setWindowTitle("Create Signature") + self.resize(620, 460) + self.store = store + self.result_png: bytes = b"" + self.result_name: str = "" + self.result_kind: str = "drawn" + self._imported: QImage | None = None + + layout = QVBoxLayout(self) + self.tabs = QTabWidget() + layout.addWidget(self.tabs, 1) + + # Draw + self.canvas = SignatureCanvas() + draw_tab = QWidget() + draw_layout = QVBoxLayout(draw_tab) + draw_layout.addWidget(QLabel("Draw your signature with a mouse, trackpad, pen or touchscreen.")) + draw_layout.addWidget(self.canvas, 1) + clear_btn = QPushButton("Clear") + clear_btn.clicked.connect(self.canvas.clear) + draw_layout.addWidget(clear_btn, 0, Qt.AlignmentFlag.AlignLeft) + self.tabs.addTab(draw_tab, "Draw") + + # Type + type_tab = QWidget() + type_layout = QFormLayout(type_tab) + self.type_name = QLineEdit() + self.type_name.setPlaceholderText("Your name") + self.type_name.textChanged.connect(self._update_typed_preview) + self.type_font = QComboBox() + for family in self._signature_fonts(): + self.type_font.addItem(family) + self.type_font.currentTextChanged.connect(self._update_typed_preview) + self.type_preview = QLabel("Preview") + self.type_preview.setAlignment(Qt.AlignmentFlag.AlignCenter) + self.type_preview.setMinimumHeight(140) + self.type_preview.setStyleSheet("background:#ffffff; border:1px solid #dfe0e4;") + type_layout.addRow("Name", self.type_name) + type_layout.addRow("Style", self.type_font) + type_layout.addRow(self.type_preview) + self.tabs.addTab(type_tab, "Type") + + # Import + import_tab = QWidget() + import_layout = QVBoxLayout(import_tab) + choose_btn = QPushButton("Choose Image…") + choose_btn.clicked.connect(self._choose_import) + import_layout.addWidget(choose_btn, 0, Qt.AlignmentFlag.AlignLeft) + self.import_preview = QLabel("PNG, JPEG, BMP or WebP") + self.import_preview.setAlignment(Qt.AlignmentFlag.AlignCenter) + self.import_preview.setMinimumHeight(140) + self.import_preview.setStyleSheet("background:#ffffff; border:1px solid #dfe0e4;") + import_layout.addWidget(self.import_preview, 1) + self.tabs.addTab(import_tab, "Import") + + # Saved + saved_tab = QWidget() + saved_layout = QVBoxLayout(saved_tab) + self.saved_list = QListWidget() + self._reload_saved() + saved_layout.addWidget(self.saved_list, 1) + saved_buttons = QHBoxLayout() + use_saved = QPushButton("Use Selected") + use_saved.clicked.connect(self._use_saved) + delete_saved = QPushButton("Delete Selected") + delete_saved.clicked.connect(self._delete_saved) + saved_buttons.addWidget(use_saved) + saved_buttons.addWidget(delete_saved) + saved_buttons.addStretch(1) + saved_layout.addLayout(saved_buttons) + self.tabs.addTab(saved_tab, "Saved") + + self.save_checkbox = QCheckBox("Save to my local signature library") + self.save_checkbox.setChecked(False) + layout.addWidget(self.save_checkbox) + + buttons = QDialogButtonBox( + QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel + ) + buttons.accepted.connect(self._accept) + buttons.rejected.connect(self.reject) + layout.addWidget(buttons) + self._update_typed_preview() + + def _signature_fonts(self) -> list[str]: + preferred = [ + "Segoe Script", + "Brush Script MT", + "Lucida Handwriting", + "Gabriola", + "Freestyle Script", + "Kunstler Script", + "Comic Sans MS", + ] + available = set(QFontDatabase.families()) + fonts = [name for name in preferred if name in available] + for name in sorted(available): + if name not in fonts and len(fonts) < 12: + fonts.append(name) + return fonts or ["Sans Serif"] + + def _update_typed_preview(self) -> None: + name = self.type_name.text().strip() + if not name: + self.type_preview.setText("Preview") + return + family = self.type_font.currentText() or "Sans Serif" + png = _typed_signature_png(name, family) + image = QImage.fromData(png, "PNG") + self.type_preview.setPixmap(QPixmap.fromImage(image).scaled( + 440, 130, Qt.AspectRatioMode.KeepAspectRatio, Qt.TransformationMode.SmoothTransformation + )) + + def _choose_import(self) -> None: + path, _ = QFileDialog.getOpenFileName( + self, + "Choose Signature Image", + str(Path.home()), + "Images (*.png *.jpg *.jpeg *.bmp *.webp *.gif)", + ) + if not path: + return + image = QImage(path) + if image.isNull(): + QMessageBox.warning(self, "Signature", "That image could not be read.") + return + self._imported = image.convertToFormat(QImage.Format.Format_ARGB32_Premultiplied) + self.import_preview.setPixmap(QPixmap.fromImage(self._imported).scaled( + 440, 150, Qt.AspectRatioMode.KeepAspectRatio, Qt.TransformationMode.SmoothTransformation + )) + + def _reload_saved(self) -> None: + self.saved_list.clear() + for entry in self.store.list(): + item = QListWidgetItem(f"{entry.name} · {entry.kind}") + item.setData(Qt.ItemDataRole.UserRole, entry.id) + self.saved_list.addItem(item) + + def _use_saved(self) -> None: + item = self.saved_list.currentItem() + if item is None: + return + entry_id = item.data(Qt.ItemDataRole.UserRole) + try: + png = self.store.load(entry_id) + except Exception as exc: + QMessageBox.warning(self, "Signature", f"Could not load signature: {exc}") + return + self.result_png = png + self.result_name = item.text().split(" · ")[0] + self.result_kind = "saved" + self.accept() + + def _delete_saved(self) -> None: + item = self.saved_list.currentItem() + if item is None: + return + entry_id = item.data(Qt.ItemDataRole.UserRole) + self.store.delete(entry_id) + self._reload_saved() + + def _accept(self) -> None: + index = self.tabs.currentIndex() + if index == 0: + if not self.canvas.has_content(): + QMessageBox.information(self, "Signature", "Draw a signature first.") + return + png = self.canvas.to_png() + kind = "drawn" + name = "Drawn signature" + elif index == 1: + name = self.type_name.text().strip() + if not name: + QMessageBox.information(self, "Signature", "Enter a name to type.") + return + png = _typed_signature_png(name, self.type_font.currentText() or "Sans Serif") + kind = "typed" + elif index == 2: + if self._imported is None: + QMessageBox.information(self, "Signature", "Choose an image first.") + return + png = _image_to_png(self._imported) + kind = "imported" + name = "Imported signature" + else: + return + if self.save_checkbox.isChecked(): + try: + self.store.save(name, png, kind) + except Exception as exc: + QMessageBox.warning(self, "Signature", f"Could not save signature: {exc}") + self.result_png = png + self.result_name = name + self.result_kind = kind + self.accept() diff --git a/pdfreader_lib/edit_objects.py b/pdfreader_lib/edit_objects.py new file mode 100644 index 0000000..c3476b3 --- /dev/null +++ b/pdfreader_lib/edit_objects.py @@ -0,0 +1,640 @@ +"""Editable PDF objects: text, signatures and images. + +This module is deliberately Qt-free. It owns the on-disk representation of +OpenReader-created objects and the document-level operations needed to add, +update, remove, undo and flatten them. + +Persistence strategy +-------------------- +* **Text** is stored as a native ``FreeText`` annotation. The text, style, + rotation and object id are also mirrored into a custom ``OpenReaderData`` + string key on the annotation xref, so OpenReader can find and re-edit its + own objects after the file is saved and reopened. FreeText keeps the text + selectable and searchable in other PDF viewers. +* **Signatures and images** are stored as image XObjects placed in the page + content by ``Page.insert_image``. The object metadata lives in a custom + ``OpenReaderData`` key on the image xref. Images are reinserted when moved, + resized, rotated or duplicated. +* Nothing here is temporary: every object is written into the PDF by the + caller's save. ``export_flattened`` uses PyMuPDF's ``Document.bake`` to + convert annotations and widgets into page content on a copy, leaving the + original document untouched. + +All coordinates are PDF points in the page's unrotated coordinate space. +Pages with a non-zero ``/Rotate`` are rejected for editing by the GUI. +""" + +from __future__ import annotations + +import base64 +import copy +import html +import io +import json +import os +import tempfile +import uuid +from dataclasses import asdict, dataclass, field +from pathlib import Path +from typing import Iterable + +import fitz + +META_KEY = "OpenReaderData" +TEXT_KIND = "text" +SIGNATURE_KIND = "signature" +IMAGE_KIND = "image" +EDITABLE_KINDS = (TEXT_KIND, SIGNATURE_KIND, IMAGE_KIND) + +# Curated PDF Base-14 families. These are embedded by every PDF viewer and +# keep user-added text selectable. The label is what the UI shows. +TEXT_FONTS: tuple[tuple[str, str], ...] = ( + ("Helvetica", "Helvetica"), + ("Times New Roman", "Times-Roman"), + ("Courier New", "Courier"), +) +_FONT_ALIASES = { + "helvetica": "Helvetica", + "arial": "Helvetica", + "sans": "Helvetica", + "sans-serif": "Helvetica", + "times": "Times-Roman", + "times new roman": "Times-Roman", + "serif": "Times-Roman", + "courier": "Courier", + "courier new": "Courier", + "mono": "Courier", + "monospace": "Courier", +} +_FONT_FILES = { + "Helvetica": ("helv", "hebo", "heit", "hebi"), + "Times-Roman": ("tiro", "tibo", "tiit", "tibi"), + "Courier": ("cour", "cobo", "coit", "cobi"), +} + + +def normalize_font(family: str) -> str: + key = (family or "").strip().lower() + if key in _FONT_ALIASES: + return _FONT_ALIASES[key] + for label, pdf_name in TEXT_FONTS: + if key == label.lower() or key == pdf_name.lower(): + return pdf_name + return "Helvetica" + + +def _clamp_color(value: str) -> str: + value = (value or "#000000").strip() + if len(value) == 7 and value.startswith("#"): + try: + int(value[1:], 16) + return value.lower() + except ValueError: + pass + return "#000000" + + +def _rgb(hex_color: str) -> tuple[float, float, float]: + color = _clamp_color(hex_color) + return ( + int(color[1:3], 16) / 255.0, + int(color[3:5], 16) / 255.0, + int(color[5:7], 16) / 255.0, + ) + + +@dataclass +class TextStyle: + font_family: str = "Helvetica" + font_size: float = 14.0 + color: str = "#000000" + bold: bool = False + italic: bool = False + underline: bool = False + align: str = "left" + + def normalized(self) -> "TextStyle": + align = self.align if self.align in ("left", "center", "right") else "left" + return TextStyle( + font_family=normalize_font(self.font_family), + font_size=max(4.0, min(200.0, float(self.font_size or 14.0))), + color=_clamp_color(self.color), + bold=bool(self.bold), + italic=bool(self.italic), + underline=bool(self.underline), + align=align, + ) + + def to_dict(self) -> dict: + return asdict(self.normalized()) + + @classmethod + def from_dict(cls, data: dict | None) -> "TextStyle": + data = data or {} + return cls( + font_family=normalize_font(str(data.get("font_family", "Helvetica"))), + font_size=float(data.get("font_size", 14.0) or 14.0), + color=str(data.get("color", "#000000") or "#000000"), + bold=bool(data.get("bold", False)), + italic=bool(data.get("italic", False)), + underline=bool(data.get("underline", False)), + align=str(data.get("align", "left") or "left"), + ).normalized() + + +@dataclass +class EditObject: + oid: str + kind: str + page_index: int + rect: tuple[float, float, float, float] + rotation: int = 0 + text: str = "" + style: TextStyle = field(default_factory=TextStyle) + image_png: bytes = b"" + name: str = "" + z: int = 0 + xref: int = 0 # image XObject xref (runtime) + annot_xref: int = 0 # FreeText annotation xref (runtime) + + def normalized(self) -> "EditObject": + x0, y0, x1, y1 = (float(v) for v in self.rect) + if x1 < x0: + x0, x1 = x1, x0 + if y1 < y0: + y0, y1 = y1, y0 + return EditObject( + oid=self.oid or uuid.uuid4().hex, + kind=self.kind, + page_index=max(0, int(self.page_index)), + rect=(x0, y0, max(x0 + 1.0, x1), max(y0 + 1.0, y1)), + rotation=int(self.rotation or 0) % 360, + text=self.text or "", + style=self.style.normalized(), + image_png=self.image_png or b"", + name=self.name or "", + z=int(self.z or 0), + xref=int(self.xref or 0), + annot_xref=int(self.annot_xref or 0), + ) + + def to_meta(self) -> dict: + obj = self.normalized() + return { + "oid": obj.oid, + "kind": obj.kind, + "page": obj.page_index, + "rect": [round(v, 4) for v in obj.rect], + "rotation": obj.rotation, + "text": obj.text, + "style": obj.style.to_dict(), + "name": obj.name, + "z": obj.z, + } + + @classmethod + def from_meta(cls, meta: dict, *, xref: int = 0, annot_xref: int = 0, + image_png: bytes = b"") -> "EditObject": + rect = meta.get("rect") or [0, 0, 100, 30] + return cls( + oid=str(meta.get("oid") or uuid.uuid4().hex), + kind=str(meta.get("kind") or TEXT_KIND), + page_index=int(meta.get("page", 0) or 0), + rect=tuple(float(v) for v in rect[:4]), + rotation=int(meta.get("rotation", 0) or 0), + text=str(meta.get("text", "") or ""), + style=TextStyle.from_dict(meta.get("style")), + image_png=image_png, + name=str(meta.get("name", "") or ""), + z=int(meta.get("z", 0) or 0), + xref=xref, + annot_xref=annot_xref, + ).normalized() + + def copy(self) -> "EditObject": + return copy.deepcopy(self) + + +# --------------------------------------------------------------------------- +# Metadata on PDF xrefs +# --------------------------------------------------------------------------- + + +def _meta_text(meta: dict) -> str: + return fitz.get_pdf_str(json.dumps(meta, ensure_ascii=False)) + + +def set_object_meta(doc: fitz.Document, xref: int, meta: dict) -> None: + doc.xref_set_key(xref, META_KEY, _meta_text(meta)) + + +def get_object_meta(doc: fitz.Document, xref: int) -> dict | None: + try: + kind, value = doc.xref_get_key(xref, META_KEY) + except Exception: + return None + if kind != "string" or not value: + return None + try: + meta = json.loads(value) + except (TypeError, ValueError): + return None + if not isinstance(meta, dict) or meta.get("kind") not in EDITABLE_KINDS: + return None + return meta + + +# --------------------------------------------------------------------------- +# FreeText styling +# --------------------------------------------------------------------------- + + +def _fontname(style: TextStyle) -> str: + family = normalize_font(style.font_family) + names = _FONT_FILES.get(family, _FONT_FILES["Helvetica"]) + if style.bold and style.italic: + return names[3] + if style.bold: + return names[1] + if style.italic: + return names[2] + return names[0] + + +def _align_value(style: TextStyle) -> int: + return {"left": 0, "center": 1, "right": 2}.get(style.align, 0) + + +def _style_css(style: TextStyle) -> str: + style = style.normalized() + parts = [ + f"font-family:{style.font_family}", + f"font-size:{style.font_size:g}px", + f"color:{style.color}", + f"text-align:{style.align}", + ] + if style.bold: + parts.append("font-weight:bold") + if style.italic: + parts.append("font-style:italic") + if style.underline: + parts.append("text-decoration:underline") + return ";".join(parts) + + +def _html_text(text: str) -> str: + body = html.escape(text or " ").replace("\r\n", "\n").replace("\r", "\n") + return body.replace("\n", "
") or " " + + +def _add_text(doc: fitz.Document, obj: EditObject) -> EditObject: + obj = obj.normalized() + page = doc[obj.page_index] + annot = page.add_freetext_annot( + fitz.Rect(*obj.rect), + _html_text(obj.text), + fontsize=obj.style.font_size, + fontname=_fontname(obj.style), + text_color=_rgb(obj.style.color), + border_width=0, + align=_align_value(obj.style), + rotate=obj.rotation, + richtext=True, + style=_style_css(obj.style), + ) + try: + annot.set_info(title="OpenReader", subject="OpenReader editable text") + except Exception: + pass + annot.update() + set_object_meta(doc, annot.xref, obj.to_meta()) + obj.annot_xref = annot.xref + return obj + + +def _unique_png(png_bytes: bytes, oid: str) -> bytes: + """Return PNG bytes with a unique metadata chunk. + + PyMuPDF reuses an existing image XObject for byte-identical images. Two + OpenReader image objects with their own metadata must not share one + XObject, so each placement carries a small private tEXt chunk. + """ + try: + from PIL import Image, PngImagePlugin + + with Image.open(io.BytesIO(png_bytes)) as image: + info = PngImagePlugin.PngInfo() + info.add_text("OpenReaderOID", oid) + buffer = io.BytesIO() + image.save(buffer, "PNG", pnginfo=info) + return buffer.getvalue() + except Exception: + return png_bytes + + +def _add_image(doc: fitz.Document, obj: EditObject) -> EditObject: + obj = obj.normalized() + if not obj.image_png: + raise ValueError("image object has no image data") + page = doc[obj.page_index] + xref = page.insert_image( + fitz.Rect(*obj.rect), + stream=_unique_png(obj.image_png, obj.oid), + overlay=True, + keep_proportion=False, + ) + set_object_meta(doc, xref, obj.to_meta()) + obj.xref = xref + return obj + + +def add_object(doc: fitz.Document, obj: EditObject) -> EditObject: + """Add an object to the document and return it with runtime xrefs set.""" + obj = obj.normalized() + if obj.kind == TEXT_KIND: + return _add_text(doc, obj) + if obj.kind in (SIGNATURE_KIND, IMAGE_KIND): + return _add_image(doc, obj) + raise ValueError(f"unsupported object kind: {obj.kind}") + + +# --------------------------------------------------------------------------- +# Discovery / deletion +# --------------------------------------------------------------------------- + + +def _image_bytes(doc: fitz.Document, xref: int) -> bytes: + try: + extracted = doc.extract_image(xref) + return extracted.get("image", b"") or b"" + except Exception: + return b"" + + +def _objects_on_page(doc: fitz.Document, page_index: int) -> list[EditObject]: + page = doc[page_index] + found: list[EditObject] = [] + seen: set[str] = set() + try: + annotations = list(page.annots() or []) + except Exception: + annotations = [] + for annot in annotations: + meta = get_object_meta(doc, annot.xref) + if meta and meta.get("kind") == TEXT_KIND: + obj = EditObject.from_meta(meta, annot_xref=annot.xref) + if obj.oid not in seen: + found.append(obj) + seen.add(obj.oid) + try: + images = page.get_images(full=True) or [] + except Exception: + images = [] + for image in images: + xref = int(image[0]) + meta = get_object_meta(doc, xref) + if meta and meta.get("kind") in (SIGNATURE_KIND, IMAGE_KIND): + obj = EditObject.from_meta( + meta, xref=xref, image_png=_image_bytes(doc, xref) + ) + if obj.oid not in seen: + found.append(obj) + seen.add(obj.oid) + return found + + +def list_objects(doc: fitz.Document) -> list[EditObject]: + """Return every OpenReader-created editable object in the document.""" + objects: list[EditObject] = [] + for page_index in range(doc.page_count): + objects.extend(_objects_on_page(doc, page_index)) + objects.sort(key=lambda o: (o.page_index, o.z, o.oid)) + return objects + + +def remove_object(doc: fitz.Document, obj: EditObject) -> None: + obj = obj.normalized() + if obj.kind == TEXT_KIND: + page = doc[obj.page_index] + target = None + try: + for annot in page.annots() or []: + if annot.xref == obj.annot_xref or get_object_meta(doc, annot.xref): + meta = get_object_meta(doc, annot.xref) + if meta and meta.get("oid") == obj.oid: + target = annot + break + except Exception: + target = None + if target is not None: + try: + page.delete_annot(target) + except Exception: + pass + return + if obj.xref: + page = doc[obj.page_index] + try: + page.delete_image(obj.xref) + except Exception: + pass + + +def clear_objects(doc: fitz.Document) -> None: + for obj in list_objects(doc): + remove_object(doc, obj) + + +def apply_objects(doc: fitz.Document, objects: Iterable[EditObject]) -> list[EditObject]: + """Replace all OpenReader objects with ``objects`` (used by undo/redo).""" + clear_objects(doc) + applied: list[EditObject] = [] + ordered = sorted( + (o.copy() for o in objects), + key=lambda o: (o.page_index, o.z, o.oid), + ) + for obj in ordered: + try: + applied.append(add_object(doc, obj)) + except Exception: + continue # one bad object must not block the rest + return applied + + +def snapshot(doc: fitz.Document) -> list[EditObject]: + return [obj.copy() for obj in list_objects(doc)] + + +# --------------------------------------------------------------------------- +# Document safety +# --------------------------------------------------------------------------- + + +def document_has_signatures(doc: fitz.Document) -> bool: + """Return True when the document contains a digital signature field.""" + try: + for page in doc: + for widget in page.widgets() or []: + if int(getattr(widget, "field_type", -1)) == int( + getattr(fitz, "PDF_WIDGET_TYPE_SIGNATURE", 8) + ): + return True + except Exception: + pass + try: + for page in doc: + for annot in page.annots() or []: + try: + kind, value = doc.xref_get_key(annot.xref, "FT") + except Exception: + continue + if kind == "name" and value == "/Sig": + return True + except Exception: + pass + return False + + +def document_allows_editing( + doc: fitz.Document, *, encrypted: bool | None = None +) -> bool: + """Conservative editability check. + + Encrypted documents are treated as read-only. PyMuPDF 1.28 corrupts its + decryption state when encryption properties are inspected after + ``authenticate()``, so callers that may have authenticated must pass the + ``encrypted`` flag captured at open time; without it, only the pre-auth + state is read. + """ + if doc is None or getattr(doc, "is_closed", False): + return False + if encrypted is not None: + return not encrypted + try: + if doc.needs_pass or doc.is_encrypted: + return False + except Exception: + return False + return True + + +def page_allows_editing(page: fitz.Page) -> bool: + try: + return int(page.rotation or 0) % 360 == 0 + except Exception: + return True + + +# --------------------------------------------------------------------------- +# Saving +# --------------------------------------------------------------------------- + + +def _atomic_write(doc: fitz.Document, target: Path) -> None: + target = Path(target) + target.parent.mkdir(parents=True, exist_ok=True) + fd, tmp_name = tempfile.mkstemp( + prefix=f".{target.stem}-", suffix=".tmp", dir=str(target.parent) + ) + os.close(fd) + try: + # KEEP is also correct for unencrypted documents: PyMuPDF writes them + # unencrypted. For encrypted documents it preserves the encryption + # dictionary and passwords even after the user has authenticated + # (``is_encrypted`` becomes False after authentication). + encryption = int(getattr(fitz, "PDF_ENCRYPT_KEEP", 2)) + doc.save( + tmp_name, + garbage=3, + deflate=True, + encryption=encryption, + ) + os.replace(tmp_name, target) + except Exception: + try: + os.unlink(tmp_name) + except OSError: + pass + raise + + +def save_document(doc: fitz.Document, target: str | Path) -> None: + """Atomically write the document to ``target``.""" + _atomic_write(doc, Path(target)) + + +def export_flattened(doc: fitz.Document, target: str | Path) -> None: + """Write a flattened copy with annotations/widgets baked into content. + + The original document object is not modified. + """ + target = Path(target) + fd, tmp_name = tempfile.mkstemp( + prefix=".openreader-flat-", suffix=".pdf", dir=str(target.parent) + ) + os.close(fd) + try: + doc.save(tmp_name, garbage=1, deflate=True) + copy_doc = fitz.open(tmp_name) + try: + copy_doc.bake(annots=True, widgets=True) + _atomic_write(copy_doc, target) + finally: + copy_doc.close() + finally: + try: + os.unlink(tmp_name) + except OSError: + pass + + +# --------------------------------------------------------------------------- +# Image helpers (Qt-free; used by tests and the controller) +# --------------------------------------------------------------------------- + + +def png_from_bytes(data: bytes) -> bytes: + """Normalize arbitrary image bytes to PNG when Pillow is available.""" + try: + from PIL import Image + import io + + with Image.open(io.BytesIO(data)) as image: + buffer = io.BytesIO() + image.save(buffer, "PNG") + return buffer.getvalue() + except Exception: + return data + + +def rotated_png(png_bytes: bytes, angle: int) -> bytes: + """Rotate a PNG by an arbitrary angle, expanding the canvas.""" + from PIL import Image + import io + + with Image.open(io.BytesIO(png_bytes)) as image: + rotated = image.convert("RGBA").rotate( + -int(angle or 0) % 360, expand=True, resample=Image.Resampling.BICUBIC + ) + buffer = io.BytesIO() + rotated.save(buffer, "PNG") + return buffer.getvalue() + + +def aspect_size(width: float, image_png: bytes) -> float: + try: + from PIL import Image + import io + + with Image.open(io.BytesIO(image_png)) as image: + w, h = image.size + if w: + return max(1.0, width * h / w) + except Exception: + pass + return max(1.0, width * 0.35) + + +def base64_image(png_bytes: bytes) -> str: + """Optional helper for embedding image data in JSON (tests/debugging).""" + return base64.b64encode(png_bytes).decode("ascii") diff --git a/pdfreader_lib/signature_store.py b/pdfreader_lib/signature_store.py new file mode 100644 index 0000000..f317296 --- /dev/null +++ b/pdfreader_lib/signature_store.py @@ -0,0 +1,154 @@ +"""Local-only signature library for OpenReader. + +Signatures are stored as PNG files plus a small JSON index in the app's +private data directory. Nothing is uploaded; the store is entirely local and +can be cleared by the user at any time. +""" + +from __future__ import annotations + +import json +import os +import tempfile +import uuid +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path + +INDEX_NAME = "signatures.json" + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def _safe_id(value: str) -> str: + return "".join(ch for ch in str(value) if ch.isalnum() or ch in "-_") or uuid.uuid4().hex + + +@dataclass(frozen=True) +class SignatureEntry: + id: str + name: str + kind: str + created: str + path: Path + + def load(self) -> bytes: + return self.path.read_bytes() + + +class SignatureStore: + """A small, atomic, local signature library.""" + + def __init__(self, base_dir: str | Path | None = None): + self.base_dir = Path(base_dir) if base_dir else ( + Path.home() / ".openreader" / "signatures" + ) + self.base_dir.mkdir(parents=True, exist_ok=True) + self.index_path = self.base_dir / INDEX_NAME + + # -- index --------------------------------------------------------- + + def _read_index(self) -> dict: + try: + data = json.loads(self.index_path.read_text(encoding="utf-8")) + return data if isinstance(data, dict) else {} + except (OSError, ValueError): + return {} + + def _write_index(self, data: dict) -> None: + fd, tmp_name = tempfile.mkstemp( + prefix=".signatures-", suffix=".json", dir=str(self.base_dir) + ) + os.close(fd) + try: + Path(tmp_name).write_text( + json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8" + ) + os.replace(tmp_name, self.index_path) + except Exception: + try: + os.unlink(tmp_name) + except OSError: + pass + raise + + # -- public API ---------------------------------------------------- + + def save(self, name: str, png_bytes: bytes, kind: str = "drawn") -> SignatureEntry: + if not png_bytes: + raise ValueError("signature image is empty") + entry_id = uuid.uuid4().hex + path = self.base_dir / f"{entry_id}.png" + fd, tmp_name = tempfile.mkstemp( + prefix=".sig-", suffix=".png", dir=str(self.base_dir) + ) + os.close(fd) + try: + Path(tmp_name).write_bytes(png_bytes) + os.replace(tmp_name, path) + except Exception: + try: + os.unlink(tmp_name) + except OSError: + pass + raise + created = _now() + data = self._read_index() + data[entry_id] = { + "name": (name or "Signature").strip() or "Signature", + "kind": kind, + "created": created, + } + self._write_index(data) + return SignatureEntry(entry_id, data[entry_id]["name"], kind, created, path) + + def list(self) -> list[SignatureEntry]: + data = self._read_index() + entries: list[SignatureEntry] = [] + for entry_id, meta in data.items(): + entry_id = _safe_id(entry_id) + path = self.base_dir / f"{entry_id}.png" + if not path.exists(): + continue + entries.append( + SignatureEntry( + id=entry_id, + name=str(meta.get("name", "Signature")), + kind=str(meta.get("kind", "drawn")), + created=str(meta.get("created", "")), + path=path, + ) + ) + entries.sort(key=lambda e: e.created, reverse=True) + return entries + + def load(self, entry_id: str) -> bytes: + path = self.base_dir / f"{_safe_id(entry_id)}.png" + if not path.exists(): + raise FileNotFoundError(entry_id) + return path.read_bytes() + + def delete(self, entry_id: str) -> None: + entry_id = _safe_id(entry_id) + path = self.base_dir / f"{entry_id}.png" + try: + path.unlink() + except FileNotFoundError: + pass + data = self._read_index() + if entry_id in data: + data.pop(entry_id, None) + self._write_index(data) + + def clear(self) -> None: + for entry in self.list(): + try: + entry.path.unlink() + except OSError: + pass + self._write_index({}) + + def count(self) -> int: + return len(self.list()) diff --git a/tests/test_edit_gui.py b/tests/test_edit_gui.py new file mode 100644 index 0000000..7d9679d --- /dev/null +++ b/tests/test_edit_gui.py @@ -0,0 +1,399 @@ +"""Offscreen GUI tests for v1.3.0 Fill / Edit / Sign.""" + +from __future__ import annotations + +import io + +import fitz +import pytest +from PIL import Image +from PySide6.QtCore import QPoint +from PySide6.QtWidgets import QApplication, QFileDialog, QMessageBox + +from pdfreader_lib import edit_gui, edit_objects as eo + + +@pytest.fixture(autouse=True) +def _no_blocking_dialogs(monkeypatch): + # Closing a dirty test document must not wait for a human. + monkeypatch.setattr( + QMessageBox, + "question", + staticmethod(lambda *args, **kwargs: QMessageBox.Discard), + ) + + +def _png(color=(180, 30, 80, 255), size=(80, 40)) -> bytes: + buffer = io.BytesIO() + Image.new("RGBA", size, color).save(buffer, "PNG") + return buffer.getvalue() + + +def _flush(window) -> None: + window._render_timer.stop() + window._do_render() + QApplication.processEvents() + QApplication.processEvents() + + +def _open(window, path) -> None: + window.open_pdf(str(path)) + _flush(window) + _flush(window) + + +def _controller(window): + controller = window._edit_for_current() + assert controller is not None + return controller + + +def _page_label(window, index=0): + return window._continuous_pages[index] + + +def _zoom(window): + return window._continuous_layout_zoom or 1.0 + + +def _add_text(window, page_index=0, x=100, y=120): + window._activate_edit_tool("text", True) + QApplication.processEvents() + controller = _controller(window) + before = {obj.oid for obj in controller.objects} + label = _page_label(window, page_index) + controller.handle_page_click( + page_index, label, QPoint(x, y), _zoom(window) + ) + QApplication.processEvents() + created = [obj for obj in controller.objects if obj.oid not in before] + assert len(created) == 1 + return controller, created[0] + + +def test_window_has_edit_tools_and_hidden_context_bar(make_window): + window = make_window() + for name in ("fill_button", "text_button", "sign_button", "image_button"): + assert hasattr(window, name) + assert window.context_toolbar is not None + assert window.context_toolbar.isHidden() + + +def test_add_text_commit_save_and_reopen(tmp_path, make_window, make_pdf): + pdf = make_pdf(1, body="Page content") + window = make_window() + _open(window, pdf) + + controller, obj = _add_text(window) + assert obj.kind == eo.TEXT_KIND + assert controller._editor is not None + assert window.context_toolbar.isVisible() + assert window._ctx_done.isVisible() + + controller._commit_text_edit(obj.oid, "Hello edit") + QApplication.processEvents() + assert not window._ctx_done.isVisible() + _flush(window) + saved = controller.object_by_oid(obj.oid) + assert saved is not None and saved.text == "Hello edit" + assert window._document_dirty(window.current_tab_id) + assert window.windowTitle().startswith("●") + + assert window._save_document() is True + assert not window._document_dirty(window.current_tab_id) + assert not window.windowTitle().startswith("●") + + second = make_window() + _open(second, pdf) + objects = eo.list_objects(second.document) + assert len(objects) == 1 + assert objects[0].kind == eo.TEXT_KIND + assert objects[0].text == "Hello edit" + + +def test_text_style_and_context_toolbar(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window) + controller._commit_text_edit(obj.oid, "Styled") + _flush(window) + + assert window.context_toolbar.isVisible() + window._ctx_font.setCurrentIndex( + window._ctx_font.findData("Times-Roman") + ) + window._ctx_size.setValue(24) + window._ctx_bold.setChecked(True) + window._ctx_underline.setChecked(True) + window._on_context_style_changed() + _flush(window) + + updated = controller.object_by_oid(obj.oid) + assert updated is not None + assert updated.style.font_family == "Times-Roman" + assert updated.style.font_size >= 20 + assert updated.style.bold and updated.style.underline + + +def test_image_placement_undo_redo(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller = _controller(window) + label = _page_label(window) + controller.set_pending_image("signature", _png(), "Test") + controller.handle_page_click(0, label, QPoint(150, 350), _zoom(window)) + _flush(window) + assert len(controller.objects) == 1 + obj = controller.objects[0] + assert obj.kind == eo.SIGNATURE_KIND + assert obj.name == "Test" + + assert controller.undo() is True + _flush(window) + assert eo.list_objects(window.document) == [] + assert controller.redo() is True + _flush(window) + objects = eo.list_objects(window.document) + assert len(objects) == 1 and objects[0].kind == eo.SIGNATURE_KIND + + +def test_continuous_mode_editing_and_overlay_scaling(make_window, make_pdf): + pdf = make_pdf(4) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window, page_index=1, x=100, y=100) + controller._commit_text_edit(obj.oid, "Page two") + _flush(window) + assert obj.page_index == 1 + + overlay = controller._overlays.get(obj.oid) + if overlay is not None: + before = overlay.geometry() + window.zoom_in() + _flush(window) + overlay = controller._overlays.get(obj.oid) + if overlay is not None: + assert overlay.geometry().width() > before.width() + + # The object survives navigation and page changes. + window.jump_to_page(4) + _flush(window) + window.jump_to_page(2) + _flush(window) + assert eo.list_objects(window.document)[0].text == "Page two" + + +def test_duplicate_and_delete(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window) + controller._commit_text_edit(obj.oid, "Duplicate me") + _flush(window) + controller.select(obj.oid) + controller.duplicate_selected() + _flush(window) + assert len(eo.list_objects(window.document)) == 2 + controller.select(obj.oid) + controller.delete_selected() + _flush(window) + assert len(eo.list_objects(window.document)) == 1 + + +def test_save_as_and_flattened_export( + tmp_path, monkeypatch, make_window, make_pdf +): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window) + controller._commit_text_edit(obj.oid, "Export me") + _flush(window) + + target = tmp_path / "saved-as.pdf" + monkeypatch.setattr( + QFileDialog, + "getSaveFileName", + lambda *args, **kwargs: (str(target), "PDF files (*.pdf)"), + ) + assert window._save_document_as() is True + assert target.exists() + reopened = fitz.open(target) + try: + assert any(o.text == "Export me" for o in eo.list_objects(reopened)) + finally: + reopened.close() + + flat = tmp_path / "flat.pdf" + monkeypatch.setattr( + QFileDialog, + "getSaveFileName", + lambda *args, **kwargs: (str(flat), "PDF files (*.pdf)"), + ) + window._export_flattened() + assert flat.exists() + flattened = fitz.open(flat) + try: + assert list(flattened[0].annots()) == [] + assert "Export me" in flattened[0].get_text() + finally: + flattened.close() + + +def test_tool_activation_and_escape(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + window._activate_edit_tool("text", True) + controller = _controller(window) + assert controller.tool == "text" + assert window.text_button.isChecked() + assert window._edit_escape() is True + assert controller.tool is None + assert not window.text_button.isChecked() + + +def test_rotated_pages_are_safely_rejected(make_window, tmp_path): + pdf = tmp_path / "rotated.pdf" + doc = fitz.open() + page = doc.new_page(width=612, height=792) + page.insert_text((72, 72), "Rotated", fontsize=18) + page.set_rotation(90) + doc.save(pdf) + doc.close() + + window = make_window() + _open(window, pdf) + controller = _controller(window) + controller.set_tool("text") + label = _page_label(window) + consumed = controller.handle_page_click( + 0, label, QPoint(80, 80), _zoom(window) + ) + assert consumed is True + assert controller.objects == [] + + +def test_inline_editor_ctrl_enter_commits(make_window, make_pdf): + from PySide6.QtCore import Qt + from PySide6.QtTest import QTest + + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window) + editor = controller._editor + assert editor is not None + editor.setPlainText("Typed in the editor") + QTest.keyClick(editor, Qt.Key.Key_Return, Qt.KeyboardModifier.ControlModifier) + QApplication.processEvents() + _flush(window) + assert controller.object_by_oid(obj.oid).text == "Typed in the editor" + + +def test_text_rotation_swaps_rect_and_persists(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller, obj = _add_text(window) + controller._commit_text_edit(obj.oid, "Rotate me") + _flush(window) + before = controller.object_by_oid(obj.oid) + width = before.rect[2] - before.rect[0] + height = before.rect[3] - before.rect[1] + + controller.select(obj.oid) + controller.rotate_selected(90) + _flush(window) + + rotated = controller.object_by_oid(obj.oid) + assert rotated.rotation == 90 + assert (rotated.rect[2] - rotated.rect[0]) == pytest.approx(height, abs=2) + assert (rotated.rect[3] - rotated.rect[1]) == pytest.approx(width, abs=2) + assert eo.list_objects(window.document)[0].rotation == 90 + + +def test_context_toolbar_hides_text_controls_for_images(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + controller = _controller(window) + controller.set_pending_image("signature", _png(), "Test") + label = _page_label(window) + controller.handle_page_click(0, label, QPoint(200, 400), _zoom(window)) + _flush(window) + signature = [o for o in controller.objects if o.kind == eo.SIGNATURE_KIND][0] + controller.select(signature.oid) + QApplication.processEvents() + assert window.context_toolbar.isVisible() + assert not window._ctx_text_actions[0].isVisible() + assert window._ctx_rotate.isVisible() + assert not window._ctx_done.isVisible() + + +def test_coordinate_mapping_at_two_zoom_levels(make_window, make_pdf): + pdf = make_pdf(1) + window = make_window() + _open(window, pdf) + + def expected(point, zoom): + page_rect = window.document[0].rect + return ( + page_rect.x0 + (point.x() - 1) / zoom, + page_rect.y0 + (point.y() - 1) / zoom, + ) + + controller, obj = _add_text(window, x=100, y=140) + zoom = _zoom(window) + ex, ey = expected(QPoint(100, 140), zoom) + assert obj.rect[0] == pytest.approx(ex, abs=1) + assert obj.rect[1] == pytest.approx(ey, abs=1) + controller._commit_text_edit(obj.oid, "One") + _flush(window) + + window.zoom_in() + _flush(window) + controller, obj2 = _add_text(window, x=180, y=220) + zoom2 = _zoom(window) + ex2, ey2 = expected(QPoint(180, 220), zoom2) + assert obj2.rect[0] == pytest.approx(ex2, abs=1) + assert obj2.rect[1] == pytest.approx(ey2, abs=1) + + +def test_typed_signature_dialog_produces_png(tmp_path): + from pdfreader_lib import signature_store as ss + + store = ss.SignatureStore(tmp_path / "sigs") + dialog = edit_gui.SignatureDialog(store) + dialog.tabs.setCurrentIndex(1) + dialog.type_name.setText("Sparsh Sam") + assert dialog.type_font.count() > 0 + dialog._accept() + assert dialog.result_png + assert dialog.result_png[:8] == b"\x89PNG\r\n\x1a\n" + assert dialog.result_kind == "typed" + + +def test_drawn_canvas_produces_transparent_png(): + from PySide6.QtCore import QPointF + + canvas = edit_gui.SignatureCanvas() + canvas.resize(400, 200) + canvas._strokes = [[QPointF(20, 120), QPointF(120, 40), QPointF(260, 140)]] + assert canvas.has_content() + png = canvas.to_png() + image = Image.open(io.BytesIO(png)) + assert image.mode == "RGBA" + assert image.size[0] > 0 and image.size[1] > 0 + canvas.clear() + assert not canvas.has_content() + + +def test_dark_theme_keeps_edit_toolbar_styled(make_window): + window = make_window() + window.set_theme(window.THEME_DARK) + assert "ContextToolbar" in window.styleSheet() + window.set_theme(window.THEME_LIGHT) + assert "ContextToolbar" in window.styleSheet() diff --git a/tests/test_edit_objects.py b/tests/test_edit_objects.py new file mode 100644 index 0000000..292ffdb --- /dev/null +++ b/tests/test_edit_objects.py @@ -0,0 +1,367 @@ +"""Tests for the Qt-free editable-object model (v1.3.0).""" + +from __future__ import annotations + +import hashlib +import io +import json + +import fitz +import pytest +from PIL import Image + +from pdfreader_lib import edit_objects as eo + + +def _png(color=(200, 30, 60, 255), size=(60, 30)) -> bytes: + buffer = io.BytesIO() + Image.new("RGBA", size, color).save(buffer, "PNG") + return buffer.getvalue() + + +def _blank_doc(): + doc = fitz.open() + doc.new_page(width=612, height=792) + return doc + + +def _text_object(**overrides) -> eo.EditObject: + values = dict( + oid="text-1", + kind=eo.TEXT_KIND, + page_index=0, + rect=(72, 72, 300, 120), + text="Hello OpenReader\nsecond line", + style=eo.TextStyle( + font_family="Times New Roman", + font_size=18, + color="#cc0000", + bold=True, + italic=True, + underline=True, + align="center", + ), + rotation=0, + ) + values.update(overrides) + return eo.EditObject(**values) + + +def _image_object(**overrides) -> eo.EditObject: + values = dict( + oid="image-1", + kind=eo.SIGNATURE_KIND, + page_index=0, + rect=(72, 200, 252, 280), + image_png=_png(), + name="Sparsh", + ) + values.update(overrides) + return eo.EditObject(**values) + + +def test_text_style_normalization(): + style = eo.TextStyle( + font_family="Arial", + font_size=1000, + color="not-a-color", + align="diagonal", + ).normalized() + assert style.font_family == "Helvetica" + assert style.font_size == 200 + assert style.color == "#000000" + assert style.align == "left" + + +def test_add_text_persists_metadata_and_style(tmp_path): + doc = _blank_doc() + eo.add_object(doc, _text_object()) + found = eo.list_objects(doc) + assert len(found) == 1 + obj = found[0] + assert obj.kind == eo.TEXT_KIND + assert obj.text.startswith("Hello OpenReader") + assert obj.style.font_family == "Times-Roman" + assert obj.style.bold and obj.style.italic and obj.style.underline + assert obj.style.align == "center" + + path = tmp_path / "text.pdf" + eo.save_document(doc, path) + doc.close() + + reopened = fitz.open(path) + try: + objects = eo.list_objects(reopened) + assert len(objects) == 1 + assert objects[0].oid == "text-1" + assert objects[0].rect == pytest.approx((72, 72, 300, 120)) + assert "second line" in objects[0].text + assert objects[0].style.color == "#cc0000" + finally: + reopened.close() + + +def test_update_text_replace_and_delete(tmp_path): + doc = _blank_doc() + obj = eo.add_object(doc, _text_object()) + updated = obj.copy() + updated.text = "Replaced" + updated.rect = (100, 100, 340, 150) + updated.style = eo.TextStyle(font_family="Courier New", font_size=12) + eo.remove_object(doc, obj) + eo.add_object(doc, updated) + found = eo.list_objects(doc) + assert len(found) == 1 + assert found[0].text == "Replaced" + assert found[0].rect == pytest.approx((100, 100, 340, 150)) + assert found[0].style.font_family == "Courier" + + eo.remove_object(doc, found[0]) + assert eo.list_objects(doc) == [] + doc.close() + + +def test_text_rotation_roundtrip(tmp_path): + doc = _blank_doc() + eo.add_object(doc, _text_object(rotation=90)) + path = tmp_path / "rotated.pdf" + eo.save_document(doc, path) + doc.close() + reopened = fitz.open(path) + try: + annots = list(reopened[0].annots()) + assert len(annots) == 1 + assert annots[0].rotation == 90 + assert eo.list_objects(reopened)[0].rotation == 90 + finally: + reopened.close() + + +def test_add_image_persists_and_removes_visually(tmp_path): + doc = _blank_doc() + obj = eo.add_object(doc, _image_object()) + page = doc[0] + found = eo.list_objects(doc) + assert len(found) == 1 + assert found[0].kind == eo.SIGNATURE_KIND + assert found[0].image_png # extracted from the XObject + assert found[0].name == "Sparsh" + + pix = page.get_pixmap(matrix=fitz.Matrix(1, 1)) + assert pix.pixel(100, 240) != (255, 255, 255) + + path = tmp_path / "image.pdf" + eo.save_document(doc, path) + doc.close() + + reopened = fitz.open(path) + try: + objects = eo.list_objects(reopened) + assert len(objects) == 1 + assert objects[0].kind == eo.SIGNATURE_KIND + assert objects[0].rect == pytest.approx((72, 200, 252, 280)) + eo.remove_object(reopened, objects[0]) + pix = reopened[0].get_pixmap(matrix=fitz.Matrix(1, 1)) + assert pix.pixel(100, 240) == (255, 255, 255) + assert eo.list_objects(reopened) == [] + finally: + reopened.close() + + +def test_duplicate_image_gets_independent_metadata(tmp_path): + doc = _blank_doc() + first = eo.add_object(doc, _image_object()) + duplicate = first.copy() + duplicate.oid = "image-2" + duplicate.rect = (300, 200, 480, 280) + eo.add_object(doc, duplicate) + objects = eo.list_objects(doc) + assert len(objects) == 2 + assert {o.oid for o in objects} == {"image-1", "image-2"} + assert objects[0].xref != objects[1].xref + assert objects[0].rect != objects[1].rect + page = doc[0] + before = page.get_pixmap(matrix=fitz.Matrix(1, 1)) + assert before.pixel(100, 240) != (255, 255, 255) + assert before.pixel(350, 240) != (255, 255, 255) + + # Deleting one placement must leave the other intact. + eo.remove_object(doc, objects[0]) + remaining = eo.list_objects(doc) + assert len(remaining) == 1 and remaining[0].oid == "image-2" + after = page.get_pixmap(matrix=fitz.Matrix(1, 1)) + assert after.pixel(100, 240) == (255, 255, 255) + assert after.pixel(350, 240) != (255, 255, 255) + doc.close() + + +def test_apply_objects_restores_a_snapshot(): + doc = _blank_doc() + eo.add_object(doc, _text_object()) + eo.add_object(doc, _image_object()) + saved = eo.snapshot(doc) + assert len(saved) == 2 + + eo.clear_objects(doc) + assert eo.list_objects(doc) == [] + + restored = eo.apply_objects(doc, saved) + assert len(restored) == 2 + current = eo.list_objects(doc) + assert {o.oid for o in current} == {"text-1", "image-1"} + assert any(o.kind == eo.TEXT_KIND for o in current) + assert any(o.kind == eo.SIGNATURE_KIND for o in current) + doc.close() + + +def test_save_document_is_atomic_and_preserves_content(tmp_path): + doc = _blank_doc() + doc[0].insert_text((72, 40), "Existing page content", fontsize=12) + eo.add_object(doc, _text_object()) + path = tmp_path / "atomic.pdf" + eo.save_document(doc, path) + doc.close() + + reopened = fitz.open(path) + try: + assert "Existing page content" in reopened[0].get_text() + assert len(eo.list_objects(reopened)) == 1 + finally: + reopened.close() + # No temporary files are left behind. + assert [p.name for p in tmp_path.iterdir() if p.name.endswith(".tmp")] == [] + + +def test_export_flattened_leaves_original_untouched(tmp_path): + doc = _blank_doc() + eo.add_object(doc, _text_object()) + eo.add_object(doc, _image_object()) + source = tmp_path / "source.pdf" + eo.save_document(doc, source) + hash_before = hashlib.sha256(source.read_bytes()).hexdigest() + + flat = tmp_path / "flattened.pdf" + eo.export_flattened(doc, flat) + + assert hashlib.sha256(source.read_bytes()).hexdigest() == hash_before + assert len(eo.list_objects(doc)) == 2 + + flattened = fitz.open(flat) + try: + page = flattened[0] + assert list(page.annots()) == [] + assert list(page.widgets() or []) == [] + assert "Hello OpenReader" in page.get_text() + assert len(page.get_images(full=True)) >= 1 + finally: + flattened.close() + doc.close() + + +def test_document_safety_helpers(): + doc = _blank_doc() + assert eo.document_allows_editing(doc) is True + assert eo.document_has_signatures(doc) is False + assert eo.page_allows_editing(doc[0]) is True + doc.close() + assert eo.document_allows_editing(doc) is False + + +def test_document_has_signatures_detects_signature_fields(): + doc = fitz.open() + page = doc.new_page() + widget = fitz.Widget() + widget.field_type = fitz.PDF_WIDGET_TYPE_SIGNATURE + widget.field_name = "signature1" + widget.rect = fitz.Rect(50, 50, 200, 100) + page.add_widget(widget) + try: + assert eo.document_has_signatures(doc) is True + finally: + doc.close() + + +def test_encrypted_read_only_document_is_not_editable(tmp_path): + source = tmp_path / "encrypted.pdf" + doc = fitz.open() + page = doc.new_page() + page.insert_text((72, 72), "Locked content", fontsize=14) + doc.save( + source, + encryption=fitz.PDF_ENCRYPT_AES_256, + owner_pw="owner-secret", + user_pw="user-secret", + permissions=fitz.PDF_PERM_PRINT, + ) + doc.close() + + reopened = fitz.open(source) + try: + assert reopened.needs_pass + assert reopened.authenticate("user-secret") + # The encryption flag is captured at open time; do not inspect the + # authenticated document's encryption properties (PyMuPDF 1.28 bug). + assert eo.document_allows_editing(reopened, encrypted=True) is False + assert "Locked content" in reopened[0].get_text() + finally: + reopened.close() + + +def test_atomic_save_preserves_encryption(tmp_path): + source = tmp_path / "encrypted.pdf" + target = tmp_path / "encrypted-copy.pdf" + doc = fitz.open() + doc.new_page().insert_text((72, 72), "Encrypted content", fontsize=14) + doc.save( + source, + encryption=fitz.PDF_ENCRYPT_AES_256, + owner_pw="owner-secret", + user_pw="user-secret", + permissions=fitz.PDF_PERM_PRINT, + ) + doc.close() + + reopened = fitz.open(source) + try: + assert reopened.authenticate("user-secret") + reopened[0].insert_text((72, 100), "Second line", fontsize=12) + eo.save_document(reopened, target) + finally: + reopened.close() + + copied = fitz.open(target) + try: + assert copied.needs_pass + assert copied.authenticate("user-secret") + text = copied[0].get_text() + assert "Encrypted content" in text and "Second line" in text + finally: + copied.close() + + +def test_rotated_png_and_aspect_size(): + png = _png(size=(100, 50)) + rotated = eo.rotated_png(png, 90) + with Image.open(io.BytesIO(rotated)) as image: + assert image.size == (50, 100) + assert eo.aspect_size(200, png) == pytest.approx(100) + + +def test_metadata_rejects_foreign_annotations(tmp_path): + doc = _blank_doc() + page = doc[0] + page.add_freetext_annot(fitz.Rect(10, 10, 100, 50), "foreign") + assert eo.list_objects(doc) == [] + path = tmp_path / "foreign.pdf" + eo.save_document(doc, path) + doc.close() + + +def test_invalid_object_kind_is_rejected(): + doc = _blank_doc() + with pytest.raises(ValueError): + eo.add_object( + doc, + eo.EditObject(oid="x", kind="video", page_index=0, rect=(0, 0, 10, 10)), + ) + doc.close() diff --git a/tests/test_signature_store.py b/tests/test_signature_store.py new file mode 100644 index 0000000..7bb1cd8 --- /dev/null +++ b/tests/test_signature_store.py @@ -0,0 +1,74 @@ +"""Tests for the local-only signature library.""" + +from __future__ import annotations + +import io + +from PIL import Image + +from pdfreader_lib.signature_store import SignatureStore + + +def _png() -> bytes: + buffer = io.BytesIO() + Image.new("RGBA", (40, 20), (10, 20, 30, 255)).save(buffer, "PNG") + return buffer.getvalue() + + +def test_save_list_load_delete(tmp_path): + store = SignatureStore(tmp_path) + entry = store.save("Sparsh", _png(), kind="typed") + assert entry.name == "Sparsh" + assert entry.kind == "typed" + assert entry.path.exists() + assert entry.load()[:8] == b"\x89PNG\r\n\x1a\n" + + entries = store.list() + assert len(entries) == 1 + assert entries[0].id == entry.id + assert store.load(entry.id) == entry.load() + + store.delete(entry.id) + assert store.list() == [] + assert not entry.path.exists() + + +def test_clear_and_count(tmp_path): + store = SignatureStore(tmp_path) + store.save("One", _png()) + store.save("Two", _png()) + assert store.count() == 2 + store.clear() + assert store.count() == 0 + assert list(tmp_path.glob("*.png")) == [] + + +def test_empty_signature_rejected(tmp_path): + store = SignatureStore(tmp_path) + try: + store.save("Bad", b"") + except ValueError: + pass + else: + raise AssertionError("empty signature should be rejected") + + +def test_missing_index_degrades_gracefully(tmp_path): + store = SignatureStore(tmp_path) + (tmp_path / "signatures.json").write_text("not json", encoding="utf-8") + assert store.list() == [] + entry = store.save("Recovered", _png()) + assert store.list()[0].id == entry.id + + +def test_path_traversal_id_is_sanitized(tmp_path): + store = SignatureStore(tmp_path) + entry = store.save("Safe", _png()) + # Unknown/traversal ids never resolve outside the store directory. + try: + store.load("../../etc/passwd") + except FileNotFoundError: + pass + store.delete("../../etc/passwd") + assert store.count() == 1 + assert entry.path.exists() From 7106ae5637a35f5a223a2c8f6e2285ba860390fe Mon Sep 17 00:00:00 2001 From: Sparsh Sam <110058692+sparshsam@users.noreply.github.com> Date: Sun, 8 Nov 2026 20:13:17 -0500 Subject: [PATCH 3/4] docs(v1.3.0): Fill, Edit & Sign changelog, architecture and design spec Document the editing architecture, persistence rules, safety limits, UI, limitations and test coverage. Align the MCP package metadata to 1.3.0. Co-Authored-By: Claude Code --- AGENTS.md | 9 ++ CHANGELOG.md | 22 ++-- CLAUDE.md | 10 ++ README.md | 2 + docs/Architecture.md | 20 +++ .../specs/2026-11-08-fill-edit-sign-design.md | 119 ++++++++++++++++++ .../src/openreader_mcp.egg-info/PKG-INFO | 2 +- 7 files changed, 176 insertions(+), 8 deletions(-) create mode 100644 docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md diff --git a/AGENTS.md b/AGENTS.md index 0ffd73a..c941812 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,15 @@ This repository is a local-first desktop PDF utility. Keep maintenance changes b - Do not introduce network behavior beyond the explicit GitHub release update check (update detection only — no downloading or applying updates). - Treat PDFs as local/private user data. +## Editing Rules (v1.3.0+) + +- Keep the object model and persistence in `pdfreader_lib/edit_objects.py` **Qt-free**. GUI-only logic (overlays, inline editor, signature dialog, coordinate conversion) belongs in `pdfreader_lib/edit_gui.py`. +- Persist text as native `FreeText` annotations and signatures/images as image XObjects in page content, each carrying the `OpenReaderData` metadata key. Never persist edits as temporary overlays that disappear on save. +- Save atomically (temp file + `os.replace`) and preserve encryption with `PDF_ENCRYPT_KEEP`. Flattened export must operate on a copy, never the open original. +- Warn before editing/saving documents that contain `/FT /Sig` signature fields. Encrypted documents and pages with `/Rotate` are read-only for editing. +- Any change to the object model needs save → reopen round-trip tests. Any change to overlays needs continuous-scroll/zoom coordinate tests. +- Signature data is local-only. Do not add uploads, accounts, or cloud processing. + ## Release and Update Rules - The app detects updates via GitHub API and opens the releases page in a browser. It does not download or install updates. diff --git a/CHANGELOG.md b/CHANGELOG.md index f33379f..ec1e04f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,24 @@ # Changelog -## v1.3.0 — PDF Form Intelligence — 2026-08-02 - -- **Version:** Bumped `__version__` to `1.3.0`, MSIX version to `1.3.0.0`; aligned the MCP package version. -- **Added (v1.3.0 — Interactive Forms):** AcroForm fields are detected automatically and rendered as native editable controls overlaid on the page — text, multiline text, checkboxes, radio groups, dropdowns (combo) and list boxes. Existing field values are preserved and seeded into the controls. Read-only fields are shown but never editable; required, max-length and password rules are respected (including combing). Fillable areas are highlighted on the page so blank forms stay discoverable. +## v1.3.0 — Fill, Edit & Sign — 2026-11-08 + +- **Version:** Bumped `__version__` to `1.3.0`, MSIX version to `1.3.0.0`; aligned the MCP package version. The optional MCP SDK is constrained to 1.x (`mcp>=1.0.0,<2`) because MCP 2.x changed the server API. +- **Added (Add Text — freeform editing):** Click anywhere on a page to create a multiline text object and type directly in an inline editor. Text objects can be dragged, resized, rotated in 90° steps, duplicated, copied/pasted and deleted. The contextual bar changes font family (Helvetica, Times New Roman, Courier New), size, color, bold, italic, underline and alignment. Text boxes grow to fit multiline content. Objects are stored as native PDF `FreeText` annotations with an `OpenReaderData` metadata key, so saved documents reopen with fully editable objects in OpenReader while remaining selectable in other viewers. +- **Added (Sign — visual electronic signatures):** Create a signature by drawing (mouse, touch, pen or trackpad), typing a name with locally available signature-style fonts, importing an image (PNG/JPEG/BMP/WebP/GIF with transparency), or reusing a saved signature. Signatures can be placed anywhere, dragged, proportionally resized, rotated, duplicated, removed and added to multiple pages. An optional local signature library stores PNGs in the app data directory with per-entry delete/clear controls; nothing is uploaded. Visual electronic signatures are explicitly distinguished from certificate-based digital signatures, which are out of scope. +- **Added (Images):** Insert common image formats, position/resize proportionally, rotate, duplicate and delete using the same placement infrastructure as signatures. +- **Added (Editing architecture):** `pdfreader_lib/edit_objects.py` (Qt-free object model, metadata, atomic save, flattened export), `pdfreader_lib/edit_gui.py` (per-tab controller, overlays, inline editor, signature creator, undo/redo) and `pdfreader_lib/signature_store.py` (local library). Editing works in the virtualized continuous-scroll view at any zoom; coordinates are converted to PDF points and objects re-anchor after scrolling, zooming, resizing and tab switches. +- **Added (Persistence & safety):** Save and Save As use atomic temp-file replacement. Export Flattened PDF bakes annotations and form widgets into page content on a copy, leaving the original untouched. Dirty indicators appear in the tab and window title; closing a modified tab/window prompts Save / Discard / Cancel. Undo/redo covers object edits. Existing annotations, links, bookmarks and metadata are preserved. Documents with digital signature fields trigger an explicit warning before editing or saving; encrypted documents and rotated pages are treated as read-only. +- **Added (Editing UI):** Fill, Add Text, Sign and Image actions join the compact v1.2.8 toolbar; a contextual formatting bar appears for selected text (and rotate/duplicate/delete for images/signatures). Both themes, accessible names, tooltips, Escape/Delete/Ctrl+Z/Y/C/V/S/Shift+S shortcuts and continuous-mode editing are supported. +- **Added (Fill — interactive forms):** AcroForm fields are detected automatically and rendered as native editable controls overlaid on the page — text, multiline text, checkboxes, radio groups, dropdowns (combo) and list boxes. Existing field values are preserved and seeded into the controls. Read-only fields are shown but never editable; required, max-length and password rules are respected (including combing). Fillable areas are highlighted on the page so blank forms stay discoverable. - **Added:** Keyboard and accessible navigation — Tab/Shift+Tab move between fields in document order, arrow keys move within a radio group, and every control exposes its field name to screen readers via the Qt accessibility bridge. - **Added:** Save behaviour — Save (Ctrl+S) writes completed values into the PDF (regenerating appearance streams so they render in any viewer) via incremental save; new **Save As…** (Ctrl+Shift+S) writes a completed copy. Closing a tab or the window with unsaved form work prompts **Save / Discard / Cancel**. -- **Added (v1.3.1 — Field Type Intelligence):** Field types are detected from PDF formatting rules (explicit) and from field names / nearby labels (inferred) — date, time, phone, ZIP/postal, email, currency, numeric. Inferred types are always advisory: an inferred date field is still fully editable as plain text and shows a picker + validation rather than enforcing. Users can override a field's type via its context menu; overrides persist outside the PDF. A date-picker button appears next to detected date fields. Advisory validation produces clear messages (e.g. "Expected a phone number like +1 555 123 4567") that never block input and tolerate legitimate international formats. -- **Added (v1.3.2 — Completion Workflow):** **Form Navigator** dock (View/Form menu) lists every field with status — filled / empty / required / invalid — grouped by page; clicking one scrolls to and focuses it. **Next/Previous Field** (Ctrl+Down/Ctrl+Up), **Clear Field**, **Clear Form**, and **Review & Complete** (a completion summary that highlights missing required and invalid fields). Required-but-empty fields get an amber outline. Unsaved form work is autosaved locally and **restored on reopen** with a prompt; the recent-files menu marks documents that contain fillable forms. +- **Added (Fill — field type intelligence):** Field types are detected from PDF formatting rules (explicit) and from field names / nearby labels (inferred) — date, time, phone, ZIP/postal, email, currency, numeric. Inferred types are always advisory: an inferred date field is still fully editable as plain text and shows a picker + validation rather than enforcing. Users can override a field's type via its context menu; overrides persist outside the PDF. A date-picker button appears next to detected date fields. Advisory validation produces clear messages (e.g. "Expected a phone number like +1 555 123 4567") that never block input and tolerate legitimate international formats. +- **Added (Fill — completion workflow):** **Form Navigator** dock (View/Form menu) lists every field with status — filled / empty / required / invalid — grouped by page; clicking one scrolls to and focuses it. **Next/Previous Field** (Ctrl+Down/Ctrl+Up), **Clear Field**, **Clear Form**, and **Review & Complete** (a completion summary that highlights missing required and invalid fields). Required-but-empty fields get an amber outline. Unsaved form work is autosaved locally and **restored on reopen** with a prompt; the recent-files menu marks documents that contain fillable forms. - **MCP Server:** Five new tools — `form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate` — mirroring the GUI's form engine (shared `pdfreader_lib/form_fields.py`), in both the bundled server and the standalone `openreader-mcp` package (19 tools total). Per-field success/failure reporting; read-only fields are respected. - **Fixed:** A debounced render could fire after a document was closed (rendering a closed PDF raised `ValueError: document closed`); `_do_render` now bails out and the render timer is stopped on close. Removed a redundant `_perf_end` in `_render_continuous` that referenced an undefined local. -- **Verification:** New shared-module test suite (44 tests: normalization, flags, radio grouping, read/write round-trips, incremental-save persistence, type detection explicit-vs-inferred, international-tolerant validation, form-state store), 15 new MCP form-tool tests, and 4 offscreen GUI smoke tests (overlay creation, dirty tracking, persistence, validation messaging). +- **Limitations (v1.3.0):** Text rotation is limited to 90° increments (a FreeText constraint); text font families are the Base-14 Helvetica/Times/Courier families; editing arbitrary pre-existing embedded PDF text, certificate-based signing, and editing rotated pages are out of scope. Encrypted documents are read-only. +- **Verification:** **261 tests pass** (18 pre-existing skips): the form-engine/MCP suites, 13 editable-object persistence tests (text/image metadata, reopen, undo state, atomic save, flattening, signing detection, encrypted save), 5 signature-store tests, 16 offscreen editing GUI tests (text, inline Ctrl+Enter commit, formatting, images/signatures, undo/redo, Save As, flattened export, coordinate mapping, continuous mode, rotated pages, themes) and the existing reader/toolbar/scrolling regressions. + ## v1.2.8 — Continuous Reading & Toolbar Redesign — 2026-11-08 - **Fixed (continuous scrolling):** The continuous view no longer renders a sliding window around the current page. Every page now gets a correctly sized placeholder in one persistent document layout, so the scrollbar spans the whole PDF — a 76-page document exposes all 76 pages instead of roughly six. Pixmaps are rendered lazily for the viewport plus a small overscan and released once they leave the cache window, so memory stays bounded for very long documents. diff --git a/CLAUDE.md b/CLAUDE.md index 9b19985..64b693a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -133,6 +133,16 @@ The repository ships two MCP server entry points: - **Validation** (`FormValidator`) is advisory and international-tolerant; it writes `validation_message`, never blocks input. - **Rules:** when adding a new form operation, mirror it in the bundled server and `packages/mcp-server/` (copy `_form_fields.py` too). See `docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md` for the full spec. +## Editing — Add Text, Signatures & Images (v1.3.0) + +- **Model / persistence:** `pdfreader_lib/edit_objects.py` is Qt-free. Text is stored as native `FreeText` annotations with an `OpenReaderData` metadata key on the annotation xref; signatures and images are page-content image XObjects carrying the same metadata key. This is what makes objects survive save/reopen and remain re-editable in OpenReader. Never store edits as temporary overlays. +- **GUI:** `pdfreader_lib/edit_gui.py` owns the per-tab `EditController`, selection/resize overlays on the persistent continuous page labels, the inline text editor, the signature draw/type/import dialog, and snapshot-based undo/redo. Coordinate conversion belongs here (PDF points ↔ page-label pixels), never in the model. +- **Signatures:** `pdfreader_lib/signature_store.py` is a local PNG library under the app data directory. It has per-entry delete and clear-all; nothing is ever uploaded. +- **Save/export:** saves are atomic (temp file + `os.replace`) and preserve the document's encryption via `PDF_ENCRYPT_KEEP`. Export Flattened PDF uses `Document.bake(annots=True, widgets=True)` on a copy, never the open original. +- **Safety:** documents with `/FT /Sig` signature fields warn before editing/saving. Encrypted documents and pages with `/Rotate` are read-only for editing. Never silently invalidate a signature. +- **Limitations:** text rotation is 90° steps only (FreeText); text fonts are Base-14 Helvetica/Times/Courier; editing arbitrary pre-existing embedded text and certificate-based signing are out of scope. Form-field value changes use native widget undo; the global undo stack covers editable objects. +- **Spec:** `docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md`. + ## Design Playbooks Three canonical playbooks govern all design and architecture decisions. Loaded at `docs/playbooks/`: diff --git a/README.md b/README.md index 5315376..acddab4 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ | | | |---|---| | **Read** — Open PDFs, one-page or continuous scroll, fit-width zoom, page jump. | **Annotate** — Highlight, underline, strikethrough, and sticky notes. Saved as native PDF annotations. | +| **Fill, Edit & Sign** — Complete AcroForm fields, add formatted text, insert images and place visual signatures in continuous scroll. | **Forms & flatten** — Save, Save As, or export a flattened copy; annotations, links and metadata are preserved. | | **Search** — Full-document keyword search with match count and navigation. | **Library search** — Index entire folders with SQLite FTS5 for cross-document BM25-ranked search. | | **Semantic search** — TF-IDF cosine similarity — meaning-based matching, no external ML. | **Compare** — Side-by-side diff with color-coded changes and structured summary. | | **Multi-tab** — Open several documents in one window with movable tabs. | **Dark mode** — System-aware theme with Auto/Light/Dark toggle. | @@ -115,6 +116,7 @@ The focus is on reading and working with documents, not fighting the interface. | Release | Date | Milestone | |---------|------|-----------| +| **v1.3.0** | Nov 2026 | Fill, Edit & Sign — AcroForm filling, freeform text objects, visual signatures, image placement, atomic save and flattened export | | **v1.2.8** | Nov 2026 | Continuous scrolling rebuilt on a virtualized full-document layout; unified Fluent toolbar and light/dark redesign | | **v1.2.7** | Aug 2026 | Store-aware updates — install-source detection, channel-aware update dialog | | **v1.2.6** | Aug 2026 | Default reader experience — Windows default-app detection and settings | diff --git a/docs/Architecture.md b/docs/Architecture.md index 7cd3436..047ff94 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -40,6 +40,9 @@ OpenReader is a local-first desktop PDF utility built with Python and PySide6 (Q | Search | `pdfreader_lib/search_index.py` | SQLite FTS5 keyword index + TF-IDF semantic search | | Comparison | `pdfreader_lib/comparison.py` | Page-by-page text diff with color-coded output | | Forms | `pdfreader_lib/form_fields.py` | AcroForm field model, value read/write, type detection & advisory validation (v1.3.0+) | +| Editing model | `pdfreader_lib/edit_objects.py` | Qt-free text/signature/image objects, `OpenReaderData` metadata, atomic save, flattened export, signature detection | +| Editing UI | `pdfreader_lib/edit_gui.py` | Per-tab edit controller, page overlays, inline text editor, signature dialog, undo/redo | +| Signatures | `pdfreader_lib/signature_store.py` | Local-only PNG signature library with delete/clear controls | | MCP Server | `pdfreader_lib/mcp_server.py` | Model Context Protocol server for AI agent integration (19 tools) | ## Key Architecture Decisions @@ -51,6 +54,23 @@ OpenReader is a local-first desktop PDF utility built with Python and PySide6 (Q 5. **No self-update.** The app detects updates via GitHub API but never downloads or runs installers. MSIX updates are handled by Windows App Installer. 6. **Virtualized continuous rendering.** The default view keeps one correctly sized placeholder widget per page in a single persistent layout, so the scrollbar always spans the whole document and every page stays reachable. Page pixmaps are rendered lazily for the viewport plus a small overscan (`CONTINUOUS_OVERSCAN`) and released once they leave the cache window (`CONTINUOUS_CACHE`), keeping memory bounded at high zoom and for long documents. Scroll position drives the current page; Next/Previous, the page box, and search jumps scroll in place without rebuilding the layout. Explicit renders (zoom, annotations, search, theme) invalidate the cached pixmaps. Single-page mode remains available via **View → Continuous Scroll**. 7. **Theme-aware design system.** A single 44 px toolbar groups file, page, zoom, annotation, and search actions. Icons are drawn as vectors from one factory (`_make_toolbar_icon`) in the active theme's palette, and both light and dark stylesheets share the same neutral tokens with the OpenReader accent. +8. **Editing is persisted, never painted on top.** Text objects are native `FreeText` annotations; signatures and images are image XObjects in page content. Both carry an `OpenReaderData` JSON key so OpenReader can find and re-edit them after save/reopen. There is no sidecar or temporary canvas that is lost on save. +9. **Safe writes.** Saves use a temp file in the same directory plus `os.replace`; encryption is preserved with `PDF_ENCRYPT_KEEP`. Flattened export uses `Document.bake` on a copy, so the original file is untouched. Documents with digital-signature fields warn before editing/saving; encrypted documents and rotated pages are read-only for editing. + +## Editing Pipeline (v1.3.0) + +``` +Fill ── AcroForm widgets ────────────────┐ +Add Text ── FreeText annot + metadata ────┤ +Sign ── PNG image content + metadata ────┤── EditController (per tab) +Image ── PNG image content + metadata ────┘ │ + ├─ overlays on page labels (continuous or single page) + ├─ inline text editor + contextual formatting bar + ├─ undo/redo snapshots of editable objects + └─ atomic save / Save As / flattened export +``` + +Coordinates are always PDF points; the GUI converts to and from page-label pixels using the active layout zoom. Page labels are persistent in continuous mode, so editing works without leaving continuous scroll. ## Security Model diff --git a/docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md b/docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md new file mode 100644 index 0000000..b6c1961 --- /dev/null +++ b/docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md @@ -0,0 +1,119 @@ +# Fill, Edit & Sign (v1.3.0) — Design + +> **Status:** Implemented for v1.3.0 on top of the released v1.2.8 reader. +> **Scope:** Interactive form filling, freeform text, visual electronic signatures, +> image placement, persistence, and editing UI. Certificate-based signing and +> editing arbitrary embedded PDF text are explicitly out of scope. + +## Goals + +Make OpenReader a practical local alternative to Acrobat for everyday completion: + +**Open a PDF → Fill its fields → Add text or images → Sign → Save or export.** + +Everything runs locally. No accounts, no subscriptions, no uploads. + +## Architecture + +``` +pdfreader_lib/form_fields.py Qt-free AcroForm engine (Forms) +pdfreader_lib/edit_objects.py Qt-free editable-object model + persistence +pdfreader_lib/edit_gui.py Qt controller, overlays, inline editor, + signature dialog/canvas, undo/redo +pdfreader_lib/signature_store.py Local-only PNG signature library +main.py Toolbar actions, contextual bar, save/dirty UI, + page-label overlay attachment +``` + +The model never imports PySide6, so it is usable from tests and the MCP server. +The GUI controller owns all Qt widgets and coordinate conversion. + +## Persistence + +| Object | PDF representation | Re-edit metadata | +|---|---|---| +| Text | Native `FreeText` annotation (rich text, base-14 fonts, selectable) | `OpenReaderData` JSON string key on the annotation xref: oid, rect, text, style, rotation | +| Signature | Image XObject inserted into page content | `OpenReaderData` JSON on the image xref: oid, kind, rect, rotation, name | +| Image | Image XObject inserted into page content | Same as signatures | + +Notes: + +- Image payloads are made unique per placement with a private PNG `tEXt` chunk so + PyMuPDF cannot merge two objects onto one XObject and lose metadata. +- `list_objects()` only returns objects carrying `OpenReaderData`; foreign + annotations and images are never modified. +- Text style is a Qt-free `TextStyle` (family, size, color, bold, italic, + underline, alignment) mapped to FreeText CSS + `/Q`. +- Moving/resizing/reformatting removes and re-inserts the object while preserving + its `oid`, so the same object remains selected and editable. + +## Save / export + +- **Save / Save As:** temp file in the target directory + `os.replace`; encryption + preserved with `PDF_ENCRYPT_KEEP`. Dirty state clears after success. +- **Export Flattened PDF:** save a copy to a temp file, open it, call + `Document.bake(annots=True, widgets=True)`, save the target. The open document + and source file are untouched. +- **Form values:** written with `set_field_value` (which calls `widget.update()` + to regenerate appearances) before the atomic document save. + +## Undo / redo + +Snapshot-based per tab: each edit pushes a deep copy of the editable-object list. +Undo/redo applies a snapshot by removing all OpenReader objects and re-adding the +snapshot. Image bytes are immutable and shared between snapshots. Form fields use +native widget undo; global undo covers text/signature/image objects. + +## Coordinates + +- Stored in PDF points. +- GUI conversion: `label_px = (pdf_point − page.rect.origin) × zoom + 1` + (1 px = page-label border/content offset). +- Works in continuous and single-page modes; overlays live on the persistent + page QLabels, so scrolling and the virtualized renderer do not break editing. +- Pages with a non-zero `/Rotate` refuse editing with a clear status message. + +## UI + +- Main toolbar adds **Fill | Add Text | Sign | Image** as compact vector buttons. +- Fill shows the Form Navigator and focuses the first field; fields are always + directly editable (no separate form mode). +- A contextual `ContextToolbar` row appears for the selection: font family, size, + color, B/I/U, alignment, rotate, duplicate, delete and Done (inline editor). + Image/signature selections show rotate/duplicate/delete only. +- Inline text editor commits on Ctrl+Enter or Done; Escape cancels; selecting + another object commits. +- Dirty indicators: `●` in the tab and window title; close prompts Save / Discard / + Cancel. + +## Safety + +- Signature fields (`/FT /Sig`) trigger an explicit warning before editing and + before saving a dirty document; Save As Copy is offered. +- Encrypted documents are treated as read-only for editing. Encryption is captured + at open time because PyMuPDF 1.28 corrupts its decryption state if + `needs_pass`/`permissions` are read after `authenticate()`. +- Pages with `/Rotate` are read-only. +- Existing annotations, links, bookmarks and metadata are preserved by full saves. +- No cryptographic signing is performed; signatures are visual electronic + signatures and are labelled as such. + +## Limitations (v1.3.0) + +- Text rotation: 0/90/180/270 only (FreeText `/Rotate`). +- Text fonts: Base-14 Helvetica / Times New Roman / Courier New. +- User-added text is selectable; signatures/images are raster images. +- Arbitrary pre-existing embedded text editing is out of scope. +- Certificate-based digital signatures and signing workflows are out of scope. +- Rotated pages and encrypted documents are read-only for editing. + +## Testing + +- `tests/test_form_fields.py` — AcroForm engine, type detection, validation, state. +- `tests/test_edit_objects.py` — text/image metadata, reopen, undo state, atomic + save, flattened export, signature detection, encrypted save. +- `tests/test_signature_store.py` — local signature library lifecycle. +- `tests/test_edit_gui.py` — offscreen end-to-end text/image/signature editing, + inline commit, formatting, undo/redo, Save As, flatten, coordinate mapping, + continuous mode, rotated-page rejection, themes. +- Existing reader, scrolling, toolbar, security and packaging suites remain green. diff --git a/packages/mcp-server/src/openreader_mcp.egg-info/PKG-INFO b/packages/mcp-server/src/openreader_mcp.egg-info/PKG-INFO index 9926cf0..e4dd146 100644 --- a/packages/mcp-server/src/openreader_mcp.egg-info/PKG-INFO +++ b/packages/mcp-server/src/openreader_mcp.egg-info/PKG-INFO @@ -1,6 +1,6 @@ Metadata-Version: 2.4 Name: openreader-mcp -Version: 1.2.8 +Version: 1.3.0 Summary: AI assistant tools for PDFs — read, search, compare, merge, split, compress, and index PDFs locally. Author: Sparsh Sam License: AGPL-3.0-or-later From 1e31e626d311bdfa153abece998f7f67cdc29197 Mon Sep 17 00:00:00 2001 From: Sparsh Sam <110058692+sparshsam@users.noreply.github.com> Date: Sun, 8 Nov 2026 21:13:15 -0500 Subject: [PATCH 4/4] docs: v1.3.0 session handoff and next-session runtime testing plan Record the released v1.2.8 baseline, the implemented-but-unreleased v1.3.0 Fill/Edit/Sign branch and PR #107 (implementation head 7106ae5), test/CI status, backup branch 60038ca, known limitations, branching/CI/ versioning/release/Store workflows, and the isolated Windows runtime testing task for the next session. Documentation only: no application code, version, tag, release, branch protection, or Store changes. Co-Authored-By: Claude Code --- AGENTS.md | 186 ++++++++++++------------- CLAUDE.md | 403 +++++++++++++++++++++++------------------------------- 2 files changed, 261 insertions(+), 328 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c941812..23db99d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,98 +1,90 @@ -# Agent Maintenance Guide - -This repository is a local-first desktop PDF utility. Keep maintenance changes boring, explicit, and release-safe. - -## Product Boundaries - -**Current version:** v1.3.0 (2026-11-08) — Fill, Edit & Sign: native AcroForm filling, freeform text, visual signatures, and image placement (v1.2.8 continuous scrolling and toolbar retained) - -- Do not add new user-facing PDF features unless the task explicitly asks for them. -- Do not change the local-first privacy philosophy. -- Do not introduce network behavior beyond the explicit GitHub release update check (update detection only — no downloading or applying updates). -- Treat PDFs as local/private user data. - -## Editing Rules (v1.3.0+) - -- Keep the object model and persistence in `pdfreader_lib/edit_objects.py` **Qt-free**. GUI-only logic (overlays, inline editor, signature dialog, coordinate conversion) belongs in `pdfreader_lib/edit_gui.py`. -- Persist text as native `FreeText` annotations and signatures/images as image XObjects in page content, each carrying the `OpenReaderData` metadata key. Never persist edits as temporary overlays that disappear on save. -- Save atomically (temp file + `os.replace`) and preserve encryption with `PDF_ENCRYPT_KEEP`. Flattened export must operate on a copy, never the open original. -- Warn before editing/saving documents that contain `/FT /Sig` signature fields. Encrypted documents and pages with `/Rotate` are read-only for editing. -- Any change to the object model needs save → reopen round-trip tests. Any change to overlays needs continuous-scroll/zoom coordinate tests. -- Signature data is local-only. Do not add uploads, accounts, or cloud processing. - -## Release and Update Rules - -- The app detects updates via GitHub API and opens the releases page in a browser. It does not download or install updates. -- Canonical release assets must keep these exact names: - - `OpenReader-Windows.zip` - - `OpenReader-macOS-Apple-Silicon.zip` - - `OpenReader-macOS-Intel.zip` - - `OpenReader.msix` (MSIX package for Store submission/advanced use) - - `OpenReader-Setup.exe` (legacy Inno Setup installer) -- The Microsoft Store identity (`SparshSam.OpenReader`) is frozen — never change. -- Tag releases with `vMAJOR.MINOR.PATCH`. -- Packaged builds must inject the tag version into `main.py` via `scripts/inject_version.py`. -- Source builds may remain `-dev`. -- Update `docs/RELEASE.md` if release mechanics change. - -## Build and Test - -- Keep `build-windows.yml`, `build-macos.yml`, and `security.yml` passing. -- Use `.github/workflows/release.yml` as the canonical distribution workflow. -- Do not rename status check jobs casually because `main` branch protection depends on their contexts. -- Run Python syntax checks after editing Python: - - ```powershell - .\.venv\Scripts\python.exe -m py_compile main.py tools\create_icon.py scripts\inject_version.py +# Agent Maintenance Guide — OpenReader + +OpenReader is Kovina's **privacy-first, local-only** desktop PDF utility (Windows primary; macOS experimental; Linux unsupported). Read, annotate, search, compare, and from v1.3.0 **fill forms, add text, sign visually, and insert images** — all locally, with no accounts, subscriptions, cloud processing, telemetry, uploads, or internet access beyond the optional GitHub update check. + +Keep changes boring, explicit, and release-safe. Full architecture and command reference: [CLAUDE.md](CLAUDE.md); canonical architecture: [docs/Architecture.md](docs/Architecture.md). + +## Current State (2026-11-08) + +| Item | Value | +|---|---| +| **Latest published release** | **v1.2.8** — merge `57c29ea`, tag `v1.2.8`, release `https://github.com/sparshsam/openreader/releases/tag/v1.2.8` | +| **Current development version** | **v1.3.0 — Fill, Edit & Sign** — implemented, **NOT approved for release** | +| **Active branch** | `feat/v1.3.0-fill-edit-sign` | +| **Open PR** | **#107** — implementation head **`7106ae5`**; the documentation-handoff commit follows on the same branch/PR | +| **Backup branch** | `wip/v1.3.0-form-intelligence` at **`60038ca`** — unchanged; do not modify | +| **Tests** | **261 passed, 18 skipped**; CI green on the implementation head | +| **Installed app** | Untouched; no Store submission | +| **Branch protection** | PR required; 0 required approvals; required checks `Validate`, `Security`, `build`; admins enforced; force pushes/deletions blocked | + +## Immediate Next Task — next session only + +**v1.3.0 is implemented but NOT approved for release.** Begin the next session with **isolated Windows runtime testing**: + +1. Prepare an isolated v1.3.0 Windows dev environment (separate source copy, private venv/profile). +2. Preserve the installed OpenReader application and all previous dev environments. +3. Launch the real desktop GUI for Sparsh's manual testing. +4. Prepare realistic fixtures: interactive forms (all field types), non-interactive forms, long/multi-page PDFs, signed/encrypted samples, images/signatures. +5. Test form filling, freeform text/formatting, signature draw/type/import, images, Save, Save As, reopen, flattened export. +6. Verify continuous-scroll editing (scroll, zoom, resize, tabs). +7. Cross-viewer checks where possible (Acrobat/Edge/Chrome), including text selectability and preservation of links/bookmarks/metadata. +8. Fix defects, re-run tests/CI, then request release approval. + +Do not merge, tag, publish, or submit to the Store until Sparsh approves the runtime results. + +## Product Boundaries & Kovina Standards + +- **Privacy-first / local-first:** never upload or transmit PDFs, signatures, or user data; no accounts, subscriptions, or cloud processing. +- No network behavior beyond the optional GitHub update check (detection only) and the optional local MCP transport. +- Treat PDFs as private user data. Signature data is local-only. +- Kovina/OPEN branding: OPEN is typography only; the app icon belongs to OpenReader; brand accent `#ff255F`; never redesign the header lockup without instruction. See `docs/BRANDING.md`. +- Design/architectural decisions start from `docs/playbooks/`. +- Do not add user-facing features or refactor working code unless the task explicitly asks. + +## Editing & Form Rules (v1.3.0+) + +- `pdfreader_lib/form_fields.py` and `pdfreader_lib/edit_objects.py` are **Qt-free**. GUI logic (overlays, inline editor, signature dialog, coordinate conversion) belongs in `pdfreader_lib/edit_gui.py` / `main.py`. +- **Persist, don't paint over:** text is native `FreeText` annotations; signatures/images are image XObjects in page content; both carry the `OpenReaderData` metadata key. Never use temporary overlays that disappear on save. +- Save atomically (temp file + `os.replace`); preserve encryption with `PDF_ENCRYPT_KEEP`. Flattened export uses `Document.bake` on a copy, never the open original. +- Warn before editing/saving documents with `/FT /Sig` signature fields. Encrypted documents and `/Rotate` pages are read-only for editing. Never silently invalidate a signature. +- Object-model changes require save → reopen round-trip tests; overlay changes require continuous-scroll/zoom coordinate tests. +- Visual signatures are **not** certificate-based digital signatures; keep that distinction explicit. +- Known limits: 90° text rotation only; Base-14 text fonts; arbitrary existing embedded text editing and cryptographic signing out of scope. + +## Build, Test & CI Rules + +- Keep `Validate`, `Security`, and `build` passing; `main` branch protection depends on those exact check names — do not rename the jobs casually. +- Run the suite before pushing: + ```bash + QT_QPA_PLATFORM=offscreen python -m pytest tests/ -q + python -m py_compile main.py tools/create_icon.py scripts/inject_version.py ``` - -## Security Rules - -- Preserve PDF pre-validation and resource limits. -- Keep dependency pins deliberate. -- Do not remove `pip-audit`, Bandit, or Dependabot without replacing them. -- Avoid exposing raw exception internals in user-facing dialogs. - -## Documentation Rules - -- README should describe shipped behavior only. -- OpenReader does not install updates itself. Store installations update automatically; GitHub MSIX installations are manual. -- Keep Mac signing/Gatekeeper caveats visible until releases are signed and notarized. - -## MCP Server (AI Agent Integration) - -The repository ships two MCP server entry points: - -1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app. 19 tools, stdio + SSE transport. -2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`. - -**v1.3.0 (August 2026):** added five AcroForm tools — `form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate` — in both the bundled server and the standalone package. They share the form engine (`pdfreader_lib/form_fields.py` / `packages/mcp-server/src/openreader_mcp/_form_fields.py`) with the GUI's interactive form overlays. - -**Improvements made (June 2026):** -- All 14 tool descriptions rewritten as AI-optimized sentences (what it does, what it returns, when to use vs alternatives). -- Error messages tiered by type: validation errors, file-not-found, missing params, unexpected errors — each tells the agent what to fix. -- 43 tests added at `tests/test_mcp_server.py` covering registration, input validation, output shape, and error handling. -- Standalone package created at `packages/mcp-server/` — users install with one `pip install` command, no repo clone needed. - -**Maintenance rules:** -- `pdfreader_lib/mcp_server.py` must stay in sync with the feature set in `main.py`. -- When adding a new PDF operation to the GUI, add a matching MCP tool. -- Do not introduce network behavior beyond the existing GitHub release check (update detection only — no download) and MCP transport. -- The MCP server is optional — it does not affect the desktop GUI or packaged builds. -- Keep `requirements-mcp.txt` minimal (only `mcp` SDK required for stdio mode). -- When adding a tool to the bundled server, add it to `packages/mcp-server/` too. -- Agent config uses `"args": ["-m", "openreader_mcp"]` for standalone, `"args": ["-m", "pdfreader_lib.mcp_server"]` for bundled. - -## Landing Page & Docs - -OpenReader has a showcase landing page at **https://reader.kovina.org** (Cloudflare Pages). - -- **Source:** `site/` — static HTML + CSS. Huninn font, `#ff255F` accent, dark/light toggle. -- **Pages:** `index.html` (home), `docs/index.html` (MCP setup guide), `privacy.html` (Privacy Policy), `terms.html` (Terms of Service). -- **Footer:** All pages include links to Privacy, Terms, GitHub, and Microsoft Store. -- **Features:** Hero → Story → SVG feature icons → MCP/AI section with copy-paste prompt → CTA. -- **MCP prompt box:** Users click Copy, paste to any AI assistant to set up `python -m openreader_mcp`. -- **Docs page:** `site/docs/index.html` — full MCP setup guide for Claude Code, Desktop, Cursor. -- **Deploy:** Auto via `.github/workflows/deploy-site.yml` on push to `main` touching `site/`. Manual via `npx wrangler pages deploy site/ --project-name reader`. -- **Branding:** See [docs/BRANDING.md](docs/BRANDING.md) for the Open Product Family branding architecture, header lockup rules, and ecosystem hierarchy. -- **Privacy & Legal:** See `CLAUDE.md` → "Privacy & Legal Pages" for the full reference on legal page content, customisation, and update checklist. +- Current suite: **261 passed, 18 skipped**; packaging tests 7/7; Bandit clean. +- Preserve PDF pre-validation, resource limits, dependency pins, pip-audit, Bandit, and Dependabot. +- Do not expose raw exception internals in user-facing dialogs. +- When pushing with `gh`/`git` in this environment, prefix with `env -u GITHUB_TOKEN` (an invalid env token shadows the working login). + +## Versioning, Release & Store Rules + +- Canonical version: `main.py __version__`; propagate with `python scripts/inject_version.py ` (MCP pyproject/PKG-INFO + MSIX manifests for strict semver). +- Tags are **immutable** (`vMAJOR.MINOR.PATCH`); never retag. If a release fails, ship a patch version. +- **Release workflow is two-phase:** tag push builds artifacts only (Publish job gated); after verification, publish with `gh workflow run release.yml --ref vX.Y.Z -f publish=true`. MSIX generation is mandatory. +- Canonical assets: `OpenReader-Windows.zip`, `OpenReader-macOS-Apple-Silicon.zip`, `OpenReader-macOS-Intel.zip`, `OpenReader.msix`, `OpenReader-Setup.exe`. +- Microsoft Store: upload the production `OpenReader.msix` to Partner Center (Store ID `9MXDVW2645LL`); Store signs it. **Never submit without explicit approval.** Do not modify an installed copy during testing. +- Frozen identity: `SparshSam.OpenReader` · `CN=E6186421-BF8A-47E0-A89C-0F513DFF91C0` · PFN `SparshSam.OpenReader_yh0byntbzd2qw` · Store ID `9MXDVW2645LL`. +- Update `docs/store-acceptance-checklist.md` for the version being submitted; run it after Store acceptance. + +## MCP Server (19 tools) + +- Bundled: `pdfreader_lib/mcp_server.py` (stdio + SSE). Standalone: `packages/mcp-server/` (`pip install openreader-mcp`, `python -m openreader_mcp`). +- Five form tools added in v1.3.0: `form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate`; they share `form_fields.py`. +- Keep the bundled server and standalone package in sync (including `_form_fields.py`). Keep `requirements-mcp.txt` minimal; the SDK is constrained to **`mcp>=1.0.0,<2`** (MCP 2.x changed the server API). +- The MCP server is optional and must not affect the desktop GUI or packaged builds. + +## Documentation & Site + +- README describes **shipped** behavior only. +- `docs/Architecture.md` is canonical; keep `CHANGELOG.md` current (Keep a Changelog); keep macOS experimental caveats visible. +- Design specs live in `docs/superpowers/specs/` (forms 2026-08-02; Fill/Edit/Sign 2026-11-08). +- Landing site `site/` → `https://reader.kovina.org` (Cloudflare Pages; auto-deploys on `main` changes under `site/`). +- Keep the Privacy Policy and Terms pages in sync; update their "Last updated" date on material changes. diff --git a/CLAUDE.md b/CLAUDE.md index 64b693a..4fdd649 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,262 +1,203 @@ -# OpenReader — Agent Instructions +# OpenReader — Agent Instructions & Session Handoff -## Overview +## What OpenReader Is -**Latest update:** v1.3.0 — Fill, Edit & Sign: native form filling, freeform text objects, visual signatures, image placement (2026-11-08) +Privacy-first, **local-only** desktop PDF utility for Windows (macOS experimental; Linux unsupported). Read, annotate, search, compare, merge/split/compress — and, from v1.3.0, **fill forms, add text, sign visually, and insert images** — without accounts, subscriptions, cloud processing, uploads, or internet access. The only network call is the optional GitHub update check (detection only; no downloads). -Privacy-first, local-only desktop PDF utility for Windows. -macOS experimental; Linux unsupported. +**Stack:** Python 3.11–3.14 · PySide6 6.11.1 (Qt 6) · PyMuPDF 1.28.2 · Pillow · PyInstaller (Windows/macOS packaging) · Inno Setup (legacy installer) · MSIX (Windows/Store). -## Version History +## Current Repository State (2026-11-08) -| Version | Date | Summary | -|---------|------|---------| -| v1.3.0 | 2026-11-08 | Fill, Edit & Sign — AcroForm filling, freeform text objects, visual signatures, image placement; 5 new MCP form tools | -| v1.2.8 | 2026-11-08 | Continuous scrolling rebuilt as a virtualized full-document layout; unified 44 px Fluent toolbar with vector icons; light/dark chrome redesign; tab page-controls fix | -| v1.2.7 | 2026-08-02 | Store-aware updates — install-source detection, channel-aware Software Updates dialog, persisted skip + last-checked | -| v1.2.6 | 2026-08-02 | Default Reader Experience — Windows UserChoice detection, Settings dialog, first-launch default prompt | -| v1.2.5 | 2026-08-02 | Windows File Association Fix — MSIX `.pdf` association, ChangesAssociations, single-source version injector, changelog cleanup | -| v1.2.5 | 2026-07-03 | OpenPalette canonical spec, 155 assets from PNG via Lanczos, RGBA transparency fix, dual-image CSS dark/light transition, reader.kovina.org deployed to Cloudflare Pages | -| v1.2.5 | 2026-07-02 | Open Product Family branding alignment — header lockup, docs/BRANDING.md, icon generation pipeline, dark/light theme icon | -| v1.2.4 | 2026-06-28 | (previous release) | +| Item | Value | +|---|---| +| **Latest published release** | **v1.2.8** — merge commit `57c29ea`, annotated tag `v1.2.8`, release `https://github.com/sparshsam/openreader/releases/tag/v1.2.8` | +| **Current development version** | **v1.3.0 — Fill, Edit & Sign** — implemented, **NOT approved for release** | +| **Active branch** | `feat/v1.3.0-fill-edit-sign` | +| **Open PR** | **#107** — https://github.com/sparshsam/openreader/pull/107 — implementation head **`7106ae5`**; the documentation-handoff commit follows on this branch and is the current PR head | +| **Backup branch** | `wip/v1.3.0-form-intelligence` at **`60038ca`** — unchanged; do not modify | +| **Tests** | **261 passed, 18 skipped** (local Python 3.14 and CI Python 3.11) | +| **CI** | All checks green on the implementation head: Validate, Security, python-security, Windows build (MSIX), macOS Apple Silicon + Intel, CodeQL/Analyze, Cloudflare Pages | +| **Branch protection** | PR required; **0 required approvals**; required checks `Validate`, `Security`, `build`; admins enforced; force pushes/deletions blocked | +| **Installed app** | Untouched; no Microsoft Store submission | -## Architecture Constraints +### Immediate Next Task — next session only -1. **Local-first.** No cloud dependency. No network calls beyond the optional GitHub release update check (no downloads). -2. **Privacy by design.** Treat PDFs as local/private user data. Never upload or transmit document content. -3. **Cross-platform** (Windows primary, macOS experimental). +**v1.3.0 is implemented but NOT approved for release.** The next session must begin with **isolated Windows runtime testing** (do not start it in the documentation session): -## Distribution and Updates +1. Prepare an isolated v1.3.0 Windows development environment (separate source copy + private venv/profile; do not reuse the installed app's data). +2. Preserve the existing installed OpenReader application and all previous development environments. +3. Launch the actual desktop GUI for Sparsh's manual testing. +4. Prepare realistic PDF fixtures: interactive AcroForm forms (all field types), non-interactive printed forms, long documents, multi-page documents, signed/encrypted samples, images and signatures. +5. Test interactive and non-interactive form filling, freeform text and formatting, signature draw/type/import/place, image insertion, Save, Save As, reopen, and flattened export. +6. Verify editing in **continuous-scroll mode** (scroll, zoom, window resize, tab switches). +7. Perform cross-viewer compatibility checks where possible (Acrobat, Edge, Chrome) and confirm text selectability, links/bookmarks/metadata preservation. +8. Fix any defects found, re-run tests/CI, and only then request release approval. -- **Microsoft Store** (live) — automatic updates through the Store. -- **GitHub MSIX** — advanced users, unsigned, requires Developer Mode for sideloading. -- **Legacy Setup.exe** — manual recovery only. -- The app detects updates via GitHub API (opens browser). It never downloads or runs installers. +Do **not** merge, tag, publish, or submit to the Store until Sparsh explicitly approves the runtime test results. -## Frozen Identity — Never Change +## Repository Structure -- Identity Name: `SparshSam.OpenReader` -- Publisher: `CN=E6186421-BF8A-47E0-A89C-0F513DFF91C0` -- PFN: `SparshSam.OpenReader_yh0byntbzd2qw` -- Store ID: `9MXDVW2645LL` - -## Commands - -### Development -```powershell -# Windows — run from source -python -m venv .venv -.\.venv\Scripts\Activate.ps1 -pip install -r requirements.txt -python main.py - -# Build packaged executable -.\scripts\build_windows.ps1 -``` - -### Build verification -```bash -# Syntax check -python -m py_compile main.py tools/create_icon.py scripts/inject_version.py ``` - -### Testing -```bash -python -m pytest tests/ -v +main.py PySide6 application (window, toolbar, page rendering, + form overlays, edit overlays, save/dirty/close flows) +pdfreader_lib/ + form_fields.py Qt-free AcroForm engine (fields, type detection, + advisory validation, local form-state store) + edit_objects.py Qt-free text/signature/image model + persistence, + atomic save, flattened export, signature detection + edit_gui.py Per-tab EditController, overlays, inline text editor, + signature draw/type/import dialog, undo/redo + signature_store.py Local-only PNG signature library + mcp_server.py Bundled MCP server (19 tools, stdio + SSE) + search_index.py SQLite FTS5 + TF-IDF search + comparison.py Page-by-page PDF comparison + install_source.py source / MSIX / Setup / portable detection + win_default_apps.py Windows default-PDF-reader detection +packages/mcp-server/ Standalone openreader-mcp pip package + src/openreader_mcp/server.py + _form_fields.py +assets/ branding, icons, screenshots +docs/ Architecture, RELEASE, VERSIONING, BRANDING, + playbooks, superpowers design specs +packaging/msix/ AppxManifest.xml, AppInstaller.xml +installer/ Inno Setup script +scripts/ inject_version.py, build scripts, icon generation +site/ reader.kovina.org (Cloudflare Pages) +tests/ pytest suites (forms, editing, scrolling, toolbar, + MCP, packaging, security, updater) +.github/workflows/ ci, security, build-windows, build-macos, release, + deploy-site ``` -## Release Rules - -- Canonical release asset names: - - `OpenReader-Windows.zip` - - `OpenReader-macOS-Apple-Silicon.zip` - - `OpenReader-macOS-Intel.zip` - - `OpenReader.msix` (MSIX package) - - `OpenReader-Setup.exe` (legacy installer) -- MSIX identity (`SparshSam.OpenReader`) is frozen — never change. -- Tag releases with `vMAJOR.MINOR.PATCH`. -- Version injected from tag via `scripts/inject_version.py`. -- Source builds remain `-dev`. -- Update `docs/RELEASE.md` if release mechanics change. - -## Workflow - -1. Branch from `main`. Branch naming: `/`. -2. PR for every merge. No direct pushes to `main`. -3. Run lint/tests before creating a PR. -4. Do not change application behavior beyond what the task requests. -5. Do not add new features unless explicitly asked. - -## Documentation Rules - -- README should describe shipped behavior only. -- docs/Architecture.md is the canonical architecture reference. -- docs/VERSIONING.md documents the versioning scheme. -- Keep CHANGELOG.md updated per Keep a Changelog format. -- Keep Mac caveats visible for experimental platform status. +## v1.3.0 Functionality -## Security Rules +### Fill +- Native AcroForm overlays: text/multiline, checkbox, radio groups, combo, listbox; existing values preserved; read-only/required/max-length/password/comb rules. +- Tab/Shift+Tab navigation; accessible names; field highlights. +- Field type detection (explicit vs. inferred), advisory validation, date picker, persisted overrides. +- Form Navigator (status, next/previous, clear, completion review), autosave/recovery, recent-file form markers. +- Non-interactive forms completed with **Add Text**. -- Validate `.gitignore` coverage for `.env` and secret files before every commit. -- Preserve PDF pre-validation and resource limits. -- Keep dependency pins deliberate. -- Do not expose raw exception internals in user-facing dialogs. -- If a secret is accidentally exposed, report immediately. Do not fix silently. +### Add Text +- Click-to-place multiline text objects; inline editor (Ctrl+Enter/Done); auto-grow boxes. +- Drag, resize, rotate in 90° steps, duplicate, copy/paste, delete; snapshot undo/redo. +- Contextual bar: Helvetica/Times New Roman/Courier New, size, color, bold/italic/underline, left/center/right. +- Native `FreeText` annotations with `OpenReaderData` metadata — reopens editable and remains selectable in other viewers. -## MCP Server +### Sign +- Draw (mouse/touch/pen/trackpad), Type (installed signature-style fonts with preview), Import (PNG/JPEG/BMP/WebP/GIF, transparency), and Saved signatures. +- Place anywhere, drag, proportional resize, rotate, duplicate, remove, multi-page. +- Local-only signature library with delete/clear; **visual electronic signature**, not certificate-based. -The repository ships two MCP server entry points: +### Images +- Insert common formats; position, proportional resize, rotate, duplicate, delete. -1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app source. 19 tools, stdio + SSE transport. - - All tool descriptions rewritten as AI-optimized sentences (what, returns, when-to-use). - - Error messages are tiered: validation, file-not-found, missing params, unexpected errors. - - Tests at `tests/test_mcp_server.py` — 58 tests covering registration, validation, output shape, error handling. - - Form tools (`form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate`) added in v1.3.0 — they share the AcroForm engine with the GUI via `pdfreader_lib/form_fields.py`. +### Persistence & Safety +- Atomic Save / Save As; **Export Flattened PDF** via `Document.bake` on a copy (original untouched). +- Dirty indicators in tab/window title; Save / Discard / Cancel on close. +- Existing annotations, links, bookmarks, metadata preserved. +- Digital-signature fields warn before editing/saving; encrypted docs and `/Rotate` pages are read-only for editing. +- Editing works directly in virtualized continuous scroll at any zoom. -2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`. - - Mirrors the bundled server but imports bundled `_search_index`, `_comparison`, and `_form_fields` modules. - - `pyproject.toml` defines metadata. Update whenever `pdfreader_lib/mcp_server.py` gains new tools. +### MCP +- Five form tools (`form_list_fields`, `form_get_field`, `form_set_value`, `form_fill`, `form_validate`) → **19 tools total**, mirrored in the standalone package. +- Optional SDK constrained to **`mcp>=1.0.0,<2`** (v1.3.0 server uses the 1.x API). -### Rules +## Architecture Rules -- `pdfreader_lib/mcp_server.py` must stay in sync with `main.py`'s feature set. -- When adding a new PDF operation to the GUI, add a matching MCP tool. -- Keep `requirements-mcp.txt` minimal (only `mcp` SDK required for stdio mode). -- When adding a tool to the bundled server, add it to `packages/mcp-server/` too. -- Agent config uses `"args": ["-m", "openreader_mcp"]` (standalone) or `"args": ["-m", "pdfreader_lib.mcp_server"]` (bundled). +1. **Local-first / privacy by design.** No cloud, accounts, telemetry, or uploads. PDFs and signatures stay local. +2. **Qt-free model.** `form_fields.py` and `edit_objects.py` must not import PySide6; GUI logic stays in `edit_gui.py`/`main.py`. +3. **Persisted, not painted on top.** Text = native `FreeText` annotations; signatures/images = image XObjects in page content; both carry `OpenReaderData` JSON metadata for re-editing. Never use temporary overlays that vanish on save. +4. **Coordinates in PDF points.** The GUI converts to/from page-label pixels with the active layout zoom; editing must survive scrolling, zoom, resize, and tab switches. +5. **Safe writes.** Temp file + `os.replace`; preserve encryption with `PDF_ENCRYPT_KEEP`; flatten a copy, never the open original. +6. **Do not silently invalidate signatures.** Warn on `/FT /Sig` documents; encrypted documents and rotated pages are read-only for editing. +7. **Preserve the v1.2.8 reader.** Continuous scrolling, unified toolbar, themes, annotations, search, tabs and existing shortcuts must keep working. -## PDF Form Intelligence (v1.3.0+) +## Testing -- **Shared engine:** `pdfreader_lib/form_fields.py` is pure logic (no PySide6 imports) and is consumed by both the GUI and the MCP server. Keep GUI form logic out of the module. -- **GUI:** native Qt overlay widgets are positioned over AcroForm field rects per page (Approach A), managed per-tab by `_FormController` in `main.py`. Overlays are rebuilt on every render (`detach_all()` before continuous-mode rebuilds). -- **Type detection** (`FormTypeDetector`) distinguishes explicit (PDF formatting rule) from inferred (name/label) types — inference is always advisory, never enforced. User overrides persist outside the PDF via `FormStateStore`. -- **Validation** (`FormValidator`) is advisory and international-tolerant; it writes `validation_message`, never blocks input. -- **Rules:** when adding a new form operation, mirror it in the bundled server and `packages/mcp-server/` (copy `_form_fields.py` too). See `docs/superpowers/specs/2026-08-02-pdf-form-intelligence-design.md` for the full spec. - -## Editing — Add Text, Signatures & Images (v1.3.0) - -- **Model / persistence:** `pdfreader_lib/edit_objects.py` is Qt-free. Text is stored as native `FreeText` annotations with an `OpenReaderData` metadata key on the annotation xref; signatures and images are page-content image XObjects carrying the same metadata key. This is what makes objects survive save/reopen and remain re-editable in OpenReader. Never store edits as temporary overlays. -- **GUI:** `pdfreader_lib/edit_gui.py` owns the per-tab `EditController`, selection/resize overlays on the persistent continuous page labels, the inline text editor, the signature draw/type/import dialog, and snapshot-based undo/redo. Coordinate conversion belongs here (PDF points ↔ page-label pixels), never in the model. -- **Signatures:** `pdfreader_lib/signature_store.py` is a local PNG library under the app data directory. It has per-entry delete and clear-all; nothing is ever uploaded. -- **Save/export:** saves are atomic (temp file + `os.replace`) and preserve the document's encryption via `PDF_ENCRYPT_KEEP`. Export Flattened PDF uses `Document.bake(annots=True, widgets=True)` on a copy, never the open original. -- **Safety:** documents with `/FT /Sig` signature fields warn before editing/saving. Encrypted documents and pages with `/Rotate` are read-only for editing. Never silently invalidate a signature. -- **Limitations:** text rotation is 90° steps only (FreeText); text fonts are Base-14 Helvetica/Times/Courier; editing arbitrary pre-existing embedded text and certificate-based signing are out of scope. Form-field value changes use native widget undo; the global undo stack covers editable objects. -- **Spec:** `docs/superpowers/specs/2026-11-08-fill-edit-sign-design.md`. - -## Design Playbooks - -Three canonical playbooks govern all design and architecture decisions. Loaded at `docs/playbooks/`: - -| File | What it covers | -|------|---------------| -| `docs/playbooks/PRODUCT_ARCHITECTURE_PLAYBOOK.md` | Structural canvas — spatial system, grids, containers, responsive, layout archetypes, reading tempo, motion | -| `docs/playbooks/DESIGN_PLAYBOOK.md` | Visual design — machine metaphor, color, typography, component rules, buttons, navigation, states | -| `docs/playbooks/MCP-SERVER-BUILD-GUIDE.md` | MCP server blueprint — SHA-256 token auth, Streamable HTTP, user isolation, tool patterns, testing | +```bash +# Full suite (offscreen Qt) +QT_QPA_PLATFORM=offscreen python -m pytest tests/ -q -**Every design or architectural decision starts from these playbooks first.** +# Syntax check +python -m py_compile main.py tools/create_icon.py scripts/inject_version.py +``` -## Branding Architecture +- Current: **261 passed, 18 skipped** (pre-existing skips). +- New v1.3.0 suites: `test_edit_objects.py` (16), `test_edit_gui.py` (16), `test_signature_store.py` (5), plus the ported form/MCP suites (`test_form_fields.py`, `test_form_gui.py`, `test_mcp_server.py`). +- Packaging: `tests/test_packaging.py` — 7/7 (version alignment, frozen identity, `.pdf` association, MinVersion). +- CI required checks: **`Validate`** (compile + pytest), **`Security`** (pip-audit + Bandit), **`build`** (Windows PyInstaller + MSIX). Also run: macOS builds, python-security, CodeQL/Analyze, Cloudflare Pages. + +## Known Limitations & Outstanding Verification + +**Limitations (v1.3.0):** +- Text rotation: 90° increments only (FreeText `/Rotate`). +- Text fonts: Base-14 Helvetica / Times New Roman / Courier New. +- User-added text is native/selectable; signatures and images are raster content. +- Editing arbitrary pre-existing embedded PDF text is out of scope. +- Certificate-based digital signing is out of scope (visual signatures only). +- Encrypted documents and `/Rotate` pages are read-only for editing. +- Form-field value changes use native widget undo; the global undo stack covers editable objects. + +**Still to verify before release approval:** +1. **Isolated Windows runtime manual test** (the next session's first task). +2. Cross-viewer round-trip (Acrobat/Edge/Chrome): text selectability, images/signatures, flattened output, links/bookmarks/metadata. +3. Signature draw/import dialogs and real pen/touch input on Windows. +4. Signed-document warning UX and encrypted/read-only behavior on real files. +5. MSIX install/update compatibility with the existing installed copy (without modifying it). +6. CI currently builds the **test** MSIX: package version `1.3.0.0`, app version `1.3.0-test`. The production package must be built from the `v1.3.0` tag (app version `1.3.0`). + +## Branching, CI, Versioning, Release & Store + +### Branching / CI +- Branch from `main`; naming `/`; PR for every merge (no direct pushes). +- Branch protection: PR required, 0 required approvals, required checks `Validate`, `Security`, `build`; admins enforced; no force pushes/deletions. Do not rename those job contexts casually. +- Workflows: `ci.yml` (Validate/Security), `security.yml` (python-security/CodeQL), `build-windows.yml` (PR/main; builds PyInstaller ZIP + Inno Setup + unsigned MSIX), `build-macos.yml`, `release.yml` (tag build-only; publish via manual dispatch), `deploy-site.yml`. +- When using `gh`/`git` push in this environment, prefix with `env -u GITHUB_TOKEN` (an invalid `GITHUB_TOKEN` shadows the working login). + +### Versioning +- Canonical source: `main.py` `__version__`; propagate with `python scripts/inject_version.py ` (also updates MCP pyproject/PKG-INFO and MSIX manifests when strict semver). +- `source` builds may be `-dev`/`-test`; MSIX manifests require `x.y.z.0`. +- Tags are **immutable**; never retag. If a release fails, ship a patch version. + +### Release +1. Merge the approved PR; tag the merge commit with an **annotated** `vX.Y.Z`; push the tag. +2. The tag run builds `OpenReader.msix`, `OpenReader-Setup.exe`, `OpenReader-Windows.zip`, and the macOS ZIPs **without publishing** (Publish job gated). +3. Verify the MSIX identity/version and version metadata. +4. Publish explicitly: `gh workflow run release.yml --ref vX.Y.Z -f publish=true`. +- Canonical asset names: `OpenReader-Windows.zip`, `OpenReader-macOS-Apple-Silicon.zip`, `OpenReader-macOS-Intel.zip`, `OpenReader.msix`, `OpenReader-Setup.exe`. +- MSIX generation is mandatory; the release fails without it. + +### Microsoft Store +- Upload the production `OpenReader.msix` to Partner Center (Store ID `9MXDVW2645LL`); Microsoft signs it. +- **Never submit without Sparsh's explicit approval.** Do not modify an installed copy during testing. +- Post-release acceptance: `docs/store-acceptance-checklist.md` (update to the current version when submitting). + +### Frozen identity — never change +`SparshSam.OpenReader` · Publisher `CN=E6186421-BF8A-47E0-A89C-0F513DFF91C0` · PFN `SparshSam.OpenReader_yh0byntbzd2qw` · Store ID `9MXDVW2645LL`. + +## Kovina Standards + +- **Privacy-first, local-first, open-source.** No accounts, subscriptions, cloud processing, telemetry, or uploads; signatures remain local. +- **Open Product Family branding:** KOVINA → OPEN → Reader. OPEN is typography only (no icon); the app icon belongs to OpenReader. Brand accent `#ff255F`. See `docs/BRANDING.md`; never redesign the header lockup without instruction. +- **Design decisions start from `docs/playbooks/`** (Product Architecture, Design, MCP Server Build Guide). +- **Docs discipline:** README describes shipped behavior only; `docs/Architecture.md` is canonical; keep `CHANGELOG.md` current (Keep a Changelog); keep macOS experimental caveats visible; update `docs/RELEASE.md` if release mechanics change. +- **Security:** preserve PDF pre-validation/resource limits; keep dependency pins deliberate; never expose raw exception internals in user dialogs; report accidental secret exposure immediately. + +## Useful Commands -### Hierarchy +```powershell +# Windows source run +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +pip install -r requirements.txt +python main.py -``` -KOVINA Parent ecosystem → kovina.org/standards/KOVINA_MANIFESTO.md - ↓ -OPEN Product family → kovina.org/standards/BRAND_GUIDELINES.md - ↓ -Reader Individual product → docs/BRANDING.md +# Packaged build +.\scripts\build_windows.ps1 ``` -- **OPEN has no icon.** No symbol, no badge, no monogram. Typography only. -- The application icon belongs only to OpenReader, never to OPEN. -- Do not merge the icon into the typography lockup. -- Do not create a combined logo mark. -- The header lockup is: `[icon] OPEN / Reader` (stacked, icon on left). -- Never redesign the header lockup without explicit instruction. -- Kovina standards are authoritative. OpenReader inherits them. -- OpenPalette is the canonical reference implementation for the Open Product Family branding. -- Brand accent: `#ff255F` pink-red. -- See [docs/BRANDING.md](docs/BRANDING.md) for complete product-specific branding documentation. - -### Icon Generation Pipeline (v1.2.5) - -- **Source art:** `openreader_light_mode.png` (1024x1024 PNG) -- **Resampling:** Lanczos (high-quality) via `scripts/generate-icons.js` -- **Total assets:** 155 across all target formats -- **Formats:** Windows ICO (multi-resolution), MSIX assets, Android adaptive icons, iOS/macOS app icons, Web/PWA favicons (incl. SVG), social OG image (1200x630), GitHub avatar/profile icons, header icon for app chrome -- **Automation:** GitHub Actions workflow `.github/workflows/generate-icons.yml` runs on icon source change detection - -### Header Lockup - -```html - +```bash +# Tests / compile +QT_QPA_PLATFORM=offscreen python -m pytest tests/ -q +python -m py_compile main.py tools/create_icon.py scripts/inject_version.py ``` - -- OPEN: uppercase, bold, 0.06em tracking, muted 50% opacity -- Reader: title case, medium weight, primary text color -- Icon: 28px mobile / 32px desktop, 6px border-radius -- OpenPalette alignment (v1.2.5): product Reader `font-medium -mt-0.5 leading-tight`; icon wrapper `margin-top: -1px` for optical centering against text ascender -- Themed icon (v1.2.5): CSS `transition: all 0.3s ease` on app chrome icon for dark/light mode switching; same source image for both modes until dark-specific art is created - -## Landing Page - -OpenReader's showcase landing page at **https://reader.kovina.org**, hosted on Cloudflare Pages. - -- **Source:** `site/` — static HTML + CSS, no build step. -- **Font:** Huninn (rounded sans-serif), hosted TTF. -- **Accent:** `#ff255F` (pink/red). -- **Dark mode toggle:** sun/moon icon at right screen edge, persists to localStorage. -- **Features:** SVG icons replace numbered list. Hero icon at 512×512px. -- **Nav:** logo left, links centered, theme toggle far right. Seamless (no border). -- **Sections:** Hero → Story → Features (SVG icons) → MCP/AI (with copy-paste prompt) → Ribbon (#ff255F filled) → CTA → Footer. -- **MCP prompt box:** Click-to-copy JSON config users paste to any AI assistant. -- **Docs page:** `site/docs/index.html` — full MCP setup guide for Claude Code, Desktop, Cursor. - -### Deploy - -- **Manual:** `npx wrangler pages deploy site/ --project-name reader` (requires `CLOUDFLARE_API_TOKEN`). -- **Auto:** `.github/workflows/deploy-site.yml` deploys on push to `main` touching `site/`. - -## GitHub Repo - -- **Website URL:** `https://reader.kovina.org` -- **Description:** Includes Microsoft Store ID (`9MXDVW2645LL`) for discoverability. -- **Release page:** v1.2.4 release body has Store link at top + direct download assets below. - -## Privacy & Legal Pages - -The website at **reader.kovina.org** has dedicated legal pages: - -| Page | Path | Last Updated | -|------|------|-------------| -| Privacy Policy | `site/privacy.html` → `/privacy` | July 2, 2026 | -| Terms of Service | `site/terms.html` → `/terms` | July 2, 2026 | - -Both pages follow the standardised Kovina Privacy & Terms template. Key OpenReader-specific customisations: - -- **No cloud / no backup provider** — OpenReader is 100% offline. -- **Third-party services** — Lists Cloudflare (hosting), Microsoft Store, and GitHub (distribution) with privacy policy links. -- **Advice disclaimer** — "No Professional Advice" since OpenReader is a PDF tool. -- **Data deletion** — All local; no cloud data to delete. -- Footer on all three site pages (`index.html`, `privacy.html`, `terms.html`) includes Privacy + Terms links. - -### Update checklist -- When legal content changes, update both `site/privacy.html` and `site/terms.html`. -- The "Last updated" date must be updated on every material change. -- Cloudflare Pages auto-deploys on push to `main` touching `site/`. - -## App Identity Card - -| Property | Definition | -|----------|-----------| -| Core metaphor | Reading desk / Document workbench | -| Primary brand color | #ff255F (accent) | -| Emotional tone | Focused, calm | -| Main user action | Read & annotate PDFs | -| Navigation | Features · AI Access · Docs · Store · GitHub |