diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7f2730a3..821b7de7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,12 +23,14 @@ jobs:
strategy:
fail-fast: false
matrix:
- os: [ubuntu-latest, macos-latest, windows-latest]
+ # No macOS on PRs, main or nightly: the org's 5 macOS slots are kept for release builds,
+ # and release.yml builds macOS (a failing release is fixed and rebuilt).
+ os: [ubuntu-latest, windows-latest]
steps:
- uses: actions/checkout@v4
# The optional craft-fonts build input (Japanese fonts), so the Japanese font tests run on
- # Linux; macOS and Windows test the build without it. See craftrules standards/fonts.md.
+ # Linux; Windows tests the build without it. See craftrules standards/fonts.md.
- name: Check out craft-fonts (Linux)
if: runner.os == 'Linux'
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md
index 4e3221a9..afe30062 100644
--- a/ATTRIBUTION.md
+++ b/ATTRIBUTION.md
@@ -4,7 +4,7 @@
Every asset PdfCraft includes, bundles or uses to build its published material, with its author, source and licence. The policy is in [AGENTS.md](AGENTS.md) §1. The machine-readable list, with SHA-256 hashes, is [ATTRIBUTION.toml](ATTRIBUTION.toml). Licence texts are kept beside the assets and summarised in [NOTICE](NOTICE).
-## In this repository (249)
+## In this repository (257)
| Asset | Title | Author | Licence | Source | Used for |
|---|---|---|---|---|---|
@@ -14,7 +14,13 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
| `crates/ui-egui/src/i18n/pt-br.tsv` | Brazilian Portuguese interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Brazilian Portuguese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
| `crates/ui-egui/src/i18n/es.tsv` | Spanish interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Spanish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
| `crates/ui-egui/src/i18n/fr.tsv` | French interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | French UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/de.tsv` | German interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | German UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/te.tsv` | Telugu interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Telugu UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/ru.tsv` | Russian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Russian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/hu.tsv` | Hungarian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Hungarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/bg.tsv` | Bulgarian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Bulgarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
| `crates/ui-egui/src/i18n/ja.tsv` | Japanese interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Japanese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/uk.tsv` | Ukrainian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Ukrainian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
| `assets/icons/accessibility.svg` | Lucide icon "accessibility" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/accessibility.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
| `assets/icons/align-left.svg` | Lucide icon "align-left" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/align-left.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
| `assets/icons/align-center.svg` | Lucide icon "align-center" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/align-center.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
@@ -257,6 +263,8 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
| `crates/sign/tests/data/openssl-signed.pdf` | One-page PDF signed with OpenSSL CMS (adbe.pkcs7.detached) by the RSA test key | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: hand-written PDF objects; signature made with `openssl cms -sign` over its byte ranges (see crates/sign/tests/data/README.md) | Signature validation tests (crates/sign/tests/pdf.rs): a signature PdfCraft did not make |
| `assets/icons/clipboard-paste.svg` | Lucide icon "clipboard-paste" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/clipboard-paste.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
| `assets/fonts/DancingScript.ttf` | Dancing Script (variable) | The Dancing Script Project Authors (Pablo Impallari) | OFL-1.1 | https://github.com/google/fonts/blob/9710da1eacb3be272583c3224dcb70f9da6eadbb/ofl/dancingscript/DancingScript%5Bwght%5D.ttf | Fill & Sign typed signatures and initials: the typed name's glyph outlines, drawn as filled paths (the font file itself is not embedded in PDFs) |
+| `packaging/macos/dmg/background.svg` | PdfCraft macOS DMG window background | @XusBadia | MIT OR Apache-2.0 | Original work for this repository, derived from the PdfCraft app icon (assets/app-icon/pdfcraft.svg, referenced via an SVG image element, not copied) | Finder window of the macOS DMG; rendered to background.tiff by packaging/macos/dmg/generate.py |
+| `packaging/macos/dmg/background.tiff` | PdfCraft macOS DMG window background (rendered) | @XusBadia | MIT OR Apache-2.0 | Rendered from packaging/macos/dmg/background.svg by packaging/macos/dmg/generate.py | 1x + 2x HiDPI 16-colour palette TIFF copied into the macOS DMG by packaging/macos/package.sh; includes the app icon and the free LittleCMS built-in sRGB profile |
## Compiled in through dependencies (6)
diff --git a/ATTRIBUTION.toml b/ATTRIBUTION.toml
index 36087581..b33510f3 100644
--- a/ATTRIBUTION.toml
+++ b/ATTRIBUTION.toml
@@ -19,7 +19,7 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Simplified Chinese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "5da2aa2944fcad4720972062f0f97800f73b8bfa5dd0fff6c28f4ec0f8ee19f9"
+sha256 = "2d56f8464f3c25efe9737b204db34cef012ea3716f4d78209d9abeaf0ea9393b"
[[asset]]
path = "crates/ui-egui/src/i18n/zh-hant.tsv"
@@ -30,7 +30,7 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Traditional Chinese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "39f83ab539f6380df995a855c1c8e8c036bcd060e06b9d1b027771e1e7d6e7ef"
+sha256 = "b0ca648560c45e554447aae8dba37c1c9c636c86b277d00fceeb2a21b474c8f7"
[[asset]]
path = "crates/ui-egui/src/i18n/cs.tsv"
@@ -41,7 +41,7 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Czech UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "accf181cff1f0ea86bb33528f6158d1aec18c9c3ff54de62dc758536a24cb677"
+sha256 = "8bab483a3f5ba3a724365c2a5a892291a10f41fdc443eaceb66f49c8a20cae20"
[[asset]]
path = "crates/ui-egui/src/i18n/pt-br.tsv"
@@ -52,7 +52,7 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Brazilian Portuguese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "0ee4d2f630623ef7e06413a7c34a4a0269a2600fba682f06988a1346be4d07a5"
+sha256 = "2cd5dcc6cf7e94914b955ee0f2f5c3e8951b16e26ab49fcb7111246a6e31ee2a"
[[asset]]
path = "crates/ui-egui/src/i18n/es.tsv"
@@ -63,7 +63,7 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Spanish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "4c409434bd3385b56b561c36ff819e19e574bda8979d16cd53232cb5bea3c65f"
+sha256 = "e9a9bad1252afdcb42c36b24ca85411f8c63df7debada94d4423bd48761ecb05"
[[asset]]
path = "crates/ui-egui/src/i18n/fr.tsv"
@@ -74,7 +74,62 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "French UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "d322ac956218961d22828726a7fe0752b0a68603679c2dcf17c5aa840995e124"
+sha256 = "0351382a91d2df51da3d45e25a09af87a081bc88e3496c3512ad89f5d4460a3a"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/de.tsv"
+title = "German interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "German UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "57f52e3671a322938a160ac11b73b1f55fb6311140f20d89ae12c9a91a0500d6"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/te.tsv"
+title = "Telugu interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Telugu UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "d3630f989e9725c22444dc27765142674b66f72436502ca969b2851fc38d703d"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/ru.tsv"
+title = "Russian interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Russian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "e505c00bcc8b8af6aec27abf84bebac7a1925c632130411000a6c57241816193"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/hu.tsv"
+title = "Hungarian interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Hungarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "c198f1de831d7f9c853baa6977894ccc34d94e6b36c772c2e53fc5b0e0fe708b"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/bg.tsv"
+title = "Bulgarian interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Bulgarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "9682b2c3c28449dc63637cb5962b309df3ad7db7e8d96bf8bb0f0bc386c9c611"
[[asset]]
path = "crates/ui-egui/src/i18n/ja.tsv"
@@ -85,7 +140,18 @@ licence = "MIT OR Apache-2.0"
licence_file = "LICENSE-MIT"
kind = "translation"
usage = "Japanese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "4b14f85bc0890823c30bff37723ecb05bc5ea5a8583334644168b08043ab6bde"
+sha256 = "319b032d2c50097ec14e2c7eab92e8696d33e198aeac3585ff46e98c61dec90f"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/uk.tsv"
+title = "Ukrainian interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Ukrainian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "f3a03fc466c1f956cbd44a5cad101c53db5ffc80b3b7551a273ac41f43263dd5"
[[asset]]
path = "assets/icons/accessibility.svg"
@@ -3083,6 +3149,29 @@ kind = "font"
usage = "Fill & Sign typed signatures and initials: the typed name's glyph outlines, drawn as filled paths (the font file itself is not embedded in PDFs)"
sha256 = "21808625578fe8d8cd10cb684be546dca077b27cd03a53a2f1ec11dc743c924c"
+[[asset]]
+path = "packaging/macos/dmg/background.svg"
+title = "PdfCraft macOS DMG window background"
+author = "@XusBadia"
+source = "Original work for this repository, derived from the PdfCraft app icon (assets/app-icon/pdfcraft.svg, referenced via an SVG image element, not copied)"
+licence = "MIT OR Apache-2.0"
+licence_file = "assets/app-icon/LICENSE.txt"
+kind = "image"
+usage = "Finder window of the macOS DMG; rendered to background.tiff by packaging/macos/dmg/generate.py"
+sha256 = "e8b9ea9d5e64b7b741c977543c1693825e77d5c4c579eeb674bf5dcd3764cd8a"
+
+
+[[asset]]
+path = "packaging/macos/dmg/background.tiff"
+title = "PdfCraft macOS DMG window background (rendered)"
+author = "@XusBadia"
+source = "Rendered from packaging/macos/dmg/background.svg by packaging/macos/dmg/generate.py"
+licence = "MIT OR Apache-2.0"
+licence_file = "assets/app-icon/LICENSE.txt"
+kind = "image"
+usage = "1x + 2x HiDPI 16-colour palette TIFF copied into the macOS DMG by packaging/macos/package.sh; includes the app icon and the free LittleCMS built-in sRGB profile"
+sha256 = "f46881724a6621f3686a612a79dbdce4f7dbe9e2025610e44c9a094341334c2c"
+
[[fetched]]
file = "text-detection.rten"
url = "https://ocrs-models.s3-accelerate.amazonaws.com/text-detection.rten"
diff --git a/Cargo.lock b/Cargo.lock
index 2520b60a..879c1cfd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3477,6 +3477,7 @@ dependencies = [
"hayro-syntax",
"pdfcraft-cos",
"pdfcraft-fonts",
+ "pdfcraft-model",
"thiserror 2.0.21",
]
@@ -3486,8 +3487,11 @@ version = "0.4.0"
dependencies = [
"base64 0.22.1",
"image",
+ "pdfcraft-cos",
"pdfcraft-engine",
+ "pdfcraft-model",
"pdfcraft-organize",
+ "pdfcraft-platform",
"pdfcraft-render",
"pdfcraft-xfa",
"png 0.18.1",
@@ -3566,6 +3570,7 @@ dependencies = [
"pdfcraft-fonts",
"pdfcraft-model",
"thiserror 2.0.21",
+ "unicode-bidi",
]
[[package]]
@@ -3573,6 +3578,8 @@ name = "pdfcraft-engine"
version = "0.4.0"
dependencies = [
"chrono",
+ "icu_properties",
+ "idna",
"image",
"pdfcraft-a11y",
"pdfcraft-annot",
@@ -3598,6 +3605,7 @@ dependencies = [
"pdfcraft-xfdf",
"png 0.18.1",
"thiserror 2.0.21",
+ "url",
]
[[package]]
@@ -3621,6 +3629,7 @@ dependencies = [
name = "pdfcraft-fonts"
version = "0.4.0"
dependencies = [
+ "harfrust",
"pdfcraft-cos",
"skrifa 0.44.0",
]
@@ -3634,6 +3643,7 @@ dependencies = [
"pdfcraft-cos",
"pdfcraft-fonts",
"pdfcraft-model",
+ "pdfcraft-render",
"thiserror 2.0.21",
]
@@ -3700,6 +3710,10 @@ dependencies = [
"thiserror 2.0.21",
]
+[[package]]
+name = "pdfcraft-platform"
+version = "0.4.0"
+
[[package]]
name = "pdfcraft-preflight"
version = "0.4.0"
@@ -3736,12 +3750,15 @@ dependencies = [
name = "pdfcraft-render"
version = "0.4.0"
dependencies = [
+ "bytemuck",
"getrandom 0.4.3",
"hayro",
"hayro-syntax",
"kurbo 0.13.1",
"log",
"lopdf",
+ "pdfcraft-fonts",
+ "skrifa 0.44.0",
"thiserror 2.0.21",
]
@@ -3777,6 +3794,7 @@ version = "0.4.0"
dependencies = [
"arboard",
"base64 0.22.1",
+ "bytemuck",
"eframe",
"egui",
"egui_extras",
@@ -3785,10 +3803,14 @@ dependencies = [
"image",
"js-sys",
"log",
+ "objc2 0.6.4",
+ "objc2-app-kit 0.3.2",
+ "objc2-foundation 0.3.2",
"pdfcraft-cos",
"pdfcraft-engine",
"pdfcraft-fonts",
"pdfcraft-model",
+ "pdfcraft-platform",
"pdfcraft-render",
"pdfcraft-xfa",
"png 0.18.1",
@@ -3822,9 +3844,12 @@ name = "pdfcraft-xfa"
version = "0.4.0"
dependencies = [
"base64 0.22.1",
+ "image",
"pdfcraft-cos",
"pdfcraft-fonts",
+ "png 0.18.1",
"roxmltree",
+ "sha2",
"thiserror 2.0.21",
]
@@ -6571,8 +6596,6 @@ checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
[[package]]
name = "winit"
version = "0.30.13"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d"
dependencies = [
"ahash",
"android-activity",
diff --git a/Cargo.toml b/Cargo.toml
index 8a1c3b65..e80a0b46 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -40,6 +40,7 @@ pdfcraft-forms = { path = "crates/forms", version = "0.4.0" }
pdfcraft-xfa = { path = "crates/xfa", version = "0.4.0" }
pdfcraft-render = { path = "crates/render", version = "0.4.0" }
pdfcraft-engine = { path = "crates/engine", version = "0.4.0" }
+pdfcraft-platform = { path = "crates/platform", version = "0.4.0" }
pdfcraft-ui-egui = { path = "crates/ui-egui", version = "0.4.0" }
pdfcraft-automation = { path = "crates/automation", version = "0.4.0", default-features = false }
@@ -74,8 +75,14 @@ unsafe_code = "forbid"
dbg_macro = "warn"
todo = "warn"
+# `"*"` matches every non-workspace package: crates.io dependencies and the
+# vendored crates under `vendor/` (excluded from the workspace). Our own crates
+# keep full debug info. Dependencies keep only line tables, so backtraces still
+# show file and line, but debug info for the whole dependency graph stays out of
+# every test binary (each UI test binary had a 500-600 MB PDB on Windows, #454).
[profile.dev.package."*"]
opt-level = 2
+debug = "line-tables-only"
[profile.dev]
opt-level = 1
@@ -91,3 +98,4 @@ hayro = { path = "vendor/hayro" }
hayro-syntax = { path = "vendor/hayro-syntax" }
hayro-jbig2 = { path = "vendor/hayro-jbig2" }
lopdf = { path = "vendor/lopdf" }
+winit = { path = "vendor/winit" }
diff --git a/README.md b/README.md
index e08d5551..43342478 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,7 @@ Search the whole document as you type, step through matches with ⌘G
## Navigate long documents
-Bookmarks, page thumbnails and the document's own page labels (i, ii, 1, 2…) keep you oriented in long documents.
+Bookmarks, page thumbnails and the document's own page labels (i, ii, 1, 2…) keep you oriented in long documents. Search bookmark titles in the Bookmarks panel to find nested entries even when their parents are collapsed. Matches keep their ancestors for context; Clear restores the unfiltered tree without changing its expansion state.
@@ -172,6 +172,8 @@ Open **Organize pages** to see every page at once:
- *Atomic:* the file is written to a temporary copy, then swapped in.
- *Verified:* independently checked with qpdf.
+When open documents exceed the window width, scroll over the tab strip with the mouse wheel or trackpad, or use its horizontal scrollbar. Opening or switching to a document brings its tab into view.
+
Unsaved documents carry a dot on their tab, and closing or quitting asks before anything is lost. Changes are autosaved every minute. If PdfCraft ever quits unexpectedly, it offers to recover your work the next time it opens. Encrypted documents stay encrypted on disk.
@@ -291,6 +293,8 @@ Every engine feature is reachable without the GUI, through one table of JSON-Sch
{ "mcpServers": { "pdfcraft": { "command": "pdfcraft-cli", "args": ["mcp", "--root", "/path/to/your/pdfs"] } } }
```
+ `--compact` shrinks the tool list the agent has to read: `tools/list` returns about ten core tools plus `tool_search` and `tool_call`, which find and run every other tool, so the list costs far fewer tokens. Every tool still works.
+
`--root` confines every file the agent can read or write to one directory. Builds that should not include the server at all can use `cargo build -p pdfcraft-cli --no-default-features`.
- **The Rust API** (`pdfcraft_automation::Automation::call`), for embedding.
@@ -418,6 +422,10 @@ The honest assessment by area, what's lacking and where we're going are in **[RO
Installers and executables are code-signed.
+The portable zip runs from any folder, a USB stick included. Its `portable.txt` keeps the settings,
+logs and crash recovery in a `PdfCraftData` folder next to `pdfcraft.exe`, so nothing is written to
+`%APPDATA%`; delete that file to use the normal per-user folders.
+
The MSI installs for all users and requires administrator privileges. For unattended deployment
without a desktop shortcut, run from an elevated terminal:
diff --git a/ROADMAP.md b/ROADMAP.md
index ecd96d48..ce510d9c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -79,7 +79,8 @@ The gaps that matter most, in priority order. Agents: prefer these over adding P
3. **Measure fidelity against Acrobat.** Build a side-by-side harness (render, text, form behaviour) over synthetic fixtures (`plan/acrobat/`, clean-room rules apply). Until then, parity numbers count features, not quality.
4. **Editing existing content (M7).** Fonts, subsets, reflow and CJK. The most visible gap for Pro users.
5. **Pro workflows.** Signatures with timestamps and LTV (M9), OCR beyond Latin (M10), Office import/export (M10), preflight and PDF/A/X/UA (M11), XFA (M12).
-6. **1.0 polish (M14).** Code-signed installers, localization (the catalog system is in place and French, Spanish, Japanese and both Chinese catalogs cover the UI; Czech and Brazilian Portuguese still cover menus only), keyboard-only operation, a full screen-reader audit.
+6. **1.0 polish (M14).** Code-signed installers, localization (the catalog system is in place and French, German, Spanish, Japanese, Russian and both Chinese catalogs cover the UI; Czech and Brazilian Portuguese still cover menus only), keyboard-only operation, a full screen-reader audit.
+6. **1.0 polish (M14).** Code-signed installers, localization (the catalog system is in place and French, Spanish, Japanese, Russian, Ukrainian and both Chinese catalogs cover the UI; Czech and Brazilian Portuguese still cover menus only), keyboard-only operation, a full screen-reader audit.
Decided against for now (owner, 2026-10-05): self-installing updates and an update check at start. Help ▸ Check for updates is manual only.
@@ -90,20 +91,21 @@ Hours are for a single agent (low–high). "Done" is the estimated fraction of t
| M | Milestone | Est. hours | Done | Remaining (h) | Notes |
|---|---|---|---|---|---|
| M0 | Skeleton: workspace, xtask gates, CI | 15–30 | 92% | 2–4 | GitHub workflow, `deny.toml` (licence audit of every dependency), parity checklist (826 features, `xtask parity`) done. Missing: remaining crate stubs, testkit/oracle crates |
-| M1 | COS: filters, crypt, parser, xref, writer | 120–200 | 78% | 25–45 | Done:
- filters and crypt: every standard-security revision R2–R6 (RC4, AES-128/256), SASLprep, permissions, creating encryption;
- cos: parse and repair (including invalid xref object-number ranges), decrypt on load, re-encrypt on save, incremental and full writing.
Corpus: open/edit/save passes on 958 files, and all 7 password-protected files open.
Full saves now pack objects into compressed object streams. Fuzzing runs nightly (`xtask fuzz`). Missing: ≥ 250 tests, own image codecs |
-| M2 | Model, render, text | 200–350 | 15% | 170–300 | hayro bootstrap renderer (vendored patches). Text extraction reaches word-F1 0.98 against pdftotext. Missing: model crate, fonts, DisplayList, renderer independent of hayro |
+| M2 | Model, render, text | 200–350 | 15% | 170–300 | hayro bootstrap renderer (vendored patches); inspector predictor scratch is bounded by available input. Text extraction reaches word-F1 0.98 against pdftotext. Missing: model crate, fonts, DisplayList, renderer independent of hayro |
+| M1 | COS: filters, crypt, parser, xref, writer | 120–200 | 78% | 25–45 | Done:
- filters and crypt: every standard-security revision R2–R6 (RC4, AES-128/256), SASLprep, permissions, creating encryption;
- cos: parse and repair (including invalid xref object-number ranges), decoded-stream limits including unfiltered data, decrypt on load, re-encrypt on save, incremental and full writing.
Corpus: open/edit/save passes on 958 files, and all 7 password-protected files open.
Full saves now pack objects into compressed object streams. Fuzzing runs nightly (`xtask fuzz`). Missing: ≥ 250 tests, own image codecs |
| M3 | Viewer app (native + web) | 80–150 | 88% | 10–19 | Acrobat-style shell, find, select, panels, tiles, web build, UI control channel for agents (opt-in). Missing: 60 fps test on a 500-page document, snapshot tests of every panel Done since: fit visible, document title in the window; Linux middle-button scrolling; shared three-state theme preferences in the toolbar, View menu and control channel. |
-| M4 | Engine, history, save, organize | 100–180 | 95% | 9–17 | Done:
- command registry (menus, shortcuts and palette all use it);
- undo/redo; incremental, atomic and encrypted saves;
- autosave and crash recovery;
- organize, combine, extract, split and insert-from-file, with identical fonts and images stored once;
- CLI `edit/combine/extract/split`.
Done since: bookmark editing, page labels (Number pages), CLI `run`, Set Page Boxes, Crop tool, Duplicate pages, Ctrl+A / Cmd+A to select all pages in Organize. Missing: Replace pages, page transitions, recovery on the web |
-| M5 | Comments (all annotation types, XFDF) | 120–200 | 88% | 15–25 | Done: notes, highlight/underline/strikeout/squiggly, text boxes, ink, lines, arrows, rectangles, ovals, stamps (dynamic, Sign Here, Standard Business), with appearance streams; replies, status, checkmarks, locking, move/resize/restyle/delete; properties dialog; panel filter and sort; hide all; summaries (comments only); XFDF/FDF import and export; flatten; Fill & Sign; agent tools. Done since: polygons, connected lines, clouds, callouts, inserted text, colour and checkmark filters. Missing: custom stamps, replace-text proposals, summary layouts with the page |
+| M4 | Engine, history, save, organize | 100–180 | 95% | 9–17 | Done:
- command registry (menus, shortcuts and palette all use it);
- undo/redo; incremental, atomic and encrypted saves;
- autosave and crash recovery;
- organize, combine, extract, split and insert-from-file, with identical fonts and images stored once;
- CLI `edit/combine/extract/split`.
Done since: Combine files in its own tab (sortable, resizable columns; folders; early warnings; unlocking protected files), bookmark editing, page labels (Number pages), CLI `run`, Set Page Boxes, Crop tool, Duplicate pages, Ctrl+A / Cmd+A to select all pages in Organize. Missing: Replace pages, page transitions, recovery on the web |
+| M5 | Comments (all annotation types, XFDF) | 120–200 | 88% | 15–25 | Done: notes, highlight/underline/strikeout/squiggly, text boxes, ink, lines, arrows, rectangles, ovals, stamps (dynamic, Sign Here, Standard Business), with appearance streams; replies, status, checkmarks, locking, move/resize/restyle/delete; properties dialog; panel filter and sort; hide all; summaries (comments only); XFDF/FDF import and export; flatten; Fill & Sign; agent tools. Done since: polygons, connected lines, clouds, callouts, inserted text, colour and checkmark filters; image signature pointer previews, selection handles and live image movement/resizing with proportional corners and independent edge handles. Missing: custom stamps, replace-text proposals, summary layouts with the page |
| M6 | Forms + JavaScript | 160–320 | 45% | 95–185 | Done: filling all field types with regenerated appearances; Prepare a form (every field type, move/resize/delete, Field Properties General/Appearance/Position/Options/Format/Validate/Calculate); Acrobat's AF format/keystroke/validate/calculate functions and simplified field notation run natively in Acrobat's event order; tab order; push-button actions; flatten; agent tools. Form data exchange (FDF, XFDF, XML, CSV, text) done. Done since: JavaScript engine (boa, sandboxed) running custom keystroke/validate/calculate/format and button scripts, document JavaScripts, console. Missing: Actions tab, wider object model (annotations, layers, dialogs), XFA |
| M7 | Content editing (text, images, header/footer, watermark) | 250–500 | 17% | 210–420 | Done: header & footer, watermarks, backgrounds, Bates; added text and images that stay editable (move, resize, format, rotate, flip, crop, replace); links (Link tool, Link Properties, create from URLs, remove all). Missing: editing existing text and images in place (the longest pole), image/PDF watermarks |
| M8 | Security + redaction | 100–180 | 66% | 35–65 | Done: opening protected documents, permissions, Protect Using Password, Remove security; redaction (mark text/areas/pages, Search & Redact with patterns, apply removing glyphs, image pixels, vectors, XObject content, annotations and fields, verification, full rewrite on save); Remove hidden information and Sanitize. Missing: certificate security, redaction codes and pattern locales, DCT re-encoding |
| M9 | Signatures (PAdES, validation) | 160–280 | 55% | 70–125 | Done: new `sign` crate (DER, X.509, CMS, PKCS #12 on RustCrypto; aws-lc-rs for RSA private keys); PAdES B-B signing (visible, invisible, existing fields, certification with DocMDP); validation with trust store and changes-after-signing classification; self-signed digital IDs; Signatures panel, message bar, sign dialogs; agent tools. Checked with pdfsig and OpenSSL. Done since: macOS Keychain and Windows Current User Personal store signing (software-backed CNG keys), certificate viewer, signed documents protected from rewrites. Missing: timestamps (B-T), LTV (DSS, OCSP, CRL), FieldMDP, smart cards, PKCS #11 |
-| M10 | OCR, create, export, print | 200–350 | 33% | 130–235 | Done: create from blank/text/PNG/JPEG/TIFF (multi-page)/GIF/BMP; export PNG/JPEG/TIFF and text; Print (Acrobat's sizing, n-up, booklet, poster, comments & forms, preview, CUPS spooler, print-ready PDF). Done since: embedded/72/custom DPI choices for image imports; export all images; OCR (searchable image for pages, ranges and multiple files); single-sided cut-and-stack imposition with cut marks, through Print and doc_print. Missing: OCR languages beyond Latin, editable-text OCR output, Office export/import, Windows/web printing |
+| M10 | OCR, create, export, print | 200–350 | 33% | 130–235 | Done: create from blank/text/PNG/JPEG/TIFF (multi-page)/GIF/BMP; export PNG/JPEG/TIFF and text; Print (Acrobat's sizing, n-up, booklet, poster, comments & forms, preview, CUPS spooler, print-ready PDF). Done since: embedded/72/custom DPI choices for image imports; export all images; OCR (searchable image for pages, ranges and multiple files); single-sided cut-and-stack imposition with cut marks, through Print and doc_print; Create PDF from multiple files (PDFs, images and text, edited as pages in the grid). Missing: OCR languages beyond Latin, editable-text OCR output, Office export/import, Windows/web printing |
| M11 | Optimize, preflight, PDF/A/X/UA, print production | 200–350 | 18% | 165–290 | Done: new `optimize` crate: Reduce File Size and the PDF Optimizer (images measured where drawn, bicubic downsampling, JPEG/ZIP recompression only when smaller, discard objects and user data, Flate clean-up, resource merging, object streams). Missing: fonts and transparency panels, space audit, preflight, PDF/A/X/UA |
| M12 | Accessibility, compare, measure, search, XFA | 200–380 | 23% | 155–295 | Done: new `a11y` crate with the Accessibility Checker (all 32 rules, report, Fix/Skip/Explain, options dialog and results panel, agent tools). Done since: 2D distance, perimeter and area measurements with persistent viewport calibration, snapping, live information and CSV export. Missing: autotag, Tags/Order/Content panels, Reading Order tool, alt-text workflow, compare, geospatial/3D measurement, search index, XFA |
| M13 | Automation (MCP, Action Wizard, CLI) + AI providers | 60–120 | 45% | 33–66 | Done: MCP resources (document info, text, page images); headless tool table (123 tools incl. signing, optimizing, initial view, links, stamps, data exchange, comment review, forms authoring and scripts, redaction, sanitize, print, add content), opt-in MCP server over stdio, CLI `run`/`tools` (closed stdout pipes exit cleanly), UI control channel with drag. Missing: Action Wizard, AI providers |
-| M14 | 1.0 polish: performance, localization, installers | 120–250 | 5% | 115–240 | Done: PhotoCraft's translation system (`i18n/`: TSV catalogs, `tl!`, command-id and plural entries, system-language detection, strict catalog tests); every dialog, panel and notice goes through `tl!`; Japanese, Traditional Chinese, Simplified Chinese, Spanish and French catalogs have ≈1,800 entries each; Simplified Chinese and French coverage is checked against the UI source; Czech and Brazilian Portuguese for menus. French locales (`fr`, `fr_FR`, `fr_CA`) follow the French catalog. Missing: more catalogs filled in, installers, performance budgets |
+| M14 | 1.0 polish: performance, localization, installers | 120–250 | 5% | 115–240 | Done: PhotoCraft's translation system (`i18n/`: TSV catalogs, `tl!`, command-id and plural entries, system-language detection, strict catalog tests); every dialog, panel and notice goes through `tl!`; Japanese, Traditional Chinese, Simplified Chinese, Russian, German, Spanish and French catalogs have ≈1,800 entries each; Simplified Chinese, French and German coverage is checked against the UI source; Czech and Brazilian Portuguese for menus. French locales (`fr`, `fr_FR`, `fr_CA`) follow the French catalog. Missing: more catalogs filled in, installers, performance budgets |
+| M14 | 1.0 polish: performance, localization, installers | 120–250 | 5% | 115–240 | Done: PhotoCraft's translation system (`i18n/`: TSV catalogs, `tl!`, command-id and plural entries, system-language detection, strict catalog tests); every dialog, panel and notice goes through `tl!`; Japanese, Traditional Chinese, Simplified Chinese, Russian, Spanish, French and Ukrainian catalogs have ≈1,800–2,000 entries each; Simplified Chinese, French and Ukrainian coverage is checked against the UI source; Czech and Brazilian Portuguese for menus. French locales (`fr`, `fr_FR`, `fr_CA`) follow the French catalog; Ukrainian locales (`uk`, `uk_UA`) follow the Ukrainian one. Missing: more catalogs filled in, installers, performance budgets |
| | **Total (original plan sizing)** | **2,085–3,840** | **≈ 35%** | **≈ 1,350–2,500 at the planned rate; ≈ 600–1,100 at the measured rate** | |
**Overall progress: about 30–35% of the effort (51.0% of features shipped).** The viewer and the core are far ahead of the editing features, because the viewer was built first so progress could be seen; rendering itself is still borrowed from `hayro`. See [Honest assessment](#honest-assessment-2026-10-05).
@@ -125,14 +127,48 @@ M0 → M1 → M2 → M3 → M4 must happen in order. After M4, M5–M12 can run
## Log
+- **2026-10-09 (M5, line endings):** Lines, connected lines and callouts draw all ten standard line-ending styles. `comment_add` accepts `endings`, and Comment properties can change them in one undo step. An unknown name is left undrawn, and a non-finite direction is rejected. Cloudy borders remain polygon-only, so `comment.line-endings` stays partial. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (M6, field rotation):** Regenerated form appearances honour `/MK /R` (0, 90, 180, 270). Filling or restyling a rotated field keeps the text, check mark and button caption turned, and Field Properties ▸ Position and `form_set_props` `rotation` set it, swapping width and height around the field's center when the axis changes. `form.appearance-regeneration` stays partial (Helvetica metrics are still approximate). Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (M5.7, #434 partial):** Natural-size image stamps placed at a click or through `stamp_custom` remain upright on rotated pages, with a displayed-space-sized rectangle and a counterrotated standard appearance matrix. Move, resize, restyle and undo/redo preserve that orientation. Native and external Poppler save/reopen rendering cover all four quarter-turns; UI tests verify the displayed bounds. Explicit rectangle placement, image signatures, PDF-page stamps and image-file orientation metadata remain outside this repair. #434 stays open; milestone table and effort estimates remain unchanged.
+- **2026-10-09 (M1, raw-stream decoding limits):** COS checks unfiltered decoded data against the caller and per-stream limits before copying it, including empty filter arrays and streams whose Crypt filter was applied on load. Strict decoding uses the same raw-data guard. Tiny synthetic regressions cover exceeded, exact and zero-byte limits while retaining the filtered decoder behavior. Milestone and overall effort estimates unchanged (about 30–35%).
+
+- **2026-10-09 (M7, grouped artwork):** Edit text/images selects page-drawn Form XObjects as whole figures, including nested raster/vector/text content. Their BBox and optional Matrix determine the selection; move/resize/rotate/flip/delete rewrite only the selected page placement, preserving shared Forms and other placements. Engine, automation and UI core regressions cover geometry, rendered movement, save/reopen, undo and selection/drag/Delete. Bitmap replacement/extraction remain raster-only; inline images and individual elements inside a Form are not editable through this tool. Overall estimate unchanged (about 30–35%).
+
+- **2026-10-08 (M5.7, signature resize proportions):** Image signature corner handles preserve the embedded image's original aspect ratio and anchor the opposite corner; edge midpoint handles stretch width or height independently. The live preview and committed edit share the constrained geometry, including page/view rotation and reopened PDFs whose rectangles were stretched previously. Synthetic UI tests cover all corners, edge resizing, undo and redo. Milestone and effort estimates unchanged.
+- **2026-10-08 (M5.7, live signature adjustment):** Embedded image signatures resize and move with every pointer frame. Movement hides the frame and handles, which return on release; Escape cancels without committing. A cached background preserves the page beneath the image, and only the completed gesture enters undo history. The read-only engine preview and `comment_image_preview` tool share bounded image decoding and render layers. Synthetic pixel tests cover live geometry, alpha, coloured page content, rotation, cancellation and encrypted save/reopen. Milestone and effort estimates unchanged.
+- **2026-10-08 (M10/M4, create from multiple files):** Create a PDF ▸ Multiple files is live. The picked PDFs, images and `.txt` files open as one unsaved document in the Organize page grid, where pages are removed and reordered and Save pages writes what is shown. The grid gained a "+" at every gap that inserts files right there, and on desktop files dropped on the grid go to the gap under the pointer; Insert from file now takes several files in order, converts images and text, and selects what it inserted. File-type detection moved from the shell into `pdfcraft-create` (`source_kind`), with one engine entry point (`Session::convert_to_pdf`) shared by Open, Insert, Create and the new `doc_create_multiple` tool (which can also write one PDF per file). Not yet: Office/HTML/Markdown inputs, PDF Portfolios, progress for big batches, dropping onto the grid in the web build. Overall estimate unchanged (about 30–35%).
+
+- **2026-10-08 (M5.7, signature placement):** Image signatures and initials preview at the pointer at their actual page size, including zoom and document/view rotation. A successful placement switches to Select with the new annotation selected; stamp resize handles use the existing engine edit, automation tool and undo history while preserving the appearance. Synthetic rendered UI and automation tests verify positioning, one placement per selection, resizing, undo/redo and save/reopen. Milestone and overall effort estimates unchanged.
+- **2026-10-08 (M5.7, image signatures):** Fill & Sign imports local PNG/JPEG signatures and initials through the Image tab, with previews, local persistence and undoable placement. The shared engine validates bounded images and preserves transparency and orientation; `fill_sign_add` accepts an image path. Synthetic UI and automation tests cover cancellation, invalid input, settings, undo/redo and save/reopen rendering. Overall effort estimate unchanged (about 30–35%).
+
- **2026-10-08 (M9, #179):** Windows Current User Personal certificate store identities join file-based digital IDs, signing through CNG without exporting keys. RSA-2048 and ECDSA P-256 round trips use temporary certificates with cleanup guards; enumeration, missing identities, automation errors and the password-free UI have regression coverage. Smart cards and PKCS #11 remain planned; overall effort estimate unchanged.
Newest first. One line per session: the date, what moved, and the new overall percentage.
+- **2026-10-09 (M14, German interface follow-up):** Follow the merged German catalog with shorter search/action labels, corrected callout/accessibility wording and a distinct certificate Subject context. Localized tool names retain their capitalization and comment composer titles go through the catalog. Search hints reserve shortcut space and Home cards bound text with full hover text; layout, context and German Preferences/search control regression tests cover these changes. Overall effort estimate remains about 30–35%.
+
+- **2026-10-09 (community, destinations):** Bookmarks and links go to their destination's position, not just its page (ISO 32000-2 §12.3.2.2): `/XYZ` puts (left, top) at the window's top-left and applies a non-zero zoom; `/Fit`, `/FitH` and `/FitV` switch to fit page, width and height with `top` or `left` at the window's edge; `/FitR` zooms to fit the rectangle, centred. Named destinations resolve the same way; crop-box origin, `/Rotate` and view rotation are accounted for; malformed or non-finite operands fall back to the top of the page. Not yet: the `/FitB*` content box (read as the page). Overall estimate unchanged (about 30–35%).
+
+- **2026-10-09 (community, M14, Hungarian):** Magyar (`hu`) is a complete interface catalog (2,036 entries) covering every command, All tools entry, dialog, panel and notice, selected automatically for `hu` and `hu_HU`, and from Preferences. Informal "te"; commands are nouns (Mentés, Megnyitás). After a numeral the noun stays singular, so both plural forms match. Coverage tests check commands, All tools labels and every `tl!` literal; history labels keep captured names; the bundled Latin faces cover Hungarian diacritics including ő and ű. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (M14, Windows Auto):** Neutral launcher locales (`C`, `C.UTF-8`, `POSIX`) no longer select English ahead of the Windows preferred display-language list. Explicit supported locale overrides retain their priority. Regression tests use existing catalogs and cover neutral/mixed overrides, unsupported first display tags and multiple preferred Windows languages. Catalogs and other platforms are unchanged; overall effort estimate remains about 30–35%.
+
+- **2026-10-09 (community, M14, German):** Deutsch (`de`) is a complete interface catalog (2,035 entries) covering every command, All tools entry, dialog, panel and notice, selected automatically for `de`, `de_DE`, `de_AT`, `de_CH` and other German locales, and from Preferences. Informal "du", infinitive for commands. Coverage tests check commands, All tools labels and every `tl!` literal; history labels keep captured names; the bundled Latin faces cover umlauts, ß and German quotes. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (community, M7, Arabic added text):** Add text writes Arabic into the PDF instead of `?`. The text is shaped with the craft-fonts `Arab` face through harfrust (already in the tree via egui): joining forms, ligatures and mark positions. Each line is laid out in display order by the Unicode bidirectional algorithm, so Arabic mixed with Latin words, European or Arabic-Indic digits and brackets reads correctly; justified right-to-left paragraphs end at the right edge. Each cluster (a letter with its dots or marks) becomes one glyph of a Type 3 font built from the face's outlines, with a ToUnicode entry, so `text_extract`, copy and search get every letter once and no font file is embedded. Wrapping measures shaped words. Each item has its own fonts under names free on the page (a full save renumbers objects but not resource names); updating or deleting the item removes them. Without the face, adding Arabic text returns a clear error and changes nothing, while an existing item holding Arabic still moves and retypes, drawn as `?` as before. Tests cover shaping, display order, ToUnicode, font names and clean-up on one page, and odd input (empty lines, direction controls, lone marks, 18,000 characters). Not yet: bold/italic Arabic, Hebrew, right-to-left typing in the box (misc.rtl-ui), editing existing Arabic text (edit.rtl-cjk-editing). The craft-fonts revision pinned for releases predates its Arabic face, so release builds report the missing font until the pin moves. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (M2, predictor hardening):** Empty PNG predictor frames return without row buffers. Packed TIFF Predictor 2 rows reject overflowing dimensions and size per-component scratch to the samples present in the input, aligned with upstream lopdf#589. Synthetic regressions cover malformed dimensions, partial rows, 1/2/4-bit decoding and padding. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (community, document inspection):** Annotation dates preserve non-date Unicode text instead of panicking while opening; failed auxiliary structure inspection keeps renderer page geometry and reports a warning. Synthetic UTF16BE annotation, UTF8-boundary and independent panic regressions cover the fix. Overall estimate unchanged (about 30–35%).
+
+- **2026-10-09 (community, M14, #503):** Ukrainian (Українська, `uk`) adds 2,047 original catalog entries covering commands, tools, dialogs, panels, notices, history and contributor controls. Auto resolves `uk`/`uk_UA`; the manual preference persists. Integer plurals distinguish one/few/many, including 11–14 and large counts; fixed-count templates use count-neutral wording. Calendar dates use genitive month names; Home cards fit wrapped text and the search hint keeps clear of its shortcut. Coverage checks scan UI literals, and font checks use bundled Inter and JetBrains Mono, including ґ/є/і/ї. Control tests check translated Preferences, command search, error framing and language switching with unsaved documents. Overall estimate unchanged (about 30–35%).
+
+- **2026-10-09 (community, Home pinned folders):** Home gets a Folders section: File ▸ Pin folder to Home… (or "Pin a folder…" on Home) pins up to 8 folders, and each lists its newest PDFs (name, how long ago, size; 8 at first, up to 100 with Show more), one click to open, Unpin to remove. Folders are read on a worker thread and listed again every few seconds while Home shows, so new scans appear without reopening anything; a folder that can't be read (moved, offline synced drive) stays pinned and says so. Each folder is described by where it is ("iCloud Drive", "OneDrive · Contoso", "Documents › Work") rather than its full path, so two folders called "Scans" can be told apart. Cloud drives work through their local synced folder; nothing is read through a provider's API. Settings keep only absolute paths, without duplicates. Command label translated in every catalog; Home strings in French, Spanish, Japanese and both Chinese catalogs. Not yet: subfolders, search inside a pinned folder, the web build. Overall estimate unchanged (about 30–35%).
+
+- **2026-10-09 (community, M14, Telugu):** Telugu (తెలుగు, `te`) as a complete catalog of 1,984 entries covering every command, All tools entry, dialog, panel and notice; `te` and `te_IN` locales follow it. Telugu text is drawn with a craft-fonts `Telu` face (Noto Sans Telugu, storytold/craft-fonts#10), kept in the web build too, after the CJK and Arabic faces; egui shapes its conjuncts. Commands use the plain imperative and sentences the polite form. The craft-fonts revision pinned for releases has no Telugu face yet, so release builds show Telugu as replacement boxes until the pin moves. Overall estimate unchanged (about 30–35%).
+
- **2026-10-09 (M14, Simplified Chinese About):** The About tabs, contributor controls and statistics, and model table now have Simplified Chinese translations, along with multiline link-privacy and cut-and-stack guidance. Coverage checks include direct `i18n::t` calls, multiline literals and dynamic credit labels; UI control checks exercise the translated About tabs and tables. Chinese font delivery remains incomplete; overall ≈ 30–35% (unchanged).
- **2026-10-09 (M14, #305):** Windows MSI rejects per-user installation overrides while allowing removal of legacy per-user installs and keeps its progress message visible. README documents unattended deployment without a desktop shortcut. Compiled x64 MSI checks pass; ARM64 install regressions added for CI. Overall estimate unchanged (about 30–35%).
+- **2026-10-08 (M4, Combine files):** Combine files is now its own tab instead of a dialog: a table of the files (name, pages, size, modified, warnings) whose columns sort, resize and move, with the layout kept in the settings. Files, folders (optionally with subfolders) and open documents can be added, or dropped on the tab; rows select like a file manager (Ctrl/Shift), move as a block by toolbar, Alt+arrows or drag, and every change undoes with ⌘Z. Problems show before Combine: password-protected files, security settings that withhold page assembly, bad page ranges (checked as typed), duplicates; protected files unlock with their open or permissions password, also headlessly (`doc_combine` `passwords`). The result is never encrypted, and the list says so. `organize.combine-sort` shipped; `organize.combine-options` partial (open files). Still missing: protecting the result in the same step, file-size and PDF/A options. Overall estimate unchanged (about 30–35%).
+
- **2026-10-08 (M14, French):** Français (`fr`) is a complete interface catalog (about 1,880 entries), selected automatically for `fr`, `fr_FR`, `fr_CA` and other French locales, and from Preferences. Coverage tests check commands, All tools labels and every `tl!` literal; history labels keep captured names. Latin UI faces cover the catalog. Localization remains partial for Czech and Brazilian Portuguese; overall ≈ 30–35% (unchanged).
- **2026-10-08 (M14, right-to-left file names):** A tab with an Arabic or Hebrew file name showed replacement boxes. The interface now takes an `Arab` face from craft-fonts when the build input has one, and on desktop falls back to one font installed on the machine for characters no embedded face has (`PDFCRAFT_SYSTEM_FONTS=0` turns that off; README screenshots do). File names and paths in the tab strip, the recent-files list and Properties are put in display order, since egui joins the letters but does not reorder runs. Still missing: multi-line text (bookmarks, comments, search results), text input and a mirrored layout, so `misc.rtl-ui` stays planned; the craft-fonts revision pinned for releases predates its Arabic face, so release builds rely on the installed font until the pin moves. Overall estimate unchanged (about 30–35%).
@@ -238,3 +274,5 @@ Newest first. One line per session: the date, what moved, and the new overall pe
- Robustness sweep (963 of 983 files open, 0 crashes), text layer, find and select, tiles, web build, polish.
- Overall ≈ 3–4%.
- **2026-09-30 (session 1):** planning complete; viewer vertical slice.
+
+- M13: common command, batch, inspection and bounded preview tools share the existing confined automation path. MCP tools carry complete hints and reject unknown top-level keys as invalid parameters.
diff --git a/apps/pdfcraft-cli/src/main.rs b/apps/pdfcraft-cli/src/main.rs
index 011d8320..1940d63e 100644
--- a/apps/pdfcraft-cli/src/main.rs
+++ b/apps/pdfcraft-cli/src/main.rs
@@ -1,22 +1,6 @@
//! pdfcraft-cli — headless PdfCraft.
//!
-//! ```text
-//! pdfcraft-cli info [--password PW] document summary as JSON
-//! pdfcraft-cli render --page N [--dpi 96] --out x.png (.png, .jpg, .tif or .pam)
-//! pdfcraft-cli text [--page N] extracted text (pages separated by form feeds)
-//! pdfcraft-cli edit --out out.pdf [--rotate 1,3:90] [--delete 2,4] [--move 5:1]
-//! [--insert-blank 1] [--title T] [--author A] [--full]
-//! pdfcraft-cli combine … --out combined.pdf
-//! pdfcraft-cli extract --pages 1,3,5 --out out.pdf
-//! pdfcraft-cli split (--every N | --before 3,7) [--out-dir DIR]
-//! pdfcraft-cli check [--timeout 20] [--dpi 36] [--json out.json]
-//! pdfcraft-cli tools automation tools and their JSON Schemas
-//! pdfcraft-cli run [key=value …] [--root DIR] [--out image.png]
-//! pdfcraft-cli run --script steps.json [--root DIR] [{"tool": "doc_open", "args": {…}}, …]
-//! pdfcraft-cli mcp [--root DIR] MCP server on stdin/stdout (opt-in)
-//! pdfcraft-cli ui --control FILE [key=value …] [--out shot.png]
-//! drive a running app started with --control FILE
-//! ```
+//! Usage: `pdfcraft-cli --help`, which prints `USAGE` below.
//!
//! `run` and `mcp` drive the same tool table (`pdfcraft-automation`). In `run`, values parse as
//! JSON when they can (`pages=[1,3]`, `degrees=90`) and are strings otherwise. A script runs its
@@ -42,28 +26,75 @@ use std::time::{Duration, Instant};
use pdfcraft_engine::export::ImageFormat;
use pdfcraft_render::{PageRenderer, RenderConfig, RenderRequest, RequestKind, inspect};
+/// The `mcp` lines of [`USAGE`]: only a build with the `mcp` feature has the command.
+#[cfg(feature = "mcp")]
+macro_rules! mcp_usage {
+ () => {
+ "\
+pdfcraft-cli mcp [--root DIR] [--compact] MCP server on stdin/stdout (opt-in)
+ --compact lists a core set of tools plus tool_search and tool_call
+"
+ };
+}
+#[cfg(not(feature = "mcp"))]
+macro_rules! mcp_usage {
+ () => {
+ ""
+ };
+}
+
+/// The full usage, printed by `--help` (also after a command, e.g. `render --help`).
+const USAGE: &str = concat!(
+ "\
+pdfcraft-cli info [--password PW] document summary as JSON
+pdfcraft-cli render --page N [--dpi 96] --out x.png (.png, .jpg, .tif or .pam)
+pdfcraft-cli text [--page N] extracted text (pages separated by form feeds)
+pdfcraft-cli edit --out out.pdf [--rotate 1,3:90] [--delete 2,4] [--move 5:1]
+ [--insert-blank 1] [--title T] [--author A] [--full]
+pdfcraft-cli combine … --out combined.pdf
+pdfcraft-cli extract --pages 1,3,5 --out out.pdf
+pdfcraft-cli split (--every N | --before 3,7) [--out-dir DIR]
+pdfcraft-cli check [--timeout 20] [--dpi 36] [--json out.json]
+pdfcraft-cli tools automation tools and their JSON Schemas
+pdfcraft-cli run [key=value …] [--root DIR] [--out image.png]
+pdfcraft-cli run --script steps.json [--root DIR] [{\"tool\": \"doc_open\", \"args\": {…}}, …]
+",
+ mcp_usage!(),
+ "\
+pdfcraft-cli ui --control FILE [key=value …] [--out shot.png]
+ drive a running app started with --control FILE
+help and feedback: https://discord.gg/artcraft"
+);
+
fn main() -> ExitCode {
let args: Vec = std::env::args().skip(1).collect();
- let result =
- match args.first().map(String::as_str) {
- Some("info") => info(&args[1..]),
- Some("render") => render(&args[1..]),
- Some("text") => text(&args[1..]),
- Some("edit") => edit(&args[1..]),
- Some("combine") => combine(&args[1..]),
- Some("extract") => extract(&args[1..]),
- Some("split") => split(&args[1..]),
- Some("check") => check(&args[1..]),
- Some("check-one") => check_one(&args[1..]),
- Some("tools") => tools(),
- Some("run") => run(&args[1..]),
- Some("ui") => ui(&args[1..]),
- #[cfg(feature = "mcp")]
- Some("mcp") => mcp(&args[1..]),
- Some("--version") => version(),
- _ => Err("usage: pdfcraft-cli … (see source header for options)\nhelp and feedback: https://discord.gg/artcraft"
- .into()),
- };
+ // ` --help` too; only right after the command, so a later `-h` (a value) still reaches it.
+ let command = match args.get(1).map(String::as_str) {
+ Some("--help" | "-h") => Some("--help"),
+ _ => args.first().map(String::as_str),
+ };
+ let result = match command {
+ Some("--help" | "-h" | "help") => stdout_line(format_args!("{USAGE}")),
+ None => Err(format!("usage:\n{USAGE}").into()),
+ Some("info") => info(&args[1..]),
+ Some("render") => render(&args[1..]),
+ Some("text") => text(&args[1..]),
+ Some("edit") => edit(&args[1..]),
+ Some("combine") => combine(&args[1..]),
+ Some("extract") => extract(&args[1..]),
+ Some("split") => split(&args[1..]),
+ Some("check") => check(&args[1..]),
+ Some("check-one") => check_one(&args[1..]),
+ Some("tools") => tools(),
+ Some("run") => run(&args[1..]),
+ Some("ui") => ui(&args[1..]),
+ #[cfg(feature = "mcp")]
+ Some("mcp") => mcp(&args[1..]),
+ #[cfg(not(feature = "mcp"))]
+ Some("mcp") => Err("mcp: this build leaves out the MCP server (built without the `mcp` feature)".into()),
+ Some("--version") => version(),
+ Some(other) => Err(format!("unknown command '{other}'; see pdfcraft-cli --help").into()),
+ };
match result {
Ok(()) => ExitCode::SUCCESS,
Err(CliError::Stdout(e)) if e.kind() == std::io::ErrorKind::BrokenPipe => ExitCode::SUCCESS,
@@ -175,6 +206,22 @@ fn info(args: &[String]) -> Result<(), CliError> {
fn text(args: &[String]) -> Result<(), CliError> {
let path = *positional(args).first().ok_or("text: missing file")?;
+ let mut selected_page = None;
+ // Validate every supplied value before reading, retaining the first valid selection.
+ let mut options = args.iter();
+ while let Some(option) = options.next() {
+ if option == "--page" {
+ let page = options
+ .next()
+ .and_then(|value| value.parse::().ok())
+ .filter(|page| *page > 0)
+ .ok_or("bad --page: expected a positive page number")?;
+ selected_page.get_or_insert(page - 1);
+ } else if option.starts_with("--") {
+ // Match positional(): an option's operand is not itself another option.
+ options.next();
+ }
+ }
let password = flag(args, "--password");
let bytes = read(path)?;
let mut r = PageRenderer::new(bytes.clone(), RenderConfig { password: password.map(Arc::from), ..Default::default() });
@@ -187,15 +234,15 @@ fn text(args: &[String]) -> Result<(), CliError> {
return Err("text: the document could not be parsed".into());
}
}
- let pages: Vec = match flag(args, "--page") {
- Some(p) => vec![p.parse::().map_err(|_| "bad --page")?.saturating_sub(1)],
+ let pages: Vec = match selected_page {
+ Some(page) => vec![page],
None => (0..r.page_count()).collect(),
};
let mut failed: Vec = Vec::new();
for (n, p) in pages.iter().enumerate() {
let out = r.render(RenderRequest { page: *p, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0 });
if let Some(e) = out.error {
- eprintln!("page {}: {e}", p + 1);
+ let _ = writeln!(std::io::stderr().lock(), "page {}: {e}", p + 1);
failed.push(p + 1);
continue;
}
@@ -262,11 +309,11 @@ fn edit(args: &[String]) -> Result<(), CliError> {
"--move" => {
let (pages, to) = value.split_once(':').ok_or("--move PAGES:TO")?;
let to: usize = to.parse().map_err(|_| "bad target")?;
- edits.push(Edit::MovePages { pages: page_list(pages)?, to: to.saturating_sub(1) });
+ edits.push(Edit::MovePages { pages: page_list(pages)?, to: to.checked_sub(1).ok_or("--move target must be at least 1")? });
}
"--insert-blank" => {
let at: usize = value.parse().map_err(|_| "bad position")?;
- edits.push(Edit::InsertBlankPage { at: at.saturating_sub(1), width: 612.0, height: 792.0 });
+ edits.push(Edit::InsertBlankPage { at: at.checked_sub(1).ok_or("--insert-blank must be at least 1")?, width: 612.0, height: 792.0 });
}
"--title" => edits.push(Edit::SetInfo { key: "Title".into(), value: value.into() }),
"--author" => edits.push(Edit::SetInfo { key: "Author".into(), value: value.into() }),
@@ -337,6 +384,7 @@ fn split(args: &[String]) -> Result<(), CliError> {
fn render(args: &[String]) -> Result<(), CliError> {
let path = *positional(args).first().ok_or("render: missing file")?;
let page: usize = flag(args, "--page").unwrap_or("1").parse().map_err(|_| "bad --page")?;
+ let page_index = page.checked_sub(1).ok_or("--page must be at least 1")?;
let dpi: f32 = flag(args, "--dpi").unwrap_or("96").parse().map_err(|_| "bad --dpi")?;
let out = flag(args, "--out").ok_or("render: missing --out (.png, .jpg, .tif or .pam)")?;
// The file is what its name says (#248): a `.png` used to get a netpbm PAM stream.
@@ -348,7 +396,7 @@ fn render(args: &[String]) -> Result<(), CliError> {
_ => return Err(format!("render: --out {out}: use a .png, .jpg, .tif or .pam name").into()),
};
let mut r = PageRenderer::new(read(path)?, RenderConfig { password: flag(args, "--password").map(Arc::from), ..Default::default() });
- let p = r.render(RenderRequest { page: page.saturating_sub(1), kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0 });
+ let p = r.render(RenderRequest { page: page_index, kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0 });
if let Some(e) = p.error {
return Err(e.into());
}
@@ -362,7 +410,7 @@ fn render(args: &[String]) -> Result<(), CliError> {
}
};
std::fs::write(out, bytes).map_err(|e| format!("{out}: {e}"))?;
- eprintln!("rendered page {page} at {dpi} dpi: {}×{} px in {} ms", p.width, p.height, p.millis);
+ let _ = writeln!(std::io::stderr().lock(), "rendered page {page} at {dpi} dpi: {}×{} px in {} ms", p.width, p.height, p.millis);
Ok(())
}
@@ -579,8 +627,14 @@ fn run(args: &[String]) -> Result<(), CliError> {
#[cfg(feature = "mcp")]
fn mcp(args: &[String]) -> Result<(), CliError> {
- let mut server = pdfcraft_automation::mcp::McpServer::new(automation(args)?);
- eprintln!("pdfcraft-cli: MCP server on stdio (protocol {}); close stdin to stop", pdfcraft_automation::mcp::PROTOCOL_VERSIONS[0]);
+ let compact = args.iter().any(|a| a == "--compact");
+ let mut server = pdfcraft_automation::mcp::McpServer::new(automation(args)?).with_compact(compact);
+ let _ = writeln!(
+ std::io::stderr().lock(),
+ "pdfcraft-cli: MCP server on stdio (protocol {}{}); close stdin to stop",
+ pdfcraft_automation::mcp::PROTOCOL_VERSIONS[0],
+ if compact { ", compact tool list" } else { "" }
+ );
server.serve(std::io::stdin().lock(), std::io::stdout().lock()).map_err(|e| CliError::Message(e.to_string()))
}
diff --git a/apps/pdfcraft-cli/tests/edit.rs b/apps/pdfcraft-cli/tests/edit.rs
index 8cd47cfb..15fdb68c 100644
--- a/apps/pdfcraft-cli/tests/edit.rs
+++ b/apps/pdfcraft-cli/tests/edit.rs
@@ -91,3 +91,91 @@ fn the_documented_options_still_edit_and_save() {
assert_eq!(info.title.as_deref(), Some("Rotated"), "{name}");
}
}
+
+mod one_based_arguments {
+ use super::*;
+ use std::sync::atomic::{AtomicU64, Ordering};
+
+ struct TestDir(PathBuf);
+ impl TestDir {
+ fn new() -> Self {
+ static NEXT: AtomicU64 = AtomicU64::new(0);
+ for _ in 0..128 {
+ let path =
+ std::env::temp_dir().join(format!("pdfcraft-cli-one-based-{}-{}", std::process::id(), NEXT.fetch_add(1, Ordering::Relaxed)));
+ match std::fs::create_dir(&path) {
+ Ok(()) => return Self(path),
+ Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
+ Err(e) => panic!("cannot create test directory: {e}"),
+ }
+ }
+ panic!("cannot reserve test directory");
+ }
+ }
+ impl Drop for TestDir {
+ fn drop(&mut self) {
+ let _ = std::fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn zero_render_page_and_edit_positions_fail_before_io() {
+ let dir = TestDir::new();
+ let source = fixture();
+ std::fs::write(dir.0.join("input.pdf"), &source).unwrap();
+ for input in ["input.pdf", "missing.pdf"] {
+ for destination in ["output.pam", "new.pam", "input.pdf"] {
+ std::fs::write(dir.0.join("output.pam"), b"keep destination").unwrap();
+ for (command, option, value, diagnostic) in [
+ ("render", "--page", "0", "--page must be at least 1"),
+ ("edit", "--move", "1:0", "--move target must be at least 1"),
+ ("edit", "--insert-blank", "0", "--insert-blank must be at least 1"),
+ ] {
+ let out = Command::new(BIN).current_dir(&dir.0).args([command, input, "--out", destination, option, value]).output().unwrap();
+ assert_eq!(out.status.code(), Some(1), "{command} {input} {option} {value}");
+ assert_eq!(out.stderr, format!("pdfcraft-cli: {diagnostic}\n").as_bytes());
+ assert!(out.stdout.is_empty());
+ assert_eq!(std::fs::read(dir.0.join("input.pdf")).unwrap(), source);
+ assert_eq!(std::fs::read(dir.0.join("output.pam")).unwrap(), b"keep destination");
+ assert!(!dir.0.join("new.pam").exists());
+ assert!(!dir.0.join("missing.pdf").exists());
+ }
+ }
+ }
+ assert_eq!(std::fs::read_dir(&dir.0).unwrap().count(), 2);
+ }
+
+ #[test]
+ fn first_render_page_move_target_and_insertion_position_remain_usable() {
+ let dir = TestDir::new();
+ let source = fixture();
+ std::fs::write(dir.0.join("input.pdf"), &source).unwrap();
+ for output in ["page.pam", "page.png"] {
+ let out =
+ Command::new(BIN).current_dir(&dir.0).args(["render", "input.pdf", "--page", "1", "--dpi", "18", "--out", output]).output().unwrap();
+ assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+ let bytes = std::fs::read(dir.0.join(output)).unwrap();
+ if output.ends_with(".pam") {
+ let header = b"P7\nWIDTH 50\nHEIGHT 75\nDEPTH 4\nMAXVAL 255\nTUPLTYPE RGB_ALPHA\nENDHDR\n";
+ assert!(bytes.starts_with(header));
+ assert_eq!(bytes.len(), header.len() + 50 * 75 * 4);
+ } else {
+ assert!(bytes.starts_with(b"\x89PNG\r\n\x1a\n"));
+ assert_eq!(u32::from_be_bytes(bytes[16..20].try_into().unwrap()), 50);
+ assert_eq!(u32::from_be_bytes(bytes[20..24].try_into().unwrap()), 75);
+ }
+ }
+ let out = Command::new(BIN)
+ .current_dir(&dir.0)
+ .args(["edit", "input.pdf", "--out", "edited.pdf", "--move", "1:1", "--rotate", "1:90", "--insert-blank", "1"])
+ .output()
+ .unwrap();
+ assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+ assert!(out.stdout.is_empty() && out.stderr.is_empty());
+ let info = pdfcraft_render::inspect(std::sync::Arc::new(std::fs::read(dir.0.join("edited.pdf")).unwrap()), None).unwrap();
+ assert_eq!(info.pages.len(), 2);
+ assert_eq!((info.pages[0].width, info.pages[0].height, info.pages[0].rotation), (612.0, 792.0, 0));
+ assert_eq!((info.pages[1].width, info.pages[1].height, info.pages[1].rotation), (300.0, 200.0, 90));
+ assert_eq!(std::fs::read(dir.0.join("input.pdf")).unwrap(), source);
+ }
+}
diff --git a/apps/pdfcraft-cli/tests/help.rs b/apps/pdfcraft-cli/tests/help.rs
new file mode 100644
index 00000000..9a86150f
--- /dev/null
+++ b/apps/pdfcraft-cli/tests/help.rs
@@ -0,0 +1,65 @@
+//! `--help` prints the full usage to stdout and succeeds; a missing or unknown command fails with
+//! the usage (or a pointer to `--help`) on stderr.
+
+use std::process::{Command, Output};
+
+const BIN: &str = env!("CARGO_BIN_EXE_pdfcraft-cli");
+
+fn run(args: &[&str]) -> Output {
+ Command::new(BIN).args(args).output().unwrap()
+}
+
+fn text(bytes: &[u8]) -> String {
+ String::from_utf8_lossy(bytes).into_owned()
+}
+
+#[test]
+fn help_flags_print_full_usage_to_stdout() {
+ for args in [&["--help"][..], &["-h"], &["help"], &["render", "--help"], &["check", "-h"]] {
+ let out = run(args);
+ assert!(out.status.success(), "{args:?} exited {:?}", out.status);
+ let stdout = text(&out.stdout);
+ // Per-command options, not just the command list.
+ assert!(stdout.contains("pdfcraft-cli render --page N"), "{args:?}: {stdout}");
+ assert!(stdout.contains("--every N"), "{args:?}: {stdout}");
+ assert!(out.stderr.is_empty(), "{args:?}: {}", text(&out.stderr));
+ }
+}
+
+#[test]
+fn no_command_fails_with_usage_on_stderr() {
+ let out = run(&[]);
+ assert!(!out.status.success());
+ assert!(out.stdout.is_empty());
+ assert!(text(&out.stderr).contains("pdfcraft-cli render --page N"));
+}
+
+/// `mcp` is listed only when the build has it (`--no-default-features` leaves it out).
+#[test]
+fn usage_lists_mcp_only_when_built_with_it() {
+ let out = run(&["--help"]);
+ let stdout = text(&out.stdout);
+ assert_eq!(stdout.contains("pdfcraft-cli mcp"), cfg!(feature = "mcp"), "{stdout}");
+ assert_eq!(stdout.contains("--compact"), cfg!(feature = "mcp"), "{stdout}");
+ // The lines around it are still there.
+ assert!(stdout.contains("pdfcraft-cli run --script steps.json"), "{stdout}");
+ assert!(stdout.contains("pdfcraft-cli ui --control FILE"), "{stdout}");
+}
+
+#[cfg(not(feature = "mcp"))]
+#[test]
+fn mcp_without_the_feature_says_it_was_left_out() {
+ let out = run(&["mcp"]);
+ assert!(!out.status.success());
+ let stderr = text(&out.stderr);
+ assert!(stderr.contains("without the `mcp` feature"), "{stderr}");
+}
+
+#[test]
+fn unknown_command_names_it_and_points_to_help() {
+ let out = run(&["frobnicate"]);
+ assert!(!out.status.success());
+ let stderr = text(&out.stderr);
+ assert!(stderr.contains("unknown command 'frobnicate'"), "{stderr}");
+ assert!(stderr.contains("pdfcraft-cli --help"), "{stderr}");
+}
diff --git a/apps/pdfcraft-cli/tests/mcp_compact.rs b/apps/pdfcraft-cli/tests/mcp_compact.rs
new file mode 100644
index 00000000..48692068
--- /dev/null
+++ b/apps/pdfcraft-cli/tests/mcp_compact.rs
@@ -0,0 +1,76 @@
+//! `pdfcraft-cli mcp --compact`: the flag reaches the server, `--root` is still honoured, and plain `mcp` still lists every tool.
+#![cfg(feature = "mcp")]
+
+use std::io::Write as _;
+use std::process::{Command, Stdio};
+
+use serde_json::{Value, json};
+
+/// Run `pdfcraft-cli mcp ` over an initialize request plus `requests` and return the replies to `requests`.
+fn session(flags: &[&str], requests: &[Value]) -> Vec {
+ let mut child = Command::new(env!("CARGO_BIN_EXE_pdfcraft-cli"))
+ .arg("mcp")
+ .args(flags)
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::null())
+ .spawn()
+ .unwrap();
+ let mut input = String::from("{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{}}\n");
+ for r in requests {
+ input.push_str(&r.to_string());
+ input.push('\n');
+ }
+ child.stdin.take().unwrap().write_all(input.as_bytes()).unwrap();
+ let out = child.wait_with_output().unwrap();
+ assert!(out.status.success());
+ String::from_utf8(out.stdout).unwrap().lines().skip(1).map(|l| serde_json::from_str(l).unwrap()).collect()
+}
+
+fn request(id: u64, method: &str, params: Value) -> Value {
+ json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params })
+}
+
+/// The `tools/list` tool names of `pdfcraft-cli mcp `.
+fn listed_tools(flags: &[&str]) -> Vec {
+ let reply = session(flags, &[request(1, "tools/list", json!({}))]).remove(0);
+ reply["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap().to_string()).collect()
+}
+
+#[test]
+fn compact_flag_shortens_the_tool_list() {
+ let full = listed_tools(&[]);
+ let compact = listed_tools(&["--compact"]);
+ assert_eq!(compact.len(), 17, "{compact:?}");
+ assert!(compact.iter().any(|n| n == "tool_search") && compact.iter().any(|n| n == "tool_call"));
+ assert!(compact.iter().all(|n| full.contains(n) || n == "tool_search" || n == "tool_call"));
+ assert!(full.len() > 100 && !full.iter().any(|n| n == "tool_search"), "{} tools", full.len());
+ // The flag can sit on either side of --root.
+ assert_eq!(listed_tools(&["--root", ".", "--compact"]), compact);
+ assert_eq!(listed_tools(&["--compact", "--root", "."]), compact);
+}
+
+#[test]
+fn compact_flag_keeps_the_root() {
+ let root = std::env::temp_dir().join(format!("pdfcraft-cli-compact-root-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&root);
+ std::fs::create_dir_all(&root).unwrap();
+ let outside = std::env::temp_dir().join(format!("pdfcraft-cli-compact-outside-{}.pdf", std::process::id()));
+ let outside = outside.to_string_lossy().into_owned();
+ let root_arg = root.to_string_lossy().into_owned();
+ let open_outside =
+ request(1, "tools/call", json!({ "name": "tool_call", "arguments": { "name": "doc_open", "arguments": { "path": outside } } }));
+ let text = |reply: &Value| reply["result"]["content"][0]["text"].as_str().unwrap_or_default().to_string();
+
+ // With the root, in either flag order, a path outside it is refused with the root's own message.
+ for flags in [vec!["--root", root_arg.as_str(), "--compact"], vec!["--compact", "--root", root_arg.as_str()]] {
+ let reply = session(&flags, std::slice::from_ref(&open_outside)).remove(0);
+ assert_eq!(reply["result"]["isError"], true, "{flags:?}: {reply}");
+ assert!(text(&reply).contains("is outside the allowed directory"), "{flags:?}: {}", text(&reply));
+ }
+ // Without a root the same call gets past that check (the file does not exist, so it fails for that reason instead).
+ let reply = session(&["--compact"], std::slice::from_ref(&open_outside)).remove(0);
+ assert_eq!(reply["result"]["isError"], true, "{reply}");
+ assert!(!text(&reply).contains("is outside the allowed directory"), "{}", text(&reply));
+ let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/apps/pdfcraft-cli/tests/run_root.rs b/apps/pdfcraft-cli/tests/run_root.rs
index 2f9fb69b..511621cc 100644
--- a/apps/pdfcraft-cli/tests/run_root.rs
+++ b/apps/pdfcraft-cli/tests/run_root.rs
@@ -61,11 +61,19 @@ fn script_image_output_is_confined_to_the_root() {
assert!(!base.join("outside/escaped.png").exists() && !base.join("outside/new").exists());
assert_eq!(std::fs::read_to_string(base.join("outside/existing.txt")).unwrap(), "SENTINEL\n");
- // "." is the root itself: refused, without staging a temporary file beside the root.
+ // "." is the root itself: refused, without staging a temporary file beside the root. The
+ // file at the old fixed staging name and the listing are canaries; staging names are random.
std::fs::write(base.join(".root.pdfcraft-tmp"), "SENTINEL\n").unwrap();
+ let listing = || {
+ let mut names: Vec<_> = std::fs::read_dir(&base).unwrap().map(|e| e.unwrap().file_name()).collect();
+ names.sort();
+ names
+ };
+ let before = listing();
let o = render_to(&base, &base, Some(&root), ".");
assert!(!o.status.success() && String::from_utf8_lossy(&o.stderr).contains("is a folder"), "{}", String::from_utf8_lossy(&o.stderr));
assert_eq!(std::fs::read_to_string(base.join(".root.pdfcraft-tmp")).unwrap(), "SENTINEL\n");
+ assert_eq!(listing(), before, "nothing was left beside the root");
// A relative path resolves inside the root, not in the working directory.
let o = render_to(&base, &base, Some(&root), "relative.png");
diff --git a/apps/pdfcraft-cli/tests/stderr.rs b/apps/pdfcraft-cli/tests/stderr.rs
new file mode 100644
index 00000000..9991bc1c
--- /dev/null
+++ b/apps/pdfcraft-cli/tests/stderr.rs
@@ -0,0 +1,132 @@
+//! Diagnostic stderr failures must not replace a command's real result.
+#![cfg(target_os = "linux")]
+
+use std::io::Write as _;
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, Output, Stdio};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+const BIN: &str = env!("CARGO_BIN_EXE_pdfcraft-cli");
+
+struct Scratch(PathBuf);
+impl Scratch {
+ fn new() -> Self {
+ static NEXT: AtomicU64 = AtomicU64::new(0);
+ for _ in 0..128 {
+ let path = std::env::temp_dir().join(format!("pdfcraft-stderr-{}-{}", std::process::id(), NEXT.fetch_add(1, Ordering::Relaxed)));
+ match std::fs::create_dir(&path) {
+ Ok(()) => return Self(path),
+ Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+ Err(error) => panic!("creating stderr test directory: {error}"),
+ }
+ }
+ panic!("no unused stderr test directory after 128 attempts");
+ }
+}
+impl Drop for Scratch {
+ fn drop(&mut self) {
+ let _ = std::fs::remove_dir_all(&self.0);
+ }
+}
+
+// Only this test's newly spawned child is ever terminated, including assertion unwinding.
+struct OwnedChild(Option);
+impl Drop for OwnedChild {
+ fn drop(&mut self) {
+ if let Some(child) = &mut self.0 {
+ let _ = child.kill();
+ let _ = child.wait();
+ }
+ }
+}
+fn run(command: &mut Command, input: Option<&str>) -> Output {
+ command.stdin(if input.is_some() { Stdio::piped() } else { Stdio::null() });
+ let mut owned = OwnedChild(Some(command.spawn().unwrap()));
+ if let Some(input) = input {
+ owned.0.as_mut().unwrap().stdin.take().unwrap().write_all(input.as_bytes()).unwrap();
+ }
+ // Every fixture emits only a few short lines, below the pipe capacity.
+ let deadline = Instant::now() + Duration::from_secs(30);
+ while owned.0.as_mut().unwrap().try_wait().unwrap().is_none() {
+ assert!(Instant::now() < deadline, "owned CLI child exceeded thirty seconds");
+ std::thread::sleep(Duration::from_millis(10));
+ }
+ owned.0.take().unwrap().wait_with_output().unwrap()
+}
+fn full() -> Stdio {
+ std::fs::OpenOptions::new().write(true).open("/dev/full").unwrap().into()
+}
+fn render(pdf: &Path, out: &Path, stderr: Stdio) -> Output {
+ run(Command::new(BIN).arg("render").arg(pdf).args(["--page", "1", "--dpi", "18", "--out"]).arg(out).stdout(Stdio::piped()).stderr(stderr), None)
+}
+
+#[test]
+fn failing_diagnostics_preserve_render_success_and_real_text_or_file_errors() {
+ let dir = Scratch::new();
+ let bytes = pdfcraft_engine::Session::new().create_from_text("Diagnostic test", "Ordinary diagnostic text").unwrap();
+ let pdf = dir.0.join("input.pdf");
+ std::fs::write(&pdf, bytes.as_slice()).unwrap();
+ let image_path = dir.0.join("page.pam");
+ let failed_sink = render(&pdf, &image_path, full());
+ assert!(failed_sink.status.success(), "completed render must survive failed diagnostics: {}", failed_sink.status);
+ assert!(failed_sink.stdout.is_empty());
+ let image = std::fs::read(&image_path).unwrap();
+ assert!(image.starts_with(b"P7\nWIDTH ") && image.windows(7).any(|part| part == b"ENDHDR\n"));
+ let ordinary = render(&pdf, &image_path, Stdio::piped());
+ assert!(ordinary.status.success());
+ assert!(String::from_utf8_lossy(&ordinary.stderr).contains("rendered page 1 at 18 dpi"));
+ assert_eq!(std::fs::read(&image_path).unwrap(), image, "diagnostic destination must not change rendered bytes");
+
+ let invalid = run(Command::new(BIN).arg("text").arg(&pdf).args(["--page", "2"]).stdout(Stdio::piped()).stderr(full()), None);
+ assert_eq!(invalid.status.code(), Some(1), "page errors remain normal failures rather than stderr panics");
+ assert!(invalid.stdout.is_empty());
+ let valid = run(Command::new(BIN).arg("text").arg(&pdf).stdout(Stdio::piped()).stderr(full()), None);
+ assert!(valid.status.success());
+ assert!(String::from_utf8_lossy(&valid.stdout).contains("Ordinary diagnostic text"));
+
+ // An existing directory with a supported extension reaches the real file writer.
+ // Using /dev/full as the render path would only test upstream's extension check.
+ let folder = dir.0.join("folder.pam");
+ std::fs::create_dir(&folder).unwrap();
+ std::fs::write(folder.join("keep"), b"sentinel").unwrap();
+ assert_eq!(render(&pdf, &folder, full()).status.code(), Some(1));
+ assert_eq!(std::fs::read(folder.join("keep")).unwrap(), b"sentinel");
+ assert_eq!(std::fs::read(&image_path).unwrap(), image);
+ assert_eq!(std::fs::read(&pdf).unwrap(), bytes.as_slice());
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn failing_startup_diagnostics_preserve_mcp_replies_and_protocol_output_errors() {
+ let requests = [
+ serde_json::json!({ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } }),
+ serde_json::json!({ "jsonrpc": "2.0", "id": 2, "method": "ping" }),
+ serde_json::json!({ "jsonrpc": "2.0", "id": 3, "method": "ordinary-unknown-method" }),
+ ];
+ let input = requests.iter().map(|request| format!("{request}\n")).collect::();
+ let output = run(Command::new(BIN).arg("mcp").stdout(Stdio::piped()).stderr(full()), Some(&input));
+ assert!(output.status.success(), "failed startup diagnostics must not stop stdio: {}", output.status);
+ let replies: Vec = String::from_utf8(output.stdout).unwrap().lines().map(|line| serde_json::from_str(line).unwrap()).collect();
+ assert_eq!(replies.len(), 3);
+ assert_eq!(replies[0]["id"], 1);
+ assert_eq!(replies[0]["result"]["protocolVersion"], "2025-06-18");
+ assert_eq!(replies[1]["id"], 2);
+ assert_eq!(replies[1]["result"], serde_json::json!({}));
+ assert_eq!(replies[2]["id"], 3);
+ assert_eq!(replies[2]["error"]["code"], -32601);
+ // Upstream's compact mode still reaches stdio even when its expanded diagnostic fails.
+ let ping = "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"ping\"}\n";
+ for (stderr, diagnostic_expected) in [(full(), false), (Stdio::piped(), true)] {
+ let output = run(Command::new(BIN).args(["mcp", "--compact"]).stdout(Stdio::piped()).stderr(stderr), Some(ping));
+ assert!(output.status.success());
+ let reply: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+ assert_eq!(reply["id"], 4);
+ assert_eq!(reply["result"], serde_json::json!({}));
+ if diagnostic_expected {
+ assert!(String::from_utf8_lossy(&output.stderr).contains(", compact tool list); close stdin to stop"));
+ }
+ }
+ let output = run(Command::new(BIN).arg("mcp").stdout(full()).stderr(full()), Some("{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"ping\"}\n"));
+ assert_eq!(output.status.code(), Some(1), "actual protocol output failure must still fail");
+}
diff --git a/apps/pdfcraft-cli/tests/text.rs b/apps/pdfcraft-cli/tests/text.rs
index c573393b..5ac2e07c 100644
--- a/apps/pdfcraft-cli/tests/text.rs
+++ b/apps/pdfcraft-cli/tests/text.rs
@@ -95,3 +95,117 @@ fn text_of_a_protected_document_with_the_password_succeeds() {
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Page 1") && stdout.contains("Page 3"), "{stdout}");
}
+
+mod page_argument_tests {
+ use super::*;
+ use std::path::PathBuf;
+ use std::sync::atomic::{AtomicU64, Ordering};
+
+ struct PageDir(PathBuf);
+
+ impl PageDir {
+ fn new() -> Self {
+ static NEXT: AtomicU64 = AtomicU64::new(0);
+ for _ in 0..128 {
+ let serial = NEXT.fetch_add(1, Ordering::Relaxed);
+ let path = std::env::temp_dir().join(format!("pdfcraft-page-{}-{serial}", std::process::id()));
+ match std::fs::create_dir(&path) {
+ Ok(()) => return Self(path),
+ Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+ Err(error) => panic!("creating page test directory: {error}"),
+ }
+ }
+ panic!("no unused page test directory after 128 attempts");
+ }
+ }
+
+ impl Drop for PageDir {
+ fn drop(&mut self) {
+ let _ = std::fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn malformed_page_values_fail_before_reading_or_printing_document_text() {
+ let dir = PageDir::new();
+ let path = dir.0.join("three.pdf");
+ let bytes = fixture(3);
+ std::fs::write(&path, &bytes).unwrap();
+ let missing = dir.0.join("missing.pdf");
+ let invalid = [
+ vec!["--page", "0"],
+ vec!["--page", ""],
+ vec!["--page", "bad"],
+ vec!["--page", "-1"],
+ vec!["--page", "1.5"],
+ vec!["--page", "18446744073709551616"],
+ vec!["--page"],
+ vec!["--page", "--password", "unused"],
+ vec!["--page", "2", "--page"],
+ ];
+ for input in [&path, &missing] {
+ for args in &invalid {
+ let out = Command::new(BIN).arg("text").arg(input).args(args).output().unwrap();
+ assert_eq!(out.status.code(), Some(1), "{args:?}: {out:?}");
+ assert!(out.stdout.is_empty(), "{args:?}: no text may be printed");
+ assert_eq!(String::from_utf8(out.stderr).unwrap().trim(), "pdfcraft-cli: bad --page: expected a positive page number");
+ assert_eq!(std::fs::read(&path).unwrap(), bytes);
+ assert!(!missing.exists());
+ }
+ }
+ }
+
+ #[test]
+ fn valid_page_values_preserve_all_page_selection_and_first_duplicate_semantics() {
+ let dir = PageDir::new();
+ let path = dir.0.join("three.pdf");
+ let bytes = fixture(3);
+ std::fs::write(&path, &bytes).unwrap();
+ for (args, expected) in [
+ (vec![], vec!["Page 1", "Page 2", "Page 3"]),
+ (vec!["--page", "1"], vec!["Page 1"]),
+ (vec!["--page", "2"], vec!["Page 2"]),
+ (vec!["--page", "3"], vec!["Page 3"]),
+ (vec!["--page", "2", "--page", "1"], vec!["Page 2"]),
+ ] {
+ let out = Command::new(BIN).arg("text").arg(&path).args(args).output().unwrap();
+ assert!(out.status.success(), "{out:?}");
+ assert!(out.stderr.is_empty());
+ let text = String::from_utf8(out.stdout).unwrap();
+ assert_eq!(text.split(' ').map(str::trim).collect::>(), expected);
+ assert_eq!(std::fs::read(&path).unwrap(), bytes);
+ }
+ }
+
+ #[test]
+ fn an_option_shaped_password_is_not_parsed_as_a_page_flag() {
+ let dir = PageDir::new();
+ let source = dir.0.join("three.pdf");
+ let bytes = fixture(3);
+ std::fs::write(&source, &bytes).unwrap();
+ let protected = dir.0.join("protected.pdf");
+ let script = dir.0.join("protect.json");
+ let steps = serde_json::json!([
+ { "tool": "doc_open", "args": { "path": source } },
+ { "tool": "doc_protect", "args": { "doc": 1, "open_password": "--page" } },
+ { "tool": "doc_save", "args": { "doc": 1, "path": protected } },
+ ]);
+ std::fs::write(&script, steps.to_string()).unwrap();
+ let out = Command::new(BIN).args(["run", "--script"]).arg(&script).output().unwrap();
+ assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+ let protected_bytes = std::fs::read(&protected).unwrap();
+ for (args, expected) in [
+ (vec!["--password", "--page"], vec!["Page 1", "Page 2", "Page 3"]),
+ (vec!["--page", "2", "--password", "--page"], vec!["Page 2"]),
+ (vec!["--password", "--page", "--page", "2"], vec!["Page 2"]),
+ ] {
+ let out = Command::new(BIN).arg("text").arg(&protected).args(args).output().unwrap();
+ assert!(out.status.success(), "{out:?}");
+ assert!(out.stderr.is_empty());
+ let text = String::from_utf8(out.stdout).unwrap();
+ assert_eq!(text.split(' ').map(str::trim).collect::>(), expected);
+ assert_eq!(std::fs::read(&protected).unwrap(), protected_bytes);
+ assert_eq!(std::fs::read(&source).unwrap(), bytes);
+ }
+ }
+}
diff --git a/apps/pdfcraft/Cargo.toml b/apps/pdfcraft/Cargo.toml
index 78d9fb5c..2400fe9e 100644
--- a/apps/pdfcraft/Cargo.toml
+++ b/apps/pdfcraft/Cargo.toml
@@ -14,7 +14,9 @@ workspace = true
ureq = { version = "3.4", default-features = false, features = ["rustls-no-provider", "_ring"] }
rustls-native-certs = "0.8"
pdfcraft-ui-egui = { workspace = true }
-eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit", "wayland", "x11", "persistence", "links"] }
+# wgpu draws; OpenGL (glow) is the fallback when wgpu can't start on an old or unusual GPU or
+# driver (#461, #435, #392), and can be chosen with PDFCRAFT_RENDERER=gl.
+eframe = { workspace = true, features = ["default_fonts", "wgpu", "glow", "accesskit", "wayland", "x11", "persistence", "links"] }
egui = { workspace = true }
serde_json = { workspace = true }
# Records from every crate go to standard error and the log file (src/logging.rs).
diff --git a/apps/pdfcraft/src/main.rs b/apps/pdfcraft/src/main.rs
index 8fae5b58..5d567b81 100644
--- a/apps/pdfcraft/src/main.rs
+++ b/apps/pdfcraft/src/main.rs
@@ -19,6 +19,9 @@
#![cfg_attr(all(windows, not(debug_assertions)), windows_subsystem = "windows")]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+use std::cell::Cell;
+use std::rc::Rc;
+
use pdfcraft_ui_egui::PdfCraftApp;
#[cfg(target_os = "macos")]
@@ -39,16 +42,24 @@ const APP_ICON_PNG: &[u8] = include_bytes!("../../../assets/app-icon/hicolor/256
/// The app was called PrintCraft before; settings saved then are under this key.
const LEGACY_STORAGE_KEY: &str = "printcraft";
-/// The settings folder: `app.ron` and the `logs` folder (docs/development.md). eframe would
-/// otherwise derive it from the app id; keep it under "PdfCraft".
+/// The settings folder: `app.ron` and the `logs` folder (docs/development.md). In portable mode
+/// it is `PdfCraftData` beside the executable (#157). eframe would otherwise derive it from the
+/// app id; keep it under "PdfCraft".
fn settings_dir() -> Option {
+ if let Some(dir) = pdfcraft_ui_egui::portable::data_dir() {
+ return Some(dir.to_path_buf());
+ }
eframe::storage_dir("PdfCraft")
}
/// Move the settings and crash-recovery folders of the app's former name, PrintCraft, to the new
/// name once, so an upgrade keeps recent files, preferences and unsaved work. Best effort: a
-/// folder is left alone when the new one already exists or the move fails.
+/// folder is left alone when the new one already exists or the move fails. A portable copy leaves
+/// the per-user folders alone.
fn migrate_legacy_folders() {
+ if pdfcraft_ui_egui::portable::data_dir().is_some() {
+ return;
+ }
let mut moves = vec![(eframe::storage_dir("PrintCraft"), settings_dir())];
// Recovery lives in the settings folder except on Windows, where it is under %LOCALAPPDATA%.
if cfg!(windows) {
@@ -70,6 +81,37 @@ fn migrate_legacy_folders() {
}
}
+/// Desktop launchers (GNOME Files, KDE Dolphin…) only recognise an app as the default handler for a
+/// mime type if its `Exec` takes URIs (`%u`/`%U`), not just paths (`%F`); the packaged `.desktop`
+/// file uses `%U` accordingly (packaging/linux/ai.storyteller.pdfcraft.desktop). Decode a local
+/// `file://` argument (`file:///path` or `file://localhost/path`) to a plain path here so the rest
+/// of the app, which only ever opens paths, is unaffected. Other schemes (`http://`, `mailto:`…),
+/// URIs naming another host, and plain paths pass through untouched.
+fn path_from_arg(arg: String) -> String {
+ let Some(rest) = arg.strip_prefix("file://") else { return arg };
+ let rest = rest.strip_prefix("localhost").unwrap_or(rest);
+ if !rest.starts_with('/') {
+ return arg;
+ }
+ // `file:///C:/x.pdf` on Windows names `C:/x.pdf`. `rest` starts with the one-byte '/', so
+ // byte 1 is a char boundary.
+ let rest = if cfg!(windows) && rest.as_bytes().get(2) == Some(&b':') { &rest[1..] } else { rest };
+ let mut out = Vec::with_capacity(rest.len());
+ let mut bytes = rest.bytes();
+ while let Some(b) = bytes.next() {
+ if b == b'%' {
+ let hex = bytes.clone().take(2).collect::>();
+ if let Some(byte) = std::str::from_utf8(&hex).ok().filter(|h| h.len() == 2).and_then(|h| u8::from_str_radix(h, 16).ok()) {
+ out.push(byte);
+ bytes.nth(1);
+ continue;
+ }
+ }
+ out.push(b);
+ }
+ String::from_utf8(out).unwrap_or(arg)
+}
+
fn main() -> eframe::Result {
// First, so the panic hook and every start-up warning are recorded (`logging`).
let logger = logging::install();
@@ -107,10 +149,89 @@ fn main() -> eframe::Result {
let value = args.next().unwrap_or_default();
options.push((flag.trim_start_matches("--").to_string(), value));
}
- _ => files.push(a),
+ _ => files.push(path_from_arg(a)),
}
}
let integrated = cfg!(target_os = "macos");
+ migrate_legacy_folders();
+ // The log file lives in the settings folder; opened after the arguments (so `--version` leaves
+ // no file behind) and after the PrintCraft migration (which a fresh folder would block).
+ // Records logged until now are written to it first.
+ if let (Some(logger), Some(dir)) = (logger, settings_dir()) {
+ match logger.attach_dir(&dir.join("logs")) {
+ Ok(path) => log::info!("PdfCraft {}, log file {}", env!("CARGO_PKG_VERSION"), path.display()),
+ // Standard error only by now (`attach_dir` gave up on the file); unlike `eprintln!`, never panics.
+ Err(e) => log::warn!("no log file: {e}"),
+ }
+ }
+ let choice = renderer_choice(std::env::var("PDFCRAFT_RENDERER").ok().as_deref());
+ let launch = Launch { files, options, control_file, create_images, integrated };
+ // Finder, Open With and the Dock deliver files as Apple events, not arguments; catch the one
+ // that launched us as well as later ones. Lives until the event loop returns.
+ #[cfg(target_os = "macos")]
+ let apple_events = apple_events::AppleEvents::install();
+ // Set once the app is created, which is after the renderer has started.
+ let started = Rc::new(Cell::new(false));
+ let first = if choice == RendererChoice::Gl { eframe::Renderer::Glow } else { eframe::Renderer::Wgpu };
+ let result = eframe::run_native(
+ "PdfCraft",
+ native_options(integrated, first),
+ app_creator(
+ launch.clone(),
+ Rc::clone(&started),
+ #[cfg(target_os = "macos")]
+ &apple_events,
+ ),
+ );
+ match result {
+ // Only a renderer that couldn't start: without a window or display at all, OpenGL can't
+ // help either, and winit's own error says more.
+ Err(e @ eframe::Error::Wgpu(_)) if retry_with_gl(choice, started.get()) => {
+ // Old or unusual GPUs and drivers (#461, #435, #392) can't give wgpu a device; OpenGL
+ // usually still works there, so that's better than quitting.
+ log::error!("the GPU renderer (wgpu) didn't start: {e}. Starting with OpenGL instead; set PDFCRAFT_RENDERER=gl to skip wgpu.");
+ eframe::run_native(
+ "PdfCraft",
+ native_options(integrated, eframe::Renderer::Glow),
+ app_creator(
+ launch,
+ started,
+ #[cfg(target_os = "macos")]
+ &apple_events,
+ ),
+ )
+ }
+ other => other,
+ }
+}
+
+/// Which renderer to start with, from `PDFCRAFT_RENDERER`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum RendererChoice {
+ /// wgpu, then OpenGL if wgpu can't start (unset, or anything unrecognised).
+ Auto,
+ /// wgpu only (`wgpu`): a failure is reported, not worked around.
+ Wgpu,
+ /// OpenGL only (`gl`, `opengl` or `glow`): for drivers where wgpu starts but misbehaves.
+ Gl,
+}
+
+fn renderer_choice(value: Option<&str>) -> RendererChoice {
+ match value.map(|v| v.trim().to_ascii_lowercase()).as_deref() {
+ Some("wgpu") => RendererChoice::Wgpu,
+ Some("gl" | "opengl" | "glow") => RendererChoice::Gl,
+ _ => RendererChoice::Auto,
+ }
+}
+
+/// Whether a failed run should be retried with OpenGL: only when wgpu was tried first by choice of
+/// nobody, and it failed before the app was created (so while starting the renderer, not later).
+fn retry_with_gl(choice: RendererChoice, app_started: bool) -> bool {
+ choice == RendererChoice::Auto && !app_started
+}
+
+/// The window and renderer settings for one run.
+fn native_options(integrated: bool, renderer: eframe::Renderer) -> eframe::NativeOptions {
let mut viewport = egui::ViewportBuilder::default()
.with_title("PdfCraft")
.with_inner_size([1440.0, 920.0])
@@ -126,90 +247,130 @@ fn main() -> eframe::Result {
if integrated {
viewport = viewport.with_fullsize_content_view(true).with_titlebar_shown(false).with_title_shown(false);
}
- migrate_legacy_folders();
- // The log file lives in the settings folder; opened after the arguments (so `--version` leaves
- // no file behind) and after the PrintCraft migration (which a fresh folder would block).
- // Records logged until now are written to it first.
- if let (Some(logger), Some(dir)) = (logger, settings_dir()) {
- match logger.attach_dir(&dir.join("logs")) {
- Ok(path) => log::info!("PdfCraft {}, log file {}", env!("CARGO_PKG_VERSION"), path.display()),
- // Standard error only by now (`attach_dir` gave up on the file); unlike `eprintln!`, never panics.
- Err(e) => log::warn!("no log file: {e}"),
- }
- }
let persistence_path = settings_dir().map(|d| d.join("app.ron"));
- let mut native = eframe::NativeOptions { viewport, persistence_path, ..Default::default() };
- configure_gpu(&mut native);
- // Finder, Open With and the Dock deliver files as Apple events, not arguments; catch the one
- // that launched us as well as later ones. Lives until the event loop returns.
- #[cfg(target_os = "macos")]
- let apple_events = apple_events::AppleEvents::install();
- #[cfg(target_os = "macos")]
- let apple_events = &apple_events;
- eframe::run_native(
- "PdfCraft",
- native,
- Box::new(move |cc| {
- let mut app = PdfCraftApp::new();
- if let Some(json) = cc.storage.and_then(|s| s.get_string("pdfcraft").or_else(|| s.get_string(LEGACY_STORAGE_KEY))) {
- app.restore(&json);
+ // Set explicitly, so the renderer never depends on which one eframe defaults to.
+ let mut native = eframe::NativeOptions { viewport, persistence_path, renderer, ..Default::default() };
+ if renderer == eframe::Renderer::Wgpu {
+ configure_gpu(&mut native);
+ }
+ native
+}
+
+/// What the command line asked for, kept so a second run (with OpenGL) can start the same way.
+#[derive(Clone)]
+struct Launch {
+ files: Vec,
+ options: Vec<(String, String)>,
+ control_file: Option,
+ create_images: bool,
+ integrated: bool,
+}
+
+fn app_creator<'a>(
+ launch: Launch,
+ started: Rc>,
+ #[cfg(target_os = "macos")] apple_events: &'a apple_events::AppleEvents,
+) -> eframe::AppCreator<'a> {
+ let Launch { files, options, control_file, create_images, integrated } = launch;
+ Box::new(move |cc| {
+ started.set(true);
+ let mut app = PdfCraftApp::new();
+ if let Some(json) = cc.storage.and_then(|s| s.get_string("pdfcraft").or_else(|| s.get_string(LEGACY_STORAGE_KEY))) {
+ app.restore(&json);
+ }
+ app.integrated_titlebar = integrated;
+ app.update_source = Some(std::sync::Arc::new(updates::latest_release));
+ app.os_key_store_ids = cfg!(any(target_os = "macos", target_os = "windows"));
+ #[cfg(target_os = "macos")]
+ {
+ app.os_events = Some(apple_events.connect(&cc.egui_ctx));
+ }
+ if let Some(file) = &control_file {
+ let client = app.attach_control(&cc.egui_ctx);
+ match pdfcraft_ui_egui::control::serve(client).and_then(|ep| write_control_file(file, ep.port, &ep.token).map(|()| ep.port)) {
+ // Never the token (AGENTS.md §3): it stays in the owner-only file.
+ Ok(port) => log::info!("UI control channel on 127.0.0.1:{port} (connection details in {file})"),
+ Err(e) => log::error!("--control {file}: {e}"),
}
- app.integrated_titlebar = integrated;
- app.update_source = Some(std::sync::Arc::new(updates::latest_release));
- app.os_key_store_ids = cfg!(any(target_os = "macos", target_os = "windows"));
- #[cfg(target_os = "macos")]
- {
- app.os_events = Some(apple_events.connect(&cc.egui_ctx));
+ }
+ // Autosave unsaved changes; offer to recover documents a crashed session left behind.
+ if let Some(dir) = pdfcraft_ui_egui::RecoveryStore::default_dir() {
+ app.enable_recovery(pdfcraft_ui_egui::RecoveryStore::new(dir));
+ }
+ // A portable marker whose data folder can't be written (#157): say where settings went.
+ if let Some(w) = &pdfcraft_ui_egui::portable::current().unwritable {
+ app.notify_fmt(
+ "Portable mode is off: {folder} can't be written ({error}). Settings are kept in your user folder instead.",
+ &[("folder", &w.folder.display().to_string()), ("error", &w.error)],
+ );
+ }
+ if create_images {
+ if let Err(e) = app.begin_image_import_paths(&files) {
+ app.notify(e);
}
- if let Some(file) = &control_file {
- let client = app.attach_control(&cc.egui_ctx);
- match pdfcraft_ui_egui::control::serve(client).and_then(|ep| write_control_file(file, ep.port, &ep.token).map(|()| ep.port)) {
- // Never the token (AGENTS.md §3): it stays in the owner-only file.
- Ok(port) => log::info!("UI control channel on 127.0.0.1:{port} (connection details in {file})"),
- Err(e) => log::error!("--control {file}: {e}"),
- }
+ } else {
+ // With the preference on, last session's files come back first; files named on
+ // the command line open after them, in front (#442).
+ app.reopen_last_files(&files);
+ for f in files {
+ app.open_path(&f);
}
- // Autosave unsaved changes; offer to recover documents a crashed session left behind.
- if let Some(dir) = pdfcraft_ui_egui::RecoveryStore::default_dir() {
- app.enable_recovery(pdfcraft_ui_egui::RecoveryStore::new(dir));
+ }
+ for (k, v) in options {
+ if let Err(e) = app.set_option(&k, &v) {
+ log::warn!("--{k} {v}: {e}");
}
- if create_images {
- if let Err(e) = app.begin_image_import_paths(&files) {
- app.notify(e);
- }
- } else {
- for f in files {
- app.open_path(&f);
- }
- }
- for (k, v) in options {
- if let Err(e) = app.set_option(&k, &v) {
- log::warn!("--{k} {v}: {e}");
- }
- }
- Ok(Box::new(app))
- }),
- )
+ }
+ Ok(Box::new(app))
+ })
}
/// Write the control endpoint so that only the current user can read the token.
+///
+/// The JSON goes to a new file next to `path`, created fresh (owner-only on Unix), which then
+/// replaces `path`. Opening `path` itself would follow a link planted there and truncate whatever
+/// it points at; a rename replaces the link and leaves its target alone. A reader polling for the
+/// file also never sees it half-written.
fn write_control_file(path: &str, port: u16, token: &str) -> std::io::Result<()> {
+ use std::io::{ErrorKind, Write};
let json = serde_json::json!({ "port": port, "token": token, "pid": std::process::id() }).to_string();
- let mut opts = std::fs::OpenOptions::new();
- opts.write(true).create(true).truncate(true);
- #[cfg(unix)]
- {
- use std::os::unix::fs::OpenOptionsExt;
- opts.mode(0o600);
+ let path = std::path::Path::new(path);
+ let name = path.file_name().ok_or_else(|| std::io::Error::new(ErrorKind::InvalidInput, "not a file name"))?;
+ // Unpredictable suffixes, so the name can't be planted in advance. `RandomState` is keyed from
+ // the operating system's random source.
+ let random = std::hash::RandomState::new();
+ for i in 0..16u32 {
+ let mut staged = std::ffi::OsString::from(".");
+ staged.push(name);
+ staged.push(format!(".{:016x}.tmp", std::hash::BuildHasher::hash_one(&random, i)));
+ let staged = path.with_file_name(staged);
+ let mut opts = std::fs::OpenOptions::new();
+ opts.write(true).create_new(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ opts.mode(0o600);
+ }
+ let file = match opts.open(&staged) {
+ Ok(f) => f,
+ Err(e) if e.kind() == ErrorKind::AlreadyExists => continue,
+ // Windows refuses `create_new` on a folder with "access denied"; the name is taken all
+ // the same. A folder we can't write to, with nothing at the name, still fails here.
+ Err(e) if e.kind() == ErrorKind::PermissionDenied && staged.symlink_metadata().is_ok() => continue,
+ Err(e) => return Err(e),
+ };
+ // The block closes the file before it is renamed.
+ let written = {
+ let mut file = file;
+ file.write_all(json.as_bytes())
+ };
+ let done = written.and_then(|()| std::fs::rename(&staged, path));
+ if done.is_err() {
+ let _ = std::fs::remove_file(&staged);
+ }
+ return done;
}
- use std::io::Write;
- let mut f = opts.open(path)?;
- #[cfg(unix)]
- {
- use std::os::unix::fs::PermissionsExt;
- f.set_permissions(std::fs::Permissions::from_mode(0o600))?;
- }
- f.write_all(json.as_bytes())
+ Err(std::io::Error::new(ErrorKind::AlreadyExists, "no free name for the control file's temporary copy"))
}
/// How wgpu finds a GPU. Each choice yields to its wgpu environment variable.
@@ -220,7 +381,9 @@ fn write_control_file(path: &str, port: u16, token: &str) -> std::io::Result<()>
/// It also saves battery. Machines with one GPU are unaffected.
/// - On Linux, draw on a GPU that a monitor is plugged into. On a desktop whose monitors all hang
/// off the discrete GPU, drawing on the integrated one leaves the window black under Wayland
-/// compositors on NVIDIA. Among the GPUs that drive a display, the integrated one still wins.
+/// compositors on NVIDIA. When several GPUs drive a display, the one driving a built-in panel
+/// wins (a hybrid laptop, issue #8); without a built-in panel (a desktop with a monitor on each
+/// GPU, issue #445) the discrete one wins, as the integrated one may fail to present there.
/// - On Windows, use Direct3D 12, falling back to OpenGL, and never load Vulkan drivers unless
/// `WGPU_BACKEND` asks for them. Creating a Vulkan instance loads every installed Vulkan driver
/// into the process, and a faulty one (an Intel driver in issue #37) crashed PdfCraft before
@@ -256,58 +419,125 @@ fn configure_gpu(native: &mut eframe::NativeOptions) {
}
}
-/// PCI `(vendor, device)` ids of the GPUs with a connected monitor, read from the DRM connectors
-/// under `drm` (`card1-DP-3/status` is `connected`, `card1/device/{vendor,device}` hold `0x10de`).
+/// A GPU with a connected monitor.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+struct DisplayGpu {
+ /// PCI `(vendor, device)` ids.
+ pci: (u32, u32),
+ /// Whether one of its connected connectors is a built-in panel (`eDP`, `LVDS` or `DSI`).
+ internal_panel: bool,
+}
+
+/// Whether a DRM connector name (`eDP-1`, `LVDS-1`, `DSI-1`) is a laptop's built-in panel.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+fn is_internal_panel(connector: &str) -> bool {
+ ["eDP", "LVDS", "DSI"].iter().any(|kind| connector.starts_with(kind))
+}
+
+/// The GPUs with a connected monitor, read from the DRM connectors under `drm` (`card1-DP-3/status`
+/// is `connected`, `card1/device/{vendor,device}` hold `0x10de`).
#[cfg(target_os = "linux")]
-fn linux_display_gpus(drm: &std::path::Path) -> Vec<(u32, u32)> {
+fn linux_display_gpus(drm: &std::path::Path) -> Vec {
let read_hex = |p: std::path::PathBuf| -> Option {
let s = std::fs::read_to_string(p).ok()?;
u32::from_str_radix(s.trim().trim_start_matches("0x"), 16).ok()
};
- let mut gpus = Vec::new();
+ let mut gpus: Vec = Vec::new();
let Ok(entries) = std::fs::read_dir(drm) else { return gpus };
// A machine has a handful of connectors; the cap only bounds a pathological sysfs.
for entry in entries.flatten().take(256) {
let name = entry.file_name();
- let Some((card, _connector)) = name.to_str().and_then(|n| n.split_once('-')) else { continue };
+ let Some((card, connector)) = name.to_str().and_then(|n| n.split_once('-')) else { continue };
let connected = std::fs::read_to_string(entry.path().join("status")).is_ok_and(|s| s.trim() == "connected");
if !connected {
continue;
}
let device = drm.join(card).join("device");
- if let (Some(v), Some(d)) = (read_hex(device.join("vendor")), read_hex(device.join("device")))
- && !gpus.contains(&(v, d))
- {
- gpus.push((v, d));
+ let (Some(v), Some(d)) = (read_hex(device.join("vendor")), read_hex(device.join("device"))) else { continue };
+ let internal_panel = is_internal_panel(connector);
+ match gpus.iter_mut().find(|g| g.pci == (v, d)) {
+ Some(gpu) => gpu.internal_panel |= internal_panel,
+ None => gpus.push(DisplayGpu { pci: (v, d), internal_panel }),
}
}
gpus
}
-/// Index of the adapter to draw with: one that drives a display (by PCI ids) first, then the most
-/// frugal kind — integrated, discrete, other, virtual, software.
+/// Index of the adapter to draw with: one that drives a display (by PCI ids) first. Among several
+/// of those, the one driving a built-in panel (a hybrid laptop, #8), or else, with no built-in
+/// panel anywhere (a desktop with a monitor on each GPU, #445), the discrete one. Otherwise the
+/// most frugal kind: integrated, discrete, other, virtual, software.
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
-fn pick_adapter(adapters: &[(u32, u32, eframe::wgpu::DeviceType)], displays: &[(u32, u32)]) -> Option {
+fn pick_adapter(adapters: &[(u32, u32, eframe::wgpu::DeviceType)], displays: &[DisplayGpu]) -> Option {
use eframe::wgpu::DeviceType;
+ let display = |pci: (u32, u32)| displays.iter().find(|g| g.pci == pci);
+ let multi_gpu_desktop = displays.len() > 1 && !displays.iter().any(|g| g.internal_panel);
adapters
.iter()
.enumerate()
.min_by_key(|(_, (vendor, device, kind))| {
- let drives_display = displays.contains(&(*vendor, *device));
- let frugality = match kind {
- DeviceType::IntegratedGpu => 0,
- DeviceType::DiscreteGpu => 1,
- DeviceType::Other => 2,
- DeviceType::VirtualGpu => 3,
- DeviceType::Cpu => 4,
+ let shown = display((*vendor, *device));
+ let drives_display = shown.is_some();
+ let drives_panel = shown.is_some_and(|g| g.internal_panel);
+ let rank = match kind {
+ // On a desktop with monitors on both, the integrated GPU can accept the window and
+ // still fail to present to it (#445).
+ DeviceType::DiscreteGpu if drives_display && multi_gpu_desktop => 0,
+ DeviceType::IntegratedGpu => 1,
+ DeviceType::DiscreteGpu => 2,
+ DeviceType::Other => 3,
+ DeviceType::VirtualGpu => 4,
+ DeviceType::Cpu => 5,
};
- (!drives_display, frugality)
+ (!drives_display, !drives_panel, rank)
})
.map(|(i, _)| i)
}
#[cfg(test)]
mod tests {
+ #[test]
+ fn path_from_arg_decodes_file_uris() {
+ assert_eq!(super::path_from_arg("file:///home/alice/report.pdf".to_string()), "/home/alice/report.pdf");
+ assert_eq!(super::path_from_arg("file:///home/alice/my%20report.pdf".to_string()), "/home/alice/my report.pdf");
+ assert_eq!(super::path_from_arg("file://localhost/tmp/a%C3%A9.pdf".to_string()), "/tmp/aé.pdf");
+ // Malformed or truncated escapes are kept as written; bytes that aren't UTF-8 keep the URI.
+ assert_eq!(super::path_from_arg("file:///tmp/100%.pdf".to_string()), "/tmp/100%.pdf");
+ assert_eq!(super::path_from_arg("file:///tmp/a%2".to_string()), "/tmp/a%2");
+ assert_eq!(super::path_from_arg("file:///tmp/%zz%".to_string()), "/tmp/%zz%");
+ assert_eq!(super::path_from_arg("file:///tmp/%FF.pdf".to_string()), "file:///tmp/%FF.pdf");
+ }
+
+ #[test]
+ fn path_from_arg_leaves_plain_paths_and_other_schemes_alone() {
+ assert_eq!(super::path_from_arg("report.pdf".to_string()), "report.pdf");
+ assert_eq!(super::path_from_arg("/home/alice/report.pdf".to_string()), "/home/alice/report.pdf");
+ assert_eq!(super::path_from_arg("https://example.com/report.pdf".to_string()), "https://example.com/report.pdf");
+ assert_eq!(super::path_from_arg("file://server/share/a.pdf".to_string()), "file://server/share/a.pdf");
+ assert_eq!(super::path_from_arg("file://".to_string()), "file://");
+ }
+
+ #[test]
+ fn opengl_is_the_fallback_unless_a_renderer_was_chosen() {
+ use super::{RendererChoice, native_options, renderer_choice, retry_with_gl};
+ assert_eq!(renderer_choice(None), RendererChoice::Auto);
+ assert_eq!(renderer_choice(Some("")), RendererChoice::Auto);
+ assert_eq!(renderer_choice(Some("vulkan")), RendererChoice::Auto);
+ assert_eq!(renderer_choice(Some(" WGPU ")), RendererChoice::Wgpu);
+ for gl in ["gl", "OpenGL", "glow"] {
+ assert_eq!(renderer_choice(Some(gl)), RendererChoice::Gl);
+ }
+ // Retried with OpenGL only when wgpu failed to start by default, never after the app ran.
+ assert!(retry_with_gl(RendererChoice::Auto, false));
+ assert!(!retry_with_gl(RendererChoice::Auto, true));
+ assert!(!retry_with_gl(RendererChoice::Wgpu, false));
+ assert!(!retry_with_gl(RendererChoice::Gl, false));
+ // Each run states its renderer rather than relying on eframe's default.
+ assert_eq!(native_options(false, eframe::Renderer::Wgpu).renderer, eframe::Renderer::Wgpu);
+ assert_eq!(native_options(false, eframe::Renderer::Glow).renderer, eframe::Renderer::Glow);
+ }
+
#[test]
fn gpu_backends_avoid_vulkan_on_windows_and_prefer_low_power() {
let mut native = eframe::NativeOptions::default();
@@ -325,6 +555,23 @@ mod tests {
}
}
+ #[test]
+ fn winit_carries_the_windows_11_monitor_scale_fix() {
+ // Issue #324: winit 0.30.13 as released nudges a window dragged onto a monitor with another
+ // scale factor back onto the one it is leaving, so on Windows 11 it ends up on the wrong
+ // monitor, at the wrong size and scale. vendor/winit carries the fix from winit master. A
+ // dependency bump that resolves winit from crates.io again, or a re-vendored copy without
+ // the patch, would silently bring the bug back: re-apply the patch, or drop the copy once a
+ // winit 0.30 release has the fix (vendor/README.md).
+ let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
+ let lock = std::fs::read_to_string(root.join("Cargo.lock")).unwrap();
+ let winit = lock.split("[[package]]").find(|p| p.contains("\nname = \"winit\"\n")).expect("winit is in Cargo.lock");
+ assert!(!winit.contains("\nsource = "), "winit must resolve to vendor/winit, not:{winit}");
+ let dpi_changed = std::fs::read_to_string(root.join("vendor/winit/src/platform_impl/windows/event_loop.rs")).unwrap();
+ let patch = "if !WIN10_BUILD_VERSION.is_some_and(|build| build < 22000) {\n new_outer_rect = suggested_rect;";
+ assert!(dpi_changed.contains(patch), "vendor/winit lost its WM_DPICHANGED patch");
+ }
+
const NVIDIA: (u32, u32) = (0x10de, 0x2684);
const AMD_IGPU: (u32, u32) = (0x1002, 0x164e);
@@ -333,29 +580,65 @@ mod tests {
vec![(NVIDIA.0, NVIDIA.1, DeviceType::DiscreteGpu), (AMD_IGPU.0, AMD_IGPU.1, DeviceType::IntegratedGpu), (0, 0, DeviceType::Cpu)]
}
+ const INTEL_IGPU: (u32, u32) = (0x8086, 0xa780);
+
+ fn monitor(pci: (u32, u32)) -> super::DisplayGpu {
+ super::DisplayGpu { pci, internal_panel: false }
+ }
+
+ fn panel(pci: (u32, u32)) -> super::DisplayGpu {
+ super::DisplayGpu { pci, internal_panel: true }
+ }
+
#[test]
fn pick_adapter_prefers_the_gpu_driving_the_monitors() {
// A desktop whose monitors are all on the discrete GPU: the integrated one shows black.
- assert_eq!(super::pick_adapter(&adapters(), &[NVIDIA]), Some(0));
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA)]), Some(0));
}
#[test]
fn pick_adapter_keeps_the_integrated_gpu_on_hybrid_laptops() {
// Issue #8: the panel is on the integrated GPU, an external monitor on the discrete one.
- assert_eq!(super::pick_adapter(&adapters(), &[NVIDIA, AMD_IGPU]), Some(1));
- assert_eq!(super::pick_adapter(&adapters(), &[AMD_IGPU]), Some(1));
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA), panel(AMD_IGPU)]), Some(1));
+ assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)]), Some(1));
+ assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU)]), Some(1));
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU)]), Some(1));
+ }
+
+ #[test]
+ fn pick_adapter_prefers_the_discrete_gpu_on_desktops_with_a_monitor_on_each() {
+ // Issue #445: one monitor on the Intel iGPU, one on the NVIDIA card, no built-in panel.
+ use eframe::wgpu::DeviceType;
+ let desktop =
+ [(INTEL_IGPU.0, INTEL_IGPU.1, DeviceType::IntegratedGpu), (NVIDIA.0, NVIDIA.1, DeviceType::DiscreteGpu), (0, 0, DeviceType::Cpu)];
+ assert_eq!(super::pick_adapter(&desktop, &[monitor(INTEL_IGPU), monitor(NVIDIA)]), Some(1));
+ assert_eq!(super::pick_adapter(&desktop, &[monitor(NVIDIA), monitor(INTEL_IGPU)]), Some(1));
+ // A GPU driving no display still loses to one that does.
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU), monitor(INTEL_IGPU)]), Some(1));
}
#[test]
fn pick_adapter_falls_back_to_low_power_without_a_match() {
- assert_eq!(super::pick_adapter(&adapters(), &[(0x8086, 0x1234)]), Some(1));
- assert_eq!(super::pick_adapter(&[], &[NVIDIA]), None);
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234))]), Some(1));
+ assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234)), monitor((0x8086, 0x5678))]), Some(1));
+ assert_eq!(super::pick_adapter(&[], &[monitor(NVIDIA)]), None);
+ }
+
+ #[test]
+ fn internal_panels_are_edp_lvds_and_dsi_connectors() {
+ for name in ["eDP-1", "LVDS-1", "DSI-1"] {
+ assert!(super::is_internal_panel(name), "{name}");
+ }
+ for name in ["DP-3", "HDMI-A-1", "DVI-D-1", "VGA-1", "Writeback-1", ""] {
+ assert!(!super::is_internal_panel(name), "{name}");
+ }
}
#[cfg(target_os = "linux")]
#[test]
fn linux_display_gpus_reads_connected_connectors() -> std::io::Result<()> {
let dir = std::env::temp_dir().join(format!("pdfcraft-drm-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
let card = |name: &str, (vendor, device): (u32, u32)| -> std::io::Result<()> {
std::fs::create_dir_all(dir.join(name).join("device"))?;
std::fs::write(dir.join(name).join("device/vendor"), format!("{vendor:#06x}\n"))?;
@@ -371,10 +654,92 @@ mod tests {
connector("card1-DP-4", "connected")?;
connector("card2-HDMI-A-1", "disconnected")?;
connector("card2-Writeback-1", "unknown")?;
- let gpus = super::linux_display_gpus(&dir);
+ let desktop = super::linux_display_gpus(&dir);
+ // Issue #445: a monitor on the integrated GPU too, still no built-in panel.
+ connector("card2-HDMI-A-1", "connected")?;
+ let mut both = super::linux_display_gpus(&dir);
+ // A hybrid laptop: the integrated GPU drives the built-in panel as well.
+ connector("card2-eDP-1", "connected")?;
+ let mut laptop = super::linux_display_gpus(&dir);
std::fs::remove_dir_all(&dir)?;
- assert_eq!(gpus, vec![NVIDIA]);
+ assert_eq!(desktop, vec![monitor(NVIDIA)]);
+ both.sort_by_key(|g| g.pci);
+ assert_eq!(both, vec![monitor(AMD_IGPU), monitor(NVIDIA)]);
+ laptop.sort_by_key(|g| g.pci);
+ assert_eq!(laptop, vec![panel(AMD_IGPU), monitor(NVIDIA)]);
assert!(super::linux_display_gpus(std::path::Path::new("/nonexistent/drm")).is_empty());
Ok(())
}
+
+ /// A fresh folder per call: tests run in parallel.
+ fn scratch() -> std::path::PathBuf {
+ static N: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
+ let n = N.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+ let d = std::env::temp_dir().join(format!("pdfcraft-control-file-{}-{n}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&d);
+ std::fs::create_dir_all(&d).unwrap();
+ d
+ }
+
+ /// The control file's port and token, and every name in its folder.
+ fn written(dir: &std::path::Path) -> (serde_json::Value, Vec) {
+ let json = serde_json::from_str(&std::fs::read_to_string(dir.join("ctl.json")).unwrap()).unwrap();
+ let mut names: Vec = std::fs::read_dir(dir).unwrap().map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();
+ names.sort();
+ (json, names)
+ }
+
+ #[test]
+ fn the_control_file_replaces_a_hard_link_instead_of_writing_through_it() {
+ // The file used to be opened with create + truncate, so a link planted at the path had its
+ // target truncated and overwritten with the token.
+ let dir = scratch();
+ std::fs::write(dir.join("victim.txt"), "keep me").unwrap();
+ std::fs::hard_link(dir.join("victim.txt"), dir.join("ctl.json")).unwrap();
+ super::write_control_file(&dir.join("ctl.json").to_string_lossy(), 4242, "t0ken").unwrap();
+ assert_eq!(std::fs::read_to_string(dir.join("victim.txt")).unwrap(), "keep me");
+ let (json, names) = written(&dir);
+ assert_eq!((json["port"].as_u64(), json["token"].as_str()), (Some(4242), Some("t0ken")));
+ assert_eq!(names, ["ctl.json", "victim.txt"], "no temporary file left behind");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn the_control_file_replaces_a_symlink_instead_of_writing_through_it() {
+ let dir = scratch();
+ let (link, target) = (dir.join("ctl.json"), dir.join("victim.txt"));
+ std::fs::write(&target, "keep me").unwrap();
+ #[cfg(unix)]
+ let made = std::os::unix::fs::symlink(&target, &link);
+ #[cfg(windows)]
+ let made = std::os::windows::fs::symlink_file(&target, &link);
+ if let Err(e) = made {
+ // Windows needs Developer Mode (or admin) for symlinks.
+ eprintln!("skipped: can't create a symlink here: {e}");
+ let _ = std::fs::remove_dir_all(&dir);
+ return;
+ }
+ super::write_control_file(&link.to_string_lossy(), 4242, "t0ken").unwrap();
+ assert_eq!(std::fs::read_to_string(&target).unwrap(), "keep me");
+ assert!(!std::fs::symlink_metadata(&link).unwrap().file_type().is_symlink());
+ assert_eq!(written(&dir).0["token"].as_str(), Some("t0ken"));
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn the_control_file_replaces_the_one_a_previous_run_left() {
+ let dir = scratch();
+ std::fs::write(dir.join("ctl.json"), r#"{"port":1,"token":"old"}"#).unwrap();
+ super::write_control_file(&dir.join("ctl.json").to_string_lossy(), 4242, "t0ken").unwrap();
+ let (json, names) = written(&dir);
+ assert_eq!(json["token"].as_str(), Some("t0ken"));
+ assert_eq!(names, ["ctl.json"]);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mode = std::fs::metadata(dir.join("ctl.json")).unwrap().permissions().mode();
+ assert_eq!(mode & 0o077, 0, "only the owner can read the token: {mode:o}");
+ }
+ let _ = std::fs::remove_dir_all(&dir);
+ }
}
diff --git a/contributors/people.toml b/contributors/people.toml
index c0549e9d..ade46dac 100644
--- a/contributors/people.toml
+++ b/contributors/people.toml
@@ -22,6 +22,11 @@ real_name = "Brandon Thomas"
display_name = "Brandon Thomas"
sync_github_name = false
+[people.jcl-bit]
+real_name = "James Locke"
+display_name = "James Locke"
+sync_github_name = false
+
[people.switch87]
real_name = "Gert Pellin"
display_name = "Gert Pellin"
@@ -36,3 +41,26 @@ sync_github_name = false
real_name = "Hal Goff"
display_name = "Hal Goff, HG Studio"
sync_github_name = false
+
+[people.mlkonrad]
+real_name = "Marlon Konrad"
+display_name = "Marlon Konrad"
+sync_github_name = false
+
+[people.chiranjeevi-max]
+real_name = "Chiranjeevi Uddanti"
+display_name = "Chiranjeevi U"
+sync_github_name = false
+
+[people.cyfung1031]
+real_name = "Chester Fung"
+display_name = "Chester Fung"
+sync_github_name = true
+
+[people.amitabhthakur]
+sync_github_name = true
+
+[people.chent11]
+real_name = "Tao Chen"
+display_name = "Tao Chen"
+sync_github_name = false
diff --git a/crates/a11y/src/alt.rs b/crates/a11y/src/alt.rs
index 95e272d3..38f0c9f2 100644
--- a/crates/a11y/src/alt.rs
+++ b/crates/a11y/src/alt.rs
@@ -144,10 +144,8 @@ fn content_bbox(doc: &Document, page: &Dict, ids: &HashSet) -> Option<[f64;
let top = ctm.last().copied().unwrap_or(Matrix([1.0, 0.0, 0.0, 1.0, 0.0, 0.0]));
match op.op.as_slice() {
b"q" => ctm.push(top),
- b"Q" => {
- if ctm.len() > 1 {
- ctm.pop();
- }
+ b"Q" if ctm.len() > 1 => {
+ ctm.pop();
}
b"cm" => {
if let Some(m) = Matrix::from_operands(&op.operands)
diff --git a/crates/annot/Cargo.toml b/crates/annot/Cargo.toml
index 9603e572..8a313814 100644
--- a/crates/annot/Cargo.toml
+++ b/crates/annot/Cargo.toml
@@ -11,6 +11,7 @@ workspace = true
[dependencies]
pdfcraft-cos = { workspace = true }
pdfcraft-fonts = { workspace = true }
+pdfcraft-model = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
diff --git a/crates/annot/README.md b/crates/annot/README.md
index b3224b7b..4d0fa7c9 100644
--- a/crates/annot/README.md
+++ b/crates/annot/README.md
@@ -1,6 +1,6 @@
# pdfcraft-annot
-Comments (annotations), ISO 32000-2 §12.5. Layer L3, depends only on `pdfcraft-cos`.
+Comments (annotations), ISO 32000-2 §12.5. Layer L3, depends on `pdfcraft-cos`, `pdfcraft-fonts` and `pdfcraft-model`.
## What it does
@@ -23,6 +23,7 @@ set_review_state(&mut doc, page, index, ReviewState::Accepted, "Ada", &meta)?;
move_annotation(&mut doc, page, index, dx, dy, &meta)?;
set_style(&mut doc, page, index, Some(rgb), Some(0.5), Some(2.0), &meta)?;
delete_annotation(&mut doc, page, index)?;
+signature_image(&doc, page, index)?; // embedded image XObject of Fill & Sign signature/initials
```
A comment is addressed by `(page, index in /Annots)`, the same pair
@@ -37,6 +38,12 @@ deterministic; the engine supplies them.
cloudy borders or callouts, instead of leaving a stale appearance.
- Replies get the parent's `/Rect` and an empty appearance: they appear in comment lists but
never paint a second icon.
+- Resizing a stamp changes its `/Rect` and preserves its original appearance and resources;
+ viewers scale that appearance into the new rectangle. Locked stamps refuse the edit.
+- Natural-size image stamps placed by the engine counterrotate their appearance on rotated
+ pages. Image restyling retains that appearance matrix. Explicit rectangles, image signatures
+ and PDF-page stamps still use their existing placement behavior; page-rotation support for
+ those paths is not complete.
## Not yet
diff --git a/crates/annot/src/appearance.rs b/crates/annot/src/appearance.rs
index ecb8549b..9a026069 100644
--- a/crates/annot/src/appearance.rs
+++ b/crates/annot/src/appearance.rs
@@ -26,23 +26,98 @@ pub fn cloud_radius(w: f64) -> f64 {
6.0 + 1.5 * w.max(0.0)
}
-/// Draw a line ending (`/LE`) at `tip`, for a line arriving from `from`. Open and closed arrows only.
-fn line_end(c: &mut String, kind: &[u8], tip: (f64, f64), from: (f64, f64), w: f64) {
+/// One of the ten `/LE` names (ISO 32000-2 Table 217). Unknown names are not drawn.
+pub(crate) fn known_ending(kind: &[u8]) -> bool {
+ std::str::from_utf8(kind).ok().and_then(crate::LineEnding::parse).is_some()
+}
+
+/// Draw a line ending (`/LE`) at `tip`, for a line arriving from `from`.
+///
+/// Returns false for an unknown style or a non-finite direction, so the caller keeps the
+/// previous appearance instead of writing `NaN`. `None` and a zero-length direction draw nothing.
+fn line_end(c: &mut String, kind: &[u8], tip: (f64, f64), from: (f64, f64), w: f64) -> bool {
if kind == b"None" {
- return;
+ return true;
+ }
+ if !known_ending(kind) {
+ return false;
}
let (dx, dy) = (from.0 - tip.0, from.1 - tip.1);
- let len = dx.hypot(dy);
- if len == 0.0 {
- return;
+ if !dx.is_finite() || !dy.is_finite() {
+ return false;
+ }
+ let len = dx.hypot(dy);
+ if !len.is_finite() {
+ return false;
+ }
+ if len == 0.0 {
+ return true;
}
- let (ux, uy) = (dx / len, dy / len);
let s = arrow_size(w);
- let (cos, sin) = (30f64.to_radians().cos(), 30f64.to_radians().sin());
- let a = (tip.0 + s * (ux * cos - uy * sin), tip.1 + s * (ux * sin + uy * cos));
- let b = (tip.0 + s * (ux * cos + uy * sin), tip.1 + s * (-ux * sin + uy * cos));
- let op = if kind == b"ClosedArrow" { "h B" } else { "S" };
- c.push_str(&format!("{} {} m {} {} l {} {} l {op}\n", n(a.0), n(a.1), n(tip.0), n(tip.1), n(b.0), n(b.1)));
+ if !s.is_finite() {
+ return false;
+ }
+ let (ix, iy) = (dx / len, dy / len);
+ match kind {
+ b"OpenArrow" | b"ClosedArrow" | b"ROpenArrow" | b"RClosedArrow" => {
+ // Open and closed arrows keep their original geometry. A reverse arrow uses the same
+ // head, pointing back along the line.
+ let (ux, uy) = if kind.starts_with(b"R") { (-ix, -iy) } else { (ix, iy) };
+ let (cos, sin) = (30f64.to_radians().cos(), 30f64.to_radians().sin());
+ let a = (tip.0 + s * (ux * cos - uy * sin), tip.1 + s * (ux * sin + uy * cos));
+ let b = (tip.0 + s * (ux * cos + uy * sin), tip.1 + s * (-ux * sin + uy * cos));
+ let op = if kind.ends_with(b"ClosedArrow") { "h B" } else { "S" };
+ c.push_str(&format!("{} {} m {} {} l {} {} l {op}\n", n(a.0), n(a.1), n(tip.0), n(tip.1), n(b.0), n(b.1)));
+ }
+ b"Square" | b"Circle" | b"Diamond" => {
+ let h = s / 2.0;
+ if kind == b"Square" {
+ c.push_str(&format!("{} {} {} {} re h B\n", n(tip.0 - h), n(tip.1 - h), n(s), n(s)));
+ } else if kind == b"Circle" {
+ c.push_str(&ellipse(tip.0 - h, tip.1 - h, tip.0 + h, tip.1 + h));
+ c.push_str("B\n");
+ } else {
+ let (px, py) = (-iy, ix);
+ let v = |along: f64, across: f64| (tip.0 + ix * along + px * across, tip.1 + iy * along + py * across);
+ let (a, b, d, e) = (v(h, 0.0), v(0.0, h), v(-h, 0.0), v(0.0, -h));
+ c.push_str(&format!("{} {} m {} {} l {} {} l {} {} l h B\n", n(a.0), n(a.1), n(b.0), n(b.1), n(d.0), n(d.1), n(e.0), n(e.1)));
+ }
+ }
+ _ => {
+ // Butt is perpendicular to the line. Slash is that stroke turned 45 degrees.
+ let (px, py) = (-iy, ix);
+ let (sx, sy) = if kind == b"Slash" {
+ let q = std::f64::consts::FRAC_1_SQRT_2;
+ (px * q - py * q, px * q + py * q)
+ } else {
+ (px, py)
+ };
+ let h = s / 2.0;
+ c.push_str(&format!("{} {} m {} {} l S\n", n(tip.0 - sx * h), n(tip.1 - sy * h), n(tip.0 + sx * h), n(tip.1 + sy * h)));
+ }
+ }
+ true
+}
+
+/// The cubic Bézier segments (first control point, second control point, end) of a smooth curve
+/// through every point of `pts`, from the first: a Catmull-Rom spline, so the curve leaves each
+/// point parallel to the chord between its neighbours (an end uses itself as the missing
+/// neighbour). Ink is drawn so, as Acrobat draws it, rather than as straight segments. The curve
+/// stays within its points and these control points.
+pub(crate) fn smooth_segments(pts: &[(f64, f64)]) -> Vec<[(f64, f64); 3]> {
+ let Some(&last) = pts.last() else { return Vec::new() };
+ let at = |i: usize| pts.get(i).copied().unwrap_or(last);
+ (0..pts.len().saturating_sub(1))
+ .map(|i| {
+ let (p0, p1, p2, p3) = (at(i.saturating_sub(1)), at(i), at(i + 1), at(i + 2));
+ [(p1.0 + (p2.0 - p0.0) / 6.0, p1.1 + (p2.1 - p0.1) / 6.0), (p2.0 - (p3.0 - p1.0) / 6.0, p2.1 - (p3.1 - p1.1) / 6.0), p2]
+ })
+ .collect()
+}
+
+/// `c` operators for [`smooth_segments`] (the path already starts at the first point).
+fn smooth_curve(pts: &[(f64, f64)]) -> String {
+ smooth_segments(pts).iter().map(|[a, b, e]| format!("{} {} {} {} {} {} c\n", n(a.0), n(a.1), n(b.0), n(b.1), n(e.0), n(e.1))).collect()
}
/// A closed cloudy outline through `pts` (§12.5.4 `/BE /S /C`): each edge becomes a row of
@@ -179,6 +254,12 @@ fn form(bbox: [f64; 4], content: &[u8], resources: Dict) -> Stream {
Stream::flate(d, content)
}
+/// The page `/Rotate` an image signature's picture is turned back by (`/PCPictureRotate`, written
+/// when the signature is added to a turned page): 0, 90, 180 or 270.
+pub(crate) fn picture_turn(d: &Dict) -> i64 {
+ d.get(b"PCPictureRotate").and_then(Object::as_int).unwrap_or(0).rem_euclid(360) / 90 * 90
+}
+
/// Draw the normal appearance of an annotation, or `None` if this subtype/variant isn't supported.
pub fn build(d: &Dict) -> Option {
// Imported measurement appearances may include leaders, captions and formatting that
@@ -313,32 +394,45 @@ pub fn build(d: &Dict) -> Option {
});
}
b"Line" => {
- let l = nums(d, b"L").filter(|l| l.len() == 4)?;
+ let l = nums(d, b"L").filter(|l| l.len() == 4 && l.iter().all(|x| x.is_finite()))?;
let col = stroke?;
let ends: Vec> = match d.get(b"LE") {
None => vec![b"None".to_vec(), b"None".to_vec()],
Some(o) => o.as_array()?.iter().map(|e| e.as_name().map(<[u8]>::to_vec)).collect::>()?,
};
- if ends.len() != 2 || ends.iter().any(|e| !matches!(e.as_slice(), b"None" | b"OpenArrow" | b"ClosedArrow")) {
+ if ends.len() != 2 || ends.iter().any(|e| !known_ending(e)) {
return None;
}
let fill = color(d, b"IC")?.unwrap_or(col);
c.push_str(&format!("{}{}{} w 1 J 1 j\n{}", rg_stroke(col), rg(fill), n(w), dash(d)));
c.push_str(&format!("{} {} m {} {} l S\n[] 0 d\n", n(l[0]), n(l[1]), n(l[2]), n(l[3])));
for (end, (tip, from)) in ends.iter().zip([((l[0], l[1]), (l[2], l[3])), ((l[2], l[3]), (l[0], l[1]))]) {
- line_end(&mut c, end, tip, from, w);
+ if !line_end(&mut c, end, tip, from, w) {
+ return None;
+ }
}
}
b"Polygon" | b"PolyLine" => {
- let v = nums(d, b"Vertices").filter(|v| v.len() >= 4 && v.len() % 2 == 0)?;
+ let v = nums(d, b"Vertices").filter(|v| v.len() >= 4 && v.len() % 2 == 0 && v.iter().all(|x| x.is_finite()))?;
let pts: Vec<(f64, f64)> = v.as_chunks::<2>().0.iter().map(|p| (p[0], p[1])).collect();
let col = stroke;
let closed = subtype == b"Polygon";
let fill = if closed { color(d, b"IC")? } else { None };
- if subtype == b"PolyLine" && d.get(b"LE").is_some_and(|e| e.as_array().is_none_or(|a| a.iter().any(|x| x.as_name() != Some(b"None")))) {
- // Line endings on connected lines aren't drawn yet.
- return None;
- }
+ let ends = if subtype == b"PolyLine" {
+ match d.get(b"LE") {
+ None => None,
+ Some(o) => {
+ let names: Vec> =
+ o.as_array().filter(|a| a.len() == 2)?.iter().map(|e| e.as_name().map(<[u8]>::to_vec)).collect::>()?;
+ if names.iter().any(|e| !known_ending(e)) {
+ return None;
+ }
+ Some(names)
+ }
+ }
+ } else {
+ None
+ };
if let Some(f) = fill {
c.push_str(&rg(f));
}
@@ -362,6 +456,17 @@ pub fn build(d: &Dict) -> Option {
(false, true) => "S\n",
(false, false) => "n\n",
});
+ if let Some(ends) = ends {
+ let col = col?;
+ let (Some(start), Some(end)) = (ends.first(), ends.get(1)) else { return None };
+ let (Some(&tip0), Some(&from0)) = (pts.first(), pts.get(1)) else { return None };
+ let (Some(&tip1), Some(&from1)) = (pts.last(), pts.get(pts.len().saturating_sub(2))) else { return None };
+ let fill = color(d, b"IC")?.unwrap_or(col);
+ c.push_str(&format!("[] 0 d\n{}", rg(fill)));
+ if !line_end(&mut c, start, tip0, from0, w) || !line_end(&mut c, end, tip1, from1, w) {
+ return None;
+ }
+ }
}
b"Caret" => {
// A filled caret: two curved flanks meeting at the top centre.
@@ -396,11 +501,10 @@ pub fn build(d: &Dict) -> Option {
let pts: Vec<(f64, f64)> = pts.as_chunks::<2>().0.iter().map(|p| (p[0], p[1])).collect();
let Some(first) = pts.first() else { continue };
c.push_str(&format!("{} {} m\n", n(first.0), n(first.1)));
- if pts.len() == 1 {
- c.push_str(&format!("{} {} l\n", n(first.0 + 0.01), n(first.1)));
- }
- for p in &pts[1..] {
- c.push_str(&format!("{} {} l\n", n(p.0), n(p.1)));
+ match pts.as_slice() {
+ [_] => c.push_str(&format!("{} {} l\n", n(first.0 + 0.01), n(first.1))),
+ [_, end] => c.push_str(&format!("{} {} l\n", n(end.0), n(end.1))),
+ _ => c.push_str(&smooth_curve(&pts)),
}
c.push_str("S\n");
}
@@ -424,11 +528,14 @@ pub fn build(d: &Dict) -> Option {
return Some(form(rect, c.as_bytes(), res));
}
// A custom stamp: its picture (an image, or a form mapped to /PCPictureSize) fills
- // the rectangle.
+ // the rectangle. An image signature added to a turned page (`/PCPictureRotate`) gets
+ // the standard counter-rotation as its form `/Matrix`: viewers fit the turned
+ // bounding box to `/Rect` (ISO 32000-2 §12.5.5), so it reads upright as displayed.
if let Some(pic) = d.get(b"PCPicture").and_then(Object::as_ref) {
let [x0, y0, x1, y1] = rect;
let (w, h) = (x1 - x0, y1 - y0);
- let place = if matches!(d.get(b"PCPictureImage"), Some(Object::Bool(true))) {
+ let image = matches!(d.get(b"PCPictureImage"), Some(Object::Bool(true)));
+ let place = if image {
format!("{} 0 0 {} {} {} cm", n(w), n(h), n(x0), n(y0))
} else {
let size = nums(d, b"PCPictureSize").filter(|s| s.len() == 2 && s[0] > 0.0 && s[1] > 0.0)?;
@@ -438,7 +545,15 @@ pub fn build(d: &Dict) -> Option {
let mut xo = Dict::new();
xo.set(b"Pic".to_vec(), Object::Ref(pic));
res.set(b"XObject".to_vec(), Object::Dict(xo));
- return Some(form(rect, c.as_bytes(), res));
+ let mut stream = form(rect, c.as_bytes(), res);
+ let turn = picture_turn(d);
+ if image && turn != 0 {
+ // The page's view matrix without its offset: display axes in user space.
+ let m = pdfcraft_model::view_matrix_for(turn, [0.0; 4]);
+ let matrix = [m[0], m[1], m[2], m[3], 0.0, 0.0];
+ stream.dict.set(b"Matrix".to_vec(), Object::Array(matrix.iter().map(|x| Object::Real(*x)).collect()));
+ }
+ return Some(stream);
}
// Only PdfCraft's own Fill & Sign marks are drawn here.
let name = d.name(b"Name")?;
@@ -516,17 +631,22 @@ pub fn build(d: &Dict) -> Option {
None => b"None".to_vec(),
Some(o) => o.as_name()?.to_vec(),
};
- if !matches!(end.as_slice(), b"None" | b"OpenArrow" | b"ClosedArrow") {
+ if !known_ending(&end) {
return None;
}
let lw = bw.max(0.5);
let pts: Vec<(f64, f64)> = cl.as_chunks::<2>().0.iter().map(|p| (p[0], p[1])).collect();
+ if pts.len() < 2 || pts.iter().any(|p| !p.0.is_finite() || !p.1.is_finite()) {
+ return None;
+ }
c.push_str(&format!("{}{}{} w 1 J 1 j\n", rg_stroke(text_color), rg(bg.unwrap_or([1.0; 3])), n(lw)));
for (i, p) in pts.iter().enumerate() {
c.push_str(&format!("{} {} {}\n", n(p.0), n(p.1), if i == 0 { "m" } else { "l" }));
}
c.push_str("S\n");
- line_end(&mut c, &end, pts[0], pts[1], lw);
+ if !line_end(&mut c, &end, pts[0], pts[1], lw) {
+ return None;
+ }
}
if let Some(bg) = bg {
c.push_str(&format!("{}{} {} {} {} re f\n", rg(bg), n(rect[0]), n(rect[1]), n(rect[2] - rect[0]), n(rect[3] - rect[1])));
diff --git a/crates/annot/src/lib.rs b/crates/annot/src/lib.rs
index a0f76306..9eb34651 100644
--- a/crates/annot/src/lib.rs
+++ b/crates/annot/src/lib.rs
@@ -274,6 +274,55 @@ impl StampKind {
}
}
+/// A line ending (`/LE`): the ten styles in ISO 32000-2 Table 217.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LineEnding {
+ None,
+ Square,
+ Circle,
+ Diamond,
+ OpenArrow,
+ ClosedArrow,
+ Butt,
+ ROpenArrow,
+ RClosedArrow,
+ Slash,
+}
+
+impl LineEnding {
+ pub const ALL: [Self; 10] = [
+ Self::None,
+ Self::Square,
+ Self::Circle,
+ Self::Diamond,
+ Self::OpenArrow,
+ Self::ClosedArrow,
+ Self::Butt,
+ Self::ROpenArrow,
+ Self::RClosedArrow,
+ Self::Slash,
+ ];
+
+ pub fn name(self) -> &'static str {
+ match self {
+ Self::None => "None",
+ Self::Square => "Square",
+ Self::Circle => "Circle",
+ Self::Diamond => "Diamond",
+ Self::OpenArrow => "OpenArrow",
+ Self::ClosedArrow => "ClosedArrow",
+ Self::Butt => "Butt",
+ Self::ROpenArrow => "ROpenArrow",
+ Self::RClosedArrow => "RClosedArrow",
+ Self::Slash => "Slash",
+ }
+ }
+
+ pub fn parse(name: &str) -> Option {
+ Self::ALL.into_iter().find(|ending| ending.name() == name)
+ }
+}
+
/// Geometry of a new comment, in PDF user space of its page.
#[derive(Clone, Debug, PartialEq)]
pub enum Shape {
@@ -294,11 +343,12 @@ pub enum Shape {
Oval {
rect: [f64; 4],
},
- /// A line, with an open arrowhead at `to` when `arrow` is set.
+ /// A line. An open arrow at `to` is `start: None`, `end: OpenArrow` (the Arrow tool).
Line {
from: [f64; 2],
to: [f64; 2],
- arrow: bool,
+ start: LineEnding,
+ end: LineEnding,
},
/// Freehand strokes (Draw tool).
Ink {
@@ -357,9 +407,11 @@ pub enum Shape {
vertices: Vec<[f64; 2]>,
cloud: bool,
},
- /// Connected lines (Polygonal Line tool).
+ /// Connected lines (Polygonal Line tool). `start` is the first vertex, `end` the last.
PolyLine {
vertices: Vec<[f64; 2]>,
+ start: LineEnding,
+ end: LineEnding,
},
/// A text callout: a text box at `rect` with a leader line from `point` (arrowhead) via
/// `knee` to the box (FreeText, `/IT /FreeTextCallout`, `/CL`).
@@ -368,6 +420,7 @@ pub enum Shape {
knee: [f64; 2],
point: [f64; 2],
font_size: f64,
+ ending: LineEnding,
},
/// Insert text: a caret in `rect` (its point at the top centre).
Caret {
@@ -662,6 +715,31 @@ fn annot_dict(doc: &Document, r: ObjRef) -> Dict {
doc.get(r).as_dict().cloned().unwrap_or_default()
}
+/// The embedded image of a Fill & Sign image signature or initials (0-based target).
+/// Other stamps have appearances that can't be represented by this image alone.
+pub fn signature_image(doc: &Document, page: usize, index: usize) -> Result, AnnotError> {
+ let p = page_ref(doc, page)?;
+ let list = annots(doc, p);
+ let entry = list.get(index).ok_or(AnnotError::NoSuchAnnotation { page, index })?;
+ let obj = doc.resolve(entry);
+ let Some(d) = obj.as_dict() else { return Ok(None) };
+ Ok((d.name(b"Subtype") == Some(b"Stamp")
+ && matches!(d.name(b"Name"), Some(b"PCCustomSignature" | b"PCCustomInitials"))
+ && matches!(d.get(b"PCPictureImage"), Some(Object::Bool(true))))
+ .then(|| d.reference(b"PCPicture"))
+ .flatten())
+}
+
+/// The page `/Rotate` the picture of the image signature at `(page, index)` is drawn turned back
+/// by, so it reads upright on a page shown that way: 0 for one added to an unturned page, or by
+/// another app. The picture appears turned by the page's current rotation less this.
+pub fn picture_rotation(doc: &Document, page: usize, index: usize) -> Result {
+ let p = page_ref(doc, page)?;
+ let list = annots(doc, p);
+ let entry = list.get(index).ok_or(AnnotError::NoSuchAnnotation { page, index })?;
+ Ok(doc.resolve(entry).as_dict().map_or(0, appearance::picture_turn))
+}
+
// ── building ────────────────────────────────────────────────────────────────────────────────
/// Annotation flags (§12.5.3).
@@ -701,6 +779,14 @@ fn grow(r: [f64; 4], by: f64) -> [f64; 4] {
[r[0] - by, r[1] - by, r[2] + by, r[3] + by]
}
+fn ending_draws(ending: LineEnding) -> bool {
+ ending != LineEnding::None
+}
+
+fn ending_pair(start: LineEnding, end: LineEnding) -> Object {
+ Object::Array(vec![Object::name(start.name()), Object::name(end.name())])
+}
+
/// Validate and compute `/Rect` for a new comment.
fn rect_for(shape: &Shape, style: &Style) -> Result<[f64; 4], AnnotError> {
let bad = |what: &str| AnnotError::Invalid(format!("invalid {what}"));
@@ -724,7 +810,6 @@ fn rect_for(shape: &Shape, style: &Style) -> Result<[f64; 4], AnnotError> {
| Shape::TextBox { rect, .. }
| Shape::Typewriter { rect, .. }
| Shape::Stamp { rect, .. }
- | Shape::CustomStamp { rect, .. }
| Shape::TypedSignature { rect, .. }
| Shape::Mark { rect, .. } => {
let r = normalize(*rect);
@@ -733,18 +818,32 @@ fn rect_for(shape: &Shape, style: &Style) -> Result<[f64; 4], AnnotError> {
}
r
}
- Shape::Line { from, to, arrow } => {
+ Shape::CustomStamp { rect, .. } => {
+ let r = normalize(*rect);
+ // Image signatures may be very thin; a positive PDF appearance box still works.
+ if !finite(rect) || r[2] <= r[0] || r[3] <= r[1] {
+ return Err(bad("rectangle (empty)"));
+ }
+ r
+ }
+ Shape::Line { from, to, start, end } => {
if !finite(from) || !finite(to) || (from[0] - to[0]).hypot(from[1] - to[1]) < 1.0 {
return Err(bad("line (too short)"));
}
- let pad = half + if *arrow { appearance::arrow_size(style.width) } else { 0.0 };
+ let pad = half + if ending_draws(*start) || ending_draws(*end) { appearance::arrow_size(style.width) } else { 0.0 };
grow(bounds([*from, *to].into_iter()).unwrap_or_default(), pad + 1.0)
}
Shape::Ink { strokes } | Shape::Signature { strokes } => {
if strokes.iter().all(|s| s.is_empty()) || !strokes.iter().flatten().all(|p| finite(p)) {
return Err(bad("drawing (no points)"));
}
- grow(bounds(strokes.iter().flatten().copied()).unwrap_or_default(), half + 1.0)
+ // Strokes of three or more points are drawn as curves, which stay within their
+ // points and control points.
+ let controls = strokes.iter().filter(|s| s.len() > 2).flat_map(|s| {
+ let pts: Vec<(f64, f64)> = s.iter().map(|p| (p[0], p[1])).collect();
+ appearance::smooth_segments(&pts).into_iter().flat_map(|[a, b, _]| [[a.0, a.1], [b.0, b.1]])
+ });
+ grow(bounds(strokes.iter().flatten().copied().chain(controls)).unwrap_or_default(), half + 1.0)
}
Shape::Polygon { vertices, cloud } => {
let b = bounds(vertices.iter().copied())
@@ -752,10 +851,11 @@ fn rect_for(shape: &Shape, style: &Style) -> Result<[f64; 4], AnnotError> {
let b = b.ok_or_else(|| bad("polygon (it needs three points)"))?;
grow(b, half + 1.0 + if *cloud { 1.5 * appearance::cloud_radius(style.width) } else { 0.0 })
}
- Shape::PolyLine { vertices } => {
+ Shape::PolyLine { vertices, start, end } => {
let b = bounds(vertices.iter().copied())
.filter(|b| vertices.len() >= 2 && vertices.iter().all(|p| finite(p)) && (b[2] - b[0]).max(b[3] - b[1]) >= 1.0);
- grow(b.ok_or_else(|| bad("connected lines (they need two points)"))?, half + 1.0)
+ let extra = if ending_draws(*start) || ending_draws(*end) { appearance::arrow_size(style.width) } else { 0.0 };
+ grow(b.ok_or_else(|| bad("connected lines (they need two points)"))?, half + 1.0 + extra)
}
Shape::Callout { rect, knee, point, .. } => {
let r = normalize(*rect);
@@ -808,7 +908,7 @@ fn subject(shape: &Shape) -> &'static str {
Shape::TextMarkup { kind: Markup::Squiggly, .. } => "Squiggly",
Shape::Rectangle { .. } => "Rectangle",
Shape::Oval { .. } => "Oval",
- Shape::Line { arrow: true, .. } => "Arrow",
+ Shape::Line { start: LineEnding::None, end: LineEnding::OpenArrow, .. } => "Arrow",
Shape::Line { .. } => "Line",
Shape::Ink { .. } => "Pencil",
Shape::TextBox { .. } => "Text Box",
@@ -905,11 +1005,11 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
}
border(&mut d);
}
- Shape::Line { from, to, arrow } => {
+ Shape::Line { from, to, start, end } => {
d.set(b"C".to_vec(), rgb(style.color));
d.set(b"L".to_vec(), num_array(&[from[0], from[1], to[0], to[1]]));
- if *arrow {
- d.set(b"LE".to_vec(), Object::Array(vec![Object::name("None"), Object::name("OpenArrow")]));
+ if ending_draws(*start) || ending_draws(*end) {
+ d.set(b"LE".to_vec(), ending_pair(*start, *end));
}
border(&mut d);
}
@@ -940,6 +1040,14 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
d.set(b"PCPicture".to_vec(), Object::Ref(*picture));
d.set(b"PCPictureImage".to_vec(), Object::Bool(*image));
d.set(b"PCPictureSize".to_vec(), num_array(&[size.0, size.1]));
+ // An image signature's rectangle is in user space; on a turned page its appearance is
+ // turned back (see `appearance::build`), so it reads upright as displayed.
+ if *image && matches!(clean.as_str(), "Signature" | "Initials") {
+ let turn = pdfcraft_model::pages(doc).get(new.page).map_or(0, |p| p.rotation(doc));
+ if turn != 0 {
+ d.set(b"PCPictureRotate".to_vec(), Object::Int(turn));
+ }
+ }
}
Shape::Ink { strokes } | Shape::Signature { strokes } => {
d.set(b"C".to_vec(), rgb(style.color));
@@ -962,9 +1070,12 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
}
border(&mut d);
}
- Shape::PolyLine { vertices } => {
+ Shape::PolyLine { vertices, start, end } => {
d.set(b"C".to_vec(), rgb(style.color));
d.set(b"Vertices".to_vec(), num_array(&vertices.concat()));
+ if ending_draws(*start) || ending_draws(*end) {
+ d.set(b"LE".to_vec(), ending_pair(*start, *end));
+ }
border(&mut d);
}
Shape::Caret { .. } => {
@@ -1001,12 +1112,12 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
d.set(b"Contents".to_vec(), PdfString::text(file.trim()));
}
}
- Shape::Callout { rect: tb, knee, point, .. } => {
+ Shape::Callout { rect: tb, knee, point, ending, .. } => {
let tb = normalize(*tb);
let attach = callout_attach(tb, *knee);
d.set(b"IT".to_vec(), Object::name("FreeTextCallout"));
d.set(b"CL".to_vec(), num_array(&[point[0], point[1], knee[0], knee[1], attach[0], attach[1]]));
- d.set(b"LE".to_vec(), Object::name("OpenArrow"));
+ d.set(b"LE".to_vec(), Object::name(ending.name()));
// The text box inside /Rect (§12.5.6.6 /RD).
d.set(b"RD".to_vec(), num_array(&[tb[0] - rect[0], tb[1] - rect[1], rect[2] - tb[2], rect[3] - tb[3]]));
}
@@ -1050,14 +1161,57 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
Ok(index)
}
+/// Counterrotate a newly placed image stamp's appearance into displayed-page axes.
+/// The normal appearance's transformed bounding box is fitted to `/Rect` by PDF viewers.
+pub fn orient_image_stamp(doc: &mut Document, page: usize, index: usize, rotation: i64) -> Result<(), AnnotError> {
+ let matrix = match rotation {
+ 90 => [0.0, 1.0, -1.0, 0.0, 0.0, 0.0],
+ 180 => [-1.0, 0.0, 0.0, -1.0, 0.0, 0.0],
+ 270 => [0.0, -1.0, 1.0, 0.0, 0.0, 0.0],
+ _ => return Ok(()),
+ };
+ let (_, r) = annot_ref(doc, page, index)?;
+ let d = annot_dict(doc, r);
+ if d.name(b"Subtype") != Some(b"Stamp") || !matches!(d.get(b"PCPictureImage"), Some(Object::Bool(true))) {
+ return Err(AnnotError::Invalid("only an image stamp can be oriented".into()));
+ }
+ let normal = d
+ .get(b"AP")
+ .map(|ap| doc.resolve(ap))
+ .and_then(|ap| ap.as_dict().and_then(|ap| ap.reference(b"N")))
+ .ok_or_else(|| AnnotError::Invalid("the stamp has no normal appearance".into()))?;
+ let Object::Stream(mut stream) = doc.get(normal).as_ref().clone() else {
+ return Err(AnnotError::Invalid("the stamp's normal appearance is not a stream".into()));
+ };
+ stream.dict.set(b"Matrix".to_vec(), num_array(&matrix));
+ doc.set(normal, Object::Stream(stream));
+ Ok(())
+}
+
/// (Re)generate `/AP /N` for the annotation `r` from its dictionary.
/// Regenerate an annotation's normal appearance from its dictionary.
pub fn set_appearance(doc: &mut Document, r: ObjRef) -> Result<(), AnnotError> {
let d = annot_dict(doc, r);
let subtype = String::from_utf8_lossy(d.name(b"Subtype").unwrap_or_default()).into_owned();
- let Some(stream) = appearance::build(&d) else { return Err(AnnotError::Unsupported(subtype)) };
+ let Some(mut stream) = appearance::build(&d) else { return Err(AnnotError::Unsupported(subtype)) };
+ // Image stamp restyling must retain the placement's page-axis correction.
+ if matches!(d.get(b"PCPictureImage"), Some(Object::Bool(true))) {
+ let matrix = d.get(b"AP").and_then(|ap| {
+ let ap = doc.resolve(ap);
+ let normal = doc.resolve(ap.as_dict()?.get(b"N")?);
+ let Object::Stream(normal) = normal.as_ref() else { return None };
+ normal.dict.get(b"Matrix").cloned()
+ });
+ if let Some(matrix) = matrix {
+ stream.dict.set(b"Matrix".to_vec(), matrix);
+ }
+ }
let ap = doc.add(Object::Stream(stream));
- let mut apd = Dict::new();
+ // A copy (a shared /AP is left alone) that keeps unknown entries; the old down and rollover
+ // appearances would show the previous look on press or hover, so they go with the old /N.
+ let mut apd = d.get(b"AP").map(|a| doc.resolve(a)).and_then(|a| a.as_dict().cloned()).unwrap_or_default();
+ apd.remove(b"D");
+ apd.remove(b"R");
apd.set(b"N".to_vec(), Object::Ref(ap));
doc.update_dict(r, |d| {
d.set(b"AP".to_vec(), Object::Dict(apd));
@@ -1066,6 +1220,30 @@ pub fn set_appearance(doc: &mut Document, r: ObjRef) -> Result<(), AnnotError> {
Ok(())
}
+/// A copy of `doc` in which every annotation without a normal appearance (`/AP /N`) has the one
+/// [`appearance::build`] draws from its dictionary, for displaying the document (`None` when no
+/// annotation needs one). Many files carry comments without appearances (FreeText, Ink, notes,
+/// stamps, …) that viewers draw from the dictionary. `doc` is not changed: saving writes the file
+/// as it was. Links, form fields and pop-ups keep their own handling.
+pub fn with_missing_appearances(doc: &Document) -> Option {
+ let mut copy: Option = None;
+ for page in page_refs(doc).ok()? {
+ for r in annots(doc, page).iter().filter_map(Object::as_ref) {
+ let d = annot_dict(doc, r);
+ if matches!(d.name(b"Subtype"), None | Some(b"Link" | b"Widget" | b"Popup")) {
+ continue;
+ }
+ let has_normal = d.get(b"AP").is_some_and(|ap| doc.resolve(ap).as_dict().is_some_and(|ap| ap.contains(b"N")));
+ if has_normal || appearance::build(&d).is_none() {
+ continue;
+ }
+ // Fails only when `r` isn't a dictionary, which `build` above has just ruled out.
+ set_appearance(copy.get_or_insert_with(|| doc.clone()), r).ok();
+ }
+ }
+ copy
+}
+
/// Format a number for content streams and DA strings.
pub(crate) fn n(v: f64) -> String {
let s = format!("{:.3}", if v.abs() < 5e-4 { 0.0 } else { v });
@@ -1353,12 +1531,24 @@ pub fn move_annotation(doc: &mut Document, page: usize, index: usize, dx: f64, d
Ok(())
}
-/// Resize a rectangle, oval or text box to `rect`; its appearance is redrawn.
+/// Resize a rectangle, oval, text box or stamp to `rect`. Stamps keep their appearance,
+/// which PDF viewers scale from its bounding box into the new rectangle.
pub fn set_rect(doc: &mut Document, page: usize, index: usize, rect: [f64; 4], meta: &Meta) -> Result<(), AnnotError> {
let (_, r) = annot_ref(doc, page, index)?;
unlocked(doc, r)?;
let d = annot_dict(doc, r);
let subtype = String::from_utf8_lossy(d.name(b"Subtype").unwrap_or_default()).into_owned();
+ if subtype == "Stamp" {
+ let rect = normalize(rect);
+ if !finite(&rect) || rect[2] <= rect[0] || rect[3] <= rect[1] {
+ return Err(AnnotError::Invalid("invalid rectangle (too small)".into()));
+ }
+ doc.update_dict(r, |d| {
+ d.set(b"Rect".to_vec(), num_array(&rect));
+ touch(d, meta);
+ })?;
+ return Ok(());
+ }
if !matches!(subtype.as_str(), "Square" | "Circle" | "FreeText") {
return Err(AnnotError::Invalid(format!("{subtype} comments can't be resized")));
}
@@ -1405,7 +1595,8 @@ fn border_width_of(d: &Dict) -> f64 {
d.get(b"BS").and_then(|b| b.as_dict()).and_then(|b| b.get(b"W")).and_then(|w| w.as_f64()).unwrap_or(1.0).max(0.0)
}
-/// Change a comment's colour, opacity and/or line width, and redraw it.
+/// Change a comment's colour, opacity, line width and/or line endings, and redraw it.
+#[allow(clippy::too_many_arguments)]
pub fn set_style(
doc: &mut Document,
page: usize,
@@ -1413,6 +1604,7 @@ pub fn set_style(
color: Option,
opacity: Option,
width: Option,
+ endings: Option<&[LineEnding]>,
meta: &Meta,
) -> Result<(), AnnotError> {
let (_, r) = annot_ref(doc, page, index)?;
@@ -1421,11 +1613,18 @@ pub fn set_style(
let subtype = String::from_utf8_lossy(d.name(b"Subtype").unwrap_or_default()).into_owned();
// Check before changing anything: a stale appearance would contradict the new style.
if appearance::build(&d).is_none() {
- return Err(AnnotError::Unsupported(subtype));
+ return Err(AnnotError::Unsupported(subtype.clone()));
}
if color.is_some_and(|c| !finite(&c)) || opacity.is_some_and(|o| !o.is_finite()) || width.is_some_and(|w| !w.is_finite()) {
return Err(AnnotError::Invalid("invalid style".into()));
}
+ if let Some(ends) = endings {
+ let callout = subtype == "FreeText" && d.contains(b"CL");
+ let pair = matches!(subtype.as_str(), "Line" | "PolyLine");
+ if (callout && ends.len() != 1) || (pair && ends.len() != 2) || (!callout && !pair) {
+ return Err(AnnotError::Invalid("this comment has no line endings to change".into()));
+ }
+ }
let free_text = subtype == "FreeText";
doc.update_dict(r, |d| {
if let Some(c) = color {
@@ -1452,11 +1651,55 @@ pub fn set_style(
d.set(b"BS".to_vec(), Object::Dict(bs));
d.remove(b"Border");
}
+ if let Some(ends) = endings {
+ if ends.len() == 1 {
+ if let Some(ending) = ends.first() {
+ d.set(b"LE".to_vec(), Object::name(ending.name()));
+ }
+ } else if let (Some(start), Some(end)) = (ends.first(), ends.get(1)) {
+ d.set(b"LE".to_vec(), ending_pair(*start, *end));
+ }
+ }
+ ensure_ending_room(d);
touch(d, meta);
})?;
set_appearance(doc, r)
}
+/// Grow a line or polyline's rectangle so a non-`None` ending is not clipped. Idempotent.
+fn ensure_ending_room(d: &mut Dict) {
+ let subtype = d.name(b"Subtype").unwrap_or_default();
+ if !matches!(subtype, b"Line" | b"PolyLine") {
+ return;
+ }
+ if !line_endings_of(d).is_some_and(|ends| ends.iter().any(|e| ending_draws(*e))) {
+ return;
+ }
+ let key: &[u8] = if subtype == b"Line" { b"L" } else { b"Vertices" };
+ let Some(pts) = pair_points(d, key) else { return };
+ let Some(bounds) = bounds(pts.iter().copied()) else { return };
+ let w = border_width_of(d);
+ let need = grow(bounds, w / 2.0 + appearance::arrow_size(w) + 1.0);
+ let vals: Vec = d.get(b"Rect").and_then(|o| o.as_array()).map(|a| a.iter().filter_map(|x| x.as_f64()).collect()).unwrap_or_default();
+ let Some(rect) = four(&vals) else { return };
+ let union = [rect[0].min(need[0]), rect[1].min(need[1]), rect[2].max(need[2]), rect[3].max(need[3])];
+ if union != rect {
+ d.set(b"Rect".to_vec(), num_array(&union));
+ }
+}
+
+fn four(v: &[f64]) -> Option<[f64; 4]> {
+ Some([*v.first()?, *v.get(1)?, *v.get(2)?, *v.get(3)?])
+}
+
+fn pair_points(d: &Dict, key: &[u8]) -> Option> {
+ let v: Vec = d.get(key)?.as_array()?.iter().filter_map(|o| o.as_f64()).collect();
+ if v.len() < 4 || !v.len().is_multiple_of(2) || v.iter().any(|x| !x.is_finite()) {
+ return None;
+ }
+ Some(v.as_chunks::<2>().0.to_vec())
+}
+
// ── reading ─────────────────────────────────────────────────────────────────────────────────
/// One comment as the viewer lists it (the same fields and rules as
@@ -1602,6 +1845,8 @@ pub struct Props {
pub restylable: bool,
/// The Locked flag.
pub locked: bool,
+ /// `/LE`: two names for a line or polyline (`None` when unset), one for a callout.
+ pub endings: Option>,
}
/// The current properties of the comment at `(page, index)`.
@@ -1626,9 +1871,23 @@ pub fn props(doc: &Document, page: usize, index: usize) -> Option {
restylable: appearance::build(d).is_some(),
locked: d.get(b"F").and_then(|f| doc.resolve(f).as_int()).unwrap_or(0) & FLAG_LOCKED != 0,
subtype,
+ endings: line_endings_of(d),
})
}
+/// `/LE` for a line, polyline or callout. Unknown names yield `None` so the control stays hidden.
+fn line_endings_of(d: &Dict) -> Option> {
+ let parse = |name: &[u8]| std::str::from_utf8(name).ok().and_then(LineEnding::parse);
+ match d.name(b"Subtype")? {
+ b"Line" | b"PolyLine" => match d.get(b"LE") {
+ None => Some(vec![LineEnding::None, LineEnding::None]),
+ Some(o) => o.as_array().filter(|a| a.len() == 2)?.iter().map(|e| parse(e.as_name()?)).collect(),
+ },
+ b"FreeText" if d.contains(b"CL") => Some(vec![parse(d.name(b"LE").unwrap_or(b"None"))?]),
+ _ => None,
+ }
+}
+
/// Replace Text (Acrobat's proposal): strike out `quads` and add a caret at the end of the
/// struck text holding `replacement`, grouped with the strikeout (`/IRT` + `/RT /Group`) so they
/// move, list and delete as one. Returns the strikeout's index.
diff --git a/crates/annot/src/tests.rs b/crates/annot/src/tests.rs
index afcee4bb..5990e0d0 100644
--- a/crates/annot/src/tests.rs
+++ b/crates/annot/src/tests.rs
@@ -60,7 +60,7 @@ fn list(doc: &Document, page: usize) -> Vec {
}
fn ap_content(doc: &Document, d: &Dict) -> String {
- let n = d.get(b"AP").and_then(|a| a.as_dict()).and_then(|a| a.reference(b"N")).expect("has /AP /N");
+ let n = d.get(b"AP").map(|a| doc.resolve(a)).and_then(|a| a.as_dict().and_then(|a| a.reference(b"N"))).expect("has /AP /N");
let obj = doc.get(n);
let Object::Stream(s) = &*obj else { panic!("AP is not a stream") };
String::from_utf8_lossy(&s.decoded().unwrap()).into_owned()
@@ -84,7 +84,7 @@ fn every_tool_creates_a_drawable_comment() {
Shape::TextMarkup { kind: Markup::Squiggly, quads: vec![[72.0, 412.0, 200.0, 412.0, 72.0, 400.0, 200.0, 400.0]] },
Shape::Rectangle { rect: [300.0, 300.0, 200.0, 200.0] },
Shape::Oval { rect: [300.0, 300.0, 400.0, 350.0] },
- Shape::Line { from: [50.0, 50.0], to: [150.0, 100.0], arrow: true },
+ Shape::Line { from: [50.0, 50.0], to: [150.0, 100.0], start: LineEnding::None, end: LineEnding::OpenArrow },
Shape::Ink { strokes: vec![vec![[10.0, 10.0], [20.0, 30.0], [30.0, 10.0]], vec![[40.0, 40.0]]] },
Shape::TextBox { rect: [300.0, 600.0, 500.0, 650.0], font_size: 14.0 },
];
@@ -141,6 +141,28 @@ fn every_tool_creates_a_drawable_comment() {
assert_eq!(all[1].reference(b"Popup"), entries[2].as_ref());
}
+/// #260 (page 7): Acrobat draws an Ink annotation as a smooth curve through its `/InkList`
+/// points, where PdfCraft drew straight segments between them. Three or more points now make a
+/// Catmull-Rom spline through every point (as cubic Béziers); two points stay a line, one a dot.
+#[test]
+fn ink_strokes_are_smooth_curves_through_their_points() {
+ let mut doc = fixture();
+ let strokes = vec![vec![[0.0, 0.0], [10.0, 10.0], [20.0, 0.0]], vec![[30.0, 0.0], [40.0, 10.0]], vec![[50.0, 50.0]]];
+ let i = add_annotation(&mut doc, &new(0, Shape::Ink { strokes }), &meta("ink")).unwrap();
+ let ap = ap_content(&doc, &list(&doc, 0)[i]);
+ // Tangents at each point run parallel to the chord between its neighbours (the ends use
+ // their own point): (0,0)→(10,10) leaves along (10,10) and arrives along (20,0).
+ assert!(ap.contains("0 0 m\n1.667 1.667 6.667 10 10 10 c\n13.333 10 18.333 1.667 20 0 c\nS\n"), "{ap}");
+ assert!(ap.contains("30 0 m\n40 10 l\nS\n"), "{ap}");
+ assert!(ap.contains("50 50 m\n50.01 50 l\nS\n"), "{ap}");
+ // /Rect holds the whole curve: rising to (20, 20) and dropping to (21, 0), it swings above
+ // y 20 (its control point is at y 21.667), beyond the points' own bounds plus the margin.
+ let rise = Shape::Ink { strokes: vec![vec![[0.0, 0.0], [10.0, 10.0], [20.0, 20.0], [21.0, 0.0]]] };
+ let j = add_annotation(&mut doc, &new(0, rise), &meta("rise")).unwrap();
+ let top = rect(&list(&doc, 0)[j])[3];
+ assert!(top >= 21.667 + 2.0 - 0.01, "/Rect top {top}");
+}
+
#[test]
fn indirect_annots_array_is_updated_in_place() {
let mut doc = fixture();
@@ -157,7 +179,7 @@ fn invalid_geometry_is_rejected() {
let bad = [
Shape::TextMarkup { kind: Markup::Highlight, quads: vec![] },
Shape::Rectangle { rect: [0.0, 0.0, 0.5, 10.0] },
- Shape::Line { from: [1.0, 1.0], to: [1.0, 1.0], arrow: false },
+ Shape::Line { from: [1.0, 1.0], to: [1.0, 1.0], start: LineEnding::None, end: LineEnding::None },
Shape::Ink { strokes: vec![vec![]] },
Shape::Note { at: [f64::NAN, 0.0], icon: NoteIcon::Note },
];
@@ -239,7 +261,7 @@ fn move_shifts_all_geometry_and_the_popup() {
fn restyle_and_resize_redraw_the_appearance() {
let mut doc = fixture();
let r = add_annotation(&mut doc, &new(0, Shape::Rectangle { rect: [10.0, 10.0, 110.0, 60.0] }), &meta("r")).unwrap();
- set_style(&mut doc, 0, r, Some([1.0, 0.0, 0.0]), Some(0.5), Some(4.0), &meta("")).unwrap();
+ set_style(&mut doc, 0, r, Some([1.0, 0.0, 0.0]), Some(0.5), Some(4.0), None, &meta("")).unwrap();
set_rect(&mut doc, 0, r, [0.0, 0.0, 200.0, 100.0], &meta("")).unwrap();
let doc2 = reopen(&doc);
let d = &list(&doc2, 0)[r];
@@ -249,10 +271,15 @@ fn restyle_and_resize_redraw_the_appearance() {
assert_eq!(d.get(b"CA").and_then(|o| o.as_f64()), Some(0.5));
// A stamp's appearance can't be regenerated, so restyling it changes nothing.
let before = list(&doc, 1)[0].clone();
- assert_eq!(set_style(&mut doc, 1, 0, Some([0.0; 3]), None, None, &meta("")), Err(AnnotError::Unsupported("Stamp".into())));
+ assert_eq!(set_style(&mut doc, 1, 0, Some([0.0; 3]), None, None, None, &meta("")), Err(AnnotError::Unsupported("Stamp".into())));
assert_eq!(list(&doc, 1)[0], before);
// Lines can't be resized as rectangles.
- let l = add_annotation(&mut doc, &new(0, Shape::Line { from: [0.0, 0.0], to: [10.0, 10.0], arrow: false }), &meta("l")).unwrap();
+ let l = add_annotation(
+ &mut doc,
+ &new(0, Shape::Line { from: [0.0, 0.0], to: [10.0, 10.0], start: LineEnding::None, end: LineEnding::None }),
+ &meta("l"),
+ )
+ .unwrap();
assert!(matches!(set_rect(&mut doc, 0, l, [0.0, 0.0, 5.0, 5.0], &meta("")), Err(AnnotError::Invalid(_))));
}
@@ -261,7 +288,7 @@ fn text_box_text_and_colour_changes_are_drawn() {
let mut doc = fixture();
let t = add_annotation(&mut doc, &new(0, Shape::TextBox { rect: [0.0, 0.0, 300.0, 100.0], font_size: 12.0 }), &meta("t")).unwrap();
set_contents(&mut doc, 0, t, "Caf\u{e9} (draft) \u{2014} 100%", &meta("")).unwrap();
- set_style(&mut doc, 0, t, Some([1.0, 0.0, 0.0]), None, None, &meta("")).unwrap();
+ set_style(&mut doc, 0, t, Some([1.0, 0.0, 0.0]), None, None, None, &meta("")).unwrap();
let doc = reopen(&doc);
let d = &list(&doc, 0)[t];
assert_eq!(text(d, b"Contents"), "Caf\u{e9} (draft) \u{2014} 100%");
@@ -315,7 +342,16 @@ fn editing_a_callout_refits_the_box_and_keeps_the_leader() {
let mut doc = fixture();
let c = add_annotation(
&mut doc,
- &new(0, Shape::Callout { rect: [300.0, 600.0, 500.0, 612.0], knee: [260.0, 560.0], point: [200.0, 520.0], font_size: 12.0 }),
+ &new(
+ 0,
+ Shape::Callout {
+ rect: [300.0, 600.0, 500.0, 612.0],
+ knee: [260.0, 560.0],
+ point: [200.0, 520.0],
+ font_size: 12.0,
+ ending: LineEnding::OpenArrow,
+ },
+ ),
&meta("c"),
)
.unwrap();
@@ -407,8 +443,8 @@ fn fill_and_sign_items_are_drawn() {
assert_eq!(text(&all[s], b"Subj"), "Signature");
// Other stamps still can't be restyled; ours can.
let mut doc = doc;
- set_style(&mut doc, 1, marks[0], Some([0.0, 0.0, 1.0]), None, None, &meta("")).unwrap();
- assert!(set_style(&mut doc, 1, 0, Some([0.0; 3]), None, None, &meta("")).is_err());
+ set_style(&mut doc, 1, marks[0], Some([0.0, 0.0, 1.0]), None, None, None, &meta("")).unwrap();
+ assert!(set_style(&mut doc, 1, 0, Some([0.0; 3]), None, None, None, &meta("")).is_err());
}
#[test]
@@ -493,11 +529,24 @@ fn polygons_clouds_connected_lines_callouts_and_carets_are_drawn() {
let tri = vec![[100.0, 100.0], [200.0, 100.0], [150.0, 180.0]];
let i = add_annotation(&mut doc, &new(0, Shape::Polygon { vertices: tri.clone(), cloud: false }), &meta("p")).unwrap();
let c = add_annotation(&mut doc, &new(0, Shape::Polygon { vertices: tri.clone(), cloud: true }), &meta("c")).unwrap();
- let l =
- add_annotation(&mut doc, &new(0, Shape::PolyLine { vertices: vec![[300.0, 300.0], [350.0, 320.0], [400.0, 300.0]] }), &meta("l")).unwrap();
+ let l = add_annotation(
+ &mut doc,
+ &new(0, Shape::PolyLine { vertices: vec![[300.0, 300.0], [350.0, 320.0], [400.0, 300.0]], start: LineEnding::None, end: LineEnding::None }),
+ &meta("l"),
+ )
+ .unwrap();
let co = add_annotation(
&mut doc,
- &new(0, Shape::Callout { rect: [300.0, 500.0, 420.0, 540.0], knee: [260.0, 520.0], point: [220.0, 460.0], font_size: 10.0 }),
+ &new(
+ 0,
+ Shape::Callout {
+ rect: [300.0, 500.0, 420.0, 540.0],
+ knee: [260.0, 520.0],
+ point: [220.0, 460.0],
+ font_size: 10.0,
+ ending: LineEnding::OpenArrow,
+ },
+ ),
&meta("co"),
)
.unwrap();
@@ -554,7 +603,7 @@ fn polygons_clouds_connected_lines_callouts_and_carets_are_drawn() {
for bad in [
Shape::Polygon { vertices: vec![[0.0, 0.0], [10.0, 10.0]], cloud: false },
- Shape::PolyLine { vertices: vec![[0.0, 0.0]] },
+ Shape::PolyLine { vertices: vec![[0.0, 0.0]], start: LineEnding::None, end: LineEnding::None },
Shape::Caret { rect: [0.0, 0.0, 0.0, 10.0] },
] {
assert!(add_annotation(&mut doc, &new(0, bad), &meta("b")).is_err());
@@ -657,3 +706,216 @@ fn the_eraser_cuts_strokes_and_removes_empty_drawings() {
erase_ink(&mut doc, 0, i, &all[21..], 8.0, &meta("e")).unwrap();
assert!(!list(&doc, 0).iter().any(|d| d.name(b"Subtype") == Some(b"Ink")));
}
+
+/// A one-page document from object bodies (object 1 is the catalog, 3 the page).
+fn document_of(objs: &[&[u8]]) -> Document {
+ let mut out = b"%PDF-1.7\n".to_vec();
+ let mut offsets = Vec::new();
+ for (i, o) in objs.iter().enumerate() {
+ offsets.push(out.len());
+ out.extend_from_slice(format!("{} 0 obj\n", i + 1).as_bytes());
+ out.extend_from_slice(o);
+ out.extend_from_slice(b"\nendobj\n");
+ }
+ let xref = out.len();
+ out.extend_from_slice(format!("xref\n0 {}\n0000000000 65535 f \n", objs.len() + 1).as_bytes());
+ for o in offsets {
+ out.extend_from_slice(format!("{o:010} 00000 n \n").as_bytes());
+ }
+ out.extend_from_slice(format!("trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n", objs.len() + 1).as_bytes());
+ Document::open(Arc::new(out)).expect("opens")
+}
+
+#[test]
+fn comments_without_appearances_get_one_for_display_only() {
+ let doc = document_of(&[
+ b"<< /Type /Catalog /Pages 2 0 R >>",
+ b"<< /Type /Pages /Kids [3 0 R] /Count 1 /MediaBox [0 0 612 792] >>",
+ b"<< /Type /Page /Parent 2 0 R /Annots [4 0 R 5 0 R 6 0 R 7 0 R 8 0 R 9 0 R 10 0 R] >>",
+ b"<< /Type /Annot /Subtype /FreeText /Rect [48 582 285 632] /Contents (FreeText annotation with valid /DA string.) /DA (/Helv 10 Tf 0 0 1 rg) /Border [0 0 1] /C [.85 .47 .02] >>",
+ b"<< /Type /Annot /Subtype /Ink /Rect [70 392 275 472] /InkList [[80 402 120 452 160 412 210 462 260 417]] /Border [0 0 2] /C [.49 .18 .07] >>",
+ b"<< /Type /Annot /Subtype /Text /Rect [400 717 420 737] /C [1 1 0] /Contents (A note) >>",
+ b"<< /Type /Annot /Subtype /Square /Rect [10 10 50 50] /C [1 0 0] /AP << /N 11 0 R >> >>",
+ b"<< /Type /Annot /Subtype /Link /Rect [48 717 308 741] /Border [0 0 1] /C [0 0 1] >>",
+ b"<< /Type /Annot /Subtype /Widget /FT /Tx /T (f) /Rect [10 100 100 120] >>",
+ b"<< /Type /Annot /Subtype /Sound /Rect [10 200 30 220] >>",
+ b"<< /Type /XObject /Subtype /Form /BBox [10 10 50 50] /Length 0 >>\nstream\n\nendstream",
+ ]);
+ let display = with_missing_appearances(&doc).expect("three comments need an appearance");
+ let has_ap = |doc: &Document| list(doc, 0).iter().map(|d| d.get(b"AP").is_some()).collect::>();
+ assert_eq!(has_ap(&doc), [false, false, false, true, false, false, false], "the document itself is untouched");
+ assert_eq!(has_ap(&display), [true, true, true, true, false, false, false], "FreeText, Ink and Text get one; the rest don't");
+ let shown = list(&display, 0);
+ let free_text = ap_content(&display, &shown[0]);
+ assert!(free_text.contains("re f") && free_text.contains("Tj"), "background box and text: {free_text}");
+ assert_eq!(shown[3].get(b"AP"), list(&doc, 0)[3].get(b"AP"), "an existing appearance is kept");
+ // The display copy survives a save and reopen (what the renderer reads).
+ assert_eq!(has_ap(&reopen(&display)), [true, true, true, true, false, false, false]);
+ // Nothing to add: no copy.
+ let complete = document_of(&[
+ b"<< /Type /Catalog /Pages 2 0 R >>",
+ b"<< /Type /Pages /Kids [3 0 R] /Count 1 /MediaBox [0 0 612 792] >>",
+ b"<< /Type /Page /Parent 2 0 R /Annots [4 0 R 5 0 R] >>",
+ b"<< /Type /Annot /Subtype /Link /Rect [48 717 308 741] >>",
+ b"<< /Type /Annot /Subtype /Square /Rect [10 10 50 50] /C [1 0 0] /AP << /N 6 0 R >> >>",
+ b"<< /Type /XObject /Subtype /Form /BBox [10 10 50 50] /Length 0 >>\nstream\n\nendstream",
+ ]);
+ assert!(with_missing_appearances(&complete).is_none());
+}
+
+fn line_dict(coords: [f64; 4], ending: &str) -> pdfcraft_cos::Dict {
+ let mut d = pdfcraft_cos::Dict::new();
+ d.set(b"Subtype".to_vec(), Object::name("Line"));
+ d.set(b"Rect".to_vec(), Object::Array([0.0, 0.0, 300.0, 300.0].into_iter().map(Object::Real).collect()));
+ d.set(b"C".to_vec(), Object::Array([1.0, 0.0, 0.0].into_iter().map(Object::Real).collect()));
+ d.set(b"L".to_vec(), Object::Array(coords.into_iter().map(Object::Real).collect()));
+ d.set(b"LE".to_vec(), Object::Array(vec![Object::name("None"), Object::name(ending)]));
+ d
+}
+
+#[test]
+fn every_line_ending_is_drawn() {
+ let filled = [LineEnding::Square, LineEnding::Circle, LineEnding::Diamond, LineEnding::ClosedArrow, LineEnding::RClosedArrow];
+ let (mut open, mut reverse) = (String::new(), String::new());
+ for ending in LineEnding::ALL {
+ let mut doc = fixture();
+ add_annotation(
+ &mut doc,
+ &new(0, Shape::Line { from: [80.0, 100.0], to: [200.0, 160.0], start: LineEnding::None, end: ending }),
+ &meta("ending"),
+ )
+ .unwrap();
+ let doc = reopen(&doc);
+ let line = list(&doc, 0).into_iter().find(|d| d.name(b"Subtype") == Some(b"Line")).expect("line");
+ let content = ap_content(&doc, &line);
+ assert!(!content.is_empty(), "{ending:?}");
+ let paints = content.contains("h B") || content.contains("B\n");
+ assert_eq!(paints, filled.contains(&ending), "{ending:?} fill: {content}");
+ if ending != LineEnding::None {
+ let r = rect(&line);
+ assert!(r[0] < 70.0 && r[2] > 210.0, "{ending:?} rectangle includes the ending: {r:?}");
+ }
+ if ending == LineEnding::OpenArrow {
+ open = content.clone();
+ }
+ if ending == LineEnding::ROpenArrow {
+ reverse = content;
+ }
+ }
+ assert_ne!(open, reverse, "a reverse arrow points the other way");
+
+ let mut doc = fixture();
+ let index = add_annotation(
+ &mut doc,
+ &new(0, Shape::Line { from: [40.0, 40.0], to: [140.0, 40.0], start: LineEnding::None, end: LineEnding::None }),
+ &meta("plain"),
+ )
+ .unwrap();
+ let before = rect(&list(&doc, 0).into_iter().find(|d| d.name(b"Subtype") == Some(b"Line")).expect("line"));
+ set_style(&mut doc, 0, index, None, None, None, Some(&[LineEnding::None, LineEnding::Square]), &meta("style")).unwrap();
+ let mut doc = reopen(&doc);
+ let line = list(&doc, 0).into_iter().find(|d| d.name(b"Subtype") == Some(b"Line")).expect("line");
+ let after = rect(&line);
+ assert!(after[1] < before[1] - 5.0 && after[3] > before[3] + 5.0, "the square is not clipped: {before:?} → {after:?}");
+ assert!(ap_content(&doc, &line).contains("re h B"), "square ending");
+
+ add_annotation(
+ &mut doc,
+ &new(0, Shape::PolyLine { vertices: vec![[40.0, 200.0], [90.0, 260.0], [150.0, 200.0]], start: LineEnding::Circle, end: LineEnding::Slash }),
+ &meta("poly"),
+ )
+ .unwrap();
+ add_annotation(
+ &mut doc,
+ &new(
+ 0,
+ Shape::Callout {
+ rect: [300.0, 500.0, 420.0, 540.0],
+ knee: [260.0, 520.0],
+ point: [220.0, 460.0],
+ font_size: 10.0,
+ ending: LineEnding::Diamond,
+ },
+ ),
+ &meta("call"),
+ )
+ .unwrap();
+ let doc = reopen(&doc);
+ let all = list(&doc, 0);
+ let poly = all.iter().find(|d| d.name(b"Subtype") == Some(b"PolyLine")).expect("polyline");
+ let poly_ap = ap_content(&doc, poly);
+ assert!(poly_ap.contains("B\n") && poly_ap.contains(" l S"), "circle fills and the slash only strokes: {poly_ap}");
+ let call = all.iter().find(|d| d.name(b"IT") == Some(b"FreeTextCallout")).expect("callout");
+ assert_eq!(call.name(b"LE"), Some(b"Diamond".as_slice()));
+ assert!(ap_content(&doc, call).contains("h B"), "diamond callout");
+
+ assert!(appearance::build(&line_dict([f64::NAN, 0.0, 10.0, 0.0], "OpenArrow")).is_none(), "a non-finite endpoint is rejected");
+ assert!(appearance::build(&line_dict([0.0, 0.0, 10.0, 0.0], "Foo")).is_none(), "an unknown ending is not replaced");
+}
+
+#[test]
+fn redraw_keeps_shared_annotation_appearances_and_drops_stale_alternates() {
+ let alternates: [(&[u8], &[u8]); 2] = [(b"R", b"0 0 20 10 re f\n"), (b"D", b"1 1 18 8 re S\n")];
+ for indirect in [false, true] {
+ let mut doc = fixture();
+ let first = add_annotation(&mut doc, &new(0, Shape::Rectangle { rect: [10.0, 10.0, 110.0, 60.0] }), &meta("first")).unwrap();
+ let other = add_annotation(&mut doc, &new(0, Shape::Rectangle { rect: [120.0, 10.0, 220.0, 60.0] }), &meta("other")).unwrap();
+ let (_, first_ref) = annot_ref(&mut doc, 0, first).unwrap();
+ let (_, other_ref) = annot_ref(&mut doc, 0, other).unwrap();
+ let mut entries = annot_dict(&doc, first_ref).get(b"AP").unwrap().as_dict().unwrap().clone();
+ for (key, bytes) in alternates {
+ let mut d = Dict::new();
+ d.set(b"Type".to_vec(), Object::name("XObject"));
+ d.set(b"Subtype".to_vec(), Object::name("Form"));
+ d.set(b"BBox".to_vec(), num_array(&[0.0, 0.0, 20.0, 10.0]));
+ let r = doc.add(Object::Stream(pdfcraft_cos::Stream::from_raw(d, bytes.to_vec())));
+ entries.set(key.to_vec(), Object::Ref(r));
+ }
+ entries.set(b"VendorState".to_vec(), Object::name("Retained"));
+ let shared = if indirect { Object::Ref(doc.add(Object::Dict(entries))) } else { Object::Dict(entries) };
+ for r in [first_ref, other_ref] {
+ doc.update_dict(r, |d| d.set(b"AP".to_vec(), shared.clone())).unwrap();
+ }
+ let mut doc = reopen(&doc);
+ let other_dict = list(&doc, 0)[other].clone();
+ let source = other_dict.get(b"AP").unwrap();
+ let before = doc.resolve(source);
+ set_style(&mut doc, 0, first, Some([1.0, 0.0, 0.0]), None, None, None, &meta("")).unwrap();
+ assert_eq!(doc.resolve(source), before, "a shared AP must not change");
+ for full in [false, true] {
+ let bytes = if full {
+ pdfcraft_cos::write_full(&doc, &SaveOptions::default()).unwrap()
+ } else {
+ assert!(!doc.revisions().is_empty(), "incremental save needs an existing revision");
+ assert!(!doc.encryption_changed() && !doc.full_save_required(), "this edit must not require a full rewrite");
+ let original = doc.bytes();
+ let bytes = write_incremental(&doc, &SaveOptions::default()).unwrap();
+ assert!(bytes.len() > original.len(), "incremental save appends the changed appearance");
+ assert!(bytes.starts_with(original.as_slice()), "incremental save preserves the complete original prefix");
+ bytes
+ };
+ hayro_syntax::Pdf::new(bytes.clone()).unwrap();
+ let doc = Document::open(Arc::new(bytes)).unwrap();
+ let all = list(&doc, 0);
+ let first_ap = doc.resolve(all[first].get(b"AP").unwrap());
+ let other_ap = doc.resolve(all[other].get(b"AP").unwrap());
+ let first_ap = first_ap.as_dict().unwrap();
+ let other_ap = other_ap.as_dict().unwrap();
+ assert_ne!(first_ap.get(b"N"), other_ap.get(b"N"));
+ // The restyled annotation keeps unknown entries, but not down/rollover looks in its
+ // old colour.
+ assert_eq!(first_ap.len(), 2);
+ assert_eq!(other_ap.len(), 4);
+ for (key, bytes) in alternates {
+ assert!(first_ap.get(key).is_none(), "stale /{}", String::from_utf8_lossy(key));
+ let object = doc.resolve(other_ap.get(key).unwrap());
+ let Object::Stream(stream) = &*object else { panic!("alternate appearance") };
+ assert_eq!(stream.decoded().unwrap(), bytes);
+ }
+ assert_eq!(first_ap.name(b"VendorState"), Some(&b"Retained"[..]));
+ assert_eq!(other_ap.name(b"VendorState"), Some(&b"Retained"[..]));
+ assert!(ap_content(&doc, &all[first]).contains("1 0 0 RG"));
+ assert!(ap_content(&doc, &all[other]).contains("0 0.4 1 RG"));
+ }
+ }
+}
diff --git a/crates/automation/Cargo.toml b/crates/automation/Cargo.toml
index 556e9da0..3f8d63e2 100644
--- a/crates/automation/Cargo.toml
+++ b/crates/automation/Cargo.toml
@@ -12,6 +12,7 @@ workspace = true
pdfcraft-engine = { workspace = true }
pdfcraft-render = { workspace = true }
pdfcraft-organize = { workspace = true }
+pdfcraft-platform = { workspace = true }
serde_json = { workspace = true }
png = "0.18"
base64 = { version = "0.22", optional = true }
@@ -23,5 +24,7 @@ default = ["mcp"]
mcp = ["dep:base64"]
[dev-dependencies]
+pdfcraft-cos = { workspace = true }
+pdfcraft-model = { workspace = true }
pdfcraft-xfa = { workspace = true }
image = { version = "0.25", default-features = false, features = ["jpeg"] }
diff --git a/crates/automation/README.md b/crates/automation/README.md
index d1d60f07..3e220b67 100644
--- a/crates/automation/README.md
+++ b/crates/automation/README.md
@@ -23,6 +23,8 @@ mcp::McpServer::new(a).serve(stdin, stdout)? // newline-delimited JS
- Pages and positions are **1-based**. Rectangles are PDF points with the origin at the top-left of the displayed page.
- Unknown arguments are rejected, so typos fail loudly.
- Tools that change a document return its summary (`doc`, `pages`, `dirty`, `undo`, `redo`, …).
+- `comment_image_preview` returns JSON and a PNG: `layer: "background"` (the default) gives the page without the selected image signature/initials; `layer: "image"` gives its embedded image with alpha. The metadata supplies its displayed rectangle, document rotation, `image_rotation` (how far clockwise the image is shown turned: 0 for one placed by PdfCraft, which keeps it upright as displayed) and annotation opacity. Each result can be saved with the CLI's `--out`. Cache the background and transform the image for live movement/resizing; `comment_edit` commits the final geometry in one undo step. Previewing never changes the document.
+- For proportional image signature resizing, use the embedded image layer's width/height ratio rather than a previously stretched annotation rectangle. The GUI preserves this ratio at corners with the opposite corner anchored; edge midpoint handles change only their own axis. `comment_edit` accepts the resulting rectangle.
- `doc_close` refuses to drop unsaved changes unless `discard_changes: true`. `doc_save` writes atomically, incrementally in place, and in full for a new path.
- With a root set, every read and write path must resolve inside it (symlinks and `..` included). Relative paths resolve inside the root, and `..` is resolved by name before the check. Every path outside the root gets the same refusal (` is outside the allowed directory `), whether or not it exists, so a confined agent can't probe the rest of the disk; on Windows another network share or device path (`\\host\share`, `\\?\UNC\…`, `\\.\…`) is refused without being contacted. "Not found" and other filesystem errors are reported only for paths inside the root. Tools that write several files into a folder name them after the document or input file, with separators, colons and control characters replaced by `_`, so a name can't lead them out of the folder. The root itself must be a folder.
@@ -30,6 +32,8 @@ mcp::McpServer::new(a).serve(stdin, stdout)? // newline-delimited JS
**Opt-in only.** Nothing starts it automatically, and it opens no port. It runs while `pdfcraft-cli mcp [--root DIR]` runs, normally launched by an agent from its MCP configuration. It stops when stdin closes. The CLI's `mcp` Cargo feature (on by default) compiles it out entirely when disabled.
+`pdfcraft-cli mcp --compact` (or `McpServer::with_compact(true)`) keeps `tools/list` short for agents with small context budgets. It lists only the core tools (`mcp::COMPACT_CORE_TOOLS`: open, info, save, close, render, text extract and find, combine, split, undo) plus the common command/inspection/preview tools and two meta tools: `tool_search` (optional `query` and `category`, the name prefix; or `name` for one tool's full `input_schema`) and `tool_call` (`name` and `arguments`, run through the same `Automation::call`). `tools/call` by name keeps working for every tool, and the server instructions mention the meta tools. Without the flag nothing changes.
+
Implemented: `initialize` (protocol 2025-06-18, 2025-03-26, 2024-11-05), `ping`, `tools/list` (with `readOnlyHint`/`destructiveHint` annotations), `tools/call` (JSON results also returned as `structuredContent`; images as `image/png`), and `resources/list`, `resources/templates/list` and `resources/read`. The resources expose the open documents read-only: `pdfcraft://doc/{doc}/info` (JSON), `…/text`, `…/page/{page}/text` and `…/page/{page}/image{?dpi}` (PNG, 1–600 dpi). Tool failures come back as `isError: true` results, so the agent can read and recover from them.
## Adding a tool
@@ -38,3 +42,29 @@ Implemented: `initialize` (protocol 2025-06-18, 2025-03-26, 2024-11-05), `ping`,
2. Add a `ToolDef` in `src/tools.rs`: a precise description, the schema, `ro()`/`destructive()`, and `cmd()` if a registry command exists.
3. Handle it in `Automation::call`, validating pages and positions with the existing helpers.
4. Add an end-to-end test in `tests/automation.rs`. `tool_table_is_well_formed` checks names, schemas and command links.
+
+
+## Common command tools
+
+Following FilmCraft's MCP conventions, `command_list {doc?, filter?, enabled_only?}` keeps its
+`{commands: [...]}` result and adds each mapped tool's parameter schema. `command_run {id, params?}`
+runs that command through its existing headless tool: include `doc` and other tool arguments in
+`params`. Commands without a headless mapping return a tool error. Unknown parameter keys are
+ignored with a `warnings` array; required values and paths still go through the original validation.
+
+`command_batch {steps: [{id, params?}], stop_on_error?}` returns `completed`, `failed`, and per-step
+`{ok, result?, error?}` entries. The default is to stop at the first error; earlier edits remain.
+MCP marks a batch with any failed steps as `isError`, including through compact `tool_call`.
+`doc_inspect {doc?}` returns one document's info, or `{documents: [...]}` for all open documents.
+`render_preview {doc?, page?, max_side?}` returns a PNG (page defaults to 1, maximum side defaults
+to 1024, allowed 1–4096). Omit `doc` only when exactly one document is open.
+
+All task tools remain available; compact mode includes the five common tools. Every MCP tool has
+all four annotation hints. Unknown top-level argument keys return JSON-RPC `-32602` with the
+accepted keys; failures in the invoked tool remain `isError` results. An escaped tool panic is
+reported as an internal tool error, and the server continues serving.
+
+Exports complete synchronously. `progressToken` and cancellation notifications are harmlessly
+ignored; no background-job or cancellation behavior is added.
+
+Session resources `pdfcraft://document` and `pdfcraft://commands`, and the refusal of unknown argument keys, are described in [docs/mcp.md](../../docs/mcp.md).
diff --git a/crates/automation/src/comments.rs b/crates/automation/src/comments.rs
index 7b09e4d4..ebeab262 100644
--- a/crates/automation/src/comments.rs
+++ b/crates/automation/src/comments.rs
@@ -3,11 +3,13 @@
//! Geometry follows the automation convention: points from the top-left of the displayed page,
//! y down. It is converted to PDF user space (crop box, `/Rotate`) here.
-use pdfcraft_engine::{Edit, Markup, NOTE_SIZE, NewAnnotation, NoteIcon, ReviewState, Rgb, Shape, StampGroup, StampKind, Style, SummarySort};
+use pdfcraft_engine::{
+ Edit, LineEnding, Markup, NOTE_SIZE, NewAnnotation, NoteIcon, ReviewState, Rgb, Shape, StampGroup, StampKind, Style, SummarySort,
+};
use pdfcraft_render::{Annotation, PageInfo};
use serde_json::{Value, json};
-use crate::{Args, Automation, Result, ToolError, failed};
+use crate::{Args, Automation, Content, DEFAULT_DPI, MAX_DPI, Result, ToolError, encode_png, failed};
/// Author used when a tool call names none.
pub(crate) const DEFAULT_AUTHOR: &str = "PdfCraft";
@@ -34,6 +36,33 @@ pub(crate) fn parse_color(s: &str) -> Result {
Ok([c(0), c(2), c(4)])
}
+const ENDING_NAMES: &str = "None, Square, Circle, Diamond, OpenArrow, ClosedArrow, Butt, ROpenArrow, RClosedArrow, Slash";
+
+fn line_endings(a: &Args) -> Result>> {
+ let Some(v) = a.get("endings") else { return Ok(None) };
+ let arr = v.as_array().ok_or_else(|| ToolError::InvalidArgs("endings must be an array of line-ending names".into()))?;
+ if arr.is_empty() || arr.len() > 2 {
+ return Err(ToolError::InvalidArgs("endings takes one name for a callout, or two for a line or polyline".into()));
+ }
+ arr.iter()
+ .map(|item| {
+ let name = item.as_str().ok_or_else(|| ToolError::InvalidArgs("endings must be line-ending names".into()))?;
+ LineEnding::parse(name).ok_or_else(|| ToolError::InvalidArgs(format!("unknown line ending {name:?} ({ENDING_NAMES})")))
+ })
+ .collect::>>()
+ .map(Some)
+}
+
+/// `[start, end]` for a line, arrow or polyline. An arrow with no `endings` stays `[None, OpenArrow]`.
+fn ending_pair(kind: &str, endings: Option<&[LineEnding]>) -> Result<[LineEnding; 2]> {
+ match endings {
+ None if kind == "arrow" => Ok([LineEnding::None, LineEnding::OpenArrow]),
+ None => Ok([LineEnding::None, LineEnding::None]),
+ Some(v) if v.len() == 2 => Ok([v.first().copied().unwrap_or(LineEnding::None), v.get(1).copied().unwrap_or(LineEnding::None)]),
+ Some(_) => Err(ToolError::InvalidArgs("a line or polyline needs two endings, the start and the end".into())),
+ }
+}
+
fn hex(c: [f32; 3]) -> String {
let b = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u8;
format!("#{:02X}{:02X}{:02X}", b(c[0]), b(c[1]), b(c[2]))
@@ -86,6 +115,35 @@ impl Args<'_> {
}
impl Automation {
+ /// One of the read-only layers the GUI uses to drag/resize an embedded image signature.
+ pub(crate) fn comment_image_preview(&self, a: &Args) -> Result> {
+ let (page, index) = self.comment_target(a)?;
+ let dpi = a.opt_num("dpi")?.unwrap_or(DEFAULT_DPI);
+ if !(1.0..=MAX_DPI).contains(&dpi) {
+ return Err(ToolError::InvalidArgs(format!("dpi must be between 1 and {MAX_DPI}")));
+ }
+ let doc = self.doc(a)?;
+ let preview = doc.image_signature_preview(page, index).map_err(failed)?.ok_or_else(|| failed("choose an image signature or initials"))?;
+ let annotation = doc.info.annotations.iter().find(|c| c.page == page && c.index == index).ok_or_else(|| failed("no such comment"))?;
+ let info = doc.info.pages.get(page).ok_or_else(|| failed("no such page"))?;
+ let [w, h] = preview.image.size();
+ let layer = a.opt_str("layer")?.unwrap_or("background");
+ let image = match layer {
+ "image" => Content::Png { data: preview.image.bytes().as_ref().clone(), width: w as u32, height: h as u32 },
+ "background" => {
+ let out = preview.render_background((dpi / 72.0) as f32).map_err(failed)?;
+ Content::Png { data: encode_png(out.width, out.height, &out.rgba)?, width: out.width, height: out.height }
+ }
+ _ => return Err(ToolError::InvalidArgs("layer must be background or image".into())),
+ };
+ Ok(vec![
+ Content::Json(json!({ "page": page + 1, "index": index + 1, "rect": rect_to_view(info, annotation.rect), "rotation": info.rotation,
+ "image_rotation": (i64::from(info.rotation) - preview.turn).rem_euclid(360),
+ "layer": layer, "opacity": preview.opacity, "dpi": dpi })),
+ image,
+ ])
+ }
+
/// Comments of a document, optionally only of one 0-based page.
fn comments(&self, a: &Args) -> Result> {
let doc = self.doc(a)?;
@@ -152,6 +210,10 @@ impl Automation {
let page = self.page(a)?;
let info = self.doc(a)?.info.pages[page].clone();
let kind = a.str("type")?;
+ let endings = line_endings(a)?;
+ if endings.is_some() && !matches!(kind, "line" | "arrow" | "polyline" | "callout") {
+ return Err(ToolError::InvalidArgs("endings apply to a line, arrow, polyline or callout".into()));
+ }
let markup = match kind {
"highlight" => Some(Markup::Highlight),
"underline" => Some(Markup::Underline),
@@ -225,7 +287,8 @@ impl Automation {
}
"line" | "arrow" => {
let (f, t) = (a.need::<2>("from", "a line")?, a.need::<2>("to", "a line")?);
- Shape::Line { from: to_user(&info, f[0], f[1]), to: to_user(&info, t[0], t[1]), arrow: kind == "arrow" }
+ let [start, end] = ending_pair(kind, endings.as_deref())?;
+ Shape::Line { from: to_user(&info, f[0], f[1]), to: to_user(&info, t[0], t[1]), start, end }
}
"ink" => {
let wrong = || ToolError::InvalidArgs("strokes must be an array of arrays of [x, y] points".into());
@@ -258,7 +321,10 @@ impl Automation {
})
.collect::>>()?;
match kind {
- "polyline" => Shape::PolyLine { vertices },
+ "polyline" => {
+ let [start, end] = ending_pair(kind, endings.as_deref())?;
+ Shape::PolyLine { vertices, start, end }
+ }
_ => Shape::Polygon { vertices, cloud: kind == "cloud" },
}
}
@@ -281,7 +347,17 @@ impl Automation {
[(point[0] + side) / 2.0, mid]
}
};
- Shape::Callout { rect, knee, point, font_size: a.opt_num("font_size")?.unwrap_or(10.0) }
+ Shape::Callout {
+ rect,
+ knee,
+ point,
+ font_size: a.opt_num("font_size")?.unwrap_or(10.0),
+ ending: match endings.as_deref() {
+ None => LineEnding::OpenArrow,
+ Some([ending]) => *ending,
+ Some(_) => return Err(ToolError::InvalidArgs("a callout needs one ending".into())),
+ },
+ }
}
"attachment" => {
let [x, y] = a.need::<2>("at", "an attachment (its icon's top-left)")?;
@@ -350,13 +426,24 @@ impl Automation {
let [x, y] = a.need::<2>("at", "Fill & Sign")?;
let at = to_user(&info, x, y);
let author = a.opt_str("author")?.unwrap_or(DEFAULT_AUTHOR).to_string();
+ let kind = a.str("type")?;
+ if let Some(path) = a.opt_str("path")? {
+ if !matches!(kind, "signature" | "initials") || a.opt_str("text")?.is_some() {
+ return Err(ToolError::InvalidArgs("path is only for an image signature or initials; pass either path or text".into()));
+ }
+ let path = self.resolve(path, false)?;
+ let file = std::fs::File::open(&path).map_err(|e| failed(format!("{}: {e}", path.display())))?;
+ let image = pdfcraft_engine::SignatureImage::read(file).map_err(|e| ToolError::InvalidArgs(e.to_string()))?;
+ let edit = image.edit(page, &info, at, kind == "initials", &author).ok_or_else(|| ToolError::InvalidArgs("at must be finite".into()))?;
+ return self.apply(a, edit);
+ }
let size = 10.0;
let text_at = |t: &str| {
let w = (pdfcraft_engine::annot_text::text_width(t, size) + 8.0).clamp(20.0, 600.0);
let h = size * 1.2 + 6.0;
Shape::Typewriter { rect: [at[0], at[1] - h, at[0] + w, at[1]], font_size: size }
};
- let (shape, contents) = match a.str("type")? {
+ let (shape, contents) = match kind {
"text" => {
let t = a.str("text")?.to_string();
(text_at(&t), t)
@@ -366,12 +453,12 @@ impl Automation {
let t = format!("{m}/{d}/{yy}");
(text_at(&t), t)
}
- // A typed signature or initials in the script font, left edge at `at`.
+ // A typed signature or initials in the script font, left edge at `at`, upright as displayed.
kind @ ("signature" | "initials") => {
let t = a.str("text")?;
let h = if kind == "initials" { 24.0 } else { 32.0 };
- let shape =
- pdfcraft_engine::typed_signature_shape(at, t, h).ok_or_else(|| ToolError::InvalidArgs("text has nothing to draw".into()))?;
+ let shape = pdfcraft_engine::typed_signature_shape(at, t, h, i64::from(info.rotation))
+ .ok_or_else(|| ToolError::InvalidArgs("text has nothing to draw".into()))?;
(shape, String::new())
}
kind => {
@@ -444,7 +531,7 @@ impl Automation {
}
let (color, opacity, width) = (a.color("color")?, a.opt_num("opacity")?, a.opt_num("width")?);
if color.is_some() || opacity.is_some() || width.is_some() {
- edits.push(Edit::StyleAnnotation { page, index, color, opacity, width });
+ edits.push(Edit::StyleAnnotation { page, index, color, opacity, width, endings: None });
}
if let Some(r) = a.nums::<4>("rect")? {
edits.push(Edit::ResizeAnnotation { page, index, rect: rect_to_user(&info, r) });
diff --git a/crates/automation/src/conventions.rs b/crates/automation/src/conventions.rs
new file mode 100644
index 00000000..62153082
--- /dev/null
+++ b/crates/automation/src/conventions.rs
@@ -0,0 +1,124 @@
+//! Shared command/inspection/preview entry points, using the existing confined tool path.
+use serde_json::{Value, json};
+
+use crate::{Args, Automation, Content, Result, ToolError, encode_png, failed, info, tools};
+use pdfcraft_render::{RenderRequest, RequestKind};
+
+/// The most steps one `command_batch` runs.
+pub(crate) const MAX_BATCH_STEPS: usize = 1000;
+
+impl Automation {
+ pub(crate) fn command_run(&mut self, args: &Args) -> Result> {
+ let id = args.str("id")?;
+ let tool = tools::tool_for_command(id).ok_or_else(|| failed(format!("command {id:?} has no headless tool; see command_list")))?;
+ let def = tools::find(tool).ok_or_else(|| failed("command tool is unavailable"))?;
+ let mut params = match args.get("params") {
+ None | Some(Value::Null) => serde_json::Map::new(),
+ Some(Value::Object(params)) => params.clone(),
+ Some(_) => return Err(ToolError::InvalidArgs("params must be an object".into())),
+ };
+ let props = def.input_schema.get("properties").and_then(Value::as_object).ok_or_else(|| failed("tool has no parameter schema"))?;
+ let accepted = props.keys().map(String::as_str).collect::>().join(", ");
+ let mut warnings = Vec::new();
+ params.retain(|key, _| {
+ if props.contains_key(key) {
+ return true;
+ }
+ warnings.push(format!("unknown param {key:?} for {id} (accepted: {accepted})"));
+ false
+ });
+ // This preserves the task tool's validation, atomic writes and --root confinement.
+ let mut content = self.call(tool, &Value::Object(params))?;
+ if !warnings.is_empty() {
+ if let Some(object) = content.iter_mut().find_map(|c| match c {
+ Content::Json(v) => v.as_object_mut(),
+ _ => None,
+ }) {
+ let mut all = match object.remove("warnings") {
+ Some(Value::Array(old)) => old,
+ Some(old) => vec![old],
+ None => Vec::new(),
+ };
+ all.extend(warnings.into_iter().map(Value::String));
+ object.insert("warnings".into(), Value::Array(all));
+ } else {
+ content.push(Content::Json(json!({"warnings":warnings})));
+ }
+ }
+ Ok(content)
+ }
+
+ pub(crate) fn command_batch(&mut self, args: &Args) -> Result {
+ let steps = args.get("steps").and_then(Value::as_array).ok_or_else(|| ToolError::InvalidArgs("steps must be an array".into()))?;
+ if steps.len() > MAX_BATCH_STEPS {
+ return Err(ToolError::InvalidArgs(format!("a batch has at most {MAX_BATCH_STEPS} steps ({} given); split it", steps.len())));
+ }
+ // Check every envelope before applying any edit.
+ for step in steps {
+ let a = Args(step);
+ a.str("id")?;
+ if a.get("params").is_some_and(|p| !p.is_object() && !p.is_null()) {
+ return Err(ToolError::InvalidArgs("step params must be an object".into()));
+ }
+ }
+ let stop = args.opt_bool("stop_on_error")?.unwrap_or(true);
+ let (mut completed, mut failed, mut results) = (0usize, 0usize, Vec::new());
+ for step in steps {
+ match self.command_run(&Args(step)) {
+ Ok(content) => {
+ completed += 1;
+ let result = content.into_iter().find_map(|c| match c {
+ Content::Json(v) => Some(v),
+ _ => None,
+ });
+ results.push(json!({"ok":true,"result":result}));
+ }
+ Err(e) => {
+ failed += 1;
+ results.push(json!({"ok":false,"error":e.to_string()}));
+ if stop {
+ break;
+ }
+ }
+ }
+ }
+ Ok(json!({"completed":completed,"failed":failed,"results":results}))
+ }
+
+ pub(crate) fn doc_inspect(&self, args: &Args) -> Result {
+ if args.opt_int("doc")?.is_some() {
+ return Ok(info(self.doc(args)?));
+ }
+ Ok(json!({"documents":self.session.docs().iter().map(info).collect::>()}))
+ }
+
+ pub(crate) fn render_preview(&mut self, args: &Args) -> Result {
+ let id = if args.opt_int("doc")?.is_some() {
+ self.doc(args)?.id
+ } else {
+ match self.session.docs() {
+ [doc] => doc.id,
+ _ => return Err(failed("give doc from doc_list (a single open document is selected automatically)")),
+ }
+ };
+ let page = args.opt_int("page")?.unwrap_or(1);
+ let max = args.opt_int("max_side")?.unwrap_or(1024);
+ if !(1..=4096).contains(&max) {
+ return Err(ToolError::InvalidArgs("max_side must be between 1 and 4096".into()));
+ }
+ let page = usize::try_from(page).ok().and_then(|p| p.checked_sub(1)).ok_or_else(|| failed("page must be at least 1"))?;
+ let doc = self.session.get(id).ok_or_else(|| failed("no such document"))?;
+ let size = doc.info.pages.get(page).ok_or_else(|| failed("page is out of range"))?;
+ let side = size.width.max(size.height);
+ if !side.is_finite() || side <= 0.0 {
+ return Err(failed("page has invalid dimensions"));
+ }
+ let scale = (max as f32 / side).min(1.0);
+ let out = self.renderer(id)?.render(RenderRequest { page, kind: RequestKind::Pixels, tile: None, scale, tag: 0 });
+ if let Some(error) = out.error {
+ return Err(failed(error));
+ }
+ let data = encode_png(out.width, out.height, &out.rgba)?;
+ Ok(Content::Png { data, width: out.width, height: out.height })
+ }
+}
diff --git a/crates/automation/src/forms.rs b/crates/automation/src/forms.rs
index 0203934b..eb3f1b38 100644
--- a/crates/automation/src/forms.rs
+++ b/crates/automation/src/forms.rs
@@ -189,10 +189,12 @@ impl Automation {
"value": match f.kind {
FormFieldKind::CheckBox => json!(!f.value.is_empty()),
FormFieldKind::List if f.has(field_flags::MULTI_SELECT) => json!(f.value),
+ FormFieldKind::Radio => json!(f.value.first().map(|v| f.export_for_state(v))),
_ => json!(f.value.first()),
},
"page": w.and_then(|w| w.page).map(|p| p + 1),
"rect": rect,
+ "rotation": w.map(|w| w.rotation).unwrap_or(0),
"read_only": f.read_only(),
"required": f.has(field_flags::REQUIRED),
});
@@ -225,7 +227,7 @@ impl Automation {
}
match f.kind {
FormFieldKind::Radio => {
- o.insert("options".into(), json!(f.widgets.iter().filter_map(|w| w.on_state.clone()).collect::>()));
+ o.insert("options".into(), json!((0..f.widgets.len()).filter_map(|i| f.export_of(i)).collect::>()));
}
FormFieldKind::Combo | FormFieldKind::List => {
o.insert("options".into(), f.options.iter().map(|(e, d)| json!({ "value": e, "label": d })).collect());
@@ -393,6 +395,11 @@ impl Automation {
out
}
},
+ rotation: match a.opt_int("rotation")? {
+ None => None,
+ Some(r @ (0 | 90 | 180 | 270)) => Some((0, r)),
+ Some(r) => return Err(ToolError::InvalidArgs(format!("rotation must be 0, 90, 180 or 270, not {r}"))),
+ },
actions: None,
check_style: match a.opt_str("check_style")? {
None => None,
diff --git a/crates/automation/src/lib.rs b/crates/automation/src/lib.rs
index 1e199d2c..684eebd2 100644
--- a/crates/automation/src/lib.rs
+++ b/crates/automation/src/lib.rs
@@ -14,6 +14,7 @@
mod a11y;
mod comments;
mod content;
+mod conventions;
mod forms;
mod links;
#[cfg(feature = "mcp")]
@@ -29,6 +30,7 @@ use std::path::{Path, PathBuf};
use std::sync::Arc;
use pdfcraft_engine::{DocId, Document, Edit, Session, commands};
+use pdfcraft_platform::staging::{StagingName, create_staging, staging_suffixes};
use pdfcraft_render::{PageRenderer, PageText, RenderConfig, RenderRequest, RequestKind};
use serde_json::{Value, json};
@@ -154,6 +156,7 @@ impl Automation {
self.apply(&a, edit)?
}
"page_render" => return self.page_render(&a).map(|c| vec![c]),
+ "comment_image_preview" => return self.comment_image_preview(&a),
"text_extract" => self.text_extract(&a)?,
"text_find" => self.text_find(&a)?,
"page_rotate" => {
@@ -200,6 +203,7 @@ impl Automation {
"page_insert_file" => self.insert_file(&a)?,
"page_extract" => self.page_extract(&a)?,
"doc_combine" => self.doc_combine(&a)?,
+ "doc_create_multiple" => self.doc_create_multiple(&a)?,
"doc_split" => self.doc_split(&a)?,
"edit_undo" => {
let id = self.doc(&a)?.id;
@@ -212,6 +216,10 @@ impl Automation {
json!({ "redone": label, "document": summary(self.doc(&a)?) })
}
"command_list" => self.command_list(&a)?,
+ "command_run" => return self.command_run(&a),
+ "command_batch" => self.command_batch(&a)?,
+ "doc_inspect" => self.doc_inspect(&a)?,
+ "render_preview" => return self.render_preview(&a).map(|c| vec![c]),
"page_number" => {
use pdfcraft_organize::LabelStyle as L;
let n = self.doc(&a)?.info.pages.len();
@@ -329,7 +337,7 @@ impl Automation {
.enumerate()
.map(|(i, im)| {
let (u, v) = (info.user_to_view(im.rect[0] as f32, im.rect[1] as f32), info.user_to_view(im.rect[2] as f32, im.rect[3] as f32));
- json!({ "image": i + 1, "rect": [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))], "pixels": [im.width, im.height], "name": im.name })
+ json!({ "image": i + 1, "rect": [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))], "pixels": [im.width, im.height], "name": im.name, "kind": if im.is_form { "form" } else { "image" } })
})
.collect();
json!({ "page": page + 1, "count": list.len(), "images": list })
@@ -417,6 +425,7 @@ impl Automation {
let block = self.doc(&a)?.text_blocks(page)[k as usize - 1].clone();
let text = a.opt_str("text")?.map(str::to_owned).unwrap_or(block.text);
let mut style = pdfcraft_engine::BlockStyle {
+ bold: a.opt_bool("bold")?,
size: a.opt_num("size")?,
underline: a.opt_bool("underline")?,
line_spacing: a.opt_num("line_spacing")?,
@@ -1140,6 +1149,63 @@ impl Automation {
Ok(result)
}
+ fn doc_create_multiple(&mut self, a: &Args) -> Result {
+ let paths = a.strs("paths")?;
+ if paths.is_empty() || paths.len() > pdfcraft_engine::MAX_CREATE_FILES {
+ return Err(ToolError::InvalidArgs(format!("paths must list 1 to {} files", pdfcraft_engine::MAX_CREATE_FILES)));
+ }
+ let separate = match a.opt_str("mode")? {
+ None | Some("combine") => false,
+ Some("separate") => true,
+ Some(m) => return Err(ToolError::InvalidArgs(format!("mode must be \"combine\" or \"separate\", not {m:?}"))),
+ };
+ if separate {
+ return self.create_separate(a, &paths);
+ }
+ let ranges: Vec> = match a.get("pages") {
+ None | Some(Value::Null) => vec![None; paths.len()],
+ Some(Value::Array(v)) if v.len() == paths.len() => v.iter().map(|x| x.as_str().map(str::to_owned)).collect(),
+ Some(_) => return Err(ToolError::InvalidArgs("pages must list a range (or null) for each path".into())),
+ };
+ let mut sources = Vec::new();
+ for (p, range) in paths.into_iter().zip(ranges) {
+ let path = self.resolve(p, false)?;
+ let bytes = std::fs::read(&path).map_err(|e| failed(format!("{}: {e}", path.display())))?;
+ let name = path.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
+ let (_, pdf) = self.session.convert_to_pdf(&name, &Arc::new(bytes)).map_err(failed)?;
+ let title = path.file_stem().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
+ sources.push((title, pdf, range));
+ }
+ let bytes = self.session.combine_ranges(&sources).map_err(failed)?;
+ self.deliver(a, "Combined", bytes)
+ }
+
+ /// One PDF per file, written into `out_dir`; a file that fails doesn't stop the others.
+ fn create_separate(&mut self, a: &Args, paths: &[&str]) -> Result {
+ let dir = self.resolve(a.str("out_dir").map_err(|_| ToolError::InvalidArgs("mode \"separate\" needs out_dir".into()))?, true)?;
+ std::fs::create_dir_all(&dir).map_err(|e| failed(format!("{}: {e}", dir.display())))?;
+ let mut out = Vec::new();
+ for &p in paths {
+ let converted = self.resolve(p, false).map_err(|e| e.to_string()).and_then(|src| {
+ let bytes = std::fs::read(&src).map_err(|e| format!("{}: {e}", src.display()))?;
+ let name = src.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
+ let stem = src.file_stem().map(|n| n.to_string_lossy().into_owned()).unwrap_or_else(|| "document".into());
+ let (kind, pdf) = self.session.convert_to_pdf(&name, &Arc::new(bytes)).map_err(|e| e.to_string())?;
+ Ok((kind, stem, pdf))
+ });
+ out.push(match converted {
+ Ok((pdfcraft_engine::SourceKind::Pdf, ..)) => json!({ "path": p, "skipped": "already a PDF" }),
+ Ok((_, stem, pdf)) => {
+ let target = unused(&dir, &stem);
+ write_atomic(&target, &pdf)?;
+ json!({ "path": p, "output": target.to_string_lossy(), "bytes": pdf.len() })
+ }
+ Err(e) => json!({ "path": p, "error": e }),
+ });
+ }
+ Ok(json!({ "files": out }))
+ }
+
fn page_extract(&mut self, a: &Args) -> Result {
let doc = self.doc(a)?;
let (id, name) = (doc.id, format!("{} (extract)", doc.name));
@@ -1175,9 +1241,24 @@ impl Automation {
}
let ranges: Vec> = match a.get("pages") {
None | Some(Value::Null) => vec![None; paths.len()],
- Some(Value::Array(v)) if v.len() == paths.len() => v.iter().map(|x| x.as_str().map(str::to_owned)).collect(),
+ Some(Value::Array(v)) if v.len() == paths.len() => v
+ .iter()
+ .enumerate()
+ .map(|(index, value)| match value {
+ Value::Null => Ok(None),
+ Value::String(range) => Ok(Some(range.clone())),
+ _ => Err(ToolError::InvalidArgs(format!("pages[{index}] must be a range string or null"))),
+ })
+ .collect::>()?,
Some(_) => return Err(ToolError::InvalidArgs("pages must list a range (or null) for each path".into())),
};
+ let passwords: Vec> = match a.get("passwords") {
+ None | Some(Value::Null) => vec![None; paths.len()],
+ Some(Value::Array(v)) if v.len() == paths.len() && v.iter().all(|x| x.is_string() || x.is_null()) => {
+ v.iter().map(|x| x.as_str().map(str::to_owned)).collect()
+ }
+ Some(_) => return Err(ToolError::InvalidArgs("passwords must list a password (or null) for each path".into())),
+ };
let mut sources = Vec::new();
for (p, range) in paths.into_iter().zip(ranges) {
let path = self.resolve(p, false)?;
@@ -1185,7 +1266,8 @@ impl Automation {
let name = path.file_stem().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
sources.push((name, Arc::new(bytes), range));
}
- let bytes = self.session.combine_ranges(&sources).map_err(failed)?;
+ let passwords: Vec> = passwords.iter().map(Option::as_deref).collect();
+ let bytes = self.session.combine_unlocked(&sources, &passwords).map_err(failed)?;
self.deliver(a, "Combined", bytes)
}
@@ -1267,10 +1349,10 @@ impl Automation {
let doc = self.session.get(id).ok_or_else(|| failed("no such document"))?;
let fresh = || {
let config = RenderConfig { password: doc.password.as_deref().map(Arc::from), ..Default::default() };
- (doc.bytes.clone(), PageRenderer::new(doc.bytes.clone(), config))
+ (doc.display.clone(), PageRenderer::new(doc.display.clone(), config))
};
let entry = self.renderers.entry(id).or_insert_with(fresh);
- if !Arc::ptr_eq(&entry.0, &doc.bytes) {
+ if !Arc::ptr_eq(&entry.0, &doc.display) {
*entry = fresh();
}
Ok(&mut entry.1)
@@ -1356,6 +1438,8 @@ impl Automation {
Some(_) => Some(self.doc(a)?.id),
None => None,
};
+ let filter = a.opt_str("filter")?.unwrap_or("").to_lowercase();
+ let enabled_only = a.opt_bool("enabled_only")?.unwrap_or(false);
let list: Vec = commands::COMMANDS
.iter()
.map(|c| {
@@ -1366,9 +1450,18 @@ impl Automation {
"shortcut": c.shortcut.map(|s| s.label(cfg!(target_os = "macos"))),
"enabled": commands::is_enabled(c, &self.session, active),
"tool": tools::tool_for_command(c.id),
+ "params": tools::tool_for_command(c.id).and_then(tools::find).map(|t| &t.input_schema),
})
})
.collect();
+ let list: Vec = list
+ .into_iter()
+ .filter(|c| {
+ (!enabled_only || c.get("enabled").and_then(Value::as_bool) == Some(true))
+ && (filter.is_empty()
+ || ["id", "label", "menu"].iter().any(|k| c.get(k).is_some_and(|v| v.to_string().to_lowercase().contains(&filter))))
+ })
+ .collect();
Ok(json!({ "commands": list }))
}
@@ -1613,7 +1706,7 @@ fn info(d: &Document) -> Value {
"links": i.links.iter().map(|l| json!({
"page": page1(l.page), "rect": view_rect(i, l.page, l.rect),
"target": match &l.target {
- pdfcraft_render::LinkTarget::Page(p) => json!({ "page": page1(*p) }),
+ pdfcraft_render::LinkTarget::Page(p, _) => json!({ "page": page1(*p) }),
pdfcraft_render::LinkTarget::Uri(u) => json!({ "uri": u }),
pdfcraft_render::LinkTarget::SetLayers { changes, preserve_rb } => json!({
"layers": changes.iter().map(|(op, ocg)| json!({
@@ -1718,8 +1811,23 @@ fn child(dir: &Path, name: &str) -> PathBuf {
dir.join(safe)
}
+/// `.pdf` in `dir`, or ` (2).pdf` and so on when that name is taken.
+fn unused(dir: &Path, stem: &str) -> PathBuf {
+ let first = child(dir, &format!("{stem}.pdf"));
+ if !first.exists() {
+ return first;
+ }
+ (2..10_000u32).map(|n| child(dir, &format!("{stem} ({n}).pdf"))).find(|p| !p.exists()).unwrap_or(first)
+}
+
/// Write via a temporary file in the same directory, then rename over the target.
fn write_atomic(path: &Path, bytes: &[u8]) -> Result<()> {
+ write_atomic_with(path, bytes, staging_suffixes())
+}
+
+/// [`write_atomic`], trying the staging names that `suffixes` give.
+fn write_atomic_with(path: &Path, bytes: &[u8], suffixes: impl IntoIterator- ) -> Result<()> {
+ use std::io::Write;
// A folder can't be replaced, and staging beside it could land outside the root: "." names
// the root itself, whose parent isn't ours to write in.
if path.is_dir() {
@@ -1728,8 +1836,17 @@ fn write_atomic(path: &Path, bytes: &[u8]) -> Result<()> {
let dir = path.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or(Path::new("."));
let name = path.file_name().ok_or_else(|| failed(format!("{}: not a file path", path.display())))?;
std::fs::create_dir_all(dir).map_err(|e| failed(format!("{}: {e}", dir.display())))?;
- let tmp = dir.join(format!(".{}.pdfcraft-tmp", name.to_string_lossy()));
- std::fs::write(&tmp, bytes).map_err(|e| failed(format!("{}: {e}", tmp.display())))?;
+ let (tmp, file) =
+ create_staging(dir, &name.to_string_lossy(), StagingName::SuffixThenTag, suffixes).map_err(|e| failed(format!("{}: {e}", dir.display())))?;
+ // Closed at the end of the block, before the rename.
+ let written = {
+ let mut file = file;
+ file.write_all(bytes)
+ };
+ if let Err(e) = written {
+ let _ = std::fs::remove_file(&tmp);
+ return Err(failed(format!("{}: {e}", tmp.display())));
+ }
std::fs::rename(&tmp, path).map_err(|e| {
let _ = std::fs::remove_file(&tmp);
failed(format!("{}: {e}", path.display()))
@@ -1739,6 +1856,7 @@ fn write_atomic(path: &Path, bytes: &[u8]) -> Result<()> {
#[cfg(test)]
mod tests {
use super::*;
+ use pdfcraft_platform::staging::STAGING_ATTEMPTS;
#[test]
fn dot_dot_resolves_by_name_and_never_climbs_above_the_start() {
@@ -1790,4 +1908,158 @@ mod tests {
assert!(foreign_share(Path::new(r"\\server\other\x.pdf"), shared));
assert!(foreign_share(Path::new(r"\\attacker\docs\x.pdf"), shared));
}
+
+ /// A fresh, empty folder for one staging test.
+ fn staging_dir(test: &str) -> PathBuf {
+ let dir = std::env::temp_dir().join(format!("pdfcraft-staging-{}-{test}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
+ std::fs::create_dir_all(&dir).unwrap();
+ dir
+ }
+
+ fn staged(dir: &Path, suffix: u64) -> PathBuf {
+ dir.join(format!(".out.pdf.{suffix:016x}.pdfcraft-tmp"))
+ }
+
+ fn read(p: &Path) -> String {
+ std::fs::read_to_string(p).unwrap()
+ }
+
+ /// A symbolic link to a file, where the system allows one (Windows needs Developer Mode or an
+ /// administrator for it).
+ fn file_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
+ #[cfg(unix)]
+ {
+ std::os::unix::fs::symlink(target, link)
+ }
+ #[cfg(windows)]
+ {
+ std::os::windows::fs::symlink_file(target, link)
+ }
+ #[cfg(not(any(unix, windows)))]
+ {
+ Err(std::io::Error::other(format!("no symbolic links here: {} {}", target.display(), link.display())))
+ }
+ }
+
+ #[test]
+ fn staging_never_writes_through_a_file_planted_at_its_name() {
+ let dir = staging_dir("planted");
+ // A file elsewhere that a planted link points at.
+ let outside = dir.join("outside.txt");
+ std::fs::write(&outside, "PRECIOUS").unwrap();
+ let target = dir.join("out.pdf");
+ // A hard link needs no privileges on any system, and writing to it writes to `outside`.
+ std::fs::hard_link(&outside, staged(&dir, 1)).unwrap();
+ std::fs::write(staged(&dir, 2), "PLANTED").unwrap();
+ write_atomic_with(&target, b"NEW", [1, 2, 3]).unwrap();
+ assert_eq!(read(&target), "NEW");
+ assert_eq!(read(&outside), "PRECIOUS");
+ assert_eq!(read(&staged(&dir, 1)), "PRECIOUS");
+ assert_eq!(read(&staged(&dir, 2)), "PLANTED");
+ assert!(!staged(&dir, 3).exists(), "the staging file was renamed into place");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn staging_never_writes_through_a_symbolic_link_planted_at_its_name() {
+ let dir = staging_dir("symlink");
+ let outside = dir.join("outside.txt");
+ std::fs::write(&outside, "PRECIOUS").unwrap();
+ let target = dir.join("out.pdf");
+ if let Err(e) = file_symlink(&outside, &staged(&dir, 1)) {
+ eprintln!("symbolic links not checked: {e}");
+ return;
+ }
+ write_atomic_with(&target, b"NEW", [1, 2]).unwrap();
+ assert_eq!(read(&target), "NEW");
+ assert_eq!(read(&outside), "PRECIOUS");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn staging_never_creates_a_file_through_a_dangling_link_at_its_name() {
+ let dir = staging_dir("dangling");
+ let unborn = dir.join("created-through-a-link.txt");
+ let target = dir.join("out.pdf");
+ if let Err(e) = file_symlink(&unborn, &staged(&dir, 1)) {
+ eprintln!("symbolic links not checked: {e}");
+ return;
+ }
+ write_atomic_with(&target, b"NEW", [1, 2]).unwrap();
+ assert_eq!(read(&target), "NEW");
+ assert!(!unborn.exists(), "nothing was created through the dangling link");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn staging_gives_up_rather_than_reuse_a_taken_name() {
+ let dir = staging_dir("taken");
+ let target = dir.join("out.pdf");
+ std::fs::write(&target, "OLD").unwrap();
+ for s in 1..=STAGING_ATTEMPTS as u64 {
+ std::fs::write(staged(&dir, s), "PLANTED").unwrap();
+ }
+ assert!(write_atomic_with(&target, b"NEW", 1..).is_err());
+ assert_eq!(read(&target), "OLD");
+ for s in 1..=STAGING_ATTEMPTS as u64 {
+ assert_eq!(read(&staged(&dir, s)), "PLANTED");
+ }
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ /// The names in a folder: what a test can see was left behind.
+ fn listing(dir: &Path) -> Vec {
+ let mut names: Vec<_> = std::fs::read_dir(dir).unwrap().map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();
+ names.sort();
+ names
+ }
+
+ #[test]
+ fn staging_names_differ_between_saves_and_fit_long_names() {
+ let suffixes: std::collections::HashSet = staging_suffixes().take(64).collect();
+ assert_eq!(suffixes.len(), 64);
+ assert_ne!(staging_suffixes().next(), staging_suffixes().next(), "each save draws new names");
+ // 60 four-byte characters: a 244-byte name, within every system's limit. Its staging name
+ // must be too (on Linux the whole name in it would be 275 bytes).
+ let dir = staging_dir("long");
+ let name = format!("{}.pdf", "\u{1F600}".repeat(60));
+ write_atomic(&dir.join(&name), b"NEW").unwrap();
+ assert_eq!(read(&dir.join(&name)), "NEW");
+ assert_eq!(listing(&dir), [name], "no staging file is left behind");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn a_folder_at_the_staging_name_is_left_alone() {
+ let dir = staging_dir("folder");
+ std::fs::create_dir(staged(&dir, 1)).unwrap();
+ std::fs::write(staged(&dir, 1).join("inside.txt"), "PLANTED").unwrap();
+ let target = dir.join("out.pdf");
+ write_atomic_with(&target, b"NEW", [1, 2]).unwrap();
+ assert_eq!(read(&target), "NEW");
+ assert_eq!(read(&staged(&dir, 1).join("inside.txt")), "PLANTED");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ /// Windows refuses to replace a read-only file, so the rename fails: the staging file must not
+ /// be left behind.
+ #[cfg(windows)]
+ #[test]
+ fn a_failed_rename_removes_the_staging_file() {
+ let dir = staging_dir("readonly");
+ let target = dir.join("out.pdf");
+ std::fs::write(&target, "OLD").unwrap();
+ let mut perms = std::fs::metadata(&target).unwrap().permissions();
+ perms.set_readonly(true);
+ std::fs::set_permissions(&target, perms.clone()).unwrap();
+ let e = write_atomic_with(&target, b"NEW", [7]).unwrap_err();
+ assert!(e.to_string().contains(&target.display().to_string()), "the rename failed, not the staging: {e}");
+ assert_eq!(read(&target), "OLD");
+ assert_eq!(listing(&dir), ["out.pdf"], "the staging file was removed");
+ #[allow(clippy::permissions_set_readonly_false)]
+ perms.set_readonly(false);
+ std::fs::set_permissions(&target, perms).unwrap();
+ let _ = std::fs::remove_dir_all(&dir);
+ }
}
diff --git a/crates/automation/src/mcp.rs b/crates/automation/src/mcp.rs
index e746cf53..d114ea6d 100644
--- a/crates/automation/src/mcp.rs
+++ b/crates/automation/src/mcp.rs
@@ -29,15 +29,53 @@ const INVALID_PARAMS: i64 = -32602;
const INSTRUCTIONS: &str = "PdfCraft edits PDFs. Open a file with doc_open to get a document id, then inspect \
(doc_info, text_extract, text_find, page_render) or edit it (page_*, doc_set_info). Edits are undoable \
(edit_undo) and stay in memory until doc_save. Page numbers are 1-based. Open documents are also \
-resources: pdfcraft://doc/{doc}/info, /text, /page/{page}/text and /page/{page}/image.";
+resources: pdfcraft://doc/{doc}/info, /text, /page/{page}/text and /page/{page}/image. \
+command_list discovers command ids and tool schemas; command_run executes one, command_batch runs several. \
+doc_inspect returns open document state; render_preview returns a bounded PNG.";
+
+/// Appended to the instructions in compact mode.
+const COMPACT_INSTRUCTIONS: &str = " Only a core set of tools is listed. Every other tool is still available: find it with \
+tool_search (optional query and category, or name for its full input schema) and run it with tool_call.";
+
+/// The tools `tools/list` returns in compact mode, besides the two meta tools.
+pub const COMPACT_CORE_TOOLS: &[&str] = &[
+ "doc_open",
+ "doc_info",
+ "doc_save",
+ "doc_close",
+ "page_render",
+ "text_extract",
+ "text_find",
+ "doc_combine",
+ "doc_split",
+ "edit_undo",
+ "command_list",
+ "command_run",
+ "command_batch",
+ "doc_inspect",
+ "render_preview",
+];
+
+/// Meta tools that exist only in compact mode.
+const TOOL_SEARCH: &str = "tool_search";
+const TOOL_CALL: &str = "tool_call";
pub struct McpServer {
automation: Automation,
+ compact: bool,
}
impl McpServer {
pub fn new(automation: Automation) -> Self {
- Self { automation }
+ Self { automation, compact: false }
+ }
+
+ /// In compact mode `tools/list` returns only [`COMPACT_CORE_TOOLS`] plus `tool_search` and
+ /// `tool_call`, which find and run any other tool. `tools/call` accepts every tool by name
+ /// either way. Off by default.
+ pub fn with_compact(mut self, on: bool) -> Self {
+ self.compact = on;
+ self
}
pub fn automation(&self) -> &Automation {
@@ -78,7 +116,8 @@ impl McpServer {
};
let params = obj.get("params").cloned().unwrap_or(Value::Null);
let id = id?; // notifications/initialized, notifications/cancelled, …: nothing to answer
- Some(match self.dispatch(method, ¶ms) {
+ let result = if method == "tools/call" { guarded_tool(|| self.dispatch(method, ¶ms)) } else { self.dispatch(method, ¶ms) };
+ Some(match result {
Ok(result) => json!({ "jsonrpc": "2.0", "id": id, "result": result }),
Err((code, message)) => error(id, code, &message),
})
@@ -93,18 +132,46 @@ impl McpServer {
"protocolVersion": version,
"capabilities": { "tools": { "listChanged": false }, "resources": { "listChanged": false, "subscribe": false } },
"serverInfo": { "name": "pdfcraft", "title": "PdfCraft", "version": env!("CARGO_PKG_VERSION"), "websiteUrl": pdfcraft_engine::links::APP_PAGE },
- "instructions": INSTRUCTIONS,
+ "instructions": if self.compact { format!("{INSTRUCTIONS}{COMPACT_INSTRUCTIONS}") } else { INSTRUCTIONS.to_string() },
}))
}
"ping" => Ok(json!({})),
- "tools/list" => Ok(json!({ "tools": crate::tools().iter().map(tool_json).collect::>() })),
+ "tools/list" => Ok(json!({ "tools": self.tool_list() })),
"tools/call" => {
let name = params.get("name").and_then(Value::as_str).ok_or((INVALID_PARAMS, "tools/call needs a tool name".to_string()))?;
let args = params.get("arguments").cloned().unwrap_or(Value::Null);
+ if self.compact && name == TOOL_SEARCH {
+ check_keys(name, &args, &["query", "category", "name"]).map_err(|e| (INVALID_PARAMS, e))?;
+ return Ok(match search_tools(&args) {
+ Ok(found) => call_result(vec![Content::Json(found)]),
+ Err(message) => tool_error(&message),
+ });
+ }
+ if self.compact && name == TOOL_CALL {
+ check_keys(name, &args, &["name", "arguments"]).map_err(|e| (INVALID_PARAMS, e))?;
+ let (inner, inner_args) = match unwrap_tool_call(&args) {
+ Ok(pair) => pair,
+ Err(message) => return Ok(tool_error(&message)),
+ };
+ return Ok(match self.automation.call(&inner, &inner_args) {
+ Ok(content) => tool_content(&inner, content),
+ Err(ToolError::UnknownTool(t)) => tool_error(&format!("unknown tool {t:?}; use tool_search to find the right name")),
+ Err(e) => tool_error(&e.to_string()),
+ });
+ }
+ if let Some(def) = crate::tools::find(name) {
+ let keys: Vec<&str> = def
+ .input_schema
+ .get("properties")
+ .and_then(Value::as_object)
+ .map(|p| p.keys().map(String::as_str).collect())
+ .unwrap_or_default();
+ check_keys(name, &args, &keys).map_err(|e| (INVALID_PARAMS, e))?;
+ }
match self.automation.call(name, &args) {
- Ok(content) => Ok(call_result(content)),
+ Ok(content) => Ok(tool_content(name, content)),
Err(ToolError::UnknownTool(t)) => Err((INVALID_PARAMS, format!("unknown tool {t:?}"))),
- Err(e) => Ok(json!({ "content": [{ "type": "text", "text": e.to_string() }], "isError": true })),
+ Err(e) => Ok(tool_error(&e.to_string())),
}
}
"resources/list" => Ok(json!({ "resources": self.resource_list() })),
@@ -118,6 +185,167 @@ impl McpServer {
}
}
+impl McpServer {
+ /// What `tools/list` returns: every tool, or in compact mode the core set and the meta tools.
+ fn tool_list(&self) -> Vec {
+ let all = crate::tools();
+ if !self.compact {
+ return all.iter().map(tool_json).collect();
+ }
+ let mut out: Vec = COMPACT_CORE_TOOLS.iter().filter_map(|n| all.iter().find(|t| t.name == *n)).map(tool_json).collect();
+ out.extend(meta_tools());
+ out
+ }
+}
+
+/// The two tools only compact mode lists.
+fn meta_tools() -> [Value; 2] {
+ [
+ json!({
+ "name": TOOL_SEARCH,
+ "title": "Find PdfCraft tools",
+ "description": "Search and list all PdfCraft automation tools, including the core tools, with a one-sentence description each. Filter by query \
+ (words matched against name, title and description) and/or category (the name prefix: doc, page, text, form, …). \
+ With name, return that one tool in full, including its input_schema. Run a tool with tool_call.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "query": { "type": "string", "description": "Words to look for, all of which must match (case-insensitive)." },
+ "category": { "type": "string", "description": "Tool name prefix, e.g. page, text, form, redact." },
+ "name": { "type": "string", "description": "Exact tool name: return its description and input_schema." },
+ },
+ "required": [],
+ "additionalProperties": false,
+ },
+ "annotations": { "title": "Find PdfCraft tools", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false },
+ }),
+ json!({
+ "name": TOOL_CALL,
+ "title": "Run any PdfCraft tool",
+ "description": "Run any PdfCraft tool by name with its arguments, exactly as if it were called directly. \
+ Find names and argument schemas with tool_search. The result is the tool's own result.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "name": { "type": "string", "description": "The tool to run, e.g. page_rotate." },
+ "arguments": { "type": "object", "description": "The tool's arguments (see its input_schema from tool_search)." },
+ },
+ "required": ["name"],
+ "additionalProperties": false,
+ },
+ "annotations": { "title": "Run any PdfCraft tool", "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false },
+ }),
+ ]
+}
+
+/// The category of a tool: its name up to the first underscore (`page_rotate` → `page`).
+fn category_of(name: &str) -> &str {
+ name.split('_').next().unwrap_or(name)
+}
+
+/// A description up to and including its first sentence.
+fn first_sentence(text: &str) -> &str {
+ // ASCII lowercasing keeps byte offsets, so positions found in `lower` are valid in `text`.
+ let lower = text.to_ascii_lowercase();
+ let mut from = 0;
+ while let Some(i) = lower.get(from..).and_then(|rest| rest.find(". ")).map(|i| i + from) {
+ // "e.g. " and "i.e. " are abbreviations, not the end of the sentence.
+ if !lower.get(..i).is_some_and(|before| before.ends_with("e.g") || before.ends_with("i.e")) {
+ return text.get(..=i).unwrap_or(text);
+ }
+ from = i + 2;
+ }
+ text
+}
+
+/// Reject keys other than `allowed`, as the tool table does for a tool's own arguments.
+fn check_keys(tool: &str, args: &Value, allowed: &[&str]) -> Result<(), String> {
+ match args.as_object().and_then(|o| o.keys().find(|k| !allowed.contains(&k.as_str()))) {
+ Some(k) => Err(format!("{tool}: unknown argument {k:?} (expected: {})", allowed.join(", "))),
+ None => Ok(()),
+ }
+}
+
+/// `tool_search`: filter the tool table by query and category, or describe one tool in full.
+fn search_tools(args: &Value) -> Result {
+ if !(args.is_object() || args.is_null()) {
+ return Err(format!("{TOOL_SEARCH} takes an object with optional query, category and name"));
+ }
+ check_keys(TOOL_SEARCH, args, &["query", "category", "name"])?;
+ let text = |key: &str| match args.get(key) {
+ None | Some(Value::Null) => Ok(None),
+ Some(Value::String(s)) => Ok(Some(s.trim())),
+ Some(_) => Err(format!("{TOOL_SEARCH}: {key} must be a string")),
+ };
+ let (query, category, name) = (text("query")?, text("category")?, text("name")?);
+ let all = crate::tools();
+ if let Some(name) = name {
+ let t =
+ all.iter().find(|t| t.name == name).ok_or_else(|| format!("unknown tool {name:?}; call {TOOL_SEARCH} without name to list the tools"))?;
+ return Ok(json!({ "tool": {
+ "name": t.name, "title": t.title, "category": category_of(t.name), "description": t.description,
+ "read_only": t.read_only, "destructive": t.destructive, "input_schema": t.input_schema,
+ } }));
+ }
+ let category = category.map(|c| c.trim_end_matches('_').to_lowercase()).filter(|c| !c.is_empty());
+ let words: Vec = query.map(|q| q.to_lowercase().split_whitespace().map(str::to_owned).collect()).unwrap_or_default();
+ let mut categories: Vec<&str> = all.iter().map(|t| category_of(t.name)).collect();
+ categories.sort_unstable();
+ categories.dedup();
+ let found: Vec = all
+ .iter()
+ .filter(|t| category.as_deref().is_none_or(|c| category_of(t.name) == c))
+ .filter(|t| {
+ let haystack = format!("{} {} {}", t.name, t.title, t.description).to_lowercase();
+ words.iter().all(|w| haystack.contains(w.as_str()))
+ })
+ .map(|t| json!({ "name": t.name, "category": category_of(t.name), "description": first_sentence(t.description), "read_only": t.read_only }))
+ .collect();
+ Ok(json!({ "count": found.len(), "tools": found, "categories": categories }))
+}
+
+/// `tool_call`: the tool name and its arguments from the meta tool's own arguments.
+fn unwrap_tool_call(args: &Value) -> Result<(String, Value), String> {
+ let Some(obj) = args.as_object() else { return Err(format!("{TOOL_CALL} needs an object with name and arguments")) };
+ check_keys(TOOL_CALL, args, &["name", "arguments"])?;
+ let name = obj
+ .get("name")
+ .and_then(Value::as_str)
+ .ok_or_else(|| format!("{TOOL_CALL} needs the name of the tool to run; find it with {TOOL_SEARCH}"))?;
+ if name == TOOL_CALL || name == TOOL_SEARCH {
+ return Err(format!("{TOOL_SEARCH} and {TOOL_CALL} are called directly, not through {TOOL_CALL}"));
+ }
+ let inner = match obj.get("arguments") {
+ None | Some(Value::Null) => Value::Null,
+ Some(v @ Value::Object(_)) => v.clone(),
+ Some(_) => return Err(format!("{TOOL_CALL}: arguments must be an object")),
+ };
+ Ok((name.to_owned(), inner))
+}
+
+/// Last-resort boundary shared by every tools/call route, including compact dispatch.
+fn guarded_tool(f: impl FnOnce() -> Result) -> Result {
+ pdfcraft_engine::guard(f).unwrap_or_else(|message| Ok(tool_error(&format!("internal error: {message}"))))
+}
+
+fn tool_content(name: &str, content: Vec) -> Value {
+ let failed = name == "command_batch"
+ && content.iter().any(|c| match c {
+ Content::Json(v) => v.get("failed").and_then(Value::as_u64).is_some_and(|n| n > 0),
+ _ => false,
+ });
+ let mut result = call_result(content);
+ if let Some(object) = result.as_object_mut() {
+ object.insert("isError".into(), json!(failed));
+ }
+ result
+}
+
+/// A failed tool call, as the agent should read it.
+fn tool_error(message: &str) -> Value {
+ json!({ "content": [{ "type": "text", "text": message }], "isError": true })
+}
+
/// The resource behind a `pdfcraft://` URI.
#[derive(Debug, PartialEq)]
enum Resource {
@@ -176,10 +404,29 @@ impl McpServer {
}
}
}
+ out.extend([
+ json!({"uri":"pdfcraft://document","name":"Open documents","mimeType":"application/json","description":"Session document state, as doc_inspect without arguments."}),
+ json!({"uri":"pdfcraft://commands","name":"Command catalog","mimeType":"application/json","description":"Commands and mapped tool schemas, as command_list without arguments."}),
+ ]);
out
}
fn read_resource(&mut self, uri: &str) -> Result {
+ if let Some(tool) = match uri {
+ "pdfcraft://document" => Some("doc_inspect"),
+ "pdfcraft://commands" => Some("command_list"),
+ _ => None,
+ } {
+ let content = self.automation.call(tool, &json!({})).map_err(|e| (INVALID_PARAMS, e.to_string()))?;
+ let value = content
+ .into_iter()
+ .find_map(|c| match c {
+ Content::Json(v) => Some(v),
+ _ => None,
+ })
+ .ok_or((INVALID_PARAMS, "resource returned no JSON".into()))?;
+ return Ok(json!({"uri":uri,"mimeType":"application/json","text":value.to_string()}));
+ }
let r = parse_uri(uri).ok_or((INVALID_PARAMS, format!("unknown resource {uri:?}")))?;
let call = |a: &mut Automation, tool: &str, args: Value| a.call(tool, &args).map_err(|e| (INVALID_PARAMS, e.to_string()));
let json_of = |c: Vec| c.into_iter().find_map(|c| if let Content::Json(v) = c { Some(v) } else { None }).unwrap_or(Value::Null);
@@ -232,7 +479,7 @@ fn tool_json(t: &crate::ToolDef) -> Value {
"title": t.title,
"description": t.description,
"inputSchema": t.input_schema,
- "annotations": { "title": t.title, "readOnlyHint": t.read_only, "destructiveHint": t.destructive, "openWorldHint": false },
+ "annotations": { "title": t.title, "readOnlyHint": t.read_only, "destructiveHint": t.destructive, "idempotentHint": t.read_only || matches!(t.name, "doc_save" | "doc_optimize" | "doc_export_data" | "measure_export" | "doc_export_images" | "doc_export_office" | "doc_export_all_images" | "doc_export_text" | "image_save"), "openWorldHint": false },
})
}
@@ -262,7 +509,28 @@ fn call_result(content: Vec) -> Value {
#[cfg(test)]
mod tests {
- use super::{Resource, parse_uri};
+ use super::{Resource, first_sentence, parse_uri};
+
+ #[test]
+ fn conventions_panic_is_a_tool_error() {
+ let r = super::guarded_tool(|| panic!("synthetic tool failure")).unwrap();
+ assert_eq!(r["isError"], true);
+ assert!(r["content"][0]["text"].as_str().unwrap().contains("synthetic tool failure"));
+ let next = super::guarded_tool(|| Ok(serde_json::json!({"ok":true}))).unwrap();
+ assert_eq!(next["ok"], true);
+ }
+
+ #[test]
+ fn first_sentence_skips_abbreviations() {
+ assert_eq!(first_sentence("Rotate pages. Undoable."), "Rotate pages.");
+ assert_eq!(first_sentence("Label pages (i.e. roman numerals). Undoable."), "Label pages (i.e. roman numerals).");
+ assert_eq!(first_sentence("Label pages (I.E. roman numerals, E.G. i, ii). Undoable."), "Label pages (I.E. roman numerals, E.G. i, ii).");
+ assert_eq!(first_sentence("Use a value, e.g. en-US, or none. Then more."), "Use a value, e.g. en-US, or none.");
+ assert_eq!(first_sentence("No full stop here"), "No full stop here");
+ assert_eq!(first_sentence("Only an abbreviation, e.g. this"), "Only an abbreviation, e.g. this");
+ assert_eq!(first_sentence(""), "");
+ assert_eq!(first_sentence("Zażółć gęślą, i.e. jaźń. Dalej."), "Zażółć gęślą, i.e. jaźń.");
+ }
#[test]
fn resource_uris_parse() {
diff --git a/crates/automation/src/tools.rs b/crates/automation/src/tools.rs
index 2588efaa..5e9e10ca 100644
--- a/crates/automation/src/tools.rs
+++ b/crates/automation/src/tools.rs
@@ -185,17 +185,31 @@ pub fn tools() -> Vec {
json!({ "doc": doc(), "pages": pages("to extract"), "out": save_out.clone(), "open": open.clone(), "separate": { "type": "boolean" }, "out_dir": { "type": "string" }, "delete": { "type": "boolean" } }),
&["doc", "pages"],
)),
- t("doc_combine", "Combine files", "Combine PDFs, in order, into one (bookmarks are kept under one entry per file). pages optionally chooses each file's pages, in step with paths: a range such as \"1-3, 6\" or null for all pages.")
+ t("doc_combine", "Combine files", "Combine PDFs, in order, into one (bookmarks are kept under one entry per file). pages optionally chooses each file's pages, in step with paths: a range such as \"1-3, 6\" or null for all pages. passwords, also in step with paths, opens encrypted files (the open password, or the permissions password where a file's security doesn't allow copying pages; null for none). The result is not encrypted. Passwords are never echoed back.")
.cmd("page.combine")
.with(schema(
json!({
"paths": { "type": "array", "items": { "type": "string" }, "minItems": 2 },
"pages": { "type": "array", "items": { "type": ["string", "null"] } },
+ "passwords": { "type": "array", "items": { "type": ["string", "null"] } },
"out": save_out,
"open": open,
}),
&["paths"],
)),
+ t("doc_create_multiple", "Create PDF from multiple files", "Convert several files (PDFs, PNG/JPEG/JPEG 2000/TIFF/GIF/BMP images, .txt files) to PDF in one run. mode \"combine\" (default) joins them, in order, into one PDF with a bookmark per file; pages optionally chooses each file's pages, in step with paths (a range such as \"1-3, 6\" or null). mode \"separate\" writes one PDF per file into out_dir (files that are already PDFs are skipped; existing files are never overwritten) and reports each file's result.")
+ .cmd("create.multiple")
+ .with(schema(
+ json!({
+ "paths": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": pdfcraft_engine::MAX_CREATE_FILES },
+ "mode": { "type": "string", "enum": ["combine", "separate"] },
+ "pages": { "type": "array", "items": { "type": ["string", "null"] } },
+ "out": save_out.clone(),
+ "open": open.clone(),
+ "out_dir": { "type": "string", "description": "Folder for mode \"separate\"." },
+ }),
+ &["paths"],
+ )),
t("doc_split", "Split a document", "Split into several files written to out_dir: every N pages, before given pages, at top-level bookmarks (bookmarks: true; files named after them), or by file size (max_mb). Files are -partK.pdf.")
.cmd("page.split")
.with(schema(
@@ -231,7 +245,7 @@ pub fn tools() -> Vec {
}),
&["doc", "from", "to"],
)),
- t("form_fields", "List form fields", "Every interactive form field: name, type (text, checkbox, radio, combo, list, button, signature), value, options, page and rect (top-left-origin points), read-only and required flags.")
+ t("form_fields", "List form fields", "Every interactive form field: name, type (text, checkbox, radio, combo, list, button, signature), value, options, page, rect (top-left-origin points) and rotation (0, 90, 180 or 270 degrees counterclockwise), read-only and required flags.")
.ro()
.with(schema(json!({ "doc": doc() }), &["doc"])),
t(
@@ -284,7 +298,7 @@ pub fn tools() -> Vec {
t(
"form_set_props",
"Field properties",
- "Change a field's properties (General and Options tabs): name (renames it), tooltip, read_only, required, multiline, max_length (0 = no limit), options (combo/list items), font_size (0 = auto), rect (position), format, validate, calculate (Acrobat's Format/Validate/Calculate tabs, run natively: values are checked, formatted and recalculated as in Acrobat). Options tab: align (left, center, right), default (the value Reset form restores; for check boxes and radio buttons their on state, \"\" for off), flags { scroll, rich_text, password, file_select, spell_check, comb (needs max_length), sort, editable, multi_select, commit_immediately }, check_style (check boxes and radio buttons: check, circle, cross, diamond, square, star). Only the given ones change. Undoable.",
+ "Change a field's properties (General and Options tabs): name (renames it), tooltip, read_only, required, multiline, max_length (0 = no limit), options (combo/list items), font_size (0 = auto), rect (position), rotation (0, 90, 180 or 270 degrees counterclockwise; changing between horizontal and vertical swaps width and height around the center), format, validate, calculate (Acrobat's Format/Validate/Calculate tabs, run natively: values are checked, formatted and recalculated as in Acrobat). Options tab: align (left, center, right), default (the value Reset form restores; for check boxes and radio buttons their on state, \"\" for off), flags { scroll, rich_text, password, file_select, spell_check, comb (needs max_length), sort, editable, multi_select, commit_immediately }, check_style (check boxes and radio buttons: check, circle, cross, diamond, square, star). Only the given ones change. Undoable.",
)
.with(schema(
json!({
@@ -304,6 +318,7 @@ pub fn tools() -> Vec {
"flags": { "type": "object", "additionalProperties": { "type": "boolean" } },
"font_size": { "type": "number", "minimum": 0 },
"rect": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "Move/resize: points from the top-left of the displayed page." },
+ "rotation": { "type": "integer", "enum": [0, 90, 180, 270], "description": "Widget rotation in degrees, counterclockwise. Changing between horizontal and vertical swaps the rectangle around its center." },
"appearance": { "type": "object", "description": "Appearance tab: border, fill, text_color (#RRGGBB, a name or \"none\"), width (1 thin, 2 medium, 3 thick), style (solid, dashed, beveled, inset, underline), font (helvetica, times, courier)." },
"format": { "description": "Format tab: {\"type\": \"number\", \"decimals\": 2, \"currency\": \"$\", \"separator\": 0-4, \"negative\": 0-3}, {\"type\": \"percent\"}, {\"type\": \"date\"|\"time\", \"pattern\": \"mm/dd/yyyy\"}, {\"type\": \"zip\"|\"zip4\"|\"phone\"|\"ssn\"}, {\"type\": \"mask\", \"mask\": \"AA-9999\"}, or \"none\"." },
"validate": { "description": "Validate tab: {\"min\": 0, \"max\": 100} (either may be left out) or \"none\"." },
@@ -513,7 +528,7 @@ pub fn tools() -> Vec {
"Add a comment",
"Add a comment as Acrobat's commenting tools do. Geometry is in points with the origin at the top-left of the displayed page, y down (as in page_render images at 72 dpi and text_find rects). \
note: `at` [x, y] (icon top-left). stamp: `at` [x, y] (its centre) and `stamp`: approved, completed, confidential, draft, final, for comment, for public release, information only, not approved, not for public release, preliminary results, void, accepted, initial here, rejected, sign here, witness; dynamic: true for the dynamic approved/confidential/received/reviewed/revised stamps with a By … at … line. highlight/underline/strikeout/squiggly: `find` (text on the page to mark; every match with all: true) or `quads`. \
- rectangle/oval/textbox: `rect` [x0, y0, x1, y1]. line/arrow: `from`, `to`. ink: `strokes` [[[x, y], …], …]. \
+ rectangle/oval/textbox: `rect` [x0, y0, x1, y1]. line/arrow: `from`, `to`. Optional `endings` (two names: start, end) for a line, arrow or polyline, or one name for a callout: None, Square, Circle, Diamond, OpenArrow, ClosedArrow, Butt, ROpenArrow, RClosedArrow, Slash. An arrow without endings is None then OpenArrow. ink: `strokes` [[[x, y], …], …]. \
polygon/cloud/polyline (connected lines): `points` [[x, y], …]. callout: `rect` (its text box), `to` (the point the arrow touches), optional `knee`. caret (inserted text): `at`, the insertion point on the baseline. replace (Replace Text): `find` or `quads` like highlight, `contents` the replacement. attachment: `path` (the file), `at`, optional `icon` (PushPin, Paperclip, Graph, Tag). Undoable.",
)
.with(schema(
@@ -541,6 +556,7 @@ pub fn tools() -> Vec {
"fill": color(),
"opacity": { "type": "number", "minimum": 0, "maximum": 1 },
"width": { "type": "number", "minimum": 0, "description": "Line width in points." },
+ "endings": { "type": "array", "items": { "type": "string", "enum": ["None", "Square", "Circle", "Diamond", "OpenArrow", "ClosedArrow", "Butt", "ROpenArrow", "RClosedArrow", "Slash"] }, "minItems": 1, "maxItems": 2, "description": "Line endings. Two names (start, end) for a line, arrow or polyline; one name for a callout." },
"font_size": { "type": "number", "exclusiveMinimum": 0 },
}),
&["doc", "page", "type"],
@@ -617,7 +633,7 @@ pub fn tools() -> Vec {
json!({ "doc": doc(), "sort": { "type": "string", "enum": ["page", "author", "date", "type"] }, "out": save_out, "open": open }),
&["doc"],
)),
- t("comment_edit", "Edit a comment", "Change a comment's text, colour, opacity, line width, rectangle (rectangle/oval/text box) or position (`move` [dx, dy] in points). One undo step.").with(schema(
+ t("comment_edit", "Edit a comment", "Change a comment's text, colour, opacity, line width, rectangle (rectangle/oval/text box/stamp) or position (`move` [dx, dy] in points). Stamps keep their original appearance when resized. One undo step.").with(schema(
comment_ref(json!({
"contents": { "type": "string" },
"color": color(),
@@ -628,6 +644,8 @@ pub fn tools() -> Vec {
})),
&["doc"],
)),
+ t("comment_image_preview", "Preview image signature layers", "Return a PNG of the page without the selected image signature/initials (layer=background, default), or its embedded image with alpha (layer=image). Includes the displayed rectangle, document rotation, image_rotation (how far clockwise the image is shown turned) and annotation opacity. Cache these layers for live placement/resizing; commit once with comment_edit. Does not change the document or undo history.")
+ .ro().with(schema(comment_ref(json!({ "layer": { "type": "string", "enum": ["background", "image"], "default": "background" }, "dpi": { "type": "number", "minimum": 1, "maximum": 600, "default": 96 } })), &["doc"])),
t("comment_delete", "Delete a comment", "Delete a comment with its pop-up and replies. Undoable.").destructive().with(schema(comment_ref(json!({})), &["doc"])),
t(
"doc_protect",
@@ -892,7 +910,7 @@ pub fn tools() -> Vec {
t(
"fill_sign_add",
"Fill & Sign: type text or place a mark",
- "Fill in a form that has no fields, as Acrobat's Fill & Sign does: type text (`text`, 10 pt), place a check, cross, dot or line, today's date, or a typed signature or initials (`text` drawn in a script font as filled outlines; at is its left edge, centred vertically), at `at` [x, y] in points from the top-left of the page (the text's top-left; a mark's centre). Creates movable, undoable annotations.",
+ "Fill in a form that has no fields, as Acrobat's Fill & Sign does: type text (`text`, 10 pt), place a check, cross, dot or line, today's date, or a signature or initials (either `text` drawn in a script font, or `path` to a local PNG/JPEG image up to 4 MiB and 4 megapixels, preserving transparency). `at` [x, y] is in points from the top-left of the page: text's top-left, mark's centre, signature's left edge centred vertically. Image signatures fit within 150 pt wide and 32 pt tall (24 pt for initials). Creates movable, undoable annotations.",
)
.cmd("sign.fill.text")
.with(schema(
@@ -902,6 +920,7 @@ pub fn tools() -> Vec {
"type": { "type": "string", "enum": ["text", "check", "cross", "dot", "line", "date", "signature", "initials"] },
"at": point(),
"text": { "type": "string", "minLength": 1 },
+ "path": { "type": "string", "description": "PNG or JPEG for signature/initials; pass either path or text." },
"author": { "type": "string" },
}),
&["doc", "page", "type", "at"],
@@ -955,11 +974,11 @@ pub fn tools() -> Vec {
.ro()
.cmd("edit.edit_text")
.with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 } }), &["doc", "page"])),
- t("page_images", "List page images", "The images a page draws (Edit a PDF): number, box (top-left-origin points), pixel size and resource name.")
+ t("page_images", "List page images", "The raster images and grouped Form artwork a page draws (Edit a PDF): number, box (top-left-origin points), kind (image/form), pixel size ([0,0] for forms) and resource name. Forms include nested graphics and are edited as a whole. Numbers count forms and images together in drawing order, so a page with forms numbers its images differently than before forms were listed: always take numbers from a fresh page_images call.")
.ro()
.cmd("edit.edit_text")
.with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 } }), &["doc", "page"])),
- t("image_edit", "Edit an image", "Change one of a page's images (number from page_images): action move (rect: new box in top-left-origin points), rotate (quarters clockwise, default 1), flip_horizontal, flip_vertical, replace (path: an image file, drawn in the same place) or delete. Undoable.")
+ t("image_edit", "Edit an image", "Change one of a page's images (number from page_images): action move (rect: new box in top-left-origin points), rotate (quarters clockwise, default 1), flip_horizontal, flip_vertical, replace (path: an image file, drawn in the same place) or delete. Undoable. Form artwork supports move/resize/rotate/flip/delete as a group; replace and image_save only support raster images.")
.cmd("edit.edit_text")
.with(schema(
json!({
@@ -973,7 +992,7 @@ pub fn tools() -> Vec {
}),
&["doc", "page", "image", "action"],
)),
- t("image_save", "Save image as", "Write one of a page's images to path: JPEG images unchanged, others as PNG (the extension is added when missing).")
+ t("image_save", "Save image as", "Write one of a page's raster images (number from page_images; forms are refused) to path: JPEG images unchanged, others as PNG (the extension is added when missing).")
.destructive()
.cmd("edit.edit_text")
.with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "image": { "type": "integer", "minimum": 1 }, "path": { "type": "string" } }), &["doc", "page", "image", "path"])),
@@ -981,7 +1000,7 @@ pub fn tools() -> Vec {
.ro()
.cmd("edit.edit_text")
.with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 } }), &["doc", "page"])),
- t("text_edit", "Edit text", "Replace the text of one paragraph (paragraph, from text_paragraphs: rewrapped to the paragraph's width with its line spacing) or one line (line, from text_lines) in place, keeping position, size and colour. For a paragraph, also change its formatting: font (helvetica, times, courier) with bold/italic, size (points), color (#rrggbb), align (left, center, right, justify), underline, line_spacing (× size), char_spacing (points) and scale (horizontal, percent), or move it (dx, dy in points; up is +dy) and rewrap it to a new width (points); text may then be omitted. Its own font is reused when it can show every character; otherwise the line is set in Helvetica (the result shows the font used). Text that no available font can show is refused. Undoable.")
+ t("text_edit", "Edit text", "Replace the text of one paragraph (paragraph, from text_paragraphs: rewrapped to the paragraph's width with its line spacing) or one line (line, from text_lines) in place, keeping position, size and colour. For a paragraph, also change its formatting: font (helvetica, times, courier) with bold/italic, size (points), color (#rrggbb), align (left, center, right, justify), underline, line_spacing (× size), char_spacing (points) and scale (horizontal, percent), or move it (dx, dy in points; up is +dy) and rewrap it to a new width (points); text may then be omitted. Its own font is reused when it can show every character and no font/weight change is requested; otherwise it uses a standard font matching the source style or, for Japanese and other text no standard font can show (Cyrillic, Greek), real Mincho/Gothic fallback outlines matching the requested/source family and available weight, from a face that has every character (the result shows the font used). Missing Japanese weights use Regular, not synthetic bold; the small web build has only Gothic Regular. Paragraph bold may be set without font to keep the source family. Text that no available font can show is refused. Undoable.")
.cmd("edit.edit_text")
.with(schema(
json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "line": { "type": "integer", "minimum": 1 },
@@ -1032,7 +1051,15 @@ pub fn tools() -> Vec {
t("edit_redo", "Redo", "Redo the last undone edit of a document.").cmd("edit.redo").with(schema(json!({ "doc": doc() }), &["doc"])),
t("command_list", "List commands", "Every registered PdfCraft command with its menu, shortcut, whether it is enabled now, and the tool that automates it.")
.ro()
- .with(schema(json!({ "doc": doc() }), &[])),
+ .with(schema(json!({ "doc": doc(), "filter":{"type":"string"}, "enabled_only":{"type":"boolean"} }), &[])),
+ t("command_run", "Run a command", "Run a registry command through its headless tool. Pass that tool's arguments in params (see command_list). Unknown params are ignored with warnings; path confinement still applies.")
+ .destructive().with(schema(json!({"id":{"type":"string"},"params":{"type":"object"}}), &["id"])),
+ t("command_batch", "Run several commands", "Run steps in order (at most 1000). Returns completed/failed counts and per-step ok/result/error; stop_on_error defaults to true.")
+ .destructive().with(schema(json!({"steps":{"type":"array","items":schema(json!({"id":{"type":"string"},"params":{"type":"object"}}), &["id"])},"stop_on_error":{"type":"boolean"}}), &["steps"])),
+ t("doc_inspect", "Inspect open documents", "With doc, return doc_info; otherwise return information for every open document (empty documents array when none are open).")
+ .ro().with(schema(json!({"doc":doc()}), &[])),
+ t("render_preview", "Render a preview", "Render a PNG bounded by max_side (default 1024), without changing or saving the document. Page defaults to 1; doc may be omitted when exactly one document is open.")
+ .ro().with(schema(json!({"doc":doc(),"page":{"type":"integer","minimum":1},"max_side":{"type":"integer","minimum":1,"maximum":4096}}), &[])),
]
}
diff --git a/crates/automation/tests/automation.rs b/crates/automation/tests/automation.rs
index 3083dce4..7f8b2853 100644
--- a/crates/automation/tests/automation.rs
+++ b/crates/automation/tests/automation.rs
@@ -405,12 +405,20 @@ fn root_refusals_do_not_reveal_what_exists_outside() {
#[test]
fn writing_to_a_folder_touches_nothing_beside_it() {
// "." names the root itself. Saving there used to stage its temporary file next to the
- // root, outside it, overwriting and then deleting any file of that name.
+ // root, outside it, overwriting and then deleting any file of that name. Staging names are
+ // random now and a failed rename removes the staging file, so the "is a folder" refusal is
+ // what this checks; the listings and the file at the old staging name are canaries.
let (base, root) = sandbox("root-itself");
let mut a = auto(&root);
let beside = base.join(".root.pdfcraft-tmp");
std::fs::write(&beside, "SENTINEL").unwrap();
std::fs::create_dir_all(root.join("folder")).unwrap();
+ let listing = |dir: &Path| {
+ let mut names: Vec<_> = std::fs::read_dir(dir).unwrap().map(|e| e.unwrap().file_name()).collect();
+ names.sort();
+ names
+ };
+ let (base_before, folder_before) = (listing(&base), listing(&root.join("folder")));
let doc = ok(&mut a, "doc_open", json!({ "path": "inside.pdf" }))["doc"].as_u64().unwrap();
for p in [".", "", "folder", "folder/"] {
let e = a.call("doc_save", &json!({ "doc": doc, "path": p })).unwrap_err();
@@ -419,7 +427,8 @@ fn writing_to_a_folder_touches_nothing_beside_it() {
let png = vec![1, 2, 3];
assert!(a.write_output(".", &png).is_err());
assert_eq!(std::fs::read_to_string(&beside).unwrap(), "SENTINEL");
- assert!(!root.join(".folder.pdfcraft-tmp").exists());
+ assert_eq!(listing(&base), base_before, "nothing was left beside the root");
+ assert_eq!(listing(&root.join("folder")), folder_before, "nothing was left in the folder");
// `image_save` adds an extension when the path has none, which turned "." into `root.png`
// beside the root.
ok(&mut a, "doc_export_images", json!({ "doc": doc, "folder": "src", "dpi": 18 }));
@@ -561,11 +570,11 @@ fn mcp_resources_expose_open_documents() {
let dir = workdir("mcp-resources");
let mut s = McpServer::new(auto(&dir));
assert!(rpc(&mut s, 1, "initialize", json!({}))["result"]["capabilities"]["resources"].is_object());
- assert_eq!(rpc(&mut s, 2, "resources/list", json!({}))["result"]["resources"], json!([]));
+ assert_eq!(rpc(&mut s, 2, "resources/list", json!({}))["result"]["resources"].as_array().unwrap().len(), 2);
assert_eq!(rpc(&mut s, 3, "resources/templates/list", json!({}))["result"]["resourceTemplates"].as_array().unwrap().len(), 4);
rpc(&mut s, 4, "tools/call", json!({ "name": "doc_open", "arguments": { "path": "a.pdf" } }));
let list = rpc(&mut s, 5, "resources/list", json!({}))["result"]["resources"].as_array().cloned().unwrap();
- assert_eq!(list.len(), 2 + 3, "info, text and three page images");
+ assert_eq!(list.len(), 2 + 3 + 2, "info, text, three page images and two session resources");
assert_eq!(list[0]["uri"], "pdfcraft://doc/1/info");
let read = |s: &mut McpServer, uri: &str| rpc(s, 6, "resources/read", json!({ "uri": uri }))["result"]["contents"][0].clone();
let text = read(&mut s, "pdfcraft://doc/1/text");
@@ -581,6 +590,272 @@ fn mcp_resources_expose_open_documents() {
assert_eq!(rpc(&mut s, 7, "resources/read", json!({ "uri": "pdfcraft://doc/1/page/9/image" }))["error"]["code"], -32602);
}
+/// A server in compact mode with `dir` as its root.
+#[cfg(feature = "mcp")]
+fn compact_server(dir: &Path) -> McpServer {
+ McpServer::new(auto(dir)).with_compact(true)
+}
+
+/// Run a tool through the compact server's `tool_call`.
+#[cfg(feature = "mcp")]
+fn via_tool_call(s: &mut McpServer, id: u64, tool: &str, arguments: Value) -> Value {
+ rpc(s, id, "tools/call", json!({ "name": "tool_call", "arguments": { "name": tool, "arguments": arguments } }))
+}
+
+#[cfg(feature = "mcp")]
+fn tool_names(reply: &Value) -> Vec {
+ reply["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap().to_string()).collect()
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_default_lists_every_tool_and_has_no_meta_tools() {
+ let mut s = McpServer::new(Automation::new());
+ let names = tool_names(&rpc(&mut s, 1, "tools/list", json!({})));
+ assert_eq!(names.len(), tools().len());
+ assert!(!names.iter().any(|n| n == "tool_search" || n == "tool_call"));
+ assert!(!rpc(&mut s, 2, "initialize", json!({}))["result"]["instructions"].as_str().unwrap().contains("tool_search"));
+ // Without --compact the meta tools do not exist.
+ assert_eq!(rpc(&mut s, 3, "tools/call", json!({ "name": "tool_search" }))["error"]["code"], -32602);
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_lists_the_core_tools_and_two_meta_tools() {
+ let mut s = McpServer::new(Automation::new()).with_compact(true);
+ let list = rpc(&mut s, 1, "tools/list", json!({}));
+ let mut expected: Vec = pdfcraft_automation::mcp::COMPACT_CORE_TOOLS.iter().map(|n| n.to_string()).collect();
+ expected.extend(["tool_search".to_string(), "tool_call".to_string()]);
+ assert_eq!(tool_names(&list), expected);
+ let all: Vec<&str> = tools().iter().map(|t| t.name).collect();
+ for core in pdfcraft_automation::mcp::COMPACT_CORE_TOOLS {
+ assert!(all.contains(core), "core tool {core} is not in the tool table");
+ }
+ // Core tools are the real definitions, and the list is far smaller than the full one.
+ let full = rpc(&mut McpServer::new(Automation::new()), 2, "tools/list", json!({}));
+ let core_open = list["result"]["tools"][0].clone();
+ assert_eq!(Some(&core_open), full["result"]["tools"].as_array().unwrap().iter().find(|t| t["name"] == "doc_open"));
+ assert!(list.to_string().len() * 5 < full.to_string().len(), "compact {} vs full {}", list.to_string().len(), full.to_string().len());
+ for meta in &list["result"]["tools"].as_array().unwrap()[pdfcraft_automation::mcp::COMPACT_CORE_TOOLS.len()..] {
+ assert_eq!(meta["inputSchema"]["type"], "object");
+ }
+ let instructions = rpc(&mut s, 3, "initialize", json!({}))["result"]["instructions"].as_str().unwrap().to_string();
+ assert!(instructions.contains("tool_search") && instructions.contains("tool_call"), "{instructions}");
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_tool_search_filters_by_query_and_category() {
+ let mut s = McpServer::new(Automation::new()).with_compact(true);
+ let mut search = |args: Value| rpc(&mut s, 1, "tools/call", json!({ "name": "tool_search", "arguments": args }));
+
+ let everything = search(json!({}));
+ assert_eq!(everything["result"]["isError"], false);
+ assert_eq!(everything["result"]["structuredContent"]["count"], tools().len());
+ let first = &everything["result"]["structuredContent"]["tools"][0];
+ assert!(first["name"].is_string() && first["description"].is_string() && first["read_only"].is_boolean(), "{first}");
+
+ let rotate = search(json!({ "query": "ROTATE" }))["result"]["structuredContent"].clone();
+ let names: Vec<&str> = rotate["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap()).collect();
+ assert!(names.contains(&"page_rotate"), "{names:?}");
+ assert!(names.len() < tools().len());
+
+ let docs = search(json!({ "category": "doc" }))["result"]["structuredContent"].clone();
+ let expected = tools().iter().filter(|t| t.name.starts_with("doc_")).count();
+ assert!(expected > 0);
+ assert_eq!(docs["count"], expected);
+ assert!(docs["tools"].as_array().unwrap().iter().all(|t| t["name"].as_str().unwrap().starts_with("doc_") && t["category"] == "doc"));
+
+ let both = search(json!({ "category": "page", "query": "rotate" }))["result"]["structuredContent"].clone();
+ assert!(both["tools"].as_array().unwrap().iter().all(|t| t["name"].as_str().unwrap().starts_with("page_")));
+ assert!(both["tools"].as_array().unwrap().iter().any(|t| t["name"] == "page_rotate"));
+
+ // No match is an empty result that lists the categories, not an error.
+ let none = search(json!({ "category": "nonsense" }));
+ assert_eq!(none["result"]["isError"], false);
+ assert_eq!(none["result"]["structuredContent"]["count"], 0);
+ assert!(none["result"]["structuredContent"]["categories"].as_array().unwrap().iter().any(|c| c == "page"));
+
+ // One tool in full.
+ let one = search(json!({ "name": "page_rotate" }))["result"]["structuredContent"]["tool"].clone();
+ assert_eq!(one["name"], "page_rotate");
+ assert_eq!(one["input_schema"]["type"], "object");
+ let def = tools().into_iter().find(|t| t.name == "page_rotate").unwrap();
+ assert_eq!(one["input_schema"], def.input_schema);
+ assert_eq!(one["description"], def.description);
+
+ // Bad arguments are tool errors.
+ for bad in [json!({ "name": "no_such_tool" }), json!({ "query": 3 }), json!({ "category": ["doc"] }), json!("doc")] {
+ let r = search(bad.clone());
+ assert_eq!(r["result"]["isError"], true, "{bad}");
+ assert!(r["result"]["content"][0]["text"].as_str().is_some_and(|t| !t.is_empty()));
+ }
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_tool_call_dispatches_to_any_tool() {
+ let dir = workdir("mcp-compact");
+ let mut s = compact_server(&dir);
+ let opened = via_tool_call(&mut s, 1, "doc_open", json!({ "path": "a.pdf" }));
+ assert_eq!(opened["result"]["isError"], false);
+ assert_eq!(opened["result"]["structuredContent"]["pages"], 3);
+
+ // A tool outside the core list, through the meta tool.
+ let deleted = via_tool_call(&mut s, 2, "page_delete", json!({ "doc": 1, "pages": [3] }));
+ assert_eq!(deleted["result"]["isError"], false, "{deleted}");
+ assert_eq!(deleted["result"]["structuredContent"]["pages"], 2);
+
+ // The same tool called by name directly still works, and sees the same session.
+ let listed = rpc(&mut s, 3, "tools/call", json!({ "name": "doc_list", "arguments": {} }));
+ assert_eq!(listed["result"]["isError"], false);
+ assert_eq!(listed["result"]["structuredContent"]["documents"][0]["pages"], 2);
+
+ // Images come back as images.
+ let png = via_tool_call(&mut s, 4, "page_render", json!({ "doc": 1, "page": 1, "dpi": 36 }));
+ assert_eq!(png["result"]["content"][0]["type"], "image");
+
+ // `arguments` may be left out for tools that need none.
+ assert_eq!(via_tool_call(&mut s, 5, "doc_list", Value::Null)["result"]["isError"], false);
+ let no_args = rpc(&mut s, 6, "tools/call", json!({ "name": "tool_call", "arguments": { "name": "doc_list" } }));
+ assert_eq!(no_args["result"]["isError"], false);
+
+ // The result equals what the direct call returns.
+ let direct = rpc(&mut s, 7, "tools/call", json!({ "name": "doc_info", "arguments": { "doc": 1 } }));
+ let wrapped = via_tool_call(&mut s, 8, "doc_info", json!({ "doc": 1 }));
+ assert_eq!(direct["result"], wrapped["result"]);
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_tool_call_reports_errors_without_panicking() {
+ let dir = workdir("mcp-compact-errors");
+ let mut s = compact_server(&dir);
+ let text = |r: &Value| r["result"]["content"][0]["text"].as_str().unwrap_or_default().to_string();
+
+ let unknown = via_tool_call(&mut s, 1, "no_such_tool", json!({}));
+ assert_eq!(unknown["result"]["isError"], true);
+ assert!(text(&unknown).contains("no_such_tool") && text(&unknown).contains("tool_search"), "{}", text(&unknown));
+
+ // The tool's own validation errors pass through.
+ let missing = via_tool_call(&mut s, 2, "doc_open", json!({}));
+ assert_eq!(missing["result"]["isError"], true);
+ let outside = via_tool_call(&mut s, 3, "doc_open", json!({ "path": "/definitely/not/here.pdf" }));
+ assert_eq!(outside["result"]["isError"], true);
+ let wrong_type = via_tool_call(&mut s, 4, "page_delete", json!({ "doc": "one", "pages": "all" }));
+ assert_eq!(wrong_type["result"]["isError"], true);
+
+ // Malformed meta-tool arguments.
+ for args in [
+ json!({}),
+ json!({ "name": 7 }),
+ json!({ "name": "doc_list", "arguments": [1] }),
+ json!("doc_list"),
+ Value::Null,
+ json!({ "name": "tool_call" }),
+ json!({ "name": "tool_search" }),
+ ] {
+ let r = rpc(&mut s, 5, "tools/call", json!({ "name": "tool_call", "arguments": args }));
+ assert_eq!(r["result"]["isError"], true, "{args}");
+ assert!(!text(&r).is_empty());
+ }
+
+ // Direct calls keep the usual protocol error for an unknown tool, and the session survives all of it.
+ assert_eq!(rpc(&mut s, 6, "tools/call", json!({ "name": "nope" }))["error"]["code"], -32602);
+ assert_eq!(via_tool_call(&mut s, 7, "doc_open", json!({ "path": "a.pdf" }))["result"]["isError"], false);
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_tool_search_summarizes_the_first_sentence() {
+ let mut s = McpServer::new(Automation::new()).with_compact(true);
+ let mut summary = |tool: &str| {
+ let found = rpc(
+ &mut s,
+ 1,
+ "tools/call",
+ json!({ "name": "tool_search", "arguments": { "query": tool, "category": tool.split('_').next().unwrap() } }),
+ );
+ found["result"]["structuredContent"]["tools"].as_array().unwrap().iter().find(|t| t["name"] == tool).unwrap()["description"]
+ .as_str()
+ .unwrap()
+ .to_string()
+ };
+ // Abbreviations such as "e.g." do not end the summary.
+ assert_eq!(summary("page_number"), "Label a range of pages (e.g. i, ii, iii for front matter, or A-1, A-2 for an appendix).");
+ assert_eq!(
+ summary("accessibility_fix"),
+ "Apply the checker's automatic fix for a rule: primary-language (value: the language, e.g. en-US), title (value: the title; default the current title or file name; also shows it in the title bar) or tab-order (every page tabs in structure order)."
+ );
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_meta_tools_reject_unknown_arguments() {
+ let dir = workdir("mcp-compact-keys");
+ let mut s = compact_server(&dir);
+ let list = rpc(&mut s, 1, "tools/list", json!({}));
+ let metas = &list["result"]["tools"].as_array().unwrap()[pdfcraft_automation::mcp::COMPACT_CORE_TOOLS.len()..];
+ assert_eq!(metas.len(), 2);
+ for meta in metas {
+ assert_eq!(meta["inputSchema"]["additionalProperties"], false, "{}", meta["name"]);
+ }
+ let text = |r: &Value| r["error"]["message"].as_str().or_else(|| r["result"]["content"][0]["text"].as_str()).unwrap_or_default().to_string();
+
+ // A misspelled filter is an error, not an unfiltered listing.
+ let typo = rpc(&mut s, 2, "tools/call", json!({ "name": "tool_search", "arguments": { "qurey": "rotate" } }));
+ assert_eq!(typo["error"]["code"], -32602, "{typo}");
+ assert!(text(&typo).contains("\"qurey\"") && text(&typo).contains("query"), "{}", text(&typo));
+ let extra = rpc(&mut s, 3, "tools/call", json!({ "name": "tool_search", "arguments": { "query": "rotate", "extra": 1 } }));
+ assert_eq!(extra["error"]["code"], -32602, "{extra}");
+ assert!(text(&extra).contains("\"extra\""), "{}", text(&extra));
+
+ // tool_call rejects extra outer keys before running anything.
+ let misspelled =
+ rpc(&mut s, 4, "tools/call", json!({ "name": "tool_call", "arguments": { "name": "doc_open", "argumentz": { "path": "a.pdf" } } }));
+ assert_eq!(misspelled["error"]["code"], -32602, "{misspelled}");
+ assert!(text(&misspelled).contains("\"argumentz\""), "{}", text(&misspelled));
+ let extra = rpc(&mut s, 5, "tools/call", json!({ "name": "tool_call", "arguments": { "name": "doc_list", "unexpected": "value" } }));
+ assert_eq!(extra["error"]["code"], -32602, "{extra}");
+ assert!(text(&extra).contains("\"unexpected\""), "{}", text(&extra));
+ assert_eq!(rpc(&mut s, 6, "tools/call", json!({ "name": "doc_list", "arguments": {} }))["result"]["structuredContent"]["documents"], json!([]));
+
+ // Keys inside "arguments" are left to the target tool, which rejects its unknown ones itself.
+ let inner = via_tool_call(&mut s, 7, "doc_list", json!({ "unexpected": "value" }));
+ assert_eq!(inner["result"]["isError"], true, "{inner}");
+ assert!(text(&inner).contains("doc_list: unknown argument \"unexpected\""), "{}", text(&inner));
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_compact_tool_call_keeps_the_root_confinement() {
+ let root = workdir("mcp-compact-root");
+ let outside_dir = workdir("mcp-compact-outside");
+ let outside = outside_dir.join("a.pdf").to_string_lossy().into_owned();
+ let text = |r: &Value| r["result"]["content"][0]["text"].as_str().unwrap_or_default().to_string();
+
+ // Direct call and tool_call both refuse a real PDF outside the root, with the same words.
+ let mut confined = compact_server(&root);
+ let direct = rpc(&mut confined, 1, "tools/call", json!({ "name": "doc_open", "arguments": { "path": outside } }));
+ assert_eq!(direct["result"]["isError"], true, "{direct}");
+ assert!(text(&direct).contains("is outside the allowed directory"), "{}", text(&direct));
+ let wrapped = via_tool_call(&mut confined, 2, "doc_open", json!({ "path": outside }));
+ assert_eq!(wrapped["result"]["isError"], true, "{wrapped}");
+ assert_eq!(text(&wrapped), text(&direct));
+ // Nothing was opened.
+ let listed = rpc(&mut confined, 3, "tools/call", json!({ "name": "doc_list", "arguments": {} }));
+ assert_eq!(listed["result"]["structuredContent"]["documents"], json!([]));
+
+ // The same file opens through tool_call on a server without a root, so the refusal came from the root.
+ let mut open = McpServer::new(Automation::new()).with_compact(true);
+ let opened = via_tool_call(&mut open, 4, "doc_open", json!({ "path": outside }));
+ assert_eq!(opened["result"]["isError"], false, "{opened}");
+ assert_eq!(opened["result"]["structuredContent"]["pages"], 3);
+
+ // And a file inside the root still opens through the confined server.
+ assert_eq!(via_tool_call(&mut confined, 5, "doc_open", json!({ "path": "a.pdf" }))["result"]["isError"], false);
+}
+
#[test]
fn parallel_text_extraction_keeps_page_order_and_follows_edits() {
let dir = workdir("parallel");
@@ -747,6 +1022,33 @@ fn protecting_through_tools() {
ok(&mut c, "doc_open", json!({ "path": "open.pdf" }));
}
+#[test]
+fn combine_opens_protected_files_with_their_passwords() {
+ let dir = workdir("combine-passwords");
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "a.pdf" }))["doc"].as_u64().unwrap();
+ // Opens with "open"; only "boss" may assemble pages.
+ ok(&mut a, "doc_protect", json!({ "doc": doc, "open_password": "open", "permissions_password": "boss", "changes": "none" }));
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "locked.pdf" }));
+ let combine = |a: &mut Automation, passwords: Value| {
+ a.call("doc_combine", &json!({ "paths": ["locked.pdf", "b.pdf"], "passwords": passwords, "open": true }))
+ };
+ let err = |r: Result<_, ToolError>| match r {
+ Err(ToolError::Failed(m)) => m,
+ Err(other) => panic!("expected a failure, got {other:?}"),
+ Ok(_) => panic!("expected a failure"),
+ };
+ assert!(err(combine(&mut a, Value::Null)).contains("password-protected"));
+ assert!(err(combine(&mut a, json!(["wrong", null]))).contains("password is wrong"));
+ assert!(err(combine(&mut a, json!(["open", null]))).contains("don't allow copying pages"));
+ assert!(matches!(combine(&mut a, json!(["boss"])), Err(ToolError::InvalidArgs(_))), "one per path");
+ let done = ok(&mut a, "doc_combine", json!({ "paths": ["locked.pdf", "b.pdf"], "passwords": ["boss", null], "open": true }));
+ assert!(!done.to_string().contains("boss"), "passwords are never echoed");
+ let out = done["document"]["doc"].as_u64().unwrap();
+ assert_eq!(page_text(&mut a, out), ["Page 1", "Page 2", "Page 3", "Page 1", "Page 2"]);
+ assert_eq!(ok(&mut a, "doc_info", json!({ "doc": out }))["security"]["protected"], false, "the result is not encrypted");
+}
+
/// Restrictions exist only behind a permissions password: open_password alone encrypts and
/// restricts nothing, and asking for a restriction without one is refused rather than ignored (#134).
#[test]
@@ -986,6 +1288,20 @@ fn editing_existing_text_through_tools() {
assert_eq!(p["lines"].as_array().map(Vec::len), Some(2), "{p}");
}
+#[test]
+fn paragraph_bold_without_font_keeps_the_source_family() {
+ let dir = workdir("paragraph-bold");
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "a.pdf" }))["doc"].as_u64().unwrap();
+ ok(&mut a, "text_edit", json!({ "doc": doc, "page": 2, "paragraph": 1, "font": "times" }));
+ let bold = ok(&mut a, "text_edit", json!({ "doc": doc, "page": 2, "paragraph": 1, "bold": true }));
+ assert_eq!(bold["paragraph"]["font"], "Times-Bold");
+ let regular = ok(&mut a, "text_edit", json!({ "doc": doc, "page": 2, "paragraph": 1, "bold": false }));
+ assert_eq!(regular["paragraph"]["font"], "Times-Roman");
+ assert_eq!(regular["paragraph"]["text"], "Page 2");
+ assert!(matches!(a.call("text_edit", &json!({ "doc": doc, "page": 2, "paragraph": 1, "bold": "yes" })), Err(ToolError::InvalidArgs(_))));
+}
+
#[test]
fn editing_page_images_through_tools() {
let dir = workdir("page-images");
@@ -1011,6 +1327,51 @@ fn editing_page_images_through_tools() {
assert!(matches!(a.call("image_edit", &json!({ "doc": made, "page": 1, "image": 1, "action": "delete" })), Err(ToolError::InvalidArgs(_))));
}
+#[test]
+fn editing_form_artwork_through_tools() {
+ use pdfcraft_cos::{Dict, Document, Object, SaveOptions, Stream, write_incremental};
+ let dir = workdir("form-artwork");
+ let mut cos = Document::open(std::sync::Arc::new(fixture(1))).unwrap();
+ let page = pdfcraft_model::pages(&cos)[0].clone();
+ let mut form = Dict::new();
+ form.set(b"Subtype".to_vec(), Object::name("Form"));
+ form.set(b"BBox".to_vec(), Object::Array([0, 0, 80, 40].map(Object::Int).to_vec()));
+ let artwork = cos.add(Object::Stream(Stream::flate(form, b"0.2 0.5 0.9 rg 0 0 80 40 re f")));
+ let contents = cos.add(Object::Stream(Stream::flate(Dict::new(), b"q 1 0 0 1 20 240 cm /Figure Do Q")));
+ cos.update_dict(page.obj, |d| {
+ d.set(b"Contents".to_vec(), Object::Ref(contents));
+ let mut xo = Dict::new();
+ xo.set(b"Figure".to_vec(), Object::Ref(artwork));
+ let mut resources = Dict::new();
+ resources.set(b"XObject".to_vec(), Object::Dict(xo));
+ d.set(b"Resources".to_vec(), Object::Dict(resources));
+ })
+ .unwrap();
+ std::fs::write(dir.join("figure.pdf"), write_incremental(&cos, &SaveOptions::default()).unwrap()).unwrap();
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({"path": "figure.pdf"}))["doc"].as_u64().unwrap();
+ let before = ok(&mut a, "page_images", json!({"doc": doc, "page": 1}))["images"][0].clone();
+ assert_eq!(before["kind"], "form");
+ assert_eq!(before["pixels"], json!([0, 0]));
+ assert_eq!(before["rect"], json!([20.0, 20.0, 100.0, 60.0]));
+ let rendered_before = a.call("page_render", &json!({"doc": doc, "page": 1, "dpi": 72})).unwrap();
+ assert!(a.call("image_save", &json!({"doc": doc, "page": 1, "image": 1, "path": "out/figure"})).is_err());
+ ok(&mut a, "image_edit", json!({"doc": doc, "page": 1, "image": 1, "action": "move", "rect": [40, 50, 120, 90]}));
+ assert_eq!(ok(&mut a, "page_images", json!({"doc": doc, "page": 1}))["images"][0]["rect"], json!([40.0, 50.0, 120.0, 90.0]));
+ let rendered_moved = a.call("page_render", &json!({"doc": doc, "page": 1, "dpi": 72})).unwrap();
+ assert_ne!(rendered_before, rendered_moved, "the rendered artwork actually moves");
+ ok(&mut a, "doc_save", json!({"doc": doc, "path": "out/moved.pdf"}));
+ let re = ok(&mut a, "doc_open", json!({"path": "out/moved.pdf"}))["doc"].as_u64().unwrap();
+ assert_eq!(ok(&mut a, "page_images", json!({"doc": re, "page": 1}))["images"][0]["rect"], json!([40.0, 50.0, 120.0, 90.0]));
+ ok(&mut a, "image_edit", json!({"doc": re, "page": 1, "image": 1, "action": "delete"}));
+ assert_eq!(ok(&mut a, "page_images", json!({"doc": re, "page": 1}))["count"], 0);
+ ok(&mut a, "edit_undo", json!({"doc": re}));
+ assert_eq!(ok(&mut a, "page_images", json!({"doc": re, "page": 1}))["count"], 1);
+ ok(&mut a, "edit_undo", json!({"doc": doc}));
+ assert_eq!(ok(&mut a, "page_images", json!({"doc": doc, "page": 1}))["images"][0], before);
+ assert_eq!(a.call("page_render", &json!({"doc": doc, "page": 1, "dpi": 72})).unwrap(), rendered_before);
+}
+
#[test]
fn auditing_space_through_tools() {
let dir = workdir("audit");
@@ -1064,6 +1425,136 @@ fn fill_and_sign_through_tools() {
assert!(matches!(a.call("fill_sign_add", &json!({ "doc": doc, "page": 1, "type": "text", "at": [1, 1] })), Err(ToolError::InvalidArgs(_))));
}
+#[test]
+fn image_signatures_through_tools_preserve_transparency_and_survive_save() {
+ let dir = workdir("image-signatures");
+ let mut png = Vec::new();
+ {
+ let mut encoder = png::Encoder::new(&mut png, 120, 40);
+ encoder.set_color(png::ColorType::Rgba);
+ encoder.set_depth(png::BitDepth::Eight);
+ let rgba: Vec = (0..40)
+ .flat_map(|y| (0..120).flat_map(move |x| if (40..80).contains(&x) && (10..30).contains(&y) { [0, 0, 0, 255] } else { [0, 0, 0, 0] }))
+ .collect();
+ encoder.write_header().unwrap().write_image_data(&rgba).unwrap();
+ }
+ std::fs::write(dir.join("signature.png"), png).unwrap();
+ std::fs::write(dir.join("broken.png"), b"broken").unwrap();
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_create", json!({ "from": "blank", "width": 200, "height": 300 }))["doc"].as_u64().unwrap();
+ for (kind, y) in [("signature", 60), ("initials", 120)] {
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": 1, "type": kind, "at": [20, y], "path": "signature.png" }));
+ }
+ let render = |a: &mut Automation, doc| {
+ let output = a.call("page_render", &json!({ "doc": doc, "page": 1, "dpi": 72 })).unwrap();
+ let Content::Png { data, .. } = &output[0] else { panic!() };
+ image::load_from_memory(data).unwrap().to_rgba8()
+ };
+ let before = render(&mut a, doc);
+ assert_eq!(before.get_pixel(25, 60).0, [255, 255, 255, 255], "transparent margin exposes the page");
+ assert_eq!(before.get_pixel(65, 60).0, [0, 0, 0, 255], "signature ink is embedded");
+ assert_eq!(ok(&mut a, "edit_undo", json!({ "doc": doc }))["undone"], "Add initials");
+ assert_eq!(ok(&mut a, "comment_list", json!({ "doc": doc }))["count"], 1);
+ ok(&mut a, "edit_redo", json!({ "doc": doc }));
+ // The same resize edit the selection handles use must keep the imported appearance.
+ for rect in [json!([20, 40, 20, 88]), json!([20, 40, 100000000, 88])] {
+ assert!(a.call("comment_edit", &json!({ "doc": doc, "page": 1, "index": 1, "rect": rect })).is_err());
+ }
+ ok(&mut a, "comment_lock", json!({ "doc": doc, "page": 1, "index": 1 }));
+ assert!(a.call("comment_edit", &json!({ "doc": doc, "page": 1, "index": 1, "rect": [20, 40, 164, 88] })).is_err());
+ ok(&mut a, "comment_lock", json!({ "doc": doc, "page": 1, "index": 1, "locked": false }));
+ assert_eq!(render(&mut a, doc), before, "invalid and locked resizes leave the image intact");
+ ok(&mut a, "comment_edit", json!({ "doc": doc, "page": 1, "index": 1, "rect": [20, 40, 164, 88] }));
+ let resized = render(&mut a, doc);
+ assert_eq!(resized.get_pixel(110, 64).0, [0, 0, 0, 255], "resizing scales the original ink");
+ assert_eq!(resized.get_pixel(25, 64).0, [255, 255, 255, 255], "resizing retains alpha");
+ assert_eq!(ok(&mut a, "edit_undo", json!({ "doc": doc }))["undone"], "Resize comment");
+ assert_eq!(render(&mut a, doc), before);
+ ok(&mut a, "edit_redo", json!({ "doc": doc }));
+ assert_eq!(render(&mut a, doc), resized);
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "signed.pdf" }));
+ let reopened = ok(&mut a, "doc_open", json!({ "path": "signed.pdf" }))["doc"].as_u64().unwrap();
+ assert_eq!(ok(&mut a, "comment_list", json!({ "doc": reopened }))["count"], 2);
+ assert_eq!(render(&mut a, reopened), resized, "resized appearances retain alpha and geometry after save");
+ for args in [
+ json!({ "type": "signature", "path": "broken.png" }),
+ json!({ "type": "signature", "path": "signature.png", "text": "Ada" }),
+ json!({ "type": "check", "path": "signature.png" }),
+ json!({ "type": "signature", "path": "../outside.png" }),
+ ] {
+ let mut args = args;
+ args["doc"] = json!(doc);
+ args["page"] = json!(1);
+ args["at"] = json!([20, 80]);
+ assert!(a.call("fill_sign_add", &args).is_err(), "{args}");
+ }
+ assert_eq!(ok(&mut a, "comment_list", json!({ "doc": doc }))["count"], 2, "errors leave the PDF intact");
+}
+
+#[test]
+fn image_signature_preview_layers_are_read_only_and_survive_encrypted_save() {
+ let dir = workdir("signature-preview");
+ let mut png = Vec::new();
+ {
+ let mut encoder = png::Encoder::new(&mut png, 120, 40);
+ encoder.set_color(png::ColorType::Rgba);
+ encoder.set_depth(png::BitDepth::Eight);
+ let rgba: Vec = (0..40)
+ .flat_map(|y| (0..120).flat_map(move |x| if (40..80).contains(&x) && (10..30).contains(&y) { [20, 40, 60, 128] } else { [0, 0, 0, 0] }))
+ .collect();
+ encoder.write_header().unwrap().write_image_data(&rgba).unwrap();
+ }
+ std::fs::write(dir.join("signature.png"), png).unwrap();
+ std::fs::write(dir.join("form.pdf"), fixture(1)).unwrap();
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "form.pdf" }))["doc"].as_u64().unwrap();
+ ok(&mut a, "page_rotate", json!({ "doc": doc, "pages": [1], "degrees": 90 }));
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": 1, "type": "initials", "at": [20, 40], "path": "signature.png" }));
+ let background = a.call("page_render", &json!({ "doc": doc, "page": 1, "dpi": 72 })).unwrap();
+ let Content::Png { data: expected, .. } = &background[0] else { panic!() };
+ let expected = image::load_from_memory(expected).unwrap().to_rgba8();
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": 1, "type": "signature", "at": [120, 100], "path": "signature.png" }));
+ ok(&mut a, "comment_edit", json!({ "doc": doc, "page": 1, "index": 2, "opacity": 0.5 }));
+ ok(&mut a, "doc_protect", json!({ "doc": doc, "open_password": "preview-test" }));
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "signed.pdf" }));
+ let reopened = ok(&mut a, "doc_open", json!({ "path": "signed.pdf", "password": "preview-test" }))["doc"].as_u64().unwrap();
+ for doc in [doc, reopened] {
+ let before = ok(&mut a, "doc_info", json!({ "doc": doc }));
+ let d = a.session().docs().iter().find(|d| d.id.0 == doc).unwrap();
+ let generation = d.edit_generation();
+ let bytes = d.bytes.clone();
+ let output = a.call("comment_image_preview", &json!({ "doc": doc, "page": 1, "index": 2, "dpi": 72 })).unwrap();
+ let [Content::Json(meta), Content::Png { data: background, .. }] = output.as_slice() else { panic!("labeled background layer") };
+ let image = a.call("comment_image_preview", &json!({ "doc": doc, "page": 1, "index": 2, "layer": "image" })).unwrap();
+ let [Content::Json(image_meta), Content::Png { data: signature, width, height }] = image.as_slice() else { panic!("labeled image layer") };
+ assert_eq!(meta["layer"], "background");
+ assert_eq!(image_meta["layer"], "image");
+ assert_eq!(meta["rotation"], 90);
+ assert_eq!(meta["image_rotation"], 0, "placed upright as displayed on the turned page");
+ assert_eq!(meta["opacity"], 0.5);
+ assert_eq!((*width, *height), (120, 40));
+ assert_eq!(image::load_from_memory(background).unwrap().to_rgba8(), expected, "page text and the other signature remain");
+ let signature = image::load_from_memory(signature).unwrap().to_rgba8();
+ assert_eq!(signature.get_pixel(5, 20).0[3], 0);
+ assert_eq!(signature.get_pixel(60, 20).0, [20, 40, 60, 128], "embedded alpha and colour survive reopen");
+ assert_eq!(ok(&mut a, "doc_info", json!({ "doc": doc })), before);
+ let d = a.session().docs().iter().find(|d| d.id.0 == doc).unwrap();
+ assert_eq!(d.edit_generation(), generation);
+ assert!(std::sync::Arc::ptr_eq(&bytes, &d.bytes));
+ assert!(d.image_signature_preview(0, 1).unwrap().unwrap().render_background(f32::NAN).is_err());
+ assert!(d.image_signature_preview(0, 999).is_err());
+ }
+ assert!(tools().iter().find(|t| t.name == "comment_image_preview").unwrap().read_only);
+ for dpi in [0, 601] {
+ assert!(matches!(
+ a.call("comment_image_preview", &json!({ "doc": reopened, "page": 1, "index": 2, "dpi": dpi })),
+ Err(ToolError::InvalidArgs(_))
+ ));
+ }
+ ok(&mut a, "fill_sign_add", json!({ "doc": reopened, "page": 1, "type": "check", "at": [10, 10] }));
+ assert!(a.call("comment_image_preview", &json!({ "doc": reopened, "page": 1, "index": 3 })).is_err());
+}
+
#[test]
fn creating_and_reducing_through_tools() {
let dir = workdir("create");
@@ -1079,6 +1570,62 @@ fn creating_and_reducing_through_tools() {
assert!(matches!(a.call("doc_create", &json!({ "from": "images", "paths": ["notes.txt"] })), Err(ToolError::Failed(_))));
}
+#[test]
+fn creating_from_multiple_files_through_tools() {
+ let dir = workdir("create-multiple");
+ let mut png = Vec::new();
+ {
+ let mut enc = png::Encoder::new(&mut png, 4, 2);
+ enc.set_color(png::ColorType::Rgb);
+ enc.set_depth(png::BitDepth::Eight);
+ enc.write_header().unwrap().write_image_data(&[100; 4 * 2 * 3]).unwrap();
+ }
+ std::fs::write(dir.join("scan.png"), png).unwrap();
+ std::fs::write(dir.join("notes.txt"), "hello").unwrap();
+ std::fs::write(dir.join("report.docx"), b"PK\x03\x04").unwrap();
+ let mut a = auto(&dir);
+
+ // Combine: every file converted, in the order given, with a bookmark per file.
+ let made = ok(
+ &mut a,
+ "doc_create_multiple",
+ json!({ "paths": ["notes.txt", "a.pdf", "scan.png"], "pages": [null, "3", null], "out": "all.pdf", "open": true }),
+ );
+ let doc = made["document"]["doc"].as_u64().unwrap();
+ assert_eq!(page_text(&mut a, doc), ["hello", "Page 3", ""]);
+ let titles: Vec = ok(&mut a, "bookmark_list", json!({ "doc": doc }))["bookmarks"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|b| b["title"].as_str().unwrap().to_string())
+ .collect();
+ assert_eq!(titles, ["notes", "a", "scan"]);
+ assert!(dir.join("all.pdf").is_file());
+ // A file that can't be converted fails the whole combine, naming it.
+ let err = a.call("doc_create_multiple", &json!({ "paths": ["a.pdf", "report.docx"] })).unwrap_err();
+ assert!(matches!(&err, ToolError::Failed(m) if m.contains("report.docx") && m.contains("can't be converted")), "{err}");
+ assert!(matches!(a.call("doc_create_multiple", &json!({ "paths": [] })), Err(ToolError::InvalidArgs(_))));
+ assert!(matches!(a.call("doc_create_multiple", &json!({ "paths": ["a.pdf"], "mode": "zip" })), Err(ToolError::InvalidArgs(_))));
+ assert!(matches!(a.call("doc_create_multiple", &json!({ "paths": ["a.pdf"], "mode": "separate" })), Err(ToolError::InvalidArgs(_))));
+
+ // Separate: one PDF per file; PDFs are skipped, a bad file doesn't stop the rest, and an
+ // existing file is never overwritten.
+ std::fs::create_dir_all(dir.join("out")).unwrap();
+ std::fs::write(dir.join("out/notes.pdf"), b"mine").unwrap();
+ let args = json!({ "paths": ["notes.txt", "report.docx", "a.pdf", "scan.png", "missing.txt"], "mode": "separate", "out_dir": "out" });
+ let made = ok(&mut a, "doc_create_multiple", args);
+ let files = made["files"].as_array().unwrap();
+ assert!(files[0]["output"].as_str().unwrap().ends_with("notes (2).pdf"), "{files:?}");
+ assert!(files[1]["error"].as_str().unwrap().contains("can't be converted"));
+ assert_eq!(files[2]["skipped"], "already a PDF");
+ assert!(files[3]["output"].as_str().unwrap().ends_with("scan.pdf"));
+ assert!(files[4]["error"].is_string());
+ assert_eq!(std::fs::read(dir.join("out/notes.pdf")).unwrap(), b"mine");
+ let reopened = ok(&mut a, "doc_open", json!({ "path": "out/notes (2).pdf" }))["doc"].as_u64().unwrap();
+ assert_eq!(page_text(&mut a, reopened), ["hello"]);
+ assert!(!dir.join("out/a.pdf").exists());
+}
+
#[test]
fn creating_images_with_dpi_through_tools() {
let dir = workdir("image-dpi");
@@ -1196,6 +1743,34 @@ fn preparing_a_form_through_tools() {
assert!(matches!(a.call("form_set_image", &json!({ "doc": doc, "field": "size", "path": "pics/a_page_1.png" })), Err(ToolError::Failed(_))));
}
+#[test]
+fn rotating_a_field_through_tools() {
+ let dir = workdir("rotate-field");
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "a.pdf" }))["doc"].as_u64().unwrap();
+ ok(&mut a, "form_add_field", json!({ "doc": doc, "page": 1, "type": "text", "rect": [20, 20, 180, 42], "name": "City" }));
+ let rect_of = |a: &mut Automation| {
+ let f = &ok(a, "form_fields", json!({ "doc": doc }))["fields"][0];
+ (f["rotation"].as_i64().unwrap(), f["rect"].as_array().unwrap().iter().map(|v| v.as_f64().unwrap()).collect::>())
+ };
+ let (rot, before) = rect_of(&mut a);
+ assert_eq!(rot, 0);
+ assert!(matches!(a.call("form_set_props", &json!({ "doc": doc, "field": "City", "rotation": 45 })), Err(ToolError::InvalidArgs(_))));
+ assert_eq!(rect_of(&mut a).1, before, "a rejected rotation changes nothing");
+ ok(&mut a, "form_set_props", json!({ "doc": doc, "field": "City", "rotation": 90 }));
+ let (rot, turned) = rect_of(&mut a);
+ assert_eq!(rot, 90);
+ let (bw, bh) = (before[2] - before[0], before[3] - before[1]);
+ let (tw, th) = (turned[2] - turned[0], turned[3] - turned[1]);
+ assert!((tw - bh).abs() < 0.2 && (th - bw).abs() < 0.2, "swapped {before:?} -> {turned:?}");
+ let center = |r: &[f64]| ((r[0] + r[2]) / 2.0, (r[1] + r[3]) / 2.0);
+ let (bc, tc) = (center(&before), center(&turned));
+ assert!((bc.0 - tc.0).abs() < 0.2 && (bc.1 - tc.1).abs() < 0.2, "center moved {bc:?} -> {tc:?}");
+ assert_eq!(ok(&mut a, "edit_undo", json!({ "doc": doc }))["undone"], "Change field properties");
+ let (rot, back) = rect_of(&mut a);
+ assert_eq!((rot, back), (0, before));
+}
+
#[test]
fn redacting_through_tools() {
let dir = workdir("redact");
@@ -1381,6 +1956,47 @@ fn comments_and_form_data_travel_as_xfdf_fdf_and_text() {
assert_eq!(r["undo"], "Import all.xfdf");
}
+#[test]
+fn natural_image_stamps_through_tools_on_rotated_pages() {
+ for degrees in [0, 90, 180, 270] {
+ let dir = workdir(&format!("natural-stamps-{degrees}"));
+ let mut bytes = Vec::new();
+ {
+ let mut encoder = png::Encoder::new(&mut bytes, 80, 40);
+ encoder.set_color(png::ColorType::Rgb);
+ encoder.set_depth(png::BitDepth::Eight);
+ let pixels: Vec = (0..40)
+ .flat_map(|y| {
+ (0..80).flat_map(move |x| {
+ [[240, 20, 20], [20, 180, 20], [20, 20, 240], [230, 180, 20]][usize::from(y >= 20) * 2 + usize::from(x >= 40)]
+ })
+ })
+ .collect();
+ encoder.write_header().unwrap().write_image_data(&pixels).unwrap();
+ }
+ std::fs::write(dir.join("quadrants.png"), bytes).unwrap();
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({"path":"a.pdf"}))["doc"].as_u64().unwrap();
+ ok(&mut a, "page_rotate", json!({"doc":doc,"pages":[1],"degrees":degrees}));
+ ok(&mut a, "stamp_custom", json!({"doc":doc,"page":1,"path":"quadrants.png","at":[100,100]}));
+ let rendered = a.call("page_render", &json!({"doc":doc,"page":1,"dpi":72})).unwrap();
+ let Content::Png { data, .. } = &rendered[0] else { panic!("expected PNG") };
+ let mut reader = png::Decoder::new(std::io::Cursor::new(data)).read_info().unwrap();
+ let mut pixels = vec![0; reader.output_buffer_size().unwrap()];
+ let info = reader.next_frame(&mut pixels).unwrap();
+ assert_eq!(info.color_type, png::ColorType::Rgba);
+ for ((x, y), colour) in [(80, 90), (120, 90), (80, 110), (120, 110)].into_iter().zip([
+ [240, 20, 20, 255],
+ [20, 180, 20, 255],
+ [20, 20, 240, 255],
+ [230, 180, 20, 255],
+ ]) {
+ let offset = ((y * info.width + x) * 4) as usize;
+ assert_eq!(&pixels[offset..offset + 4], &colour, "page rotation {degrees}");
+ }
+ }
+}
+
#[test]
fn stamps_through_tools() {
let dir = workdir("stamps");
@@ -1539,6 +2155,112 @@ fn note_icons_anchor_at_the_requested_corner_on_rotated_pages() {
}
}
+/// An image signature is drawn upright as displayed, and anchored at the displayed point asked
+/// for, on every `/Rotate`: its picture is placed in user space, which the page turns, so the
+/// appearance is counter-rotated and its box is found in user space.
+#[test]
+fn image_signatures_stay_upright_on_rotated_pages() {
+ let dir = workdir("image-upright");
+ // 80 x 40 px, one colour per quadrant: red and green above, blue and yellow below.
+ let quadrants = image::RgbaImage::from_fn(80, 40, |x, y| match (x < 40, y < 20) {
+ (true, true) => image::Rgba([255, 0, 0, 255]),
+ (false, true) => image::Rgba([0, 255, 0, 255]),
+ (true, false) => image::Rgba([0, 0, 255, 255]),
+ (false, false) => image::Rgba([255, 255, 0, 255]),
+ });
+ quadrants.save(dir.join("quadrants.png")).unwrap();
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_create", json!({ "from": "blank", "width": 200, "height": 300, "pages": 4 }))["doc"].as_u64().unwrap();
+ for (page, degrees) in [(2, 90), (3, 180), (4, 270)] {
+ ok(&mut a, "page_rotate", json!({ "doc": doc, "pages": [page], "degrees": degrees }));
+ }
+ for page in 1..=4 {
+ // 64 x 32 pt from x = 60 as displayed, centred on y = 140.
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": page, "type": "signature", "at": [60, 140], "path": "quadrants.png" }));
+ }
+ let (white, red, green, blue, yellow) = ([255, 255, 255], [255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 0]);
+ let check = |a: &mut Automation, doc: u64| {
+ for page in 1..=4 {
+ let output = a.call("page_render", &json!({ "doc": doc, "page": page, "dpi": 72 })).unwrap();
+ let Content::Png { data, .. } = &output[0] else { panic!() };
+ let pixels = image::load_from_memory(data).unwrap().to_rgba8();
+ for (x, y, want, what) in [
+ (76, 132, red, "signature top-left"),
+ (108, 132, green, "signature top-right"),
+ (76, 148, blue, "signature bottom-left"),
+ (108, 148, yellow, "signature bottom-right"),
+ (56, 140, white, "left of the signature"),
+ (128, 140, white, "right of the signature"),
+ (92, 120, white, "above the signature"),
+ (92, 160, white, "below the signature"),
+ ] {
+ let got = pixels.get_pixel(x, y).0;
+ assert!(got[..3].iter().zip(want).all(|(g, w)| g.abs_diff(w) < 12), "page {page}, {what} at ({x}, {y}): {got:?}, want {want:?}");
+ }
+ }
+ };
+ check(&mut a, doc);
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "placed.pdf" }));
+ let reopened = ok(&mut a, "doc_open", json!({ "path": "placed.pdf" }))["doc"].as_u64().unwrap();
+ check(&mut a, reopened);
+}
+
+/// Issue #299: a typed signature and initials read across, as displayed, on every `/Rotate`,
+/// anchored at the displayed point, and look the same as on an unturned page.
+#[test]
+fn typed_signatures_stay_upright_on_rotated_pages() {
+ let dir = workdir("typed-upright");
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_create", json!({ "from": "blank", "width": 200, "height": 300, "pages": 4 }))["doc"].as_u64().unwrap();
+ for (page, degrees) in [(2, 90), (3, 180), (4, 270)] {
+ ok(&mut a, "page_rotate", json!({ "doc": doc, "pages": [page], "degrees": degrees }));
+ }
+ for page in 1..=4 {
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": page, "type": "signature", "at": [30, 60], "text": "Ada Lovelace" }));
+ ok(&mut a, "fill_sign_add", json!({ "doc": doc, "page": page, "type": "initials", "at": [30, 140], "text": "AL" }));
+ }
+ let check = |a: &mut Automation, doc: u64| {
+ let mut upright = Vec::new();
+ for page in 1..=4 {
+ let output = a.call("page_render", &json!({ "doc": doc, "page": page, "dpi": 72 })).unwrap();
+ let Content::Png { data, .. } = &output[0] else { panic!() };
+ let pixels = image::load_from_memory(data).unwrap().to_rgba8();
+ assert_eq!(pixels.dimensions(), if page % 2 == 1 { (200, 300) } else { (300, 200) }, "page {page}");
+ let dark: Vec = pixels.pixels().map(|p| p.0[..3].iter().all(|v| *v < 128)).collect();
+ for y in [60, 140] {
+ let mut b = [u32::MAX, u32::MAX, 0, 0];
+ for (x, py, p) in pixels.enumerate_pixels() {
+ if py.abs_diff(y) < 40 && p.0[..3].iter().all(|v| *v < 128) {
+ b = [b[0].min(x), b[1].min(py), b[2].max(x), b[3].max(py)];
+ }
+ }
+ assert!(b[0] <= b[2], "page {page}: no ink near y = {y}");
+ assert!(b[2] - b[0] > b[3] - b[1], "page {page}: the name reads across: {b:?}");
+ assert!(b[0].abs_diff(30) <= 2 && b[1] < y && b[3] > y, "page {page}: anchored at (30, {y}): {b:?}");
+ }
+ if page == 1 {
+ upright = dark;
+ continue;
+ }
+ // Same pixels as the unturned page where both pages are (pages 2 and 4 are wider).
+ let width = pixels.width();
+ let (mut differ, mut ink) = (0, 0);
+ for y in 0..200 {
+ for x in 0..200 {
+ let (want, got) = (upright[(y * 200 + x) as usize], dark[(y * width + x) as usize]);
+ ink += usize::from(want);
+ differ += usize::from(want != got);
+ }
+ }
+ assert!(differ * 10 < ink, "page {page}: {differ} of {ink} ink pixels differ from the unturned page");
+ }
+ };
+ check(&mut a, doc);
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "placed.pdf" }));
+ let reopened = ok(&mut a, "doc_open", json!({ "path": "placed.pdf" }))["doc"].as_u64().unwrap();
+ check(&mut a, reopened);
+}
+
#[test]
fn comment_checkmarks_locks_hiding_and_summaries_through_tools() {
let dir = workdir("comment-polish");
@@ -1570,6 +2292,72 @@ fn comment_checkmarks_locks_hiding_and_summaries_through_tools() {
assert!(matches!(a.call("comments_summarize", &json!({ "doc": doc, "sort": "colour" })), Err(ToolError::InvalidArgs(_))));
}
+#[test]
+fn line_endings_through_the_tool() {
+ let dir = workdir("endings");
+ let mut a = auto(&dir);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "a.pdf" }))["doc"].as_u64().unwrap();
+ ok(&mut a, "comment_add", json!({ "doc": doc, "page": 1, "type": "line", "from": [20, 40], "to": [120, 80], "endings": ["None", "Diamond"] }));
+ ok(
+ &mut a,
+ "comment_add",
+ json!({ "doc": doc, "page": 1, "type": "polyline", "points": [[20, 120], [60, 100], [100, 140]], "endings": ["Circle", "Slash"] }),
+ );
+ ok(
+ &mut a,
+ "comment_add",
+ json!({ "doc": doc, "page": 1, "type": "callout", "rect": [110, 200, 190, 240], "to": [40, 160], "contents": "Look", "endings": ["Square"] }),
+ );
+ assert!(matches!(
+ a.call("comment_add", &json!({ "doc": doc, "page": 1, "type": "line", "from": [20, 40], "to": [120, 80], "endings": ["Sparkle", "None"] })),
+ Err(ToolError::InvalidArgs(_))
+ ));
+ assert!(matches!(
+ a.call(
+ "comment_add",
+ &json!({ "doc": doc, "page": 1, "type": "callout", "rect": [10, 10, 80, 40], "to": [90, 80], "endings": ["None", "None"] })
+ ),
+ Err(ToolError::InvalidArgs(_))
+ ));
+ assert!(matches!(
+ a.call("comment_add", &json!({ "doc": doc, "page": 1, "type": "rectangle", "rect": [10, 10, 40, 40], "endings": ["Circle"] })),
+ Err(ToolError::InvalidArgs(_))
+ ));
+ ok(&mut a, "doc_save", json!({ "doc": doc, "path": "ended.pdf" }));
+ let saved = pdfcraft_cos::Document::open(std::sync::Arc::new(std::fs::read(dir.join("ended.pdf")).unwrap())).unwrap();
+ for name in [b"Diamond".as_slice(), b"Circle", b"Slash", b"Square"] {
+ assert!(
+ saved.object_numbers().iter().any(|n| saved.try_get(*n).ok().is_some_and(|o| object_has_name(&o, name))),
+ "missing /{}",
+ String::from_utf8_lossy(name)
+ );
+ }
+ let drawn: Vec = saved
+ .object_numbers()
+ .into_iter()
+ .filter_map(|n| {
+ let obj = saved.try_get(n).ok()?;
+ let pdfcraft_cos::Object::Stream(s) = &*obj else { return None };
+ if s.dict.name(b"Subtype") != Some(b"Form") {
+ return None;
+ }
+ s.decoded().ok().map(|b| String::from_utf8_lossy(&b).into_owned())
+ })
+ .collect();
+ assert!(drawn.iter().any(|s| s.contains("h B")), "a filled ending was drawn: {drawn:?}");
+ assert!(drawn.iter().any(|s| s.contains(" l S")), "an open ending was drawn: {drawn:?}");
+}
+
+fn object_has_name(obj: &pdfcraft_cos::Object, name: &[u8]) -> bool {
+ match obj {
+ pdfcraft_cos::Object::Name(n) => n.as_slice() == name,
+ pdfcraft_cos::Object::Array(items) => items.iter().any(|o| object_has_name(o, name)),
+ pdfcraft_cos::Object::Dict(d) => d.iter().any(|(_, o)| object_has_name(o, name)),
+ pdfcraft_cos::Object::Stream(s) => s.dict.iter().any(|(_, o)| object_has_name(o, name)),
+ _ => false,
+ }
+}
+
#[test]
fn drawing_comments_through_tools() {
let dir = workdir("drawing");
@@ -2313,3 +3101,211 @@ mod close_argument_tests {
assert_eq!(std::fs::read(dir.0.join("a.pdf")).unwrap(), source);
}
}
+
+mod combine_argument_tests {
+ use super::*;
+ use std::sync::atomic::{AtomicU64, Ordering};
+
+ // Own only a newly created directory; the bounded runner provides project-local TMPDIR.
+ struct CombineDir(PathBuf);
+
+ impl CombineDir {
+ fn new() -> Self {
+ static NEXT: AtomicU64 = AtomicU64::new(0);
+ let parent = std::env::temp_dir();
+ for _ in 0..128 {
+ let serial = NEXT.fetch_add(1, Ordering::Relaxed);
+ let path = parent.join(format!("pdfcraft-combine-{}-{serial}", std::process::id()));
+ match std::fs::create_dir(&path) {
+ Ok(()) => {
+ let dir = Self(path);
+ std::fs::write(dir.0.join("a.pdf"), fixture(3)).unwrap();
+ std::fs::write(dir.0.join("b.pdf"), fixture(2)).unwrap();
+ return dir;
+ }
+ Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+ Err(error) => panic!("creating combine test directory: {error}"),
+ }
+ }
+ panic!("no unused combine test directory after 128 attempts");
+ }
+ }
+
+ impl Drop for CombineDir {
+ fn drop(&mut self) {
+ let _ = std::fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn invalid_combine_selectors_preserve_outputs_inputs_and_open_documents() {
+ let dir = CombineDir::new();
+ let first = std::fs::read(dir.0.join("a.pdf")).unwrap();
+ let second = std::fs::read(dir.0.join("b.pdf")).unwrap();
+ let sentinel = b"existing destination";
+ std::fs::write(dir.0.join("combined.pdf"), sentinel).unwrap();
+ let mut a = auto(&dir.0);
+ let doc = ok(&mut a, "doc_open", json!({ "path": "a.pdf" }))["doc"].as_u64().unwrap();
+ ok(&mut a, "doc_set_info", json!({ "doc": doc, "key": "Title", "value": "Unsaved title" }));
+ ok(&mut a, "doc_open", json!({ "path": "b.pdf" }));
+ let list = ok(&mut a, "doc_list", json!({}));
+ let info = ok(&mut a, "doc_info", json!({ "doc": doc }));
+ let text = page_text(&mut a, doc);
+ let bytes = a.session().get(pdfcraft_engine::DocId(doc)).unwrap().bytes.clone();
+ for invalid in [json!(1), json!(true), json!({ "page": 1 }), json!(["1"])] {
+ for (index, pages) in [json!([invalid, null]), json!([null, invalid])].into_iter().enumerate() {
+ for out in ["combined.pdf", "not-created.pdf"] {
+ let error = a.call("doc_combine", &json!({ "paths": ["a.pdf", "b.pdf"], "pages": pages, "out": out, "open": true })).unwrap_err();
+ assert!(
+ matches!(error, ToolError::InvalidArgs(ref message) if message == &format!("pages[{index}] must be a range string or null"))
+ );
+ assert_eq!(std::fs::read(dir.0.join("combined.pdf")).unwrap(), sentinel);
+ assert!(!dir.0.join("not-created.pdf").exists());
+ assert_eq!(ok(&mut a, "doc_list", json!({})), list);
+ assert_eq!(ok(&mut a, "doc_info", json!({ "doc": doc })), info);
+ assert_eq!(page_text(&mut a, doc), text);
+ assert_eq!(a.session().get(pdfcraft_engine::DocId(doc)).unwrap().bytes, bytes);
+ assert_eq!(std::fs::read(dir.0.join("a.pdf")).unwrap(), first);
+ assert_eq!(std::fs::read(dir.0.join("b.pdf")).unwrap(), second);
+ }
+ }
+ }
+ let error = a
+ .call("doc_combine", &json!({ "paths": ["missing-a.pdf", "missing-b.pdf"], "pages": [null, false], "out": "not-created.pdf" }))
+ .unwrap_err();
+ assert!(matches!(error, ToolError::InvalidArgs(ref message) if message == "pages[1] must be a range string or null"));
+ assert_eq!(ok(&mut a, "doc_list", json!({})), list);
+ assert_eq!(std::fs::read_dir(&dir.0).unwrap().count(), 3, "no output or staging files are created");
+ }
+
+ #[test]
+ fn valid_combine_selectors_keep_all_pages_and_selected_order_after_reopen() {
+ let dir = CombineDir::new();
+ let first = std::fs::read(dir.0.join("a.pdf")).unwrap();
+ let second = std::fs::read(dir.0.join("b.pdf")).unwrap();
+ let mut a = auto(&dir.0);
+ let all = vec!["Page 1", "Page 2", "Page 3", "Page 1", "Page 2"];
+ for (pages, expected) in [
+ (None, all.clone()),
+ (Some(Value::Null), all.clone()),
+ (Some(json!([null, null])), all.clone()),
+ (Some(json!(["", null])), all),
+ (Some(json!(["3, 1", null])), vec!["Page 3", "Page 1", "Page 1", "Page 2"]),
+ (Some(json!([null, "2"])), vec!["Page 1", "Page 2", "Page 3", "Page 2"]),
+ ] {
+ let mut args = json!({ "paths": ["a.pdf", "b.pdf"], "out": "combined.pdf", "open": false });
+ if let Some(pages) = pages {
+ args["pages"] = pages;
+ }
+ let result = ok(&mut a, "doc_combine", args);
+ assert!(result["bytes"].as_u64().unwrap() > 0);
+ assert!(result.get("document").is_none());
+ assert!(a.session().docs().is_empty());
+ let mut fresh = auto(&dir.0);
+ let opened = ok(&mut fresh, "doc_open", json!({ "path": "combined.pdf" }));
+ assert_eq!(opened["pages"].as_u64().unwrap(), expected.len() as u64);
+ assert_eq!(page_text(&mut fresh, opened["doc"].as_u64().unwrap()), expected);
+ assert_eq!(std::fs::read(dir.0.join("a.pdf")).unwrap(), first);
+ assert_eq!(std::fs::read(dir.0.join("b.pdf")).unwrap(), second);
+ }
+ }
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn conventions_core_tools_preserve_root_and_batch_errors() {
+ let dir = workdir("conventions-core");
+ let mut s = McpServer::new(auto(&dir));
+ let run = |s: &mut McpServer, name: &str, args: Value| rpc(s, 1, "tools/call", json!({"name":name,"arguments":args}));
+ assert_eq!(run(&mut s, "doc_inspect", json!({}))["result"]["structuredContent"]["documents"], json!([]));
+ let opened = run(&mut s, "command_run", json!({"id":"file.open","params":{"path":"a.pdf"}}));
+ assert_eq!(opened["result"]["isError"], false, "{opened}");
+ let doc = opened["result"]["structuredContent"]["doc"].as_u64().unwrap();
+ let filtered = run(&mut s, "command_list", json!({"doc":doc,"filter":"rotate","enabled_only":true}));
+ let commands = filtered["result"]["structuredContent"]["commands"].as_array().unwrap();
+ assert!(!commands.is_empty());
+ assert!(commands.iter().all(|c| c["enabled"] == true));
+ assert!(commands.iter().find(|c| c["id"] == "page.rotate").unwrap()["params"].is_object());
+ for stop in [true, false] {
+ let r = run(
+ &mut s,
+ "command_batch",
+ json!({"steps":[{"id":"page.rotate","params":{"doc":doc,"degrees":90}},{"id":"no.such.command"},{"id":"page.rotate","params":{"doc":doc,"degrees":90}}],"stop_on_error":stop}),
+ );
+ assert_eq!(r["result"]["isError"], true, "{r}");
+ assert_eq!(r["result"]["structuredContent"]["completed"], if stop { 1 } else { 2 });
+ assert_eq!(r["result"]["structuredContent"]["failed"], 1);
+ }
+ let r = run(&mut s, "command_run", json!({"id":"file.save","params":{"doc":doc,"path":"../escaped.pdf"}}));
+ assert_eq!(r["result"]["isError"], true);
+ assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("outside the allowed directory"));
+ let r = run(&mut s, "command_run", json!({"id":"page.rotate","params":{"doc":doc,"degrees":90,"typo":1}}));
+ assert_eq!(r["result"]["isError"], false);
+ assert!(r["result"]["structuredContent"]["warnings"][0].as_str().unwrap().contains("typo"));
+ let before = run(&mut s, "doc_info", json!({"doc":doc}));
+ let r = run(&mut s, "render_preview", json!({"doc":doc,"page":1,"max_side":64}));
+ assert_eq!(r["result"]["isError"], false, "{r}");
+ use base64::Engine as _;
+ let png = base64::engine::general_purpose::STANDARD.decode(r["result"]["content"][0]["data"].as_str().unwrap()).unwrap();
+ let image = image::load_from_memory(&png).unwrap();
+ assert!(image.width().max(image.height()) <= 64);
+ assert_eq!(before["result"], run(&mut s, "doc_info", json!({"doc":doc}))["result"]);
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn conventions_annotations_and_strict_keys_in_both_modes() {
+ for compact in [false, true] {
+ let mut s = McpServer::new(Automation::new()).with_compact(compact);
+ let r = rpc(&mut s, 1, "tools/list", json!({}));
+ let tools = r["result"]["tools"].as_array().unwrap();
+ for name in ["command_list", "command_run", "command_batch", "doc_inspect", "render_preview"] {
+ assert!(tools.iter().any(|t| t["name"] == name), "missing {name}");
+ }
+ for tool in tools {
+ for hint in ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] {
+ assert!(tool["annotations"][hint].is_boolean(), "{}: {hint}", tool["name"]);
+ }
+ let r = rpc(&mut s, 2, "tools/call", json!({"name":tool["name"],"arguments":{"bogus_arg":1}}));
+ assert_eq!(r["error"]["code"], -32602, "{}", tool["name"]);
+ let message = r["error"]["message"].as_str().unwrap();
+ assert!(message.contains("bogus_arg") && message.contains("expected:"));
+ }
+ }
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn conventions_resources() {
+ let dir = workdir("conventions-resources");
+ let mut s = McpServer::new(auto(&dir));
+ let read = |s: &mut McpServer, uri: &str| {
+ let r = rpc(s, 1, "resources/read", json!({"uri":uri}));
+ serde_json::from_str::(r["result"]["contents"][0]["text"].as_str().expect("JSON resource")).unwrap()
+ };
+ assert_eq!(read(&mut s, "pdfcraft://document"), json!({"documents":[]}));
+ rpc(&mut s, 2, "tools/call", json!({"name":"doc_open","arguments":{"path":"a.pdf"}}));
+ let doc = rpc(&mut s, 3, "tools/call", json!({"name":"doc_inspect","arguments":{}}));
+ assert_eq!(read(&mut s, "pdfcraft://document"), doc["result"]["structuredContent"]);
+ let commands = rpc(&mut s, 4, "tools/call", json!({"name":"command_list","arguments":{}}));
+ assert_eq!(read(&mut s, "pdfcraft://commands"), commands["result"]["structuredContent"]);
+ // Responses keep the shape every supported protocol revision expects: no cache hints.
+ for (method, params) in [("tools/list", json!({})), ("resources/list", json!({})), ("resources/read", json!({"uri":"pdfcraft://document"}))] {
+ assert!(rpc(&mut s, 5, method, params)["result"].get("resultType").is_none());
+ }
+ assert_eq!(rpc(&mut s, 7, "initialize", json!({"protocolVersion":"2026-07-28"}))["result"]["protocolVersion"], "2025-06-18");
+ assert!(s.handle_line(r#"{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":999}}"#).is_none());
+ assert_eq!(
+ rpc(&mut s, 9, "tools/call", json!({"name":"doc_inspect","arguments":{},"_meta":{"progressToken":"quick"}}))["result"]["isError"],
+ false
+ );
+}
+
+#[test]
+fn command_batch_refuses_more_than_a_thousand_steps() {
+ let dir = workdir("batch-cap");
+ let mut a = auto(&dir);
+ let steps: Vec = (0..1001).map(|_| json!({"id":"no.such.command"})).collect();
+ let err = a.call("command_batch", &json!({"steps": steps})).unwrap_err();
+ assert!(err.to_string().contains("at most 1000 steps"), "{err}");
+}
diff --git a/crates/cos/README.md b/crates/cos/README.md
new file mode 100644
index 00000000..b3ac964d
--- /dev/null
+++ b/crates/cos/README.md
@@ -0,0 +1,91 @@
+# pdfcraft-cos
+
+The PDF object layer (ISO 32000-2 §7): the COS object graph, parsed lazily and tolerantly, edited
+through a copy-on-write overlay, and written back incrementally or as a full rewrite.
+
+- **Layer:** L1, standalone. The layering table lets it use only `pdfcraft-filters`,
+ `pdfcraft-crypt` and `pdfcraft-geom` (`xtask/src/layers.rs::STANDALONE_DEPS`); it currently uses
+ the first two. That keeps the parser and the crypto independently auditable and reusable.
+- `#![forbid(unsafe_code)]`, and the crate denies `unwrap`/`expect`/`panic!`/`todo!`. Builds for
+ `wasm32-unknown-unknown`.
+
+**The object graph is the document model.** Nothing is lifted into a tidier representation and
+written back out, because that is how data gets silently dropped. Typed views live above, in
+`pdfcraft-model`.
+
+## API
+
+```rust
+let doc = Document::open(bytes)?; // Arc>
+let doc = Document::open_with_password(bytes, Some("owner"))?; // encrypted files
+
+let root = doc.root(); // Option — the catalog
+let obj = doc.get(ObjRef { num: 12, gen: 0 }); // load (and cache): Arc