Updated documentation

Author: ekscrypto

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+# Build the package
+swift build
+
+# Run all tests
+swift test
+
+# Run tests with code coverage
+swift test --enable-code-coverage
+```
+
+## Architecture Overview
+
+SwiftEmailValidator is an RFC-compliant email syntax validator supporting international email addresses. It validates email format without requiring network access.
+
+### Core Components
+
+**EmailSyntaxValidator** (`Sources/SwiftEmailValidator/EmailSyntaxValidator.swift`)
+- Main entry point with static methods: `correctlyFormatted()` and `mailbox()`
+- Returns `Mailbox` struct containing parsed `localPart` (dotAtom or quotedString) and `host` (domain or addressLiteral)
+- Supports three compatibility modes: `.ascii` (RFC822), `.asciiWithUnicodeExtension` (RFC2047), `.unicode` (RFC6531)
+- Domain validation delegated to SwiftPublicSuffixList by default, customizable via `domainValidator` closure
+
+**RFC2047Coder** (`Sources/SwiftEmailValidator/RFC2047Coder.swift`)
+- Encodes/decodes Unicode email addresses for ASCII-only systems
+- Supports Base64 ('b') and Quoted-Printable ('q') encodings
+- Handles utf-8, utf-16, utf-32, iso-8859-1, iso-8859-2 charsets
+
+**IPAddressSyntaxValidator** (`Sources/SwiftEmailValidator/IPAddressSyntaxValidator.swift`)
+- Validates IPv4 and IPv6 address literals in email hosts
+- Used when `allowAddressLiteral: true` is passed to validation methods
+
+### Validation Flow
+
+1. Optionally decode RFC2047 encoded input
+2. Extract and validate local part (before @) - either dot-atom or quoted-string format
+3. Extract host (after @) - either domain or address literal
+4. Validate domain against Public Suffix List (or custom validator)
+5. Return structured `Mailbox` or `nil`
+
+### Dependencies
+
+- **SwiftPublicSuffixList**: Domain validation against the Public Suffix List. First use incurs 100-900ms initialization delay.
+
+### Key Design Decisions
+
+- All public API methods are static - no instance creation needed
+- Returns `nil` for invalid input rather than throwing
+- Domain validation is pluggable via closure parameter
+- Character validation uses pre-built `CharacterSet` instances for efficiency

README.md

@@ -22,13 +22,21 @@ You can use The Swift Package Manager to install SwiftEmailValidator by adding i
         ]
     )
 
+## Performance Considerations
+
+Due to the high number of entries in the Public Suffix list (>9k), the first email validation may add 100ms to 900ms depending on the device. To avoid this delay affecting user experience, you can pre-load the rules on a background thread soon after launching the app:
+
+    import SwiftPublicSuffixList
+
+    DispatchQueue.global(qos: .utility).async {
+        _ = PublicSuffixRulesRegistry.rules
+    }
+
 ## Public Suffix List
 
 By default, domains are validated against the [Public Suffix List](https://publicsuffix.org) using the [SwiftPublicSuffixList](https://github.com/ekscrypto/SwiftPublicSuffixList) library.
 
 ### Notes:
-* Due to the high number of entries in the Public Suffix list (>9k), the first validation may add 100ms to 900ms depending on the device you are using.  If this is unacceptable you can
- pre-load on a background thread PublicSuffixRulesRegistry.rules prior to using EmailSyntaxValidator.
 * The [Public Suffix List](https://publicsuffix.org) is updated regularly. If your application is published regularly you may be fine by simply pulling the latest version of the SwiftPublicSuffixList library.  However it is recommended to have
 your application retrieve the latest copy of the public suffix list on a somewhat regular basis.  Details on how to accomplish this are available in the [SwiftPublicSuffixList](https://github.com/ekscrypto/SwiftPublicSuffixList) library page.  You can then use the domainValidator parameter to specify the closure to use for the domain validation.  See "Using Custom SwiftPublicSuffixList Rules" below.
 * You can bypass the Public Suffix List altogether and use your own custom Regex if desired. See "Bypassing SwiftPublicSuffixList" below.