Add Kindle EPUB compatibility fixer

Introduce an optional Kindle EPUB compatibility fixer and integrate it into the ebook organization flow. Adds a new config key (ebook_kindle_fix_enabled, default false), a settings API update, and a UI toggle (visible when preferred format is EPUB). Implements src/lib/utils/epub-fixer.ts (uses adm-zip and cheerio) to apply fixes: add UTF-8 XML declarations, remove body/#bodymatter fragments from links, validate/normalize dc:language, and remove stray <img> tags without src. organize-files.processor now detects EPUB downloads, runs the fixer (produces a temp fixed EPUB), uses the fixed file for organization, logs fixes, and cleans up temporary files; fix failures are non-blocking and the original download is preserved. Adds dependencies adm-zip and @types/adm-zip and updates documentation and types/UI to expose the new setting. Also includes helper functions to detect EPUB paths in downloads.

src/app/admin/settings/lib/types.ts

@@ -115,6 +115,8 @@ export interface EbookSettings {
   // General settings (shared across sources)
   preferredFormat: string;
   autoGrabEnabled: boolean;
+  // Kindle compatibility
+  kindleFixEnabled: boolean;
 }
 
 /**

src/app/admin/settings/tabs/EbookTab/EbookTab.tsx

@@ -254,6 +254,32 @@ export function EbookTab({ ebook, onChange, onSuccess, onError, markAsSaved }: E
                 </p>
               </div>
             </div>
+
+            {/* Kindle Fix Toggle - Only shown when EPUB is selected */}
+            {(ebook.preferredFormat === 'epub' || !ebook.preferredFormat) && (
+              <div className="flex items-start gap-4 pt-2 border-t border-gray-200 dark:border-gray-700 mt-4">
+                <input
+                  type="checkbox"
+                  id="kindle-fix-enabled"
+                  checked={ebook.kindleFixEnabled ?? false}
+                  onChange={(e) => updateEbook('kindleFixEnabled', e.target.checked)}
+                  className="mt-1 h-5 w-5 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                />
+                <div className="flex-1">
+                  <label
+                    htmlFor="kindle-fix-enabled"
+                    className="block text-sm font-medium text-gray-900 dark:text-gray-100 cursor-pointer"
+                  >
+                    Fix EPUB for Kindle import
+                  </label>
+                  <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+                    Apply compatibility fixes before organizing EPUB files. Fixes encoding declarations,
+                    broken hyperlinks, invalid language tags, and orphaned image elements that can
+                    cause Kindle import failures.
+                  </p>
+                </div>
+              </div>
+            )}
           </div>
         </div>
       )}

src/app/admin/settings/tabs/EbookTab/useEbookSettings.ts

@@ -83,6 +83,7 @@ export function useEbookSettings({ ebook, onChange, onSuccess, onError, markAsSa
           baseUrl: ebook.baseUrl || 'https://annas-archive.li',
           flaresolverrUrl: ebook.flaresolverrUrl || '',
           autoGrabEnabled: ebook.autoGrabEnabled ?? true,
+          kindleFixEnabled: ebook.kindleFixEnabled ?? false,
         }),
       });
 

src/app/api/admin/settings/ebook/route.ts

@@ -14,7 +14,7 @@ export async function PUT(request: NextRequest) {
     return requireAdmin(req, async () => {
       try {
         // Parse request body - new structure with separate source toggles
-        const { annasArchiveEnabled, indexerSearchEnabled, format, baseUrl, flaresolverrUrl, autoGrabEnabled } = await request.json();
+        const { annasArchiveEnabled, indexerSearchEnabled, format, baseUrl, flaresolverrUrl, autoGrabEnabled, kindleFixEnabled } = await request.json();
 
         // Enforce: auto-grab must be false if no sources are enabled
         const effectiveAutoGrabEnabled = (annasArchiveEnabled || indexerSearchEnabled) ? (autoGrabEnabled ?? true) : false;
@@ -88,6 +88,13 @@ export async function PUT(request: NextRequest) {
             category: 'ebook',
             description: 'FlareSolverr URL for bypassing Cloudflare protection',
           },
+          // Kindle compatibility
+          {
+            key: 'ebook_kindle_fix_enabled',
+            value: kindleFixEnabled ? 'true' : 'false',
+            category: 'ebook',
+            description: 'Apply compatibility fixes to EPUB files for Kindle import',
+          },
         ];
 
         await configService.setMany(configs);

src/app/api/admin/settings/route.ts

@@ -141,6 +141,8 @@ export async function GET(request: NextRequest) {
         preferredFormat: configMap.get('ebook_sidecar_preferred_format') || 'epub',
         // Auto-grab: default true to preserve existing behavior
         autoGrabEnabled: configMap.get('ebook_auto_grab_enabled') !== 'false',
+        // Kindle compatibility fixes: default false
+        kindleFixEnabled: configMap.get('ebook_kindle_fix_enabled') === 'true',
       },
       general: {
         appName: configMap.get('app_name') || 'ReadMeABook',