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:
@@ -27,18 +30,24 @@ jobs:
         # and release.yml builds macOS (a failing release is fixed and rebuilt).
         os: [ubuntu-latest, windows-latest]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # The optional craft-fonts build input (Japanese fonts), so the Japanese font tests run on
       # Linux; Windows tests the build without it. See craftrules standards/fonts.md.
       - name: Check out craft-fonts (Linux)
         if: runner.os == 'Linux'
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        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: |
@@ -47,8 +56,9 @@ jobs:
             libxkbcommon-dev libwayland-dev libx11-dev libxrandr-dev libxi-dev \
             libgl1-mesa-dev libgtk-3-dev
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@686976e191b89faba57d3206551f0f330d8cb249 # stable
         with:
+          toolchain: stable
           components: clippy, rustfmt
 
       - name: Require Windows executable resources
@@ -56,7 +66,7 @@ jobs:
         run: Add-Content -Path $env:GITHUB_ENV -Value 'PDFCRAFT_REQUIRE_WINRES=1'
         shell: pwsh
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
 
       - name: Format
         if: runner.os == 'Linux'
@@ -71,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)
@@ -91,11 +99,12 @@ jobs:
     name: wasm32 check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: dtolnay/rust-toolchain@686976e191b89faba57d3206551f0f330d8cb249 # stable
         with:
+          toolchain: stable
           targets: wasm32-unknown-unknown
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           key: wasm32
       - name: Check library crates for wasm32
@@ -105,7 +114,7 @@ jobs:
     name: dependency licences and advisories
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: EmbarkStudios/cargo-deny-action@v2
         with:
           command: check
@@ -115,9 +124,11 @@ jobs:
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: dtolnay/rust-toolchain@686976e191b89faba57d3206551f0f330d8cb249 # stable
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
         with:
           key: fuzz
       - name: Fetch the pdf.js corpus (seeds)
@@ -126,7 +137,7 @@ jobs:
         run: cargo xtask fuzz --time 900 --seed ${{ github.run_number }}
       - name: Upload findings
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: fuzz-findings
           path: fuzz-out/findings

.github/workflows/freebsd.yml

@@ -23,30 +23,7 @@ permissions:
 
 jobs:
   freebsd:
-    name: FreeBSD 14 (build + test)
-    runs-on: ubuntu-latest
-    timeout-minutes: 300
-    steps:
-      - uses: actions/checkout@v4
-      - name: Build and test in a FreeBSD VM
-        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc # v1
-        with:
-          release: "14.3"
-          usesh: true
-          cpu: 4
-          mem: 12288
-          # Nothing to bring back; copying the target dir out of the VM fails on large builds.
-          copyback: false
-          prepare: |
-            pkg install -y bash git curl pkgconf cmake python3 libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
-            curl -fsSL https://sh.rustup.rs | sh -s -- -y --profile minimal
-          run: |
-            . "$HOME/.cargo/env"
-            # The checkout is synced in under another owner; let tests that call git read it.
-            git config --global --add safe.directory "*"
-            rustc --version
-            CARGO_PROFILE_DEV_DEBUG=0 cargo build --workspace --all-targets --locked
-            CARGO_PROFILE_DEV_DEBUG=0 cargo test --workspace --locked
-            # The release packaging, end to end (a quicker release profile than the real release).
-            CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 packaging/freebsd/package.sh
-            tar -tzf dist/release/pdfcraft-*-freebsd-*.tar.gz | grep -E '/bin/pdfcraft$|/bin/pdfcraft-cli$|applications/|/share/pdfcraft/models/.+\.rten$'
+    # 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: 3d9ab3a132ed0eff457e424226a435a901da30d3

.github/workflows/packaging-lint.yml

@@ -19,48 +19,5 @@ concurrency:
 
 jobs:
   lint:
