Application Lifecycle & Process Management

/**
 * Control your application's event lifecycle
 */
interface App extends EventEmitter {
  // === Core Lifecycle Methods ===
  
  /** Returns true if Electron has finished initializing, false otherwise */
  isReady(): boolean;
  
  /** Returns a promise that is fulfilled when Electron has finished initialization */
  whenReady(): Promise<void>;
  
  /** Try to close all windows. The before-quit event will be emitted first */
  quit(): void;
  
  /** Exits immediately with exitCode. exitCode defaults to 0 */
  exit(exitCode?: number): void;
  
  /** Relaunches the app when the current instance exits */
  relaunch(options?: RelaunchOptions): void;
  
  /** Focuses on the first visible window (Linux), makes app active (macOS), focuses first window (Windows) */
  focus(options?: FocusOptions): void;
  
  // === Path and Directory Methods ===
  
  /** Returns the current application directory */
  getAppPath(): string;
  
  /** Returns a path to a special directory or file associated with name */
  getPath(name: PathName): string;
  
  /** Overrides the path to a special directory or file associated with name */
  setPath(name: string, path: string): void;
  
  /** Sets or creates a directory your app's logs which can then be manipulated with app.getPath() */
  setAppLogsPath(path?: string): void;
  
  // === Application Information Methods ===
  
  /** Returns the version of the loaded application */
  getVersion(): string;
  
  /** Returns the current application's name */
  getName(): string;
  
  /** Overrides the current application's name */
  setName(name: string): void;
  
  /** Returns the current application locale */
  getLocale(): string;
  
  /** Returns the country code of the current application locale */
  getLocaleCountryCode(): string;
  
  /** Returns the current system locale */
  getSystemLocale(): string;
  
  /** Returns the user's preferred system languages from most preferred to least preferred */
  getPreferredSystemLanguages(): string[];
  
  // === File and Icon Methods ===
  
  /** Fetches a path's associated icon */
  getFileIcon(path: string, options?: FileIconOptions): Promise<NativeImage>;
  
  // === Recent Documents Methods (macOS/Windows) ===
  
  /** Adds path to the recent documents list */
  addRecentDocument(path: string): void;
  
  /** Clears the recent documents list */
  clearRecentDocuments(): void;
  
  /** Returns an array containing documents in the most recent documents list */
  getRecentDocuments(): string[];
  
  // === Protocol Handler Methods ===
  
  /** Sets the current executable as the default handler for a protocol */
  setAsDefaultProtocolClient(protocol: string, path?: string, args?: string[]): boolean;
  
  /** Removes the app as the default handler for a protocol */
  removeAsDefaultProtocolClient(protocol: string, path?: string, args?: string[]): boolean;
  
  /** Returns whether the current executable is the default handler for a protocol */
  isDefaultProtocolClient(protocol: string, path?: string, args?: string[]): boolean;
  
  /** Returns the application name of the default handler for the protocol of a URL */
  getApplicationNameForProtocol(url: string): string;
  
  /** Returns application name, icon and path of the default handler for the protocol of a URL */
  getApplicationInfoForProtocol(url: string): Promise<ApplicationProtocolInfo>;
  
  // === Single Instance Methods ===
  
  /** Requests for permission to be the single instance and returns whether successful */
  requestSingleInstanceLock(additionalData?: Record<string, any>): boolean;
  
  /** Returns whether this instance currently holds the single instance lock */
  hasSingleInstanceLock(): boolean;
  
  /** Releases all locks that were created by requestSingleInstanceLock */
  releaseSingleInstanceLock(): void;
  
  // === Badge and Counter Methods (Linux/macOS) ===
  
  /** Sets the counter badge for current app */
  setBadgeCount(count?: number): boolean;
  
  /** Returns the current value displayed in the counter badge */
  getBadgeCount(): number;
  
  // === System Integration Methods ===
  
  /** Returns whether the current desktop environment is Unity launcher (Linux) */
  isUnityRunning(): boolean;
  
  // === Login Items Methods (macOS/Windows) ===
  
