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 0f56341b..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 (251)
+## In this repository (257)
| Asset | Title | Author | Licence | Source | Used for |
|---|---|---|---|---|---|
@@ -14,9 +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 |
@@ -259,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 3a1801a2..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 = "50ec1133889f3a3948a3901a9fa40b3499f3c549b605e55848138483946d74da"
+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 = "3746a7d87fb98c9f3aeb41c63ce50371c42dfebca64b67ccbb599abb36a93ba8"
+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 = "2c09a121e493fb123d9f886529f62268119ca580ad5d5300eca61d4a39216827"
+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 = "0ccf62e34424981d5980eeaee8799db2653a4c186807df143326ef9881959006"
+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 = "0b579afad6e52b98cef5e61e07e238d9cf76cc7f295395f7e1c855400e5fbaf9"
+sha256 = "e9a9bad1252afdcb42c36b24ca85411f8c63df7debada94d4423bd48761ecb05"
[[asset]]
path = "crates/ui-egui/src/i18n/fr.tsv"
@@ -74,7 +74,18 @@ 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 = "956753e05b5a9e1d4c4a63ee57667cc9fa5bb95288c3d46c6b15435b83d6ed8d"
+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"
@@ -85,7 +96,7 @@ 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 = "e8b96edd718a1cd212b7440c4ab100f2555c97dccb0cda289bdb1775d5f3aa61"
+sha256 = "d3630f989e9725c22444dc27765142674b66f72436502ca969b2851fc38d703d"
[[asset]]
path = "crates/ui-egui/src/i18n/ru.tsv"
@@ -96,7 +107,29 @@ 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 = "136a9ae206c4ee5aad29d248613c568799080b4b3ee9cd197233072ee9a2983a"
+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"
@@ -107,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 = "d2e7114c70da3c52200cf68e9023dc32ff462439795784e49c2ae771531240e2"
+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"
@@ -3105,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 d05e13d8..bc613bb8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3477,6 +3477,7 @@ dependencies = [
"hayro-syntax",
"pdfcraft-cos",
"pdfcraft-fonts",
+ "pdfcraft-model",
"thiserror 2.0.21",
]
@@ -3569,6 +3570,7 @@ dependencies = [
"pdfcraft-fonts",
"pdfcraft-model",
"thiserror 2.0.21",
+ "unicode-bidi",
]
[[package]]
@@ -3627,6 +3629,7 @@ dependencies = [
name = "pdfcraft-fonts"
version = "0.4.0"
dependencies = [
+ "harfrust",
"pdfcraft-cos",
"skrifa 0.44.0",
]
@@ -3640,6 +3643,7 @@ dependencies = [
"pdfcraft-cos",
"pdfcraft-fonts",
"pdfcraft-model",
+ "pdfcraft-render",
"thiserror 2.0.21",
]
@@ -3746,6 +3750,7 @@ dependencies = [
name = "pdfcraft-render"
version = "0.4.0"
dependencies = [
+ "bytemuck",
"getrandom 0.4.3",
"hayro",
"hayro-syntax",
@@ -3753,6 +3758,7 @@ dependencies = [
"log",
"lopdf",
"pdfcraft-fonts",
+ "skrifa 0.44.0",
"thiserror 2.0.21",
]
@@ -3788,6 +3794,7 @@ version = "0.4.0"
dependencies = [
"arboard",
"base64 0.22.1",
+ "bytemuck",
"eframe",
"egui",
"egui_extras",
@@ -6586,8 +6593,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 37f8fe30..e80a0b46 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -75,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
@@ -92,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 24db83c6..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.
diff --git a/ROADMAP.md b/ROADMAP.md
index 9d6d7412..41ace172 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, 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, 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,8 +91,8 @@ 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: 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 |
@@ -103,7 +104,8 @@ Hours are for a single agent (low–high). "Done" is the estimated fraction of t
| 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, Russian, 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,6 +127,11 @@ 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.
@@ -138,6 +145,20 @@ M0 → M1 → M2 → M3 → M4 must happen in order. After M4, M5–M12 can run
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%).
diff --git a/apps/pdfcraft-cli/src/main.rs b/apps/pdfcraft-cli/src/main.rs
index 3fe28824..1940d63e 100644
--- a/apps/pdfcraft-cli/src/main.rs
+++ b/apps/pdfcraft-cli/src/main.rs
@@ -1,23 +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] [--compact] MCP server on stdin/stdout (opt-in)
-//! --compact lists a core set of tools plus tool_search and tool_call
-//! 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
@@ -43,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,
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/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 e40607a8..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")]
@@ -150,6 +153,85 @@ fn main() -> eframe::Result {
}
}
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])
@@ -165,77 +247,82 @@ 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}");
}
- // 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);
- }
- } 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.
@@ -294,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
@@ -330,52 +419,78 @@ 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)
}
@@ -403,6 +518,26 @@ mod tests {
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();
@@ -420,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);
@@ -428,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"))?;
@@ -466,9 +654,19 @@ 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(())
}
diff --git a/contributors/people.toml b/contributors/people.toml
index 00beb658..ade46dac 100644
--- a/contributors/people.toml
+++ b/contributors/people.toml
@@ -59,3 +59,8 @@ 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/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 c98cb6d2..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
@@ -40,6 +40,10 @@ deterministic; the engine supplies them.
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 6045743f..9a026069 100644
--- a/crates/annot/src/appearance.rs
+++ b/crates/annot/src/appearance.rs
@@ -26,23 +26,77 @@ 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
@@ -200,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
@@ -334,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));
}
@@ -383,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.
@@ -444,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)?;
@@ -458,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")?;
@@ -536,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 2abfdce5..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 {
@@ -677,6 +730,16 @@ pub fn signature_image(doc: &Document, page: usize, index: usize) -> Result 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).
@@ -716,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}"));
@@ -755,11 +826,11 @@ fn rect_for(shape: &Shape, style: &Style) -> Result<[f64; 4], AnnotError> {
}
r
}
- Shape::Line { from, to, arrow } => {
+ 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 } => {
@@ -780,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);
@@ -836,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",
@@ -933,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);
}
@@ -968,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));
@@ -990,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 { .. } => {
@@ -1029,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]]));
}
@@ -1078,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));
@@ -1469,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,
@@ -1477,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)?;
@@ -1485,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 {
@@ -1516,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
@@ -1666,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)`.
@@ -1690,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 3664e7ca..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 },
];
@@ -179,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 },
];
@@ -261,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];
@@ -271,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(_))));
}
@@ -283,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%");
@@ -337,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();
@@ -429,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]
@@ -515,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();
@@ -576,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());
@@ -735,3 +762,160 @@ fn comments_without_appearances_get_one_for_display_only() {
]);
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/README.md b/crates/automation/README.md
index 21dbc3f5..29e9eb9e 100644
--- a/crates/automation/README.md
+++ b/crates/automation/README.md
@@ -23,7 +23,7 @@ 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 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.
+- `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.
diff --git a/crates/automation/src/comments.rs b/crates/automation/src/comments.rs
index 4d97e321..ebeab262 100644
--- a/crates/automation/src/comments.rs
+++ b/crates/automation/src/comments.rs
@@ -3,7 +3,9 @@
//! 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};
@@ -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]))
@@ -109,6 +138,7 @@ impl Automation {
};
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,
])
@@ -180,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),
@@ -253,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());
@@ -286,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" },
}
}
@@ -309,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)")?;
@@ -386,7 +434,7 @@ impl Automation {
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, at, kind == "initials", &author).ok_or_else(|| ToolError::InvalidArgs("at must be finite".into()))?;
+ 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;
@@ -405,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 => {
@@ -483,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/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 a74e1a09..2c36d07f 100644
--- a/crates/automation/src/lib.rs
+++ b/crates/automation/src/lib.rs
@@ -1690,7 +1690,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!({
diff --git a/crates/automation/src/tools.rs b/crates/automation/src/tools.rs
index 73b28960..14039804 100644
--- a/crates/automation/src/tools.rs
+++ b/crates/automation/src/tools.rs
@@ -245,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(
@@ -298,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!({
@@ -318,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\"." },
@@ -527,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(
@@ -555,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"],
@@ -642,7 +644,7 @@ 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 and annotation opacity. Cache these layers for live placement/resizing; commit once with comment_edit. Does not change the document or undo history.")
+ 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(
@@ -972,7 +974,7 @@ 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 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.")
+ 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"])),
@@ -990,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"])),
@@ -998,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 and no font/weight change is requested; otherwise it uses a standard font matching the source style or, for Japanese, real Mincho/Gothic fallback outlines matching the requested/source family and available weight (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.")
+ 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 },
diff --git a/crates/automation/tests/automation.rs b/crates/automation/tests/automation.rs
index 73bcb2c7..a8ecbee4 100644
--- a/crates/automation/tests/automation.rs
+++ b/crates/automation/tests/automation.rs
@@ -1530,6 +1530,7 @@ fn image_signature_preview_layers_are_read_only_and_survive_encrypted_save() {
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");
@@ -1742,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");
@@ -1927,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");
@@ -2085,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");
@@ -2116,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");
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