Redesign env var system to use Vite's builtin system

fix: get all Playwright E2E tests loading and expand CI to run full suite (#6009 )
## Fix Playwright E2E tests and expand CI to run full suite ### Problem The full Playwright suite was broken in two ways: 1. **`ConvertE2E.spec.ts` crashed at import time** — `conversionEndpointDiscovery.ts` imported a React hook at the top level, which pulled in the entire component tree. That chain eventually required `material-symbols-icons.json` (a generated file that didn't exist), crashing module resolution before any tests ran. 2. **CI only ran cert validation tests** — both `build.yml` and `nightly.yml` hardcoded `src/core/tests/certValidation` as the test path, silently ignoring everything else. ### Changes **`ConvertE2E.spec.ts` — complete rewrite** The old tests were useless in practice: all 9 dynamic conversion tests were permanently skipped unless a real Spring Boot backend was running (they called a live `/api/v1/config/endpoints-enabled` endpoint at module load time). Replaced with 4 focused tests that use `page.route()` mocking — no backend required, same pattern as `CertificateValidationE2E`. New tests cover: - Convert button absent before a format pair is selected - Successful PDF→PNG conversion shows a download button (mocked API response) - API error surfaces as an error notification - Convert button appears and is enabled after selecting valid formats **`conversionEndpointDiscovery.ts` — deleted** Only existed to support the old tests. The `useConversionEndpoints` React hook it exported was never imported anywhere else. **`ReviewToolStep.tsx`** Added `data-testid="download-result-button"` to the download button — required for the happy-path test assertion. **CI workflows (`build.yml`, `nightly.yml`)** - Added a `Generate icons` step before Playwright runs (`node scripts/generate-icons.js`) — the icon JSON is generated by `npm run dev` locally but skipped by `npm ci` in CI - Removed the `src/core/tests/certValidation` path filter so the full suite runs
2026-09-03 21:30:14 +03:00 · 2026-03-30 15:42:15 +01:00 · 2026-03-30 11:27:55 +01:00 · 2026-03-30 11:04:11 +01:00 · 2026-03-30 11:03:11 +01:00 · 2026-03-30 11:02:30 +01:00
1357 changed files with 426480 additions and 304548 deletions
@@ -1,75 +1,75 @@
-# Node modules and build artifacts
-node_modules
-frontend/node_modules
-frontend/dist
-frontend/build
-frontend/.vite
-frontend/.tauri
-frontend/src-tauri/target
-
-# Gradle build artifacts
-.gradle
-build
-bin
-target
-out
-
-# Git
-.git
+# Version control
+.git/
 .gitignore

-# IDE
-.vscode
-.idea
+# Build outputs
+build/
+*/build/
+**/build/
+out/
+target/
+**/target/
+bin/
+version_builds/
+
+# Gradle caches (local, not what's in the container)
+.gradle/
+**/.gradle/
+
+# Node / frontend
+node_modules/
+**/node_modules/
+frontend/node_modules/
+frontend/dist/
+.npm/
+.yarn/
+
+# Tauri/desktop builds
+src-tauri/target/
+src-tauri/dist/
+
+# IDE and editor
+.idea/
+.vscode/
 *.iml
-*.iws
 *.ipr
+*.iws

-# Logs
+# Logs and temp files
 *.log
-logs
+*.tmp
+*.pid
+.DS_Store
+Thumbs.db

-# Environment files
+# Docker itself
+Dockerfile*
+.dockerignore
+
+# CI / CD configs (not needed in build context)
+.github/
+.circleci/
+.gitlab-ci.yml
+
+# Test reports
+**/test-results/
+**/jacoco/
+
+# Testing and documentation (not needed in build)
+testing/
+docs/
+*.md
+README*
+
+# Local env
 .env
 .env.*
 !.env.example

-# OS files
-.DS_Store
-Thumbs.db
-
-# Java compiled files
-*.class
-*.jar
-*.war
-*.ear
-
-# Test reports
-test-results
-coverage
-
-# Docker
-docker-compose.override.yml
-.dockerignore
-
-# Temporary files
-tmp
-temp
-*.tmp
+# Misc
 *.swp
+*.swo
 *~
-
-# Runtime database and config files (locked by running app)
-app/core/configs/**
-stirling/**
-stirling-pdf-DB*.mv.db
-stirling-pdf-DB*.trace.db
-
-# Documentation
-*.md
-!README.md
-docs
-
-# CI/CD
-.github
-.gitlab-ci.yml
+.DS_Store
+.cache/
+.pytest_cache/
@@ -14,7 +14,7 @@ indent_size = 4
 max_line_length = 100

 [*.py]
-indent_size = 2
+indent_size = 4

 [*.gradle]
 indent_size = 4
@@ -6,14 +6,20 @@ openapi: &openapi
  - *build
  - app/(common|core|proprietary)/src/main/java/**

+docker-base: &docker-base
+  - docker/base/Dockerfile
+  - ".github/workflows/push-docker-base.yml"
+
 docker: &docker
-  - Dockerfile
-  - Dockerfile.fat
-  - Dockerfile.ultra-lite
+  - docker/embedded/Dockerfile
+  - docker/embedded/Dockerfile.fat
+  - docker/embedded/Dockerfile.ultra-lite
  - ".github/workflows/build.yml"
+  - ".github/workflows/push-docker.yml"
  - scripts/init.sh
  - scripts/init-without-ocr.sh
  - exampleYmlFiles/**
+  - *docker-base

 project: &project
  - app/(common|core|proprietary)/src/(main|test)/java/**
@@ -24,6 +30,7 @@ project: &project
  - libs/**
  - "testing/**/!(requirements*.txt|requirements*.in)*"
  - *docker
+  - *docker-base
  - gradle.properties
  - gradlew
  - gradlew.bat
@@ -68,3 +68,8 @@ updates:
    schedule:
      interval: "weekly"
    rebase-strategy: "auto"
+
+  - package-ecosystem: cargo
+    directory: /frontend/src-tauri/provisioner
+    schedule:
+      interval: daily
@@ -9,7 +9,7 @@
 # CVE-2025-6176 mitigation: pin brotli to a specific commit
 brotli @ git+https://github.com/google/brotli.git@028fb5a23661f123017c060daa546b55cf4bde29
    # via
-    #   -r .github/scripts/requirements_dev.in
+    #   -r requirements_dev.in
    #   fonttools
 cffi==2.0.0 \
    --hash=sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb \
@@ -256,105 +256,105 @@ opencv-python-headless==4.13.0.90 \
    --hash=sha256:e13790342591557050157713af17a7435ac1b50c65282715093c9297fa045d8f \
    --hash=sha256:eba38bc255d0b7d1969c5bcc90a060ca2b61a3403b613872c750bfa5dfe9e03b \
    --hash=sha256:f46b17ea0aa7e4124ca6ad71143f89233ae9557f61d2326bcdb34329a1ddf9bd
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
 pdf2image==1.17.0 \
    --hash=sha256:eaa959bc116b420dd7ec415fcae49b98100dda3dd18cd2fdfa86d09f112f6d57 \
    --hash=sha256:ecdd58d7afb810dffe21ef2b1bbc057ef434dabbac6c33778a38a3f7744a27e2
-    # via -r .github/scripts/requirements_dev.in
-pillow==12.1.0 \
-    --hash=sha256:00162e9ca6d22b7c3ee8e61faa3c3253cd19b6a37f126cad04f2f88b306f557d \
-    --hash=sha256:079af2fb0c599c2ec144ba2c02766d1b55498e373b3ac64687e43849fbbef5bc \
-    --hash=sha256:0b022eaaf709541b391ee069f0022ee5b36c709df71986e3f7be312e46f42c84 \
-    --hash=sha256:0c27407a2d1b96774cbc4a7594129cc027339fd800cd081e44497722ea1179de \
-    --hash=sha256:0ddedfaa8b5f0b4ffbc2fa87b556dc59f6bb4ecb14a53b33f9189713ae8053c0 \
-    --hash=sha256:0deedf2ea233722476b3a81e8cdfbad786f7adbed5d848469fa59fe52396e4ef \
-    --hash=sha256:0ed07dca4a8464bada6139ab38f5382f83e5f111698caf3191cb8dbf27d908b4 \
-    --hash=sha256:0fde7ec5538ab5095cc02df38ee99b0443ff0e1c847a045554cf5f9af1f4aa82 \
-    --hash=sha256:15c794d74303828eaa957ff8070846d0efe8c630901a1c753fdc63850e19ecd9 \
-    --hash=sha256:1a949604f73eb07a8adab38c4fe50791f9919344398bdc8ac6b307f755fc7030 \
-    --hash=sha256:1f345e7bc9d7f368887c712aa5054558bad44d2a301ddf9248599f4161abc7c0 \
-    --hash=sha256:1fcc52d86ce7a34fd17cb04e87cfdb164648a3662a6f20565910a99653d66c18 \
-    --hash=sha256:21e686a21078b0f9cb8c8a961d99e6a4ddb88e0fc5ea6e130172ddddc2e5221a \
-    --hash=sha256:2415373395a831f53933c23ce051021e79c8cd7979822d8cc478547a3f4da8ef \
-    --hash=sha256:277518bf4fe74aa91489e1b20577473b19ee70fb97c374aa50830b279f25841b \
-    --hash=sha256:27b9baecb428899db6c0de572d6d305cfaf38ca1596b5c0542a5182e3e74e8c6 \
-    --hash=sha256:29a4cef9cb672363926f0470afc516dbf7305a14d8c54f7abbb5c199cd8f8179 \
-    --hash=sha256:3413c2ae377550f5487991d444428f1a8ae92784aac79caa8b1e3b89b175f77e \
-    --hash=sha256:351889afef0f485b84078ea40fe33727a0492b9af3904661b0abbafee0355b72 \
-    --hash=sha256:3ffaa2f0659e2f740473bcf03c702c39a8d4b2b7ffc629052028764324842c64 \
-    --hash=sha256:40a8e3b9e8773876d6e30daed22f016509e3987bab61b3b7fe309d7019a87451 \
-    --hash=sha256:414b9a78e14ffeb98128863314e62c3f24b8a86081066625700b7985b3f529bd \
-    --hash=sha256:43aca0a55ce1eefc0aefa6253661cb54571857b1a7b2964bd8a1e3ef4b729924 \
-    --hash=sha256:43b4899cfd091a9693a1278c4982f3e50f7fb7cff5153b05174b4afc9593b616 \
-    --hash=sha256:461f9dfdafa394c59cd6d818bdfdbab4028b83b02caadaff0ffd433faf4c9a7a \
-    --hash=sha256:4f9f6a650743f0ddee5593ac9e954ba1bdbc5e150bc066586d4f26127853ab94 \
-    --hash=sha256:53d8b764726d3af1a138dd353116f774e3862ec7e3794e0c8781e30db0f35dfc \
-    --hash=sha256:565c986f4b45c020f5421a4cea13ef294dde9509a8577f29b2fc5edc7587fff8 \
-    --hash=sha256:5c5ae0a06e9ea030ab786b0251b32c7e4ce10e58d983c0d5c56029455180b5b9 \
-    --hash=sha256:5cb7bc1966d031aec37ddb9dcf15c2da5b2e9f7cc3ca7c54473a20a927e1eb91 \
-    --hash=sha256:5da841d81b1a05ef940a8567da92decaa15bc4d7dedb540a8c219ad83d91808a \
-    --hash=sha256:5fee4c04aad8932da9f8f710af2c1a15a83582cfb884152a9caa79d4efcdbf9c \
-    --hash=sha256:609e89d9f90b581c8d16358c9087df76024cf058fa693dd3e1e1620823f39670 \
-    --hash=sha256:6258f3260986990ba2fa8a874f8b6e808cf5abb51a94015ca3dc3c68aa4f30ea \
-    --hash=sha256:64efdf00c09e31efd754448a383ea241f55a994fd079866b92d2bbff598aad91 \
-    --hash=sha256:65b80c1ee7e14a87d6a068dd3b0aea268ffcabfe0498d38661b00c5b4b22e74c \
-    --hash=sha256:6741e6f3074a35e47c77b23a4e4f2d90db3ed905cb1c5e6e0d49bff2045632bc \
-    --hash=sha256:681088909d7e8fa9e31b9799aaa59ba5234c58e5e4f1951b4c4d1082a2e980e0 \
-    --hash=sha256:6b7a9d1db5dad90e2991645874f708e87d9a3c370c243c2d7684d28f7e133e6b \
-    --hash=sha256:7315f9137087c4e0ee73a761b163fc9aa3b19f5f606a7fc08d83fd3e4379af65 \
-    --hash=sha256:742aea052cf5ab5034a53c3846165bc3ce88d7c38e954120db0ab867ca242661 \
-    --hash=sha256:75af0b4c229ac519b155028fa1be632d812a519abba9b46b20e50c6caa184f19 \
-    --hash=sha256:7b5dd7cbae20285cdb597b10eb5a2c13aa9de6cde9bb64a3c1317427b1db1ae1 \
-    --hash=sha256:7d6daa89a00b58c37cb1747ec9fb7ac3bc5ffd5949f5888657dfddde6d1312e0 \
-    --hash=sha256:800429ac32c9b72909c671aaf17ecd13110f823ddb7db4dfef412a5587c2c24e \
-    --hash=sha256:806f3987ffe10e867bab0ddad45df1148a2b98221798457fa097ad85d6e8bc75 \
-    --hash=sha256:808b99604f7873c800c4840f55ff389936ef1948e4e87645eaf3fccbc8477ac4 \
-    --hash=sha256:80941e6d573197a0c28f394753de529bb436b1ca990ed6e765cf42426abc39f8 \
-    --hash=sha256:84cabc7095dd535ca934d57e9ce2a72ffd216e435a84acb06b2277b1de2689bd \
-    --hash=sha256:8637e29d13f478bc4f153d8daa9ffb16455f0a6cb287da1b432fdad2bfbd66c7 \
-    --hash=sha256:896866d2d436563fa2a43a9d72f417874f16b5545955c54a64941e87c1376c61 \
-    --hash=sha256:8e178e3e99d3c0ea8fc64b88447f7cac8ccf058af422a6cedc690d0eadd98c51 \
-    --hash=sha256:907bfa8a9cb790748a9aa4513e37c88c59660da3bcfffbd24a7d9e6abf224551 \
-    --hash=sha256:9212d6b86917a2300669511ed094a9406888362e085f2431a7da985a6b124f45 \
-    --hash=sha256:92a7fe4225365c5e3a8e598982269c6d6698d3e783b3b1ae979e7819f9cd55c1 \
-    --hash=sha256:935b9d1aed48fcfb3f838caac506f38e29621b44ccc4f8a64d575cb1b2a88644 \
-    --hash=sha256:97e9993d5ed946aba26baf9c1e8cf18adbab584b99f452ee72f7ee8acb882796 \
-    --hash=sha256:983976c2ab753166dc66d36af6e8ec15bb511e4a25856e2227e5f7e00a160587 \
-    --hash=sha256:9f5fefaca968e700ad1a4a9de98bf0869a94e397fe3524c4c9450c1445252304 \
-    --hash=sha256:a332ac4ccb84b6dde65dbace8431f3af08874bf9770719d32a635c4ef411b18b \
-    --hash=sha256:a40905599d8079e09f25027423aed94f2823adaf2868940de991e53a449e14a8 \
-    --hash=sha256:a6dfc2af5b082b635af6e08e0d1f9f1c4e04d17d4e2ca0ef96131e85eda6eb17 \
-    --hash=sha256:a786bf667724d84aa29b5db1c61b7bfdde380202aaca12c3461afd6b71743171 \
-    --hash=sha256:a83e0850cb8f5ac975291ebfc4170ba481f41a28065277f7f735c202cd8e0af3 \
-    --hash=sha256:aa0c9cc0b82b14766a99fbe6084409972266e82f459821cd26997a488a7261a7 \
-    --hash=sha256:b17fbdbe01c196e7e159aacb889e091f28e61020a8abeac07b68079b6e626988 \
-    --hash=sha256:b63e13dd27da389ed9475b3d28510f0f954bca0041e8e551b2a4eb1eab56a39a \
-    --hash=sha256:b6e53e82ec2db0717eabb276aa56cf4e500c9a7cec2c2e189b55c24f65a3e8c0 \
-    --hash=sha256:bb0984b30e973f7e2884362b7d23d0a348c7143ee559f38ef3eaab640144204c \
-    --hash=sha256:bc11908616c8a283cf7d664f77411a5ed2a02009b0097ff8abbba5e79128ccf2 \
-    --hash=sha256:bdec5e43377761c5dbca620efb69a77f6855c5a379e32ac5b158f54c84212b14 \
-    --hash=sha256:bef9768cab184e7ae6e559c032e95ba8d07b3023c289f79a2bd36e8bf85605a5 \
-    --hash=sha256:c990547452ee2800d8506c4150280757f88532f3de2a58e3022e9b179107862a \
-    --hash=sha256:ca94b6aac0d7af2a10ba08c0f888b3d5114439b6b3ef39968378723622fed377 \
-    --hash=sha256:cad302dc10fac357d3467a74a9561c90609768a6f73a1923b0fd851b6486f8b0 \
-    --hash=sha256:d0a7735df32ccbcc98b98a1ac785cc4b19b580be1bdf0aeb5c03223220ea09d5 \
-    --hash=sha256:d70347c8a5b7ccd803ec0c85c8709f036e6348f1e6a5bf048ecd9c64d3550b8b \
-    --hash=sha256:d70534cea9e7966169ad29a903b99fc507e932069a881d0965a1a84bb57f6c6d \
-    --hash=sha256:db44d5c160a90df2d24a24760bbd37607d53da0b34fb546c4c232af7192298ac \
-    --hash=sha256:e115c15e3bc727b1ca3e641a909f77f8ca72a64fff150f666fcc85e57701c26c \
-    --hash=sha256:e2479c7f02f9d505682dc47df8c0ea1fc5e264c4d1629a5d63fe3e2334b89554 \
-    --hash=sha256:e5dcbe95016e88437ecf33544ba5db21ef1b8dd6e1b434a2cb2a3d605299e643 \
-    --hash=sha256:e6bdb408f7c9dd2a5ff2b14a3b0bb6d4deb29fb9961e6eb3ae2031ae9a5cec13 \
-    --hash=sha256:e75d3dba8fc1ddfec0cd752108f93b83b4f8d6ab40e524a95d35f016b9683b09 \
-    --hash=sha256:efdc140e7b63b8f739d09a99033aa430accce485ff78e6d311973a67b6bf3208 \
-    --hash=sha256:f10c98f49227ed8383d28174ee95155a675c4ed7f85e2e573b04414f7e371bda \
-    --hash=sha256:f188028b5af6b8fb2e9a76ac0f841a575bd1bd396e46ef0840d9b88a48fdbcea \
-    --hash=sha256:f188d580bd870cda1e15183790d1cc2fa78f666e76077d103edf048eed9c356e \
-    --hash=sha256:f45bd71d1fa5e5749587613037b172e0b3b23159d1c00ef2fc920da6f470e6f0 \
-    --hash=sha256:f61333d817698bdcdd0f9d7793e365ac3d2a21c1f1eb02b32ad6aefb8d8ea831 \
-    --hash=sha256:fb125d860738a09d363a88daa0f59c4533529a90e564785e20fe875b200b6dbd
+    # via -r requirements_dev.in
+pillow==12.1.1 \
+    --hash=sha256:02f84dfad02693676692746df05b89cf25597560db2857363a208e393429f5e9 \
+    --hash=sha256:0330d233c1a0ead844fc097a7d16c0abff4c12e856c0b325f231820fee1f39da \
+    --hash=sha256:03edcc34d688572014ff223c125a3f77fb08091e4607e7745002fc214070b35f \
+    --hash=sha256:097690ba1f2efdeb165a20469d59d8bb03c55fb6621eb2041a060ae8ea3e9642 \
+    --hash=sha256:178aa072084bd88ec759052feca8e56cbb14a60b39322b99a049e58090479713 \
+    --hash=sha256:18e5bddd742a44b7e6b1e773ab5db102bd7a94c32555ba656e76d319d19c3850 \
+    --hash=sha256:1a9b0ee305220b392e1124a764ee4265bd063e54a751a6b62eff69992f457fa9 \
+    --hash=sha256:1f1625b72740fdda5d77b4def688eb8fd6490975d06b909fd19f13f391e077e0 \
+    --hash=sha256:1f1be78ce9466a7ee64bfda57bdba0f7cc499d9794d518b854816c41bf0aa4e9 \
+    --hash=sha256:1f90cff8aa76835cba5769f0b3121a22bd4eb9e6884cfe338216e557a9a548b8 \
+    --hash=sha256:21329ec8c96c6e979cd0dfd29406c40c1d52521a90544463057d2aaa937d66a6 \
+    --hash=sha256:2815a87ab27848db0321fb78c7f0b2c8649dee134b7f2b80c6a45c6831d75ccd \
+    --hash=sha256:2c1fc0f2ca5f96a3c8407e41cca26a16e46b21060fe6d5b099d2cb01412222f5 \
+    --hash=sha256:2e0c664be47252947d870ac0d327fea7e63985a08794758aa8af5b6cb6ec0c9c \
+    --hash=sha256:339ffdcb7cbeaa08221cd401d517d4b1fe7a9ed5d400e4a8039719238620ca35 \
+    --hash=sha256:344cf1e3dab3be4b1fa08e449323d98a2a3f819ad20f4b22e77a0ede31f0faa1 \
+    --hash=sha256:36341d06738a9f66c8287cf8b876d24b18db9bd8740fa0672c74e259ad408cff \
+    --hash=sha256:365b10bb9417dd4498c0e3b128018c4a624dc11c7b97d8cc54effe3b096f4c38 \
+    --hash=sha256:3a5cbdcddad0af3da87cb16b60d23648bc3b51967eb07223e9fed77a82b457c4 \
+    --hash=sha256:417423db963cb4be8bac3fc1204fe61610f6abeed1580a7a2cbb2fbda20f12af \
+    --hash=sha256:42fc1f4677106188ad9a55562bbade416f8b55456f522430fadab3cef7cd4e60 \
+    --hash=sha256:44ce27545b6efcf0fdbdceb31c9a5bdea9333e664cda58a7e674bb74608b3986 \
+    --hash=sha256:472a8d7ded663e6162dafdf20015c486a7009483ca671cece7a9279b512fcb13 \
+    --hash=sha256:47b94983da0c642de92ced1702c5b6c292a84bd3a8e1d1702ff923f183594717 \
+    --hash=sha256:495c302af3aad1ca67420ddd5c7bd480c8867ad173528767d906428057a11f0e \
+    --hash=sha256:4ceb838d4bd9dab43e06c363cab2eebf63846d6a4aeaea283bbdfd8f1a8ed58b \
+    --hash=sha256:50480dcd74fa63b8e78235957d302d98d98d82ccbfac4c7e12108ba9ecbdba15 \
+    --hash=sha256:518a48c2aab7ce596d3bf79d0e275661b846e86e4d0e7dec34712c30fe07f02a \
+    --hash=sha256:559b38da23606e68681337ad74622c4dbba02254fc9cb4488a305dd5975c7eeb \
+    --hash=sha256:578510d88c6229d735855e1f278aa305270438d36a05031dfaae5067cc8eb04d \
+    --hash=sha256:597bd9c8419bc7c6af5604e55847789b69123bbe25d65cc6ad3012b4f3c98d8b \
+    --hash=sha256:5a8eb7ed8d4198bccbd07058416eeec51686b498e784eda166395a23eb99138e \
+    --hash=sha256:5c0dd1636633e7e6a0afe7bf6a51a14992b7f8e60de5789018ebbdfae55b040a \
+    --hash=sha256:5cb1785d97b0c3d1d1a16bc1d710c4a0049daefc4935f3a8f31f827f4d3d2e7f \
+    --hash=sha256:5d1f9575a12bed9e9eedd9a4972834b08c97a352bd17955ccdebfeca5913fa0a \
+    --hash=sha256:5d8c41325b382c07799a3682c1c258469ea2ff97103c53717b7893862d0c98ce \
+    --hash=sha256:5dae5f21afb91322f2ff791895ddd8889e5e947ff59f71b46041c8ce6db790bc \
+    --hash=sha256:600fd103672b925fe62ed08e0d874ea34d692474df6f4bf7ebe148b30f89f39f \
+    --hash=sha256:6408a7b064595afcab0a49393a413732a35788f2a5092fdc6266952ed67de586 \
+    --hash=sha256:652a2c9ccfb556235b2b501a3a7cf3742148cd22e04b5625c5fe057ea3e3191f \
+    --hash=sha256:665e1b916b043cef294bc54d47bf02d87e13f769bc4bc5fa225a24b3a6c5aca9 \
+    --hash=sha256:691ab2ac363b8217f7d31b3497108fb1f50faab2f75dfb03284ec2f217e87bf8 \
+    --hash=sha256:6c52f062424c523d6c4db85518774cc3d50f5539dd6eed32b8f6229b26f24d40 \
+    --hash=sha256:6c6db3b84c87d48d0088943bf33440e0c42370b99b1c2a7989216f7b42eede60 \
+    --hash=sha256:7311c0a0dcadb89b36b7025dfd8326ecfa36964e29913074d47382706e516a7c \
+    --hash=sha256:7aac39bcf8d4770d089588a2e1dd111cbaa42df5a94be3114222057d68336bd0 \
+    --hash=sha256:7b03048319bfc6170e93bd60728a1af51d3dd7704935feb228c4d4faab35d334 \
+    --hash=sha256:7e7976bf1910a8116b523b9f9f58bf410f3e8aa330cd9a2bb2953f9266ab49af \
+    --hash=sha256:8089c852a56c2966cf18835db62d9b34fef7ba74c726ad943928d494fa7f4735 \
+    --hash=sha256:86172b0831b82ce4f7877f280055892b31179e1576aa00d0df3bb1bbf8c3e524 \
+    --hash=sha256:89b54027a766529136a06cfebeecb3a04900397a3590fd252160b888479517bf \
+    --hash=sha256:89c7e895002bbe49cdc5426150377cbbc04767d7547ed145473f496dfa40408b \
+    --hash=sha256:8b7e5304e34942bf62e15184219a7b5ad4ff7f3bb5cca4d984f37df1a0e1aee2 \
+    --hash=sha256:8fd420ef0c52c88b5a035a0886f367748c72147b2b8f384c9d12656678dfdfa9 \
+    --hash=sha256:98edb152429ab62a1818039744d8fbb3ccab98a7c29fc3d5fcef158f3f1f68b7 \
+    --hash=sha256:99c1506ea77c11531d75e3a412832a13a71c7ebc8192ab9e4b2e355555920e3e \
+    --hash=sha256:9ad8fa5937ab05218e2b6a4cff30295ad35afd2f83ac592e68c0d871bb0fdbc4 \
+    --hash=sha256:9f51079765661884a486727f0729d29054242f74b46186026582b4e4769918e4 \
+    --hash=sha256:a003d7422449f6d1e3a34e3dd4110c22148336918ddbfc6a32581cd54b2e0b2b \
+    --hash=sha256:a0b1cd6232e2b618adcc54d9882e4e662a089d5768cd188f7c245b4c8c44a397 \
+    --hash=sha256:a285e3eb7a5a45a2ff504e31f4a8d1b12ef62e84e5411c6804a42197c1cf586c \
+    --hash=sha256:a37691702ed687799de29a518d63d4682d9016932db66d4e90c345831b02fb4e \
+    --hash=sha256:a550ae29b95c6dc13cf69e2c9dc5747f814c54eeb2e32d683e5e93af56caa029 \
+    --hash=sha256:ab174cd7d29a62dd139c44bf74b698039328f45cb03b4596c43473a46656b2f3 \
+    --hash=sha256:ab323b787d6e18b3d91a72fc99b1a2c28651e4358749842b8f8dfacd28ef2052 \
+    --hash=sha256:adebb5bee0f0af4909c30db0d890c773d1a92ffe83da908e2e9e720f8edf3984 \
+    --hash=sha256:aee2810642b2898bb187ced9b349e95d2a7272930796e022efaf12e99dccd293 \
+    --hash=sha256:af9a332e572978f0218686636610555ae3defd1633597be015ed50289a03c523 \
+    --hash=sha256:b574c51cf7d5d62e9be37ba446224b59a2da26dc4c1bb2ecbe936a4fb1a7cb7f \
+    --hash=sha256:b66e95d05ba806247aaa1561f080abc7975daf715c30780ff92a20e4ec546e1b \
+    --hash=sha256:b81b5e3511211631b3f672a595e3221252c90af017e399056d0faabb9538aa80 \
+    --hash=sha256:b957b71c6b2387610f556a7eb0828afbe40b4a98036fc0d2acfa5a44a0c2036f \
+    --hash=sha256:bb66b7cc26f50977108790e2456b7921e773f23db5630261102233eb355a3b79 \
+    --hash=sha256:c6008de247150668a705a6338156efb92334113421ceecf7438a12c9a12dab23 \
+    --hash=sha256:c7697918b5be27424e9ce568193efd13d925c4481dd364e43f5dff72d33e10f8 \
+    --hash=sha256:cb9bb857b2d057c6dfc72ac5f3b44836924ba15721882ef103cecb40d002d80e \
+    --hash=sha256:cc7d296b5ea4d29e6570dabeaed58d31c3fea35a633a69679fb03d7664f43fb3 \
+    --hash=sha256:d242e8ac078781f1de88bf823d70c1a9b3c7950a44cdf4b7c012e22ccbcd8e4e \
+    --hash=sha256:d2912fd8114fc5545aa3a4b5576512f64c55a03f3ebcca4c10194d593d43ea36 \
+    --hash=sha256:d470ab1178551dd17fdba0fef463359c41aaa613cdcd7ff8373f54be629f9f8f \
+    --hash=sha256:d4ce8e329c93845720cd2014659ca67eac35f6433fd3050393d85f3ecef0dad5 \
+    --hash=sha256:d6e4571eedf43af33d0fc233a382a76e849badbccdf1ac438841308652a08e1f \
+    --hash=sha256:e65498daf4b583091ccbb2556c7000abf0f3349fcd57ef7adc9a84a394ed29f6 \
+    --hash=sha256:e879bb6cd5c73848ef3b2b48b8af9ff08c5b71ecda8048b7dd22d8a33f60be32 \
+    --hash=sha256:e9e8064fb1cc019296958595f6db671fba95209e3ceb0c4734c9baf97de04b20 \
+    --hash=sha256:f7ed2c6543bad5a7d5530eb9e78c53132f93dfa44a28492db88b41cdab885202 \
+    --hash=sha256:f95c00d5d6700b2b890479664a06e754974848afaae5e21beb4d83c106923fd0 \
+    --hash=sha256:f975aa7ef9684ce7e2c18a3aa8f8e2106ce1e46b94ab713d156b2898811651d3 \
+    --hash=sha256:fbfa2a7c10cc2623f412753cddf391c7f971c52ca40a3f65dc5039b2939e8563 \
+    --hash=sha256:fc354a04072b765eccf2204f588a7a532c9511e8b9c7f900e1b64e3e33487090 \
+    --hash=sha256:fc44ef1f3de4f45b50ccf9136999d71abb99dca7706bc75d222ed350b9fd2289
    # via
-    #   -r .github/scripts/requirements_dev.in
+    #   -r requirements_dev.in
    #   pdf2image
    #   weasyprint
 platformdirs==4.5.1 \
@@ -364,7 +364,7 @@ platformdirs==4.5.1 \
 pre-commit==4.5.1 \
    --hash=sha256:3b3afd891e97337708c1674210f8eba659b52a38ea5f822ff142d10786221f77 \
    --hash=sha256:eb545fcff725875197837263e977ea257a402056661f09dae08e4b149b030a61
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
 pycparser==3.0 \
    --hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
    --hash=sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992
@@ -465,7 +465,7 @@ tinyhtml5==2.0.0 \
 unoserver==3.6 \
    --hash=sha256:25c360fa194396a89cb79b4edd2735f8e4f0fd8531e59db3952114585bd7df05 \
    --hash=sha256:e446bcb3638c51880f002aaeecab1cf74dfa9df81035f027f7ff2e081b6d7015
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
 virtualenv==20.36.1 \
    --hash=sha256:575a8d6b124ef88f6f51d56d656132389f961062a9177016a50e4f507bbcc19f \
    --hash=sha256:8befb5c81842c641f8ee658481e42641c68b5eab3521d8e092d18320902466ba
@@ -473,7 +473,7 @@ virtualenv==20.36.1 \
 weasyprint==68.0 \
    --hash=sha256:447f40898b747cb44ac31a5d493d512e7441fd56e13f63744c099383bbf9cda9 \
    --hash=sha256:c2cb40c71b50837c5971f00171c9e4078e8c9912dd7c217f3e90e068f11e8aa1
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
 webencodings==0.5.1 \
    --hash=sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78 \
    --hash=sha256:b36a1c245f2d304965eb4e0a82848379241dc04b865afcc4aab16748587e1923
@@ -500,8 +500,8 @@ zopfli==0.4.0 \
 pip==26.0 \
    --hash=sha256:3ce220a0a17915972fbf1ab451baae1521c4539e778b28127efa79b974aff0fa \
    --hash=sha256:98436feffb9e31bc9339cf369fd55d3331b1580b6a6f1173bacacddcf9c34754
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
 setuptools==80.10.2 \
    --hash=sha256:8b0e9d10c784bf7d262c4e5ec5d4ec94127ce206e8738f29a437945fbc219b70 \
    --hash=sha256:95b30ddfb717250edb492926c92b5221f7ef3fbcc2b07579bcd4a27da21d0173
-    # via -r .github/scripts/requirements_dev.in
+    # via -r requirements_dev.in
@@ -35,7 +35,7 @@ jobs:
      pr_ref: ${{ steps.resolve.outputs.ref }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -111,7 +111,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -231,6 +231,8 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile
          push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-${{ steps.commit-hash.outputs.app_short }}
          build-args: VERSION_TAG=v2-alpha
          platforms: linux/amd64
@@ -357,7 +359,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -40,7 +40,7 @@ jobs:
      enable_enterprise: ${{ steps.check-pro-flag.outputs.enable_enterprise }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -128,7 +128,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -150,16 +150,16 @@ jobs:
          ref: refs/pull/${{ needs.check-comment.outputs.pr_number }}/merge
          token: ${{ steps.setup-bot.outputs.token }}

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Run Gradle Command
        run: |
@@ -190,6 +190,8 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile
          push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:pr-${{ needs.check-comment.outputs.pr_number }}
          build-args: VERSION_TAG=alpha
          platforms: linux/amd64
@@ -370,7 +372,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -21,7 +21,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -0,0 +1,83 @@
+name: AI Engine CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  engine:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: engine
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run fixers
+        # Ignore errors here because we're going to add comments for them in the following steps before actually failing
+        run: make fix || true
+
+      - name: Check for fixer changes
+        id: fixer_changes
+        run: |
+          if git diff --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post fixer suggestions
+        if: steps.fixer_changes.outputs.changed == 'true' && github.event_name == 'pull_request'
+        uses: reviewdog/action-suggester@v1
+        continue-on-error: true
+        with:
+          tool_name: engine-make-fix
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          filter_mode: file
+          fail_level: any
+          level: info
+
+      - name: Comment on fixer suggestions
+        if: steps.fixer_changes.outputs.changed == 'true' && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: "The Python code in your PR has formatting/linting issues. Consider running `make fix` locally or setting up your editor's Ruff integration to auto-format and lint your files as you go, or commit the suggested changes on this PR.",
+            });
+
+      - name: Verify fixer changes are committed
+        if: steps.fixer_changes.outputs.changed == 'true'
+        run: |
+          if ! git diff --exit-code; then
+            echo "Fixes are out of date."
+            echo "Apply the reviewdog suggestions or run 'make fix' from engine/ and commit the updated files."
+            git --no-pager diff --stat
+            exit 1
+          fi
+
+      - name: Run linting
+        run: make lint
+
+      - name: Run type checking
+        run: make typecheck
+
+      - name: Run tests
+        run: make test
@@ -19,7 +19,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -87,7 +87,7 @@ jobs:
      - name: AI PR Title Analysis
        if: steps.actor.outputs.is_repo_dev == 'true'
        id: ai-title-analysis
-        uses: actions/ai-inference@a6101c89c6feaecc585efdd8d461f18bb7896f20 # v2.0.5
+        uses: actions/ai-inference@e09e65981758de8b2fdab13c2bfb7c7d5493b0b6 # v2.0.7
        with:
          model: openai/gpt-4o
          system-prompt-file: ".github/config/system-prompt.txt"
@@ -16,7 +16,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -29,7 +29,7 @@ jobs:
          app-id: ${{ secrets.GH_APP_ID }}
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}

-      - uses: srvaroa/labeler@0a20eccb8c94a1ee0bed5f16859aece1c45c3e55 # v1.13.0
+      - uses: srvaroa/labeler@bf262763a8a8e191f5847873aecc0f29df84f957 # v1.14.0
        with:
          config_path: .github/labeler-config-srvaroa.yml
          use_local_config: false
@@ -30,16 +30,17 @@ jobs:
      project: ${{ steps.changes.outputs.project }}
      openapi: ${{ steps.changes.outputs.openapi }}
      frontend: ${{ steps.changes.outputs.frontend }}
+      docker-base: ${{ steps.changes.outputs.docker-base }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: changes
        with:
          filters: .github/config/.files.yaml
@@ -52,11 +53,11 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        jdk-version: [17, 21]
+        jdk-version: [21, 25]
        spring-security: [true, false]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit
      - name: Checkout repository
@@ -68,10 +69,20 @@ jobs:
          java-version: ${{ matrix.jdk-version }}
          distribution: "temurin"

+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-${{ matrix.jdk-version }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
+          cache-disabled: true

      - name: Build with Gradle and spring security ${{ matrix.spring-security }}
        run: ./gradlew build -PnoSpotless
@@ -101,7 +112,7 @@ jobs:

      - name: Upload Test Reports
        if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: test-reports-jdk-${{ matrix.jdk-version }}-spring-security-${{ matrix.spring-security }}
          path: |
@@ -130,23 +141,33 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
+          cache-disabled: true

      - name: Generate OpenAPI documentation
        run: ./gradlew :stirling-pdf:generateOpenApiDocs
@@ -157,7 +178,7 @@ jobs:
          DISABLE_ADDITIONAL_FEATURES: true

      - name: Upload OpenAPI Documentation
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: openapi-docs
          path: ./SwaggerDoc.json
@@ -168,13 +189,13 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Set up Node.js
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: "22"
          cache: "npm"
@@ -182,7 +203,7 @@ jobs:
      - name: Install frontend dependencies
        run: cd frontend && npm ci
      - name: Type-check frontend
-        run: cd frontend && npm run prebuild && npm run typecheck:all
+        run: cd frontend && npm run prep && npm run typecheck:all
      - name: Lint frontend
        run: cd frontend && npm run lint
      - name: Build frontend
@@ -190,38 +211,86 @@ jobs:
      - name: Run frontend tests
        run: cd frontend && npm run test -- --run
      - name: Upload frontend build artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: frontend-build
          path: frontend/dist/
          retention-days: 3

+  playwright-e2e:
+    if: needs.files-changed.outputs.frontend == 'true'
+    needs: files-changed
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install frontend dependencies
+        run: cd frontend && npm ci
+      - name: Generate icons
+        run: cd frontend && node scripts/generate-icons.js
+      - name: Install Playwright (chromium only)
+        run: cd frontend && npx playwright install chromium --with-deps
+      - name: Run E2E tests (chromium)
+        run: cd frontend && npx playwright test --project=chromium
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: playwright-report-pr-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 7
+
  check-licence:
    if: needs.files-changed.outputs.build == 'true'
    needs: [files-changed, build]
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
+          cache-disabled: true

      - name: check the licenses for compatibility
-        run: ./gradlew checkLicense
+        # NOTE: --no-parallel is intentional here. Running the checkLicense task in parallel with other
+        # Gradle tasks has been observed to cause intermittent failures with the dependency license
+        # checking plugin on this Gradle version. Disabling parallel execution trades some build speed
+        # for more reliable, deterministic license checks. If upgrading Gradle or the plugin, consider
+        # re-evaluating whether this flag is still required before removing it.
+        run: ./gradlew checkLicense --no-parallel
        env:
          MAVEN_USER: ${{ secrets.MAVEN_USER }}
          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
@@ -229,7 +298,7 @@ jobs:

      - name: FAILED - check the licenses for compatibility
        if: failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: dependencies-without-allowed-license.json
          path: build/reports/dependency-license/dependencies-without-allowed-license.json
@@ -253,37 +322,55 @@ jobs:
    #     )

    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: read
+      checks: write

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Checkout Repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
+          cache-disabled: true

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

+      # Expose ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL for docker buildx type=gha cache backend.
+      - name: Expose GitHub runtime for Buildx cache
+        uses: crazy-max/ghaction-github-runtime@04d248b84655b509d8c44dc1d6f990c879747487 # v4.0.0
+
      - name: Install Docker Compose
        run: |
          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
          sudo chmod +x /usr/local/bin/docker-compose

      - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.12"
          cache: "pip" # caching pip dependencies
@@ -292,6 +379,7 @@ jobs:
      - name: Pip requirements
        run: |
          pip install --require-hashes -r ./testing/cucumber/requirements.txt
+          pip install behave-html-formatter

      - name: Run Docker Compose Tests
        run: |
@@ -303,6 +391,34 @@ jobs:
          MAVEN_USER: ${{ secrets.MAVEN_USER }}
          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+          DOCKER_BASE_CHANGED: ${{ needs.files-changed.outputs.docker-base }}
+
+      - name: Upload Cucumber Report
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: cucumber-report
+          path: testing/cucumber/report.html
+          retention-days: 7
+          if-no-files-found: warn
+
+      - name: Upload Test Reports
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: docker-compose-test-reports
+          path: testing/reports/
+          retention-days: 7
+          if-no-files-found: warn
+
+      - name: Cucumber Test Report
+        if: always()
+        uses: dorny/test-reporter@b082adf0eced0765477756c2a610396589b8c637 # v2.5.0
+        with:
+          name: Cucumber Tests
+          path: testing/cucumber/junit/*.xml
+          reporter: java-junit
+          fail-on-error: false

  test-build-docker-images:
    if: github.event_name == 'pull_request' && needs.files-changed.outputs.project == 'true'
@@ -314,19 +430,33 @@ jobs:
        include:
          - docker-rev: docker/embedded/Dockerfile
            artifact-suffix: Dockerfile
+            cache-scope: stirling-pdf-latest
          - docker-rev: docker/embedded/Dockerfile.ultra-lite
            artifact-suffix: Dockerfile.ultra-lite
+            cache-scope: stirling-pdf-ultra-lite
          - docker-rev: docker/embedded/Dockerfile.fat
            artifact-suffix: Dockerfile.fat
+            cache-scope: stirling-pdf-fat
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Checkout Repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.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: Free disk space on runner
        run: |
          echo "Disk space before cleanup:" && df -h
@@ -334,16 +464,26 @@ jobs:
          docker system prune -af || true
          echo "Disk space after cleanup:" && df -h

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

+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
+          cache-disabled: true

      - name: Build application
        run: ./gradlew build
@@ -355,12 +495,28 @@ jobs:
          STIRLING_PDF_DESKTOP_UI: false

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0

      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

+      - name: Build base image locally (PR base change only)
+        if: github.event_name == 'pull_request' && needs.files-changed.outputs.docker-base == 'true'
+        run: |
+          docker build -t stirling-pdf-base:pr-test -f docker/base/Dockerfile docker/base
+
+      - name: Set base image and platform for this build
+        id: build-params
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ] && [ "${{ needs.files-changed.outputs.docker-base }}" == "true" ]; then
+            echo "base_image=stirling-pdf-base:pr-test" >> $GITHUB_OUTPUT
+            echo "platforms=linux/amd64" >> $GITHUB_OUTPUT
+          else
+            echo "base_image=ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-base:latest" >> $GITHUB_OUTPUT
+            echo "platforms=linux/amd64,linux/arm64/v8" >> $GITHUB_OUTPUT
+          fi
+
      - name: Build ${{ matrix.docker-rev }}
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
@@ -368,15 +524,17 @@ jobs:
          context: .
          file: ./${{ matrix.docker-rev }}
          push: false
-          cache-from: type=gha,scope=${{ matrix.artifact-suffix }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.artifact-suffix }}
-          platforms: linux/amd64,linux/arm64/v8
+          cache-from: type=gha,scope=${{ matrix.cache-scope }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.cache-scope }}
+          platforms: ${{ steps.build-params.outputs.platforms }}
+          build-args: |
+            BASE_IMAGE=${{ steps.build-params.outputs.base_image }}
          provenance: true
          sbom: true

      - name: Upload Reports
        if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: reports-docker-${{ matrix.artifact-suffix }}
          path: |
@@ -27,7 +27,7 @@ jobs:
      pull-requests: write # Allow writing to pull requests
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.12"

@@ -17,7 +17,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -18,7 +18,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -97,6 +97,8 @@ jobs:
          context: .
          file: ./docker/frontend/Dockerfile
          push: true
+          cache-from: type=gha,scope=stirling-v2-frontend
+          cache-to: type=gha,mode=max,scope=stirling-v2-frontend
          tags: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-frontend-${{ steps.commit-hashes.outputs.frontend_short }}
            ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-frontend-latest
@@ -110,6 +112,8 @@ jobs:
          context: .
          file: ./docker/backend/Dockerfile
          push: true
+          cache-from: type=gha,scope=stirling-v2-backend
+          cache-to: type=gha,mode=max,scope=stirling-v2-backend
          tags: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-backend-${{ steps.commit-hashes.outputs.backend_short }}
            ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-backend-latest
@@ -25,7 +25,7 @@ jobs:
      licenses-backend: ${{ steps.changes.outputs.licenses-backend }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: changes
        with:
          filters: .github/config/.files.yaml
@@ -49,7 +49,7 @@ jobs:
      repository-projects: write # Required for enabling automerge
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Set up Node.js
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: "22"
          cache: "npm"
@@ -312,7 +312,7 @@ jobs:
      repository-projects: write # Required for enabling automerge
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -330,21 +330,26 @@ jobs:
          app-id: ${{ secrets.GH_APP_ID }}
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Check licenses and generate report
        id: license-check
        run: |
-          ./gradlew checkLicense generateLicenseReport || echo "LICENSE_CHECK_FAILED=true" >> $GITHUB_ENV
+          # NOTE: --no-parallel is intentional here. Running the license-checking tasks in parallel has
+          # previously caused intermittent concurrency issues in CI (e.g. flaky failures in the license
+          # plugin/Gradle when multiple projects are evaluated concurrently). Disabling parallelism trades
+          # some build speed for more reliable license reports. If the underlying issues are resolved in
+          # future Gradle or plugin versions, this flag can be reconsidered.
+          ./gradlew checkLicense generateLicenseReport --no-parallel || echo "LICENSE_CHECK_FAILED=true" >> $GITHUB_ENV
        env:
          MAVEN_USER: ${{ secrets.MAVEN_USER }}
          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
@@ -364,7 +369,7 @@ jobs:

      - name: Upload artifact on license issues
        if: env.LICENSE_WARNINGS_EXIST == 'true'
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: backend-dependencies-without-allowed-license.json
          path: build/reports/dependency-license/dependencies-without-allowed-license.json
@@ -15,7 +15,7 @@ jobs:
      issues: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@24d110aa46a59976b8a7f35518cb7f14f434c916 # v5.3.0
+        uses: crazy-max/ghaction-github-labeler@548a7c3603594ec17c819e1239f281a3b801ab4d # v6.0.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          yaml-file: .github/labels.yml
@@ -21,8 +21,6 @@ on:
          - windows
          - macos
          - linux
-  push:
-    branches: [main, V2-master]
  release:
    types: [created]

@@ -38,22 +36,32 @@ jobs:
      version: ${{ steps.versionNumber.outputs.versionNumber }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

+      - name: Cache Gradle dependencies
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Get version number
        id: versionNumber
@@ -111,26 +119,26 @@ jobs:
            file_suffix: "-server"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Setup Node.js
        if: matrix.variant.build_frontend == true
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: 22
          cache: "npm"
@@ -154,7 +162,7 @@ jobs:
          cp app/core/build/libs/stirling-pdf-${{ needs.determine-matrix.outputs.version }}.jar ./jar-dist/Stirling-PDF${{ matrix.variant.file_suffix }}.jar

      - name: Upload JAR artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: jar${{ matrix.variant.file_suffix }}
          path: ./jar-dist/*.jar
@@ -171,9 +179,12 @@ jobs:
      WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit
+          allowed-endpoints: >
+            one.digicert.com:443
+            clientauth.one.digicert.com:443

      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -185,7 +196,7 @@ jobs:
          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libjavascriptcoregtk-4.0-dev libsoup2.4-dev libjavascriptcoregtk-4.1-dev libsoup-3.0-dev

      - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: 22
          cache: "npm"
@@ -197,16 +208,16 @@ jobs:
          toolchain: stable
          targets: ${{ (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Build Java backend with JLink
        working-directory: ./
@@ -291,7 +302,7 @@ jobs:
      - name: Setup DigiCert KeyLocker
        id: digicert-setup
        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') }}
-        uses: digicert/ssm-code-signing@af7f4b07694120e514fe5b19f0598af3c20256e3 # v1.2.0
+        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
        env:
          SM_API_KEY: ${{ secrets.SM_API_KEY }}
          SM_CLIENT_CERT_FILE_B64: ${{ secrets.SM_CLIENT_CERT_FILE_B64 }}
@@ -411,8 +422,9 @@ jobs:
          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.APPIMAGETOOL_SIGN_PASSPHRASE }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
-          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY }}
-          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
          # Only enable Windows signing in Tauri when on release or V2-master
          SIGN: ${{ (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') && (env.SM_API_KEY == '' && env.WINDOWS_CERTIFICATE != '') && '1' || '0' }}
          CI: true
@@ -533,7 +545,7 @@ jobs:
          fi

      - name: Upload build artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: Stirling-PDF-${{ matrix.name }}
          path: ./dist/*
@@ -547,30 +559,30 @@ jobs:
      contents: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Download all Tauri artifacts
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          pattern: Stirling-PDF-*
          path: ./artifacts/tauri

      - name: Download JAR artifact (default)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: jar
          path: ./artifacts/jars

      - name: Download JAR artifact (with login)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: jar-with-login
          path: ./artifacts/jars

      - name: Download JAR artifact (server only)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: jar-server
          path: ./artifacts/jars
@@ -579,7 +591,7 @@ jobs:
        run: ls -R ./artifacts

      - name: Upload binaries to Release
-        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
        with:
          tag_name: v${{ needs.determine-matrix.outputs.version }}
          generate_release_notes: true
@@ -0,0 +1,53 @@
+name: Nightly E2E Tests
+
+on:
+  schedule:
+    - cron: "0 2 * * *" # 2 AM UTC every night
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  playwright-all-browsers:
+    name: Playwright (chromium + firefox + webkit)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        run: cd frontend && npm ci
+
+      - name: Generate icons
+        run: cd frontend && node scripts/generate-icons.js
+
+      - name: Install all Playwright browsers
+        run: cd frontend && npx playwright install --with-deps
+
+      - name: Run E2E tests (all browsers)
+        run: cd frontend && npx playwright test
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: playwright-nightly-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 14
@@ -21,7 +21,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: 3.12
          cache: "pip" # caching pip dependencies
@@ -59,16 +59,16 @@ jobs:
          pre-commit run trailing-whitespace --all-files -c .pre-commit-config.yaml
        continue-on-error: true

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Build with Gradle
        run: ./gradlew build
@@ -0,0 +1,119 @@
+name: Push Docker Base Image
+
+on:
+  push:
+    branches:
+      - baseDockerImage
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Base image version (e.g., 1.0.0, 1.0.1)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  push-base:
+    if: ${{ vars.CI_PROFILE != 'lite' && github.actor == 'Frooodle' }}
+    runs-on: ubuntu-24.04-8core
+    permissions:
+      packages: write
+      id-token: write
+    steps:
+      - name: Verify authorized user
+        run: |
+          if [ "${{ github.actor }}" != "Frooodle" ]; then
+            echo "Error: Only Frooodle is authorized to run this workflow"
+            exit 1
+          fi
+
+      - name: Set version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            VERSION="1.0.0"
+          fi
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Harden Runner
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_API }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+
+      - name: Convert repository owner to lowercase
+        id: repoowner
+        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+      - name: Generate tags for base image
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: |
+            ${{ secrets.DOCKER_HUB_ORG_USERNAME }}/stirling-pdf-base
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-base
+          tags: |
+            type=raw,value=${{ steps.version.outputs.version }}
+
+      - name: Build and push base image
+        id: build-push-base
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: docker/base
+          file: ./docker/base/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-pdf-base
+          cache-to: type=gha,mode=max,scope=stirling-pdf-base
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64/v8
+          provenance: true
+          sbom: true
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        with:
+          cosign-release: "v2.4.1"
+
+      - name: Sign base images
+        env:
+          DIGEST: ${{ steps.build-push-base.outputs.digest }}
+          TAGS: ${{ steps.meta.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 --yes \
+                --key env://COSIGN_PRIVATE_KEY \
+                "${tag}@${DIGEST}"
+            done
+          else
+            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping image signing"
+          fi
@@ -33,22 +33,32 @@ jobs:
      id-token: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

+      - name: Cache Gradle dependencies
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Set up Docker Buildx
        id: buildx
@@ -64,13 +74,13 @@ jobs:

      - name: Install cosign
        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
-        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22 # v4.1.0
        with:
          cosign-release: "v2.4.1"

      - name: Install cosign
        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
-        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        uses: sigstore/cosign-installer@ba7bc0a3fef59531c69a25acd34668d6d3fe6f22 # v4.1.0
        with:
          cosign-release: "v2.4.1"

@@ -88,7 +98,7 @@ jobs:
          password: ${{ github.token }}

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0

      - name: Convert repository owner to lowercase
        id: repoowner
@@ -96,7 +106,7 @@ jobs:

      - name: Generate tags for latest
        id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        with:
          images: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -116,11 +126,13 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile
          push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
-          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
+          build-args: |
+            VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
+            BASE_VERSION=1.0.0
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true
@@ -141,7 +153,7 @@ jobs:

      - name: Generate tags for latest-fat
        id: meta-fat
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
        with:
          images: |
@@ -162,8 +174,8 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile.fat
          push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-fat
+          cache-to: type=gha,mode=max,scope=stirling-pdf-fat
          tags: ${{ steps.meta-fat.outputs.tags }}
          labels: ${{ steps.meta-fat.outputs.labels }}
          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
@@ -185,7 +197,7 @@ jobs:

      - name: Generate tags for ultra-lite
        id: meta-lite
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
        with:
          images: |
@@ -206,8 +218,8 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile.ultra-lite
          push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-ultra-lite
+          cache-to: type=gha,mode=max,scope=stirling-pdf-ultra-lite
          tags: ${{ steps.meta-lite.outputs.tags }}
          labels: ${{ steps.meta-lite.outputs.labels }}
          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
@@ -35,7 +35,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -67,7 +67,7 @@ jobs:
      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
      # format to the repository Actions tab.
      - name: "Upload artifact"
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: SARIF file
          path: results.sarif
@@ -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@cdefb33c0f6224e58673d9004f47f7cb3e328b89 # v3.29.5
+        uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.29.5
        with:
          sarif_file: results.sarif
@@ -17,7 +17,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -27,22 +27,22 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Generate Swagger documentation
        run: ./gradlew :stirling-pdf:generateOpenApiDocs
@@ -35,7 +35,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

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

      - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.12"
          cache: "pip" # caching pip dependencies
@@ -14,14 +14,16 @@ on:
          - macos
          - linux
  pull_request:
-    branches: [main, V2-tauri-windows]
+    branches: [main]
+    types: [opened, reopened, synchronize, ready_for_review]
    paths:
      - "frontend/src-tauri/**"
      - "frontend/src/desktop/**"
      - "frontend/tsconfig.desktop.json"
+      - "frontend/package.json"
+      - "frontend/package-lock.json"
+      - "frontend/vite.config.ts"
      - ".github/workflows/tauri-build.yml"
-  push:
-    branches: [main]

 permissions:
  contents: read
@@ -35,33 +37,48 @@ jobs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Determine build matrix
        id: set-matrix
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
        run: |
+          WINDOWS='{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"}'
+          MACOS_ARM='{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"}'
+          MACOS_INTEL='{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"}'
+          LINUX='{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}'
+
+          # Resolve requested platform (non-dispatch events always build all)
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            case "${{ github.event.inputs.platform }}" in
-              "windows")
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              "macos")
-                echo 'matrix={"include":[{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              "linux")
-                echo 'matrix={"include":[{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              *)
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-            esac
+            PLATFORM="${{ github.event.inputs.platform }}"
          else
-            # For PR/push events, build all platforms
-            echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
+            PLATFORM="all"
          fi

+          # Build candidate list
+          case "$PLATFORM" in
+            windows) ENTRIES=("$WINDOWS") ;;
+            macos)   ENTRIES=("$MACOS_ARM" "$MACOS_INTEL") ;;
+            linux)   ENTRIES=("$LINUX") ;;
+            *)       ENTRIES=("$WINDOWS" "$MACOS_ARM" "$MACOS_INTEL" "$LINUX") ;;
+          esac
+
+          # Drop macOS entries when Apple certificate secret is unavailable
+          if [ -z "$APPLE_CERTIFICATE" ]; then
+            echo "⚠️ APPLE_CERTIFICATE secret not available - skipping macOS builds"
+            FILTERED=()
+            for entry in "${ENTRIES[@]}"; do
+              [[ "$entry" != *'"macos'* ]] && FILTERED+=("$entry")
+            done
+            ENTRIES=("${FILTERED[@]}")
+          fi
+
+          JOINED=$(IFS=','; echo "${ENTRIES[*]}")
+          echo "matrix={\"include\":[$JOINED]}" >> $GITHUB_OUTPUT
+
  build:
    needs: determine-matrix
    strategy:
@@ -71,9 +88,10 @@ jobs:
    env:
      SM_API_KEY: ${{ secrets.SM_API_KEY }}
      WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
+      APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -87,7 +105,7 @@ jobs:
          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libjavascriptcoregtk-4.0-dev libsoup2.4-dev libjavascriptcoregtk-4.1-dev libsoup-3.0-dev

      - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: 22
          cache: "npm"
@@ -99,16 +117,16 @@ jobs:
          toolchain: stable
          targets: ${{ (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Build Java backend with JLink
        working-directory: ./
@@ -194,7 +212,7 @@ jobs:
      - name: Setup DigiCert KeyLocker
        id: digicert-setup
        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
-        uses: digicert/ssm-code-signing@af7f4b07694120e514fe5b19f0598af3c20256e3 # v1.2.0
+        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
        env:
          SM_API_KEY: ${{ secrets.SM_API_KEY }}
          SM_CLIENT_CERT_FILE_B64: ${{ secrets.SM_CLIENT_CERT_FILE_B64 }}
@@ -269,7 +287,7 @@ jobs:
          }

      - name: Import Apple Developer Certificate
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && env.APPLE_CERTIFICATE != ''
        env:
          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
@@ -290,7 +308,7 @@ jobs:
          rm certificate.p12

      - name: Verify Certificate
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && env.APPLE_CERTIFICATE != ''
        run: |
          echo "Verifying Apple Developer Certificate..."
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
@@ -325,8 +343,9 @@ jobs:
          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.APPIMAGETOOL_SIGN_PASSPHRASE }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
-          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY }}
-          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
          # Only enable Windows signing in Tauri when on main
          SIGN: ${{ github.ref == 'refs/heads/main' && (env.SM_API_KEY == '' && env.WINDOWS_CERTIFICATE != '') && '1' || '0' }}
          CI: true
@@ -587,7 +606,7 @@ jobs:
          }

      - name: Upload artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: Stirling-PDF-${{ matrix.name }}
          path: ./dist/*
@@ -648,7 +667,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden the runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -740,7 +759,7 @@ jobs:
    if: always()
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -25,23 +25,23 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

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

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
        with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1

      - name: Build with Gradle
        run: ./gradlew build
@@ -72,6 +72,8 @@ jobs:
          context: .
          file: ./docker/embedded/Dockerfile
          push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:test-${{ github.sha }}
          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
          platforms: linux/amd64
@@ -129,14 +131,14 @@ jobs:
      frontend: ${{ steps.changes.outputs.frontend }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: changes
        with:
          filters: ".github/config/.files.yaml"
@@ -148,14 +150,14 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Set up Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          cache: "npm"
          cache-dependency-path: frontend/package-lock.json
@@ -184,7 +186,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
        with:
          egress-policy: audit

@@ -29,8 +29,14 @@ clientWebUI/
 exampleYmlFiles/stirling/
 /stirling/
 /testing/file_snapshots
+/testing/cucumber/junit/
+/testing/cucumber/report.html
+/testing/.failed_tests
 SwaggerDoc.json

+# Runtime storage for uploaded files and user data (not Java source code)
+app/core/storage/
+
 # Frontend build artifacts copied to backend static resources
 # These are generated by npm build and should not be committed
 app/core/src/main/resources/static/assets/
@@ -157,7 +163,6 @@ __pycache__/
 *.pyo

 # Virtual environments
-.env*
 .venv*
 env*/
 venv*/
@@ -196,6 +201,9 @@ out/
 *.jks
 *.asc

+# Allow test fixture certificates (synthetic, no real credentials)
+!frontend/src/core/tests/test-fixtures/certs/**
+
 # SSH Keys
 *.pub
 *.priv
@@ -0,0 +1,356 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents when working with code in this repository.
+
+## Common Development Commands
+
+### Build and Test
+- **Build project**: `./gradlew clean build`
+- **Run locally**: `./gradlew bootRun`
+- **Full test suite**: `./test.sh` (builds all Docker variants and runs comprehensive tests)
+- **Code formatting**: `./gradlew spotlessApply` (runs automatically before compilation)
+
+### Docker Development
+- **Build ultra-lite**: `docker build -t stirlingtools/stirling-pdf:latest-ultra-lite -f ./Dockerfile.ultra-lite .`
+- **Build standard**: `docker build -t stirlingtools/stirling-pdf:latest -f ./Dockerfile .`
+- **Build fat version**: `docker build -t stirlingtools/stirling-pdf:latest-fat -f ./Dockerfile.fat .`
+- **Example compose files**: Located in `exampleYmlFiles/` directory
+
+### Security Mode Development
+Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security features during development. This is required for testing the full version locally.
+
+### Python Development
+Development for the AI engine happens in the `engine/` folder. The frontend calls the Python via Java as a proxy.
+
+- Follow the engine-specific guidance in [engine/AGENTS.md](engine/AGENTS.md) for Python architecture, code style, and AI usage.
+- Use Makefile commands for Python work:
+  - From `engine/`: `make check` to lint, type-check, test, etc. and `make fix` to fix easily fixable linting and formatting issues.
+- The project structure is defined in `engine/pyproject.toml`. Any new dependencies should be listed there, followed by running `make install`.
+
+### Frontend Development
+- **Frontend dev server**: `cd frontend && npm run dev` (requires backend on localhost:8080)
+- **Tech Stack**: Vite + React + TypeScript + Mantine UI + TailwindCSS
+- **Proxy Configuration**: Vite proxies `/api/*` calls to backend (localhost:8080)
+- **Build Process**: DO NOT run build scripts manually - builds are handled by CI/CD pipelines
+- **Package Installation**: DO NOT run npm install commands - package management handled separately
+- **Deployment Options**:
+  - **Desktop App**: `npm run tauri-build` (native desktop application)
+  - **Web Server**: `npm run build` then serve dist/ folder
+  - **Development**: `npm run tauri-dev` for desktop dev mode
+
+#### Environment Variables
+- Committed `.env` files contain defaults; local overrides go in `.env.local` / `.env.*.local` (gitignored):
+  - `frontend/.env` — core, proprietary, and shared vars
+  - `frontend/.env.saas` — SaaS-only vars
+  - `frontend/.env.desktop` — desktop (Tauri)-only vars
+- All `VITE_*` variables must be declared in one of these committed `.env` files
+- Never use `|| 'hardcoded-fallback'` inline — put defaults in the `.env` files
+- See `frontend/README.md#environment-variables` for full documentation
+
+#### Import Paths - CRITICAL
+**ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.
+
+For a broader explanation of the frontend layering and override architecture, see [frontend/DeveloperGuide.md](frontend/DeveloperGuide.md).
+
+```typescript
+// ✅ CORRECT - Use @app/* for all imports
+import { AppLayout } from "@app/components/AppLayout";
+import { useFileContext } from "@app/contexts/FileContext";
+import { FileContext } from "@app/contexts/FileContext";
+
+// ❌ WRONG - Do not use @core/* or @proprietary/* in normal code
+import { AppLayout } from "@core/components/AppLayout";
+import { useFileContext } from "@proprietary/contexts/FileContext";
+```
+
+**Only use explicit aliases when:**
+- Building layer-specific override that wraps a lower layer's component
+- Example: `import { AppProviders as CoreAppProviders } from "@core/components/AppProviders"` when creating proprietary/AppProviders.tsx that extends the core version
+
+The `@app/*` alias automatically resolves to the correct layer based on build target (core/proprietary/desktop) and handles the fallback cascade.
+
+#### Component Override Pattern (Stub/Shadow)
+Use this pattern for desktop-specific or proprietary-specific features WITHOUT runtime checks or conditionals.
+
+**How it works:**
+1. Core defines stub component (returns null or no-op)
+2. Desktop/proprietary overrides with same path/name
+3. Core imports via `@app/*` - higher layer "shadows" core in those builds
+4. No `@ts-ignore`, no `isTauri()` checks, no runtime conditionals!
+
+**Example - Desktop-specific footer:**
+
+```typescript
+// core/components/rightRail/RightRailFooterExtensions.tsx (stub)
+interface RightRailFooterExtensionsProps {
+  className?: string;
+}
+
+export function RightRailFooterExtensions(_props: RightRailFooterExtensionsProps) {
+  return null; // Stub - does nothing in web builds
+}
+```
+
+```tsx
+// desktop/components/rightRail/RightRailFooterExtensions.tsx (real implementation)
+import { Box } from '@mantine/core';
+import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
+
+interface RightRailFooterExtensionsProps {
+  className?: string;
+}
+
+export function RightRailFooterExtensions({ className }: RightRailFooterExtensionsProps) {
+  return (
+    <Box className={className}>
+      <BackendHealthIndicator />
+    </Box>
+  );
+}
+```
+
+```tsx
+// core/components/shared/RightRail.tsx (usage - works in ALL builds)
+import { RightRailFooterExtensions } from '@app/components/rightRail/RightRailFooterExtensions';
+
+export function RightRail() {
+  return (
+    <div>
+      {/* In web builds: renders nothing (stub returns null) */}
+      {/* In desktop builds: renders BackendHealthIndicator */}
+      <RightRailFooterExtensions className="right-rail-footer" />
+    </div>
+  );
+}
+```
+
+**Build resolution:**
+- **Core build**: `@app/*` → `core/*` → Gets stub (returns null)
+- **Desktop build**: `@app/*` → `desktop/*` → Gets real implementation (shadows core)
+
+**Benefits:**
+- No runtime checks or feature flags
+- Type-safe across all builds
+- Clean, readable code
+- Build-time optimization (dead code elimination)
+
+#### Multi-Tool Workflow Architecture
+Frontend designed for **stateful document processing**:
+- Users upload PDFs once, then chain tools (split → merge → compress → view)
+- File state and processing results persist across tool switches
+- No file reloading between tools - performance critical for large PDFs (up to 100GB+)
+
+#### FileContext - Central State Management
+**Location**: `frontend/src/core/contexts/FileContext.tsx`
+- **Active files**: Currently loaded PDFs and their variants
+- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
+- **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
+- **IndexedDB persistence**: File storage with thumbnail caching
+- **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
+
+**Critical**: All file operations go through FileContext. Don't bypass with direct file handling.
+
+#### Processing Services
+- **enhancedPDFProcessingService**: Background PDF parsing and manipulation
+- **thumbnailGenerationService**: Web Worker-based with main-thread fallback
+- **fileStorage**: IndexedDB with LRU cache management
+
+#### Memory Management Strategy
+**Why manual cleanup exists**: Large PDFs (up to 100GB+) through multiple tools accumulate:
+- PDF.js documents that need explicit .destroy() calls
+- Blob URLs from tool outputs that need revocation
+- Web Workers that need termination
+Without cleanup: browser crashes with memory leaks.
+
+#### Tool Development
+
+**Architecture**: Modular hook-based system with clear separation of concerns:
+
+- **useToolOperation** (`frontend/src/core/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook
+  - Coordinates all tool operations with consistent interface
+  - Integrates with FileContext for operation tracking
+  - Handles validation, error handling, and UI state management
+
+- **Supporting Hooks**:
+  - **useToolState**: UI state management (loading, progress, error, files)
+  - **useToolApiCalls**: HTTP requests and file processing
+  - **useToolResources**: Blob URLs, thumbnails, ZIP downloads
+
+- **Utilities**:
+  - **toolErrorHandler**: Standardized error extraction and i18n support
+  - **toolResponseProcessor**: API response handling (single/zip/custom)
+  - **toolOperationTracker**: FileContext integration utilities
+
+**Three Tool Patterns**:
+
+**Pattern 1: Single-File Tools** (Individual processing)
+- Backend processes one file per API call
+- Set `multiFileEndpoint: false`
+- Examples: Compress, Rotate
+```typescript
+return useToolOperation({
+  operationType: 'compress',
+  endpoint: '/api/v1/misc/compress-pdf',
+  buildFormData: (params, file: File) => { /* single file */ },
+  multiFileEndpoint: false,
+});
+```
+
+**Pattern 2: Multi-File Tools** (Batch processing)
+- Backend accepts `MultipartFile[]` arrays in single API call
+- Set `multiFileEndpoint: true`
+- Examples: Split, Merge, Overlay
+```typescript
+return useToolOperation({
+  operationType: 'split',
+  endpoint: '/api/v1/general/split-pages',
+  buildFormData: (params, files: File[]) => { /* all files */ },
+  multiFileEndpoint: true,
+  filePrefix: 'split_',
+});
+```
+
+**Pattern 3: Complex Tools** (Custom processing)
+- Tools with complex routing logic or non-standard processing
+- Provide `customProcessor` for full control
+- Examples: Convert, OCR
+```typescript
+return useToolOperation({
+  operationType: 'convert',
+  customProcessor: async (params, files) => { /* custom logic */ },
+});
+```
+
+**Benefits**:
+- **No Timeouts**: Operations run until completion (supports 100GB+ files)
+- **Consistent**: All tools follow same pattern and interface
+- **Maintainable**: Single responsibility hooks, easy to test and modify
+- **i18n Ready**: Built-in internationalization support
+- **Type Safe**: Full TypeScript support with generic interfaces
+- **Memory Safe**: Automatic resource cleanup and blob URL management
+
+## Architecture Overview
+
+### Project Structure
+- **Backend**: Spring Boot application
+- **Frontend**: React-based SPA in `/frontend` directory
+  - **File Storage**: IndexedDB for client-side file persistence and thumbnails
+  - **Internationalization**: JSON-based translations (converted from backend .properties)
+- **PDF Processing**: PDFBox for core PDF operations, LibreOffice for conversions, PDF.js for client-side rendering
+- **Security**: Spring Security with optional authentication (controlled by `DOCKER_ENABLE_SECURITY`)
+- **Configuration**: YAML-based configuration with environment variable overrides
+
+### Controller Architecture
+- **API Controllers** (`src/main/java/.../controller/api/`): REST endpoints for PDF operations
+  - Organized by function: converters, security, misc, pipeline
+  - Follow pattern: `@RestController` + `@RequestMapping("/api/v1/...")`
+
+### Key Components
+- **SPDFApplication.java**: Main application class with desktop UI and browser launching logic
+- **ConfigInitializer**: Handles runtime configuration and settings files
+- **Pipeline System**: Automated PDF processing workflows via `PipelineController`
+- **Security Layer**: Authentication, authorization, and user management (when enabled)
+
+### Frontend Directory Structure
+The frontend is organized with a clear separation of concerns:
+
+- **`frontend/src/core/`**: Main application code (shared, production-ready components)
+  - **`core/components/`**: React components organized by feature
+    - `core/components/tools/`: Individual PDF tool implementations
+    - `core/components/viewer/`: PDF viewer components
+    - `core/components/pageEditor/`: Page manipulation UI
+    - `core/components/tooltips/`: Help tooltips for tools
+    - `core/components/shared/`: Reusable UI components
+  - **`core/contexts/`**: React Context providers
+    - `FileContext.tsx`: Central file state management
+    - `file/`: File reducer and selectors
+    - `toolWorkflow/`: Tool workflow state
+  - **`core/hooks/`**: Custom React hooks
+    - `hooks/tools/`: Tool-specific operation hooks (one directory per tool)
+    - `hooks/tools/shared/`: Shared hook utilities (useToolOperation, etc.)
+  - **`core/constants/`**: Application constants and configuration
+  - **`core/data/`**: Static data (tool taxonomy, etc.)
+  - **`core/services/`**: Business logic services (PDF processing, storage, etc.)
+
+- **`frontend/src/desktop/`**: Desktop-specific (Tauri) code
+- **`frontend/src/proprietary/`**: Proprietary/licensed features
+- **`frontend/src-tauri/`**: Tauri (Rust) native desktop application code
+- **`frontend/public/`**: Static assets served directly
+  - `public/locales/`: Translation JSON files
+
+### Component Architecture
+- **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/public/` (modern)
+- **Internationalization**:
+  - Backend: `messages_*.properties` files
+  - Frontend: JSON files in `frontend/public/locales/` (converted from .properties)
+  - Conversion Script: `scripts/convert_properties_to_json.py`
+
+### Configuration Modes
+- **Ultra-lite**: Basic PDF operations only
+- **Standard**: Full feature set
+- **Fat**: Pre-downloaded dependencies for air-gapped environments
+- **Security Mode**: Adds authentication, user management, and enterprise features
+
+### Testing Strategy
+- **Integration Tests**: Cucumber tests in `testing/cucumber/`
+- **Docker Testing**: `test.sh` validates all Docker variants
+- **Manual Testing**: No unit tests currently - relies on UI and API testing
+
+## Development Workflow
+
+1. **Local Development**:
+   - Backend: `./gradlew bootRun` (runs on localhost:8080)
+   - Frontend: `cd frontend && npm run dev` (runs on localhost:5173, proxies to backend)
+2. **Docker Testing**: Use `./test.sh` before submitting PRs
+3. **Code Style**: Spotless enforces Google Java Format automatically
+4. **Translations**:
+   - Backend: Use helper scripts in `/scripts` for multi-language updates
+   - Frontend: Update JSON files in `frontend/public/locales/` or use conversion script
+5. **Documentation**: API docs auto-generated and available at `/swagger-ui/index.html`
+
+## Frontend Architecture Status
+
+- **Core Status**: React SPA architecture complete with multi-tool workflow support
+- **State Management**: FileContext handles all file operations and tool navigation
+- **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
+- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
+  - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
+  - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker`
+  - Pattern: Each tool creates focused operation hook, UI consumes state/actions
+- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
+- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
+
+## Translation Rules
+
+- **CRITICAL**: Always update translations in `en-GB` only, never `en-US`
+- Translation files are located in `frontend/public/locales/`
+
+## Important Notes
+
+- **Java Version**: Minimum JDK 21, supports and recommends JDK 25
+- **Lombok**: Used extensively - ensure IDE plugin is installed
+- **File Persistence**:
+  - **Backend**: Designed to be stateless - files are processed in memory/temp locations only
+  - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails)
+- **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation
+- **Import Paths**: ALWAYS use `@app/*` for imports - never use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer
+- **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling
+- **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code
+- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
+- **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
+- **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
+- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
+
+## Communication Style
+- Be direct and to the point
+- No apologies or conversational filler
+- Answer questions directly without preamble
+- Explain reasoning concisely when asked
+- Avoid unnecessary elaboration
+
+## Decision Making
+- Ask clarifying questions before making assumptions
+- Stop and ask when uncertain about project-specific details
+- Confirm approach before making structural changes
+- Request guidance on preferences (cross-platform vs specific tools, etc.)
+- Verify understanding of requirements before proceeding
@@ -1,337 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Common Development Commands
-
-### Build and Test
- **Build project**: `./gradlew clean build`
- **Run locally**: `./gradlew bootRun`
- **Full test suite**: `./test.sh` (builds all Docker variants and runs comprehensive tests)
- **Code formatting**: `./gradlew spotlessApply` (runs automatically before compilation)
-
-### Docker Development
- **Build ultra-lite**: `docker build -t stirlingtools/stirling-pdf:latest-ultra-lite -f ./Dockerfile.ultra-lite .`
- **Build standard**: `docker build -t stirlingtools/stirling-pdf:latest -f ./Dockerfile .`
- **Build fat version**: `docker build -t stirlingtools/stirling-pdf:latest-fat -f ./Dockerfile.fat .`
- **Example compose files**: Located in `exampleYmlFiles/` directory
-
-### Security Mode Development
-Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security features during development. This is required for testing the full version locally.
-
-### Frontend Development
- **Frontend dev server**: `cd frontend && npm run dev` (requires backend on localhost:8080)
- **Tech Stack**: Vite + React + TypeScript + Mantine UI + TailwindCSS
- **Proxy Configuration**: Vite proxies `/api/*` calls to backend (localhost:8080)
- **Build Process**: DO NOT run build scripts manually - builds are handled by CI/CD pipelines
- **Package Installation**: DO NOT run npm install commands - package management handled separately
- **Deployment Options**:
-  - **Desktop App**: `npm run tauri-build` (native desktop application)
-  - **Web Server**: `npm run build` then serve dist/ folder
-  - **Development**: `npm run tauri-dev` for desktop dev mode
-
-#### Import Paths - CRITICAL
-**ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.
-
-```typescript
-// ✅ CORRECT - Use @app/* for all imports
-import { AppLayout } from "@app/components/AppLayout";
-import { useFileContext } from "@app/contexts/FileContext";
-import { FileContext } from "@app/contexts/FileContext";
-
-// ❌ WRONG - Do not use @core/* or @proprietary/* in normal code
-import { AppLayout } from "@core/components/AppLayout";
-import { useFileContext } from "@proprietary/contexts/FileContext";
-```
-
-**Only use explicit aliases when:**
- Building layer-specific override that wraps a lower layer's component
- Example: `import { AppProviders as CoreAppProviders } from "@core/components/AppProviders"` when creating proprietary/AppProviders.tsx that extends the core version
-
-The `@app/*` alias automatically resolves to the correct layer based on build target (core/proprietary/desktop) and handles the fallback cascade.
-
-#### Component Override Pattern (Stub/Shadow)
-Use this pattern for desktop-specific or proprietary-specific features WITHOUT runtime checks or conditionals.
-
-**How it works:**
-1. Core defines stub component (returns null or no-op)
-2. Desktop/proprietary overrides with same path/name
-3. Core imports via `@app/*` - higher layer "shadows" core in those builds
-4. No `@ts-ignore`, no `isTauri()` checks, no runtime conditionals!
-
-**Example - Desktop-specific footer:**
-
-```typescript
-// core/components/rightRail/RightRailFooterExtensions.tsx (stub)
-interface RightRailFooterExtensionsProps {
-  className?: string;
-}
-
-export function RightRailFooterExtensions(_props: RightRailFooterExtensionsProps) {
-  return null; // Stub - does nothing in web builds
-}
-```
-
-```typescript
-// desktop/components/rightRail/RightRailFooterExtensions.tsx (real implementation)
-import { Box } from '@mantine/core';
-import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
-
-interface RightRailFooterExtensionsProps {
-  className?: string;
-}
-
-export function RightRailFooterExtensions({ className }: RightRailFooterExtensionsProps) {
-  return (
-    <Box className={className}>
-      <BackendHealthIndicator />
-    </Box>
-  );
-}
-```
-
-```typescript
-// core/components/shared/RightRail.tsx (usage - works in ALL builds)
-import { RightRailFooterExtensions } from '@app/components/rightRail/RightRailFooterExtensions';
-
-export function RightRail() {
-  return (
-    <div>
-      {/* In web builds: renders nothing (stub returns null) */}
-      {/* In desktop builds: renders BackendHealthIndicator */}
-      <RightRailFooterExtensions className="right-rail-footer" />
-    </div>
-  );
-}
-```
-
-**Build resolution:**
- **Core build**: `@app/*` → `core/*` → Gets stub (returns null)
- **Desktop build**: `@app/*` → `desktop/*` → Gets real implementation (shadows core)
-
-**Benefits:**
- No runtime checks or feature flags
- Type-safe across all builds
- Clean, readable code
- Build-time optimization (dead code elimination)
-
-#### Multi-Tool Workflow Architecture
-Frontend designed for **stateful document processing**:
- Users upload PDFs once, then chain tools (split → merge → compress → view)
- File state and processing results persist across tool switches
- No file reloading between tools - performance critical for large PDFs (up to 100GB+)
-
-#### FileContext - Central State Management
-**Location**: `frontend/src/core/contexts/FileContext.tsx`
- **Active files**: Currently loaded PDFs and their variants
- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
- **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
- **IndexedDB persistence**: File storage with thumbnail caching
- **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
-
-**Critical**: All file operations go through FileContext. Don't bypass with direct file handling.
-
-#### Processing Services
- **enhancedPDFProcessingService**: Background PDF parsing and manipulation
- **thumbnailGenerationService**: Web Worker-based with main-thread fallback
- **fileStorage**: IndexedDB with LRU cache management
-
-#### Memory Management Strategy
-**Why manual cleanup exists**: Large PDFs (up to 100GB+) through multiple tools accumulate:
- PDF.js documents that need explicit .destroy() calls
- Blob URLs from tool outputs that need revocation
- Web Workers that need termination
-Without cleanup: browser crashes with memory leaks.
-
-#### Tool Development
-
-**Architecture**: Modular hook-based system with clear separation of concerns:
-
- **useToolOperation** (`frontend/src/core/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook
-  - Coordinates all tool operations with consistent interface
-  - Integrates with FileContext for operation tracking
-  - Handles validation, error handling, and UI state management
-
- **Supporting Hooks**:
-  - **useToolState**: UI state management (loading, progress, error, files)
-  - **useToolApiCalls**: HTTP requests and file processing
-  - **useToolResources**: Blob URLs, thumbnails, ZIP downloads
-
- **Utilities**:
-  - **toolErrorHandler**: Standardized error extraction and i18n support
-  - **toolResponseProcessor**: API response handling (single/zip/custom)
-  - **toolOperationTracker**: FileContext integration utilities
-
-**Three Tool Patterns**:
-
-**Pattern 1: Single-File Tools** (Individual processing)
- Backend processes one file per API call
- Set `multiFileEndpoint: false`
- Examples: Compress, Rotate
-```typescript
-return useToolOperation({
-  operationType: 'compress',
-  endpoint: '/api/v1/misc/compress-pdf',
-  buildFormData: (params, file: File) => { /* single file */ },
-  multiFileEndpoint: false,
-});
-```
-
-**Pattern 2: Multi-File Tools** (Batch processing)
- Backend accepts `MultipartFile[]` arrays in single API call
- Set `multiFileEndpoint: true`
- Examples: Split, Merge, Overlay
-```typescript
-return useToolOperation({
-  operationType: 'split',
-  endpoint: '/api/v1/general/split-pages',
-  buildFormData: (params, files: File[]) => { /* all files */ },
-  multiFileEndpoint: true,
-  filePrefix: 'split_',
-});
-```
-
-**Pattern 3: Complex Tools** (Custom processing)
- Tools with complex routing logic or non-standard processing
- Provide `customProcessor` for full control
- Examples: Convert, OCR
-```typescript
-return useToolOperation({
-  operationType: 'convert',
-  customProcessor: async (params, files) => { /* custom logic */ },
-});
-```
-
-**Benefits**:
- **No Timeouts**: Operations run until completion (supports 100GB+ files)
- **Consistent**: All tools follow same pattern and interface
- **Maintainable**: Single responsibility hooks, easy to test and modify
- **i18n Ready**: Built-in internationalization support
- **Type Safe**: Full TypeScript support with generic interfaces
- **Memory Safe**: Automatic resource cleanup and blob URL management
-
-## Architecture Overview
-
-### Project Structure
- **Backend**: Spring Boot application
- **Frontend**: React-based SPA in `/frontend` directory
-  - **File Storage**: IndexedDB for client-side file persistence and thumbnails
-  - **Internationalization**: JSON-based translations (converted from backend .properties)
- **PDF Processing**: PDFBox for core PDF operations, LibreOffice for conversions, PDF.js for client-side rendering
- **Security**: Spring Security with optional authentication (controlled by `DOCKER_ENABLE_SECURITY`)
- **Configuration**: YAML-based configuration with environment variable overrides
-
-### Controller Architecture
- **API Controllers** (`src/main/java/.../controller/api/`): REST endpoints for PDF operations
-  - Organized by function: converters, security, misc, pipeline
-  - Follow pattern: `@RestController` + `@RequestMapping("/api/v1/...")`
-
-### Key Components
- **SPDFApplication.java**: Main application class with desktop UI and browser launching logic
- **ConfigInitializer**: Handles runtime configuration and settings files
- **Pipeline System**: Automated PDF processing workflows via `PipelineController`
- **Security Layer**: Authentication, authorization, and user management (when enabled)
-
-### Frontend Directory Structure
-The frontend is organized with a clear separation of concerns:
-
- **`frontend/src/core/`**: Main application code (shared, production-ready components)
-  - **`core/components/`**: React components organized by feature
-    - `core/components/tools/`: Individual PDF tool implementations
-    - `core/components/viewer/`: PDF viewer components
-    - `core/components/pageEditor/`: Page manipulation UI
-    - `core/components/tooltips/`: Help tooltips for tools
-    - `core/components/shared/`: Reusable UI components
-  - **`core/contexts/`**: React Context providers
-    - `FileContext.tsx`: Central file state management
-    - `file/`: File reducer and selectors
-    - `toolWorkflow/`: Tool workflow state
-  - **`core/hooks/`**: Custom React hooks
-    - `hooks/tools/`: Tool-specific operation hooks (one directory per tool)
-    - `hooks/tools/shared/`: Shared hook utilities (useToolOperation, etc.)
-  - **`core/constants/`**: Application constants and configuration
-  - **`core/data/`**: Static data (tool taxonomy, etc.)
-  - **`core/services/`**: Business logic services (PDF processing, storage, etc.)
-
- **`frontend/src/desktop/`**: Desktop-specific (Tauri) code
- **`frontend/src/proprietary/`**: Proprietary/licensed features
- **`frontend/src-tauri/`**: Tauri (Rust) native desktop application code
- **`frontend/public/`**: Static assets served directly
-  - `public/locales/`: Translation JSON files
-
-### Component Architecture
- **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/public/` (modern)
- **Internationalization**:
-  - Backend: `messages_*.properties` files
-  - Frontend: JSON files in `frontend/public/locales/` (converted from .properties)
-  - Conversion Script: `scripts/convert_properties_to_json.py`
-
-### Configuration Modes
- **Ultra-lite**: Basic PDF operations only
- **Standard**: Full feature set
- **Fat**: Pre-downloaded dependencies for air-gapped environments
- **Security Mode**: Adds authentication, user management, and enterprise features
-
-### Testing Strategy
- **Integration Tests**: Cucumber tests in `testing/cucumber/`
- **Docker Testing**: `test.sh` validates all Docker variants
- **Manual Testing**: No unit tests currently - relies on UI and API testing
-
-## Development Workflow
-
-1. **Local Development**:
-   - Backend: `./gradlew bootRun` (runs on localhost:8080)
-   - Frontend: `cd frontend && npm run dev` (runs on localhost:5173, proxies to backend)
-2. **Docker Testing**: Use `./test.sh` before submitting PRs
-3. **Code Style**: Spotless enforces Google Java Format automatically
-4. **Translations**:
-   - Backend: Use helper scripts in `/scripts` for multi-language updates
-   - Frontend: Update JSON files in `frontend/public/locales/` or use conversion script
-5. **Documentation**: API docs auto-generated and available at `/swagger-ui/index.html`
-
-## Frontend Architecture Status
-
- **Core Status**: React SPA architecture complete with multi-tool workflow support
- **State Management**: FileContext handles all file operations and tool navigation
- **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
-  - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
-  - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker`
-  - Pattern: Each tool creates focused operation hook, UI consumes state/actions
- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
-
-## Translation Rules
-
- **CRITICAL**: Always update translations in `en-GB` only, never `en-US`
- Translation files are located in `frontend/public/locales/`
-
-## Important Notes
-
- **Java Version**: Minimum JDK 17, supports and recommends JDK 21
- **Lombok**: Used extensively - ensure IDE plugin is installed
- **File Persistence**:
-  - **Backend**: Designed to be stateless - files are processed in memory/temp locations only
-  - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails)
- **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation
- **Import Paths**: ALWAYS use `@app/*` for imports - never use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer
- **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling
- **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code
- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
- **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
- **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
-
-## Communication Style
- Be direct and to the point
- No apologies or conversational filler
- Answer questions directly without preamble
- Explain reasoning concisely when asked
- Avoid unnecessary elaboration
-
-## Decision Making
- Ask clarifying questions before making assumptions
- Stop and ask when uncertain about project-specific details
- Confirm approach before making structural changes
- Request guidance on preferences (cross-platform vs specific tools, etc.)
- Verify understanding of requirements before proceeding
@@ -0,0 +1 @@
+AGENTS.md
@@ -11,7 +11,7 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
 **Stirling 2.0** is built using:

 **Backend:**
- Spring Boot (Java 17+, JDK 21 recommended)
+- Spring Boot (Java 21+, JDK 25 recommended)
 - PDFBox for core PDF operations
 - LibreOffice for document conversions
 - qpdf for PDF optimization
@@ -44,7 +44,7 @@ This guide focuses on developing for Stirling 2.0, including both the React fron

 - Docker
 - Git
- Java JDK 17 or later (JDK 21 recommended)
+- Java JDK 21 or later (JDK 25 recommended)
 - Node.js 18+ and npm (required for frontend development)
 - Gradle 7.0 or later (Included within the repo)
 - Rust and Cargo (required for Tauri desktop app development)
@@ -59,7 +59,7 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
   cd Stirling-PDF
   ```

-2. Install Docker and JDK17 if not already installed.
+2. Install Docker and JDK 21 (or JDK 25 recommended) if not already installed.

 3. Install a recommended Java IDE such as Eclipse, IntelliJ, or VSCode
   1. Only VSCode
@@ -0,0 +1,444 @@
+# File Sharing Feature - Architecture & Workflow
+
+## Overview
+
+The File Sharing feature enables users to store files server-side and share them with other registered users or via token-based share links. Files are stored using a pluggable storage provider (local filesystem or database) with optional quota enforcement.
+
+**Key Capabilities:**
+- Server-side file storage (upload, update, download, delete)
+- Optional history bundle and audit log attachments per file
+- Direct user-to-user sharing with access roles
+- Token-based share links (requires `system.frontendUrl`)
+- Optional email notifications for shares (requires `mail.enabled`)
+- Access audit trail (tracks who accessed a share link and how)
+- Automatic share link expiration
+- Storage quotas (per-user and total)
+- Pluggable storage backend (local filesystem or database BLOB)
+- Integration with the Shared Signing workflow
+
+## Architecture
+
+### Database Schema
+
+**`stored_files`**
+- One record per uploaded file
+- Stores file metadata (name, content type, size, storage key)
+- Optionally links to a history bundle and audit log as separate stored objects
+- `workflow_session_id` — nullable link to a `WorkflowSession` (signing feature)
+- `file_purpose` — enum classifying the file's role: `GENERIC`, `SIGNING_ORIGINAL`, `SIGNING_SIGNED`, `SIGNING_HISTORY`
+
+**`file_shares`**
+- One record per sharing relationship
+- Two share types, distinguished by which fields are set:
+  - **User share**: `shared_with_user_id` is set, `share_token` is null
+  - **Link share**: `share_token` is set (UUID), `shared_with_user_id` is null
+- `access_role` — `EDITOR`, `COMMENTER`, or `VIEWER`
+- `expires_at` — nullable expiration for link shares
+- `workflow_participant_id` — when set, marks this as a **workflow share** (hidden from the file manager, accessible only via workflow endpoints)
+
+**`file_share_accesses`**
+- One record per access event on a share link
+- Tracks: user, share link, access type (`VIEW` or `DOWNLOAD`), timestamp
+
+**`storage_cleanup_entries`**
+- Queue of storage keys to be deleted asynchronously
+- Used when a file is deleted but the physical storage object cleanup is deferred
+
+### Access Roles
+
+| Role | Can Read | Can Write |
+|------|----------|-----------|
+| `EDITOR` | ✅ | ✅ |
+| `COMMENTER` | ✅ | ❌ |
+| `VIEWER` | ✅ | ❌ |
+
+Default role when none is specified: `EDITOR`.
+
+Owners always have full access regardless of role.
+
+#### Role Semantics: COMMENTER vs VIEWER
+
+In the file storage layer, `COMMENTER` and `VIEWER` are equivalent — both grant read-only access and neither can replace file content. The distinction is meaningful in the **signing workflow** context:
+
+| Context | COMMENTER | VIEWER |
+|---------|-----------|--------|
+| File storage | Read only (same as VIEWER) | Read only |
+| Signing workflow | Can submit a signing action | Read only |
+
+`WorkflowParticipant.canEdit()` returns `true` for `COMMENTER` (and `EDITOR`) roles, which the signing workflow uses to determine if a participant can still submit a signature. Once a participant has signed or declined, their effective role is automatically downgraded to `VIEWER` regardless of their configured role.
+
+The rationale: "annotating" a document (submitting a signature) is not the same as "replacing" it. COMMENTER grants annotation rights without file-replacement rights.
+
+### Backend Architecture
+
+#### Service Layer
+
+**FileStorageService** (`1137 lines`)
+- Core file management service
+- Upload, update, download, and delete operations
+- User share management (share, revoke, leave)
+- Link share management (create, revoke, access)
+- Access recording and listing
+- Storage quota enforcement
+- Configuration feature gate checks
+
+**StorageCleanupService**
+- Scheduled daily: deletes orphaned storage keys from `storage_cleanup_entries`
+- Scheduled daily: purges expired share links from `file_shares`
+- Processes cleanup in batches of 50 entries
+
+#### Storage Providers
+
+**LocalStorageProvider**
+- Files stored on the filesystem under `storage.local.basePath` (default: `./storage`)
+- Storage key is a path relative to the base directory
+
+**DatabaseStorageProvider**
+- Files stored as BLOBs in `stored_file_blobs` table
+- No filesystem dependency
+
+Provider is selected at startup via `storage.provider: local | database`.
+
+#### Controller Layer
+
+**FileStorageController** (`/api/v1/storage`)
+- All endpoints require authentication
+- File CRUD and sharing operations
+
+### Data Flow
+
+```
+User uploads file → StorageProvider stores bytes → StoredFile record created
+       ↓
+Owner shares file → FileShare record created (user or link)
+       ↓
+Recipient accesses file → Access recorded → File bytes streamed
+```
+
+## File Operations
+
+### Upload File
+
+```bash
+POST /api/v1/storage/files
+Content-Type: multipart/form-data
+
+file: document.pdf                # Required — main file
+historyBundle: history.json       # Optional — version history
+auditLog: audit.json              # Optional — audit trail
+```
+
+**Response:**
+```json
+{
+  "id": 42,
+  "fileName": "document.pdf",
+  "contentType": "application/pdf",
+  "sizeBytes": 102400,
+  "owner": "alice",
+  "ownedByCurrentUser": true,
+  "accessRole": "editor",
+  "createdAt": "2025-01-01T12:00:00",
+  "updatedAt": "2025-01-01T12:00:00",
+  "sharedWithUsers": [],
+  "sharedUsers": [],
+  "shareLinks": []
+}
+```
+
+### Update File
+
+Replaces the file content. Only the owner can update.
+
+```bash
+PUT /api/v1/storage/files/{fileId}
+Content-Type: multipart/form-data
+
+file: document_v2.pdf
+historyBundle: history.json       # Optional
+auditLog: audit.json              # Optional
+```
+
+### List Files
+
+Returns all files owned by or shared with the current user. Workflow-shared files (signing participants) are excluded — those are accessible via signing endpoints only.
+
+```bash
+GET /api/v1/storage/files
+```
+
+Response is sorted by `createdAt` descending.
+
+### Download File
+
+```bash
+GET /api/v1/storage/files/{fileId}/download?inline=false
+```
+
+- `inline=false` (default) — `Content-Disposition: attachment`
+- `inline=true` — `Content-Disposition: inline` (for browser preview)
+
+### Delete File
+
+Only the owner can delete. All associated share links and their access records are deleted first, then the database record, then the physical storage object.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}
+```
+
+## Sharing Operations
+
+### Share with User
+
+```bash
+POST /api/v1/storage/files/{fileId}/shares/users
+Content-Type: application/json
+
+{
+  "username": "bob",          # Username or email address
+  "accessRole": "editor"      # "editor", "commenter", or "viewer" (default: "editor")
+}
+```
+
+**Behaviour:**
+- If the target user exists: creates/updates a `FileShare` with `sharedWithUser` set
+- If `username` is an email address and the user doesn't exist: creates a share link and sends a notification email (requires `sharing.emailEnabled` and `sharing.linkEnabled`)
+- If the target user is the owner: returns 400
+- If sharing is disabled: returns 403
+
+### Revoke User Share
+
+Only the owner can revoke.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/users/{username}
+```
+
+### Leave Shared File
+
+The recipient removes themselves from a shared file.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/self
+```
+
+### Create Share Link
+
+Creates a token-based link for anonymous/authenticated access. Requires `sharing.linkEnabled` and `system.frontendUrl` to be configured.
+
+```bash
+POST /api/v1/storage/files/{fileId}/shares/links
+Content-Type: application/json
+
+{
+  "accessRole": "viewer"      # Optional (default: "editor")
+}
+```
+
+**Response:**
+```json
+{
+  "token": "550e8400-e29b-41d4-a716-446655440000",
+  "accessRole": "viewer",
+  "createdAt": "2025-01-01T12:00:00",
+  "expiresAt": "2025-01-04T12:00:00"
+}
+```
+
+Expiration is set to `now + sharing.linkExpirationDays` (default: 3 days).
+
+### Revoke Share Link
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/links/{token}
+```
+
+Also deletes all access records for that token.
+
+## Share Link Access
+
+### Download via Share Link
+
+Authentication is required (even for share links). Anonymous access is not permitted.
+
+```bash
+GET /api/v1/storage/share-links/{token}?inline=false
+```
+
+- Returns 401 if unauthenticated
+- Returns 403 if authenticated but link doesn't permit access
+- Returns 410 if the link has expired
+- Records a `FileShareAccess` entry on success
+
+> **Token-as-credential semantics:** Any authenticated user who holds the token can access the file — the token is the credential. If you need per-user access control (only a specific person can open it), use "Share with User" instead. Share links are appropriate for broader distribution where possession of the token implies authorization.
+
+### Get Share Link Metadata
+
+```bash
+GET /api/v1/storage/share-links/{token}/metadata
+```
+
+Returns file name, owner, access role, creation/expiry timestamps, and whether the current user owns the file.
+
+### List Accessed Share Links
+
+Returns the most recent access for each non-expired share link the current user has accessed.
+
+```bash
+GET /api/v1/storage/share-links/accessed
+```
+
+### List Accesses for a Link (Owner Only)
+
+```bash
+GET /api/v1/storage/files/{fileId}/shares/links/{token}/accesses
+```
+
+Returns per-user access history (username, VIEW/DOWNLOAD, timestamp), sorted descending by time.
+
+## Workflow Share Integration
+
+Signing workflow participants access documents via their own `WorkflowParticipant.shareToken`. No `FileShare` record is created for participants; access control is self-contained in the `WorkflowParticipant` entity.
+
+The `FileShare.workflow_participant_id` column and the `FileShare.isWorkflowShare()` method are **deprecated**. Legacy data (sessions created before this change) may still have `FileShare` records with `workflow_participant_id` set, which continue to work via the existing token lookup path in `UnifiedAccessControlService`. No new records are created.
+
+`GET /api/v1/storage/files` returns all files owned by or shared with the current user (via `FileShare`). Signing-session PDFs use the `file_purpose` field (`SIGNING_ORIGINAL`, `SIGNING_SIGNED`, etc.) to distinguish them from generic files. The file manager UI can filter on this field if needed.
+
+## API Reference
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/api/v1/storage/files` | Upload file | Required |
+| PUT | `/api/v1/storage/files/{id}` | Update file | Required (owner) |
+| GET | `/api/v1/storage/files` | List accessible files | Required |
+| GET | `/api/v1/storage/files/{id}` | Get file metadata | Required |
+| GET | `/api/v1/storage/files/{id}/download` | Download file | Required |
+| DELETE | `/api/v1/storage/files/{id}` | Delete file | Required (owner) |
+| POST | `/api/v1/storage/files/{id}/shares/users` | Share with user | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/users/{username}` | Revoke user share | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/self` | Leave shared file | Required |
+| POST | `/api/v1/storage/files/{id}/shares/links` | Create share link | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/links/{token}` | Revoke share link | Required (owner) |
+| GET | `/api/v1/storage/share-links/{token}` | Download via share link | Required |
+| GET | `/api/v1/storage/share-links/{token}/metadata` | Get share link metadata | Required |
+| GET | `/api/v1/storage/share-links/accessed` | List accessed share links | Required |
+| GET | `/api/v1/storage/files/{id}/shares/links/{token}/accesses` | List share accesses | Required (owner) |
+
+## Configuration
+
+All storage settings live under the `storage:` key in `settings.yml`:
+
+```yaml
+storage:
+  enabled: true                  # Requires security.enableLogin = true
+  provider: local                # 'local' or 'database'
+  local:
+    basePath: './storage'        # Filesystem base directory (local provider only)
+  quotas:
+    maxStorageMbPerUser: -1      # Per-user storage cap in MB; -1 = unlimited
+    maxStorageMbTotal: -1        # Total storage cap in MB; -1 = unlimited
+    maxFileMb: -1                # Max size per upload (main + history + audit) in MB; -1 = unlimited
+  sharing:
+    enabled: false               # Master switch for all sharing (opt-in)
+    linkEnabled: false           # Enable token-based share links (requires system.frontendUrl)
+    emailEnabled: false          # Enable email notifications (requires mail.enabled)
+    linkExpirationDays: 3        # Days until share links expire
+```
+
+**Prerequisites:**
+- `storage.enabled` requires `security.enableLogin = true`
+- `sharing.linkEnabled` requires `system.frontendUrl` to be set (used to build share link URLs)
+- `sharing.emailEnabled` requires `mail.enabled = true`
+
+## Security Considerations
+
+### Access Control
+- All endpoints require authentication — there is no anonymous access
+- Owner-only operations enforced in service layer (not just controller)
+- `requireReadAccess` / `requireEditorAccess` checked on every download
+
+### Share Link Security
+- Tokens are UUIDs (random, not guessable)
+- Expiration enforced on every access
+- Expired links return HTTP 410 Gone
+- Revoked links delete all access records
+
+### Quota Enforcement
+- Checked before storing (not after)
+- Accounts for existing file size when replacing (only the delta counts)
+- Covers main file + history bundle + audit log in a single check
+
+## Automatic Cleanup
+
+`StorageCleanupService` runs two scheduled jobs daily:
+
+1. **Orphaned storage cleanup** — processes up to 50 `StorageCleanupEntry` records, deletes the physical storage object, then removes the entry. Failed attempts increment `attemptCount` for retry.
+
+2. **Expired share link cleanup** — deletes all `FileShare` records where `expiresAt` is in the past and `shareToken` is set.
+
+## Troubleshooting
+
+**"Storage is disabled":**
+- Check `storage.enabled: true` in settings
+- Verify `security.enableLogin: true`
+
+**"Share links are disabled":**
+- Check `sharing.linkEnabled: true`
+- Verify `system.frontendUrl` is set and non-empty
+
+**"Email sharing is disabled":**
+- Check `sharing.emailEnabled: true`
+- Verify `mail.enabled: true` and mail configuration
+
+**Signing-session PDF appearing in the general file list:**
+- This is expected — signing PDFs are accessible to owners and shared users
+- Filter by `file_purpose` (`SIGNING_ORIGINAL`, `SIGNING_SIGNED`) in the UI to distinguish them
+
+**Share link returns 410:**
+- Link has expired — check `expires_at` in `file_shares` table
+- Owner must create a new link
+
+### Debug Queries
+
+```sql
+-- List files and their share counts
+SELECT sf.stored_file_id, sf.original_filename, u.username as owner,
+       COUNT(DISTINCT fs.file_share_id) FILTER (WHERE fs.shared_with_user_id IS NOT NULL) as user_shares,
+       COUNT(DISTINCT fs.file_share_id) FILTER (WHERE fs.share_token IS NOT NULL) as link_shares
+FROM stored_files sf
+LEFT JOIN users u ON sf.owner_id = u.user_id
+LEFT JOIN file_shares fs ON fs.stored_file_id = sf.stored_file_id
+GROUP BY sf.stored_file_id, u.username;
+
+-- Check share link expiration
+SELECT share_token, access_role, created_at, expires_at,
+       expires_at < NOW() as is_expired
+FROM file_shares
+WHERE share_token IS NOT NULL;
+
+-- Check access history for a share link
+SELECT u.username, fsa.access_type, fsa.accessed_at
+FROM file_share_accesses fsa
+JOIN file_shares fs ON fsa.file_share_id = fs.file_share_id
+JOIN users u ON fsa.user_id = u.user_id
+WHERE fs.share_token = '{token}'
+ORDER BY fsa.accessed_at DESC;
+
+-- Pending cleanup entries
+SELECT storage_key, attempt_count, updated_at
+FROM storage_cleanup_entries
+ORDER BY updated_at ASC;
+```
+
+## Summary
+
+The File Sharing feature provides:
+- ✅ Server-side file storage with pluggable backend (local/database)
+- ✅ History bundle and audit log attachments per file
+- ✅ Direct user-to-user sharing with EDITOR/COMMENTER/VIEWER roles
+- ✅ Token-based share links with expiration
+- ✅ Optional email notifications for shares
+- ✅ Per-access audit trail for share links
+- ✅ Storage quotas (per-user, total, per-file)
+- ✅ Automatic cleanup of expired links and orphaned storage
+- ✅ Workflow integration (signing-session PDFs stored via same infrastructure; participant access via `WorkflowParticipant.shareToken`)
@@ -6,10 +6,14 @@ Portions of this software are licensed as follows:

 * All content that resides under the "app/proprietary/" directory of this repository,
 if that directory exists, is licensed under the license defined in "app/proprietary/LICENSE".
+* All content that resides under the "engine/" directory of this repository,
+if that directory exists, is licensed under the license defined in "engine/LICENSE".
 * All content that resides under the "frontend/src/proprietary/" directory of this repository,
 if that directory exists, is licensed under the license defined in "frontend/src/proprietary/LICENSE".
 * All content that resides under the "frontend/src/desktop/" directory of this repository,
 if that directory exists, is licensed under the license defined in "frontend/src/desktop/LICENSE".
+* All content that resides under the "frontend/src/saas/" directory of this repository,
+if that directory exists, is licensed under the license defined in "frontend/src/saas/LICENSE".
 * Content outside of the above mentioned directories or restrictions above is
 available under the MIT License as defined below.

@@ -0,0 +1,691 @@
+# Shared Signing Feature - Architecture & Workflow
+
+## Overview
+
+The Shared Signing feature enables collaborative document signing workflows where a document owner can request signatures from multiple participants. Each participant receives a secure token to access the document, submit their digital signature (with optional wet signature overlay), and track the signing progress.
+
+**Key Capabilities:**
+- Multi-participant signing sessions
+- Digital certificate signatures (P12/PKCS12, JKS, SERVER, USER_CERT, PEM/UPLOAD)
+- Visual wet signature overlays (drawn, typed, or uploaded) — multiple per participant
+- Token-based participant access (no authentication required for participants)
+- Authenticated participant access for registered users via sign-requests API
+- Progress tracking for session owners
+- Optional signature summary page appended to finalized PDF
+- Automatic role downgrade after signing (security)
+- GDPR-compliant wet signature metadata cleanup
+
+## Architecture
+
+### Database Schema
+
+#### Core Tables
+
+**`workflow_sessions`**
+- Tracks signing sessions created by document owners
+- Links to original and processed (signed) PDF files
+- Stores session metadata (message, due date, status)
+
+**`workflow_participants`**
+- One record per participant per session
+- Tracks participant status: PENDING → VIEWED → SIGNED/DECLINED
+  - `NOTIFIED` status is reserved for a future email notification feature; no current code path sets it
+- Stores participant-specific metadata (certificates, wet signatures) as JSONB
+- Each participant holds their own `shareToken` (UUID) for token-based access — no separate `FileShare` record is created
+- `accessRole` controls what actions the participant can perform. `COMMENTER` (and `EDITOR`) allow submitting a signature; `VIEWER` does not. After signing/declining, effective role is automatically downgraded to `VIEWER`
+
+**`user_server_certificates`**
+- Stores auto-generated certificates per user
+- Enables "Use My Personal Certificate" option
+
+#### Extended Tables
+
+**`stored_files`**
+- Added `workflow_session_id` to link files to signing sessions
+- Added `file_purpose` enum (SIGNING_ORIGINAL, SIGNING_SIGNED, etc.)
+
+**`file_shares`**
+- Regular file shares are created when the session owner shares the document with other users via the file manager
+- The `workflow_participant_id` column is deprecated; participant access is self-contained in `WorkflowParticipant.shareToken`
+
+### Backend Architecture
+
+#### Service Layer
+
+**WorkflowSessionService** (`816 lines`)
+- Core workflow management service
+- Creates sessions with participants
+- Handles participant status updates
+- Stores signature metadata (certificates and wet signatures)
+- Finalizes sessions by coordinating signing process
+
+Key responsibilities:
+- Session lifecycle management (create, list, get details, delete)
+- Participant management (add, remove, notify)
+- Certificate submission storage
+- Wet signature metadata storage
+- Session finalization orchestration
+
+**UnifiedAccessControlService**
+- Validates participant tokens
+- Checks session status and expiration
+- Maps participant status to effective access role
+- Automatic role downgrade after signing: SIGNED/DECLINED → VIEWER role
+
+**UserServerCertificateService**
+- Auto-generates personal certificates for users
+- Manages certificate storage and retrieval
+- Enables "Use My Personal Certificate" signing option
+
+#### Controller Layer
+
+**SigningSessionController** (Owner-facing + Authenticated participant endpoints)
+- `POST /api/v1/security/cert-sign/sessions` - Create signing session
+- `GET /api/v1/security/cert-sign/sessions` - List user's sessions
+- `GET /api/v1/security/cert-sign/sessions/{id}` - Get session details
+- `GET /api/v1/security/cert-sign/sessions/{id}/pdf` - Download original PDF
+- `POST /api/v1/security/cert-sign/sessions/{id}/finalize` - Finalize and apply signatures
+- `GET /api/v1/security/cert-sign/sessions/{id}/signed-pdf` - Download signed PDF
+- `DELETE /api/v1/security/cert-sign/sessions/{id}` - Delete session
+- `POST /api/v1/security/cert-sign/sessions/{id}/participants` - Add participants
+- `DELETE /api/v1/security/cert-sign/sessions/{id}/participants/{participantId}` - Remove participant
+- `GET /api/v1/security/cert-sign/sign-requests` - List sign requests for authenticated user
+- `GET /api/v1/security/cert-sign/sign-requests/{id}` - Get sign request details
+- `GET /api/v1/security/cert-sign/sign-requests/{id}/document` - Download document for signing
+- `POST /api/v1/security/cert-sign/sign-requests/{id}/sign` - Sign document (authenticated)
+- `POST /api/v1/security/cert-sign/sign-requests/{id}/decline` - Decline sign request (authenticated)
+
+**WorkflowParticipantController** (Participant-facing, token-based)
+- `GET /api/v1/workflow/participant/session?token={token}` - View session details
+- `GET /api/v1/workflow/participant/details?token={token}` - Get participant details
+- `GET /api/v1/workflow/participant/document?token={token}` - Download PDF
+- `POST /api/v1/workflow/participant/submit-signature` - Submit signature
+- `POST /api/v1/workflow/participant/decline?token={token}` - Decline to sign
+
+#### Data Flow
+
+```
+Owner creates session → Participants receive tokens →
+Participants access via token (or authenticated) → Participants submit signatures →
+Owner finalizes → System applies signatures → [Optional: append summary page] → Signed PDF generated
+```
+
+### Frontend Architecture
+
+#### Quick Access Integration
+
+**SignPopout Component**
+- Displays in Quick Access Bar (top navigation)
+- Shows active and completed signing sessions
+- Auto-refreshes every 15 seconds to show signature progress
+- Badge indicator shows count of pending sessions
+
+**ActiveSessionsPanel**
+- Lists sessions where user is owner or participant
+- Shows signature progress: "X/Y signatures" (e.g., "2/5 signatures")
+- Color-coded badges:
+  - Blue: No signatures yet (0/X)
+  - Yellow: Partial signatures (X/Y)
+  - Green: Ready to finalize (X/X)
+
+**CompletedSessionsPanel**
+- Lists finalized sessions and declined sign requests
+- Allows viewing/downloading signed PDFs
+
+#### Workbench Views
+
+**SignRequestWorkbenchView**
+- Full-screen view for participants to sign documents
+- Integrated PDF viewer with annotation support
+- Certificate selection (Personal/Organization/Custom P12)
+- Wet signature input (draw, type, or upload)
+- Signature placement on PDF pages
+
+**SessionDetailWorkbenchView**
+- Owner's view of session details
+- Participant list with status indicators
+- Ability to add/remove participants
+- Finalize button when all signatures collected
+- Download original/signed PDF
+
+#### State Management
+
+**FileContext Integration**
+- Signing sessions operate within FileContext workflow
+- PDFs loaded once, persist across tool switches
+- Memory management for large files (up to 100GB+)
+
+**ToolWorkflowContext**
+- Registers custom workbench views
+- Manages navigation between viewer and signing tools
+- Preserves file state during signing operations
+
+#### Services & Hooks
+
+**workflowService.ts**
+- API client for all signing endpoints
+- Handles session creation, listing, and management
+- Participant operations (submit, decline)
+
+**useWorkflowSession.ts**
+- React hook for owner session management
+- State management for session list and details
+
+**useParticipantSession.ts**
+- React hook for participant signing workflow
+- Manages signature submission state
+
+## Signing Workflow Process
+
+### 1. Session Creation (Owner)
+
+```
+Owner → Uploads PDF → Selects participants → Creates session
+        ↓
+System creates:
+  - WorkflowSession record
+  - WorkflowParticipant records (one per participant, each with a unique shareToken)
+        ↓
+Participants receive token (via email or share link)
+```
+
+**API Call:**
+```bash
+POST /api/v1/security/cert-sign/sessions
+Content-Type: multipart/form-data
+
+file: document.pdf
+workflowType: SIGNING
+documentName: "contract.pdf"           # Optional display name
+participantUserIds: [1, 2, 3]          # Registered user IDs
+participantEmails: ["a@b.com"]         # External/unregistered users
+participants: [...]                    # Detailed participant configs (optional)
+message: "Please sign this contract"
+dueDate: "2025-12-31"
+ownerEmail: "owner@example.com"        # Optional, for notifications
+workflowMetadata: '{"showSignature": false, "showLogo": false, "includeSummaryPage": true}'
+```
+
+**Session-level `workflowMetadata` fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `showSignature` | boolean | Show visible digital signature block on PDF |
+| `pageNumber` | integer | Page to place digital signature on |
+| `showLogo` | boolean | Show logo in digital signature block |
+| `includeSummaryPage` | boolean | Append a signature summary page before digital signing |
+
+**Response:**
+```json
+{
+  "sessionId": "uuid",
+  "documentName": "contract.pdf",
+  "participants": [
+    {
+      "userId": 1,
+      "email": "user1@example.com",
+      "shareToken": "token1",
+      "status": "PENDING"
+    }
+  ],
+  "participantCount": 3,
+  "signedCount": 0
+}
+```
+
+### 2. Participant Access
+
+```
+Participant → Clicks token link → Views session details
+        ↓
+Status changes: PENDING/NOTIFIED → VIEWED
+        ↓
+Participant downloads PDF to review
+```
+
+**Access URL (unauthenticated):**
+```
+https://app.example.com/sign?token={participant_token}
+```
+
+**Authenticated participants** can also use:
+```
+GET /api/v1/security/cert-sign/sign-requests
+GET /api/v1/security/cert-sign/sign-requests/{sessionId}
+GET /api/v1/security/cert-sign/sign-requests/{sessionId}/document
+```
+
+**Automatic Status Update:**
+- First access: PENDING/NOTIFIED → VIEWED
+- Downloads tracked but don't change status
+
+### 3. Signature Submission
+
+```
+Participant → Selects certificate type → Uploads certificate (if needed)
+           → Draws/uploads wet signatures (optional, multiple supported)
+           → Submits signature
+        ↓
+System stores:
+  - Certificate data (P12/JKS keystore as base64)
+  - Certificate password
+  - Wet signatures metadata (JSON array: base64 image + coordinates per signature)
+        ↓
+Status changes: VIEWED → SIGNED
+Access role: EDITOR → VIEWER (automatic downgrade)
+```
+
+**API Call (token-based, unauthenticated):**
+```bash
+POST /api/v1/workflow/participant/submit-signature
+Content-Type: multipart/form-data
+
+participantToken: {token}
+certType: P12 | JKS | SERVER | USER_CERT
+p12File: certificate.p12 (if certType=P12)
+jksFile: keystore.jks (if certType=JKS)
+password: cert_password
+showSignature: false
+pageNumber: 1
+location: "New York"
+reason: "I approve this contract"
+showLogo: false
+wetSignaturesData: '[{"page":0,"x":100,"y":200,"width":150,"height":50,"type":"IMAGE","data":"base64..."}]'
+```
+
+**API Call (authenticated users):**
+```bash
+POST /api/v1/security/cert-sign/sign-requests/{sessionId}/sign
+Content-Type: multipart/form-data
+
+certType: SERVER | USER_CERT | UPLOAD | PEM | PKCS12 | PFX | JKS
+p12File: certificate.p12 (if applicable)
+password: cert_password
+reason: "I approve this contract"
+location: "New York"
+wetSignaturesData: '[...]'
+```
+
+**Metadata Storage (JSONB):**
+```json
+{
+  "certificateSubmission": {
+    "certType": "P12",
+    "password": "cert_password",
+    "p12Keystore": "base64_encoded_keystore",
+    "showSignature": false,
+    "pageNumber": 1,
+    "location": "New York",
+    "reason": "I approve this contract",
+    "showLogo": false
+  },
+  "wetSignatures": [
+    {
+      "type": "IMAGE",
+      "data": "base64_image",
+      "page": 0,
+      "x": 100,
+      "y": 200,
+      "width": 150,
+      "height": 50
+    }
+  ]
+}
+```
+
+Note: Multiple wet signatures are supported per participant (array).
+
+### 4. Progress Tracking (Owner)
+
+```
+Owner → Views session list → Sees "2/5 signatures"
+      → Clicks session → Views participant status
+        ↓
+Participant list shows:
+  - user1@example.com: SIGNED ✓
+  - user2@example.com: SIGNED ✓
+  - user3@example.com: VIEWED (pending)
+  - user4@example.com: PENDING
+  - user5@example.com: DECLINED ✗
+        ↓
+Auto-refresh every 15 seconds
+```
+
+**Badge Colors:**
+- 🔵 Blue: 0/5 signatures (awaiting)
+- 🟡 Yellow: 2/5 signatures (partial)
+- 🟢 Green: 5/5 signatures (ready to finalize)
+
+### 5. Session Finalization
+
+```
+Owner → Clicks "Finalize" → System processes signatures
+        ↓
+Processing steps:
+  1. Apply wet signatures to PDF (visual overlays)
+  1.5. Append signature summary page (if includeSummaryPage=true)
+  2. Apply digital certificates in participant order
+     - Visual signature block suppressed when summary page is enabled
+  3. Store signed PDF
+  4. Clear wet signature metadata (GDPR compliance)
+        ↓
+Owner downloads signed PDF
+```
+
+**Finalization Process:**
+
+1. **Apply Wet Signatures First**
+   ```java
+   for (WetSignature sig : wetSignatures) {
+     PDPage page = document.getPage(sig.getPage());
+     byte[] imageBytes = Base64.decode(sig.getData());
+     // Convert Y from top-left (UI) to bottom-left (PDF) coordinate system
+     float pdfY = page.getMediaBox().getHeight() - sig.getY() - sig.getHeight();
+     PDImageXObject image = PDImageXObject.createFromByteArray(document, imageBytes, "signature");
+     contentStream.drawImage(image, sig.getX(), pdfY, sig.getWidth(), sig.getHeight());
+   }
+   ```
+
+2. **Append Summary Page (optional, before digital signing)**
+
+   If `includeSummaryPage=true`, a new A4 page is appended showing:
+   - Stirling logo and "Signature Summary" title
+   - Document name and session owner
+   - Finalization timestamp
+   - Per-participant: name, email, status, signed timestamp, reason, location, certificate type
+   - Supports overflow to additional pages
+
+   This step occurs **before** digital certificate signing so signatures are not invalidated.
+   When a summary page is added, the visual digital signature block (`showSignature`) is suppressed — wet signatures (hand-drawn overlays) are unaffected.
+
+3. **Apply Digital Certificates (in participant order)**
+   ```java
+   for (Participant p : participants) {
+     if (p.status == SIGNED) {
+       KeyStore keystore = buildKeystore(p.certificate);
+       // Reason: participant override > owner default > "Document Signing"
+       // Location: participant-provided only (no default)
+       CertSignController.sign(pdfBytes, keystore, password, settings);
+     }
+   }
+   ```
+
+4. **Store and Cleanup**
+   ```java
+   StoredFile signedFile = storeFile(signedPdfBytes, SIGNING_SIGNED);
+   session.setProcessedFile(signedFile);
+   session.setFinalized(true);
+
+   // GDPR: Clear sensitive metadata after finalization
+   for (Participant p : participants) {
+     p.metadata.remove("wetSignatures");         // Clears wet signature image data
+     p.metadata.remove("certificateSubmission"); // Clears keystore bytes + password
+   }
+   ```
+
+**API Call:**
+```bash
+POST /api/v1/security/cert-sign/sessions/{sessionId}/finalize
+Authorization: Bearer {owner_token}
+```
+
+**Response:** Binary PDF file with Content-Disposition header
+
+## Key Technical Features
+
+### 1. Double JSON Encoding Fix (Recent)
+
+**Problem:** JSONB columns were storing JSON strings instead of JSON objects, requiring double-parsing.
+
+**Solution:** Created `JsonMapConverter` JPA AttributeConverter:
+```java
+@Convert(converter = JsonMapConverter.class)
+@Column(name = "participant_metadata", columnDefinition = "jsonb")
+private Map<String, Object> participantMetadata;
+```
+
+**Benefits:**
+- Single parse on read
+- Proper JSON storage in PostgreSQL
+- Type-safe Map access
+- Backward compatible with legacy data
+
+### 2. Signature Progress Display (Recent)
+
+**Implementation:**
+- `WorkflowSessionResponse` includes `participantCount` and `signedCount`
+- `WorkflowMapper` calculates counts when converting to DTO
+- Frontend displays "X/Y signatures" in session list
+- Auto-refresh every 15 seconds keeps counts updated
+
+### 3. Token-Based Security
+
+**No Authentication Required for Participants:**
+- Participants access via secure token (UUID)
+- Token linked to specific participant and session
+- Automatic expiration support
+- One-time signing (cannot sign twice)
+
+**Authenticated Participant Access:**
+- Registered users can also access sign requests via `/api/v1/security/cert-sign/sign-requests`
+- Standard Spring Security authentication required
+- Supports additional cert types: UPLOAD, PEM, PKCS12, PFX
+
+**Automatic Role Downgrade:**
+- After signing: EDITOR → VIEWER
+- After declining: EDITOR → VIEWER
+- Prevents modification after action taken
+
+### 4. Storage Integration
+
+**Unified with File Sharing:**
+- All PDFs stored via `StorageProvider` (Database or Local)
+- Respects storage quotas
+- Supports files up to 100GB+ (with Local storage)
+- Consistent with existing file sharing infrastructure
+
+### 5. Certificate Types
+
+**P12/PKCS12/PFX:** User uploads PKCS#12 file + password
+**JKS:** User uploads Java KeyStore + password
+**PEM/UPLOAD:** User uploads PEM certificate + private key
+**SERVER:** Uses organization's server certificate (no upload needed)
+**USER_CERT:** Uses user's auto-generated personal certificate (one-click)
+
+Note: UPLOAD, PEM, PKCS12, PFX are available on the authenticated (`sign-requests`) path. The token-based path uses P12, JKS, SERVER, USER_CERT.
+
+## Frontend Components Overview
+
+### Owner Workflow Components
+
+1. **CreateSessionPanel** - Form to create new signing session
+2. **ActiveSessionsPanel** - List of pending sessions with progress
+3. **SessionDetailWorkbenchView** - Full session management interface
+4. **CompletedSessionsPanel** - History of finalized sessions
+
+### Participant Workflow Components
+
+1. **SignRequestWorkbenchView** - Main signing interface
+2. **SignatureSettingsInput** - Certificate selection and configuration
+3. **WetSignatureInput** - Draw/type/upload signature overlay
+4. **SignatureSettingsDisplay** - Preview of signature settings
+
+### Shared Components
+
+1. **UserSelector** - Multi-select user picker for participants
+2. **LocalEmbedPDFWithAnnotations** - PDF viewer with signature placement
+
+## Configuration
+
+### Backend Configuration
+
+**application.properties:**
+```properties
+# Database (H2 or PostgreSQL)
+spring.jpa.hibernate.ddl-auto=update
+
+# Security
+DOCKER_ENABLE_SECURITY=true
+
+# Storage Provider (DATABASE or LOCAL)
+storage.provider=LOCAL
+storage.maxFileSize=100GB
+```
+
+### Frontend Configuration
+
+**Quick Access Bar:**
+- Signing popout accessible from top navigation
+- Auto-refresh interval: 15 seconds
+- Badge shows pending session count
+
+## API Reference Summary
+
+### Owner Endpoints (Authenticated)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/v1/security/cert-sign/sessions` | Create session |
+| GET | `/api/v1/security/cert-sign/sessions` | List sessions |
+| GET | `/api/v1/security/cert-sign/sessions/{id}` | Get details |
+| POST | `/api/v1/security/cert-sign/sessions/{id}/finalize` | Finalize session |
+| GET | `/api/v1/security/cert-sign/sessions/{id}/pdf` | Download original |
+| GET | `/api/v1/security/cert-sign/sessions/{id}/signed-pdf` | Download signed |
+| DELETE | `/api/v1/security/cert-sign/sessions/{id}` | Delete session |
+| POST | `/api/v1/security/cert-sign/sessions/{id}/participants` | Add participants |
+| DELETE | `/api/v1/security/cert-sign/sessions/{id}/participants/{pid}` | Remove participant |
+
+### Authenticated Participant Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/security/cert-sign/sign-requests` | List sign requests |
+| GET | `/api/v1/security/cert-sign/sign-requests/{id}` | Get sign request details |
+| GET | `/api/v1/security/cert-sign/sign-requests/{id}/document` | Download document |
+| POST | `/api/v1/security/cert-sign/sign-requests/{id}/sign` | Sign document |
+| POST | `/api/v1/security/cert-sign/sign-requests/{id}/decline` | Decline signing |
+
+### Token-Based Participant Endpoints (No Auth Required)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/workflow/participant/session?token={token}` | View session |
+| GET | `/api/v1/workflow/participant/details?token={token}` | Get participant details |
+| GET | `/api/v1/workflow/participant/document?token={token}` | Download PDF |
+| POST | `/api/v1/workflow/participant/submit-signature` | Submit signature |
+| POST | `/api/v1/workflow/participant/decline?token={token}` | Decline signing |
+
+## Security Considerations
+
+### Data Protection
+- Wet signature image data cleared after finalization (GDPR compliance)
+- Certificate submission data (keystore bytes + password) cleared after finalization (GDPR compliance)
+- Certificate passwords are not encrypted at rest while stored (TODO: encrypt at rest)
+- Token expiration support
+
+### Access Control
+- Owner authentication required for session management
+- Participant access via secure UUID tokens (no auth) or standard auth (sign-requests)
+- Automatic role downgrade prevents re-signing
+- Session status checks prevent unauthorized actions
+
+### Audit Trail
+- All participant actions tracked
+- FileShare access logged
+- Status transitions recorded
+- Notification history maintained
+
+## Performance Characteristics
+
+### Scalability
+- Supports PDFs up to 100GB+ (with Local storage provider)
+- Memory-efficient streaming for large files
+- IndexedDB caching on frontend
+- Database indexes on session_id, share_token, workflow_session_id
+
+### Response Times
+- Session creation: ~500ms (10MB file)
+- Session listing: ~100ms
+- Token validation: ~50ms
+- Finalization: ~2s per MB of PDF (varies by certificate operations)
+
+## Future Enhancements
+
+### Planned Features
+- Email notifications for participants
+- Reminder system for pending signatures
+- Bulk signing operations
+- Template-based signing workflows
+- Signature validation/verification UI
+- Certificate password encryption at rest
+- Certificate keystore cleanup after finalization (GDPR)
+- Webhook support for external integrations
+- Analytics dashboard for signing metrics
+
+### Additional Workflow Types
+- **REVIEW** - Document review with comments
+- **APPROVAL** - Multi-level approval chains
+- **COLLABORATION** - Real-time collaborative editing
+
+## Troubleshooting
+
+### Common Issues
+
+**"Token invalid" error:**
+- Check token exists in workflow_participants table
+- Verify session is not finalized
+- Check expiration date (expires_at)
+
+**Signature not appearing on PDF:**
+- Verify certificate type is correct
+- Check certificate password
+- Review logs for signing errors
+- Ensure PDFDocumentFactory is available
+
+**"Awaiting signatures" not updating:**
+- Backend should return participantCount and signedCount
+- Frontend auto-refresh every 15 seconds
+- Check network tab for API errors
+
+**Wet signatures not visible after finalization:**
+- Wet signatures are applied first as image overlays (Step 1)
+- Check `wetSignaturesData` was sent as valid JSON array
+- Verify page index is within document bounds
+- Note: wet signatures survive regardless of `includeSummaryPage` setting
+
+### Debug Queries
+
+```sql
+-- Check session status
+SELECT session_id, status, finalized,
+       (SELECT COUNT(*) FROM workflow_participants WHERE workflow_session_id = ws.id) as participant_count,
+       (SELECT COUNT(*) FROM workflow_participants WHERE workflow_session_id = ws.id AND status = 'SIGNED') as signed_count
+FROM workflow_sessions ws;
+
+-- Check participant tokens
+SELECT email, status, share_token, expires_at
+FROM workflow_participants
+WHERE workflow_session_id = (SELECT id FROM workflow_sessions WHERE session_id = '{session_id}');
+
+-- Check metadata storage
+SELECT email,
+       participant_metadata->'certificateSubmission'->>'certType' as cert_type,
+       jsonb_array_length(participant_metadata->'wetSignatures') as wet_sig_count
+FROM workflow_participants;
+```
+
+## Summary
+
+The Shared Signing feature provides a complete collaborative signing workflow with:
+- ✅ Multi-participant support with progress tracking
+- ✅ Multiple certificate types (P12/PKCS12/PFX, JKS, PEM, SERVER, USER_CERT)
+- ✅ Visual wet signature overlays (multiple per participant)
+- ✅ Token-based security for unauthenticated participants
+- ✅ Authenticated participant access via sign-requests API
+- ✅ Automatic role management
+- ✅ Large file support (100GB+)
+- ✅ GDPR-compliant wet signature metadata cleanup
+- ✅ Real-time progress updates
+- ✅ Full frontend integration with Quick Access Bar
+- ✅ Optional signature summary page with logo and participant details
+
+The architecture leverages existing file sharing infrastructure while adding workflow-specific features, ensuring consistency and maintainability across the application.
@@ -5,10 +5,10 @@ bootRun {
 spotless {
    java {
        target 'src/**/java/**/*.java'
+        targetExclude 'src/main/java/org/apache/**'
        googleJavaFormat(googleJavaFormatVersion).aosp().reorderImports(false)

        importOrder("java", "javax", "org", "com", "net", "io", "jakarta", "lombok", "me", "stirling")
-        toggleOffOn()
        trimTrailingWhitespace()
        leadingTabsToSpaces()
        endWithNewline()
@@ -27,9 +27,10 @@ spotless {
    }
 }
 dependencies {
-    api 'org.springframework.boot:spring-boot-starter-web'
-    api 'org.springframework.boot:spring-boot-starter-aop'
-    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20240325.1'
+    api 'com.google.guava:guava:33.4.8-jre'
+    api 'org.springframework.boot:spring-boot-starter-webmvc'
+    api 'org.springframework.boot:spring-boot-starter-aspectj'
+    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20260102.1'
    api 'com.fathzer:javaluator:3.0.6'
    api 'com.posthog.java:posthog:1.2.0'
    api 'org.apache.commons:commons-lang3:3.20.0'
@@ -39,10 +40,10 @@ dependencies {
    api "org.apache.pdfbox:pdfbox-io:$pdfboxVersion"
    api "org.apache.pdfbox:xmpbox:$pdfboxVersion"
    api "org.apache.pdfbox:preflight:$pdfboxVersion"
-    api 'com.github.junrar:junrar:7.5.7' // RAR archive support for CBR files
+    api 'com.github.junrar:junrar:7.5.8' // 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.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.15"
+    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.1"
    // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
    api 'org.simplejavamail:simple-java-mail:8.12.6'
    api 'org.simplejavamail:outlook-module:8.12.6' // MSG file support
@@ -103,8 +103,9 @@ public class EndpointConfiguration {

        // Rule 2: Functional-group override - check if endpoint belongs to any disabled functional
        // group
-        for (String group : endpointGroups.keySet()) {
-            if (disabledGroups.contains(group) && endpointGroups.get(group).contains(endpoint)) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
+            if (disabledGroups.contains(group) && entry.getValue().contains(endpoint)) {
                // Skip tool groups (qpdf, OCRmyPDF, Ghostscript, LibreOffice, etc.)
                if (!isToolGroup(group)) {
                    log.debug(
@@ -131,10 +132,11 @@ public class EndpointConfiguration {

        // Rule 4: Single-dependency check - if no alternatives defined, check if endpoint belongs
        // to any disabled tool groups
-        for (String group : endpointGroups.keySet()) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
            if (isToolGroup(group)
                    && disabledGroups.contains(group)
-                    && endpointGroups.get(group).contains(endpoint)) {
+                    && entry.getValue().contains(endpoint)) {
                log.debug(
                        "isEndpointEnabled('{}') -> false (single tool group '{}' disabled, no alternatives)",
                        original,
@@ -354,6 +356,7 @@ public class EndpointConfiguration {
        addEndpointToGroup("Security", "cert-sign");
        addEndpointToGroup("Security", "remove-cert-sign");
        addEndpointToGroup("Security", "sanitize-pdf");
+        addEndpointToGroup("Security", "timestamp-pdf");
        addEndpointToGroup("Security", "auto-redact");
        addEndpointToGroup("Security", "validate-signature");
        addEndpointToGroup("Security", "add-stamp");
@@ -371,7 +374,6 @@ public class EndpointConfiguration {
        addEndpointToGroup("Other", REMOVE_BLANKS);
        addEndpointToGroup("Other", "remove-annotations");
        addEndpointToGroup("Other", "get-info-on-pdf");
-        addEndpointToGroup("Other", "remove-image-pdf");
        addEndpointToGroup("Other", "add-attachments");
        addEndpointToGroup("Other", "replace-invert-pdf");
        addEndpointToGroup("Other", "edit-table-of-contents");
@@ -391,13 +393,24 @@ public class EndpointConfiguration {
        addEndpointToGroup("Advance", "extract-image-scans");
        addEndpointToGroup("Advance", "repair");
        addEndpointToGroup("Advance", "auto-rename");
-        addEndpointToGroup("Advance", "handleData");
        addEndpointToGroup("Advance", "scanner-effect");
-        addEndpointToGroup("Advance", "show-javascript");
        addEndpointToGroup("Advance", "overlay-pdf");
        // Backend-only endpoints
        addEndpointToGroup("Advance", "adjust-contrast");
-        addEndpointToGroup("Advance", "pipeline");
+
+        // Adding endpoints to "Automation" group
+        addEndpointToGroup("Automation", "handleData");
+        addEndpointToGroup("Automation", "automate"); // Alias for handleData (user-friendly name)
+        addEndpointToGroup("Automation", "pipeline");
+
+        // Adding endpoints to "DeveloperTools" group
+        addEndpointToGroup("DeveloperTools", "show-javascript");
+
+        // Adding endpoints to "DeveloperDocs" group (fake endpoints for link-only tools)
+        addEndpointToGroup("DeveloperDocs", "dev-api-docs");
+        addEndpointToGroup("DeveloperDocs", "dev-folder-scanning-docs");
+        addEndpointToGroup("DeveloperDocs", "dev-sso-guide-docs");
+        addEndpointToGroup("DeveloperDocs", "dev-airgapped-docs");

        // CLI
        addEndpointToGroup("CLI", "compress-pdf");
@@ -460,6 +473,7 @@ public class EndpointConfiguration {
        addEndpointToGroup("Java", "auto-rename");
        addEndpointToGroup("Java", "auto-split-pdf");
        addEndpointToGroup("Java", "sanitize-pdf");
+        addEndpointToGroup("Java", "timestamp-pdf");
        addEndpointToGroup("Java", "crop");
        addEndpointToGroup("Java", "get-info-on-pdf");
        addEndpointToGroup("Java", "pdf-to-single-page");
@@ -475,7 +489,6 @@ public class EndpointConfiguration {
        addEndpointToGroup("Java", REMOVE_BLANKS);
        addEndpointToGroup("Java", "remove-annotations");
        addEndpointToGroup("Java", "pdf-to-text");
-        addEndpointToGroup("Java", "remove-image-pdf");
        addEndpointToGroup("Java", "pdf-to-markdown");
        addEndpointToGroup("Java", "add-attachments");
        addEndpointToGroup("Java", "compress-pdf");
@@ -595,6 +608,12 @@ public class EndpointConfiguration {
        return endpointGroups.getOrDefault(group, new HashSet<>());
    }

+    public Set<String> getAllEndpoints() {
+        return endpointGroups.values().stream()
+                .flatMap(Set::stream)
+                .collect(java.util.stream.Collectors.toSet());
+    }
+
    private boolean isToolGroup(String group) {
        return "qpdf".equals(group)
                || "OCRmyPDF".equals(group)
@@ -628,8 +647,9 @@ public class EndpointConfiguration {
        }

        // Check if endpoint belongs to any disabled functional group
-        for (String group : endpointGroups.keySet()) {
-            if (disabledGroups.contains(group) && endpointGroups.get(group).contains(endpoint)) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
+            if (disabledGroups.contains(group) && entry.getValue().contains(endpoint)) {
                if (!isToolGroup(group)) {
                    return false;
                }
@@ -2,12 +2,14 @@ package stirling.software.common.aop;

 import java.io.IOException;
 import java.time.Duration;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.TimeUnit;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;

 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.*;
+import org.slf4j.MDC;
 import org.springframework.core.annotation.Order;
 import org.springframework.stereotype.Component;
 import org.springframework.web.multipart.MultipartFile;
@@ -26,7 +28,7 @@ import stirling.software.common.service.JobExecutorService;
@Component
@RequiredArgsConstructor
@Slf4j
-@Order(0) // Highest precedence - executes before audit aspects
+@Order(20) // Lower precedence - executes AFTER audit aspects populate MDC
 public class AutoJobAspect {

    private static final Duration RETRY_BASE_DELAY = Duration.ofMillis(100);
@@ -70,26 +72,29 @@ public class AutoJobAspect {
            // No retries needed, simple execution
            return jobExecutorService.runJobGeneric(
                    async,
-                    () -> {
-                        try {
-                            // Note: Progress tracking is handled in TaskManager/JobExecutorService
-                            // The trackProgress flag controls whether detailed progress is stored
-                            // for REST API queries, not WebSocket notifications
-                            return joinPoint.proceed(args);
-                        } catch (Throwable ex) {
-                            log.error(
-                                    "AutoJobAspect caught exception during job execution: {}",
-                                    ex.getMessage(),
-                                    ex);
-                            // Rethrow RuntimeException as-is to preserve exception type
-                            if (ex instanceof RuntimeException) {
-                                throw (RuntimeException) ex;
-                            }
-                            // Wrap checked exceptions - GlobalExceptionHandler will unwrap
-                            // BaseAppException
-                            throw new RuntimeException(ex);
-                        }
-                    },
+                    wrapWithMDC(
+                            () -> {
+                                try {
+                                    // Note: Progress tracking is handled in
+                                    // TaskManager/JobExecutorService
+                                    // The trackProgress flag controls whether detailed progress is
+                                    // stored
+                                    // for REST API queries, not WebSocket notifications
+                                    return joinPoint.proceed(args);
+                                } catch (Throwable ex) {
+                                    log.error(
+                                            "AutoJobAspect caught exception during job execution: {}",
+                                            ex.getMessage(),
+                                            ex);
+                                    // Rethrow RuntimeException as-is to preserve exception type
+                                    if (ex instanceof RuntimeException) {
+                                        throw (RuntimeException) ex;
+                                    }
+                                    // Wrap checked exceptions - GlobalExceptionHandler will unwrap
+                                    // BaseAppException
+                                    throw new RuntimeException(ex);
+                                }
+                            }),
                    timeout,
                    queueable,
                    resourceWeight);
@@ -123,114 +128,108 @@ public class AutoJobAspect {

        return jobExecutorService.runJobGeneric(
                async,
-                () -> {
-                    // Use iterative approach instead of recursion to avoid stack overflow
-                    Throwable lastException = null;
+                wrapWithMDC(
+                        () -> {
+                            // Use iterative approach instead of recursion to avoid stack overflow
+                            Throwable lastException = null;

-                    // Attempt counter starts at 1 for first try
-                    for (int currentAttempt = 1; currentAttempt <= maxRetries; currentAttempt++) {
-                        try {
-                            if (trackProgress && async) {
-                                // Get jobId for progress tracking in TaskManager
-                                // This enables REST API progress queries, not WebSocket
-                                if (jobIdRef.get() == null) {
-                                    jobIdRef.set(getJobIdFromContext());
-                                }
-                                String jobId = jobIdRef.get();
-                                if (jobId != null) {
-                                    log.debug(
-                                            "Tracking progress for job {} (attempt {}/{})",
-                                            jobId,
+                            // Attempt counter starts at 1 for first try
+                            for (int currentAttempt = 1;
+                                    currentAttempt <= maxRetries;
+                                    currentAttempt++) {
+                                try {
+                                    if (trackProgress && async) {
+                                        // Get jobId for progress tracking in TaskManager
+                                        // This enables REST API progress queries, not WebSocket
+                                        if (jobIdRef.get() == null) {
+                                            jobIdRef.set(getJobIdFromContext());
+                                        }
+                                        String jobId = jobIdRef.get();
+                                        if (jobId != null) {
+                                            log.debug(
+                                                    "Tracking progress for job {} (attempt {}/{})",
+                                                    jobId,
+                                                    currentAttempt,
+                                                    maxRetries);
+                                            // Progress is tracked in TaskManager for REST API
+                                            // access
+                                            // No WebSocket notifications sent here
+                                        }
+                                    }
+
+                                    // Attempt to execute the operation
+                                    return joinPoint.proceed(args);
+
+                                } catch (Throwable ex) {
+                                    lastException = ex;
+                                    log.error(
+                                            "AutoJobAspect caught exception during job execution (attempt"
+                                                    + " {}/{}): {}",
                                            currentAttempt,
-                                            maxRetries);
-                                    // Progress is tracked in TaskManager for REST API access
-                                    // No WebSocket notifications sent here
-                                }
-                            }
+                                            maxRetries,
+                                            ex.getMessage(),
+                                            ex);

-                            // Attempt to execute the operation
-                            return joinPoint.proceed(args);
+                                    // Check if we should retry
+                                    if (currentAttempt < maxRetries) {
+                                        log.info(
+                                                "Retrying operation, attempt {}/{}",
+                                                currentAttempt + 1,
+                                                maxRetries);

-                        } catch (Throwable ex) {
-                            lastException = ex;
-                            log.error(
-                                    "AutoJobAspect caught exception during job execution (attempt"
-                                            + " {}/{}): {}",
-                                    currentAttempt,
-                                    maxRetries,
-                                    ex.getMessage(),
-                                    ex);
+                                        if (trackProgress && async) {
+                                            String jobId = jobIdRef.get();
+                                            if (jobId != null) {
+                                                log.debug(
+                                                        "Recording retry attempt for job {} in TaskManager",
+                                                        jobId);
+                                                // Retry info is tracked in TaskManager for REST API
+                                                // access
+                                            }
+                                        }

-                            // Check if we should retry
-                            if (currentAttempt < maxRetries) {
-                                log.info(
-                                        "Retrying operation, attempt {}/{}",
-                                        currentAttempt + 1,
-                                        maxRetries);
+                                        // Use sleep for retry delay
+                                        // For sync jobs, both sleep and async are blocking at this
+                                        // point
+                                        // For async jobs, the delay occurs in the executor thread
+                                        long delayMs = RETRY_BASE_DELAY.toMillis() * currentAttempt;

-                                if (trackProgress && async) {
-                                    String jobId = jobIdRef.get();
-                                    if (jobId != null) {
-                                        log.debug(
-                                                "Recording retry attempt for job {} in TaskManager",
-                                                jobId);
-                                        // Retry info is tracked in TaskManager for REST API access
+                                        try {
+                                            Thread.sleep(delayMs);
+                                        } catch (InterruptedException e) {
+                                            Thread.currentThread().interrupt();
+                                            log.debug(
+                                                    "Retry delay interrupted for attempt {}/{}",
+                                                    currentAttempt,
+                                                    maxRetries);
+                                            break;
+                                        }
+                                    } else {
+                                        // No more retries, we'll throw the exception after the loop
+                                        break;
                                    }
                                }
-
-                                // Use non-blocking delay for all retry attempts to avoid blocking
-                                // threads
-                                // For sync jobs this avoids starving the tomcat thread pool under
-                                // load
-                                long delayMs = RETRY_BASE_DELAY.toMillis() * currentAttempt;
-
-                                // Execute the retry after a delay through the JobExecutorService
-                                // rather than blocking the current thread with sleep
-                                CompletableFuture<Object> delayedRetry = new CompletableFuture<>();
-
-                                // Use a delayed executor for non-blocking delay
-                                CompletableFuture.delayedExecutor(delayMs, TimeUnit.MILLISECONDS)
-                                        .execute(
-                                                () -> {
-                                                    // Continue the retry loop in the next iteration
-                                                    // We can't return from here directly since
-                                                    // we're in a Runnable
-                                                    delayedRetry.complete(null);
-                                                });
-
-                                // Wait for the delay to complete before continuing
-                                try {
-                                    delayedRetry.join();
-                                } catch (Exception e) {
-                                    Thread.currentThread().interrupt();
-                                    break;
-                                }
-                            } else {
-                                // No more retries, we'll throw the exception after the loop
-                                break;
                            }
-                        }
-                    }

-                    // If we get here, all retries failed
-                    if (lastException != null) {
-                        // Rethrow RuntimeException as-is to preserve exception type
-                        if (lastException instanceof RuntimeException) {
-                            throw (RuntimeException) lastException;
-                        }
-                        // Wrap checked exceptions - GlobalExceptionHandler will unwrap
-                        // BaseAppException
-                        throw new RuntimeException(
-                                "Job failed after "
-                                        + maxRetries
-                                        + " attempts: "
-                                        + lastException.getMessage(),
-                                lastException);
-                    }
+                            // If we get here, all retries failed
+                            if (lastException != null) {
+                                // Rethrow RuntimeException as-is to preserve exception type
+                                if (lastException instanceof RuntimeException) {
+                                    throw (RuntimeException) lastException;
+                                }
+                                // Wrap checked exceptions - GlobalExceptionHandler will unwrap
+                                // BaseAppException
+                                throw new RuntimeException(
+                                        "Job failed after "
+                                                + maxRetries
+                                                + " attempts: "
+                                                + lastException.getMessage(),
+                                        lastException);
+                            }

-                    // This should never happen if lastException is properly tracked
-                    throw new RuntimeException("Job failed but no exception was recorded");
-                },
+                            // This should never happen if lastException is properly tracked
+                            throw new RuntimeException("Job failed but no exception was recorded");
+                        }),
                timeout,
                queueable,
                resourceWeight);
@@ -299,4 +298,32 @@ public class AutoJobAspect {
            return null;
        }
    }
+
+    /**
+     * Wraps a supplier to propagate MDC context to background threads. Captures MDC on request
+     * thread and restores it in the background thread. Ensures proper cleanup to prevent context
+     * leakage across jobs in thread pools.
+     */
+    private <T> Supplier<T> wrapWithMDC(Supplier<T> supplier) {
+        final Map<String, String> captured = MDC.getCopyOfContextMap();
+        return () -> {
+            final Map<String, String> previous = MDC.getCopyOfContextMap();
+            try {
+                // Set the captured context (or clear if none was captured)
+                if (captured != null) {
+                    MDC.setContextMap(new HashMap<>(captured));
+                } else {
+                    MDC.clear();
+                }
+                return supplier.get();
+            } finally {
+                // Restore previous state (or clear if there was none)
+                if (previous != null) {
+                    MDC.setContextMap(previous);
+                } else {
+                    MDC.clear();
+                }
+            }
+        };
+    }
 }
@@ -91,9 +91,9 @@ public class RuntimePathConfig {

        // Initialize Operation paths
        String defaultWeasyPrintPath = isDocker ? "/opt/venv/bin/weasyprint" : "weasyprint";
-        String defaultUnoConvertPath = isDocker ? "/opt/venv/bin/unoconvert" : "unoconvert";
+        String defaultUnoConvertPath = isDocker ? "/usr/local/bin/unoconvert" : "unoconvert";
        String defaultCalibrePath = isDocker ? "/opt/calibre/ebook-convert" : "ebook-convert";
-        String defaultOcrMyPdfPath = isDocker ? "/usr/bin/ocrmypdf" : "ocrmypdf";
+        String defaultOcrMyPdfPath = isDocker ? "/opt/venv/bin/ocrmypdf" : "ocrmypdf";
        String defaultSOfficePath = isDocker ? "/usr/bin/soffice" : "soffice";

        Operations operations = customPaths.getOperations();
@@ -0,0 +1,23 @@
+package stirling.software.common.configuration;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.TaskScheduler;
+import org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler;
+
+/**
+ * Configures the scheduler used by all {@code @Scheduled} methods. Uses virtual threads so that
+ * long-running scheduled tasks (e.g. cleanup, license checks, file monitoring) never block each
+ * other — each runs on its own lightweight virtual thread.
+ */
+@Configuration
+public class SchedulingConfig {
+
+    @Bean
+    public TaskScheduler taskScheduler() {
+        SimpleAsyncTaskScheduler scheduler = new SimpleAsyncTaskScheduler();
+        scheduler.setVirtualThreads(true);
+        scheduler.setThreadNamePrefix("scheduled-vt-");
+        return scheduler;
+    }
+}
@@ -0,0 +1,49 @@
+package stirling.software.common.constants;
+
+/**
+ * Centralized constants for JWT token management.
+ *
+ * <p>These defaults are used when configuration values are not explicitly set.
+ */
+public final class JwtConstants {
+
+    private JwtConstants() {
+        throw new UnsupportedOperationException("Utility class");
+    }
+
+    /** Default JWT access token lifetime in minutes (24 hours). */
+    public static final int DEFAULT_TOKEN_EXPIRY_MINUTES = 1440;
+
+    /** Default desktop client token lifetime in minutes (30 days). */
+    public static final int DEFAULT_DESKTOP_TOKEN_EXPIRY_MINUTES = 43200;
+
+    /**
+     * Default refresh grace period in minutes.
+     *
+     * <p>Allows refresh of expired tokens within this window after expiration.
+     */
+    public static final int DEFAULT_REFRESH_GRACE_MINUTES = 15;
+
+    /**
+     * Default allowed clock skew in seconds.
+     *
+     * <p>Tolerates small time drift between client and server clocks during validation.
+     */
+    public static final int DEFAULT_CLOCK_SKEW_SECONDS = 60;
+
+    /** Milliseconds per minute. */
+    public static final long MILLIS_PER_MINUTE = 60_000L;
+
+    /** Seconds per minute. */
+    public static final long SECONDS_PER_MINUTE = 60L;
+
+    /** JWT issuer identifier. */
+    public static final String ISSUER = "https://stirling.com";
+
+    /**
+     * Maximum refresh attempts allowed within the grace period window.
+     *
+     * <p>Prevents abuse of expired tokens by limiting refresh attempts.
+     */
+    public static final int MAX_REFRESH_ATTEMPTS_IN_GRACE = 3;
+}
@@ -29,16 +29,17 @@ import org.springframework.stereotype.Component;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;

+import jakarta.annotation.PostConstruct;
+
 import lombok.Data;
 import lombok.Getter;
 import lombok.Setter;
 import lombok.ToString;
 import lombok.extern.slf4j.Slf4j;

-import jakarta.annotation.PostConstruct;
-
 import stirling.software.common.configuration.InstallationPathConfig;
 import stirling.software.common.configuration.YamlPropertySourceFactory;
+import stirling.software.common.constants.JwtConstants;
 import stirling.software.common.model.exception.UnsupportedProviderException;
 import stirling.software.common.model.oauth2.GitHubProvider;
 import stirling.software.common.model.oauth2.GoogleProvider;
@@ -57,6 +58,7 @@ public class ApplicationProperties {
    private Legal legal = new Legal();
    private Security security = new Security();
    private System system = new System();
+    private Storage storage = new Storage();
    private Ui ui = new Ui();
    private Endpoints endpoints = new Endpoints();
    private Metrics metrics = new Metrics();
@@ -101,8 +103,8 @@ public class ApplicationProperties {
    }

    /**
-     * Initialize fileUploadLimit from environment variables if not set in settings.yml.
-     * Supports SYSTEMFILEUPLOADLIMIT (format: "100MB") and SYSTEM_MAXFILESIZE (format: "100" in MB).
+     * Initialize fileUploadLimit from environment variables if not set in settings.yml. Supports
+     * SYSTEMFILEUPLOADLIMIT (format: "100MB") and SYSTEM_MAXFILESIZE (format: "100" in MB).
     */
    @PostConstruct
    public void initializeFileUploadLimitFromEnv() {
@@ -124,12 +126,18 @@ public class ApplicationProperties {
                        long sizeInMB = Long.parseLong(systemMaxFileSize.trim());
                        if (sizeInMB > 0 && sizeInMB <= 999) {
                            fileUploadLimit = sizeInMB + "MB";
-                            log.info("Setting fileUploadLimit from SYSTEM_MAXFILESIZE: {}MB", sizeInMB);
+                            log.info(
+                                    "Setting fileUploadLimit from SYSTEM_MAXFILESIZE: {}MB",
+                                    sizeInMB);
                        } else {
-                            log.warn("SYSTEM_MAXFILESIZE value {} is out of valid range (1-999), ignoring", sizeInMB);
+                            log.warn(
+                                    "SYSTEM_MAXFILESIZE value {} is out of valid range (1-999), ignoring",
+                                    sizeInMB);
                        }
                    } catch (NumberFormatException e) {
-                        log.warn("SYSTEM_MAXFILESIZE value '{}' is not a valid number, ignoring", systemMaxFileSize);
+                        log.warn(
+                                "SYSTEM_MAXFILESIZE value '{}' is not a valid number, ignoring",
+                                systemMaxFileSize);
                    }
                }
            }
@@ -143,6 +151,44 @@ public class ApplicationProperties {
    @Data
    public static class AutoPipeline {
        private String outputFolder;
+        private FileReadiness fileReadiness = new FileReadiness();
+
+        /**
+         * Configuration for the {@link stirling.software.common.util.FileReadinessChecker}.
+         * Controls how the pipeline determines whether a file is fully written and stable before
+         * processing begins.
+         */
+        @Data
+        public static class FileReadiness {
+            /**
+             * Master toggle. When {@code false} every readiness check is skipped and all files are
+             * considered immediately ready (preserves legacy behaviour).
+             */
+            private boolean enabled = true;
+
+            /**
+             * How long (in milliseconds) a file must remain unmodified before it is considered
+             * stable. Files modified more recently than this threshold are skipped and retried on
+             * the next scan cycle. Default: 5 000 ms (5 seconds).
+             */
+            private long settleTimeMillis = 5000;
+
+            /**
+             * How long (in milliseconds) to pause between two consecutive file-size reads when
+             * checking whether a file is still being written. If the size differs between the two
+             * reads the file is considered unstable. This catches active copies on Linux/macOS
+             * where advisory locking alone cannot detect a mid-copy file. Default: 500 ms.
+             */
+            private long sizeCheckDelayMillis = 500;
+
+            /**
+             * Optional list of file extensions (without the leading dot, case-insensitive) that are
+             * allowed through the readiness check. An empty list means all extensions are accepted.
+             * Example: {@code ["pdf", "tiff"]} will skip any file whose extension is not {@code
+             * pdf} or {@code tiff}.
+             */
+            private List<String> allowedExtensions = new java.util.ArrayList<>();
+        }
    }

    @Data
@@ -206,6 +252,7 @@ public class ApplicationProperties {
        private String customGlobalAPIKey;
        private Jwt jwt = new Jwt();
        private Validation validation = new Validation();
+        private Timestamp timestamp = new Timestamp();
        private String xFrameOptions = "DENY";

        public Boolean isAltLogin() {
@@ -358,11 +405,11 @@ public class ApplicationProperties {
            }

            public boolean isSettingsValid() {
-                return !ValidationUtils.isStringEmpty(this.getIssuer())
-                        && !ValidationUtils.isStringEmpty(this.getClientId())
-                        && !ValidationUtils.isStringEmpty(this.getClientSecret())
-                        && !ValidationUtils.isCollectionEmpty(this.getScopes())
-                        && !ValidationUtils.isStringEmpty(this.getUseAsUsername());
+                return !ValidationUtils.isStringEmpty(this.issuer)
+                        && !ValidationUtils.isStringEmpty(this.clientId)
+                        && !ValidationUtils.isStringEmpty(this.clientSecret)
+                        && !ValidationUtils.isCollectionEmpty(this.scopes)
+                        && !ValidationUtils.isStringEmpty(this.useAsUsername);
            }

            @Data
@@ -387,12 +434,107 @@ public class ApplicationProperties {
            }
        }

+        /**
+         * JWT token configuration.
+         *
+         * <p><b>BREAKING CHANGE (v2.0):</b> Default token expiry increased from 12 hours (720
+         * minutes) to 24 hours (1440 minutes). If you require the previous behavior, explicitly set
+         * {@code tokenExpiryMinutes: 720} in your configuration.
+         */
        @Data
        public static class Jwt {
            private boolean enableKeystore = true;
            private boolean enableKeyRotation = false;
            private boolean enableKeyCleanup = true;
-            private int keyRetentionDays = 7;
+
+            /**
+             * JWT access token lifetime in minutes for web clients.
+             *
+             * <p>Default: {@value JwtConstants#DEFAULT_TOKEN_EXPIRY_MINUTES} minutes (24 hours).
+             *
+             * <p><b>BREAKING CHANGE:</b> Previously hardcoded to 720 minutes (12 hours). Now
+             * defaults to 1440 minutes (24 hours).
+             */
+            private int tokenExpiryMinutes = JwtConstants.DEFAULT_TOKEN_EXPIRY_MINUTES;
+
+            /**
+             * JWT access token lifetime in minutes for desktop clients (Tauri app).
+             *
+             * <p>Desktop clients are automatically detected via User-Agent header and receive
+             * longer-lived tokens because they run on personal devices with OS-level encrypted
+             * storage (macOS Keychain, Windows Credential Manager, Linux Secret Service).
+             *
+             * <p>This provides better UX (login once per month) while maintaining security through
+             * device encryption and secure storage, matching the behavior of popular desktop apps
+             * like Slack, Discord, VS Code, etc.
+             *
+             * <p>Default: 43200 minutes (30 days).
+             */
+            private int desktopTokenExpiryMinutes = 43200;
+
+            /**
+             * Allowed clock skew in seconds for JWT validation.
+             *
+             * <p>Tolerates small time drift between client and server clocks. Tokens that are
+             * slightly expired or slightly in the future (within this window) will still be
+             * accepted.
+             *
+             * <p>Default: {@value JwtConstants#DEFAULT_CLOCK_SKEW_SECONDS} seconds.
+             */
+            private int allowedClockSkewSeconds = JwtConstants.DEFAULT_CLOCK_SKEW_SECONDS;
+
+            /**
+             * Grace period in minutes for refreshing expired tokens.
+             *
+             * <p>Allows token refresh using an expired access token if the token expired within
+             * this many minutes. This provides better UX by allowing users to refresh slightly
+             * expired tokens without re-authentication.
+             *
+             * <p>Rate limiting is applied to prevent abuse of expired tokens within the grace
+             * window (max {@value JwtConstants#MAX_REFRESH_ATTEMPTS_IN_GRACE} attempts).
+             *
+             * <p>Default: {@value JwtConstants#DEFAULT_REFRESH_GRACE_MINUTES} minutes.
+             */
+            private int refreshGraceMinutes = JwtConstants.DEFAULT_REFRESH_GRACE_MINUTES;
+
+            /**
+             * Calculate number of days to retain old JWT signing keys.
+             *
+             * <p>Automatically calculated based on the longest token lifetime plus a proportional
+             * safety buffer. Keys must be retained for at least as long as the tokens they signed
+             * remain valid, otherwise token verification will fail.
+             *
+             * <p>Formula: ceil((maxTokenExpiry + 10% buffer + refreshGrace + clockSkew) / 1440)
+             *
+             * <p>The buffer includes:
+             *
+             * <ul>
+             *   <li>10% of token lifetime (scales with token duration)
+             *   <li>Token refresh grace period ({@link #refreshGraceMinutes})
+             *   <li>Clock skew tolerance ({@link #allowedClockSkewSeconds} converted to minutes)
+             * </ul>
+             *
+             * @return calculated key retention period in days
+             */
+            public int getKeyRetentionDays() {
+                final int MINUTES_PER_DAY = 1440;
+                final double BUFFER_PERCENTAGE = 0.10; // 10% buffer
+
+                int maxTokenExpiryMinutes = Math.max(tokenExpiryMinutes, desktopTokenExpiryMinutes);
+
+                // Add 10% buffer (scales with token lifetime)
+                int bufferMinutes = (int) Math.ceil(maxTokenExpiryMinutes * BUFFER_PERCENTAGE);
+
+                // Add refresh grace period
+                bufferMinutes += refreshGraceMinutes;
+
+                // Add clock skew (convert seconds to minutes, round up)
+                bufferMinutes += (int) Math.ceil(allowedClockSkewSeconds / 60.0);
+
+                // Total retention in minutes, convert to days (round up)
+                int totalMinutes = maxTokenExpiryMinutes + bufferMinutes;
+                return (int) Math.ceil(totalMinutes / (double) MINUTES_PER_DAY);
+            }
        }

        @Data
@@ -429,6 +571,12 @@ public class ApplicationProperties {
                private boolean hardFail = false;
            }
        }
+
+        @Data
+        public static class Timestamp {
+            private String defaultTsaUrl = "http://timestamp.digicert.com";
+            private List<String> customTsaUrls = new ArrayList<>();
+        }
    }

    @Data
@@ -473,19 +621,52 @@ public class ApplicationProperties {
        }

        public boolean isAnalyticsEnabled() {
-            return this.getEnableAnalytics() != null && this.getEnableAnalytics();
+            return this.enableAnalytics != null && this.enableAnalytics;
        }

        public boolean isPosthogEnabled() {
            // Treat null as enabled when analytics is enabled
-            return this.isAnalyticsEnabled()
-                    && (this.getEnablePosthog() == null || this.getEnablePosthog());
+            return this.isAnalyticsEnabled() && (this.enablePosthog == null || this.enablePosthog);
        }

        public boolean isScarfEnabled() {
            // Treat null as enabled when analytics is enabled
-            return this.isAnalyticsEnabled()
-                    && (this.getEnableScarf() == null || this.getEnableScarf());
+            return this.isAnalyticsEnabled() && (this.enableScarf == null || this.enableScarf);
+        }
+    }
+
+    @Data
+    public static class Storage {
+        private boolean enabled = false;
+        private String provider = "local";
+        private Local local = new Local();
+        private Quotas quotas = new Quotas();
+        private Sharing sharing = new Sharing();
+        private Signing signing = new Signing();
+
+        @Data
+        public static class Local {
+            private String basePath = InstallationPathConfig.getPath() + "storage";
+        }
+
+        @Data
+        public static class Sharing {
+            private boolean enabled = false;
+            private boolean linkEnabled = false;
+            private boolean emailEnabled = false;
+            private int linkExpirationDays = 3;
+        }
+
+        @Data
+        public static class Quotas {
+            private long maxStorageMbPerUser = -1;
+            private long maxStorageMbTotal = -1;
+            private long maxFileMb = -1;
+        }
+
+        @Data
+        public static class Signing {
+            private boolean enabled = false;
        }
    }

@@ -610,6 +791,9 @@ public class ApplicationProperties {
        private String appNameNavbar;
        private List<String> languages;
        private String logoStyle = "classic"; // Options: "classic" (default) or "modern"
+        private boolean defaultHideUnavailableTools = false;
+        private boolean defaultHideUnavailableConversions = false;
+        private HideDisabledTools hideDisabledTools = new HideDisabledTools();

        public String getAppNameNavbar() {
            return appNameNavbar != null && !appNameNavbar.trim().isEmpty() ? appNameNavbar : null;
@@ -622,6 +806,12 @@ public class ApplicationProperties {
            }
            return "classic"; // default
        }
+
+        @Data
+        public static class HideDisabledTools {
+            private boolean googleDrive = false;
+            private boolean mobileQRScanner = false;
+        }
    }

    @Data
@@ -809,6 +999,15 @@ public class ApplicationProperties {
            private boolean ssoAutoLogin;
            private boolean database;
            private CustomMetadata customMetadata = new CustomMetadata();
+            private GoogleDrive googleDrive = new GoogleDrive();
+
+            @Data
+            public static class GoogleDrive {
+                private boolean enabled = false;
+                private String clientId = "";
+                private String apiKey = "";
+                private String appId = "";
+            }

            @Data
            public static class CustomMetadata {
@@ -858,6 +1057,12 @@ public class ApplicationProperties {
                private boolean enabled = true;
                private int level = 2; // 0=OFF, 1=BASIC, 2=STANDARD, 3=VERBOSE
                private int retentionDays = 90;
+                private boolean captureFileHash =
+                        false; // Capture SHA-256 hash of files (increases processing time)
+                private boolean capturePdfAuthor =
+                        false; // Capture PDF author metadata (increases processing time)
+                private boolean captureOperationResults =
+                        false; // Capture operation return values (not recommended, high volume)
            }

            @Data
@@ -0,0 +1,98 @@
+package stirling.software.common.model;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/** Form field information with coordinates for interactive form viewer. */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@Schema(description = "Form field with coordinates and metadata")
+public class FormFieldWithCoordinates {
+
+    @Schema(description = "Fully qualified field name", example = "form1.firstName")
+    private String name;
+
+    @Schema(description = "Display label for the field", example = "First Name")
+    private String label;
+
+    @Schema(description = "Field type: text, checkbox, radio, combobox, listbox, button, signature")
+    private String type;
+
+    @Schema(description = "Current field value")
+    private String value;
+
+    @Schema(
+            description =
+                    "Available options (export values) for choice fields"
+                            + " (dropdown, radio, listbox)")
+    private List<String> options;
+
+    @Schema(
+            description =
+                    "Human-readable display labels for choice field options,"
+                            + " parallel to the 'options' list. Null when identical to options.")
+    private List<String> displayOptions;
+
+    @Schema(description = "Whether the field is required")
+    private boolean required;
+
+    @Schema(description = "Whether the field is read-only")
+    private boolean readOnly;
+
+    @Schema(description = "Whether this is a multi-select list box")
+    private boolean multiSelect;
+
+    @Schema(description = "Whether this is a multi-line text field")
+    private boolean multiline;
+
+    @Schema(description = "Tooltip/alternate name for the field")
+    private String tooltip;
+
+    @Schema(description = "Widget coordinates on each page (fields can have multiple widgets)")
+    private List<WidgetCoordinates> widgets;
+
+    /**
+     * Coordinates for a single widget annotation (visual representation of the field). A field can
+     * have multiple widgets if it appears on multiple pages.
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    @Schema(description = "Widget coordinates in PDF space")
+    public static class WidgetCoordinates {
+
+        @Schema(description = "Page index (0-based)", example = "0")
+        private int pageIndex;
+
+        @Schema(description = "X coordinate in PDF points (lower-left origin)")
+        private float x;
+
+        @Schema(description = "Y coordinate in PDF points (lower-left origin)")
+        private float y;
+
+        @Schema(description = "Width in PDF points")
+        private float width;
+
+        @Schema(description = "Height in PDF points")
+        private float height;
+
+        @Schema(description = "Export value for this widget (radio/checkbox buttons only)")
+        private String exportValue;
+
+        @Schema(description = "Font size in PDF points")
+        private Float fontSize;
+    }
+}
@@ -0,0 +1,16 @@
+package stirling.software.common.model.api.security;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class UserSummaryDTO {
+    private Long userId;
+    private String username;
+    private String displayName;
+    private String teamName;
+    private boolean enabled;
+}
@@ -42,7 +42,7 @@ public enum Role {
        // Using the fromString method to get the Role enum based on the roleId
        Role role = fromString(roleId);
        // Return the roleName of the found Role enum
-        return role.getRoleName();
+        return role.roleName;
    }

    // Method to retrieve all role IDs and role names
@@ -50,14 +50,14 @@ public enum Role {
        // Using LinkedHashMap to preserve order
        Map<String, String> roleDetails = new LinkedHashMap<>();
        for (Role role : Role.values()) {
-            roleDetails.put(role.getRoleId(), role.getRoleName());
+            roleDetails.put(role.roleId, role.roleName);
        }
        return roleDetails;
    }

    public static Role fromString(String roleId) {
        for (Role role : Role.values()) {
-            if (role.getRoleId().equalsIgnoreCase(roleId)) {
+            if (role.roleId.equalsIgnoreCase(roleId)) {
                return role;
            }
        }
@@ -117,13 +117,13 @@ public class Provider {
                + ", clientName="
                + getClientName()
                + ", clientId="
-                + getClientId()
+                + clientId
                + ", clientSecret="
-                + (getClientSecret() != null && !getClientSecret().isEmpty() ? "*****" : "NULL")
+                + (clientSecret != null && !clientSecret.isEmpty() ? "*****" : "NULL")
                + ", scopes="
                + getScopes()
                + ", useAsUsername="
-                + getUseAsUsername()
+                + useAsUsername
                + "]";
    }
 }
@@ -1,6 +1,8 @@
 package stirling.software.common.service;

+import java.io.BufferedInputStream;
 import java.io.IOException;
+import java.io.InputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.UUID;
@@ -21,6 +23,9 @@ import lombok.extern.slf4j.Slf4j;
@Slf4j
 public class FileStorage {

+    /** Holds the result of a stream-to-disk store operation: the file ID and the bytes written. */
+    public record StoredFile(String fileId, long size) {}
+
    @Value("${stirling.tempDir:/tmp/stirling-files}")
    private String tempDirPath;

@@ -104,6 +109,40 @@ public class FileStorage {
        return Files.readAllBytes(filePath);
    }

+    /**
+     * Retrieve a file by its ID as a streaming InputStream. The caller is responsible for closing
+     * the returned stream.
+     *
+     * @param fileId The ID of the file to retrieve
+     * @return A buffered InputStream for the file
+     * @throws IOException If the file doesn't exist or can't be read
+     */
+    public InputStream retrieveInputStream(String fileId) throws IOException {
+        Path filePath = getFilePath(fileId);
+        // Let Files.newInputStream throw NoSuchFileException naturally — avoids TOCTOU race
+        // between exists-check and open when another thread may delete concurrently.
+        return new BufferedInputStream(Files.newInputStream(filePath));
+    }
+
+    /**
+     * Store data from an InputStream as a file and return its unique ID and byte count. Streams
+     * directly to disk without buffering the entire content in heap.
+     *
+     * @param inputStream The input stream to read from
+     * @param originalName The original name of the file (unused, kept for API symmetry)
+     * @return A {@link StoredFile} containing the file ID and the number of bytes written
+     * @throws IOException If there is an error storing the file
+     */
+    public StoredFile storeInputStream(InputStream inputStream, String originalName)
+            throws IOException {
+        String fileId = generateFileId();
+        Path filePath = getFilePath(fileId);
+        Files.createDirectories(filePath.getParent());
+        long size = Files.copy(inputStream, filePath);
+        log.debug("Stored input stream with ID: {}", fileId);
+        return new StoredFile(fileId, size);
+    }
+
    /**
     * Delete a file by its ID
     *
@@ -35,7 +35,7 @@ public class JobExecutorService {
    private final HttpServletRequest request;
    private final ResourceMonitor resourceMonitor;
    private final JobQueue jobQueue;
-    private final ExecutorService executor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
    private final long effectiveTimeoutMs;

    @Autowired(required = false)
@@ -254,10 +254,13 @@ public class JobExecutorService {
                return ResponseEntity.internalServerError()
                        .body(Map.of("error", "Job timed out after " + timeoutToUse + " ms"));
            } catch (RuntimeException e) {
-                // Check if this is a wrapped typed exception that should be handled by
-                // GlobalExceptionHandler
+                // Check if this is a typed exception that should be handled by
+                // GlobalExceptionHandler (either directly or wrapped)
                Throwable cause = e.getCause();
-                if (cause instanceof stirling.software.common.util.ExceptionUtils.BaseAppException
+                if (e instanceof IllegalArgumentException
+                        || cause
+                                instanceof
+                                stirling.software.common.util.ExceptionUtils.BaseAppException
                        || cause
                                instanceof
                                stirling.software.common.util.ExceptionUtils
@@ -313,7 +316,7 @@ public class JobExecutorService {
                            filename =
                                    disposition.substring(
                                            disposition.indexOf("filename=") + 9,
-                                            disposition.lastIndexOf("\""));
+                                            disposition.lastIndexOf('"'));
                        }
                    }

@@ -44,8 +44,10 @@ public class JobQueue implements SmartLifecycle {

    private volatile BlockingQueue<QueuedJob> jobQueue;
    private final Map<String, QueuedJob> jobMap = new ConcurrentHashMap<>();
-    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
-    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ScheduledExecutorService scheduler =
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("job-queue-scheduler-", 0).factory());
+    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualThreadExecutor();
    private final Object queueLock = new Object(); // Lock for synchronizing queue operations

    private boolean shuttingDown = false;
@@ -0,0 +1,29 @@
+package stirling.software.common.service;
+
+/**
+ * Interface for checking license status dynamically. Implementation provided by proprietary module
+ * when available.
+ */
+public interface LicenseServiceInterface {
+
+    /**
+     * Get the license type as a string.
+     *
+     * @return "NORMAL", "SERVER", or "ENTERPRISE"
+     */
+    String getLicenseTypeName();
+
+    /**
+     * Check if running Pro or higher (SERVER or ENTERPRISE license).
+     *
+     * @return true if SERVER or ENTERPRISE license is active
+     */
+    boolean isRunningProOrHigher();
+
+    /**
+     * Check if running Enterprise edition.
+     *
+     * @return true if ENTERPRISE license is active
+     */
+    boolean isRunningEE();
+}
@@ -9,6 +9,7 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.regex.Pattern;

 import org.springframework.scheduling.annotation.Scheduled;
 import org.springframework.stereotype.Service;
@@ -25,6 +26,9 @@ import lombok.extern.slf4j.Slf4j;
 public class MobileScannerService {

    private static final long SESSION_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+    private static final Pattern FILENAME_SANITIZE_PATTERN = Pattern.compile("[^a-zA-Z0-9._-]");
+    private static final Pattern SESSION_ID_VALIDATION_PATTERN = Pattern.compile("[a-zA-Z0-9-]+");
+    private static final Pattern FILE_EXTENSION_PATTERN = Pattern.compile("[.][^.]+$");
    private final Map<String, SessionData> activeSessions = new ConcurrentHashMap<>();
    private final Path tempDirectory;

@@ -121,10 +125,11 @@ public class MobileScannerService {
            // Handle duplicate filenames
            int counter = 1;
            while (Files.exists(filePath)) {
-                String nameWithoutExt = safeFilename.replaceFirst("[.][^.]+$", "");
+                String nameWithoutExt =
+                        FILE_EXTENSION_PATTERN.matcher(safeFilename).replaceFirst("");
                String ext =
                        safeFilename.contains(".")
-                                ? safeFilename.substring(safeFilename.lastIndexOf("."))
+                                ? safeFilename.substring(safeFilename.lastIndexOf('.'))
                                : "";
                safeFilename = nameWithoutExt + "-" + counter + ext;
                filePath = sessionDir.resolve(safeFilename).normalize().toAbsolutePath();
@@ -271,14 +276,14 @@ public class MobileScannerService {
            throw new IllegalArgumentException("Session ID cannot be empty");
        }
        // Basic validation: alphanumeric and hyphens only
-        if (!sessionId.matches("[a-zA-Z0-9-]+")) {
+        if (!SESSION_ID_VALIDATION_PATTERN.matcher(sessionId).matches()) {
            throw new IllegalArgumentException("Invalid session ID format");
        }
    }

    private String sanitizeFilename(String filename) {
        // Remove path traversal attempts and dangerous characters
-        String sanitized = filename.replaceAll("[^a-zA-Z0-9._-]", "_");
+        String sanitized = FILENAME_SANITIZE_PATTERN.matcher(filename).replaceAll("_");
        // Ensure we have a non-empty, safe filename
        if (sanitized.isBlank()) {
            sanitized = "upload-" + System.currentTimeMillis();
@@ -169,7 +169,10 @@ public class PdfMetadataService {
                            .getAuthor();

            if (userService != null) {
-                author = author.replace("username", userService.getCurrentUsername());
+                String username = userService.getCurrentUsername();
+                if (username != null) {
+                    author = author.replace("username", username);
+                }
            }
        }
        pdf.getDocumentInformation().setAuthor(author);
@@ -0,0 +1,37 @@
+package stirling.software.common.service;
+
+import java.security.KeyStore;
+
+/**
+ * Abstraction for PDF digital signature operations. Defined in common so that proprietary services
+ * can use it without creating a circular dependency on core.
+ */
+public interface PdfSigningService {
+
+    /**
+     * Signs a PDF document using the provided KeyStore.
+     *
+     * @param pdfBytes raw PDF bytes to sign
+     * @param keystore the KeyStore containing the signing key and certificate chain
+     * @param password keystore password
+     * @param showSignature whether to render a visible signature block
+     * @param pageNumber 0-indexed page on which to render the visible signature (may be null)
+     * @param name signer name embedded in the signature
+     * @param location location string embedded in the signature
+     * @param reason reason string embedded in the signature
+     * @param showLogo whether to include the Stirling-PDF logo in the visible signature
+     * @return signed PDF bytes
+     * @throws Exception on any signing failure
+     */
+    byte[] signWithKeystore(
+            byte[] pdfBytes,
+            KeyStore keystore,
+            char[] password,
+            boolean showSignature,
+            Integer pageNumber,
+            String name,
+            String location,
+            String reason,
+            boolean showLogo)
+            throws Exception;
+}
@@ -43,7 +43,9 @@ public class ResourceMonitor {
    @Value("${stirling.resource.monitor.interval-ms:60000}")
    private long monitorIntervalMs = 60000; // 60 seconds

-    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
+    private final ScheduledExecutorService scheduler =
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("resource-monitor-", 0).factory());
    private final MemoryMXBean memoryMXBean = ManagementFactory.getMemoryMXBean();
    private final OperatingSystemMXBean osMXBean = ManagementFactory.getOperatingSystemMXBean();

@@ -226,10 +226,11 @@ public class SsrfProtectionService {
    }

    private boolean isPrivateIPv4Range(String ip) {
-        // Includes RFC1918, loopback, link-local, and unspecified addresses
+        // Includes RFC1918, RFC6598, loopback, link-local, and unspecified addresses
        return ip.startsWith("10.")
                || ip.startsWith("192.168.")
                || (ip.startsWith("172.") && isInRange172(ip))
+                || (ip.startsWith("100.") && isInRange100(ip))
                || ip.startsWith("169.254.")
                || ip.startsWith("127.")
                || "0.0.0.0".equals(ip);
@@ -247,6 +248,18 @@ public class SsrfProtectionService {
        return false;
    }

+    private boolean isInRange100(String ip) {
+        String[] parts = ip.split("\\.");
+        if (parts.length >= 2) {
+            try {
+                int secondOctet = Integer.parseInt(parts[1]);
+                return secondOctet >= 64 && secondOctet <= 127;
+            } catch (NumberFormatException e) {
+            }
+        }
+        return false;
+    }
+
    private boolean isCloudMetadataAddress(String ip) {
        String normalizedIp = normalizeIpv4MappedAddress(ip);
        // Cloud metadata endpoints for AWS, GCP, Azure, Oracle Cloud, and IBM Cloud
@@ -1,8 +1,8 @@
 package stirling.software.common.service;

-import java.io.ByteArrayInputStream;
-import java.io.ByteArrayOutputStream;
+import java.io.BufferedInputStream;
 import java.io.IOException;
+import java.io.InputStream;
 import java.time.LocalDateTime;
 import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
@@ -19,7 +19,6 @@ import java.util.zip.ZipInputStream;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.MediaType;
 import org.springframework.stereotype.Service;
-import org.springframework.web.multipart.MultipartFile;

 import io.github.pixee.security.ZipSecurity;

@@ -42,7 +41,8 @@ public class TaskManager {

    private final FileStorage fileStorage;
    private final ScheduledExecutorService cleanupExecutor =
-            Executors.newSingleThreadScheduledExecutor();
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("task-cleanup-", 0).factory());

    /** Initialize the task manager and start the cleanup scheduler */
    public TaskManager(FileStorage fileStorage) {
@@ -362,39 +362,29 @@ public class TaskManager {
            String zipFileId, String originalZipFileName) throws IOException {
        List<ResultFile> extractedFiles = new ArrayList<>();

-        MultipartFile zipFile = fileStorage.retrieveFile(zipFileId);
-
-        try (ZipInputStream zipIn =
-                ZipSecurity.createHardenedInputStream(
-                        new ByteArrayInputStream(zipFile.getBytes()))) {
+        try (InputStream fileStream = fileStorage.retrieveInputStream(zipFileId);
+                ZipInputStream zipIn =
+                        ZipSecurity.createHardenedInputStream(
+                                new BufferedInputStream(fileStream))) {
            ZipEntry entry;
            while ((entry = zipIn.getNextEntry()) != null) {
                if (!entry.isDirectory()) {
-                    // Use buffered reading for memory safety
-                    ByteArrayOutputStream out = new ByteArrayOutputStream();
-                    byte[] buffer = new byte[4096];
-                    int bytesRead;
-                    while ((bytesRead = zipIn.read(buffer)) != -1) {
-                        out.write(buffer, 0, bytesRead);
-                    }
-                    byte[] fileContent = out.toByteArray();
-
                    String contentType = determineContentType(entry.getName());
-                    String individualFileId = fileStorage.storeBytes(fileContent, entry.getName());
+                    // storeInputStream returns the fileId and byte count — no extra stat needed
+                    FileStorage.StoredFile stored =
+                            fileStorage.storeInputStream(zipIn, entry.getName());

                    ResultFile resultFile =
                            ResultFile.builder()
-                                    .fileId(individualFileId)
+                                    .fileId(stored.fileId())
                                    .fileName(entry.getName())
                                    .contentType(contentType)
-                                    .fileSize(fileContent.length)
+                                    .fileSize(stored.size())
                                    .build();

                    extractedFiles.add(resultFile);
                    log.debug(
-                            "Extracted file: {} (size: {} bytes)",
-                            entry.getName(),
-                            fileContent.length);
+                            "Extracted file: {} (size: {} bytes)", entry.getName(), stored.size());
                }
                zipIn.closeEntry();
            }
@@ -466,4 +456,24 @@ public class TaskManager {
        }
        return null;
    }
+
+    /**
+     * Find the job key that owns a given file ID.
+     *
+     * @param fileId file identifier to look up
+     * @return scoped job key if found, otherwise null
+     */
+    public String findJobKeyByFileId(String fileId) {
+        for (Map.Entry<String, JobResult> entry : jobResults.entrySet()) {
+            JobResult jobResult = entry.getValue();
+            if (jobResult.hasFiles()) {
+                for (ResultFile resultFile : jobResult.getAllResultFiles()) {
+                    if (fileId.equals(resultFile.getFileId())) {
+                        return entry.getKey();
+                    }
+                }
+            }
+        }
+        return null;
+    }
 }
@@ -4,6 +4,7 @@ import java.io.BufferedInputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.Enumeration;
@@ -30,15 +31,7 @@ import stirling.software.common.service.CustomPDFDocumentFactory;
@UtilityClass
 public class CbzUtils {

-    public byte[] convertCbzToPdf(
-            MultipartFile cbzFile,
-            CustomPDFDocumentFactory pdfDocumentFactory,
-            TempFileManager tempFileManager)
-            throws IOException {
-        return convertCbzToPdf(cbzFile, pdfDocumentFactory, tempFileManager, false);
-    }
-
-    public byte[] convertCbzToPdf(
+    public TempFile convertCbzToPdf(
            MultipartFile cbzFile,
            CustomPDFDocumentFactory pdfDocumentFactory,
            TempFileManager tempFileManager,
@@ -64,70 +57,90 @@ public class CbzUtils {

            try (PDDocument document = pdfDocumentFactory.createNewDocument();
                    ZipFile zipFile = new ZipFile(tempFile.getFile())) {
+
+                // Pass 1: collect sorted image names (cheap just strings, no image data)
+                List<String> sortedImageNames = new ArrayList<>();
                Enumeration<? extends ZipEntry> entries = zipFile.entries();
-                List<ImageEntryData> imageEntries = new ArrayList<>();
                while (entries.hasMoreElements()) {
                    ZipEntry entry = entries.nextElement();
                    if (!entry.isDirectory() && isImageFile(entry.getName())) {
-                        try (InputStream is = zipFile.getInputStream(entry)) {
-                            ByteArrayOutputStream baos = new ByteArrayOutputStream();
-                            is.transferTo(baos);
-                            imageEntries.add(
-                                    new ImageEntryData(entry.getName(), baos.toByteArray()));
-                        } catch (IOException e) {
-                            log.warn("Error reading image {}: {}", entry.getName(), e.getMessage());
-                        }
+                        sortedImageNames.add(entry.getName());
                    }
                }
+                sortedImageNames.sort(new NaturalOrderComparator());

-                imageEntries.sort(
-                        Comparator.comparing(ImageEntryData::name, new NaturalOrderComparator()));
-
-                if (imageEntries.isEmpty()) {
+                if (sortedImageNames.isEmpty()) {
                    throw ExceptionUtils.createCbzNoImagesException();
                }

-                for (ImageEntryData imageEntry : imageEntries) {
-                    try {
-                        PDImageXObject pdImage =
-                                PDImageXObject.createFromByteArray(
-                                        document, imageEntry.data(), imageEntry.name());
-                        PDPage page =
-                                new PDPage(
-                                        new PDRectangle(pdImage.getWidth(), pdImage.getHeight()));
-                        document.addPage(page);
-                        try (PDPageContentStream contentStream =
-                                new PDPageContentStream(
-                                        document,
-                                        page,
-                                        PDPageContentStream.AppendMode.OVERWRITE,
-                                        true,
-                                        true)) {
-                            contentStream.drawImage(pdImage, 0, 0);
+                // Pass 2: load ONE image at a time peak memory = max(single image)
+                for (String imageName : sortedImageNames) {
+                    ZipEntry entry = zipFile.getEntry(imageName);
+                    try (InputStream is = zipFile.getInputStream(entry)) {
+                        ByteArrayOutputStream imgBaos = new ByteArrayOutputStream();
+                        is.transferTo(imgBaos);
+                        byte[] imageBytes = imgBaos.toByteArray();
+                        try {
+                            PDImageXObject pdImage =
+                                    PDImageXObject.createFromByteArray(
+                                            document, imageBytes, imageName);
+                            PDPage page =
+                                    new PDPage(
+                                            new PDRectangle(
+                                                    pdImage.getWidth(), pdImage.getHeight()));
+                            document.addPage(page);
+                            try (PDPageContentStream contentStream =
+                                    new PDPageContentStream(
+                                            document,
+                                            page,
+                                            PDPageContentStream.AppendMode.OVERWRITE,
+                                            true,
+                                            true)) {
+                                contentStream.drawImage(pdImage, 0, 0);
+                            }
+                        } catch (IOException e) {
+                            log.warn("Error processing image {}: {}", imageName, e.getMessage());
                        }
+                        // imageBytes eligible for GC after each iteration
                    } catch (IOException e) {
-                        log.warn(
-                                "Error processing image {}: {}", imageEntry.name(), e.getMessage());
+                        log.warn("Error reading image {}: {}", imageName, e.getMessage());
                    }
                }

                if (document.getNumberOfPages() == 0) {
                    throw ExceptionUtils.createCbzCorruptedImagesException();
                }
-                ByteArrayOutputStream baos = new ByteArrayOutputStream();
-                document.save(baos);
-                byte[] pdfBytes = baos.toByteArray();

-                // Apply Ghostscript optimization if requested
-                if (optimizeForEbook) {
-                    try {
-                        return GeneralUtils.optimizePdfWithGhostscript(pdfBytes);
-                    } catch (IOException e) {
-                        log.warn("Ghostscript optimization failed, returning unoptimized PDF", e);
+                // Write to TempFile (not BAOS)
+                TempFile pdfTempFile = new TempFile(tempFileManager, ".pdf");
+                try {
+                    document.save(pdfTempFile.getFile());
+
+                    if (optimizeForEbook) {
+                        try {
+                            byte[] pdfBytes = Files.readAllBytes(pdfTempFile.getPath());
+                            byte[] optimized = GeneralUtils.optimizePdfWithGhostscript(pdfBytes);
+                            pdfTempFile.close();
+                            TempFile optimizedFile = new TempFile(tempFileManager, ".pdf");
+                            try {
+                                Files.write(optimizedFile.getPath(), optimized);
+                                return optimizedFile;
+                            } catch (Exception e) {
+                                optimizedFile.close();
+                                throw e;
+                            }
+                        } catch (IOException e) {
+                            log.warn(
+                                    "Ghostscript optimization failed, returning unoptimized PDF",
+                                    e);
+                        }
                    }
-                }

-                return pdfBytes;
+                    return pdfTempFile;
+                } catch (Exception e) {
+                    pdfTempFile.close();
+                    throw e;
+                }
            }
        }
    }
@@ -175,8 +188,6 @@ public class CbzUtils {
        return RegexPatternUtils.getInstance().getImageFilePattern().matcher(filename).matches();
    }

-    private record ImageEntryData(String name, byte[] data) {}
-
    private class NaturalOrderComparator implements Comparator<String> {
        @Override
        public int compare(String s1, String s2) {
@@ -13,11 +13,18 @@ public class EmlToPdf {

    public static String convertEmlToHtml(byte[] emlBytes, EmlToPdfRequest request)
            throws IOException {
+        return convertEmlToHtml(emlBytes, request, null);
+    }
+
+    public static String convertEmlToHtml(
+            byte[] emlBytes, EmlToPdfRequest request, CustomHtmlSanitizer customHtmlSanitizer)
+            throws IOException {
        EmlProcessingUtils.validateEmlInput(emlBytes);

        EmlParser.EmailContent emailContent =
-                EmlParser.extractEmailContent(emlBytes, request, null);
-        return EmlProcessingUtils.generateEnhancedEmailHtml(emailContent, request, null);
+                EmlParser.extractEmailContent(emlBytes, request, customHtmlSanitizer);
+        return EmlProcessingUtils.generateEnhancedEmailHtml(
+                emailContent, request, customHtmlSanitizer);
    }

    public static byte[] convertEmlToPdf(
@@ -2,30 +2,28 @@ package stirling.software.common.util;

 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;

-import lombok.extern.slf4j.Slf4j;
+/**
+ * Factory for creating executors backed by virtual threads (Java 21+). Virtual threads are
+ * lightweight, managed by the JVM, and ideal for I/O-bound tasks. They eliminate the need for
+ * thread pool sizing since thousands can run concurrently with minimal overhead.
+ */
+public final class ExecutorFactory {

-@Slf4j
-public class ExecutorFactory {
+    private ExecutorFactory() {}
+
+    /** Creates an {@link ExecutorService} that starts a new virtual thread for each task. */
+    public static ExecutorService newVirtualThreadExecutor() {
+        return Executors.newVirtualThreadPerTaskExecutor();
+    }

    /**
-     * Creates an ExecutorService using virtual threads if available (Java 21+), or falls back to a
-     * cached thread pool on older Java versions.
+     * Creates a {@link ScheduledExecutorService} backed by a single virtual thread. Useful for
+     * periodic/delayed tasks that should not pin a platform thread.
     */
-    public static ExecutorService newVirtualOrCachedThreadExecutor() {
-        try {
-            ExecutorService executor =
-                    (ExecutorService)
-                            Executors.class
-                                    .getMethod("newVirtualThreadPerTaskExecutor")
-                                    .invoke(null);
-            return executor;
-        } catch (NoSuchMethodException e) {
-            log.debug("Virtual threads not available; falling back to cached thread pool.");
-        } catch (Exception e) {
-            log.debug("Error initializing virtual thread executor: {}", e.getMessage(), e);
-        }
-
-        return Executors.newCachedThreadPool();
+    public static ScheduledExecutorService newSingleVirtualThreadScheduledExecutor() {
+        return Executors.newSingleThreadScheduledExecutor(
+                Thread.ofVirtual().name("scheduled-vt-", 0).factory());
    }
 }
@@ -68,6 +68,17 @@ public class FileMonitor {

        if (this.rootDirs.isEmpty()) {
            log.error("No valid directories to monitor - FileMonitor will not function");
+        } else {
+            // Register directories eagerly so the first @Scheduled tick does not warn.
+            for (Path rootDir : this.rootDirs) {
+                if (Files.exists(rootDir)) {
+                    try {
+                        recursivelyRegisterEntry(rootDir);
+                    } catch (IOException e) {
+                        log.error("Failed to register monitoring for {}", rootDir, e);
+                    }
+                }
+            }
        }
    }

@@ -0,0 +1,217 @@
+package stirling.software.common.util;
+
+import java.io.IOException;
+import java.io.RandomAccessFile;
+import java.nio.channels.FileChannel;
+import java.nio.channels.FileLock;
+import java.nio.channels.OverlappingFileLockException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Locale;
+
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.model.ApplicationProperties.AutoPipeline.FileReadiness;
+
+/**
+ * Stateless safety checker that decides whether a file is stable and ready for pipeline processing.
+ * Call {@link #isReady(Path)} before moving or processing any file picked up from a watched folder.
+ *
+ * <p>A file is considered ready when ALL of the following hold:
+ *
+ * <ol>
+ *   <li>The file exists on disk.
+ *   <li>The path refers to a regular file, not a directory.
+ *   <li>The file's extension matches the configured allow-list (if one is set).
+ *   <li>The file has not been modified within the configured settle window ({@code
+ *       settleTimeMillis}), meaning it is no longer being written.
+ *   <li>The file size is stable: two reads separated by {@code sizeCheckDelayMillis} return the
+ *       same value. This catches active copies on Linux/macOS where advisory file locking alone
+ *       cannot detect a mid-copy file.
+ *   <li>An exclusive file-system lock can be acquired, confirming no other process holds it.
+ * </ol>
+ *
+ * <p>All behaviour is controlled through {@link FileReadiness} inside {@link
+ * ApplicationProperties.AutoPipeline}. Setting {@code enabled: false} makes every call return
+ * {@code true} so the checker is a no-op drop-in.
+ */
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class FileReadinessChecker {
+
+    private final ApplicationProperties applicationProperties;
+
+    /**
+     * Returns {@code true} when the file at {@code path} passes every readiness check and is safe
+     * to hand off to the pipeline for processing. Returns {@code false} when any check fails; the
+     * caller should skip the file and retry on the next scan cycle.
+     */
+    public boolean isReady(Path path) {
+        FileReadiness config = applicationProperties.getAutoPipeline().getFileReadiness();
+
+        if (!config.isEnabled()) {
+            return true;
+        }
+
+        if (!existsAsRegularFile(path)) {
+            return false;
+        }
+
+        if (!isExtensionAllowed(path, config.getAllowedExtensions())) {
+            return false;
+        }
+
+        if (!hasSettled(path, config.getSettleTimeMillis())) {
+            return false;
+        }
+
+        if (!hasSizeStabilized(path, config.getSizeCheckDelayMillis())) {
+            return false;
+        }
+
+        if (isLocked(path)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    // -------------------------------------------------------------------------
+    // Individual checks
+    // -------------------------------------------------------------------------
+
+    private boolean existsAsRegularFile(Path path) {
+        if (!Files.exists(path)) {
+            log.debug("File does not exist, skipping: {}", path);
+            return false;
+        }
+        if (!Files.isRegularFile(path)) {
+            log.debug("Path is not a regular file (directory or symlink?), skipping: {}", path);
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Returns {@code true} when {@code allowedExtensions} is empty (no filter) or when the file's
+     * extension (case-insensitive) appears in the list.
+     */
+    private boolean isExtensionAllowed(Path path, List<String> allowedExtensions) {
+        if (allowedExtensions == null || allowedExtensions.isEmpty()) {
+            return true;
+        }
+        String filename = path.getFileName().toString();
+        String extension =
+                filename.contains(".")
+                        ? filename.substring(filename.lastIndexOf('.') + 1).toLowerCase(Locale.ROOT)
+                        : "";
+        boolean allowed =
+                allowedExtensions.stream().anyMatch(ext -> ext.equalsIgnoreCase(extension));
+        if (!allowed) {
+            log.debug(
+                    "File '{}' has extension '{}' which is not in the allowed list {}, skipping",
+                    filename,
+                    extension,
+                    allowedExtensions);
+        }
+        return allowed;
+    }
+
+    /**
+     * Returns {@code true} when the file's last-modified timestamp is at least {@code
+     * settleTimeMillis} milliseconds in the past, indicating the write has completed and the file
+     * has "settled".
+     */
+    private boolean hasSettled(Path path, long settleTimeMillis) {
+        try {
+            long lastModified = Files.getLastModifiedTime(path).toMillis();
+            long ageMillis = System.currentTimeMillis() - lastModified;
+            boolean settled = ageMillis >= settleTimeMillis;
+            if (!settled) {
+                log.debug(
+                        "File '{}' was modified {}ms ago (settle threshold: {}ms), not yet ready",
+                        path.getFileName(),
+                        ageMillis,
+                        settleTimeMillis);
+            }
+            return settled;
+        } catch (IOException e) {
+            log.warn(
+                    "Could not read last-modified time for '{}', treating as not settled: {}",
+                    path,
+                    e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * Returns {@code true} when the file size is the same before and after a short pause of {@code
+     * sizeCheckDelayMillis} milliseconds. A size change indicates another process is still
+     * appending to the file. This is the primary write-detection mechanism on Linux/macOS, where
+     * mandatory file locking is not enforced by the OS.
+     */
+    private boolean hasSizeStabilized(Path path, long sizeCheckDelayMillis) {
+        try {
+            long sizeBefore = Files.size(path);
+            Thread.sleep(sizeCheckDelayMillis);
+            long sizeAfter = Files.size(path);
+            boolean stable = sizeBefore == sizeAfter;
+            if (!stable) {
+                log.debug(
+                        "File '{}' size changed from {} to {} bytes during stability check,"
+                                + " not yet ready",
+                        path.getFileName(),
+                        sizeBefore,
+                        sizeAfter);
+            }
+            return stable;
+        } catch (IOException e) {
+            log.warn(
+                    "Could not read file size for '{}', treating as unstable: {}",
+                    path,
+                    e.getMessage());
+            return false;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            log.warn(
+                    "Size stability check interrupted for '{}', treating as unstable",
+                    path.getFileName());
+            return false;
+        }
+    }
+
+    /**
+     * Returns {@code true} when an exclusive file-system lock cannot be acquired, which indicates
+     * another process still holds the file open for writing.
+     *
+     * <p>{@link OverlappingFileLockException} is also treated as locked: the JVM already holds a
+     * lock on this file (e.g. from another thread), so it is unsafe to process.
+     */
+    private boolean isLocked(Path path) {
+        try (RandomAccessFile raf = new RandomAccessFile(path.toFile(), "rw");
+                FileChannel channel = raf.getChannel()) {
+            FileLock lock = channel.tryLock();
+            if (lock == null) {
+                log.debug("File '{}' is locked by another process", path.getFileName());
+                return true;
+            }
+            lock.release();
+            return false;
+        } catch (OverlappingFileLockException e) {
+            log.debug("File '{}' is already locked by this JVM", path.getFileName());
+            return true;
+        } catch (IOException e) {
+            log.debug(
+                    "Could not acquire lock on '{}', treating as locked: {}",
+                    path.getFileName(),
+                    e.getMessage());
+            return true;
+        }
+    }
+}
@@ -44,9 +44,7 @@ public class FileToPdf {
                            sanitizeHtmlContent(
                                    new String(fileBytes, StandardCharsets.UTF_8),
                                    customHtmlSanitizer);
-                    Files.write(
-                            tempInputFile.getPath(),
-                            sanitizedHtml.getBytes(StandardCharsets.UTF_8));
+                    Files.writeString(tempInputFile.getPath(), sanitizedHtml);
                } else if (fileName.toLowerCase(Locale.ROOT).endsWith(".zip")) {
                    Files.write(tempInputFile.getPath(), fileBytes);
                    sanitizeHtmlFilesInZip(
@@ -100,6 +98,13 @@ public class FileToPdf {
                while (entry != null) {
                    Path filePath =
                            tempUnzippedDir.getPath().resolve(sanitizeZipFilename(entry.getName()));
+                    Path normalizedTargetDir =
+                            tempUnzippedDir.getPath().toAbsolutePath().normalize();
+                    Path normalizedFilePath = filePath.toAbsolutePath().normalize();
+                    if (!normalizedFilePath.startsWith(normalizedTargetDir)) {
+                        throw new IOException(
+                                "Zip entry path escapes target directory: " + entry.getName());
+                    }
                    if (!entry.isDirectory()) {
                        Files.createDirectories(filePath.getParent());
                        if (entry.getName().toLowerCase(Locale.ROOT).endsWith(".html")
@@ -108,8 +113,7 @@ public class FileToPdf {
                                    new String(zipIn.readAllBytes(), StandardCharsets.UTF_8);
                            String sanitizedContent =
                                    sanitizeHtmlContent(content, customHtmlSanitizer);
-                            Files.write(
-                                    filePath, sanitizedContent.getBytes(StandardCharsets.UTF_8));
+                            Files.writeString(filePath, sanitizedContent);
                        } else {
                            Files.copy(zipIn, filePath);
                        }
@@ -1,4 +1,4 @@
-package stirling.software.proprietary.util;
+package stirling.software.common.util;

 import java.io.IOException;
 import java.util.Arrays;
@@ -1,10 +1,11 @@
-package stirling.software.proprietary.util;
+package stirling.software.common.util;

 import java.awt.image.BufferedImage;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.Comparator;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.IdentityHashMap;
@@ -16,8 +17,10 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.regex.Pattern;

 import org.apache.pdfbox.cos.COSArray;
+import org.apache.pdfbox.cos.COSBase;
 import org.apache.pdfbox.cos.COSDictionary;
 import org.apache.pdfbox.cos.COSName;
 import org.apache.pdfbox.pdmodel.PDDocument;
@@ -46,9 +49,7 @@ import lombok.experimental.UtilityClass;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;
-import stirling.software.common.util.ApplicationContextProvider;
-import stirling.software.common.util.ExceptionUtils;
-import stirling.software.common.util.RegexPatternUtils;
+import stirling.software.common.model.FormFieldWithCoordinates;

@Slf4j
@UtilityClass
@@ -67,6 +68,17 @@ public class FormUtils {
    public final Set<String> CHOICE_FIELD_TYPES =
            Set.of(FIELD_TYPE_COMBOBOX, FIELD_TYPE_LISTBOX, FIELD_TYPE_RADIO);

+    /**
+     * Threshold in PDF points for considering two widgets to be on the same line. Fields whose
+     * y-coordinates differ by less than this value are sorted left-to-right by x-coordinate instead
+     * of top-to-bottom.
+     */
+    private static final float SAME_LINE_THRESHOLD_PT = 10.0f;
+
+    private static final Pattern HEX_UUID_PATTERN =
+            Pattern.compile("^[0-9a-fA-F]{8}[0-9a-fA-F]{24,}$");
+    private static final Pattern WHITESPACE_PATTERN = Pattern.compile("\\s+");
+
    /**
     * Returns a normalized logical type string for the supplied PDFBox field instance. Centralized
     * so all callers share identical mapping logic.
@@ -109,6 +121,8 @@ public class FormUtils {
        List<FormFieldInfo> fields = new ArrayList<>();
        Map<String, Integer> typeCounters = new HashMap<>();
        Map<Integer, Integer> pageOrderCounters = new HashMap<>();
+        Map<COSDictionary, Integer> annotationPageMap = buildAnnotationPageMap(document);
+
        for (PDField field : acroForm.getFieldTree()) {
            if (!(field instanceof PDTerminalField terminalField)) {
                continue;
@@ -123,9 +137,9 @@ public class FormUtils {
                continue;
            }

-            String currentValue = safeValue(terminalField);
+            String currentValue = safeFieldValue(terminalField);
            boolean required = field.isRequired();
-            int pageIndex = resolveFirstWidgetPageIndex(document, terminalField);
+            int pageIndex = resolveFirstWidgetPageIndex(document, terminalField, annotationPageMap);
            List<String> options = resolveOptions(terminalField);
            String tooltip = resolveTooltip(terminalField);
            int typeIndex = typeCounters.merge(type, 1, Integer::sum);
@@ -164,6 +178,396 @@ public class FormUtils {
        return Collections.unmodifiableList(fields);
    }

+    /**
+     * Extract form fields with widget coordinates for the interactive form viewer.
+     *
+     * @param document PDF document
+     * @return List of form fields with coordinates and metadata
+     */
+    public List<FormFieldWithCoordinates> extractFormFieldsWithCoordinates(PDDocument document) {
+        if (document == null) return List.of();
+
+        PDAcroForm acroForm = getAcroFormSafely(document);
+        if (acroForm == null) return List.of();
+
+        List<FormFieldWithCoordinates> fields = new ArrayList<>();
+        Map<String, Integer> typeCounters = new HashMap<>();
+
+        Map<COSDictionary, Integer> annotationPageMap = buildAnnotationPageMap(document);
+
+        for (PDField field : acroForm.getFieldTree()) {
+            if (!(field instanceof PDTerminalField terminalField)) {
+                continue;
+            }
+
+            String type = detectFieldType(terminalField);
+            String name =
+                    Optional.ofNullable(field.getFullyQualifiedName())
+                            .orElseGet(field::getPartialName);
+            if (name == null || name.isBlank()) {
+                continue;
+            }
+
+            String currentValue = safeFieldValue(terminalField);
+            boolean required = field.isRequired();
+            boolean readOnly = field.isReadOnly();
+            List<String> options = resolveOptions(terminalField);
+            List<String> displayOptions = resolveDisplayOptions(terminalField);
+            String tooltip = resolveTooltip(terminalField);
+            int typeIndex = typeCounters.merge(type, 1, Integer::sum);
+            String displayLabel =
+                    deriveDisplayLabel(field, name, tooltip, type, typeIndex, options);
+            boolean multiSelect = resolveMultiSelect(terminalField);
+            boolean multiline =
+                    terminalField instanceof PDTextField
+                            && ((PDTextField) terminalField).isMultiline();
+
+            // Extract widget coordinates
+            List<FormFieldWithCoordinates.WidgetCoordinates> widgets =
+                    extractWidgetCoordinates(document, terminalField, annotationPageMap);
+
+            // Only include displayOptions when they differ from export options
+            List<String> displayOptsToSend = null;
+            if (displayOptions != null
+                    && !displayOptions.isEmpty()
+                    && !displayOptions.equals(options)) {
+                displayOptsToSend = displayOptions;
+            }
+
+            fields.add(
+                    FormFieldWithCoordinates.builder()
+                            .name(name)
+                            .label(displayLabel)
+                            .type(type)
+                            .value(currentValue)
+                            .options(options.isEmpty() ? null : options)
+                            .displayOptions(displayOptsToSend)
+                            .required(required)
+                            .readOnly(readOnly)
+                            .multiSelect(multiSelect)
+                            .multiline(multiline)
+                            .tooltip(tooltip)
+                            .widgets(widgets.isEmpty() ? null : widgets)
+                            .build());
+        }
+
+        // Sort by page and position
+        fields.sort(new FieldCoordinateComparator());
+
+        log.debug("Total fields processed: {}", fields.size());
+        log.debug(
+                "Fields WITH widgets: {}",
+                fields.stream()
+                        .filter(f -> f.getWidgets() != null && !f.getWidgets().isEmpty())
+                        .count());
+        log.debug(
+                "Fields WITHOUT widgets: {}",
+                fields.stream()
+                        .filter(f -> f.getWidgets() == null || f.getWidgets().isEmpty())
+                        .count());
+
+        fields.stream()
+                .filter(f -> f.getWidgets() == null || f.getWidgets().isEmpty())
+                .forEach(
+                        f ->
+                                log.debug(
+                                        "Field '{}' type={} has NO widget coordinates",
+                                        f.getName(),
+                                        f.getType()));
+
+        return Collections.unmodifiableList(fields);
+    }
+
+    /**
+     * Extract widget coordinates for a form field.
+     *
+     * @param document PDF document
+     * @param field Terminal field
+     * @return List of widget coordinates
+     */
+    private List<FormFieldWithCoordinates.WidgetCoordinates> extractWidgetCoordinates(
+            PDDocument document,
+            PDTerminalField field,
+            Map<COSDictionary, Integer> annotationPageMap) {
+        List<FormFieldWithCoordinates.WidgetCoordinates> result = new ArrayList<>();
+
+        List<PDAnnotationWidget> widgets = field.getWidgets();
+
+        log.debug(
+                "Field '{}' type={} has {} widgets",
+                field.getFullyQualifiedName(),
+                field.getClass().getSimpleName(),
+                widgets != null ? widgets.size() : 0);
+
+        if (widgets == null || widgets.isEmpty()) {
+            // Some fields (especially text fields) might be their own widget annotation
+            log.trace(
+                    "Field '{}' has no widgets, checking if field acts as its own annotation",
+                    field.getFullyQualifiedName());
+            try {
+                COSDictionary fieldDict = field.getCOSObject();
+                COSBase rectBase = fieldDict.getDictionaryObject(COSName.RECT);
+                if (rectBase instanceof COSArray rectArray) {
+                    int pageIndex =
+                            findPageIndexForAnnotation(document, fieldDict, annotationPageMap);
+                    if (pageIndex >= 0) {
+                        PDRectangle rectangle = new PDRectangle(rectArray);
+                        result.add(
+                                createWidgetCoordinates(
+                                        document, rectangle, pageIndex, null, field));
+                    } else {
+                        log.warn(
+                                "Found rectangle for field '{}' but could not resolve page index",
+                                field.getFullyQualifiedName());
+                    }
+                }
+            } catch (Exception e) {
+                log.debug(
+                        "Could not extract direct rectangle for field '{}': {}",
+                        field.getFullyQualifiedName(),
+                        e.getMessage());
+            }
+            return result;
+        }
+
+        // For radio buttons, pre-resolve export values per widget
+        List<String> exportValues = null;
+        if (field instanceof PDRadioButton radio) {
+            exportValues = radio.getExportValues();
+        }
+
+        for (int i = 0; i < widgets.size(); i++) {
+            PDAnnotationWidget widget = widgets.get(i);
+            try {
+                PDRectangle rectangle = widget.getRectangle();
+                if (rectangle == null) {
+                    log.warn(
+                            "Field '{}' widget {} has NULL rectangle",
+                            field.getFullyQualifiedName(),
+                            i);
+                    continue;
+                }
+
+                int pageIndex = resolveWidgetPageIndex(document, widget, annotationPageMap);
+                if (pageIndex < 0) {
+                    log.warn(
+                            "Field '{}' widget {} could not resolve page index",
+                            field.getFullyQualifiedName(),
+                            i);
+                    continue;
+                }
+
+                // Resolve export value for radio/checkbox widgets
+                String exportValue = null;
+                if (exportValues != null && i < exportValues.size()) {
+                    exportValue = exportValues.get(i);
+                } else if (field instanceof PDButton) {
+                    // Fall back to appearance state name from the widget's normal appearance
+                    try {
+                        var ap = widget.getAppearance();
+                        if (ap != null && ap.getNormalAppearance() != null) {
+                            var normalAp = ap.getNormalAppearance();
+                            if (normalAp.isSubDictionary()) {
+                                for (var cosName : normalAp.getSubDictionary().keySet()) {
+                                    String key = cosName.getName();
+                                    if (!"Off".equals(key)) {
+                                        exportValue = key;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                    } catch (Exception e) {
+                        log.trace(
+                                "Could not extract export value for widget in '{}': {}",
+                                field.getFullyQualifiedName(),
+                                e.getMessage());
+                    }
+                }
+
+                result.add(
+                        createWidgetCoordinates(
+                                document, rectangle, pageIndex, exportValue, field));
+            } catch (Exception e) {
+                log.debug(
+                        "Failed to extract coordinates for widget in field '{}': {}",
+                        field.getFullyQualifiedName(),
+                        e.getMessage());
+            }
+        }
+
+        return result;
+    }
+
+    private FormFieldWithCoordinates.WidgetCoordinates createWidgetCoordinates(
+            PDDocument document,
+            PDRectangle rectangle,
+            int pageIndex,
+            String exportValue,
+            PDTerminalField field) {
+        if (pageIndex < 0 || pageIndex >= document.getNumberOfPages()) {
+            return null;
+        }
+
+        PDPage page = document.getPage(pageIndex);
+        PDRectangle cropBox = page.getCropBox();
+
+        // Use CropBox dimensions for the y-flip.
+        // Note: getWidth() and getHeight() return dimensions BEFORE rotation.
+        float cropHeight = cropBox.getHeight();
+
+        // Get absolute widget coordinates (in MediaBox space, un-rotated)
+        float pdfX = rectangle.getLowerLeftX();
+        float pdfY = rectangle.getLowerLeftY();
+        float width = rectangle.getWidth();
+        float height = rectangle.getHeight();
+
+        // Adjust relative to CropBox origin
+        float relativeX = pdfX - cropBox.getLowerLeftX();
+        float relativeY = pdfY - cropBox.getLowerLeftY();
+
+        // Convert from PDF lower-left origin to CSS upper-left origin (y-flip).
+        // Widget /Rect coordinates are always in un-rotated PDF user space.
+        // The embedpdf viewer wraps all page content inside a <Rotate> CSS
+        // component that handles visual rotation — we must NOT apply any
+        // rotation transform here, or widgets would be double-rotated.
+        float finalX = relativeX;
+        float finalY = cropHeight - relativeY - height;
+        float finalW = width;
+        float finalH = height;
+
+        // Validate coordinates are within reasonable bounds
+        if (finalX < -1.0f
+                || finalY < -1.0f
+                || finalX > cropBox.getWidth() * 2 // Allow some horizontal overflow
+                || finalY > cropHeight + 1.0f) {
+            log.warn(
+                    "Widget coordinates out of bounds for field '{}': page={}, x={}, y={}, w={}, h={}",
+                    field.getFullyQualifiedName(),
+                    pageIndex,
+                    finalX,
+                    finalY,
+                    finalW,
+                    finalH);
+            return null;
+        }
+
+        return FormFieldWithCoordinates.WidgetCoordinates.builder()
+                .pageIndex(pageIndex)
+                .x(finalX)
+                .y(finalY)
+                .width(finalW)
+                .height(finalH)
+                .exportValue(exportValue)
+                .fontSize(extractFontSize(field))
+                .build();
+    }
+
+    /**
+     * Repairs widgets with missing page references by scanning all pages and setting the /P entry
+     * for orphan widgets.
+     *
+     * <p>This should be called BEFORE extracting form field coordinates.
+     *
+     * @param document PDF document to repair
+     */
+    public void repairMissingWidgetPageReferences(PDDocument document) {
+        try {
+            PDAcroForm acroForm = getAcroFormSafely(document);
+            if (acroForm == null) {
+                return;
+            }
+
+            log.debug("Checking for widgets with missing page references...");
+            int repairedCount = 0;
+
+            Map<COSDictionary, Integer> annotationPageMap = buildAnnotationPageMap(document);
+
+            for (PDField field : acroForm.getFieldTree()) {
+                if (!(field instanceof PDTerminalField terminalField)) {
+                    continue;
+                }
+
+                List<PDAnnotationWidget> widgets = terminalField.getWidgets();
+
+                if (widgets == null || widgets.isEmpty()) {
+                    continue;
+                }
+
+                for (PDAnnotationWidget widget : widgets) {
+                    if (widget.getPage() == null) {
+                        Integer pageIndex = annotationPageMap.get(widget.getCOSObject());
+                        if (pageIndex != null && pageIndex >= 0) {
+                            PDPage foundPage = document.getPage(pageIndex);
+                            widget.setPage(foundPage);
+                            repairedCount++;
+                            log.debug(
+                                    "Repaired widget for field '{}' - set page reference via map",
+                                    field.getFullyQualifiedName());
+                        } else {
+                            log.warn(
+                                    "Could not find page for widget in field '{}'",
+                                    field.getFullyQualifiedName());
+                        }
+                    }
+                }
+            }
+
+            if (repairedCount > 0) {
+                log.debug(
+                        "Successfully repaired {} widgets with missing page references",
+                        repairedCount);
+            } else {
+                log.debug("No widgets needed repair");
+            }
+
+        } catch (Exception e) {
+            log.error("Error repairing widget page references: {}", e.getMessage(), e);
+        }
+    }
+
+    private int findPageIndexForAnnotation(
+            PDDocument document,
+            COSDictionary annotDict,
+            Map<COSDictionary, Integer> annotationPageMap) {
+        try {
+            // Method 0: Check the pre-built lookup map (fastest)
+            if (annotationPageMap != null) {
+                Integer idx = annotationPageMap.get(annotDict);
+                if (idx != null) {
+                    return idx;
+                }
+            }
+
+            // Method 1: Check the /P entry if it points to a page
+            COSBase base = annotDict.getDictionaryObject(COSName.P);
+            COSDictionary pageDict = (base instanceof COSDictionary c) ? c : null;
+            if (pageDict != null) {
+                for (int i = 0; i < document.getNumberOfPages(); i++) {
+                    if (document.getPage(i).getCOSObject() == pageDict) {
+                        return i;
+                    }
+                }
+            }
+
+            // Method 2: Fallback search through all pages' annotations
+            for (int i = 0; i < document.getNumberOfPages(); i++) {
+                PDPage page = document.getPage(i);
+                List<PDAnnotation> annotations = page.getAnnotations();
+                if (annotations != null) {
+                    for (PDAnnotation annot : annotations) {
+                        if (annot != null && annot.getCOSObject() == annotDict) {
+                            return i;
+                        }
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.trace("Error finding page for annotation: {}", e.getMessage());
+        }
+        return -1;
+    }
+
    /**
     * Build a single record object (field-name -> value placeholder) that can be directly submitted
     * to /api/v1/form/fill as the 'data' JSON. For checkboxes a boolean false is supplied unless
@@ -312,7 +716,24 @@ public class FormUtils {
            return;
        }

-        flattenViaRendering(document, acroForm);
+        if (acroForm == null) {
+            return;
+        }
+
+        // Use PDFBox's built-in field flattening which bakes form field values
+        // into the page content stream as static text/graphics, removing the
+        // interactive form structure but preserving all other document content
+        // (images, text, annotations, etc.) at full quality.
+        try {
+            ensureAppearances(acroForm);
+            acroForm.flatten();
+        } catch (Exception e) {
+            log.warn(
+                    "PDFBox acroForm.flatten() failed, falling back to rendering: {}",
+                    e.getMessage(),
+                    e);
+            flattenViaRendering(document, acroForm);
+        }
    }

    private void rebuildDocumentFromImages(PDDocument document, PDFRenderer renderer, int dpi)
@@ -385,7 +806,7 @@ public class FormUtils {

                PDPage page = widget.getPage();
                if (page == null) {
-                    page = resolveWidgetPage(document, widget);
+                    page = resolveWidgetPage(document, widget, null);
                    if (page != null) {
                        widget.setPage(page);
                    }
@@ -818,8 +1239,22 @@ public class FormUtils {
        return states;
    }

-    private String safeValue(PDTerminalField field) {
+    public String safeValue(String value) {
+        return value != null ? value : "";
+    }
+
+    private String safeFieldValue(PDTerminalField field) {
        try {
+            // PDChoice.getValueAsString() returns a raw COS string representation
+            // that doesn't reliably reflect the selected value. Use getValue()
+            // which returns the proper List<String> of selected options.
+            if (field instanceof PDChoice choiceField) {
+                List<String> selected = choiceField.getValue();
+                if (selected == null || selected.isEmpty()) {
+                    return null;
+                }
+                return String.join(",", selected);
+            }
            return field.getValueAsString();
        } catch (Exception e) {
            log.debug(
@@ -833,14 +1268,25 @@ public class FormUtils {
    List<String> resolveOptions(PDTerminalField field) {
        try {
            if (field instanceof PDChoice choice) {
-                List<String> display = choice.getOptionsDisplayValues();
-                if (display != null && !display.isEmpty()) {
-                    return new ArrayList<>(display);
-                }
+                LinkedHashSet<String> allowed = new LinkedHashSet<>();
                List<String> exportValues = choice.getOptionsExportValues();
-                if (exportValues != null && !exportValues.isEmpty()) {
-                    return new ArrayList<>(exportValues);
+                List<String> displayValues = choice.getOptionsDisplayValues();
+
+                if (exportValues != null) {
+                    exportValues.stream()
+                            .filter(Objects::nonNull)
+                            .map(String::trim)
+                            .filter(s -> !s.isEmpty())
+                            .forEach(allowed::add);
                }
+                if (displayValues != null) {
+                    displayValues.stream()
+                            .filter(Objects::nonNull)
+                            .map(String::trim)
+                            .filter(s -> !s.isEmpty())
+                            .forEach(allowed::add);
+                }
+                return new ArrayList<>(allowed);
            } else if (field instanceof PDRadioButton radio) {
                List<String> exports = radio.getExportValues();
                if (exports != null && !exports.isEmpty()) {
@@ -861,6 +1307,29 @@ public class FormUtils {
        return Collections.emptyList();
    }

+    /**
+     * Returns the display-value labels for a choice field's options. For radio / checkbox this
+     * returns an empty list (no separate display values). For PDChoice fields, if the PDF provides
+     * distinct display values, those are returned; otherwise an empty list (indicating that the
+     * export values from {@link #resolveOptions} should be shown directly).
+     */
+    List<String> resolveDisplayOptions(PDTerminalField field) {
+        try {
+            if (field instanceof PDChoice choice) {
+                List<String> display = choice.getOptionsDisplayValues();
+                if (display != null && !display.isEmpty()) {
+                    return new ArrayList<>(display);
+                }
+            }
+        } catch (Exception e) {
+            log.debug(
+                    "Failed to resolve display options for field '{}': {}",
+                    field.getFullyQualifiedName(),
+                    e.getMessage());
+        }
+        return Collections.emptyList();
+    }
+
    private boolean resolveMultiSelect(PDTerminalField field) {
        if (field instanceof PDListBox listBox) {
            try {
@@ -875,6 +1344,44 @@ public class FormUtils {
        return false;
    }

+    private Float extractFontSize(PDTerminalField field) {
+        try {
+            String da = null;
+            if (field instanceof PDVariableText vt) {
+                da = vt.getDefaultAppearance();
+            }
+
+            if (da == null || da.isBlank()) {
+                // Check parent/acroform default appearance if field's is missing
+                PDAcroForm form = field.getAcroForm();
+                if (form != null) {
+                    da = form.getDefaultAppearance();
+                }
+            }
+
+            if (da != null && !da.isBlank()) {
+                // Standard DA looks like: /Helv 12 Tf 0 g
+                // We want the number before 'Tf'
+                String[] tokens = WHITESPACE_PATTERN.split(da);
+                for (int i = 0; i < tokens.length; i++) {
+                    if ("Tf".equals(tokens[i]) && i > 0) {
+                        try {
+                            float size = Float.parseFloat(tokens[i - 1]);
+                            return size > 0 ? size : null;
+                        } catch (NumberFormatException ignored) {
+                        }
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.trace(
+                    "Could not extract font size for field '{}': {}",
+                    field.getFullyQualifiedName(),
+                    e.getMessage());
+        }
+        return null;
+    }
+
    private boolean isSettableCheckBoxState(String state) {
        if (state == null) return false;
        String trimmed = state.trim();
@@ -952,6 +1459,12 @@ public class FormUtils {

        if (simplified.isEmpty()) return true;

+        // Detect UUID-like hex strings (e.g. "cdc47b7041524571 7b2d93017fe77bf7")
+        // Standard UUIDs are 32 hex characters; require at least that to avoid
+        // false positives on short hex-like field names.
+        String nospaces = WHITESPACE_PATTERN.matcher(simplified).replaceAll("");
+        if (nospaces.length() >= 32 && HEX_UUID_PATTERN.matcher(nospaces).matches()) return true;
+
        return patterns.getGenericFieldNamePattern().matcher(simplified).matches()
                || patterns.getSimpleFormFieldPattern().matcher(simplified).matches()
                || patterns.getOptionalTNumericPattern().matcher(simplified).matches();
@@ -1007,7 +1520,7 @@ public class FormUtils {

            PDAnnotationWidget widget = widgets.get(0);
            PDRectangle originalRectangle = cloneRectangle(widget.getRectangle());
-            PDPage page = resolveWidgetPage(document, widget);
+            PDPage page = resolveWidgetPage(document, widget, null);
            if (page == null || originalRectangle == null) {
                log.warn(
                        "Unable to resolve widget page or rectangle for '{}'; skipping",
@@ -1064,7 +1577,7 @@ public class FormUtils {
                            desiredName,
                            modification.label(),
                            resolvedType,
-                            determineWidgetPageIndex(document, widget),
+                            determineWidgetPageIndex(document, widget, null),
                            originalRectangle.getLowerLeftX(),
                            originalRectangle.getLowerLeftY(),
                            originalRectangle.getWidth(),
@@ -1205,59 +1718,43 @@ public class FormUtils {
        return null;
    }

-    private int resolveFirstWidgetPageIndex(PDDocument document, PDTerminalField field) {
+    private int resolveFirstWidgetPageIndex(
+            PDDocument document,
+            PDTerminalField field,
+            Map<COSDictionary, Integer> annotationPageMap) {
        List<PDAnnotationWidget> widgets = field.getWidgets();
        if (widgets == null || widgets.isEmpty()) {
            return -1;
        }
-        Map<PDAnnotationWidget, Integer> widgetPageFallbacks = null;
        for (PDAnnotationWidget widget : widgets) {
-            int idx = resolveWidgetPageIndex(document, widget);
+            int idx = resolveWidgetPageIndex(document, widget, annotationPageMap);
            if (idx >= 0) {
                return idx;
            }
-            try {
-                COSDictionary widgetDictionary = widget.getCOSObject();
-                if (widgetDictionary != null
-                        && widgetDictionary.getDictionaryObject(COSName.P) == null) {
-                    if (widgetPageFallbacks == null) {
-                        widgetPageFallbacks = buildWidgetPageFallbackMap(document);
-                    }
-                    Integer fallbackIndex = widgetPageFallbacks.get(widget);
-                    if (fallbackIndex != null && fallbackIndex >= 0) {
-                        return fallbackIndex;
-                    }
-                }
-            } catch (Exception e) {
-                log.debug(
-                        "Failed to inspect widget page reference for field '{}': {}",
-                        field.getFullyQualifiedName(),
-                        e.getMessage());
-            }
        }
        return -1;
    }

-    private int resolveWidgetPageIndex(PDDocument document, PDAnnotationWidget widget) {
+    private int resolveWidgetPageIndex(
+            PDDocument document,
+            PDAnnotationWidget widget,
+            Map<COSDictionary, Integer> annotationPageMap) {
        if (document == null || widget == null) {
            return -1;
        }
-        try {
-            COSDictionary widgetDictionary = widget.getCOSObject();
-            if (widgetDictionary != null
-                    && widgetDictionary.getDictionaryObject(COSName.P) == null) {
-                Map<PDAnnotationWidget, Integer> fallback = buildWidgetPageFallbackMap(document);
-                Integer index = fallback.get(widget);
-                if (index != null) {
-                    return index;
-                }
+
+        // Method 0: Check the pre-built lookup map (fastest)
+        if (annotationPageMap != null) {
+            Integer idx = annotationPageMap.get(widget.getCOSObject());
+            if (idx != null) {
+                return idx;
            }
-        } catch (Exception e) {
-            log.debug("Widget page lookup via fallback map failed: {}", e.getMessage());
        }
+
        try {
            PDPage page = widget.getPage();
            if (page != null) {
+                // indexOf is O(N), still slower than map but better than scanning annotations
                int idx = document.getPages().indexOf(page);
                if (idx >= 0) {
                    return idx;
@@ -1267,14 +1764,36 @@ public class FormUtils {
            log.debug("Widget page lookup failed: {}", e.getMessage());
        }

+        // Method 1: Check the /P entry if it points to a page
+        try {
+            COSDictionary widgetDictionary = widget.getCOSObject();
+            if (widgetDictionary != null) {
+                COSBase base = widgetDictionary.getDictionaryObject(COSName.P);
+                COSDictionary pageDict = (base instanceof COSDictionary c) ? c : null;
+                if (pageDict != null) {
+                    for (int i = 0; i < document.getNumberOfPages(); i++) {
+                        if (document.getPage(i).getCOSObject() == pageDict) {
+                            return i;
+                        }
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.debug("Widget page lookup via /P entry failed: {}", e.getMessage());
+        }
+
+        // Method 2: Fallback search through all pages' annotations
        int pageCount = document.getNumberOfPages();
+        COSDictionary widgetDict = widget.getCOSObject();
        for (int i = 0; i < pageCount; i++) {
            try {
                PDPage candidate = document.getPage(i);
                List<PDAnnotation> annotations = candidate.getAnnotations();
-                for (PDAnnotation annotation : annotations) {
-                    if (annotation == widget) {
-                        return i;
+                if (annotations != null) {
+                    for (PDAnnotation annot : annotations) {
+                        if (annot != null && annot.getCOSObject() == widgetDict) {
+                            return i;
+                        }
                    }
                }
            } catch (IOException e) {
@@ -1317,7 +1836,7 @@ public class FormUtils {
            List<PDAnnotationWidget> widgets = field.getWidgets();
            if (widgets != null) {
                for (PDAnnotationWidget widget : widgets) {
-                    PDPage page = resolveWidgetPage(document, widget);
+                    PDPage page = resolveWidgetPage(document, widget, null);
                    if (page != null) {
                        page.getAnnotations().remove(widget);
                    }
@@ -1437,7 +1956,10 @@ public class FormUtils {
                rectangle.getHeight());
    }

-    private PDPage resolveWidgetPage(PDDocument document, PDAnnotationWidget widget) {
+    private PDPage resolveWidgetPage(
+            PDDocument document,
+            PDAnnotationWidget widget,
+            Map<COSDictionary, Integer> annotationPageMap) {
        if (widget == null) {
            return null;
        }
@@ -1445,7 +1967,7 @@ public class FormUtils {
        if (page != null) {
            return page;
        }
-        int pageIndex = determineWidgetPageIndex(document, widget);
+        int pageIndex = determineWidgetPageIndex(document, widget, annotationPageMap);
        if (pageIndex >= 0) {
            try {
                return document.getPage(pageIndex);
@@ -1456,11 +1978,21 @@ public class FormUtils {
        return null;
    }

-    private int determineWidgetPageIndex(PDDocument document, PDAnnotationWidget widget) {
+    private int determineWidgetPageIndex(
+            PDDocument document,
+            PDAnnotationWidget widget,
+            Map<COSDictionary, Integer> annotationPageMap) {
        if (document == null || widget == null) {
            return -1;
        }

+        if (annotationPageMap != null) {
+            Integer idx = annotationPageMap.get(widget.getCOSObject());
+            if (idx != null) {
+                return idx;
+            }
+        }
+
        PDPage directPage = widget.getPage();
        if (directPage != null) {
            int index = 0;
@@ -1488,6 +2020,33 @@ public class FormUtils {
        return -1;
    }

+    /**
+     * Build a map of annotation COS dictionaries to their respective page index. Scan once
+     * per-document to avoid O(N^2) lookups during field extraction.
+     */
+    public Map<COSDictionary, Integer> buildAnnotationPageMap(PDDocument document) {
+        if (document == null) {
+            return Collections.emptyMap();
+        }
+
+        Map<COSDictionary, Integer> map = new HashMap<>();
+        int pageCount = document.getNumberOfPages();
+        for (int i = 0; i < pageCount; i++) {
+            try {
+                PDPage page = document.getPage(i);
+                List<PDAnnotation> annotations = page.getAnnotations();
+                for (PDAnnotation annot : annotations) {
+                    if (annot != null) {
+                        map.putIfAbsent(annot.getCOSObject(), i);
+                    }
+                }
+            } catch (Exception e) {
+                log.debug("Failed to index annotations for page {}: {}", i, e.getMessage());
+            }
+        }
+        return map;
+    }
+
    private Map<PDAnnotationWidget, Integer> buildWidgetPageFallbackMap(PDDocument document) {
        if (document == null) {
            return Collections.emptyMap();
@@ -1760,4 +2319,46 @@ public class FormUtils {
            boolean multiSelect,
            String tooltip,
            int pageOrder) {}
+
+    /**
+     * Comparator for sorting form fields by page, then vertically (top-to-bottom), then
+     * horizontally (left-to-right) for fields on approximately the same line.
+     */
+    static final class FieldCoordinateComparator implements Comparator<FormFieldWithCoordinates> {
+
+        private static int firstWidgetPageIndex(FormFieldWithCoordinates f) {
+            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
+                    ? f.getWidgets().get(0).getPageIndex()
+                    : -1;
+        }
+
+        private static float firstWidgetY(FormFieldWithCoordinates f) {
+            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
+                    ? f.getWidgets().get(0).getY()
+                    : 0;
+        }
+
+        private static float firstWidgetX(FormFieldWithCoordinates f) {
+            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
+                    ? f.getWidgets().get(0).getX()
+                    : 0;
+        }
+
+        @Override
+        public int compare(FormFieldWithCoordinates a, FormFieldWithCoordinates b) {
+            int pageA = firstWidgetPageIndex(a);
+            int pageB = firstWidgetPageIndex(b);
+            int pageCompare = Integer.compare(pageA, pageB);
+            if (pageCompare != 0) return pageCompare;
+
+            float yA = firstWidgetY(a);
+            float yB = firstWidgetY(b);
+
+            // Fields on approximately the same line should be sorted left-to-right
+            if (Math.abs(yA - yB) < SAME_LINE_THRESHOLD_PT) {
+                return Float.compare(firstWidgetX(a), firstWidgetX(b));
+            }
+            return Float.compare(yA, yB);
+        }
+    }
 }
@@ -649,8 +649,10 @@ public class GeneralUtils {
    }

    public List<Integer> parsePageList(String[] pages, int totalPages, boolean oneBased) {
-        List<Integer> result = new ArrayList<>();
+        // Use LinkedHashSet to prevent duplicates from inflating size and triggering maxSize guard
+        Set<Integer> result = new LinkedHashSet<>();
        int offset = oneBased ? 1 : 0;
+        int maxSize = Math.max(1000, totalPages * 3);
        for (String page : pages) {
            if ("all".equalsIgnoreCase(page)) {

@@ -666,8 +668,12 @@ public class GeneralUtils {
            } else {
                result.addAll(handlePart(page, totalPages, offset));
            }
+            if (result.size() > maxSize) {
+                throw new IllegalArgumentException(
+                        "Page list exceeds maximum allowed size of " + maxSize);
+            }
        }
-        return result;
+        return new ArrayList<>(result);
    }

    /*
@@ -867,6 +873,36 @@ public class GeneralUtils {
        settingsYaml.saveOverride(settingsPath);
    }

+    /**
+     * Updates multiple settings in a single transaction. This ensures that nested settings (e.g.,
+     * oauth2.client.google.*) don't lose sibling values when partial updates are made.
+     *
+     * <p>Instead of multiple read-update-write cycles (which could cause race conditions), this
+     * method loads the YAML once, applies all updates, and saves once.
+     *
+     * @param settingsMap Map of dotted-notation keys to values to update
+     * @throws IOException if file read/write fails
+     */
+    public void updateSettingsTransactional(Map<String, Object> settingsMap) throws IOException {
+        if (settingsMap == null || settingsMap.isEmpty()) {
+            return;
+        }
+
+        Path settingsPath = Paths.get(InstallationPathConfig.getSettingsPath());
+        YamlHelper settingsYaml = new YamlHelper(settingsPath);
+
+        // Apply all updates to the same YamlHelper instance
+        for (Map.Entry<String, Object> entry : settingsMap.entrySet()) {
+            String key = entry.getKey();
+            Object value = entry.getValue();
+            String[] keyArray = key.split("\\.");
+            settingsYaml.updateValue(Arrays.asList(keyArray), value);
+        }
+
+        // Save only once after all updates are applied
+        settingsYaml.saveOverride(settingsPath);
+    }
+
    /*
     * Machine fingerprint generation with better error logging and fallbacks.
     *
@@ -10,6 +10,7 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
+import java.util.regex.Pattern;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;

@@ -33,6 +34,8 @@ import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
@Slf4j
 public class PDFToFile {

+    private static final Pattern PATTERN =
+            Pattern.compile("(!\\[.*?\\])\\((?!images/)([^/)][^)]*?)\\)");
    private final TempFileManager tempFileManager;
    private final RuntimePathConfig runtimePathConfig;

@@ -107,56 +110,65 @@ public class PDFToFile {
            File[] outputFiles =
                    Objects.requireNonNull(tempOutputDir.getPath().toFile().listFiles());
            List<File> markdownFiles = new ArrayList<>();
+            List<File> imageFiles = new ArrayList<>();

-            // Convert HTML files to Markdown
+            // Convert HTML files to Markdown and collect image files
            for (File outputFile : outputFiles) {
                if (outputFile.getName().endsWith(".html")) {
                    String html = Files.readString(outputFile.toPath());
                    String markdown = htmlToMarkdownConverter.convert(html);

+                    // Update image references to point to images/ folder
+                    markdown = updateImageReferences(markdown);
+
                    String mdFileName = outputFile.getName().replace(".html", ".md");
                    File mdFile = new File(tempOutputDir.getPath().toFile(), mdFileName);
                    Files.writeString(mdFile.toPath(), markdown);
                    markdownFiles.add(mdFile);
+                } else if (!outputFile.getName().endsWith(".md")) {
+                    // Collect non-HTML, non-MD files as images/assets
+                    imageFiles.add(outputFile);
                }
            }

-            // If there's only one markdown file, return it directly
-            if (markdownFiles.size() == 1) {
-                fileName = pdfBaseName + ".md";
-                fileBytes = Files.readAllBytes(markdownFiles.get(0).toPath());
-            } else {
-                // Multiple files - create a zip
-                fileName = pdfBaseName + "ToMarkdown.zip";
-                ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
+            // Always create a ZIP file
+            fileName = pdfBaseName + "ToMarkdown.zip";
+            ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();

-                try (ZipOutputStream zipOutputStream = new ZipOutputStream(byteArrayOutputStream)) {
-                    // Add markdown files
-                    for (File mdFile : markdownFiles) {
-                        ZipEntry mdEntry = new ZipEntry(mdFile.getName());
-                        zipOutputStream.putNextEntry(mdEntry);
-                        Files.copy(mdFile.toPath(), zipOutputStream);
-                        zipOutputStream.closeEntry();
-                    }
-
-                    // Add images and other assets
-                    for (File file : outputFiles) {
-                        if (!file.getName().endsWith(".html") && !file.getName().endsWith(".md")) {
-                            ZipEntry assetEntry = new ZipEntry(file.getName());
-                            zipOutputStream.putNextEntry(assetEntry);
-                            Files.copy(file.toPath(), zipOutputStream);
-                            zipOutputStream.closeEntry();
-                        }
-                    }
+            try (ZipOutputStream zipOutputStream = new ZipOutputStream(byteArrayOutputStream)) {
+                // Add markdown files to root of ZIP
+                for (File mdFile : markdownFiles) {
+                    ZipEntry mdEntry = new ZipEntry(mdFile.getName());
+                    zipOutputStream.putNextEntry(mdEntry);
+                    Files.copy(mdFile.toPath(), zipOutputStream);
+                    zipOutputStream.closeEntry();
                }

-                fileBytes = byteArrayOutputStream.toByteArray();
+                // Add images and other assets to images/ folder
+                for (File imageFile : imageFiles) {
+                    ZipEntry assetEntry = new ZipEntry("images/" + imageFile.getName());
+                    zipOutputStream.putNextEntry(assetEntry);
+                    Files.copy(imageFile.toPath(), zipOutputStream);
+                    zipOutputStream.closeEntry();
+                }
            }
+
+            fileBytes = byteArrayOutputStream.toByteArray();
        }
        return WebResponseUtils.bytesToWebResponse(
                fileBytes, fileName, MediaType.APPLICATION_OCTET_STREAM);
    }

+    /**
+     * Updates image references in markdown to point to the images/ folder. Matches patterns like
+     * ![alt](filename.png) and converts to ![alt](images/filename.png)
+     */
+    private String updateImageReferences(String markdown) {
+        // Match markdown image syntax: ![alt text](image.png)
+        // Only update if the path doesn't already start with images/
+        return PATTERN.matcher(markdown).replaceAll("$1(images/$2)");
+    }
+
    public ResponseEntity<byte[]> processPdfToHtml(MultipartFile inputFile)
            throws IOException, InterruptedException {
        if (!MediaType.APPLICATION_PDF_VALUE.equals(inputFile.getContentType())) {
@@ -1,8 +1,8 @@
 package stirling.software.common.util;

 import java.awt.image.BufferedImage;
-import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.nio.file.Files;
 import java.util.Locale;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;
@@ -22,8 +22,11 @@ import stirling.software.common.service.CustomPDFDocumentFactory;
@Slf4j
 public class PdfToCbzUtils {

-    public static byte[] convertPdfToCbz(
-            MultipartFile pdfFile, int dpi, CustomPDFDocumentFactory pdfDocumentFactory)
+    public static TempFile convertPdfToCbz(
+            MultipartFile pdfFile,
+            int dpi,
+            CustomPDFDocumentFactory pdfDocumentFactory,
+            TempFileManager tempFileManager)
            throws IOException {

        validatePdfFile(pdfFile);
@@ -33,7 +36,7 @@ public class PdfToCbzUtils {
                throw ExceptionUtils.createPdfNoPages();
            }

-            return createCbzFromPdf(document, dpi);
+            return createCbzFromPdf(document, dpi, tempFileManager);
        }
    }

@@ -53,46 +56,49 @@ public class PdfToCbzUtils {
        }
    }

-    private static byte[] createCbzFromPdf(PDDocument document, int dpi) throws IOException {
+    private static TempFile createCbzFromPdf(
+            PDDocument document, int dpi, TempFileManager tempFileManager) throws IOException {
        PDFRenderer pdfRenderer = new PDFRenderer(document);
        pdfRenderer.setSubsamplingAllowed(true); // Enable subsampling to reduce memory usage

-        try (ByteArrayOutputStream cbzOutputStream = new ByteArrayOutputStream();
-                ZipOutputStream zipOut = new ZipOutputStream(cbzOutputStream)) {
+        TempFile cbzTempFile = new TempFile(tempFileManager, ".cbz");
+        try {
+            try (ZipOutputStream zipOut =
+                    new ZipOutputStream(Files.newOutputStream(cbzTempFile.getPath()))) {

-            int totalPages = document.getNumberOfPages();
+                int totalPages = document.getNumberOfPages();

-            for (int pageIndex = 0; pageIndex < totalPages; pageIndex++) {
-                final int currentPage = pageIndex;
-                try {
-                    BufferedImage image =
-                            ExceptionUtils.handleOomRendering(
-                                    currentPage + 1,
-                                    dpi,
-                                    () ->
-                                            pdfRenderer.renderImageWithDPI(
-                                                    currentPage, dpi, ImageType.RGB));
+                for (int pageIndex = 0; pageIndex < totalPages; pageIndex++) {
+                    final int currentPage = pageIndex;
+                    try {
+                        BufferedImage image =
+                                ExceptionUtils.handleOomRendering(
+                                        currentPage + 1,
+                                        dpi,
+                                        () ->
+                                                pdfRenderer.renderImageWithDPI(
+                                                        currentPage, dpi, ImageType.RGB));

-                    String imageFilename =
-                            String.format(Locale.ROOT, "page_%03d.png", currentPage + 1);
-                    ZipEntry zipEntry = new ZipEntry(imageFilename);
-                    zipOut.putNextEntry(zipEntry);
+                        String imageFilename =
+                                String.format(Locale.ROOT, "page_%03d.png", currentPage + 1);
+                        zipOut.putNextEntry(new ZipEntry(imageFilename));
+                        ImageIO.write(image, "PNG", zipOut);
+                        zipOut.closeEntry();

-                    ImageIO.write(image, "PNG", zipOut);
-                    zipOut.closeEntry();
-
-                } catch (ExceptionUtils.OutOfMemoryDpiException e) {
-                    // Re-throw OOM exceptions without wrapping
-                    throw e;
-                } catch (IOException e) {
-                    // Wrap other IOExceptions with context
-                    throw ExceptionUtils.createFileProcessingException(
-                            "CBZ creation for page " + (currentPage + 1), e);
+                    } catch (ExceptionUtils.OutOfMemoryDpiException e) {
+                        // Re-throw OOM exceptions without wrapping
+                        throw e;
+                    } catch (IOException e) {
+                        // Wrap other IOExceptions with context
+                        throw ExceptionUtils.createFileProcessingException(
+                                "CBZ creation for page " + (currentPage + 1), e);
+                    }
                }
            }
-
-            zipOut.finish();
-            return cbzOutputStream.toByteArray();
+            return cbzTempFile;
+        } catch (Exception e) {
+            cbzTempFile.close();
+            throw e;
        }
    }

@@ -219,58 +219,31 @@ public class PdfUtils {
                    int maxWidth = 0;
                    int totalHeight = 0;

-                    BufferedImage pdfSizeImage = null;
-                    int pdfSizeImageIndex = -1;
-
-                    // Using a map to store the rendered dimensions of each page size
-                    // to avoid rendering the same page sizes multiple times
+                    // Using a map to store the calculated dimensions of each page size
                    HashMap<PdfRenderSettingsKey, PdfImageDimensionValue> pageSizes =
                            new HashMap<>();
                    for (int i = 0; i < pageCount; ++i) {
-                        final int pageIndex = i;
                        PDPage page = document.getPage(i);
-                        PDRectangle mediaBox = page.getMediaBox();
+                        PDRectangle cropBox = page.getCropBox();
                        int rotation = page.getRotation();
                        PdfRenderSettingsKey settings =
                                new PdfRenderSettingsKey(
-                                        mediaBox.getWidth(), mediaBox.getHeight(), rotation);
+                                        cropBox.getWidth(), cropBox.getHeight(), rotation);
                        PdfImageDimensionValue dimension = pageSizes.get(settings);
                        if (dimension == null) {
-                            // Render the image to get the dimensions
-                            try {
-                                // Validate dimensions before rendering
-                                ExceptionUtils.validateRenderingDimensions(
-                                        page, pageIndex + 1, DPI);
-
-                                pdfSizeImage =
-                                        ExceptionUtils.handleOomRendering(
-                                                pageIndex + 1,
-                                                DPI,
-                                                () ->
-                                                        pdfRenderer.renderImageWithDPI(
-                                                                pageIndex, DPI, colorType));
-                            } catch (IllegalArgumentException e) {
-                                if (e.getMessage() != null
-                                        && e.getMessage()
-                                                .contains("Maximum size of image exceeded")) {
-                                    throw ExceptionUtils.createIllegalArgumentException(
-                                            "error.pageTooBigExceedsArray",
-                                            "PDF page {0} is too large to render at {1} DPI. The"
-                                                    + " resulting image would exceed Java's maximum"
-                                                    + " array size. Please try a lower DPI value"
-                                                    + " (recommended: 150 or less).",
-                                            i + 1,
-                                            DPI);
-                                }
-                                throw e;
+                            float scale = DPI / 72f;
+                            int widthPx = (int) Math.max(Math.floor(cropBox.getWidth() * scale), 1);
+                            int heightPx =
+                                    (int) Math.max(Math.floor(cropBox.getHeight() * scale), 1);
+                            if (rotation == 90 || rotation == 270) {
+                                int tmp = widthPx;
+                                widthPx = heightPx;
+                                heightPx = tmp;
                            }
-                            pdfSizeImageIndex = i;
-                            dimension =
-                                    new PdfImageDimensionValue(
-                                            pdfSizeImage.getWidth(), pdfSizeImage.getHeight());
+                            dimension = new PdfImageDimensionValue(widthPx, heightPx);
                            pageSizes.put(settings, dimension);
-                            if (pdfSizeImage.getWidth() > maxWidth) {
-                                maxWidth = pdfSizeImage.getWidth();
+                            if (widthPx > maxWidth) {
+                                maxWidth = widthPx;
                            }
                        }
                        totalHeight += dimension.height();
@@ -284,40 +257,32 @@ public class PdfUtils {
                    int currentHeight = 0;
                    BufferedImage pageImage;

-                    // Check if the first image is the last rendered image
-                    boolean firstImageAlreadyRendered = pdfSizeImageIndex == 0;
-
                    for (int i = 0; i < pageCount; ++i) {
                        final int pageIndex = i;
-                        if (firstImageAlreadyRendered && i == 0) {
-                            pageImage = pdfSizeImage;
-                        } else {
-                            try {
-                                // Validate dimensions before rendering
-                                ExceptionUtils.validateRenderingDimensions(
-                                        document.getPage(pageIndex), pageIndex + 1, DPI);
+                        try {
+                            // Validate dimensions before rendering
+                            ExceptionUtils.validateRenderingDimensions(
+                                    document.getPage(pageIndex), pageIndex + 1, DPI);

-                                pageImage =
-                                        ExceptionUtils.handleOomRendering(
-                                                pageIndex + 1,
-                                                DPI,
-                                                () ->
-                                                        pdfRenderer.renderImageWithDPI(
-                                                                pageIndex, DPI, colorType));
-                            } catch (IllegalArgumentException e) {
-                                if (e.getMessage() != null
-                                        && e.getMessage()
-                                                .contains("Maximum size of image exceeded")) {
-                                    throw ExceptionUtils.createIllegalArgumentException(
-                                            "error.pageTooBigForDpi",
-                                            "PDF page {0} is too large to render at {1} DPI. Please"
-                                                    + " try a lower DPI value (recommended: 150 or"
-                                                    + " less).",
-                                            i + 1,
-                                            DPI);
-                                }
-                                throw e;
+                            pageImage =
+                                    ExceptionUtils.handleOomRendering(
+                                            pageIndex + 1,
+                                            DPI,
+                                            () ->
+                                                    pdfRenderer.renderImageWithDPI(
+                                                            pageIndex, DPI, colorType));
+                        } catch (IllegalArgumentException e) {
+                            if (e.getMessage() != null
+                                    && e.getMessage().contains("Maximum size of image exceeded")) {
+                                throw ExceptionUtils.createIllegalArgumentException(
+                                        "error.pageTooBigForDpi",
+                                        "PDF page {0} is too large to render at {1} DPI. Please"
+                                                + " try a lower DPI value (recommended: 150 or"
+                                                + " less).",
+                                        i + 1,
+                                        DPI);
                            }
+                            throw e;
                        }

                        // Calculate the x-coordinate to center the image
@@ -574,34 +539,39 @@ public class PdfUtils {
            boolean everyPage)
            throws IOException {

-        PDDocument document = pdfDocumentFactory.load(pdfBytes);
-
-        // Get the first page of the PDF
-        int pages = document.getNumberOfPages();
-        for (int i = 0; i < pages; i++) {
-            PDPage page = document.getPage(i);
-            try (PDPageContentStream contentStream =
-                    new PDPageContentStream(
-                            document, page, PDPageContentStream.AppendMode.APPEND, true, true)) {
-                // Create an image object from the image bytes
-                PDImageXObject image = PDImageXObject.createFromByteArray(document, imageBytes, "");
-                // Draw the image onto the page at the specified x and y coordinates
-                contentStream.drawImage(image, x, y);
-                log.info("Image successfully overlaid onto PDF");
-                if (!everyPage && i == 0) {
-                    break;
+        try (PDDocument document = pdfDocumentFactory.load(pdfBytes)) {
+            // Get the first page of the PDF
+            int pages = document.getNumberOfPages();
+            for (int i = 0; i < pages; i++) {
+                PDPage page = document.getPage(i);
+                try (PDPageContentStream contentStream =
+                        new PDPageContentStream(
+                                document,
+                                page,
+                                PDPageContentStream.AppendMode.APPEND,
+                                true,
+                                true)) {
+                    // Create an image object from the image bytes
+                    PDImageXObject image =
+                            PDImageXObject.createFromByteArray(document, imageBytes, "");
+                    // Draw the image onto the page at the specified x and y coordinates
+                    contentStream.drawImage(image, x, y);
+                    log.info("Image successfully overlaid onto PDF");
+                    if (!everyPage && i == 0) {
+                        break;
+                    }
+                } catch (IOException e) {
+                    // Log an error message if there is an issue overlaying the image onto the PDF
+                    log.error("Error overlaying image onto PDF", e);
+                    throw e;
                }
-            } catch (IOException e) {
-                // Log an error message if there is an issue overlaying the image onto the PDF
-                log.error("Error overlaying image onto PDF", e);
-                throw e;
            }
+            // Create a ByteArrayOutputStream to save the PDF to
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            document.save(baos);
+            log.info("PDF successfully saved to byte array");
+            return baos.toByteArray();
        }
-        // Create a ByteArrayOutputStream to save the PDF to
-        ByteArrayOutputStream baos = new ByteArrayOutputStream();
-        document.save(baos);
-        log.info("PDF successfully saved to byte array");
-        return baos.toByteArray();
    }

    public boolean containsTextInFile(PDDocument pdfDocument, String text, String pagesToCheck)
@@ -226,50 +226,54 @@ public class ProcessExecutor {
            List<String> outputLines = new ArrayList<>();

            Thread errorReaderThread =
-                    new Thread(
-                            () -> {
-                                try (BufferedReader errorReader =
-                                        new BufferedReader(
-                                                new InputStreamReader(
-                                                        process.getErrorStream(),
-                                                        StandardCharsets.UTF_8))) {
-                                    String line;
-                                    while ((line =
-                                                    BoundedLineReader.readLine(
-                                                            errorReader, 5_000_000))
-                                            != null) {
-                                        errorLines.add(line);
-                                        if (liveUpdates) log.info(line);
-                                    }
-                                } catch (InterruptedIOException e) {
-                                    log.warn("Error reader thread was interrupted due to timeout.");
-                                } catch (IOException e) {
-                                    log.error("exception", e);
-                                }
-                            });
+                    Thread.ofVirtual()
+                            .unstarted(
+                                    () -> {
+                                        try (BufferedReader errorReader =
+                                                new BufferedReader(
+                                                        new InputStreamReader(
+                                                                process.getErrorStream(),
+                                                                StandardCharsets.UTF_8))) {
+                                            String line;
+                                            while ((line =
+                                                            BoundedLineReader.readLine(
+                                                                    errorReader, 5_000_000))
+                                                    != null) {
+                                                errorLines.add(line);
+                                                if (liveUpdates) log.info(line);
+                                            }
+                                        } catch (InterruptedIOException e) {
+                                            log.warn(
+                                                    "Error reader thread was interrupted due to timeout.");
+                                        } catch (IOException e) {
+                                            log.error("exception", e);
+                                        }
+                                    });

            Thread outputReaderThread =
-                    new Thread(
-                            () -> {
-                                try (BufferedReader outputReader =
-                                        new BufferedReader(
-                                                new InputStreamReader(
-                                                        process.getInputStream(),
-                                                        StandardCharsets.UTF_8))) {
-                                    String line;
-                                    while ((line =
-                                                    BoundedLineReader.readLine(
-                                                            outputReader, 5_000_000))
-                                            != null) {
-                                        outputLines.add(line);
-                                        if (liveUpdates) log.info(line);
-                                    }
-                                } catch (InterruptedIOException e) {
-                                    log.warn("Error reader thread was interrupted due to timeout.");
-                                } catch (IOException e) {
-                                    log.error("exception", e);
-                                }
-                            });
+                    Thread.ofVirtual()
+                            .unstarted(
+                                    () -> {
+                                        try (BufferedReader outputReader =
+                                                new BufferedReader(
+                                                        new InputStreamReader(
+                                                                process.getInputStream(),
+                                                                StandardCharsets.UTF_8))) {
+                                            String line;
+                                            while ((line =
+                                                            BoundedLineReader.readLine(
+                                                                    outputReader, 5_000_000))
+                                                    != null) {
+                                                outputLines.add(line);
+                                                if (liveUpdates) log.info(line);
+                                            }
+                                        } catch (InterruptedIOException e) {
+                                            log.warn(
+                                                    "Error reader thread was interrupted due to timeout.");
+                                        } catch (IOException e) {
+                                            log.error("exception", e);
+                                        }
+                                    });

            errorReaderThread.start();
            outputReaderThread.start();
@@ -370,7 +374,7 @@ public class ProcessExecutor {
            }
            // Match common unoconvert variants (but NOT soffice)
            String lowerBasename = basename.toLowerCase(java.util.Locale.ROOT);
-            if (lowerBasename.contains("unoconvert") || lowerBasename.equals("unoconv")) {
+            if (lowerBasename.contains("unoconvert") || "unoconv".equals(lowerBasename)) {
                return true;
            }
        }
@@ -86,7 +86,6 @@ public class RequestUriUtils {
        // Blocklist of backend/non-frontend paths that should still go through filters
        String[] backendOnlyPrefixes = {
            "/register",
-            "/invite",
            "/pipeline",
            "/pdfjs",
            "/pdfjs-legacy",
@@ -181,7 +180,9 @@ public class RequestUriUtils {
                || trimmedUri.startsWith("/readiness")
                || trimmedUri.startsWith(
                        "/api/v1/mobile-scanner/") // Mobile scanner endpoints (no auth)
-                || trimmedUri.startsWith("/v1/api-docs");
+                || trimmedUri.startsWith("/v1/api-docs")
+                // Workflow participant endpoints — access controlled by share tokens, not login
+                || trimmedUri.startsWith("/api/v1/workflow/participant/");
    }

    private static String stripContextPath(String contextPath, String requestURI) {
@@ -47,6 +47,7 @@ public class SvgSanitizer {
    private static final Pattern DATA_SCRIPT_PATTERN =
            Pattern.compile(
                    "^\\s*data\\s*:[^,]*(?:script|javascript|vbscript)", Pattern.CASE_INSENSITIVE);
+    private static final Pattern NULL_BYTE_PATTERN = Pattern.compile("\u0000");
    private final SsrfProtectionService ssrfProtectionService;
    private final ApplicationProperties applicationProperties;

@@ -85,7 +86,7 @@ public class SvgSanitizer {
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();

        factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
-
+        factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
        factory.setFeature("http://xml.org/sax/features/external-general-entities", false);
        factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
        factory.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
@@ -210,7 +211,7 @@ public class SvgSanitizer {

        String result = url.trim();

-        result = result.replaceAll("\u0000", "");
+        result = NULL_BYTE_PATTERN.matcher(result).replaceAll("");

        for (int i = 0; i < 3; i++) {
            try {
@@ -191,7 +191,7 @@ public class YamlHelper {
            mappingNode.getValue().clear();
            mappingNode.getValue().addAll(updatedTuples);
        }
-        setNewNode(node);
+        updatedRootNode = node;

        return updated;
    }
@@ -19,7 +19,7 @@ public abstract class ReplaceAndInvertColorStrategy extends PDFFile {

    public ReplaceAndInvertColorStrategy(MultipartFile file, ReplaceAndInvert replaceAndInvert) {
        setFileInput(file);
-        setReplaceAndInvert(replaceAndInvert);
+        this.replaceAndInvert = replaceAndInvert;
    }

    public abstract InputStreamResource replace() throws IOException;
@@ -4,18 +4,23 @@ import java.beans.PropertyEditorSupport;
 import java.util.ArrayList;
 import java.util.List;

-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.DeserializationFeature;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.api.security.RedactionArea;

+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.DeserializationFeature;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
+
@Slf4j
 public class StringToArrayListPropertyEditor extends PropertyEditorSupport {

-    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final ObjectMapper objectMapper =
+            JsonMapper.builder()
+                    .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+                    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+                    .build();

    @Override
    public void setAsText(String text) throws IllegalArgumentException {
@@ -24,7 +29,6 @@ public class StringToArrayListPropertyEditor extends PropertyEditorSupport {
            return;
        }
        try {
-            objectMapper.configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true);
            TypeReference<ArrayList<RedactionArea>> typeRef = new TypeReference<>() {};
            List<RedactionArea> list = objectMapper.readValue(text, typeRef);
            setValue(list);
@@ -4,12 +4,13 @@ import java.beans.PropertyEditorSupport;
 import java.util.HashMap;
 import java.util.Map;

-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;

 public class StringToMapPropertyEditor extends PropertyEditorSupport {

-    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final ObjectMapper objectMapper = JsonMapper.builder().build();

    @Override
    public void setAsText(String text) throws IllegalArgumentException {
@@ -12,11 +12,12 @@ class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
    public StrategyType lastStrategyUsed;

    public SpyPDFDocumentFactory(PdfMetadataService service) {
-        super(service);
+        super(service); // TempFileManager falls back to Files.createTempFile in tests
    }

    @Override
-    public StreamCacheCreateFunction getStreamCacheFunction(long contentSize) {
+    protected StreamCacheCreateFunction getStreamCacheFunction(
+            long contentSize, MemorySnapshot mem) {
        StrategyType type;
        if (contentSize < 10 * 1024 * 1024) {
            type = StrategyType.MEMORY_ONLY;
@@ -26,6 +27,6 @@ class SpyPDFDocumentFactory extends CustomPDFDocumentFactory {
            type = StrategyType.TEMP_FILE;
        }
        this.lastStrategyUsed = type;
-        return super.getStreamCacheFunction(contentSize); // delegate to real behavior
+        return super.getStreamCacheFunction(contentSize, mem);
    }
 }
@@ -0,0 +1,56 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import java.util.List;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.ApplicationArguments;
+
+class AppArgsCaptureTest {
+
+    private AppArgsCapture capture;
+
+    @BeforeEach
+    void setUp() {
+        capture = new AppArgsCapture();
+        AppArgsCapture.APP_ARGS.set(List.of());
+    }
+
+    @Test
+    void run_withArgs_capturesArgs() {
+        ApplicationArguments args = mock(ApplicationArguments.class);
+        when(args.getSourceArgs()).thenReturn(new String[] {"--server.port=8080", "--debug"});
+        capture.run(args);
+        assertEquals(List.of("--server.port=8080", "--debug"), AppArgsCapture.APP_ARGS.get());
+    }
+
+    @Test
+    void run_withNoArgs_capturesEmptyList() {
+        ApplicationArguments args = mock(ApplicationArguments.class);
+        when(args.getSourceArgs()).thenReturn(new String[] {});
+        capture.run(args);
+        assertEquals(List.of(), AppArgsCapture.APP_ARGS.get());
+    }
+
+    @Test
+    void run_calledTwice_overwritesPreviousArgs() {
+        ApplicationArguments args1 = mock(ApplicationArguments.class);
+        when(args1.getSourceArgs()).thenReturn(new String[] {"--first"});
+        capture.run(args1);
+        assertEquals(List.of("--first"), AppArgsCapture.APP_ARGS.get());
+
+        ApplicationArguments args2 = mock(ApplicationArguments.class);
+        when(args2.getSourceArgs()).thenReturn(new String[] {"--second", "--third"});
+        capture.run(args2);
+        assertEquals(List.of("--second", "--third"), AppArgsCapture.APP_ARGS.get());
+    }
+
+    @Test
+    void appArgs_defaultValue_isEmptyList() {
+        // After setUp resets it
+        assertTrue(AppArgsCapture.APP_ARGS.get().isEmpty());
+    }
+}
@@ -0,0 +1,108 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.NoSuchBeanDefinitionException;
+import org.springframework.context.ApplicationContext;
+
+class ApplicationContextProviderTest {
+
+    private ApplicationContextProvider provider;
+
+    @BeforeEach
+    void setUp() {
+        provider = new ApplicationContextProvider();
+        // Reset to null state
+        provider.setApplicationContext(null);
+    }
+
+    @AfterEach
+    void tearDown() {
+        // Clean up static state
+        provider.setApplicationContext(null);
+    }
+
+    @Test
+    void getBean_byClass_whenNoContext_returnsNull() {
+        provider.setApplicationContext(null);
+        assertNull(ApplicationContextProvider.getBean(String.class));
+    }
+
+    @Test
+    void getBean_byClass_whenBeanExists_returnsBean() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean(String.class)).thenReturn("hello");
+        provider.setApplicationContext(ctx);
+        assertEquals("hello", ApplicationContextProvider.getBean(String.class));
+    }
+
+    @Test
+    void getBean_byClass_whenBeanNotFound_returnsNull() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean(String.class)).thenThrow(new NoSuchBeanDefinitionException(""));
+        provider.setApplicationContext(ctx);
+        assertNull(ApplicationContextProvider.getBean(String.class));
+    }
+
+    @Test
+    void getBean_byNameAndClass_whenNoContext_returnsNull() {
+        provider.setApplicationContext(null);
+        assertNull(ApplicationContextProvider.getBean("myBean", String.class));
+    }
+
+    @Test
+    void getBean_byNameAndClass_whenBeanExists_returnsBean() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean("myBean", String.class)).thenReturn("world");
+        provider.setApplicationContext(ctx);
+        assertEquals("world", ApplicationContextProvider.getBean("myBean", String.class));
+    }
+
+    @Test
+    void getBean_byNameAndClass_whenBeanNotFound_returnsNull() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean("missing", String.class)).thenThrow(new NoSuchBeanDefinitionException(""));
+        provider.setApplicationContext(ctx);
+        assertNull(ApplicationContextProvider.getBean("missing", String.class));
+    }
+
+    @Test
+    void containsBean_whenNoContext_returnsFalse() {
+        provider.setApplicationContext(null);
+        assertFalse(ApplicationContextProvider.containsBean(String.class));
+    }
+
+    @Test
+    void containsBean_whenBeanExists_returnsTrue() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean(String.class)).thenReturn("exists");
+        provider.setApplicationContext(ctx);
+        assertTrue(ApplicationContextProvider.containsBean(String.class));
+    }
+
+    @Test
+    void containsBean_whenBeanNotFound_returnsFalse() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean(Integer.class)).thenThrow(new NoSuchBeanDefinitionException(""));
+        provider.setApplicationContext(ctx);
+        assertFalse(ApplicationContextProvider.containsBean(Integer.class));
+    }
+
+    @Test
+    void setApplicationContext_updatesStaticContext() {
+        ApplicationContext ctx = mock(ApplicationContext.class);
+        when(ctx.getBean(String.class)).thenReturn("test");
+        provider.setApplicationContext(ctx);
+        assertEquals("test", ApplicationContextProvider.getBean(String.class));
+
+        // Now set a different context
+        ApplicationContext ctx2 = mock(ApplicationContext.class);
+        when(ctx2.getBean(String.class)).thenReturn("updated");
+        provider.setApplicationContext(ctx2);
+        assertEquals("updated", ApplicationContextProvider.getBean(String.class));
+    }
+}
@@ -0,0 +1,70 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.apache.pdfbox.cos.COSDictionary;
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentCatalog;
+import org.apache.pdfbox.pdmodel.PageMode;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class AttachmentUtilsTest {
+
+    @Test
+    @DisplayName("should set page mode on catalog")
+    void setsPageMode() {
+        try (PDDocument document = new PDDocument()) {
+            AttachmentUtils.setCatalogViewerPreferences(document, PageMode.USE_ATTACHMENTS);
+
+            PDDocumentCatalog catalog = document.getDocumentCatalog();
+            assertEquals(PageMode.USE_ATTACHMENTS, catalog.getPageMode());
+        } catch (Exception e) {
+            fail("Should not throw: " + e.getMessage());
+        }
+    }
+
+    @Test
+    @DisplayName("should create viewer preferences dictionary if absent")
+    void createsViewerPreferences() {
+        try (PDDocument document = new PDDocument()) {
+            AttachmentUtils.setCatalogViewerPreferences(document, PageMode.USE_ATTACHMENTS);
+
+            COSDictionary catalogDict = document.getDocumentCatalog().getCOSObject();
+            COSDictionary viewerPrefs =
+                    (COSDictionary) catalogDict.getDictionaryObject(COSName.VIEWER_PREFERENCES);
+            assertNotNull(viewerPrefs);
+        } catch (Exception e) {
+            fail("Should not throw: " + e.getMessage());
+        }
+    }
+
+    @Test
+    @DisplayName("should set DisplayDocTitle to true in viewer preferences")
+    void setsDisplayDocTitle() {
+        try (PDDocument document = new PDDocument()) {
+            AttachmentUtils.setCatalogViewerPreferences(document, PageMode.USE_ATTACHMENTS);
+
+            COSDictionary catalogDict = document.getDocumentCatalog().getCOSObject();
+            COSDictionary viewerPrefs =
+                    (COSDictionary) catalogDict.getDictionaryObject(COSName.VIEWER_PREFERENCES);
+            assertTrue(viewerPrefs.getBoolean(COSName.getPDFName("DisplayDocTitle"), false));
+        } catch (Exception e) {
+            fail("Should not throw: " + e.getMessage());
+        }
+    }
+
+    @Test
+    @DisplayName("should not throw when catalog returns null from mocked document")
+    void handlesNullCatalogGracefully() {
+        PDDocument document = mock(PDDocument.class);
+        when(document.getDocumentCatalog()).thenReturn(null);
+
+        assertDoesNotThrow(
+                () ->
+                        AttachmentUtils.setCatalogViewerPreferences(
+                                document, PageMode.USE_ATTACHMENTS));
+    }
+}
@@ -0,0 +1,98 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.web.multipart.MultipartFile;
+
+class CbrUtilsTest {
+
+    // --- isCbrFile tests ---
+
+    @Test
+    void isCbrFile_withCbrExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbr");
+        assertTrue(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withRarExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("archive.rar");
+        assertTrue(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withUpperCaseExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.CBR");
+        assertTrue(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withPdfExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("document.pdf");
+        assertFalse(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withNullFilename_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn(null);
+        assertFalse(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withCbzExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbz");
+        assertFalse(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withNoExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("noextension");
+        assertFalse(CbrUtils.isCbrFile(file));
+    }
+
+    @Test
+    void isCbrFile_withMixedCaseRar_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("file.RaR");
+        assertTrue(CbrUtils.isCbrFile(file));
+    }
+
+    // --- convertCbrToPdf validation tests ---
+
+    @Test
+    void convertCbrToPdf_withNullFile_throwsException() {
+        assertThrows(Exception.class, () -> CbrUtils.convertCbrToPdf(null, null, null));
+    }
+
+    @Test
+    void convertCbrToPdf_withEmptyFile_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(true);
+        assertThrows(Exception.class, () -> CbrUtils.convertCbrToPdf(file, null, null));
+    }
+
+    @Test
+    void convertCbrToPdf_withNullFilename_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(false);
+        when(file.getOriginalFilename()).thenReturn(null);
+        assertThrows(Exception.class, () -> CbrUtils.convertCbrToPdf(file, null, null));
+    }
+
+    @Test
+    void convertCbrToPdf_withWrongExtension_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(false);
+        when(file.getOriginalFilename()).thenReturn("file.pdf");
+        assertThrows(Exception.class, () -> CbrUtils.convertCbrToPdf(file, null, null));
+    }
+}
@@ -0,0 +1,142 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.web.multipart.MultipartFile;
+
+class CbzUtilsTest {
+
+    // --- isCbzFile tests ---
+
+    @Test
+    void isCbzFile_withCbzExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbz");
+        assertTrue(CbzUtils.isCbzFile(file));
+    }
+
+    @Test
+    void isCbzFile_withZipExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("archive.zip");
+        assertTrue(CbzUtils.isCbzFile(file));
+    }
+
+    @Test
+    void isCbzFile_withUpperCaseExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.CBZ");
+        assertTrue(CbzUtils.isCbzFile(file));
+    }
+
+    @Test
+    void isCbzFile_withPdfExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("document.pdf");
+        assertFalse(CbzUtils.isCbzFile(file));
+    }
+
+    @Test
+    void isCbzFile_withNullFilename_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn(null);
+        assertFalse(CbzUtils.isCbzFile(file));
+    }
+
+    @Test
+    void isCbzFile_withCbrExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbr");
+        assertFalse(CbzUtils.isCbzFile(file));
+    }
+
+    // --- isComicBookFile tests ---
+
+    @Test
+    void isComicBookFile_withCbzExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbz");
+        assertTrue(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withZipExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("archive.zip");
+        assertTrue(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withCbrExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.cbr");
+        assertTrue(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withRarExtension_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("archive.rar");
+        assertTrue(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withPdfExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("document.pdf");
+        assertFalse(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withNullFilename_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn(null);
+        assertFalse(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withUpperCaseCBR_returnsTrue() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("comic.CBR");
+        assertTrue(CbzUtils.isComicBookFile(file));
+    }
+
+    @Test
+    void isComicBookFile_withNoExtension_returnsFalse() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("noextension");
+        assertFalse(CbzUtils.isComicBookFile(file));
+    }
+
+    // --- convertCbzToPdf validation tests ---
+
+    @Test
+    void convertCbzToPdf_withNullFile_throwsException() {
+        assertThrows(Exception.class, () -> CbzUtils.convertCbzToPdf(null, null, null, false));
+    }
+
+    @Test
+    void convertCbzToPdf_withEmptyFile_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(true);
+        assertThrows(Exception.class, () -> CbzUtils.convertCbzToPdf(file, null, null, false));
+    }
+
+    @Test
+    void convertCbzToPdf_withNullFilename_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(false);
+        when(file.getOriginalFilename()).thenReturn(null);
+        assertThrows(Exception.class, () -> CbzUtils.convertCbzToPdf(file, null, null, false));
+    }
+
+    @Test
+    void convertCbzToPdf_withWrongExtension_throwsException() {
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.isEmpty()).thenReturn(false);
+        when(file.getOriginalFilename()).thenReturn("file.pdf");
+        assertThrows(Exception.class, () -> CbzUtils.convertCbzToPdf(file, null, null, false));
+    }
+}
@@ -0,0 +1,210 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class ChecksumUtilsAdditionalTest {
+
+    private static final byte[] HELLO = "hello".getBytes(StandardCharsets.UTF_8);
+
+    @TempDir Path tempDir;
+
+    private Path writeFile(byte[] data) throws IOException {
+        Path file = tempDir.resolve("testfile.bin");
+        Files.write(file, data);
+        return file;
+    }
+
+    // --- checksum(Path, String) ---
+
+    @Test
+    void testChecksumPath_sha256() throws IOException {
+        Path file = writeFile(HELLO);
+        String hex = ChecksumUtils.checksum(file, "SHA-256");
+        assertEquals("2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", hex);
+    }
+
+    @Test
+    void testChecksumPath_md5() throws IOException {
+        Path file = writeFile(HELLO);
+        String hex = ChecksumUtils.checksum(file, "MD5");
+        assertEquals("5d41402abc4b2a76b9719d911017c592", hex);
+    }
+
+    @Test
+    void testChecksumPath_crc32() throws IOException {
+        Path file = writeFile(HELLO);
+        String hex = ChecksumUtils.checksum(file, "CRC32");
+        assertEquals("3610a686", hex);
+    }
+
+    // --- checksum(InputStream, String) ---
+
+    @Test
+    void testChecksumStream_adler32() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            String hex = ChecksumUtils.checksum(is, "ADLER32");
+            assertNotNull(hex);
+            assertEquals(8, hex.length());
+        }
+    }
+
+    @Test
+    void testChecksumStream_sha1() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            String hex = ChecksumUtils.checksum(is, "SHA-1");
+            assertEquals("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d", hex);
+        }
+    }
+
+    @Test
+    void testChecksumStream_unsupportedAlgorithm() {
+        assertThrows(
+                IllegalStateException.class,
+                () -> {
+                    try (InputStream is = new ByteArrayInputStream(HELLO)) {
+                        ChecksumUtils.checksum(is, "FAKE-ALGO");
+                    }
+                });
+    }
+
+    // --- checksumBase64(Path, String) ---
+
+    @Test
+    void testChecksumBase64Path_md5() throws IOException {
+        Path file = writeFile(HELLO);
+        String b64 = ChecksumUtils.checksumBase64(file, "MD5");
+        assertEquals("XUFAKrxLKna5cZ2REBfFkg==", b64);
+    }
+
+    @Test
+    void testChecksumBase64Path_crc32() throws IOException {
+        Path file = writeFile(HELLO);
+        String b64 = ChecksumUtils.checksumBase64(file, "CRC32");
+        assertEquals("NhCmhg==", b64);
+    }
+
+    // --- checksumBase64(InputStream, String) ---
+
+    @Test
+    void testChecksumBase64Stream_adler32() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            String b64 = ChecksumUtils.checksumBase64(is, "ADLER32");
+            assertNotNull(b64);
+            assertFalse(b64.isEmpty());
+        }
+    }
+
+    @Test
+    void testChecksumBase64Stream_sha256() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            String b64 = ChecksumUtils.checksumBase64(is, "SHA-256");
+            assertNotNull(b64);
+            assertFalse(b64.isEmpty());
+        }
+    }
+
+    // --- checksums(Path, String...) ---
+
+    @Test
+    void testChecksumsPath_multipleAlgorithms() throws IOException {
+        Path file = writeFile(HELLO);
+        Map<String, String> results = ChecksumUtils.checksums(file, "MD5", "SHA-256", "CRC32");
+        assertEquals(3, results.size());
+        assertEquals("5d41402abc4b2a76b9719d911017c592", results.get("MD5"));
+        assertEquals(
+                "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+                results.get("SHA-256"));
+        assertEquals("3610a686", results.get("CRC32"));
+    }
+
+    @Test
+    void testChecksumsPath_preservesOrder() throws IOException {
+        Path file = writeFile(HELLO);
+        // Digests are output first, then Checksums (CRC32/ADLER32), per implementation
+        Map<String, String> results = ChecksumUtils.checksums(file, "MD5", "SHA-1");
+        String[] keys = results.keySet().toArray(new String[0]);
+        assertEquals("MD5", keys[0]);
+        assertEquals("SHA-1", keys[1]);
+    }
+
+    @Test
+    void testChecksumsStream_unsupportedAlgorithm() {
+        assertThrows(
+                IllegalStateException.class,
+                () -> {
+                    try (InputStream is = new ByteArrayInputStream(HELLO)) {
+                        ChecksumUtils.checksums(is, "BOGUS");
+                    }
+                });
+    }
+
+    // --- matches(Path, String, String) ---
+
+    @Test
+    void testMatchesPath_correctHash() throws IOException {
+        Path file = writeFile(HELLO);
+        assertTrue(ChecksumUtils.matches(file, "MD5", "5d41402abc4b2a76b9719d911017c592"));
+    }
+
+    @Test
+    void testMatchesPath_wrongHash() throws IOException {
+        Path file = writeFile(HELLO);
+        assertFalse(ChecksumUtils.matches(file, "MD5", "0000000000000000000000000000000000"));
+    }
+
+    @Test
+    void testMatchesPath_caseInsensitive() throws IOException {
+        Path file = writeFile(HELLO);
+        assertTrue(ChecksumUtils.matches(file, "MD5", "5D41402ABC4B2A76B9719D911017C592"));
+    }
+
+    // --- matches(InputStream, String, String) ---
+
+    @Test
+    void testMatchesStream_correct() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            assertTrue(
+                    ChecksumUtils.matches(is, "SHA-1", "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"));
+        }
+    }
+
+    @Test
+    void testMatchesStream_wrong() throws IOException {
+        try (InputStream is = new ByteArrayInputStream(HELLO)) {
+            assertFalse(
+                    ChecksumUtils.matches(is, "SHA-1", "0000000000000000000000000000000000000000"));
+        }
+    }
+
+    // --- empty input ---
+
+    @Test
+    void testChecksumEmptyInput() throws IOException {
+        byte[] empty = new byte[0];
+        try (InputStream is = new ByteArrayInputStream(empty)) {
+            String hex = ChecksumUtils.checksum(is, "MD5");
+            // MD5 of empty input is d41d8cd98f00b204e9800998ecf8427e
+            assertEquals("d41d8cd98f00b204e9800998ecf8427e", hex);
+        }
+    }
+
+    @Test
+    void testChecksumCrc32EmptyInput() throws IOException {
+        byte[] empty = new byte[0];
+        try (InputStream is = new ByteArrayInputStream(empty)) {
+            String hex = ChecksumUtils.checksum(is, "CRC32");
+            assertEquals("00000000", hex);
+        }
+    }
+}
@@ -0,0 +1,93 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+class EmlParserTest {
+
+    @Nested
+    @DisplayName("safeMimeDecode")
+    class SafeMimeDecodeTests {
+
+        @Test
+        @DisplayName("should return empty string for null input")
+        void nullInput() {
+            assertEquals("", EmlParser.safeMimeDecode(null));
+        }
+
+        @Test
+        @DisplayName("should return empty string for empty input")
+        void emptyInput() {
+            assertEquals("", EmlParser.safeMimeDecode(""));
+        }
+
+        @Test
+        @DisplayName("should return empty string for blank input")
+        void blankInput() {
+            assertEquals("", EmlParser.safeMimeDecode("   "));
+        }
+
+        @Test
+        @DisplayName("should return plain text as-is")
+        void plainText() {
+            assertEquals("Hello World", EmlParser.safeMimeDecode("Hello World"));
+        }
+
+        @Test
+        @DisplayName("should trim surrounding whitespace")
+        void trimWhitespace() {
+            assertEquals("Hello", EmlParser.safeMimeDecode("  Hello  "));
+        }
+
+        @Test
+        @DisplayName("should decode base64 MIME encoded word")
+        void decodeBase64MimeWord() {
+            // =?UTF-8?B?SGVsbG8=?= is Base64 for "Hello"
+            assertEquals("Hello", EmlParser.safeMimeDecode("=?UTF-8?B?SGVsbG8=?="));
+        }
+
+        @Test
+        @DisplayName("should decode quoted-printable MIME encoded word")
+        void decodeQpMimeWord() {
+            // =?UTF-8?Q?Hello_World?= where _ means space in Q encoding
+            assertEquals("Hello World", EmlParser.safeMimeDecode("=?UTF-8?Q?Hello_World?="));
+        }
+
+        @Test
+        @DisplayName("should handle mixed text and encoded words")
+        void mixedTextAndEncoded() {
+            String input = "Re: =?UTF-8?B?SGVsbG8=?= test";
+            String result = EmlParser.safeMimeDecode(input);
+            assertEquals("Re: Hello test", result);
+        }
+    }
+
+    @Nested
+    @DisplayName("extractEmailContent")
+    class ExtractEmailContentTests {
+
+        @Test
+        @DisplayName("should throw on null input")
+        void nullInput() {
+            assertThrows(Exception.class, () -> EmlParser.extractEmailContent(null, null, null));
+        }
+
+        @Test
+        @DisplayName("should throw on empty input")
+        void emptyInput() {
+            assertThrows(
+                    Exception.class, () -> EmlParser.extractEmailContent(new byte[0], null, null));
+        }
+
+        @Test
+        @DisplayName("should throw on invalid content that is not EML or MSG")
+        void invalidContent() {
+            byte[] randomBytes = "This is not an email file at all.".getBytes();
+            assertThrows(
+                    Exception.class, () -> EmlParser.extractEmailContent(randomBytes, null, null));
+        }
+    }
+}
@@ -0,0 +1,293 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+class EmlProcessingUtilsTest {
+
+    @Nested
+    @DisplayName("validateEmlInput")
+    class ValidateEmlInputTests {
+
+        @Test
+        @DisplayName("should throw on null input")
+        void nullInput() {
+            assertThrows(Exception.class, () -> EmlProcessingUtils.validateEmlInput(null));
+        }
+
+        @Test
+        @DisplayName("should throw on empty input")
+        void emptyInput() {
+            assertThrows(Exception.class, () -> EmlProcessingUtils.validateEmlInput(new byte[0]));
+        }
+
+        @Test
+        @DisplayName("should throw on invalid format with insufficient headers")
+        void invalidFormat() {
+            byte[] data = "Hello, this is just random text without email headers.".getBytes();
+            assertThrows(Exception.class, () -> EmlProcessingUtils.validateEmlInput(data));
+        }
+
+        @Test
+        @DisplayName("should accept valid EML with multiple headers")
+        void validEml() {
+            String emlContent =
+                    "From: sender@example.com\r\n"
+                            + "To: recipient@example.com\r\n"
+                            + "Subject: Test\r\n"
+                            + "Date: Mon, 1 Jan 2024 00:00:00 +0000\r\n"
+                            + "\r\n"
+                            + "Body text";
+            assertDoesNotThrow(() -> EmlProcessingUtils.validateEmlInput(emlContent.getBytes()));
+        }
+    }
+
+    @Nested
+    @DisplayName("isMsgFile")
+    class IsMsgFileTests {
+
+        @Test
+        @DisplayName("should return false for null")
+        void nullInput() {
+            assertFalse(EmlProcessingUtils.isMsgFile(null));
+        }
+
+        @Test
+        @DisplayName("should return false for short bytes")
+        void shortBytes() {
+            assertFalse(EmlProcessingUtils.isMsgFile(new byte[] {0x01, 0x02}));
+        }
+
+        @Test
+        @DisplayName("should return true for MSG magic bytes")
+        void msgMagicBytes() {
+            byte[] magic = {
+                (byte) 0xD0,
+                (byte) 0xCF,
+                (byte) 0x11,
+                (byte) 0xE0,
+                (byte) 0xA1,
+                (byte) 0xB1,
+                (byte) 0x1A,
+                (byte) 0xE1,
+                0x00,
+                0x00
+            };
+            assertTrue(EmlProcessingUtils.isMsgFile(magic));
+        }
+
+        @Test
+        @DisplayName("should return false for non-MSG bytes")
+        void nonMsgBytes() {
+            byte[] data = new byte[] {0x50, 0x4B, 0x03, 0x04, 0x00, 0x00, 0x00, 0x00};
+            assertFalse(EmlProcessingUtils.isMsgFile(data));
+        }
+    }
+
+    @Nested
+    @DisplayName("escapeHtml")
+    class EscapeHtmlTests {
+
+        @Test
+        @DisplayName("should return empty string for null")
+        void nullInput() {
+            assertEquals("", EmlProcessingUtils.escapeHtml(null));
+        }
+
+        @Test
+        @DisplayName("should escape all HTML special characters")
+        void escapeSpecialChars() {
+            String result = EmlProcessingUtils.escapeHtml("<div class=\"test\">'&'</div>");
+            assertEquals("&lt;div class=&quot;test&quot;&gt;&#39;&amp;&#39;&lt;/div&gt;", result);
+        }
+
+        @Test
+        @DisplayName("should not modify plain text")
+        void plainText() {
+            assertEquals("Hello World", EmlProcessingUtils.escapeHtml("Hello World"));
+        }
+    }
+
+    @Nested
+    @DisplayName("convertTextToHtml")
+    class ConvertTextToHtmlTests {
+
+        @Test
+        @DisplayName("should return empty string for null")
+        void nullInput() {
+            assertEquals("", EmlProcessingUtils.convertTextToHtml(null, null));
+        }
+
+        @Test
+        @DisplayName("should convert newlines to br tags")
+        void newlinesToBr() {
+            String result = EmlProcessingUtils.convertTextToHtml("Line1\nLine2", null);
+            assertTrue(result.contains("<br>"));
+        }
+
+        @Test
+        @DisplayName("should convert CRLF to br tags")
+        void crlfToBr() {
+            String result = EmlProcessingUtils.convertTextToHtml("Line1\r\nLine2", null);
+            assertTrue(result.contains("<br>"));
+            assertFalse(result.contains("\r"));
+        }
+
+        @Test
+        @DisplayName("should linkify URLs")
+        void linkifyUrls() {
+            String result =
+                    EmlProcessingUtils.convertTextToHtml("Visit https://example.com today", null);
+            assertTrue(result.contains("<a href=\"https://example.com\""));
+        }
+
+        @Test
+        @DisplayName("should linkify email addresses")
+        void linkifyEmails() {
+            String result = EmlProcessingUtils.convertTextToHtml("Contact test@example.com", null);
+            assertTrue(result.contains("mailto:test@example.com"));
+        }
+    }
+
+    @Nested
+    @DisplayName("decodeMimeHeader")
+    class DecodeMimeHeaderTests {
+
+        @Test
+        @DisplayName("should return null for null input")
+        void nullInput() {
+            assertNull(EmlProcessingUtils.decodeMimeHeader(null));
+        }
+
+        @Test
+        @DisplayName("should return empty string for empty input")
+        void emptyInput() {
+            assertEquals("", EmlProcessingUtils.decodeMimeHeader(""));
+        }
+
+        @Test
+        @DisplayName("should return plain text unchanged")
+        void plainText() {
+            assertEquals("Hello World", EmlProcessingUtils.decodeMimeHeader("Hello World"));
+        }
+
+        @Test
+        @DisplayName("should decode Base64 encoded header")
+        void decodeBase64() {
+            // "Hello" in Base64
+            String result = EmlProcessingUtils.decodeMimeHeader("=?UTF-8?B?SGVsbG8=?=");
+            assertEquals("Hello", result);
+        }
+
+        @Test
+        @DisplayName("should decode quoted-printable encoded header")
+        void decodeQuotedPrintable() {
+            String result = EmlProcessingUtils.decodeMimeHeader("=?UTF-8?Q?Hello_World?=");
+            assertEquals("Hello World", result);
+        }
+
+        @Test
+        @DisplayName("should decode concatenated encoded words")
+        void decodeConcatenated() {
+            String input = "=?UTF-8?B?SGVs?= =?UTF-8?B?bG8=?=";
+            String result = EmlProcessingUtils.decodeMimeHeader(input);
+            assertEquals("Hello", result);
+        }
+
+        @Test
+        @DisplayName("should handle unknown encoding gracefully")
+        void unknownEncoding() {
+            String input = "=?UTF-8?X?unknown?=";
+            String result = EmlProcessingUtils.decodeMimeHeader(input);
+            assertEquals("=?UTF-8?X?unknown?=", result);
+        }
+    }
+
+    @Nested
+    @DisplayName("detectMimeType")
+    class DetectMimeTypeTests {
+
+        @Test
+        @DisplayName("should return existing MIME type if provided")
+        void existingMimeType() {
+            assertEquals(
+                    "image/jpeg", EmlProcessingUtils.detectMimeType("photo.png", "image/jpeg"));
+        }
+
+        @Test
+        @DisplayName("should detect PNG from filename")
+        void detectPng() {
+            assertEquals("image/png", EmlProcessingUtils.detectMimeType("image.png", null));
+        }
+
+        @Test
+        @DisplayName("should detect JPEG from filename")
+        void detectJpeg() {
+            assertEquals("image/jpeg", EmlProcessingUtils.detectMimeType("photo.jpg", null));
+        }
+
+        @Test
+        @DisplayName("should default to image/png for unknown extension")
+        void defaultMimeType() {
+            assertEquals("image/png", EmlProcessingUtils.detectMimeType("file.xyz", null));
+        }
+
+        @Test
+        @DisplayName("should default to image/png for null filename and mime")
+        void nullFilenameAndMime() {
+            assertEquals("image/png", EmlProcessingUtils.detectMimeType(null, null));
+        }
+    }
+
+    @Nested
+    @DisplayName("sanitizeText")
+    class SanitizeTextTests {
+
+        @Test
+        @DisplayName("should escape HTML when no sanitizer provided")
+        void noSanitizer() {
+            String result = EmlProcessingUtils.sanitizeText("<script>", null);
+            assertEquals("&lt;script&gt;", result);
+        }
+    }
+
+    @Nested
+    @DisplayName("processEmailHtmlBody")
+    class ProcessEmailHtmlBodyTests {
+
+        @Test
+        @DisplayName("should return empty string for null body")
+        void nullBody() {
+            assertEquals("", EmlProcessingUtils.processEmailHtmlBody(null, null, null));
+        }
+
+        @Test
+        @DisplayName("should strip fixed position CSS")
+        void stripFixedPosition() {
+            String html = "<div style=\"position:fixed; top:0\">content</div>";
+            String result = EmlProcessingUtils.processEmailHtmlBody(html, null, null);
+            assertFalse(result.contains("position:fixed"));
+        }
+    }
+
+    @Nested
+    @DisplayName("decodeUrlEncoded")
+    class DecodeUrlEncodedTests {
+
+        @Test
+        @DisplayName("should decode URL-encoded string")
+        void decodeEncoded() {
+            assertEquals("hello world", EmlProcessingUtils.decodeUrlEncoded("hello%20world"));
+        }
+
+        @Test
+        @DisplayName("should return original on invalid encoding")
+        void invalidEncoding() {
+            String result = EmlProcessingUtils.decodeUrlEncoded("%ZZinvalid");
+            assertEquals("%ZZinvalid", result);
+        }
+    }
+}
@@ -1,44 +1,114 @@
 package stirling.software.common.util;

 import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;

+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.springframework.ui.Model;
 import org.springframework.web.servlet.ModelAndView;

-public class ErrorUtilsTest {
+class ErrorUtilsTest {

-    @Test
-    public void testExceptionToModel() {
-        // Create a mock Model
-        Model model = new org.springframework.ui.ExtendedModelMap();
+    @Nested
+    @DisplayName("exceptionToModel")
+    class ExceptionToModelTests {

-        // Create a test exception
-        Exception ex = new Exception("Test Exception");
+        @Test
+        @DisplayName("should add error message to model")
+        void addsErrorMessage() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException("test error");

-        // Call the method under test
-        Model resultModel = ErrorUtils.exceptionToModel(model, ex);
+            ErrorUtils.exceptionToModel(model, ex);

-        // Verify the result
-        assertNotNull(resultModel);
-        assertEquals("Test Exception", resultModel.getAttribute("errorMessage"));
-        assertNotNull(resultModel.getAttribute("stackTrace"));
+            verify(model).addAttribute("errorMessage", "test error");
+        }
+
+        @Test
+        @DisplayName("should add stack trace to model")
+        void addsStackTrace() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException("test error");
+
+            ErrorUtils.exceptionToModel(model, ex);
+
+            verify(model)
+                    .addAttribute(
+                            eq("stackTrace"),
+                            argThat(
+                                    arg ->
+                                            arg instanceof String s
+                                                    && s.contains("RuntimeException")
+                                                    && s.contains("test error")));
+        }
+
+        @Test
+        @DisplayName("should return the same model instance")
+        void returnsSameModel() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException("test");
+
+            Model result = ErrorUtils.exceptionToModel(model, ex);
+
+            assertSame(model, result);
+        }
+
+        @Test
+        @DisplayName("should handle exception with null message")
+        void nullExceptionMessage() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException((String) null);
+
+            ErrorUtils.exceptionToModel(model, ex);
+
+            verify(model).addAttribute("errorMessage", null);
+        }
    }

-    @Test
-    public void testExceptionToModelView() {
-        // Create a mock Model
-        Model model = new org.springframework.ui.ExtendedModelMap();
+    @Nested
+    @DisplayName("exceptionToModelView")
+    class ExceptionToModelViewTests {

-        // Create a test exception
-        Exception ex = new Exception("Test Exception");
+        @Test
+        @DisplayName("should create ModelAndView with error message")
+        void addsErrorMessage() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException("view error");

-        // Call the method under test
-        ModelAndView modelAndView = ErrorUtils.exceptionToModelView(model, ex);
+            ModelAndView result = ErrorUtils.exceptionToModelView(model, ex);

-        // Verify the result
-        assertNotNull(modelAndView);
-        assertEquals("Test Exception", modelAndView.getModel().get("errorMessage"));
-        assertNotNull(modelAndView.getModel().get("stackTrace"));
+            assertNotNull(result);
+            assertEquals("view error", result.getModel().get("errorMessage"));
+        }
+
+        @Test
+        @DisplayName("should create ModelAndView with stack trace")
+        void addsStackTrace() {
+            Model model = mock(Model.class);
+            Exception ex = new RuntimeException("view error");
+
+            ModelAndView result = ErrorUtils.exceptionToModelView(model, ex);
+
+            String stackTrace = (String) result.getModel().get("stackTrace");
+            assertNotNull(stackTrace);
+            assertTrue(stackTrace.contains("RuntimeException"));
+            assertTrue(stackTrace.contains("view error"));
+        }
+
+        @Test
+        @DisplayName("should handle nested exception")
+        void nestedException() {
+            Model model = mock(Model.class);
+            Exception cause = new IllegalArgumentException("root cause");
+            Exception ex = new RuntimeException("wrapper", cause);
+
+            ModelAndView result = ErrorUtils.exceptionToModelView(model, ex);
+
+            String stackTrace = (String) result.getModel().get("stackTrace");
+            assertTrue(stackTrace.contains("root cause"));
+            assertEquals("wrapper", result.getModel().get("errorMessage"));
+        }
    }
 }
@@ -0,0 +1,90 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class ExecutorFactoryTest {
+
+    @Test
+    @DisplayName("newVirtualThreadExecutor should return non-null executor")
+    void virtualThreadExecutorNotNull() {
+        ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
+        assertNotNull(executor);
+        executor.shutdown();
+    }
+
+    @Test
+    @DisplayName("newVirtualThreadExecutor should execute tasks")
+    void virtualThreadExecutorExecutesTasks() throws Exception {
+        ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
+        AtomicBoolean ran = new AtomicBoolean(false);
+        CountDownLatch latch = new CountDownLatch(1);
+
+        executor.submit(
+                () -> {
+                    ran.set(true);
+                    latch.countDown();
+                });
+
+        assertTrue(latch.await(5, TimeUnit.SECONDS));
+        assertTrue(ran.get());
+        executor.shutdown();
+    }
+
+    @Test
+    @DisplayName("newVirtualThreadExecutor should run on virtual threads")
+    void virtualThreadExecutorUsesVirtualThreads() throws Exception {
+        ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
+        AtomicReference<Boolean> isVirtual = new AtomicReference<>();
+        CountDownLatch latch = new CountDownLatch(1);
+
+        executor.submit(
+                () -> {
+                    isVirtual.set(Thread.currentThread().isVirtual());
+                    latch.countDown();
+                });
+
+        assertTrue(latch.await(5, TimeUnit.SECONDS));
+        assertTrue(isVirtual.get());
+        executor.shutdown();
+    }
+
+    @Test
+    @DisplayName("newSingleVirtualThreadScheduledExecutor should return non-null")
+    void scheduledExecutorNotNull() {
+        ScheduledExecutorService executor =
+                ExecutorFactory.newSingleVirtualThreadScheduledExecutor();
+        assertNotNull(executor);
+        executor.shutdown();
+    }
+
+    @Test
+    @DisplayName("newSingleVirtualThreadScheduledExecutor should execute scheduled tasks")
+    void scheduledExecutorExecutesTasks() throws Exception {
+        ScheduledExecutorService executor =
+                ExecutorFactory.newSingleVirtualThreadScheduledExecutor();
+        AtomicBoolean ran = new AtomicBoolean(false);
+        CountDownLatch latch = new CountDownLatch(1);
+
+        executor.schedule(
+                () -> {
+                    ran.set(true);
+                    latch.countDown();
+                },
+                10,
+                TimeUnit.MILLISECONDS);
+
+        assertTrue(latch.await(5, TimeUnit.SECONDS));
+        assertTrue(ran.get());
+        executor.shutdown();
+    }
+}
@@ -1,194 +1,110 @@
 package stirling.software.common.util;

 import static org.junit.jupiter.api.Assertions.*;
-import static org.mockito.ArgumentMatchers.any;
-import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.*;

 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.nio.file.attribute.FileTime;
-import java.time.Instant;
 import java.util.List;
 import java.util.function.Predicate;

-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.ExtendWith;
 import org.junit.jupiter.api.io.TempDir;
-import org.mockito.Mock;
-import org.mockito.Mockito;
-import org.mockito.junit.jupiter.MockitoExtension;

 import stirling.software.common.configuration.RuntimePathConfig;

-@ExtendWith(MockitoExtension.class)
 class FileMonitorTest {

    @TempDir Path tempDir;

-    @Mock private RuntimePathConfig runtimePathConfig;
-
-    @Mock private Predicate<Path> pathFilter;
-
-    private FileMonitor fileMonitor;
-
-    @BeforeEach
-    void setUp() throws IOException {
+    private FileMonitor createFileMonitor(Path watchDir) throws IOException {
+        Predicate<Path> acceptAll = path -> true;
+        RuntimePathConfig runtimePathConfig = mock(RuntimePathConfig.class);
        when(runtimePathConfig.getPipelineWatchedFoldersPaths())
-                .thenReturn(List.of(tempDir.toString()));
-
-        // This mock is used in all tests except testPathFilter
-        // We use lenient to avoid UnnecessaryStubbingException in that test
-        Mockito.lenient().when(pathFilter.test(any())).thenReturn(true);
-
-        fileMonitor = new FileMonitor(pathFilter, runtimePathConfig);
+                .thenReturn(List.of(watchDir.toString()));
+        return new FileMonitor(acceptAll, runtimePathConfig);
    }

    @Test
-    void testIsFileReadyForProcessing_OldFile() throws IOException {
-        // Capture test time at the beginning for deterministic calculations
-        final Instant testTime = Instant.now();
-
-        // Create a test file
-        Path testFile = tempDir.resolve("test-file.txt");
-        Files.write(testFile, "test content".getBytes());
-
-        // Set modified time to 10 seconds ago (relative to test start time)
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime.minusMillis(10000)));
-
-        // File should be ready for processing as it was modified more than 5 seconds ago
-        assertTrue(fileMonitor.isFileReadyForProcessing(testFile));
+    void testConstructor_withValidDirectory() throws IOException {
+        FileMonitor monitor = createFileMonitor(tempDir);
+        assertNotNull(monitor);
    }

    @Test
-    void testIsFileReadyForProcessing_RecentFile() throws IOException {
-        // Capture test time at the beginning for deterministic calculations
-        final Instant testTime = Instant.now();
+    void testConstructor_withNonExistentDirectory() throws IOException {
+        Path nonExistent = tempDir.resolve("does_not_exist");
+        Predicate<Path> acceptAll = path -> true;
+        RuntimePathConfig config = mock(RuntimePathConfig.class);
+        when(config.getPipelineWatchedFoldersPaths()).thenReturn(List.of(nonExistent.toString()));

-        // Create a test file
-        Path testFile = tempDir.resolve("recent-file.txt");
-        Files.write(testFile, "test content".getBytes());
-
-        // Set modified time to just now (relative to test start time)
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime));
-
-        // File should not be ready for processing as it was just modified
-        assertFalse(fileMonitor.isFileReadyForProcessing(testFile));
+        // Should not throw - just logs an error about non-existent path
+        FileMonitor monitor = new FileMonitor(acceptAll, config);
+        assertNotNull(monitor);
    }

    @Test
-    void testIsFileReadyForProcessing_NonExistentFile() {
-        // Create a path to a file that doesn't exist
-        Path nonExistentFile = tempDir.resolve("non-existent-file.txt");
+    void testConstructor_withEmptyWatchedFolders() throws IOException {
+        Predicate<Path> acceptAll = path -> true;
+        RuntimePathConfig config = mock(RuntimePathConfig.class);
+        when(config.getPipelineWatchedFoldersPaths()).thenReturn(List.of());

-        // Non-existent file should not be ready for processing
-        assertFalse(fileMonitor.isFileReadyForProcessing(nonExistentFile));
+        FileMonitor monitor = new FileMonitor(acceptAll, config);
+        assertNotNull(monitor);
    }

    @Test
-    void testIsFileReadyForProcessing_LockedFile() throws IOException {
-        // Capture test time at the beginning for deterministic calculations
-        final Instant testTime = Instant.now();
-
-        // Create a test file
-        Path testFile = tempDir.resolve("locked-file.txt");
-        Files.write(testFile, "test content".getBytes());
-
-        // Set modified time to 10 seconds ago (relative to test start time) to make sure it passes
-        // the time check
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime.minusMillis(10000)));
-
-        // Verify the file is considered ready when it meets the time criteria
-        assertTrue(
-                fileMonitor.isFileReadyForProcessing(testFile),
-                "File should be ready for processing when sufficiently old");
+    void testTrackFiles_noEventsDoesNotThrow() throws IOException {
+        FileMonitor monitor = createFileMonitor(tempDir);
+        // Should not throw even when no events have occurred
+        assertDoesNotThrow(() -> monitor.trackFiles());
    }

    @Test
-    void testPathFilter() throws IOException {
-        // Use a simple lambda instead of a mock for better control
-        Predicate<Path> pdfFilter = path -> path.toString().endsWith(".pdf");
+    void testIsFileReadyForProcessing_nonExistentFile() throws IOException {
+        FileMonitor monitor = createFileMonitor(tempDir);
+        Path nonExistent = tempDir.resolve("nonexistent.pdf");

-        // Create a new FileMonitor with the PDF filter
-        FileMonitor pdfMonitor = new FileMonitor(pdfFilter, runtimePathConfig);
-
-        // Create a PDF file
-        Path pdfFile = tempDir.resolve("test.pdf");
-        Files.write(pdfFile, "pdf content".getBytes());
-        Files.setLastModifiedTime(pdfFile, FileTime.from(Instant.ofEpochMilli(1000000L)));
-
-        // Create a TXT file
-        Path txtFile = tempDir.resolve("test.txt");
-        Files.write(txtFile, "text content".getBytes());
-        Files.setLastModifiedTime(txtFile, FileTime.from(Instant.ofEpochMilli(1000000L)));
-
-        // PDF file should be ready for processing
-        assertTrue(pdfMonitor.isFileReadyForProcessing(pdfFile));
-
-        // Note: In the current implementation, FileMonitor.isFileReadyForProcessing()
-        // doesn't check file filters directly - it only checks criteria like file existence
-        // and modification time. The filtering is likely handled elsewhere in the workflow.
-
-        // To avoid test failures, we'll verify that the filter itself works correctly
-        assertFalse(pdfFilter.test(txtFile), "PDF filter should reject txt files");
-        assertTrue(pdfFilter.test(pdfFile), "PDF filter should accept pdf files");
+        // Non-existent file should not be ready (file lock check will fail)
+        boolean ready = monitor.isFileReadyForProcessing(nonExistent);
+        assertFalse(ready, "Non-existent file should not be ready for processing");
    }

    @Test
-    void testIsFileReadyForProcessing_FileInUse() throws IOException {
-        // Capture test time at the beginning for deterministic calculations
-        final Instant testTime = Instant.now();
+    void testIsFileReadyForProcessing_existingFile() throws IOException, InterruptedException {
+        FileMonitor monitor = createFileMonitor(tempDir);
+        Path testFile = tempDir.resolve("test.pdf");
+        Files.writeString(testFile, "test content");

-        // Create a test file
-        Path testFile = tempDir.resolve("in-use-file.txt");
-        Files.write(testFile, "initial content".getBytes());
+        // Run trackFiles to process any events
+        monitor.trackFiles();

-        // Set modified time to 10 seconds ago (relative to test start time)
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime.minusMillis(10000)));
-
-        // First check that the file is ready when meeting time criteria
-        assertTrue(
-                fileMonitor.isFileReadyForProcessing(testFile),
-                "File should be ready for processing when sufficiently old");
-
-        // After modifying the file to simulate closing, it should still be ready
-        Files.write(testFile, "updated content".getBytes());
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime.minusMillis(10000)));
-
-        assertTrue(
-                fileMonitor.isFileReadyForProcessing(testFile),
-                "File should be ready for processing after updating");
+        // The file might or might not be ready depending on timing,
+        // but calling the method should not throw
+        assertDoesNotThrow(() -> monitor.isFileReadyForProcessing(testFile));
    }

    @Test
-    void testIsFileReadyForProcessing_FileWithAbsolutePath() throws IOException {
-        // Capture test time at the beginning for deterministic calculations
-        final Instant testTime = Instant.now();
+    void testTrackFiles_afterFileCreation() throws IOException {
+        FileMonitor monitor = createFileMonitor(tempDir);

-        // Create a test file
-        Path testFile = tempDir.resolve("absolute-path-file.txt");
-        Files.write(testFile, "test content".getBytes());
+        // Create a file in the watched directory
+        Path testFile = tempDir.resolve("newfile.txt");
+        Files.writeString(testFile, "hello");

-        // Set modified time to 10 seconds ago (relative to test start time)
-        Files.setLastModifiedTime(testFile, FileTime.from(testTime.minusMillis(10000)));
-
-        // File should be ready for processing as it was modified more than 5 seconds ago
-        // Use the absolute path to make sure it's handled correctly
-        assertTrue(fileMonitor.isFileReadyForProcessing(testFile.toAbsolutePath()));
+        // Track files should process the creation event
+        assertDoesNotThrow(() -> monitor.trackFiles());
    }

    @Test
-    void testIsFileReadyForProcessing_DirectoryInsteadOfFile() throws IOException {
-        // Create a test directory
-        Path testDir = tempDir.resolve("test-directory");
-        Files.createDirectory(testDir);
+    void testConstructor_withPathFilter() throws IOException {
+        // Filter that rejects all paths
+        Predicate<Path> rejectAll = path -> false;
+        RuntimePathConfig config = mock(RuntimePathConfig.class);
+        when(config.getPipelineWatchedFoldersPaths()).thenReturn(List.of(tempDir.toString()));

-        // Set modified time to 10 seconds ago
-        Files.setLastModifiedTime(testDir, FileTime.from(Instant.ofEpochMilli(1000000L)));
-
-        // A directory should not be considered ready for processing
-        boolean isReady = fileMonitor.isFileReadyForProcessing(testDir);
-        assertFalse(isReady, "A directory should not be considered ready for processing");
+        FileMonitor monitor = new FileMonitor(rejectAll, config);
+        assertNotNull(monitor);
    }
 }
@@ -0,0 +1,357 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Answers.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.*;
+
+import java.io.IOException;
+import java.io.RandomAccessFile;
+import java.nio.channels.FileChannel;
+import java.nio.channels.FileLock;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.FileTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.Mock;
+import org.mockito.MockedStatic;
+import org.mockito.MockitoAnnotations;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.model.ApplicationProperties.AutoPipeline.FileReadiness;
+
+@DisplayName("FileReadinessChecker")
+class FileReadinessCheckerTest {
+
+    @TempDir Path tempDir;
+
+    @Mock ApplicationProperties applicationProperties;
+    @Mock ApplicationProperties.AutoPipeline autoPipeline;
+
+    /** Real config object — easier to tweak per test than chaining multiple stubs. */
+    FileReadiness config;
+
+    FileReadinessChecker checker;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+
+        config = new FileReadiness();
+        config.setEnabled(true);
+        config.setSettleTimeMillis(0); // instant settle by default — individual tests override
+        config.setSizeCheckDelayMillis(1); // minimal pause keeps tests fast
+        config.setAllowedExtensions(new ArrayList<>());
+
+        when(applicationProperties.getAutoPipeline()).thenReturn(autoPipeline);
+        when(autoPipeline.getFileReadiness()).thenReturn(config);
+
+        checker = new FileReadinessChecker(applicationProperties);
+    }
+
+    // =========================================================================
+    // Master toggle
+    // =========================================================================
+
+    @Nested
+    @DisplayName("when enabled=false")
+    class WhenDisabled {
+
+        @Test
+        @DisplayName("always returns true regardless of file state")
+        void alwaysReady() throws IOException {
+            config.setEnabled(false);
+
+            // Non-existent path — would normally fail check #1
+            Path ghost = tempDir.resolve("does-not-exist.pdf");
+            assertTrue(checker.isReady(ghost));
+        }
+    }
+
+    // =========================================================================
+    // Check #1 + #2: existence and regular-file guard
+    // =========================================================================
+
+    @Nested
+    @DisplayName("existence and file-type checks")
+    class ExistenceChecks {
+
+        @Test
+        @DisplayName("non-existent path → not ready")
+        void fileDoesNotExist() {
+            Path ghost = tempDir.resolve("ghost.pdf");
+            assertFalse(checker.isReady(ghost));
+        }
+
+        @Test
+        @DisplayName("path is a directory → not ready")
+        void pathIsDirectory() throws IOException {
+            Path dir = tempDir.resolve("subdir");
+            Files.createDirectory(dir);
+            assertFalse(checker.isReady(dir));
+        }
+
+        @Test
+        @DisplayName("path is a regular file → passes existence checks")
+        void regularFilePassesExistenceCheck() throws IOException {
+            Path file = realFile("test.pdf", "content");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+    }
+
+    // =========================================================================
+    // Check #3: extension filter
+    // =========================================================================
+
+    @Nested
+    @DisplayName("extension filter")
+    class ExtensionFilter {
+
+        @Test
+        @DisplayName("empty allow-list → all extensions accepted")
+        void emptyAllowListAcceptsAll() throws IOException {
+            config.setAllowedExtensions(new ArrayList<>()); // empty = no filter
+            Path file = realFile("report.docx", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("extension in allow-list → passes")
+        void extensionInAllowList() throws IOException {
+            config.setAllowedExtensions(List.of("pdf", "tiff"));
+            Path file = realFile("scan.pdf", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("extension not in allow-list → not ready")
+        void extensionNotInAllowList() throws IOException {
+            config.setAllowedExtensions(List.of("pdf", "tiff"));
+            Path file = realFile("document.docx", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertFalse(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("extension matching is case-insensitive")
+        void extensionMatchIsCaseInsensitive() throws IOException {
+            config.setAllowedExtensions(List.of("PDF"));
+            Path file = realFile("scan.pdf", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("file without extension and non-empty allow-list → not ready")
+        void fileWithNoExtension() throws IOException {
+            config.setAllowedExtensions(List.of("pdf"));
+            Path file = realFile("README", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertFalse(checker.isReady(file));
+        }
+    }
+
+    // =========================================================================
+    // Check #4: settle-time (last-modified age)
+    // =========================================================================
+
+    @Nested
+    @DisplayName("settle-time check")
+    class SettleTime {
+
+        @Test
+        @DisplayName("recently modified file → not ready")
+        void recentlyModified_notReady() throws IOException {
+            config.setSettleTimeMillis(60_000); // require 1 minute of quiet
+            Path file = realFile("new.pdf", "data");
+            // last-modified is now (just created) — well within the threshold
+            assertFalse(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("file settled for longer than threshold → ready")
+        void settled_ready() throws IOException {
+            config.setSettleTimeMillis(5_000);
+            Path file = realFile("old.pdf", "data");
+            setLastModifiedInPast(file, 10_000); // 10 s ago — older than 5 s threshold
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("settle threshold of 0 ms passes any file")
+        void zeroThreshold_alwaysPasses() throws IOException {
+            config.setSettleTimeMillis(0);
+            Path file = realFile("instant.pdf", "data");
+            // last-modified is right now; 0 ms threshold means anything passes
+            assertTrue(checker.isReady(file));
+        }
+    }
+
+    // =========================================================================
+    // Check #5: size stability
+    // =========================================================================
+
+    @Nested
+    @DisplayName("size-stability check")
+    class SizeStability {
+
+        @Test
+        @DisplayName("size unchanged between two reads → ready")
+        void sizeStable_ready() throws IOException {
+            config.setSizeCheckDelayMillis(1);
+            Path file = realFile("stable.pdf", "fixed content");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("size changes between two reads → not ready")
+        void sizeChanging_notReady() throws IOException {
+            config.setSizeCheckDelayMillis(1);
+            Path file = realFile("growing.pdf", "initial");
+            setLastModifiedInPast(file, 60_000);
+
+            // Use MockedStatic to control what Files.size() returns on each call
+            // while leaving all other Files.* methods intact.
+            AtomicInteger sizeCallCount = new AtomicInteger(0);
+            try (MockedStatic<Files> mockedFiles = mockStatic(Files.class, CALLS_REAL_METHODS)) {
+                mockedFiles
+                        .when(() -> Files.size(file))
+                        .thenAnswer(
+                                inv ->
+                                        sizeCallCount.incrementAndGet() == 1
+                                                ? 100L // first read: 100 bytes
+                                                : 200L); // second read: 200 bytes — changed!
+                assertFalse(checker.isReady(file));
+            }
+        }
+    }
+
+    // =========================================================================
+    // Check #6: file-lock check
+    // =========================================================================
+
+    @Nested
+    @DisplayName("file-lock check")
+    class FileLockCheck {
+
+        @Test
+        @DisplayName("file held open with exclusive lock by another thread → not ready")
+        void fileLocked_notReady() throws IOException, InterruptedException {
+            Path file = realFile("locked.pdf", "data");
+            setLastModifiedInPast(file, 60_000);
+
+            CountDownLatch lockAcquired = new CountDownLatch(1);
+            CountDownLatch testDone = new CountDownLatch(1);
+            AtomicInteger lockThreadFailed = new AtomicInteger(0);
+
+            Thread lockHolder =
+                    new Thread(
+                            () -> {
+                                try (RandomAccessFile raf =
+                                                new RandomAccessFile(file.toFile(), "rw");
+                                        FileChannel channel = raf.getChannel();
+                                        FileLock lock = channel.lock()) {
+                                    lockAcquired.countDown();
+                                    testDone.await(10, TimeUnit.SECONDS);
+                                } catch (Exception e) {
+                                    lockThreadFailed.set(1);
+                                    lockAcquired.countDown();
+                                }
+                            });
+            lockHolder.setDaemon(true);
+            lockHolder.start();
+            lockAcquired.await(5, TimeUnit.SECONDS);
+
+            try {
+                if (lockThreadFailed.get() == 0) {
+                    // Lock was successfully held — the checker must see it as locked.
+                    // On JVM, tryLock() from a second thread in the same process throws
+                    // OverlappingFileLockException (or returns null on some platforms), both of
+                    // which isLocked() maps to true.
+                    assertFalse(checker.isReady(file));
+                }
+                // If locking failed on this platform we simply skip the assertion rather than
+                // failing the build — the logic path is still exercised by other tests.
+            } finally {
+                testDone.countDown();
+                lockHolder.join(5_000);
+            }
+        }
+
+        @Test
+        @DisplayName("file with no external lock and all checks passing → ready")
+        void noLock_ready() throws IOException {
+            Path file = realFile("unlocked.pdf", "data");
+            setLastModifiedInPast(file, 60_000);
+            assertTrue(checker.isReady(file));
+        }
+    }
+
+    // =========================================================================
+    // Full happy-path integration
+    // =========================================================================
+
+    @Nested
+    @DisplayName("full happy path")
+    class HappyPath {
+
+        @Test
+        @DisplayName("all checks pass → ready")
+        void allChecksPass_ready() throws IOException {
+            config.setSettleTimeMillis(5_000);
+            config.setSizeCheckDelayMillis(1);
+            config.setAllowedExtensions(List.of("pdf"));
+
+            Path file = realFile("invoice.pdf", "PDF content");
+            setLastModifiedInPast(file, 10_000);
+
+            assertTrue(checker.isReady(file));
+        }
+
+        @Test
+        @DisplayName("first failing check short-circuits evaluation")
+        void shortCircuitsOnFirstFailure() throws IOException {
+            // Extension filter will reject — settle / size / lock checks must never run
+            config.setAllowedExtensions(List.of("pdf"));
+            config.setSettleTimeMillis(0);
+            config.setSizeCheckDelayMillis(1);
+
+            Path file = realFile("archive.zip", "ZIP data");
+            setLastModifiedInPast(file, 60_000);
+
+            assertFalse(checker.isReady(file));
+        }
+    }
+
+    // =========================================================================
+    // Helpers
+    // =========================================================================
+
+    private Path realFile(String name, String content) throws IOException {
+        Path file = tempDir.resolve(name);
+        Files.writeString(file, content);
+        return file;
+    }
+
+    /**
+     * Back-dates the last-modified time of {@code path} by {@code millisAgo} so that settle-time
+     * checks pass without actually waiting.
+     */
+    private void setLastModifiedInPast(Path path, long millisAgo) throws IOException {
+        Files.setLastModifiedTime(
+                path, FileTime.fromMillis(System.currentTimeMillis() - millisAgo));
+    }
+}
@@ -1,115 +1,76 @@
 package stirling.software.common.util;

 import static org.junit.jupiter.api.Assertions.*;
-import static org.mockito.ArgumentMatchers.anyString;
-import static org.mockito.Mockito.mock;
-import static org.mockito.Mockito.when;

-import java.io.IOException;
-import java.nio.file.Files;
-
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;

-import stirling.software.common.model.api.converters.HTMLToPdfRequest;
-import stirling.software.common.service.SsrfProtectionService;
+class FileToPdfTest {

-public class FileToPdfTest {
-
-    private CustomHtmlSanitizer customHtmlSanitizer;
-
-    @BeforeEach
-    void setUp() {
-        SsrfProtectionService mockSsrfProtectionService = mock(SsrfProtectionService.class);
-        stirling.software.common.model.ApplicationProperties mockApplicationProperties =
-                mock(stirling.software.common.model.ApplicationProperties.class);
-        stirling.software.common.model.ApplicationProperties.System mockSystem =
-                mock(stirling.software.common.model.ApplicationProperties.System.class);
-
-        when(mockSsrfProtectionService.isUrlAllowed(org.mockito.ArgumentMatchers.anyString()))
-                .thenReturn(true);
-        when(mockApplicationProperties.getSystem()).thenReturn(mockSystem);
-        when(mockSystem.isDisableSanitize()).thenReturn(false);
-
-        customHtmlSanitizer =
-                new CustomHtmlSanitizer(mockSsrfProtectionService, mockApplicationProperties);
+    @Test
+    void testSanitizeZipFilename_normalFilename() {
+        String result = FileToPdf.sanitizeZipFilename("document.html");
+        assertEquals("document.html", result);
    }

-    /**
-     * Test the HTML to PDF conversion. This test expects an IOException when an empty HTML input is
-     * provided.
-     */
    @Test
-    public void testConvertHtmlToPdf() {
-        HTMLToPdfRequest request = new HTMLToPdfRequest();
-        byte[] fileBytes = new byte[0]; // Sample file bytes (empty input)
-        String fileName = "test.html"; // Sample file name indicating an HTML file
-        TempFileManager tempFileManager = mock(TempFileManager.class); // Mock TempFileManager
-
-        // Mock the temp file creation to return real temp files
-        try {
-            when(tempFileManager.createTempFile(anyString()))
-                    .thenReturn(Files.createTempFile("test", ".pdf").toFile())
-                    .thenReturn(Files.createTempFile("test", ".html").toFile());
-        } catch (IOException e) {
-            throw new RuntimeException(e);
-        }
-
-        // Expect an IOException to be thrown due to empty input or invalid weasyprint path
-        Throwable thrown =
-                assertThrows(
-                        Exception.class,
-                        () ->
-                                FileToPdf.convertHtmlToPdf(
-                                        "/path/",
-                                        request,
-                                        fileBytes,
-                                        fileName,
-                                        tempFileManager,
-                                        customHtmlSanitizer));
-        assertNotNull(thrown);
+    void testSanitizeZipFilename_pathTraversal() {
+        String result = FileToPdf.sanitizeZipFilename("../../etc/passwd");
+        // Should remove ../ sequences
+        assertFalse(result.contains(".."), "Path traversal sequences should be removed");
    }

-    /**
-     * Test sanitizeZipFilename with null or empty input. It should return an empty string in these
-     * cases.
-     */
    @Test
-    public void testSanitizeZipFilename_NullOrEmpty() {
-        assertEquals("", FileToPdf.sanitizeZipFilename(null));
-        assertEquals("", FileToPdf.sanitizeZipFilename("   "));
+    void testSanitizeZipFilename_driveLetterRemoved() {
+        String result = FileToPdf.sanitizeZipFilename("C:\\Users\\test\\file.html");
+        assertFalse(result.startsWith("C:"), "Drive letter should be removed");
    }

-    /**
-     * Test sanitizeZipFilename to ensure it removes path traversal sequences. This includes
-     * removing both forward and backward slash sequences.
-     */
    @Test
-    public void testSanitizeZipFilename_RemovesTraversalSequences() {
-        String input = "../some/../path/..\\to\\file.txt";
-        String expected = "some/path/to/file.txt";
-
-        // Expect that the method replaces backslashes with forward slashes
-        // and removes path traversal sequences
-        assertEquals(expected, FileToPdf.sanitizeZipFilename(input));
+    void testSanitizeZipFilename_backslashesNormalized() {
+        String result = FileToPdf.sanitizeZipFilename("path\\to\\file.html");
+        assertFalse(result.contains("\\"), "Backslashes should be normalized to forward slashes");
+        assertTrue(result.contains("/") || !result.contains("\\"));
    }

-    /** Test sanitizeZipFilename to ensure that it removes leading drive letters and slashes. */
    @Test
-    public void testSanitizeZipFilename_RemovesLeadingDriveAndSlashes() {
-        String input = "C:\\folder\\file.txt";
-        String expected = "folder/file.txt";
-        assertEquals(expected, FileToPdf.sanitizeZipFilename(input));
-
-        input = "/folder/file.txt";
-        expected = "folder/file.txt";
-        assertEquals(expected, FileToPdf.sanitizeZipFilename(input));
+    void testSanitizeZipFilename_nullInput() {
+        String result = FileToPdf.sanitizeZipFilename(null);
+        assertEquals("", result, "Null input should return empty string");
    }

-    /** Test sanitizeZipFilename to verify that safe filenames remain unchanged. */
    @Test
-    public void testSanitizeZipFilename_NoChangeForSafeNames() {
-        String input = "folder/subfolder/file.txt";
-        assertEquals(input, FileToPdf.sanitizeZipFilename(input));
+    void testSanitizeZipFilename_emptyInput() {
+        String result = FileToPdf.sanitizeZipFilename("");
+        assertEquals("", result, "Empty input should return empty string");
+    }
+
+    @Test
+    void testSanitizeZipFilename_whitespaceOnly() {
+        String result = FileToPdf.sanitizeZipFilename("   ");
+        assertEquals("", result, "Whitespace-only input should return empty string");
+    }
+
+    @Test
+    void testSanitizeZipFilename_leadingSlashes() {
+        String result = FileToPdf.sanitizeZipFilename("///path/to/file.html");
+        assertFalse(result.startsWith("/"), "Leading slashes should be removed");
+    }
+
+    @Test
+    void testSanitizeZipFilename_nestedDirectories() {
+        String result = FileToPdf.sanitizeZipFilename("dir1/dir2/file.html");
+        assertEquals("dir1/dir2/file.html", result, "Normal nested paths should be preserved");
+    }
+
+    @Test
+    void testSanitizeZipFilename_mixedTraversal() {
+        String result = FileToPdf.sanitizeZipFilename("dir/../../../etc/passwd");
+        assertFalse(result.contains(".."), "Mixed path traversal should be removed");
+    }
+
+    @Test
+    void testSanitizeZipFilename_backslashTraversal() {
+        String result = FileToPdf.sanitizeZipFilename("dir\\..\\..\\etc\\passwd");
+        assertFalse(result.contains(".."), "Backslash path traversal should be removed");
    }
 }
@@ -0,0 +1,163 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDComboBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDListBox;
+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.PDTerminalField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.junit.jupiter.api.Test;
+
+class FormFieldTypeSupportTest {
+
+    @Test
+    void forField_withNull_returnsNull() {
+        assertNull(FormFieldTypeSupport.forField(null));
+    }
+
+    @Test
+    void forField_withTextField_returnsTEXT() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTextField field = new PDTextField(form);
+            assertEquals(FormFieldTypeSupport.TEXT, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withCheckBox_returnsCHECKBOX() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDCheckBox field = new PDCheckBox(form);
+            assertEquals(FormFieldTypeSupport.CHECKBOX, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withRadioButton_returnsRADIO() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDRadioButton field = new PDRadioButton(form);
+            assertEquals(FormFieldTypeSupport.RADIO, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withComboBox_returnsCOMBOBOX() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDComboBox field = new PDComboBox(form);
+            assertEquals(FormFieldTypeSupport.COMBOBOX, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withListBox_returnsLISTBOX() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDListBox field = new PDListBox(form);
+            assertEquals(FormFieldTypeSupport.LISTBOX, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withSignatureField_returnsSIGNATURE() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDSignatureField field = new PDSignatureField(form);
+            assertEquals(FormFieldTypeSupport.SIGNATURE, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forField_withPushButton_returnsBUTTON() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDPushButton field = new PDPushButton(form);
+            assertEquals(FormFieldTypeSupport.BUTTON, FormFieldTypeSupport.forField(field));
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void forTypeName_withValidNames_returnsCorrectEnum() {
+        assertEquals(FormFieldTypeSupport.TEXT, FormFieldTypeSupport.forTypeName("text"));
+        assertEquals(FormFieldTypeSupport.CHECKBOX, FormFieldTypeSupport.forTypeName("checkbox"));
+        assertEquals(FormFieldTypeSupport.RADIO, FormFieldTypeSupport.forTypeName("radio"));
+        assertEquals(FormFieldTypeSupport.COMBOBOX, FormFieldTypeSupport.forTypeName("combobox"));
+        assertEquals(FormFieldTypeSupport.LISTBOX, FormFieldTypeSupport.forTypeName("listbox"));
+        assertEquals(FormFieldTypeSupport.SIGNATURE, FormFieldTypeSupport.forTypeName("signature"));
+        assertEquals(FormFieldTypeSupport.BUTTON, FormFieldTypeSupport.forTypeName("button"));
+    }
+
+    @Test
+    void forTypeName_withNull_returnsNull() {
+        assertNull(FormFieldTypeSupport.forTypeName(null));
+    }
+
+    @Test
+    void forTypeName_withUnknown_returnsNull() {
+        assertNull(FormFieldTypeSupport.forTypeName("unknown"));
+    }
+
+    @Test
+    void doesNotSupportsDefinitionCreation_textReturnsFalse() {
+        assertFalse(FormFieldTypeSupport.TEXT.doesNotsupportsDefinitionCreation());
+    }
+
+    @Test
+    void doesNotSupportsDefinitionCreation_radioReturnsTrue() {
+        assertTrue(FormFieldTypeSupport.RADIO.doesNotsupportsDefinitionCreation());
+    }
+
+    @Test
+    void doesNotSupportsDefinitionCreation_signatureReturnsTrue() {
+        assertTrue(FormFieldTypeSupport.SIGNATURE.doesNotsupportsDefinitionCreation());
+    }
+
+    @Test
+    void doesNotSupportsDefinitionCreation_buttonReturnsTrue() {
+        assertTrue(FormFieldTypeSupport.BUTTON.doesNotsupportsDefinitionCreation());
+    }
+
+    @Test
+    void createField_text_returnsPDTextField() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTerminalField field = FormFieldTypeSupport.TEXT.createField(form);
+            assertInstanceOf(PDTextField.class, field);
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+
+    @Test
+    void createField_checkbox_returnsPDCheckBox() {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTerminalField field = FormFieldTypeSupport.CHECKBOX.createField(form);
+            assertInstanceOf(PDCheckBox.class, field);
+        } catch (Exception e) {
+            fail("Unexpected exception: " + e.getMessage());
+        }
+    }
+}
@@ -0,0 +1,304 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+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.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.junit.jupiter.api.Test;
+
+class FormUtilsAdditionalTest {
+
+    private record SetupDocument(PDPage page, PDAcroForm acroForm) {}
+
+    private static SetupDocument createBasicDocument(PDDocument document) throws IOException {
+        PDPage page = new PDPage();
+        document.addPage(page);
+
+        PDAcroForm acroForm = new PDAcroForm(document);
+        acroForm.setDefaultResources(new PDResources());
+        acroForm.setNeedAppearances(true);
+        document.getDocumentCatalog().setAcroForm(acroForm);
+
+        return new SetupDocument(page, acroForm);
+    }
+
+    private static void attachWidget(
+            SetupDocument setup,
+            org.apache.pdfbox.pdmodel.interactive.form.PDTerminalField field,
+            PDRectangle rectangle)
+            throws IOException {
+        PDAnnotationWidget widget = new PDAnnotationWidget();
+        widget.setRectangle(rectangle);
+        widget.setPage(setup.page);
+        List<PDAnnotationWidget> widgets = new ArrayList<>(field.getWidgets());
+        widgets.add(widget);
+        field.setWidgets(widgets);
+        setup.acroForm.getFields().add(field);
+        setup.page.getAnnotations().add(widget);
+    }
+
+    // --- detectFieldType ---
+
+    @Test
+    void testDetectFieldType_textField() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+            PDTextField field = new PDTextField(setup.acroForm);
+            assertEquals("text", FormUtils.detectFieldType(field));
+        }
+    }
+
+    @Test
+    void testDetectFieldType_checkBox() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+            PDCheckBox field = new PDCheckBox(setup.acroForm);
+            assertEquals("checkbox", FormUtils.detectFieldType(field));
+        }
+    }
+
+    // --- extractFormFields ---
+
+    @Test
+    void testExtractFormFields_nullDocument() {
+        List<FormUtils.FormFieldInfo> fields = FormUtils.extractFormFields(null);
+        assertTrue(fields.isEmpty());
+    }
+
+    @Test
+    void testExtractFormFields_noAcroForm() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            // No AcroForm set
+            List<FormUtils.FormFieldInfo> fields = FormUtils.extractFormFields(doc);
+            assertTrue(fields.isEmpty());
+        }
+    }
+
+    @Test
+    void testExtractFormFields_singleTextField() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+            PDTextField textField = new PDTextField(setup.acroForm);
+            textField.setPartialName("firstName");
+            attachWidget(setup, textField, new PDRectangle(50, 700, 200, 20));
+
+            List<FormUtils.FormFieldInfo> fields = FormUtils.extractFormFields(doc);
+            assertEquals(1, fields.size());
+            assertEquals("firstName", fields.get(0).name());
+            assertEquals("text", fields.get(0).type());
+            assertEquals(0, fields.get(0).pageIndex());
+        }
+    }
+
+    @Test
+    void testExtractFormFields_multipleFields() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+
+            PDTextField field1 = new PDTextField(setup.acroForm);
+            field1.setPartialName("name");
+            attachWidget(setup, field1, new PDRectangle(50, 700, 200, 20));
+
+            PDTextField field2 = new PDTextField(setup.acroForm);
+            field2.setPartialName("email");
+            attachWidget(setup, field2, new PDRectangle(50, 660, 200, 20));
+
+            List<FormUtils.FormFieldInfo> fields = FormUtils.extractFormFields(doc);
+            assertEquals(2, fields.size());
+        }
+    }
+
+    // --- buildFillTemplateRecord ---
+
+    @Test
+    void testBuildFillTemplateRecord_null() {
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(null);
+        assertTrue(result.isEmpty());
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_empty() {
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(Collections.emptyList());
+        assertTrue(result.isEmpty());
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_textField() {
+        FormUtils.FormFieldInfo info =
+                new FormUtils.FormFieldInfo(
+                        "name", "Name", "text", "John", null, false, 0, false, null, 0);
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(List.of(info));
+        assertEquals("John", result.get("name"));
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_checkboxField() {
+        FormUtils.FormFieldInfo info =
+                new FormUtils.FormFieldInfo(
+                        "agree", "Agreement", "checkbox", "Yes", null, false, 0, false, null, 0);
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(List.of(info));
+        assertEquals(Boolean.TRUE, result.get("agree"));
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_checkboxFieldOff() {
+        FormUtils.FormFieldInfo info =
+                new FormUtils.FormFieldInfo(
+                        "agree", "Agreement", "checkbox", "Off", null, false, 0, false, null, 0);
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(List.of(info));
+        assertEquals(Boolean.FALSE, result.get("agree"));
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_skipsButton() {
+        FormUtils.FormFieldInfo info =
+                new FormUtils.FormFieldInfo(
+                        "submit", "Submit", "button", null, null, false, 0, false, null, 0);
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(List.of(info));
+        assertFalse(result.containsKey("submit"));
+    }
+
+    @Test
+    void testBuildFillTemplateRecord_skipsSignature() {
+        FormUtils.FormFieldInfo info =
+                new FormUtils.FormFieldInfo(
+                        "sig", "Signature", "signature", null, null, false, 0, false, null, 0);
+        Map<String, Object> result = FormUtils.buildFillTemplateRecord(List.of(info));
+        assertFalse(result.containsKey("sig"));
+    }
+
+    // --- safeValue ---
+
+    @Test
+    void testSafeValue_nonNull() {
+        assertEquals("hello", FormUtils.safeValue("hello"));
+    }
+
+    @Test
+    void testSafeValue_null() {
+        assertEquals("", FormUtils.safeValue(null));
+    }
+
+    // --- applyFieldValues ---
+
+    @Test
+    void testApplyFieldValues_nullDocument() throws IOException {
+        // Should not throw
+        FormUtils.applyFieldValues(null, Map.of("key", "value"), false);
+    }
+
+    @Test
+    void testApplyFieldValues_noAcroFormStrict() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            assertThrows(
+                    IOException.class,
+                    () -> FormUtils.applyFieldValues(doc, Map.of("key", "val"), false, true));
+        }
+    }
+
+    @Test
+    void testApplyFieldValues_noAcroFormNonStrict() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            // Should not throw in non-strict mode
+            FormUtils.applyFieldValues(doc, Map.of("key", "val"), false, false);
+        }
+    }
+
+    @Test
+    void testApplyFieldValues_setsTextValue() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+            PDTextField textField = new PDTextField(setup.acroForm);
+            textField.setPartialName("company");
+            attachWidget(setup, textField, new PDRectangle(60, 720, 220, 20));
+
+            FormUtils.applyFieldValues(doc, Map.of("company", "Stirling"), false);
+            assertEquals("Stirling", textField.getValueAsString());
+        }
+    }
+
+    @Test
+    void testApplyFieldValues_checksCheckbox_nonStrict() throws IOException {
+        // In non-strict mode, checkbox state changes may fail silently
+        // if appearance streams are not properly configured. Just verify no exception.
+        try (PDDocument doc = new PDDocument()) {
+            SetupDocument setup = createBasicDocument(doc);
+            PDCheckBox checkBox = new PDCheckBox(setup.acroForm);
+            checkBox.setPartialName("subscribed");
+            checkBox.setExportValues(List.of("Yes"));
+            attachWidget(setup, checkBox, new PDRectangle(60, 680, 16, 16));
+
+            // Should not throw in non-strict mode even if appearance is missing
+            FormUtils.applyFieldValues(doc, Map.of("subscribed", true), false, false);
+            FormUtils.applyFieldValues(doc, Map.of("subscribed", false), false, false);
+        }
+    }
+
+    // --- filterSingleChoiceSelection ---
+
+    @Test
+    void testFilterSingleChoiceSelection_validSelection() {
+        String result =
+                FormUtils.filterSingleChoiceSelection(
+                        "Option A", List.of("Option A", "Option B"), "field1");
+        assertEquals("Option A", result);
+    }
+
+    @Test
+    void testFilterSingleChoiceSelection_invalidSelection() {
+        String result =
+                FormUtils.filterSingleChoiceSelection(
+                        "Invalid", List.of("Option A", "Option B"), "field1");
+        assertNull(result);
+    }
+
+    @Test
+    void testFilterSingleChoiceSelection_nullSelection() {
+        String result = FormUtils.filterSingleChoiceSelection(null, List.of("Option A"), "field1");
+        assertNull(result);
+    }
+
+    @Test
+    void testFilterSingleChoiceSelection_emptySelection() {
+        String result = FormUtils.filterSingleChoiceSelection("  ", List.of("Option A"), "field1");
+        assertNull(result);
+    }
+
+    // --- extractFieldsWithTemplate ---
+
+    @Test
+    void testExtractFieldsWithTemplate_emptyDocument() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            FormUtils.FormFieldExtraction extraction = FormUtils.extractFieldsWithTemplate(doc);
+            assertNotNull(extraction);
+            assertTrue(extraction.fields().isEmpty());
+            assertTrue(extraction.template().isEmpty());
+        }
+    }
+
+    // --- hasAnyRotatedPage ---
+
+    @Test
+    void testHasAnyRotatedPage_noRotation() throws IOException {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            assertFalse(FormUtils.hasAnyRotatedPage(doc));
+        }
+    }
+}
@@ -1,4 +1,4 @@
-package stirling.software.proprietary.util;
+package stirling.software.common.util;

 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -0,0 +1,97 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.junit.jupiter.api.Test;
+
+class GeneralFormCopyUtilsTest {
+
+    @Test
+    void hasAnyRotatedPage_noRotation_returnsFalse() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            doc.addPage(new PDPage());
+            assertFalse(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void hasAnyRotatedPage_with90Rotation_returnsTrue() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDPage page = new PDPage();
+            page.setRotation(90);
+            doc.addPage(page);
+            assertTrue(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void hasAnyRotatedPage_with180Rotation_returnsTrue() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDPage page = new PDPage();
+            page.setRotation(180);
+            doc.addPage(page);
+            assertTrue(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void hasAnyRotatedPage_with360Rotation_returnsFalse() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDPage page = new PDPage();
+            page.setRotation(360);
+            doc.addPage(page);
+            assertFalse(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void hasAnyRotatedPage_emptyDocument_returnsFalse() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            assertFalse(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void hasAnyRotatedPage_mixedPages_returnsTrue() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            doc.addPage(new PDPage());
+            PDPage rotated = new PDPage();
+            rotated.setRotation(270);
+            doc.addPage(rotated);
+            assertTrue(GeneralFormCopyUtils.hasAnyRotatedPage(doc));
+        }
+    }
+
+    @Test
+    void copyAndTransformFormFields_noAcroForm_doesNotThrow() throws Exception {
+        try (PDDocument source = new PDDocument();
+                PDDocument target = new PDDocument()) {
+            source.addPage(new PDPage());
+            target.addPage(new PDPage());
+            // No acro form set on source - should simply return without error
+            assertDoesNotThrow(
+                    () ->
+                            GeneralFormCopyUtils.copyAndTransformFormFields(
+                                    source, target, 1, 1, 1, 1, 612f, 792f));
+        }
+    }
+
+    @Test
+    void copyAndTransformFormFields_emptyAcroForm_doesNotThrow() throws Exception {
+        try (PDDocument source = new PDDocument();
+                PDDocument target = new PDDocument()) {
+            source.addPage(new PDPage());
+            target.addPage(new PDPage());
+            // Empty acro form
+            var acroForm = new org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm(source);
+            source.getDocumentCatalog().setAcroForm(acroForm);
+            assertDoesNotThrow(
+                    () ->
+                            GeneralFormCopyUtils.copyAndTransformFormFields(
+                                    source, target, 1, 1, 1, 1, 612f, 792f));
+        }
+    }
+}
@@ -0,0 +1,147 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
+import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDComboBox;
+import org.apache.pdfbox.pdmodel.interactive.form.PDListBox;
+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.PDTerminalField;
+import org.apache.pdfbox.pdmodel.interactive.form.PDTextField;
+import org.junit.jupiter.api.Test;
+
+class GeneralFormFieldTypeSupportTest {
+
+    @Test
+    void forField_withNull_returnsNull() {
+        assertNull(GeneralFormFieldTypeSupport.forField(null));
+    }
+
+    @Test
+    void forField_withTextField_returnsTEXT() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTextField field = new PDTextField(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.TEXT, GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withCheckBox_returnsCHECKBOX() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDCheckBox field = new PDCheckBox(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.CHECKBOX,
+                    GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withRadioButton_returnsRADIO() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDRadioButton field = new PDRadioButton(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.RADIO, GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withComboBox_returnsCOMBOBOX() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDComboBox field = new PDComboBox(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.COMBOBOX,
+                    GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withListBox_returnsLISTBOX() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDListBox field = new PDListBox(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.LISTBOX,
+                    GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withSignatureField_returnsSIGNATURE() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDSignatureField field = new PDSignatureField(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.SIGNATURE,
+                    GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void forField_withPushButton_returnsBUTTON() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDPushButton field = new PDPushButton(form);
+            assertEquals(
+                    GeneralFormFieldTypeSupport.BUTTON,
+                    GeneralFormFieldTypeSupport.forField(field));
+        }
+    }
+
+    @Test
+    void createField_text_returnsPDTextField() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTerminalField field = GeneralFormFieldTypeSupport.TEXT.createField(form);
+            assertInstanceOf(PDTextField.class, field);
+        }
+    }
+
+    @Test
+    void createField_checkbox_returnsPDCheckBox() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTerminalField field = GeneralFormFieldTypeSupport.CHECKBOX.createField(form);
+            assertInstanceOf(PDCheckBox.class, field);
+        }
+    }
+
+    @Test
+    void createField_signature_returnsPDSignatureField() throws Exception {
+        try (PDDocument doc = new PDDocument()) {
+            PDAcroForm form = new PDAcroForm(doc);
+            PDTerminalField field = GeneralFormFieldTypeSupport.SIGNATURE.createField(form);
+            assertInstanceOf(PDSignatureField.class, field);
+        }
+    }
+
+    @Test
+    void typeName_returnsExpectedValues() {
+        assertEquals("text", GeneralFormFieldTypeSupport.TEXT.typeName());
+        assertEquals("checkbox", GeneralFormFieldTypeSupport.CHECKBOX.typeName());
+        assertEquals("radio", GeneralFormFieldTypeSupport.RADIO.typeName());
+        assertEquals("combobox", GeneralFormFieldTypeSupport.COMBOBOX.typeName());
+        assertEquals("listbox", GeneralFormFieldTypeSupport.LISTBOX.typeName());
+        assertEquals("signature", GeneralFormFieldTypeSupport.SIGNATURE.typeName());
+        assertEquals("button", GeneralFormFieldTypeSupport.BUTTON.typeName());
+    }
+
+    @Test
+    void fallbackWidgetName_returnsExpectedValues() {
+        assertEquals("textField", GeneralFormFieldTypeSupport.TEXT.fallbackWidgetName());
+        assertEquals("checkBox", GeneralFormFieldTypeSupport.CHECKBOX.fallbackWidgetName());
+        assertEquals("radioButton", GeneralFormFieldTypeSupport.RADIO.fallbackWidgetName());
+        assertEquals("comboBox", GeneralFormFieldTypeSupport.COMBOBOX.fallbackWidgetName());
+        assertEquals("listBox", GeneralFormFieldTypeSupport.LISTBOX.fallbackWidgetName());
+        assertEquals("signature", GeneralFormFieldTypeSupport.SIGNATURE.fallbackWidgetName());
+        assertEquals("pushButton", GeneralFormFieldTypeSupport.BUTTON.fallbackWidgetName());
+    }
+}
@@ -2,79 +2,110 @@ package stirling.software.common.util;

 import static org.junit.jupiter.api.Assertions.*;

-import java.awt.*;
+import java.awt.Color;
+import java.awt.Graphics2D;
 import java.awt.image.BufferedImage;
+import java.awt.image.DataBufferByte;
+import java.awt.image.DataBufferInt;

 import org.junit.jupiter.api.Test;

-public class ImageProcessingUtilsTest {
+class ImageProcessingUtilsTest {

-    private static void fillImageWithColor(BufferedImage image) {
-        for (int y = 0; y < image.getHeight(); y++) {
-            for (int x = 0; x < image.getWidth(); x++) {
-                image.setRGB(x, y, Color.RED.getRGB());
-            }
-        }
+    @Test
+    void convertColorType_greyscale_returnsGrayscaleImage() {
+        BufferedImage source = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.convertColorType(source, "greyscale");
+        assertEquals(BufferedImage.TYPE_BYTE_GRAY, result.getType());
+        assertEquals(10, result.getWidth());
+        assertEquals(10, result.getHeight());
    }

    @Test
-    void testConvertColorTypeToGreyscale() {
-        BufferedImage sourceImage = new BufferedImage(100, 100, BufferedImage.TYPE_INT_RGB);
-        fillImageWithColor(sourceImage);
-
-        BufferedImage convertedImage =
-                ImageProcessingUtils.convertColorType(sourceImage, "greyscale");
-
-        assertNotNull(convertedImage);
-        assertEquals(BufferedImage.TYPE_BYTE_GRAY, convertedImage.getType());
-        assertEquals(sourceImage.getWidth(), convertedImage.getWidth());
-        assertEquals(sourceImage.getHeight(), convertedImage.getHeight());
-
-        // Check if a pixel is correctly converted to greyscale
-        Color grey = new Color(convertedImage.getRGB(0, 0));
-        assertEquals(grey.getRed(), grey.getGreen());
-        assertEquals(grey.getGreen(), grey.getBlue());
+    void convertColorType_blackwhite_returnsBinaryImage() {
+        BufferedImage source = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.convertColorType(source, "blackwhite");
+        assertEquals(BufferedImage.TYPE_BYTE_BINARY, result.getType());
    }

    @Test
-    void testConvertColorTypeToBlackWhite() {
-        BufferedImage sourceImage = new BufferedImage(100, 100, BufferedImage.TYPE_INT_RGB);
-        fillImageWithColor(sourceImage);
-
-        BufferedImage convertedImage =
-                ImageProcessingUtils.convertColorType(sourceImage, "blackwhite");
-
-        assertNotNull(convertedImage);
-        assertEquals(BufferedImage.TYPE_BYTE_BINARY, convertedImage.getType());
-        assertEquals(sourceImage.getWidth(), convertedImage.getWidth());
-        assertEquals(sourceImage.getHeight(), convertedImage.getHeight());
-
-        // Check if a pixel is converted correctly (binary image will be either black or white)
-        int rgb = convertedImage.getRGB(0, 0);
-        assertTrue(rgb == Color.BLACK.getRGB() || rgb == Color.WHITE.getRGB());
+    void convertColorType_fullColor_returnsSameImage() {
+        BufferedImage source = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.convertColorType(source, "fullcolor");
+        assertSame(source, result);
    }

    @Test
-    void testConvertColorTypeToFullColor() {
-        BufferedImage sourceImage = new BufferedImage(100, 100, BufferedImage.TYPE_INT_RGB);
-        fillImageWithColor(sourceImage);
-
-        BufferedImage convertedImage =
-                ImageProcessingUtils.convertColorType(sourceImage, "fullcolor");
-
-        assertNotNull(convertedImage);
-        assertEquals(sourceImage, convertedImage);
+    void convertColorType_unknownType_returnsSameImage() {
+        BufferedImage source = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.convertColorType(source, "something_else");
+        assertSame(source, result);
    }

    @Test
-    void testConvertColorTypeInvalid() {
-        BufferedImage sourceImage = new BufferedImage(100, 100, BufferedImage.TYPE_INT_RGB);
-        fillImageWithColor(sourceImage);
+    void getImageData_byteBuffer_returnsCorrectData() {
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_BYTE_GRAY);
+        byte[] data = ImageProcessingUtils.getImageData(image);
+        assertNotNull(data);
+        assertTrue(data instanceof byte[]);
+        // TYPE_BYTE_GRAY uses DataBufferByte
+        assertTrue(image.getRaster().getDataBuffer() instanceof DataBufferByte);
+    }

-        BufferedImage convertedImage =
-                ImageProcessingUtils.convertColorType(sourceImage, "invalidtype");
+    @Test
+    void getImageData_intBuffer_returnsCorrectLength() {
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_INT_RGB);
+        // TYPE_INT_RGB uses DataBufferInt
+        assertTrue(image.getRaster().getDataBuffer() instanceof DataBufferInt);
+        byte[] data = ImageProcessingUtils.getImageData(image);
+        assertNotNull(data);
+        // 2x2 pixels, 4 bytes per int
+        assertEquals(2 * 2 * 4, data.length);
+    }

-        assertNotNull(convertedImage);
-        assertEquals(sourceImage, convertedImage);
+    @Test
+    void getImageData_ushortBuffer_returnsRGBData() {
+        // TYPE_USHORT_GRAY uses DataBufferUShort which hits the else branch
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_USHORT_GRAY);
+        byte[] data = ImageProcessingUtils.getImageData(image);
+        assertNotNull(data);
+        // 2x2 pixels, 3 bytes per pixel (RGB)
+        assertEquals(2 * 2 * 3, data.length);
+    }
+
+    @Test
+    void applyOrientation_zeroRotation_returnsSameImage() {
+        BufferedImage image = new BufferedImage(10, 20, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.applyOrientation(image, 0);
+        assertSame(image, result);
+    }
+
+    @Test
+    void applyOrientation_90degrees_returnsRotatedImage() {
+        BufferedImage image = new BufferedImage(10, 20, BufferedImage.TYPE_INT_RGB);
+        Graphics2D g = image.createGraphics();
+        g.setColor(Color.RED);
+        g.fillRect(0, 0, 10, 20);
+        g.dispose();
+
+        BufferedImage result = ImageProcessingUtils.applyOrientation(image, 90);
+        assertNotNull(result);
+        // The rotated image should have non-zero dimensions
+        assertTrue(result.getWidth() > 0);
+        assertTrue(result.getHeight() > 0);
+    }
+
+    @Test
+    void applyOrientation_180degrees_returnsRotatedImage() {
+        BufferedImage image = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.applyOrientation(image, 180);
+        assertNotNull(result);
+    }
+
+    @Test
+    void applyOrientation_270degrees_returnsRotatedImage() {
+        BufferedImage image = new BufferedImage(10, 20, BufferedImage.TYPE_INT_RGB);
+        BufferedImage result = ImageProcessingUtils.applyOrientation(image, 270);
+        assertNotNull(result);
    }
 }
@@ -0,0 +1,49 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+
+class JarPathUtilTest {
+
+    @Test
+    void currentJar_notRunningFromJar_returnsNull() {
+        // When running tests from IDE/Gradle, we are not in a JAR
+        Path result = JarPathUtil.currentJar();
+        assertNull(result, "Should return null when not running from a JAR file");
+    }
+
+    @Test
+    void restartHelperJar_notFound_returnsNull() {
+        // Since we're not running from JAR and restart-helper.jar likely doesn't exist
+        Path result = JarPathUtil.restartHelperJar();
+        assertNull(result, "Should return null when restart-helper.jar is not found");
+    }
+
+    @Test
+    void javaExecutable_returnsNonNullPath() {
+        String result = JarPathUtil.javaExecutable();
+        assertNotNull(result);
+        assertTrue(result.contains("java"), "Should contain 'java' in the path");
+        assertTrue(result.contains("bin"), "Should contain 'bin' in the path");
+    }
+
+    @Test
+    void javaExecutable_containsJavaHome() {
+        String javaHome = System.getProperty("java.home");
+        String result = JarPathUtil.javaExecutable();
+        assertTrue(result.startsWith(javaHome), "Should start with java.home system property");
+    }
+
+    @Test
+    void javaExecutable_windowsHasExeExtension() {
+        String result = JarPathUtil.javaExecutable();
+        if (System.getProperty("os.name").toLowerCase().contains("win")) {
+            assertTrue(result.endsWith(".exe"), "On Windows, should end with .exe");
+        } else {
+            assertFalse(result.endsWith(".exe"), "On non-Windows, should not end with .exe");
+        }
+    }
+}
@@ -0,0 +1,62 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class JobContextTest {
+
+    @AfterEach
+    void cleanup() {
+        JobContext.clear();
+    }
+
+    @Test
+    @DisplayName("should return null when no job ID is set")
+    void returnsNullByDefault() {
+        assertNull(JobContext.getJobId());
+    }
+
+    @Test
+    @DisplayName("should store and retrieve job ID")
+    void setAndGet() {
+        JobContext.setJobId("job-123");
+        assertEquals("job-123", JobContext.getJobId());
+    }
+
+    @Test
+    @DisplayName("should clear job ID")
+    void clearJobId() {
+        JobContext.setJobId("job-456");
+        JobContext.clear();
+        assertNull(JobContext.getJobId());
+    }
+
+    @Test
+    @DisplayName("should isolate job IDs between threads")
+    void threadIsolation() throws Exception {
+        JobContext.setJobId("main-job");
+
+        Thread other =
+                new Thread(
+                        () -> {
+                            assertNull(JobContext.getJobId());
+                            JobContext.setJobId("other-job");
+                            assertEquals("other-job", JobContext.getJobId());
+                        });
+        other.start();
+        other.join();
+
+        assertEquals("main-job", JobContext.getJobId());
+    }
+
+    @Test
+    @DisplayName("should allow overwriting job ID")
+    void overwriteJobId() {
+        JobContext.setJobId("first");
+        JobContext.setJobId("second");
+        assertEquals("second", JobContext.getJobId());
+    }
+}
@@ -0,0 +1,95 @@
+package stirling.software.common.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+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.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import stirling.software.common.service.CustomPDFDocumentFactory;
+
+class PDFServiceTest {
+
+    private PDFService pdfService;
+    private CustomPDFDocumentFactory mockFactory;
+    private final List<PDDocument> documentsToClose = new ArrayList<>();
+
+    @BeforeEach
+    void setUp() {
+        mockFactory = mock(CustomPDFDocumentFactory.class);
+        pdfService = new PDFService(mockFactory);
+    }
+
+    @AfterEach
+    void tearDown() throws IOException {
+        for (PDDocument doc : documentsToClose) {
+            try {
+                doc.close();
+            } catch (Exception ignored) {
+            }
+        }
+    }
+
+    private PDDocument createDocWithPages(int pageCount) {
+        PDDocument doc = new PDDocument();
+        for (int i = 0; i < pageCount; i++) {
+            doc.addPage(new PDPage());
+        }
+        documentsToClose.add(doc);
+        return doc;
+    }
+
+    @Test
+    void mergeDocuments_twoDocuments_mergesPages() throws IOException {
+        PDDocument merged = new PDDocument();
+        documentsToClose.add(merged);
+        when(mockFactory.createNewDocument()).thenReturn(merged);
+
+        PDDocument doc1 = createDocWithPages(2);
+        PDDocument doc2 = createDocWithPages(3);
+
+        PDDocument result = pdfService.mergeDocuments(List.of(doc1, doc2));
+        assertEquals(5, result.getNumberOfPages());
+    }
+
+    @Test
+    void mergeDocuments_emptyList_returnsEmptyDocument() throws IOException {
+        PDDocument merged = new PDDocument();
+        documentsToClose.add(merged);
+        when(mockFactory.createNewDocument()).thenReturn(merged);
+
+        PDDocument result = pdfService.mergeDocuments(List.of());
+        assertEquals(0, result.getNumberOfPages());
+    }
+
+    @Test
+    void mergeDocuments_singleDocument_returnsSamePages() throws IOException {
+        PDDocument merged = new PDDocument();
+        documentsToClose.add(merged);
+        when(mockFactory.createNewDocument()).thenReturn(merged);
+
+        PDDocument doc1 = createDocWithPages(4);
+
+        PDDocument result = pdfService.mergeDocuments(List.of(doc1));
+        assertEquals(4, result.getNumberOfPages());
+    }
+
+    @Test
+    void mergeDocuments_factoryCalled() throws IOException {
+        PDDocument merged = new PDDocument();
+        documentsToClose.add(merged);
+        when(mockFactory.createNewDocument()).thenReturn(merged);
+
+        PDDocument doc1 = createDocWithPages(1);
+
+        pdfService.mergeDocuments(List.of(doc1));
+        verify(mockFactory).createNewDocument();
+    }
+}
--- a/Show More
+++ b/Show More