Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 89 additions & 86 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,87 +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.2.8 (2026-11-08) — virtualized continuous scrolling and the unified Fluent toolbar

- 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.

## 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. 14 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`.

**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 <version>` (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.
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 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 (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.
- **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.
Expand Down
Loading
Loading