safari-internal-js/DEV.md

Password & Form Autofill System

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

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

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

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

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 (~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

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

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

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

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

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

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

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

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

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