fix(automation): sync staged output before publication

Sync staged output after writing all bytes and before replacing its destination, closing the handle before rename. Return sync failures while keeping the old destination and ordinary save state available for retry.

Fixes #1804

.github/pull_request_template.md

@@ -0,0 +1,76 @@
+<!--
+Thanks for contributing to PdfCraft.
+
+Base this on `main` — it is the only integration branch. `main` moves fast (it took
+396 commits in the three days to 2026-10-12), so a PR that sits for a day usually needs
+a rebase. Rebasing the same day you are asked keeps the work from dying of conflicts.
+Delete any section below that does not apply.
+-->
+
+## What this changes
+
+<!-- What behaviour is different afterwards, and why it is worth doing. If it fixes an
+     issue, say `Fixes #123`. -->
+
+## How you verified it
+
+<!-- The commands you ran and what they said. Per-crate is fine and preferred:
+     `cargo test -p <crate>`. CI runs the full workspace on every PR, so you do not
+     need to locally. -->
+
+- [ ] `cargo fmt --check`
+- [ ] clippy with `-D warnings` on the crates I changed
+- [ ] tests pass on the crates I changed
+- [ ] `cargo xtask layers` and `cargo xtask assets` (if you touched crate boundaries or any asset)
+
+**Tests.** New behaviour needs a test at the right scale — a property test, a unit test, a
+crate integration test or an end-to-end one. For a bug fix, **please check that the test
+fails before your fix** by reverting the fix and watching it go red. A test nobody has seen
+fail is not evidence that it pins anything.
+
+## Never-crash
+
+Every PDF, script, MCP call, settings file and keystroke is untrusted input (`AGENTS.md` §4).
+
+- [ ] No new `unwrap`/`expect`/`panic!`/`unreachable!`/`todo!` outside tests, unless it is
+      provably infallible with a comment saying why
+- [ ] No indexing or slicing with input-derived positions (`get`, and strings only at char
+      boundaries); checked or saturating arithmetic; allocations sized by input are capped;
+      recursion is bounded
+- [ ] No `unsafe`
+- [ ] Any crash this fixes has a small synthetic regression test
+
+## Provenance
+
+This is the part that cannot be undone after a merge, and the part a new contributor is
+least likely to know about. Please read `AGENTS.md` §1 before adding any asset.
+
+- [ ] No asset from an Adobe product, and no Adobe icon recreated, traced or imitated
+- [ ] No font files committed here (they live in
+      [storytold/craft-fonts](https://github.com/storytold/craft-fonts))
+- [ ] No GPL/AGPL code copied in — MuPDF, Ghostscript, Poppler, veraPDF and DSS may only be
+      run as external oracle processes
+- [ ] Behaviour comes from the specification or black-box observation, **not** from reading
+      another implementation's source
+- [ ] Every new asset has an `ATTRIBUTION.toml` entry and `cargo xtask assets` passes
+
+## Security
+
+- [ ] `--root` confinement still holds on every path, including ones reached by nested
+      tool dispatch
+- [ ] MCP and the UI control channel stay opt-in, loopback-only and token-authenticated
+- [ ] No new outbound network access (that decision is the owner's)
+
+## Parity and reach
+
+- [ ] `parity/acrobat-features.toml` updated in this PR, with `notes` saying what is *still*
+      missing — `shipped` means "exists and tested", not "as good as Acrobat"
+- [ ] Reachable headlessly through an `automation` tool where that applies (`AGENTS.md` §3),
+      so agents can drive it and not just the UI
+- [ ] Docs updated if this changes a documented behaviour (`docs/`, crate README)
+
+## Anything a reviewer should look at first
+
+<!-- The judgement call you are least sure about, a deliberate restraint you want pinned,
+     or a behaviour change existing users will notice. Say so here rather than leaving it
+     to be found. -->

.github/workflows/ci.yml

@@ -20,6 +20,9 @@ jobs:
   test:
     name: test (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
+    env:
+      CARGO_PROFILE_DEV_DEBUG: line-tables-only
+      CARGO_PROFILE_TEST_DEBUG: line-tables-only
     strategy:
       fail-fast: false
       matrix:
@@ -36,9 +39,15 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
+          ref: 3d9ab3a132ed0eff457e424226a435a901da30d3
           path: craft-fonts
 
+      - name: Configure craft-fonts (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          echo "CRAFT_FONTS_DIR=$GITHUB_WORKSPACE/craft-fonts" >> "$GITHUB_ENV"
+          echo "CRAFT_FONTS_REQUIRED=1" >> "$GITHUB_ENV"
+
       - name: Install Linux system dependencies (egui/winit/rfd)
         if: runner.os == 'Linux'
         run: |
@@ -72,12 +81,10 @@ jobs:
 
       - name: Test (with craft-fonts)
         if: runner.os == 'Linux'
-        env:
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
         run: cargo test --workspace
 
       - name: Layering
+        if: runner.os == 'Linux'
         run: cargo xtask layers
 
       - name: Assets (licences and attribution)

.github/workflows/freebsd.yml

@@ -26,4 +26,4 @@ jobs:
     # Intentionally tracked at @main (not SHA-pinned) so org-wide CI improvements, security fixes, and build optimizations propagate without PR churn across all craftapp repos.
     uses: storytold/craft-common-actions/.github/workflows/freebsd.yml@main
     with:
-      craft-fonts-ref: 8dcdacd5153e64560d109541a47d806f26f048c0
+      craft-fonts-ref: 3d9ab3a132ed0eff457e424226a435a901da30d3

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
     with:
       app-name: pdfcraft
       app-title: PdfCraft
-      craft-fonts-ref: 8dcdacd5153e64560d109541a47d806f26f048c0
+      craft-fonts-ref: 3d9ab3a132ed0eff457e424226a435a901da30d3
       version: ${{ inputs.version }}
     secrets:
       APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
@@ -35,3 +35,9 @@ jobs:
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
       WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
       WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
+      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+      AZURE_SIGNING_ENDPOINT: ${{ secrets.AZURE_SIGNING_ENDPOINT }}
+      AZURE_SIGNING_ACCOUNT: ${{ secrets.AZURE_SIGNING_ACCOUNT }}
+      AZURE_CERT_PROFILE: ${{ secrets.AZURE_CERT_PROFILE }}

AGENTS.md

@@ -25,7 +25,7 @@ An **asset** is any non-code material that the project includes, ships, embeds,
 - Screenshots of Adobe software exist only as private, local observation notes under `plan/acrobat/`, which is gitignored. They must **never** be committed, published, linked, shown in docs, used as a design source to trace, or placed anywhere else in the repository or its outputs.
 - The only Adobe-authored material allowed is **non-visual technical data** that is openly licensed and required for PDF compatibility. Each item needs its own entry in `ATTRIBUTION.toml` with `adobe_data = true`, and the list below is closed:
   - The CMap resources (BSD-3-Clause), bundled inside the `hayro-cmap` dependency.
-  - The standard-14 font metrics and encoding tables in the PDF specification. They are data, not typefaces, and are embedded as code in hayro.
+  - The standard-14 font metrics and encoding tables in the PDF specification. They are data, not typefaces. They are embedded as code in hayro, and as our own generated table in `crates/fonts/src/std14_metrics.rs` (approved by the owner, 2026-10-08; that file holds the data alone, so the code reading it can change without re-attesting the table), which is what generated appearances measure with and what survives hayro being retired.
 
   Adding anything to this list needs the user's explicit approval.
 

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 (269)
+## In this repository (270)
 
 | Asset | Title | Author | Licence | Source | Used for |
 |---|---|---|---|---|---|
@@ -27,6 +27,7 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
 | `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 |
 | `crates/ui-egui/src/i18n/ar.tsv` | Arabic 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 | Arabic UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/tr.tsv` | Turkish 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 | Turkish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/lt.tsv` | Lithuanian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels and user-facing messages; reviewed by a native Lithuanian-speaking contributor | Lithuanian 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 |
@@ -221,7 +222,7 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
 | `vendor/hayro-interpret/assets/FoxitSerifItalic.pfb` | FoxitSerifItalic (standard-14 substitute font) | Foxit Software Inc. / PDFium Authors | BSD-3-Clause | https://pdfium.googlesource.com/pdfium (via hayro-interpret 0.7.0 assets/) | Renders non-embedded standard-14 fonts (vendored hayro-interpret) |
 | `vendor/hayro-interpret/assets/FoxitSymbol.pfb` | FoxitSymbol (standard-14 substitute font) | Foxit Software Inc. / PDFium Authors | BSD-3-Clause | https://pdfium.googlesource.com/pdfium (via hayro-interpret 0.7.0 assets/) | Renders non-embedded standard-14 fonts (vendored hayro-interpret) |
 | `vendor/hayro-interpret/assets/CGATS001Compat-v2-micro.icc` | CGATS001Compat v2 micro ICC profile | Clinton Ingram (saucecontrol/Compact-ICC-Profiles) | CC0-1.0 | https://github.com/saucecontrol/Compact-ICC-Profiles | Default CMYK colour conversion (vendored hayro-interpret) |
-| `vendor/hayro-interpret/assets/LAB.icc` | Lab abstract ICC profile | The Hayro Authors (generated with LittleCMS 2) | MIT OR Apache-2.0 | https://github.com/LaurenzV/hayro (hayro-interpret 0.7.0 assets/) | Lab colour space conversion (vendored hayro-interpret) |
+| `crates/fonts/src/std14_metrics.rs` | Standard-14 font advance widths and encodings (as Rust tables) | Adobe (Core14 AFM metrics, PDF specification encodings); tables generated by the PdfCraft contributors | MIT OR Apache-2.0 | ISO 32000-2 Annex D and the Adobe Core14 AFM metrics. Generated by joining the published WinAnsi, Symbol and ZapfDingbats encodings (code to glyph name) with the per-glyph advance widths, then spot-checked against the specification by hand in the tests of crates/fonts/src/std14.rs. Data only: the code that reads these tables lives in std14.rs, so that ordinary edits do not churn this file's hash. | Advance widths for the fourteen standard fonts, which a PDF may name without embedding. Non-visual data, not a typeface: the item AGENTS.md 1.1 permits, held first-party so generated appearance streams and the renderer agree. |
 | `docs/brand/artcraft-logo-white.png` | ArtCraft brand: artcraft-logo-white | ArtCraft Team | LicenseRef-Storyteller-Trademark | ArtCraft Team brand assets (provided by the project owner, 2026-10-01; identical copies in storytold/photocraft) | ArtCraft branding next to the community links (About dialog, Help menu, home screen) and in docs. ArtCraft Team trademark, not open source; may be used only unmodified within PdfCraft; forks and modified versions must remove it. |
 | `docs/brand/artcraft-logo-white.svg` | ArtCraft brand: artcraft-logo-white | ArtCraft Team | LicenseRef-Storyteller-Trademark | ArtCraft Team brand assets (provided by the project owner, 2026-10-01; identical copies in storytold/photocraft) | ArtCraft branding next to the community links (About dialog, Help menu, home screen) and in docs. ArtCraft Team trademark, not open source; may be used only unmodified within PdfCraft; forks and modified versions must remove it. |
 | `docs/brand/artcraft-logo.png` | ArtCraft brand: artcraft-logo | ArtCraft Team | LicenseRef-Storyteller-Trademark | ArtCraft Team brand assets (provided by the project owner, 2026-10-01; identical copies in storytold/photocraft) | ArtCraft branding next to the community links (About dialog, Help menu, home screen) and in docs. ArtCraft Team trademark, not open source; may be used only unmodified within PdfCraft; forks and modified versions must remove it. |

ATTRIBUTION.toml

@@ -7,7 +7,7 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Greek UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "23a9402d3ebbcff69aed133706e6e428a804ae06a7dba4923892cca5c98e92d1"
+sha256 = "389982dcbb7f1ac29fb150c9af43f9529db6e59a091b9971f0401684847d8b53"
 
 # ATTRIBUTION.toml: one entry per asset (AGENTS.md §1). The source of truth for provenance and licences.
 # ATTRIBUTION.md is generated from this file: `cargo xtask assets --write`. Checked by `cargo xtask assets` (part of `xtask ci`).
@@ -30,7 +30,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 = "1863437c886142b2bccce3f44a538ae80d0ceea81074b84dfdfe8d9a4a4227ab"
+sha256 = "d8ea23644d81476e3fd35c09780ab9b3ac8c9e28bed4e14e1cbc6493bb896d91"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/zh-hant.tsv"
@@ -41,7 +41,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 = "6c8604d5cd71412c6a673b75001c7ef629727839eca1449147c7d6ec4bf0be99"
+sha256 = "26dd0b0d697fd40db996fc102f3c7f2320bdeb6d6af38dbdde353bd5d940baad"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/cs.tsv"
@@ -52,7 +52,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 = "5ae2e315a9b99b4c0dfaf7be019c4d430ace17b4fbbfea5a2779b3e972846a21"
+sha256 = "322b8cda21a2b8d157716182846619bd92bfb31263d1f8d13da7eaad365fbfd7"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/pt-br.tsv"
@@ -63,7 +63,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 = "8b9e22fa25339e4aedb0542b8bf6f68dfd97bc3634105199e1951475e30eed53"
+sha256 = "21bf9c73b482eb987ddaf839b4a4aa8f9938d5aa10428e6d39beea254a95a0c0"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/es.tsv"
@@ -74,7 +74,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 = "6d81592677f2b4eb3b97ba5810de9752da969545d91897e27033f37310696ffc"
+sha256 = "fef35ae1771edf2e044e72aebb958bb4827ded57234207f96b6cb7a250fedb22"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/fr.tsv"
@@ -85,7 +85,7 @@ 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 = "fb9c91a98c6975bc24249e8ae750fd46b9245ac5d2d7381f1e21319b9adbcaac"
+sha256 = "d723622298b10400e9a1ba697cbebd831f5e0f7e5bbe4545b97f61e64db7535f"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/de.tsv"
@@ -96,7 +96,7 @@ 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 = "f36aefae1a1ba6d576a4647fbfdd65b9b5086bfb266ea260e513244adc7af05a"
+sha256 = "686ab9658b7ef9dd7f3af05ce73f99f1ab2a75f8357bad6f7e987d40a8730df9"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/te.tsv"
@@ -107,7 +107,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 = "656940b456a6c2401f8bd3107a71cedcae5e52cd446e86e806285b6322d8ed8e"
+sha256 = "90b94038699aa74aa48ffbda3e90a2255b65d0dbf081e8ecf20c5804940fc129"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/it.tsv"
@@ -118,7 +118,7 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Italian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "14884c08a550600d310a794ceb0b2bb864987a074178ee49b657578b66625bef"
+sha256 = "5aa6475df91a3e82010aee198c2e29bb80328505bbd0240f3828e36a5d6dfdf3"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/pl.tsv"
@@ -129,7 +129,7 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Polish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "be960bdf9b6eeac2d95db91325076ee79c9b2efdcc4e459c7400e7ddb05fab3a"
+sha256 = "e6d306d9bf289fac2fe8fcfa6f9d0a51b650728e45669289d391be2031076692"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ru.tsv"
@@ -140,7 +140,7 @@ 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 = "bada9b6f0b3775e4dab1213d9759070f7551d8a6142de10159268c88a04d3f0c"
+sha256 = "277f4995a87297a2fcc473df1feebdbdf3378fa460a7f85eb1a0a151cee40a2b"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/hu.tsv"
@@ -151,7 +151,7 @@ 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 = "efb75d8575df9e1dd4610602f20545b3a14a3a0814060efc27eb7cab591ccccb"
+sha256 = "01b32370cedce935b74925858a79ee691dc2a5560ba5eb758de2de1c243c528e"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/bg.tsv"
@@ -162,7 +162,7 @@ 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 = "ca305b188abc8d9c261901dde10f7cd8518520983fdf88d2358374b352ad3d5a"
+sha256 = "f8ae97901c61dfdc0a844a23356173211bb052b3ff54128d7edc8097c535eee9"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/kk.tsv"
@@ -173,7 +173,7 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Kazakh UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "77afe7d7fa215c99e8e627a758178d79c51e08e33564e00b97b8840aeb91a9dd"
+sha256 = "7107ba77577794395451dd85355a86ef3e033a7f240b72414b877b9b43adb19e"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ja.tsv"
@@ -184,7 +184,7 @@ 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 = "f004b06f4e7eb8f4a99e22e1abfd97c95795b2215080e4008574522e54eda74c"
+sha256 = "114b3d50531eb1682535c7a646e62914b0c9afaa5d5d1b9f66b94fd472e4e7b3"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/uk.tsv"
@@ -195,7 +195,7 @@ 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 = "cd9ecaf661533cbd3b055cfd3994602f6739c83061d1e225ba43ee6f229068cf"
+sha256 = "f56ec5f4cb7d1992041df0783f1cfd76c27d5d180c3f73c60b104e3fd02f600d"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ar.tsv"
@@ -206,7 +206,7 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Arabic UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "a8a66390b2d80b4708c4f854318b923eef7f0f5932439fb5ef25f2651980f24e"
+sha256 = "113fdf57e28fcff90d212fb468011bedebfb98ac100218d29b584f4de4c87912"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/tr.tsv"
@@ -217,7 +217,18 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Turkish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "5688538845a80c154feabd096badbf097485dea8a7402fede4ef7d71466e9d6a"
+sha256 = "2b5edfe026578ed475f07f94f1d1ed4a3dac93a745c19209589936e2d67f6ec5"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/lt.tsv"
+title = "Lithuanian interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels and user-facing messages; reviewed by a native Lithuanian-speaking contributor"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Lithuanian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+sha256 = "fe58835b0538f470b463f078e1b4cdf78a8e2632056bc61c6946071478f39a64"
 
 [[asset]]
 path = "assets/icons/accessibility.svg"
@@ -2354,15 +2365,16 @@ usage = "Default CMYK colour conversion (vendored hayro-interpret)"
 sha256 = "73e1ba37d2bad5bab2a964f40a9eed96209666efc067c3322626214bbef234a0"
 
 [[asset]]
-path = "vendor/hayro-interpret/assets/LAB.icc"
-title = "Lab abstract ICC profile"
-author = "The Hayro Authors (generated with LittleCMS 2)"
-source = "https://github.com/LaurenzV/hayro (hayro-interpret 0.7.0 assets/)"
+path = "crates/fonts/src/std14_metrics.rs"
+title = "Standard-14 font advance widths and encodings (as Rust tables)"
+author = "Adobe (Core14 AFM metrics, PDF specification encodings); tables generated by the PdfCraft contributors"
+source = "ISO 32000-2 Annex D and the Adobe Core14 AFM metrics. Generated by joining the published WinAnsi, Symbol and ZapfDingbats encodings (code to glyph name) with the per-glyph advance widths, then spot-checked against the specification by hand in the tests of crates/fonts/src/std14.rs. Data only: the code that reads these tables lives in std14.rs, so that ordinary edits do not churn this file's hash."
 licence = "MIT OR Apache-2.0"
-licence_file = "vendor/hayro-interpret/LICENSE-MIT"
+licence_file = "LICENSE-MIT"
 kind = "data"
-usage = "Lab colour space conversion (vendored hayro-interpret)"
-sha256 = "a6efc5c30ece826eba2a83ddf5aa7026289b0c5ffa90acb129bc59ab8d7f5c59"
+adobe_data = true
+usage = "Advance widths for the fourteen standard fonts, which a PDF may name without embedding. Non-visual data, not a typeface: the item AGENTS.md 1.1 permits, held first-party so generated appearance streams and the renderer agree."
+sha256 = "f225e0b044875b8fa6375b6b5ad935f0d99fcc1ad03ecf9f0baae2cedbfca4d2"
 
 [[bundled]]
 crate = "epaint_default_fonts"
@@ -3339,4 +3351,4 @@ licence = "MIT OR Apache-2.0"
 licence_file = "LICENSE-MIT"
 kind = "translation"
 usage = "Slovene UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
-sha256 = "8590f5acce1da70d6a3ce58de073bf4f86815651ff74a59625980c6c52e051b7"
+sha256 = "9bbbd0d516f284b571ad6e2ed811f6bbdee283cea8483686f4aa939db38ea288"

CLAUDE.md

@@ -31,8 +31,15 @@ PdfCraft is a clean-room, open-source, Rust-native PDF application targeting Ado
   - No `unsafe` (`unsafe_code = "forbid"`).
   - Every crash fix gets a synthetic regression test. See `AGENTS.md` §4 (and, for team members, the internal `craftrules/standards/never-crash.md`).
 - **Rust only** in the product and build (`xtask`). No handwritten JS/TS.
-- **Quality gates** before every commit: `cargo fmt --check`, `cargo clippy --workspace -- -D warnings`, `cargo test --workspace`, and the wasm check once `xtask ci` exists (M0).
-- **Commits:** one task id per commit (e.g. `M1.4: xref stream reader`). Commit only green states. End messages with the attribution line required by the environment.
+- **Review every update as you make it, at four zooms.** Not an end-of-task pass — a per-update habit, so a defect never gets built on. **Clause:** checked arithmetic, `get()` not `[i]`, char-boundary slicing, the right error through `?`, `<` against `<=`, the 1-based/0-based seam, capped allocations. **Function:** is it total — name an input that panics; walk empty, zero, max, malformed, cyclic; is the return type honest. **File/module:** two sources of truth, dead or duplicated code, is the public surface still smallest and the doc comment still true. **Project:** layering, wasm, undo/redo, save fidelity, encryption and permissions, a matching `automation` tool or registry entry, and whether a `parity/` status or note just became untrue. Scale the zoom to the change, and fix what a level turns up before widening.
+  - Tests mirror the zooms: property → unit → crate integration → end-to-end.
+  - **Prove a test fails before the fix by actually reverting the fix.** A test nobody has seen fail is not evidence. This has caught two worthless tests in this repo: one confinement test passed with path resolution switched off entirely, because the tools failed on a nonexistent document id before reaching the path.
+  - **Rebasing is a review step, not a mechanical one.** Read every hunk you resolve, and the auto-merged hunks in the files you touched too — `main` moves fast enough that a file can change by hundreds of lines under a branch.
+- **External PRs are held to safety, security and completeness before style.** Provenance first (no Adobe-derived asset, no committed font, no copied GPL/AGPL code, behaviour from the spec and not from reading another implementation), then no new panic path or `unsafe`, then `--root` confinement on every path including ones reached by nested dispatch, opt-in-only MCP and control channel, no new outbound network, then a headless `automation` tool, tests at the right zoom and an honest `parity/` entry. Provenance is the part a contributor cannot be expected to know, and the only part that cannot be undone after merge.
+- **Quality gates** before every commit: `cargo fmt --check`, clippy with `-D warnings`, the tests, `cargo xtask layers`, `cargo xtask assets`, and the wasm check once `xtask ci` exists (M0).
+  - **Scope builds and tests to the crates you touched** — `cargo clippy -p <crate> -j 2 --all-targets` and `cargo test -p <crate> -j 2`, under a `timeout`. A full `--workspace` build has locked up a development machine's CPU; it is CI's job and CI runs it on every PR. Run the workspace sweep locally only when you have a reason to and the machine is free.
+- **Commits and PRs:** `main` is the only integration branch and is **never pushed to directly**. Branch from an up-to-date `main` as `<type>/<slug>` (`feat/`, `fix/`, `docs/`, `chore/`, `refactor/`), one task id per commit (e.g. `M1.4: xref stream reader`), commit only green states, and open a PR into `main` using `.github/pull_request_template.md`. Merge only when CI is green.
+  - **`main` moves fast enough that PRs rot.** It took 396 commits in the three days to 2026-10-12, and most open PRs are conflicting at any given time. Rebase your own branch the same day `main` moves under it, and ask the author to rebase theirs — never rewrite a contributor's branch. Conflict risk tracks how *contested* the files are, not how large the change is: tooling, tests and docs are nearly free, while `crates/fonts`, `ui-egui` and the i18n catalogues are where several people collide at once.
 
 ## Running and looking at the app
 - `cargo run -p pdfcraft -- <file.pdf>` opens the desktop app.

Cargo.toml

@@ -5,47 +5,49 @@ exclude = ["vendor"]
 default-members = ["crates/*", "apps/pdfcraft", "apps/pdfcraft-cli", "xtask"]
 
 [workspace.package]
-version = "0.6.0"
+version = "0.7.1"
 edition = "2024"
 license = "MIT OR Apache-2.0"
-rust-version = "1.90"
+rust-version = "1.95"
 repository = "https://github.com/storytold/pdfcraft"
 
 [workspace.dependencies]
 # Shared frontend components; engines remain independent of egui.
 craft-ui = { git = "https://github.com/storytold/craft-libs", version = "0.1.0", rev = "5c874d51eeb3de70e735c8ce87a59a7dedd47675", features = ["serde"] }
+# Shared system spooler; document composition remains in pdfcraft-print.
+craft-print = { git = "https://github.com/storytold/craft-libs", version = "0.1.0", rev = "f03ec27ab2c405969428512178f746183cd55ca0" }
 # internal
-pdfcraft-geom = { path = "crates/geom", version = "0.6.0" }
-pdfcraft-filters = { path = "crates/filters", version = "0.6.0" }
-pdfcraft-cos = { path = "crates/cos", version = "0.6.0" }
-pdfcraft-crypt = { path = "crates/crypt", version = "0.6.0" }
-pdfcraft-organize = { path = "crates/organize", version = "0.6.0" }
-pdfcraft-measure = { path = "crates/measure", version = "0.6.0" }
-pdfcraft-annot = { path = "crates/annot", version = "0.6.0" }
-pdfcraft-audit = { path = "crates/audit", version = "0.6.0" }
-pdfcraft-fonts = { path = "crates/fonts", version = "0.6.0" }
-pdfcraft-model = { path = "crates/model", version = "0.6.0" }
-pdfcraft-content = { path = "crates/content", version = "0.6.0" }
-pdfcraft-redact = { path = "crates/redact", version = "0.6.0" }
-pdfcraft-print = { path = "crates/print", version = "0.6.0" }
-pdfcraft-xfdf = { path = "crates/xfdf", version = "0.6.0" }
-pdfcraft-sign = { path = "crates/sign", version = "0.6.0" }
-pdfcraft-optimize = { path = "crates/optimize", version = "0.6.0" }
-pdfcraft-a11y = { path = "crates/a11y", version = "0.6.0" }
-pdfcraft-ocr = { path = "crates/ocr", version = "0.6.0" }
-pdfcraft-js = { path = "crates/js", version = "0.6.0" }
-pdfcraft-compare = { path = "crates/compare", version = "0.6.0" }
-pdfcraft-preflight = { path = "crates/preflight", version = "0.6.0" }
-pdfcraft-export = { path = "crates/export", version = "0.6.0" }
-pdfcraft-edit = { path = "crates/edit", version = "0.6.0" }
-pdfcraft-create = { path = "crates/create", version = "0.6.0" }
-pdfcraft-forms = { path = "crates/forms", version = "0.6.0" }
-pdfcraft-xfa = { path = "crates/xfa", version = "0.6.0" }
-pdfcraft-render = { path = "crates/render", version = "0.6.0" }
-pdfcraft-engine = { path = "crates/engine", version = "0.6.0" }
-pdfcraft-platform = { path = "crates/platform", version = "0.6.0" }
-pdfcraft-ui-egui = { path = "crates/ui-egui", version = "0.6.0" }
-pdfcraft-automation = { path = "crates/automation", version = "0.6.0", default-features = false }
+pdfcraft-geom = { path = "crates/geom", version = "0.7.0" }
+pdfcraft-filters = { path = "crates/filters", version = "0.7.0" }
+pdfcraft-cos = { path = "crates/cos", version = "0.7.0" }
+pdfcraft-crypt = { path = "crates/crypt", version = "0.7.0" }
+pdfcraft-organize = { path = "crates/organize", version = "0.7.0" }
+pdfcraft-measure = { path = "crates/measure", version = "0.7.0" }
+pdfcraft-annot = { path = "crates/annot", version = "0.7.0" }
+pdfcraft-audit = { path = "crates/audit", version = "0.7.0" }
+pdfcraft-fonts = { path = "crates/fonts", version = "0.7.0" }
+pdfcraft-model = { path = "crates/model", version = "0.7.0" }
+pdfcraft-content = { path = "crates/content", version = "0.7.0" }
+pdfcraft-redact = { path = "crates/redact", version = "0.7.0" }
+pdfcraft-print = { path = "crates/print", version = "0.7.0" }
+pdfcraft-xfdf = { path = "crates/xfdf", version = "0.7.0" }
+pdfcraft-sign = { path = "crates/sign", version = "0.7.0" }
+pdfcraft-optimize = { path = "crates/optimize", version = "0.7.0" }
+pdfcraft-a11y = { path = "crates/a11y", version = "0.7.0" }
+pdfcraft-ocr = { path = "crates/ocr", version = "0.7.0" }
+pdfcraft-js = { path = "crates/js", version = "0.7.0" }
+pdfcraft-compare = { path = "crates/compare", version = "0.7.0" }
+pdfcraft-preflight = { path = "crates/preflight", version = "0.7.0" }
+pdfcraft-export = { path = "crates/export", version = "0.7.0" }
+pdfcraft-edit = { path = "crates/edit", version = "0.7.0" }
+pdfcraft-create = { path = "crates/create", version = "0.7.0" }
+pdfcraft-forms = { path = "crates/forms", version = "0.7.0" }
+pdfcraft-xfa = { path = "crates/xfa", version = "0.7.0" }
+pdfcraft-render = { path = "crates/render", version = "0.7.0" }
+pdfcraft-engine = { path = "crates/engine", version = "0.7.0" }
+pdfcraft-platform = { path = "crates/platform", version = "0.7.0" }
+pdfcraft-ui-egui = { path = "crates/ui-egui", version = "0.7.0" }
+pdfcraft-automation = { path = "crates/automation", version = "0.7.0", default-features = false }
 
 # pdf
 hayro = "0.7.1"

NOTICE

@@ -20,20 +20,22 @@ list (author, source, license) is in ATTRIBUTION.md.
 - Inter typeface (assets/fonts/Inter-*.ttf) — SIL Open Font License 1.1. See assets/fonts/OFL-Inter.txt.
 - JetBrains Mono typeface (assets/fonts/JetBrainsMono-*.ttf) — SIL Open Font License 1.1. See assets/fonts/OFL-JetBrainsMono.txt.
 - Dancing Script typeface (assets/fonts/DancingScript.ttf), Copyright 2016 The Dancing Script Project Authors — SIL Open Font License 1.1 (Reserved Font Name "Dancing Script"). See assets/fonts/OFL-DancingScript.txt.
-- Japanese fonts from craft-fonts (https://github.com/storytold/craft-fonts), an optional build input
+- Fonts from craft-fonts (https://github.com/storytold/craft-fonts), an optional build input
   (CRAFT_FONTS_DIR) that is not part of this repository. Builds made with it, which includes every
   official release, embed the fonts listed in
   https://github.com/storytold/craft-fonts/blob/main/ATTRIBUTION.md (BIZ UDPGothic, Shippori Mincho,
   BIZ UDMincho; the web build only BIZ UDPGothic Regular) under the SIL Open Font License 1.1. Those
-  packages carry each font's licence as OFL-<family>.txt.
+  packages carry each font's licence as OFL-<family>.txt. Builds made with the craft-fonts revision
+  pinned in .github/workflows/ also include Noto Sans Thai (in the web build too), Copyright 2022
+  The Noto Project Authors (https://github.com/notofonts/thai), under SIL OFL 1.1; its licence is
+  fonts/noto-sans-thai/OFL.txt in the craft-fonts build input.
 - hayro (rendering, via crates.io) — Apache-2.0 OR MIT. Its `embed-fonts` feature bundles the Foxit
   standard-14 Type 1 fonts under BSD-3-Clause ("Copyright 2014 PDFium Authors"), and hayro-cmap bundles
   Adobe CMap resources under BSD-3-Clause.
 - lopdf (bootstrap document inspection, via crates.io) — MIT.
 - egui default fonts (epaint_default_fonts, via eframe) — Ubuntu Light (Ubuntu Font Licence 1.0),
   Hack (MIT / Bitstream Vera licence), Noto Emoji (SIL OFL 1.1), emoji-icon-font (MIT).
-- Colour profiles in hayro-interpret — CGATS001Compat-v2-micro.icc (CC0-1.0, Clinton Ingram) and
-  LAB.icc (generated by the hayro authors with LittleCMS 2; MIT OR Apache-2.0).
+- Colour profile in hayro-interpret — CGATS001Compat-v2-micro.icc (CC0-1.0, Clinton Ingram).
 
 Required notices:
 

README.md

@@ -133,6 +133,8 @@ Search the whole document as you type, step through matches with <kbd>⌘G</kbd>
 
 ## Navigate long documents
 
+Right-click a PDF tab to close it, reopen the last closed file-backed tab, or reveal its file. Closing still asks about unsaved changes. Reopening reads the saved file from disk; it does not restore discarded edits. Reveal selects the file in Explorer or Finder. On Linux and FreeBSD it requests `org.freedesktop.FileManager1.ShowItems`, falling back to opening the containing directory with `xdg-open` when that service is unavailable. Reopen and Reveal are unavailable on the web; Reveal is also unavailable for pathless 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.
 
 <table>
@@ -369,6 +371,8 @@ PdfCraft is a clean-room implementation. Its behaviour comes from the ISO 32000
 
 ## Get started
 
+Building needs Rust 1.95 or later.
+
 ```sh
 git clone https://github.com/storytold/pdfcraft
 cd pdfcraft
@@ -417,10 +421,10 @@ PdfCraft is young and moving fast. The aim is a workbench where you can view, or
 
 - **Good today:** viewing and search; organizing, combining and splitting; most kinds of comment; filling and authoring forms (with sandboxed JavaScript); passwords, redaction and sanitizing; basic digital signatures; printing; the Accessibility Checker; agent control through the CLI and MCP.
 - **Still borrowed:** pages are drawn by the `hayro` crate while our own renderer is built.
-- **Thin or missing:** reliable editing of existing text (especially CJK and right-to-left), OCR beyond Latin script, Office import/export, signature tokens and online long-term validation, Preflight and PDF/X/UA, printing from the web build, and full XFA forms.
+- **Thin or missing:** reliable editing of existing text (especially CJK and right-to-left), OCR beyond Latin script, Office import/export, signature tokens and online long-term validation, Preflight and PDF/X/UA, printing from the web build, physical printer fidelity, and full XFA forms.
 - **Hardening:** fuzzing still turns up crashes and hangs on hostile files; each one is fixed with a regression test. Quality has not yet been compared with Acrobat side by side.
 
-**Next, in order:** Office-to-PDF and a Word export that keeps layout, the reported bugs, web printing and the Chinese interface font, a fidelity harness against Acrobat and the renderer, editing existing content, then the Pro workflows (OCR, Office, Preflight, signatures, accessibility tagging) and 1.0 polish.
+**Next, in order:** Office-to-PDF and a Word export that keeps layout, the reported bugs and the Chinese interface font, a fidelity harness against Acrobat and the renderer, editing existing content, then the Pro workflows (OCR, Office, Preflight, signatures, accessibility tagging) and 1.0 polish.
 
 The summary is in **[ROADMAP.md](ROADMAP.md)**; the full assessment by dimension and area is in [docs/target-app-parity.md](docs/target-app-parity.md), the ranked gaps in [docs/gaps.md](docs/gaps.md), and the milestones in [docs/roadmap.md](docs/roadmap.md).
 
@@ -446,14 +450,18 @@ The portable zip runs from any folder, a USB stick included. Its `portable.txt`
 logs and crash recovery in a `PdfCraftData` folder next to `pdfcraft.exe`, so nothing is written to
 `%APPDATA%`; delete that file to use the normal per-user folders.
 
-The MSI installs for all users and requires administrator privileges. For unattended deployment
-without a desktop shortcut, run from an elevated terminal:
+The MSI installs for all users and requires administrator privileges. It adds "Edit with PdfCraft"
+to the right-click menu of PDF files in File Explorer (on Windows 11, under "Show more options"),
+without changing which app opens PDFs by default. For unattended deployment without a desktop
+shortcut, run from an elevated terminal:
 
 ```powershell
 msiexec /i "pdfcraft-<ver>-windows-x64.msi" /qn /norestart INSTALLDESKTOPSHORTCUT=0
 ```
 
-Use the MSI for your architecture. Per-user installation overrides are not supported.
+Add `INSTALLPDFCONTEXTMENU=0` to leave out the right-click menu entry. Pass both on upgrades too,
+since each install applies its own choices. Use the MSI for your architecture. Per-user
+installation overrides are not supported.
 
 ### macOS
 

ROADMAP.md

@@ -2,8 +2,22 @@
 
 **Stage: alpha** · next: beta, ~26% (ready for real work 49% → 75%) and ~400–700 h away
 
+> **Last reviewed:** 2026-10-13 · **Last updated:** 2026-10-13 · **Change:** minor (M3 candidate: native opens retain chosen tools through password retries and defer startup intake while preparation is pending; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M13: CLI check visits each directory once through aliases and cycles; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M4: Extract and Split preserve shared Type 3 glyph resources; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M2: packed TIFF-predictor RGB rows retain their byte boundaries; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M3 #1364 candidate: consent before absolute local GoToR access; estimates unchanged); earlier: minor (M1 #1339: an unchanged incremental save of a classic cross-reference table writes a zero-length subsection; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M5 #1398: stamps read upright on rotated pages; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (gap 6: cloudy comments stay when flatten cannot draw them, a refused text-box edit keeps its properties, arrow defaults stay off lines, a custom match stops at a separator, and the vertical-text redaction error no longer claims an overlap; #1317, #1327, #1302, #1315, #1340; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M7 #1316: replacing a line keeps a neighbouring line whose glyph box overlaps; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M1 #1339: an unchanged incremental save of a classic cross-reference table writes a zero-length subsection; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M14 Windows low-DPI font-hinting candidate measured on macOS; no Windows runtime claim; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M3: Windows' Animation effects setting is followed, and Preferences has Animation effects: system, on or off); earlier: exclusive image-crop resize follow-up; M2 short same-line redraws split before placement; estimates unchanged · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** minor (M7 #1200 candidate: local GoToR links and confined automation; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-10-12 · **Change:** exclusive image-crop resize follow-up; minor (M2 short same-line redraws split before placement; estimates unchanged) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-12 · **Change:** minor (M10, #1028: OCR reads pictures on pages that have text, on request); earlier: M14 #307 Plan 3 uses one marker traversal on open and full refresh, and the combined scanner borrows metadata instead of cloning scan-only containers; includes a behavior-preserving `organize` binding for the workspace Clippy gate · earlier: minor (localized shortcut labels, #496; readiness table with hours per audience; full number as weighted sum 49%; second look: ready 40% → 47%, mainstream 55% added; core-workflow gate applied → alpha) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-11 · **Change:** minor (#594 paragraph drags validated in the Linux test environment; localized shortcut labels, #496; readiness table with hours per audience; full number as weighted sum 49%; earlier: second look: ready 40% → 47%, mainstream 55% added; core-workflow gate applied → alpha) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
 > **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-11 · **Change:** minor (architectural paper controls from #599; localized shortcut labels, #496; readiness table with hours per audience; full number as weighted sum 49%; earlier: second look: ready 40% → 47%, mainstream 55% added; core-workflow gate applied → alpha) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-11 · **Change:** M14 #307 Plan 3 uses one marker traversal on open and full refresh, and the combined scanner borrows metadata instead of cloning scan-only containers; includes a behavior-preserving `organize` binding for the workspace Clippy gate · earlier: minor (localized shortcut labels, #496; readiness table with hours per audience; full number as weighted sum 49%; second look: ready 40% → 47%, mainstream 55% added; core-workflow gate applied → alpha) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
 > **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-11 · **Change:** minor (closed issues synced: #774, #756 and the #799–#821 batch; earlier: localized shortcut labels, #496; readiness table with hours per audience; full number as weighted sum 49%; earlier: second look: ready 40% → 47%, mainstream 55% added; core-workflow gate applied → alpha) · **Target:** Adobe Acrobat Pro (Acrobat DC, continuous track 26.002.21931, macOS)
 
 PdfCraft's one-page summary: how close it is to Adobe Acrobat Pro's offline feature set, and what
@@ -44,7 +58,7 @@ and add a line to the [progress log](#progress-log); when a gap closes, remove i
 of 0.4–0.5, switching reports such as #179). Two are only partial: editing (no CJK/RTL) and convert
 and share (no in-app Office→PDF; Word export loses layout, #773; password-protected files open in
 Acrobat since #836, #774). Those, unmeasured quality against Acrobat, the borrowed `hayro` renderer,
-no printing on the web and 245 open issues keep it far from beta.
+and 245 open issues keep it far from beta.
 
 ### Readiness by audience
 
@@ -124,7 +138,7 @@ Ranked; detail and the full milestone table in [docs/roadmap.md](docs/roadmap.md
 | Rank | Milestone | Estimate (h) |
 |---|---|---|
 | 0 | Convert and share: Create PDF from Office, Word export that keeps layout (#773) | 32–55 |
-| 1 | Backlog and platform: crash and wrong-result reports, web printing, Chinese UI face (#826) | 65–120 |
+| 1 | Backlog and platform: crash and wrong-result reports, Chinese UI face (#826) | 50–90 |
 | 2 | Fidelity harness against Acrobat and the renderer decision (M2; owner decision on #841) | 110–190 |
 | 3 | Editing existing content (M7) | 100–180 |
 | 4 | OCR languages and Office export/import (M10) | 95–175 |
@@ -135,17 +149,82 @@ Ranked; detail and the full milestone table in [docs/roadmap.md](docs/roadmap.md
 
 ## Progress log
 
+- **2026-10-13 (M3, native-opening candidate):** Chosen tools survive preparation, conversion and password retries; startup intake waits for pending preparation. Regression tests cover completion, cancellation and document identity. Estimates unchanged.
+- **2026-10-12 (M10, Windows printing without PowerShell, #1107):** craft-print now prints on Windows in-process: printers from EnumPrinters/GetDefaultPrinter, jobs drawn as vectors by Windows.Data.Pdf into the XPS print API with a driver-validated PrintTicket (exact paper, orientation, no scaling), so printing works where App Control for Business or AppLocker run PowerShell in Constrained Language Mode. Portrait and landscape sheets still print as one job (turned with /Rotate); a sheet size the driver lacks is refused rather than shrunk. Pins craft-libs f03ec27 (craft-libs#28); deny.toml allows the storytold/winprint.rs fork and adds a webpki-root-certs licence exception and a RUSTSEC-2024-0370 ignore for winprint's build-dependencies. An earlier craft-print revision was checked in Windows Sandbox under enforced WDAC: printers listed, CLI and desktop jobs spooled, and no powershell.exe in the 4688 audit. The final pinned revision passed craft-libs Windows CI, including a real paused-queue job; that Sandbox run has not been repeated. Estimates unchanged.
+- **2026-10-12 (M13, CLI robustness scans):** `pdfcraft-cli check` visits a directory once even when input roots overlap or directory symlinks lead back into the tree. PDFs reached through file symlinks remain accepted. Three real CLI regressions cover overlapping roots, a directory cycle and directory/file aliases. Estimates unchanged.
+- **2026-10-12 (M4, Type 3 extraction fidelity):** Extract and Split preserve shared image/resource dictionaries reached through Type 3 glyphs, including nested forms, patterns and soft masks. A bounded object-graph walk protects unknown glyph content; unreadable pages/forms retain their glyph resources, and shared explicit fonts are visited once. Separate page dictionaries still prune unused images. Synthetic save/reopen regressions and an opt-in Poppler pixel oracle cover resource ownership, nested forms, cycles, limits and repeated fonts. Estimates unchanged.
+- **2026-10-12 (M2, TIFF predictor rows):** Packed RGB images using TIFF horizontal differencing keep every row when samples do not fill the last byte. The renderer aligns each decoded row before moving to the next. Synthetic decoding tests cover 1/2/4-bit samples, horizontal differencing and an 8-bit control; a red/green page-render regression verifies visible output. Estimates unchanged.
+- **2026-10-12 (M3, #1364 candidate):** Absolute local GoToR links wait for Allow/Cancel before target-file access. Pending requests preserve their source and page/view destination; relative links retain their existing behavior. Headless `link_open` requires explicit `allow_absolute: true`, preserving existing root, symlink, file and password validation. Estimates unchanged.
+
+- **2026-10-12 (community, M7, inline Arabic ActualText):** A single-glyph lam-alef `/ActualText` span joins its surrounding word in Edit text instead of splitting it into separate lines. Pure RTL ligature text is put in visual order before line assembly and recovered to typing order with its neighbours. Multi-glyph and mixed-direction replacements retain their authoritative order. Synthetic regressions cover lam-alef variants, marks, two-byte glyph codes, nested spans, replacement and save/reopen. Estimates unchanged.
+- **2026-10-12 (M5, #1398):** A stamp placed on a page with `/Rotate` reads upright as that page is displayed. Rubber stamps (including Sign Here), natural-size and explicit-rectangle images, and PDF-page stamps counterrotate their appearance; restyling a picture stamp keeps that correction, and a saved file reopens the same way. Estimates unchanged.
+- **2026-10-12 (M10, file formats):** Create PDF reads BigTIFF scans; a malformed GIF header is no longer detected as an image only to fail conversion. file-format-parity.md now lists XDP data import/export for XFA forms (already shipped under `form.xfa-data`) separately from opening `.xdp` as a document. Estimates unchanged.
+- **2026-10-12 (gap 6, #1317, #1327, #1302, #1315, #1340):** Flattening keeps a visible comment it cannot draw, such as a cloudy square with no stored appearance, and still draws a solid square, a hidden comment and a cloudy square that already has an appearance. A text box another program drew is left unchanged when a restyle or resize is refused. Make Current Properties Default on an arrow updates the Arrow tool and leaves plain lines alone. A custom text match that ends on a reconstructed word or line separator no longer includes the next glyph. The vertical-writing redaction refusal still fails closed, and its message no longer says the text was under the mark. Estimates unchanged.
+- **2026-10-12 (M12, text-only auto-tag):** Automatically tag PDF now writes marked text objects, paragraph tags, a Document element and a parent tree for untagged text-only PDFs. The result is undoable and opens the Tags panel for review. Mixed paint, forms, annotations, existing tags and malformed streams are refused before mutation. Synthetic two-page engine and tool tests check the tree, checker, unchanged rendering and save/reopen. Richer content and role classification remain open. Estimates unchanged.
+- **2026-10-12 (M7, #1316):** Replacing a line or paragraph no longer removes a distinct neighbour whose glyph box overlaps the edited line. A second drawing is removed only when it also sits on the same baseline, so fake-bold and invisible copies still go. Synthetic regressions cover 6 pt leading, the same word on the next line, ordinary spacing, a separate paragraph, same-position copies, and incremental and full save/reopen. Estimates unchanged.
+- **2026-10-12 (M1, #1339):** An incremental save of an unchanged classic-table file used to append `xref` and then `trailer` with no subsection, which qpdf reports as a damaged file. The section now has a zero-length subsection, so no object entry changes and a trailer-only edit is still written. Estimates unchanged.
+- **2026-10-12 (M12, auto-tag preview):** The engine and `accessibility_autotag_preview` propose paragraph and large-heading roles for bounded text blocks on one page, with locations and reasons. Every proposal needs review; images remain unclassified. No PDF tags are written yet. Synthetic tool tests cover normal text, a larger heading, bounds and unchanged source bytes. Estimates unchanged.
+- **2026-10-12 (M10, editing OCR text on scans):** Editing a recognised word on a scanned page now changes what the page shows. Before, the rewrite stayed invisible OCR text, so the scan still showed the old word; on a form, the whole OCR layer also grouped into one paragraph that rewrapped when one word changed. OCR words now group into phrases (a table cell or a tab stop splits them, and lines stay apart); an edit draws the phrase visibly in the scan's sampled ink colour over a cover in the sampled paper colour, keeping each word's width and growing rightwards. The editor covers the scanned word while typing. OCR words are now sized from their letters (a capitals-only word's box spans the cap height, not the full ascender-descender span), so recognised and rewritten text is as tall as the scanned word and sits on its baseline. Five engine tests on synthetic scans and a kittest UI test; `ocr.editable-text-output` is partial.
+- **2026-10-12 (M2, Lab Bradford follow-up):** Lab white-point adaptation scales Bradford LMS cone responses using LMS white-point ratios. Independent D50 and equal-energy neutral/chromatic render oracles, D65 identity, direct/Indexed consistency with asymmetric chromatic Range, and degenerate-cone fallback cover the correction. CalRGB and the merged Indexed/Range scaling retain their behavior. Estimates unchanged.
+- **2026-10-12 (community, M14, recovery metadata):** A recovery snapshot whose metadata is missing, damaged or names another snapshot is no longer deleted when the folder is listed: it is offered for recovery without an original path (Save asks for a destination), and encrypted snapshots still ask for their password. Recovering one writes fresh metadata in place of the damaged file, and clearing the folder also removes metadata left without a snapshot. Before, a failed metadata write meant the next start deleted the finished snapshot. Synthetic regressions cover the failed write, missing, corrupt, mismatched and encrypted cases. Estimates unchanged.
+- **2026-10-12 (M7, Arabic ActualText):** Add text records each shaped line in typing order with `/ActualText`, so copy and search preserve mixed Arabic, Latin, digits and brackets. Edit text keeps the logical order supplied by `/ActualText` instead of reversing Arabic or Hebrew a second time. Adjacent visual glyph runs retain their own bidi recovery. Font-independent tests cover Arabic marks, numbers, Latin words, reopen and complete replacement; automation checks saved editor text and unchanged rendering. Font fallback and bidi typing remain separate gaps; estimates unchanged.
+- **2026-10-12 (M5, Fill & Sign text size):** The active Fill & Sign toolbar now chooses 4–300 pt for new text and dates; the in-place editor and saved annotation use that size, which persists in local settings. `fill_sign_add` accepts the same `font_size`. Feature and readiness estimates unchanged.
+- **2026-10-12 (community, M3, Greek search):** Case-insensitive Find treats normal, final and capital sigma (`σ`, `ς`, `Σ`) as the same letter, so `κόσμος` and `ΚΌΣΜΟΣ` find each other. Case-sensitive and whole-word options, glyph ranges and match limits retain their behavior. Synthetic text-search regressions cover both directions. The tab-menu regression selects the platform's Reveal label (Finder on macOS), restoring the macOS test without changing the menu. Estimates unchanged.
+- **2026-10-12 (M2, soft scans):** A shrunk, interpolated, axis-aligned image (a 300 dpi scan on a screen) is snapped to whole device pixels and shrunk once, not resampled a second time at a fractional scale and offset. On a synthetic scan page the error against an area-average reference fell from 3.4 to 1.6 grey levels at 96 dpi, and edge sharpness is within 2% of the reference (was 10% soft). Rotated, skewed, flipped and non-interpolated images are unchanged; downscaling of those is still open.
+- **2026-10-12 (M14, Lithuanian localization):** Added Lithuanian as another interface and date language alongside the existing languages, with a 2,578-entry catalog and three-form plurals. Calendar, inspector and password-dialog regressions check localized labels and unchanged document values. The contributor has reviewed the translation as a native Lithuanian speaker. Estimates unchanged.
+- **2026-10-12 (M12, XFA scripts turned off):** When a runaway script turns an XFA form's scripts off, the app now says so: a toast as it happens (at open or after a click), and the notice bar from then on, ahead of its other notices, with a JavaScript Console button. Before, the error was only in the console, so calculations and buttons just stopped. A notice bar the user had closed comes back for it; closed again, it stays closed. The engine reports the state (`Document::xfa_scripts_off`, and `xfa_scripts_off` in `doc_info`) instead of the UI reading error text. Two kittest UI tests (a runaway at open; a runaway click after the bar was closed), engine assertions and a `doc_info` tool test. Overall unchanged.
+- **2026-10-12 (M14, Windows low-DPI font-hinting candidate):** The Windows policy disables symmetric rendering for embedded JetBrains Mono only. On the locked-font macOS probe, horizontal alpha-edge energy per ink improves 2.78%, 3.87% and 1.59% at 100%, 125% and 150% scaling, and is down 0.79% at 200%; Inter is pixel-identical. Logical layout hashes and 8 MiB atlas size match, repeated fractional offsets add no atlas dimensions, and baseline/candidate time and RSS ranges overlap. Windows runtime and hardware remain unverified; estimates unchanged.
+- **2026-10-12 (M7, #1200 candidate):** Bounded local GoToR file specifications open in desktop tabs; explicit numeric page views apply, while named destinations open at the default view with a warning. The automation tool resolves relative to the source and uses existing `--root` confinement. Appearance-only Link Properties edits preserve the existing action. URL/network paths remain refused; `/NewWindow` is a tab hint. Estimates unchanged.
+- **2026-10-12 (M7, private image crops):** Exclusive image crops resize with their pixels across nested states, intervening operators and content streams; shared clips remain fixed. Synthetic engine/tool regressions and private image save/reopen checks; estimates unchanged.
+
+- **2026-10-12 (M12, accessibility finding locations):** Checker findings for figures, annotations and form widgets carry verified page bounds. Selecting one flashes its location; the headless check returns the same PDF-space rectangle. Malformed annotation rectangles remain page-only findings. Guided review and tagging estimates unchanged.
+
+- **2026-10-12 (M14, gap 13, large-file memory):** Measured on synthetic 1 GiB and 100,000-page files. Edits let go of the previous working file (working bytes, display bytes, renderer) before writing the next, so a 1 GiB file peaks at two copies while editing instead of three (five edits: 3.1 → 2.1 GiB, 16 → 8.5 s). Saving still peaks at three; reading from disk on demand is blocked on the renderer (gap 2). Estimates unchanged.
+- **2026-10-12 (M2, short text redraws):** Same-line redraws that restart a matching three-glyph prefix after more than one glyph-height of progress split before placement, so short doubled words no longer interleave. The existing redraw-position tolerance is reused; controls cover negative TJ movement, combining marks, RTL, CJK, vertical and turned text. Estimates unchanged.
+- **2026-10-11 (M5, #1191):** Quick-bar colour changes now restyle the selected comment when it matches the active comment tool, while continuing to update that tool's default; added an accessible label to the swatch controls and a UI regression proving the saved style and undo step. Estimates unchanged.
 - **2026-10-11 (M10.5, focused follow-up to #599):** Carry the architectural/ANSI/large ISO paper presets, current-page matching at 100%, and previewed PDF scale into the current print dialog and `doc_print`. Retains the #847/#1007 spooler and background discovery. Driver substitution, physical calibration, vector Windows printing and managed-endpoint restrictions remain separate gaps. Overall estimates unchanged.
 
+- **2026-10-11 (contributor fork, M7):** Full matching font import completes source-subset glyphs; installed/file font selection, TrueType/OpenType-CFF mapping, disjoint range styles, marked paragraph boundaries and single-face contextual shaping/bidi added. Private Chinese keyboard edits on all four pages preserve source anchors and save/reopen renders. Curved clips exclude holes from hit tests; shared path scopes are isolated for image transforms without moving neighbouring paint. No font binary or private fixture is published; release font inputs and readiness estimates unchanged.
+
+- **2026-10-11 (M7, cropped image resize follow-up):** Resize from the visible (clipped) frame; an image's own clip moves with it (#1049) and shared clips stay fixed. Selected corner grips keep control over overlapping text; horizontal/vertical-only shrinking responds without freezing; one drag frame is previewed and one edit is applied on release. Synthetic pointer/tool regressions and private grow/shrink/save/reopen/undo rendering checks cover the regression. Shared clipping scopes containing unrelated painted content are refused. Estimates unchanged.
+
+- **2026-10-11 (M7, cropped artwork selection):** Image/Form inventories now expose page/path-clipped visible bounds while retaining full placement geometry for transforms. Edit clicks prioritize text over background artwork; image frames stay within their own page and fixed clips remain fixed during movement. Engine/tool/UI regressions and an opt-in four-page private-file test cover direct access to 73 text regions and five cropped placements. Rectangular clips are exact; curved/complex clips use conservative bounds. Estimates unchanged.
+
+- **2026-10-11 (M7, live text editor follow-up):** Reuse validated embedded sfnt source faces; adapt Mac format-6 subset cmaps through PDF Unicode mappings in memory without changing or installing source fonts. Preserve source baseline positions on entry. Show draft text and a single frame that grows/shrinks as rows are added or removed; single rows can grow toward the page edge. `text_edit_layout` exposes read-only draft bounds through the engine and automation. Licensed synthetic font/frame regressions and an opt-in all-page private-file check cover source font usage, stable positions, typing and deletion. Unsupported source programs, shaping and installed-font selection remain limited; estimates unchanged.
+
+- **2026-10-11 (M7, mixed-style regions follow-up):** Group adjacent source runs into visual rows and aligned rows into regions across subset fonts, colours, weights and text-matrix sizes. One inline TextEdit uses styled spans and source row breaks; rewriting preserves surviving source-run styles, source subset encodings and centered mixed-size title alignment. Added engine, automation and UI regressions for edit/delete, read-only preview, save/reopen and undo; privately verified the supplied real PDF's three-row title and six-row body, including selecting both in one editor without extra rows. `text_paragraphs` exposes `editor_text` and `rows`. Installed-font selection, exact editor glyphs, complex shaping and arbitrary multi-range style edits remain open. Readiness estimates unchanged.
+
+- **2026-10-11 (M7, contributor fork):** Join compatible words across text objects and subset-font spaces; preserve source fonts that lack a space glyph using text positioning; recognize component colour operators. Inline editing uses one editor frame, resets its available width when switching blocks, keeps source line breaks, and renders a COS-clone background without the original glyphs, preserving unselected text advances. `page_render.hide_text_block` exposes the same read-only preview. Mixed-style paragraph grouping, installed-font selection and exact source-font editor rendering remain open.
+
 Newest first: the date, what moved, and the new overall estimate.
 
+- **2026-10-12 (M3, GNOME title bar, #553):** On GNOME's Wayland session, whose compositor draws no window frames (it offers no `zxdg_decoration_manager_v1`), PdfCraft no longer shows winit's fallback title bar: it turns the frame off and the tab strip becomes the header bar, as in GNOME's own apps. Minimize, maximize/restore and close are drawn in Adwaita's style, in the order and on the side GNOME's `button-layout` names (Fedora's default shows only close); the window's edges and corners resize it, and a hairline outlines it while it isn't maximized. Preferences ▸ Use system title bar (shown only there) gives the window back winit's frame at once, without a restart (part of #1001), and `PDFCRAFT_TITLEBAR=app|system` overrides the choice. KDE, Sway, Hyprland, COSMIC and X11 keep the frame their desktop draws. Not done: right-clicking the header bar doesn't open GNOME's window menu (egui can't ask for it), the window has no shadow or rounded corners, the resize edges lie just inside the window rather than outside it, and Windows still uses its system frame (the rest of #1001). Estimates unchanged.
+- **2026-10-12 (M0, build label):** A local or patched build can carry a label, set at compile time with `PDFCRAFT_BUILD_LABEL`: `pdfcraft --version`, `pdfcraft-cli --version`, About and the log show `0.7.1 (titlebar)`, and `packaging/linux/package.sh` names the files `pdfcraft-0.7.1-titlebar-…` and makes the .rpm/.deb release `1.titlebar`, which upgrades over the release of the same version (and the next release over it). The version itself is unchanged, so the update check still compares it with published releases. Unlabelled builds are as before. Estimates unchanged.
+- 2026-10-11: Organize Pages shows an editable, synchronized physical page-range selection (#1092), with bounded validation and UI/operation regression coverage; overall estimate unchanged.
+
+- **2026-10-11 (M5.7, scanned signatures, #1110):** Fill & Sign ▸ Add signature has a Scan tab: a phone photo of a signature on paper is framed automatically (all words; table, sheet edge and dust ignored; a sideways signature turned upright), the frame can be moved, resized or redrawn, the photo turned, and an ink-sensitivity slider picks up faint ink. A morphological paper estimate removes shadows and uneven light, and the trimmed ink is saved and reused like an image signature. Photos and images can also be dropped on the Image and Scan tabs. Photos keep the image-signature limits (#1124: a 4 MiB file, up to 32 megapixels decoded, scaled down to 4 megapixels), so a scan never processes more than 4 megapixels. `fill_sign_add` takes `scan` and `sensitivity`. Synthetic engine, UI and automation tests; checked by hand on real phone photos. Milestone and effort estimates unchanged.
+- **2026-10-12 (M10.5, hosted CI):** Integrated current main, including its date-table formatting and static-storage fixes. The Arabic synthetic drawing regression now checks the original serialized-output golden with and without the optional font face: the face-dependent FontName and FontFamily are checked separately and normalized only in the fixture. The hosted FreeBSD fingerprint is reproduced by those two metadata fields alone. Drawing bytes and all other fields retain the original golden; no printing behavior or readiness estimate changes.
+- **2026-10-11 (M3, animation effects):** PdfCraft follows Windows' Settings ▸ Accessibility ▸ Visual effects ▸ Animation effects, and Preferences has its own Animation effects: Use system setting (the default), On or Off. With animation effects off, a wheel notch scrolls its whole distance, and Ctrl with the wheel zooms its whole step, in the frame it arrives. Both were eased over about a quarter of a second whatever the setting: egui spreads a coarse wheel step over later frames and has no switch for it, so `crates/ui-egui/src/motion.rs` reads each frame's wheel input the way egui does, minus the easing, and hands that to the scroll areas and the views (a test sums what egui eases and compares it with what is read at once, and fails if egui stops easing). egui's own animations (menus, sections, scrolling to a row) take no time, the chrome's hover and press washes are simply there, and the progress card's bar steps without its sweep. The desktop app asks WinRT's `UISettings.AnimationsEnabled` at launch and every two seconds of use, so a change applies without a restart. How far a notch scrolls or zooms is unchanged. The preference set to On or Off decides all of this whatever the system says; it is saved, set as `animation_effects` (`system`, `on`, `off`) on the control channel, and translated in all 20 catalogs. Not done: macOS (Reduce motion), Linux (GNOME's animations switch) and the browser (`prefers-reduced-motion`) aren't asked yet, so Use system setting animates there as before; Off works everywhere. Estimates unchanged.
+- **2026-10-11 (M10, gap 4):** The web build prints. Its Print dialog offers "Browser's print dialog" (the default there), which reaches every printer the operating system knows. PdfCraft draws the print-ready PDF's sheets itself with its own renderer, a sheet a frame because the web build has no threads: 300 dpi up to 100 sheets, 200 up to 300, 150 up to 1,000, at most 64 megapixels a sheet and 1 GiB of pictures a job. It then prints them from a hidden iframe, one sheet per printed page with no margin. A landscape sheet among portrait ones is turned onto the paper, as a driver does, because Chromium prints every page at the default `@page` size. Copies, two-sided and colour are set in the browser's dialog, so the dialog greys them out. If the browser refuses to print (a sandboxed frame, for example), the print-ready PDF downloads instead. Verified in headless Chromium: the right sheets at 300 dpi, the landscape sheet turned, no blank trailing page, and the download fallback. Not yet tested in Firefox or Safari. Gap 4 closed; rank 1 is 65–120 → 50–90 h; other estimates unchanged.
+- **2026-10-11 (M10.5):** Extracted printer discovery, options and PDF submission into craft-libs/craft-print, shared with DesignCraft. Windows preserves composed sheet size and orientation without fitting into default margins; duplex binding edges are corrected. PdfCraft retains permission checks and imposition. Shared transport and local composition, engine, automation and UI coverage validate the boundary; native Windows CI passes, including paused-queue submission and cleanup; physical printer fidelity remains a hardware check. Rust 1.95 is required by the shared crate. No readiness percentage change.
+- **2026-10-11 (M10, #1028):** Recognize Text can read pages that already have text: "Also recognize pages that already have text" in the dialog (remembered with the other choices, and used by Recognize text in multiple files) and `skip_text_pages: false` on `ocr_recognize` and, newly, `ocr_recognize_files`. A picture on such a page becomes searchable, and a recognised word at least half covered by the page's own text (an earlier OCR layer included) is left out, so nothing is found twice; `ocr_recognize` reports how many were left out as `already_on_page`. Before, the option existed only for agents and added the page's text a second time. The default still skips pages with text. Synthetic tests (a picture of a sentence plus real text) cover the engine, the tool and the dialog, and fail with the filter turned off. Still missing: reading only the picture areas (the whole page is read, as for a scan). Separately, `recognize_text_makes_a_scanned_page_searchable` fails on main wherever the models are installed (the model reads "quick" as "auick"). Estimates unchanged.
+- **2026-10-11 (M2, page-label prefixes):** The page-label readers bound the total size of decoded prefixes. Each range decodes its own prefix, and ranges may share one prefix object, so a small file could ask for a copy per range: within the 200,000-entry tree limit, about 200 MiB of copies of one 1,024-byte prefix. Inspection and Organize now refuse a tree whose decoded prefixes pass 4 MiB in total (`MAX_PREFIX_TOTAL_BYTES`), before any label is made, as the other tree limits do; relabelling such a tree changes nothing. Synthetic tests share one 1,000-byte prefix across 5,000 ranges and keep exactly 4 MiB of prefixes readable. Overall estimate unchanged.
+- **2026-10-11 (UI, checkboxes and radio buttons):** Checkboxes no longer look like radio buttons, and on the light theme neither is invisible. With the theme's 6 px widget radius egui drew a checkbox's 14 px box as a circle, so View ▸ Page display's Continuous scrolling and Show cover page read as two more layout choices; on the light theme an unticked box or an unselected radio button was white on white with no edge. Every checkbox (81) and radio button (79) now goes through `widgets::checkbox` / `widgets::radio` / `widgets::radio_value`: a 1 px outline (darker on hover), the plain fill on the light theme as dialogs already had, and for checkboxes a rounded-square box (3 px), keeping what the caller set (dialogs, the search panel). `clippy.toml` disallows `ui.checkbox`, `ui.radio`, `ui.radio_value`, `egui::Checkbox` and `egui::RadioButton` so new ones use them too. Estimates unchanged.
+- **2026-10-11 (M13, #971):** `text_find` now bounds each page's temporary match-range list to the remaining result limit plus one, which is enough to detect and return a continuation without allocating every match on a dense page. Added limited-search coverage; the existing end-to-end continuation test passes. The text cache byte budget and per-page extraction warnings remain open.
+- **2026-10-11 (M7, #594):** Ordinary paragraph body drags now use the existing source-preserving object translation path; edge drags still rewrap. An in-progress drag is discarded if the document generation changes, and added-content gestures keep their own edit handler. Added real-shell source regressions for overlapping and identical labels, history, save/reopen, partial overlap, kerning, rotation/crop/UserUnit and atomic refusal. Linux validation passed: focused UI/engine regressions, exact-base source-loss failures, native drag/undo/redo/save/reopen with independent Poppler renders, and all eight CI gates. Text replacement and resizing over unrelated overlapping content remain outside this repair. Estimates unchanged.
+
+- **2026-10-10 (community, M7, Thai Add Text):** Optional craft-fonts Thai face (Noto Sans Thai) for the UI and shaped Add Text through the engine, CLI and MCP. Stacked marks and Sara Am are kept through Type 3 clusters with ToUnicode; regular style, and wrapping at cluster boundaries (no dictionary word segmentation). The craft-fonts pin for CI and releases moves to the revision with the Thai face. Forms and Fill & Sign are outside this change. Estimates unchanged.
 - **2026-10-11 (#995, #1077, permissions password after opening):** A PDF with only a permissions password opens without asking, restricted, and nothing let the user enter that password afterwards: the notice and the hint pointed at reopening with it. Now the security notice and Properties ▸ Security offer Unlock…, and Change settings / Remove security on a restricted document ask for the permissions password first and then carry on (as Acrobat does). The open password is refused there. `Session::unlock` upgrades the open document in place (owner and user passwords unlock the same file key, so nothing is re-read), unlocks the undo and redo states and reopens saves as owner; it is not an edit and doesn't mark the document unsaved. New command `protect.unlock`; the new strings are in all 15 full catalogs. Tests cover crypt, cos, engine (undo, redo, save, separate open password) and the UI. Still missing: an automation tool for it. Estimates unchanged.
 - **2026-10-11 (M14, #307 Plan 3):** Engine open and full refresh use one page/content traversal to populate marks and added content. The independent public scans remain available; the combined scanner borrows direct objects and holds referenced objects through `Arc<Object>` instead of cloning scan-only `/Contents` arrays or `/PCAdded` dictionaries. Differential tests cover an indirect `/PCAdded` dictionary as well as ordering, malformed/direct/indirect/repeated entries and `/UserUnit`. Exact `bbbe600`→final release CLI measurements used 10 alternating pairs: wall-time medians were 183.645→174.440 ms on 10,000 marker-free pages (10/10 wins), 33.587→32.752 ms on 1,500 mixed pages (8/10), and 24.331→20.133 ms on the 100,000-entry array stress fixture (10/10). The stress fixture's maximum-RSS median fell 28,655,616→19,038,208 B; peak-footprint medians were 14,747,136→14,673,408 B. From P0, the follow-up stress run was 20.886→20.201 ms (10/10), with RSS 23,953,408→19,087,360 B and peak footprint 14,706,144→14,697,952 B. `doc_open` stdout hashes matched every pair. The ancillary `organize` binding preserves the prior `prune_legacy` update condition. Estimates unchanged.
 - **2026-10-11 (M4, Organize overview):** Opening Organize pages from All tools, Home, the tool palette or `ui.set tool=organize` opens the thumbnail grid directly. Checkboxes toggle individual pages without modifier keys; page controls rotate either way or delete one page, while the toolbar acts on the selection. Portrait and landscape previews retain their aspect ratio. UI and control regressions cover entry, selection, single-page versus batch actions, undo, permissions and retaining the last page. Milestone and effort estimates unchanged.
 
+- **2026-10-11 (M5, partial comment imports):** Replacing an editable named comment through XFDF or FDF (including an indirect name in the source PDF) preserves its object identity, so existing replies and review statuses remain attached after saving, reopening and exporting again. Replaced pop-ups are still removed. Locked comments, redaction marks and their pop-ups stay unchanged, including when their names are indirect; imported redactions remain visible. Synthetic round-trip tests cover both formats, incremental and full saves; milestone and effort estimates unchanged.
+
 - **2026-10-10 (M9, signature graphics):** A visible digital signature can show a graphic where the signer's name is large, as Acrobat's Configure Signature Appearance does: the saved Fill & Sign signature (drawn strokes smoothed as ink, typed outlines in the script font, or an image) or an imported PNG/JPEG. Sign as previews it and remembers the choice for the next signing; `sign_document` takes `graphic` (`image`, `text` or `strokes`). Graphics are checked and capped before drawing (non-finite or unbounded points, mismatched pixel buffers, oversized images are refused with an error the caller can act on); images keep their alpha as a soft mask. `sign.signature-appearance` stays partial (no named saved appearances or PDF-page graphics). Overall estimates unchanged.
 - **2026-10-11 (M14, absolute interface sizes):** A chosen Interface size is now absolute, as PhotoCraft's UI Scale is: "100%" is one screen pixel per point whatever scale the display reports, so on a 1080p screen whose system reports 200 % it draws at a true 100 % (#456, reported after the first change). Auto still keeps the display's scale and adds GNOME's text scaling, and its menu entry shows the size it draws at. The menu offers PhotoCraft's sizes (75–300 %).
 - **2026-10-11 (automation, #971):** `text_find` reads pages in growing batches (8, doubling to 128) and stops once `limit` is reached, so a bounded search on a long document no longer extracts and caches every page first. Results say `complete`, and a capped one gives `next` (`start_page`, `skip`) to continue. Still open from #971: a byte budget for the automation text cache and per-page warnings for pages whose text can't be extracted.
+- **2026-10-11 (M10, #773 integration):** Merged current upstream updates into the Word export fix and adopted the shared Windows symlink test setup. Word layout scope and estimates unchanged.
+- **2026-10-11 (M10, #773):** Word export no longer invents visible borders for tables inferred from text alignment. Rotated text, and pages where text overlaps an image or a watermark-sized text block, use positioned, editable shapes so invoice watermarks do not reserve body space (pages whose logo or title sits clear of the text keep flowing paragraphs, tables and inline images); source pages have separate sizes and section breaks. Synthetic export and automation regressions cover the invoice failure. Exact font matching, vector rules and general layout fidelity remain partial; estimates unchanged.
 - **2026-10-11 (docs, closed issues):** The progress docs caught up with issues closed on 2026-10-10: encrypted output opens in Acrobat (#774, #836; gap 1 closed, rank 0 is 32–55 h), Windows prints (#756, #847), column select (#740), 1:1 touchpad scrolling (#759), same-page multi-object move (#844), and the #799–#821 batch of wrong-result fixes including the #816 panic. Scores and readiness not re-judged; overall estimate unchanged.
 - **2026-10-11 (M7, watermark placement):** A watermark can be moved from the page centre by a horizontal and a vertical offset in points: Add/Update Watermark has an "Offset from centre" row (the preview follows it, for text and for pictures) and `doc_watermark` takes `offset_x` and `offset_y`. A non-finite offset is refused instead of written into the page. `edit.watermark-appearance` stays partial: no offset from the page edge or in page units, no print/screen-only variants, no repeat. Image and PDF watermarks, already shipped, no longer appear as missing. The overall estimate is unchanged.
 - **2026-10-11 (M12, XFA script time limits):** An XFA script's time limit (1 s for scripts that run unasked, on open and on every change) counted the engine's start-up too: the script's thread, a new context and, for the first script in a process, the engine's own set-up (≈ 60–170 ms when idle). On a busy machine a trivial initialize script could pass the limit, be abandoned and turn the form's scripts off; that made `xfa_buttons_run_their_scripts_in_the_app` and `messages_from_scripts_run_on_open_show_right_away` flaky (under full CPU load 25 of 40 runs of the test binary failed, with "ran longer than 1.0 s and was abandoned" in the console). The limit now runs from when the engine is ready; start-up has its own 10 s cap, so nothing waits forever, and a trivial warm-up script takes the first-in-process set-up. Under the same load none of 40 runs fails, and runaway scripts are abandoned as before. The two UI tests print the script console when they fail. Overall unchanged.
@@ -161,6 +240,8 @@ Newest first: the date, what moved, and the new overall estimate.
 - **2026-10-11 (M14, #307, Plan 2):** Forms now return terminal fields and the page-widget adoption count from one enumeration, and engine open reuses that result while retaining XFA script-button marking. The 12,000-page/no-form PDF (1,442,052 bytes) and 2,500-orphan-widget PDF (673,432 bytes) produce byte-identical `doc_open`/`doc_info` outputs against upstream `33c14e07cfd742a82bf03baa6b103c01008fa68c`, including the orphan repair note. After one warm-up per binary and three interleaved base/candidate rounds, median open times were 0.16/0.15 s and 0.08/0.07 s, with median peak RSS 62.69/59.98 MiB and 33.28/32.20 MiB. Workspace tests, Clippy, formatting, focused forms/engine/organize tests, and the WASM check pass. A behavior-preserving local binding in `organize` also lets the workspace Clippy gate pass. No estimate change.
 - **2026-10-11 (M14, Traditional Chinese semantics):** Corrected accessibility pass/fail labels, the inverted script-accessibility rule, Taiwan row/column terminology and form choice/read-only labels; added the missing table-row explanation. Catalog regressions cover the rule metadata and preserve field names. Milestone and effort estimates unchanged.
 
+
+- **2026-10-11 (M14, no silent `?`):** Text PdfCraft's fonts can't draw (Chinese, Greek, Czech's ř in Helvetica) is never written into a PDF as `?` without a word. Form values and button captions, text boxes, callouts, Fill & Sign text, measurement labels and dynamic stamps' by-lines are kept as typed, as Acrobat keeps them: the appearance draws `?` there, the annotation is marked (`PCUndrawn`), and the edit says so (the interface shows a translated notice; tools return `warnings`). A form also sets `/NeedAppearances`, so other viewers redraw the field from its value (not in a PDF/A document, which forbids it); a restyle doesn't replace a comment another program drew with those characters. Where `?` would be permanent, the edit is refused with the character and what to do instead: flattening what PdfCraft drew with `?`, redaction overlay text (also checked before anything is redacted), typed signatures through `fill_sign_add`, visible signature details, and new documents from text (with the line). Reports PdfCraft writes from documents (comment summaries, compare reports) write such characters as `[U+XXXX]` and say so; a dynamic XFA form's own text is laid out and reported. One end-to-end test drives every path through the tools. Not yet: drawing those characters (embedding a font that has them). Overall estimate unchanged.
 - **2026-10-10 (M14, interface size):** Preferences ▸ Interface size scales the whole interface (50–250 %, setting `ui_scale`, control option `ui-scale`); 50 % brings an interface the system draws at 200 % back to 100 % (#456). Auto, the default, follows the desktop's text scaling: on Linux and the BSDs the desktop app reads GNOME's `text-scaling-factor` once at launch, so with Large Text (1.25) on a 1× display the interface no longer draws 13 px labels that show their pixels next to the system's text. The size is egui's zoom factor, so `pixels_per_point` grows with it and page rasters stay one texel per screen pixel; egui's own ⌘+/⌘− interface zoom is turned off so those keys stay page zoom. Still missing: KDE's font DPI and Windows' "Make text bigger" aren't read (both scale only text there), and egui's text is still greyscale-antialiased without the system's gamma, so small text looks rougher than GTK's at 100 %.
 - **2026-10-10 (M14, #496):** Shortcut displays share a UI formatter across toolbar search, registry menus, command palette, Help and tooltips. Modifier and key names use a dedicated catalog context in every bundled translation; missing entries keep the English key name rather than a command translation. German shows Strg/Umschalt/Entf, macOS retains its symbols, and runtime language changes refresh the display. Regression coverage checks localized layout widths, English/German switching, platform conventions and unchanged command execution. Milestone and effort estimates unchanged.
 
@@ -209,6 +290,7 @@ Newest first: the date, what moved, and the new overall estimate.
 
 - **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 (community, M7, Hebrew in Edit text):** Editing existing Hebrew text showed it reversed (`בדיוק` read back letter-reversed) and wrote replacement boxes on save. Content streams draw right-to-left lines in visual order; Edit text now reads lines and paragraphs in typing order and writes them back in drawing order (`pdfcraft-edit::bidi`, UAX #9 through `unicode-bidi`, with numbers, Latin and mirrored brackets; where visual order allows several readings, the one that draws back exactly and pairs its brackets wins). Right-to-left paragraphs are right-aligned unless an alignment is chosen, and a single line keeps its right edge as it grows. Letters the page's font lacks are drawn with a craft-fonts `Hebr` face (Noto Sans Hebrew, storytold/craft-fonts PR) as Type 3 glyphs with ToUnicode, so the result is searchable; the interface uses that face too, and the web build keeps it. Without it, a clear error and no change. `edit.rtl-cjk-editing` moves to partial. Not yet: niqqud in replacement text (refused, not misdrawn), Arabic in Edit text (shaping; Add text has it since #403), typing right to left in the box (#437), lines drawn word by word from the right; the release craft-fonts pin must move to a revision with the Hebrew face. Overall estimate unchanged (about 30–35%).
 - **2026-10-09 (M2, bounded page labels):** Inspector number trees have shared work, depth, and cycle limits; prefixes are bounded before decoding and complete custom labels have per-label and aggregate UTF-8 byte caps. A refused tree leaves physical page numbers intact and records one warning, with custom labels applied only after every range succeeds. Pure COS Roman and repeated-letter formatters are shared with Organize; label queries and edits return errors for unsupported output before changing the stored tree, while ordinary labels and prefix-only ranges remain supported. Synthetic tests cover safe just-over-limit cases, large first numbers, aliases, cycles, wide/deep trees, UTF-16/UTF-8 boundaries, aggregate output, and unchanged refused edits. Milestone and overall effort estimates unchanged (about 30–35%).
 - **2026-10-09 (M4, page grid zoom):** The Organize page grid zooms from 50% to 300%: toolbar buttons with a percentage that resets, trackpad pinch or Ctrl/⌘ + wheel about the page under the pointer, and ⌘+ / ⌘− / ⌘0. Pages drawn larger than their thumbnails are rendered at the size drawn while in view, so text stays sharp in documents of any length. Not yet: a slider, remembering the size, a size control for the Pages panel. Overall estimate 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%).
@@ -345,7 +427,15 @@ Newest first: the date, what moved, and the new overall estimate.
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-10-12 | minor | M3/#1364 candidate: absolute local GoToR links require desktop consent or headless allow_absolute; existing relative navigation and validation retained. Estimates unchanged. |
+| 2026-10-12 | minor | M8: redaction retires inherited `/Resources` so a parent `/Pages` can't keep a removed XObject reachable; only redacted pages that inherit are pinned (one shared reference), unredacted pages are untouched; estimates unchanged |
+| 2026-10-12 | minor | M7/#1200 candidate: bounded local GoToR opening, root-confined automation, and action-preserving appearance edits; named destinations and window behavior remain partial; estimates unchanged. |
+| 2026-10-12 | minor | Exclusive image crops resize with their pixels across nested states, intervening operators and content streams; shared clips remain fixed. Synthetic engine/tool regressions and private image save/reopen checks; estimates unchanged. |
+| 2026-10-11 | minor | M10: borderless inferred tables and positioned invoice watermarks (#773); estimates unchanged. |
+| 2026-10-11 | minor | M3: Windows' Animation effects setting is followed (wheel scrolling and zooming without easing, no other animations), and Preferences has Animation effects (Use system setting, On, Off). Estimates unchanged. |
+| 2026-10-11 | minor | M7: #594 paragraph-drag candidate and source regressions prepared; subsequent Linux validation passed all eight CI gates. Estimates unchanged. |
 | 2026-10-10 | minor | Recorded the remaining System appearance repair after #881; estimates unchanged |
+| 2026-10-11 | minor | Contributor fork: document-font selection and subset completion, CFF, style ranges, contextual/bidi save/reopen and all-page Chinese keyboard acceptance; curve/hole hit testing (shared clips stay fixed, as on main). Scope remains bounded; percentages unchanged |
 | 2026-10-10 | minor | Readiness table with hours per audience; full number restated as the additive weighted sum over dimensions (47% → 49%; method aligned with the standard, no new evidence) |
 | 2026-10-10 | minor | Essentials-user score added (≈ 66%) |
 | 2026-10-10 | minor | Gate consistency check: convert and share re-judged partial, not blocking; stage pre-alpha → alpha |
@@ -353,3 +443,5 @@ Newest first: the date, what moved, and the new overall estimate.
 | 2026-10-10 | major | Restructured to the progress-docs standard (stage, two numbers, dimensions, features, languages, upcoming, log); full re-measure; assessment, gaps and milestones moved to `docs/`; log sorted newest first and a stray merged entry dated |
 | 2026-10-07 | minor | 806 tracked features, 51.0% shipped, effort-weighted ≈ 30–35%, 600–1,100 h |
 | 2026-10-05 | major | Honest assessment and "Where we're lacking" added |
+
+- **2026-10-12 (M8):** Redaction cleans indirect and form structure references, preserving surviving form tags.

apps/pdfcraft-cli/src/batch.rs

@@ -0,0 +1,61 @@
+//! Friendly flags for the same folder-job tool exposed by `run` and MCP.
+
+use serde_json::json;
+
+use crate::{CliError, OptionSpec, automation, flag, print_output, validate_options};
+
+const OPTIONS: &[OptionSpec] = &[
+    OptionSpec { name: "--root", takes_value: true },
+    OptionSpec { name: "--out-dir", takes_value: true },
+    OptionSpec { name: "--steps", takes_value: true },
+    OptionSpec { name: "--recursive", takes_value: false },
+    OptionSpec { name: "--stop-on-error", takes_value: false },
+    OptionSpec { name: "--ppi", takes_value: true },
+    OptionSpec { name: "--quality", takes_value: true },
+    OptionSpec { name: "--dpi", takes_value: true },
+    OptionSpec { name: "--language", takes_value: true },
+    OptionSpec { name: "--ocr-all-pages", takes_value: false },
+];
+
+pub(super) fn run(args: &[String]) -> Result<(), CliError> {
+    validate_options("batch", args, OPTIONS)?;
+    let mut paths = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    let mut i = 0;
+    while let Some(arg) = args.get(i) {
+        if let Some(spec) = OPTIONS.iter().find(|s| s.name == arg) {
+            if !seen.insert(spec.name) {
+                return Err(format!("batch: {} may only be supplied once", spec.name).into());
+            }
+            if spec.takes_value {
+                if args.get(i + 1).is_none_or(|v| v.is_empty() || v.starts_with("--")) {
+                    return Err(format!("batch: {} needs a value", spec.name).into());
+                }
+                i += 1;
+            }
+        } else {
+            paths.push(arg);
+        }
+        i += 1;
+    }
+    let steps: Vec<_> = flag(args, "--steps").ok_or("batch: missing --steps (convert, ocr, optimize)")?.split(',').collect();
+    let out = flag(args, "--out-dir").ok_or("batch: missing --out-dir")?;
+    let mut params =
+        json!({"paths":paths,"steps":steps,"out_dir":out,"recursive":seen.contains("--recursive"),"stop_on_error":seen.contains("--stop-on-error")});
+    for (option, key) in [("--ppi", "ppi"), ("--quality", "quality"), ("--dpi", "dpi")] {
+        if let Some(v) = flag(args, option) {
+            params[key] = serde_json::from_str(v).map_err(|_| format!("batch: {option} needs a number"))?;
+        }
+    }
+    if let Some(lang) = flag(args, "--language") {
+        params["language"] = json!(lang);
+    }
+    if seen.contains("--ocr-all-pages") {
+        params["skip_text_pages"] = json!(false);
+    }
+    let mut auto = automation(args)?;
+    let content = auto.call("doc_batch", &params).map_err(|e| e.to_string())?;
+    let failed = content.iter().any(|c| matches!(c, pdfcraft_automation::Content::Json(v) if v["failed"].as_u64().is_some_and(|n| n > 0)));
+    print_output(&auto, content, None)?;
+    if failed { Err("batch: one or more files failed; see the JSON report".into()) } else { Ok(()) }
+}

apps/pdfcraft-cli/src/main.rs

@@ -17,6 +17,8 @@
 
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
+mod batch;
+
 use std::io::Write;
 use std::path::{Path, PathBuf};
 use std::process::{Command, ExitCode, Stdio};
@@ -51,11 +53,15 @@ pdfcraft-cli render <file.pdf> --page N [--dpi 96] --out x.png   (.png, .jpg, .t
 pdfcraft-cli text   <file.pdf> [--page N]                  extracted text (pages separated by form feeds)
 pdfcraft-cli edit   <in.pdf> --out out.pdf [--rotate 1,3:90] [--delete 2,4] [--move 5:1]
                       [--insert-blank 1] [--title T] [--author A] [--full]
+                      (options run in order; page numbers refer to the document after the earlier options)
 pdfcraft-cli combine <a.pdf> <b.pdf> … --out combined.pdf
 pdfcraft-cli extract <in.pdf> --pages 1,3,5 --out out.pdf
 pdfcraft-cli split   <in.pdf> (--every N | --before 3,7) [--out-dir DIR]
 pdfcraft-cli check  <files or dirs…> [--timeout 20] [--dpi 36] [--json out.json]
 pdfcraft-cli audit  <file.pdf> [--password PW]            find faux redactions (fails when found)
+pdfcraft-cli batch <files or dirs...> --steps convert,ocr,optimize --out-dir DIR
+                      [--recursive] [--root DIR] [--stop-on-error]
+                      [--ppi 150] [--quality 60] [--dpi 300] [--language en] [--ocr-all-pages]
 pdfcraft-cli tools                                       automation tools and their JSON Schemas
 pdfcraft-cli run    <tool> [key=value …] [--root DIR] [--out image.png]
 pdfcraft-cli run    --script steps.json [--root DIR]      [{\"tool\": \"doc_open\", \"args\": {…}}, …]
@@ -89,6 +95,7 @@ fn main() -> ExitCode {
         Some("audit") => audit(&args[1..]),
         Some("tools") => tools(),
         Some("run") => run(&args[1..]),
+        Some("batch") => batch::run(&args[1..]),
         Some("ui") => ui(&args[1..]),
         #[cfg(feature = "mcp")]
         Some("mcp") => mcp(&args[1..]),
@@ -141,7 +148,7 @@ fn stdout_line(line: std::fmt::Arguments<'_>) -> Result<(), CliError> {
 }
 
 fn version() -> Result<(), CliError> {
-    stdout_line(format_args!("pdfcraft-cli {}", env!("CARGO_PKG_VERSION")))?;
+    stdout_line(format_args!("pdfcraft-cli {}", pdfcraft_engine::build_info::version()))?;
     stdout_line(format_args!("Discord: {}  (help and feedback)", pdfcraft_engine::links::DISCORD))?;
     stdout_line(format_args!("Web:     {}", pdfcraft_engine::links::APP_PAGE))?;
     stdout_line(format_args!("Source:  {}", pdfcraft_engine::links::GITHUB))?;
@@ -151,6 +158,7 @@ fn version() -> Result<(), CliError> {
 /// Audit a document for faux redactions. Prints the findings as JSON; fails when any are
 /// found so scripts and CI can gate on it, and when the audit itself cannot run.
 fn audit(args: &[String]) -> Result<(), CliError> {
+    validate_options("audit", args, AUDIT_OPTIONS)?;
     let path = *positional(args).first().ok_or("audit: missing file")?;
     let bytes = read(path)?;
     let doc = pdfcraft_cos::Document::open_with_password(bytes, flag(args, "--password")).map_err(|e| format!("{path}: {e}"))?;
@@ -213,6 +221,7 @@ fn validate_options(command: &str, args: &[String], specs: &[OptionSpec]) -> Res
 }
 
 const INFO_OPTIONS: &[OptionSpec] = &[OptionSpec { name: "--password", takes_value: true }];
+const AUDIT_OPTIONS: &[OptionSpec] = &[OptionSpec { name: "--password", takes_value: true }];
 const TEXT_OPTIONS: &[OptionSpec] = &[OptionSpec { name: "--page", takes_value: true }, OptionSpec { name: "--password", takes_value: true }];
 const COMBINE_OPTIONS: &[OptionSpec] = &[OptionSpec { name: "--out", takes_value: true }];
 const EXTRACT_OPTIONS: &[OptionSpec] = &[
@@ -329,18 +338,27 @@ fn text(args: &[String]) -> Result<(), CliError> {
     // no pages, and "extract every page" of nothing would print nothing and exit 0 (#132). Ask
     // `inspect` why instead, so a protected file fails the same way `info` does.
     if r.page_count() == 0 {
-        let info = inspect(bytes, password).map_err(|e| format!("text: {e}"))?;
+        let info = inspect(bytes.clone(), password).map_err(|e| format!("text: {e}"))?;
         if !info.pages.is_empty() {
             return Err("text: the document could not be parsed".into());
         }
     }
+    // Printing the text is copying it, so ask what `text_extract` asks (#1645): without the
+    // permissions password, a document that doesn't allow copying gives no text.
+    let mut session = pdfcraft_engine::Session::new();
+    if let Some(doc) = session.open(path, None, bytes, password).ok().and_then(|id| session.get(id)) {
+        // The engine's hint is about editing in the app; on the command line the way in is
+        // `--password`.
+        doc.check_copying()
+            .map_err(|_| "text: the document's permissions don't allow copying its text; pass the owner password with --password to extract it")?;
+    }
     let pages: Vec<usize> = match selected_page {
         Some(page) => vec![page],
         None => (0..r.page_count()).collect(),
     };
     let mut failed: Vec<usize> = Vec::new();
     for (n, p) in pages.iter().enumerate() {
-        let out = r.render(RenderRequest { page: *p, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0 });
+        let out = r.render(RenderRequest { page: *p, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0, preview: false });
         if let Some(e) = out.error {
             let _ = writeln!(std::io::stderr().lock(), "page {}: {e}", p + 1);
             failed.push(p + 1);
@@ -426,6 +444,28 @@ fn edit(args: &[String]) -> Result<(), CliError> {
     let mut session = Session::new();
     let id = session.open(path, Some(path.to_string()), read(path)?, password).map_err(|e| e.to_string())?;
     for e in edits {
+        // A destination past the end must fail like `page_move` / `page_insert_blank` do, not
+        // silently become an append (#1330). Checked per edit: earlier edits change the count.
+        let n = session.get(id).map_or(0, |d| d.info.pages.len());
+        let destination = match &e {
+            Edit::MovePages { to, .. } => Some(("--move target", *to)),
+            Edit::InsertBlankPage { at, .. } => Some(("--insert-blank", *at)),
+            _ => None,
+        };
+        if let Some((option, at)) = destination.filter(|(_, at)| *at > n) {
+            return Err(format!("{option} {} is past the end: it must be between 1 and {} (the document has {n} pages)", at + 1, n + 1).into());
+        }
+        // Pages count from the document as the earlier options left it, so a page past the end is
+        // reported with its own option and the current page count (#1550).
+        let listed = match &e {
+            Edit::RotatePages { pages, .. } => Some(("--rotate", pages)),
+            Edit::DeletePages { pages } => Some(("--delete", pages)),
+            Edit::MovePages { pages, .. } => Some(("--move", pages)),
+            _ => None,
+        };
+        if let Some((option, bad)) = listed.and_then(|(option, pages)| pages.iter().find(|p| **p >= n).map(|p| (option, *p))) {
+            return Err(format!("{option}: page {} does not exist; after the earlier options the document has {n} pages", bad + 1).into());
+        }
         session.apply(id, e).map_err(|e| e.to_string())?;
     }
     let bytes = if full { session.save_full_bytes(id) } else { session.save_bytes(id) }.map_err(|e| e.to_string())?;
@@ -503,7 +543,7 @@ fn render(args: &[String]) -> Result<(), CliError> {
         read(path)?,
         RenderConfig { password: flag(args, "--password").map(Arc::from), reject_oversize: true, ..Default::default() },
     );
-    let p = r.render(RenderRequest { page: page_index, kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0 });
+    let p = r.render(RenderRequest { page: page_index, kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0, preview: false });
     if let Some(e) = p.error {
         return Err(e.into());
     }
@@ -541,8 +581,8 @@ fn check_one(args: &[String]) -> Result<(), CliError> {
             let mut r = PageRenderer::new(bytes, RenderConfig::default());
             let mut failed = Vec::new();
             for i in 0..info.pages.len().min(500) {
-                let p = r.render(RenderRequest { page: i, kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0 });
-                if let Some(e) = r.render(RenderRequest { page: i, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0 }).error {
+                let p = r.render(RenderRequest { page: i, kind: RequestKind::Pixels, tile: None, scale: dpi / 72.0, tag: 0, preview: false });
+                if let Some(e) = r.render(RenderRequest { page: i, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0, preview: false }).error {
                     failed.push(format!("p{} text: {e}", i + 1));
                 }
                 if let Some(e) = p.error {
@@ -597,8 +637,20 @@ fn short(s: &str) -> String {
 fn collect(paths: &[&str]) -> Vec<PathBuf> {
     let mut out = Vec::new();
     let mut stack: Vec<PathBuf> = paths.iter().map(PathBuf::from).collect();
+    let mut visited = std::collections::HashSet::new();
     while let Some(p) = stack.pop() {
         if p.is_dir() {
+            // Directory aliases and symlink cycles must not scan the same tree repeatedly.
+            let identity = match p.canonicalize() {
+                Ok(identity) => identity,
+                Err(error) => {
+                    eprintln!("{}: could not resolve directory: {error}", p.display());
+                    continue;
+                }
+            };
+            if !visited.insert(identity) {
+                continue;
+            }
             if let Ok(rd) = std::fs::read_dir(&p) {
                 stack.extend(rd.flatten().map(|e| e.path()));
             }

apps/pdfcraft-cli/tests/batch.rs

@@ -0,0 +1,46 @@
+use serde_json::Value;
+use std::process::Command;
+
+const BIN: &str = env!("CARGO_BIN_EXE_pdfcraft-cli");
+
+#[test]
+fn cli_batch_reports_partial_failure_and_continues_into_subfolders() {
+    let dir = std::env::temp_dir().join(format!("pdfcraft-cli-batch-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(dir.join("input/sub")).unwrap();
+    std::fs::write(dir.join("input/0.pdf"), b"broken").unwrap();
+    std::fs::write(dir.join("input/sub/page.txt"), "Batch text").unwrap();
+    let output = Command::new(BIN)
+        .args(["batch", "input", "--root"])
+        .arg(&dir)
+        .args(["--steps", "convert,optimize", "--out-dir", "out", "--recursive"])
+        .output()
+        .unwrap();
+    assert!(!output.status.success());
+    let report: Value = serde_json::from_slice(&output.stdout).unwrap();
+    assert_eq!(report["completed"], 1, "{report}");
+    assert_eq!(report["failed"], 1);
+    let converted = dir.join("out/sub/page.pdf");
+    assert!(converted.exists());
+    let text = Command::new(BIN).arg("text").arg(converted).output().unwrap();
+    assert!(text.status.success());
+    assert!(String::from_utf8_lossy(&text.stdout).contains("Batch text"));
+    let success = Command::new(BIN).current_dir(&dir).args(["batch", "input/sub", "--steps", "convert", "--out-dir", "other"]).output().unwrap();
+    assert!(success.status.success(), "{}", String::from_utf8_lossy(&success.stderr));
+    std::fs::remove_dir_all(dir).unwrap();
+}
+
+#[test]
+fn cli_batch_rejects_bad_flags_before_creating_outputs() {
+    for args in [
+        vec!["batch", "--steps"],
+        vec!["batch", "--recursive", "--root"],
+        vec!["batch", "--steps", "convert", "--out-dir"],
+        vec!["batch", "--steps", "convert", "--steps", "ocr", "--out-dir", "out"],
+        vec!["batch", "--unknown"],
+    ] {
+        let output = Command::new(BIN).args(args).output().unwrap();
+        assert!(!output.status.success());
+        assert!(output.stdout.is_empty());
+    }
+}

apps/pdfcraft-cli/tests/check.rs

@@ -0,0 +1,111 @@
+//! The robustness harness visits each directory once, including symlink aliases and cycles.
+
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+const BIN: &str = env!("CARGO_BIN_EXE_pdfcraft-cli");
+
+struct Workdir(PathBuf);
+
+impl Workdir {
+    fn new(test: &str) -> Self {
+        let dir = std::env::temp_dir().join(format!("pdfcraft-cli-check-{test}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(dir.join("input/nested")).unwrap();
+        let objects = [
+            "<< /Type /Catalog /Pages 2 0 R >>",
+            "<< /Type /Pages /Kids [3 0 R] /Count 1 /MediaBox [0 0 20 30] >>",
+            "<< /Type /Page /Parent 2 0 R >>",
+        ];
+        let mut bytes = b"%PDF-1.7\n".to_vec();
+        let mut offsets = Vec::new();
+        for (i, object) in objects.iter().enumerate() {
+            offsets.push(bytes.len());
+            bytes.extend_from_slice(format!("{} 0 obj\n{object}\nendobj\n", i + 1).as_bytes());
+        }
+        let xref = bytes.len();
+        bytes.extend_from_slice(b"xref\n0 4\n0000000000 65535 f \n");
+        for offset in offsets {
+            bytes.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes());
+        }
+        bytes.extend_from_slice(format!("trailer\n<< /Size 4 /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n").as_bytes());
+        std::fs::write(dir.join("input/a.pdf"), &bytes).unwrap();
+        std::fs::write(dir.join("input/nested/b.PDF"), &bytes).unwrap();
+        Self(dir)
+    }
+
+    fn check(&self, inputs: &[&Path]) -> Vec<serde_json::Value> {
+        let report = self.0.join("report.json");
+        let mut child = Command::new(BIN)
+            .arg("check")
+            .args(inputs)
+            .args(["--dpi", "36", "--timeout", "2", "--json"])
+            .arg(&report)
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+        let deadline = Instant::now() + Duration::from_secs(10);
+        while child.try_wait().unwrap().is_none() {
+            if Instant::now() >= deadline {
+                child.kill().unwrap();
+                let output = child.wait_with_output().unwrap();
+                panic!("check did not finish scanning directories: {}", String::from_utf8_lossy(&output.stderr));
+            }
+            std::thread::sleep(Duration::from_millis(10));
+        }
+        let output = child.wait_with_output().unwrap();
+        assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr));
+        serde_json::from_slice(&std::fs::read(report).unwrap()).unwrap()
+    }
+}
+
+impl Drop for Workdir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+fn assert_two_valid_pdfs(results: &[serde_json::Value]) {
+    assert_eq!(results.len(), 2, "each PDF should be checked once: {results:?}");
+    for result in results {
+        assert_eq!(result["status"], "ok", "{result}");
+        assert_eq!(result["pages"], 1, "{result}");
+    }
+    assert!(results[0]["file"].as_str().unwrap().ends_with("a.pdf"));
+    assert!(results[1]["file"].as_str().unwrap().ends_with("b.PDF"));
+}
+
+#[test]
+fn check_scans_overlapping_directories_once() {
+    let dir = Workdir::new("overlap");
+    let input = dir.0.join("input");
+    assert_two_valid_pdfs(&dir.check(&[&input, &input, &input.join("nested")]));
+}
+
+#[cfg(unix)]
+#[test]
+fn check_scans_a_directory_symlink_cycle_once() {
+    let dir = Workdir::new("cycle");
+    let input = dir.0.join("input");
+    std::os::unix::fs::symlink(".", input.join("again")).unwrap();
+    assert_two_valid_pdfs(&dir.check(&[&input]));
+}
+
+#[cfg(unix)]
+#[test]
+fn check_follows_directory_and_file_symlinks() {
+    let dir = Workdir::new("aliases");
+    let input = dir.0.join("input");
+    let alias = dir.0.join("alias");
+    std::os::unix::fs::symlink(&input, &alias).unwrap();
+    assert_two_valid_pdfs(&dir.check(&[&input, &alias]));
+
+    let file_alias = dir.0.join("page.pdf");
+    std::os::unix::fs::symlink(input.join("a.pdf"), &file_alias).unwrap();
+    let results = dir.check(&[&file_alias]);
+    assert_eq!(results.len(), 1);
+    assert_eq!(results[0]["status"], "ok");
+    assert_eq!(results[0]["file"], file_alias.to_string_lossy().as_ref());
+}

apps/pdfcraft-cli/tests/edit.rs

@@ -179,3 +179,63 @@ mod one_based_arguments {
         assert_eq!(std::fs::read(dir.0.join("input.pdf")).unwrap(), source);
     }
 }
+
+/// A destination past the end must fail, not silently become an append (#1330).
+#[test]
+fn a_destination_past_the_end_fails_and_writes_nothing() {
+    let input = tmp("past-end", "in.pdf");
+    std::fs::write(&input, fixture()).unwrap();
+    let output = tmp("past-end", "out.pdf");
+    for (option, value, diagnostic) in [
+        ("--insert-blank", "3", "--insert-blank 3 is past the end: it must be between 1 and 2 (the document has 1 pages)"),
+        ("--insert-blank", "99", "--insert-blank 99 is past the end: it must be between 1 and 2 (the document has 1 pages)"),
+        ("--move", "1:3", "--move target 3 is past the end: it must be between 1 and 2 (the document has 1 pages)"),
+        ("--move", "1:99", "--move target 99 is past the end: it must be between 1 and 2 (the document has 1 pages)"),
+    ] {
+        let out = Command::new(BIN).args(["edit", input.to_str().unwrap(), "--out", output.to_str().unwrap(), option, value]).output().unwrap();
+        assert_eq!(out.status.code(), Some(1), "{option} {value}");
+        assert_eq!(String::from_utf8_lossy(&out.stderr), format!("pdfcraft-cli: {diagnostic}\n"), "{option} {value}");
+        assert!(!output.exists(), "{option} {value}: no output may be written");
+    }
+}
+
+/// One past the last page appends, and each destination is checked against the page count at that point.
+#[test]
+fn the_append_destination_and_counts_grown_by_earlier_edits_are_accepted() {
+    let input = tmp("append", "in.pdf");
+    std::fs::write(&input, fixture()).unwrap();
+    for (name, args) in [
+        ("insert.pdf", vec!["--insert-blank", "2"]),
+        ("move.pdf", vec!["--insert-blank", "1", "--move", "1:3"]),
+        ("grown.pdf", vec!["--insert-blank", "2", "--insert-blank", "3"]),
+    ] {
+        let output = tmp("append", name);
+        let mut all = vec!["edit", input.to_str().unwrap(), "--out", output.to_str().unwrap()];
+        all.extend(args);
+        let out = Command::new(BIN).args(&all).output().unwrap();
+        assert!(out.status.success(), "{name}: {}", String::from_utf8_lossy(&out.stderr));
+        let info = pdfcraft_render::inspect(std::sync::Arc::new(std::fs::read(&output).unwrap()), None).unwrap();
+        let sizes: Vec<_> = info.pages.iter().map(|p| (p.width, p.height)).collect();
+        let expected: &[(f32, f32)] = match name {
+            "insert.pdf" => &[(200.0, 300.0), (612.0, 792.0)],
+            "move.pdf" => &[(200.0, 300.0), (612.0, 792.0)],
+            _ => &[(200.0, 300.0), (612.0, 792.0), (612.0, 792.0)],
+        };
+        assert_eq!(sizes, expected, "{name}");
+    }
+}
+
+/// A page past the end names its own option and the page count left by the earlier options (#1550).
+#[test]
+fn a_page_past_the_end_after_earlier_edits_names_that_option() {
+    let input = tmp("chained", "in.pdf");
+    std::fs::write(&input, fixture()).unwrap();
+    let output = tmp("chained", "out.pdf");
+    // 1 page, grown to 3, then --delete leaves 2: the 3 in --move 3:1 is the page that is gone.
+    let args = ["--insert-blank", "2", "--insert-blank", "3", "--delete", "3", "--move", "3:1"];
+    let out = Command::new(BIN).args(["edit", input.to_str().unwrap(), "--out", output.to_str().unwrap()]).args(args).output().unwrap();
+    assert!(!out.status.success());
+    let err = String::from_utf8_lossy(&out.stderr);
+    assert!(err.contains("--move: page 3 does not exist") && err.contains("has 2 pages"), "{err}");
+    assert!(!output.exists());
+}

apps/pdfcraft-cli/tests/mcp_compact.rs

@@ -37,6 +37,18 @@ fn listed_tools(flags: &[&str]) -> Vec<String> {
     reply["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap().to_string()).collect()
 }
 
+#[test]
+fn mcp_rejects_unknown_options_before_starting_the_server() {
+    for option in ["--totally-bogus-flag", "--rot", "--root=."] {
+        let out = Command::new(env!("CARGO_BIN_EXE_pdfcraft-cli")).args(["mcp", option]).output().expect("run CLI");
+
+        let stderr = String::from_utf8_lossy(&out.stderr);
+        assert!(!out.status.success(), "mcp {option} unexpectedly succeeded");
+        assert!(stderr.contains("unknown option") && stderr.contains(option), "mcp {option}: {stderr}");
+        assert!(!stderr.contains("MCP server on stdio"), "server started despite invalid option: {stderr}");
+    }
+}
+
 #[test]
 fn compact_flag_shortens_the_tool_list() {
     let full = listed_tools(&[]);

apps/pdfcraft-cli/tests/options.rs

@@ -15,6 +15,8 @@ fn non_edit_commands_reject_unknown_options_before_io() {
         vec!["render", "missing.pdf", "--dppi", "96", "--out", "out.png"],
         vec!["check-one", "missing.pdf", "--edti"],
         vec!["check", "missing.pdf", "--timout", "2"],
+        vec!["audit", "missing.pdf", "--passwrod", "x"],
+        vec!["audit", "missing.pdf", "--nonsense", "1"],
         vec!["run", "doc_open", "--roto", "/tmp"],
         vec!["ui", "--contro", "control.json", "state"],
     ] {

apps/pdfcraft-cli/tests/text.rs

@@ -96,6 +96,41 @@ fn text_of_a_protected_document_with_the_password_succeeds() {
     assert!(stdout.contains("Page 1") && stdout.contains("Page 3"), "{stdout}");
 }
 
+/// `three.pdf` encrypted so that the open password `openme` doesn't allow copying, and the
+/// permissions password `boss` lifts that.
+fn copy_protected_fixture() -> std::path::PathBuf {
+    let src = tmp("to-protect-no-copy.pdf");
+    std::fs::write(&src, fixture(3)).unwrap();
+    let out_path = tmp("protected-no-copy.pdf");
+    let script = tmp("protect-no-copy.json");
+    let steps = serde_json::json!([
+        { "tool": "doc_open", "args": { "path": src } },
+        { "tool": "doc_protect", "args": { "doc": 1, "open_password": "openme", "permissions_password": "boss", "copy": false } },
+        { "tool": "doc_save", "args": { "doc": 1, "path": out_path } },
+    ]);
+    std::fs::write(&script, steps.to_string()).unwrap();
+    let out = Command::new(BIN).args(["run", "--script", script.to_str().unwrap()]).output().unwrap();
+    assert!(out.status.success(), "protecting the fixture failed: {}", String::from_utf8_lossy(&out.stderr));
+    out_path
+}
+
+/// `text` copies text out, so it asks what `text_extract` asks (#1645): the open password alone
+/// gives no text when copying isn't allowed, the permissions password does.
+#[test]
+fn text_respects_a_document_that_does_not_allow_copying() {
+    let path = copy_protected_fixture();
+    let out = Command::new(BIN).args(["text", path.to_str().unwrap(), "--password", "openme"]).output().unwrap();
+    assert!(!out.status.success(), "copying isn't allowed: {}", String::from_utf8_lossy(&out.stdout));
+    assert!(out.stdout.is_empty(), "{}", String::from_utf8_lossy(&out.stdout));
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("don't allow copying"), "the reason must be named: {stderr}");
+    assert!(stderr.contains("--password"), "and the way in: {stderr}");
+    let out = Command::new(BIN).args(["text", path.to_str().unwrap(), "--password", "boss"]).output().unwrap();
+    assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(stdout.contains("Page 1") && stdout.contains("Page 3"), "{stdout}");
+}
+
 mod page_argument_tests {
     use super::*;
     use std::path::PathBuf;

apps/pdfcraft/Cargo.toml

@@ -14,6 +14,8 @@ workspace = true
 ureq = { version = "3.4", default-features = false, features = ["rustls-no-provider", "_ring"] }
 rustls-native-certs = "0.8"
 pdfcraft-ui-egui = { workspace = true }
+# `build_info`: the version and compile-time build label for `--version` and the log.
+pdfcraft-engine = { workspace = true }
 # 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"] }
@@ -42,6 +44,10 @@ pollster = "1.0"
 # Which GPU drives which display (EnumDisplayDevices), so the window is drawn on the GPU that
 # shows it (issue #378). Safe wrappers over Win32; only the `user` feature (which brings `kernel` with it).
 winsafe = { version = "0.0.29", default-features = false, features = ["user"] }
+# Settings ▸ Accessibility ▸ Visual effects ▸ Animation effects (src/motion.rs), through WinRT's
+# `UISettings`, whose bindings are safe to call (winsafe's `SystemParametersInfo` is an unsafe
+# fn). Already in the tree through wgpu's DX12 backend; this adds one small namespace to it.
+windows = { version = "0.62", default-features = false, features = ["std", "UI_ViewManagement"] }
 # Single instance (#282): later launches hand their files to the running app over a Unix domain
 # socket. `std` has no Unix sockets on Windows, and calling Winsock directly needs unsafe, which
 # our workspace forbids. Already in the lockfile through zbus; pinned exactly, review before bumping.

apps/pdfcraft/src/decorations.rs

@@ -0,0 +1,70 @@
+//! Who draws the window frame on Linux.
+//!
+//! Wayland compositors that draw frames for their clients offer `zxdg_decoration_manager_v1`
+//! (KDE, Sway, Hyprland, COSMIC). GNOME doesn't: it leaves the frame to the app, and winit then
+//! drew an imitation of GNOME's. Without that protocol PdfCraft turns winit's frame off and draws
+//! a header bar like GNOME's own apps (`pdfcraft_ui_egui::window_controls`), with the window
+//! buttons GNOME's `button-layout` names. X11 window managers always draw the frame.
+//!
+//! `PDFCRAFT_TITLEBAR=app` or `=system` overrides the choice.
+
+use pdfcraft_ui_egui::window_controls::Layout;
+
+/// The window buttons to draw in the app, or `None` when the desktop draws the frame.
+pub(crate) fn app_drawn() -> Option<Layout> {
+    let drawn = match std::env::var("PDFCRAFT_TITLEBAR").ok().as_deref().map(str::trim) {
+        Some("app") => true,
+        Some("system") => false,
+        _ => compositor_leaves_frame_to_app(),
+    };
+    drawn.then(button_layout)
+}
+
+/// GNOME's button order, or minimize, maximize and close on the right when it names none.
+fn button_layout() -> Layout {
+    #[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd"))]
+    if let Some(value) = crate::text_scale::gsettings(&["get", "org.gnome.desktop.wm.preferences", "button-layout"]) {
+        let layout = Layout::parse(&value);
+        // A layout without a single button would leave no way to close the window by mouse.
+        if !layout.left.is_empty() || !layout.right.is_empty() {
+            return layout;
+        }
+    }
+    Layout::default()
+}
+
+/// Whether this is a Wayland session whose compositor draws no frames.
+#[cfg(target_os = "linux")]
+fn compositor_leaves_frame_to_app() -> bool {
+    use wayland_client::Connection;
+    use wayland_client::globals::registry_queue_init;
+    // No Wayland compositor: X11, whose window manager draws the frame (winit falls back to it).
+    let Ok(conn) = Connection::connect_to_env() else { return false };
+    let Ok((globals, _queue)) = registry_queue_init::<Registry>(&conn) else { return false };
+    let offered = globals.contents().with_list(|list| list.iter().any(|g| g.interface == "zxdg_decoration_manager_v1"));
+    if !offered {
+        log::info!("the Wayland compositor draws no window frames; PdfCraft draws its own title bar");
+    }
+    !offered
+}
+
+#[cfg(not(target_os = "linux"))]
+fn compositor_leaves_frame_to_app() -> bool {
+    false
+}
+
+#[cfg(target_os = "linux")]
+struct Registry;
+
+#[cfg(target_os = "linux")]
+impl wayland_client::Dispatch<wayland_client::protocol::wl_registry::WlRegistry, wayland_client::globals::GlobalListContents> for Registry {
+    fn event(
+        _: &mut Self,
+        _: &wayland_client::protocol::wl_registry::WlRegistry,
+        _: wayland_client::protocol::wl_registry::Event,
+        _: &wayland_client::globals::GlobalListContents,
+        _: &wayland_client::Connection,
+        _: &wayland_client::QueueHandle<Self>,
+    ) {
+    }
+}

apps/pdfcraft/src/main.rs

@@ -32,7 +32,10 @@ use pdfcraft_ui_egui::PdfCraftApp;
 #[cfg(target_os = "macos")]
 mod apple_events;
 mod compositor_gpu;
+mod decorations;
 mod logging;
+#[cfg(target_os = "windows")]
+mod motion;
 mod reopen;
 mod single_instance;
 mod text_scale;
@@ -124,6 +127,35 @@ fn path_from_arg(arg: String) -> String {
     String::from_utf8(out).unwrap_or(arg)
 }
 
+/// Some programs start the PDF reader with the path unquoted (`pdfcraft.exe P:\Docs\01 Contract.PDF`),
+/// so a path with spaces arrives split into several arguments (Acrobat accepts this). When an
+/// argument names no file but it and the ones after it, joined with one space, do, rejoin them
+/// (the longest such run). Anything else is kept as given. Runs of several spaces can't be recovered: the split has lost them.
+fn rejoin_split_paths(args: Vec<String>, exists: impl Fn(&str) -> bool) -> Vec<String> {
+    let mut out = Vec::with_capacity(args.len());
+    let mut i = 0;
+    while let Some(first) = args.get(i) {
+        if exists(first) {
+            out.push(first.clone());
+            i += 1;
+            continue;
+        }
+        // The longest run starting here that names a file; capped so a long list stays cheap.
+        let end = (i + 2..=args.len().min(i + 32)).rev().find(|&j| args.get(i..j).is_some_and(|run| exists(&run.join(" "))));
+        match end.and_then(|j| Some((j, args.get(i..j)?.join(" ")))) {
+            Some((j, joined)) => {
+                out.push(joined);
+                i = j;
+            }
+            None => {
+                out.push(first.clone());
+                i += 1;
+            }
+        }
+    }
+    out
+}
+
 fn main() -> eframe::Result {
     // First, so the panic hook and every start-up warning are recorded (`logging`).
     let logger = logging::install();
@@ -153,7 +185,7 @@ fn main() -> eframe::Result {
     while let Some(a) = args.next() {
         match a.as_str() {
             "--version" => {
-                println!("pdfcraft {}", env!("CARGO_PKG_VERSION"));
+                println!("pdfcraft {}", pdfcraft_engine::build_info::version());
                 return Ok(());
             }
             "--control" => control_file = args.next(),
@@ -166,14 +198,17 @@ fn main() -> eframe::Result {
             _ => files.push(path_from_arg(a)),
         }
     }
+    let files = rejoin_split_paths(files, |p| std::path::Path::new(p).is_file());
     let integrated = cfg!(target_os = "macos");
+    // GNOME on Wayland leaves the window frame to the app (src/decorations.rs).
+    let window_controls = if cfg!(any(target_os = "macos", target_os = "windows")) { None } else { decorations::app_drawn() };
     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()),
+            Ok(path) => log::info!("PdfCraft {}, log file {}", pdfcraft_engine::build_info::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}"),
         }
@@ -188,7 +223,7 @@ fn main() -> eframe::Result {
         single_instance::Claim::Alone => None,
     };
     let choice = renderer_choice(std::env::var("PDFCRAFT_RENDERER").ok().as_deref());
-    let launch = Launch { files, options, control_file, create_images, integrated };
+    let launch = Launch { files, options, control_file, create_images, integrated, window_controls };
     // 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")]
@@ -198,7 +233,7 @@ fn main() -> eframe::Result {
     let first = if choice == RendererChoice::Gl { eframe::Renderer::Glow } else { eframe::Renderer::Wgpu };
     let result = eframe::run_native(
         "PdfCraft",
-        native_options(integrated, first),
+        native_options(launch.integrated, launch.window_controls.is_some(), first),
         app_creator(
             launch.clone(),
             Rc::clone(&started),
@@ -216,7 +251,7 @@ fn main() -> eframe::Result {
             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),
+                native_options(launch.integrated, launch.window_controls.is_some(), eframe::Renderer::Glow),
                 app_creator(
                     launch,
                     started,
@@ -256,7 +291,7 @@ fn retry_with_gl(choice: RendererChoice, app_started: bool) -> bool {
 }
 
 /// The window and renderer settings for one run.
-fn native_options(integrated: bool, renderer: eframe::Renderer) -> eframe::NativeOptions {
+fn native_options(integrated: bool, app_frame: bool, renderer: eframe::Renderer) -> eframe::NativeOptions {
     let mut viewport = egui::ViewportBuilder::default()
         .with_title("PdfCraft")
         .with_inner_size([1440.0, 920.0])
@@ -272,6 +307,10 @@ fn native_options(integrated: bool, renderer: eframe::Renderer) -> eframe::Nativ
     if integrated {
         viewport = viewport.with_fullsize_content_view(true).with_titlebar_shown(false).with_title_shown(false);
     }
+    if app_frame {
+        // The tab strip is the title bar (pdfcraft_ui_egui::window_controls).
+        viewport = viewport.with_decorations(false);
+    }
     let persistence_path = settings_dir().map(|d| d.join("app.ron"));
     // Set explicitly, so the renderer never depends on which one eframe defaults to.
     let mut native = eframe::NativeOptions { viewport, persistence_path, renderer, ..Default::default() };
@@ -289,6 +328,8 @@ struct Launch {
     control_file: Option<String>,
     create_images: bool,
     integrated: bool,
+    /// The window buttons the app draws, when the desktop leaves the frame to it.
+    window_controls: Option<pdfcraft_ui_egui::window_controls::Layout>,
 }
 
 fn app_creator<'a>(
@@ -297,7 +338,7 @@ fn app_creator<'a>(
     instance: Option<&'a single_instance::Server>,
     #[cfg(target_os = "macos")] apple_events: &'a apple_events::AppleEvents,
 ) -> eframe::AppCreator<'a> {
-    let Launch { files, options, control_file, create_images, integrated } = launch;
+    let Launch { files, options, control_file, create_images, integrated, window_controls } = launch;
     Box::new(move |cc| {
         started.set(true);
         let mut app = PdfCraftApp::new();
@@ -311,7 +352,14 @@ fn app_creator<'a>(
             app.restore(&json);
         }
         app.integrated_titlebar = integrated;
+        app.window_controls = window_controls;
         app.system_text_scale = text_scale::system();
+        // Windows' Animation effects setting, which Preferences ▸ Animation effects follows unless
+        // it is set to On or Off.
+        #[cfg(target_os = "windows")]
+        {
+            app.motion.source = Some(motion::source());
+        }
         app.update_source = Some(std::sync::Arc::new(updates::latest_release));
         app.printer_source = Some(pdfcraft_ui_egui::system_printers());
         app.os_key_store_ids = cfg!(any(target_os = "macos", target_os = "windows"));
@@ -476,6 +524,11 @@ fn write_control_file(path: &str, port: u16, token: &str) -> std::io::Result<()>
 ///   its window appeared. D3D12 is the native, best-supported backend there.
 fn configure_gpu(native: &mut eframe::NativeOptions) {
     let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &mut native.wgpu_options.wgpu_setup else { return };
+    // Nothing draws or dispatches indirectly, so wgpu's check of indirect arguments only costs a
+    // compute shader when the device is created, one that Metal can't compile on an Intel Iris
+    // Pro: the device is lost and the window falls back to OpenGL. `WGPU_VALIDATION_INDIRECT_CALL=1`
+    // turns the check back on.
+    setup.instance_descriptor.flags = setup.instance_descriptor.flags.difference(eframe::wgpu::InstanceFlags::VALIDATION_INDIRECT_CALL).with_env();
     // egui-wgpu requests only 8192 pixels even when the adapter can render larger surfaces.
     // A restored 3440-point window at 250% DPI requests 8600 pixels and otherwise panics in
     // Surface::configure before the app starts. Keep the renderer's other device requirements,
@@ -672,6 +725,19 @@ mod tests {
         Ok(Endpoint { port: 4321, token: "0123456789abcdef".into() })
     }
 
+    /// Tests that open a real GPU device take this first, so only one of them is inside the
+    /// graphics libraries at a time. The test threads otherwise run them together, and on
+    /// FreeBSD's CI machine the test process then died with SIGSEGV, in about half the runs:
+    /// the first device was still being set up when the second test began its own. The UI
+    /// tests take turns the same way (`crates/ui-egui/tests/view.rs`). Hold it for the whole
+    /// test (declared before the instance, so it's released after the device is dropped).
+    static GPU: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    fn gpu() -> std::sync::MutexGuard<'static, ()> {
+        // A test that panicked while holding it leaves nothing to clean up.
+        GPU.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+
     #[test]
     fn a_control_channel_that_cant_be_published_stops_the_app() {
         let dir = std::env::temp_dir().join(format!("pdfcraft-app-control-{}", std::process::id()));
@@ -706,6 +772,24 @@ mod tests {
         assert_eq!(super::path_from_arg("file:///tmp/%FF.pdf".to_string()), "file:///tmp/%FF.pdf");
     }
 
+    #[test]
+    fn unquoted_paths_with_spaces_are_rejoined() {
+        let have = ["P:\\Archive\\00042A26 Contract.PDF", "C:\\a b c.pdf", "C:\\a.pdf", "C:\\x y.pdf"];
+        let exists = |p: &str| have.contains(&p);
+        let args = |a: &[&str]| a.iter().map(|s| s.to_string()).collect::<Vec<_>>();
+        // The case an office program produced: one path, split at its space.
+        assert_eq!(
+            super::rejoin_split_paths(args(&["P:\\Archive\\00042A26", "Contract.PDF"]), exists),
+            args(&["P:\\Archive\\00042A26 Contract.PDF"])
+        );
+        // The longest run wins; files that exist on their own are left alone.
+        assert_eq!(super::rejoin_split_paths(args(&["C:\\a", "b", "c.pdf", "C:\\a.pdf"]), exists), args(&["C:\\a b c.pdf", "C:\\a.pdf"]));
+        assert_eq!(super::rejoin_split_paths(args(&["C:\\a.pdf", "C:\\x", "y.pdf"]), exists), args(&["C:\\a.pdf", "C:\\x y.pdf"]));
+        // Nothing to join: kept as given, so the missing file is still reported by name.
+        assert_eq!(super::rejoin_split_paths(args(&["missing.pdf", "other"]), exists), args(&["missing.pdf", "other"]));
+        assert!(super::rejoin_split_paths(Vec::new(), exists).is_empty());
+    }
+
     #[test]
     fn path_from_arg_leaves_plain_paths_and_other_schemes_alone() {
         assert_eq!(super::path_from_arg("report.pdf".to_string()), "report.pdf");
@@ -731,8 +815,15 @@ mod tests {
         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);
+        assert_eq!(native_options(false, false, eframe::Renderer::Wgpu).renderer, eframe::Renderer::Wgpu);
+        assert_eq!(native_options(false, false, eframe::Renderer::Glow).renderer, eframe::Renderer::Glow);
+    }
+
+    #[test]
+    fn the_desktop_frame_is_turned_off_only_when_the_app_draws_one() {
+        use super::native_options;
+        assert_eq!(native_options(false, false, eframe::Renderer::Glow).viewport.decorations, None);
+        assert_eq!(native_options(false, true, eframe::Renderer::Glow).viewport.decorations, Some(false));
     }
 
     #[test]
@@ -760,6 +851,10 @@ mod tests {
         if std::env::var_os("WGPU_POWER_PREF").is_none() {
             assert_eq!(setup.power_preference, eframe::wgpu::PowerPreference::LowPower);
         }
+        if std::env::var_os("WGPU_VALIDATION_INDIRECT_CALL").is_none() {
+            let flags = setup.instance_descriptor.flags;
+            assert!(!flags.contains(eframe::wgpu::InstanceFlags::VALIDATION_INDIRECT_CALL), "Intel Metal can't compile its shader: {flags:?}");
+        }
         if cfg!(target_os = "windows") && std::env::var_os("WGPU_BACKEND").is_none() {
             let backends = setup.instance_descriptor.backends;
             assert!(backends.contains(eframe::wgpu::Backends::DX12), "{backends:?}");
@@ -878,7 +973,8 @@ mod tests {
         // and an error wgpu raises before anything reaches the driver: a texture one pixel wider
         // than the device allows.
         use eframe::wgpu;
-        let native = super::native_options(false, eframe::Renderer::Wgpu);
+        let _gpu = gpu();
+        let native = super::native_options(false, false, eframe::Renderer::Wgpu);
         let eframe::egui_wgpu::WgpuSetup::CreateNew(setup) = &native.wgpu_options.wgpu_setup else {
             panic!("default setup creates its own instance")
         };
@@ -944,7 +1040,8 @@ mod tests {
     #[test]
     fn pipeline_creation_error_is_returned_and_device_remains_usable() {
         use eframe::{egui_wgpu, wgpu};
-        let mut native = super::native_options(false, eframe::Renderer::Wgpu);
+        let _gpu = gpu();
+        let mut native = super::native_options(false, false, eframe::Renderer::Wgpu);
         let egui_wgpu::WgpuSetup::CreateNew(setup) = &native.wgpu_options.wgpu_setup else { panic!("default setup creates its own instance") };
         let instance = pollster::block_on(native.wgpu_options.wgpu_setup.new_instance());
         let options = wgpu::RequestAdapterOptions { power_preference: setup.power_preference, ..Default::default() };

apps/pdfcraft/src/motion.rs

@@ -0,0 +1,75 @@
+//! The system's "no animations" setting, which Preferences ▸ Animation effects follows unless it is
+//! set to On or Off (`pdfcraft_ui_egui::motion`).
+//!
+//! Windows: Settings ▸ Accessibility ▸ Visual effects ▸ Animation effects (in the Control Panel,
+//! "Show animations in Windows"), read through WinRT's `UISettings.AnimationsEnabled`. Other
+//! systems aren't asked yet: there the window animates as before.
+
+use pdfcraft_ui_egui::motion::MotionSource;
+
+/// Asks the system each time, and logs the answer when it changes.
+pub fn source() -> MotionSource {
+    let last = std::cell::Cell::new(None);
+    Box::new(move || {
+        let reduced = reduced();
+        if reduced.is_some() && last.replace(reduced) != reduced {
+            log::info!("system animation effects: {}", if reduced == Some(true) { "off" } else { "on" });
+        }
+        reduced
+    })
+}
+
+/// Whether the system asks for no animations; `None` when it can't be asked.
+pub fn reduced() -> Option<bool> {
+    match animations_enabled() {
+        Ok(enabled) => Some(!enabled),
+        Err(e) => {
+            log::debug!("system animation effects: {e}");
+            None
+        }
+    }
+}
+
+fn animations_enabled() -> windows::core::Result<bool> {
+    windows::UI::ViewManagement::UISettings::new()?.AnimationsEnabled()
+}
+
+#[cfg(test)]
+mod tests {
+    /// The user's saved Animation effects choice, or `None` when `reg` can't read it. Windows
+    /// keeps its on/off system parameters as the bits of `UserPreferencesMask`: bit n is the
+    /// parameter `SPI_GET…` 0x1000 + 2n, and client-area animation is 0x1042, so bit 33.
+    fn saved_choice() -> Option<bool> {
+        let out = std::process::Command::new("reg").args(["query", r"HKCU\Control Panel\Desktop", "/v", "UserPreferencesMask"]).output().ok()?;
+        if !out.status.success() {
+            return None;
+        }
+        let text = String::from_utf8_lossy(&out.stdout);
+        let hex = text.split_whitespace().skip_while(|word| *word != "REG_BINARY").nth(1)?;
+        let byte = u8::from_str_radix(hex.get(8..10)?, 16).ok()?;
+        Some(byte & 0b10 != 0)
+    }
+
+    #[test]
+    fn the_answer_is_the_systems_animation_effects_setting() {
+        let answer = super::reduced();
+        // The first answer is logged and later ones only when they change; the answers don't.
+        let source = super::source();
+        assert_eq!((source(), source()), (answer, answer));
+        match super::animations_enabled() {
+            // With Animation effects turned off, the answer must be "reduced". Only this way
+            // round: the session's own value may be off for other reasons (a policy, a remote
+            // session) while the saved choice is on.
+            Ok(enabled) => {
+                assert_eq!(answer, Some(!enabled));
+                if saved_choice() == Some(false) {
+                    assert!(!enabled, "Animation effects are off in Settings, but the answer was that animations are on");
+                }
+            }
+            Err(e) => {
+                eprintln!("UISettings isn't available here ({e}); not compared with the saved choice");
+                assert_eq!(answer, None);
+            }
+        }
+    }
+}

apps/pdfcraft/src/text_scale.rs

@@ -27,7 +27,7 @@ fn parse(output: &str) -> f32 {
 
 /// Run `gsettings` and return what it printed, or `None` if it is missing, fails or hangs.
 #[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd"))]
-fn gsettings(args: &[&str]) -> Option<String> {
+pub(crate) fn gsettings(args: &[&str]) -> Option<String> {
     use std::io::Read;
     use std::process::{Command, Stdio};
     let mut child = Command::new("gsettings").args(args).stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::null()).spawn().ok()?;

apps/pdfcraft/tests/winit_x11_dpi.rs

@@ -0,0 +1,14 @@
+#[test]
+fn winit_carries_the_x11_server_dpi_fallback() {
+    // The behavior tests live beside the policy in winit (util::randr::tests).
+    // This guards PdfCraft's vendored copy, which workspace tests do not test itself.
+    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
+    let randr = std::fs::read_to_string(root.join("vendor/winit/src/platform_impl/linux/x11/util/randr.rs")).unwrap();
+    assert!(randr.contains("let screen = self.default_root();"));
+    assert!(randr.contains("default_dpi_factor(\n                    self.get_xft_dpi(),"));
+    assert!(randr.contains("screen.width_in_millimeters.into()"));
+    assert!(randr.contains("calc_dpi_factor(screen_pixels, screen_mm)"));
+    assert!(randr.contains("server_dpi_wins_over_the_panels_physical_density"));
+    let desktop = std::fs::read_to_string(root.join("packaging/linux/ai.storyteller.pdfcraft.desktop")).unwrap();
+    assert!(!desktop.contains("WINIT_X11_SCALE_FACTOR"));
+}

assets/demo/README.md

@@ -20,6 +20,9 @@ environment variable if you set one.
    Inter and JetBrains Mono fonts).
 2. **Chrome.** Headless Chrome prints the page to PDF with
    `--headless=new --no-pdf-header-footer --generate-pdf-document-outline --print-to-pdf`.
+   It runs with a throwaway `--user-data-dir` and
+   `--disable-features=MacAppCodeSignClone`, so no code-sign clones are left
+   behind on macOS.
    Skia produces 12 tagged pages with embedded font subsets. Variable
    system-ui weights come out as Type 3 fonts and emoji as Type 3 bitmap
    glyphs. The pages also get shadings, blend modes, soft masks, tiling

clippy.toml

@@ -2,3 +2,14 @@ allow-unwrap-in-tests = true
 allow-expect-in-tests = true
 allow-panic-in-tests = true
 allow-indexing-slicing-in-tests = true
+
+# With the theme's widget visuals egui draws a checkbox's box as a circle, like a radio button,
+# and on the light theme neither has an outline or a fill that shows on a white panel.
+disallowed-methods = [
+    { path = "egui::Ui::checkbox", reason = "use checkbox from crates/ui-egui/src/widgets.rs, whose box is a square" },
+    { path = "egui::Checkbox::new", reason = "use checkbox from crates/ui-egui/src/widgets.rs, whose box is a square" },
+    { path = "egui::Checkbox::without_text", reason = "use checkbox_without_text from crates/ui-egui/src/widgets.rs, whose box is a square" },
+    { path = "egui::Ui::radio", reason = "use radio from crates/ui-egui/src/widgets.rs, which is outlined and filled" },
+    { path = "egui::Ui::radio_value", reason = "use radio_value from crates/ui-egui/src/widgets.rs, which is outlined and filled" },
+    { path = "egui::RadioButton::new", reason = "use radio from crates/ui-egui/src/widgets.rs, which is outlined and filled" },
+]

contributors/people.toml

@@ -17,6 +17,9 @@
 # To remove your names, delete your entry (or set fields empty) in a PR. The next
 # contributors.py run, and the next build, drop them.
 
+[people.YouseifUS]
+sync_github_name = true
+
 [people.echelon]
 real_name = "Brandon Thomas"
 display_name = "Brandon Thomas"
@@ -103,3 +106,26 @@ sync_github_name = true   # use the name on your public GitHub profile as displa
 
 [people.Losminek]
 sync_github_name = true
+
+[people.earlvanze]
+sync_github_name = true
+
+[people.rp6186030]
+real_name = "Raj Patel"
+sync_github_name = false
+
+[people.yeniufuklar-com]
+real_name = "Ufuk Efe"
+display_name = "Ufuk Efe"
+sync_github_name = true
+
+[people.lollinoo]
+sync_github_name = true
+
+[people.JeremyYao]
+real_name = "Jeremy Yao"
+display_name = "Jeremy Yao"
+sync_github_name = false
+
+[people.webdevtodayjason]
+display_name = "Jason Brashear"

crates/a11y/Cargo.toml

@@ -14,5 +14,6 @@ workspace = true
 pdfcraft-cos = { workspace = true }
 pdfcraft-model = { workspace = true }
 pdfcraft-content = { workspace = true }
+pdfcraft-filters = { workspace = true }
 pdfcraft-fonts = { workspace = true }
 thiserror.workspace = true

crates/a11y/src/alt.rs

@@ -47,18 +47,28 @@ pub(crate) fn standard(doc: &Document, role_map: &Dict, s: &[u8]) -> Vec<u8> {
     t
 }
 
-/// Indirect structure elements in document order, with their page.
-fn elements(doc: &Document) -> Vec<(ObjRef, Dict, Option<ObjRef>)> {
+/// An indirect structure element and its nearest indirect parent in tree order.
+pub(crate) struct Element {
+    pub object: ObjRef,
+    pub dict: Dict,
+    pub page: Option<ObjRef>,
+    pub parent: Option<ObjRef>,
+    pub depth: usize,
+}
+
+/// Indirect structure elements in document order, with their page and hierarchy.
+pub(crate) fn elements(doc: &Document) -> Vec<Element> {
     let Some(root) = tree_root(doc) else { return Vec::new() };
     let mut out = Vec::new();
     let mut seen = HashSet::new();
-    let mut stack: Vec<(Object, Option<ObjRef>)> = root.get(b"K").map(|k| vec![(k.clone(), None)]).unwrap_or_default();
-    while let Some((k, pg)) = stack.pop() {
+    let mut stack: Vec<(Object, Option<ObjRef>, Option<ObjRef>, usize)> =
+        root.get(b"K").map(|k| vec![(k.clone(), None, None, 0)]).unwrap_or_default();
+    while let Some((k, pg, parent, depth)) = stack.pop() {
         if out.len() > 1_000_000 {
             break;
         }
         match k {
-            Object::Array(a) => stack.extend(a.into_iter().rev().map(|x| (x, pg))),
+            Object::Array(a) => stack.extend(a.into_iter().rev().map(|x| (x, pg, parent, depth))),
             Object::Ref(r) => {
                 if !seen.insert(r) {
                     continue;
@@ -67,16 +77,16 @@ fn elements(doc: &Document) -> Vec<(ObjRef, Dict, Option<ObjRef>)> {
                 if d.contains(b"S") {
                     let pg = d.get(b"Pg").and_then(Object::as_ref).or(pg);
                     if let Some(kids) = d.get(b"K") {
-                        stack.push((kids.clone(), pg));
+                        stack.push((kids.clone(), pg, Some(r), depth.saturating_add(1)));
                     }
-                    out.push((r, d, pg));
+                    out.push(Element { object: r, dict: d, page: pg, parent, depth });
                 }
             }
             Object::Dict(d) if d.contains(b"S") => {
                 // Direct elements can't be addressed; their indirect children still can.
                 let pg = d.get(b"Pg").and_then(Object::as_ref).or(pg);
                 if let Some(kids) = d.get(b"K") {
-                    stack.push((kids.clone(), pg));
+                    stack.push((kids.clone(), pg, parent, depth));
                 }
             }
             _ => {}
@@ -218,13 +228,13 @@ pub fn figures(doc: &Document) -> Vec<Figure> {
     let index: HashMap<ObjRef, usize> = pages.iter().enumerate().map(|(i, p)| (p.obj, i)).collect();
     elements(doc)
         .into_iter()
-        .filter(|(_, d, _)| d.name(b"S").is_some_and(|s| standard(doc, &role_map, s) == b"Figure"))
-        .map(|(obj, d, pg)| {
-            let page = pg.and_then(|p| index.get(&p).copied());
-            let alt = d.get(b"Alt").map(|o| doc.resolve(o)).and_then(|o| o.as_string().map(|s| s.to_text()));
-            let ids: HashSet<i64> = mcids(&d).into_iter().collect();
+        .filter(|e| e.dict.name(b"S").is_some_and(|s| standard(doc, &role_map, s) == b"Figure"))
+        .map(|e| {
+            let page = e.page.and_then(|p| index.get(&p).copied());
+            let alt = e.dict.get(b"Alt").map(|o| doc.resolve(o)).and_then(|o| o.as_string().map(|s| s.to_text()));
+            let ids: HashSet<i64> = mcids(&e.dict).into_iter().collect();
             let bbox = page.and_then(|p| content_bbox(doc, &pages[p].dict, &ids));
-            Figure { obj, page, alt, bbox }
+            Figure { obj: e.object, page, alt, bbox }
         })
         .collect()
 }
@@ -258,7 +268,7 @@ pub fn mark_decorative(doc: &mut Document, obj: ObjRef) -> Result<(), AltError>
     let d = check_figure(doc, obj)?;
     let ids: HashSet<i64> = mcids(&d).into_iter().collect();
     let pages = pdfcraft_model::pages(doc);
-    let pg = d.get(b"Pg").and_then(Object::as_ref).or_else(|| elements(doc).into_iter().find(|(r, _, _)| *r == obj).and_then(|(_, _, p)| p));
+    let pg = d.get(b"Pg").and_then(Object::as_ref).or_else(|| elements(doc).into_iter().find(|e| e.object == obj).and_then(|e| e.page));
     if let Some(page) = pg.and_then(|p| pages.iter().find(|x| x.obj == p)).filter(|_| !ids.is_empty()) {
         let mut ops = pdfcraft_content::parse(&page_content(doc, &page.dict)).ops;
         let mut changed = false;

crates/a11y/src/autotag.rs

@@ -0,0 +1,282 @@
+//! Create a valid, reviewable structure tree for PDFs whose painted content is text only.
+//!
+//! The writer refuses mixed content and existing tags. Each text object becomes a paragraph,
+//! which can then be retagged with the existing tag-property tool after human review.
+
+use pdfcraft_content::{Op, parse, serialize_ops};
+use pdfcraft_cos::{Dict, Document, ObjRef, Object, Stream};
+
+const MAX_PAGES: usize = 1_000;
+const MAX_PAGE_BYTES: usize = 16 * 1024 * 1024;
+const MAX_OPERATORS: usize = 100_000;
+const MAX_TEXT_OBJECTS: usize = 4_096;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct AutoTagResult {
+    pub pages: usize,
+    pub paragraphs: usize,
+}
+
+#[derive(Debug, thiserror::Error, PartialEq)]
+pub enum AutoTagError {
+    #[error("the document already has a structure tree; review its existing tags instead")]
+    AlreadyTagged,
+    #[error("the document has no text objects to tag")]
+    NoText,
+    #[error("the document has too many pages to auto-tag in one edit (maximum {MAX_PAGES})")]
+    TooManyPages,
+    #[error("page {page}: {reason}")]
+    Unsupported { page: usize, reason: String },
+    #[error("the PDF has no document catalog")]
+    NoCatalog,
+    #[error(transparent)]
+    Cos(#[from] pdfcraft_cos::CosError),
+}
+
+struct Plan {
+    page: ObjRef,
+    ops: Vec<Op>,
+    spans: Vec<(usize, usize)>,
+}
+
+fn unsupported(page: usize, reason: impl Into<String>) -> AutoTagError {
+    AutoTagError::Unsupported { page: page + 1, reason: reason.into() }
+}
+
+fn content_bytes(doc: &Document, page: &pdfcraft_model::Page, index: usize) -> Result<Vec<u8>, AutoTagError> {
+    let Some(contents) = page.dict.get(b"Contents") else { return Ok(Vec::new()) };
+    let resolved = doc.resolve(contents);
+    let pieces: Vec<Object> = match &*resolved {
+        Object::Array(items) => items.clone(),
+        Object::Stream(_) => vec![contents.clone()],
+        _ => return Err(unsupported(index, "contents are not a stream or array of streams")),
+    };
+    let mut all = Vec::new();
+    for item in pieces {
+        let value = doc.resolve(&item);
+        let Object::Stream(stream) = &*value else { return Err(unsupported(index, "contents include a non-stream object")) };
+        let remaining = MAX_PAGE_BYTES.saturating_sub(all.len().saturating_add(1));
+        if remaining == 0 {
+            return Err(unsupported(index, "decoded content exceeds 16 MiB"));
+        }
+        let chain = stream.filters();
+        let decoded = if chain.is_empty() {
+            if stream.raw.len() > remaining {
+                return Err(unsupported(index, "decoded content exceeds 16 MiB"));
+            }
+            stream.raw.to_vec()
+        } else {
+            pdfcraft_filters::decode(&chain, &stream.raw, remaining)
+                .map_err(|e| unsupported(index, format!("content cannot be decoded strictly: {e}")))?
+        };
+        all.extend_from_slice(&decoded);
+        all.push(b'\n');
+    }
+    Ok(all)
+}
+
+fn harmless_outside(op: &[u8]) -> bool {
+    matches!(
+        op,
+        b"q" | b"Q"
+            | b"cm"
+            | b"w"
+            | b"J"
+            | b"j"
+            | b"M"
+            | b"d"
+            | b"ri"
+            | b"i"
+            | b"gs"
+            | b"G"
+            | b"g"
+            | b"RG"
+            | b"rg"
+            | b"K"
+            | b"k"
+            | b"CS"
+            | b"cs"
+            | b"SC"
+            | b"sc"
+            | b"SCN"
+            | b"scn"
+    )
+}
+
+fn harmless_inside(op: &[u8]) -> bool {
+    matches!(
+        op,
+        b"Tf"
+            | b"Tc"
+            | b"Tw"
+            | b"Tz"
+            | b"TL"
+            | b"Tr"
+            | b"Ts"
+            | b"Td"
+            | b"TD"
+            | b"Tm"
+            | b"T*"
+            | b"G"
+            | b"g"
+            | b"RG"
+            | b"rg"
+            | b"K"
+            | b"k"
+            | b"CS"
+            | b"cs"
+            | b"SC"
+            | b"sc"
+            | b"SCN"
+            | b"scn"
+    )
+}
+
+fn plan(doc: &Document) -> Result<Vec<Plan>, AutoTagError> {
+    let root = doc.root().ok_or(AutoTagError::NoCatalog)?;
+    let catalog = doc.get(root);
+    let catalog = catalog.as_dict().ok_or(AutoTagError::NoCatalog)?;
+    if catalog.contains(b"StructTreeRoot") {
+        return Err(AutoTagError::AlreadyTagged);
+    }
+    if catalog.contains(b"AcroForm") {
+        return Err(unsupported(0, "form fields need their own tags; this text-only action cannot tag them"));
+    }
+    let pages = pdfcraft_model::pages(doc);
+    if pages.len() > MAX_PAGES {
+        return Err(AutoTagError::TooManyPages);
+    }
+    let mut out = Vec::with_capacity(pages.len());
+    let mut total = 0usize;
+    for (index, page) in pages.iter().enumerate() {
+        if page.dict.contains(b"StructParents") {
+            return Err(unsupported(index, "page already has a structure parent key"));
+        }
+        if page.dict.get(b"Annots").is_some_and(|a| match &*doc.resolve(a) {
+            Object::Array(items) => !items.is_empty(),
+            _ => true,
+        }) {
+            return Err(unsupported(index, "annotations need separate structure tags"));
+        }
+        let bytes = content_bytes(doc, page, index)?;
+        let parsed = parse(&bytes);
+        if parsed.skipped > 0 || parsed.ops.len() > MAX_OPERATORS {
+            return Err(unsupported(index, "content has malformed or too many operators"));
+        }
+        let mut start = None;
+        let mut has_text = false;
+        let mut spans = Vec::new();
+        for (at, op) in parsed.ops.iter().enumerate() {
+            match op.op.as_slice() {
+                b"BT" if start.is_none() => {
+                    start = Some(at);
+                    has_text = false;
+                }
+                b"ET" => {
+                    let Some(first) = start.take() else { return Err(unsupported(index, "unmatched ET operator")) };
+                    if has_text {
+                        spans.push((first, at));
+                        if spans.len() > MAX_TEXT_OBJECTS {
+                            return Err(unsupported(index, "too many text objects (maximum 4096)"));
+                        }
+                    }
+                }
+                b"Tj" | b"TJ" | b"'" | b"\"" if start.is_some() => has_text = true,
+                name if start.is_some() && harmless_inside(name) => {}
+                name if start.is_none() && harmless_outside(name) => {}
+                _ => return Err(unsupported(index, format!("unsupported or painted operator {}", String::from_utf8_lossy(&op.op)))),
+            }
+        }
+        if start.is_some() {
+            return Err(unsupported(index, "unterminated BT text object"));
+        }
+        total = total.saturating_add(spans.len());
+        out.push(Plan { page: page.obj, ops: parsed.ops, spans });
+    }
+    if total == 0 {
+        return Err(AutoTagError::NoText);
+    }
+    Ok(out)
+}
+
+/// Tag every text object in an untagged, text-only PDF as a paragraph. The full structure tree,
+/// parent tree and marked-content IDs are written together. Mixed content is refused before any
+/// mutation. On success the caller can use tag-property edits to assign reviewed heading roles.
+pub fn autotag_text(doc: &mut Document) -> Result<AutoTagResult, AutoTagError> {
+    let plans = plan(doc)?;
+    let mut next = doc.clone();
+    let catalog = next.root().ok_or(AutoTagError::NoCatalog)?;
+    let root = next.add(Object::Null);
+    let document = next.add(Object::Null);
+    let mut children = Vec::new();
+    let mut numbers = Vec::new();
+    let mut tagged_pages = 0usize;
+    let mut paragraphs = 0usize;
+    for page in plans {
+        if page.spans.is_empty() {
+            continue;
+        }
+        let key = i64::try_from(tagged_pages).map_err(|_| AutoTagError::TooManyPages)?;
+        let mut parents = Vec::with_capacity(page.spans.len());
+        let mut starts = std::collections::HashMap::new();
+        let mut ends = std::collections::HashSet::new();
+        for (mcid, (first, last)) in page.spans.iter().enumerate() {
+            let mut element = Dict::new();
+            element.set(b"Type".to_vec(), Object::name("StructElem"));
+            element.set(b"S".to_vec(), Object::name("P"));
+            element.set(b"P".to_vec(), Object::Ref(document));
+            element.set(b"Pg".to_vec(), Object::Ref(page.page));
+            element.set(b"K".to_vec(), Object::Int(i64::try_from(mcid).map_err(|_| AutoTagError::TooManyPages)?));
+            let reference = next.add(element);
+            parents.push(Object::Ref(reference));
+            children.push(Object::Ref(reference));
+            starts.insert(*first, mcid);
+            ends.insert(*last);
+            paragraphs = paragraphs.saturating_add(1);
+        }
+        let mut marked = Vec::with_capacity(page.ops.len().saturating_add(page.spans.len().saturating_mul(2)));
+        for (at, op) in page.ops.into_iter().enumerate() {
+            if let Some(mcid) = starts.get(&at) {
+                let mut properties = Dict::new();
+                properties.set(b"MCID".to_vec(), Object::Int(i64::try_from(*mcid).map_err(|_| AutoTagError::TooManyPages)?));
+                marked.push(Op::new("BDC", vec![Object::name("P"), Object::Dict(properties)]));
+            }
+            marked.push(op);
+            if ends.contains(&at) {
+                marked.push(Op::new("EMC", Vec::new()));
+            }
+        }
+        let stream = next.add(Stream::flate(Dict::new(), &serialize_ops(&marked)));
+        next.update_dict(page.page, |d| {
+            d.set(b"Contents".to_vec(), Object::Ref(stream));
+            d.set(b"StructParents".to_vec(), Object::Int(key));
+        })?;
+        numbers.push(Object::Int(key));
+        numbers.push(Object::Array(parents));
+        tagged_pages += 1;
+    }
+    let mut tree = Dict::new();
+    tree.set(b"Nums".to_vec(), Object::Array(numbers));
+    let parent_tree = next.add(tree);
+    let mut doc_element = Dict::new();
+    doc_element.set(b"Type".to_vec(), Object::name("StructElem"));
+    doc_element.set(b"S".to_vec(), Object::name("Document"));
+    doc_element.set(b"P".to_vec(), Object::Ref(root));
+    doc_element.set(b"K".to_vec(), Object::Array(children));
+    next.set(document, doc_element);
+    let mut structure = Dict::new();
+    structure.set(b"Type".to_vec(), Object::name("StructTreeRoot"));
+    structure.set(b"K".to_vec(), Object::Ref(document));
+    structure.set(b"ParentTree".to_vec(), Object::Ref(parent_tree));
+    structure.set(b"ParentTreeNextKey".to_vec(), Object::Int(i64::try_from(tagged_pages).map_err(|_| AutoTagError::TooManyPages)?));
+    next.set(root, structure);
+    let mark_info = next.get(catalog).as_dict().and_then(|d| d.get(b"MarkInfo")).map(|m| next.resolve(m)).and_then(|m| m.as_dict().cloned());
+    let mut mark_info = mark_info.unwrap_or_default();
+    mark_info.set(b"Marked".to_vec(), Object::Bool(true));
+    next.update_dict(catalog, |d| {
+        d.set(b"StructTreeRoot".to_vec(), Object::Ref(root));
+        d.set(b"MarkInfo".to_vec(), Object::Dict(mark_info));
+    })?;
+    *doc = next;
+    Ok(AutoTagResult { pages: tagged_pages, paragraphs })
+}

crates/a11y/src/content.rs

@@ -218,6 +218,20 @@ fn subtype_name(d: &Dict) -> String {
     String::from_utf8_lossy(d.name(b"Subtype").unwrap_or(b"Unknown")).into_owned()
 }
 
+/// An annotation's rectangle is already in page user space. Ignore missing, malformed and
+/// degenerate rectangles rather than sending the checker to an arbitrary place on the page.
+fn annotation_rect(doc: &Document, annot: &Dict) -> Option<[f64; 4]> {
+    let rect = annot.get(b"Rect").map(|r| doc.resolve(r))?;
+    let values = rect.as_array()?;
+    let [x0, y0, x1, y1] = values.as_slice() else { return None };
+    let [x0, y0, x1, y1] = [x0, y0, x1, y1].map(|v| doc.resolve(v).as_f64());
+    let (x0, y0, x1, y1) = (x0?, y0?, x1?, y1?);
+    if ![x0, y0, x1, y1].iter().all(|v| v.is_finite()) || x0 == x1 || y0 == y1 {
+        return None;
+    }
+    Some([x0.min(x1), y0.min(y1), x0.max(x1), y0.max(y1)])
+}
+
 pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usize], scan: &Scan, tagged: bool) -> Vec<Finding> {
     let mut out = Vec::new();
     let annots = |p: &Page| -> Vec<(ObjRef, Dict)> {
@@ -260,7 +274,9 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
                             values.push(("{}", subtype_name(&a)));
                             "{} annotation on page {p} isn't tagged"
                         };
-                        out.push(Finding::worded(Some(p), pattern, values));
+                        let mut finding = Finding::worded(Some(p), pattern, values);
+                        finding.bbox = annotation_rect(doc, &a);
+                        out.push(finding);
                     }
                 }
             }
@@ -313,11 +329,13 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
                     }
                     let fd = doc.get(field).as_dict().cloned().unwrap_or_default();
                     if text_of(doc, &fd, b"TU").is_none() {
-                        out.push(Finding::worded(
+                        let mut finding = Finding::worded(
                             Some(p),
                             "Field \"{}\" on page {p} has no description (tooltip)",
                             vec![("{}", full_name(doc, field)), ("{p}", (p + 1).to_string())],
-                        ));
+                        );
+                        finding.bbox = annotation_rect(doc, &a);
+                        out.push(finding);
                     }
                 }
             }

crates/a11y/src/lib.rs

@@ -8,19 +8,23 @@
 
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
-use std::collections::BTreeSet;
+use std::collections::{BTreeSet, HashMap};
 
 use pdfcraft_cos::Document;
 
 mod alt;
+mod autotag;
 mod content;
 mod headings;
 mod report;
 mod structure;
+mod tags;
 
 pub use alt::{AltError, Figure, figures, mark_decorative, set_alt};
+pub use autotag::{AutoTagError, AutoTagResult, autotag_text};
 pub use headings::{Heading, headings};
 pub use report::{REPORT_WORDS, report_html};
+pub use tags::{TagError, TagInfo, TagPlacement, TagProperty, move_tag, set_tag_property, tags};
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Category {
@@ -422,6 +426,10 @@ impl Status {
 pub struct Finding {
     /// 0-based page, when the problem is on a page.
     pub page: Option<usize>,
+    /// Indirect structure element that caused the finding, when one is available.
+    pub object: Option<pdfcraft_cos::ObjRef>,
+    /// Bounds in PDF user space when the affected content can be located safely.
+    pub bbox: Option<[f64; 4]>,
     pub message: String,
     /// The English sentence with a hole, such as `{p}` or `{what}`, where each value went.
     pub pattern: &'static str,
@@ -432,13 +440,13 @@ pub struct Finding {
 impl Finding {
     /// A finding whose sentence says the same thing however the document is put together.
     pub fn plain(page: Option<usize>, sentence: &'static str) -> Self {
-        Finding { page, message: sentence.to_owned(), pattern: sentence, values: Vec::new() }
+        Finding { page, object: None, bbox: None, message: sentence.to_owned(), pattern: sentence, values: Vec::new() }
     }
 
     /// A finding built from a wording and what goes in its holes. The English `message` is filled
     /// in here, so it and `pattern` can never drift apart.
     pub fn worded(page: Option<usize>, pattern: &'static str, values: Vec<(&'static str, String)>) -> Self {
-        Finding { page, message: say(pattern, &values), pattern, values }
+        Finding { page, object: None, bbox: None, message: say(pattern, &values), pattern, values }
     }
 
     /// A finding that says where the problem is and, in `{what}`, what is wrong, each worded
@@ -450,7 +458,7 @@ impl Finding {
     pub fn nested(page: Option<usize>, pattern: &'static str, what: &'static str, mut values: Vec<(&'static str, String)>) -> Self {
         let message = say(&pattern.replace("{what}", what), &values);
         values.push(("{what}", what.to_owned()));
-        Finding { page, message, pattern, values }
+        Finding { page, object: None, bbox: None, message, pattern, values }
     }
 
     /// This finding as one sentence, said in the language `words` translates into.
@@ -612,6 +620,7 @@ pub fn check(doc: &Document, options: &Options) -> Report {
     let tagged = structure::has_struct_tree(doc);
     let scan = content::Scan::run(doc, &pages, &page_list);
     let mut tree_rules = structure::run(doc, &pages, &options.rules);
+    let mut figure_bounds: Option<HashMap<pdfcraft_cos::ObjRef, (usize, [f64; 4])>> = None;
     let mut results = Vec::with_capacity(32);
     for rule in Rule::ALL {
         if !options.rules.contains(&rule) {
@@ -636,6 +645,24 @@ pub fn check(doc: &Document, options: &Options) -> Report {
             }
             _ => tree_rules.remove(&rule).unwrap_or_default(),
         };
+        if rule.category() == Category::AlternateText && findings.iter().any(|f| f.object.is_some()) {
+            let bounds = figure_bounds.get_or_insert_with(|| {
+                figures(doc)
+                    .into_iter()
+                    .filter_map(|figure| {
+                        let (page, bbox) = (figure.page?, figure.bbox?);
+                        (bbox.iter().all(|v| v.is_finite()) && bbox[0] < bbox[2] && bbox[1] < bbox[3]).then_some((figure.obj, (page, bbox)))
+                    })
+                    .collect()
+            });
+            for finding in &mut findings {
+                if let Some((page, bbox)) = finding.object.and_then(|obj| bounds.get(&obj))
+                    && finding.page == Some(*page)
+                {
+                    finding.bbox = Some(*bbox);
+                }
+            }
+        }
         if total > MAX_FINDINGS {
             let more = total - MAX_FINDINGS;
             findings.truncate(MAX_FINDINGS);

crates/a11y/src/report.rs

@@ -48,6 +48,10 @@ pub fn report_html(report: &Report, file_name: &str, date: &str, lang: &str, wor
     // `REPORT_WORDS` can be read off this file.
     h.push_str(&if report.count(Status::Failed) > 0 {
         esc(&words("The checker found problems which may prevent the document from being fully accessible."))
+    } else if report.count(Status::Manual) > 0 {
+        format!("{}: {}", esc(&words(Status::Manual.label())), report.count(Status::Manual))
+    } else if report.count(Status::Skipped) > 0 {
+        format!("{}: {}", esc(&words(Status::Skipped.label())), report.count(Status::Skipped))
     } else {
         esc(&words("The checker found no problems in this document."))
     });

crates/a11y/src/structure.rs

@@ -154,6 +154,8 @@ fn kind_of(ty: &[u8]) -> Kind {
 /// is filled in as the walk goes on.
 #[derive(Debug)]
 pub(crate) struct Frame {
+    /// Indirect object holding this tag, if it is not an inline dictionary.
+    object: Option<ObjRef>,
     /// The standard type after the role map, or the type as written when it maps to nothing.
     ty: Vec<u8>,
     kind: Kind,
@@ -314,7 +316,7 @@ impl Walker<'_> {
             }
             Object::Int(_) => self.mark_content(),
             Object::Ref(r) => self.reference(*r, depth, page, v),
-            Object::Dict(_) => self.dict(loc, depth, page, v),
+            Object::Dict(_) => self.dict(loc, depth, page, None, v),
             _ => {}
         }
     }
@@ -326,13 +328,13 @@ impl Walker<'_> {
         }
         let target = self.doc.get(r);
         if target.as_dict().is_some() {
-            self.dict(&Loc { owner: target, path: Vec::new() }, depth, page, v);
+            self.dict(&Loc { owner: target, path: Vec::new() }, depth, page, Some(r), v);
         }
     }
 
     /// A dictionary. Marked content and object references only mark the open element; a
     /// dictionary with /S is an element, and its /K kids are read inside it.
-    fn dict<V: Visitor>(&mut self, loc: &Loc, depth: usize, page: Option<usize>, v: &mut V) {
+    fn dict<V: Visitor>(&mut self, loc: &Loc, depth: usize, page: Option<usize>, object: Option<ObjRef>, v: &mut V) {
         let Some(d) = loc.value().and_then(|o| o.as_dict()) else { return };
         match d.name(b"Type") {
             Some(b"MCR") => return self.mark_content(),
@@ -356,6 +358,7 @@ impl Walker<'_> {
         let kind = kind_of(&ty);
         let attrs = if matches!(kind, Kind::Table | Kind::Td | Kind::Th) { self.attr_dicts(d) } else { Vec::new() };
         let frame = Frame {
+            object,
             ty,
             kind,
             index: self.opened,
@@ -463,13 +466,15 @@ fn row_owner(path: &[Frame]) -> Option<usize> {
 fn worded(e: &Frame, what: &'static str, extra: Vec<(&'static str, String)>) -> Finding {
     let mut values = extra;
     values.push(("{ty}", String::from_utf8_lossy(&e.ty).into_owned()));
-    match e.page {
+    let mut finding = match e.page {
         Some(p) => {
             values.push(("{p}", p.saturating_add(1).to_string()));
             Finding::nested(e.page, "{ty} element on page {p}: {what}", what, values)
         }
         None => Finding::nested(None, "{ty} element: {what}", what, values),
-    }
+    };
+    finding.object = e.object;
+    finding
 }
 
 /// A finding whose `{what}` wording has no holes of its own.

crates/a11y/src/tags.rs

@@ -0,0 +1,166 @@
+//! Properties of reachable indirect structure elements.
+
+use pdfcraft_cos::{CosError, Document, ObjRef, Object, PdfString};
+
+use crate::alt;
+
+/// A tag that can be addressed by an edit. Inline dictionaries have no stable object reference.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct TagInfo {
+    pub object: ObjRef,
+    /// Nearest reachable indirect parent, if any. Inline ancestors are skipped.
+    pub parent: Option<ObjRef>,
+    /// Indentation level among reachable indirect tags.
+    pub depth: usize,
+    pub kind: String,
+    pub title: Option<String>,
+    pub actual_text: Option<String>,
+    pub alt: Option<String>,
+    pub language: Option<String>,
+    /// Zero-based page when `/Pg` is known.
+    pub page: Option<usize>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TagProperty {
+    Type,
+    Title,
+    ActualText,
+    AlternateText,
+    Language,
+}
+
+/// Where to place a structure tag relative to one of its direct siblings.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TagPlacement {
+    Before,
+    After,
+}
+
+impl TagProperty {
+    pub fn from_id(id: &str) -> Option<Self> {
+        match id {
+            "type" => Some(Self::Type),
+            "title" => Some(Self::Title),
+            "actual_text" => Some(Self::ActualText),
+            "alternate_text" => Some(Self::AlternateText),
+            "language" => Some(Self::Language),
+            _ => None,
+        }
+    }
+
+    fn key(self) -> &'static [u8] {
+        match self {
+            Self::Type => b"S",
+            Self::Title => b"T",
+            Self::ActualText => b"ActualText",
+            Self::AlternateText => b"Alt",
+            Self::Language => b"Lang",
+        }
+    }
+}
+
+#[derive(Debug, thiserror::Error, PartialEq)]
+pub enum TagError {
+    #[error("object {0} is not a reachable indirect structure tag")]
+    NotATag(ObjRef),
+    #[error("a tag type must be a nonempty PDF name using letters, digits, colon, period, underscore or hyphen")]
+    InvalidType,
+    #[error("tag property text is too long (maximum 65536 bytes)")]
+    TooLong,
+    #[error("both tags must be distinct, reachable, direct children of the same structure parent")]
+    NotSiblings,
+    #[error("the parent must list each tag exactly once in its /K array")]
+    AmbiguousChildren,
+    #[error("the tag is already at the requested position")]
+    AlreadyThere,
+    #[error(transparent)]
+    Cos(#[from] CosError),
+}
+
+/// Reorder two direct sibling tags in their parent's `/K` array. Content and page appearance
+/// stay untouched; tagged reading order follows the new array order.
+pub fn move_tag(doc: &mut Document, object: ObjRef, anchor: ObjRef, placement: TagPlacement) -> Result<(), TagError> {
+    if object == anchor {
+        return Err(TagError::NotSiblings);
+    }
+    let reachable = alt::elements(doc);
+    if !reachable.iter().any(|e| e.object == object) || !reachable.iter().any(|e| e.object == anchor) {
+        return Err(TagError::NotSiblings);
+    }
+    let parent_of = |r| doc.get(r).as_dict().and_then(|d| d.get(b"P").and_then(Object::as_ref));
+    let Some(parent) = parent_of(object) else { return Err(TagError::NotSiblings) };
+    if parent_of(anchor) != Some(parent) {
+        return Err(TagError::NotSiblings);
+    }
+    let owner = doc.get(parent);
+    let Some(children) = owner.as_dict().and_then(|d| d.get(b"K").and_then(Object::as_array)) else {
+        return Err(TagError::AmbiguousChildren);
+    };
+    let one_position = |child| {
+        let mut matches = children.iter().enumerate().filter(|(_, item)| item.as_ref() == Some(child));
+        matches.next().and_then(|(index, _)| matches.next().is_none().then_some(index))
+    };
+    let (Some(from), Some(to)) = (one_position(object), one_position(anchor)) else { return Err(TagError::AmbiguousChildren) };
+    let mut reordered = children.clone();
+    let moved = reordered.remove(from);
+    let target = if from < to { to - 1 } else { to };
+    let destination = target + usize::from(placement == TagPlacement::After);
+    if destination == from {
+        return Err(TagError::AlreadyThere);
+    }
+    reordered.insert(destination, moved);
+    doc.update_dict(parent, |d| d.set(b"K".to_vec(), Object::Array(reordered)))?;
+    Ok(())
+}
+
+fn text(doc: &Document, d: &pdfcraft_cos::Dict, key: &[u8]) -> Option<String> {
+    d.get(key).map(|o| doc.resolve(o)).and_then(|o| o.as_string().map(PdfString::to_text))
+}
+
+/// List reachable, indirect tags in structure-tree order.
+pub fn tags(doc: &Document) -> Vec<TagInfo> {
+    let pages = pdfcraft_model::pages(doc);
+    let page_index: std::collections::HashMap<ObjRef, usize> = pages.iter().enumerate().map(|(i, p)| (p.obj, i)).collect();
+    alt::elements(doc)
+        .into_iter()
+        .filter_map(|e| {
+            Some(TagInfo {
+                object: e.object,
+                parent: e.parent,
+                depth: e.depth,
+                kind: String::from_utf8_lossy(e.dict.name(b"S")?).into_owned(),
+                title: text(doc, &e.dict, b"T"),
+                actual_text: text(doc, &e.dict, b"ActualText"),
+                alt: text(doc, &e.dict, b"Alt"),
+                language: text(doc, &e.dict, b"Lang"),
+                page: e.page.and_then(|p| page_index.get(&p).copied()),
+            })
+        })
+        .collect()
+}
+
+/// Change one property of a reachable tag; `None` removes a text property.
+pub fn set_tag_property(doc: &mut Document, object: ObjRef, property: TagProperty, value: Option<&str>) -> Result<(), TagError> {
+    if !alt::elements(doc).iter().any(|e| e.object == object) {
+        return Err(TagError::NotATag(object));
+    }
+    // ActualText may intentionally contain leading or trailing whitespace; preserve it.
+    let value = value.filter(|s| !s.is_empty());
+    if value.is_some_and(|s| s.len() > 65_536) {
+        return Err(TagError::TooLong);
+    }
+    if property == TagProperty::Type
+        && !value.is_some_and(|s| s.len() <= 127 && s.as_bytes().iter().all(|b| b.is_ascii_alphanumeric() || matches!(b, b':' | b'.' | b'_' | b'-')))
+    {
+        return Err(TagError::InvalidType);
+    }
+    doc.update_dict(object, |d| match value {
+        Some(s) if property == TagProperty::Type => d.set(property.key().to_vec(), Object::name(s)),
+        Some(s) => d.set(property.key().to_vec(), Object::String(PdfString::text(s))),
+        None => {
+            d.remove(property.key());
+        }
+    })?;
+    Ok(())
+}

crates/a11y/src/tests.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use pdfcraft_cos::Document;
+use pdfcraft_cos::{Document, Object};
 
 use super::*;
 
@@ -35,6 +35,67 @@ fn failed(r: &Report) -> Vec<Rule> {
 
 const FONT: &str = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>";
 
+#[test]
+fn autotag_text_writes_marked_content_and_parent_tree_across_pages() {
+    let mut doc = pdf(
+        &[
+            "<< /Type /Catalog /Pages 2 0 R >>".into(),
+            "<< /Type /Pages /Kids [3 0 R 6 0 R] /Count 2 >>".into(),
+            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>".into(),
+            stream("BT /F1 18 Tf 20 160 Td (Heading) Tj ET BT /F1 12 Tf 20 120 Td (Body) Tj ET"),
+            FONT.into(),
+            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Contents 7 0 R /Resources << /Font << /F1 5 0 R >> >> >>".into(),
+            stream("BT /F1 12 Tf 20 120 Td (Second page) Tj ET"),
+        ],
+        "",
+    );
+    let result = autotag_text(&mut doc).unwrap();
+    assert_eq!(result, AutoTagResult { pages: 2, paragraphs: 3 });
+    let catalog = doc.get(doc.root().unwrap());
+    let root = catalog.as_dict().unwrap().reference(b"StructTreeRoot").unwrap();
+    let tree = doc.get(root);
+    let parent_tree = tree.as_dict().unwrap().reference(b"ParentTree").unwrap();
+    let numbers = doc.get(parent_tree);
+    let entries = numbers.as_dict().unwrap().get(b"Nums").unwrap().as_array().unwrap();
+    assert_eq!(entries.len(), 4);
+    assert_eq!(entries[0].as_int(), Some(0));
+    assert_eq!(entries[2].as_int(), Some(1));
+    assert_eq!(entries[1].as_array().unwrap().len(), 2);
+    assert_eq!(entries[3].as_array().unwrap().len(), 1);
+    for page in pdfcraft_model::pages(&doc) {
+        let content = page.dict.get(b"Contents").unwrap();
+        let stream = doc.resolve(content);
+        let Object::Stream(stream) = &*stream else { panic!("marked page content") };
+        let text = String::from_utf8(stream.decoded_strict().unwrap()).unwrap();
+        assert!(text.contains("/P <</MCID 0>> BDC"), "{text}");
+        assert!(text.contains("EMC"), "{text}");
+    }
+    let report = check(&doc, &Options::default());
+    assert_eq!(status(&report, Rule::TaggedPdf), Status::Passed);
+    assert_eq!(status(&report, Rule::TaggedContent), Status::Passed);
+    let bytes = pdfcraft_cos::write_incremental(&doc, &pdfcraft_cos::SaveOptions::default()).unwrap();
+    let reopened = Document::open(Arc::new(bytes)).unwrap();
+    assert_eq!(tags(&reopened).len(), 4);
+    assert_eq!(status(&check(&reopened, &Options::default()), Rule::TaggedContent), Status::Passed);
+}
+
+#[test]
+fn autotag_text_refuses_paint_and_does_not_modify_the_document() {
+    let mut doc = pdf(
+        &[
+            "<< /Type /Catalog /Pages 2 0 R >>".into(),
+            "<< /Type /Pages /Kids [3 0 R] /Count 1 >>".into(),
+            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>".into(),
+            stream("BT /F1 12 Tf 20 100 Td (Hello) Tj ET 0 0 50 50 re f"),
+            FONT.into(),
+        ],
+        "",
+    );
+    assert!(matches!(autotag_text(&mut doc), Err(AutoTagError::Unsupported { .. })));
+    assert!(!doc.get(doc.root().unwrap()).as_dict().unwrap().contains(b"StructTreeRoot"));
+    assert_eq!(autotag_text(&mut pdf(&good(), "")), Err(AutoTagError::AlreadyTagged));
+}
+
 #[test]
 fn an_untagged_document_fails_the_document_rules() {
     let doc = pdf(
@@ -164,6 +225,48 @@ fn structure_doc(objects: &[String]) -> Document {
     pdf(&objs, "")
 }
 
+#[test]
+fn reachable_tag_properties_round_trip_and_reject_unrelated_objects() {
+    let mut doc =
+        structure_doc(&["<< /S /Document /K [4 0 R] >>".into(), "<< /S /Figure /T (Old) /Alt (A chart) >>".into(), "<< /S /Figure >>".into()]);
+    let tag = pdfcraft_cos::ObjRef::new(4, 0);
+    let listed = tags(&doc);
+    assert_eq!(listed.len(), 2);
+    assert_eq!(listed[1].object, tag);
+    assert_eq!(listed[1].title.as_deref(), Some("Old"));
+    for (property, value) in [
+        (TagProperty::Type, "P"),
+        (TagProperty::Title, "Figure title"),
+        (TagProperty::ActualText, " Revenue increased "),
+        (TagProperty::AlternateText, "A rising chart"),
+        (TagProperty::Language, "en-GB"),
+    ] {
+        set_tag_property(&mut doc, tag, property, Some(value)).unwrap();
+    }
+    let edited = &tags(&doc)[1];
+    assert_eq!(edited.kind, "P");
+    assert_eq!(edited.title.as_deref(), Some("Figure title"));
+    assert_eq!(edited.actual_text.as_deref(), Some(" Revenue increased "));
+    assert_eq!(edited.alt.as_deref(), Some("A rising chart"));
+    assert_eq!(edited.language.as_deref(), Some("en-GB"));
+    set_tag_property(&mut doc, tag, TagProperty::Title, None).unwrap();
+    assert_eq!(tags(&doc)[1].title, None);
+    assert!(matches!(set_tag_property(&mut doc, tag, TagProperty::Type, None), Err(TagError::InvalidType)));
+    assert!(matches!(set_tag_property(&mut doc, tag, TagProperty::Type, Some("bad type")), Err(TagError::InvalidType)));
+    assert!(matches!(set_tag_property(&mut doc, pdfcraft_cos::ObjRef::new(5, 0), TagProperty::Title, Some("No")), Err(TagError::NotATag(_))));
+    assert!(matches!(set_tag_property(&mut doc, pdfcraft_cos::ObjRef::new(4, 1), TagProperty::Title, Some("No")), Err(TagError::NotATag(_))));
+}
+
+#[test]
+fn tag_hierarchy_keeps_indirect_parent_through_inline_tags() {
+    let doc = structure_doc(&["<< /S /Document /K 4 0 R >>".into(), "<< /S /Sect /K << /S /Div /K 5 0 R >> >>".into(), "<< /S /Figure >>".into()]);
+    let listed = tags(&doc);
+    assert_eq!(
+        listed.iter().map(|t| (t.object.num, t.parent.map(|p| p.num), t.depth)).collect::<Vec<_>>(),
+        [(3, None, 0), (4, Some(3), 1), (5, Some(4), 2)]
+    );
+}
+
 fn checked(doc: &Document, rules: &[Rule]) -> Report {
     check(doc, &Options { rules: rules.iter().copied().collect(), pages: None })
 }
@@ -216,6 +319,16 @@ fn cycles_shared_kids_and_missing_kids_are_read_once() {
     assert_eq!(r.result(Rule::FiguresAltText).unwrap().findings.len(), 1);
 }
 
+#[test]
+fn structure_findings_identify_indirect_elements_without_guessing_inline_objects() {
+    let doc = structure_doc(&["<< /S /Document /K [4 0 R << /S /Figure >>] >>".into(), "<< /S /Figure >>".into()]);
+    let r = checked(&doc, &[Rule::FiguresAltText]);
+    let found = &r.result(Rule::FiguresAltText).unwrap().findings;
+    assert_eq!(found.len(), 2);
+    assert_eq!(found[0].object.map(|r| r.num), Some(4));
+    assert_eq!(found[1].object, None);
+}
+
 #[test]
 fn nesting_is_read_to_the_depth_limit_and_no_further() {
     // Sections, each the kid of the one before, ending in a figure without alternate text. The
@@ -300,6 +413,19 @@ fn page_content_and_annotation_problems_are_found() {
     assert_eq!(got, [Rule::TaggedContent, Rule::TaggedAnnotations, Rule::TabOrder, Rule::FieldDescriptions]);
     assert_eq!(r.result(Rule::TaggedContent).unwrap().findings[0].message, "Page 1: 1 untagged content item");
     assert!(r.result(Rule::FieldDescriptions).unwrap().findings[0].message.contains("\"name\""));
+    assert_eq!(r.result(Rule::TaggedAnnotations).unwrap().findings[0].bbox, Some([20.0, 20.0, 80.0, 40.0]));
+    assert_eq!(r.result(Rule::FieldDescriptions).unwrap().findings[0].bbox, Some([20.0, 60.0, 120.0, 80.0]));
+}
+
+#[test]
+fn annotation_findings_only_locate_valid_rectangles() {
+    let cases = [("[80 40 20 20]", Some([20.0, 20.0, 80.0, 40.0])), ("[20 20 20 40]", None), ("[20 20 80]", None), ("[20 20 80 (bad)]", None)];
+    for (rect, expected) in cases {
+        let mut objs = good();
+        objs[8] = format!("<< /Type /Annot /Subtype /Link /Rect {rect} >>");
+        let r = checked(&pdf(&objs, "/Info 8 0 R"), &[Rule::TaggedAnnotations]);
+        assert_eq!(r.result(Rule::TaggedAnnotations).unwrap().findings[0].bbox, expected, "{rect}");
+    }
 }
 
 #[test]
@@ -356,6 +482,13 @@ fn rules_have_ids_and_the_report_lists_them() {
     let other = report_html(&report, "a<b>.pdf", "2026-10-02", "es", &|w| format!("«{w}»"));
     assert!(other.contains("<html lang=\"es\">") && other.contains("<h3>«Headings»</h3>") && other.contains("a&lt;b&gt;.pdf"));
     assert!(!other.contains(">Headings<"), "an English heading is left in the report: {other}");
+    let manual_only = Report { results: vec![RuleResult { rule: Rule::LogicalReadingOrder, status: Status::Manual, findings: Vec::new() }] };
+    let manual_html = report_html(&manual_only, "review.pdf", "2026-10-02", "en", &in_english);
+    assert!(manual_html.contains("<p>Needs manual check: 1</p>"));
+    assert!(!manual_html.contains("no problems"));
+    let all_passed = Report { results: vec![RuleResult { rule: Rule::LogicalReadingOrder, status: Status::Passed, findings: Vec::new() }] };
+    let passed_html = report_html(&all_passed, "review.pdf", "2026-10-02", "en", &in_english);
+    assert!(passed_html.contains("<p>The checker found no problems in this document.</p>"), "{passed_html}");
 }
 
 fn figures_doc() -> Document {
@@ -388,6 +521,49 @@ fn figures_are_listed_with_their_alt_text_and_place() {
     assert_eq!(f.len(), 2, "role-mapped Photo counts");
     assert_eq!((f[0].page, f[0].alt.as_deref(), f[0].bbox), (Some(0), None, Some([10.0, 150.0, 50.0, 170.0])));
     assert_eq!((f[1].alt.as_deref(), f[1].bbox), (Some("A bar"), Some([100.0, 100.0, 150.0, 130.0])));
+    let report = check(&doc, &Options { rules: [Rule::FiguresAltText].into(), pages: None });
+    let finding = &report.result(Rule::FiguresAltText).unwrap().findings[0];
+    assert_eq!((finding.object, finding.page, finding.bbox), (Some(f[0].obj), Some(0), f[0].bbox));
+}
+
+#[test]
+fn sibling_tags_move_in_reading_order_without_changing_content() {
+    let mut doc = figures_doc();
+    let before: Vec<_> = tags(&doc).into_iter().map(|tag| tag.object.num).collect();
+    assert_eq!(before, [6, 7, 8]);
+    let content = doc.get(pdfcraft_cos::ObjRef::new(4, 0));
+    move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 0), pdfcraft_cos::ObjRef::new(7, 0), TagPlacement::Before).unwrap();
+    assert_eq!(tags(&doc).into_iter().map(|tag| tag.object.num).collect::<Vec<_>>(), [6, 8, 7]);
+    assert_eq!(doc.get(pdfcraft_cos::ObjRef::new(4, 0)), content, "page content stays unchanged");
+    assert_eq!(
+        move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 0), pdfcraft_cos::ObjRef::new(7, 0), TagPlacement::Before),
+        Err(TagError::AlreadyThere)
+    );
+    move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 0), pdfcraft_cos::ObjRef::new(7, 0), TagPlacement::After).unwrap();
+    assert_eq!(tags(&doc).into_iter().map(|tag| tag.object.num).collect::<Vec<_>>(), [6, 7, 8]);
+    assert_eq!(
+        move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 0), pdfcraft_cos::ObjRef::new(6, 0), TagPlacement::Before),
+        Err(TagError::NotSiblings)
+    );
+    assert_eq!(
+        move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 1), pdfcraft_cos::ObjRef::new(7, 0), TagPlacement::Before),
+        Err(TagError::NotSiblings)
+    );
+    doc.update_dict(pdfcraft_cos::ObjRef::new(6, 0), |d| {
+        d.set(
+            b"K".to_vec(),
+            pdfcraft_cos::Object::Array(vec![
+                pdfcraft_cos::Object::Ref(pdfcraft_cos::ObjRef::new(7, 0)),
+                pdfcraft_cos::Object::Ref(pdfcraft_cos::ObjRef::new(8, 0)),
+                pdfcraft_cos::Object::Ref(pdfcraft_cos::ObjRef::new(7, 0)),
+            ]),
+        );
+    })
+    .unwrap();
+    assert_eq!(
+        move_tag(&mut doc, pdfcraft_cos::ObjRef::new(8, 0), pdfcraft_cos::ObjRef::new(7, 0), TagPlacement::After),
+        Err(TagError::AmbiguousChildren)
+    );
 }
 
 #[test]

crates/annot/README.md

@@ -10,7 +10,14 @@ Comments (annotations), ISO 32000-2 §12.5. Layer L3, depends on `pdfcraft-cos`,
 - **Appearance streams** (`appearance::build`) generated from the annotation dictionary, so new
   and restyled comments look the same in every viewer. Highlights multiply (`/BM /Multiply`).
   Note icons are PdfCraft's own drawings. Text boxes use standard Helvetica (WinAnsi), with
-  line breaking by approximate Helvetica proportions (no font program is bundled).
+  line breaking by approximate Helvetica proportions (no font program is bundled). Text it can't
+  draw (in a text box, callout, Fill & Sign text, measurement label or dynamic stamp's by-line;
+  `appearance::undrawable_text`) is kept as typed and drawn as `?`, and the comment is marked with
+  the first such character (`pdfcraft_fonts::UNDRAWN_MARK`) so the engine reports the edit and
+  flattening refuses to make it permanent. Two refusals (`AnnotError::Undrawable`): a redaction
+  mark's overlay text, which becomes page content when applied; and a restyle or resize of a
+  comment another program drew with a font that has those characters, whose appearance is kept
+  rather than redrawn with `?` (new text for it is taken).
 - **Edits:** reply (`/IRT`), set review status (a `/State` reply, as Acrobat's "Set status"
   does), change text, move, resize, restyle, delete (with pop-up and replies).
 
@@ -40,10 +47,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.
+- Picture stamps (a natural-size or explicit-rectangle image, a PDF page, or an image
+  signature) and PdfCraft's rubber stamps counterrotate their appearance on rotated pages, so
+  the picture or label reads upright as the page is displayed. Restyling a picture stamp keeps
+  that appearance matrix. The rotation is the page's `/Rotate` at placement.
 
 ## Not yet
 

crates/annot/src/appearance.rs

@@ -11,8 +11,8 @@
 //! Helvetica's proportions by character class (no font program or metrics file is bundled).
 
 use pdfcraft_cos::{Dict, Object, PdfString, Stream};
+use pdfcraft_fonts::{first_undrawable, literal, win_ansi};
 pub use pdfcraft_fonts::{helvetica_width as text_width, wrap};
-use pdfcraft_fonts::{literal, win_ansi};
 
 use crate::{NOTE_SIZE, Rgb, n};
 
@@ -264,7 +264,32 @@ 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
 }
 
+/// The page `/Rotate` a rubber stamp's label is turned back by (`/PCStampRotate`).
+fn stamp_turn(d: &Dict) -> i64 {
+    d.get(b"PCStampRotate").and_then(Object::as_int).unwrap_or(0).rem_euclid(360) / 90 * 90
+}
+
+/// The first text [`build`] would draw in the standard fonts (Helvetica, WinAnsiEncoding) that
+/// they can't, which would come out as `?`: what it is (for the message) and the character. The
+/// text of a text box, callout or Fill & Sign text, a measurement's label, a dynamic stamp's
+/// "By …" line, and a redaction mark's overlay text (drawn when it is applied). `None` when all of
+/// it can be drawn.
+pub fn undrawable_text(d: &Dict) -> Option<(&'static str, char)> {
+    let text = |key: &[u8]| d.get(key).and_then(Object::as_string).map(PdfString::to_text);
+    let (what, text) = match d.name(b"Subtype")? {
+        b"FreeText" => ("the comment's text", text(b"Contents")?),
+        b"Line" | b"PolyLine" | b"Polygon" => ("the measurement label", text(b"PCMeasureValue")?),
+        b"Stamp" if matches!(d.get(b"PCStamp"), Some(Object::Bool(true))) => ("the stamp's \"By\" line", text(b"PCByLine")?),
+        // Drawn in Helvetica when the redaction is applied: refused when it is marked.
+        b"Redact" => ("the redaction's overlay text", text(b"OverlayText")?),
+        _ => return None,
+    };
+    Some((what, first_undrawable(&text)?))
+}
+
 /// Draw the normal appearance of an annotation, or `None` if this subtype/variant isn't supported.
+/// Text the standard fonts can't draw comes out as `?`: [`undrawable_text`] says which, and
+/// [`crate::set_appearance`] marks the annotation with it (`pdfcraft_fonts::UNDRAWN_MARK`).
 pub fn build(d: &Dict) -> Option<Stream> {
     // Imported measurement appearances may include leaders, captions and formatting that
     // this builder cannot reproduce. Preserve them rather than silently losing detail.
@@ -612,7 +637,26 @@ pub fn build(d: &Dict) -> Option<Stream> {
                     }
                     let kind = crate::StampKind::from_name(other)?;
                     let by = d.get(b"PCByLine").and_then(|o| o.as_string()).map(PdfString::to_text);
-                    return Some(stamp(kind, rect, stroke.unwrap_or(kind.color()), by.as_deref(), opacity, res));
+                    let turn = stamp_turn(d);
+                    let draw = if turn == 0 {
+                        rect
+                    } else {
+                        let (rw, rh) = (rect[2] - rect[0], rect[3] - rect[1]);
+                        let (dw, dh) = if matches!(turn, 90 | 270) { (rh, rw) } else { (rw, rh) };
+                        if dw < 1.0 || dh < 1.0 {
+                            return None;
+                        }
+                        [0.0, 0.0, dw, dh]
+                    };
+                    let mut stream = stamp(kind, draw, stroke.unwrap_or(kind.color()), by.as_deref(), opacity, res);
+                    if turn != 0 {
+                        // Upright in the stamp's displayed box, then mapped into `/Rect` the way
+                        // the page maps display space into user space. Viewers fit that box to
+                        // `/Rect`; the page rotation then shows the label the right way up.
+                        let m = pdfcraft_model::view_matrix_for(turn, rect);
+                        stream.dict.set(b"Matrix".to_vec(), Object::Array(m.iter().copied().map(Object::Real).collect()));
+                    }
+                    return Some(stream);
                 }
             }
         }

crates/annot/src/lib.rs

@@ -14,7 +14,7 @@
 
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
-use pdfcraft_cos::{Dict, Document, ObjRef, Object, PdfString};
+use pdfcraft_cos::{Dict, Document, ObjRef, Object, PdfString, Stream};
 
 pub mod appearance;
 pub mod links;
@@ -26,7 +26,8 @@ mod tests;
 pub enum AnnotError {
     #[error("the document has no page tree")]
     NoPageTree,
-    #[error("page {0} does not exist")]
+    /// Holds the 0-based index; the message names the 1-based page a user counts (#1550).
+    #[error("page {} does not exist", .0.saturating_add(1))]
     NoSuchPage(usize),
     #[error("there is no comment {index} on page {page}")]
     NoSuchAnnotation { page: usize, index: usize },
@@ -34,6 +35,11 @@ pub enum AnnotError {
     Invalid(String),
     #[error("{0} comments can't be restyled yet (their appearance can't be regenerated)")]
     Unsupported(String),
+    /// Text the standard fonts can't draw where `?` would be permanent or replace a good drawing:
+    /// a redaction's overlay text, or an edit that would redraw a comment another program drew
+    /// with a font that has those characters. The message names the character.
+    #[error("{0}")]
+    Undrawable(String),
     #[error("{0}")]
     Cos(#[from] pdfcraft_cos::CosError),
 }
@@ -1085,6 +1091,11 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
             if let Some(b) = by {
                 d.set(b"PCByLine".to_vec(), PdfString::text(b));
             }
+            // The label is drawn for the page as displayed. A later page rotation is a new edit.
+            let turn = pdfcraft_model::pages(doc).get(new.page).map_or(0, |p| p.rotation(doc));
+            if matches!(turn, 90 | 180 | 270) {
+                d.set(b"PCStampRotate".to_vec(), Object::Int(turn));
+            }
         }
         Shape::TypedSignature { contours, .. } => {
             d.set(b"C".to_vec(), rgb(style.color));
@@ -1202,8 +1213,16 @@ pub fn add_annotation(doc: &mut Document, new: &NewAnnotation, meta: &Meta) -> R
         // Survives a later subject edit, so flatten-on-save still finds the mark.
         d.set(b"PCFillSign".to_vec(), Object::Bool(true));
     }
+    // A redaction's overlay text becomes page content when it is applied, where `?` would be there
+    // for good: refused before anything is added. A comment's own text is stored as typed and
+    // drawn with `?` for what the standard fonts can't draw (marked, see `draw_appearance`).
+    if d.name(b"Subtype") == Some(b"Redact")
+        && let Some((what, c)) = appearance::undrawable_text(&d)
+    {
+        return Err(AnnotError::Undrawable(pdfcraft_fonts::undrawable_message(what, c)));
+    }
     let r = doc.add(Object::Dict(d.clone()));
-    set_appearance(doc, r)?;
+    draw_appearance(doc, r)?;
     let mut list = annots(doc, page);
     let index = list.len();
     list.push(Object::Ref(r));
@@ -1223,8 +1242,9 @@ 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.
+/// Counterrotate a newly placed picture stamp's appearance into displayed-page axes.
+/// The picture may be an image or a PDF page. 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],
@@ -1234,8 +1254,8 @@ pub fn orient_image_stamp(doc: &mut Document, page: usize, index: usize, rotatio
     };
     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()));
+    if d.name(b"Subtype") != Some(b"Stamp") || d.get(b"PCPicture").is_none() {
+        return Err(AnnotError::Invalid("only a picture stamp can be oriented".into()));
     }
     let normal = d
         .get(b"AP")
@@ -1250,14 +1270,60 @@ pub fn orient_image_stamp(doc: &mut Document, page: usize, index: usize, rotatio
     Ok(())
 }
 
-/// (Re)generate `/AP /N` for the annotation `r` from its dictionary.
-/// Regenerate an annotation's normal appearance from its dictionary.
+/// A comment another program drew, whose text the standard fonts can't draw. Redrawing it would
+/// replace those characters with `?`, so the edit is refused before the dictionary changes.
+fn refuse_foreign_text(doc: &Document, d: &Dict) -> Result<(), AnnotError> {
+    let drawn_elsewhere =
+        d.get(b"AP").is_some_and(|ap| doc.resolve(ap).as_dict().is_some_and(|ap| ap.contains(b"N"))) && pdfcraft_fonts::undrawn_mark(d).is_none();
+    if drawn_elsewhere && let Some((what, c)) = appearance::undrawable_text(d) {
+        return Err(AnnotError::Undrawable(format!(
+            "PdfCraft can't redraw this comment: the standard fonts can't draw \"{}\" (U+{:04X}) in {what}, which would then show as ? (the comment was left as it is)",
+            c.escape_debug(),
+            u32::from(c)
+        )));
+    }
+    Ok(())
+}
+
+/// (Re)generate `/AP /N` for the annotation `r` from its dictionary, for an edit that keeps its
+/// text (a restyle, a new size or colour).
+///
+/// A comment whose text the standard fonts can't draw, with an appearance another program drew
+/// (with a font that has those characters), keeps that appearance: redrawing it would put `?` in
+/// their place, so the edit is refused (`AnnotError::Undrawable`). One PdfCraft drew with `?`
+/// (marked `pdfcraft_fonts::UNDRAWN_MARK`) is redrawn.
 pub fn set_appearance(doc: &mut Document, r: ObjRef) -> Result<(), AnnotError> {
+    refuse_foreign_text(doc, &annot_dict(doc, r))?;
+    draw_appearance(doc, r)
+}
+
+/// Put `before` back when redrawing fails, so a refused edit does not keep the new rectangle or style.
+fn redraw_or_restore(doc: &mut Document, r: ObjRef, before: Dict) -> Result<(), AnnotError> {
+    if let Err(e) = set_appearance(doc, r) {
+        doc.set(r, Object::Dict(before));
+        return Err(e);
+    }
+    Ok(())
+}
+
+/// Draw `r`'s normal appearance from its dictionary, whatever its text: characters the standard
+/// fonts can't draw come out as `?`, and the annotation is marked (`pdfcraft_fonts::UNDRAWN_MARK`,
+/// cleared when all of it can be drawn) so the edit is reported and flattening won't make that
+/// `?` permanent. For new text (a new comment, changed contents), as Acrobat keeps text its font
+/// can't show, and for display-only copies.
+fn draw_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(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 Some(stream) = build_appearance(doc, &d) else { return Err(AnnotError::Unsupported(subtype)) };
+    apply_appearance(doc, r, &d, stream)
+}
+
+/// Draw the appearance for an annotation dictionary: the expensive half of [`set_appearance`].
+/// Pure from the dictionary and the objects it points at, so [`AppearanceCache`] can reuse it.
+fn build_appearance(doc: &Document, d: &Dict) -> Option<Stream> {
+    let mut stream = appearance::build(d)?;
+    // Picture-stamp restyling must retain the placement's page-axis correction.
+    if d.get(b"PCPicture").is_some() {
         let matrix = d.get(b"AP").and_then(|ap| {
             let ap = doc.resolve(ap);
             let normal = doc.resolve(ap.as_dict()?.get(b"N")?);
@@ -1268,6 +1334,13 @@ pub fn set_appearance(doc: &mut Document, r: ObjRef) -> Result<(), AnnotError> {
             stream.dict.set(b"Matrix".to_vec(), matrix);
         }
     }
+    Some(stream)
+}
+
+/// Store a built appearance on the annotation: the cheap half of [`set_appearance`].
+fn apply_appearance(doc: &mut Document, r: ObjRef, d: &Dict, stream: Stream) -> Result<(), AnnotError> {
+    // Characters the standard fonts can't draw came out as `?`: mark the annotation with the first.
+    let missing = appearance::undrawable_text(d).map(|(_, c)| c);
     let ap = doc.add(Object::Stream(stream));
     // 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.
@@ -1278,16 +1351,80 @@ pub fn set_appearance(doc: &mut Document, r: ObjRef) -> Result<(), AnnotError> {
     doc.update_dict(r, |d| {
         d.set(b"AP".to_vec(), Object::Dict(apd));
         d.remove(b"AS");
+        pdfcraft_fonts::set_undrawn_mark(d, missing);
     })?;
     Ok(())
 }
 
+/// Display appearances built for annotations without any, reused while the annotation
+/// dictionaries they were drawn from are unchanged.
+///
+/// A content edit (moving a paragraph, retyping text, …) leaves every annotation dictionary
+/// alone, but the display copy is rebuilt from the edited document on every refresh: without
+/// this cache each refresh redrew every appearance (27k on one CAD file, ~0.7 s per edit
+/// commit). Entries are keyed by annotation reference; object numbers are never reused within
+/// a document lineage, so an entry stays valid until an annotation edit runs. Callers clear
+/// the cache on any refresh that may change annotations (comments, structural and full
+/// refreshes) and keep it for content-only ones.
+#[derive(Clone, Debug, Default)]
+pub struct AppearanceCache {
+    entries: std::collections::HashMap<ObjRef, Stream>,
+    bytes: usize,
+    hits: u64,
+    builds: u64,
+}
+
+impl AppearanceCache {
+    /// Cached appearance data restarts past this instead of growing without bound.
+    const MAX_BYTES: usize = 64 << 20;
+
+    /// Forget every entry (an annotation edit may have changed the dictionaries).
+    pub fn clear(&mut self) {
+        *self = Self::default();
+    }
+
+    fn get(&mut self, r: ObjRef) -> Option<Stream> {
+        let stream = self.entries.get(&r)?.clone();
+        self.hits += 1;
+        Some(stream)
+    }
+
+    fn insert(&mut self, r: ObjRef, stream: &Stream) {
+        self.builds += 1;
+        if self.entries.len() >= 1_000_000 {
+            self.clear();
+        }
+        if self.bytes.saturating_add(stream.raw.len()) <= Self::MAX_BYTES {
+            self.bytes += stream.raw.len();
+            self.entries.insert(r, stream.clone());
+        }
+        // Else over budget: keep serving the entries already cached instead of growing.
+    }
+
+    /// Cache hits so far (reused appearances); for tests.
+    pub fn hits(&self) -> u64 {
+        self.hits
+    }
+
+    /// Appearances built so far; for tests.
+    pub fn builds(&self) -> u64 {
+        self.builds
+    }
+}
+
 /// A copy of `doc` in which every annotation without a normal appearance (`/AP /N`) has the one
 /// [`appearance::build`] draws from its dictionary, for displaying the document (`None` when no
 /// annotation needs one). Many files carry comments without appearances (FreeText, Ink, notes,
 /// stamps, …) that viewers draw from the dictionary. `doc` is not changed: saving writes the file
 /// as it was. Links, form fields and pop-ups keep their own handling.
 pub fn with_missing_appearances(doc: &Document) -> Option<Document> {
+    with_missing_appearances_cached(doc, &mut AppearanceCache::default())
+}
+
+/// A copy of `doc` with [`AppearanceCache`] reuse across refreshes: annotations whose
+/// dictionary is unchanged since the cached build keep their stored appearance instead of
+/// redrawing it. See [`AppearanceCache`] for when entries stay valid.
+pub fn with_missing_appearances_cached(doc: &Document, cache: &mut AppearanceCache) -> Option<Document> {
     let mut copy: Option<Document> = None;
     for page in page_refs(doc).ok()? {
         for r in annots(doc, page).iter().filter_map(Object::as_ref) {
@@ -1296,11 +1433,18 @@ pub fn with_missing_appearances(doc: &Document) -> Option<Document> {
                 continue;
             }
             let has_normal = d.get(b"AP").is_some_and(|ap| doc.resolve(ap).as_dict().is_some_and(|ap| ap.contains(b"N")));
-            if has_normal || appearance::build(&d).is_none() {
+            if has_normal {
                 continue;
             }
-            // Fails only when `r` isn't a dictionary, which `build` above has just ruled out.
-            set_appearance(copy.get_or_insert_with(|| doc.clone()), r).ok();
+            if let Some(stream) = cache.get(r) {
+                // Fails only when `r` isn't a dictionary, which the cached build ruled out.
+                apply_appearance(copy.get_or_insert_with(|| doc.clone()), r, &d, stream).ok();
+                continue;
+            }
+            let Some(stream) = build_appearance(doc, &d) else { continue };
+            cache.insert(r, &stream);
+            // Fails only when `r` isn't a dictionary, which the build just ruled out.
+            apply_appearance(copy.get_or_insert_with(|| doc.clone()), r, &d, stream).ok();
         }
     }
     copy
@@ -1407,10 +1551,12 @@ pub fn set_contents(doc: &mut Document, page: usize, index: usize, text: &str, m
     })?;
     if free_text {
         // The box grows and shrinks with the text instead of clipping it. A locked box keeps its
-        // text editable (as in Acrobat), so the re-fit ignores the lock.
+        // text editable (as in Acrobat), so the re-fit ignores the lock. New text is drawn even
+        // where the standard fonts can't draw some of it (marked and reported, see
+        // `draw_appearance`).
         match fitted_box(doc, r, text) {
-            Some(rect) => apply_text_box(doc, r, rect, meta)?,
-            None => set_appearance(doc, r)?,
+            Some(rect) => apply_text_box(doc, r, rect, meta, true)?,
+            None => draw_appearance(doc, r)?,
         }
     }
     Ok(())
@@ -1618,7 +1764,7 @@ pub fn set_rect(doc: &mut Document, page: usize, index: usize, rect: [f64; 4], m
     if !matches!(subtype.as_str(), "Square" | "Circle" | "FreeText") {
         return Err(AnnotError::Invalid(format!("{subtype} comments can't be resized")));
     }
-    apply_text_box(doc, r, rect, meta)
+    apply_text_box(doc, r, rect, meta, false)
 }
 
 /// Scale a drawing's strokes into `rect`. The margin between the strokes and the old `/Rect` (half
@@ -1658,23 +1804,27 @@ fn resize_ink(doc: &mut Document, r: ObjRef, rect: [f64; 4], meta: &Meta) -> Res
             s.iter().map(|p| [axis(p[0], inner[0], inner[2], target[0], target[2]), axis(p[1], inner[1], inner[3], target[1], target[3])]).collect()
         })
         .collect();
+    let before = annot_dict(doc, r);
     doc.update_dict(r, |d| {
         d.set(b"InkList".to_vec(), Object::Array(scaled.iter().map(|s| num_array(&s.concat())).collect()));
         d.set(b"Rect".to_vec(), num_array(&rect));
         touch(d, meta);
     })?;
-    set_appearance(doc, r)?;
-    Ok(())
+    redraw_or_restore(doc, r, before)
 }
 
 /// Store `rect` as a FreeText annotation's text box (or a square's/oval's rectangle): a callout's
-/// leader line re-attaches and `/Rect` grows to hold it, and the appearance is redrawn.
-fn apply_text_box(doc: &mut Document, r: ObjRef, rect: [f64; 4], meta: &Meta) -> Result<(), AnnotError> {
+/// leader line re-attaches and `/Rect` grows to hold it, and the appearance is redrawn
+/// (`new_text`: for changed contents, see [`set_appearance`] and `draw_appearance`).
+fn apply_text_box(doc: &mut Document, r: ObjRef, rect: [f64; 4], meta: &Meta, new_text: bool) -> Result<(), AnnotError> {
     let rect = normalize(rect);
     if !finite(&rect) || rect[2] - rect[0] < 1.0 || rect[3] - rect[1] < 1.0 {
         return Err(AnnotError::Invalid("invalid rectangle (too small)".into()));
     }
     let d = annot_dict(doc, r);
+    if !new_text {
+        refuse_foreign_text(doc, &d)?;
+    }
     // A callout's rectangle is its text box: the leader line re-attaches and `/Rect` grows to hold it.
     let callout = d.get(b"CL").and_then(|o| o.as_array()).map(|a| a.iter().filter_map(|x| x.as_f64()).collect::<Vec<f64>>()).filter(|l| l.len() == 6);
     let (outer, cl) = match callout {
@@ -1700,7 +1850,16 @@ fn apply_text_box(doc: &mut Document, r: ObjRef, rect: [f64; 4], meta: &Meta) ->
         }
         touch(d, meta);
     })?;
-    set_appearance(doc, r)
+    let before = d;
+    if new_text {
+        if let Err(e) = draw_appearance(doc, r) {
+            doc.set(r, Object::Dict(before));
+            return Err(e);
+        }
+        Ok(())
+    } else {
+        redraw_or_restore(doc, r, before)
+    }
 }
 
 fn border_width_of(d: &Dict) -> f64 {
@@ -1737,7 +1896,9 @@ pub fn set_style(
             return Err(AnnotError::Invalid("this comment has no line endings to change".into()));
         }
     }
+    refuse_foreign_text(doc, &d)?;
     let free_text = subtype == "FreeText";
+    let before = d;
     doc.update_dict(r, |d| {
         if let Some(c) = color {
             if free_text {
@@ -1775,7 +1936,7 @@ pub fn set_style(
         ensure_ending_room(d);
         touch(d, meta);
     })?;
-    set_appearance(doc, r)
+    redraw_or_restore(doc, r, before)
 }
 
 /// Whether a comment of this subtype has an interior that can be filled (`/IC`: rectangles,
@@ -1801,6 +1962,8 @@ pub fn set_fill(doc: &mut Document, page: usize, index: usize, fill: Option<Rgb>
     if fill.is_some_and(|c| !finite(&c)) {
         return Err(AnnotError::Invalid("invalid fill colour".into()));
     }
+    refuse_foreign_text(doc, &d)?;
+    let before = d;
     doc.update_dict(r, |d| {
         match fill {
             Some(c) => d.set(b"IC".to_vec(), rgb(c)),
@@ -1810,7 +1973,7 @@ pub fn set_fill(doc: &mut Document, page: usize, index: usize, fill: Option<Rgb>
         }
         touch(d, meta);
     })?;
-    set_appearance(doc, r)
+    redraw_or_restore(doc, r, before)
 }
 
 /// Grow a line or polyline's rectangle so a non-`None` ending is not clipped. Idempotent.

crates/annot/src/tests.rs

@@ -187,6 +187,7 @@ fn invalid_geometry_is_rejected() {
         assert!(matches!(add_annotation(&mut doc, &new(0, s.clone()), &meta("x")), Err(AnnotError::Invalid(_))), "{s:?}");
     }
     assert_eq!(add_annotation(&mut doc, &new(5, Shape::Rectangle { rect: [0.0, 0.0, 10.0, 10.0] }), &meta("x")), Err(AnnotError::NoSuchPage(5)));
+    assert_eq!(AnnotError::NoSuchPage(5).to_string(), "page 6 does not exist", "the message counts pages from 1 (#1550)");
     assert!(!doc.is_modified(), "failed adds change nothing");
 }
 
@@ -1158,3 +1159,117 @@ fn drawings_resize_by_scaling_their_strokes() {
     // Too small to hold the stroke margin.
     assert!(matches!(set_rect(&mut doc, 0, i, [100.0, 400.0, 101.0, 401.0], &meta("")), Err(AnnotError::Invalid(_))));
 }
+
+/// Comment text the standard fonts can't draw is kept, as Acrobat keeps it: a text box, Fill & Sign
+/// text or a dynamic stamp's by-line is added with its text as typed, its appearance draws `?` for
+/// those characters, and the comment is marked with the first one (cleared once all of it can be
+/// drawn). A comment another program drew with a font that has those characters keeps that
+/// appearance: a restyle is refused rather than replace it with `?`, while new text is taken.
+#[test]
+fn comment_text_the_standard_fonts_cannot_draw_is_kept_and_marked() {
+    let mut doc = fixture();
+    let mark = |doc: &Document, i: usize| pdfcraft_fonts::undrawn_mark(&list(doc, 0)[i]);
+    let mut boxed = new(0, Shape::TextBox { rect: [100.0, 600.0, 300.0, 650.0], font_size: 12.0 });
+    boxed.contents = "签名 Ada".into();
+    let t = add_annotation(&mut doc, &boxed, &meta("t")).unwrap();
+    assert_eq!(text(&list(&doc, 0)[t], b"Contents"), "签名 Ada");
+    assert!(ap_content(&doc, &list(&doc, 0)[t]).contains("(?? Ada)"), "{}", ap_content(&doc, &list(&doc, 0)[t]));
+    assert_eq!(mark(&doc, t), Some('签'));
+    let typed = Shape::Typewriter { rect: [100.0, 700.0, 200.0, 716.0], font_size: 11.0 };
+    let f = add_annotation(
+        &mut doc,
+        &NewAnnotation { page: 0, style: Style::default_for(&typed), shape: typed, contents: "张三".into(), author: "Ada".into() },
+        &meta("x"),
+    )
+    .unwrap();
+    assert_eq!(mark(&doc, f), Some('张'));
+    let stamp =
+        Shape::Stamp { rect: [100.0, 100.0, 260.0, 142.0], stamp: StampKind::DynApproved, by: Some("By 张三 at 2:14 pm, Oct 02, 2026".into()) };
+    let s = add_annotation(
+        &mut doc,
+        &NewAnnotation { page: 0, style: Style::default_for(&stamp), shape: stamp, contents: String::new(), author: "张三".into() },
+        &meta("s"),
+    )
+    .unwrap();
+    assert_eq!(mark(&doc, s), Some('张'));
+    // Our own `?` appearance is redrawn on a restyle; Western European text clears the mark.
+    set_style(&mut doc, 0, t, Some([1.0, 0.0, 0.0]), None, None, None, &meta("")).unwrap();
+    assert_eq!(mark(&doc, t), Some('签'));
+    set_contents(&mut doc, 0, t, "Zürich —\nGenève", &meta("")).unwrap();
+    assert_eq!(mark(&doc, t), None);
+    set_contents(&mut doc, 0, t, "签名", &meta("")).unwrap();
+    assert_eq!((text(&list(&doc, 0)[t], b"Contents").as_str(), mark(&doc, t)), ("签名", Some('签')));
+    // A text box another program drew (with a font that has 欢): a restyle keeps that appearance.
+    let mut foreign = Dict::new();
+    foreign.set(b"Type".to_vec(), Object::name("Annot"));
+    foreign.set(b"Subtype".to_vec(), Object::name("FreeText"));
+    foreign.set(b"Rect".to_vec(), Object::Array([100.0, 400.0, 300.0, 430.0].iter().map(|v| Object::Real(*v)).collect()));
+    foreign.set(b"DA".to_vec(), PdfString::literal(b"0 g /Helv 12 Tf".to_vec()));
+    foreign.set(b"Contents".to_vec(), PdfString::text("欢迎"));
+    let mut drawn = Dict::new();
+    drawn.set(b"Type".to_vec(), Object::name("XObject"));
+    drawn.set(b"Subtype".to_vec(), Object::name("Form"));
+    drawn.set(b"BBox".to_vec(), Object::Array([0.0, 0.0, 200.0, 30.0].iter().map(|v| Object::Real(*v)).collect()));
+    let drawn = doc.add(Object::Stream(pdfcraft_cos::Stream::from_raw(drawn, b"BT /F1 12 Tf (\x01\x02) Tj ET".to_vec())));
+    let mut ap = Dict::new();
+    ap.set(b"N".to_vec(), Object::Ref(drawn));
+    foreign.set(b"AP".to_vec(), Object::Dict(ap));
+    let r = doc.add(Object::Dict(foreign));
+    let page = page_ref(&doc, 0).unwrap();
+    let mut on_page = annots(&doc, page);
+    on_page.push(Object::Ref(r));
+    set_annots(&mut doc, page, on_page).unwrap();
+    let k = list(&doc, 0).len() - 1;
+    let before = list(&doc, 0)[k].clone();
+    let err = set_style(&mut doc, 0, k, Some([1.0, 0.0, 0.0]), Some(0.4), Some(6.0), None, &meta("")).unwrap_err();
+    assert!(matches!(&err, AnnotError::Undrawable(m) if m.contains("can't redraw") && m.contains("\"欢\" (U+6B22)")), "{err:?}");
+    assert_eq!(list(&doc, 0)[k], before, "a refused restyle keeps the colour, opacity, width and appearance");
+    let err = set_rect(&mut doc, 0, k, [40.0, 40.0, 180.0, 90.0], &meta("")).unwrap_err();
+    assert!(matches!(&err, AnnotError::Undrawable(_)), "{err:?}");
+    assert_eq!(list(&doc, 0)[k], before, "a refused resize keeps the rectangle");
+    // New text from the user is taken (and marked), as for any comment.
+    set_contents(&mut doc, 0, k, "欢迎光临", &meta("")).unwrap();
+    assert_eq!(mark(&doc, k), Some('欢'));
+    // One without an appearance is shown in the display copy only; drawing it marks it.
+    let mut bare = Dict::new();
+    bare.set(b"Type".to_vec(), Object::name("Annot"));
+    bare.set(b"Subtype".to_vec(), Object::name("FreeText"));
+    bare.set(b"Rect".to_vec(), Object::Array([100.0, 300.0, 300.0, 330.0].iter().map(|v| Object::Real(*v)).collect()));
+    bare.set(b"DA".to_vec(), PdfString::literal(b"0 g /Helv 12 Tf".to_vec()));
+    bare.set(b"Contents".to_vec(), PdfString::text("欢迎"));
+    let b = doc.add(Object::Dict(bare));
+    let mut on_page = annots(&doc, page);
+    on_page.push(Object::Ref(b));
+    set_annots(&mut doc, page, on_page).unwrap();
+    let shown = with_missing_appearances(&doc).expect("a display copy");
+    assert!(shown.get(b).as_dict().unwrap().contains(b"AP"), "displayed anyway");
+    assert!(!doc.get(b).as_dict().unwrap().contains(b"AP"), "the document itself is unchanged");
+    set_appearance(&mut doc, b).unwrap();
+    assert_eq!(doc.get(b).as_dict().and_then(pdfcraft_fonts::undrawn_mark), Some('欢'));
+    // Kept through a save.
+    let doc = reopen(&doc);
+    assert_eq!(text(&list(&doc, 0)[t], b"Contents"), "签名");
+}
+
+/// Content edits rebuild the display copy on every commit but leave annotations alone: the
+/// cached appearance is drawn once and reused after that, byte-identical.
+#[test]
+fn cached_appearances_are_reused_while_annotations_are_unchanged() {
+    let mut doc = fixture();
+    let idx = add_annotation(&mut doc, &new(0, Shape::Note { at: [100.0, 700.0], icon: NoteIcon::Comment }), &meta("cache")).expect("adds");
+    // Files carry comments without appearances; strip the created one to simulate that.
+    let page = page_refs(&doc).unwrap()[0];
+    let r = annots(&doc, page)[idx].as_ref().expect("indirect");
+    doc.update_dict(r, |d| {
+        d.remove(b"AP");
+    })
+    .expect("strips");
+    let mut cache = AppearanceCache::default();
+    let first = with_missing_appearances_cached(&doc, &mut cache).expect("builds");
+    assert_eq!((cache.builds(), cache.hits()), (1, 0), "only the note needs an appearance");
+    let second = with_missing_appearances_cached(&doc, &mut cache).expect("reuses");
+    assert_eq!((cache.builds(), cache.hits()), (1, 1), "nothing is redrawn");
+    let [a, b] = [&first, &second].map(|copy| ap_content(copy, &list(copy, 0)[idx]));
+    assert!(!a.is_empty());
+    assert_eq!(a, b, "the reused appearance is byte-identical");
+}

crates/audit/README.md

@@ -18,8 +18,9 @@ shading and highlights don't either: they're painted before the text, or light a
 
 Limits, by design and documented rather than hidden:
 
-- only `re` rectangles closed by a fill count as covers (not arbitrary paths, shadings or
-  patterns), and a translucent one (`/ca` below 1) is not flagged;
+- only filled rectangles count as covers, drawn with `re` or as a single `m`/`l` subpath whose
+  corners form an axis-aligned rectangle (not other paths, shadings or patterns), and a
+  translucent one (`/ca` below 1) is not flagged;
 - covers inside form XObjects are found, but only text drawn directly in the page content is
   checked under them;
 - annotation rectangles are compared in unrotated user space, so `/Rotate` pages may misalign.

crates/audit/src/cover.rs

@@ -1,10 +1,11 @@
 //! Walk page content streams and collect the opaque filled rectangles they draw.
 //!
 //! This is the geometric half of the faux-redaction audit: a rectangle filled with an opaque
-//! color (`re` + `f`) is the classic way a "redaction" is faked. Graphics state tracked here is
-//! deliberately small: the CTM stack (`q`/`Q`/`cm`), the non-stroking color (`g`/`rg`/`k`) and
-//! the non-stroking alpha from ExtGState (`gs` reading `/ca`). Form XObjects are followed
-//! read-only with a depth cap. Anything fancier (arbitrary filled paths, shadings, patterns) is
+//! color (`re` + `f`) is the classic way a "redaction" is faked. A single closed `m`/`l` subpath
+//! whose four corners form an axis-aligned rectangle in user space is the same shape and counts
+//! too (#1510). Graphics state tracked here is deliberately small: the CTM stack (`q`/`Q`/`cm`),
+//! the non-stroking color (`g`/`rg`/`k`) and the non-stroking alpha from ExtGState (`gs` reading
+//! `/ca`). Form XObjects are followed read-only with a depth cap. Anything fancier (other filled paths, shadings, patterns) is
 //! out of scope and documented as such.
 //!
 //! Paint order: a page's content streams are one stream in pieces (ISO 32000-2 §7.8.2), so they
@@ -45,6 +46,58 @@ struct Gs {
     alpha: f64,
 }
 
+/// The path under construction, as far as the audit cares about it.
+enum Path {
+    Empty,
+    /// A `re` rectangle, in user space.
+    Rect([f64; 4]),
+    /// One `m`/`l` subpath, corners already mapped to user space; `true` once closed by `h`.
+    Lines(Vec<[f64; 2]>, bool),
+    /// Anything else: curves, a second subpath, a CTM change mid-path.
+    Other,
+}
+
+impl Path {
+    /// The rectangle a fill of this path paints, if the path is one.
+    fn rect(self) -> Option<[f64; 4]> {
+        match self {
+            Path::Rect(r) => Some(r),
+            Path::Lines(pts, _) => lines_rect(pts),
+            Path::Empty | Path::Other => None,
+        }
+    }
+}
+
+/// The bounding box of a closed polygon that is an axis-aligned rectangle, or `None`. A repeated
+/// start point is dropped first; the remaining four corners must alternate horizontal and
+/// vertical edges.
+fn lines_rect(mut pts: Vec<[f64; 2]>) -> Option<[f64; 4]> {
+    // CTM products leave rounding noise, so corners compare with a tolerance (in points).
+    const EPS: f64 = 1e-6;
+    let same = |a: f64, b: f64| (a - b).abs() <= EPS;
+    if pts.len() == 5 && same(pts[0][0], pts[4][0]) && same(pts[0][1], pts[4][1]) {
+        pts.pop();
+    }
+    let [a, b, c, d] = <[[f64; 2]; 4]>::try_from(pts).ok()?;
+    let fits = |first_horizontal: bool| {
+        [(a, b), (b, c), (c, d), (d, a)]
+            .iter()
+            .enumerate()
+            .all(|(i, (p, q))| if (i % 2 == 0) == first_horizontal { same(p[1], q[1]) } else { same(p[0], q[0]) })
+    };
+    if !(fits(true) || fits(false)) {
+        return None;
+    }
+    let (xs, ys) = ([a[0], b[0], c[0], d[0]], [a[1], b[1], c[1], d[1]]);
+    let r = [
+        xs.into_iter().fold(f64::INFINITY, f64::min),
+        ys.into_iter().fold(f64::INFINITY, f64::min),
+        xs.into_iter().fold(f64::NEG_INFINITY, f64::max),
+        ys.into_iter().fold(f64::NEG_INFINITY, f64::max),
+    ];
+    (r[2] - r[0] > EPS && r[3] - r[1] > EPS).then_some(r)
+}
+
 impl Default for Gs {
     fn default() -> Self {
         Gs { ctm: Matrix::IDENTITY, fill: [0.0, 0.0, 0.0], alpha: 1.0 }
@@ -79,8 +132,7 @@ impl<'a> Walker<'a> {
         depth: usize,
         at_do: Option<(usize, usize)>,
     ) -> Result<(), AuditError> {
-        // A pending `re` rectangle, in the user space active when it was built.
-        let mut pending: Option<[f64; 4]> = None;
+        let mut path = Path::Empty;
         for (i, op) in ops.iter().enumerate() {
             self.bump()?;
             // Paint position of this operator: its own `(piece, joined index)` at page level,
@@ -95,15 +147,20 @@ impl<'a> Walker<'a> {
                     if let Some(g) = stack.pop() {
                         *gs = g;
                     }
-                    pending = None;
+                    path = Path::Empty;
                 }
                 b"cm" => {
+                    let before = gs.ctm;
                     if let Some(m) = Matrix::from_operands(&op.operands)
                         && m.0.iter().all(|v| v.is_finite())
                     {
                         gs.ctm = m.then(&gs.ctm);
                     }
-                    pending = None;
+                    // A `cm` that leaves the CTM unchanged (an identity matrix) cannot move the
+                    // pending path, so keep it for the fill (#1333).
+                    if gs.ctm != before && !matches!(path, Path::Empty) {
+                        path = Path::Other;
+                    }
                 }
                 b"g" => {
                     if let Some(v) = op.num(0).filter(|v| v.is_finite()) {
@@ -133,7 +190,7 @@ impl<'a> Walker<'a> {
                     }
                 }
                 b"re" => {
-                    pending = op.nums::<4>().and_then(|[x, y, w, h]| {
+                    let rect = op.nums::<4>().and_then(|[x, y, w, h]| {
                         if [x, y, w, h].iter().all(|v| v.is_finite()) && w != 0.0 && h != 0.0 {
                             let r = gs.ctm.bbox([x.min(x + w), y.min(y + h), x.max(x + w), y.max(y + h)]);
                             (r[2] > r[0] && r[3] > r[1]).then_some(r)
@@ -141,18 +198,39 @@ impl<'a> Walker<'a> {
                             None
                         }
                     });
+                    path = rect.map_or(Path::Other, Path::Rect);
+                }
+                b"m" => {
+                    path = match (path, user_point(gs, op)) {
+                        (Path::Empty, Some(p)) => Path::Lines(vec![p], false),
+                        _ => Path::Other,
+                    };
+                }
+                b"l" => {
+                    path = match (path, user_point(gs, op)) {
+                        // Past a repeated start point it can no longer be a rectangle.
+                        (Path::Lines(mut pts, false), Some(p)) if pts.len() < 5 => {
+                            pts.push(p);
+                            Path::Lines(pts, false)
+                        }
+                        _ => Path::Other,
+                    };
+                }
+                b"h" => {
+                    path = match path {
+                        Path::Lines(pts, _) => Path::Lines(pts, true),
+                        _ => Path::Other,
+                    };
                 }
                 b"f" | b"F" | b"f*" | b"B" | b"B*" => {
-                    if let Some(r) = pending.take()
+                    if let Some(r) = std::mem::replace(&mut path, Path::Empty).rect()
                         && gs.alpha >= 1.0
                     {
                         self.out.push(FilledRect { rect: r, rgb: gs.fill, pos });
                     }
-                    // Any other path construction clears the pending rectangle.
-                }
-                b"m" | b"l" | b"c" | b"v" | b"y" | b"h" | b"S" | b"s" | b"n" | b"W" | b"W*" => {
-                    pending = None;
                 }
+                b"S" | b"s" | b"n" => path = Path::Empty,
+                b"c" | b"v" | b"y" | b"W" | b"W*" => path = Path::Other,
                 b"Do" => {
                     if let Some(name) = op.name(0) {
                         if depth >= MAX_DEPTH {
@@ -160,7 +238,7 @@ impl<'a> Walker<'a> {
                         }
                         self.walk_xobject(name, gs, resources, depth, pos)?;
                     }
-                    pending = None;
+                    path = Path::Empty;
                 }
                 _ => {}
             }
@@ -201,6 +279,13 @@ impl<'a> Walker<'a> {
     }
 }
 
+/// The `x y` operands of `m`/`l`, mapped to user space.
+fn user_point(gs: &Gs, op: &Op) -> Option<[f64; 2]> {
+    let [x, y] = op.nums::<2>().filter(|v| v.iter().all(|n| n.is_finite()))?;
+    let (x, y) = gs.ctm.apply(x, y);
+    Some([x, y])
+}
+
 /// The non-stroking alpha (`/ca`) of a named ExtGState, defaulting to opaque.
 fn ext_alpha(doc: &Document, resources: &Dict, name: &[u8]) -> f64 {
     let alpha = resources

crates/audit/src/tests.rs

@@ -113,6 +113,20 @@ fn faux_redaction_is_found() {
     assert!(f.covered_text.contains("SECRET"), "covered_text was {:?}", f.covered_text);
 }
 
+#[test]
+fn identity_matrix_between_rectangle_and_fill_still_covers_text() {
+    // A no-op `cm` inside the path must not drop the pending rectangle (#1333).
+    for cover in [&b"0 g\n100 688 220 32 re 1 0 0 1 0 0 cm f\n"[..], b"0 g\n1 0 0 1 0 0 cm 100 688 220 32 re f\n"] {
+        let mut content = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n".to_vec();
+        content.extend_from_slice(cover);
+        let findings = audit_redactions(&open(one_page(&content, ""))).expect("audit must run");
+        assert_eq!(findings.len(), 1, "{:?}: {findings:?}", String::from_utf8_lossy(cover));
+        assert_eq!(findings[0].kind, FindingKind::CoveredText);
+        assert_eq!(findings[0].rect, [100.0, 688.0, 320.0, 720.0]);
+        assert_eq!(findings[0].covered_text, "SECRET DATA 123");
+    }
+}
+
 #[test]
 fn clean_document_has_no_findings() {
     let content = b"BT /F1 24 Tf 100 700 Td (nothing hidden here) Tj ET\n";
@@ -213,3 +227,48 @@ fn self_drawing_form_fails_the_audit() {
     let result = audit_redactions(&open(b.build()));
     assert!(matches!(result, Err(crate::AuditError::TooDeep)), "{result:?}");
 }
+
+#[test]
+fn rectangle_drawn_as_a_path_covers_text_like_re() {
+    // The same cover as `re`, built from `m`/`l` (closed with `h`, a repeated start point, or
+    // only by the fill itself), or in a scaled user space: all are faux redactions (#1510).
+    let covers: [&[u8]; 5] = [
+        b"0 g\n100 688 220 32 re f\n",
+        b"0 g\n100 688 m 320 688 l 320 720 l 100 720 l h f\n",
+        b"0 g\n100 688 m 320 688 l 320 720 l 100 720 l 100 688 l h f\n",
+        b"0 g\n100 688 m 100 720 l 320 720 l 320 688 l f\n",
+        b"0 g\nq 2 0 0 2 0 0 cm 50 344 m 160 344 l 160 360 l 50 360 l h f Q\n",
+    ];
+    for cover in covers {
+        let mut content = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n".to_vec();
+        content.extend_from_slice(cover);
+        let findings = audit_redactions(&open(one_page(&content, ""))).expect("audit must run");
+        assert_eq!(findings.len(), 1, "{:?}: {findings:?}", String::from_utf8_lossy(cover));
+        assert_eq!(findings[0].kind, FindingKind::CoveredText);
+        assert_eq!(findings[0].rect, [100.0, 688.0, 320.0, 720.0]);
+        assert_eq!(findings[0].covered_text, "SECRET DATA 123");
+    }
+}
+
+#[test]
+fn non_rectangular_path_is_not_a_cover() {
+    // Each path's bounding box covers the text, but the shape itself does not hide it all.
+    let covers: [&[u8]; 5] = [
+        // A triangle.
+        b"0 g\n100 688 m 320 688 l 320 720 l h f\n",
+        // A triangle, then a line from its start point after `h`: not a fourth corner.
+        b"0 g\n100 688 m 320 688 l 320 720 l h 100 720 l f\n",
+        // A trapezoid: four corners, one slanted side.
+        b"0 g\n100 688 m 320 688 l 320 720 l 140 720 l h f\n",
+        // A rectangle rotated 5 degrees about the text by the CTM.
+        b"0 g\nq 0.9962 0.0872 -0.0872 0.9962 62.15 -15.63 cm 100 688 m 320 688 l 320 720 l 100 720 l h f Q\n",
+        // Two subpaths filled together: even-odd leaves the inner one as a hole.
+        b"0 g\n90 680 m 330 680 l 330 730 l 90 730 l h 100 688 m 320 688 l 320 720 l 100 720 l h f*\n",
+    ];
+    for cover in covers {
+        let mut content = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n".to_vec();
+        content.extend_from_slice(cover);
+        let findings = audit_redactions(&open(one_page(&content, ""))).expect("audit must run");
+        assert!(findings.is_empty(), "{:?}: {findings:?}", String::from_utf8_lossy(cover));
+    }
+}

crates/automation/Cargo.toml

@@ -10,10 +10,13 @@ workspace = true
 
 [dependencies]
 pdfcraft-engine = { workspace = true }
+pdfcraft-cos = { workspace = true }
 pdfcraft-render = { workspace = true }
 pdfcraft-organize = { workspace = true }
 pdfcraft-platform = { workspace = true }
 serde_json = { workspace = true }
+sha2 = "0.11"
+tempfile = "3.27"
 png = "0.18"
 base64 = { version = "0.22", optional = true }
 
@@ -24,7 +27,8 @@ default = ["mcp"]
 mcp = ["dep:base64"]
 
 [dev-dependencies]
-pdfcraft-cos = { workspace = true }
+pdfcraft-fonts = { workspace = true }
+flate2.workspace = true
 pdfcraft-model = { workspace = true }
 pdfcraft-xfa = { workspace = true }
 image = { version = "0.25", default-features = false, features = ["jpeg"] }

crates/automation/README.md

@@ -25,9 +25,38 @@ mcp::McpServer::new(a).serve(stdin, stdout)?             // newline-delimited JS
 - Tools that change a document return its summary (`doc`, `pages`, `dirty`, `undo`, `redo`, …).
 - `comment_image_preview` returns JSON and a PNG: `layer: "background"` (the default) gives the page without the selected image signature/initials; `layer: "image"` gives its embedded image with alpha. The metadata supplies its displayed rectangle, document rotation, `image_rotation` (how far clockwise the image is shown turned: 0 for one placed by PdfCraft, which keeps it upright as displayed) and annotation opacity. Each result can be saved with the CLI's `--out`. Cache the background and transform the image for live movement/resizing; `comment_edit` commits the final geometry in one undo step. Previewing never changes the document.
 - For proportional image signature resizing, use the embedded image layer's width/height ratio rather than a previously stretched annotation rectangle. The GUI preserves this ratio at corners with the opposite corner anchored; edge midpoint handles change only their own axis. `comment_edit` accepts the resulting rectangle.
-- `doc_close` refuses to drop unsaved changes unless `discard_changes: true`. `doc_save` writes atomically, incrementally in place, and in full for a new path.
+- `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. Atomic output writes call `sync_all` on the staging file before replacing the destination. A write or sync error leaves the destination intact, removes staging and leaves the document dirty for retry. A filesystem that does not support syncing returns an error; there is no unsynced fallback. This flushes file contents, but does not guarantee persistence of the parent-directory rename across power loss.
 - 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 (`<path> is outside the allowed directory <root>`), 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.
 
+## Text search and cache limits
+
+Extracted page text is reused in a session-wide LRU cache: at most **64 MiB** of estimated owned
+text storage and **4,096 pages**, shared by all open documents. Accounting includes glyph-vector
+capacity, each glyph string's capacity, line indexes and word-break flags. Cache hits share the
+renderer result instead of copying glyphs. Oversized pages remain usable by the current call but
+are not cached; evicted pages can be extracted again. A changed document version invalidates its
+cached text on the next text request, and closing a document removes its entries. Cache entries
+do not keep an old PDF byte buffer alive.
+
+This bounds retained text-cache data, not total process memory: active extraction batches,
+renderers, document buffers and the requested output have separate lifetimes. Search still reads
+growing batches (8 to 128 pages), with one lookahead match to determine continuation.
+
+`text_find` keeps matches from readable pages when another reached page fails extraction. It
+returns `warnings` with 1-based `page`, `error` and `error_truncated`, plus `warning_count` and
+`warnings_truncated`. At most 100 warnings and 1,024 UTF-8 bytes per error are returned. Failures
+are retried on later calls; they are not cached as empty pages. Warnings describe pages visited in
+search order, up to the continuation point, not failures in unvisited later pages.
+
+`complete: true` means the requested search was exhausted with no page failures and no further
+matches. `next: {start_page, skip}` exists only when another match would exceed `limit`. A search
+that reaches the end with warnings therefore has `complete: false` **without** `next`. Callers
+should follow `next` when present and separately inspect warnings. A capped search can return
+both. The existing `query`, `count`, `matches` and rectangle semantics are unchanged.
+
+`text_extract`, comment placement and redaction keep strict all-requested-pages-must-succeed
+semantics; they never silently act on partial text.
+
 ## Shared field properties
 
 `form_set_props` accepts either `field` (one name) or `fields` (1–1000 unique names):
@@ -85,6 +114,15 @@ moves 1–1000 references atomically in displayed points (right/down), preservin
 and fonts. A refusal changes nothing; success is one undo step. See
 [the selection and movement guide](../../docs/editing-multiple-objects.md) for limits and examples.
 
+## Accessibility review record
+
+Open the original and edited PDFs as separate documents, then call
+`accessibility_review_record {before, after, path}`. The tool writes a JSON record atomically within
+`--root`: SHA-256 hashes of both working PDFs, rule statuses and finding counts before and after,
+changed rules, and rules still failed or requiring manual review. `all: true` also includes the
+colour-contrast rule. It does not change either PDF or certify accessibility. Keep the original open
+while making edits to the second document so the comparison has a stable baseline.
+
 ## Common command tools
 
 Following FilmCraft's MCP conventions, `command_list {doc?, filter?, enabled_only?}` keeps its
@@ -109,3 +147,40 @@ Exports complete synchronously. `progressToken` and cancellation notifications a
 ignored; no background-job or cancellation behavior is added.
 
 Session resources `pdfcraft://document` and `pdfcraft://commands`, and the refusal of unknown argument keys, are described in [docs/mcp.md](../../docs/mcp.md).
+
+For inline editor previews, `page_render` accepts `hide_text_block` (a 1-based index from
+`text_paragraphs`). It renders the page without that paragraph’s source glyphs and leaves the
+working document unchanged.
+
+
+## Existing text and document fonts
+
+`text_font_files` discovers eligible installed files on request (or specified confined folders),
+`text_font_import` registers a full document face, and `text_fonts` lists source/full resources.
+Use `text_edit.font_resource` to choose a resource, or keep source faces and let matching full
+faces complete absent subset glyphs. `text_edit.ranges` accepts disjoint UTF-8 byte ranges;
+`text_edit_layout` measures the same resource/range draft without committing. All changes are
+undoable and survive saving/reopening. `image_hit` shares the UI's curve and hole hit testing.
+The bounds, limits and font requirements are in [existing-text editing](../../docs/editing-existing-text.md)
+and [image editing](../../docs/editing-images.md).
+
+## Opening local GoToR links
+
+`link_open {doc, page, index, password?}` follows a local PDF link using `link_list`
+numbering. Relative file specifications open normally. An **absolute** file specification
+requires `allow_absolute: true`, after reviewing the target reported by `link_list`.
+Omitting the argument or passing false refuses the request before checking or reading the
+target file. This is an intentional compatibility change for callers that previously opened
+absolute GoToR targets without explicit consent. Opting in does not bypass `--root`, symlink
+confinement, regular-file, PDF-extension, size, or password validation. Consent applies only
+to that call, including each password retry; it is never remembered for other links.
+
+The desktop UI asks Allow/Cancel before following absolute GoToR targets and displays the
+complete path. Relative links retain their existing behavior. Named destinations remain
+unapplied with a warning.
+
+## Folder batches
+
+`doc_batch` runs conversion, OCR and compression over files and optionally recursive
+folders. The CLI also exposes it as `pdfcraft-cli batch`. See the
+[batch guide](../../docs/cli-batch.md) for examples, output protection, errors and limits.

crates/automation/src/a11y.rs

@@ -1,7 +1,10 @@
 //! Accessibility tools: the full check, the accessibility report, and the automatic fixes.
 
+use pdfcraft_engine::DocId;
 use pdfcraft_engine::a11y::{Category, Options, Report, Rule, Status};
 use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+use std::collections::BTreeSet;
 
 use crate::{Args, Automation, Result, ToolError, child, failed, unused, write_atomic};
 
@@ -31,7 +34,19 @@ pub(crate) fn report_json(r: &Report) -> Value {
         .results
         .iter()
         .map(|x| {
-            let findings: Vec<Value> = x.findings.iter().map(|f| json!({ "page": f.page.map(|p| p + 1), "message": f.message })).collect();
+            let findings: Vec<Value> = x
+                .findings
+                .iter()
+                .map(|f| {
+                    json!({
+                        "page": f.page.map(|p| p + 1),
+                        "object": f.object.map(|r| r.num),
+                        "object_generation": f.object.map(|r| r.generation),
+                        "bbox_user_space": f.bbox,
+                        "message": f.message,
+                    })
+                })
+                .collect();
             json!({ "rule": x.rule.id(), "name": x.rule.name(), "category": category_id(x.rule.category()), "status": status_id(x.status), "findings": findings })
         })
         .collect();
@@ -44,7 +59,183 @@ pub(crate) fn report_json(r: &Report) -> Value {
     })
 }
 
+fn review_hash(bytes: &[u8]) -> String {
+    Sha256::digest(bytes).iter().map(|b| format!("{b:02x}")).collect()
+}
+
+fn review_decisions(value: &Value, pages: usize) -> Result<Vec<Value>> {
+    let rows = value.as_array().ok_or_else(|| ToolError::InvalidArgs("decisions must be an array".into()))?;
+    let mut seen = BTreeSet::new();
+    rows.iter()
+        .map(|row| {
+            let fields = row.as_object().ok_or_else(|| ToolError::InvalidArgs("each decision must be an object".into()))?;
+            if fields.keys().any(|key| !matches!(key.as_str(), "rule" | "decision" | "page" | "note")) {
+                return Err(ToolError::InvalidArgs("unknown decision property".into()));
+            }
+            let rule = row["rule"].as_str().and_then(Rule::from_id).ok_or_else(|| ToolError::InvalidArgs("decision has an unknown rule".into()))?;
+            let decision = row["decision"].as_str().ok_or_else(|| ToolError::InvalidArgs("decision status is required".into()))?;
+            if !matches!(decision, "accepted" | "needs_work" | "skipped") {
+                return Err(ToolError::InvalidArgs("decision must be accepted, needs_work or skipped".into()));
+            }
+            let page = match row.get("page").filter(|value| !value.is_null()) {
+                Some(value) => {
+                    let page = value.as_u64().ok_or_else(|| ToolError::InvalidArgs("decision page must be positive".into()))?;
+                    if page == 0 || page > pages as u64 {
+                        return Err(ToolError::InvalidArgs("decision page is outside the document".into()));
+                    }
+                    Some(page)
+                }
+                None => None,
+            };
+            let note = match row.get("note").filter(|value| !value.is_null()) {
+                Some(value) => {
+                    let note = value.as_str().ok_or_else(|| ToolError::InvalidArgs("decision note must be text".into()))?;
+                    if note.len() > 4096 {
+                        return Err(ToolError::InvalidArgs("decision note exceeds 4096 bytes".into()));
+                    }
+                    Some(note)
+                }
+                None => None,
+            };
+            if !seen.insert((rule.id(), page)) {
+                return Err(ToolError::InvalidArgs("duplicate decision for a rule and page".into()));
+            }
+            Ok(json!({ "rule": rule.id(), "decision": decision, "page": page, "note": note }))
+        })
+        .collect()
+}
+
+/// A review sidecar is a few KiB of JSON; anything larger is not one.
+const MAX_REVIEW_SIDECAR_BYTES: u64 = 1 << 20;
+
+/// Read a review sidecar without trusting its size: the path is the caller's
+/// and may name any file, so the read stops past `MAX_REVIEW_SIDECAR_BYTES` and
+/// an oversized file is refused as not being a sidecar.
+fn read_review_sidecar(path: &std::path::Path) -> Result<Vec<u8>> {
+    use std::io::Read;
+    let mut bytes = Vec::new();
+    std::fs::File::open(path).and_then(|file| file.take(MAX_REVIEW_SIDECAR_BYTES.saturating_add(1)).read_to_end(&mut bytes)).map_err(failed)?;
+    if bytes.len() as u64 > MAX_REVIEW_SIDECAR_BYTES {
+        return Err(failed("file is not an accessibility review sidecar"));
+    }
+    Ok(bytes)
+}
+
+fn parse_review_sidecar(bytes: &[u8]) -> Result<Value> {
+    let value: Value = serde_json::from_slice(bytes).map_err(|_| failed("file is not an accessibility review sidecar"))?;
+    let hash = value["sha256"].as_str().ok_or_else(|| failed("review sidecar has no document hash"))?;
+    let Some(pages) = value["pages"].as_u64().and_then(|n| usize::try_from(n).ok()).filter(|n| *n > 0) else {
+        return Err(failed("unsupported or invalid accessibility review sidecar"));
+    };
+    if value["schema"] != 1 || hash.len() != 64 || !hash.bytes().all(|b| b.is_ascii_hexdigit()) {
+        return Err(failed("unsupported or invalid accessibility review sidecar"));
+    }
+    review_decisions(&value["decisions"], pages).map_err(failed)?;
+    Ok(value)
+}
+
+fn html_escape(value: &str) -> String {
+    value.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;").replace('\'', "&#39;")
+}
+
+/// A self-contained, human-readable view of the same evidence as the JSON review record.
+fn review_html(record: &Value) -> Result<String> {
+    let str_at = |value: &Value, key: &str| -> Result<String> {
+        value.get(key).and_then(Value::as_str).map(html_escape).ok_or_else(|| failed(format!("review record is missing {key}")))
+    };
+    let count = |value: &Value, key: &str| -> Result<u64> {
+        value.get(key).and_then(Value::as_u64).ok_or_else(|| failed(format!("review record is missing {key}")))
+    };
+    let before = &record["before"];
+    let after = &record["after"];
+    let mut html = format!(
+        "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><title>Accessibility review</title><style>\
+         body{{font:15px/1.5 system-ui,sans-serif;max-width:1100px;margin:2rem auto;padding:0 1rem;color:#1d1d1f}}\
+         table{{border-collapse:collapse;width:100%;margin:1rem 0}}th,td{{border:1px solid #aaa;padding:.45rem;text-align:left;vertical-align:top}}\
+         th{{background:#f2f2f2}}.hash{{overflow-wrap:anywhere;font-family:monospace}}\
+         </style></head><body><main><h1>Accessibility review</h1><p>Record created: {}</p>\n",
+        str_at(record, "date")?
+    );
+    html.push_str("<h2>Before and after</h2><table><caption>Accessibility checker outcomes</caption><thead><tr><th scope=\"col\">Version</th><th scope=\"col\">Document</th><th scope=\"col\">Passed</th><th scope=\"col\">Failed</th><th scope=\"col\">Needs manual check</th><th scope=\"col\">Skipped</th></tr></thead><tbody>");
+    for (label, version) in [("Before", before), ("After", after)] {
+        let summary = &version["summary"];
+        html.push_str(&format!(
+            "<tr><th scope=\"row\">{label}</th><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td></tr>",
+            str_at(version, "name")?,
+            count(summary, "passed")?,
+            count(summary, "failed")?,
+            count(summary, "manual")?,
+            count(summary, "skipped")?
+        ));
+    }
+    html.push_str("</tbody></table>");
+    html.push_str(&format!(
+        "<p>Before SHA-256: <span class=\"hash\">{}</span><br>After SHA-256: <span class=\"hash\">{}</span></p>",
+        str_at(before, "sha256")?,
+        str_at(after, "sha256")?
+    ));
+    html.push_str("<h2>Rule comparison</h2><table><caption>Before and after checker results</caption><thead><tr><th scope=\"col\">Rule</th><th scope=\"col\">Before</th><th scope=\"col\">Before findings</th><th scope=\"col\">After</th><th scope=\"col\">After findings</th><th scope=\"col\">Change</th></tr></thead><tbody>");
+    let rules = record["rules"].as_array().ok_or_else(|| failed("review record is missing rules"))?;
+    for row in rules {
+        let id = row["rule"].as_str().ok_or_else(|| failed("review record has a rule without an id"))?;
+        let name = Rule::from_id(id).map(Rule::name).unwrap_or(id);
+        let old = &row["before"];
+        let new = &row["after"];
+        let old_status = str_at(old, "status")?;
+        let new_status = str_at(new, "status")?;
+        let old_findings = count(old, "findings")?;
+        let new_findings = count(new, "findings")?;
+        let changed = old_status != new_status || old_findings != new_findings;
+        html.push_str(&format!(
+            "<tr><th scope=\"row\">{}</th><td>{old_status}</td><td>{old_findings}</td><td>{new_status}</td><td>{new_findings}</td><td>{}</td></tr>",
+            html_escape(name),
+            if changed { "Changed" } else { "Unchanged" }
+        ));
+    }
+    html.push_str("</tbody></table><h2>Still requiring review</h2><ul>");
+    for id in record["review_required"].as_array().ok_or_else(|| failed("review record is missing review_required"))? {
+        let id = id.as_str().ok_or_else(|| failed("review record has an invalid review_required entry"))?;
+        html.push_str(&format!("<li>{}</li>", html_escape(Rule::from_id(id).map(Rule::name).unwrap_or(id))));
+    }
+    html.push_str("</ul>");
+    html.push_str(&format!("<p>{}</p></main></body></html>\n", str_at(record, "note")?));
+    Ok(html)
+}
+
 impl Automation {
+    pub(crate) fn accessibility_autotag_apply(&mut self, a: &Args) -> Result<Value> {
+        let id = self.doc(a)?.id;
+        self.session.apply(id, pdfcraft_engine::Edit::AutoTagText).map_err(failed)?;
+        let tags = self.accessibility_tags(a)?;
+        Ok(json!({
+            "tags": tags["tags"], "count": tags["count"],
+            "note": "Text objects were tagged as paragraphs. Review heading roles, reading order and remaining accessibility findings manually.",
+        }))
+    }
+
+    pub(crate) fn accessibility_autotag_preview(&self, a: &Args) -> Result<Value> {
+        let page = self.page(a)?;
+        let preview = self.doc(a)?.autotag_preview(page).map_err(failed)?;
+        let candidates: Vec<Value> = preview
+            .candidates
+            .into_iter()
+            .map(|c| {
+                json!({
+                    "type": c.kind, "reason": c.reason, "text": c.text,
+                    "text_truncated": c.text_truncated, "bbox_user_space": c.rect,
+                    "font_size": c.size, "bold": c.bold, "needs_review": true,
+                })
+            })
+            .collect();
+        Ok(json!({
+            "page": page + 1, "candidates": candidates,
+            "unclassified_images": preview.unclassified_images,
+            "unclassified_text_blocks": preview.unclassified_text_blocks,
+            "existing_structure": preview.existing_structure,
+            "note": "Text roles are proposals only. Review images, tables, lists, annotations and existing tags before applying structure.",
+        }))
+    }
+
     fn a11y_options(&self, a: &Args) -> Result<Options> {
         let mut o = Options::default();
         if a.opt_bool("all")?.unwrap_or(false) {
@@ -93,6 +284,120 @@ impl Automation {
         Ok(out)
     }
 
+    fn review_record_value(&self, a: &Args) -> Result<Value> {
+        let id = |key| -> Result<DocId> {
+            let n = u64::try_from(a.int(key)?).map_err(|_| ToolError::InvalidArgs(format!("{key} must be positive")))?;
+            if n == 0 {
+                return Err(ToolError::InvalidArgs(format!("{key} must be positive")));
+            }
+            Ok(DocId(n))
+        };
+        let before_id = id("before")?;
+        let after_id = id("after")?;
+        if before_id == after_id {
+            return Err(ToolError::InvalidArgs("before and after must be separate open documents".into()));
+        }
+        let before = self.session.get(before_id).ok_or_else(|| failed(format!("no open document with id {}", before_id.0)))?;
+        let after = self.session.get(after_id).ok_or_else(|| failed(format!("no open document with id {}", after_id.0)))?;
+        let mut options = Options::default();
+        if a.opt_bool("all")?.unwrap_or(false) {
+            options.rules = Rule::ALL.into_iter().collect();
+        }
+        let before_report = before.accessibility_check(&options).ok_or_else(|| failed("the original document can't be read for checking"))?;
+        let after_report = after.accessibility_check(&options).ok_or_else(|| failed("the edited document can't be read for checking"))?;
+        if before_report.results.len() != after_report.results.len() {
+            return Err(failed("the two accessibility checks returned different rule sets"));
+        }
+        let mut rules = Vec::new();
+        let mut changed = Vec::new();
+        let mut review_required = Vec::new();
+        for (prior, current) in before_report.results.iter().zip(&after_report.results) {
+            if prior.rule != current.rule {
+                return Err(failed("the two accessibility checks returned different rule sets"));
+            }
+            let rule = prior.rule.id();
+            let before_status = status_id(prior.status);
+            let after_status = status_id(current.status);
+            let before_findings = prior.findings.len();
+            let after_findings = current.findings.len();
+            if before_status != after_status || before_findings != after_findings {
+                changed.push(rule);
+            }
+            if matches!(current.status, Status::Failed | Status::Manual) {
+                review_required.push(rule);
+            }
+            rules.push(json!({
+                "rule": rule,
+                "before": { "status": before_status, "findings": before_findings },
+                "after": { "status": after_status, "findings": after_findings },
+            }));
+        }
+        let (y, m, d) = self.session.today();
+        let hash = |bytes: &[u8]| Sha256::digest(bytes).iter().map(|b| format!("{b:02x}")).collect::<String>();
+        let record = json!({
+            "schema": 1,
+            "date": format!("{y}-{m:02}-{d:02}"),
+            "before": { "name": before.name, "sha256": hash(before.bytes.as_slice()), "summary": {
+                "passed": before_report.count(Status::Passed), "failed": before_report.count(Status::Failed),
+                "manual": before_report.count(Status::Manual), "skipped": before_report.count(Status::Skipped),
+            } },
+            "after": { "name": after.name, "sha256": hash(after.bytes.as_slice()), "summary": {
+                "passed": after_report.count(Status::Passed), "failed": after_report.count(Status::Failed),
+                "manual": after_report.count(Status::Manual), "skipped": after_report.count(Status::Skipped),
+            } },
+            "rules": rules,
+            "changed": changed,
+            "review_required": review_required,
+            "note": "Automated checks cover only part of accessibility. Review remaining findings manually and validate the final PDF independently.",
+        });
+        Ok(record)
+    }
+
+    pub(crate) fn a11y_review_record(&self, a: &Args) -> Result<Value> {
+        let record = self.review_record_value(a)?;
+        let path = self.resolve(a.str("path")?, true)?;
+        let bytes = serde_json::to_vec_pretty(&record).map_err(failed)?;
+        write_atomic(&path, &bytes)?;
+        Ok(json!({ "path": path.to_string_lossy(), "record": record }))
+    }
+
+    pub(crate) fn a11y_review_save(&self, a: &Args) -> Result<Value> {
+        let doc = self.doc(a)?;
+        let decisions = review_decisions(a.get("decisions").ok_or_else(|| Args::missing("decisions"))?, doc.info.pages.len())?;
+        let hash = review_hash(doc.bytes.as_slice());
+        let path = self.resolve(a.str("path")?, true)?;
+        if path.exists() {
+            let prior = read_review_sidecar(&path)?;
+            let prior = parse_review_sidecar(&prior)?;
+            if prior["sha256"] != hash && !a.opt_bool("replace")?.unwrap_or(false) {
+                return Err(failed("review sidecar belongs to a different PDF revision; pass replace: true to replace it"));
+            }
+        }
+        let (y, m, d) = self.session.today();
+        let sidecar =
+            json!({ "schema": 1, "date": format!("{y}-{m:02}-{d:02}"), "sha256": hash, "pages": doc.info.pages.len(), "decisions": decisions });
+        write_atomic(&path, &serde_json::to_vec_pretty(&sidecar).map_err(failed)?)?;
+        Ok(json!({ "path": path.to_string_lossy(), "review": sidecar }))
+    }
+
+    pub(crate) fn a11y_review_load(&self, a: &Args) -> Result<Value> {
+        let doc = self.doc(a)?;
+        let path = self.resolve(a.str("path")?, false)?;
+        let review = parse_review_sidecar(&read_review_sidecar(&path)?)?;
+        if review["sha256"] != review_hash(doc.bytes.as_slice()) {
+            return Err(failed("review sidecar belongs to a different PDF revision"));
+        }
+        Ok(json!({ "path": path.to_string_lossy(), "review": review }))
+    }
+
+    pub(crate) fn a11y_review_html(&self, a: &Args) -> Result<Value> {
+        let record = self.review_record_value(a)?;
+        let html = review_html(&record)?;
+        let path = self.resolve(a.str("path")?, true)?;
+        write_atomic(&path, html.as_bytes())?;
+        Ok(json!({ "path": path.to_string_lossy(), "record": record }))
+    }
+
     pub(crate) fn a11y_fix(&mut self, a: &Args) -> Result<Value> {
         let id = a.str("rule")?;
         let rule = Rule::from_id(id).ok_or_else(|| ToolError::InvalidArgs(format!("unknown rule {id:?}")))?;
@@ -135,10 +440,67 @@ impl Automation {
         self.session.apply(id, edit).map_err(failed)?;
         self.accessibility_figures(a)
     }
+
+    pub(crate) fn accessibility_tags(&self, a: &Args) -> Result<Value> {
+        let tags: Vec<Value> = self
+            .doc(a)?
+            .tags()
+            .into_iter()
+            .map(|t| {
+                json!({
+                    "object": t.object.num, "generation": t.object.generation, "type": t.kind,
+                    "parent": t.parent.map(|p| json!({ "object": p.num, "generation": p.generation })), "depth": t.depth,
+                    "title": t.title, "actual_text": t.actual_text, "alternate_text": t.alt,
+                    "language": t.language, "page": t.page.map(|p| p + 1),
+                })
+            })
+            .collect();
+        Ok(json!({ "count": tags.len(), "tags": tags }))
+    }
+
+    pub(crate) fn accessibility_set_tag_property(&mut self, a: &Args) -> Result<Value> {
+        let object = u32::try_from(a.int("object")?).map_err(|_| ToolError::InvalidArgs("object must be a positive tag object number".into()))?;
+        if object == 0 {
+            return Err(ToolError::InvalidArgs("object must be a positive tag object number".into()));
+        }
+        let generation = u16::try_from(a.int("generation")?)
+            .map_err(|_| ToolError::InvalidArgs("generation must be a PDF object generation from accessibility_tags".into()))?;
+        let property_id = a.str("property")?;
+        let property = pdfcraft_engine::a11y::TagProperty::from_id(property_id)
+            .ok_or_else(|| ToolError::InvalidArgs(format!("unknown tag property {property_id:?}")))?;
+        let value = a.opt_str("value")?.map(str::to_owned);
+        let id = self.doc(a)?.id;
+        self.session
+            .apply(id, pdfcraft_engine::Edit::SetTagProperty { object: pdfcraft_cos::ObjRef::new(object, generation), property, value })
+            .map_err(failed)?;
+        self.accessibility_tags(a)
+    }
+
+    pub(crate) fn accessibility_move_tag(&mut self, a: &Args) -> Result<Value> {
+        let reference = |number: &str, generation: &str| -> Result<pdfcraft_cos::ObjRef> {
+            let n = u32::try_from(a.int(number)?).map_err(|_| ToolError::InvalidArgs(format!("{number} must be a positive tag object number")))?;
+            if n == 0 {
+                return Err(ToolError::InvalidArgs(format!("{number} must be a positive tag object number")));
+            }
+            let g = u16::try_from(a.int(generation)?)
+                .map_err(|_| ToolError::InvalidArgs(format!("{generation} must be a PDF object generation from accessibility_tags")))?;
+            Ok(pdfcraft_cos::ObjRef::new(n, g))
+        };
+        let object = reference("object", "generation")?;
+        let anchor = reference("anchor", "anchor_generation")?;
+        let placement = match a.str("placement")? {
+            "before" => pdfcraft_engine::a11y::TagPlacement::Before,
+            "after" => pdfcraft_engine::a11y::TagPlacement::After,
+            other => return Err(ToolError::InvalidArgs(format!("placement must be before or after, not {other:?}"))),
+        };
+        let id = self.doc(a)?.id;
+        self.session.apply(id, pdfcraft_engine::Edit::MoveTag { object, anchor, placement }).map_err(failed)?;
+        self.accessibility_tags(a)
+    }
 }
 
 impl Automation {
-    fn ocr_settings(&self, a: &Args) -> Result<pdfcraft_engine::ocr::OcrSettings> {
+    pub(crate) fn ocr_settings(&self, a: &Args) -> Result<pdfcraft_engine::ocr::OcrSettings> {
         let mut settings = pdfcraft_engine::ocr::OcrSettings::default();
         if let Some(d) = a.opt_num("dpi")? {
             settings.dpi = d.clamp(72.0, 600.0) as f32;
@@ -195,7 +557,7 @@ impl Automation {
             .iter()
             .map(|p| match &p.skipped {
                 Some(why) => json!({ "page": p.page + 1, "skipped": why }),
-                None => json!({ "page": p.page + 1, "words": p.words.len(), "text": p.text() }),
+                None => json!({ "page": p.page + 1, "words": p.words.len(), "already_on_page": p.already_on_page, "text": p.text() }),
             })
             .collect();
         Ok(json!({ "words": found.iter().map(|p| p.words.len()).sum::<usize>(), "pages": list }))
@@ -272,7 +634,7 @@ impl Automation {
         let path = self.resolve(a.str("path")?, true)?;
         let ext = path.extension().map(|e| e.to_string_lossy().into_owned()).unwrap_or_default();
         let format = pdfcraft_engine::compare::OfficeFormat::from_extension(&ext)
-            .ok_or_else(|| ToolError::InvalidArgs(format!("unsupported extension {ext:?} (docx, html or rtf)")))?;
+            .ok_or_else(|| ToolError::InvalidArgs(format!("unsupported extension {ext:?} (docx, pptx, html or rtf)")))?;
         let bytes = self.doc_to_copy(a)?.export_office(format);
         write_atomic(&path, &bytes)?;
         Ok(json!({ "path": path.to_string_lossy(), "bytes": bytes.len(), "format": format.extension() }))
@@ -300,6 +662,56 @@ impl Automation {
         }))
     }
 
+    pub(crate) fn print_readiness(&self, a: &Args) -> Result<Value> {
+        let report = self.doc(a)?.print_readiness();
+        let findings: Vec<Value> =
+            report.findings.iter().map(|f| json!({ "id": f.id, "severity": f.severity, "message": f.message, "page": f.page })).collect();
+        let pages: Vec<Value> = report
+            .pages
+            .iter()
+            .map(|p| {
+                json!({
+                    "page": p.page,
+                    "media_mm": p.media_mm,
+                    "crop_mm": p.crop_mm,
+                    "trim_mm": p.trim_mm,
+                    "bleed_mm": p.bleed_mm,
+                    "trim_set": p.trim_set,
+                    "bleed_set": p.bleed_set,
+                    "bleed_margin_mm": p.bleed_margin_mm,
+                })
+            })
+            .collect();
+        let images: Vec<Value> = report
+            .images
+            .iter()
+            .map(|image| {
+                json!({
+                    "page": image.page,
+                    "name": image.name,
+                    "ppi": image.ppi,
+                    "pixels": image.pixels,
+                    "size_mm": image.size_mm,
+                })
+            })
+            .collect();
+        let pdfa: Vec<Value> = report
+            .pdfa_issues
+            .iter()
+            .map(|issue| json!({ "clause": issue.clause, "message": issue.message, "page": issue.page.map(|p| p + 1) }))
+            .collect();
+        Ok(json!({
+            "text": report.text(),
+            "findings": findings,
+            "pages": pages,
+            "images": images,
+            "output_intents": report.output_intents,
+            "fonts_not_embedded": report.fonts_not_embedded,
+            "pdfa_issues": pdfa,
+            "resolution_unknown": report.resolution_unknown,
+        }))
+    }
+
     pub(crate) fn pdfa_convert(&mut self, a: &Args) -> Result<Value> {
         let level = self.pdfa_level(a)?;
         let id = self.doc(a)?.id;
@@ -516,3 +928,23 @@ impl Automation {
         Ok(json!({ "enabled": self.session.javascript() }))
     }
 }
+
+#[cfg(test)]
+mod review_html_tests {
+    use super::*;
+
+    #[test]
+    fn document_names_are_escaped_in_review_html() {
+        let record = json!({
+            "date": "2026-10-12",
+            "before": { "name": "<script>alert('x')</script>.pdf", "sha256": "a", "summary": { "passed": 0, "failed": 1, "manual": 0, "skipped": 0 } },
+            "after": { "name": "safe.pdf", "sha256": "b", "summary": { "passed": 1, "failed": 0, "manual": 0, "skipped": 0 } },
+            "rules": [{ "rule": "primary-language", "before": { "status": "failed", "findings": 1 }, "after": { "status": "passed", "findings": 0 } }],
+            "review_required": [],
+            "note": "Review independently.",
+        });
+        let html = review_html(&record).unwrap();
+        assert!(html.contains("&lt;script&gt;alert(&#39;x&#39;)&lt;/script&gt;.pdf"));
+        assert!(!html.contains("<script>"));
+    }
+}

crates/automation/src/batch.rs

@@ -0,0 +1,276 @@
+//! One-shot folder jobs shared by CLI and MCP. Discovery finishes before any output is made.
+
+use std::collections::{BTreeMap, HashSet};
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use pdfcraft_engine::{Session, ocr, optimize};
+use serde_json::{Value, json};
+
+use crate::{Args, Automation, Result, failed};
+
+const MAX_ENTRIES: usize = 10_000;
+const MAX_DEPTH: usize = 64;
+const MAX_INPUT: u64 = 512 * 1024 * 1024;
+
+struct Recipe<'a> {
+    steps: Vec<&'a str>,
+    images: optimize::ImageSettings,
+    ocr: ocr::OcrSettings,
+}
+
+impl<'a> Recipe<'a> {
+    fn parse(auto: &Automation, args: &'a Args) -> Result<Self> {
+        let steps = args.strs("steps")?;
+        if steps.is_empty() || steps.len() > 3 {
+            return Err(Args::wrong("steps", "one to three unique steps: convert, ocr, optimize"));
+        }
+        let mut seen = HashSet::new();
+        for (i, step) in steps.iter().enumerate() {
+            if !matches!(*step, "convert" | "ocr" | "optimize") || !seen.insert(*step) || (*step == "convert" && i != 0) {
+                return Err(Args::wrong("steps", "unique convert/ocr/optimize steps, with convert first when present"));
+            }
+        }
+        for (keys, step) in [(&["ppi", "quality"][..], "optimize"), (&["dpi", "language", "skip_text_pages"][..], "ocr")] {
+            if !steps.contains(&step) && keys.iter().any(|k| args.get(k).is_some()) {
+                return Err(failed(format!("{} settings need the {step} step", keys.join("/"))));
+            }
+        }
+        let mut images = optimize::ImageSettings::REDUCE;
+        if let Some(ppi) = args.opt_num("ppi")? {
+            if !(9.0..=1600.0).contains(&ppi) {
+                return Err(Args::wrong("ppi", "9 to 1600"));
+            }
+            images.target_ppi = ppi;
+            images.above_ppi = ppi * 1.5;
+        }
+        if let Some(q) = args.opt_int("quality")? {
+            if !(1..=100).contains(&q) {
+                return Err(Args::wrong("quality", "1 to 100"));
+            }
+            images.compression = optimize::Compression::Jpeg(q as u8);
+        }
+        if args.opt_num("dpi")?.is_some_and(|dpi| !(72.0..=600.0).contains(&dpi)) {
+            return Err(Args::wrong("dpi", "72 to 600"));
+        }
+        Ok(Self { steps, images, ocr: auto.ocr_settings(args)? })
+    }
+
+    fn accepts(&self, path: &Path) -> bool {
+        let extension = path.extension().and_then(|s| s.to_str()).unwrap_or("").to_ascii_lowercase();
+        extension == "pdf" || (self.steps.contains(&"convert") && pdfcraft_engine::CONVERTIBLE.contains(&extension.as_str()))
+    }
+
+    fn process(&self, path: &Path) -> Result<(Arc<Vec<u8>>, Vec<Value>)> {
+        // A fresh session per file bounds retained document state and never touches caller tabs.
+        let mut session = Session::new();
+        let mut input = Vec::new();
+        std::fs::File::open(path).map_err(failed)?.take(MAX_INPUT + 1).read_to_end(&mut input).map_err(failed)?;
+        if input.len() as u64 > MAX_INPUT {
+            return Err(failed("input exceeds 512 MiB"));
+        }
+        let name = path.file_name().and_then(|n| n.to_str()).ok_or_else(|| failed("input name is not UTF-8"))?;
+        let mut bytes = Arc::new(input);
+        let mut log = Vec::new();
+        for step in &self.steps {
+            let before = bytes.len();
+            match *step {
+                "convert" => bytes = session.convert_to_pdf(name, &bytes)?.1,
+                "ocr" => {
+                    let engine = ocr::engine().map_err(failed)?;
+                    let result = ocr::recognize_file(name, bytes, None, self.ocr.clone(), &engine, |_, _| true).map_err(failed)?;
+                    log.push(
+                        json!({"step":"ocr","words":result.words(),"skipped_pages":result.pages.iter().filter(|p| p.skipped.is_some()).count()}),
+                    );
+                    bytes = result.bytes;
+                    continue;
+                }
+                "optimize" => {
+                    let id = session.open(name, None, bytes.clone(), None).map_err(failed)?;
+                    let settings = optimize::Settings { color: self.images, gray: self.images, ..Default::default() };
+                    let (candidate, _) = session.optimized_bytes(id, &settings, &[])?;
+                    session.close(id);
+                    if candidate.len() < bytes.len() {
+                        bytes = candidate;
+                    }
+                }
+                _ => return Err(failed("unknown batch step")),
+            }
+            log.push(json!({"step":step,"bytes_before":before,"bytes_after":bytes.len()}));
+        }
+        Ok((bytes, log))
+    }
+}
+
+// Windows junctions are reparse points too; do not descend into them as ordinary folders.
+fn linked(metadata: &std::fs::Metadata) -> bool {
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        metadata.file_attributes() & 0x400 != 0
+    }
+    #[cfg(not(windows))]
+    {
+        metadata.file_type().is_symlink()
+    }
+}
+
+/// Canonicalize the existing ancestor, including when the requested output does not exist yet.
+fn absolute(path: &Path) -> Result<PathBuf> {
+    let mut ancestor = path;
+    let mut tail = Vec::new();
+    while !ancestor.exists() {
+        if ancestor.symlink_metadata().is_ok() {
+            return Err(failed("broken link in batch path"));
+        }
+        tail.push(ancestor.file_name().ok_or_else(|| failed("invalid batch path"))?);
+        ancestor = ancestor.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or(Path::new("."));
+    }
+    let mut path = ancestor.canonicalize().map_err(failed)?;
+    path.extend(tail.iter().rev());
+    crate::lexical(&path).ok_or_else(|| failed("invalid batch path"))
+}
+
+struct Discovery {
+    files: BTreeMap<PathBuf, PathBuf>,
+    skipped: Vec<Value>,
+    seen: HashSet<PathBuf>,
+    visited: usize,
+}
+
+impl Discovery {
+    fn walk(&mut self, path: &Path, relative: &Path, out: &Path, recursive: bool, depth: usize) -> Result<()> {
+        self.visited += 1;
+        if self.visited > MAX_ENTRIES || depth > MAX_DEPTH {
+            return Err(failed("batch discovery exceeds 10000 entries or 64 folder levels"));
+        }
+        if depth > 0 && path.starts_with(out) {
+            return Ok(());
+        }
+        let metadata = path.symlink_metadata().map_err(|e| failed(format!("{}: {e}", path.display())))?;
+        if linked(&metadata) || (!metadata.is_file() && !metadata.is_dir()) {
+            self.skipped.push(json!({"path":path.to_string_lossy(),"status":"skipped","reason":"link or special file"}));
+        } else if (metadata.is_file() || depth == 0 || recursive) && self.seen.insert(path.to_path_buf()) {
+            if metadata.is_file() {
+                self.files.insert(path.to_path_buf(), relative.to_path_buf());
+            } else if depth == 0 || recursive {
+                // Bound the list before sorting it; never collect an unbounded folder listing.
+                let mut entries = Vec::new();
+                for entry in std::fs::read_dir(path).map_err(failed)? {
+                    if entries.len() >= MAX_ENTRIES.saturating_sub(self.visited) {
+                        return Err(failed("batch discovery exceeds 10000 entries"));
+                    }
+                    entries.push(entry.map_err(failed)?.path());
+                }
+                entries.sort();
+                for child in entries {
+                    let name = child.file_name().ok_or_else(|| failed("entry has no name"))?;
+                    self.walk(&child, &relative.join(name), out, recursive, depth + 1)?;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+impl Automation {
+    pub(crate) fn doc_batch(&self, args: &Args) -> Result<Value> {
+        let recipe = Recipe::parse(self, args)?;
+        let recursive = args.opt_bool("recursive")?.unwrap_or(false);
+        let stop = args.opt_bool("stop_on_error")?.unwrap_or(false);
+        let paths = args.strs("paths")?;
+        if paths.is_empty() || paths.len() > 1000 {
+            return Err(Args::wrong("paths", "1 to 1000 files or folders"));
+        }
+        let out = absolute(&self.resolve(args.str("out_dir")?, true)?)?;
+        let mut roots = Vec::new();
+        for path in paths {
+            let resolved = self.resolve(path, false)?;
+            let original = self.root.as_ref().map_or_else(|| PathBuf::from(path), |root| root.join(path));
+            if linked(&original.symlink_metadata().map_err(failed)?) {
+                return Err(failed("input roots must be regular files or folders, not links"));
+            }
+            let real = absolute(&resolved)?;
+            if real.is_dir() && real.starts_with(&out) {
+                return Err(failed("out_dir must not contain an input folder or equal it"));
+            }
+            roots.push(real);
+        }
+        let mut discovery = Discovery { files: BTreeMap::new(), skipped: Vec::new(), seen: HashSet::new(), visited: 0 };
+        for root in roots {
+            let relative = if root.is_dir() { PathBuf::new() } else { PathBuf::from(root.file_name().ok_or_else(|| failed("input has no name"))?) };
+            discovery.walk(&root, &relative, &out, recursive, 0)?;
+        }
+        let mut files = discovery.skipped;
+        let (mut completed, mut failed_count) = (0, 0);
+        let mut stopped = false;
+        for (path, relative) in discovery.files {
+            if stopped || !recipe.accepts(&path) {
+                files.push(json!({"path":path.to_string_lossy(),"status":"skipped","reason":if stopped {"stopped after error"} else {"unsupported input extension"}}));
+                continue;
+            }
+            // Recheck confinement and links before reading a discovered file.
+            let result: Result<_> = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                let current = self.resolve(path.to_str().ok_or_else(|| failed("input path is not UTF-8"))?, false)?;
+                if linked(&path.symlink_metadata().map_err(failed)?) || absolute(&current)? != path {
+                    return Err(failed("input path changed after discovery"));
+                }
+                let (bytes, log) = recipe.process(&current)?;
+                let target = out.join(relative).with_extension("pdf");
+                let target = self.resolve(target.to_str().ok_or_else(|| failed("output path is not UTF-8"))?, true)?;
+                if !target.starts_with(&out) {
+                    return Err(failed("output path leaves out_dir"));
+                }
+                let output = publish(&target, &bytes)?;
+                Ok((output, bytes.len(), log))
+            }))
+            .unwrap_or_else(|_| Err(failed("batch conversion panicked; no output was published")));
+            match result {
+                Ok((output, bytes, steps)) => {
+                    completed += 1;
+                    files.push(json!({"path":path.to_string_lossy(),"status":"ok","output":output.to_string_lossy(),"bytes":bytes,"steps":steps}));
+                }
+                Err(e) => {
+                    failed_count += 1;
+                    files.push(json!({"path":path.to_string_lossy(),"status":"error","error":e.to_string()}));
+                    stopped = stop;
+                }
+            }
+        }
+        let skipped = files.len().saturating_sub(completed + failed_count);
+        Ok(json!({"completed":completed,"failed":failed_count,"skipped":skipped,"stopped":stopped,"files":files}))
+    }
+}
+
+/// Publish atomically without replacing any existing name, even if another writer wins a race.
+fn publish(target: &Path, bytes: &[u8]) -> Result<PathBuf> {
+    let dir = target.parent().ok_or_else(|| failed("output has no parent"))?;
+    std::fs::create_dir_all(dir).map_err(failed)?;
+    let mut temp = tempfile::NamedTempFile::new_in(dir).map_err(failed)?;
+    temp.write_all(bytes).map_err(failed)?;
+    temp.as_file().sync_all().map_err(failed)?;
+    let stem = target.file_stem().ok_or_else(|| failed("output has no stem"))?.to_string_lossy();
+    for n in 1..=10_000 {
+        let candidate = if n == 1 { target.to_path_buf() } else { dir.join(format!("{stem} ({n}).pdf")) };
+        match temp.persist_noclobber(&candidate) {
+            Ok(_) => return Ok(candidate),
+            Err(e) if e.error.kind() == std::io::ErrorKind::AlreadyExists || candidate.symlink_metadata().is_ok() => temp = e.file,
+            Err(e) => return Err(failed(e.error)),
+        }
+    }
+    Err(failed("all 10000 output names are occupied"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn discovery_limits_fail_before_reading_another_entry() {
+        let mut discovery = Discovery { files: BTreeMap::new(), skipped: Vec::new(), seen: HashSet::new(), visited: MAX_ENTRIES };
+        assert!(discovery.walk(Path::new("absent"), Path::new(""), Path::new("output"), true, 0).unwrap_err().to_string().contains("10000"));
+        discovery.visited = 0;
+        assert!(discovery.walk(Path::new("absent"), Path::new(""), Path::new("output"), true, MAX_DEPTH + 1).unwrap_err().to_string().contains("64"));
+    }
+}

crates/automation/src/comments.rs

@@ -469,17 +469,45 @@ impl Automation {
         let at = to_user(&info, x, y);
         let author = a.opt_str("author")?.unwrap_or(DEFAULT_AUTHOR).to_string();
         let kind = a.str("type")?;
+        let scan = a.opt_bool("scan")?.unwrap_or(false);
+        let sensitivity = a.opt_int("sensitivity")?;
+        if (scan || sensitivity.is_some()) && a.opt_str("path")?.is_none() {
+            return Err(ToolError::InvalidArgs("scan and sensitivity need path, a photo of a signature on paper".into()));
+        }
+        if sensitivity.is_some() && !scan {
+            return Err(ToolError::InvalidArgs("sensitivity is only for scan: true".into()));
+        }
+        let requested_size = a.opt_num("font_size")?;
+        if requested_size.is_some() && !matches!(kind, "text" | "date") {
+            return Err(ToolError::InvalidArgs("font_size is only for type text or date".into()));
+        }
+        let size = requested_size.unwrap_or(10.0);
+        if !(4.0..=300.0).contains(&size) {
+            return Err(ToolError::InvalidArgs("font_size must be 4–300 pt".into()));
+        }
         if let Some(path) = a.opt_str("path")? {
             if !matches!(kind, "signature" | "initials") || a.opt_str("text")?.is_some() {
                 return Err(ToolError::InvalidArgs("path is only for an image signature or initials; pass either path or text".into()));
             }
             let path = self.resolve(path, false)?;
             let file = std::fs::File::open(&path).map_err(|e| failed(format!("{}: {e}", path.display())))?;
-            let image = pdfcraft_engine::SignatureImage::read(file).map_err(|e| ToolError::InvalidArgs(e.to_string()))?;
+            let image = if scan {
+                let sensitivity = match sensitivity {
+                    None => pdfcraft_engine::signature_scan::DEFAULT_SENSITIVITY,
+                    Some(s) => u8::try_from(s)
+                        .ok()
+                        .filter(|s| *s <= 100)
+                        .ok_or_else(|| ToolError::InvalidArgs(format!("sensitivity must be 0–100, got {s}")))?,
+                };
+                let mut photo = pdfcraft_engine::SignaturePhoto::read(file).map_err(|e| ToolError::InvalidArgs(e.to_string()))?;
+                let frame = photo.auto_frame();
+                photo.scan(frame, sensitivity, pdfcraft_engine::signature_scan::SCAN_MAX_SIDE).map_err(|e| ToolError::InvalidArgs(e.to_string()))?
+            } else {
+                pdfcraft_engine::SignatureImage::read(file).map_err(|e| ToolError::InvalidArgs(e.to_string()))?
+            };
             let edit = image.edit(page, &info, at, kind == "initials", &author).ok_or_else(|| ToolError::InvalidArgs("at must be finite".into()))?;
             return self.apply(a, edit);
         }
-        let size = 10.0;
         let text_at = |t: &str| {
             let w = (pdfcraft_engine::annot_text::text_width(t, size) + 8.0).clamp(20.0, 600.0);
             let h = size * 1.2 + 6.0;
@@ -501,6 +529,14 @@ impl Automation {
             // A typed signature or initials in the script font, left edge at `at`, upright as displayed.
             kind @ ("signature" | "initials") => {
                 let t = a.str("text")?;
+                // Nobody sees a preview here: refuse what the script font would leave out.
+                if let Some(c) = pdfcraft_engine::script_missing(t) {
+                    return Err(ToolError::InvalidArgs(format!(
+                        "the signature script font can't draw \"{}\" (U+{:04X}); type the {kind} in Latin, Cyrillic or Greek letters, or pass `path` to a PNG or JPEG image of it instead of `text`",
+                        c.escape_debug(),
+                        u32::from(c)
+                    )));
+                }
                 let h = if kind == "initials" { 24.0 } else { 32.0 };
                 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()))?;

crates/automation/src/content.rs

@@ -164,6 +164,9 @@ impl Automation {
                 if a.get("text").is_some() {
                     return Err(bad("images have no text"));
                 }
+                if ["font", "size", "bold", "italic", "color", "align"].iter().any(|k| a.get(k).is_some()) {
+                    return Err(bad("font, size, bold, italic, color and align apply to text"));
+                }
                 if let Some(deg) = a.opt_int("rotate")? {
                     if deg.rem_euclid(90) != 0 {
                         return Err(bad("rotate must be a multiple of 90"));

crates/automation/src/conventions.rs

@@ -114,7 +114,7 @@ impl Automation {
             return Err(failed("page has invalid dimensions"));
         }
         let scale = (max as f32 / side).min(1.0);
-        let out = self.renderer(id)?.render(RenderRequest { page, kind: RequestKind::Pixels, tile: None, scale, tag: 0 });
+        let out = self.renderer(id)?.render(RenderRequest { page, kind: RequestKind::Pixels, tile: None, scale, tag: 0, preview: false });
         if let Some(error) = out.error {
             return Err(failed(error));
         }

crates/automation/src/forms.rs

@@ -520,7 +520,8 @@ impl Automation {
         let id = self.doc(a)?.id;
         let path = self.resolve(a.str("path")?, true)?;
         let ext = path.extension().map(|e| e.to_string_lossy().into_owned()).unwrap_or_default();
-        let format = pdfcraft_engine::DataFormat::from_extension(&ext).ok_or_else(|| bad("the path must end in .xfdf, .fdf, .xml, .csv or .txt"))?;
+        let format =
+            pdfcraft_engine::DataFormat::from_extension(&ext).ok_or_else(|| bad("the path must end in .xfdf, .fdf, .xml, .xdp, .csv or .txt"))?;
         let (comments, fields) = match a.opt_str("what")?.unwrap_or("all") {
             "all" => (true, true),
             "comments" => (true, false),

crates/automation/src/lib.rs

@@ -12,6 +12,7 @@
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
 mod a11y;
+mod batch;
 mod comments;
 mod content;
 mod conventions;
@@ -21,8 +22,10 @@ mod links;
 pub mod mcp;
 mod measure;
 mod printing;
+mod reading;
 mod redact;
 mod signing;
+mod text_cache;
 mod tools;
 
 use std::collections::HashMap;
@@ -94,8 +97,11 @@ const MAX_BOOKMARK_PAGE: usize = 1000;
 const FIND_FIRST_BATCH: usize = 8;
 const FIND_MAX_BATCH: usize = 128;
 
-/// Page texts of one document version: (the working bytes, one slot per page).
-type TextCache = (Arc<Vec<u8>>, Vec<Option<Arc<PageText>>>);
+use text_cache::TextCache;
+
+type PageTexts = Vec<(usize, std::result::Result<Arc<PageText>, String>)>;
+const FIND_MAX_WARNINGS: usize = 100;
+const FIND_MAX_WARNING_BYTES: usize = 1024;
 
 /// A headless PdfCraft session driven by tool calls.
 pub struct Automation {
@@ -103,8 +109,8 @@ pub struct Automation {
     root: Option<PathBuf>,
     /// Synchronous renderers, rebuilt when a document's working bytes change.
     renderers: HashMap<DocId, (Arc<Vec<u8>>, PageRenderer)>,
-    /// Extracted page text per document version (the working bytes it was taken from).
-    texts: HashMap<DocId, TextCache>,
+    /// Extracted page text, under one memory budget across all open documents.
+    texts: TextCache,
 }
 
 impl Default for Automation {
@@ -115,7 +121,7 @@ impl Default for Automation {
 
 impl Automation {
     pub fn new() -> Self {
-        Self { session: Session::new(), root: None, renderers: HashMap::new(), texts: HashMap::new() }
+        Self { session: Session::new(), root: None, renderers: HashMap::new(), texts: TextCache::default() }
     }
 
     /// Confine every path the tools read or write to `root` (relative paths resolve inside it).
@@ -164,8 +170,13 @@ impl Automation {
         let a = Args(args);
         let out = match name {
             "doc_open" => self.doc_open(&a)?,
+            "doc_batch" => self.doc_batch(&a)?,
             "doc_list" => json!({ "documents": self.session.docs().iter().map(summary).collect::<Vec<_>>() }),
-            "doc_info" => info(self.doc(&a)?),
+            "doc_info" => {
+                let id = self.doc(&a)?.id;
+                self.session.refresh_fonts(id);
+                info(self.doc(&a)?)
+            }
             "doc_close" => self.doc_close(&a)?,
             "doc_save" => self.doc_save(&a)?,
             "doc_set_info" => {
@@ -386,6 +397,21 @@ impl Automation {
                     .collect();
                 json!({ "page": page + 1, "count": lines.len(), "lines": lines })
             }
+            "image_hit" => {
+                let page = self.page(&a)?;
+                let point = a
+                    .get("point")
+                    .and_then(Value::as_array)
+                    .filter(|p| p.len() == 2)
+                    .and_then(|p| Some([p.first()?.as_f64()?, p.get(1)?.as_f64()?]))
+                    .filter(|p| p.iter().all(|v| v.is_finite() && v.abs() <= 1e9))
+                    .ok_or_else(|| ToolError::InvalidArgs("point must contain two finite coordinates".into()))?;
+                let doc = self.doc(&a)?;
+                let p = &doc.info.pages[page];
+                let user = p.view_to_user(point[0] as f32, point[1] as f32).map(f64::from);
+                let images: Vec<_> = doc.page_images(page).iter().enumerate().filter(|(_, im)| im.contains(user)).map(|(i, _)| i + 1).collect();
+                json!({"page":page+1,"images":images})
+            }
             "page_images" => {
                 let page = self.page(&a)?;
                 let doc = self.doc(&a)?;
@@ -397,7 +423,11 @@ impl Automation {
                     .enumerate()
                     .map(|(i, im)| {
                         let (u, v) = (info.user_to_view(im.rect[0] as f32, im.rect[1] as f32), info.user_to_view(im.rect[2] as f32, im.rect[3] as f32));
-                        json!({ "image": i + 1, "rect": [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))], "pixels": [im.width, im.height], "name": im.name, "kind": if im.is_form { "form" } else { "image" } })
+                        let visible = im.visible_rect.map(|rect| {
+                            let (u, v) = (info.user_to_view(rect[0] as f32, rect[1] as f32), info.user_to_view(rect[2] as f32, rect[3] as f32));
+                            [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))]
+                        });
+                        json!({ "visible_rect": visible, "image": i + 1, "rect": [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))], "pixels": [im.width, im.height], "name": im.name, "kind": if im.is_form { "form" } else { "image" } })
                     })
                     .collect();
                 json!({ "page": page + 1, "count": list.len(), "images": list })
@@ -466,6 +496,8 @@ impl Automation {
                         json!({
                             "paragraph": i + 1,
                             "text": b.text,
+                            "editor_text": b.editor_text,
+                            "rows": b.rows.iter().map(|row| row.iter().map(|i| i + 1).collect::<Vec<_>>()).collect::<Vec<_>>(),
                             "lines": b.lines.iter().map(|l| l + 1).collect::<Vec<_>>(),
                             "rect": [r(u[0].min(v[0])), r(u[1].min(v[1])), r(u[0].max(v[0])), r(u[1].max(v[1]))],
                             "font": b.base_font,
@@ -475,6 +507,78 @@ impl Automation {
                     .collect();
                 json!({ "page": page + 1, "count": blocks.len(), "paragraphs": blocks })
             }
+            "text_font_files" => {
+                let roots = if let Some(paths) = a.get("directories") {
+                    let paths = paths
+                        .as_array()
+                        .filter(|p| p.len() <= 16)
+                        .ok_or_else(|| ToolError::InvalidArgs("directories must be at most 16 paths".into()))?;
+                    paths
+                        .iter()
+                        .map(|p| self.resolve(p.as_str().ok_or_else(|| ToolError::InvalidArgs("directory must be a path".into()))?, false))
+                        .collect::<Result<Vec<_>>>()?
+                } else if let Some(root) = &self.root {
+                    vec![root.clone()]
+                } else {
+                    pdfcraft_engine::text_fonts::installed_directories()
+                };
+                json!({"fonts": pdfcraft_engine::text_fonts::discover(&roots).into_iter().map(|f| json!({"path":f.path,"family":f.family,"font":f.face})).collect::<Vec<_>>()})
+            }
+            "text_font_import" => {
+                let page = self.page(&a)?;
+                let path = self.resolve(a.str("path")?, false)?;
+                let file = std::fs::File::open(&path).map_err(failed)?;
+                use std::io::Read;
+                let mut bytes = Vec::new();
+                file.take((16 << 20) + 1).read_to_end(&mut bytes).map_err(failed)?;
+                if bytes.len() > 16 << 20 {
+                    return Err(ToolError::InvalidArgs("font input exceeds 16 MiB".into()));
+                }
+                let before: Vec<_> = self.doc(&a)?.text_editor_fonts(page).into_iter().map(|f| f.resource).collect();
+                let mut out = self.apply(&a, Edit::RegisterTextFont { page, bytes: Arc::new(bytes) })?;
+                let added = self
+                    .doc(&a)?
+                    .text_editor_fonts(page)
+                    .into_iter()
+                    .find(|f| !before.contains(&f.resource) && !f.resource.starts_with("PCApproved"));
+                if let Some(f) = added {
+                    out["resource"] = json!(f.resource);
+                    out["font"] = json!(f.face);
+                }
+                out
+            }
+            "text_fonts" => {
+                let page = self.page(&a)?;
+                json!({"fonts": self.doc(&a)?.text_editor_fonts(page).into_iter().map(|f| json!({"resource":f.resource,"font":f.face,"full_face":f.resource.starts_with("PCFull"),"preview_only":f.resource.starts_with("PCApproved")})).collect::<Vec<_>>()})
+            }
+            "text_edit_layout" => {
+                let page = self.page(&a)?;
+                let doc = self.doc(&a)?;
+                let k = a.int("paragraph")?;
+                let blocks = doc.text_blocks(page);
+                if k < 1 || k as usize > blocks.len() {
+                    return Err(ToolError::InvalidArgs("paragraph is out of range".into()));
+                }
+                let source = &blocks[k as usize - 1];
+                let text = a.opt_str("text")?.unwrap_or(&source.editor_text);
+                let style = pdfcraft_engine::BlockStyle {
+                    size: a.opt_num("size")?,
+                    width: a.opt_num("width")?,
+                    resource: a.opt_str("font_resource")?.map(str::to_owned),
+                    ranges: parse_style_ranges(a.get("ranges"))?,
+                    ..Default::default()
+                };
+                let layout = doc.text_edit_layout(page, k as usize - 1, text, &style).map_err(failed)?;
+                let info = &doc.info.pages[page];
+                let view_rect = |r: [f64; 4]| {
+                    let a = info.user_to_view(r[0] as f32, r[1] as f32);
+                    let b = info.user_to_view(r[2] as f32, r[3] as f32);
+                    [a[0].min(b[0]), a[1].min(b[1]), a[0].max(b[0]), a[1].max(b[1])]
+                };
+                let fonts: Vec<_> = doc.text_editor_fonts(page).into_iter().map(|f| json!({"resource": f.resource, "face": f.face})).collect();
+                json!({ "page": page + 1, "paragraph": k, "source_rect": view_rect(layout.source_rect),
+                    "draft_rect": layout.draft_rect.map(view_rect), "overflow": layout.overflow, "embedded_fonts": fonts })
+            }
             "text_edit" if a.get("paragraph").is_some() => {
                 let page = self.page(&a)?;
                 let n = self.doc(&a)?.text_blocks(page).len();
@@ -485,6 +589,8 @@ impl Automation {
                 let block = self.doc(&a)?.text_blocks(page)[k as usize - 1].clone();
                 let text = a.opt_str("text")?.map(str::to_owned).unwrap_or(block.text);
                 let mut style = pdfcraft_engine::BlockStyle {
+                    ranges: parse_style_ranges(a.get("ranges"))?,
+                    resource: a.opt_str("font_resource")?.map(str::to_owned),
                     bold: a.opt_bool("bold")?,
                     size: a.opt_num("size")?,
                     underline: a.opt_bool("underline")?,
@@ -583,6 +689,7 @@ impl Automation {
             "printers" => self.printers()?,
             "printer_options" => self.printer_options(&a)?,
             "link_list" => self.link_list(&a)?,
+            "link_open" => self.link_open(&a)?,
             "link_add" => self.link_add(&a)?,
             "link_edit" => self.link_edit(&a)?,
             "link_delete" => self.link_delete(&a)?,
@@ -615,6 +722,8 @@ impl Automation {
             "comment_set_status" => self.comment_set_status(&a)?,
             "sign_list" => self.sign_list(&a)?,
             "accessibility_check" => self.a11y_check(&a)?,
+            "accessibility_autotag_preview" => self.accessibility_autotag_preview(&a)?,
+            "accessibility_autotag_apply" => self.accessibility_autotag_apply(&a)?,
             "ocr_recognize" => self.ocr_recognize(&a)?,
             "js_run" => self.js_run(&a)?,
             "js_document_scripts" => self.js_document_scripts(&a)?,
@@ -627,6 +736,7 @@ impl Automation {
             "doc_compare" => self.doc_compare(&a)?,
             "action_list" => self.action_list()?,
             "pdfa_verify" => self.pdfa_verify(&a)?,
+            "print_readiness" => self.print_readiness(&a)?,
             "doc_export_office" => self.doc_export_office(&a)?,
             "pdfa_convert" => self.pdfa_convert(&a)?,
             "action_run" => self.action_run(&a)?,
@@ -636,9 +746,16 @@ impl Automation {
             "ocr_status" => self.ocr_status()?,
             "ocr_recognize_files" => self.ocr_recognize_files(&a)?,
             "accessibility_report" => self.a11y_report(&a)?,
+            "accessibility_review_record" => self.a11y_review_record(&a)?,
+            "accessibility_review_save" => self.a11y_review_save(&a)?,
+            "accessibility_review_load" => self.a11y_review_load(&a)?,
+            "accessibility_review_html" => self.a11y_review_html(&a)?,
             "accessibility_fix" => self.a11y_fix(&a)?,
             "accessibility_figures" => self.accessibility_figures(&a)?,
             "accessibility_set_alt" => self.accessibility_set_alt(&a)?,
+            "accessibility_tags" => self.accessibility_tags(&a)?,
+            "accessibility_set_tag_property" => self.accessibility_set_tag_property(&a)?,
+            "accessibility_move_tag" => self.accessibility_move_tag(&a)?,
             "sign_id_create" => self.sign_id_create(&a)?,
             "sign_document" => self.sign_document(&a)?,
             "sign_keychain_ids" => {
@@ -676,6 +793,7 @@ impl Automation {
             "comment_mark" => self.comment_mark(&a)?,
             "comment_lock" => self.comment_lock(&a)?,
             "comments_hide" => self.comments_hide(&a)?,
+            "view_reading_colors" => self.view_reading_colors(&a)?,
             "comments_summarize" => self.comments_summarize(&a)?,
             "comment_edit" => self.comment_edit(&a)?,
             "comment_delete" => self.comment_delete(&a)?,
@@ -740,6 +858,10 @@ impl Automation {
     }
 
     fn doc_save(&mut self, a: &Args) -> Result<Value> {
+        self.doc_save_with(a, write_atomic)
+    }
+
+    fn doc_save_with(&mut self, a: &Args, write: impl FnOnce(&Path, &[u8]) -> Result<()>) -> Result<Value> {
         let doc = self.doc(a)?;
         let id = doc.id;
         let target = match a.opt_str("path")? {
@@ -754,10 +876,13 @@ impl Automation {
             self.apply(a, Edit::FlattenFillSign)?;
         }
         let bytes = if full { self.session.save_full_bytes(id) } else { self.session.save_bytes(id) }.map_err(failed)?;
-        write_atomic(&target, &bytes)?;
+        // A save that adds or removes encryption, or must not keep the old revision (Sanitize,
+        // redaction), is rewritten in full even when an incremental save was asked for.
+        let incremental = !full && bytes.starts_with(&self.doc(a)?.saved_bytes());
+        write(&target, &bytes)?;
         let path = target.to_string_lossy().into_owned();
         self.session.mark_saved(id, bytes.clone(), Some(path.clone())).map_err(failed)?;
-        Ok(json!({ "path": path, "bytes": bytes.len(), "incremental": !full, "document": summary(self.doc(a)?) }))
+        Ok(json!({ "path": path, "bytes": bytes.len(), "incremental": incremental, "document": summary(self.doc(a)?) }))
     }
 
     fn doc_revisions(&mut self, a: &Args) -> Result<Value> {
@@ -965,7 +1090,13 @@ impl Automation {
     fn apply(&mut self, a: &Args, edit: Edit) -> Result<Value> {
         let id = self.doc(a)?.id;
         self.session.apply(id, edit).map_err(failed)?;
-        Ok(summary(self.doc(a)?))
+        let doc = self.doc(a)?;
+        let mut out = summary(doc);
+        // Text the edit stored as typed but drew with `?` (its font can't draw it): said, not silent.
+        if !doc.edit_notices.is_empty() {
+            out["warnings"] = json!(doc.edit_notices.iter().map(ToString::to_string).collect::<Vec<_>>());
+        }
+        Ok(out)
     }
 
     fn marks(&mut self, tool: &str, a: &Args) -> Result<Value> {
@@ -1132,11 +1263,13 @@ impl Automation {
                     }
                     (None, None) => return Err(ToolError::InvalidArgs("text needs `text` or `path`".into())),
                 };
-                // The page font is Helvetica/WinAnsi: refuse what it would silently turn into `?`.
-                if let Some(c) = pdfcraft_engine::first_undrawable_plain(&text) {
-                    return Err(ToolError::InvalidArgs(pdfcraft_engine::undrawable_message(c)));
-                }
-                (format!("{title}.pdf"), self.session.create_from_text(&title, &text).map_err(failed)?)
+                // The page font is Helvetica/WinAnsi: text it would turn into `?` is refused (with
+                // its line) by `pdfcraft_create::from_text`, as for every other caller.
+                let bytes = self.session.create_from_text(&title, &text).map_err(|e| match e {
+                    pdfcraft_engine::EditError::Create(pdfcraft_engine::CreateError::Invalid(m)) => ToolError::InvalidArgs(m),
+                    e => failed(e),
+                })?;
+                (format!("{title}.pdf"), bytes)
             }
             other => return Err(ToolError::InvalidArgs(format!("unknown source {other:?}"))),
         };
@@ -1251,7 +1384,7 @@ impl Automation {
         let bytes = std::fs::read(&path).map_err(|e| failed(format!("{}: {e}", path.display())))?;
         let pages = a.opt_ints("pages")?.map(|p| one_based(&p)).transpose()?;
         let name = path.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
-        self.apply(a, Edit::InsertPagesFrom { name, bytes: Arc::new(bytes), pages, at })
+        self.apply(a, Edit::InsertPagesFrom { name, bytes: Arc::new(bytes), pages, at, field_conflicts: pdfcraft_organize::FieldConflicts::Rename })
     }
 
     /// Write freshly created bytes to `out` and/or open them as a new document.
@@ -1388,6 +1521,13 @@ impl Automation {
             }
             Some(_) => return Err(ToolError::InvalidArgs("groups must list a number (or null) for each path".into())),
         };
+        let field_conflicts = match a.opt_str("field_conflicts")? {
+            None | Some("rename") => pdfcraft_organize::FieldConflicts::Rename,
+            Some("merge") => pdfcraft_organize::FieldConflicts::Merge,
+            Some(other) => {
+                return Err(ToolError::InvalidArgs(format!("field_conflicts must be \"rename\" or \"merge\", not {other:?}")));
+            }
+        };
         let mut sources: Vec<CombineSource> = Vec::new();
         let mut firsts: Vec<(u64, PathBuf, usize)> = Vec::new();
         for (i, (p, range)) in paths.into_iter().zip(ranges).enumerate() {
@@ -1415,8 +1555,8 @@ impl Automation {
             sources.push((name, bytes, range));
         }
         let passwords: Vec<Option<&str>> = passwords.iter().map(Option::as_deref).collect();
-        let bytes = match groups {
-            None => self.session.combine_unlocked(&sources, &passwords),
+        let combined = match groups {
+            None => self.session.combine_unlocked_reporting(&sources, &passwords, field_conflicts),
             Some(groups) => {
                 // A path without a group is a file of its own: give it a key no group uses.
                 let mut next = groups.iter().flatten().max().map_or(Some(0), |m| m.checked_add(1));
@@ -1431,11 +1571,15 @@ impl Automation {
                         }
                     });
                 }
-                self.session.combine_grouped(&sources, &keys, &passwords)
+                self.session.combine_grouped_reporting(&sources, &keys, &passwords, field_conflicts)
             }
         }
         .map_err(failed)?;
-        self.deliver(a, "Combined", bytes)
+        let mut result = self.deliver(a, "Combined", combined.bytes)?;
+        if !combined.renamed_fields.is_empty() {
+            result["renamed_fields"] = json!(combined.renamed_fields.iter().map(|(old, new)| json!([old, new])).collect::<Vec<_>>());
+        }
+        Ok(result)
     }
 
     fn doc_split(&mut self, a: &Args) -> Result<Value> {
@@ -1522,8 +1666,9 @@ impl Automation {
 
     fn renderer(&mut self, id: DocId) -> Result<&mut PageRenderer> {
         let doc = self.session.get(id).ok_or_else(|| failed("no such document"))?;
+        let colors = self.session.reading_colors(id).unwrap_or_default();
         let fresh = || {
-            let config = RenderConfig { password: doc.password.as_deref().map(Arc::from), ..Default::default() };
+            let config = RenderConfig { password: doc.password.as_deref().map(Arc::from), reading_colors: colors, ..Default::default() };
             (doc.display.clone(), PageRenderer::new(doc.display.clone(), config))
         };
         let entry = self.renderers.entry(id).or_insert_with(fresh);
@@ -1540,7 +1685,16 @@ impl Automation {
         if !(1.0..=MAX_DPI).contains(&dpi) {
             return Err(ToolError::InvalidArgs(format!("dpi must be between 1 and {MAX_DPI}")));
         }
-        let out = self.renderer(id)?.render(RenderRequest { page, kind: RequestKind::Pixels, tile: None, scale: (dpi / 72.0) as f32, tag: 0 });
+        let scale = (dpi / 72.0) as f32;
+        let out = if let Some(block) = a.opt_int("hide_text_block")? {
+            let index = usize::try_from(block)
+                .ok()
+                .and_then(|n| n.checked_sub(1))
+                .ok_or_else(|| ToolError::InvalidArgs("hide_text_block must be a positive paragraph index from text_paragraphs".into()))?;
+            self.doc(a)?.text_edit_preview(page, index).map_err(failed)?.render_background(scale).map_err(failed)?
+        } else {
+            self.renderer(id)?.render(RenderRequest { page, kind: RequestKind::Pixels, tile: None, scale, tag: 0, preview: false })
+        };
         if let Some(e) = out.error {
             return Err(failed(format!("page {} could not be rendered: {e}", page + 1)));
         }
@@ -1559,23 +1713,47 @@ impl Automation {
 
     /// The text of `pages` (0-based), from the cache or extracted in parallel.
     fn page_texts(&mut self, id: DocId, pages: &[usize]) -> Result<Vec<Arc<PageText>>> {
+        self.page_text_results(id, pages, &mut extract_parallel)?
+            .into_iter()
+            .map(|(p, text)| text.map_err(|e| failed(format!("page {}: {e}", p + 1))))
+            .collect()
+    }
+
+    /// Keep per-page failures until the caller chooses strict or partial-result semantics.
+    fn page_text_results(
+        &mut self,
+        id: DocId,
+        pages: &[usize],
+        extract: &mut impl FnMut(&Arc<Vec<u8>>, Option<Arc<str>>, &[usize]) -> PageTexts,
+    ) -> Result<PageTexts> {
         let doc = self.session.get(id).ok_or_else(|| failed("no such document"))?;
         let (bytes, n) = (doc.bytes.clone(), doc.info.pages.len());
         let password: Option<Arc<str>> = doc.password.as_deref().map(Arc::from);
-        let entry = self.texts.entry(id).or_insert_with(|| (bytes.clone(), Vec::new()));
-        if !Arc::ptr_eq(&entry.0, &bytes) || entry.1.len() != n {
-            *entry = (bytes.clone(), vec![None; n]);
-        }
-        let mut missing: Vec<usize> = pages.iter().copied().filter(|p| entry.1.get(*p).is_some_and(Option::is_none)).collect();
-        missing.sort_unstable();
-        missing.dedup();
-        for (p, text) in extract_parallel(&bytes, password, &missing) {
-            let text = Arc::new(text.map_err(|e| failed(format!("page {}: {e}", p + 1)))?);
-            if let Some(slot) = entry.1.get_mut(p) {
-                *slot = Some(text);
+        self.texts.prepare(id, &bytes);
+        let mut results = HashMap::new();
+        let mut missing = Vec::new();
+        for &p in pages {
+            if p >= n {
+                results.insert(p, Err("page is out of range".to_owned()));
+            } else if let Some(text) = self.texts.get(id, p) {
+                results.insert(p, Ok(text));
+            } else {
+                missing.push(p);
             }
         }
-        pages.iter().map(|p| entry.1.get(*p).cloned().flatten().ok_or_else(|| failed(format!("page {} has no text", p + 1)))).collect()
+        missing.sort_unstable();
+        missing.dedup();
+        if !missing.is_empty() {
+            for (p, text) in extract(&bytes, password, &missing) {
+                if let Ok(text) = &text {
+                    self.texts.insert(id, p, &bytes, text.clone());
+                }
+                results.insert(p, text);
+            }
+        }
+        // The batch owns its Arcs: evicting a cache entry cannot lose a requested result. A
+        // worker that fails to return a page is an explicit failure, never an empty success.
+        Ok(pages.iter().map(|p| (*p, results.get(p).cloned().unwrap_or_else(|| Err("text extraction returned no result".into())))).collect())
     }
 
     fn text_extract(&mut self, a: &Args) -> Result<Value> {
@@ -1598,9 +1776,13 @@ impl Automation {
 
     /// Matches in document order, extracting page text in growing batches and stopping as soon as
     /// `limit` is reached, so a bounded search doesn't extract (and cache) the whole document
-    /// (#971). One match past the limit is looked for, so `complete` is true only when no more
-    /// exist; otherwise `next` holds the arguments that continue the search.
+    /// (#971). One match past the limit supplies `next`. Reached extraction failures are reported
+    /// as bounded warnings; `complete` requires both no continuation and no failed pages.
     fn text_find(&mut self, a: &Args) -> Result<Value> {
+        self.text_find_with(a, &mut extract_parallel)
+    }
+
+    fn text_find_with(&mut self, a: &Args, extract: &mut impl FnMut(&Arc<Vec<u8>>, Option<Arc<str>>, &[usize]) -> PageTexts) -> Result<Value> {
         let doc = self.doc(a)?;
         let (id, n) = (doc.id, doc.info.pages.len());
         let query = a.str("query")?;
@@ -1613,14 +1795,32 @@ impl Automation {
         let skip = usize::try_from(a.opt_int("skip")?.unwrap_or(0).max(0)).unwrap_or(usize::MAX);
         let mut matches = Vec::new();
         let mut next = None;
+        let mut warnings = Vec::new();
+        let mut warning_count = 0usize;
         let (mut first, mut batch) = (start, FIND_FIRST_BATCH);
         'search: while first < n {
             let end = first.saturating_add(batch).min(n);
             let pages: Vec<usize> = (first..end).collect();
-            let texts = self.page_texts(id, &pages)?;
-            for (p, text) in pages.iter().zip(&texts) {
-                let skip_here = if *p == start { skip } else { 0 };
-                for (k, r) in text.find(query).into_iter().enumerate().skip(skip_here) {
+            let texts = self.page_text_results(id, &pages, extract)?;
+            for (p, text) in texts {
+                let text = match text {
+                    Ok(text) => text,
+                    Err(mut error) => {
+                        warning_count += 1;
+                        if warnings.len() < FIND_MAX_WARNINGS {
+                            let end = error.floor_char_boundary(FIND_MAX_WARNING_BYTES.min(error.len()));
+                            let truncated = end < error.len();
+                            error.truncate(end);
+                            warnings.push(json!({ "page": p + 1, "error": error, "error_truncated": truncated }));
+                        }
+                        continue;
+                    }
+                };
+                let skip_here = if p == start { skip } else { 0 };
+                // One extra match proves that the caller needs a continuation. Include skipped
+                // matches on the starting page when bounding the temporary per-page result.
+                let needed = limit.saturating_sub(matches.len()).saturating_add(skip_here).saturating_add(1);
+                for (k, r) in text.find_opts_limited(query, false, false, needed).into_iter().enumerate().skip(skip_here) {
                     if matches.len() == limit {
                         next = Some(json!({ "start_page": p + 1, "skip": k }));
                         break 'search;
@@ -1631,7 +1831,8 @@ impl Automation {
             first = end;
             batch = batch.saturating_mul(2).min(FIND_MAX_BATCH);
         }
-        let mut out = json!({ "query": query, "count": matches.len(), "complete": next.is_none(), "matches": matches });
+        let mut out = json!({ "query": query, "count": matches.len(), "complete": next.is_none() && warning_count == 0, "matches": matches,
+            "warnings_truncated": warning_count > warnings.len(), "warning_count": warning_count, "warnings": warnings });
         if let (Some(next), Some(o)) = (next, out.as_object_mut()) {
             o.insert("next".into(), next);
         }
@@ -1759,6 +1960,53 @@ fn foreign_share(path: &Path, root: &Path) -> bool {
 
 // ---- JSON helpers ----------------------------------------------------------------------------
 
+fn parse_style_ranges(value: Option<&Value>) -> Result<Vec<pdfcraft_engine::RangeStyle>> {
+    let Some(value) = value else { return Ok(Vec::new()) };
+    let values = value.as_array().filter(|v| v.len() <= 1024).ok_or_else(|| Args::wrong("ranges", "an array of at most 1024 style objects"))?;
+    values
+        .iter()
+        .map(|v| {
+            let a = Args(v);
+            let bounds = a
+                .get("range")
+                .and_then(Value::as_array)
+                .filter(|v| v.len() == 2)
+                .ok_or_else(|| Args::wrong("range", "[start,end] UTF-8 byte offsets"))?;
+            let start = bounds
+                .first()
+                .and_then(Value::as_u64)
+                .and_then(|n| usize::try_from(n).ok())
+                .ok_or_else(|| Args::wrong("range", "nonnegative byte offsets"))?;
+            let end = bounds
+                .get(1)
+                .and_then(Value::as_u64)
+                .and_then(|n| usize::try_from(n).ok())
+                .ok_or_else(|| Args::wrong("range", "nonnegative byte offsets"))?;
+            let family = a
+                .opt_str("font")?
+                .map(|f| match f {
+                    "helvetica" => Ok(pdfcraft_engine::FontFamily::Helvetica),
+                    "times" => Ok(pdfcraft_engine::FontFamily::Times),
+                    "courier" => Ok(pdfcraft_engine::FontFamily::Courier),
+                    _ => Err(Args::wrong("font", "helvetica, times or courier")),
+                })
+                .transpose()?
+                .map(|f| -> Result<_> { Ok((f, a.opt_bool("bold")?.unwrap_or(false), a.opt_bool("italic")?.unwrap_or(false))) })
+                .transpose()?;
+            Ok(pdfcraft_engine::RangeStyle {
+                range: start..end,
+                family,
+                resource: a.opt_str("font_resource")?.map(str::to_owned),
+                size: a.opt_num("size")?,
+                color: a.opt_str("color")?.map(comments::parse_color).transpose()?,
+                underline: a.opt_bool("underline")?,
+                char_spacing: a.opt_num("char_spacing")?,
+                scale: a.opt_num("scale")?,
+            })
+        })
+        .collect()
+}
+
 /// Typed access to validated arguments.
 struct Args<'a>(&'a Value);
 
@@ -1909,6 +2157,9 @@ fn info(d: &Document) -> Value {
         // (laid out from the template by PdfCraft, see xfa_layout; placeholder pages when that failed).
         "xfa": i.xfa.map(|x| match x { pdfcraft_render::Xfa::Static => "static", pdfcraft_render::Xfa::Dynamic => "dynamic" }),
         "xfa_layout": d.xfa.as_ref().map(|x| json!({ "pages": x.pages, "fields": x.fields, "warnings": x.warnings })),
+        // A script of the form ran too long and was abandoned: its scripts no longer run in this
+        // document (calculations, buttons) until it is opened again.
+        "xfa_scripts_off": d.xfa_scripts_off(),
         // What was rewritten from, or could not be written to, the XFA data.
         "xfa_warnings": d.xfa_warnings,
         "security": security,
@@ -1944,13 +2195,27 @@ fn info(d: &Document) -> Value {
                     })).collect::<Vec<_>>(),
                     "preserve_rb": preserve_rb,
                 }),
+                pdfcraft_render::LinkTarget::RemoteGoTo { file, destination, new_window } => json!({
+                    "remote_document": file,
+                    "destination": match destination {
+                        pdfcraft_render::RemoteDestination::Default => json!({ "kind": "default" }),
+                        pdfcraft_render::RemoteDestination::Page { page, view } => json!({ "kind": "page", "page": page1(*page), "view": format!("{view:?}") }),
+                        pdfcraft_render::RemoteDestination::Named(name) => json!({ "kind": "named", "name": name }),
+                    },
+                    "new_window": new_window,
+                }),
                 pdfcraft_render::LinkTarget::Other(o) => json!({ "other": o }),
             },
         })).collect::<Vec<_>>(),
         "layers": i.layers.iter().map(|l| json!({ "name": l.name, "visible": l.visible })).collect::<Vec<_>>(),
         "attachments": i.attachments.iter().map(|a| json!({ "name": a.name, "description": a.description, "size": a.size })).collect::<Vec<_>>(),
+        // `substitute` names the face standing in for a program the document does not embed, and
+        // `substitution` says why. Both are null for an embedded font: nothing stands in. A null
+        // `substitute` with a non-null `substitution` means no face was available at all, so
+        // nothing is drawn for that font -- which is the answer to "why is my text missing?".
         "fonts": i.fonts.iter().map(|f| json!({
             "name": f.name, "kind": f.kind, "embedded": f.embedded, "subset": f.subset, "encoding": f.encoding,
+            "substitute": f.substitute, "substitution": f.substitution,
         })).collect::<Vec<_>>(),
         "warnings": i.warnings,
         "repairs": d.repair_log(),
@@ -1988,12 +2253,12 @@ fn encode_png(width: u32, height: u32, premultiplied: &[u8]) -> Result<Vec<u8>>
 }
 
 /// Extract the text of `pages` (0-based) with one renderer per worker thread.
-fn extract_parallel(bytes: &Arc<Vec<u8>>, password: Option<Arc<str>>, pages: &[usize]) -> Vec<(usize, std::result::Result<PageText, String>)> {
+fn extract_parallel(bytes: &Arc<Vec<u8>>, password: Option<Arc<str>>, pages: &[usize]) -> PageTexts {
     let extract = |r: &mut PageRenderer, p: usize| {
-        let out = r.render(RenderRequest { page: p, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0 });
+        let out = r.render(RenderRequest { page: p, kind: RequestKind::Text, tile: None, scale: 1.0, tag: 0, preview: false });
         match out.error {
             Some(e) => Err(e),
-            None => Ok(out.text.map(|t| (*t).clone()).unwrap_or_default()),
+            None => Ok(out.text.unwrap_or_default()),
         }
     };
     let config = RenderConfig { password, ..Default::default() };
@@ -2004,7 +2269,7 @@ fn extract_parallel(bytes: &Arc<Vec<u8>>, password: Option<Arc<str>>, pages: &[u
         return pages.iter().map(|p| (*p, extract(&mut r, *p))).collect();
     }
     let next = std::sync::atomic::AtomicUsize::new(0);
-    let mut out: Vec<(usize, std::result::Result<PageText, String>)> = std::thread::scope(|s| {
+    let mut out: PageTexts = std::thread::scope(|s| {
         let handles: Vec<_> = (0..workers)
             .map(|_| {
                 s.spawn(|| {
@@ -2045,13 +2310,24 @@ fn unused(dir: &Path, stem: &str) -> PathBuf {
     (2..10_000u32).map(|n| child(dir, &format!("{stem} ({n}).pdf"))).find(|p| !p.exists()).unwrap_or(first)
 }
 
-/// Write via a temporary file in the same directory, then rename over the target.
+/// Write and sync a temporary file in the same directory, then rename over the target.
+/// This flushes staged contents; it does not promise parent-directory durability after a
+/// power loss. Filesystems that refuse sync cause the save to fail before publication.
 fn write_atomic(path: &Path, bytes: &[u8]) -> Result<()> {
     write_atomic_with(path, bytes, staging_suffixes())
 }
 
 /// [`write_atomic`], trying the staging names that `suffixes` give.
 fn write_atomic_with(path: &Path, bytes: &[u8], suffixes: impl IntoIterator<Item = u64>) -> Result<()> {
+    write_atomic_synced(path, bytes, suffixes, std::fs::File::sync_all)
+}
+
+fn write_atomic_synced(
+    path: &Path,
+    bytes: &[u8],
+    suffixes: impl IntoIterator<Item = u64>,
+    sync: impl FnOnce(&std::fs::File) -> std::io::Result<()>,
+) -> Result<()> {
     use std::io::Write;
     // A folder can't be replaced, and staging beside it could land outside the root: "." names
     // the root itself, whose parent isn't ours to write in.
@@ -2066,7 +2342,9 @@ fn write_atomic_with(path: &Path, bytes: &[u8], suffixes: impl IntoIterator<Item
     // Closed at the end of the block, before the rename.
     let written = {
         let mut file = file;
-        file.write_all(bytes)
+        // Surface delayed writeback failures before replacing the destination or marking
+        // a document clean. The handle is closed before rename (required on Windows).
+        file.write_all(bytes).and_then(|()| sync(&file))
     };
     if let Err(e) = written {
         let _ = std::fs::remove_file(&tmp);
@@ -2116,6 +2394,118 @@ mod tests {
         }
     }
 
+    fn search_document(a: &mut Automation, pages: usize) -> DocId {
+        a.session.open("synthetic.pdf", None, Arc::new(numbered_pages(pages)), None).unwrap()
+    }
+
+    #[test]
+    fn search_cache_stays_bounded_reextracts_and_follows_edits_and_close() {
+        let mut a = Automation::new();
+        a.texts = TextCache::new(16 * 1024);
+        let first = search_document(&mut a, 200);
+        let second = search_document(&mut a, 200);
+        for id in [first, second] {
+            let result = json(&mut a, "text_find", json!({ "doc": id.0, "query": "absent" }));
+            assert_eq!(result["complete"], true);
+            assert!(a.texts.bytes() <= 16 * 1024);
+            assert!(a.texts.len() < 200, "an exhaustive search must not retain every page");
+            let found = json(&mut a, "text_find", json!({ "doc": id.0, "query": "Page", "limit": 1000 }));
+            assert_eq!(found["count"], 200, "eviction inside a batch must not discard its matches");
+            eprintln!("200 pages searched: {} resident pages, {} estimated bytes (budget 16384)", a.texts.len(), a.texts.bytes());
+        }
+        assert!(a.texts.get(first, 0).is_none());
+        let text = a.page_texts(first, &[0]).unwrap().remove(0);
+        assert_eq!(text.plain_text(), "Page 1");
+        let again = a.page_texts(first, &[0]).unwrap().remove(0);
+        assert!(Arc::ptr_eq(&text, &again), "cache hits reuse glyph storage");
+        assert!(a.texts.bytes() <= 16 * 1024);
+        json(&mut a, "page_delete", json!({ "doc": first.0, "pages": [1] }));
+        let edited = a.page_texts(first, &[0]).unwrap().remove(0);
+        assert_eq!(edited.plain_text(), "Page 2");
+        assert!(!Arc::ptr_eq(&text, &edited));
+        json(&mut a, "doc_close", json!({ "doc": first.0, "discard_changes": true }));
+        json(&mut a, "doc_close", json!({ "doc": second.0 }));
+        assert_eq!((a.texts.bytes(), a.texts.len()), (0, 0));
+    }
+
+    #[test]
+    fn strict_text_collection_refuses_partial_results_but_keeps_successful_pages() {
+        let mut a = Automation::new();
+        let id = search_document(&mut a, 3);
+        let error = a.page_texts(id, &[0, 3, 1]).unwrap_err();
+        assert!(error.to_string().contains("page 4: page is out of range"));
+        assert!(a.texts.get(id, 0).is_some());
+        assert!(a.texts.get(id, 1).is_some(), "successful extraction after the failed entry is retained");
+        let results = a.page_text_results(id, &[2], &mut |_, _, _| vec![]).unwrap();
+        assert!(results[0].1.is_err(), "a missing worker result must not become an empty page");
+    }
+
+    #[test]
+    fn search_keeps_matches_around_failed_pages_and_continuations() {
+        let mut a = Automation::new();
+        let id = search_document(&mut a, 16);
+        let mut extract = |bytes: &Arc<Vec<u8>>, password, pages: &[usize]| {
+            extract_parallel(bytes, password, pages)
+                .into_iter()
+                .map(|(p, result)| (p, if [2, 6].contains(&p) { Err(format!("synthetic page {} failure", p + 1)) } else { result }))
+                .collect()
+        };
+        let all = a.text_find_with(&Args(&json!({ "doc": id.0, "query": "Page" })), &mut extract).unwrap();
+        assert_eq!(all["count"], 14);
+        assert_eq!(all["complete"], false);
+        assert_eq!(all["warning_count"], 2);
+        assert_eq!(all["warnings"][0]["page"], 3);
+        assert_eq!(all["warnings"][1]["page"], 7);
+        assert!(all.get("next").is_none());
+        assert_eq!(all["matches"][13]["page"], 16);
+        assert!(a.texts.get(id, 7).is_some(), "success after a failure in the same batch is cached");
+        let mut args = json!({ "doc": id.0, "query": "Page", "limit": 4 });
+        let mut matches = Vec::new();
+        let mut warned = Vec::new();
+        loop {
+            let part = a.text_find_with(&Args(&args), &mut extract).unwrap();
+            matches.extend(part["matches"].as_array().unwrap().iter().cloned());
+            warned.extend(part["warnings"].as_array().unwrap().iter().map(|w| w["page"].clone()));
+            if !part["warnings"].as_array().unwrap().is_empty() {
+                assert_eq!(part["complete"], false);
+            }
+            let Some(next) = part.get("next") else { break };
+            args["start_page"] = next["start_page"].clone();
+            args["skip"] = next["skip"].clone();
+        }
+        assert_eq!(matches, *all["matches"].as_array().unwrap(), "no readable match is lost or repeated");
+        assert_eq!(warned, vec![json!(3), json!(7)]);
+    }
+
+    #[test]
+    fn search_bounds_warning_volume_and_does_not_reach_distant_failures() {
+        let mut a = Automation::new();
+        let id = search_document(&mut a, 200);
+        let first = a
+            .text_find_with(&Args(&json!({ "doc": id.0, "query": "Page", "limit": 1 })), &mut |bytes, password, pages| {
+                assert!(pages.iter().all(|p| *p < FIND_FIRST_BATCH), "a bounded search must not reach the bad page at the end");
+                extract_parallel(bytes, password, pages)
+            })
+            .unwrap();
+        assert_eq!(first["count"], 1);
+        assert_eq!(first["warning_count"], 0);
+        assert_eq!(first["next"], json!({ "start_page": 2, "skip": 0 }));
+        a.texts.remove(&id);
+        let failures = a
+            .text_find_with(&Args(&json!({ "doc": id.0, "query": "Page" })), &mut |_, _, pages| {
+                pages.iter().map(|p| (*p, Err("界".repeat(2000)))).collect()
+            })
+            .unwrap();
+        assert_eq!(failures["count"], 0);
+        assert_eq!(failures["complete"], false);
+        assert!(failures.get("next").is_none());
+        assert_eq!(failures["warning_count"], 200);
+        assert_eq!(failures["warnings_truncated"], true);
+        let warnings = failures["warnings"].as_array().unwrap();
+        assert_eq!(warnings.len(), FIND_MAX_WARNINGS);
+        assert!(warnings.iter().all(|w| w["error"].as_str().unwrap().len() <= FIND_MAX_WARNING_BYTES && w["error_truncated"] == true));
+    }
+
     #[test]
     fn a_bounded_text_find_reads_only_the_pages_it_needs_and_says_it_stopped() {
         let dir = std::env::temp_dir().join(format!("pdfcraft-automation-find-{}", std::process::id()));
@@ -2124,7 +2514,7 @@ mod tests {
         std::fs::write(dir.join("long.pdf"), numbered_pages(200)).unwrap();
         let mut a = Automation::new().with_root(&dir).unwrap();
         let doc = json(&mut a, "doc_open", json!({ "path": "long.pdf" }))["doc"].clone();
-        let extracted = |a: &Automation| a.texts.values().map(|(_, pages)| pages.iter().filter(|t| t.is_some()).count()).sum::<usize>();
+        let extracted = |a: &Automation| a.texts.len();
 
         // #971: the first match is on page 1 and the next on page 10, so the rest of the 200 pages
         // aren't extracted or cached.
@@ -2312,6 +2702,79 @@ mod tests {
         let _ = std::fs::remove_dir_all(&dir);
     }
 
+    #[test]
+    fn a_failed_staging_sync_keeps_the_destination_and_cleans_up() {
+        for exists in [false, true] {
+            let dir = staging_dir(if exists { "sync-existing" } else { "sync-new" });
+            let target = dir.join("out.pdf");
+            if exists {
+                std::fs::write(&target, "OLD").unwrap();
+            }
+            let result = write_atomic_synced(&target, b"NEW", [1], |_| {
+                assert_eq!(std::fs::read(staged(&dir, 1)).unwrap(), b"NEW", "sync follows writing");
+                if exists {
+                    assert_eq!(read(&target), "OLD", "sync precedes publication");
+                }
+                Err(std::io::Error::other("injected storage sync failure"))
+            });
+            assert!(result.is_err(), "sync failure must refuse publication");
+            assert!(result.unwrap_err().to_string().contains("injected storage sync failure"));
+            if exists {
+                assert_eq!(read(&target), "OLD");
+                assert_eq!(listing(&dir), ["out.pdf"]);
+            } else {
+                assert!(!target.exists());
+                assert!(listing(&dir).is_empty());
+            }
+            std::fs::remove_dir_all(dir).unwrap();
+        }
+    }
+
+    #[test]
+    fn a_failed_save_sync_keeps_the_document_dirty_and_can_be_retried() {
+        let dir = staging_dir("sync-dirty");
+        let target = dir.join("out.pdf");
+        let mut a = Automation::new().with_root(&dir).unwrap();
+        let id = search_document(&mut a, 2);
+        json(&mut a, "doc_save", json!({"doc": id.0, "path": "out.pdf"}));
+        let old = std::fs::read(&target).unwrap();
+        json(&mut a, "page_rotate", json!({"doc": id.0, "pages": [1], "degrees": 90}));
+        let args = json!({"doc": id.0});
+        let before = summary(a.doc(&Args(&args)).unwrap());
+        let result = a.doc_save_with(&Args(&args), |path, bytes| {
+            write_atomic_synced(path, bytes, [1], |_| Err(std::io::Error::other("injected storage sync failure")))
+        });
+        assert!(result.is_err());
+        let doc = a.doc(&Args(&args)).unwrap();
+        assert!(doc.dirty);
+        assert_eq!(summary(doc), before, "failed save must not reset history or saved state");
+        assert_eq!(std::fs::read(&target).unwrap(), old);
+        assert_eq!(listing(&dir), ["out.pdf"]);
+        json(&mut a, "doc_save", args.clone());
+        assert!(!a.doc(&Args(&args)).unwrap().dirty);
+        assert_ne!(std::fs::read(&target).unwrap(), old);
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+
+    #[test]
+    fn successful_staging_sync_precedes_publication() {
+        let dir = staging_dir("sync-success");
+        let target = dir.join("out.pdf");
+        std::fs::write(&target, "OLD").unwrap();
+        let mut called = false;
+        write_atomic_synced(&target, b"NEW", [1], |file| {
+            called = true;
+            assert_eq!(read(&target), "OLD");
+            assert_eq!(std::fs::read(staged(&dir, 1)).unwrap(), b"NEW");
+            file.sync_all()
+        })
+        .unwrap();
+        assert!(called);
+        assert_eq!(read(&target), "NEW");
+        assert_eq!(listing(&dir), ["out.pdf"]);
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+
     /// The names in a folder: what a test can see was left behind.
     fn listing(dir: &Path) -> Vec<String> {
         let mut names: Vec<_> = std::fs::read_dir(dir).unwrap().map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();

crates/automation/src/links.rs

@@ -1,8 +1,12 @@
 //! Link tools: list, add, edit and delete links; create links from URLs in the text; remove
 //! all links. Rectangles are points from the top-left of the displayed page.
 
-use pdfcraft_engine::{Edit, LinkAction, LinkHighlight, LinkStyle};
+use pdfcraft_engine::{
+    Edit, LinkAction, LinkHighlight, LinkStyle, read_remote_document, remote_document_path_is_absolute, resolve_remote_document_path,
+};
+use pdfcraft_render::{DestView, LinkTarget, RemoteDestination};
 use serde_json::{Value, json};
+use std::path::Path;
 
 use crate::comments::parse_color;
 use crate::{Args, Automation, Result, ToolError, failed};
@@ -80,6 +84,72 @@ impl Automation {
         Ok(json!({ "count": items.len(), "links": items }))
     }
 
+    pub(crate) fn link_open(&mut self, a: &Args) -> Result<Value> {
+        let page_number = a.int("page")?;
+        let index_number = a.int("index")?;
+        let page = usize::try_from(page_number.checked_sub(1).filter(|n| *n >= 0).ok_or_else(|| bad("page must be 1 or more"))?)
+            .map_err(|_| bad("page is out of range"))?;
+        let index = usize::try_from(index_number.checked_sub(1).filter(|n| *n >= 0).ok_or_else(|| bad("index must be 1 or more"))?)
+            .map_err(|_| bad("index is out of range"))?;
+        let (source_path, file, destination, new_window) = {
+            let source = self.doc(a)?;
+            if page >= source.info.pages.len() {
+                return Err(bad(format!("page {page_number} is out of range: the document has {} pages", source.info.pages.len())));
+            }
+            let link = source
+                .info
+                .links
+                .iter()
+                .find(|link| link.page == page && link.index == index)
+                .ok_or_else(|| failed(format!("page {page_number} has no link {index_number} (see link_list)")))?;
+            let LinkTarget::RemoteGoTo { file, destination, new_window } = &link.target else {
+                return Err(bad("the selected link is not a supported local PDF GoToR link"));
+            };
+            (source.path.clone(), file.clone(), destination.clone(), *new_window)
+        };
+        let path = resolve_remote_document_path(source_path.as_deref().map(Path::new), &file).map_err(failed)?;
+        let allow_absolute = a.opt_bool("allow_absolute")?.unwrap_or(false);
+        if remote_document_path_is_absolute(&file) && !allow_absolute {
+            return Err(failed(
+                "this GoToR link names an absolute local path; review the target with link_list and pass allow_absolute: true to open it",
+            ));
+        }
+        let path = self.resolve(&path.to_string_lossy(), false)?;
+        let bytes = read_remote_document(&path).map_err(|e| failed(format!("{}: {e}", path.display())))?;
+        let name = path.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
+        let id =
+            self.session.open(name, Some(path.to_string_lossy().into_owned()), std::sync::Arc::new(bytes), a.opt_str("password")?).map_err(failed)?;
+        let opened = self.session.get(id).ok_or_else(|| failed("the linked document vanished"))?;
+        let (destination_applied, destination_value, warning) = match destination {
+            RemoteDestination::Default => (true, json!({ "kind": "default" }), None),
+            RemoteDestination::Named(name) => {
+                (false, json!({ "kind": "named", "name": name }), Some("The PDF opened, but the named destination was not applied."))
+            }
+            RemoteDestination::Page { page, view } if page < opened.info.pages.len() => {
+                (true, json!({ "kind": "page", "page": page.saturating_add(1), "view": dest_view_value(view) }), None)
+            }
+            RemoteDestination::Page { page, view } => (
+                false,
+                json!({ "kind": "page", "page": page.saturating_add(1), "view": dest_view_value(view) }),
+                Some("The PDF opened, but the link's page destination is out of range."),
+            ),
+        };
+        let mut display_path = path.to_string_lossy().into_owned();
+        if let Some(root) = &self.root
+            && let Ok(relative) = path.strip_prefix(root)
+        {
+            display_path = relative.to_string_lossy().into_owned();
+        }
+        Ok(json!({
+            "document": crate::summary(opened),
+            "path": display_path,
+            "destination_applied": destination_applied,
+            "destination": destination_value,
+            "warning": warning,
+            "new_window_hint": new_window,
+        }))
+    }
+
     pub(crate) fn link_add(&mut self, a: &Args) -> Result<Value> {
         let page = self.page(a)?;
         let rect = self.view_rect(a, page)?.ok_or_else(|| bad("link_add needs rect"))?;
@@ -126,9 +196,27 @@ impl Automation {
     }
 
     pub(crate) fn links_remove(&mut self, a: &Args) -> Result<Value> {
-        let before = self.doc(a)?.links.len();
-        let mut out = self.apply(a, Edit::RemoveLinks { pages: None })?;
+        let pages = match a.opt_ints("pages")? {
+            Some(_) => Some(self.pages(a, "pages")?),
+            None => None,
+        };
+        let before = match &pages {
+            Some(ps) => self.doc(a)?.links.iter().filter(|l| ps.contains(&l.page)).count(),
+            None => self.doc(a)?.links.len(),
+        };
+        let mut out = self.apply(a, Edit::RemoveLinks { pages })?;
         out["removed"] = json!(before);
         Ok(out)
     }
 }
+
+fn dest_view_value(view: DestView) -> Value {
+    match view {
+        DestView::Top => json!({ "kind": "top" }),
+        DestView::Xyz { left, top, zoom } => json!({ "kind": "xyz", "left": left, "top": top, "zoom": zoom }),
+        DestView::Fit => json!({ "kind": "fit" }),
+        DestView::FitH { top } => json!({ "kind": "fit_h", "top": top }),
+        DestView::FitV { left } => json!({ "kind": "fit_v", "left": left }),
+        DestView::FitR { rect } => json!({ "kind": "fit_r", "rect": rect }),
+    }
+}

crates/automation/src/mcp.rs

@@ -329,7 +329,7 @@ fn guarded_tool(f: impl FnOnce() -> Result<Value, (i64, String)>) -> Result<Valu
 }
 
 fn tool_content(name: &str, content: Vec<Content>) -> Value {
-    let failed = name == "command_batch"
+    let failed = matches!(name, "command_batch" | "doc_batch")
         && content.iter().any(|c| match c {
             Content::Json(v) => v.get("failed").and_then(Value::as_u64).is_some_and(|n| n > 0),
             _ => false,

crates/automation/src/printing.rs

@@ -12,7 +12,16 @@ fn bad(m: impl Into<String>) -> ToolError {
 
 impl Automation {
     pub(crate) fn printers(&self) -> Result<Value> {
-        let list: Vec<Value> = spool::printers().into_iter().map(|p| json!({ "name": p.name, "default": p.default })).collect();
+        let list: Vec<Value> = spool::printers()
+            .into_iter()
+            .map(|p| {
+                let mut v = json!({ "name": p.name, "default": p.default });
+                if let Some(two_sided) = p.two_sided {
+                    v["two_sided"] = json!(two_sided);
+                }
+                v
+            })
+            .collect();
         Ok(json!({ "count": list.len(), "printers": list }))
     }
 
@@ -56,9 +65,10 @@ impl Automation {
                     o => return Err(bad(format!("unknown order {o:?}"))),
                 };
                 match Layout::multiple(per) {
-                    Layout::Multiple { cols, rows, .. } => Layout::Multiple {
+                    Layout::Multiple { cols, rows, per_sheet, .. } => Layout::Multiple {
                         cols,
                         rows,
+                        per_sheet,
                         order,
                         border: a.opt_bool("border")?.unwrap_or(false),
                         auto_rotate: a.opt_bool("auto_rotate")?.unwrap_or(true),
@@ -132,12 +142,13 @@ impl Automation {
                     printer: if printer == "default" { None } else { Some(printer.to_string()) },
                     copies: a.opt_int("copies")?.unwrap_or(1).clamp(1, 999) as u32,
                     collate: a.opt_bool("collate")?.unwrap_or(true),
-                    duplex: match a.opt_str("duplex")?.unwrap_or("off") {
+                    duplex: Some(match a.opt_str("duplex")?.unwrap_or("off") {
                         "off" => spool::Duplex::Off,
                         "long-edge" => spool::Duplex::LongEdge,
                         "short-edge" => spool::Duplex::ShortEdge,
                         d => return Err(bad(format!("unknown duplex {d:?}"))),
-                    },
+                    }),
+                    scaling: spool::Scaling::Exact,
                     grayscale: a.opt_bool("grayscale")?.unwrap_or(false),
                     title: name,
                     options: match a.get("options") {

crates/automation/src/reading.rs

@@ -0,0 +1,36 @@
+//! Reading colours: Acrobat's Replace Document Colors as a tool (#897, AGENTS.md §3).
+//!
+//! A per-document view setting: solid text and line-art paints remap for readability and the
+//! page clears to the setting's background when rendering. The file itself never changes.
+
+use pdfcraft_render::ReadingColors;
+use serde_json::{Value, json};
+
+use crate::{Args, Automation, Result, ToolError};
+
+/// The modes `ReadingColors::parse` accepts, for error messages.
+const MODES: &str = "off, black-on-white, white-on-black, yellow-on-black, green-on-black, custom";
+
+impl Automation {
+    /// Set the document's reading colours. Colours are only meaningful with `mode: "custom"`;
+    /// `parse` enforces the rest and its errors are actionable.
+    pub(crate) fn view_reading_colors(&mut self, a: &Args) -> Result<Value> {
+        let id = self.doc(a)?.id;
+        let Some(mode) = a.opt_str("mode")? else {
+            return Err(ToolError::InvalidArgs(format!("mode is required (one of: {MODES})")));
+        };
+        let colors = ReadingColors::parse(mode, a.opt_str("text")?, a.opt_str("background")?, a.opt_bool("only_black")?, a.opt_bool("line_art")?)
+            .map_err(ToolError::InvalidArgs)?;
+        if self.session.set_reading_colors(id, colors) {
+            // Cached renderers baked the old setting into their config; page_render must re-read it.
+            self.renderers.remove(&id);
+        }
+        Ok(json!({
+            "mode": colors.mode_name(),
+            "text": colors.text_hex(),
+            "background": colors.background_hex(),
+            "only_black": colors.params.is_some_and(|p| p.only_black),
+            "line_art": colors.params.is_some_and(|p| p.line_art),
+        }))
+    }
+}

crates/automation/src/redact.rs

@@ -54,6 +54,11 @@ impl Automation {
         if chosen.iter().filter(|c| **c).count() != 1 {
             return Err(ToolError::InvalidArgs("pass exactly one of rect (with page), find, words, pattern or whole_pages: true".into()));
         }
+        let case_sensitive = a.opt_bool("case_sensitive")?.unwrap_or(false);
+        let whole_words = a.opt_bool("whole_words")?.unwrap_or(false);
+        if (case_sensitive || whole_words) && a.get("find").is_none() && a.get("words").is_none() {
+            return Err(ToolError::InvalidArgs("case_sensitive and whole_words apply only to find or words".into()));
+        }
         // Per searched word or phrase: how many marks it made.
         let mut matched_words: Vec<(String, usize)> = Vec::new();
         if a.get("rect").is_some() {
@@ -95,7 +100,11 @@ impl Automation {
             for (&p, text) in pages.iter().zip(&texts) {
                 let hits: Vec<(Option<usize>, _)> = match pattern {
                     Some(pat) => text.find_with(|chars| find_pattern(pat, chars)).into_iter().map(|h| (None, h)).collect(),
-                    None => needles.iter().enumerate().flat_map(|(i, w)| text.find(w).into_iter().map(move |h| (Some(i), h))).collect(),
+                    None => needles
+                        .iter()
+                        .enumerate()
+                        .flat_map(|(i, w)| text.find_opts(w, case_sensitive, whole_words).into_iter().map(move |h| (Some(i), h)))
+                        .collect(),
                 };
                 for (word, h) in hits {
                     let quads: Vec<[f64; 8]> = text.line_rects(h).into_iter().map(|r| info.pages[p].view_rect_to_quad(r)).collect();

crates/automation/src/signing.rs

@@ -214,6 +214,14 @@ impl Automation {
         }
         if let Some(text) = o.get("text") {
             let text = text.as_str().ok_or_else(|| bad("graphic.text must be a string"))?;
+            // Nobody sees a preview here: refuse what the script font and its fallback would leave out.
+            if let Some(c) = pdfcraft_engine::script_missing(text) {
+                return Err(bad(format!(
+                    "the signature script font can't draw \"{}\" (U+{:04X}) in graphic.text; type it in Latin, Cyrillic or Greek letters, or pass graphic.image instead",
+                    c.escape_debug(),
+                    u32::from(c)
+                )));
+            }
             return pdfcraft_engine::typed_signature_graphic(text).ok_or_else(|| {
                 bad(format!(
                     "graphic.text {text:?} has nothing the script font can draw (at most {} characters)",

crates/automation/src/text_cache.rs

@@ -0,0 +1,177 @@
+//! Bounded, session-wide page-text reuse. Active tool results own their Arcs independently.
+
+use std::collections::{BTreeMap, HashMap};
+use std::sync::{Arc, Weak};
+
+use pdfcraft_engine::DocId;
+use pdfcraft_render::{PageText, TextGlyph};
+
+const BYTE_BUDGET: usize = 64 * 1024 * 1024;
+// Also bound bookkeeping for documents with thousands of empty pages.
+const PAGE_BUDGET: usize = 4096;
+type Key = (DocId, usize);
+
+struct Cached {
+    version: Weak<Vec<u8>>,
+    text: Arc<PageText>,
+    bytes: usize,
+    stamp: u64,
+}
+
+pub(super) struct TextCache {
+    pages: HashMap<Key, Cached>,
+    order: BTreeMap<u64, Key>,
+    clock: u64,
+    bytes: usize,
+    budget: usize,
+}
+
+impl Default for TextCache {
+    fn default() -> Self {
+        Self::new(BYTE_BUDGET)
+    }
+}
+
+impl TextCache {
+    pub(super) fn new(budget: usize) -> Self {
+        Self { pages: HashMap::new(), order: BTreeMap::new(), clock: 0, bytes: 0, budget }
+    }
+
+    pub(super) fn prepare(&mut self, id: DocId, bytes: &Arc<Vec<u8>>) {
+        let version = Arc::downgrade(bytes);
+        // At most PAGE_BUDGET entries, independent of the document's page count. Weak pointers
+        // distinguish revisions without keeping an obsolete PDF byte buffer alive.
+        let stale: Vec<_> = self.pages.iter().filter(|(key, page)| key.0 == id && !page.version.ptr_eq(&version)).map(|(key, _)| *key).collect();
+        for key in stale {
+            self.remove_page(key);
+        }
+    }
+
+    pub(super) fn remove(&mut self, id: &DocId) {
+        let keys: Vec<_> = self.pages.keys().filter(|key| key.0 == *id).copied().collect();
+        for key in keys {
+            self.remove_page(key);
+        }
+    }
+
+    fn remove_page(&mut self, key: Key) {
+        if let Some(page) = self.pages.remove(&key) {
+            self.order.remove(&page.stamp);
+            self.bytes -= page.bytes;
+        }
+    }
+
+    fn stamp(&mut self) -> u64 {
+        if self.clock == u64::MAX {
+            self.pages.clear();
+            self.order.clear();
+            self.bytes = 0;
+            self.clock = 0;
+        }
+        self.clock += 1;
+        self.clock
+    }
+
+    pub(super) fn get(&mut self, id: DocId, page: usize) -> Option<Arc<PageText>> {
+        let stamp = self.stamp();
+        let entry = self.pages.get_mut(&(id, page))?;
+        self.order.remove(&entry.stamp);
+        entry.stamp = stamp;
+        self.order.insert(stamp, (id, page));
+        Some(entry.text.clone())
+    }
+
+    pub(super) fn insert(&mut self, id: DocId, page: usize, version: &Arc<Vec<u8>>, text: Arc<PageText>) {
+        let bytes = retained_bytes(&text);
+        self.remove_page((id, page));
+        // An oversized page is usable by this call, but never retained by the cache.
+        if bytes > self.budget {
+            return;
+        }
+        while self.bytes > self.budget - bytes || self.pages.len() >= PAGE_BUDGET {
+            let Some((_, key)) = self.order.first_key_value() else { break };
+            self.remove_page(*key);
+        }
+        let stamp = self.stamp();
+        self.pages.insert((id, page), Cached { version: Arc::downgrade(version), text, bytes, stamp });
+        self.order.insert(stamp, (id, page));
+        self.bytes += bytes;
+    }
+
+    #[cfg(test)]
+    pub(super) fn len(&self) -> usize {
+        self.pages.len()
+    }
+
+    #[cfg(test)]
+    pub(super) fn bytes(&self) -> usize {
+        self.bytes
+    }
+}
+
+// Estimate owned allocations, including spare capacity; bookkeeping has its own page-count cap.
+fn retained_bytes(text: &PageText) -> usize {
+    let arrays = std::mem::size_of::<PageText>()
+        .saturating_add(2 * std::mem::size_of::<usize>())
+        .saturating_add(text.glyphs.capacity().saturating_mul(std::mem::size_of::<TextGlyph>()))
+        .saturating_add(text.line_of.capacity().saturating_mul(std::mem::size_of::<u32>()))
+        .saturating_add(text.space_before.capacity().saturating_mul(std::mem::size_of::<bool>()));
+    text.glyphs.iter().fold(arrays, |sum, glyph| sum.saturating_add(glyph.text.capacity()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn budget_counts_owned_capacity_and_lru_is_shared_across_documents() {
+        let mut text = PageText::default();
+        text.glyphs.reserve(32);
+        text.line_of.reserve(48);
+        text.space_before.reserve(64);
+        let mut word = String::with_capacity(1000);
+        word.push('a');
+        text.glyphs.push(TextGlyph { text: word, rect: [0.0; 4], quad: [[0.0; 2]; 4], direction: [1.0, 0.0] });
+        let cost = retained_bytes(&text);
+        assert!(cost >= 32 * std::mem::size_of::<TextGlyph>() + 48 * 4 + 64 + 1000);
+        let text = Arc::new(text);
+        let version = Arc::new(vec![1]);
+        let mut cache = TextCache::new(cost * 2);
+        cache.insert(DocId(1), 0, &version, text.clone());
+        cache.insert(DocId(2), 0, &version, text.clone());
+        assert!(Arc::ptr_eq(&cache.get(DocId(1), 0).unwrap(), &text));
+        cache.insert(DocId(3), 0, &version, text.clone());
+        assert!(cache.get(DocId(2), 0).is_none(), "least recently used page in another document is evicted");
+        assert_eq!(cache.bytes, 2 * cost);
+        cache.insert(DocId(1), 0, &version, text.clone());
+        assert_eq!(cache.bytes, 2 * cost, "replacement does not double-count");
+        let next_version = Arc::new(vec![1]);
+        cache.prepare(DocId(1), &next_version);
+        assert!(cache.get(DocId(1), 0).is_none(), "equal bytes in a new Arc are a new version");
+        assert_eq!(cache.bytes, cost);
+        cache.remove(&DocId(3));
+        assert_eq!((cache.bytes, cache.len(), cache.order.len()), (0, 0, 0));
+        assert_eq!(Arc::strong_count(&version), 1, "the cache never retains a PDF byte buffer");
+    }
+
+    #[test]
+    fn oversized_pages_bypass_cache_and_empty_pages_have_a_bookkeeping_limit() {
+        let text = Arc::new(PageText::default());
+        let version = Arc::new(vec![]);
+        let cost = retained_bytes(&text);
+        let mut tiny = TextCache::new(cost - 1);
+        tiny.insert(DocId(1), 0, &version, text.clone());
+        assert_eq!((tiny.bytes, tiny.len()), (0, 0));
+        let mut cache = TextCache::default();
+        for page in 0..PAGE_BUDGET + 50 {
+            cache.insert(DocId(1), page, &version, text.clone());
+        }
+        assert_eq!(cache.len(), PAGE_BUDGET);
+        assert!(cache.get(DocId(1), 0).is_none());
+        assert!(cache.get(DocId(1), PAGE_BUDGET + 49).is_some());
+        assert_eq!(cache.bytes, PAGE_BUDGET * cost);
+        cache.clock = u64::MAX;
+        cache.insert(DocId(2), 0, &version, text);
+        assert_eq!((cache.bytes, cache.len()), (cost, 1), "recency counter rollover safely clears old state");
+    }
+}

crates/automation/src/tools.rs

@@ -118,6 +118,17 @@ pub fn tools() -> Vec<ToolDef> {
     let save_out = json!({ "type": "string", "description": "File to write. Omit to open the result as a new unsaved document instead." });
     let open = json!({ "type": "boolean", "description": "Also open the result as a new document (default: only when out is omitted)." });
     vec![
+        t("doc_batch", "Process files and folders", "Run convert, ocr and/or optimize over files and folders, one file at a time. recursive defaults to false. Preserve paths relative to each selected folder inside out_dir; duplicate inputs run once. Skip unsupported files, links and the output subtree. Existing outputs receive numbered names and are never replaced. Continue after per-file errors unless stop_on_error is true. Return completed/failed/skipped counts and per-file results. Discovery is bounded to 10000 entries and 64 folder levels. Convert must be first; each step can appear once. OCR uses installed models. Optimize uses Reduce File Size settings, optionally overriding target ppi (threshold 1.5 times ppi) and JPEG quality; a larger candidate keeps the original bytes. Sources and open documents are unchanged.")
+            .with(schema(json!({
+                "paths": {"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000},
+                "out_dir": {"type":"string"},
+                "steps": {"type":"array","items":{"type":"string","enum":["convert","ocr","optimize"]},"minItems":1,"maxItems":3,"uniqueItems":true},
+                "recursive": {"type":"boolean"}, "stop_on_error": {"type":"boolean"},
+                "ppi": {"type":"number","minimum":9,"maximum":1600},
+                "quality": {"type":"integer","minimum":1,"maximum":100},
+                "dpi": {"type":"number","minimum":72,"maximum":600},
+                "language": {"type":"string"}, "skip_text_pages": {"type":"boolean"}
+            }), &["paths","out_dir","steps"])),
         t("doc_open", "Open a PDF", "Open a PDF file and return its document id, page count and whether it can be edited.")
             .cmd("file.open")
             .with(schema(json!({ "path": { "type": "string" }, "password": { "type": "string", "description": "User or owner password for encrypted files." } }), &["path"])),
@@ -145,11 +156,13 @@ pub fn tools() -> Vec<ToolDef> {
             }),
             &["doc"],
         )),
-        t("doc_set_info", "Set document metadata", "Set a document information entry such as Title, Author, Subject or Keywords. Undoable.")
+        t("doc_set_info", "Set document metadata", "Set a document information entry such as Title, Author, Subject or Keywords; an empty value removes it. When the file has XMP metadata, the matching XMP property (dc:title, dc:creator, dc:description, pdf:Keywords, xmp:CreatorTool, pdf:Producer) is changed too, so viewers that read XMP first show the new value. Undoable.")
             .with(schema(json!({ "doc": doc(), "key": { "type": "string" }, "value": { "type": "string" } }), &["doc", "key", "value"])),
         t("page_render", "Render a page", "Render one page to a PNG image (default 96 dpi, at most 600).")
             .ro()
-            .with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "dpi": { "type": "number", "minimum": 1, "maximum": 600 } }), &["doc", "page"])),
+            .with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "dpi": { "type": "number", "minimum": 1, "maximum": 600 },
+                "hide_text_block": { "type": "integer", "minimum": 1, "description": "Render an inline editor background without this paragraph (index from text_paragraphs). Does not modify the document." }
+            }), &["doc", "page"])),
         t("object_list", "List editable objects", "List existing paragraphs, Image/Form artwork and added content once, with source kind/index references, displayed rectangles and document generation. Indexes change when content changes; use generation in object_move to reject stale references.")
             .ro().with(schema(json!({"doc":doc(),"page":{"type":"integer","minimum":1}}), &["doc","page"])),
         t("object_move", "Move objects together", "Atomically translate 1–1000 mixed references from object_list by [dx, dy] in displayed points (right/down). Preserves glyph codes, fonts, image data and relative spacing; success is one undo step. Clipping and vertical text are refused. A bad/stale reference refuses the entire move.")
@@ -168,10 +181,10 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc"],
             )),
-        t("text_find", "Find text", "Find a phrase (case-insensitive, whitespace-normalised) and return each match, in page order, with its page and line rectangles in points (origin top-left). Pages are read only until the limit is reached.")
+        t("text_find", "Find text", "Find a phrase (case-insensitive, whitespace-normalised) and return matches in page order with page and line rectangles in points (origin top-left). Reads growing batches, looking one match past the limit for a continuation. Failed pages do not discard readable matches: warnings contains up to 100 {page, error, error_truncated} entries (errors capped at 1024 UTF-8 bytes), warning_count counts failed pages, and warnings_truncated reports a capped list. complete is false after a page failure or when more matches exist; next is present only for a match-limit continuation.")
             .ro()
             .cmd("edit.find")
-            .with(schema(json!({ "doc": doc(), "query": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum matches (default 500). The search stops once it has this many; `complete` says whether every match was returned, and when it is false `next` holds the start_page and skip that continue the search." },
+            .with(schema(json!({ "doc": doc(), "query": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum matches (default 500). When another match exists, next holds start_page and skip to continue. complete is false for either additional matches or failed pages; an exhausted search with warnings has no next." },
                 "start_page": { "type": "integer", "minimum": 1, "description": "Page to start searching from (default 1)." },
                 "skip": { "type": "integer", "minimum": 0, "description": "Matches to pass over on start_page before returning any (default 0)." } }), &["doc", "query"])),
         t("page_rotate", "Rotate pages", "Rotate pages by a multiple of 90 degrees (positive is clockwise): the listed pages (default all), filtered like Acrobat's Rotate Pages by subset (all, even, odd page numbers) and orientation (all, landscape, portrait). Undoable.")
@@ -219,7 +232,7 @@ pub fn tools() -> Vec<ToolDef> {
                 json!({ "doc": doc(), "pages": pages("to extract"), "out": save_out.clone(), "open": open.clone(), "separate": { "type": "boolean" }, "out_dir": { "type": "string" }, "delete": { "type": "boolean" } }),
                 &["doc", "pages"],
             )),
-        t("doc_combine", "Combine files", "Combine files, in order, into one PDF (bookmarks are kept under one entry per file). Images (PNG, JPEG, TIFF, GIF, BMP, JPEG 2000) and .txt files are made into PDFs first. pages optionally chooses each file's pages, in step with paths: a range such as \"1-3, 6\" or null for all pages. passwords, also in step with paths, opens encrypted files (the open password, or the permissions password where a file's security doesn't allow copying pages; null for none). The result is not encrypted. Passwords are never echoed back. groups, also in step with paths, splits a file around others: entries with the same number (they must name the same path) are one file, copied once, so it keeps one bookmark at its first page, its links and its form fields; null for a file of its own. A group uses its first entry's password.")
+        t("doc_combine", "Combine files", "Combine files, in order, into one PDF (bookmarks are kept under one entry per file). Images (PNG, JPEG, TIFF, GIF, BMP, JPEG 2000) and .txt files are made into PDFs first. pages optionally chooses each file's pages, in step with paths: a range such as \"1-3, 6\" or null for all pages. passwords, also in step with paths, opens encrypted files (the open password, or the permissions password where a file's security doesn't allow copying pages; null for none). The result is not encrypted. Passwords are never echoed back. groups, also in step with paths, splits a file around others: entries with the same number (they must name the same path) are one file, copied once, so it keeps one bookmark at its first page, its links and its form fields; null for a file of its own. A group uses its first entry's password. When two files' forms name the same field, field_conflicts says what happens: \"rename\" (the default) keeps the fields separate by renaming the later one (Text1 becomes Text1-1) and the result lists renamed_fields as [[old, new], …] — scripts that refer to the old name are not rewritten; \"merge\" makes them one field, as before.")
             .cmd("page.combine")
             .with(schema(
                 json!({
@@ -227,6 +240,7 @@ pub fn tools() -> Vec<ToolDef> {
                     "pages": { "type": "array", "items": { "type": ["string", "null"] } },
                     "passwords": { "type": "array", "items": { "type": ["string", "null"] } },
                     "groups": { "type": "array", "items": { "type": ["integer", "null"], "minimum": 0 } },
+                    "field_conflicts": { "type": "string", "enum": ["rename", "merge"] },
                     "out": save_out,
                     "open": open,
                 }),
@@ -303,7 +317,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "form_fill",
             "Fill in form fields",
-            "Set several fields at once (one undo step). values maps field names (from form_fields) to: a string for text fields, combo boxes and radio groups (an option), true/false for check boxes, an array of strings for multi-select lists. Appearances are regenerated so every viewer shows the values.",
+            "Set several fields at once (one undo step). values maps field names (from form_fields) to: a string for text fields, combo boxes and radio groups (an option), true/false for check boxes, an array of strings for multi-select lists. Appearances are regenerated so every viewer shows the values. A value whose characters the field's font can't draw (Chinese in a Helvetica field) is still saved; `warnings` in the result names the field and character: PdfCraft draws `?` there and asks other viewers to redraw the field from its value.",
         )
         .with(schema(json!({ "doc": doc(), "values": { "type": "object", "description": "Field name → value." } }), &["doc", "values"])),
         t("form_reset", "Clear form", "Reset fields to their default values: all of them, or only those listed. Undoable.")
@@ -345,7 +359,7 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc", "page", "path", "at"],
             )),
-        t("form_set_image", "Set an image field's picture", "Show an image file (PNG, JPEG, TIFF, GIF or BMP) in an image field or button, scaled to fit and centred (what clicking an image field does). Undoable.")
+        t("form_set_image", "Set an image field's picture", "Show an image file (PNG, JPEG, TIFF, GIF or BMP) in an image field or button, scaled to fit and centred (what clicking an image field does). On an XFA form the picture is kept in its data too (base64, as Designer saves it) and the form shows it from there. Undoable.")
             .with(schema(json!({ "doc": doc(), "field": { "type": "string" }, "path": { "type": "string" } }), &["doc", "field", "path"])),
         t(
             "form_set_props",
@@ -388,10 +402,10 @@ pub fn tools() -> Vec<ToolDef> {
                 json!({ "doc": doc(), "order": { "type": "string", "enum": ["row", "column", "structure", "annotations"] }, "pages": pages("to set (default: all)"), "field": { "type": "string" }, "move": { "type": "string", "enum": ["earlier", "later"] } }),
                 &["doc"],
             )),
-        t("doc_export_data", "Export comments or form data", "Write comments and/or form data to path; the extension picks the format: .xfdf or .fdf (comments and/or fields), .xml, .csv or .txt (form data). what: all (default), comments, fields.")
+        t("doc_export_data", "Export comments or form data", "Write comments and/or form data to path; the extension picks the format: .xfdf or .fdf (comments and/or fields), .xml, .csv or .txt (form data). For an XFA form, .xml is its data alone (rooted at the form's root data node, as Acrobat exports it) and .xdp an XML Data Package holding the whole datasets. what: all (default), comments, fields.")
             .destructive()
             .with(schema(json!({ "doc": doc(), "path": { "type": "string" }, "what": { "type": "string", "enum": ["all", "comments", "fields"] } }), &["doc", "path"])),
-        t("doc_import_data", "Import comments or form data", "Import comments and/or field values from an XFDF, FDF, XML, CSV or tab-delimited text file (detected from its content). Comments with the same name are replaced; values go through the form's formats and validation. Undoable.")
+        t("doc_import_data", "Import comments or form data", "Import comments and/or field values from an XFDF, FDF, XML, CSV or tab-delimited text file (detected from its content). Comments with the same name are replaced; values go through the form's formats and validation. For an XFA form, an XDP, datasets or data XML file replaces the form's data: a laid-out form is laid out again from it (rows included) and its calculations run. Undoable.")
             .with(schema(json!({ "doc": doc(), "path": { "type": "string" } }), &["doc", "path"])),
         t("form_delete_field", "Delete a field", "Delete a form field and all its widgets. Undoable.")
             .destructive()
@@ -399,7 +413,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "redact_mark",
             "Mark for redaction",
-            "Mark content for redaction (nothing is removed until redact_apply). One of: rect [x0, y0, x1, y1] (points from the top-left of the displayed page) with page; find (text, every match); words (a list of words or phrases, every match of each; the result's matched_words says how many marks each made); pattern (phone, email, credit-card, ssn, date: every match, Acrobat's Search & Redact patterns); whole_pages: true. find, words, pattern and whole_pages work on pages (default all). overlay: text shown on the box once applied, or code_set (foia: U.S. FOIA (b)(1)(A)…(b)(9); privacy-act: U.S. Privacy Act (d)(5), (j)(1)…(k)(7)) with codes, shown as \"(b)(6), (b)(7)(C)\"; fill: box colour (default black). Undoable.",
+            "Mark content for redaction (nothing is removed until redact_apply). One of: rect [x0, y0, x1, y1] (points from the top-left of the displayed page) with page; find (text, every match); words (a list of words or phrases, every match of each; the result's matched_words says how many marks each made); pattern (phone, email, credit-card, ssn, date: every match, Acrobat's Search & Redact patterns); whole_pages: true. find and words accept case_sensitive and whole_words (both default false). find, words, pattern and whole_pages work on pages (default all). overlay: text shown on the box once applied, or code_set (foia: U.S. FOIA (b)(1)(A)…(b)(9); privacy-act: U.S. Privacy Act (d)(5), (j)(1)…(k)(7)) with codes, shown as \"(b)(6), (b)(7)(C)\"; fill: box colour (default black). Undoable.",
         )
         .with(schema(
             json!({
@@ -408,6 +422,8 @@ pub fn tools() -> Vec<ToolDef> {
                 "rect": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 },
                 "find": { "type": "string", "minLength": 1 },
                 "words": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 1000 },
+                "case_sensitive": { "type": "boolean", "description": "Match letter case for find or words (default false)." },
+                "whole_words": { "type": "boolean", "description": "Match whole words for find or words (default false)." },
                 "pattern": { "type": "string", "enum": ["phone", "email", "credit-card", "ssn", "date"] },
                 "whole_pages": { "type": "boolean" },
                 "pages": pages("to search or mark (default: all)"),
@@ -545,6 +561,11 @@ pub fn tools() -> Vec<ToolDef> {
         t("link_list", "List links", "Every link: page, 1-based index (for link_edit/link_delete), rect (points from the top-left of the page), and where it goes (url or to_page).")
             .ro()
             .with(schema(json!({ "doc": doc() }), &["doc"])),
+        t("link_open", "Open a linked PDF", "Follow a local GoToR link in PdfCraft: open the referenced PDF as a new document, respecting --root. page and index use link_list numbering. Named destinations are reported but not applied. Absolute file specifications require allow_absolute: true after reviewing the target; relative links need no opt-in.")
+            .with(schema(
+                json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "index": { "type": "integer", "minimum": 1 }, "password": { "type": "string", "description": "Optional password for the linked PDF." }, "allow_absolute": { "type": "boolean", "description": "Explicitly allow an absolute local GoToR target (default false). Existing validation and --root confinement still apply." } }),
+                &["doc", "page", "index"],
+            )),
         t("link_add", "Add a link", "Add a link over rect on page that opens url or goes to to_page. Appearance: visible (rectangle), color, width 1-3, highlight none/invert/outline/inset. Undoable.")
             .cmd("edit.link")
             .with(schema(
@@ -571,10 +592,10 @@ pub fn tools() -> Vec<ToolDef> {
         t("links_from_urls", "Create links from URLs", "Find web addresses (http://, https://, www.) in the text of every page and make them clickable links. Returns the URLs. Undoable.")
             .cmd("edit.links_from_urls")
             .with(schema(json!({ "doc": doc() }), &["doc"])),
-        t("links_remove", "Remove all links", "Remove every link in the document. Undoable.")
+        t("links_remove", "Remove all links", "Remove every link in the document (or on the given pages). Undoable.")
             .destructive()
             .cmd("edit.remove_links")
-            .with(schema(json!({ "doc": doc() }), &["doc"])),
+            .with(schema(json!({ "doc": doc(), "pages": pages("whose links to remove (default: all)") }), &["doc"])),
         t("measure_distance", "Measure distance", "Add an undoable two-point distance annotation using the scale of the first point's viewport.")
             .cmd("measure.distance").with(measure_schema()),
         t("measure_perimeter", "Measure perimeter", "Add an undoable connected-line length annotation. To include a closing edge, repeat the first point at the end.")
@@ -600,7 +621,7 @@ pub fn tools() -> Vec<ToolDef> {
             "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`. 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.",
+             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. Text a text box, callout or stamp draws in the standard fonts that they can't draw (Chinese, Greek) is saved as typed and drawn as `?`; `warnings` in the result says so.",
         )
         .with(schema(
             json!({
@@ -709,6 +730,19 @@ pub fn tools() -> Vec<ToolDef> {
         t("comments_hide", "Hide all comments", "Hide or show every comment on the page (fields and links still draw). A view setting: the file doesn't change.")
             .cmd("comment.hide_all")
             .with(schema(json!({ "doc": doc(), "hidden": { "type": "boolean", "description": "Default true." } }), &["doc"])),
+        t("view_reading_colors", "Set reading colours", "Set the document's reading colours (Acrobat's Replace Document Colors, in the Reading Options): solid text and line-art paints are remapped for readability and the page clears to the background colour in page_render. A view setting: the file doesn't change. mode is one of: off, black-on-white, white-on-black, yellow-on-black, green-on-black, or custom (which takes text and background as #RRGGBB). only_black maps only near-black paints (default false) and line_art also maps line-art paints (default true); both override the mode's preset. A flag that differs from the mode's preset default makes the returned mode read custom, because the resulting params no longer match any preset. Returns the resulting setting.")
+            .cmd("a11y.reading_options")
+            .with(schema(
+                json!({
+                    "doc": doc(),
+                    "mode": { "type": "string", "enum": ["off", "black-on-white", "white-on-black", "yellow-on-black", "green-on-black", "custom"] },
+                    "text": { "type": "string", "description": "With mode custom: the text colour, #RRGGBB." },
+                    "background": { "type": "string", "description": "With mode custom: the background colour, #RRGGBB." },
+                    "only_black": { "type": "boolean", "description": "Map only near-black paints. Default false." },
+                    "line_art": { "type": "boolean", "description": "Also map line-art paints. Default true." },
+                }),
+                &["doc", "mode"],
+            )),
         t("comments_summarize", "Summarize comments", "Make a PDF summarising every comment (number, author, type, date, text, replies), sorted by page, author, date or type.")
             .cmd("comment.summarize")
             .with(schema(
@@ -839,7 +873,12 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc", "folder"],
             )),
-        t("accessibility_check", "Check for accessibility", "Run the Accessibility Checker's full check (32 rules in 7 categories: document, page_content, forms, alternate_text, tables, lists, headings). Each rule is passed, failed (with findings and pages), manual (needs a person) or skipped. Colour contrast is off unless all is true; rules (ids such as tagged-pdf, figures-alt-text) or categories narrow the check; pages limit the page rules.")
+        t("accessibility_autotag_preview", "Preview automatic tags", "Propose paragraph and heading tags for visible text blocks on one page. Returns page bounds, tentative roles and reasons. Does not change the PDF or claim accessibility compliance. Images, tables, lists, annotations and existing structure require separate review.")
+            .ro()
+            .with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 } }), &["doc", "page"])),
+        t("accessibility_autotag_apply", "Automatically tag text-only PDF", "Write marked content, a Document structure element, paragraph tags and a parent tree for every text object in an untagged, text-only PDF. Refuses graphics, images, annotations, forms, existing tags and malformed streams before changing anything. Review all resulting roles; this does not certify accessibility. Undoable.")
+            .with(schema(json!({ "doc": doc() }), &["doc"])),
+        t("accessibility_check", "Check for accessibility", "Run the Accessibility Checker's full check (32 rules in 7 categories: document, page_content, forms, alternate_text, tables, lists, headings). Each rule is passed, failed (with findings and pages), manual (needs a person) or skipped. Findings on locatable figures, annotations and form widgets include bbox_user_space in PDF coordinates. Colour contrast is off unless all is true; rules (ids such as tagged-pdf, figures-alt-text) or categories narrow the check; pages limit the page rules.")
             .ro()
             .cmd("a11y.check")
             .with(schema(
@@ -866,6 +905,34 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc", "path"],
             )),
+        t("accessibility_review_record", "Accessibility review record", "Compare the same accessibility rules on two open versions of a PDF and write a JSON record to path. Includes document SHA-256 hashes, before/after rule statuses and finding counts, changed rules, and rules still needing review. Does not change either PDF or claim accessibility compliance. Open the original and edited copies as separate documents.")
+            .destructive()
+            .with(schema(
+                json!({
+                    "before": doc(),
+                    "after": doc(),
+                    "path": { "type": "string" },
+                    "all": { "type": "boolean", "description": "Include rules that are off by default (colour contrast)." },
+                }),
+                &["before", "after", "path"],
+            )),
+        t("accessibility_review_save", "Save accessibility review decisions", "Write a local JSON sidecar for an open PDF with rule-level human review decisions. The sidecar records the PDF SHA-256; replacing one tied to different bytes requires replace: true. Does not change the PDF or assert compliance.")
+            .destructive()
+            .with(schema(json!({ "doc": doc(), "path": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "decision": { "type": "string", "enum": ["accepted", "needs_work", "skipped"] }, "page": { "type": "integer", "minimum": 1 }, "note": { "type": "string" } }, "required": ["rule", "decision"], "additionalProperties": false } }, "replace": { "type": "boolean" } }), &["doc", "path", "decisions"])),
+        t("accessibility_review_load", "Open accessibility review decisions", "Read a local review sidecar only when its recorded SHA-256 matches the open PDF. Returns the decisions without changing the PDF.")
+            .ro()
+            .with(schema(json!({ "doc": doc(), "path": { "type": "string" } }), &["doc", "path"])),
+        t("accessibility_review_html", "Accessibility review summary", "Compare two open versions of a PDF and write a self-contained HTML summary of the same evidence as accessibility_review_record: document hashes, outcome counts, rule changes, and rules still requiring review. Does not change either PDF or claim accessibility compliance.")
+            .destructive()
+            .with(schema(
+                json!({
+                    "before": doc(),
+                    "after": doc(),
+                    "path": { "type": "string" },
+                    "all": { "type": "boolean", "description": "Include rules that are off by default (colour contrast)." },
+                }),
+                &["before", "after", "path"],
+            )),
         t("accessibility_fix", "Fix an accessibility problem", "Apply the checker's automatic fix for a rule: primary-language (value: the language, e.g. en-US), title (value: the title; default the current title or file name; also shows it in the title bar) or tab-order (every page tabs in structure order). Returns the rule's new status. Undoable.")
             .with(schema(json!({ "doc": doc(), "rule": { "type": "string", "enum": ["primary-language", "title", "tab-order"] }, "value": { "type": "string" } }), &["doc", "rule"])),
         t("accessibility_figures", "List figures", "The tagged figures (Figure elements, through the role map) in document order: figure number, page, alternate text and where the figure is drawn (top-left-origin points).")
@@ -875,6 +942,25 @@ pub fn tools() -> Vec<ToolDef> {
         t("accessibility_set_alt", "Set alternate text", "Set a figure's alternate text (alt; empty or omitted clears it), or mark it decorative (decorative: true: its content becomes an artifact and the figure leaves the tags). figure is a number from accessibility_figures. Returns the figures. Undoable.")
             .cmd("a11y.alt_text")
             .with(schema(json!({ "doc": doc(), "figure": { "type": "integer", "minimum": 1 }, "alt": { "type": "string" }, "decorative": { "type": "boolean" } }), &["doc", "figure"])),
+        t("accessibility_tags", "List structure tags", "List reachable indirect structure tags in document order with PDF object number, generation, nearest indirect parent, depth, page, type, title, actual text, alternate text and language. Inline tag dictionaries have no stable object reference and are not listed.")
+            .ro()
+            .cmd("a11y.tags")
+            .with(schema(json!({ "doc": doc() }), &["doc"])),
+        t("accessibility_set_tag_property", "Edit tag property", "Set or clear one property of a reachable indirect structure tag. Use object and generation from accessibility_tags. Properties: type, title, actual_text, alternate_text, language. Empty or omitted value clears text properties; type requires a nonempty PDF name. Undoable.")
+            .with(schema(json!({
+                "doc": doc(), "object": { "type": "integer", "minimum": 1 },
+                "generation": { "type": "integer", "minimum": 0, "maximum": 65535 },
+                "property": { "type": "string", "enum": ["type", "title", "actual_text", "alternate_text", "language"] },
+                "value": { "type": "string" },
+            }), &["doc", "object", "generation", "property"])),
+        t("accessibility_move_tag", "Move structure tag", "Move a reachable indirect structure tag before or after a direct sibling in their parent's /K array, changing tagged reading order without changing page appearance. Use object and generation values from accessibility_tags. Rejects distinct parents, duplicate references and positions that are already current. Undoable.")
+            .with(schema(json!({
+                "doc": doc(), "object": { "type": "integer", "minimum": 1 },
+                "generation": { "type": "integer", "minimum": 0, "maximum": 65535 },
+                "anchor": { "type": "integer", "minimum": 1 },
+                "anchor_generation": { "type": "integer", "minimum": 0, "maximum": 65535 },
+                "placement": { "type": "string", "enum": ["before", "after"] },
+            }), &["doc", "object", "generation", "anchor", "anchor_generation", "placement"])),
         t("form_merge_data", "Merge data files into spreadsheet", "Collect the field values of form data files (FDF, XFDF) or filled-in PDF forms into one CSV file at path: a column per field name, a row per file. Returns the row and column counts.")
             .cmd("form.merge_data")
             .with(schema(json!({ "paths": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "path": { "type": "string" } }), &["paths", "path"])),
@@ -897,13 +983,16 @@ pub fn tools() -> Vec<ToolDef> {
                 json!({ "doc": doc(), "field": { "type": "string" }, "event": { "type": "string", "enum": ["keystroke", "format", "validate", "calculate", "mouse_up"] }, "script": { "type": "string" } }),
                 &["doc", "field", "event"],
             )),
-        t("doc_export_office", "Export to Word, HTML or RTF", "Export a PDF ▸ Word (.docx), HTML (.html, one file with images inline) or RTF (.rtf), chosen by path's extension: paragraphs in reading order, headings from larger text, bold and italic, images where they fall, a page break between pages.")
+        t("doc_export_office", "Export to Word, PowerPoint, HTML or RTF", "Export a PDF ▸ Word (.docx), PowerPoint (.pptx, one slide per page), HTML (.html, one file with images inline) or RTF (.rtf), chosen by path's extension: text, headings, bold and italic. Word uses borderless inferred tables and positioned editable shapes on pages with artwork, rotated or large text; each source page retains its size. Font matching and vector graphics remain limited.")
             .cmd("export.docx")
             .with(schema(json!({ "doc": doc(), "path": { "type": "string" } }), &["doc", "path"])),
         t("pdfa_verify", "Verify PDF/A", "Standards ▸ Verify PDF/A compliance: the PDF/A-2b or 3b rules the document breaks (ISO 19005 clause, message, page, whether Save as PDF/A can fix it), plus what it declares.")
             .ro()
             .cmd("standards.pdfa")
             .with(schema(json!({ "doc": doc(), "level": { "type": "string", "enum": ["2b", "3b"], "description": "Default 2b." } }), &["doc"])),
+        t("print_readiness", "Print readiness", "Verification only. Reports effective image resolution where each image is drawn (not against the page size), page boxes and bleed past the trim, output intents, fonts that are not embedded, and the PDF/A-2b structural result. Does not modify the document, embed fonts, invent a press profile, or check PDF/X.")
+            .ro()
+            .with(schema(json!({ "doc": doc() }), &["doc"])),
         t("pdfa_convert", "Save as PDF/A", "Standards ▸ Save as PDF/A: fix what can be fixed for PDF/A-2b or 3b (XMP identification and metadata, an sRGB output intent, forbidden actions and JavaScript, annotation print flags, image interpolation, encryption). Returns what was fixed and what remains (e.g. fonts that aren't embedded). Undoable; save the document to keep it.")
             .cmd("standards.pdfa")
             .with(schema(json!({ "doc": doc(), "level": { "type": "string", "enum": ["2b", "3b"] } }), &["doc"])),
@@ -951,7 +1040,7 @@ pub fn tools() -> Vec<ToolDef> {
             )),
         t("js_enabled", "JavaScript on or off", "Preferences ▸ JavaScript ▸ Enable Acrobat JavaScript: set it with `enabled`, or read it. With JavaScript off, field scripts other than Acrobat's AF calls don't run.")
             .with(schema(json!({ "enabled": { "type": "boolean" } }), &[])),
-        t("ocr_recognize", "Recognize text (OCR)", "Scan & OCR ▸ Recognize text: render pages, read the words in them and add them as invisible text over the page image, so scanned pages become searchable and selectable (a searchable image; the image is not changed). Pages that already have text are skipped unless skip_text_pages is false. Returns each page's recognised text, word count or why it was skipped. Needs the OCR models (ocr_status). Undoable as one step.")
+        t("ocr_recognize", "Recognize text (OCR)", "Scan & OCR ▸ Recognize text: render pages, read the words in them and add them as invisible text over the page image, so scanned pages become searchable and selectable (a searchable image; the image is not changed). Pages that already have text are skipped unless skip_text_pages is false; then pictures on those pages are read too, and recognised words that the page's own text already has (an earlier OCR layer included) are left out and counted as already_on_page. Returns each page's recognised text, word count or why it was skipped. Needs the OCR models (ocr_status). Undoable as one step.")
             .cmd("ocr.recognize")
             .with(schema(
                 json!({
@@ -959,11 +1048,11 @@ pub fn tools() -> Vec<ToolDef> {
                     "pages": pages("to recognise (default: all)"),
                     "dpi": { "type": "number", "minimum": 72, "maximum": 600, "description": "Resolution pages are read at (default 300; a scanned page is read at most at its own resolution)." },
                     "language": { "type": "string", "enum": ["en"], "description": "Document language (default en)." },
-                    "skip_text_pages": { "type": "boolean", "description": "Leave pages that already contain text alone (default true)." },
+                    "skip_text_pages": { "type": "boolean", "description": "Leave pages that already contain text alone (default true). false also reads pictures on such pages, without adding their text again." },
                 }),
                 &["doc"],
             )),
-        t("ocr_recognize_files", "Recognize text in multiple files", "Scan & OCR ▸ Recognize text ▸ In multiple files: read every page of each PDF in paths and write the searchable result into folder under the same name (pages that already have text are left alone). Returns, per file, the output path, word count and skipped pages, or the error.")
+        t("ocr_recognize_files", "Recognize text in multiple files", "Scan & OCR ▸ Recognize text ▸ In multiple files: read every page of each PDF in paths and write the searchable result into folder under the same name (pages that already have text are left alone unless skip_text_pages is false, as in ocr_recognize). Returns, per file, the output path, word count and skipped pages, or the error.")
             .cmd("ocr.recognize_batch")
             .with(schema(
                 json!({
@@ -971,6 +1060,7 @@ pub fn tools() -> Vec<ToolDef> {
                     "folder": { "type": "string" },
                     "dpi": { "type": "number", "minimum": 72, "maximum": 600 },
                     "language": { "type": "string", "enum": ["en"] },
+                    "skip_text_pages": { "type": "boolean", "description": "Leave pages that already contain text alone (default true); see ocr_recognize." },
                 }),
                 &["paths", "folder"],
             )),
@@ -995,7 +1085,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "fill_sign_add",
             "Fill & Sign: type text or place a mark",
-            "Fill in a form that has no fields, as Acrobat's Fill & Sign does: type text (`text`, 10 pt), place a check, cross, dot or line, today's date (in Preferences ▸ Date format, see fill_sign_date_format, or `format`), or a signature or initials (either `text` drawn in a script font, or `path` to a local PNG/JPEG image up to 4 MiB and 32 megapixels, scaled down to 4 megapixels, preserving transparency). `at` [x, y] is in points from the top-left of the page: text's top-left, mark's centre, signature's left edge centred vertically. Image signatures fit within 150 pt wide and 32 pt tall (24 pt for initials). Creates movable, undoable annotations.",
+            "Fill in a form that has no fields, as Acrobat's Fill & Sign does: type text (`text`, default 10 pt; `font_size` 4–300 pt), place a check, cross, dot or line, today's date (in Preferences ▸ Date format, see fill_sign_date_format, or `format`; `font_size` also applies), or a signature or initials (either `text` drawn in a script font, or `path` to a local PNG/JPEG image up to 4 MiB and 32 megapixels, scaled down to 4 megapixels, preserving transparency; with `scan: true`, `path` is instead a photo of a signature on paper, within the same limits: the signature is found, and the paper, shadows and table around it are removed, with `sensitivity` 0–100, default 50, picking up fainter ink when higher). `at` [x, y] is in points from the top-left of the page: text's top-left, mark's centre, signature's left edge centred vertically. Image signatures fit within 150 pt wide and 32 pt tall (24 pt for initials). Creates movable, undoable annotations. Typed text the standard fonts can't draw is saved and drawn as `?` (`warnings` in the result says so); a typed signature neither the script font nor its fallback can draw is refused (pass `path` instead).",
         )
         .cmd("sign.fill.text")
         .with(schema(
@@ -1005,7 +1095,10 @@ pub fn tools() -> Vec<ToolDef> {
                 "type": { "type": "string", "enum": ["text", "check", "cross", "dot", "line", "date", "signature", "initials"] },
                 "at": point(),
                 "text": { "type": "string", "minLength": 1 },
+                "font_size": { "type": "number", "minimum": 4, "maximum": 300, "description": "For type text or date (default 10 pt)." },
                 "path": { "type": "string", "description": "PNG or JPEG for signature/initials; pass either path or text." },
+                "scan": { "type": "boolean", "description": "With path: scan a photo of a signature on paper (default false)." },
+                "sensitivity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "With scan: how faint ink may be, 0–100 (default 50)." },
                 "format": { "type": "string", "description": "For type date: this pattern instead of the date-format preference, e.g. \"dd.mm.yyyy\"." },
                 "language": { "type": "string", "description": "For type date: month and weekday names in this language code (see fill_sign_date_format) instead of the preference." },
                 "author": { "type": "string" },
@@ -1063,11 +1156,15 @@ pub fn tools() -> Vec<ToolDef> {
             .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. 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.")
+        t("image_hit", "Hit test page artwork", "List image/Form numbers whose placement and all clipping paths contain point [x,y] in top-left-origin points. Bezier curves, even-odd/nonzero fill and holes are respected. Read only.")
+            .ro()
+            .cmd("edit.edit_text")
+            .with(schema(json!({"doc":doc(),"page":{"type":"integer","minimum":1},"point":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}), &["doc","page","point"])),
+        t("page_images", "List page images", "The raster images and grouped Form artwork a page draws (Edit a PDF): number, full placement rect and visible_rect after page/path clipping (top-left-origin points; null if fully hidden), kind (image/form), pixel size ([0,0] for forms) and resource name. Forms include nested graphics and are edited as a whole. Numbers count forms and images together in drawing order, so a page with forms numbers its images differently than before forms were listed: always take numbers from a fresh page_images call.")
             .ro()
             .cmd("edit.edit_text")
             .with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 } }), &["doc", "page"])),
-        t("image_edit", "Edit an image", "Change one of a page's images (number from page_images): action move (rect: new box in top-left-origin points), rotate (quarters clockwise, default 1), flip_horizontal, flip_vertical, replace (path: an image file, drawn in the same place) or delete. Undoable. Form artwork supports move/resize/rotate/flip/delete as a group; replace and image_save only support raster images.")
+        t("image_edit", "Edit an image", "Change one of a page's images (number from page_images): action move (rect: new full placement box in top-left-origin points, based on page_images.rect), rotate (quarters clockwise, default 1), flip_horizontal, flip_vertical, replace (path: an image file, drawn in the same place) or delete. Undoable. The selected image crop transforms with its pixels, isolating shared path scopes while retaining neighboring painting. Text-outline clips return a clear error. Rotation/flip use the visible centre. Form artwork supports move/resize/rotate/flip/delete as a group; replace and image_save only support raster images.")
             .cmd("edit.edit_text")
             .with(schema(
                 json!({
@@ -1085,15 +1182,30 @@ pub fn tools() -> Vec<ToolDef> {
             .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"])),
-        t("text_paragraphs", "List paragraphs", "The paragraphs on a page (lines grouped by font, size, alignment and spacing): number, text, its line numbers, box (top-left-origin points), font and size. Use the number with text_edit's paragraph.")
+        t("text_font_files", "List installed document fonts", "Discover openly licensed, embeddable TrueType/OpenType files on request. Optional directories (at most 16) restrict the scan; with --root, only that root is scanned by default and supplied folders must stay inside it. The scan skips symlinks, collections and invalid/licence-restricted fonts, with depth, entry and byte budgets. Select a returned path with text_font_import.")
+            .ro().cmd("edit.edit_text")
+            .with(schema(json!({"directories":{"type":"array","items":{"type":"string"},"maxItems":16}}), &[])),
+        t("text_font_import", "Load document font", "Load an explicitly selected, openly licensed full TrueType/OpenType face into a page. The program's family, embedding permissions and licence declaration are validated. Completes source subsets of the same face without replacing existing glyphs. Returns a font resource usable with text_edit.font_resource. Undoable; respects root confinement. No system-interface fallback is exported.")
+            .cmd("edit.edit_text")
+            .with(schema(json!({"doc":doc(), "page":{"type":"integer","minimum":1}, "path":{"type":"string"}}), &["doc","page","path"])),
+        t("text_fonts", "List document fonts", "List validated embedded source faces and approved full preview faces for a page. Full registered resources can be selected by text_edit.font_resource; preview_only faces are not PDF resource names.")
+            .ro().cmd("edit.edit_text")
+            .with(schema(json!({"doc":doc(), "page":{"type":"integer","minimum":1}}), &["doc","page"])),
+        t("text_paragraphs", "List paragraphs", "The paragraphs on a page (adjacent source runs grouped into aligned visual rows, including mixed fonts, sizes and colours): number, text, editor_text (visual rows separated by newlines), rows and source line numbers, box (top-left-origin points), font and size. Use the number with text_edit's paragraph.")
             .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 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.")
+        t("text_edit_layout", "Measure text draft", "Measure a paragraph draft using the same PDF rewrite as Apply, without changing the document. Returns source_rect, draft_rect (top-left-origin points), overflow, and the embedded sfnt source faces available to the inline editor. Text defaults to the unchanged paragraph. Optional size, width, font_resource and disjoint UTF-8 ranges preview formatting changes.")
+            .ro()
+            .cmd("edit.edit_text")
+            .with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "paragraph": { "type": "integer", "minimum": 1 }, "text": { "type": "string" }, "size": { "type": "number" }, "width": { "type": "number" }, "font_resource":{"type":"string"}, "ranges":{"type":"array","maxItems":1024,"items":{"type":"object"}} }), &["doc", "page", "paragraph"])),
+        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 mixed-style region, editor_text supplies visual row breaks; surviving text keeps its source-run styles and inserted text inherits the surrounding run. 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 },
                     "paragraph": { "type": "integer", "minimum": 1 },
+                    "font_resource": { "type": "string", "description": "Explicit source/full page font resource from text_fonts or text_font_import." },
+                    "ranges": { "type": "array", "maxItems": 1024, "items": { "type": "object", "properties": {"range":{"type":"array","items":{"type":"integer","minimum":0},"minItems":2,"maxItems":2},"font":{"type":"string","enum":["helvetica","times","courier"]},"bold":{"type":"boolean"},"italic":{"type":"boolean"},"font_resource":{"type":"string"},"size":{"type":"number","exclusiveMinimum":0},"color":{"type":"string"},"underline":{"type":"boolean"},"char_spacing":{"type":"number"},"scale":{"type":"number"}},"required":["range"]}, "description":"Disjoint UTF-8 byte ranges in replacement text; unspecified source formatting survives." },
                     "text": { "type": "string" },
                     "font": { "type": "string", "enum": ["helvetica", "times", "courier"] },
                     "bold": { "type": "boolean" },

crates/automation/tests/batch.rs

@@ -0,0 +1,230 @@
+use pdfcraft_automation::{Automation, Content};
+use pdfcraft_engine::Session;
+use serde_json::{Value, json};
+
+fn result(auto: &mut Automation, args: Value) -> Value {
+    match auto.call("doc_batch", &args).unwrap().remove(0) {
+        Content::Json(value) => value,
+        _ => panic!("expected a report"),
+    }
+}
+
+// Fresh fixtures include the current timestamp; retain their bytes for output comparisons.
+fn pdf() -> Vec<u8> {
+    Session::new().create_from_text("Original", "Original text").unwrap().as_ref().clone()
+}
+
+#[test]
+fn batch_recurses_preserves_paths_continues_errors_and_never_replaces_outputs() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join("input/sub")).unwrap();
+    std::fs::create_dir_all(dir.path().join("input/output/sub")).unwrap();
+    std::fs::write(dir.path().join("input/a.txt"), "Hello").unwrap();
+    std::fs::write(dir.path().join("input/b.pdf"), b"broken").unwrap();
+    std::fs::write(dir.path().join("input/sub/a.txt"), "World").unwrap();
+    std::fs::write(dir.path().join("input/notes.bin"), b"ignore").unwrap();
+    std::fs::write(dir.path().join("input/output/sub/a.pdf"), b"precious").unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let args = json!({"paths":["input","input/a.txt"],"steps":["convert","optimize"],"out_dir":"input/output","recursive":true});
+    let report = result(&mut auto, args.clone());
+    assert_eq!(report["completed"], 2, "{report}");
+    assert_eq!(report["failed"], 1);
+    assert_eq!(report["skipped"], 1);
+    assert_eq!(std::fs::read(dir.path().join("input/output/sub/a.pdf")).unwrap(), b"precious");
+    assert_eq!(std::fs::read_to_string(dir.path().join("input/a.txt")).unwrap(), "Hello");
+    for name in ["a.pdf", "sub/a (2).pdf"] {
+        let bytes = std::fs::read(dir.path().join("input/output").join(name)).unwrap();
+        let mut session = Session::new();
+        let id = session.open(name, None, std::sync::Arc::new(bytes), None).unwrap();
+        assert_eq!(session.get(id).unwrap().info.pages.len(), 1);
+    }
+    assert!(!dir.path().join("input/output/b.pdf").exists());
+    assert!(auto.session().docs().is_empty());
+    let again = result(&mut auto, args);
+    assert_eq!(again["completed"], 2, "previous outputs must not become new inputs: {again}");
+    assert!(dir.path().join("input/output/a (2).pdf").exists());
+}
+
+#[test]
+fn batch_is_nonrecursive_by_default_and_stop_reports_unprocessed_files() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join("input/sub")).unwrap();
+    std::fs::write(dir.path().join("input/0.pdf"), b"broken").unwrap();
+    let original = pdf();
+    std::fs::write(dir.path().join("input/1.pdf"), &original).unwrap();
+    std::fs::write(dir.path().join("input/sub/2.pdf"), &original).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["input"],"steps":["optimize"],"out_dir":"out","stop_on_error":true}));
+    assert_eq!(report["failed"], 1);
+    assert_eq!(report["completed"], 0);
+    assert_eq!(report["skipped"], 1);
+    assert_eq!(report["stopped"], true);
+    assert!(!dir.path().join("out").exists());
+    let report = result(&mut auto, json!({"paths":["input"],"steps":["optimize"],"out_dir":"out"}));
+    assert_eq!(report["completed"], 1);
+    assert!(!dir.path().join("out/sub").exists());
+    assert!(std::fs::metadata(dir.path().join("out/1.pdf")).unwrap().len() <= original.len() as u64);
+}
+
+#[test]
+fn invalid_batch_arguments_and_outside_paths_write_nothing() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir(dir.path().join("input")).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    for change in [
+        json!({"steps":["convert","convert"]}),
+        json!({"steps":["optimize","convert"]}),
+        json!({"steps":[]}),
+        json!({"steps":["nope"]}),
+        json!({"recursive":"yes"}),
+        json!({"paths":[]}),
+        json!({"paths":["input","../outside"]}),
+        json!({"out_dir":"../outside"}),
+        json!({"out_dir":"input"}),
+        json!({"out_dir":"."}),
+        json!({"quality":0}),
+        json!({"quality":"80"}),
+        json!({"ppi":2000}),
+        json!({"steps":["ocr"],"language":"not-a-language"}),
+        json!({"steps":["ocr"],"dpi":1}),
+    ] {
+        let mut args = json!({"paths":["input"],"steps":["optimize"],"out_dir":"out"});
+        args.as_object_mut().unwrap().extend(change.as_object().unwrap().clone());
+        assert!(auto.call("doc_batch", &args).is_err(), "{args}");
+        assert!(!dir.path().join("out").exists(), "invalid arguments must be refused before writing");
+    }
+}
+
+#[test]
+fn explicitly_selected_subfolder_is_processed_without_recursive() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join("input/sub")).unwrap();
+    std::fs::write(dir.path().join("input/sub/page.pdf"), pdf()).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["input","input/sub"],"steps":["convert"],"out_dir":"out"}));
+    assert_eq!(report["completed"], 1, "{report}");
+    assert!(dir.path().join("out/page.pdf").exists());
+}
+
+#[test]
+fn explicit_file_can_write_a_numbered_copy_beside_its_source() {
+    let dir = tempfile::tempdir().unwrap();
+    let original = pdf();
+    std::fs::write(dir.path().join("page.pdf"), &original).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["page.pdf"],"steps":["convert"],"out_dir":"."}));
+    assert_eq!(report["completed"], 1, "{report}");
+    assert_eq!(std::fs::read(dir.path().join("page.pdf")).unwrap(), original);
+    assert_eq!(std::fs::read(dir.path().join("page (2).pdf")).unwrap(), original);
+}
+
+#[cfg(unix)]
+#[test]
+fn non_utf8_discovered_names_are_reported_without_panicking() {
+    use std::os::unix::ffi::OsStrExt;
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir(dir.path().join("input")).unwrap();
+    let invalid = dir.path().join("input").join(std::ffi::OsStr::from_bytes(b"bad-\xff.pdf"));
+    if let Err(error) = std::fs::write(&invalid, pdf()) {
+        // APFS rejects this filename before batch discovery can see it. Keep the
+        // discovery assertions on filesystems that allow it; no other I/O error
+        // is an unsupported fixture.
+        #[cfg(target_os = "macos")]
+        if error.raw_os_error() == Some(92) {
+            assert!(!invalid.exists());
+            assert_eq!(std::fs::read_dir(dir.path().join("input")).unwrap().count(), 0);
+            assert!(!dir.path().join("out").exists());
+            let valid = dir.path().join("input/valid-λ.pdf");
+            let original = pdf();
+            std::fs::write(&valid, &original).unwrap();
+            assert_eq!(std::fs::read(&valid).unwrap(), original);
+            let mut auto = Automation::new().with_root(dir.path()).unwrap();
+            let report = result(&mut auto, json!({"paths":["input"],"steps":["convert"],"out_dir":"out"}));
+            assert_eq!(report["completed"], 1, "{report}");
+            assert_eq!(report["failed"], 0, "{report}");
+            assert_eq!(std::fs::read(dir.path().join("out/valid-λ.pdf")).unwrap(), original);
+            eprintln!(
+                "non-UTF-8 fixture capability unavailable: macOS filesystem rejected creation with EILSEQ92; valid-Unicode batch companion passed; invalid-name discovery still requires Linux/FreeBSD or a supporting filesystem"
+            );
+            return;
+        }
+        panic!("could not create the non-UTF-8 fixture: {error}");
+    }
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["input"],"steps":["convert"],"out_dir":"out"}));
+    assert_eq!(report["failed"], 1);
+    assert!(report["files"][0]["error"].as_str().unwrap().contains("UTF-8"));
+}
+
+#[cfg(unix)]
+#[test]
+fn directory_links_are_not_followed_and_output_links_cannot_escape() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join("input/sub")).unwrap();
+    std::fs::create_dir(dir.path().join("outside")).unwrap();
+    std::fs::create_dir(dir.path().join("out")).unwrap();
+    std::fs::write(dir.path().join("input/sub/page.pdf"), pdf()).unwrap();
+    std::os::unix::fs::symlink(dir.path().join("input"), dir.path().join("input/loop")).unwrap();
+    std::os::unix::fs::symlink(dir.path().join("outside"), dir.path().join("out/sub")).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["input"],"steps":["convert"],"out_dir":"out","recursive":true}));
+    assert_eq!(report["skipped"], 1);
+    assert_eq!(report["failed"], 1);
+    assert_eq!(std::fs::read_dir(dir.path().join("outside")).unwrap().count(), 0);
+}
+
+#[test]
+fn batch_ocr_uses_existing_models_or_reports_the_missing_models_per_file() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::write(dir.path().join("page.pdf"), pdf()).unwrap();
+    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+    let report = result(&mut auto, json!({"paths":["page.pdf"],"steps":["ocr","optimize"],"out_dir":"out"}));
+    if pdfcraft_engine::ocr::available() {
+        assert_eq!(report["completed"], 1, "{report}");
+        assert_eq!(report["files"][0]["steps"][0]["skipped_pages"], 1);
+        assert!(dir.path().join("out/page.pdf").exists());
+    } else {
+        assert_eq!(report["failed"], 1, "{report}");
+        assert!(report["files"][0]["error"].as_str().unwrap().contains("model"), "{report}");
+        assert!(!dir.path().join("out/page.pdf").exists());
+    }
+}
+
+#[test]
+fn batch_output_collisions_are_safe_under_concurrent_writers() {
+    let dir = tempfile::tempdir().unwrap();
+    let original = pdf();
+    std::fs::write(dir.path().join("page.pdf"), &original).unwrap();
+    let barrier = std::sync::Barrier::new(2);
+    std::thread::scope(|scope| {
+        let handles: Vec<_> = (0..2)
+            .map(|_| {
+                scope.spawn(|| {
+                    let mut auto = Automation::new().with_root(dir.path()).unwrap();
+                    barrier.wait();
+                    result(&mut auto, json!({"paths":["page.pdf"],"steps":["convert"],"out_dir":"out"}))
+                })
+            })
+            .collect();
+        let reports: Vec<_> = handles.into_iter().map(|h| h.join().unwrap()).collect();
+        assert!(reports.iter().all(|r| r["completed"] == 1), "{reports:?}");
+        assert_ne!(reports[0]["files"][0]["output"], reports[1]["files"][0]["output"]);
+    });
+    for name in ["page.pdf", "page (2).pdf"] {
+        assert_eq!(std::fs::read(dir.path().join("out").join(name)).unwrap(), original);
+    }
+    assert_eq!(std::fs::read_dir(dir.path().join("out")).unwrap().count(), 2, "no staging files remain");
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn mcp_batch_errors_keep_the_structured_per_file_report() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::write(dir.path().join("broken.pdf"), b"broken").unwrap();
+    let input = json!({"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"doc_batch","arguments":{"paths":["broken.pdf"],"steps":["optimize"],"out_dir":"out"}}}).to_string() + "\n";
+    let mut out = Vec::new();
+    pdfcraft_automation::mcp::McpServer::new(Automation::new().with_root(dir.path()).unwrap()).serve(input.as_bytes(), &mut out).unwrap();
+    let report: Value = serde_json::from_slice(&out).unwrap();
+    assert_eq!(report["result"]["isError"], true, "{report}");
+    assert_eq!(report["result"]["structuredContent"]["failed"], 1);
+}

crates/content/src/lib.rs

@@ -125,12 +125,19 @@ pub fn parse(data: &[u8]) -> Parsed {
                 start.get_or_insert(at);
                 operands.push(Object::Null);
             }
-            b"BI" => {
-                let (dict, img, end) = inline_image(data, lx.pos);
-                lx.pos = end;
-                out.ops.push(Op { op: b"BI".to_vec(), operands: Vec::new(), inline: Some((dict, img)), span: start.take().unwrap_or(at)..end });
-                operands.clear();
-            }
+            b"BI" => match inline_image(data, lx.pos) {
+                Ok((dict, img, end)) => {
+                    lx.pos = end;
+                    out.ops.push(Op { op: b"BI".to_vec(), operands: Vec::new(), inline: Some((dict, img)), span: start.take().unwrap_or(at)..end });
+                    operands.clear();
+                }
+                Err(end) => {
+                    out.skipped += end.saturating_sub(at);
+                    lx.pos = end;
+                    start = None;
+                    operands.clear();
+                }
+            },
             _ => {
                 let s = start.take().unwrap_or(at);
                 out.ops.push(Op { op: kw.to_vec(), operands: std::mem::take(&mut operands), inline: None, span: s..lx.pos });
@@ -141,8 +148,9 @@ pub fn parse(data: &[u8]) -> Parsed {
     out
 }
 
-/// Read an inline image starting after `BI`: (parameters, data, position after `EI`).
-fn inline_image(data: &[u8], pos: usize) -> (Dict, Vec<u8>, usize) {
+/// Read an inline image starting after `BI`: (parameters, data, position after `EI`). `Err` holds
+/// the position after the `EI` (or the end of the stream) of an image whose parameters can't be read.
+fn inline_image(data: &[u8], pos: usize) -> Result<(Dict, Vec<u8>, usize), usize> {
     let mut lx = Lexer::new(data, pos);
     let mut dict = Dict::new();
     loop {
@@ -150,17 +158,32 @@ fn inline_image(data: &[u8], pos: usize) -> (Dict, Vec<u8>, usize) {
         if lx.eat_keyword(b"ID") {
             break;
         }
-        let Ok(Object::Name(k)) = lx.object() else {
-            return (dict, Vec::new(), data.len());
+        let at = lx.pos;
+        let entry = match lx.object() {
+            Ok(Object::Name(k)) => lx.object().ok().map(|v| (k, v)),
+            _ => None,
         };
-        let Ok(v) = lx.object() else {
-            return (dict, Vec::new(), data.len());
+        let Some((k, v)) = entry else {
+            // A stream that ends inside the parameters is cut short, not unreadable: keep what was read.
+            if at >= data.len() {
+                return Ok((dict, Vec::new(), data.len()));
+            }
+            // Without an `EI` after it, the image runs to the end of the stream.
+            return Err(end_of_image(data, at).map_or(data.len(), |(_, end)| end));
         };
         dict.set(k, v);
     }
     // One whitespace byte separates ID from the data.
     let begin = (lx.pos + 1).min(data.len());
-    // The data ends at whitespace + `EI` + (whitespace or end). Search for that pattern.
+    Ok(match end_of_image(data, begin) {
+        Some((end_data, end)) => (dict, data[begin..end_data].to_vec(), end),
+        None => (dict, data[begin..].to_vec(), data.len()),
+    })
+}
+
+/// Where inline image data starting at `begin` ends: (end of the data, position after `EI`). The
+/// data ends at whitespace + `EI` + (whitespace, a delimiter or the end).
+fn end_of_image(data: &[u8], begin: usize) -> Option<(usize, usize)> {
     let mut i = begin;
     while i + 2 <= data.len() {
         if data[i] == b'E'
@@ -169,11 +192,11 @@ fn inline_image(data: &[u8], pos: usize) -> (Dict, Vec<u8>, usize) {
             && data.get(i + 2).is_none_or(|b| is_ws(*b) || is_delim(*b))
         {
             let end_data = if i > begin && is_ws(data[i - 1]) { i - 1 } else { i };
-            return (dict, data[begin..end_data].to_vec(), i + 2);
+            return Some((end_data, i + 2));
         }
         i += 1;
     }
-    (dict, data[begin..].to_vec(), data.len())
+    None
 }
 
 /// Write one operator (with a trailing newline).

crates/content/src/tests.rs

@@ -48,6 +48,36 @@ fn damage_is_skipped_not_fatal() {
     assert!(parse(b"BI /W 1").ops.len() == 1);
 }
 
+/// Issue #1318: an inline image whose dictionary can't be read is skipped up to its `EI`, counted,
+/// and what follows it is parsed.
+#[test]
+fn an_unreadable_inline_image_is_skipped_to_its_end() {
+    let src = b"q BI /W 4 H 4 ID aa EI Q BT (After) Tj ET";
+    let p = parse(src);
+    let names: Vec<&[u8]> = p.ops.iter().map(|o| o.op.as_slice()).collect();
+    assert_eq!(names, [&b"q"[..], b"Q", b"BT", b"Tj", b"ET"]);
+    assert_eq!(p.skipped, b"BI /W 4 H 4 ID aa EI".len());
+    let control = parse(b"q BI /W 4 /H 4 ID aa EI Q BT (After) Tj ET");
+    assert_eq!(control.skipped, 0);
+    assert_eq!(control.ops.len(), 6);
+}
+
+/// Issue #1318, follow-up: without an `EI`, an unreadable inline image runs to the end of the
+/// stream, and those bytes are counted. A readable one whose data is cut short is kept, data and
+/// all, so nothing of it is skipped.
+#[test]
+fn an_unreadable_inline_image_without_ei_is_counted() {
+    let p = parse(b"q BI /W 4 H 4 ID aa");
+    let names: Vec<&[u8]> = p.ops.iter().map(|o| o.op.as_slice()).collect();
+    assert_eq!(names, [&b"q"[..]]);
+    assert_eq!(p.skipped, b"BI /W 4 H 4 ID aa".len());
+    let control = parse(b"q BI /W 4 /H 4 ID aa");
+    assert_eq!(control.skipped, 0);
+    let names: Vec<&[u8]> = control.ops.iter().map(|o| o.op.as_slice()).collect();
+    assert_eq!(names, [&b"q"[..], b"BI"]);
+    assert_eq!(control.ops[1].inline.as_ref().map(|(_, data)| data.as_slice()), Some(&b"aa"[..]));
+}
+
 #[test]
 fn matrices_compose_and_invert() {
     let a = Matrix([2.0, 0.0, 0.0, 3.0, 10.0, 20.0]);

crates/cos/src/document.rs

@@ -105,6 +105,8 @@ pub struct Document {
     entries: Arc<BTreeMap<u32, XrefEntry>>,
     trailer: Dict,
     revisions: Arc<Vec<Revision>>,
+    /// See [`Self::xref_oddities`].
+    xref_oddities: Arc<Vec<(u64, u32)>>,
     repair_log: Arc<Vec<String>>,
     cache: Arc<Mutex<HashMap<u32, Arc<Object>>>>,
     objstms: Arc<Mutex<HashMap<u32, Arc<ObjStm>>>>,
@@ -219,6 +221,7 @@ impl Document {
             entries: Arc::new(BTreeMap::new()),
             trailer: Dict::new(),
             revisions: Arc::new(Vec::new()),
+            xref_oddities: Arc::default(),
             repair_log: Arc::new(Vec::new()),
             cache: Arc::default(),
             objstms: Arc::default(),
@@ -282,6 +285,7 @@ impl Document {
             entries: Arc::new(BTreeMap::new()),
             trailer: Dict::new(),
             revisions: Arc::new(Vec::new()),
+            xref_oddities: Arc::default(),
             repair_log: Arc::new(Vec::new()),
             cache: Arc::default(),
             objstms: Arc::default(),
@@ -304,10 +308,11 @@ impl Document {
         let parsed = doc.read_xref_chain(&mut log);
         let mut authenticated = false;
         let ok = match parsed {
-            Ok((entries, trailer, revisions)) => {
+            Ok((entries, trailer, revisions, oddities)) => {
                 doc.entries = Arc::new(entries);
                 doc.trailer = trailer;
                 doc.revisions = Arc::new(revisions);
+                doc.xref_oddities = Arc::new(oddities);
                 // Authenticate before checking the catalog: it may sit in an encrypted object
                 // stream, which reads as garbage until the key is known.
                 if let Some(enc) = doc.trailer.get(b"Encrypt").cloned() {
@@ -587,6 +592,36 @@ impl Document {
         self.entries.get(&num).cloned()
     }
 
+    /// Cross-reference entries this reader did not take at face value, as (byte offset of the
+    /// section, object number): an in-use entry at offset 0, a second and different entry for
+    /// one object in the same section, a reserved cross-reference stream entry type, or a
+    /// hybrid /XRefStm entry that disagrees with the table. The reader sets such an entry aside
+    /// and keeps what it already had for the object. Another reader, the page renderer among
+    /// them, may follow it instead, so the two can then show different objects for one number.
+    /// Code that compares revisions (signature validation) must not call such an object
+    /// unchanged.
+    pub fn xref_oddities(&self) -> &[(u64, u32)] {
+        &self.xref_oddities
+    }
+
+    /// Whether the cross-reference entry of `num` locates that object itself: its `num G obj`
+    /// header at exactly the recorded offset, or the member with that number at the recorded
+    /// position of its object stream. When it does not, [`Self::get`] still finds the object by
+    /// searching, but another reader may resolve the number differently. Ignores unsaved edits.
+    pub fn xref_entry_is_exact(&self, num: u32) -> bool {
+        match self.entries.get(&num) {
+            None | Some(XrefEntry::Free { .. }) => true,
+            Some(XrefEntry::InFile { offset, .. }) => {
+                let at = |off: usize| matches!(parse_indirect_shared(&self.data, off, &|_| None), Ok((id, _)) if id.num == num);
+                // Offsets may count from a header that does not start the file.
+                usize::try_from(*offset).is_ok_and(|off| at(off) || (self.header_offset != 0 && at(off.saturating_add(self.header_offset))))
+            }
+            Some(XrefEntry::InStream { stream, index }) => {
+                self.objstm(*stream).is_ok_and(|stm| usize::try_from(*index).ok().and_then(|i| stm.index.get(i)).is_some_and(|(n, _)| *n == num))
+            }
+        }
+    }
+
     /// Object `num` has an unsaved edit.
     pub fn is_edited(&self, num: u32) -> bool {
         self.overlay.contains_key(&num)
@@ -951,7 +986,7 @@ impl Document {
     }
 
     #[allow(clippy::type_complexity)]
-    fn read_xref_chain(&self, log: &mut Vec<String>) -> Result<(BTreeMap<u32, XrefEntry>, Dict, Vec<Revision>), CosError> {
+    fn read_xref_chain(&self, log: &mut Vec<String>) -> Result<(BTreeMap<u32, XrefEntry>, Dict, Vec<Revision>, Vec<(u64, u32)>), CosError> {
         let data = &self.data;
         let tail_start = data.len().saturating_sub(4096);
         let sx = rfind(data, b"startxref", tail_start).ok_or(CosError::Syntax { offset: data.len(), detail: "no startxref".into() })?;
@@ -963,6 +998,7 @@ impl Document {
         let mut entries = BTreeMap::new();
         let mut trailer: Option<Dict> = None;
         let mut revisions = Vec::new();
+        let mut oddities = Vec::new();
         let mut visited = HashSet::new();
         let mut next = Some(first);
         while let Some(off) = next.take() {
@@ -972,12 +1008,15 @@ impl Document {
             }
             // This section's own entries; older sections only fill what newer ones left out.
             let mut sect = BTreeMap::new();
-            let (sect_trailer, is_stream) = match self.read_section(off as usize, &mut sect) {
+            // Object numbers whose entry in this section was set aside ([`Self::xref_oddities`]).
+            let mut odd = Vec::new();
+            let (sect_trailer, is_stream) = match self.read_section(off as usize, &mut sect, &mut odd) {
                 Ok(v) => v,
                 Err(e) if self.header_offset > 0 => {
                     log.push(format!("xref at {off} unreadable ({e}); retrying relative to the header"));
                     sect.clear();
-                    self.read_section(off as usize + self.header_offset, &mut sect)?
+                    odd.clear();
+                    self.read_section(off as usize + self.header_offset, &mut sect, &mut odd)?
                 }
                 Err(e) => {
                     if revisions.is_empty() {
@@ -992,17 +1031,23 @@ impl Document {
             // free entries it gives objects only a cross-reference stream can locate.
             if let Some(x) = sect_trailer.int(b"XRefStm").filter(|x| *x >= 0) {
                 let mut stm = BTreeMap::new();
-                match self.read_section(x as usize, &mut stm) {
+                match self.read_section(x as usize, &mut stm, &mut odd) {
                     Ok(_) => {
                         for (num, e) in stm {
-                            if sect.get(&num).is_none_or(|old| matches!(old, XrefEntry::Free { .. })) {
-                                sect.insert(num, e);
+                            match sect.get(&num) {
+                                None | Some(XrefEntry::Free { .. }) => {
+                                    sect.insert(num, e);
+                                }
+                                // The table already places the object somewhere else.
+                                Some(old) if *old != e => odd.push(num),
+                                Some(_) => {}
                             }
                         }
                     }
                     Err(e) => log.push(format!("hybrid /XRefStm at {x} unreadable: {e}")),
                 }
             }
+            oddities.extend(odd.into_iter().map(|num| (off, num)));
             for (num, e) in sect {
                 entries.entry(num).or_insert(e);
             }
@@ -1016,11 +1061,12 @@ impl Document {
         for k in [&b"Prev"[..], b"XRefStm", b"Type", b"W", b"Index", b"Filter", b"DecodeParms", b"Length"] {
             trailer.remove(k);
         }
-        Ok((entries, trailer, revisions))
+        Ok((entries, trailer, revisions, oddities))
     }
 
-    /// Read one section at `off`, adding entries not already known (newer sections win).
-    fn read_section(&self, off: usize, entries: &mut BTreeMap<u32, XrefEntry>) -> Result<(Dict, bool), CosError> {
+    /// Read one section at `off`, adding entries not already known (newer sections win). `odd`
+    /// collects the object numbers whose entry here is set aside ([`Self::xref_oddities`]).
+    fn read_section(&self, off: usize, entries: &mut BTreeMap<u32, XrefEntry>, odd: &mut Vec<u32>) -> Result<(Dict, bool), CosError> {
         let data = &self.data;
         let mut lx = Lexer::new(data, off);
         if lx.eat_keyword(b"xref") {
@@ -1052,11 +1098,17 @@ impl Document {
                         (b"f", _) => XrefEntry::Free { next_generation: generation },
                         _ => return Err(CosError::Syntax { offset: lx.pos, detail: "bad xref entry".into() }),
                     };
-                    // Offset 0 "in use" entries are a known producer bug: ignore them.
+                    // Offset 0 "in use" entries are a known producer bug: ignore them. (Object 0
+                    // is never a real object, so its entry cannot mislead anyone.)
                     if matches!(entry, XrefEntry::InFile { offset: 0, .. }) {
+                        if num != 0 {
+                            odd.push(num);
+                        }
                         continue;
                     }
-                    entries.entry(num).or_insert(entry);
+                    if *entries.entry(num).or_insert(entry) != entry {
+                        odd.push(num);
+                    }
                 }
             }
         }
@@ -1110,12 +1162,21 @@ impl Document {
                     0 => XrefEntry::Free { next_generation: b.min(u16::MAX as u64) as u16 },
                     1 => XrefEntry::InFile { offset: a, generation: b.min(u16::MAX as u64) as u16 },
                     2 => XrefEntry::InStream { stream: a.min(u32::MAX as u64) as u32, index: b.min(u32::MAX as u64) as u32 },
-                    _ => continue, // reserved types are treated as null references (§7.5.8.3)
+                    // Reserved types are treated as null references (§7.5.8.3).
+                    _ => {
+                        odd.push(num);
+                        continue;
+                    }
                 };
                 if matches!(entry, XrefEntry::InFile { offset: 0, .. }) {
+                    if num != 0 {
+                        odd.push(num);
+                    }
                     continue;
                 }
-                entries.entry(num).or_insert(entry);
+                if *entries.entry(num).or_insert(entry) != entry {
+                    odd.push(num);
+                }
             }
         }
         Ok((s.dict.clone(), true))
@@ -1263,6 +1324,44 @@ mod tests {
         out
     }
 
+    /// Entries the reader sets aside are remembered, so a caller comparing revisions can tell
+    /// that another reader may resolve the object differently.
+    #[test]
+    fn cross_reference_entries_that_are_set_aside_are_recorded() {
+        let base = build(&["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [] /Count 0 >>", "(three)"], "/Root 1 0 R");
+        let plain = Document::open(Arc::new(base.clone())).unwrap();
+        assert!(plain.xref_oddities().is_empty());
+        assert!((1..=3).all(|n| plain.xref_entry_is_exact(n)));
+        let prev = String::from_utf8_lossy(&base).rfind("xref\n0 4").unwrap();
+        let third = plain.xref_entry(3).unwrap();
+
+        // A later section: object 3 "in use" at offset 0, object 2 listed twice with different
+        // offsets, and object 0 at offset 0 (the usual producer slip, which names no object).
+        let mut bytes = base.clone();
+        let section = bytes.len();
+        bytes.extend_from_slice(
+            format!("xref\n0 1\n0000000000 65535 n \n3 1\n0000000000 00000 n \n2 1\n0000000058 00000 n \n2 1\n0000000009 00000 n \ntrailer\n<< /Size 4 /Root 1 0 R /Prev {prev} >>\nstartxref\n{section}\n%%EOF\n").as_bytes(),
+        );
+        let doc = Document::open(Arc::new(bytes)).unwrap();
+        assert_eq!(doc.xref_oddities(), [(section as u64, 3), (section as u64, 2)]);
+        // What the reader resolves is what it resolved before: the first entry it kept.
+        assert_eq!(doc.xref_entry(3), Some(third));
+        assert_eq!(doc.xref_entry(2), Some(XrefEntry::InFile { offset: 58, generation: 0 }));
+    }
+
+    /// An entry that misses its object still resolves (by searching) but is not exact.
+    #[test]
+    fn an_entry_that_misses_its_object_is_found_by_searching_but_is_not_exact() {
+        let base = build(&["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [] /Count 0 >>", "(three)"], "/Root 1 0 R");
+        let text = String::from_utf8_lossy(&base).into_owned();
+        let at = text.find("3 0 obj").unwrap();
+        let bytes = text.replacen(&format!("{at:010} 00000 n"), &format!("{:010} 00000 n", at + 2), 1).into_bytes();
+        let doc = Document::open(Arc::new(bytes)).unwrap();
+        assert_eq!(doc.get(ObjRef { num: 3, generation: 0 }).as_string().map(|s| s.bytes.clone()), Some(b"three".to_vec()));
+        assert!(!doc.xref_entry_is_exact(3));
+        assert!(doc.xref_entry_is_exact(1) && doc.xref_entry_is_exact(2));
+    }
+
     #[test]
     fn invalid_xref_object_ranges_are_reconstructed() {
         // Original in-memory PDF: an intact catalog followed by a damaged xref section.

crates/cos/src/lib.rs

@@ -24,8 +24,10 @@ mod writer;
 pub use bytes::Bytes;
 pub use document::{Document, Revision, SourceIdentity, XrefEntry};
 pub use object::{Dict, MAX_DECODED, Name, ObjRef, Object, PdfString, Stream};
-pub use parser::{Lexer, parse_indirect};
-pub use pdfcraft_crypt::{Algorithm, Auth, Method as CryptMethod, NewEncryption, Permissions, SecurityHandler, pdfdoc_byte, pdfdoc_char};
+pub use parser::{Lexer, is_whitespace, parse_indirect};
+pub use pdfcraft_crypt::{
+    Algorithm, Auth, Method as CryptMethod, NewEncryption, Permissions, SecurityHandler, effective_password, pdfdoc_byte, pdfdoc_char,
+};
 pub use writer::{SaveOptions, pdf_date, serialize, write_full, write_incremental};
 
 #[derive(Debug, thiserror::Error, Clone, PartialEq)]

crates/cos/src/page_labels.rs

@@ -7,6 +7,11 @@ pub const MAX_LABEL_BYTES: usize = 1024;
 pub const MAX_PREFIX_BYTES: usize = 2 * MAX_LABEL_BYTES + 2;
 /// Sum of the UTF-8 bytes of custom labels for one document.
 pub const MAX_LABEL_TOTAL_BYTES: usize = 4 << 20;
+/// Sum of the UTF-8 bytes of the decoded prefixes of one `/PageLabels` tree. Each range decodes
+/// its own prefix, and ranges may share one prefix object, so without this a small file could ask
+/// for a copy per range: [`MAX_LABEL_TREE_WORK`] ranges naming one 1,024-byte prefix would hold
+/// about 200 MiB. Real documents stay far below it.
+pub const MAX_PREFIX_TOTAL_BYTES: usize = 4 << 20;
 /// The most number-tree entries (nodes, kids and range pairs) read from one `/PageLabels`
 /// tree. Scaled for real documents: one range per page on a ten-thousand-page PDF happens
 /// (prefix labels; #307's file has 9,156 pages), so the cap is twenty times that while still

crates/cos/src/parser.rs

@@ -11,7 +11,8 @@ use crate::{Bytes, CosError};
 
 const MAX_DEPTH: usize = 128;
 
-pub(crate) fn is_whitespace(b: u8) -> bool {
+/// One of the six PDF whitespace characters (ISO 32000-2 §7.2.3, Table 1).
+pub fn is_whitespace(b: u8) -> bool {
     matches!(b, b'\0' | b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
 }
 

crates/cos/src/writer.rs

@@ -431,6 +431,15 @@ fn write_xref_table(out: &mut Vec<u8>, offsets: &BTreeMap<u32, (u64, u16, bool)>
     if include_zero {
         all.insert(0, (0, (0, 65535, false)));
     }
+    // A section is one or more subsections. `xref` followed immediately by `trailer` is not a
+    // table (qpdf: "xref syntax invalid") and is what an incremental save of a classic-table
+    // file used to append when nothing was edited. A zero-length subsection names no objects,
+    // so the free list and every in-use entry stay as they were, while a trailer-only change
+    // (a missing `/ID`, or a caller edit of the trailer) is still written.
+    if all.is_empty() {
+        let _ = writeln!(out, "0 0");
+        return;
+    }
     let mut i = 0;
     while i < all.len() {
         let start = all[i].0;

crates/cos/tests/writer.rs

@@ -135,6 +135,116 @@ fn full_saves_are_allocated_at_their_exact_size() {
     }
 }
 
+/// A one-page classic-table file with no `/ID`, the case that used to append `xref` and then
+/// `trailer` with no subsection (#1339).
+fn classic_table() -> Vec<u8> {
+    let objects = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Resources << >> /Contents 4 0 R >>",
+        "<< /Length 0 >>\nstream\n\nendstream",
+    ];
+    let mut bytes = b"%PDF-1.7\n".to_vec();
+    let mut offsets = Vec::new();
+    for (i, object) in objects.iter().enumerate() {
+        offsets.push(bytes.len());
+        bytes.extend_from_slice(format!("{} 0 obj\n{object}\nendobj\n", i + 1).as_bytes());
+    }
+    let xref = bytes.len();
+    bytes.extend_from_slice(b"xref\n0 5\n0000000000 65535 f \n");
+    for offset in offsets {
+        bytes.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes());
+    }
+    bytes.extend_from_slice(format!("trailer\n<< /Size 5 /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n").as_bytes());
+    bytes
+}
+
+fn qpdf_check(bytes: &[u8]) -> Option<std::process::Output> {
+    let Ok(version) = std::process::Command::new("qpdf").arg("--version").output() else {
+        return None;
+    };
+    assert!(version.status.success());
+    static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+    let n = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("pdfcraft-xref-{}-{n}.pdf", std::process::id()));
+    std::fs::write(&path, bytes).unwrap();
+    let check = std::process::Command::new("qpdf").arg("--check").arg(&path).output().unwrap();
+    let _ = std::fs::remove_file(&path);
+    Some(check)
+}
+
+fn page(doc: &Document) -> Dict {
+    let root = doc.resolve(doc.trailer().get(b"Root").unwrap());
+    let pages = doc.resolve(root.as_dict().unwrap().get(b"Pages").unwrap());
+    let kids = pages.as_dict().unwrap().get(b"Kids").unwrap().as_array().unwrap();
+    doc.resolve(kids.first().unwrap()).as_dict().cloned().unwrap()
+}
+
+fn assert_qpdf_clean(bytes: &[u8]) {
+    let Some(check) = qpdf_check(bytes) else {
+        eprintln!("qpdf not installed: skipped");
+        return;
+    };
+    let report = format!("{}{}", String::from_utf8_lossy(&check.stdout), String::from_utf8_lossy(&check.stderr));
+    assert!(check.status.success() && !report.contains("WARNING"), "{report}");
+}
+
+#[test]
+fn unchanged_incremental_save_of_a_classic_table_is_a_valid_xref() {
+    let input = classic_table();
+    let doc = Document::open(Arc::new(input.clone())).unwrap();
+    assert!(!doc.is_modified());
+    assert!(doc.repair_log().is_empty());
+    assert_eq!(doc.revisions().len(), 1);
+    assert!(!doc.revisions()[0].is_stream);
+
+    let unchanged = write_incremental(&doc, &SaveOptions::default()).unwrap();
+    assert!(unchanged.starts_with(&input));
+    let appended = &unchanged[input.len()..];
+    assert!(appended.windows(8).any(|w| w == b"xref\n0 0"), "a section with no entries still needs a subsection");
+    assert!(!appended.windows(13).any(|w| w == b"xref\ntrailer"));
+
+    let back = Document::open(Arc::new(unchanged.clone())).unwrap();
+    assert!(back.repair_log().is_empty(), "{:?}", back.repair_log());
+    assert_eq!(back.revisions().len(), 2);
+    assert_eq!(page(&back).name(b"Type"), Some(b"Page".as_slice()));
+    assert!(back.trailer().get(b"ID").is_some(), "a file without an identifier still receives one");
+    assert_eq!(hayro_pages(&unchanged), 1);
+    assert_qpdf_clean(&unchanged);
+
+    let mut edited = doc.clone();
+    edited.update_dict(ObjRef::new(3, 0), |d| d.set(b"Rotate".to_vec(), Object::Int(90))).unwrap();
+    let edited = write_incremental(&edited, &SaveOptions::default()).unwrap();
+    let edited_back = Document::open(Arc::new(edited.clone())).unwrap();
+    assert!(edited_back.repair_log().is_empty(), "{:?}", edited_back.repair_log());
+    assert_eq!(edited_back.get(ObjRef::new(3, 0)).as_dict().unwrap().int(b"Rotate"), Some(90));
+    assert_qpdf_clean(&edited);
+
+    let stamped = write_incremental(&doc, &SaveOptions { mod_date: Some("D:20260101000000Z".into()), ..SaveOptions::default() }).unwrap();
+    let stamped_back = Document::open(Arc::new(stamped.clone())).unwrap();
+    assert!(stamped_back.repair_log().is_empty(), "{:?}", stamped_back.repair_log());
+    let info = stamped_back.resolve(stamped_back.trailer().get(b"Info").unwrap());
+    assert_eq!(
+        info.as_dict().unwrap().get(b"ModDate").and_then(|d| d.as_string()).map(|s| s.bytes.as_slice()),
+        Some(b"D:20260101000000Z".as_slice())
+    );
+    assert_qpdf_clean(&stamped);
+}
+
+#[test]
+fn incremental_save_keeps_a_trailer_only_edit() {
+    let input = classic_table();
+    let mut doc = Document::open(Arc::new(input)).unwrap();
+    assert!(!doc.is_modified());
+    doc.trailer_mut().set(b"Custom".to_vec(), Object::String(pdfcraft_cos::PdfString::literal(b"keep me".to_vec())));
+    let saved = write_incremental(&doc, &SaveOptions::default()).unwrap();
+    let back = Document::open(Arc::new(saved.clone())).unwrap();
+    assert!(back.repair_log().is_empty(), "{:?}", back.repair_log());
+    assert_eq!(back.trailer().get(b"Custom").and_then(|o| o.as_string()).map(|s| s.bytes.as_slice()), Some(b"keep me".as_slice()));
+    assert_eq!(hayro_pages(&saved), 1);
+    assert_qpdf_clean(&saved);
+}
+
 #[test]
 fn qpdf_accepts_object_stream_output() {
     let Ok(out) = std::process::Command::new("qpdf").arg("--version").output() else {

crates/create/Cargo.toml

@@ -15,6 +15,8 @@ pdfcraft-fonts = { workspace = true }
 png = "0.18"
 tiff = "0.11"
 image = { version = "0.25", default-features = false, features = ["bmp", "gif", "jpeg"] }
+# Already in the graph through image; read directly for CMYK JPEG samples, which image converts to RGB.
+zune-jpeg = "0.5"
 thiserror = { workspace = true }
 # Already in the graph through lopdf; used only to read plain-text files (decode_text).
 encoding_rs = "0.8"

crates/create/README.md

@@ -16,6 +16,10 @@ Layer L4. Create a PDF (Acrobat's Create a PDF tool), execution plan M10.2:
   resolution (1–1200 dpi), without resampling or recompressing image pixels. Use 72 dpi
   for one point per pixel, or `ImageResolution::Embedded` for the same behavior as
   `from_images`. The largest page side is still capped at 14,400 points;
-- `from_text(text, …)`: plain text set in Helvetica, wrapped and paginated.
+- `from_text(text, …)`: plain text set in Helvetica, wrapped and paginated. Text Helvetica
+  can't draw is refused, naming the line and the character, never set as `?`.
+- `from_text_escaped(text, …)`: the same for reports PdfCraft generates from documents
+  (comment summaries, compare reports): such characters are written as `[U+XXXX]` and the first
+  line says so (`ESCAPED_NOTE`).
 
 Every function returns a `pdfcraft_cos::Document`; the caller writes it.

crates/create/src/extract.rs

@@ -1,6 +1,6 @@
 //! Export a PDF ▸ Image ▸ Export all images, and Edit ▸ Save image as: the images that pages
 //! use, as files. JPEG images are written unchanged; other images, and JPEG images with
-//! transparency, are decoded and written as PNG with their soft mask, stencil mask or colour
+//! transparency or with CMYK samples a viewer would read inverted, are decoded and written as PNG with their soft mask, stencil mask or colour
 //! key as alpha. Images PdfCraft can't decode yet (JPEG 2000, JBIG2, CCITT, separations) are
 //! reported, never silently left out.
 
@@ -126,13 +126,24 @@ fn image(doc: &Document, s: &Stream) -> Result<(&'static str, Vec<u8>), String>
     // A stencil mask (`ImageMask true`) has no /SMask or /Mask of its own (8.9.6.2).
     let mut alpha = if mask { None } else { soft_mask(doc, s, w, h).or_else(|| stencil_mask(doc, s, w, h)) };
     let key = if mask { None } else { colour_key(doc, s) };
-    if jpeg && alpha.is_none() && key.is_none() {
+    // Decode arrays: only inversion ([1 0] per component) is honoured, the common case.
+    let inverted = s
+        .dict
+        .get(b"Decode")
+        .map(|d| doc.resolve(d))
+        .and_then(|d| d.as_array().map(|a| a.first().and_then(Object::as_f64) > a.get(1).and_then(Object::as_f64)))
+        .unwrap_or(false);
+    // In a PDF a CMYK JPEG's samples are ink amounts unless /Decode inverts them, while image
+    // viewers read a CMYK JPEG file as inverted (Adobe's convention): as is, it would show as
+    // a negative.
+    let as_is_negative = jpeg && !inverted && matches!(space(doc, s.dict.get(b"ColorSpace")), Ok(Space::Cmyk));
+    if jpeg && alpha.is_none() && key.is_none() && !as_is_negative {
         return as_is();
     }
     let mut space = if mask { Space::Gray } else { space(doc, s.dict.get(b"ColorSpace"))? };
     let (samples, bpc) = if jpeg {
-        // A JPEG decoder gives grey or RGB (CMYK and YCCK are converted); a JPEG that doesn't
-        // decode, or an indexed one (not valid), is written as is, without its transparency.
+        // Grey, RGB or CMYK samples (YCCK is converted); a JPEG that doesn't decode, or an
+        // indexed one (not valid), is written as is, without its transparency.
         let Some((samples, decoded)) = jpeg_samples(&s.raw, &space, w, h) else { return as_is() };
         space = decoded;
         (samples, 8)
@@ -153,17 +164,10 @@ fn image(doc: &Document, s: &Stream) -> Result<(&'static str, Vec<u8>), String>
     if alpha.is_none() {
         alpha = key.and_then(|k| keyed_alpha(&samples, n, bpc, &k));
     }
-    if jpeg && alpha.is_none() {
+    if jpeg && alpha.is_none() && !as_is_negative {
         return as_is();
     }
-    // Decode arrays: only inversion ([1 0] per component) is honoured, the common case. A JPEG
-    // decoder has already applied an Adobe JPEG's own inversion.
-    let invert = s
-        .dict
-        .get(b"Decode")
-        .map(|d| doc.resolve(d))
-        .and_then(|d| d.as_array().map(|a| a.first().and_then(Object::as_f64) > a.get(1).and_then(Object::as_f64)));
-    let invert = (invert.unwrap_or(false) && !jpeg) ^ mask; // a stencil mask paints its 0 samples
+    let invert = inverted ^ mask; // a stencil mask paints its 0 samples
     let max = (1u32 << bpc.min(8)) - 1;
     let mut rgb = Vec::with_capacity(w * h * 3);
     for px in samples.chunks_exact(n) {
@@ -200,10 +204,13 @@ fn size(w: i64, h: i64) -> Option<(usize, usize)> {
     (w > 0 && h > 0 && pixels <= MAX_PIXELS).then_some((w, h))
 }
 
-/// A JPEG's samples (8 bits): grey for a grey image, else RGB, with the space they are in.
+/// A JPEG's samples (8 bits): grey for a grey image, CMYK as stored for a CMYK one, else RGB,
+/// with the space they are in.
 fn jpeg_samples(data: &[u8], space: &Space, w: usize, h: usize) -> Option<(Vec<u8>, Space)> {
-    if matches!(space, Space::Indexed(..)) {
-        return None;
+    match space {
+        Space::Indexed(..) => return None,
+        Space::Cmyk => return cmyk_jpeg_samples(data, w, h).map(|px| (px, Space::Cmyk)),
+        _ => {}
     }
     let img = image::load_from_memory_with_format(data, image::ImageFormat::Jpeg).ok()?;
     if img.width() as usize != w || img.height() as usize != h {
@@ -215,6 +222,34 @@ fn jpeg_samples(data: &[u8], space: &Space, w: usize, h: usize) -> Option<(Vec<u
     })
 }
 
+/// A four-component JPEG's CMYK samples as the page reads them: as stored, not inverted the way
+/// a decoder converting to RGB inverts them, with YCCK converted to CMYK.
+fn cmyk_jpeg_samples(data: &[u8], w: usize, h: usize) -> Option<Vec<u8>> {
+    use zune_jpeg::zune_core::{bytestream::ZCursor, colorspace::ColorSpace, options::DecoderOptions};
+    let options = DecoderOptions::default().set_strict_mode(false).set_max_width(usize::from(u16::MAX)).set_max_height(usize::from(u16::MAX));
+    let mut dec = zune_jpeg::JpegDecoder::new_with_options(ZCursor::new(data), options);
+    dec.decode_headers().ok()?;
+    let input = dec.input_colorspace()?;
+    if !matches!(input, ColorSpace::CMYK | ColorSpace::YCCK) || dec.dimensions()? != (w, h) {
+        return None;
+    }
+    dec.set_options(options.jpeg_set_out_colorspace(input));
+    let mut px = dec.decode().ok()?;
+    if px.len() != w.checked_mul(h)?.checked_mul(4)? {
+        return None;
+    }
+    if input == ColorSpace::YCCK {
+        for p in px.as_chunks_mut::<4>().0 {
+            let (y, cb, cr) = (f32::from(p[0]), f32::from(p[1]) - 128.0, f32::from(p[2]) - 128.0);
+            let ink = |rgb: f32| (255.0 - rgb).round().clamp(0.0, 255.0) as u8;
+            p[0] = ink(y + 1.402 * cr);
+            p[1] = ink(y - 0.344_136 * cb - 0.714_136 * cr);
+            p[2] = ink(y + 1.772 * cb);
+        }
+    }
+    Some(px)
+}
+
 /// The colour-key `/Mask` (8.9.6.4): a [min max] pair per colour component, in sample values.
 fn colour_key(doc: &Document, s: &Stream) -> Option<Vec<(u32, u32)>> {
     let m = doc.resolve(s.dict.get(b"Mask")?);

crates/create/src/lib.rs

@@ -488,12 +488,21 @@ pub enum SourceKind {
 /// File extensions Create converts to PDF (images and plain text).
 pub const CONVERTIBLE: [&str; 12] = ["png", "jpg", "jpeg", "tif", "tiff", "gif", "bmp", "jp2", "j2k", "jpx", "txt", "text"];
 
+/// A classic TIFF or a BigTIFF (version 43), in either byte order.
+fn is_tiff(bytes: &[u8]) -> bool {
+    [b"II*\0", b"MM\0*", b"II+\0", b"MM\0+"].iter().any(|m| bytes.starts_with(*m))
+}
+
+/// The GIF headers `embed` decodes, so detection and conversion agree.
+fn is_gif(bytes: &[u8]) -> bool {
+    bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a")
+}
+
 fn is_image(bytes: &[u8]) -> bool {
     bytes.starts_with(&[0xFF, 0xD8])
         || bytes.starts_with(b"\x89PNG\r\n\x1a\n")
-        || bytes.starts_with(b"II*\0")
-        || bytes.starts_with(b"MM\0*")
-        || bytes.starts_with(b"GIF8")
+        || is_tiff(bytes)
+        || is_gif(bytes)
         // JPEG 2000: a JP2 file or a raw codestream.
         || bytes.starts_with(JP2_SIGNATURE)
         || bytes.starts_with(&[0xFF, 0x4F, 0xFF, 0x51])
@@ -522,11 +531,11 @@ fn embed(name: &str, bytes: &[u8]) -> Result<Vec<Embedded>, CreateError> {
         Ok(vec![jpeg(name, bytes)?])
     } else if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
         Ok(vec![png_image(name, bytes)?])
-    } else if bytes.starts_with(b"II*\0") || bytes.starts_with(b"MM\0*") {
+    } else if is_tiff(bytes) {
         tiff_pages(name, bytes)
     } else if bytes.starts_with(b"BM") {
         Ok(vec![decoded(name, bytes, image::ImageFormat::Bmp)?])
-    } else if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
+    } else if is_gif(bytes) {
         Ok(vec![decoded(name, bytes, image::ImageFormat::Gif)?])
     } else if bytes.starts_with(JP2_SIGNATURE) || bytes.starts_with(&[0xFF, 0x4F, 0xFF, 0x51]) {
         Ok(vec![jpx(name, bytes)?])
@@ -618,8 +627,50 @@ fn turkish_code_page(bytes: &[u8]) -> bool {
         && !bytes.iter().any(|b| matches!(b, 0xC1 | 0xCD | 0xD3 | 0xDA | 0xE1 | 0xED | 0xF3 | 0xFA))
 }
 
-/// Plain text set in Helvetica on pages of `page` size with 1-inch margins.
+/// Plain text set in Helvetica on pages of `page` size with 1-inch margins. Text Helvetica can't
+/// draw (outside Western European) is refused with [`CreateError::Invalid`] naming the line and
+/// the character; text PdfCraft generates goes through [`from_text_escaped`] instead.
 pub fn from_text(title: &str, text: &str, page: (f64, f64), font_size: f64) -> Result<Document, CreateError> {
+    // Helvetica in WinAnsiEncoding: text it can't draw is refused with where it is, not set as `?`.
+    if let Some((line, c)) = first_undrawable_line(text) {
+        return Err(CreateError::Invalid(pdfcraft_fonts::undrawable_message(&format!("the text (line {line})"), c)));
+    }
+    set_text(title, text, page, font_size)
+}
+
+/// The line (1-based) and character of the first one Helvetica can't draw. Line breaks, tabs and
+/// form feeds (new pages) are layout, not drawn.
+fn first_undrawable_line(text: &str) -> Option<(usize, char)> {
+    text.split('\n').enumerate().find_map(|(i, l)| pdfcraft_fonts::first_undrawable(&l.replace('\u{c}', "")).map(|c| (i + 1, c)))
+}
+
+/// What a PDF made from text PdfCraft generated says, in its first line, about characters it
+/// wrote as `[U+XXXX]`.
+pub const ESCAPED_NOTE: &str = "Characters Helvetica can't draw are written as [U+XXXX] code points.";
+
+/// [`from_text`] for text PdfCraft generates from documents (a comment summary, a compare
+/// report), which may quote any language. Each character Helvetica can't draw is written as
+/// `[U+XXXX]` instead of being refused or set as `?`, so nothing is lost, and the first line says
+/// so ([`ESCAPED_NOTE`]). Returns the document and how many characters were written that way.
+pub fn from_text_escaped(title: &str, text: &str, page: (f64, f64), font_size: f64) -> Result<(Document, usize), CreateError> {
+    let mut escaped = 0usize;
+    let mut out = String::with_capacity(text.len());
+    for c in text.chars() {
+        if matches!(c, '\n' | '\r' | '\u{c}') || pdfcraft_fonts::first_undrawable(c.encode_utf8(&mut [0; 4])).is_none() {
+            out.push(c);
+        } else {
+            escaped = escaped.saturating_add(1);
+            out.push_str(&format!("[U+{:04X}]", u32::from(c)));
+        }
+    }
+    if escaped > 0 {
+        out = format!("{ESCAPED_NOTE}\n\n{out}");
+    }
+    // The title is a text string in /Info, which holds any character.
+    Ok((set_text(title, &out, page, font_size)?, escaped))
+}
+
+fn set_text(title: &str, text: &str, page: (f64, f64), font_size: f64) -> Result<Document, CreateError> {
     let size = if font_size.is_finite() && font_size > 0.0 { font_size.clamp(4.0, 72.0) } else { 11.0 };
     let (w, h) = page;
     let margin = 72.0;

crates/create/src/tests.rs

@@ -124,6 +124,32 @@ fn text_is_wrapped_and_paginated() {
     assert!(content(p.last().unwrap()).contains("(After a form feed) Tj"), "a form feed starts a page");
 }
 
+/// Text Helvetica can't draw is refused with its line and character, never set as `?`; text
+/// PdfCraft generates writes such characters as [U+XXXX] and says so.
+#[test]
+fn text_helvetica_cannot_draw_is_refused_or_escaped() {
+    let err = from_text("notes", "Café —\tok\r\n\u{c}第二页 notes", LETTER, 11.0).unwrap_err();
+    let CreateError::Invalid(msg) = &err else { panic!("{err:?}") };
+    assert!(msg.contains("(line 2)") && msg.contains("\"第\" (U+7B2C)") && msg.contains("Western European"), "{msg}");
+    // Western European text, tabs, CRLF and form feeds included, still converts.
+    from_text("notes", "Café —\tok\r\n\u{c}Seite zwei: Grüße", LETTER, 11.0).unwrap();
+    let (doc, escaped) = from_text_escaped("Summary of Comments on 报告.pdf", "Comment: 签名 ok\nPage 2", LETTER, 11.0).unwrap();
+    assert_eq!(escaped, 2);
+    let doc = reopen(&doc);
+    let p = pages(&doc);
+    let c = doc.resolve(p[0].get(b"Contents").unwrap());
+    let Object::Stream(s) = &*c else { panic!() };
+    let shown = String::from_utf8_lossy(&s.decoded().unwrap()).into_owned();
+    assert!(shown.contains("(Comment: [U+7B7E][U+540D] ok) Tj") && shown.contains(&format!("({ESCAPED_NOTE}) Tj")), "{shown}");
+    assert!(!shown.contains('?'), "{shown}");
+    // Nothing to escape: no note.
+    let (doc, escaped) = from_text_escaped("r", "Plain report", LETTER, 11.0).unwrap();
+    assert_eq!(escaped, 0);
+    let p = pages(&doc);
+    let Object::Stream(s) = &*doc.resolve(p[0].get(b"Contents").unwrap()) else { panic!() };
+    assert!(!String::from_utf8_lossy(&s.decoded().unwrap()).contains("U+XXXX"));
+}
+
 fn image_of(doc: &Document, page: usize) -> Dict {
     let p = &pages(doc)[page];
     let res = doc.resolve(p.get(b"Resources").unwrap()).as_dict().cloned().unwrap();
@@ -382,6 +408,28 @@ fn source_kind_tells_pdfs_images_and_text_apart() {
     assert_eq!(source_kind("b.bmp", b"BM"), None);
     assert_eq!(source_kind("a.docx", b"PK\x03\x04"), None);
     assert_eq!(source_kind("", b""), None);
+    // Only the GIF versions Create decodes count as images, so detection never promises a
+    // conversion that then fails.
+    assert_eq!(source_kind("a.gif", b"GIF8x not a gif"), None);
+    assert_eq!(source_kind("notes.txt", b"GIF8 is a word here"), Some(SourceKind::Text));
+}
+
+/// BigTIFF (version 43, used for large scans) is detected and converted like a classic TIFF.
+#[test]
+fn bigtiff_images_become_pages() {
+    let mut tif = std::io::Cursor::new(Vec::new());
+    {
+        let mut enc = tiff::encoder::TiffEncoder::new_big(&mut tif).unwrap();
+        let mut im = enc.new_image::<tiff::encoder::colortype::Gray8>(4, 2).unwrap();
+        im.resolution(tiff::tags::ResolutionUnit::Inch, tiff::encoder::Rational { n: 144, d: 1 });
+        im.write_data(&[128; 8]).unwrap();
+    }
+    let tif = tif.into_inner();
+    assert!(tif.starts_with(b"II+\0"), "the encoder wrote a BigTIFF");
+    assert_eq!(source_kind("scan.tif", &tif), Some(SourceKind::Image));
+    let doc = reopen(&from_images(&[("scan.tif".into(), tif)]).unwrap());
+    assert_eq!(pages(&doc).len(), 1);
+    assert_eq!(media(&pages(&doc)[0]), [0.0, 0.0, 2.0, 1.0], "4×2 px at 144 dpi");
 }
 
 /// A synthetic ICC profile: a 128-byte header (size, device class, colour space, `acsp`) and
@@ -695,3 +743,78 @@ fn damaged_masks_and_sizes_never_panic() {
         let _ = image_file(&doc, r);
     }
 }
+
+/// An 8×8 baseline JPEG of one flat colour with four components, stored as `samples`, and an
+/// Adobe APP14 segment with `transform` (0: CMYK, 2: YCCK).
+fn flat_four_component_jpeg(samples: [u8; 4], transform: u8) -> Vec<u8> {
+    fn put(bits: &mut Vec<bool>, value: u32, n: u32) {
+        bits.extend((0..n).rev().map(|i| value >> i & 1 == 1));
+    }
+    let mut v = vec![0xFF, 0xD8];
+    v.extend_from_slice(&[0xFF, 0xEE, 0, 14, b'A', b'd', b'o', b'b', b'e', 0, 100, 0, 0, 0, 0, transform]);
+    v.extend_from_slice(&[0xFF, 0xDB, 0, 67, 0]);
+    v.extend_from_slice(&[1; 64]);
+    v.extend_from_slice(&[0xFF, 0xC0, 0, 20, 8, 0, 8, 0, 8, 4]);
+    for id in 1..=4 {
+        v.extend_from_slice(&[id, 0x11, 0]);
+    }
+    // DC table: categories 0 to 11 with four-bit codes equal to the category. AC table: EOB, "0".
+    v.extend_from_slice(&[0xFF, 0xC4, 0, 31, 0x00, 0, 0, 0, 12, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+    v.extend(0..12u8);
+    v.extend_from_slice(&[0xFF, 0xC4, 0, 20, 0x10, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+    v.extend_from_slice(&[0xFF, 0xDA, 0, 14, 4, 1, 0, 2, 0, 3, 0, 4, 0, 0, 63, 0]);
+    let mut bits = Vec::new();
+    for s in samples {
+        // With every quantiser 1, a flat block's DC coefficient is 8 × (sample − 128).
+        let dc = (i32::from(s) - 128) * 8;
+        let category = 32 - dc.unsigned_abs().leading_zeros();
+        put(&mut bits, category, 4);
+        put(&mut bits, if dc < 0 { (dc + (1 << category) - 1) as u32 } else { dc as u32 }, category);
+        put(&mut bits, 0, 1);
+    }
+    bits.resize(bits.len().div_ceil(8) * 8, true);
+    for byte in bits.chunks(8).map(|b| b.iter().fold(0u8, |a, &x| a << 1 | u8::from(x))) {
+        v.push(byte);
+        if byte == 0xFF {
+            v.push(0);
+        }
+    }
+    v.extend_from_slice(&[0xFF, 0xD9]);
+    v
+}
+
+#[test]
+fn cmyk_and_ycck_jpegs_export_in_the_colours_the_page_shows() {
+    // Issue #1640: in a PDF a CMYK JPEG's samples are ink amounts, inverted only by its /Decode,
+    // while JPEG decoders and image viewers read them inverted (Adobe's convention for files).
+    // Exported cyan came out red. YCCK samples (Y 179, Cb 171, Cr 1) are cyan ink too.
+    let inverting = Object::Array([1, 0, 1, 0, 1, 0, 1, 0].map(Object::Int).to_vec());
+    for (what, samples, transform, decode, masked) in [
+        ("CMYK", [255, 0, 0, 0], 0, None, true),
+        ("YCCK", [179, 171, 1, 0], 2, None, true),
+        ("inverted CMYK with an inverting /Decode", [0, 255, 255, 255], 0, Some(&inverting), true),
+        ("CMYK without a mask", [255, 0, 0, 0], 0, None, false),
+        ("inverted CMYK with an inverting /Decode, without a mask", [0, 255, 255, 255], 0, Some(&inverting), false),
+    ] {
+        let jpeg = flat_four_component_jpeg(samples, transform);
+        let mut doc = from_images(&[("flat.png".into(), png_bytes(false))]).unwrap();
+        with_image(&mut doc, |doc| {
+            let mut d = image_dict(8, 8, "DeviceCMYK", 8);
+            d.set(b"Filter".to_vec(), Object::name("DCTDecode"));
+            if let Some(decode) = decode {
+                d.set(b"Decode".to_vec(), decode.clone());
+            }
+            if masked {
+                let m = doc.add(Object::Stream(Stream::from_raw(image_dict(8, 8, "DeviceGray", 8), vec![255; 64])));
+                d.set(b"SMask".to_vec(), Object::Ref(m));
+            }
+            Stream::from_raw(d, jpeg.clone())
+        });
+        let (ext, rgba) = exported_rgba(&doc);
+        assert!(rgba.as_chunks::<4>().0.iter().all(|p| p[0] <= 6 && p[1] >= 249 && p[2] >= 249), "{what}: {:?}", &rgba[..4]);
+        if decode.is_some() && !masked {
+            // Inverted like an image file expects: still written as is.
+            assert_eq!((ext, &extract_images(&doc, &[0], 0).images[0].data), ("jpg", &jpeg), "{what}");
+        }
+    }
+}

crates/crypt/src/lib.rs

@@ -539,6 +539,32 @@ pub enum Algorithm {
     Aes256,
 }
 
+/// A password as [`create`] prepares it: for R2–R4 its PDFDocEncoding (characters it lacks
+/// dropped), at most 32 bytes; for R6 its SASLprep (RFC 4013: soft hyphens and the like removed,
+/// other spaces made plain, then NFKC; the password as given if SASLprep refuses it), in UTF-8,
+/// at most 127 bytes.
+fn prepared_password(algorithm: Algorithm, password: &str) -> Vec<u8> {
+    match algorithm {
+        Algorithm::Rc4_40 | Algorithm::Rc4_128 | Algorithm::Aes128 => legacy_password(password),
+        Algorithm::Aes256 => sasl_password(password),
+    }
+}
+
+/// The bytes new encryption with `algorithm` derives its keys from for `password`: for R2–R4 its
+/// PDFDocEncoding cut or padded to exactly 32 bytes (Algorithm 2); for R6 its SASLprep (the
+/// password as given if SASLprep refuses it), at most 127 bytes of UTF-8. Two passwords with the
+/// same bytes are the same password to the file, and a password with the bytes of `""` opens it
+/// without asking, so callers can refuse either before encrypting. Different bytes can still give
+/// the same key (RC4-40 keeps 5 bytes of a hash). `create` still uses the user password for an
+/// empty R2–R4 owner password.
+pub fn effective_password(algorithm: Algorithm, password: &str) -> Vec<u8> {
+    let prepared = prepared_password(algorithm, password);
+    match algorithm {
+        Algorithm::Rc4_40 | Algorithm::Rc4_128 | Algorithm::Aes128 => pad(&prepared).to_vec(),
+        Algorithm::Aes256 => prepared,
+    }
+}
+
 /// Parameters for new encryption.
 #[derive(Clone, Debug)]
 pub struct NewEncryption<'a> {
@@ -573,6 +599,8 @@ pub fn create(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, Cry
     // Bits 7–8 and 13–32 must be 1; bits 1–2 must be 0 (§7.6.4.2).
     let p = (params.permissions | !0xFFF | 0xC0) & !0x3;
     let mut d = EncryptDict { filter: b"Standard".to_vec(), p, encrypt_metadata: params.encrypt_metadata, ..Default::default() };
+    let user = prepared_password(params.algorithm, params.user_password);
+    let owner = prepared_password(params.algorithm, params.owner_password);
     match params.algorithm {
         Algorithm::Rc4_40 | Algorithm::Rc4_128 | Algorithm::Aes128 => {
             (d.v, d.r, d.length_bits) = match params.algorithm {
@@ -587,8 +615,7 @@ pub fn create(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, Cry
             } else {
                 d.encrypt_metadata = true; // V < 4 always encrypts metadata
             }
-            let user = legacy_password(params.user_password);
-            let owner = if params.owner_password.is_empty() { user.clone() } else { legacy_password(params.owner_password) };
+            let owner = if params.owner_password.is_empty() { user.clone() } else { owner };
             // Algorithm 3: /O
             let rk = owner_rc4_key(&d, &owner);
             let mut o = rc4(&rk, &pad(&user));
@@ -610,8 +637,6 @@ pub fn create(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, Cry
             d.str_f = b"StdCF".to_vec();
             let key = expand(&params.seed, b"file key", 32);
             let salts = expand(&params.seed, b"salts", 32);
-            let user = sasl_password(params.user_password);
-            let owner = sasl_password(params.owner_password);
             // Algorithm 8: /U, /UE
             let mut u = hash_r6(6, &user, &salts[0..8], &[]);
             u.extend_from_slice(&salts[0..16]);

crates/crypt/src/tests.rs

@@ -145,6 +145,53 @@ fn r6_passwords_are_saslprepped() {
     assert!(SecurityHandler::open(d, ID, Some("SaSL-prep")).is_err());
 }
 
+#[test]
+fn effective_passwords_are_the_bytes_the_keys_are_made_from() {
+    // AES-256: SASLprep drops soft hyphens, makes other spaces plain and folds compatibility
+    // characters (NFKC); at most 127 bytes of UTF-8.
+    let r6 = |pw: &str| effective_password(Algorithm::Aes256, pw);
+    assert_eq!(r6("\u{AD}"), r6(""), "a soft hyphen alone is no password");
+    assert_eq!(r6("\u{FF21}"), r6("A"), "fullwidth A");
+    assert_eq!(r6("\u{FB01}"), r6("fi"), "the fi ligature");
+    assert_eq!(r6("a\u{3000}b"), b"a b", "an ideographic space");
+    assert_ne!(r6("A"), r6("a"), "case matters");
+    assert_eq!(r6(&"é".repeat(100)).len(), 127);
+    // RC4 and AES-128: PDFDocEncoding, padded or cut to exactly 32 bytes.
+    let (a31, a32) = ("a".repeat(31), "a".repeat(32));
+    for alg in [Algorithm::Rc4_40, Algorithm::Rc4_128, Algorithm::Aes128] {
+        assert_eq!(effective_password(alg, &format!("{a32}1")), a32.as_bytes(), "{alg:?}");
+        assert_eq!(effective_password(alg, &format!("1{a32}")), effective_password(alg, &format!("1{a32}2")), "{alg:?}");
+        assert_ne!(effective_password(alg, &format!("1{a32}")), effective_password(alg, &format!("2{a32}")), "{alg:?}");
+        assert_eq!(effective_password(alg, &a31), effective_password(alg, &format!("{a31}(")), "{alg:?}: the padding starts with '('");
+        assert_eq!(effective_password(alg, ""), PADDING, "{alg:?}");
+        assert_eq!(effective_password(alg, "ılık€")[..5], [0x9A, b'l', 0x9A, b'k', 0xA0], "{alg:?}");
+    }
+}
+
+#[test]
+fn passwords_with_the_same_effective_bytes_are_one_password() {
+    // A file protected with "\u{FF21}" (fullwidth A) opens with "A".
+    let d = new(Algorithm::Aes256, "\u{FF21}", "owner", 0b0100).dict().clone();
+    assert_eq!(SecurityHandler::open(d.clone(), ID, Some("A")).unwrap().auth(), Auth::User);
+    assert_eq!(SecurityHandler::open(d, ID, Some("a")).unwrap_err(), CryptError::WrongPassword);
+    // A soft hyphen is no open password at all.
+    let d = new(Algorithm::Aes256, "\u{AD}", "owner", 0b0100).dict().clone();
+    assert_eq!(SecurityHandler::open(d, ID, None).unwrap().auth(), Auth::User);
+    // Open and permissions passwords with the same bytes: the open password gives owner rights.
+    let d = new(Algorithm::Aes256, "\u{FB01}", "fi", 0b0100).dict().clone();
+    assert_eq!(effective_password(Algorithm::Aes256, "\u{FB01}"), effective_password(Algorithm::Aes256, "fi"));
+    assert_eq!(SecurityHandler::open(d, ID, Some("\u{FB01}")).unwrap().auth(), Auth::Owner);
+    let a31 = "a".repeat(31);
+    let pairs = [(format!("{a31}a1"), format!("{a31}a2")), (a31.clone(), format!("{a31}("))];
+    for alg in [Algorithm::Rc4_40, Algorithm::Rc4_128, Algorithm::Aes128] {
+        for (open, perms) in &pairs {
+            assert_eq!(effective_password(alg, open), effective_password(alg, perms), "{alg:?}");
+            let d = new(alg, open, perms, 0b0100).dict().clone();
+            assert_eq!(SecurityHandler::open(d, ID, Some(open)).unwrap().auth(), Auth::Owner, "{alg:?} {open:?}");
+        }
+    }
+}
+
 #[test]
 fn unsupported_handlers_are_reported() {
     let mut d = new(Algorithm::Aes128, "", "o", -1).dict().clone();

crates/edit/Cargo.toml

@@ -15,7 +15,9 @@ pdfcraft-content = { workspace = true }
 pdfcraft-fonts = { workspace = true }
 pdfcraft-model = { workspace = true }
 thiserror = { workspace = true }
-# Display order of right-to-left lines in added text; already in the tree via the interface.
+kurbo = { workspace = true }
+# Display order of right-to-left lines in added text, and reading and writing order in Edit text;
+# already in the tree via the interface.
 unicode-bidi = "0.3"
 
 [dev-dependencies]

crates/edit/src/added.rs

@@ -11,7 +11,7 @@
 use std::collections::{HashMap, HashSet};
 
 use pdfcraft_cos::{Dict, Document, ObjRef, Object, PdfString, Stream};
-use pdfcraft_fonts::{GlyphError, GlyphOutline, ShapedCluster, arabic_glyph, helvetica_width, literal, shape_arabic, win_ansi};
+use pdfcraft_fonts::{GlyphError, GlyphOutline, ShapedCluster, ShapedScript, Std14, literal, shape_arabic, shape_thai, shaped_glyph, win_ansi};
 use unicode_bidi::{Level, ParagraphBidiInfo};
 
 use crate::{EditError, MarkKind, check, contents, n, page_list, place_tagged};
@@ -65,15 +65,30 @@ impl Family {
         (family, s.contains("Bold"), s.contains("Italic") || s.contains("Oblique"))
     }
 
-    /// Approximate advance width of `s` (standard-14 metrics are not bundled: Helvetica widths,
-    /// scaled for Times; Courier is monospaced).
-    pub fn width(self, s: &str, size: f64, bold: bool) -> f64 {
-        let w = match self {
-            Family::Courier => s.chars().count() as f64 * 0.6 * size,
-            Family::Times => helvetica_width(s, size) * 0.9,
-            Family::Helvetica => helvetica_width(s, size),
-        };
-        if bold { w * 1.05 } else { w }
+    /// Advance width of `s` at `size` points, from the published standard-14 metrics.
+    ///
+    /// `italic` matters: the item is written out as the oblique/italic face (see [`Family::base_font`]),
+    /// whose published widths differ from the upright face (Times-Italic `A` is 611, Times-Roman 722).
+    pub fn width(self, s: &str, size: f64, bold: bool, italic: bool) -> f64 {
+        self.std14(bold, italic).text_width(s, size)
+    }
+
+    /// The standard-14 face this family means at the given style.
+    pub fn std14(self, bold: bool, italic: bool) -> Std14 {
+        match (self, bold, italic) {
+            (Family::Courier, false, false) => Std14::Courier,
+            (Family::Courier, true, false) => Std14::CourierBold,
+            (Family::Courier, false, true) => Std14::CourierOblique,
+            (Family::Courier, true, true) => Std14::CourierBoldOblique,
+            (Family::Times, false, false) => Std14::TimesRoman,
+            (Family::Times, true, false) => Std14::TimesBold,
+            (Family::Times, false, true) => Std14::TimesItalic,
+            (Family::Times, true, true) => Std14::TimesBoldItalic,
+            (Family::Helvetica, false, false) => Std14::Helvetica,
+            (Family::Helvetica, true, false) => Std14::HelveticaBold,
+            (Family::Helvetica, false, true) => Std14::HelveticaOblique,
+            (Family::Helvetica, true, true) => Std14::HelveticaBoldOblique,
+        }
     }
 }
 
@@ -225,17 +240,26 @@ fn wrapped(t: &AddedText) -> Vec<(String, bool)> {
     let mut out = Vec::new();
     for para in t.text.split('\n') {
         let arabic = para.chars().any(is_arabic);
+        let thai = para.chars().any(is_thai);
+        if thai
+            && !arabic
+            && let Ok(lines) = thai_lines(t, para, width)
+        {
+            out.extend(lines.into_iter().map(|line| (line, false)));
+            continue;
+        }
         let rtl = arabic && unicode_bidi::get_base_direction(para) == unicode_bidi::Direction::Rtl;
         // Arabic words are shaped one by one (joining stops at spaces), so a line's width is the
         // sum of its words' and shaping stays linear in the paragraph's length. The space is the
         // paragraph's; a space between Latin words is drawn in the item's font, a few hundredths
         // of an em apart.
-        let measure = |s: &str| if arabic { arabic_width(t, s, rtl) } else { t.family.width(s, t.size, t.bold) };
+        let measure = |s: &str| if arabic || thai { shaped_width(t, s, rtl) } else { t.family.width(s, t.size, t.bold, t.italic) };
         let space = measure(" ");
         let (mut line, mut line_w) = (String::new(), 0.0);
         for word in para.split(' ') {
             let candidate = if line.is_empty() { word.to_string() } else { format!("{line} {word}") };
-            let candidate_w = if arabic { if line.is_empty() { measure(word) } else { line_w + space + measure(word) } } else { measure(&candidate) };
+            let candidate_w =
+                if arabic || thai { if line.is_empty() { measure(word) } else { line_w + space + measure(word) } } else { measure(&candidate) };
             if !line.is_empty() && candidate_w > width {
                 out.push((std::mem::take(&mut line), rtl));
                 line = word.to_string();
@@ -250,6 +274,39 @@ fn wrapped(t: &AddedText) -> Vec<(String, bool)> {
     out
 }
 
+/// Thai wrapping at shaped cluster boundaries never detaches a tone/vowel mark from its base.
+/// This is glyph-safe wrapping, not dictionary-based Thai word segmentation.
+fn thai_lines(t: &AddedText, para: &str, width: f64) -> Result<Vec<String>, EditError> {
+    let (pieces, _) = shaped_layout(t, para, false)?;
+    let mut atoms = Vec::new();
+    for piece in pieces {
+        match piece {
+            Piece::Shaped(clusters) => atoms.extend(clusters.into_iter().map(|c| (c.text, c.advance * t.size))),
+            Piece::Latin(s) => atoms.extend(s.chars().map(|c| {
+                let text = c.to_string();
+                let w = t.family.width(&text, t.size, t.bold, t.italic);
+                (text, w)
+            })),
+        }
+    }
+    let mut lines = Vec::new();
+    let (mut line, mut used) = (String::new(), 0.0);
+    for (text, advance) in atoms {
+        if !line.is_empty() && used + advance > width {
+            lines.push(std::mem::take(&mut line));
+            used = 0.0;
+        }
+        line.push_str(&text);
+        used += advance;
+    }
+    lines.push(line);
+    Ok(lines)
+}
+
+fn is_thai(c: char) -> bool {
+    matches!(u32::from(c), 0x0E00..=0x0E7F)
+}
+
 /// Arabic letters, marks, digits and punctuation: an item with any of them is shaped with the
 /// craft-fonts Arabic face.
 fn is_arabic(c: char) -> bool {
@@ -260,6 +317,13 @@ fn is_arabic(c: char) -> bool {
 /// with the craft-fonts Arabic face (#125), or Arabic that the face can't draw (or that has no
 /// face to draw it). Page-content tools refuse such text; the Add-text editor keeps it open.
 pub fn first_undrawable(t: &AddedText) -> Option<char> {
+    if t.text.chars().any(is_thai) {
+        if let Some(c) = t.text.chars().find(|c| is_thai(*c) && !pdfcraft_fonts::thai_has(*c)) {
+            return Some(c);
+        }
+        let rest = AddedText { text: t.text.chars().filter(|c| !is_thai(*c)).collect(), ..t.clone() };
+        return first_undrawable(&rest);
+    }
     // Arabic that nothing can draw: there's no face, or the face lacks it.
     if let Some(c) = t.text.chars().find(|c| shaped_arabic(*c) && !pdfcraft_fonts::arabic_has(*c)) {
         return Some(c);
@@ -269,12 +333,12 @@ pub fn first_undrawable(t: &AddedText) -> Option<char> {
         // that is also how `draw` redraws an existing item, so it's checked that way.
         return t.text.split('\n').find_map(pdfcraft_fonts::first_non_win_ansi);
     }
-    // What `arabic_layout` leaves to the standard font, exactly as `draw_arabic` splits it.
+    // What `shaped_layout` leaves to the standard font, exactly as `draw_shaped` splits it.
     wrapped(t).into_iter().find_map(|(line, rtl)| {
-        let (pieces, _) = arabic_layout(t, &line, rtl).ok()?;
+        let (pieces, _) = shaped_layout(t, &line, rtl).ok()?;
         pieces.iter().find_map(|p| match p {
             Piece::Latin(s) => pdfcraft_fonts::first_non_win_ansi(s),
-            Piece::Arabic(_) => None,
+            Piece::Shaped(_) => None,
         })
     })
 }
@@ -305,16 +369,16 @@ fn mirrored(c: char) -> char {
     }
 }
 
-/// A piece of a line with Arabic text, in drawing order.
+/// A piece of a line with shaped text, in drawing order.
 enum Piece {
     /// Shown in the item's own standard font.
     Latin(String),
-    Arabic(Vec<ShapedCluster>),
+    Shaped(Vec<ShapedCluster>),
 }
 
-/// A line of an Arabic item in drawing order (the Unicode bidirectional algorithm, UAX #9), and
+/// A line of a shaped-text item in drawing order (the Unicode bidirectional algorithm, UAX #9), and
 /// its width at the item's size. `rtl` is its paragraph's direction.
-fn arabic_layout(t: &AddedText, line: &str, rtl: bool) -> Result<(Vec<Piece>, f64), EditError> {
+fn shaped_layout(t: &AddedText, line: &str, rtl: bool) -> Result<(Vec<Piece>, f64), EditError> {
     // unicode-bidi indexes the first level of a line, so an empty one would panic.
     if line.is_empty() {
         return Ok((Vec::new(), 0.0));
@@ -329,20 +393,30 @@ fn arabic_layout(t: &AddedText, line: &str, rtl: bool) -> Result<(Vec<Piece>, f6
         let Some(text) = line.get(run) else { continue };
         // Arabic letters take the Arabic face; so do spaces and punctuation between them, which the
         // shaper then mirrors. Latin text (and what the face lacks) keeps the item's font.
-        let mut segments: Vec<(bool, String)> = Vec::new();
+        let mut segments: Vec<(Option<ShapedScript>, String)> = Vec::new();
         for c in text.chars().filter(|c| !is_bidi_control(*c)) {
-            let arabic = is_arabic(c) || (run_rtl && !c.is_alphanumeric() && pdfcraft_fonts::arabic_has(c));
+            let script = if is_thai(c) {
+                Some(ShapedScript::Thai)
+            } else if is_arabic(c) || (run_rtl && !c.is_alphanumeric() && pdfcraft_fonts::arabic_has(c)) {
+                Some(ShapedScript::Arabic)
+            } else {
+                None
+            };
             match segments.last_mut() {
-                Some((kind, s)) if *kind == arabic => s.push(c),
-                _ => segments.push((arabic, c.to_string())),
+                Some((kind, s)) if *kind == script => s.push(c),
+                _ => segments.push((script, c.to_string())),
             }
         }
         if run_rtl {
             segments.reverse();
         }
-        for (arabic, s) in segments {
-            pieces.push(if arabic {
-                Piece::Arabic(shape_arabic(&s, run_rtl).map_err(|e| arabic_error(e, &s))?)
+        for (script, s) in segments {
+            pieces.push(if let Some(script) = script {
+                let shaped = match script {
+                    ShapedScript::Arabic => shape_arabic(&s, run_rtl).map_err(|e| arabic_error(e, &s))?,
+                    ShapedScript::Thai => shape_thai(&s).map_err(|e| thai_error(e, &s))?,
+                };
+                Piece::Shaped(shaped)
             } else if run_rtl {
                 Piece::Latin(s.chars().rev().map(mirrored).collect())
             } else {
@@ -353,17 +427,17 @@ fn arabic_layout(t: &AddedText, line: &str, rtl: bool) -> Result<(Vec<Piece>, f6
     let width = pieces
         .iter()
         .map(|p| match p {
-            Piece::Latin(s) => t.family.width(s, t.size, t.bold),
-            Piece::Arabic(clusters) => clusters.iter().map(|c| c.advance).sum::<f64>() * t.size,
+            Piece::Latin(s) => t.family.width(s, t.size, t.bold, t.italic),
+            Piece::Shaped(clusters) => clusters.iter().map(|c| c.advance).sum::<f64>() * t.size,
         })
         .sum();
     Ok((pieces, width))
 }
 
-/// The width of `s` in an Arabic item; the item's font's estimate if it can't be shaped (drawing
+/// The width of `s` in a shaped-text item; the item's font's estimate if it can't be shaped (drawing
 /// then reports why).
-fn arabic_width(t: &AddedText, s: &str, rtl: bool) -> f64 {
-    arabic_layout(t, s, rtl).map(|(_, w)| w).unwrap_or_else(|_| t.family.width(s, t.size, t.bold))
+fn shaped_width(t: &AddedText, s: &str, rtl: bool) -> f64 {
+    shaped_layout(t, s, rtl).map(|(_, w)| w).unwrap_or_else(|_| t.family.width(s, t.size, t.bold, t.italic))
 }
 
 fn arabic_error(e: GlyphError, text: &str) -> EditError {
@@ -376,6 +450,16 @@ fn arabic_error(e: GlyphError, text: &str) -> EditError {
     })
 }
 
+fn thai_error(e: GlyphError, text: &str) -> EditError {
+    EditError::Invalid(match e {
+        GlyphError::NoFont => {
+            "Thai text needs a Thai font in this build; rebuild with CRAFT_FONTS_DIR pointing to craft-fonts with a Thai face".into()
+        }
+        GlyphError::Missing => format!("the Thai font can't show \"{text}\""),
+        GlyphError::TooComplex => "the Thai glyphs are too complex; use a shorter text box".into(),
+    })
+}
+
 /// The box a text item occupies (height from its lines).
 pub fn text_rect(t: &AddedText) -> [f64; 4] {
     let r = norm(t.rect);
@@ -391,31 +475,31 @@ fn font_name(base: &str) -> String {
 /// per 240 distinct glyphs it needs.
 const GLYPHS_PER_FONT: usize = 240;
 
-/// A line of an Arabic item after layout: its text, whether its paragraph runs right to left, its
-/// pieces in drawing order and its width at the item's size.
+/// A line of a shaped-text item after layout: its text, whether its paragraph runs right to left,
+/// its pieces in drawing order and its width at the item's size.
 type LaidLine = (String, bool, Vec<Piece>, f64);
 
-/// Draw a text item that has Arabic in it. Each line is laid out in display order; Arabic glyphs
+/// Draw a text item that has Arabic or Thai in it. Each line is laid out in display order; Arabic glyphs
 /// come from Type 3 fonts drawn from the craft-fonts face's outlines (no font file is embedded),
 /// with a ToUnicode map for copy and search. Other text uses the item's standard font.
-fn draw_arabic(doc: &mut Document, t: &AddedText, taken: &Dict, fonts: &mut Dict, out: &mut Vec<u8>) -> Result<(), EditError> {
+fn draw_shaped(doc: &mut Document, t: &AddedText, taken: &Dict, fonts: &mut Dict, out: &mut Vec<u8>) -> Result<(), EditError> {
     let laid = wrapped(t)
         .into_iter()
-        .map(|(line, rtl)| arabic_layout(t, &line, rtl).map(|(pieces, w)| (line, rtl, pieces, w)))
+        .map(|(line, rtl)| shaped_layout(t, &line, rtl).map(|(pieces, w)| (line, rtl, pieces, w)))
         .collect::<Result<Vec<_>, _>>()?;
-    draw_laid_arabic(doc, t, &laid, taken, fonts, out, arabic_glyph)
+    draw_laid_shaped(doc, t, &laid, taken, fonts, out, shaped_glyph)
 }
 
-/// [`draw_arabic`] for lines that are already laid out. `outline` is the source of glyph outlines
-/// (the craft-fonts face, or a stand-in in tests).
-fn draw_laid_arabic(
+/// [`draw_shaped`] for lines that are already laid out. `outline` is the source of glyph outlines
+/// for a script's face (the craft-fonts faces, or a stand-in in tests).
+fn draw_laid_shaped(
     doc: &mut Document,
     t: &AddedText,
     laid: &[LaidLine],
     taken: &Dict,
     fonts: &mut Dict,
     out: &mut Vec<u8>,
-    outline: impl Fn(u32) -> Result<GlyphOutline, GlyphError>,
+    outline: impl Fn(ShapedScript, u32) -> Result<GlyphOutline, GlyphError>,
 ) -> Result<(), EditError> {
     let r = text_rect(t);
     let latin = font_name(t.family.base_font(t.bold, t.italic));
@@ -424,7 +508,7 @@ fn draw_laid_arabic(
     let mut keys: Vec<&ShapedCluster> = Vec::new();
     let mut index: HashMap<ClusterKey, usize> = HashMap::new();
     for c in laid.iter().flat_map(|(_, _, pieces, _)| pieces).flat_map(|p| match p {
-        Piece::Arabic(clusters) => clusters.as_slice(),
+        Piece::Shaped(clusters) => clusters.as_slice(),
         Piece::Latin(_) => &[],
     }) {
         index.entry(cluster_key(c)).or_insert_with(|| {
@@ -432,12 +516,16 @@ fn draw_laid_arabic(
             keys.len() - 1
         });
     }
+
     // Every outline is read before anything is written, so a failure leaves the document as it was.
     let mut outlines = HashMap::new();
     for c in &keys {
         for (id, _) in &c.glyphs {
-            if !outlines.contains_key(id) {
-                outlines.insert(*id, outline(*id).map_err(|e| arabic_error(e, &c.text))?);
+            if let std::collections::hash_map::Entry::Vacant(entry) = outlines.entry((c.script, *id)) {
+                entry.insert(outline(c.script, *id).map_err(|e| match c.script {
+                    ShapedScript::Arabic => arabic_error(e, &c.text),
+                    ShapedScript::Thai => thai_error(e, &c.text),
+                })?);
             }
         }
     }
@@ -445,7 +533,7 @@ fn draw_laid_arabic(
     let mut taken_names: HashSet<Vec<u8>> = taken.iter().chain(fonts.iter()).map(|(name, _)| name.clone()).collect();
     let mut names = Vec::new();
     for chunk in keys.chunks(GLYPHS_PER_FONT) {
-        let font = type3_arabic(doc, chunk, &outlines);
+        let font = type3_shaped(doc, chunk, &outlines);
         // A name no font on the page has, so items never replace each other's fonts (object
         // numbers alone don't do: a full save renumbers objects but keeps resource names).
         let mut name = format!("PCAr{}", font.num);
@@ -461,6 +549,10 @@ fn draw_laid_arabic(
     let [cr, cg, cb] = t.color.map(|v| v.clamp(0.0, 1.0));
     out.extend(format!("BT {} {} {} rg\n", n(cr), n(cg), n(cb)).bytes());
     for (i, (line, rtl, pieces, w)) in laid.iter().enumerate() {
+        // Shaped glyphs are painted in visual order. Keep the original line's typing order
+        // explicitly, including marks, ligatures, digits and mixed-script punctuation.
+        let logical: String = line.encode_utf16().map(|u| format!("{u:04X}")).collect();
+        out.extend(format!("/Span <</ActualText <FEFF{logical}>>> BDC\n").bytes());
         let spaces = line.matches(' ').count();
         // Justified: the spaces of every line but the last stretch to fill the box.
         let tw = if t.align == Align::Justify && i + 1 < laid.len() && spaces > 0 { ((r[2] - r[0]) - w).max(0.0) / spaces as f64 } else { 0.0 };
@@ -481,9 +573,9 @@ fn draw_laid_arabic(
                     out.extend(literal(&win_ansi(s)));
                     out.extend_from_slice(b" Tj\n");
                     current = Some(latin.as_str());
-                    pen += t.family.width(s, t.size, t.bold) + tw * s.matches(' ').count() as f64;
+                    pen += t.family.width(s, t.size, t.bold, t.italic) + tw * s.matches(' ').count() as f64;
                 }
-                Piece::Arabic(clusters) => {
+                Piece::Shaped(clusters) => {
                     for c in clusters {
                         let Some(&k) = index.get(&cluster_key(c)) else { continue };
                         let Some(name) = names.get(k / GLYPHS_PER_FONT) else { continue };
@@ -501,6 +593,7 @@ fn draw_laid_arabic(
                 }
             }
         }
+        out.extend_from_slice(b"EMC\n");
     }
     out.extend_from_slice(b"ET\n");
     Ok(())
@@ -508,14 +601,14 @@ fn draw_laid_arabic(
 
 /// What makes two clusters the same Type 3 glyph: text, glyphs, offsets and advance (bit for bit;
 /// equal clusters come from the same font units).
-type ClusterKey<'a> = (&'a str, Vec<(u32, u64, u64)>, u64);
+type ClusterKey<'a> = (ShapedScript, &'a str, Vec<(u32, u64, u64)>, u64);
 
 fn cluster_key(c: &ShapedCluster) -> ClusterKey<'_> {
-    (c.text.as_str(), c.glyphs.iter().map(|(id, [x, y])| (*id, x.to_bits(), y.to_bits())).collect(), c.advance.to_bits())
+    (c.script, c.text.as_str(), c.glyphs.iter().map(|(id, [x, y])| (*id, x.to_bits(), y.to_bits())).collect(), c.advance.to_bits())
 }
 
-/// A Type 3 font with `clusters` as codes 1…, each drawn from the Arabic face's glyph `outlines`.
-fn type3_arabic(doc: &mut Document, clusters: &[&ShapedCluster], outlines: &HashMap<u32, GlyphOutline>) -> ObjRef {
+/// A Type 3 font with `clusters` as codes 1…, each drawn from its script face's glyph `outlines`.
+fn type3_shaped(doc: &mut Document, clusters: &[&ShapedCluster], outlines: &HashMap<(ShapedScript, u32), GlyphOutline>) -> ObjRef {
     let mut charprocs = Dict::new();
     let mut differences = vec![Object::Int(1)];
     let mut widths = Vec::with_capacity(clusters.len());
@@ -527,7 +620,7 @@ fn type3_arabic(doc: &mut Document, clusters: &[&ShapedCluster], outlines: &Hash
         let mut paths = Vec::new();
         let mut ink: Option<[f64; 4]> = None;
         for (id, [dx, dy]) in &c.glyphs {
-            let Some(g) = outlines.get(id) else { continue };
+            let Some(g) = outlines.get(&(c.script, *id)) else { continue };
             for contour in &g.contours {
                 for (j, p) in contour.iter().enumerate() {
                     paths.extend(format!("{} {} {}\n", n((p[0] + dx) * 1000.0), n((p[1] + dy) * 1000.0), if j == 0 { "m" } else { "l" }).bytes());
@@ -564,7 +657,18 @@ fn type3_arabic(doc: &mut Document, clusters: &[&ShapedCluster], outlines: &Hash
     }
     cmap.push_str("endcmap\nCMapName currentdict /CMap defineresource pop\nend\nend\n");
     let cmap = doc.add(Object::Stream(Stream::flate(Dict::new(), cmap.as_bytes())));
-    let family = pdfcraft_fonts::document_arabic_font().map_or("Arabic", |f| f.family);
+    // The face's family when every glyph comes from one script; without the face, the script's
+    // name (as Arabic items were always named).
+    let family = match clusters.first().map(|c| c.script).filter(|s| clusters.iter().all(|c| c.script == *s)) {
+        Some(script) => script.font().map_or(
+            match script {
+                ShapedScript::Arabic => "Arabic",
+                ShapedScript::Thai => "Thai",
+            },
+            |f| f.family,
+        ),
+        None => "PdfCraft Shaped Text",
+    };
     let mut descriptor = Dict::new();
     descriptor.set(b"Type".to_vec(), Object::name("FontDescriptor"));
     descriptor.set(b"FontName".to_vec(), Object::name(&family.replace(' ', "")));
@@ -611,8 +715,8 @@ fn draw(doc: &mut Document, c: &Content, view: [f64; 6], taken: &Dict, existing:
             }
             let mut fonts = Dict::new();
             fonts.set(name.clone().into_bytes(), Object::Dict(font));
-            if t.text.chars().any(is_arabic) && (pdfcraft_fonts::document_arabic_font().is_some() || !existing) {
-                draw_arabic(doc, t, taken, &mut fonts, &mut out)?;
+            if t.text.chars().any(is_thai) || (t.text.chars().any(is_arabic) && (pdfcraft_fonts::document_arabic_font().is_some() || !existing)) {
+                draw_shaped(doc, t, taken, &mut fonts, &mut out)?;
                 res.set(b"Font".to_vec(), Object::Dict(fonts));
                 out.extend_from_slice(b"Q\n");
                 return Ok((out, res));
@@ -622,7 +726,7 @@ fn draw(doc: &mut Document, c: &Content, view: [f64; 6], taken: &Dict, existing:
             let [cr, cg, cb] = t.color.map(|v| v.clamp(0.0, 1.0));
             out.extend(format!("BT /{name} {} Tf {} {} {} rg\n", n(t.size), n(cr), n(cg), n(cb)).bytes());
             for (i, line) in lines(t).iter().enumerate() {
-                let w = t.family.width(line, t.size, t.bold);
+                let w = t.family.width(line, t.size, t.bold, t.italic);
                 let x = match t.align {
                     Align::Left | Align::Justify => r[0],
                     Align::Center => r[0] + ((r[2] - r[0]) - w) / 2.0,
@@ -840,11 +944,17 @@ fn validate(c: &Content) -> Result<(), EditError> {
             if (r[2] - r[0]).abs() < 1.0 {
                 return Err(EditError::Invalid("the text box is too narrow".into()));
             }
+            if t.text.chars().any(is_thai) && pdfcraft_fonts::document_thai_font().is_none() {
+                return Err(thai_error(GlyphError::NoFont, &t.text));
+            }
             // Without the Arabic face, `draw` decides for the Arabic letters themselves (#403): a new
             // item is refused with what's missing, and one that already holds Arabic stays movable.
             // Everything else in it is drawn in the standard font, so it still has to fit.
             let undrawable = if t.text.chars().any(shaped_arabic) && pdfcraft_fonts::document_arabic_font().is_none() {
-                t.text.split('\n').find_map(|line| line.chars().find(|c| !shaped_arabic(*c) && !pdfcraft_fonts::win_ansi_encodable(*c)))
+                t.text.split('\n').find_map(|line| {
+                    line.chars()
+                        .find(|c| !(shaped_arabic(*c) || is_thai(*c) && pdfcraft_fonts::thai_has(*c) || pdfcraft_fonts::win_ansi_encodable(*c)))
+                })
             } else {
                 first_undrawable(t)
             };
@@ -963,7 +1073,7 @@ pub fn delete_content(doc: &mut Document, page: usize, index: usize) -> Result<(
     Ok(())
 }
 
-/// The Type 3 fonts an Arabic item's stream shows text with. Each item has its own (`draw_arabic`
+/// The Type 3 fonts an Arabic item's stream shows text with. Each item has its own (`draw_shaped`
 /// names them so), so they go when the item is replaced or deleted.
 fn own_fonts(doc: &Document, obj: ObjRef) -> Vec<Vec<u8>> {
     let Object::Stream(s) = &*doc.get(obj) else { return Vec::new() };

crates/edit/src/added/arabic_tests.rs

@@ -6,20 +6,25 @@ use std::cell::Cell;
 
 use super::*;
 
-/// The fingerprint of an item below the old limit, from the code before the change: its content
-/// stream, its new fonts and every object of the document.
-const SMALL_ITEM_FINGERPRINT: u64 = 14_135_892_979_695_233_112;
+/// Regression fingerprint for the small-item fixture: drawing bytes, font map and document
+/// objects, with generated streams decoded so Flate backend selection cannot change the hash.
+// Re-pinned when the standard-14 metrics became exact (F1). The Latin run in the fingerprinted
+// item is "Hi " in Helvetica 12pt: the old character-class guess called H 680, i 260 and space
+// 260 (14.4pt), where the published metrics are 722, 222 and 278 (14.664pt). The Arabic clusters
+// that follow therefore start 0.264pt further right, which is the whole point of F1 -- the glyphs
+// now land where the font says they do. Nothing about the Arabic path changed.
+const SMALL_ITEM_FINGERPRINT: u64 = 9_200_256_185_091_160_371;
 
 /// A cluster that shows one character with the single glyph `id`, at `advance` em.
 fn cluster(id: u32, advance: f64) -> ShapedCluster {
-    ShapedCluster { glyphs: vec![(id, [0.0, 0.0])], advance, text: "ب".into() }
+    ShapedCluster { script: ShapedScript::Arabic, glyphs: vec![(id, [0.0, 0.0])], advance, text: "ب".into() }
 }
 
 /// One run of `clusters` as a line of an item at `item()`'s size.
 fn line(clusters: Vec<ShapedCluster>, rtl: bool) -> LaidLine {
     let text = clusters.iter().map(|c| c.text.as_str()).collect();
     let width = clusters.iter().map(|c| c.advance).sum::<f64>() * item().size;
-    (text, rtl, vec![Piece::Arabic(clusters)], width)
+    (text, rtl, vec![Piece::Shaped(clusters)], width)
 }
 
 /// A glyph outline: a box on the baseline, `advance` em wide.
@@ -43,6 +48,25 @@ fn snapshot(doc: &Document) -> Vec<u8> {
     bytes
 }
 
+/// Serialize generated objects with decoded stream bytes so the golden does not depend on which
+/// Flate backend Cargo's unified dependency features select for the test binary. Only the raw
+/// bytes (and so `/Length`, which the writer takes from them) are normalised: `/Filter` and
+/// `/DecodeParms` stay in the hash, so a change that stops compressing generated streams, or
+/// switches filters, still fails the golden.
+fn golden_snapshot(doc: &Document) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    for num in doc.object_numbers() {
+        let mut obj = (*doc.get(ObjRef { num, generation: doc.generation(num) })).clone();
+        if let Object::Stream(ref mut stream) = obj {
+            let decoded = stream.decoded_strict().expect("generated stream decodes");
+            stream.raw = decoded.into();
+        }
+        pdfcraft_cos::serialize(&obj, &mut bytes);
+        bytes.push(b'\n');
+    }
+    bytes
+}
+
 /// The fonts an item drew, in creation order, with their glyph counts.
 fn fonts_of(doc: &Document, fonts: &Dict) -> Vec<(Vec<u8>, usize)> {
     fonts
@@ -85,7 +109,7 @@ fn an_item_past_the_old_glyph_limit_gets_a_font_per_240_glyphs() {
     let laid = vec![line((0..n).map(|i| cluster(i as u32 + 1, 0.5)).collect(), false)];
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_| Ok(boxed(0.5)));
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| Ok(boxed(0.5)));
     assert!(drawn.is_ok(), "{drawn:?}");
     let made = fonts_of(&doc, &fonts);
     let mut expected = vec![GLYPHS_PER_FONT; 16];
@@ -108,7 +132,7 @@ fn an_outline_missing_from_a_later_font_leaves_the_document_unchanged() {
     let before = snapshot(&doc);
     let missing = n as u32;
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |id| {
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, id| {
         if id == missing { Err(GlyphError::Missing) } else { Ok(boxed(0.5)) }
     });
     assert!(matches!(&drawn, Err(EditError::Invalid(msg)) if msg.contains("can't show")), "{drawn:?}");
@@ -120,21 +144,45 @@ fn an_outline_missing_from_a_later_font_leaves_the_document_unchanged() {
 fn an_item_below_the_old_limit_is_drawn_exactly_as_before() {
     // A left-to-right line with a Latin run, a space and a two-glyph cluster, then a right-to-left
     // line. Glyphs repeat across the two lines and share one font.
-    let space = ShapedCluster { glyphs: vec![(6, [0.0, 0.0])], advance: 0.25, text: " ".into() };
-    let ligature = ShapedCluster { glyphs: vec![(4, [0.0, 0.0]), (5, [-0.1, 0.2])], advance: 0.6, text: "لا".into() };
+    let space = ShapedCluster { script: ShapedScript::Arabic, glyphs: vec![(6, [0.0, 0.0])], advance: 0.25, text: " ".into() };
+    let ligature = ShapedCluster { script: ShapedScript::Arabic, glyphs: vec![(4, [0.0, 0.0]), (5, [-0.1, 0.2])], advance: 0.6, text: "لا".into() };
     let mixed: LaidLine =
-        ("Hi ب".into(), false, vec![Piece::Latin("Hi ".into()), Piece::Arabic(vec![cluster(1, 0.5), cluster(2, 0.5), space, ligature])], 4.0);
+        ("Hi ب".into(), false, vec![Piece::Latin("Hi ".into()), Piece::Shaped(vec![cluster(1, 0.5), cluster(2, 0.5), space, ligature])], 4.0);
     let rtl = line(vec![cluster(2, 0.5), cluster(9, 0.75)], true);
     let laid = vec![mixed, rtl];
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |id| Ok(boxed(0.5 + f64::from(id) * 0.01)));
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, id| Ok(boxed(0.5 + f64::from(id) * 0.01)));
     assert!(drawn.is_ok(), "{drawn:?}");
     assert_eq!(fonts.len(), 1);
+    // The injected outlines are fixed; only the descriptor's family comes from craft-fonts.
+    // Check that metadata separately, then normalize those two fields to the original golden.
+    // ActualText is new metadata: check each line's value and remove only its added wrappers
+    // before hashing. Drawing bytes and font objects still match the original golden exactly.
+    let family = pdfcraft_fonts::document_arabic_font().map_or("Arabic", |face| face.family);
+    for (_, font) in fonts.iter() {
+        let descriptor = doc.dict(font).unwrap().get(b"FontDescriptor").and_then(Object::as_ref).unwrap();
+        let dict = doc.dict(&Object::Ref(descriptor)).unwrap();
+        assert_eq!(dict.name(b"FontName"), Some(family.replace(' ', "").as_bytes()));
+        assert_eq!(dict.get(b"FontFamily").and_then(Object::as_string).unwrap().bytes, family.as_bytes());
+        doc.update_dict(descriptor, |d| {
+            d.set(b"FontName".to_vec(), Object::name("Arabic"));
+            d.set(b"FontFamily".to_vec(), Object::String(PdfString::literal(b"Arabic".to_vec())));
+        })
+        .unwrap();
+    }
     let mut bytes = out.clone();
+    for (line, ..) in &laid {
+        let hex: String = line.encode_utf16().map(|u| format!("{u:04X}")).collect();
+        let header = format!("/Span <</ActualText <FEFF{hex}>>> BDC\n").into_bytes();
+        let start = bytes.windows(header.len()).position(|w| w == header).expect("each line has its logical text");
+        bytes.drain(start..start + header.len());
+        let end = bytes.windows(4).position(|w| w == b"EMC\n").expect("each ActualText span closes");
+        bytes.drain(end..end + 4);
+    }
     pdfcraft_cos::serialize(&Object::Dict(fonts.clone()), &mut bytes);
-    bytes.extend(snapshot(&doc));
-    assert_eq!(fnv1a(&bytes), SMALL_ITEM_FINGERPRINT, "output changed; the golden is the code before the sharding change");
+    bytes.extend(golden_snapshot(&doc));
+    assert_eq!(fnv1a(&bytes), SMALL_ITEM_FINGERPRINT, "small-item output changed");
 }
 
 #[test]
@@ -145,7 +193,7 @@ fn long_text_with_few_distinct_glyphs_needs_one_font() {
     let reads = Cell::new(0usize);
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_| {
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| {
         reads.set(reads.get() + 1);
         Ok(boxed(0.5))
     });
@@ -159,13 +207,18 @@ fn long_text_with_few_distinct_glyphs_needs_one_font() {
 fn distinct_clusters_past_the_old_limit_share_their_glyph_outlines() {
     // 3,841 different clusters (their advances differ) built from four glyphs: four outlines are read.
     let clusters: Vec<ShapedCluster> = (0..3_841u32)
-        .map(|i| ShapedCluster { glyphs: vec![(1 + i % 4, [0.0, 0.0])], advance: 0.5 + f64::from(i) * 1e-6, text: "ب".into() })
+        .map(|i| ShapedCluster {
+            script: ShapedScript::Arabic,
+            glyphs: vec![(1 + i % 4, [0.0, 0.0])],
+            advance: 0.5 + f64::from(i) * 1e-6,
+            text: "ب".into(),
+        })
         .collect();
     let laid = vec![line(clusters, false)];
     let reads = Cell::new(0usize);
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_| {
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| {
         reads.set(reads.get() + 1);
         Ok(boxed(0.5))
     });
@@ -178,18 +231,18 @@ fn distinct_clusters_past_the_old_limit_share_their_glyph_outlines() {
 #[test]
 fn hostile_clusters_draw_empty_or_fail_without_changing_the_document() {
     // A cluster with no glyphs and no text draws nothing, but it is still one glyph of a font.
-    let empty = ShapedCluster { glyphs: Vec::new(), advance: 0.0, text: String::new() };
+    let empty = ShapedCluster { script: ShapedScript::Arabic, glyphs: Vec::new(), advance: 0.0, text: String::new() };
     let laid = vec![line(vec![empty, cluster(1, 0.5)], false)];
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_| Ok(boxed(0.5)));
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| Ok(boxed(0.5)));
     assert!(drawn.is_ok(), "{drawn:?}");
     assert_eq!(glyphs_shown(&out).len(), 2);
     // A glyph id the face doesn't have fails the item before anything is written.
     let before = snapshot(&doc);
     let laid = vec![line(vec![cluster(1, 0.5), cluster(u32::MAX, 0.5)], false)];
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |id| {
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, id| {
         if id == u32::MAX { Err(GlyphError::Missing) } else { Ok(boxed(0.5)) }
     });
     assert!(drawn.is_err());
@@ -202,7 +255,7 @@ fn a_font_name_the_page_already_uses_is_not_reused() {
     let laid = vec![line(vec![cluster(1, 0.5)], false)];
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_| Ok(boxed(0.5)));
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| Ok(boxed(0.5)));
     assert!(drawn.is_ok(), "{drawn:?}");
     let first = fonts_of(&doc, &fonts)[0].0.clone();
     // The same item on a page whose resources already use that name.
@@ -210,7 +263,7 @@ fn a_font_name_the_page_already_uses_is_not_reused() {
     taken.set(first.clone(), Object::Null);
     let mut doc = Document::new_empty();
     let (mut fonts, mut out) = (Dict::new(), Vec::new());
-    let drawn = draw_laid_arabic(&mut doc, &item(), &laid, &taken, &mut fonts, &mut out, |_| Ok(boxed(0.5)));
+    let drawn = draw_laid_shaped(&mut doc, &item(), &laid, &taken, &mut fonts, &mut out, |_, _| Ok(boxed(0.5)));
     assert!(drawn.is_ok(), "{drawn:?}");
     let second = fonts_of(&doc, &fonts)[0].0.clone();
     assert_ne!(second, first);

crates/edit/src/bidi.rs

@@ -0,0 +1,364 @@
+//! Right-to-left text in Edit text (Hebrew, Arabic).
+//!
+//! A content stream draws glyphs left to right, so a producer writes a right-to-left line in
+//! *visual* order: `בדיוק` is drawn, and read back from the stream, as `קוידב`. The
+//! editor works on *logical* (typing) order instead: [`to_logical`] turns a line read from the
+//! page into the order a person types it, and [`to_visual`] turns a line about to be written back
+//! into the order it must be drawn in (UAX #9 through `unicode-bidi`).
+//!
+//! Visual order doesn't always determine one logical order (`abc 12 םולש` is both `abc שלום 12`
+//! and `abc 12 שלום`), so [`to_logical`] tries a few readings and keeps the first that draws back
+//! exactly as the page did. Lines without right-to-left characters are returned unchanged.
+//!
+//! Combining marks (Hebrew points, Arabic harakat) stay after their base character in both
+//! orders. Brackets drawn in a right-to-left run are mirrored, as UAX #9 L4 mirrors them on
+//! display.
+
+use unicode_bidi::{BidiInfo, Level};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum Class {
+    Rtl,
+    Ltr,
+    Number,
+    Neutral,
+}
+
+/// Letters, marks and punctuation of the right-to-left scripts' blocks (digits excepted).
+pub(crate) fn is_rtl(c: char) -> bool {
+    !is_digit(c) && matches!(u32::from(c), 0x0590..=0x08FF | 0xFB1D..=0xFDFF | 0xFE70..=0xFEFC | 0x1_0800..=0x1_0FFF | 0x1_E800..=0x1_EFFF)
+}
+
+/// The Hebrew block and the Hebrew presentation forms.
+pub(crate) fn is_hebrew(c: char) -> bool {
+    matches!(u32::from(c), 0x0590..=0x05FF | 0xFB1D..=0xFB4F)
+}
+
+/// Hebrew points and cantillation marks (niqqud, te'amim): combining, drawn on their letter.
+pub(crate) fn is_hebrew_mark(c: char) -> bool {
+    matches!(u32::from(c), 0x0591..=0x05BD | 0x05BF | 0x05C1..=0x05C2 | 0x05C4..=0x05C5 | 0x05C7 | 0xFB1E)
+}
+
+fn is_digit(c: char) -> bool {
+    c.is_ascii_digit() || matches!(c, '\u{0660}'..='\u{0669}' | '\u{06F0}'..='\u{06F9}')
+}
+
+/// Combining marks that ride on the character before them.
+fn is_mark(c: char) -> bool {
+    is_hebrew_mark(c)
+        || matches!(
+            u32::from(c),
+            0x0300..=0x036F | 0x0610..=0x061A | 0x064B..=0x065F | 0x0670 | 0x06D6..=0x06DC | 0x06DF..=0x06E4 | 0x06E7..=0x06E8 | 0x06EA..=0x06ED | 0xFE20..=0xFE2F
+        )
+}
+
+/// Direction marks, embeddings, overrides and isolates: they steer the reordering and are not drawn.
+fn is_bidi_control(c: char) -> bool {
+    matches!(c, '\u{061C}' | '\u{200E}' | '\u{200F}' | '\u{202A}'..='\u{202E}' | '\u{2066}'..='\u{2069}')
+}
+
+fn mirrored(c: char) -> char {
+    match c {
+        '(' => ')',
+        ')' => '(',
+        '[' => ']',
+        ']' => '[',
+        '{' => '}',
+        '}' => '{',
+        '<' => '>',
+        '>' => '<',
+        '«' => '»',
+        '»' => '«',
+        other => other,
+    }
+}
+
+fn class(c: char) -> Class {
+    if is_digit(c) {
+        Class::Number
+    } else if is_rtl(c) {
+        Class::Rtl
+    } else if c.is_alphabetic() {
+        Class::Ltr
+    } else {
+        Class::Neutral
+    }
+}
+
+/// A base character with the combining marks after it.
+#[derive(Clone, Debug)]
+struct Cluster {
+    text: String,
+    class: Class,
+}
+
+impl Cluster {
+    /// The cluster with its base mirrored (marks stay as they are).
+    fn mirror(&self) -> Cluster {
+        let mut chars = self.text.chars();
+        let mut text: String = chars.next().map(mirrored).into_iter().collect();
+        text.extend(chars);
+        Cluster { text, class: self.class }
+    }
+}
+
+fn clusters(s: &str) -> Vec<Cluster> {
+    let mut out: Vec<Cluster> = Vec::new();
+    for c in s.chars() {
+        match out.last_mut() {
+            Some(last) if is_mark(c) => last.text.push(c),
+            _ => out.push(Cluster { text: c.to_string(), class: class(c) }),
+        }
+    }
+    out
+}
+
+/// Whether the line reads right to left as a whole: more right-to-left letters than
+/// left-to-right ones. Counting (not the first strong character) gives the same answer for a
+/// line in either order, so reading a line and writing it back agree on its direction.
+pub(crate) fn rtl_base(text: &str) -> bool {
+    let (mut r, mut l) = (0usize, 0usize);
+    for c in text.chars() {
+        match class(c) {
+            Class::Rtl if !is_mark(c) => r = r.saturating_add(1),
+            Class::Ltr if !is_mark(c) => l = l.saturating_add(1),
+            _ => {}
+        }
+    }
+    r > l
+}
+
+/// Maximal ranges that start and end with a `member` and hold only members and `bridge`s.
+fn runs(cl: &[Cluster], member: impl Fn(&Cluster) -> bool, bridge: impl Fn(&[Cluster], usize) -> bool) -> Vec<std::ops::Range<usize>> {
+    let mut out = Vec::new();
+    let mut i = 0;
+    while i < cl.len() {
+        if !cl.get(i).is_some_and(&member) {
+            i += 1;
+            continue;
+        }
+        let mut end = i;
+        let mut j = i + 1;
+        while let Some(c) = cl.get(j) {
+            if member(c) {
+                end = j;
+            } else if !bridge(cl, j) {
+                break;
+            }
+            j += 1;
+        }
+        out.push(i..end + 1);
+        i = end + 1;
+    }
+    out
+}
+
+/// One separator between two digits (`1,000`, `12:30`, `3.5`, `1/2`, `5-6`) keeps a number whole.
+fn number_separator(cl: &[Cluster], j: usize) -> bool {
+    let digit = |k: Option<usize>| k.and_then(|k| cl.get(k)).is_some_and(|c| c.class == Class::Number);
+    cl.get(j).is_some_and(|c| matches!(c.text.as_str(), "." | "," | ":" | "/" | "-" | "+")) && digit(j.checked_sub(1)) && digit(Some(j + 1))
+}
+
+fn reverse_mirrored(cl: &mut [Cluster]) {
+    cl.reverse();
+    for c in cl.iter_mut() {
+        *c = c.mirror();
+    }
+}
+
+/// One reading of `visual` in logical order. `wide` lets runs of the other direction swallow the
+/// spaces and numbers between their words; narrow keeps numbers and words apart.
+fn reading(visual: &[Cluster], rtl: bool, wide: bool) -> String {
+    let mut cl = visual.to_vec();
+    let number = |c: &Cluster| c.class == Class::Number;
+    if rtl {
+        // Everything reads right to left, except left-to-right words and numbers.
+        reverse_mirrored(&mut cl);
+        let ltr = |c: &Cluster| matches!(c.class, Class::Ltr | Class::Number);
+        let bridge =
+            |cl: &[Cluster], j: usize| cl.get(j).is_some_and(|c| c.class == Class::Neutral) && (wide || !neutral_between_word_and_number(cl, j));
+        for r in runs(&cl, ltr, bridge) {
+            if let Some(run) = cl.get_mut(r) {
+                reverse_mirrored(run);
+            }
+        }
+    } else {
+        // Left to right, except right-to-left stretches; numbers inside those read left to right.
+        let rtl_member = |c: &Cluster| c.class == Class::Rtl;
+        let bridge = |cl: &[Cluster], j: usize| cl.get(j).is_some_and(|c| c.class == Class::Neutral || (wide && c.class == Class::Number));
+        for r in runs(&cl, rtl_member, bridge) {
+            if let Some(run) = cl.get_mut(r) {
+                reverse_mirrored(run);
+                for n in runs(run, number, number_separator) {
+                    if let Some(num) = run.get_mut(n) {
+                        reverse_mirrored(num);
+                    }
+                }
+            }
+        }
+    }
+    cl.iter().map(|c| c.text.as_str()).collect()
+}
+
+/// Whether the neutral at `j` sits between a left-to-right word on one side and a number on the
+/// other (UAX #9 resolves such a space to the line's direction, splitting the run).
+fn neutral_between_word_and_number(cl: &[Cluster], j: usize) -> bool {
+    let strong = |mut k: usize, step: isize| -> Option<Class> {
+        loop {
+            k = k.checked_add_signed(step)?;
+            match cl.get(k)?.class {
+                Class::Neutral => continue,
+                other => return Some(other),
+            }
+        }
+    };
+    matches!((strong(j, -1), strong(j, 1)), (Some(Class::Ltr), Some(Class::Number)) | (Some(Class::Number), Some(Class::Ltr)))
+}
+
+/// A line read from a content stream (drawn left to right), in logical order.
+pub fn to_logical(visual: &str) -> String {
+    if !visual.chars().any(is_rtl) {
+        return visual.to_owned();
+    }
+    let cl = clusters(visual);
+    let rtl = rtl_base(visual);
+    let readings = [reading(&cl, rtl, true), reading(&cl, rtl, false)];
+    // Readings that draw back exactly as the page did; of those, one whose brackets pair up
+    // (`12 (PDF)`, not `PDF) 12)`), else the first.
+    let exact: Vec<&String> = readings.iter().filter(|r| to_visual(r) == visual).collect();
+    let chosen = exact.iter().find(|r| balanced(r)).or(exact.first()).map_or_else(|| readings[0].clone(), |r| (*r).clone());
+    // Some producers (LibreOffice) map a bracket drawn in a right-to-left run to the character it
+    // stands for, not the shape drawn, so mirroring it again turns it inside out: `)טיוטה(`.
+    let swapped: String = chosen.chars().map(mirrored).collect();
+    if !balanced(&chosen) && balanced(&swapped) { swapped } else { chosen }
+}
+
+/// Whether every closing bracket closes an open one.
+fn balanced(text: &str) -> bool {
+    let mut open: Vec<char> = Vec::new();
+    for c in text.chars() {
+        match c {
+            '(' | '[' | '{' => open.push(c),
+            ')' | ']' | '}' if open.pop() != Some(mirrored(c)) => return false,
+            _ => {}
+        }
+    }
+    open.is_empty()
+}
+
+/// A line in logical order, in the order it must be drawn (left to right), without the bidi
+/// controls fonts can't draw.
+pub fn to_visual(logical: &str) -> String {
+    let text: String = logical.chars().filter(|c| !is_bidi_control(*c)).collect();
+    if !text.chars().any(is_rtl) {
+        return text;
+    }
+    let level = if rtl_base(&text) { Level::rtl() } else { Level::ltr() };
+    let info = BidiInfo::new(&text, Some(level));
+    let mut out = String::with_capacity(text.len());
+    for para in &info.paragraphs {
+        let (levels, runs) = info.visual_runs(para, para.range.clone());
+        for run in runs {
+            let rtl = levels.get(run.start).is_some_and(|l| l.is_rtl());
+            // Runs lie on character boundaries; a missing slice is skipped, never a panic.
+            let Some(piece) = text.get(run) else { continue };
+            if rtl {
+                for c in clusters(piece).iter().rev() {
+                    out.push_str(&c.mirror().text);
+                }
+            } else {
+                out.push_str(piece);
+            }
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// What a producer writes into the content stream for `logical`.
+    fn drawn(logical: &str) -> String {
+        to_visual(logical)
+    }
+
+    #[test]
+    fn the_reported_word_reads_back_in_typing_order() {
+        // The report: Edit text showed "בדיוק" (exactly) reversed.
+        assert_eq!(drawn("בדיוק"), "קוידב");
+        assert_eq!(to_logical("קוידב"), "בדיוק");
+    }
+
+    #[test]
+    fn hebrew_sentences_numbers_latin_and_brackets_round_trip() {
+        for logical in [
+            "שלום עולם",
+            "עמוד 12 מתוך 40",
+            "מחיר: 1,250.50 ₪",
+            "השעה 12:30",
+            "קובץ PDF חדש",
+            "שלום (עולם)",
+            "ראו [1] ו-[2]",
+            "גרסה 2.0 של PdfCraft נוסחה",
+            "hello שלום עולם world",
+            "abc שלום def",
+            "שלום abc def עולם",
+            "Report: דוח שנתי 2026",
+            "שלום עולם, עמוד 12 (PDF)",
+            "פרק 3 (מבוא)",
+            "שָׁלוֹם עוֹלָם",
+            "مرحبا بالعالم",
+        ] {
+            let visual = drawn(logical);
+            assert_ne!(visual, logical, "{logical:?} should be reordered");
+            assert_eq!(to_visual(&to_logical(&visual)), visual, "{logical:?} drawn as {visual:?}");
+            assert_eq!(to_logical(&visual), logical, "{logical:?} drawn as {visual:?}");
+        }
+    }
+
+    #[test]
+    fn ambiguous_lines_still_draw_back_the_same() {
+        // "abc 12 םולש" is both "abc שלום 12" and "abc 12 שלום"; either must draw the same.
+        for logical in ["abc שלום 12", "שלום 12 abc", "a (ב) c", "דוח Report 2026", "(1) שלום"] {
+            let visual = drawn(logical);
+            assert_eq!(to_visual(&to_logical(&visual)), visual, "{logical:?}");
+        }
+    }
+
+    #[test]
+    fn brackets_mapped_to_their_logical_character_pair_up() {
+        // LibreOffice draws "(טיוטה)" with ToUnicode giving the logical brackets: `)הטויט(`.
+        assert_eq!(to_logical(")הטויט("), "(טיוטה)");
+        // Brackets mapped to the shape drawn read the same.
+        assert_eq!(to_logical("(הטויט)"), "(טיוטה)");
+    }
+
+    #[test]
+    fn left_to_right_text_is_untouched() {
+        for s in ["", "Hello, world (1)", "日本語のテキスト", "Ünïcödé 12:30"] {
+            assert_eq!(to_logical(s), s);
+            assert_eq!(to_visual(s), s);
+        }
+    }
+
+    #[test]
+    fn points_stay_on_their_letter() {
+        // Each point follows its letter in both orders.
+        let visual = drawn("שָׁלוֹם");
+        let first = visual.chars().next();
+        assert_eq!(first, Some('ם'));
+        assert!(visual.contains("לוֹ") || visual.contains("וֹל"), "{visual:?}");
+        assert_eq!(to_logical(&visual), "שָׁלוֹם");
+    }
+
+    #[test]
+    fn controls_are_not_drawn_and_hostile_input_does_not_panic() {
+        assert_eq!(to_visual("\u{200F}שלום\u{202B}"), "םולש");
+        for s in ["\u{05B8}", "\u{05B8}\u{05B8}א", "(((", "א\u{0300}", "1-", "-1א", "א\n\tב", "\u{202E}abc"] {
+            let _ = to_visual(&to_logical(s));
+        }
+        let long = "שלום 12 abc (x) ".repeat(2_000);
+        assert_eq!(to_visual(&to_logical(&to_visual(&long))), to_visual(&long));
+    }
+}

crates/edit/src/flatten.rs

@@ -97,9 +97,45 @@ pub fn flatten_fill_sign(doc: &mut Document, pages: &[usize]) -> Result<usize, E
     flatten_which(doc, pages, Which::FillSign)
 }
 
+/// The first annotation flattening would turn into page content with `?` in it, before anything
+/// changes: one whose appearance PdfCraft drew with `?` for characters its fonts can't draw
+/// (`pdfcraft_fonts::UNDRAWN_MARK`: a form field's value, a comment's text), or a comment without
+/// an appearance whose text the standard fonts can't draw. Its page (0-based), whether it is a
+/// form field, and the character.
+fn undrawn_on(doc: &Document, all: &[pdfcraft_model::Page], pages: &[usize], which: Which) -> Option<(usize, bool, char)> {
+    for &i in pages {
+        let list = all.get(i)?.dict.get(b"Annots").map(|a| doc.resolve(a)).and_then(|a| a.as_array().cloned()).unwrap_or_default();
+        for entry in &list {
+            let Some(d) = doc.resolve(entry).as_dict().cloned() else { continue };
+            let flags = d.get(b"F").and_then(|f| doc.resolve(f).as_int()).unwrap_or(0);
+            if !selected(doc, &d, which) || flags & (HIDDEN | NO_VIEW) != 0 {
+                continue;
+            }
+            let widget = d.name(b"Subtype") == Some(b"Widget");
+            let drawn = pdfcraft_fonts::undrawn_mark(&d);
+            let would_draw = || (!widget && appearance(doc, &d).is_none()).then(|| pdfcraft_annot::appearance::undrawable_text(&d)).flatten();
+            if let Some(c) = drawn.or_else(|| would_draw().map(|(_, c)| c)) {
+                return Some((i, widget, c));
+            }
+        }
+    }
+    None
+}
+
 fn flatten_which(doc: &mut Document, pages: &[usize], which: Which) -> Result<usize, EditError> {
     let all = page_list(doc);
     check(pages, all.len())?;
+    // `?` in an appearance can still be fixed (a field's value, a comment's text are stored as
+    // typed, and other viewers redraw form fields); flattened, it would be the page for good.
+    if let Some((i, widget, c)) = undrawn_on(doc, &all, pages, which) {
+        return Err(EditError::Invalid(format!(
+            "can't flatten {} on page {}: it shows ? in place of \"{}\" (U+{:04X}), which its font can't draw, and flattening would make that permanent (nothing was flattened); change or remove that text first",
+            if widget { "a form field" } else { "a comment" },
+            i + 1,
+            c.escape_debug(),
+            u32::from(c)
+        )));
+    }
     let mut drawn = 0;
     let mut removed_widgets: HashSet<ObjRef> = HashSet::new();
     for &i in pages {
@@ -132,7 +168,9 @@ fn flatten_which(doc: &mut Document, pages: &[usize], which: Which) -> Result<us
             if flags & (HIDDEN | NO_VIEW) != 0 || appearance(doc, &d).is_some() {
                 continue;
             }
-            // A subtype this build cannot draw only fails here; it is still removed below.
+            // A subtype this build cannot draw fails here and is kept below, so the comment is
+            // not deleted with nothing drawn in its place. (Text the standard fonts can't draw
+            // was refused before anything changed: `undrawn_on`.)
             let _ = pdfcraft_annot::set_appearance(doc, r);
         }
         for (k, entry) in list.iter().enumerate() {
@@ -148,6 +186,7 @@ fn flatten_which(doc: &mut Document, pages: &[usize], which: Which) -> Result<us
                 continue;
             }
             let rect = nums(doc, d.get(b"Rect")).filter(|r| r.len() == 4).map(|r| [r[0].min(r[2]), r[1].min(r[3]), r[0].max(r[2]), r[1].max(r[3])]);
+            let mut drew = false;
             if let (Some(ap), Some(rect)) = (appearance(doc, d), rect) {
                 let form = doc.get(ap).as_dict().cloned().unwrap_or_default();
                 if let Some(m) = placement(doc, &form, rect) {
@@ -155,8 +194,15 @@ fn flatten_which(doc: &mut Document, pages: &[usize], which: Which) -> Result<us
                     content.push_str(&format!("q {} {} {} {} {} {} cm /{name} Do Q\n", n(m[0]), n(m[1]), n(m[2]), n(m[3]), n(m[4]), n(m[5])));
                     xobjects.set(name.into_bytes(), Object::Ref(ap));
                     drawn += 1;
+                    drew = true;
                 }
             }
+            // A comment whose ink was not written into the page stays. Removing it would drop
+            // the annotation (a cloudy square this builder cannot draw, for example) with nothing
+            // left on the page. Widgets are form fields: flattening still removes them.
+            if !widget && !drew {
+                continue;
+            }
             match entry.as_ref() {
                 Some(r) => {
                     gone.insert(r);
@@ -212,33 +258,49 @@ fn flatten_which(doc: &mut Document, pages: &[usize], which: Which) -> Result<us
             })?,
         }
     }
-    if !removed_widgets.is_empty() {
-        prune_fields(doc, &removed_widgets)?;
+    // A field whose widgets are on no page has nothing to draw, but flattening every field of the
+    // document must still take it out of the form, or other software keeps seeing one (#1470).
+    let orphans = matches!(which, Which::Comments { fields: true, .. }) && (0..all.len()).all(|i| pages.contains(&i));
+    if !removed_widgets.is_empty() || orphans {
+        let on_page: HashSet<ObjRef> = page_list(doc)
+            .iter()
+            .filter_map(|p| p.dict.get(b"Annots").map(|a| doc.resolve(a)).and_then(|a| a.as_array().cloned()))
+            .flatten()
+            .filter_map(|e| e.as_ref())
+            .collect();
+        prune_fields(doc, &removed_widgets, orphans.then_some(&on_page))?;
     }
     Ok(drawn)
 }
 
-/// Remove flattened widgets from the AcroForm field tree, and fields left without widgets.
-fn prune_fields(doc: &mut Document, widgets: &HashSet<ObjRef>) -> Result<(), EditError> {
+/// Remove flattened widgets from the AcroForm field tree, and fields left without widgets. With
+/// `on_page`, also the widgets (fields without kids) that are on no page.
+fn prune_fields(doc: &mut Document, widgets: &HashSet<ObjRef>, on_page: Option<&HashSet<ObjRef>>) -> Result<(), EditError> {
     let Some(root) = doc.root() else { return Ok(()) };
     let Some(af) = doc.get(root).as_dict().and_then(|d| d.get(b"AcroForm").cloned()) else { return Ok(()) };
     let af_ref = af.as_ref();
     let mut af_dict = doc.resolve(&af).as_dict().cloned().unwrap_or_default();
     let fields = af_dict.get(b"Fields").map(|f| doc.resolve(f)).and_then(|f| f.as_array().cloned()).unwrap_or_default();
     // Returns whether the node survives.
-    fn keep(doc: &mut Document, r: ObjRef, widgets: &HashSet<ObjRef>, depth: usize) -> bool {
+    fn keep(doc: &mut Document, r: ObjRef, widgets: &HashSet<ObjRef>, on_page: Option<&HashSet<ObjRef>>, depth: usize) -> bool {
         if widgets.contains(&r) || depth > 64 {
             return depth > 64;
         }
         let Some(d) = doc.get(r).as_dict().cloned() else { return true };
-        let Some(kids) = d.get(b"Kids").map(|k| doc.resolve(k)).and_then(|k| k.as_array().cloned()) else { return true };
-        let survivors: Vec<Object> = kids.iter().filter(|k| k.as_ref().is_none_or(|kr| keep(doc, kr, widgets, depth + 1))).cloned().collect();
+        let Some(kids) = d.get(b"Kids").map(|k| doc.resolve(k)).and_then(|k| k.as_array().cloned()) else {
+            return on_page.is_none_or(|p| p.contains(&r));
+        };
+        let survivors: Vec<Object> =
+            kids.iter().filter(|k| k.as_ref().is_none_or(|kr| keep(doc, kr, widgets, on_page, depth + 1))).cloned().collect();
         if survivors.len() != kids.len() {
             let _ = doc.update_dict(r, |d| d.set(b"Kids".to_vec(), Object::Array(survivors.clone())));
         }
         !survivors.is_empty()
     }
-    let survivors: Vec<Object> = fields.iter().filter(|f| f.as_ref().is_none_or(|r| keep(doc, r, widgets, 0))).cloned().collect();
+    let survivors: Vec<Object> = fields.iter().filter(|f| f.as_ref().is_none_or(|r| keep(doc, r, widgets, on_page, 0))).cloned().collect();
+    if survivors.len() == fields.len() && widgets.is_empty() {
+        return Ok(()); // only looked for fields on no page, and there were none
+    }
     af_dict.set(b"Fields".to_vec(), Object::Array(survivors));
     match af_ref {
         Some(r) => doc.set(r, Object::Dict(af_dict)),

crates/edit/src/images.rs

@@ -3,8 +3,10 @@
 //! `q … cm … Q` with the extra transform), replace (it draws another XObject in the same place),
 //! or delete. Only the stream that draws it is rewritten, as a new object.
 
+use kurbo::{BezPath, Point, Shape};
 use pdfcraft_content::{Matrix, Op, parse, serialize_ops};
 use pdfcraft_cos::{Dict, Document, ObjRef, Object, Stream};
+use std::sync::Arc;
 
 use crate::EditError;
 
@@ -13,6 +15,11 @@ use crate::EditError;
 pub struct PageImage {
     /// Its box in user space.
     pub rect: [f64; 4],
+    /// Visible frame after page and analytic path bounds. Hit testing also respects curve
+    /// interiors, winding rules and holes, rather than intercepting their empty areas.
+    pub visible_rect: Option<[f64; 4]>,
+    /// Current page/path clip in user space. A private crop transforms with its image.
+    pub clip_rect: Option<[f64; 4]>,
     /// The placement: image unit square or Form coordinates → user space.
     pub matrix: [f64; 6],
     /// The XObject resource name and object.
@@ -27,6 +34,41 @@ pub struct PageImage {
     op: usize,
     /// CTM before `Do`, excluding a Form's own Matrix.
     draw_matrix: [f64; 6],
+    clips: Vec<ClipPath>,
+}
+
+impl PageImage {
+    /// Whether a user-space point belongs to the placed artwork and every active clip.
+    pub fn contains(&self, point: [f64; 2]) -> bool {
+        if !point.iter().all(|v| v.is_finite()) {
+            return false;
+        }
+        let Some(bounds) = self.visible_rect else {
+            return false;
+        };
+        if point[0] < bounds[0] || point[0] > bounds[2] || point[1] < bounds[1] || point[1] > bounds[3] {
+            return false;
+        }
+        if !self.is_form {
+            let Some(inverse) = Matrix(self.matrix).invert() else {
+                return false;
+            };
+            let (x, y) = inverse.apply(point[0], point[1]);
+            if !(0.0..=1.0).contains(&x) || !(0.0..=1.0).contains(&y) {
+                return false;
+            }
+        }
+        self.clips.iter().all(|clip| {
+            let winding = clip.path.winding(Point::new(point[0], point[1]));
+            if clip.even_odd { winding % 2 != 0 } else { winding != 0 }
+        })
+    }
+}
+
+#[derive(Clone, Debug, PartialEq)]
+struct ClipPath {
+    path: Arc<BezPath>,
+    even_odd: bool,
 }
 
 fn streams(doc: &Document, page: &Dict) -> Vec<(Object, Vec<u8>)> {
@@ -59,6 +101,113 @@ fn xobjects(doc: &Document, page: &Dict) -> Dict {
         .unwrap_or_default()
 }
 
+fn intersection(a: [f64; 4], b: [f64; 4]) -> Option<[f64; 4]> {
+    let r = [a[0].max(b[0]), a[1].max(b[1]), a[2].min(b[2]), a[3].min(b[3])];
+    (r.iter().all(|v| v.is_finite()) && r[2] > r[0] && r[3] > r[1]).then_some(r)
+}
+
+#[derive(Clone)]
+struct Placement {
+    matrix: Matrix,
+    clip: [f64; 4],
+    clips: Vec<ClipPath>,
+}
+
+/// Path coordinates are transformed when constructed; q/Q save clips, not the current path.
+struct ImageState {
+    placement: Placement,
+    stack: Vec<Placement>,
+    path: BezPath,
+    pending_clip: Option<bool>,
+}
+
+impl ImageState {
+    fn new(matrix: Matrix, clip: [f64; 4], clips: Vec<ClipPath>) -> Self {
+        Self { placement: Placement { matrix, clip, clips }, stack: Vec::new(), path: BezPath::new(), pending_clip: None }
+    }
+
+    fn point(&self, x: f64, y: f64) -> Point {
+        let (x, y) = self.placement.matrix.apply(x, y);
+        Point::new(x, y)
+    }
+
+    fn apply(&mut self, op: &Op) -> Result<(), EditError> {
+        if matches!(op.op.as_slice(), b"cm" | b"m" | b"l" | b"c" | b"v" | b"y" | b"re")
+            && op.operands.iter().any(|v| v.as_f64().is_some_and(|v| !v.is_finite() || v.abs() > 1e12))
+        {
+            return Err(EditError::Invalid("the image path contains invalid coordinates".into()));
+        }
+        if self.path.elements().len() > 16384 || self.stack.len() > 4096 || self.placement.clips.len() > 256 {
+            return Err(EditError::Invalid("the image clip or graphics state exceeds its complexity budget".into()));
+        }
+        match op.op.as_slice() {
+            b"q" => self.stack.push(self.placement.clone()),
+            b"Q" => {
+                if let Some(saved) = self.stack.pop() {
+                    self.placement = saved;
+                }
+            }
+            b"cm" => {
+                if let Some(m) = op.nums::<6>() {
+                    self.placement.matrix = Matrix(m).then(&self.placement.matrix);
+                }
+            }
+            b"m" => {
+                if let Some([x, y]) = op.nums::<2>() {
+                    self.path.move_to(self.point(x, y));
+                }
+            }
+            b"l" => {
+                if let Some([x, y]) = op.nums::<2>() {
+                    self.path.line_to(self.point(x, y));
+                }
+            }
+            b"c" => {
+                if let Some([x1, y1, x2, y2, x3, y3]) = op.nums::<6>() {
+                    self.path.curve_to(self.point(x1, y1), self.point(x2, y2), self.point(x3, y3));
+                }
+            }
+            b"v" => {
+                if let Some([x1, y1, x2, y2]) = op.nums::<4>()
+                    && let Some(current) = self.path.elements().last().and_then(|e| e.end_point())
+                {
+                    self.path.curve_to(current, self.point(x1, y1), self.point(x2, y2));
+                }
+            }
+            b"y" => {
+                if let Some([x1, y1, x2, y2]) = op.nums::<4>() {
+                    let end = self.point(x2, y2);
+                    self.path.curve_to(self.point(x1, y1), end, end);
+                }
+            }
+            b"h" => self.path.close_path(),
+            b"re" => {
+                if let Some([x, y, w, h]) = op.nums::<4>() {
+                    self.path.move_to(self.point(x, y));
+                    self.path.line_to(self.point(x + w, y));
+                    self.path.line_to(self.point(x + w, y + h));
+                    self.path.line_to(self.point(x, y + h));
+                    self.path.close_path();
+                }
+            }
+            b"W" => self.pending_clip = Some(false),
+            b"W*" => self.pending_clip = Some(true),
+            b"n" | b"S" | b"s" | b"f" | b"F" | b"f*" | b"B" | b"B*" | b"b" | b"b*" => {
+                if let Some(even_odd) = self.pending_clip.take() {
+                    // Filling/clipping implicitly closes open subpaths. BezPath's winding
+                    // follows the same rule, and its bounds use cubic extrema, not controls.
+                    let bounds = self.path.bounding_box();
+                    self.placement.clip = intersection(self.placement.clip, [bounds.x0, bounds.y0, bounds.x1, bounds.y1]).unwrap_or([0.0; 4]);
+                    self.placement.clips.push(ClipPath { path: Arc::new(std::mem::take(&mut self.path)), even_odd });
+                }
+                self.path = BezPath::new();
+            }
+            _ => {}
+        }
+        Ok(())
+    }
+}
+
 /// The images and Form artwork page `page` (0-based) draws, in drawing order.
 /// Forms stay intact: no traversal or rewriting of their internal objects is needed.
 pub fn page_images(doc: &Document, page: usize) -> Result<Vec<PageImage>, EditError> {
@@ -66,76 +215,70 @@ pub fn page_images(doc: &Document, page: usize) -> Result<Vec<PageImage>, EditEr
     let xo = xobjects(doc, &p.dict);
     let mut out = Vec::new();
     // The graphics state carries over from one stream to the next.
-    let mut ctm = Matrix::IDENTITY;
-    let mut stack = Vec::new();
+    let mut state = ImageState::new(Matrix::IDENTITY, p.crop(doc), Vec::new());
     for (si, (_, data)) in streams(doc, &p.dict).into_iter().enumerate() {
         for (i, op) in parse(&data).ops.iter().enumerate() {
-            match op.op.as_slice() {
-                b"q" => stack.push(ctm),
-                b"Q" => ctm = stack.pop().unwrap_or(ctm),
-                b"cm" => {
-                    if let Some(m) = op.nums::<6>() {
-                        ctm = Matrix(m).then(&ctm);
-                    }
-                }
-                b"Do" => {
-                    let Some(name) = op.name(0) else { continue };
-                    let Some(resource) = xo.get(name) else { continue };
-                    let obj = doc.resolve(resource);
-                    let Object::Stream(s) = &*obj else { continue };
-                    let is_form = s.dict.name(b"Subtype") == Some(b"Form");
-                    let (matrix, bounds) = if is_form {
-                        let Some(bounds) = s.dict.get(b"BBox").map(|v| doc.resolve(v)).and_then(|v| {
-                            v.as_array().and_then(|a| {
-                                if a.len() != 4 {
-                                    return None;
-                                }
-                                let mut b = [0.0; 4];
-                                for (n, v) in b.iter_mut().zip(a) {
-                                    *n = v.as_f64()?;
-                                }
-                                Some(b)
-                            })
-                        }) else {
-                            continue;
-                        };
-                        let matrix = match s.dict.get(b"Matrix") {
-                            Some(v) => {
-                                let v = doc.resolve(v);
-                                let Some(m) = v.as_array().and_then(|a| Matrix::from_operands(a)) else { continue };
-                                m
+            state.apply(op)?;
+            let ctm = state.placement.matrix;
+            if op.is("Do") {
+                let Some(name) = op.name(0) else { continue };
+                let Some(resource) = xo.get(name) else { continue };
+                let obj = doc.resolve(resource);
+                let Object::Stream(s) = &*obj else { continue };
+                let is_form = s.dict.name(b"Subtype") == Some(b"Form");
+                let (matrix, bounds) = if is_form {
+                    let Some(bounds) = s.dict.get(b"BBox").map(|v| doc.resolve(v)).and_then(|v| {
+                        v.as_array().and_then(|a| {
+                            if a.len() != 4 {
+                                return None;
                             }
-                            None => Matrix::IDENTITY,
-                        };
-                        (matrix.then(&ctm), bounds)
-                    } else if s.dict.name(b"Subtype") == Some(b"Image") {
-                        (ctm, [0.0, 0.0, 1.0, 1.0])
-                    } else {
+                            let mut b = [0.0; 4];
+                            for (n, v) in b.iter_mut().zip(a) {
+                                *n = v.as_f64()?;
+                            }
+                            Some(b)
+                        })
+                    }) else {
                         continue;
                     };
-                    let rect = matrix.bbox(bounds);
-                    if !bounds.iter().chain(matrix.0.iter()).chain(rect.iter()).all(|v| v.is_finite())
-                        || bounds[2] <= bounds[0]
-                        || bounds[3] <= bounds[1]
-                        || rect[2] <= rect[0]
-                        || rect[3] <= rect[1]
-                    {
-                        continue;
-                    }
-                    out.push(PageImage {
-                        rect,
-                        matrix: matrix.0,
-                        name: String::from_utf8_lossy(name).into_owned(),
-                        object: resource.as_ref(),
-                        is_form,
-                        width: if is_form { 0 } else { s.dict.int(b"Width").unwrap_or(0).clamp(0, u32::MAX as i64) as u32 },
-                        height: if is_form { 0 } else { s.dict.int(b"Height").unwrap_or(0).clamp(0, u32::MAX as i64) as u32 },
-                        stream: si,
-                        op: i,
-                        draw_matrix: ctm.0,
-                    });
+                    let matrix = match s.dict.get(b"Matrix") {
+                        Some(v) => {
+                            let v = doc.resolve(v);
+                            let Some(m) = v.as_array().and_then(|a| Matrix::from_operands(a)) else { continue };
+                            m
+                        }
+                        None => Matrix::IDENTITY,
+                    };
+                    (matrix.then(&ctm), bounds)
+                } else if s.dict.name(b"Subtype") == Some(b"Image") {
+                    (ctm, [0.0, 0.0, 1.0, 1.0])
+                } else {
+                    continue;
+                };
+                let rect = matrix.bbox(bounds);
+                if !bounds.iter().chain(matrix.0.iter()).chain(rect.iter()).all(|v| v.is_finite())
+                    || bounds[2] <= bounds[0]
+                    || bounds[3] <= bounds[1]
+                    || rect[2] <= rect[0]
+                    || rect[3] <= rect[1]
+                {
+                    continue;
                 }
-                _ => {}
+                out.push(PageImage {
+                    rect,
+                    visible_rect: intersection(rect, state.placement.clip),
+                    clip_rect: Some(state.placement.clip),
+                    matrix: matrix.0,
+                    name: String::from_utf8_lossy(name).into_owned(),
+                    object: resource.as_ref(),
+                    is_form,
+                    width: if is_form { 0 } else { s.dict.int(b"Width").unwrap_or(0).clamp(0, u32::MAX as i64) as u32 },
+                    height: if is_form { 0 } else { s.dict.int(b"Height").unwrap_or(0).clamp(0, u32::MAX as i64) as u32 },
+                    stream: si,
+                    op: i,
+                    draw_matrix: ctm.0,
+                    clips: state.placement.clips.clone(),
+                });
             }
         }
     }
@@ -153,65 +296,73 @@ pub fn reading_images(doc: &Document, page: usize) -> Result<Vec<PageImage>, Edi
         path: Vec<ObjRef>,
         visits: usize,
     }
-    struct State {
-        ctm: Matrix,
-        stack: Vec<Matrix>,
-    }
-    fn walk(doc: &Document, data: &[u8], resources: &Dict, st: &mut State, stream: usize, forms: &mut Forms, out: &mut Vec<PageImage>) {
+    fn walk(
+        doc: &Document,
+        data: &[u8],
+        resources: &Dict,
+        st: &mut ImageState,
+        stream: usize,
+        forms: &mut Forms,
+        out: &mut Vec<PageImage>,
+    ) -> Result<(), EditError> {
         let xo = resources.get(b"XObject").map(|x| doc.resolve(x)).and_then(|x| x.as_dict().cloned()).unwrap_or_default();
-        let (ctm, stack) = (&mut st.ctm, &mut st.stack);
         for (i, op) in parse(data).ops.iter().enumerate() {
-            match op.op.as_slice() {
-                b"q" => stack.push(*ctm),
-                b"Q" => *ctm = stack.pop().unwrap_or(*ctm),
-                b"cm" => {
-                    if let Some(m) = op.nums::<6>() {
-                        *ctm = Matrix(m).then(ctm);
+            st.apply(op)?;
+            let ctm = st.placement.matrix;
+            if op.is("Do") {
+                let Some(name) = op.name(0) else { continue };
+                if let Some(form) = crate::text::form_call(doc, resources, name, ctm, &forms.path, &mut forms.visits) {
+                    if let Some(r) = form.obj {
+                        forms.path.push(r);
                     }
+                    let bounds =
+                        xo.get(name).map(|o| doc.resolve(o)).and_then(|o| o.as_dict().and_then(|d| d.get(b"BBox")).map(|b| doc.resolve(b))).and_then(
+                            |b| {
+                                let a = b.as_array()?;
+                                let [x0, y0, x1, y1] = a.as_slice() else { return None };
+                                Some(form.ctm.bbox([x0.as_f64()?, y0.as_f64()?, x1.as_f64()?, y1.as_f64()?]))
+                            },
+                        );
+                    let clip = bounds.map_or(st.placement.clip, |b| intersection(st.placement.clip, b).unwrap_or([0.0; 4]));
+                    let mut inner = ImageState::new(form.ctm, clip, st.placement.clips.clone());
+                    walk(doc, &form.data, &form.resources, &mut inner, stream, forms, out)?;
+                    if form.obj.is_some() {
+                        forms.path.pop();
+                    }
+                    continue;
                 }
-                b"Do" => {
-                    let Some(name) = op.name(0) else { continue };
-                    if let Some(form) = crate::text::form_call(doc, resources, name, *ctm, &forms.path, &mut forms.visits) {
-                        if let Some(r) = form.obj {
-                            forms.path.push(r);
-                        }
-                        let mut inner = State { ctm: form.ctm, stack: Vec::new() };
-                        walk(doc, &form.data, &form.resources, &mut inner, stream, forms, out);
-                        if form.obj.is_some() {
-                            forms.path.pop();
-                        }
-                        continue;
-                    }
-                    let Some(r) = xo.get(name).and_then(Object::as_ref) else { continue };
-                    let obj = doc.get(r);
-                    let Object::Stream(s) = &*obj else { continue };
-                    if s.dict.name(b"Subtype") != Some(b"Image") {
-                        continue;
-                    }
-                    out.push(PageImage {
-                        rect: ctm.bbox([0.0, 0.0, 1.0, 1.0]),
-                        matrix: ctm.0,
-                        name: String::from_utf8_lossy(name).into_owned(),
-                        object: Some(r),
-                        is_form: false,
-                        width: s.dict.int(b"Width").unwrap_or(0).max(0) as u32,
-                        height: s.dict.int(b"Height").unwrap_or(0).max(0) as u32,
-                        stream,
-                        op: i,
-                        draw_matrix: ctm.0,
-                    });
+                let Some(r) = xo.get(name).and_then(Object::as_ref) else { continue };
+                let obj = doc.get(r);
+                let Object::Stream(s) = &*obj else { continue };
+                if s.dict.name(b"Subtype") != Some(b"Image") {
+                    continue;
                 }
-                _ => {}
+                out.push(PageImage {
+                    rect: ctm.bbox([0.0, 0.0, 1.0, 1.0]),
+                    visible_rect: intersection(ctm.bbox([0.0, 0.0, 1.0, 1.0]), st.placement.clip),
+                    clip_rect: Some(st.placement.clip),
+                    matrix: ctm.0,
+                    name: String::from_utf8_lossy(name).into_owned(),
+                    object: Some(r),
+                    is_form: false,
+                    width: s.dict.int(b"Width").unwrap_or(0).max(0) as u32,
+                    height: s.dict.int(b"Height").unwrap_or(0).max(0) as u32,
+                    stream,
+                    op: i,
+                    draw_matrix: ctm.0,
+                    clips: st.placement.clips.clone(),
+                });
             }
         }
+        Ok(())
     }
     let p = page_of(doc, page)?;
     let res = p.dict.get(b"Resources").map(|r| doc.resolve(r)).and_then(|r| r.as_dict().cloned()).unwrap_or_default();
     let mut out = Vec::new();
-    let mut st = State { ctm: Matrix::IDENTITY, stack: Vec::new() };
+    let mut st = ImageState::new(Matrix::IDENTITY, p.crop(doc), Vec::new());
     let mut forms = Forms { path: Vec::new(), visits: 0 };
     for (si, (_, data)) in streams(doc, &p.dict).into_iter().enumerate() {
-        walk(doc, &data, &res, &mut st, si, &mut forms, &mut out);
+        walk(doc, &data, &res, &mut st, si, &mut forms, &mut out)?;
     }
     Ok(out)
 }
@@ -284,33 +435,14 @@ pub fn change_image(doc: &mut Document, page: usize, index: usize, change: &Imag
     let all = streams(doc, &p.dict);
     let (obj, data) = all.get(img.stream).cloned().ok_or_else(|| EditError::Invalid("the image stream is missing".into()))?;
     let mut ops = parse(&data).ops;
-    let original = ops.get(img.op).cloned().ok_or_else(|| EditError::Invalid("the image operation is missing".into()))?;
+    if ops.get(img.op).is_none() {
+        return Err(EditError::Invalid("the image operation is missing".into()));
+    }
     let mut resources = None;
-    let mut clip_move = None;
     let replacement: Vec<Op> = match change {
         ImageChange::Delete => Vec::new(),
         ImageChange::Transform(t) => {
-            if !t.iter().all(|v| v.is_finite()) {
-                return Err(EditError::Invalid("the image transform must be finite".into()));
-            }
-            // New CTM = placement × T; as a `cm` before the Do: M = P · T · P⁻¹.
-            let pm = Matrix(img.draw_matrix);
-            let inv = pm.invert().ok_or_else(|| EditError::Invalid("the image has no area".into()))?;
-            let m = pm.then(&Matrix(*t)).then(&inv);
-            if !m.0.iter().all(|v| v.is_finite()) {
-                return Err(EditError::Invalid("the image transform is too large".into()));
-            }
-            // `q re W n cm Do Q` clips only this image: move the clip with it instead of leaving it behind.
-            if let Some((at, cm)) = exclusive_clip(&ops, img.op) {
-                if let Some(c) = clip_matrix(Matrix(img.draw_matrix), cm, Matrix(*t)).filter(|c| c.0.iter().all(|v| v.is_finite())) {
-                    clip_move = Some((at, Op::new("cm", c.0.iter().map(|v| pdfcraft_content::num(*v)).collect())));
-                    vec![original]
-                } else {
-                    return Err(EditError::Invalid("the image transform is too large".into()));
-                }
-            } else {
-                vec![Op::new("q", vec![]), Op::new("cm", m.0.iter().map(|v| pdfcraft_content::num(*v)).collect()), original, Op::new("Q", vec![])]
-            }
+            return transform_image(doc, &p, &all, &img, *t);
         }
         ImageChange::Replace(r) => {
             if img.is_form {
@@ -328,9 +460,6 @@ pub fn change_image(doc: &mut Document, page: usize, index: usize, change: &Imag
         }
     };
     ops.splice(img.op..=img.op, replacement);
-    if let Some((at, cm)) = clip_move {
-        ops.insert(at, cm);
-    }
     let mut dict = match &*doc.resolve(&obj) {
         Object::Stream(s) => s.dict.clone(),
         _ => Dict::new(),
@@ -362,6 +491,140 @@ pub(crate) fn selectable_images(
         .collect())
 }
 
+/// Find the saved graphics-state scope containing just this image and its crop. Applying
+/// the transform before that scope moves the actual clipping path as well as the pixels.
+/// A shared clip must never be moved along with unrelated artwork or text.
+fn image_transform_scope(ops: &[Op], target: usize) -> Result<Option<(usize, usize, Matrix)>, EditError> {
+    struct Scope {
+        start: usize,
+        matrix: Matrix,
+        inherited_clip: bool,
+        inherited_path: bool,
+        selected: bool,
+        other_paint: bool,
+    }
+    let mut stack: Vec<Scope> = Vec::new();
+    let mut matrix = Matrix::IDENTITY;
+    let mut clipped = false;
+    let mut path = false;
+    let mut pending_clip = false;
+    let mut text = false;
+    let mut at_image = None;
+    let mut isolated = None;
+    for (index, op) in ops.iter().enumerate() {
+        match op.op.as_slice() {
+            b"q" => {
+                if stack.len() >= 256 {
+                    return Err(EditError::Invalid("the image graphics state is too deeply nested to transform".into()));
+                }
+                stack.push(Scope { start: index, matrix, inherited_clip: clipped, inherited_path: path, selected: false, other_paint: false });
+            }
+            b"Q" => {
+                if let Some(scope) = stack.pop() {
+                    if scope.selected && !scope.other_paint && !scope.inherited_clip && !scope.inherited_path {
+                        // Prefer the innermost scope that contains every active clipping path.
+                        isolated.get_or_insert((scope.start, index, scope.matrix));
+                    }
+                    matrix = scope.matrix;
+                    clipped = scope.inherited_clip;
+                }
+            }
+            b"cm" => {
+                if let Some(m) = op.nums::<6>() {
+                    matrix = Matrix(m).then(&matrix);
+                }
+            }
+            b"BT" => text = true,
+            b"ET" => text = false,
+            b"m" | b"l" | b"c" | b"v" | b"y" | b"re" => path = true,
+            b"W" | b"W*" => pending_clip = true,
+            _ => {}
+        }
+        if index == target {
+            if text {
+                return Err(EditError::Invalid("an image inside a text object cannot be transformed".into()));
+            }
+            at_image = Some((matrix, clipped));
+            for scope in &mut stack {
+                scope.selected = true;
+            }
+        } else if matches!(
+            op.op.as_slice(),
+            b"Do" | b"Tj" | b"TJ" | b"'" | b"\"" | b"sh" | b"BI" | b"S" | b"s" | b"f" | b"F" | b"f*" | b"B" | b"B*" | b"b" | b"b*"
+        ) {
+            for scope in &mut stack {
+                scope.other_paint = true;
+            }
+        }
+        if matches!(op.op.as_slice(), b"n" | b"S" | b"s" | b"f" | b"F" | b"f*" | b"B" | b"B*" | b"b" | b"b*") {
+            clipped |= pending_clip;
+            pending_clip = false;
+            path = false;
+        }
+    }
+    let (placement, clipped) = at_image.ok_or_else(|| EditError::Invalid("the image operation is missing".into()))?;
+    if !clipped {
+        return Ok(Some((target, target, placement)));
+    }
+    Ok(isolated)
+}
+
+fn transform_image(
+    doc: &mut Document,
+    page: &pdfcraft_model::Page,
+    streams: &[(Object, Vec<u8>)],
+    image: &PageImage,
+    transform: [f64; 6],
+) -> Result<(), EditError> {
+    if !transform.iter().all(|v| v.is_finite() && v.abs() <= 1e12) {
+        return Err(EditError::Invalid("the image transform must be finite and no larger than 1e12".into()));
+    }
+    let mut offset = 0_usize;
+    for (_, data) in streams.iter().take(image.stream) {
+        offset = offset
+            .checked_add(data.len())
+            .and_then(|n| n.checked_add(1))
+            .ok_or_else(|| EditError::Invalid("the image content is too large".into()))?;
+    }
+    let data = streams.get(image.stream).ok_or_else(|| EditError::Invalid("the image stream is missing".into()))?;
+    let op = parse(&data.1).ops.get(image.op).cloned().ok_or_else(|| EditError::Invalid("the image operation is missing".into()))?;
+    let span = offset.checked_add(op.span.start).ok_or_else(|| EditError::Invalid("the image content is too large".into()))?;
+    let pieces = pdfcraft_content::Pieces::join(&streams.iter().map(|(_, data)| data.as_slice()).collect::<Vec<_>>());
+    let ops = pieces.parse().ops;
+    let target = ops
+        .iter()
+        .position(|op| op.span.start == span && op.is("Do"))
+        .ok_or_else(|| EditError::Invalid("the image operation could not be located".into()))?;
+    // A private path crop moves with its image regardless of intervening state operators.
+    // Shared crops retain the existing fixed-clip behavior, preserving neighbouring paint.
+    let (start, end, placement) = image_transform_scope(&ops, target)?.unwrap_or((target, target, Matrix(image.draw_matrix)));
+    let inverse = placement.invert().ok_or_else(|| EditError::Invalid("the image has no area".into()))?;
+    let local = placement.then(&Matrix(transform)).then(&inverse);
+    if !local.0.iter().all(|v| v.is_finite() && v.abs() <= 1e12) {
+        return Err(EditError::Invalid("the image transform is too large".into()));
+    }
+    let changed = crate::text::splice(&pieces, &ops, |index| {
+        if index == start {
+            let mut out = vec![Op::new("q", vec![]), Op::new("cm", local.0.map(Object::Real).to_vec())];
+            if start == end {
+                out.extend(ops.get(index).cloned());
+                out.push(Op::new("Q", vec![]));
+                return (out, false);
+            }
+            (out, true)
+        } else if index == end {
+            let mut out: Vec<_> = ops.get(index).cloned().into_iter().collect();
+            out.push(Op::new("Q", vec![]));
+            (out, false)
+        } else {
+            (Vec::new(), true)
+        }
+    });
+    let contents = crate::text::rewritten_contents(doc, streams, changed);
+    doc.update_dict(page.obj, |d| d.set(b"Contents".to_vec(), contents))?;
+    Ok(())
+}
+
 /// Plan all transforms before changing a stream; indexes refer to the original inventory.
 /// Splice only the chosen Do operators and preserve all other bytes and stream dictionaries.
 pub(crate) fn translate_images(doc: &mut Document, page: usize, indexes: &[usize], offset: [f64; 2]) -> Result<(), EditError> {

crates/edit/src/indic.rs

@@ -0,0 +1,258 @@
+//! Visual and logical order for Indic scripts in Edit text (Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Malayalam).
+//!
+//! Legacy PDF producers often output glyphs in *visual* display order when using fonts without
+//! OpenType GSUB layout tables. In visual order, pre-base vowel signs (such as Devanagari short 'i'
+//! `ि` U+093F) appear in the stream *before* the consonant cluster they modify, matching their visual
+//! placement to the left of the glyph.
+//!
+//! Standard Unicode text is *logical* (typing order): the pre-base vowel sign follows the consonant
+//! cluster. The editor presents and edits text in logical order. When a source font is flagged with
+//! `visual_order`, [`to_logical`] converts extracted stream text to logical order for editing, and
+//! [`to_visual`] converts logical edits back into the visual glyph sequence the font expects.
+
+/// Whether `c` is an Indic consonant across covered scripts.
+pub fn is_indic_consonant(c: char) -> bool {
+    matches!(
+        c,
+        '\u{0915}'..='\u{0939}' | '\u{0958}'..='\u{095F}' | '\u{0978}'..='\u{097F}' // Devanagari
+        | '\u{0995}'..='\u{09B9}' | '\u{09DC}'..='\u{09DF}' // Bengali
+        | '\u{0A15}'..='\u{0A39}' | '\u{0A59}'..='\u{0A5E}' // Gurmukhi
+        | '\u{0A95}'..='\u{0AB9}' // Gujarati
+        | '\u{0B15}'..='\u{0B39}' | '\u{0B5C}'..='\u{0B5F}' // Oriya
+        | '\u{0B95}'..='\u{0BB9}' // Tamil
+        | '\u{0C15}'..='\u{0C39}' | '\u{0C58}'..='\u{0C5A}' // Telugu
+        | '\u{0C95}'..='\u{0CB9}' | '\u{0CDE}' // Kannada
+        | '\u{0D15}'..='\u{0D3A}' // Malayalam
+    )
+}
+
+/// Whether `c` is an Indic nukta (diacritic dot modifying a consonant).
+pub fn is_indic_nukta(c: char) -> bool {
+    matches!(
+        c,
+        '\u{093C}' // Devanagari
+        | '\u{09BC}' // Bengali
+        | '\u{0A3C}' // Gurmukhi
+        | '\u{0ABC}' // Gujarati
+        | '\u{0B3C}' // Oriya
+    )
+}
+
+/// Whether `c` is an Indic virama (halant / vowel killer).
+pub fn is_indic_virama(c: char) -> bool {
+    matches!(
+        c,
+        '\u{094D}' // Devanagari
+        | '\u{09CD}' // Bengali
+        | '\u{0A4D}' // Gurmukhi
+        | '\u{0ACD}' // Gujarati
+        | '\u{0B4D}' // Oriya
+        | '\u{0BCD}' // Tamil
+        | '\u{0C4D}' // Telugu
+        | '\u{0CCD}' // Kannada
+        | '\u{0D4D}' // Malayalam
+    )
+}
+
+/// Whether `c` is an Indic pre-base vowel sign that appears visually to the left of its consonant.
+pub fn is_indic_pre_base_vowel(c: char) -> bool {
+    matches!(
+        c,
+        '\u{093F}' // Devanagari short I
+        | '\u{09BF}' | '\u{09C7}' | '\u{09C8}' // Bengali short I, E, AI
+        | '\u{0A3F}' // Gurmukhi short I
+        | '\u{0ABF}' // Gujarati short I
+        | '\u{0B3F}' // Oriya short I
+        | '\u{0BC6}' | '\u{0BC7}' | '\u{0BC8}' // Tamil E, EE, AI
+        | '\u{0D46}' | '\u{0D47}' | '\u{0D48}' // Malayalam E, EE, AI
+    )
+}
+
+/// Modifiers that attach to an Indic vowel sign (such as candrabindu, anusvara, or visarga).
+fn is_indic_vowel_modifier(c: char) -> bool {
+    matches!(
+        c,
+        '\u{0901}'..='\u{0903}' // Devanagari candrabindu, anusvara, visarga
+        | '\u{0981}'..='\u{0983}' // Bengali
+        | '\u{0A01}'..='\u{0A03}' // Gurmukhi
+        | '\u{0A81}'..='\u{0A83}' // Gujarati
+        | '\u{0B01}'..='\u{0B03}' // Oriya
+    )
+}
+
+/// The character at `i`, if any.
+fn at(chars: &[char], i: usize) -> Option<char> {
+    chars.get(i).copied()
+}
+
+/// The end of the consonant cluster starting at `start` (consonants with their nuktas, joined by
+/// viramas and optional ZWNJ/ZWJ); `start` itself when no consonant starts there.
+fn cluster_end(chars: &[char], start: usize) -> usize {
+    let mut end = start;
+    while at(chars, end).is_some_and(is_indic_consonant) {
+        end += 1;
+        if at(chars, end).is_some_and(is_indic_nukta) {
+            end += 1;
+        }
+        if at(chars, end).is_some_and(is_indic_virama) {
+            end += 1;
+            if at(chars, end).is_some_and(|c| matches!(c, '\u{200C}' | '\u{200D}')) {
+                end += 1;
+            }
+            if at(chars, end).is_some_and(is_indic_consonant) {
+                continue;
+            }
+        }
+        break;
+    }
+    end
+}
+
+/// The end of the vowel-modifier run (candrabindu, anusvara, visarga) starting at `start`.
+fn modifiers_end(chars: &[char], start: usize) -> usize {
+    let mut end = start;
+    while at(chars, end).is_some_and(is_indic_vowel_modifier) {
+        end += 1;
+    }
+    end
+}
+
+/// Convert Indic text from visual glyph order (pre-base vowels before their consonant cluster)
+/// to standard Unicode logical order.
+pub fn to_logical(text: &str) -> String {
+    let chars: Vec<char> = text.chars().collect();
+    let mut out: Vec<char> = Vec::with_capacity(chars.len());
+    let mut i = 0;
+    while let Some(ch) = at(&chars, i) {
+        if is_indic_pre_base_vowel(ch) {
+            let v_end = modifiers_end(&chars, i + 1);
+            let c_end = cluster_end(&chars, v_end);
+            if c_end > v_end {
+                out.extend_from_slice(chars.get(v_end..c_end).unwrap_or_default());
+                out.extend_from_slice(chars.get(i..v_end).unwrap_or_default());
+                i = c_end;
+                continue;
+            }
+        }
+        out.push(ch);
+        i += 1;
+    }
+    out.into_iter().collect()
+}
+
+/// Convert Indic text from standard Unicode logical order to visual display order for fonts
+/// that expect pre-base vowels before their consonant cluster.
+pub fn to_visual(text: &str) -> String {
+    let chars: Vec<char> = text.chars().collect();
+    let mut out: Vec<char> = Vec::with_capacity(chars.len());
+    let mut i = 0;
+    while let Some(ch) = at(&chars, i) {
+        if is_indic_consonant(ch) {
+            let c_end = cluster_end(&chars, i);
+            if at(&chars, c_end).is_some_and(is_indic_pre_base_vowel) {
+                let v_end = modifiers_end(&chars, c_end + 1);
+                out.extend_from_slice(chars.get(c_end..v_end).unwrap_or_default());
+                out.extend_from_slice(chars.get(i..c_end).unwrap_or_default());
+                i = v_end;
+            } else {
+                out.extend_from_slice(chars.get(i..c_end).unwrap_or_default());
+                i = c_end;
+            }
+            continue;
+        }
+        out.push(ch);
+        i += 1;
+    }
+    out.into_iter().collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn simple_words_roundtrip() {
+        // किताब (kitab): k + i + t + aa + b
+        let visual = "\u{093F}\u{0915}\u{0924}\u{093E}\u{092C}";
+        let logical = "\u{0915}\u{093F}\u{0924}\u{093E}\u{092C}";
+        assert_eq!(to_logical(visual), logical);
+        assert_eq!(to_visual(logical), visual);
+
+        // दिन (din): d + i + n
+        let visual_din = "\u{093F}\u{0926}\u{0928}";
+        let logical_din = "\u{0926}\u{093F}\u{0928}";
+        assert_eq!(to_logical(visual_din), logical_din);
+        assert_eq!(to_visual(logical_din), visual_din);
+    }
+
+    #[test]
+    fn decomposed_nukta_with_pre_base_vowel() {
+        // Decomposed ड़ि: DDA (U+0921) + NUKTA (U+093C) + Short I (U+093F)
+        let logical = "\u{0921}\u{093C}\u{093F}";
+        let visual = "\u{093F}\u{0921}\u{093C}";
+        assert_eq!(to_logical(visual), logical);
+        assert_eq!(to_visual(logical), visual);
+
+        // Decomposed ढ़ि: DDHA (U+0922) + NUKTA (U+093C) + Short I (U+093F)
+        let logical_ddhi = "\u{0922}\u{093C}\u{093F}";
+        let visual_ddhi = "\u{093F}\u{0922}\u{093C}";
+        assert_eq!(to_logical(visual_ddhi), logical_ddhi);
+        assert_eq!(to_visual(logical_ddhi), visual_ddhi);
+    }
+
+    #[test]
+    fn precomposed_nukta_with_pre_base_vowel() {
+        // Precomposed ड़ि (U+095C + U+093F)
+        let logical = "\u{095C}\u{093F}";
+        let visual = "\u{093F}\u{095C}";
+        assert_eq!(to_logical(visual), logical);
+        assert_eq!(to_visual(logical), visual);
+    }
+
+    #[test]
+    fn full_words_with_nukta_and_pre_base_vowel() {
+        // बढ़िया (badhiya): ba + ddha + nukta + short_i + ya + aa
+        let logical = "\u{092C}\u{0922}\u{093C}\u{093F}\u{092F}\u{093E}";
+        let visual = "\u{092C}\u{093F}\u{0922}\u{093C}\u{092F}\u{093E}";
+        assert_eq!(to_logical(visual), logical);
+        assert_eq!(to_visual(logical), visual);
+
+        // खिड़की (khirki): kha + short_i + dda + nukta + ka + long_ii
+        let logical_khirki = "\u{0916}\u{093F}\u{0921}\u{093C}\u{0915}\u{0940}";
+        let visual_khirki = "\u{093F}\u{0916}\u{0921}\u{093C}\u{0915}\u{0940}";
+        assert_eq!(to_logical(visual_khirki), logical_khirki);
+        assert_eq!(to_visual(logical_khirki), visual_khirki);
+    }
+
+    #[test]
+    fn complex_conjuncts_with_pre_base_vowel() {
+        // स्थिति (sthiti): sa + virama + tha + short_i + ta + short_i
+        let logical = "\u{0938}\u{094D}\u{0925}\u{093F}\u{0924}\u{093F}";
+        let visual = "\u{093F}\u{0938}\u{094D}\u{0925}\u{093F}\u{0924}";
+        assert_eq!(to_logical(visual), logical);
+        assert_eq!(to_visual(logical), visual);
+    }
+
+    #[test]
+    fn other_indic_scripts_pre_base_vowels() {
+        // Bengali কি (ki): KA (U+0995) + I (U+09BF)
+        let b_logical = "\u{0995}\u{09BF}";
+        let b_visual = "\u{09BF}\u{0995}";
+        assert_eq!(to_logical(b_visual), b_logical);
+        assert_eq!(to_visual(b_logical), b_visual);
+
+        // Gurmukhi ਕਿ (ki): KA (U+0A15) + I (U+0A3F)
+        let g_logical = "\u{0A15}\u{0A3F}";
+        let g_visual = "\u{0A3F}\u{0A15}";
+        assert_eq!(to_logical(g_visual), g_logical);
+        assert_eq!(to_visual(g_logical), g_visual);
+    }
+
+    #[test]
+    fn non_indic_text_is_untouched() {
+        for s in ["", "Hello world!", "PDF 123", "日本語テキスト", "123.45"] {
+            assert_eq!(to_logical(s), s);
+            assert_eq!(to_visual(s), s);
+        }
+    }
+}

crates/edit/src/lib.rs

@@ -19,7 +19,8 @@ use pdfcraft_fonts::{helvetica_width, literal, win_ansi};
 
 #[derive(Debug, thiserror::Error, PartialEq)]
 pub enum EditError {
-    #[error("page {0} does not exist")]
+    /// Holds the 0-based index; the message names the 1-based page a user counts (#1550).
+    #[error("page {} does not exist", .0.saturating_add(1))]
     NoSuchPage(usize),
     #[error("{0}")]
     Invalid(String),
@@ -395,12 +396,6 @@ pub fn undrawable_message(c: char) -> String {
     format!("the standard fonts can't draw \"{c}\" (U+{:04X}); only Western European characters can be added as text for now", u32::from(c))
 }
 
-/// The first character of plain `text` that Helvetica/WinAnsi can't draw (line and page breaks
-/// and tabs are layout, not glyphs).
-pub fn first_undrawable_plain(text: &str) -> Option<char> {
-    text.chars().find(|c| !matches!(c, '\r' | '\n' | '\t' | '\u{c}') && !pdfcraft_fonts::win_ansi_encodable(*c))
-}
-
 fn text_op(x: f64, y: f64, text: &str) -> Vec<u8> {
     let mut v = format!("1 0 0 1 {} {} Tm ", n(x), n(y)).into_bytes();
     v.extend(literal(&win_ansi(text)));
@@ -629,8 +624,13 @@ mod flatten;
 pub use flatten::{flatten, flatten_fill_sign};
 pub mod images;
 pub use images::{ImageChange, PageImage, change_image, page_images, reading_images, rect_to_rect, turn_about_centre};
+pub mod bidi;
+pub mod indic;
 pub mod text;
-pub use text::{BlockStyle, LineEdit, TextBlock, TextLine, reading_blocks, replace_block, replace_line, rewrite_block, text_blocks, text_lines};
+pub use text::{
+    BlockStyle, LineEdit, RangeStyle, TextBlock, TextLine, clear_block, reading_blocks, replace_block, replace_line, rewrite_block, text_blocks,
+    text_lines,
+};
 pub mod added;
 pub use added::{
     Added, AddedImage, AddedText, Align, Content, Family, MarkerScan, add_content, delete_content, first_undrawable, list_added, scan_markers,

crates/edit/src/objects.rs

@@ -81,9 +81,10 @@ pub fn editable_objects(doc: &Document, page: usize) -> Result<Vec<EditableObjec
         });
     }
     for (index, image) in crate::images::selectable_images(doc, page, &excluded)? {
+        let Some(rect) = image.visible_rect else { continue };
         objects.push(EditableObject {
             target: ObjectTarget { kind: ObjectKind::Image, index },
-            rect: image.rect,
+            rect,
             content_type: if image.is_form { "form" } else { "image" },
             text: None,
         });

crates/edit/src/text_regions.rs

@@ -0,0 +1,725 @@
+//! Geometry-based regions and mixed-style rewriting of existing text.
+
+use super::*;
+
+fn same_plane(a: &TextLine, b: &TextLine) -> bool {
+    let at = Matrix(a.origin.tm).then(&Matrix(a.origin.ctm));
+    let bt = Matrix(b.origin.tm).then(&Matrix(b.origin.ctm));
+    a.scope == b.scope
+        && [0, 2].iter().all(|axis| {
+            let ax = at.0.get(*axis).copied().unwrap_or(0.0);
+            let ay = at.0.get(axis + 1).copied().unwrap_or(0.0);
+            let bx = bt.0.get(*axis).copied().unwrap_or(0.0);
+            let by = bt.0.get(axis + 1).copied().unwrap_or(0.0);
+            let al = ax.hypot(ay);
+            let bl = bx.hypot(by);
+            al > 0.0 && bl > 0.0 && (ax / al - bx / bl).abs() < 0.001 && (ay / al - by / bl).abs() < 0.001
+        })
+}
+
+fn union(a: [f64; 4], b: [f64; 4]) -> [f64; 4] {
+    [a[0].min(b[0]), a[1].min(b[1]), a[2].max(b[2]), a[3].max(b[3])]
+}
+
+fn row_rect(row: &[usize], lines: &[TextLine]) -> Option<[f64; 4]> {
+    row.iter().filter_map(|i| lines.get(*i)).map(|l| l.rect).reduce(union)
+}
+
+pub(super) fn group_blocks(lines: &[TextLine]) -> Vec<TextBlock> {
+    group_layout(lines, true)
+}
+
+/// Exporters currently represent a block with one style. Keep their style boundaries until
+/// they support rich runs, while edit selection may encompass the complete visual region.
+pub(super) fn group_reading_blocks(lines: &[TextLine]) -> Vec<TextBlock> {
+    group_layout(lines, false)
+}
+
+/// Text-space units → user space along the baseline. It is the vertical scale ([`Origin::k`])
+/// unless the text matrix stretches the glyphs, as an OCR layer fitting each word to the scan does.
+fn across(line: &TextLine) -> f64 {
+    let m = Matrix(line.origin.tm).then(&Matrix(line.origin.ctm)).0;
+    let h = m[0].hypot(m[1]);
+    if h.is_finite() && h > 1e-9 { h } else { line.origin.k }
+}
+
+/// Invisible text (rendering mode 3), as in an OCR layer over a scanned image.
+fn invisible(line: &TextLine) -> bool {
+    line.origin.state.render_mode == 3
+}
+
+fn same_style(a: &TextLine, b: &TextLine) -> bool {
+    same_font(a, b.font.as_bytes(), b.face.as_deref())
+        && a.base_font == b.base_font
+        && a.bold == b.bold
+        && a.italic == b.italic
+        && a.color == b.color
+        && (a.rotation() - b.rotation()).abs() < 0.01
+        && (a.size - b.size).abs() < 0.01
+}
+
+fn group_layout(lines: &[TextLine], mixed: bool) -> Vec<TextBlock> {
+    let mut rows: Vec<Vec<usize>> = Vec::new();
+    for (i, line) in lines.iter().enumerate() {
+        let joins = rows.last().and_then(|r| r.last()).and_then(|i| lines.get(*i)).is_some_and(|prev| {
+            let gap = line.rect[0] - prev.rect[2];
+            // OCR words (invisible text over a scan) join only across a word space: a wider gap
+            // is a table cell or a tab stop, which a rewrite would close up.
+            let scanned = !mixed || (invisible(prev) == invisible(line) && (!invisible(line) || gap < prev.size.max(line.size) * 0.6));
+            scanned
+                && (mixed || same_style(prev, line))
+                && same_plane(prev, line)
+                && (prev.origin.baseline - line.origin.baseline).abs() < prev.size.min(line.size) * 0.2
+                && gap >= -prev.size.min(line.size) * 0.2
+                && gap < prev.size.max(line.size) * 1.5
+                // Separate same-style text objects that merely touch or overlap, with no space
+                // between them, are separate labels (for example a paragraph dragged against
+                // another, #594). Style runs and words separated by a space or gap still join.
+                && (prev.origin.bt_op == line.origin.bt_op
+                    || gap > prev.size.min(line.size) * 0.01
+                    || !same_style(prev, line)
+                    || prev.text.ends_with(char::is_whitespace)
+                    || line.text.starts_with(char::is_whitespace))
+        });
+        if joins && let Some(row) = rows.last_mut() {
+            row.push(i);
+        } else {
+            rows.push(vec![i]);
+        }
+    }
+    let mut blocks: Vec<TextBlock> = Vec::new();
+    for row in rows {
+        let Some(first) = row.first().and_then(|i| lines.get(*i)) else { continue };
+        let Some(rect) = row_rect(&row, lines) else { continue };
+        let joins = blocks.last().is_some_and(|block| {
+            let Some(prev_row) = block.rows.last() else { return false };
+            let Some(prev) = prev_row.first().and_then(|i| lines.get(*i)) else { return false };
+            let Some(pr) = row_rect(prev_row, lines) else { return false };
+            let gap = prev.origin.baseline - first.origin.baseline;
+            let tol = prev.size.max(first.size).max(1.0);
+            let aligned = (pr[0] - rect[0]).abs() < tol || ((pr[0] + pr[2] - rect[0] - rect[2]) / 2.0).abs() < tol || (pr[2] - rect[2]).abs() < tol;
+            // OCR lines stay apart: the scan fixes where each one is, so they never rewrap together.
+            (!mixed || !(invisible(prev) || invisible(first)))
+                && (mixed || same_style(prev, first))
+                && same_plane(prev, first)
+                && aligned
+                && first.size.min(prev.size) >= first.size.max(prev.size) * 0.4
+                && gap > first.size.min(prev.size) * 0.8
+                && gap < first.size.max(prev.size) * 2.5
+        });
+        if !joins {
+            blocks.push(TextBlock {
+                text: String::new(),
+                editor_text: String::new(),
+                spans: Vec::new(),
+                rect,
+                base_font: first.base_font.clone(),
+                size: first.size,
+                bold: first.bold,
+                italic: first.italic,
+                color: first.color,
+                rotation: first.rotation(),
+                lines: Vec::new(),
+                rows: Vec::new(),
+                invisible: true,
+            });
+        }
+        let Some(block) = blocks.last_mut() else { continue };
+        let mut row_text = String::new();
+        if !block.rows.is_empty() {
+            block.editor_text.push('\n');
+        }
+        for &index in &row {
+            let Some(line) = lines.get(index) else { continue };
+            // Some producers position separate words without encoding a space.
+            if let Some(prev) = block.lines.last().filter(|i| row.contains(i)).and_then(|i| lines.get(*i))
+                && !row_text.ends_with(char::is_whitespace)
+                && !line.text.starts_with(char::is_whitespace)
+                && line.rect[0] - prev.rect[2] > line.size * 0.12
+            {
+                row_text.push(' ');
+                block.editor_text.push(' ');
+            }
+            let start = block.editor_text.len();
+            block.editor_text.push_str(&line.text);
+            block.spans.push((start..block.editor_text.len(), index));
+            row_text.push_str(&line.text);
+            block.invisible &= line.origin.state.render_mode == 3;
+            block.lines.push(index);
+        }
+        if !block.text.is_empty() {
+            if block.text.ends_with('-') {
+                block.text.pop();
+            } else {
+                block.text.push(' ');
+            }
+        }
+        block.text.push_str(row_text.trim_matches(paragraph_separator));
+        block.rect = union(block.rect, rect);
+        block.rows.push(row);
+    }
+    blocks
+}
+
+/// Shape in the source or an explicitly registered matching full face. Never use interface fonts.
+fn shape_source(
+    doc: &Document,
+    fonts: &Dict,
+    name: &str,
+    text: &str,
+) -> Result<Option<(Vec<u8>, pdfcraft_fonts::source_shaping::ShapedRun, String)>, EditError> {
+    if !pdfcraft_fonts::source_shaping::required(text) {
+        return Ok(None);
+    }
+    let source =
+        fonts.get(name.as_bytes()).and_then(|f| doc.dict(f)).ok_or_else(|| EditError::Invalid("the shaped text has no font resource".into()))?;
+    let family = Metrics::from_dict(doc, &source).base_font;
+    let mut candidates = vec![source];
+    candidates.extend(
+        fonts
+            .iter()
+            .filter_map(|(_, f)| doc.dict(f))
+            .filter(|f| pdfcraft_fonts::embedding::face_key(&Metrics::from_dict(doc, f).base_font) == pdfcraft_fonts::embedding::face_key(&family)),
+    );
+    for font in candidates {
+        if let Some(bytes) = pdfcraft_fonts::pdf::embedded_sfnt(doc, &font)
+            && pdfcraft_fonts::embedding::covers(&bytes, text)
+            && let Ok(shaped) = pdfcraft_fonts::source_shaping::shape(&bytes, text)
+        {
+            return Ok(Some((bytes, shaped, family)));
+        }
+    }
+    Err(EditError::Invalid("complex text needs the complete source TrueType/OpenType face; load that font before editing".into()))
+}
+
+/// Rewrite visual rows while keeping the source style on each surviving character. Resource
+/// names may differ between Unicode subsets of the same face; encoding searches those subsets.
+pub(super) fn rewrite_styled_block(
+    doc: &mut Document,
+    page: usize,
+    block: &TextBlock,
+    lines: &[TextLine],
+    text: Option<&str>,
+    style: &BlockStyle,
+) -> Result<LineEdit, EditError> {
+    let first = block.lines.first().and_then(|i| lines.get(*i)).ok_or_else(|| EditError::Invalid("the paragraph has no source runs".into()))?;
+    let draft = match text {
+        Some(t) if t != block.text => t,
+        _ => &block.editor_text,
+    };
+    if draft.len() > 4_000_000 {
+        return Err(EditError::Invalid("the replacement text is too large".into()));
+    }
+    if draft == block.editor_text && *style == BlockStyle::default() {
+        return Ok(LineEdit { substituted: None });
+    }
+    let mut ranges: Vec<_> = style.ranges.iter().collect();
+    ranges.sort_by_key(|r| r.range.start);
+    if ranges.len() > 1024
+        || ranges.iter().any(|r| {
+            r.range.start >= r.range.end
+                || draft.get(r.range.clone()).is_none()
+                || [r.size, r.char_spacing, r.scale].iter().flatten().any(|n| !n.is_finite())
+                || r.size.is_some_and(|n| n <= 0.0 || n > 14400.0)
+                || r.color.is_some_and(|c| c.iter().any(|n| !n.is_finite() || !(0.0..=1.0).contains(n)))
+        })
+        || ranges.windows(2).any(|r| r[0].range.end > r[1].range.start)
+    {
+        return Err(EditError::Invalid("text style ranges must be disjoint UTF-8 boundaries with finite formatting (at most 1024 ranges)".into()));
+    }
+    let mut styled_lines = lines.to_vec();
+    let mut styled_spans = Vec::new();
+    let mut underlines = HashMap::new();
+    let mut overrides = HashMap::new();
+    for (span, source) in block.edited_spans(draft) {
+        let mut edges = vec![span.start, span.end];
+        for r in &ranges {
+            for edge in [r.range.start, r.range.end] {
+                if span.contains(&edge) {
+                    edges.push(edge);
+                }
+            }
+        }
+        edges.sort_unstable();
+        edges.dedup();
+        for bounds in edges.windows(2) {
+            let (Some(start), Some(end)) = (bounds.first().copied(), bounds.get(1).copied()) else { continue };
+            let mut index = source;
+            let selected = ranges.iter().find(|r| r.range.contains(&start)).copied();
+            if selected.is_some() || style.family.is_some() || style.bold.is_some() {
+                let default_range = RangeStyle {
+                    range: start..end,
+                    family: None,
+                    resource: None,
+                    size: None,
+                    color: None,
+                    underline: None,
+                    char_spacing: None,
+                    scale: None,
+                };
+                let r = selected.unwrap_or(&default_range);
+                let mut line = lines.get(source).unwrap_or(first).clone();
+                if let Some((family, bold, italic)) =
+                    r.family.or(style.family).or_else(|| style.bold.map(|b| (source_family(&line.base_font), b, line.italic)))
+                {
+                    let base = family.base_font(bold, italic);
+                    line.font = format!("PCRange{}", base.replace('-', ""));
+                    line.base_font = base.to_owned();
+                    line.bold = bold;
+                    line.italic = italic;
+                }
+                if let Some(resource) = &r.resource {
+                    line.font = resource.clone();
+                }
+                if let Some(size) = r.size {
+                    line.size = size;
+                }
+                if let Some(color) = r.color {
+                    line.color = color;
+                    line.origin.state.fill = vec![Op::new("rg", color.map(Object::Real).to_vec())];
+                }
+                if let Some(spacing) = r.char_spacing {
+                    line.origin.state.char_spacing = spacing / line.origin.k.max(1e-6);
+                }
+                if let Some(scale) = r.scale {
+                    line.origin.state.scale = (scale / 100.0).clamp(0.1, 10.0);
+                }
+                index = styled_lines.len();
+                styled_lines.push(line);
+                if let Some(r) = selected {
+                    overrides.insert(index, r);
+                }
+                if let Some(underline) = r.underline {
+                    underlines.insert(index, underline);
+                }
+            }
+            styled_spans.push((start..end, index));
+        }
+    }
+    let lines = styled_lines.as_slice();
+    let p = page_dict(doc, page)?;
+    let mut res = p.dict.get(b"Resources").and_then(|r| doc.resolve(r).as_dict().cloned()).unwrap_or_default();
+    let mut fonts = res.get(b"Font").and_then(|r| doc.resolve(r).as_dict().cloned()).unwrap_or_default();
+    for line in lines.iter().filter(|line| line.font.starts_with("PCRange")) {
+        let mut f = Dict::new();
+        f.set(b"Type".to_vec(), Object::name("Font"));
+        f.set(b"Subtype".to_vec(), Object::name("Type1"));
+        f.set(b"BaseFont".to_vec(), Object::name(&line.base_font));
+        f.set(b"Encoding".to_vec(), Object::name("WinAnsiEncoding"));
+        fonts.set(line.font.as_bytes().to_vec(), Object::Dict(f));
+    }
+    let mut metrics = std::collections::BTreeMap::new();
+    for (name, object) in fonts.iter().take(256) {
+        if let Some(font) = doc.resolve(object).as_dict() {
+            metrics.insert(String::from_utf8_lossy(name).into_owned(), Metrics::from_dict(doc, font));
+        }
+    }
+    for index in &block.lines {
+        if let Some(line) = lines.get(*index)
+            && !metrics.contains_key(&line.font)
+            && let Some(font) = fonts.get(line.font.as_bytes()).and_then(|f| doc.resolve(f).as_dict().cloned())
+        {
+            metrics.insert(line.font.clone(), Metrics::from_dict(doc, &font));
+        }
+    }
+    if [style.size, style.line_spacing, style.char_spacing, style.scale, style.width].iter().flatten().any(|v| !v.is_finite())
+        || style.color.is_some_and(|c| c.iter().any(|v| !v.is_finite()))
+    {
+        return Err(EditError::Invalid("the paragraph's formatting must use finite numbers".into()));
+    }
+    let [dx, dy] = style.offset.unwrap_or([0.0, 0.0]);
+    if !dx.is_finite() || !dy.is_finite() || style.width.is_some_and(|w| !w.is_finite()) {
+        return Err(EditError::Invalid("the paragraph's position and width must be finite".into()));
+    }
+    // A rewritten OCR line grows to the right rather than wrapping onto the scanned line below.
+    let natural = if block.invisible {
+        (p.crop(doc)[2] - 36.0 - (block.rect[0] + dx)).max(block.rect[2] - block.rect[0])
+    } else {
+        block.rect[2] - block.rect[0]
+    };
+    let width = style.width.unwrap_or(natural).clamp(1.0, 14_400.0);
+    // Each tuple is a character, its source style and an encodable resource name.
+    let mut chars = Vec::new();
+    let mut substituted = None;
+    let mut fallback_names: std::collections::BTreeMap<(String, char), String> = std::collections::BTreeMap::new();
+    let mut full_faces: HashMap<String, String> = HashMap::new();
+    for (range, index) in styled_spans {
+        let source = lines.get(index).unwrap_or(first);
+        for ch in draft.get(range).unwrap_or_default().chars() {
+            if ch == '\n' {
+                chars.push((ch, index, source.font.clone()));
+                continue;
+            }
+            let s = ch.to_string();
+            let name = if let Some(resource) = overrides.get(&index).and_then(|r| r.resource.as_ref()).or(style.resource.as_ref()) {
+                if !metrics.get(resource).is_some_and(|m| source_encodes(m, &s)) {
+                    return Err(EditError::Invalid(format!("the selected font resource {resource} cannot show U+{:04X}", u32::from(ch))));
+                }
+                resource.clone()
+            } else if metrics.get(&source.font).is_some_and(|m| source_encodes(m, &s)) {
+                source.font.clone()
+            } else if let Some((name, _)) = metrics.iter().find(|(_, m)| {
+                pdfcraft_fonts::embedding::face_key(&m.base_font) == pdfcraft_fonts::embedding::face_key(&source.base_font) && source_encodes(m, &s)
+            }) {
+                name.clone()
+            } else if let Some(face) =
+                pdfcraft_fonts::embedding::matching_faces(&source.base_font).into_iter().find(|f| pdfcraft_fonts::embedding::covers(f.bytes, &s))
+            {
+                let key = face.name();
+                if let Some(name) = full_faces.get(&key) {
+                    name.clone()
+                } else {
+                    let name = pdfcraft_fonts::embedding::embed(doc, &mut fonts, face.bytes, face.family).map_err(EditError::Invalid)?;
+                    let font = fonts
+                        .get(name.as_bytes())
+                        .and_then(|f| doc.dict(f))
+                        .ok_or_else(|| EditError::Invalid("the full source font could not be loaded".into()))?;
+                    metrics.insert(name.clone(), Metrics::from_dict(doc, &font));
+                    full_faces.insert(key, name.clone());
+                    name
+                }
+            } else {
+                let family = source_family(&source.base_font);
+                if needs_type3(&s) {
+                    let key = (source.base_font.rsplit('+').next().unwrap_or(&source.base_font).to_owned(), ch);
+                    if let Some(name) = fallback_names.get(&key) {
+                        chars.push((ch, index, name.clone()));
+                        continue;
+                    }
+                    if fallback_names.len() >= MAX_TYPE3_GLYPHS {
+                        return Err(EditError::Invalid("the replacement has too many fallback glyphs".into()));
+                    }
+                    let fallback = type3_font(doc, &mut fonts, &s, family, source.bold, MAX_TYPE3_GLYPHS)?;
+                    let name = fallback.names.first().cloned().ok_or_else(no_japanese_font)?;
+                    let dict = fonts
+                        .get(name.as_bytes())
+                        .and_then(|f| doc.resolve(f).as_dict().cloned())
+                        .ok_or_else(|| EditError::Invalid("the fallback font could not be loaded".into()))?;
+                    metrics.insert(name.clone(), Metrics::from_dict(doc, &dict));
+                    substituted = Some(fallback.family.to_string());
+                    fallback_names.insert(key, name.clone());
+                    name
+                } else {
+                    let base = family.base_font(source.bold, source.italic);
+                    let name = format!("PCEd{}", base.replace('-', ""));
+                    let mut f = Dict::new();
+                    f.set(b"Type".to_vec(), Object::name("Font"));
+                    f.set(b"Subtype".to_vec(), Object::name("Type1"));
+                    f.set(b"BaseFont".to_vec(), Object::name(base));
+                    f.set(b"Encoding".to_vec(), Object::name("WinAnsiEncoding"));
+                    metrics.entry(name.clone()).or_insert_with(|| Metrics::from_dict(doc, &f));
+                    fonts.set(name.clone().into_bytes(), Object::Dict(f));
+                    substituted = Some(base.to_string());
+                    name
+                }
+            };
+            chars.push((ch, index, name));
+        }
+    }
+    let size_of = |source: &TextLine, index: usize| {
+        overrides.get(&index).and_then(|r| r.size).or(style.size).unwrap_or(source.size).max(0.1) / source.origin.k.max(1e-6)
+    };
+    // A source run may carry TJ kerning/justification that is absent from its text state.
+    // Keep its measured advance when rebuilding the run instead of making it wrap on entry.
+    let mut calibration = HashMap::new();
+    for (index, source) in lines.iter().enumerate() {
+        if let Some(m) = metrics.get(&source.font) {
+            let nominal = source_width(
+                m,
+                &source.text,
+                source.origin.state.font.as_ref().map_or(1.0, |(_, s)| *s),
+                source_space(doc, &fonts, m),
+                source.origin.state.char_spacing,
+                source.origin.state.word_spacing,
+            ) * source.origin.state.scale
+                * across(source);
+            let changed_face = style.resource.is_some() || overrides.get(&index).is_some_and(|r| r.family.is_some() || r.resource.is_some());
+            let factor = if nominal > 0.0 && !changed_face { ((source.rect[2] - source.rect[0]) / nominal).clamp(0.5, 2.0) } else { 1.0 };
+            calibration.insert(index, factor);
+        }
+    }
+    let advance = |item: &(char, usize, String)| -> f64 {
+        let source = lines.get(item.1).unwrap_or(first);
+        let Some(m) = metrics.get(&item.2) else { return 0.0 };
+        source_width(
+            m,
+            &item.0.to_string(),
+            size_of(source, item.1),
+            source_space(doc, &fonts, m),
+            overrides
+                .get(&item.1)
+                .and_then(|r| r.char_spacing)
+                .or(style.char_spacing)
+                .map_or(source.origin.state.char_spacing, |c| c / source.origin.k.max(1e-6)),
+            source.origin.state.word_spacing,
+        ) * overrides.get(&item.1).and_then(|r| r.scale).or(style.scale).map_or(source.origin.state.scale, |s| (s / 100.0).clamp(0.1, 10.0))
+            * across(source)
+            * calibration.get(&item.1).copied().unwrap_or(1.0)
+    };
+    let measure = |items: &[(char, usize, String)]| -> Result<f64, EditError> {
+        let mut width = 0.0;
+        let mut at = 0;
+        while let Some(item) = items.get(at) {
+            let mut end = at + 1;
+            while items.get(end).is_some_and(|v| v.1 == item.1 && v.2 == item.2) {
+                end += 1;
+            }
+            let segment = items.get(at..end).unwrap_or_default();
+            let string: String = segment.iter().map(|v| v.0).collect();
+            if let Some((_, shaped, _)) = shape_source(doc, &fonts, &item.2, &string)? {
+                let source = lines.get(item.1).unwrap_or(first);
+                let scale =
+                    overrides.get(&item.1).and_then(|r| r.scale).or(style.scale).map_or(source.origin.state.scale, |s| (s / 100.0).clamp(0.1, 10.0));
+                let spacing = overrides
+                    .get(&item.1)
+                    .and_then(|r| r.char_spacing)
+                    .or(style.char_spacing)
+                    .map_or(source.origin.state.char_spacing, |s| s / source.origin.k.max(1e-6));
+                width += (shaped.advance * size_of(source, item.1)
+                    + spacing * string.chars().count() as f64
+                    + source.origin.state.word_spacing * string.matches(' ').count() as f64)
+                    * scale
+                    * source.origin.k;
+            } else {
+                width += segment.iter().map(&advance).sum::<f64>();
+            }
+            at = end;
+        }
+        Ok(width)
+    };
+    let mut rows: Vec<Vec<(char, usize, String)>> = Vec::new();
+    let mut row = Vec::new();
+    let mut row_width = 0.0;
+    // Wrap at word boundaries, retaining explicit source row breaks and whitespace.
+    let mut at = 0;
+    while at < chars.len() {
+        let Some(item) = chars.get(at) else { break };
+        if item.0 == '\n' {
+            rows.push(std::mem::take(&mut row));
+            row_width = 0.0;
+            at += 1;
+            continue;
+        }
+        let mut end = at + 1;
+        if !item.0.is_whitespace() {
+            while chars.get(end).is_some_and(|c| !c.0.is_whitespace()) {
+                end += 1;
+            }
+        }
+        let word = chars.get(at..end).unwrap_or_default();
+        let w = measure(word)?;
+        if !row.is_empty() && !item.0.is_whitespace() && row_width + w > width + 0.5 {
+            while row.last().is_some_and(|c: &(char, usize, String)| c.0.is_whitespace()) {
+                row.pop();
+            }
+            rows.push(std::mem::take(&mut row));
+            row_width = 0.0;
+        }
+        row.extend_from_slice(word);
+        row_width += w;
+        at = end;
+    }
+    if !row.is_empty() {
+        rows.push(row);
+    }
+    for row in &rows {
+        let text: String = row.iter().map(|v| v.0).collect();
+        if pdfcraft_fonts::source_shaping::required(&text) && row.first().is_some_and(|first| row.iter().any(|v| v.1 != first.1 || v.2 != first.2)) {
+            return Err(EditError::Invalid(
+                "contextual/bidi text across font or style boundaries needs a uniform full-face row; mixed contextual runs are not yet supported"
+                    .into(),
+            ));
+        }
+    }
+    let measured: Vec<_> = rows.iter().map(|r| measure(r)).collect::<Result<_, _>>()?;
+    let mut shaped_runs = HashMap::new();
+    let mut segment_advances = HashMap::new();
+    for (row_index, row) in rows.iter().enumerate() {
+        let mut at = 0;
+        while let Some(item) = row.get(at) {
+            let mut end = at + 1;
+            while row.get(end).is_some_and(|v| v.1 == item.1 && v.2 == item.2) {
+                end += 1;
+            }
+            segment_advances.insert((row_index, at), row.get(at..end).unwrap_or_default().iter().map(&advance).sum::<f64>());
+            let string: String = row.get(at..end).unwrap_or_default().iter().map(|v| v.0).collect();
+            if let Some((bytes, shaped, family)) = shape_source(doc, &fonts, &item.2, &string)? {
+                shaped_runs.insert((row_index, at), (bytes, shaped, family));
+            }
+            at = end;
+        }
+    }
+    let mut glyph_resources = HashMap::new();
+    for (key, (bytes, shaped, family)) in &shaped_runs {
+        let mappings: Vec<_> = shaped.glyphs.iter().map(|g| (g.text.clone(), g.id)).collect();
+        let resource = pdfcraft_fonts::embedding::embed_mapping(doc, &mut fonts, bytes, family, &mappings).map_err(EditError::Invalid)?;
+        glyph_resources.insert(*key, resource);
+    }
+    let n = pdfcraft_content::num;
+    let mut block_ops = vec![Op::new("q", vec![])];
+    block_ops.extend(reveal_ops(block, lines, style, first.origin.ctm)?);
+    let back = Matrix([first.origin.ctm[0], first.origin.ctm[1], first.origin.ctm[2], first.origin.ctm[3], 0.0, 0.0])
+        .invert()
+        .ok_or_else(|| EditError::Invalid("the paragraph is drawn in a space it cannot be edited in".into()))?;
+    let (tx, ty) = back.apply(dx, dy);
+    block_ops.push(Op::new("cm", vec![n(1.0), n(0.0), n(0.0), n(1.0), n(tx), n(ty)]));
+    let centre = (block.rect[0] + block.rect[2]) / 2.0;
+    let lefts: Vec<_> = block.rows.iter().filter_map(|r| row_rect(r, lines).map(|r| r[0])).collect();
+    let left_span = lefts.iter().copied().fold(f64::NEG_INFINITY, f64::max) - lefts.iter().copied().fold(f64::INFINITY, f64::min);
+    let centered = block.rows.len() > 1
+        && left_span > first.size * 0.5
+        && block.rows.iter().all(|row| row_rect(row, lines).is_some_and(|r| ((r[0] + r[2]) / 2.0 - centre).abs() < first.size));
+    let source_leading = block
+        .rows
+        .windows(2)
+        .filter_map(|rows| {
+            let a = rows[0].first().and_then(|i| lines.get(*i))?;
+            let b = rows[1].first().and_then(|i| lines.get(*i))?;
+            Some((a.origin.baseline - b.origin.baseline).abs())
+        })
+        .rfind(|v| *v > 0.0)
+        .unwrap_or(first.size * 1.5);
+    let mut baseline = first.origin.baseline;
+    for (row_index, row) in rows.iter().enumerate() {
+        let anchor = block.rows.get(row_index).and_then(|r| r.first()).and_then(|i| lines.get(*i));
+        if style.line_spacing.is_none()
+            && style.size.is_none()
+            && let Some(anchor) = anchor
+        {
+            baseline = anchor.origin.baseline;
+        }
+        let anchor = anchor.unwrap_or(first);
+        let w = measured.get(row_index).copied().unwrap_or(0.0);
+        let align = style.align.unwrap_or(if centered { crate::added::Align::Center } else { crate::added::Align::Left });
+        let original_rect = block.rows.get(row_index).and_then(|row| row_rect(row, lines)).unwrap_or(block.rect);
+        let left = if style.width.is_none() && style.align.is_none() { original_rect[0] } else { block.rect[0] };
+        let available = if style.width.is_none() && style.align.is_none() { original_rect[2] - original_rect[0] } else { width };
+        let mut x = left
+            + match align {
+                crate::added::Align::Center => (available - w) / 2.0,
+                crate::added::Align::Right => available - w,
+                _ => 0.0,
+            };
+        let mut pos = 0;
+        while pos < row.len() {
+            let Some(item) = row.get(pos) else { break };
+            let source = lines.get(item.1).unwrap_or(first);
+            let mut end = pos + 1;
+            while row.get(end).is_some_and(|other| other.1 == item.1 && other.2 == item.2) {
+                end += 1;
+            }
+            let segment = row.get(pos..end).unwrap_or_default();
+            let string: String = segment.iter().map(|c| c.0).collect();
+            let m = metrics.get(&item.2).ok_or_else(|| EditError::Invalid("the paragraph font is missing".into()))?;
+            let mut state = source.origin.state.clone();
+            state.font = Some((item.2.clone(), size_of(source, item.1)));
+            if let Some(c) = overrides.get(&item.1).and_then(|r| r.char_spacing).or(style.char_spacing) {
+                state.char_spacing = c / source.origin.k.max(1e-6);
+            }
+            if let Some(s) = overrides.get(&item.1).and_then(|r| r.scale).or(style.scale) {
+                state.scale = (s / 100.0).clamp(0.1, 10.0);
+            }
+            if !shaped_runs.contains_key(&(row_index, pos)) {
+                state.scale *= calibration.get(&item.1).copied().unwrap_or(1.0);
+            }
+            if let Some([r, g, b]) = overrides.get(&item.1).and_then(|r| r.color).or(style.color) {
+                state.fill = vec![Op::new("rg", vec![n(r), n(g), n(b)])];
+            }
+            let inverse = Matrix(first.origin.ctm).invert().ok_or_else(|| EditError::Invalid("the paragraph has a singular transform".into()))?;
+            let mut tm = Matrix(source.origin.tm).then(&Matrix(source.origin.ctm)).then(&inverse).0;
+            let (ax, ay) = back.apply(x - source.origin.x, baseline - source.origin.baseline);
+            tm[4] += ax;
+            tm[5] += ay;
+            let mut segment_width = segment_advances.get(&(row_index, pos)).copied().unwrap_or(0.0);
+            if let Some((_, shaped, _)) = shaped_runs.get(&(row_index, pos)) {
+                let resource = glyph_resources.get(&(row_index, pos)).ok_or_else(|| EditError::Invalid("shaped font is missing".into()))?;
+                let mut properties = Dict::new();
+                properties.set(b"ActualText".to_vec(), Object::String(PdfString::text(&string)));
+                block_ops.push(Op::new("BDC", vec![Object::name("Span"), Object::Dict(properties)]));
+                state.font = Some((resource.clone(), size_of(source, item.1)));
+                // Absolute glyph matrices preserve marks and contextual positions; font-program
+                // codes are separate from Unicode and ToUnicode/ActualText keep logical text.
+                let size = size_of(source, item.1);
+                let mut extra = 0.0;
+                for (i, glyph) in shaped.glyphs.iter().enumerate() {
+                    let mut matrix = tm;
+                    let x = (glyph.position[0] * size + extra) * state.scale;
+                    let y = glyph.position[1] * size;
+                    matrix[4] += matrix[0] * x + matrix[2] * y;
+                    matrix[5] += matrix[1] * x + matrix[3] * y;
+                    let code = u16::try_from(i + 1).map_err(|_| EditError::Invalid("shaped glyph limit".into()))?;
+                    block_ops.push(Op::new("BT", vec![]));
+                    block_ops.extend(state.ops());
+                    block_ops.push(Op::new("Tm", matrix.map(n).to_vec()));
+                    block_ops.push(Op::new("Tj", vec![Object::String(PdfString::literal(code.to_be_bytes().to_vec()))]));
+                    block_ops.push(Op::new("ET", vec![]));
+                    extra += state.char_spacing * glyph.text.chars().count() as f64 + state.word_spacing * glyph.text.matches(' ').count() as f64;
+                }
+                block_ops.push(Op::new("EMC", vec![]));
+                segment_width = (shaped.advance * size + extra) * state.scale * source.origin.k;
+            } else {
+                block_ops.push(Op::new("BT", vec![]));
+                block_ops.extend(state.ops());
+                block_ops.push(Op::new("Tm", tm.iter().map(|v| n(*v)).collect()));
+                block_ops.extend(source_show(
+                    m,
+                    &string,
+                    size_of(source, item.1),
+                    source_space(doc, &fonts, m),
+                    state.char_spacing,
+                    state.word_spacing,
+                )?);
+                block_ops.push(Op::new("ET", vec![]));
+            }
+            if underlines.get(&item.1).copied().or(style.underline) == Some(true) {
+                let [r, g, b] = overrides.get(&item.1).and_then(|r| r.color).or(style.color).unwrap_or(source.color);
+                let underline_size = size_of(source, item.1) * source.origin.k;
+                let (x0, y0) = back.apply(x - first.origin.ctm[4], baseline - first.origin.ctm[5] - underline_size * 0.12);
+                let (x1, y1) = back.apply(x + segment_width - first.origin.ctm[4], baseline - first.origin.ctm[5] - underline_size * 0.12);
+                block_ops.push(Op::new("RG", vec![n(r), n(g), n(b)]));
+                block_ops.push(Op::new("w", vec![n(underline_size * 0.06 / first.origin.ctm[2].hypot(first.origin.ctm[3]).max(1e-6))]));
+                block_ops.push(Op::new("m", vec![n(x0), n(y0)]));
+                block_ops.push(Op::new("l", vec![n(x1), n(y1)]));
+                block_ops.push(Op::new("S", vec![]));
+            }
+            x += segment_width;
+            pos = end;
+        }
+        baseline -= if style.line_spacing.is_none() && style.size.is_none() {
+            source_leading
+        } else {
+            style.line_spacing.unwrap_or(1.5).clamp(0.5, 5.0) * style.size.unwrap_or(anchor.size)
+        };
+    }
+    block_ops.push(Op::new("Q", vec![]));
+    let streams = content_streams(doc, &p.dict);
+    let pieces = Pieces::join(&streams.iter().map(|(_, d)| d.as_slice()).collect::<Vec<_>>());
+    let ops = pieces.parse().ops;
+    let members: Vec<_> = block.lines.iter().filter_map(|i| lines.get(*i)).collect();
+    let mut drop = coincident_ops(lines, &members);
+    drop.extend(members.iter().flat_map(|l| l.ops.iter().copied()));
+    let o = &first.origin;
+    let start = first.ops.first().copied().unwrap_or(o.bt_op);
+    let split = ops
+        .get(o.bt_op..start)
+        .unwrap_or_default()
+        .iter()
+        .enumerate()
+        .any(|(i, op)| matches!(op.op.as_slice(), b"Tj" | b"TJ" | b"'" | b"\"") && !drop.contains(&(o.bt_op + i)));
+    let after = if split { &o.state } else { &o.bt_state };
+    block_ops.extend(after.ops());
+    if split {
+        block_ops.insert(0, Op::new("ET", vec![]));
+        block_ops.push(Op::new("BT", vec![]));
+        block_ops.push(Op::new("Tm", o.tlm.iter().map(|v| n(*v)).collect()));
+    }
+    let at = if split { start } else { o.bt_op };
+    let data = splice(&pieces, &ops, |i| (if i == at { std::mem::take(&mut block_ops) } else { Vec::new() }, !drop.contains(&i)));
+    let contents = rewritten_contents(doc, &streams, data);
+    res.set(b"Font".to_vec(), Object::Dict(fonts));
+    doc.update_dict(p.obj, |d| {
+        d.set(b"Contents".to_vec(), contents);
+        d.set(b"Resources".to_vec(), Object::Dict(res));
+    })?;
+    Ok(LineEdit { substituted })
+}

crates/engine/README.md

@@ -78,3 +78,7 @@ family (`sign`, `sign_with_timestamp`, `timestamp_document`, `embed_ltv`).
 - Performance budgets (`misc.performance-budgets`) are not set or enforced.
 - Some shipped features are still reachable only from the UI, not through an `automation` tool;
   `cargo xtask parity` lists them; closing that gap is tracked in the execution plan (D4).
+
+`doc.text_edit_preview(page, block)` prepares a read-only page background with the selected
+paragraph’s glyphs removed, preserving text positioning, images and colours. It shares the
+working document’s render configuration and never enters the undo history.

crates/engine/src/autotag.rs

@@ -0,0 +1,86 @@
+//! Reviewable structure proposals for pages that have not yet been tagged.
+//!
+//! A proposal is deliberately not a PDF tag. It records the visible text blocks and the
+//! evidence for a tentative role, so a later edit can attach marked content and a parent tree
+//! without presenting a font-size guess as a finished accessible document.
+
+use crate::Document;
+
+/// A bounded text block proposed for a structure element.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Candidate {
+    pub kind: &'static str,
+    pub reason: &'static str,
+    pub text: String,
+    pub text_truncated: bool,
+    pub rect: [f64; 4],
+    pub size: f64,
+    pub bold: bool,
+}
+
+/// The visible text portion of one page's proposed structure.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Preview {
+    pub candidates: Vec<Candidate>,
+    /// Raster or grouped artwork requires separate figure/artifact review.
+    pub unclassified_images: usize,
+    /// Text blocks omitted because their geometry or font size was invalid.
+    pub unclassified_text_blocks: usize,
+    /// Existing structure must be reconciled before any proposal is applied.
+    pub existing_structure: bool,
+}
+
+const MAX_BLOCKS: usize = 2_048;
+const MAX_TEXT_CHARS: usize = 512;
+
+impl Document {
+    /// Propose text tags for one 0-based page. This reads the current working PDF and does not
+    /// alter it. Every result needs review before tags are written; image and table semantics
+    /// are outside this text-only proposal.
+    pub fn autotag_preview(&self, page: usize) -> Result<Preview, String> {
+        if self.info.pages.get(page).is_none() {
+            return Err(format!("page {} is outside the document", page.saturating_add(1)));
+        }
+        let editor = self.editor.as_ref().ok_or("the document can't be read")?;
+        let existing_structure = editor.cos.root().is_some_and(|r| editor.cos.get(r).as_dict().is_some_and(|d| d.contains(b"StructTreeRoot")));
+        let blocks = pdfcraft_edit::text_blocks(&editor.cos, page).map_err(|e| e.to_string())?;
+        if blocks.len() > MAX_BLOCKS {
+            return Err(format!("page {} has too many text blocks to preview (maximum {MAX_BLOCKS})", page.saturating_add(1)));
+        }
+        let mut sizes: Vec<f64> = blocks.iter().map(|b| b.size).filter(|s| s.is_finite() && *s > 0.0).collect();
+        sizes.sort_by(f64::total_cmp);
+        let body_size = sizes.get(sizes.len().saturating_sub(1) / 2).copied().unwrap_or(12.0);
+        let mut unclassified_text_blocks = 0;
+        let candidates = blocks
+            .into_iter()
+            .filter(|b| {
+                let valid = !b.text.trim().is_empty() && b.rect.iter().all(|v| v.is_finite()) && b.size.is_finite() && b.size > 0.0;
+                if !valid {
+                    unclassified_text_blocks += 1;
+                }
+                valid
+            })
+            .map(|b| {
+                let mut chars = b.text.chars();
+                let text: String = chars.by_ref().take(MAX_TEXT_CHARS).collect();
+                let text_truncated = chars.next().is_some();
+                let short_line = b.rows.len() == 1 && b.text.chars().count() <= 120;
+                let heading = short_line && b.size.is_finite() && b.size > body_size * 1.35;
+                Candidate {
+                    kind: if heading { "H1" } else { "P" },
+                    reason: if heading {
+                        "short, single-line text larger than the page body"
+                    } else {
+                        "visible text block; semantic role needs review"
+                    },
+                    text,
+                    text_truncated,
+                    rect: b.rect,
+                    size: b.size,
+                    bold: b.bold,
+                }
+            })
+            .collect();
+        Ok(Preview { candidates, unclassified_images: self.page_images(page).len(), unclassified_text_blocks, existing_structure })
+    }
+}

crates/engine/src/build_info.rs

@@ -0,0 +1,35 @@
+//! What this build calls itself. A local or patched build sets `PDFCRAFT_BUILD_LABEL` at compile
+//! time (`PDFCRAFT_BUILD_LABEL=titlebar cargo build`, or through `packaging/linux/package.sh`), so
+//! it can be told from the release of the same version. The version itself stays the release's:
+//! the update check compares it with published releases.
+
+/// The release version from the workspace `Cargo.toml`.
+pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// The compile-time build label, if any.
+pub const LABEL: Option<&str> = option_env!("PDFCRAFT_BUILD_LABEL");
+
+/// The version as shown to people: `0.7.1`, or `0.7.1 (titlebar)` for a labelled build.
+pub fn version() -> String {
+    describe(VERSION, LABEL)
+}
+
+fn describe(version: &str, label: Option<&str>) -> String {
+    match label.map(str::trim).filter(|l| !l.is_empty()) {
+        Some(label) => format!("{version} ({label})"),
+        None => version.to_owned(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::describe;
+
+    #[test]
+    fn a_label_follows_the_version_and_a_blank_one_is_ignored() {
+        assert_eq!(describe("0.7.1", None), "0.7.1");
+        assert_eq!(describe("0.7.1", Some("")), "0.7.1");
+        assert_eq!(describe("0.7.1", Some("  ")), "0.7.1");
+        assert_eq!(describe("0.7.1", Some("titlebar")), "0.7.1 (titlebar)");
+    }
+}

crates/engine/src/camera_edges.rs

@@ -232,7 +232,8 @@ fn support(a: Point, b: Point, edges: &[Option<Edge>], w: usize, h: usize) -> f6
             edges.get(y as usize * w + x as usize).copied().flatten().is_some_and(|e| {
                 // Either way across: dark-to-light or light-to-dark.
                 let d = (e.dir - normal).rem_euclid(std::f32::consts::PI);
-                d < 0.35 || d > std::f32::consts::PI - 0.35
+                // A NaN direction is no hit, as the two comparisons it replaces said.
+                !d.is_nan() && !(0.35..=std::f32::consts::PI - 0.35).contains(&d)
             })
         });
         hits += hit as usize;

crates/engine/src/catalog.rs

@@ -71,7 +71,7 @@ pub static TOOL_GROUPS: &[ToolGroup] = &[
             items: &[
                 item("Microsoft Word (.docx)", "file-text", "export.docx", Ready),
                 item("Spreadsheet (.xlsx)", "grid-3x3", "export.xlsx", Planned("M10")),
-                item("Presentation (.pptx)", "presentation", "export.pptx", Planned("M10")),
+                item("Presentation (.pptx)", "presentation", "export.pptx", Ready),
                 item("Image (PNG)", "image", "export.image", Ready),
                 item("Export all images", "image", "export.all_images", Ready),
                 item("HTML web page", "file-symlink", "export.html", Ready),
@@ -150,6 +150,7 @@ pub static TOOL_GROUPS: &[ToolGroup] = &[
             items: &[
                 item("Single file", "file-input", "create.file", Ready),
                 item("Multiple files", "files", "create.multiple", Ready),
+                item("Separate PDFs", "files", "create.multiple_separate", Ready),
                 item("Images", "image", "create.images", Ready),
                 item("Clipboard", "copy-plus", "create.clipboard", Ready),
                 item("Blank page", "file-plus-2", "create.blank", Ready),
@@ -456,11 +457,12 @@ pub static TOOL_GROUPS: &[ToolGroup] = &[
         sections: &[ToolSection {
             title: "Accessibility",
             items: &[
-                item("Automatically tag PDF", "tag", "a11y.autotag", Planned("M12")),
+                item("Automatically tag PDF", "tag", "a11y.autotag", Ready),
                 item("Change reading options", "book-open", "a11y.reading_options", Ready),
                 item("Check for accessibility", "accessibility", "a11y.check", Ready),
                 item("Open accessibility report", "file-text", "a11y.report", Ready),
                 item("Add alternate text", "image", "a11y.alt_text", Ready),
+                item("Tags panel", "tag", "a11y.tags", Ready),
                 item("Fix reading order", "list-ordered", "a11y.reading_order", Planned("M12")),
             ],
         }],

crates/engine/src/commands.rs

@@ -179,6 +179,7 @@ pub const COMMANDS: &[CommandSpec] = &[
     c("page.paste", "Paste pages", None, None, Assembly, "clipboard-paste"),
     c("create.file", "Create PDF from file…", FILE, None, Nothing, "file-input"),
     c("create.multiple", "Create PDF from multiple files…", FILE, None, Nothing, "files"),
+    c("create.multiple_separate", "Create separate PDFs…", FILE, None, Nothing, "files"),
     c("create.images", "Create PDF from images…", FILE, None, Nothing, "image"),
     c("create.clipboard", "Create PDF from clipboard", FILE, None, Nothing, "copy-plus"),
     c("page.combine", "Combine files…", FILE, None, Nothing, "files"),
@@ -215,6 +216,11 @@ pub const COMMANDS: &[CommandSpec] = &[
     c("edit.snapshot", "Take a snapshot", EDIT, None, Copying, "camera"),
     c("view.full_screen", "Full screen mode", VIEW, Some(Shortcut::cmd("L")), Document, "maximize"),
     c("view.read_mode", "Read mode", VIEW, Some(Shortcut { command: true, shift: false, mac_ctrl: true, key: "H" }), Document, "book-open"),
+    // Browsers' tab keys (#1542): Ctrl+Tab on every platform, ⌃Tab rather than ⌘Tab on macOS,
+    // where the system takes ⌘Tab. They follow the tabs' order on screen and wrap around, and
+    // also run from Combine files, which has no document open.
+    c("view.next_tab", "Next tab", VIEW, Some(Shortcut { command: false, shift: false, mac_ctrl: true, key: "Tab" }), Nothing, "chevron-right"),
+    c("view.previous_tab", "Previous tab", VIEW, Some(Shortcut { command: false, shift: true, mac_ctrl: true, key: "Tab" }), Nothing, "chevron-left"),
     c("view.focus_page_input", "Go to page…", VIEW, Some(Shortcut::cmd_shift("N")), Document, "text-cursor-input"),
     c("ui.dock.reset", "Reset panel layout", VIEW, None, Nothing, "settings"),
     c("view.theme", "Switch light / dark theme", None, None, Nothing, "moon"),
@@ -310,6 +316,7 @@ pub const COMMANDS: &[CommandSpec] = &[
     c("optimize.advanced", "Optimize PDF…", FILE, None, Document, "settings-2"),
     c("export.text", "Export to text…", FILE, None, Copying, "type"),
     c("export.docx", "Export to Word…", FILE, None, Copying, "file-text"),
+    c("export.pptx", "Export to PowerPoint…", FILE, None, Copying, "presentation"),
     c("export.html", "Export to HTML…", FILE, None, Copying, "file-symlink"),
     c("export.rtf", "Export to RTF…", FILE, None, Copying, "file-text"),
     c("app.preferences", "Preferences…", EDIT, Some(Shortcut::cmd(",")), Nothing, "settings"),
@@ -319,9 +326,11 @@ pub const COMMANDS: &[CommandSpec] = &[
     c("ocr.enhance_camera", "Enhance camera image", None, None, Modification, "camera"),
     c("ocr.recognize_batch", "Recognize text in multiple files…", None, None, Nothing, "files"),
     c("a11y.check", "Check for accessibility…", None, None, Document, "accessibility"),
+    c("a11y.autotag", "Automatically tag PDF", None, None, Document, "tag"),
     c("a11y.report", "Open accessibility report", None, None, Document, "file-text"),
     c("a11y.reading_options", "Change reading options…", None, None, Document, "book-open"),
     c("a11y.alt_text", "Add alternate text…", None, None, Modification, "image"),
+    c("a11y.tags", "Tags panel", None, None, Document, "tag"),
     c("export.all_images", "Export all images…", FILE, None, Copying, "image"),
     c("edit.header_footer", "Add header & footer…", None, None, Modification, "heading"),
     c("edit.header_footer.update", "Update header & footer…", None, None, Marks(crate::MarkKind::HeaderFooter), "heading"),

crates/engine/src/compare.rs

@@ -64,13 +64,12 @@ impl Session {
         let (mut ra, mut rb) = (renderer(a), renderer(b));
         let scale = dpi.clamp(18.0, 150.0) / 72.0;
         let mut out = Vec::new();
-        for page in 0..a.info.pages.len().min(b.info.pages.len()) {
+        for (page, info) in b.info.pages.iter().enumerate().take(a.info.pages.len()) {
             let req = pdfcraft_render::RenderRequest { page, scale, ..Default::default() };
             let (x, y) = (ra.render(req), rb.render(req));
             if x.error.is_some() || y.error.is_some() {
                 continue;
             }
-            let info = &b.info.pages[page];
             let s = y.width as f32 / info.width.max(1e-3);
             for r in pdfcraft_compare::visual_regions((&y.rgba, y.width, y.height), (&x.rgba, x.width, x.height), 24) {
                 let p = info.view_to_user(r[0] as f32 / s, r[1] as f32 / s);
@@ -85,7 +84,7 @@ impl Session {
     pub fn compare_report(&self, old: DocId, new: DocId) -> Result<Arc<Vec<u8>>, EditError> {
         let c = self.compare(old, new)?;
         let name = |id| self.get(id).map(|d| d.name.clone()).unwrap_or_default();
-        self.create_from_text("Compare Report", &pdfcraft_compare::report(&c, &name(old), &name(new)))
+        self.create_report("Compare Report", &pdfcraft_compare::report(&c, &name(old), &name(new)))
     }
 
     /// Mark the differences in `new` as comments: highlights over replaced and inserted text
@@ -122,10 +121,11 @@ impl Session {
     }
 }
 
-/// Export a PDF ▸ Word, HTML or RTF.
+/// Export a PDF ▸ Word, PowerPoint, HTML or RTF.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum OfficeFormat {
     Docx,
+    Pptx,
     Html,
     Rtf,
 }
@@ -134,6 +134,7 @@ impl OfficeFormat {
     pub fn extension(self) -> &'static str {
         match self {
             OfficeFormat::Docx => "docx",
+            OfficeFormat::Pptx => "pptx",
             OfficeFormat::Html => "html",
             OfficeFormat::Rtf => "rtf",
         }
@@ -142,6 +143,7 @@ impl OfficeFormat {
     pub fn from_extension(ext: &str) -> Option<OfficeFormat> {
         match ext.to_ascii_lowercase().as_str() {
             "docx" => Some(OfficeFormat::Docx),
+            "pptx" => Some(OfficeFormat::Pptx),
             "html" | "htm" => Some(OfficeFormat::Html),
             "rtf" => Some(OfficeFormat::Rtf),
             _ => None,
@@ -159,6 +161,16 @@ impl crate::Document {
             .iter()
             .enumerate()
             .map(|(i, info)| {
+                // Export uses the visible page in points, y up. Raw PDF coordinates include
+                // CropBox offsets and precede /Rotate and /UserUnit.
+                let visible_rect = |r: [f64; 4]| {
+                    let a = info.user_to_view(r[0] as f32, r[1] as f32);
+                    let b = info.user_to_view(r[2] as f32, r[3] as f32);
+                    [a[0].min(b[0]) as f64, (info.height - a[1].max(b[1])) as f64, a[0].max(b[0]) as f64, (info.height - a[1].min(b[1])) as f64]
+                };
+                let crop_width = f64::from(info.crop[2] - info.crop[0]);
+                let display_width = f64::from(if info.rotation % 180 == 0 { info.width } else { info.height });
+                let unit = if crop_width > 0.0 && crop_width.is_finite() && display_width.is_finite() { display_width / crop_width } else { 1.0 };
                 let blocks = pdfcraft_edit::reading_blocks(cos, i)
                     .unwrap_or_default()
                     .into_iter()
@@ -167,11 +179,12 @@ impl crate::Document {
                         let f = b.base_font.to_ascii_lowercase();
                         pdfcraft_export::Block {
                             text: b.text,
-                            rect: b.rect,
-                            size: b.size,
+                            rect: visible_rect(b.rect),
+                            size: b.size * unit,
                             bold: f.contains("bold") || f.contains("black") || f.contains("heavy"),
                             italic: f.contains("italic") || f.contains("oblique"),
                             color: b.color,
+                            rotation: b.rotation - f64::from(info.rotation),
                         }
                     })
                     .collect();
@@ -180,7 +193,13 @@ impl crate::Document {
                     .iter()
                     .filter_map(|im| {
                         let (ext, bytes) = pdfcraft_create::image_file(cos, im.object?).ok()?;
-                        Some(pdfcraft_export::Image { ext: if ext == "jpg" { "jpg" } else { "png" }, bytes, rect: im.rect })
+                        Some(pdfcraft_export::Image {
+                            ext: if ext == "jpg" { "jpg" } else { "png" },
+                            bytes,
+                            rect: visible_rect(im.rect),
+                            size: [im.matrix[0].hypot(im.matrix[1]) * unit, im.matrix[2].hypot(im.matrix[3]) * unit],
+                            rotation: im.matrix[1].atan2(im.matrix[0]).to_degrees() - f64::from(info.rotation),
+                        })
                     })
                     .collect();
                 pdfcraft_export::Page { width: info.width as f64, height: info.height as f64, blocks, images }
@@ -188,12 +207,13 @@ impl crate::Document {
             .collect()
     }
 
-    /// The document as a Word, HTML or RTF file.
+    /// The document as a Word, PowerPoint, HTML or RTF file.
     pub fn export_office(&self, format: OfficeFormat) -> Vec<u8> {
         let pages = self.export_pages();
         let title = self.info.title.clone().unwrap_or_else(|| self.name.trim_end_matches(".pdf").to_string());
         match format {
             OfficeFormat::Docx => pdfcraft_export::docx(&pages, &title),
+            OfficeFormat::Pptx => pdfcraft_export::pptx(&pages, &title),
             OfficeFormat::Html => pdfcraft_export::html(&pages, &title).into_bytes(),
             OfficeFormat::Rtf => pdfcraft_export::rtf(&pages).into_bytes(),
         }

crates/engine/src/copy_image.rs

@@ -0,0 +1,108 @@
+//! Copy Image: find the picture under a point and hand it to the clipboard, as pixels or as a
+//! file in its original format. A picture drawn through grouped
+//! Form artwork (as Word, InDesign and many scanners write them) is found inside the group.
+
+use std::collections::HashSet;
+
+use pdfcraft_cos::{Dict, Document as Cos, ObjRef, Object};
+
+use crate::Document;
+
+/// Clipboards copy the whole bitmap; past this many pixels a pixel copy is refused.
+const MAX_COPY_PIXELS: u64 = 64_000_000;
+/// How deep Form artwork is searched for its picture.
+const MAX_FORM_DEPTH: usize = 12;
+
+impl Document {
+    /// The topmost picture on `page` under user-space point `at`, as its index in
+    /// [`Document::page_images`]: a raster image, or Form artwork that holds one.
+    pub fn page_image_at(&self, page: usize, at: [f64; 2]) -> Option<usize> {
+        let editor = self.editor.as_ref()?;
+        let inside = |r: &[f64; 4]| (r[0]..=r[2]).contains(&at[0]) && (r[1]..=r[3]).contains(&at[1]);
+        self.page_images(page).iter().rposition(|i| {
+            inside(&i.rect)
+                && match (i.is_form, i.object) {
+                    (false, Some(_)) => true,
+                    (true, Some(form)) => picture_in_form(&editor.cos, form).is_some(),
+                    _ => false,
+                }
+        })
+    }
+
+    /// Copy Image in Original Format: picture `index` on `page` as a file (extension, bytes):
+    /// a JPEG as stored in the PDF, otherwise a lossless PNG.
+    pub fn page_image_copy_file(&self, page: usize, index: usize) -> Result<(&'static str, Vec<u8>), String> {
+        let editor = self.editor.as_ref().ok_or("the document can't be read")?;
+        let img = self.page_images(page).into_iter().nth(index).ok_or_else(|| format!("page {} has no image {}", page + 1, index + 1))?;
+        let object = img.object.ok_or("the image has no object")?;
+        let picture = if img.is_form { picture_in_form(&editor.cos, object).ok_or("this artwork holds no picture")? } else { object };
+        pdfcraft_create::image_file(&editor.cos, picture)
+    }
+
+    /// Copy Image: picture `index` on `page` at its own resolution, as straight (unpremultiplied)
+    /// RGBA pixels (width, height, pixels) for the clipboard. Soft masks become alpha.
+    pub fn page_image_rgba(&self, page: usize, index: usize) -> Result<(u32, u32, Vec<u8>), String> {
+        let (_, bytes) = self.page_image_copy_file(page, index)?;
+        let format = image::guess_format(&bytes).map_err(|e| e.to_string())?;
+        let mut reader = image::ImageReader::with_format(std::io::Cursor::new(bytes.as_slice()), format);
+        let mut limits = image::Limits::default();
+        limits.max_alloc = Some(MAX_COPY_PIXELS * 4);
+        reader.limits(limits);
+        let decoder = reader.into_decoder().map_err(|e| e.to_string())?;
+        let (w, h) = image::ImageDecoder::dimensions(&decoder);
+        if w == 0 || h == 0 {
+            return Err("the image is empty".into());
+        }
+        if u64::from(w) * u64::from(h) > MAX_COPY_PIXELS {
+            return Err(format!("the image is too large to copy ({w} × {h} pixels); use Save Image As"));
+        }
+        let rgba = image::DynamicImage::from_decoder(decoder).map_err(|e| e.to_string())?.into_rgba8();
+        Ok((rgba.width(), rgba.height(), rgba.into_raw()))
+    }
+}
+
+/// The largest raster image Form `form` draws through its resources (nested Forms included).
+fn picture_in_form(cos: &Cos, form: ObjRef) -> Option<ObjRef> {
+    let mut seen = HashSet::from([form]);
+    let mut best: Option<(u64, ObjRef)> = None;
+    let res = resources(cos, form)?;
+    collect(cos, &res, 0, &mut seen, &mut best);
+    best.map(|(_, r)| r)
+}
+
+fn resources(cos: &Cos, stream: ObjRef) -> Option<Dict> {
+    match &*cos.get(stream) {
+        Object::Stream(s) => s.dict.get(b"Resources").map(|r| cos.resolve(r)).and_then(|r| r.as_dict().cloned()),
+        _ => None,
+    }
+}
+
+fn collect(cos: &Cos, res: &Dict, depth: usize, seen: &mut HashSet<ObjRef>, best: &mut Option<(u64, ObjRef)>) {
+    if depth > MAX_FORM_DEPTH {
+        return;
+    }
+    let Some(xobjects) = res.get(b"XObject").map(|x| cos.resolve(x)).and_then(|x| x.as_dict().cloned()) else { return };
+    for (_, v) in xobjects.iter() {
+        let Some(r) = v.as_ref() else { continue };
+        if !seen.insert(r) {
+            continue;
+        }
+        let obj = cos.get(r);
+        let Object::Stream(s) = &*obj else { continue };
+        match s.dict.name(b"Subtype") {
+            Some(b"Image") => {
+                let px = |k: &[u8]| u64::try_from(s.dict.int(k).unwrap_or(0)).unwrap_or(0);
+                let size = px(b"Width").saturating_mul(px(b"Height"));
+                if size > 0 && best.is_none_or(|(b, _)| size > b) {
+                    *best = Some((size, r));
+                }
+            }
+            Some(b"Form") => {
+                if let Some(inner) = resources(cos, r) {
+                    collect(cos, &inner, depth + 1, seen, best);
+                }
+            }
+            _ => {}
+        }
+    }
+}