-    runs-on: ubuntu-latest
-    env:
-      ACTIONLINT_VERSION: 1.7.12
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install tools
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends shellcheck desktop-file-utils appstream libxml2-utils python3-yaml
-          curl -fsSL "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" \
-            | tar -xz -C "$RUNNER_TEMP" actionlint
-      - name: actionlint
-        run: |
-          "$RUNNER_TEMP/actionlint" -color
-      - name: shellcheck
-        run: shellcheck packaging/*.sh packaging/*/*.sh
-      - name: PowerShell
-        shell: pwsh
-        run: |
-          foreach ($f in Get-ChildItem packaging/windows/*.ps1) {
-            $errors = $null
-            [System.Management.Automation.Language.Parser]::ParseFile($f.FullName, [ref]$null, [ref]$errors) | Out-Null
-            if ($errors) { $errors | ForEach-Object { Write-Output "::error file=$($f.Name)::$_" }; exit 1 }
-            Write-Output "ok $($f.Name)"
-          }
-      - name: XML, desktop entry, AppStream, Flatpak manifest
-        run: |
-          xmllint --noout packaging/windows/*.wxs packaging/macos/*.plist* packaging/linux/*.xml*
-          # Windows Installer needs Icon ids ending in .ico or .exe, or shortcuts show a blank icon (#57).
-          if grep -oE '<Icon Id="[^"]*"' packaging/windows/pdfcraft.wxs | grep -vE '\.(ico|exe)"$'; then
-            echo "::error file=packaging/windows/pdfcraft.wxs::Icon Id must end in .ico or .exe"; exit 1
-          fi
-          desktop-file-validate packaging/linux/ai.storyteller.pdfcraft.desktop
-          sed -e 's/@VERSION@/0.0.0/' -e 's/@DATE@/2026-01-01/' packaging/linux/ai.storyteller.pdfcraft.metainfo.xml.in >"$RUNNER_TEMP/ai.storyteller.pdfcraft.metainfo.xml"
-          appstreamcli validate --no-net --explain "$RUNNER_TEMP/ai.storyteller.pdfcraft.metainfo.xml"
-          python3 - <<'EOF'
-          import yaml
-          src = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.pdfcraft.yml"))
-          bundle = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.pdfcraft.bundle.yml"))
-          for m in (src, bundle):
-              assert m["id"] == "ai.storyteller.pdfcraft" and m["command"] == "pdfcraft", m["id"]
-          for key in ("runtime", "runtime-version", "sdk", "finish-args"):
-              assert src[key] == bundle[key], f"Flatpak manifests disagree on {key}: {src[key]} vs {bundle[key]}"
-          print("Flatpak manifests ok")
-          EOF
+    # 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/packaging-lint.yml@main

.github/workflows/release.yml

@@ -1,12 +1,3 @@
-# Release pipeline: every push to `release` builds signed installers for every platform and
-# creates or updates the draft GitHub Release "PdfCraft v<version>". See docs/releasing.md.
-#
-# The jobs that sign (macOS, Windows) and the one that drafts the release run in the `release`
-# environment (restricted to the `release` branch), which holds the signing secrets. Every secret
-# is optional: missing ones produce unsigned artifacts and a warning, never a failed build. The
-# other jobs use no secrets and so no environment: a dispatch on another branch builds and checks
-# them (a dry run), while the signing jobs are refused there and the draft-release job, which
-# needs them, is skipped.
 name: Release
 
 on:
@@ -20,494 +11,33 @@ on:
         default: ""
 
 permissions:
-  contents: read
+  contents: write
 
 concurrency:
   group: release-${{ github.ref }}
-  # Never cancel a run mid-notarization or mid-upload; a newer push waits its turn.
   cancel-in-progress: false
 
-env:
-  CARGO_TERM_COLOR: always
-  CARGO_INCREMENTAL: 0
-  RUST_BACKTRACE: 1
-  PDFCRAFT_BUILD_SHA: ${{ github.sha }}
-  INPUT_VERSION: ${{ inputs.version }}
-
 jobs:
-  version:
-    name: version
-    runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.v.outputs.version }}
-      date: ${{ steps.v.outputs.date }}
-      prerelease: ${{ steps.v.outputs.prerelease }}
-    steps:
-      - uses: actions/checkout@v4
-      - id: v
-        name: Resolve version
-        run: |
-          . packaging/env.sh
-          v="${INPUT_VERSION#v}"
-          v="${v:-$VERSION}"
-          if ! printf '%s' "$v" | grep -Eq '^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$'; then
-            echo "::error::'$v' is not a version like 1.2.3 or 1.2.3-rc.1"
-            exit 1
-          fi
-          case "$v" in *-*) pre=true ;; *) pre=false ;; esac
-          {
-            echo "version=$v"
-            echo "date=$(date -u +%Y-%m-%d)"
-            echo "prerelease=$pre"
-          } >>"$GITHUB_OUTPUT"
-          echo "### PdfCraft v$v (\`${GITHUB_SHA::9}\`)" >>"$GITHUB_STEP_SUMMARY"
-
-  macos:
-    name: macOS universal
-    needs: version
-    runs-on: macos-15-xlarge  # M2 Pro larger runner; use only in release.yml (actions_macos_xl budget caps spend)
-    environment: release
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: aarch64-apple-darwin, x86_64-apple-darwin
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: release-macos-universal
-      - name: Apply version override
-        if: inputs.version != ''
-        run: cargo xtask version set "$PDFCRAFT_VERSION"
-      - name: Import signing certificate
-        env:
-          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
-          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
-          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
-        run: packaging/macos/import-cert.sh
-      - name: Build, sign, notarize
-        env:
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
-        run: packaging/macos/package.sh --arch universal
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-macos
-          path: dist/release/*
-          if-no-files-found: error
-      - name: Remove temporary keychain
-        if: always()
-        run: |
-          if [ -n "${MACOS_KEYCHAIN:-}" ]; then security delete-keychain "$MACOS_KEYCHAIN" || true; fi
-
-  windows:
-    name: Windows ${{ matrix.arch }}
-    needs: version
-    runs-on: windows-latest
-    environment: release
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { arch: x64, target: x86_64-pc-windows-msvc }
-          - { arch: x86, target: i686-pc-windows-msvc }
-          # Windows on ARM (#61): cross-compiled on the x64 runner, so signing and WiX run as above.
-          # .github/workflows/windows-arm64.yml installs and runs it on ARM64 hardware.
-          - { arch: arm64, target: aarch64-pc-windows-msvc }
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: ${{ matrix.target }}
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: release-windows-${{ matrix.arch }}
-      - name: Apply version override
-        if: inputs.version != ''
-        shell: bash
-        run: cargo xtask version set "$PDFCRAFT_VERSION"
-      - name: Install WiX
-        shell: pwsh
-        run: dotnet tool install --global wix --version 5.0.2
-      - name: Build, sign, package
-        shell: pwsh
-        env:
-          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 }}
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
-        run: ./packaging/windows/package.ps1 -Arch ${{ matrix.arch }}
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-windows-${{ matrix.arch }}
-          path: dist/release/*
-          if-no-files-found: error
-
-  linux:
-    name: Linux ${{ matrix.arch }}
-    needs: version
-    # The oldest GitHub-hosted image, so the binaries only need glibc >= 2.35 (Ubuntu 22.04+,
-    # Debian 12+, Fedora 36+, RHEL 10). See docs/releasing.md.
-    runs-on: ${{ matrix.runner }}
-    # No `environment: release`: this job signs nothing, so it gets no release secrets.
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { arch: x86_64, runner: ubuntu-22.04, deb: amd64 }
-          - { arch: aarch64, runner: ubuntu-22.04-arm, deb: arm64 }
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-      NFPM_VERSION: 2.47.0
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - name: Install build and packaging tools
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libxkbcommon-dev libwayland-dev libx11-dev libxrandr-dev libxi-dev libgl1-mesa-dev \
-            desktop-file-utils appstream python3-yaml zsync
-          curl -fsSL -o "$RUNNER_TEMP/nfpm.deb" \
-            "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_${{ matrix.deb }}.deb"
-          sudo dpkg -i "$RUNNER_TEMP/nfpm.deb"
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: release-linux-${{ matrix.arch }}
-      - name: Apply version override
-        if: inputs.version != ''
-        run: cargo xtask version set "$PDFCRAFT_VERSION"
-      - name: Build and package (AppImage, deb, rpm, tar.gz, CLI tar.gz)
-        env:
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
-        run: packaging/linux/package.sh
-      - name: Check the packages
-        run: |
-          dpkg-deb --info dist/release/*.deb
-          dpkg-deb --contents dist/release/*.deb | grep -E 'usr/bin/pdfcraft$|metainfo|applications'
-          # The OCR models (#103), where the installed app looks: <bin>/../share/pdfcraft/models.
-          dpkg-deb --contents dist/release/*.deb | grep -E 'usr/share/pdfcraft/models/.+\.rten$'
-          # Named exactly: dist/release also holds the CLI-only tar.gz, and `tar -tzf a b` reads b as a member.
-          tar -tzf "dist/release/pdfcraft-$PDFCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz" | grep -E '/share/pdfcraft/models/.+\.rten$'
-          ldd target/release/pdfcraft
-          # The CLI-only archive: the binary and its licences, and it runs.
-          cli="dist/release/pdfcraft-cli-$PDFCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz"
-          tar -tzf "$cli" | grep -E '/pdfcraft-cli$'
-          tar -tzf "$cli" | grep -E '/LICENSE-APACHE$'
-          mkdir -p "$RUNNER_TEMP/cli" && tar -xzf "$cli" -C "$RUNNER_TEMP/cli"
-          "$RUNNER_TEMP/cli/pdfcraft-cli-$PDFCRAFT_VERSION-linux-${{ matrix.arch }}/pdfcraft-cli" --version
-          python3 -c "import yaml; m = yaml.safe_load(open('packaging/linux/flatpak/ai.storyteller.pdfcraft.yml')); assert m['id'] == 'ai.storyteller.pdfcraft'"
-          for appimage in dist/release/*.AppImage; do
-            chmod +x "$appimage"
-            APPIMAGE_EXTRACT_AND_RUN=1 "$appimage" --version
-            # Update information is embedded, and the .zsync for delta updates sits beside it.
-            "$appimage" --appimage-updateinformation | grep -F 'gh-releases-zsync|'
-            test -s "$appimage.zsync"
-          done
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-linux-${{ matrix.arch }}
-          path: dist/release/*
-          if-no-files-found: error
-
-  linux-riscv64:
-    name: Linux riscv64
-    needs: version
-    # Cross-compiled on x86_64 (no hosted RISC-V runners) against the runner's own Ubuntu release
-    # from ports.ubuntu.com, so the binaries need that release's glibc (24.04: 2.39). 22.04's
-    # riscv64 ports lag its amd64 updates, which breaks the multiarch install. tar.gz only (the
-    # app tree and the CLI-only archive); the CLI is smoke-tested under QEMU.
-    runs-on: ubuntu-24.04
-    # No `environment: release`: this job signs nothing, so it gets no release secrets.
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: riscv64gc-unknown-linux-gnu
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: release-linux-riscv64
-      - name: Apply version override
-        if: inputs.version != ''
-        run: cargo xtask version set "$PDFCRAFT_VERSION"
-      - name: Install cross-compilation dependencies
-        run: |
-          . /etc/os-release
-          sudo dpkg --add-architecture riscv64
-          # Pin the existing (archive.ubuntu.com) sources to amd64; riscv64 comes from ports.
-          if [ -f /etc/apt/sources.list.d/ubuntu.sources ]; then
-            sudo sed -i '/^Types: deb/a Architectures: amd64' /etc/apt/sources.list.d/ubuntu.sources
-          fi
-          if [ -f /etc/apt/sources.list ]; then
-            sudo sed -i 's/^deb /deb [arch=amd64] /g' /etc/apt/sources.list
-            sudo sed -i 's/^deb-src /deb-src [arch=amd64] /g' /etc/apt/sources.list
-          fi
-          for suite in "$VERSION_CODENAME" "$VERSION_CODENAME-updates" "$VERSION_CODENAME-security"; do
-            echo "deb [arch=riscv64] http://ports.ubuntu.com/ubuntu-ports $suite main universe restricted multiverse"
-          done | sudo tee /etc/apt/sources.list.d/riscv64.list
-          sudo apt-get update
-          # The same -dev packages as the linux job, for riscv64; the C toolchain also builds
-          # aws-lc-sys and ring (signing, TLS).
-          sudo apt-get install -y --no-install-recommends \
-            gcc-riscv64-linux-gnu g++-riscv64-linux-gnu binutils-riscv64-linux-gnu libc6-dev-riscv64-cross \
-            libc6-dev:riscv64 qemu-user \
-            libxkbcommon-dev:riscv64 libwayland-dev:riscv64 libx11-dev:riscv64 libxrandr-dev:riscv64 \
-            libxi-dev:riscv64 libgl1-mesa-dev:riscv64
-      - name: Build and package (tar.gz, CLI tar.gz)
-        env:
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
-          CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER: riscv64-linux-gnu-gcc
-          CC_riscv64gc_unknown_linux_gnu: riscv64-linux-gnu-gcc
-          CXX_riscv64gc_unknown_linux_gnu: riscv64-linux-gnu-g++
-          AR_riscv64gc_unknown_linux_gnu: riscv64-linux-gnu-ar
-          PKG_CONFIG_SYSROOT_DIR: /
-          PKG_CONFIG_PATH: /usr/lib/riscv64-linux-gnu/pkgconfig:/usr/share/pkgconfig
-          PKG_CONFIG_ALLOW_CROSS: "1"
-          CROSS_ARCH: riscv64
-          CROSS_TARGET: riscv64gc-unknown-linux-gnu
-          CROSS_COMPILE: riscv64-linux-gnu-
-          EMULATOR: qemu-riscv64
-          QEMU_LD_PREFIX: /usr/riscv64-linux-gnu
-        run: packaging/linux/package.sh --formats "tar cli"
-      - name: Check the packages
-        run: |
-          tar -tzf "dist/release/pdfcraft-$PDFCRAFT_VERSION-linux-riscv64.tar.gz" | grep -E '/bin/pdfcraft$'
-          # The OCR models (#103), where the installed app looks: <bin>/../share/pdfcraft/models.
-          tar -tzf "dist/release/pdfcraft-$PDFCRAFT_VERSION-linux-riscv64.tar.gz" | grep -E '/share/pdfcraft/models/.+\.rten$'
-          cli="dist/release/pdfcraft-cli-$PDFCRAFT_VERSION-linux-riscv64.tar.gz"
-          tar -tzf "$cli" | grep -E '/pdfcraft-cli$'
-          tar -tzf "$cli" | grep -E '/LICENSE-APACHE$'
-          file target/riscv64gc-unknown-linux-gnu/release/pdfcraft | grep -F 'RISC-V'
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-linux-riscv64
-          path: dist/release/*.tar.gz
-          if-no-files-found: error
-
-  flatpak:
-    name: Flatpak ${{ matrix.arch }}
-    needs: [version, linux]
-    # Repackages the Linux job's tarball (the same binaries as the AppImage/deb/rpm); no Rust
-    # build here. 24.04 for a newer flatpak-builder (1.4) than 22.04 ships.
-    runs-on: ${{ matrix.runner }}
-    # No `environment: release`: this job signs nothing, so it gets no release secrets.
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { arch: x86_64, runner: ubuntu-24.04 }
-          - { arch: aarch64, runner: ubuntu-24.04-arm }
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-        with:
-          name: release-linux-${{ matrix.arch }}
-          path: dist/linux
-      - name: Install flatpak-builder
-        run: |
-          sudo apt-get update
-          # librsvg2-common: the SVG pixbuf loader. flatpak-builder runs the host's
-          # `appstreamcli compose`, which renders the scalable icon and fails without it.
-          sudo apt-get install -y --no-install-recommends flatpak flatpak-builder librsvg2-common
-          # Ubuntu 24.04's AppArmor blocks the unprivileged user namespaces bubblewrap needs.
-          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
-      - name: Build the Flatpak bundle
-        run: packaging/linux/flatpak-bundle.sh "dist/linux/pdfcraft-$PDFCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz"
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-flatpak-${{ matrix.arch }}
-          path: dist/release/*.flatpak
-          if-no-files-found: error
-
-  freebsd:
-    name: FreeBSD x86_64
-    needs: version
-    # GitHub has no FreeBSD runners: build in a FreeBSD VM (see .github/workflows/freebsd.yml).
-    runs-on: ubuntu-latest
-    timeout-minutes: 180
-    # No `environment: release`: this job signs nothing, so it gets no release secrets.
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-      VERSION_OVERRIDE: ${{ inputs.version }}
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - name: Build and package in a FreeBSD VM (tar.gz)
-        # vmactions/freebsd-vm v1.5.9, pinned by commit (it runs our build).
-        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc
-        with:
-          release: "14.3"
-          usesh: true
-          cpu: 4
-          mem: 12288
-          envs: "PDFCRAFT_VERSION PDFCRAFT_BUILD_DATE VERSION_OVERRIDE"
-          # The same packages as the FreeBSD CI workflow, plus bash for the packaging script.
-          prepare: |
-            pkg install -y bash git curl pkgconf cmake python3 libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
-          run: |
-            set -e
-            . "$HOME/.cargo/env"
-            git config --global --add safe.directory "$PWD"
-            export CRAFT_FONTS_DIR="$PWD/craft-fonts" CRAFT_FONTS_REQUIRED=1
-            if [ -n "$VERSION_OVERRIDE" ]; then cargo xtask version set "$PDFCRAFT_VERSION"; fi
-            packaging/freebsd/package.sh
-            # Only dist/ comes back out of the VM: copying the target dir back fails on large builds.
-            rm -rf target
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-freebsd-x86_64
-          path: dist/release/*
-          if-no-files-found: error
-
-  web:
-    name: Web (wasm)
-    needs: version
-    runs-on: ubuntu-latest
-    # No `environment: release`: this job signs nothing, so it gets no release secrets.
-    env:
-      PDFCRAFT_VERSION: ${{ needs.version.outputs.version }}
-      PDFCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
-      TRUNK_VERSION: 0.21.14
-    steps:
-      - uses: actions/checkout@v4
-      # The craft-fonts build input (Japanese fonts): every release embeds it. Bump deliberately.
-      - name: Check out craft-fonts
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-        with:
-          repository: storytold/craft-fonts
-          ref: 8dcdacd5153e64560d109541a47d806f26f048c0
-          path: craft-fonts
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: wasm32-unknown-unknown
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: release-web
-      - name: Install trunk
-        run: |
-          curl -fsSL "https://github.com/trunk-rs/trunk/releases/download/v${TRUNK_VERSION}/trunk-x86_64-unknown-linux-gnu.tar.gz" \
-            | tar -xz -C "$HOME/.cargo/bin" trunk
-          trunk --version
-      - name: Apply version override
-        if: inputs.version != ''
-        run: cargo xtask version set "$PDFCRAFT_VERSION"
-      - name: Build and zip
-        env:
-          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
-          CRAFT_FONTS_REQUIRED: "1"
-        run: packaging/web/package.sh
-      - uses: actions/upload-artifact@v4
-        with:
-          name: release-web
-          path: dist/release/*
-          if-no-files-found: error
-
   release:
-    name: Draft GitHub Release
-    # Needs the signing jobs, which only run on `release`: a branch dry run never drafts a release.
-    needs: [version, macos, windows, linux, linux-riscv64, flatpak, freebsd, web]
-    runs-on: ubuntu-latest
-    environment: release
-    permissions:
-      contents: write
-    env:
-      VERSION: ${{ needs.version.outputs.version }}
-      PRERELEASE: ${{ needs.version.outputs.prerelease }}
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      GH_REPO: ${{ github.repository }}
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          pattern: release-*
-          path: artifacts
-          merge-multiple: true
-      - name: Checksums
-        working-directory: artifacts
-        run: |
-          sha256sum -- * | tee SHA256SUMS.txt
-      - name: Create or update the draft release
-        working-directory: artifacts
-        run: |
-          tag="v$VERSION"
-          title="PdfCraft v$VERSION"
-          pre=()
-          if [ "$PRERELEASE" = true ]; then pre=(--prerelease); fi
-          if draft="$(gh release view "$tag" --json isDraft --jq .isDraft 2>/dev/null)"; then
-            if [ "$draft" != "true" ]; then
-              echo "::error::Release $tag is already published. Bump the version (cargo xtask version set) before pushing to release."
-              exit 1
-            fi
-            echo "Updating draft $tag: replacing its assets"
-            gh release view "$tag" --json assets --jq '.assets[].name' | while read -r asset; do
-              gh release delete-asset "$tag" "$asset" --yes
-            done
-            gh release edit "$tag" --draft --title "$title" --target "$GITHUB_SHA" --prerelease="$PRERELEASE"
-            gh release upload "$tag" --clobber -- *
-          else
-            echo "Creating draft $tag"
-            gh release create "$tag" --draft --title "$title" --target "$GITHUB_SHA" --generate-notes "${pre[@]}" -- *
-          fi
-          {
-            echo "Draft release **$title** at \`${GITHUB_SHA::9}\`:"
-            echo
-            sed 's/^/    /' SHA256SUMS.txt
-          } >>"$GITHUB_STEP_SUMMARY"
+    # 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/release.yml@main
+    with:
+      app-name: pdfcraft
+      app-title: PdfCraft
+      craft-fonts-ref: 3d9ab3a132ed0eff457e424226a435a901da30d3
+      version: ${{ inputs.version }}
+    secrets:
+      APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+      APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+      KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
+      APPLE_ID: ${{ secrets.APPLE_ID }}
+      APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+      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 }}

.github/workflows/windows-arm64.yml

@@ -25,134 +25,10 @@ concurrency:
 permissions:
   contents: read
 
-env:
-  CARGO_TERM_COLOR: always
-  CARGO_INCREMENTAL: 0
-  RUST_BACKTRACE: 1
-
 jobs:
-  package:
-    name: package (cross-compiled on x64)
-    runs-on: windows-latest
-    timeout-minutes: 90
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: aarch64-pc-windows-msvc
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: windows-arm64-package
-      - name: Install WiX
-        shell: pwsh
-        run: dotnet tool install --global wix --version 5.0.2
-      - name: Build and package (unsigned)
-        shell: pwsh
-        env:
-          DIST: ${{ github.workspace }}\dist\arm64
-        run: ./packaging/windows/package.ps1 -Arch arm64
-      - uses: actions/upload-artifact@v4
-        with:
-          name: pdfcraft-windows-arm64
-          path: dist/arm64/*
-          if-no-files-found: error
-          retention-days: 7
-
-  install:
-    name: install and run on ARM64
-    needs: package
-    runs-on: windows-11-arm
-    timeout-minutes: 30
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: pdfcraft-windows-arm64
-          path: dist
-      - name: Install the MSI, check it, run it, uninstall it, reinstall without the desktop shortcut
-        shell: pwsh
-        run: |
-          $ErrorActionPreference = 'Stop'
-          $msi = (Get-ChildItem dist/*.msi | Select-Object -First 1).FullName
-          # A command-line override must not put files in a user profile while registering
-          # their handlers machine-wide (#305). This runs on a disposable CI runner.
-          $p = Start-Process msiexec.exe -WindowStyle Hidden -ArgumentList '/i', "`"$msi`"", '/qn', 'ALLUSERS=2', 'MSIINSTALLPERUSER=1', '/l*v', 'per-user.log' -Wait -PassThru
-          if ($p.ExitCode -ne 1603) { Get-Content per-user.log -Tail 60; throw "per-user install should fail with 1603, got $($p.ExitCode)" }
-          if (-not (Select-String -Path per-user.log -SimpleMatch 'PdfCraft must be installed for all users.')) {
-            Get-Content per-user.log -Tail 60; throw 'per-user install did not fail on the scope guard'
-          }
-          $p = Start-Process msiexec.exe -ArgumentList '/i', "`"$msi`"", '/qn', '/l*v', 'install.log' -Wait -PassThru
-          if ($p.ExitCode -ne 0) { Get-Content install.log -Tail 60; throw "msiexec /i exited $($p.ExitCode)" }
-          $shortcuts = @(
-            (Join-Path ([Environment]::GetFolderPath('CommonPrograms')) 'PdfCraft.lnk'),
-            (Join-Path ([Environment]::GetFolderPath('CommonDesktopDirectory')) 'PdfCraft.lnk')
-          )
-          # Plain shortcuts to the program (#143), not advertised ones, so TargetPath is the exe.
-          $exePath = Join-Path $env:ProgramFiles 'PdfCraft\pdfcraft.exe'
-          $wsh = New-Object -ComObject WScript.Shell
-          foreach ($shortcut in $shortcuts) {
-            if (-not (Test-Path -LiteralPath $shortcut)) { throw "installer did not create $shortcut" }
-            $target = $wsh.CreateShortcut($shortcut).TargetPath
-            if ($target -ne $exePath) { throw "$shortcut points to '$target', not $exePath" }
-            Write-Output "ok $shortcut -> $target"
-          }
-          $dir = Join-Path $env:ProgramFiles 'PdfCraft'
-          foreach ($exe in 'pdfcraft.exe', 'pdfcraft-cli.exe') {
-            $path = Join-Path $dir $exe
-            if (-not (Test-Path $path)) { Get-ChildItem -Recurse $env:ProgramFiles -Filter $exe | Select-Object -First 3; throw "$exe not installed in $dir" }
-            $bytes = [System.IO.File]::ReadAllBytes($path)
-            $machine = [BitConverter]::ToUInt16($bytes, [BitConverter]::ToInt32($bytes, 0x3C) + 4)
-            if ($machine -ne 0xAA64) { throw "$exe is for machine 0x$('{0:X}' -f $machine), not ARM64" }
-            Write-Output "ok $path (ARM64)"
-          }
-          # The installed CLI runs natively: open, render and edit a small PDF through the engine.
-          $cli = Join-Path $dir 'pdfcraft-cli.exe'
-          & $cli tools | Out-Null
-          if ($LASTEXITCODE -ne 0) { throw "pdfcraft-cli tools exited $LASTEXITCODE" }
-          $body = 'BT /F1 24 Tf 20 150 Td (Hello ARM64) Tj ET'
-          $objs = @('<< /Type /Catalog /Pages 2 0 R >>', '<< /Type /Pages /Kids [3 0 R] /Count 1 >>',
-            '<< /Type /Page /Parent 2 0 R /MediaBox [0 0 300 200] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>',
-            "<< /Length $($body.Length) >>`nstream`n$body`nendstream", '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>')
-          $sb = [System.Text.StringBuilder]::new("%PDF-1.7`n"); $offsets = @()
-          for ($i = 0; $i -lt $objs.Count; $i++) { $offsets += $sb.Length; [void]$sb.Append("$($i + 1) 0 obj`n$($objs[$i])`nendobj`n") }
-          $xref = $sb.Length
-          [void]$sb.Append("xref`n0 $($objs.Count + 1)`n0000000000 65535 f `n")
-          foreach ($o in $offsets) { [void]$sb.Append(('{0:D10} 00000 n `n' -f $o)) }
-          [void]$sb.Append("trailer`n<< /Size $($objs.Count + 1) /Root 1 0 R >>`nstartxref`n$xref`n%%EOF`n")
-          New-Item -ItemType Directory -Force smoke | Out-Null
-          [System.IO.File]::WriteAllText("$PWD\smoke\hello.pdf", $sb.ToString(), [System.Text.Encoding]::ASCII)
-          $steps = '[{"tool":"doc_open","args":{"path":"hello.pdf"}},{"tool":"text_paragraphs","args":{"doc":1,"page":1}},{"tool":"text_edit","args":{"doc":1,"page":1,"paragraph":1,"text":"Edited on ARM64"}},{"tool":"page_render","args":{"doc":1,"page":1,"dpi":72},"out":"page.png"},{"tool":"doc_save","args":{"doc":1,"path":"out.pdf"}}]'
-          [System.IO.File]::WriteAllText("$PWD\smoke\steps.json", $steps)
-          $out = & $cli run --script smoke\steps.json --root smoke 2>&1 | Out-String
-          if ($LASTEXITCODE -ne 0) { Write-Output $out; throw "pdfcraft-cli run exited $LASTEXITCODE" }
-          if ($out -notmatch 'Hello ARM64') { Write-Output $out; throw 'text_paragraphs did not read the page' }
-          foreach ($f in 'smoke\page.png', 'smoke\out.pdf') { if (-not (Test-Path $f) -or (Get-Item $f).Length -eq 0) { Write-Output $out; throw "$f was not written" } }
-          Write-Output 'ok pdfcraft-cli: opened, read, edited, rendered and saved a PDF on ARM64'
-          $p = Start-Process msiexec.exe -ArgumentList '/x', "`"$msi`"", '/qn' -Wait -PassThru
-          if ($p.ExitCode -ne 0) { throw "msiexec /x exited $($p.ExitCode)" }
-          if (Test-Path (Join-Path $dir 'pdfcraft.exe')) { throw 'uninstall left pdfcraft.exe behind' }
-          foreach ($shortcut in $shortcuts) {
-            if (Test-Path -LiteralPath $shortcut) { throw "uninstall left $shortcut behind" }
-          }
-          Write-Output 'ok uninstalled'
-          # Unattended installs can opt out of the desktop shortcut (#143); the Start Menu one stays.
-          $p = Start-Process msiexec.exe -ArgumentList '/i', "`"$msi`"", '/qn', 'INSTALLDESKTOPSHORTCUT=0', '/l*v', 'install-nodesktop.log' -Wait -PassThru
-          if ($p.ExitCode -ne 0) { Get-Content install-nodesktop.log -Tail 60; throw "msiexec /i INSTALLDESKTOPSHORTCUT=0 exited $($p.ExitCode)" }
-          if (-not (Test-Path -LiteralPath $shortcuts[0])) { throw "INSTALLDESKTOPSHORTCUT=0 also skipped $($shortcuts[0])" }
-          if (Test-Path -LiteralPath $shortcuts[1]) { throw "INSTALLDESKTOPSHORTCUT=0 still created $($shortcuts[1])" }
-          $p = Start-Process msiexec.exe -ArgumentList '/x', "`"$msi`"", '/qn' -Wait -PassThru
-          if ($p.ExitCode -ne 0) { throw "msiexec /x exited $($p.ExitCode)" }
-          if (Test-Path -LiteralPath $shortcuts[0]) { throw "uninstall left $($shortcuts[0]) behind" }
-          Write-Output 'ok INSTALLDESKTOPSHORTCUT=0: Start Menu shortcut only'
-
-  test:
-    name: test (native ARM64)
-    runs-on: windows-11-arm
-    timeout-minutes: 120
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
-        with:
-          key: windows-arm64-test
-      - name: Test
-        run: cargo test --workspace --locked
+  windows-arm64:
+    # 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/windows-arm64.yml@main
+    with:
+      app-name: pdfcraft
+      app-dir: PdfCraft

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,10 +4,11 @@
 
 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 (264)
+## In this repository (270)
 
 | Asset | Title | Author | Licence | Source | Used for |
 |---|---|---|---|---|---|
+| `crates/ui-egui/src/i18n/el.tsv` | Greek interface translation catalog | Camthalion77 and contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft English UI labels | Greek UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/zh-hans.tsv` | Simplified Chinese 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 | Simplified Chinese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/zh-hant.tsv` | Traditional Chinese (Taiwan) 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 | Traditional Chinese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/cs.tsv` | Czech 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 | Czech UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
@@ -21,9 +22,12 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
 | `crates/ui-egui/src/i18n/ru.tsv` | Russian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Russian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/hu.tsv` | Hungarian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Hungarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/bg.tsv` | Bulgarian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Bulgarian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
+| `crates/ui-egui/src/i18n/kk.tsv` | Kazakh interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of the English UI labels into Kazakh, no proprietary localisation resources | Kazakh UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/ja.tsv` | Japanese interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Japanese UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `crates/ui-egui/src/i18n/uk.tsv` | Ukrainian interface translation catalog | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources | Ukrainian UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 | `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 |
@@ -199,7 +203,7 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
 | `assets/icons/x.svg` | Lucide icon "x" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/x.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
 | `assets/icons/zoom-in.svg` | Lucide icon "zoom-in" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/zoom-in.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
 | `assets/icons/zoom-out.svg` | Lucide icon "zoom-out" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/zoom-out.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
-| `assets/fonts/Inter-Regular.ttf` | Inter Regular | The Inter Project Authors (Rasmus Andersson) | OFL-1.1 | https://github.com/rsms/inter | UI font, embedded in the app; demo PDF labels |
+| `assets/fonts/Inter-Regular.ttf` | Inter Regular | The Inter Project Authors (Rasmus Andersson) | OFL-1.1 | https://github.com/rsms/inter | UI font, embedded in the app; demo PDF labels; slanted fallback glyphs in Fill & Sign typed signatures for characters Dancing Script lacks (Cyrillic, Greek), drawn as filled paths |
 | `assets/fonts/Inter-Medium.ttf` | Inter Medium | The Inter Project Authors (Rasmus Andersson) | OFL-1.1 | https://github.com/rsms/inter | UI font, embedded in the app; demo PDF labels |
 | `assets/fonts/Inter-SemiBold.ttf` | Inter SemiBold | The Inter Project Authors (Rasmus Andersson) | OFL-1.1 | https://github.com/rsms/inter | UI font, embedded in the app; demo PDF labels |
 | `assets/fonts/JetBrainsMono-Regular.ttf` | JetBrains Mono Regular | The JetBrains Mono Project Authors | OFL-1.1 | https://github.com/JetBrains/JetBrainsMono | UI monospace font; demo PDF code |
@@ -218,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. |
@@ -272,6 +276,8 @@ Every asset PdfCraft includes, bundles or uses to build its published material,
 | `packaging/macos/dmg/background.svg` | PdfCraft macOS DMG window background | @XusBadia | MIT OR Apache-2.0 | Original work for this repository, derived from the PdfCraft app icon (assets/app-icon/pdfcraft.svg, referenced via an SVG image element, not copied) | Finder window of the macOS DMG; rendered to background.tiff by packaging/macos/dmg/generate.py |
 | `packaging/macos/dmg/background.tiff` | PdfCraft macOS DMG window background (rendered) | @XusBadia | MIT OR Apache-2.0 | Rendered from packaging/macos/dmg/background.svg by packaging/macos/dmg/generate.py | 1x + 2x HiDPI 16-colour palette TIFF copied into the macOS DMG by packaging/macos/package.sh; includes the app icon and the free LittleCMS built-in sRGB profile |
 | `crates/sign/tests/data/x509-rsa-sha1.pdf` | One-page PDF with a legacy adbe.x509.rsa_sha1 signature by the RSA test key | PdfCraft contributors | MIT OR Apache-2.0 | Contributor-original: hand-written PDF objects; signature made with `openssl dgst -sha1 -sign` over its byte ranges (see crates/sign/tests/data/README.md) | Signature validation tests (crates/sign/tests/pdf.rs): the legacy adbe.x509.rsa_sha1 format |
+| `assets/icons/monitor.svg` | Lucide icon "monitor" | Lucide Contributors (portions Cole Bemis, Feather) | ISC | https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/monitor.svg) | UI icon, embedded via crates/ui-egui/src/icon_data.rs |
+| `crates/ui-egui/src/i18n/sl.tsv` | Slovene 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 | Slovene UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs |
 
 ## Compiled in through dependencies (6)
 

ATTRIBUTION.toml

@@ -1,3 +1,14 @@
+[[asset]]
+path = "crates/ui-egui/src/i18n/el.tsv"
+title = "Greek interface translation catalog"
+author = "Camthalion77 and contributors"
+source = "Contributor-original: clean-room translations of PdfCraft English UI labels"
+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 = "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`).
 #
@@ -19,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 = "b568edd80dfce809d1e8fbdad9f2c30e1fabc04d631a06dc154fd8e799ede3e0"
+sha256 = "d8ea23644d81476e3fd35c09780ab9b3ac8c9e28bed4e14e1cbc6493bb896d91"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/zh-hant.tsv"
@@ -30,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 = "cbaf398cd35b4667ceffe4f93df014289da9ea5711eb936f0315b6029bf93681"
+sha256 = "26dd0b0d697fd40db996fc102f3c7f2320bdeb6d6af38dbdde353bd5d940baad"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/cs.tsv"
@@ -41,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 = "8e38ce2add4bc43b972b83d78046fe0fe1c9d2eb85d0092a73867eea86ad2691"
+sha256 = "322b8cda21a2b8d157716182846619bd92bfb31263d1f8d13da7eaad365fbfd7"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/pt-br.tsv"
@@ -52,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 = "0c9fc284430ebf75561ec92783b63f5a9cc5d8eaa077e9b31c65d429eb40b69f"
+sha256 = "21bf9c73b482eb987ddaf839b4a4aa8f9938d5aa10428e6d39beea254a95a0c0"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/es.tsv"
@@ -63,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 = "9e15919fd57382776ffd2a09d0d2985ceeba526a3ef28fd58568c32aed43fc53"
+sha256 = "fef35ae1771edf2e044e72aebb958bb4827ded57234207f96b6cb7a250fedb22"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/fr.tsv"
@@ -74,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 = "df37b79a0c7e3d6ed171264103c90cd3fd48ee34e8a1fe9b1dd132947e709bd1"
+sha256 = "d723622298b10400e9a1ba697cbebd831f5e0f7e5bbe4545b97f61e64db7535f"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/de.tsv"
@@ -85,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 = "3923ec15c37e091793174b3546fce68bd5560cb7206a993d72f82ff878f66c07"
+sha256 = "686ab9658b7ef9dd7f3af05ce73f99f1ab2a75f8357bad6f7e987d40a8730df9"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/te.tsv"
@@ -96,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 = "cf915289e47679e6a778c7924863cbed25fcf00c1a8190379e1afeb10f411fbd"
+sha256 = "90b94038699aa74aa48ffbda3e90a2255b65d0dbf081e8ecf20c5804940fc129"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/it.tsv"
@@ -107,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 = "b7ec9e05598242f3b95a5edf4680f4faa437ea099297809a693452e7094d41c8"
+sha256 = "5aa6475df91a3e82010aee198c2e29bb80328505bbd0240f3828e36a5d6dfdf3"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/pl.tsv"
@@ -118,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 = "7052f5ee37d26e0173bc5fe48411c94e1b48e31e0fc8a9188fca2bec54f29e32"
+sha256 = "e6d306d9bf289fac2fe8fcfa6f9d0a51b650728e45669289d391be2031076692"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ru.tsv"
@@ -129,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 = "9db76f9f7f22a3f93b213f3931ba30036a2a60ac9c0b65c2fddc6c0a6dd4751c"
+sha256 = "277f4995a87297a2fcc473df1feebdbdf3378fa460a7f85eb1a0a151cee40a2b"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/hu.tsv"
@@ -140,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 = "846ade5369c59ce68cd3be1722645d82de21131125606f20aeec134b2ef1412e"
+sha256 = "01b32370cedce935b74925858a79ee691dc2a5560ba5eb758de2de1c243c528e"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/bg.tsv"
@@ -151,7 +162,18 @@ 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 = "2737dcd01e375b7d207c92473a4adc97eef23ebf1bbc15d69357f89a072a366f"
+sha256 = "f8ae97901c61dfdc0a844a23356173211bb052b3ff54128d7edc8097c535eee9"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/kk.tsv"
+title = "Kazakh interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of the English UI labels into Kazakh, no proprietary localisation resources"
+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 = "7107ba77577794395451dd85355a86ef3e033a7f240b72414b877b9b43adb19e"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ja.tsv"
@@ -162,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 = "0313526d0ba0c1b28f9d79bdae6c85279df65fd0beb9a53522e847316225339d"
+sha256 = "114b3d50531eb1682535c7a646e62914b0c9afaa5d5d1b9f66b94fd472e4e7b3"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/uk.tsv"
@@ -173,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 = "25527729c4119d520b5ae1d3201283d8baca17bcc14706a26adf82479a0499af"
+sha256 = "f56ec5f4cb7d1992041df0783f1cfd76c27d5d180c3f73c60b104e3fd02f600d"
 
 [[asset]]
 path = "crates/ui-egui/src/i18n/ar.tsv"
@@ -184,7 +206,29 @@ 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 = "7de1152206c40c411002bbb444533dfef3ee2e5418219a6e3059c2a53a4bf7d6"
+sha256 = "113fdf57e28fcff90d212fb468011bedebfb98ac100218d29b584f4de4c87912"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/tr.tsv"
+title = "Turkish interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Turkish UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+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"
@@ -2119,7 +2163,7 @@ source = "https://github.com/rsms/inter"
 licence = "OFL-1.1"
 licence_file = "assets/fonts/OFL-Inter.txt"
 kind = "font"
-usage = "UI font, embedded in the app; demo PDF labels"
+usage = "UI font, embedded in the app; demo PDF labels; slanted fallback glyphs in Fill & Sign typed signatures for characters Dancing Script lacks (Cyrillic, Greek), drawn as filled paths"
 sha256 = "40d692fce188e4471e2b3cba937be967878f631ad3ebbbdcd587687c7ebe0c82"
 
 [[asset]]
@@ -2321,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"
@@ -3285,3 +3330,25 @@ licence_file = "LICENSE-MIT"
 kind = "document"
 usage = "Signature validation tests (crates/sign/tests/pdf.rs): the legacy adbe.x509.rsa_sha1 format"
 sha256 = "b77bfb21166f4bd043597e45a1ea28b9d9f4ba6df0142b3a0fc8b7f8e0fc111b"
+
+[[asset]]
+path = "assets/icons/monitor.svg"
+title = "Lucide icon \"monitor\""
+author = "Lucide Contributors (portions Cole Bemis, Feather)"
+source = "https://github.com/lucide-icons/lucide (npm lucide-static 1.49.0, icons/monitor.svg)"
+licence = "ISC"
+licence_file = "assets/icons/LICENSE-lucide.txt"
+kind = "icon"
+usage = "UI icon, embedded via crates/ui-egui/src/icon_data.rs"
+sha256 = "d1a443233345724859de8e4fb48968ba91e885e12ddbd710701548bd91b39428"
+
+[[asset]]
+path = "crates/ui-egui/src/i18n/sl.tsv"
+title = "Slovene interface translation catalog"
+author = "PdfCraft contributors"
+source = "Contributor-original: clean-room translations of PdfCraft's English UI labels, no proprietary localisation resources"
+licence = "MIT OR Apache-2.0"
+licence_file = "LICENSE-MIT"
+kind = "translation"
+usage = "Slovene UI strings, compiled in by crates/ui-egui/src/i18n/mod.rs"
+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,44 +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-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"
@@ -87,6 +92,11 @@ debug = "line-tables-only"
 [profile.dev]
 opt-level = 1
 
+[profile.low-disk]
+inherits = "dev"
+debug = "line-tables-only"
+incremental = false
+
 [profile.release]
 lto = "thin"
 codegen-units = 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>
@@ -314,8 +316,25 @@ pdfcraft-cli ui --control ~/.pdfcraft-control.json key key=K modifiers='["comman
 pdfcraft-cli ui --control ~/.pdfcraft-control.json command id=comment.square   # pick a tool, then draw:
 pdfcraft-cli ui --control ~/.pdfcraft-control.json drag from='[400,300]' to='[600,420]'
 pdfcraft-cli ui --control ~/.pdfcraft-control.json screenshot --out window.png
+pdfcraft-cli ui --control ~/.pdfcraft-control.json resize width=1200 height=800
+pdfcraft-cli ui --control ~/.pdfcraft-control.json focus label="Read"
+pdfcraft-cli ui --control ~/.pdfcraft-control.json inspect focused=true
+pdfcraft-cli ui --control ~/.pdfcraft-control.json quit
 ```
 
+`ui.dock` arranges the `tools` and `inspector` panels; `canvas` is the protected document view.
+Each per-panel request requires a `panel` ID and an `operation`: `open`, `close`,
+`activate`, `float` with `rect: [x, y, width, height]`, or `move` with `target` and
+`zone: center|left|right|top|bottom`. For example,
+`{"operation":"float","panel":"tools","rect":[100,100,320,440]}` floats Tools.
+`ui.dock.reset` restores the default
+arrangement. The control channel accepts these methods directly; `ui.command` also accepts
+`{"id":"ui.dock","params":{...}}`. Saved preferences retain groups, active tabs, visibility
+and floating geometry. Invalid requests return an error without changing the document or layout.
+
+
+`resize` requests a native inner-window size in logical points (each dimension must be between 320 and 8192); the window manager may constrain it. `state` reports the observed `window.width`, `window.height` and `window.pixels_per_point`. `focus` accepts exactly one widget `id` or unique enabled, focusable `label`; subsequent `key` requests traverse or activate the actual widgets. `inspect` includes focusability and accepts a `focused` filter. `quit` takes no parameters: clean documents exit normally, while unsaved edits or typing open the existing Save/Don't save/Cancel prompt and return `quitting: false, needs_confirmation: true`. It never silently discards work. Window resizing and application quit are native-only.
+
 ---
 
 ## How it's built
@@ -352,9 +371,12 @@ 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
+cargo xtask models                                # fetch the OCR models Scan & OCR needs (release builds include them)
 cargo run --release -p pdfcraft -- some.pdf     # desktop app
 cargo xtask demo-pdf                              # build the showcase PDF used in these screenshots
 cargo xtask screenshots                           # regenerate every screenshot in this README
@@ -395,14 +417,14 @@ Logs, environment variables and other development notes are in [docs/development
 
 PdfCraft is young and moving fast. The aim is a workbench where you can view, organize, annotate, fill, sign and edit PDFs, at parity with Acrobat Pro.
 
-**Where it stands (October 2026), honestly:** PdfCraft is **alpha**. Most of Acrobat Pro's offline features exist in some form (57% of all tracked features, 94% of the must-haves). For everyday work (viewing, commenting, filling and signing forms, organizing pages) it is about 55% of the way to replacing Acrobat; against all of Acrobat Pro, about 49%; for someone who only needs the essentials, about 66%. Every everyday workflow can be completed, but converting and sharing is weak: password-protected files Acrobat can't open, no Office-to-PDF, and Word export that loses layout.
+**Where it stands (October 2026), honestly:** PdfCraft is **alpha**. Most of Acrobat Pro's offline features exist in some form (57% of all tracked features, 94% of the must-haves). For everyday work (viewing, commenting, filling and signing forms, organizing pages) it is about 55% of the way to replacing Acrobat; against all of Acrobat Pro, about 49%; for someone who only needs the essentials, about 66%. Every everyday workflow can be completed, but converting and sharing is weak: no Office-to-PDF, and Word export that loses layout.
 
 - **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 on Windows, 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:** encrypted files that Acrobat opens, the reported bugs and Windows printing, 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).
 
@@ -428,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
 
@@ -536,3 +562,14 @@ Forks and modified versions must remove them.
   <a href="https://getartcraft.com/"><img alt="ArtCraft" src="docs/brand/artcraft-mark.svg" width="28"></a><br>
   <sub>Made by the <a href="https://getartcraft.com/">ArtCraft</a> team and community.</sub>
 </p>
+
+Tools and Inspector panels can be dragged into tab groups, split beside the PDF, or floated within the app window. Read and full-screen modes keep their existing focused document view. Drag a panel header to a target edge or another header. Its context menu offers Float panel, Move to group, and Close panel. Existing panel toggles reopen panels at their saved location; Reset Panel Layout restores the app layout. Floating panels remain inside the current app window.
+
+Advanced `ui.dock` operations use the same validated transaction as pointer gestures:
+`moveFloating` updates `rect`, `resizeSplit` accepts a boolean child `path` and
+`size` (`{"Ratio":0.5}`, `{"FixedFirst":280}`, or `{"FixedSecond":280}`),
+`setStackOpen` takes `open`, and `resizeStack` takes a point `height` or null.
+A center `move` can include `before` (panel ID or null to append) for tab order.
+The equivalent `{"action": ...}` form accepts a serialized shared docking action;
+this is also the form emitted by the renderer. Protected-canvas and app-specific panel
+rules apply equally to both forms.

ROADMAP.md

@@ -2,7 +2,23 @@
 
 **Stage: alpha** · next: beta, ~26% (ready for real work 49% → 75%) and ~400–700 h away
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** minor (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-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:** 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
 comes next. Adobe's cloud services (Document Cloud, Acrobat Sign requests, shared review, the AI
@@ -40,17 +56,17 @@ and add a line to the [progress log](#progress-log); when a gap closes, remove i
 **Why alpha:** all six of Acrobat Pro's everyday workflows can be completed end to end on macOS
 (the [alpha gate](docs/roadmap.md#alpha-gate)), and users praise them (7.6k stars, ≈ 217k downloads
 of 0.4–0.5, switching reports such as #179). Two are only partial: editing (no CJK/RTL) and convert
-and share (password-protected files we write don't open in Acrobat or Reader, #774; no in-app
-Office→PDF; Word export loses layout, #773). Those, unmeasured quality against Acrobat, the borrowed
-`hayro` renderer, no printing on Windows (#756) and 245 open issues keep it far from beta.
+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,
+and 245 open issues keep it far from beta.
 
 ### Readiness by audience
 
 | Audience | Ready | Opus 5.5 agent-hours to ≈ 95% | Work that dominates |
 |---|---|---|---|
 | Full Acrobat Pro (ready for real work) | ≈ 49% | ≈ 780–1,400 h (≈ 300–550 h wall clock with 3–5 agents; 60–70% parallelizes) | Own renderer and fidelity harness, editing existing content, OCR and Office conversion, Preflight and PDF/A/X/UA, accessibility tagging, signatures for institutions |
-| Mainstream practitioner | ≈ 55% | ≈ 500–900 h (≈ 200–400 h wall clock; ≈ 60% parallelizes) | Rendering fidelity, editing existing text (CJK, RTL, subsets), conversion (Word layout, Excel, PowerPoint, Office→PDF), OCR languages, Windows printing, the bug backlog |
-| Essentials user | ≈ 66% | ≈ 180–330 h (≈ 90–180 h wall clock; ≈ 50% parallelizes) | Rendering fidelity on everyday files, Windows printing, launch and GPU stability, encrypted output Acrobat opens (#774), simple text fixes, Word export layout, Chinese UI glyphs |
+| Mainstream practitioner | ≈ 55% | ≈ 500–900 h (≈ 200–400 h wall clock; ≈ 60% parallelizes) | Rendering fidelity, editing existing text (CJK, RTL, subsets), conversion (Word layout, Excel, PowerPoint, Office→PDF), OCR languages, the bug backlog |
+| Essentials user | ≈ 66% | ≈ 180–330 h (≈ 90–180 h wall clock; ≈ 50% parallelizes) | Rendering fidelity on everyday files, launch and GPU stability, simple text fixes, Word export layout, Chinese UI glyphs |
 
 Hours are calibrated as in [Effort and calibration](docs/target-app-parity.md#effort-and-calibration) (≈ 1k kept lines per agent-hour for new features, 3–10× slower for hardening and fidelity). The audiences are nested subsets, so essentials ≤ mainstream ≤ full.
 
@@ -121,8 +137,8 @@ Ranked; detail and the full milestone table in [docs/roadmap.md](docs/roadmap.md
 
 | Rank | Milestone | Estimate (h) |
 |---|---|---|
-| 0 | Convert and share: encrypted output opens in Acrobat (#774), Create PDF from Office, Word export that keeps layout (#773) | 40–70 |
-| 1 | Backlog and platform: crash and wrong-result reports, Windows printing (#756), Chinese UI face (#826) | 65–120 |
+| 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, 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 |
@@ -133,8 +149,99 @@ 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.
+- **2026-10-11 (M4, #569):** Combine files takes images and text files as well as PDFs. PNG, JPEG, TIFF, GIF, BMP, JPEG 2000 and .txt files become PDFs as they are added (Add files…, drops, folder scans), so each is an ordinary row with its pages, thumbnails and page range; a file that can't be read (a damaged image or PDF, a type that can't be converted) stays in the list with why in its Warnings, and Combine asks before leaving such files out (Cancel changes nothing); password-protected files still have to be unlocked first. `doc_combine` accepts the same types, and a converted file's bookmark drops its extension. A PNG whose header claims more than 2 GiB of pixels is now refused before its buffer is allocated (the png crate's limits don't cover it), as TIFF already was. Office documents and HTML are still not converted. Overall estimate unchanged.
+- **2026-10-11 (M3, Windows renderer startup):** Renderer-creation GPU errors return through the existing scoped handler so Auto startup can use the existing OpenGL fallback. A real-device invalid/valid pipeline regression covers error propagation and device reuse; the independent Windows hostile-argument fixture reports unavailable symbolic-link privileges. The underlying x86 DX12 compiler error remains unresolved; see `docs/windows-renderer-startup.md`. Milestone and effort estimates unchanged.
+
+- **2026-10-11 (M6):** Existing simple field-font encodings and Differences are respected when generating appearances; an unencodable value uses a separate Helvetica appearance font without changing the source font. Synthetic reopen regressions cover punctuation, subset fallback and multiline text. Exact font metrics/layout and broader Unicode fallback remain incomplete. Estimates unchanged.
+
+- **2026-10-11 (M6):** Tab and Shift-Tab wrapping to the same field or another widget of that field refresh the newly opened editor from the accepted value before Save. Synthetic UI regressions cover both directions, same-frame Save, validation refusal and undo/redo. Estimates unchanged.
+
+- **2026-10-11 (M13):** CLI run and MCP reject missing, empty, repeated and option-valued --root arguments before any tool/script execution or MCP initialization. A single-hyphen directory name remains valid; synthetic CLI regressions preserve a would-be overwritten file. Estimates unchanged.
+
+- **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.
 
@@ -142,9 +249,13 @@ Newest first: the date, what moved, and the new overall estimate.
 - **2026-10-10 (M10, #645):** Export all images and Save image as keep transparency. A JPEG with a soft mask (the usual cut-out photo) was written as the bare JPEG, and soft masks of another size than the image, JPEG-compressed soft masks, stencil `/Mask` images and colour-key `/Mask` arrays were dropped, so cut-outs came out on solid white or black. These images are now PNG with the mask as alpha (soft masks scaled to the image, `/Matte` un-blended); JPEGs without transparency are still written byte for byte. A negative image size no longer overflows in Save image as. JPX/JBIG2/CCITT masks are still left out. Overall estimate unchanged (about 30–35%).
 - **2026-10-10 (M12, XFA rows and areas):** Dynamic XFA forms lay out a repeating subform inside a top-to-bottom container in positioned content (a table in an area) with all its instances, drawn and measured, instead of one; and areas no longer appear in data paths (`pdfcraft_xfa::data_path`), since they are not data scopes. Before, a form whose fields sit in an area read none of the values Adobe's viewers saved, wrote what was filled here under a new element named after the area, which Adobe's viewers would most likely not read, and a FormCalc total looping over the table's rows failed on the rows that were missing. Layout, the script tree, reading and writing the data and the engine's value and row operations share the one path rule. Synthetic tests cover the layout, the path rule and the whole round trip (rows, Adobe-written values, a FormCalc total over all rows, the written data, reopening). Still open for such forms: XFA script objects (`<variables><script>`), which aren't supported. Overall estimate unchanged (about 30–35%).
 
+- **2026-10-11 (M10, Windows printing follow-up to #847):** Windows print jobs print each sheet at 100% on the driver's paper closest to the sheet's size, landscape for wide sheets; they had been shrunk into .NET's default 1-inch margins (about 76% on Letter) and not rotated. Sheets are capped at about 64 megapixels so a poster-sized sheet can't exhaust memory. PowerShell runs without a console window, and the Print dialog lists printers and spools jobs off the UI thread (the desktop app's `printer_source`), so neither Ctrl+P nor a long job freezes the app. Kittest regression for the background printer list; the Windows rendering path is still checked only by the Windows CI job. Estimates unchanged.
+- **2026-10-10 (M3, System appearance completion, #446/#881):** The Linux portal introduced by #881 now uses the standard numeric appearance setting and event-driven updates, with idle-window wakeups for initial and changed results. When that setting states no preference it falls back to the GNOME schema's `color-scheme`, which XFCE's portal answers instead. Native windows retain inherited appearance and both egui style branches use the selected palette. Manual choices and the Light default remain; unknown System appearance resolves to Light. Controlled protocol and UI checks cover the remaining gaps; the supplied EndeavourOS/GNOME report has not been reproduced on that desktop. Estimates unchanged.
+
 - **2026-10-10 (M9, #179 follow-up):** A Windows store certificate that can't sign is no longer left out of the Sign dialog silently: `windows::list` names it with the reason and Windows error code (no private key, a P-521/Brainpool/Ed25519 key, a key CNG can't open), the picker shows it greyed and unselectable, and `sign_windows_ids` returns it under `unusable`. A key that needs a permission prompt to open is listed instead of skipped. Reported by a user whose CA-issued identity showed in Acrobat but not here; a plain .p12 import into the CNG and legacy Microsoft providers was verified to list, so the next report will carry the reason. Store test adds a key-less certificate; overall estimate unchanged (about 30–35%).
 - **2026-10-10 (M10.2, JPEG scanning follow-up to #729):** Skip marker fill bytes and keep reading JFIF, APP14 and ICC metadata after the frame header, stopping before scan data or at EOI. Invalid segment lengths return errors; damaged or mismatched ICC profiles retain #729's device-space fallback. Synthetic regression cases added but not run at the contributor's request. Estimates unchanged.
 - **2026-10-10 (M13, desktop action outputs):** Desktop Action Wizard keeps every result when input basenames repeat, or when the destination already has a result from an earlier run. It preserves the original filename and extension for a free name and adds numbered suffixes for occupied names; the bounded search returns an error rather than reusing an occupied path. A real-shell regression drives Start twice and reopens the three-page and one-page results, checking that the original inputs and earlier output remain intact. This covers the desktop writer separately from the CLI/MCP action_run repair in #877. Milestone and effort estimates unchanged.
+- **2026-10-10 (L Print, #756):** Windows prints. The Print dialog lists the system's printers and its default from `Win32_Printer` (through PowerShell's CIM; `wmic` is gone from Windows 11), and Print spools the print-ready PDF: the in-box Windows.Data.Pdf renders each sheet at the printer's own resolution and System.Drawing.Printing carries copies, collation, duplex and colour as the job's settings — both reached through `powershell`, so the Rust code touches no Win32 API and the machine needs no PDF reader. This closes #756 and the "printer not showing" duplicates #160, #244, #293, #465 and #644, using the CIM approach community-tested in #452; the tests render the job's sheets through the whole WinRT path on CI (dry run, no printer needed) and, where a printer can be added, catch a real job in its paused queue. Web printing is still missing; milestone and effort estimates are unchanged.
 
 - **2026-10-10 (M3, #740):** Column select, as in Acrobat: holding Alt (Option on macOS) when a drag starts selects only the text inside the rectangle, with the Select tool, the text markup tools and Redact; Edit ▸ Column select does it with a plain drag, for Linux desktops whose window manager takes Alt-drag (Xfce, Cinnamon, MATE, KDE Plasma 5 by default). Copy gives rows top to bottom with tab-separated cells (right to left in right-to-left rows, reading order for vertical text); `text_extract` takes the same rectangle as `rect`. The new label is in all 15 catalogs. Also repaired `parity/acrobat-features.toml`, which #650 had left unparseable (duplicate keys on `form.field-list`). Still missing: column selection across pages and ⇧-click extension. Estimates unchanged.
 - **2026-10-10 (progress docs, hours per audience):** Each readiness number gets its own hours to ≈ 95%: full ≈ 49% / 780–1,400 h, mainstream ≈ 55% / 500–900 h, essentials ≈ 66% / 180–330 h. The full number is now the standard's additive weighted sum over the dimensions (written weights), 47% → 49%: method aligned with the standard, no new evidence. Beta ≈ 26 points, ≈ 400–700 h.
@@ -169,11 +280,17 @@ Newest first: the date, what moved, and the new overall estimate.
 - **2026-10-09 (M2, JPX sample normalization):** JPEG 2000 rescaling uses bounded integer arithmetic for supported 1–32-bit samples, including the 32-bit boundary that previously shifted past the integer width. Zero-sized rows are refused before scaling. Small contributor-original codestreams exercise decoding and rendering; endpoint and standard-depth regressions cover the same helper. Overall estimate unchanged (about 30–35%).
 - **2026-10-09 (M14, #577):** The desktop GPU setup enables the selected adapter's supported 2D texture extent instead of egui-wgpu's fixed 8192-pixel extent. This removes the artificial surface ceiling behind a mixed-DPI Windows startup crash when opening Outlook PDF attachments. Synthetic regressions cover the observed 8600 × 3423 surface, downlevel adapters and preservation of other device limits. Hardware resolution limits still apply; milestone and overall effort estimates are unchanged.
 - **2026-10-09 (M14, #577 follow-up):** A window larger than the GPU's texture limit no longer closes PdfCraft. Vendored egui-wgpu 0.36.2 fits the window's surface within `max_texture_dimension_2d` and draws egui at the matching scale, on every path that sizes a surface (start-up restore, resize, maximise, DPI change, a recreated surface); upstream is emilk/egui#8361. Root cause of the Outlook-only trigger: winit creates the window on the launching app's monitor and converts the restored size at that monitor's scale. Unit tests cover the 8600 × 3423 case and edge sizes; a Windows Sandbox (WARP) run of a window one pixel over the limit panicked before and kept drawing after. Estimates unchanged.
-- **2026-10-09 (M14, #577 follow-up):** A window larger than the GPU's texture limit no longer closes PdfCraft. Vendored egui-wgpu 0.36.2 fits the window's surface within `max_texture_dimension_2d` and draws egui at the matching scale, on every path that sizes a surface (start-up restore, resize, maximise, DPI change, a recreated surface); upstream is emilk/egui#8361. Root cause of the Outlook-only trigger: winit creates the window on the launching app's monitor and converts the restored size at that monitor's scale. Unit tests cover the 8600 × 3423 case and edge sizes; a Windows Sandbox (WARP) run of a window one pixel over the limit panicked before and kept drawing after. Estimates unchanged.
 - **2026-10-09 (M14, #519):** A GPU that can't configure the window's surface at launch no longer panics, so PdfCraft's OpenGL retry runs. Vendored egui-wgpu configures a new window's surface inside wgpu error scopes (`winit::catch_errors`) and returns a failure as an error, so eframe returns `Error::Wgpu` and the existing OpenGL retry (#530) runs (a device lost during that configure still panics, on the first frame). Before, wgpu's default handler panicked: on a 2015 Intel GPU with no D3D12 driver wgpu picked the GL adapter over WARP and timed out in `Surface::configure` (`GpuWaitTimeout`). A real-device regression test (a wgpu validation error inside `catch_errors`) panicked with the scopes removed; in Windows Sandbox a forced configure failure panicked unpatched and retried with OpenGL patched (Sandbox has no OpenGL 2.0, so the OpenGL window itself was not shown there). Defaulting Windows to DX12 only (WARP instead of wgpu's GL backend) is left to the maintainers. Overall estimate unchanged (about 30–35%).
 - **2026-10-09 (M5, Fill & Sign flatten on save):** Preferences and `doc_save` can bake Fill & Sign text, marks and signatures into the page when saving. The option defaults off. Other comments and form fields stay, a second flatten does not reuse an XObject name already on the page, and a document that cannot be changed is left unwritten. Overall estimate unchanged (about 30–35%).
+- **2026-10-09 (M3.9, native control lifecycle):** The opt-in UI control channel can request bounded window sizes, report observed dimensions, focus accessible widgets and inspect actual keyboard focus. Graceful quit uses the existing unsaved-work prompt, including uncommitted typing; force/discard parameters are rejected. Tests cover resize validation, Tab/Shift-Tab traversal, keyboard activation, invalid focus targets and quit cancellation with retained edits. Focused buttons preserve document undo/redo shortcuts, while text editors keep their own undo history. No milestone percentage change.
+
+- **2026-10-09 (UI.5, shared tab interaction):** Document and Combine tabs use revision-pinned `craft-ui` interaction, with accessible tab roles, selected state, keyboard activation and a theme-colored focus outline. Document IDs keep tab identity stable through dirty-label changes and earlier-tab removal. Existing labels, painting, horizontal scrolling and close requests stay in the frontend. No milestone percentage change.
+
+- **2026-10-09 (UI.2, shared icon buttons):** The frontend uses revision-pinned `craft-ui` for its SVG catalog and square icon buttons. Existing assets, fallback cache keys, dark/light colors, tool labels and commands remain app-owned. Buttons gain a visible keyboard-focus outline; the layer checker keeps the shared dependency at L7. No milestone percentage change.
+
 - **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%).
@@ -303,10 +420,22 @@ Newest first: the date, what moved, and the new overall estimate.
   - Overall ≈ 3–4%.
 - **2026-09-30 (session 1):** planning complete; viewer vertical slice.
 
+- M13: common command, batch, inspection and bounded preview tools share the existing confined automation path. MCP tools carry complete hints and reject unknown top-level keys as invalid parameters.
+- **2026-10-10 (UI docking):** Tools and Inspector can be regrouped, split beside the PDF, or floated inside the app window. Existing toggles reopen panels at their saved locations; UI commands arrange/reset panels, and preferences retain their layout. Read/full-screen modes preserve the focused document view. No milestone percentage change.
+
 ## Revision history
 
 | 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 |
@@ -314,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/Cargo.toml

@@ -16,6 +16,7 @@ workspace = true
 pdfcraft-render = { workspace = true }
 serde_json = { workspace = true }
 pdfcraft-engine = { workspace = true }
+pdfcraft-audit = { workspace = true }
 pdfcraft-cos = { workspace = true }
 pdfcraft-automation = { workspace = true }
 base64 = "0.22"

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,10 +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\": {…}}, …]
@@ -85,8 +92,10 @@ fn main() -> ExitCode {
         Some("split") => split(&args[1..]),
         Some("check") => check(&args[1..]),
         Some("check-one") => check_one(&args[1..]),
+        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..]),
@@ -139,13 +148,36 @@ 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))?;
     Ok(())
 }
 
+/// 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}"))?;
+    let findings = pdfcraft_audit::audit_redactions(&doc).map_err(|e| format!("{path}: {e}"))?;
+    let items: Vec<serde_json::Value> = findings
+        .into_iter()
+        .map(|f| {
+            serde_json::json!({
+                "page": f.page + 1,
+                "kind": f.kind.id(),
+                "rect": f.rect,
+                "covered_text": f.covered_text,
+            })
+        })
+        .collect();
+    println!("{}", serde_json::json!({ "file": path, "findings": items, "count": items.len() }));
+    if items.is_empty() { Ok(()) } else { Err(format!("audit: {} faux redaction(s) found", items.len()).into()) }
+}
+
 fn flag<'a>(args: &'a [String], name: &str) -> Option<&'a str> {
     args.iter().position(|a| a == name).and_then(|i| args.get(i + 1)).map(String::as_str)
 }
@@ -156,15 +188,29 @@ struct OptionSpec {
     takes_value: bool,
 }
 
-/// Refuse a long option `command` doesn't take (a misspelling) before any file is read.
+/// Refuse unknown options and malformed confinement flags before any file is read.
 fn validate_options(command: &str, args: &[String], specs: &[OptionSpec]) -> Result<(), CliError> {
+    if specs.iter().any(|spec| spec.name == "--root") {
+        // `flag` searches every token, including another option's value. Match that lookup so
+        // a malformed confinement flag cannot be hidden there and fall back to no root.
+        let mut root_seen = false;
+        for (i, _) in args.iter().enumerate().filter(|(_, arg)| arg.as_str() == "--root") {
+            if root_seen {
+                return Err(format!("{command}: --root may only be supplied once").into());
+            }
+            root_seen = true;
+            if args.get(i + 1).is_none_or(|value| value.is_empty() || value.starts_with("--")) {
+                return Err(format!("{command}: --root needs a directory value").into());
+            }
+        }
+    }
     let mut i = 0;
     while let Some(arg) = args.get(i) {
         if let Some(name) = arg.strip_prefix("--") {
             let Some(spec) = specs.iter().find(|spec| spec.name == arg) else {
                 return Err(format!("{command}: unknown option --{name}").into());
             };
-            // A missing or malformed value is left to the command, which reports it in its own
+            // Other missing or malformed values are left to the command, which reports them in its own
             // terms (`text` and `extract` explain what a page value must be).
             i += if spec.takes_value { 2 } else { 1 };
         } else {
@@ -175,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] = &[
@@ -291,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);
@@ -388,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())?;
@@ -465,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());
     }
@@ -503,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 {
@@ -559,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/root_arguments.rs

@@ -0,0 +1,121 @@
+//! A malformed `--root` must never fall back to an unconfined automation session.
+
+use std::path::PathBuf;
+use std::process::Command;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+const BIN: &str = env!("CARGO_BIN_EXE_pdfcraft-cli");
+const CANARY: &[u8] = b"KEEP EXISTING DESTINATION\n";
+
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new() -> Self {
+        static NEXT: AtomicU64 = AtomicU64::new(0);
+        for _ in 0..128 {
+            let path = std::env::temp_dir().join(format!("pdfcraft-root-arguments-{}-{}", std::process::id(), NEXT.fetch_add(1, Ordering::Relaxed)));
+            match std::fs::create_dir(&path) {
+                Ok(()) => return Self(path),
+                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+                Err(error) => panic!("creating argument test directory: {error}"),
+            }
+        }
+        panic!("no unused argument test directory after 128 attempts");
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+#[test]
+fn malformed_root_fails_before_a_script_can_overwrite_a_file() {
+    let dir = TestDir::new();
+    let destination = dir.0.join("existing.pdf");
+    let script = dir.0.join("steps.json");
+    let steps = serde_json::json!([
+        { "tool": "doc_create", "args": { "from": "blank", "width": 100, "height": 100 } },
+        { "tool": "doc_save", "args": { "doc": 1, "path": destination } },
+    ]);
+    std::fs::write(&script, steps.to_string()).unwrap();
+    std::fs::write(&destination, CANARY).unwrap();
+
+    for (flags, diagnostic) in [
+        (vec!["--root"], "--root needs a directory value"),
+        (vec!["--root", ""], "--root needs a directory value"),
+        (vec!["--root", "--out", "escaped.png"], "--root needs a directory value"),
+        (vec!["--out", "--root"], "--root needs a directory value"),
+        (vec!["--root", ".", "--root"], "--root may only be supplied once"),
+        (vec!["--root", ".", "--root", "."], "--root may only be supplied once"),
+        (vec!["--root", ".", "--out", "--root"], "--root may only be supplied once"),
+    ] {
+        // Both a valid script and a missing one: argument validation precedes script I/O.
+        for script_name in ["steps.json", "missing.json"] {
+            let out = Command::new(BIN).current_dir(&dir.0).args(["run", "--script", script_name]).args(&flags).output().unwrap();
+            assert_eq!(out.status.code(), Some(1), "{script_name} {flags:?} unexpectedly succeeded");
+            assert_eq!(String::from_utf8(out.stderr).unwrap().trim(), format!("pdfcraft-cli: run: {diagnostic}"));
+            assert!(out.stdout.is_empty(), "a refused command must not execute or report tool results");
+            assert_eq!(std::fs::read(&destination).unwrap(), CANARY);
+            assert!(!dir.0.join("escaped.png").exists());
+        }
+    }
+    assert_eq!(std::fs::read_dir(&dir.0).unwrap().count(), 2);
+}
+
+#[test]
+fn malformed_root_fails_before_direct_tool_argument_validation() {
+    let out = Command::new(BIN).args(["run", "doc_open", "not-key-value", "--root"]).output().unwrap();
+    assert_eq!(out.status.code(), Some(1));
+    assert_eq!(String::from_utf8(out.stderr).unwrap().trim(), "pdfcraft-cli: run: --root needs a directory value");
+    assert!(out.stdout.is_empty());
+}
+
+#[test]
+fn a_directory_name_starting_with_a_single_hyphen_remains_valid() {
+    let dir = TestDir::new();
+    std::fs::create_dir(dir.0.join("-documents")).unwrap();
+    let out = Command::new(BIN)
+        .current_dir(&dir.0)
+        .args(["run", "doc_create", "from=blank", "width=100", "height=100", "--root", "-documents"])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
+    assert!(serde_json::from_slice::<serde_json::Value>(&out.stdout).is_ok());
+}
+
+#[cfg(feature = "mcp")]
+#[test]
+fn malformed_root_never_starts_or_initializes_an_mcp_server() {
+    use std::io::Write as _;
+    use std::process::Stdio;
+
+    let dir = TestDir::new();
+    // Even if a directory matches the next option's name, it is not a root operand.
+    std::fs::create_dir(dir.0.join("--compact")).unwrap();
+    for (flags, diagnostic) in [
+        (vec!["--root"], "--root needs a directory value"),
+        (vec!["--root", ""], "--root needs a directory value"),
+        (vec!["--root", "--compact"], "--root needs a directory value"),
+        (vec!["--compact", "--root"], "--root needs a directory value"),
+        (vec!["--root", ".", "--root"], "--root may only be supplied once"),
+        (vec!["--root", ".", "--root", "./--compact"], "--root may only be supplied once"),
+    ] {
+        let mut child = Command::new(BIN)
+            .current_dir(&dir.0)
+            .arg("mcp")
+            .args(&flags)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+        // Early rejection may close stdin before this write; that is the intended behavior.
+        let _ = child.stdin.take().unwrap().write_all(b"{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{}}\n");
+        let out = child.wait_with_output().unwrap();
+        assert_eq!(out.status.code(), Some(1), "{flags:?} unexpectedly started the server");
+        assert_eq!(String::from_utf8(out.stderr).unwrap().trim(), format!("pdfcraft-cli: mcp: {diagnostic}"));
+        assert!(out.stdout.is_empty(), "a refused server must not answer initialize");
+    }
+}

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"] }
@@ -28,6 +30,12 @@ log = { workspace = true }
 # behind a safe API. Same version as PhotoCraft. Pinned exactly: review the diff before bumping.
 fmv-macos-events = "=0.1.0"
 
+[target.'cfg(target_os = "linux")'.dependencies]
+# Asks the Wayland compositor which GPU it draws with (linux-dmabuf feedback), so the window is
+# drawn on that one (src/compositor_gpu.rs). Both are already in the tree through winit.
+wayland-client = "0.31"
+wayland-protocols = { version = "0.32", features = ["client"] }
+
 [dev-dependencies]
 # Waits for wgpu's adapter, device and error-scope futures in tests (already in the tree through wgpu).
 pollster = "1.0"
@@ -36,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/compositor_gpu.rs

@@ -0,0 +1,177 @@
+//! The GPU the Wayland compositor draws with.
+//!
+//! A window drawn on another GPU reaches the compositor as that GPU's buffers, and the compositor
+//! may not show them: it can refuse them and end the window's connection (#96), or take them and
+//! show nothing, with no error on either side. The second happened on a hybrid laptop whose
+//! Hyprland runs on the NVIDIA GPU (`AQ_DRM_DEVICES`) while the built-in panel hangs off the Intel
+//! one: the panel rule picked Intel and the window stayed empty. Which GPU drives a display is a
+//! guess at the compositor's GPU; the compositor states it, as the `main_device` of its
+//! linux-dmabuf feedback (protocol version 4): the device it imports client buffers on.
+
+#[cfg(target_os = "linux")]
+use wayland_client::globals::{GlobalListContents, registry_queue_init};
+#[cfg(target_os = "linux")]
+use wayland_client::protocol::wl_registry::{self, WlRegistry};
+#[cfg(target_os = "linux")]
+use wayland_client::{Connection, Dispatch, QueueHandle};
+#[cfg(target_os = "linux")]
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_feedback_v1::{self, ZwpLinuxDmabufFeedbackV1};
+#[cfg(target_os = "linux")]
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_v1::{self, ZwpLinuxDmabufV1};
+
+/// PCI `(vendor, device)` ids of the GPU the Wayland compositor draws with. `None` outside a
+/// Wayland session, when the compositor doesn't say (linux-dmabuf older than version 4), when its
+/// device isn't a PCI GPU, and on other systems.
+#[cfg(target_os = "linux")]
+pub(crate) fn compositor_gpu() -> Option<(u32, u32)> {
+    let device = match main_device() {
+        Ok(device) => device,
+        Err(why) => {
+            log::debug!("the compositor's GPU is unknown: {why}");
+            return None;
+        }
+    };
+    let pci = pci_ids(std::path::Path::new("/sys/dev/char"), device);
+    match pci {
+        Some((vendor, id)) => log::info!("the compositor draws with {vendor:04x}:{id:04x}"),
+        None => log::debug!("the compositor's device {:?} has no PCI ids", major_minor(device)),
+    }
+    pci
+}
+
+#[cfg(not(target_os = "linux"))]
+pub(crate) fn compositor_gpu() -> Option<(u32, u32)> {
+    None
+}
+
+/// The `main_device` of the compositor's default linux-dmabuf feedback, asked on a connection of
+/// its own that is closed again before the window opens.
+#[cfg(target_os = "linux")]
+fn main_device() -> Result<u64, String> {
+    let conn = Connection::connect_to_env().map_err(|e| format!("no Wayland compositor: {e}"))?;
+    let (globals, mut queue) = registry_queue_init::<Feedback>(&conn).map_err(|e| e.to_string())?;
+    let qh = queue.handle();
+    // Version 4 brought the feedback; older compositors only list formats.
+    let dmabuf: ZwpLinuxDmabufV1 = globals.bind(&qh, 4..=4, ()).map_err(|e| format!("linux-dmabuf version 4: {e}"))?;
+    let _feedback = dmabuf.get_default_feedback(&qh, ());
+    let mut state = Feedback::default();
+    // The compositor sends the whole feedback, ending with `done`, in reply; the bound only keeps
+    // a compositor that never ends it from holding up the start.
+    for _ in 0..4 {
+        if state.done {
+            break;
+        }
+        queue.roundtrip(&mut state).map_err(|e| e.to_string())?;
+    }
+    // Dropping the connection releases the objects.
+    let device = state.main_device.ok_or("the compositor named no main device")?;
+    // A `dev_t`, in this machine's byte order.
+    let device: [u8; 8] = device.try_into().map_err(|d: Vec<u8>| format!("a {}-byte device number", d.len()))?;
+    Ok(u64::from_ne_bytes(device))
+}
+
+/// What [`main_device`] collects from the feedback events.
+#[cfg(target_os = "linux")]
+#[derive(Default)]
+struct Feedback {
+    main_device: Option<Vec<u8>>,
+    done: bool,
+}
+
+#[cfg(target_os = "linux")]
+impl Dispatch<WlRegistry, GlobalListContents> for Feedback {
+    fn event(_: &mut Self, _: &WlRegistry, _: wl_registry::Event, _: &GlobalListContents, _: &Connection, _: &QueueHandle<Self>) {}
+}
+
+#[cfg(target_os = "linux")]
+impl Dispatch<ZwpLinuxDmabufV1, ()> for Feedback {
+    // Version 4 sends no format or modifier events: the feedback replaces them.
+    fn event(_: &mut Self, _: &ZwpLinuxDmabufV1, _: zwp_linux_dmabuf_v1::Event, _: &(), _: &Connection, _: &QueueHandle<Self>) {}
+}
+
+#[cfg(target_os = "linux")]
+impl Dispatch<ZwpLinuxDmabufFeedbackV1, ()> for Feedback {
+    fn event(
+        state: &mut Self,
+        _: &ZwpLinuxDmabufFeedbackV1,
+        event: zwp_linux_dmabuf_feedback_v1::Event,
+        _: &(),
+        _: &Connection,
+        _: &QueueHandle<Self>,
+    ) {
+        match event {
+            zwp_linux_dmabuf_feedback_v1::Event::MainDevice { device } => state.main_device = Some(device),
+            zwp_linux_dmabuf_feedback_v1::Event::Done => state.done = true,
+            _ => {}
+        }
+    }
+}
+
+/// The major and minor numbers of a Linux `dev_t`, as glibc's and musl's `major()` and `minor()`
+/// split it.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+fn major_minor(device: u64) -> (u64, u64) {
+    let major = ((device & 0x0000_0000_000f_ff00) >> 8) | ((device & 0xffff_f000_0000_0000) >> 32);
+    let minor = (device & 0x0000_0000_0000_00ff) | ((device & 0x0000_0fff_fff0_0000) >> 12);
+    (major, minor)
+}
+
+/// The PCI ids of the GPU behind DRM device `device` (its `cardN` or `renderDN` node), from
+/// `<sys_dev_char>/MAJOR:MINOR/device/{vendor,device}`.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
+fn pci_ids(sys_dev_char: &std::path::Path, device: u64) -> Option<(u32, u32)> {
+    let read_hex = |p: std::path::PathBuf| -> Option<u32> {
+        let s = std::fs::read_to_string(p).ok()?;
+        u32::from_str_radix(s.trim().trim_start_matches("0x"), 16).ok()
+    };
+    let (major, minor) = major_minor(device);
+    let gpu = sys_dev_char.join(format!("{major}:{minor}")).join("device");
+    Some((read_hex(gpu.join("vendor"))?, read_hex(gpu.join("device"))?))
+}
+
+#[cfg(test)]
+mod tests {
+    /// glibc's `makedev()`.
+    fn makedev(major: u64, minor: u64) -> u64 {
+        ((major & 0x0000_0fff) << 8) | ((major & 0xffff_f000) << 32) | (minor & 0x0000_00ff) | ((minor & 0xffff_ff00) << 12)
+    }
+
+    #[test]
+    fn device_numbers_split_into_major_and_minor() {
+        // DRM nodes: card1 is 226:1, renderD128 is 226:128.
+        assert_eq!(super::major_minor(0xe201), (226, 1));
+        assert_eq!(super::major_minor(0xe280), (226, 128));
+        for (major, minor) in [(0, 0), (226, 129), (511, 1_048_575), (0xfff, 0xff), (0x1000, 0x100), (0xffff_ffff, 0xffff_ffff)] {
+            assert_eq!(super::major_minor(makedev(major, minor)), (major, minor));
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn the_gpu_behind_a_device_number_comes_from_sysfs() -> std::io::Result<()> {
+        let dir = std::env::temp_dir().join(format!("pdfcraft-dev-char-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        // /sys/dev/char/226:128 links to the render node, whose `device` is the PCI GPU.
+        std::fs::create_dir_all(dir.join("226:128/device"))?;
+        std::fs::write(dir.join("226:128/device/vendor"), "0x10de\n")?;
+        std::fs::write(dir.join("226:128/device/device"), "0x25ac\n")?;
+        // A device that isn't a PCI GPU (a virtual one) has no ids.
+        std::fs::create_dir_all(dir.join("226:0/device"))?;
+        let render = super::pci_ids(&dir, makedev(226, 128));
+        let virtual_gpu = super::pci_ids(&dir, makedev(226, 0));
+        let missing = super::pci_ids(&dir, makedev(226, 1));
+        std::fs::remove_dir_all(&dir)?;
+        assert_eq!(render, Some((0x10de, 0x25ac)));
+        assert_eq!(virtual_gpu, None);
+        assert_eq!(missing, None);
+        Ok(())
+    }
+
+    #[test]
+    fn the_compositor_names_a_pci_gpu_or_nothing() {
+        // Whatever this session has: no compositor (CI), one that doesn't say, or a PCI GPU.
+        if let Some((vendor, _)) = super::compositor_gpu() {
+            assert_ne!(vendor, 0);
+        }
+    }
+}

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

@@ -4,10 +4,10 @@
 //! `--create-images [images…]` stages the images in one PDF and asks for the page DPI.
 //!
 //! View options (applied after the files open; also the seed of the UI control channel):
-//! `--page N  --zoom 150  --layout continuous|two-up|single  --panel comments|bookmarks|pages|fields|layers|attachments|none
+//! `--page N  --zoom 150  --layout single|continuous|two-up|two-page  --continuous on|off  --panel comments|bookmarks|pages|fields|layers|attachments|none
 //!  --theme light|dark|system  --language auto|<code>  --mode all|read|edit|convert|sign  --tool <catalogue id>  --left open|closed
 //!  --organize on  --fields on  --dialog properties|shortcuts|about  --palette <query>  --home on
-//!  --cover on|off  --default-layout continuous|two-up|single  --default-zoom fit-width|fit-page|<percent>
+//!  --cover on|off  --default-layout single|continuous|two-up|two-page  --default-continuous on|off  --default-zoom fit-width|fit-page|<percent>
 //!  --combine-view grid|list  --combine-zoom 60..200`
 //!
 //! `--new-window` opens a window of its own. Without it, on Windows, a launch that only names files
@@ -31,7 +31,12 @@ 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;
 mod updates;
@@ -122,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();
@@ -151,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(),
@@ -164,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}"),
         }
@@ -186,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")]
@@ -196,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),
@@ -214,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,
@@ -254,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])
@@ -270,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() };
@@ -287,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>(
@@ -295,16 +338,30 @@ 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();
+        // First start (or settings from before Units existed): the region's unit.
+        app.units = pdfcraft_ui_egui::units::Unit::system();
+        #[cfg(target_os = "linux")]
+        app.enable_desktop_theme();
+        // The system's reopen-windows choice (macOS) starts the preference; a saved choice replaces it.
+        app.reopen_last_session = reopen::system_default();
         if let Some(json) = cc.storage.and_then(|s| s.get_string("pdfcraft").or_else(|| s.get_string(LEGACY_STORAGE_KEY))) {
             app.restore(&json);
         }
         app.integrated_titlebar = integrated;
+        app.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"));
         #[cfg(target_os = "macos")]
         {
@@ -457,12 +514,21 @@ fn write_control_file(path: &str, port: u16, token: &str) -> std::io::Result<()>
 ///   desktop with a monitor on each GPU, issue #445) the discrete one wins, as the integrated one
 ///   may fail to present there. Where the system doesn't say which GPU drives a display (macOS,
 ///   containers, remote sessions) the power preference alone decides.
+/// - Under Wayland, the GPU the compositor draws with comes before all of that: the compositor
+///   says which one it is ([`compositor_gpu::compositor_gpu`]), and frames from another GPU may
+///   never reach the screen, even from the GPU behind the built-in panel when the compositor runs
+///   on the discrete one.
 /// - On Windows, use Direct3D 12, falling back to OpenGL, and never load Vulkan drivers unless
 ///   `WGPU_BACKEND` asks for them. Creating a Vulkan instance loads every installed Vulkan driver
 ///   into the process, and a faulty one (an Intel driver in issue #37) crashed PdfCraft before
 ///   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,
@@ -476,7 +542,8 @@ fn configure_gpu(native: &mut eframe::NativeOptions) {
     if std::env::var_os("WGPU_POWER_PREF").is_none() {
         setup.power_preference = eframe::wgpu::PowerPreference::LowPower;
         let displays = display_gpus();
-        if !displays.is_empty() {
+        let compositor = compositor_gpu::compositor_gpu();
+        if !displays.is_empty() || compositor.is_some() {
             setup.native_adapter_selector = Some(std::sync::Arc::new(move |adapters, surface| {
                 let usable: Vec<&eframe::wgpu::Adapter> = adapters.iter().filter(|a| surface.is_none_or(|s| a.is_surface_supported(s))).collect();
                 let infos: Vec<(u32, u32, eframe::wgpu::DeviceType)> = usable
@@ -486,7 +553,7 @@ fn configure_gpu(native: &mut eframe::NativeOptions) {
                         (info.vendor, info.device, info.device_type)
                     })
                     .collect();
-                let picked = pick_adapter(&infos, &displays).and_then(|i| usable.get(i)).map(|a| (*a).clone());
+                let picked = pick_adapter(&infos, &displays, compositor).and_then(|i| usable.get(i)).map(|a| (*a).clone());
                 match &picked {
                     // Which GPU draws is the first question when a window stays black (#8, #378, #445).
                     Some(a) => {
@@ -619,12 +686,12 @@ fn linux_display_gpus(drm: &std::path::Path) -> Vec<DisplayGpu> {
     gpus
 }
 
-/// Index of the adapter to draw with: one that drives a display (by PCI ids) first. Among several
-/// of those, the one driving the primary display (a hybrid laptop's panel, #8; the primary display
-/// on Windows, #378), or else, with no primary display known (a Linux desktop with a monitor on
-/// each GPU, #445), the discrete one. Otherwise the most frugal kind: integrated, discrete, other,
-/// virtual, software.
-fn pick_adapter(adapters: &[(u32, u32, eframe::wgpu::DeviceType)], displays: &[DisplayGpu]) -> Option<usize> {
+/// Index of the adapter to draw with: the GPU the Wayland compositor draws with (`compositor`, by
+/// PCI ids) first, then one that drives a display. Among several of those, the one driving the
+/// primary display (a hybrid laptop's panel, #8; the primary display on Windows, #378), or else,
+/// with no primary display known (a Linux desktop with a monitor on each GPU, #445), the discrete
+/// one. Otherwise the most frugal kind: integrated, discrete, other, virtual, software.
+fn pick_adapter(adapters: &[(u32, u32, eframe::wgpu::DeviceType)], displays: &[DisplayGpu], compositor: Option<(u32, u32)>) -> Option<usize> {
     use eframe::wgpu::DeviceType;
     let display = |pci: (u32, u32)| displays.iter().find(|g| g.pci == pci);
     let multi_gpu_desktop = displays.len() > 1 && !displays.iter().any(|g| g.primary);
@@ -645,7 +712,7 @@ fn pick_adapter(adapters: &[(u32, u32, eframe::wgpu::DeviceType)], displays: &[D
                 DeviceType::VirtualGpu => 4,
                 DeviceType::Cpu => 5,
             };
-            (!drives_display, !drives_primary, rank)
+            (compositor != Some((*vendor, *device)), !drives_display, !drives_primary, rank)
         })
         .map(|(i, _)| i)
 }
@@ -658,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()));
@@ -692,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");
@@ -717,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]
@@ -746,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:?}");
@@ -864,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")
         };
@@ -927,6 +1037,37 @@ mod tests {
         }
     }
 
+    #[test]
+    fn pipeline_creation_error_is_returned_and_device_remains_usable() {
+        use eframe::{egui_wgpu, 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() };
+        let Ok(adapter) = pollster::block_on(instance.request_adapter(&options)) else {
+            assert!(std::env::var_os("PDFCRAFT_TEST_REQUIRE_GPU").is_none(), "a GPU adapter is required for this run");
+            eprintln!("skipping pipeline regression: no GPU adapter");
+            return;
+        };
+        let (device, queue) = pollster::block_on(adapter.request_device(&(setup.device_descriptor)(&adapter)))
+            .expect("the selected adapter must provide a test device");
+        native.wgpu_options.wgpu_setup =
+            egui_wgpu::WgpuSetup::Existing(egui_wgpu::WgpuSetupExisting { instance: instance.clone(), adapter, device, queue });
+        // Three samples is invalid on every backend, so this reproduces a pipeline error
+        // without depending on a particular driver. The unpatched constructor panics.
+        for samples in [3, 1, 3, 1] {
+            let options = egui_wgpu::RendererOptions { msaa_samples: samples, ..Default::default() };
+            let result = pollster::block_on(egui_wgpu::RenderState::create(&native.wgpu_options, &instance, None, options));
+            if samples == 3 {
+                let error = result.err().expect("invalid pipeline must return an error");
+                assert!(error.to_string().contains("egui_pipeline"), "{error}");
+            } else {
+                assert!(result.is_ok(), "the device must remain usable: {:?}", result.err());
+            }
+        }
+    }
+
     #[test]
     fn winit_carries_the_windows_11_monitor_scale_fix() {
         // Issue #324: winit 0.30.13 as released nudges a window dragged onto a monitor with another
@@ -966,17 +1107,17 @@ mod tests {
     #[test]
     fn pick_adapter_prefers_the_gpu_driving_the_monitors() {
         // A desktop whose monitors are all on the discrete GPU: the integrated one shows black.
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA)]), Some(0));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA)], None), Some(0));
         // Issue #378: the same on Windows, where the Ryzen integrated GPU without a monitor crashed
         // the display driver. Windows also says which display is the primary one.
-        assert_eq!(super::pick_adapter(&adapters(), &[panel(NVIDIA)]), Some(0));
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(NVIDIA)], None), Some(0));
     }
 
     #[test]
     fn pick_adapter_prefers_the_gpu_driving_the_primary_display() {
         // A Windows desktop with a monitor on each GPU: the window opens on the primary display.
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU), panel(NVIDIA)]), Some(0));
-        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)]), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU), panel(NVIDIA)], None), Some(0));
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)], None), Some(1));
     }
 
     #[test]
@@ -1008,10 +1149,10 @@ mod tests {
     #[test]
     fn pick_adapter_keeps_the_integrated_gpu_on_hybrid_laptops() {
         // Issue #8: the panel is on the integrated GPU, an external monitor on the discrete one.
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA), panel(AMD_IGPU)]), Some(1));
-        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)]), Some(1));
-        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU)]), Some(1));
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU)]), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor(NVIDIA), panel(AMD_IGPU)], None), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)], None), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU)], None), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU)], None), Some(1));
     }
 
     #[test]
@@ -1020,17 +1161,32 @@ mod tests {
         use eframe::wgpu::DeviceType;
         let desktop =
             [(INTEL_IGPU.0, INTEL_IGPU.1, DeviceType::IntegratedGpu), (NVIDIA.0, NVIDIA.1, DeviceType::DiscreteGpu), (0, 0, DeviceType::Cpu)];
-        assert_eq!(super::pick_adapter(&desktop, &[monitor(INTEL_IGPU), monitor(NVIDIA)]), Some(1));
-        assert_eq!(super::pick_adapter(&desktop, &[monitor(NVIDIA), monitor(INTEL_IGPU)]), Some(1));
+        assert_eq!(super::pick_adapter(&desktop, &[monitor(INTEL_IGPU), monitor(NVIDIA)], None), Some(1));
+        assert_eq!(super::pick_adapter(&desktop, &[monitor(NVIDIA), monitor(INTEL_IGPU)], None), Some(1));
         // A GPU driving no display still loses to one that does.
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU), monitor(INTEL_IGPU)]), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor(AMD_IGPU), monitor(INTEL_IGPU)], None), Some(1));
+    }
+
+    #[test]
+    fn pick_adapter_prefers_the_gpu_the_compositor_draws_with() {
+        // A hybrid laptop whose Wayland compositor runs on the discrete GPU (Hyprland with
+        // `AQ_DRM_DEVICES` naming it first): the integrated GPU drives the built-in panel, yet the
+        // compositor shows nothing it draws, and reports no error either.
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU)], Some(NVIDIA)), Some(0));
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)], Some(NVIDIA)), Some(0));
+        // The usual hybrid laptop, with the compositor on the integrated GPU: as before (#8).
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU), monitor(NVIDIA)], Some(AMD_IGPU)), Some(1));
+        // No GPU drives a display as far as sysfs says (a container), but the compositor knows.
+        assert_eq!(super::pick_adapter(&adapters(), &[], Some(NVIDIA)), Some(0));
+        // A compositor GPU no adapter matches (a virtual one) leaves the displays in charge.
+        assert_eq!(super::pick_adapter(&adapters(), &[panel(AMD_IGPU)], Some((0x1af4, 0x1050))), Some(1));
     }
 
     #[test]
     fn pick_adapter_falls_back_to_low_power_without_a_match() {
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234))]), Some(1));
-        assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234)), monitor((0x8086, 0x5678))]), Some(1));
-        assert_eq!(super::pick_adapter(&[], &[monitor(NVIDIA)]), None);
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234))], None), Some(1));
+        assert_eq!(super::pick_adapter(&adapters(), &[monitor((0x8086, 0x1234)), monitor((0x8086, 0x5678))], None), Some(1));
+        assert_eq!(super::pick_adapter(&[], &[monitor(NVIDIA)], None), None);
     }
 
     #[test]
@@ -1151,4 +1307,13 @@ mod tests {
         }
         let _ = std::fs::remove_dir_all(&dir);
     }
+
+    /// X11 startup notification and docks match a window to its launcher by `StartupWMClass`,
+    /// so it has to be the class the window carries: the app id, on Wayland and X11 alike.
+    #[test]
+    fn the_desktop_entry_names_the_window_class() {
+        let entry = include_str!("../../../packaging/linux/ai.storyteller.pdfcraft.desktop");
+        let class = entry.lines().find_map(|line| line.strip_prefix("StartupWMClass="));
+        assert_eq!(class, Some(super::APP_ID));
+    }
 }

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/reopen.rs

@@ -0,0 +1,72 @@
+//! The system's choice for Preferences ▸ "Reopen the files that were open when PdfCraft last closed".
+//!
+//! On macOS, System Settings ▸ Desktop & Dock ▸ Windows ▸ "Close windows when quitting an
+//! application" is on by default; turning it off stores `NSQuitAlwaysKeepsWindows = 1`, and apps
+//! then reopen their windows on the next launch. A user who turned it off expects PdfCraft to
+//! bring its documents back too (#871), so that setting is the preference's starting value. It
+//! is read once at launch through `defaults`; the user's own choice in Preferences, once saved,
+//! wins over it. Other systems have no such setting, and the preference starts off there.
+
+/// How long `defaults` may take before launch goes on without it.
+#[cfg(target_os = "macos")]
+const TIMEOUT: std::time::Duration = std::time::Duration::from_millis(500);
+
+/// Whether reopening the last session starts on, before the saved preferences are applied.
+pub fn system_default() -> bool {
+    #[cfg(target_os = "macos")]
+    if let Some(output) = defaults(&["read", "-g", "NSQuitAlwaysKeepsWindows"]) {
+        return keeps_windows(&output);
+    }
+    false
+}
+
+/// `defaults read` output for a boolean (`1`, `0`, `true`, `false`): true only when it says so.
+#[cfg_attr(not(target_os = "macos"), allow(dead_code))]
+fn keeps_windows(output: &str) -> bool {
+    matches!(output.trim(), "1" | "true" | "yes" | "YES")
+}
+
+/// Run `defaults` and return what it printed, or `None` if it fails or hangs. Fails when the key
+/// was never set, which means the system default: close windows when quitting.
+#[cfg(target_os = "macos")]
+fn defaults(args: &[&str]) -> Option<String> {
+    use std::io::Read;
+    use std::process::{Command, Stdio};
+    // The absolute path keeps a `defaults` earlier on PATH from running.
+    let mut child = Command::new("/usr/bin/defaults").args(args).stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::null()).spawn().ok()?;
+    let start = std::time::Instant::now();
+    loop {
+        match child.try_wait() {
+            Ok(Some(status)) if status.success() => break,
+            Ok(None) if start.elapsed() < TIMEOUT => std::thread::sleep(std::time::Duration::from_millis(5)),
+            _ => {
+                let _ = child.kill();
+                let _ = child.wait();
+                return None;
+            }
+        }
+    }
+    let mut out = String::new();
+    // A boolean fits in far less; a misbehaving `defaults` can't make launch read without end.
+    child.stdout.take()?.take(256).read_to_string(&mut out).ok()?;
+    Some(out)
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn only_a_set_flag_keeps_windows() {
+        for on in ["1\n", "1", "true", "YES"] {
+            assert!(super::keeps_windows(on), "{on:?}");
+        }
+        for off in ["0\n", "0", "false", "NO", "", "garbage"] {
+            assert!(!super::keeps_windows(off), "{off:?}");
+        }
+    }
+
+    #[test]
+    fn reading_the_system_default_never_fails() {
+        // Whatever this machine is set to, the read returns a value within the timeout.
+        let _ = super::system_default();
+    }
+}

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

assets/icons/monitor.svg

@@ -0,0 +1,15 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect width="20" height="14" x="2" y="3" rx="2" />
+  <line x1="8" x2="16" y1="21" y2="21" />
+  <line x1="12" x2="12" y1="17" y2="21" />
+</svg>

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"
@@ -74,3 +77,55 @@ sync_github_name = true
 
 [people.jay-tau]
 sync_github_name = true
+
+[people.Piohrun]
+real_name = "Grzegorz Martens"
+sync_github_name = true
+
+[people.krinry]
+sync_github_name = true
+
+
+[people.arcanii]
+real_name = "Bryan Mark"
+display_name = "Arcanii"
+sync_github_name = false
+
+[people.atoslins]
+real_name = "Atos Lins"
+display_name = "Atos Lins"
+sync_github_name = false
+
+[people.mhadidi06]
+display_name = "Mustafa Hadidi"
+
+[people.LucasT-dev]
+real_name = "Lucas"
+display_name = "Lucas"
+sync_github_name = true   # use the name on your public GitHub profile as display name
+
+[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/README.md

@@ -4,7 +4,7 @@ Layer L4: accessibility (execution plan M12.3). Today: the Accessibility Checker
 
 ```rust
 let report = check(&doc, &Options::default());          // 31 of 32 rules (colour contrast off)
-let html = report_html(&report, "file.pdf", "2026-10-02");
+let html = report_html(&report, "file.pdf", "2026-10-02", "en", &in_english);  // or an interface's words
 ```
 
 - **32 rules in 7 categories**, as in Acrobat's full check: Document (permission flag,

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

@@ -1,12 +1,14 @@
 //! The Document, Page Content and Forms rules: catalog settings, page content (tagged or
 //! artifact, text, images, fonts) and annotations.
+//!
+//! Every sentence a rule here can say is listed in [`crate::WORDINGS`], so interfaces can say it in
+//! their own language; a test in this crate keeps that list complete.
 
 use std::collections::{BTreeMap, BTreeSet, HashSet};
 
 use pdfcraft_cos::{Dict, Document, ObjRef, Object};
 use pdfcraft_model::Page;
 
-use crate::structure::Tree;
 use crate::{Finding, Rule};
 
 /// What the page content holds, per checked page.
@@ -145,8 +147,8 @@ fn text_of(doc: &Document, d: &Dict, key: &[u8]) -> Option<String> {
     d.get(key).map(|o| doc.resolve(o)).and_then(|o| o.as_string().map(|s| s.to_text())).map(|s| s.trim().to_owned()).filter(|s| !s.is_empty())
 }
 
-fn doc_finding(message: impl Into<String>) -> Vec<Finding> {
-    vec![Finding { page: None, message: message.into() }]
+fn doc_finding(sentence: &'static str) -> Vec<Finding> {
+    vec![Finding::plain(None, sentence)]
 }
 
 pub(crate) fn document_rule(doc: &Document, rule: Rule, pages: &[Page], scan: &Scan) -> Vec<Finding> {
@@ -168,10 +170,10 @@ pub(crate) fn document_rule(doc: &Document, rule: Rule, pages: &[Page], scan: &S
             let marked = cat.get(b"MarkInfo").map(|m| doc.resolve(m)).and_then(|m| m.as_dict().and_then(|d| d.get(b"Marked").cloned()));
             let mut out = Vec::new();
             if !cat.contains(b"StructTreeRoot") {
-                out.push(Finding { page: None, message: "The document has no tags (structure tree)".into() });
+                out.push(Finding::plain(None, "The document has no tags (structure tree)"));
             }
             if !matches!(marked, Some(Object::Bool(true))) {
-                out.push(Finding { page: None, message: "The document isn't marked as tagged (MarkInfo Marked)".into() });
+                out.push(Finding::plain(None, "The document isn't marked as tagged (MarkInfo Marked)"));
             }
             out
         }
@@ -186,7 +188,7 @@ pub(crate) fn document_rule(doc: &Document, rule: Rule, pages: &[Page], scan: &S
             let mut out = Vec::new();
             let info = doc.trailer().get(b"Info").map(|i| doc.resolve(i)).and_then(|i| i.as_dict().cloned()).unwrap_or_default();
             if text_of(doc, &info, b"Title").is_none() {
-                out.push(Finding { page: None, message: "The document has no title".into() });
+                out.push(Finding::plain(None, "The document has no title"));
             }
             let shows = cat
                 .get(b"ViewerPreferences")
@@ -194,13 +196,17 @@ pub(crate) fn document_rule(doc: &Document, rule: Rule, pages: &[Page], scan: &S
                 .and_then(|v| v.as_dict().and_then(|d| d.get(b"DisplayDocTitle").map(|x| matches!(&*doc.resolve(x), Object::Bool(true)))))
                 .unwrap_or(false);
             if !shows {
-                out.push(Finding { page: None, message: "The window shows the file name, not the title (Initial View > Show)".into() });
+                out.push(Finding::plain(None, "The window shows the file name, not the title (Initial View > Show)"));
             }
             out
         }
         Rule::Bookmarks => {
             let has = cat.get(b"Outlines").map(|o| doc.resolve(o)).and_then(|o| o.as_dict().map(|d| d.contains(b"First"))).unwrap_or(false);
-            if pages.len() > 20 && !has { doc_finding(format!("{} pages and no bookmarks", pages.len())) } else { Vec::new() }
+            if pages.len() > 20 && !has {
+                vec![Finding::worded(None, "{n} pages and no bookmarks", vec![("{n}", pages.len().to_string())])]
+            } else {
+                Vec::new()
+            }
         }
         _ => Vec::new(),
     }
@@ -212,9 +218,22 @@ fn subtype_name(d: &Dict) -> String {
     String::from_utf8_lossy(d.name(b"Subtype").unwrap_or(b"Unknown")).into_owned()
 }
 
-pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usize], scan: &Scan, tree: &Tree) -> Vec<Finding> {
+/// 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 tagged = tree.exists;
     let annots = |p: &Page| -> Vec<(ObjRef, Dict)> {
         let a = p.dict.get(b"Annots").map(|a| doc.resolve(a)).and_then(|a| a.as_array().cloned()).unwrap_or_default();
         a.iter()
@@ -228,7 +247,10 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
                 return doc_finding("The document isn't tagged, so none of its content is");
             }
             for (p, n) in &scan.untagged {
-                out.push(Finding { page: Some(*p), message: format!("Page {}: {n} untagged content item{}", p + 1, if *n == 1 { "" } else { "s" }) });
+                // One item and several items are separate wordings, so a language can agree the
+                // noun with the number its own way.
+                let pattern = if *n == 1 { "Page {p}: {n} untagged content item" } else { "Page {p}: {n} untagged content items" };
+                out.push(Finding::worded(Some(*p), pattern, vec![("{p}", (p + 1).to_string()), ("{n}", n.to_string())]));
             }
         }
         Rule::TaggedAnnotations | Rule::TaggedMultimedia | Rule::TaggedFormFields => {
@@ -242,8 +264,19 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
                         _ => st != b"Widget" && !MULTIMEDIA.contains(&st) && st != b"PrinterMark",
                     };
                     if applies && !(tagged && a.contains(b"StructParent")) {
-                        let what = if st == b"Widget" { "Form field".to_string() } else { format!("{} annotation", subtype_name(&a)) };
-                        out.push(Finding { page: Some(p), message: format!("{what} on page {} isn't tagged", p + 1) });
+                        // A whole sentence each way, rather than a noun put in front of one: a form
+                        // field and an annotation of some subtype read differently in other
+                        // languages. The subtype itself is the PDF's own name and goes in as it is.
+                        let mut values = vec![("{p}", (p + 1).to_string())];
+                        let pattern = if st == b"Widget" {
+                            "Form field on page {p} isn't tagged"
+                        } else {
+                            values.push(("{}", subtype_name(&a)));
+                            "{} annotation on page {p} isn't tagged"
+                        };
+                        let mut finding = Finding::worded(Some(p), pattern, values);
+                        finding.bbox = annotation_rect(doc, &a);
+                        out.push(finding);
                     }
                 }
             }
@@ -252,7 +285,7 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
             for &p in list {
                 let Some(page) = pages.get(p) else { continue };
                 if !annots(page).is_empty() && page.dict.name(b"Tabs") != Some(b"S") {
-                    out.push(Finding { page: Some(p), message: format!("Page {} doesn't tab in structure order", p + 1) });
+                    out.push(Finding::worded(Some(p), "Page {p} doesn't tab in structure order", vec![("{p}", (p + 1).to_string())]));
                 }
             }
         }
@@ -264,8 +297,18 @@ pub(crate) fn page_rule(doc: &Document, rule: Rule, pages: &[Page], list: &[usiz
                         && let Some(f) = doc.get(*r).as_dict()
                         && !maps_to_unicode(doc, f)
                     {
-                        let name = f.name(b"BaseFont").map(|n| String::from_utf8_lossy(n).into_owned()).unwrap_or_else(|| "(unnamed)".into());
-                        out.push(Finding { page: Some(*p), message: format!("Font {name} on page {} doesn't map its characters to Unicode", p + 1) });
+                        // A font with no name gets its own whole sentence, so another language can
+                        // word that rather than translate a parenthesis. The name itself is the
+                        // document's own and goes in as it stands.
+                        let page = ("{p}", (p + 1).to_string());
+                        out.push(match f.name(b"BaseFont") {
+                            Some(n) => Finding::worded(
+                                Some(*p),
+                                "Font {} on page {p} doesn't map its characters to Unicode",
+                                vec![("{}", String::from_utf8_lossy(n).into_owned()), page],
+                            ),
+                            None => Finding::worded(Some(*p), "Font (unnamed) on page {p} doesn't map its characters to Unicode", vec![page]),
+                        });
                     }
                 }
             }
@@ -286,10 +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 {
-                            page: Some(p),
-                            message: format!("Field \"{}\" on page {} has no description (tooltip)", full_name(doc, field), p + 1),
-                        });
+                        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_html;
+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 {
@@ -407,13 +411,158 @@ impl Status {
 }
 
 /// One problem: where it is and what is wrong.
+///
+/// The sentence comes in two forms. [`message`](Finding::message) is it, in English, ready to read.
+/// [`pattern`](Finding::pattern) is the same sentence with a named hole where each value went, and
+/// [`values`](Finding::values) is what filled them, so an interface can say it in another language
+/// instead of showing the English one: it translates the pattern and puts the same values back.
+/// `message` is always `pattern` with `values` in it, because [`Finding::worded`] builds it.
+///
+/// Every hole holds the document's own data — an element type, a font name, a count — and goes in
+/// as it stands, with one exception: a hole named `{what}` holds another wording of ours, still with
+/// its own holes in it. An interface translates that wording too and puts it in the frame first, and
+/// then fills every hole in what it has; [`Finding::nested`] builds such a finding.
 #[derive(Clone, Debug, PartialEq)]
 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,
+    /// What goes in each of `pattern`'s holes, by the hole's name (`"{p}"`, braces included).
+    pub values: Vec<(&'static str, String)>,
 }
 
+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, 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, 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
+    /// separately so the two read in whichever order the language reads them.
+    ///
+    /// `what` is one of our own wordings and may have holes of its own; they are filled from
+    /// `values` along with the frame's. It goes in before the values do — it is ours, not the
+    /// document's — which is what lets its holes be filled at all.
+    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, object: None, bbox: None, message, pattern, values }
+    }
+
+    /// This finding as one sentence, said in the language `words` translates into.
+    ///
+    /// The frame is translated, the wording in `{what}` — if the frame has one — is translated and
+    /// goes in, and only then does the document's own data, in a single pass, so nothing the
+    /// document itself says can be read as a hole. With `&|s: &str| s.to_owned()` this is
+    /// [`message`](Finding::message).
+    pub fn said(&self, words: Words) -> String {
+        let mut frame = words(self.pattern);
+        if let Some((_, what)) = self.values.iter().find(|(name, _)| *name == "{what}") {
+            frame = frame.replace("{what}", &words(what));
+        }
+        say(&frame, &self.values)
+    }
+}
+
+/// How an interface says one of our wordings in its own language, holes and all: given the English
+/// in [`WORDINGS`], the same wording in that language. [`in_english`] keeps the English.
+pub type Words<'a> = &'a dyn Fn(&str) -> String;
+
+/// The [`Words`] that translate nothing: the wording as it is written here.
+pub fn in_english(wording: &str) -> String {
+    wording.to_owned()
+}
+
+/// A wording with its holes filled.
+///
+/// A hole is a name in braces, such as `{p}`; what is not in `values` is left as it is written.
+/// Values go in during a single pass over the wording, so a value that itself contains braces is
+/// never read as a hole: the document's own words reach the screen as they stand.
+///
+/// An interface says a [`Finding`] in its own language with this, after translating the pattern
+/// and, if there is one, the wording in `{what}`.
+pub fn say(pattern: &str, values: &[(&str, String)]) -> String {
+    let mut out = String::with_capacity(pattern.len() + 16);
+    let mut rest = pattern;
+    while let Some(open) = rest.find('{') {
+        let (before, from_brace) = rest.split_at(open);
+        out.push_str(before);
+        // `find` counts from the brace, and `}` is one byte, so this is a char boundary; `get`
+        // rather than slicing in case it ever isn't.
+        let Some(close) = from_brace.find('}') else {
+            // A brace with nothing closing it is just text.
+            out.push_str(from_brace);
+            return out;
+        };
+        let Some(hole) = from_brace.get(..=close) else { return out + from_brace };
+        match values.iter().find(|(name, _)| *name == hole) {
+            Some((_, value)) => out.push_str(value),
+            None => out.push_str(hole),
+        }
+        rest = from_brace.get(close + 1..).unwrap_or_default();
+    }
+    out.push_str(rest);
+    out
+}
+
+/// Every sentence the checker can say: each [`Finding::pattern`] and each wording that goes in a
+/// `{what}` hole, in English, with its holes still in it.
+///
+/// An interface that shows the report in another language translates these, which is the whole
+/// reason they are gathered here; `wordings_are_complete` fails if a rule says something that is
+/// not on the list.
+pub const WORDINGS: &[&str] = &[
+    // Document rules.
+    "The security settings don't allow screen readers to read the text",
+    "No page has text: the document appears to be images of pages",
+    "The document has no tags (structure tree)",
+    "The document isn't marked as tagged (MarkInfo Marked)",
+    "No document language is set",
+    "The document has no title",
+    "The window shows the file name, not the title (Initial View > Show)",
+    "{n} pages and no bookmarks",
+    // Page content and forms.
+    "The document isn't tagged, so none of its content is",
+    "Page {p}: {n} untagged content item",
+    "Page {p}: {n} untagged content items",
+    "Form field on page {p} isn't tagged",
+    "{} annotation on page {p} isn't tagged",
+    "Page {p} doesn't tab in structure order",
+    "Font {} on page {p} doesn't map its characters to Unicode",
+    "Font (unnamed) on page {p} doesn't map its characters to Unicode",
+    "Field \"{}\" on page {p} has no description (tooltip)",
+    // The structure rules: the two frames, then what goes in their `{what}`.
+    "{ty} element: {what}",
+    "{ty} element on page {p}: {what}",
+    "no alternate text",
+    "its alternate text is inside another element's and will never be read",
+    "alternate text on an element with no page content",
+    "alternate text hides an annotation inside it",
+    "not in a Table, THead, TBody or TFoot",
+    "not in a TR",
+    "no header cells (TH)",
+    "rows have between {min} and {max} columns",
+    "no summary",
+    "not in an L (list)",
+    "not in an LI (list item)",
+    "the first heading is an H{n}; headings should not skip levels",
+    "H{n} follows an H{d}; headings should not skip levels",
+    // The summary at the end of a long list.
+    AND_MORE,
+];
+
 #[derive(Clone, Debug, PartialEq)]
 pub struct RuleResult {
     pub rule: Rule,
@@ -458,6 +607,9 @@ impl Report {
 /// Findings beyond this many per rule are summarised ("… and n more").
 const MAX_FINDINGS: usize = 200;
 
+/// What the summary of the findings beyond [`MAX_FINDINGS`] says.
+const AND_MORE: &str = "… and {n} more";
+
 /// Run the full check.
 pub fn check(doc: &Document, options: &Options) -> Report {
     let pages = pdfcraft_model::pages(doc);
@@ -465,8 +617,10 @@ pub fn check(doc: &Document, options: &Options) -> Report {
         Some(p) => p.iter().copied().filter(|p| *p < pages.len()).collect(),
         None => (0..pages.len()).collect(),
     };
-    let tree = structure::Tree::read(doc, &pages);
+    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) {
@@ -477,15 +631,42 @@ pub fn check(doc: &Document, options: &Options) -> Report {
             results.push(RuleResult { rule, status: Status::Manual, findings: Vec::new() });
             continue;
         }
-        let mut findings = match rule.category() {
-            Category::Document => content::document_rule(doc, rule, &pages, &scan),
-            Category::PageContent | Category::Forms => content::page_rule(doc, rule, &pages, &page_list, &scan, &tree),
-            _ => tree.rule(rule),
+        // `total` counts every finding; `findings` holds the first MAX_FINDINGS of them.
+        let (mut findings, total) = match rule.category() {
+            Category::Document => {
+                let found = content::document_rule(doc, rule, &pages, &scan);
+                let n = found.len();
+                (found, n)
+            }
+            Category::PageContent | Category::Forms => {
+                let found = content::page_rule(doc, rule, &pages, &page_list, &scan, tagged);
+                let n = found.len();
+                (found, n)
+            }
+            _ => tree_rules.remove(&rule).unwrap_or_default(),
         };
-        if findings.len() > MAX_FINDINGS {
-            let more = findings.len() - MAX_FINDINGS;
+        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);
-            findings.push(Finding { page: None, message: format!("… and {more} more") });
+            findings.push(Finding::worded(None, AND_MORE, vec![("{n}", more.to_string())]));
         }
         let status = if findings.is_empty() { Status::Passed } else { Status::Failed };
         results.push(RuleResult { rule, status, findings });

crates/a11y/src/report.rs

@@ -1,48 +1,80 @@
 //! The accessibility report: a self-contained HTML page with the summary and, per category,
 //! each rule's status, description and problems.
+//!
+//! The page is written in whichever language `words` translates into, down to its `lang` attribute,
+//! so it reads the way the interface that saved it reads. Only the file name, the date and what the
+//! findings say about the document itself come from elsewhere.
 
-use crate::{Category, Report, Status};
+use crate::{Category, Report, Status, Words};
 
 fn esc(s: &str) -> String {
     s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;")
 }
 
-/// The report for `file_name`, dated `date` (as the caller formats it).
-pub fn report_html(report: &Report, file_name: &str, date: &str) -> String {
+/// The page's own words, in the order it says them: its heading, what it calls the file and the
+/// date, the two things the summary can say, and the headers of the table.
+///
+/// The rest of what the page says it gets from elsewhere — the categories, the rules and the
+/// findings name themselves — so an interface has these to translate and those to translate; a test
+/// in this crate keeps the list in step with the page.
+pub const REPORT_WORDS: &[&str] = &[
+    "Accessibility Report",
+    "Filename",
+    "Report created",
+    "Summary",
+    "The checker found problems which may prevent the document from being fully accessible.",
+    "The checker found no problems in this document.",
+    "Detailed Report",
+    "Rule Name",
+    "Status",
+    "Description",
+];
+
+/// The report for `file_name`, dated `date` (as the caller formats it), written in the language
+/// `words` translates into and marked `lang` (`"en"` and `&|s: &str| s.to_owned()` for English).
+pub fn report_html(report: &Report, file_name: &str, date: &str, lang: &str, words: Words) -> String {
+    let title = esc(&words("Accessibility Report"));
     let mut h = String::new();
-    h.push_str("<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><title>Accessibility Report</title>\n<style>\n");
+    h.push_str(&format!("<!doctype html>\n<html lang=\"{}\"><head><meta charset=\"utf-8\"><title>{title}</title>\n<style>\n", esc(lang)));
     h.push_str(
         "body{font:14px/1.45 system-ui,sans-serif;margin:24px;color:#1d1d1f}h1{font-size:22px}h2{font-size:17px;margin-top:28px}\
          table{border-collapse:collapse;width:100%}th,td{border:1px solid #ccc;padding:6px 8px;text-align:left;vertical-align:top}\
          th{background:#f2f2f2}.Failed{color:#b3261e;font-weight:600}.Passed{color:#1e7b34}ul{margin:4px 0 0;padding-left:18px}\n",
     );
-    h.push_str("</style></head><body>\n<h1>Accessibility Report</h1>\n");
-    h.push_str(&format!("<p>Filename: <b>{}</b><br>Report created: {}</p>\n", esc(file_name), esc(date)));
-    h.push_str("<h2>Summary</h2>\n<p>");
-    h.push_str(if report.count(Status::Failed) > 0 {
-        "The checker found problems which may prevent the document from being fully accessible."
+    h.push_str(&format!("</style></head><body>\n<h1>{title}</h1>\n"));
+    h.push_str(&format!("<p>{}: <b>{}</b><br>{}: {}</p>\n", esc(&words("Filename")), esc(file_name), esc(&words("Report created")), esc(date)));
+    h.push_str(&format!("<h2>{}</h2>\n<p>", esc(&words("Summary"))));
+    // Each outcome is a whole sentence, and each is handed over on its own, so the list in
+    // `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 {
-        "The checker found no problems in this document."
+        esc(&words("The checker found no problems in this document."))
     });
     h.push_str("</p>\n<ul>\n");
     for s in [Status::Manual, Status::Skipped, Status::Passed, Status::Failed] {
-        h.push_str(&format!("<li>{}: {}</li>\n", s.label(), report.count(s)));
+        h.push_str(&format!("<li>{}: {}</li>\n", esc(&words(s.label())), report.count(s)));
     }
-    h.push_str("</ul>\n<h2>Detailed Report</h2>\n");
+    h.push_str(&format!("</ul>\n<h2>{}</h2>\n", esc(&words("Detailed Report"))));
+    let (name, status, description) = (esc(&words("Rule Name")), esc(&words("Status")), esc(&words("Description")));
     for c in Category::ALL {
-        h.push_str(&format!("<h3>{}</h3>\n<table><tr><th>Rule Name</th><th>Status</th><th>Description</th></tr>\n", c.label()));
+        h.push_str(&format!("<h3>{}</h3>\n<table><tr><th>{name}</th><th>{status}</th><th>{description}</th></tr>\n", esc(&words(c.label()))));
         for r in report.in_category(c) {
             h.push_str(&format!(
                 "<tr><td>{}</td><td class=\"{:?}\">{}</td><td>{}",
-                esc(r.rule.name()),
+                esc(&words(r.rule.name())),
                 r.status,
-                r.status.label(),
-                esc(r.rule.description())
+                esc(&words(r.status.label())),
+                esc(&words(r.rule.description()))
             ));
             if !r.findings.is_empty() {
                 h.push_str("<ul>");
                 for f in &r.findings {
-                    h.push_str(&format!("<li>{}</li>", esc(&f.message)));
+                    h.push_str(&format!("<li>{}</li>", esc(&f.said(words))));
                 }
                 h.push_str("</ul>");
             }

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(
@@ -157,6 +218,187 @@ fn row_and_column_spans_keep_a_table_regular() {
     assert_eq!(status(&r, Rule::TableRegularity), Status::Passed, "{:?}", r.result(Rule::TableRegularity));
 }
 
+/// A tagged document whose structure tree is the Document element `document` (object 3).
+fn structure_doc(objects: &[String]) -> Document {
+    let mut objs = vec!["<< /Type /Catalog /StructTreeRoot 2 0 R >>".to_string(), "<< /Type /StructTreeRoot /K 3 0 R >>".to_string()];
+    objs.extend_from_slice(objects);
+    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 })
+}
+
+#[test]
+fn figures_and_tables_past_the_old_element_cut_off_are_checked() {
+    // Five thousand paragraphs, then a figure without alternate text and a table whose second row
+    // is narrower than its first.
+    let mut kids = vec!["<< /S /P >>".to_string(); 5_000];
+    kids.push("<< /S /Figure >>".into());
+    kids.push(
+        "<< /S /Table /A << /O /Table /Summary (s) >> /K [ << /S /TR /K [ << /S /TD >> << /S /TD >> ] >> << /S /TR /K [ << /S /TD >> ] >> ] >>"
+            .into(),
+    );
+    let doc = structure_doc(&[format!("<< /S /Document /K [{}] >>", kids.join(" "))]);
+    let r = checked(&doc, &[Rule::FiguresAltText, Rule::TableRegularity]);
+    assert_eq!(r.result(Rule::FiguresAltText).unwrap().findings.len(), 1);
+    assert!(r.result(Rule::TableRegularity).unwrap().findings[0].message.contains("between 1 and 2"));
+}
+
+#[test]
+fn findings_are_listed_in_document_order_not_in_the_order_they_close() {
+    // Each element has alternate text but no content. The outer ones close last.
+    let doc = structure_doc(&["<< /S /Document /K [ << /S /Sect /Alt (a) /K [ << /S /P /Alt (b) /K [ << /S /Div /Alt (c) >> ] >> ] >> ] >>".into()]);
+    let r = checked(&doc, &[Rule::AltTextAssociated]);
+    let kinds: Vec<&str> = r.result(Rule::AltTextAssociated).unwrap().findings.iter().map(|f| f.message.split(' ').next().unwrap_or("")).collect();
+    assert_eq!(kinds, ["Sect", "P", "Div"]);
+}
+
+#[test]
+fn a_rule_lists_its_first_findings_and_counts_the_rest() {
+    let figures = vec!["<< /S /Figure >>".to_string(); 300].join(" ");
+    let doc = structure_doc(&[format!("<< /S /Document /K [{figures}] >>")]);
+    let r = checked(&doc, &[Rule::FiguresAltText]);
+    let found = &r.result(Rule::FiguresAltText).unwrap().findings;
+    assert_eq!(found.len(), 201);
+    assert_eq!(found[200].message, "… and 100 more");
+    assert!(found[..200].iter().all(|f| f.message == "Figure element: no alternate text"));
+}
+
+#[test]
+fn cycles_shared_kids_and_missing_kids_are_read_once() {
+    // Object 4 holds itself, a figure twice, and a missing object is listed too.
+    let doc = structure_doc(&[
+        "<< /S /Document /K [4 0 R 4 0 R 99 0 R] >>".into(),
+        "<< /S /Sect /K [4 0 R 5 0 R 5 0 R] >>".into(),
+        "<< /S /Figure >>".into(),
+    ]);
+    let r = checked(&doc, &[Rule::FiguresAltText]);
+    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
+    // figure is at depth `sections`; the walk reads depths up to 256.
+    let figure_within = |sections: usize| {
+        let mut objs: Vec<String> = (0..sections).map(|i| format!("<< /S /Sect /K {} 0 R >>", 4 + i)).collect();
+        objs.push("<< /S /Figure >>".into());
+        let r = checked(&structure_doc(&objs), &[Rule::FiguresAltText]);
+        r.result(Rule::FiguresAltText).unwrap().findings.len()
+    };
+    assert_eq!(figure_within(250), 1, "within the depth limit");
+    assert_eq!(figure_within(300), 0, "past the depth limit");
+}
+
+#[test]
+fn arrays_nested_deeper_than_the_limit_are_not_read() {
+    let nested = |n: usize| format!("<< /S /Document /K {}<< /S /Figure >>{} >>", "[".repeat(n), "]".repeat(n));
+    let shallow = checked(&structure_doc(&[nested(100)]), &[Rule::FiguresAltText]);
+    assert_eq!(shallow.result(Rule::FiguresAltText).unwrap().findings.len(), 1);
+    let deep = checked(&structure_doc(&[nested(300)]), &[Rule::FiguresAltText]);
+    assert_eq!(deep.result(Rule::FiguresAltText).unwrap().findings.len(), 0);
+}
+
+#[test]
+fn a_long_list_of_marked_content_counts_as_content() {
+    // The first paragraph holds 20,000 marked-content items, so its alternate text has content.
+    let items = (0..20_000).map(|i| i.to_string()).collect::<Vec<_>>().join(" ");
+    let doc = structure_doc(&[format!("<< /S /Document /K [ << /S /P /Alt (a) /K [{items}] >> << /S /P /Alt (b) >> ] >>")]);
+    let r = checked(&doc, &[Rule::AltTextAssociated]);
+    assert_eq!(r.result(Rule::AltTextAssociated).unwrap().findings.len(), 1);
+}
+
+#[test]
+fn huge_spans_do_not_size_the_table() {
+    // A row of 2,000 cells, each spanning 10,000 columns, then a row of one cell.
+    let wide = vec!["<< /S /TD /A << /O /Table /ColSpan 10000 >> >>".to_string(); 2_000].join(" ");
+    let doc = structure_doc(&[format!(
+        "<< /S /Document /K [ << /S /Table /A << /O /Table /Summary (s) >> /K [ << /S /TR /K [{wide}] >> << /S /TR /K [ << /S /TD >> ] >> ] >> ] >>"
+    )]);
+    let r = checked(&doc, &[Rule::TableRegularity]);
+    let found = &r.result(Rule::TableRegularity).unwrap().findings;
+    assert_eq!(found[0].message, "Table element: rows have between 1 and 20000000 columns");
+}
+
+#[test]
+fn row_spans_carry_past_their_row() {
+    // Row 1: 3,000 cells, each spanning 10,000 rows. Row 2: 3,000 cells, which start after them.
+    let row1 = vec!["<< /S /TD /A << /O /Table /RowSpan 10000 >> >>".to_string(); 3_000].join(" ");
+    let row2 = vec!["<< /S /TD >>".to_string(); 3_000].join(" ");
+    let doc = structure_doc(&[format!(
+        "<< /S /Document /K [ << /S /Table /A << /O /Table /Summary (s) >> /K [ << /S /TR /K [{row1}] >> << /S /TR /K [{row2}] >> ] >> ] >>"
+    )]);
+    let r = checked(&doc, &[Rule::TableRegularity]);
+    let found = &r.result(Rule::TableRegularity).unwrap().findings;
+    assert_eq!(found[0].message, "Table element: rows have between 3000 and 6000 columns");
+}
+
+#[test]
+fn spans_that_are_not_positive_integers_read_as_one() {
+    // ColSpan -3 and 0 read as 1, and 2.0 reads as 2; the first row is 4 columns wide, the second 5.
+    let doc = structure_doc(&[
+        "<< /S /Document /K [ << /S /Table /A << /O /Table /Summary (s) >> /K [ \
+         << /S /TR /K [ << /S /TD /A << /O /Table /ColSpan -3 >> >> << /S /TD /A << /O /Table /ColSpan 0 >> >> << /S /TD /A << /O /Table /ColSpan 2.0 >> >> ] >> \
+         << /S /TR /K [ << /S /TD >> << /S /TD >> << /S /TD >> << /S /TD >> << /S /TD >> ] >> ] >> ] >>"
+            .into(),
+    ]);
+    let r = checked(&doc, &[Rule::TableRegularity]);
+    assert_eq!(r.result(Rule::TableRegularity).unwrap().findings[0].message, "Table element: rows have between 4 and 5 columns");
+}
+
 #[test]
 fn page_content_and_annotation_problems_are_found() {
     let mut objs = good();
@@ -171,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]
@@ -218,9 +473,22 @@ fn rules_have_ids_and_the_report_lists_them() {
     let per: Vec<usize> = Category::ALL.iter().map(|c| Rule::ALL.iter().filter(|r| r.category() == *c).count()).collect();
     assert_eq!(per, [8, 9, 2, 5, 5, 2, 1]);
     let doc = pdf(&good(), "/Info 8 0 R");
-    let html = report_html(&check(&doc, &Options::default()), "a<b>.pdf", "2026-10-02");
+    let report = check(&doc, &Options::default());
+    let html = report_html(&report, "a<b>.pdf", "2026-10-02", "en", &in_english);
     assert!(html.contains("a&lt;b&gt;.pdf") && html.contains("Accessibility permission flag") && html.contains("Needs manual check: 5"));
     assert!(html.contains("<h3>Headings</h3>"));
+    // In another language every word of ours is said in it, down to the `lang`; the file name is the
+    // file's own and stays as it is.
+    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 {
@@ -253,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]
@@ -335,3 +646,93 @@ fn an_untagged_document_has_no_headings() {
     objs[0] = "<< /Type /Catalog /Pages 2 0 R >>".into();
     assert!(headings(&pdf(&objs, "")).is_empty());
 }
+
+/// The text of every `"…"` literal with a space in it, outside comments and byte strings.
+fn sentences(source: &str) -> Vec<String> {
+    let b = source.as_bytes();
+    let (mut out, mut i) = (Vec::new(), 0);
+    while i < b.len() {
+        if b[i] == b'/' && b.get(i + 1) == Some(&b'/') {
+            while i < b.len() && b[i] != b'\n' {
+                i += 1;
+            }
+        } else if b[i] == b'"' {
+            let byte_string = i > 0 && b[i - 1] == b'b';
+            let start = i + 1;
+            i = start;
+            while i < b.len() && b[i] != b'"' {
+                i += if b[i] == b'\\' { 2 } else { 1 };
+            }
+            // Quotes and backslashes are ASCII, so this never cuts a character in two.
+            let text = source.get(start..i.min(b.len())).unwrap_or_default();
+            if !byte_string && text.contains(' ') {
+                out.push(text.replace("\\\"", "\""));
+            }
+            i += 1;
+        } else {
+            i += 1;
+        }
+    }
+    out
+}
+
+/// Every sentence the rules can say is listed in `WORDINGS`, so an interface showing the report in
+/// another language has something to translate. The two rule files hold no prose of their own, so a
+/// literal with a space in it is a sentence a person reads.
+#[test]
+fn wordings_are_complete() {
+    let mut missing = Vec::new();
+    for source in [include_str!("content.rs"), include_str!("structure.rs")] {
+        for sentence in sentences(source) {
+            if !WORDINGS.contains(&sentence.as_str()) {
+                missing.push(sentence);
+            }
+        }
+    }
+    assert!(missing.is_empty(), "add these to WORDINGS, and a translation of each to every interface: {missing:#?}");
+}
+
+/// Every word the report page says of its own is listed in `REPORT_WORDS`, and every word on that
+/// list is one the page says: the page hands each over to `words` as a literal, so the two can be
+/// read off one another.
+#[test]
+fn report_words_are_complete() {
+    let source = include_str!("report.rs");
+    let mut said = Vec::new();
+    let mut rest = source;
+    while let Some(at) = rest.find("words(\"") {
+        rest = &rest[at + 7..];
+        let Some(end) = rest.find('"') else { break };
+        said.push(&rest[..end]);
+        rest = &rest[end..];
+    }
+    let missing: Vec<&&str> = said.iter().filter(|word| !REPORT_WORDS.contains(word)).collect();
+    assert!(missing.is_empty(), "add these to REPORT_WORDS, and a translation of each to every interface: {missing:#?}");
+    let unsaid: Vec<&&str> = REPORT_WORDS.iter().filter(|word| !said.contains(word)).collect();
+    assert!(unsaid.is_empty(), "REPORT_WORDS lists words the page no longer says: {unsaid:#?}");
+}
+
+/// `say` puts the values in, and what it puts in is never read as a hole of its own: a document that
+/// names a font `{p}` cannot make a finding say which page it is on.
+#[test]
+fn say_fills_holes_once() {
+    let values = [("{p}", "7".to_string()), ("{}", "{p} {n}".to_string())];
+    assert_eq!(
+        say("Font {} on page {p} doesn't map its characters to Unicode", &values),
+        "Font {p} {n} on page 7 doesn't map its characters to Unicode"
+    );
+    // A hole with nothing for it, and a brace with nothing closing it, are left as they stand.
+    assert_eq!(say("{a} {p} {", &values), "{a} 7 {");
+}
+
+/// A finding whose frame holds another wording says the whole thing in English, holes and all
+/// filled, and still hands the interface the two wordings to translate.
+#[test]
+fn a_nested_finding_says_itself() {
+    let values = vec![("{min}", "1".to_string()), ("{max}", "2".to_string()), ("{ty}", "Table".to_string()), ("{p}", "3".to_string())];
+    let f = Finding::nested(Some(2), "{ty} element on page {p}: {what}", "rows have between {min} and {max} columns", values);
+    assert_eq!(f.message, "Table element on page 3: rows have between 1 and 2 columns");
+    assert_eq!(f.said(&in_english), f.message, "saying it in English is the message");
+    // Both wordings are translated, each on its own, and the document's words are left alone.
+    assert_eq!(f.said(&|w: &str| format!("«{w}»")), "«Table element on page 3: «rows have between 1 and 2 columns»»");
+}

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};
 
@@ -104,7 +104,7 @@ fn line_end(c: &mut String, kind: &[u8], tip: (f64, f64), from: (f64, f64), w: f
 /// point parallel to the chord between its neighbours (an end uses itself as the missing
 /// neighbour). Ink is drawn so, as Acrobat draws it, rather than as straight segments. The curve
 /// stays within its points and these control points.
-pub(crate) fn smooth_segments(pts: &[(f64, f64)]) -> Vec<[(f64, f64); 3]> {
+pub fn smooth_segments(pts: &[(f64, f64)]) -> Vec<[(f64, f64); 3]> {
     let Some(&last) = pts.last() else { return Vec::new() };
     let at = |i: usize| pts.get(i).copied().unwrap_or(last);
     (0..pts.len().saturating_sub(1))
@@ -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.
@@ -1931,7 +2094,9 @@ pub fn summaries(doc: &Document) -> Vec<Summary> {
                 index,
                 subtype,
                 author: text_value(doc, d, b"T"),
-                contents: text_value(doc, d, b"Contents"),
+                // Acrobat ends lines with CR, which the interface would draw as nothing (keep in
+                // step with `pdfcraft_render::inspect`).
+                contents: text_value(doc, d, b"Contents").map(|s| s.replace("\r\n", "\n").replace('\r', "\n")),
                 modified: text_value(doc, d, b"M"),
                 name: text_value(doc, d, b"NM"),
                 in_reply_to,

crates/annot/src/links.rs

@@ -202,13 +202,24 @@ fn write_action(doc: &Document, d: &mut Dict, a: &LinkAction) -> Result<(), Anno
     Ok(())
 }
 
+/// Check link geometry before writing PDF objects: a user or automation call can supply
+/// non-finite coordinates or a finite pair whose difference overflows to infinity.
+fn checked_rect(rect: [f64; 4]) -> Result<[f64; 4], AnnotError> {
+    if !rect.iter().all(|v| v.is_finite()) {
+        return Err(AnnotError::Invalid("the link area must have finite coordinates".into()));
+    }
+    let r = [rect[0].min(rect[2]), rect[1].min(rect[3]), rect[0].max(rect[2]), rect[1].max(rect[3])];
+    let (width, height) = (r[2] - r[0], r[3] - r[1]);
+    if !width.is_finite() || !height.is_finite() || width < 2.0 || height < 2.0 {
+        return Err(AnnotError::Invalid("the link area is too small or too large".into()));
+    }
+    Ok(r)
+}
+
 /// Add a link over `rect` (user space). Returns its index in the page's `/Annots`.
 pub fn add(doc: &mut Document, page: usize, rect: [f64; 4], action: &LinkAction, style: &LinkStyle) -> Result<usize, AnnotError> {
     let p = page_ref(doc, page)?;
-    let r = [rect[0].min(rect[2]), rect[1].min(rect[3]), rect[0].max(rect[2]), rect[1].max(rect[3])];
-    if !r.iter().all(|v| v.is_finite()) || r[2] - r[0] < 2.0 || r[3] - r[1] < 2.0 {
-        return Err(AnnotError::Invalid("the link area is too small".into()));
-    }
+    let r = checked_rect(rect)?;
     if matches!(action, LinkAction::Other(_)) {
         return Err(AnnotError::Invalid("choose a page or a web address".into()));
     }
@@ -250,10 +261,7 @@ pub fn set(
     let (_, r) = link_at(doc, page, index)?;
     let mut d = doc.get(r).as_dict().cloned().unwrap_or_default();
     if let Some(rect) = rect {
-        let rr = [rect[0].min(rect[2]), rect[1].min(rect[3]), rect[0].max(rect[2]), rect[1].max(rect[3])];
-        if rr[2] - rr[0] < 2.0 || rr[3] - rr[1] < 2.0 {
-            return Err(AnnotError::Invalid("the link area is too small".into()));
-        }
+        let rr = checked_rect(rect)?;
         d.set(b"Rect".to_vec(), Object::Array(rr.iter().map(|v| Object::Real(*v)).collect()));
     }
     if let Some(s) = style {
@@ -296,6 +304,59 @@ pub fn remove_all(doc: &mut Document, pages: Option<&[usize]>) -> Result<usize,
     Ok(n)
 }
 
+/// Recognise common ASCII mailbox addresses without mistaking domains, partial words or
+/// invalid labels for e-mail links. The returned end is in source-character indices.
+fn email_at(chars: &[char], start: usize) -> Option<(usize, String)> {
+    let local_char = |c: char| c.is_ascii_alphanumeric() || "._+%-".contains(c);
+    let domain_char = |c: char| c.is_ascii_alphanumeric() || c == '-' || c == '.';
+    // Don't create a link starting in the middle of an address.
+    if start > 0 && chars.get(start - 1).is_some_and(|c| local_char(*c) || *c == '@') {
+        return None;
+    }
+    let mut at = start;
+    while chars.get(at).is_some_and(|c| local_char(*c)) {
+        at += 1;
+        if at - start > 64 {
+            return None;
+        }
+    }
+    let local = chars.get(start..at)?;
+    if local.is_empty() || local.first() == Some(&'.') || local.last() == Some(&'.') || local.windows(2).any(|w| w == ['.', '.']) {
+        return None;
+    }
+    if chars.get(at) != Some(&'@') {
+        return None;
+    }
+    let mut end = at + 1;
+    while chars.get(end).is_some_and(|c| domain_char(*c)) {
+        end += 1;
+        if end - at - 1 > 253 {
+            return None;
+        }
+    }
+    while end > at + 1 && chars.get(end - 1) == Some(&'.') {
+        end -= 1;
+    }
+    if chars.get(end).is_some_and(|c| c.is_ascii_alphanumeric() || *c == '@' || *c == '_') {
+        return None;
+    }
+    let domain = chars.get(at + 1..end)?;
+    let mut labels = 0;
+    let mut tld_length = 0;
+    for label in domain.split(|c| *c == '.') {
+        if label.is_empty() || label.len() > 63 || !label.first()?.is_ascii_alphanumeric() || !label.last()?.is_ascii_alphanumeric() {
+            return None;
+        }
+        labels += 1;
+        tld_length = label.len();
+    }
+    if labels < 2 || tld_length < 2 {
+        return None;
+    }
+    let address: String = chars.get(start..end)?.iter().collect();
+    Some((end, format!("mailto:{address}")))
+}
+
 /// Find web addresses in text: `http(s)://…`, `www.…` and bare e-mail addresses become
 /// `mailto:`. Returns character ranges and the URI for each.
 pub fn find_urls(chars: &[char]) -> Vec<(std::ops::Range<usize>, String)> {
@@ -327,6 +388,11 @@ pub fn find_urls(chars: &[char]) -> Vec<(std::ops::Range<usize>, String)> {
                 continue;
             }
         }
+        if boundary && let Some((end, uri)) = email_at(chars, i) {
+            out.push((i..end, uri));
+            i = end;
+            continue;
+        }
         i += 1;
     }
     out

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");
 }
 
@@ -432,6 +433,19 @@ fn real_annotation_flags_do_not_lock_comments() {
     assert!(set_info(&mut doc, 0, 0, Some("Ada"), None, None, &meta("")).is_ok());
 }
 
+#[test]
+fn carriage_returns_in_comment_text_become_line_breaks() {
+    let mut doc = fixture();
+    let page = page_refs(&doc).unwrap()[0];
+    let mut entries = annots(&doc, page);
+    let Object::Dict(annotation) = &mut entries[0] else { panic!("fixture annotation is inline") };
+    // Acrobat ends lines in /Contents with CR; the interface only breaks lines at LF.
+    annotation.set(b"Contents".to_vec(), PdfString::text("one\r\rtwo\r\nthree"));
+    set_annots(&mut doc, page, entries).unwrap();
+
+    assert_eq!(summaries(&doc)[0].contents.as_deref(), Some("one\n\ntwo\nthree"));
+}
+
 #[test]
 fn a_locked_text_box_still_refits_its_text() {
     let mut doc = fixture();
@@ -574,6 +588,31 @@ fn links_are_added_edited_listed_and_removed() {
     assert!(links::add(&mut doc, 0, [0.0, 0.0, 1.0, 1.0], &LinkAction::Page(0), &LinkStyle::default()).is_err(), "too small");
 }
 
+#[test]
+fn link_edit_rejects_non_finite_and_overflowed_rectangles_without_mutating_the_pdf() {
+    use crate::links::{self, LinkAction, LinkStyle};
+    let mut doc = fixture();
+    let original_rect = [10.0, 20.0, 110.0, 70.0];
+    let index = links::add(&mut doc, 0, original_rect, &LinkAction::Uri("https://example.org".into()), &LinkStyle::default()).unwrap();
+    let before = links::list(&doc);
+    let changed_action = LinkAction::Uri("https://other.example".into());
+    for rect in [
+        [f64::NAN, 0.0, 100.0, 30.0],
+        [0.0, 0.0, f64::INFINITY, 30.0],
+        [f64::NEG_INFINITY, 0.0, 100.0, 30.0],
+        [-1e308, 0.0, 1e308, 30.0],
+        [0.0, 0.0, 1.5, 30.0],
+    ] {
+        assert!(links::set(&mut doc, 0, index, Some(rect), Some(&changed_action), None).is_err(), "edit accepted {rect:?}");
+        assert_eq!(links::list(&doc), before, "invalid edit changed an existing link");
+        assert!(links::add(&mut doc, 0, rect, &changed_action, &LinkStyle::default()).is_err(), "add accepted {rect:?}");
+    }
+    // A reversed but otherwise valid rectangle is normalized on edit.
+    links::set(&mut doc, 0, index, Some([110.0, 70.0, 10.0, 20.0]), None, None).unwrap();
+    let edited = links::list(&doc).into_iter().find(|l| l.page == 0 && l.index == index).map(|l| l.rect);
+    assert_eq!(edited, Some(original_rect));
+}
+
 #[test]
 fn urls_are_found_in_text() {
     let t: Vec<char> = "See https://example.org/a?b=1, or www.rust-lang.org. Not a.b or http:/x.".chars().collect();
@@ -581,6 +620,30 @@ fn urls_are_found_in_text() {
     assert_eq!(found, ["https://example.org/a?b=1", "http://www.rust-lang.org"]);
 }
 
+#[test]
+fn common_email_addresses_become_mailto_links_with_source_character_ranges() {
+    let source = "İ Contact ada.lovelace+forms@example.co.uk, browse HTTPS://EXAMPLE.ORG; or ask admin@example.org.";
+    let chars: Vec<char> = source.chars().collect();
+    let links = crate::links::find_urls(&chars);
+    let found: Vec<(String, String)> = links.into_iter().map(|(range, url)| (chars.get(range).unwrap().iter().collect(), url)).collect();
+    assert_eq!(
+        found,
+        [
+            ("ada.lovelace+forms@example.co.uk".into(), "mailto:ada.lovelace+forms@example.co.uk".into()),
+            ("HTTPS://EXAMPLE.ORG".into(), "HTTPS://EXAMPLE.ORG".into()),
+            ("admin@example.org".into(), "mailto:admin@example.org".into()),
+        ]
+    );
+}
+
+#[test]
+fn malformed_email_addresses_are_not_autolinked() {
+    for invalid in ["a@b", "broken@localhost", "a..b@example.org", "foo@.example.org", "foo@example..org", "foo@example.com@x"] {
+        let input: Vec<char> = invalid.chars().collect();
+        assert!(crate::links::find_urls(&input).is_empty(), "{invalid:?} produced a link");
+    }
+}
+
 #[test]
 fn urls_are_found_after_length_changing_lowercase() {
     // U+0130 (İ) lowercases to "i" plus a combining dot above, so a case-folded copy is longer
@@ -1096,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/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "pdfcraft-audit"
+description = "Verification tooling: audit documents for faux redactions (opaque covers over extractable text)"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+pdfcraft-cos = { workspace = true }
+pdfcraft-content = { workspace = true }
+pdfcraft-edit = { workspace = true }
+pdfcraft-model = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]

crates/audit/README.md

@@ -0,0 +1,31 @@
+# pdfcraft-audit
+
+Layer L4 (may use `edit`): verification tooling, the faux-redaction audit.
+
+```rust
+let findings: Vec<Finding> = audit_redactions(&doc)?;  // page, kind, rect, covered_text
+```
+
+It reports two kinds of finding:
+
+- **faux redaction**: an opaque filled rectangle painted *after* text it overlaps, dark enough
+  against the text's colour (WCAG contrast below 3) to hide it, while the text is still
+  extractable underneath;
+- **unapplied mark**: a Redact annotation that was marked but never applied.
+
+A properly applied redaction removes the text, so it never flags. Page backgrounds, table
+shading and highlights don't either: they're painted before the text, or light against it.
+
+Limits, by design and documented rather than hidden:
+
+- 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.
+
+It fails closed: an undecodable content stream, malformed `/Annots`, form XObjects nested deeper
+than 32 or in a cycle, or a walk past the operator bound is an error, never "no findings".
+
+Surfaces: the `redact_audit` automation tool and `pdfcraft-cli`.

crates/audit/src/cover.rs

@@ -0,0 +1,327 @@
+//! 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. 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
+//! are parsed joined and walked once with a single graphics state — state set in an earlier
+//! stream (a `cm`, a fill color) is still in force in the later ones. Each rectangle records the
+//! position of the fill operator that painted it, as `(content-stream index, operator index in
+//! the joined stream)`; rectangles inside a form XObject carry the `Do` operator's position.
+//! Positions compare lexicographically in paint order.
+
+use pdfcraft_content::{Matrix, Op, Pieces, parse};
+use pdfcraft_cos::{Dict, Document, Object};
+
+use crate::AuditError;
+
+/// Maximum form-XObject nesting followed. Deeper nesting (including a cycle) fails the audit: a
+/// cover drawn below the cut could otherwise go unseen and the page be reported clean.
+const MAX_DEPTH: usize = 32;
+/// Bound on total operators walked per page, so a hostile stream cannot spin forever.
+/// Hitting it fails the audit: a truncated walk must never report "clean".
+const MAX_OPS: usize = 2_000_000;
+
+/// One opaque filled rectangle, in page user space.
+#[derive(Clone, Debug, PartialEq)]
+pub struct FilledRect {
+    /// `[x0, y0, x1, y1]`, normalized so `x0 <= x1` and `y0 <= y1`.
+    pub rect: [f64; 4],
+    /// The fill color as sRGB-ish `[r, g, b]` (CMYK is converted approximately).
+    pub rgb: [f64; 3],
+    /// Paint position: `(content-stream index, operator index in the joined stream)`.
+    /// Rectangles inside a form XObject carry the `Do` operator's position.
+    pub pos: (usize, usize),
+}
+
+#[derive(Clone)]
+struct Gs {
+    ctm: Matrix,
+    fill: [f64; 3],
+    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 }
+    }
+}
+
+struct Walker<'a> {
+    doc: &'a Document,
+    pieces: &'a Pieces,
+    out: Vec<FilledRect>,
+    ops_seen: usize,
+}
+
+impl<'a> Walker<'a> {
+    fn bump(&mut self) -> Result<(), AuditError> {
+        self.ops_seen += 1;
+        if self.ops_seen > MAX_OPS {
+            return Err(AuditError::TooManyOps);
+        }
+        Ok(())
+    }
+
+    /// Walk one operator slice with the given graphics state. `at_do` is the `Do` position to
+    /// stamp on rectangles found inside a form XObject, or `None` at page level (where each
+    /// fill operator's own position is used).
+    fn walk_ops(
+        &mut self,
+        ops: &[Op],
+        gs: &mut Gs,
+        stack: &mut Vec<Gs>,
+        resources: &Dict,
+        depth: usize,
+        at_do: Option<(usize, usize)>,
+    ) -> Result<(), AuditError> {
+        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,
+            // the enclosing `Do`'s position inside a form XObject.
+            let pos = match at_do {
+                Some(p) => p,
+                None => (self.pieces.pieces_of(op).0, i),
+            };
+            match op.op.as_slice() {
+                b"q" => stack.push(gs.clone()),
+                b"Q" => {
+                    if let Some(g) = stack.pop() {
+                        *gs = g;
+                    }
+                    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);
+                    }
+                    // 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()) {
+                        let v = v.clamp(0.0, 1.0);
+                        gs.fill = [v, v, v];
+                    }
+                }
+                b"rg" => {
+                    if let Some([r, g, b]) = op.nums::<3>()
+                        && [r, g, b].iter().all(|v| v.is_finite())
+                    {
+                        gs.fill = [r.clamp(0.0, 1.0), g.clamp(0.0, 1.0), b.clamp(0.0, 1.0)];
+                    }
+                }
+                b"k" => {
+                    if let Some([c, m, y, k]) = op.nums::<4>()
+                        && [c, m, y, k].iter().all(|v| v.is_finite())
+                    {
+                        // Naive CMYK -> RGB; good enough to tell black from white.
+                        let (c, m, y, k) = (c.clamp(0.0, 1.0), m.clamp(0.0, 1.0), y.clamp(0.0, 1.0), k.clamp(0.0, 1.0));
+                        gs.fill = [(1.0 - c) * (1.0 - k), (1.0 - m) * (1.0 - k), (1.0 - y) * (1.0 - k)];
+                    }
+                }
+                b"gs" => {
+                    if let Some(name) = op.name(0) {
+                        gs.alpha = ext_alpha(self.doc, resources, name);
+                    }
+                }
+                b"re" => {
+                    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)
+                        } else {
+                            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) = std::mem::replace(&mut path, Path::Empty).rect()
+                        && gs.alpha >= 1.0
+                    {
+                        self.out.push(FilledRect { rect: r, rgb: gs.fill, pos });
+                    }
+                }
+                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 {
+                            return Err(AuditError::TooDeep);
+                        }
+                        self.walk_xobject(name, gs, resources, depth, pos)?;
+                    }
+                    path = Path::Empty;
+                }
+                _ => {}
+            }
+        }
+        Ok(())
+    }
+
+    /// Follow a form XObject read-only, composing its matrix onto the current CTM. State
+    /// changes inside never leak out; every rectangle found is stamped with the `Do`
+    /// position `pos`.
+    fn walk_xobject(&mut self, name: &[u8], gs: &Gs, resources: &Dict, depth: usize, pos: (usize, usize)) -> Result<(), AuditError> {
+        let xobjects = resources.get(b"XObject").map(|o| self.doc.resolve(o)).and_then(|o| o.as_dict().cloned()).unwrap_or_default();
+        let Some(entry) = xobjects.get(name) else { return Ok(()) };
+        let resolved = self.doc.resolve(entry);
+        let Object::Stream(stream) = &*resolved else { return Ok(()) };
+        let dict = &stream.dict;
+        if dict.name(b"Subtype") != Some(b"Form") {
+            return Ok(());
+        }
+        let matrix = dict
+            .get(b"Matrix")
+            .map(|o| self.doc.resolve(o))
+            .and_then(|o| o.as_array().map(|a| a.to_vec()))
+            .and_then(|a| {
+                let v: Vec<f64> = a.iter().filter_map(|o| self.doc.resolve(o).as_f64()).collect();
+                (v.len() == 6 && v.iter().all(|x| x.is_finite())).then(|| Matrix([v[0], v[1], v[2], v[3], v[4], v[5]]))
+            })
+            .unwrap_or(Matrix::IDENTITY);
+        let sub_resources = dict.get(b"Resources").map(|o| self.doc.resolve(o)).and_then(|o| o.as_dict().cloned()).unwrap_or_default();
+        // A form stream that cannot be decoded fails the audit: it might hide a cover.
+        let data = stream.decoded_strict()?;
+        let ops = parse(&data).ops;
+        // The XObject matrix maps form space into the user space active at `Do`.
+        let mut sub_gs = gs.clone();
+        sub_gs.ctm = matrix.then(&gs.ctm);
+        let mut sub_stack = Vec::new();
+        self.walk_ops(&ops, &mut sub_gs, &mut sub_stack, &sub_resources, depth + 1, Some(pos))
+    }
+}
+
+/// 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
+        .get(b"ExtGState")
+        .map(|o| doc.resolve(o))
+        .and_then(|o| o.as_dict().cloned())
+        .and_then(|d| d.get(name).map(|o| doc.resolve(o)))
+        .and_then(|o| o.as_dict().cloned())
+        .and_then(|d| d.get(b"ca").map(|o| doc.resolve(o)).and_then(|o| o.as_f64()));
+    alpha.filter(|a| a.is_finite()).map(|a| a.clamp(0.0, 1.0)).unwrap_or(1.0)
+}
+
+/// Every opaque filled rectangle drawn by a page's content (and its form XObjects), with paint
+/// positions. A page's content streams are walked once, joined, with one graphics state, so
+/// state set in an earlier stream is still in force in the later ones. Any content stream that
+/// cannot be decoded is an audit failure, never an empty result.
+pub fn filled_rects(doc: &Document, page: &Dict) -> Result<Vec<FilledRect>, AuditError> {
+    let resources = page.get(b"Resources").map(|o| doc.resolve(o)).and_then(|o| o.as_dict().cloned()).unwrap_or_default();
+    let contents: Vec<Object> = match page.get(b"Contents") {
+        None => Vec::new(),
+        Some(c) => match &*doc.resolve(c) {
+            Object::Array(a) => a.clone(),
+            _ => vec![c.clone()],
+        },
+    };
+    let mut streams = Vec::with_capacity(contents.len());
+    for c in &contents {
+        if let Object::Stream(s) = &*doc.resolve(c) {
+            streams.push(s.decoded_strict()?);
+        }
+    }
+    let pieces = Pieces::join(&streams);
+    let parsed = pieces.parse();
+    let mut w = Walker { doc, pieces: &pieces, out: Vec::new(), ops_seen: 0 };
+    let mut gs = Gs::default();
+    let mut stack = Vec::new();
+    w.walk_ops(&parsed.ops, &mut gs, &mut stack, &resources, 0, None)?;
+    Ok(w.out)
+}

crates/audit/src/lib.rs

@@ -0,0 +1,192 @@
+//! Verification tooling: audit a document for faux redactions.
+//!
+//! [`audit_redactions`] finds *faux redactions* — opaque filled rectangles drawn over text
+//! that is still extractable underneath — and redaction annotations that were marked but
+//! never applied. A properly applied redaction removes the text, so it never flags.
+//!
+//! A rectangle counts as a cover only when it was painted strictly *after* the text it
+//! overlaps, and only when it is dark enough against the text's color to make the text
+//! unreadable (WCAG contrast below 3.0). Page backgrounds, table shading and highlight
+//! marks are therefore not flagged.
+//!
+//! Detection limits (documented, not hidden): only `re` rectangles closed by a fill operator
+//! are considered — arbitrary filled paths, shadings and patterns are not; a rectangle drawn
+//! with a translucent ExtGState (`/ca < 1`) is not flagged; annotation rectangles are compared
+//! in unrotated user space, so pages with `/Rotate` may misalign; covers inside form XObjects
+//! are found, but only text drawn directly in the page content is checked under them, so text
+//! inside a form XObject is not audited.
+//!
+//! The audit fails closed: any content that cannot be read (an undecodable content stream,
+//! malformed annotations, form XObjects nested deeper than 32 or in a cycle) is an error, never
+//! an empty finding list.
+
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+use pdfcraft_cos::{Dict, Document};
+use pdfcraft_edit::TextLine;
+
+mod cover;
+
+#[cfg(test)]
+mod tests;
+
+/// What the audit found.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum FindingKind {
+    /// An opaque filled rectangle covers text that is still extractable.
+    CoveredText,
+    /// A `/Redact` annotation was placed but never applied: the text is untouched.
+    UnappliedMark,
+}
+
+impl FindingKind {
+    pub fn id(self) -> &'static str {
+        match self {
+            FindingKind::CoveredText => "covered-text",
+            FindingKind::UnappliedMark => "unapplied-mark",
+        }
+    }
+}
+
+/// One audit finding.
+#[derive(Clone, Debug, PartialEq)]
+pub struct AuditFinding {
+    /// 0-based page index.
+    pub page: usize,
+    pub kind: FindingKind,
+    /// The covering rectangle (or the mark's rectangle), in page user space.
+    pub rect: [f64; 4],
+    /// The extractable text the cover hides (possibly empty when nothing decodable remains).
+    pub covered_text: String,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum AuditError {
+    #[error("page {0}: {1}")]
+    Text(usize, String),
+    #[error("content walk exceeded the operator bound")]
+    TooManyOps,
+    #[error("form XObjects nest deeper than the audit follows")]
+    TooDeep,
+    #[error("page has a malformed /Annots entry")]
+    BadAnnots,
+    #[error(transparent)]
+    Cos(#[from] pdfcraft_cos::CosError),
+    #[error(transparent)]
+    Edit(#[from] pdfcraft_edit::EditError),
+}
+
+/// Fraction of a text line's area that must lie under a cover to count as hidden.
+const COVER_FRACTION: f64 = 0.4;
+/// WCAG contrast ratio below which the text is unreadable against the cover.
+const COVER_CONTRAST: f64 = 3.0;
+
+/// Audit every page for faux redactions and unapplied redaction marks. Fails closed: any
+/// content that cannot be decoded is returned as an error, never as an empty finding list.
+pub fn audit_redactions(doc: &Document) -> Result<Vec<AuditFinding>, AuditError> {
+    let mut out = Vec::new();
+    for (n, page) in pdfcraft_model::pages(doc).iter().enumerate() {
+        let lines = pdfcraft_edit::text_lines(doc, n).map_err(|e| AuditError::Text(n, e.to_string()))?;
+        // 1. Opaque filled rectangles over extractable text.
+        for r in cover::filled_rects(doc, &page.dict)? {
+            let mut covered = String::new();
+            for line in &lines {
+                if is_cover(&r, line) {
+                    if !covered.is_empty() {
+                        covered.push(' ');
+                    }
+                    covered.push_str(line.text.trim());
+                }
+            }
+            if !covered.trim().is_empty() {
+                out.push(AuditFinding { page: n, kind: FindingKind::CoveredText, rect: r.rect, covered_text: covered });
+            }
+        }
+        // 2. Redact annotations that were never applied.
+        for annot in annots(doc, &page.dict)? {
+            let mut covered = String::new();
+            for line in &lines {
+                if covers(&annot, &line.rect) {
+                    if !covered.is_empty() {
+                        covered.push(' ');
+                    }
+                    covered.push_str(line.text.trim());
+                }
+            }
+            if !covered.trim().is_empty() {
+                out.push(AuditFinding { page: n, kind: FindingKind::UnappliedMark, rect: annot, covered_text: covered });
+            }
+        }
+    }
+    Ok(out)
+}
+
+/// A filled rectangle is a faux-redaction cover for a text line iff it was painted strictly
+/// after the line, overlaps it substantially, and is dark enough against the line's color to
+/// make the text unreadable. Light covers (table shading, highlights) over dark text fail the
+/// contrast check and are not flagged.
+fn is_cover(rect: &cover::FilledRect, line: &TextLine) -> bool {
+    rect.pos > line.paint_pos() && covers(&rect.rect, &line.rect) && contrast(line.color, rect.rgb) < COVER_CONTRAST
+}
+
+/// Does `cover` hide a substantial part of `line`?
+fn covers(cover: &[f64; 4], line: &[f64; 4]) -> bool {
+    let ix0 = cover[0].max(line[0]);
+    let iy0 = cover[1].max(line[1]);
+    let ix1 = cover[2].min(line[2]);
+    let iy1 = cover[3].min(line[3]);
+    if ix1 <= ix0 || iy1 <= iy0 {
+        return false;
+    }
+    let line_area = (line[2] - line[0]).max(0.0) * (line[3] - line[1]).max(0.0);
+    if line_area <= 0.0 {
+        return false;
+    }
+    (ix1 - ix0) * (iy1 - iy0) / line_area >= COVER_FRACTION
+}
+
+/// WCAG 2.x relative luminance of an sRGB triple.
+fn luminance(rgb: [f64; 3]) -> f64 {
+    let lin = rgb.map(|c| {
+        let c = c.clamp(0.0, 1.0);
+        if c <= 0.03928 { c / 12.92 } else { ((c + 0.055) / 1.055).powf(2.4) }
+    });
+    0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+}
+
+/// WCAG contrast ratio between two sRGB colors: 1.0 (identical) to 21.0 (black on white).
+fn contrast(a: [f64; 3], b: [f64; 3]) -> f64 {
+    let (l1, l2) = (luminance(a), luminance(b));
+    let (hi, lo) = if l1 > l2 { (l1, l2) } else { (l2, l1) };
+    (hi + 0.05) / (lo + 0.05)
+}
+
+/// Rectangles of `/Redact` annotations on a page (unrotated user space). A missing `/Annots`
+/// means no marks; a malformed one fails the audit rather than silently passing.
+fn annots(doc: &Document, page: &Dict) -> Result<Vec<[f64; 4]>, AuditError> {
+    let Some(a) = page.get(b"Annots") else { return Ok(Vec::new()) };
+    let resolved = doc.resolve(a);
+    let items: Vec<pdfcraft_cos::Object> = match &*resolved {
+        pdfcraft_cos::Object::Array(items) => items.clone(),
+        // A missing /Annots means no marks; a malformed one fails the audit.
+        _ => return Err(AuditError::BadAnnots),
+    };
+    let mut out = Vec::new();
+    for a in &items {
+        let dict = match &*doc.resolve(a) {
+            pdfcraft_cos::Object::Dict(d) => d.clone(),
+            _ => continue,
+        };
+        if dict.name(b"Subtype") != Some(b"Redact") {
+            continue;
+        }
+        let v: Vec<f64> = match dict.get(b"Rect") {
+            None => continue,
+            Some(r) => doc.resolve(r).as_array().map(|arr| arr.iter().filter_map(|o| doc.resolve(o).as_f64()).collect()).unwrap_or_default(),
+        };
+        if v.len() == 4 && v.iter().all(|x| x.is_finite()) {
+            out.push([v[0].min(v[2]), v[1].min(v[3]), v[0].max(v[2]), v[1].max(v[3])]);
+        }
+    }
+    Ok(out)
+}

crates/audit/src/tests.rs

@@ -0,0 +1,274 @@
+//! Tests build their own tiny PDFs in code (contributor-original fixtures): no binary files,
+//! no Adobe material, exact xref offsets computed by the builder below.
+
+use std::sync::Arc;
+
+use pdfcraft_cos::Document;
+
+use crate::{FindingKind, audit_redactions};
+
+/// Minimal PDF assembler: objects are numbered 1..=n in order.
+struct Builder {
+    objects: Vec<Vec<u8>>,
+}
+
+impl Builder {
+    fn new() -> Self {
+        Builder { objects: Vec::new() }
+    }
+
+    fn add(&mut self, body: &str) -> usize {
+        self.objects.push(body.as_bytes().to_vec());
+        self.objects.len()
+    }
+
+    fn add_stream(&mut self, data: &[u8]) -> usize {
+        self.add_stream_with(data, "")
+    }
+
+    fn add_stream_with(&mut self, data: &[u8], dict_extra: &str) -> usize {
+        let mut body = format!("<< /Length {} {dict_extra} >>\nstream\n", data.len()).into_bytes();
+        body.extend_from_slice(data);
+        body.extend_from_slice(b"\nendstream");
+        self.objects.push(body);
+        self.objects.len()
+    }
+
+    fn build(self) -> Vec<u8> {
+        let mut out = b"%PDF-1.7\n".to_vec();
+        let mut offsets = Vec::new();
+        for (i, obj) in self.objects.iter().enumerate() {
+            offsets.push(out.len());
+            out.extend_from_slice(format!("{} 0 obj\n", i + 1).as_bytes());
+            out.extend_from_slice(obj);
+            out.extend_from_slice(b"\nendobj\n");
+        }
+        let xref_at = out.len();
+        let n = self.objects.len() + 1;
+        out.extend_from_slice(format!("xref\n0 {n}\n").as_bytes());
+        out.extend_from_slice(b"0000000000 65535 f \n");
+        for off in offsets {
+            out.extend_from_slice(format!("{off:010} 00000 n \n").as_bytes());
+        }
+        out.extend_from_slice(b"trailer\n<< ");
+        out.extend_from_slice(format!("/Size {n} /Root 1 0 R").as_bytes());
+        out.extend_from_slice(b" >>\nstartxref\n");
+        out.extend_from_slice(format!("{xref_at}\n").as_bytes());
+        out.extend_from_slice(b"%%EOF\n");
+        out
+    }
+}
+
+const FONT: &str = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>";
+
+/// One page with `content` as its stream; `page_extra` is appended inside the page dict.
+fn one_page(content: &[u8], page_extra: &str) -> Vec<u8> {
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    let stream_num = 4;
+    b.add(&format!(
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents {stream_num} 0 R /Resources << /Font << /F1 5 0 R >> >> {page_extra} >>"
+    ));
+    b.add_stream(content);
+    b.add(FONT);
+    b.build()
+}
+
+/// One page with two content streams (`/Contents [4 0 R 5 0 R]`).
+fn two_streams(s1: &[u8], s2: &[u8]) -> Vec<u8> {
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    b.add("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents [4 0 R 5 0 R] /Resources << /Font << /F1 6 0 R >> >> >>");
+    b.add_stream(s1);
+    b.add_stream(s2);
+    b.add(FONT);
+    b.build()
+}
+
+/// One page whose content stream claims `/FlateDecode` but holds garbage: decoding must fail.
+fn bad_filter_page() -> Vec<u8> {
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    b.add("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>");
+    b.add_stream_with(b"this is not deflated data", "/Filter /FlateDecode");
+    b.add(FONT);
+    b.build()
+}
+
+fn open(bytes: Vec<u8>) -> Document {
+    Document::open(Arc::new(bytes)).expect("test pdf must open")
+}
+
+#[test]
+fn faux_redaction_is_found() {
+    let content = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n0 g\n100 688 220 32 re f\n";
+    let findings = audit_redactions(&open(one_page(content, ""))).expect("audit must run");
+    assert_eq!(findings.len(), 1, "{findings:?}");
+    let f = &findings[0];
+    assert_eq!(f.page, 0);
+    assert_eq!(f.kind, FindingKind::CoveredText);
+    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";
+    let findings = audit_redactions(&open(one_page(content, ""))).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn black_box_without_text_is_not_a_finding() {
+    // A filled rectangle with no text under it is decoration, not a faux redaction.
+    let content = b"BT /F1 24 Tf 100 100 Td (far away) Tj ET\n0 g\n400 600 100 40 re f\n";
+    let findings = audit_redactions(&open(one_page(content, ""))).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn translucent_cover_is_not_flagged() {
+    // A rectangle drawn with a translucent ExtGState does not hide the text.
+    let content = b"/GS1 gs\nBT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n0 g\n100 688 220 32 re f\n";
+    let page_extra = "/Resources << /Font << /F1 5 0 R >> /ExtGState << /GS1 6 0 R >> >>";
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    b.add(&format!("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R {page_extra} >>"));
+    b.add_stream(content);
+    b.add(FONT);
+    b.add("<< /Type /ExtGState /ca 0.5 >>");
+    let findings = audit_redactions(&open(b.build())).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn unapplied_redact_mark_is_found() {
+    let content = b"BT /F1 24 Tf 100 700 Td (DO NOT SHARE) Tj ET\n";
+    let page_extra = "/Annots [6 0 R]";
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    b.add(&format!("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> {page_extra} >>"));
+    b.add_stream(content);
+    b.add(FONT);
+    b.add("<< /Type /Annot /Subtype /Redact /Rect [95 685 305 725] /C [1 0 0] >>");
+    let findings = audit_redactions(&open(b.build())).expect("audit must run");
+    assert_eq!(findings.len(), 1, "{findings:?}");
+    assert_eq!(findings[0].kind, FindingKind::UnappliedMark);
+    assert!(findings[0].covered_text.contains("DO NOT SHARE"));
+}
+
+#[test]
+fn background_before_text_is_not_flagged() {
+    // An opaque dark rectangle painted *before* the text is a background, not a cover.
+    let content = b"0 g\n100 688 220 32 re f\nBT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n";
+    let findings = audit_redactions(&open(one_page(content, ""))).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn light_shading_after_text_is_not_flagged() {
+    // Light table-style shading painted after the text leaves it readable: not a cover.
+    let content = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n0.9 g\n100 688 220 32 re f\n";
+    let findings = audit_redactions(&open(one_page(content, ""))).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn graphics_state_carries_across_streams() {
+    // The first stream sets a white fill after the text; the second stream's rectangle over
+    // the text is therefore white, not the default black: no finding. Without the carry fix
+    // the rectangle would default to black and flag.
+    let s1 = b"BT /F1 24 Tf 100 700 Td (SECRET DATA 123) Tj ET\n1 g\n";
+    let s2 = b"100 688 220 32 re f\n";
+    let findings = audit_redactions(&open(two_streams(s1, s2))).expect("audit must run");
+    assert!(findings.is_empty(), "{findings:?}");
+}
+
+#[test]
+fn audit_fails_closed_on_undecodable_stream() {
+    // A content stream that cannot be decoded is an audit error, never an empty finding list.
+    let err = audit_redactions(&open(bad_filter_page())).expect_err("audit must fail closed");
+    let msg = err.to_string();
+    assert!(msg.contains("decoded"), "unexpected error: {msg}");
+}
+
+/// A form XObject that draws itself nests without end. The walk can't follow it to the bottom, so
+/// the audit fails rather than report the page clean with a possible cover left unseen.
+#[test]
+fn self_drawing_form_fails_the_audit() {
+    let mut b = Builder::new();
+    b.add("<< /Type /Catalog /Pages 2 0 R >>");
+    b.add("<< /Type /Pages /Kids [3 0 R] /Count 1 >>");
+    b.add("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 6 0 R >> /XObject << /X 5 0 R >> >> >>");
+    b.add_stream(b"BT /F1 24 Tf 100 700 Td (SECRET) Tj ET\n/X Do\n");
+    b.add_stream_with(
+        b"0 g\n100 688 220 32 re f\n/X Do\n",
+        "/Type /XObject /Subtype /Form /BBox [0 0 612 792] /Resources << /XObject << /X 5 0 R >> >>",
+    );
+    b.add(FONT);
+    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):
@@ -52,6 +81,23 @@ or fill colour. Names, rectangles and rotations require the single-field form. R
 
 Implemented: `initialize` (protocol 2025-06-18, 2025-03-26, 2024-11-05), `ping`, `tools/list` (with `readOnlyHint`/`destructiveHint` annotations), `tools/call` (JSON results also returned as `structuredContent`; images as `image/png`), and `resources/list`, `resources/templates/list` and `resources/read`. The resources expose the open documents read-only: `pdfcraft://doc/{doc}/info` (JSON), `…/text`, `…/page/{page}/text` and `…/page/{page}/image{?dpi}` (PNG, 1–600 dpi). Tool failures come back as `isError: true` results, so the agent can read and recover from them.
 
+### From an installed release
+
+The release packages ship `pdfcraft-cli` alongside the desktop app, so no build is needed:
+
+| Install | CLI |
+|---|---|
+| Windows (MSI) | `C:\Program Files\PdfCraft\pdfcraft-cli.exe` by default (wherever you installed it otherwise), not on `PATH` |
+| Linux (deb, rpm) | `/usr/bin/pdfcraft-cli` |
+| macOS | the separate `pdfcraft-cli-<version>-macos-<arch>.zip` release asset (the `.app` holds only the desktop app) |
+
+```sh
+# Windows, default install folder
+claude mcp add pdfcraft -- "C:\Program Files\PdfCraft\pdfcraft-cli.exe" mcp --root <dir>
+# Linux, or macOS with the CLI unzipped onto PATH
+claude mcp add pdfcraft -- pdfcraft-cli mcp --root <dir>
+```
+
 ## Adding a tool
 
 1. Add the engine capability first, with its tests (the tool is a thin adapter).
@@ -68,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
@@ -92,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) {
@@ -84,13 +275,129 @@ impl Automation {
         let r = doc.accessibility_check(&o).ok_or_else(|| failed("the document can't be read for checking"))?;
         let path = self.resolve(a.str("path")?, true)?;
         let (y, m, d) = self.session.today();
-        let html = pdfcraft_engine::a11y::report_html(&r, &doc.name, &format!("{y}-{m:02}-{d:02}"));
+        // A script's report is in English, like the rest of what the tools say and answer with.
+        let words = pdfcraft_engine::a11y::in_english;
+        let html = pdfcraft_engine::a11y::report_html(&r, &doc.name, &format!("{y}-{m:02}-{d:02}"), "en", &words);
         write_atomic(&path, html.as_bytes())?;
         let mut out = report_json(&r);
         out["path"] = json!(path.to_string_lossy());
         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:?}")))?;
@@ -133,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;
@@ -193,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 }))
@@ -270,8 +634,8 @@ 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)")))?;
-        let bytes = self.doc(a)?.export_office(format);
+            .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() }))
     }
@@ -298,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;
@@ -514,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/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),
@@ -105,9 +115,15 @@ impl Automation {
             None => PAPERS[0].1,
             Some(p) => PAPERS
                 .iter()
-                .find(|(n, _)| n.eq_ignore_ascii_case(p) || n.replace("US ", "").eq_ignore_ascii_case(p))
+                .find(|(n, _)| {
+                    n.eq_ignore_ascii_case(p)
+                        || n.replace("US ", "").eq_ignore_ascii_case(p)
+                        || n.split(" (").next().is_some_and(|name| name.eq_ignore_ascii_case(p))
+                })
                 .map(|x| x.1)
-                .ok_or_else(|| bad(format!("unknown paper {p:?} (Letter, Legal, Tabloid, A3, A4, A5)")))?,
+                .ok_or_else(|| {
+                    bad(format!("unknown paper {p:?}; choose one of {}", PAPERS.iter().map(|(name, _)| *name).collect::<Vec<_>>().join(", ")))
+                })?,
         };
         let settings = print::Settings { pages, paper, orientation, layout, content };
         let sizes: Vec<(f64, f64)> = self.doc(a)?.info.pages.iter().map(|p| (p.width as f64, p.height as f64)).collect();
@@ -126,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();
@@ -163,6 +172,22 @@ impl Automation {
         Ok(json!({ "total": total, "categories": items }))
     }
 
+    pub(crate) fn doc_audit_redactions(&self, a: &Args) -> Result<Value> {
+        let findings = self.doc(a)?.audit_redactions().map_err(ToolError::Failed)?;
+        let items: Vec<Value> = findings
+            .into_iter()
+            .map(|f| {
+                json!({
+                    "page": f.page + 1,
+                    "kind": f.kind.id(),
+                    "rect": f.rect,
+                    "covered_text": f.covered_text,
+                })
+            })
+            .collect();
+        Ok(json!({ "findings": items, "count": items.len() }))
+    }
+
     pub(crate) fn doc_remove_hidden(&mut self, a: &Args) -> Result<Value> {
         let edit = match a.get("categories") {
             None => Edit::Sanitize,

crates/automation/src/signing.rs

@@ -70,7 +70,8 @@ impl Automation {
             "timestamp_time": s.timestamp_time.map(|t| t.to_string()),
             "modification": modification,
             "changes": changes,
-            "details": s.details,
+            // Scripts read this, so the sentences stay in English, whatever the interface reads in.
+            "details": s.details.iter().map(|d| d.message.clone()).collect::<Vec<_>>(),
         }))
     }
 
@@ -171,6 +172,11 @@ impl Automation {
             }),
             Some(v) => Some(v.as_u64().filter(|n| (1..=3).contains(n)).ok_or_else(|| bad("certify must be 1, 2 or 3"))? as u8),
         };
+        let graphic = match a.get("graphic") {
+            None | Some(Value::Null) => None,
+            Some(g) if rect.is_none() && field.is_none() => return Err(bad(format!("graphic {g} needs a visible signature: pass rect or field"))),
+            Some(g) => Some(self.signature_graphic(g)?),
+        };
         let out = self.resolve(a.str("out")?, true)?;
         let opts = SignOptions {
             field,
@@ -180,9 +186,14 @@ impl Automation {
             location: a.opt_str("location")?.map(str::to_string),
             contact: a.opt_str("contact")?.map(str::to_string),
             certify,
+            graphic,
             ..SignOptions::default()
         };
-        let signed = self.session.sign(doc_id, &id, opts).map_err(failed)?;
+        let signed = self.session.sign(doc_id, &id, opts).map_err(|e| match e {
+            // A graphic the signer refuses is the caller's to fix.
+            pdfcraft_engine::EditError::Sign(m) if m.starts_with("the signature graphic") => bad(m),
+            e => failed(e),
+        })?;
         write_atomic(&out, &signed)?;
         let path = out.to_string_lossy().into_owned();
         self.session.mark_signed(doc_id, signed.clone(), Some(path.clone())).map_err(failed)?;
@@ -191,6 +202,41 @@ impl Automation {
         Ok(json!({ "path": path, "bytes": signed.len(), "signature": newest.map(|s| self.sig_json(a, &s)).transpose()? }))
     }
 
+    /// `{"image": path}` (PNG or JPEG), `{"text": name}` (typed in the script font) or
+    /// `{"strokes": [[[x, y], …], …]}` (y up; the drawing pad is 1 wide).
+    fn signature_graphic(&self, g: &Value) -> Result<sign::Graphic> {
+        let kinds = "graphic must be an object with exactly one of image (a PNG or JPEG path), text, or strokes";
+        let Some(o) = g.as_object().filter(|o| o.len() == 1) else { return Err(bad(kinds)) };
+        if let Some(path) = o.get("image") {
+            let path = self.resolve(path.as_str().ok_or_else(|| bad("graphic.image must be a path"))?, false)?;
+            let file = std::fs::File::open(&path).map_err(|e| bad(format!("graphic.image {}: {e}", path.display())))?;
+            return Ok(pdfcraft_engine::SignatureImage::read(file).map_err(|e| bad(e.to_string()))?.graphic());
+        }
+        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)",
+                    pdfcraft_engine::MAX_SIGNATURE_CHARS
+                ))
+            });
+        }
+        if let Some(strokes) = o.get("strokes") {
+            let strokes: Vec<Vec<[f64; 2]>> =
+                serde_json::from_value(strokes.clone()).map_err(|e| bad(format!("graphic.strokes must be strokes of [x, y] points: {e}")))?;
+            return Ok(sign::Graphic::Strokes(strokes));
+        }
+        Err(bad(kinds))
+    }
+
     pub(crate) fn sign_trust(&mut self, a: &Args) -> Result<Value> {
         let mut certs: Vec<Certificate> =
             if a.opt_bool("clear")?.unwrap_or(false) { Vec::new() } else { self.session.trusted_certificates().to_vec() };

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,12 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc"],
             )),
-        t("text_find", "Find text", "Find a phrase (case-insensitive, whitespace-normalised) and return each match with its page and line rectangles in points (origin top-left).")
+        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)." } }), &["doc", "query"])),
+            .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.")
             .cmd("page.rotate")
             .with(schema(
@@ -182,6 +197,18 @@ pub fn tools() -> Vec<ToolDef> {
                 }),
                 &["doc", "degrees"],
             )),
+        t("page_enhance_camera", "Enhance camera image", "Straighten a photographed document (Scan & OCR ▸ Enhance ▸ Camera image): the part of the page inside the four corners (x1, y1, … x4, y4 in top-left-origin points, any order, a convex quadrilateral; when omitted, the document's edges are found automatically, or an error says they could not be) is warped to an upright rectangle that replaces what the page shows, at the page picture's own resolution (at most 600 dpi). mode is how it looks: original, colour (default), greyscale or bw (black and white, stored losslessly). level (0–100, default 0) then cleans the photo up: even lighting so the paper turns white (casts, shadows, dark edges), more contrast, and from 60 no isolated specks; colour ink stays colour. For bw the level is the threshold (higher keeps fainter strokes black). The page's comments, links and bookmarks stay. Undoable.")
+            .cmd("ocr.enhance_camera")
+            .with(schema(
+                json!({
+                    "doc": doc(),
+                    "page": { "type": "integer", "minimum": 1 },
+                    "corners": { "type": "array", "items": { "type": "number" }, "minItems": 8, "maxItems": 8 },
+                    "level": { "type": "integer", "minimum": 0, "maximum": 100 },
+                    "mode": { "type": "string", "enum": ["original", "colour", "greyscale", "bw"] },
+                }),
+                &["doc", "page"],
+            )),
         t("page_delete", "Delete pages", "Delete pages. Undoable until saved.")
             .destructive()
             .cmd("page.delete")
@@ -205,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 PDFs, in order, into one (bookmarks are kept under one entry per file). pages optionally chooses each file's pages, in step with paths: a range such as \"1-3, 6\" or null for all pages. passwords, also in step with paths, opens encrypted files (the open password, or the permissions password where a file's security doesn't allow copying pages; null for none). The result is not encrypted. Passwords are never echoed back. 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!({
@@ -213,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,
                 }),
@@ -222,7 +250,7 @@ pub fn tools() -> Vec<ToolDef> {
             .cmd("create.multiple")
             .with(schema(
                 json!({
-                    "paths": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": pdfcraft_engine::MAX_CREATE_FILES },
+                    "paths": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
                     "mode": { "type": "string", "enum": ["combine", "separate"] },
                     "pages": { "type": "array", "items": { "type": ["string", "null"] } },
                     "out": save_out.clone(),
@@ -289,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.")
@@ -331,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",
@@ -374,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()
@@ -385,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!({
@@ -394,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)"),
@@ -435,6 +465,13 @@ pub fn tools() -> Vec<ToolDef> {
             }),
             &["doc"],
         )),
+        t(
+            "doc_audit_redactions",
+            "Audit faux redactions",
+            "Find faux redactions: opaque filled rectangles painted over text that is still extractable, and /Redact annotations that were marked but never applied. Paint-order and colour-aware: a rectangle counts only when painted after the text and dark enough to hide it (page backgrounds and light shading are not flagged). Each finding reports the 1-based page, the kind (covered-text or unapplied-mark), the rectangle, and the hidden text. Fails closed: unreadable content is an error, never a clean bill. A properly applied redaction removes the text and never flags.",
+        )
+        .ro()
+        .with(schema(json!({ "doc": doc() }), &["doc"])),
         t("printers", "List printers", "The printers the system's print spooler knows (CUPS on macOS and Linux), with the default marked.").ro().with(schema(json!({}), &[])),
         t("printer_options", "List printer options", "A printer driver's own job options (CUPS: from its PPD), such as the paper tray, paper type or finishing: key, label, group, default and choices. Pass chosen values to doc_print as options. Empty on Windows, where the driver's preferences window holds them.")
             .ro()
@@ -442,7 +479,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "doc_print",
             "Print",
-            "Print with Acrobat's Print dialog options, or save the print-ready PDF. pages: a range such as \"1-3, 6, 9-\" (page labels allowed; default all); subset odd/even; reverse. layout: fit (default), actual, shrink, custom (scale %), multiple (per_sheet 2/4/6/9/16, order, border, auto_rotate; cut-stack order arranges single-sided sheets for cutting into piles and stacking left to right, top to bottom, keeping sheet order within each pile; duplex must be off), booklet (booklet_subset both/front/back, binding left/right), poster (scale %, overlap pt, cut_marks). orientation auto/portrait/landscape; comments_forms document / document-and-markups (default) / document-and-stamps / form-fields-only; paper Letter/Legal/Tabloid/A3/A4/A5. Then path (save) or printer (a name or \"default\") with copies, collate, duplex off/long-edge/short-edge, grayscale, and options (driver options from printer_options, CUPS).",
+            "Print with Acrobat's Print dialog options, or save the print-ready PDF. pages: a range such as \"1-3, 6, 9-\" (page labels allowed; default all); subset odd/even; reverse. layout: fit (default), actual, shrink, custom (scale %), multiple (per_sheet 2/4/6/9/16, order, border, auto_rotate; cut-stack order arranges single-sided sheets for cutting into piles and stacking left to right, top to bottom, keeping sheet order within each pile; duplex must be off), booklet (booklet_subset both/front/back, binding left/right), poster (scale %, overlap pt, cut_marks). orientation auto/portrait/landscape; comments_forms document / document-and-markups (default) / document-and-stamps / form-fields-only; paper Letter/Legal/Tabloid, ARCH A/B/C/D/E1/E, ANSI C/D/E, or A0/A1/A2/A3/A4/A5 (short names or full preset labels); use layout actual for 100% in the print-ready PDF; printer drivers may still substitute paper or scale. Then path (save) or printer (a name or \"default\") with copies, collate, duplex off/long-edge/short-edge, grayscale, and options (driver options from printer_options, CUPS).",
         )
         .with(schema(
             json!({
@@ -479,7 +516,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "page_add_text",
             "Add text to a page",
-            "Add text as page content (not a comment). Place it with at [x, y] (top-left, points from the top-left of the displayed page) and width (wrap width, default 200), or rect. Newlines start new lines; long lines wrap. Style: font helvetica/times/courier, size, bold, italic, color (#RRGGBB or a name), align left/center/right. It stays editable with content_update. Undoable.",
+            "Add text as page content (not a comment). Place it with at [x, y] (top-left, points from the top-left of the displayed page) and width (wrap width, default 200), or rect. Newlines start new lines; long lines wrap. Style: font helvetica/times/courier, size, bold, italic, color (#RRGGBB or a name), align left/center/right. Text must be Western European (WinAnsi) characters; others are refused. It stays editable with content_update. Undoable.",
         )
         .cmd("edit.text")
         .with(schema(
@@ -524,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(
@@ -550,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.")
@@ -579,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!({
@@ -644,7 +686,7 @@ pub fn tools() -> Vec<ToolDef> {
             .ro()
             .cmd("sign.digital")
             .with(schema(json!({}), &[])),
-        t("sign_document", "Sign a document", "Sign with a digital ID (a .p12/.pfx path, or on macOS a Keychain identity: \"keychain:<common name or fingerprint>\" from sign_keychain_ids, or on Windows a store identity: \"windows:<common name or fingerprint>\" from sign_windows_ids) and save the signed file to `out` (signing always saves, as in Acrobat; the document then shows the signed file). Sign an existing empty signature field (`field`), or a new one on `page` at `rect` (omit rect for an invisible signature). certify: no_changes, form_fill or comments makes a certification signature. PAdES B-B, SHA-256 (SHA-384 for P-384 keys).")
+        t("sign_document", "Sign a document", "Sign with a digital ID (a .p12/.pfx path, or on macOS a Keychain identity: \"keychain:<common name or fingerprint>\" from sign_keychain_ids, or on Windows a store identity: \"windows:<common name or fingerprint>\" from sign_windows_ids) and save the signed file to `out` (signing always saves, as in Acrobat; the document then shows the signed file). Sign an existing empty signature field (`field`), or a new one on `page` at `rect` (omit rect for an invisible signature). certify: no_changes, form_fill or comments makes a certification signature. graphic shows a picture where the signer's name would be large (Acrobat: Configure Signature Appearance): {\"image\": path} (PNG or JPEG), {\"text\": name} (typed in the Fill & Sign script font) or {\"strokes\": [[[x, y], …], …]} (y up, the drawing pad 1 wide); it needs a visible signature. PAdES B-B, SHA-256 (SHA-384 for P-384 keys).")
             .cmd("sign.digital")
             .with(schema(
                 json!({
@@ -658,6 +700,17 @@ pub fn tools() -> Vec<ToolDef> {
                     "location": { "type": "string" },
                     "contact": { "type": "string" },
                     "certify": { "type": "string", "enum": ["no_changes", "form_fill", "comments"] },
+                    "graphic": {
+                        "type": "object",
+                        "description": "Exactly one of image, text or strokes.",
+                        "properties": {
+                            "image": { "type": "string", "description": "A PNG or JPEG file." },
+                            "text": { "type": "string", "description": "Typed in the script font." },
+                            "strokes": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } },
+                        },
+                        "minProperties": 1,
+                        "maxProperties": 1,
+                    },
                     "out": { "type": "string", "description": "Where to save the signed document." },
                 }),
                 &["doc", "id", "out"],
@@ -677,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(
@@ -764,7 +830,7 @@ pub fn tools() -> Vec<ToolDef> {
             }),
             &["doc"],
         )),
-        t("doc_watermark", "Add watermark", "Add a watermark to pages: text, or a picture from `file` (an image, or page `file_page` of a PDF) at `scale` of the page (default 0.5); rotated (degrees counter-clockwise, default 45), semi-transparent (opacity 0–1, default 0.5), text fitted to the page unless font_size is given, on top unless behind: true. replace: true swaps out existing ones. Undoable.")
+        t("doc_watermark", "Add watermark", "Add a watermark to pages: text, or a picture from `file` (an image, or page `file_page` of a PDF) at `scale` of the page (default 0.5); rotated (degrees counter-clockwise, default 45), semi-transparent (opacity 0–1, default 0.5), text fitted to the page unless font_size is given, on top unless behind: true; moved from the page centre by `offset_x` (right) and `offset_y` (up) points (default 0). replace: true swaps out existing ones. Undoable.")
             .cmd("edit.watermark")
             .with(schema(
                 json!({
@@ -779,6 +845,8 @@ pub fn tools() -> Vec<ToolDef> {
                     "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
                     "rotation": { "type": "number" },
                     "behind": { "type": "boolean" },
+                    "offset_x": { "type": "number", "description": "Points right of the page centre (negative: left)." },
+                    "offset_y": { "type": "number", "description": "Points above the page centre (negative: below)." },
                     "replace": { "type": "boolean" },
                 }),
                 &["doc"],
@@ -805,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(
@@ -832,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).")
@@ -841,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"])),
@@ -863,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"])),
@@ -917,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!({
@@ -925,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!({
@@ -937,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"],
             )),
@@ -961,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 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(
@@ -971,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" },
@@ -983,7 +1110,7 @@ pub fn tools() -> Vec<ToolDef> {
         t(
             "doc_create",
             "Create a PDF",
-            "Create a new, unsaved document and return it like doc_open: `blank` (pages, width, height in points; default 1 US Letter page), `images` (paths of PNG, JPEG, TIFF (every page), GIF or BMP files, one page each at the image's resolution) or `text` (a .txt path, or `text` directly). Save it with doc_save and a path.",
+            "Create a new, unsaved document and return it like doc_open: `blank` (pages, width, height in points; default 1 US Letter page), `images` (paths of PNG, JPEG, TIFF (every page), GIF or BMP files, one page each at the image's resolution) or `text` (a .txt path, or `text` directly; Western European (WinAnsi) characters only, others are refused). Save it with doc_save and a path.",
         )
         .with(schema(
             json!({
@@ -1029,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!({
@@ -1051,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/automation/tests/hostile_args.rs

@@ -81,8 +81,9 @@ fn zoo() -> Vec<Value> {
 
 /// Paths that must never resolve inside the root. Absolute ones point into the test's own temp
 /// `base` (the root's parent), never at real system files or network shares, so a confinement
-/// bug can only touch what the test made.
-fn escapes(base: &std::path::Path) -> Vec<String> {
+/// bug can only touch what the test made. `linked`: the root holds `link-out`, a symbolic link
+/// to `base`.
+fn escapes(base: &std::path::Path, linked: bool) -> Vec<String> {
     let mut out: Vec<String> = vec![
         "../outside.pdf".into(),
         "../../outside.pdf".into(),
@@ -92,8 +93,10 @@ fn escapes(base: &std::path::Path) -> Vec<String> {
         base.join("outside.pdf").to_string_lossy().into_owned(),
         base.join("new-outside.pdf").to_string_lossy().into_owned(),
         base.join("sub").join("new-outside.pdf").to_string_lossy().into_owned(),
-        "link-out/outside.pdf".into(), // through a planted symbolic link, when the system allows one
     ];
+    if linked {
+        out.push("link-out/outside.pdf".into());
+    }
     // Backslashes separate only on Windows; elsewhere this is an ordinary file name in the root.
     if cfg!(windows) {
         out.push(r"..\..\outside.pdf".into());
@@ -101,6 +104,23 @@ fn escapes(base: &std::path::Path) -> Vec<String> {
     out
 }
 
+/// A symbolic link to a folder, where the system allows one (Windows needs Developer Mode or an
+/// administrator for it, #948).
+fn dir_symlink(target: &std::path::Path, link: &std::path::Path) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        std::os::unix::fs::symlink(target, link)
+    }
+    #[cfg(windows)]
+    {
+        std::os::windows::fs::symlink_dir(target, link)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        Err(std::io::Error::other(format!("no symbolic links here: {} {}", target.display(), link.display())))
+    }
+}
+
 /// The properties of `def` whose values are paths, by name and whether they are a list.
 fn path_props(def: &pdfcraft_automation::ToolDef) -> Vec<(String, bool)> {
     let Some(props) = def.input_schema["properties"].as_object() else { return Vec::new() };
@@ -223,11 +243,15 @@ fn no_tool_escapes_the_root() {
     .expect("outside file");
     let before = listing(&base);
 
-    // A link inside the root pointing out of it, where the system allows one to be made.
-    #[cfg(unix)]
-    let _ = std::os::unix::fs::symlink(&base, root.join("link-out"));
-    #[cfg(windows)]
-    let _ = std::os::windows::fs::symlink_dir(&base, root.join("link-out"));
+    // A link inside the root pointing out of it, where the system allows one to be made. Without
+    // it `link-out/…` is an ordinary path inside the root, which tools that write rightly accept.
+    let linked = match dir_symlink(&base, &root.join("link-out")) {
+        Ok(()) => true,
+        Err(e) => {
+            eprintln!("escapes through a symbolic link not checked: {e}");
+            false
+        }
+    };
 
     let mut a = Automation::new().with_root(&root).expect("root");
 
@@ -247,7 +271,7 @@ fn no_tool_escapes_the_root() {
 
     for def in tools() {
         for (prop, is_list) in path_props(&def) {
-            for escape in escapes(&base) {
+            for escape in escapes(&base, linked) {
                 let mut obj = plausible_with(&def, Some(doc));
                 obj.insert(prop.clone(), if is_list { json!([escape]) } else { json!(escape) });
                 let args = Value::Object(obj);

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>>>>,
@@ -145,6 +147,8 @@ impl ObjectReader {
 
     pub(crate) fn try_get(&mut self, reference: ObjRef) -> Result<Arc<Object>, CosError> {
         let object = self.document.try_get(reference.num);
+        // A missed eviction here only costs a re-parse, so never fail the read on a poisoned
+        // lock. The editing-cache evictors propagate instead; they guard user edits.
         if let Ok(mut streams) = self.document.objstms.lock() {
             // Only insertion changes this private cache between reads. Most neighboring
             // objects reuse a decoded stream: do not sum the whole store for every object.
@@ -217,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(),
@@ -280,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(),
@@ -302,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() {
@@ -355,10 +362,7 @@ impl Document {
             return Ok(());
         };
         let params = crate::security::encrypt_dict(self, &dict);
-        let id0 = match self.trailer.get(b"ID") {
-            Some(Object::Array(a)) => a.first().and_then(|s| s.as_string()).map(|s| s.bytes.clone()).unwrap_or_default(),
-            _ => Vec::new(),
-        };
+        let id0 = self.first_id();
         let handler = pdfcraft_crypt::SecurityHandler::open(params, &id0, password).map_err(|e| match e {
             pdfcraft_crypt::CryptError::WrongPassword if password.is_none() => CosError::NeedsPassword,
             pdfcraft_crypt::CryptError::WrongPassword => CosError::WrongPassword,
@@ -372,6 +376,31 @@ impl Document {
         Ok(())
     }
 
+    /// The first file identifier, part of the encryption key (empty when there is none).
+    fn first_id(&self) -> Vec<u8> {
+        match self.trailer.get(b"ID") {
+            Some(Object::Array(a)) => a.first().and_then(|s| s.as_string()).map(|s| s.bytes.clone()).unwrap_or_default(),
+            _ => Vec::new(),
+        }
+    }
+
+    /// Lift the restrictions of a document opened with its user password by entering the
+    /// owner (permissions) password (§7.6.4). Fails with `WrongPassword` for any other
+    /// password. Does nothing when the document is unencrypted or already opened as owner.
+    /// Both passwords unlock the same file key, so nothing read so far is decoded again.
+    pub fn unlock(&mut self, password: &str) -> Result<(), CosError> {
+        let Some(current) = self.security.as_deref() else { return Ok(()) };
+        if current.auth() == pdfcraft_crypt::Auth::Owner {
+            return Ok(());
+        }
+        let owner = current.authenticate_owner(&self.first_id(), password).map_err(|e| match e {
+            pdfcraft_crypt::CryptError::WrongPassword => CosError::WrongPassword,
+            other => CosError::Security(other.to_string()),
+        })?;
+        self.security = Some(Arc::new(owner));
+        Ok(())
+    }
+
     /// The security handler, when the document is encrypted.
     pub fn security(&self) -> Option<&pdfcraft_crypt::SecurityHandler> {
         self.security.as_deref()
@@ -563,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)
@@ -607,10 +666,81 @@ impl Document {
             LoadGuard::enter(num).ok_or_else(|| CosError::Syntax { offset: 0, detail: format!("reference cycle while loading object {num}") })?;
         let obj = self.load(num, 0)?;
         let obj = Arc::new(obj);
+        // The editing cache is bounded like the scan reader's: re-parsing a file-backed view
+        // is cheap, and returned objects outlive eviction.
         self.cache.lock().map_err(|_| CosError::Poisoned)?.insert(num, obj.clone());
+        self.evict_editor_cache_if_over_budget(num, &obj)?;
         Ok(obj)
     }
 
+    /// Bounds for the editing cache: roomier than the scan reader's (128 objects / 8 MB)
+    /// so interactive editing does not thrash, but still capped so touching a large
+    /// document cannot pin its whole object graph. Only owned (decrypted/copied) bytes
+    /// count; file-backed views re-parse for free.
+    ///
+    /// Worst case per document: input bytes + up to `EDITOR_CACHE_OBJECTS` ×
+    /// `EDITOR_LARGE_OBJECT` (1024 × 256 KB = 256 MB) of small objects between full
+    /// accounting passes + `EDITOR_OBJSTM_BYTES` (32 MB) + unsaved `overlay` edits.
+    /// The count cap always holds; byte accounting between passes is approximate.
+    /// Clones share these caches, so one clone's eviction drops another's hot set;
+    /// that only costs re-parsing, never correctness. Eviction keeps just the newcomer:
+    /// file-backed views re-parse cheaply and editor working sets stay far below 1024.
+    const EDITOR_CACHE_OBJECTS: usize = 1024;
+    const EDITOR_CACHE_BYTES: usize = 32 * 1024 * 1024;
+    /// Object streams decode to megabytes each, so fewer are kept than plain objects.
+    const EDITOR_OBJSTM_OBJECTS: usize = 256;
+    const EDITOR_OBJSTM_BYTES: usize = 32 * 1024 * 1024;
+    /// Newcomers above this force a full accounting pass even below the count cap:
+    /// `EDITOR_CACHE_BYTES / 128`, so 128 large newcomers always trigger a pass before the
+    /// byte budget can double.
+    const EDITOR_LARGE_OBJECT: usize = 256 * 1024;
+
+    fn evict_editor_cache_if_over_budget(&self, fresh_num: u32, fresh: &Object) -> Result<(), CosError> {
+        // Fast path: the full fold is O(cache) per insert, so skip it for a small newcomer
+        // below the count cap. `len` is copied out first; nothing here holds the lock.
+        let len = self.cache.lock().map_err(|_| CosError::Poisoned)?.len();
+        if len <= Self::EDITOR_CACHE_OBJECTS && owned_bytes(fresh, &self.data, 0) <= Self::EDITOR_LARGE_OBJECT {
+            return Ok(());
+        }
+        // Walk a snapshot off-lock; re-lock only to evict.
+        let live: Vec<(u32, Arc<Object>)> = self.cache.lock().map_err(|_| CosError::Poisoned)?.iter().map(|(n, o)| (*n, o.clone())).collect();
+        let data = &self.data;
+        let owned: usize = live.iter().fold(0usize, |n, (_, o)| n.saturating_add(owned_bytes(o, data, 0)));
+        if live.len() <= Self::EDITOR_CACHE_OBJECTS && owned <= Self::EDITOR_CACHE_BYTES {
+            return Ok(());
+        }
+        // Re-check under the final lock: another thread may have inserted or evicted since
+        // the snapshot. Keep its newcomers, and skip the eviction if back within budget.
+        let snapshot: std::collections::HashSet<u32> = live.into_iter().map(|(n, _)| n).collect();
+        let mut cache = self.cache.lock().map_err(|_| CosError::Poisoned)?;
+        if cache.len() <= Self::EDITOR_CACHE_OBJECTS {
+            let data = &self.data;
+            let owned: usize = cache.values().fold(0usize, |n, o| n.saturating_add(owned_bytes(o, data, 0)));
+            if owned <= Self::EDITOR_CACHE_BYTES {
+                return Ok(());
+            }
+        }
+        cache.retain(|n, _| *n == fresh_num || !snapshot.contains(n));
+        Ok(())
+    }
+
+    fn evict_editor_streams_if_over_budget(&self, current: u32) -> Result<(), CosError> {
+        // The caller inserts `current` first, so retaining it keeps a live entry.
+        let over = {
+            let streams = self.objstms.lock().map_err(|_| CosError::Poisoned)?;
+            let bytes = streams.values().fold(0usize, |bytes, stream| {
+                bytes
+                    .saturating_add(stream.data.capacity())
+                    .saturating_add(stream.index.capacity().saturating_mul(std::mem::size_of::<(u32, usize)>()))
+            });
+            bytes > Self::EDITOR_OBJSTM_BYTES || streams.len() > Self::EDITOR_OBJSTM_OBJECTS
+        };
+        if over {
+            self.objstms.lock().map_err(|_| CosError::Poisoned)?.retain(|n, _| *n == current);
+        }
+        Ok(())
+    }
+
     /// Visit every current object without filling this document's editing cache.
     ///
     /// Full-document searches (for example, standalone timestamps) need to inspect objects
@@ -720,7 +850,10 @@ impl Document {
             index.push((onum.max(0) as u32, first + off.max(0) as usize));
         }
         let stm = Arc::new(ObjStm { index, data: Arc::new(data) });
+        // Same bound as the object cache: decoded object streams can be megabytes each.
+        // Insert first so the retained `num` is actually in the map.
         self.objstms.lock().map_err(|_| CosError::Poisoned)?.insert(num, stm.clone());
+        self.evict_editor_streams_if_over_budget(num)?;
         Ok(stm)
     }
 
@@ -853,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() })?;
@@ -865,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() {
@@ -874,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() {
@@ -894,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);
             }
@@ -918,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") {
@@ -954,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);
+                    }
                 }
             }
         }
@@ -1012,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))
@@ -1165,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.
@@ -1361,6 +1558,74 @@ mod tests {
         }
     }
 
+    #[test]
+    fn editor_cache_stays_bounded() {
+        let mut source = Document::new_empty();
+        let objects: Vec<_> = (0..(Document::EDITOR_CACHE_OBJECTS + 64))
+            .map(|i| {
+                let mut value = vec![b'x'; 1024];
+                value[..4].copy_from_slice(&(i as u32).to_le_bytes());
+                Object::Ref(source.add(Object::String(crate::PdfString::literal(value))))
+            })
+            .collect();
+        source.update_dict(source.root().unwrap(), |d| d.set(b"Extension".to_vec(), Object::Array(objects))).unwrap();
+        let bytes = Arc::new(crate::write_full(&source, &crate::SaveOptions::default()).unwrap());
+        let doc = Document::open(bytes).unwrap();
+        let root = doc.get(doc.root().unwrap());
+        let references = root.as_dict().unwrap().get(b"Extension").unwrap().as_array().unwrap().clone();
+        let mut held = None;
+        for (i, reference) in references.iter().enumerate() {
+            let Object::Ref(reference) = reference else { panic!("indirect object") };
+            let object = doc.get(*reference);
+            assert_eq!(&object.as_string().unwrap().bytes[..4], &(i as u32).to_le_bytes());
+            if i == 0 {
+                held = Some(object);
+            }
+            assert!(doc.cache.lock().unwrap().len() <= Document::EDITOR_CACHE_OBJECTS, "editing must not pin the whole object graph");
+            // Eviction keeps the newcomer.
+            assert!(doc.cache.lock().unwrap().contains_key(&reference.num), "eviction must keep the newcomer");
+        }
+        // Returned objects survive eviction, through both handles of the shared cache.
+        assert_eq!(&held.unwrap().as_string().unwrap().bytes[..4], &0u32.to_le_bytes());
+        let snapshot = doc.clone();
+        let first = references[0].as_ref().unwrap();
+        assert_eq!(&snapshot.get(first).as_string().unwrap().bytes[..4], &0u32.to_le_bytes());
+    }
+
+    #[test]
+    fn editor_cache_byte_bound_fires() {
+        // 40 × 1 MB strings: far below the count cap, above the 32 MB byte budget. Each
+        // newcomer exceeds EDITOR_LARGE_OBJECT, so every insert takes a full accounting pass.
+        let mut source = Document::new_empty();
+        let objects: Vec<_> = (0..40)
+            .map(|i| {
+                let mut value = vec![b'y'; 1024 * 1024];
+                value[..4].copy_from_slice(&(i as u32).to_le_bytes());
+                Object::Ref(source.add(Object::String(crate::PdfString::literal(value))))
+            })
+            .collect();
+        source.update_dict(source.root().unwrap(), |d| d.set(b"Extension".to_vec(), Object::Array(objects))).unwrap();
+        let bytes = Arc::new(crate::write_full(&source, &crate::SaveOptions::default()).unwrap());
+        let doc = Document::open(bytes).unwrap();
+        let root = doc.get(doc.root().unwrap());
+        let references = root.as_dict().unwrap().get(b"Extension").unwrap().as_array().unwrap().clone();
+        let mut held = None;
+        for (i, reference) in references.iter().enumerate() {
+            let Object::Ref(reference) = reference else { panic!("indirect object") };
+            let object = doc.get(*reference);
+            assert_eq!(&object.as_string().unwrap().bytes[..4], &(i as u32).to_le_bytes());
+            if i == 0 {
+                held = Some(object);
+            }
+            // Eviction keeps the newcomer.
+            assert!(doc.cache.lock().unwrap().contains_key(&reference.num), "eviction must keep the newcomer");
+        }
+        assert!(doc.cache.lock().unwrap().len() < references.len(), "the byte budget must evict even below the count cap");
+        let last = references[references.len() - 1].as_ref().unwrap();
+        assert!(doc.cache.lock().unwrap().contains_key(&last.num), "eviction must keep the newcomer");
+        assert_eq!(&held.unwrap().as_string().unwrap().bytes[..4], &0u32.to_le_bytes());
+    }
+
     #[test]
     fn a_stream_limited_document_cannot_be_saved() {
         let bytes = Arc::new(crate::write_full(&Document::new_empty(), &crate::SaveOptions::default()).unwrap());

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/object.rs

@@ -230,6 +230,17 @@ impl Stream {
         pdfcraft_filters::decode(&chain, &self.raw, MAX_DECODED).map_err(|e| CosError::Filter(e.to_string()))
     }
 
+    /// Data after the first filter alone, bounded by `max`: the rest of the chain stays encoded.
+    /// Any corruption in that first filter is an error.
+    pub fn decoded_first_filter_strict(&self, max: usize) -> Result<Vec<u8>, CosError> {
+        let mut chain = self.filters();
+        chain.truncate(1);
+        if chain.is_empty() {
+            return self.raw_within(max);
+        }
+        pdfcraft_filters::decode(&chain, &self.raw, max.min(MAX_DECODED)).map_err(|e| CosError::Filter(e.to_string()))
+    }
+
     fn raw_within(&self, max: usize) -> Result<Vec<u8>, CosError> {
         let max = max.min(MAX_DECODED);
         // An empty decoder chain still produces an owned output buffer: check its limit
@@ -470,4 +481,20 @@ mod tests {
         assert_eq!(stream.decoded_within(3).unwrap(), b"abc");
         assert_eq!(stream.decoded_strict().unwrap(), b"abc");
     }
+
+    #[test]
+    fn first_filter_decodes_only_the_outer_wrapper() {
+        let data = "0 0 m 100 100 l S\n".repeat(64).into_bytes();
+        let inner = Stream::flate(Dict::new(), &data).raw.to_vec();
+        for (outer, name, corrupt) in [(Filter::Ascii85, "ASCII85Decode", &b"{~>"[..]), (Filter::AsciiHex, "ASCIIHexDecode", &b"G0>"[..])] {
+            let encoded = pdfcraft_filters::encode(&outer, &Params::default(), &inner).unwrap();
+            let mut dict = Dict::new();
+            dict.set(b"Filter".to_vec(), Object::Array(vec![Object::name(name), Object::name("FlateDecode")]));
+            let stream = Stream::from_raw(dict.clone(), encoded);
+            assert_eq!(stream.decoded_first_filter_strict(usize::MAX).unwrap(), inner);
+            assert_eq!(stream.decoded_strict().unwrap(), data);
+            assert!(matches!(stream.decoded_first_filter_strict(inner.len() - 1), Err(CosError::Filter(_))));
+            assert!(matches!(Stream::from_raw(dict, corrupt.to_vec()).decoded_first_filter_strict(usize::MAX), Err(CosError::Filter(_))));
+        }
+    }
 }

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/encryption.rs

@@ -102,6 +102,36 @@ fn empty_user_password_opens_but_reports_restrictions() {
     assert!(Document::open(Arc::new(fixture())).unwrap().permissions().is_none(), "unencrypted: no restrictions");
 }
 
+#[test]
+fn the_permissions_password_unlocks_an_open_document() {
+    for alg in ALL {
+        // Only a permissions password: opens without asking, restricted (#995).
+        let mut doc = Document::open(Arc::new(protect(alg, "", "perms", 0b0100))).unwrap();
+        // Read something before unlocking: it must stay readable afterwards.
+        assert_eq!(content(&doc), SECRET, "{alg:?}");
+        assert_eq!(doc.unlock("").unwrap_err(), CosError::WrongPassword, "{alg:?}");
+        assert_eq!(doc.unlock("nope").unwrap_err(), CosError::WrongPassword, "{alg:?}");
+        assert!(!doc.permissions().unwrap().modify(), "{alg:?}: still restricted");
+        doc.unlock("perms").unwrap();
+        assert_eq!(doc.security().unwrap().auth(), Auth::Owner, "{alg:?}");
+        assert!(doc.permissions().unwrap().modify(), "{alg:?}");
+        assert_eq!(content(&doc), SECRET, "{alg:?}");
+        assert_eq!(title(&doc).as_deref(), Some("Quarterly numbers"), "{alg:?}");
+        // Unlocked, security can be removed.
+        doc.remove_encryption();
+        let plain = write_full(&doc, &SaveOptions::default()).unwrap();
+        assert!(Document::open(Arc::new(plain)).unwrap().security().is_none(), "{alg:?}");
+    }
+    // Opened with a separate open password: that password doesn't unlock.
+    let mut doc = Document::open_with_password(Arc::new(protect(Algorithm::Aes256, "open", "perms", 0b0100)), Some("open")).unwrap();
+    assert_eq!(doc.unlock("open").unwrap_err(), CosError::WrongPassword);
+    doc.unlock("perms").unwrap();
+    assert!(doc.permissions().unwrap().modify());
+    // Nothing to unlock: unencrypted, or already the owner.
+    Document::open(Arc::new(fixture())).unwrap().unlock("anything").unwrap();
+    doc.unlock("anything").unwrap();
+}
+
 #[test]
 fn incremental_edits_of_encrypted_documents_stay_encrypted() {
     for alg in ALL {

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

@@ -314,7 +314,13 @@ fn png_image(name: &str, bytes: &[u8]) -> Result<Embedded, CreateError> {
         _ => (72.0, 72.0),
     };
     let icc = reader.info().icc_profile.as_ref().map(|p| p.to_vec());
-    let mut buf = vec![0; reader.output_buffer_size().ok_or_else(|| bad("image too large".into()))?];
+    // The decoded size comes from the header alone, so a file of a few bytes can claim any
+    // size: keep the ceiling, and ask for the memory fallibly (a failed allocation would abort
+    // the whole app, and no `catch_unwind` stops that).
+    let size = reader.output_buffer_size().filter(|n| *n <= MAX_DECODED_BYTES).ok_or_else(|| bad("image too large".into()))?;
+    let mut buf = Vec::new();
+    buf.try_reserve_exact(size).map_err(|_| bad("not enough memory for this image".into()))?;
+    buf.resize(size, 0);
     let frame = reader.next_frame(&mut buf).map_err(|e| bad(e.to_string()))?;
     let (w, h) = (frame.width, frame.height);
     let data = &buf[..frame.buffer_size()];
@@ -327,8 +333,14 @@ fn png_image(name: &str, bytes: &[u8]) -> Result<Embedded, CreateError> {
     };
     let has_alpha = channels == 2 || channels == 4;
     let colour_n = if has_alpha { channels - 1 } else { channels };
-    let mut colour = Vec::with_capacity(w as usize * h as usize * colour_n);
+    let mut colour = Vec::new();
+    colour
+        .try_reserve_exact((w as usize).saturating_mul(h as usize).saturating_mul(colour_n))
+        .map_err(|_| bad("not enough memory for this image".into()))?;
     let mut alpha = Vec::new();
+    if has_alpha {
+        alpha.try_reserve_exact((w as usize).saturating_mul(h as usize)).map_err(|_| bad("not enough memory for this image".into()))?;
+    }
     for px in data.chunks_exact(channels) {
         colour.extend_from_slice(&px[..colour_n]);
         if has_alpha {
@@ -385,8 +397,9 @@ fn decoded(name: &str, bytes: &[u8], format: image::ImageFormat) -> Result<Embed
     Ok(rgba_image(rgba.as_raw(), rgba.dimensions(), (72.0, 72.0)))
 }
 
-/// Most decoded bytes one TIFF page may take: room for the 768 MiB CMYK poster in #665, twice over.
-const MAX_TIFF_DECODED_BYTES: usize = 2 << 30;
+/// Most decoded bytes one TIFF page or PNG may take: room for the 768 MiB CMYK poster in #665,
+/// twice over.
+const MAX_DECODED_BYTES: usize = 2 << 30;
 
 /// Every page of a TIFF (multi-page scans become multi-page PDFs).
 fn tiff_pages(name: &str, bytes: &[u8]) -> Result<Vec<Embedded>, CreateError> {
@@ -398,7 +411,7 @@ fn tiff_pages(name: &str, bytes: &[u8]) -> Result<Vec<Embedded>, CreateError> {
     // 12000x16000 CMYK is 768 MiB. Raise it, but keep a ceiling so a tiny file claiming
     // enormous dimensions can't ask for unbounded memory.
     let mut limits = Limits::default();
-    limits.decoding_buffer_size = MAX_TIFF_DECODED_BYTES;
+    limits.decoding_buffer_size = MAX_DECODED_BYTES;
     let mut dec = Decoder::new(std::io::Cursor::new(bytes)).map_err(|e| bad(e.to_string()))?.with_limits(limits);
     let mut out = Vec::new();
     loop {
@@ -475,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])
@@ -509,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)?])
@@ -605,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();
@@ -198,6 +224,64 @@ fn a_tiff_claiming_enormous_dimensions_is_refused() {
     assert!(matches!(from_images(&[("huge.tif".into(), tif)]), Err(CreateError::Image(..))));
 }
 
+/// A PNG of a few bytes whose header claims `w`×`h` 8-bit RGBA pixels, with no pixel data.
+fn png_claiming(w: u32, h: u32) -> Vec<u8> {
+    fn crc32(bytes: &[u8]) -> u32 {
+        let mut c = !0u32;
+        for &b in bytes {
+            c ^= u32::from(b);
+            for _ in 0..8 {
+                c = if c & 1 != 0 { 0xEDB8_8320 ^ (c >> 1) } else { c >> 1 };
+            }
+        }
+        !c
+    }
+    let mut png = b"\x89PNG\r\n\x1a\n".to_vec();
+    let mut chunk = |kind: &[u8], data: &[u8]| {
+        png.extend_from_slice(&(data.len() as u32).to_be_bytes());
+        let body = [kind, data].concat();
+        png.extend_from_slice(&body);
+        png.extend_from_slice(&crc32(&body).to_be_bytes());
+    };
+    let ihdr = [&w.to_be_bytes()[..], &h.to_be_bytes(), &[8, 6, 0, 0, 0]].concat();
+    chunk(b"IHDR", &ihdr);
+    // An empty zlib stream: one stored block of no bytes.
+    chunk(b"IDAT", &[0x78, 0x01, 0x01, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0x00, 0x01]);
+    chunk(b"IEND", &[]);
+    png
+}
+
+#[test]
+fn a_tiny_png_claiming_huge_dimensions_is_refused_before_allocating() {
+    // 68 bytes claiming 13 GiB (and 1 TiB) of pixels: refused before anything is allocated,
+    // where it used to abort the process when the allocation failed.
+    for (w, h) in [(60_000, 60_000), (1 << 20, 1 << 18)] {
+        let png = png_claiming(w, h);
+        assert_eq!(png.len(), 68);
+        let r = from_images(&[("huge.png".into(), png)]);
+        assert!(matches!(&r, Err(CreateError::Image(_, m)) if m.contains("too large")), "{w}x{h}");
+    }
+}
+
+/// Likewise a PNG: the png crate's limits don't cover the frame buffer, which its header sizes
+/// (60000x60000 RGBA is 14.4 GB). Refused before anything is allocated, not after.
+#[test]
+fn a_png_claiming_enormous_dimensions_is_refused() {
+    let mut png = Vec::new();
+    {
+        let mut enc = png::Encoder::new(&mut png, 60_000, 60_000);
+        enc.set_color(png::ColorType::Rgba);
+        enc.set_depth(png::BitDepth::Eight);
+        let mut w = enc.write_header().unwrap();
+        // A zlib stream holding one zero byte: far too little data, but a well-formed start.
+        w.write_chunk(png::chunk::IDAT, &[0x78, 0x01, 0x01, 0x01, 0x00, 0xFE, 0xFF, 0x00, 0x00, 0x01, 0x00, 0x01]).unwrap();
+    }
+    match from_images(&[("huge.png".into(), png)]) {
+        Err(CreateError::Image(_, m)) => assert!(m.contains("too large"), "{m}"),
+        other => panic!("expected a refusal, got {:?}", other.map(|_| ())),
+    }
+}
+
 #[test]
 fn images_export_as_jpeg_unchanged_and_others_as_png() {
     let doc = reopen(
@@ -324,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
@@ -637,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

@@ -180,6 +180,18 @@ impl SecurityHandler {
         Ok(Self { dict, key, auth, recovered_user })
     }
 
+    /// Upgrade to owner access with the owner (permissions) password, as when a restricted
+    /// document is unlocked after opening. The user password, or any other, is `WrongPassword`.
+    /// Both passwords unlock the same file key, so what was decrypted so far stays valid; a
+    /// different key is refused too.
+    pub fn authenticate_owner(&self, id0: &[u8], password: &str) -> Result<Self, CryptError> {
+        let owner = Self::open(self.dict.clone(), id0, Some(password))?;
+        if owner.auth != Auth::Owner || owner.key != self.key {
+            return Err(CryptError::WrongPassword);
+        }
+        Ok(owner)
+    }
+
     pub fn auth(&self) -> Auth {
         self.auth
     }
@@ -527,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> {
@@ -561,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 {
@@ -575,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));
@@ -598,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

@@ -69,6 +69,29 @@ fn created_encryption_authenticates_owner_and_user() {
     }
 }
 
+#[test]
+fn the_owner_password_upgrades_a_user_session() {
+    for alg in ALL {
+        let d = new(alg, "", "secret", 0b0100).dict().clone();
+        let user = SecurityHandler::open(d, ID, None).unwrap();
+        assert!(!user.permissions().modify(), "{alg:?}");
+        // The (empty) user password and wrong ones don't unlock anything.
+        assert_eq!(user.authenticate_owner(ID, "").unwrap_err(), CryptError::WrongPassword, "{alg:?}");
+        assert_eq!(user.authenticate_owner(ID, "nope").unwrap_err(), CryptError::WrongPassword, "{alg:?}");
+        let owner = user.authenticate_owner(ID, "secret").unwrap();
+        assert_eq!(owner.auth(), Auth::Owner, "{alg:?}");
+        assert_eq!(owner.file_key(), user.file_key(), "{alg:?}");
+        assert!(owner.permissions().modify(), "{alg:?}");
+    }
+    // A separate open password is not the permissions password.
+    for alg in ALL {
+        let d = new(alg, "open", "perms", 0b0100).dict().clone();
+        let user = SecurityHandler::open(d, ID, Some("open")).unwrap();
+        assert_eq!(user.authenticate_owner(ID, "open").unwrap_err(), CryptError::WrongPassword, "{alg:?}");
+        assert_eq!(user.authenticate_owner(ID, "perms").unwrap().auth(), Auth::Owner, "{alg:?}");
+    }
+}
+
 #[test]
 fn empty_user_password_opens_without_asking() {
     for alg in ALL {
@@ -122,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

@@ -8,13 +8,13 @@
 //! after `/UserUnit` and `/Rotate`), so items stay upright on rotated pages; an item records the
 //! `/UserUnit` it was written for.
 
-use std::collections::HashMap;
+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, check, contents, n, page_list, place_tagged};
+use crate::{EditError, MarkKind, check, contents, n, page_list, place_tagged};
 
 const TAG: &str = "Added";
 
@@ -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,
+        }
     }
 }
 
@@ -198,6 +213,13 @@ pub struct Added {
     pub content: Content,
 }
 
+/// PdfCraft-owned page content discovered in one page/content traversal.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct MarkerScan {
+    pub marks: Vec<MarkKind>,
+    pub added: Vec<Added>,
+}
+
 fn nums(doc: &Document, o: Option<&Object>) -> Vec<f64> {
     o.map(|o| doc.resolve(o)).and_then(|a| a.as_array().map(|a| a.iter().filter_map(Object::as_f64).collect())).unwrap_or_default()
 }
@@ -218,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();
@@ -243,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 {
@@ -253,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);
@@ -262,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,
         })
     })
 }
@@ -298,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));
@@ -322,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 {
@@ -346,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 {
@@ -369,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);
@@ -380,25 +471,44 @@ fn font_name(base: &str) -> String {
     format!("PCF{}", base.replace('-', ""))
 }
 
-/// Most glyphs in one Type 3 font: its codes are single bytes, 1–240.
+/// Most glyphs in one Type 3 font: its codes are single bytes, 1–240. An item gets one such font
+/// per 240 distinct glyphs it needs.
 const GLYPHS_PER_FONT: usize = 240;
-/// Most Type 3 fonts one item may use, which bounds the objects it adds (ordinary text needs one
-/// or two).
-const MAX_ARABIC_FONTS: usize = 16;
 
-/// Draw a text item that has Arabic in it. Each line is laid out in display order; Arabic glyphs
+/// 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 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 `latin`.
-fn draw_arabic(doc: &mut Document, t: &AddedText, latin: &str, taken: &Dict, fonts: &mut Dict, out: &mut Vec<u8>) -> Result<(), EditError> {
+/// with a ToUnicode map for copy and search. Other text uses the item's standard font.
+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)| shaped_layout(t, &line, rtl).map(|(pieces, w)| (line, rtl, pieces, w)))
+        .collect::<Result<Vec<_>, _>>()?;
+    draw_laid_shaped(doc, t, &laid, taken, fonts, out, shaped_glyph)
+}
+
+/// [`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(ShapedScript, u32) -> Result<GlyphOutline, GlyphError>,
+) -> Result<(), EditError> {
     let r = text_rect(t);
-    let lines = wrapped(t);
-    let laid = lines.iter().map(|(line, rtl)| arabic_layout(t, line, *rtl)).collect::<Result<Vec<_>, _>>()?;
+    let latin = font_name(t.family.base_font(t.bold, t.italic));
     // Every distinct cluster (a letter with its dots and the text it stands for) is one glyph of
     // one of the fonts, so copy and search get each character exactly once.
     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(),
+    for c in laid.iter().flat_map(|(_, _, pieces, _)| pieces).flat_map(|p| match p {
+        Piece::Shaped(clusters) => clusters.as_slice(),
         Piece::Latin(_) => &[],
     }) {
         index.entry(cluster_key(c)).or_insert_with(|| {
@@ -406,38 +516,46 @@ fn draw_arabic(doc: &mut Document, t: &AddedText, latin: &str, taken: &Dict, fon
             keys.len() - 1
         });
     }
-    if keys.len() > GLYPHS_PER_FONT * MAX_ARABIC_FONTS {
-        return Err(EditError::Invalid("the text uses too many different Arabic glyphs; split it into several boxes".into()));
-    }
+
     // 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, arabic_glyph(*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),
+                })?);
             }
         }
     }
+    // The names the page and this item already use: a new font never takes one of them.
+    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);
         let mut suffix = 0usize;
-        while taken.contains(name.as_bytes()) || fonts.contains(name.as_bytes()) {
+        while taken_names.contains(name.as_bytes()) {
             suffix = suffix.saturating_add(1);
             name = format!("PCAr{}_{suffix}", font.num);
         }
+        taken_names.insert(name.clone().into_bytes());
         fonts.set(name.clone().into_bytes(), Object::Ref(font));
         names.push(name);
     }
     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 lines.iter().zip(&laid).enumerate() {
+    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 < lines.len() && spaces > 0 { ((r[2] - r[0]) - w).max(0.0) / spaces as f64 } else { 0.0 };
+        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 };
         let x = match t.align {
             // A right-to-left paragraph's unstretched last line ends at the right edge.
             Align::Justify if *rtl => r[2] - w - tw * spaces as f64,
@@ -454,10 +572,10 @@ fn draw_arabic(doc: &mut Document, t: &AddedText, latin: &str, taken: &Dict, fon
                     out.extend(format!("/{latin} {} Tf {} Tw 1 0 0 1 {} {} Tm ", n(t.size), n(tw), n(pen), n(y)).bytes());
                     out.extend(literal(&win_ansi(s)));
                     out.extend_from_slice(b" Tj\n");
-                    current = Some(latin);
-                    pen += t.family.width(s, t.size, t.bold) + tw * s.matches(' ').count() as f64;
+                    current = Some(latin.as_str());
+                    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 };
@@ -475,6 +593,7 @@ fn draw_arabic(doc: &mut Document, t: &AddedText, latin: &str, taken: &Dict, fon
                 }
             }
         }
+        out.extend_from_slice(b"EMC\n");
     }
     out.extend_from_slice(b"ET\n");
     Ok(())
@@ -482,14 +601,14 @@ fn draw_arabic(doc: &mut Document, t: &AddedText, latin: &str, taken: &Dict, fon
 
 /// 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());
@@ -501,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());
@@ -538,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(' ', "")));
@@ -585,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, &name, 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));
@@ -596,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,
@@ -728,6 +858,76 @@ fn parse(doc: &Document, d: &Dict) -> Option<Content> {
     }
 }
 
+fn with_resolved<T>(doc: &Document, object: &Object, f: impl FnOnce(&Object) -> T) -> T {
+    match object {
+        Object::Ref(reference) => {
+            let resolved = doc.get(*reference);
+            f(&resolved)
+        }
+        direct => f(direct),
+    }
+}
+
+fn for_each_content_entry(doc: &Document, page: &pdfcraft_model::Page, mut visit: impl FnMut(&Object)) {
+    let Some(contents) = page.dict.get(b"Contents") else { return };
+    with_resolved(doc, contents, |resolved| match resolved {
+        Object::Array(entries) => {
+            for entry in entries {
+                visit(entry);
+            }
+        }
+        _ => visit(contents),
+    });
+}
+
+/// Finds page marks and editable added content in one pass over the page content entries.
+pub fn scan_markers(doc: &Document) -> MarkerScan {
+    let mut scan = MarkerScan::default();
+    for (pi, page) in page_list(doc).iter().enumerate() {
+        for_each_content_entry(doc, page, |entry| {
+            with_resolved(doc, entry, |resolved| {
+                let Some(dict) = resolved.as_dict() else { return };
+                let tag = dict.name(b"PCMark");
+                let kind = if tag == Some(&b"HeaderFooter"[..]) {
+                    Some(MarkKind::HeaderFooter)
+                } else if tag == Some(&b"Watermark"[..]) {
+                    Some(MarkKind::Watermark)
+                } else if tag == Some(&b"Background"[..]) {
+                    Some(MarkKind::Background)
+                } else {
+                    None
+                };
+                if let Some(kind) = kind
+                    && !scan.marks.contains(&kind)
+                {
+                    scan.marks.push(kind);
+                }
+
+                let Some(obj) = Object::as_ref(entry) else { return };
+                if tag != Some(TAG.as_bytes()) {
+                    return;
+                }
+                let Some(params_object) = dict.get(b"PCAdded") else { return };
+                with_resolved(doc, params_object, |resolved_params| {
+                    let Some(params) = resolved_params.as_dict() else { return };
+                    if let Some(content) = parse(doc, params) {
+                        // Display points depend on the page's /UserUnit. An item records the one it was
+                        // written for; none means 1, as for items written before display space followed
+                        // /UserUnit.
+                        let written = params
+                            .get(b"UserUnit")
+                            .and_then(Object::as_f64)
+                            .filter(|u| u.is_finite() && *u >= 1.0)
+                            .map_or(1.0, |u| u.min(pdfcraft_model::MAX_USER_UNIT));
+                        scan.added.push(Added { page: pi, obj, content: content.scaled(page.user_unit(doc) / written) });
+                    }
+                });
+            });
+        });
+    }
+    scan
+}
+
 fn validate(c: &Content) -> Result<(), EditError> {
     let r = c.rect();
     if !r.iter().all(|v| v.is_finite()) {
@@ -744,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)
             };
@@ -816,37 +1022,7 @@ fn write(doc: &mut Document, page: usize, c: &Content, obj: Option<ObjRef>) -> R
 
 /// Every added item, page by page, in drawing order.
 pub fn list_added(doc: &Document) -> Vec<Added> {
-    let mut out = Vec::new();
-    for (pi, p) in page_list(doc).iter().enumerate() {
-        let list: Vec<Object> = match p.dict.get(b"Contents") {
-            Some(c) => match &*doc.resolve(c) {
-                Object::Array(a) => a.clone(),
-                _ => vec![c.clone()],
-            },
-            None => Vec::new(),
-        };
-        for o in list {
-            let Some(r) = o.as_ref() else { continue };
-            let obj = doc.get(r);
-            let Some(d) = obj.as_dict() else { continue };
-            if d.name(b"PCMark") != Some(TAG.as_bytes()) {
-                continue;
-            }
-            let Some(params) = d.get(b"PCAdded").and_then(|o| doc.resolve(o).as_dict().cloned()) else { continue };
-            if let Some(c) = parse(doc, &params) {
-                // Display points depend on the page's /UserUnit. An item records the one it was
-                // written for; none means 1, as for items written before display space followed
-                // /UserUnit.
-                let written = params
-                    .get(b"UserUnit")
-                    .and_then(Object::as_f64)
-                    .filter(|u| u.is_finite() && *u >= 1.0)
-                    .map_or(1.0, |u| u.min(pdfcraft_model::MAX_USER_UNIT));
-                out.push(Added { page: pi, obj: r, content: c.scaled(p.user_unit(doc) / written) });
-            }
-        }
-    }
-    out
+    scan_markers(doc).added
 }
 
 /// Add an item to a page (0-based). Returns its index among the page's added items.
@@ -897,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() };
@@ -915,3 +1091,6 @@ fn drop_fonts(doc: &Document, res: &mut Dict, names: &[Vec<u8>]) {
     }
     res.set(b"Font".to_vec(), Object::Dict(fonts));
 }
+
+#[cfg(test)]
+mod arabic_tests;

crates/edit/src/added/arabic_tests.rs

@@ -0,0 +1,271 @@
+//! Arabic items too big for one Type 3 font. Shaped clusters and glyph outlines are injected here,
+//! so these run without the craft-fonts Arabic face. Shaping itself is covered by the face tests in
+//! `tests.rs`, which run where the face is built in.
+
+use std::cell::Cell;
+
+use super::*;
+
+/// 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 { 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::Shaped(clusters)], width)
+}
+
+/// A glyph outline: a box on the baseline, `advance` em wide.
+fn boxed(advance: f64) -> GlyphOutline {
+    let contours = vec![vec![[0.0, 0.0], [advance, 0.0], [advance, 0.5], [0.0, 0.5]]];
+    GlyphOutline { contours, width: advance, bbox: [0.0, 0.0, advance, 0.5] }
+}
+
+fn item() -> AddedText {
+    AddedText { rect: [72.0, 600.0, 540.0, 700.0], ..AddedText::default() }
+}
+
+/// Every object of `doc`, serialised: equal snapshots mean the document did not change.
+fn snapshot(doc: &Document) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    for num in doc.object_numbers() {
+        let obj = doc.get(ObjRef { num, generation: doc.generation(num) });
+        pdfcraft_cos::serialize(&obj, &mut bytes);
+        bytes.push(b'\n');
+    }
+    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
+        .iter()
+        .map(|(name, font)| {
+            let glyphs = match doc.dict(font).as_ref().and_then(|f| f.get(b"CharProcs")) {
+                Some(Object::Dict(procs)) => procs.len(),
+                _ => 0,
+            };
+            (name.clone(), glyphs)
+        })
+        .collect()
+}
+
+/// The font and code of every glyph the content stream shows, in drawing order.
+fn glyphs_shown(out: &[u8]) -> Vec<(Vec<u8>, u8)> {
+    let mut font = Vec::new();
+    let mut shown = Vec::new();
+    for op in pdfcraft_content::parse(out).ops {
+        if op.is("Tf") {
+            font = op.name(0).unwrap_or_default().to_vec();
+        } else if op.is("Tj")
+            && let Some(Object::String(s)) = op.operands.first()
+        {
+            shown.push((font.clone(), s.bytes.first().copied().unwrap_or_default()));
+        }
+    }
+    shown
+}
+
+/// 64-bit FNV-1a: a stable fingerprint for the golden check.
+fn fnv1a(bytes: &[u8]) -> u64 {
+    bytes.iter().fold(0xcbf2_9ce4_8422_2325, |h, b| (h ^ u64::from(*b)).wrapping_mul(0x0100_0000_01b3))
+}
+
+#[test]
+fn an_item_past_the_old_glyph_limit_gets_a_font_per_240_glyphs() {
+    // Sixteen fonts of 240 glyphs was the most an item could use. This one needs 3,841 glyphs.
+    let n = 16 * GLYPHS_PER_FONT + 1;
+    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_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];
+    expected.push(1);
+    assert_eq!(made.iter().map(|(_, glyphs)| *glyphs).collect::<Vec<_>>(), expected);
+    let shown = glyphs_shown(&out);
+    assert_eq!(shown.len(), n);
+    for (k, (font, code)) in shown.iter().enumerate() {
+        assert_eq!(font, &made[k / GLYPHS_PER_FONT].0, "glyph {k} is drawn from the wrong font");
+        assert_eq!(usize::from(*code), k % GLYPHS_PER_FONT + 1, "glyph {k} has the wrong code");
+    }
+}
+
+#[test]
+fn an_outline_missing_from_a_later_font_leaves_the_document_unchanged() {
+    // Two fonts' worth of glyphs; the glyph in the second font has no outline.
+    let n = 2 * GLYPHS_PER_FONT;
+    let laid = vec![line((0..n).map(|i| cluster(i as u32 + 1, 0.5)).collect(), false)];
+    let mut doc = Document::new_empty();
+    let before = snapshot(&doc);
+    let missing = n as u32;
+    let (mut fonts, mut out) = (Dict::new(), Vec::new());
+    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:?}");
+    assert_eq!(snapshot(&doc), before);
+    assert!(fonts.is_empty() && out.is_empty());
+}
+
+#[test]
+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 { 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::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_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(golden_snapshot(&doc));
+    assert_eq!(fnv1a(&bytes), SMALL_ITEM_FINGERPRINT, "small-item output changed");
+}
+
+#[test]
+fn long_text_with_few_distinct_glyphs_needs_one_font() {
+    // 5,000 clusters that repeat three glyphs: one font, and one outline read per glyph.
+    let clusters: Vec<ShapedCluster> = (0..5_000u32).map(|i| cluster(1 + i % 3, 0.5)).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_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| {
+        reads.set(reads.get() + 1);
+        Ok(boxed(0.5))
+    });
+    assert!(drawn.is_ok(), "{drawn:?}");
+    assert_eq!(fonts_of(&doc, &fonts).iter().map(|(_, glyphs)| *glyphs).collect::<Vec<_>>(), [3]);
+    assert_eq!(reads.get(), 3);
+    assert_eq!(glyphs_shown(&out).len(), 5_000);
+}
+
+#[test]
+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 {
+            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_shaped(&mut doc, &item(), &laid, &Dict::new(), &mut fonts, &mut out, |_, _| {
+        reads.set(reads.get() + 1);
+        Ok(boxed(0.5))
+    });
+    assert!(drawn.is_ok(), "{drawn:?}");
+    assert_eq!(fonts.len(), 17);
+    assert_eq!(reads.get(), 4);
+    assert_eq!(glyphs_shown(&out).len(), 3_841);
+}
+
+#[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 { 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_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_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());
+    assert_eq!(snapshot(&doc), before);
+    assert!(fonts.is_empty() && out.is_empty());
+}
+
+#[test]
+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_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.
+    let mut taken = Dict::new();
+    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_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);
+    assert!(second.starts_with(b"PCAr"), "{}", String::from_utf8_lossy(&second));
+}

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)
 }
@@ -248,6 +399,34 @@ pub fn turn_about_centre(rect: [f64; 4], quarters: i32, flip_h: bool, flip_v: bo
     [a, b, c, d, cx - a * cx - c * cy, cy - b * cx - d * cy]
 }
 
+/// For a `Do` at `op` that sits alone in `q re W n cm Do Q`: the index of the `re` and the `cm` matrix.
+/// That clip belongs to this image only, so it may move with it. A `cm` this move put before the
+/// `re` earlier (`q cm re W n cm Do Q`) keeps the pattern, so the image can be moved again.
+fn exclusive_clip(ops: &[Op], op: usize) -> Option<(usize, Matrix)> {
+    let at = op.checked_sub(4)?;
+    let mut q = at.checked_sub(1)?;
+    while ops.get(q)?.is("cm") {
+        q = q.checked_sub(1)?;
+    }
+    let ok = ops.get(q)?.is("q")
+        && ops.get(at)?.is("re")
+        && (ops.get(at + 1)?.is("W") || ops.get(at + 1)?.is("W*"))
+        && ops.get(at + 2)?.is("n")
+        && ops.get(at + 3)?.is("cm")
+        && ops.get(op + 1)?.is("Q");
+    if !ok {
+        return None;
+    }
+    Some((at, Matrix(ops.get(at + 3)?.nums::<6>()?)))
+}
+
+/// The `cm` to put before the clip so that user-space transform `t` also moves the clip:
+/// the clip is drawn in the CTM before the image's own `cm` (`cm` · that = `draw`).
+fn clip_matrix(draw: Matrix, cm: Matrix, t: Matrix) -> Option<Matrix> {
+    let outer = cm.invert()?.then(&draw);
+    Some(outer.then(&t).then(&outer.invert()?))
+}
+
 /// Change image `index` (from [`page_images`]) on `page`.
 pub fn change_image(doc: &mut Document, page: usize, index: usize, change: &ImageChange) -> Result<(), EditError> {
     let images = page_images(doc, page)?;
@@ -256,22 +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 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()));
-            }
-            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 {
@@ -320,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> {
@@ -339,7 +644,7 @@ pub(crate) fn translate_images(doc: &mut Document, page: usize, indexes: &[usize
         if !movement.0.iter().all(|v| v.is_finite() && v.abs() <= 1e12) {
             return Err(EditError::Invalid("the image move is too large".into()));
         }
-        plans.insert((image.stream, image.op), movement);
+        plans.insert((image.stream, image.op), (movement, placement, offset));
     }
     let mut data = Vec::with_capacity(all.len());
     let mut inside_text = false;
@@ -355,8 +660,23 @@ pub(crate) fn translate_images(doc: &mut Document, page: usize, indexes: &[usize
                 return Err(EditError::Invalid("an image inside a text object cannot be moved in a group".into()));
             }
         }
+        // Images alone in their own `q re W n cm Do Q` take the clip with them.
+        let mut clips = std::collections::BTreeMap::new();
+        for index in 0..ops.len() {
+            let Some(&(_, placement, offset)) = plans.get(&(stream, index)) else { continue };
+            let Some((at, cm)) = exclusive_clip(&ops, index) else { continue };
+            let translation = Matrix([1.0, 0.0, 0.0, 1.0, offset[0], offset[1]]);
+            let Some(c) = clip_matrix(placement, cm, translation).filter(|c| c.0.iter().all(|v| v.is_finite() && v.abs() <= 1e12)) else {
+                return Err(EditError::Invalid("the image move is too large".into()));
+            };
+            plans.remove(&(stream, index));
+            clips.insert((stream, at), c);
+        }
         let changed = crate::text::splice(&pieces, &ops, |index| {
-            let Some(matrix) = plans.remove(&(stream, index)) else { return (Vec::new(), true) };
+            if let Some(c) = clips.remove(&(stream, index)) {
+                return (vec![Op::new("cm", c.0.map(Object::Real).to_vec())], true);
+            }
+            let Some((matrix, _, _)) = plans.remove(&(stream, index)) else { return (Vec::new(), true) };
             let original = ops.get(index).cloned().into_iter();
             // Local translations can be tiny under a large CTM. Preserve their precision
             // rather than rounding them to zero or amplifying an error on the page.