  /** Returns the app's login item settings */
  getLoginItemSettings(options?: LoginItemSettingsOptions): LoginItemSettings;
  
  /** Set the app's login item settings */
  setLoginItemSettings(settings: LoginItemSettingsOptions): void;
  
  // === Accessibility Methods (macOS/Windows) ===
  
  /** Returns true if Chrome's accessibility support is enabled */
  isAccessibilitySupportEnabled(): boolean;
  
  /** Manually enables Chrome's accessibility support */
  setAccessibilitySupportEnabled(enabled: boolean): void;
  
  // === About Panel Methods ===
  
  /** Show the app's about panel options */
  showAboutPanel(): void;
  
  /** Set the about panel options */
  setAboutPanelOptions(options: AboutPanelOptions): void;
  
  // === Emoji Panel Methods ===
  
  /** Returns whether the current OS version allows for native emoji pickers */
  isEmojiPanelSupported(): boolean;
  
  /** Show the platform's native emoji picker (macOS/Windows) */
  showEmojiPanel(): void;
  
  // === macOS Specific Methods ===
  
  /** Hides all application windows without minimizing them (macOS) */
  hide(): void;
  
  /** Returns true if the application is hidden (macOS) */
  isHidden(): boolean;
  
  /** Shows application windows after they were hidden (macOS) */
  show(): void;
  
  /** Sets the activation policy for a given app (macOS) */
  setActivationPolicy(policy: 'regular' | 'accessory' | 'prohibited'): void;
  
  /** Returns whether the application is currently running from the Applications folder (macOS) */
  isInApplicationsFolder(): boolean;
  
  /** Moves the app to the Applications folder (macOS) */
  moveToApplicationsFolder(options?: MoveToApplicationsFolderOptions): boolean;
  
  /** Returns whether Secure Keyboard Entry is enabled (macOS) */
  isSecureKeyboardEntryEnabled(): boolean;
  
  /** Set the Secure Keyboard Entry enabled state (macOS) */
  setSecureKeyboardEntryEnabled(enabled: boolean): void;
  
  /** Start accessing a security scoped resource (macOS MAS) */
  startAccessingSecurityScopedResource(bookmarkData: string): Function;
  
  // === macOS Handoff Methods ===
  
  /** Creates an NSUserActivity and sets it as the current activity (macOS) */
  setUserActivity(type: string, userInfo: any, webpageURL?: string): void;
  
  /** Returns the type of the currently running activity (macOS) */
  getCurrentActivityType(): string;
  
  /** Invalidates the current Handoff user activity (macOS) */
  invalidateCurrentActivity(): void;
  
  /** Marks the current Handoff user activity as inactive without invalidating it (macOS) */
  resignCurrentActivity(): void;
  
  /** Updates the current activity if its type matches type (macOS) */
  updateCurrentActivity(type: string, userInfo: any): void;
  
  // === Windows Specific Methods ===
  
  /** Changes the Application User Model ID to id (Windows) */
  setAppUserModelId(id: string): void;
  
  /** Adds tasks to the Tasks category of the Jump List (Windows) */
  setUserTasks(tasks: Task[]): boolean;
  
  /** Returns Jump List settings (Windows) */
  getJumpListSettings(): JumpListSettings;
  
  /** Sets or removes a custom Jump List for the application (Windows) */
  setJumpList(categories: JumpListCategory[] | null): JumpListResult;
  
  // === Linux Specific Methods ===
  
  /** Imports the certificate in pkcs12 format into the platform certificate store (Linux) */
  importCertificate(options: ImportCertificateOptions, callback: (result: number) => void): void;
  
  /** Sets a handler for client certificate request passwords (Linux) */
  setClientCertRequestPasswordHandler(handler: ClientCertPasswordHandler): void;
  
  // === System Performance Methods ===
  
  /** Disables hardware acceleration for current app */
  disableHardwareAcceleration(): void;
  
  /** Disables domain blocking for 3D APIs */
  disableDomainBlockingFor3DAPIs(): void;
  
  /** Returns memory and CPU usage statistics of all processes associated with the app */
  getAppMetrics(): ProcessMetric[];
  
