Merge branch 'main' into mailbox

chore: update Gradle to 9.7.1 (#7673 )
Automated update of the Gradle wrapper and Gradle Docker build images. Gradle version: `9.7.1` Docker image: `gradle:9.7.1-jdk25` Co-authored-by: Frooodle <77850077+Frooodle@users.noreply.github.com>
2026-09-03 05:10:16 +03:00 · 2026-08-25 15:44:11 +02:00 · 2026-08-25 12:36:38 +00:00 · 2026-08-25 13:57:19 +02:00 · 2026-08-25 13:41:05 +02:00 · 2026-08-25 12:54:56 +02:00
323 changed files with 22006 additions and 3116 deletions
@@ -96,6 +96,14 @@ configs/
 __pycache__/
 **/__pycache__/

+# Python virtualenvs. Large, platform-specific, and their symlinks break the build.
+.venv/
+**/.venv/
+venv/
+**/venv/
+*.egg-info/
+**/*.egg-info/
+
 # Local env
 .env
 .env.*
@@ -22,26 +22,15 @@ indent_size = 4

 [*.html]
 indent_size = 2
-insert_final_newline = false
-trim_trailing_whitespace = false

-[{*.js,*.jsx,*.mjs,*.ts,*.tsx}]
+[{*.js,*.jsx,*.mjs,*.ts,*.tsx,*.mts}]
 indent_size = 2

 [*.css]
-# CSS files typically use an indent size of 2 spaces for better readability and alignment with community standards.
 indent_size = 2

 [*.{yml,yaml}]
-# YAML files use an indent size of 2 spaces to maintain consistency with common YAML formatting practices.
-indent_size = 2
-insert_final_newline = false
-trim_trailing_whitespace = false
-
-[*.json]
-# JSON files use an indent size of 2 spaces, which is the standard for JSON formatting.
 indent_size = 2

-[*.jsonc]
-# JSONC (JSON with comments) files also follow the standard JSON formatting with an indent size of 2 spaces.
+[*.{json,jsonc}]
 indent_size = 2
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-desktop
-pkgver=2.14.3
+pkgver=2.15.0
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (Tauri desktop app, official Stirling PDF Inc build)"
 arch=('x86_64')
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-server-bin
-pkgver=2.14.3
+pkgver=2.15.0
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
 arch=('any')
@@ -39,7 +39,7 @@ jobs:
      pr_ref: ${{ steps.resolve.outputs.ref }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -121,7 +121,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -475,7 +475,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -70,7 +70,7 @@ jobs:
      enable_prototypes: ${{ steps.check-prototypes-flag.outputs.enable_prototypes }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -177,7 +177,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -482,7 +482,7 @@ jobs:
      issues: write # add/remove labels, delete the command comment
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -22,7 +22,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -38,7 +38,7 @@ jobs:
      is_fork: ${{ steps.decide.outputs.is_fork }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -20,7 +20,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -26,7 +26,7 @@ jobs:
      jar_sha256: ${{ steps.hashes.outputs.jar_sha256 }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -71,7 +71,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -18,7 +18,7 @@ jobs:
      issues: write # labels are applied through the issues API
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -31,7 +31,7 @@ jobs:
        flavor: [core, proprietary, saas]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -58,7 +58,7 @@ jobs:
      SYSTEM_ENABLEANALYTICS: "false"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -351,7 +351,7 @@ jobs:
      MN_COMPOSE: docker-compose-multinode.yml
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -49,7 +49,7 @@ jobs:
      proprietary: ${{ steps.changes.outputs.proprietary }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -298,7 +298,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -28,7 +28,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -16,7 +16,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -17,7 +17,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -28,7 +28,7 @@ jobs:
      pull-requests: write # Allow writing to pull requests
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -34,7 +34,7 @@ jobs:
    timeout-minutes: 15
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -20,7 +20,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -14,7 +14,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -28,7 +28,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -18,7 +18,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -32,7 +32,7 @@ jobs:
            project: stubbed-webkit
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -21,7 +21,7 @@ jobs:
    timeout-minutes: 25
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -28,7 +28,7 @@ jobs:
      licenses-backend: ${{ steps.changes.outputs.licenses-backend }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -56,7 +56,7 @@ jobs:
      repository-projects: write # Required for enabling automerge
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -334,7 +334,7 @@ jobs:
      repository-projects: write # Required for enabling automerge
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -15,7 +15,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -18,7 +18,7 @@ jobs:
    timeout-minutes: 15
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -15,7 +15,7 @@ jobs:
      issues: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -48,7 +48,7 @@ jobs:
      version: ${{ steps.versionNumber.outputs.versionNumber }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -140,7 +140,7 @@ jobs:
            file_suffix: "-server"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -207,7 +207,7 @@ jobs:
      RELEASE_GPG_PRIVATE_KEY: ${{ secrets.RELEASE_GPG_PRIVATE_KEY }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
          allowed-endpoints: >
@@ -715,7 +715,7 @@ jobs:
      contents: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -23,7 +23,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -74,7 +74,7 @@ jobs:
    timeout-minutes: 60
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -140,7 +140,7 @@ jobs:
      contents: read
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -28,7 +28,7 @@ jobs:
      jar_sha256: ${{ steps.hashes.outputs.jar_sha256 }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -80,7 +80,7 @@ jobs:
      contents: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -32,7 +32,7 @@ jobs:
      pull-requests: write # pulls.get/list plus add/remove the label on PRs
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -14,7 +14,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -48,7 +48,7 @@ jobs:
          echo "version=${VERSION}" >> $GITHUB_OUTPUT

      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -18,6 +18,16 @@ on:
        required: false
        type: boolean
        default: false
+      build_engine:
+        description: "Build & push the standalone stirling-engine image."
+        required: false
+        type: boolean
+        default: true
+      force_engine_rebuild:
+        description: "Rebuild stirling-engine even if its source hash is unchanged."
+        required: false
+        type: boolean
+        default: false
  push:
    branches:
      - release
@@ -50,9 +60,10 @@ jobs:
    env:
      RUN_MAIN_APP: ${{ github.event_name != 'workflow_dispatch' || inputs.build_main_app }}
      RUN_UNOSERVER: ${{ github.event_name != 'workflow_dispatch' || inputs.build_unoserver }}
+      RUN_ENGINE: ${{ github.event_name != 'workflow_dispatch' || inputs.build_engine }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -387,3 +398,119 @@ jobs:
          else
            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping unoserver image signing"
          fi
+
+      # Standalone AI engine image, same shape as the unoserver image above.
+      - name: Compute engine image source hash
+        id: engineHash
+        if: env.RUN_ENGINE == 'true'
+        run: |
+          set -eu
+          hash=$( { cat engine/Dockerfile engine/pyproject.toml engine/uv.lock engine/.env; \
+                    find engine/src -type f -print0 | sort -z | xargs -0 cat; } \
+                  | sha256sum | cut -d' ' -f1)
+          echo "hash=${hash}" >> "$GITHUB_OUTPUT"
+          echo "Engine source hash: ${hash}"
+
+      - name: Decide whether to publish engine image
+        id: engineDecision
+        if: env.RUN_ENGINE == 'true'
+        env:
+          ENGINE_VERSION: ${{ steps.versionNumber.outputs.versionNumber }}
+          ENGINE_HASH: ${{ steps.engineHash.outputs.hash }}
+          ENGINE_IMAGE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-engine
+          ENGINE_HASH_ANNOTATION: org.stirlingpdf.engine-source-hash
+          FORCE_REBUILD: ${{ inputs.force_engine_rebuild }}
+          GH_REF: ${{ github.ref }}
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -eu
+          mode="skip"
+          tags=""
+
+          read_published_hash() {
+            local ref="$1"
+            docker buildx imagetools inspect "$ref" --raw 2>/dev/null \
+              | jq -r --arg key "$ENGINE_HASH_ANNOTATION" \
+                  '.annotations[$key] // empty' \
+              2>/dev/null || true
+          }
+
+          # Manual dispatch from any branch routes to the :alpha publish path.
+          EFFECTIVE_REF="$GH_REF"
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            EFFECTIVE_REF="refs/heads/testMain"
+          fi
+
+          case "$EFFECTIVE_REF" in
+            refs/heads/release)
+              if [ "${FORCE_REBUILD}" = "true" ]; then
+                echo "force_engine_rebuild=true — building stable regardless"
+                mode="stable"
+                tags="${ENGINE_IMAGE}:${ENGINE_VERSION},${ENGINE_IMAGE}:latest"
+              elif docker manifest inspect "${ENGINE_IMAGE}:${ENGINE_VERSION}" >/dev/null 2>&1; then
+                echo "stirling-engine:${ENGINE_VERSION} already on GHCR — skipping"
+              else
+                echo "stirling-engine:${ENGINE_VERSION} is new — will publish"
+                mode="stable"
+                tags="${ENGINE_IMAGE}:${ENGINE_VERSION},${ENGINE_IMAGE}:latest"
+              fi
+              ;;
+            refs/heads/main|refs/heads/testMain)
+              published_hash=$(read_published_hash "${ENGINE_IMAGE}:alpha")
+              if [ "${FORCE_REBUILD}" = "true" ]; then
+                echo "force_engine_rebuild=true — rebuilding :alpha regardless"
+                mode="alpha"
+                tags="${ENGINE_IMAGE}:alpha"
+              elif [ -n "$published_hash" ] && [ "$published_hash" = "$ENGINE_HASH" ]; then
+                echo "Published :alpha source hash matches (${published_hash}) — skipping"
+              else
+                if [ -z "$published_hash" ]; then
+                  echo ":alpha has no source-hash annotation (first publish) — will publish"
+                else
+                  echo "Source hash changed (was ${published_hash}, now ${ENGINE_HASH}) — will publish"
+                fi
+                mode="alpha"
+                tags="${ENGINE_IMAGE}:alpha"
+              fi
+              ;;
+            *)
+              echo "Branch ${GH_REF} does not publish engine image"
+              ;;
+          esac
+          echo "mode=${mode}" >> "$GITHUB_OUTPUT"
+          echo "tags=${tags}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push engine image
+        id: build-push-engine
+        if: env.RUN_ENGINE == 'true' && steps.engineDecision.outputs.mode != 'skip'
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: .
+          file: ./engine/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-engine
+          cache-to: type=gha,mode=max,scope=stirling-engine
+          tags: ${{ steps.engineDecision.outputs.tags }}
+          # Manifest annotation read by the decision step above to detect drift.
+          annotations: |
+            index:org.stirlingpdf.engine-source-hash=${{ steps.engineHash.outputs.hash }}
+          platforms: linux/amd64,linux/arm64/v8
+          provenance: true
+          sbom: true
+
+      - name: Sign engine image
+        if: env.RUN_ENGINE == 'true' && steps.engineDecision.outputs.mode == 'stable'
+        env:
+          DIGEST: ${{ steps.build-push-engine.outputs.digest }}
+          TAGS: ${{ steps.engineDecision.outputs.tags }}
+          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
+          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
+        run: |
+          if [ -n "$COSIGN_PRIVATE_KEY" ]; then
+            echo "$TAGS" | tr ',' '\n' | while read -r tag; do
+              cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
+            done
+          else
+            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping engine image signing"
+          fi
@@ -19,7 +19,7 @@ jobs:
      packages: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -35,7 +35,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -17,7 +17,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -30,7 +30,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -33,7 +33,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -37,7 +37,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -72,7 +72,7 @@ jobs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -134,7 +134,7 @@ jobs:
      SIGN_BUNDLE: ${{ inputs.sign && (matrix.platform == 'macos-15' && secrets.APPLE_CERTIFICATE != '' || github.ref == 'refs/heads/main') }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -703,7 +703,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden the runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -795,7 +795,7 @@ jobs:
    if: always()
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -34,7 +34,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -77,7 +77,7 @@ jobs:
            cache-scope: stirling-pdf-fat
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -217,7 +217,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -19,7 +19,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden runner
-        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -176,6 +176,8 @@ app/core/src/main/resources/static/images/google-drive.svg
 *.nar
 *.ear
 *.zip
+# Real backend archives the form-bundle reader is tested against.
+!frontend/editor/src/core/tools/formFill/__fixtures__/*.zip
 *.tar.gz
 *.rar
 *.db
@@ -375,13 +375,13 @@ tasks:
    desc: "Auto-fix code formatting"
    deps: [install]
    cmds:
-      - npx prettier --write .
+      - npx oxfmt --write .

  format:check:
    desc: "Check code formatting"
    deps: [install]
    cmds:
-      - npx prettier --check .
+      - npx oxfmt --check .

  fix:
    desc: "Auto-fix lint and format"
@@ -554,6 +554,7 @@ tasks:
    deps: [install, ":backend:swagger"]
    cmds:
      - npx tsx editor/scripts/generate-tool-api-types.mts --spec ../SwaggerDoc.json --output editor/src/core/types/toolApiTypes.ts --io-output editor/src/core/types/toolIO.ts
+      - task: format
    sources:
      - editor/scripts/generate-tool-api-types.mts
      - ../SwaggerDoc.json
@@ -563,9 +564,9 @@ tasks:

  tool-models:check:
    desc: "Fail if committed tool API types are out of date"
-    deps: [install, ":backend:swagger"]
    cmds:
-      - npx tsx editor/scripts/generate-tool-api-types.mts --spec ../SwaggerDoc.json --output editor/src/core/types/toolApiTypes.ts --io-output editor/src/core/types/toolIO.ts --check
+      - task: tool-models
+      - git diff --exit-code -- editor/src/core/types/toolApiTypes.ts editor/src/core/types/toolIO.ts

  licenses:generate:
    desc: "Generate frontend license report"
@@ -18,7 +18,7 @@ dependencies {
    api "org.apache.pdfbox:preflight:$pdfboxVersion"
    api 'com.github.junrar:junrar:8.0.0' // RAR archive support for CBR files
    api 'jakarta.servlet:jakarta.servlet-api:6.1.0'
-    api 'org.snakeyaml:snakeyaml-engine:3.0.1'
+    api 'org.snakeyaml:snakeyaml-engine:3.1.1'
    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3"
    // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
    api 'org.simplejavamail:simple-java-mail:9.3.2'
@@ -66,6 +66,7 @@ public class ApplicationProperties {
    private AutomaticallyGenerated automaticallyGenerated = new AutomaticallyGenerated();

    private Mail mail = new Mail();
+    private Mailbox mailbox = new Mailbox();
    private Telegram telegram = new Telegram();

    private Premium premium = new Premium();
@@ -1416,6 +1417,26 @@ public class ApplicationProperties {
        private Boolean sslCheckServerIdentity;
    }

+    /**
+     * OAuth configuration for external mailbox providers.
+     *
+     * @since 2.15.x
+     */
+    @Data
+    public static class Mailbox {
+        private Gmail gmail = new Gmail();
+
+        @Data
+        public static class Gmail {
+            private String clientId = "";
+            @ToString.Exclude private String clientSecret = "";
+            private String redirectUri = "";
+
+            /** Google account emails allowed to connect to Gmail; empty means all accounts. */
+            private List<String> allowedEmails = new ArrayList<>();
+        }
+    }
+
    /**
     * Telegram bot configuration properties.
     *
@@ -62,6 +62,15 @@ public class FormFieldWithCoordinates {
    @Schema(description = "Widget coordinates on each page (fields can have multiple widgets)")
    private List<WidgetCoordinates> widgets;

+    @Schema(description = "Maximum character count for a text field (/MaxLen); null when unset")
+    private Integer maxLength;
+
+    @Schema(
+            description =
+                    "Push button activation action as a spec string:"
+                            + " 'reset', 'print', 'uri:<url>' or 'submit:<url>'")
+    private String buttonActionSpec;
+
    /**
     * Coordinates for a single widget annotation (visual representation of the field). A field can
     * have multiple widgets if it appears on multiple pages.
@@ -94,5 +103,12 @@ public class FormFieldWithCoordinates {

        @Schema(description = "Font size in PDF points")
        private Float fontSize;
+
+        @Schema(
+                description =
+                        "CropBox height in PDF points. Lets the frontend reverse the backend's"
+                                + " Y-flip when sending new widget coordinates back for"
+                                + " create/modify operations.")
+        private Float cropBoxHeight;
    }
 }
@@ -3,14 +3,20 @@ package stirling.software.common.util;
 import java.io.IOException;
 import java.util.Arrays;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
 import java.util.function.Function;
+import java.util.regex.Pattern;
 import java.util.stream.Collectors;

 import org.apache.pdfbox.cos.COSName;
 import org.apache.pdfbox.pdmodel.graphics.color.PDColor;
 import org.apache.pdfbox.pdmodel.graphics.color.PDDeviceRGB;
+import org.apache.pdfbox.pdmodel.interactive.action.PDActionNamed;
+import org.apache.pdfbox.pdmodel.interactive.action.PDActionResetForm;
+import org.apache.pdfbox.pdmodel.interactive.action.PDActionSubmitForm;
+import org.apache.pdfbox.pdmodel.interactive.action.PDActionURI;
 import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationWidget;
 import org.apache.pdfbox.pdmodel.interactive.annotation.PDAppearanceCharacteristicsDictionary;
 import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
@@ -59,6 +65,24 @@ public enum FormFieldTypeSupport {
                List<String> options)
                throws IOException {
            PDTextField textField = (PDTextField) field;
+            if (definition.fontSize() != null && definition.fontSize() > 0) {
+                textField.setDefaultAppearance("/Helv " + definition.fontSize() + " Tf 0 g");
+            }
+            if (Boolean.TRUE.equals(definition.multiline())) {
+                textField.setMultiline(true);
+            }
+            // Comb field: evenly spaced character cells (e.g. SSN, phone). Requires
+            // a positive MaxLen and is mutually exclusive with multiline.
+            if (definition.maxLength() != null && definition.maxLength() > 0) {
+                textField.setMaxLen(definition.maxLength());
+                if (!Boolean.TRUE.equals(definition.multiline())) {
+                    try {
+                        textField.setComb(true);
+                    } catch (Exception e) {
+                        log.debug("Unable to set comb flag: {}", e.getMessage());
+                    }
+                }
+            }
            String defaultValue = Optional.ofNullable(definition.defaultValue()).orElse("");
            if (!defaultValue.isBlank()) {
                FormUtils.setTextValue(textField, defaultValue);
@@ -272,14 +296,108 @@ public enum FormFieldTypeSupport {
        PDTerminalField createField(PDAcroForm acroForm) {
            return new PDSignatureField(acroForm);
        }
+
+        @Override
+        boolean doesNotsupportsDefinitionCreation() {
+            return false;
+        }
+        // Empty signature placeholder: no value to apply (signed later by a sign tool).
    },
    BUTTON("button", "pushButton", PDPushButton.class) {
        @Override
        PDTerminalField createField(PDAcroForm acroForm) {
            return new PDPushButton(acroForm);
        }
+
+        @Override
+        boolean doesNotsupportsDefinitionCreation() {
+            return false;
+        }
+
+        @Override
+        void applyNewFieldDefinition(
+                PDTerminalField field,
+                FormUtils.NewFormFieldDefinition definition,
+                List<String> options)
+                throws IOException {
+            if (field.getWidgets().isEmpty()) {
+                return;
+            }
+            PDAnnotationWidget widget = field.getWidgets().get(0);
+
+            // Visible caption (/MK /CA).
+            String caption = definition.label();
+            if (caption == null || caption.isBlank()) {
+                caption = definition.name();
+            }
+            if (caption != null && !caption.isBlank()) {
+                PDAppearanceCharacteristicsDictionary mk = widget.getAppearanceCharacteristics();
+                if (mk == null) {
+                    mk = new PDAppearanceCharacteristicsDictionary(widget.getCOSObject());
+                    widget.setAppearanceCharacteristics(mk);
+                }
+                mk.setNormalCaption(caption);
+            }
+            widget.setPrinted(true);
+
+            applyButtonAction(widget, definition.buttonAction());
+        }
    };

+    /**
+     * Writes a push button's activation action from a "reset"/"print"/"uri:"/"submit:" spec,
+     * returning why it could not, or null on success. A blank spec clears the action.
+     */
+    public static String applyButtonAction(PDAnnotationWidget widget, String action) {
+        if (action == null) {
+            return null;
+        }
+        if (action.isBlank()) {
+            // An explicit blank clears the action rather than leaving the old one behind.
+            widget.getCOSObject().removeItem(COSName.A);
+            return null;
+        }
+        String spec = action.trim();
+        if (!ACTION_SPEC.matcher(spec).matches()) {
+            return "'" + action + "' is not a button action this editor understands";
+        }
+        // The editor emits "uri:" the moment that kind is picked, before a URL is typed; an
+        // empty target is not yet an action, so clear rather than write an inert one.
+        int colon = spec.indexOf(':');
+        if (colon >= 0 && spec.substring(colon + 1).isBlank()) {
+            widget.getCOSObject().removeItem(COSName.A);
+            return null;
+        }
+        try {
+            String lower = spec.toLowerCase(Locale.ROOT);
+            if (lower.equals("reset")) {
+                widget.getCOSObject().setItem(COSName.A, new PDActionResetForm().getCOSObject());
+            } else if (lower.equals("print")) {
+                PDActionNamed named = new PDActionNamed();
+                named.setN("Print");
+                widget.getCOSObject().setItem(COSName.A, named.getCOSObject());
+            } else if (lower.startsWith("uri:")) {
+                PDActionURI uri = new PDActionURI();
+                uri.setURI(spec.substring(4));
+                widget.getCOSObject().setItem(COSName.A, uri.getCOSObject());
+            } else if (lower.startsWith("submit:")) {
+                PDActionSubmitForm submit = new PDActionSubmitForm();
+                // Store the target URL on the action dictionary's /F entry.
+                submit.getCOSObject().setString(COSName.F, spec.substring(7));
+                widget.getCOSObject().setItem(COSName.A, submit.getCOSObject());
+            }
+            return null;
+        } catch (Exception e) {
+            log.debug("Unable to apply button action '{}': {}", action, e.getMessage());
+            return e.getMessage();
+        }
+    }
+
+    /** The spec forms applyButtonAction understands; anything else is reported, not dropped. */
+    private static final Pattern ACTION_SPEC =
+            Pattern.compile(
+                    "^(reset|print|uri:.*|submit:.*)$", Pattern.CASE_INSENSITIVE | Pattern.DOTALL);
+
    private static final Map<String, FormFieldTypeSupport> BY_TYPE =
            Arrays.stream(values())
                    .collect(
@@ -196,6 +196,7 @@ public class RequestUriUtils {
                || trimmedUri.startsWith("/api/v1/auth/login")
                || trimmedUri.startsWith("/api/v1/auth/refresh")
                || trimmedUri.startsWith("/api/v1/auth/logout")
+                || trimmedUri.startsWith("/api/v1/email/gmail/callback")
                || trimmedUri.startsWith(
                        "/api/v1/proprietary/ui-data/login") // Login page config (SSO providers +
                // enableLogin)
@@ -0,0 +1,116 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.List;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSArray;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.cos.COSObject;
+import org.apache.pdfbox.cos.COSObjectKey;
+import org.apache.pdfbox.cos.COSString;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.digitalsignature.PDSignature;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDComboBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDSignatureField;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/** Pins how a choice field's options survive a save, which real forms rely on. */
+class ChoiceOptionRoundTripTest {
+
+    private static PDComboBox combo(PDDocument document, List<String> options) throws IOException {
+        document.addPage(new PDPage(PDRectangle.A4));
+        PDAcroForm form = new PDAcroForm(document);
+        document.getDocumentCatalog().setAcroForm(form);
+        PDComboBox field = new PDComboBox(form);
+        field.setPartialName("state");
+        field.setOptions(options);
+        form.getFields().add(field);
+        return field;
+    }
+
+    @Test
+    @DisplayName("a whitespace-only option survives a load, save and reload")
+    void whitespaceOptionSurvivesRoundTrip() throws IOException {
+        List<String> options = List.of(" ", "Alabama", "Alaska");
+
+        byte[] first;
+        try (PDDocument document = new PDDocument();
+                ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            combo(document, options);
+            document.save(out);
+            first = out.toByteArray();
+        }
+        // The real path edits a document loaded from bytes, not one built in memory.
+        byte[] saved;
+        try (PDDocument loaded = Loader.loadPDF(first);
+                ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            loaded.save(out);
+            saved = out.toByteArray();
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDComboBox reread =
+                    (PDComboBox) reloaded.getDocumentCatalog().getAcroForm(null).getField("state");
+            assertEquals(
+                    options,
+                    reread.getOptionsExportValues(),
+                    "an option must not vanish because the writer made it indirect");
+        }
+    }
+
+    @Test
+    @DisplayName("an option stored as an indirect reference is still reported")
+    void indirectOptionIsStillReported() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            PDComboBox field = combo(document, List.of(" ", "Alabama"));
+
+            // Real forms reference option strings indirectly; the reader must follow the reference.
+            COSArray options = new COSArray();
+            options.add(new COSObject(new COSString(" "), new COSObjectKey(629, 0)));
+            options.add(new COSString("Alabama"));
+            field.getCOSObject().setItem(COSName.OPT, options);
+
+            // Every read path runs this repair first, which is where the reference is followed.
+            FormUtils.repairMissingWidgetPageReferences(document);
+
+            assertEquals(
+                    List.of(" ", "Alabama"),
+                    field.getOptionsExportValues(),
+                    "an indirectly stored option must not be dropped");
+        }
+    }
+
+    @Test
+    @DisplayName("a signature field reports no value rather than a JVM identity hash")
+    void signatureValueIsNotAnIdentityHash() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            document.addPage(new PDPage(PDRectangle.A4));
+            PDAcroForm form = new PDAcroForm(document);
+            document.getDocumentCatalog().setAcroForm(form);
+            PDSignatureField signature = new PDSignatureField(form);
+            signature.setPartialName("approval");
+            // Only a field that actually holds a signature hits getValueAsString's toString().
+            signature.setValue(new PDSignature());
+            form.getFields().add(signature);
+
+            List<FormUtils.FormFieldInfo> fields = FormUtils.extractFormFields(document);
+
+            FormUtils.FormFieldInfo field =
+                    fields.stream()
+                            .filter(f -> "approval".equals(f.name()))
+                            .findFirst()
+                            .orElseThrow();
+            // An identity hash differs per load, so the same document would describe itself twice.
+            assertNull(field.value(), "a signature has no text value");
+        }
+    }
+}
@@ -0,0 +1,62 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSArray;
+import org.apache.pdfbox.cos.COSDictionary;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/** A hostile or corrupt form must fail as a rejected request, never as a crashed thread. */
+class DeepFieldTreeTest {
+
+    private static byte[] chainOfKids(int depth) throws IOException {
+        try (PDDocument document = new PDDocument();
+                ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            document.addPage(new PDPage(PDRectangle.A4));
+            PDAcroForm form = new PDAcroForm(document);
+            document.getDocumentCatalog().setAcroForm(form);
+
+            COSDictionary root = new COSDictionary();
+            root.setString(COSName.T, "n0");
+            COSDictionary cursor = root;
+            for (int i = 1; i < depth; i++) {
+                COSDictionary kid = new COSDictionary();
+                kid.setString(COSName.T, "n" + i);
+                kid.setItem(COSName.PARENT, cursor);
+                COSArray kids = new COSArray();
+                kids.add(kid);
+                cursor.setItem(COSName.KIDS, kids);
+                cursor = kid;
+            }
+            cursor.setItem(COSName.FT, COSName.getPDFName("Tx"));
+
+            COSArray fields = new COSArray();
+            fields.add(root);
+            form.getCOSObject().setItem(COSName.FIELDS, fields);
+            document.save(out);
+            return out.toByteArray();
+        }
+    }
+
+    @Test
+    @DisplayName("a deeply nested field tree extracts without overflowing the stack")
+    void deepKidsChainDoesNotOverflow() throws IOException {
+        // 2000 is as deep as PDFBox's own writer can build here; beyond that the overflow is in
+        // the writer, not in extraction, so it is not something a read endpoint would hit.
+        byte[] pdf = chainOfKids(2000);
+
+        try (PDDocument document = Loader.loadPDF(pdf)) {
+            assertDoesNotThrow(() -> FormUtils.extractFormFieldsWithCoordinates(document));
+        }
+    }
+}
@@ -0,0 +1,201 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDRadioButton;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import stirling.software.common.model.FormFieldWithCoordinates;
+
+/** An edit that cannot be honoured must be refused and reported, never silently reshaped. */
+class FormEditSafetyTest {
+
+    private static PDDocument formWith(String name, String type) throws IOException {
+        PDDocument document = new PDDocument();
+        document.addPage(new PDPage(PDRectangle.A4));
+        document.getDocumentCatalog().setAcroForm(new PDAcroForm(document));
+        FormUtils.addNewFields(
+                document,
+                List.of(
+                        new FormUtils.NewFormFieldDefinition(
+                                name,
+                                null,
+                                type,
+                                0,
+                                50f,
+                                700f,
+                                200f,
+                                20f,
+                                null,
+                                null,
+                                type.equals("radio") ? List.of("a", "b") : null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null)));
+        return document;
+    }
+
+    private static FormUtils.ModifyFormFieldDefinition modify(
+            String target, String type, Float width, Float height) {
+        // Order: targetName, name, label, type, pageIndex, x, y, width, height, then the rest.
+        return new FormUtils.ModifyFormFieldDefinition(
+                target, null, null, type, null, null, null, width, height, null, null, null, null,
+                null, null, null, null, null, null);
+    }
+
+    @Test
+    @DisplayName("a type that cannot be rebuilt is refused instead of becoming a text field")
+    void unrebuildableTypeIsRefused() throws IOException {
+        try (PDDocument document = formWith("choice", "text")) {
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+
+            FormUtils.modifyFormFields(
+                    document, List.of(modify("choice", "radio", null, null)), skipped);
+
+            PDField field = document.getDocumentCatalog().getAcroForm(null).getField("choice");
+            assertFalse(skipped.isEmpty(), "the refusal must be reported to the caller");
+            assertFalse(
+                    field instanceof PDRadioButton,
+                    "it could not become a radio, so it must not claim to be one");
+            assertEquals(
+                    "text",
+                    FormUtils.extractFormFields(document).getFirst().type(),
+                    "the original field must survive untouched rather than be retyped");
+        }
+    }
+
+    @Test
+    @DisplayName("a field rebuilt as a checkbox gets an appearance so it can be ticked")
+    void rebuiltCheckboxIsUsable() throws IOException {
+        try (PDDocument document = formWith("agree", "text")) {
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+
+            FormUtils.modifyFormFields(
+                    document, List.of(modify("agree", "checkbox", null, null)), skipped);
+
+            PDField field = document.getDocumentCatalog().getAcroForm(null).getField("agree");
+            assertTrue(field instanceof PDCheckBox, "the rebuild should have produced a checkbox");
+            assertNotNull(
+                    field.getWidgets().getFirst().getAppearance(),
+                    "without an appearance the checkbox renders blank and cannot be ticked");
+        }
+    }
+
+    @Test
+    @DisplayName("a size of zero or infinity is refused rather than written into the page")
+    void unusableSizeIsRefused() throws IOException {
+        for (Float bad : new Float[] {0f, -5f, Float.POSITIVE_INFINITY, Float.NaN}) {
+            try (PDDocument document = formWith("box", "text")) {
+                List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+
+                FormUtils.modifyFormFields(
+                        document, List.of(modify("box", null, bad, 20f)), skipped);
+
+                PDRectangle rect =
+                        document.getDocumentCatalog()
+                                .getAcroForm(null)
+                                .getField("box")
+                                .getWidgets()
+                                .getFirst()
+                                .getRectangle();
+                assertFalse(skipped.isEmpty(), "a refused resize must be reported: width " + bad);
+                assertEquals(
+                        200f,
+                        rect.getWidth(),
+                        0.01f,
+                        "the original size must survive: width " + bad);
+            }
+        }
+    }
+
+    @Test
+    @DisplayName("a widget off the page still reports its geometry instead of dropping the field")
+    void offPageWidgetKeepsItsGeometry() throws IOException {
+        try (PDDocument document = formWith("stray", "text")) {
+            PDField field = document.getDocumentCatalog().getAcroForm(null).getField("stray");
+            // Above the page top: legal PDF, and the user needs the coordinates to drag it back.
+            field.getWidgets().getFirst().setRectangle(new PDRectangle(50f, 2000f, 200f, 20f));
+
+            List<FormFieldWithCoordinates> fields =
+                    FormUtils.extractFormFieldsWithCoordinates(document);
+
+            FormFieldWithCoordinates stray =
+                    fields.stream()
+                            .filter(f -> "stray".equals(f.getName()))
+                            .findFirst()
+                            .orElseThrow();
+            assertNotNull(stray.getWidgets(), "the field must keep its widget list");
+            assertFalse(stray.getWidgets().isEmpty(), "the off-page widget must still be reported");
+            assertNotNull(stray.getWidgets().getFirst(), "a null entry would crash the overlay");
+        }
+    }
+
+    private static FormUtils.ModifyFormFieldDefinition withValue(String target, String value) {
+        return new FormUtils.ModifyFormFieldDefinition(
+                target, null, null, null, null, null, null, null, null, null, null, null, value,
+                null, null, null, null, null, null);
+    }
+
+    private static FormUtils.ModifyFormFieldDefinition withOptions(
+            String target, List<String> options) {
+        return new FormUtils.ModifyFormFieldDefinition(
+                target, null, null, null, null, null, null, null, null, null, null, options, null,
+                null, null, null, null, null, null);
+    }
+
+    @Test
+    @DisplayName("a value a radio group cannot hold does not destroy the group")
+    void badRadioValueLeavesTheGroupIntact() throws IOException {
+        try (PDDocument document = formWith("plan", "radio")) {
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+
+            FormUtils.modifyFormFields(
+                    document, List.of(withValue("plan", "not-an-option")), skipped);
+
+            PDField field = document.getDocumentCatalog().getAcroForm(null).getField("plan");
+            assertTrue(
+                    field instanceof PDRadioButton,
+                    "a rejected value must not turn the group into another kind of field");
+            assertEquals(
+                    2,
+                    field.getWidgets().size(),
+                    "the group's options must survive a rejected value");
+            assertFalse(skipped.isEmpty(), "the caller must be told the value was not applied");
+        }
+    }
+
+    @Test
+    @DisplayName("editing a radio group's options is either applied or reported, never ignored")
+    void radioOptionEditIsNotSilentlyDropped() throws IOException {
+        try (PDDocument document = formWith("plan", "radio")) {
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+
+            FormUtils.modifyFormFields(
+                    document, List.of(withOptions("plan", List.of("a", "b", "c"))), skipped);
+
+            PDField field = document.getDocumentCatalog().getAcroForm(null).getField("plan");
+            boolean applied = field.getWidgets().size() == 3;
+            assertTrue(
+                    applied || !skipped.isEmpty(),
+                    "a change the UI shows as saved must either happen or be reported as skipped");
+        }
+    }
+}
@@ -0,0 +1,61 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * A field name is caller-supplied and reaches several loggers. A line break in one would forge a
+ * second log line (CWE-117), so names carrying control characters are refused outright.
+ */
+class FormFieldNameSafetyTest {
+
+    @Test
+    void aNameWithCrLfIsRefused() {
+        String forged = "evil\r\n2026-01-01 00:00:00 ERROR admin login from 1.2.3.4";
+        String reason = FormUtils.invalidFieldNameReason(forged);
+        assertNotNull(reason, "a name containing CR/LF must be refused");
+        assertFalse(reason.contains("\n"), "the refusal itself must not carry a line break");
+        assertFalse(reason.contains("\r"), "the refusal itself must not carry a carriage return");
+    }
+
+    @Test
+    void otherControlCharactersAreRefusedToo() {
+        assertNotNull(FormUtils.invalidFieldNameReason("tab\there"));
+        assertNotNull(FormUtils.invalidFieldNameReason("null\u0000byte"));
+    }
+
+    @Test
+    void ordinaryNamesStillPass() {
+        assertNull(FormUtils.invalidFieldNameReason("Full Name"));
+        assertNull(FormUtils.invalidFieldNameReason("weird/[]{}"));
+        assertNull(FormUtils.invalidFieldNameReason("Mr Smith"));
+    }
+
+    @Test
+    void thePeriodRefusalDoesNotEchoControlCharacters() {
+        // Both problems at once: the period branch must not leak the raw name into a log line.
+        String reason = FormUtils.invalidFieldNameReason("Customer.Name\r\nFORGED");
+        assertNotNull(reason);
+        assertFalse(reason.contains("\r") || reason.contains("\n"), "no raw line break: " + reason);
+    }
+
+    @Test
+    void sanitizeForLogFlattensControlCharacters() {
+        assertEquals("a b", FormUtils.sanitizeForLog("a\nb"));
+        assertEquals("a b", FormUtils.sanitizeForLog("a\rb"));
+        assertEquals("plain", FormUtils.sanitizeForLog("plain"));
+        assertNull(FormUtils.sanitizeForLog(null));
+    }
+
+    @Test
+    void aPeriodIsStillRefusedWithTheOffendingCharacterNamed() {
+        String reason = FormUtils.invalidFieldNameReason("Customer.Name");
+        assertNotNull(reason);
+        assertTrue(reason.contains("period"), "the message should name the problem: " + reason);
+    }
+}
@@ -130,13 +130,15 @@ class FormFieldTypeSupportTest {
    }

    @Test
