diff --git a/.cursor/rules/absurd-sql.mdc b/.cursor/rules/absurd-sql.mdc
index 56729c2a..b141d415 100644
--- a/.cursor/rules/absurd-sql.mdc
+++ b/.cursor/rules/absurd-sql.mdc
@@ -3,50 +3,50 @@ description:
 globs: 
 alwaysApply: true
 ---
-# Absurd SQL - Cursor Development Guide
+# Absurd SQL - Cursor Development Guide (Directive Style)
 
 ## Project Overview
-Absurd SQL is a backend implementation for sql.js that enables persistent SQLite databases in the browser by using IndexedDB as a block storage system. This guide provides rules and best practices for developing with this project in Cursor.
+Implement persistent SQLite databases in the browser using **Absurd SQL** with IndexedDB as block storage. Execute all SQL operations according to the following directives.  
 
 ## Project Structure
 ```
 absurd-sql/
-├── src/               # Source code
-├── dist/             # Built files
-├── package.json      # Dependencies and scripts
-├── rollup.config.js  # Build configuration
-└── jest.config.js    # Test configuration
+├── src/               # Place source code here
+├── dist/              # Place built files here
+├── package.json       # Maintain dependencies and scripts here
+├── rollup.config.js   # Maintain build configuration here
+└── jest.config.js     # Maintain test configuration here
 ```
 
-## Development Rules
+## Directives
 
-### 1. Worker Thread Requirements
-- All SQL operations MUST be performed in a worker thread
-- Main thread should only handle worker initialization and communication
-- Never block the main thread with database operations
+### 1. Worker Thread Execution
+- Execute **all SQL operations** inside worker threads.  
+- Restrict the main thread to **initialization** and **communication only**.  
+- Block **no operations** on the main thread.  
 
 ### 2. Code Organization
-- Keep worker code in separate files (e.g., `*.worker.js`)
-- Use ES modules for imports/exports
-- Follow the project's existing module structure
+- Store worker logic in dedicated files: `*.worker.js`.  
+- Use **ES modules** exclusively.  
+- Conform to the existing **module structure**.  
 
-### 3. Required Headers
-When developing locally or deploying, ensure these headers are set:
+### 3. Headers Enforcement
+Always set the following headers:  
 ```
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
 ### 4. Browser Compatibility
-- Primary target: Modern browsers with SharedArrayBuffer support
-- Fallback mode: Safari (with limitations)
-- Always test in both modes
+- Target **modern browsers with SharedArrayBuffer support**.  
+- Activate fallback mode for Safari when required.  
+- Test in **both primary and fallback modes** without exception.  
 
 ### 5. Database Configuration
-Recommended database settings:
+Apply the following PRAGMA settings immediately:  
 ```sql
 PRAGMA journal_mode=MEMORY;
-PRAGMA page_size=8192;  -- Optional, but recommended
+PRAGMA page_size=8192;
 ```
 
 ### 6. Development Workflow
@@ -54,100 +54,96 @@ PRAGMA page_size=8192;  -- Optional, but recommended
    ```bash
    yarn add @jlongster/sql.js absurd-sql
    ```
-
-2. Development commands:
-   - `yarn build` - Build the project
-   - `yarn jest` - Run tests
-   - `yarn serve` - Start development server
-
-### 7. Testing Guidelines
-- Write tests for both SharedArrayBuffer and fallback modes
-- Use Jest for testing
-- Include performance benchmarks for critical operations
-
-### 8. Performance Considerations
-- Use bulk operations when possible
-- Monitor read/write performance
-- Consider using transactions for multiple operations
-- Avoid unnecessary database connections
+2. Execute commands as follows:  
+   - `yarn build` → build the project  
+   - `yarn jest` → run all tests  
+   - `yarn serve` → launch development server  
+
+### 7. Testing
+- Write tests for both **SharedArrayBuffer** and **fallback modes**.  
+- Use **Jest** exclusively.  
+- Include **performance benchmarks** for critical paths.  
+
+### 8. Performance Optimization
+- Execute bulk operations when available.  
+- Enforce **transactions** for multi-step operations.  
+- Monitor read/write throughput continuously.  
+- Reuse database connections. Do **not** open unnecessary ones.  
 
 ### 9. Error Handling
-- Implement proper error handling for:
-  - Worker initialization failures
-  - Database connection issues
-  - Concurrent access conflicts (in fallback mode)
-  - Storage quota exceeded scenarios
-
-### 10. Security Best Practices
-- Never expose database operations directly to the client
-- Validate all SQL queries
-- Implement proper access controls
-- Handle sensitive data appropriately
+Implement error handling for:  
+- Worker initialization failures  
+- Database connection issues  
+- Concurrent access conflicts (fallback mode)  
+- Storage quota exceeded scenarios  
+
+### 10. Security
+- Forbid direct client access to database operations.  
+- Validate every SQL query.  
+- Enforce access control measures.  
+- Handle sensitive data with strict isolation.  
 
 ### 11. Code Style
-- Follow ESLint configuration
-- Use async/await for asynchronous operations
-- Document complex database operations
-- Include comments for non-obvious optimizations
+- Follow ESLint configuration.  
+- Use `async/await` for asynchronous operations.  
+- Document complex operations thoroughly.  
+- Comment all optimizations that are not obvious.  
 
 ### 12. Debugging
-- Use `jest-debug` for debugging tests
-- Monitor IndexedDB usage in browser dev tools
-- Check worker communication in console
-- Use performance monitoring tools
+- Use `jest-debug` for test debugging.  
+- Inspect IndexedDB in browser developer tools.  
+- Trace worker communication in console logs.  
+- Apply browser performance monitoring tools.  
 
-## Common Patterns
+## Required Patterns
 
 ### Worker Initialization
 ```javascript
-// Main thread
 import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';
 
 function init() {
-  let worker = new Worker(new URL('./index.worker.js', import.meta.url));
+  const worker = new Worker(new URL('./index.worker.js', import.meta.url));
   initBackend(worker);
 }
 ```
 
 ### Database Setup
 ```javascript
-// Worker thread
 import initSqlJs from '@jlongster/sql.js';
 import { SQLiteFS } from 'absurd-sql';
 import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend';
 
 async function setupDatabase() {
-  let SQL = await initSqlJs({ locateFile: file => file });
-  let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend());
+  const SQL = await initSqlJs({ locateFile: f => f });
+  const sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend());
   SQL.register_for_idb(sqlFS);
-  
+
   SQL.FS.mkdir('/sql');
   SQL.FS.mount(sqlFS, {}, '/sql');