  /** Returns the Graphics Feature Status from chrome://gpu/ */
  getGPUFeatureStatus(): GPUFeatureStatus;
  
  /** Returns GPU information */
  getGPUInfo(infoType: 'basic' | 'complete'): Promise<any>;
  
  // === Network Configuration Methods ===
  
  /** Configures host resolution (DNS and DNS-over-HTTPS) */
  configureHostResolver(options: HostResolverOptions): void;
  
  /** Sets the proxy settings for network requests */
  setProxy(config: ProxyConfig): Promise<void>;
  
  /** Resolves proxy information for a URL */
  resolveProxy(url: string): Promise<string>;
  
  // === Sandbox Methods ===
  
  /** Enables full sandbox mode on the app */
  enableSandbox(): void;
  
  // === Properties ===
  
  /** Returns true if Chrome's accessibility support is enabled */
  accessibilitySupportEnabled: boolean;
  
  /** Returns Menu if one has been set and null otherwise */
  applicationMenu: Menu | null;
  
  /** Returns the badge count for current app (Linux/macOS) */
  badgeCount: number;
  
  /** Command line object that allows you to read and manipulate command line arguments (Readonly) */
  readonly commandLine: CommandLine;
  
  /** Dock object for macOS, undefined on other platforms (Readonly) */
  readonly dock: Dock | undefined;
  
  /** Returns true if the app is packaged, false otherwise (Readonly) */
  readonly isPackaged: boolean;
  
  /** The current application's name */
  name: string;
  
  /** User agent string Electron will use as a global fallback */
  userAgentFallback: string;
  
  /** Returns true if app is running under ARM64 translation (macOS/Windows, Readonly) */
  readonly runningUnderARM64Translation: boolean;
}

declare const app: App;

interface AppEvents {
  /** Emitted when the application has finished basic startup */
  'will-finish-launching': () => void;
  
  /** Emitted once, when Electron has finished initializing */
  'ready': (event: Event, launchInfo?: Record<string, any> | NotificationResponse) => void;
  
  /** Emitted when all windows have been closed */
  'window-all-closed': () => void;
  
  /** Emitted before the application starts closing its windows */
  'before-quit': (event: Event) => void;
  
  /** Emitted when all windows have been closed and the application will quit */
  'will-quit': (event: Event) => void;
  
  /** Emitted when the application is quitting */
  'quit': (event: Event, exitCode: number) => void;
  
  /** Emitted when the user wants to open a file with the application (macOS) */
  'open-file': (event: Event, path: string) => void;
  
  /** Emitted when the user wants to open a URL with the application (macOS) */
  'open-url': (event: Event, url: string) => void;
  
  /** Emitted when the application is activated (macOS) */
  'activate': (event: Event, hasVisibleWindows: boolean) => void;
  
  /** Emitted when the application becomes active (macOS) */
  'did-become-active': (event: Event) => void;
  
  /** Emitted when the app is no longer active and doesn't have focus (macOS) */
  'did-resign-active': (event: Event) => void;
  
  /** Emitted during Handoff when an activity from a different device wants to be resumed (macOS) */
  'continue-activity': (event: Event, type: string, userInfo: unknown, details: ContinueActivityDetails) => void;
  
  /** Emitted during Handoff before an activity from a different device wants to be resumed (macOS) */
  'will-continue-activity': (event: Event, type: string) => void;
  
  /** Emitted during Handoff when an activity from a different device fails to be resumed (macOS) */
  'continue-activity-error': (event: Event, type: string, error: string) => void;
  
  /** Emitted during Handoff after an activity from this device was successfully resumed on another one (macOS) */
  'activity-was-continued': (event: Event, type: string, userInfo: unknown) => void;
  
  /** Emitted when Handoff is about to be resumed on another device (macOS) */
  'update-activity-state': (event: Event, type: string, userInfo: unknown) => void;
  
  /** Emitted when the user clicks the native macOS new tab button (macOS) */
  'new-window-for-tab': (event: Event) => void;
  
  /** Emitted when a browserWindow gets blurred */
  'browser-window-blur': (event: Event, window: BrowserWindow) => void;
  
