Update FileRunEventRepository.java

Merge branch 'main' into format_java
saas: wrap long strings + Jackson import reorder
2026-09-03 13:20:08 +03:00 · 2026-09-01 11:48:00 +02:00 · 2026-09-01 11:30:04 +02:00 · 2026-09-01 11:23:50 +02:00 · 2026-09-01 11:18:33 +02:00 · 2026-09-01 08:56:35 +00:00
1010 changed files with 43698 additions and 9379 deletions
@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/scripts/lint/comment-lint-hook.mjs"
+            ],
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -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
@@ -8,11 +8,6 @@ updates:
  - package-ecosystem: "gradle" # See documentation for possible values
    directories:
      - "/" # Location of package manifests
-      - "/app/common"
-      - "/app/core"
-      - "/app/proprietary"
-      - "/app/saas"
-      - "/buildSrc"
    schedule:
      interval: "weekly"
    cooldown:
@@ -67,6 +67,7 @@ labels:
      - 'frontend/**'
      - 'frontend/.*'
      - 'frontend/**/.*'
+      - '.taskfiles/frontend.yml'

  - label: 'Tauri'
    files:
@@ -20,6 +20,7 @@ Closes #(issue_number)
 - [ ] 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
+- [ ] Every comment I added says something the code does not ([guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/CODE_COMMENTS.md))
 - [ ] My changes generate no new warnings

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

@@ -182,7 +182,7 @@ jobs:
          fetch-depth: 0 # Fetch full history for commit hash detection

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Get version number
        id: versionNumber
@@ -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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0

      - name: Build and deploy Storybook
        id: storybook
@@ -475,7 +475,7 @@ jobs:

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

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

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

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

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

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Run Gradle Command
        run: |
          if [ "${{ needs.check-comment.outputs.disable_security }}" == "true" ]; then
@@ -222,7 +222,7 @@ jobs:
          STIRLING_PDF_DESKTOP_UI: false

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Login to GitHub Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
@@ -482,7 +482,7 @@ jobs:
      issues: write # add/remove labels, delete the command comment
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

