docs: comprehensive documentation updates and modernization

- Update BUILDING.md with current build system information
- Modernize various README files across the project
- Update CHANGELOG.md with recent changes
- Improve documentation consistency and formatting
- Update platform-specific documentation (iOS, Electron, Docker)
- Enhance test documentation and build guides

doc/cors-image-loading-solution.md

@@ -7,6 +7,7 @@ This document describes the implementation of a comprehensive image loading solu
 ## Problem Statement
 
 When using SharedArrayBuffer (required for absurd-sql), browsers enforce a cross-origin isolated environment with these headers:
+
 - `Cross-Origin-Opener-Policy: same-origin`
 - `Cross-Origin-Embedder-Policy: require-corp`
 
@@ -19,6 +20,7 @@ This isolation prevents loading external resources (including images) unless the
 The solution uses a multi-tier approach to handle images from various sources:
 
 #### Tier 1: Specific Domain Proxies (Development Only)
+
 - **TimeSafari Images**: `/image-proxy/` → `https://image.timesafari.app/`
 - **Flickr Images**: `/flickr-proxy/` → `https://live.staticflickr.com/`
 - **Imgur Images**: `/imgur-proxy/` → `https://i.imgur.com/`
@@ -26,14 +28,17 @@ The solution uses a multi-tier approach to handle images from various sources:
 - **Unsplash**: `/unsplash-proxy/` → `https://images.unsplash.com/`
 
 #### Tier 2: Universal CORS Proxy (Development Only)
+
 - **Any External Domain**: Uses `https://api.allorigins.win/raw?url=` for arbitrary domains
 
 #### Tier 3: Direct Loading (Production)
+
 - **Production Mode**: All images load directly without proxying
 
 ### 2. Smart URL Transformation
 
 The `transformImageUrlForCors` function automatically:
+
 - Detects the image source domain
 - Routes through appropriate proxy in development
 - Preserves original URLs in production
@@ -44,6 +49,7 @@ The `transformImageUrlForCors` function automatically:
 ### Configuration Files
 
 #### `vite.config.common.mts`
+
 ```typescript
 server: {
   headers: {
@@ -63,6 +69,7 @@ server: {
 ```
 
 #### `src/libs/util.ts`
+
 ```typescript
 export function transformImageUrlForCors(imageUrl: string): string {
   // Development mode: Transform URLs to use proxies
@@ -93,21 +100,25 @@ const imageUrl = transformImageUrlForCors(originalImageUrl);
 ## Benefits
 
 ### ✅ SharedArrayBuffer Support
+
 - Maintains cross-origin isolation required for SharedArrayBuffer
 - Enables fast SQLite database operations via absurd-sql
 - Provides better performance than IndexedDB fallback
 
 ### ✅ Universal Image Support
+
 - Handles images from any domain
 - No need to pre-configure every possible image source
 - Graceful fallback for unknown domains
 
 ### ✅ Development/Production Flexibility
+
 - Proxy system only active in development
 - Production uses direct URLs for maximum performance
 - No proxy server required in production
 
 ### ✅ Automatic Detection
+
 - Smart URL transformation based on domain patterns
 - Preserves relative URLs and data URLs
 - Handles edge cases gracefully
@@ -115,6 +126,7 @@ const imageUrl = transformImageUrlForCors(originalImageUrl);
 ## Testing
 
 ### Automated Testing
+
 Run the test suite to verify URL transformation:
 
 ```typescript
@@ -125,6 +137,7 @@ testCorsImageTransformation();
 ```
 
 ### Visual Testing
+
 Create test image elements to verify loading:
 
 ```typescript
@@ -135,6 +148,7 @@ createTestImageElements();
 ```
 
 ### Manual Testing
+
 1. Start development server: `npm run dev`
 2. Open browser console to see transformation logs
 3. Check Network tab for proxy requests
@@ -143,16 +157,19 @@ createTestImageElements();
 ## Security Considerations
 
 ### Development Environment
+
 - CORS proxies are only used in development
 - External proxy services (allorigins.win) are used for testing
 - No sensitive data is exposed through proxies
 
 ### Production Environment
+
 - All images load directly without proxying
 - No dependency on external proxy services
 - Original security model maintained
 
 ### Privacy
+
 - Image URLs are not logged or stored by proxy services
 - Proxy requests are only made during development
 - No tracking or analytics in proxy chain
@@ -160,11 +177,13 @@ createTestImageElements();
 ## Performance Impact
 
 ### Development
+
 - Slight latency from proxy requests
 - Additional network hops for external domains
 - More verbose logging for debugging
 
 ### Production
+
 - No performance impact
 - Direct image loading as before
 - No proxy overhead
@@ -174,17 +193,20 @@ createTestImageElements();
 ### Common Issues
 
 #### Images Not Loading in Development
+
 1. Check console for proxy errors
 2. Verify CORS headers are set
 3. Test with different image URLs
 4. Check network connectivity to proxy services
 
 #### SharedArrayBuffer Not Available
+
 1. Verify CORS headers are set in server configuration
 2. Check that site is served over HTTPS (or localhost)
 3. Ensure browser supports SharedArrayBuffer
 
 #### Proxy Service Unavailable
+
 1. Check if allorigins.win is accessible
 2. Consider using alternative CORS proxy services
 3. Temporarily disable CORS headers for testing
@@ -207,12 +229,14 @@ testCorsImageTransformation();
 ## Migration Guide
 
 ### From Previous Implementation
+
 1. CORS headers are now required for SharedArrayBuffer
 2. Image URLs automatically transformed in development
 3. No changes needed to existing image loading code
 4. Test thoroughly in both development and production
 
 ### Adding New Image Sources
+
 1. Add specific proxy for frequently used domains
 2. Update `transformImageUrlForCors` function
 3. Add CORS headers to proxy configuration
@@ -221,6 +245,7 @@ testCorsImageTransformation();
 ## Future Enhancements
 
 ### Possible Improvements
+
 1. **Local Proxy Server**: Run dedicated proxy server for development
 2. **Caching**: Cache proxy responses for better performance
 3. **Fallback Chain**: Multiple proxy services for reliability
@@ -228,6 +253,7 @@ testCorsImageTransformation();
 5. **Analytics**: Track image loading success/failure rates
 
 ### Alternative Approaches
+
 1. **Service Worker**: Intercept image requests at service worker level
 2. **Build-time Processing**: Pre-process images during build
 3. **CDN Integration**: Use CDN with proper CORS headers
@@ -237,4 +263,4 @@ testCorsImageTransformation();
 
 This solution provides a robust, scalable approach to image loading in a cross-origin isolated environment while maintaining the benefits of SharedArrayBuffer support. The multi-tier proxy system ensures compatibility with any image source while optimizing for performance and security.
 
-For questions or issues, refer to the troubleshooting section or consult the development team. 
+For questions or issues, refer to the troubleshooting section or consult the development team.