  /** Emitted when a browserWindow gets focused */
  'browser-window-focus': (event: Event, window: BrowserWindow) => void;
  
  /** Emitted when a new browserWindow is created */
  'browser-window-created': (event: Event, window: BrowserWindow) => void;
  
  /** Emitted when a new webContents is created */
  'web-contents-created': (event: Event, webContents: WebContents) => void;
  
  /** Emitted when failed to verify the certificate for url */
  'certificate-error': (event: Event, webContents: WebContents, url: string, error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void;
  
  /** Emitted when a client certificate is requested */
  'select-client-certificate': (event: Event, webContents: WebContents, url: URL, certificateList: Certificate[], callback: (certificate: Certificate) => void) => void;
  
  /** Emitted when webContents wants to do basic auth */
  'login': (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void;
  
  /** Emitted whenever there is a GPU info update */
  'gpu-info-update': () => void;
  
  /** Emitted when the renderer process unexpectedly disappears */
  'render-process-gone': (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void;
  
  /** Emitted when the child process unexpectedly disappears */
  'child-process-gone': (event: Event, details: ChildProcessGoneDetails) => void;
  
  /** Emitted when Chrome's accessibility support changes (macOS/Windows) */
  'accessibility-support-changed': (event: Event, accessibilitySupportEnabled: boolean) => void;
  
  /** Emitted when Electron has created a new session */
  'session-created': (session: Session) => void;
  
  /** Emitted inside the primary instance when a second instance has been executed */
  'second-instance': (event: Event, argv: string[], workingDirectory: string, additionalData?: unknown) => void;
}

const { app, BrowserWindow } = require('electron');

// Basic application setup with comprehensive lifecycle handling
app.whenReady().then(() => {
  console.log('Electron has finished initialization');
  
  // Create main window
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    }
  });
  
  mainWindow.loadFile('index.html');
  
  // Set application info
  app.setAboutPanelOptions({
    applicationName: 'My Electron App',
    applicationVersion: '1.0.0',
    copyright: '© 2024 My Company',
    credits: 'Built with Electron'
  });
});

// Handle all major lifecycle events
app.on('window-all-closed', () => {
  // On macOS, apps typically stay active until explicitly quit
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  // On macOS, re-create window when dock icon is clicked
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

app.on('before-quit', (event) => {
  // Handle any cleanup before quit
  console.log('App is about to quit');
  // Prevent quitting if needed: event.preventDefault();
});

app.on('will-quit', (event) => {
  // Final cleanup before quit
  console.log('App will quit');
});

// Handle file opening (macOS)
app.on('open-file', (event, path) => {
  event.preventDefault();
  console.log('Opening file:', path);
  // Handle file opening logic
});

// Handle URL opening (macOS)
app.on('open-url', (event, url) => {
  event.preventDefault();
  console.log('Opening URL:', url);
  // Handle URL opening logic
});

// Handle certificate errors
app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  // Prevent having error
  event.preventDefault();
  // Verify certificate manually and trust if valid
  const isValidCertificate = verifyCertificate(certificate, url);
  callback(isValidCertificate);
});

// Single instance handling
const gotTheLock = app.requestSingleInstanceLock();

if (!gotTheLock) {
  app.quit();
} else {
  app.on('second-instance', (event, commandLine, workingDirectory, additionalData) => {
    console.log('Second instance attempted:', additionalData);
    // Someone tried to run a second instance, focus our window instead
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.focus();
    }
  });
}

// Protocol handler setup
app.setAsDefaultProtocolClient('myapp');

// Badge count (macOS/Linux)
if (process.platform === 'darwin' || process.platform === 'linux') {
  app.setBadgeCount(5); // Show notification badge
}

// macOS specific features
if (process.platform === 'darwin') {
  // Set up Handoff
  app.setUserActivity('com.myapp.editing', { documentId: '123' });
  
  app.on('continue-activity', (event, type, userInfo) => {
    console.log('Continue activity:', type, userInfo);
  });
  
  // Handle new tab creation
  app.on('new-window-for-tab', (event) => {
    // Create new tab/window
    createNewTab();
  });
}

