Stirling 2.0 (#3928)

# Description of Changes

<!--

File context for managing files between tools and views
Optimisation for large files
Updated Split to work with new file system and match Matts stepped
design closer

-->

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

---------

Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>

.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(mkdir:*)",
       "Bash(./gradlew:*)",
       "Bash(grep:*)",
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(find:*)"
     ],
     "deny": []
   }

.github/labeler-config-srvaroa.yml

@@ -115,7 +115,7 @@ labels:
       - '.editorconfig'
       - '.pre-commit-config'
       - '.github/workflows/pre_commit.yml'
-      - 'HowToAddNewLanguage.md'
+      - 'devGuide/.*'
 
   - label: 'Test'
     files:

.github/pull_request_template.md

@@ -1,5 +1,6 @@
 # Description of Changes
 
+<!--
 Please provide a summary of the changes, including:
 
 - What was changed
@@ -7,6 +8,7 @@ Please provide a summary of the changes, including:
 - Any challenges encountered
 
 Closes #(issue_number)
+-->
 
 ---
 
@@ -15,15 +17,15 @@ Closes #(issue_number)
 ### General
 
 - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
-- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable)
-- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable)
+- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable)
+- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable)
 - [ ] I have performed a self-review of my own code
 - [ ] My changes generate no new warnings
 
 ### Documentation
 
 - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed)
-- [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only)
+- [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only)
 
 ### UI Changes (if applicable)
 
@@ -31,4 +33,4 @@ Closes #(issue_number)
 
 ### Testing (if applicable)
 
-- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details.
+- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details.

.github/scripts/requirements_pre_commit.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile --generate-hashes --output-file='.github\scripts\requirements_pre_commit.txt' '.github\scripts\requirements_pre_commit.in'
+#    pip-compile --generate-hashes --output-file='.github\scripts\requirements_pre_commit.txt' --strip-extras '.github\scripts\requirements_pre_commit.in'
 #
 cfgv==3.4.0 \
     --hash=sha256:b7265b1f29fd3316bfcd2b330d63d024f2bfd8bcb8b0272f8e19a504856c48f9 \
@@ -12,25 +12,25 @@ distlib==0.3.9 \
     --hash=sha256:47f8c22fd27c27e25a65601af709b38e4f0a45ea4fc2e710f65755fa8caaaf87 \
     --hash=sha256:a60f20dea646b8a33f3e7772f74dc0b2d0772d2837ee1342a00645c81edf9403
     # via virtualenv
-filelock==3.16.1 \
-    --hash=sha256:2082e5703d51fbf98ea75855d9d5527e33d8ff23099bec374a134febee6946b0 \
-    --hash=sha256:c249fbfcd5db47e5e2d6d62198e565475ee65e4831e2561c8e313fa7eb961435
+filelock==3.18.0 \
+    --hash=sha256:adbc88eabb99d2fec8c9c1b229b171f18afa655400173ddc653d5d01501fb9f2 \
+    --hash=sha256:c401f4f8377c4464e6db25fff06205fd89bdd83b65eb0488ed1b160f780e21de
     # via virtualenv
-identify==2.6.5 \
-    --hash=sha256:14181a47091eb75b337af4c23078c9d09225cd4c48929f521f3bf16b09d02566 \
-    --hash=sha256:c10b33f250e5bba374fae86fb57f3adcebf1161bce7cdf92031915fd480c13bc
+identify==2.6.12 \
+    --hash=sha256:ad9672d5a72e0d2ff7c5c8809b62dfa60458626352fb0eb7b55e69bdc45334a2 \
+    --hash=sha256:d8de45749f1efb108badef65ee8386f0f7bb19a7f26185f74de6367bffbaf0e6
     # via pre-commit
 nodeenv==1.9.1 \
     --hash=sha256:6ec12890a2dab7946721edbfbcd91f3319c6ccc9aec47be7c7e6b7011ee6645f \
     --hash=sha256:ba11c9782d29c27c70ffbdda2d7415098754709be8a7056d79a737cd901155c9
     # via pre-commit
-platformdirs==4.3.6 \
-    --hash=sha256:357fb2acbc885b0419afd3ce3ed34564c13c9b95c89360cd9563f73aa5e2b907 \
-    --hash=sha256:73e575e1408ab8103900836b97580d5307456908a03e92031bab39e4554cc3fb
+platformdirs==4.3.8 \
+    --hash=sha256:3d512d96e16bcb959a814c9f348431070822a6496326a4be0911c40b5a74c2bc \
+    --hash=sha256:ff7059bb7eb1179e2685604f4aaf157cfd9535242bd23742eadc3c13542139b4
     # via virtualenv
-pre-commit==4.0.1 \
-    --hash=sha256:80905ac375958c0444c65e9cebebd948b3cdb518f335a091a670a89d652139d2 \
-    --hash=sha256:efde913840816312445dc98787724647c65473daefe420785f885e8ed9a06878
+pre-commit==4.2.0 \
+    --hash=sha256:601283b9757afd87d40c4c4a9b2b5de9637a8ea02eaff7adc2d0fb4e04841146 \
+    --hash=sha256:a009ca7205f1eb497d10b845e52c838a98b6cdd2102a6c8e4540e94ee75c58bd
     # via -r .github\scripts\requirements_pre_commit.in
 pyyaml==6.0.2 \
     --hash=sha256:01179a4a8559ab5de078078f37e5c1a30d76bb88519906844fd7bdea1b7729ff \
@@ -87,7 +87,7 @@ pyyaml==6.0.2 \
     --hash=sha256:f753120cb8181e736c57ef7636e83f31b9c0d1722c516f7e86cf15b7aa57ff12 \
     --hash=sha256:ff3824dc5261f50c9b0dfb3be22b4567a6f938ccce4587b38952d85fd9e9afe4
     # via pre-commit
-virtualenv==20.28.1 \
-    --hash=sha256:412773c85d4dab0409b83ec36f7a6499e72eaf08c80e81e9576bca61831c71cb \
-    --hash=sha256:5d34ab240fdb5d21549b76f9e8ff3af28252f5499fb6d6f031adac4e5a8c5329
+virtualenv==20.31.2 \
+    --hash=sha256:36efd0d9650ee985f0cad72065001e66d49a6f24eb44d98980f630686243cf11 \
+    --hash=sha256:e10c0a9d02835e592521be48b332b6caee6887f332c111aa79a09b9e79efc2af
     # via pre-commit

.github/scripts/requirements_sync_readme.txt

@@ -2,9 +2,9 @@
 # This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile --generate-hashes --output-file='.github\scripts\requirements_sync_readme.txt' '.github\scripts\requirements_sync_readme.in'
+#    pip-compile --generate-hashes --output-file='.github\scripts\requirements_sync_readme.txt' --strip-extras '.github\scripts\requirements_sync_readme.in'
 #
-tomlkit==0.13.2 \
-    --hash=sha256:7a974427f6e119197f670fbbbeae7bef749a6c14e793db934baefc1b5f03efde \
-    --hash=sha256:fff5fe59a87295b278abd31bec92c15d9bc4a06885ab12bcea52c71119392e79
+tomlkit==0.13.3 \
+    --hash=sha256:430cf247ee57df2b94ee3fbe588e71d362a941ebb545dec29b53961d61add2a1 \
+    --hash=sha256:c89c649d79ee40629a9fda55f8ace8c6a1b42deb912b2a8fd8d942ddadb606b0
     # via -r .github\scripts\requirements_sync_readme.in

.github/workflows/PR-Auto-Deploy-V2.yml

@@ -0,0 +1,327 @@
+name: Auto PR V2 Deployment
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  check-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      should_deploy: ${{ steps.check-conditions.outputs.should_deploy }}
+      pr_number: ${{ github.event.number }}
+      pr_repository: ${{ steps.get-pr-info.outputs.repository }}
+      pr_ref: ${{ steps.get-pr-info.outputs.ref }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        with:
+          egress-policy: audit
+
+      - name: Check deployment conditions
+        id: check-conditions
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          echo "PR Title: $PR_TITLE"
+          echo "PR Author: $PR_AUTHOR"
+          echo "PR Branch: $PR_BRANCH"
+          echo "PR Base Branch: ${{ github.event.pull_request.base.ref }}"
+          
+          # Define authorized users
+          authorized_users=(
+            "Frooodle"
+            "sf298"
+            "Ludy87"
+            "LaserKaspar"
+            "sbplat"
+            "reecebrowne"
+            "DarioGii"
+            "ConnorYoh"
+          )
+          
+          # Check if author is in the authorized list
+          is_authorized=false
+          for user in "${authorized_users[@]}"; do
+            if [[ "$PR_AUTHOR" == "$user" ]]; then
+              is_authorized=true
+              break
+            fi
+          done
+          
+          # If PR is targeting feature/react-overhaul and user is authorized, deploy unconditionally
+          PR_BASE_BRANCH="${{ github.event.pull_request.base.ref }}"
+          if [[ "$PR_BASE_BRANCH" == "feature/react-overhaul" && "$is_authorized" == "true" ]]; then
+            echo "✅ Deployment forced: PR targets feature/react-overhaul and author is authorized."
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          
+          # Otherwise, continue with original keyword checks
+          has_v2_keyword=false
+          if [[ "$PR_TITLE" =~ [Vv]2 ]] || [[ "$PR_TITLE" =~ [Vv]ersion.?2 ]] || [[ "$PR_TITLE" =~ [Vv]ersion.?[Tt]wo ]]; then
+            has_v2_keyword=true
+          fi
+          
+          has_branch_keyword=false
+          if [[ "$PR_BRANCH" =~ [Vv]2 ]] || [[ "$PR_BRANCH" =~ [Rr]eact ]]; then
+            has_branch_keyword=true
+          fi
+          
+          if [[ "$is_authorized" == "true" && ( "$has_v2_keyword" == "true" || "$has_branch_keyword" == "true" ) ]]; then
+            echo "✅ Deployment conditions met"
+            echo "should_deploy=true" >> $GITHUB_OUTPUT
+          else
+            echo "❌ Deployment conditions not met"
+            echo "  - Authorized user: $is_authorized"
+            echo "  - Has V2 keyword in title: $has_v2_keyword"
+            echo "  - Has V2/React keyword in branch: $has_branch_keyword"
+            echo "should_deploy=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Get PR repository and ref
+        id: get-pr-info
+        if: steps.check-conditions.outputs.should_deploy == 'true'
+        run: |
+          # For forks, use the full repository name, for internal PRs use the current repo
+          if [[ "${{ github.event.pull_request.head.repo.fork }}" == "true" ]]; then
+            repository="${{ github.event.pull_request.head.repo.full_name }}"
+          else
+            repository="${{ github.repository }}"
+          fi
+          
+          echo "repository=$repository" >> $GITHUB_OUTPUT
+          echo "ref=${{ github.event.pull_request.head.ref }}" >> $GITHUB_OUTPUT
+
+  deploy-v2-pr:
+    needs: check-pr
+    runs-on: ubuntu-latest
+    if: needs.check-pr.outputs.should_deploy == 'true'
+    # Concurrency control - only one deployment per PR at a time
+    concurrency:
+      group: v2-deploy-pr-${{ needs.check-pr.outputs.pr_number }}
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout main repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: ${{ github.repository }}
+          ref: main
+
+      - name: Setup GitHub App Bot
+        if: github.actor != 'dependabot[bot]'
+        id: setup-bot
+        uses: ./.github/actions/setup-bot
+        continue-on-error: true
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
+      - name: Add deployment started comment
+        id: deployment-started
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          github-token: ${{ steps.setup-bot.outputs.token }}
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = ${{ needs.check-pr.outputs.pr_number }};
+            
+            // Delete previous V2 deployment comments to avoid clutter
+            const { data: comments } = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number: prNumber,
+              per_page: 100
+            });
+            
+            const v2Comments = comments.filter(comment => 
+              comment.body.includes('🚀 **Auto-deploying V2 version**') ||
+              comment.body.includes('## 🚀 V2 Auto-Deployment Complete!') ||
+              comment.body.includes('❌ **V2 Auto-deployment failed**')
+            );
+            
+            for (const comment of v2Comments) {
+              console.log(`Deleting old V2 comment: ${comment.id}`);
+              await github.rest.issues.deleteComment({
+                owner,
+                repo,
+                comment_id: comment.id
+              });
+            }
+            
+            // Create new deployment started comment
+            const { data: newComment } = await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: prNumber,
+              body: `🚀 **Auto-deploying V2 version** for PR #${prNumber}...\n\n_This is an automated deployment triggered by V2/version2 keywords in the PR title or V2/React keywords in the branch name._\n\n⚠️ **Note:** If new commits are pushed during deployment, this build will be cancelled and replaced with the latest version.`
+            });
+            
+            return newComment.id;
+
+      - name: Checkout PR
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: ${{ needs.check-pr.outputs.pr_repository }}
+          ref: ${{ needs.check-pr.outputs.pr_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up JDK
+        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        with:
+          java-version: "17"
+          distribution: "temurin"
+
+      - name: Build backend
+        run: |
+          export DISABLE_ADDITIONAL_FEATURES=true
+          ./gradlew clean build
+        env:
+          STIRLING_PDF_DESKTOP_UI: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - name: Get version number
+        id: versionNumber
+        run: |
+          VERSION=$(grep "^version =" build.gradle | awk -F'"' '{print $2}')
+          echo "versionNumber=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_API }}
+
+      - name: Build and push V2 monolith image
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        with:
+          context: .
+          file: ./docker/monolith/Dockerfile
+          push: true
+          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-pr-${{ needs.check-pr.outputs.pr_number }}
+          build-args: VERSION_TAG=v2-alpha
+          platforms: linux/amd64
+
+      - name: Set up SSH
+        run: |
+          mkdir -p ~/.ssh/
+          echo "${{ secrets.VPS_SSH_KEY }}" > ../private.key
+          sudo chmod 600 ../private.key
+
+      - name: Deploy V2 to VPS
+        id: deploy
+        run: |
+          # Use same port strategy as regular PRs - just the PR number
+          V2_PORT=${{ needs.check-pr.outputs.pr_number }}
+          
+          # Create docker-compose for V2 monolith
+          cat > docker-compose.yml << EOF
+          version: '3.3'
+          services:
+            stirling-pdf-v2:
+              container_name: stirling-pdf-v2-pr-${{ needs.check-pr.outputs.pr_number }}
+              image: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-pr-${{ needs.check-pr.outputs.pr_number }}
+              ports:
+                - "${V2_PORT}:80"      # Frontend port (same as regular PRs)
+              volumes:
+                - /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/data:/usr/share/tessdata:rw
+                - /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/config:/configs:rw
+                - /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/logs:/logs:rw
+              environment:
+                DISABLE_ADDITIONAL_FEATURES: "true"
+                SECURITY_ENABLELOGIN: "false"
+                SYSTEM_DEFAULTLOCALE: en-GB
+                UI_APPNAME: "Stirling-PDF V2 PR#${{ needs.check-pr.outputs.pr_number }}"
+                UI_HOMEDESCRIPTION: "V2 PR#${{ needs.check-pr.outputs.pr_number }} - Frontend/Backend Split Architecture"
+                UI_APPNAMENAVBAR: "V2 PR#${{ needs.check-pr.outputs.pr_number }}"
+                SYSTEM_MAXFILESIZE: "100"
+                METRICS_ENABLED: "true"
+                SYSTEM_GOOGLEVISIBILITY: "false"
+              restart: on-failure:5
+          EOF
+
+          # Deploy to VPS
+          scp -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null docker-compose.yml ${{ secrets.VPS_USERNAME }}@${{ secrets.VPS_HOST }}:/tmp/docker-compose-v2.yml
+
+          ssh -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -T ${{ secrets.VPS_USERNAME }}@${{ secrets.VPS_HOST }} << ENDSSH
+            # Create V2 PR-specific directories
+            mkdir -p /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/{data,config,logs}
+
+            # Move docker-compose file to correct location
+            mv /tmp/docker-compose-v2.yml /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/docker-compose.yml
+
+            # Stop any existing container and clean up
+            cd /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}
+            docker-compose down --remove-orphans 2>/dev/null || true
+            
+            # Start the new container
+            docker-compose pull
+            docker-compose up -d
+            
+            # Clean up unused Docker resources to save space
+            docker system prune -af --volumes
+          ENDSSH
+
+          # Set port for output
+          echo "v2_port=${V2_PORT}" >> $GITHUB_OUTPUT
+
+      - name: Post V2 deployment URL to PR
+        if: success()
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          github-token: ${{ steps.setup-bot.outputs.token }}
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = ${{ needs.check-pr.outputs.pr_number }};
+            const v2Port = ${{ steps.deploy.outputs.v2_port }};
+            
+            // Delete the "deploying..." comment since we're posting the final result
+            const deploymentStartedId = ${{ steps.deployment-started.outputs.result }};
+            if (deploymentStartedId) {
+              console.log(`Deleting deployment started comment: ${deploymentStartedId}`);
+              try {
+                await github.rest.issues.deleteComment({
+                  owner,
+                  repo,
+                  comment_id: deploymentStartedId
+                });
+              } catch (error) {
+                console.log(`Could not delete deployment started comment: ${error.message}`);
+              }
+            }
+            
+            const deploymentUrl = `http://${{ secrets.VPS_HOST }}:${v2Port}`;
+            
+            const commentBody = `## 🚀 V2 Auto-Deployment Complete!\n\n` +
+                              `Your V2 PR with the new frontend/backend split architecture has been deployed!\n\n` +
+                              `🔗 **V2 Test URL:** [${deploymentUrl}](${deploymentUrl})\n\n` +
+                              `_This deployment will be automatically cleaned up when the PR is closed._\n\n` +
+                              `🔄 **Auto-deployed** because PR title or branch name contains V2/version2/React keywords.`;
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: prNumber,
+              body: commentBody
+            });
+

.github/workflows/PR-Demo-Comment-with-react.yml

@@ -30,6 +30,7 @@ jobs:
         github.event.comment.user.login == 'sbplat' ||
         github.event.comment.user.login == 'reecebrowne' ||
         github.event.comment.user.login == 'DarioGii' ||
+        github.event.comment.user.login == 'EthanHealy01' ||
         github.event.comment.user.login == 'ConnorYoh'
       )
     outputs:
@@ -42,7 +43,7 @@ jobs:
       enable_enterprise: ${{ steps.check-pro-flag.outputs.enable_enterprise }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -149,7 +150,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/PR-Demo-cleanup.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/ai_pr_title_review.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/auto-labeler.yml

@@ -13,7 +13,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/auto-labelerV2.yml

@@ -13,7 +13,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/build.yml

@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -91,7 +91,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -135,7 +135,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/check_properties.yml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write # Allow writing to pull requests
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/dependency-review.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/licenses-update.yml

@@ -19,7 +19,7 @@ jobs:
       repository-projects: write # Required for enabling automerge
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/manage-label.yml

@@ -15,7 +15,7 @@ jobs:
       issues: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/multiOSReleases.yml

@@ -21,27 +21,31 @@ jobs:
       versionMac: ${{ steps.versionNumberMac.outputs.versionNumberMac }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      # Get version number
+      - name: Set up JDK
+        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+
+      # ✅ Get version from Gradle
       - name: Get version number
         id: versionNumber
         run: |
-          VERSION=$(grep "^version =" build.gradle | awk -F'"' '{print $2}')
+          VERSION=$(./gradlew printVersion --quiet | tail -1)
           echo "versionNumber=$VERSION" >> $GITHUB_OUTPUT
 
+      # ✅ Get Mac-specific version from Gradle
       - name: Get version number mac
         id: versionNumberMac
         run: |
-          VERSION=$(grep "^version =" build.gradle | awk -F'"' '{print $2}')
-          CURRENT_YEAR=$(date +'%Y')
-          IFS='.' read -r -a VERSION_PARTS <<< "$VERSION"
-          MAC_VERSION="$CURRENT_YEAR.${VERSION_PARTS[1]:-0}.${VERSION_PARTS[2]:-0}"
-          echo "versionNumberMac=$MAC_VERSION" >> $GITHUB_OUTPUT
+          VERSION_MAC=$(./gradlew printMacVersion --quiet | tail -1)
+          echo "versionNumberMac=$VERSION_MAC" >> $GITHUB_OUTPUT
 
   build-portable:
     needs: read_versions
@@ -56,7 +60,7 @@ jobs:
             file_suffix: ""
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -82,7 +86,7 @@ jobs:
         run: |
           mkdir ./binaries
           mv ./build/launch4j/Stirling-PDF.exe ./binaries/win-Stirling-PDF-portable-Server${{ matrix.file_suffix }}.exe
-          mv ./build/libs/Stirling-PDF-${{ needs.read_versions.outputs.version }}.jar ./binaries/Stirling-PDF${{ matrix.file_suffix }}.jar
+          mv ./stirling-pdf/build/libs/stirling-pdf-${{ needs.read_versions.outputs.version }}.jar ./binaries/Stirling-PDF${{ matrix.file_suffix }}.jar
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
@@ -106,7 +110,7 @@ jobs:
             file_suffix: ""
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -144,7 +148,7 @@ jobs:
       contents: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -234,7 +238,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -248,7 +252,7 @@ jobs:
 
       - name: Install Cosign
         if: matrix.os == 'windows-latest'
-        uses: sigstore/cosign-installer@fb28c2b6339dcd94da6e4cbcbc5e888961f6f8c3 # v3.9.0
+        uses: sigstore/cosign-installer@398d4b0eeef1380460a10c8013a76f728fb906ac # v3.9.1
 
       - name: Generate key pair
         if: matrix.os == 'windows-latest'
@@ -297,7 +301,7 @@ jobs:
       contents: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/pre_commit.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/push-docker.yml

@@ -18,7 +18,7 @@ jobs:
       id-token: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -42,7 +42,7 @@ jobs:
 
       - name: Install cosign
         if: github.ref == 'refs/heads/master'
-        uses: sigstore/cosign-installer@fb28c2b6339dcd94da6e4cbcbc5e888961f6f8c3 # v3.9.0
+        uses: sigstore/cosign-installer@398d4b0eeef1380460a10c8013a76f728fb906ac # v3.9.1
         with:
           cosign-release: "v2.4.1"
 
@@ -77,6 +77,7 @@ jobs:
       - name: Generate tags
         id: meta
         uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0
+        if: github.ref != 'refs/heads/main'
         with:
           images: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -86,11 +87,11 @@ jobs:
           tags: |
             type=raw,value=${{ steps.versionNumber.outputs.versionNumber }},enable=${{ github.ref == 'refs/heads/master' }}
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }}
-            type=raw,value=alpha,enable=${{ github.ref == 'refs/heads/main' }}
 
       - name: Build and push main Dockerfile
         id: build-push-regular
         uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        if: github.ref != 'refs/heads/main'
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: .
@@ -153,7 +154,6 @@ jobs:
       - name: Generate tags fat
         id: meta3
         uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0
-        if: github.ref != 'refs/heads/main'
         with:
           images: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -163,11 +163,11 @@ jobs:
           tags: |
             type=raw,value=${{ steps.versionNumber.outputs.versionNumber }}-fat,enable=${{ github.ref == 'refs/heads/master' }}
             type=raw,value=latest-fat,enable=${{ github.ref == 'refs/heads/master' }}
+            type=raw,value=alpha,enable=${{ github.ref == 'refs/heads/main' }}
 
       - name: Build and push main Dockerfile fat
         id: build-push-fat
         uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
-        if: github.ref != 'refs/heads/main'
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: .

.github/workflows/releaseArtifacts.yml

