Merge branch 'main' into custom_task_20260812

form field editing (#6655 )
# Description of Changes Building ontop of a users draft PR for form creation tools **Fill Form** becomes a full **Form Editor**: fill, create, modify and delete AcroForm fields visually. Builds on the community form-creation draft, plus a UX/UI rework pass. - **Backend**: `/api/v1/form` endpoints — `fields-with-coordinates`, `add/modify/delete-fields`, combined `edit-fields` (one round-trip), `fill`, `extract-csv/xlsx`; supports text (multiline, comb), checkbox, dropdown, list box, radio, button actions (reset/print/URL/submit) and signature placeholders - **Create**: type palette, click-or-drag placement with snap guides, inline property editor, batch "Add N fields" - **Modify**: move/resize on the page, arrow-nudge + Delete key, X/Y/W/H inputs, staged edits/deletes with chips, discard - **Fill**: live progress + required tracking, flatten toggle, Export menu (JSON/CSV/XLSX), Ctrl/Cmd+S - **Safety**: confirm dialog before discarding staged work; empty required fields warn with "Save anyway" instead of blocking - **UI**: consistent panel skeleton (fixed header / scrolling list / pinned actions), empty states that link into Create, full i18n with plural keys [walkthrough.html](https://github.com/user-attachments/files/30508976/walkthrough.html) --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### Translations (if applicable) - [ ] I ran [`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have run `task check` to verify linters, typechecks, and tests pass - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#7-testing) for more details. --------- Co-authored-by: Denys Vitali <denys@denv.it> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-09-03 05:10:16 +03:00 · 2026-08-25 00:20:59 +02:00 · 2026-08-24 20:45:54 +00:00 · 2026-08-24 17:39:57 +00:00 · 2026-08-24 16:23:55 +00:00 · 2026-08-24 15:06:22 +00:00
460 changed files with 44248 additions and 17166 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
@@ -0,0 +1,80 @@
+name: Setup Task from the CI image
+description: Install the pinned Task binary from the CI image when Docker is available, or from a verified release archive
+inputs:
+  version:
+    description: Task version to install
+    required: false
+    default: 3.53.1
+runs:
+  using: composite
+  steps:
+    - name: Install Task on Linux
+      if: runner.os == 'Linux'
+      shell: bash
+      env:
+        TASK_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+        install_dir="${RUNNER_TEMP}/task-bin"
+        mkdir -p "${install_dir}"
+
+        if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+          image="ghcr.io/stirling-tools/stirling-pdf-ci:task-${TASK_VERSION}"
+          docker pull "${image}"
+          container_id="$(docker create "${image}")"
+          cleanup() { docker rm "${container_id}" >/dev/null; }
+          trap cleanup EXIT
+          docker cp "${container_id}:/usr/local/bin/task" "${install_dir}/task"
+          chmod 0755 "${install_dir}/task"
+        else
+          case "${RUNNER_ARCH}" in
+            X64) task_arch=amd64 ;;
+            ARM64) task_arch=arm64 ;;
+            *) echo "Unsupported runner architecture: ${RUNNER_ARCH}" >&2; exit 1 ;;
+          esac
+          task_file="task_linux_${task_arch}.tar.gz"
+          archive="${RUNNER_TEMP}/${task_file}"
+          checksums="${RUNNER_TEMP}/task_checksums.txt"
+          release_url="https://github.com/go-task/task/releases/download/v${TASK_VERSION}"
+          curl --fail --silent --show-error --location --http1.1 \
+            --retry 5 --retry-all-errors --retry-delay 2 --connect-timeout 30 \
+            "${release_url}/${task_file}" --output "${archive}"
+          curl --fail --silent --show-error --location --http1.1 \
+            --retry 5 --retry-all-errors --retry-delay 2 --connect-timeout 30 \
+            "${release_url}/task_checksums.txt" --output "${checksums}"
+          (
+            cd "${RUNNER_TEMP}"
+            grep "  ${task_file}$" "${checksums}" | sha256sum -c -
+          )
+          tar -xzf "${archive}" -C "${install_dir}" task
+        fi
+        echo "${install_dir}" >> "${GITHUB_PATH}"
+
+    - name: Install Task natively
+      if: runner.os != 'Linux'
+      shell: bash
+      env:
+        TASK_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+        install_dir="${RUNNER_TEMP}/task-bin"
+        mkdir -p "${install_dir}"
+        case "${RUNNER_OS}-${RUNNER_ARCH}" in
+          macOS-X64) task_platform=darwin; task_arch=amd64; task_file=task_darwin_amd64.tar.gz; task_sha256=7f1a702d54a789cb818a636039a83df071f4179893133afafa4eba351a7e19ef ;;
+          macOS-ARM64) task_platform=darwin; task_arch=arm64; task_file=task_darwin_arm64.tar.gz; task_sha256=85d2d96c2380b33d7855b07b3f7a20dc7ca0eda999a26efa0fb5f6f32b366cd7 ;;
+          Windows-X64) task_platform=windows; task_arch=amd64; task_file=task_windows_amd64.zip; task_sha256=27c0cd248c12cba03d8958d954a3df981c900be885ec9ce5f6a3cdc4e9a19316 ;;
+          Windows-ARM64) task_platform=windows; task_arch=arm64; task_file=task_windows_arm64.zip; task_sha256=4f7c32c0b5a09aabfd860bcf4ff5649f0483339c1f7f90ad5ee55692da7237b6 ;;
+          *) echo "Unsupported runner: ${RUNNER_OS}-${RUNNER_ARCH}" >&2; exit 1 ;;
+        esac
+        archive="${RUNNER_TEMP}/${task_file}"
+        curl --fail --silent --show-error --location --http1.1 \
+          --retry 5 --retry-all-errors --retry-delay 2 --connect-timeout 30 \
+          "https://github.com/go-task/task/releases/download/v${TASK_VERSION}/${task_file}" \
+          --output "${archive}"
+        echo "${task_sha256}  ${archive}" | sha256sum -c -
+        if [[ "${task_platform}" == windows ]]; then
+          unzip -p "${archive}" task.exe > "${install_dir}/task.exe"
+        else
+          tar -xzf "${archive}" -C "${install_dir}" task
+        fi
+        echo "${install_dir}" >> "${GITHUB_PATH}"
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-desktop
-pkgver=2.14.2
+pkgver=2.14.3
 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.2
+pkgver=2.14.3
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
 arch=('any')
@@ -4,10 +4,12 @@
 # instead of matching only the project filter.
 ci: &ci
  - .github/workflows/build.yml
+  - .github/workflows/gradle-cache-prime.yml
  - .github/config/.files.yaml

 build: &build
  - *ci
+  - buildSrc/**
  - build.gradle
  - gradle/spotless.gradle
  - app/(common|core|proprietary|saas)/build.gradle
@@ -15,6 +17,22 @@ build: &build
  - .taskfiles/backend.yml
  - .github/workflows/check-licence.yml

+# Backend build inputs. This is intentionally broader than `build`: Java and
+# backend resource changes must exercise the backend matrix even when Gradle
+# build scripts themselves are unchanged.
+backend: &backend
+  - *ci
+  - *build
+  - gradle/**
+  - gradle.properties
+  - gradlew
+  - gradlew.bat
+  - settings.gradle
+  - app/(common|core|proprietary|saas)/src/(main|test)/java/**
+  - "app/(common|core|proprietary|saas)/src/(main|test)/resources/**/!(messages_*.properties|*.md)*"
+  - scripts/db-migration/**
+  - .github/workflows/backend-build.yml
+
 openapi: &openapi
  - *ci
  - *build
@@ -31,6 +31,7 @@ updates:
      - "/docker/embedded"
      - "/docker/frontend"
      - "/docker/base"
+      - "/docker/ci"
      - "/docker/engine"
      - "/docker/unoserver"
      - "/engine"
@@ -65,6 +66,7 @@ updates:
    directories:
      - /devTools
      - /frontend
+      - /testing/compose/mcp-client-check
    schedule:
      interval: "weekly"
    cooldown:
@@ -93,6 +95,13 @@ updates:
          - "react-dom"
          - "@types/react"
          - "@types/react-dom"
+      tanstack:
+        patterns:
+          - "@tanstack/*"
+      typescript:
+        patterns:
+          - "typescript"
+          - "@typescript/*"
      vite:
        patterns:
          - "vite"
@@ -171,14 +180,6 @@ updates:
          - "tokio"
          - "tokio-*"

-  - package-ecosystem: pip
-    directory: /testing/cucumber
-    schedule:
-      interval: "weekly"
-    cooldown:
-      default-days: 7
-    rebase-strategy: "auto"
-
  - package-ecosystem: "uv"
    directory: "/engine"
    schedule:
@@ -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

@@ -353,7 +353,7 @@ jobs:

      - name: Install Task for Storybook
        if: steps.sb-changes.outputs.storybook == 'true'
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Build and deploy Storybook
        id: storybook
@@ -462,7 +462,10 @@ jobs:
            });

  cleanup-v2-deployment:
-    environment: pr-preview
+    # Tearing a preview down is not a deployment - no deployment object.
+    environment:
+      name: pr-preview
+      deployment: false
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    permissions:
@@ -472,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

@@ -557,5 +560,5 @@ jobs:
      - name: Cleanup temporary files
        if: always()
        run: |
-          rm -f ../private.key
+          rm -f ../private.key docker-compose.yml storybook.tgz
        continue-on-error: true
@@ -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

@@ -206,7 +206,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Run Gradle Command
        run: |
          if [ "${{ needs.check-comment.outputs.disable_security }}" == "true" ]; then
@@ -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

@@ -9,7 +9,10 @@ permissions:

 jobs:
  cleanup:
-    environment: pr-preview
+    # Tearing a preview down is not a deployment - no deployment object.
+    environment:
+      name: pr-preview
+      deployment: false
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    permissions:
@@ -19,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

@@ -28,7 +28,7 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -37,7 +37,7 @@ jobs:
          cache-suffix: ai-engine

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Quality-check engine
        id: engine-check
@@ -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

@@ -20,7 +20,9 @@ permissions:

 jobs:
  build:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
@@ -29,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
@@ -50,7 +52,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Check Java formatting (Spotless)
        # Runs once per matrix combination - pick the cheapest leg
        # (core - no proprietary, no saas) so we don't wait for the
@@ -195,7 +197,7 @@ jobs:

      - name: Install uv
        if: always() && matrix.flavor == 'saas'
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -42,7 +42,9 @@ jobs:
    uses: ./.github/workflows/_runner-pick.yml

  playwright-e2e-enterprise:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    needs: pick
    # Skip on fork PRs / untrusted authors: they have no PREMIUM_KEY_ENTERPRISE,
    # so the suite can't boot premium and would fail. See the header comment.
@@ -56,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
@@ -93,7 +95,7 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Install Playwright (chromium only)
        run: task e2e:install -- chromium
      - name: Build frontend (needed for playwright's vite preview webServer)
@@ -322,10 +324,18 @@ jobs:
          path: frontend/playwright-report/
          retention-days: 7

+      - name: Cleanup temporary files
+        if: always()
+        run: |
+          rm -f /tmp/helpers.sh /tmp/backend.log /tmp/backend.pid
+        continue-on-error: true
+
  # Multi-node regression: builds + seeds the clustered stack (testing/compose/docker-compose-multinode.yml)
  # and runs behave features/multinode. Licence-gated, so it runs after the Playwright job (not in parallel).
  multinode-e2e:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    needs: [pick, playwright-e2e-enterprise]
    # Nightly cron + manual dispatch only (heavy build), fork-gated for the licence secret.
    if: >-
@@ -341,13 +351,13 @@ 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
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -37,6 +37,7 @@ jobs:
    timeout-minutes: 3
    outputs:
      build: ${{ steps.changes.outputs.build }}
+      backend: ${{ steps.changes.outputs.backend }}
      project: ${{ steps.changes.outputs.project }}
      openapi: ${{ steps.changes.outputs.openapi }}
      frontend: ${{ steps.changes.outputs.frontend }}
@@ -48,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
@@ -61,61 +62,12 @@ jobs:
          filters: .github/config/.files.yaml

  gradle-cache-prime:
-    environment: ci-unsigned
-    name: Prime shared Gradle cache
    needs: [files-changed]
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
-        with:
-          egress-policy: audit
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Calculate Gradle cache key
-        id: gradle-cache-key
-        shell: bash
-        run: |
-          echo "key=gradle-v1-${{ runner.os }}-${{ runner.arch }}-jdk-25-${{ hashFiles('gradle/wrapper/gradle-wrapper.properties', 'gradle/libs.versions.toml', 'buildSrc/**', 'settings.gradle', 'build.gradle', 'app/**/build.gradle', 'gradle/**/*.gradle') }}" >> "$GITHUB_OUTPUT"
-
-      - name: Cache Gradle (lookup-only)
-        id: cache-gradle-restore
-        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: |
-            ~/.gradle/caches
-            ~/.gradle/wrapper
-          key: ${{ steps.gradle-cache-key.outputs.key }}
-          lookup-only: true
-
-      - name: Set up JDK 25
-        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
-        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
-        with:
-          java-version: "25"
-          distribution: "temurin"
-
-      - name: Resolve backend dependencies
-        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
-        run: ./gradlew :stirling-pdf:classes --no-daemon
-        env:
-          STIRLING_FLAVOR: saas
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-
-      - name: Save cache Gradle User Home
-        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
-        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: |
-            ~/.gradle/caches
-            ~/.gradle/wrapper
-          key: ${{ steps.gradle-cache-key.outputs.key }}
+    uses: ./.github/workflows/gradle-cache-prime.yml
+    secrets: inherit

  build:
+    if: needs.files-changed.outputs.backend == 'true'
    needs: [files-changed, gradle-cache-prime]
    permissions:
      actions: read
@@ -194,7 +146,7 @@ jobs:

  check-licence:
    if: needs.files-changed.outputs.build == 'true'
-    needs: [files-changed, build, gradle-cache-prime]
+    needs: [files-changed, gradle-cache-prime]
    permissions:
      contents: read
    uses: ./.github/workflows/check-licence.yml
@@ -213,7 +165,14 @@ jobs:
      docker-base-changed: ${{ needs.files-changed.outputs.docker-base }}

  test-build-docker-images:
-    if: github.event_name == 'pull_request' && needs.files-changed.outputs.project == 'true'
+    if: |
+      always() &&
+      github.event_name == 'pull_request' &&
+      needs.files-changed.outputs.project == 'true' &&
+      contains(fromJSON('["success", "skipped"]'), needs.gradle-cache-prime.result) &&
+      contains(fromJSON('["success", "skipped"]'), needs.build.result) &&
+      contains(fromJSON('["success", "skipped"]'), needs.check-generateOpenApiDocs.result) &&
+      contains(fromJSON('["success", "skipped"]'), needs.check-licence.result)
    needs:
      [
        files-changed,
@@ -319,6 +278,7 @@ jobs:
    if: always()
    needs:
      - files-changed
+      - gradle-cache-prime
      - build
      - db-migration-test
      - check-generateOpenApiDocs
@@ -338,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

@@ -346,6 +306,7 @@ jobs:
        env:
          RESULTS: |
            files-changed=${{ needs.files-changed.result }}
+            gradle-cache-prime=${{ needs.gradle-cache-prime.result }}
            build=${{ needs.build.result }}
            db-migration-test=${{ needs.db-migration-test.result }}
            check-generateOpenApiDocs=${{ needs.check-generateOpenApiDocs.result }}
@@ -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

@@ -36,7 +36,7 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -76,7 +76,7 @@ jobs:
          cache-dependency-path: frontend/package-lock.json

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Verify generated models are up to date
        id: models-check
@@ -10,11 +10,13 @@ permissions:

 jobs:
  check-licence:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    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

@@ -36,7 +38,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Check licenses for compatibility
        run: task backend:licenses:check
        env:
@@ -11,11 +11,13 @@ permissions:

 jobs:
  check-generate-openapi-docs:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    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

@@ -37,7 +39,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Generate OpenAPI documentation
        run: task backend:swagger
        env:
@@ -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

@@ -195,7 +195,7 @@ jobs:
            core.exportVariable("REFERENCE_FILE", referenceFilePath);

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -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
@@ -55,7 +55,7 @@ jobs:
          distribution: "temurin"

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -13,12 +13,14 @@ permissions:

 jobs:
  migration-test:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    runs-on: ubuntu-latest
    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

@@ -79,3 +81,8 @@ jobs:
          path: /tmp/stirling-migration-failed-*/app.log
          retention-days: 7
          if-no-files-found: warn
+
+      - name: Cleanup temporary files
+        if: always()
+        run: rm -rf /tmp/stirling-migration-failed-*
+        continue-on-error: true
@@ -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

@@ -17,7 +17,9 @@ permissions:

 jobs:
  docker-compose-tests:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    runs-on: ubuntu-latest
    permissions:
      actions: write
@@ -26,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

@@ -64,11 +66,11 @@ jobs:

      - name: Install Docker Compose
        run: |
-          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+          sudo curl -SL "https://github.com/docker/compose/releases/download/v5.4.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
          sudo chmod +x /usr/local/bin/docker-compose

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -11,12 +11,14 @@ permissions:

 jobs:
  playwright-e2e-live:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    runs-on: ubuntu-latest
    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
@@ -43,7 +45,7 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Install Playwright (chromium only)
        run: task e2e:install -- chromium
      - name: Build frontend (production bundle for vite preview)
@@ -104,7 +106,7 @@ jobs:
          fi
      - name: Install uv
        if: always()
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -14,6 +14,11 @@ jobs:
  playwright-e2e:
    name: playwright-e2e (${{ matrix.browser }})
    runs-on: ubuntu-latest
+    # The image already contains the Playwright browsers and all Linux
+    # dependencies. This keeps the matrix for per-browser reporting while
+    # avoiding three concurrent `playwright install --with-deps` runs.
+    container:
+      image: mcr.microsoft.com/playwright:v1.58.2-noble@sha256:6446946a1d9fd62d9ae501312a2d76a43ee688542b21622056a372959b65d63d
    strategy:
      # One browser breaking must not mask a failure in another - report all.
      fail-fast: false
@@ -27,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
@@ -39,16 +44,24 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
-      - name: Install Playwright (${{ matrix.browser }})
-        run: task e2e:install -- ${{ matrix.browser }}
+        uses: ./.github/actions/setup-task
      - name: Build frontend (production bundle for vite preview)
        env:
          VITE_BUILD_FOR_PREVIEW: "1"
        run: task frontend:build
      - name: Run stubbed E2E tests (${{ matrix.browser }})
        env:
+          # The official Playwright image expects its browser runtime under
+          # the root home directory. Keep this scoped to Playwright and use a
+          # neutral Docker config path so Docker does not read /root/.docker.
+          HOME: /root
+          DOCKER_CONFIG: /tmp/playwright-docker-config
          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
+          NPM_CONFIG_PREFER_OFFLINE: "true"
+          NPM_CONFIG_FETCH_RETRIES: "5"
+          NPM_CONFIG_FETCH_RETRY_FACTOR: "2"
+          NPM_CONFIG_FETCH_RETRY_MINTIMEOUT: "1000"
+          NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT: "120000"
        run: task e2e:stubbed-project PROJECT=${{ matrix.project }} -- --workers=3
      - name: Flag flaky tests
        # Runs regardless of the test outcome: a flaky test (passed on retry)
@@ -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
@@ -36,7 +36,7 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: a11y gate (changed stories)
        run: task frontend:storybook:a11y:changed -- origin/${{ github.base_ref || 'main' }}
      - name: Upload scan reports
@@ -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

@@ -43,7 +43,9 @@ jobs:

  generate-frontend-license-report:
    # ci-bot, not bot-identity: this job runs on PRs too, and bot-identity is main-only.
-    environment: ci-bot
+    environment:
+      name: ci-bot
+      deployment: false
    if: needs.files-changed.outputs.licenses-frontend == 'true'
    name: Generate Frontend License Report
    needs: files-changed
@@ -54,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

@@ -95,7 +97,7 @@ jobs:
        run: npm ci --ignore-scripts --audit=false --fund=false

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Generate frontend license report (Push only)
        if: github.event_name == 'push'
@@ -319,7 +321,9 @@ jobs:

  generate-backend-license-report:
    # ci-bot, not bot-identity: this job runs on PRs too, and bot-identity is main-only.
-    environment: ci-bot
+    environment:
+      name: ci-bot
+      deployment: false
    if: needs.files-changed.outputs.licenses-backend == 'true'
    needs: files-changed
    name: Generate Backend License Report
@@ -330,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

@@ -363,7 +367,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Check licenses and generate report
        id: license-check
@@ -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
@@ -27,7 +27,7 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Quality-check frontend
        id: frontend-check
        run: task frontend:check:all
@@ -107,7 +107,7 @@ jobs:
            }
      - name: Install uv
        if: always()
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -0,0 +1,66 @@
+name: Prime Gradle Cache
+
+on:
+  workflow_call:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  gradle-cache-prime:
+    environment:
+      name: ci-unsigned
+      deployment: false
+    name: Prime shared Gradle cache
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Calculate Gradle cache key
+        id: gradle-cache-key
+        shell: bash
+        run: |
+          echo "key=gradle-v1-${{ runner.os }}-${{ runner.arch }}-jdk-25-${{ hashFiles('gradle/wrapper/gradle-wrapper.properties', 'gradle/libs.versions.toml', 'buildSrc/**', 'settings.gradle', 'build.gradle', 'app/**/build.gradle', 'gradle/**/*.gradle') }}" >> "$GITHUB_OUTPUT"
+
+      - name: Cache Gradle (lookup-only)
+        id: cache-gradle-restore
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ steps.gradle-cache-key.outputs.key }}
+          lookup-only: true
+
+      - name: Set up JDK 25
+        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
+        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Resolve backend dependencies
+        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
+        run: ./gradlew :stirling-pdf:classes --no-daemon
+        env:
+          STIRLING_FLAVOR: saas
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+
+      - name: Save cache Gradle User Home
+        if: steps.cache-gradle-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ steps.gradle-cache-key.outputs.key }}
@@ -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

@@ -38,7 +38,9 @@ permissions:

 jobs:
  determine-matrix:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    if: ${{ vars.CI_PROFILE != 'lite' }}
    runs-on: ubuntu-latest
    outputs:
@@ -46,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

@@ -67,7 +69,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Get version number
        id: versionNumber
        run: |
@@ -116,7 +118,9 @@ jobs:
        env:
          INPUT_PLATFORM: ${{ github.event.inputs.platform }}
  build-jars:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    needs: determine-matrix
    runs-on: ubuntu-latest
    strategy:
@@ -136,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

@@ -165,7 +169,7 @@ jobs:
          cache-dependency-path: frontend/package-lock.json

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Build JAR
        run: ./gradlew build ${{ matrix.variant.build_frontend && '-PbuildWithFrontend=true' || '' }} -x spotlessApply -x spotlessCheck -x test -x sonarqube
@@ -203,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: >
@@ -264,7 +268,7 @@ jobs:
          distribution: ${{ matrix.platform == 'windows-11-arm' && 'microsoft' || 'temurin' }}

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      # Build the universal JRE before desktop:prepare so the jlink:runtime
      # task short-circuits on its `test -d runtime/jre` status check.