// Windows specific features
if (process.platform === 'win32') {
  // Set App User Model ID for proper taskbar grouping
  app.setAppUserModelId('com.mycompany.myapp');
  
  // Set up Jump List
  app.setJumpList([
    {
      type: 'custom',
      name: 'Recent Projects',
      items: [
        { type: 'file', path: 'C:\\Projects\\project1.proj' },
        { type: 'file', path: 'C:\\Projects\\project2.proj' }
      ]
    }
  ]);
}

// Performance monitoring
setInterval(() => {
  const metrics = app.getAppMetrics();
  console.log('App metrics:', metrics);
}, 30000);

// GPU info monitoring
app.on('gpu-info-update', () => {
  const gpuFeatures = app.getGPUFeatureStatus();
  console.log('GPU features:', gpuFeatures);
});

interface RelaunchOptions {
  args?: string[];
  execPath?: string;
}

interface FocusOptions {
  steal?: boolean; // macOS only
}

interface FileIconOptions {
  size?: 'small' | 'normal' | 'large';
}

interface ApplicationProtocolInfo {
  icon: NativeImage;
  path: string;
  name: string;
}

interface LoginItemSettingsOptions {
  type?: 'mainAppService' | 'agentService' | 'daemonService' | 'loginItemService'; // macOS
  serviceName?: string; // macOS
  path?: string; // Windows
  args?: string[]; // Windows
  enabled?: boolean; // Windows
  name?: string; // Windows
  openAtLogin?: boolean;
  openAsHidden?: boolean; // macOS, deprecated
}

interface LoginItemSettings {
  openAtLogin: boolean;
  openAsHidden?: boolean; // macOS, deprecated
  wasOpenedAtLogin?: boolean; // macOS
  wasOpenedAsHidden?: boolean; // macOS, deprecated
  restoreState?: boolean; // macOS, deprecated
  status?: 'not-registered' | 'enabled' | 'requires-approval' | 'not-found'; // macOS
  executableWillLaunchAtLogin?: boolean; // Windows
  launchItems?: LaunchItem[]; // Windows
}

interface LaunchItem {
  name: string;
  path: string;
  args: string[];
  scope: 'user' | 'machine';
  enabled: boolean;
}

interface AboutPanelOptions {
  applicationName?: string;
  applicationVersion?: string;
  copyright?: string;
  version?: string; // macOS
  credits?: string; // macOS/Windows
  authors?: string[]; // Linux
  website?: string; // Linux
  iconPath?: string; // Linux/Windows
}

interface MoveToApplicationsFolderOptions {
  conflictHandler?: (conflictType: 'exists' | 'existsAndRunning') => boolean;
}

interface Task {
  program: string;
  arguments: string;
  title: string;
  description: string;
  iconPath: string;
  iconIndex?: number;
}

interface JumpListSettings {
  minItems: number;
  removedItems: JumpListItem[];
}

interface JumpListCategory {
  type?: 'tasks' | 'frequent' | 'recent' | 'custom';
  name?: string;
  items?: JumpListItem[];
}

interface JumpListItem {
  type?: 'task' | 'separator' | 'file';
  path?: string;
  program?: string;
  args?: string;
  title?: string;
  description?: string;
  iconPath?: string;
  iconIndex?: number;
  workingDirectory?: string;
}

type JumpListResult = 'ok' | 'error' | 'invalidSeparatorError' | 'fileTypeRegistrationError' | 'customCategoryAccessDeniedError';

interface ImportCertificateOptions {
  certificate: string; // Path for the pkcs12 file
  password: string; // Passphrase for the certificate
}

type ClientCertPasswordHandler = (params: ClientCertRequestParams) => Promise<string>;

interface ClientCertRequestParams {
  hostname: string;
  tokenName: string;
  isRetry: boolean;
}

interface ProcessMetric {
  pid: number;
  type: 'Browser' | 'Tab' | 'Utility' | 'Zygote' | 'Sandbox helper' | 'GPU' | 'Pepper Plugin' | 'Pepper Plugin Broker' | 'Unknown';
  cpu: CPUUsage;
  creationTime: number;
  memory: MemoryInfo;
  sandboxed?: boolean;
  integrityLevel?: 'low' | 'medium' | 'high' | 'unknown';
}