@@ -23,7 +23,7 @@ jobs:
       version: ${{ steps.versionNumber.outputs.versionNumber }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -83,7 +83,7 @@ jobs:
             file_suffix: ""
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -95,7 +95,7 @@ jobs:
         run: ls -R
 
       - name: Install Cosign
-        uses: sigstore/cosign-installer@fb28c2b6339dcd94da6e4cbcbc5e888961f6f8c3 # v3.9.0
+        uses: sigstore/cosign-installer@398d4b0eeef1380460a10c8013a76f728fb906ac # v3.9.1
 
       - name: Generate key pair
         run: cosign generate-key-pair
@@ -161,7 +161,7 @@ jobs:
             file_suffix: ""
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/scorecards.yml

@@ -34,7 +34,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -74,6 +74,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@ce28f5bb42b7a9f2c824e633a3f6ee835bab6858 # v3.29.0
+        uses: github/codeql-action/upload-sarif@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2
         with:
           sarif_file: results.sarif

.github/workflows/sonarqube.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/stale.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/swagger.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.github/workflows/sync_files.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -57,8 +57,8 @@ jobs:
 
       - name: Run git add
         run: |
-          git add README.md
-          git diff --staged --quiet || git commit -m ":memo: Sync README.md" || echo "No changes detected"
+          git add README.md scripts/ignore_translation.toml
+          git diff --staged --quiet || git commit -m ":memo: Sync README.md & scripts/ignore_translation.toml" || echo "No changes detected"
 
       - name: Create Pull Request
         if: always()

.github/workflows/testdriver.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -105,7 +105,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -134,7 +134,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 

.gitignore

@@ -27,6 +27,7 @@ clientWebUI/
 !cucumber/exampleFiles/
 !cucumber/exampleFiles/example_html.zip
 exampleYmlFiles/stirling/
+stirling/
 /testing/file_snapshots
 SwaggerDoc.json
 

CLAUDE.md

@@ -25,23 +25,54 @@ Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security featur
 - **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
 
-#### Tailwind CSS Setup (if not already installed)
-```bash
-cd frontend
-npm install -D tailwindcss postcss autoprefixer
-npx tailwindcss init -p
-```
+#### 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**: `src/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
+- **Pattern**: Follow `src/tools/Split.tsx` as reference implementation
+- **File Access**: Tools receive `selectedFiles` prop (computed from activeFiles based on user selection)
+- **File Selection**: Users select files in FileEditor (tool mode) → stored as IDs → computed to File objects for tools
+- **Integration**: All files are part of FileContext ecosystem - automatic memory management and operation tracking
+- **Parameters**: Tool parameter handling patterns still being standardized
+- **Preview Integration**: Tools can implement preview functionality (see Split tool's thumbnail preview)
 
 ## Architecture Overview
 
 ### Project Structure
 - **Backend**: Spring Boot application with Thymeleaf templating
-- **Frontend**: React-based SPA in `/frontend` directory (replacing legacy Thymeleaf templates)
-  - **Current Status**: Active development to replace Thymeleaf UI with modern React SPA
+- **Frontend**: React-based SPA in `/frontend` directory (Thymeleaf templates fully replaced)
   - **File Storage**: IndexedDB for client-side file persistence and thumbnails
   - **Internationalization**: JSON-based translations (converted from backend .properties)
-  - **URL Parameters**: Deep linking support for tool states and configurations
 - **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
@@ -59,9 +90,8 @@ npx tailwindcss init -p
 - **Pipeline System**: Automated PDF processing workflows via `PipelineController`
 - **Security Layer**: Authentication, authorization, and user management (when enabled)
 
-### Template System (Legacy + Modern)
-- **Legacy Thymeleaf Templates**: Located in `src/main/resources/templates/` (being phased out)
-- **Modern React Components**: Located in `frontend/src/components/` and `frontend/src/tools/`
+### Component Architecture
+- **React Components**: Located in `frontend/src/components/` and `frontend/src/tools/`
 - **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/public/` (modern)
 - **Internationalization**:
   - Backend: `messages_*.properties` files
@@ -91,13 +121,14 @@ npx tailwindcss init -p
    - 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 Migration Notes
+## Frontend Architecture Status
 
-- **Current Branch**: `feature/react-overhaul` - Active React SPA development
-- **Migration Status**: Core tools (Split, Merge, Compress) converted to React with URL parameter support
-- **File Management**: Implemented IndexedDB storage with thumbnail generation using PDF.js
-- **Tools Architecture**: Each tool receives `params` and `updateParams` for URL state synchronization
-- **Remaining Work**: Convert remaining Thymeleaf templates to React components
+- **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**: Standardized tool interface - see `src/tools/Split.tsx` as reference
+- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
+- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
 
 ## Important Notes
 
@@ -108,6 +139,11 @@ npx tailwindcss init -p
   - **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
+- **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 Split tool pattern (`src/tools/Split.tsx`)
+- **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)
 
 ## Communication Style
 - Be direct and to the point

CONTRIBUTING.md

@@ -25,7 +25,7 @@ Please make sure your Pull Request adheres to the following guidelines:
 
 ## Translations
 
-If you would like to add or modify a translation, please see [How to add new languages to Stirling-PDF](HowToAddNewLanguage.md). Also, please create a Pull Request so others can use it!
+If you would like to add or modify a translation, please see [How to add new languages to Stirling-PDF](devGuide/HowToAddNewLanguage.md). Also, please create a Pull Request so others can use it!
 
 ## Docs
 
@@ -37,7 +37,18 @@ First, make sure you've read the section [Pull Requests](#pull-requests).
 
 If, at any point in time, you have a question, please feel free to ask in the same issue thread or in our [Discord](https://discord.gg/FJUSXUSYec).
 
-Developers should review our [Developer Guide](DeveloperGuide.md)
+## Developer Documentation
+
+For technical guides, setup instructions, and development resources, please see our [Developer Documentation](devGuide/) which includes:
+
+- [Developer Guide](devGuide/DeveloperGuide.md) - Main setup and architecture guide
+- [Exception Handling Guide](devGuide/EXCEPTION_HANDLING_GUIDE.md) - Error handling patterns and i18n
+- [Translation Guide](devGuide/HowToAddNewLanguage.md) - Adding new languages
+- And more in the [devGuide folder](devGuide/)
+
+For configuration and usage guides, see:
+- [Database Guide](DATABASE.md) - Database setup and configuration
+- [OCR Guide](HowToUseOCR.md) - OCR setup and configuration
 
 ## License
 

Dockerfile.dev

@@ -1,60 +0,0 @@
-# dockerfile.dev
-
-# Basisimage: Gradle mit JDK 17 (Debian-basiert)
-FROM gradle:8.14-jdk17
-
-# Als Root-Benutzer arbeiten, um benötigte Pakete zu installieren
-USER root
-
-# Set GRADLE_HOME und füge Gradle zum PATH hinzu
-ENV GRADLE_HOME=/opt/gradle
-ENV PATH="$GRADLE_HOME/bin:$PATH"
-
-# Update und Installation zusätzlicher Pakete (Debian/Ubuntu-basiert)
-RUN apt-get update && apt-get install -y \
-  sudo \
-  libreoffice \
-  poppler-utils \
-  qpdf \
-# settings.yml | tessdataDir: /usr/share/tesseract-ocr/5/tessdata
-  tesseract-ocr \
-  tesseract-ocr-eng \
-  fonts-terminus fonts-dejavu fonts-font-awesome fonts-noto fonts-noto-core fonts-noto-cjk fonts-noto-extra fonts-liberation fonts-linuxlibertine \
-  python3-uno \
-  python3-venv \
-# ss -tln
-  iproute2 \
-  && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# Setze die Environment Variable für setuptools
-ENV SETUPTOOLS_USE_DISTUTILS=local \
-    STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
-    TMPDIR=/tmp/stirling-pdf \
-    TEMP=/tmp/stirling-pdf \
-    TMP=/tmp/stirling-pdf
-
-# Installation der benötigten Python-Pakete
-RUN python3 -m venv --system-site-packages /opt/venv \
-  && . /opt/venv/bin/activate \
-  && pip install --upgrade pip setuptools \
-  && pip install --no-cache-dir WeasyPrint pdf2image pillow unoserver opencv-python-headless pre-commit
-
-# Füge den venv-Pfad zur globalen PATH-Variable hinzu, damit die Tools verfügbar sind
-ENV PATH="/opt/venv/bin:$PATH"
-
-COPY . /workspace
-
-RUN mkdir -p /tmp/stirling-pdf \
-  && adduser --disabled-password --gecos '' devuser \
-  && chown -R devuser:devuser /home/devuser /workspace /tmp/stirling-pdf
-RUN echo "devuser ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/devuser \
-  && chmod 0440 /etc/sudoers.d/devuser
-
-# Setze das Arbeitsverzeichnis (wird später per Bind-Mount überschrieben)
-WORKDIR /workspace
-
-RUN chmod +x /workspace/.devcontainer/git-init.sh
-RUN sudo chmod +x /workspace/.devcontainer/init-setup.sh
-
-# Wechsel zum Nicht‑Root Benutzer
-USER devuser

README.md

@@ -29,7 +29,7 @@ All documentation available at [https://docs.stirlingpdf.com/](https://docs.stir
 - API for integration with external scripts
 - Optional Login and Authentication support (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/System%20and%20Security) for documentation)
 - Database Backup and Import (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/DATABASE) for documentation)
-- Enterprise features like SSO see [here](https://docs.stirlingpdf.com/Enterprise%20Edition)
+- Enterprise features like SSO (see [here](https://docs.stirlingpdf.com/Advanced%20Configuration/Single%20Sign-On%20Configuration) for documentation)
 
 ## PDF Features
 
@@ -116,47 +116,47 @@ Stirling-PDF currently supports 40 languages!
 
 | Language                                     | Progress                               |
 | -------------------------------------------- | -------------------------------------- |
-| Arabic (العربية) (ar_AR)                        | ![65%](https://geps.dev/progress/65)   |
-| Azerbaijani (Azərbaycan Dili) (az_AZ)        | ![65%](https://geps.dev/progress/65)   |
-| Basque (Euskara) (eu_ES)                     | ![38%](https://geps.dev/progress/38)   |
-| Bulgarian (Български) (bg_BG)                | ![72%](https://geps.dev/progress/72)   |
-| Catalan (Català) (ca_CA)                     | ![71%](https://geps.dev/progress/71)   |
-| Croatian (Hrvatski) (hr_HR)                  | ![64%](https://geps.dev/progress/64)   |
-| Czech (Česky) (cs_CZ)                        | ![74%](https://geps.dev/progress/74)   |
-| Danish (Dansk) (da_DK)                       | ![65%](https://geps.dev/progress/65)   |
-| Dutch (Nederlands) (nl_NL)                   | ![63%](https://geps.dev/progress/63)   |
+| Arabic (العربية) (ar_AR)                        | ![63%](https://geps.dev/progress/63)   |
+| Azerbaijani (Azərbaycan Dili) (az_AZ)        | ![63%](https://geps.dev/progress/63)   |
+| Basque (Euskara) (eu_ES)                     | ![37%](https://geps.dev/progress/37)   |
+| Bulgarian (Български) (bg_BG)                | ![70%](https://geps.dev/progress/70)   |
+| Catalan (Català) (ca_CA)                     | ![69%](https://geps.dev/progress/69)   |
+| Croatian (Hrvatski) (hr_HR)                  | ![62%](https://geps.dev/progress/62)   |
+| Czech (Česky) (cs_CZ)                        | ![71%](https://geps.dev/progress/71)   |
+| Danish (Dansk) (da_DK)                       | ![63%](https://geps.dev/progress/63)   |
+| Dutch (Nederlands) (nl_NL)                   | ![61%](https://geps.dev/progress/61)   |
 | English (English) (en_GB)                    | ![100%](https://geps.dev/progress/100) |
 | English (US) (en_US)                         | ![100%](https://geps.dev/progress/100) |
-| French (Français) (fr_FR)                    | ![73%](https://geps.dev/progress/73)   |
-| German (Deutsch) (de_DE)                     | ![92%](https://geps.dev/progress/92)   |
-| Greek (Ελληνικά) (el_GR)                     | ![71%](https://geps.dev/progress/71)   |
-| Hindi (हिंदी) (hi_IN)                          | ![71%](https://geps.dev/progress/71)   |
+| French (Français) (fr_FR)                    | ![91%](https://geps.dev/progress/91)   |
+| German (Deutsch) (de_DE)                     | ![100%](https://geps.dev/progress/100)   |
+| Greek (Ελληνικά) (el_GR)                     | ![69%](https://geps.dev/progress/69)   |
+| Hindi (हिंदी) (hi_IN)                          | ![68%](https://geps.dev/progress/68)   |
 | Hungarian (Magyar) (hu_HU)                   | ![99%](https://geps.dev/progress/99)   |
-| Indonesian (Bahasa Indonesia) (id_ID)        | ![65%](https://geps.dev/progress/65)   |
-| Irish (Gaeilge) (ga_IE)                      | ![72%](https://geps.dev/progress/72)   |
+| Indonesian (Bahasa Indonesia) (id_ID)        | ![63%](https://geps.dev/progress/63)   |
+| Irish (Gaeilge) (ga_IE)                      | ![70%](https://geps.dev/progress/70)   |
 | Italian (Italiano) (it_IT)                   | ![98%](https://geps.dev/progress/98)   |
-| Japanese (日本語) (ja_JP)                    | ![72%](https://geps.dev/progress/72)   |
-| Korean (한국어) (ko_KR)                      | ![71%](https://geps.dev/progress/71)   |
-| Norwegian (Norsk) (no_NB)                    | ![70%](https://geps.dev/progress/70)   |
-| Persian (فارسی) (fa_IR)                      | ![68%](https://geps.dev/progress/68)   |
-| Polish (Polski) (pl_PL)                      | ![76%](https://geps.dev/progress/76)   |
-| Portuguese (Português) (pt_PT)               | ![72%](https://geps.dev/progress/72)   |
-| Portuguese Brazilian (Português) (pt_BR)     | ![80%](https://geps.dev/progress/80)   |
-| Romanian (Română) (ro_RO)                    | ![61%](https://geps.dev/progress/61)   |
-| Russian (Русский) (ru_RU)                    | ![72%](https://geps.dev/progress/72)   |
-| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | ![46%](https://geps.dev/progress/46)   |
-| Simplified Chinese (简体中文) (zh_CN)         | ![93%](https://geps.dev/progress/93)   |
-| Slovakian (Slovensky) (sk_SK)                | ![54%](https://geps.dev/progress/54)   |
-| Slovenian (Slovenščina) (sl_SI)              | ![75%](https://geps.dev/progress/75)   |
-| Spanish (Español) (es_ES)                    | ![78%](https://geps.dev/progress/78)   |
-| Swedish (Svenska) (sv_SE)                    | ![69%](https://geps.dev/progress/69)   |
-| Thai (ไทย) (th_TH)                           | ![62%](https://geps.dev/progress/62)   |
-| Tibetan (བོད་ཡིག་) (bo_CN)                     | ![68%](https://geps.dev/progress/68) |
-| Traditional Chinese (繁體中文) (zh_TW)        | ![80%](https://geps.dev/progress/80)   |
-| Turkish (Türkçe) (tr_TR)                     | ![85%](https://geps.dev/progress/85)   |
-| Ukrainian (Українська) (uk_UA)               | ![75%](https://geps.dev/progress/75)   |
-| Vietnamese (Tiếng Việt) (vi_VN)              | ![60%](https://geps.dev/progress/60)   |
-| Malayalam (മലയാളം) (ml_IN)              | ![77%](https://geps.dev/progress/77)   |
+| Japanese (日本語) (ja_JP)                    | ![70%](https://geps.dev/progress/70)   |
+| Korean (한국어) (ko_KR)                      | ![69%](https://geps.dev/progress/69)   |
+| Norwegian (Norsk) (no_NB)                    | ![67%](https://geps.dev/progress/67)   |
+| Persian (فارسی) (fa_IR)                      | ![66%](https://geps.dev/progress/66)   |
+| Polish (Polski) (pl_PL)                      | ![73%](https://geps.dev/progress/73)   |
+| Portuguese (Português) (pt_PT)               | ![70%](https://geps.dev/progress/70)   |
+| Portuguese Brazilian (Português) (pt_BR)     | ![77%](https://geps.dev/progress/77)   |
+| Romanian (Română) (ro_RO)                    | ![59%](https://geps.dev/progress/59)   |
+| Russian (Русский) (ru_RU)                    | ![70%](https://geps.dev/progress/70)   |
+| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | ![97%](https://geps.dev/progress/97)   |
+| Simplified Chinese (简体中文) (zh_CN)         | ![90%](https://geps.dev/progress/90)   |
+| Slovakian (Slovensky) (sk_SK)                | ![53%](https://geps.dev/progress/53)   |
+| Slovenian (Slovenščina) (sl_SI)              | ![73%](https://geps.dev/progress/73)   |
+| Spanish (Español) (es_ES)                    | ![75%](https://geps.dev/progress/75)   |
+| Swedish (Svenska) (sv_SE)                    | ![67%](https://geps.dev/progress/67)   |
+| Thai (ไทย) (th_TH)                           | ![60%](https://geps.dev/progress/60)   |
+| Tibetan (བོད་ཡིག་) (bo_CN)                     | ![66%](https://geps.dev/progress/66) |
+| Traditional Chinese (繁體中文) (zh_TW)        | ![77%](https://geps.dev/progress/77)   |
+| Turkish (Türkçe) (tr_TR)                     | ![82%](https://geps.dev/progress/82)   |
+| Ukrainian (Українська) (uk_UA)               | ![72%](https://geps.dev/progress/72)   |
+| Vietnamese (Tiếng Việt) (vi_VN)              | ![58%](https://geps.dev/progress/58)   |
+| Malayalam (മലയാളം) (ml_IN)              | ![75%](https://geps.dev/progress/75)   |
 
 ## Stirling PDF Enterprise
 
@@ -168,7 +168,7 @@ Check out our [Enterprise docs](https://docs.stirlingpdf.com/Pro)
 
 Join our community:
 - [Contribution Guidelines](CONTRIBUTING.md)
-- [Translation Guide (How to add custom languages)](HowToAddNewLanguage.md)
+- [Translation Guide (How to add custom languages)](devGuide/HowToAddNewLanguage.md)
+- [Developer Guide](devGuide/DeveloperGuide.md)
 - [Issue Tracker](https://github.com/Stirling-Tools/Stirling-PDF/issues)
 - [Discord Community](https://discord.gg/HYmhKj45pU)
-- [Developer Guide](DeveloperGuide.md)

build.gradle

@@ -9,12 +9,14 @@ plugins {
     id "com.diffplug.spotless" version "7.0.4"
     id "com.github.jk1.dependency-license-report" version "2.9"
     //id "nebula.lint" version "19.0.3"
-    id "org.panteleyev.jpackageplugin" version "1.6.1"
+    id "org.panteleyev.jpackageplugin" version "1.7.3"
     id "org.sonarqube" version "6.2.0.5505"
 }
 
 import com.github.jk1.license.render.*
 import org.gradle.internal.os.OperatingSystem
+import org.panteleyev.jpackage.ImageType
+
 import java.nio.file.Files
 import java.time.Year
 
@@ -26,7 +28,7 @@ ext {
     bouncycastleVersion = "1.81"
     springSecuritySamlVersion = "6.5.1"
     openSamlVersion = "4.3.2"
-    commonmarkVersion = "0.24.0"
+    commonmarkVersion = "0.25.0"
     googleJavaFormatVersion = "1.27.0"
     tempJrePath = null
 }
@@ -43,39 +45,19 @@ bootJar {
     enabled = false
 }
 
-sourceSets {
-    main {
-        java {
-            if (System.getenv('DOCKER_ENABLE_SECURITY') == 'false' || System.getenv('DISABLE_ADDITIONAL_FEATURES') == 'true'
-                || (project.hasProperty('DISABLE_ADDITIONAL_FEATURES')
-                && System.getProperty('DISABLE_ADDITIONAL_FEATURES') == 'true')) {
-                exclude 'stirling/software/proprietary/security/**'
-            }
-            if (System.getenv('STIRLING_PDF_DESKTOP_UI') == 'false') {
-                exclude 'stirling/software/SPDF/UI/impl/**'
-            }
+// Configure main class for the root project
+springBoot {
+    mainClass = 'stirling.software.SPDF.SPDFApplication'
+}
 
-        }
-    }
-
-    test {
-        java {
-            if (System.getenv('DOCKER_ENABLE_SECURITY') == 'false' || System.getenv('DISABLE_ADDITIONAL_FEATURES') == 'true'
-                || (project.hasProperty('DISABLE_ADDITIONAL_FEATURES')
-                && System.getProperty('DISABLE_ADDITIONAL_FEATURES') == 'true')) {
-                exclude 'stirling/software/proprietary/security/**'
-            }
-
-            if (System.getenv('STIRLING_PDF_DESKTOP_UI') == 'false') {
-                exclude 'stirling/software/SPDF/UI/impl/**'
-            }
-        }
-    }
+repositories {
+    mavenCentral()
+    maven { url = 'https://build.shibboleth.net/maven/releases' }
 }
 
 allprojects {
     group = 'stirling.software'
-    version = '1.0.0'
+    version = '1.0.2'
 
     configurations.configureEach {
         exclude group: 'commons-logging', module: 'commons-logging'
@@ -83,7 +65,6 @@ allprojects {
     }
 }
 
-
 tasks.register('writeVersion') {
     def propsFile = file("$projectDir/common/src/main/resources/version.properties")
     def propsDir = propsFile.parentFile
@@ -108,6 +89,10 @@ tasks.register('writeVersion') {
     }
 }
 
+tasks.named('createExe') {
+    dependsOn(":stirling-pdf:bootJar")
+}
+
 subprojects {
     apply plugin: 'java'
     apply plugin: 'java-library'
@@ -120,9 +105,11 @@ subprojects {
         sourceCompatibility = JavaVersion.VERSION_17
     }
 
-    bootJar {
-        enabled = false
-    }
+     if (project.name != "stirling-pdf") {
+        bootJar {
+            enabled = false
+        }
+     }
 
     repositories {
         mavenCentral()
@@ -170,7 +157,7 @@ subprojects {
     test {
         useJUnitPlatform()
     }
-    
+
 	tasks.named("processResources") {
 	  dependsOn(rootProject.tasks.writeVersion)
 	}
@@ -224,6 +211,14 @@ openApi {
     waitTimeInSeconds = 60 // Increase the wait time to 60 seconds
 }
 
+// Configure the forked spring boot run task to properly delegate to the stirling-pdf module
+tasks.named('forkedSpringBootRun') {
+    dependsOn ':stirling-pdf:bootRun'
+    doFirst {
+        println "Delegating forkedSpringBootRun to :stirling-pdf:bootRun"
+    }
+}
+
 //0.11.5 to 2024.11.5
 static def getMacVersion(String version) {
     def currentYear = Year.now().getValue()
@@ -232,14 +227,15 @@ static def getMacVersion(String version) {
 }
 
 jpackage {
-    input = "build/libs"
-    destination = "${projectDir}/build/jpackage"
+    dependsOn(":stirling-pdf:bootJar")
+    input = layout.projectDirectory.dir("stirling-pdf/build/libs")
+    destination = layout.projectDirectory.dir("build/jpackage")
     mainJar = "Stirling-PDF-${project.version}.jar"
     appName = "Stirling PDF"
     appVersion = project.version
     vendor = "Stirling PDF Inc"
     appDescription = "Stirling PDF - Your Local PDF Editor"
-    icon = "stirling-pdf/src/main/resources/static/favicon.ico"
+    icon = layout.projectDirectory.file("stirling-pdf/src/main/resources/static/favicon.ico")
     verbose = true
 //    mainClass = "org.springframework.boot.loader.launch.JarLauncher"
 
@@ -274,15 +270,15 @@ jpackage {
         winUpgradeUuid = "2a43ed0c-b8c2-40cf-89e1-751129b87641" // Unique identifier for updates
         winHelpUrl = "https://github.com/Stirling-Tools/Stirling-PDF"
         winUpdateUrl = "https://github.com/Stirling-Tools/Stirling-PDF/releases"
-        type = "exe"
+        type = ImageType.EXE
         installDir = "C:/Program Files/Stirling-PDF"
     }
 
     // MacOS-specific configuration
     mac {
         appVersion = getMacVersion(project.version.toString())
-        icon = "stirling-pdf/src/main/resources/static/favicon.icns"
-        type = "dmg"
+        icon = layout.projectDirectory.file("stirling-pdf/src/main/resources/static/favicon.icns")
+        type = ImageType.DMG
         macPackageIdentifier = "Stirling PDF"
         macPackageName = "Stirling PDF"
         macAppCategory = "public.app-category.productivity"
@@ -303,8 +299,8 @@ jpackage {
     // Linux-specific configuration
     linux {
         appVersion = project.version
-        icon = "stirling-pdf/src/main/resources/static/favicon.png"
-        type = "deb" // Can also use "rpm" for Red Hat-based systems
+        icon = layout.projectDirectory.file("stirling-pdf/src/main/resources/static/favicon.png")
+        type = ImageType.DEB // Can also use "rpm" for Red Hat-based systems
 
         // Debian package configuration
         //linuxPackageName = "stirlingpdf"
@@ -340,7 +336,7 @@ jpackage {
 
     // Add copyright and license information
     copyright = "Copyright © 2025 Stirling PDF Inc."
-    licenseFile = "LICENSE"
+    licenseFile = layout.projectDirectory.file("LICENSE")
 }
 
 //tasks.wrapper {
@@ -375,7 +371,7 @@ tasks.register('jpackageMacX64') {
             commandLine 'jpackage',
                 '--type', 'dmg',
                 '--name', 'Stirling PDF (x86_64)',
-                '--input', 'build/libs',
+                '--input', 'stirling-pdf/build/libs',
                 '--main-jar', "Stirling-PDF-${project.version}.jar",
                 '--main-class', 'org.springframework.boot.loader.launch.JarLauncher',
                 '--runtime-image', file(jrePath + "/zulu-17.jre/Contents/Home"),
@@ -475,7 +471,7 @@ launch4j {
     } else {
         headerType = "console"
     }
-    jarTask = tasks.bootJar
+    jarTask = project(":stirling-pdf").tasks.bootJar
 
     errTitle="Encountered error, do you have Java 21?"
     downloadUrl="https://download.oracle.com/java/21/latest/jdk-21_windows-x64_bin.exe"
@@ -537,6 +533,14 @@ swaggerhubUpload {
 }
 
 dependencies {
+    implementation project(':stirling-pdf')
+    implementation project(':common')
+    if (System.getenv('DISABLE_ADDITIONAL_FEATURES') != 'true'
+        || (project.hasProperty('DISABLE_ADDITIONAL_FEATURES')
+        && System.getProperty('DISABLE_ADDITIONAL_FEATURES') != 'true')) {
+        implementation project(':proprietary')
+    }
+
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher:1.12.2'
 }

common/src/main/java/stirling/software/common/configuration/AppConfig.java

@@ -10,7 +10,6 @@ import java.util.Properties;
 import java.util.function.Predicate;
 
 import org.springframework.beans.factory.annotation.Value;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -21,6 +20,7 @@ import org.springframework.core.env.Environment;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.core.io.Resource;
 import org.springframework.core.io.ResourceLoader;
+import org.springframework.util.ClassUtils;
 import org.thymeleaf.spring6.SpringTemplateEngine;
 
 import lombok.Getter;
@@ -148,23 +148,10 @@ public class AppConfig {
     }
 
     @Bean(name = "activeSecurity")
-    public boolean activeSecurity() {
-        String disableAdditionalFeatures = env.getProperty("DISABLE_ADDITIONAL_FEATURES");
-
-        if (disableAdditionalFeatures != null) {
-            // DISABLE_ADDITIONAL_FEATURES=true means security OFF, so return false
-            // DISABLE_ADDITIONAL_FEATURES=false means security ON, so return true
-            return !Boolean.parseBoolean(disableAdditionalFeatures);
-        }
-
-        return env.getProperty("DOCKER_ENABLE_SECURITY", Boolean.class, true);
-    }
-
-    @Bean(name = "missingActiveSecurity")
-    @ConditionalOnMissingClass(
-            "stirling.software.proprietary.security.configuration.SecurityConfiguration")
     public boolean missingActiveSecurity() {
-        return true;
+        return ClassUtils.isPresent(
+                "stirling.software.proprietary.security.configuration.SecurityConfiguration",
+                this.getClass().getClassLoader());
     }
 
     @Bean(name = "directoryFilter")

common/src/main/java/stirling/software/common/model/ApplicationProperties.java

@@ -545,6 +545,8 @@ public class ApplicationProperties {
             private int calibreSessionLimit;
             private int qpdfSessionLimit;
             private int tesseractSessionLimit;
+            private int ghostscriptSessionLimit;
+            private int ocrMyPdfSessionLimit;
 
             public int getQpdfSessionLimit() {
                 return qpdfSessionLimit > 0 ? qpdfSessionLimit : 2;
@@ -577,6 +579,14 @@ public class ApplicationProperties {
             public int getCalibreSessionLimit() {
                 return calibreSessionLimit > 0 ? calibreSessionLimit : 1;
             }
+
+            public int getGhostscriptSessionLimit() {
+                return ghostscriptSessionLimit > 0 ? ghostscriptSessionLimit : 8;
+            }
+
+            public int getOcrMyPdfSessionLimit() {
+                return ocrMyPdfSessionLimit > 0 ? ocrMyPdfSessionLimit : 2;
+            }
         }
 
         @Data
@@ -589,6 +599,8 @@ public class ApplicationProperties {
             private long calibreTimeoutMinutes;
             private long tesseractTimeoutMinutes;
             private long qpdfTimeoutMinutes;
+            private long ghostscriptTimeoutMinutes;
+            private long ocrMyPdfTimeoutMinutes;
 
             public long getTesseractTimeoutMinutes() {
                 return tesseractTimeoutMinutes > 0 ? tesseractTimeoutMinutes : 30;
@@ -621,6 +633,14 @@ public class ApplicationProperties {
             public long getCalibreTimeoutMinutes() {
                 return calibreTimeoutMinutes > 0 ? calibreTimeoutMinutes : 30;
             }
+
+            public long getGhostscriptTimeoutMinutes() {
+                return ghostscriptTimeoutMinutes > 0 ? ghostscriptTimeoutMinutes : 30;
+            }
+
+            public long getOcrMyPdfTimeoutMinutes() {
+                return ocrMyPdfTimeoutMinutes > 0 ? ocrMyPdfTimeoutMinutes : 30;
+            }
         }
     }
 }

common/src/main/java/stirling/software/common/model/job/JobResult.java

@@ -1,6 +1,7 @@
 package stirling.software.common.model.job;
 
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
@@ -26,14 +27,8 @@ public class JobResult {
     /** Error message if the job failed */
     private String error;
 
-    /** The file ID of the result file, if applicable */
-    private String fileId;
-
-    /** Original file name, if applicable */
-    private String originalFileName;
-
-    /** MIME type of the result, if applicable */
-    private String contentType;
+    /** List of result files for jobs that produce files */
+    private List<ResultFile> resultFiles;
 
     /** Time when the job was created */
     private LocalDateTime createdAt;
@@ -64,21 +59,6 @@ public class JobResult {
                 .build();
     }
 
-    /**
-     * Mark this job as complete with a file result
-     *
-     * @param fileId The file ID of the result
-     * @param originalFileName The original file name
-     * @param contentType The content type of the file
-     */
-    public void completeWithFile(String fileId, String originalFileName, String contentType) {
-        this.complete = true;
-        this.fileId = fileId;
-        this.originalFileName = originalFileName;
-        this.contentType = contentType;
-        this.completedAt = LocalDateTime.now();
-    }
-
     /**
      * Mark this job as complete with a general result
      *
@@ -101,6 +81,67 @@ public class JobResult {
         this.completedAt = LocalDateTime.now();
     }
 
+    /**
+     * Mark this job as complete with multiple file results
+     *
+     * @param resultFiles The list of result files
+     */
+    public void completeWithFiles(List<ResultFile> resultFiles) {
+        this.complete = true;
+        this.resultFiles = new ArrayList<>(resultFiles);
+        this.completedAt = LocalDateTime.now();
+    }
+
+    /**
+     * Mark this job as complete with a single file result (convenience method)
+     *
+     * @param fileId The file ID of the result
+     * @param fileName The file name
+     * @param contentType The content type of the file
+     * @param fileSize The size of the file in bytes
+     */
+    public void completeWithSingleFile(
+            String fileId, String fileName, String contentType, long fileSize) {
+        ResultFile resultFile =
+                ResultFile.builder()
+                        .fileId(fileId)
+                        .fileName(fileName)
+                        .contentType(contentType)
+                        .fileSize(fileSize)
+                        .build();
+        completeWithFiles(List.of(resultFile));
+    }
+
+    /**
+     * Check if this job has file results
+     *
+     * @return true if this job has file results, false otherwise
+     */
+    public boolean hasFiles() {
+        return resultFiles != null && !resultFiles.isEmpty();
+    }
+
+    /**
+     * Check if this job has multiple file results
+     *
+     * @return true if this job has multiple file results, false otherwise
+     */
+    public boolean hasMultipleFiles() {
+        return resultFiles != null && resultFiles.size() > 1;
+    }
+
+    /**
+     * Get all result files
+     *
+     * @return List of result files
+     */
+    public List<ResultFile> getAllResultFiles() {
+        if (resultFiles != null && !resultFiles.isEmpty()) {
+            return Collections.unmodifiableList(resultFiles);
+        }
+        return Collections.emptyList();
+    }
+
     /**
      * Add a note to this job
      *

common/src/main/java/stirling/software/common/model/job/ResultFile.java

@@ -0,0 +1,26 @@
+package stirling.software.common.model.job;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/** Represents a single file result from a job execution */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ResultFile {
+
+    /** The file ID for accessing the file */
+    private String fileId;
+
+    /** The original file name */
+    private String fileName;
+
+    /** MIME type of the file */
+    private String contentType;
+
+    /** Size of the file in bytes */
+    private long fileSize;
+}

common/src/main/java/stirling/software/common/service/CustomPDFDocumentFactory.java

@@ -24,6 +24,7 @@ import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.util.ApplicationContextProvider;
+import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.TempFileRegistry;
 
@@ -82,7 +83,7 @@ public class CustomPDFDocumentFactory {
      */
     public PDDocument load(File file, boolean readOnly) throws IOException {
         if (file == null) {
-            throw new IllegalArgumentException("File cannot be null");
+            throw ExceptionUtils.createNullArgumentException("File");
         }
 
         long fileSize = file.length();
@@ -109,7 +110,7 @@ public class CustomPDFDocumentFactory {
      */
     public PDDocument load(Path path, boolean readOnly) throws IOException {
         if (path == null) {
-            throw new IllegalArgumentException("File cannot be null");
+            throw ExceptionUtils.createNullArgumentException("File");
         }
 
         long fileSize = Files.size(path);
@@ -130,7 +131,7 @@ public class CustomPDFDocumentFactory {
     /** Load a PDF from byte array with automatic optimization and read-only option. */
     public PDDocument load(byte[] input, boolean readOnly) throws IOException {
         if (input == null) {
-            throw new IllegalArgumentException("Input bytes cannot be null");
+            throw ExceptionUtils.createNullArgumentException("Input bytes");
         }
 
         long dataSize = input.length;
@@ -151,7 +152,7 @@ public class CustomPDFDocumentFactory {
     /** Load a PDF from InputStream with automatic optimization and read-only option. */
     public PDDocument load(InputStream input, boolean readOnly) throws IOException {
         if (input == null) {
-            throw new IllegalArgumentException("InputStream cannot be null");
+            throw ExceptionUtils.createNullArgumentException("InputStream");
         }
 
         // Since we don't know the size upfront, buffer to a temp file
@@ -174,7 +175,7 @@ public class CustomPDFDocumentFactory {
     public PDDocument load(InputStream input, String password, boolean readOnly)
             throws IOException {
         if (input == null) {
-            throw new IllegalArgumentException("InputStream cannot be null");
+            throw ExceptionUtils.createNullArgumentException("InputStream");
         }
 
         // Since we don't know the size upfront, buffer to a temp file
@@ -292,9 +293,32 @@ public class CustomPDFDocumentFactory {
         } else {
             throw new IllegalArgumentException("Unsupported source type: " + source.getClass());
         }
+
+        configureResourceCacheIfNeeded(document, contentSize);
+
         return document;
     }
 
+    /**
+     * Configure resource cache based on content size and memory constraints. Disables resource
+     * cache for large files or when memory is low to prevent OOM errors.
+     */
+    private void configureResourceCacheIfNeeded(PDDocument document, long contentSize) {
+        if (contentSize > LARGE_FILE_THRESHOLD) {
+            document.setResourceCache(null);
+        } else {
+            // Check current memory status for smaller files
+            long maxMemory = Runtime.getRuntime().maxMemory();
+            long usedMemory =
+                    Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory();
+            double freeMemoryPercent = (double) (maxMemory - usedMemory) / maxMemory * 100;
+
+            if (freeMemoryPercent < MIN_FREE_MEMORY_PERCENTAGE) {
+                document.setResourceCache(null);
+            }
+        }
+    }
+
     /** Load a PDF with password protection using adaptive loading strategies */
     private PDDocument loadAdaptivelyWithPassword(Object source, long contentSize, String password)
             throws IOException {
@@ -313,6 +337,9 @@ public class CustomPDFDocumentFactory {
         } else {
             throw new IllegalArgumentException("Unsupported source type: " + source.getClass());
         }
+
+        configureResourceCacheIfNeeded(document, contentSize);
+
         return document;
     }
 
@@ -354,7 +381,12 @@ public class CustomPDFDocumentFactory {
 
     private PDDocument loadFromFile(File file, long size, StreamCacheCreateFunction cache)
             throws IOException {
-        return Loader.loadPDF(new DeletingRandomAccessFile(file), "", null, null, cache);
+        try {
+            return Loader.loadPDF(new DeletingRandomAccessFile(file), "", null, null, cache);
+        } catch (IOException e) {
+            ExceptionUtils.logException("PDF loading from file", e);
+            throw ExceptionUtils.handlePdfException(e);
+        }
     }
 
     private PDDocument loadFromBytes(byte[] bytes, long size, StreamCacheCreateFunction cache)
@@ -366,7 +398,13 @@ public class CustomPDFDocumentFactory {
             Files.write(tempFile, bytes);
             return loadFromFile(tempFile.toFile(), size, cache);
         }
-        return Loader.loadPDF(bytes, "", null, null, cache);
+
+        try {
+            return Loader.loadPDF(bytes, "", null, null, cache);
+        } catch (IOException e) {
+            ExceptionUtils.logException("PDF loading from bytes", e);
+            throw ExceptionUtils.handlePdfException(e);
+        }
     }
 
     public PDDocument createNewDocument(MemoryUsageSetting settings) throws IOException {
@@ -399,7 +437,7 @@ public class CustomPDFDocumentFactory {
             try {
                 document.setAllSecurityToBeRemoved(true);
             } catch (Exception e) {
-                log.error("Decryption failed", e);
+                ExceptionUtils.logException("PDF decryption", e);
                 throw new IOException("PDF decryption failed", e);
             }
         }

common/src/main/java/stirling/software/common/service/FileStorage.java

@@ -131,14 +131,46 @@ public class FileStorage {
         return Files.exists(filePath);
     }
 
+    /**
+     * Get the size of a file by its ID without loading the content into memory
+     *
+     * @param fileId The ID of the file
+     * @return The size of the file in bytes
+     * @throws IOException If the file doesn't exist or can't be read
+     */
+    public long getFileSize(String fileId) throws IOException {
+        Path filePath = getFilePath(fileId);
+
+        if (!Files.exists(filePath)) {
+            throw new IOException("File not found with ID: " + fileId);
+        }
+
+        return Files.size(filePath);
+    }
+
     /**
      * Get the path for a file ID
      *
      * @param fileId The ID of the file
      * @return The path to the file
+     * @throws IllegalArgumentException if fileId contains path traversal characters or resolves
+     *     outside base directory
      */
     private Path getFilePath(String fileId) {
-        return Path.of(tempDirPath).resolve(fileId);
+        // Validate fileId to prevent path traversal
+        if (fileId.contains("..") || fileId.contains("/") || fileId.contains("\\")) {
+            throw new IllegalArgumentException("Invalid file ID");
+        }
+
+        Path basePath = Path.of(tempDirPath).normalize().toAbsolutePath();
+        Path resolvedPath = basePath.resolve(fileId).normalize();
+
+        // Ensure resolved path is within the base directory
+        if (!resolvedPath.startsWith(basePath)) {
+            throw new IllegalArgumentException("File ID resolves to an invalid path");
+        }
+
+        return resolvedPath;
     }
 
     /**

common/src/main/java/stirling/software/common/service/TaskManager.java

@@ -1,15 +1,26 @@
 package stirling.software.common.service;
 
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
 import java.time.LocalDateTime;
 import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
+import java.util.zip.ZipEntry;
+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;
 
 import jakarta.annotation.PreDestroy;
 
@@ -17,6 +28,7 @@ import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.common.model.job.JobResult;
 import stirling.software.common.model.job.JobStats;
+import stirling.software.common.model.job.ResultFile;
 
 /** Manages async tasks and their results */
 @Service
@@ -80,8 +92,53 @@ public class TaskManager {
     public void setFileResult(
             String jobId, String fileId, String originalFileName, String contentType) {
         JobResult jobResult = getOrCreateJobResult(jobId);
-        jobResult.completeWithFile(fileId, originalFileName, contentType);
-        log.debug("Set file result for job ID: {} with file ID: {}", jobId, fileId);
+
+        // Check if this is a ZIP file that should be extracted
+        if (isZipFile(contentType, originalFileName)) {
+            try {
+                List<ResultFile> extractedFiles =
+                        extractZipToIndividualFiles(fileId, originalFileName);
+                if (!extractedFiles.isEmpty()) {
+                    jobResult.completeWithFiles(extractedFiles);
+                    log.debug(
+                            "Set multiple file results for job ID: {} with {} files extracted from ZIP",
+                            jobId,
+                            extractedFiles.size());
+                    return;
+                }
+            } catch (Exception e) {
+                log.warn(
+                        "Failed to extract ZIP file for job {}: {}. Falling back to single file result.",
+                        jobId,
+                        e.getMessage());
+            }
+        }
+
+        // Handle as single file using new ResultFile approach
+        try {
+            long fileSize = fileStorage.getFileSize(fileId);
+            jobResult.completeWithSingleFile(fileId, originalFileName, contentType, fileSize);
+            log.debug("Set single file result for job ID: {} with file ID: {}", jobId, fileId);
+        } catch (Exception e) {
+            log.warn(
+                    "Failed to get file size for job {}: {}. Using size 0.", jobId, e.getMessage());
+            jobResult.completeWithSingleFile(fileId, originalFileName, contentType, 0);
+        }
+    }
+
+    /**
+     * Set the result of a task as multiple files
+     *
+     * @param jobId The job ID
+     * @param resultFiles The list of result files
+     */
+    public void setMultipleFileResults(String jobId, List<ResultFile> resultFiles) {
+        JobResult jobResult = getOrCreateJobResult(jobId);
+        jobResult.completeWithFiles(resultFiles);
+        log.debug(
+                "Set multiple file results for job ID: {} with {} files",
+                jobId,
+                resultFiles.size());
     }
 
     /**
@@ -104,7 +161,7 @@ public class TaskManager {
     public void setComplete(String jobId) {
         JobResult jobResult = getOrCreateJobResult(jobId);
         if (jobResult.getResult() == null
-                && jobResult.getFileId() == null
+                && !jobResult.hasFiles()
                 && jobResult.getError() == null) {
             // If no result or error has been set, mark it as complete with an empty result
             jobResult.completeWithResult("Task completed successfully");
@@ -186,7 +243,7 @@ public class TaskManager {
                     failedJobs++;
                 } else {
                     successfulJobs++;
-                    if (result.getFileId() != null) {
+                    if (result.hasFiles()) {
                         fileResultJobs++;
                     }
                 }
@@ -250,17 +307,8 @@ public class TaskManager {
                         && result.getCompletedAt() != null
                         && result.getCompletedAt().isBefore(expiryThreshold)) {
 
-                    // If the job has a file result, delete the file
-                    if (result.getFileId() != null) {
-                        try {
-                            fileStorage.deleteFile(result.getFileId());
-                        } catch (Exception e) {
-                            log.warn(
-                                    "Failed to delete file for job {}: {}",
-                                    entry.getKey(),
-                                    e.getMessage());
-                        }
-                    }
+                    // Clean up file results
+                    cleanupJobFiles(result, entry.getKey());
 
                     // Remove the job result
                     jobResults.remove(entry.getKey());
@@ -290,4 +338,129 @@ public class TaskManager {
             cleanupExecutor.shutdownNow();
         }
     }
+
+    /** Check if a file is a ZIP file based on content type and filename */
+    private boolean isZipFile(String contentType, String fileName) {
+        if (contentType != null
+                && (contentType.equals("application/zip")
+                        || contentType.equals("application/x-zip-compressed"))) {
+            return true;
+        }
+
+        if (fileName != null && fileName.toLowerCase().endsWith(".zip")) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /** Extract a ZIP file into individual files and store them */
+    private List<ResultFile> extractZipToIndividualFiles(
+            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()))) {
+            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());
+
+                    ResultFile resultFile =
+                            ResultFile.builder()
+                                    .fileId(individualFileId)
+                                    .fileName(entry.getName())
+                                    .contentType(contentType)
+                                    .fileSize(fileContent.length)
+                                    .build();
+
+                    extractedFiles.add(resultFile);
+                    log.debug(
+                            "Extracted file: {} (size: {} bytes)",
+                            entry.getName(),
+                            fileContent.length);
+                }
+                zipIn.closeEntry();
+            }
+        }
+
+        // Clean up the original ZIP file after extraction
+        try {
+            fileStorage.deleteFile(zipFileId);
+            log.debug("Cleaned up original ZIP file: {}", zipFileId);
+        } catch (Exception e) {
+            log.warn("Failed to clean up original ZIP file {}: {}", zipFileId, e.getMessage());
+        }
+
+        return extractedFiles;
+    }
+
+    /** Determine content type based on file extension */
+    private String determineContentType(String fileName) {
+        if (fileName == null) {
+            return MediaType.APPLICATION_OCTET_STREAM_VALUE;
+        }
+
+        String lowerName = fileName.toLowerCase();
+        if (lowerName.endsWith(".pdf")) {
+            return MediaType.APPLICATION_PDF_VALUE;
+        } else if (lowerName.endsWith(".txt")) {
+            return MediaType.TEXT_PLAIN_VALUE;
+        } else if (lowerName.endsWith(".json")) {
+            return MediaType.APPLICATION_JSON_VALUE;
+        } else if (lowerName.endsWith(".xml")) {
+            return MediaType.APPLICATION_XML_VALUE;
+        } else if (lowerName.endsWith(".jpg") || lowerName.endsWith(".jpeg")) {
+            return MediaType.IMAGE_JPEG_VALUE;
+        } else if (lowerName.endsWith(".png")) {
+            return MediaType.IMAGE_PNG_VALUE;
+        } else {
+            return MediaType.APPLICATION_OCTET_STREAM_VALUE;
+        }
+    }
+
+    /** Clean up files associated with a job result */
+    private void cleanupJobFiles(JobResult result, String jobId) {
+        // Clean up all result files
+        if (result.hasFiles()) {
+            for (ResultFile resultFile : result.getAllResultFiles()) {
+                try {
+                    fileStorage.deleteFile(resultFile.getFileId());
+                } catch (Exception e) {
+                    log.warn(
+                            "Failed to delete file {} for job {}: {}",
+                            resultFile.getFileId(),
+                            jobId,
+                            e.getMessage());
+                }
+            }
+        }
+    }
+
+    /** Find the ResultFile metadata for a given file ID by searching through all job results */
+    public ResultFile findResultFileByFileId(String fileId) {
+        for (JobResult jobResult : jobResults.values()) {
+            if (jobResult.hasFiles()) {
+                for (ResultFile resultFile : jobResult.getAllResultFiles()) {
+                    if (fileId.equals(resultFile.getFileId())) {
+                        return resultFile;
+                    }
+                }
+            }
+        }
+        return null;
+    }
 }

common/src/main/java/stirling/software/common/service/TempFileCleanupService.java

@@ -154,11 +154,15 @@ public class TempFileCleanupService {
         boolean containerMode = isContainerMode();
         int unregisteredDeletedCount = cleanupUnregisteredFiles(containerMode, true, maxAgeMillis);
 
-        log.info(
-                "Scheduled cleanup complete. Deleted {} registered files, {} unregistered files, {} directories",
-                registeredDeletedCount,
-                unregisteredDeletedCount,
-                directoriesDeletedCount);
+        if (registeredDeletedCount > 0
+                || unregisteredDeletedCount > 0
+                || directoriesDeletedCount > 0) {
+            log.info(
+                    "Scheduled cleanup complete. Deleted {} registered files, {} unregistered files, {} directories",
+                    registeredDeletedCount,
+                    unregisteredDeletedCount,
+                    directoriesDeletedCount);
+        }
     }
 
     /**
@@ -166,7 +170,6 @@ public class TempFileCleanupService {
      * important in Docker environments where temp files persist between container restarts.
      */
     private void runStartupCleanup() {
-        log.info("Running startup temporary file cleanup");
         boolean containerMode = isContainerMode();
 
         log.info(
@@ -178,7 +181,6 @@ public class TempFileCleanupService {
         long maxAgeMillis = containerMode ? 0 : 24 * 60 * 60 * 1000; // 0 or 24 hours
 
         int totalDeletedCount = cleanupUnregisteredFiles(containerMode, false, maxAgeMillis);
-
         log.info(
                 "Startup cleanup complete. Deleted {} temporary files/directories",
                 totalDeletedCount);
@@ -225,7 +227,7 @@ public class TempFileCleanupService {
                             tempDir -> {
                                 try {
                                     String phase = isScheduled ? "scheduled" : "startup";
-                                    log.info(
+                                    log.debug(
                                             "Scanning directory for {} cleanup: {}",
                                             phase,
                                             tempDir);

common/src/main/java/stirling/software/common/util/ExceptionUtils.java

@@ -0,0 +1,327 @@
+package stirling.software.common.util;
+
+import java.io.IOException;
+import java.text.MessageFormat;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Utility class for handling exceptions with internationalized error messages. Provides consistent
+ * error handling and user-friendly messages across the application.
+ */
+@Slf4j
+public class ExceptionUtils {
+
+    /**
+     * Create an IOException with internationalized message for PDF corruption.
+     *
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createPdfCorruptedException(Exception cause) {
+        return createPdfCorruptedException(null, cause);
+    }
+
+    /**
+     * Create an IOException with internationalized message for PDF corruption with context.
+     *
+     * @param context additional context (e.g., "during merge", "during image extraction")
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createPdfCorruptedException(String context, Exception cause) {
+        String message;
+        if (context != null && !context.isEmpty()) {
+            message =
+                    String.format(
+                            "Error %s: PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF' feature first to fix the file before proceeding with this operation.",
+                            context);
+        } else {
+            message =
+                    "PDF file appears to be corrupted or damaged. Please try using the 'Repair PDF' feature first to fix the file before proceeding with this operation.";
+        }
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create an IOException with internationalized message for multiple corrupted PDFs.
+     *
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createMultiplePdfCorruptedException(Exception cause) {
+        String message =
+                "One or more PDF files appear to be corrupted or damaged. Please try using the 'Repair PDF' feature on each file first before attempting to merge them.";
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create an IOException with internationalized message for PDF encryption issues.
+     *
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createPdfEncryptionException(Exception cause) {
+        String message =
+                "The PDF appears to have corrupted encryption data. This can happen when the PDF was created with incompatible encryption methods. Please try using the 'Repair PDF' feature first, or contact the document creator for a new copy.";
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create an IOException with internationalized message for PDF password issues.
+     *
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createPdfPasswordException(Exception cause) {
+        String message =
+                "The PDF Document is passworded and either the password was not provided or was incorrect";
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create an IOException with internationalized message for file processing errors.
+     *
+     * @param operation the operation being performed (e.g., "merge", "split", "convert")
+     * @param cause the original exception
+     * @return IOException with user-friendly message
+     */
+    public static IOException createFileProcessingException(String operation, Exception cause) {
+        String message =
+                String.format(
+                        "An error occurred while processing the file during %s operation: %s",
+                        operation, cause.getMessage());
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create a generic IOException with internationalized message.
+     *
+     * @param messageKey the i18n message key
+     * @param defaultMessage the default message if i18n is not available
+     * @param cause the original exception
+     * @param args optional arguments for the message
+     * @return IOException with user-friendly message
+     */
+    public static IOException createIOException(
+            String messageKey, String defaultMessage, Exception cause, Object... args) {
+        String message = MessageFormat.format(defaultMessage, args);
+        return new IOException(message, cause);
+    }
+
+    /**
+     * Create a generic RuntimeException with internationalized message.
+     *
+     * @param messageKey the i18n message key
+     * @param defaultMessage the default message if i18n is not available
+     * @param cause the original exception
+     * @param args optional arguments for the message
+     * @return RuntimeException with user-friendly message
+     */
+    public static RuntimeException createRuntimeException(
+            String messageKey, String defaultMessage, Exception cause, Object... args) {
+        String message = MessageFormat.format(defaultMessage, args);
+        return new RuntimeException(message, cause);
+    }
+
+    /**
+     * Create an IllegalArgumentException with internationalized message.
+     *
+     * @param messageKey the i18n message key
+     * @param defaultMessage the default message if i18n is not available
+     * @param args optional arguments for the message
+     * @return IllegalArgumentException with user-friendly message
+     */
+    public static IllegalArgumentException createIllegalArgumentException(
+            String messageKey, String defaultMessage, Object... args) {
+        String message = MessageFormat.format(defaultMessage, args);
+        return new IllegalArgumentException(message);
+    }
+
+    /** Create file validation exceptions. */
+    public static IllegalArgumentException createHtmlFileRequiredException() {
+        return createIllegalArgumentException(
+                "error.fileFormatRequired", "File must be in {0} format", "HTML or ZIP");
+    }
+
+    public static IllegalArgumentException createPdfFileRequiredException() {
+        return createIllegalArgumentException(
+                "error.fileFormatRequired", "File must be in {0} format", "PDF");
+    }
+
+    public static IllegalArgumentException createInvalidPageSizeException(String size) {
+        return createIllegalArgumentException(
+                "error.invalidFormat", "Invalid {0} format: {1}", "page size", size);
+    }
+
+    /** Create OCR-related exceptions. */
+    public static IOException createOcrLanguageRequiredException() {
+        return createIOException(
+                "error.optionsNotSpecified", "{0} options are not specified", null, "OCR language");
+    }
+
+    public static IOException createOcrInvalidLanguagesException() {
+        return createIOException(
+                "error.invalidFormat",
+                "Invalid {0} format: {1}",
+                null,
+                "OCR languages",
+                "none of the selected languages are valid");
+    }
+
+    public static IOException createOcrToolsUnavailableException() {
+        return createIOException(
+                "error.toolNotInstalled", "{0} is not installed", null, "OCR tools");
+    }
+
+    /** Create system requirement exceptions. */
+    public static IOException createPythonRequiredForWebpException() {
+        return createIOException(
+                "error.toolRequired", "{0} is required for {1}", null, "Python", "WebP conversion");
+    }
+
+    /** Create file operation exceptions. */
+    public static IOException createFileNotFoundException(String fileId) {
+        return createIOException("error.fileNotFound", "File not found with ID: {0}", null, fileId);
+    }
+
+    public static RuntimeException createPdfaConversionFailedException() {
+        return createRuntimeException(
+                "error.conversionFailed", "{0} conversion failed", null, "PDF/A");
+    }
+
+    public static IllegalArgumentException createInvalidComparatorException() {
+        return createIllegalArgumentException(
+                "error.invalidFormat",
+                "Invalid {0} format: {1}",
+                "comparator",
+                "only 'greater', 'equal', and 'less' are supported");
+    }
+
+    /** Create compression-related exceptions. */
+    public static RuntimeException createMd5AlgorithmException(Exception cause) {
+        return createRuntimeException(
+                "error.algorithmNotAvailable", "{0} algorithm not available", cause, "MD5");
+    }
+
+    public static IllegalArgumentException createCompressionOptionsException() {
+        return createIllegalArgumentException(
+                "error.optionsNotSpecified",
+                "{0} options are not specified",
+                "compression (expected output size and optimize level)");
+    }
+
+    public static IOException createGhostscriptCompressionException() {
+        return createIOException(
+                "error.commandFailed", "{0} command failed", null, "Ghostscript compression");
+    }
+
+    public static IOException createGhostscriptCompressionException(Exception cause) {
+        return createIOException(
+                "error.commandFailed", "{0} command failed", cause, "Ghostscript compression");
+    }
+
+    public static IOException createQpdfCompressionException(Exception cause) {
+        return createIOException("error.commandFailed", "{0} command failed", cause, "QPDF");
+    }
+
+    /**
+     * Check if an exception indicates a corrupted PDF and wrap it with appropriate message.
+     *
+     * @param e the exception to check
+     * @return the original exception if not PDF corruption, or a new IOException with user-friendly
+     *     message
+     */
+    public static IOException handlePdfException(IOException e) {
+        return handlePdfException(e, null);
+    }
+
+    /**
+     * Check if an exception indicates a corrupted PDF and wrap it with appropriate message.
+     *
+     * @param e the exception to check
+     * @param context additional context for the error
+     * @return the original exception if not PDF corruption, or a new IOException with user-friendly
+     *     message
+     */
+    public static IOException handlePdfException(IOException e, String context) {
+        if (PdfErrorUtils.isCorruptedPdfError(e)) {
+            return createPdfCorruptedException(context, e);
+        }
+
+        if (isEncryptionError(e)) {
+            return createPdfEncryptionException(e);
+        }
+
+        if (isPasswordError(e)) {
+            return createPdfPasswordException(e);
+        }
+
+        return e; // Return original exception if no specific handling needed
+    }
+
+    /**
+     * Check if an exception indicates a PDF encryption/decryption error.
+     *
+     * @param e the exception to check
+     * @return true if it's an encryption error, false otherwise
+     */
+    public static boolean isEncryptionError(IOException e) {
+        String message = e.getMessage();
+        if (message == null) return false;
+
+        return message.contains("BadPaddingException")
+                || message.contains("Given final block not properly padded")
+                || message.contains("AES initialization vector not fully read")
+                || message.contains("Failed to decrypt");
+    }
+
+    /**
+     * Check if an exception indicates a PDF password error.
+     *
+     * @param e the exception to check
+     * @return true if it's a password error, false otherwise
+     */
+    public static boolean isPasswordError(IOException e) {
+        String message = e.getMessage();
+        if (message == null) return false;
+
+        return message.contains("password is incorrect")
+                || message.contains("Password is not provided")
+                || message.contains("PDF contains an encryption dictionary");
+    }
+
+    /**
+     * Log an exception with appropriate level based on its type.
+     *
+     * @param operation the operation being performed
+     * @param e the exception that occurred
+     */
+    public static void logException(String operation, Exception e) {
+        if (PdfErrorUtils.isCorruptedPdfError(e)) {
+            log.warn("PDF corruption detected during {}: {}", operation, e.getMessage());
+        } else if (e instanceof IOException
+                && (isEncryptionError((IOException) e) || isPasswordError((IOException) e))) {
+            log.info("PDF security issue during {}: {}", operation, e.getMessage());
+        } else {
+            log.error("Unexpected error during {}", operation, e);
+        }
+    }
+
+    /** Create common validation exceptions. */
+    public static IllegalArgumentException createInvalidArgumentException(String argumentName) {
+        return createIllegalArgumentException(
+                "error.invalidArgument", "Invalid argument: {0}", argumentName);
+    }
+
+    public static IllegalArgumentException createInvalidArgumentException(
+            String argumentName, String value) {
+        return createIllegalArgumentException(
+                "error.invalidFormat", "Invalid {0} format: {1}", argumentName, value);
+    }
+
+    public static IllegalArgumentException createNullArgumentException(String argumentName) {
+        return createIllegalArgumentException(
+                "error.argumentRequired", "{0} must not be null", argumentName);
+    }
+}

common/src/main/java/stirling/software/common/util/FileToPdf.java

@@ -32,21 +32,23 @@ public class FileToPdf {
 
         try (TempFile tempOutputFile = new TempFile(tempFileManager, ".pdf")) {
             try (TempFile tempInputFile =
-                    new TempFile(tempFileManager, fileName.endsWith(".html") ? ".html" : ".zip")) {
+                    new TempFile(
+                            tempFileManager,
+                            fileName.toLowerCase().endsWith(".html") ? ".html" : ".zip")) {
 
-                if (fileName.endsWith(".html")) {
+                if (fileName.toLowerCase().endsWith(".html")) {
                     String sanitizedHtml =
                             sanitizeHtmlContent(
                                     new String(fileBytes, StandardCharsets.UTF_8), disableSanitize);
                     Files.write(
                             tempInputFile.getPath(),
                             sanitizedHtml.getBytes(StandardCharsets.UTF_8));
-                } else if (fileName.endsWith(".zip")) {
+                } else if (fileName.toLowerCase().endsWith(".zip")) {
                     Files.write(tempInputFile.getPath(), fileBytes);
                     sanitizeHtmlFilesInZip(
                             tempInputFile.getPath(), disableSanitize, tempFileManager);
                 } else {
-                    throw new IllegalArgumentException("Unsupported file format: " + fileName);
+                    throw ExceptionUtils.createHtmlFileRequiredException();
                 }
 
                 List<String> command = new ArrayList<>();

common/src/main/java/stirling/software/common/util/PdfErrorUtils.java

@@ -0,0 +1,55 @@
+package stirling.software.common.util;
+
+import java.io.IOException;
+
+/** Utility class for detecting and handling PDF-related errors. */
+public class PdfErrorUtils {
+
+    /**
+     * Checks if an IOException indicates a corrupted PDF file.
+     *
+     * @param e the IOException to check
+     * @return true if the error indicates PDF corruption, false otherwise
+     */
+    public static boolean isCorruptedPdfError(IOException e) {
+        return isCorruptedPdfError(e.getMessage());
+    }
+
+    /**
+     * Checks if any Exception indicates a corrupted PDF file.
+     *
+     * @param e the Exception to check
+     * @return true if the error indicates PDF corruption, false otherwise
+     */
+    public static boolean isCorruptedPdfError(Exception e) {
+        return isCorruptedPdfError(e.getMessage());
+    }
+
+    /**
+     * Checks if an error message indicates a corrupted PDF file.
+     *
+     * @param message the error message to check
+     * @return true if the message indicates PDF corruption, false otherwise
+     */
+    private static boolean isCorruptedPdfError(String message) {
+        if (message == null) return false;
+
+        // Check for common corruption indicators
+        return message.contains("Missing root object specification")
+                || message.contains("Header doesn't contain versioninfo")
+                || message.contains("Expected trailer")
+                || message.contains("Invalid PDF")
+                || message.contains("Corrupted")
+                || message.contains("damaged")
+                || message.contains("Unknown dir object")
+                || message.contains("Can't dereference COSObject")
+                || message.contains("parseCOSString string should start with")
+                || message.contains("ICCBased colorspace array must have a stream")
+                || message.contains("1-based index not found")
+                || message.contains("Invalid dictionary, found:")
+                || message.contains("AES initialization vector not fully read")
+                || message.contains("BadPaddingException")
+                || message.contains("Given final block not properly padded")
+                || message.contains("End-of-File, expected line");
+    }
+}

common/src/main/java/stirling/software/common/util/PdfUtils.java

@@ -42,26 +42,34 @@ public class PdfUtils {
 
     public static PDRectangle textToPageSize(String size) {
         switch (size.toUpperCase()) {
-            case "A0":
+            case "A0" -> {
                 return PDRectangle.A0;
-            case "A1":
+            }
+            case "A1" -> {
                 return PDRectangle.A1;
-            case "A2":
+            }
+            case "A2" -> {
                 return PDRectangle.A2;
-            case "A3":
+            }
+            case "A3" -> {
                 return PDRectangle.A3;
-            case "A4":
+            }
+            case "A4" -> {
                 return PDRectangle.A4;
-            case "A5":
+            }
+            case "A5" -> {
                 return PDRectangle.A5;
-            case "A6":
+            }
+            case "A6" -> {
                 return PDRectangle.A6;
-            case "LETTER":
+            }
+            case "LETTER" -> {
                 return PDRectangle.LETTER;
-            case "LEGAL":
+            }
+            case "LEGAL" -> {
                 return PDRectangle.LEGAL;
-            default:
-                throw new IllegalArgumentException("Invalid standard page size: " + size);
+            }
+            default -> throw ExceptionUtils.createInvalidPageSizeException(size);
         }
     }
 
@@ -135,6 +143,17 @@ public class PdfUtils {
             int DPI,
             String filename)
             throws IOException, Exception {
+
+        // Validate and limit DPI to prevent excessive memory usage
+        final int MAX_SAFE_DPI = 500; // Maximum safe DPI to prevent memory issues
+        if (DPI > MAX_SAFE_DPI) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.dpiExceedsLimit",
+                    "DPI value {0} exceeds maximum safe limit of {1}. High DPI values can cause memory issues and crashes. Please use a lower DPI value.",
+                    DPI,
+                    MAX_SAFE_DPI);
+        }
+
         try (PDDocument document = pdfDocumentFactory.load(inputStream)) {
             PDFRenderer pdfRenderer = new PDFRenderer(document);
             pdfRenderer.setSubsamplingAllowed(true);
@@ -158,7 +177,21 @@ public class PdfUtils {
                         writer.prepareWriteSequence(null);
 
                         for (int i = 0; i < pageCount; ++i) {
-                            BufferedImage image = pdfRenderer.renderImageWithDPI(i, DPI, colorType);
+                            BufferedImage image;
+                            try {
+                                image = pdfRenderer.renderImageWithDPI(i, 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;
+                            }
                             writer.writeToSequence(new IIOImage(image, null, null), param);
                         }
 
@@ -190,7 +223,20 @@ public class PdfUtils {
                         PdfImageDimensionValue dimension = pageSizes.get(settings);
                         if (dimension == null) {
                             // Render the image to get the dimensions
-                            pdfSizeImage = pdfRenderer.renderImageWithDPI(i, DPI, colorType);
+                            try {
+                                pdfSizeImage = pdfRenderer.renderImageWithDPI(i, 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;
+                            }
                             pdfSizeImageIndex = i;
                             dimension =
                                     new PdfImageDimensionValue(
@@ -218,7 +264,20 @@ public class PdfUtils {
                         if (firstImageAlreadyRendered && i == 0) {
                             pageImage = pdfSizeImage;
                         } else {
-                            pageImage = pdfRenderer.renderImageWithDPI(i, DPI, colorType);
+                            try {
+                                pageImage = pdfRenderer.renderImageWithDPI(i, 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
@@ -238,7 +297,20 @@ public class PdfUtils {
                 // Zip the images and return as byte array
                 try (ZipOutputStream zos = new ZipOutputStream(baos)) {
                     for (int i = 0; i < pageCount; ++i) {
-                        BufferedImage image = pdfRenderer.renderImageWithDPI(i, DPI, colorType);
+                        BufferedImage image;
+                        try {
+                            image = pdfRenderer.renderImageWithDPI(i, 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;
+                        }
                         try (ByteArrayOutputStream baosImage = new ByteArrayOutputStream()) {
                             ImageIO.write(image, imageType, baosImage);
 
@@ -276,7 +348,19 @@ public class PdfUtils {
         PDFRenderer pdfRenderer = new PDFRenderer(document);
         pdfRenderer.setSubsamplingAllowed(true);
         for (int page = 0; page < document.getNumberOfPages(); ++page) {
-            BufferedImage bim = pdfRenderer.renderImageWithDPI(page, 300, ImageType.RGB);
+            BufferedImage bim;
+            try {
+                bim = pdfRenderer.renderImageWithDPI(page, 300, ImageType.RGB);
+            } catch (IllegalArgumentException e) {
+                if (e.getMessage() != null
+                        && e.getMessage().contains("Maximum size of image exceeded")) {
+                    throw ExceptionUtils.createIllegalArgumentException(
+                            "error.pageTooBigFor300Dpi",
+                            "PDF page {0} is too large to render at 300 DPI. The resulting image would exceed Java's maximum array size. Please use a lower DPI value for PDF-to-image conversion.",
+                            page + 1);
+                }
+                throw e;
+            }
             PDPage originalPage = document.getPage(page);
 
             float width = originalPage.getMediaBox().getWidth();
@@ -349,7 +433,7 @@ public class PdfUtils {
             }
             ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
             doc.save(byteArrayOutputStream);
-            log.info("PDF successfully saved to byte array");
+            log.debug("PDF successfully saved to byte array");
             return byteArrayOutputStream.toByteArray();
         }
     }
@@ -495,8 +579,7 @@ public class PdfUtils {
             case "less":
                 return actualPageCount < pageCount;
             default:
-                throw new IllegalArgumentException(
-                        "Invalid comparator. Only 'greater', 'equal', and 'less' are supported.");
+                throw ExceptionUtils.createInvalidArgumentException("comparator", comparator);
         }
     }
 

common/src/main/java/stirling/software/common/util/ProcessExecutor.java

@@ -84,6 +84,16 @@ public class ProcessExecutor {
                                                 .getProcessExecutor()
                                                 .getSessionLimit()
                                                 .getCalibreSessionLimit();
+                                case GHOSTSCRIPT ->
+                                        applicationProperties
+                                                .getProcessExecutor()
+                                                .getSessionLimit()
+                                                .getGhostscriptSessionLimit();
+                                case OCR_MY_PDF ->
+                                        applicationProperties
+                                                .getProcessExecutor()
+                                                .getSessionLimit()
+                                                .getOcrMyPdfSessionLimit();
                             };
 
                     long timeoutMinutes =
@@ -128,6 +138,16 @@ public class ProcessExecutor {
                                                 .getProcessExecutor()
                                                 .getTimeoutMinutes()
                                                 .getCalibreTimeoutMinutes();
+                                case GHOSTSCRIPT ->
+                                        applicationProperties
+                                                .getProcessExecutor()
+                                                .getTimeoutMinutes()
+                                                .getGhostscriptTimeoutMinutes();
+                                case OCR_MY_PDF ->
+                                        applicationProperties
+                                                .getProcessExecutor()
+                                                .getTimeoutMinutes()
+                                                .getOcrMyPdfTimeoutMinutes();
                             };
                     return new ProcessExecutor(semaphoreLimit, liveUpdates, timeoutMinutes);
                 });
@@ -278,7 +298,9 @@ public class ProcessExecutor {
         INSTALL_APP,
         CALIBRE,
         TESSERACT,
-        QPDF
+        QPDF,
+        GHOSTSCRIPT,
+        OCR_MY_PDF
     }
 
     public class ProcessExecutorResult {

common/src/main/java/stirling/software/common/util/misc/CustomColorReplaceStrategy.java

@@ -108,6 +108,12 @@ public class CustomColorReplaceStrategy extends ReplaceAndInvertColorStrategy {
                         } catch (IllegalArgumentException ie) {
                             log.info("text not supported by font ");
                             font = checkSupportedFontForCharacter(unicodeText);
+                        } catch (UnsupportedOperationException ue) {
+                            log.info(
+                                    "font does not support encoding operation: {} for text: '{}'",
+                                    font.getClass().getSimpleName(),
+                                    unicodeText);
+                            font = checkSupportedFontForCharacter(unicodeText);
                         } finally {
                             // if any other font is not supported, then replace default character *
                             if (font == null) {

common/src/test/java/stirling/software/common/annotations/AutoJobPostMappingIntegrationTest.java

@@ -126,7 +126,7 @@ class AutoJobPostMappingIntegrationTest {
 
         verify(jobExecutorService).runJobGeneric(
                 asyncCaptor.capture(),
-                workCaptor.capture(), 
+                workCaptor.capture(),
                 timeoutCaptor.capture(),
                 queueableCaptor.capture(),
                 resourceWeightCaptor.capture());
@@ -197,7 +197,7 @@ class AutoJobPostMappingIntegrationTest {
         autoJobAspect.wrapWithJobExecution(joinPoint, autoJobPostMapping);
 
         // Then
-        assertEquals("stored-file-id", pdfFile.getFileId(), 
+        assertEquals("stored-file-id", pdfFile.getFileId(),
                 "FileId should be set to the stored file id");
         assertNotNull(pdfFile.getFileInput(), "FileInput should be replaced with persistent file");
 

common/src/test/java/stirling/software/common/service/FileStorageTest.java

@@ -187,4 +187,4 @@ class FileStorageTest {
         // Assert
         assertFalse(result);
     }
-}
+}

common/src/test/java/stirling/software/common/service/JobExecutorServiceTest.java

@@ -64,8 +64,8 @@ class JobExecutorServiceTest {
     void setUp() {
         // Initialize the service manually with all its dependencies
         jobExecutorService = new JobExecutorService(
-                taskManager, 
-                fileStorage, 
+                taskManager,
+                fileStorage,
                 request,
                 resourceMonitor,
                 jobQueue,
@@ -199,4 +199,4 @@ class JobExecutorServiceTest {
             assertTrue(e.getCause() instanceof TimeoutException);
         }
     }
-}
+}

common/src/test/java/stirling/software/common/service/JobQueueTest.java

@@ -36,7 +36,7 @@ class JobQueueTest {
         // Mark stubbing as lenient to avoid UnnecessaryStubbingException
         lenient().when(resourceMonitor.calculateDynamicQueueCapacity(anyInt(), anyInt())).thenReturn(10);
         lenient().when(resourceMonitor.getCurrentStatus()).thenReturn(statusRef);
-        
+
         // Initialize JobQueue with mocked ResourceMonitor
         jobQueue = new JobQueue(resourceMonitor);
     }
@@ -99,4 +99,4 @@ class JobQueueTest {
         assertTrue(jobQueue.isJobQueued(jobId));
         assertFalse(jobQueue.isJobQueued("nonexistent"));
     }
-}
+}

common/src/test/java/stirling/software/common/service/ResourceMonitorTest.java

@@ -117,7 +117,7 @@ class ResourceMonitorTest {
 
         // Then
         assertEquals(shouldQueue, result,
-                String.format("For weight %d and status %s, shouldQueue should be %s", 
+                String.format("For weight %d and status %s, shouldQueue should be %s",
                         weight, status, shouldQueue));
     }
 
@@ -134,4 +134,4 @@ class ResourceMonitorTest {
         assertTrue(staleMetrics.isStale(5000), "Metrics from 6 seconds ago should be stale with 5s threshold");
         assertFalse(freshMetrics.isStale(5000), "Fresh metrics should not be stale");
     }
-}
+}

common/src/test/java/stirling/software/common/service/TaskManagerTest.java

@@ -18,6 +18,7 @@ import org.springframework.test.util.ReflectionTestUtils;
 
 import stirling.software.common.model.job.JobResult;
 import stirling.software.common.model.job.JobStats;
+import stirling.software.common.model.job.ResultFile;
 
 class TaskManagerTest {
 
@@ -73,13 +74,17 @@ class TaskManagerTest {
     }
 
     @Test
-    void testSetFileResult() {
+    void testSetFileResult() throws Exception {
         // Arrange
         String jobId = UUID.randomUUID().toString();
         taskManager.createTask(jobId);
         String fileId = "file-id";
         String originalFileName = "test.pdf";
         String contentType = "application/pdf";
+        long fileSize = 1024L;
+
+        // Mock the fileStorage.getFileSize() call
+        when(fileStorage.getFileSize(fileId)).thenReturn(fileSize);
 
         // Act
         taskManager.setFileResult(jobId, fileId, originalFileName, contentType);
@@ -88,9 +93,17 @@ class TaskManagerTest {
         JobResult result = taskManager.getJobResult(jobId);
         assertNotNull(result);
         assertTrue(result.isComplete());
-        assertEquals(fileId, result.getFileId());
-        assertEquals(originalFileName, result.getOriginalFileName());
-        assertEquals(contentType, result.getContentType());
+        assertTrue(result.hasFiles());
+        assertFalse(result.hasMultipleFiles());
+        
+        var resultFiles = result.getAllResultFiles();
+        assertEquals(1, resultFiles.size());
+        
+        ResultFile resultFile = resultFiles.get(0);
+        assertEquals(fileId, resultFile.getFileId());
+        assertEquals(originalFileName, resultFile.getFileName());
+        assertEquals(contentType, resultFile.getContentType());
+        assertEquals(fileSize, resultFile.getFileSize());
         assertNotNull(result.getCompletedAt());
     }
 
@@ -163,8 +176,11 @@ class TaskManagerTest {
     }
 
     @Test
-    void testGetJobStats() {
+    void testGetJobStats() throws Exception {
         // Arrange
+        // Mock fileStorage.getFileSize for file operations
+        when(fileStorage.getFileSize("file-id")).thenReturn(1024L);
+        
         // 1. Create active job
         String activeJobId = "active-job";
         taskManager.createTask(activeJobId);
@@ -216,9 +232,15 @@ class TaskManagerTest {
         LocalDateTime oldTime = LocalDateTime.now().minusHours(1);
         ReflectionTestUtils.setField(oldJob, "completedAt", oldTime);
         ReflectionTestUtils.setField(oldJob, "complete", true);
-        ReflectionTestUtils.setField(oldJob, "fileId", "file-id");
-        ReflectionTestUtils.setField(oldJob, "originalFileName", "test.pdf");
-        ReflectionTestUtils.setField(oldJob, "contentType", "application/pdf");
+        
+        // Create a ResultFile and set it using the new approach
+        ResultFile resultFile = ResultFile.builder()
+                .fileId("file-id")
+                .fileName("test.pdf")
+                .contentType("application/pdf")
+                .fileSize(1024L)
+                .build();
+        ReflectionTestUtils.setField(oldJob, "resultFiles", java.util.List.of(resultFile));
 
         when(fileStorage.deleteFile("file-id")).thenReturn(true);
 
@@ -252,17 +274,17 @@ class TaskManagerTest {
         // Verify the executor service is shutdown
         // This is difficult to test directly, but we can verify it doesn't throw exceptions
     }
-    
+
     @Test
     void testAddNote() {
         // Arrange
         String jobId = UUID.randomUUID().toString();
         taskManager.createTask(jobId);
         String note = "Test note";
-        
+
         // Act
         boolean result = taskManager.addNote(jobId, note);
-        
+
         // Assert
         assertTrue(result);
         JobResult jobResult = taskManager.getJobResult(jobId);
@@ -271,16 +293,16 @@ class TaskManagerTest {
         assertEquals(1, jobResult.getNotes().size());
         assertEquals(note, jobResult.getNotes().get(0));
     }
-    
+
     @Test
     void testAddNote_NonExistentJob() {
         // Arrange
         String jobId = "non-existent-job";
         String note = "Test note";
-        
+
         // Act
         boolean result = taskManager.addNote(jobId, note);
-        
+
         // Assert
         assertFalse(result);
     }

common/src/test/java/stirling/software/common/service/TempFileCleanupServiceTest.java

@@ -82,10 +82,10 @@ public class TempFileCleanupServiceTest {
         when(tempFileManagement.isStartupCleanup()).thenReturn(false);
         when(tempFileManagement.isCleanupSystemTemp()).thenReturn(false);
         when(tempFileManagement.getCleanupIntervalMinutes()).thenReturn(30L);
-        
+
         // Set machineType using reflection (still needed for this field)
         ReflectionTestUtils.setField(cleanupService, "machineType", "Standard");
-        
+
         when(tempFileManager.getMaxAgeMillis()).thenReturn(3600000L); // 1 hour
     }
 
@@ -113,30 +113,30 @@ public class TempFileCleanupServiceTest {
         Path ourTempFile3 = Files.createFile(customTempDir.resolve("stirling-pdf-789.tmp"));
         Path ourTempFile4 = Files.createFile(customTempDir.resolve("pdf-save-123-456.tmp"));
         Path ourTempFile5 = Files.createFile(libreOfficeTempDir.resolve("input_file.pdf"));
-        
+
         // Old temporary files
         Path oldTempFile = Files.createFile(systemTempDir.resolve("output_old.pdf"));
-        
+
         // System temp files that should be cleaned in container mode
         Path sysTempFile1 = Files.createFile(systemTempDir.resolve("lu123abc.tmp"));
         Path sysTempFile2 = Files.createFile(customTempDir.resolve("ocr_process123"));
         Path sysTempFile3 = Files.createFile(customTempDir.resolve("tmp_upload.tmp"));
-        
+
         // Files that should be preserved
         Path jettyFile1 = Files.createFile(systemTempDir.resolve("jetty-123.tmp"));
         Path jettyFile2 = Files.createFile(systemTempDir.resolve("something-with-jetty-inside.tmp"));
         Path regularFile = Files.createFile(systemTempDir.resolve("important.txt"));
-        
+
         // Create a nested directory with temp files
         Path nestedDir = Files.createDirectories(systemTempDir.resolve("nested"));
         Path nestedTempFile = Files.createFile(nestedDir.resolve("output_nested.pdf"));
-        
+
         // Empty file (special case)
         Path emptyFile = Files.createFile(systemTempDir.resolve("empty.tmp"));
-        
+
         // Configure mock registry to say these files aren't registered
         when(registry.contains(any(File.class))).thenReturn(false);
-        
+
         // The set of files that will be deleted in our test
         Set<Path> deletedFiles = new HashSet<>();
 
@@ -145,31 +145,31 @@ public class TempFileCleanupServiceTest {
             // Mock Files.list for each directory we'll process
             mockedFiles.when(() -> Files.list(eq(systemTempDir)))
                     .thenReturn(Stream.of(
-                            ourTempFile1, ourTempFile2, oldTempFile, sysTempFile1, 
+                            ourTempFile1, ourTempFile2, oldTempFile, sysTempFile1,
                             jettyFile1, jettyFile2, regularFile, emptyFile, nestedDir));
-            
+
             mockedFiles.when(() -> Files.list(eq(customTempDir)))
                     .thenReturn(Stream.of(ourTempFile3, ourTempFile4, sysTempFile2, sysTempFile3));
-            
+
             mockedFiles.when(() -> Files.list(eq(libreOfficeTempDir)))
                     .thenReturn(Stream.of(ourTempFile5));
-            
+
             mockedFiles.when(() -> Files.list(eq(nestedDir)))
                     .thenReturn(Stream.of(nestedTempFile));
-            
+
             // Configure Files.isDirectory for each path
             mockedFiles.when(() -> Files.isDirectory(eq(nestedDir))).thenReturn(true);
             mockedFiles.when(() -> Files.isDirectory(any(Path.class))).thenReturn(false);
-            
+
             // Configure Files.exists to return true for all paths
             mockedFiles.when(() -> Files.exists(any(Path.class))).thenReturn(true);
-            
+
             // Configure Files.getLastModifiedTime to return different times based on file names
             mockedFiles.when(() -> Files.getLastModifiedTime(any(Path.class)))
                     .thenAnswer(invocation -> {
                         Path path = invocation.getArgument(0);
                         String fileName = path.getFileName().toString();
-                        
+
                         // For files with "old" in the name, return a timestamp older than maxAgeMillis
                         if (fileName.contains("old")) {
                             return FileTime.fromMillis(System.currentTimeMillis() - 5000000);
@@ -183,13 +183,13 @@ public class TempFileCleanupServiceTest {
                             return FileTime.fromMillis(System.currentTimeMillis() - 60000); // 1 minute ago
                         }
                     });
-            
+
             // Configure Files.size to return different sizes based on file names
             mockedFiles.when(() -> Files.size(any(Path.class)))
                     .thenAnswer(invocation -> {
                         Path path = invocation.getArgument(0);
                         String fileName = path.getFileName().toString();
-                        
+
                         // Return 0 bytes for the empty file
                         if (fileName.equals("empty.tmp")) {
                             return 0L;
@@ -199,7 +199,7 @@ public class TempFileCleanupServiceTest {
                             return 1024L; // 1 KB
                         }
                     });
-            
+
             // For deleteIfExists, track which files would be deleted
             mockedFiles.when(() -> Files.deleteIfExists(any(Path.class)))
                     .thenAnswer(invocation -> {
@@ -207,28 +207,28 @@ public class TempFileCleanupServiceTest {
                         deletedFiles.add(path);
                         return true;
                     });
-            
+
             // Act - set containerMode to false for this test
             invokeCleanupDirectoryStreaming(systemTempDir, false, 0, 3600000);
             invokeCleanupDirectoryStreaming(customTempDir, false, 0, 3600000);
             invokeCleanupDirectoryStreaming(libreOfficeTempDir, false, 0, 3600000);
-            
+
             // Assert - Only old temp files and empty files should be deleted
             assertTrue(deletedFiles.contains(oldTempFile), "Old temp file should be deleted");
             assertTrue(deletedFiles.contains(emptyFile), "Empty file should be deleted");
-            
+
             // Regular temp files should not be deleted because they're too new
             assertFalse(deletedFiles.contains(ourTempFile1), "Recent temp file should be preserved");
             assertFalse(deletedFiles.contains(ourTempFile2), "Recent temp file should be preserved");
             assertFalse(deletedFiles.contains(ourTempFile3), "Recent temp file should be preserved");
             assertFalse(deletedFiles.contains(ourTempFile4), "Recent temp file should be preserved");
             assertFalse(deletedFiles.contains(ourTempFile5), "Recent temp file should be preserved");
-            
+
             // System temp files should not be deleted in non-container mode
             assertFalse(deletedFiles.contains(sysTempFile1), "System temp file should be preserved in non-container mode");
             assertFalse(deletedFiles.contains(sysTempFile2), "System temp file should be preserved in non-container mode");
             assertFalse(deletedFiles.contains(sysTempFile3), "System temp file should be preserved in non-container mode");
-            
+
             // Jetty files and regular files should never be deleted
             assertFalse(deletedFiles.contains(jettyFile1), "Jetty file should be preserved");
             assertFalse(deletedFiles.contains(jettyFile2), "File with jetty in name should be preserved");
@@ -242,10 +242,10 @@ public class TempFileCleanupServiceTest {
         Path ourTempFile = Files.createFile(systemTempDir.resolve("output_123.pdf"));
         Path sysTempFile = Files.createFile(systemTempDir.resolve("lu123abc.tmp"));
         Path regularFile = Files.createFile(systemTempDir.resolve("important.txt"));
-        
+
         // Configure mock registry to say these files aren't registered
         when(registry.contains(any(File.class))).thenReturn(false);
-        
+
         // The set of files that will be deleted in our test
         Set<Path> deletedFiles = new HashSet<>();
 
@@ -254,21 +254,21 @@ public class TempFileCleanupServiceTest {
             // Mock Files.list for systemTempDir
             mockedFiles.when(() -> Files.list(eq(systemTempDir)))
                     .thenReturn(Stream.of(ourTempFile, sysTempFile, regularFile));
-            
+
             // Configure Files.isDirectory
             mockedFiles.when(() -> Files.isDirectory(any(Path.class))).thenReturn(false);
-            
+
             // Configure Files.exists
             mockedFiles.when(() -> Files.exists(any(Path.class))).thenReturn(true);
-            
+
             // Configure Files.getLastModifiedTime to return recent timestamps
             mockedFiles.when(() -> Files.getLastModifiedTime(any(Path.class)))
                     .thenReturn(FileTime.fromMillis(System.currentTimeMillis() - 60000)); // 1 minute ago
-            
+
             // Configure Files.size to return normal size
             mockedFiles.when(() -> Files.size(any(Path.class)))
                     .thenReturn(1024L); // 1 KB
-            
+
             // For deleteIfExists, track which files would be deleted
             mockedFiles.when(() -> Files.deleteIfExists(any(Path.class)))
                     .thenAnswer(invocation -> {
@@ -276,10 +276,10 @@ public class TempFileCleanupServiceTest {
                         deletedFiles.add(path);
                         return true;
                     });
-            
+
             // Act - set containerMode to true and maxAgeMillis to 0 for container startup cleanup
             invokeCleanupDirectoryStreaming(systemTempDir, true, 0, 0);
-            
+
             // Assert - In container mode, both our temp files and system temp files should be deleted
             // regardless of age (when maxAgeMillis is 0)
             assertTrue(deletedFiles.contains(ourTempFile), "Our temp file should be deleted in container mode");
@@ -293,10 +293,10 @@ public class TempFileCleanupServiceTest {
         // Arrange - Create an empty file
         Path emptyFile = Files.createFile(systemTempDir.resolve("empty.tmp"));
         Path recentEmptyFile = Files.createFile(systemTempDir.resolve("recent_empty.tmp"));
-        
+
         // Configure mock registry to say these files aren't registered
         when(registry.contains(any(File.class))).thenReturn(false);
-        
+
         // The set of files that will be deleted in our test
         Set<Path> deletedFiles = new HashSet<>();
 
@@ -305,19 +305,19 @@ public class TempFileCleanupServiceTest {
             // Mock Files.list for systemTempDir
             mockedFiles.when(() -> Files.list(eq(systemTempDir)))
                     .thenReturn(Stream.of(emptyFile, recentEmptyFile));
-            
+
             // Configure Files.isDirectory
             mockedFiles.when(() -> Files.isDirectory(any(Path.class))).thenReturn(false);
-            
+
             // Configure Files.exists
             mockedFiles.when(() -> Files.exists(any(Path.class))).thenReturn(true);
-            
+
             // Configure Files.getLastModifiedTime to return different times based on file names
             mockedFiles.when(() -> Files.getLastModifiedTime(any(Path.class)))
                     .thenAnswer(invocation -> {
                         Path path = invocation.getArgument(0);
                         String fileName = path.getFileName().toString();
-                        
+
                         if (fileName.equals("empty.tmp")) {
                             // More than 5 minutes old
                             return FileTime.fromMillis(System.currentTimeMillis() - 6 * 60 * 1000);
@@ -326,11 +326,11 @@ public class TempFileCleanupServiceTest {
                             return FileTime.fromMillis(System.currentTimeMillis() - 2 * 60 * 1000);
                         }
                     });
-            
+
             // Configure Files.size to return 0 for empty files
             mockedFiles.when(() -> Files.size(any(Path.class)))
                     .thenReturn(0L);
-            
+
             // For deleteIfExists, track which files would be deleted
             mockedFiles.when(() -> Files.deleteIfExists(any(Path.class)))
                     .thenAnswer(invocation -> {
@@ -338,14 +338,14 @@ public class TempFileCleanupServiceTest {
                         deletedFiles.add(path);
                         return true;
                     });
-            
+
             // Act
             invokeCleanupDirectoryStreaming(systemTempDir, false, 0, 3600000);
-            
+
             // Assert
-            assertTrue(deletedFiles.contains(emptyFile), 
+            assertTrue(deletedFiles.contains(emptyFile),
                     "Empty file older than 5 minutes should be deleted");
-            assertFalse(deletedFiles.contains(recentEmptyFile), 
+            assertFalse(deletedFiles.contains(recentEmptyFile),
                     "Empty file newer than 5 minutes should not be deleted");
         }
     }
@@ -356,14 +356,14 @@ public class TempFileCleanupServiceTest {
         Path dir1 = Files.createDirectories(systemTempDir.resolve("dir1"));
         Path dir2 = Files.createDirectories(dir1.resolve("dir2"));
         Path dir3 = Files.createDirectories(dir2.resolve("dir3"));
-        
+
         Path tempFile1 = Files.createFile(dir1.resolve("output_1.pdf"));
         Path tempFile2 = Files.createFile(dir2.resolve("output_2.pdf"));
         Path tempFile3 = Files.createFile(dir3.resolve("output_old_3.pdf"));
-        
+
         // Configure mock registry to say these files aren't registered
         when(registry.contains(any(File.class))).thenReturn(false);
-        
+
         // The set of files that will be deleted in our test
         Set<Path> deletedFiles = new HashSet<>();
 
@@ -372,16 +372,16 @@ public class TempFileCleanupServiceTest {
             // Mock Files.list for each directory
             mockedFiles.when(() -> Files.list(eq(systemTempDir)))
                     .thenReturn(Stream.of(dir1));
-            
+
             mockedFiles.when(() -> Files.list(eq(dir1)))
                     .thenReturn(Stream.of(tempFile1, dir2));
-            
+
             mockedFiles.when(() -> Files.list(eq(dir2)))
                     .thenReturn(Stream.of(tempFile2, dir3));
-            
+
             mockedFiles.when(() -> Files.list(eq(dir3)))
                     .thenReturn(Stream.of(tempFile3));
-            
+
             // Configure Files.isDirectory for each path
             mockedFiles.when(() -> Files.isDirectory(eq(dir1))).thenReturn(true);
             mockedFiles.when(() -> Files.isDirectory(eq(dir2))).thenReturn(true);
@@ -389,16 +389,16 @@ public class TempFileCleanupServiceTest {
             mockedFiles.when(() -> Files.isDirectory(eq(tempFile1))).thenReturn(false);
             mockedFiles.when(() -> Files.isDirectory(eq(tempFile2))).thenReturn(false);
             mockedFiles.when(() -> Files.isDirectory(eq(tempFile3))).thenReturn(false);
-            
+
             // Configure Files.exists to return true for all paths
             mockedFiles.when(() -> Files.exists(any(Path.class))).thenReturn(true);
-            
+
             // Configure Files.getLastModifiedTime to return different times based on file names
             mockedFiles.when(() -> Files.getLastModifiedTime(any(Path.class)))
                     .thenAnswer(invocation -> {
                         Path path = invocation.getArgument(0);
                         String fileName = path.getFileName().toString();
-                        
+
                         if (fileName.contains("old")) {
                             // Old file
                             return FileTime.fromMillis(System.currentTimeMillis() - 5000000);
@@ -407,11 +407,11 @@ public class TempFileCleanupServiceTest {
                             return FileTime.fromMillis(System.currentTimeMillis() - 60000);
                         }
                     });
-            
+
             // Configure Files.size to return normal size
             mockedFiles.when(() -> Files.size(any(Path.class)))
                     .thenReturn(1024L);
-            
+
             // For deleteIfExists, track which files would be deleted
             mockedFiles.when(() -> Files.deleteIfExists(any(Path.class)))
                     .thenAnswer(invocation -> {
@@ -419,14 +419,14 @@ public class TempFileCleanupServiceTest {
                         deletedFiles.add(path);
                         return true;
                     });
-            
+
             // Act
             invokeCleanupDirectoryStreaming(systemTempDir, false, 0, 3600000);
-            
+
             // Debug - print what was deleted
             System.out.println("Deleted files: " + deletedFiles);
             System.out.println("Looking for: " + tempFile3);
-            
+
             // Assert
             assertFalse(deletedFiles.contains(tempFile1), "Recent temp file should be preserved");
             assertFalse(deletedFiles.contains(tempFile2), "Recent temp file should be preserved");
@@ -437,28 +437,28 @@ public class TempFileCleanupServiceTest {
     /**
      * Helper method to invoke the private cleanupDirectoryStreaming method using reflection
      */
-    private void invokeCleanupDirectoryStreaming(Path directory, boolean containerMode, int depth, long maxAgeMillis) 
+    private void invokeCleanupDirectoryStreaming(Path directory, boolean containerMode, int depth, long maxAgeMillis)
             throws IOException {
         try {
             // Create a consumer that tracks deleted files
             AtomicInteger deleteCount = new AtomicInteger(0);
             Consumer<Path> deleteCallback = path -> deleteCount.incrementAndGet();
-            
+
             // Get the method with updated signature
             var method = TempFileCleanupService.class.getDeclaredMethod(
-                    "cleanupDirectoryStreaming", 
+                    "cleanupDirectoryStreaming",
                     Path.class, boolean.class, int.class, long.class, boolean.class, Consumer.class);
             method.setAccessible(true);
-            
+
             // Invoke the method with appropriate parameters
             method.invoke(cleanupService, directory, containerMode, depth, maxAgeMillis, false, deleteCallback);
         } catch (Exception e) {
             throw new RuntimeException("Error invoking cleanupDirectoryStreaming", e);
         }
     }
-    
+
     // Matcher for exact path equality
     private static Path eq(Path path) {
         return argThat(arg -> arg != null && arg.equals(path));
     }
-}
+}

common/src/test/java/stirling/software/common/util/FileToPdfTest.java

@@ -27,7 +27,7 @@ public class FileToPdfTest {
         String fileName = "test.html"; // Sample file name indicating an HTML file
         boolean disableSanitize = false; // Flag to control sanitization
         TempFileManager tempFileManager = mock(TempFileManager.class); // Mock TempFileManager
-        
+
         // Mock the temp file creation to return real temp files
         try {
             when(tempFileManager.createTempFile(anyString()))

common/src/test/java/stirling/software/common/util/SpringContextHolderTest.java

@@ -22,7 +22,7 @@ class SpringContextHolderTest {
     void testSetApplicationContext() {
         // Act
         contextHolder.setApplicationContext(mockApplicationContext);
-        
+
         // Assert
         assertTrue(SpringContextHolder.isInitialized());
     }
@@ -33,10 +33,10 @@ class SpringContextHolderTest {
         contextHolder.setApplicationContext(mockApplicationContext);
         TestBean expectedBean = new TestBean();
         when(mockApplicationContext.getBean(TestBean.class)).thenReturn(expectedBean);
-        
+
         // Act
         TestBean result = SpringContextHolder.getBean(TestBean.class);
-        
+
         // Assert
         assertSame(expectedBean, result);
         verify(mockApplicationContext).getBean(TestBean.class);
@@ -46,10 +46,10 @@ class SpringContextHolderTest {
     @Test
     void testGetBean_ApplicationContextNotSet() {
         // Don't set application context
-        
+
         // Act
         TestBean result = SpringContextHolder.getBean(TestBean.class);
-        
+
         // Assert
         assertNull(result);
     }
@@ -59,10 +59,10 @@ class SpringContextHolderTest {
         // Arrange
         contextHolder.setApplicationContext(mockApplicationContext);
         when(mockApplicationContext.getBean(TestBean.class)).thenThrow(new org.springframework.beans.BeansException("Bean not found") {});
-        
+
         // Act
         TestBean result = SpringContextHolder.getBean(TestBean.class);
-        
+
         // Assert
         assertNull(result);
     }
@@ -70,4 +70,4 @@ class SpringContextHolderTest {
     // Simple test class
     private static class TestBean {
     }
-}
+}

devGuide/DeveloperGuide.md

@@ -0,0 +1,588 @@
+# Stirling-PDF Developer Guide
+
+## 1. Introduction
+
+Stirling-PDF is a robust, locally hosted, web-based PDF manipulation tool. This guide focuses on Docker-based development and testing, which is the recommended approach for working with the full version of Stirling-PDF.
+
+## 2. Project Overview
+
+Stirling-PDF is built using:
+
+- Spring Boot + Thymeleaf
+- PDFBox
+- LibreOffice
+- qpdf
+- HTML, CSS, JavaScript
+- Docker
+- PDF.js
+- PDF-LIB.js
+- Lombok
+
+## 3. Development Environment Setup
+
+### Prerequisites
+
+- Docker
+- Git
+- Java JDK 17 or later
+- Gradle 7.0 or later (Included within the repo)
+
+### Setup Steps
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/Stirling-Tools/Stirling-PDF.git
+   cd Stirling-PDF
+   ```
+
+2. Install Docker and JDK17 if not already installed.
+
+3. Install a recommended Java IDE such as Eclipse, IntelliJ, or VSCode
+   1. Only VSCode
+      1. Open VS Code.
+      2. When prompted, install the recommended extensions.
+      3. Alternatively, open the command palette (`Ctrl + Shift + P` or `Cmd + Shift + P` on macOS) and run:
+
+        ```sh
+        Extensions: Show Recommended Extensions
+        ```
+
+      4. Install the required extensions from the list.
+
+4. Lombok Setup
+Stirling-PDF uses Lombok to reduce boilerplate code. Some IDEs, like Eclipse, don't support Lombok out of the box. To set up Lombok in your development environment:
+Visit the [Lombok website](https://projectlombok.org/setup/) for installation instructions specific to your IDE.
+
+5. Add environment variable
+For local testing, you should generally be testing the full 'Security' version of Stirling PDF. To do this, you must add the environment flag DISABLE_ADDITIONAL_FEATURES=false to your system and/or IDE build/run step.
+
+## 4. Project Structure
+
+```bash
+Stirling-PDF/
+├── .github/               # GitHub-specific files (workflows, issue templates)
+├── configs/               # Configuration files used by stirling at runtime (generated at runtime)
+├── cucumber/              # Cucumber test files
+│   ├── features/
+├── customFiles/           # Custom static files and templates (generated at runtime used to replace existing files)
+├── docs/                  # Documentation files
+├── exampleYmlFiles/       # Example YAML configuration files
+├── images/                # Image assets
+├── pipeline/              # Pipeline-related files (generated at runtime)
+├── scripts/               # Utility scripts
+├── src/                   # Source code
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── stirling/
+│   │   │       └── software/
+│   │   │           └── SPDF/
+│   │   │               ├── config/
+│   │   │               ├── controller/
+│   │   │               ├── model/
+│   │   │               ├── repository/
+│   │   │               ├── service/
+│   │   │               └── utils/
+│   │   └── resources/
+│   │       ├── static/
+│   │       │   ├── css/
+│   │       │   ├── js/
+│   │       │   └── pdfjs/
+│   │       └── templates/
+│   └── test/
+│       └── java/
+│           └── stirling/
+│               └── software/
+│                   └── SPDF/
+├── build.gradle           # Gradle build configuration
+├── Dockerfile             # Main Dockerfile
+├── Dockerfile.ultra-lite  # Dockerfile for ultra-lite version
+├── Dockerfile.fat         # Dockerfile for fat version
+├── docker-compose.yml     # Docker Compose configuration
+└── test.sh                # Test script to deploy all docker versions and run cuke tests
+```
+
+## 5. Docker-based Development
+
+Stirling-PDF offers several Docker versions:
+
+- Full: All features included
+- Ultra-Lite: Basic PDF operations only
+- Fat: Includes additional libraries and fonts predownloaded
+
+### Example Docker Compose Files
+
+Stirling-PDF provides several example Docker Compose files in the `exampleYmlFiles` directory, such as:
+
+- `docker-compose-latest.yml`: Latest version without login and security features
+- `docker-compose-latest-security.yml`: Latest version with login and security features enabled
+- `docker-compose-latest-fat-security.yml`: Fat version with login and security features enabled
+
+These files provide pre-configured setups for different scenarios. For example, here's a snippet from `docker-compose-latest-security.yml`:
+
+```yaml
+services:
+  stirling-pdf:
+    container_name: Stirling-PDF-Security
+    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
+      interval: 5s
+      timeout: 10s
+      retries: 16
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./stirling/latest/data:/usr/share/tessdata:rw
+      - ./stirling/latest/config:/configs:rw
+      - ./stirling/latest/logs:/logs:rw
+    environment:
+      DISABLE_ADDITIONAL_FEATURES: "false"
+      SECURITY_ENABLELOGIN: "true"
+      PUID: 1002
+      PGID: 1002
+      UMASK: "022"
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Demo site for Stirling-PDF Latest with Security
+      UI_APPNAMENAVBAR: Stirling-PDF Latest
+      SYSTEM_MAXFILESIZE: "100"
+      METRICS_ENABLED: "true"
+      SYSTEM_GOOGLEVISIBILITY: "true"
+      SHOW_SURVEY: "true"
+    restart: on-failure:5
+```
+
+To use these example files, copy the desired file to your project root and rename it to `docker-compose.yml`, or specify the file explicitly when running Docker Compose:
+
+```bash
+docker-compose -f exampleYmlFiles/docker-compose-latest-security.yml up
+```
+
+### Building Docker Images
+
+Stirling-PDF uses different Docker images for various configurations. The build process is controlled by environment variables and uses specific Dockerfile variants. Here's how to build the Docker images:
+
+1. Set the security environment variable:
+
+   ```bash
+   export DISABLE_ADDITIONAL_FEATURES=true  # or false for to enable login and security features for builds
+   ```
+
+2. Build the project with Gradle:
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+3. Build the Docker images:
+
+   For the latest version:
+
+   ```bash
+   docker build --no-cache --pull --build-arg VERSION_TAG=alpha -t stirlingtools/stirling-pdf:latest -f ./Dockerfile .
+   ```
+
+   For the ultra-lite version:
+
+   ```bash
+   docker build --no-cache --pull --build-arg VERSION_TAG=alpha -t stirlingtools/stirling-pdf:latest-ultra-lite -f ./Dockerfile.ultra-lite .
+   ```
+
+   For the fat version (with login and security features enabled):
+
+   ```bash
+   export DISABLE_ADDITIONAL_FEATURES=false
+   docker build --no-cache --pull --build-arg VERSION_TAG=alpha -t stirlingtools/stirling-pdf:latest-fat -f ./Dockerfile.fat .
+   ```
+
+Note: The `--no-cache` and `--pull` flags ensure that the build process uses the latest base images and doesn't use cached layers, which is useful for testing and ensuring reproducible builds. however to improve build times these can often be removed depending on your usecase
+
+## 6. Testing
+
+### Comprehensive Testing Script
+
+Stirling-PDF provides a `test.sh` script in the root directory. This script builds all versions of Stirling-PDF, checks that each version works, and runs Cucumber tests. It's recommended to run this script before submitting a final pull request.
+
+To run the test script:
+
+```bash
+./test.sh
+```
+
+This script performs the following actions:
+
+1. Builds all Docker images (full, ultra-lite, fat).
+2. Runs each version to ensure it starts correctly.
+3. Executes Cucumber tests against the main version and ensures feature compatibility. In the event these tests fail, your PR will not be merged.
+
+Note: The `test.sh` script will run automatically when you raise a PR. However, it's recommended to run it locally first to save resources and catch any issues early.
+
+### Full Testing with Docker
+
+1. Build and run the Docker container per the above instructions:
+
+2. Access the application at `http://localhost:8080` and manually test all features developed.
+
+### Local Testing (Java and UI Components)
+
+For quick iterations and development of Java backend, JavaScript, and UI components, you can run and test Stirling-PDF locally without Docker. This approach allows you to work on and verify changes to:
+
+- Java backend logic
+- RESTful API endpoints
+- JavaScript functionality
+- User interface components and styling
+- Thymeleaf templates
+
+To run Stirling-PDF locally:
+
+1. Compile and run the project using built-in IDE methods or by running:
+
+   ```bash
+   ./gradlew bootRun
+   ```
+
+2. Access the application at `http://localhost:8080` in your web browser.
+
+3. Manually test the features you're working on through the UI.
+
+4. For API changes, use tools like Postman or curl to test endpoints directly.
+
+Important notes:
+
+- Local testing doesn't include features that depend on external tools like qpdf, LibreOffice, or Python scripts.
+- There are currently no automated unit tests. All testing is done manually through the UI or API calls. (You are welcome to add JUnits!)
+- Always verify your changes in the full Docker environment before submitting pull requests, as some integrations and features will only work in the complete setup.
+
+## 7. Contributing
+
+1. Fork the repository on GitHub.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them with clear, descriptive messages and ensure any documentation is updated related to your changes.
+4. Test your changes thoroughly in the Docker environment.
+5. Run the `test.sh` script to ensure all versions build correctly and pass the Cucumber tests:
+
+   ```bash
+   ./test.sh
+   ```
+
+6. Push your changes to your fork.
+7. Submit a pull request to the main repository.
+8. See additional [contributing guidelines](../CONTRIBUTING.md).
+
+When you raise a PR:
+
+- The `test.sh` script will run automatically against your PR.
+- The PR checks will verify versioning and dependency updates.
+- Documentation will be automatically updated for dependency changes.
+- Security issues will be checked using Snyk and PixeeBot.
+
+Address any issues that arise from these checks before finalizing your pull request.
+
+## 8. API Documentation
+
+API documentation is available at `/swagger-ui/index.html` when running the application. You can also view the latest API documentation [here](https://app.swaggerhub.com/apis-docs/Stirling-Tools/Stirling-PDF/).
+
+## 9. Customization
+
+Stirling-PDF can be customized through environment variables or a `settings.yml` file. Key customization options include:
+
+- Application name and branding
+- Security settings
+- UI customization
+- Endpoint management
+
+When using Docker, pass environment variables using the `-e` flag or in your `docker-compose.yml` file.
+
+Example:
+
+```bash
+docker run -p 8080:8080 -e APP_NAME="My PDF Tool" stirling-pdf:full
+```
+
+Refer to the main README for a full list of customization options.
+
+## 10. Language Translations
+
+For managing language translations that affect multiple files, Stirling-PDF provides a helper script:
+
+```bash
+/scripts/replace_translation_line.sh
+```
+
+This script helps you make consistent replacements across language files.
+
+When contributing translations:
+
+1. Use the helper script for multi-file changes.
+2. Ensure all language files are updated consistently.
+3. The PR checks will verify consistency in language file updates.
+
+Remember to test your changes thoroughly to ensure they don't break any existing functionality.
+
+## Code examples
+
+### Overview of Thymeleaf
+
+Thymeleaf is a server-side Java HTML template engine. It is used in Stirling-PDF to render dynamic web pages. Thymeleaf integrates heavily with Spring Boot.
+
+### Thymeleaf overview
+
+In Stirling-PDF, Thymeleaf is used to create HTML templates that are rendered on the server side. These templates are located in the `stirling-pdf/src/main/resources/templates` directory. Thymeleaf templates use a combination of HTML and special Thymeleaf attributes to dynamically generate content.
+
+Some examples of this are:
+
+```html
+<th:block th:insert="~{fragments/navbar.html :: navbar}"></th:block>
+```
+or
+```html
+<th:block th:insert="~{fragments/footer.html :: footer}"></th:block>
+```
+
+Where it uses the `th:block`, `th:` indicating it's a special Thymeleaf element to be used server-side in generating the HTML, and block being the actual element type.
+In this case, we are inserting the `navbar` entry within the `fragments/navbar.html` fragment into the `th:block` element.
+
+They can be more complex, such as:
+
+```html
+<th:block th:insert="~{fragments/common :: head(title=#{pageExtracter.title}, header=#{pageExtracter.header})}"></th:block>
+```
+
+Which is the same as above but passes the parameters title and header into the fragment `common.html` to be used in its HTML generation.
+
+Thymeleaf can also be used to loop through objects or pass things from the Java side into the HTML side.
+
+```java
+ @GetMapping
+       public String newFeaturePage(Model model) {
+           model.addAttribute("exampleData", exampleData);
+           return "new-feature";
+       }
+```
+
+In the above example, if exampleData is a list of plain java objects of class Person and within it, you had id, name, age, etc. You can reference it like so
+
+```html
+<tbody>
+   <!-- Use th:each to iterate over the list -->
+   <tr th:each="person : ${exampleData}">
+       <td th:text="${person.id}"></td>
+       <td th:text="${person.name}"></td>
+       <td th:text="${person.age}"></td>
+       <td th:text="${person.email}"></td>
+   </tr>
+</tbody>
+```
+
+This would generate n entries of tr for each person in exampleData
+
+### Adding a New Feature to the Backend (API)
+
+1. **Create a New Controller:**
+   - Create a new Java class in the `stirling-pdf/src/main/java/stirling/software/SPDF/controller/api` directory.
+   - Annotate the class with `@RestController` and `@RequestMapping` to define the API endpoint.
+   - Ensure to add API documentation annotations like `@Tag(name = "General", description = "General APIs")` and `@Operation(summary = "Crops a PDF document", description = "This operation takes an input PDF file and crops it according to the given coordinates. Input:PDF Output:PDF Type:SISO")`.
+
+   ```java
+   package stirling.software.SPDF.controller.api;
+
+   import org.springframework.web.bind.annotation.GetMapping;
+   import org.springframework.web.bind.annotation.RequestMapping;
+   import org.springframework.web.bind.annotation.RestController;
+   import io.swagger.v3.oas.annotations.Operation;
+   import io.swagger.v3.oas.annotations.tags.Tag;
+
+   @RestController
+   @RequestMapping("/api/v1/new-feature")
+   @Tag(name = "General", description = "General APIs")
+   public class NewFeatureController {
+
+       @GetMapping
+       @Operation(summary = "New Feature", description = "This is a new feature endpoint.")
+       public String newFeature() {
+           return "NewFeatureResponse"; // This refers to the NewFeatureResponse.html template presenting the user with the generated html from that file when they navigate to /api/v1/new-feature
+       }
+   }
+   ```
+
+2. **Define the Service Layer:** (Not required but often useful)
+   - Create a new service class in the `stirling-pdf/src/main/java/stirling/software/SPDF/service` directory.
+   - Implement the business logic for the new feature.
+
+   ```java
+   package stirling.software.SPDF.service;
+
+   import org.springframework.stereotype.Service;
+
+   @Service
+   public class NewFeatureService {
+
+       public String getNewFeatureData() {
+           // Implement business logic here
+           return "New Feature Data";
+       }
+   }
+   ```
+
+2b. **Integrate the Service with the Controller:**
+
+- Autowire the service class in the controller and use it to handle the API request.
+
+  ```java
+  package stirling.software.SPDF.controller.api;
+
+  import org.springframework.beans.factory.annotation.Autowired;
+  import org.springframework.web.bind.annotation.GetMapping;
+  import org.springframework.web.bind.annotation.RequestMapping;
+  import org.springframework.web.bind.annotation.RestController;
+  import stirling.software.SPDF.service.NewFeatureService;
+  import io.swagger.v3.oas.annotations.Operation;
+  import io.swagger.v3.oas.annotations.tags.Tag;
+
+  @RestController
+  @RequestMapping("/api/v1/new-feature")
+  @Tag(name = "General", description = "General APIs")
+  public class NewFeatureController {
+
+      @Autowired
+      private NewFeatureService newFeatureService;
+
+      @GetMapping
+      @Operation(summary = "New Feature", description = "This is a new feature endpoint.")
+      public String newFeature() {
+          return newFeatureService.getNewFeatureData();
+      }
+  }
+  ```
+
+### Adding a New Feature to the Frontend (UI)
+
+1. **Create a New Thymeleaf Template:**
+   - Create a new HTML file in the `stirling-pdf/src/main/resources/templates` directory.
+   - Use Thymeleaf attributes to dynamically generate content.
+   - Use `extract-page.html` as a base example for the HTML template, which is useful to ensure importing of the general layout, navbar, and footer.
+
+   ```html
+   <!DOCTYPE html>
+   <html th:lang="${#locale.language}" th:dir="#{language.direction}" th:data-language="${#locale.toString()}" xmlns:th="https://www.thymeleaf.org">
+     <head>
+     <th:block th:insert="~{fragments/common :: head(title=#{newFeature.title}, header=#{newFeature.header})}"></th:block>
+     </head>
+
+     <body>
+       <div id="page-container">
+         <div id="content-wrap">
+           <th:block th:insert="~{fragments/navbar.html :: navbar}"></th:block>
+           <br><br>
+           <div class="container">
+             <div class="row justify-content-center">
+               <div class="col-md-6 bg-card">
+                 <div class="tool-header">
+                   <span class="material-symbols-rounded tool-header-icon organize">upload</span>
+                   <span class="tool-header-text" th:text="#{newFeature.header}"></span>
+                 </div>
+                 <form th:action="@{'/api/v1/new-feature'}" method="post" enctype="multipart/form-data">
+                   <div th:replace="~{fragments/common :: fileSelector(name='fileInput', multipleInputsForSingleRequest=false, accept='application/pdf')}"></div>
+                   <input type="hidden" id="customMode" name="customMode" value="">
+                   <div class="mb-3">
+                     <label for="featureInput" th:text="#{newFeature.prompt}"></label>
+                     <input type="text" class="form-control" id="featureInput" name="featureInput" th:placeholder="#{newFeature.placeholder}" required>
+                   </div>
+
+                   <button type="submit" id="submitBtn" class="btn btn-primary" th:text="#{newFeature.submit}"></button>
+                 </form>
+               </div>
+             </div>
+           </div>
+         </div>
+         <th:block th:insert="~{fragments/footer.html :: footer}"></th:block>
+       </div>
+     </body>
+   </html>
+   ```
+
+2. **Create a New Controller for the UI:**
+   - Create a new Java class in the `stirling-pdf/src/main/java/stirling/software/SPDF/controller/ui` directory.
+   - Annotate the class with `@Controller` and `@RequestMapping` to define the UI endpoint.
+
+   ```java
+   package stirling.software.SPDF.controller.ui;
+
+   import org.springframework.beans.factory.annotation.Autowired;
+   import org.springframework.stereotype.Controller;
+   import org.springframework.ui.Model;
+   import org.springframework.web.bind.annotation.GetMapping;
+   import org.springframework.web.bind.annotation.RequestMapping;
+   import stirling.software.SPDF.service.NewFeatureService;
+
+   @Controller
+   @RequestMapping("/new-feature")
+   public class NewFeatureUIController {
+
+       @Autowired
+       private NewFeatureService newFeatureService;
+
+       @GetMapping
+       public String newFeaturePage(Model model) {
+           model.addAttribute("newFeatureData", newFeatureService.getNewFeatureData());
+           return "new-feature";
+       }
+   }
+   ```
+
+3. **Update the Navigation Bar:**
+   - Add a link to the new feature page in the navigation bar.
+   - Update the `stirling-pdf/src/main/resources/templates/fragments/navbar.html` file.
+
+   ```html
+   <li class="nav-item">
+       <a class="nav-link" th:href="@{'/new-feature'}">New Feature</a>
+   </li>
+   ```
+
+## Adding New Translations to Existing Language Files in Stirling-PDF
+
+When adding a new feature or modifying existing ones in Stirling-PDF, you'll need to add new translation entries to the existing language files. Here's a step-by-step guide:
+
+### 1. Locate Existing Language Files
+
+Find the existing `messages.properties` files in the `stirling-pdf/src/main/resources` directory. You'll see files like:
+
+- `messages.properties` (default, usually English)
+- `messages_en_GB.properties`
+- `messages_fr_FR.properties`
+- `messages_de_DE.properties`
+- etc.
+
+### 2. Add New Translation Entries
+
+Open each of these files and add your new translation entries. For example, if you're adding a new feature called "PDF Splitter",
+Use descriptive, hierarchical keys (e.g., `feature.element.description`)
+you might add:
+
+```properties
+pdfSplitter.title=PDF Splitter
+pdfSplitter.description=Split your PDF into multiple documents
+pdfSplitter.button.split=Split PDF
+pdfSplitter.input.pages=Enter page numbers to split
+```
+
+Add these entries to the default GB language file and any others you wish, translating the values as appropriate for each language.
+
+### 3. Use Translations in Thymeleaf Templates
+
+In your Thymeleaf templates, use the `#{key}` syntax to reference the new translations:
+
+```html
+<h1 th:text="#{pdfSplitter.title}">PDF Splitter</h1>
+<p th:text="#{pdfSplitter.description}">Split your PDF into multiple documents</p>
+<input type="text" th:placeholder="#{pdfSplitter.input.pages}">
+<button th:text="#{pdfSplitter.button.split}">Split PDF</button>
+```
+
+Remember, never hard-code text in your templates or Java code. Always use translation keys to ensure proper localization.

devGuide/EXCEPTION_HANDLING_GUIDE.md

@@ -0,0 +1,66 @@
+# Exception Handling Guide
+
+This guide outlines the common error handling patterns used within Stirling-PDF and provides tips for internationalising error messages. The examples cover the main languages found in the project: Java, JavaScript, HTML/CSS, and a small amount of Python.
+
+## General Principles
+
+- **Fail fast and log clearly.** Exceptions should provide enough information for debugging without exposing sensitive data.
+- **Use consistent user messages.** Text shown to users must be pulled from the localisation files so that translations are centrally managed.
+- **Avoid silent failures.** Always log unexpected errors and provide the user with a helpful message.
+
+## Java
+
+Java forms the core of Stirling-PDF. When adding new features or handling errors:
+
+1. **Create custom exceptions** to represent specific failure cases. This keeps the code self-documenting and easier to handle at higher levels.
+2. **Use `try-with-resources`** when working with streams or other closable resources to ensure clean-up even on failure.
+3. **Return meaningful HTTP status codes** in controllers by throwing `ResponseStatusException` or using `@ExceptionHandler` methods.
+4. **Log with context** using the project’s logging framework. Include identifiers or IDs that help trace the issue.
+5. **Internationalise messages** by placing user-facing text in `messages_en_GB.properties` and referencing them with message keys.
+
+## JavaScript
+
+On the client side, JavaScript handles form validation and user interactions.
+
+- Use `try`/`catch` around asynchronous operations (e.g., `fetch`) and display a translated error notice if the call fails.
+- Validate input before sending it to the server and provide inline feedback with messages from the translation files.
+- Log unexpected errors to the browser console for easier debugging, but avoid revealing sensitive information.
+
+## HTML & CSS
+
+HTML templates should reserve a space for displaying error messages. Example pattern:
+
+```html
+<div class="error" role="alert" th:text="${errorMessage}"></div>
+```
+
+Use CSS classes (e.g., `.error`) to style the message so it is clearly visible and accessible. Keep the markup simple to ensure screen readers can announce the error correctly.
+
+## Python
+
+Python scripts in this project are mainly for utility tasks. Follow these guidelines:
+
+- Wrap file operations or external calls in `try`/`except` blocks.
+- Print or log errors in a consistent format. If the script outputs messages to end users, ensure they are translatable.
+
+Example:
+
+```python
+try:
+  perform_task()
+except Exception as err:
+  logger.error("Task failed: %s", err)
+  print(gettext("task.error"))
+```
+
+## Internationalisation (i18n)
+
+All user-visible error strings should be defined in the main translation file (`messages_en_GB.properties`). Other language files will use the same keys. Refer to messages in code rather than hard-coding text.
+
+When creating new messages:
+
+1. Add the English phrase to `messages_en_GB.properties`.
+2. Reference the message key in your Java, JavaScript, or Python code.
+3. Update other localisation files as needed.
+
+Following these patterns helps keep Stirling-PDF stable, easier to debug, and friendly to users in all supported languages.

devGuide/README.md

@@ -0,0 +1,29 @@
+# Developer Guide Directory
+
+This directory contains all development-related documentation for Stirling PDF.
+
+## 📚 Documentation Index
+
+### Core Development
+- **[DeveloperGuide.md](./DeveloperGuide.md)** - Main developer setup and architecture guide
+- **[EXCEPTION_HANDLING_GUIDE.md](./EXCEPTION_HANDLING_GUIDE.md)** - Exception handling patterns and i18n best practices
+- **[HowToAddNewLanguage.md](./HowToAddNewLanguage.md)** - Internationalization and translation guide
+
+### Features & Documentation
+- **[AGENTS.md](./AGENTS.md)** - Agent-based functionality documentation
+- **[USERS.md](./USERS.md)** - User-focused documentation and guides
+
+## 🔗 Related Files in Root
+- **[README.md](../README.md)** - Project overview and quick start
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines
+- **[SECURITY.md](../SECURITY.md)** - Security policies and reporting
+- **[DATABASE.md](../DATABASE.md)** - Database setup and configuration (usage guide)
+- **[HowToUseOCR.md](../HowToUseOCR.md)** - OCR setup and configuration (usage guide)
+
+## 📝 Contributing to Documentation
+
+When adding new development documentation:
+1. Place technical guides in this `devGuide/` directory
+2. Update this index file with a brief description
+3. Keep user-facing docs (README, CONTRIBUTING, SECURITY) in the root
+4. Follow existing naming conventions (PascalCase for guides)

docker/README.md

@@ -0,0 +1,67 @@
+# Docker Setup for Stirling-PDF
+
+This directory contains the organized Docker configurations for the split frontend/backend architecture.
+
+## Directory Structure
+
+```
+docker/
+├── backend/           # Backend Docker files
+│   ├── Dockerfile            # Standard backend
+│   ├── Dockerfile.ultra-lite # Minimal backend
+│   └── Dockerfile.fat        # Full-featured backend
+├── frontend/          # Frontend Docker files
+│   ├── Dockerfile     # React/Vite frontend with nginx
+│   ├── nginx.conf     # Nginx configuration
+│   └── entrypoint.sh  # Dynamic backend URL setup
+├── monolith/          # Single container setup
+│   ├── Dockerfile           # Combined frontend + backend
+│   ├── nginx-monolith.conf  # Nginx config for monolith
+│   └── start-monolith.sh    # Startup script
+└── compose/           # Docker Compose files
+    ├── docker-compose.yml           # Standard setup
+    ├── docker-compose.ultra-lite.yml # Ultra-lite setup
+    ├── docker-compose.fat.yml       # Full-featured setup
+    └── docker-compose.monolith.yml  # Single container setup
+```
+
+## Usage
+
+### Separate Containers (Recommended)
+
+From the project root directory:
+
+```bash
+# Standard version
+docker-compose -f docker/compose/docker-compose.yml up --build
+
+# Ultra-lite version
+docker-compose -f docker/compose/docker-compose.ultra-lite.yml up --build
+
+# Fat version
+docker-compose -f docker/compose/docker-compose.fat.yml up --build
+```
+
+### Single Container (Monolith)
+
+```bash
+# Single container with both frontend and backend
+docker-compose -f docker/compose/docker-compose.monolith.yml up --build
+```
+
+## Access Points
+
+- **Frontend**: http://localhost:3000
+- **Backend API (debugging)**: http://localhost:8080 (TODO: Remove in production)
+- **Backend API (via frontend)**: http://localhost:3000/api/*
+
+## Configuration
+
+- **Backend URL**: Set `BACKEND_URL` environment variable for custom backend locations
+- **Custom Ports**: Modify port mappings in docker-compose files
+- **Memory Limits**: Adjust memory limits per variant (2G ultra-lite, 4G standard, 6G fat)
+
+## Development vs Production
+
+- **Development**: Keep backend port 8080 exposed for debugging
+- **Production**: Remove backend port exposure, use only frontend proxy

docker/backend/Dockerfile

@@ -1,4 +1,4 @@
-# Main stage
+# Backend Dockerfile - Java Spring Boot with all dependencies
 FROM alpine:3.22.0@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715
 
 # Copy necessary files
@@ -9,8 +9,8 @@ COPY stirling-pdf/build/libs/*.jar app.jar
 
 ARG VERSION_TAG
 
-LABEL org.opencontainers.image.title="Stirling-PDF"
-LABEL org.opencontainers.image.description="A powerful locally hosted web-based PDF manipulation tool supporting 50+ operations including merging, splitting, conversion, OCR, watermarking, and more."
+LABEL org.opencontainers.image.title="Stirling-PDF Backend"
+LABEL org.opencontainers.image.description="Backend service for Stirling-PDF - Java Spring Boot with PDF processing capabilities"
 LABEL org.opencontainers.image.source="https://github.com/Stirling-Tools/Stirling-PDF"
 LABEL org.opencontainers.image.licenses="MIT"
 LABEL org.opencontainers.image.vendor="Stirling-Tools"
@@ -19,7 +19,7 @@ LABEL org.opencontainers.image.documentation="https://docs.stirlingpdf.com"
 LABEL maintainer="Stirling-Tools"
 LABEL org.opencontainers.image.authors="Stirling-Tools"
 LABEL org.opencontainers.image.version="${VERSION_TAG}"
-LABEL org.opencontainers.image.keywords="PDF, manipulation, merge, split, convert, OCR, watermark"
+LABEL org.opencontainers.image.keywords="PDF, manipulation, backend, API, Spring Boot"
 
 # Set Environment Variables
 ENV DISABLE_ADDITIONAL_FEATURES=true \
@@ -39,8 +39,7 @@ ENV DISABLE_ADDITIONAL_FEATURES=true \
     TEMP=/tmp/stirling-pdf \
     TMP=/tmp/stirling-pdf
 
-
-# JDK for app
+# JDK for app and all dependencies
 RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/apk/repositories && \
     echo "@community https://dl-cdn.alpinelinux.org/alpine/edge/community" | tee -a /etc/apk/repositories && \
     echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" | tee -a /etc/apk/repositories && \
@@ -95,4 +94,4 @@ EXPOSE 8080/tcp
 
 # Set user and run command
 ENTRYPOINT ["tini", "--", "/scripts/init.sh"]
-CMD ["sh", "-c", "java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -jar /app.jar & /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1"]
+CMD ["sh", "-c", "java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -jar /app.jar & /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1"]

docker/backend/Dockerfile.fat

@@ -1,3 +1,4 @@
+# Backend fat Dockerfile - Java Spring Boot with all dependencies and build stage
 # Build the application
 FROM gradle:8.14-jdk21 AS build
 
@@ -52,7 +53,6 @@ ENV DISABLE_ADDITIONAL_FEATURES=true \
     TEMP=/tmp/stirling-pdf \
     TMP=/tmp/stirling-pdf
 
-
 # JDK for app
 RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/apk/repositories && \
     echo "@community https://dl-cdn.alpinelinux.org/alpine/edge/community" | tee -a /etc/apk/repositories && \
@@ -108,4 +108,4 @@ RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/a
 EXPOSE 8080/tcp
 # Set user and run command
 ENTRYPOINT ["tini", "--", "/scripts/init.sh"]
-CMD ["sh", "-c", "java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -jar /app.jar & /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1"]
+CMD ["sh", "-c", "java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -jar /app.jar & /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1"]

docker/backend/Dockerfile.ultra-lite

@@ -1,4 +1,4 @@
-# use alpine
+# Backend ultra-lite Dockerfile - Java Spring Boot with minimal dependencies
 FROM alpine:3.22.0@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715
 
 ARG VERSION_TAG
@@ -52,4 +52,4 @@ EXPOSE 8080/tcp
 
 # Run the application
 ENTRYPOINT ["tini", "--", "/scripts/init-without-ocr.sh"]
-CMD ["java", "-Dfile.encoding=UTF-8", "-Djava.io.tmpdir=/tmp/stirling-pdf", "-jar", "/app.jar"]
+CMD ["java", "-Dfile.encoding=UTF-8", "-Djava.io.tmpdir=/tmp/stirling-pdf", "-jar", "/app.jar"]

docker/compose/docker-compose.fat.yml

@@ -0,0 +1,66 @@
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: ../..
+      dockerfile: docker/backend/Dockerfile.fat
+    container_name: stirling-pdf-backend-fat
+    restart: on-failure:5
+    deploy:
+      resources:
+        limits:
+          memory: 6G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP'"]
+      interval: 5s
+      timeout: 10s
+      retries: 16
+    ports:
+      - "8080:8080"  # TODO: Remove in production - for debugging only
+    expose:
+      - "8080"
+    volumes:
+      - ../../stirling/latest/data:/usr/share/tessdata:rw
+      - ../../stirling/latest/config:/configs:rw
+      - ../../stirling/latest/logs:/logs:rw
+    environment:
+      DISABLE_ADDITIONAL_FEATURES: "false"
+      SECURITY_ENABLELOGIN: "false"
+      FAT_DOCKER: "true"
+      INSTALL_BOOK_AND_ADVANCED_HTML_OPS: "false"
+      LANGS: "en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID"
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Full-featured Stirling-PDF with all capabilities
+      UI_APPNAMENAVBAR: Stirling-PDF Fat
+      SYSTEM_MAXFILESIZE: "200"
+      METRICS_ENABLED: "true"
+      SYSTEM_GOOGLEVISIBILITY: "true"
+      SHOW_SURVEY: "true"
+    networks:
+      - stirling-network
+
+  frontend:
+    build:
+      context: ../../frontend
+      dockerfile: ../docker/frontend/Dockerfile
+    container_name: stirling-pdf-frontend-fat
+    restart: on-failure:5
+    ports:
+      - "3000:80"
+    environment:
+      BACKEND_URL: http://backend:8080
+    depends_on:
+      - backend
+    networks:
+      - stirling-network
+
+networks:
+  stirling-network:
+    driver: bridge
+
+volumes:
+  stirling-data:
+  stirling-config:
+  stirling-logs:

docker/compose/docker-compose.monolith.yml

@@ -0,0 +1,42 @@
+version: '3.8'
+
+services:
+  stirling-pdf-monolith:
+    build:
+      context: ../..
+      dockerfile: docker/monolith/Dockerfile
+    container_name: stirling-pdf-monolith
+    restart: on-failure:5
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:80/ && curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP'"]
+      interval: 10s
+      timeout: 15s
+      retries: 16
+    ports:
+      - "3000:80"   # Frontend access
+      - "8080:8080" # Direct backend access (for debugging)
+    volumes:
+      - ../../stirling/latest/data:/usr/share/tessdata:rw
+      - ../../stirling/latest/config:/configs:rw
+      - ../../stirling/latest/logs:/logs:rw
+    environment:
+      DISABLE_ADDITIONAL_FEATURES: "true"
+      SECURITY_ENABLELOGIN: "false"
+      LANGS: "en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID"
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Single container Stirling-PDF
+      UI_APPNAMENAVBAR: Stirling-PDF Monolith
+      SYSTEM_MAXFILESIZE: "100"
+      METRICS_ENABLED: "true"
+      SYSTEM_GOOGLEVISIBILITY: "true"
+      SHOW_SURVEY: "true"
+
+volumes:
+  stirling-data:
+  stirling-config:
+  stirling-logs:

docker/compose/docker-compose.ultra-lite.yml

@@ -0,0 +1,56 @@
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: ../..
+      dockerfile: docker/backend/Dockerfile.ultra-lite
+    container_name: stirling-pdf-backend-ultra-lite
+    restart: on-failure:5
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP'"]
+      interval: 5s
+      timeout: 10s
+      retries: 16
+    ports:
+      - "8080:8080"  # TODO: Remove in production - for debugging only
+    expose:
+      - "8080"
+    volumes:
+      - ../../stirling/latest/config:/configs:rw
+      - ../../stirling/latest/logs:/logs:rw
+    environment:
+      DISABLE_ADDITIONAL_FEATURES: "true"
+      SECURITY_ENABLELOGIN: "false"
+      ENDPOINTS_GROUPS_TO_REMOVE: "CLI"
+      LANGS: "en_GB,en_US"
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Ultra-lite version of Stirling-PDF
+      UI_APPNAMENAVBAR: Stirling-PDF Ultra-lite
+      SYSTEM_MAXFILESIZE: "50"
+    networks:
+      - stirling-network
+
+  frontend:
+    build:
+      context: ../../frontend
+      dockerfile: ../docker/frontend/Dockerfile
+    container_name: stirling-pdf-frontend-ultra-lite
+    restart: on-failure:5
+    ports:
+      - "3000:80"
+    environment:
+      BACKEND_URL: http://backend:8080
+    depends_on:
+      - backend
+    networks:
+      - stirling-network
+
+networks:
+  stirling-network:
+    driver: bridge

docker/compose/docker-compose.yml

@@ -0,0 +1,64 @@
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: ../..
+      dockerfile: docker/backend/Dockerfile
+    container_name: stirling-pdf-backend
+    restart: on-failure:5
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP'"]
+      interval: 5s
+      timeout: 10s
+      retries: 16
+    ports:
+      - "8080:8080"  # TODO: Remove in production - for debugging only
+    expose:
+      - "8080"
+    volumes:
+      - ../../stirling/latest/data:/usr/share/tessdata:rw
+      - ../../stirling/latest/config:/configs:rw
+      - ../../stirling/latest/logs:/logs:rw
+    environment:
+      DISABLE_ADDITIONAL_FEATURES: "true"
+      SECURITY_ENABLELOGIN: "false"
+      LANGS: "en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID"
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Demo site for Stirling-PDF Latest
+      UI_APPNAMENAVBAR: Stirling-PDF Latest
+      SYSTEM_MAXFILESIZE: "100"
+      METRICS_ENABLED: "true"
+      SYSTEM_GOOGLEVISIBILITY: "true"
+      SHOW_SURVEY: "true"
+    networks:
+      - stirling-network
+
+  frontend:
+    build:
+      context: ../../frontend
+      dockerfile: ../docker/frontend/Dockerfile
+    container_name: stirling-pdf-frontend
+    restart: on-failure:5
+    ports:
+      - "3000:80"
+    environment:
+      BACKEND_URL: http://backend:8080
+    depends_on:
+      - backend
+    networks:
+      - stirling-network
+
+networks:
+  stirling-network:
+    driver: bridge
+
+volumes:
+  stirling-data:
+  stirling-config:
+  stirling-logs:

docker/frontend/Dockerfile

@@ -0,0 +1,38 @@
+# Frontend Dockerfile - React/Vite application
+FROM node:20-alpine AS build
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine
+
+# Copy built files from build stage
+COPY --from=build /app/dist /usr/share/nginx/html
+
+# Copy nginx configuration and entrypoint
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY entrypoint.sh /entrypoint.sh
+
+# Make entrypoint executable
+RUN chmod +x /entrypoint.sh
+
+# Expose port 80 (standard HTTP port)
+EXPOSE 80
+
+# Environment variables for flexibility
+ENV BACKEND_URL=http://backend:8080
+
+# Use custom entrypoint
+ENTRYPOINT ["/entrypoint.sh"]

docker/frontend/entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# Set default backend URL if not provided
+BACKEND_URL=${BACKEND_URL:-"http://backend:8080"}
+
+# Replace the placeholder in nginx.conf with the actual backend URL
+sed -i "s|\${BACKEND_URL}|${BACKEND_URL}|g" /etc/nginx/nginx.conf
+
+# Start nginx
+exec nginx -g "daemon off;"

docker/frontend/nginx.conf

@@ -0,0 +1,49 @@
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+
+    server {
+        listen 80;
+        server_name _;
+        root /usr/share/nginx/html;
+        index index.html index.htm;
+
+        # Handle client-side routing - support subpaths
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+
+        # Proxy API calls to backend
+        location /api/ {
+            proxy_pass ${BACKEND_URL}/api/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+        }
+
+        # Cache static assets
+        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Security headers
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    }
+}

docker/monolith/Dockerfile

@@ -0,0 +1,128 @@
+# Monolith Dockerfile - Frontend + Backend in same container
+# Build frontend
+FROM node:20-alpine AS frontend-build
+
+WORKDIR /app/frontend
+
+# Copy frontend package files
+COPY frontend/package*.json ./
+
+# Install frontend dependencies
+RUN npm ci
+
+# Copy frontend source
+COPY frontend/ ./
+
+# Build frontend
+RUN npm run build
+
+# Main stage - Backend with frontend files
+FROM alpine:3.22.0@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715
+
+# Copy necessary files
+COPY scripts /scripts
+COPY pipeline /pipeline
+COPY stirling-pdf/src/main/resources/static/fonts/*.ttf /usr/share/fonts/opentype/noto/
+COPY stirling-pdf/build/libs/*.jar app.jar
+
+# Copy built frontend files
+COPY --from=frontend-build /app/frontend/dist /usr/share/nginx/html
+
+ARG VERSION_TAG
+
+LABEL org.opencontainers.image.title="Stirling-PDF Monolith"
+LABEL org.opencontainers.image.description="Single container with both frontend and backend for Stirling-PDF"
+LABEL org.opencontainers.image.source="https://github.com/Stirling-Tools/Stirling-PDF"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.vendor="Stirling-Tools"
+LABEL org.opencontainers.image.url="https://www.stirlingpdf.com"
+LABEL org.opencontainers.image.documentation="https://docs.stirlingpdf.com"
+LABEL maintainer="Stirling-Tools"
+LABEL org.opencontainers.image.authors="Stirling-Tools"
+LABEL org.opencontainers.image.version="${VERSION_TAG}"
+LABEL org.opencontainers.image.keywords="PDF, manipulation, monolith, single-container"
+
+# Set Environment Variables
+ENV DISABLE_ADDITIONAL_FEATURES=true \
+    VERSION_TAG=$VERSION_TAG \
+    JAVA_BASE_OPTS="-XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70" \
+    JAVA_CUSTOM_OPTS="" \
+    HOME=/home/stirlingpdfuser \
+    PUID=1000 \
+    PGID=1000 \
+    UMASK=022 \
+    PYTHONPATH=/usr/lib/libreoffice/program:/opt/venv/lib/python3.12/site-packages \
+    UNO_PATH=/usr/lib/libreoffice/program \
+    URE_BOOTSTRAP=file:///usr/lib/libreoffice/program/fundamentalrc \
+    PATH=$PATH:/opt/venv/bin \
+    STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
+    TMPDIR=/tmp/stirling-pdf \
+    TEMP=/tmp/stirling-pdf \
+    TMP=/tmp/stirling-pdf
+
+# Install nginx and all dependencies
+RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/apk/repositories && \
+    echo "@community https://dl-cdn.alpinelinux.org/alpine/edge/community" | tee -a /etc/apk/repositories && \
+    echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" | tee -a /etc/apk/repositories && \
+    apk upgrade --no-cache -a && \
+    apk add --no-cache \
+    ca-certificates \
+    tzdata \
+    tini \
+    bash \
+    curl \
+    qpdf \
+    shadow \
+    su-exec \
+    openssl \
+    openssl-dev \
+    openjdk21-jre \
+    nginx \
+    # Doc conversion
+    gcompat \
+    libc6-compat \
+    libreoffice \
+    # pdftohtml
+    poppler-utils \
+    # OCR MY PDF (unpaper for descew and other advanced features)
+    tesseract-ocr-data-eng \
+    tesseract-ocr-data-chi_sim \
+	tesseract-ocr-data-deu \
+	tesseract-ocr-data-fra \
+	tesseract-ocr-data-por \
+    # CV
+    py3-opencv \
+    python3 \
+    py3-pip \
+    py3-pillow@testing \
+    py3-pdf2image@testing && \
+    python3 -m venv /opt/venv && \
+    /opt/venv/bin/pip install --upgrade pip setuptools && \
+    /opt/venv/bin/pip install --no-cache-dir --upgrade unoserver weasyprint && \
+    ln -s /usr/lib/libreoffice/program/uno.py /opt/venv/lib/python3.12/site-packages/ && \
+    ln -s /usr/lib/libreoffice/program/unohelper.py /opt/venv/lib/python3.12/site-packages/ && \
+    ln -s /usr/lib/libreoffice/program /opt/venv/lib/python3.12/site-packages/LibreOffice && \
+    mv /usr/share/tessdata /usr/share/tessdata-original && \
+    mkdir -p $HOME /configs /logs /customFiles /pipeline/watchedFolders /pipeline/finishedFolders /tmp/stirling-pdf && \
+    fc-cache -f -v && \
+    chmod +x /scripts/* && \
+    chmod +x /scripts/init.sh && \
+    # User permissions
+    addgroup -S stirlingpdfgroup && adduser -S stirlingpdfuser -G stirlingpdfgroup && \
+    chown -R stirlingpdfuser:stirlingpdfgroup $HOME /scripts /usr/share/fonts/opentype/noto /configs /customFiles /pipeline /tmp/stirling-pdf && \
+    chown stirlingpdfuser:stirlingpdfgroup /app.jar && \
+    chown -R stirlingpdfuser:stirlingpdfgroup /usr/share/nginx/html
+
+# Copy nginx configuration for monolith
+COPY docker/monolith/nginx-monolith.conf /etc/nginx/nginx.conf
+
+# Copy startup script
+COPY docker/monolith/start-monolith.sh /start-monolith.sh
+RUN chmod +x /start-monolith.sh
+
+# Expose both ports
+EXPOSE 80 8080
+
+# Set user and run command
+ENTRYPOINT ["tini", "--"]
+CMD ["/start-monolith.sh"]

docker/monolith/nginx-monolith.conf

@@ -0,0 +1,49 @@
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+
+    server {
+        listen 80;
+        server_name _;
+        root /usr/share/nginx/html;
+        index index.html index.htm;
+
+        # Handle client-side routing - support subpaths
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+
+        # Proxy API calls to backend running on same container
+        location /api/ {
+            proxy_pass http://localhost:8080/api/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+        }
+
+        # Cache static assets
+        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Security headers
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    }
+}

docker/monolith/start-monolith.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Start the Java backend in the background
+echo "Starting Java backend..."
+su-exec stirlingpdfuser:stirlingpdfgroup bash -c "
+    cd /home/stirlingpdfuser && \
+    java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -jar /app.jar &
+    /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1 &
+"
+
+# Wait for backend to start
+echo "Waiting for backend to start..."
+until curl -f http://localhost:8080/api/v1/info/status >/dev/null 2>&1; do
+    sleep 2
+done
+
+echo "Backend started, starting nginx..."
+
+# Start nginx in the foreground
+nginx -g "daemon off;"

exampleYmlFiles/docker-compose-latest-ultra-lite.yml

@@ -17,7 +17,6 @@ services:
       - ./stirling/latest/config:/configs:rw
       - ./stirling/latest/logs:/logs:rw
     environment:
-      DISABLE_ADDITIONAL_FEATURES: "true"
       SECURITY_ENABLELOGIN: "false"
       SYSTEM_DEFAULTLOCALE: en-US
       UI_APPNAME: Stirling-PDF-Ultra-lite

exampleYmlFiles/docker-compose-latest.yml

@@ -18,7 +18,6 @@ services:
       - ./stirling/latest/config:/configs:rw
       - ./stirling/latest/logs:/logs:rw
     environment:
-      DISABLE_ADDITIONAL_FEATURES: "true"
       SECURITY_ENABLELOGIN: "false"
       LANGS: "en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID"
       SYSTEM_DEFAULTLOCALE: en-US

frontend/package-lock.json

@@ -25,6 +25,7 @@
         "i18next": "^25.2.1",
         "i18next-browser-languagedetector": "^8.1.0",
         "i18next-http-backend": "^3.0.2",
+        "jszip": "^3.10.1",
         "pdf-lib": "^1.17.1",
         "pdfjs-dist": "^3.11.174",
         "react": "^19.1.0",
@@ -2689,6 +2690,11 @@
         "node": ">=18"
       }
     },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="
+    },
     "node_modules/cosmiconfig": {
       "version": "7.1.0",
       "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-7.1.0.tgz",
@@ -3450,6 +3456,11 @@
         "cross-fetch": "4.0.0"
       }
     },
+    "node_modules/immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ=="
+    },
     "node_modules/import-fresh": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
@@ -3491,8 +3502,7 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "license": "ISC",
-      "optional": true
+      "license": "ISC"
     },
     "node_modules/is-arrayish": {
       "version": "0.2.1",
@@ -3571,6 +3581,11 @@
         "node": ">=0.12.0"
       }
     },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="
+    },
     "node_modules/jiti": {
       "version": "2.4.2",
       "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.4.2.tgz",
@@ -3630,6 +3645,52 @@
         "graceful-fs": "^4.1.6"
       }
     },
+    "node_modules/jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "dependencies": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      }
+    },
+    "node_modules/jszip/node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/jszip/node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
+    },
+    "node_modules/jszip/node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
+    "node_modules/lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "dependencies": {
+        "immediate": "~3.0.5"
+      }
+    },
     "node_modules/lightningcss": {
       "version": "1.30.1",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.30.1.tgz",
@@ -4729,6 +4790,11 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="
+    },
     "node_modules/prop-types": {
       "version": "15.8.1",
       "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz",
@@ -5237,6 +5303,11 @@
       "integrity": "sha512-IOc8uWeOZgnb3ptbCURJWNjWUPcO3ZnTTdzsurqERrP6nPyv+paC55vJM0LpOlT2ne+Ix+9+CRG1MNLlyZ4GjQ==",
       "license": "MIT"
     },
+    "node_modules/setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA=="
+    },
     "node_modules/signal-exit": {
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
@@ -5697,7 +5768,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
       "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/vite": {

frontend/package.json

@@ -21,6 +21,7 @@
     "i18next": "^25.2.1",
     "i18next-browser-languagedetector": "^8.1.0",
     "i18next-http-backend": "^3.0.2",
+    "jszip": "^3.10.1",
     "pdf-lib": "^1.17.1",
     "pdfjs-dist": "^3.11.174",
     "react": "^19.1.0",

frontend/public/thumbnailWorker.js

@@ -0,0 +1,157 @@
+// Web Worker for parallel thumbnail generation
+console.log('🔧 Thumbnail worker starting up...');
+
+let pdfJsLoaded = false;
+
+// Import PDF.js properly for worker context
+try {
+  console.log('📦 Loading PDF.js locally...');
+  importScripts('/pdf.js');
+
+  // PDF.js exports to globalThis, check both self and globalThis
+  const pdfjsLib = self.pdfjsLib || globalThis.pdfjsLib;
+  
+  if (pdfjsLib) {
+    // Make it available on self for consistency
+    self.pdfjsLib = pdfjsLib;
+    
+    // Set up PDF.js worker
+    self.pdfjsLib.GlobalWorkerOptions.workerSrc = '/pdf.worker.js';
+    pdfJsLoaded = true;
+    console.log('✓ PDF.js loaded successfully from local files');
+    console.log('✓ PDF.js version:', self.pdfjsLib.version || 'unknown');
+  } else {
+    throw new Error('pdfjsLib not available after import - neither self.pdfjsLib nor globalThis.pdfjsLib found');
+  }
+} catch (error) {
+  console.error('✗ Failed to load local PDF.js:', error.message || error);
+  console.error('✗ Available globals:', Object.keys(self).filter(key => key.includes('pdf')));
+  pdfJsLoaded = false;
+}
+
+// Log the final status
+if (pdfJsLoaded) {
+  console.log('✅ Thumbnail worker ready for PDF processing');
+} else {
+  console.log('❌ Thumbnail worker failed to initialize - PDF.js not available');
+}
+
+self.onmessage = async function(e) {
+  const { type, data, jobId } = e.data;
+
+  try {
+    // Handle PING for worker health check
+    if (type === 'PING') {
+      console.log('🏓 Worker PING received, checking PDF.js status...');
+      
+      // Check if PDF.js is loaded before responding
+      if (pdfJsLoaded && self.pdfjsLib) {
+        console.log('✓ Worker PONG - PDF.js ready');
+        self.postMessage({ type: 'PONG', jobId });
+      } else {
+        console.error('✗ PDF.js not loaded - worker not ready');
+        console.error('✗ pdfJsLoaded:', pdfJsLoaded);
+        console.error('✗ self.pdfjsLib:', !!self.pdfjsLib);
+        self.postMessage({
+          type: 'ERROR',
+          jobId,
+          data: { error: 'PDF.js not loaded in worker' }
+        });
+      }
+      return;
+    }
+
+    if (type === 'GENERATE_THUMBNAILS') {
+      console.log('🖼️ Starting thumbnail generation for', data.pageNumbers.length, 'pages');
+
+      if (!pdfJsLoaded || !self.pdfjsLib) {
+        const error = 'PDF.js not available in worker';
+        console.error('✗', error);
+        throw new Error(error);
+      }
+      const { pdfArrayBuffer, pageNumbers, scale = 0.2, quality = 0.8 } = data;
+
+      console.log('📄 Loading PDF document, size:', pdfArrayBuffer.byteLength, 'bytes');
+      // Load PDF in worker using imported PDF.js
+      const pdf = await self.pdfjsLib.getDocument({ data: pdfArrayBuffer }).promise;
+      console.log('✓ PDF loaded, total pages:', pdf.numPages);
+
+      const thumbnails = [];
+
+      // Process pages in smaller batches for smoother UI
+      const batchSize = 3; // Process 3 pages at once for smoother UI
+      for (let i = 0; i < pageNumbers.length; i += batchSize) {
+        const batch = pageNumbers.slice(i, i + batchSize);
+
+        const batchPromises = batch.map(async (pageNumber) => {
+          try {
+            console.log(`🎯 Processing page ${pageNumber}...`);
+            const page = await pdf.getPage(pageNumber);
+            const viewport = page.getViewport({ scale });
+            console.log(`📐 Page ${pageNumber} viewport:`, viewport.width, 'x', viewport.height);
+
+            // Create OffscreenCanvas for better performance
+            const canvas = new OffscreenCanvas(viewport.width, viewport.height);
+            const context = canvas.getContext('2d');
+
+            if (!context) {
+              throw new Error('Failed to get 2D context from OffscreenCanvas');
+            }
+
+            await page.render({ canvasContext: context, viewport }).promise;
+            console.log(`✓ Page ${pageNumber} rendered`);
+
+            // Convert to blob then to base64 (more efficient than toDataURL)
+            const blob = await canvas.convertToBlob({ type: 'image/jpeg', quality });
+            const arrayBuffer = await blob.arrayBuffer();
+            const base64 = btoa(String.fromCharCode(...new Uint8Array(arrayBuffer)));
+            const thumbnail = `data:image/jpeg;base64,${base64}`;
+            console.log(`✓ Page ${pageNumber} thumbnail generated (${base64.length} chars)`);
+
+            return { pageNumber, thumbnail, success: true };
+          } catch (error) {
+            console.error(`✗ Failed to generate thumbnail for page ${pageNumber}:`, error.message || error);
+            return { pageNumber, error: error.message || String(error), success: false };
+          }
+        });
+
+        const batchResults = await Promise.all(batchPromises);
+        thumbnails.push(...batchResults);
+
+        // Send progress update
+        console.log(`📊 Worker: Sending progress update - ${thumbnails.length}/${pageNumbers.length} completed, ${batchResults.filter(r => r.success).length} new thumbnails`);
+        self.postMessage({
+          type: 'PROGRESS',
+          jobId,
+          data: {
+            completed: thumbnails.length,
+            total: pageNumbers.length,
+            thumbnails: batchResults.filter(r => r.success)
+          }
+        });
+
+        // Small delay between batches to keep UI smooth
+        if (i + batchSize < pageNumbers.length) {
+          console.log(`⏸️ Worker: Pausing 100ms before next batch (${i + batchSize}/${pageNumbers.length})`);
+          await new Promise(resolve => setTimeout(resolve, 100)); // Increased to 100ms pause between batches for smoother scrolling
+        }
+      }
+
+      // Clean up
+      pdf.destroy();
+
+      self.postMessage({
+        type: 'COMPLETE',
+        jobId,
+        data: { thumbnails: thumbnails.filter(r => r.success) }
+      });
+
+    }
+  } catch (error) {
+    self.postMessage({
+      type: 'ERROR',
+      jobId,
+      data: { error: error.message }
+    });
+  }
+};

frontend/src/App.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import { RainbowThemeProvider } from './components/shared/RainbowThemeProvider';
+import { FileContextProvider } from './contexts/FileContext';
 import HomePage from './pages/HomePage';
 
 // Import global styles
@@ -9,7 +10,9 @@ import './index.css';
 export default function App() {
   return (
     <RainbowThemeProvider>
-      <HomePage />
+      <FileContextProvider enableUrlSync={true} enablePersistence={true}>
+        <HomePage />
+      </FileContextProvider>
     </RainbowThemeProvider>
   );
 }

frontend/src/commands/pageCommands.ts

@@ -97,27 +97,8 @@ export class DeletePagesCommand extends PageCommand {
   }
 
   undo(): void {
-    let restoredPages = [...this.pdfDocument.pages];
-    
-    // Insert deleted pages back at their original positions
-    this.deletedPages
-      .sort((a, b) => (this.deletedPositions.get(a.id) || 0) - (this.deletedPositions.get(b.id) || 0))
-      .forEach(page => {
-        const originalIndex = this.deletedPositions.get(page.id) || 0;
-        restoredPages.splice(originalIndex, 0, page);
-      });
-    
-    // Update page numbers
-    restoredPages = restoredPages.map((page, index) => ({ 
-      ...page, 
-      pageNumber: index + 1 
-    }));
-    
-    this.setPdfDocument({ 
-      ...this.pdfDocument, 
-      pages: restoredPages, 
-      totalPages: restoredPages.length 
-    });
+    // Simply restore to the previous state (before deletion)
+    this.setPdfDocument(this.previousState);
   }
 
   get description(): string {

frontend/src/components/fileEditor/FileEditor.tsx

@@ -0,0 +1,858 @@
+import React, { useState, useCallback, useRef, useEffect } from 'react';
+import {
+  Button, Text, Center, Box, Notification, TextInput, LoadingOverlay, Modal, Alert, Container,
+  Stack, Group
+} from '@mantine/core';
+import { Dropzone } from '@mantine/dropzone';
+import { useTranslation } from 'react-i18next';
+import UploadFileIcon from '@mui/icons-material/UploadFile';
+import { useFileContext } from '../../contexts/FileContext';
+import { FileOperation } from '../../types/fileContext';
+import { fileStorage } from '../../services/fileStorage';
+import { generateThumbnailForFile } from '../../utils/thumbnailUtils';
+import { zipFileService } from '../../services/zipFileService';
+import styles from '../pageEditor/PageEditor.module.css';
+import FileThumbnail from '../pageEditor/FileThumbnail';
+import DragDropGrid from '../pageEditor/DragDropGrid';
+import FilePickerModal from '../shared/FilePickerModal';
+import SkeletonLoader from '../shared/SkeletonLoader';
+
+interface FileItem {
+  id: string;
+  name: string;
+  pageCount: number;
+  thumbnail: string;
+  size: number;
+  file: File;
+  splitBefore?: boolean;
+}
+
+interface FileEditorProps {
+  onOpenPageEditor?: (file: File) => void;
+  onMergeFiles?: (files: File[]) => void;
+  toolMode?: boolean;
+  multiSelect?: boolean;
+  showUpload?: boolean;
+  showBulkActions?: boolean;
+  onFileSelect?: (files: File[]) => void;
+}
+
+const FileEditor = ({
+  onOpenPageEditor,
+  onMergeFiles,
+  toolMode = false,
+  multiSelect = true,
+  showUpload = true,
+  showBulkActions = true,
+  onFileSelect
+}: FileEditorProps) => {
+  const { t } = useTranslation();
+
+  // Get file context
+  const fileContext = useFileContext();
+  const {
+    activeFiles,
+    processedFiles,
+    selectedFileIds,
+    setSelectedFiles: setContextSelectedFiles,
+    isProcessing,
+    addFiles,
+    removeFiles,
+    setCurrentView,
+    recordOperation,
+    markOperationApplied
+  } = fileContext;
+
+  const [files, setFiles] = useState<FileItem[]>([]);
+  const [status, setStatus] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [localLoading, setLocalLoading] = useState(false);
+  const [selectionMode, setSelectionMode] = useState(toolMode);
+  
+  // Enable selection mode automatically in tool mode
+  React.useEffect(() => {
+    if (toolMode) {
+      setSelectionMode(true);
+    }
+  }, [toolMode]);
+  const [draggedFile, setDraggedFile] = useState<string | null>(null);
+  const [dropTarget, setDropTarget] = useState<string | null>(null);
+  const [multiFileDrag, setMultiFileDrag] = useState<{fileIds: string[], count: number} | null>(null);
+  const [dragPosition, setDragPosition] = useState<{x: number, y: number} | null>(null);
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [showFilePickerModal, setShowFilePickerModal] = useState(false);
+  const [conversionProgress, setConversionProgress] = useState(0);
+  const [zipExtractionProgress, setZipExtractionProgress] = useState<{
+    isExtracting: boolean;
+    currentFile: string;
+    progress: number;
+    extractedCount: number;
+    totalFiles: number;
+  }>({
+    isExtracting: false,
+    currentFile: '',
+    progress: 0,
+    extractedCount: 0,
+    totalFiles: 0
+  });
+  const fileRefs = useRef<Map<string, HTMLDivElement>>(new Map());
+  const lastActiveFilesRef = useRef<string[]>([]);
+  const lastProcessedFilesRef = useRef<number>(0);
+
+  // Map context selected file names to local file IDs
+  // Defensive programming: ensure selectedFileIds is always an array
+  const safeSelectedFileIds = Array.isArray(selectedFileIds) ? selectedFileIds : [];
+  
+  const localSelectedFiles = files
+    .filter(file => {
+      const fileId = (file.file as any).id || file.name;
+      return safeSelectedFileIds.includes(fileId);
+    })
+    .map(file => file.id);
+
+  // Convert shared files to FileEditor format
+  const convertToFileItem = useCallback(async (sharedFile: any): Promise<FileItem> => {
+    // Generate thumbnail if not already available
+    const thumbnail = sharedFile.thumbnail || await generateThumbnailForFile(sharedFile.file || sharedFile);
+
+    return {
+      id: sharedFile.id || `file-${Date.now()}-${Math.random()}`,
+      name: (sharedFile.file?.name || sharedFile.name || 'unknown'),
+      pageCount: sharedFile.pageCount || Math.floor(Math.random() * 20) + 1, // Mock for now
+      thumbnail,
+      size: sharedFile.file?.size || sharedFile.size || 0,
+      file: sharedFile.file || sharedFile,
+    };
+  }, []);
+
+  // Convert activeFiles to FileItem format using context (async to avoid blocking)
+  useEffect(() => {
+    // Check if the actual content has changed, not just references
+    const currentActiveFileNames = activeFiles.map(f => f.name);
+    const currentProcessedFilesSize = processedFiles.size;
+    
+    const activeFilesChanged = JSON.stringify(currentActiveFileNames) !== JSON.stringify(lastActiveFilesRef.current);
+    const processedFilesChanged = currentProcessedFilesSize !== lastProcessedFilesRef.current;
+    
+    if (!activeFilesChanged && !processedFilesChanged) {
+      return;
+    }
+    
+    // Update refs
+    lastActiveFilesRef.current = currentActiveFileNames;
+    lastProcessedFilesRef.current = currentProcessedFilesSize;
+    
+    const convertActiveFiles = async () => {
+      
+      if (activeFiles.length > 0) {
+        setLocalLoading(true);
+        try {
+          // Process files in chunks to avoid blocking UI
+          const convertedFiles: FileItem[] = [];
+          
+          for (let i = 0; i < activeFiles.length; i++) {
+            const file = activeFiles[i];
+            
+            // Try to get thumbnail from processed file first
+            const processedFile = processedFiles.get(file);
+            let thumbnail = processedFile?.pages?.[0]?.thumbnail;
+            
+            // If no thumbnail from processed file, try to generate one
+            if (!thumbnail) {
+              try {
+                thumbnail = await generateThumbnailForFile(file);
+              } catch (error) {
+                console.warn(`Failed to generate thumbnail for ${file.name}:`, error);
+                thumbnail = undefined; // Use placeholder
+              }
+            }
+            
+            const convertedFile = {
+              id: `file-${Date.now()}-${Math.random()}`,
+              name: file.name,
+              pageCount: processedFile?.totalPages || Math.floor(Math.random() * 20) + 1,
+              thumbnail,
+              size: file.size,
+              file,
+            };
+            
+            convertedFiles.push(convertedFile);
+            
+            // Update progress
+            setConversionProgress(((i + 1) / activeFiles.length) * 100);
+            
+            // Yield to main thread between files
+            if (i < activeFiles.length - 1) {
+              await new Promise(resolve => requestAnimationFrame(resolve));
+            }
+          }
+              
+          
+          setFiles(convertedFiles);
+        } catch (err) {
+          console.error('Error converting active files:', err);
+        } finally {
+          setLocalLoading(false);
+          setConversionProgress(0);
+        }
+      } else {
+        setFiles([]);
+        setLocalLoading(false);
+        setConversionProgress(0);
+      }
+    };
+
+    convertActiveFiles();
+  }, [activeFiles, processedFiles]);
+
+
+  // Process uploaded files using context
+  const handleFileUpload = useCallback(async (uploadedFiles: File[]) => {
+    setError(null);
+
+    try {
+      const allExtractedFiles: File[] = [];
+      const errors: string[] = [];
+
+      for (const file of uploadedFiles) {
+        if (file.type === 'application/pdf') {
+          // Handle PDF files normally
+          allExtractedFiles.push(file);
+        } else if (file.type === 'application/zip' || file.type === 'application/x-zip-compressed' || file.name.toLowerCase().endsWith('.zip')) {
+          // Handle ZIP files
+          try {
+            // Validate ZIP file first
+            const validation = await zipFileService.validateZipFile(file);
+            if (!validation.isValid) {
+              errors.push(`ZIP file "${file.name}": ${validation.errors.join(', ')}`);
+              continue;
+            }
+
+            // Extract PDF files from ZIP
+            setZipExtractionProgress({
+              isExtracting: true,
+              currentFile: file.name,
+              progress: 0,
+              extractedCount: 0,
+              totalFiles: validation.fileCount
+            });
+
+            const extractionResult = await zipFileService.extractPdfFiles(file, (progress) => {
+              setZipExtractionProgress({
+                isExtracting: true,
+                currentFile: progress.currentFile,
+                progress: progress.progress,
+                extractedCount: progress.extractedCount,
+                totalFiles: progress.totalFiles
+              });
+            });
+
+            // Reset extraction progress
+            setZipExtractionProgress({
+              isExtracting: false,
+              currentFile: '',
+              progress: 0,
+              extractedCount: 0,
+              totalFiles: 0
+            });
+
+            if (extractionResult.success) {
+              allExtractedFiles.push(...extractionResult.extractedFiles);
+              
+              // Record ZIP extraction operation
+              const operationId = `zip-extract-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+              const operation: FileOperation = {
+                id: operationId,
+                type: 'convert',
+                timestamp: Date.now(),
+                fileIds: extractionResult.extractedFiles.map(f => f.name),
+                status: 'pending',
+                metadata: {
+                  originalFileName: file.name,
+                  outputFileNames: extractionResult.extractedFiles.map(f => f.name),
+                  fileSize: file.size,
+                  parameters: {
+                    extractionType: 'zip',
+                    extractedCount: extractionResult.extractedCount,
+                    totalFiles: extractionResult.totalFiles
+                  }
+                }
+              };
+              
+              recordOperation(file.name, operation);
+              markOperationApplied(file.name, operationId);
+              
+              if (extractionResult.errors.length > 0) {
+                errors.push(...extractionResult.errors);
+              }
+            } else {
+              errors.push(`Failed to extract ZIP file "${file.name}": ${extractionResult.errors.join(', ')}`);
+            }
+          } catch (zipError) {
+            errors.push(`Failed to process ZIP file "${file.name}": ${zipError instanceof Error ? zipError.message : 'Unknown error'}`);
+            setZipExtractionProgress({
+              isExtracting: false,
+              currentFile: '',
+              progress: 0,
+              extractedCount: 0,
+              totalFiles: 0
+            });
+          }
+        } else {
+          errors.push(`Unsupported file type: ${file.name} (${file.type})`);
+        }
+      }
+
+      // Show any errors
+      if (errors.length > 0) {
+        setError(errors.join('\n'));
+      }
+
+      // Process all extracted files
+      if (allExtractedFiles.length > 0) {
+        // Record upload operations for PDF files
+        for (const file of allExtractedFiles) {
+          const operationId = `upload-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+          const operation: FileOperation = {
+            id: operationId,
+            type: 'upload',
+            timestamp: Date.now(),
+            fileIds: [file.name],
+            status: 'pending',
+            metadata: {
+              originalFileName: file.name,
+              fileSize: file.size,
+              parameters: {
+                uploadMethod: 'drag-drop'
+              }
+            }
+          };
+          
+          recordOperation(file.name, operation);
+          markOperationApplied(file.name, operationId);
+        }
+
+        // Add files to context (they will be processed automatically)
+        await addFiles(allExtractedFiles);
+        setStatus(`Added ${allExtractedFiles.length} files`);
+      }
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Failed to process files';
+      setError(errorMessage);
+      console.error('File processing error:', err);
+      
+      // Reset extraction progress on error
+      setZipExtractionProgress({
+        isExtracting: false,
+        currentFile: '',
+        progress: 0,
+        extractedCount: 0,
+        totalFiles: 0
+      });
+    }
+  }, [addFiles, recordOperation, markOperationApplied]);
+
+  const selectAll = useCallback(() => {
+    setContextSelectedFiles(files.map(f => (f.file as any).id || f.name));
+  }, [files, setContextSelectedFiles]);
+
+  const deselectAll = useCallback(() => setContextSelectedFiles([]), [setContextSelectedFiles]);
+
+  const closeAllFiles = useCallback(() => {
+    if (activeFiles.length === 0) return;
+    
+    // Record close all operation for each file
+    activeFiles.forEach(file => {
+      const operationId = `close-all-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+      const operation: FileOperation = {
+        id: operationId,
+        type: 'remove',
+        timestamp: Date.now(),
+        fileIds: [file.name],
+        status: 'pending',
+        metadata: {
+          originalFileName: file.name,
+          fileSize: file.size,
+          parameters: {
+            action: 'close_all',
+            reason: 'user_request'
+          }
+        }
+      };
+      
+      recordOperation(file.name, operation);
+      markOperationApplied(file.name, operationId);
+    });
+    
+    // Remove all files from context but keep in storage
+    removeFiles(activeFiles.map(f => (f as any).id || f.name), false);
+    
+    // Clear selections
+    setContextSelectedFiles([]);
+  }, [activeFiles, removeFiles, setContextSelectedFiles, recordOperation, markOperationApplied]);
+
+  const toggleFile = useCallback((fileId: string) => {
+    const targetFile = files.find(f => f.id === fileId);
+    if (!targetFile) return;
+    
+    const contextFileId = (targetFile.file as any).id || targetFile.name;
+    
+    if (!multiSelect) {
+      // Single select mode for tools - toggle on/off
+      const isCurrentlySelected = safeSelectedFileIds.includes(contextFileId);
+      if (isCurrentlySelected) {
+        // Deselect the file
+        setContextSelectedFiles([]);
+        if (onFileSelect) {
+          onFileSelect([]);
+        }
+      } else {
+        // Select the file
+        setContextSelectedFiles([contextFileId]);
+        if (onFileSelect) {
+          onFileSelect([targetFile.file]);
+        }
+      }
+    } else {
+      // Multi select mode (default)
+      setContextSelectedFiles(prev => {
+        const safePrev = Array.isArray(prev) ? prev : [];
+        return safePrev.includes(contextFileId)
+          ? safePrev.filter(id => id !== contextFileId)
+          : [...safePrev, contextFileId];
+      });
+      
+      // Notify parent with selected files
+      if (onFileSelect) {
+        const selectedFiles = files
+          .filter(f => {
+            const fId = (f.file as any).id || f.name;
+            return safeSelectedFileIds.includes(fId) || fId === contextFileId;
+          })
+          .map(f => f.file);
+        onFileSelect(selectedFiles);
+      }
+    }
+  }, [files, setContextSelectedFiles, multiSelect, onFileSelect, safeSelectedFileIds]);
+
+  const toggleSelectionMode = useCallback(() => {
+    setSelectionMode(prev => {
+      const newMode = !prev;
+      if (!newMode) {
+        setContextSelectedFiles([]);
+      }
+      return newMode;
+    });
+  }, [setContextSelectedFiles]);
+
+
+  // Drag and drop handlers
+  const handleDragStart = useCallback((fileId: string) => {
+    setDraggedFile(fileId);
+
+    if (selectionMode && localSelectedFiles.includes(fileId) && localSelectedFiles.length > 1) {
+      setMultiFileDrag({
+        fileIds: localSelectedFiles,
+        count: localSelectedFiles.length
+      });
+    } else {
+      setMultiFileDrag(null);
+    }
+  }, [selectionMode, localSelectedFiles]);
+
+  const handleDragEnd = useCallback(() => {
+    setDraggedFile(null);
+    setDropTarget(null);
+    setMultiFileDrag(null);
+    setDragPosition(null);
+  }, []);
+
+  const handleDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+
+    if (!draggedFile) return;
+
+    if (multiFileDrag) {
+      setDragPosition({ x: e.clientX, y: e.clientY });
+    }
+
+    const elementUnderCursor = document.elementFromPoint(e.clientX, e.clientY);
+    if (!elementUnderCursor) return;
+
+    const fileContainer = elementUnderCursor.closest('[data-file-id]');
+    if (fileContainer) {
+      const fileId = fileContainer.getAttribute('data-file-id');
+      if (fileId && fileId !== draggedFile) {
+        setDropTarget(fileId);
+        return;
+      }
+    }
+
+    const endZone = elementUnderCursor.closest('[data-drop-zone="end"]');
+    if (endZone) {
+      setDropTarget('end');
+      return;
+    }
+
+    setDropTarget(null);
+  }, [draggedFile, multiFileDrag]);
+
+  const handleDragEnter = useCallback((fileId: string) => {
+    if (draggedFile && fileId !== draggedFile) {
+      setDropTarget(fileId);
+    }
+  }, [draggedFile]);
+
+  const handleDragLeave = useCallback(() => {
+    // Let dragover handle this
+  }, []);
+
+  const handleDrop = useCallback((e: React.DragEvent, targetFileId: string | 'end') => {
+    e.preventDefault();
+    if (!draggedFile || draggedFile === targetFileId) return;
+
+    let targetIndex: number;
+    if (targetFileId === 'end') {
+      targetIndex = files.length;
+    } else {
+      targetIndex = files.findIndex(f => f.id === targetFileId);
+      if (targetIndex === -1) return;
+    }
+
+    const filesToMove = selectionMode && localSelectedFiles.includes(draggedFile)
+      ? localSelectedFiles
+      : [draggedFile];
+
+    // Update the local files state and sync with activeFiles
+    setFiles(prev => {
+      const newFiles = [...prev];
+      const movedFiles = filesToMove.map(id => newFiles.find(f => f.id === id)!).filter(Boolean);
+
+      // Remove moved files
+      filesToMove.forEach(id => {
+        const index = newFiles.findIndex(f => f.id === id);
+        if (index !== -1) newFiles.splice(index, 1);
+      });
+
+      // Insert at target position
+      newFiles.splice(targetIndex, 0, ...movedFiles);
+
+      // TODO: Update context with reordered files (need to implement file reordering in context)
+      // For now, just return the reordered local state
+      return newFiles;
+    });
+
+    const moveCount = multiFileDrag ? multiFileDrag.count : 1;
+    setStatus(`${moveCount > 1 ? `${moveCount} files` : 'File'} reordered`);
+
+  }, [draggedFile, files, selectionMode, localSelectedFiles, multiFileDrag]);
+
+  const handleEndZoneDragEnter = useCallback(() => {
+    if (draggedFile) {
+      setDropTarget('end');
+    }
+  }, [draggedFile]);
+
+  // File operations using context
+  const handleDeleteFile = useCallback((fileId: string) => {
+    console.log('handleDeleteFile called with fileId:', fileId);
+    const file = files.find(f => f.id === fileId);
+    console.log('Found file:', file);
+    
+    if (file) {
+      console.log('Attempting to remove file:', file.name);
+      console.log('Actual file object:', file.file);
+      console.log('Actual file.file.name:', file.file.name);
+      
+      // Record close operation
+      const fileName = file.file.name;
+      const fileId = (file.file as any).id || fileName;
+      const operationId = `close-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+      const operation: FileOperation = {
+        id: operationId,
+        type: 'remove',
+        timestamp: Date.now(),
+        fileIds: [fileName],
+        status: 'pending',
+        metadata: {
+          originalFileName: fileName,
+          fileSize: file.size,
+          parameters: {
+            action: 'close',
+            reason: 'user_request'
+          }
+        }
+      };
+      
+      recordOperation(fileName, operation);
+      
+      // Remove file from context but keep in storage (close, don't delete)
+      console.log('Calling removeFiles with:', [fileId]);
+      removeFiles([fileId], false);
+      
+      // Remove from context selections
+      setContextSelectedFiles(prev => {
+        const safePrev = Array.isArray(prev) ? prev : [];
+        return safePrev.filter(id => id !== fileId);
+      });
+      
+      // Mark operation as applied
+      markOperationApplied(fileName, operationId);
+    } else {
+      console.log('File not found for fileId:', fileId);
+    }
+  }, [files, removeFiles, setContextSelectedFiles, recordOperation, markOperationApplied]);
+
+  const handleViewFile = useCallback((fileId: string) => {
+    const file = files.find(f => f.id === fileId);
+    if (file) {
+      // Set the file as selected in context and switch to page editor view
+      const contextFileId = (file.file as any).id || file.name;
+      setContextSelectedFiles([contextFileId]);
+      setCurrentView('pageEditor');
+      onOpenPageEditor?.(file.file);
+    }
+  }, [files, setContextSelectedFiles, setCurrentView, onOpenPageEditor]);
+
+  const handleMergeFromHere = useCallback((fileId: string) => {
+    const startIndex = files.findIndex(f => f.id === fileId);
+    if (startIndex === -1) return;
+
+    const filesToMerge = files.slice(startIndex).map(f => f.file);
+    if (onMergeFiles) {
+      onMergeFiles(filesToMerge);
+    }
+  }, [files, onMergeFiles]);
+
+  const handleSplitFile = useCallback((fileId: string) => {
+    const file = files.find(f => f.id === fileId);
+    if (file && onOpenPageEditor) {
+      onOpenPageEditor(file.file);
+    }
+  }, [files, onOpenPageEditor]);
+
+  const handleLoadFromStorage = useCallback(async (selectedFiles: any[]) => {
+    if (selectedFiles.length === 0) return;
+
+    setLocalLoading(true);
+    try {
+      const convertedFiles = await Promise.all(
+        selectedFiles.map(convertToFileItem)
+      );
+      setFiles(prev => [...prev, ...convertedFiles]);
+      setStatus(`Loaded ${selectedFiles.length} files from storage`);
+    } catch (err) {
+      console.error('Error loading files from storage:', err);
+      setError('Failed to load some files from storage');
+    } finally {
+      setLocalLoading(false);
+    }
+  }, [convertToFileItem]);
+
+
+  return (
+    <Box pos="relative" h="100vh" style={{ overflow: 'auto' }}>
+      <LoadingOverlay visible={false} />
+
+      <Box p="md" pt="xl">
+        <Group mb="md">
+          {showBulkActions && !toolMode && (
+            <>
+              <Button onClick={selectAll} variant="light">Select All</Button>
+              <Button onClick={deselectAll} variant="light">Deselect All</Button>
+              <Button onClick={closeAllFiles} variant="light" color="orange">
+                Close All
+              </Button>
+            </>
+          )}
+
+          {/* Load from storage and upload buttons */}
+          {showUpload && (
+            <>
+              <Button
+                variant="outline"
+                color="blue"
+                onClick={() => setShowFilePickerModal(true)}
+              >
+                Load from Storage
+              </Button>
+
+              <Dropzone
+                onDrop={handleFileUpload}
+                accept={["application/pdf", "application/zip", "application/x-zip-compressed"]}
+                multiple={true}
+                maxSize={2 * 1024 * 1024 * 1024}
+                style={{ display: 'contents' }}
+              >
+                <Button variant="outline" color="green">
+                  Upload Files
+                </Button>
+              </Dropzone>
+            </>
+          )}
+        </Group>
+
+
+        {files.length === 0 && !localLoading && !zipExtractionProgress.isExtracting ? (
+          <Center h="60vh">
+            <Stack align="center" gap="md">
+              <Text size="lg" c="dimmed">📁</Text>
+              <Text c="dimmed">No files loaded</Text>
+              <Text size="sm" c="dimmed">Upload PDF files, ZIP archives, or load from storage to get started</Text>
+            </Stack>
+          </Center>
+        ) : files.length === 0 && (localLoading || zipExtractionProgress.isExtracting) ? (
+          <Box>
+            <SkeletonLoader type="controls" />
+            
+            {/* ZIP Extraction Progress */}
+            {zipExtractionProgress.isExtracting && (
+              <Box mb="md" p="sm" style={{ backgroundColor: 'var(--mantine-color-orange-0)', borderRadius: 8 }}>
+                <Group justify="space-between" mb="xs">
+                  <Text size="sm" fw={500}>Extracting ZIP archive...</Text>
+                  <Text size="sm" c="dimmed">{Math.round(zipExtractionProgress.progress)}%</Text>
+                </Group>
+                <Text size="xs" c="dimmed" mb="xs">
+                  {zipExtractionProgress.currentFile || 'Processing files...'}
+                </Text>
+                <Text size="xs" c="dimmed" mb="xs">
+                  {zipExtractionProgress.extractedCount} of {zipExtractionProgress.totalFiles} files extracted
+                </Text>
+                <div style={{ 
+                  width: '100%', 
+                  height: '4px', 
+                  backgroundColor: 'var(--mantine-color-gray-2)', 
+                  borderRadius: '2px',
+                  overflow: 'hidden'
+                }}>
+                  <div style={{
+                    width: `${Math.round(zipExtractionProgress.progress)}%`,
+                    height: '100%',
+                    backgroundColor: 'var(--mantine-color-orange-6)',
+                    transition: 'width 0.3s ease'
+                  }} />
+                </div>
+              </Box>
+            )}
+            
+            {/* Processing indicator */}
+            {localLoading && (
+              <Box mb="md" p="sm" style={{ backgroundColor: 'var(--mantine-color-blue-0)', borderRadius: 8 }}>
+                <Group justify="space-between" mb="xs">
+                  <Text size="sm" fw={500}>Loading files...</Text>
+                  <Text size="sm" c="dimmed">{Math.round(conversionProgress)}%</Text>
+                </Group>
+                <div style={{ 
+                  width: '100%', 
+                  height: '4px', 
+                  backgroundColor: 'var(--mantine-color-gray-2)', 
+                  borderRadius: '2px',
+                  overflow: 'hidden'
+                }}>
+                  <div style={{
+                    width: `${Math.round(conversionProgress)}%`,
+                    height: '100%',
+                    backgroundColor: 'var(--mantine-color-blue-6)',
+                    transition: 'width 0.3s ease'
+                  }} />
+                </div>
+              </Box>
+            )}
+            
+            <SkeletonLoader type="fileGrid" count={6} />
+          </Box>
+        ) : (
+          <DragDropGrid
+            items={files}
+            selectedItems={localSelectedFiles}
+            selectionMode={selectionMode}
+            isAnimating={isAnimating}
+          onDragStart={handleDragStart}
+          onDragEnd={handleDragEnd}
+          onDragOver={handleDragOver}
+          onDragEnter={handleDragEnter}
+          onDragLeave={handleDragLeave}
+          onDrop={handleDrop}
+          onEndZoneDragEnter={handleEndZoneDragEnter}
+          draggedItem={draggedFile}
+          dropTarget={dropTarget}
+          multiItemDrag={multiFileDrag}
+          dragPosition={dragPosition}
+          renderItem={(file, index, refs) => (
+            <FileThumbnail
+              file={file}
+              index={index}
+              totalFiles={files.length}
+              selectedFiles={localSelectedFiles}
+              selectionMode={selectionMode}
+              draggedFile={draggedFile}
+              dropTarget={dropTarget}
+              isAnimating={isAnimating}
+              fileRefs={refs}
+              onDragStart={handleDragStart}
+              onDragEnd={handleDragEnd}
+              onDragOver={handleDragOver}
+              onDragEnter={handleDragEnter}
+              onDragLeave={handleDragLeave}
+              onDrop={handleDrop}
+              onToggleFile={toggleFile}
+              onDeleteFile={handleDeleteFile}
+              onViewFile={handleViewFile}
+              onMergeFromHere={handleMergeFromHere}
+              onSplitFile={handleSplitFile}
+              onSetStatus={setStatus}
+              toolMode={toolMode}
+            />
+          )}
+          renderSplitMarker={(file, index) => (
+            <div
+              style={{
+                width: '2px',
+                height: '24rem',
+                borderLeft: '2px dashed #3b82f6',
+                backgroundColor: 'transparent',
+                marginLeft: '-0.75rem',
+                marginRight: '-0.75rem',
+                flexShrink: 0
+              }}
+            />
+          )}
+        />
+        )}
+      </Box>
+
+      {/* File Picker Modal */}
+      <FilePickerModal
+        opened={showFilePickerModal}
+        onClose={() => setShowFilePickerModal(false)}
+        storedFiles={[]} // FileEditor doesn't have access to stored files, needs to be passed from parent
+        onSelectFiles={handleLoadFromStorage}
+        allowMultiple={true}
+      />
+
+      {status && (
+        <Notification
+          color="blue"
+          mt="md"
+          onClose={() => setStatus(null)}
+          style={{ position: 'fixed', bottom: 20, right: 20, zIndex: 1000 }}
+        >
+          {status}
+        </Notification>
+      )}
+
+      {error && (
+        <Notification
+          color="red"
+          mt="md"
+          onClose={() => setError(null)}
+          style={{ position: 'fixed', bottom: 80, right: 20, zIndex: 1000 }}
+        >
+          {error}
+        </Notification>
+      )}
+    </Box>
+  );
+};
+
+export default FileEditor;

frontend/src/components/fileManagement/FileCard.tsx

@@ -6,9 +6,9 @@ import StorageIcon from "@mui/icons-material/Storage";
 import VisibilityIcon from "@mui/icons-material/Visibility";
 import EditIcon from "@mui/icons-material/Edit";
 
-import { FileWithUrl } from "../../types/file";
 import { getFileSize, getFileDate } from "../../utils/fileUtils";
 import { useIndexedDBThumbnail } from "../../hooks/useIndexedDBThumbnail";
+import { fileStorage } from "../../services/fileStorage";
 
 interface FileCardProps {
   file: FileWithUrl;

frontend/src/components/fileManagement/FileManager.tsx

@@ -1,440 +0,0 @@
-import React, { useState, useEffect } from "react";
-import { Box, Flex, Text, Notification, Button, Group } from "@mantine/core";
-import { Dropzone, MIME_TYPES } from "@mantine/dropzone";
-import { useTranslation } from "react-i18next";
-
-import { GlobalWorkerOptions } from "pdfjs-dist";
-import { StorageStats } from "../../services/fileStorage";
-import { FileWithUrl, defaultStorageConfig, initializeStorageConfig, StorageConfig } from "../../types/file";
-
-// Refactored imports
-import { fileOperationsService } from "../../services/fileOperationsService";
-import { checkStorageWarnings } from "../../utils/storageUtils";
-import StorageStatsCard from "./StorageStatsCard";
-import FileCard from "./FileCard";
-import FileUploadSelector from "../shared/FileUploadSelector";
-
-GlobalWorkerOptions.workerSrc = "/pdf.worker.js";
-
-interface FileManagerProps {
-  files: FileWithUrl[];
-  setFiles: React.Dispatch<React.SetStateAction<FileWithUrl[]>>;
-  allowMultiple?: boolean;
-  setCurrentView?: (view: string) => void;
-  onOpenFileEditor?: (selectedFiles?: FileWithUrl[]) => void;
-  onOpenPageEditor?: (selectedFiles?: FileWithUrl[]) => void;
-  onLoadFileToActive?: (file: File) => void;
-}
-
-const FileManager = ({
-  files = [],
-  setFiles,
-  allowMultiple = true,
-  setCurrentView,
-  onOpenFileEditor,
-  onOpenPageEditor,
-  onLoadFileToActive,
-}: FileManagerProps) => {
-  const { t } = useTranslation();
-  const [loading, setLoading] = useState(false);
-  const [storageStats, setStorageStats] = useState<StorageStats | null>(null);
-  const [notification, setNotification] = useState<string | null>(null);
-  const [filesLoaded, setFilesLoaded] = useState(false);
-  const [selectedFiles, setSelectedFiles] = useState<string[]>([]);
-  const [storageConfig, setStorageConfig] = useState<StorageConfig>(defaultStorageConfig);
-
-  // Extract operations from service for cleaner code
-  const {
-    loadStorageStats,
-    forceReloadFiles,
-    loadExistingFiles,
-    uploadFiles,
-    removeFile,
-    clearAllFiles,
-    createBlobUrlForFile,
-    checkForPurge,
-    updateStorageStatsIncremental
-  } = fileOperationsService;
-
-  // Add CSS for spinner animation
-  useEffect(() => {
-    if (!document.querySelector('#spinner-animation')) {
-      const style = document.createElement('style');
-      style.id = 'spinner-animation';
-      style.textContent = `
-        @keyframes spin {
-          0% { transform: rotate(0deg); }
-          100% { transform: rotate(360deg); }
-        }
-      `;
-      document.head.appendChild(style);
-    }
-  }, []);
-
-  // Load existing files from IndexedDB on mount
-  useEffect(() => {
-    if (!filesLoaded) {
-      handleLoadExistingFiles();
-    }
-  }, [filesLoaded]);
-
-  // Initialize storage configuration on mount
-  useEffect(() => {
-    const initStorage = async () => {
-      try {
-        const config = await initializeStorageConfig();
-        setStorageConfig(config);
-        console.log('Initialized storage config:', config);
-      } catch (error) {
-        console.warn('Failed to initialize storage config, using defaults:', error);
-      }
-    };
-
-    initStorage();
-  }, []);
-
-  // Load storage stats and set up periodic updates
-  useEffect(() => {
-    handleLoadStorageStats();
-
-    const interval = setInterval(async () => {
-      await handleLoadStorageStats();
-      await handleCheckForPurge();
-    }, 10000); // Update every 10 seconds
-
-    return () => clearInterval(interval);
-  }, []);
-
-  // Sync UI with IndexedDB whenever storage stats change
-  useEffect(() => {
-    const syncWithStorage = async () => {
-      if (storageStats && filesLoaded) {
-        // If file counts don't match, force reload
-        if (storageStats.fileCount !== files.length) {
-          console.warn('File count mismatch: storage has', storageStats.fileCount, 'but UI shows', files.length, '- forcing reload');
-          const reloadedFiles = await forceReloadFiles();
-          setFiles(reloadedFiles);
-        }
-      }
-    };
-
-    syncWithStorage();
-  }, [storageStats, filesLoaded, files.length]);
-
-  // Handlers using extracted operations
-  const handleLoadStorageStats = async () => {
-    const stats = await loadStorageStats();
-    if (stats) {
-      setStorageStats(stats);
-
-      // Check for storage warnings
-      const warning = checkStorageWarnings(stats);
-      if (warning) {
-        setNotification(warning);
-      }
-    }
-  };
-
-  const handleLoadExistingFiles = async () => {
-    try {
-      const loadedFiles = await loadExistingFiles(filesLoaded, files);
-      setFiles(loadedFiles);
-      setFilesLoaded(true);
-    } catch (error) {
-      console.error('Failed to load existing files:', error);
-      setFilesLoaded(true);
-    }
-  };
-
-  const handleCheckForPurge = async () => {
-    try {
-      const isPurged = await checkForPurge(files);
-      if (isPurged) {
-        console.warn('IndexedDB purge detected - forcing UI reload');
-        setNotification(t("fileManager.storageCleared", "Browser cleared storage. Files have been removed. Please re-upload."));
-        const reloadedFiles = await forceReloadFiles();
-        setFiles(reloadedFiles);
-        setFilesLoaded(true);
-      }
-    } catch (error) {
-      console.error('Error checking for purge:', error);
-    }
-  };
-
-  const validateStorageLimits = (filesToUpload: File[]): { valid: boolean; error?: string } => {
-    // Check individual file sizes
-    for (const file of filesToUpload) {
-      if (file.size > storageConfig.maxFileSize) {
-        const maxSizeMB = Math.round(storageConfig.maxFileSize / (1024 * 1024));
-        return {
-          valid: false,
-          error: `${t("storage.fileTooLarge", "File too large. Maximum size per file is")} ${maxSizeMB}MB`
-        };
-      }
-    }
-
-    // Check total storage capacity
-    if (storageStats) {
-      const totalNewSize = filesToUpload.reduce((sum, file) => sum + file.size, 0);
-      const projectedUsage = storageStats.totalSize + totalNewSize;
-
-      if (projectedUsage > storageConfig.maxTotalStorage) {
-        return {
-          valid: false,
-          error: t("storage.storageQuotaExceeded", "Storage quota exceeded. Please remove some files before uploading more.")
-        };
-      }
-    }
-
-    return { valid: true };
-  };
-
-  const handleDrop = async (uploadedFiles: File[]) => {
-    setLoading(true);
-
-    try {
-      // Validate storage limits before uploading
-      const validation = validateStorageLimits(uploadedFiles);
-      if (!validation.valid) {
-        setNotification(validation.error);
-        setLoading(false);
-        return;
-      }
-
-      const newFiles = await uploadFiles(uploadedFiles, storageConfig.useIndexedDB);
-
-      // Update files state
-      setFiles((prevFiles) => (allowMultiple ? [...prevFiles, ...newFiles] : newFiles));
-
-      // Update storage stats incrementally
-      if (storageStats) {
-        const updatedStats = updateStorageStatsIncremental(storageStats, 'add', newFiles);
-        setStorageStats(updatedStats);
-
-        // Check for storage warnings
-        const warning = checkStorageWarnings(updatedStats);
-        if (warning) {
-          setNotification(warning);
-        }
-      }
-    } catch (error) {
-      console.error('Error handling file drop:', error);
-      setNotification(t("fileManager.uploadError", "Failed to upload some files."));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  const handleRemoveFile = async (index: number) => {
-    const file = files[index];
-
-    try {
-      await removeFile(file);
-
-      // Update storage stats incrementally
-      if (storageStats) {
-        const updatedStats = updateStorageStatsIncremental(storageStats, 'remove', [file]);
-        setStorageStats(updatedStats);
-      }
-
-      setFiles((prevFiles) => prevFiles.filter((_, i) => i !== index));
-    } catch (error) {
-      console.error('Failed to remove file:', error);
-    }
-  };
-
-  const handleClearAll = async () => {
-    try {
-      await clearAllFiles(files);
-
-      // Reset storage stats
-      if (storageStats) {
-        const clearedStats = updateStorageStatsIncremental(storageStats, 'clear');
-        setStorageStats(clearedStats);
-      }
-
-      setFiles([]);
-    } catch (error) {
-      console.error('Failed to clear all files:', error);
-    }
-  };
-
-  const handleReloadFiles = () => {
-    setFilesLoaded(false);
-    setFiles([]);
-  };
-
-  const handleFileDoubleClick = async (file: FileWithUrl) => {
-    try {
-      // Reconstruct File object from storage and add to active files
-      if (onLoadFileToActive) {
-        const reconstructedFile = await reconstructFileFromStorage(file);
-        onLoadFileToActive(reconstructedFile);
-        setCurrentView && setCurrentView("viewer");
-      }
-    } catch (error) {
-      console.error('Failed to load file to active set:', error);
-      setNotification(t("fileManager.failedToOpen", "Failed to open file. It may have been removed from storage."));
-    }
-  };
-
-  const handleFileView = async (file: FileWithUrl) => {
-    try {
-      // Reconstruct File object from storage and add to active files
-      if (onLoadFileToActive) {
-        const reconstructedFile = await reconstructFileFromStorage(file);
-        onLoadFileToActive(reconstructedFile);
-        setCurrentView && setCurrentView("viewer");
-      }
-    } catch (error) {
-      console.error('Failed to load file to active set:', error);
-      setNotification(t("fileManager.failedToOpen", "Failed to open file. It may have been removed from storage."));
-    }
-  };
-
-  const reconstructFileFromStorage = async (fileWithUrl: FileWithUrl): Promise<File> => {
-    // If it's already a regular file, return it
-    if (fileWithUrl instanceof File) {
-      return fileWithUrl;
-    }
-
-    // Reconstruct from IndexedDB
-    const arrayBuffer = await createBlobUrlForFile(fileWithUrl);
-    if (typeof arrayBuffer === 'string') {
-      // createBlobUrlForFile returned a blob URL, we need the actual data
-      const response = await fetch(arrayBuffer);
-      const data = await response.arrayBuffer();
-      return new File([data], fileWithUrl.name, {
-        type: fileWithUrl.type || 'application/pdf',
-        lastModified: fileWithUrl.lastModified || Date.now()
-      });
-    } else {
-      return new File([arrayBuffer], fileWithUrl.name, {
-        type: fileWithUrl.type || 'application/pdf',
-        lastModified: fileWithUrl.lastModified || Date.now()
-      });
-    }
-  };
-
-  const handleFileEdit = (file: FileWithUrl) => {
-    if (onOpenFileEditor) {
-      onOpenFileEditor([file]);
-    }
-  };
-
-  const toggleFileSelection = (fileId: string) => {
-    setSelectedFiles(prev =>
-      prev.includes(fileId)
-        ? prev.filter(id => id !== fileId)
-        : [...prev, fileId]
-    );
-  };
-
-  const handleOpenSelectedInEditor = () => {
-    if (onOpenFileEditor && selectedFiles.length > 0) {
-      const selected = files.filter(f => selectedFiles.includes(f.id || f.name));
-      onOpenFileEditor(selected);
-    }
-  };
-
-  const handleOpenSelectedInPageEditor = () => {
-    if (onOpenPageEditor && selectedFiles.length > 0) {
-      const selected = files.filter(f => selectedFiles.includes(f.id || f.name));
-      onOpenPageEditor(selected);
-    }
-  };
-
-  return (
-    <div style={{
-      width: "100%",
-      justifyContent: "center",
-      display: "flex",
-      flexDirection: "column",
-      alignItems: "center",
-      paddingTop: "3rem"
-    }}>
-
-      {/* File upload is now handled by FileUploadSelector when no files exist */}
-
-      {/* Storage Stats Card */}
-      <StorageStatsCard
-        storageStats={storageStats}
-        filesCount={files.length}
-        onClearAll={handleClearAll}
-        onReloadFiles={handleReloadFiles}
-        storageConfig={storageConfig}
-      />
-
-      {/* Multi-selection controls */}
-      {selectedFiles.length > 0 && (
-        <Box mb="md" p="md" style={{ backgroundColor: 'var(--mantine-color-blue-0)', borderRadius: 8 }}>
-          <Group justify="space-between">
-            <Text size="sm">
-              {selectedFiles.length} {t("fileManager.filesSelected", "files selected")}
-            </Text>
-            <Group>
-              <Button
-                size="xs"
-                variant="light"
-                onClick={() => setSelectedFiles([])}
-              >
-                {t("fileManager.clearSelection", "Clear Selection")}
-              </Button>
-              <Button
-                size="xs"
-                color="orange"
-                onClick={handleOpenSelectedInEditor}
-                disabled={selectedFiles.length === 0}
-              >
-                {t("fileManager.openInFileEditor", "Open in File Editor")}
-              </Button>
-              <Button
-                size="xs"
-                color="blue"
-                onClick={handleOpenSelectedInPageEditor}
-                disabled={selectedFiles.length === 0}
-              >
-                {t("fileManager.openInPageEditor", "Open in Page Editor")}
-              </Button>
-            </Group>
-          </Group>
-        </Box>
-      )}
-
-
-          <Flex
-            wrap="wrap"
-            gap="lg"
-            justify="flex-start"
-            style={{ width: "90%", marginTop: "1rem"}}
-          >
-            {files.map((file, idx) => (
-              <FileCard
-                key={file.id || file.name + idx}
-                file={file}
-                onRemove={() => handleRemoveFile(idx)}
-                onDoubleClick={() => handleFileDoubleClick(file)}
-                onView={() => handleFileView(file)}
-                onEdit={() => handleFileEdit(file)}
-                isSelected={selectedFiles.includes(file.id || file.name)}
-                onSelect={() => toggleFileSelection(file.id || file.name)}
-              />
-            ))}
-          </Flex>
-
-
-      {/* Notifications */}
-      {notification && (
-        <Notification
-          color="blue"
-          onClose={() => setNotification(null)}
-          style={{ position: "fixed", bottom: 20, right: 20, zIndex: 1000 }}
-        >
-          {notification}
-        </Notification>
-      )}
-    </div>
-  );
-};
-
-export default FileManager;

frontend/src/components/history/FileOperationHistory.tsx

@@ -0,0 +1,177 @@
+import React from 'react';
+import {
+  Stack,
+  Paper,
+  Text,
+  Badge,
+  Group,
+  Collapse,
+  Box,
+  ScrollArea,
+  Code,
+  Divider
+} from '@mantine/core';
+import { useFileContext } from '../../contexts/FileContext';
+import { FileOperation, FileOperationHistory as FileOperationHistoryType } from '../../types/fileContext';
+import { PageOperation } from '../../types/pageEditor';
+
+interface FileOperationHistoryProps {
+  fileId: string;
+  showOnlyApplied?: boolean;
+  maxHeight?: number;
+}
+
+const FileOperationHistory: React.FC<FileOperationHistoryProps> = ({
+  fileId,
+  showOnlyApplied = false,
+  maxHeight = 400
+}) => {
+  const { getFileHistory, getAppliedOperations } = useFileContext();
+  
+  const history = getFileHistory(fileId);
+  const operations = showOnlyApplied ? getAppliedOperations(fileId) : history?.operations || [];
+
+  const formatTimestamp = (timestamp: number) => {
+    return new Date(timestamp).toLocaleString();
+  };
+
+  const getOperationIcon = (type: string) => {
+    switch (type) {
+      case 'split': return '✂️';
+      case 'merge': return '🔗';
+      case 'compress': return '🗜️';
+      case 'rotate': return '🔄';
+      case 'delete': return '🗑️';
+      case 'move': return '↕️';
+      case 'insert': return '📄';
+      case 'upload': return '⬆️';
+      case 'add': return '➕';
+      case 'remove': return '➖';
+      case 'replace': return '🔄';
+      case 'convert': return '🔄';
+      default: return '⚙️';
+    }
+  };
+
+  const getStatusColor = (status: string) => {
+    switch (status) {
+      case 'applied': return 'green';
+      case 'failed': return 'red';
+      case 'pending': return 'yellow';
+      default: return 'gray';
+    }
+  };
+
+  const renderOperationDetails = (operation: FileOperation | PageOperation) => {
+    if ('metadata' in operation && operation.metadata) {
+      const { metadata } = operation;
+      return (
+        <Box mt="xs">
+          {metadata.parameters && (
+            <Text size="xs" c="dimmed">
+              Parameters: <Code>{JSON.stringify(metadata.parameters, null, 2)}</Code>
+            </Text>
+          )}
+          {metadata.originalFileName && (
+            <Text size="xs" c="dimmed">
+              Original file: {metadata.originalFileName}
+            </Text>
+          )}
+          {metadata.outputFileNames && (
+            <Text size="xs" c="dimmed">
+              Output files: {metadata.outputFileNames.join(', ')}
+            </Text>
+          )}
+          {metadata.fileSize && (
+            <Text size="xs" c="dimmed">
+              File size: {(metadata.fileSize / 1024 / 1024).toFixed(2)} MB
+            </Text>
+          )}
+          {metadata.pageCount && (
+            <Text size="xs" c="dimmed">
+              Pages: {metadata.pageCount}
+            </Text>
+          )}
+          {metadata.error && (
+            <Text size="xs" c="red">
+              Error: {metadata.error}
+            </Text>
+          )}
+        </Box>
+      );
+    }
+    return null;
+  };
+
+  if (!history || operations.length === 0) {
+    return (
+      <Paper p="md" withBorder>
+        <Text c="dimmed" ta="center">
+          {showOnlyApplied ? 'No applied operations found' : 'No operation history available'}
+        </Text>
+      </Paper>
+    );
+  }
+
+  return (
+    <Paper p="md" withBorder>
+      <Group justify="space-between" mb="md">
+        <Text fw={500}>
+          {showOnlyApplied ? 'Applied Operations' : 'Operation History'}
+        </Text>
+        <Badge variant="light" color="blue">
+          {operations.length} operations
+        </Badge>
+      </Group>
+
+      <ScrollArea h={maxHeight}>
+        <Stack gap="sm">
+          {operations.map((operation, index) => (
+            <Paper key={operation.id} p="sm" withBorder radius="sm" bg="gray.0">
+              <Group justify="space-between" align="start">
+                <Group gap="xs">
+                  <Text span size="lg">
+                    {getOperationIcon(operation.type)}
+                  </Text>
+                  <Box>
+                    <Text fw={500} size="sm">
+                      {operation.type.charAt(0).toUpperCase() + operation.type.slice(1)}
+                    </Text>
+                    <Text size="xs" c="dimmed">
+                      {formatTimestamp(operation.timestamp)}
+                    </Text>
+                  </Box>
+                </Group>
+                
+                <Badge
+                  variant="filled"
+                  color={getStatusColor(operation.status)}
+                  size="sm"
+                >
+                  {operation.status}
+                </Badge>
+              </Group>
+
+              {renderOperationDetails(operation)}
+
+              {index < operations.length - 1 && <Divider mt="sm" />}
+            </Paper>
+          ))}
+        </Stack>
+      </ScrollArea>
+
+      {history && (
+        <Group justify="space-between" mt="sm" pt="sm" style={{ borderTop: '1px solid var(--mantine-color-gray-3)' }}>
+          <Text size="xs" c="dimmed">
+            Created: {formatTimestamp(history.createdAt)}
+          </Text>
+          <Text size="xs" c="dimmed">
+            Last modified: {formatTimestamp(history.lastModified)}
+          </Text>
+        </Group>
+      )}
+    </Paper>
+  );
+};
+
+export default FileOperationHistory;

frontend/src/components/pageEditor/BulkSelectionPanel.tsx

@@ -4,7 +4,7 @@ import { Paper, Group, TextInput, Button, Text } from '@mantine/core';
 interface BulkSelectionPanelProps {
   csvInput: string;
   setCsvInput: (value: string) => void;
-  selectedPages: string[];
+  selectedPages: number[];
   onUpdatePagesFromCSV: () => void;
 }
 

frontend/src/components/pageEditor/DragDropGrid.tsx

@@ -9,21 +9,21 @@ interface DragDropItem {
 
 interface DragDropGridProps<T extends DragDropItem> {
   items: T[];
-  selectedItems: string[];
+  selectedItems: number[];
   selectionMode: boolean;
   isAnimating: boolean;
-  onDragStart: (itemId: string) => void;
+  onDragStart: (pageNumber: number) => void;
   onDragEnd: () => void;
   onDragOver: (e: React.DragEvent) => void;
-  onDragEnter: (itemId: string) => void;
+  onDragEnter: (pageNumber: number) => void;
   onDragLeave: () => void;
-  onDrop: (e: React.DragEvent, targetId: string | 'end') => void;
+  onDrop: (e: React.DragEvent, targetPageNumber: number | 'end') => void;
   onEndZoneDragEnter: () => void;
   renderItem: (item: T, index: number, refs: React.MutableRefObject<Map<string, HTMLDivElement>>) => React.ReactNode;
   renderSplitMarker?: (item: T, index: number) => React.ReactNode;
-  draggedItem: string | null;
-  dropTarget: string | null;
-  multiItemDrag: {itemIds: string[], count: number} | null;
+  draggedItem: number | null;
+  dropTarget: number | null;
+  multiItemDrag: {pageNumbers: number[], count: number} | null;
   dragPosition: {x: number, y: number} | null;
 }
 
@@ -77,7 +77,13 @@ const DragDropGrid = <T extends DragDropItem>({
           flexWrap: 'wrap',
           gap: '1.5rem',
           justifyContent: 'flex-start',
-          paddingBottom: '100px'
+          paddingBottom: '100px',
+          // Performance optimizations for smooth scrolling
+          willChange: 'scroll-position',
+          transform: 'translateZ(0)', // Force hardware acceleration
+          backfaceVisibility: 'hidden',
+          // Use containment for better rendering performance
+          contain: 'layout style paint',
         }}
       >
         {items.map((item, index) => (

frontend/src/components/pageEditor/FileEditor.tsx

@@ -1,561 +0,0 @@
-import React, { useState, useCallback, useRef, useEffect } from 'react';
-import {
-  Button, Text, Center, Box, Notification, TextInput, LoadingOverlay, Modal, Alert, Container,
-  Stack, Group
-} from '@mantine/core';
-import { Dropzone } from '@mantine/dropzone';
-import { useTranslation } from 'react-i18next';
-import UploadFileIcon from '@mui/icons-material/UploadFile';
-import { fileStorage } from '../../services/fileStorage';
-import { generateThumbnailForFile } from '../../utils/thumbnailUtils';
-import styles from './PageEditor.module.css';
-import FileThumbnail from './FileThumbnail';
-import BulkSelectionPanel from './BulkSelectionPanel';
-import DragDropGrid from './DragDropGrid';
-import FilePickerModal from '../shared/FilePickerModal';
-
-interface FileItem {
-  id: string;
-  name: string;
-  pageCount: number;
-  thumbnail: string;
-  size: number;
-  file: File;
-  splitBefore?: boolean;
-}
-
-interface FileEditorProps {
-  onOpenPageEditor?: (file: File) => void;
-  onMergeFiles?: (files: File[]) => void;
-  activeFiles?: File[];
-  setActiveFiles?: (files: File[]) => void;
-  preSelectedFiles?: { file: File; url: string }[];
-  onClearPreSelection?: () => void;
-}
-
-const FileEditor = ({
-  onOpenPageEditor,
-  onMergeFiles,
-  activeFiles = [],
-  setActiveFiles,
-  preSelectedFiles = [],
-  onClearPreSelection
-}: FileEditorProps) => {
-  const { t } = useTranslation();
-
-  const [files, setFiles] = useState<FileItem[]>([]);
-  const [selectedFiles, setSelectedFiles] = useState<string[]>([]);
-  const [status, setStatus] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [csvInput, setCsvInput] = useState<string>('');
-  const [selectionMode, setSelectionMode] = useState(false);
-  const [draggedFile, setDraggedFile] = useState<string | null>(null);
-  const [dropTarget, setDropTarget] = useState<string | null>(null);
-  const [multiFileDrag, setMultiFileDrag] = useState<{fileIds: string[], count: number} | null>(null);
-  const [dragPosition, setDragPosition] = useState<{x: number, y: number} | null>(null);
-  const [isAnimating, setIsAnimating] = useState(false);
-  const [showFilePickerModal, setShowFilePickerModal] = useState(false);
-  const fileRefs = useRef<Map<string, HTMLDivElement>>(new Map());
-
-  // Convert shared files to FileEditor format
-  const convertToFileItem = useCallback(async (sharedFile: any): Promise<FileItem> => {
-    // Generate thumbnail if not already available
-    const thumbnail = sharedFile.thumbnail || await generateThumbnailForFile(sharedFile.file || sharedFile);
-
-    return {
-      id: sharedFile.id || `file-${Date.now()}-${Math.random()}`,
-      name: (sharedFile.file?.name || sharedFile.name || 'unknown').replace(/\.pdf$/i, ''),
-      pageCount: sharedFile.pageCount || Math.floor(Math.random() * 20) + 1, // Mock for now
-      thumbnail,
-      size: sharedFile.file?.size || sharedFile.size || 0,
-      file: sharedFile.file || sharedFile,
-    };
-  }, []);
-
-  // Convert activeFiles to FileItem format
-  useEffect(() => {
-    const convertActiveFiles = async () => {
-      if (activeFiles.length > 0) {
-        setLoading(true);
-        try {
-          const convertedFiles = await Promise.all(
-            activeFiles.map(async (file) => {
-              const thumbnail = await generateThumbnailForFile(file);
-              return {
-                id: `file-${Date.now()}-${Math.random()}`,
-                name: file.name.replace(/\.pdf$/i, ''),
-                pageCount: Math.floor(Math.random() * 20) + 1, // Mock for now
-                thumbnail,
-                size: file.size,
-                file,
-              };
-            })
-          );
-          setFiles(convertedFiles);
-        } catch (err) {
-          console.error('Error converting active files:', err);
-        } finally {
-          setLoading(false);
-        }
-      } else {
-        setFiles([]);
-      }
-    };
-
-    convertActiveFiles();
-  }, [activeFiles]);
-
-  // Only load shared files when explicitly passed (not on mount)
-  useEffect(() => {
-    const loadSharedFiles = async () => {
-      // Only load if we have pre-selected files (coming from FileManager)
-      if (preSelectedFiles.length > 0) {
-        setLoading(true);
-        try {
-          const convertedFiles = await Promise.all(
-            preSelectedFiles.map(convertToFileItem)
-          );
-          if (setActiveFiles) {
-            const updatedActiveFiles = convertedFiles.map(fileItem => fileItem.file);
-            setActiveFiles(updatedActiveFiles);
-          }
-        } catch (err) {
-          console.error('Error converting pre-selected files:', err);
-        } finally {
-          setLoading(false);
-        }
-      }
-    };
-
-    loadSharedFiles();
-  }, [preSelectedFiles, convertToFileItem]);
-
-  // Handle pre-selected files
-  useEffect(() => {
-    if (preSelectedFiles.length > 0) {
-      const preSelectedIds = preSelectedFiles.map(f => f.id || f.name);
-      setSelectedFiles(preSelectedIds);
-      onClearPreSelection?.();
-    }
-  }, [preSelectedFiles, onClearPreSelection]);
-
-  // Process uploaded files
-  const handleFileUpload = useCallback(async (uploadedFiles: File[]) => {
-    setLoading(true);
-    setError(null);
-
-    try {
-      const newFiles: FileItem[] = [];
-
-      for (const file of uploadedFiles) {
-        if (file.type !== 'application/pdf') {
-          setError('Please upload only PDF files');
-          continue;
-        }
-
-        // Generate thumbnail and get page count
-        const thumbnail = await generateThumbnailForFile(file);
-
-        const fileItem: FileItem = {
-          id: `file-${Date.now()}-${Math.random()}`,
-          name: file.name.replace(/\.pdf$/i, ''),
-          pageCount: Math.floor(Math.random() * 20) + 1, // Mock page count
-          thumbnail,
-          size: file.size,
-          file,
-        };
-
-        newFiles.push(fileItem);
-
-        // Store in IndexedDB
-        await fileStorage.storeFile(file, thumbnail);
-      }
-
-      if (setActiveFiles) {
-        setActiveFiles(prev => [...prev, ...newFiles.map(f => f.file)]);
-      }
-
-      setStatus(`Added ${newFiles.length} files`);
-    } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : 'Failed to process files';
-      setError(errorMessage);
-      console.error('File processing error:', err);
-    } finally {
-      setLoading(false);
-    }
-  }, [setActiveFiles]);
-
-  const selectAll = useCallback(() => {
-    setSelectedFiles(files.map(f => f.id));
-  }, [files]);
-
-  const deselectAll = useCallback(() => setSelectedFiles([]), []);
-
-  const toggleFile = useCallback((fileId: string) => {
-    setSelectedFiles(prev =>
-      prev.includes(fileId)
-        ? prev.filter(id => id !== fileId)
-        : [...prev, fileId]
-    );
-  }, []);
-
-  const toggleSelectionMode = useCallback(() => {
-    setSelectionMode(prev => {
-      const newMode = !prev;
-      if (!newMode) {
-        setSelectedFiles([]);
-        setCsvInput('');
-      }
-      return newMode;
-    });
-  }, []);
-
-  const parseCSVInput = useCallback((csv: string) => {
-    const fileIds: string[] = [];
-    const ranges = csv.split(',').map(s => s.trim()).filter(Boolean);
-
-    ranges.forEach(range => {
-      if (range.includes('-')) {
-        const [start, end] = range.split('-').map(n => parseInt(n.trim()));
-        for (let i = start; i <= end && i <= files.length; i++) {
-          if (i > 0) {
-            const file = files[i - 1];
-            if (file) fileIds.push(file.id);
-          }
-        }
-      } else {
-        const fileIndex = parseInt(range);
-        if (fileIndex > 0 && fileIndex <= files.length) {
-          const file = files[fileIndex - 1];
-          if (file) fileIds.push(file.id);
-        }
-      }
-    });
-
-    return fileIds;
-  }, [files]);
-
-  const updateFilesFromCSV = useCallback(() => {
-    const fileIds = parseCSVInput(csvInput);
-    setSelectedFiles(fileIds);
-  }, [csvInput, parseCSVInput]);
-
-  // Drag and drop handlers
-  const handleDragStart = useCallback((fileId: string) => {
-    setDraggedFile(fileId);
-
-    if (selectionMode && selectedFiles.includes(fileId) && selectedFiles.length > 1) {
-      setMultiFileDrag({
-        fileIds: selectedFiles,
-        count: selectedFiles.length
-      });
-    } else {
-      setMultiFileDrag(null);
-    }
-  }, [selectionMode, selectedFiles]);
-
-  const handleDragEnd = useCallback(() => {
-    setDraggedFile(null);
-    setDropTarget(null);
-    setMultiFileDrag(null);
-    setDragPosition(null);
-  }, []);
-
-  const handleDragOver = useCallback((e: React.DragEvent) => {
-    e.preventDefault();
-
-    if (!draggedFile) return;
-
-    if (multiFileDrag) {
-      setDragPosition({ x: e.clientX, y: e.clientY });
-    }
-
-    const elementUnderCursor = document.elementFromPoint(e.clientX, e.clientY);
-    if (!elementUnderCursor) return;
-
-    const fileContainer = elementUnderCursor.closest('[data-file-id]');
-    if (fileContainer) {
-      const fileId = fileContainer.getAttribute('data-file-id');
-      if (fileId && fileId !== draggedFile) {
-        setDropTarget(fileId);
-        return;
-      }
-    }
-
-    const endZone = elementUnderCursor.closest('[data-drop-zone="end"]');
-    if (endZone) {
-      setDropTarget('end');
-      return;
-    }
-
-    setDropTarget(null);
-  }, [draggedFile, multiFileDrag]);
-
-  const handleDragEnter = useCallback((fileId: string) => {
-    if (draggedFile && fileId !== draggedFile) {
-      setDropTarget(fileId);
-    }
-  }, [draggedFile]);
-
-  const handleDragLeave = useCallback(() => {
-    // Let dragover handle this
-  }, []);
-
-  const handleDrop = useCallback((e: React.DragEvent, targetFileId: string | 'end') => {
-    e.preventDefault();
-    if (!draggedFile || draggedFile === targetFileId) return;
-
-    let targetIndex: number;
-    if (targetFileId === 'end') {
-      targetIndex = files.length;
-    } else {
-      targetIndex = files.findIndex(f => f.id === targetFileId);
-      if (targetIndex === -1) return;
-    }
-
-    const filesToMove = selectionMode && selectedFiles.includes(draggedFile)
-      ? selectedFiles
-      : [draggedFile];
-
-    if (setActiveFiles) {
-      // Update the local files state and sync with activeFiles
-      setFiles(prev => {
-        const newFiles = [...prev];
-        const movedFiles = filesToMove.map(id => newFiles.find(f => f.id === id)!).filter(Boolean);
-
-        // Remove moved files
-        filesToMove.forEach(id => {
-          const index = newFiles.findIndex(f => f.id === id);
-          if (index !== -1) newFiles.splice(index, 1);
-        });
-
-        // Insert at target position
-        newFiles.splice(targetIndex, 0, ...movedFiles);
-
-        // Update activeFiles with the reordered File objects
-        setActiveFiles(newFiles.map(f => f.file));
-
-        return newFiles;
-      });
-    }
-
-    const moveCount = multiFileDrag ? multiFileDrag.count : 1;
-    setStatus(`${moveCount > 1 ? `${moveCount} files` : 'File'} reordered`);
-
-    handleDragEnd();
-  }, [draggedFile, files, selectionMode, selectedFiles, multiFileDrag, handleDragEnd, setActiveFiles]);
-
-  const handleEndZoneDragEnter = useCallback(() => {
-    if (draggedFile) {
-      setDropTarget('end');
-    }
-  }, [draggedFile]);
-
-  // File operations
-  const handleDeleteFile = useCallback((fileId: string) => {
-    if (setActiveFiles) {
-      // Remove from local files and sync with activeFiles
-      setFiles(prev => {
-        const newFiles = prev.filter(f => f.id !== fileId);
-        setActiveFiles(newFiles.map(f => f.file));
-        return newFiles;
-      });
-    }
-    setSelectedFiles(prev => prev.filter(id => id !== fileId));
-  }, [setActiveFiles]);
-
-  const handleViewFile = useCallback((fileId: string) => {
-    const file = files.find(f => f.id === fileId);
-    if (file && onOpenPageEditor) {
-      onOpenPageEditor(file.file);
-    }
-  }, [files, onOpenPageEditor]);
-
-  const handleMergeFromHere = useCallback((fileId: string) => {
-    const startIndex = files.findIndex(f => f.id === fileId);
-    if (startIndex === -1) return;
-
-    const filesToMerge = files.slice(startIndex).map(f => f.file);
-    if (onMergeFiles) {
-      onMergeFiles(filesToMerge);
-    }
-  }, [files, onMergeFiles]);
-
-  const handleSplitFile = useCallback((fileId: string) => {
-    const file = files.find(f => f.id === fileId);
-    if (file && onOpenPageEditor) {
-      onOpenPageEditor(file.file);
-    }
-  }, [files, onOpenPageEditor]);
-
-  const handleLoadFromStorage = useCallback(async (selectedFiles: any[]) => {
-    if (selectedFiles.length === 0) return;
-
-    setLoading(true);
-    try {
-      const convertedFiles = await Promise.all(
-        selectedFiles.map(convertToFileItem)
-      );
-      setFiles(prev => [...prev, ...convertedFiles]);
-      setStatus(`Loaded ${selectedFiles.length} files from storage`);
-    } catch (err) {
-      console.error('Error loading files from storage:', err);
-      setError('Failed to load some files from storage');
-    } finally {
-      setLoading(false);
-    }
-  }, [convertToFileItem]);
-
-
-  return (
-    <Box pos="relative" h="100vh" style={{ overflow: 'auto' }}>
-      <LoadingOverlay visible={loading} />
-
-      <Box p="md" pt="xl">
-        <Group mb="md">
-          <Button
-            onClick={toggleSelectionMode}
-            variant={selectionMode ? "filled" : "outline"}
-            color={selectionMode ? "blue" : "gray"}
-            styles={{
-              root: {
-                transition: 'all 0.2s ease',
-                ...(selectionMode && {
-                  boxShadow: '0 2px 8px rgba(59, 130, 246, 0.3)',
-                })
-              }
-            }}
-          >
-            {selectionMode ? "Exit Selection" : "Select Files"}
-          </Button>
-          {selectionMode && (
-            <>
-              <Button onClick={selectAll} variant="light">Select All</Button>
-              <Button onClick={deselectAll} variant="light">Deselect All</Button>
-            </>
-          )}
-
-          {/* Load from storage and upload buttons */}
-          <Button
-            variant="outline"
-            color="blue"
-            onClick={() => setShowFilePickerModal(true)}
-          >
-            Load from Storage
-          </Button>
-
-          <Dropzone
-            onDrop={handleFileUpload}
-            accept={["application/pdf"]}
-            multiple={true}
-            maxSize={2 * 1024 * 1024 * 1024}
-            style={{ display: 'contents' }}
-          >
-            <Button variant="outline" color="green">
-              Upload Files
-            </Button>
-          </Dropzone>
-        </Group>
-
-        {selectionMode && (
-          <BulkSelectionPanel
-            csvInput={csvInput}
-            setCsvInput={setCsvInput}
-            selectedPages={selectedFiles}
-            onUpdatePagesFromCSV={updateFilesFromCSV}
-          />
-        )}
-
-        <DragDropGrid
-          items={files}
-          selectedItems={selectedFiles}
-          selectionMode={selectionMode}
-          isAnimating={isAnimating}
-          onDragStart={handleDragStart}
-          onDragEnd={handleDragEnd}
-          onDragOver={handleDragOver}
-          onDragEnter={handleDragEnter}
-          onDragLeave={handleDragLeave}
-          onDrop={handleDrop}
-          onEndZoneDragEnter={handleEndZoneDragEnter}
-          draggedItem={draggedFile}
-          dropTarget={dropTarget}
-          multiItemDrag={multiFileDrag}
-          dragPosition={dragPosition}
-          renderItem={(file, index, refs) => (
-            <FileThumbnail
-              file={file}
-              index={index}
-              totalFiles={files.length}
-              selectedFiles={selectedFiles}
-              selectionMode={selectionMode}
-              draggedFile={draggedFile}
-              dropTarget={dropTarget}
-              isAnimating={isAnimating}
-              fileRefs={refs}
-              onDragStart={handleDragStart}
-              onDragEnd={handleDragEnd}
-              onDragOver={handleDragOver}
-              onDragEnter={handleDragEnter}
-              onDragLeave={handleDragLeave}
-              onDrop={handleDrop}
-              onToggleFile={toggleFile}
-              onDeleteFile={handleDeleteFile}
-              onViewFile={handleViewFile}
-              onMergeFromHere={handleMergeFromHere}
-              onSplitFile={handleSplitFile}
-              onSetStatus={setStatus}
-            />
-          )}
-          renderSplitMarker={(file, index) => (
-            <div
-              style={{
-                width: '2px',
-                height: '24rem',
-                borderLeft: '2px dashed #3b82f6',
-                backgroundColor: 'transparent',
-                marginLeft: '-0.75rem',
-                marginRight: '-0.75rem',
-                flexShrink: 0
-              }}
-            />
-          )}
-        />
-      </Box>
-
-      {/* File Picker Modal */}
-      <FilePickerModal
-        opened={showFilePickerModal}
-        onClose={() => setShowFilePickerModal(false)}
-        storedFiles={[]} // FileEditor doesn't have access to stored files, needs to be passed from parent
-        onSelectFiles={handleLoadFromStorage}
-        allowMultiple={true}
-      />
-
-      {status && (
-        <Notification
-          color="blue"
-          mt="md"
-          onClose={() => setStatus(null)}
-          style={{ position: 'fixed', bottom: 20, right: 20, zIndex: 1000 }}
-        >
-          {status}
-        </Notification>
-      )}
-
-      {error && (
-        <Notification
-          color="red"
-          mt="md"
-          onClose={() => setError(null)}
-          style={{ position: 'fixed', bottom: 80, right: 20, zIndex: 1000 }}
-        >
-          {error}
-        </Notification>
-      )}
-    </Box>
-  );
-};
-
-export default FileEditor;

frontend/src/components/pageEditor/FileThumbnail.tsx

@@ -1,11 +1,11 @@
-import React from 'react';
-import { Text, Checkbox, Tooltip, ActionIcon, Badge } from '@mantine/core';
-import DeleteIcon from '@mui/icons-material/Delete';
+import React, { useState } from 'react';
+import { Text, Checkbox, Tooltip, ActionIcon, Badge, Modal } from '@mantine/core';
+import CloseIcon from '@mui/icons-material/Close';
 import VisibilityIcon from '@mui/icons-material/Visibility';
-import MergeIcon from '@mui/icons-material/Merge';
-import SplitscreenIcon from '@mui/icons-material/Splitscreen';
+import HistoryIcon from '@mui/icons-material/History';
 import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
 import styles from './PageEditor.module.css';
+import FileOperationHistory from '../history/FileOperationHistory';
 
 interface FileItem {
   id: string;
@@ -35,9 +35,8 @@ interface FileThumbnailProps {
   onToggleFile: (fileId: string) => void;
   onDeleteFile: (fileId: string) => void;
   onViewFile: (fileId: string) => void;
-  onMergeFromHere: (fileId: string) => void;
-  onSplitFile: (fileId: string) => void;
   onSetStatus: (status: string) => void;
+  toolMode?: boolean;
 }
 
 const FileThumbnail = ({
@@ -59,10 +58,11 @@ const FileThumbnail = ({
   onToggleFile,
   onDeleteFile,
   onViewFile,
-  onMergeFromHere,
-  onSplitFile,
   onSetStatus,
+  toolMode = false,
 }: FileThumbnailProps) => {
+  const [showHistory, setShowHistory] = useState(false);
+
   const formatFileSize = (bytes: number) => {
     if (bytes === 0) return '0 B';
     const k = 1024;
@@ -238,63 +238,53 @@ const FileThumbnail = ({
             whiteSpace: 'nowrap'
           }}
         >
-          <Tooltip label="View File">
+          {!toolMode && (
+            <>
+              <Tooltip label="View File">
+                <ActionIcon
+                  size="md"
+                  variant="subtle"
+                  c="white"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    onViewFile(file.id);
+                    onSetStatus(`Opened ${file.name}`);
+                  }}
+                >
+                  <VisibilityIcon style={{ fontSize: 20 }} />
+                </ActionIcon>
+              </Tooltip>
+
+            </>
+          )}
+
+          <Tooltip label="View History">
             <ActionIcon
               size="md"
               variant="subtle"
               c="white"
               onClick={(e) => {
                 e.stopPropagation();
-                onViewFile(file.id);
-                onSetStatus(`Opened ${file.name}`);
+                setShowHistory(true);
+                onSetStatus(`Viewing history for ${file.name}`);
               }}
             >
-              <VisibilityIcon style={{ fontSize: 20 }} />
+              <HistoryIcon style={{ fontSize: 20 }} />
             </ActionIcon>
           </Tooltip>
 
-          <Tooltip label="Merge from here">
+          <Tooltip label="Close File">
             <ActionIcon
               size="md"
               variant="subtle"
-              c="white"
-              onClick={(e) => {
-                e.stopPropagation();
-                onMergeFromHere(file.id);
-                onSetStatus(`Starting merge from ${file.name}`);
-              }}
-            >
-              <MergeIcon style={{ fontSize: 20 }} />
-            </ActionIcon>
-          </Tooltip>
-
-          <Tooltip label="Split File">
-            <ActionIcon
-              size="md"
-              variant="subtle"
-              c="white"
-              onClick={(e) => {
-                e.stopPropagation();
-                onSplitFile(file.id);
-                onSetStatus(`Opening ${file.name} in page editor`);
-              }}
-            >
-              <SplitscreenIcon style={{ fontSize: 20 }} />
-            </ActionIcon>
-          </Tooltip>
-
-          <Tooltip label="Delete File">
-            <ActionIcon
-              size="md"
-              variant="subtle"
-              c="red"
+              c="orange"
               onClick={(e) => {
                 e.stopPropagation();
                 onDeleteFile(file.id);
-                onSetStatus(`Deleted ${file.name}`);
+                onSetStatus(`Closed ${file.name}`);
               }}
             >
-              <DeleteIcon style={{ fontSize: 20 }} />
+              <CloseIcon style={{ fontSize: 20 }} />
             </ActionIcon>
           </Tooltip>
         </div>
@@ -320,6 +310,21 @@ const FileThumbnail = ({
           {formatFileSize(file.size)}
         </Text>
       </div>
+
+      {/* History Modal */}
+      <Modal
+        opened={showHistory}
+        onClose={() => setShowHistory(false)}
+        title={`Operation History - ${file.name}`}
+        size="lg"
+        scrollAreaComponent="div"
+      >
+        <FileOperationHistory 
+          fileId={file.name} 
+          showOnlyApplied={true}
+          maxHeight={500}
+        />
+      </Modal>
     </div>
   );
 };

frontend/src/components/pageEditor/PageEditor.module.css

@@ -1,10 +1,14 @@
-/* Page container hover effects */
+/* Page container hover effects - optimized for smooth scrolling */
 .pageContainer {
   transition: transform 0.2s ease-in-out;
+  /* Enable hardware acceleration for smoother scrolling */
+  will-change: transform;
+  transform: translateZ(0);
+  backface-visibility: hidden;
 }
 
 .pageContainer:hover {
-  transform: scale(1.02);
+  transform: scale(1.02) translateZ(0);
 }
 
 .pageContainer:hover .pageNumber {

frontend/src/components/pageEditor/PageEditorControls.tsx

@@ -56,7 +56,7 @@ const PageEditorControls = ({
   return (
     <div
       style={{
-        position: 'fixed',
+        position: 'absolute',
         left: '50%',
         bottom: '20px',
         transform: 'translateX(-50%)',

frontend/src/components/pageEditor/PageThumbnail.tsx

@@ -1,5 +1,5 @@
-import React, { useCallback } from 'react';
-import { Text, Checkbox, Tooltip, ActionIcon } from '@mantine/core';
+import React, { useCallback, useState, useEffect, useRef } from 'react';
+import { Text, Checkbox, Tooltip, ActionIcon, Loader } from '@mantine/core';
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
 import ArrowForwardIcon from '@mui/icons-material/ArrowForward';
 import RotateLeftIcon from '@mui/icons-material/RotateLeft';
@@ -7,42 +7,55 @@ import RotateRightIcon from '@mui/icons-material/RotateRight';
 import DeleteIcon from '@mui/icons-material/Delete';
 import ContentCutIcon from '@mui/icons-material/ContentCut';
 import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
-import { PDFPage } from '../../../types/pageEditor';
+import { PDFPage, PDFDocument } from '../../../types/pageEditor';
+import { RotatePagesCommand, DeletePagesCommand, ToggleSplitCommand } from '../../../commands/pageCommands';
+import { Command } from '../../../hooks/useUndoRedo';
 import styles from './PageEditor.module.css';
+import { getDocument, GlobalWorkerOptions } from 'pdfjs-dist';
+
+// Ensure PDF.js worker is available
+if (!GlobalWorkerOptions.workerSrc) {
+  GlobalWorkerOptions.workerSrc = '/pdf.worker.js';
+  console.log('📸 PageThumbnail: Set PDF.js worker source to /pdf.worker.js');
+} else {
+  console.log('📸 PageThumbnail: PDF.js worker source already set to', GlobalWorkerOptions.workerSrc);
+}
 
 interface PageThumbnailProps {
   page: PDFPage;
   index: number;
   totalPages: number;
-  selectedPages: string[];
+  originalFile?: File; // For lazy thumbnail generation
+  selectedPages: number[];
   selectionMode: boolean;
-  draggedPage: string | null;
-  dropTarget: string | null;
-  movingPage: string | null;
+  draggedPage: number | null;
+  dropTarget: number | null;
+  movingPage: number | null;
   isAnimating: boolean;
   pageRefs: React.MutableRefObject<Map<string, HTMLDivElement>>;
-  onDragStart: (pageId: string) => void;
+  onDragStart: (pageNumber: number) => void;
   onDragEnd: () => void;
   onDragOver: (e: React.DragEvent) => void;
-  onDragEnter: (pageId: string) => void;
+  onDragEnter: (pageNumber: number) => void;
   onDragLeave: () => void;
-  onDrop: (e: React.DragEvent, pageId: string) => void;
-  onTogglePage: (pageId: string) => void;
-  onAnimateReorder: (pageId: string, targetIndex: number) => void;
-  onExecuteCommand: (command: any) => void;
+  onDrop: (e: React.DragEvent, pageNumber: number) => void;
+  onTogglePage: (pageNumber: number) => void;
+  onAnimateReorder: (pageNumber: number, targetIndex: number) => void;
+  onExecuteCommand: (command: Command) => void;
   onSetStatus: (status: string) => void;
-  onSetMovingPage: (pageId: string | null) => void;
-  RotatePagesCommand: any;
-  DeletePagesCommand: any;
-  ToggleSplitCommand: any;
-  pdfDocument: any;
-  setPdfDocument: any;
+  onSetMovingPage: (pageNumber: number | null) => void;
+  RotatePagesCommand: typeof RotatePagesCommand;
+  DeletePagesCommand: typeof DeletePagesCommand;
+  ToggleSplitCommand: typeof ToggleSplitCommand;
+  pdfDocument: PDFDocument;
+  setPdfDocument: (doc: PDFDocument) => void;
 }
 
-const PageThumbnail = ({
+const PageThumbnail = React.memo(({
   page,
   index,
   totalPages,
+  originalFile,
   selectedPages,
   selectionMode,
   draggedPage,
@@ -67,6 +80,44 @@ const PageThumbnail = ({
   pdfDocument,
   setPdfDocument,
 }: PageThumbnailProps) => {
+  const [thumbnailUrl, setThumbnailUrl] = useState<string | null>(page.thumbnail);
+  const [isLoadingThumbnail, setIsLoadingThumbnail] = useState(false);
+  
+  // Update thumbnail URL when page prop changes
+  useEffect(() => {
+    if (page.thumbnail && page.thumbnail !== thumbnailUrl) {
+      console.log(`📸 PageThumbnail: Updating thumbnail URL for page ${page.pageNumber}`, page.thumbnail.substring(0, 50) + '...');
+      setThumbnailUrl(page.thumbnail);
+    }
+  }, [page.thumbnail, page.pageNumber, page.id, thumbnailUrl]);
+
+  // Listen for ready thumbnails from Web Workers (only if no existing thumbnail)
+  useEffect(() => {
+    if (thumbnailUrl) {
+      console.log(`📸 PageThumbnail: Page ${page.pageNumber} already has thumbnail, skipping worker listener`);
+      return; // Skip if we already have a thumbnail
+    }
+    
+    console.log(`📸 PageThumbnail: Setting up worker listener for page ${page.pageNumber} (${page.id})`);
+    
+    const handleThumbnailReady = (event: CustomEvent) => {
+      const { pageNumber, thumbnail, pageId } = event.detail;
+      console.log(`📸 PageThumbnail: Received worker thumbnail for page ${pageNumber}, looking for page ${page.pageNumber} (${page.id})`);
+      
+      if (pageNumber === page.pageNumber && pageId === page.id) {
+        console.log(`✓ PageThumbnail: Thumbnail matched for page ${page.pageNumber}, setting URL`);
+        setThumbnailUrl(thumbnail);
+      }
+    };
+
+    window.addEventListener('thumbnailReady', handleThumbnailReady as EventListener);
+    return () => {
+      console.log(`📸 PageThumbnail: Cleaning up worker listener for page ${page.pageNumber}`);
+      window.removeEventListener('thumbnailReady', handleThumbnailReady as EventListener);
+    };
+  }, [page.pageNumber, page.id, thumbnailUrl]);
+
+
   // Register this component with pageRefs for animations
   const pageElementRef = useCallback((element: HTMLDivElement | null) => {
     if (element) {
@@ -79,7 +130,7 @@ const PageThumbnail = ({
   return (
     <div
       ref={pageElementRef}
-      data-page-id={page.id}
+      data-page-number={page.pageNumber}
       className={`
         ${styles.pageContainer}
         !rounded-lg
@@ -96,12 +147,12 @@ const PageThumbnail = ({
         ${selectionMode
           ? 'bg-white hover:bg-gray-50'
           : 'bg-white hover:bg-gray-50'}
-        ${draggedPage === page.id ? 'opacity-50 scale-95' : ''}
-        ${movingPage === page.id ? 'page-moving' : ''}
+        ${draggedPage === page.pageNumber ? 'opacity-50 scale-95' : ''}
+        ${movingPage === page.pageNumber ? 'page-moving' : ''}
       `}
       style={{
         transform: (() => {
-          if (!isAnimating && draggedPage && page.id !== draggedPage && dropTarget === page.id) {
+          if (!isAnimating && draggedPage && page.pageNumber !== draggedPage && dropTarget === page.pageNumber) {
             return 'translateX(20px)';
           }
           return 'translateX(0)';
@@ -109,12 +160,12 @@ const PageThumbnail = ({
         transition: isAnimating ? 'none' : 'transform 0.2s ease-in-out'
       }}
       draggable
-      onDragStart={() => onDragStart(page.id)}
+      onDragStart={() => onDragStart(page.pageNumber)}
       onDragEnd={onDragEnd}
       onDragOver={onDragOver}
-      onDragEnter={() => onDragEnter(page.id)}
+      onDragEnter={() => onDragEnter(page.pageNumber)}
       onDragLeave={onDragLeave}
-      onDrop={(e) => onDrop(e, page.id)}
+      onDrop={(e) => onDrop(e, page.pageNumber)}
     >
       {selectionMode && (
         <div
@@ -123,26 +174,31 @@ const PageThumbnail = ({
             position: 'absolute',
             top: 8,
             right: 8,
-            zIndex: 4,
-            backgroundColor: 'white',
+            zIndex: 10,
+            backgroundColor: 'rgba(255, 255, 255, 0.95)',
+            border: '1px solid #ccc',
             borderRadius: '4px',
-            padding: '2px',
+            padding: '4px',
             boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
-            pointerEvents: 'auto'
+            pointerEvents: 'auto',
+            cursor: 'pointer'
           }}
           onMouseDown={(e) => e.stopPropagation()}
           onDragStart={(e) => {
             e.preventDefault();
             e.stopPropagation();
           }}
+          onClick={(e) => {
+            console.log('📸 Checkbox clicked for page', page.pageNumber);
+            e.stopPropagation();
+            onTogglePage(page.pageNumber);
+          }}
         >
           <Checkbox
-            checked={selectedPages.includes(page.id)}
-            onChange={(event) => {
-              event.stopPropagation();
-              onTogglePage(page.id);
+            checked={Array.isArray(selectedPages) ? selectedPages.includes(page.pageNumber) : false}
+            onChange={() => {
+              // onChange is handled by the parent div click
             }}
-            onClick={(e) => e.stopPropagation()}
             size="sm"
           />
         </div>
@@ -162,18 +218,30 @@ const PageThumbnail = ({
             justifyContent: 'center'
           }}
         >
-          <img
-            src={page.thumbnail}
-            alt={`Page ${page.pageNumber}`}
-            style={{
-              maxWidth: '100%',
-              maxHeight: '100%',
-              objectFit: 'contain',
-              borderRadius: 2,
-              transform: `rotate(${page.rotation}deg)`,
-              transition: 'transform 0.3s ease-in-out'
-            }}
-          />
+          {thumbnailUrl ? (
+            <img
+              src={thumbnailUrl}
+              alt={`Page ${page.pageNumber}`}
+              style={{
+                width: '100%',
+                height: '100%',
+                objectFit: 'contain',
+                borderRadius: 2,
+                transform: `rotate(${page.rotation}deg)`,
+                transition: 'transform 0.3s ease-in-out'
+              }}
+            />
+          ) : isLoadingThumbnail ? (
+            <div style={{ textAlign: 'center' }}>
+              <Loader size="sm" />
+              <Text size="xs" c="dimmed" mt={4}>Loading...</Text>
+            </div>
+          ) : (
+            <div style={{ textAlign: 'center' }}>
+              <Text size="lg" c="dimmed">📄</Text>
+              <Text size="xs" c="dimmed" mt={4}>Page {page.pageNumber}</Text>
+            </div>
+          )}
         </div>
 
         <Text
@@ -224,8 +292,8 @@ const PageThumbnail = ({
               onClick={(e) => {
                 e.stopPropagation();
                 if (index > 0 && !movingPage && !isAnimating) {
-                  onSetMovingPage(page.id);
-                  onAnimateReorder(page.id, index - 1);
+                  onSetMovingPage(page.pageNumber);
+                  onAnimateReorder(page.pageNumber, index - 1);
                   setTimeout(() => onSetMovingPage(null), 500);
                   onSetStatus(`Moved page ${page.pageNumber} left`);
                 }
@@ -244,8 +312,8 @@ const PageThumbnail = ({
               onClick={(e) => {
                 e.stopPropagation();
                 if (index < totalPages - 1 && !movingPage && !isAnimating) {
-                  onSetMovingPage(page.id);
-                  onAnimateReorder(page.id, index + 1);
+                  onSetMovingPage(page.pageNumber);
+                  onAnimateReorder(page.pageNumber, index + 1);
                   setTimeout(() => onSetMovingPage(null), 500);
                   onSetStatus(`Moved page ${page.pageNumber} right`);
                 }
@@ -353,6 +421,20 @@ const PageThumbnail = ({
       </div>
     </div>
   );
-};
+}, (prevProps, nextProps) => {
+  // Only re-render if essential props change
+  return (
+    prevProps.page.id === nextProps.page.id &&
+    prevProps.page.pageNumber === nextProps.page.pageNumber &&
+    prevProps.page.rotation === nextProps.page.rotation &&
+    prevProps.page.thumbnail === nextProps.page.thumbnail &&
+    prevProps.selectedPages === nextProps.selectedPages && // Compare array reference - will re-render when selection changes
+    prevProps.selectionMode === nextProps.selectionMode &&
+    prevProps.draggedPage === nextProps.draggedPage &&
+    prevProps.dropTarget === nextProps.dropTarget &&
+    prevProps.movingPage === nextProps.movingPage &&
+    prevProps.isAnimating === nextProps.isAnimating
+  );
+});
 
 export default PageThumbnail;

frontend/src/components/shared/FileGrid.tsx

@@ -0,0 +1,168 @@
+import React, { useState } from "react";
+import { Box, Flex, Group, Text, Button, TextInput, Select, Badge } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import SearchIcon from "@mui/icons-material/Search";
+import SortIcon from "@mui/icons-material/Sort";
+import FileCard from "../fileManagement/FileCard";
+import { FileWithUrl } from "../../types/file";
+
+interface FileGridProps {
+  files: FileWithUrl[];
+  onRemove?: (index: number) => void;
+  onDoubleClick?: (file: FileWithUrl) => void;
+  onView?: (file: FileWithUrl) => void;
+  onEdit?: (file: FileWithUrl) => void;
+  onSelect?: (fileId: string) => void;
+  selectedFiles?: string[];
+  showSearch?: boolean;
+  showSort?: boolean;
+  maxDisplay?: number; // If set, shows only this many files with "Show All" option
+  onShowAll?: () => void;
+  showingAll?: boolean;
+  onDeleteAll?: () => void;
+}
+
+type SortOption = 'date' | 'name' | 'size';
+
+const FileGrid = ({
+  files,
+  onRemove,
+  onDoubleClick,
+  onView,
+  onEdit,
+  onSelect,
+  selectedFiles = [],
+  showSearch = false,
+  showSort = false,
+  maxDisplay,
+  onShowAll,
+  showingAll = false,
+  onDeleteAll
+}: FileGridProps) => {
+  const { t } = useTranslation();
+  const [searchTerm, setSearchTerm] = useState("");
+  const [sortBy, setSortBy] = useState<SortOption>('date');
+
+  // Filter files based on search term
+  const filteredFiles = files.filter(file =>
+    file.name.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  // Sort files
+  const sortedFiles = [...filteredFiles].sort((a, b) => {
+    switch (sortBy) {
+      case 'date':
+        return (b.lastModified || 0) - (a.lastModified || 0);
+      case 'name':
+        return a.name.localeCompare(b.name);
+      case 'size':
+        return (b.size || 0) - (a.size || 0);
+      default:
+        return 0;
+    }
+  });
+
+  // Apply max display limit if specified
+  const displayFiles = maxDisplay && !showingAll
+    ? sortedFiles.slice(0, maxDisplay)
+    : sortedFiles;
+
+  const hasMoreFiles = maxDisplay && !showingAll && sortedFiles.length > maxDisplay;
+
+  return (
+    <Box >
+      {/* Search and Sort Controls */}
+      {(showSearch || showSort || onDeleteAll) && (
+        <Group mb="md" justify="space-between" wrap="wrap" gap="sm">
+          <Group gap="sm">
+            {showSearch && (
+              <TextInput
+                placeholder={t("fileManager.searchFiles", "Search files...")}
+                leftSection={<SearchIcon size={16} />}
+                value={searchTerm}
+                onChange={(e) => setSearchTerm(e.currentTarget.value)}
+                style={{ flexGrow: 1, maxWidth: 300, minWidth: 200 }}
+              />
+            )}
+
+            {showSort && (
+              <Select
+                data={[
+                  { value: 'date', label: t("fileManager.sortByDate", "Sort by Date") },
+                  { value: 'name', label: t("fileManager.sortByName", "Sort by Name") },
+                  { value: 'size', label: t("fileManager.sortBySize", "Sort by Size") }
+                ]}
+                value={sortBy}
+                onChange={(value) => setSortBy(value as SortOption)}
+                leftSection={<SortIcon size={16} />}
+                style={{ minWidth: 150 }}
+              />
+            )}
+          </Group>
+
+          {onDeleteAll && (
+            <Button
+              color="red"
+              size="sm"
+              onClick={onDeleteAll}
+            >
+              {t("fileManager.deleteAll", "Delete All")}
+            </Button>
+          )}
+        </Group>
+      )}
+
+      {/* File Grid */}
+      <Flex
+        direction="row"
+        wrap="wrap"
+        gap="md"
+        h="30rem" 
+        style={{ overflowY: "auto", width: "100%" }}
+      >
+        {displayFiles.map((file, idx) => {
+          const fileId = file.id || file.name;
+          const originalIdx = files.findIndex(f => (f.id || f.name) === fileId);
+          return (
+            <FileCard
+              key={fileId + idx}
+              file={file}
+              onRemove={onRemove ? () => onRemove(originalIdx) : undefined}
+              onDoubleClick={onDoubleClick ? () => onDoubleClick(file) : undefined}
+              onView={onView ? () => onView(file) : undefined}
+              onEdit={onEdit ? () => onEdit(file) : undefined}
+              isSelected={selectedFiles.includes(fileId)}
+              onSelect={onSelect ? () => onSelect(fileId) : undefined}
+            />
+          );
+        })}
+      </Flex>
+
+      {/* Show All Button */}
+      {hasMoreFiles && onShowAll && (
+        <Group justify="center" mt="md">
+          <Button
+            variant="light"
+            onClick={onShowAll}
+          >
+            {t("fileManager.showAll", "Show All")} ({sortedFiles.length} files)
+          </Button>
+        </Group>
+      )}
+
+      {/* Empty State */}
+      {displayFiles.length === 0 && (
+        <Box style={{ textAlign: 'center', padding: '2rem' }}>
+          <Text c="dimmed">
+            {searchTerm
+              ? t("fileManager.noFilesFound", "No files found matching your search")
+              : t("fileManager.noFiles", "No files available")
+            }
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+export default FileGrid;

frontend/src/components/shared/FileUploadSelector.tsx

@@ -1,9 +1,13 @@
-import React, { useState, useCallback, useRef } from 'react';
-import { Stack, Button, Text, Center } from '@mantine/core';
+import React, { useState, useCallback, useRef, useEffect } from 'react';
+import { Stack, Button, Text, Center, Box, Divider } from '@mantine/core';
 import { Dropzone } from '@mantine/dropzone';
 import UploadFileIcon from '@mui/icons-material/UploadFile';
 import { useTranslation } from 'react-i18next';
-import FilePickerModal from './FilePickerModal';
+import { fileStorage } from '../../services/fileStorage';
+import { FileWithUrl } from '../../types/file';
+import FileGrid from './FileGrid';
+import MultiSelectControls from './MultiSelectControls';
+import { useFileManager } from '../../hooks/useFileManager';
 
 interface FileUploadSelectorProps {
   // Appearance
@@ -20,6 +24,10 @@ interface FileUploadSelectorProps {
   // Loading state
   loading?: boolean;
   disabled?: boolean;
+
+  // Recent files
+  showRecentFiles?: boolean;
+  maxRecentFiles?: number;
 }
 
 const FileUploadSelector = ({
@@ -29,50 +37,94 @@ const FileUploadSelector = ({
   sharedFiles = [],
   onFileSelect,
   onFilesSelect,
-  accept = ["application/pdf"],
+  accept = ["application/pdf", "application/zip", "application/x-zip-compressed"],
   loading = false,
   disabled = false,
+  showRecentFiles = true,
+  maxRecentFiles = 8,
 }: FileUploadSelectorProps) => {
   const { t } = useTranslation();
-  const [showFilePickerModal, setShowFilePickerModal] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
-  const handleFileUpload = useCallback((uploadedFiles: File[]) => {
+  const [recentFiles, setRecentFiles] = useState<FileWithUrl[]>([]);
+  const [selectedFiles, setSelectedFiles] = useState<string[]>([]);
+
+  const { loadRecentFiles, handleRemoveFile, storeFile, convertToFile, createFileSelectionHandlers } = useFileManager();
+
+  const refreshRecentFiles = useCallback(async () => {
+    const files = await loadRecentFiles();
+    setRecentFiles(files);
+  }, [loadRecentFiles]);
+
+  const handleNewFileUpload = useCallback(async (uploadedFiles: File[]) => {
     if (uploadedFiles.length === 0) return;
 
+    if (showRecentFiles) {
+      try {
+        for (const file of uploadedFiles) {
+          await storeFile(file);
+        }
+        refreshRecentFiles();
+      } catch (error) {
+        console.error('Failed to save files to recent:', error);
+      }
+    }
+
     if (onFilesSelect) {
       onFilesSelect(uploadedFiles);
     } else if (onFileSelect) {
       onFileSelect(uploadedFiles[0]);
     }
-  }, [onFileSelect, onFilesSelect]);
+  }, [onFileSelect, onFilesSelect, showRecentFiles, storeFile, refreshRecentFiles]);
 
   const handleFileInputChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
     const files = event.target.files;
     if (files && files.length > 0) {
       const fileArray = Array.from(files);
       console.log('File input change:', fileArray.length, 'files');
-      handleFileUpload(fileArray);
+      handleNewFileUpload(fileArray);
     }
-    // Reset input
     if (fileInputRef.current) {
       fileInputRef.current.value = '';
     }
-  }, [handleFileUpload]);
+  }, [handleNewFileUpload]);
 
   const openFileDialog = useCallback(() => {
     fileInputRef.current?.click();
   }, []);
 
-  const handleStorageSelection = useCallback((selectedFiles: File[]) => {
-    if (selectedFiles.length === 0) return;
-
-    if (onFilesSelect) {
-      onFilesSelect(selectedFiles);
-    } else if (onFileSelect) {
-      onFileSelect(selectedFiles[0]);
+  const handleRecentFileSelection = useCallback(async (file: FileWithUrl) => {
+    try {
+      const fileObj = await convertToFile(file);
+      if (onFilesSelect) {
+        onFilesSelect([fileObj]);
+      } else if (onFileSelect) {
+        onFileSelect(fileObj);
+      }
+    } catch (error) {
+      console.error('Failed to load file from recent:', error);
     }
-  }, [onFileSelect, onFilesSelect]);
+  }, [onFileSelect, onFilesSelect, convertToFile]);
+
+  const selectionHandlers = createFileSelectionHandlers(selectedFiles, setSelectedFiles);
+
+  const handleSelectedRecentFiles = useCallback(async () => {
+    if (onFilesSelect) {
+      await selectionHandlers.selectMultipleFiles(recentFiles, onFilesSelect);
+    }
+  }, [recentFiles, onFilesSelect, selectionHandlers]);
+
+  const handleRemoveFileByIndex = useCallback(async (index: number) => {
+    await handleRemoveFile(index, recentFiles, setRecentFiles);
+    const file = recentFiles[index];
+    setSelectedFiles(prev => prev.filter(id => id !== (file.id || file.name)));
+  }, [handleRemoveFile, recentFiles]);
+
+  useEffect(() => {
+    if (showRecentFiles) {
+      refreshRecentFiles();
+    }
+  }, [showRecentFiles, refreshRecentFiles]);
 
   // Get default title and subtitle from translations if not provided
   const displayTitle = title || t("fileUpload.selectFiles", "Select files");
@@ -80,7 +132,7 @@ const FileUploadSelector = ({
 
   return (
     <>
-      <Stack align="center" gap="xl">
+      <Stack align="center" gap="sm">
         {/* Title and description */}
         <Stack align="center" gap="md">
           <UploadFileIcon style={{ fontSize: 64 }} />
@@ -94,27 +146,14 @@ const FileUploadSelector = ({
 
         {/* Action buttons */}
         <Stack align="center" gap="md" w="100%">
-          <Button
-            variant="filled"
-            size="lg"
-            onClick={() => setShowFilePickerModal(true)}
-            disabled={disabled || sharedFiles.length === 0}
-            loading={loading}
-          >
-            {loading ? "Loading..." : `Load from Storage (${sharedFiles.length} files available)`}
-          </Button>
-
-          <Text size="md" c="dimmed">
-            {t("fileUpload.or", "or")}
-          </Text>
 
           {showDropzone ? (
             <Dropzone
-              onDrop={handleFileUpload}
+              onDrop={handleNewFileUpload}
               accept={accept}
               multiple={true}
               disabled={disabled || loading}
-              style={{ width: '100%', minHeight: 120 }}
+              style={{ width: '100%', height: "5rem" }}
               activateOnClick={true}
             >
               <Center>
@@ -123,7 +162,9 @@ const FileUploadSelector = ({
                     {t("fileUpload.dropFilesHere", "Drop files here or click to upload")}
                   </Text>
                   <Text size="sm" c="dimmed">
-                    {accept.includes('application/pdf')
+                    {accept.includes('application/pdf') && accept.includes('application/zip')
+                      ? t("fileUpload.pdfAndZipFiles", "PDF and ZIP files")
+                      : accept.includes('application/pdf')
                       ? t("fileUpload.pdfFilesOnly", "PDF files only")
                       : t("fileUpload.supportedFileTypes", "Supported file types")
                     }
@@ -142,7 +183,7 @@ const FileUploadSelector = ({
               >
                 {t("fileUpload.uploadFiles", "Upload Files")}
               </Button>
-              
+
               {/* Manual file input as backup */}
               <input
                 ref={fileInputRef}
@@ -155,15 +196,46 @@ const FileUploadSelector = ({
             </Stack>
           )}
         </Stack>
-      </Stack>
 
-      {/* File Picker Modal */}
-      <FilePickerModal
-        opened={showFilePickerModal}
-        onClose={() => setShowFilePickerModal(false)}
-        storedFiles={sharedFiles}
-        onSelectFiles={handleStorageSelection}
-      />
+      {/* Recent Files Section */}
+      {showRecentFiles && recentFiles.length > 0 && (
+        <Box w="100%" >
+          <Divider my="md" />
+          <Text size="lg" fw={500} mb="md">
+            {t("fileUpload.recentFiles", "Recent Files")}
+          </Text>
+          <MultiSelectControls
+            selectedCount={selectedFiles.length}
+            onClearSelection={selectionHandlers.clearSelection}
+            onAddToUpload={handleSelectedRecentFiles}
+            onDeleteAll={async () => {
+              await Promise.all(recentFiles.map(async (file) => {
+                await fileStorage.deleteFile(file.id || file.name);
+              }));
+              setRecentFiles([]);
+              setSelectedFiles([]);
+            }}
+          />
+
+          <FileGrid
+            files={recentFiles}
+            onDoubleClick={handleRecentFileSelection}
+            onSelect={selectionHandlers.toggleSelection}
+            onRemove={handleRemoveFileByIndex}
+            selectedFiles={selectedFiles}
+            showSearch={true}
+            showSort={true}
+            onDeleteAll={async () => {
+              await Promise.all(recentFiles.map(async (file) => {
+                await fileStorage.deleteFile(file.id || file.name);
+              }));
+              setRecentFiles([]);
+              setSelectedFiles([]);
+            }}
+          />
+        </Box>
+      )}
+            </Stack>
     </>
   );
 };

frontend/src/components/shared/MultiSelectControls.tsx

@@ -0,0 +1,88 @@
+import React from "react";
+import { Box, Group, Text, Button } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+
+interface MultiSelectControlsProps {
+  selectedCount: number;
+  onClearSelection: () => void;
+  onOpenInFileEditor?: () => void;
+  onOpenInPageEditor?: () => void;
+  onAddToUpload?: () => void;
+  onDeleteAll?: () => void;
+}
+
+const MultiSelectControls = ({
+  selectedCount,
+  onClearSelection,
+  onOpenInFileEditor,
+  onOpenInPageEditor,
+  onAddToUpload,
+  onDeleteAll
+}: MultiSelectControlsProps) => {
+  const { t } = useTranslation();
+
+  if (selectedCount === 0) return null;
+
+  return (
+    <Box mb="md" p="md" style={{ backgroundColor: 'var(--mantine-color-blue-0)', borderRadius: 8 }}>
+      <Group justify="space-between">
+        <Text size="sm">
+          {selectedCount} {t("fileManager.filesSelected", "files selected")}
+        </Text>
+        <Group>
+          <Button
+            size="xs"
+            variant="light"
+            onClick={onClearSelection}
+          >
+            {t("fileManager.clearSelection", "Clear Selection")}
+          </Button>
+          
+          {onAddToUpload && (
+            <Button
+              size="xs"
+              color="green"
+              onClick={onAddToUpload}
+            >
+              {t("fileManager.addToUpload", "Add to Upload")}
+            </Button>
+          )}
+          
+          {onOpenInFileEditor && (
+            <Button
+              size="xs"
+              color="orange"
+              onClick={onOpenInFileEditor}
+              disabled={selectedCount === 0}
+            >
+              {t("fileManager.openInFileEditor", "Open in File Editor")}
+            </Button>
+          )}
+          
+          {onOpenInPageEditor && (
+            <Button
+              size="xs"
+              color="blue"
+              onClick={onOpenInPageEditor}
+              disabled={selectedCount === 0}
+            >
+              {t("fileManager.openInPageEditor", "Open in Page Editor")}
+            </Button>
+          )}
+          
+          {onDeleteAll && (
+            <Button
+              size="xs"
+              color="red"
+              onClick={onDeleteAll}
+            >
+              {t("fileManager.deleteAll", "Delete All")}
+            </Button>
+          )}
+        </Group>
+      </Group>
+    </Box>
+  );
+};
+
+export default MultiSelectControls;

frontend/src/components/shared/NavigationWarningModal.tsx

@@ -0,0 +1,106 @@
+import React from 'react';
+import { Modal, Text, Button, Group, Stack } from '@mantine/core';
+import { useFileContext } from '../../contexts/FileContext';
+
+interface NavigationWarningModalProps {
+  onApplyAndContinue?: () => Promise<void>;
+  onExportAndContinue?: () => Promise<void>;
+}
+
+const NavigationWarningModal = ({
+  onApplyAndContinue,
+  onExportAndContinue
+}: NavigationWarningModalProps) => {
+  const { 
+    showNavigationWarning, 
+    hasUnsavedChanges,
+    confirmNavigation, 
+    cancelNavigation,
+    setHasUnsavedChanges
+  } = useFileContext();
+
+  const handleKeepWorking = () => {
+    cancelNavigation();
+  };
+
+  const handleDiscardChanges = () => {
+    setHasUnsavedChanges(false);
+    confirmNavigation();
+  };
+
+  const handleApplyAndContinue = async () => {
+    if (onApplyAndContinue) {
+      await onApplyAndContinue();
+    }
+    setHasUnsavedChanges(false);
+    confirmNavigation();
+  };
+
+  const handleExportAndContinue = async () => {
+    if (onExportAndContinue) {
+      await onExportAndContinue();
+    }
+    setHasUnsavedChanges(false);
+    confirmNavigation();
+  };
+
+  if (!hasUnsavedChanges) {
+    return null;
+  }
+
+  return (
+    <Modal
+      opened={showNavigationWarning}
+      onClose={handleKeepWorking}
+      title="Unsaved Changes"
+      centered
+      closeOnClickOutside={false}
+      closeOnEscape={false}
+    >
+      <Stack gap="md">
+        <Text>
+          You have unsaved changes to your PDF. What would you like to do?
+        </Text>
+        
+        <Group justify="flex-end" gap="sm">
+          <Button
+            variant="light"
+            color="gray"
+            onClick={handleKeepWorking}
+          >
+            Keep Working
+          </Button>
+          
+          <Button
+            variant="light"
+            color="red"
+            onClick={handleDiscardChanges}
+          >
+            Discard Changes
+          </Button>
+          
+          {onApplyAndContinue && (
+            <Button
+              variant="light"
+              color="blue"
+              onClick={handleApplyAndContinue}
+            >
+              Apply & Continue
+            </Button>
+          )}
+          
+          {onExportAndContinue && (
+            <Button
+              color="green"
+              onClick={handleExportAndContinue}
+            >
+              Export & Continue
+            </Button>
+          )}
+        </Group>
+      </Stack>
+    </Modal>
+  );
+};
+
+export default NavigationWarningModal;

frontend/src/components/shared/SkeletonLoader.tsx

@@ -0,0 +1,104 @@
+import React from 'react';
+import { Box, Group, Stack } from '@mantine/core';
+
+interface SkeletonLoaderProps {
+  type: 'pageGrid' | 'fileGrid' | 'controls' | 'viewer';
+  count?: number;
+  animated?: boolean;
+}
+
+const SkeletonLoader: React.FC<SkeletonLoaderProps> = ({ 
+  type, 
+  count = 8, 
+  animated = true 
+}) => {
+  const animationStyle = animated ? { animation: 'pulse 2s infinite' } : {};
+
+  const renderPageGridSkeleton = () => (
+    <div style={{ 
+      display: 'grid', 
+      gridTemplateColumns: 'repeat(auto-fill, minmax(180px, 1fr))', 
+      gap: '1rem' 
+    }}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Box
+          key={i}
+          w="100%"
+          h={240}
+          bg="gray.1"
+          style={{ 
+            borderRadius: '8px',
+            ...animationStyle,
+            animationDelay: animated ? `${i * 0.1}s` : undefined
+          }}
+        />
+      ))}
+    </div>
+  );
+
+  const renderFileGridSkeleton = () => (
+    <div style={{ 
+      display: 'grid', 
+      gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))', 
+      gap: '1rem' 
+    }}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Box
+          key={i}
+          w="100%"
+          h={280}
+          bg="gray.1"
+          style={{ 
+            borderRadius: '8px',
+            ...animationStyle,
+            animationDelay: animated ? `${i * 0.1}s` : undefined
+          }}
+        />
+      ))}
+    </div>
+  );
+
+  const renderControlsSkeleton = () => (
+    <Group mb="md">
+      <Box w={150} h={36} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+      <Box w={120} h={36} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+      <Box w={100} h={36} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+    </Group>
+  );
+
+  const renderViewerSkeleton = () => (
+    <Stack gap="md" h="100%">
+      {/* Toolbar skeleton */}
+      <Group>
+        <Box w={40} h={40} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+        <Box w={40} h={40} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+        <Box w={80} h={40} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+        <Box w={40} h={40} bg="gray.1" style={{ borderRadius: 4, ...animationStyle }} />
+      </Group>
+      {/* Main content skeleton */}
+      <Box 
+        flex={1} 
+        bg="gray.1" 
+        style={{ 
+          borderRadius: '8px',
+          ...animationStyle 
+        }} 
+      />
+    </Stack>
+  );
+
+  switch (type) {
+    case 'pageGrid':
+      return renderPageGridSkeleton();
+    case 'fileGrid':
+      return renderFileGridSkeleton();
+    case 'controls':
+      return renderControlsSkeleton();
+    case 'viewer':
+      return renderViewerSkeleton();
+    default:
+      return null;
+  }
+};
+
+export default SkeletonLoader;