@@ -693,6 +697,17 @@ jobs:
          path: ./dist/*
          retention-days: 1

+      - name: Cleanup temporary files
+        if: always()
+        shell: bash
+        run: |
+          rm -f certificate.p12
+          rm -rf "$RUNNER_TEMP/msi-verify"
+          if [ "${{ matrix.platform }}" = "macos-15" ]; then
+            security delete-keychain "$RUNNER_TEMP/app-signing.keychain-db" 2>/dev/null || true
+          fi
+        continue-on-error: true
+
  collect-and-release:
    needs: [determine-matrix, build, build-jars]
    runs-on: ubuntu-latest
@@ -700,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

@@ -857,7 +872,7 @@ jobs:
      # Gate publish on valid updater sigs. Runs after the review upload (so
      # artifacts survive for debugging) and before action-gh-release.
      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -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

@@ -38,7 +38,7 @@ jobs:
          cache-dependency-path: frontend/package-lock.json

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Install all Playwright browsers
        run: task e2e:install

@@ -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

@@ -89,7 +89,7 @@ jobs:
          cache-dependency-path: frontend/package-lock.json

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: a11y gate (every story, ${{ matrix.theme }})
        run: task frontend:storybook:a11y:${{ matrix.theme }}
@@ -127,7 +127,9 @@ jobs:
  # Runs the @nightly tag (conversion scenarios) plus a 10-shard concurrency run
  # of every other feature.
  cucumber-nightly:
-    environment: ci-unsigned
+    environment:
+      name: ci-unsigned
+      deployment: false
    name: Cucumber (nightly scenarios + full concurrency)
    runs-on: ubuntu-latest
    # Fork pull requests get no MAVEN_* secrets, so the image build cannot work.
@@ -138,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

@@ -146,13 +148,13 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Set up JDK 25
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
        with:
          java-version: "25"
          distribution: "temurin"

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -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

@@ -25,7 +25,7 @@ jobs:
          persist-credentials: false

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -34,7 +34,7 @@ jobs:
          cache-suffix: pre-commit

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Run pre-commit checks
        run: task pre-commit
@@ -0,0 +1,55 @@
+name: Publish Task CI image
+
+on:
+  workflow_dispatch:
+    inputs:
+      task-version:
+        description: Task version to publish
+        required: true
+        default: 3.53.1
+        type: string
+  push:
+    paths:
+      - docker/ci/Dockerfile
+      - .github/workflows/publish-ci-image.yml
+
+jobs:
+  publish:
+    permissions:
+      contents: read
+      packages: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set Task version
+        id: version
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ inputs.task-version }}
+        run: echo "value=${INPUT_VERSION:-3.53.1}" >> "${GITHUB_OUTPUT}"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Log in to GHCR
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish Task CI image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: docker/ci/Dockerfile
+          # GitHub-hosted Linux jobs in this repository run on amd64. Avoid
+          # QEMU/arm64 here because the image is only consumed by those jobs.
+          platforms: linux/amd64
+          push: true
+          build-args: |
+            TASK_VERSION=${{ steps.version.outputs.value }}
+          tags: |
+            ghcr.io/stirling-tools/stirling-pdf-ci:task-${{ steps.version.outputs.value }}
@@ -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

@@ -77,7 +88,7 @@ jobs:
        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Get version number
        id: versionNumber
        run: echo "versionNumber=$(./gradlew printVersion --quiet | tail -1)" >> $GITHUB_OUTPUT
@@ -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

@@ -75,6 +75,6 @@ jobs:

      # Upload the results to GitHub's code scanning dashboard.
      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          sarif_file: results.sarif
@@ -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

@@ -63,7 +63,7 @@ jobs:
          SWAGGERHUB_USER: "Frooodle"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Get version number
        id: versionNumber
        run: echo "versionNumber=$(./gradlew printVersion --quiet | tail -1)" >> $GITHUB_OUTPUT
@@ -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

@@ -53,7 +53,7 @@ jobs:
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}

      - name: Install uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true
          cache-dependency-glob: |
@@ -66,7 +66,7 @@ jobs:
          uv sync --project engine --locked --group tools

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Sync translation TOML files
        run: |
@@ -63,14 +63,16 @@ jobs:
  determine-matrix:
    # Only probes APPLE_CERTIFICATE for presence, so it stays on the unrestricted
    # signing environment - release-signing would block every PR run.
-    environment: ci-signing
+    environment:
+      name: ci-signing
+      deployment: false
    if: ${{ vars.CI_PROFILE != 'lite' }}
    runs-on: ubuntu-latest
    outputs:
      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

@@ -132,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

@@ -210,7 +212,7 @@ jobs:
          distribution: ${{ matrix.platform == 'windows-11-arm' && 'microsoft' || 'temurin' }}

      - name: Setup Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task

      - name: Build universal macOS JRE
        if: matrix.platform == 'macos-15'
@@ -675,6 +677,17 @@ jobs:
            fi
          done

+      - name: Cleanup temporary files
+        if: always()
+        shell: bash
+        run: |
+          rm -f certificate.p12
+          rm -rf "$RUNNER_TEMP/msi-verify"
+          if [ "${{ matrix.platform }}" = "macos-15" ]; then
+            security delete-keychain "$RUNNER_TEMP/app-signing.keychain-db" 2>/dev/null || true
+          fi
+        continue-on-error: true
+
  pr-comment:
    needs: build
    runs-on: ubuntu-latest
@@ -690,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

@@ -782,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

@@ -22,22 +22,45 @@ permissions:
  contents: read

 jobs:
-  # TODO: extract a pre-matrix `prepare` job that runs once and produces
-  # shared artifacts for the three matrix entries below to consume:
-  #   1. `task backend:build` — currently runs 3× in parallel with
-  #      identical env (DISABLE_ADDITIONAL_FEATURES=true,
-  #      STIRLING_PDF_DESKTOP_UI=false). Build once, upload the JAR as an
-  #      artifact, matrix entries download.
-  #   2. The base-image `docker build` (gated on docker-base-changed) —
-  #      currently runs 3× in parallel against the same Dockerfile and
-  #      context. Build once, `docker save` to an artifact, matrix entries
-  #      `docker load` before the embedded build.
-  # Saves ~2 full backend builds + 2 base-image builds per PR that touches
-  # docker. May also be reusable from backend-build.yml's jdk-25 +
-  # spring-security=true matrix entry if `task backend:build` and
-  # `task backend:build:ci` produce equivalent JARs (verify before wiring).
+  # A changed base image is shared by all three embedded-image builds. Build
+  # it once and transfer it as an artifact; the matrix jobs use the local
+  # Docker driver so the loaded image is visible to the build.
+  prepare-base-image:
+    if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+    environment:
+      name: ci-unsigned
+      deployment: false
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout Repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Build base image locally
+        run: docker build --platform linux/amd64 -t stirling-pdf-base:pr-test -f docker/base/Dockerfile docker/base
+
+      - name: Export base image
+        run: docker save stirling-pdf-base:pr-test | gzip -1 > stirling-pdf-base-pr-test.tar.gz
+
+      - name: Upload base image
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docker-base-pr-test
+          path: stirling-pdf-base-pr-test.tar.gz
+          retention-days: 1
+          if-no-files-found: error
+
  test-build-docker-images:
-    environment: ci-unsigned
+    if: always() && (needs.prepare-base-image.result == 'success' || needs.prepare-base-image.result == 'skipped')
+    needs: [prepare-base-image]
+    environment:
+      name: ci-unsigned
+      deployment: false
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
@@ -54,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

@@ -79,6 +102,16 @@ jobs:
          docker system prune -af || true
          echo "Disk space after cleanup:" && df -h

+      - name: Download prepared base image
+        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: docker-base-pr-test
+
+      - name: Load prepared base image
+        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+        run: gzip -dc stirling-pdf-base-pr-test.tar.gz | docker load
+
      - name: Restore cache Gradle User Home
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
@@ -94,7 +127,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: ./.github/actions/setup-task
      - name: Build application
        run: task backend:build
        env:
@@ -111,11 +144,6 @@ jobs:
        id: buildx
        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

-      - name: Build base image locally (PR base change only)
-        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
-        run: |
-          docker build -t stirling-pdf-base:pr-test -f docker/base/Dockerfile docker/base
-
      - name: Set base image and platform for this build
        id: build-params
        # Pass workflow inputs through env vars rather than expanding `${{ }}`
@@ -189,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

@@ -0,0 +1,112 @@
+name: Update Gradle
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 3 * * 1"
+
+concurrency:
+  group: update-gradle
+  cancel-in-progress: true
+
+jobs:
+  update-gradle:
+    name: Update Gradle and Docker images
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          egress-policy: audit
+
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Java
+        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
+        with:
+          distribution: temurin
+          java-version: "25"
+
+      - name: Find latest Gradle release
+        id: gradle
+        shell: bash
+        run: |
+          set -euo pipefail
+          version=$(curl --fail --silent --show-error --retry 3 \
+            https://services.gradle.org/versions/current | jq -r '.version')
+          [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+            echo "Could not determine a stable Gradle version: $version" >&2
+            exit 1
+          }
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Find matching Docker image digest
+        id: docker
+        env:
+          GRADLE_VERSION: ${{ steps.gradle.outputs.version }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${GRADLE_VERSION}-jdk25"
+          digest=$(curl --fail --silent --show-error --retry 3 \
+            "https://hub.docker.com/v2/repositories/library/gradle/tags/${tag}" \
+            | jq -r '.digest // empty')
+          [[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || {
+            echo "Docker image gradle:${tag} was not found" >&2
+            exit 1
+          }
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "digest=$digest" >> "$GITHUB_OUTPUT"
+
+      - name: Update Gradle wrapper
+        env:
+          GRADLE_VERSION: ${{ steps.gradle.outputs.version }}
+        run: ./gradlew wrapper --gradle-version "$GRADLE_VERSION" --distribution-type bin
+
+      - name: Update Gradle Docker images
+        env:
+          DOCKER_TAG: ${{ steps.docker.outputs.tag }}
+          DOCKER_DIGEST: ${{ steps.docker.outputs.digest }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          find docker -type f -name 'Dockerfile*' -print0 |
+            xargs -0 sed -E -i \
+              "s#gradle:[^@[:space:]]+-jdk25(@sha256:[^[:space:]]+)?#gradle:${DOCKER_TAG}@${DOCKER_DIGEST}#g"
+
+      - name: Verify Gradle update
+        env:
+          EXPECTED_VERSION: ${{ steps.gradle.outputs.version }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          actual=$(./gradlew --version | sed -n 's/^Gradle \([0-9.]*\)$/\1/p')
+          [[ "$actual" == "$EXPECTED_VERSION" ]] || {
+            echo "Wrapper resolved Gradle $actual, expected $EXPECTED_VERSION" >&2
+            exit 1
+          }
+          if git diff --quiet; then
+            echo "Gradle is already up to date."
+            exit 0
+          fi
+          git diff --check
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: automation/update-gradle
+          delete-branch: true
+          commit-message: "chore: update Gradle"
+          title: "chore: update Gradle to ${{ steps.gradle.outputs.version }}"
+          body: |
+            Automated update of the Gradle wrapper and Gradle Docker build images.
+
+            Gradle version: `${{ steps.gradle.outputs.version }}`
+            Docker image: `gradle:${{ steps.docker.outputs.tag }}`
+          labels: dependencies
@@ -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
@@ -27,3 +27,8 @@ app/core/src/main/java/stirling/software/SPDF/pdf/signature/CreateSignatureBase.
 # Supabase publishable key (public by design, RLS-protected) used as a CI fallback
 # default in the tauri-build workflow when the GitHub secret is unset - not a real secret.
 .github/workflows/tauri-build.yml:generic-api-key:402
+
+# Staging Supabase publishable key (public by design). Ignored here rather than with an
+# inline gitleaks:allow because a trailing comment in a .properties file is part of the
+# value, so the pragma would end up inside the key.
+app/saas/src/main/resources/application-staging.properties:generic-api-key:16
@@ -1,5 +1,7 @@
 {
  "ignoredFiles": [
-    "frontend/editor/src-tauri/icons/icon.png"
+    "frontend/editor/src-tauri/icons/macos/*",
+    "frontend/editor/src-tauri/icons/linux/*",
+    "frontend/editor/src-tauri/icons/windows/*"
  ]
 }
@@ -57,16 +57,57 @@ tasks:
      - cmd: ./gradlew clean bootRun -PbuildWithFrontend=true
        platforms: [linux, darwin]

+  # SaaS backend. dev:saas -> the PR's preview branch, staging:saas -> shared v3,
+  # PROFILES=none -> production against your own SAAS_DB_*. Production has no named
+  # task on purpose. Use `none`, not an empty value: Go template `default` treats ""
+  # as absent and would resolve back to dev.
+
  dev:saas:
-    desc: "Start backend in SaaS flavor against Supabase"
-    # `dotenv:` reads from the root Taskfile's directory (".") because this
-    # subtaskfile is included with `dir: .`.
+    desc: "Start SaaS backend against the current PR's Supabase preview branch"
+    dotenv: ['app/.env.saas.local', 'app/.env.saas']
+    vars:
+      PROFILES: '{{.PROFILES | default "dev"}}'
+    cmds:
+      # Don't move this check into a `sh:` var: dotenv is visible in cmds but not
+      # during var evaluation, so the test would always see an empty value.
+      - cmd: |
+          if [ "{{.PROFILES}}" = "dev" ] && [ -z "${SAAS_DEV_PROJECT_REF:-}" ]; then
+            echo ">> SAAS_DEV_PROJECT_REF is not set."
+            echo ">> Testing a SaaS PR? Put its ref, DB password and publishable key in app/.env.saas.local."
+            echo ">> Wanted the shared v3 project? Use 'task backend:staging:saas' instead."
+            exit 1
+          fi
+      - task: _run:saas
+        vars:
+          PORT: '{{.PORT}}'
+          PROFILES: '{{.PROFILES}}'
+          AIENGINE_URL: '{{.AIENGINE_URL}}'
+          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
+          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+
+  staging:saas:
+    desc: "Start SaaS backend against the shared v3 staging project"
+    cmds:
+      - task: _run:saas
+        vars:
+          PORT: '{{.PORT}}'
+          PROFILES: staging
+          AIENGINE_URL: '{{.AIENGINE_URL}}'
+          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
+          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+
+  _run:saas:
+    internal: true
    dotenv: ['app/.env.saas.local', 'app/.env.saas']
    ignore_error: true
    vars:
      PORT: '{{.PORT | default "8080"}}'
-      # Override to "" to run the pure `saas` profile against your own SAAS_DB_*.
      PROFILES: '{{.PROFILES | default "dev"}}'
+      # Built here rather than inline in the cmds below: the Windows line is an
+      # unquoted YAML scalar wrapping a cmd.exe string, so a nested {{if ne .X
+      # "none"}} needs escaped quotes that reach the Go template as literal
+      # backslashes and fail with `unexpected "\" in operand`.
+      PROFILE_ARGS: '{{if ne .PROFILES "none"}}--spring.profiles.include={{.PROFILES}}{{end}}'
      AIENGINE_URL: '{{.AIENGINE_URL | default ""}}'
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
@@ -77,9 +118,11 @@ tasks:
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
    cmds:
-      - cmd: cmd /c ".\gradlew.bat :stirling-pdf:bootRun {{if .PROFILES}}--args=\"--spring.profiles.include={{.PROFILES}}\"{{end}}"
+      # PROFILE_ARGS is empty when PROFILES=none, i.e. the bare `saas` profile
+      # against SAAS_DB_* (production).
+      - cmd: cmd /c ".\gradlew.bat :stirling-pdf:bootRun {{if .PROFILE_ARGS}}--args=\"{{.PROFILE_ARGS}}\"{{end}}"
        platforms: [windows]
-      - cmd: ./gradlew :stirling-pdf:bootRun {{if .PROFILES}}--args='--spring.profiles.include={{.PROFILES}}'{{end}}
+      - cmd: ./gradlew :stirling-pdf:bootRun {{if .PROFILE_ARGS}}--args='{{.PROFILE_ARGS}}'{{end}}
        platforms: [linux, darwin]

  build:
@@ -36,6 +36,11 @@ tasks:
    cmds:
      - docker build -t stirling-pdf-engine .

+  build:ci:
+    desc: "Build the Ubuntu CI image with Task installed"
+    cmds:
+      - docker build --tag stirling-pdf-ci --file docker/ci/Dockerfile .
+
  up:
    desc: "Start standard docker compose stack"
    cmds:
@@ -5,6 +5,14 @@ version: '3'
 # mode flag) or use `--project editor/...` for tsc — so the editor lives
 # under frontend/editor/ without each task needing a cd.

+vars:
+  # Dev-only browser-tab label so concurrent worktrees are distinguishable. Only
+  # the worktree folder basename (e.g. "wt1") is exposed — never the full path,
+  # hostname, or user. Dropped from production builds.
+  DEV_LABEL:
+    sh: >-
+      {{if eq OS "windows"}}powershell -NoProfile -Command '$root = git rev-parse --show-toplevel 2>$null; if (-not $root) { $root = (Get-Location).Path }; Split-Path -Leaf $root'{{else}}basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"{{end}}
+
 tasks:
  install:
    desc: "Install dependencies"
@@ -80,16 +88,52 @@ tasks:
      OPEN: '{{.OPEN | default ""}}'
    env:
      BACKEND_URL: '{{.BACKEND_URL}}'
-      # Dev-only browser-tab label so concurrent worktrees are distinguishable.
-      # Only the worktree folder basename (e.g. "wt1") is exposed — never the
-      # full path, hostname, or user. Consumed at dev-serve time by vite.config
-      # and dropped from production builds.
-      STIRLING_DEV_LABEL:
-        sh: >-
-          {{if eq OS "windows"}}powershell -NoProfile -Command '$root = git rev-parse --show-toplevel 2>$null; if (-not $root) { $root = (Get-Location).Path }; Split-Path -Leaf $root'{{else}}basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"{{end}}
+      STIRLING_DEV_LABEL: '{{.DEV_LABEL}}'
    cmds:
      - npx vite editor --mode {{.MODE}} --port {{.PORT}}{{if .OPEN}} --open{{end}}

+  # Separate from dev:_run rather than a flag on it: Task sets an `env:` key even
+  # when its value resolves to empty, and Vite treats an empty process.env VITE_* as
+  # authoritative over the committed editor/.env, so folding these in blanks Supabase
+  # config for the core, proprietary and desktop dev servers.
+  dev:_run:saas:
+    internal: true
+    ignore_error: true
+    # The backend's own env files, so both halves target one project. Paths are
+    # relative to this taskfile's dir, `frontend`.
+    dotenv: ['../app/.env.saas.local', '../app/.env.saas']
+    vars:
+      PORT: '{{.PORT | default "5173"}}'
+      BACKEND_URL: '{{.BACKEND_URL | default "http://localhost:8080"}}'
+      OPEN: '{{.OPEN | default ""}}'
+      SAAS_ENV: '{{.SAAS_ENV | default "dev"}}'
+    env:
+      BACKEND_URL: '{{.BACKEND_URL}}'
+      STIRLING_DEV_LABEL: '{{.DEV_LABEL}}'
+      SAAS_ENV: '{{.SAAS_ENV}}'
+      # A real process.env VITE_* beats a committed .env in Vite (loadEnv applies
+      # process.env last), which is what lets this override editor/.env.
+      #
+      # These must stay `sh:`, not Go templates: dotenv values are visible to Task's
+      # embedded shell but not to templates, where {{.SAAS_DEV_PROJECT_REF}} is
+      # always empty.
+      VITE_SUPABASE_URL:
+        sh: |
+          case "${SAAS_ENV:-dev}" in
+            staging) ref="${SAAS_STAGING_PROJECT_REF:?set it in app/.env.saas.local}" ;;
+            *)       ref="${SAAS_DEV_PROJECT_REF:?set it in app/.env.saas.local, or run task staging:saas}" ;;
+          esac
+          echo "https://${ref}.supabase.co"
+      VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY:
+        sh: |
+          case "${SAAS_ENV:-dev}" in
+            staging) echo "${SAAS_STAGING_PUBLISHABLE_KEY:?set it in app/.env.saas.local}" ;;
+            *)       echo "${SAAS_DEV_PUBLISHABLE_KEY:?set it in app/.env.saas.local}" ;;
+          esac
+    cmds:
+      - 'echo ">> frontend Supabase target: $VITE_SUPABASE_URL"'
+      - npx vite editor --mode saas --port {{.PORT}}{{if .OPEN}} --open{{end}}
+
  dev:
    desc: "Start frontend dev server"
    cmds:
@@ -111,13 +155,23 @@ tasks:
        vars: { MODE: proprietary, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }

  dev:saas:
-    desc: "Start frontend dev server in SaaS mode"
+    desc: "Start frontend dev server in SaaS mode (SAAS_ENV=dev|staging|prod)"
    deps:
      - task: prepare
        vars: { MODE: saas }
+    vars:
+      SAAS_ENV: '{{.SAAS_ENV | default "dev"}}'
+      # prod routes to the plain runner, which sets no VITE_SUPABASE_* and so leaves
+      # the committed editor/.env alone.
+      RUNNER: '{{if eq .SAAS_ENV "prod"}}dev:_run{{else}}dev:_run:saas{{end}}'
    cmds:
-      - task: dev:_run
-        vars: { MODE: saas, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+      - task: '{{.RUNNER}}'
+        vars:
+          MODE: saas
+          PORT: '{{.PORT}}'
+          BACKEND_URL: '{{.BACKEND_URL}}'
+          OPEN: '{{.OPEN}}'
+          SAAS_ENV: '{{.SAAS_ENV}}'

  dev:desktop:
    desc: "Start frontend dev server in desktop mode"
@@ -321,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"
@@ -500,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
@@ -509,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"
@@ -46,8 +46,8 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
 - Docker
 - Git
 - Java JDK 25
- Node.js 18+ and npm (required for frontend development)
- Gradle 7.0 or later (Included within the repo)
+- Node.js 22+ and npm (required for frontend development)
+- Gradle 9.0 or later (Included within the repo)
 - [uv](https://docs.astral.sh/uv/) — Python package manager (required for engine development)
 - Rust and Cargo (required for Tauri desktop app development)
 - Tauri CLI (install with `cargo install tauri-cli`)
@@ -99,11 +99,22 @@ tasks:
          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
          OPEN: "true"

+  # Set SAAS_DEV_PROJECT_REF in app/.env.saas.local to pick the PR.
  dev:saas:
-    desc: "Start SaaS backend + frontend concurrently on free ports"
+    desc: "Start SaaS backend + frontend + engine against the current PR's preview branch"
    cmds:
      - task: dev:_all
-        vars: { FRONTEND: saas, BACKEND: saas }
+        vars: { FRONTEND: saas, BACKEND: saas, SAAS_ENV: dev }
+
+  staging:saas:
+    desc: "Start SaaS backend + frontend + engine against the shared v3 staging project"
+    cmds:
+      - task: dev:_all
+        vars:
+          FRONTEND: saas
+          BACKEND: saas
+          BACKEND_TASK: backend:staging:saas
+          SAAS_ENV: staging

  dev:all:
    desc: "Start backend + frontend + engine concurrently on free ports"
@@ -115,6 +126,9 @@ tasks:
    vars:
      FRONTEND: '{{.FRONTEND | default "proprietary"}}'
      BACKEND: '{{.BACKEND | default "proprietary"}}'
+      BACKEND_TASK: '{{.BACKEND_TASK | default (printf "backend:dev:%s" .BACKEND)}}'
+      # Only meaningful to the saas frontend; every other flavor ignores it.
+      SAAS_ENV: '{{.SAAS_ENV | default ""}}'
      PORTS:
        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173 5001{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173 5001{{end}}'
      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
@@ -124,7 +138,7 @@ tasks:
      - task: engine:dev
        vars:
          PORT: '{{.ENGINE_PORT}}'
-      - task: 'backend:dev:{{.BACKEND}}'
+      - task: '{{.BACKEND_TASK}}'
        vars:
          PORT: '{{.BACKEND_PORT}}'
          AIENGINE_URL: 'http://localhost:{{.ENGINE_PORT}}'
@@ -134,6 +148,7 @@ tasks:
          PORT: '{{.FRONTEND_PORT}}'
          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
          OPEN: "true"
+          SAAS_ENV: '{{.SAAS_ENV}}'

  # ============================================================
  # Build
@@ -1,15 +1,16 @@
-###############################################################################
-# Stirling-PDF SaaS environment defaults.
+# Stirling-PDF SaaS environment defaults. Committed, non-secret. Real values for secrets go in
+# .env.saas.local, which is loaded first and wins. Do not commit that file.
 #
-# This file is committed and provides non-secret defaults loaded by
-# `task backend:dev:saas`. Put real values for secrets (passwords, project
-# refs, edge function secrets) in `.env.saas.local` - any variable set there
-# takes precedence over what's defined here.
+# Three environments, each deriving its Supabase URLs, JWT issuer and JWKS from one project ref:
 #
-# DO NOT commit `.env.saas.local`. Only `.env.saas` is checked in.
-###############################################################################
+#   prod     PROFILES=none       SAAS_DB_*          the live project
+#   staging  PROFILES=staging    SAAS_STAGING_*     pinned to v3, always there
+#   dev      PROFILES=dev        SAAS_DEV_*         follows a SaaS PR's preview branch
+#
+# dev is the default for `task backend:dev:saas`. Use staging for somewhere stable; use dev when
+# testing an open SaaS PR, since its preview branch is the only place those migrations are applied.

-# ---------- Supabase project ----------
+# ---------- Supabase project (prod / no-profile) ----------
 # Project reference (the subdomain part of <ref>.supabase.co). Required.
 # Set in .env.saas.local.
 SAAS_DB_PROJECT_REF=
@@ -17,18 +18,35 @@ SAAS_DB_PROJECT_REF=
 # Edge function secret used by billing/license rollup calls. Set in .env.saas.local.
 SUPABASE_EDGE_FUNCTION_SECRET=

-# ---------- Database (saas profile) ----------
-# Direct JDBC URL to the Supabase Postgres. Required when running the plain
-# `saas` profile (i.e. without `--spring.profiles.include=dev`).
+# ---------- Database (no profile) ----------
+# Direct JDBC URL to the Supabase Postgres. Required when running without
+# `--spring.profiles.include=...`.
 # Example: jdbc:postgresql://db.<project-ref>.supabase.co:5432/postgres
 SAAS_DB_URL=
 SAAS_DB_USERNAME=postgres
 SAAS_DB_PASSWORD=

-# ---------- Database (dev profile overrides) ----------
-# Used when `--spring.profiles.include=dev` is active. The dev profile
-# defaults the URL/username to the shared dev Supabase project, but the
-# password must still be provided in .env.saas.local.
-SAAS_DEV_DB_URL=
+# ---------- staging profile ----------
+# The shared long-lived v3 project. application-staging.properties defaults the ref,
+# URL, database host and meter endpoint, so staging needs only the password, in
+# .env.saas.local. Set SAAS_STAGING_PROJECT_REF to repoint it; everything derives.
+#
+# The ref and publishable key are duplicated here because the task derives the
+# frontend's VITE_SUPABASE_* from them and a shell cannot read a Spring default.
+# Neither is secret: the ref is a public subdomain, the key ships in the bundle.
+SAAS_STAGING_PROJECT_REF=qacaivhsjtftfwtgjvva
+SAAS_STAGING_PUBLISHABLE_KEY=sb_publishable_nIM8y-9ARPE7EzQwAQHKMg_40fCN6kY # gitleaks:allow
+SAAS_STAGING_DB_USERNAME=postgres
+SAAS_STAGING_DB_PASSWORD=
+
+# ---------- dev profile ----------
+# The SaaS PR's Supabase preview branch. Take the ref from that PR's "Supabase
+# Preview" check; the profile derives URL, JWT issuer, JWKS, meter endpoint and
+# database host from it, so this one value follows a different PR.
+#
+# A preview branch has its own password and keys; the parent project's will not
+# authenticate. Both go in .env.saas.local, along with the ref.
+SAAS_DEV_PROJECT_REF=
+SAAS_DEV_PUBLISHABLE_KEY=
 SAAS_DEV_DB_USERNAME=postgres
 SAAS_DEV_DB_PASSWORD=
@@ -18,11 +18,11 @@ 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.2.0'
-    api 'org.simplejavamail:outlook-module:9.2.0' // MSG file support
+    api 'org.simplejavamail:simple-java-mail:9.3.2'
+    api 'org.simplejavamail:outlook-module:9.3.2' // MSG file support
    api 'jakarta.mail:jakarta.mail-api:2.1.5'
    runtimeOnly 'org.eclipse.angus:angus-mail:2.0.5'

@@ -6,6 +6,7 @@ import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;

+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;

@@ -13,6 +14,7 @@ import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.PdfaLevelAServiceInterface;

@Service
@Slf4j
@@ -51,12 +53,16 @@ public class EndpointConfiguration {
    private Map<String, DisableReason> groupDisableReasons = new ConcurrentHashMap<>();
    private Map<String, Set<String>> endpointAlternatives = new ConcurrentHashMap<>();
    private final boolean runningProOrHigher;
+    private final boolean pdfUaAvailable;

    public EndpointConfiguration(
            ApplicationProperties applicationProperties,
-            @Qualifier("runningProOrHigher") boolean runningProOrHigher) {
+            @Qualifier("runningProOrHigher") boolean runningProOrHigher,
+            @Autowired(required = false) PdfaLevelAServiceInterface pdfaLevelAService) {
        this.applicationProperties = applicationProperties;
        this.runningProOrHigher = runningProOrHigher;
+        // The PDF/UA tagger ships in the proprietary module, and so do its endpoints.
+        this.pdfUaAvailable = pdfaLevelAService != null;
        init();
        processEnvironmentConfigs();
    }
@@ -356,6 +362,7 @@ public class EndpointConfiguration {
        addEndpointToGroup("Convert", "pdf-to-img");
        addEndpointToGroup("Convert", "img-to-pdf");
        addEndpointToGroup("Convert", "pdf-to-pdfa");
+        addEndpointToGroup("Convert", "pdf-to-ua");
        addEndpointToGroup("Convert", "file-to-pdf");
        addEndpointToGroup("Convert", "pdf-to-word");
        addEndpointToGroup("Convert", "pdf-to-presentation");
@@ -395,6 +402,7 @@ public class EndpointConfiguration {
        // Backend-only endpoints (not in frontend tool registry endpoints)
        addEndpointToGroup("Security", "redact");
        addEndpointToGroup("Security", "verify-pdf");
+        addEndpointToGroup("Security", "accessibility-report");
        addEndpointToGroup("Security", "sign");

        // Adding endpoints to "Other" group
@@ -529,6 +537,8 @@ public class EndpointConfiguration {
        addEndpointToGroup("Java", "json-to-pdf");
        addEndpointToGroup("Java", "pdf-to-video");
        addEndpointToGroup("Java", "verify-pdf");
+        addEndpointToGroup("Java", "pdf-to-ua");
+        addEndpointToGroup("Java", "accessibility-report");
        addEndpointToGroup("Java", "flatten");
        addEndpointToGroup("Java", "unlock-pdf-forms");
        addEndpointToGroup("Java", "validate-signature");
@@ -600,6 +610,8 @@ public class EndpointConfiguration {

        // veraPDF dependent endpoints
        addEndpointToGroup("veraPDF", "verify-pdf");
+        addEndpointToGroup("veraPDF", "pdf-to-ua");
+        addEndpointToGroup("veraPDF", "accessibility-report");

        // Pdftohtml dependent endpoints
        addEndpointToGroup("Pdftohtml", "pdf-to-html");
@@ -630,6 +642,11 @@ public class EndpointConfiguration {
            disableGroup("enterprise");
        }

+        if (!pdfUaAvailable) {
+            disableEndpoint("pdf-to-ua");
+            disableEndpoint("accessibility-report");
+        }
+
        if (!applicationProperties.getSystem().isEnableUrlToPDF()) {
            disableEndpoint("url-to-pdf");
        }
@@ -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;
    }
 }
@@ -0,0 +1,22 @@
+package stirling.software.common.service;
+
+import java.util.List;
+
+/**
+ * Raises a converted PDF/A file from conformance level B to level A, which needs the tagging the
+ * PDF/UA tagger does. Implemented only in the proprietary module; core builds convert at level B.
+ */
+public interface PdfaLevelAServiceInterface {
+
+    /**
+     * @param levelA true only when the file was tagged and validated, so the claim is never a guess
+     */
+    record Result(byte[] pdfBytes, boolean levelA, List<String> warnings) {}
+
+    /**
+     * @param part PDF/A part, 1 to 3; part 1 keeps its PDF 1.4 version
+     * @param alsoDeclareUa additionally claim PDF/UA, but only if it validates
+     */
+    Result upgradeToLevelA(
+            byte[] pdfBytes, int part, String language, String title, boolean alsoDeclareUa);
+}
@@ -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(
@@ -4,7 +4,14 @@ import java.util.regex.Pattern;

 public class RequestUriUtils {

-    private static final Pattern SHARE_LINK_PATTERN = Pattern.compile("^/share/[^/]+/?$");
+    // Share tokens are 36-char lowercase UUIDs (UUID.randomUUID().toString()); match exactly
+    private static final Pattern SHARE_LINK_PATTERN =
+            Pattern.compile(
+                    "^/share/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/?$");
+    // Invite tokens are 36-char lowercase UUIDs (UUID.randomUUID().toString()); match exactly
+    private static final Pattern INVITE_LINK_PATTERN =
+            Pattern.compile(
+                    "^/invite/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/?$");

    public static boolean isStaticResource(String requestURI) {
        return isStaticResource("", requestURI);
@@ -69,7 +76,7 @@ public class RequestUriUtils {
        // cookie, so the server can't authenticate the navigation itself). The
        // portal gates access via its own auth gate + RequirePortalAccess, and its
        // data APIs stay protected, so serving the shell pre-auth is safe.
-        if (normalizedUri.equals("/processor") || normalizedUri.startsWith("/processor/")) {
+        if ("/processor".equals(normalizedUri) || normalizedUri.startsWith("/processor/")) {
            return true;
        }

@@ -209,7 +216,9 @@ public class RequestUriUtils {
                // Workflow participant endpoints - access controlled by share tokens, not login
                || trimmedUri.startsWith("/api/v1/workflow/participant/")
                // Share-link SPA bootstrap; data APIs remain protected
-                || SHARE_LINK_PATTERN.matcher(trimmedUri).matches();
+                || SHARE_LINK_PATTERN.matcher(trimmedUri).matches()
+                // Invite-accept SPA bootstrap; data APIs remain protected
+                || INVITE_LINK_PATTERN.matcher(trimmedUri).matches();
    }

    private static String stripContextPath(String contextPath, String requestURI) {
@@ -17,6 +17,7 @@ import org.junit.jupiter.api.Test;
 import stirling.software.SPDF.config.EndpointConfiguration.DisableReason;
 import stirling.software.SPDF.config.EndpointConfiguration.EndpointAvailability;
 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.PdfaLevelAServiceInterface;

 /**
 * Unit tests for {@link EndpointConfiguration}. The class wires up its endpoint/group registry in
@@ -32,7 +33,14 @@ class EndpointConfigurationGapTest {
     * Construct an EndpointConfiguration with the given pro flag and current applicationProperties.
     */
    private EndpointConfiguration build(boolean runningProOrHigher) {
-        return new EndpointConfiguration(applicationProperties, runningProOrHigher);
+        return build(runningProOrHigher, null);
+    }
+
+    /** The PDF/UA service is only present in proprietary builds, so it is injected separately. */
+    private EndpointConfiguration build(
+            boolean runningProOrHigher, PdfaLevelAServiceInterface pdfaLevelAService) {
+        return new EndpointConfiguration(
+                applicationProperties, runningProOrHigher, pdfaLevelAService);
    }

    /** Default config: not pro, no removals, url-to-pdf disabled (default System flag is false). */
@@ -177,6 +185,28 @@ class EndpointConfigurationGapTest {
        }
    }

+    @Nested
+    @DisplayName("PDF/UA availability")
+    class PdfUaTests {
+
+        @Test
+        @DisplayName("the PDF/UA endpoints are off when the proprietary tagger is absent")
+        void disabledWithoutTagger() {
+            EndpointConfiguration config = build(false, null);
+            assertFalse(config.isEndpointEnabled("pdf-to-ua"));
+            assertFalse(config.isEndpointEnabled("accessibility-report"));
+        }
+
+        @Test
+        @DisplayName("they are on once the tagger is on the classpath")
+        void enabledWithTagger() {
+            EndpointConfiguration config =
+                    build(false, (pdfBytes, part, language, title, alsoDeclareUa) -> null);
+            assertTrue(config.isEndpointEnabled("pdf-to-ua"));
+            assertTrue(config.isEndpointEnabled("accessibility-report"));
+        }
+    }
+
    @Nested
    @DisplayName("group enable / disable")
    class GroupTests {
@@ -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");
+        }
+    }
+}
@@ -206,12 +206,24 @@ class RequestUriUtilsTest {

    @Test
    void testIsPublicAuthEndpoint_shareLinkTokenTrailingSlash() {
-        assertTrue(RequestUriUtils.isPublicAuthEndpoint("/share/abc123/", ""));
+        assertTrue(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/share/00dcac3a-fc7a-4989-9c4f-97745484d62f/", ""));
    }

    @Test
    void testIsPublicAuthEndpoint_shareLinkWithContextPath() {
-        assertTrue(RequestUriUtils.isPublicAuthEndpoint("/app/share/abc123", "/app"));
+        assertTrue(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/app/share/00dcac3a-fc7a-4989-9c4f-97745484d62f", "/app"));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_shareLinkWithInvalidTokenLength() {
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/share/abc123", ""));
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/share/00dcac3a-fc7a-4989-9c4f-97745484d62fa", ""));
    }

    @Test
@@ -236,4 +248,86 @@ class RequestUriUtilsTest {
                RequestUriUtils.isPublicAuthEndpoint(
                        "/api/v1/storage/share-links/abc123/metadata", ""));
    }
+
+    // --- invite-accept SPA bootstrap ---
+
+    private static final String INVITE_TOKEN = "06a20e7e-2e35-4e26-be7d-2dce14f28f12";
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteLinkToken() {
+        assertTrue(RequestUriUtils.isPublicAuthEndpoint("/invite/" + INVITE_TOKEN, ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteLinkTokenTrailingSlash() {
+        assertTrue(RequestUriUtils.isPublicAuthEndpoint("/invite/" + INVITE_TOKEN + "/", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteLinkWithContextPath() {
+        assertTrue(RequestUriUtils.isPublicAuthEndpoint("/app/invite/" + INVITE_TOKEN, "/app"));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteRootNotPublic() {
+        // Avoid matching bare "/invite" or "/invite/" - must have a token segment
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite", ""));
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteNestedPathNotPublic() {
+        // Guard against future additions like /invite/<token>/foo becoming accidentally public
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/" + INVITE_TOKEN + "/foo", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_invitePrefixDoesNotOvermatch() {
+        // "/inviteX" must not match the invite pattern
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/inviteX", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteNonUuidTokenNotPublic() {
+        // Only exactly-shaped 36-char lowercase UUID tokens are treated as invite links
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/abc123", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteUppercaseUuidNotPublic() {
+        // Tokens are generated lowercase by UUID.randomUUID().toString()
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/invite/06A20E7E-2E35-4E26-BE7D-2DCE14F28F12", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteWrongLengthNotPublic() {
+        // 35-char and 37-char UUID-like tokens are not valid UUIDs
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/invite/06a20e7e-2e35-4e26-be7d-2dce14f28f1", ""));
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/invite/06a20e7e-2e35-4e26-be7d-2dce14f28f122", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteWrongGroupingNotPublic() {
+        // Groups of 8-4-4-4-4 must not be shifted around (e.g. 4-4-4-4-8)
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/invite/06a2-0e7e-2e35-4e26-be7d2dce14f28f12", ""));
+    }
+
+    @Test
+    void testIsPublicAuthEndpoint_inviteTokenInvalidCharsNotPublic() {
+        // Hex-only; anything outside [0-9a-f] or the UUID hyphens is rejected
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/abc$123", ""));
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/abc..123", ""));
+        assertFalse(RequestUriUtils.isPublicAuthEndpoint("/invite/abc%2F123", ""));
+        assertFalse(
+                RequestUriUtils.isPublicAuthEndpoint(
+                        "/invite/06a20e7e-2e35-4e26-be7d-2dce14f28f1g", ""));
+    }
 }
@@ -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);
        }
@@ -11,6 +11,7 @@ import java.time.Instant;
 import java.time.ZoneId;
 import java.time.ZonedDateTime;
 import java.util.*;
+import java.util.Locale;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
@@ -71,6 +72,7 @@ import org.apache.xmpbox.schema.PDFAIdentificationSchema;
 import org.apache.xmpbox.schema.XMPBasicSchema;
 import org.apache.xmpbox.xml.DomXmpParser;
 import org.apache.xmpbox.xml.XmpSerializer;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.io.Resource;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
@@ -83,7 +85,6 @@ import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;

 import lombok.Getter;
-import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.SPDF.model.api.converters.PdfToPdfARequest;
@@ -93,6 +94,7 @@ import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.enumeration.ResourceWeight;
 import stirling.software.common.model.tool.ToolFormat;
 import stirling.software.common.model.tool.ToolIO;
+import stirling.software.common.service.PdfaLevelAServiceInterface;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
@@ -102,14 +104,26 @@ import stirling.software.common.util.WebResponseUtils;

@ConvertApi
@Slf4j
-@RequiredArgsConstructor
 public class ConvertPDFToPDFA {

    private static final Pattern NON_PRINTABLE_ASCII = Pattern.compile("[^\\x20-\\x7E]");
    private final RuntimePathConfig runtimePathConfig;
    private final stirling.software.SPDF.service.VeraPDFService veraPDFService;
+    // Level A needs the proprietary tagger; core builds convert at level B instead.
+    private final PdfaLevelAServiceInterface pdfaLevelAService;
    private final TempFileManager tempFileManager;

+    public ConvertPDFToPDFA(
+            RuntimePathConfig runtimePathConfig,
+            stirling.software.SPDF.service.VeraPDFService veraPDFService,
+            @Autowired(required = false) PdfaLevelAServiceInterface pdfaLevelAService,
+            TempFileManager tempFileManager) {
+        this.runtimePathConfig = runtimePathConfig;
+        this.veraPDFService = veraPDFService;
+        this.pdfaLevelAService = pdfaLevelAService;
+        this.tempFileManager = tempFileManager;
+    }
+
    private static final String ICC_RESOURCE_PATH = "/icc/sRGB2014.icc";
    private static final int PDFA_COMPATIBILITY_POLICY = 1;

@@ -604,7 +618,10 @@ public class ConvertPDFToPDFA {
            return handlePdfXConversion(inputFile, outputFormat);
        } else {
            return handlePdfAConversion(
-                    inputFile, outputFormat, request.getStrict() != null && request.getStrict());
+                    inputFile,
+                    outputFormat,
+                    request.getStrict() != null && request.getStrict(),
+                    request.getPdfUa() != null && request.getPdfUa());
        }
    }

@@ -1815,8 +1832,64 @@ public class ConvertPDFToPDFA {
        return Files.readAllBytes(outputPdf);
    }

+    /** Tags a converted PDF/A for level A; must run after Ghostscript, which discards tags. */
+    private PdfaLevelAServiceInterface.Result applyLevelA(
+            byte[] converted,
+            Path original,
+            PdfaProfile profile,
+            String baseFileName,
+            boolean declarePdfUa) {
+        if (!profile.requiresTagging()) {
+            return new PdfaLevelAServiceInterface.Result(converted, true, List.of());
+        }
+        if (pdfaLevelAService == null) {
+            return new PdfaLevelAServiceInterface.Result(
+                    converted,
+                    false,
+                    List.of(
+                            "Level A tagging is not available in this build, so the file was left"
+                                    + " at conformance level B."));
+        }
+        // Prefer the document's own title/language; hardcoding "en" mislabelled German reports.
+        // Read the original, not the converted bytes: Ghostscript discards /Lang, so probing its
+        // output always yields null and every document would be relabelled with the default.
+        String language = null;
+        String title = null;
+        try (PDDocument probe = Loader.loadPDF(original.toFile())) {
+            language = probe.getDocumentCatalog().getLanguage();
+            title = probe.getDocumentInformation().getTitle();
+        } catch (IOException e) {
+            log.debug("Could not read original title/language: {}", e.getMessage());
+        }
+        if (language == null || language.isBlank()) {
+            try (PDDocument probe = Loader.loadPDF(converted)) {
+                language = probe.getDocumentCatalog().getLanguage();
+                if (title == null || title.isBlank()) {
+                    title = probe.getDocumentInformation().getTitle();
+                }
+            } catch (IOException e) {
+                log.debug("Could not read converted title/language: {}", e.getMessage());
+            }
+        }
+        PdfaLevelAServiceInterface.Result result =
+                pdfaLevelAService.upgradeToLevelA(
+                        converted,
+                        profile.getPart(),
+                        language,
+                        title != null && !title.isBlank() ? title : baseFileName,
+                        declarePdfUa);
+        result.warnings().forEach(warning -> log.info("PDF/A level A: {}", warning));
+        if (!result.levelA()) {
+            log.warn(
+                    "{} requested but the document could not be tagged; returning level B",
+                    profile.getDisplayName());
+        }
+        return result;
+    }
+
    private ResponseEntity<Resource> handlePdfAConversion(
-            MultipartFile inputFile, String outputFormat, boolean strict) throws Exception {
+            MultipartFile inputFile, String outputFormat, boolean strict, boolean declarePdfUa)
+            throws Exception {
        PdfaProfile profile = PdfaProfile.fromRequest(outputFormat);

        // Get the original filename without extension
@@ -1841,12 +1914,15 @@ public class ConvertPDFToPDFA {
                log.info("Using Ghostscript for PDF/A conversion to {}", profile.getDisplayName());
                try {
                    converted = convertWithGhostscript(inputPath, workingDir, profile);
-                    String outputFilename = baseFileName + profile.outputSuffix();
+                    var levelA =
+                            applyLevelA(converted, inputPath, profile, baseFileName, declarePdfUa);
+                    converted = levelA.pdfBytes();
+                    String outputFilename = baseFileName + profile.outputSuffix(levelA.levelA());

                    validateAndWarnPdfA(converted, profile, "Ghostscript");

                    if (strict) {
-                        verifyStrictCompliance(converted);
+                        verifyStrictCompliance(converted, profile, levelA.levelA());
                    }

                    TempFile tempOut = tempFileManager.createManagedTempFile(".pdf");
@@ -1867,13 +1943,15 @@ public class ConvertPDFToPDFA {
            }

            converted = convertWithPdfBoxMethod(inputPath, profile);
-            String outputFilename = baseFileName + profile.outputSuffix();
+            var levelA = applyLevelA(converted, inputPath, profile, baseFileName, declarePdfUa);
+            converted = levelA.pdfBytes();
+            String outputFilename = baseFileName + profile.outputSuffix(levelA.levelA());

            // Validate with PDFBox preflight and warn if issues found
            validateAndWarnPdfA(converted, profile, "PDFBox/LibreOffice");

            if (strict) {
-                verifyStrictCompliance(converted);
+                verifyStrictCompliance(converted, profile, levelA.levelA());
            }

            TempFile tempOut = tempFileManager.createManagedTempFile(".pdf");
@@ -1889,11 +1967,56 @@ public class ConvertPDFToPDFA {
        }
    }

-    private void verifyStrictCompliance(byte[] pdfBytes) throws IOException {
+    /** True for a PDF/UA or WCAG result, which says nothing about archival conformance. */
+    private static boolean isAccessibilityProfile(
+            stirling.software.SPDF.model.api.security.PDFVerificationResult result) {
+        String profile = result.getValidationProfile();
+        if (profile == null) {
+            return false;
+        }
+        String normalised = profile.toLowerCase(Locale.ROOT);
+        return normalised.contains("ua") || normalised.contains("wcag");
+    }
+
+    /**
+     * True when a result speaks for the requested profile. Only archival results count, and a level
+     * B pass must never satisfy a level A request.
+     */
+    private static boolean answersRequest(
+            PdfaProfile profile,
+            stirling.software.SPDF.model.api.security.PDFVerificationResult result) {
+        if (isAccessibilityProfile(result)) {
+            return false;
+        }
+        String standard = result.getStandard();
+        if (standard == null || standard.length() < 2) {
+            return false;
+        }
+        if (standard.charAt(0) != Character.forDigit(profile.getPart(), 10)) {
+            return false;
+        }
+        return !profile.requiresTagging() || Character.toLowerCase(standard.charAt(1)) == 'a';
+    }
+
+    private void verifyStrictCompliance(byte[] pdfBytes, PdfaProfile profile, boolean levelAReached)
+            throws IOException {
+        // Tagging is the only route to level A, so an untagged file cannot answer a strict request.
+        if (!levelAReached) {
+            throw new ResponseStatusException(
+                    HttpStatus.BAD_REQUEST,
+                    "Strict PDF/A mode enabled: the document could not be tagged, so "
+                            + profile.getDisplayName()
+                            + " was not reached. It is valid at level B.");
+        }
        try (InputStream is = new ByteArrayInputStream(pdfBytes)) {
            List<stirling.software.SPDF.model.api.security.PDFVerificationResult> results =
                    veraPDFService.validatePDF(is);
-            boolean isCompliant = results.stream().anyMatch(result -> result.isCompliant());
+            boolean isCompliant =
+                    results.stream()
+                            .filter(result -> answersRequest(profile, result))
+                            .anyMatch(
+                                    stirling.software.SPDF.model.api.security.PDFVerificationResult
+                                            ::isCompliant);
            if (!isCompliant) {
                String details =
                        results.stream()
@@ -1901,7 +2024,9 @@ public class ConvertPDFToPDFA {
                                .collect(Collectors.joining("; "));
                throw new ResponseStatusException(
                        HttpStatus.BAD_REQUEST,
-                        "Strict PDF/A mode enabled: Conversion is not perfectly compliant. Details: "
+                        "Strict PDF/A mode enabled: the output is not perfectly compliant with "
+                                + profile.getDisplayName()
+                                + ". Details: "
                                + details);
            }
        } catch (Exception e) {
@@ -2466,11 +2591,16 @@ public class ConvertPDFToPDFA {

    @Getter
    private enum PdfaProfile {
-        PDF_A_1B(1, "PDF/A-1b", "_PDFA-1b.pdf", "1.4", Format.PDF_A1B, "pdfa-1"),
-        PDF_A_2B(2, "PDF/A-2b", "_PDFA-2b.pdf", "1.7", null, "pdfa", "pdfa-2", "pdfa-2b"),
-        PDF_A_3B(3, "PDF/A-3b", "_PDFA-3b.pdf", "1.7", null, "pdfa-3", "pdfa-3b");
+        PDF_A_1B(1, "B", "PDF/A-1b", "_PDFA-1b.pdf", "1.4", Format.PDF_A1B, "pdfa-1"),
+        PDF_A_2B(2, "B", "PDF/A-2b", "_PDFA-2b.pdf", "1.7", null, "pdfa", "pdfa-2", "pdfa-2b"),
+        PDF_A_3B(3, "B", "PDF/A-3b", "_PDFA-3b.pdf", "1.7", null, "pdfa-3", "pdfa-3b"),
+        // Level A = level B plus tagging, declared language and Unicode text; tagged post-convert.
+        PDF_A_1A(1, "A", "PDF/A-1a", "_PDFA-1a.pdf", "1.4", Format.PDF_A1B, "pdfa-1a"),
+        PDF_A_2A(2, "A", "PDF/A-2a", "_PDFA-2a.pdf", "1.7", null, "pdfa-2a"),
+        PDF_A_3A(3, "A", "PDF/A-3a", "_PDFA-3a.pdf", "1.7", null, "pdfa-3a");

        private final int part;
+        private final String conformanceLevel;
        private final String displayName;
        private final String suffix;
        private final String compatibilityLevel;
@@ -2479,12 +2609,14 @@ public class ConvertPDFToPDFA {

        PdfaProfile(
                int part,
+                String conformanceLevel,
                String displayName,
                String suffix,
                String compatibilityLevel,
                Format preflightFormat,
                String... requestTokens) {
            this.part = part;
+            this.conformanceLevel = conformanceLevel;
            this.displayName = displayName;
            this.suffix = suffix;
            this.compatibilityLevel = compatibilityLevel;
@@ -2495,6 +2627,10 @@ public class ConvertPDFToPDFA {
                            .toList();
        }

+        boolean requiresTagging() {
+            return "A".equals(conformanceLevel);
+        }
+
        static PdfaProfile fromRequest(String requestToken) {
            if (requestToken == null) {
                return PDF_A_2B;
@@ -2508,8 +2644,11 @@ public class ConvertPDFToPDFA {
            return match.orElse(PDF_A_2B);
        }

-        String outputSuffix() {
-            return suffix;
+        /**
+         * Names the file at the level actually reached; a level A name over level B content lies.
+         */
+        String outputSuffix(boolean levelAReached) {
+            return levelAReached ? suffix : "_PDFA-" + part + "b.pdf";
        }

        Optional<Format> preflightFormat() {
@@ -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();
@@ -14,9 +14,19 @@ public class PdfToPdfARequest extends PDFFile {
    @Schema(
            description = "The output format type (PDF/A or PDF/X)",
            requiredMode = Schema.RequiredMode.REQUIRED,
-            allowableValues = {"pdfa", "pdfa-1", "pdfa-2", "pdfa-2b", "pdfa-3", "pdfa-3b", "pdfx"})
+            allowableValues = {
+                "pdfa", "pdfa-1", "pdfa-2", "pdfa-2b", "pdfa-3", "pdfa-3b", "pdfa-1a", "pdfa-2a",
+                "pdfa-3a", "pdfx"
+            })
    private String outputFormat;

+    @Schema(
+            description =
+                    "Also declare PDF/UA accessibility alongside PDF/A. Only applies to the level A"
+                            + " formats, and the claim is written only if it validates.",
+            defaultValue = "false")
+    private Boolean pdfUa;
+
    @Schema(
            description =
                    "If true, the conversion will fail if the output is not perfectly compliant")
@@ -285,6 +285,8 @@ public class VeraPDFService {
            }
        }

+        // Never force PDF/UA here - it flags every ordinary document as non-compliant and doubles
+        // verify cost; /accessibility-report checks PDF/UA on demand.
        if (!hasPdfaDeclaration) {
            results.add(createNoPdfaDeclarationResult());
        }
@@ -14,6 +14,13 @@
            "moduleLicense": "GNU Lesser General Public License",
            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
        },
+        {
+            "moduleName": "ch.qos.logback:logback-classic",
+            "moduleUrl": "http://www.qos.ch",
+            "moduleVersion": "1.6.1",
+            "moduleLicense": "LGPL-2.1-only",
+            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
+        },
        {
            "moduleName": "ch.qos.logback:logback-core",
            "moduleUrl": "http://www.qos.ch",
@@ -21,6 +28,13 @@
            "moduleLicense": "GNU Lesser General Public License",
            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
        },
+        {
+            "moduleName": "ch.qos.logback:logback-core",
+            "moduleUrl": "http://www.qos.ch",
+            "moduleVersion": "1.6.1",
+            "moduleLicense": "LGPL-2.1-only",
+            "moduleLicenseUrl": "https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"
+        },
        {
            "moduleName": "com.adobe.xmp:xmpcore",
            "moduleUrl": "https://www.adobe.com/devnet/xmp/library/eula-xmp-library-java.html",
@@ -182,7 +196,7 @@
        {
            "moduleName": "com.github.mwiede:jsch",
            "moduleUrl": "https://github.com/mwiede/jsch",
-            "moduleVersion": "0.2.23",
+            "moduleVersion": "2.28.6",
            "moduleLicense": "Revised BSD",
            "moduleLicenseUrl": "https://github.com/mwiede/jsch/blob/master/LICENSE.txt"
        },
@@ -513,27 +527,45 @@
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.common:common-image",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.common:common-io",
            "moduleVersion": "3.13.1",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.common:common-io",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.common:common-lang",
            "moduleVersion": "3.13.1",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.common:common-lang",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.imageio:imageio-batik",
-            "moduleVersion": "3.13.1",
+            "moduleVersion": "3.14.0",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
        {
            "moduleName": "com.twelvemonkeys.imageio:imageio-bmp",
-            "moduleVersion": "3.13.1",
+            "moduleVersion": "3.14.0",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
@@ -543,9 +575,15 @@
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.imageio:imageio-core",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.imageio:imageio-jpeg",
-            "moduleVersion": "3.13.1",
+            "moduleVersion": "3.14.0",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
@@ -555,9 +593,15 @@
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.imageio:imageio-metadata",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.imageio:imageio-psd",
-            "moduleVersion": "3.13.1",
+            "moduleVersion": "3.14.0",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
@@ -567,12 +611,24 @@
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.imageio:imageio-tiff",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.twelvemonkeys.imageio:imageio-webp",
            "moduleVersion": "3.13.1",
            "moduleLicense": "The BSD License",
            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
        },
+        {
+            "moduleName": "com.twelvemonkeys.imageio:imageio-webp",
+            "moduleVersion": "3.14.0",
+            "moduleLicense": "The BSD License",
+            "moduleLicenseUrl": "https://github.com/haraldk/TwelveMonkeys#license"
+        },
        {
            "moduleName": "com.vladsch.flexmark:flexmark",
            "moduleVersion": "0.64.8",
@@ -758,7 +814,7 @@
        {
            "moduleName": "commons-net:commons-net",
            "moduleUrl": "https://commons.apache.org/proper/commons-net/",
-            "moduleVersion": "3.11.1",
+            "moduleVersion": "3.13.0",
            "moduleLicense": "Apache-2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
@@ -1213,24 +1269,48 @@
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "net.shibboleth:shib-networking",
+            "moduleVersion": "9.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "net.shibboleth:shib-security",
            "moduleVersion": "9.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "net.shibboleth:shib-security",
+            "moduleVersion": "9.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "net.shibboleth:shib-support",
            "moduleVersion": "9.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "net.shibboleth:shib-support",
+            "moduleVersion": "9.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "net.shibboleth:shib-velocity",
            "moduleVersion": "9.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "net.shibboleth:shib-velocity",
+            "moduleVersion": "9.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.antlr:antlr4-runtime",
            "moduleUrl": "https://www.antlr.org/",
@@ -1325,13 +1405,6 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
-        {
-            "moduleName": "org.apache.httpcomponents:httpclient",
-            "moduleUrl": "http://hc.apache.org/httpcomponents-client",
-            "moduleVersion": "4.5.13",
-            "moduleLicense": "Apache License, Version 2.0",
-            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
-        },
        {
            "moduleName": "org.apache.httpcomponents:httpclient",
            "moduleUrl": "http://hc.apache.org/httpcomponents-client-ga",
@@ -1456,6 +1529,13 @@
            "moduleLicense": "Apache-2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.apache.santuario:xmlsec",
+            "moduleUrl": "https://www.apache.org/",
+            "moduleVersion": "3.0.6",
+            "moduleLicense": "Apache-2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.apache.tomcat.embed:tomcat-embed-el",
            "moduleUrl": "https://tomcat.apache.org/",
@@ -1470,6 +1550,13 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.apache.velocity:velocity-engine-core",
+            "moduleUrl": "https://www.apache.org/",
+            "moduleVersion": "2.4.1",
+            "moduleLicense": "Apache-2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.apache.xmlbeans:xmlbeans",
            "moduleUrl": "https://xmlbeans.apache.org/",
@@ -1647,6 +1734,13 @@
            "moduleLicense": "GNU Lesser General Public License",
            "moduleLicenseUrl": "http://www.gnu.org/licenses/lgpl-3.0.txt"
        },
+        {
+            "moduleName": "org.cryptacular:cryptacular",
+            "moduleUrl": "https://www.cryptacular.org",
+            "moduleVersion": "1.3.0",
+            "moduleLicense": "GNU Lesser General Public License",
+            "moduleLicenseUrl": "https://www.gnu.org/licenses/lgpl-3.0.txt"
+        },
        {
            "moduleName": "org.eclipse.angus:angus-activation",
            "moduleUrl": "https://www.eclipse.org",
@@ -2016,78 +2110,156 @@
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-core-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-core-impl",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-core-impl",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-messaging-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-messaging-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-profile-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-profile-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-saml-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-saml-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-saml-impl",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-saml-impl",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-security-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-security-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-security-impl",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-security-impl",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-soap-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-soap-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-soap-impl",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-soap-impl",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-storage-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-storage-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-xmlsec-api",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-xmlsec-api",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.opensaml:opensaml-xmlsec-impl",
            "moduleVersion": "5.1.6",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "org.opensaml:opensaml-xmlsec-impl",
+            "moduleVersion": "5.2.2",
+            "moduleLicense": "The Apache Software License, Version 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "org.ow2.asm:asm",
            "moduleUrl": "http://asm.ow2.org",
@@ -2132,7 +2304,7 @@
        },
        {
            "moduleName": "org.simplejavamail:core-module",
-            "moduleVersion": "9.2.0",
+            "moduleVersion": "9.3.1",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
@@ -2145,13 +2317,13 @@
        },
        {
            "moduleName": "org.simplejavamail:outlook-module",
-            "moduleVersion": "9.2.0",
+            "moduleVersion": "9.3.1",
            "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.2.0",
+            "moduleVersion": "9.3.1",
            "moduleLicense": "The Apache Software License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
@@ -2564,6 +2736,13 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
+        {
+            "moduleName": "org.springframework.security:spring-security-core",
+            "moduleUrl": "https://spring.io/projects/spring-security",
+            "moduleVersion": "7.1.0",
+            "moduleLicense": "Apache License, Version 2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
+        },
        {
            "moduleName": "org.springframework.security:spring-security-crypto",
            "moduleUrl": "https://spring.io/projects/spring-security",
@@ -2606,6 +2785,13 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
        },
+        {
+            "moduleName": "org.springframework.security:spring-security-saml2-service-provider",
+            "moduleUrl": "https://spring.io/projects/spring-security",
+            "moduleVersion": "7.1.0",
+            "moduleLicense": "Apache License, Version 2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0"
+        },
        {
            "moduleName": "org.springframework.security:spring-security-web",
            "moduleUrl": "https://spring.io/projects/spring-security",
@@ -2805,207 +2991,207 @@
        },
        {
            "moduleName": "software.amazon.awssdk:annotations",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
-            "moduleName": "software.amazon.awssdk:apache-client",
-            "moduleVersion": "2.44.12",
+            "moduleName": "software.amazon.awssdk:apache5-client",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:arns",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:auth",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:aws-core",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:aws-query-protocol",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:aws-xml-protocol",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:checksums",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:checksums-spi",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:crt-core",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:endpoints-spi",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:http-auth",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:http-auth-aws",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:http-auth-aws-eventstream",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:http-auth-spi",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:http-client-spi",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:identity-spi",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:json-utils",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:metrics-spi",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:netty-nio-client",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:profiles",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:protocol-core",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:regions",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:retries",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:retries-spi",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:s3",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:sdk-core",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:third-party-jackson-core",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:url-connection-client",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:utils",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
        {
            "moduleName": "software.amazon.awssdk:utils-lite",
            "moduleUrl": "https://aws.amazon.com/sdkforjava",
-            "moduleVersion": "2.44.12",
+            "moduleVersion": "2.51.3",
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "https://aws.amazon.com/apache2.0"
        },
@@ -46,6 +46,7 @@ import stirling.software.SPDF.model.api.converters.PdfToPdfARequest;
 import stirling.software.SPDF.model.api.security.PDFVerificationResult;
 import stirling.software.SPDF.service.VeraPDFService;
 import stirling.software.common.configuration.RuntimePathConfig;
+import stirling.software.common.service.PdfaLevelAServiceInterface;
 import stirling.software.common.util.TempFileManager;

 /**
@@ -62,10 +63,12 @@ class ConvertPDFToPDFAGapTest {

    @Mock private RuntimePathConfig runtimePathConfig;
    @Mock private VeraPDFService veraPDFService;
+    @Mock private PdfaLevelAServiceInterface pdfaLevelAService;
    @Mock private TempFileManager tempFileManager;

    private ConvertPDFToPDFA newController() {
-        return new ConvertPDFToPDFA(runtimePathConfig, veraPDFService, tempFileManager);
+        return new ConvertPDFToPDFA(
+                runtimePathConfig, veraPDFService, pdfaLevelAService, tempFileManager);
    }

    // ---- reflection helpers ----------------------------------------------------------------
@@ -161,9 +164,21 @@ class ConvertPDFToPDFAGapTest {
        }

        private String suffixOf(Object profile) throws Exception {
-            Method m = profile.getClass().getDeclaredMethod("outputSuffix");
+            return suffixOf(profile, true);
+        }
+
+        private String suffixOf(Object profile, boolean levelAReached) throws Exception {
+            Method m = profile.getClass().getDeclaredMethod("outputSuffix", boolean.class);
            m.setAccessible(true);
-            return (String) m.invoke(profile);
+            return (String) m.invoke(profile, levelAReached);
+        }
+
+        @Test
+        @DisplayName("a level A profile falls back to the level B name when tagging failed")
+        void levelANotReachedIsNamedLevelB() throws Exception {
+            assertThat(suffixOf(resolveProfile("pdfa-1a"), false)).isEqualTo("_PDFA-1b.pdf");
+            assertThat(suffixOf(resolveProfile("pdfa-2a"), false)).isEqualTo("_PDFA-2b.pdf");
+            assertThat(suffixOf(resolveProfile("pdfa-3a"), true)).isEqualTo("_PDFA-3a.pdf");
        }

        @Test
@@ -717,6 +732,30 @@ class ConvertPDFToPDFAGapTest {
    @DisplayName("verifyStrictCompliance (VeraPDFService mocked)")
    class StrictCompliance {

+        private Object profile(String token) throws Exception {
+            Class<?> enumClass = null;
+            for (Class<?> inner : ConvertPDFToPDFA.class.getDeclaredClasses()) {
+                if (inner.getSimpleName().equals("PdfaProfile")) {
+                    enumClass = inner;
+                }
+            }
+            Method m = enumClass.getDeclaredMethod("fromRequest", String.class);
+            m.setAccessible(true);
+            return m.invoke(null, token);
+        }
+
+        private Throwable verify(String token, boolean levelAReached) throws Exception {
+            ConvertPDFToPDFA controller = newController();
+            return catchThrowable(
+                    () ->
+                            invokeInstance(
+                                    controller,
+                                    "verifyStrictCompliance",
+                                    (Object) "dummy".getBytes(),
+                                    profile(token),
+                                    levelAReached));
+        }
+
        @Test
        @DisplayName("compliant result passes without throwing")
        void compliantPasses() throws Exception {
@@ -726,14 +765,7 @@ class ConvertPDFToPDFAGapTest {
            ok.setComplianceSummary("PDF/A-1b compliant");
            when(veraPDFService.validatePDF(any())).thenReturn(List.of(ok));

-            ConvertPDFToPDFA controller = newController();
-            assertThatCode(
-                            () ->
-                                    invokeInstance(
-                                            controller,
-                                            "verifyStrictCompliance",
-                                            (Object) "dummy".getBytes()))
-                    .doesNotThrowAnyException();
+            assertThat(verify("pdfa-1", true)).isNull();
        }

        @Test
@@ -745,34 +777,70 @@ class ConvertPDFToPDFAGapTest {
            bad.setComplianceSummary("PDF/A-1b with errors");
            when(veraPDFService.validatePDF(any())).thenReturn(List.of(bad));

-            ConvertPDFToPDFA controller = newController();
-            ResponseStatusException ex =
-                    (ResponseStatusException)
-                            catchThrowable(
-                                    () ->
-                                            invokeInstance(
-                                                    controller,
-                                                    "verifyStrictCompliance",
-                                                    (Object) "dummy".getBytes()));
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-1", true);
            assertThat(ex).isNotNull();
            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
            assertThat(ex.getReason()).contains("PDF/A-1b with errors");
        }

+        @Test
+        @DisplayName("a level B pass does not satisfy a level A request")
+        void levelBDoesNotSatisfyLevelA() throws Exception {
+            PDFVerificationResult ok = new PDFVerificationResult();
+            ok.setCompliant(true);
+            ok.setStandard("1b");
+            ok.setComplianceSummary("PDF/A-1b compliant");
+            when(veraPDFService.validatePDF(any())).thenReturn(List.of(ok));
+
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-1a", true);
+            assertThat(ex).isNotNull();
+            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
+            assertThat(ex.getReason()).contains("PDF/A-1a");
+        }
+
+        @Test
+        @DisplayName("a level A result satisfies a level A request")
+        void levelASatisfiesLevelA() throws Exception {
+            PDFVerificationResult ok = new PDFVerificationResult();
+            ok.setCompliant(true);
+            ok.setStandard("2a");
+            ok.setComplianceSummary("PDF/A-2a compliant");
+            when(veraPDFService.validatePDF(any())).thenReturn(List.of(ok));
+
+            assertThat(verify("pdfa-2a", true)).isNull();
+        }
+
+        @Test
+        @DisplayName("untagged output fails a level A request before validation runs")
+        void untaggedLevelARequestFails() throws Exception {
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-2a", false);
+            assertThat(ex).isNotNull();
+            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
+            assertThat(ex.getReason()).contains("could not be tagged");
+            verifyNoInteractions(veraPDFService);
+        }
+
+        @Test
+        @DisplayName("a compliant PDF/UA result never satisfies a strict PDF/A request")
+        void accessibilityResultIsIgnored() throws Exception {
+            PDFVerificationResult ua = new PDFVerificationResult();
+            ua.setCompliant(true);
+            ua.setStandard("ua1");
+            ua.setValidationProfile("ua1");
+            ua.setComplianceSummary("PDF/UA-1 compliant");
+            when(veraPDFService.validatePDF(any())).thenReturn(List.of(ua));
+
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-2b", true);
+            assertThat(ex).isNotNull();
+            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
+        }
+
        @Test
        @DisplayName("empty result list is treated as non-compliant -> 400")
        void emptyResultsTreatedNonCompliant() throws Exception {
            when(veraPDFService.validatePDF(any())).thenReturn(Collections.emptyList());

-            ConvertPDFToPDFA controller = newController();
-            ResponseStatusException ex =
-                    (ResponseStatusException)
-                            catchThrowable(
-                                    () ->
-                                            invokeInstance(
-                                                    controller,
-                                                    "verifyStrictCompliance",
-                                                    (Object) "dummy".getBytes()));
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-1", true);
            assertThat(ex).isNotNull();
            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
        }
@@ -782,15 +850,7 @@ class ConvertPDFToPDFAGapTest {
        void serviceErrorWrappedAs500() throws Exception {
            when(veraPDFService.validatePDF(any())).thenThrow(new IOException("boom"));

-            ConvertPDFToPDFA controller = newController();
-            ResponseStatusException ex =
-                    (ResponseStatusException)
-                            catchThrowable(
-                                    () ->
-                                            invokeInstance(
-                                                    controller,
-                                                    "verifyStrictCompliance",
-                                                    (Object) "dummy".getBytes()));
+            ResponseStatusException ex = (ResponseStatusException) verify("pdfa-1", true);
            assertThat(ex).isNotNull();
            assertThat(ex.getStatusCode()).isEqualTo(HttpStatus.INTERNAL_SERVER_ERROR);
        }
@@ -42,6 +42,7 @@ import org.springframework.mock.web.MockMultipartFile;
 import stirling.software.SPDF.model.api.converters.PdfToPdfARequest;
 import stirling.software.SPDF.service.VeraPDFService;
 import stirling.software.common.configuration.RuntimePathConfig;
+import stirling.software.common.service.PdfaLevelAServiceInterface;
 import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.TempFile;
@@ -63,10 +64,12 @@ class ConvertPDFToPDFAMoreTest {

    @Mock private RuntimePathConfig runtimePathConfig;
    @Mock private VeraPDFService veraPDFService;
+    @Mock private PdfaLevelAServiceInterface pdfaLevelAService;
    @Mock private TempFileManager tempFileManager;

    private ConvertPDFToPDFA newController() {
-        return new ConvertPDFToPDFA(runtimePathConfig, veraPDFService, tempFileManager);
+        return new ConvertPDFToPDFA(
+                runtimePathConfig, veraPDFService, pdfaLevelAService, tempFileManager);
    }

    private static ResponseEntity<Resource> streamingOk(byte[] bytes) {
@@ -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
@@ -90,7 +90,9 @@ class VeraPDFServicePdfaFixtureTest {
                        () -> service.validatePDF(new ByteArrayInputStream(pdfBytes)),
                        "Empty veraPDF flavour list must not surface as IndexOutOfBoundsException");

-        assertEquals(1, results.size());
+        // One result: PDF/UA is checked by the dedicated accessibility-report endpoint, not here.
+        assertEquals(1, results.size(), () -> "Expected a single PDF/A result, got: " + results);
+
        PDFVerificationResult result = results.get(0);
        assertEquals("not-pdfa", result.getStandard());
        assertFalse(result.isDeclaredPdfa());
@@ -161,13 +163,22 @@ class VeraPDFServicePdfaFixtureTest {
        }
    }

+    /** The PDF/A result; every document is also checked against PDF/UA, so filter that one out. */
    private PDFVerificationResult onlyResult(byte[] pdfBytes) throws Exception {
        List<PDFVerificationResult> results =
                service.validatePDF(new ByteArrayInputStream(pdfBytes));

        assertNotNull(results);
-        assertEquals(1, results.size(), () -> "Expected a single result, got: " + results);
-        return results.get(0);
+        List<PDFVerificationResult> pdfaResults =
+                results.stream().filter(r -> !isUaResult(r)).toList();
+        assertEquals(
+                1, pdfaResults.size(), () -> "Expected a single PDF/A result, got: " + results);
+        return pdfaResults.get(0);
+    }
+
+    private static boolean isUaResult(PDFVerificationResult result) {
+        String profile = result.getValidationProfile();
+        return profile != null && profile.toLowerCase().contains("ua");
    }

    private static String messages(PDFVerificationResult result) {
@@ -27,7 +27,7 @@ dependencies {
    api 'org.springframework.boot:spring-boot-starter-cache'
    api 'com.github.ben-manes.caffeine:caffeine'
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
-    api 'io.swagger.core.v3:swagger-core-jakarta:2.2.46'
+    api 'io.swagger.core.v3:swagger-core-jakarta:2.2.53'
    implementation "com.bucket4j:bucket4j_jdk17-core:${bucket4jVersion}"
    // Lettuce-backed Bucket4j ProxyManager used by ValkeyRateLimitStore for cluster-wide
    // token-bucket rate limiting (parity with in-process Bucket4j semantics; no fixed-window
@@ -37,6 +37,15 @@ dependencies {
    // https://mvnrepository.com/artifact/com.bucket4j/bucket4j_jdk17
    implementation "org.bouncycastle:bcprov-jdk18on:$bouncycastleVersion"

+    // PDF/UA tagging and its validation oracle.
+    implementation 'org.verapdf:validation-model:1.30.2'
+    // CVE-2025-66453: Explicit rhino 1.7.15 to override verapdf's 1.7.13
+    implementation "org.mozilla:rhino:${rhinoVersion}"
+    // veraPDF still uses javax.xml.bind, not the new jakarta namespace
+    implementation 'javax.xml.bind:jaxb-api:2.3.1'
+    runtimeOnly 'com.sun.xml.bind:jaxb-impl:2.3.9'
+    runtimeOnly 'com.sun.xml.bind:jaxb-core:4.0.9'
+
    implementation "com.google.code.gson:gson:${gsonVersion}"

    // jinjava/jjwt transitively request older Jackson 2 versions; declare the current
@@ -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 =
@@ -0,0 +1,176 @@
+package stirling.software.proprietary.controller.api.converters;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+import org.springframework.core.io.Resource;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.github.pixee.security.Filenames;
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
+import stirling.software.common.enumeration.ResourceWeight;
+import stirling.software.common.model.tool.ToolFormat;
+import stirling.software.common.model.tool.ToolIO;
+import stirling.software.common.util.ExceptionUtils;
+import stirling.software.common.util.TempFile;
+import stirling.software.common.util.TempFileManager;
+import stirling.software.common.util.WebResponseUtils;
+import stirling.software.proprietary.model.api.converters.PdfToPdfUaRequest;
+import stirling.software.proprietary.model.api.ua.PdfUaConversionOutcome;
+import stirling.software.proprietary.pdf.ua.PdfUaProfile;
+import stirling.software.proprietary.pdf.ua.TaggingOptions;
+import stirling.software.proprietary.service.ua.PdfUaConversionService;
+
+/** Converts a PDF to PDF/UA; response headers say whether the result actually conforms. */
+@ConvertApi
+@Slf4j
+@RequiredArgsConstructor
+public class ConvertPdfToPdfUa {
+
+    private static final String HEADER_DECLARED = "X-Stirling-UA-Declared";
+    private static final String HEADER_FAILURES = "X-Stirling-UA-Failures";
+    private static final String HEADER_ALT_NEEDED = "X-Stirling-UA-Figures-Needing-Alt";
+    private static final String HEADER_WARNINGS = "X-Stirling-UA-Warnings";
+
+    /** Any line ending, so descriptions pasted from any platform parse the same. */
+    private static final Pattern NEWLINE = Pattern.compile("\\R");
+
+    private final PdfUaConversionService conversionService;
+    private final TempFileManager tempFileManager;
+
+    @AutoJobPostMapping(
+            consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
+            value = "/pdf/ua",
+            resourceWeight = ResourceWeight.LARGE_WEIGHT)
+    @ToolIO(produces = ToolFormat.PDF)
+    @Operation(
+            summary = "Convert a PDF to PDF/UA-1 or PDF/UA-2",
+            description =
+                    "Tags the document, marks decorative content as artifacts, embeds fonts and"
+                            + " applies the document-level requirements of PDF/UA, then validates"
+                            + " the result. A conformance declaration is written only if validation"
+                            + " passes, so the returned file never claims more than it delivers.")
+    public ResponseEntity<Resource> pdfToPdfUa(@ModelAttribute PdfToPdfUaRequest request)
+            throws IOException {
+
+        MultipartFile input = request.getFileInput();
+        if (input == null || input.isEmpty()) {
+            throw ExceptionUtils.createPdfFileRequiredException();
+        }
+
+        String originalName = Filenames.toSimpleFileName(input.getOriginalFilename());
+        String stem = stripExtension(originalName == null ? "document" : originalName);
+        PdfUaProfile profile = PdfUaProfile.fromRequest(request.getProfile());
+
+        TaggingOptions options =
+                TaggingOptions.builder()
+                        .profile(profile)
+                        .title(request.getTitle())
+                        .fallbackTitle(stem)
+                        // Only used when the document declares no language of its own.
+                        .language(
+                                request.getLanguage() == null || request.getLanguage().isBlank()
+                                        ? "en-GB"
+                                        : request.getLanguage())
+                        .overrideLanguage(
+                                request.getOverrideLanguage() != null
+                                        && request.getOverrideLanguage())
+                        .existingTags(existingTags(request.getExistingTags()))
+                        .figurePolicy(figurePolicy(request.getFigurePolicy()))
+                        .embedFonts(request.getEmbedFonts() == null || request.getEmbedFonts())
+                        .altTextByFigure(parseAltText(request.getAltText()))
+                        .build();
+
+        PdfUaConversionOutcome outcome = conversionService.convert(input.getBytes(), options);
+
+        log.info(
+                "Converted '{}' to {}: declared={}, {} remaining failure(s)",
+                originalName,
+                profile.displayName(),
+                outcome.declared(),
+                outcome.validation().totalFailures());
+
+        outcome.warnings().forEach(warning -> log.info("PDF/UA warning: {}", warning));
+
+        // Streamed from a temp file so a large conversion does not hold a second heap copy.
+        String suffix = outcome.declared() ? "_pdfua" + profile.part() : "_tagged";
+        TempFile tempOut = tempFileManager.createManagedTempFile(".pdf");
+        try {
+            Files.write(tempOut.getPath(), outcome.pdfBytes());
+        } catch (IOException e) {
+            tempOut.close();
+            throw e;
+        }
+        ResponseEntity<Resource> response =
+                WebResponseUtils.pdfFileToWebResponse(tempOut, stem + suffix + ".pdf");
+
+        return ResponseEntity.status(response.getStatusCode())
+                .headers(response.getHeaders())
+                .header(HEADER_DECLARED, String.valueOf(outcome.declared()))
+                .header(HEADER_FAILURES, String.valueOf(outcome.validation().totalFailures()))
+                .header(
+                        HEADER_ALT_NEEDED,
+                        String.valueOf(outcome.tagging().figuresNeedingAltText()))
+                // Count only: warning text is multi-line prose, which HTTP headers mangle.
+                .header(HEADER_WARNINGS, String.valueOf(outcome.warnings().size()))
+                .body(response.getBody());
+    }
+
+    /**
+     * Parses newline-separated {@code key=description} pairs, keyed as the report hands them out.
+     * Only the first "=" splits, since a description may contain one.
+     */
+    public static Map<String, String> parseAltText(String raw) {
+        if (raw == null || raw.isBlank()) {
+            return Map.of();
+        }
+        Map<String, String> parsed = new LinkedHashMap<>();
+        for (String line : NEWLINE.split(raw)) {
+            int split = line.indexOf('=');
+            if (split <= 0) {
+                continue;
+            }
+            String key = line.substring(0, split).strip();
+            String description = line.substring(split + 1).strip();
+            if (!key.isEmpty() && !description.isEmpty()) {
+                parsed.put(key, description);
+            }
+        }
+        return parsed;
+    }
+
+    private static TaggingOptions.ExistingTags existingTags(String value) {
+        if (value == null) {
+            return TaggingOptions.ExistingTags.AUTO;
+        }
+        return switch (value.trim().toLowerCase()) {
+            case "keep" -> TaggingOptions.ExistingTags.KEEP;
+            case "rebuild" -> TaggingOptions.ExistingTags.REBUILD;
+            default -> TaggingOptions.ExistingTags.AUTO;
+        };
+    }
+
+    private static TaggingOptions.FigurePolicy figurePolicy(String value) {
+        if (value != null && value.trim().equalsIgnoreCase("mark-decorative")) {
+            return TaggingOptions.FigurePolicy.MARK_DECORATIVE;
+        }
+        return TaggingOptions.FigurePolicy.REQUIRE_ALT;
+    }
+
+    private static String stripExtension(String filename) {
+        int dot = filename.lastIndexOf('.');
+        return dot > 0 ? filename.substring(0, dot) : filename;
+    }
+}
--- a/Show More
+++ b/Show More