@@ -0,0 +1,246 @@
+name: Auto SaaS Dev Deployment
+
+on:
+  push:
+    branches:
+      - saas-prod
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  FRONTEND_PORT: "901"
+  BACKEND_PORT: "902"
+  DEPLOY_DIR: /stirling/SAAS-DEV
+
+jobs:
+  deploy-saas-dev:
+    runs-on: ubuntu-latest
+    environment: saas-dev
+    concurrency:
+      group: saas-dev-deploy
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
+        with:
+          egress-policy: audit
+
+      - name: Check SaaS configuration
+        id: config
+        env:
+          PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+        run: |
+          echo "supabase_url=https://${PROJECT_REF}.supabase.co" >> "$GITHUB_OUTPUT"
+          echo "meter_endpoint=https://${PROJECT_REF}.supabase.co/functions/v1/meter-payg-units" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Convert repository owner to lowercase
+        id: repoowner
+        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+      - name: Get commit hash
+        id: commit-hash
+        run: echo "app_short=$(git rev-parse --short=8 HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Build and push backend image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: ./docker/backend/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-saas-backend
+          cache-to: type=gha,mode=max,scope=stirling-saas-backend
+          tags: |
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-${{ steps.commit-hash.outputs.app_short }}
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-latest
+          build-args: |
+            VERSION_TAG=v2-alpha
+            STIRLING_FLAVOR=saas
+          platforms: linux/amd64
+
+      - name: Build and push frontend image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: ./docker/frontend/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-saas-frontend
+          cache-to: type=gha,mode=max,scope=stirling-saas-frontend
+          tags: |
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-${{ steps.commit-hash.outputs.app_short }}
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-latest
+          build-args: |
+            VERSION_TAG=v2-alpha
+            STIRLING_FLAVOR=saas
+            VITE_BUILD_MODE=development
+            VITE_SUPABASE_URL=${{ steps.config.outputs.supabase_url }}
+            VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY=${{ secrets.SAAS_SUPABASE_PUBLISHABLE_KEY }}
+          platforms: linux/amd64
+
+      - name: Build and push AI engine image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: ./engine/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-saas-engine
+          cache-to: type=gha,mode=max,scope=stirling-saas-engine
+          tags: |
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-${{ steps.commit-hash.outputs.app_short }}
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-latest
+          platforms: linux/amd64
+
+      - name: Set up SSH
+        env:
+          SSH_KEY: ${{ secrets.NEW_VPS_SSH_KEY }}
+        run: |
+          mkdir -p ~/.ssh/
+          echo "$SSH_KEY" > ../private.key
+          sudo chmod 600 ../private.key
+
+      - name: Deploy to VPS
+        env:
+          IMAGE_BASE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test
+          IMAGE_TAG: ${{ steps.commit-hash.outputs.app_short }}
+          GHCR_USER: ${{ github.actor }}
+          GHCR_TOKEN: ${{ github.token }}
+          VPS_USERNAME: ${{ secrets.NEW_VPS_USERNAME }}
+          VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+          SAAS_DB_URL: ${{ secrets.SAAS_DB_URL }}
+          SAAS_DB_USERNAME: ${{ secrets.SAAS_DB_USERNAME || 'postgres' }}
+          SAAS_DB_PASSWORD: ${{ secrets.SAAS_DB_PASSWORD }}
+          SAAS_DB_PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+          SUPABASE_EDGE_FUNCTION_SECRET: ${{ secrets.SUPABASE_EDGE_FUNCTION_SECRET }}
+          PAYG_METER_ENDPOINT: ${{ steps.config.outputs.meter_endpoint }}
+          STIRLING_KEYGEN_ENABLED: ${{ secrets.KEYGEN_ACCOUNT_ID != '' && secrets.KEYGEN_API_TOKEN != '' && secrets.KEYGEN_POLICY_ID != '' }}
+          KEYGEN_ACCOUNT_ID: ${{ secrets.KEYGEN_ACCOUNT_ID }}
+          KEYGEN_API_TOKEN: ${{ secrets.KEYGEN_API_TOKEN }}
+          KEYGEN_POLICY_ID: ${{ secrets.KEYGEN_POLICY_ID }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
+        run: |
+          set -euo pipefail
+
+          BASE_URL="http://${VPS_HOST}:${FRONTEND_PORT}"
+
+          yaml() {
+            printf "'%s'" "$(printf '%s' "$1" | sed -e "s/'/''/g" -e 's/\$/$$/g')"
+          }
+
+            ENGINE_SECRET="$(openssl rand -hex 32)"
+            AI_BACKEND_VARS="
+                SYSTEM_AIENGINE_ENABLED: \"true\"
+                SYSTEM_AIENGINE_URL: \"http://saas-engine:5001\"
+                APP_AI_SERVICEBASEURL: \"http://saas-engine:5001\"
+                STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")"
+            AI_SERVICE="
+
+            saas-engine:
+              container_name: stirling-saas-dev-engine
+              image: ${IMAGE_BASE}:saas-engine-${IMAGE_TAG}
+              environment:
+                ANTHROPIC_API_KEY: $(yaml "$ANTHROPIC_API_KEY")
+                VOYAGE_API_KEY: $(yaml "$VOYAGE_API_KEY")
+                STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")
+              restart: on-failure:5"
+
+          cat > docker-compose.yml << EOF
+          version: '3.3'
+          services:
+            saas-backend:
+              container_name: stirling-saas-dev-backend
+              image: ${IMAGE_BASE}:saas-backend-${IMAGE_TAG}
+              ports:
+                - "${BACKEND_PORT}:8080"
+              volumes:
+                - ${DEPLOY_DIR}/config:/configs:rw
+                - ${DEPLOY_DIR}/logs:/logs:rw
+                - ${DEPLOY_DIR}/storage:/storage:rw
+              environment:
+                SPRING_PROFILES_ACTIVE: "saas"
+                DISABLE_ADDITIONAL_FEATURES: "false"
+                SAAS_DB_URL: $(yaml "$SAAS_DB_URL")
+                SAAS_DB_USERNAME: $(yaml "$SAAS_DB_USERNAME")
+                SAAS_DB_PASSWORD: $(yaml "$SAAS_DB_PASSWORD")
+                SAAS_DB_PROJECT_REF: $(yaml "$SAAS_DB_PROJECT_REF")
+                SUPABASE_EDGE_FUNCTION_SECRET: $(yaml "$SUPABASE_EDGE_FUNCTION_SECRET")
+                PAYG_METER_ENDPOINT: $(yaml "$PAYG_METER_ENDPOINT")
+                STIRLING_KEYGEN_ENABLED: $(yaml "$STIRLING_KEYGEN_ENABLED")
+                KEYGEN_ACCOUNT_ID: $(yaml "$KEYGEN_ACCOUNT_ID")
+                KEYGEN_API_TOKEN: $(yaml "$KEYGEN_API_TOKEN")
+                KEYGEN_POLICY_ID: $(yaml "$KEYGEN_POLICY_ID")
+                SYSTEM_DEFAULTLOCALE: en-US
+                SYSTEM_MAXFILESIZE: "100"
+                METRICS_ENABLED: "true"
+                SYSTEM_GOOGLEVISIBILITY: "false"
+                SWAGGER_SERVER_URL: "${BASE_URL}"
+                baseUrl: "${BASE_URL}"${AI_BACKEND_VARS}
+              restart: on-failure:5
+
+            saas-frontend:
+              container_name: stirling-saas-dev-frontend
+              image: ${IMAGE_BASE}:saas-frontend-${IMAGE_TAG}
+              ports:
+                - "${FRONTEND_PORT}:80"
+              environment:
+                VITE_API_BASE_URL: "http://saas-backend:8080"
+              depends_on:
+                - saas-backend
+              restart: on-failure:5${AI_SERVICE}
+          EOF
+
+          SSH_OPTS=(-i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null)
+
+          scp "${SSH_OPTS[@]}" docker-compose.yml "${VPS_USERNAME}@${VPS_HOST}:/tmp/saas-dev-docker-compose.yml"
+
+          ssh "${SSH_OPTS[@]}" -T "${VPS_USERNAME}@${VPS_HOST}" << ENDSSH
+            set -e
+            mkdir -p ${DEPLOY_DIR}/{config,logs,storage}
+            mv /tmp/saas-dev-docker-compose.yml ${DEPLOY_DIR}/docker-compose.yml
+            chmod 600 ${DEPLOY_DIR}/docker-compose.yml
+            cd ${DEPLOY_DIR}
+            printf '%s' "${GHCR_TOKEN}" | docker login ghcr.io -u "${GHCR_USER}" --password-stdin
+            docker-compose down --remove-orphans 2>/dev/null || true
+            docker-compose pull
+            docker-compose up -d
+            docker logout ghcr.io >/dev/null 2>&1 || true
+            docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true
+          ENDSSH
+
+      - name: Wait for the backend to answer
+        env:
+          VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+        run: |
+          URL="http://${VPS_HOST}:${BACKEND_PORT}/api/v1/info/status"
+          for i in $(seq 1 60); do
+            code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$URL" || true)
+            if [ "$code" = "200" ]; then echo "Healthy after $((i * 10))s"; exit 0; fi
+            sleep 10
+          done
+          echo "::error::SaaS dev backend did not become healthy within 10 minutes"
+          exit 1
+
+      - name: Cleanup temporary files
+        if: always()
+        run: rm -f ../private.key docker-compose.yml
+        continue-on-error: true
@@ -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,16 +28,15 @@ 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: |
            engine/pyproject.toml
            engine/uv.lock
-          cache-suffix: ai-engine

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

      - 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

@@ -31,7 +31,7 @@ jobs:
        flavor: [core, proprietary, saas]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -52,7 +52,7 @@ jobs:
          distribution: "temurin"

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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
@@ -197,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: |
@@ -58,7 +58,7 @@ jobs:
      SYSTEM_ENABLEANALYTICS: "false"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -95,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Install Playwright (chromium only)
        run: task e2e:install -- chromium
      - name: Build frontend (needed for playwright's vite preview webServer)
@@ -351,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: |
@@ -49,7 +49,7 @@ jobs:
      proprietary: ${{ steps.changes.outputs.proprietary }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -298,7 +298,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

@@ -36,13 +36,12 @@ 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: |
            engine/pyproject.toml
            engine/uv.lock
-          cache-suffix: generated-models

      - name: Restore cache Gradle User Home
        if: inputs.use_shared_cache
@@ -76,7 +75,7 @@ jobs:
          cache-dependency-path: frontend/package-lock.json

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

      - name: Verify generated models are up to date
        id: models-check
@@ -16,7 +16,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Check licenses for compatibility
        run: task backend:licenses:check
        env:
@@ -17,7 +17,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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: |
@@ -20,7 +20,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

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

@@ -57,7 +57,7 @@ jobs:
      # runtime token isn't exposed) since the docker driver can't use it.
      - name: Set up Docker Buildx
        if: inputs.docker-base-changed != 'true'
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      # Expose ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL for docker buildx type=gha cache backend.
      - name: Expose GitHub runtime for Buildx cache
@@ -70,7 +70,7 @@ jobs:
          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: |
@@ -18,7 +18,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -45,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Install Playwright (chromium only)
        run: task e2e:install -- chromium
      - name: Build frontend (production bundle for vite preview)
@@ -106,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: |
@@ -32,7 +32,7 @@ jobs:
            project: stubbed-webkit
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -44,7 +44,7 @@ jobs:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Build frontend (production bundle for vite preview)
        env:
          VITE_BUILD_FOR_PREVIEW: "1"
@@ -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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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

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

@@ -97,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0

      - name: Generate frontend license report (Push only)
        if: github.event_name == 'push'
@@ -334,7 +334,7 @@ jobs:
      repository-projects: write # Required for enabling automerge
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

      - 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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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: |
@@ -18,7 +18,7 @@ jobs:
    timeout-minutes: 15
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -15,7 +15,7 @@ jobs:
      issues: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Get version number
        id: versionNumber
        run: |
@@ -140,7 +140,7 @@ jobs:
            file_suffix: "-server"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

      - name: Build JAR
        run: ./gradlew build ${{ matrix.variant.build_frontend && '-PbuildWithFrontend=true' || '' }} -x spotlessApply -x spotlessCheck -x test -x sonarqube
@@ -207,7 +207,7 @@ jobs:
      RELEASE_GPG_PRIVATE_KEY: ${{ secrets.RELEASE_GPG_PRIVATE_KEY }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit
          allowed-endpoints: >
@@ -268,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0

      # Build the universal JRE before desktop:prepare so the jlink:runtime
      # task short-circuits on its `test -d runtime/jre` status check.
@@ -715,7 +715,7 @@ jobs:
      contents: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -872,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0

      - name: a11y gate (every story, ${{ matrix.theme }})
        run: task frontend:storybook:a11y:${{ matrix.theme }}
@@ -140,7 +140,7 @@ jobs:
      contents: read
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -154,7 +154,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: |
@@ -162,7 +162,7 @@ jobs:
            engine/uv.lock

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

      - name: Start the fat image with login and storage enabled
        run: docker compose -f docker/embedded/compose/test_cicd.yml up -d --build
@@ -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,16 +25,20 @@ 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: |
            engine/pyproject.toml
            engine/uv.lock
-          cache-suffix: pre-commit

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

      - name: Run pre-commit checks
        run: task pre-commit
+
+      # The fixture corpus checks the comment rules themselves, so it runs here
+      # rather than on every local commit.
+      - name: Check the comment-lint fixture corpus
+        run: task pre-commit:comment-lint:selftest
@@ -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

@@ -69,7 +69,7 @@ jobs:

      - name: Set up Docker Buildx
        id: buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Set up QEMU
        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
@@ -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

@@ -74,10 +85,10 @@ jobs:

      - name: Set up Docker Buildx
        id: buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        uses: github/codeql-action/upload-sarif@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
        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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - 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,20 +53,19 @@ 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: |
            engine/pyproject.toml
            engine/uv.lock
-          cache-suffix: sync-files

      - name: Install Python dependencies
        run: |
          uv sync --project engine --locked --group tools

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

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

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

@@ -212,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: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0

      - name: Build universal macOS JRE
        if: matrix.platform == 'macos-15'
@@ -703,7 +703,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden the runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

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

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

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

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

      - name: Install Task
-        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+        uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
      - name: Build application
        run: task backend:build
        env:
@@ -142,7 +142,7 @@ jobs:

      - name: Set up Docker Buildx
        id: buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Set base image and platform for this build
        id: build-params
@@ -217,7 +217,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -229,7 +229,7 @@ jobs:

      - name: Set up Docker Buildx
        id: buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Build docker/unoserver/Dockerfile
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -19,7 +19,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden runner
-        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

@@ -176,6 +176,8 @@ app/core/src/main/resources/static/images/google-drive.svg
 *.nar
 *.ear
 *.zip
+# Real backend archives the form-bundle reader is tested against.
+!frontend/editor/src/core/tools/formFill/__fixtures__/*.zip
 *.tar.gz
 *.rar
 *.db
@@ -296,8 +298,13 @@ docs/type3/signatures/

 **/application-dev-local.properties

-# Claude
-.claude/
+# Claude. Contents are ignored so personal config stays local, with the two
+# shared pieces re-included: settings.json (the comment-lint hook) and skills/.
+# The directory itself cannot be ignored or git will not look inside it.
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+.claude/settings.local.json

 # Playwright MCP screenshots / traces
 .playwright-mcp/
@@ -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/*"
  ]
 }
@@ -40,12 +40,15 @@ tasks:
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
      SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN | default ""}}'
+      # Set by dev:linked. Inline rather than in `env:` so an empty value emits nothing
+      # and cannot blank the committed default.
+      ACCOUNT_LINK_SAAS_BASE_URL: '{{.ACCOUNT_LINK_SAAS_BASE_URL | default ""}}'
    env:
      SERVER_PORT: '{{.PORT}}'
    cmds:
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .ACCOUNT_LINK_SAAS_BASE_URL}}STIRLING_BILLING_ACCOUNT_LINK_ENABLED=true STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL={{.ACCOUNT_LINK_SAAS_BASE_URL}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
        platforms: [windows]
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}./gradlew :stirling-pdf:bootRun'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .ACCOUNT_LINK_SAAS_BASE_URL}}STIRLING_BILLING_ACCOUNT_LINK_ENABLED=true STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL={{.ACCOUNT_LINK_SAAS_BASE_URL}} {{end}}./gradlew :stirling-pdf:bootRun'
        platforms: [linux, darwin]

  dev:bundled:
@@ -84,6 +87,8 @@ tasks:
          AIENGINE_URL: '{{.AIENGINE_URL}}'
          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+          APP_BASE_URL: '{{.APP_BASE_URL}}'
+          BASE_PATH: '{{.BASE_PATH}}'

  staging:saas:
    desc: "Start SaaS backend against the shared v3 staging project"
@@ -95,10 +100,47 @@ tasks:
          AIENGINE_URL: '{{.AIENGINE_URL}}'
          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+          APP_BASE_URL: '{{.APP_BASE_URL}}'
+          BASE_PATH: '{{.BASE_PATH}}'
+
+  dev:linked:
+    desc: "Self-hosted backend linked to a locally running SaaS backend (see task linked:*)"
+    ignore_error: true
+    vars:
+      PORT: '{{.PORT | default "8080"}}'
+      SAAS_BASE_URL: '{{.SAAS_BASE_URL | default "http://localhost:8081"}}'
+    cmds:
+      - 'echo ">> self-hosted :{{.PORT}} linking to SaaS at {{.SAAS_BASE_URL}}"'
+      # The two backends run different STIRLING_FLAVOURs, which are different Gradle
+      # project graphs sharing one build/ tree. Waiting avoids overlapping builds; it
+      # does not make the sharing safe, so avoid rebuilding one while the other runs.
+      - cmd: |
+          n=0
+          while [ "$n" -lt 150 ]; do
+            if curl -s -m 2 "{{.SAAS_BASE_URL}}" >/dev/null 2>&1; then
+              echo ">> SaaS backend is up, starting self-hosted"
+              break
+            fi
+            n=$((n + 1))
+            {{if eq OS "windows"}}powershell -NoProfile -Command "Start-Sleep -Seconds 2"{{else}}sleep 2{{end}}
+          done
+          if [ "$n" -ge 150 ]; then
+            echo ">> SaaS backend never answered; starting anyway"
+          fi
+      - task: dev:proprietary
+        vars:
+          PORT: '{{.PORT}}'
+          ACCOUNT_LINK_SAAS_BASE_URL: '{{.SAAS_BASE_URL}}'

  _run:saas:
    internal: true
-    dotenv: ['app/.env.saas.local', 'app/.env.saas']
+    # The frontend files are here only for RUN_SUBPATH, which the authorize URL needs.
+    # Last, because dotenv is set-if-absent: app/* still decides everything else.
+    dotenv:
+      - 'app/.env.saas.local'
+      - 'app/.env.saas'
+      - 'frontend/editor/.env.saas.local'
+      - 'frontend/editor/.env.saas'
    ignore_error: true
    vars:
      PORT: '{{.PORT | default "8080"}}'
@@ -111,12 +153,29 @@ tasks:
      AIENGINE_URL: '{{.AIENGINE_URL | default ""}}'
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
+      # Empty is the same as unset: the property defaults to empty and is blank-checked.
+      APP_BASE_URL: '{{.APP_BASE_URL | default ""}}'
+      # Relocates configs/pipeline/logs, for a second backend in the same directory.
+      # Empty is the same as unset: the reader blank-checks it.
+      BASE_PATH: '{{.BASE_PATH | default ""}}'
    env:
      SERVER_PORT: '{{.PORT}}'
      STIRLING_FLAVOR: saas
+      STIRLING_BASE_PATH: '{{.BASE_PATH}}'
      AIENGINE_URL: '{{.AIENGINE_URL}}'
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+      # Appends RUN_SUBPATH: the approval page is at <base>/link, so a subpath build
+      # serves it at <base>/app/link. An explicit value still wins.
+      SYSTEM_FRONTENDURL:
+        sh: |
+          if [ -n "${SYSTEM_FRONTENDURL:-}" ]; then
+            echo "${SYSTEM_FRONTENDURL}"
+          elif [ -n "{{.APP_BASE_URL}}" ] && [ -n "${RUN_SUBPATH:-}" ]; then
+            echo "{{.APP_BASE_URL}}/${RUN_SUBPATH}"
+          else
+            echo "{{.APP_BASE_URL}}"
+          fi
    cmds:
      # PROFILE_ARGS is empty when PROFILES=none, i.e. the bare `saas` profile
      # against SAAS_DB_* (production).
@@ -23,7 +23,7 @@ tasks:
      - package-lock.json
      - package.json
    status:
-      - test -d node_modules
+      - npm ls --depth=0
    env:
      CI: '{{ .CI | default "false" }}'

@@ -121,17 +121,17 @@ tasks:
        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}" ;;
+            *)       ref="${SAAS_DEV_PROJECT_REF:?set it in app/.env.saas.local, or pass SAAS_ENV=staging}" ;;
          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}" ;;
+            *)       echo "${SAAS_DEV_PUBLISHABLE_KEY:?set it in app/.env.saas.local, or pass SAAS_ENV=staging}" ;;
          esac
    cmds:
-      - 'echo ">> frontend Supabase target: $VITE_SUPABASE_URL"'
+      - 'echo ">> frontend {{.SAAS_ENV}}: Supabase $VITE_SUPABASE_URL, backend $BACKEND_URL"'
      - npx vite editor --mode saas --port {{.PORT}}{{if .OPEN}} --open{{end}}

  dev:
@@ -173,6 +173,16 @@ tasks:
          OPEN: '{{.OPEN}}'
          SAAS_ENV: '{{.SAAS_ENV}}'

+  staging:saas:
+    desc: "Start frontend dev server against the shared v3 staging project"
+    cmds:
+      - task: dev:saas
+        vars:
+          SAAS_ENV: staging
+          PORT: '{{.PORT}}'
+          BACKEND_URL: '{{.BACKEND_URL}}'
+          OPEN: '{{.OPEN}}'
+
  dev:desktop:
    desc: "Start frontend dev server in desktop mode"
    deps:
@@ -375,13 +385,13 @@ tasks:
    desc: "Auto-fix code formatting"
    deps: [install]
    cmds:
-      - npx prettier --write .
+      - npx oxfmt --write .

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

  fix:
    desc: "Auto-fix lint and format"
@@ -554,6 +564,7 @@ tasks:
    deps: [install, ":backend:swagger"]
    cmds:
      - npx tsx editor/scripts/generate-tool-api-types.mts --spec ../SwaggerDoc.json --output editor/src/core/types/toolApiTypes.ts --io-output editor/src/core/types/toolIO.ts
+      - task: format
    sources:
      - editor/scripts/generate-tool-api-types.mts
      - ../SwaggerDoc.json
@@ -563,9 +574,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"
@@ -11,6 +11,7 @@ vars:
    '.github/scripts/*.py'
    'app/core/src/main/resources/static/python/*.py'
    ':(exclude)*split_photos.py'
+    ':(exclude)scripts/lint/fixtures/*'
  SPELL_FILES: >-
    '*.html'
    '*.css'
@@ -59,6 +60,7 @@ tasks:
      - task: gitleaks
      - task: whitespace
      - task: toml-sort
+      - task: comment-lint

  fix:
    desc: "Auto-fix formatting, spelling, and secrets issues across the repo"
@@ -75,6 +77,7 @@ tasks:
        vars: { FIX: '1' }
      - task: codespell
      - task: gitleaks
+      - task: comment-lint

  install:
    desc: "Install the pinned pre-commit Python tools"
@@ -130,6 +133,85 @@ tasks:
    cmds:
      - "{{.GITLEAKS_BIN}} git --pre-commit --redact --staged --verbose"

+  comment-lint:
+    desc: "Check comment quality on the lines this branch adds"
+    summary: |
+      Blocks a comment that restates the code below it, a section banner, or a
+      block of commented-out code. Everything else it reports is advisory.
+
+      Scoped to added lines, so touching an old file never surfaces the standing
+      backlog. The standard is devGuide/CODE_COMMENTS.md.
+
+      With no arguments it diffs the working tree against HEAD, which is what a
+      pre-commit run wants: the lines you are about to commit. On a CI pull request
+      it diffs against the target branch instead, via GITHUB_BASE_REF.
+
+      To ask what a whole branch adds instead, use the branch variant, which
+      needs no argument passing:
+        task comment-lint:branch
+
+      Full tree (report only):     task pre-commit:comment-lint:all
+      Fixture corpus:             task pre-commit:comment-lint:selftest
+    # Depends on the frontend install because the .ts/.tsx half of the rule set
+    # runs as an oxlint plugin. Without it the TS engine warns and skips, which
+    # would leave the frontend silently unchecked on CI.
+    deps: [":frontend:install"]
+    cmds:
+      - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+  comment-lint:branch:
+    desc: "Check comment quality on everything this branch adds over its base"
+    summary: |
+      Like `task comment-lint`, but scoped to the whole branch rather than to
+      uncommitted work, so it still reports after you commit.
+
+      Exists as its own task because passing `-- --since origin/main` through Task
+      is not portable: with the npm build of Task the launcher is a PowerShell
+      script, and PowerShell strips the `--` before Task sees it, leaving Task to
+      print its own usage.
+
+      Override the base with BASE=<ref>.
+    vars:
+      BASE: '{{.BASE | default "origin/main"}}'
+    deps: [":frontend:install"]
+    cmds:
+      - node scripts/lint/comment-lint.mjs --since {{.BASE}}
+
+  comment-lint:ci:
+    desc: "Comment gate as CI runs it: fixture corpus, then the diff"
+    summary: |
+      The corpus checks the rules themselves rather than the code under review, so
+      it belongs on CI and not on every local commit. Run this before changing a
+      rule, and let CI run it on every pull request.
+    deps: [":frontend:install"]
+    cmds:
+      - node scripts/lint/comment-lint.mjs --selftest
+      - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+  comment-lint:hook:
+    desc: "Comment gate for the editor hook: everything this turn changed"
+    summary: |
+      Same scope as `task comment-lint`, kept as its own name so the hook has a
+      stable entry point and the taskfile shows every way the linter is invoked.
+
+      Not in the frontend-install dependency chain on purpose: this runs at the end
+      of every turn, so it stays as short as it can be. If oxlint is missing the TS
+      half warns and skips.
+    cmds:
+      - node scripts/lint/comment-lint.mjs
+
+  comment-lint:all:
+    desc: "Report every comment finding in the tree (never fails)"
+    deps: [":frontend:install"]
+    cmds:
+      - node scripts/lint/comment-lint.mjs --all
+
+  comment-lint:selftest:
+    desc: "Check both comment-lint engines against the fixture corpus"
+    deps: [":frontend:install"]
+    cmds:
+      - node scripts/lint/comment-lint.mjs --selftest
+
  gitleaks-bin:
    internal: true
    desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
@@ -42,7 +42,7 @@
  "java.configuration.updateBuildConfiguration": "interactive",
  "java.format.enabled": true,
  "java.format.settings.profile": "GoogleStyle",
-  "java.format.settings.google.version": "1.28.0",
+  "java.format.settings.google.version": "1.35.0",
  "java.format.settings.google.extra": "--aosp --skip-sorting-imports --skip-javadoc-formatting",
  // (DE) Aktiviert Kommentare im Java-Format.
  // (EN) Enables comments in Java formatting.
@@ -21,6 +21,43 @@ Task `desc:` fields should describe **what** the task does, not **how** it does
 - `task docker:build` — build standard Docker image
 - `task docker:up` — start Docker compose stack

+## Comments
+
+A comment must carry information the code cannot. If a reader could derive it from the code in front of them, delete it.
+
+Comment the current state. Not what the code used to do, not what changed, not why it changed: git holds that. Where history explains the shape, state the reason instead, so "this used to reimplement the modal internals" becomes "thin wrapper over the shared Modal: duplicating its portal and focus trap is how dialogs drift apart". Future state goes in a TODO with an issue.
+
+Write a comment when it does one of these four jobs:
+
+- **Contract.** What a caller must know that the signature cannot say: preconditions, invariants, units, ownership and lifetime, thread-safety, error semantics, side effects. Document the contract of everything a caller outside the file can reach, and nothing else. Goes on the type/method/module as Javadoc, JSDoc, or a docstring.
+- **Why.** The constraint the code satisfies, the bug it avoids, the alternative rejected and the reason.
+- **Hazard.** "Must stay in sync with X", "order matters because Y", "do not remove, it prevents Z".
+- **Map.** A short orientation at the top of a genuinely complex file: what it owns, and what it deliberately does not.
+
+Never write:
+
+- A comment that restates the next line. `// Handle drag start` above `handleDragStart` is noise.
+- Section banners or position markers: `// --- Types ---`, `// Helpers`, `// =====`.
+- Step narration in a function body (`// Step 1:`, `// Then we`). If the steps need labels they need names: extract functions. Numbering a genuinely numbered thing, like a wizard step, is fine.
+- Commented-out code. Delete it.
+- Doc tags that restate the signature. `@param blob - The blob` says nothing; omit the tag rather than pad it.
+- Docs on self-explanatory members with no constraint to state.
+
+Two tests before keeping a comment:
+
+- **Delete it.** Is any information lost? If not, it stays deleted.
+- **Could a name carry it instead?** A better identifier, an extracted function, or a named constant beats a comment. Prefer the code change.
+
+A comment at the end of a line usually decodes that line, and that is worth keeping: `{0x25, 0x50} // "%PDF"`, `50L * 1024 * 1024 // 50 MB`. The rules that compare a comment against the code below it do not apply there, but a trailing TODO or a trailing bit of history is judged like any other.
+
+A reference is supplementary, never load-bearing: the comment must survive deleting it. `// See #1234` is a dead end; `// saving first loses every annotation (#6865)` is not. Prefer a spec (`RFC 3161`) or CVE where one applies.
+
+A TODO needs an issue, not an owner: `// TODO(#1234): re-enable the gate once account syncing lands`. If it is not worth an issue, it is not worth a TODO. A question is not a TODO.
+
+A comment block over ~12 lines outside a file or type header usually means the code needs restructuring, or that the prose is product documentation and belongs in the docs repo.
+
+`task comment-lint` checks the mechanical part of this on the lines you add, and runs inside `task pre-commit`. Reasoning, worked examples and the linter's own rules: @devGuide/CODE_COMMENTS.md
+
 ## Common Development Commands

 ### Build and Test
@@ -70,7 +107,7 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie
 - Avoid nested functions and nested classes unless the language construct requires them.
 - Prefer composition to inheritance when combining concepts.
 - Avoid speculative abstractions. Add a layer only when it removes real duplication or clarifies lifecycle.
- Add comments sparingly and only when they explain non-obvious intent.
+- Comments follow the repo-wide rules in the "Comments" section above.

 #### Python Typing and Models
 - Deserialize into Pydantic models as early as possible.
@@ -42,6 +42,7 @@ Please make sure your Pull Request adheres to the following guidelines:
 - Keep commits atomic. One commit should contain one change. If you want to make multiple changes, submit multiple Pull Requests.
 - Commits should be clear, concise, and easy to understand.
 - References to the Issue number in the Pull Request and/or Commit message.
+- Every comment in the diff should say something the code does not. See [Code comments](devGuide/CODE_COMMENTS.md); `task comment-lint` checks the mechanical part.

 ## Translations

@@ -121,6 +121,92 @@ tasks:
    cmds:
      - task: dev:_all

+  # No engine: linking never calls it.
+  linked:staging:
+    desc: "SaaS on the shared v3 project + a self-hosted instance linked to it"
+    cmds:
+      - task: linked:_all
+        vars: { SAAS_ENV: staging }
+
+  linked:dev:
+    desc: "SaaS on the current PR's preview branch + a self-hosted instance linked to it"
+    cmds:
+      - task: linked:_all
+        vars: { SAAS_ENV: dev }
+
+  linked:_all:
+    internal: true
+    vars:
+      SAAS_ENV: '{{.SAAS_ENV | default "staging"}}'
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8081 5174 8080 5173{{else}}{{.FIND_FREE_PORT_SH}} 8081 5174 8080 5173{{end}}'
+      SAAS_BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      SAAS_FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+      APP_BACKEND_PORT: '{{index (splitList "\n" .PORTS) 2}}'
+      APP_FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 3}}'
+    deps:
+      # APP_BASE_URL is the SaaS *frontend*: the approval page is served by vite, not
+      # by the API. BASE_PATH moves this backend's configs/pipeline aside so it does not
+      # race the self-hosted one, which keeps ./configs and its existing database.
+      - task: 'backend:{{.SAAS_ENV}}:saas'
+        vars:
+          PORT: '{{.SAAS_BACKEND_PORT}}'
+          APP_BASE_URL: 'http://localhost:{{.SAAS_FRONTEND_PORT}}'
+          BASE_PATH: 'tmp/linked-saas'
+      - task: frontend:dev:saas
+        vars:
+          PORT: '{{.SAAS_FRONTEND_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.SAAS_BACKEND_PORT}}'
+          SAAS_ENV: '{{.SAAS_ENV}}'
+      - task: backend:dev:linked
+        vars:
+          PORT: '{{.APP_BACKEND_PORT}}'
+          SAAS_BASE_URL: 'http://localhost:{{.SAAS_BACKEND_PORT}}'
+      - task: frontend:dev:proprietary
+        vars:
+          PORT: '{{.APP_FRONTEND_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.APP_BACKEND_PORT}}'
+          OPEN: "true"
+      - task: linked:_ready
+        vars:
+          SAAS_BACKEND_PORT: '{{.SAAS_BACKEND_PORT}}'
+          SAAS_FRONTEND_PORT: '{{.SAAS_FRONTEND_PORT}}'
+          APP_BACKEND_PORT: '{{.APP_BACKEND_PORT}}'
+          APP_FRONTEND_PORT: '{{.APP_FRONTEND_PORT}}'
+
+  # Waits for all four to answer, then prints where they landed.
+  linked:_ready:
+    internal: true
+    cmds:
+      - cmd: |
+          n=0
+          ok=0
+          while [ "$n" -lt 150 ]; do
+            ok=1
+            for u in "http://localhost:{{.SAAS_BACKEND_PORT}}" \
+                     "http://localhost:{{.SAAS_FRONTEND_PORT}}" \
+                     "http://localhost:{{.APP_BACKEND_PORT}}" \
+                     "http://localhost:{{.APP_FRONTEND_PORT}}"; do
+              # Not -o /dev/null: Windows curl.exe treats it as a real path and exits 23.
+              curl -s -m 2 "$u" >/dev/null 2>&1 || ok=0
+            done
+            if [ "$ok" = 1 ]; then break; fi
+            n=$((n + 1))
+            # `sleep` is a binary, not a builtin, and Windows has none.
+            {{if eq OS "windows"}}powershell -NoProfile -Command "Start-Sleep -Seconds 2"{{else}}sleep 2{{end}}
+          done
+          echo ""
+          if [ "$ok" = 1 ]; then
+            echo ">> all four answering"
+          else
+            echo ">> still waiting on one or more after 5 minutes; addresses below anyway"
+          fi
+          echo ">>   self-hosted UI  http://localhost:{{.APP_FRONTEND_PORT}}/processor"
+          echo ">>   self-hosted api http://localhost:{{.APP_BACKEND_PORT}}"
+          echo ">>   saas UI         http://localhost:{{.SAAS_FRONTEND_PORT}}"
+          echo ">>   saas api        http://localhost:{{.SAAS_BACKEND_PORT}}"
+          echo ""
+
  dev:_all:
    internal: true
    vars:
@@ -180,6 +266,20 @@ tasks:
    cmds:
      - task: frontend:lint
      - task: engine:lint
+      - task: comment-lint
+
+  comment-lint:
+    desc: "Check comment quality on the lines this branch adds"
+    aliases: [comments]
+    cmds:
+      - task: pre-commit:comment-lint
+        vars: { CLI_ARGS: '{{.CLI_ARGS}}' }
+
+  comment-lint:branch:
+    desc: "Check comment quality on everything this branch adds over its base"
+    cmds:
+      - task: pre-commit:comment-lint:branch
+        vars: { BASE: '{{.BASE}}' }

  fix:
    desc: "Auto-fix all components"
@@ -3,6 +3,10 @@ bootRun {
    enabled = false
 }
 dependencies {
+    // Security-hardening utilities (zip-slip, SSRF, filename sanitization, command injection).
+    // Declared as api here so core + proprietary (which depend on common) get it transitively,
+    // keeping it off modules that don't need it (e.g. saas).
+    api 'io.github.pixee:java-security-toolkit:1.2.3'
    api "com.google.guava:guava:${guavaVersion}"
    api 'org.springframework.boot:spring-boot-starter-webmvc'
    api 'org.springframework.boot:spring-boot-starter-aspectj'
@@ -18,11 +22,14 @@ dependencies {
    api "org.apache.pdfbox:preflight:$pdfboxVersion"
    api 'com.github.junrar:junrar:8.0.0' // RAR archive support for CBR files
    api 'jakarta.servlet:jakarta.servlet-api:6.1.0'
-    api 'org.snakeyaml:snakeyaml-engine:3.0.1'
+    api 'org.snakeyaml:snakeyaml-engine:3.1.1'
    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3"
    // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
-    api 'org.simplejavamail:simple-java-mail:9.3.1'
-    api 'org.simplejavamail:outlook-module:9.3.1' // MSG file support
+    api 'org.simplejavamail:simple-java-mail:9.3.2'
+    // MSG file support; exclude commons-math3 (only HSSF/formula needs it, MSG parsing doesn't)
+    api('org.simplejavamail:outlook-module:9.3.2') {
+        exclude group: 'org.apache.commons', module: 'commons-math3'
+    }
    api 'jakarta.mail:jakarta.mail-api:2.1.5'
    runtimeOnly 'org.eclipse.angus:angus-mail:2.0.5'

@@ -36,12 +43,30 @@ dependencies {

    api "com.stirling:jpdfium:${jpdfiumVersion}"

-    // -PjpdfiumPlatforms=all|none|<csv of linux-x64,linux-arm64,darwin-x64,darwin-arm64,windows-x64>
-    // 'none' skips natives entirely (windows-arm64 builds, until JPDFium ships that platform).
-    def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'all').toString().trim()
-    def jpdfiumAllPlatforms = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']
+    // -PjpdfiumPlatforms=auto|all|none|<csv of linux-x64,linux-arm64,linux-musl-x64,linux-musl-arm64,darwin-x64,darwin-arm64,windows-x64> (windows-arm64 natives not published yet)
+    def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'auto').toString().trim()
+    def jpdfiumAllPlatforms = ['linux-x64', 'linux-arm64', 'linux-musl-x64', 'linux-musl-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']
    def jpdfiumPlatforms
-    if (jpdfiumPlatformsProp == 'all') {
+    if (jpdfiumPlatformsProp == 'auto') {
+        def osName = System.getProperty('os.name').toLowerCase()
+        def osArch = System.getProperty('os.arch').toLowerCase()
+        def isArm64 = osArch.contains('aarch64') || osArch.contains('arm64')
+        if (osName.contains('linux')) {
+            jpdfiumPlatforms = isArm64 ? ['linux-arm64'] : ['linux-x64']
+        } else if (osName.contains('mac')) {
+            jpdfiumPlatforms = isArm64 ? ['darwin-arm64'] : ['darwin-x64']
+        } else if (osName.contains('win')) {
+            if (isArm64) {
+                logger.lifecycle("JPDFium natives are not available for windows-arm64; set -PjpdfiumPlatforms=none to skip bundling natives.")
+                jpdfiumPlatforms = []
+            } else {
+                jpdfiumPlatforms = ['windows-x64']
+            }
+        } else {
+            // Fallback: bundle all platforms when host can't be determined
+            jpdfiumPlatforms = jpdfiumAllPlatforms
+        }
+    } else if (jpdfiumPlatformsProp == 'all') {
        jpdfiumPlatforms = jpdfiumAllPlatforms
    } else if (jpdfiumPlatformsProp == 'none') {
        jpdfiumPlatforms = []
@@ -51,7 +76,7 @@ dependencies {
    def jpdfiumInvalid = jpdfiumPlatforms.findAll { !jpdfiumAllPlatforms.contains(it) }
    if (jpdfiumInvalid) {
        throw new GradleException("Unknown jpdfiumPlatforms value(s): ${jpdfiumInvalid.join(', ')}. " +
-                "Valid: ${jpdfiumAllPlatforms.join(', ')}, 'all' or 'none'.")
+                "Valid: ${jpdfiumAllPlatforms.join(', ')}, 'auto', 'all' or 'none'.")
    }
    logger.lifecycle("JPDFium native platforms: ${jpdfiumPlatforms ? jpdfiumPlatforms.join(', ') : 'none'}")
    jpdfiumPlatforms.each { platform ->
@@ -48,7 +48,7 @@ public class EndpointConfiguration {
    private final ApplicationProperties applicationProperties;
    @Getter private Map<String, Boolean> endpointStatuses = new ConcurrentHashMap<>();
    private Map<String, Set<String>> endpointGroups = new ConcurrentHashMap<>();
-    private Set<String> disabledGroups = new HashSet<>();
+    private Set<String> disabledGroups = ConcurrentHashMap.newKeySet();
    private Map<String, DisableReason> endpointDisableReasons = new ConcurrentHashMap<>();
    private Map<String, DisableReason> groupDisableReasons = new ConcurrentHashMap<>();
    private Map<String, Set<String>> endpointAlternatives = new ConcurrentHashMap<>();
@@ -174,7 +174,8 @@ public class EndpointConfiguration {
                    && disabledGroups.contains(group)
                    && entry.getValue().contains(endpoint)) {
                log.debug(
-                        "isEndpointEnabled('{}') -> false (single tool group '{}' disabled, no alternatives)",
+                        "isEndpointEnabled('{}') -> false (single tool group '{}' disabled, no"
+                                + " alternatives)",
                        original,
                        group);
                return false;
@@ -333,7 +334,8 @@ public class EndpointConfiguration {
                    String.join(", ", functionallyDisabledEndpoints));
        } else if (!disabledToolGroups.isEmpty()) {
            log.info(
-                    "No endpoints disabled despite missing tools - fallback implementations available");
+                    "No endpoints disabled despite missing tools - fallback implementations"
+                            + " available");
        }
    }

@@ -237,7 +237,7 @@ public class TabulaTableParser implements TableParser {
            score -= 0.3f;
        }

-        return Math.max(0f, Math.min(1f, score));
+        return Math.clamp(score, 0f, 1f);
    }

    private Bounds tableBounds(Table table) {
@@ -85,7 +85,8 @@ public class AutoJobAspect {
                                    return joinPoint.proceed(args);
                                } catch (Throwable ex) {
                                    log.error(
-                                            "AutoJobAspect caught exception during job execution: {}",
+                                            "AutoJobAspect caught exception during job execution:"
+                                                    + " {}",
                                            ex.getMessage(),
                                            ex);
                                    // Rethrow RuntimeException as-is to preserve exception type
@@ -165,8 +166,8 @@ public class AutoJobAspect {
                                } catch (Throwable ex) {
                                    lastException = ex;
                                    log.error(
-                                            "AutoJobAspect caught exception during job execution (attempt"
-                                                    + " {}/{}): {}",
+                                            "AutoJobAspect caught exception during job execution"
+                                                    + " (attempt {}/{}): {}",
                                            currentAttempt,
                                            maxRetries,
                                            ex.getMessage(),
@@ -183,7 +184,8 @@ public class AutoJobAspect {
                                            String jobId = jobIdRef.get();
                                            if (jobId != null) {
                                                log.debug(
-                                                        "Recording retry attempt for job {} in TaskManager",
+                                                        "Recording retry attempt for job {} in"
+                                                                + " TaskManager",
                                                        jobId);
                                                // Retry info is tracked in TaskManager for REST API
                                                // access
@@ -43,9 +43,9 @@ public class ClusterConfig {
        } else if ("inprocess".equalsIgnoreCase(backplane)) {
            // enabled+inprocess only coordinates the local JVM; cross-node lookups will 410.
            log.warn(
-                    "cluster.enabled=true with backplane=inprocess - only the local"
-                            + " JVM is coordinated. Cross-node lookups and the file proxy will fail."
-                            + " Use backplane=valkey for real multi-node deployments.");
+                    "cluster.enabled=true with backplane=inprocess - only the local JVM is"
+                            + " coordinated. Cross-node lookups and the file proxy will fail. Use"
+                            + " backplane=valkey for real multi-node deployments.");
        } else {
            // Fail fast on typos like "valky" so Spring doesn't later report a cryptic
            // "no ClusterBackplane bean" - the operator-facing error names the bad value.
@@ -230,12 +230,14 @@ public class RuntimePathConfig {
                // Check if one path is a parent of the other
                if (path1.startsWith(path2)) {
                    log.warn(
-                            "Watched folder path '{}' is nested inside '{}' - this may cause duplicate processing",
+                            "Watched folder path '{}' is nested inside '{}' - this may cause"
+                                    + " duplicate processing",
                            path1,
                            path2);
                } else if (path2.startsWith(path1)) {
                    log.warn(
-                            "Watched folder path '{}' is nested inside '{}' - this may cause duplicate processing",
+                            "Watched folder path '{}' is nested inside '{}' - this may cause"
+                                    + " duplicate processing",
                            path2,
                            path1);
                }
@@ -253,21 +255,24 @@ public class RuntimePathConfig {
                // Check if watched folder is same as finished folder
                if (watchedPath.equals(finishedPath)) {
                    log.error(
-                            "CRITICAL: Watched folder '{}' is the same as finished folder '{}' - this will cause processing loops!",
+                            "CRITICAL: Watched folder '{}' is the same as finished folder '{}' -"
+                                    + " this will cause processing loops!",
                            watchedPath,
                            finishedPath);
                }
                // Check if watched folder contains finished folder
                else if (finishedPath.startsWith(watchedPath)) {
                    log.warn(
-                            "Finished folder '{}' is nested inside watched folder '{}' - this may cause issues",
+                            "Finished folder '{}' is nested inside watched folder '{}' - this may"
+                                    + " cause issues",
                            finishedPath,
                            watchedPath);
                }
                // Check if finished folder contains watched folder
                else if (watchedPath.startsWith(finishedPath)) {
                    log.error(
-                            "CRITICAL: Watched folder '{}' is nested inside finished folder '{}' - this will cause processing loops!",
+                            "CRITICAL: Watched folder '{}' is nested inside finished folder '{}' -"
+                                    + " this will cause processing loops!",
                            watchedPath,
                            finishedPath);
                }
@@ -295,15 +300,17 @@ public class RuntimePathConfig {
                // Warn if manual endpoint count doesn't match sessionLimit
                if (configured.size() != sessionLimit) {
                    log.warn(
-                            "Manual UNO endpoint count ({}) differs from libreOfficeSessionLimit ({}). "
-                                    + "Concurrency will be limited by endpoint count, not sessionLimit.",
+                            "Manual UNO endpoint count ({}) differs from libreOfficeSessionLimit"
+                                    + " ({}). Concurrency will be limited by endpoint count, not"
+                                    + " sessionLimit.",
                            configured.size(),
                            sessionLimit);
                }
                return configured;
            }
            log.warn(
-                    "autoUnoServer disabled but no unoServerEndpoints configured; defaulting to 127.0.0.1:2003.");
+                    "autoUnoServer disabled but no unoServerEndpoints configured; defaulting to"
+                            + " 127.0.0.1:2003.");
            return Collections.singletonList(
                    new ApplicationProperties.ProcessExecutor.UnoServerEndpoint());
        }
@@ -144,7 +144,8 @@ public class ApplicationProperties {
                                    sizeInMB);
                        } else {
                            log.warn(
-                                    "SYSTEM_MAXFILESIZE value {} is out of valid range (1-999), ignoring",
+                                    "SYSTEM_MAXFILESIZE value {} is out of valid range (1-999),"
+                                            + " ignoring",
                                    sizeInMB);
                        }
                    } catch (NumberFormatException e) {
@@ -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;
    }
 }
@@ -24,7 +24,8 @@ public class PDFFile {

    @Schema(
            description =
-                    "File ID for server-side files (can be used instead of fileInput if job was previously done on file in async mode)")
+                    "File ID for server-side files (can be used instead of fileInput if job was"
+                            + " previously done on file in async mode)")
    private String fileId;

    @AssertTrue(message = "Either fileInput or fileId must be provided")
@@ -209,7 +209,8 @@ public class ResourceMonitor {
                    return (double) m.invoke(osMXBean);
                } catch (Exception e2) {
                    log.trace(
-                            "Could not get CPU load through reflection, assuming moderate load (0.5)");
+                            "Could not get CPU load through reflection, assuming moderate load"
+                                    + " (0.5)");
                    return 0.5;
                }
            }
@@ -167,7 +167,8 @@ public class TempFileCleanupService {
                || unregisteredDeletedCount > 0
                || directoriesDeletedCount > 0) {
            log.info(
-                    "Scheduled cleanup complete. Deleted {} registered files, {} unregistered files, {} directories",
+                    "Scheduled cleanup complete. Deleted {} registered files, {} unregistered"
+                            + " files, {} directories",
                    registeredDeletedCount,
                    unregisteredDeletedCount,
                    directoriesDeletedCount);
@@ -252,7 +253,8 @@ public class TempFileCleanupService {
                                                dirDeletedCount.incrementAndGet();
                                                if (log.isDebugEnabled()) {
                                                    log.debug(
-                                                            "Deleted temp file during {} cleanup: {}",
+                                                            "Deleted temp file during {} cleanup:"
+                                                                    + " {}",
                                                            phase,
                                                            path);
                                                }
@@ -41,7 +41,8 @@ public class AttachmentUtils {
                viewerPrefs.setBoolean(COSName.getPDFName("DisplayDocTitle"), true);

                log.info(
-                        "Set PDF PageMode to UseAttachments to automatically show attachments pane");
+                        "Set PDF PageMode to UseAttachments to automatically show attachments"
+                                + " pane");
            }
        } catch (Exception e) {
            log.error("Failed to set catalog viewer preferences for attachments", e);
@@ -342,26 +342,26 @@ public class EmlProcessingUtils {

    private String getFallbackStyles() {
        return """
-            /* Minimal fallback - main CSS resource failed to load */
-            body {
-                font-family: var(--font-family, Helvetica, sans-serif);
-                font-size: var(--font-size, 12px);
-                line-height: var(--line-height, 1.4);
-                color: var(--text-color, #202124);
-                margin: 0;
-                padding: 20px;
-                word-wrap: break-word;
-            }
-            .email-container { max-width: 100%; }
-            .email-header { border-bottom: 1px solid #ccc; margin-bottom: 16px; padding-bottom: 12px; }
-            .email-header h1 { margin: 0 0 8px 0; font-size: 18px; }
-            .email-meta { font-size: 12px; color: #666; }
-            .email-body { line-height: 1.6; }
-            .attachment-section { margin-top: 20px; padding: 12px; background: #f5f5f5; border-radius: 4px; }
-            .attachment-item { padding: 6px 0; border-bottom: 1px solid #ddd; }
-            .no-content { padding: 20px; text-align: center; color: #888; font-style: italic; }
-            img { max-width: 100%; height: auto; }
-            """;
+        /* Minimal fallback - main CSS resource failed to load */
+        body {
+            font-family: var(--font-family, Helvetica, sans-serif);
+            font-size: var(--font-size, 12px);
+            line-height: var(--line-height, 1.4);
+            color: var(--text-color, #202124);
+            margin: 0;
+            padding: 20px;
+            word-wrap: break-word;
+        }
+        .email-container { max-width: 100%; }
+        .email-header { border-bottom: 1px solid #ccc; margin-bottom: 16px; padding-bottom: 12px; }
+        .email-header h1 { margin: 0 0 8px 0; font-size: 18px; }
+        .email-meta { font-size: 12px; color: #666; }
+        .email-body { line-height: 1.6; }
+        .attachment-section { margin-top: 20px; padding: 12px; background: #f5f5f5; border-radius: 4px; }
+        .attachment-item { padding: 6px 0; border-bottom: 1px solid #ddd; }
+        .no-content { padding: 20px; text-align: center; color: #888; font-style: italic; }
+        img { max-width: 100%; height: auto; }
+        """;
    }

    private void appendAttachmentsSection(
@@ -290,7 +290,8 @@ public class ExceptionUtils {
        // Additional safety check: warn about very large images (> 1GB estimated)
        if (estimatedBytes > 1024L * 1024 * 1024) {
            log.warn(
-                    "Page {} will create a very large image: {}x{} pixels (~{} MB) at {} DPI. This may cause memory issues.",
+                    "Page {} will create a very large image: {}x{} pixels (~{} MB) at {} DPI. This"
+                            + " may cause memory issues.",
                    pageNumber,
                    widthInPixels,
                    heightInPixels,
@@ -394,7 +395,8 @@ public class ExceptionUtils {
            message = getMessage(contextKey, defaultMsg, context);
        } else {
            message =
-                    "PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF' feature first to fix the file before proceeding with this operation.";
+                    "PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF'"
+                        + " feature first to fix the file before proceeding with this operation.";
        }

        return new PdfCorruptedException(message, cause, ErrorCode.PDF_CORRUPTED.getCode());
@@ -1119,19 +1121,25 @@ public class ExceptionUtils {
        PDF_CORRUPTED(
                "E001",
                "error.pdfCorrupted",
-                "PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF' feature first to fix the file before proceeding with this operation."),
+                "PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF'"
+                        + " feature first to fix the file before proceeding with this operation."),
        PDF_MULTIPLE_CORRUPTED(
                "E002",
                "error.multiplePdfCorrupted",
-                "One or more PDF files appear to be corrupted or damaged. Please try using the 'Repair PDF' feature on each file first before attempting to merge them."),
+                "One or more PDF files appear to be corrupted or damaged. Please try using the"
+                    + " 'Repair PDF' feature on each file first before attempting to merge them."),
        PDF_ENCRYPTION(
                "E003",
                "error.pdfEncryption",
-                "The PDF appears to have corrupted encryption data. This can happen when the PDF was created with incompatible encryption methods. Please try using the 'Repair PDF' feature first, or contact the document creator for a new copy."),
+                "The PDF appears to have corrupted encryption data. This can happen when the PDF"
+                        + " was created with incompatible encryption methods. Please try using the"
+                        + " 'Repair PDF' feature first, or contact the document creator for a new"
+                        + " copy."),
        PDF_PASSWORD(
                "E004",
                "error.pdfPassword",
-                "The PDF Document is passworded and either the password was not provided or was incorrect"),
+                "The PDF Document is passworded and either the password was not provided or was"
+                        + " incorrect"),
        PDF_NO_PAGES("E005", "error.pdfNoPages", "PDF file contains no pages"),
        PDF_NOT_PDF("E006", "error.notPdfFile", "File must be in PDF format"),

@@ -1139,20 +1147,25 @@ public class ExceptionUtils {
        CBR_INVALID_FORMAT(
                "E010",
                "error.cbrInvalidFormat",
-                "Invalid or corrupted CBR/RAR archive. The file may be corrupted, use an unsupported RAR format (RAR5+), encrypted, or may not be a valid RAR archive."),
+                "Invalid or corrupted CBR/RAR archive. The file may be corrupted, use an"
+                        + " unsupported RAR format (RAR5+), encrypted, or may not be a valid RAR"
+                        + " archive."),
        CBR_NO_IMAGES(
                "E012",
                "error.cbrNoImages",
-                "No valid images found in the CBR file. The archive may be empty, or all images may be corrupted or in unsupported formats."),
+                "No valid images found in the CBR file. The archive may be empty, or all images may"
+                        + " be corrupted or in unsupported formats."),
        CBR_NOT_CBR("E014", "error.notCbrFile", "File must be a CBR or RAR archive"),
        CBZ_INVALID_FORMAT(
                "E015",
                "error.cbzInvalidFormat",
-                "Invalid or corrupted CBZ/ZIP archive. The file may be empty, corrupted, or may not be a valid ZIP archive."),
+                "Invalid or corrupted CBZ/ZIP archive. The file may be empty, corrupted, or may not"
+                        + " be a valid ZIP archive."),
        CBZ_NO_IMAGES(
                "E016",
                "error.cbzNoImages",
-                "No valid images found in the CBZ file. The archive may be empty, or all images may be corrupted or in unsupported formats."),
+                "No valid images found in the CBZ file. The archive may be empty, or all images may"
+                        + " be corrupted or in unsupported formats."),
        CBZ_NOT_CBZ("E018", "error.notCbzFile", "File must be a CBZ or ZIP archive"),

        // EML errors
@@ -1205,7 +1218,8 @@ public class ExceptionUtils {
        FFMPEG_REQUIRED(
                "E063",
                "error.ffmpegRequired",
-                "FFmpeg must be installed to convert PDFs to video. Install FFmpeg and ensure it is available on the system PATH."),
+                "FFmpeg must be installed to convert PDFs to video. Install FFmpeg and ensure it is"
+                        + " available on the system PATH."),

        // Validation errors
        INVALID_ARGUMENT("E070", "error.invalidArgument", "Invalid argument ''{0}'': {1}"),
@@ -1221,7 +1235,10 @@ public class ExceptionUtils {
        OUT_OF_MEMORY_DPI(
                "E081",
                "error.outOfMemoryDpi",
-                "Out of memory or image-too-large error while rendering PDF page {0} at {1} DPI. This can occur when the resulting image exceeds Java's array/memory limits (e.g., NegativeArraySizeException). Please use a lower DPI value (recommended: 150 or less) or process the document in smaller chunks.");
+                "Out of memory or image-too-large error while rendering PDF page {0} at {1} DPI."
+                    + " This can occur when the resulting image exceeds Java's array/memory limits"
+                    + " (e.g., NegativeArraySizeException). Please use a lower DPI value"
+                    + " (recommended: 150 or less) or process the document in smaller chunks.");

        private final String code;
        private final String messageKey;
@@ -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(
@@ -392,9 +392,9 @@ public class PdfUtils {
                            && e.getMessage().contains("Maximum size of image exceeded")) {
                        throw ExceptionUtils.createIllegalArgumentException(
                                "error.pageTooBigFor300Dpi",
-                                "PDF page {0} is too large to render at 300 DPI. The resulting image"
-                                        + " would exceed Java's maximum array size. Please use a lower DPI"
-                                        + " value for PDF-to-image conversion.",
+                                "PDF page {0} is too large to render at 300 DPI. The resulting"
+                                    + " image would exceed Java's maximum array size. Please use a"
+                                    + " lower DPI value for PDF-to-image conversion.",
                                pageIndex + 1);
                    }
                    throw e;
@@ -253,7 +253,8 @@ public class ProcessExecutor {
                                            }
                                        } catch (InterruptedIOException e) {
                                            log.warn(
-                                                    "Error reader thread was interrupted due to timeout.");
+                                                    "Error reader thread was interrupted due to"
+                                                            + " timeout.");
                                        } catch (IOException e) {
                                            log.error("exception", e);
                                        }
@@ -278,7 +279,8 @@ public class ProcessExecutor {
                                            }
                                        } catch (InterruptedIOException e) {
                                            log.warn(
-                                                    "Error reader thread was interrupted due to timeout.");
+                                                    "Error reader thread was interrupted due to"
+                                                            + " timeout.");
                                        } catch (IOException e) {
                                            log.error("exception", e);
                                        }
@@ -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) {
@@ -15,7 +15,8 @@ public class StringToMapPropertyEditor extends PropertyEditorSupport {
    @Override
    public void setAsText(String text) throws IllegalArgumentException {
        try {
-            TypeReference<HashMap<String, String>> typeRef = new TypeReference<>() {};
+            TypeReference<HashMap<String, String>> typeRef =
+                    new TypeReference<HashMap<String, String>>() {};
            Map<String, String> map = objectMapper.readValue(text, typeRef);
            setValue(map);
        } catch (Exception e) {
@@ -237,6 +237,7 @@ class ApplicationPropertiesLogicTest {

        assertTrue(
                oauth2.isValid(oneBlank, "scopes"),
-                "Dokumentiert aktuelles Verhalten: nicht-leere Liste gilt als gültig, auch wenn Element leer/blank ist");
+                "Dokumentiert aktuelles Verhalten: nicht-leere Liste gilt als gültig, auch wenn"
+                        + " Element leer/blank ist");
    }
 }
@@ -130,7 +130,8 @@ class PdfMarkdownConverterTest {
        if (similarity < THRESHOLD) {
            fail(
                    String.format(
-                            "Markdown output differs from golden file '%s' by %.1f%% (threshold %.0f%%):%n%s",
+                            "Markdown output differs from golden file '%s' by %.1f%% (threshold"
+                                    + " %.0f%%):%n%s",
                            mdName,
                            (1.0 - similarity) * 100,
                            (1.0 - THRESHOLD) * 100,
@@ -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");
+        }
+    }
+}
@@ -60,10 +60,10 @@ class CustomHtmlSanitizerTest {
                        new String[] {"<p>", "<strong>", "<em>"}),
                Arguments.of(
                        "<p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>,"
-                                + " <em>emphasis</em>, <strong>strong</strong>,"
-                                + " <strike>strikethrough</strike>, <s>strike</s>,"
-                                + " <sub>subscript</sub>, <sup>superscript</sup>, <tt>teletype</tt>,"
-                                + " <code>code</code>, <big>big</big>, <small>small</small>.</p>",
+                            + " <em>emphasis</em>, <strong>strong</strong>,"
+                            + " <strike>strikethrough</strike>, <s>strike</s>,"
+                            + " <sub>subscript</sub>, <sup>superscript</sup>, <tt>teletype</tt>,"
+                            + " <code>code</code>, <big>big</big>, <small>small</small>.</p>",
                        new String[] {
                            "<b>bold</b>",
                            "<i>italic</i>",
@@ -271,8 +271,8 @@ class CustomHtmlSanitizerTest {
        // Arrange
        String htmlWithObjects =
                "<p>Safe content</p><object data=\"data.swf\""
-                        + " type=\"application/x-shockwave-flash\"></object><embed src=\"embed.swf\""
-                        + " type=\"application/x-shockwave-flash\">";
+                    + " type=\"application/x-shockwave-flash\"></object><embed src=\"embed.swf\""
+                    + " type=\"application/x-shockwave-flash\">";

        // Act
        String sanitizedHtml = customHtmlSanitizer.sanitize(htmlWithObjects);
@@ -309,11 +309,11 @@ class CustomHtmlSanitizerTest {
        // Arrange
        String complexHtml =
                "<div class=\"container\">  <h1 style=\"color: blue;\">Welcome</h1>  <p>This is a"
-                        + " <strong>test</strong> with <a href=\"https://example.com\">link</a>.</p> "
-                        + " <table>    <tr><th>Name</th><th>Value</th></tr>    <tr><td>Item"
-                        + " 1</td><td>100</td></tr>  </table>  <img src=\"image.jpg\" alt=\"Test"
-                        + " image\">  <script>alert('XSS');</script>  <iframe"
-                        + " src=\"https://evil.com\"></iframe></div>";
+                    + " <strong>test</strong> with <a href=\"https://example.com\">link</a>.</p> "
+                    + " <table>    <tr><th>Name</th><th>Value</th></tr>    <tr><td>Item"
+                    + " 1</td><td>100</td></tr>  </table>  <img src=\"image.jpg\" alt=\"Test"
+                    + " image\">  <script>alert('XSS');</script>  <iframe"
+                    + " src=\"https://evil.com\"></iframe></div>";

        // Act
        String sanitizedHtml = customHtmlSanitizer.sanitize(complexHtml);
@@ -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));
+        }
+    }
+}
@@ -120,10 +120,10 @@ class EmlToPdfTest {
        void parseHtmlEmailWithStyling() throws IOException {
            String htmlBody =
                    "<html><head><style>.header{color:blue;font-weight:bold;}"
-                            + ".content{margin:10px;}.footer{font-size:12px;}</style></head>"
-                            + "<body><div class=\"header\">Important Notice</div>"
-                            + "<div class=\"content\">This is <strong>HTML content</strong> with styling.</div>"
-                            + "<div class=\"footer\">Best regards</div></body></html>";
+                        + ".content{margin:10px;}.footer{font-size:12px;}</style></head><body><div"
+                        + " class=\"header\">Important Notice</div><div class=\"content\">This is"
+                        + " <strong>HTML content</strong> with styling.</div><div"
+                        + " class=\"footer\">Best regards</div></body></html>";

            String emlContent =
                    createHtmlEmail(
@@ -286,11 +286,13 @@ class EmlToPdfTest {
        @DisplayName("Should handle complex nested HTML structures")
        void handleComplexNestedHtml() throws IOException {
            String complexHtml =
-                    "<html><head><title>Complex Email</title></head><body>"
-                            + "<div class=\"container\"><header><h1>Email Header</h1></header><main><section>"
-                            + "<p>Paragraph with <a href=\"https://example.com\">link</a></p><ul>"
-                            + "<li>List item 1</li><li>List item 2 with <em>emphasis</em></li></ul><table>"
-                            + "<tr><td>Cell 1</td><td>Cell 2</td></tr><tr><td>Cell 3</td><td>Cell 4</td></tr>"
+                    "<html><head><title>Complex Email</title></head><body><div"
+                            + " class=\"container\"><header><h1>Email"
+                            + " Header</h1></header><main><section><p>Paragraph with <a"
+                            + " href=\"https://example.com\">link</a></p><ul><li>List item"
+                            + " 1</li><li>List item 2 with"
+                            + " <em>emphasis</em></li></ul><table><tr><td>Cell 1</td><td>Cell"
+                            + " 2</td></tr><tr><td>Cell 3</td><td>Cell 4</td></tr>"
                            + "</table></section></main></div></body></html>";

            String emlContent =
@@ -346,7 +348,8 @@ class EmlToPdfTest {
                    This line breaks header format
                    Content-Type: text/plain

-                    Body content""";
+                    Body content\
+                    """;

            byte[] emlBytes = malformedEml.getBytes(StandardCharsets.UTF_8);
            EmlToPdfRequest request = createBasicRequest();
@@ -781,7 +784,13 @@ class EmlToPdfTest {
            String from, String to, String subject, String body, String charset) {
        return String.format(
                Locale.ROOT,
-                "From: %s\nTo: %s\nSubject: %s\nDate: %s\nContent-Type: text/plain; charset=%s\nContent-Transfer-Encoding: 8bit\n\n%s",
+                "From: %s\n"
+                        + "To: %s\n"
+                        + "Subject: %s\n"
+                        + "Date: %s\n"
+                        + "Content-Type: text/plain; charset=%s\n"
+                        + "Content-Transfer-Encoding: 8bit\n\n"
+                        + "%s",
                from,
                to,
                subject,
@@ -793,7 +802,11 @@ class EmlToPdfTest {
    private String createEmailWithCustomHeaders() {
        return String.format(
                Locale.ROOT,
-                "From: sender@example.com\nDate: %s\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n\n%s",
+                "From: sender@example.com\n"
+                        + "Date: %s\n"
+                        + "Content-Type: text/plain; charset=UTF-8\n"
+                        + "Content-Transfer-Encoding: 8bit\n\n"
+                        + "%s",
                getTimestamp(),
                "This is an email body with some headers missing.");
    }
@@ -801,7 +814,13 @@ class EmlToPdfTest {
    private String createHtmlEmail(String from, String to, String subject, String htmlBody) {
        return String.format(
                Locale.ROOT,
-                "From: %s\nTo: %s\nSubject: %s\nDate: %s\nContent-Type: text/html; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n\n%s",
+                "From: %s\n"
+                        + "To: %s\n"
+                        + "Subject: %s\n"
+                        + "Date: %s\n"
+                        + "Content-Type: text/html; charset=UTF-8\n"
+                        + "Content-Transfer-Encoding: 8bit\n\n"
+                        + "%s",
                from,
                to,
                subject,
@@ -823,26 +842,27 @@ class EmlToPdfTest {
        return String.format(
                Locale.ROOT,
                """
-                    From: %s
-                    To: %s
-                    Subject: %s
-                    Date: %s
-                    Content-Type: multipart/mixed; boundary="%s"
+                From: %s
+                To: %s
+                Subject: %s
+                Date: %s
+                Content-Type: multipart/mixed; boundary="%s"

-                    --%s
-                    Content-Type: text/plain; charset=UTF-8
-                    Content-Transfer-Encoding: 8bit
+                --%s
+                Content-Type: text/plain; charset=UTF-8
+                Content-Transfer-Encoding: 8bit

-                    %s
+                %s

-                    --%s
-                    Content-Type: text/plain; charset=UTF-8
-                    Content-Disposition: attachment; filename="%s"
-                    Content-Transfer-Encoding: base64
+                --%s
+                Content-Type: text/plain; charset=UTF-8
+                Content-Disposition: attachment; filename="%s"
+                Content-Transfer-Encoding: base64

-                    %s
+                %s

-                    --%s--""",
+                --%s--\
+                """,
                from,
                to,
                subject,
@@ -863,26 +883,27 @@ class EmlToPdfTest {
        return String.format(
                Locale.ROOT,
                """
-                    From: %s
-                    To: %s
-                    Subject: %s
-                    Date: %s
-                    Content-Type: multipart/mixed; boundary="%s"
+                From: %s
+                To: %s
+                Subject: %s
+                Date: %s
+                Content-Type: multipart/mixed; boundary="%s"

-                    --%s
-                    Content-Type: text/plain; charset=UTF-8
-                    Content-Transfer-Encoding: 8bit
+                --%s
+                Content-Type: text/plain; charset=UTF-8
+                Content-Transfer-Encoding: 8bit

-                    %s
+                %s

-                    --%s
-                    Content-Type: message/rfc822; name="%s"
-                    Content-Disposition: attachment; filename="%s"
-                    Content-Transfer-Encoding: base64
+                --%s
+                Content-Type: message/rfc822; name="%s"
+                Content-Disposition: attachment; filename="%s"
+                Content-Transfer-Encoding: base64

-                    %s
+                %s

-                    --%s--""",
+                --%s--\
+                """,
                "outer@example.com",
                "outer_recipient@example.com",
                "Fwd: Inner Email Subject",
@@ -902,26 +923,27 @@ class EmlToPdfTest {
        return String.format(
                Locale.ROOT,
                """
-                    From: %s
-                    To: %s
-                    Subject: %s
-                    Date: %s
-                    MIME-Version: 1.0
-                    Content-Type: multipart/alternative; boundary="%s"
+                From: %s
+                To: %s
+                Subject: %s
+                Date: %s
+                MIME-Version: 1.0
+                Content-Type: multipart/alternative; boundary="%s"

-                    --%s
-                    Content-Type: text/plain; charset=UTF-8
-                    Content-Transfer-Encoding: 7bit
+                --%s
+                Content-Type: text/plain; charset=UTF-8
+                Content-Transfer-Encoding: 7bit

-                    %s
+                %s

-                    --%s
-                    Content-Type: text/html; charset=UTF-8
-                    Content-Transfer-Encoding: 7bit
+                --%s
+                Content-Type: text/html; charset=UTF-8
+                Content-Transfer-Encoding: 7bit

-                    %s
+                %s

-                    --%s--""",
+                --%s--\
+                """,
                "sender@example.com",
                "receiver@example.com",
                "Multipart/Alternative Test",
@@ -937,7 +959,14 @@ class EmlToPdfTest {
    private String createQuotedPrintableEmail() {
        return String.format(
                Locale.ROOT,
-                "From: %s\nTo: %s\nSubject: %s\nDate: %s\nMIME-Version: 1.0\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: quoted-printable\n\n%s",
+                "From: %s\n"
+                        + "To: %s\n"
+                        + "Subject: %s\n"
+                        + "Date: %s\n"
+                        + "MIME-Version: 1.0\n"
+                        + "Content-Type: text/plain; charset=UTF-8\n"
+                        + "Content-Transfer-Encoding: quoted-printable\n\n"
+                        + "%s",
                "sender@example.com",
                "recipient@example.com",
                "Quoted-Printable Test",
@@ -950,7 +979,14 @@ class EmlToPdfTest {
                Base64.getEncoder().encodeToString(body.getBytes(StandardCharsets.UTF_8));
        return String.format(
                Locale.ROOT,
-                "From: %s\nTo: %s\nSubject: %s\nDate: %s\nMIME-Version: 1.0\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: base64\n\n%s",
+                "From: %s\n"
+                        + "To: %s\n"
+                        + "Subject: %s\n"
+                        + "Date: %s\n"
+                        + "MIME-Version: 1.0\n"
+                        + "Content-Type: text/plain; charset=UTF-8\n"
+                        + "Content-Transfer-Encoding: base64\n\n"
+                        + "%s",
                "sender@example.com",
                "recipient@example.com",
                "Base64 Test",
@@ -963,27 +999,28 @@ class EmlToPdfTest {
        return String.format(
                Locale.ROOT,
                """
-                    From: %s
-                    To: %s
-                    Subject: %s
-                    Date: %s
-                    Content-Type: multipart/related; boundary="%s"
+                From: %s
+                To: %s
+                Subject: %s
+                Date: %s
+                Content-Type: multipart/related; boundary="%s"

-                    --%s
-                    Content-Type: text/html; charset=UTF-8
-                    Content-Transfer-Encoding: 8bit
+                --%s
+                Content-Type: text/html; charset=UTF-8
+                Content-Transfer-Encoding: 8bit

-                    %s
+                %s

-                    --%s
-                    Content-Type: image/png
-                    Content-Transfer-Encoding: base64
-                    Content-ID: <%s>
-                    Content-Disposition: inline; filename="image.png"
+                --%s
+                Content-Type: image/png
+                Content-Transfer-Encoding: base64
+                Content-ID: <%s>
+                Content-Disposition: inline; filename="image.png"

-                    %s
+                %s

-                    --%s--""",
+                --%s--\
+                """,
                "sender@example.com",
                "receiver@example.com",
                "Inline Image Test",
@@ -1008,39 +1045,40 @@ class EmlToPdfTest {
        return String.format(
                Locale.ROOT,
                """
-                    From: %s
-                    To: %s
-                    Subject: %s
-                    Date: %s
-                    Content-Type: multipart/mixed; boundary="%s"
+                From: %s
+                To: %s
+                Subject: %s
+                Date: %s
+                Content-Type: multipart/mixed; boundary="%s"

-                    --%s
-                    Content-Type: multipart/related; boundary="related-%s"
+                --%s
+                Content-Type: multipart/related; boundary="related-%s"

-                    --related-%s
-                    Content-Type: text/html; charset=UTF-8
-                    Content-Transfer-Encoding: 8bit
+                --related-%s
+                Content-Type: text/html; charset=UTF-8
+                Content-Transfer-Encoding: 8bit

-                    %s
+                %s

-                    --related-%s
-                    Content-Type: image/png
-                    Content-Transfer-Encoding: base64
-                    Content-ID: <%s>
-                    Content-Disposition: inline; filename="image.png"
+                --related-%s
+                Content-Type: image/png
+                Content-Transfer-Encoding: base64
+                Content-ID: <%s>
+                Content-Disposition: inline; filename="image.png"

-                    %s
+                %s

-                    --related-%s--
+                --related-%s--

-                    --%s
-                    Content-Type: text/plain; charset=UTF-8
-                    Content-Disposition: attachment; filename="%s"
-                    Content-Transfer-Encoding: base64
+                --%s
+                Content-Type: text/plain; charset=UTF-8
+                Content-Disposition: attachment; filename="%s"
+                Content-Transfer-Encoding: base64

-                    %s
+                %s

-                    --%s--""",
+                --%s--\
+                """,
                "sender@example.com",
                "receiver@example.com",
                "Mixed Attachments Test",
@@ -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");
+        }
+    }
+}
@@ -31,21 +31,22 @@ class OfficeDocumentSanitizerTest {
    private static final String INTERNAL_TARGET = "media/image1.png";

    private static final String DOCX_RELS =
-            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-                    + "<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">"
-                    + "<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
-                    + " Target=\""
+            "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships"
+                + " xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"><Relationship"
+                + " Id=\"rId1\""
+                + " Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
+                + " Target=\""
                    + EXTERNAL_URL
-                    + "\" TargetMode=\"External\"/>"
-                    + "<Relationship Id=\"rId2\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
+                    + "\" TargetMode=\"External\"/><Relationship Id=\"rId2\""
+                    + " Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
                    + " Target=\""
                    + INTERNAL_TARGET
                    + "\"/>"
                    + "</Relationships>";

    private static final String DOCX_DOCUMENT =
-            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-                    + "<w:document xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\">"
+            "<?xml version=\"1.0\" encoding=\"UTF-8\"?><w:document"
+                    + " xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\">"
                    + "<w:body><w:p/></w:body></w:document>";

    private static final String ODF_CONTENT_EXTERNAL =
@@ -57,8 +58,8 @@ class OfficeDocumentSanitizerTest {
                    + "<office:body><office:text>"
                    + "<draw:frame><draw:image xlink:href=\""
                    + EXTERNAL_URL
-                    + "\" xlink:type=\"simple\"/></draw:frame>"
-                    + "<draw:frame><draw:image xlink:href=\"Pictures/image1.png\" xlink:type=\"simple\"/></draw:frame>"
+                    + "\" xlink:type=\"simple\"/></draw:frame><draw:frame><draw:image"
+                    + " xlink:href=\"Pictures/image1.png\" xlink:type=\"simple\"/></draw:frame>"
                    + "</office:text></office:body></office:document-content>";

    private SsrfProtectionService ssrfProtectionService;
@@ -113,10 +114,11 @@ class OfficeDocumentSanitizerTest {
    @Test
    void sanitize_pptxExternalImageRelStripped() throws IOException {
        String pptxRels =
-                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-                        + "<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">"
-                        + "<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
-                        + " Target=\""
+                "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships"
+                    + " xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"><Relationship"
+                    + " Id=\"rId1\""
+                    + " Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
+                    + " Target=\""
                        + EXTERNAL_URL
                        + "\" TargetMode=\"External\"/>"
                        + "</Relationships>";
@@ -135,10 +137,11 @@ class OfficeDocumentSanitizerTest {
    @Test
    void sanitize_xlsxExternalImageRelStripped() throws IOException {
        String xlsxRels =
-                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-                        + "<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">"
-                        + "<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
-                        + " Target=\""
+                "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships"
+                    + " xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"><Relationship"
+                    + " Id=\"rId1\""
+                    + " Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
+                    + " Target=\""
                        + EXTERNAL_URL
                        + "\" TargetMode=\"External\"/>"
                        + "</Relationships>";
@@ -162,7 +165,7 @@ class OfficeDocumentSanitizerTest {
        entries.put("content.xml", ODF_CONTENT_EXTERNAL.getBytes(StandardCharsets.UTF_8));
        String manifestXml =
                "<?xml version=\"1.0\"?><manifest:manifest"
-                        + " xmlns:manifest=\"urn:oasis:names:tc:opendocument:xmlns:manifest:1.0\"/>";
+                    + " xmlns:manifest=\"urn:oasis:names:tc:opendocument:xmlns:manifest:1.0\"/>";
        entries.put("META-INF/manifest.xml", manifestXml.getBytes(StandardCharsets.UTF_8));
        byte[] odt = zip(entries);

@@ -294,11 +297,11 @@ class OfficeDocumentSanitizerTest {
    @Test
    void sanitize_internalLinksKeptWhenNoExternalPresent() throws IOException {
        String internalOnlyRels =
-                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
-                        + "<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">"
-                        + "<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
-                        + " Target=\"media/image1.png\"/>"
-                        + "</Relationships>";
+                "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships"
+                    + " xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"><Relationship"
+                    + " Id=\"rId1\""
+                    + " Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image\""
+                    + " Target=\"media/image1.png\"/></Relationships>";
        Map<String, byte[]> entries = new LinkedHashMap<>();
        entries.put(
                "word/_rels/document.xml.rels", internalOnlyRels.getBytes(StandardCharsets.UTF_8));
@@ -249,7 +249,8 @@ class ProcessExecutorGapTest {

        @Test
        @DisplayName(
-                "injects --host/--port after the executable, defaults omit host-location and protocol")
+                "injects --host/--port after the executable, defaults omit host-location and"
+                        + " protocol")
        void injectsHostAndPortWithDefaults() throws Exception {
            List<String> command = List.of("unoconvert", "in.docx", "out.pdf");
            ApplicationProperties.ProcessExecutor.UnoServerEndpoint ep =
@@ -113,6 +113,16 @@ class RequestUriUtilsTest {
        assertTrue(RequestUriUtils.isFrontendRoute("", "/split-pdf"));
    }

+    @Test
+    void testIsFrontendRoute_editorRouteOwnedByFrontend() {
+        // /editor (and its tool routes) is an SPA route: a direct-nav/refresh must
+        // serve index.html, not the auth filter's 302-to-/login. Regression test for
+        // the editor moving from / to /editor, whose refresh bounced processor users
+        // to the processor because the redirect dropped the return path.
+        assertTrue(RequestUriUtils.isFrontendRoute("", "/editor"));
+        assertTrue(RequestUriUtils.isFrontendRoute("/app", "/app/editor"));
+    }
+
    @Test
    void testIsFrontendRoute_filesRouteOwnedByFrontend() {
        // /files and /files/<folder-uuid> are FileManagerView routes - they
@@ -206,12 +216,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 +258,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", ""));
+    }
 }
@@ -38,7 +38,8 @@ class SvgSanitizerTest {
    @Test
    void testSanitize_removesScriptElement() throws IOException {
        String svg =
-                "<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert('xss')</script><circle r=\"10\"/></svg>";
+                "<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert('xss')</script><circle"
+                        + " r=\"10\"/></svg>";
        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
        String output = new String(result, StandardCharsets.UTF_8);
        assertFalse(output.contains("script"));
@@ -48,7 +49,8 @@ class SvgSanitizerTest {
    @Test
    void testSanitize_removesEventHandler() throws IOException {
        String svg =
-                "<svg xmlns=\"http://www.w3.org/2000/svg\"><circle r=\"10\" onclick=\"alert('xss')\"/></svg>";
+                "<svg xmlns=\"http://www.w3.org/2000/svg\"><circle r=\"10\""
+                        + " onclick=\"alert('xss')\"/></svg>";
        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
        String output = new String(result, StandardCharsets.UTF_8);
        assertFalse(output.contains("onclick"));
@@ -57,7 +59,8 @@ class SvgSanitizerTest {
    @Test
    void testSanitize_removesJavascriptUrl() throws IOException {
        String svg =
-                "<svg xmlns=\"http://www.w3.org/2000/svg\"><a href=\"javascript:alert('xss')\"><circle r=\"10\"/></a></svg>";
+                "<svg xmlns=\"http://www.w3.org/2000/svg\"><a"
+                        + " href=\"javascript:alert('xss')\"><circle r=\"10\"/></a></svg>";
        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
        String output = new String(result, StandardCharsets.UTF_8);
        assertFalse(output.contains("javascript"));
@@ -86,7 +89,8 @@ class SvgSanitizerTest {
    @Test
    void testSanitize_removesForeignObject() throws IOException {
        String svg =
-                "<svg xmlns=\"http://www.w3.org/2000/svg\"><foreignObject><body>evil</body></foreignObject><rect width=\"10\" height=\"10\"/></svg>";
+                "<svg xmlns=\"http://www.w3.org/2000/svg\"><foreignObject><body>evil</body></foreignObject><rect"
+                    + " width=\"10\" height=\"10\"/></svg>";
        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
        String output = new String(result, StandardCharsets.UTF_8);
        assertFalse(output.toLowerCase().contains("foreignobject"));
@@ -113,8 +117,8 @@ class SvgSanitizerTest {
    void testSanitize_removesRelativeLocalPath() throws IOException {
        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
        String svg =
-                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
-                        + "<image href=\"../../assets/image.png\" width=\"10\" height=\"10\"/></svg>";
+                "<svg xmlns=\"http://www.w3.org/2000/svg\"><image href=\"../../assets/image.png\""
+                        + " width=\"10\" height=\"10\"/></svg>";
        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
        String output = new String(result, StandardCharsets.UTF_8);
        assertFalse(output.contains("assets/image.png"), "Relative local path must be stripped");
@@ -106,6 +106,7 @@ SwaggerDoc.json

 # Log file
 *.log
+*.log.gz

 # BlueJ files
 *.ctxt
@@ -62,8 +62,16 @@ dependencies {
    // CVE-2022-25647: Explicit gson to prevent unsafe deserialization (tabula would pull 2.8.7)
    implementation "com.google.code.gson:gson:${gsonVersion}"
    implementation 'org.apache.pdfbox:jbig2-imageio:3.0.5'
-    implementation 'com.opencsv:opencsv:5.12.0' // https://mvnrepository.com/artifact/com.opencsv/opencsv
-    implementation 'org.apache.poi:poi-ooxml:5.5.1'
+    // OpenCSV: Stirling-PDF only uses CSVWriter, not the opencsv-bean module.
+    // Exclude commons-beanutils + commons-collections.
+    implementation('com.opencsv:opencsv:5.12.0') {
+        exclude group: 'commons-beanutils', module: 'commons-beanutils'
+        exclude group: 'commons-collections', module: 'commons-collections'
+    }
+    // POI: only XSSF (modern Excel) is used, not HSSF/FormulaEvaluator which need commons-math3.
+    implementation('org.apache.poi:poi-ooxml:5.5.1') {
+        exclude group: 'org.apache.commons', module: 'commons-math3'
+    }

    // Batik only bridge module needed (transitively pulls anim, gvt, util, css, dom, svg-dom)
    // Replaces batik-all which included unused codec, svggen, transcoder, script modules
@@ -129,6 +137,10 @@ bootJar {
    exclude 'META-INF/*.RSA'
    exclude 'META-INF/*.EC'

+    // Exclude source maps from production JAR, dev-only debugging artifacts, not needed at runtime
+    exclude 'static/pdfjs-legacy/**/*.map'
+    exclude 'static/**/*.map'
+
    manifest {
        attributes(
            'Implementation-Title': 'Stirling-PDF',
--- a/Show More
+++ b/Show More