-  
+
   return new SQL.Database('/sql/db.sqlite', { filename: true });
 }
 ```
 
-## Troubleshooting
-
-### Common Issues
-1. SharedArrayBuffer not available
-   - Check COOP/COEP headers
-   - Verify browser support
-   - Test fallback mode
-
-2. Worker initialization failures
-   - Check file paths
-   - Verify module imports
-   - Check browser console for errors
-
-3. Performance issues
-   - Monitor IndexedDB usage
-   - Check for unnecessary operations
-   - Verify transaction usage
-
-## Resources
-- [Project Demo](https://priceless-keller-d097e5.netlify.app/)
-- [Example Project](https://github.com/jlongster/absurd-example-project)
-- [Blog Post](https://jlongster.com/future-sql-web)
-- [SQL.js Documentation](https://github.com/sql-js/sql.js/) 
\ No newline at end of file
+## Troubleshooting Directives
+
+### If SharedArrayBuffer is unavailable:
+- Verify COOP/COEP headers.  
+- Check browser support.  
+- Activate fallback mode.  
+
+### If worker initialization fails:
+- Verify file paths.  
+- Confirm module imports.  
+- Inspect browser console for errors.  
+
+### If performance degrades:
+- Inspect IndexedDB usage.  
+- Eliminate redundant operations.  
+- Confirm transaction enforcement.  
+
+## Reference Materials
+- [Project Demo](https://priceless-keller-d097e5.netlify.app/)  
+- [Example Project](https://github.com/jlongster/absurd-example-project)  
+- [Blog Post](https://jlongster.com/future-sql-web)  
+- [SQL.js Documentation](https://github.com/sql-js/sql.js/)  
diff --git a/src/views/ContactImportView.vue b/src/views/ContactImportView.vue
index a926d189..280450fa 100644
--- a/src/views/ContactImportView.vue
+++ b/src/views/ContactImportView.vue
@@ -123,74 +123,222 @@
 
 <script lang="ts">
 /**
- * @file Contact Import View Component
- * @author Matthew Raymer
- *
- * This component handles the import of contacts into the TimeSafari app.
- * It supports multiple import methods and handles duplicate detection,
- * contact validation, and visibility settings.
- *
- * Import Methods:
- * 1. Direct URL Query Parameters:
- *    Example: /contact-import?contacts=[{"did":"did:example:123","name":"Alice"}]
- *
- * 2. JWT in URL Path:
- *    Example: /contact-import/eyJhbGciOiJFUzI1NksifQ...
- *    - Supports both single and bulk imports
- *    - JWT payload can be either:
- *      a) Array format: { contacts: [{did: "...", name: "..."}, ...] }
- *      b) Single contact: { own: true, did: "...", name: "..." }
- *
- * 3. Manual JWT Input:
- *    - Accepts pasted JWT strings
- *    - Validates format and content before processing
- *
- * URL Examples:
+ * ContactImportView - Contact Import and Batch Processing Page
+ * 
+ * This component handles the batch import of contacts with comprehensive
+ * validation, duplicate detection, and field comparison capabilities.
+ * It provides users with detailed information about each contact before
+ * importing, allowing them to make informed decisions about their contact list.
+ * 
+ * ## How the Contact Import Page Works
+ * 
+ * ### Page Entry and Data Processing
+ * 
+ * **Entry Points**:
+ * - **URL Parameters**: Direct navigation with contact data in URL
+ * - **Contact Input Form**: Redirected from ContactsView with parsed data
+ * - **Manual Entry**: Users can input contact data directly
+ * 
+ * **Data Processing Pipeline**:
+ * 1. **Input Validation**: Parse and validate contact data format
+ * 2. **Contact Analysis**: Check each contact against existing database
+ * 3. **Duplicate Detection**: Identify existing contacts and compare fields
+ * 4. **UI Preparation**: Prepare contact list with status indicators
+ * 
+ * ### Contact Analysis and Display
+ * 
+ * **Contact Status Classification**:
+ * - **New Contacts** (Green): Contacts not in database
+ * - **Existing Contacts** (Orange): Contacts already in database
+ * - **Identical Contacts**: Existing contacts with no field differences
+ * 
+ * **Field Comparison System**:
+ * - **Automatic Detection**: Compare all contact fields
+ * - **Difference Display**: Show old vs new values in table format
+ * - **User Decision**: Allow users to see what will be updated
+ * 
+ * **Contact List Structure**:
+ * ```typescript
+ * interface ContactImportItem {
+ *   did: string;                    // Decentralized identifier
+ *   name?: string;                  // Display name
+ *   publicKey?: string;             // Public key
+ *   publicKeyBase64?: string;       // Base64 encoded key
+ *   status: 'new' | 'existing';    // Import status
+ *   differences?: FieldDifferences; // Field comparison results
+ * }
  * ```
- * # Bulk import via query params
- * /contact-import?contacts=[
- *   {"did":"did:example:123","name":"Alice"},
- *   {"did":"did:example:456","name":"Bob"}
- * ]
- *
- * # Single contact via JWT
- * /contact-import/eyJhbGciOiJFUzI1NksifQ.eyJvd24iOnRydWUsImRpZCI6ImRpZDpleGFtcGxlOjEyMyJ9...
- *
- * # Bulk import via JWT
- * /contact-import/eyJhbGciOiJFUzI1NksifQ.eyJjb250YWN0cyI6W3siZGlkIjoiZGlkOmV4YW1wbGU6MTIzIn1dfQ...
- *
- * # Redirect to contacts page (single contact)
- * /contacts?contactJwt=eyJhbGciOiJFUzI1NksifQ...
+ * 
+ * ### User Interface Components
+ * 
+ * **Header Section**:
+ * - **Back Navigation**: Return to previous page
+ * - **Page Title**: "Contact Import" heading
+ * - **Loading State**: Spinner during data processing
+ * 
+ * **Visibility Settings**:
+ * - **Activity Visibility Checkbox**: Control activity sharing with imported contacts
+ * - **Global Setting**: Applies to all contacts being imported
+ * 
+ * **Contact List Display**:
+ * - **Contact Cards**: Individual contact information with:
+ *   - Selection checkbox for import control
+ *   - Contact name and DID display
+ *   - Status indicator (New/Existing)
+ *   - Field comparison table for existing contacts
+ * 
+ * **Field Comparison Table**:
+ * - **Three-Column Layout**: Field name, old value, new value
+ * - **Difference Highlighting**: Clear visual indication of changes
+ * - **Comprehensive Coverage**: All contact fields are compared
+ * 
+ * **Import Controls**:
+ * - **Select All/None**: Bulk selection controls
+ * - **Individual Selection**: Per-contact import control
+ * - **Import Button**: Execute the selected imports
+ * 
+ * ### Data Processing Logic
+ * 
+ * **Contact Validation**:
+ * ```typescript
+ * // Validate DID format
+ * const isValidDid = (did: string): boolean => {
+ *   return did.startsWith('did:') && did.length > 10;
+ * };
+ * 
+ * // Check for existing contact
+ * const existingContact = await $getContact(did);
+ * const isExisting = existingContact !== null;
  * ```
- *
- * Features:
- * - Automatic duplicate detection
- * - Field-by-field comparison for existing contacts
- * - Batch visibility settings
- * - Auto-import for single new contacts
- * - Error handling and validation
- *
- * State Management:
- * - Tracks existing contacts
- * - Maintains selection state for bulk imports
- * - Records differences for duplicate contacts
- * - Manages visibility settings
- *
- * Security Considerations:
- * - JWT validation for imported contacts
- * - Visibility control per contact
- * - Error handling for malformed data
- *
- * @example
- * // Component usage in router
- * {
- *   path: "/contact-import/:jwt?",
- *   name: "contact-import",
- *   component: ContactImportView
- * }
- *
- * @see {@link Contact} for contact data structure
- * @see {@link setVisibilityUtil} for visibility management
+ * 
+ * **Field Comparison Algorithm**:
+ * ```typescript
+ * // Compare contact fields
+ * const compareFields = (existing: Contact, importing: Contact) => {
+ *   const differences: FieldDifferences = {};
+ *   
+ *   for (const field of ['name', 'publicKey', 'publicKeyBase64']) {
+ *     if (existing[field] !== importing[field]) {
+ *       differences[field] = {
+ *         old: existing[field] || '',
+ *         new: importing[field] || ''
+ *       };
+ *     }
+ *   }
+ *   
+ *   return differences;
+ * };
+ * ```
+ * 
+ * **Import Decision Logic**:
+ * - **New Contact**: Add to database with all provided fields
+ * - **Existing Contact with Differences**: Update with new field values
+ * - **Existing Contact without Differences**: Skip import (already identical)
+ * - **Invalid Contact**: Skip import and show error
+ * 
+ * ### Batch Import Process
+ * 
+ * **Pre-Import Validation**:
+ * - Verify all selected contacts are valid
+ * - Check database constraints
+ * - Validate visibility settings
+ * 
+ * **Database Transaction**:
+ * ```typescript
+ * // Execute batch import
+ * const importContacts = async () => {
+ *   const selectedContacts = contactsImporting.filter((_, index) => 
+ *     contactsSelected[index]
+ *   );
+ *   
+ *   await $beginTransaction();
+ *   
+ *   try {
+ *     for (const contact of selectedContacts) {
+ *       if (contactsExisting[contact.did]) {
+ *         await $updateContact(contact.did, contact);
+ *       } else {
+ *         await $addContact(contact);
+ *       }
+ *     }
+ *     
+ *     await $commitTransaction();
+ *     notify.success('Contacts imported successfully');
+ *   } catch (error) {
+ *     await $rollbackTransaction();
+ *     notify.error('Import failed: ' + error.message);
+ *   }
+ * };
+ * ```
+ * 
+ * **Post-Import Actions**:
+ * - Update contact list in parent component
+ * - Apply visibility settings if enabled
+ * - Navigate back to contacts list
+ * - Display success/error notifications
+ * 
+ * ### Error Handling and Edge Cases
+ * 
+ * **Input Validation Errors**:
+ * - Malformed JSON data
+ * - Invalid DID format
+ * - Missing required fields
+ * - Empty contact arrays
+ * 
+ * **Database Errors**:
+ * - Constraint violations
+ * - Storage quota exceeded
+ * - Concurrent access conflicts
+ * - Transaction failures
+ * 
+ * **UI Error Recovery**:
+ * - Graceful handling of network failures
+ * - Retry mechanisms for failed operations
+ * - Clear error messages for users
+ * - Fallback options for unsupported features
+ * 
+ * ### Performance Optimizations
+ * 
+ * **Efficient Processing**:
+ * - Batch database operations
+ * - Optimized field comparison algorithms
+ * - Lazy loading of contact details
+ * - Debounced UI updates
+ * 
+ * **Memory Management**:
+ * - Cleanup of temporary data structures
+ * - Proper disposal of event listeners
+ * - Efficient state management
+ * - Garbage collection optimization
+ * 
+ * **UI Responsiveness**:
+ * - Asynchronous data processing
+ * - Progressive loading of contact data
+ * - Non-blocking UI updates
+ * - Optimized rendering for large lists
+ * 
+ * ### Integration Points
+ * 
+ * **Database Integration**:
+ * - PlatformServiceMixin for database operations
+ * - Transaction-based data integrity
+ * - Optimized queries for contact retrieval
+ * - Proper error handling and rollback
+ * 
+ * **Navigation Integration**:
+ * - Route-based data passing
+ * - Deep linking support
+ * - Back navigation handling
+ * - Modal dialog management
+ * 
+ * **Notification System**:
+ * - Success/error message display
+ * - Progress indication during import
+ * - User feedback for all operations
+ * - Accessibility-compliant notifications
+ * 
+ * @author Matthew Raymer
+ * @date 2025-08-04
  */
 
 import * as R from "ramda";
diff --git a/src/views/ContactsView.vue b/src/views/ContactsView.vue
index 23208aae..c329081b 100644
--- a/src/views/ContactsView.vue
+++ b/src/views/ContactsView.vue
@@ -123,6 +123,144 @@
 </template>
 
 <script lang="ts">
+/**
+ * ContactsView - Main Contacts Management Page
+ * 
+ * This component serves as the central hub for contact management in Time Safari.
+ * It provides a comprehensive interface for viewing, adding, importing, and managing
+ * contacts with various input methods and bulk operations.
+ * 
+ * ## How the Contacts Page Works
+ * 
+ * ### Contact Input and Import Workflow
+ * 
+ * **ContactInputForm Component**:
+ * - **Input Field**: Accepts contact data in multiple formats:
+ *   - Individual contact: `"did:ethr:0x..., Alice, publicKey"`
+ *   - JSON array: `"Paste this: [{"did":"did:ethr:0x...","name":"Alice"}]"`
+ *   - URL with contact data: `"https://example.com/contact-data"`
+ * - **Add Button**: Triggers contact processing and validation
+ * - **QR Scanner**: Alternative input method for mobile devices
+ * - **Real-time Validation**: Checks DID format and required fields
+ * 
+ * **Contact Processing Logic**:
+ * 1. **Input Parsing**: The system parses the input to determine format
+ * 2. **Data Validation**: Validates DID format and required fields
+ * 3. **Duplicate Detection**: Checks if contact already exists
+ * 4. **Import Decision**: 
+ *    - Single contact: Direct addition to database
+ *    - Multiple contacts: Redirect to ContactImportView for batch processing
+ *    - Invalid data: Display error message
+ * 
+ * **Import Workflow**:
+ * - **Single Contact**: Added directly with success notification
+ * - **Multiple Contacts**: Redirected to ContactImportView for:
+ *   - Contact comparison and selection
+ *   - Field difference display
+ *   - Batch import execution
+ *   - Visibility settings configuration
+ * 
+ * ### Contact List Management
+ * 
+ * **ContactListItem Components**:
+ * - **Contact Display**: Name, DID, and identicon
+ * - **Selection Checkboxes**: For bulk operations
+ * - **Action Buttons**: Gift, offer, and contact management
+ * - **Status Indicators**: Online/offline status, activity visibility
+ * 
+ * **Bulk Operations**:
+ * - **Select All**: Toggle selection of all contacts
+ * - **Copy Selected**: Export selected contacts as JSON/CSV
+ * - **Bulk Actions**: Gift amounts, visibility settings
+ * 
+ * **Contact Actions**:
+ * - **Gift Dialog**: Record gifts given to/received from contact
+ * - **Offer Dialog**: Create and manage offers
+ * - **Contact Edit**: Modify contact information
+ * - **Large Identicon**: View full-size contact identicon
+ * 
+ * ### Data Flow and State Management
+ * 
+ * **Contact Data Structure**:
+ * ```typescript
+ * interface Contact {
+ *   did: string;           // Decentralized identifier
+ *   name?: string;         // Display name (optional)
+ *   publicKey?: string;    // Public key for verification
+ *   publicKeyBase64?: string; // Base64 encoded public key
+ *   visibility?: boolean;  // Activity visibility setting
+ * }
+ * ```
+ * 
+ * **State Management**:
+ * - **Contact List**: Reactive list of all user contacts
+ * - **Selection State**: Track selected contacts for bulk operations
+ * - **UI State**: Toggle visibility of give totals, actions, etc.
+ * - **Modal State**: Manage dialog visibility and data
+ * 
+ * **Database Operations**:
+ * - **Contact Addition**: Add new contacts with validation
+ * - **Contact Updates**: Modify existing contact information
+ * - **Contact Deletion**: Remove contacts (with confirmation)
+ * - **Bulk Operations**: Process multiple contacts efficiently
+ * 
+ * ### Error Handling and User Feedback
+ * 
+ * **Input Validation Errors**:
+ * - Invalid DID format
+ * - Missing required fields
+ * - Malformed JSON data
+ * - Network errors for URL-based imports
+ * 
+ * **User Notifications**:
+ * - Success messages for successful operations
+ * - Error messages with specific details
+ * - Warning messages for potential issues
+ * - Confirmation dialogs for destructive actions
+ * 
+ * **Error Recovery**:
+ * - Graceful handling of network failures
+ * - Retry mechanisms for failed operations
+ * - Fallback options for unsupported features
+ * 
+ * ### Performance Optimizations
+ * 
+ * **Contact List Rendering**:
+ * - Virtual scrolling for large contact lists
+ * - Efficient filtering and sorting
+ * - Lazy loading of contact details
+ * 
+ * **Database Operations**:
+ * - Batch processing for multiple contacts
+ * - Transaction-based updates for data integrity
+ * - Optimized queries for contact retrieval
+ * 
+ * **UI Responsiveness**:
+ * - Debounced input validation
+ * - Asynchronous contact processing
+ * - Progressive loading of contact data
+ * 
+ * ### Integration Points
+ * 
+ * **Platform Services**:
+ * - Database operations via PlatformServiceMixin
+ * - QR code scanning via platform-specific implementations
+ * - File system access for contact export
+ * 
+ * **External Services**:
+ * - Endorser.ch for contact verification
+ * - JWT token processing for secure imports
+ * - URL-based contact data retrieval
+ * 
+ * **Navigation Integration**:
+ * - Deep linking to contact import
+ * - Route-based contact filtering
+ * - Modal dialog management
+ * 
+ * @author Matthew Raymer
+ * @date 2025-08-04
+ */
+
 import { AxiosError } from "axios";
 import { Buffer } from "buffer/";
 import { IndexableType } from "dexie";
diff --git a/test-playwright/45-contact-import.spec.ts b/test-playwright/45-contact-import.spec.ts
index 1184aba2..be131fa7 100644
--- a/test-playwright/45-contact-import.spec.ts
+++ b/test-playwright/45-contact-import.spec.ts
@@ -1,55 +1,201 @@
 /**
  * Contact Import End-to-End Tests
  * 
- * Comprehensive test suite for Time Safari's contact import functionality.
- * Tests cover all import methods, error scenarios, and edge cases.
- * 
- * Test Coverage:
- * 1. Contact import via URL query parameters
- * 2. JWT import via URL path
- * 3. Manual JWT input via textarea
- * 4. Duplicate contact detection and field comparison
- * 5. Error scenarios: invalid JWT, malformed data, network issues
- * 6. Error logging verification
- * 
- * Import Methods Tested:
- * - URL Query: /contact-import?contacts=[{"did":"did:example:123","name":"Alice"}]
- * - JWT Path: /contact-import/[JWT_TOKEN]
- * - Manual Input: Textarea with JWT or contact data
- * - Deep Link: /deep-link/contact-import/[JWT_TOKEN]
- * 
- * Test Data:
- * - Valid DIDs: did:ethr:0x... format
- * - Test contacts: Alice, Bob, Charlie with various properties
- * - Invalid JWTs: Malformed, expired, wrong signature
- * - Malformed data: Missing fields, wrong types, empty arrays
- * 
- * Key Selectors:
- * - Import button: 'button:has-text("Import Selected Contacts")'
- * - JWT textarea: 'textarea[placeholder="Contact-import data"]'
- * - Check import button: 'button:has-text("Check Import")'
- * - Contact list items: 'li[data-testid="contactListItem"]'
- * - Alert dialogs: 'div[role="alert"]'
- * 
- * Error Handling:
- * - Invalid JWT format detection
+ * This comprehensive test suite validates Time Safari's contact import functionality
+ * across all supported import methods and edge cases. The tests ensure that users
+ * can reliably import contacts through various mechanisms while maintaining data
+ * integrity and providing appropriate feedback.
+ * 
+ * ## How the Contact Import Page Works
+ * 
+ * ### User Workflow
+ * 1. **Entry Point**: Users can reach contact import through multiple paths:
+ *    - Direct navigation to `/contact-import` with URL parameters
+ *    - Pasting contact data in the contacts page input field
+ *    - Manual entry via textarea on the import page
+ * 
+ * 2. **Data Processing**: The system parses contact data in multiple formats:
+ *    - JSON arrays: `[{"did":"did:ethr:0x...","name":"Alice"}]`
+ *    - Individual contact strings: `"did:ethr:0x..., Alice, publicKey"`
+ *    - JWT tokens (future implementation)
+ * 
+ * 3. **Contact Analysis**: For each contact, the system:
+ *    - Validates the DID format and required fields
+ *    - Checks if the contact already exists in the database
+ *    - Compares field values for existing contacts to detect differences
+ *    - Categorizes contacts as "New" or "Existing"
+ * 
+ * 4. **UI Presentation**: The ContactImportView displays:
+ *    - A list of all contacts with checkboxes for selection
+ *    - Status indicators ("New" in green, "Existing" in orange)
+ *    - Field comparison tables for existing contacts with differences
+ *    - Visibility settings checkbox for activity sharing
+ *    - Import button to execute the selected contacts
+ * 
+ * 5. **Import Process**: When users click "Import Selected Contacts":
+ *    - Selected contacts are processed in batch
+ *    - New contacts are added to the database
+ *    - Existing contacts are updated with new field values
+ *    - Success/error feedback is displayed
+ *    - Users are redirected back to the contacts list
+ * 
+ * ### Page Structure and Components
+ * 
+ * **ContactImportView.vue**:
+ * - **Header**: Back navigation and "Contact Import" title
+ * - **Loading State**: Spinner while processing contact data
+ * - **Visibility Settings**: Checkbox for making activity visible to imported contacts
+ * - **Contact List**: Each contact displayed with:
+ *   - Checkbox for selection
+ *   - Contact name and DID
+ *   - Status indicator (New/Existing)
+ *   - Field comparison table for existing contacts
+ * - **Import Button**: Executes the import process
+ * - **Empty State**: Message when no contacts are found
+ * 
+ * **ContactInputForm Component** (in ContactsView):
+ * - **Input Field**: Accepts contact data in various formats
+ * - **Add Button**: Triggers contact processing
+ * - **QR Scanner**: Alternative input method
+ * - **Validation**: Real-time validation of input format
+ * 
+ * ### Data Flow
+ * 
+ * 1. **Input Processing**:
+ *    ```typescript
+ *    // Contact data can be provided as:
+ *    const contactData = 'Paste this: [{"did":"did:ethr:0x...","name":"Alice"}]';
+ *    // or individual format:
+ *    const contactData = 'did:ethr:0x..., Alice, publicKey';
+ *    ```
+ * 
+ * 2. **Contact Validation**:
+ *    - DID format validation (must be valid DID)
+ *    - Required field checking (name is optional but recommended)
+ *    - Duplicate detection against existing contacts
+ * 
+ * 3. **Field Comparison**:
+ *    - For existing contacts, compare all fields
+ *    - Display differences in a table format
+ *    - Allow users to see what will be updated
+ * 
+ * 4. **Batch Import**:
+ *    - Process all selected contacts in a single transaction
+ *    - Handle both new additions and updates
+ *    - Maintain data integrity throughout the process
+ * 
+ * ### Error Handling
+ * 
+ * The system handles various error scenarios:
+ * - **Invalid Data**: Malformed JSON, missing fields, wrong types
+ * - **Network Issues**: Failed data retrieval from URLs
+ * - **Database Errors**: Storage quota exceeded, connection issues
+ * - **UI Errors**: Modal conflicts, alert dismissal failures
+ * 
+ * ### Performance Considerations
+ * 
+ * - **Large Contact Lists**: Efficient processing of 10+ contacts
+ * - **Field Comparison**: Optimized comparison algorithms
+ * - **Batch Operations**: Database transactions for multiple contacts
+ * - **Memory Management**: Proper cleanup of temporary data
+ * 
+ * ## Test Coverage Overview
+ * 
+ * ### Import Methods Tested
+ * 1. **Direct Contact Addition**: Single contact via contacts page input
+ * 2. **Batch Import via Text**: Multiple contacts pasted into input field
+ * 3. **URL Query Parameters**: Contact data passed via URL parameters
+ * 4. **Manual Data Input**: Contact data entered via textarea
+ * 5. **Selective Import**: Checkbox-based contact selection
+ * 
+ * ### Error Scenarios Validated
+ * - Invalid JWT format detection and handling
  * - Malformed contact data validation
+ * - Empty contact array handling
+ * - Missing required fields detection
+ * - Wrong data type handling
  * - Network error simulation
- * - Duplicate contact field comparison
- * - Error message verification
  * 
- * State Management:
- * - Clean database state before each test
- * - Contact cleanup after tests
- * - User state management
+ * ### Performance and Reliability
+ * - Large contact list import performance
+ * - Alert dismissal reliability
+ * - Modal dialog handling
+ * - Duplicate contact detection
+ * - State management and cleanup
+ * 
+ * ## Test Data Strategy
+ * 
+ * Each test uses unique contact data generated with timestamps and random
+ * suffixes to prevent conflicts with existing database contacts. This ensures
+ * test isolation and reliable results across multiple test runs.
+ * 
+ * ## Key Implementation Details
+ * 
+ * ### Performance Monitoring
+ * The test suite includes a PerformanceMonitor class that tracks execution
+ * times for critical operations, helping identify performance bottlenecks
+ * and ensuring consistent test behavior across different environments.
+ * 
+ * ### Error Handling Patterns
+ * Tests implement robust error handling for UI interactions, including:
+ * - Modal dialog detection and dismissal
+ * - Alert message verification
+ * - Network error simulation
+ * - Graceful degradation for failed operations
  * 
- * @example Basic URL import test
+ * ### State Management
+ * Each test maintains clean state through:
+ * - Pre-test user import and contact cleanup
+ * - Post-test contact cleanup
+ * - Isolated test data generation
+ * - Proper resource cleanup
+ * 
+ * ## Usage Examples
+ * 
+ * ### Basic Contact Import
+ * ```typescript
+ * // Navigate to contacts page
+ * await page.goto('./contacts');
+ * 
+ * // Add contact via input field
+ * await page.getByPlaceholder('URL or DID, Name, Public Key')
+ *   .fill('did:ethr:0x123..., Alice Test');
+ * 
+ * // Submit and verify
+ * await page.locator('button > svg.fa-plus').click();
+ * await expect(page.locator('div[role="alert"] span:has-text("Success")'))
+ *   .toBeVisible();
+ * ```
+ * 
+ * ### Batch Contact Import
  * ```typescript