-    void doesNotSupportsDefinitionCreation_signatureReturnsTrue() {
-        assertTrue(FormFieldTypeSupport.SIGNATURE.doesNotsupportsDefinitionCreation());
+    void doesNotSupportsDefinitionCreation_signatureReturnsFalse() {
+        // Signature placeholders are now creatable via the editor.
+        assertFalse(FormFieldTypeSupport.SIGNATURE.doesNotsupportsDefinitionCreation());
    }

    @Test
-    void doesNotSupportsDefinitionCreation_buttonReturnsTrue() {
-        assertTrue(FormFieldTypeSupport.BUTTON.doesNotsupportsDefinitionCreation());
+    void doesNotSupportsDefinitionCreation_buttonReturnsFalse() {
+        // Push buttons (with actions) are now creatable via the editor.
+        assertFalse(FormFieldTypeSupport.BUTTON.doesNotsupportsDefinitionCreation());
    }

    @Test
@@ -0,0 +1,911 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.PDResources;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationWidget;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAppearanceDictionary;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAppearanceEntry;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDNonTerminalField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDRadioButton;
+import org.apache.pdfbox.pdmodel.interactive.form.PDSignatureField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Guards the form editor against silently destroying a field it edits. Assertions run after a
+ * save/reload cycle because only the serialised document reflects what a viewer sees.
+ */
+class FormUtilsEditRegressionTest {
+
+    private static PDAcroForm setupForm(PDDocument document) {
+        document.addPage(new PDPage(PDRectangle.A4));
+        PDAcroForm acroForm = new PDAcroForm(document);
+        acroForm.setDefaultResources(new PDResources());
+        document.getDocumentCatalog().setAcroForm(acroForm);
+        return acroForm;
+    }
+
+    private static byte[] save(PDDocument document) throws IOException {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        document.save(baos);
+        return baos.toByteArray();
+    }
+
+    private static FormUtils.NewFormFieldDefinition newField(
+            String type, String name, float x, float y, float w, float h, List<String> options) {
+        return new FormUtils.NewFormFieldDefinition(
+                name, null, type, 0, x, y, w, h, null, null, options, null, null, null, null, null,
+                null, null);
+    }
+
+    /** Moves a field to a rect; null width/height leave the size alone. */
+    private static FormUtils.ModifyFormFieldDefinition moveTo(
+            String target, float x, float y, Float w, Float h) {
+        return new FormUtils.ModifyFormFieldDefinition(
+                target, null, null, null, 0, x, y, w, h, null, null, null, null, null, null, null,
+                null, null, null);
+    }
+
+    private static PDRectangle firstWidgetRect(PDAcroForm acroForm, String name) {
+        PDField field = acroForm.getField(name);
+        assertNotNull(field, "field '" + name + "' should exist");
+        return field.getWidgets().get(0).getRectangle();
+    }
+
+    /** The /AP /N state names on a widget. */
+    private static Set<String> normalStateNames(PDAnnotationWidget widget) {
+        PDAppearanceDictionary appearance = widget.getAppearance();
+        assertNotNull(appearance, "widget should have an /AP dictionary");
+        PDAppearanceEntry normal = appearance.getNormalAppearance();
+        assertNotNull(normal, "widget should have an /AP /N entry");
+        assertTrue(normal.isSubDictionary(), "a toggle needs per-state appearances");
+        return normal.getSubDictionary().keySet().stream()
+                .map(COSName::getName)
+                .collect(Collectors.toSet());
+    }
+
+    @Test
+    void movingCheckboxKeepsItFillable() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("checkbox", "agree", 50, 700, 14, 14, null)));
+            FormUtils.modifyFormFields(document, List.of(moveTo("agree", 200f, 400f, null, null)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("agree");
+            assertTrue(field instanceof PDCheckBox, "'agree' should still be a checkbox");
+            assertFalse(
+                    ((PDCheckBox) field).getOnValue().isEmpty(),
+                    "a moved checkbox must keep an on-state, or it can never be ticked again");
+            assertTrue(
+                    normalStateNames(field.getWidgets().get(0)).size() >= 2,
+                    "both /AP /N states must survive a move");
+            PDRectangle rect = firstWidgetRect(acroForm, "agree");
+            assertEquals(200f, rect.getLowerLeftX(), 0.5f);
+            assertEquals(400f, rect.getLowerLeftY(), 0.5f);
+        }
+    }
+
+    @Test
+    void resizingCheckboxRebuildsAppearanceAtTheNewSize() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("checkbox", "agree", 50, 700, 14, 14, null)));
+            FormUtils.modifyFormFields(document, List.of(moveTo("agree", 50f, 700f, 28f, 28f)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDCheckBox checkBox = (PDCheckBox) acroForm.getField("agree");
+            assertFalse(
+                    checkBox.getOnValue().isEmpty(), "a resized checkbox must keep its on-state");
+            PDAnnotationWidget widget = checkBox.getWidgets().get(0);
+            assertTrue(normalStateNames(widget).size() >= 2, "both /AP /N states must be rebuilt");
+            PDRectangle bbox =
+                    widget.getAppearance()
+                            .getNormalAppearance()
+                            .getSubDictionary()
+                            .get(COSName.getPDFName(checkBox.getOnValue()))
+                            .getBBox();
+            assertEquals(28f, bbox.getWidth(), 0.5f, "the rebuilt /AP must match the new size");
+        }
+    }
+
+    /** applyToggleAppearance parks /AS on Off, so a resize must put the selection back. */
+    @Test
+    void resizingCheckboxKeepsItChecked() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("checkbox", "agree", 50, 700, 14, 14, null)));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            ((PDCheckBox) form.getField("agree")).check();
+            FormUtils.modifyFormFields(document, List.of(moveTo("agree", 50f, 700f, 30f, 30f)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertTrue(
+                    ((PDCheckBox) acroForm.getField("agree")).isChecked(),
+                    "a resize must not silently untick the box");
+        }
+    }
+
+    /** Only widgets.get(0) used to move, so a radio group lost every option but the first. */
+    @Test
+    void movingRadioGroupMovesEveryOption() throws IOException {
+        byte[] saved;
+        float[] before = new float[6];
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(newField("radio", "choice", 50, 700, 14, 14, List.of("A", "B", "C"))));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            List<PDAnnotationWidget> widgets = form.getField("choice").getWidgets();
+            assertEquals(3, widgets.size(), "the fixture needs three option widgets");
+            for (int i = 0; i < 3; i++) {
+                before[i * 2] = widgets.get(i).getRectangle().getLowerLeftX();
+                before[i * 2 + 1] = widgets.get(i).getRectangle().getLowerLeftY();
+            }
+            FormUtils.modifyFormFields(document, List.of(moveTo("choice", 90f, 670f, null, null)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("choice");
+            assertTrue(field instanceof PDRadioButton, "'choice' should still be a radio group");
+            List<PDAnnotationWidget> widgets = field.getWidgets();
+            assertEquals(3, widgets.size(), "no option may be left behind");
+            float dx = 90f - before[0];
+            float dy = 670f - before[1];
+            for (int i = 0; i < 3; i++) {
+                PDRectangle rect = widgets.get(i).getRectangle();
+                assertEquals(
+                        before[i * 2] + dx,
+                        rect.getLowerLeftX(),
+                        0.5f,
+                        "option " + i + " should shift by the same delta");
+                assertEquals(before[i * 2 + 1] + dy, rect.getLowerLeftY(), 0.5f);
+            }
+        }
+    }
+
+    /** A signature's /AP is the signature, so it must never be dropped. */
+    @Test
+    void movingSignatureKeepsItsAppearance() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("signature", "sig", 50, 700, 120, 40, null)));
+            FormUtils.modifyFormFields(document, List.of(moveTo("sig", 60f, 600f, 140f, 50f)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertTrue(
+                    acroForm.getField("sig") instanceof PDSignatureField,
+                    "'sig' should still be a signature");
+            assertEquals(60f, firstWidgetRect(acroForm, "sig").getLowerLeftX(), 0.5f);
+        }
+    }
+
+    @Test
+    void invalidFieldNameReason_rejectsPeriodAndAllowsTheRest() {
+        String reason = FormUtils.invalidFieldNameReason("Customer.Name");
+        assertNotNull(reason, "a period must be refused, not silently dropped");
+        assertTrue(reason.contains("period"), "the message should name the offending character");
+        assertNull(FormUtils.invalidFieldNameReason("Has Space"));
+        assertNull(FormUtils.invalidFieldNameReason("weird/[]{}"));
+        assertNull(FormUtils.invalidFieldNameReason(null));
+    }
+
+    /** Dropped operations used to log a warning and still report success. */
+    @Test
+    void applyFieldEdits_reportsEveryDroppedOperation() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "present", 50, 700, 200, 20, null)));
+
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.applyFieldEdits(
+                    document,
+                    List.of(newField("text", "Bad.Name", 50, 600, 100, 20, null)),
+                    List.of(moveTo("ghost", 10f, 10f, null, null)),
+                    List.of("alsoGhost"),
+                    skipped);
+
+            assertEquals(3, skipped.size(), "each dropped operation should be reported");
+            assertTrue(skipped.stream().anyMatch(s -> "add".equals(s.operation())));
+            assertTrue(skipped.stream().anyMatch(s -> "modify".equals(s.operation())));
+            assertTrue(skipped.stream().anyMatch(s -> "delete".equals(s.operation())));
+            assertNotNull(
+                    document.getDocumentCatalog().getAcroForm(null).getField("present"),
+                    "the rest of the document must still be applied");
+        }
+    }
+
+    /** A clean batch must not report anything, or the UI would cry wolf on every save. */
+    @Test
+    void applyFieldEdits_reportsNothingWhenEverythingApplies() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.applyFieldEdits(
+                    document,
+                    List.of(newField("text", "fine", 50, 700, 200, 20, null)),
+                    List.of(),
+                    List.of(),
+                    skipped);
+            assertTrue(skipped.isEmpty(), "a fully applied batch reports no skips");
+        }
+    }
+
+    /** A drag must not normalise other options to the dragged widget's size. */
+    @Test
+    void movingRadioGroupKeepsEachOptionsOwnSize() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(newField("radio", "choice", 50, 700, 20, 20, List.of("A", "B"))));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            List<PDAnnotationWidget> widgets = form.getField("choice").getWidgets();
+            // Hand-authored groups legitimately have option boxes of differing size.
+            PDRectangle second = widgets.get(1).getRectangle();
+            widgets.get(1)
+                    .setRectangle(
+                            new PDRectangle(
+                                    second.getLowerLeftX(), second.getLowerLeftY(), 40f, 40f));
+            FormUtils.modifyFormFields(document, List.of(moveTo("choice", 90f, 700f, 20f, 20f)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            List<PDAnnotationWidget> widgets = acroForm.getField("choice").getWidgets();
+            assertEquals(
+                    40f,
+                    widgets.get(1).getRectangle().getWidth(),
+                    0.5f,
+                    "a pure drag must not shrink the other options");
+            assertEquals(90f, widgets.get(0).getRectangle().getLowerLeftX(), 0.5f);
+        }
+    }
+
+    /** With no /AP and no /Opt the on-state must come from /V, not the invented "Yes". */
+    @Test
+    void resizingCheckboxWithoutAppearanceKeepsItsExportValue() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("checkbox", "agree", 50, 700, 14, 14, null)));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            PDCheckBox box = (PDCheckBox) form.getField("agree");
+            // A NeedAppearances form exported by Word/LibreOffice looks exactly like this.
+            box.getWidgets().get(0).getCOSObject().removeItem(COSName.AP);
+            box.getCOSObject().setItem(COSName.V, COSName.getPDFName("On"));
+            FormUtils.modifyFormFields(document, List.of(moveTo("agree", 50f, 700f, 30f, 30f)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDCheckBox box = (PDCheckBox) acroForm.getField("agree");
+            assertEquals(
+                    "On",
+                    box.getOnValue(),
+                    "the export value must survive; inventing 'Yes' would orphan /V");
+            assertTrue(box.isChecked(), "the box was ticked and must stay ticked");
+        }
+    }
+
+    /** Renaming to the same qualified name is not a rename, so a nested field is not rejected. */
+    @Test
+    void renameProblem_ignoresAnUnchangedQualifiedName() {
+        assertNull(
+                FormUtils.renameProblem("Customer.Name", "Customer.Name"),
+                "a field standing still must not be rejected for its parent's period");
+        assertNull(FormUtils.renameProblem("plain", null));
+        assertNotNull(
+                FormUtils.renameProblem("plain", "New.Name"),
+                "an actual rename introducing a period must still be refused");
+    }
+
+    /** A nested field whose name box was left at its qualified name must still be modified. */
+    @Test
+    void modifyingNestedFieldKeepsWorkingWhenNameIsUntouched() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "Name", 50, 700, 200, 20, null)));
+            // Re-parent it so its qualified name legitimately contains a period.
+            PDNonTerminalField parent = new PDNonTerminalField(form);
+            parent.setPartialName("Customer");
+            PDField child = form.getField("Name");
+            parent.setChildren(List.of(child));
+            child.getCOSObject().setItem(COSName.PARENT, parent.getCOSObject());
+            form.setFields(List.of(parent));
+
+            FormUtils.ModifyFormFieldDefinition mod =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "Customer.Name",
+                            "Customer.Name",
+                            null,
+                            null,
+                            0,
+                            90f,
+                            600f,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(mod), skipped);
+            assertTrue(
+                    skipped.isEmpty(), "an untouched qualified name is not a rename: " + skipped);
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("Customer.Name");
+            assertNotNull(field, "the nested field must survive the edit");
+            assertEquals(90f, field.getWidgets().get(0).getRectangle().getLowerLeftX(), 0.5f);
+        }
+    }
+
+    /** Zero clears /MaxLen; null means unchanged, so it could never be removed otherwise. */
+    @Test
+    void maxLengthZeroClearsTheCombSetting() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            new FormUtils.NewFormFieldDefinition(
+                                    "code", null, "text", 0, 50f, 700f, 200f, 20f, null, null, null,
+                                    null, null, null, null, null, 8, null)));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            assertEquals(8, ((PDTextField) form.getField("code")).getMaxLen());
+
+            FormUtils.ModifyFormFieldDefinition clear =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "code", null, null, null, null, null, null, null, null, null, null,
+                            null, null, null, null, null, null, 0, null);
+            FormUtils.modifyFormFields(document, List.of(clear));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertEquals(
+                    -1,
+                    ((PDTextField) acroForm.getField("code")).getMaxLen(),
+                    "/MaxLen should be gone, not merely zero");
+        }
+    }
+
+    /** An unrecognised button action must be reported rather than silently ignored. */
+    @Test
+    void unknownButtonActionIsReported() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("button", "go", 50, 700, 100, 24, null)));
+
+            FormUtils.ModifyFormFieldDefinition mod =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "go",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            "launchTheMissiles");
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(mod), skipped);
+
+            assertEquals(1, skipped.size(), "an unusable action spec should be reported");
+            assertTrue(skipped.get(0).reason().contains("launchTheMissiles"));
+        }
+    }
+
+    /** Renaming a nested field must not re-parent it to the top level. */
+    @Test
+    void renamingNestedFieldKeepsItUnderItsParent() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "Name", 50, 700, 200, 20, null)));
+            PDNonTerminalField parent = new PDNonTerminalField(form);
+            parent.setPartialName("Customer");
+            PDField child = form.getField("Name");
+            parent.setChildren(List.of(child));
+            child.getCOSObject().setItem(COSName.PARENT, parent.getCOSObject());
+            form.setFields(List.of(parent));
+
+            FormUtils.ModifyFormFieldDefinition rename =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "Customer.Name",
+                            "Customer.Phone",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(rename), skipped);
+            assertTrue(
+                    skipped.isEmpty(), "a leaf rename under the same parent is legal: " + skipped);
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(
+                    acroForm.getField("Customer.Phone"),
+                    "the field should still live under Customer, not at the top level");
+            assertNull(acroForm.getField("Customer.Name"), "the old name should be gone");
+        }
+    }
+
+    /** One rejected action on a multi-widget button is one report, not one per widget. */
+    @Test
+    void unknownButtonActionIsReportedOncePerField() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("button", "go", 50, 700, 100, 24, null)));
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            PDField button = form.getField("go");
+            // Give it a second widget, as a button repeated on two pages would have.
+            PDAnnotationWidget extra = new PDAnnotationWidget();
+            extra.setRectangle(new PDRectangle(50, 600, 100, 24));
+            extra.getCOSObject().setItem(COSName.PARENT, button.getCOSObject());
+            List<PDAnnotationWidget> widgets = new ArrayList<>(button.getWidgets());
+            widgets.add(extra);
+            button.getCOSObject()
+                    .setItem(
+                            COSName.KIDS,
+                            new org.apache.pdfbox.cos.COSArray() {
+                                {
+                                    for (PDAnnotationWidget w : widgets) add(w.getCOSObject());
+                                }
+                            });
+
+            FormUtils.ModifyFormFieldDefinition mod =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "go",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            "launchTheMissiles");
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(mod), skipped);
+
+            assertEquals(1, skipped.size(), "one field, one report: " + skipped);
+        }
+    }
+
+    /** A clamped page index still creates the field, so it is not a dropped edit. */
+    @Test
+    void clampedPageIsNotReportedAsSkipped() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            new FormUtils.NewFormFieldDefinition(
+                                    "late", null, "text", 9, 50f, 700f, 100f, 20f, null, null, null,
+                                    null, null, null, null, null, null, null)),
+                    skipped);
+
+            assertNotNull(
+                    document.getDocumentCatalog().getAcroForm(null).getField("late"),
+                    "the field is created on the clamped page");
+            assertTrue(skipped.isEmpty(), "an applied edit must not appear as skipped: " + skipped);
+        }
+    }
+
+    /** Recreation builds a top-level field, so it must refuse rather than re-parent. */
+    @Test
+    void typeChangeOnNestedFieldIsRefusedNotSilentlyReparented() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "Name", 50, 700, 200, 20, null)));
+            PDNonTerminalField parent = new PDNonTerminalField(form);
+            parent.setPartialName("Customer");
+            PDField child = form.getField("Name");
+            parent.setChildren(List.of(child));
+            child.getCOSObject().setItem(COSName.PARENT, parent.getCOSObject());
+            form.setFields(List.of(parent));
+
+            FormUtils.ModifyFormFieldDefinition retype =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "Customer.Name",
+                            null,
+                            null,
+                            "checkbox",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(retype), skipped);
+
+            assertEquals(1, skipped.size(), "the refusal must be reported: " + skipped);
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(
+                    acroForm.getField("Customer.Name"),
+                    "the original nested field must be left intact");
+            assertNull(acroForm.getField("Name"), "nothing should be re-parented to the top level");
+        }
+    }
+
+    /** The editor emits "uri:" the moment that kind is picked, which must not fail the edit. */
+    @Test
+    void incompleteUrlActionClearsRatherThanFailing() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("button", "go", 50, 700, 100, 24, null)));
+
+            FormUtils.ModifyFormFieldDefinition pickUri =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "go", null, null, null, null, null, null, null, null, null, null, null,
+                            null, null, null, null, null, null, "uri:");
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(pickUri), skipped);
+
+            assertTrue(
+                    skipped.isEmpty(),
+                    "choosing a URL action before typing the URL is not an error: " + skipped);
+            PDField button = document.getDocumentCatalog().getAcroForm(null).getField("go");
+            assertNull(
+                    button.getWidgets().get(0).getCOSObject().getDictionaryObject(COSName.A),
+                    "an empty target must leave no action behind");
+        }
+    }
+
+    /** A real URL still writes a real action. */
+    @Test
+    void completeUrlActionIsApplied() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document);
+            FormUtils.addNewFields(
+                    document, List.of(newField("button", "go", 50, 700, 100, 24, null)));
+
+            FormUtils.ModifyFormFieldDefinition setUri =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "go",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            "uri:https://example.com");
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(setUri), skipped);
+
+            assertTrue(skipped.isEmpty(), "a complete spec applies cleanly: " + skipped);
+            PDField button = document.getDocumentCatalog().getAcroForm(null).getField("go");
+            assertNotNull(
+                    button.getWidgets().get(0).getCOSObject().getDictionaryObject(COSName.A),
+                    "the action should be written");
+        }
+    }
+
+    /** Builds a parent with the given terminal children already attached. */
+    private static PDNonTerminalField nest(
+            PDDocument document, PDAcroForm form, String parentName, String... childNames)
+            throws IOException {
+        List<FormUtils.NewFormFieldDefinition> defs = new ArrayList<>();
+        for (int i = 0; i < childNames.length; i++) {
+            defs.add(newField("text", childNames[i], 50, 700 - i * 40, 200, 20, null));
+        }
+        FormUtils.addNewFields(document, defs);
+
+        PDNonTerminalField parent = new PDNonTerminalField(form);
+        parent.setPartialName(parentName);
+        List<PDField> kids = new ArrayList<>();
+        for (String child : childNames) {
+            PDField field = form.getField(child);
+            field.getCOSObject().setItem(COSName.PARENT, parent.getCOSObject());
+            kids.add(field);
+        }
+        parent.setChildren(kids);
+        form.setFields(List.of(parent));
+        return parent;
+    }
+
+    /** A refused edit must not release the name the field still really has. */
+    @Test
+    void refusedNestedEditDoesNotFreeItsNameForALaterEdit() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = setupForm(document);
+            nest(document, form, "Customer", "Name", "Email");
+
+            // Edit 1 is refused (type change on a nested field). Edit 2 then asks for the
+            // name edit 1 still occupies, which must not be handed out.
+            FormUtils.ModifyFormFieldDefinition refused =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "Customer.Name",
+                            "Customer.Foo",
+                            null,
+                            "checkbox",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+            FormUtils.ModifyFormFieldDefinition rename =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "Customer.Email",
+                            "Customer.Name",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.modifyFormFields(document, List.of(refused, rename), skipped);
+
+            List<String> names = new ArrayList<>();
+            for (PDField f : document.getDocumentCatalog().getAcroForm(null).getFieldTree()) {
+                if (f instanceof PDTerminalField) names.add(f.getFullyQualifiedName());
+            }
+            assertEquals(
+                    names.size(),
+                    new java.util.HashSet<>(names).size(),
+                    "two fields must never share a qualified name: " + names);
+            assertTrue(
+                    names.contains("Customer.Name"), "the refused field keeps its name: " + names);
+        }
+    }
+
+    /** A group name occupies the namespace, so a new field must not be able to take it. */
+    @Test
+    void groupNamesParticipateInCollisionChecks() throws IOException {
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = setupForm(document);
+            nest(document, form, "Customer", "Name");
+
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "Customer", 50, 500, 100, 20, null)));
+
+            List<String> names = new ArrayList<>();
+            for (PDField f : document.getDocumentCatalog().getAcroForm(null).getFieldTree()) {
+                String fqn = f.getFullyQualifiedName();
+                if (fqn != null) names.add(fqn);
+            }
+            assertEquals(
+                    names.size(),
+                    new java.util.HashSet<>(names).size(),
+                    "the new field must not take the group's name: " + names);
+        }
+    }
+
+    /** "Customer." has no leaf, so it must be refused rather than become "Customer.field". */
+    @Test
+    void renameToBareParentPrefixIsRefused() {
+        assertNotNull(
+                FormUtils.renameProblem("Customer.Name", "Customer."),
+                "a name with nothing after the parent prefix is not a rename");
+        assertNull(FormUtils.renameProblem("Customer.Name", "Customer.Phone"));
+    }
+
+    /** A type change must leave the field on its own page, not relocate it to the last one. */
+    @Test
+    void typeChangeKeepsTheFieldOnItsPage() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(document);
+            for (int i = 0; i < 5; i++) {
+                document.addPage(new PDPage(PDRectangle.A4));
+            }
+            form.setDefaultResources(new PDResources());
+            document.getDocumentCatalog().setAcroForm(form);
+
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            new FormUtils.NewFormFieldDefinition(
+                                    "onPageTwo",
+                                    null,
+                                    "text",
+                                    1,
+                                    50f,
+                                    700f,
+                                    200f,
+                                    20f,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null)));
+
+            FormUtils.ModifyFormFieldDefinition retype =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "onPageTwo",
+                            null,
+                            null,
+                            "checkbox",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null);
+            FormUtils.modifyFormFields(document, List.of(retype));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("onPageTwo");
+            assertNotNull(field, "the retyped field should exist");
+            int page = -1;
+            for (int i = 0; i < reloaded.getNumberOfPages(); i++) {
+                for (var annot : reloaded.getPage(i).getAnnotations()) {
+                    if (annot.getCOSObject() == field.getWidgets().get(0).getCOSObject()) page = i;
+                }
+            }
+            assertEquals(
+                    1, page, "a retyped field must stay on its own page, not move to the last");
+        }
+    }
+}
@@ -0,0 +1,118 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.junit.jupiter.api.Test;
+
+/** An edit the backend cannot honour must be reported, not logged and reported as success. */
+class FormUtilsEditReportingTest {
+
+    private static FormUtils.NewFormFieldDefinition field(String type, String name) {
+        return new FormUtils.NewFormFieldDefinition(
+                name, name, type, 0, 60f, 700f, 120f, 20f, null, null, null, null, null, null, null,
+                null, null, null);
+    }
+
+    private static PDDocument blank() {
+        PDDocument document = new PDDocument();
+        document.addPage(new PDPage(PDRectangle.LETTER));
+        document.getDocumentCatalog().setAcroForm(new PDAcroForm(document));
+        return document;
+    }
+
+    @Test
+    void anUncreatableTypeIsReportedRatherThanSilentlyMadeText() throws IOException {
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        try (PDDocument document = blank()) {
+            FormUtils.addNewFields(document, List.of(field("nonsense", "mystery")), skipped);
+            PDAcroForm acroForm = document.getDocumentCatalog().getAcroForm(null);
+            assertTrue(
+                    acroForm.getFields().isEmpty(),
+                    "an unsupported type must not quietly become a text field");
+        }
+        assertEquals(1, skipped.size(), "the caller must be told: " + skipped);
+        assertTrue(skipped.get(0).reason().contains("nonsense"), skipped.get(0).reason());
+    }
+
+    @Test
+    void aLyingPageCountIsSurvivable() throws IOException {
+        // /Count overstates the tree, so getNumberOfPages() passes the guard but getPage throws.
+        byte[] broken =
+                ("%PDF-1.4\n"
+                                + "1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj\n"
+                                + "2 0 obj << /Type /Pages /Count 1 /Kids [] >> endobj\n"
+                                + "trailer << /Root 1 0 R >>\n")
+                        .getBytes(java.nio.charset.StandardCharsets.ISO_8859_1);
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        try (PDDocument document = Loader.loadPDF(broken)) {
+            // Must not throw; the field is reported as skipped instead.
+            FormUtils.addNewFields(document, List.of(field("text", "ghost")), skipped);
+        } catch (IOException loadFailure) {
+            // A parser that refuses the file outright is an equally acceptable outcome.
+            return;
+        }
+        assertFalse(skipped.isEmpty(), "an unreachable page must be reported, not thrown");
+    }
+
+    @Test
+    void aTwoWidgetCheckboxKeepsItsOnStateWhenMoved() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            document.addPage(new PDPage(PDRectangle.LETTER));
+            document.addPage(new PDPage(PDRectangle.LETTER));
+            document.getDocumentCatalog().setAcroForm(new PDAcroForm(document));
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            new FormUtils.NewFormFieldDefinition(
+                                    "agree",
+                                    "agree",
+                                    "checkbox",
+                                    0,
+                                    60f,
+                                    700f,
+                                    14f,
+                                    14f,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null,
+                                    null)),
+                    new ArrayList<>());
+            FormUtils.modifyFormFields(
+                    document,
+                    List.of(
+                            new FormUtils.ModifyFormFieldDefinition(
+                                    "agree", null, null, null, 0, 200f, 400f, null, null, null,
+                                    null, null, null, null, null, null, null, null, null)));
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            document.save(out);
+            saved = out.toByteArray();
+        }
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDCheckBox box = (PDCheckBox) acroForm.getField("agree");
+            assertNotNull(box);
+            assertFalse(box.getOnValue().isEmpty(), "a moved checkbox must stay tickable");
+        }
+    }
+}
@@ -0,0 +1,467 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.PDResources;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationWidget;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAppearanceDictionary;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAppearanceEntry;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDPushButton;
+import org.apache.pdfbox.pdmodel.interactive.form.PDRadioButton;
+import org.apache.pdfbox.pdmodel.interactive.form.PDSignatureField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDVariableText;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Assertions run after a save/reload cycle: PDFBox synthesises widgets for fields with no explicit
+ * {@code /Kids}, so only the serialised document reflects what a viewer sees.
+ */
+class FormUtilsEditingTest {
+
+    private static PDAcroForm setupForm(PDDocument document, PDRectangle pageSize) {
+        PDPage page = new PDPage(pageSize);
+        document.addPage(page);
+        PDAcroForm acroForm = new PDAcroForm(document);
+        acroForm.setDefaultResources(new PDResources());
+        document.getDocumentCatalog().setAcroForm(acroForm);
+        return acroForm;
+    }
+
+    private static byte[] save(PDDocument document) throws IOException {
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        document.save(baos);
+        return baos.toByteArray();
+    }
+
+    private static FormUtils.NewFormFieldDefinition newText(
+            String name, float x, float y, float w, float h) {
+        return new FormUtils.NewFormFieldDefinition(
+                name, null, "text", 0, x, y, w, h, null, null, null, null, null, null, null, null,
+                null, null);
+    }
+
+    private static FormUtils.NewFormFieldDefinition newField(
+            String type,
+            String name,
+            float x,
+            float y,
+            float w,
+            float h,
+            List<String> options,
+            Integer maxLength,
+            String buttonAction) {
+        return new FormUtils.NewFormFieldDefinition(
+                name,
+                null,
+                type,
+                0,
+                x,
+                y,
+                w,
+                h,
+                null,
+                null,
+                options,
+                null,
+                null,
+                null,
+                null,
+                null,
+                maxLength,
+                buttonAction);
+    }
+
+    private static PDRectangle firstWidgetRect(PDAcroForm acroForm, String name) {
+        PDField field = acroForm.getField(name);
+        assertNotNull(field, "field '" + name + "' should exist");
+        assertTrue(!field.getWidgets().isEmpty(), "field should have at least one widget");
+        return field.getWidgets().get(0).getRectangle();
+    }
+
+    /**
+     * PDAcroForm.refreshAppearances() never synthesizes /AP for the button family, so without an
+     * explicit appearance a created checkbox or radio renders blank and resolves to Off.
+     */
+    @Test
+    void addNewFields_givesToggleFieldsAppearanceStreamsAndKeepsTheirDefault() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField("checkbox", "agree", 50, 600, 20, 20, null, null, null),
+                            newField(
+                                    "radio",
+                                    "choice",
+                                    50,
+                                    500,
+                                    20,
+                                    20,
+                                    List.of("Yes", "No"),
+                                    null,
+                                    null),
+                            newText("fullname", 50, 400, 200, 24)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(acroForm);
+
+            // NeedAppearances=false means viewers trust our streams, so they must exist.
+            assertFalse(acroForm.getNeedAppearances(), "appearance generation should have run");
+
+            PDField checkBox = acroForm.getField("agree");
+            assertTrue(checkBox instanceof PDCheckBox);
+            assertEquals(
+                    Set.of("Off", "Yes"),
+                    normalStateNames(checkBox.getWidgets().get(0)),
+                    "checkbox needs an Off and an on-state appearance");
+
+            PDField radio = acroForm.getField("choice");
+            assertTrue(radio instanceof PDRadioButton);
+            assertEquals(2, radio.getWidgets().size());
+            assertEquals(Set.of("Off", "Yes"), normalStateNames(radio.getWidgets().get(0)));
+            assertEquals(Set.of("Off", "No"), normalStateNames(radio.getWidgets().get(1)));
+
+            // A text field's DA names /Helv; if /DR lacks that alias refreshAppearances throws for
+            // the whole form and every field above loses its appearance too.
+            PDField text = acroForm.getField("fullname");
+            assertNotNull(
+                    text.getWidgets().get(0).getAppearance().getNormalAppearance(),
+                    "text field should have a generated appearance");
+        }
+    }
+
+    /** The /AP /N state names on a widget. */
+    private static Set<String> normalStateNames(PDAnnotationWidget widget) {
+        PDAppearanceDictionary appearance = widget.getAppearance();
+        assertNotNull(appearance, "widget should have an /AP dictionary");
+        PDAppearanceEntry normal = appearance.getNormalAppearance();
+        assertNotNull(normal, "widget should have an /AP /N entry");
+        assertTrue(normal.isSubDictionary(), "a toggle needs per-state appearances");
+        return normal.getSubDictionary().keySet().stream()
+                .map(COSName::getName)
+                .collect(java.util.stream.Collectors.toSet());
+    }
+
+    @Test
+    void addNewFields_createsTextFieldAtRequestedRectangle() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(document, List.of(newText("created", 50, 700, 200, 20)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(acroForm, "AcroForm should exist after reload");
+            assertTrue(acroForm.getField("created") instanceof PDTextField);
+            PDRectangle rect = firstWidgetRect(acroForm, "created");
+            assertNotNull(rect, "created widget should keep its rectangle after reload");
+            assertEquals(50f, rect.getLowerLeftX(), 0.5f);
+            assertEquals(700f, rect.getLowerLeftY(), 0.5f);
+            assertEquals(200f, rect.getWidth(), 0.5f);
+            assertEquals(20f, rect.getHeight(), 0.5f);
+        }
+    }
+
+    @Test
+    void addNewFields_appliesCropBoxOffsetToCoordinates() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            // Shift the CropBox origin; the frontend sends CropBox-relative coords.
+            document.getPage(0).setCropBox(new PDRectangle(10, 20, 500, 700));
+            FormUtils.addNewFields(document, List.of(newText("shifted", 5, 5, 100, 15)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDRectangle rect = firstWidgetRect(acroForm, "shifted");
+            // Absolute = CropBox-relative + CropBox lower-left offset.
+            assertEquals(15f, rect.getLowerLeftX(), 0.5f);
+            assertEquals(25f, rect.getLowerLeftY(), 0.5f);
+        }
+    }
+
+    @Test
+    void addNewFields_appliesReadOnlyFontSizeAndMultiline() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.NewFormFieldDefinition def =
+                    new FormUtils.NewFormFieldDefinition(
+                            "opts",
+                            null,
+                            "text",
+                            0,
+                            10f,
+                            10f,
+                            120f,
+                            18f,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            18f,
+                            Boolean.TRUE,
+                            Boolean.TRUE,
+                            null,
+                            null);
+            FormUtils.addNewFields(document, List.of(def));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("opts");
+            assertNotNull(field);
+            assertTrue(field.isReadOnly(), "read-only flag should survive reload");
+            assertTrue(field instanceof PDTextField);
+            assertTrue(((PDTextField) field).isMultiline(), "multiline flag should survive reload");
+            String da = ((PDVariableText) field).getDefaultAppearance();
+            assertTrue(da.contains("18"), "default appearance should carry the font size: " + da);
+        }
+    }
+
+    @Test
+    void modifyFormFields_movesAndResizesWidget() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(document, List.of(newText("movable", 50, 700, 200, 20)));
+
+            FormUtils.ModifyFormFieldDefinition mod =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "movable", null, null, null, 0, 100f, 600f, 150f, 30f, null, null, null,
+                            null, null, null, null, null, null, null);
+            FormUtils.modifyFormFields(document, List.of(mod));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDRectangle rect = firstWidgetRect(acroForm, "movable");
+            assertEquals(100f, rect.getLowerLeftX(), 0.5f);
+            assertEquals(600f, rect.getLowerLeftY(), 0.5f);
+            assertEquals(150f, rect.getWidth(), 0.5f);
+            assertEquals(30f, rect.getHeight(), 0.5f);
+        }
+    }
+
+    @Test
+    void modifyFormFields_setsReadOnlyAndFontSize() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(document, List.of(newText("editable", 50, 700, 200, 20)));
+
+            FormUtils.ModifyFormFieldDefinition mod =
+                    new FormUtils.ModifyFormFieldDefinition(
+                            "editable",
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            null,
+                            22f,
+                            Boolean.TRUE,
+                            null,
+                            null,
+                            null);
+            FormUtils.modifyFormFields(document, List.of(mod));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("editable");
+            assertNotNull(field);
+            assertTrue(field.isReadOnly(), "read-only flag should survive reload");
+            String da = ((PDVariableText) field).getDefaultAppearance();
+            assertTrue(da.contains("22"), "font size should be reflected in DA: " + da);
+        }
+    }
+
+    @Test
+    void deleteFormFields_removesField() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            PDAcroForm acroForm = setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(document, List.of(newText("temp", 50, 700, 200, 20)));
+            FormUtils.deleteFormFields(document, List.of("temp"));
+            // After delete the AcroForm may still exist; the field must be gone.
+            if (acroForm != null) {
+                assertNull(acroForm.getField("temp"));
+            }
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertTrue(acroForm == null || acroForm.getField("temp") == null);
+        }
+    }
+
+    @Test
+    void addNewFields_createsRadioGroupWithOneWidgetPerOption() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField(
+                                    "radio",
+                                    "choice",
+                                    60,
+                                    700,
+                                    16,
+                                    16,
+                                    List.of("Yes", "No"),
+                                    null,
+                                    null)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDField field = acroForm.getField("choice");
+            assertNotNull(field, "radio field should exist");
+            assertTrue(field instanceof PDRadioButton, "should be a radio button group");
+            assertEquals(2, field.getWidgets().size(), "one widget per option");
+            assertTrue(((PDRadioButton) field).getExportValues().contains("Yes"));
+            assertTrue(((PDRadioButton) field).getExportValues().contains("No"));
+        }
+    }
+
+    @Test
+    void extractFormFields_prefersFieldNameOverFirstOptionForChoiceLabel() throws IOException {
+        // A radio group's label is its field name, not its first option, so the viewer label
+        // matches the name shown in the editor.
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField(
+                                    "radio",
+                                    "Choice",
+                                    60,
+                                    700,
+                                    16,
+                                    16,
+                                    List.of("Yes", "No"),
+                                    null,
+                                    null)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            FormUtils.FormFieldInfo choice =
+                    FormUtils.extractFormFields(reloaded).stream()
+                            .filter(f -> "Choice".equals(f.name()))
+                            .findFirst()
+                            .orElse(null);
+            assertNotNull(choice, "radio field should be extracted");
+            assertEquals(
+                    "Choice", choice.label(), "field name should win over the first option value");
+        }
+    }
+
+    @Test
+    void addNewFields_createsCombTextField() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "ssn", 50, 700, 200, 20, null, 9, null)));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDTextField field = (PDTextField) acroForm.getField("ssn");
+            assertNotNull(field);
+            assertEquals(9, field.getMaxLen(), "comb max length should persist");
+            assertTrue(field.isComb(), "comb flag should be set");
+        }
+    }
+
+    @Test
+    void addNewFields_createsSignatureAndButton() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField("signature", "sig", 50, 600, 200, 60, null, null, null),
+                            newField("button", "btn", 50, 500, 120, 24, null, null, "reset")));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertTrue(
+                    acroForm.getField("sig") instanceof PDSignatureField,
+                    "signature placeholder should exist");
+            assertTrue(
+                    acroForm.getField("btn") instanceof PDPushButton, "push button should exist");
+        }
+    }
+
+    @Test
+    void applyFieldEdits_addsModifiesAndDeletesInOnePass() throws IOException {
+        byte[] saved;
+        try (PDDocument document = new PDDocument()) {
+            setupForm(document, PDRectangle.A4);
+            FormUtils.addNewFields(document, List.of(newText("old", 50, 700, 200, 20)));
+
+            FormUtils.applyFieldEdits(
+                    document,
+                    List.of(newText("fresh", 50, 600, 200, 20)),
+                    List.of(),
+                    List.of("old"));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(acroForm.getField("fresh"), "added field should be present");
+            assertNull(acroForm.getField("old"), "deleted field should be gone");
+        }
+    }
+}
@@ -705,10 +705,20 @@ class FormUtilsGapTest {
                                "newName",
                                "New Label",
                                null, // keep type (text) -> in-place path
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
                                Boolean.TRUE,
                                null,
                                null,
                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
                                null);

                FormUtils.modifyFormFields(doc, List.of(mod));
