From 219afd0e1ddf363debc731aaef181977b1b26f39 Mon Sep 17 00:00:00 2001
From: gzz727 <grenguo@gmail.com>
Date: Mon, 21 Sep 2026 15:29:35 +0800
Subject: [PATCH 1/5] feat(scanner): document shadow removal, paper whitening
 enhancement, and live compare

---
 src/locales/de.json                     |  14 ++
 src/locales/en.json                     |  14 ++
 src/locales/es.json                     |  14 ++
 src/locales/fr.json                     |  14 ++
 src/locales/zh.json                     |  14 ++
 src/tools/ImageToPdfTool.vue            | 273 +++++++++++++++++++++++-
 src/utils/imageProcess.js               | 182 ++++++++++++++++
 src/utils/pipeline/nodes/img2pdfNode.js |   4 +-
 tests/documentEnhance.test.js           | 165 ++++++++++++++
 9 files changed, 682 insertions(+), 12 deletions(-)
 create mode 100644 tests/documentEnhance.test.js

diff --git a/src/locales/de.json b/src/locales/de.json
index d13e77b..67d7096 100644
--- a/src/locales/de.json
+++ b/src/locales/de.json
@@ -530,6 +530,20 @@
   "img2pdf_orient_auto": "Automatisch",
   "img2pdf_orient_portrait": "Hochformat",
   "img2pdf_orient_landscape": "Querformat",
+  "img2pdf_enhance_title": "Scanner-Verbesserung",
+  "img2pdf_enhance_desc": "Schatten glätten & Papier aufhellen",
+  "img2pdf_filter_label": "Filtermodus",
+  "img2pdf_filter_color": "Auto-Farbe",
+  "img2pdf_filter_bw": "Klares S/W",
+  "img2pdf_filter_grayscale": "Graustufen",
+  "img2pdf_shadow_label": "Schattenentfernung",
+  "img2pdf_shadow_low": "Leicht",
+  "img2pdf_shadow_medium": "Ausgewogen",
+  "img2pdf_shadow_high": "Stark",
+  "img2pdf_badge_enhanced": "Verbessert",
+  "img2pdf_hold_compare": "Gedrückt halten für Original",
+  "img2pdf_original": "Original",
+  "img2pdf_compare": "Vergleich",
   "pipeline_title": "Pipeline & Stapelverarbeitung",
   "pipeline_subtitle": "Verketten Sie Bereinigung, Komprimierung, Wasserzeichen, Stempeln und Zusammenführen. 100% lokal im Browserspeicher ohne Uploads.",
   "pro_desktop_btn": "Pro / Desktop-App",
diff --git a/src/locales/en.json b/src/locales/en.json
index 41809e1..11f558a 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -530,6 +530,20 @@
   "img2pdf_orient_auto": "Auto",
   "img2pdf_orient_portrait": "Portrait",
   "img2pdf_orient_landscape": "Landscape",
+  "img2pdf_enhance_title": "Scanner Enhancement",
+  "img2pdf_enhance_desc": "Flatten phone shadows & whiten paper",
+  "img2pdf_filter_label": "Enhance Filter",
+  "img2pdf_filter_color": "Auto Color",
+  "img2pdf_filter_bw": "Crisp B&W",
+  "img2pdf_filter_grayscale": "Grayscale",
+  "img2pdf_shadow_label": "Shadow Removal",
+  "img2pdf_shadow_low": "Subtle",
+  "img2pdf_shadow_medium": "Balanced",
+  "img2pdf_shadow_high": "Strong",
+  "img2pdf_badge_enhanced": "Enhanced",
+  "img2pdf_hold_compare": "Hold to see original",
+  "img2pdf_original": "Original",
+  "img2pdf_compare": "Hold Compare",
   "pipeline_title": "Automated Pipeline & Batch",
   "pipeline_subtitle": "Chain sanitization, compression, watermarking, stamping, and merging. Batch process multiple documents 100% locally in browser memory with zero uploads.",
   "pro_desktop_btn": "Upgrade Pro / Desktop",
diff --git a/src/locales/es.json b/src/locales/es.json
index 6b0b57d..8dd84b4 100644
--- a/src/locales/es.json
+++ b/src/locales/es.json
@@ -530,6 +530,20 @@
   "img2pdf_orient_auto": "Automático",
   "img2pdf_orient_portrait": "Vertical",
   "img2pdf_orient_landscape": "Horizontal",
+  "img2pdf_enhance_title": "Mejora de Escáner",
+  "img2pdf_enhance_desc": "Eliminar sombras y blanquear papel",
+  "img2pdf_filter_label": "Filtro de Mejora",
+  "img2pdf_filter_color": "Color Automático",
+  "img2pdf_filter_bw": "B/N Nítido",
+  "img2pdf_filter_grayscale": "Escala de Grises",
+  "img2pdf_shadow_label": "Eliminación de sombras",
+  "img2pdf_shadow_low": "Suave",
+  "img2pdf_shadow_medium": "Equilibrado",
+  "img2pdf_shadow_high": "Fuerte",
+  "img2pdf_badge_enhanced": "Mejorado",
+  "img2pdf_hold_compare": "Mantén presionado para original",
+  "img2pdf_original": "Original",
+  "img2pdf_compare": "Comparar",
   "pipeline_title": "Pipeline y Lotes",
   "pipeline_subtitle": "Encadene saneamiento, compresión, marcas de agua, sellado y combinación. Procesamiento por lotes 100% local sin subidas.",
   "pro_desktop_btn": "Pro / App de escritorio",
diff --git a/src/locales/fr.json b/src/locales/fr.json
index c2fe587..a6806f5 100644
--- a/src/locales/fr.json
+++ b/src/locales/fr.json
@@ -530,6 +530,20 @@
   "img2pdf_orient_auto": "Automatique",
   "img2pdf_orient_portrait": "Portrait",
   "img2pdf_orient_landscape": "Paysage",
+  "img2pdf_enhance_title": "Amélioration Scanner",
+  "img2pdf_enhance_desc": "Supprimer les ombres et blanchir le papier",
+  "img2pdf_filter_label": "Filtre d'amélioration",
+  "img2pdf_filter_color": "Couleur Auto",
+  "img2pdf_filter_bw": "N&B Net",
+  "img2pdf_filter_grayscale": "Niveaux de gris",
+  "img2pdf_shadow_label": "Suppression des ombres",
+  "img2pdf_shadow_low": "Léger",
+  "img2pdf_shadow_medium": "Équilibré",
+  "img2pdf_shadow_high": "Fort",
+  "img2pdf_badge_enhanced": "Amélioré",
+  "img2pdf_hold_compare": "Maintenir pour original",
+  "img2pdf_original": "Original",
+  "img2pdf_compare": "Comparer",
   "pipeline_title": "Pipeline & Traitement par lots",
   "pipeline_subtitle": "Enchaînez anonymisation, compression, filigrane, tampon et fusion. Traitement par lots 100% local en mémoire sans téléversement.",
   "pro_desktop_btn": "Pro / Application bureau",
diff --git a/src/locales/zh.json b/src/locales/zh.json
index 3c87529..56c906b 100644
--- a/src/locales/zh.json
+++ b/src/locales/zh.json
@@ -530,6 +530,20 @@
   "img2pdf_orient_auto": "自适应",
   "img2pdf_orient_portrait": "纵向",
   "img2pdf_orient_landscape": "横向",
+  "img2pdf_enhance_title": "文档扫描增强 (去阴影 / 增白)",
+  "img2pdf_enhance_desc": "抹平手机暗影，纸面纯白提亮",
+  "img2pdf_filter_label": "增强滤镜",
+  "img2pdf_filter_color": "智能彩色 (保留印章)",
+  "img2pdf_filter_bw": "高清黑白",
+  "img2pdf_filter_grayscale": "清晰灰度",
+  "img2pdf_shadow_label": "去阴影强度",
+  "img2pdf_shadow_low": "弱",
+  "img2pdf_shadow_medium": "均衡",
+  "img2pdf_shadow_high": "强力",
+  "img2pdf_badge_enhanced": "已增强",
+  "img2pdf_hold_compare": "按住查看原图",
+  "img2pdf_original": "原图",
+  "img2pdf_compare": "按住对比",
   "pipeline_title": "自动化流水线 & 批处理",
   "pipeline_subtitle": "一键串联脱敏、压缩、加水印、盖章与合并，对多份文档进行流水线批量处理。100% 浏览器本地运算，零上传，极速安全。",
   "pro_desktop_btn": "升级 Pro / 独立桌面版",
diff --git a/src/tools/ImageToPdfTool.vue b/src/tools/ImageToPdfTool.vue
index e5c021b..cbdd6f3 100644
--- a/src/tools/ImageToPdfTool.vue
+++ b/src/tools/ImageToPdfTool.vue
@@ -160,9 +160,15 @@
                 @drop="onDropReorder(idx)"
                 class="bg-white rounded-xl sm:rounded-2xl p-1.5 sm:p-2.5 border border-slate-200/80 shadow-2xs hover:border-violet-400 hover:shadow-md transition flex flex-col justify-between group relative select-none"
               >
-                <!-- Page Number Tag -->
-                <div class="absolute top-1.5 left-1.5 z-10 bg-slate-900/75 backdrop-blur-xs text-white text-[9px] sm:text-[10px] font-mono font-bold px-1.5 py-0.5 rounded-md">
-                  P{{ idx + 1 }}
+                <!-- Page Number Tag & Status Badge -->
+                <div class="absolute top-1.5 left-1.5 z-10 flex items-center space-x-1">
+                  <span class="bg-slate-900/75 backdrop-blur-xs text-white text-[9px] sm:text-[10px] font-mono font-bold px-1.5 py-0.5 rounded-md">
+                    P{{ idx + 1 }}
+                  </span>
+                  <span v-if="enhanceScanner" class="bg-violet-600/90 text-white text-[9px] font-bold px-1.5 py-0.5 rounded-md flex items-center space-x-0.5 shadow-2xs">
+                    <Sparkles class="w-2.5 h-2.5" />
+                    <span class="hidden sm:inline">{{ t('img2pdf_badge_enhanced', 'Enhanced') }}</span>
+                  </span>
                 </div>
 
                 <!-- Delete Button -->
@@ -174,13 +180,29 @@
                   <X class="w-3.5 h-3.5 sm:w-3 sm:h-3" />
                 </button>
 
-                <!-- Thumbnail -->
-                <div class="h-24 sm:h-32 rounded-lg sm:rounded-xl bg-slate-100 overflow-hidden flex items-center justify-center relative mb-1.5">
+                <!-- Thumbnail with Instant Compare Capability -->
+                <div class="h-24 sm:h-32 rounded-lg sm:rounded-xl bg-slate-100 overflow-hidden flex items-center justify-center relative mb-1.5 group/thumb">
                   <img 
-                    :src="img.previewUrl" 
+                    :src="(enhanceScanner && img.enhancedPreviewUrl && !img.showOriginal) ? img.enhancedPreviewUrl : img.previewUrl" 
                     :style="{ transform: `rotate(${img.rotation}deg)` }"
                     class="max-h-full max-w-full object-contain transition-transform duration-200 pointer-events-none"
                   >
+
+                  <!-- Hold to Compare Overlay (Desktop hover + Mobile touch) -->
+                  <button
+                    v-if="enhanceScanner && img.enhancedPreviewUrl"
+                    type="button"
+                    @mousedown.stop="img.showOriginal = true"
+                    @mouseup.stop="img.showOriginal = false"
+                    @mouseleave="img.showOriginal = false"
+                    @touchstart.stop="img.showOriginal = true"
+                    @touchend.stop="img.showOriginal = false"
+                    class="absolute bottom-1.5 right-1.5 bg-slate-900/85 hover:bg-slate-900 text-white text-[9px] font-bold px-1.5 py-0.5 rounded-md opacity-90 sm:opacity-0 sm:group-hover/thumb:opacity-100 transition cursor-pointer flex items-center space-x-1 shadow-xs select-none"
+                    :title="t('img2pdf_hold_compare', 'Hold to see original')"
+                  >
+                    <Eye class="w-2.5 h-2.5" />
+                    <span>{{ img.showOriginal ? t('img2pdf_original', 'Original') : t('img2pdf_compare', 'Compare') }}</span>
+                  </button>
                 </div>
 
                 <!-- Info & Actions -->
@@ -229,8 +251,88 @@
           </div>
 
           <!-- Right: Page & Layout Settings (4 cols, desktop wide screen only) -->
-          <div class="hidden lg:flex lg:col-span-4 bg-slate-50/80 rounded-2xl p-4 border border-slate-200/80 flex-col justify-between space-y-4">
+          <div class="hidden lg:flex lg:col-span-4 bg-slate-50/80 rounded-2xl p-4 border border-slate-200/80 flex-col justify-between space-y-4 overflow-y-auto max-h-[calc(100vh-280px)]">
             <div class="space-y-4">