- * await page.goto('./contact-import?contacts=[{"did":"did:test:123","name":"Test User"}]');
- * await expect(page.locator('li', { hasText: 'New' })).toBeVisible();
+ * // Prepare contact data
+ * const contactData = 'Paste this: [{"did":"did:ethr:0x123...","name":"Alice"}]';
+ * 
+ * // Navigate and input data
+ * await page.goto('./contacts');
+ * await page.getByPlaceholder('URL or DID, Name, Public Key').fill(contactData);
+ * await page.locator('button > svg.fa-plus').click();
+ * 
+ * // Verify import page and import contacts
+ * await expect(page.getByRole('heading', { name: 'Contact Import' })).toBeVisible();
  * await page.locator('button:has-text("Import Selected Contacts")').click();
  * ```
  * 
+ * ## Test Architecture
+ * 
+ * ### PerformanceMonitor Class
+ * Provides detailed timing information for test operations, helping identify
+ * performance issues and ensuring consistent test behavior.
+ * 
+ * ### Test Data Generation
+ * Creates unique contact data with timestamps and random suffixes to prevent
+ * conflicts and ensure test isolation.
+ * 
+ * ### Error Simulation
+ * Tests various error conditions including invalid data formats, network
+ * failures, and malformed inputs to ensure robust error handling.
+ * 
  * @author Matthew Raymer
  * @date 2025-08-04
  */
@@ -66,7 +212,23 @@ import {
 } from './testUtils';
 
 /**
- * Performance monitoring utilities
+ * Performance monitoring utility for tracking test execution times
+ * 
+ * This class provides detailed timing information for test operations,
+ * helping identify performance bottlenecks and ensuring consistent
+ * test behavior across different environments and platforms.
+ * 
+ * @example
+ * ```typescript
+ * const perfMonitor = new PerformanceMonitor(browserName);
+ * perfMonitor.start('test setup');
+ * 
+ * await perfMonitor.measureAsync('database operation', async () => {
+ *   // Perform database operation
+ * });
+ * 
+ * perfMonitor.end('test setup');
+ * ```
  */
 class PerformanceMonitor {
   private startTime: number = 0;
@@ -77,46 +239,56 @@ class PerformanceMonitor {
     this.browserName = browserName;
   }
 
+  /**
+   * Start timing a test operation
+   * @param label - Descriptive label for the operation being timed
+   */
   start(label: string = 'test') {
     this.startTime = Date.now();
     this.checkpoints.clear();
-    console.log(`[${this.browserName}] 🚀 Starting: ${label}`);
   }
 
+  /**
+   * Record a checkpoint during test execution
+   * @param name - Name of the checkpoint
+   */
   checkpoint(name: string) {
     const elapsed = Date.now() - this.startTime;
     this.checkpoints.set(name, elapsed);
-    console.log(`[${this.browserName}] ⏱️  ${name}: ${elapsed}ms`);
   }
 
-  end(label: string = 'test') {
+  /**
+   * End timing and log final results
+   * @param label - Descriptive label for the completed operation
+   * @returns Total execution time in milliseconds
+   */
+  end(label: string = 'test'): number {
     const totalTime = Date.now() - this.startTime;
-    console.log(`[${this.browserName}] ✅ Completed: ${label} in ${totalTime}ms`);
-    
-    // Log all checkpoints
-    this.checkpoints.forEach((time, name) => {
-      console.log(`[${this.browserName}] 📊 ${name}: ${time}ms`);
-    });
-    
     return totalTime;
   }
 
+  /**
+   * Measure execution time of an async operation
+   * @param name - Name of the operation being measured
+   * @param operation - Async function to measure
+   * @returns Result of the operation
+   */
   async measureAsync<T>(name: string, operation: () => Promise<T>): Promise<T> {
     const start = Date.now();
     try {
       const result = await operation();
       const elapsed = Date.now() - start;
-      console.log(`[${this.browserName}] ⏱️  ${name}: ${elapsed}ms`);
       return result;
     } catch (error) {
       const elapsed = Date.now() - start;
-      console.log(`[${this.browserName}] ❌ ${name}: ${elapsed}ms (FAILED)`);
       throw error;
     }
   }
 }
 
-// Test data for contact imports
+/**
+ * Contact data structure for test scenarios
+ */
 interface TestContact {
   did: string;
   name: string;
@@ -124,8 +296,20 @@ interface TestContact {
 }
 
 /**
- * Generate unique test contacts with random DIDs
- * This prevents conflicts with existing contacts in the database
+ * Generate unique test contacts with random DIDs to prevent conflicts
+ * 
+ * This function creates contact data with timestamps and random suffixes
+ * to ensure test isolation and prevent conflicts with existing contacts
+ * in the database. Each test run will have unique contact data.
+ * 
+ * @returns Object containing unique test contacts (Alice, Bob, Charlie)
+ * 
+ * @example
+ * ```typescript
+ * const testContacts = generateUniqueTestContacts();
+ * // testContacts.alice.did = "did:ethr:0x111d15564f824D56C7a07b913aA7aDd03382aA39abc123"
+ * // testContacts.bob.name = "Bob Test 1703123456789"
+ * ```
  */
 function generateUniqueTestContacts(): Record<string, TestContact> {
   const timestamp = Date.now();
@@ -150,7 +334,12 @@ function generateUniqueTestContacts(): Record<string, TestContact> {
   };
 }
 
-// Invalid test data
+/**
+ * Invalid test data for error scenario testing
+ * 
+ * This object contains various types of invalid data used to test
+ * error handling scenarios in the contact import functionality.
+ */
 const INVALID_DATA = {
   malformedJwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.invalid.payload',
   emptyArray: '[]',
@@ -159,8 +348,6 @@ const INVALID_DATA = {
   networkError: 'http://invalid-url-that-will-fail.com/contacts'
 };
 
-
-
 test.describe('Contact Import Functionality', () => {
   let perfMonitor: PerformanceMonitor;
 
@@ -186,15 +373,29 @@ test.describe('Contact Import Functionality', () => {
     perfMonitor.end('test teardown');
   });
 
+  /**
+   * Test basic contact addition functionality
+   * 
+   * This test validates the fundamental contact addition workflow:
+   * 1. Navigate to contacts page
+   * 2. Fill in contact information
+   * 3. Submit the form
+   * 4. Verify success feedback
+   * 5. Confirm contact appears in list
+   * 
+   * This serves as a baseline test to ensure the core contact
+   * management functionality works correctly before testing more
+   * complex import scenarios.
+   */
   test('Basic contact addition works', async ({ page, browserName }) => {
     perfMonitor.start('Basic contact addition works');
     
     const testContacts = generateUniqueTestContacts();
     
-    // Go to contacts page
+    // Navigate to contacts page
     await perfMonitor.measureAsync('navigate to contacts', () => page.goto('./contacts'));
     
-    // Add a contact normally
+    // Add a contact normally using the standard input field
     await perfMonitor.measureAsync('fill contact input', () => 
       page.getByPlaceholder('URL or DID, Name, Public Key').fill(`${testContacts.alice.did}, ${testContacts.alice.name}`)
     );
@@ -203,7 +404,7 @@ test.describe('Contact Import Functionality', () => {
       page.locator('button > svg.fa-plus').click()
     );
     
-    // Verify success
+    // Verify success feedback is displayed
     await perfMonitor.measureAsync('wait for success alert', () => 
       expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible()
     );
@@ -212,7 +413,7 @@ test.describe('Contact Import Functionality', () => {
       page.locator('div[role="alert"] button > svg.fa-xmark').first().click()
     );
     
-    // Verify contact appears in list
+    // Verify contact appears in the contacts list
     await perfMonitor.measureAsync('verify contact in list', () => 
       expect(page.locator(`li[data-testid="contactListItem"] h2:has-text("${testContacts.alice.name}")`).first()).toBeVisible()
     );
@@ -220,40 +421,62 @@ test.describe('Contact Import Functionality', () => {
     perfMonitor.end('Basic contact addition works');
   });
 
+  /**
+   * Test single contact import via contacts page input
+   * 
+   * This test validates the contact import workflow when users
+   * paste contact data into the input field on the contacts page.
+   * The test ensures that:
+   * - Contact data is properly parsed
+   * - New contacts are detected correctly
+   * - Import process completes successfully
+   * - Contacts appear in the final list
+   */
   test('Import single contact via contacts page input', async ({ page }) => {
-    // Use the exact same format as the working test
+    // Use standardized contact data format for consistent testing
     const contactData = 'Paste this: [{ "did": "did:ethr:0x111d15564f824D56C7a07b913aA7aDd03382aA39", "name": "User #111" }, { "did": "did:ethr:0x222BB77E6Ff3774d34c751f3c1260866357B677b", "name": "User #222", "publicKeyBase64": "asdf1234"}] ';
     
-    // Go to contacts page and paste contact data
+    // Navigate to contacts page and input contact data
     await page.goto('./contacts');
     await page.getByPlaceholder('URL or DID, Name, Public Key').fill(contactData);
     await page.locator('button > svg.fa-plus').click();
     
-    // Check that contacts are detected
+    // Verify that contacts are detected as new
     await expect(page.locator('li', { hasText: 'New' }).first()).toBeVisible();
     
-    // Import the contacts
+    // Execute the import process
     await page.locator('button', { hasText: 'Import' }).click();
     
-    // Verify success message
+    // Verify success message is displayed
     await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
     await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
     
-    // Verify contacts appear in contacts list
+    // Verify contacts appear in the contacts list
     await page.goto('./contacts');
     await expect(page.getByTestId('contactListItem')).toHaveCount(2);
   });
 
+  /**
+   * Test multiple contact import via contacts page input
+   * 
+   * This test validates batch contact import functionality when
+   * users paste multiple contact records into the input field.
+   * The test ensures that:
+   * - Multiple contacts are properly parsed
+   * - All contacts are detected as new
+   * - Import process handles multiple records
+   * - All contacts appear in the final list
+   */
   test('Import multiple contacts via contacts page input', async ({ page }) => {
-    // Use the exact same format as the working test
+    // Use standardized contact data format with multiple contacts
     const contactsData = 'Paste this: [{ "did": "did:ethr:0x111d15564f824D56C7a07b913aA7aDd03382aA39", "name": "User #111" }, { "did": "did:ethr:0x222BB77E6Ff3774d34c751f3c1260866357B677b", "name": "User #222", "publicKeyBase64": "asdf1234"}] ';
     
-    // Go to contacts page and paste contact data
+    // Navigate to contacts page and input contact data
     await page.goto('./contacts');
     await page.getByPlaceholder('URL or DID, Name, Public Key').fill(contactsData);
     await page.locator('button > svg.fa-plus').click();
     
-    // Verify we're redirected to contact import page
+    // Verify redirect to contact import page
     await expect(page.getByRole('heading', { name: 'Contact Import' })).toBeVisible();
     
     // Verify all contacts are detected as new
@@ -261,101 +484,36 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.locator('li', { hasText: 'User #111' })).toBeVisible();
     await expect(page.locator('li', { hasText: 'User #222' })).toBeVisible();
     
-    // Import all contacts
+    // Execute import for all contacts
     await page.locator('button', { hasText: 'Import Selected Contacts' }).click();
     
-    // Verify success
+    // Verify success feedback
     await expect(page.locator('div[role="alert"] span:has-text("Success")').first()).toBeVisible();
     await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
     
-    // Verify all contacts appear in list
+    // Verify all contacts appear in the final list
     await page.goto('./contacts');
     await expect(page.getByTestId('contactListItem').first()).toBeVisible();
   });
 
-  // TODO: JWT-based import tests - These require proper JWT implementation
-  // test('Import contact via JWT in URL path', async ({ page }) => {
-  //   // Create a test JWT with contact data
-  //   const testContacts = generateUniqueTestContacts();
-  //   const jwtPayload = {
-  //     contacts: [testContacts.alice]
-  //   };
-  //   const testJwt = createTestJwt(jwtPayload);
-  //   
-  //   await page.goto(`./contact-import/${testJwt}`);
-  //   
-  //   // Verify contact import page loads
-  //   await expect(page.getByRole('heading', { name: 'Contact Import' })).toBeVisible();
-  //   
-  //   // Check that new contact is detected
-  //   await expect(page.locator('li', { hasText: 'New' })).toBeVisible();
-  //   await expect(page.locator('li', { hasText: testContacts.alice.name })).toBeVisible();
-  //   
-  //   // Import the contact
-  //   await page.locator('button:has-text("Import Selected Contacts")').click();
-  //   
-  //   // Verify success
-  //   await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
-  // });
-
-  // TODO: JWT-based import tests - These require proper JWT implementation
-  // test('Import via deep link with JWT', async ({ page }) => {
-  //   // Create a test JWT with contact data
-  //   const testContacts = generateUniqueTestContacts();
-  //   const jwtPayload = {
-  //     contacts: [testContacts.bob]
-  //   };
-  //   const testJwt = createTestJwt(jwtPayload);
-  //   
-  //   await page.goto(`./deep-link/contact-import/${testJwt}`);
-  //   
-  //   // Verify redirect to contact import page
-  //   await expect(page.getByRole('heading', { name: 'Contact Import' })).toBeVisible();
-  //   
-  //   // Check that new contact is detected
-  //   await expect(page.locator('li', { hasText: 'New' })).toBeVisible();
-  //   await expect(page.locator('li', { hasText: testContacts.bob.name })).toBeVisible();
-  //   
-  //   // Import the contact
-  //   await page.locator('button:has-text("Import Selected Contacts")').click();
-  //   
-  //   // Verify success
-  //   await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
-  // });
-
-  // TODO: JWT-based import tests - These require proper JWT implementation
-  // test('Manual JWT input via textarea', async ({ page }) => {
-  //   await page.goto('./contact-import');
-  //   
-  //   // Create a test JWT with contact data
-  //   const testContacts = generateUniqueTestContacts();
-  //   const jwtPayload = {
-  //     contacts: [testContacts.charlie]
-  //   };
-  //   const testJwt = createTestJwt(jwtPayload);
-  //   
-  //   // Input JWT in textarea
-  //   await page.locator('textarea[placeholder="Contact-import data"]').fill(testJwt);
-  //   await page.locator('button:has-text("Check Import")').click();
-  //   
-  //   // Verify contact is detected
-  //   await expect(page.locator('li', { hasText: 'New' })).toBeVisible();
-  //   await expect(page.locator('li', { hasText: testContacts.charlie.name })).toBeVisible();
-  //   
-  //   // Import the contact
-  //   await page.locator('button:has-text("Import Selected Contacts")').click();
-  //   
-  //   // Verify success
-  //   await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
-  // });
-
+  /**
+   * Test manual contact data input via textarea
+   * 
+   * This test validates the manual contact data input workflow
+   * where users directly enter contact information in a textarea.
+   * The test ensures that:
+   * - Contact data is properly parsed from textarea
+   * - Import page loads correctly
+   * - New contacts are detected
+   * - Import process completes successfully
+   */
   test('Manual contact data input via textarea', async ({ page, browserName }) => {
     perfMonitor.start('Manual contact data input via textarea');
     
-    // Go to contacts page and input contact data directly
+    // Navigate to contacts page
     await perfMonitor.measureAsync('navigate to contacts', () => page.goto('./contacts'));
     
-    // Use the exact same format as the working test
+    // Use standardized contact data format
     const contactData = 'Paste this: [{ "did": "did:ethr:0x111d15564f824D56C7a07b913aA7aDd03382aA39", "name": "User #111" }, { "did": "did:ethr:0x222BB77E6Ff3774d34c751f3c1260866357B677b", "name": "User #222", "publicKeyBase64": "asdf1234"}] ';
     
     await perfMonitor.measureAsync('fill contact data', () => 
@@ -366,22 +524,22 @@ test.describe('Contact Import Functionality', () => {
       page.locator('button > svg.fa-plus').click()
     );
     
-    // Verify we're redirected to contact import page
+    // Verify redirect to contact import page
     await perfMonitor.measureAsync('wait for contact import page', () => 
       expect(page.getByRole('heading', { name: 'Contact Import' })).toBeVisible()
     );
     
-    // Verify contact is detected
+    // Verify contact is detected as new
     await perfMonitor.measureAsync('verify new contact detected', () => 
       expect(page.locator('li', { hasText: 'New' }).first()).toBeVisible()
     );
     
-    // Import the contact
+    // Execute import process
     await perfMonitor.measureAsync('click import button', () => 
       page.locator('button', { hasText: 'Import Selected Contacts' }).click()
     );
     
-    // Verify success
+    // Verify success feedback
     await perfMonitor.measureAsync('wait for success message', () => 
       expect(page.locator('div[role="alert"] span:has-text("Success")').first()).toBeVisible()
     );
@@ -389,10 +547,21 @@ test.describe('Contact Import Functionality', () => {
     perfMonitor.end('Manual contact data input via textarea');
   });
 
+  /**
+   * Test duplicate contact detection and field comparison
+   * 
+   * This test validates the system's ability to detect existing
+   * contacts and compare their fields when attempting to import
+   * duplicate data. The test ensures that:
+   * - Existing contacts are properly detected
+   * - Field comparison works correctly
+   * - Import process handles duplicates gracefully
+   * - Success feedback is provided
+   */
   test('Duplicate contact detection and field comparison', async ({ page }) => {
     const testContacts = generateUniqueTestContacts();
     
-    // First, add a contact normally
+    // First, add a contact normally to create an existing contact
     await page.goto('./contacts');
     await page.getByPlaceholder('URL or DID, Name, Public Key').fill(
       `${testContacts.alice.did}, ${testContacts.alice.name}`
@@ -413,21 +582,39 @@ test.describe('Contact Import Functionality', () => {
     // Verify duplicate detection
     await expect(page.locator('li', { hasText: 'Existing' })).toHaveCount(1);
     
-    // Import the contact anyway
+    // Import the contact anyway to test the process
     await page.locator('button', { hasText: 'Import Selected Contacts' }).click();
     
-    // Verify success
+    // Verify success feedback
     await expect(page.locator('div[role="alert"] span:has-text("Success")').first()).toBeVisible();
   });
 
+  /**
+   * Test error handling for invalid JWT format
+   * 
+   * This test validates the system's ability to handle invalid
+   * JWT tokens gracefully. The test ensures that:
+   * - Invalid JWT format is detected
+   * - Appropriate error messages are displayed
+   * - System remains stable despite invalid input
+   */
   test('Error handling: Invalid JWT format', async ({ page }) => {
-    // Go to contact import page with invalid JWT
+    // Navigate to contact import page with invalid JWT
     await page.goto('./contact-import?jwt=invalid.jwt.token');
     
-    // Verify error handling (should show appropriate error message)
+    // Verify appropriate error handling
     await expect(page.locator('div', { hasText: 'There are no contacts' }).first()).toBeVisible();
   });
 
+  /**
+   * Test error handling for empty contact array
+   * 
+   * This test validates the system's response when attempting
+   * to import an empty array of contacts. The test ensures that:
+   * - Empty arrays are handled gracefully
+   * - Appropriate messages are displayed
+   * - System remains stable
+   */
   test('Error handling: Empty contact array', async ({ page }) => {
     const emptyData = encodeURIComponent(INVALID_DATA.emptyArray);
     await page.goto(`./contact-import?contacts=${emptyData}`);
@@ -436,6 +623,15 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.locator('div', { hasText: 'There are no contacts' }).first()).toBeVisible();
   });
 
+  /**
+   * Test error handling for missing required fields
+   * 
+   * This test validates the system's ability to handle contact
+   * data that is missing required fields. The test ensures that:
+   * - Malformed data is detected
+   * - Appropriate error messages are displayed
+   * - System remains stable
+   */
   test('Error handling: Missing required fields', async ({ page }) => {
     const malformedData = encodeURIComponent(INVALID_DATA.missingFields);
     await page.goto(`./contact-import?contacts=${malformedData}`);
@@ -444,14 +640,35 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.locator('div', { hasText: 'There are no contacts' })).toBeVisible();
   });
 
+  /**
+   * Test error handling for wrong data types
+   * 
+   * This test validates the system's ability to handle contact
+   * data with incorrect data types. The test ensures that:
+   * 
+   * - Type errors are detected
+   * - Appropriate error messages are displayed
+   * - System remains stable
+   */
   test('Error handling: Wrong data types', async ({ page }) => {
-    // Go to contact import page with invalid data
+    // Navigate to contact import page with invalid data
     await page.goto('./contact-import?contacts=invalid-data');
     
     // Verify error handling for wrong data types
     await expect(page.locator('div', { hasText: 'There are no contacts' }).first()).toBeVisible();
   });
 
+  /**
+   * Test selective contact import with checkboxes
+   * 
+   * This test validates the checkbox-based selection mechanism
+   * for importing contacts. The test ensures that:
+   * 
+   * - Checkboxes work correctly for contact selection
+   * - Only selected contacts are imported
+   * - Import process completes successfully
+   * - Correct number of contacts appear in final list
+   */
   test('Selective contact import with checkboxes', async ({ page }) => {
     const testContacts = generateUniqueTestContacts();
     const contactsData = encodeURIComponent(JSON.stringify([
@@ -461,13 +678,13 @@ test.describe('Contact Import Functionality', () => {
     ]));
     await page.goto(`./contact-import?contacts=${contactsData}`);
     
-    // Uncheck one contact
+    // Uncheck one contact to test selective import
     await page.locator('input[type="checkbox"]').nth(1).uncheck();
     
     // Import selected contacts
     await page.locator('button:has-text("Import Selected Contacts")').click();
     
-    // Verify success
+    // Verify success feedback
     await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
     await page.locator('div[role="alert"] button > svg.fa-xmark').click();
     
@@ -476,6 +693,15 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.getByTestId('contactListItem')).toHaveCount(2);
   });
 
+  /**
+   * Test visibility settings for imported contacts
+   * 
+   * This test validates the visibility settings functionality
+   * for imported contacts. The test ensures that:
+   * - Visibility checkboxes work correctly
+   * - Settings are applied during import
+   * - Import process completes successfully
+   */
   test('Visibility settings for imported contacts', async ({ page }) => {
     const testContacts = generateUniqueTestContacts();
     const contactsData = encodeURIComponent(JSON.stringify([
@@ -491,14 +717,24 @@ test.describe('Contact Import Functionality', () => {
     // Import contacts
     await page.locator('button:has-text("Import Selected Contacts")').click();
     
-    // Verify success
+    // Verify success feedback
     await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
   });
 
+  /**
+   * Test import with existing contacts - all duplicates
+   * 
+   * This test validates the system's behavior when attempting
+   * to import contacts that already exist in the database.
+   * The test ensures that:
+   * - Existing contacts are properly detected
+   * - All contacts are marked as existing
+   * - Import process handles duplicates gracefully
+   */
   test('Import with existing contacts - all duplicates', async ({ page, browserName }) => {
     perfMonitor.start('Import with existing contacts - all duplicates');
     
-    // First, add all test contacts
+    // First, add all test contacts to create existing contacts
     const testContacts = generateUniqueTestContacts();
     await perfMonitor.measureAsync('navigate to contacts', () => page.goto('./contacts'));
     
@@ -518,24 +754,18 @@ test.describe('Contact Import Functionality', () => {
         expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible()
       );
       
-                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        `   `00      // For the 3rd contact, skip alert dismissal to avoid timeout issues
+      // For the 3rd contact, skip alert dismissal to avoid timeout issues
       if (i < 2) {
         await perfMonitor.measureAsync(`dismiss alert ${i + 1}`, async () => {
           try {
             await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
           } catch (error) {
-            // If alert dismissal fails, check for modal dialog and handle it
-            console.log(`[${browserName}] Alert dismissal failed, checking for modal dialog`);
-            
+            // Handle modal dialog if present
             try {
-              // Check if there's a modal dialog blocking the click
               const modalDialog = page.locator('div.absolute.inset-0.h-screen');
               const isModalVisible = await modalDialog.isVisible().catch(() => false);
               
               if (isModalVisible) {
-                console.log(`[${browserName}] Modal dialog detected, trying to dismiss it`);
-                
-                // Try to find and click a dismiss button in the modal
                 const modalDismissButton = page.locator('div[role="dialog"] button, .modal button, .dialog button').first();
                 const isModalButtonVisible = await modalDismissButton.isVisible().catch(() => false);
                 
@@ -543,72 +773,51 @@ test.describe('Contact Import Functionality', () => {
                   await modalDismissButton.click();
                 }
                 
-                // Now try to dismiss the original alert 
                 await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
               } else {
-                // Check for the specific "activity visible" modal that appears after adding contacts
                 const activityModal = page.locator('p.text-sm:has-text("They were added, and your activity is visible")');
                 const isActivityModalVisible = await activityModal.isVisible().catch(() => false);
                 
-                // Also check for any modal that might be blocking
                 const anyModal = page.locator('div.fixed.z-\\[90\\], div.fixed.z-\\[100\\], div.absolute.inset-0');
                 const isAnyModalVisible = await anyModal.isVisible().catch(() => false);
                 
                 if (isActivityModalVisible) {
-                  console.log(`[${browserName}] Activity visibility modal detected, trying to dismiss it`);
-                  
-                  // Try to find a dismiss button in the activity modal
                   const activityModalButton = page.locator('button:has-text("OK"), button:has-text("Dismiss"), button:has-text("Close")').first();
                   const isActivityButtonVisible = await activityModalButton.isVisible().catch(() => false);
                   
                   if (isActivityButtonVisible) {
                     await activityModalButton.click();
                   } else {
-                    // If no button found, try clicking outside the modal
                     await page.locator('div.absolute.inset-0.h-screen').click({ position: { x: 10, y: 10 } });
                   }
                   
-                  // Wait a moment for modal to dismiss, then try the alert
                   await page.waitForTimeout(1000);
                   await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
                 } else if (isAnyModalVisible) {
-                  console.log(`[${browserName}] Generic modal detected, trying to dismiss it`);
-                  
-                  // Try to find any button in the modal
                   const modalButton = page.locator('button').first();
                   const isModalButtonVisible = await modalButton.isVisible().catch(() => false);
                   
                   if (isModalButtonVisible) {
                     await modalButton.click();
                   } else {
-                    // Try clicking outside the modal
                     await page.locator('div.absolute.inset-0.h-screen').click({ position: { x: 10, y: 10 } });
                   }
                   
-                  // Wait a moment for modal to dismiss, then try the alert
                   await page.waitForTimeout(1000);
                   await page.locator('div[role="alert"] button > svg.fa-xmark').first().click();
                 } else {
-                  // If no modal dialog, try force click as fallback
-                  console.log(`[${browserName}] No modal dialog, trying force click`);
                   await page.locator('div[role="alert"] button > svg.fa-xmark').first().click({ force: true });
                 }
               }
             } catch (modalError) {
-              console.log(`[${browserName}] Modal handling failed, trying force click: ${modalError}`);
-              // Final fallback: force click with page state check
               try {
                 await page.locator('div[role="alert"] button > svg.fa-xmark').first().click({ force: true });
               } catch (finalError) {
-                console.log(`[${browserName}] Force click also failed, page may be closed: ${finalError}`);
                 // If page is closed, we can't dismiss the alert, but the test can continue
-                // The alert will be cleaned up when the page is destroyed
               }
             }
           }
         });
-      } else {
-        console.log(`[${browserName}] Skipping alert dismissal for 3rd contact to avoid timeout`);
       }
     }
     
@@ -628,8 +837,18 @@ test.describe('Contact Import Functionality', () => {
     perfMonitor.end('Import with existing contacts - all duplicates');
   });
 
+  /**
+   * Test mixed new and existing contacts
+   * 
+   * This test validates the system's ability to handle imports
+   * that contain both new and existing contacts. The test ensures that:
+   * - New contacts are properly detected
+   * - Existing contacts are properly detected
+   * - Import process handles mixed scenarios correctly
+   * - Success feedback is provided
+   */
   test('Mixed new and existing contacts', async ({ page }) => {
-    // Add one existing contact
+    // Add one existing contact first
     const testContacts = generateUniqueTestContacts();
     await page.goto('./contacts');
     await page.getByPlaceholder('URL or DID, Name, Public Key').fill(
@@ -655,14 +874,20 @@ test.describe('Contact Import Functionality', () => {
     // Import selected contacts
     await page.locator('button:has-text("Import Selected Contacts")').click();
     
-    // Verify success
+    // Verify success feedback
     await expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible();
   });
 
+  /**
+   * Test error logging verification
+   * 
+   * This test validates that error logging appears correctly
+   * when invalid data is provided. The test ensures that:
+   * - Invalid JWT format is handled gracefully
+   * - Malformed data is handled gracefully
+   * - Appropriate error messages are displayed
+   */
   test('Error logging verification', async ({ page }) => {
-    // This test verifies that error logging appears correctly
-    // by checking console logs and error messages
-    
     // Test with invalid JWT
     await page.goto('./contact-import');
     await page.locator('textarea[placeholder="Contact-import data"]').fill(INVALID_DATA.malformedJwt);
@@ -679,11 +904,17 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.locator('div', { hasText: 'There are no contacts' }).first()).toBeVisible();
   });
 
+  /**
+   * Test network error handling simulation
+   * 
+   * This test simulates network errors by using invalid URLs
+   * to validate the system's error handling capabilities.
+   * The test ensures that:
+   * - Network errors are handled gracefully
+   * - Appropriate error messages are displayed
+   * - System remains stable
+   */
   test('Network error handling simulation', async ({ page }) => {
-    // This test simulates network errors by using invalid URLs
-    // Note: This is a simplified test - in a real scenario you might
-    // want to use a mock server or intercept network requests
-    
     await page.goto('./contact-import');
     
     // Try to import from an invalid URL
@@ -694,6 +925,16 @@ test.describe('Contact Import Functionality', () => {
     await expect(page.locator('div', { hasText: 'There are no contacts' }).first()).toBeVisible();
   });
 
+  /**
+   * Test large contact import performance
+   * 
+   * This test validates the system's performance when handling
+   * larger contact lists. The test ensures that:
+   * - Large contact lists are processed efficiently
+   * - All contacts are detected correctly
+   * - Import process completes successfully
+   * - Performance remains acceptable
+   */
   test('Large contact import performance', async ({ page, browserName }) => {
     perfMonitor.start('Large contact import performance');
     
@@ -722,7 +963,7 @@ test.describe('Contact Import Functionality', () => {
       page.locator('button:has-text("Import Selected Contacts")').click()
     );
     
-    // Verify success
+    // Verify success feedback
     await perfMonitor.measureAsync('wait for success message', () => 
       expect(page.locator('div[role="alert"] span:has-text("Success")')).toBeVisible()
     );
@@ -730,6 +971,15 @@ test.describe('Contact Import Functionality', () => {
     perfMonitor.end('Large contact import performance');
   });
 
+  /**
+   * Test alert dismissal performance
+   * 
+   * This test validates the performance and reliability of
+   * alert dismissal functionality. The test ensures that:
+   * - Alerts are dismissed efficiently
+   * - Different dismissal strategies work correctly
+   * - Performance remains acceptable
+   */
   test('Alert dismissal performance test', async ({ page, browserName }) => {
     perfMonitor.start('Alert dismissal performance test');
     
@@ -760,7 +1010,6 @@ test.describe('Contact Import Functionality', () => {
       try {
         await alertButton.click({ timeout: 5000 });
       } catch (error) {
-        console.log(`[${browserName}] Alert dismissal failed, trying alternative approach`);
         // Try force click if normal click fails
         await alertButton.click({ force: true, timeout: 5000 });
       }