documentation-hub 5.7.2

package/electron/memoryConfig.ts

@@ -0,0 +1,187 @@
+/**
+ * Memory Configuration for Electron Main Process
+ *
+ * Configures Node.js heap size and memory limits for document processing operations.
+ */
+
+import { app } from 'electron';
+import * as os from 'os';
+import { logger } from '../src/utils/logger';
+
+const log = logger.namespace('MemoryConfig');
+
+export interface MemoryConfiguration {
+  heapSizeMB: number;
+  maxDocumentSizeMB: number;
+  recommendedConcurrency: number;
+  systemTotalMB: number;
+  systemFreeMB: number;
+}
+
+export class MemoryConfig {
+  private static readonly MIN_HEAP_SIZE_MB = 512; // Minimum 512MB
+  private static readonly DEFAULT_HEAP_SIZE_MB = 1024; // Default 1GB
+  private static readonly MAX_HEAP_SIZE_MB = 4096; // Maximum 4GB
+
+  /**
+   * Calculate optimal heap size based on system RAM
+   */
+  static calculateHeapSize(): number {
+    const totalMemoryMB = os.totalmem() / (1024 * 1024);
+    const freeMemoryMB = os.freemem() / (1024 * 1024);
+
+    log.info(`System RAM: ${totalMemoryMB.toFixed(0)}MB total, ${freeMemoryMB.toFixed(0)}MB free`);
+
+    // Use 25% of total RAM, but cap between MIN and MAX
+    let heapSize = Math.floor(totalMemoryMB * 0.25);
+
+    // Ensure within bounds
+    heapSize = Math.max(this.MIN_HEAP_SIZE_MB, heapSize);
+    heapSize = Math.min(this.MAX_HEAP_SIZE_MB, heapSize);
+
+    // Round to nearest 256MB for cleaner numbers
+    heapSize = Math.round(heapSize / 256) * 256;
+
+    log.info(`Calculated heap size: ${heapSize}MB`);
+    return heapSize;
+  }
+
+  /**
+   * Get memory configuration
+   */
+  static getConfiguration(): MemoryConfiguration {
+    const totalMemoryMB = os.totalmem() / (1024 * 1024);
+    const freeMemoryMB = os.freemem() / (1024 * 1024);
+    const heapSizeMB = this.calculateHeapSize();
+
+    // Max document size should be roughly 1/4 of heap size to allow for processing overhead
+    const maxDocumentSizeMB = Math.floor(heapSizeMB / 4);
+
+    // Recommended concurrency based on available heap
+    // Each concurrent operation needs ~256MB minimum
+    const recommendedConcurrency = Math.max(1, Math.floor(heapSizeMB / 256));
+
+    return {
+      heapSizeMB,
+      maxDocumentSizeMB,
+      recommendedConcurrency,
+      systemTotalMB: totalMemoryMB,
+      systemFreeMB: freeMemoryMB,
+    };
+  }
+
+  /**
+   * Configure Electron app with memory settings
+   * IMPORTANT: Must be called before app.ready
+   */
+  static configureApp(): void {
+    const config = this.getConfiguration();
+
+    log.info('========================================');
+    log.info('Configuration Summary:');
+    log.info(`  System Total RAM: ${config.systemTotalMB.toFixed(0)}MB`);
+    log.info(`  System Free RAM: ${config.systemFreeMB.toFixed(0)}MB`);
+    log.info(`  Heap Size: ${config.heapSizeMB}MB`);
+    log.info(`  Max Document Size: ${config.maxDocumentSizeMB}MB`);
+    log.info(`  Recommended Concurrency: ${config.recommendedConcurrency}`);
+    log.info('========================================');
+
+    // Set heap size via V8 flags
+    // Note: These must be set before app initialization
+    try {
+      app.commandLine.appendSwitch('--js-flags', `--max-old-space-size=${config.heapSizeMB}`);
+      log.info(`✓ Set --max-old-space-size=${config.heapSizeMB}`);
+    } catch (error) {
+      log.error('✗ Failed to set heap size:', error);
+    }
+
+    // Enable GC exposure for manual garbage collection if needed
+    // Useful for cleaning up after large document operations
+    try {
+      app.commandLine.appendSwitch('--js-flags', '--expose-gc');
+      log.info('✓ Enabled garbage collection exposure');
+    } catch (error) {
+      log.warn('⚠️ Could not enable GC exposure:', error);
+    }
+
+    // Optimize garbage collection for document processing
+    // More aggressive GC to prevent memory buildup
+    try {
+      app.commandLine.appendSwitch('--js-flags', '--gc-interval=100');
+      log.info('✓ Configured aggressive garbage collection');
+    } catch (error) {
+      log.warn('⚠️ Could not configure GC interval:', error);
+    }
+  }
+
+  /**
+   * Log current memory usage
+   */
+  static logMemoryUsage(label: string = 'Current'): void {
+    const usage = process.memoryUsage();
+    const config = this.getConfiguration();
+
+    log.info(`${label} Memory Usage:`);
+    log.info(`  Heap Used: ${(usage.heapUsed / 1024 / 1024).toFixed(2)}MB`);
+    log.info(`  Heap Total: ${(usage.heapTotal / 1024 / 1024).toFixed(2)}MB`);
+    log.info(`  Heap Limit: ~${config.heapSizeMB}MB`);
+    log.info(`  External: ${(usage.external / 1024 / 1024).toFixed(2)}MB`);
+    log.info(`  RSS: ${(usage.rss / 1024 / 1024).toFixed(2)}MB`);
+
+    const percentUsed = (usage.heapUsed / (config.heapSizeMB * 1024 * 1024)) * 100;
+    if (percentUsed > 85) {
+      log.error(`🚨 CRITICAL: ${percentUsed.toFixed(1)}% of heap used!`);
+    } else if (percentUsed > 70) {
+      log.warn(`⚠️ WARNING: ${percentUsed.toFixed(1)}% of heap used`);
+    } else {
+      log.info(`✓ ${percentUsed.toFixed(1)}% of heap used`);
+    }
+  }
+
+  /**
+   * Check if system has sufficient memory for operation
+   */
+  static canProcessDocument(documentSizeMB: number): boolean {
+    const config = this.getConfiguration();
+    const usage = process.memoryUsage();
+    const usedMB = usage.heapUsed / (1024 * 1024);
+    const availableMB = config.heapSizeMB - usedMB;
+
+    // Need at least 4x document size for processing overhead
+    const requiredMB = documentSizeMB * 4;
+
+    if (availableMB < requiredMB) {
+      log.error(`🚨 Insufficient memory to process ${documentSizeMB.toFixed(2)}MB document`);
+      log.error(`   Required: ${requiredMB.toFixed(2)}MB, Available: ${availableMB.toFixed(2)}MB`);
+      return false;
+    }
+
+    log.info(`✓ Sufficient memory for ${documentSizeMB.toFixed(2)}MB document (${availableMB.toFixed(2)}MB available)`);
+    return true;
+  }
+
+  /**
+   * Get memory statistics for reporting
+   */
+  static getStats(): {
+    heapUsedMB: number;
+    heapTotalMB: number;
+    heapLimitMB: number;
+    percentUsed: number;
+    systemFreeMB: number;
+  } {
+    const usage = process.memoryUsage();
+    const config = this.getConfiguration();
+    const heapUsedMB = usage.heapUsed / (1024 * 1024);
+
+    return {
+      heapUsedMB,
+      heapTotalMB: usage.heapTotal / (1024 * 1024),
+      heapLimitMB: config.heapSizeMB,
+      percentUsed: (heapUsedMB / config.heapSizeMB) * 100,
+      systemFreeMB: config.systemFreeMB,
+    };
+  }
+}
+
+export default MemoryConfig;