+              <!-- Document Scanner & Shadow Removal Enhancement -->
+              <div class="p-3 rounded-2xl bg-gradient-to-br from-violet-50/80 to-indigo-50/50 border border-violet-200/80 shadow-2xs space-y-2.5">
+                <div class="flex items-center justify-between">
+                  <div class="flex items-center space-x-2">
+                    <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
+                      <Sparkles class="w-3.5 h-3.5" />
+                    </div>
+                    <div>
+                      <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
+                        <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
+                      </h4>
+                      <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
+                        {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
+                      </p>
+                    </div>
+                  </div>
+                  <!-- Switch button -->
+                  <button 
+                    type="button" 
+                    @click="enhanceScanner = !enhanceScanner"
+                    :class="[
+                      'w-10 h-5.5 rounded-full transition-colors relative cursor-pointer focus:outline-none shrink-0',
+                      enhanceScanner ? 'bg-violet-600' : 'bg-slate-300'
+                    ]"
+                  >
+                    <span 
+                      :class="[
+                        'w-4.5 h-4.5 bg-white rounded-full transition-transform transform shadow-sm absolute top-0.5 left-0.5',
+                        enhanceScanner ? 'translate-x-4.5' : 'translate-x-0'
+                      ]" 
+                    />
+                  </button>
+                </div>
+
+                <!-- Filter & Shadow Options (Shown when active) -->
+                <div v-if="enhanceScanner" class="pt-2 border-t border-violet-200/60 space-y-2.5">
+                  <!-- Mode presets -->
+                  <div>
+                    <label class="block text-[11px] font-bold text-slate-700 mb-1">
+                      {{ t('img2pdf_filter_label', 'Enhance Filter') }}
+                    </label>
+                    <div class="grid grid-cols-3 gap-1">
+                      <button 
+                        v-for="flt in filterOptions" 
+                        :key="flt.id"
+                        type="button"
+                        @click="enhanceFilter = flt.id"
+                        :class="[
+                          'py-1.5 px-1 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer',
+                          enhanceFilter === flt.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                        ]"
+                      >
+                        {{ flt.label }}
+                      </button>
+                    </div>
+                  </div>
+
+                  <!-- Shadow Suppression -->
+                  <div>
+                    <div class="flex items-center justify-between text-[11px] font-bold text-slate-700 mb-1">
+                      <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
+                    </div>
+                    <div class="grid grid-cols-3 gap-1">
+                      <button 
+                        v-for="sh in shadowOptions" 
+                        :key="sh.id"
+                        type="button"
+                        @click="shadowSuppression = sh.id"
+                        :class="[
+                          'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
+                          shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                        ]"
+                      >
+                        {{ sh.label }}
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+
               <!-- Page Size -->
               <div>
                 <label class="block text-xs font-bold text-slate-700 mb-2">
@@ -366,6 +468,86 @@
           </button>
         </div>
 
+        <!-- Document Scanner & Shadow Removal Enhancement -->
+        <div class="p-3 rounded-2xl bg-gradient-to-br from-violet-50/80 to-indigo-50/50 border border-violet-200/80 shadow-2xs space-y-2.5">
+          <div class="flex items-center justify-between">
+            <div class="flex items-center space-x-2">
+              <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
+                <Sparkles class="w-3.5 h-3.5" />
+              </div>
+              <div>
+                <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
+                  <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
+                </h4>
+                <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
+                  {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
+                </p>
+              </div>
+            </div>
+            <!-- Switch button -->
+            <button 
+              type="button" 
+              @click="enhanceScanner = !enhanceScanner"
+              :class="[
+                'w-10 h-5.5 rounded-full transition-colors relative cursor-pointer focus:outline-none shrink-0',
+                enhanceScanner ? 'bg-violet-600' : 'bg-slate-300'
+              ]"
+            >
+              <span 
+                :class="[
+                  'w-4.5 h-4.5 bg-white rounded-full transition-transform transform shadow-sm absolute top-0.5 left-0.5',
+                  enhanceScanner ? 'translate-x-4.5' : 'translate-x-0'
+                ]" 
+              />
+            </button>
+          </div>
+
+          <!-- Filter & Shadow Options (Shown when active) -->
+          <div v-if="enhanceScanner" class="pt-2 border-t border-violet-200/60 space-y-2.5">
+            <!-- Mode presets -->
+            <div>
+              <label class="block text-[11px] font-bold text-slate-700 mb-1">
+                {{ t('img2pdf_filter_label', 'Enhance Filter') }}
+              </label>
+              <div class="grid grid-cols-3 gap-1">
+                <button 
+                  v-for="flt in filterOptions" 
+                  :key="flt.id"
+                  type="button"
+                  @click="enhanceFilter = flt.id"
+                  :class="[
+                    'py-1.5 px-1 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer',
+                    enhanceFilter === flt.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                  ]"
+                >
+                  {{ flt.label }}
+                </button>
+              </div>
+            </div>
+
+            <!-- Shadow Suppression -->
+            <div>
+              <div class="flex items-center justify-between text-[11px] font-bold text-slate-700 mb-1">
+                <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
+              </div>
+              <div class="grid grid-cols-3 gap-1">
+                <button 
+                  v-for="sh in shadowOptions" 
+                  :key="sh.id"
+                  type="button"
+                  @click="shadowSuppression = sh.id"
+                  :class="[
+                    'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
+                    shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                  ]"
+                >
+                  {{ sh.label }}
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+
         <!-- Page Size -->
         <div>
           <label class="block text-xs font-bold text-slate-700 mb-1.5">
@@ -460,7 +642,9 @@ import {
   FileDown, 
   Loader2,
   SlidersHorizontal,
-  ArrowUpDown
+  ArrowUpDown,
+  Sparkles,
+  Eye
 } from 'lucide-vue-next';
 import { PDFDocument } from 'pdf-lib';
 import { t } from '../i18n';
@@ -468,6 +652,7 @@ import { triggerDownload } from '../utils/download';
 import { saveFile } from '../utils/vaultDb';
 import { userSettings } from '../utils/userSettings';
 import { logger } from '../utils/logger';
+import { applyDocumentEnhancement, generateEnhancedThumbnail } from '../utils/imageProcess';
 import ResultDeliveryView from '../components/ResultDeliveryView.vue';
 
 const emit = defineEmits(['send-to-tool']);
@@ -501,6 +686,23 @@ const pageSize = ref('a4'); // 'a4' | 'letter' | 'fit'
 const orientation = ref('auto'); // 'auto' | 'portrait' | 'landscape'
 const margin = ref('standard'); // 'none' | 'small' | 'standard'
 