@@ -731,7 +741,8 @@ class FormUtilsGapTest {

                FormUtils.ModifyFormFieldDefinition mod =
                        new FormUtils.ModifyFormFieldDefinition(
-                                "missing", null, null, null, null, null, null, null, null);
+                                "missing", null, null, null, null, null, null, null, null, null,
+                                null, null, null, null, null, null, null, null, null);

                FormUtils.modifyFormFields(doc, List.of(mod));

@@ -754,7 +765,8 @@ class FormUtilsGapTest {
                mods.add(null);
                mods.add(
                        new FormUtils.ModifyFormFieldDefinition(
-                                "  ", null, null, null, null, null, null, null, null));
+                                "  ", null, null, null, null, null, null, null, null, null, null,
+                                null, null, null, null, null, null, null, null));

                FormUtils.modifyFormFields(doc, mods);
                assertEquals(1, FormUtils.extractFormFields(doc).size());
@@ -285,13 +285,13 @@ class FormUtilsMoreTest {
        }

        @Test
-        void widgetOutOfBoundsYieldsNullCoordinateEntry() throws IOException {
+        void widgetOutOfBoundsStillReportsItsCoordinates() throws IOException {
            try (PDDocument doc = new PDDocument()) {
                SetupDocument setup = createBasicDocument(doc);
                PDTextField text = new PDTextField(setup.acroForm());
                text.setPartialName("offpage");
-                // Far below the page origin -> finalY exceeds bounds -> createWidgetCoordinates
-                // returns null, which is still added to the per-field widget list.
+                // Off the page is legal PDF; dropping it would leave the user unable to drag it
+                // back.
                attachWidget(setup, text, new PDRectangle(50, -5000, 200, 20));

                List<FormFieldWithCoordinates> fields =
@@ -301,7 +301,8 @@ class FormUtilsMoreTest {
                        fields.get(0).getWidgets();
                assertNotNull(widgets);
                assertEquals(1, widgets.size());
-                assertNull(widgets.get(0));
+                assertNotNull(widgets.get(0), "a null entry here crashes sorting and the overlay");
+                assertEquals(50f, widgets.get(0).getX(), 0.01f);
            }
        }

@@ -476,8 +477,18 @@ class FormUtilsMoreTest {
                                "combobox",
                                null,
                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
                                List.of("One", "Two"),
                                "One",
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
                                null);

                FormUtils.modifyFormFields(doc, List.of(mod));
@@ -505,10 +516,20 @@ class FormUtilsMoreTest {
                                null,
                                "listbox", // same type -> in-place path
                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
                                Boolean.TRUE,
                                List.of("X", "Y", "Z"),
                                null,
-                                "Choose items");
+                                "Choose items",
+                                null,
+                                null,
+                                null,
+                                null,
+                                null);

                FormUtils.modifyFormFields(doc, List.of(mod));

@@ -529,7 +550,25 @@ class FormUtilsMoreTest {

                FormUtils.ModifyFormFieldDefinition mod =
                        new FormUtils.ModifyFormFieldDefinition(
-                                "keep", null, null, "bogusType", null, null, null, null, null);
+                                "keep",
+                                null,
+                                null,
+                                "bogusType",
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null,
+                                null);

                FormUtils.modifyFormFields(doc, List.of(mod));
                // The field is preserved unchanged because the target type is unsupported.
@@ -554,7 +593,8 @@ class FormUtilsMoreTest {
                // Rename beta -> alpha; should be uniquified to avoid the collision.
                FormUtils.ModifyFormFieldDefinition mod =
                        new FormUtils.ModifyFormFieldDefinition(
-                                "beta", "alpha", null, null, null, null, null, null, null);
+                                "beta", "alpha", null, null, null, null, null, null, null, null,
+                                null, null, null, null, null, null, null, null, null);

                FormUtils.modifyFormFields(doc, List.of(mod));

@@ -575,7 +615,8 @@ class FormUtilsMoreTest {
                doc.addPage(new PDPage());
                FormUtils.ModifyFormFieldDefinition mod =
                        new FormUtils.ModifyFormFieldDefinition(
-                                "x", null, null, null, null, null, null, null, null);
+                                "x", null, null, null, null, null, null, null, null, null, null,
+                                null, null, null, null, null, null, null, null);
                FormUtils.modifyFormFields(doc, List.of(mod));
            }
        }