package/electron/preload.ts

@@ -0,0 +1,394 @@
+import { contextBridge, ipcRenderer, IpcRendererEvent, webUtils } from 'electron';
+import type {
+  HyperlinkProcessingOptions,
+  BatchProcessingOptions,
+  BatchProgress,
+} from '../src/types/hyperlink';
+import type {
+  BackupCreateResponse,
+  BackupRestoreResponse,
+  BackupListResponse,
+  BackupDeleteResponse,
+  BackupCleanupResponse,
+  BackupVerifyResponse,
+  BackupStorageInfoResponse,
+  BackupSetConfigResponse,
+  BackupConfig,
+} from '../src/types/backup';
+import type {
+  SharePointConfig,
+  DictionarySyncStatus,
+  DictionarySyncResponse,
+  DictionaryInitResponse,
+  DictionaryCredentialsResponse,
+  SyncProgressUpdate,
+} from '../src/types/dictionary';
+import type { HyperlinkLookupResult } from './services/LocalDictionaryLookupService';
+
+const electronAPI = {
+  minimizeWindow: () => ipcRenderer.invoke('window-minimize'),
+  maximizeWindow: () => ipcRenderer.invoke('window-maximize'),
+  closeWindow: () => ipcRenderer.invoke('window-close'),
+  isMaximized: () => ipcRenderer.invoke('window-is-maximized'),
+  isFullscreen: () => ipcRenderer.invoke('window-is-fullscreen'),
+  getAppVersion: () => ipcRenderer.invoke('app-version'),
+  getPlatform: () => ipcRenderer.invoke('platform'),
+  openDevTools: () => ipcRenderer.invoke('open-dev-tools'),
+
+  // Always on top (pin window)
+  setAlwaysOnTop: (flag: boolean) => ipcRenderer.invoke('window-set-always-on-top', flag),
+  isAlwaysOnTop: () => ipcRenderer.invoke('window-is-always-on-top'),
+  onAlwaysOnTopChanged: (callback: (isOnTop: boolean) => void) => {
+    const subscription = (_event: IpcRendererEvent, isOnTop: boolean) => callback(isOnTop);
+    ipcRenderer.on('window-always-on-top-changed', subscription);
+    return () => ipcRenderer.removeListener('window-always-on-top-changed', subscription);
+  },
+
+  // File handling
+  selectDocuments: () => ipcRenderer.invoke('select-documents'),
+  processDocument: (path: string) => ipcRenderer.invoke('process-document', path),
+  showInFolder: (path: string) => ipcRenderer.invoke('show-in-folder', path),
+  openDocument: (path: string) => ipcRenderer.invoke('open-document', path),
+  getFileStats: (filePath: string) => ipcRenderer.invoke('get-file-stats', filePath),
+  restoreFromBackup: (backupPath: string, targetPath: string) =>
+    ipcRenderer.invoke('restore-from-backup', { backupPath, targetPath }),
+
+  getPathsForFiles: (files: File[]) => {
+    return files.map((file) => webUtils.getPathForFile(file));
+  },
+
+  // Export and Reporting
+  selectFolder: () => ipcRenderer.invoke('select-folder') as Promise<string | null>,
+  copyFilesToFolder: (filePaths: string[], destinationFolder: string) =>
+    ipcRenderer.invoke('copy-files-to-folder', { filePaths, destinationFolder }) as Promise<{
+      copied: number;
+      skipped: number;
+    }>,
+  getDownloadsPath: () => ipcRenderer.invoke('get-downloads-path') as Promise<string>,
+  createFolder: (folderPath: string) => ipcRenderer.invoke('create-folder', folderPath) as Promise<boolean>,
+  copyFileToFolder: (sourcePath: string, destFolder: string) =>
+    ipcRenderer.invoke('copy-file-to-folder', { sourcePath, destFolder }) as Promise<boolean>,
+  createReportZip: (folderPath: string, zipName: string) =>
+    ipcRenderer.invoke('create-report-zip', { folderPath, zipName }) as Promise<string>,
+  openOutlookEmail: (subject: string, attachmentPath: string) =>
+    ipcRenderer.invoke('open-outlook-email', { subject, attachmentPath }) as Promise<{
+      success: boolean;
+      method: 'outlook' | 'mailto';
+    }>,
+
+  // Document text extraction (for comparison views)
+  extractDocumentText: (filePath: string) =>
+    ipcRenderer.invoke('document:extract-text', filePath),
+
+  // Read file as buffer (for snapshot capture)
+  readFileAsBuffer: (filePath: string): Promise<ArrayBuffer> =>
+    ipcRenderer.invoke('file:read-buffer', filePath),
+
+  // Hyperlink processing
+  selectFiles: () => ipcRenderer.invoke('hyperlink:select-files'),
+  processHyperlinkDocument: (filePath: string, options: HyperlinkProcessingOptions) =>
+    ipcRenderer.invoke('hyperlink:process-document', { filePath, options }),
+  batchProcessDocuments: (filePaths: string[], options: BatchProcessingOptions) =>
+    ipcRenderer.invoke('hyperlink:batch-process', { filePaths, options }),
+  validateApi: (apiUrl: string) => ipcRenderer.invoke('hyperlink:validate-api', { apiUrl }),
+  callPowerAutomateApi: (
+    apiUrl: string,
+    payload: {
+      Lookup_ID: string[];
+      Hyperlinks_Checked: number;
+      Total_Hyperlinks: number;
+      First_Name: string;
+      Last_Name: string;
+      Email: string;
+    },
+    timeout?: number
+  ) => ipcRenderer.invoke('hyperlink:call-api', { apiUrl, payload, timeout }),
+  cancelOperation: (operationId: string) =>
+    ipcRenderer.invoke('hyperlink:cancel-operation', { operationId }),
+  onBatchProgress: (callback: (progress: BatchProgress) => void) => {
+    const subscription = (_event: IpcRendererEvent, progress: BatchProgress) => callback(progress);
+    ipcRenderer.on('hyperlink:batch-progress', subscription);
+    return () => ipcRenderer.removeListener('hyperlink:batch-progress', subscription);
+  },
+
+  onWindowMaximized: (callback: () => void) => {
+    const subscription = (_event: IpcRendererEvent) => callback();
+    ipcRenderer.on('window-maximized', subscription);
+    return () => ipcRenderer.removeListener('window-maximized', subscription);
+  },
+
+  onWindowUnmaximized: (callback: () => void) => {
+    const subscription = (_event: IpcRendererEvent) => callback();
+    ipcRenderer.on('window-unmaximized', subscription);
+    return () => ipcRenderer.removeListener('window-unmaximized', subscription);
+  },
+
+  onWindowFullscreen: (callback: () => void) => {
+    const subscription = (_event: IpcRendererEvent) => callback();
+    ipcRenderer.on('window-fullscreen', subscription);
+    return () => ipcRenderer.removeListener('window-fullscreen', subscription);
+  },
+
+  onWindowUnfullscreen: (callback: () => void) => {
+    const subscription = (_event: IpcRendererEvent) => callback();
+    ipcRenderer.on('window-unfullscreen', subscription);
+    return () => ipcRenderer.removeListener('window-unfullscreen', subscription);
+  },
+
+  // Export/Import
+  exportSettings: () => ipcRenderer.invoke('export-settings'),
+  importSettings: () => ipcRenderer.invoke('import-settings'),
+  saveExportData: (filePath: string, data: any) =>
+    ipcRenderer.invoke('save-export-data', { filePath, data }),
+
+  // Backup operations
+  backup: {
+    create: (documentPath: string): Promise<BackupCreateResponse> =>
+      ipcRenderer.invoke('backup:create', documentPath),
+    restore: (backupPath: string, targetPath: string): Promise<BackupRestoreResponse> =>
+      ipcRenderer.invoke('backup:restore', { backupPath, targetPath }),
+    list: (documentPath: string): Promise<BackupListResponse> =>
+      ipcRenderer.invoke('backup:list', documentPath),
+    delete: (backupPath: string): Promise<BackupDeleteResponse> =>
+      ipcRenderer.invoke('backup:delete', backupPath),
+    cleanup: (documentPath: string): Promise<BackupCleanupResponse> =>
+      ipcRenderer.invoke('backup:cleanup', documentPath),
+    cleanupAll: (): Promise<BackupCleanupResponse> =>
+      ipcRenderer.invoke('backup:cleanup-all'),
+    verify: (backupPath: string): Promise<BackupVerifyResponse> =>
+      ipcRenderer.invoke('backup:verify', backupPath),
+    getStorageInfo: (): Promise<BackupStorageInfoResponse> =>
+      ipcRenderer.invoke('backup:storage-info'),
+    setConfig: (config: Partial<BackupConfig>): Promise<BackupSetConfigResponse> =>
+      ipcRenderer.invoke('backup:set-config', config),
+  },
+
+  // Dictionary operations (Local SharePoint Dictionary)
+  dictionary: {
+    initialize: (): Promise<DictionaryInitResponse> =>
+      ipcRenderer.invoke('dictionary:initialize'),
+    configureSync: (config: SharePointConfig): Promise<{ success: boolean; error?: string }> =>
+      ipcRenderer.invoke('dictionary:configure-sync', config),
+    setCredentials: (clientSecret: string): Promise<DictionaryCredentialsResponse> =>
+      ipcRenderer.invoke('dictionary:set-credentials', clientSecret),
+    sync: (): Promise<DictionarySyncResponse> =>
+      ipcRenderer.invoke('dictionary:sync'),
+    startScheduler: (intervalHours: number): Promise<{ success: boolean; error?: string }> =>
+      ipcRenderer.invoke('dictionary:start-scheduler', intervalHours),
+    stopScheduler: (): Promise<{ success: boolean; error?: string }> =>
+      ipcRenderer.invoke('dictionary:stop-scheduler'),
+    lookup: (lookupId: string): Promise<{ success: boolean; result?: HyperlinkLookupResult; error?: string }> =>
+      ipcRenderer.invoke('dictionary:lookup', lookupId),
+    batchLookup: (lookupIds: string[]): Promise<{ success: boolean; results?: HyperlinkLookupResult[]; error?: string }> =>
+      ipcRenderer.invoke('dictionary:batch-lookup', lookupIds),
+    getStatus: (): Promise<{ success: boolean; status?: DictionarySyncStatus; error?: string }> =>
+      ipcRenderer.invoke('dictionary:get-status'),
+    // Interactive SharePoint retrieval (using browser login)
+    retrieveFromSharePoint: (fileUrl: string): Promise<{ success: boolean; entriesImported?: number; error?: string }> =>
+      ipcRenderer.invoke('dictionary:retrieve-from-sharepoint', { fileUrl }),
+    sharePointLogin: (): Promise<{ success: boolean; error?: string }> =>
+      ipcRenderer.invoke('dictionary:sharepoint-login'),
+    isSharePointAuthenticated: (): Promise<{ authenticated: boolean }> =>
+      ipcRenderer.invoke('dictionary:is-sharepoint-authenticated'),
+    onSyncProgress: (callback: (progress: SyncProgressUpdate) => void) => {
+      const subscription = (_event: IpcRendererEvent, progress: SyncProgressUpdate) => callback(progress);
+      ipcRenderer.on('dictionary:sync-progress', subscription);
+      return () => ipcRenderer.removeListener('dictionary:sync-progress', subscription);
+    },
+    onSyncComplete: (callback: (result: DictionarySyncResponse) => void) => {
+      const subscription = (_event: IpcRendererEvent, result: DictionarySyncResponse) => callback(result);
+      ipcRenderer.on('dictionary:sync-complete', subscription);
+      return () => ipcRenderer.removeListener('dictionary:sync-complete', subscription);
+    },
+  },
+
+  // Display/Monitor operations
+  display: {
+    getAllDisplays: () => ipcRenderer.invoke('display:get-all-displays'),
+    identifyMonitors: () => ipcRenderer.invoke('display:identify-monitors'),
+    openComparison: (backupPath: string, processedPath: string, monitorIndex: number) =>
+      ipcRenderer.invoke('display:open-comparison', { backupPath, processedPath, monitorIndex }),
+  },
+
+  // Auto-updater
+  checkForUpdates: () => ipcRenderer.invoke('check-for-updates'),
+  downloadUpdate: () => ipcRenderer.invoke('download-update'),
+  installUpdate: () => ipcRenderer.invoke('install-update'),
+  getCurrentVersion: () => ipcRenderer.invoke('get-app-version'),
+
+  // SharePoint update source
+  setUpdateProvider: (config: { type: 'github' | 'sharepoint'; sharePointUrl?: string }) =>
+    ipcRenderer.invoke('update:set-provider', config),
+  testSharePointConnection: (url: string) =>
+    ipcRenderer.invoke('update:test-sharepoint-connection', url),
+  sharePointLogin: () => ipcRenderer.invoke('update:sharepoint-login'),
+  sharePointLogout: () => ipcRenderer.invoke('update:sharepoint-logout'),
+
+  // Update event listeners
+  onUpdateChecking: (callback: () => void) => {
+    const subscription = (_event: IpcRendererEvent) => callback();
+    ipcRenderer.on('update-checking', subscription);
+    return () => ipcRenderer.removeListener('update-checking', subscription);
+  },
+  onUpdateAvailable: (
+    callback: (info: { version: string; releaseDate: string; releaseNotes: string }) => void
+  ) => {
+    const subscription = (_event: IpcRendererEvent, info: any) => callback(info);
+    ipcRenderer.on('update-available', subscription);
+    return () => ipcRenderer.removeListener('update-available', subscription);
+  },
+  onUpdateNotAvailable: (callback: (info: { version: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, info: any) => callback(info);
+    ipcRenderer.on('update-not-available', subscription);
+    return () => ipcRenderer.removeListener('update-not-available', subscription);
+  },
+  onUpdateError: (callback: (error: { message: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, error: any) => callback(error);
+    ipcRenderer.on('update-error', subscription);
+    return () => ipcRenderer.removeListener('update-error', subscription);
+  },
+  onUpdateDownloadProgress: (
+    callback: (progress: {
+      bytesPerSecond: number;
+      percent: number;
+      transferred: number;
+      total: number;
+    }) => void
+  ) => {
+    const subscription = (_event: IpcRendererEvent, progress: any) => callback(progress);
+    ipcRenderer.on('update-download-progress', subscription);
+    return () => ipcRenderer.removeListener('update-download-progress', subscription);
+  },
+  onUpdateDownloaded: (
+    callback: (info: { version: string; releaseNotes: string; fallbackUsed?: boolean }) => void
+  ) => {
+    const subscription = (_event: IpcRendererEvent, info: any) => callback(info);
+    ipcRenderer.on('update-downloaded', subscription);
+    return () => ipcRenderer.removeListener('update-downloaded', subscription);
+  },
+  onUpdateFallbackMode: (callback: (data: { message: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('update-fallback-mode', subscription);
+    return () => ipcRenderer.removeListener('update-fallback-mode', subscription);
+  },
+  onUpdateExtracting: (callback: (data: { message: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('update-extracting', subscription);
+    return () => ipcRenderer.removeListener('update-extracting', subscription);
+  },
+  onUpdateStatus: (callback: (data: { message: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('update-status', subscription);
+    return () => ipcRenderer.removeListener('update-status', subscription);
+  },
+
+  // Manual download
+  openUpdateInBrowser: () => ipcRenderer.invoke('open-update-in-browser'),
+
+  // Certificate Management
+  checkZscalerStatus: () => ipcRenderer.invoke('check-zscaler-status'),
+  getCertificatePath: () => ipcRenderer.invoke('get-certificate-path'),
+  getInstalledCertificates: () => ipcRenderer.invoke('get-installed-certificates'),
+  importCertificate: () => ipcRenderer.invoke('import-certificate'),
+  autoDetectCertificates: () => ipcRenderer.invoke('auto-detect-certificates'),
+  removeCertificate: (certPath: string) => ipcRenderer.invoke('remove-certificate', certPath),
+  testGitHubConnection: () => ipcRenderer.invoke('test-github-connection'),
+  openExternal: (url: string) => ipcRenderer.invoke('open-external', url),
+
+  // Event system helpers (SECURITY: restricted to allowed channels only)
+  on: (channel: string, callback: (...args: any[]) => void) => {
+    const allowedChannels = [
+      'window-maximized', 'window-unmaximized',
+      'window-fullscreen', 'window-unfullscreen',
+      'window-always-on-top-changed',
+      'hyperlink:batch-progress',
+      'dictionary:sync-progress', 'dictionary:sync-complete',
+      'update-checking', 'update-available', 'update-not-available',
+      'update-error', 'update-download-progress', 'update-downloaded',
+      'update-fallback-mode', 'update-extracting', 'update-status',
+      'update-manual-download',
+      'debug-network-request', 'debug-cert-error',
+      'debug-network-error', 'debug-tls-error',
+      'certificate-check-complete', 'certificate-configured',
+    ];
+    if (!allowedChannels.includes(channel)) {
+      console.error(`[Preload] Blocked IPC listener on disallowed channel: ${channel}`);
+      return () => {}; // no-op unsubscribe
+    }
+    const subscription = (_event: IpcRendererEvent, ...args: any[]) => callback(...args);
+    ipcRenderer.on(channel, subscription);
+    return () => ipcRenderer.removeListener(channel, subscription);
+  },
+  removeListener: (
+    channel: string,
+    callback: (event: IpcRendererEvent, ...args: any[]) => void
+  ) => {
+    // Same allowlist as on() — only permitted channels can be unsubscribed
+    const allowedChannels = [
+      'window-maximized', 'window-unmaximized',
+      'window-fullscreen', 'window-unfullscreen',
+      'window-always-on-top-changed',
+      'hyperlink:batch-progress',
+      'dictionary:sync-progress', 'dictionary:sync-complete',
+      'update-checking', 'update-available', 'update-not-available',
+      'update-error', 'update-download-progress', 'update-downloaded',
+      'update-fallback-mode', 'update-extracting', 'update-status',
+      'update-manual-download',
+      'debug-network-request', 'debug-cert-error',
+      'debug-network-error', 'debug-tls-error',
+      'certificate-check-complete', 'certificate-configured',
+    ];
+    if (!allowedChannels.includes(channel)) return;
+    ipcRenderer.removeListener(channel, callback);
+  },
+
+  // Debug events
+  onDebugNetworkRequest: (callback: (data: any) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('debug-network-request', subscription);
+    return () => ipcRenderer.removeListener('debug-network-request', subscription);
+  },
+  onDebugCertError: (callback: (data: any) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('debug-cert-error', subscription);
+    return () => ipcRenderer.removeListener('debug-cert-error', subscription);
+  },
+  onDebugNetworkError: (callback: (data: any) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('debug-network-error', subscription);
+    return () => ipcRenderer.removeListener('debug-network-error', subscription);
+  },
+  onDebugTLSError: (callback: (data: any) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('debug-tls-error', subscription);
+    return () => ipcRenderer.removeListener('debug-tls-error', subscription);
+  },
+  onUpdateManualDownload: (callback: (data: { message: string; downloadUrl: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('update-manual-download', subscription);
+    return () => ipcRenderer.removeListener('update-manual-download', subscription);
+  },
+
+  // Certificate check events (background)
+  onCertificateCheckComplete: (callback: (data: { success: boolean; error?: string; timestamp: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('certificate-check-complete', subscription);
+    return () => ipcRenderer.removeListener('certificate-check-complete', subscription);
+  },
+
+  onCertificateConfigured: (callback: (data: { message: string; certPath?: string }) => void) => {
+    const subscription = (_event: IpcRendererEvent, data: any) => callback(data);
+    ipcRenderer.on('certificate-configured', subscription);
+    return () => ipcRenderer.removeListener('certificate-configured', subscription);
+  },
+};
+
+// Expose to window using contextBridge (required for contextIsolation: true)
+// This is the correct, secure way to expose APIs to the renderer process
+contextBridge.exposeInMainWorld('electronAPI', electronAPI);
+
+// TYPE EXPORT: The ElectronAPI type is now defined in src/types/electron.ts
+// This provides a single source of truth for the API interface, shared between
+// the preload script and the renderer process.
+// Import from '@/types/electron' in renderer code for full type safety.
+