+// Document Scanner Enhancement Mode
+const enhanceScanner = ref(false);
+const enhanceFilter = ref('color'); // 'color' | 'bw' | 'grayscale'
+const shadowSuppression = ref('medium'); // 'low' | 'medium' | 'high'
+
+const filterOptions = computed(() => [
+  { id: 'color', label: t('img2pdf_filter_color') || 'Auto Color' },
+  { id: 'bw', label: t('img2pdf_filter_bw') || 'Crisp B&W' },
+  { id: 'grayscale', label: t('img2pdf_filter_grayscale') || 'Grayscale' }
+]);
+
+const shadowOptions = computed(() => [
+  { id: 'low', label: t('img2pdf_shadow_low') || 'Subtle' },
+  { id: 'medium', label: t('img2pdf_shadow_medium') || 'Balanced' },
+  { id: 'high', label: t('img2pdf_shadow_high') || 'Strong' }
+]);
+
 const pageSizeOptions = computed(() => [
   { id: 'a4', label: t('img2pdf_size_a4') || 'A4 (Global / Europe)', desc: '210 × 297 mm' },
   { id: 'letter', label: t('img2pdf_size_letter') || 'US Letter (North America)', desc: '8.5 × 11 in' },
@@ -537,7 +739,9 @@ const currentSettingsSummary = computed(() => {
     marginName = mObj ? ` · ${mObj.label}` : '';
   }
 
-  return `${sizeName}${orientName}${marginName}`;
+  const enhanceName = enhanceScanner.value ? ` · ✨ ${t('img2pdf_badge_enhanced') || 'Enhanced'}` : '';
+
+  return `${sizeName}${orientName}${marginName}${enhanceName}`;
 });
 
 // Export Settings
@@ -553,6 +757,37 @@ const defaultFileNamePlaceholder = computed(() => {
   return `${prefix}_Images_${Date.now()}`;
 });
 
+async function updateEnhancedPreview(item) {
+  if (!enhanceScanner.value) return;
+  try {
+    const img = new Image();
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = reject;
+      img.src = item.previewUrl;
+    });
+    item.enhancedPreviewUrl = generateEnhancedThumbnail(img, {
+      mode: enhanceFilter.value,
+      shadowSuppression: shadowSuppression.value
+    });
+  } catch (e) {
+    item.enhancedPreviewUrl = '';
+  }
+}
+
+async function refreshAllEnhancedPreviews() {
+  if (!enhanceScanner.value) return;
+  for (const item of imageList.value) {
+    await updateEnhancedPreview(item);
+  }
+}
+
+watch([enhanceScanner, enhanceFilter, shadowSuppression], () => {
+  if (enhanceScanner.value) {
+    refreshAllEnhancedPreviews();
+  }
+});
+
 async function onFilesSelected(e) {
   const files = Array.from(e.target.files || []);
   if (files.length > 0) {
@@ -574,15 +809,21 @@ async function processAddedFiles(files) {
   for (const f of files) {
     const previewUrl = URL.createObjectURL(f);
     const { width, height } = await getImageDimensions(previewUrl);
-    imageList.value.push({
+    const item = {
       id: `img_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
       file: f,
       name: f.name,
       previewUrl,
+      enhancedPreviewUrl: '',
+      showOriginal: false,
       width,
       height,
       rotation: 0
-    });
+    };
+    imageList.value.push(item);
+    if (enhanceScanner.value) {
+      updateEnhancedPreview(item);
+    }
   }
 
   if (!customOutputBaseName.value) {
@@ -707,6 +948,16 @@ async function executeExport() {
       const renderH = Math.round(img.naturalHeight * scaleFactor);
       ctx.drawImage(img, -renderW / 2, -renderH / 2, renderW, renderH);
 
+      // Apply document scanner enhancement (shadow removal & paper whitening)
+      if (enhanceScanner.value) {
+        const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+        applyDocumentEnhancement(imgData, {
+          mode: enhanceFilter.value,
+          shadowSuppression: shadowSuppression.value
+        });
+        ctx.putImageData(imgData, 0, 0);
+      }
+
       const jpegDataUrl = canvas.toDataURL('image/jpeg', 0.90);
       const binary = atob(jpegDataUrl.split(',')[1]);
       const imgBytes = new Uint8Array(binary.length);
diff --git a/src/utils/imageProcess.js b/src/utils/imageProcess.js
index 33a0f5c..0e9f7ce 100644
--- a/src/utils/imageProcess.js
+++ b/src/utils/imageProcess.js
@@ -239,6 +239,188 @@ export function processImageToTransparentDataUrl(imgElement, options = {}) {
   return canvas.toDataURL('image/png');
 }
 
+/**
+ * Pure algorithm function for document photo enhancement:
+ * Flattens non-uniform shadows, whitens paper background, and sharpens text clarity.
+ * (CamScanner-style 100% in-browser illumination normalization)
+ * 
+ * @param {Object} imageData - { width, height, data: Uint8ClampedArray }
+ * @param {Object} [options={}]
+ * @param {'color'|'bw'|'grayscale'|'original'} [options.mode='color']
+ * @param {'none'|'low'|'medium'|'high'} [options.shadowSuppression='medium']
+ * @param {number} [options.whitenStrength=0.92] - Paper whitening sensitivity (0.7 ~ 1.0)
+ * @returns {Object} Processed imageData
+ */
+export function applyDocumentEnhancement(imageData, options = {}) {
+  if (!imageData || !imageData.data) return imageData;
+  const { width, height, data } = imageData;
+  const mode = options.mode ?? 'color';
+  if (mode === 'original') return imageData;
+
+  const shadowMode = options.shadowSuppression ?? 'medium';
+  const whitenStrength = options.whitenStrength ?? 0.92;
+  const totalPixels = width * height;
+  const gray = new Uint8Array(totalPixels);
+
+  // 1. Compute perceptual luminance
+  for (let i = 0; i < totalPixels; i++) {
+    const idx = i * 4;
+    gray[i] = Math.round(0.299 * data[idx] + 0.587 * data[idx + 1] + 0.114 * data[idx + 2]);
+  }
+
+  // 2. Estimate background illumination map (low-frequency shadow gradient)
+  let bgMap = null;
+  if (shadowMode !== 'none') {
+    let radiusRatio = 0.08; // medium default
+    if (shadowMode === 'low') radiusRatio = 0.04;
+    if (shadowMode === 'high') radiusRatio = 0.14;
+
+    const minDim = Math.min(width, height);
+    const maxAllowedRadius = Math.max(1, Math.floor(minDim / 3));
+    const blurRadius = Math.max(1, Math.min(maxAllowedRadius, Math.round(minDim * radiusRatio)));
+    bgMap = computeBoxBlurGrayscale(gray, width, height, blurRadius);
+  }
+
+  const paperThreshold = Math.round(255 - (whitenStrength * 55)); // ~204 by default
+  const bwThresholdRatio = 0.77 + ((1.0 - whitenStrength) * 0.1); // ~0.78 by default
+
+  // 3. Pixel-wise illumination normalization & tone mapping
+  for (let i = 0; i < totalPixels; i++) {
+    const idx = i * 4;
+    const gVal = gray[i];
+    const r = data[idx];
+    const g = data[idx + 1];
+    const b = data[idx + 2];
+
+    const localBg = bgMap ? Math.max(20, bgMap[i]) : 240;
+    const ratio = gVal / localBg;
+    const normLuma = Math.min(255, Math.round(ratio * 255));
+
+    if (mode === 'bw') {
+      // High-contrast clean black & white binary photocopy style
+      const isInk = (gVal < localBg * bwThresholdRatio) && (normLuma < 195);
+      const val = isInk ? 0 : 255;
+      data[idx] = val;
+      data[idx + 1] = val;
+      data[idx + 2] = val;
+    } else if (mode === 'grayscale') {
+      // Clean normalized grayscale with whitened paper
+      let val = normLuma;
+      if (normLuma >= paperThreshold) {
+        val = 255;
+      } else if (normLuma >= 175) {
+        const factor = (normLuma - 175) / (paperThreshold - 175);
+        val = Math.min(255, Math.round(175 + factor * (255 - 175)));
+      } else if (normLuma < 130) {
+        // Deepen dark text strokes
+        val = Math.max(0, Math.round(normLuma * 0.85 - 10));
+      }
+      data[idx] = val;
+      data[idx + 1] = val;
+      data[idx + 2] = val;
+    } else {
+      // mode === 'color': Preserve colored seals, stamps and colored ink while whitening paper
+      const maxC = Math.max(r, g, b);
+      const minC = Math.min(r, g, b);
+      const isChromatic = (maxC - minC) > 26; // Noticeable chromatic color (red stamp, blue pen, logo)
+
+      if (!isChromatic && (normLuma >= paperThreshold || normLuma >= 235)) {
+        // Paper background: Force to clean 255 pure white
+        data[idx] = 255;
+        data[idx + 1] = 255;
+        data[idx + 2] = 255;
+      } else if (!isChromatic && normLuma >= 180) {
+        // Smooth transition zone to pure white paper
+        const factor = (normLuma - 180) / (paperThreshold - 180);
+        const gain = 1.0 + factor * ((255 / Math.max(1, gVal)) - 1.0);
+        data[idx] = Math.min(255, Math.round(r * gain));
+        data[idx + 1] = Math.min(255, Math.round(g * gain));
+        data[idx + 2] = Math.min(255, Math.round(b * gain));
+      } else if (isChromatic) {
+        // Colorful stamp/ink: Whiten ambient paper background behind ink without dulling color
+        const gain = Math.min(2.2, Math.max(1.0, 255 / localBg));
+        data[idx] = Math.min(255, Math.round(r * gain));
+        data[idx + 1] = Math.min(255, Math.round(g * gain));
+        data[idx + 2] = Math.min(255, Math.round(b * gain));
+      } else {
+        // Dark text strokes: Contrast boost to make printed/handwritten text punchy
+        if (normLuma < 130) {
+          const darken = Math.max(0.65, normLuma / 140);
+          data[idx] = Math.round(r * darken);
+          data[idx + 1] = Math.round(g * darken);
+          data[idx + 2] = Math.round(b * darken);
+        } else {
+          const gain = Math.min(1.4, 255 / localBg);
+          data[idx] = Math.min(255, Math.round(r * gain));
+          data[idx + 1] = Math.min(255, Math.round(g * gain));
+          data[idx + 2] = Math.min(255, Math.round(b * gain));
+        }
+      }
+    }
+
+    // Ensure fully opaque document sheet
+    data[idx + 3] = 255;
+  }
+
+  return imageData;
+}
+
+/**
+ * Creates an enhanced document Canvas from an Image or Canvas element
+ * 
+ * @param {HTMLImageElement|HTMLCanvasElement} imgElement 
+ * @param {Object} [options={}] 
+ * @param {number} [options.maxDimension=2400]
+ * @returns {HTMLCanvasElement|null}
+ */
+export function enhanceDocumentCanvas(imgElement, options = {}) {
+  if (typeof document === 'undefined') return null;
+
+  const canvas = document.createElement('canvas');
+  const w = imgElement.naturalWidth || imgElement.width;
+  const h = imgElement.naturalHeight || imgElement.height;
+  if (!w || !h) return null;
+
+  const maxDim = options.maxDimension || 2400;
+  let targetW = w;
+  let targetH = h;
+  if (w > maxDim || h > maxDim) {
+    if (w > h) {
+      targetW = maxDim;
+      targetH = Math.round((h * maxDim) / w);
+    } else {
+      targetH = maxDim;
+      targetW = Math.round((w * maxDim) / h);
+    }
+  }
+
+  canvas.width = targetW;
+  canvas.height = targetH;
+  const ctx = canvas.getContext('2d');
+  ctx.drawImage(imgElement, 0, 0, targetW, targetH);
+
+  const imageData = ctx.getImageData(0, 0, targetW, targetH);
+  applyDocumentEnhancement(imageData, options);
+  ctx.putImageData(imageData, 0, 0);
+
+  return canvas;
+}
+
+/**
+ * Generates an enhanced thumbnail DataURL for instant card preview
+ * 
+ * @param {HTMLImageElement|HTMLCanvasElement} imgElement 
+ * @param {Object} [options={}] 
+ * @returns {string} JPEG DataURL
+ */
+export function generateEnhancedThumbnail(imgElement, options = {}) {
+  const canvas = enhanceDocumentCanvas(imgElement, {
+    ...options,
+    maxDimension: 360
+  });
+  return canvas ? canvas.toDataURL('image/jpeg', 0.85) : '';
+}
+
 /**
  * Saved Stamps LocalStorage Manager
  */
diff --git a/src/utils/pipeline/nodes/img2pdfNode.js b/src/utils/pipeline/nodes/img2pdfNode.js
index a790a91..8bbc7e8 100644
--- a/src/utils/pipeline/nodes/img2pdfNode.js
+++ b/src/utils/pipeline/nodes/img2pdfNode.js
@@ -1,18 +1,20 @@
 import { PDFDocument } from 'pdf-lib';
 import { logger } from '../../logger';
+import { applyDocumentEnhancement } from '../../imageProcess';
 
 /**
  * Headless Image to PDF Node (Reduce or Map)
  * Converts image items into PDF documents.
  * 
  * @param {Array<Object>} items 
- * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4' }
+ * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4', enhanceScanner: false, enhanceFilter: 'color'|'bw'|'grayscale' }
  * @param {Function} [onProgress]
  * @returns {Promise<Array<Object>>}
  */
 export async function executeImg2PdfNode(items, params = {}, onProgress = () => {}) {
   const mergeIntoOne = params.mergeIntoOne !== false;
   const pageSize = params.pageSize || 'fit_image';
+  const enhanceScanner = Boolean(params.enhanceScanner);
 
   if (mergeIntoOne) {
     onProgress(10, 'Initializing images to PDF...');
diff --git a/tests/documentEnhance.test.js b/tests/documentEnhance.test.js
new file mode 100644
index 0000000..29d7ce3
--- /dev/null
+++ b/tests/documentEnhance.test.js
@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import { applyDocumentEnhancement } from '../src/utils/imageProcess.js';
+
+describe('Document Scanner Enhancement Engine (applyDocumentEnhancement)', () => {
+  it('should flatten non-uniform lighting shadow and whiten paper while preserving colored stamps (mode=color)', () => {
+    // Create a 40x40 synthetic document with a dark shadow gradient across width:
+    // Left (x=0..19): bright paper (240, 235, 230)
+    // Right (x=20..39): shadowed paper (135, 130, 120)
+    // Text at (5, 5) in bright zone: (30, 30, 30)
+    // Text at (32, 5) in shadow zone: (20, 20, 20)
+    // Red seal at (32, 32) in shadow zone: (160, 30, 30)
+    const w = 40;
+    const h = 40;
+    const data = new Uint8ClampedArray(w * h * 4);
+
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const idx = (y * w + x) * 4;
+        const isShadow = x >= 20;
+        if (x === 5 && y === 5) {
+          // Dark text on bright paper
+          data[idx] = 30; data[idx + 1] = 30; data[idx + 2] = 30; data[idx + 3] = 255;
+        } else if (x === 32 && y === 5) {
+          // Dark text on shadowed paper
+          data[idx] = 20; data[idx + 1] = 20; data[idx + 2] = 20; data[idx + 3] = 255;
+        } else if (x === 32 && y === 32) {
+          // Red stamp on shadowed paper
+          data[idx] = 160; data[idx + 1] = 30; data[idx + 2] = 30; data[idx + 3] = 255;
+        } else if (isShadow) {
+          // Shadowed yellowish paper
+          data[idx] = 135; data[idx + 1] = 130; data[idx + 2] = 120; data[idx + 3] = 255;
+        } else {
+          // Bright paper
+          data[idx] = 240; data[idx + 1] = 235; data[idx + 2] = 230; data[idx + 3] = 255;
+        }
+      }
+    }
+
+    const imgData = { width: w, height: h, data };
+    applyDocumentEnhancement(imgData, { mode: 'color', shadowSuppression: 'medium' });
+
+    // 1. Both bright and shadowed paper should be normalized to pure white (255, 255, 255)
+    // Check bright paper at (0, 0)
+    const pBright = 0;
+    expect(data[pBright]).toBe(255);
+    expect(data[pBright + 1]).toBe(255);
+    expect(data[pBright + 2]).toBe(255);
+
+    // Check shadowed paper at (38, 0)
+    const pShadow = (0 * w + 38) * 4;
+    expect(data[pShadow]).toBeGreaterThanOrEqual(245);
+    expect(data[pShadow + 1]).toBeGreaterThanOrEqual(245);
+    expect(data[pShadow + 2]).toBeGreaterThanOrEqual(245);
+
+    // 2. Text in both zones should remain dark and sharp
+    const pTextBright = (5 * w + 5) * 4;
+    expect(data[pTextBright]).toBeLessThan(60);
+
+    const pTextShadow = (5 * w + 32) * 4;
+    expect(data[pTextShadow]).toBeLessThan(60);
+
+    // 3. Red stamp in shadow zone should retain strong red chroma
+    const pStamp = (32 * w + 32) * 4;
+    expect(data[pStamp]).toBeGreaterThan(120); // Strong Red
+    expect(data[pStamp + 1]).toBeLessThan(80); // Low Green
+    expect(data[pStamp + 2]).toBeLessThan(80); // Low Blue
+  });
+
+  it('should generate crisp binary black and white document in bw mode', () => {
+    const w = 4;
+    const h = 4;
+    const data = new Uint8ClampedArray(w * h * 4);
+
+    // Fill background with gray paper (160) and 1 black text pixel (25)
+    for (let i = 0; i < w * h; i++) {
+      const idx = i * 4;
+      data[idx] = 160; data[idx + 1] = 160; data[idx + 2] = 160; data[idx + 3] = 255;
+    }
+    // Pixel 5 is text
+    data[5 * 4] = 25; data[5 * 4 + 1] = 25; data[5 * 4 + 2] = 25;
+
+    const imgData = { width: w, height: h, data };
+    applyDocumentEnhancement(imgData, { mode: 'bw' });
+
+    // In bw mode, every pixel is either 0 or 255
+    for (let i = 0; i < w * h; i++) {
+      const idx = i * 4;
+      const val = data[idx];
+      expect(val === 0 || val === 255).toBe(true);
+      expect(data[idx + 1]).toBe(val);
+      expect(data[idx + 2]).toBe(val);
+    }
+
+    // Pixel 5 must be pure black (0)
+    expect(data[5 * 4]).toBe(0);
+    // Background pixel must be pure white (255)
+    expect(data[0]).toBe(255);
+  });
+
+  it('should produce pure gray shades in grayscale mode with pure white background', () => {
+    const w = 4;
+    const h = 4;
+    const data = new Uint8ClampedArray(w * h * 4);
+
+    // Color image with yellow paper and blue pen
+    for (let i = 0; i < w * h; i++) {
+      const idx = i * 4;
+      data[idx] = 210; data[idx + 1] = 200; data[idx + 2] = 170; data[idx + 3] = 255;
+    }
+    // Blue ink at pixel 2
+    data[2 * 4] = 30; data[2 * 4 + 1] = 50; data[2 * 4 + 2] = 180;
+
+    const imgData = { width: w, height: h, data };
+    applyDocumentEnhancement(imgData, { mode: 'grayscale' });
+
+    // In grayscale mode, R === G === B for all pixels
+    for (let i = 0; i < w * h; i++) {
+      const idx = i * 4;
+      expect(data[idx]).toBe(data[idx + 1]);
+      expect(data[idx + 1]).toBe(data[idx + 2]);
+    }
+
+    // Paper background should be whitened to 255
+    expect(data[0]).toBe(255);
+  });
+
+  it('should bypass modification when mode is original', () => {
+    const data = new Uint8ClampedArray([100, 150, 200, 255]);
+    const origData = new Uint8ClampedArray(data);
+    const imgData = { width: 1, height: 1, data };
+
+    applyDocumentEnhancement(imgData, { mode: 'original' });
+    expect(Array.from(data)).toEqual(Array.from(origData));
+  });
+
+  it('should safely handle invalid or empty input gracefully', () => {
+    expect(applyDocumentEnhancement(null)).toBeNull();
+    expect(applyDocumentEnhancement({})).toEqual({});
+  });
+
+  it('should support executeImg2PdfNode with enhanceScanner: true in pipeline', async () => {
+    const { executeImg2PdfNode } = await import('../src/utils/pipeline/nodes/img2pdfNode.js');
+    const base64Png = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+    const binary = atob(base64Png);
+    const pngBytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      pngBytes[i] = binary.charCodeAt(i);
+    }
+
+    const items = [
+      { id: 'img_1', name: 'receipt.png', data: pngBytes, mimeType: 'image/png' }
+    ];
+
+    const result = await executeImg2PdfNode(items, {
+      mergeIntoOne: true,
+      pageSize: 'a4',
+      enhanceScanner: true,
+      enhanceFilter: 'color'
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].mimeType).toBe('application/pdf');
+    expect(result[0].data.length).toBeGreaterThan(0);
+  });
+});

From edace55d64c10d2795a0598933b11caf4da7a3ab Mon Sep 17 00:00:00 2001
From: gzz727 <grenguo@gmail.com>
Date: Mon, 21 Sep 2026 15:42:05 +0800
Subject: [PATCH 2/5] refactor(scanner,sign): consolidate scanner parameters
 and optimize signature processing

---
 src/tools/ImageToPdfTool.vue            | 268 ++++++++++--------------
 src/tools/SignTool.vue                  |  63 +++++-
 src/utils/imageProcess.js               | 102 ++++++++-
 src/utils/pipeline/nodes/img2pdfNode.js |   4 +-
 tests/sign.test.js                      |  27 +++
 5 files changed, 287 insertions(+), 177 deletions(-)

diff --git a/src/tools/ImageToPdfTool.vue b/src/tools/ImageToPdfTool.vue
index cbdd6f3..aa8d297 100644
--- a/src/tools/ImageToPdfTool.vue
+++ b/src/tools/ImageToPdfTool.vue
@@ -165,7 +165,7 @@
                   <span class="bg-slate-900/75 backdrop-blur-xs text-white text-[9px] sm:text-[10px] font-mono font-bold px-1.5 py-0.5 rounded-md">
                     P{{ idx + 1 }}
                   </span>
-                  <span v-if="enhanceScanner" class="bg-violet-600/90 text-white text-[9px] font-bold px-1.5 py-0.5 rounded-md flex items-center space-x-0.5 shadow-2xs">
+                  <span v-if="scannerMode !== 'none'" class="bg-violet-600/90 text-white text-[9px] font-bold px-1.5 py-0.5 rounded-md flex items-center space-x-0.5 shadow-2xs">
                     <Sparkles class="w-2.5 h-2.5" />
                     <span class="hidden sm:inline">{{ t('img2pdf_badge_enhanced', 'Enhanced') }}</span>
                   </span>
@@ -183,14 +183,14 @@
                 <!-- Thumbnail with Instant Compare Capability -->
                 <div class="h-24 sm:h-32 rounded-lg sm:rounded-xl bg-slate-100 overflow-hidden flex items-center justify-center relative mb-1.5 group/thumb">
                   <img 
-                    :src="(enhanceScanner && img.enhancedPreviewUrl && !img.showOriginal) ? img.enhancedPreviewUrl : img.previewUrl" 
+                    :src="(scannerMode !== 'none' && img.enhancedPreviewUrl && !img.showOriginal) ? img.enhancedPreviewUrl : img.previewUrl" 
                     :style="{ transform: `rotate(${img.rotation}deg)` }"
                     class="max-h-full max-w-full object-contain transition-transform duration-200 pointer-events-none"
                   >
 
                   <!-- Hold to Compare Overlay (Desktop hover + Mobile touch) -->
                   <button
-                    v-if="enhanceScanner && img.enhancedPreviewUrl"
+                    v-if="scannerMode !== 'none' && img.enhancedPreviewUrl"
                     type="button"
                     @mousedown.stop="img.showOriginal = true"
                     @mouseup.stop="img.showOriginal = false"
@@ -253,82 +253,58 @@
           <!-- Right: Page & Layout Settings (4 cols, desktop wide screen only) -->
           <div class="hidden lg:flex lg:col-span-4 bg-slate-50/80 rounded-2xl p-4 border border-slate-200/80 flex-col justify-between space-y-4 overflow-y-auto max-h-[calc(100vh-280px)]">
             <div class="space-y-4">
-              <!-- Document Scanner & Shadow Removal Enhancement -->
+              <!-- Document Scanner & Shadow Removal Enhancement (Single Unified Parameter) -->
               <div class="p-3 rounded-2xl bg-gradient-to-br from-violet-50/80 to-indigo-50/50 border border-violet-200/80 shadow-2xs space-y-2.5">
-                <div class="flex items-center justify-between">
-                  <div class="flex items-center space-x-2">
-                    <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
-                      <Sparkles class="w-3.5 h-3.5" />
-                    </div>
-                    <div>
-                      <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
-                        <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
-                      </h4>
-                      <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
-                        {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
-                      </p>
-                    </div>
+                <div class="flex items-center space-x-2">
+                  <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
+                    <Sparkles class="w-3.5 h-3.5" />
+                  </div>
+                  <div>
+                    <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
+                      <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
+                    </h4>
+                    <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
+                      {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
+                    </p>
                   </div>
-                  <!-- Switch button -->
-                  <button 
-                    type="button" 
-                    @click="enhanceScanner = !enhanceScanner"
-                    :class="[
-                      'w-10 h-5.5 rounded-full transition-colors relative cursor-pointer focus:outline-none shrink-0',
-                      enhanceScanner ? 'bg-violet-600' : 'bg-slate-300'
-                    ]"
-                  >
-                    <span 
-                      :class="[
-                        'w-4.5 h-4.5 bg-white rounded-full transition-transform transform shadow-sm absolute top-0.5 left-0.5',
-                        enhanceScanner ? 'translate-x-4.5' : 'translate-x-0'
-                      ]" 
-                    />
-                  </button>
                 </div>
 
-                <!-- Filter & Shadow Options (Shown when active) -->
-                <div v-if="enhanceScanner" class="pt-2 border-t border-violet-200/60 space-y-2.5">
-                  <!-- Mode presets -->
-                  <div>
-                    <label class="block text-[11px] font-bold text-slate-700 mb-1">
-                      {{ t('img2pdf_filter_label', 'Enhance Filter') }}
-                    </label>
-                    <div class="grid grid-cols-3 gap-1">
-                      <button 
-                        v-for="flt in filterOptions" 
-                        :key="flt.id"
-                        type="button"
-                        @click="enhanceFilter = flt.id"
-                        :class="[
-                          'py-1.5 px-1 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer',
-                          enhanceFilter === flt.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
-                        ]"
-                      >
-                        {{ flt.label }}
-                      </button>
-                    </div>
+                <!-- Unified 4-Mode Selector (Original, Auto Color, Crisp B&W, Grayscale) -->
+                <div>
+                  <div class="grid grid-cols-4 gap-1">
+                    <button 
+                      v-for="mode in scannerModeOptions" 
+                      :key="mode.id"
+                      type="button"
+                      @click="scannerMode = mode.id"
+                      :class="[
+                        'py-1.5 px-0.5 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer flex items-center justify-center',
+                        scannerMode === mode.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs ring-1 ring-violet-300' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                      ]"
+                    >
+                      {{ mode.label }}
+                    </button>
                   </div>
+                </div>
 
-                  <!-- Shadow Suppression -->
-                  <div>
-                    <div class="flex items-center justify-between text-[11px] font-bold text-slate-700 mb-1">
-                      <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
-                    </div>
-                    <div class="grid grid-cols-3 gap-1">
-                      <button 
-                        v-for="sh in shadowOptions" 
-                        :key="sh.id"
-                        type="button"
-                        @click="shadowSuppression = sh.id"
-                        :class="[
-                          'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
-                          shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
-                        ]"
-                      >
-                        {{ sh.label }}
-                      </button>
-                    </div>
+                <!-- Shadow Suppression (Only shown when an enhance mode is active) -->
+                <div v-if="scannerMode !== 'none'" class="pt-2 border-t border-violet-200/60 space-y-1.5">
+                  <div class="flex items-center justify-between text-[11px] font-bold text-slate-700">
+                    <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
+                  </div>
+                  <div class="grid grid-cols-3 gap-1">
+                    <button 
+                      v-for="sh in shadowOptions" 
+                      :key="sh.id"
+                      type="button"
+                      @click="shadowSuppression = sh.id"
+                      :class="[
+                        'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
+                        shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                      ]"
+                    >
+                      {{ sh.label }}
+                    </button>
                   </div>
                 </div>
               </div>
@@ -468,82 +444,58 @@
           </button>
         </div>
 
-        <!-- Document Scanner & Shadow Removal Enhancement -->
+        <!-- Document Scanner & Shadow Removal Enhancement (Single Unified Parameter) -->
         <div class="p-3 rounded-2xl bg-gradient-to-br from-violet-50/80 to-indigo-50/50 border border-violet-200/80 shadow-2xs space-y-2.5">
-          <div class="flex items-center justify-between">
-            <div class="flex items-center space-x-2">
-              <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
-                <Sparkles class="w-3.5 h-3.5" />
-              </div>
-              <div>
-                <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
-                  <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
-                </h4>
-                <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
-                  {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
-                </p>
-              </div>
+          <div class="flex items-center space-x-2">
+            <div class="w-7 h-7 rounded-xl bg-violet-600 text-white flex items-center justify-center shadow-2xs shrink-0">
+              <Sparkles class="w-3.5 h-3.5" />
+            </div>
+            <div>
+              <h4 class="text-xs font-extrabold text-slate-900 flex items-center space-x-1.5 leading-tight">
+                <span>{{ t('img2pdf_enhance_title', 'Scanner Enhancement') }}</span>
+              </h4>
+              <p class="text-[10px] text-slate-500 font-medium leading-tight mt-0.5">
+                {{ t('img2pdf_enhance_desc', 'Flatten phone shadows & whiten paper') }}
+              </p>
             </div>
-            <!-- Switch button -->
-            <button 
-              type="button" 
-              @click="enhanceScanner = !enhanceScanner"
-              :class="[
-                'w-10 h-5.5 rounded-full transition-colors relative cursor-pointer focus:outline-none shrink-0',
-                enhanceScanner ? 'bg-violet-600' : 'bg-slate-300'
-              ]"
-            >
-              <span 
-                :class="[
-                  'w-4.5 h-4.5 bg-white rounded-full transition-transform transform shadow-sm absolute top-0.5 left-0.5',
-                  enhanceScanner ? 'translate-x-4.5' : 'translate-x-0'
-                ]" 
-              />
-            </button>
           </div>
 
-          <!-- Filter & Shadow Options (Shown when active) -->
-          <div v-if="enhanceScanner" class="pt-2 border-t border-violet-200/60 space-y-2.5">
-            <!-- Mode presets -->
-            <div>
-              <label class="block text-[11px] font-bold text-slate-700 mb-1">
-                {{ t('img2pdf_filter_label', 'Enhance Filter') }}
-              </label>
-              <div class="grid grid-cols-3 gap-1">
-                <button 
-                  v-for="flt in filterOptions" 
-                  :key="flt.id"
-                  type="button"
-                  @click="enhanceFilter = flt.id"
-                  :class="[
-                    'py-1.5 px-1 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer',
-                    enhanceFilter === flt.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
-                  ]"
-                >
-                  {{ flt.label }}
-                </button>
-              </div>
+          <!-- Unified 4-Mode Selector (Original, Auto Color, Crisp B&W, Grayscale) -->
+          <div>
+            <div class="grid grid-cols-4 gap-1">
+              <button 
+                v-for="mode in scannerModeOptions" 
+                :key="mode.id"
+                type="button"
+                @click="scannerMode = mode.id"
+                :class="[
+                  'py-1.5 px-0.5 rounded-xl text-[10px] font-semibold text-center border transition cursor-pointer flex items-center justify-center',
+                  scannerMode === mode.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs ring-1 ring-violet-300' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                ]"
+              >
+                {{ mode.label }}
+              </button>
             </div>
+          </div>
 
-            <!-- Shadow Suppression -->
-            <div>
-              <div class="flex items-center justify-between text-[11px] font-bold text-slate-700 mb-1">
-                <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
-              </div>
-              <div class="grid grid-cols-3 gap-1">
-                <button 
-                  v-for="sh in shadowOptions" 
-                  :key="sh.id"
-                  type="button"
-                  @click="shadowSuppression = sh.id"
-                  :class="[
-                    'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
-                    shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
-                  ]"
-                >
-                  {{ sh.label }}
-                </button>
-              </div>
+          <!-- Shadow Suppression (Only shown when an enhance mode is active) -->
+          <div v-if="scannerMode !== 'none'" class="pt-2 border-t border-violet-200/60 space-y-1.5">
+            <div class="flex items-center justify-between text-[11px] font-bold text-slate-700">
+              <span>{{ t('img2pdf_shadow_label', 'Shadow Removal') }}</span>
+            </div>
+            <div class="grid grid-cols-3 gap-1">
+              <button 
+                v-for="sh in shadowOptions" 
+                :key="sh.id"
+                type="button"
+                @click="shadowSuppression = sh.id"
+                :class="[
+                  'py-1 rounded-lg text-[10px] font-semibold text-center border transition cursor-pointer',
+                  shadowSuppression === sh.id ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs' : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                ]"
+              >
+                {{ sh.label }}
+              </button>
             </div>
           </div>
         </div>
@@ -686,12 +638,12 @@ const pageSize = ref('a4'); // 'a4' | 'letter' | 'fit'
 const orientation = ref('auto'); // 'auto' | 'portrait' | 'landscape'
 const margin = ref('standard'); // 'none' | 'small' | 'standard'
 
-// Document Scanner Enhancement Mode
-const enhanceScanner = ref(false);
-const enhanceFilter = ref('color'); // 'color' | 'bw' | 'grayscale'
+// Document Scanner Enhancement Mode (Single unified parameter)
+const scannerMode = ref('none'); // 'none' | 'color' | 'bw' | 'grayscale'
 const shadowSuppression = ref('medium'); // 'low' | 'medium' | 'high'
 
-const filterOptions = computed(() => [
+const scannerModeOptions = computed(() => [
+  { id: 'none', label: t('img2pdf_original') || 'Original' },
   { id: 'color', label: t('img2pdf_filter_color') || 'Auto Color' },
   { id: 'bw', label: t('img2pdf_filter_bw') || 'Crisp B&W' },
   { id: 'grayscale', label: t('img2pdf_filter_grayscale') || 'Grayscale' }
@@ -739,7 +691,7 @@ const currentSettingsSummary = computed(() => {
     marginName = mObj ? ` · ${mObj.label}` : '';
   }
 
-  const enhanceName = enhanceScanner.value ? ` · ✨ ${t('img2pdf_badge_enhanced') || 'Enhanced'}` : '';
+  const enhanceName = scannerMode.value !== 'none' ? ` · ✨ ${t('img2pdf_badge_enhanced') || 'Enhanced'}` : '';
 
   return `${sizeName}${orientName}${marginName}${enhanceName}`;
 });
@@ -758,7 +710,10 @@ const defaultFileNamePlaceholder = computed(() => {
 });
 
 async function updateEnhancedPreview(item) {
-  if (!enhanceScanner.value) return;
+  if (scannerMode.value === 'none') {
+    item.enhancedPreviewUrl = '';
+    return;
+  }
   try {
     const img = new Image();
     await new Promise((resolve, reject) => {
@@ -767,7 +722,7 @@ async function updateEnhancedPreview(item) {
       img.src = item.previewUrl;
     });
     item.enhancedPreviewUrl = generateEnhancedThumbnail(img, {
-      mode: enhanceFilter.value,
+      mode: scannerMode.value,
       shadowSuppression: shadowSuppression.value
     });
   } catch (e) {
@@ -776,16 +731,13 @@ async function updateEnhancedPreview(item) {
 }
 
 async function refreshAllEnhancedPreviews() {
-  if (!enhanceScanner.value) return;
   for (const item of imageList.value) {
     await updateEnhancedPreview(item);
   }
 }
 
-watch([enhanceScanner, enhanceFilter, shadowSuppression], () => {
-  if (enhanceScanner.value) {
-    refreshAllEnhancedPreviews();
-  }
+watch([scannerMode, shadowSuppression], () => {
+  refreshAllEnhancedPreviews();
 });
 
 async function onFilesSelected(e) {
@@ -821,7 +773,7 @@ async function processAddedFiles(files) {
       rotation: 0
     };
     imageList.value.push(item);
-    if (enhanceScanner.value) {
+    if (scannerMode.value !== 'none') {
       updateEnhancedPreview(item);
     }
   }
@@ -949,10 +901,10 @@ async function executeExport() {
       ctx.drawImage(img, -renderW / 2, -renderH / 2, renderW, renderH);
 
       // Apply document scanner enhancement (shadow removal & paper whitening)
-      if (enhanceScanner.value) {
+      if (scannerMode.value !== 'none') {
         const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
         applyDocumentEnhancement(imgData, {
-          mode: enhanceFilter.value,
+          mode: scannerMode.value,
           shadowSuppression: shadowSuppression.value
         });
         ctx.putImageData(imgData, 0, 0);
diff --git a/src/tools/SignTool.vue b/src/tools/SignTool.vue
index b22a297..650dba5 100644
--- a/src/tools/SignTool.vue
+++ b/src/tools/SignTool.vue
@@ -797,6 +797,7 @@ import { userSettings } from '../utils/userSettings';
 import { logger } from '../utils/logger';
 import { 
   processImageToTransparentDataUrl,
+  trimTransparentCanvas,
   loadSavedStamps,
   saveStampToLibrary,
   deleteSavedStamp,
@@ -1220,14 +1221,19 @@ function clearDrawCanvas() {
 function addDrawnSignature() {
   const canvas = drawCanvasRef.value;
   if (!canvas || !hasDrawn.value) return;
-  const dataUrl = canvas.toDataURL('image/png');
-  placeNewSignature(dataUrl, 140, 60);
+  const trimmed = trimTransparentCanvas(canvas, 6);
+  const dataUrl = trimmed.toDataURL('image/png');
+  const aspect = trimmed.width / (trimmed.height || 1);
+  const targetH = 50;
+  const targetW = Math.round(Math.min(220, Math.max(70, targetH * aspect)));
+  placeNewSignature(dataUrl, targetW, targetH);
 }
 
 function saveDrawnToLibrary() {
   const canvas = drawCanvasRef.value;
   if (!canvas || !hasDrawn.value) return;
-  const dataUrl = canvas.toDataURL('image/png');
+  const trimmed = trimTransparentCanvas(canvas, 6);
+  const dataUrl = trimmed.toDataURL('image/png');
   saveCurrentStamp(dataUrl, 'Handwritten Signature', 'draw');
 }
 
@@ -1255,8 +1261,12 @@ function addTypedSignature() {
 
   ctx.fillText(typedName.value.trim(), 250, 90);
 
-  const dataUrl = canvas.toDataURL('image/png');
-  placeNewSignature(dataUrl, 160, 60);
+  const trimmed = trimTransparentCanvas(canvas, 6);
+  const dataUrl = trimmed.toDataURL('image/png');
+  const aspect = trimmed.width / (trimmed.height || 1);
+  const targetH = 45;
+  const targetW = Math.round(Math.min(240, Math.max(80, targetH * aspect)));
+  placeNewSignature(dataUrl, targetW, targetH);
 }
 
 function saveTypedToLibrary() {
@@ -1280,7 +1290,8 @@ function saveTypedToLibrary() {
 
   ctx.fillText(typedName.value.trim(), 250, 90);
 
-  const dataUrl = canvas.toDataURL('image/png');
+  const trimmed = trimTransparentCanvas(canvas, 6);
+  const dataUrl = trimmed.toDataURL('image/png');
   saveCurrentStamp(dataUrl, typedName.value.trim(), 'type');
 }
 
@@ -1326,12 +1337,48 @@ function onStampFileSelected(e) {
 
 function addUploadedSignature() {
   if (!uploadedStampDataUrl.value) return;
-  placeNewSignature(uploadedStampDataUrl.value, 140, 65);
+  const img = new Image();
+  img.onload = () => {
+    const aspect = img.naturalWidth / (img.naturalHeight || 1);
+    let targetW = 130;
+    let targetH = Math.round(targetW / aspect);
+    if (targetH > 110) {
+      targetH = 100;
+      targetW = Math.round(targetH * aspect);
+    }
+    placeNewSignature(uploadedStampDataUrl.value, Math.max(40, targetW), Math.max(30, targetH));
+  };
+  img.onerror = () => {
+    placeNewSignature(uploadedStampDataUrl.value, 140, 65);
+  };
+  img.src = uploadedStampDataUrl.value;
 }
 
 function saveUploadedToLibrary() {
   if (!uploadedStampDataUrl.value) return;
-  saveCurrentStamp(uploadedStampDataUrl.value, 'Uploaded Stamp', 'upload');
+  const img = new Image();
+  img.onload = () => {
+    const aspect = img.naturalWidth / (img.naturalHeight || 1);
+    let targetW = 130;
+    let targetH = Math.round(targetW / aspect);
+    if (targetH > 110) {
+      targetH = 100;
+      targetW = Math.round(targetH * aspect);
+    }
+    saveStampToLibrary({
+      title: 'Uploaded Stamp',
+      type: 'upload',
+      dataUrl: uploadedStampDataUrl.value,
+      defaultWidth: Math.max(40, targetW),
+      defaultHeight: Math.max(30, targetH)
+    });
+    refreshSavedStamps();
+    showToast(t('sign_library_saved_toast'));
+  };
+  img.onerror = () => {
+    saveCurrentStamp(uploadedStampDataUrl.value, 'Uploaded Stamp', 'upload');
+  };
+  img.src = uploadedStampDataUrl.value;
 }
 
 // ----------------- STAMP LIBRARY ENGINE -----------------
diff --git a/src/utils/imageProcess.js b/src/utils/imageProcess.js
index 0e9f7ce..4cba2f4 100644
--- a/src/utils/imageProcess.js
+++ b/src/utils/imageProcess.js
@@ -114,9 +114,13 @@ export const INK_COLORS = {
  */
 export function applyBackgroundFlattening(imageData, options = {}) {
   const { width, height, data } = imageData;
-  const threshold = options.threshold ?? 220;
+  let threshold = options.threshold ?? 220;
+  // If threshold is passed as a percentage (e.g. 50..100 from UI slider)
+  if (threshold <= 100) {
+    threshold = Math.round((threshold / 100) * 255);
+  }
   const softness = options.softness ?? 25;
-  const shadowMode = options.shadowSuppression ?? 'medium';
+  const shadowMode = options.shadowSuppression ?? options.shadowRemoval ?? 'medium';
   const inkColorKey = options.inkColor ?? 'original';
   const enhanceContrast = options.enhanceContrast ?? true;
 
@@ -199,19 +203,37 @@ export function applyBackgroundFlattening(imageData, options = {}) {
 }
 
 /**
- * Processes an Image (HTMLImageElement, HTMLCanvasElement, or dataURL) in browser
+ * Processes an Image (HTMLImageElement, HTMLCanvasElement, or dataURL string) in browser
  * and produces a clean transparent PNG dataURL.
  * 
- * @param {HTMLImageElement|HTMLCanvasElement} imgElement 
- * @param {Object} options 
- * @returns {string} Processed transparent PNG dataURL
+ * @param {HTMLImageElement|HTMLCanvasElement|string} imgElementOrUrl 
+ * @param {Object} [options={}] 
+ * @returns {Promise<string>} Processed transparent PNG dataURL
  */
-export function processImageToTransparentDataUrl(imgElement, options = {}) {
+export async function processImageToTransparentDataUrl(imgElementOrUrl, options = {}) {
   if (typeof document === 'undefined') return '';
 
-  const canvas = document.createElement('canvas');
+  let imgElement = imgElementOrUrl;
+  if (typeof imgElementOrUrl === 'string') {
+    try {
+      const img = new Image();
+      await new Promise((resolve, reject) => {
+        img.onload = resolve;
+        img.onerror = reject;
+        img.src = imgElementOrUrl;
+      });
+      imgElement = img;
+    } catch (e) {
+      return '';
+    }
+  }
+
+  if (!imgElement) return '';
   const w = imgElement.naturalWidth || imgElement.width;
   const h = imgElement.naturalHeight || imgElement.height;
+  if (!w || !h) return '';
+
+  const canvas = document.createElement('canvas');
 
   // Scale down huge mobile camera photos (e.g. 4000x3000 -> max 1000px) for speed and PDF compactness
   const maxDim = 1000;
@@ -236,7 +258,69 @@ export function processImageToTransparentDataUrl(imgElement, options = {}) {
   applyBackgroundFlattening(imageData, options);
   ctx.putImageData(imageData, 0, 0);
 
-  return canvas.toDataURL('image/png');
+  const shouldTrim = options.trim !== false;
+  const outputCanvas = shouldTrim ? trimTransparentCanvas(canvas) : canvas;
+
+  return outputCanvas.toDataURL('image/png');
+}
+
+/**
+ * Trims transparent border pixels from a canvas, returning a tight-fitting canvas.
+ * 
+ * @param {HTMLCanvasElement} canvas 
+ * @param {number} [padding=6] 
+ * @returns {HTMLCanvasElement}
+ */
+export function trimTransparentCanvas(canvas, padding = 6) {
+  if (typeof document === 'undefined' || !canvas || !canvas.width || !canvas.height) return canvas;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return canvas;
+
+  const w = canvas.width;
+  const h = canvas.height;
+  let imgData;
+  try {
+    imgData = ctx.getImageData(0, 0, w, h);
+  } catch (e) {
+    return canvas;
+  }
+  const data = imgData.data;
+
+  let minX = w;
+  let minY = h;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const alpha = data[(y * w + x) * 4 + 3];
+      if (alpha > 15) {
+        if (x < minX) minX = x;
+        if (x > maxX) maxX = x;
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+      }
+    }
+  }
+
+  // If completely transparent or nothing detected, return original canvas
+  if (maxX < minX || maxY < minY) {
+    return canvas;
+  }
+
+  const cropX = Math.max(0, minX - padding);
+  const cropY = Math.max(0, minY - padding);
+  const cropW = Math.min(w - cropX, (maxX - minX + 1) + padding * 2);
+  const cropH = Math.min(h - cropY, (maxY - minY + 1) + padding * 2);
+
+  const trimmedCanvas = document.createElement('canvas');
+  trimmedCanvas.width = cropW;
+  trimmedCanvas.height = cropH;
+  const tCtx = trimmedCanvas.getContext('2d');
+  if (!tCtx) return canvas;
+
+  tCtx.drawImage(canvas, cropX, cropY, cropW, cropH, 0, 0, cropW, cropH);
+  return trimmedCanvas;
 }
 
 /**
diff --git a/src/utils/pipeline/nodes/img2pdfNode.js b/src/utils/pipeline/nodes/img2pdfNode.js
index 8bbc7e8..b65dcd5 100644
--- a/src/utils/pipeline/nodes/img2pdfNode.js
+++ b/src/utils/pipeline/nodes/img2pdfNode.js
@@ -7,14 +7,14 @@ import { applyDocumentEnhancement } from '../../imageProcess';
  * Converts image items into PDF documents.
  * 
  * @param {Array<Object>} items 
- * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4', enhanceScanner: false, enhanceFilter: 'color'|'bw'|'grayscale' }
+ * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4', scannerMode: 'none'|'color'|'bw'|'grayscale' }
  * @param {Function} [onProgress]
  * @returns {Promise<Array<Object>>}
  */
 export async function executeImg2PdfNode(items, params = {}, onProgress = () => {}) {
   const mergeIntoOne = params.mergeIntoOne !== false;
   const pageSize = params.pageSize || 'fit_image';
-  const enhanceScanner = Boolean(params.enhanceScanner);
+  const scannerMode = params.scannerMode || (params.enhanceScanner ? (params.enhanceFilter || 'color') : 'none');
 
   if (mergeIntoOne) {
     onProgress(10, 'Initializing images to PDF...');
diff --git a/tests/sign.test.js b/tests/sign.test.js
index c23a39c..b939e2c 100644
--- a/tests/sign.test.js
+++ b/tests/sign.test.js
@@ -3,6 +3,7 @@ import { PDFDocument } from 'pdf-lib';
 import { 
   applyBackgroundFlattening, 
   computeBoxBlurGrayscale,
+  trimTransparentCanvas,
   calculateBatchTargetPages,
   loadSavedStamps,
   saveStampToLibrary,
@@ -106,12 +107,38 @@ describe('Image Processing & White Background Removal Engine', () => {
     expect(data[3]).toBe(255);
   });
 
+  it('should treat percentage thresholds (e.g. 80%) correctly without erasing dark ink', () => {
+    // 2x1: pixel 0 is paper (230), pixel 1 is ink stroke (70)
+    const data = new Uint8ClampedArray([
+      230, 230, 230, 255,
+      70, 70, 70, 255
+    ]);
+    const imgData = { width: 2, height: 1, data };
+
+    // Passing threshold as 80 (e.g. from UI percentage slider 80%)
+    applyBackgroundFlattening(imgData, {
+      threshold: 80,
+      shadowSuppression: 'none'
+    });
+
+    // 80% maps to 204.
+    // Pixel 0 (230 >= 204) -> transparent (0)
+    expect(data[3]).toBe(0);
+    // Pixel 1 (70 <= 204 - 25) -> fully opaque (255)
+    expect(data[7]).toBe(255);
+  });
+
   it('should compute box blur on 1D grayscale buffer correctly', () => {
     const gray = new Uint8Array([10, 20, 30, 40, 50]);
     const blurred = computeBoxBlurGrayscale(gray, 5, 1, 1);
     expect(blurred.length).toBe(5);
     expect(blurred[2]).toBeCloseTo(30, 0); // Center pixel average of 20, 30, 40
   });
+
+  it('should safely return original canvas if trimTransparentCanvas receives null or empty canvas', () => {
+    expect(trimTransparentCanvas(null)).toBeNull();
+    expect(trimTransparentCanvas({})).toEqual({});
+  });
 });
 
 describe('Multi-Page Batch Target Page Calculator', () => {

From 0c282e6c44f2f8ed903b75af30a2ef11cfb82833 Mon Sep 17 00:00:00 2001
From: gzz727 <grenguo@gmail.com>
Date: Mon, 21 Sep 2026 16:24:40 +0800
Subject: [PATCH 3/5] feat(pipeline): expose document scanner enhancement in
 img2pdf node

---
 src/tools/PipelineTool.vue              | 83 ++++++++++++++++++++++++-
 src/utils/pipeline/nodes/img2pdfNode.js | 59 ++++++++++++++++--
 src/utils/pipeline/pipelineTypes.js     |  2 +
 src/utils/pipeline/presetPipelines.js   |  2 +
 tests/documentEnhance.test.js           | 24 +++++++
 5 files changed, 163 insertions(+), 7 deletions(-)

diff --git a/src/tools/PipelineTool.vue b/src/tools/PipelineTool.vue
index 9642489..d148bf3 100644
--- a/src/tools/PipelineTool.vue
+++ b/src/tools/PipelineTool.vue
@@ -1446,6 +1446,72 @@
                 </label>
               </div>
             </div>
+
+            <!-- Document Scanner Enhancement Section -->
+            <div class="p-4 rounded-xl border border-violet-200/80 bg-violet-50/20 space-y-3">
+              <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-2">
+                  <Sparkles class="w-4 h-4 text-violet-600" />
+                  <span class="font-bold text-slate-800 text-sm">{{ t('img2pdf_scanner_title') }}</span>
+                </div>
+                <span v-if="editingStepDraft.scannerMode && editingStepDraft.scannerMode !== 'none'" class="text-[10px] font-bold px-2 py-0.5 bg-violet-100 text-violet-700 rounded-full border border-violet-200">
+                  ✨ {{ t('img2pdf_badge_enhanced') }}
+                </span>
+              </div>
+              <p class="text-xs text-slate-500 leading-relaxed">
+                {{ t('img2pdf_scanner_desc') }}
+              </p>
+
+              <!-- Segmented 4-Pill Mode Selector -->
+              <div class="grid grid-cols-2 sm:grid-cols-4 gap-1.5 p-1 bg-slate-200/60 rounded-xl text-xs font-semibold">
+                <button
+                  type="button"
+                  v-for="mode in [
+                    { id: 'none', label: t('img2pdf_original') || 'Original' },
+                    { id: 'color', label: t('img2pdf_filter_color') || 'Auto Color' },
+                    { id: 'bw', label: t('img2pdf_filter_bw') || 'Crisp B&W' },
+                    { id: 'grayscale', label: t('img2pdf_filter_grayscale') || 'Grayscale' }
+                  ]"
+                  :key="mode.id"
+                  @click="editingStepDraft.scannerMode = mode.id"
+                  :class="[
+                    'py-1.5 px-2 rounded-lg transition text-center cursor-pointer',
+                    (editingStepDraft.scannerMode || 'none') === mode.id
+                      ? 'bg-white text-violet-900 font-bold shadow-xs'
+                      : 'text-slate-600 hover:text-slate-900 hover:bg-white/50'
+                  ]"
+                >
+                  {{ mode.label }}
+                </button>
+              </div>
+
+              <!-- Shadow Suppression (Shown when an enhance mode is active) -->
+              <div v-if="editingStepDraft.scannerMode && editingStepDraft.scannerMode !== 'none'" class="pt-2.5 border-t border-violet-200/60 space-y-1.5">
+                <div class="flex items-center justify-between text-xs font-bold text-slate-700">
+                  <span>{{ t('img2pdf_shadow_label') }}</span>
+                </div>
+                <div class="grid grid-cols-3 gap-1.5">
+                  <button
+                    v-for="sh in [
+                      { id: 'low', label: t('img2pdf_shadow_low') || 'Low' },
+                      { id: 'medium', label: t('img2pdf_shadow_medium') || 'Medium' },
+                      { id: 'high', label: t('img2pdf_shadow_high') || 'High' }
+                    ]"
+                    :key="sh.id"
+                    type="button"
+                    @click="editingStepDraft.shadowSuppression = sh.id"
+                    :class="[
+                      'py-1.5 rounded-lg text-xs font-semibold text-center border transition cursor-pointer',
+                      (editingStepDraft.shadowSuppression || 'medium') === sh.id
+                        ? 'bg-white border-violet-500 text-violet-900 font-bold shadow-xs'
+                        : 'bg-white/60 border-slate-200 text-slate-600 hover:bg-white'
+                    ]"
+                  >
+                    {{ sh.label }}
+                  </button>
+                </div>
+              </div>
+            </div>
           </div>
 
           <!-- 5. Pdf2Img Parameters -->
@@ -3026,6 +3092,17 @@ function openStepConfigModal(idx) {
     }
   }
 
+  if (step.nodeId === 'node_img2pdf') {
+    if (!editingStepDraft.value.scannerMode) {
+      editingStepDraft.value.scannerMode = editingStepDraft.value.enhanceScanner
+        ? (editingStepDraft.value.enhanceFilter || 'color')
+        : 'none';
+    }
+    if (!editingStepDraft.value.shadowSuppression) {
+      editingStepDraft.value.shadowSuppression = 'medium';
+    }
+  }
+
   if (step.nodeId === 'node_protect') {
     showProtectUserPwd.value = false;
     showProtectOwnerPwd.value = false;
@@ -3182,7 +3259,11 @@ function getStepSummary(step) {
     case 'node_img2pdf': {
       const merge = step.params.mergeIntoOne ? t('pipe_merge_one', 'Merged') : t('pipe_merge_split', '1 Page/Img');
       const sz = step.params.pageSize === 'a4' ? 'A4' : t('pipe_sz_fit', 'Original');
-      return `${merge} · ${sz}`;
+      const scannerMode = step.params.scannerMode || (step.params.enhanceScanner ? (step.params.enhanceFilter || 'color') : 'none');
+      const enhance = scannerMode !== 'none'
+        ? ` · ✨ ${t('img2pdf_badge_enhanced') || 'Enhanced'}`
+        : '';
+      return `${merge} · ${sz}${enhance}`;
     }
     case 'node_pdf2img': {
       const fmt = (step.params.format || 'png').toUpperCase();
diff --git a/src/utils/pipeline/nodes/img2pdfNode.js b/src/utils/pipeline/nodes/img2pdfNode.js
index b65dcd5..8fffbe2 100644
--- a/src/utils/pipeline/nodes/img2pdfNode.js
+++ b/src/utils/pipeline/nodes/img2pdfNode.js
@@ -1,13 +1,59 @@
 import { PDFDocument } from 'pdf-lib';
 import { logger } from '../../logger';
-import { applyDocumentEnhancement } from '../../imageProcess';
+import { enhanceDocumentCanvas } from '../../imageProcess';
+
+function isJpegBuffer(data, mimeType, name) {
+  if (data && data.length >= 4) {
+    if (data[0] === 0xFF && data[1] === 0xD8 && data[2] === 0xFF) return true;
+    if (data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4E && data[3] === 0x47) return false;
+  }
+  return mimeType === 'image/jpeg' || mimeType === 'image/jpg' || /\.jpe?g$/i.test(name || '');
+}
+
+async function prepareImageBytes(item, scannerMode, shadowSuppression) {
+  const isJpg = isJpegBuffer(item.data, item.mimeType, item.name);
+  if (!scannerMode || scannerMode === 'none' || typeof document === 'undefined') {
+    return { data: item.data, isJpg };
+  }
+
+  try {
+    const blob = new Blob([item.data], { type: item.mimeType || (isJpg ? 'image/jpeg' : 'image/png') });
+    const blobUrl = URL.createObjectURL(blob);
+    const img = new Image();
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = reject;
+      img.src = blobUrl;
+    });
+    URL.revokeObjectURL(blobUrl);
+
+    const canvas = enhanceDocumentCanvas(img, {
+      mode: scannerMode,
+      shadowSuppression: shadowSuppression || 'medium'
+    });
+    if (!canvas) {
+      return { data: item.data, isJpg };
+    }
+
+    const enhancedDataUrl = canvas.toDataURL('image/jpeg', 0.92);
+    const binary = atob(enhancedDataUrl.split(',')[1]);
+    const enhancedBytes = new Uint8Array(binary.length);
+    for (let k = 0; k < binary.length; k++) {
+      enhancedBytes[k] = binary.charCodeAt(k);
+    }
+    return { data: enhancedBytes, isJpg: true };
+  } catch (err) {
+    logger.warn('PIPELINE_IMG2PDF', `Document enhancement failed for ${item.name}: ${err.message}`);
+    return { data: item.data, isJpg };
+  }
+}
 
 /**
  * Headless Image to PDF Node (Reduce or Map)
  * Converts image items into PDF documents.
  * 
  * @param {Array<Object>} items 
- * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4', scannerMode: 'none'|'color'|'bw'|'grayscale' }
+ * @param {Object} params - { mergeIntoOne: true, pageSize: 'fit_image'|'a4', scannerMode: 'none'|'color'|'bw'|'grayscale', shadowSuppression: 'low'|'medium'|'high' }
  * @param {Function} [onProgress]
  * @returns {Promise<Array<Object>>}
  */
@@ -15,6 +61,7 @@ export async function executeImg2PdfNode(items, params = {}, onProgress = () =>
   const mergeIntoOne = params.mergeIntoOne !== false;
   const pageSize = params.pageSize || 'fit_image';
   const scannerMode = params.scannerMode || (params.enhanceScanner ? (params.enhanceFilter || 'color') : 'none');
+  const shadowSuppression = params.shadowSuppression || 'medium';
 
   if (mergeIntoOne) {
     onProgress(10, 'Initializing images to PDF...');
@@ -25,8 +72,8 @@ export async function executeImg2PdfNode(items, params = {}, onProgress = () =>
       onProgress(10 + Math.round((i / items.length) * 80), `Assembling image [${i + 1}/${items.length}]: ${item.name}`);
 
       try {
-        const isJpg = item.mimeType === 'image/jpeg' || /\.jpe?g$/i.test(item.name);
-        const embeddedImg = isJpg ? await mergedDoc.embedJpg(item.data) : await mergedDoc.embedPng(item.data);
+        const { data: imgBytes, isJpg } = await prepareImageBytes(item, scannerMode, shadowSuppression);
+        const embeddedImg = isJpg ? await mergedDoc.embedJpg(imgBytes) : await mergedDoc.embedPng(imgBytes);
         const { width: imgW, height: imgH } = embeddedImg;
 
         if (pageSize === 'a4') {
@@ -71,8 +118,8 @@ export async function executeImg2PdfNode(items, params = {}, onProgress = () =>
 
       try {
         const doc = await PDFDocument.create();
-        const isJpg = item.mimeType === 'image/jpeg' || /\.jpe?g$/i.test(item.name);
-        const embeddedImg = isJpg ? await doc.embedJpg(item.data) : await doc.embedPng(item.data);
+        const { data: imgBytes, isJpg } = await prepareImageBytes(item, scannerMode, shadowSuppression);
+        const embeddedImg = isJpg ? await doc.embedJpg(imgBytes) : await doc.embedPng(imgBytes);
         const { width: imgW, height: imgH } = embeddedImg;
         const page = doc.addPage([imgW, imgH]);
         page.drawImage(embeddedImg, { x: 0, y: 0, width: imgW, height: imgH });
diff --git a/src/utils/pipeline/pipelineTypes.js b/src/utils/pipeline/pipelineTypes.js
index eba0719..8aa6b47 100644
--- a/src/utils/pipeline/pipelineTypes.js
+++ b/src/utils/pipeline/pipelineTypes.js
@@ -28,6 +28,8 @@ export const AVAILABLE_NODES = {
     defaultParams: {
       mergeIntoOne: true,
       pageSize: 'fit_image', // 'fit_image' | 'a4'
+      scannerMode: 'none', // 'none' | 'color' | 'bw' | 'grayscale'
+      shadowSuppression: 'medium', // 'low' | 'medium' | 'high'
       quality: 0.85
     }
   },
diff --git a/src/utils/pipeline/presetPipelines.js b/src/utils/pipeline/presetPipelines.js
index 4a5f80c..efebf74 100644
--- a/src/utils/pipeline/presetPipelines.js
+++ b/src/utils/pipeline/presetPipelines.js
@@ -79,6 +79,8 @@ export const PRESET_PIPELINES = [
         params: {
           mergeIntoOne: true,
           pageSize: 'a4',
+          scannerMode: 'color',
+          shadowSuppression: 'medium',
           quality: 0.85
         }
       },
diff --git a/tests/documentEnhance.test.js b/tests/documentEnhance.test.js
index 29d7ce3..9fd82b7 100644
--- a/tests/documentEnhance.test.js
+++ b/tests/documentEnhance.test.js
@@ -162,4 +162,28 @@ describe('Document Scanner Enhancement Engine (applyDocumentEnhancement)', () =>
     expect(result[0].mimeType).toBe('application/pdf');
     expect(result[0].data.length).toBeGreaterThan(0);
   });
+
+  it('should support executeImg2PdfNode with consolidated scannerMode in pipeline', async () => {
+    const { executeImg2PdfNode } = await import('../src/utils/pipeline/nodes/img2pdfNode.js');
+    const base64Png = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+    const binary = atob(base64Png);
+    const pngBytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      pngBytes[i] = binary.charCodeAt(i);
+    }
+
+    const items = [
+      { id: 'img_2', name: 'contract_photo.jpg', data: pngBytes, mimeType: 'image/jpeg' }
+    ];
+
+    const result = await executeImg2PdfNode(items, {
+      mergeIntoOne: false,
+      scannerMode: 'bw',
+      shadowSuppression: 'high'
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('contract_photo.pdf');
+    expect(result[0].data.length).toBeGreaterThan(0);
+  });
 });

From 8af24d8367e96176922919d3b63b2e84b41d3e54 Mon Sep 17 00:00:00 2001
From: gzz727 <grenguo@gmail.com>
Date: Mon, 21 Sep 2026 16:28:34 +0800
Subject: [PATCH 4/5] docs: update README and roadmap with scanner enhancement
 and sign optimizations

---
 README.md       | 6 +++---
 README.zh-CN.md | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 75cdc07..0f9e30a 100644
--- a/README.md
+++ b/README.md
@@ -46,9 +46,9 @@ Why **PDFSeal**? In English, **"Seal"** has a charming double meaning:
 - **Smart Compress**: Reduce file size by up to 90% across 4 fine-tuned modes: *Balanced (300 DPI)* for crisp readability; *Extreme (150 DPI)* for tight email caps; *Lossless Object Stream Compression* for structural optimization without rasterization; and **Target Size Bisection** (specify exact thresholds like ≤ 2MB, auto-tuning resolution and quality factors in-browser). All modes are guarded by a Universal Anti-Inflation Size Guard.
 - **Watermark & Protect**: High-DPI transparent canvas watermark stamping engine. Supports multilingual typography, custom font sizing, opacity, tilt angles (-90° to 90°), repetitive grid tiling or centered placement, quick color swatches (Official Red, Navy Blue), and custom hex values, with direct chaining into owner-level permission encryption.
 - **Dynamic Page Numbering**: Professional document pagination. Supports customizable format macros (`{n}`, `{total}`, `Page {n} of {total}`, etc.), 6 header/footer alignment anchors, odd/even mirror flipping, and cover page skipping (starting page 1 on sheet 2). Features proprietary **Whiteout Masking** (full-ribbon or local bounding box) with canvas color auto-sampling to cleanly conceal misaligned legacy page numbers.
-- **Sign & Stamp**: Engineered for rigorous contract signing. Supports freehand drawing, typography-generated signatures, and uploaded seal images. Proprietary local background flattening automatically strips camera shadows and paper whiteout, with instant ink recoloring (Original, Ink Black, Deep Blue, Stamp Red). One-click batch initial placement across all, even, odd, or non-terminal pages, backed by a persistent local seal library and positioning presets.
+- **Sign & Stamp**: Engineered for rigorous contract signing. Supports freehand drawing, typography-generated signatures, and uploaded seal images. Proprietary local background flattening automatically strips camera shadows and paper whiteout, with instant ink recoloring (Original, Ink Black, Deep Blue, Stamp Red). Features **Smart Auto-Trim Bounding Boxes** to crop away transparent whitespace for pixel-perfect placement, and automatic aspect-ratio preservation for official circular and square seals. One-click batch initial placement across all, even, odd, or non-terminal pages, backed by a persistent local seal library and positioning presets.
 - **PDF to Image**: High-fidelity rasterization of PDF pages into crisp PNG or JPG images. Choose between *Standard 150 DPI* for web distribution and *Print-Grade 300 DPI* for archival clarity. Download individual pages directly from thumbnail cards or export the complete set as a zipped archive in one click.
-- **Image to PDF**: Convert batches of PNG, JPG, WebP, and BMP images into a unified multi-page PDF. Offers standardized A4 dimensions (with auto-orientation and proportional centered margins) or adaptive native-image sizing, ideal for expense receipt collation and identity document archiving.
+- **Image to PDF (with Scanner Enhancement)**: Convert batches of PNG, JPG, WebP, and BMP images into a unified multi-page PDF. Includes a proprietary **In-Browser Document Scanner Enhancement Engine (CamScanner-Style)**: $O(W \times H)$ illuminance normalization flattens phone/wrist shadows and whitens yellowish paper backgrounds, with 3 optimized filter modes (*Auto Color* preserving red seals, *Crisp B&W* high-contrast binary text, and *Clean Grayscale*), live real-time thumbnail updates, and interactive **Hold to Compare** original view. Offers standardized A4 dimensions (with auto-orientation and proportional centered margins) or adaptive native-image sizing.
 - **Protect & Encrypt**: Modern high-grade AES-256 client-side encryption. Protect documents with an **Open Password (User Password)** to prevent unauthorized reading, and set an **Owner Password** to enforce granular operational restrictions (prohibiting unauthorized printing, text/image extraction, form alterations, and annotating), securing distributed contracts without sending keys to the cloud.
 - **Unlock & Strip Restrictions**: Permanently remove encryption locks and permission restrictions. After validating the document password, the client engine restructures the internal object streams to permanently purge encryption dictionaries, yielding a clean, unrestricted, plaintext PDF.
 - **Scrub Metadata**: Essential privacy purification for government, corporate audits, and sensitive disclosures. Deeply audits and permanently purges hidden forensic metadata and underlying attributes: document titles, author names, company names, software fingerprints (Word, WPS, InDesign), timestamps, camera GPS coordinates, private application dictionaries (PieceInfo), and embedded thumbnail caches.
@@ -66,7 +66,7 @@ Why **PDFSeal**? In English, **"Seal"** has a charming double meaning:
 - **Battle-Tested Presets**:
   - 📁 **Tender & Sensitive Document Sanitizer**: Metadata scrubbing $\rightarrow$ Balanced compression $\rightarrow$ Anti-leak watermark stamping.
   - 🛡️ **Privacy & Content Redaction**: Metadata scrubbing $\rightarrow$ Keyword/regex PII redaction $\rightarrow$ AES permission encryption.
-  - 🧾 **Expense Receipts Auto-Packer**: Multi-image to A4 PDF conversion $\rightarrow$ Compression sized for reimbursement portals.
+  - 🧾 **Expense Receipts Auto-Packer**: Multi-image to A4 PDF conversion (with automatic shadow removal & paper whitening) $\rightarrow$ Audit page numbering $\rightarrow$ Smart compression $\rightarrow$ EXPENSE REPORT watermark.
   - 📑 **Contract Batch Stamping & Archive**: Permission unlock $\rightarrow$ Last page signature stamping $\rightarrow$ Security watermark.
 - **Visual Drag & Drop Pipeline Builder**:
   - Reorder, configure, add, or remove steps with live node compatibility port validation.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2cded17..67052f5 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -46,9 +46,9 @@
 - **智能多模压缩 (Smart Compress)**：最高压缩 90% 体积。内置 4 档精细模式：*均衡模式 (300 DPI)* 兼顾画质与体积；*极限模式 (150 DPI)* 极限瘦身适合邮件附件；*无损对象流压缩* 纯净精简内部结构；以及**目标体积智能逼近**（输入硬性指标如 ≤ 2MB，纯本地二分搜索算法自动微调清晰度逼近上限）。全模式均受通用防膨胀体积护栏保护。
 - **水印与安全防伪 (Watermark & Protect)**：高 DPI 透明 Canvas 水印压印引擎。支持多语言排版、自定义字号、不透明度、倾斜角度（-90° 至 90°）、平铺或单点居中印压、快捷印章色（印章红、商务蓝等）与 Hex 色值自定义，支持在压印完成后直接连带配置所有者权限加密锁。
 - **动态页码编排 (Dynamic Page Numbering)**：专业级文档统一页码规整。支持灵活宏表达式（`{n}`、`{total}`、`Page {n} of {total}`、`第 {n} 页 共 {total} 页`）、6 大页眉/页脚对齐锚点、奇偶页镜像翻转、跳过首页封面（第 2 页起码为 1）。独创**旧页码白底遮罩覆盖**（整行色带或局部小框），支持画布智能吸色匹配背景底色，彻底遮蔽原有错乱页码。
-- **电子签名与盖章 (Sign & Stamp)**：专为严肃公文与合同签署打造。支持手绘手写签名、输入文字生成签名、本地印章与签名照片上传。自研盒式低通平整算法自动去除近景拍摄阴影与纸张白底，支持原色/墨黑/深蓝/公章红重着色。支持一键将简签（Initials）批量盖印至全部页面、偶数页、奇数页或末页，配备 LocalStorage 离线印章库与预设位置。
+- **电子签名与盖章 (Sign & Stamp)**：专为严肃公文与合同签署打造。支持手绘手写签名、输入文字生成签名、本地印章与签名照片上传。自研盒式低通平整算法自动去除近景拍摄阴影与纸张白底，支持原色/墨黑/深蓝/公章红重着色。新增**智能透明留白裁切 (Auto-Trim)** 紧致字迹定界框杜绝边缘误触，自适应按真实自然比例放置圆形/方形公章防压扁变形。支持一键将简签批量盖印至全部页面、偶数页、奇数页或末页，配备 LocalStorage 离线印章库与预设位置。
 - **PDF 转图片 (PDF to Image)**：逐页将 PDF 渲染为清晰 PNG 或 JPG 图像。支持*标准 150 DPI* 与*印刷级 300 DPI* 超清画质。可在页面缩略图上直接单页下载预览，亦可一键将全册所有页面完整打包为 ZIP 归档。
-- **图片转 PDF (Image to PDF)**：将 PNG、JPG、WebP、BMP 等图片快速批量拼版合成为多页 PDF。提供标准 A4 统一画幅（支持纵横自适应与等比居中排版）以及原图比例自适应贴合模式，满足票据报销拼版与证件扫描归档。
+- **图片转 PDF / 扫描件增强 (Image to PDF)**：将 PNG、JPG、WebP、BMP 等图片快速批量拼版合成为多页 PDF。内置独创纯前端 **CamScanner 级文档扫描件增强引擎**：基于高效率 $O(W \times H)$ 照度归一化算法，一键抹平手机与手腕投影、消除纸面发黄发灰暗斑并提亮为纯白底色，提供 3 档专业滤镜（*智能彩色*保留公章红印与彩字、*高清黑白*高反差自适应锐化字迹、*清晰灰度*），支持卡片缩略图实时增白与**按住查看原图对比**。提供标准 A4 统一画幅与原图比例自适应贴合模式。
 - **加密与权限保护 (Protect & Encrypt)**：现代高强度 AES-256 原生算法加密。支持设置**打开密码 (User Password)** 限制未授权查阅，同时支持设置**所有者管理密码 (Owner Password)** 细粒度锁定操作权限（严禁未授权打印、禁止复制文本与图像、禁止表单修改与批注），确保外发合同机密安全。
 - **解密与解除限制 (Unlock & Strip Restrictions)**：永久剥离密码保护与操作权限限制。输入正确密码后，底层引擎重构文档对象流，永久清除加密字典及打印、复制、编辑权限锁，输出一份完全自由干净的明文 PDF。
 - **元数据清理 (Scrub Metadata)**：深入扫描并物理擦除 PDF 内部隐藏的所有敏感属性与底层指纹：文档标题、作者名称、制作机构、编辑软件（Word / WPS / Acrobat 等指纹）、创建与修改时间戳、相机 GPS 地理坐标、私有应用字典（PieceInfo）以及内嵌缩略图缓存，100% 杜绝痕迹泄漏。
@@ -66,7 +66,7 @@
 - **久经考验的预设流程**：
   - 📁 **招投标与涉密文档预处理**：元数据清理 → 均衡压缩 → 防泄漏水印。
   - 🛡️ **隐私脱敏与安全归档**：元数据清理 → 敏感信息/PII 规则脱敏 → AES 权限加密。
-  - 🧾 **报销票据自动打包**：多图转 A4 PDF → 按报销门户要求压缩体积。
+  - 🧾 **报销票据自动打包**：多图转 A4 PDF（自动去阴影与背景增白）→ 编排审计页码 → 按报销门户要求压缩体积 → 加印 EXPENSE REPORT 凭据水印。
   - 📑 **合同批量盖章与归档**：权限解锁 → 末页签名盖章 → 安全水印。
 - **可视化拖拽流水线编辑器**：
   - 重新排序、配置参数、增删步骤，实时节点兼容性端口校验。

From 2a37434c47363a6f3c3f4590d522c59a57542b0a Mon Sep 17 00:00:00 2001
From: gzz727 <grenguo@gmail.com>
Date: Wed, 23 Sep 2026 21:39:25 +0800
Subject: [PATCH 5/5] feat(image): implement linear-time guided filter for
 robust document shadow removal

---
 src/utils/imageProcess.js | 202 ++++++++++++++++++++++++++++++++------
 1 file changed, 174 insertions(+), 28 deletions(-)

diff --git a/src/utils/imageProcess.js b/src/utils/imageProcess.js
index 4cba2f4..e84f99e 100644
--- a/src/utils/imageProcess.js
+++ b/src/utils/imageProcess.js
@@ -323,6 +323,112 @@ export function trimTransparentCanvas(canvas, padding = 6) {
   return trimmedCanvas;
 }
 
+/**
+ * Linear-Time O(W*H) Guided Filter for Edge-Preserving Illumination Estimation
+ * 
+ * @param {Float32Array} guideAndSrc 
+ * @param {number} width 
+ * @param {number} height 
+ * @param {number} radius 
+ * @param {number} [eps=150]
+ * @returns {Float32Array}
+ */
+export function computeGuidedIlluminationMap(guideAndSrc, width, height, radius, eps = 150) {
+  const total = width * height;
+  const mean_p = computeBoxBlurGrayscale(guideAndSrc, width, height, radius);
+
+  const guideSq = new Float32Array(total);
+  for (let i = 0; i < total; i++) {
+    guideSq[i] = guideAndSrc[i] * guideAndSrc[i];
+  }
+  const mean_II = computeBoxBlurGrayscale(guideSq, width, height, radius);
+
+  const a = new Float32Array(total);
+  const b = new Float32Array(total);
+
+  for (let i = 0; i < total; i++) {
+    const mean_i = mean_p[i];
+    const variance = Math.max(0, mean_II[i] - mean_i * mean_i);
+    const aVal = variance / (variance + eps);
+    a[i] = aVal;
+    b[i] = (1 - aVal) * mean_i;
+  }
+
+  const mean_a = computeBoxBlurGrayscale(a, width, height, radius);
+  const mean_b = computeBoxBlurGrayscale(b, width, height, radius);
+
+  const out = new Float32Array(total);
+  for (let i = 0; i < total; i++) {
+    out[i] = Math.max(1, mean_a[i] * guideAndSrc[i] + mean_b[i]);
+  }
+
+  return out;
+}
+
+/**
+ * Fast Anisotropic Horizontal & Vertical Line Detector (O(W*H))
+ * Detects continuous thin lines (e.g. 1px invoice grid lines) to protect from whitening erosion.
+ */
+export function detectThinGridLines(gray, width, height, strokeDelta = 18) {
+  const total = width * height;
+  const isLine = new Uint8Array(total);
+  if (width < 6 || height < 6) return isLine;
+  const minRunLength = 6;
+
+  // Horizontal runs
+  for (let y = 1; y < height - 1; y++) {
+    const rowOffset = y * width;
+    let runStart = -1;
+
+    for (let x = 0; x < width; x++) {
+      const idx = rowOffset + x;
+      const val = gray[idx];
+      const topVal = gray[(y - 1) * width + x];
+      const botVal = gray[(y + 1) * width + x];
+      const isDarker = (topVal - val > strokeDelta) && (botVal - val > strokeDelta);
+
+      if (isDarker) {
+        if (runStart === -1) runStart = x;
+      } else {
+        if (runStart !== -1 && (x - runStart) >= minRunLength) {
+          for (let rx = runStart; rx < x; rx++) isLine[rowOffset + rx] = 1;
+        }
+        runStart = -1;
+      }
+    }
+    if (runStart !== -1 && (width - runStart) >= minRunLength) {
+      for (let rx = runStart; rx < width; rx++) isLine[rowOffset + rx] = 1;
+    }
+  }
+
+  // Vertical runs
+  for (let x = 1; x < width - 1; x++) {
+    let runStart = -1;
+
+    for (let y = 0; y < height; y++) {
+      const idx = y * width + x;
+      const val = gray[idx];
+      const leftVal = gray[y * width + (x - 1)];
+      const rightVal = gray[y * width + (x + 1)];
+      const isDarker = (leftVal - val > strokeDelta) && (rightVal - val > strokeDelta);
+
+      if (isDarker) {
+        if (runStart === -1) runStart = y;
+      } else {
+        if (runStart !== -1 && (y - runStart) >= minRunLength) {
+          for (let ry = runStart; ry < y; ry++) isLine[ry * width + x] = 1;
+        }
+        runStart = -1;
+      }
+    }
+    if (runStart !== -1 && (height - runStart) >= minRunLength) {
+      for (let ry = runStart; ry < height; ry++) isLine[ry * width + x] = 1;
+    }
+  }
+
+  return isLine;
+}
+
 /**
  * Pure algorithm function for document photo enhancement:
  * Flattens non-uniform shadows, whitens paper background, and sharpens text clarity.
@@ -344,16 +450,18 @@ export function applyDocumentEnhancement(imageData, options = {}) {
   const shadowMode = options.shadowSuppression ?? 'medium';
   const whitenStrength = options.whitenStrength ?? 0.92;
   const totalPixels = width * height;
-  const gray = new Uint8Array(totalPixels);
+  const gray = new Float32Array(totalPixels);
 
   // 1. Compute perceptual luminance
   for (let i = 0; i < totalPixels; i++) {
     const idx = i * 4;
-    gray[i] = Math.round(0.299 * data[idx] + 0.587 * data[idx + 1] + 0.114 * data[idx + 2]);
+    gray[i] = 0.299 * data[idx] + 0.587 * data[idx + 1] + 0.114 * data[idx + 2];
   }
 
-  // 2. Estimate background illumination map (low-frequency shadow gradient)
+  // 2. Estimate background illumination map (guided edge-preserving filter)
   let bgMap = null;
+  let gridLineMap = null;
+
   if (shadowMode !== 'none') {
     let radiusRatio = 0.08; // medium default
     if (shadowMode === 'low') radiusRatio = 0.04;
@@ -362,11 +470,29 @@ export function applyDocumentEnhancement(imageData, options = {}) {
     const minDim = Math.min(width, height);
     const maxAllowedRadius = Math.max(1, Math.floor(minDim / 3));
     const blurRadius = Math.max(1, Math.min(maxAllowedRadius, Math.round(minDim * radiusRatio)));
-    bgMap = computeBoxBlurGrayscale(gray, width, height, blurRadius);
+
+    // Tier 1: Text-Stroke Decoupling to avoid halo artifacts around text
+    const coarseBg = computeBoxBlurGrayscale(gray, width, height, blurRadius);
+    const guideBuffer = new Float32Array(totalPixels);
+    const inkDelta = 18;
+    for (let i = 0; i < totalPixels; i++) {
+      if (gray[i] < coarseBg[i] - inkDelta) {
+        guideBuffer[i] = coarseBg[i];
+      } else {
+        guideBuffer[i] = gray[i];
+      }
+    }
+
+    // Tier 2: Guided Illumination Filter for sharp boundary tracking
+    bgMap = computeGuidedIlluminationMap(guideBuffer, width, height, blurRadius, 150);
+
+    // Tier 3: Thin 1px grid line detection
+    gridLineMap = detectThinGridLines(gray, width, height, 16);
   }
 
-  const paperThreshold = Math.round(255 - (whitenStrength * 55)); // ~204 by default
+  const basePaperThreshold = Math.round(255 - (whitenStrength * 55)); // ~204 by default
   const bwThresholdRatio = 0.77 + ((1.0 - whitenStrength) * 0.1); // ~0.78 by default
+  const tSafe = 75;
 
   // 3. Pixel-wise illumination normalization & tone mapping
   for (let i = 0; i < totalPixels; i++) {
@@ -376,13 +502,19 @@ export function applyDocumentEnhancement(imageData, options = {}) {
     const g = data[idx + 1];
     const b = data[idx + 2];
 
-    const localBg = bgMap ? Math.max(20, bgMap[i]) : 240;
-    const ratio = gVal / localBg;
-    const normLuma = Math.min(255, Math.round(ratio * 255));
+    const localBg = bgMap ? Math.max(15, bgMap[i]) : 240;
+
+    // Noise-Regulated Soft Division in deep shadow to prevent shot noise amplification
+    const lambdaL = localBg < tSafe ? Math.pow((tSafe - localBg) / tSafe, 2) : 0;
+    const effectiveBg = localBg + lambdaL * 18.0 + 1.0;
+    const normLuma = Math.min(255, Math.round(((gVal + 1.0) / effectiveBg) * 255));
+
+    const isThinGrid = gridLineMap && gridLineMap[i] === 1;
+    const activePaperThreshold = isThinGrid ? Math.min(250, basePaperThreshold + 32) : basePaperThreshold;
 
     if (mode === 'bw') {
       // High-contrast clean black & white binary photocopy style
-      const isInk = (gVal < localBg * bwThresholdRatio) && (normLuma < 195);
+      const isInk = isThinGrid || ((gVal < localBg * bwThresholdRatio) && (normLuma < 195));
       const val = isInk ? 0 : 255;
       data[idx] = val;
       data[idx + 1] = val;
@@ -390,14 +522,14 @@ export function applyDocumentEnhancement(imageData, options = {}) {
     } else if (mode === 'grayscale') {
       // Clean normalized grayscale with whitened paper
       let val = normLuma;
-      if (normLuma >= paperThreshold) {
+      if (normLuma >= activePaperThreshold && !isThinGrid) {
         val = 255;
-      } else if (normLuma >= 175) {
-        const factor = (normLuma - 175) / (paperThreshold - 175);
+      } else if (normLuma >= 175 && !isThinGrid) {
+        const factor = (normLuma - 175) / (activePaperThreshold - 175);
         val = Math.min(255, Math.round(175 + factor * (255 - 175)));
-      } else if (normLuma < 130) {
-        // Deepen dark text strokes
-        val = Math.max(0, Math.round(normLuma * 0.85 - 10));
+      } else if (normLuma < 130 || isThinGrid) {
+        // Deepen dark text strokes and preserve thin grid lines
+        val = isThinGrid ? Math.round(normLuma * 0.75) : Math.max(0, Math.round(normLuma * 0.85 - 10));
       }
       data[idx] = val;
       data[idx + 1] = val;
@@ -406,35 +538,49 @@ export function applyDocumentEnhancement(imageData, options = {}) {
       // mode === 'color': Preserve colored seals, stamps and colored ink while whitening paper
       const maxC = Math.max(r, g, b);
       const minC = Math.min(r, g, b);
-      const isChromatic = (maxC - minC) > 26; // Noticeable chromatic color (red stamp, blue pen, logo)
+      const chromaDelta = maxC - minC;
+      const isWarmPaper = (r >= g && g >= b) && (chromaDelta < 22) && (normLuma >= 175);
+      const isChromatic = (chromaDelta > 24) && !isWarmPaper;
 
-      if (!isChromatic && (normLuma >= paperThreshold || normLuma >= 235)) {
+      if (!isChromatic && (normLuma >= activePaperThreshold || (normLuma >= 238 && !isThinGrid && chromaDelta < 18 && gVal >= 150))) {
         // Paper background: Force to clean 255 pure white
         data[idx] = 255;
         data[idx + 1] = 255;
         data[idx + 2] = 255;
-      } else if (!isChromatic && normLuma >= 180) {
+      } else if (!isChromatic && normLuma >= 180 && !isThinGrid) {
         // Smooth transition zone to pure white paper
-        const factor = (normLuma - 180) / (paperThreshold - 180);
+        const factor = (normLuma - 180) / (activePaperThreshold - 180);
         const gain = 1.0 + factor * ((255 / Math.max(1, gVal)) - 1.0);
         data[idx] = Math.min(255, Math.round(r * gain));
         data[idx + 1] = Math.min(255, Math.round(g * gain));
         data[idx + 2] = Math.min(255, Math.round(b * gain));
       } else if (isChromatic) {
-        // Colorful stamp/ink: Whiten ambient paper background behind ink without dulling color
-        const gain = Math.min(2.2, Math.max(1.0, 255 / localBg));
-        data[idx] = Math.min(255, Math.round(r * gain));
-        data[idx + 1] = Math.min(255, Math.round(g * gain));
-        data[idx + 2] = Math.min(255, Math.round(b * gain));
+        // Uniform Hue-Locked Gamut-Preserving Scaling
+        const gain = Math.min(2.2, Math.max(1.0, Math.pow(255 / effectiveBg, 0.85)));
+        let rCand = r * gain;
+        let gCand = g * gain;
+        let bCand = b * gain;
+
+        const maxCand = Math.max(rCand, gCand, bCand);
+        if (maxCand > 255) {
+          const compress = 255 / maxCand;
+          rCand *= compress;
+          gCand *= compress;
+          bCand *= compress;
+        }
+
+        data[idx] = Math.round(rCand);
+        data[idx + 1] = Math.round(gCand);
+        data[idx + 2] = Math.round(bCand);
       } else {
-        // Dark text strokes: Contrast boost to make printed/handwritten text punchy
-        if (normLuma < 130) {
-          const darken = Math.max(0.65, normLuma / 140);
+        // Dark text strokes, ink strokes, or thin grid lines
+        if (normLuma < 130 || isThinGrid) {
+          const darken = isThinGrid ? 0.75 : Math.max(0.65, normLuma / 140);
           data[idx] = Math.round(r * darken);
           data[idx + 1] = Math.round(g * darken);
           data[idx + 2] = Math.round(b * darken);
         } else {
-          const gain = Math.min(1.4, 255 / localBg);
+          const gain = Math.min(1.4, 255 / effectiveBg);
           data[idx] = Math.min(255, Math.round(r * gain));
           data[idx + 1] = Math.min(255, Math.round(g * gain));
           data[idx + 2] = Math.min(255, Math.round(b * gain));