@@ -0,0 +1,102 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Most real PDFs have no AcroForm at all, so adding the very first field has to build one that
+ * PDFBox will accept.
+ */
+class FormUtilsNoAcroFormTest {
+
+    private static final Path PLAIN_PDF =
+            Path.of("src/test/resources/pdf-ingestion-fixtures/many-tables-test_stress.pdf");
+
+    private static FormUtils.NewFormFieldDefinition newField(
+            String type, String name, float y, List<String> options, String defaultValue) {
+        // name, label, type, pageIndex, x, y, width, height, required, multiSelect,
+        // options, defaultValue, tooltip, fontSize, readOnly, multiline, maxLength, buttonAction
+        return new FormUtils.NewFormFieldDefinition(
+                name,
+                name,
+                type,
+                0,
+                60f,
+                y,
+                200f,
+                20f,
+                null,
+                null,
+                options,
+                defaultValue,
+                null,
+                null,
+                null,
+                null,
+                null,
+                null);
+    }
+
+    private static PDDocument loadPlain() throws IOException {
+        return Loader.loadPDF(Files.readAllBytes(PLAIN_PDF));
+    }
+
+    @Test
+    void plainPdfReallyHasNoAcroForm() throws IOException {
+        try (PDDocument document = loadPlain()) {
+            assertNull(
+                    document.getDocumentCatalog().getAcroForm(null),
+                    "fixture must have no AcroForm or this test proves nothing");
+        }
+    }
+
+    @Test
+    void addsFirstFieldToAPdfWithNoAcroForm() throws IOException {
+        byte[] saved;
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        try (PDDocument document = loadPlain()) {
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField("text", "fullName", 700f, null, "Ada"),
+                            newField("checkbox", "agree", 660f, null, null),
+                            newField("radio", "contact", 600f, List.of("Email", "Post"), null)),
+                    skipped);
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            document.save(out);
+            saved = out.toByteArray();
+        }
+
+        assertTrue(skipped.isEmpty(), "no field should be skipped: " + skipped);
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            assertNotNull(acroForm, "an AcroForm should have been created");
+            assertNotNull(acroForm.getDefaultResources(), "/DR is required for variable text");
+            assertTrue(
+                    acroForm.getDefaultAppearance() != null
+                            && !acroForm.getDefaultAppearance().isBlank(),
+                    "/DA is required for variable text");
+            PDTextField text = (PDTextField) acroForm.getField("fullName");
+            assertNotNull(text, "the text field should exist");
+            assertEquals("Ada", text.getValueAsString());
+            assertNotNull(acroForm.getField("agree"));
+            assertNotNull(acroForm.getField("contact"));
+        }
+    }
+}
@@ -0,0 +1,175 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.List;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDRadioButton;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Option captions belong to the viewer, not the page. Drawing them into the content stream left
+ * orphan text behind on every move and delete, so these pin the page staying clean.
+ */
+class FormUtilsRadioCaptionTest {
+
+    private static FormUtils.NewFormFieldDefinition newField(
+            String type, String name, float x, float y, float w, float h, List<String> options) {
+        return new FormUtils.NewFormFieldDefinition(
+                name, null, type, 0, x, y, w, h, null, null, options, null, null, null, null, null,
+                null, null);
+    }
+
+    private static byte[] save(PDDocument document) throws IOException {
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        document.save(out);
+        return out.toByteArray();
+    }
+
+    private static PDDocument blankWithForm() {
+        PDDocument document = new PDDocument();
+        document.addPage(new PDPage(PDRectangle.LETTER));
+        document.getDocumentCatalog().setAcroForm(new PDAcroForm(document));
+        return document;
+    }
+
+    private static String textOf(byte[] pdf) throws IOException {
+        try (PDDocument reloaded = Loader.loadPDF(pdf)) {
+            return new PDFTextStripper().getText(reloaded);
+        }
+    }
+
+    @Test
+    void radioOptionsAreNotBakedIntoThePage() throws IOException {
+        byte[] saved;
+        try (PDDocument document = blankWithForm()) {
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField(
+                                    "radio",
+                                    "contact",
+                                    72,
+                                    600,
+                                    12,
+                                    12,
+                                    List.of("Email", "Telephone", "Post"))));
+            saved = save(document);
+        }
+
+        // The caption is the viewer's job; page content cannot follow a widget that moves.
+        String text = textOf(saved);
+        assertFalse(text.contains("Email"), "options must not be page content: " + text);
+        assertFalse(text.contains("Telephone"), "options must not be page content: " + text);
+        assertFalse(text.contains("Post"), "options must not be page content: " + text);
+    }
+
+    @Test
+    void captionsDoNotReplaceTheWidgetsThemselves() throws IOException {
+        byte[] saved;
+        try (PDDocument document = blankWithForm()) {
+            FormUtils.addNewFields(
+                    document,
+                    List.of(newField("radio", "size", 72, 600, 12, 12, List.of("S", "M", "L"))));
+            saved = save(document);
+        }
+
+        try (PDDocument reloaded = Loader.loadPDF(saved)) {
+            PDAcroForm acroForm = reloaded.getDocumentCatalog().getAcroForm(null);
+            PDRadioButton radio = (PDRadioButton) acroForm.getField("size");
+            assertEquals(3, radio.getWidgets().size(), "one widget per option");
+            assertFalse(radio.getExportValues().isEmpty(), "export values must survive");
+        }
+    }
+
+    @Test
+    void aTextFieldDrawsNoStrayCaption() throws IOException {
+        // Control: proves the assertions above read the captions and not some unrelated content.
+        byte[] saved;
+        try (PDDocument document = blankWithForm()) {
+            FormUtils.addNewFields(
+                    document, List.of(newField("text", "fullName", 72, 600, 200, 18, null)));
+            saved = save(document);
+        }
+        assertTrue(textOf(saved).isBlank(), "a text field should add no page content");
+    }
+
+    @Test
+    void deletingARadioGroupTakesItsCaptionsWithIt() throws IOException {
+        byte[] withRadio;
+        try (PDDocument document = blankWithForm()) {
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            newField(
+                                    "radio",
+                                    "contact",
+                                    72,
+                                    600,
+                                    12,
+                                    12,
+                                    List.of("Email", "Telephone", "Post"))));
+            withRadio = save(document);
+        }
+        assertFalse(
+                textOf(withRadio).contains("Telephone"),
+                "the group adds no page text to begin with");
+
+        byte[] afterDelete;
+        try (PDDocument document = Loader.loadPDF(withRadio)) {
+            FormUtils.applyFieldEdits(document, List.of(), List.of(), List.of("contact"));
+            afterDelete = save(document);
+        }
+
+        String text = textOf(afterDelete);
+        assertFalse(
+                text.contains("Telephone"),
+                "a deleted radio group must not leave its captions on the page: " + text);
+    }
+
+    @Test
+    void theDrawnBoxIsTheWholeGroupNotOneOption() {
+        // A 90pt box used to become a 360pt stack because each option got the full height.
+        PDRectangle box = new PDRectangle(72f, 500f, 100f, 90f);
+        var rects = FormUtils.radioOptionRects(box, 3, null, null);
+
+        assertEquals(3, rects.size());
+        float top = rects.get(0).getUpperRightY();
+        float bottom = rects.get(2).getLowerLeftY();
+        assertEquals(90f, top - bottom, 0.01f, "the group must fill exactly the drawn height");
+        assertEquals(
+                box.getUpperRightY(), top, 0.01f, "the first option starts at the box's top edge");
+        for (PDRectangle r : rects) {
+            assertEquals(r.getWidth(), r.getHeight(), 0.01f, "options stay square");
+            assertTrue(r.getWidth() <= box.getWidth() + 0.01f, "an option never exceeds the box");
+        }
+    }
+
+    @Test
+    void explicitSizeAndGapWin() {
+        PDRectangle box = new PDRectangle(0f, 0f, 100f, 90f);
+        var rects = FormUtils.radioOptionRects(box, 3, 20f, 14f);
+        for (PDRectangle r : rects) {
+            assertEquals(14f, r.getHeight(), 0.01f, "the requested size is used verbatim");
+        }
+        float gap = rects.get(0).getLowerLeftY() - rects.get(1).getUpperRightY();
+        assertEquals(20f, gap, 0.01f, "the requested gap is used verbatim");
+    }
+
+    @Test
+    void aSingleOptionStillFitsTheBox() {
+        var rects = FormUtils.radioOptionRects(new PDRectangle(0f, 0f, 40f, 40f), 1, null, null);
+        assertEquals(1, rects.size());
+        assertTrue(rects.get(0).getHeight() <= 40f, "one option cannot exceed its box");
+    }
+}
@@ -0,0 +1,57 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/** A form with no default resources is ordinary; adding a field to it must still work. */
+class MissingDefaultResourcesTest {
+
+    @Test
+    @DisplayName("a text field can be added to a form that has no default resources")
+    void addsToFormWithoutDefaultResources() throws IOException {
+        // A real upload arrives as bytes, and plenty of forms in the wild carry no /DR at all.
+        byte[] pdf;
+        try (PDDocument built = new PDDocument();
+                java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream()) {
+            built.addPage(new PDPage(PDRectangle.A4));
+            PDAcroForm form = new PDAcroForm(built);
+            // A /DA naming a font with no /DR to resolve it is what PDFBox refuses.
+            form.setDefaultAppearance("/Helv 0 Tf 0 g");
+            form.getCOSObject().removeItem(org.apache.pdfbox.cos.COSName.DR);
+            built.getDocumentCatalog().setAcroForm(form);
+            built.save(out);
+            pdf = out.toByteArray();
+        }
+
+        try (PDDocument document = org.apache.pdfbox.Loader.loadPDF(pdf)) {
+
+            List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            new FormUtils.NewFormFieldDefinition(
+                                    "note", null, "text", 0, 50f, 700f, 200f, 20f, null, null, null,
+                                    null, null, null, null, null, null, null)),
+                    skipped);
+
+            assertTrue(
+                    skipped.isEmpty(),
+                    "adding a plain text field should not be refused: " + skipped);
+            assertEquals(
+                    1,
+                    FormUtils.extractFormFields(document).size(),
+                    "the field should be in the document");
+        }
+    }
+}
@@ -183,7 +183,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
                            "X-Page-Number",
                            "X-Page-Size",
                            "Content-Disposition",
-                            "Content-Type")
+                            "Content-Type",
+                            "X-Stirling-Skipped-Field-Edits",
+                            "X-Stirling-Skipped-Field-Edits-Total")
                    .allowCredentials(true)
                    .maxAge(3600);
        } else if (hasConfiguredOrigins) {
@@ -229,7 +231,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
                            "X-Page-Number",
                            "X-Page-Size",
                            "Content-Disposition",
-                            "Content-Type")
+                            "Content-Type",
+                            "X-Stirling-Skipped-Field-Edits",
+                            "X-Stirling-Skipped-Field-Edits-Total")
                    .allowCredentials(true)
                    .maxAge(3600);
        } else {
@@ -256,7 +260,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
                            "X-Page-Number",
                            "X-Page-Size",
                            "Content-Disposition",
-                            "Content-Type")
+                            "Content-Type",
+                            "X-Stirling-Skipped-Field-Edits",
+                            "X-Stirling-Skipped-Field-Edits-Total")
                    .allowCredentials(true)
                    .maxAge(3600);
        }
@@ -2,10 +2,20 @@ package stirling.software.SPDF.controller.api.form;

 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.StringWriter;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Base64;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
+import java.util.stream.Stream;
+import java.util.zip.CRC32;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipOutputStream;

 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.poi.ss.usermodel.*;
@@ -35,6 +45,7 @@ import stirling.software.common.model.FormFieldWithCoordinates;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.FormUtils;
+import stirling.software.common.util.TempFile;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.WebResponseUtils;

@@ -59,6 +70,25 @@ import tools.jackson.databind.ObjectMapper;
@RequiredArgsConstructor
 public class FormFillController {

+    /** Carries the edits a request asked for but the document could not take, as base64 JSON. */
+    public static final String SKIPPED_EDITS_HEADER = "X-Stirling-Skipped-Field-Edits";
+
+    /** How many were skipped in total, which may exceed the number listed in the header above. */
+    public static final String SKIPPED_EDITS_TOTAL_HEADER = "X-Stirling-Skipped-Field-Edits-Total";
+
+    /** Keeps the header well inside Jetty's response-header budget. */
+    private static final int MAX_REPORTED_SKIPS = 20;
+
+    /** Bytes of encoded header value, well under the container's limit for the whole header set. */
+    private static final int MAX_SKIP_HEADER_BYTES = 4096;
+
+    private static final int MAX_SKIP_FIELD_CHARS = 120;
+
+    /** Entry names inside the {@code ?includeFields=true} bundle. */
+    private static final String FIELDS_ENTRY = "fields.json";
+
+    private static final String DOCUMENT_ENTRY = "document.pdf";
+
    private final CustomPDFDocumentFactory pdfDocumentFactory;
    private final ObjectMapper objectMapper;
    private final TempFileManager tempFileManager;
@@ -68,6 +98,72 @@ public class FormFillController {
        return WebResponseUtils.pdfDocToWebResponse(document, baseName + ".pdf", tempFileManager);
    }

+    /**
+     * Rejects field names PDFBox cannot store before the document is touched, so the caller gets a
+     * 400 naming the offending character instead of a 200 with the field quietly missing.
+     */
+    private static void requireUsableFieldNames(
+            List<FormUtils.NewFormFieldDefinition> adds,
+            List<FormUtils.ModifyFormFieldDefinition> modifies) {
+        Stream<String> problems =
+                Stream.concat(
+                        adds.stream()
+                                .map(FormUtils.NewFormFieldDefinition::name)
+                                .map(FormUtils::invalidFieldNameReason),
+                        // A rename to the same name is not a rename, so a nested field whose
+                        // qualified name already contains a period is left alone.
+                        modifies.stream()
+                                .map(m -> FormUtils.renameProblem(m.targetName(), m.name())));
+        problems.filter(Objects::nonNull)
+                .findFirst()
+                .ifPresent(
+                        reason -> {
+                            throw ExceptionUtils.createIllegalArgumentException(
+                                    "error.invalidArgument", "{0}", reason);
+                        });
+    }
+
+    /**
+     * The body is the updated PDF, so dropped edits travel as a base64 JSON header;
+     * percent-encoding would turn every space into a plus sign.
+     */
+    private ResponseEntity<Resource> withSkippedEdits(
+            ResponseEntity<Resource> response, List<FormUtils.SkippedFieldEdit> skipped) {
+        if (skipped.isEmpty()) {
+            return response;
+        }
+        // A count cap alone is not enough: one very long field name can still overflow the
+        // header budget and turn the response into an error page, losing the edited PDF.
+        List<FormUtils.SkippedFieldEdit> reported = new ArrayList<>();
+        String encoded = "";
+        for (FormUtils.SkippedFieldEdit edit : skipped) {
+            if (reported.size() >= MAX_REPORTED_SKIPS) {
+                break;
+            }
+            reported.add(
+                    new FormUtils.SkippedFieldEdit(
+                            edit.operation(),
+                            FormUtils.abbreviate(edit.target(), MAX_SKIP_FIELD_CHARS),
+                            FormUtils.abbreviate(edit.reason(), MAX_SKIP_FIELD_CHARS)));
+            String candidate =
+                    Base64.getEncoder()
+                            .encodeToString(
+                                    objectMapper
+                                            .writeValueAsString(reported)
+                                            .getBytes(StandardCharsets.UTF_8));
+            if (candidate.length() > MAX_SKIP_HEADER_BYTES) {
+                reported.removeLast();
+                break;
+            }
+            encoded = candidate;
+        }
+        return ResponseEntity.status(response.getStatusCode())
+                .headers(response.getHeaders())
+                .header(SKIPPED_EDITS_TOTAL_HEADER, String.valueOf(skipped.size()))
+                .header(SKIPPED_EDITS_HEADER, encoded)
+                .body(response.getBody());
+    }
+
    private static String buildBaseName(MultipartFile file, String suffix) {
        String original = Filenames.toSimpleFileName(file.getOriginalFilename());
        if (original == null || original.isBlank()) {
@@ -257,6 +353,110 @@ public class FormFillController {
        }
    }

+    @PostMapping(value = "/add-fields", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Add new form fields",
+            description =
+                    "Creates new form fields in the provided PDF and returns the updated file")
+    public ResponseEntity<Resource> addFields(
+            @Parameter(
+                            description = "The input PDF file",
+                            required = true,
+                            content =
+                                    @Content(
+                                            mediaType = MediaType.APPLICATION_PDF_VALUE,
+                                            schema = @Schema(type = "string", format = "binary")))
+                    @RequestParam("file")
+                    MultipartFile file,
+            @Parameter(
+                            description = "JSON array of new field definitions",
+                            example =
+                                    "[{\"name\":\"NewField\",\"type\":\"text\",\"pageIndex\":0,"
+                                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20}]")
+                    @RequestPart(value = "fields", required = false)
+                    byte[] fieldsPayload)
+            throws IOException {
+
+        String rawFields = decodePart(fieldsPayload);
+        List<FormUtils.NewFormFieldDefinition> definitions =
+                FormPayloadParser.parseNewFieldDefinitions(objectMapper, rawFields);
+        if (definitions.isEmpty()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.dataRequired",
+                    "{0} must contain at least one definition",
+                    "fields payload");
+        }
+
+        requireUsableFieldNames(definitions, List.of());
+
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        return withSkippedEdits(
+                processSingleFile(
+                        file,
+                        "updated",
+                        document -> FormUtils.addNewFields(document, definitions, skipped)),
+                skipped);
+    }
+
+    @PostMapping(value = "/edit-fields", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Apply a batch of form field edits",
+            description =
+                    "Adds, modifies, and deletes form fields in a single request (one document"
+                            + " load/save) and returns the updated file")
+    public ResponseEntity<Resource> editFields(
+            @Parameter(
+                            description = "The input PDF file",
+                            required = true,
+                            content =
+                                    @Content(
+                                            mediaType = MediaType.APPLICATION_PDF_VALUE,
+                                            schema = @Schema(type = "string", format = "binary")))
+                    @RequestParam("file")
+                    MultipartFile file,
+            @Parameter(
+                            description =
+                                    "JSON object with optional 'add', 'modify' and 'delete'"
+                                            + " sections",
+                            example =
+                                    "{\"add\":[{\"name\":\"f\",\"type\":\"text\",\"pageIndex\":0,"
+                                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20}],"
+                                            + "\"modify\":[],\"delete\":[]}")
+                    @RequestPart(value = "edits", required = false)
+                    byte[] editsPayload,
+            @Parameter(
+                            description =
+                                    "Return a ZIP holding the updated PDF plus the field list it"
+                                            + " produced, instead of the bare PDF. Saves re-uploading"
+                                            + " the result just to read its fields back.")
+                    @RequestParam(value = "includeFields", defaultValue = "false")
+                    boolean includeFields)
+            throws IOException {
+
+        String rawEdits = decodePart(editsPayload);
+        FormUtils.FieldEditBatch batch = FormPayloadParser.parseFieldEdits(objectMapper, rawEdits);
+        if (batch.add().isEmpty() && batch.modify().isEmpty() && batch.delete().isEmpty()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.dataRequired", "{0} must contain at least one edit", "edits payload");
+        }
+        requireUsableFieldNames(batch.add(), batch.modify());
+
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        return withSkippedEdits(
+                processSingleFile(
+                        file,
+                        "updated",
+                        includeFields,
+                        document ->
+                                FormUtils.applyFieldEdits(
+                                        document,
+                                        batch.add(),
+                                        batch.modify(),
+                                        batch.delete(),
+                                        skipped)),
+                skipped);
+    }
+
    @PostMapping(value = "/modify-fields", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    @Operation(
            summary = "Modify existing form fields",
@@ -285,8 +485,15 @@ public class FormFillController {
                    "updates payload");
        }

-        return processSingleFile(
-                file, "updated", document -> FormUtils.modifyFormFields(document, modifications));
+        requireUsableFieldNames(List.of(), modifications);
+
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        return withSkippedEdits(
+                processSingleFile(
+                        file,
+                        "updated",
+                        document -> FormUtils.modifyFormFields(document, modifications, skipped)),
+                skipped);
    }

    @PostMapping(value = "/delete-fields", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@@ -319,8 +526,13 @@ public class FormFillController {
                    "error.dataRequired", "{0} must contain at least one value", "names payload");
        }