interface CPUUsage {
  percentCPUUsage: number;
  idleWakeupsPerSecond: number;
}

interface MemoryInfo {
  workingSetSize: number;
  peakWorkingSetSize: number;
  privateBytes?: number;
}

interface GPUFeatureStatus {
  '2d_canvas': string;
  'flash_3d': string;
  'flash_stage3d': string;
  'flash_stage3d_baseline': string;
  'gpu_compositing': string;
  'multiple_raster_threads': string;
  'native_gpu_memory_buffers': string;
  'rasterization': string;
  'video_decode': string;
  'video_encode': string;
  'vpx_decode': string;
  'webgl': string;
  'webgl2': string;
}

interface HostResolverOptions {
  enableBuiltInResolver?: boolean;
  enableHappyEyeballs?: boolean;
  secureDnsMode?: 'off' | 'automatic' | 'secure';
  secureDnsServers?: string[];
  enableAdditionalDnsQueryTypes?: boolean;
}

interface ProxyConfig {
  mode?: 'direct' | 'auto_detect' | 'pac_script' | 'fixed_servers' | 'system';
  pacScript?: string;
  proxyRules?: string;
  proxyBypassRules?: string;
}

interface ContinueActivityDetails {
  webpageURL?: string;
}

interface AuthenticationResponseDetails {
  url: URL;
}

interface AuthInfo {
  isProxy: boolean;
  scheme: string;
  host: string;
  port: number;
  realm: string;
}

interface RenderProcessGoneDetails {
  reason: 'clean-exit' | 'abnormal-exit' | 'killed' | 'crashed' | 'oom' | 'launch-failed' | 'integrity-failure';
  exitCode: number;
}

interface ChildProcessGoneDetails {
  type: 'Utility' | 'Zygote' | 'Sandbox helper' | 'GPU' | 'Pepper Plugin' | 'Pepper Plugin Broker' | 'Unknown';
  reason: 'clean-exit' | 'abnormal-exit' | 'killed' | 'crashed' | 'oom' | 'launch-failed' | 'integrity-failure';
  exitCode: number;
  serviceName?: string;
  name?: string;
}

type PathName = 
  | 'home'
  | 'appData'
  | 'assets'
  | 'userData'
  | 'sessionData'
  | 'temp'
  | 'exe'
  | 'module'
  | 'desktop'
  | 'documents'
  | 'downloads'
  | 'music'
  | 'pictures'
  | 'videos'
  | 'recent'
  | 'logs'
  | 'crashDumps';

interface CommandLine {
  hasSwitch(theSwitch: string): boolean;
  getSwitchValue(theSwitch: string): string;
  appendSwitch(theSwitch: string, value?: string): void;
  appendArgument(arg: string): void;
  removeSwitch(theSwitch: string): void;
}

interface Dock {
  bounce(type?: 'critical' | 'informational'): number;
  cancelBounce(id: number): void;
  downloadFinished(filePath: string): void;
  setBadge(text: string): void;
  getBadge(): string;
  hide(): void;
  show(): Promise<void>;
  isVisible(): boolean;
  setMenu(menu: Menu | null): void;
  getMenu(): Menu | null;
  setIcon(image: NativeImage | string): void;
}

// Re-export common Electron types
interface Event {
  preventDefault(): void;
  readonly defaultPrevented: boolean;
}

interface BrowserWindow {
  // BrowserWindow interface (referenced but not fully defined here)
}

interface WebContents {
  // WebContents interface (referenced but not fully defined here)
}

interface Session {
  // Session interface (referenced but not fully defined here)
}

interface Menu {
  // Menu interface (referenced but not fully defined here)
}

interface NativeImage {
  // NativeImage interface (referenced but not fully defined here)
}

interface Certificate {
  // Certificate interface (referenced but not fully defined here)
}

interface NotificationResponse {
  // NotificationResponse interface (referenced but not fully defined here)
}