Move technical documentation to DEV.md

2026-02-22 02:45:41 +00:00 · 2026-01-17 13:14:43 +01:00
parent 750f1a766d
commit 08aef9e81e
2 changed files with 166 additions and 162 deletions
--- a/DEV.md
+++ b/DEV.md
@@ -0,0 +1,163 @@
+
+## Password & Form Autofill System
+
+### **[AutomaticPasswords.js](js/forms/AutomaticPasswords.js)**
+Manages Safari's automatic strong password generation:
+- Removes auto-generated passwords from password fields
+- Controls visibility of suggested strong passwords
+- Handles focus/blur events when users interact with password fields
+- Manages the "autofilled" state of password inputs
+
+### **[FormMetadata.js](js/forms/FormMetadata.js)**
+The brain of Safari's form autofill system:
+- **Form Detection & Classification**: Identifies login forms, signup forms, password change forms, and standard forms
+- **Smart Field Recognition**: Uses pattern matching, element positioning, visual analysis, and machine learning-like scoring to identify:
+  - Username fields
+  - Password fields (current, new, confirm)
+  - Credit card fields (number, CVV, expiration, cardholder)
+  - Address fields (street, city, postal code)
+  - Phone numbers (split across multiple fields)
+  - Email addresses
+  - One-time codes (2FA)
+
+### **[FormMetadataClassification.js](js/forms/FormMetadataClassification.js)**
+Intelligently classifies form fields to enable autofill:
+- **Identifies field types**: credit cards, names, addresses, phone numbers, emails, birthdays, passwords, etc.
+- **Handles multi-part fields**: splits fields like "First Name | Last Name" or phone numbers across multiple inputs
+- **Continuation detection**: recognizes when a single piece of data (like credit card number) is split across multiple fields
+- **Uses multiple signals**: autocomplete attributes, field names, placeholders, sizes, and positioning
+- **Date field parsing**: understands various date formats and splits (day/month/year)
+- **Smart matching**: uses pattern recognition to classify fields even without explicit HTML hints
+
+### **[NodePath.js](js/utilities/NodePath.js)**
+Creates stable references to DOM elements:
+- **Path-based element identification**: creates a "fingerprint" for DOM nodes that works even when the DOM changes
+- **Fuzzy matching**: uses similarity scoring (Levenshtein distance) to relocate elements after page updates
+- **Handles shadow DOM and iframes**: traverses across shadow boundaries and iframe documents
+- **Range support**: can reference text selections, not just elements
+- **Resilient resolution**: uses multiple strategies (CSS selectors, position, attributes) to find elements
+
+---
+
+## Reader Mode System
+
+### **[Reader.js](js/reader/Reader.js)**
+Powers Safari's Reader Mode core functionality:
+- Manages visibility transitions for Reader view
+- Handles iframe URL caching/restoration when entering/exiting Reader
+- Checks JavaScript enablement settings
+- Mac-specific UI adjustments
+
+### **[ReaderArticleFinder.js](js/reader/ReaderArticleFinder.js)** (~3500 lines)
+Safari's article detection and cleaning algorithm (similar to Mozilla's Readability):
+
+**Article Detection Strategies:**
+1. Schema.org metadata (`<article itemtype="Article">`)
+2. OpenGraph tags (`<meta property="og:type" content="article">`)
+3. Visual examination (hit-testing specific screen coordinates)
+4. Quirks list for known sites (NYTimes, Medium, etc.)
+
+**Scoring System:**
+- Text density analysis
+- Link density (fewer links = more likely article)
+- Tag names (article, main, section boost score)
+- Class names ("article", "content" boost; "comment", "sidebar" reduce)
+- Position on page
+- Font consistency
+
+**Smart Cleaning:**
+- Removes ads, comments, navigation
+- Keeps images, videos, tweets
+- Converts lazy-loaded images
+- Preserves tables and code blocks
+- Handles multi-column layouts
+- Detects CJK (Chinese, Japanese, Korean) text using Unicode ranges
+
+### **[ReaderSharedUI.js](js/reader/ReaderSharedUI.js)**
+Powers the actual Reader Mode interface:
+
+**Layout Management:**
+- Multi-column pagination for long articles
+- Responsive design adapting to window size
+- 12+ font families (System, Charter, Georgia, Iowan, Palatino, etc.)
+- 4 themes: White, Sepia, Gray, Night
+- 12 text size levels with custom line heights per font
+
+**Interactive Features:**
+- Smooth scrolling with animations
+- Content-aware navigation (stops at natural break points)
+- Next page auto-loading for paginated articles
+- Print/email formatting
+- Reading position memory
+- Table of Contents generation from headings
+- AI-generated summary display with collapsible UI
+- Sidebar for TOC/summary on wide screens
+
+### **[ReaderSharedUINormalWorld.js](js/reader/ReaderSharedUINormalWorld.js)**
+Enhances Reader Mode with rich content:
+- **Twitter/X integration**: replaces simple tweet embeds with rich Twitter widgets
+- Loads Twitter's widget JavaScript on demand
+- Handles transition from placeholder tweets to interactive embeds
+
+---
+
+## Web Page Analysis & Data Extraction
+
+### **[SchemaDataExtractor.js](js/schema/SchemaDataExtractor.js)**
+Extracts contact information from web pages:
+- Parses **Microdata** markup (HTML attributes like `itemscope`, `itemprop`)
+- Parses **JSON-LD** structured data (schema.org formatted JSON)
+- Extracts addresses, phone numbers, business names
+- Enables Safari's "Add to Contacts" feature
+
+### **[SchemaOrgMarkupChecker.js](js/schema/SchemaOrgMarkupChecker.js)**
+Simple detection utility:
+- Returns `true` if page contains schema.org structured data
+- Checks both JSON-LD scripts and microdata attributes
+- Used to determine if page has extractable structured information
+
+### **[MetadataExtractor.js](js/metadata/MetadataExtractor.js)**
+Extracts website icons and branding:
+- Favicon URLs
+- Apple Touch icons (for iOS home screen)
+- Template icons with colors
+- Sorts icons by size/quality
+
+### **[WebContentLayoutAnalyzer.js](js/layout/WebContentLayoutAnalyzer.js)**
+Analyzes page responsive design:
+- Detects centered container elements
+- Determines if containers have fixed width (non-responsive)
+- Measures container movement during window resize
+- Helps Safari optimize reader mode and display adjustments
+
+---
+
+## Search & Discovery
+
+### **[OpenSearchURLFinder.js](js/search/OpenSearchURLFinder.js)**
+Enables custom search engine discovery:
+- Finds `<link rel="search">` tags in page header
+- Powers Safari's search engine discovery feature
+- Allows users to add custom search engines from websites
+
+---
+
+## Localization & Translation
+
+### **[Translation.js](js/translation/Translation.js)**
+Manages language attributes during translation:
+- Updates page's `lang` attribute when Safari translates content
+- Ensures accessibility tools and screen readers recognize current language
+
+---
+
+## Save & Archive
+
+### **[SavePageInliningOrDiscardingExternalResources.js](js/utilities/SavePageInliningOrDiscardingExternalResources.js)**
+Creates self-contained web archives:
+- Copies all HTML elements and their styles
+- Inlines CSS from stylesheets into the document
+- Converts external resource URLs to local filenames
+- Removes scripts, objects, and dynamic content
+- Recursively captures iframe content
+- Powers Safari's "Save As Web Archive" feature