-        return processSingleFile(
-                file, "updated", document -> FormUtils.deleteFormFields(document, names));
+        List<FormUtils.SkippedFieldEdit> skipped = new ArrayList<>();
+        return withSkippedEdits(
+                processSingleFile(
+                        file,
+                        "updated",
+                        document -> FormUtils.deleteFormFields(document, names, skipped)),
+                skipped);
    }

    @PostMapping(value = "/fill", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@@ -358,13 +570,81 @@ public class FormFillController {

    private ResponseEntity<Resource> processSingleFile(
            MultipartFile file, String suffix, DocumentProcessor processor) throws IOException {
+        return processSingleFile(file, suffix, false, processor);
+    }
+
+    private ResponseEntity<Resource> processSingleFile(
+            MultipartFile file, String suffix, boolean includeFields, DocumentProcessor processor)
+            throws IOException {
        requirePdf(file);

        String baseName = buildBaseName(file, suffix);
        try (PDDocument document = pdfDocumentFactory.load(file)) {
            FormUtils.repairMissingWidgetPageReferences(document);
            processor.accept(document);
-            return saveDocument(document, baseName);
+            return includeFields
+                    ? saveDocumentWithFields(document, baseName)
+                    : saveDocument(document, baseName);
+        }
+    }
+
+    /**
+     * Answers "what fields does the saved file have?" from the document still open here, so the
+     * caller does not have to upload the result back to ask.
+     */
+    private ResponseEntity<Resource> saveDocumentWithFields(PDDocument document, String baseName)
+            throws IOException {
+        TempFile zip = null;
+        boolean zipTransferred = false;
+        try (TempFile pdf = tempFileManager.createManagedTempFile(".pdf")) {
+            document.save(pdf.getFile());
+            // Read the fields after the save so they describe the bytes actually being returned.
+            byte[] fields =
+                    objectMapper.writeValueAsBytes(
+                            FormUtils.extractFormFieldsWithCoordinates(document));
+            zip = tempFileManager.createManagedTempFile(".zip");
+            writeFieldBundle(zip.getPath(), pdf.getPath(), fields);
+            ResponseEntity<Resource> response =
+                    WebResponseUtils.zipFileToWebResponse(zip, baseName + ".zip");
+            zipTransferred = true;
+            return response;
+        } finally {
+            if (zip != null && !zipTransferred) {
+                zip.close();
+            }
+        }
+    }
+
+    /**
+     * Deflates the JSON because it is text, but stores the PDF: its streams are already compressed,
+     * so deflating costs ~25ms per MB to save a few percent.
+     */
+    private static void writeFieldBundle(Path zipPath, Path pdfPath, byte[] fields)
+            throws IOException {
+        long pdfSize = Files.size(pdfPath);
+        CRC32 crc = new CRC32();
+        try (InputStream in = Files.newInputStream(pdfPath)) {
+            byte[] buffer = new byte[8192];
+            for (int read; (read = in.read(buffer)) != -1; ) {
+                crc.update(buffer, 0, read);
+            }
+        }
+        try (ZipOutputStream zip = new ZipOutputStream(Files.newOutputStream(zipPath))) {
+            ZipEntry fieldsEntry = new ZipEntry(FIELDS_ENTRY);
+            fieldsEntry.setMethod(ZipEntry.DEFLATED);
+            zip.putNextEntry(fieldsEntry);
+            zip.write(fields);
+            zip.closeEntry();
+
+            ZipEntry documentEntry = new ZipEntry(DOCUMENT_ENTRY);
+            documentEntry.setMethod(ZipEntry.STORED);
+            documentEntry.setSize(pdfSize);
+            documentEntry.setCompressedSize(pdfSize);
+            documentEntry.setCrc(crc.getValue());
+            zip.putNextEntry(documentEntry);
+            Files.copy(pdfPath, zip);
+            zip.closeEntry();
+            zip.finish();
        }
    }

@@ -28,6 +28,8 @@ final class FormPayloadParser {
    private static final TypeReference<Map<String, Object>> MAP_TYPE = new TypeReference<>() {};
    private static final TypeReference<List<FormUtils.ModifyFormFieldDefinition>>
            MODIFY_FIELD_LIST_TYPE = new TypeReference<>() {};
+    private static final TypeReference<List<FormUtils.NewFormFieldDefinition>> NEW_FIELD_LIST_TYPE =
+            new TypeReference<>() {};
    private static final TypeReference<List<String>> STRING_LIST_TYPE = new TypeReference<>() {};

    private FormPayloadParser() {}
@@ -94,6 +96,43 @@ final class FormPayloadParser {
        return objectMapper.readValue(json, MODIFY_FIELD_LIST_TYPE);
    }

+    static List<FormUtils.NewFormFieldDefinition> parseNewFieldDefinitions(
+            ObjectMapper objectMapper, String json) {
+        if (json == null || json.isBlank()) {
+            return List.of();
+        }
+        return objectMapper.readValue(json, NEW_FIELD_LIST_TYPE);
+    }
+
+    /**
+     * Parses a combined edit batch: {@code {"add":[...],"modify":[...],"delete":[...]}}. Each
+     * section is optional. The delete section accepts the same shapes as {@link #parseNameList}.
+     */
+    static FormUtils.FieldEditBatch parseFieldEdits(ObjectMapper objectMapper, String json) {
+        if (json == null || json.isBlank()) {
+            return new FormUtils.FieldEditBatch(List.of(), List.of(), List.of());
+        }
+        final JsonNode root = objectMapper.readTree(json);
+        List<FormUtils.NewFormFieldDefinition> adds = List.of();
+        List<FormUtils.ModifyFormFieldDefinition> modifies = List.of();
+        List<String> deletes = List.of();
+        if (root != null && root.isObject()) {
+            final JsonNode addNode = root.get("add");
+            if (addNode != null && addNode.isArray()) {
+                adds = objectMapper.readValue(addNode.toString(), NEW_FIELD_LIST_TYPE);
+            }
+            final JsonNode modifyNode = root.get("modify");
+            if (modifyNode != null && modifyNode.isArray()) {
+                modifies = objectMapper.readValue(modifyNode.toString(), MODIFY_FIELD_LIST_TYPE);
+            }
+            final JsonNode deleteNode = root.get("delete");
+            if (deleteNode != null && !deleteNode.isNull()) {
+                deletes = parseNameList(objectMapper, deleteNode.toString());
+            }
+        }
+        return new FormUtils.FieldEditBatch(adds, modifies, deletes);
+    }
+
    static List<String> parseNameList(ObjectMapper objectMapper, String json) {
        if (json == null || json.isBlank()) {
            return List.of();
@@ -157,6 +157,15 @@ telegram:
      errorMessage: true # set to 'false' to hide/suppress error messages to users (to avoid spam)
      processing: true # set to 'false' to hide/suppress processing messages to users (to avoid spam)

+# Optional mailbox integration. Gmail OAuth is available in the proprietary build.
+# Prefer MAILBOX_GMAIL_CLIENT_ID and MAILBOX_GMAIL_CLIENT_SECRET in production.
+mailbox:
+  gmail:
+    client-id: "" # Google OAuth client ID
+    client-secret: "" # Google OAuth client secret; do not commit a real secret
+    redirect-uri: "" # Optional fixed public callback, e.g. https://pdf.example.com/api/v1/email/gmail/callback
+    allowed-emails: [] # Empty allows all Google accounts; otherwise only these accounts may connect
+
 legal:
  termsAndConditions: https://www.stirling.com/legal/terms-of-service # URL to the terms and conditions of your application (e.g. https://example.com/terms). Empty string to disable or filename to load from local file in static folder
  privacyPolicy: https://www.stirling.com/legal/privacy-policy # URL to the privacy policy of your application (e.g. https://example.com/privacy). Empty string to disable or filename to load from local file in static folder
@@ -17,7 +17,7 @@
        {
            "moduleName": "ch.qos.logback:logback-classic",
            "moduleUrl": "http://www.qos.ch",
-            "moduleVersion": "1.6.1",
+            "moduleVersion": "1.6.3",
            "moduleLicense": "LGPL-2.1-only",
            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
        },
@@ -31,7 +31,7 @@
        {
            "moduleName": "ch.qos.logback:logback-core",
            "moduleUrl": "http://www.qos.ch",
-            "moduleVersion": "1.6.1",
+            "moduleVersion": "1.6.3",
            "moduleLicense": "LGPL-2.1-only",
            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
        },
@@ -1064,21 +1064,14 @@
        {
            "moduleName": "io.swagger.core.v3:swagger-annotations-jakarta",
            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-annotations",
-            "moduleVersion": "2.2.46",
+            "moduleVersion": "2.2.47",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
        {
            "moduleName": "io.swagger.core.v3:swagger-annotations-jakarta",
            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-annotations",
-            "moduleVersion": "2.2.47",
-            "moduleLicense": "Apache License, Version 2.0",
-            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
-        },
-        {
-            "moduleName": "io.swagger.core.v3:swagger-core-jakarta",
-            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-core",
-            "moduleVersion": "2.2.46",
+            "moduleVersion": "2.2.53",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
@@ -1090,9 +1083,9 @@
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
        {
-            "moduleName": "io.swagger.core.v3:swagger-models-jakarta",
-            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-models",
-            "moduleVersion": "2.2.46",
+            "moduleName": "io.swagger.core.v3:swagger-core-jakarta",
+            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-core",
+            "moduleVersion": "2.2.53",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
@@ -1103,6 +1096,13 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
+        {
+            "moduleName": "io.swagger.core.v3:swagger-models-jakarta",
+            "moduleUrl": "https://github.com/swagger-api/swagger-core/modules/swagger-models",
+            "moduleVersion": "2.2.53",
+            "moduleLicense": "Apache License, Version 2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
+        },
        {
            "moduleName": "jakarta.activation:jakarta.activation-api",
            "moduleUrl": "https://www.eclipse.org",
@@ -2304,7 +2304,7 @@
        },
        {
            "moduleName": "org.simplejavamail:core-module",
-            "moduleVersion": "9.3.1",
+            "moduleVersion": "9.3.2",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
@@ -2317,13 +2317,13 @@
        },
        {
            "moduleName": "org.simplejavamail:outlook-module",
-            "moduleVersion": "9.3.1",
+            "moduleVersion": "9.3.2",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
        {
            "moduleName": "org.simplejavamail:simple-java-mail",
-            "moduleVersion": "9.3.1",
+            "moduleVersion": "9.3.2",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
@@ -2343,10 +2343,10 @@
        },
        {
            "moduleName": "org.snakeyaml:snakeyaml-engine",
-            "moduleUrl": "https://bitbucket.org/snakeyaml/snakeyaml-engine",
-            "moduleVersion": "3.0.1",
+            "moduleUrl": "https://codeberg.org/snakeyaml/snakeyaml-engine",
+            "moduleVersion": "3.1.1",
            "moduleLicense": "Apache License, Version 2.0",
-            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
        {
            "moduleName": "org.springdoc:springdoc-openapi-starter-common",
@@ -0,0 +1,374 @@
+package stirling.software.SPDF.controller.api.form;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipInputStream;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDNonTerminalField;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.core.io.Resource;
+import org.springframework.http.ResponseEntity;
+import org.springframework.mock.web.MockMultipartFile;
+
+import stirling.software.common.model.FormFieldWithCoordinates;
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.util.FormUtils;
+import stirling.software.common.util.TempFile;
+import stirling.software.common.util.TempFileManager;
+
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
+
+/**
+ * Drives ?includeFields=true across a spread of real form shapes, checking the bundled list stays
+ * interchangeable with the follow-up request it exists to remove.
+ */
+@ExtendWith(MockitoExtension.class)
+@DisplayName("edit-fields field bundle")
+class FormFieldBundleTest {
+
+    /** Set to a directory to dump the produced archives for the frontend reader's fixtures. */
+    private static final String FIXTURE_DIR = System.getProperty("bundle.fixtures");
+
+    @Mock private CustomPDFDocumentFactory pdfDocumentFactory;
+    @Mock private TempFileManager tempFileManager;
+    @InjectMocks private FormFillController controller;
+
+    private ObjectMapper objectMapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        lenient()
+                .when(tempFileManager.createManagedTempFile(anyString()))
+                .thenAnswer(
+                        invocation -> {
+                            File file =
+                                    Files.createTempFile(
+                                                    "bundle", invocation.<String>getArgument(0))
+                                            .toFile();
+                            TempFile temp = mock(TempFile.class);
+                            lenient().when(temp.getFile()).thenReturn(file);
+                            lenient().when(temp.getPath()).thenReturn(file.toPath());
+                            return temp;
+                        });
+        objectMapper = JsonMapper.builder().build();
+        var field = FormFillController.class.getDeclaredField("objectMapper");
+        field.setAccessible(true);
+        field.set(controller, objectMapper);
+    }
+
+    // -- document shapes ----------------------------------------------
+
+    private record Style(
+            String name, int pages, int rotation, List<FormUtils.NewFormFieldDefinition> fields) {}
+
+    private static FormUtils.NewFormFieldDefinition field(
+            String name, String type, int page, float y, List<String> options) {
+        return new FormUtils.NewFormFieldDefinition(
+                name, null, type, page, 50f, y, 200f, 20f, null, null, options, null, null, null,
+                null, null, null, null);
+    }
+
+    static List<Style> styles() {
+        List<Style> styles = new ArrayList<>();
+        styles.add(new Style("text-only", 1, 0, List.of(field("fullName", "text", 0, 700f, null))));
+        styles.add(
+                new Style(
+                        "checkbox-and-radio",
+                        1,
+                        0,
+                        List.of(
+                                field("agree", "checkbox", 0, 700f, null),
+                                field("plan", "radio", 0, 650f, List.of("basic", "pro")))));
+        styles.add(
+                new Style(
+                        "choice-widgets",
+                        1,
+                        0,
+                        List.of(
+                                field("country", "dropdown", 0, 700f, List.of("UK", "IE", "FR")),
+                                field("tags", "listbox", 0, 640f, List.of("a", "b", "c")))));
+        styles.add(
+                new Style(
+                        "signature", 1, 0, List.of(field("approval", "signature", 0, 700f, null))));
+        styles.add(
+                new Style(
+                        "multi-page",
+                        3,
+                        0,
+                        List.of(
+                                field("p1", "text", 0, 700f, null),
+                                field("p2", "text", 1, 700f, null),
+                                field("p3", "text", 2, 700f, null))));
+        styles.add(new Style("rotated-90", 1, 90, List.of(field("rot", "text", 0, 700f, null))));
+        styles.add(new Style("rotated-270", 1, 270, List.of(field("rot", "text", 0, 700f, null))));
+        styles.add(
+                new Style(
+                        "unicode-names",
+                        1,
+                        0,
+                        List.of(
+                                field("nom_complet", "text", 0, 700f, null),
+                                field("adresse postale", "text", 0, 660f, null))));
+
+        List<FormUtils.NewFormFieldDefinition> many = new ArrayList<>();
+        for (int i = 0; i < 120; i++) {
+            many.add(
+                    field(
+                            "field_" + i,
+                            i % 3 == 0 ? "checkbox" : "text",
+                            i / 40,
+                            740f - (i % 40) * 18f,
+                            null));
+        }
+        styles.add(new Style("many-fields", 3, 0, many));
+        return styles;
+    }
+
+    private byte[] blankPdf(int pages, int rotation) throws IOException {
+        try (PDDocument document = new PDDocument();
+                ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            for (int i = 0; i < pages; i++) {
+                PDPage page = new PDPage(PDRectangle.A4);
+                page.setRotation(rotation);
+                document.addPage(page);
+            }
+            document.getDocumentCatalog().setAcroForm(new PDAcroForm(document));
+            document.save(out);
+            return out.toByteArray();
+        }
+    }
+
+    // -- the test ------------------------------------------------------
+
+    @ParameterizedTest(name = "{0}")
+    @MethodSource("styles")
+    @DisplayName("bundled list matches the follow-up request it replaces")
+    void bundleMatchesRefetch(Style style) throws Exception {
+        byte[] source = blankPdf(style.pages(), style.rotation());
+        MockMultipartFile upload =
+                new MockMultipartFile("file", style.name() + ".pdf", "application/pdf", source);
+        byte[] edits = objectMapper.writeValueAsBytes(Map.of("add", style.fields()));
+
+        byte[] zipBytes;
+        try (PDDocument document = Loader.loadPDF(source)) {
+            when(pdfDocumentFactory.load(eq(upload))).thenReturn(document);
+            zipBytes = drain(controller.editFields(upload, edits, true));
+        }
+        Map<String, byte[]> bundle = unzip(zipBytes);
+
+        assertThat(bundle).containsKeys("document.pdf", "fields.json");
+        byte[] editedPdf = bundle.get("document.pdf");
+        assertThat(new String(editedPdf, 0, 5, StandardCharsets.UTF_8)).isEqualTo("%PDF-");
+
+        // The comparison that matters: ask the endpoint this feature stops re-calling,
+        // and demand a match.
+        MockMultipartFile saved =
+                new MockMultipartFile("file", style.name() + ".pdf", "application/pdf", editedPdf);
+        try (PDDocument reloaded = Loader.loadPDF(editedPdf)) {
+            when(pdfDocumentFactory.load(eq(saved), eq(true))).thenReturn(reloaded);
+            ResponseEntity<List<FormFieldWithCoordinates>> refetched =
+                    controller.listFieldsWithCoordinates(saved);
+            assertThat(new String(bundle.get("fields.json"), StandardCharsets.UTF_8))
+                    .isEqualTo(objectMapper.writeValueAsString(refetched.getBody()));
+        }
+
+        dumpFixture(style.name(), zipBytes);
+    }
+
+    @ParameterizedTest(name = "{0}")
+    @MethodSource("styles")
+    @DisplayName("pdf entry is stored and json entry is deflated")
+    void perEntryCompression(Style style) throws Exception {
+        byte[] source = blankPdf(style.pages(), style.rotation());
+        MockMultipartFile upload =
+                new MockMultipartFile("file", style.name() + ".pdf", "application/pdf", source);
+        byte[] edits = objectMapper.writeValueAsBytes(Map.of("add", style.fields()));
+
+        byte[] zipBytes;
+        try (PDDocument document = Loader.loadPDF(source)) {
+            when(pdfDocumentFactory.load(eq(upload))).thenReturn(document);
+            zipBytes = drain(controller.editFields(upload, edits, true));
+        }
+
+        Map<String, Integer> methods = methodsOf(zipBytes);
+        assertThat(methods.get("document.pdf")).isEqualTo(ZipEntry.STORED);
+        assertThat(methods.get("fields.json")).isEqualTo(ZipEntry.DEFLATED);
+    }
+
+    @Test
+    @DisplayName("hierarchical field names survive the bundle")
+    void nestedFieldNames() throws Exception {
+        byte[] source = nestedPdf();
+        MockMultipartFile upload =
+                new MockMultipartFile("file", "nested.pdf", "application/pdf", source);
+        byte[] edits =
+                objectMapper.writeValueAsBytes(
+                        Map.of(
+                                "modify",
+                                List.of(
+                                        Map.of(
+                                                "targetName",
+                                                "Customer.Name",
+                                                "defaultValue",
+                                                "Ada"))));
+
+        byte[] zipBytes;
+        try (PDDocument document = Loader.loadPDF(source)) {
+            when(pdfDocumentFactory.load(eq(upload))).thenReturn(document);
+            zipBytes = drain(controller.editFields(upload, edits, true));
+        }
+        Map<String, byte[]> bundle = unzip(zipBytes);
+        byte[] editedPdf = bundle.get("document.pdf");
+
+        MockMultipartFile saved =
+                new MockMultipartFile("file", "nested.pdf", "application/pdf", editedPdf);
+        try (PDDocument reloaded = Loader.loadPDF(editedPdf)) {
+            when(pdfDocumentFactory.load(eq(saved), eq(true))).thenReturn(reloaded);
+            ResponseEntity<List<FormFieldWithCoordinates>> refetched =
+                    controller.listFieldsWithCoordinates(saved);
+            String bundled = new String(bundle.get("fields.json"), StandardCharsets.UTF_8);
+            assertThat(bundled).contains("Customer.Name");
+            assertThat(bundled).isEqualTo(objectMapper.writeValueAsString(refetched.getBody()));
+        }
+    }
+
+    /** Builds a parent field with two children, which add-fields cannot express. */
+    private byte[] nestedPdf() throws IOException {
+        try (PDDocument document = Loader.loadPDF(blankPdf(1, 0));
+                ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+            PDAcroForm form = document.getDocumentCatalog().getAcroForm(null);
+            FormUtils.addNewFields(
+                    document,
+                    List.of(
+                            field("Name", "text", 0, 700f, null),
+                            field("Email", "text", 0, 660f, null)));
+
+            PDNonTerminalField parent = new PDNonTerminalField(form);
+            parent.setPartialName("Customer");
+            List<PDField> kids = new ArrayList<>();
+            for (String child : List.of("Name", "Email")) {
+                PDField kid = form.getField(child);
+                kid.getCOSObject().setItem(COSName.PARENT, parent.getCOSObject());
+                kids.add(kid);
+            }
+            parent.setChildren(kids);
+            form.setFields(List.of(parent));
+            document.save(out);
+            return out.toByteArray();
+        }
+    }
+
+    @Test
+    @DisplayName("bundle stays close to the wire cost of the two calls it replaces")
+    void wireCost() throws Exception {
+        Style style =
+                styles().stream()
+                        .filter(s -> s.name().equals("many-fields"))
+                        .findFirst()
+                        .orElseThrow();
+        byte[] source = blankPdf(style.pages(), style.rotation());
+        MockMultipartFile upload =
+                new MockMultipartFile("file", "cost.pdf", "application/pdf", source);
+        byte[] edits = objectMapper.writeValueAsBytes(Map.of("add", style.fields()));
+
+        byte[] zipBytes;
+        Map<String, byte[]> bundle;
+        try (PDDocument document = Loader.loadPDF(source)) {
+            when(pdfDocumentFactory.load(eq(upload))).thenReturn(document);
+            zipBytes = drain(controller.editFields(upload, edits, true));
+        }
+        bundle = unzip(zipBytes);
+
+        int pdfSize = bundle.get("document.pdf").length;
+        int jsonSize = bundle.get("fields.json").length;
+        System.out.printf(
+                "wire: pdf=%d json=%d zip=%d overhead=%d bytes (%.2f%% over the pdf alone)%n",
+                pdfSize,
+                jsonSize,
+                zipBytes.length,
+                zipBytes.length - pdfSize,
+                100.0 * (zipBytes.length - pdfSize) / pdfSize);
+
+        // True for a field list this repetitive; on a tiny list the ~200 bytes of zip framing can
+        // exceed what deflate saves, so this is a property of the fixture, not of every document.
+        assertThat(zipBytes.length).isLessThan(pdfSize + jsonSize);
+    }
+
+    // -- helpers -------------------------------------------------------
+
+    private static byte[] drain(ResponseEntity<Resource> response) throws IOException {
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        try (InputStream in = response.getBody().getInputStream()) {
+            in.transferTo(out);
+        }
+        return out.toByteArray();
+    }
+
+    private static Map<String, byte[]> unzip(byte[] zipBytes) throws IOException {
+        Map<String, byte[]> entries = new HashMap<>();
+        try (ZipInputStream in = new ZipInputStream(new ByteArrayInputStream(zipBytes))) {
+            for (ZipEntry entry; (entry = in.getNextEntry()) != null; ) {
+                ByteArrayOutputStream out = new ByteArrayOutputStream();
+                in.transferTo(out);
+                entries.put(entry.getName(), out.toByteArray());
+            }
+        }
+        return entries;
+    }
+
+    private static Map<String, Integer> methodsOf(byte[] zipBytes) throws IOException {
+        Map<String, Integer> methods = new HashMap<>();
+        try (ZipInputStream in = new ZipInputStream(new ByteArrayInputStream(zipBytes))) {
+            for (ZipEntry entry; (entry = in.getNextEntry()) != null; ) {
+                methods.put(entry.getName(), entry.getMethod());
+                in.transferTo(OutputStream.nullOutputStream());
+            }
+        }
+        return methods;
+    }
+
+    private static void dumpFixture(String name, byte[] zipBytes) throws IOException {
+        if (FIXTURE_DIR == null) {
+            return;
+        }
+        Path dir = Paths.get(FIXTURE_DIR);
+        Files.createDirectories(dir);
+        Files.write(dir.resolve(name + ".zip"), zipBytes);
+    }
+}
@@ -29,6 +29,7 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.mock.web.MockMultipartFile;

 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.util.FormUtils;
 import stirling.software.common.util.TempFile;
 import stirling.software.common.util.TempFileManager;

@@ -330,6 +331,160 @@ class FormFillControllerTest {
        }
    }

+    // ── addFields ──────────────────────────────────────────────────────
+
+    @Nested
+    @DisplayName("addFields")
+    class AddFields {
+
+        @Test
+        @DisplayName("throws when fields payload is null")
+        void nullPayload() {
+            assertThatThrownBy(() -> controller.addFields(pdfFile(), null))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+
+        @Test
+        @DisplayName("throws when fields payload is an empty list")
+        void emptyPayload() {
+            assertThatThrownBy(() -> controller.addFields(pdfFile(), "[]".getBytes()))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+
+        @Test
+        @DisplayName("processes a valid new-field payload")
+        void validPayload() throws Exception {
+            MockMultipartFile file = pdfFile();
+            PDDocument doc = createMinimalPdf();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(doc);
+
+            String json =
+                    "[{\"name\":\"NewField\",\"type\":\"text\",\"pageIndex\":0,"
+                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20}]";
+            ResponseEntity<Resource> response = controller.addFields(file, json.getBytes());
+
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+            assertThat(response.getBody()).isNotNull();
+        }
+    }
+
+    // ── editFields (combined) ──────────────────────────────────────────
+
+    @Nested
+    @DisplayName("editFields")
+    class EditFields {
+
+        @Test
+        @DisplayName("throws when edits payload is null")
+        void nullPayload() {
+            assertThatThrownBy(() -> controller.editFields(pdfFile(), null, false))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+
+        @Test
+        @DisplayName("throws when all sections are empty")
+        void emptyBatch() {
+            assertThatThrownBy(
+                            () ->
+                                    controller.editFields(
+                                            pdfFile(),
+                                            "{\"add\":[],\"modify\":[],\"delete\":[]}".getBytes(),
+                                            false))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+
+        @Test
+        @DisplayName("processes a combined add/delete batch")
+        void validBatch() throws Exception {
+            MockMultipartFile file = pdfFile();
+            PDDocument doc = createMinimalPdf();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(doc);
+
+            String json =
+                    "{\"add\":[{\"name\":\"f\",\"type\":\"text\",\"pageIndex\":0,\"x\":50,"
+                            + "\"y\":700,\"width\":200,\"height\":20}],\"modify\":[],"
+                            + "\"delete\":[]}";
+            ResponseEntity<Resource> response = controller.editFields(file, json.getBytes(), false);
+
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+            assertThat(response.getBody()).isNotNull();
+        }
+
+        @Test
+        @DisplayName("refuses a field name containing a period before touching the document")
+        void refusesPeriodInName() throws Exception {
+            String json =
+                    "{\"add\":[{\"name\":\"Customer.Name\",\"type\":\"text\",\"pageIndex\":0,"
+                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20}]}";
+
+            assertThatThrownBy(() -> controller.editFields(pdfFile(), json.getBytes(), false))
+                    .hasMessageContaining("period");
+            // Rejected up front, so the document is never even loaded.
+            verify(pdfDocumentFactory, never()).load(any(MockMultipartFile.class));
+        }
+
+        @Test
+        @DisplayName("renaming a nested field to its own qualified name is not a rename")
+        void allowsUnchangedQualifiedName() throws Exception {
+            MockMultipartFile file = pdfFile();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(createMinimalPdf());
+
+            String json =
+                    "{\"modify\":[{\"targetName\":\"Customer.Name\",\"name\":\"Customer.Name\","
+                            + "\"x\":10,\"y\":10}]}";
+            ResponseEntity<Resource> response = controller.editFields(file, json.getBytes(), false);
+
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+            // It must get past validation into the edit loop: the only complaint should be that
+            // this document has no such field, never that the name contains a period.
+            String encoded =
+                    response.getHeaders().getFirst(FormFillController.SKIPPED_EDITS_HEADER);
+            assertThat(encoded).isNotNull();
+            String report =
+                    new String(
+                            java.util.Base64.getDecoder().decode(encoded),
+                            java.nio.charset.StandardCharsets.UTF_8);
+            assertThat(report).contains("no field with that name exists").doesNotContain("period");
+        }
+
+        @Test
+        @DisplayName("reports a dropped edit as base64 JSON in the skipped-edits header")
+        void reportsSkippedEdits() throws Exception {
+            MockMultipartFile file = pdfFile();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(createMinimalPdf());
+
+            String json = "{\"delete\":[\"noSuchField\"]}";
+            ResponseEntity<Resource> response = controller.editFields(file, json.getBytes(), false);
+
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+            String encoded =
+                    response.getHeaders().getFirst(FormFillController.SKIPPED_EDITS_HEADER);
+            assertThat(encoded).isNotNull();
+            String report =
+                    new String(
+                            java.util.Base64.getDecoder().decode(encoded),
+                            java.nio.charset.StandardCharsets.UTF_8);
+            assertThat(report).contains("noSuchField").contains("delete");
+            // Base64 rather than percent-encoding, so spaces survive as spaces.
+            assertThat(report).contains("no field with that name exists");
+        }
+
+        @Test
+        @DisplayName("omits the skipped-edits header when everything applied")
+        void noHeaderOnCleanBatch() throws Exception {
+            MockMultipartFile file = pdfFile();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(createMinimalPdf());
+
+            String json =
+                    "{\"add\":[{\"name\":\"clean\",\"type\":\"text\",\"pageIndex\":0,\"x\":50,"
+                            + "\"y\":700,\"width\":200,\"height\":20}]}";
+            ResponseEntity<Resource> response = controller.editFields(file, json.getBytes(), false);
+
+            assertThat(response.getHeaders().getFirst(FormFillController.SKIPPED_EDITS_HEADER))
+                    .isNull();
+        }
+    }
+
    // ── buildBaseName ──────────────────────────────────────────────────

    @Nested
@@ -384,4 +539,156 @@ class FormFillControllerTest {
            assertThat(result).isEqualTo("document_filled");
        }
    }
+
+    // -- includeFields bundle ------------------------------------------
+
+    @Nested
+    @DisplayName("editFields ?includeFields=true")
+    class FieldBundle {
+
+        private byte[] editsPayload() {
+            return ("{\"add\":[{\"name\":\"bundled\",\"type\":\"text\",\"pageIndex\":0,"
+                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20}]}")
+                    .getBytes(java.nio.charset.StandardCharsets.UTF_8);
+        }
+
+        private java.util.Map<String, java.util.zip.ZipEntry> entriesOf(byte[] zipBytes)
+                throws IOException {
+            java.util.Map<String, java.util.zip.ZipEntry> found = new java.util.HashMap<>();
+            try (java.util.zip.ZipInputStream in =
+                    new java.util.zip.ZipInputStream(new java.io.ByteArrayInputStream(zipBytes))) {
+                for (java.util.zip.ZipEntry e; (e = in.getNextEntry()) != null; ) {
+                    java.io.ByteArrayOutputStream data = new java.io.ByteArrayOutputStream();
+                    in.transferTo(data);
+                    // getMethod/getSize are only final once the entry has been fully read.
+                    found.put(e.getName(), e);
+                    payloads.put(e.getName(), data.toByteArray());
+                }
+            }
+            return found;
+        }
+
+        private final java.util.Map<String, byte[]> payloads = new java.util.HashMap<>();
+
+        private byte[] bundleFor(MockMultipartFile file) throws Exception {
+            PDDocument doc = createMinimalPdf();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(doc);
+            ResponseEntity<Resource> response = controller.editFields(file, editsPayload(), true);
+            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+            return drainBody(response);
+        }
+
+        @Test
+        @DisplayName("returns a zip holding the pdf and the field list")
+        void bundlesBoth() throws Exception {
+            byte[] zip = bundleFor(pdfFile());
+            entriesOf(zip);
+
+            assertThat(payloads).containsKeys("document.pdf", "fields.json");
+            assertThat(new String(payloads.get("document.pdf"), 0, 5)).isEqualTo("%PDF-");
+            assertThat(
+                            new String(
+                                    payloads.get("fields.json"),
+                                    java.nio.charset.StandardCharsets.UTF_8))
+                    .contains("bundled");
+        }
+
+        @Test
+        @DisplayName("stores the pdf entry but deflates the json")
+        void perEntryMethods() throws Exception {
+            byte[] zip = bundleFor(pdfFile());
+            java.util.Map<String, java.util.zip.ZipEntry> entries = entriesOf(zip);
+
+            assertThat(entries.get("document.pdf").getMethod())
+                    .as("deflating an already-compressed PDF burns CPU for almost nothing")
+                    .isEqualTo(java.util.zip.ZipEntry.STORED);
+            assertThat(entries.get("fields.json").getMethod())
+                    .as("the JSON is text and no longer gets the container's gzip")
+                    .isEqualTo(java.util.zip.ZipEntry.DEFLATED);
+        }
+
+        @Test
+        @DisplayName("bundled fields match what a follow-up fetch would have returned")
+        void matchesTheSecondCallItReplaces() throws Exception {
+            byte[] zip = bundleFor(pdfFile());
+            entriesOf(zip);
+            byte[] bundledPdf = payloads.get("document.pdf");
+
+            // Re-ask the endpoint this feature stops re-calling, using the returned bytes.
+            MockMultipartFile saved =
+                    new MockMultipartFile("file", "test.pdf", "application/pdf", bundledPdf);
+            try (PDDocument reloaded = org.apache.pdfbox.Loader.loadPDF(bundledPdf)) {
+                when(pdfDocumentFactory.load(eq(saved), eq(true))).thenReturn(reloaded);
+                ResponseEntity<
+                                java.util.List<
+                                        stirling.software.common.model.FormFieldWithCoordinates>>
+                        refetched = controller.listFieldsWithCoordinates(saved);
+
+                String viaRefetch = realObjectMapper.writeValueAsString(refetched.getBody());
+                String viaBundle =
+                        new String(
+                                payloads.get("fields.json"),
+                                java.nio.charset.StandardCharsets.UTF_8);
+                assertThat(viaBundle)
+                        .as("the bundle must be interchangeable with the round trip it removes")
+                        .isEqualTo(viaRefetch);
+            }
+        }
+
+        @Test
+        @DisplayName("omitting the flag still returns a bare pdf")
+        void defaultsToPlainPdf() throws Exception {
+            MockMultipartFile file = pdfFile();
+            PDDocument doc = createMinimalPdf();
+            when(pdfDocumentFactory.load(eq(file))).thenReturn(doc);
+
+            byte[] body = drainBody(controller.editFields(file, editsPayload(), false));
+
+            assertThat(new String(body, 0, 5)).isEqualTo("%PDF-");
+        }
+    }
+
+    // -- skipped-edits header budget -----------------------------------
+
+    @Nested
+    @DisplayName("skipped-edits header")
+    class SkipHeaderBudget {
+
+        @Test
+        @DisplayName("stays within budget however long the reported names are")
+        void staysWithinBudget() throws Exception {
+            java.util.List<FormUtils.SkippedFieldEdit> skipped = new java.util.ArrayList<>();
+            String huge = "x".repeat(20000);
+            for (int i = 0; i < 40; i++) {
+                skipped.add(new FormUtils.SkippedFieldEdit("modify", huge, huge));
+            }
+
+            var method =
+                    FormFillController.class.getDeclaredMethod(
+                            "withSkippedEdits", ResponseEntity.class, java.util.List.class);
+            method.setAccessible(true);
+            @SuppressWarnings("unchecked")
+            ResponseEntity<Resource> response =
+                    (ResponseEntity<Resource>)
+                            method.invoke(controller, streamingOk(new byte[] {1}), skipped);
+
+            String header = response.getHeaders().getFirst(FormFillController.SKIPPED_EDITS_HEADER);
+            assertThat(header).isNotNull();
+            // Not merely short: an empty header would pass a length check while telling the
+            // user nothing, because the alert renders only when it has entries.
+            String decoded =
+                    new String(
+                            java.util.Base64.getDecoder().decode(header),
+                            java.nio.charset.StandardCharsets.UTF_8);
+            assertThat(decoded).startsWith("[{");
+            assertThat(decoded).contains("...");
+            // Overflowing the container's header budget turns the reply into an error page,
+            // which loses the edited PDF the user just saved.
+            assertThat(header.length()).isLessThanOrEqualTo(4096);
+            assertThat(
+                            response.getHeaders()
+                                    .getFirst(FormFillController.SKIPPED_EDITS_TOTAL_HEADER))
+                    .isEqualTo("40");
+        }
+    }
 }
@@ -170,6 +170,94 @@ class FormPayloadParserTest {
        }
    }

+    // ── parseNewFieldDefinitions ───────────────────────────────────────
+
+    @Nested
+    @DisplayName("parseNewFieldDefinitions")
+    class ParseNewFieldDefinitions {
+
+        @Test
+        @DisplayName("returns empty list for null input")
+        void nullInput() {
+            List<FormUtils.NewFormFieldDefinition> result =
+                    FormPayloadParser.parseNewFieldDefinitions(objectMapper, null);
+            assertThat(result).isEmpty();
+        }
+
+        @Test
+        @DisplayName("returns empty list for blank input")
+        void blankInput() {
+            List<FormUtils.NewFormFieldDefinition> result =
+                    FormPayloadParser.parseNewFieldDefinitions(objectMapper, "   ");
+            assertThat(result).isEmpty();
+        }
+
+        @Test
+        @DisplayName("parses a valid new-field list including geometry and flags")
+        void validNewFields() {
+            String json =
+                    "[{\"name\":\"NewField\",\"type\":\"text\",\"pageIndex\":0,"
+                            + "\"x\":50,\"y\":700,\"width\":200,\"height\":20,"
+                            + "\"fontSize\":14,\"readOnly\":true,\"multiline\":true}]";
+            List<FormUtils.NewFormFieldDefinition> result =
+                    FormPayloadParser.parseNewFieldDefinitions(objectMapper, json);
+            assertThat(result).hasSize(1);
+            FormUtils.NewFormFieldDefinition def = result.get(0);
+            assertThat(def.name()).isEqualTo("NewField");
+            assertThat(def.type()).isEqualTo("text");
+            assertThat(def.pageIndex()).isEqualTo(0);
+            assertThat(def.x()).isEqualTo(50f);
+            assertThat(def.y()).isEqualTo(700f);
+            assertThat(def.width()).isEqualTo(200f);
+            assertThat(def.height()).isEqualTo(20f);
+            assertThat(def.fontSize()).isEqualTo(14f);
+            assertThat(def.readOnly()).isTrue();
+            assertThat(def.multiline()).isTrue();
+        }
+    }
+
+    // ── parseFieldEdits ────────────────────────────────────────────────
+
+    @Nested
+    @DisplayName("parseFieldEdits")
+    class ParseFieldEdits {
+
+        @Test
+        @DisplayName("returns empty batch for null input")
+        void nullInput() {
+            FormUtils.FieldEditBatch batch = FormPayloadParser.parseFieldEdits(objectMapper, null);
+            assertThat(batch.add()).isEmpty();
+            assertThat(batch.modify()).isEmpty();
+            assertThat(batch.delete()).isEmpty();
+        }
+
+        @Test
+        @DisplayName("parses a combined add/modify/delete batch")
+        void combinedBatch() {
+            String json =
+                    "{\"add\":[{\"name\":\"new1\",\"type\":\"text\",\"pageIndex\":0,\"x\":1,"
+                            + "\"y\":2,\"width\":3,\"height\":4}],"
+                            + "\"modify\":[{\"targetName\":\"old1\",\"label\":\"L\"}],"
+                            + "\"delete\":[\"gone1\",{\"name\":\"gone2\"}]}";
+            FormUtils.FieldEditBatch batch = FormPayloadParser.parseFieldEdits(objectMapper, json);
+            assertThat(batch.add()).hasSize(1);
+            assertThat(batch.add().get(0).name()).isEqualTo("new1");
+            assertThat(batch.modify()).hasSize(1);
+            assertThat(batch.modify().get(0).targetName()).isEqualTo("old1");
+            assertThat(batch.delete()).containsExactly("gone1", "gone2");
+        }
+
+        @Test
+        @DisplayName("tolerates missing sections")
+        void missingSections() {
+            FormUtils.FieldEditBatch batch =
+                    FormPayloadParser.parseFieldEdits(objectMapper, "{\"delete\":[\"x\"]}");
+            assertThat(batch.add()).isEmpty();
+            assertThat(batch.modify()).isEmpty();
+            assertThat(batch.delete()).containsExactly("x");
+        }
+    }
+
    // ── parseNameList ──────────────────────────────────────────────────

    @Nested
@@ -91,24 +91,32 @@ public class ControllerAuditAspect {
        MethodSignature sig = (MethodSignature) joinPoint.getSignature();
        Method method = sig.getMethod();

-        // Fast path: check if auditing is enabled before doing any work
-        // This avoids all data collection if auditing is disabled
-        if (!auditService.shouldAudit(method, auditConfig)) {
+        // Resolve the event type up front so the enterprise gate can be type-aware: document
+        // processing events (the Documents tab's data source) are audited without an Enterprise
+        // license, while the rest of the audit log stays Enterprise-only. resolveEventType is cheap
+        // (annotation / class / path checks), so it's safe on the pre-record fast path.
+        Audited auditedAnnotation = method.getAnnotation(Audited.class);
+        String path = getRequestPath(method, httpMethod);
+        AuditEventType eventType =
+                auditService.resolveEventType(
+                        method,
+                        joinPoint.getTarget().getClass(),
+                        path,
+                        httpMethod,
+                        auditedAnnotation);
+
+        // Fast path: skip all data collection when this event won't be recorded.
+        if (!auditService.shouldAudit(eventType, method, auditConfig)) {
            return joinPoint.proceed();
        }

-        // Check if method is explicitly annotated with @Audited
-        Audited auditedAnnotation = method.getAnnotation(Audited.class);
        AuditLevel level = auditConfig.getAuditLevel();
-
        // If @Audited annotation is present, respect its level setting
        if (auditedAnnotation != null) {
            // Use the level from annotation if it's stricter than global level
            level = auditedAnnotation.level();
        }

-        String path = getRequestPath(method, httpMethod);
-
        // Skip static GET resources
        if ("GET".equals(httpMethod)) {
            HttpServletRequest maybe = auditService.getCurrentRequest();
@@ -209,15 +217,6 @@ public class ControllerAuditAspect {
                // the body ran, so it must happen here rather than with the pre-proceed HTTP data).
                auditService.addAutomationContext(data, req);

-                // Resolve the event type using the unified method
-                AuditEventType eventType =
-                        auditService.resolveEventType(
-                                method,
-                                joinPoint.getTarget().getClass(),
-                                path,
-                                httpMethod,
-                                auditedAnnotation);
-
                // Add result only if operation result capture is explicitly enabled
                // Skip result for UI_DATA events to avoid storing large response bodies
                if (auditService.shouldCaptureOperationResults()
@@ -0,0 +1,13 @@
+package stirling.software.proprietary.audit;
+
+import org.springframework.stereotype.Component;
+
+/** Self-hosted default: any portal user sees the whole-server documents queue. */
+@Component
+public class DefaultPortalDocumentsScopeResolver implements PortalDocumentsScopeResolver {
+
+    @Override
+    public PortalAuditScope resolve() {
+        return PortalAuditScope.server();
+    }
+}
@@ -0,0 +1,7 @@
+package stirling.software.proprietary.audit;
+
+/** Resolves which slice of the documents queue a portal user may see. */
+public interface PortalDocumentsScopeResolver {
+
+    PortalAuditScope resolve();
+}
@@ -9,6 +9,7 @@ import java.util.Map;
 import java.util.Set;

 import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentInformation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.io.Resource;
 import org.springframework.http.MediaType;
@@ -20,12 +21,13 @@ import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;

 import io.github.pixee.security.Filenames;
-import io.swagger.v3.oas.annotations.Hidden;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;

 import lombok.extern.slf4j.Slf4j;

+import stirling.software.common.model.tool.ToolFormat;
+import stirling.software.common.model.tool.ToolIO;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.service.PdfMetadataService;
 import stirling.software.common.service.UserServiceInterface;
@@ -48,11 +50,13 @@ import tools.jackson.databind.node.ObjectNode;
 * <p>Runs as a Classification-policy pipeline step: it reads a bounded page window, asks the AI
 * engine to classify the document against the built-in label set, and stores the engine's JSON
 * answer — minus the transport-only {@code outcome} field — in the custom Info-dictionary key
- * {@link PdfMetadataService#CLASSIFICATION_KEY}. Returns the labelled PDF. Not intended for direct
- * client use.
+ * {@link PdfMetadataService#CLASSIFICATION_KEY}. Returns the labelled PDF.
+ *
+ * <p>Published in the API spec rather than hidden, so the tool-model generator emits it and a
+ * pipeline can name it as a step like any other tool. Classification is a thing a pipeline does,
+ * not a thing only the Classification policy may do.
 */
@Slf4j
-@Hidden
@RestController
@RequestMapping("/api/v1/ai/tools")
@Tag(name = "AI Tools", description = "Dispatchable AI-backed tools.")
@@ -99,19 +103,31 @@ public class ClassifyLabelController {
    }

    @PostMapping(value = "/classify-and-label", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    // PDF in, the same PDF out with a verdict on it, so a chain can be checked across this step.
+    @ToolIO(accepts = ToolFormat.PDF, produces = ToolFormat.PDF)
    @Operation(
            summary = "Classify a PDF and label its metadata",
            description =
                    "Reads the first two and last two pages, classifies the document via the AI"
                            + " engine, and stores the result in the StirlingPDFClassification"
-                            + " metadata field. Dispatched by the Classification policy; not"
-                            + " intended for direct client use.")
+                            + " metadata field. A document that already carries a verdict is"
+                            + " passed through untouched unless reclassify=true.")
    public ResponseEntity<Resource> classifyAndLabel(
-            @RequestParam("fileInput") MultipartFile fileInput) throws IOException {
+            @RequestParam("fileInput") MultipartFile fileInput,
+            @RequestParam(value = "reclassify", defaultValue = "false") boolean reclassify)
+            throws IOException {
        aiFeatureGate.requireClassify();
        try (PDDocument document = pdfDocumentFactory.load(fileInput, true)) {
            String fileName = safeFileName(fileInput.getOriginalFilename());

+            if (!reclassify && isClassified(document)) {
+                // Classifying twice costs a second engine call and charges for it, and a document
+                // that already carries a verdict has nothing new to learn. A pipeline can run this
+                // step over a mixed batch without paying for the ones already done.
+                log.debug("[classify-and-label] {} already classified; passing through", fileName);
+                return WebResponseUtils.pdfDocToWebResponse(document, fileName, tempFileManager);
+            }
+
            List<EngineLabel> allowed = resolveAllowedLabels();
            if (allowed.isEmpty()) {
                // No vocabulary to classify against: pass the file through unlabelled rather than
@@ -135,6 +151,25 @@ public class ClassifyLabelController {
        }
    }

+    /**
+     * Whether a verdict is already on the document.
+     *
+     * <p>This only reads back what a previous run of this step wrote. It is not a statement that
+     * the verdict is trustworthy: the key is ordinary PDF metadata that whoever supplied the file
+     * can set. Skipping the engine on the strength of it is safe because the cost of being wrong is
+     * a missing re-classification, not a wrong decision. Anything that makes a SECURITY decision
+     * from this field - routing a document somewhere on the strength of its label, say - must
+     * classify with {@code reclassify=true} rather than trust what arrived.
+     */
+    private static boolean isClassified(PDDocument document) {
+        PDDocumentInformation info = document.getDocumentInformation();
+        if (info == null) {
+            return false;
+        }
+        String existing = info.getCustomMetadataValue(PdfMetadataService.CLASSIFICATION_KEY);
+        return existing != null && !existing.isBlank();
+    }
+
    private List<AiPageText> extractWindow(PDDocument document) throws IOException {
        List<AiPageText> pages = new ArrayList<>();
        for (int pageNumber : windowPageNumbers(document.getNumberOfPages(), WINDOW_PAGES)) {
@@ -2,6 +2,7 @@ package stirling.software.proprietary.controller.api;

 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestParam;

@@ -11,19 +12,25 @@ import lombok.RequiredArgsConstructor;

 import stirling.software.common.annotations.api.ProprietaryUiDataApi;
 import stirling.software.proprietary.audit.PortalAuditScope;
-import stirling.software.proprietary.audit.PortalAuditScopeResolver;
+import stirling.software.proprietary.audit.PortalDocumentsScopeResolver;
 import stirling.software.proprietary.model.api.documents.PortalDocumentsResponseDto;
-import stirling.software.proprietary.security.config.EnterpriseEndpoint;
 import stirling.software.proprietary.service.PortalDocumentsService;

-/** Serves the portal Documents review queue, derived from real audit data and scoped per caller. */
+/**
+ * Serves the portal Documents review queue, derived from real audit data and scoped per caller.
+ *
+ * <p>Open to every portal user (not Enterprise-gated): the Documents tab is a core Processor
+ * feature. Access is enforced by {@code @resourceAccess.canUsePortal()}; visibility is then
+ * resolved per deployment - self-hosted portal users see the whole server, SaaS users see their
+ * team (see {@link PortalDocumentsScopeResolver}).
+ */
@ProprietaryUiDataApi
@RequiredArgsConstructor
-@EnterpriseEndpoint
+@PreAuthorize("@resourceAccess.canUsePortal()")
 public class PortalDocumentsController {

    private final PortalDocumentsService portalDocumentsService;
-    private final PortalAuditScopeResolver auditScopeResolver;
+    private final PortalDocumentsScopeResolver documentsScopeResolver;

    // tier accepted for mock-seam symmetry; ignored (queue isn't tier-scoped).
    @GetMapping("/documents")
@@ -32,8 +39,9 @@ public class PortalDocumentsController {
            description = "Files processed through the org, derived from the audit trail.")
    public ResponseEntity<PortalDocumentsResponseDto> getDocuments(
            @RequestParam(value = "tier", required = false) String tier) {
-        PortalAuditScope scope = auditScopeResolver.resolve();
+        PortalAuditScope scope = documentsScopeResolver.resolve();
        if (!scope.allowed()) {
+            // SaaS caller with no team has nothing to show; surface an empty tab, not a 500.
            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
        }
        PortalDocumentsResponseDto body =
@@ -1,20 +1,17 @@
 package stirling.software.proprietary.failure;

+import org.springframework.http.HttpStatus;
+
 import lombok.Getter;

-/**
- * Why an action could not be dispatched. Carries a {@link Reason} rather than an HTTP status, so
- * the service stays web-agnostic and the controller owns the mapping.
- */
+/** Carries a {@link Reason} rather than an HTTP status, so the service stays web-agnostic. */
@Getter
 public class FailureActionException extends RuntimeException {

    public enum Reason {
        /**
-         * No such event, it belongs to another team, or the caller's team did not resolve. One
-         * reason for all three, so the response does not vary with which it was. Unrelated to
-         * {@link FailureKind#UNKNOWN}, which is an unclassified failure rather than a refused
-         * action.
+         * No such event, another team's, or an unresolved team: one reason, so the answer cannot
+         * vary.
         */
        EVENT_NOT_FOUND,

@@ -22,15 +19,13 @@ public class FailureActionException extends RuntimeException {
        ACTION_NOT_RECOGNISED,

        /**
-         * The action exists but this kind does not declare it, so an incoherent pairing (releasing
-         * a document whose destination is what failed) cannot be dispatched even by hand.
-         *
-         * <p>Unreachable today: both kinds declare both actions, so no request can trip this guard
-         * until a kind ships with a restricted action set. Declared now because the guard must
-         * exist before that kind does, not after.
+         * The action exists but this kind does not offer it, so it cannot be dispatched by hand.
         */
        ACTION_NOT_DECLARED,

+        /** Offered, but the client is what runs it, so refused rather than half-performed. */
+        ACTION_NOT_DISPATCHABLE,
+
        /** The event is already closed, so no further transition is possible. */
        ALREADY_CLOSED
    }
@@ -41,9 +36,21 @@ public class FailureActionException extends RuntimeException {
        this(reason, message, null);
    }

-    /** For a refusal that follows from a lower-level failure, so its stack is not dropped. */
    public FailureActionException(Reason reason, String message, Throwable cause) {
        super(message, cause);
        this.reason = reason;
    }
+
+    /**
+     * Lives with the reasons it maps, so every surface that dispatches an action answers alike. A
+     * closed row is a conflict, not a bad request: it was well-formed and valid a moment earlier.
+     */
+    public static HttpStatus statusOf(Reason reason) {
+        return switch (reason) {
+            case EVENT_NOT_FOUND -> HttpStatus.NOT_FOUND;
+            case ACTION_NOT_RECOGNISED, ACTION_NOT_DECLARED, ACTION_NOT_DISPATCHABLE ->
+                    HttpStatus.BAD_REQUEST;
+            case ALREADY_CLOSED -> HttpStatus.CONFLICT;
+        };
+    }
 }
@@ -1,11 +1,52 @@
 package stirling.software.proprietary.failure;

+import lombok.Getter;
+
 /**
- * The actions a {@link FailureKind} may declare. Both are incident dispositions: they change how
- * the event is shown and touch nothing else, which is what makes them valid for every kind
- * including {@link FailureKind#UNKNOWN}, and why there is no {@code APPROVE} yet.
+ * The actions a {@link FailureKind} may declare. Client actions are declared here rather than
+ * invented per client, so the server keeps deciding what a kind offers, in what order and labelled
+ * how.
 */
+@Getter
 public enum FailureActionId {
-    ACKNOWLEDGE,
-    DISMISS
+
+    /**
+     * Kept in the vocabulary for as long as any persisted row is {@code ACKNOWLEDGED}: such rows
+     * must stay readable and closable whether or not any kind currently offers this.
+     */
+    ACKNOWLEDGE(Execution.SERVER, "Acknowledge"),
+
+    DISMISS(Execution.SERVER, "Dismiss"),
+
+    /** Open the document behind the incident, in whichever client can resolve its id. */
+    VIEW_FILE(Execution.CLIENT, "View file"),
+
+    VIEW_IN_PROCESSOR(Execution.CLIENT, "View in processor");
+
+    /** Dispatch refuses a {@code CLIENT} id, so this is enforced rather than merely documented. */
+    public enum Execution {
+
+        /** {@link FailureActionRegistry} requires a {@link FailureAction} bean for these. */
+        SERVER,
+
+        /**
+         * Declared and rendered, never dispatched: the server has neither the file nor the tool.
+         */
+        CLIENT
+    }
+
+    private final Execution execution;
+
+    /** English fallback, for a client with no translation for the label key. */
+    private final String defaultLabel;
+
+    FailureActionId(Execution execution, String defaultLabel) {
+        this.execution = execution;
+        this.defaultLabel = defaultLabel;
+    }
+
+    /** Also whether it can be dispatched. */
+    public boolean runsOnServer() {
+        return execution == Execution.SERVER;
+    }
 }
@@ -16,6 +16,9 @@ import lombok.extern.slf4j.Slf4j;
 * Resolves a {@link FailureActionId} to the bean that implements it. The startup check is the
 * point: because kinds declare action ids as data, one could name an action nobody implements,
 * which would otherwise show up as a button that 400s rather than as a failed boot.
+ *
+ * <p>Only {@link FailureActionId.Execution#SERVER} ids belong here: a bean for a client action is
+ * refused, because dispatch could never reach it.
 */
@Slf4j
@Service
@@ -25,6 +28,14 @@ public class FailureActionRegistry {

    public FailureActionRegistry(List<FailureAction> actions) {
        for (FailureAction action : actions) {
+            if (!action.id().runsOnServer()) {
+                throw new IllegalStateException(
+                        "Action "
+                                + action.id()
+                                + " is run by the client, so "
+                                + action.getClass().getName()
+                                + " could never be dispatched");
+            }
            FailureAction clash = byId.put(action.id(), action);
            if (clash != null) {
                throw new IllegalStateException(
@@ -38,10 +49,7 @@ public class FailureActionRegistry {
        }
    }

-    /**
-     * Fail fast if any kind declares an action with no handler, naming every gap rather than the
-     * first, so one boot tells you everything that is missing.
-     */
+    /** Names every gap rather than the first, so one boot tells you everything that is missing. */
    @PostConstruct
    void verifyEveryDeclaredActionHasAHandler() {
        List<String> gaps =
@@ -49,6 +57,7 @@ public class FailureActionRegistry {
                        .flatMap(
                                kind ->
                                        kind.getActions().stream()
+                                                .filter(FailureActionId::runsOnServer)
                                                .filter(action -> !byId.containsKey(action))
                                                .map(action -> kind.getId() + " -> " + action))
                        .toList();
@@ -0,0 +1,15 @@
+package stirling.software.proprietary.failure;
+
+/**
+ * Who an offered action is for, the read scope having already decided they may see the incident.
+ * The distinction is possession, not seniority: a reviewer cannot reach a document only its owner
+ * holds.
+ */
+public enum FailureAudience {
+    OWNER,
+
+    /** Anyone who triages the team's incidents, whoever hit them. */
+    TEAM_REVIEWER,
+
+    ANYONE_WHO_SEES
+}
@@ -1,7 +1,11 @@
 package stirling.software.proprietary.failure;

-import static stirling.software.proprietary.failure.FailureActionId.ACKNOWLEDGE;
 import static stirling.software.proprietary.failure.FailureActionId.DISMISS;
+import static stirling.software.proprietary.failure.FailureActionId.VIEW_FILE;
+import static stirling.software.proprietary.failure.FailureActionId.VIEW_IN_PROCESSOR;
+import static stirling.software.proprietary.failure.FailureAudience.ANYONE_WHO_SEES;
+import static stirling.software.proprietary.failure.FailureAudience.OWNER;
+import static stirling.software.proprietary.failure.FailureAudience.TEAM_REVIEWER;

 import java.util.Arrays;
 import java.util.HashMap;
@@ -20,13 +24,8 @@ import lombok.Getter;
 * The registry of failure kinds, described as data: a stable id, i18n keys and an English fallback
 * like {@code ExceptionUtils.ErrorCode}, plus the facets a review surface needs.
 *
- * <p>Actions are declared here but implemented in {@link FailureAction} beans resolved by id, so a
- * new kind ships as a registry entry plus copy. Two members today: {@link #UNKNOWN} gives every
- * failed run a record, and kinds get promoted out of it as production shows what occurs.
- *
- * <p>A kind offers an acknowledgement only where there is something to acknowledge <em>doing</em>.
- * With nothing to fix, "seen it" and "clear it" are the same decision, so the row offers only the
- * one that clears it.
+ * <p>A new kind ships as a registry entry plus copy. Each offer also says who it is for, since one
+ * incident is read both by whoever hit it and by whoever reviews after them.
 */
@Getter
 public enum FailureKind {
@@ -37,8 +36,9 @@ public enum FailureKind {
            FailureScope.FILE,
            errorCodes("E004"),
            fallback("This document is password-protected, so the pipeline could not read it."),
-            offer(ACKNOWLEDGE),
-            offer(DISMISS, "dismissSkipFile")),
+            offer(VIEW_FILE, OWNER),
+            offer(VIEW_IN_PROCESSOR, TEAM_REVIEWER),
+            offer(DISMISS, ANYONE_WHO_SEES)),

    UNKNOWN(
            FailureStage.INTERNAL,
@@ -47,7 +47,11 @@ public enum FailureKind {
            FailureScope.RUN,
            noErrorCodes(),
            fallback("This run failed for a reason Stirling does not yet recognise."),
-            offer(DISMISS));
+            // Same order as every other kind: declaration order is display order, so the document
+            // leads wherever it is offered rather than moving between failures.
+            offer(VIEW_FILE, OWNER),
+            offer(VIEW_IN_PROCESSOR, TEAM_REVIEWER),
+            offer(DISMISS, ANYONE_WHO_SEES));

    private static final String KEY_PREFIX = "portal.failures.kind.";
    private static final String ACTION_KEY_PREFIX = "portal.failures.action.";
@@ -95,22 +99,26 @@ public enum FailureKind {
    }

    /**
-     * One action this kind offers, with the key to label it by. One ordered list rather than ids
-     * plus a parallel map of overrides, which could disagree with each other.
+     * One ordered list rather than ids plus parallel maps of audiences and labels, which could
+     * disagree with each other.
     *
     * @param labelKeySuffix key under {@code portal.failures.action.}, or null for the generic
     *     label
     */
-    private record Offer(FailureActionId id, String labelKeySuffix) {}
+    private record Offer(FailureActionId id, FailureAudience audience, String labelKeySuffix) {}

-    /** An action labelled by this kind's own wording, where the generic label reads badly. */
-    private static Offer offer(FailureActionId id, String labelKeySuffix) {
-        return new Offer(id, labelKeySuffix);
+    /** Declaration order is display order. */
+    private static Offer offer(FailureActionId id, FailureAudience audience) {
+        return new Offer(id, audience, null);
    }

-    /** An action labelled by the shared wording for that action. */
-    private static Offer offer(FailureActionId id) {
-        return new Offer(id, null);
+    /**
+     * As {@link #offer(FailureActionId, FailureAudience)}, but labelled by this kind's own wording
+     * where the shared one reads badly.
+     */
+    private static Offer offer(
+            FailureActionId id, FailureAudience audience, String labelKeySuffix) {
+        return new Offer(id, audience, labelKeySuffix);
    }

    /**
@@ -149,6 +157,22 @@ public enum FailureKind {
        return offers.stream().map(Offer::id).toList();
    }

+    /**
+     * What this kind offers, in declaration order, each with its label resolved. What a review
+     * surface reads, so it never has to ask two separate questions about one offer.
+     */
+    public List<OfferedAction> getOfferedActions() {
+        return offers.stream()
+                .map(
+                        offer ->
+                                new OfferedAction(
+                                        offer.id(), labelKeyFor(offer.id()), offer.audience()))
+                .toList();
+    }
+
+    /** One action as a kind declares it: what to call it and who it is for. */
+    public record OfferedAction(FailureActionId id, String labelKey, FailureAudience audience) {}
+
    /** Whether this kind offers {@code action}. The dispatch guard: see {@code FailureActionId}. */
    public boolean declares(FailureActionId action) {
        return offers.stream().anyMatch(offer -> offer.id() == action);
@@ -74,8 +74,10 @@ public class FileRunEventController {
    @Operation(
            summary = "Apply an action to a recorded failure",
            description =
-                    "Rejected with 400 if the failure's kind does not declare the action, so an"
-                            + " action that makes no sense for a given failure cannot be applied.")
+                    "Rejected with 400 if the failure's kind does not declare the action, or if the"
+                            + " action is one the client runs rather than the server, so neither an"
+                            + " action that makes no sense for a given failure nor one the server"
+                            + " cannot perform can be applied.")
    public FileRunEventView act(
            @PathVariable String eventId,
            @PathVariable String actionId,
@@ -87,7 +89,8 @@ public class FileRunEventController {
            FileRunEvent updated = service.dispatch(eventId, actionId, inputs);
            return FileRunEventView.of(updated, service.availableActions(updated));
        } catch (FailureActionException e) {
-            throw new ResponseStatusException(statusFor(e.getReason()), e.getMessage(), e);
+            throw new ResponseStatusException(
+                    FailureActionException.statusOf(e.getReason()), e.getMessage(), e);
        }
    }

@@ -147,18 +150,6 @@ public class FileRunEventController {
        return Arrays.stream(FailureKind.values()).map(FailureKindView::of).toList();
    }

-    /**
-     * A closed row is a conflict rather than a bad request: the request was well-formed and would
-     * have been valid a moment earlier.
-     */
-    private static HttpStatus statusFor(FailureActionException.Reason reason) {
-        return switch (reason) {
-            case EVENT_NOT_FOUND -> HttpStatus.NOT_FOUND;
-            case ACTION_NOT_RECOGNISED, ACTION_NOT_DECLARED -> HttpStatus.BAD_REQUEST;
-            case ALREADY_CLOSED -> HttpStatus.CONFLICT;
-        };
-    }
-
    /** Wrapped rather than a bare array so pagination can be added without breaking clients. */
    public record FileRunEventsResponse(List<FileRunEventView> events) {}

@@ -178,10 +169,13 @@ public class FileRunEventController {
        }
    }

-    /** Inputs an action declared it needs. Empty for both actions that exist today. */
+    /**
+     * Inputs an action declared it needs. Empty for every action the server runs today: the one
+     * that needs a password is run by the client, which never sends it here.
+     */
    public record ActionRequest(Map<String, String> inputs) {

-        Map<String, String> safeInputs() {
+        public Map<String, String> safeInputs() {
            return inputs == null ? Map.of() : inputs;
        }
    }
@@ -98,20 +98,18 @@ public interface FileRunEventRepository extends JpaRepository<FileRunEventEntity
     * Close the incidents about documents their owner deleted from the editor: the queue is what
     * needs attention, and a document that no longer exists needs none.
     *
-     * <p>Restricted to that owner's own editor rows. File ids are minted by the client, so scoping
-     * on team alone would let one caller close a colleague's incidents by naming ids. Processor
-     * rows are excluded outright: nothing was deleted from an editor there.
+     * <p>Scoped by the absence of a source rather than by origin: a source-fed run's {@code fileId}
+     * is a hash no client can name. Narrowed to the owner's own rows, since clients mint the ids.
     */
    @Modifying(clearAutomatically = true)
    @Transactional
    @Query(
            "update FileRunEventEntity e set e.status ="
                    + " stirling.software.proprietary.failure.FileRunEventStatus.FILE_REMOVED,"
-                    + " e.statusActor = :actor, e.statusAt = :now where e.origin ="
-                    + " stirling.software.proprietary.failure.FailureOrigin.TOOL and ((:teamId is"
-                    + " null and e.teamId is null) or e.teamId = :teamId) and ((:actor is null and"
-                    + " e.actor is null) or e.actor = :actor) and e.fileId in :fileIds and e.status in"
-                    + " :allowedFrom")
+                    + " e.statusActor = :actor, e.statusAt = :now where e.sourceId is null and"
+                    + " ((:teamId is null and e.teamId is null) or e.teamId = :teamId) and"
+                    + " ((:actor is null and e.actor is null) or e.actor = :actor) and e.fileId in"
+                    + " :fileIds and e.status in :allowedFrom")
    int markFilesRemoved(
            @Param("teamId") Long teamId,
            @Param("actor") String actor,
@@ -21,12 +21,22 @@ import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
 * team always comes from the authenticated principal, and scoping applies only when login is
 * enabled so single-user deployments keep working. When the team cannot be resolved the caller
 * reads nothing; see {@link #readScope()}.
+ *
+ * <p>The read scope decides who sees an incident; {@link #availableActions} decides who may act.
 */
@Slf4j
@Service
@RequiredArgsConstructor
 public class FileRunEventService {

+    /** Why an offered action came back disabled. Copy lives under {@code portal.failures}. */
+    private static final String CLOSED_REASON_KEY = "portal.failures.disabled.closed";
+
+    private static final String UNATTENDED_REASON_KEY = "portal.failures.disabled.unattended";
+
+    /** The row never named a document, so unlike the unattended case no client can find one. */
+    private static final String DOCUMENTLESS_REASON_KEY = "portal.failures.disabled.noDocument";
+
    private final FileRunEventStore store;
    private final FailureActionRegistry actionRegistry;
    private final PolicyManagementAuthority policyManagementAuthority;
@@ -116,36 +126,17 @@ public class FileRunEventService {
     * Dispatch an action against one event.
     *
     * @throws FailureActionException if the event is not the caller's, the action is unknown, the
-     *     event's kind does not declare the action, or the event is already closed
+     *     event's kind does not declare the action, the client is what runs the action, or the
+     *     event is already closed
     */
    public FileRunEvent dispatch(String eventId, String actionId, Map<String, String> inputs) {
        // Whoever can see it can close it: a leader for the whole team, everyone else for the
        // failures they caused. Someone who fixes their own problem should not have to ask a leader
        // to clear the row.
        //
-        // Closing the row is all this covers. Acting on the document behind it, such as supplying a
-        // password for a retry, would need its own permission, and no such action exists yet.
-        ReadScope scope = readScope();
-        if (!scope.permitted()) {
-            // Reported as "no such event", the same as an id from another team, so the response
-            // does
-            // not depend on whether the id happens to exist.
-            throw new FailureActionException(
-                    FailureActionException.Reason.EVENT_NOT_FOUND, "No such event: " + eventId);
-        }
-        FileRunEvent event =
-                store.find(eventId, scope.teamId())
-                        // Reported as "no such event" rather than a refusal, so a member cannot
-                        // learn that a colleague's incident exists by trying to close it.
-                        .filter(
-                                found ->
-                                        scope.actor() == null
-                                                || scope.actor().equals(found.actor()))
-                        .orElseThrow(
-                                () ->
-                                        new FailureActionException(
-                                                FailureActionException.Reason.EVENT_NOT_FOUND,
-                                                "No such event: " + eventId));
+        // Audience decides what is offered, not what may be dispatched, so this scope is the whole
+        // gate. A server action aimed at OWNER alone would need its own guard here.
+        FileRunEvent event = requireVisible(eventId);

        FailureActionId resolvedId = parseActionId(actionId);

@@ -156,6 +147,12 @@ public class FileRunEventService {
                    FailureActionException.Reason.ACTION_NOT_DECLARED,
                    "Kind " + event.kind().getId() + " does not offer action " + resolvedId);
        }
+        // Without this a client could post VIEW_FILE and be answered as though something happened.
+        if (!resolvedId.runsOnServer()) {
+            throw new FailureActionException(
+                    FailureActionException.Reason.ACTION_NOT_DISPATCHABLE,
+                    "Action " + resolvedId + " is run by the client, not the server");
+        }
        if (event.status().terminal()) {
            throw new FailureActionException(
                    FailureActionException.Reason.ALREADY_CLOSED,
@@ -174,23 +171,91 @@ public class FileRunEventService {
        return action.execute(event, inputs == null ? Map.of() : inputs, currentActor());
    }

+    /** "No such event" rather than a refusal, so trying does not confirm a colleague's exists. */
+    private FileRunEvent requireVisible(String eventId) {
+        ReadScope scope = readScope();
+        if (!scope.permitted()) {
+            return notFound(eventId);
+        }
+        return store.find(eventId, scope.teamId())
+                .filter(found -> scope.actor() == null || scope.actor().equals(found.actor()))
+                .orElseGet(() -> notFound(eventId));
+    }
+
+    private FileRunEvent notFound(String eventId) {
+        throw new FailureActionException(
+                FailureActionException.Reason.EVENT_NOT_FOUND, "No such event: " + eventId);
+    }
+
+    public Ownership ownershipOf(FileRunEvent event) {
+        if (event.actor() == null) {
+            return Ownership.UNOWNED;
+        }
+        String caller = currentActor();
+        return event.actor().equals(caller) ? Ownership.MINE : Ownership.THEIRS;
+    }
+
    /**
-     * Which of an event's declared actions are usable right now. Decided per row, so the client
-     * never renders a button that would be refused.
+     * Offers resolved for one caller, so no client renders a button that would be refused. Outside
+     * their audience is dropped, not disabled: greyed out would read as a permission problem.
     */
    public List<AvailableAction> availableActions(FileRunEvent event) {
+        Ownership ownership = ownershipOf(event);
+        boolean reviewsTeam = reviewsTeam();
        boolean closed = event.status().terminal();
-        return event.kind().getActions().stream()
-                .map(
-                        action ->
-                                new AvailableAction(
-                                        action,
-                                        event.kind().labelKeyFor(action),
-                                        !closed,
-                                        closed ? "portal.failures.disabled.closed" : null))
+        // Login disabled is excluded: its rows are unowned only for want of users, and its one
+        // operator owns everything they can see.
+        boolean unattended = enforced() && ownership == Ownership.UNOWNED;
+        // Answered here, or the client reports "not on this device" about a document the row never
+        // identified in the first place.
+        boolean documentless = event.fileId() == null || event.fileId().isBlank();
+        return event.kind().getOfferedActions().stream()
+                .filter(offer -> offeredTo(offer.audience(), ownership, reviewsTeam))
+                .map(offer -> availability(offer, closed, unattended, documentless))
                .toList();
    }

+    /** Enabled is derived from the reason, so a disabled button always has one to show. */
+    private static AvailableAction availability(
+            FailureKind.OfferedAction offer,
+            boolean closed,
+            boolean unattended,
+            boolean documentless) {
+        String reason = disabledReasonFor(offer.audience(), closed, unattended, documentless);
+        return new AvailableAction(offer.id(), offer.labelKey(), reason == null, reason);
+    }
+
+    /** Closed wins over everything, then the owner-only reasons, most specific first. */
+    private static String disabledReasonFor(
+            FailureAudience audience, boolean closed, boolean unattended, boolean documentless) {
+        if (closed) {
+            return CLOSED_REASON_KEY;
+        }
+        if (audience != FailureAudience.OWNER) {
+            return null;
+        }
+        if (unattended) {
+            return UNATTENDED_REASON_KEY;
+        }
+        return documentless ? DOCUMENTLESS_REASON_KEY : null;
+    }
+
+    /** An unattended incident has no owner, so its reviewer inherits the owner's actions. */
+    private static boolean offeredTo(
+            FailureAudience audience, Ownership ownership, boolean reviewsTeam) {
+        return switch (audience) {
+            case OWNER ->
+                    ownership == Ownership.MINE || (ownership == Ownership.UNOWNED && reviewsTeam);
+            case TEAM_REVIEWER -> reviewsTeam;
+            case ANYONE_WHO_SEES -> true;
+        };
+    }
+
+    /** Login disabled has no roles, so its one operator triages everything. */
+    private boolean reviewsTeam() {
+        return !enforced() || policyManagementAuthority.canEditPolicies();
+    }
+
    private FailureActionId parseActionId(String actionId) {
        for (FailureActionId candidate : FailureActionId.values()) {
            if (candidate.name().equals(actionId)) {
@@ -261,7 +326,6 @@ public class FileRunEventService {
        return applicationProperties.getSecurity().isEnableLogin();
    }

-    /** One action as offered for a specific event, with its resolved availability. */
    public record AvailableAction(
            FailureActionId id, String labelKey, boolean enabled, String disabledReasonKey) {}
 }
@@ -60,14 +60,24 @@ public record FileRunEventView(
                event.lastSeenAt() == null ? 0L : event.lastSeenAt().toEpochMilli());
    }

-    /** One button, as offered for this specific row. */
+    /**
+     * {@code defaultLabel} and {@code execution} let a client render and route an action it was
+     * never built with. Declaration order is display order.
+     */
    public record ActionView(
-            String id, String labelKey, boolean enabled, String disabledReasonKey) {
+            String id,
+            String labelKey,
+            String defaultLabel,
+            FailureActionId.Execution execution,
+            boolean enabled,
+            String disabledReasonKey) {

-        static ActionView of(FileRunEventService.AvailableAction action) {
+        public static ActionView of(FileRunEventService.AvailableAction action) {
            return new ActionView(
                    action.id().name(),
                    action.labelKey(),
+                    action.id().getDefaultLabel(),
+                    action.id().getExecution(),
                    action.enabled(),
                    action.disabledReasonKey());
        }
@@ -0,0 +1,17 @@
+package stirling.software.proprietary.failure;
+
+/**
+ * Whose incident this is, from the reader's point of view. Derived on read, never persisted: one
+ * row is {@code MINE} to whoever hit it and {@code THEIRS} to the leader reviewing after them.
+ */
+public enum Ownership {
+    MINE,
+
+    /** A colleague's, visible because the caller reviews the team. */
+    THEIRS,
+
+    /**
+     * An unattended run: a folder, bucket or webhook is its only attribution, so there is no owner.
+     */
+    UNOWNED
+}
@@ -0,0 +1,48 @@
+package stirling.software.proprietary.mail;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Convert;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import stirling.software.proprietary.integration.crypto.EncryptedStringConverter;
+
+/** Durable, user-owned Gmail OAuth connection. OAuth secrets are encrypted at rest. */
+@Entity
+@Table(name = "gmail_oauth_connections")
+@NoArgsConstructor
+@Getter
+@Setter
+public class GmailConnectionEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "username", nullable = false, unique = true, length = 255)
+    private String username;
+
+    @Convert(converter = EncryptedStringConverter.class)
+    @Column(name = "access_token", nullable = false, length = 4096)
+    private String accessToken;
+
+    @Convert(converter = EncryptedStringConverter.class)
+    @Column(name = "refresh_token", nullable = false, length = 4096)
+    private String refreshToken;
+
+    @Column(name = "expires_at", nullable = false)
+    private long expiresAt;
+
+    @Column(name = "email", nullable = false, length = 320)
+    private String email;
+
+    @Column(name = "display_name", length = 255)
+    private String displayName;
+}
@@ -0,0 +1,10 @@
+package stirling.software.proprietary.mail;
+
+import java.util.Optional;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface GmailConnectionRepository extends JpaRepository<GmailConnectionEntity, Long> {
+
+    Optional<GmailConnectionEntity> findByUsername(String username);
+}
@@ -0,0 +1,234 @@
+package stirling.software.proprietary.mail;
+
+import java.io.IOException;
+import java.security.SecureRandom;
+import java.util.Base64;
+import java.util.Map;
+
+import org.springframework.http.ContentDisposition;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.servlet.http.HttpSession;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.UserServiceInterface;
+
+@RestController
+@RequiredArgsConstructor
+@Slf4j
+public class GmailOAuthController {
+
+    static final String STATE_SESSION_KEY = "stirling.gmail.oauth.state";
+    static final String REDIRECT_URI_SESSION_KEY = "stirling.gmail.oauth.redirect-uri";
+    static final String PROFILE_SESSION_KEY = "stirling.gmail.oauth.profile";
+    static final String USER_SESSION_KEY = "stirling.gmail.oauth.username";
+
+    private final GmailOAuthService gmailOAuthService;
+    private final ApplicationProperties applicationProperties;
+    private final UserServiceInterface userService;
+    private final SecureRandom secureRandom = new SecureRandom();
+
+    @GetMapping("/api/v1/email/gmail/connect")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<Map<String, String>> connect(HttpServletRequest request) {
+        String state = randomState();
+        HttpSession session = request.getSession(true);
+        session.setAttribute(STATE_SESSION_KEY, state);
+        session.setAttribute(USER_SESSION_KEY, userService.getCurrentUsername());
+        String redirectUri = gmailOAuthService.resolveRedirectUri(request);
+        session.setAttribute(REDIRECT_URI_SESSION_KEY, redirectUri);
+        log.info(
+                "Starting Gmail OAuth: requestUri={}, redirectUri={}, sessionPresent={}, forwardedHost={}, forwardedProto={}, forwardedPort={}",
+                request.getRequestURI(),
+                redirectUri,
+                session != null,
+                request.getHeader("X-Forwarded-Host"),
+                request.getHeader("X-Forwarded-Proto"),
+                request.getHeader("X-Forwarded-Port"));
+        return ResponseEntity.ok(
+                Map.of("authorizationUrl", gmailOAuthService.authorizationUrl(state, request)));
+    }
+
+    @GetMapping("/api/v1/email/gmail/status")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<?> status(HttpServletRequest request) {
+        HttpSession session = request.getSession(false);
+        GmailOAuthService.GmailProfile profile =
+                session == null
+                        ? null
+                        : (GmailOAuthService.GmailProfile)
+                                session.getAttribute(PROFILE_SESSION_KEY);
+        GmailOAuthService.GmailConnection connection =
+                gmailOAuthService.getConnection(userService.getCurrentUsername());
+        if (profile == null && connection != null) profile = connection.profile();
+        boolean tokenPresent = connection != null;
+        ResponseEntity<?> response =
+                ResponseEntity.ok(
+                        profile == null
+                                ? Map.of("connected", false)
+                                : Map.of(
+                                        "connected",
+                                        true,
+                                        "email",
+                                        profile.email(),
+                                        "provider",
+                                        "Gmail"));
+        log.info(
+                "Gmail status: requestUri={}, sessionPresent={}, profilePresent={}, tokenPresent={}, forwardedHost={}, forwardedProto={}, forwardedPort={}",
+                request.getRequestURI(),
+                session != null,
+                profile != null,
+                tokenPresent,
+                request.getHeader("X-Forwarded-Host"),
+                request.getHeader("X-Forwarded-Proto"),
+                request.getHeader("X-Forwarded-Port"));
+        return response;
+    }
+
+    @DeleteMapping("/api/v1/email/gmail/connection")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<Map<String, Object>> disconnect(HttpServletRequest request) {
+        String username = userService.getCurrentUsername();
+        HttpSession session = request.getSession(false);
+        if (session != null) {
+            session.removeAttribute(PROFILE_SESSION_KEY);
+            session.removeAttribute(USER_SESSION_KEY);
+        }
+        boolean revoked = gmailOAuthService.disconnect(username);
+        return ResponseEntity.ok(Map.of("disconnected", true, "googleRevoked", revoked));
+    }
+
+    @GetMapping("/api/v1/email/gmail/messages")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<GmailOAuthService.GmailMessagePage> messages(
+            @RequestParam(defaultValue = "inbox") String folder,
+            @RequestParam(required = false) String types,
+            @RequestParam(required = false) String query,
+            @RequestParam(required = false) String pageToken,
+            HttpServletRequest request)
+            throws IOException, InterruptedException {
+        GmailOAuthService.GmailToken token = currentToken();
+        return ResponseEntity.ok(
+                gmailOAuthService.listMessages(token, folder, types, query, pageToken));
+    }
+
+    @GetMapping("/api/v1/email/gmail/messages/{messageId}/attachments/{attachmentId}")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<byte[]> attachment(
+            @org.springframework.web.bind.annotation.PathVariable String messageId,
+            @org.springframework.web.bind.annotation.PathVariable String attachmentId,
+            HttpServletRequest request)
+            throws IOException, InterruptedException {
+        GmailOAuthService.GmailAttachmentData attachment =
+                gmailOAuthService.downloadAttachment(currentToken(), messageId, attachmentId);
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
+        headers.setContentDisposition(
+                ContentDisposition.attachment().filename(attachmentId).build());
+        return new ResponseEntity<>(
+                attachment.data(), headers, org.springframework.http.HttpStatus.OK);
+    }
+
+    private GmailOAuthService.GmailToken currentToken() throws IOException, InterruptedException {
+        return gmailOAuthService.getValidToken(userService.getCurrentUsername());
+    }
+
+    @GetMapping("/api/v1/email/gmail/callback")
+    public void callback(
+            String code,
+            String state,
+            String error,
+            @RequestParam(name = "error_description", required = false) String errorDescription,
+            HttpServletRequest request,
+            HttpServletResponse response)
+            throws IOException, InterruptedException {
+        log.info(
+                "Received Gmail OAuth callback: requestUri={}, queryParameterNames={}, codePresent={}, statePresent={}, error={}, sessionPresent={}, forwardedHost={}, forwardedProto={}, forwardedPort={}",
+                request.getRequestURI(),
+                request.getParameterMap().keySet(),
+                code != null && !code.isBlank(),
+                state != null && !state.isBlank(),
+                error,
+                request.getSession(false) != null,
+                request.getHeader("X-Forwarded-Host"),
+                request.getHeader("X-Forwarded-Proto"),
+                request.getHeader("X-Forwarded-Port"));
+        if (error != null && !error.isBlank()) {
+            String detail =
+                    errorDescription == null || errorDescription.isBlank()
+                            ? error
+                            : error + ": " + errorDescription;
+            response.sendError(
+                    HttpServletResponse.SC_BAD_REQUEST, "Gmail OAuth was not completed: " + detail);
+            return;
+        }
+        HttpSession session = request.getSession(false);
+        String expectedState =
+                session == null ? null : (String) session.getAttribute(STATE_SESSION_KEY);
+        String redirectUri =
+                session == null ? null : (String) session.getAttribute(REDIRECT_URI_SESSION_KEY);
+        log.info(
+                "Validating Gmail OAuth callback: expectedStatePresent={}, receivedStatePresent={}, stateMatches={}, redirectUriPresent={}, codePresent={}",
+                expectedState != null,
+                state != null && !state.isBlank(),
+                expectedState != null && expectedState.equals(state),
+                redirectUri != null && !redirectUri.isBlank(),
+                code != null && !code.isBlank());
+        if (expectedState == null
+                || !expectedState.equals(state)
+                || redirectUri == null
+                || code == null
+                || code.isBlank()) {
+            response.sendError(
+                    HttpServletResponse.SC_BAD_REQUEST,
+                    "Invalid Gmail OAuth callback: missing or expired code/state");
+            return;
+        }
+        try {
+            GmailOAuthService.GmailToken token = gmailOAuthService.exchangeCode(code, redirectUri);
+            GmailOAuthService.GmailProfile profile = gmailOAuthService.getProfile(token);
+            gmailOAuthService.ensureEmailAllowed(profile.email());
+            session.removeAttribute(STATE_SESSION_KEY);
+            session.removeAttribute(REDIRECT_URI_SESSION_KEY);
+            session.setAttribute(PROFILE_SESSION_KEY, profile);
+            String username = (String) session.getAttribute(USER_SESSION_KEY);
+            if (username != null && !username.isBlank()) {
+                gmailOAuthService.saveConnection(username, token, profile);
+            }
+            response.sendRedirect(frontendTarget("connected"));
+        } catch (ResponseStatusException exception) {
+            session.removeAttribute(STATE_SESSION_KEY);
+            session.removeAttribute(REDIRECT_URI_SESSION_KEY);
+            session.removeAttribute(PROFILE_SESSION_KEY);
+            log.warn("Gmail OAuth account rejected: {}", exception.getReason());
+            response.sendRedirect(frontendTarget("not-allowed"));
+        }
+    }
+
+    private String frontendTarget(String status) {
+        String frontendUrl = applicationProperties.getSystem().getFrontendUrl();
+        String path = "/mail?gmail=" + status;
+        return frontendUrl == null || frontendUrl.isBlank()
+                ? path
+                : frontendUrl.trim().replaceAll("/$", "") + path;
+    }
+
+    private String randomState() {
+        byte[] bytes = new byte[32];
+        secureRandom.nextBytes(bytes);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
+    }
+}
@@ -0,0 +1,464 @@
+package stirling.software.proprietary.mail;
+
+import java.io.IOException;
+import java.io.Serializable;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Base64;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class GmailOAuthService {
+
+    private static final String AUTHORIZATION_URI = "https://accounts.google.com/o/oauth2/v2/auth";
+    private static final String TOKEN_URI = "https://oauth2.googleapis.com/token";
+    private static final String USER_INFO_URI = "https://www.googleapis.com/oauth2/v3/userinfo";
+    private static final String GMAIL_API_URI = "https://gmail.googleapis.com/gmail/v1/users/me";
+    static final String READONLY_SCOPE =
+            "openid email https://www.googleapis.com/auth/gmail.readonly";
+
+    private final ObjectMapper objectMapper;
+    private final GmailConnectionRepository connectionRepository;
+    private final ApplicationProperties applicationProperties;
+    // Kept replaceable for deterministic tests; production uses the standard JDK client.
+    private HttpClient httpClient = HttpClient.newHttpClient();
+
+    @Value("${mailbox.gmail.client-id:}")
+    private String clientId;
+
+    @Value("${mailbox.gmail.client-secret:}")
+    private String clientSecret;
+
+    @Value("${mailbox.gmail.redirect-uri:}")
+    private String redirectUri;
+
+    public String authorizationUrl(String state, HttpServletRequest request) {
+        requireConfigured();
+        String resolvedRedirectUri = resolveRedirectUri(request);
+        Map<String, String> params = new LinkedHashMap<>();
+        params.put("client_id", clientId);
+        params.put("redirect_uri", resolvedRedirectUri);
+        params.put("response_type", "code");
+        params.put("scope", READONLY_SCOPE);
+        params.put("access_type", "offline");
+        params.put("prompt", "consent");
+        params.put("state", state);
+        return AUTHORIZATION_URI + "?" + formEncode(params);
+    }
+
+    public GmailToken exchangeCode(String code, String resolvedRedirectUri)
+            throws IOException, InterruptedException {
+        requireConfigured();
+        Map<String, String> form = new LinkedHashMap<>();
+        form.put("code", code);
+        form.put("client_id", clientId);
+        form.put("client_secret", clientSecret);
+        form.put("redirect_uri", resolvedRedirectUri);
+        form.put("grant_type", "authorization_code");
+
+        HttpRequest request =
+                HttpRequest.newBuilder(URI.create(TOKEN_URI))
+                        .header("Content-Type", "application/x-www-form-urlencoded")
+                        .POST(HttpRequest.BodyPublishers.ofString(formEncode(form)))
+                        .build();
+        HttpResponse<String> response =
+                httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        if (response.statusCode() / 100 != 2) {
+            throw new IOException(
+                    "Gmail OAuth token exchange failed: HTTP " + response.statusCode());
+        }
+        JsonNode body = objectMapper.readTree(response.body());
+        String accessToken = body.path("access_token").asText("");
+        String refreshToken = body.path("refresh_token").asText("");
+        long expiresIn = body.path("expires_in").asLong(3600);
+        if (accessToken.isBlank())
+            throw new IOException("Gmail OAuth response did not contain an access token");
+        return new GmailToken(
+                accessToken, refreshToken, System.currentTimeMillis() + expiresIn * 1000L);
+    }
+
+    public GmailProfile getProfile(GmailToken token) throws IOException, InterruptedException {
+        HttpRequest request =
+                HttpRequest.newBuilder(URI.create(USER_INFO_URI))
+                        .header("Authorization", "Bearer " + token.accessToken())
+                        .GET()
+                        .build();
+        HttpResponse<String> response =
+                httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        if (response.statusCode() / 100 != 2) {
+            throw new IOException("Gmail profile request failed: HTTP " + response.statusCode());
+        }
+        JsonNode body = objectMapper.readTree(response.body());
+        return new GmailProfile(body.path("email").asText(""), body.path("name").asText(""));
+    }
+
+    public void saveConnection(String username, GmailToken token, GmailProfile profile) {
+        ensureEmailAllowed(profile.email());
+        GmailConnectionEntity entity =
+                connectionRepository.findByUsername(username).orElseGet(GmailConnectionEntity::new);
+        String refreshToken = token.refreshToken();
+        if ((refreshToken == null || refreshToken.isBlank())
+                && entity.getRefreshToken() != null
+                && !entity.getRefreshToken().isBlank()) {
+            refreshToken = entity.getRefreshToken();
+        }
+        entity.setUsername(username);
+        entity.setAccessToken(token.accessToken());
+        entity.setRefreshToken(refreshToken == null ? "" : refreshToken);
+        entity.setExpiresAt(token.expiresAt());
+        entity.setEmail(profile.email());
+        entity.setDisplayName(profile.name());
+        connectionRepository.save(entity);
+    }
+
+    /**
+     * Ensures that only configured Google accounts can create or retain a mailbox connection. An
+     * empty allowlist intentionally permits every Google account.
+     */
+    void ensureEmailAllowed(String email) {
+        List<String> allowedEmails =
+                applicationProperties.getMailbox().getGmail().getAllowedEmails();
+        boolean allowAll =
+                allowedEmails == null
+                        || allowedEmails.stream()
+                                .allMatch(value -> value == null || value.isBlank());
+        boolean allowed =
+                allowAll
+                        || (email != null
+                                && allowedEmails.stream()
+                                        .filter(value -> value != null && !value.isBlank())
+                                        .map(String::trim)
+                                        .anyMatch(value -> value.equalsIgnoreCase(email.trim())));
+        if (!allowed) {
+            throw new ResponseStatusException(
+                    HttpStatus.FORBIDDEN, "This Google account is not allowed to connect");
+        }
+    }
+
+    public GmailConnection getConnection(String username) {
+        return connectionRepository
+                .findByUsername(username)
+                .map(
+                        entity ->
+                                new GmailConnection(
+                                        new GmailToken(
+                                                entity.getAccessToken(),
+                                                entity.getRefreshToken(),
+                                                entity.getExpiresAt()),
+                                        new GmailProfile(
+                                                entity.getEmail(), entity.getDisplayName())))
+                .orElse(null);
+    }
+
+    /** Removes the local connection and revokes the Google grant when possible. */
+    public boolean disconnect(String username) {
+        GmailConnectionEntity entity = connectionRepository.findByUsername(username).orElse(null);
+        if (entity == null) return false;
+        boolean revoked = false;
+        try {
+            String revokeToken =
+                    entity.getRefreshToken() == null || entity.getRefreshToken().isBlank()
+                            ? entity.getAccessToken()
+                            : entity.getRefreshToken();
+            revoked = revokeToken(revokeToken);
+        } catch (IOException e) {
+            log.warn(
+                    "Could not revoke Gmail OAuth grant for user '{}'; local connection removed",
+                    username,
+                    e);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            log.warn(
+                    "Gmail OAuth revoke interrupted for user '{}'; local connection removed",
+                    username);
+        } finally {
+            connectionRepository.delete(entity);
+        }
+        return revoked;
+    }
+
+    private boolean revokeToken(String token) throws IOException, InterruptedException {
+        HttpRequest request =
+                HttpRequest.newBuilder(URI.create("https://oauth2.googleapis.com/revoke"))
+                        .header("Content-Type", "application/x-www-form-urlencoded")
+                        .POST(HttpRequest.BodyPublishers.ofString("token=" + encode(token)))
+                        .build();
+        HttpResponse<String> response =
+                httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        return response.statusCode() / 100 == 2 || response.statusCode() == 400;
+    }
+
+    public GmailToken getValidToken(String username) throws IOException, InterruptedException {
+        GmailConnection connection = getConnection(username);
+        if (connection == null) {
+            throw new org.springframework.web.server.ResponseStatusException(
+                    org.springframework.http.HttpStatus.UNAUTHORIZED,
+                    "Gmail mailbox is not connected");
+        }
+        GmailToken token = connection.token();
+        if (token.expiresAt() > System.currentTimeMillis() + 60_000L) {
+            return token;
+        }
+        if (token.refreshToken() == null || token.refreshToken().isBlank()) {
+            throw new IOException("Gmail connection has no refresh token; reconnect required");
+        }
+        GmailToken refreshed = refreshToken(token.refreshToken());
+        saveConnection(username, refreshed, connection.profile());
+        return refreshed;
+    }
+
+    private GmailToken refreshToken(String refreshToken) throws IOException, InterruptedException {
+        requireConfigured();
+        Map<String, String> form = new LinkedHashMap<>();
+        form.put("client_id", clientId);
+        form.put("client_secret", clientSecret);
+        form.put("refresh_token", refreshToken);
+        form.put("grant_type", "refresh_token");
+        HttpRequest request =
+                HttpRequest.newBuilder(URI.create(TOKEN_URI))
+                        .header("Content-Type", "application/x-www-form-urlencoded")
+                        .POST(HttpRequest.BodyPublishers.ofString(formEncode(form)))
+                        .build();
+        HttpResponse<String> response =
+                httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        if (response.statusCode() / 100 != 2) {
+            throw new IOException(
+                    "Gmail OAuth token refresh failed: HTTP " + response.statusCode());
+        }
+        JsonNode body = objectMapper.readTree(response.body());
+        String accessToken = body.path("access_token").asText("");
+        if (accessToken.isBlank()) {
+            throw new IOException("Gmail OAuth refresh response did not contain an access token");
+        }
+        long expiresIn = body.path("expires_in").asLong(3600);
+        return new GmailToken(
+                accessToken, refreshToken, System.currentTimeMillis() + expiresIn * 1000L);
+    }
+
+    public GmailMessagePage listMessages(
+            GmailToken token, String folder, String types, String query, String pageToken)
+            throws IOException, InterruptedException {
+        String label =
+                switch (folder) {
+                    case "starred" -> "STARRED";
+                    case "trash" -> "TRASH";
+                    default -> "INBOX";
+                };
+        String pageQuery =
+                pageToken == null || pageToken.isBlank()
+                        ? ""
+                        : "&pageToken=" + URLEncoder.encode(pageToken, StandardCharsets.UTF_8);
+        String gmailQuery = buildGmailQuery(types, query);
+        JsonNode list =
+                sendJson(
+                        token,
+                        GMAIL_API_URI
+                                + "/messages?labelIds="
+                                + label
+                                + "&maxResults=25&q="
+                                + URLEncoder.encode(gmailQuery, StandardCharsets.UTF_8)
+                                + pageQuery);
+        List<GmailMessage> messages = new ArrayList<>();
+        Map<String, String> labelNames = loadLabelNames(token);
+        for (JsonNode item : list.path("messages")) {
+            JsonNode message =
+                    sendJson(
+                            token,
+                            GMAIL_API_URI
+                                    + "/messages/"
+                                    + item.path("id").asText()
+                                    + "?format=full");
+            messages.add(toMessage(message, labelNames));
+        }
+        return new GmailMessagePage(messages, list.path("nextPageToken").asText(null));
+    }
+
+    private String buildGmailQuery(String types, String query) {
+        StringBuilder gmailQuery = new StringBuilder("has:attachment");
+        if (types != null && !types.isBlank()) {
+            String filenameQuery =
+                    Arrays.stream(types.split(","))
+                            .map(String::trim)
+                            .map(String::toLowerCase)
+                            .filter(type -> type.matches("[a-z0-9]{1,10}"))
+                            .distinct()
+                            .map(type -> "filename:" + type)
+                            .collect(Collectors.joining(" "));
+            if (!filenameQuery.isBlank()) {
+                gmailQuery.append(" {").append(filenameQuery).append("}");
+            }
+        }
+        if (query != null && !query.isBlank()) {
+            gmailQuery.append(' ').append(query.trim());
+        }
+        return gmailQuery.toString();
+    }
+
+    public GmailAttachmentData downloadAttachment(
+            GmailToken token, String messageId, String attachmentId)
+            throws IOException, InterruptedException {
+        JsonNode attachment =
+                sendJson(
+                        token,
+                        GMAIL_API_URI + "/messages/" + messageId + "/attachments/" + attachmentId);
+        byte[] data = Base64.getUrlDecoder().decode(attachment.path("data").asText(""));
+        return new GmailAttachmentData(data);
+    }
+
+    private Map<String, String> loadLabelNames(GmailToken token)
+            throws IOException, InterruptedException {
+        Map<String, String> labelNames = new LinkedHashMap<>();
+        JsonNode response = sendJson(token, GMAIL_API_URI + "/labels");
+        for (JsonNode label : response.path("labels")) {
+            String id = label.path("id").asText("");
+            String name = label.path("name").asText("");
+            if (!id.isBlank() && !name.isBlank()) {
+                labelNames.put(id, name);
+            }
+        }
+        return labelNames;
+    }
+
+    private GmailMessage toMessage(JsonNode message, Map<String, String> labelNames) {
+        JsonNode payload = message.path("payload");
+        String from = header(payload, "From");
+        String subject = header(payload, "Subject");
+        String date = header(payload, "Date");
+        List<String> labels = new ArrayList<>();
+        for (JsonNode labelId : message.path("labelIds")) {
+            String id = labelId.asText("");
+            String name = labelNames.get(id);
+            if (!"UNREAD".equals(id) && name != null && !name.isBlank()) {
+                labels.add(name);
+            }
+        }
+        List<GmailAttachment> attachments = new ArrayList<>();
+        collectAttachments(payload, attachments);
+        return new GmailMessage(
+                message.path("id").asText(),
+                from,
+                subject,
+                message.path("snippet").asText(""),
+                date,
+                message.path("labelIds").toString().contains("UNREAD"),
+                labels,
+                attachments);
+    }
+
+    private void collectAttachments(JsonNode part, List<GmailAttachment> attachments) {
+        String filename = part.path("filename").asText("");
+        String attachmentId = part.path("body").path("attachmentId").asText("");
+        if (!filename.isBlank() && !attachmentId.isBlank()) {
+            attachments.add(
+                    new GmailAttachment(
+                            attachmentId,
+                            filename,
+                            part.path("mimeType").asText("application/octet-stream"),
+                            part.path("body").path("size").asLong(0)));
+        }
+        for (JsonNode child : part.path("parts")) {
+            collectAttachments(child, attachments);
+        }
+    }
+
+    private String header(JsonNode payload, String name) {
+        for (JsonNode header : payload.path("headers")) {
+            if (name.equalsIgnoreCase(header.path("name").asText())) {
+                return header.path("value").asText("");
+            }
+        }
+        return "";
+    }
+
+    private JsonNode sendJson(GmailToken token, String url)
+            throws IOException, InterruptedException {
+        HttpRequest request =
+                HttpRequest.newBuilder(URI.create(url))
+                        .header("Authorization", "Bearer " + token.accessToken())
+                        .GET()
+                        .build();
+        HttpResponse<String> response =
+                httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        if (response.statusCode() / 100 != 2) {
+            throw new IOException("Gmail API request failed: HTTP " + response.statusCode());
+        }
+        return objectMapper.readTree(response.body());
+    }
+
+    public String resolveRedirectUri(HttpServletRequest request) {
+        if (redirectUri != null && !redirectUri.isBlank()) return redirectUri;
+        return ServletUriComponentsBuilder.fromCurrentContextPath()
+                .path("/api/v1/email/gmail/callback")
+                .build()
+                .toUriString();
+    }
+
+    private void requireConfigured() {
+        if (clientId == null
+                || clientId.isBlank()
+                || clientSecret == null
+                || clientSecret.isBlank()) {
+            throw new IllegalStateException("Gmail OAuth is not configured on the server");
+        }
+    }
+
+    private static String formEncode(Map<String, String> values) {
+        return values.entrySet().stream()
+                .map(entry -> encode(entry.getKey()) + "=" + encode(entry.getValue()))
+                .collect(java.util.stream.Collectors.joining("&"));
+    }
+
+    private static String encode(String value) {
+        return URLEncoder.encode(value, StandardCharsets.UTF_8);
+    }
+
+    public record GmailToken(String accessToken, String refreshToken, long expiresAt)
+            implements Serializable {}
+
+    public record GmailProfile(String email, String name) implements Serializable {}
+
+    public record GmailMessage(
+            String id,
+            String sender,
+            String subject,
+            String preview,
+            String date,
+            boolean unread,
+            List<String> labels,
+            List<GmailAttachment> attachments) {}
+
+    public record GmailMessagePage(List<GmailMessage> messages, String nextPageToken) {}
+
+    public record GmailAttachment(String id, String name, String mimeType, long size) {}
+
+    public record GmailAttachmentData(byte[] data) {}
+
+    public record GmailConnection(GmailToken token, GmailProfile profile) {}
+}
@@ -0,0 +1,48 @@
+package stirling.software.proprietary.notification;
+
+import java.util.List;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+/**
+ * Open to any authenticated user, unlike the failure endpoints it draws on: each source scopes its
+ * own rows. Read-only, because every action a notification offers runs on the client's own device.
+ */
+@RestController
+@RequestMapping("/api/v1/notifications")
+@Hidden
+@RequiredArgsConstructor
+@Tag(name = "Notifications", description = "Things worth telling the caller about")
+public class NotificationController {
+
+    /** How many notifications one read returns when the caller does not say: one panelful. */
+    private static final int DEFAULT_LIMIT = 20;
+
+    /** The most one read may return however large a limit the caller asks for. */
+    private static final int MAX_LIMIT = 100;
+
+    private final NotificationService notifications;
+
+    @GetMapping
+    @Operation(
+            summary = "List the caller's notifications",
+            description =
+                    "Newest first. Derived from the sources that produce them, so there is nothing"
+                            + " to mark read here yet: the client tracks what it has shown.")
+    public NotificationsResponse list(@RequestParam(required = false) Integer limit) {
+        int capped = Math.min(limit == null ? DEFAULT_LIMIT : Math.max(1, limit), MAX_LIMIT);
+        return new NotificationsResponse(notifications.list(capped));
+    }
+
+    /** Wrapped so paging or a total can be added without breaking clients. */
+    public record NotificationsResponse(List<NotificationView> notifications) {}
+}
@@ -0,0 +1,53 @@
+package stirling.software.proprietary.notification;
+
+import java.util.List;
+
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.proprietary.failure.FileRunEvent;
+import stirling.software.proprietary.failure.FileRunEventService;
+import stirling.software.proprietary.failure.FileRunEventView;
+
+/**
+ * Derived on read rather than stored: one source today, and a table would need a write path,
+ * retention and a per-user read model first. Each source scopes its own rows, so this cannot widen.
+ */
+@Service
+@RequiredArgsConstructor
+public class NotificationService {
+
+    private final FileRunEventService fileRunEvents;
+
+    /** Newest first, and only open failures: one already dealt with is not news. */
+    public List<NotificationView> list(int limit) {
+        return fileRunEvents.list(null, null, limit).stream().map(this::fromFailure).toList();
+    }
+
+    /** Prefixes the row id on the way out, so it is never sent bare. */
+    private NotificationView fromFailure(FileRunEvent event) {
+        return new NotificationView(
+                NotificationSource.FAILURE.qualify(event.id()),
+                NotificationSource.FAILURE,
+                event.kind().getId(),
+                event.origin(),
+                fileRunEvents.ownershipOf(event),
+                event.severity(),
+                event.status(),
+                event.kind().getTitleKey(),
+                event.kind().getDefaultTitle(),
+                event.detail(),
+                event.fileId(),
+                event.sourceId(),
+                event.policyId(),
+                event.occurrences(),
+                event.createdAt(),
+                event.lastSeenAt(),
+                // A disposition such as Dismiss belongs to the review surface, not the bell.
+                fileRunEvents.availableActions(event).stream()
+                        .filter(action -> !action.id().runsOnServer())
+                        .map(FileRunEventView.ActionView::of)
+                        .toList());
+    }
+}
@@ -0,0 +1,21 @@
+package stirling.software.proprietary.notification;
+
+import java.util.Locale;
+
+/**
+ * Which subsystem produced a notification. Every id is prefixed with it, so a client never holds
+ * the producing row's own id and cannot reach that source's endpoints by accident.
+ */
+public enum NotificationSource {
+    FAILURE;
+
+    private static final char SEPARATOR = ':';
+
+    public String prefix() {
+        return name().toLowerCase(Locale.ROOT) + SEPARATOR;
+    }
+
+    public String qualify(String sourceRowId) {
+        return prefix() + sourceRowId;
+    }
+}
@@ -0,0 +1,33 @@
+package stirling.software.proprietary.notification;
+
+import java.time.Instant;
+import java.util.List;
+
+import stirling.software.proprietary.failure.FailureOrigin;
+import stirling.software.proprietary.failure.FailureSeverity;
+import stirling.software.proprietary.failure.FileRunEventStatus;
+import stirling.software.proprietary.failure.FileRunEventView;
+import stirling.software.proprietary.failure.Ownership;
+
+/**
+ * A source's row flattened to what a bell renders. {@code fileId} is an opaque reference, never a
+ * name, and two id spaces share it: {@code sourceId} tells them apart.
+ */
+public record NotificationView(
+        String id,
+        NotificationSource source,
+        String kindId,
+        FailureOrigin origin,
+        Ownership ownership,
+        FailureSeverity severity,
+        FileRunEventStatus status,
+        String titleKey,
+        String defaultTitle,
+        String detail,
+        String fileId,
+        String sourceId,
+        String policyId,
+        int occurrences,
+        Instant createdAt,
+        Instant lastSeenAt,
+        List<FileRunEventView.ActionView> actions) {}
@@ -576,7 +576,9 @@ public class PolicyController {
                            + " under 'fileInput', supporting files under 'assets[i].key' /"
                            + " 'assets[i].file' - only for bindings the policy does not already"
                            + " store). Runs regardless of the policy's enabled flag, which only"
-                            + " gates automatic triggering. Returns a run id.")
+                            + " gates automatic triggering. A single-document run may also send its"
+                            + " own opaque 'fileId', which is recorded against any failure so the"
+                            + " caller can resolve it back to that document. Returns a run id.")
    public ResponseEntity<JobResponse<Void>> runStoredPolicy(
            @PathVariable String policyId, @Valid @ModelAttribute PolicyRunFiles files)
            throws IOException {
@@ -590,7 +592,14 @@ public class PolicyController {
                                                HttpStatus.NOT_FOUND, "No policy: " + policyId));
        stampPolicyAudit(policy.toDefinition());
        PolicyInputs inputs = toInputs(files);
-        String runId = policyRunner.runWith(policy, inputs, PolicyProgressListener.NOOP).runId();
+        String runId =
+                policyRunner
+                        .runWith(
+                                policy,
+                                inputs,
+                                PolicyProgressListener.NOOP,
+                                documentReferenceFor(files, inputs))
+                        .runId();
        return ResponseEntity.accepted().body(new JobResponse<>(true, runId, null));
    }

@@ -722,6 +731,19 @@ public class PolicyController {
        return new PolicyInputs(primary, supportingFiles);
    }

+    /**
+     * Only for a single-document run: an incident holds one file reference, so naming one of
+     * several would attribute the failure to whichever bound first. Counted off resolved inputs,
+     * not parts.
+     */
+    private static String documentReferenceFor(PolicyRunFiles files, PolicyInputs inputs) {
+        String fileId = files.getFileId();
+        if (fileId == null || fileId.isBlank() || inputs.primary().size() != 1) {
+            return null;
+        }
+        return fileId;
+    }
+
    private PolicyProgressListener streamListener(SseEmitter emitter) {
        return new PolicyProgressListener() {
            @Override
@@ -16,8 +16,8 @@ import lombok.Data;
 * from the multipart request via {@code @ModelAttribute}; the pipeline definition itself travels as
 * a separate typed {@code json} part.
 *
- * <p>Wire form: {@code fileInput} (repeated) for primaries, and {@code assets[i].key} / {@code
- * assets[i].file} for each supporting asset.
+ * <p>Wire form: {@code fileInput} (repeated) for primaries, {@code assets[i].key} / {@code
+ * assets[i].file} for each supporting asset, and the optional {@code fileId}.
 */
@Data
@Schema(description = "Files for a policy run: primary documents plus keyed supporting assets")
@@ -29,4 +29,16 @@ public class PolicyRunFiles {
    @Valid
    @Schema(description = "Supporting files, each bound to the asset key its step references")
    private List<NamedAsset> assets = new ArrayList<>();
+
+    /**
+     * Recorded against any failure of this run, so the client can resolve the row back to its
+     * document. Opaque by contract, never a name, and only honoured for a single-document run.
+     */
+    @Schema(
+            description =
+                    "The caller's opaque id for the document being run, echoed onto any failure"
+                            + " recorded for this run so the originating client can resolve it."
+                            + " Ignored unless exactly one primary document is supplied. Never a"
+                            + " filename.")
+    private String fileId;
 }
@@ -151,7 +151,8 @@ public class PolicyEngine {
     * As {@link #runPolicy(Policy, PolicyInputs, PolicyProgressListener)}, recording which source
     * fed the run and its opaque reference to the document. The first says where an unattended
     * failure came from; the second says which document, and is what lets the same document failing
-     * again fold into one incident. Both null for a user's upload.
+     * again fold into one incident. With no source {@code fileIdentity} is the client's own
+     * reference, with one it is that source's hash; this engine only carries it either way.
     */
    public PolicyRunHandle runPolicy(
            Policy policy,
--- a/Show More
+++ b/Show More