diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1ae582b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `Sources/SwiftUIHTML` holds the reusable rendering core; `Example` contains the SwiftUI host app and its unit/UI test targets.  
+- `SwiftUIHTMLExampleTests` and `SwiftUIHTMLExampleUITests` live next to the example project and keep the snapshot/test helpers, including `ViewSnapshotTester.swift`.  
+- `SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests` stores the PNG baselines and HTML payloads.  
+- `scripts/` hosts the snapshot-reporting helpers, OCR utilities, and the new `run_ios_snapshots.sh` driver.  
+- `mise.toml` defines high-level automation tasks invoked with `mise <task>` while `Package.swift` drives SwiftPM dependency resolution.
+
+## Build, Test, and Development Commands
+- `mise ios-snapshots`: boots the current iOS simulator, records every snapshot with `SWIFTUIHTML_SNAPSHOT_RECORD=1`, and produces `/tmp/swiftuihtml-ios-snapshot-report-*/index.html`.  
+- `mise ios-snapshot-single TEST_ONLY=...`: focuses on one XCTest and emits a mini report for that snapshot.  
+- `python3 scripts/snapshot_report.py --artifacts <dir> --baseline SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests --title "<label>" --out-prefix /tmp/...`: regenerates the HTML dashboard; add `--test-log` to include xcodebuild results.  
+- `xcodebuild test -scheme SwiftUIHTMLExample ...`: used when you need finer control, but prefer the `mise` wrapper for consistent artifact capture.
+
+## Coding Style & Naming Conventions
+- Follow Swift conventions: 4-space indentation, `camelCase` for variables/methods, `PascalCase` for types/protocols, and `lower_snake_case` for snapshot file stems (e.g., `testBulletImageAlignment.bulletImageAlignment.png`).  
+- Keep UI modifiers chained cleanly, avoid deeply nested closures, and prefer short helper functions (see `ViewSnapshotTester`).  
+- No automated formatter is enforced, but align new Swift files with the surrounding style and run `swift build`/`swift test` to surface formatter warnings.
+
+## Testing Guidelines
+- Snapshot tests live in `HTMLBasicTests`; each snapshot helper is also exposed through `HTMLBasicXCTest` so `xcodebuild -only-testing` can exercise the view.  
+- Naming follows `test<ScenarioDescription>`; the snapshot artifact includes the test name plus logic-specific suffixes (e.g., `.longWordsWithImages_byCharWrapping`).  
+- Always run through `mise ios-snapshots` (or the single/test-specific task) so artifacts, OCR logs, and HTML inputs are collected together with the report.
+
+## Snapshot Reporting & Diagnostics
+- `scripts/run_ios_snapshots.sh` now copies the simulator’s `artifactsRoot` back into `/tmp/swiftuihtml-ios-artifacts`, ensuring `snapshot_report.py` can find both baseline and new images.  
+- Diagnostic logs (`SWIFTUIHTML_ATTACHMENT_LOGS`, margin diagnostics, OCR json files) live under `/tmp/swiftuihtml-ios-artifacts` and are attached to XCTActivities. Link them from reports when investigating regressions.
+
+## Commit & Pull Request Guidelines
+- Write imperative commit messages (`Fix list-item gap`, `Align bullet-plus-image snapshot`). Include the test(s) you updated if relevant.  
+- PRs should describe what snapshot regressions exist, list which mise task(s) were run (e.g., `mise ios-snapshots`), and attach the latest report path (e.g., `/tmp/swiftuihtml-ios-snapshot-report-<timestamp>/index.html`). Add screenshots or report snippets when visual diffs matter.
diff --git a/Documentation/BasicUsage.md b/Documentation/BasicUsage.md
index d49e91c..7facfce 100644
--- a/Documentation/BasicUsage.md
+++ b/Documentation/BasicUsage.md
@@ -22,7 +22,7 @@ struct SimpleHTMLView: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
     }
 }
@@ -50,7 +50,7 @@ struct TextStyleExample: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
             .htmlEnvironment(\.styleContainer, {
                 var container = HTMLStyleContainer()
@@ -61,7 +61,56 @@ struct TextStyleExample: View {
 }
 ```
 
-## 3. 이미지 삽입 / Image Embedding
+## 3. 루비 주석 / Ruby Annotations
+
+### 한글 설명
+`ruby`와 `rt` 태그를 사용해 일본어 루비 주석을 렌더링할 수 있습니다. `rt` 텍스트는 루비 문자열로 사용되고 `rp`/`rtc`는 무시됩니다. 필요하면 `ruby-position`, `ruby-scale`, `ruby-font-name`, `ruby-font-size`, `ruby-annotation-font-*` 속성으로 조정할 수 있습니다.
+
+### English
+You can render ruby annotations using `ruby` and `rt`. The `rt` text becomes the ruby string, and `rp`/`rtc` are ignored. Optional attributes include `ruby-position`, `ruby-scale`, `ruby-font-name`, `ruby-font-size`, and `ruby-annotation-font-*`.
+
+```swift
+struct RubyExample: View {
+    let html = """
+        <p>루비 주석 예제:</p>
+        <p>
+            <ruby>
+                漢字<rt>かんじ</rt>
+            </ruby>
+            를 읽습니다.
+        </p>
+        <p>
+            <ruby ruby-position="after" ruby-scale="0.5">
+                今日<rt>きょう</rt>
+            </ruby>
+            는 맑습니다.
+        </p>
+        <p>
+            <ruby ruby-font-size="22" ruby-annotation-font-size="12">
+                明日<rt>あした</rt>
+            </ruby>
+            도 맑습니다.
+        </p>
+        """
+    
+    var body: some View {
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .default)
+            .htmlEnvironment(\.styleContainer, {
+                var container = HTMLStyleContainer()
+#if os(macOS)
+                let font = NSFont.systemFont(ofSize: 18)
+#else
+                let font = UIFont.systemFont(ofSize: 18)
+#endif
+                container.uiFont = font
+                return container
+            }())
+    }
+}
+```
+
+## 4. 이미지 삽입 / Image Embedding
 
 ### 한글 설명
 HTML 내에 이미지를 삽입하는 방법입니다. 웹 URL이나 로컬 이미지를 모두 지원합니다.
@@ -84,7 +133,7 @@ struct ImageExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -92,7 +141,7 @@ struct ImageExample: View {
 }
 ```
 
-## 4. 링크 처리 / Link Handling
+## 5. 링크 처리 / Link Handling
 
 ### 한글 설명
 클릭 가능한 링크를 생성하는 방법입니다. 링크 태그는 자동으로 처리됩니다.
@@ -113,13 +162,13 @@ struct LinkExample: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
     }
 }
 ```
 
-## 5. 블록 요소 구조 / Block Element Structure
+## 6. 블록 요소 구조 / Block Element Structure
 
 ### 한글 설명
 다양한 블록 요소들을 사용하는 방법입니다. div, p, section 등의 기본 블록 태그를 활용합니다.
@@ -146,14 +195,14 @@ struct BlockElementExample: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
             .padding()
     }
 }
 ```
 
-## 6. 헤더와 섹션 구조 / Headers and Section Structure
+## 7. 헤더와 섹션 구조 / Headers and Section Structure
 
 ### 한글 설명
 HTML 문서 구조를 만드는 방법입니다. header, main, section, footer 태그를 활용합니다.
@@ -189,7 +238,7 @@ struct DocumentStructureExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -197,7 +246,7 @@ struct DocumentStructureExample: View {
 }
 ```
 
-## 7. 줄바꿈 처리 / Line Break Handling
+## 8. 줄바꿈 처리 / Line Break Handling
 
 ### 한글 설명
 텍스트 줄바꿈을 처리하는 방법입니다. br 태그와 줄바꿈 모드를 설정할 수 있습니다.
@@ -225,7 +274,7 @@ struct LineBreakExample: View {
     var body: some View {
         VStack(spacing: 20) {
             // 단어 단위 줄바꿈
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
@@ -235,7 +284,7 @@ struct LineBreakExample: View {
                 .border(Color.blue)
             
             // 문자 단위 줄바꿈
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
@@ -249,13 +298,13 @@ struct LineBreakExample: View {
 }
 ```
 
-## 8. 폰트 설정 / Font Configuration
+## 9. 폰트 설정 / Font Configuration
 
 ### 한글 설명
-폰트 크기와 스타일을 설정하는 방법입니다. UIFont를 사용하여 시스템 폰트나 커스텀 폰트를 적용할 수 있습니다.
+폰트 크기와 스타일을 설정하는 방법입니다. iOS는 UIFont, macOS는 NSFont를 사용하여 시스템 폰트나 커스텀 폰트를 적용할 수 있습니다.
 
 ### English
-How to configure font size and style. You can apply system fonts or custom fonts using UIFont.
+How to configure font size and style. Use UIFont on iOS and NSFont on macOS to apply system or custom fonts.
 
 ```swift
 struct FontExample: View {
@@ -270,22 +319,32 @@ struct FontExample: View {
     var body: some View {
         VStack(spacing: 20) {
             // 기본 폰트 크기
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
-                    container.uiFont = .systemFont(ofSize: 14)
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
+                    let font = UIFont.systemFont(ofSize: 14)
+#endif
+                    container.uiFont = font
                     return container
                 }())
             
             Divider()
             
             // 큰 폰트 크기
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
-                    container.uiFont = .systemFont(ofSize: 18)
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 18)
+#else
+                    let font = UIFont.systemFont(ofSize: 18)
+#endif
+                    container.uiFont = font
                     return container
                 }())
         }
@@ -294,7 +353,7 @@ struct FontExample: View {
 }
 ```
 
-## 9. 줄 높이 설정 / Line Height Configuration
+## 10. 줄 높이 설정 / Line Height Configuration
 
 ### 한글 설명
 텍스트 줄 높이를 조정하는 방법입니다. 가독성을 높이기 위해 줄 간격을 설정할 수 있습니다.
@@ -315,11 +374,15 @@ struct LineHeightExample: View {
     var body: some View {
         VStack(spacing: 20) {
             // 좁은 줄 간격
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
                     let font = UIFont.systemFont(ofSize: 14)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 18)
                     return container
@@ -327,11 +390,15 @@ struct LineHeightExample: View {
                 .border(Color.red)
             
             // 넓은 줄 간격
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
                     let font = UIFont.systemFont(ofSize: 14)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 28)
                     return container
@@ -343,7 +410,7 @@ struct LineHeightExample: View {
 }
 ```
 
-## 10. 복합 예제 / Complex Example
+## 11. 복합 예제 / Complex Example
 
 ### 한글 설명
 여러 기능을 함께 사용하는 복합 예제입니다.
@@ -394,11 +461,15 @@ struct ComplexExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 16)
+#else
                     let font = UIFont.systemFont(ofSize: 16)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 24)
                     container.lineBreakMode = .byWordWrapping
@@ -408,4 +479,4 @@ struct ComplexExample: View {
         }
     }
 }
-```
\ No newline at end of file
+```
diff --git a/Documentation/CustomTags.md b/Documentation/CustomTags.md
index 35ab350..29c5ce7 100644
--- a/Documentation/CustomTags.md
+++ b/Documentation/CustomTags.md
@@ -3,6 +3,9 @@
 SwiftUIHTML에서 커스텀 태그를 만들고 등록하는 방법을 소개합니다.
 This guide introduces how to create and register custom tags in SwiftUIHTML.
 
+> 참고: `ruby`는 기본 InlineAttachmentTag로 제공되며 별도 등록이 필요 없습니다.
+> Note: `ruby` is built-in as an InlineAttachmentTag and does not need custom registration.
+
 ## 태그 타입 / Tag Types
 
 ### 한글 설명
@@ -17,6 +20,17 @@ SwiftUIHTML supports three types of tags:
 - **InlineTag**: Inline text elements (span, strong, em, etc.)
 - **InlineAttachmentTag**: Inline attachment elements (img, video, etc.)
 
+### Built-in ruby example / 기본 ruby 예제
+
+```swift
+let html = """
+    <p>
+        <ruby>漢字<rt>かんじ</rt></ruby>
+        를 읽습니다.
+    </p>
+    """
+```
+
 ## 1. 커스텀 블록 태그 / Custom Block Tag
 
 ### 한글 설명
@@ -372,7 +386,7 @@ struct ContentView: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, customConfiguration())
                 .padding()
         }
@@ -403,4 +417,4 @@ struct ContentView: View {
 - Custom tags can override default tags
 - BlockTag must implement the View protocol
 - InlineTag only applies styles; rendering is handled by the system
-- InlineAttachmentTag creates views that are inserted inline
\ No newline at end of file
+- InlineAttachmentTag creates views that are inserted inline
diff --git a/Documentation/ParserIntegration.md b/Documentation/ParserIntegration.md
index 5881108..3503c49 100644
--- a/Documentation/ParserIntegration.md
+++ b/Documentation/ParserIntegration.md
@@ -3,6 +3,25 @@
 SwiftUIHTML은 HTMLParserable 프로토콜을 통해 다양한 HTML 파서와 통합할 수 있습니다.
 SwiftUIHTML can integrate with various HTML parsers through the HTMLParserable protocol.
 
+> Note: For ruby annotations, parsers should keep `<ruby>` as a node with child `<rt>` nodes; the renderer extracts base/ruby text from those children.
+
+### Ruby parsing example / Ruby 파싱 예제
+
+```swift
+// Input:
+// <ruby>漢字<rt>かんじ</rt></ruby>
+//
+// Expected node shape:
+let rubyNode = HTMLNode(
+    tag: "ruby",
+    attributes: [:],
+    children: [
+        .text("漢字"),
+        .node(HTMLNode(tag: "rt", attributes: [:], children: [.text("かんじ")]))
+    ]
+)
+```
+
 ## HTMLParserable 프로토콜 / HTMLParserable Protocol
 
 ### 한글 설명
@@ -28,106 +47,13 @@ struct HTMLNode {
 
 enum HTMLChild {
     case text(String)
-    case trimmingText(String)
-    case newLine
     case node(HTMLNode)
 }
 ```
 
 ---
 
-## 1. Fuzi 파서 통합 / Fuzi Parser Integration
-
-### 한글 설명
-Fuzi는 Swift용 XML/HTML 파서입니다. libxml2를 기반으로 하며 빠른 파싱 성능을 제공합니다.
-
-### English
-Fuzi is an XML/HTML parser for Swift. Based on libxml2, it provides fast parsing performance.
-
-### 설치 / Installation
-
-```swift
-dependencies: [
-    .package(url: "https://github.com/cezheng/Fuzi.git", from: "3.0.0")
-]
-```
-
-### 구현 / Implementation
-
-```swift
-import Fuzi
-import SwiftUIHTML
-
-struct HTMLFuziParser: HTMLParserable {
-    func parse(html: String) -> HTMLNode {
-        do {
-            let document = try HTMLDocument(string: html, encoding: .utf8)
-            
-            // body 태그를 찾거나 root 사용
-            if let body = document.body {
-                return try elementToHTMLNode(element: body)
-            } else if let root = document.root {
-                return try elementToHTMLNode(element: root)
-            } else {
-                return createErrorNode("No root element found")
-            }
-        } catch {
-            return createErrorNode("Parse error: \(error.localizedDescription)")
-        }
-    }
-    
-    private func elementToHTMLNode(element: Fuzi.XMLElement) throws -> HTMLNode {
-        let tag = element.tag ?? "div"
-        
-        // 속성 변환
-        let attributes = element.attributes.reduce(into: [String: String]()) { result, attribute in
-            result[attribute.key] = attribute.value
-        }
-        
-        // 자식 노드 변환
-        let children: [HTMLChild] = try element.childNodes(ofTypes: [.Element, .Text])
-            .compactMap { node -> HTMLChild? in
-                if node.type == .Text {
-                    let text = node.stringValue
-                    return text.isEmpty ? nil : .trimmingText(text)
-                } else if let childElement = node.toElement() {
-                    // br 태그는 특별 처리
-                    if childElement.tag == "br" {
-                        return .newLine
-                    }
-                    return .node(try elementToHTMLNode(element: childElement))
-                }
-                return nil
-            }
-        
-        return HTMLNode(tag: tag, attributes: attributes, children: children)
-    }
-    
-    private func createErrorNode(_ message: String) -> HTMLNode {
-        HTMLNode(tag: "div", attributes: [:], children: [.text(message)])
-    }
-}
-```
-
-### 사용 예제 / Usage Example
-
-```swift
-struct ContentView: View {
-    let html = """
-        <h1>Fuzi Parser Example</h1>
-        <p>This HTML is parsed using <strong>Fuzi</strong>.</p>
-        """
-    
-    var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
-            .htmlEnvironment(\.configuration, .default)
-    }
-}
-```
-
----
-
-## 2. SwiftSoup 파서 통합 / SwiftSoup Parser Integration
+## 1. SwiftSoup 파서 통합 / SwiftSoup Parser Integration
 
 ### 한글 설명
 SwiftSoup은 Java의 JSoup을 Swift로 포팅한 HTML 파서입니다. CSS 선택자를 지원하며 HTML 조작이 가능합니다.
@@ -139,10 +65,16 @@ SwiftSoup is a Swift port of Java's JSoup HTML parser. It supports CSS selectors
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.0.0")
+    // Latest mainline (SwiftSoup default branch is `master`).
+    .package(url: "https://github.com/scinfu/SwiftSoup.git", branch: "master")
+    // Or pin to a stable tag:
+    // .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.x.y")
 ]
 ```
 
+> 참고: SwiftSoup의 기본 브랜치는 `master`입니다. 최신 메인라인을 추적하려면 `branch: "master"`를 사용하세요. 안정 버전은 최신 릴리스를 사용하세요.
+> Note: SwiftSoup's default branch is `master`. Use `branch: "master"` to track the latest mainline. For stable builds, pin the latest release.
+
 ### 구현 / Implementation
 
 ```swift
@@ -179,11 +111,11 @@ struct HTMLSwiftSoupParser: HTMLParserable {
         let children: [HTMLChild] = try element.getChildNodes().compactMap { node in
             if let textNode = node as? TextNode {
                 let text = textNode.text()
-                return text.isEmpty ? nil : .trimmingText(text)
+                return text.isEmpty ? nil : .text(text)
             } else if let elementNode = node as? Element {
                 // br 태그는 특별 처리
                 if elementNode.tagName() == "br" {
-                    return .newLine
+                    return .text("\n")
                 }
                 return .node(try elementToHTMLNode(element: elementNode))
             }
@@ -217,9 +149,11 @@ struct ContentView: View {
 }
 ```
 
+> Example app note: The SwiftUIHTML Example app includes a SwiftSoup parser sample that appears when SwiftSoup is linked into the target (guarded by `#if canImport(SwiftSoup)`).
+
 ---
 
-## 3. 커스텀 파서 구현 / Custom Parser Implementation
+## 2. 커스텀 파서 구현 / Custom Parser Implementation
 
 ### 한글 설명
 특별한 요구사항이 있다면 직접 파서를 구현할 수 있습니다.
@@ -294,27 +228,25 @@ struct AdvancedHTMLParser: HTMLParserable {
 
 ---
 
-## 4. 파서 선택 가이드 / Parser Selection Guide
+## 3. 파서 선택 가이드 / Parser Selection Guide
 
 ### 한글 가이드
 
 | 파서 | 장점 | 단점 | 추천 사용 케이스 |
 |-----|------|------|-----------------|
-| **Fuzi** | • 빠른 성능<br>• 메모리 효율적<br>• libxml2 기반 안정성 | • 추가 의존성<br>• 설정 복잡도 | 대용량 HTML 처리 |
-| **SwiftSoup** | • 순수 Swift<br>• CSS 선택자<br>• HTML 조작 기능 | • 상대적으로 느림<br>• 메모리 사용량 많음 | HTML 조작이 필요한 경우 |
+| **SwiftSoup** | • 순수 Swift<br>• CSS 선택자<br>• HTML 조작 기능 | • 추가 의존성<br>• 상대적으로 느림 | HTML 조작이 필요한 경우 |
 | **Custom** | • 완전한 제어<br>• 특수 요구사항 대응 | • 개발 시간<br>• 유지보수 부담 | 특별한 파싱 규칙이 필요한 경우 |
 
 ### English Guide
 
 | Parser | Pros | Cons | Recommended Use Case |
 |--------|------|------|---------------------|
-| **Fuzi** | • Fast performance<br>• Memory efficient<br>• libxml2 stability | • Additional dependency<br>• Setup complexity | Large HTML processing |
-| **SwiftSoup** | • Pure Swift<br>• CSS selectors<br>• HTML manipulation | • Relatively slow<br>• High memory usage | When HTML manipulation needed |
+| **SwiftSoup** | • Pure Swift<br>• CSS selectors<br>• HTML manipulation | • Additional dependency<br>• Relatively slow | When HTML manipulation needed |
 | **Custom** | • Full control<br>• Special requirements | • Development time<br>• Maintenance burden | Special parsing rules needed |
 
 ---
 
-## 5. 파서 최적화 팁 / Parser Optimization Tips
+## 4. 파서 최적화 팁 / Parser Optimization Tips
 
 ### 한글
 1. **캐싱**: 동일한 HTML을 반복 파싱하지 않도록 결과를 캐싱
@@ -359,7 +291,7 @@ class CachedHTMLParser: HTMLParserable {
 }
 
 // 사용
-let cachedParser = CachedHTMLParser(baseParser: HTMLFuziParser())
+let cachedParser = CachedHTMLParser(baseParser: HTMLSwiftSoupParser())
 ```
 
 ### 비동기 파싱 / Async Parsing
@@ -426,4 +358,4 @@ extension String {
         return result
     }
 }
-```
\ No newline at end of file
+```
diff --git a/Documentation/Styling.md b/Documentation/Styling.md
index 9666236..4e9421a 100644
--- a/Documentation/Styling.md
+++ b/Documentation/Styling.md
@@ -65,7 +65,7 @@ struct CSSStyleExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -101,7 +101,7 @@ struct FontFamilyExample: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
             .padding()
     }
@@ -127,13 +127,13 @@ struct StyleContainerExample: View {
     var body: some View {
         VStack(spacing: 30) {
             // 작은 폰트, 좁은 줄 간격
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, smallStyleContainer())
                 .border(Color.blue)
             
             // 큰 폰트, 넓은 줄 간격
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, largeStyleContainer())
                 .border(Color.green)
@@ -143,7 +143,11 @@ struct StyleContainerExample: View {
     
     func smallStyleContainer() -> HTMLStyleContainer {
         var container = HTMLStyleContainer()
+#if os(macOS)
+        let font = NSFont.systemFont(ofSize: 12)
+#else
         let font = UIFont.systemFont(ofSize: 12)
+#endif
         container.uiFont = font
         container.textLine = .lineHeight(font: font, lineHeight: 16)
         container.lineBreakMode = .byWordWrapping
@@ -152,7 +156,11 @@ struct StyleContainerExample: View {
     
     func largeStyleContainer() -> HTMLStyleContainer {
         var container = HTMLStyleContainer()
+#if os(macOS)
+        let font = NSFont.systemFont(ofSize: 18)
+#else
         let font = UIFont.systemFont(ofSize: 18)
+#endif
         container.uiFont = font
         container.textLine = .lineHeight(font: font, lineHeight: 28)
         container.lineBreakMode = .byWordWrapping
@@ -184,11 +192,15 @@ struct LineSpacingExample: View {
         VStack(spacing: 20) {
             Text("줄 높이 18pt")
                 .font(.caption)
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
                     let font = UIFont.systemFont(ofSize: 14)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 18)
                     return container
@@ -197,11 +209,15 @@ struct LineSpacingExample: View {
             
             Text("줄 높이 24pt")
                 .font(.caption)
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
                     let font = UIFont.systemFont(ofSize: 14)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 24)
                     return container
@@ -210,11 +226,16 @@ struct LineSpacingExample: View {
             
             Text("줄 간격 8pt")
                 .font(.caption)
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
-                    container.uiFont = .systemFont(ofSize: 14)
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
+                    let font = UIFont.systemFont(ofSize: 14)
+#endif
+                    container.uiFont = font
                     container.textLine = .lineSpacing(spacing: 8)
                     return container
                 }())
@@ -250,12 +271,17 @@ struct LineBreakModeExample: View {
         VStack(spacing: 20) {
             Text("단어 단위 줄바꿈 (byWordWrapping)")
                 .font(.caption)
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
                     container.lineBreakMode = .byWordWrapping
-                    container.uiFont = .systemFont(ofSize: 14)
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
+                    let font = UIFont.systemFont(ofSize: 14)
+#endif
+                    container.uiFont = font
                     return container
                 }())
                 .frame(width: 250)
@@ -263,12 +289,17 @@ struct LineBreakModeExample: View {
             
             Text("문자 단위 줄바꿈 (byCharWrapping)")
                 .font(.caption)
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
                     container.lineBreakMode = .byCharWrapping
-                    container.uiFont = .systemFont(ofSize: 14)
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
+                    let font = UIFont.systemFont(ofSize: 14)
+#endif
+                    container.uiFont = font
                     return container
                 }())
                 .frame(width: 250)
@@ -308,7 +339,7 @@ struct WordBreakExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -362,7 +393,7 @@ struct BoxModelExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -416,7 +447,7 @@ struct BorderStyleExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -467,11 +498,15 @@ struct ComplexStyleExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .htmlEnvironment(\.styleContainer, {
                     var container = HTMLStyleContainer()
+#if os(macOS)
+                    let font = NSFont.systemFont(ofSize: 14)
+#else
                     let font = UIFont.systemFont(ofSize: 14)
+#endif
                     container.uiFont = font
                     container.textLine = .lineHeight(font: font, lineHeight: 20)
                     return container
@@ -514,7 +549,7 @@ struct StyleInheritanceExample: View {
     
     var body: some View {
         ScrollView {
-            HTMLView(html: html, parser: HTMLFuziParser())
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
                 .htmlEnvironment(\.configuration, .default)
                 .padding()
         }
@@ -534,4 +569,5 @@ struct StyleInheritanceExample: View {
 - Not all CSS properties are supported. Use only the properties listed above.
 - HTMLStyleContainer is a global setting that affects all elements.
 - Inline styles have higher priority than HTMLStyleContainer settings.
-- Colors can use hex codes (#RRGGBB) or color names (red, blue, etc.).
\ No newline at end of file
+- Colors can use hex codes (#RRGGBB) or color names (red, blue, etc.).
+- For performance testing, use the Example app’s Testing section and the "Synthetic Stress" sample with higher section counts.
diff --git a/Example/ContentView.swift b/Example/ContentView.swift
index 1d99c3d..324cbd4 100644
--- a/Example/ContentView.swift
+++ b/Example/ContentView.swift
@@ -40,6 +40,7 @@ enum SampleCategory: String, CaseIterable, Identifiable {
                 SampleItem(title: "Text Styling", description: "Bold, italic, underline", view: TextStyleSample()),
                 SampleItem(title: "Image & Links", description: "Images and links example", view: ImageLinkSample()),
                 SampleItem(title: "Block Elements", description: "Block element structure", view: BlockElementSample()),
+                SampleItem(title: "Ruby Tags", description: "Ruby annotations with rt", view: RubyTagSample()),
                 SampleItem(title: "Line Break Modes", description: "Line break mode comparison", view: LineBreakSample())
             ]
         case .styling:
@@ -57,13 +58,18 @@ enum SampleCategory: String, CaseIterable, Identifiable {
                 SampleItem(title: "Highlight Tag", description: "Highlight inline tag", view: HighlightTagSample())
             ]
         case .parserIntegration:
-            return [
-                SampleItem(title: "Current Parser", description: "Currently used Fuzi parser", view: AnyView(CurrentParserSample())),
+            var items: [SampleItem] = [
+                SampleItem(title: "Current Parser", description: "Currently used SwiftSoup parser", view: AnyView(CurrentParserSample())),
                 SampleItem(title: "Complex HTML", description: "Complex HTML structure parsing", view: AnyView(ComplexHTMLSample()))
             ]
+#if canImport(SwiftSoup)
+            items.append(SampleItem(title: "SwiftSoup Parser", description: "Parser integration sample", view: AnyView(SwiftSoupParserSample())))
+#endif
+            return items
         case .testing:
             return [
-                SampleItem(title: "Snapshot Test Preview", description: "Snapshot test preview - Image positioning and line height", view: SnapshotTestSample())
+                SampleItem(title: "Snapshot Test Preview", description: "Snapshot test preview - Image positioning and line height", view: SnapshotTestSample()),
+                SampleItem(title: "Synthetic Stress", description: "Large synthetic HTML payload", view: SyntheticStressSample())
             ]
         }
     }
@@ -134,7 +140,7 @@ struct ContentView: View {
                 }
             }
             .navigationTitle("Examples")
-            .navigationBarTitleDisplayMode(.inline)
+            .applyInlineNavigationTitleDisplayMode()
         }
     }
 }
diff --git a/Example/Custom/HTMLFuziParser.swift b/Example/Custom/HTMLFuziParser.swift
deleted file mode 100644
index b0f6440..0000000
--- a/Example/Custom/HTMLFuziParser.swift
+++ /dev/null
@@ -1,76 +0,0 @@
-//  Copyright © 2025 PRND. All rights reserved.
-import Foundation
-
-import SwiftUIHTML
-import Fuzi
-
-struct HTMLFuziParser: HTMLParserable {
-    struct ParserError: LocalizedError {
-        let errorDescription: String?
-    }
-    init() {
-
-    }
-
-    func parse(html: String) -> HTMLNode {
-        do {
-            let _html = WhiteSpace(html: html).toNormal()
-            let document = try HTMLDocument.parse(string: _html, encoding: String.Encoding.utf8)
-
-            guard let rootElement = document.root else {
-                throw ParserError(errorDescription: "No body element found")
-            }
-            return try elementToHTMLNode(element: rootElement)
-        } catch {
-            return HTMLNode(tag: "div", children: [.text("failed parsing HTML: \(error.localizedDescription)")])
-        }
-    }
-
-    func elementToHTMLNode(element: Fuzi.XMLElement) throws -> HTMLNode {
-        let tag = element.tag ?? ""
-
-        let attributes = element.attributes.reduce(into: [String: String]()) { result, attribute in
-            result[attribute.key] = attribute.value
-        }
-
-        let children: [HTMLChild] = try element.childNodes(ofTypes: [.Element, .Text]).compactMap { node -> HTMLChild? in
-            if node.type == .Text {
-                let text = node.stringValue
-                return text.isEmpty ? nil : .text(text)
-            } else if let element = node.toElement() {
-                if element.tag == "br" {
-                    return .newLine
-                }
-                return .node(try elementToHTMLNode(element: element))
-            } else {
-                return nil
-            }
-        }
-
-        return HTMLNode(tag: tag, attributes: attributes, children: children)
-    }
-
-    struct WhiteSpace {
-        let html: String
-
-        func toNormal() -> String {
-            var result = html
-            
-            // Remove line breaks before tags: \n<tag> → <tag>
-            result = result.replacingOccurrences(
-                of: #"\n\s*(?=<\/?[a-zA-Z])"#,
-                with: "",
-                options: .regularExpression
-            )
-            
-            // Remove line breaks right after tags: <tag>\ntext → <tag>text
-            result = result.replacingOccurrences(
-                of: #"(?<=>)\s*\n\s*(?=[^<])"#,
-                with: "",
-                options: .regularExpression
-            )
-            
-            return result
-        }
-    }
-}
diff --git a/Example/Custom/HTMLStyleContainer+sample.swift b/Example/Custom/HTMLStyleContainer+sample.swift
index cbf8668..bc048a5 100644
--- a/Example/Custom/HTMLStyleContainer+sample.swift
+++ b/Example/Custom/HTMLStyleContainer+sample.swift
@@ -1,12 +1,23 @@
 //  Copyright © 2025 PRND. All rights reserved.
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
 import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 import SwiftUIHTML
 
 extension HTMLStyleContainer {
     static func sample(by lineBreakMode: LineBreakMode) -> HTMLStyleContainer {
         var style = HTMLStyleContainer()
-        let font = UIFont.systemFont(ofSize: 12)
+        let font = ExampleFont.systemFont(ofSize: 12)
         style.uiFont = font
         style.textLine = .lineHeight(font: font, lineHeight: 24)
         style.lineBreakMode = lineBreakMode
diff --git a/Example/Custom/HTMLSwiftSoupParser.swift b/Example/Custom/HTMLSwiftSoupParser.swift
new file mode 100644
index 0000000..c161b25
--- /dev/null
+++ b/Example/Custom/HTMLSwiftSoupParser.swift
@@ -0,0 +1,255 @@
+//  Copyright © 2024 PRND. All rights reserved.
+import Foundation
+import SwiftSoup
+import SwiftUIHTML
+
+struct HTMLSwiftSoupParser: HTMLParserable {
+    func parse(html: String) -> HTMLNode {
+        do {
+            let document = try SwiftSoup.parse(html)
+            if let body = document.body() {
+                if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1" {
+                    let style = (try? body.attr("style")) ?? ""
+                    print("[SwiftSoupParser] body attr style=\(style)")
+                    if let attrs = body.getAttributes(), attrs.size() > 0 {
+                        print("[SwiftSoupParser] body attr count=\(attrs.size())")
+                        for attr in attrs {
+                            print("[SwiftSoupParser] body attr \(attr.getKey())=\(attr.getValue())")
+                        }
+                    }
+                }
+                if let selectedBody = try? document.select("body").first(),
+                   !selectedBody.equals(body),
+                   (try? selectedBody.attr("style").isEmpty) == false {
+                    if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1" {
+                        let style = (try? selectedBody.attr("style")) ?? ""
+                        print("[SwiftSoupParser] using selected body with style=\(style)")
+                    }
+                    return try buildHTMLNode(from: selectedBody)
+                }
+                if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1" {
+                    logBodyChildren(body)
+                }
+                return try buildHTMLNode(from: body)
+            }
+            if let root = try document.select("*").first() {
+                return try buildHTMLNode(from: root)
+            }
+        } catch {
+            return HTMLNode(tag: "div", children: [.text("failed parsing HTML: \(error.localizedDescription)")])
+        }
+        return HTMLNode(tag: "div", children: [])
+    }
+
+    // no-op: style extraction intentionally removed; rely on SwiftSoup attributes.
+
+    private func logBodyChildren(_ body: Element) {
+        var lines: [String] = []
+        lines.reserveCapacity(body.childNodeSize() + 1)
+        lines.append("[Parser] body children=\(body.childNodeSize())")
+        for child in body.getChildNodes() {
+            if let textNode = child as? TextNode {
+                let text = normalizeText(
+                    textNode,
+                    preserveWhitespace: HTMLSwiftSoupParser.shouldPreserveWhitespace(in: body.tagName())
+                )
+                let preview = text
+                    .replacingOccurrences(of: "\n", with: "\\n")
+                    .replacingOccurrences(of: "\t", with: "\\t")
+                lines.append("[Parser] text len=\(text.count) preview=\(preview)")
+            } else if let element = child as? Element {
+                lines.append("[Parser] element tag=\(element.tagName()) children=\(element.childNodeSize())")
+            } else {
+                lines.append("[Parser] node type=\(type(of: child))")
+            }
+        }
+        let payload = lines.joined(separator: "\n") + "\n"
+        let url = URL(fileURLWithPath: "/tmp/swiftuihtml-parser.log")
+        if let data = payload.data(using: .utf8) {
+            if let handle = try? FileHandle(forWritingTo: url) {
+                try? handle.seekToEnd()
+                try? handle.write(contentsOf: data)
+                try? handle.close()
+            } else {
+                try? data.write(to: url)
+            }
+        }
+    }
+
+    @inline(__always)
+    private func normalizeText(_ node: TextNode, preserveWhitespace: Bool) -> String {
+        let text = node.text()
+        guard !preserveWhitespace else { return text }
+        var result = String()
+        result.reserveCapacity(text.count)
+        var lastWasWhitespace = false
+        for scalar in text.unicodeScalars {
+            let isWhitespace: Bool
+            if scalar.isASCII {
+                isWhitespace = ASCIIWhitespace.isWhitespace(UInt8(scalar.value))
+            } else {
+                isWhitespace = scalar.properties.isWhitespace
+            }
+            if isWhitespace {
+                if !lastWasWhitespace {
+                    result.append(" ")
+                    lastWasWhitespace = true
+                }
+            } else {
+                result.append(String(scalar))
+                lastWasWhitespace = false
+            }
+        }
+        return result.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private func buildHTMLNode(from root: Element) throws -> HTMLNode {
+        try buildHTMLNodeIterative(from: root)
+    }
+
+    fileprivate static let blockTags: Set<String> = [
+        "address", "article", "aside", "blockquote", "body", "canvas", "dd", "div", "dl",
+        "dt", "fieldset", "figcaption", "figure", "footer", "form", "h1", "h2", "h3",
+        "h4", "h5", "h6", "header", "hr", "html", "li", "main", "nav", "noscript", "ol",
+        "p", "pre", "section", "table", "tbody", "td", "tfoot", "th", "thead", "tr", "ul"
+    ]
+
+    fileprivate static func shouldDropWhitespaceText(_ text: String, in parentTag: String) -> Bool {
+        let trimmed = ASCIIWhitespace.trim(text)
+        if !trimmed.isEmpty {
+            return false
+        }
+        return blockTags.contains(parentTag)
+    }
+
+    fileprivate static let whitespacePreservingTags: Set<String> = [
+        "pre", "code", "textarea"
+    ]
+
+    fileprivate static func shouldPreserveWhitespace(in tag: String) -> Bool {
+        whitespacePreservingTags.contains(tag)
+    }
+}
+
+extension HTMLSwiftSoupParser {
+    private final class Builder {
+        private static let emptyAttributes: [String: String] = [:]
+
+        let tag: String
+        let isBlockParent: Bool
+        let attributes: [String: String]
+        let childNodes: [Node]
+        let capacityHint: Int
+        var childIndex: Int
+        var children: [HTMLChild]?
+
+        init(element: Element) {
+            let tag = element.tagName()
+            self.tag = tag
+            self.isBlockParent = HTMLSwiftSoupParser.blockTags.contains(tag)
+            if let rawAttributes = element.getAttributes(), rawAttributes.size() > 0 {
+                var attributes: [String: String] = [:]
+                attributes.reserveCapacity(rawAttributes.size())
+                for attribute in rawAttributes {
+                    attributes[attribute.getKey()] = attribute.getValue()
+                }
+                self.attributes = attributes
+            } else {
+                self.attributes = Self.emptyAttributes
+            }
+            if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1",
+               tag == "body" {
+                print("[SwiftSoupParser] builder body attrs=\(self.attributes)")
+            }
+            let count = element.childNodeSize()
+            self.capacityHint = count
+            if count > 0 {
+                self.childNodes = element.getChildNodes()
+            } else {
+                self.childNodes = []
+            }
+            self.childIndex = 0
+            self.children = nil
+        }
+
+        func appendChild(_ child: HTMLChild) {
+            if children == nil {
+                var storage: [HTMLChild] = []
+                if capacityHint > 0 {
+                    storage.reserveCapacity(capacityHint)
+                }
+                children = storage
+            }
+            children?.append(child)
+        }
+    }
+
+    func buildHTMLNodeIterative(from root: Element) throws -> HTMLNode {
+        var stack: [Builder] = []
+        stack.reserveCapacity(64)
+        stack.append(Builder(element: root))
+
+        while let current = stack.last {
+            if current.childIndex < current.capacityHint {
+                let child = current.childNodes[current.childIndex]
+                current.childIndex += 1
+
+                if let textNode = child as? TextNode {
+                    let text = normalizeText(
+                        textNode,
+                        preserveWhitespace: HTMLSwiftSoupParser.shouldPreserveWhitespace(in: current.tag)
+                    )
+                    if !text.isEmpty {
+                        if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1" {
+                            let trimmed = ASCIIWhitespace.trim(text)
+                            if trimmed.isEmpty, current.tag == "body" {
+                                let preview = text
+                                    .replacingOccurrences(of: "\n", with: "\\n")
+                                    .replacingOccurrences(of: "\t", with: "\\t")
+                                print("[SwiftSoupParser] whitespace in <body> len=\\(text.count) preview=\\(preview)")
+                            }
+                        }
+                        if current.isBlockParent && HTMLSwiftSoupParser.shouldDropWhitespaceText(text, in: current.tag) {
+                            if ProcessInfo.processInfo.environment["SWIFTUIHTML_PARSER_LOGS"] == "1" {
+                                print("[SwiftSoupParser] drop whitespace text in <\(current.tag)> len=\(text.count)")
+                            }
+                            continue
+                        }
+                        current.appendChild(.text(text))
+                    }
+                    continue
+                }
+                if let elementNode = child as? Element {
+                    if isBRTag(elementNode.tagName()) {
+                        current.appendChild(.newLine)
+                        continue
+                    }
+                    stack.append(Builder(element: elementNode))
+                }
+            } else {
+                _ = stack.popLast()
+                let built = HTMLNode(
+                    tag: current.tag,
+                    attributes: current.attributes,
+                    children: current.children ?? []
+                )
+                if stack.isEmpty {
+                    return built
+                }
+                stack[stack.count - 1].appendChild(.node(built))
+            }
+        }
+
+        return HTMLNode(tag: "div", children: [])
+    }
+}
+
+@inline(__always)
+private func isBRTag(_ raw: String) -> Bool {
+    var iterator = raw.utf8.makeIterator()
+    guard let first = iterator.next(), let second = iterator.next() else { return false }
+    if iterator.next() != nil { return false }
+    let isB = first == 0x62 || first == 0x42
+    let isR = second == 0x72 || second == 0x52
+    return isB && isR
+}
diff --git a/Example/Custom/TagView/HeadinglevelTagView.swift b/Example/Custom/TagView/HeadinglevelTagView.swift
index a3065d9..31a7cee 100644
--- a/Example/Custom/TagView/HeadinglevelTagView.swift
+++ b/Example/Custom/TagView/HeadinglevelTagView.swift
@@ -1,5 +1,17 @@
 //  Copyright © 2025 PRND. All rights reserved.
 import SwiftUI
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 import SwiftUIHTML
 
@@ -11,7 +23,7 @@ struct Headinglevel1TagView: BlockTag {
     }
 
     static func applyStyles(with attributes: [String : AttributeValue], to styleContainer: inout HTMLStyleContainer) {
-        styleContainer.uiFont = UIFont.boldSystemFont(ofSize: 24)
+        styleContainer.uiFont = ExampleFont.boldSystemFont(ofSize: 24)
     }
 }
 
@@ -23,7 +35,7 @@ struct Headinglevel2TagView: BlockTag {
         self.element = element
     }
     static func applyStyles(with attributes: [String : AttributeValue], to styleContainer: inout HTMLStyleContainer) {
-        styleContainer.uiFont = UIFont.boldSystemFont(ofSize: 20)
+        styleContainer.uiFont = ExampleFont.boldSystemFont(ofSize: 20)
     }
 }
 
@@ -36,6 +48,6 @@ struct Headinglevel3TagView: BlockTag {
     }
 
     static func applyStyles(with attributes: [String : AttributeValue], to styleContainer: inout HTMLStyleContainer) {
-        styleContainer.uiFont = UIFont.boldSystemFont(ofSize: 18)
+        styleContainer.uiFont = ExampleFont.boldSystemFont(ofSize: 18)
     }
 }
diff --git a/Example/Custom/TagView/ULTagView.swift b/Example/Custom/TagView/ULTagView.swift
index 33e5f34..0fc2b84 100644
--- a/Example/Custom/TagView/ULTagView.swift
+++ b/Example/Custom/TagView/ULTagView.swift
@@ -24,14 +24,27 @@ struct ULTagView: BlockTag {
     }
 
     func liTag(liElement: BlockElement) -> some View {
-        HStack(alignment: .top, spacing: .zero) {
-            HTMLText(" • ")
+        let isImageOnly = liIsImageOnly(liElement)
+        let alignment: VerticalAlignment = isImageOnly ? .center : .firstTextBaseline
+        return HStack(alignment: alignment, spacing: .zero) {
+            markerView(isImageOnly: isImageOnly)
             VStack(alignment: .leading, spacing: 4) {
                 HTMLBlock(element: liElement)
             }
         }
     }
 
+    @ViewBuilder
+    func markerView(isImageOnly: Bool) -> some View {
+        let marker = HTMLText(" • ", applyVerticalPadding: false)
+        if isImageOnly {
+            // Nudge list marker upward to visually center with image-only items.
+            marker.offset(y: -0.7)
+        } else {
+            marker
+        }
+    }
+
     func indent(_ index: Int) -> CGFloat {
         if index == .zero { return .zero }
         return 16
@@ -45,6 +58,34 @@ struct ULTagView: BlockTag {
             }
         return Array(zip(result.indices, result))
     }
+
+    func liIsImageOnly(_ element: BlockElement) -> Bool {
+        var hasAttachment = false
+        for content in element.contents {
+            switch content {
+            case .block:
+                return false
+            case .inline(let inline):
+                if isInlineAttachment(inline) {
+                    hasAttachment = true
+                    continue
+                }
+                let text = inline.debugDescription
+                if !ASCIIWhitespace.trim(text).isEmpty {
+                    return false
+                }
+            }
+        }
+        return hasAttachment
+    }
+
+    func isInlineAttachment(_ inline: InlineElement) -> Bool {
+        let tag = inline.tag.lowercased()
+        if tag == "img" || inline.attributes["src"] != nil {
+            return true
+        }
+        return false
+    }
 }
 
 
diff --git a/Example/Samples/BasicUsage/BlockElementSample.swift b/Example/Samples/BasicUsage/BlockElementSample.swift
index 7dafee5..dc1b4ac 100644
--- a/Example/Samples/BasicUsage/BlockElementSample.swift
+++ b/Example/Samples/BasicUsage/BlockElementSample.swift
@@ -52,11 +52,11 @@ struct BlockElementSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Supported Block Tags
@@ -102,7 +102,7 @@ struct BlockElementSample: View {
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -121,9 +121,10 @@ struct BlockElementSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Block Elements")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/BasicUsage/ImageLinkSample.swift b/Example/Samples/BasicUsage/ImageLinkSample.swift
index dd2243e..a2c289a 100644
--- a/Example/Samples/BasicUsage/ImageLinkSample.swift
+++ b/Example/Samples/BasicUsage/ImageLinkSample.swift
@@ -2,6 +2,18 @@
 
 import SwiftUI
 import SwiftUIHTML
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 struct ImageLinkSample: View {
     @State private var htmlCode = """
@@ -79,18 +91,18 @@ struct ImageLinkSample: View {
                     Text("Rendering Result")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 15)
+                            let font = ExampleFont.systemFont(ofSize: 15)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 22)
                             container.lineBreakMode = .byWordWrapping
                             return container
                         }())
                         .padding()
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                 }
                 
@@ -111,12 +123,12 @@ struct ImageLinkSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 200)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -172,9 +184,10 @@ struct ImageLinkSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Images & Links")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
@@ -182,4 +195,4 @@ struct ImageLinkSample: View {
     NavigationView {
         ImageLinkSample()
     }
-}
\ No newline at end of file
+}
diff --git a/Example/Samples/BasicUsage/LineBreakSample.swift b/Example/Samples/BasicUsage/LineBreakSample.swift
index 23cc22a..a7b9d04 100644
--- a/Example/Samples/BasicUsage/LineBreakSample.swift
+++ b/Example/Samples/BasicUsage/LineBreakSample.swift
@@ -2,6 +2,18 @@
 
 import SwiftUI
 import SwiftUIHTML
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 struct LineBreakSample: View {
     @State private var htmlCode = """
@@ -55,11 +67,11 @@ struct LineBreakSample: View {
                     Text("Word-based line breaking (.byWordWrapping)")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 20)
                             container.lineBreakMode = .byWordWrapping
@@ -79,11 +91,11 @@ struct LineBreakSample: View {
                     Text("Character-based line breaking (.byCharWrapping)")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 20)
                             container.lineBreakMode = .byCharWrapping
@@ -115,12 +127,12 @@ struct LineBreakSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 150)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -199,9 +211,10 @@ struct LineBreakSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Line Break Modes")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
@@ -209,4 +222,4 @@ struct LineBreakSample: View {
     NavigationView {
         LineBreakSample()
     }
-}
\ No newline at end of file
+}
diff --git a/Example/Samples/BasicUsage/RubyTagSample.swift b/Example/Samples/BasicUsage/RubyTagSample.swift
new file mode 100644
index 0000000..810bb2a
--- /dev/null
+++ b/Example/Samples/BasicUsage/RubyTagSample.swift
@@ -0,0 +1,74 @@
+//  Copyright © 2025 PRND. All rights reserved.
+
+import SwiftUI
+import SwiftUIHTML
+
+struct RubyTagSample: View {
+    private let html = """
+        <p>Ruby annotation rendering:</p>
+        <p>
+            <ruby style="font-size: 20px; color: #1a4;">
+                漢字<rt>かんじ</rt>
+            </ruby>
+            を読む
+        </p>
+        <p>
+            <ruby>
+                学校<rt>がっこう</rt>
+            </ruby>
+            へ行く
+        </p>
+        <p>
+            <ruby ruby-position="after" ruby-scale="0.5">
+                今日<rt>きょう</rt>
+            </ruby>
+            は晴れです
+        </p>
+        """
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 16) {
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("Ruby Annotations")
+                        .font(.largeTitle)
+                        .fontWeight(.bold)
+
+                    Text("Basic <ruby>/<rt> support using CoreText")
+                        .font(.subheadline)
+                        .foregroundColor(.secondary)
+                }
+
+                Divider()
+
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
+                    .htmlEnvironment(\.configuration, .sample)
+                    .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+                    .padding()
+                    .background(Color.platformSystemGray6)
+                    .cornerRadius(8)
+
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("HTML")
+                        .font(.headline)
+
+                    Text(html)
+                        .font(.system(.body, design: .monospaced))
+                        .padding()
+                        .background(Color.platformSystemGray6)
+                        .cornerRadius(8)
+                }
+            }
+            .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+        .navigationTitle("Ruby Tags")
+        .applyInlineNavigationTitleDisplayMode()
+    }
+}
+
+#Preview {
+    NavigationView {
+        RubyTagSample()
+    }
+}
diff --git a/Example/Samples/BasicUsage/TextStyleSample.swift b/Example/Samples/BasicUsage/TextStyleSample.swift
index 2204a05..0be5024 100644
--- a/Example/Samples/BasicUsage/TextStyleSample.swift
+++ b/Example/Samples/BasicUsage/TextStyleSample.swift
@@ -73,11 +73,11 @@ struct TextStyleSample: View {
                     Text("Rendering Result")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                         .padding()
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                 }
                 
@@ -98,12 +98,12 @@ struct TextStyleSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 150)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -161,9 +161,10 @@ struct TextStyleSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Text Styling")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/CustomTags/CustomHeadingSample.swift b/Example/Samples/CustomTags/CustomHeadingSample.swift
index 6ae21a2..c614994 100644
--- a/Example/Samples/CustomTags/CustomHeadingSample.swift
+++ b/Example/Samples/CustomTags/CustomHeadingSample.swift
@@ -38,11 +38,11 @@ struct CustomHeadingSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Custom Tag Description
@@ -81,7 +81,7 @@ struct Headinglevel3TagView: BlockTag {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -98,7 +98,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -117,9 +117,10 @@ let configuration = HTMLConfiguration.default
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Custom Headings")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/CustomTags/CustomListSample.swift b/Example/Samples/CustomTags/CustomListSample.swift
index 76f01dc..ef0df04 100644
--- a/Example/Samples/CustomTags/CustomListSample.swift
+++ b/Example/Samples/CustomTags/CustomListSample.swift
@@ -48,11 +48,11 @@ struct CustomListSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Implementation Description
@@ -96,7 +96,7 @@ struct ULTagView: BlockTag {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -111,7 +111,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -130,7 +130,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -150,9 +150,10 @@ let configuration = HTMLConfiguration.default
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Custom List Tags")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/CustomTags/HighlightTagSample.swift b/Example/Samples/CustomTags/HighlightTagSample.swift
index 6c1f331..e1149bc 100644
--- a/Example/Samples/CustomTags/HighlightTagSample.swift
+++ b/Example/Samples/CustomTags/HighlightTagSample.swift
@@ -82,11 +82,11 @@ struct HighlightTagSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, highlightConfiguration)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // InlineTag Description
@@ -121,7 +121,7 @@ struct HighlightTag: InlineTag {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -137,7 +137,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -160,7 +160,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -198,9 +198,10 @@ let configuration = HTMLConfiguration.default
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Highlight Tag")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/CustomTags/VideoTagSample.swift b/Example/Samples/CustomTags/VideoTagSample.swift
index 4f16482..552fd82 100644
--- a/Example/Samples/CustomTags/VideoTagSample.swift
+++ b/Example/Samples/CustomTags/VideoTagSample.swift
@@ -33,11 +33,11 @@ struct VideoTagSample: View {
                 Divider()
                 
                 // HTML rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Video tag description
@@ -75,7 +75,7 @@ struct VideoTagView: BlockTag, Equatable {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -90,7 +90,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -104,7 +104,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -140,9 +140,10 @@ let configuration = HTMLConfiguration.default
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Video Tag")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/ParserIntegration/ComplexHTMLSample.swift b/Example/Samples/ParserIntegration/ComplexHTMLSample.swift
index e3985a9..1a71676 100644
--- a/Example/Samples/ParserIntegration/ComplexHTMLSample.swift
+++ b/Example/Samples/ParserIntegration/ComplexHTMLSample.swift
@@ -2,6 +2,18 @@
 
 import SwiftUI
 import SwiftUIHTML
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 struct ComplexHTMLSample: View {
     let html = """
@@ -91,21 +103,21 @@ struct ComplexHTMLSample: View {
                 Divider()
                 
                 // HTML 렌더링
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, {
                         var container = HTMLStyleContainer()
-                        let font = UIFont.systemFont(ofSize: 14)
+                        let font = ExampleFont.systemFont(ofSize: 14)
                         container.uiFont = font
                         container.textLine = .lineHeight(font: font, lineHeight: 20)
                         container.lineBreakMode = .byWordWrapping
                         return container
                     }())
                     .padding()
-                    .background(Color(.systemBackground))
+                    .background(platformBackgroundColor)
                     .overlay(
                         RoundedRectangle(cornerRadius: 8)
-                            .stroke(Color(.systemGray5), lineWidth: 1)
+                            .stroke(Color.platformSystemGray5, lineWidth: 1)
                     )
                 
                 // 복잡성 설명
@@ -130,7 +142,7 @@ struct ComplexHTMLSample: View {
                         .font(.headline)
                     
                     VStack(alignment: .leading, spacing: 4) {
-                        Text("1. HTML 문자열을 Fuzi로 파싱")
+                        Text("1. HTML 문자열을 SwiftSoup로 파싱")
                         Text("2. DOM 트리를 HTMLNode 구조로 변환")
                         Text("3. 각 요소의 속성과 스타일 추출")
                         Text("4. SwiftUI View 계층으로 렌더링")
@@ -178,19 +190,28 @@ struct ComplexHTMLSample: View {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Complex HTML")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
+private var platformBackgroundColor: Color {
+#if os(macOS)
+    return Color(nsColor: .windowBackgroundColor)
+#else
+    return Color(.systemBackground)
+#endif
+}
+
 #Preview {
     NavigationView {
         ComplexHTMLSample()
     }
-}
\ No newline at end of file
+}
diff --git a/Example/Samples/ParserIntegration/CurrentParserSample.swift b/Example/Samples/ParserIntegration/CurrentParserSample.swift
index f88f185..213d0f5 100644
--- a/Example/Samples/ParserIntegration/CurrentParserSample.swift
+++ b/Example/Samples/ParserIntegration/CurrentParserSample.swift
@@ -5,16 +5,16 @@ import SwiftUIHTML
 
 struct CurrentParserSample: View {
     let html = """
-        <h2>Current Parser: HTMLFuziParser</h2>
+        <h2>Current Parser: HTMLSwiftSoupParser</h2>
         
-        <p>This app uses the <strong>Fuzi</strong> library to parse HTML.</p>
+        <p>This app uses the <strong>SwiftSoup</strong> library to parse HTML.</p>
         
         <div style="border: 1px solid #ccc; padding: 12px; background-color: #f9f9f9;">
-            <h3>Features of Fuzi Parser:</h3>
+            <h3>Features of SwiftSoup Parser:</h3>
             <p>
-                • <strong>Fast Performance</strong>: libxml2 based<br>
-                • <strong>Memory Efficient</strong>: Optimized parsing<br>
-                • <strong>XML/HTML Support</strong>: Various format handling
+                • <strong>HTML Parsing</strong>: Robust HTML parsing in Swift<br>
+                • <strong>CSS Selectors</strong>: Query and traverse elements<br>
+                • <strong>Document Model</strong>: Easy element access and manipulation
             </p>
         </div>
         
@@ -36,7 +36,7 @@ struct CurrentParserSample: View {
                         .font(.largeTitle)
                         .fontWeight(.bold)
                     
-                    Text("Currently using HTMLFuziParser")
+                    Text("Currently using HTMLSwiftSoupParser")
                         .font(.subheadline)
                         .foregroundColor(.secondary)
                 }
@@ -44,19 +44,19 @@ struct CurrentParserSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Parser Information
                 VStack(alignment: .leading, spacing: 8) {
-                    Text("HTMLFuziParser")
+                    Text("HTMLSwiftSoupParser")
                         .font(.headline)
                     
-                    Text("The default parser used in the Example project. Converts HTML to HTMLNode structure based on the Fuzi library.")
+                    Text("The default parser used in the Example project. Converts HTML to HTMLNode structure based on the SwiftSoup library.")
                         .font(.body)
                 }
                 
@@ -66,14 +66,15 @@ struct CurrentParserSample: View {
                         .font(.headline)
                     
                     Text("""
-struct HTMLFuziParser: HTMLParserable {
+struct HTMLSwiftSoupParser: HTMLParserable {
     func parse(html: String) -> HTMLNode {
         do {
-            let document = try HTMLDocument(string: html, encoding: .utf8)
-            guard let rootElement = document.root else {
-                throw ParseError.noRootElement
+            let document = try SwiftSoup.parse(html)
+            if let body = document.body() {
+                return try elementToHTMLNode(element: body)
             }
-            return try elementToHTMLNode(element: rootElement)
+            let wrapper = try document.select("*").first() ?? document
+            return try elementToHTMLNode(element: wrapper)
         } catch {
             return HTMLNode(tag: "div", children: [.text("Parse error")])
         }
@@ -82,21 +83,21 @@ struct HTMLFuziParser: HTMLParserable {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
                 // Advantages
                 VStack(alignment: .leading, spacing: 8) {
-                    Text("Fuzi Parser Advantages")
+                    Text("SwiftSoup Parser Advantages")
                         .font(.headline)
                     
                     VStack(alignment: .leading, spacing: 4) {
                         Text("• Fast parsing performance")
-                        Text("• Memory efficient")
+                        Text("• CSS selector support")
                         Text("• Accurate HTML structure analysis")
-                        Text("• libxml2-based stability")
-                        Text("• Various HTML format support")
+                        Text("• Pure Swift parser")
+                        Text("• Flexible HTML manipulation")
                     }
                     .font(.body)
                 }
@@ -106,15 +107,16 @@ struct HTMLFuziParser: HTMLParserable {
                     Text("Parser Selection Guide")
                         .font(.headline)
                     
-                    Text("SwiftUIHTML can use any parser that implements the HTMLParserable protocol. You can choose Fuzi, SwiftSoup, or custom parsers.")
+                    Text("SwiftUIHTML can use any parser that implements the HTMLParserable protocol. You can choose SwiftSoup or custom parsers.")
                         .font(.body)
                         .foregroundColor(.secondary)
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Current Parser")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
@@ -122,4 +124,4 @@ struct HTMLFuziParser: HTMLParserable {
     NavigationView {
         CurrentParserSample()
     }
-}
\ No newline at end of file
+}
diff --git a/Example/Samples/ParserIntegration/SwiftSoupParserSample.swift b/Example/Samples/ParserIntegration/SwiftSoupParserSample.swift
new file mode 100644
index 0000000..aa62f8f
--- /dev/null
+++ b/Example/Samples/ParserIntegration/SwiftSoupParserSample.swift
@@ -0,0 +1,32 @@
+//  Copyright © 2026 PRND. All rights reserved.
+
+#if canImport(SwiftSoup)
+import SwiftUI
+import SwiftUIHTML
+
+struct SwiftSoupParserSample: View {
+    private let html = """
+    <div class="parser-sample">
+        <h2>SwiftSoup Parser</h2>
+        <p id="description">Parsed with <em>SwiftSoup</em> and converted to HTMLNode.</p>
+        <p>Ruby: <ruby ruby-position="after">漢字<rt>かんじ</rt></ruby></p>
+        <p>Line break<br>after br tag.</p>
+    </div>
+    """
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            Text("SwiftSoup Parser")
+                .font(.title2)
+                .fontWeight(.semibold)
+
+            HTMLView(html: html, parser: HTMLSwiftSoupParser())
+                .htmlEnvironment(\.configuration, .sample)
+        }
+        .padding()
+        .navigationTitle("SwiftSoup Parser")
+        .applyInlineNavigationTitleDisplayMode()
+    }
+}
+
+#endif
diff --git a/Example/Samples/QuickStart/HelloWorldSample.swift b/Example/Samples/QuickStart/HelloWorldSample.swift
index 8082e0d..d046004 100644
--- a/Example/Samples/QuickStart/HelloWorldSample.swift
+++ b/Example/Samples/QuickStart/HelloWorldSample.swift
@@ -27,11 +27,11 @@ struct HelloWorldSample: View {
                 Divider()
                 
                 // HTML rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Code
@@ -46,13 +46,13 @@ let html = \"\"\"
     <p>This is the simplest HTML rendering example.</p>
 \"\"\"
 
-HTMLView(html: html, parser: HTMLFuziParser())
+HTMLView(html: html, parser: HTMLSwiftSoupParser())
     .htmlEnvironment(\\.configuration, .sample)
     .htmlEnvironment(\\.styleContainer, .sample(by: .byWordWrapping))
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -63,7 +63,7 @@ HTMLView(html: html, parser: HTMLFuziParser())
                     
                     VStack(alignment: .leading, spacing: 4) {
                         Text("• HTMLView: Main component for rendering HTML")
-                        Text("• HTMLFuziParser: Parser using the Fuzi library")
+                        Text("• HTMLSwiftSoupParser: Parser using the SwiftSoup library")
                         Text("• .sample: Default configuration for examples")
                         Text("• .byWordWrapping: Word-based line breaking")
                     }
@@ -71,9 +71,10 @@ HTMLView(html: html, parser: HTMLFuziParser())
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Hello SwiftUIHTML")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/QuickStart/READMEBasicUsageSample.swift b/Example/Samples/QuickStart/READMEBasicUsageSample.swift
index cf90e0d..181d64f 100644
--- a/Example/Samples/QuickStart/READMEBasicUsageSample.swift
+++ b/Example/Samples/QuickStart/READMEBasicUsageSample.swift
@@ -45,11 +45,11 @@ struct READMEBasicUsageSample: View {
                     Text("Rendering Result")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, createStyleContainer())
                         .padding()
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                 }
                 
@@ -70,12 +70,12 @@ struct READMEBasicUsageSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 120)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -96,7 +96,7 @@ struct ContentView: View {
         \"\"\"
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\\.configuration, .default)
             .htmlEnvironment(\\.styleContainer, createStyleContainer())
     }
@@ -111,7 +111,7 @@ struct ContentView: View {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -123,7 +123,7 @@ struct ContentView: View {
                     VStack(alignment: .leading, spacing: 4) {
                         Text("• Same example as basic usage in README.md")
                         Text("• Edit HTML directly and check results with 'Apply' button")
-                        Text("• Basic usage of HTMLView + HTMLFuziParser")
+                        Text("• Basic usage of HTMLView + HTMLSwiftSoupParser")
                         Text("• Font and line break settings with HTMLStyleContainer")
                     }
                     .font(.body)
@@ -162,9 +162,10 @@ struct ContentView: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("README Basic Usage")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/QuickStart/READMECSSStyling.swift b/Example/Samples/QuickStart/READMECSSStyling.swift
index 8ed789b..68319a9 100644
--- a/Example/Samples/QuickStart/READMECSSStyling.swift
+++ b/Example/Samples/QuickStart/READMECSSStyling.swift
@@ -76,11 +76,11 @@ struct READMECSSStyling: View {
                         .frame(width: 120)
                     }
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode.html))
                         .padding()
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                 }
                 
@@ -101,12 +101,12 @@ struct READMECSSStyling: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 140)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -125,7 +125,7 @@ HTMLView(html: html, parser: parser)
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -220,9 +220,10 @@ HTMLView(html: html, parser: parser)
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("README CSS Styling")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/QuickStart/READMECustomTagsSample.swift b/Example/Samples/QuickStart/READMECustomTagsSample.swift
index 99508ff..8200230 100644
--- a/Example/Samples/QuickStart/READMECustomTagsSample.swift
+++ b/Example/Samples/QuickStart/READMECustomTagsSample.swift
@@ -48,11 +48,11 @@ struct READMECustomTagsSample: View {
                     Text("Rendering Result")
                         .font(.headline)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
+                    HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample) // configuration with custom tags registered
                         .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                         .padding()
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                 }
                 
@@ -73,12 +73,12 @@ struct READMECustomTagsSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 140)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -96,7 +96,7 @@ let configuration = HTMLConfiguration.default
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -179,9 +179,10 @@ let configuration = HTMLConfiguration.default
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("README Custom Tags")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/QuickStart/RichContentSample.swift b/Example/Samples/QuickStart/RichContentSample.swift
index bb2ea08..be8e3bf 100644
--- a/Example/Samples/QuickStart/RichContentSample.swift
+++ b/Example/Samples/QuickStart/RichContentSample.swift
@@ -2,6 +2,18 @@
 
 import SwiftUI
 import SwiftUIHTML
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 struct RichContentSample: View {
     let html = """
@@ -56,21 +68,21 @@ struct RichContentSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, {
                         var container = HTMLStyleContainer()
-                        let font = UIFont.systemFont(ofSize: 15)
+                        let font = ExampleFont.systemFont(ofSize: 15)
                         container.uiFont = font
                         container.textLine = .lineHeight(font: font, lineHeight: 22)
                         container.lineBreakMode = .byWordWrapping
                         return container
                     }())
                     .padding()
-                    .background(Color(.systemBackground))
+                    .background(platformBackgroundColor)
                     .overlay(
                         RoundedRectangle(cornerRadius: 8)
-                            .stroke(Color(.systemGray5), lineWidth: 1)
+                            .stroke(Color.platformSystemGray5, lineWidth: 1)
                     )
                 
                 // Features
@@ -111,17 +123,26 @@ struct RichContentSample: View {
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Rich Content")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
+private var platformBackgroundColor: Color {
+#if os(macOS)
+    return Color(nsColor: .windowBackgroundColor)
+#else
+    return Color(.systemBackground)
+#endif
+}
+
 #Preview {
     NavigationView {
         RichContentSample()
diff --git a/Example/Samples/Styling/BoxModelSample.swift b/Example/Samples/Styling/BoxModelSample.swift
index e704f30..6a2cdff 100644
--- a/Example/Samples/Styling/BoxModelSample.swift
+++ b/Example/Samples/Styling/BoxModelSample.swift
@@ -81,11 +81,11 @@ struct BoxModelSample: View {
                 Divider()
                 
                 // HTML rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Box model structure
@@ -122,7 +122,7 @@ padding: 5px 10px 15px 20px;
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -142,7 +142,7 @@ margin: 5px 10px 15px 20px; /* Top, right, bottom, left */
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -164,7 +164,7 @@ border-radius: 4px 8px 12px 16px;
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -184,9 +184,10 @@ border-radius: 4px 8px 12px 16px;
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Box Model")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/Styling/CSSColorSample.swift b/Example/Samples/Styling/CSSColorSample.swift
index 9d8beae..f6a54ba 100644
--- a/Example/Samples/Styling/CSSColorSample.swift
+++ b/Example/Samples/Styling/CSSColorSample.swift
@@ -60,11 +60,11 @@ struct CSSColorSample: View {
                 Divider()
                 
                 // HTML Rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Supported Color Formats
@@ -120,7 +120,7 @@ struct CSSColorSample: View {
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -140,9 +140,10 @@ struct CSSColorSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("CSS Colors")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/Styling/FontFamilySample.swift b/Example/Samples/Styling/FontFamilySample.swift
index e1249d2..e34813c 100644
--- a/Example/Samples/Styling/FontFamilySample.swift
+++ b/Example/Samples/Styling/FontFamilySample.swift
@@ -83,11 +83,11 @@ struct FontFamilySample: View {
                 Divider()
                 
                 // HTML rendering
-                HTMLView(html: html, parser: HTMLFuziParser())
+                HTMLView(html: html, parser: HTMLSwiftSoupParser())
                     .htmlEnvironment(\.configuration, .sample)
                     .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 
                 // Supported fonts
@@ -124,7 +124,7 @@ font-family: 'Times New Roman';
 """)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -157,7 +157,7 @@ font-family: 'Times New Roman';
 """)
                     .font(.system(.caption, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -178,9 +178,10 @@ font-family: 'Times New Roman';
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Font Families")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
diff --git a/Example/Samples/Styling/LineHeightSample.swift b/Example/Samples/Styling/LineHeightSample.swift
index 59e457c..57c6f2b 100644
--- a/Example/Samples/Styling/LineHeightSample.swift
+++ b/Example/Samples/Styling/LineHeightSample.swift
@@ -2,6 +2,18 @@
 
 import SwiftUI
 import SwiftUIHTML
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
 struct LineHeightSample: View {
     let longText = """
@@ -39,11 +51,11 @@ struct LineHeightSample: View {
                             .foregroundColor(.secondary)
                     }
                     
-                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLFuziParser())
+                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 16)
                             container.lineBreakMode = .byWordWrapping
@@ -68,11 +80,11 @@ struct LineHeightSample: View {
                             .foregroundColor(.secondary)
                     }
                     
-                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLFuziParser())
+                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 20)
                             container.lineBreakMode = .byWordWrapping
@@ -97,11 +109,11 @@ struct LineHeightSample: View {
                             .foregroundColor(.secondary)
                     }
                     
-                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLFuziParser())
+                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineHeight(font: font, lineHeight: 28)
                             container.lineBreakMode = .byWordWrapping
@@ -126,11 +138,11 @@ struct LineHeightSample: View {
                             .foregroundColor(.secondary)
                     }
                     
-                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLFuziParser())
+                    HTMLView(html: "<p>\(longText)</p>", parser: HTMLSwiftSoupParser())
                         .htmlEnvironment(\.configuration, .sample)
                         .htmlEnvironment(\.styleContainer, {
                             var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
+                            let font = ExampleFont.systemFont(ofSize: 14)
                             container.uiFont = font
                             container.textLine = .lineSpacing(spacing: 8)
                             container.lineBreakMode = .byWordWrapping
@@ -149,17 +161,10 @@ struct LineHeightSample: View {
                     Text("TextLine Configuration Method")
                         .font(.headline)
                     
-                    Text("""
-// Line height setting (absolute value)
-let font = UIFont.systemFont(ofSize: 14)
-container.textLine = .lineHeight(font: font, lineHeight: 20)
-
-// Line spacing setting (relative value)
-container.textLine = .lineSpacing(spacing: 8)
-""")
+                    Text(lineHeightCodeSample)
                     .font(.system(.body, design: .monospaced))
                     .padding()
-                    .background(Color(.systemGray6))
+                    .background(Color.platformSystemGray6)
                     .cornerRadius(8)
                 }
                 
@@ -212,14 +217,34 @@ container.textLine = .lineSpacing(spacing: 8)
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Line Height")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
     }
 }
 
+private var fontTypeName: String {
+#if os(macOS)
+    return "NSFont"
+#else
+    return "UIFont"
+#endif
+}
+
+private var lineHeightCodeSample: String {
+    """
+// Line height setting (absolute value)
+let font = \(fontTypeName).systemFont(ofSize: 14)
+container.textLine = .lineHeight(font: font, lineHeight: 20)
+
+// Line spacing setting (relative value)
+container.textLine = .lineSpacing(spacing: 8)
+"""
+}
+
 #Preview {
     NavigationView {
         LineHeightSample()
     }
-}
\ No newline at end of file
+}
diff --git a/Example/Samples/Testing/SnapshotTestSample.swift b/Example/Samples/Testing/SnapshotTestSample.swift
index b9522af..2b2ebf1 100644
--- a/Example/Samples/Testing/SnapshotTestSample.swift
+++ b/Example/Samples/Testing/SnapshotTestSample.swift
@@ -1,9 +1,20 @@
 //  Copyright © 2025 PRND. All rights reserved.
 
 import SwiftUI
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+#if os(macOS)
+import AppKit
+private typealias ExampleFont = NSFont
+#else
+import UIKit
+private typealias ExampleFont = UIFont
+#endif
+#endif
 
-@testable import SwiftUIHTML
-@testable import SwiftUIHTMLExample
+import SwiftUIHTML
 
 struct SnapshotTestSample: View {
     enum LineBreakModeOption: String, CaseIterable, Hashable {
@@ -60,6 +71,8 @@ struct SnapshotTestSample: View {
     
     @State private var selectedLineBreakModeOption: LineBreakModeOption = .byWordWrapping
     @State private var frameWidth: CGFloat = 375
+    @State private var parseStatus: String = "Parse: pending"
+    @State private var renderSize: CGSize = .zero
     
     var body: some View {
         ScrollView {
@@ -102,24 +115,38 @@ struct SnapshotTestSample: View {
                 VStack(alignment: .leading, spacing: 8) {
                     Text("Rendering Result")
                         .font(.headline)
+
+                    Text(parseStatus)
+                        .font(.caption)
+                        .foregroundColor(.secondary)
                     
-                    HTMLView(html: renderingHTML, parser: HTMLFuziParser())
-                        .htmlEnvironment(\.configuration, .sample)
-                        .htmlEnvironment(\.styleContainer, {
-                            var container = HTMLStyleContainer()
-                            let font = UIFont.systemFont(ofSize: 14)
-                            container.uiFont = font
-                            container.textLine = .lineHeight(font: font, lineHeight: 20)
-                            container.lineBreakMode = selectedLineBreakModeOption.toLineBreakMode()
-                            return container
-                        }())
-                        .frame(width: frameWidth)
-                        .padding()
-                        .background(Color(.systemGray6))
-                        .overlay(
-                            RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
-                        )
+                    Text("Render size: \(Int(renderSize.width))x\(Int(renderSize.height))")
+                        .font(.caption)
+                        .foregroundColor(.secondary)
+
+                    ZStack {
+                        HTMLView(html: renderingHTML, parser: HTMLSwiftSoupParser())
+                            .htmlEnvironment(\.configuration, .sample)
+                            .htmlEnvironment(\.styleContainer, {
+                                var container = HTMLStyleContainer()
+                                let font = ExampleFont.systemFont(ofSize: 14)
+                                container.uiFont = font
+                                container.textLine = .lineHeight(font: font, lineHeight: 20)
+                                container.lineBreakMode = selectedLineBreakModeOption.toLineBreakMode()
+                                return container
+                            }())
+                            .frame(width: frameWidth)
+                            .padding()
+                            .background(Color.platformSystemGray6)
+                            .overlay(
+                                RoundedRectangle(cornerRadius: 8)
+                                    .stroke(Color.platformSystemGray4, lineWidth: 1)
+                            )
+                            .background(RenderSizeReader(size: $renderSize))
+                    }
+                    .accessibilityElement(children: .ignore)
+                    .accessibilityLabel("Rendering Result HTML")
+                    .accessibilityIdentifier("RenderingResultHTMLView")
                 }
                 
                 // HTML Editor
@@ -139,12 +166,12 @@ struct SnapshotTestSample: View {
                     TextEditor(text: $htmlCode)
                         .font(.system(.body, design: .monospaced))
                         .padding(8)
-                        .background(Color(.systemGray6))
+                        .background(Color.platformSystemGray6)
                         .cornerRadius(8)
                         .frame(minHeight: 200)
                         .overlay(
                             RoundedRectangle(cornerRadius: 8)
-                                .stroke(Color(.systemGray4), lineWidth: 1)
+                                .stroke(Color.platformSystemGray4, lineWidth: 1)
                         )
                 }
                 
@@ -205,8 +232,12 @@ struct SnapshotTestSample: View {
                         }
                         .frame(maxWidth: .infinity)
                         .buttonStyle(.bordered)
-                    }
-                }
+        }
+        .task(id: renderingHTML) {
+            let parsed = HTMLSwiftSoupParser().parse(html: renderingHTML)
+            parseStatus = "Parse ok tag=\(parsed.tagName) children=\(parsed.childrenCount) (\(renderingHTML.count) chars)"
+        }
+    }
                 
                 // Test information
                 VStack(alignment: .leading, spacing: 8) {
@@ -224,9 +255,22 @@ struct SnapshotTestSample: View {
                 }
             }
             .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
         }
         .navigationTitle("Snapshot Test")
-        .navigationBarTitleDisplayMode(.inline)
+        .applyInlineNavigationTitleDisplayMode()
+    }
+}
+
+private struct RenderSizeReader: View {
+    @Binding var size: CGSize
+
+    var body: some View {
+        GeometryReader { proxy in
+            Color.clear
+                .onAppear { size = proxy.size }
+                .onChange(of: proxy.size) { newValue in size = newValue }
+        }
     }
 }
 
diff --git a/Example/Samples/Testing/SyntheticStressSample.swift b/Example/Samples/Testing/SyntheticStressSample.swift
new file mode 100644
index 0000000..a7b3ea2
--- /dev/null
+++ b/Example/Samples/Testing/SyntheticStressSample.swift
@@ -0,0 +1,168 @@
+//  Copyright © 2025 PRND. All rights reserved.
+
+import SwiftUI
+import SwiftUIHTML
+
+struct SyntheticStressSample: View {
+    @State private var sectionCount: Int = 12
+    @State private var includeMedia: Bool = true
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 16) {
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("Synthetic Stress Sample")
+                        .font(.largeTitle)
+                        .fontWeight(.bold)
+
+                    Text("Generates large HTML that exercises most tags and styles.")
+                        .font(.subheadline)
+                        .foregroundColor(.secondary)
+                }
+
+                Divider()
+
+                VStack(alignment: .leading, spacing: 12) {
+                    HStack {
+                        Text("Sections: \(sectionCount)")
+                        Spacer()
+                    }
+                    .font(.headline)
+
+                    Slider(value: Binding(
+                        get: { Double(sectionCount) },
+                        set: { sectionCount = Int($0) }
+                    ), in: 4...30, step: 1)
+
+                    Toggle("Include media (img/video)", isOn: $includeMedia)
+                }
+                .padding()
+                .background(Color.platformSystemGray6)
+                .cornerRadius(8)
+
+                HTMLView(html: syntheticHTML(sectionCount: sectionCount, includeMedia: includeMedia), parser: HTMLSwiftSoupParser())
+                    .htmlEnvironment(\.configuration, .sample)
+                    .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+                    .padding()
+                    .background(Color.platformSystemGray6)
+                    .cornerRadius(8)
+            }
+            .padding()
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+        .navigationTitle("Synthetic Stress")
+        .applyInlineNavigationTitleDisplayMode()
+    }
+}
+
+private extension SyntheticStressSample {
+    func syntheticHTML(sectionCount: Int, includeMedia: Bool) -> String {
+        var chunks: [String] = []
+        chunks.reserveCapacity(sectionCount * 6)
+
+        chunks.append("""
+            <body style="margin: 0; padding: 0;">
+                <header style="background-color: #f0f0f0; padding: 16px; border-radius: 8px; margin-bottom: 12px;">
+                    <h1 style="color: #333;">SwiftUIHTML Stress Test</h1>
+                    <p style="color: #666;">Synthetic HTML payload exercising tags, CSS, and attachments.</p>
+                    <p style="color: #666; font-size: 12px;">
+                        Inline styling: <span style="color: #6a2; font-size: 14px;">font-size</span>,
+                        <span style="background-color: #ffe08a; border-radius: 4px;">background + radius</span>,
+                        <span style="font-family: Georgia;">font-family</span>.
+                    </p>
+                </header>
+                <main>
+            """)
+
+        chunks.append("""
+            <section style="margin: 12px 0; padding: 12px; border: 1px solid #ddd; border-radius: 6px;">
+                <h2 style="color: #1a4; font-size: 18px;">Feature Overview</h2>
+                <p style="line-height: 22px;">
+                    <strong>Text styles</strong> with <em>nested emphasis</em> and
+                    <span style="color: #955;">inline color</span>.
+                    <span style="background-color: #ddefff; border-radius: 3px;">Inline background</span>
+                    with <u>underline</u> and <b>bold</b>.
+                </p>
+                <p style="line-height: 22px;">
+                    Ruby variants:
+                    <ruby ruby-position="before" ruby-scale="0.55" ruby-annotation-font-name="Hiragino Mincho ProN" ruby-annotation-font-size="10">表現<rt>ひょうげん</rt></ruby>,
+                    <ruby ruby-position="after" ruby-scale="0.5">漢字<rt>かんじ</rt><rp>(</rp><rt>ignored</rt><rp>)</rp></ruby>,
+                    <ruby ruby-position="interCharacter" ruby-scale="0.6">東京<rt>とうきょう</rt></ruby>,
+                    <ruby ruby-position="inline" ruby-scale="0.7">可愛い<rt>かわいい</rt></ruby>.
+                </p>
+            </section>
+            """)
+
+        for index in 1...sectionCount {
+            let mediaHTML: String
+            if includeMedia {
+                mediaHTML = """
+                    <p>
+                        <img src="https://picsum.photos/seed/\(index)/80/60" width="80" height="60" />
+                        <video src="https://example.com/video\(index).mp4" />
+                    </p>
+                    """
+            } else {
+                mediaHTML = ""
+            }
+
+            chunks.append("""
+                <section style="margin: 12px 0; padding: 12px; border: 1px solid #ddd; border-radius: 6px;">
+                    <h2 style="color: #1a4; font-size: 18px;">Section \(index)</h2>
+                    <h3 style="color: #444;">Subtitle \(index)</h3>
+                    <p style="line-height: 20px;">
+                        Inline styles: <span style="color: #c33;">red</span>,
+                        <span style="background-color: #ff0;">yellow</span>,
+                        <strong>bold</strong>, <em>italic</em>, <u>underline</u>.
+                    </p>
+                    <p style="line-height: 20px;">
+                        Font family mix:
+                        <span style="font-family: Georgia; font-size: 14px;">Georgia 14px</span>,
+                        <span style="font-family: Courier; font-size: 12px;">Courier 12px</span>,
+                        <span style="font-size: 16px;">Size 16px</span>.
+                    </p>
+                    <p style="word-break: break-all;">
+                        LongWord\(index)WithNoBreaksToExerciseLineWrappingAcrossTheLayoutEngine.
+                    </p>
+                    <p>
+                        Ruby: <ruby ruby-position="after" ruby-scale="0.5">漢字<rt>かんじ</rt></ruby>,
+                        <ruby ruby-position="before" ruby-scale="0.6">現代語<rt>げんだいご</rt></ruby>,
+                        <ruby ruby-position="inline" ruby-scale="0.7">新年<rt>しんねん</rt></ruby>.
+                    </p>
+                    <p>
+                        Link: <a href="https://example.com/\(index)">example.com/\(index)</a>
+                    </p>
+                    <ul>
+                        <li>Item \(index).1</li>
+                        <li>Item \(index).2 with <span style="color: #05a;">color</span></li>
+                        <li>Item \(index).3 with <strong>bold</strong> and <em>italic</em></li>
+                    </ul>
+                    <div style="margin: 8px 0; padding: 8px; border: 1px solid #aac; border-radius: 8px; background-color: #f8fbff;">
+                        <p style="margin: 0; line-height: 20px;">
+                            Nested block with padding, margin, border, and background.
+                            <span style="background-color: #def; border-radius: 4px;">Inline badge</span>
+                            + <span style="color: #2a6;">green text</span>.
+                        </p>
+                    </div>
+                    \(mediaHTML)
+                </section>
+                """)
+        }
+
+        chunks.append("""
+                </main>
+                <footer style="margin-top: 16px; padding: 12px; background-color: #333; color: white;">
+                    <p>Footer content for synthetic payload.</p>
+                </footer>
+            </body>
+            """)
+
+        return chunks.joined(separator: "\n")
+    }
+}
+
+#Preview {
+    NavigationView {
+        SyntheticStressSample()
+    }
+}
diff --git a/Example/SwiftUIHTMLExampleApp.swift b/Example/SwiftUIHTMLExampleApp.swift
index b48cb51..9b88e37 100644
--- a/Example/SwiftUIHTMLExampleApp.swift
+++ b/Example/SwiftUIHTMLExampleApp.swift
@@ -8,6 +8,20 @@ import SwiftUI
 struct SwiftUIHTMLExampleApp: App {
     var body: some Scene {
         WindowGroup {
+            RootView()
+        }
+    }
+}
+
+private struct RootView: View {
+    private let stressOnly = ProcessInfo.processInfo.environment["SWIFTUIHTML_STRESS_ONLY"] == "1"
+
+    var body: some View {
+        if stressOnly {
+            NavigationView {
+                SyntheticStressSample()
+            }
+        } else {
             ContentView()
         }
     }
diff --git a/Package.resolved b/Package.resolved
new file mode 100644
index 0000000..1541122
--- /dev/null
+++ b/Package.resolved
@@ -0,0 +1,60 @@
+{
+  "originHash" : "e6f2cc79269e23f7880ad5c0432d18758d493265e28476478592e11705af4597",
+  "pins" : [
+    {
+      "identity" : "lrucache",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/nicklockwood/LRUCache.git",
+      "state" : {
+        "revision" : "0d91406ecd4d6c1c56275866f00508d9aeacc92a",
+        "version" : "1.2.0"
+      }
+    },
+    {
+      "identity" : "nuke",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/kean/Nuke.git",
+      "state" : {
+        "branch" : "main",
+        "revision" : "88849b71eda654a2f4326801d96cc3b01d0d7efa"
+      }
+    },
+    {
+      "identity" : "swift-atomics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-atomics.git",
+      "state" : {
+        "revision" : "b601256eab081c0f92f059e12818ac1d4f178ff7",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-syntax",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-syntax.git",
+      "state" : {
+        "revision" : "4799286537280063c85a32f09884cfbca301b1a1",
+        "version" : "602.0.0"
+      }
+    },
+    {
+      "identity" : "swift-testing",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-testing.git",
+      "state" : {
+        "revision" : "48a471ab313e858258ab0b9b0bf2cea55a50cefb",
+        "version" : "6.2.3"
+      }
+    },
+    {
+      "identity" : "swiftsoup",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/scinfu/SwiftSoup.git",
+      "state" : {
+        "branch" : "master",
+        "revision" : "cd950c96d1d2ae53068828f1f394178afbc4d83a"
+      }
+    }
+  ],
+  "version" : 3
+}
diff --git a/Package.swift b/Package.swift
index 4b9681f..0590bcd 100644
--- a/Package.swift
+++ b/Package.swift
@@ -5,15 +5,30 @@ import PackageDescription
 
 let package = Package(
     name: "SwiftUIHTML",
-    platforms: [.iOS(.v15)],
+    platforms: [.iOS(.v15), .macOS(.v12)],
     products: [
         .library(
             name: "SwiftUIHTML",
             targets: ["SwiftUIHTML"]),
     ],
-    dependencies: [],
+    dependencies: [
+        .package(url: "https://github.com/swiftlang/swift-testing.git", from: "6.2.3"),
+        .package(url: "https://github.com/scinfu/SwiftSoup.git", branch: "master"),
+        .package(url: "https://github.com/kean/Nuke.git", branch: "main"),
+    ],
     targets: [
         .target(
-            name: "SwiftUIHTML", dependencies: []),
+            name: "SwiftUIHTML",
+            dependencies: [
+                .product(name: "NukeUI", package: "Nuke"),
+            ]
+        ),
+        .testTarget(
+            name: "SwiftUIHTMLTests",
+            dependencies: [
+                "SwiftUIHTML",
+                .product(name: "Testing", package: "swift-testing"),
+                .product(name: "SwiftSoup", package: "SwiftSoup"),
+            ]),
     ]
 )
diff --git a/README.md b/README.md
index ed1a178..02f43e5 100644
--- a/README.md
+++ b/README.md
@@ -19,8 +19,9 @@
 - **HTML Rendering**: Convert HTML to native SwiftUI views
 - **Custom Tag System**: Extensible through BlockTag, InlineTag, and InlineAttachmentTag protocols
 - **CSS Style Support**: Full inline style support (padding, margin, background, border, etc.)
-- **Flexible Parser Integration**: Works with external parsers like Fuzi and SwiftSoup
+- **Flexible Parser Integration**: Works with external parsers like SwiftSoup and custom implementations
 - **Environment Value System**: Global configuration and style customization
+- **Profiling Hooks**: Optional signposts for HTML parsing via `SWIFTUIHTML_SIGNPOSTS=1`
 
 ---
 
@@ -32,16 +33,19 @@
 |----------|------|
 | **Block** | `div`, `body`, `p`, `header`, `main`, `section`, `footer`, `h1`, `h2` |
 | **Inline** | `span`, `a`, `b`, `strong`, `i`, `em`, `u` |
-| **Attachment** | `img` |
+| **Attachment** | `img`, `ruby` |
 
 > Note: Tags like h3, ul, video can be registered as custom tags.
 
+> Note: `ruby` renders `<ruby><rt>` annotations via CoreText. `<rt>` text is used for the ruby string; `<rp>`/`<rtc>` are ignored.
+
 ### CSS Style Properties
 - **Text Styles**: `color`, `background-color`, `font-family`, `font-size`, `line-height`, `word-break`
 - **Block Layout**: `padding`, `margin`, `border`, `border-radius` (block elements only: div, p, section, etc.)
 - **Inline Styles**: `color`, `background-color`, `border-radius` (inline elements: strong, em, span, etc.)
 
 > **Note**: `padding` and `margin` are not supported for inline elements (span, strong, em, etc.).
+> **Ruby options**: `ruby-position` (`before`, `after`, `interCharacter`, `inline`), `ruby-scale` (e.g. `0.58`), `ruby-font-name`, `ruby-font-size`, `ruby-annotation-font-name`, `ruby-annotation-font-size`.
 
 ---
 
@@ -76,20 +80,53 @@ struct ContentView: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
             .htmlEnvironment(\.styleContainer, createStyleContainer())
     }
     
     func createStyleContainer() -> HTMLStyleContainer {
         var container = HTMLStyleContainer()
-        container.uiFont = .systemFont(ofSize: 16)
+#if os(macOS)
+        let font = NSFont.systemFont(ofSize: 16)
+#else
+        let font = UIFont.systemFont(ofSize: 16)
+#endif
+        container.uiFont = font
         container.lineBreakMode = .byWordWrapping
         return container
     }
 }
 ```
 
+### Profiling
+
+Set `SWIFTUIHTML_SIGNPOSTS=1` in your environment to emit signposts around HTML parsing, then use Instruments to view the “HTML parse” intervals.
+For perf comparisons, you can also toggle `SWIFTUIHTML_CACHE_FRAMESETTER=1` and use `SWIFTUIHTML_DISABLE_RANGE_SCAN_OPT=1` to force the legacy range scan path.
+
+### Performance Tests
+
+The SwiftUIHTML package includes lightweight performance smoke tests that log the median parse time for synthetic HTML (and SwiftSoup when available). Run `swift test` in the SwiftUIHTML package to see the output.
+
+### Ruby Example
+
+```swift
+let html = """
+    <p>
+        <ruby ruby-position="after" ruby-scale="0.5">
+            今日<rt>きょう</rt>
+        </ruby>
+        is sunny.
+    </p>
+    <p>
+        <ruby ruby-font-size="22" ruby-annotation-font-size="12">
+            明日<rt>あした</rt>
+        </ruby>
+        is clear too.
+    </p>
+    """
+```
+
 ### Parser Implementation
 
 You can use any HTML parser by implementing the HTMLParserable protocol:
@@ -113,7 +150,7 @@ For detailed usage and examples, please refer to the Documentation folder:
 - 📖 **[Basic Usage](Documentation/BasicUsage.md)** - HTML rendering basics
 - 🎨 **[Styling Guide](Documentation/Styling.md)** - CSS styles and configuration
 - 🔧 **[Custom Tags](Documentation/CustomTags.md)** - Creating custom tags
-- 🔌 **[Parser Integration](Documentation/ParserIntegration.md)** - Fuzi, SwiftSoup integration
+- 🔌 **[Parser Integration](Documentation/ParserIntegration.md)** - SwiftSoup and custom parser integration
 - 🚀 **[Advanced Features](Documentation/AdvancedFeatures.md)** - Environment values and advanced customization
 
 ### Quick Examples
@@ -165,6 +202,8 @@ Protocol for external HTML parser integration
 ## 📱 Example Project
 
 For more examples, please refer to the project in the `Example` folder.
+The Testing section includes a "Synthetic Stress" sample for profiling large HTML payloads.
+When SwiftSoup is linked, the Parser Integration section includes a SwiftSoup parser sample.
 
 ---
 
@@ -176,4 +215,4 @@ Contributions are welcome! Feel free to submit issues and pull requests.
 
 ## 📄 License
 
-SwiftUIHTML is released under the MIT License. See [LICENSE](LICENSE) for details.
\ No newline at end of file
+SwiftUIHTML is released under the MIT License. See [LICENSE](LICENSE) for details.
diff --git a/README_ko.md b/README_ko.md
index 1645669..62d9d63 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -19,8 +19,9 @@
 - **HTML 렌더링**: SwiftUI 환경에서 HTML을 네이티브 뷰로 변환
 - **커스텀 태그 시스템**: BlockTag, InlineTag, InlineAttachmentTag 프로토콜로 자유로운 확장
 - **CSS 스타일 지원**: 인라인 스타일(padding, margin, background, border 등) 완벽 지원
-- **유연한 파서 통합**: Fuzi, SwiftSoup 등 외부 파서 라이브러리와 연동
+- **유연한 파서 통합**: SwiftSoup 및 커스텀 파서와 연동
 - **환경 값 시스템**: 전역 설정 관리 및 스타일 커스터마이징
+- **프로파일링 훅**: `SWIFTUIHTML_SIGNPOSTS=1` 설정 시 HTML 파싱 구간 signpost 출력
 
 ---
 
@@ -32,16 +33,19 @@
 |---------|-----|
 | **블록** | `div`, `body`, `p`, `header`, `main`, `section`, `footer`, `h1`, `h2` |
 | **인라인** | `span`, `a`, `b`, `strong`, `i`, `em`, `u` |
-| **첨부** | `img` |
+| **첨부** | `img`, `ruby` |
 
 > 참고: h3, ul, video 등의 태그는 커스텀 태그로 등록하여 사용할 수 있습니다.
 
+> 참고: `ruby`는 `<ruby><rt>` 형태의 주석을 CoreText로 렌더링합니다. `rt` 텍스트가 루비 문자열로 사용되며 `rp`/`rtc`는 무시됩니다.
+
 ### CSS 스타일 속성
 - **텍스트 스타일**: `color`, `background-color`, `font-family`, `font-size`, `line-height`, `word-break`
 - **블록 레이아웃**: `padding`, `margin`, `border`, `border-radius` (div, p, section 등 block 요소만)
 - **인라인 스타일**: `color`, `background-color`, `border-radius` (strong, em, span 등 inline 요소)
 
 > **참고**: inline 요소(span, strong, em 등)에서는 `padding`, `margin`이 지원되지 않습니다.
+> **루비 옵션**: `ruby-position` (`before`, `after`, `interCharacter`, `inline`), `ruby-scale` (예: `0.58`), `ruby-font-name`, `ruby-font-size`, `ruby-annotation-font-name`, `ruby-annotation-font-size`.
 
 ---
 
@@ -76,20 +80,53 @@ struct ContentView: View {
         """
     
     var body: some View {
-        HTMLView(html: html, parser: HTMLFuziParser())
+        HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .default)
             .htmlEnvironment(\.styleContainer, createStyleContainer())
     }
     
     func createStyleContainer() -> HTMLStyleContainer {
         var container = HTMLStyleContainer()
-        container.uiFont = .systemFont(ofSize: 16)
+#if os(macOS)
+        let font = NSFont.systemFont(ofSize: 16)
+#else
+        let font = UIFont.systemFont(ofSize: 16)
+#endif
+        container.uiFont = font
         container.lineBreakMode = .byWordWrapping
         return container
     }
 }
 ```
 
+### Profiling
+
+환경 변수 `SWIFTUIHTML_SIGNPOSTS=1`을 설정하면 HTML 파싱 구간에 signpost가 출력됩니다. Instruments에서 “HTML parse” 구간을 확인하세요.
+성능 비교용으로 `SWIFTUIHTML_CACHE_FRAMESETTER=1`을 켜거나 `SWIFTUIHTML_DISABLE_RANGE_SCAN_OPT=1`로 레거시 범위 스캔 경로를 강제로 사용할 수 있습니다.
+
+### Performance Tests
+
+SwiftUIHTML 패키지에는 synthetic HTML 파싱의 median 시간을 출력하는 가벼운 성능 스모크 테스트가 포함되어 있습니다(SwiftSoup 사용 시 추가 측정). SwiftUIHTML 패키지에서 `swift test`를 실행하면 결과가 출력됩니다.
+
+### 루비 예제
+
+```swift
+let html = """
+    <p>
+        <ruby ruby-position="after" ruby-scale="0.5">
+            今日<rt>きょう</rt>
+        </ruby>
+        는 맑습니다.
+    </p>
+    <p>
+        <ruby ruby-font-size="22" ruby-annotation-font-size="12">
+            明日<rt>あした</rt>
+        </ruby>
+        도 맑습니다.
+    </p>
+    """
+```
+
 ### 파서 구현
 
 HTMLParserable 프로토콜을 구현하여 원하는 HTML 파서를 사용할 수 있습니다:
@@ -113,7 +150,7 @@ struct MyHTMLParser: HTMLParserable {
 - 📖 **[기본 사용법](Documentation/BasicUsage.md)** - HTML 렌더링 기초
 - 🎨 **[스타일링 가이드](Documentation/Styling.md)** - CSS 스타일과 설정
 - 🔧 **[커스텀 태그](Documentation/CustomTags.md)** - 커스텀 태그 만들기
-- 🔌 **[파서 통합](Documentation/ParserIntegration.md)** - Fuzi, SwiftSoup 연동
+- 🔌 **[파서 통합](Documentation/ParserIntegration.md)** - SwiftSoup 및 커스텀 파서 연동
 - 🚀 **[고급 기능](Documentation/AdvancedFeatures.md)** - 환경값과 고급 커스터마이징
 
 ### 빠른 예제
@@ -165,6 +202,8 @@ HTML 콘텐츠를 렌더링하는 메인 뷰
 ## 📱 예제 프로젝트
 
 더 많은 예제는 `Example` 폴더의 프로젝트를 참고하세요.
+Testing 섹션에 대용량 HTML을 위한 "Synthetic Stress" 샘플이 있습니다.
+SwiftSoup를 연결한 경우 Parser Integration 섹션에 SwiftSoup 파서 샘플이 표시됩니다.
 
 ---
 
@@ -176,4 +215,4 @@ HTML 콘텐츠를 렌더링하는 메인 뷰
 
 ## 📄 라이선스
 
-Copyright © 2025 PRND. All rights reserved.
\ No newline at end of file
+Copyright © 2025 PRND. All rights reserved.
diff --git a/Sources/SwiftUIHTML/Core/Attachment/AttachmentDebugLogger.swift b/Sources/SwiftUIHTML/Core/Attachment/AttachmentDebugLogger.swift
new file mode 100644
index 0000000..3616074
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Attachment/AttachmentDebugLogger.swift
@@ -0,0 +1,82 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import Foundation
+
+enum AttachmentDebugLogger {
+    private static nonisolated(unsafe) let lock = NSLock()
+    private static nonisolated(unsafe) var buffer: [String] = []
+    private static let logFileURL: URL = {
+        let env = ProcessInfo.processInfo.environment
+        if let customPath = env["SWIFTUIHTML_ATTACHMENT_LOG_PATH"], !customPath.isEmpty {
+            return URL(fileURLWithPath: customPath)
+        }
+        if env["XCTestConfigurationFilePath"] != nil || env["XCTestBundlePath"] != nil {
+            return URL(fileURLWithPath: "/tmp/swiftuihtml-attachment.log")
+        }
+        return URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent("swiftuihtml-attachment.log")
+    }()
+
+    static func record(_ message: String) {
+        lock.lock()
+        buffer.append(message)
+        if let data = (message + "\n").data(using: .utf8) {
+            if let handle = try? FileHandle(forWritingTo: logFileURL) {
+                handle.seekToEndOfFile()
+                try? handle.write(contentsOf: data)
+                try? handle.close()
+            } else {
+                try? data.write(to: logFileURL)
+            }
+        }
+        lock.unlock()
+    }
+
+    static func recordOnce(_ key: String, message: @autoclosure () -> String) {
+        lock.lock()
+        if buffer.contains(key) {
+            lock.unlock()
+            return
+        }
+        buffer.append(key)
+        let rendered = message()
+        buffer.append(rendered)
+        if let data = (rendered + "\n").data(using: .utf8) {
+            if let handle = try? FileHandle(forWritingTo: logFileURL) {
+                handle.seekToEndOfFile()
+                try? handle.write(contentsOf: data)
+                try? handle.close()
+            } else {
+                try? data.write(to: logFileURL)
+            }
+        }
+        lock.unlock()
+    }
+
+    static func dump() -> String {
+        lock.lock()
+        let output = buffer.joined(separator: "\n")
+        lock.unlock()
+        return output
+    }
+
+    static func readLogFile() -> String? {
+        lock.lock()
+        let url = logFileURL
+        lock.unlock()
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    static func clear() {
+        lock.lock()
+        buffer.removeAll(keepingCapacity: true)
+        let env = ProcessInfo.processInfo.environment
+        let shouldPreserveLog = env["SWIFTUIHTML_ATTACHMENT_LOG_PRESERVE"] == "1"
+            || env["XCTestConfigurationFilePath"] != nil
+            || env["XCTestBundlePath"] != nil
+        if !shouldPreserveLog {
+            try? FileManager.default.removeItem(at: logFileURL)
+        }
+        lock.unlock()
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Attachment/AttachmentIDGenerator.swift b/Sources/SwiftUIHTML/Core/Attachment/AttachmentIDGenerator.swift
new file mode 100644
index 0000000..9846645
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Attachment/AttachmentIDGenerator.swift
@@ -0,0 +1,16 @@
+//  Copyright © 2026 PRND. All rights reserved.
+import Foundation
+
+@MainActor
+enum AttachmentIDGenerator {
+    private static var counter: Int = 0
+
+    static func next() -> Int {
+        counter += 1
+        return counter
+    }
+
+    static func reset() {
+        counter = 0
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutManager.swift b/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutManager.swift
index 6ea833a..9c23c0e 100644
--- a/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutManager.swift
+++ b/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutManager.swift
@@ -1,6 +1,17 @@
 //  Copyright © 2024 PRND. All rights reserved.
-import UIKit
 import Combine
+import Foundation
+#if canImport(Darwin)
+import Darwin
+#endif
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+#if canImport(os)
+import os
+#endif
 
 final class AttachmentLayoutEngine {
     
@@ -9,9 +20,21 @@ final class AttachmentLayoutEngine {
 
     private var keyAttachment: [AnyHashable: Weak<TextAttachment>] = [:]
     private var frameStore: [AnyHashable: CGRect] = [:]
+    private var lineMetricsByKey: [AnyHashable: TextRangeFrameCalculator.LineMetrics] = [:]
     private var texts: [TextType] = []
+    private var preparedString: NSMutableAttributedString?
+    private var targetCache: [(value: TextAttachment, range: NSRange)] = []
+    private var attachmentKeys: [AnyHashable] = []
+    private var attachmentRanges: [NSRange] = []
+    private var attachmentSizePublishers: [AnyPublisher<CGRect, Never>] = []
     private var textRangeFrameCalculator = TextRangeFrameCalculator()
     private var cancelBag = Set<AnyCancellable>()
+#if canImport(os)
+    private static let signposter = OSSignposter(
+        logHandle: OSLog(subsystem: "SwiftUIHTML", category: "AttachmentLayout")
+    )
+    private static let logger = Logger(subsystem: "SwiftUIHTML", category: "AttachmentLayout")
+#endif
 
     var lineSpacing: CGFloat {
         get { textRangeFrameCalculator.lineSpacing }
@@ -24,6 +47,34 @@ final class AttachmentLayoutEngine {
         setup()
     }
 
+    private var shouldLog: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+            || NSClassFromString("XCTestCase") != nil
+    }
+
+    private func log(_ message: @autoclosure () -> String) {
+        guard shouldLog else { return }
+        let rendered = message()
+        AttachmentDebugLogger.record("[AttachmentLayout] \(rendered)")
+#if canImport(os)
+        if #available(iOS 14.0, macOS 11.0, *) {
+            AttachmentLayoutEngine.logger.debug("\(rendered, privacy: .public)")
+        }
+#endif
+        NSLog("[SwiftUIHTML][AttachmentLayout] %@", rendered)
+        print("[SwiftUIHTML][AttachmentLayout] \(rendered)")
+    }
+
+    private func environmentFlag(_ key: String) -> Bool {
+        if let raw = getenv(key), let value = String(validatingUTF8: raw) {
+            return value == "1"
+        }
+        return ProcessInfo.processInfo.environment[key] == "1"
+    }
+
     func setup() {
         let attributedStringPublisher = _attributedString.projectedValue
             .compactMap { $0 }
@@ -32,6 +83,7 @@ final class AttachmentLayoutEngine {
         let containerSizePublisher = _containerSize.projectedValue
             .compactMap { $0 }
             .removeDuplicates()
+            .debounce(for: .milliseconds(16), scheduler: DispatchQueue.main)
 
         Publishers
             .CombineLatest(attributedStringPublisher, containerSizePublisher)
@@ -51,7 +103,15 @@ final class AttachmentLayoutEngine {
         let oldSize = textAttachment.value?.bounds.size ?? .zero
         guard oldSize != size else { return }
         textAttachment.value?.updateSize(size)
-        layoutUpdatePublisher.send(())
+#if os(iOS)
+        log("setSize key=\(key) size=\(size)")
+        recalculateLayoutIfPossible()
+        notifyLayoutUpdate()
+#else
+        log("setSize key=\(key) size=\(size)")
+        recalculateLayoutIfPossible()
+        notifyLayoutUpdate()
+#endif
     }
 
     func getSize(key: AnyHashable) -> CGSize {
@@ -59,35 +119,213 @@ final class AttachmentLayoutEngine {
         return textAttachment.value?.getAdjustedSize() ?? .zero
     }
 
+    func getFrame(key: AnyHashable) -> CGRect? {
+        frameStore[key]
+    }
+
+    func getLineMetrics(key: AnyHashable) -> TextRangeFrameCalculator.LineMetrics? {
+        lineMetricsByKey[key]
+    }
+
     func getOffset(key: AnyHashable) -> CGPoint {
-        let point = frameStore[key]?.origin ?? .zero
+        let rect = frameStore[key]
+        let point = rect?.origin ?? .zero
         guard let textAttachment = keyAttachment[key] else { return point }
-        return textAttachment.value?.getAdjustedOffset(point: point) ?? point
+#if os(macOS)
+        if environmentFlag("SWIFTUIHTML_MACOS_USE_RAW_OFFSET") {
+            log("getOffset key=\(key) frame=\(String(describing: frameStore[key])) adjusted=\(point) raw=on")
+            return point
+        }
+        if let textType = key.base as? TextType,
+           case let .attachment(_, tag, _, _) = textType,
+           tag == "img" {
+            log("getOffset key=\(key) frame=\(String(describing: frameStore[key])) adjusted=\(point) raw=img")
+            return point
+        }
+        let lineHeightOverride = rect?.height ?? 0
+        let adjusted = textAttachment.value?.getAdjustedOffset(
+            point: point,
+            lineHeightOverride: lineHeightOverride > 0 ? lineHeightOverride : nil
+        ) ?? point
+        if environmentFlag("SWIFTUIHTML_USE_TEXTKIT_LAYOUT") {
+            log("getOffset key=\(key) frame=\(String(describing: frameStore[key])) adjusted=\(adjusted) textKit=on")
+        } else {
+            log("getOffset key=\(key) frame=\(String(describing: frameStore[key])) adjusted=\(adjusted)")
+        }
+        return adjusted
+#else
+        let lineHeightOverride = rect?.height ?? 0
+        let adjusted = textAttachment.value?.getAdjustedOffset(
+            point: point,
+            lineHeightOverride: lineHeightOverride > 0 ? lineHeightOverride : nil
+        ) ?? point
+        log("getOffset key=\(key) frame=\(String(describing: frameStore[key])) adjusted=\(adjusted)")
+        return adjusted
+#endif
 
     }
 
     func setContainerSize(_ size: CGSize) {
+        if containerSize == size {
+            return
+        }
         containerSize = size
+#if os(iOS)
+        log("setContainerSize \(size)")
+        recalculateLayoutIfPossible()
+#else
+        log("setContainerSize \(size)")
+        recalculateLayoutIfPossible()
+#endif
     }
 
     @MainActor
     func setTexts(_ texts: [TextType]) {
-        let hasAttachment = !texts.lazy.filter(\.hasAttachment).isEmpty
+        let hasAttachment = texts.contains(where: \.hasAttachment)
         guard hasAttachment else {
             self.texts = []
             self.attributedString = nil
+            self.preparedString = nil
+            self.targetCache = []
+            self.attachmentKeys = []
+            self.attachmentRanges = []
+            self.attachmentSizePublishers = []
             return
         }
-        
+
         guard self.texts != texts else { return }
         self.texts = texts
-        attributedString = makeAttributedString(texts: texts)
+        lineSpacing = resolveLineSpacing(texts: texts)
+        log("resolved lineSpacing=\(lineSpacing)")
+        let newAttributedString = makeAttributedString(texts: texts)
+        attributedString = newAttributedString
+        preparedString = textRangeFrameCalculator.prepareCoreTextString(newAttributedString)
+        targetCache = textRangeFrameCalculator.findAttribute(
+            in: newAttributedString,
+            for: .attachment,
+            type: TextAttachment.self
+        )
+        attachmentKeys = targetCache.map(\.value.key)
+        attachmentRanges = targetCache.map(\.range)
+        attachmentSizePublishers = targetCache.map { target in
+            let initialBounds = target.value.bounds
+            let seedBounds = initialBounds.size > .invisible
+                ? initialBounds
+                : CGRect(origin: .zero, size: CGSize(width: 1, height: 1))
+            return target.value
+                .publisher(for: \.bounds)
+                .prepend(seedBounds)
+                .removeDuplicates()
+                .filter { $0.size > .invisible }
+                .eraseToAnyPublisher()
+        }
+        logAttachmentCounts(expected: texts.filter(\.hasAttachment).count)
+#if os(macOS)
+        applyFallbackAttachmentSizesIfNeeded()
+#endif
     }
 
 
 }
 
 private extension AttachmentLayoutEngine {
+#if os(macOS)
+    func applyFallbackAttachmentSizesIfNeeded() {
+        guard !attachmentKeys.isEmpty else { return }
+        var applied = 0
+        for key in attachmentKeys {
+            let existing = getSize(key: key)
+            if existing != .zero {
+                continue
+            }
+            guard let textType = key.base as? TextType else { continue }
+            guard case let .attachment(_, _, attributes, styleContainer) = textType else { continue }
+            let elementSize = ElementSize(attributes: attributes)
+            guard let width = elementSize.width ?? elementSize.height,
+                  let height = elementSize.height ?? elementSize.width else {
+                continue
+            }
+            let size = CGSize(width: max(1, width), height: max(1, height))
+            setSize(key: key, size: size)
+            applied += 1
+        }
+        if applied > 0 {
+            log("fallbackAttachmentSizes applied=\(applied)")
+        }
+    }
+#endif
+
+    func resolveLineSpacing(texts: [TextType]) -> CGFloat {
+        var maxLineSpacing: CGFloat = 0
+        for text in texts {
+            switch text {
+            case let .text(_, styleContainer):
+                if let lineSpacing = styleContainer.textLine?.lineSpacing {
+                    maxLineSpacing = max(maxLineSpacing, lineSpacing)
+                }
+            case let .attachment(_, _, _, styleContainer):
+                if let lineSpacing = styleContainer.textLine?.lineSpacing {
+                    maxLineSpacing = max(maxLineSpacing, lineSpacing)
+                }
+            default:
+                continue
+            }
+        }
+        return maxLineSpacing
+    }
+
+    func logAttachmentCounts(expected: Int) {
+        guard shouldLog else { return }
+        let uniqueKeys = Set(attachmentKeys)
+        let expectedImages = texts.reduce(into: 0) { count, text in
+            guard case let .attachment(_, tag, _, _) = text, tag == "img" else { return }
+            count += 1
+        }
+        log(
+            "attachmentCounts expected=\(expected) expectedImages=\(expectedImages) prepared=\(attachmentKeys.count) uniqueKeys=\(uniqueKeys.count)"
+        )
+        let preparedCount = attachmentKeys.count
+        let uniqueCount = uniqueKeys.count
+        let attachmentCounts = AttachmentLayoutTracker.AttachmentCounts(
+            expected: expected,
+            expectedImages: expectedImages,
+            prepared: preparedCount,
+            uniqueKeys: uniqueCount
+        )
+        Task { [attachmentCounts] in
+            await AttachmentLayoutTracker.shared.recordCounts(attachmentCounts)
+        }
+        guard uniqueKeys.count != expected else { return }
+        var counts: [String: Int] = [:]
+        counts.reserveCapacity(attachmentKeys.count)
+        for key in attachmentKeys {
+            let summary = attachmentSummary(for: key)
+            counts[summary, default: 0] += 1
+        }
+        let duplicates = counts
+            .filter { $0.value > 1 }
+            .sorted { $0.value > $1.value }
+            .map { "\($0.key)x\($0.value)" }
+        if !duplicates.isEmpty {
+            log("attachmentKeyDuplicates \(duplicates.joined(separator: " | "))")
+        }
+    }
+
+    func attachmentSummary(for key: AnyHashable) -> String {
+        guard let textType = key.base as? TextType else {
+            return "unknown"
+        }
+        switch textType {
+        case let .attachment(id, tag, attributes, _):
+            let src = attributes["src"]?.string ?? "-"
+            let width = attributes["width"]?.string ?? "-"
+            let height = attributes["height"]?.string ?? "-"
+            return "id=\(id) tag=\(tag) src=\(src) w=\(width) h=\(height)"
+        default:
+            return "non-attachment"
+        }
+    }
+
     func set(key: AnyHashable, attachment: TextAttachment) {
         guard let _attachment = keyAttachment[key] else {
             keyAttachment[key] = Weak(value: attachment)
@@ -96,6 +334,39 @@ private extension AttachmentLayoutEngine {
         _attachment.value = attachment
     }
 
+    func recalculateLayoutIfPossible() {
+        guard let preparedString, let attributedString, let container = containerSize else { return }
+        guard !attachmentRanges.isEmpty else { return }
+        let frames: [CGRect]
+#if os(macOS)
+        if environmentFlag("SWIFTUIHTML_USE_TEXTKIT_LAYOUT") {
+            frames = textRangeFrameCalculator.measureLayoutWithTextKit(
+                attributedString: attributedString,
+                in: container,
+                by: attachmentRanges
+            )
+            log("layoutEngine=TextKit")
+        } else {
+            frames = textRangeFrameCalculator.measureLayout(
+                for: preparedString,
+                in: container,
+                by: attachmentRanges
+            )
+        }
+#else
+        frames = textRangeFrameCalculator.measureLayout(
+            for: preparedString,
+            in: container,
+            by: attachmentRanges
+        )
+#endif
+        let values = zip(attachmentKeys, frames).map { (key: $0, bounds: $1) }
+        if shouldLog {
+            logLineMetricsIfNeeded(preparedString: preparedString, container: container)
+        }
+        storeRangeBounds(values)
+    }
+
     @MainActor
     func makeAttributedString(texts: [TextType]) -> NSMutableAttributedString {
         let attributedString = NSMutableAttributedString()
@@ -103,6 +374,12 @@ private extension AttachmentLayoutEngine {
         for element in texts {
             switch element {
             case let .text(string, styleContainer):
+                if let uiFont = styleContainer.uiFont {
+                    AttachmentDebugLogger.recordOnce(
+                        "uiFont:\(uiFont.fontName):\(uiFont.pointSize)",
+                        message: "[Font] uiFont name=\(uiFont.fontName) size=\(uiFont.pointSize)"
+                    )
+                }
                 let text = makeAttributedString(
                     string: string,
                     styleContainer: styleContainer
@@ -110,6 +387,12 @@ private extension AttachmentLayoutEngine {
                 attributedString.append(text)
 
             case let .newLine(styleContainer):
+                if let uiFont = styleContainer.uiFont {
+                    AttachmentDebugLogger.recordOnce(
+                        "uiFont:\(uiFont.fontName):\(uiFont.pointSize)",
+                        message: "[Font] uiFont name=\(uiFont.fontName) size=\(uiFont.pointSize)"
+                    )
+                }
                 let text = makeAttributedString(
                     string: "\n",
                     styleContainer: styleContainer
@@ -117,6 +400,12 @@ private extension AttachmentLayoutEngine {
                 attributedString.append(text)
 
             case let .attachment(_, _, _, styleContainer):
+                if let uiFont = styleContainer.uiFont {
+                    AttachmentDebugLogger.recordOnce(
+                        "uiFont:\(uiFont.fontName):\(uiFont.pointSize)",
+                        message: "[Font] uiFont name=\(uiFont.fontName) size=\(uiFont.pointSize)"
+                    )
+                }
                 let attachment = TextAttachment(
                     key: element,
                     styleContainer: styleContainer
@@ -141,27 +430,32 @@ private extension AttachmentLayoutEngine {
 
 
     func measureLayoutPublisher(attributedString: NSMutableAttributedString, containerSize: CGSize) -> AnyPublisher<[(AnyHashable, CGRect)], Never> {
-        let coreTextString = textRangeFrameCalculator
-            .prepareCoreTextString(attributedString)
-
-        let targets = textRangeFrameCalculator
-            .findAttribute(in: attributedString, for: .attachment, type: TextAttachment.self)
-
-        let attchmentSizeChange = targets
-            .map { target in
-                target.value
-                    .publisher(for: \.bounds)
-                    .removeDuplicates()
-                    .filter { $0.size > .invisible }
-            }
+        let coreTextString = preparedString ?? textRangeFrameCalculator.prepareCoreTextString(attributedString)
+
+        let targets = targetCache
+        if targets.isEmpty {
+            return Just([]).eraseToAnyPublisher()
+        }
 
-        let keys = targets.map(\.value.key)
-        let ranges = targets.map(\.range)
+        let keys = attachmentKeys
+        let ranges = attachmentRanges
 
-        return Publishers.MergeMany(attchmentSizeChange)
+        let sizePublishers = attachmentSizePublishers
+        return Publishers.MergeMany(sizePublishers)
             .receive(on: DispatchQueue.global(qos: .background))
             .compactMap { [weak textRangeFrameCalculator] _ in
-                textRangeFrameCalculator?
+#if canImport(os)
+                let shouldSignpost = ProcessInfo.processInfo.environment["SWIFTUIHTML_SIGNPOSTS"] == "1"
+                let intervalState = shouldSignpost
+                    ? AttachmentLayoutEngine.signposter.beginInterval("Attachment layout", "\(ranges.count) ranges")
+                    : nil
+                defer {
+                    if let intervalState {
+                        AttachmentLayoutEngine.signposter.endInterval("Attachment layout", intervalState)
+                    }
+                }
+#endif
+                return textRangeFrameCalculator?
                     .measureLayout(for: coreTextString, in: containerSize, by: ranges)
             }
             .map { zip(keys, $0).map { ($0, $1) } }
@@ -170,15 +464,96 @@ private extension AttachmentLayoutEngine {
 
 
     func storeRangeBounds(key: AnyHashable, bounds: CGRect) {
+        if let existing = frameStore[key], existing == bounds {
+            return
+        }
         frameStore[key] = bounds
-        layoutUpdatePublisher.send(())
+        let container = containerSize ?? .zero
+        log("storeRangeBounds key=\(key) bounds=\(bounds) container=\(container)")
+        logMissingAttachmentsIfNeeded()
+        notifyLayoutUpdate()
     }
 
     func storeRangeBounds(_ values: [(key: AnyHashable, bounds: CGRect)]) {
+        var didChange = false
         values.forEach {
-            frameStore[$0.key] = $0.bounds
+            if frameStore[$0.key] != $0.bounds {
+                frameStore[$0.key] = $0.bounds
+                didChange = true
+            }
         }
+        if didChange {
+            let container = containerSize ?? .zero
+            log("storeRangeBounds batch count=\(values.count) container=\(container)")
+            logLayoutFramesIfNeeded(values: values, container: container)
+            logMissingAttachmentsIfNeeded()
+            notifyLayoutUpdate()
+        }
+    }
+
+    private func notifyLayoutUpdate() {
         layoutUpdatePublisher.send(())
+        Task {
+            await AttachmentLayoutTracker.shared.markUpdated()
+        }
+    }
+}
+
+private extension AttachmentLayoutEngine {
+    func logLayoutFramesIfNeeded(values: [(key: AnyHashable, bounds: CGRect)], container: CGSize) {
+        guard shouldLog else { return }
+        guard !values.isEmpty else { return }
+        let sample = values.prefix(6).map { entry in
+            "\(summary(for: entry.key)) frame=\(entry.bounds)"
+        }
+        log("layoutFrames sample=\(sample.joined(separator: " | ")) container=\(container)")
+    }
+
+    func logLineMetricsIfNeeded(preparedString: NSMutableAttributedString, container: CGSize) {
+        guard shouldLog else { return }
+        guard !attachmentRanges.isEmpty else { return }
+        let sampleCount = min(6, attachmentRanges.count)
+        let ranges = Array(attachmentRanges.prefix(sampleCount))
+        let keys = Array(attachmentKeys.prefix(sampleCount))
+        lineMetricsByKey = textRangeFrameCalculator.collectLineMetrics(
+            for: preparedString,
+            containerSize: container,
+            ranges: ranges,
+            keys: keys,
+            summaryProvider: { summary(for: $0) }
+        )
+    }
+
+    func summary(for key: AnyHashable) -> String {
+        guard let textType = key.base as? TextType else {
+            return "key=\(key)"
+        }
+        switch textType {
+        case let .attachment(id, tag, attributes, _):
+            let src = attributes["src"]?.string ?? "-"
+            let width = attributes["width"]?.string ?? "-"
+            let height = attributes["height"]?.string ?? "-"
+            return "id=\(id) tag=\(tag) src=\(src) w=\(width) h=\(height)"
+        case let .text(string, _):
+            return "text=\(string.prefix(12))"
+        case .newLine:
+            return "newline"
+        }
+    }
+
+    func logMissingAttachmentsIfNeeded() {
+        guard shouldLog else { return }
+        guard !attachmentKeys.isEmpty else { return }
+        let expected = Set(attachmentKeys)
+        let present = Set(frameStore.keys)
+        guard expected.count > present.count else { return }
+        let missing = expected.subtracting(present)
+        guard !missing.isEmpty else { return }
+        let sample = missing.prefix(3).map { "\($0)" }.joined(separator: ", ")
+        AttachmentDebugLogger.recordOnce(
+            "missing-attachments-\(expected.count)-\(present.count)",
+            message: "[AttachmentLayout] missing attachment frames expected=\(expected.count) present=\(present.count) sample=\(sample)"
+        )
     }
 }
 
@@ -195,7 +570,12 @@ private extension NSMutableAttributedString {
         }
 
         let paragraphStyle = NSMutableParagraphStyle()
-        paragraphStyle.lineBreakMode = .byWordWrapping
+        switch styleContainer.lineBreakMode {
+        case .byCharWrapping:
+            paragraphStyle.lineBreakMode = .byCharWrapping
+        default:
+            paragraphStyle.lineBreakMode = .byWordWrapping
+        }
         paragraphStyle.lineBreakStrategy = .standard
 
         paragraphStyle.lineSpacing = styleContainer.textLine?.lineSpacing ?? 0
diff --git a/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutTracker.swift b/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutTracker.swift
new file mode 100644
index 0000000..dafa34e
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Attachment/AttachmentLayoutTracker.swift
@@ -0,0 +1,40 @@
+//  Copyright © 2026 PRND. All rights reserved.
+import Foundation
+
+actor AttachmentLayoutTracker {
+    static let shared = AttachmentLayoutTracker()
+
+    private var lastUpdate: Date = .distantPast
+    private var lastCounts: AttachmentCounts?
+
+    struct AttachmentCounts: Sendable {
+        let expected: Int
+        let expectedImages: Int
+        let prepared: Int
+        let uniqueKeys: Int
+    }
+
+    func markUpdated() {
+        lastUpdate = Date()
+    }
+
+    func recordCounts(_ counts: AttachmentCounts) {
+        lastCounts = counts
+    }
+
+    func snapshotCounts() -> AttachmentCounts? {
+        lastCounts
+    }
+
+    func waitUntilIdle(timeoutSeconds: TimeInterval, quietSeconds: TimeInterval = 0.35) async -> Bool {
+        let start = Date()
+        while Date().timeIntervalSince(start) < timeoutSeconds {
+            let last = lastUpdate
+            if Date().timeIntervalSince(last) >= quietSeconds {
+                return true
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+        return false
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Attachment/AttachmentManager.swift b/Sources/SwiftUIHTML/Core/Attachment/AttachmentManager.swift
index 534c58a..3000461 100644
--- a/Sources/SwiftUIHTML/Core/Attachment/AttachmentManager.swift
+++ b/Sources/SwiftUIHTML/Core/Attachment/AttachmentManager.swift
@@ -1,16 +1,32 @@
 // Copyright © 2025 PRND. All rights reserved.
-import UIKit
 import Combine
+import CoreGraphics
+import Foundation
+#if canImport(os)
+import os
+#endif
 
 
 final class AttachmentManager: ObservableObject {
     lazy var layoutEngine = AttachmentLayoutEngine()
     private var cancellables = Set<AnyCancellable>()
+    private var shouldLog: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+            || NSClassFromString("XCTestCase") != nil
+    }
+#if canImport(os)
+    private static let logger = Logger(subsystem: "SwiftUIHTML", category: "AttachmentManager")
+#endif
 
-    private class ImageCache: NSCache<AttachmentImageCacheKey, UIImage> {}
+    private class ImageCache: NSCache<AttachmentImageCacheKey, PlatformImage> {}
     private let textImages = ImageCache()
 
     init() {
+        textImages.countLimit = 512
+        textImages.totalCostLimit = 8 * 1024 * 1024
         layoutEngine.layoutUpdatePublisher
             .receive(on: DispatchQueue.main)
             .sink { [weak self] in
@@ -31,18 +47,33 @@ final class AttachmentManager: ObservableObject {
 
     func setAttachmentSize(key: AnyHashable, size: CGSize, styleContainer: HTMLStyleContainer) {
         layoutEngine.setSize(key: key, size: size)
-        //NOTE: lineSpacing 각각 다를 수 있음
-        layoutEngine.lineSpacing = styleContainer.textLine?.lineSpacing ?? 0
+        log("setAttachmentSize key=\(key) size=\(size)")
     }
 
     func offset(key: AnyHashable) -> CGSize {
         let point = layoutEngine.getOffset(key: key)
+        log("offset key=\(key) point=\(point)")
         return CGSize(width: point.x, height: point.y)
     }
 
+    func frame(key: AnyHashable) -> CGRect? {
+        layoutEngine.getFrame(key: key)
+    }
+
+    func lineMetrics(key: AnyHashable) -> TextRangeFrameCalculator.LineMetrics? {
+        layoutEngine.getLineMetrics(key: key)
+    }
+
     // SwiftUI Text(image:) 주입 이미지
-    func sizeImage(key: AnyHashable, styleContainer: HTMLStyleContainer) -> UIImage {
+    func sizeImage(key: AnyHashable, styleContainer: HTMLStyleContainer) -> PlatformImage {
         var size = layoutEngine.getSize(key: key)
+        if size == .zero, let fallbackSize = fallbackAttachmentSize(for: key) {
+            size = fallbackSize
+            log("fallback size key=\(key) size=\(size)")
+        }
+        if size == .zero {
+            return PlatformImage.manabiEmpty(size: .zero)
+        }
         var fontName: String? = nil
         var fontSize: CGFloat? = nil
         if let uiFont = styleContainer.uiFont {
@@ -59,33 +90,47 @@ final class AttachmentManager: ObservableObject {
             return image
         }
         let image = EmptyImage(size: size).image
-        textImages.setObject(image, forKey: cacheKey)
+        let cost = max(1, Int(size.width * size.height * 4))
+        textImages.setObject(image, forKey: cacheKey, cost: cost)
         return image
     }
 
+    private func fallbackAttachmentSize(for key: AnyHashable) -> CGSize? {
+        guard let textType = key.base as? TextType else { return nil }
+        guard case let .attachment(_, _, attributes, _) = textType else { return nil }
+        let elementSize = ElementSize(attributes: attributes)
+        guard let width = elementSize.width ?? elementSize.height,
+              let height = elementSize.height ?? elementSize.width else {
+            return nil
+        }
+        return CGSize(width: max(1, width), height: max(1, height))
+    }
+
     func clearImageCache() {
         textImages.removeAllObjects()
     }
 }
 
 private extension AttachmentManager {
+    func log(_ message: @autoclosure () -> String) {
+        guard shouldLog else { return }
+        let rendered = message()
+        AttachmentDebugLogger.record("[AttachmentManager] \(rendered)")
+#if canImport(os)
+        if #available(iOS 14.0, macOS 11.0, *) {
+            AttachmentManager.logger.debug("\(rendered, privacy: .public)")
+        }
+#endif
+        NSLog("[SwiftUIHTML][AttachmentManager] %@", rendered)
+        print("[SwiftUIHTML][AttachmentManager] \(rendered)")
+    }
 }
 
 private struct EmptyImage {
-    let scale: CGFloat
     let size: CGSize
 
-    init(scale: CGFloat = 1, size: CGSize) {
-        self.scale = scale
-        self.size = size
-    }
-
-    var image: UIImage {
-        if size == .zero { return UIImage() }
-        let format = UIGraphicsImageRendererFormat()
-        format.scale = 1
-        let renderer = UIGraphicsImageRenderer(size: size, format: format)
-        return renderer.image { _ in }
+    var image: PlatformImage {
+        PlatformImage.manabiEmpty(size: size)
     }
 }
 
diff --git a/Sources/SwiftUIHTML/Core/Attachment/ImageLoadTracker.swift b/Sources/SwiftUIHTML/Core/Attachment/ImageLoadTracker.swift
new file mode 100644
index 0000000..ce1e345
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Attachment/ImageLoadTracker.swift
@@ -0,0 +1,40 @@
+//  Copyright © 2026 PRND. All rights reserved.
+import Foundation
+
+@MainActor
+final class ImageLoadTracker {
+    static let shared = ImageLoadTracker()
+
+    private var inFlight: Set<String> = []
+
+    func begin(url: URL?) {
+        guard let url else { return }
+        let key = url.absoluteString
+        let (inserted, _) = inFlight.insert(key)
+        if inserted {
+            AttachmentDebugLogger.record("[ImageLoadTracker] begin \(key) inflight=\(inFlight.count)")
+        }
+    }
+
+    func end(url: URL?) {
+        guard let url else { return }
+        let key = url.absoluteString
+        if inFlight.remove(key) != nil {
+            AttachmentDebugLogger.record("[ImageLoadTracker] end \(key) inflight=\(inFlight.count)")
+        }
+    }
+
+    func waitUntilIdle(timeoutSeconds: TimeInterval) async -> Bool {
+        let deadline = Date().addingTimeInterval(timeoutSeconds)
+        while !inFlight.isEmpty {
+            if Date() >= deadline {
+                let urls = inFlight.sorted()
+                let suffix = urls.isEmpty ? "" : " urls=\(urls)"
+                AttachmentDebugLogger.record("[ImageLoadTracker] timeout inflight=\(inFlight.count)\(suffix)")
+                return false
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+        return true
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/AttributeStyle/DefaultAttributeStyle.swift b/Sources/SwiftUIHTML/Core/AttributeStyle/DefaultAttributeStyle.swift
index b004b9a..4f75e80 100644
--- a/Sources/SwiftUIHTML/Core/AttributeStyle/DefaultAttributeStyle.swift
+++ b/Sources/SwiftUIHTML/Core/AttributeStyle/DefaultAttributeStyle.swift
@@ -16,7 +16,7 @@ public struct DefaultAttributeStyler: AttributeStyleable {
         attributes: [String : AttributeValue],
         to styleContainer: inout HTMLStyleContainer
     ) {
-        let cssStyle = attributes["style"]?.cssStyle ?? .empty
+        guard let cssStyle = attributes["style"]?.cssStyle else { return }
 
         if let color = cssStyle["color"]?.toColor() {
             styleContainer.foregroundColor = color
@@ -26,20 +26,33 @@ public struct DefaultAttributeStyler: AttributeStyleable {
             styleContainer.backgroundColor = color
         }
 
+        if CSSFontUtility.shouldLogFontResolution(),
+           let fontFamilyValue = cssStyle["font-family"]?.string {
+            AttachmentDebugLogger.record("[Font] style font-family=\(fontFamilyValue) current=\(styleContainer.uiFont?.fontName ?? "nil")")
+        }
+
         if let newFont = CSSFontUtility.createFont(
             fromCSSStyle: cssStyle,
             currentFont: styleContainer.uiFont
         ) {
             styleContainer.uiFont = newFont
+            if case let .lineHeight(_, lineHeight)? = styleContainer.textLine {
+                styleContainer.textLine = .lineHeight(font: newFont, lineHeight: lineHeight)
+            }
         }
 
-        if let lineHeight = cssStyle["line-height"]?.cgFloat, let font = styleContainer.uiFont {
+        if let rawLineHeight = cssStyle["line-height"]?.string,
+           let font = styleContainer.uiFont,
+           let lineHeight = resolveLineHeight(rawLineHeight, font: font) {
             styleContainer.textLine = .lineHeight(font: font, lineHeight: lineHeight)
         } else if let lineSpacing = cssStyle["line-spacing"]?.cgFloat {
             styleContainer.textLine = .lineSpacing(spacing: lineSpacing)
         }
 
         if let wordBreak = cssStyle["word-break"]?.string {
+            if CSSFontUtility.shouldLogFontResolution() {
+                AttachmentDebugLogger.record("[Text] word-break=\(wordBreak) currentLineBreak=\(styleContainer.lineBreakMode)")
+            }
             switch wordBreak {
             case "break-all":
                 styleContainer.lineBreakMode = .byCharWrapping
@@ -51,3 +64,28 @@ public struct DefaultAttributeStyler: AttributeStyleable {
         }
     }
 }
+
+private func resolveLineHeight(_ rawValue: String, font: PlatformFont) -> CGFloat? {
+    let trimmed = ASCIIWhitespace.trim(rawValue)
+    guard !trimmed.isEmpty else { return nil }
+    let value = String(trimmed)
+    let lowered = value.lowercased()
+
+    if lowered == "normal" || lowered == "inherit" || lowered == "initial" || lowered == "unset" {
+        return font.manabiLineHeight
+    }
+
+    if lowered.hasSuffix("px")
+        || lowered.hasSuffix("pt")
+        || lowered.hasSuffix("em")
+        || lowered.hasSuffix("rem")
+        || lowered.hasSuffix("%") {
+        return CSSFontUtility.parseSize(fromFontSize: value, baseSize: font.pointSize)
+    }
+
+    if let multiplier = Double(lowered) {
+        return font.pointSize * CGFloat(multiplier)
+    }
+
+    return nil
+}
diff --git a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleModifier.swift b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleModifier.swift
index e995184..c777ccf 100644
--- a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleModifier.swift
+++ b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleModifier.swift
@@ -6,13 +6,17 @@ struct LayoutStyleModifier: ViewModifier {
     let cssStyle: CSSStyle
     
     func body(content: Content) -> some View {
-        content
-            .modifier(EdgeModifier(property: "padding", cssStyle: cssStyle))
-            .modifier(InnerLayoutModifier(cssStyle: cssStyle))
-            .modifier(BackgroundModifier(cssStyle: cssStyle))
-            .modifier(BorderModifier(cssStyle: cssStyle))
-            .compositingGroup()
-            .modifier(EffectsModifier(cssStyle: cssStyle))
-            .modifier(EdgeModifier(property: "margin", cssStyle: cssStyle))
+        if cssStyle.isEmpty {
+            content
+        } else {
+            content
+                .modifier(EdgeModifier(property: "padding", cssStyle: cssStyle))
+                .modifier(InnerLayoutModifier(cssStyle: cssStyle))
+                .modifier(BackgroundModifier(cssStyle: cssStyle))
+                .modifier(BorderModifier(cssStyle: cssStyle))
+                .compositingGroup()
+                .modifier(EffectsModifier(cssStyle: cssStyle))
+                .modifier(EdgeModifier(property: "margin", cssStyle: cssStyle))
+        }
     }
 }
diff --git a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/EffectsModifier.swift b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/EffectsModifier.swift
index 7bdbb52..9778de2 100644
--- a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/EffectsModifier.swift
+++ b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/EffectsModifier.swift
@@ -31,9 +31,9 @@ private struct ShadowModifier: ViewModifier {
     
     private func parseShadow(_ boxShadow: String) -> (color: Color, radius: CGFloat, x: CGFloat, y: CGFloat) {
         var color: Color = .black.opacity(0.33)
-        var radius: CGFloat = 3
-        var x: CGFloat = 0
-        var y: CGFloat = 2
+        let radius: CGFloat = 3
+        let x: CGFloat = 0
+        let y: CGFloat = 2
         
         if boxShadow.lowercased() == "none" || boxShadow.lowercased() == "initial" {
             return (Color.clear, 0, 0, 0)
diff --git a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/InnerLayoutModifier.swift b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/InnerLayoutModifier.swift
index 5415f5a..62dc761 100644
--- a/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/InnerLayoutModifier.swift
+++ b/Sources/SwiftUIHTML/Core/AttributeStyle/LayoutStyleSubModifier/InnerLayoutModifier.swift
@@ -6,14 +6,20 @@ struct InnerLayoutModifier: ViewModifier {
     let cssStyle: CSSStyle
 
     func body(content: Content) -> some View {
+        let width = cssStyle["width"]?.cgFloat
+        let height = cssStyle["height"]?.cgFloat
+        let minWidth = cssStyle["min-width"]?.cgFloat ?? width
+        let maxWidth = cssStyle["max-width"]?.cgFloat
+        let minHeight = cssStyle["min-height"]?.cgFloat ?? height
+        let maxHeight = cssStyle["max-height"]?.cgFloat
         content
             .frame(
-                minWidth: cssStyle["min-width"]?.cgFloat,
-                idealWidth: cssStyle["width"]?.cgFloat,
-                maxWidth: cssStyle["max-width"]?.cgFloat,
-                minHeight: cssStyle["min-height"]?.cgFloat,
-                idealHeight: cssStyle["height"]?.cgFloat,
-                maxHeight: cssStyle["max-height"]?.cgFloat,
+                minWidth: minWidth,
+                idealWidth: width,
+                maxWidth: maxWidth,
+                minHeight: minHeight,
+                idealHeight: height,
+                maxHeight: maxHeight,
                 alignment: getAlignment()
             )
     }
@@ -26,13 +32,13 @@ private extension InnerLayoutModifier {
            case "center":
                return .center
            case "left":
-               return .leading
+               return .topLeading
            case "right":
-               return .trailing
+               return .topTrailing
            default:
-               return .center
+               return .topLeading
            }
        }
-       return .center
+       return .topLeading
    }
 }
diff --git a/Sources/SwiftUIHTML/Core/CoreText/CoreTextRunDelegateManager.swift b/Sources/SwiftUIHTML/Core/CoreText/CoreTextRunDelegateManager.swift
index a9158dd..1443e21 100644
--- a/Sources/SwiftUIHTML/Core/CoreText/CoreTextRunDelegateManager.swift
+++ b/Sources/SwiftUIHTML/Core/CoreText/CoreTextRunDelegateManager.swift
@@ -15,9 +15,16 @@ final class CoreTextRunDelegateManager {
             },
             getAscent: { pointer -> CGFloat in
                 let attachment = Unmanaged<TextAttachment>.fromOpaque(pointer).takeUnretainedValue()
+                if let metrics = attachment.rubyMetrics() {
+                    return metrics.ascent
+                }
                 return attachment.getAdjustedSize().height
             },
-            getDescent: { _ in
+            getDescent: { pointer in
+                let attachment = Unmanaged<TextAttachment>.fromOpaque(pointer).takeUnretainedValue()
+                if let metrics = attachment.rubyMetrics() {
+                    return metrics.descent
+                }
                 return 0
             },
             getWidth: { pointer -> CGFloat in
diff --git a/Sources/SwiftUIHTML/Core/CoreText/TextRangeFrameCalculator.swift b/Sources/SwiftUIHTML/Core/CoreText/TextRangeFrameCalculator.swift
index a146f0e..b6b4455 100644
--- a/Sources/SwiftUIHTML/Core/CoreText/TextRangeFrameCalculator.swift
+++ b/Sources/SwiftUIHTML/Core/CoreText/TextRangeFrameCalculator.swift
@@ -1,7 +1,9 @@
 //  Copyright © 2025 PRND. All rights reserved.
 import Foundation
 import CoreText
-import UIKit
+#if os(macOS)
+import AppKit
+#endif
 
 /// Calculates frame rectangles for text ranges using Core Text
 final class TextRangeFrameCalculator {
@@ -58,18 +60,29 @@ final class TextRangeFrameCalculator {
     /// - Parameter attributedString: The attributed string to prepare
     /// - Returns: A mutable attributed string prepared for Core Text
     func prepareCoreTextString(_ attributedString: NSAttributedString) -> NSMutableAttributedString {
-        let mutableAttrString = NSMutableAttributedString(attributedString: attributedString)
+        let fullRange = NSRange(location: 0, length: attributedString.length)
+        var mutableAttrString: NSMutableAttributedString?
 
-        let fullRange = NSRange(location: 0, length: mutableAttrString.length)
-        mutableAttrString.enumerateAttribute(.attachment, in: fullRange) { value, range, _ in
+        attributedString.enumerateAttribute(.attachment, in: fullRange) { value, range, _ in
             guard let attachment = value as? TextAttachment else { return }
+            if mutableAttrString == nil {
+                mutableAttrString = attributedString.mutableCopy() as? NSMutableAttributedString
+                    ?? NSMutableAttributedString(attributedString: attributedString)
+            }
+            guard let mutableAttrString else { return }
             if let delegate = CoreTextRunDelegateManager.shared.createDelegate(for: attachment) {
                 mutableAttrString.removeAttribute(.attachment, range: range)
                 mutableAttrString.addAttribute(.runDelegate, value: delegate, range: range)
             }
         }
 
-        return mutableAttrString
+        if let mutableAttrString {
+            return mutableAttrString
+        }
+        if let mutable = attributedString as? NSMutableAttributedString {
+            return mutable
+        }
+        return NSMutableAttributedString(attributedString: attributedString)
     }
 
     /// Main interface: Measures layout for specified text ranges
@@ -89,6 +102,117 @@ final class TextRangeFrameCalculator {
             targetRanges: ranges
         )
     }
+
+    struct LineMetrics {
+        let range: NSRange
+        let lineIndex: Int
+        let lineOrigin: CGPoint
+        let ascent: CGFloat
+        let descent: CGFloat
+        let leading: CGFloat
+        let lineRect: CGRect
+    }
+
+    func collectLineMetrics(
+        for attributedString: NSAttributedString,
+        containerSize: CGSize,
+        ranges: [NSRange],
+        keys: [AnyHashable],
+        summaryProvider: (AnyHashable) -> String
+    ) -> [AnyHashable: LineMetrics] {
+        guard !ranges.isEmpty, !keys.isEmpty else { return [:] }
+        let frame = createTextFrame(for: attributedString, containerSize: containerSize)
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        guard !lines.isEmpty else { return [:] }
+
+        let adjustedOrigins = adjustLineOrigins(frame: frame, lines: lines, containerSize: containerSize)
+        var metricsByKey: [AnyHashable: LineMetrics] = [:]
+        metricsByKey.reserveCapacity(ranges.count)
+        for (index, range) in ranges.enumerated() {
+            let key = keys.count > index ? keys[index] : keys.last!
+            var matchedLineIndex: Int? = nil
+            for (lineIndex, line) in lines.enumerated() {
+                let lineRange = CTLineGetStringRange(line)
+                let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
+                if NSIntersectionRange(lineNSRange, range).length > 0 {
+                    matchedLineIndex = lineIndex
+                    break
+                }
+            }
+            guard let lineIndex = matchedLineIndex else { continue }
+            let line = lines[lineIndex]
+            var ascent: CGFloat = 0
+            var descent: CGFloat = 0
+            var leading: CGFloat = 0
+            _ = CTLineGetTypographicBounds(line, &ascent, &descent, &leading)
+            let lineOrigin = adjustedOrigins[lineIndex]
+            let rect = CGRect(
+                x: 0,
+                y: -descent,
+                width: 0,
+                height: ascent + descent
+            )
+            let lineRect = CGRect(
+                x: rect.origin.x + lineOrigin.x,
+                y: lineOrigin.y + rect.origin.y,
+                width: rect.size.width,
+                height: rect.size.height
+            )
+            metricsByKey[key] = LineMetrics(
+                range: range,
+                lineIndex: lineIndex,
+                lineOrigin: lineOrigin,
+                ascent: ascent,
+                descent: descent,
+                leading: leading,
+                lineRect: lineRect
+            )
+            AttachmentDebugLogger.record(
+                "[LineMetrics] key=\(summaryProvider(key)) range=\(range) lineIndex=\(lineIndex) lineOrigin=\(lineOrigin) ascent=\(ascent) descent=\(descent) leading=\(leading) lineRect=\(lineRect) container=\(containerSize)"
+            )
+        }
+        return metricsByKey
+    }
+
+#if os(macOS)
+    func measureLayoutWithTextKit(
+        attributedString: NSAttributedString,
+        in containerSize: CGSize,
+        by ranges: [NSRange]
+    ) -> [CGRect] {
+        let textStorage = NSTextStorage(attributedString: attributedString)
+        let layoutManager = NSLayoutManager()
+        let textContainer = NSTextContainer(size: containerSize)
+        textContainer.lineFragmentPadding = 0
+        textContainer.widthTracksTextView = false
+        textContainer.heightTracksTextView = false
+        layoutManager.addTextContainer(textContainer)
+        textStorage.addLayoutManager(layoutManager)
+        layoutManager.ensureLayout(for: textContainer)
+
+        var rects: [CGRect] = []
+        rects.reserveCapacity(ranges.count)
+        for range in ranges {
+            let glyphRange = layoutManager.glyphRange(
+                forCharacterRange: range,
+                actualCharacterRange: nil
+            )
+            let rect = layoutManager.boundingRect(forGlyphRange: glyphRange, in: textContainer)
+            if ProcessInfo.processInfo.environment["SWIFTUIHTML_TEXTKIT_FLIP_Y"] == "1" {
+                let flipped = CGRect(
+                    x: rect.origin.x,
+                    y: max(0, containerSize.height - rect.origin.y - rect.height),
+                    width: rect.width,
+                    height: rect.height
+                )
+                rects.append(flipped)
+            } else {
+                rects.append(rect)
+            }
+        }
+        return rects
+    }
+#endif
 }
 
 // MARK: - Private Methods
@@ -116,7 +240,7 @@ private extension TextRangeFrameCalculator {
     ///   - containerSize: Size of the container
     /// - Returns: A Core Text frame
     func createTextFrame(for attrString: NSAttributedString, containerSize: CGSize) -> CTFrame {
-        let framesetter = CTFramesetterCreateWithAttributedString(attrString)
+        let framesetter = framesetter(for: attrString)
 
         // Calculate optimal text size with constraints
         let suggestedSize = CTFramesetterSuggestFrameSizeWithConstraints(
@@ -129,8 +253,6 @@ private extension TextRangeFrameCalculator {
 
         // Ensure minimum dimensions
         let width = max(suggestedSize.width, containerSize.width)
-        let height = max(suggestedSize.height, containerSize.height)
-
         let rect = CGRect(origin: .zero, size: CGSize(width: width, height: suggestedSize.height))
         let path = CGPath(rect: rect, transform: nil)
 
@@ -201,10 +323,19 @@ private extension TextRangeFrameCalculator {
     ///   - targetRanges: Text ranges to measure
     /// - Returns: Array of rectangles for each range
     func calculateRangeRects(in frame: CTFrame, containerSize: CGSize, targetRanges: [NSRange]) -> [CGRect] {
+        return calculateRangeRectsStreaming(
+            in: frame,
+            containerSize: containerSize,
+            targetRanges: targetRanges
+        )
+    }
+
+    func calculateRangeRectsLegacy(in frame: CTFrame, containerSize: CGSize, targetRanges: [NSRange]) -> [CGRect] {
         let lines = CTFrameGetLines(frame) as! [CTLine]
         let adjustedOrigins = adjustLineOrigins(frame: frame, lines: lines, containerSize: containerSize)
 
         var rangeRects: [CGRect] = []
+        rangeRects.reserveCapacity(targetRanges.count)
 
         // Process each line
         for (lineIndex, line) in lines.enumerated() {
@@ -219,18 +350,22 @@ private extension TextRangeFrameCalculator {
             guard !intersectingRanges.isEmpty else { continue }
 
             let lineOrigin = adjustedOrigins[lineIndex]
-            let characterRects = calculateCharacterBounds(in: line, ranges: intersectingRanges)
-
-            // Get line metrics
-            var ascent: CGFloat = 0
-            var descent: CGFloat = 0
-            _ = CTLineGetTypographicBounds(line, &ascent, &descent, nil)
+            let characterRects = calculateCharacterBounds(
+                in: line,
+                lineRange: lineNSRange,
+                ranges: intersectingRanges
+            )
 
             // Create rect for each character range
             for charFrame in characterRects {
+#if os(macOS)
+                let yOrigin = lineOrigin.y + charFrame.origin.y
+#else
+                let yOrigin = lineOrigin.y
+#endif
                 let lineRect = CGRect(
-                    x: charFrame.origin.x,
-                    y: lineOrigin.y,
+                    x: charFrame.origin.x + lineOrigin.x,
+                    y: yOrigin,
                     width: charFrame.size.width,
                     height: charFrame.size.height
                 )
@@ -241,16 +376,171 @@ private extension TextRangeFrameCalculator {
         return rangeRects
     }
 
+    func calculateRangeRectsOptimized(in frame: CTFrame, containerSize: CGSize, targetRanges: [NSRange]) -> [CGRect] {
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        guard !lines.isEmpty else { return [] }
+
+        let adjustedOrigins = adjustLineOrigins(frame: frame, lines: lines, containerSize: containerSize)
+
+        var rangesAreSorted = true
+        if targetRanges.count > 1 {
+            for index in 1..<targetRanges.count where targetRanges[index].location < targetRanges[index - 1].location {
+                rangesAreSorted = false
+                break
+            }
+        }
+        let ranges = rangesAreSorted ? targetRanges : targetRanges.sorted { $0.location < $1.location }
+
+        var rangeRects: [CGRect] = []
+        rangeRects.reserveCapacity(targetRanges.count)
+
+        var rangeIndex = 0
+
+        for (lineIndex, line) in lines.enumerated() {
+            let lineRange = CTLineGetStringRange(line)
+            let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
+            let lineStart = lineNSRange.location
+            let lineEnd = lineNSRange.location + lineNSRange.length
+
+            while rangeIndex < ranges.count,
+                  ranges[rangeIndex].location + ranges[rangeIndex].length <= lineStart {
+                rangeIndex += 1
+            }
+
+            if rangeIndex >= ranges.count {
+                break
+            }
+
+            var intersectingRanges: [NSRange] = []
+            var scanIndex = rangeIndex
+            while scanIndex < ranges.count {
+                let range = ranges[scanIndex]
+                if range.location >= lineEnd {
+                    break
+                }
+                if NSIntersectionRange(lineNSRange, range).length > 0 {
+                    intersectingRanges.append(range)
+                }
+                scanIndex += 1
+            }
+
+            guard !intersectingRanges.isEmpty else { continue }
+
+            let lineOrigin = adjustedOrigins[lineIndex]
+            let characterRects = calculateCharacterBounds(
+                in: line,
+                lineRange: lineNSRange,
+                ranges: intersectingRanges
+            )
+
+            for charFrame in characterRects {
+#if os(macOS)
+                let yOrigin = lineOrigin.y + charFrame.origin.y
+#else
+                let yOrigin = lineOrigin.y
+#endif
+                let lineRect = CGRect(
+                    x: charFrame.origin.x + lineOrigin.x,
+                    y: yOrigin,
+                    width: charFrame.size.width,
+                    height: charFrame.size.height
+                )
+                rangeRects.append(lineRect)
+            }
+        }
+
+        return rangeRects
+    }
+
+    func calculateRangeRectsStreaming(in frame: CTFrame, containerSize: CGSize, targetRanges: [NSRange]) -> [CGRect] {
+        let lines = CTFrameGetLines(frame) as! [CTLine]
+        guard !lines.isEmpty else { return [] }
+
+        let adjustedOrigins = adjustLineOrigins(frame: frame, lines: lines, containerSize: containerSize)
+
+        var rangesAreSorted = true
+        if targetRanges.count > 1 {
+            for index in 1..<targetRanges.count where targetRanges[index].location < targetRanges[index - 1].location {
+                rangesAreSorted = false
+                break
+            }
+        }
+        let ranges = rangesAreSorted ? targetRanges : targetRanges.sorted { $0.location < $1.location }
+
+        var rangeRects: [CGRect] = []
+        rangeRects.reserveCapacity(targetRanges.count)
+
+        var rangeIndex = 0
+
+        for (lineIndex, line) in lines.enumerated() {
+            let lineRange = CTLineGetStringRange(line)
+            let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
+            let lineStart = lineNSRange.location
+            let lineEnd = lineNSRange.location + lineNSRange.length
+
+            while rangeIndex < ranges.count,
+                  ranges[rangeIndex].location + ranges[rangeIndex].length <= lineStart {
+                rangeIndex += 1
+            }
+
+            if rangeIndex >= ranges.count {
+                break
+            }
+
+            if ranges[rangeIndex].location >= lineEnd {
+                continue
+            }
+
+            var ascent: CGFloat = 0
+            var descent: CGFloat = 0
+            _ = CTLineGetTypographicBounds(line, &ascent, &descent, nil)
+            let lineOrigin = adjustedOrigins[lineIndex]
+
+            var scanIndex = rangeIndex
+            while scanIndex < ranges.count {
+                let range = ranges[scanIndex]
+                if range.location >= lineEnd {
+                    break
+                }
+                let intersection = NSIntersectionRange(lineNSRange, range)
+                if intersection.length > 0 {
+                    var secondaryOffset: CGFloat = 0
+                    let startOffset = CTLineGetOffsetForStringIndex(line, intersection.location, &secondaryOffset)
+                    let endOffset = CTLineGetOffsetForStringIndex(line, intersection.location + intersection.length, &secondaryOffset)
+                    let rect = CGRect(
+                        x: startOffset,
+                        y: -descent,
+                        width: endOffset - startOffset,
+                        height: ascent + descent
+                    )
+#if os(macOS)
+                    let yOrigin = lineOrigin.y + rect.origin.y
+#else
+                    let yOrigin = lineOrigin.y
+#endif
+                    let lineRect = CGRect(
+                        x: rect.origin.x + lineOrigin.x,
+                        y: yOrigin,
+                        width: rect.size.width,
+                        height: rect.size.height
+                    )
+                    rangeRects.append(lineRect)
+                }
+                scanIndex += 1
+            }
+        }
+
+        return rangeRects
+    }
+
     /// Calculates bounds for text ranges within a line
     /// - Parameters:
     ///   - line: The Core Text line
     ///   - ranges: Text ranges to measure
     /// - Returns: Array of rectangles for the ranges in this line
-    func calculateCharacterBounds(in line: CTLine, ranges: [NSRange]) -> [CGRect] {
+    func calculateCharacterBounds(in line: CTLine, lineRange: NSRange, ranges: [NSRange]) -> [CGRect] {
         var characterBounds: [CGRect] = []
-
-        let lineRange = CTLineGetStringRange(line)
-        let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
+        characterBounds.reserveCapacity(ranges.count)
 
         // Calculate metrics for the line
         var ascent: CGFloat = 0
@@ -260,7 +550,7 @@ private extension TextRangeFrameCalculator {
         // Process each range
         for range in ranges {
             // Check if the range intersects with this line
-            let intersection = NSIntersectionRange(lineNSRange, range)
+            let intersection = NSIntersectionRange(lineRange, range)
             guard intersection.length > 0 else { continue }
 
             // Calculate offsets for the intersection range
@@ -283,6 +573,12 @@ private extension TextRangeFrameCalculator {
     }
 }
 
+private extension TextRangeFrameCalculator {
+    func framesetter(for attributedString: NSAttributedString) -> CTFramesetter {
+        return CTFramesetterCreateWithAttributedString(attributedString)
+    }
+}
+
 // MARK: - Extensions
 
 extension NSAttributedString.Key {
diff --git a/Sources/SwiftUIHTML/Core/Element/InlineElement.swift b/Sources/SwiftUIHTML/Core/Element/InlineElement.swift
index 232138a..772e966 100644
--- a/Sources/SwiftUIHTML/Core/Element/InlineElement.swift
+++ b/Sources/SwiftUIHTML/Core/Element/InlineElement.swift
@@ -34,19 +34,20 @@ extension Collection where Element == InlineElement {
     
     @MainActor
     func toHTMLTextType() -> [TextType] {
+        var results: [TextType] = []
+        results.reserveCapacity(count)
         var textCount = 0
-        var attachmentCount = 0
 
-        return map { element in
+        for element in self {
             switch element.type {
             case .text:
                 defer { textCount += 1 }
-                return element.toHTMLTextType(id: textCount)
+                results.append(element.toHTMLTextType(id: textCount))
             case .attachment:
-                defer { attachmentCount += 1 }
-                return element.toHTMLTextType(id: attachmentCount)
+                results.append(element.toHTMLTextType(id: AttachmentIDGenerator.next()))
             }
         }
+        return results
     }
 }
 
diff --git a/Sources/SwiftUIHTML/Core/Extension/Color+hex.swift b/Sources/SwiftUIHTML/Core/Extension/Color+hex.swift
index f4c17b3..5acd53c 100644
--- a/Sources/SwiftUIHTML/Core/Extension/Color+hex.swift
+++ b/Sources/SwiftUIHTML/Core/Extension/Color+hex.swift
@@ -6,26 +6,27 @@ extension Color {
     /// Initializes a `Color` from a CSS color string.
     /// - Parameter cssString: The CSS color string (e.g., "rgb(255,0,0)", "#RRGGBB", "red").
     init?(cssString: String) {
-        let trimmedCSS = cssString.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedCSS = ASCIIWhitespace.trim(cssString)
+        let trimmedString = String(trimmedCSS)
 
         // RGB/RGBA 형식 처리
-        if trimmedCSS.hasPrefix("rgb") {
-            if let color = Color.fromRGBString(trimmedCSS) {
+        if trimmedString.hasPrefix("rgb") {
+            if let color = Color.fromRGBString(trimmedString) {
                 self = color
                 return
             }
         }
 
         // 16진수 형식 처리
-        else if trimmedCSS.hasPrefix("#") {
-            if let color = Color.fromHexString(trimmedCSS) {
+        else if trimmedString.hasPrefix("#") {
+            if let color = Color.fromHexString(trimmedString) {
                 self = color
                 return
             }
         }
 
         // 명명된 색상 처리
-        else if let color = Color.fromNamedColor(trimmedCSS) {
+        else if let color = Color.fromNamedColor(trimmedString) {
             self = color
             return
         }
@@ -37,6 +38,9 @@ extension Color {
 
     /// RGB 또는 RGBA 문자열에서 Color 생성
     private static func fromRGBString(_ rgbString: String) -> Color? {
+        if let color = Color.fromRGBStringFast(rgbString) {
+            return color
+        }
         let rgbPattern = "rgba?\\((\\d+),\\s*(\\d+),\\s*(\\d+)(?:,\\s*([0-9.]+))?\\)"
         guard let regex = try? NSRegularExpression(pattern: rgbPattern, options: []),
               let match = regex.firstMatch(in: rgbString, options: [], range: NSRange(rgbString.startIndex..<rgbString.endIndex, in: rgbString)) else {
@@ -72,45 +76,173 @@ extension Color {
         return Color(.sRGB, red: r, green: g, blue: b, opacity: a)
     }
 
+    private static func fromRGBStringFast(_ rgbString: String) -> Color? {
+        let trimmed = ASCIIWhitespace.trim(rgbString)
+        let utf8 = trimmed.utf8
+        guard utf8.count >= 8 else { return nil }
+
+        var index = utf8.startIndex
+        func advance() { index = utf8.index(after: index) }
+
+        // prefix: rgb or rgba
+        guard utf8[index] == 0x72, utf8.index(after: index) < utf8.endIndex else { return nil } // r
+        advance()
+        guard utf8[index] == 0x67, utf8.index(after: index) < utf8.endIndex else { return nil } // g
+        advance()
+        guard utf8[index] == 0x62 else { return nil } // b
+        advance()
+
+        var hasAlpha = false
+        if index < utf8.endIndex, utf8[index] == 0x61 { // a
+            hasAlpha = true
+            advance()
+        }
+
+        // skip whitespace
+        while index < utf8.endIndex, ASCIIWhitespace.isWhitespace(utf8[index]) {
+            advance()
+        }
+
+        guard index < utf8.endIndex, utf8[index] == 0x28 else { return nil } // (
+        advance()
+
+        var components: [Double] = []
+        components.reserveCapacity(hasAlpha ? 4 : 3)
+
+        func parseNumber() -> Double? {
+            while index < utf8.endIndex, ASCIIWhitespace.isWhitespace(utf8[index]) {
+                advance()
+            }
+            guard index < utf8.endIndex else { return nil }
+
+            var integer: Double = 0
+            var hasDigits = false
+            while index < utf8.endIndex {
+                let byte = utf8[index]
+                if byte >= 0x30 && byte <= 0x39 {
+                    integer = integer * 10 + Double(byte - 0x30)
+                    hasDigits = true
+                    advance()
+                } else {
+                    break
+                }
+            }
+
+            var fraction: Double = 0
+            var divisor: Double = 1
+            if index < utf8.endIndex, utf8[index] == 0x2E { // "."
+                advance()
+                while index < utf8.endIndex {
+                    let byte = utf8[index]
+                    if byte >= 0x30 && byte <= 0x39 {
+                        fraction = fraction * 10 + Double(byte - 0x30)
+                        divisor *= 10
+                        hasDigits = true
+                        advance()
+                    } else {
+                        break
+                    }
+                }
+            }
+
+            guard hasDigits else { return nil }
+            return integer + fraction / divisor
+        }
+
+        for idx in 0..<(hasAlpha ? 4 : 3) {
+            guard let value = parseNumber() else { return nil }
+            components.append(value)
+            while index < utf8.endIndex, ASCIIWhitespace.isWhitespace(utf8[index]) {
+                advance()
+            }
+            if idx < (hasAlpha ? 3 : 2) {
+                guard index < utf8.endIndex, utf8[index] == 0x2C else { return nil } // ","
+                advance()
+            }
+        }
+
+        while index < utf8.endIndex, ASCIIWhitespace.isWhitespace(utf8[index]) {
+            advance()
+        }
+        guard index < utf8.endIndex, utf8[index] == 0x29 else { return nil } // ")"
+
+        guard components.count >= 3 else { return nil }
+        let r = min(max(components[0] / 255.0, 0), 1)
+        let g = min(max(components[1] / 255.0, 0), 1)
+        let b = min(max(components[2] / 255.0, 0), 1)
+        let a = min(max(components.count >= 4 ? components[3] : 1.0, 0), 1)
+        return Color(.sRGB, red: r, green: g, blue: b, opacity: a)
+    }
+
     // MARK: - 16진수 색상 파싱
 
     /// 16진수 문자열에서 Color 생성
     private static func fromHexString(_ hexString: String) -> Color? {
-        // # 제거
-        var hex = hexString
-        if hex.hasPrefix("#") {
-            hex = String(hex.dropFirst())
-        }
+        let trimmed = ASCIIWhitespace.trim(hexString)
+        guard !trimmed.isEmpty else { return nil }
 
-        // 짧은 형식(RGB, RGBA)을 긴 형식(RRGGBB, RRGGBBAA)으로 변환
-        if hex.count == 3 || hex.count == 4 {
-            hex = hex.map { String(repeating: $0, count: 2) }.joined()
+        var hexBytes = trimmed.utf8
+        if let first = hexBytes.first, first == 0x23 { // "#"
+            hexBytes = hexBytes.dropFirst()
         }
 
-        // 16진수 문자열 검증
-        guard hex.count == 6 || hex.count == 8,
-              hex.allSatisfy({ $0.isHexDigit }) else {
+        let count = hexBytes.count
+        guard count == 3 || count == 4 || count == 6 || count == 8 else {
             return nil
         }
 
-        // 16진수 값 파싱
-        guard let int = UInt64(hex, radix: 16) else {
-            return nil
+        func hexValue(_ byte: UInt8) -> UInt8? {
+            switch byte {
+            case 0x30...0x39:
+                return byte &- 0x30
+            case 0x41...0x46:
+                return byte &- 0x37
+            case 0x61...0x66:
+                return byte &- 0x57
+            default:
+                return nil
+            }
+        }
+
+        var parsed: [UInt8] = []
+        parsed.reserveCapacity(count == 3 ? 3 : count == 4 ? 4 : count / 2)
+
+        if count == 3 || count == 4 {
+            for byte in hexBytes {
+                guard let value = hexValue(byte) else { return nil }
+                let full = (value << 4) | value
+                parsed.append(full)
+            }
+        } else {
+            var index = hexBytes.startIndex
+            while index < hexBytes.endIndex {
+                let highByte = hexBytes[index]
+                let nextIndex = hexBytes.index(after: index)
+                if nextIndex >= hexBytes.endIndex {
+                    return nil
+                }
+                let lowByte = hexBytes[nextIndex]
+                guard let high = hexValue(highByte),
+                      let low = hexValue(lowByte) else {
+                    return nil
+                }
+                parsed.append((high << 4) | low)
+                index = hexBytes.index(after: nextIndex)
+            }
         }
 
-        // 컴포넌트 추출
         let red, green, blue, alpha: Double
-        switch hex.count {
-        case 6: // RGB (RRGGBB)
-            red = Double((int >> 16) & 0xFF) / 255.0
-            green = Double((int >> 8) & 0xFF) / 255.0
-            blue = Double(int & 0xFF) / 255.0
+        switch parsed.count {
+        case 3:
+            red = Double(parsed[0]) / 255.0
+            green = Double(parsed[1]) / 255.0
+            blue = Double(parsed[2]) / 255.0
             alpha = 1.0
-        case 8: // RGBA (RRGGBBAA)
-            red = Double((int >> 24) & 0xFF) / 255.0
-            green = Double((int >> 16) & 0xFF) / 255.0
-            blue = Double((int >> 8) & 0xFF) / 255.0
-            alpha = Double(int & 0xFF) / 255.0
+        case 4:
+            red = Double(parsed[0]) / 255.0
+            green = Double(parsed[1]) / 255.0
+            blue = Double(parsed[2]) / 255.0
+            alpha = Double(parsed[3]) / 255.0
         default:
             return nil
         }
diff --git a/Sources/SwiftUIHTML/Core/HTMLConfiguration/HTMLConfiguration.swift b/Sources/SwiftUIHTML/Core/HTMLConfiguration/HTMLConfiguration.swift
index 0cf6d08..3523bf4 100644
--- a/Sources/SwiftUIHTML/Core/HTMLConfiguration/HTMLConfiguration.swift
+++ b/Sources/SwiftUIHTML/Core/HTMLConfiguration/HTMLConfiguration.swift
@@ -2,13 +2,14 @@
 import SwiftUI
 
 
-public struct HTMLConfiguration: Sendable {
+public struct HTMLConfiguration: @unchecked Sendable {
     enum TagType {
         case block
         case inline
         case attachment
     }
 
+    public var collapseBlockMargins: Bool = false
     var dictionary: [String: HTMLTagElementable.Type] = [:]
     var dictionaryType: [String: TagType] = [:]
     var attributeStyle: any AttributeStyleable = EmptyAttributeStyle()
@@ -16,7 +17,7 @@ public struct HTMLConfiguration: Sendable {
     public init() {
         // 최소한 정의
         self = register(
-            tag: "div", "body", "p", "header", "main", "section", "footer", "h1", "h2",
+            tag: "html", "head", "div", "body", "p", "header", "main", "section", "footer", "h1", "h2",
             renderer: DefaultBlockTag.self
         )
         .register(
@@ -39,6 +40,11 @@ public struct HTMLConfiguration: Sendable {
             tag: "u",
             renderer: UnderlineTag.self
         )
+        .register(
+            tag: "rb", "rt", "rp", "rtc", "rbc",
+            renderer: DefaultInlineTag.self
+        )
+        .register(tag: "ruby", renderer: RubyTag.self)
         .register(tag: "img", renderer: ImageTag.self)
     }
 }
@@ -49,16 +55,59 @@ extension HTMLConfiguration {
         copy.attributeStyle = style
         return copy
     }
+
+    public func collapsingBlockMargins(_ enabled: Bool) -> Self {
+        var copy = self
+        copy.collapseBlockMargins = enabled
+        return copy
+    }
+}
+
+extension HTMLConfiguration {
+    @inline(__always)
+    func cacheKey() -> Int {
+        var hasher = Hasher()
+        hasher.combine(ObjectIdentifier(type(of: attributeStyle)))
+
+        if !dictionaryType.isEmpty {
+            for key in dictionaryType.keys.sorted() {
+                hasher.combine(key)
+                if let type = dictionaryType[key] {
+                    switch type {
+                    case .block: hasher.combine(1)
+                    case .inline: hasher.combine(2)
+                    case .attachment: hasher.combine(3)
+                    }
+                } else {
+                    hasher.combine(0)
+                }
+            }
+        }
+
+        if !dictionary.isEmpty {
+            for key in dictionary.keys.sorted() {
+                hasher.combine(key)
+                if let renderer = dictionary[key] {
+                    hasher.combine(ObjectIdentifier(renderer))
+                } else {
+                    hasher.combine(0)
+                }
+            }
+        }
+        return hasher.finalize()
+    }
 }
 
 
 // MARK: - Internal Helper
 @MainActor
 extension HTMLConfiguration {
+    @inline(__always)
     func tagType(of tag: String) -> TagType? {
         dictionaryType[tag]
     }
 
+    @inline(__always)
     func applyStyles(tag: String, attributes: [String: AttributeValue], to styleContainer: inout HTMLStyleContainer) {
         attributeStyle.applyStyles(attributes: attributes, to: &styleContainer)
         dictionary[tag]?.applyStyles(with: attributes, to: &styleContainer)
@@ -68,6 +117,8 @@ extension HTMLConfiguration {
     func createBlock(element: BlockElement) -> some View {
         if let view = dictionary[element.tag] as? any BlockTag.Type  {
             AnyView(view.init(element: element))
+        } else {
+            AnyView(HTMLBlock(element: element))
         }
     }
 
diff --git a/Sources/SwiftUIHTML/Core/Node/HTMLChild.swift b/Sources/SwiftUIHTML/Core/Node/HTMLChild.swift
index 4233b34..3ae644f 100644
--- a/Sources/SwiftUIHTML/Core/Node/HTMLChild.swift
+++ b/Sources/SwiftUIHTML/Core/Node/HTMLChild.swift
@@ -13,15 +13,19 @@ public extension HTMLChild {
     }
 
     static func trimmingText(_ string: String) -> HTMLChild {
-        .text(string.trimmingCharacters(in: .trimmableSpaces))
-    }
-}
-
-// MARK - private
-private extension CharacterSet {
-    static var trimmableSpaces: CharacterSet {
-        CharacterSet
-            .whitespacesAndNewlines
-            .subtracting(CharacterSet(charactersIn: "\u{00A0}"))
+        if string.isEmpty {
+            return .text(string)
+        }
+        let utf8 = string.utf8
+        if let first = utf8.first, let last = utf8.last,
+           !ASCIIWhitespace.isWhitespace(first),
+           !ASCIIWhitespace.isWhitespace(last) {
+            return .text(string)
+        }
+        let trimmed = ASCIIWhitespace.trim(string)
+        if trimmed.startIndex == string.startIndex && trimmed.endIndex == string.endIndex {
+            return .text(string)
+        }
+        return .text(String(trimmed))
     }
 }
diff --git a/Sources/SwiftUIHTML/Core/Node/HTMLNode.swift b/Sources/SwiftUIHTML/Core/Node/HTMLNode.swift
index e2afbbd..a24a195 100644
--- a/Sources/SwiftUIHTML/Core/Node/HTMLNode.swift
+++ b/Sources/SwiftUIHTML/Core/Node/HTMLNode.swift
@@ -1,5 +1,10 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import Foundation
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
 
 
 public struct HTMLNode: Equatable, Sendable {
@@ -12,6 +17,20 @@ public struct HTMLNode: Equatable, Sendable {
         self.attributes = attributes.mapValues { AttributeValue(rawValue: $0) }
         self.children = children
     }
+
+    init(tag: String, attributes: [String: AttributeValue], children: [HTMLChild]) {
+        self.tag = tag
+        self.attributes = attributes
+        self.children = children
+    }
+
+    public var tagName: String {
+        tag
+    }
+
+    public var childrenCount: Int {
+        children.count
+    }
 }
 
 
@@ -21,17 +40,22 @@ extension HTMLNode {
         configuration: HTMLConfiguration,
         with styleContainer: HTMLStyleContainer
     ) -> BlockElement {
-        let contents = children.flatMap { child -> [TagElement] in
-            child.toElement(
+        var rootStyle = styleContainer
+        configuration.applyStyles(tag: tag, attributes: attributes, to: &rootStyle)
+        var contents: [TagElement] = []
+        contents.reserveCapacity(children.count)
+        for child in children {
+            child.appendElements(
+                into: &contents,
                 configuration: configuration,
-                with: styleContainer
+                with: rootStyle
             )
         }
         return BlockElement(
             tag: tag,
             attributes: attributes,
             contents: contents,
-            styleContainer: styleContainer
+            styleContainer: rootStyle
         )
     }
 
@@ -40,28 +64,33 @@ extension HTMLNode {
 
 
 fileprivate extension HTMLChild {
+    private static let emptyAttributes: [String: AttributeValue] = [:]
+
     @MainActor
-    func toElement(configuration: HTMLConfiguration, with styleContainer: HTMLStyleContainer) -> [TagElement] {
+    @inline(__always)
+    func appendElements(into contents: inout [TagElement], configuration: HTMLConfiguration, with styleContainer: HTMLStyleContainer) {
         switch self {
         case let .text(text) where text.isEmpty:
-            return []
+            return
 
         case let .text(text):
-            return [
+            contents.append(
                 .inline(InlineElement(
                     tag: "_text",
-                    attributes: [:],
+                    attributes: Self.emptyAttributes,
                     text: text,
                     styleContainer: styleContainer
                 ))
-            ]
+            )
+            return
 
         case let .node(childNode):
-            return childNode
-                .makeElement(
-                    configuration: configuration,
-                    with: styleContainer
-                )
+            childNode.appendElements(
+                into: &contents,
+                configuration: configuration,
+                with: styleContainer
+            )
+            return
         }
     }
 }
@@ -69,37 +98,349 @@ fileprivate extension HTMLChild {
 
 fileprivate extension HTMLNode {
     @MainActor
-    func makeElement(configuration: HTMLConfiguration, with styleContainer: HTMLStyleContainer) -> [TagElement] {
+    @inline(__always)
+    func appendElements(into contents: inout [TagElement], configuration: HTMLConfiguration, with styleContainer: HTMLStyleContainer) {
+        if tag == "rp" {
+            return
+        }
         var _styleContainer = styleContainer
+        if (ProcessInfo.processInfo.environment["SWIFTUIHTML_FONT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_FONT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil),
+           tag == "body",
+           let rawStyle = attributes["style"]?.string {
+            AttachmentDebugLogger.record("[Style] body style=\(rawStyle)")
+        }
         configuration.applyStyles(tag: tag, attributes: attributes, to: &_styleContainer)
 
+        if tag == "ruby",
+           let rubyData = rubyAttachmentData(from: children, styleContainer: _styleContainer) {
+            contents.append(
+                .inline(InlineElement(
+                    tag: tag,
+                    attributes: rubyData,
+                    type: .attachment,
+                    styleContainer: _styleContainer
+                ))
+            )
+            return
+        }
+
         switch configuration.tagType(of: tag) {
         case .inline:
-            return children
-                .flatMap { child -> [TagElement] in
-                    child.toElement(
-                        configuration: configuration,
-                        with: _styleContainer
-                    )
-                }
+            for child in children {
+                child.appendElements(
+                    into: &contents,
+                    configuration: configuration,
+                    with: _styleContainer
+                )
+            }
+            return
 
         case .attachment:
-            return [
+            contents.append(
                 .inline(InlineElement(
                     tag: tag,
                     attributes: attributes,
                     type: .attachment,
                     styleContainer: _styleContainer
                 ))
-            ]
+            )
+            return
 
         case .block, .none:
-            return [
+            contents.append(
                 .block(toElement(
                     configuration: configuration,
                     with: _styleContainer
                 ))
-            ]
+            )
+            return
+        }
+    }
+}
+
+private extension HTMLNode {
+    func rubyAttachmentData(from children: [HTMLChild], styleContainer: HTMLStyleContainer) -> [String: AttributeValue]? {
+        let rubyPieces = rubyComponents(from: children)
+        guard let baseText = rubyPieces.base, !baseText.isEmpty else { return nil }
+
+        var result = attributes
+        result["ruby-base"] = AttributeValue(rawValue: baseText)
+        if let rubyText = rubyPieces.ruby, !rubyText.isEmpty {
+            result["ruby-text"] = AttributeValue(rawValue: rubyText)
+        }
+        if result["ruby-position"] == nil,
+           let annotationPosition = rubyAnnotationPosition(from: children) {
+            result["ruby-position"] = AttributeValue(rawValue: annotationPosition)
+        }
+
+        if let font = styleContainer.uiFont {
+            result["ruby-font-name"] = AttributeValue(rawValue: font.fontName)
+            result["ruby-font-size"] = AttributeValue(rawValue: "\(font.pointSize)")
+#if os(macOS)
+            let traits = font.fontDescriptor.object(forKey: .traits) as? [NSFontDescriptor.TraitKey: Any]
+            if let weight = traits?[.weight] as? NSNumber {
+                result["ruby-font-weight"] = AttributeValue(rawValue: "\(weight.doubleValue)")
+            }
+            let symbolic = font.fontDescriptor.symbolicTraits
+            if symbolic.contains(.italic) {
+                result["ruby-font-italic"] = AttributeValue(rawValue: "1")
+            }
+#else
+            let traits = font.fontDescriptor.object(forKey: .traits) as? [UIFontDescriptor.TraitKey: Any]
+            if let weight = traits?[.weight] as? NSNumber {
+                result["ruby-font-weight"] = AttributeValue(rawValue: "\(weight.doubleValue)")
+            }
+            let symbolic = font.fontDescriptor.symbolicTraits
+            if symbolic.contains(.traitItalic) {
+                result["ruby-font-italic"] = AttributeValue(rawValue: "1")
+            }
+#endif
+        }
+
+        if let annotationStyle = rubyAnnotationStyle(from: children, baseFont: styleContainer.uiFont) {
+            if let size = annotationStyle.size {
+                result["ruby-annotation-font-size"] = AttributeValue(rawValue: "\(size)")
+            }
+            if let name = annotationStyle.name {
+                result["ruby-annotation-font-name"] = AttributeValue(rawValue: name)
+            }
+            if let color = annotationStyle.color {
+                result["ruby-annotation-color"] = AttributeValue(rawValue: color)
+            }
+        }
+
+        return result
+    }
+
+    func rubyAnnotationPosition(from children: [HTMLChild]) -> String? {
+        var position: String?
+        func scanPosition(in node: HTMLNode) {
+            if node.tag == "rt" || node.tag == "rtc" {
+                if let raw = node.attributes["ruby-position"]?.string {
+                    position = raw
+                    return
+                }
+                if let cssStyle = node.attributes["style"]?.cssStyle,
+                   let raw = cssStyle["ruby-position"]?.string {
+                    position = raw
+                    return
+                }
+            }
+            for child in node.children {
+                if case let .node(childNode) = child {
+                    scanPosition(in: childNode)
+                    if position != nil {
+                        return
+                    }
+                }
+            }
+        }
+
+        for child in children {
+            guard case let .node(node) = child else { continue }
+            scanPosition(in: node)
+            if position != nil {
+                break
+            }
+        }
+        return position
+    }
+
+    func rubyAnnotationStyle(from children: [HTMLChild], baseFont: PlatformFont?) -> (size: CGFloat?, name: String?, color: String?)? {
+        var size: CGFloat?
+        var name: String?
+        var color: String?
+        func scanRTStyles(in node: HTMLNode) {
+            guard node.tag == "rt" else {
+                for child in node.children {
+                    if case let .node(childNode) = child {
+                        scanRTStyles(in: childNode)
+                    }
+                }
+                return
+            }
+            guard let cssStyle = node.attributes["style"]?.cssStyle else { return }
+            if size == nil, let fontSize = cssStyle["font-size"]?.string {
+                let baseSize = baseFont?.pointSize ?? PlatformFont.systemFontSize
+                size = CSSFontUtility.parseSize(fromFontSize: fontSize, baseSize: baseSize)
+            }
+            if name == nil {
+                let hasExplicitFamily = cssStyle["font-family"]?.string != nil || cssStyle["font"]?.string != nil
+                if hasExplicitFamily, let font = CSSFontUtility.createFont(fromCSSStyle: cssStyle, currentFont: baseFont) {
+                    name = font.fontName
+                }
+            }
+            if color == nil, let raw = cssStyle["color"]?.string {
+                color = raw
+            }
+        }
+
+        for child in children {
+            guard case let .node(node) = child else { continue }
+            scanRTStyles(in: node)
+            if size != nil && name != nil {
+                break
+            }
+        }
+        if size == nil && name == nil && color == nil {
+            return nil
+        }
+        return (size, name, color)
+    }
+
+    func rubyComponents(from children: [HTMLChild]) -> (base: String?, ruby: String?) {
+        var baseText = ""
+        var rbText = ""
+        var rubyText = ""
+        var hasBase = false
+        var hasRuby = false
+        var hasRB = false
+
+        func appendRubyText(_ text: String) {
+            let trimmed = ASCIIWhitespace.trim(text)
+            if trimmed.isEmpty { return }
+            let normalized = normalizedRubyWhitespace(trimmed)
+            if hasRuby {
+                rubyText.append("\u{00A0}")
+            }
+            rubyText.append(contentsOf: normalized)
+            hasRuby = true
+        }
+
+        func scanRubyText(in node: HTMLNode) {
+            if node.tag == "rp" {
+                return
+            }
+            if node.tag == "rtc" {
+                var buffer = ""
+                var hasRTChild = false
+                for child in node.children {
+                    switch child {
+                    case let .text(text):
+                        buffer.append(text)
+                    case let .node(childNode):
+                        if childNode.tag == "rt" {
+                            hasRTChild = true
+                        }
+                        scanRubyText(in: childNode)
+                    }
+                }
+                if !hasRTChild, !buffer.isEmpty {
+                    appendRubyText(buffer)
+                }
+                return
+            }
+            if node.tag == "rt" {
+                var rubyBuffer = ""
+                rubyBuffer.reserveCapacity(16)
+                node.appendPlainText(into: &rubyBuffer)
+                appendRubyText(rubyBuffer)
+                return
+            }
+            for child in node.children {
+                if case let .node(childNode) = child {
+                    scanRubyText(in: childNode)
+                }
+            }
+        }
+
+        func scanBaseText(in node: HTMLNode) {
+            switch node.tag {
+            case "rb":
+                var buffer = ""
+                node.appendPlainText(into: &buffer)
+                if !buffer.isEmpty {
+                    rbText.append(contentsOf: normalizedRubyBaseWhitespace(buffer))
+                    hasBase = true
+                    hasRB = true
+                }
+            case "rbc":
+                for child in node.children {
+                    switch child {
+                    case let .text(text):
+                        if !text.isEmpty {
+                            baseText.append(contentsOf: normalizedRubyBaseWhitespace(text))
+                            hasBase = true
+                        }
+                    case let .node(childNode):
+                        scanBaseText(in: childNode)
+                    }
+                }
+            default:
+                var buffer = ""
+                node.appendPlainText(into: &buffer)
+                if !buffer.isEmpty {
+                    baseText.append(contentsOf: normalizedRubyBaseWhitespace(buffer))
+                    hasBase = true
+                }
+            }
+        }
+
+        for child in children {
+            switch child {
+            case let .text(text):
+                if !text.isEmpty {
+                    baseText.append(text)
+                    hasBase = true
+                }
+
+            case let .node(node):
+                switch node.tag {
+                case "rt":
+                    scanRubyText(in: node)
+                case "rtc":
+                    scanRubyText(in: node)
+                    continue
+                case "rp":
+                    continue
+                case "rb", "rbc":
+                    scanBaseText(in: node)
+                default:
+                    scanBaseText(in: node)
+                }
+            }
+        }
+
+        let resolvedBase = hasRB ? rbText : baseText
+        return (base: hasBase ? resolvedBase : nil, ruby: hasRuby ? rubyText : nil)
+    }
+
+    private func normalizedRubyWhitespace(_ text: Substring) -> String {
+        var output = String()
+        output.reserveCapacity(text.count)
+        for scalar in text.unicodeScalars {
+            switch scalar.value {
+            case 0x09, 0x0A, 0x0D, 0x20:
+                output.unicodeScalars.append(UnicodeScalar(0x00A0)!)
+            default:
+                output.unicodeScalars.append(scalar)
+            }
+        }
+        return output
+    }
+
+    private func normalizedRubyBaseWhitespace(_ text: String) -> String {
+        normalizedRubyWhitespace(text[...])
+    }
+
+    func plainText() -> String {
+        var result = ""
+        appendPlainText(into: &result)
+        return result
+    }
+
+    @inline(__always)
+    func appendPlainText(into result: inout String) {
+        for child in children {
+            switch child {
+            case let .text(text):
+                result.append(text)
+            case let .node(node):
+                node.appendPlainText(into: &result)
+            }
         }
     }
 }
diff --git a/Sources/SwiftUIHTML/Core/Platform/Color+Platform.swift b/Sources/SwiftUIHTML/Core/Platform/Color+Platform.swift
new file mode 100644
index 0000000..cac6c00
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Platform/Color+Platform.swift
@@ -0,0 +1,34 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import SwiftUI
+
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+
+public extension Color {
+    static var platformSystemGray4: Color {
+#if os(macOS)
+        return Color(nsColor: NSColor.systemGray.withAlphaComponent(0.35))
+#else
+        return Color(.systemGray4)
+#endif
+    }
+
+    static var platformSystemGray5: Color {
+#if os(macOS)
+        return Color(nsColor: NSColor.systemGray.withAlphaComponent(0.25))
+#else
+        return Color(.systemGray5)
+#endif
+    }
+
+    static var platformSystemGray6: Color {
+#if os(macOS)
+        return Color(nsColor: NSColor.systemGray.withAlphaComponent(0.18))
+#else
+        return Color(.systemGray6)
+#endif
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Platform/PlatformTypes.swift b/Sources/SwiftUIHTML/Core/Platform/PlatformTypes.swift
new file mode 100644
index 0000000..31fc15c
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Platform/PlatformTypes.swift
@@ -0,0 +1,91 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import CoreText
+import Foundation
+
+#if os(macOS)
+import AppKit
+internal typealias PlatformFont = NSFont
+internal typealias PlatformColor = NSColor
+internal typealias PlatformImage = NSImage
+internal typealias PlatformView = NSView
+internal typealias PlatformFontDescriptor = NSFontDescriptor
+#else
+import UIKit
+internal typealias PlatformFont = UIFont
+internal typealias PlatformColor = UIColor
+internal typealias PlatformImage = UIImage
+internal typealias PlatformView = UIView
+internal typealias PlatformFontDescriptor = UIFontDescriptor
+#endif
+
+internal extension PlatformFont {
+    var manabiCTFont: CTFont {
+        if fontName.hasPrefix(".SF") || fontName.contains("SFUI") || fontName.contains("SFNS") {
+            AttachmentDebugLogger.recordOnce(
+                "font:\(fontName):\(pointSize)",
+                message: "[Font] system font name=\(fontName) size=\(pointSize)"
+            )
+            return CTFontCreateUIFontForLanguage(.system, pointSize, nil)
+                ?? CTFontCreateWithName(fontName as CFString, pointSize, nil)
+        }
+        return CTFontCreateWithName(fontName as CFString, pointSize, nil)
+    }
+
+    var manabiLineHeight: CGFloat {
+        let ctFont = manabiCTFont
+        return CTFontGetAscent(ctFont) + CTFontGetDescent(ctFont) + CTFontGetLeading(ctFont)
+    }
+
+    var manabiFontHeight: CGFloat {
+        let ctFont = manabiCTFont
+        return CTFontGetAscent(ctFont) + CTFontGetDescent(ctFont)
+    }
+
+    var manabiBoundingBoxMaxY: CGFloat {
+        CTFontGetBoundingBox(manabiCTFont).maxY
+    }
+
+#if os(macOS)
+    func withItalicTrait() -> PlatformFont? {
+        let traits = fontDescriptor.symbolicTraits.union(.italic)
+        guard let descriptor = fontDescriptor.withSymbolicTraits(traits) else { return nil }
+        return PlatformFont(descriptor: descriptor, size: pointSize)
+    }
+#else
+    func withItalicTrait() -> PlatformFont? {
+        let traits = fontDescriptor.symbolicTraits.union(.traitItalic)
+        guard let descriptor = fontDescriptor.withSymbolicTraits(traits) else { return nil }
+        return PlatformFont(descriptor: descriptor, size: pointSize)
+    }
+#endif
+}
+
+internal extension PlatformImage {
+    static func manabiEmpty(size: CGSize) -> PlatformImage {
+#if os(macOS)
+        if size == .zero {
+            return PlatformImage(size: .zero)
+        }
+        let image = PlatformImage(size: size)
+        image.lockFocus()
+        PlatformColor.clear.setFill()
+        NSRect(origin: .zero, size: size).fill()
+        image.unlockFocus()
+        return image
+#else
+        if size == .zero {
+            return PlatformImage()
+        }
+        UIGraphicsBeginImageContextWithOptions(size, false, 1)
+        guard let context = UIGraphicsGetCurrentContext() else {
+            UIGraphicsEndImageContext()
+            return PlatformImage()
+        }
+        context.setFillColor(UIColor.clear.cgColor)
+        context.fill(CGRect(origin: .zero, size: size))
+        let image = UIGraphicsGetImageFromCurrentImageContext() ?? PlatformImage()
+        UIGraphicsEndImageContext()
+        return image
+#endif
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Platform/View+NavigationTitleDisplayMode.swift b/Sources/SwiftUIHTML/Core/Platform/View+NavigationTitleDisplayMode.swift
new file mode 100644
index 0000000..e1d9d2e
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Platform/View+NavigationTitleDisplayMode.swift
@@ -0,0 +1,13 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import SwiftUI
+
+public extension View {
+    @ViewBuilder
+    func applyInlineNavigationTitleDisplayMode() -> some View {
+#if os(iOS)
+        navigationBarTitleDisplayMode(.inline)
+#else
+        self
+#endif
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+TextLine.swift b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+TextLine.swift
index 6b27798..ea43c11 100644
--- a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+TextLine.swift
+++ b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+TextLine.swift
@@ -1,5 +1,10 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import SwiftUI
+#if os(macOS)
+import AppKit
+#elseif os(iOS)
+import UIKit
+#endif
 
 
 extension HTMLStyleContainer {
@@ -10,9 +15,15 @@ extension HTMLStyleContainer {
 }
 
 public extension HTMLStyleContainer.TextLineAttribute {
+#if os(macOS)
+    static func lineHeight(font: NSFont, lineHeight: CGFloat) -> Self {
+        .lineHeight(fontLineHeight: font.manabiLineHeight, lineHeight: lineHeight)
+    }
+#else
     static func lineHeight(font: UIFont, lineHeight: CGFloat) -> Self {
-        .lineHeight(fontLineHeight: font.lineHeight, lineHeight: lineHeight)
+        .lineHeight(fontLineHeight: font.manabiLineHeight, lineHeight: lineHeight)
     }
+#endif
 }
 
 extension HTMLStyleContainer.TextLineAttribute {
diff --git a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+Values.swift b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+Values.swift
index 059adea..2abf897 100644
--- a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+Values.swift
+++ b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer+Values.swift
@@ -1,5 +1,10 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import SwiftUI
+#if os(macOS)
+import AppKit
+#elseif os(iOS)
+import UIKit
+#endif
 
 
 public extension HTMLStyleContainer {
@@ -23,6 +28,15 @@ public extension HTMLStyleContainer {
         set { container.inlinePresentationIntent = newValue }
     }
     
+#if os(macOS)
+    var uiFont: AttributeScopes.AppKitAttributes.FontAttribute.Value? {
+        get { container.appKit.font }
+        set {
+            container.swiftUI.font = nil
+            container.appKit.font = newValue
+        }
+    }
+#else
     var uiFont: AttributeScopes.UIKitAttributes.FontAttribute.Value? {
         get { container.uiKit.font }
         set {
@@ -30,34 +44,61 @@ public extension HTMLStyleContainer {
             container.uiKit.font = newValue
         }
     }
+#endif
     
     var font: AttributeScopes.SwiftUIAttributes.FontAttribute.Value? {
         get { container.swiftUI.font }
         set {
+#if os(macOS)
+            container.appKit.font = nil
+#else
             container.uiKit.font = nil
+#endif
             container.swiftUI.font = newValue
         }
     }
     
+#if os(macOS)
+    var underlineStyle: AttributeScopes.AppKitAttributes.UnderlineStyleAttribute.Value? {
+        get { container.underlineStyle }
+        set { container.underlineStyle = newValue }
+    }
+
+    var underlineColor: AttributeScopes.AppKitAttributes.UnderlineColorAttribute.Value? {
+        get { container.underlineColor }
+        set { container.underlineColor = newValue}
+    }
+
+    var kern: AttributeScopes.AppKitAttributes.KernAttribute.Value? {
+        get { container.kern }
+        set { container.kern = newValue }
+    }
+
+    var tracking: AttributeScopes.AppKitAttributes.TrackingAttribute.Value? {
+        get { container.tracking }
+        set { container.tracking = newValue }
+    }
+#else
     var underlineStyle: AttributeScopes.UIKitAttributes.UnderlineStyleAttribute.Value? {
         get { container.underlineStyle }
         set { container.underlineStyle = newValue }
     }
-    
+
     var underlineColor: AttributeScopes.UIKitAttributes.UnderlineColorAttribute.Value? {
         get { container.underlineColor }
         set { container.underlineColor = newValue}
     }
-    
+
     var kern: AttributeScopes.UIKitAttributes.KernAttribute.Value? {
         get { container.kern }
         set { container.kern = newValue }
     }
-    
+
     var tracking: AttributeScopes.UIKitAttributes.TrackingAttribute.Value? {
         get { container.tracking }
         set { container.tracking = newValue }
     }
+#endif
     
     func merging(_ other: HTMLStyleContainer, mergePolicy: AttributedString.AttributeMergePolicy = .keepNew) -> HTMLStyleContainer {
         var copy = self
@@ -66,4 +107,3 @@ public extension HTMLStyleContainer {
         return copy
     }
 }
-
diff --git a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer.swift b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer.swift
index 3c01192..501d3b8 100644
--- a/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer.swift
+++ b/Sources/SwiftUIHTML/Core/StyleContainer/HTMLStyleContainer.swift
@@ -4,12 +4,13 @@ import SwiftUI
 
 public struct HTMLStyleContainer: Equatable, Sendable, Hashable {
     public func hash(into hasher: inout Hasher) {
-        if #available(iOS 16, *) {
+        if #available(iOS 16, macOS 13, *) {
             hasher.combine(container)
         } else {
             hasher.combine(HashableAttributeContainer(container))
         }
         hasher.combine(textLine)
+        hasher.combine(lineBreakMode)
     }
 
     var container = AttributeContainer()
diff --git a/Sources/SwiftUIHTML/Core/Util/ASCIIWhitespace.swift b/Sources/SwiftUIHTML/Core/Util/ASCIIWhitespace.swift
new file mode 100644
index 0000000..586e5e9
--- /dev/null
+++ b/Sources/SwiftUIHTML/Core/Util/ASCIIWhitespace.swift
@@ -0,0 +1,86 @@
+//  Copyright © 2026 PRND. All rights reserved.
+import Foundation
+
+public enum ASCIIWhitespace {
+    @inline(__always)
+    public static func isWhitespace(_ byte: UInt8) -> Bool {
+        switch byte {
+        case 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20:
+            return true
+        default:
+            return false
+        }
+    }
+
+    @inline(__always)
+    public static func trim(_ value: String) -> Substring {
+        trim(value[...])
+    }
+
+    @inline(__always)
+    public static func trim(_ value: Substring) -> Substring {
+        let utf8 = value.utf8
+        var start = utf8.startIndex
+        var end = utf8.endIndex
+
+        while start < end, ASCIIWhitespace.isWhitespace(utf8[start]) {
+            start = utf8.index(after: start)
+        }
+
+        while end > start {
+            let before = utf8.index(before: end)
+            if ASCIIWhitespace.isWhitespace(utf8[before]) {
+                end = before
+            } else {
+                break
+            }
+        }
+
+        let startIndex = String.Index(start, within: value) ?? value.startIndex
+        let endIndex = String.Index(end, within: value) ?? value.endIndex
+        return value[startIndex..<endIndex]
+    }
+
+    @inline(__always)
+    public static func trimLeading(_ value: String) -> Substring {
+        trimLeading(value[...])
+    }
+
+    @inline(__always)
+    public static func trimLeading(_ value: Substring) -> Substring {
+        let utf8 = value.utf8
+        var start = utf8.startIndex
+        let end = utf8.endIndex
+
+        while start < end, ASCIIWhitespace.isWhitespace(utf8[start]) {
+            start = utf8.index(after: start)
+        }
+
+        let startIndex = String.Index(start, within: value) ?? value.startIndex
+        return value[startIndex..<value.endIndex]
+    }
+
+    @inline(__always)
+    public static func trimTrailing(_ value: String) -> Substring {
+        trimTrailing(value[...])
+    }
+
+    @inline(__always)
+    public static func trimTrailing(_ value: Substring) -> Substring {
+        let utf8 = value.utf8
+        var end = utf8.endIndex
+        let start = utf8.startIndex
+
+        while end > start {
+            let before = utf8.index(before: end)
+            if ASCIIWhitespace.isWhitespace(utf8[before]) {
+                end = before
+            } else {
+                break
+            }
+        }
+
+        let endIndex = String.Index(end, within: value) ?? value.endIndex
+        return value[value.startIndex..<endIndex]
+    }
+}
diff --git a/Sources/SwiftUIHTML/Core/Util/CSSFontUtility.swift b/Sources/SwiftUIHTML/Core/Util/CSSFontUtility.swift
index f64387b..f8ec17f 100644
--- a/Sources/SwiftUIHTML/Core/Util/CSSFontUtility.swift
+++ b/Sources/SwiftUIHTML/Core/Util/CSSFontUtility.swift
@@ -1,5 +1,13 @@
 //  Copyright © 2025 PRND. All rights reserved.
+import Foundation
+#if os(iOS)
 import UIKit
+#endif
+@_implementationOnly import CoreText
+import SwiftUI
+#if os(iOS)
+import UIKit
+#endif
 
 /// CSS 폰트 스타일 파싱 및 처리를 담당하는 유틸리티 클래스
 
@@ -11,9 +19,9 @@ public enum CSSFontUtility {
     ///   - fontFamilyString: CSS font-family 문자열 (예: "Arial, Helvetica, sans-serif")
     ///   - size: 적용할 폰트 크기
     /// - Returns: 생성된 폰트
-    static func createFont(fromFontFamily fontFamilyString: String?, size: CGFloat) -> UIFont {
+    static func createFont(fromFontFamily fontFamilyString: String?, size: CGFloat) -> PlatformFont {
         guard let fontFamilyString = fontFamilyString, !fontFamilyString.isEmpty else {
-            return UIFont.systemFont(ofSize: size)
+            return PlatformFont.systemFont(ofSize: size)
         }
 
         let fontNames = parseFontFamilyString(fontFamilyString)
@@ -25,40 +33,43 @@ public enum CSSFontUtility {
     ///   - fontSizeString: CSS font-size 문자열 (예: "12px", "1.5em", "large")
     ///   - baseSize: 상대 크기 계산을 위한 기준 크기
     /// - Returns: 파싱된 폰트 크기
-    static func parseSize(fromFontSize fontSizeString: String?, baseSize: CGFloat = UIFont.systemFontSize) -> CGFloat {
+    static func parseSize(fromFontSize fontSizeString: String?, baseSize: CGFloat = PlatformFont.systemFontSize) -> CGFloat {
         guard let fontSizeString = fontSizeString, !fontSizeString.isEmpty else {
             return baseSize
         }
 
-        let trimmed = fontSizeString.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmed = ASCIIWhitespace.trim(fontSizeString)
+        if trimmed.isEmpty {
+            return baseSize
+        }
+        let trimmedString = String(trimmed)
 
         // 다양한 단위 처리
-        if trimmed.hasSuffix("px") {
-            if let value = Double(trimmed.dropLast(2)) {
+        if trimmedString.hasSuffix("px") {
+            if let value = Double(trimmedString.dropLast(2)) {
                 return CGFloat(value)
             }
-        } else if trimmed.hasSuffix("pt") {
-            if let value = Double(trimmed.dropLast(2)) {
+        } else if trimmedString.hasSuffix("pt") {
+            if let value = Double(trimmedString.dropLast(2)) {
                 return CGFloat(value)
             }
-        } else if trimmed.hasSuffix("em") {
-            if let value = Double(trimmed.dropLast(2)) {
+        } else if trimmedString.hasSuffix("rem") {
+            if let value = Double(trimmedString.dropLast(3)) {
                 return baseSize * CGFloat(value)
             }
-        } else if trimmed.hasSuffix("rem") {
-            if let value = Double(trimmed.dropLast(3)) {
+        } else if trimmedString.hasSuffix("em") {
+            if let value = Double(trimmedString.dropLast(2)) {
                 return baseSize * CGFloat(value)
             }
-        } else if trimmed.hasSuffix("%") {
-            if let value = Double(trimmed.dropLast(1)) {
+        } else if trimmedString.hasSuffix("%") {
+            if let value = Double(trimmedString.dropLast(1)) {
                 return baseSize * CGFloat(value / 100)
             }
-        } else if let value = Double(trimmed) {
+        } else if let value = Double(trimmedString) {
             return CGFloat(value)
         }
 
-        // 키워드 기반 크기
-        switch trimmed.lowercased() {
+        switch trimmedString.lowercased() {
         case "xx-small": return baseSize * 0.6
         case "x-small": return baseSize * 0.75
         case "small": return baseSize * 0.889
@@ -78,12 +89,15 @@ public enum CSSFontUtility {
     ///   - cssStyle: CSS 스타일 딕셔너리
     ///   - currentFont: 현재 설정된 폰트 (기준 크기 및 업데이트용)
     /// - Returns: 생성된 폰트
-    static func createFont(fromCSSStyle cssStyle: CSSStyle, currentFont: UIFont? = nil) -> UIFont? {
-        let currentSize = currentFont?.pointSize ?? UIFont.systemFontSize
+    static func createFont(fromCSSStyle cssStyle: CSSStyle, currentFont: PlatformFont? = nil) -> PlatformFont? {
+        let currentSize = currentFont?.pointSize ?? PlatformFont.systemFontSize
 
         // font-size와 font-family 속성 추출
         let fontSizeValue = cssStyle["font-size"]?.string
         let fontFamilyValue = cssStyle["font-family"]?.string
+        if shouldLogFontResolution(), let fontFamilyValue {
+            AttachmentDebugLogger.record("[Font] css font-family=\(fontFamilyValue) current=\(currentFont?.fontName ?? "nil") size=\(currentSize)")
+        }
 
         // font 속성이 있다면 해당 속성 파싱 (예: "italic bold 16px/2 Arial, sans-serif")
         if let fontShorthand = cssStyle["font"]?.string {
@@ -98,7 +112,7 @@ public enum CSSFontUtility {
                 } else if let family = fontFamilyValue {
                     return createFont(fromFontFamily: family, size: parsedSize)
                 } else {
-                    return currentFont?.withSize(parsedSize) ?? UIFont.systemFont(ofSize: parsedSize)
+                    return currentFont?.withSize(parsedSize) ?? PlatformFont.systemFont(ofSize: parsedSize)
                 }
             }
         }
@@ -108,9 +122,13 @@ public enum CSSFontUtility {
 
         // font-family가 있으면 해당 폰트로, 없으면 현재 폰트의 사이즈만 변경
         if let fontFamily = fontFamilyValue {
-            return createFont(fromFontFamily: fontFamily, size: size)
+            let font = createFont(fromFontFamily: fontFamily, size: size)
+            if shouldLogFontResolution() {
+                AttachmentDebugLogger.record("[Font] resolved family=\(fontFamily) -> \(font.fontName) size=\(font.pointSize)")
+            }
+            return font
         } else if size != currentSize {
-            return currentFont?.withSize(size) ?? UIFont.systemFont(ofSize: size)
+            return currentFont?.withSize(size) ?? PlatformFont.systemFont(ofSize: size)
         }
 
         return currentFont
@@ -119,17 +137,20 @@ public enum CSSFontUtility {
     // MARK: - Private Helper Methods
 
     private static func parseFontFamilyString(_ fontFamilyString: String) -> [String] {
-        return fontFamilyString
-            .components(separatedBy: ",")
-            .map {
-                $0.trimmingCharacters(in: .whitespacesAndNewlines)
-                  .replacingOccurrences(of: "\"", with: "")
-                  .replacingOccurrences(of: "'", with: "")
-            }
-            .filter { !$0.isEmpty }
+        let parts = splitByComma(fontFamilyString)
+        var results: [String] = []
+        results.reserveCapacity(parts.count)
+
+        for part in parts {
+            let trimmed = trimASCIIAndQuotes(part)
+            guard !trimmed.isEmpty else { continue }
+            results.append(String(trimmed))
+        }
+
+        return results
     }
 
-    private static func createFontWithFallbacks(fontNames: [String], size: CGFloat) -> UIFont {
+    private static func createFontWithFallbacks(fontNames: [String], size: CGFloat) -> PlatformFont {
         // 특정 폰트 이름과 제네릭 패밀리 분리
         var specificFontNames: [String] = []
         var genericFamily: String? = nil
@@ -143,9 +164,9 @@ public enum CSSFontUtility {
         }
 
         // 첫 번째 유효한 폰트 찾기
-        var primaryFont: UIFont! = nil
+        var primaryFont: PlatformFont! = nil
         for name in specificFontNames {
-            if let font = UIFont(name: name, size: size) {
+            if let font = resolveFont(named: name, size: size) {
                 primaryFont = font
                 break
             }
@@ -156,19 +177,19 @@ public enum CSSFontUtility {
             if let genericFamily = genericFamily {
                 return createSystemFontForGenericFamily(genericFamily, size: size)
             }
-            return UIFont.systemFont(ofSize: size)
+            return PlatformFont.systemFont(ofSize: size)
         }
 
         // 기본 폰트의 descriptor 가져오기
         let primaryDescriptor = primaryFont!.fontDescriptor
 
         // Cascade 목록 생성
-        var cascadeList: [UIFontDescriptor] = []
+        var cascadeList: [PlatformFontDescriptor] = []
 
         // Fallback 폰트 추가 (첫 번째 이후의 특정 폰트들)
         if specificFontNames.count > 1 {
             for name in specificFontNames.dropFirst() {
-                if let font = UIFont(name: name, size: size) {
+                if let font = resolveFont(named: name, size: size) {
                     cascadeList.append(font.fontDescriptor)
                 }
             }
@@ -181,14 +202,18 @@ public enum CSSFontUtility {
         }
 
         // 최종 fallback으로 시스템 폰트 추가
-        cascadeList.append(UIFont.systemFont(ofSize: size).fontDescriptor)
+        cascadeList.append(PlatformFont.systemFont(ofSize: size).fontDescriptor)
 
         // cascade 목록이 비어있지 않으면 descriptor 업데이트
         if !cascadeList.isEmpty {
             let descriptorWithCascade = primaryDescriptor.addingAttributes([
-                UIFontDescriptor.AttributeName.cascadeList: cascadeList
+                PlatformFontDescriptor.AttributeName.cascadeList: cascadeList
             ])
-            return UIFont(descriptor: descriptorWithCascade, size: 0) // 0은 원래 크기 유지
+#if os(macOS)
+            return PlatformFont(descriptor: descriptorWithCascade, size: 0) ?? primaryFont // 0은 원래 크기 유지
+#else
+            return PlatformFont(descriptor: descriptorWithCascade, size: 0) // 0은 원래 크기 유지
+#endif
         }
 
         return primaryFont
@@ -199,26 +224,61 @@ public enum CSSFontUtility {
         return genericFamilies.contains(name.lowercased())
     }
 
-    private static func createSystemFontForGenericFamily(_ family: String, size: CGFloat) -> UIFont {
+    private static func resolveFont(named name: String, size: CGFloat) -> PlatformFont? {
+        if let font = PlatformFont(name: name, size: size) {
+            return font
+        }
+#if os(iOS)
+        let lower = name.lowercased()
+        if lower == "arial", let font = PlatformFont(name: "ArialMT", size: size) {
+            return font
+        }
+        if lower == "helvetica", let font = PlatformFont(name: "Helvetica", size: size) {
+            return font
+        }
+        if lower == "times new roman", let font = PlatformFont(name: "TimesNewRomanPSMT", size: size) {
+            return font
+        }
+#endif
+#if os(iOS)
+        let descriptor = PlatformFontDescriptor(fontAttributes: [.family: name])
+        let font = PlatformFont(descriptor: descriptor, size: size)
+        if shouldLogFontResolution() {
+            AttachmentDebugLogger.record("[Font] resolve family=\(name) -> \(font.fontName) family=\(font.familyName)")
+        }
+        if font.familyName.caseInsensitiveCompare(name) == .orderedSame {
+            return font
+        }
+#endif
+        return nil
+    }
+
+    static func shouldLogFontResolution() -> Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_FONT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_FONT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+    }
+
+    private static func createSystemFontForGenericFamily(_ family: String, size: CGFloat) -> PlatformFont {
         switch family.lowercased() {
         case "serif":
-            return UIFont(name: "TimesNewRomanPSMT", size: size) ?? UIFont.systemFont(ofSize: size)
+            return PlatformFont(name: "TimesNewRomanPSMT", size: size) ?? PlatformFont.systemFont(ofSize: size)
         case "sans-serif":
-            return UIFont.systemFont(ofSize: size)
+            return PlatformFont.systemFont(ofSize: size)
         case "monospace":
-            if #available(iOS 13.0, *) {
-                return UIFont.monospacedSystemFont(ofSize: size, weight: .regular)
-            } else {
-                return UIFont(name: "Menlo-Regular", size: size) ?? UIFont.systemFont(ofSize: size)
+            if #available(iOS 13.0, macOS 10.15, *) {
+                return PlatformFont.monospacedSystemFont(ofSize: size, weight: .regular)
             }
+            return PlatformFont(name: "Menlo-Regular", size: size) ?? PlatformFont.systemFont(ofSize: size)
         case "cursive":
-            return UIFont(name: "SnellRoundhand", size: size) ?? UIFont.systemFont(ofSize: size)
+            return PlatformFont(name: "SnellRoundhand", size: size) ?? PlatformFont.systemFont(ofSize: size)
         case "fantasy":
-            return UIFont(name: "Papyrus", size: size) ?? UIFont.systemFont(ofSize: size)
+            return PlatformFont(name: "Papyrus", size: size) ?? PlatformFont.systemFont(ofSize: size)
         case "system-ui":
-            return UIFont.systemFont(ofSize: size)
+            return PlatformFont.systemFont(ofSize: size)
         default:
-            return UIFont.systemFont(ofSize: size)
+            return PlatformFont.systemFont(ofSize: size)
         }
     }
 
@@ -226,12 +286,12 @@ public enum CSSFontUtility {
         // font: [font-style] [font-variant] [font-weight] [font-size/line-height] [font-family]
         // 예: "italic bold 16px/2 Arial, sans-serif"
 
-        let components = fontString.components(separatedBy: .whitespaces)
+        let components = splitByASCIIWhitespace(fontString)
 
         // 마지막 요소가 폰트 패밀리 (쉼표로 구분된 목록일 수 있음)
         var familyStartIndex = -1
         for (index, component) in components.enumerated().reversed() {
-            if component.contains(",") || isGenericFontFamily(component) {
+            if containsCommaASCII(component) || isGenericFontFamily(String(component)) {
                 familyStartIndex = index
                 break
             }
@@ -240,17 +300,19 @@ public enum CSSFontUtility {
         // 폰트 패밀리 조합
         var fontFamily: String? = nil
         if familyStartIndex >= 0 {
-            fontFamily = components[familyStartIndex...].joined(separator: " ")
+            fontFamily = components[familyStartIndex...].map(String.init).joined(separator: " ")
         }
 
         // 폰트 사이즈 찾기 (px, pt, em, rem, % 등으로 끝나는 요소)
         var fontSize: String? = nil
         for component in components {
-            if component.hasSuffix("px") || component.hasSuffix("pt") ||
-               component.hasSuffix("em") || component.hasSuffix("rem") ||
-               component.hasSuffix("%") ||
-               ["xx-small", "x-small", "small", "medium", "large", "x-large", "xx-large", "xxx-large", "smaller", "larger"].contains(component.lowercased()) {
-                fontSize = component.split(separator: "/").first.map(String.init) // line-height 제거
+            let componentString = String(component)
+            if componentString.hasSuffix("px") || componentString.hasSuffix("pt") ||
+               componentString.hasSuffix("em") || componentString.hasSuffix("rem") ||
+               componentString.hasSuffix("%") ||
+               ["xx-small", "x-small", "small", "medium", "large", "x-large", "xx-large", "xxx-large", "smaller", "larger"].contains(componentString.lowercased()) {
+                let sizeSlice = prefixBeforeSlash(component)
+                fontSize = String(sizeSlice) // line-height 제거
                 break
             }
         }
@@ -258,3 +320,112 @@ public enum CSSFontUtility {
         return (fontSize, fontFamily)
     }
 }
+
+private extension CSSFontUtility {
+    static func splitByComma(_ value: String) -> [Substring] {
+        let utf8 = value.utf8
+        var results: [Substring] = []
+        results.reserveCapacity(4)
+
+        var start = utf8.startIndex
+        var index = start
+        while index < utf8.endIndex {
+            if utf8[index] == 0x2C { // ","
+                let startIndex = String.Index(start, within: value) ?? value.startIndex
+                let endIndex = String.Index(index, within: value) ?? value.endIndex
+                results.append(value[startIndex..<endIndex])
+                start = utf8.index(after: index)
+            }
+            index = utf8.index(after: index)
+        }
+
+        if start <= utf8.endIndex {
+            let startIndex = String.Index(start, within: value) ?? value.startIndex
+            let endIndex = value.endIndex
+            results.append(value[startIndex..<endIndex])
+        }
+
+        return results
+    }
+
+    static func splitByASCIIWhitespace(_ value: String) -> [Substring] {
+        let utf8 = value.utf8
+        var results: [Substring] = []
+        results.reserveCapacity(8)
+
+        var start = utf8.startIndex
+        var index = start
+        var inToken = false
+
+        while index < utf8.endIndex {
+            let byte = utf8[index]
+            if ASCIIWhitespace.isWhitespace(byte) {
+                if inToken {
+                    let startIndex = String.Index(start, within: value) ?? value.startIndex
+                    let endIndex = String.Index(index, within: value) ?? value.endIndex
+                    results.append(value[startIndex..<endIndex])
+                    inToken = false
+                }
+                index = utf8.index(after: index)
+                start = index
+                continue
+            }
+            if !inToken {
+                start = index
+                inToken = true
+            }
+            index = utf8.index(after: index)
+        }
+
+        if inToken {
+            let startIndex = String.Index(start, within: value) ?? value.startIndex
+            results.append(value[startIndex..<value.endIndex])
+        }
+
+        return results
+    }
+
+    static func trimASCIIAndQuotes(_ value: Substring) -> Substring {
+        let trimmed = ASCIIWhitespace.trim(value)
+        let utf8 = trimmed.utf8
+        guard !utf8.isEmpty else { return trimmed }
+
+        var start = utf8.startIndex
+        var end = utf8.endIndex
+
+        let first = utf8[start]
+        if first == 0x22 || first == 0x27 { // " or '
+            start = utf8.index(after: start)
+        }
+
+        if end > start {
+            let before = utf8.index(before: end)
+            let last = utf8[before]
+            if last == 0x22 || last == 0x27 {
+                end = before
+            }
+        }
+
+        let startIndex = String.Index(start, within: trimmed) ?? trimmed.startIndex
+        let endIndex = String.Index(end, within: trimmed) ?? trimmed.endIndex
+        return trimmed[startIndex..<endIndex]
+    }
+
+    static func containsCommaASCII(_ value: Substring) -> Bool {
+        for byte in value.utf8 {
+            if byte == 0x2C {
+                return true
+            }
+        }
+        return false
+    }
+
+    static func prefixBeforeSlash(_ value: Substring) -> Substring {
+        let utf8 = value.utf8
+        if let slashIndex = utf8.firstIndex(of: 0x2F) { // "/"
+            let endIndex = String.Index(slashIndex, within: value) ?? value.endIndex
+            return value[value.startIndex..<endIndex]
+        }
+        return value
+    }
+}
diff --git a/Sources/SwiftUIHTML/HTMLMinifier.swift b/Sources/SwiftUIHTML/HTMLMinifier.swift
index d1e12ef..9f71c27 100644
--- a/Sources/SwiftUIHTML/HTMLMinifier.swift
+++ b/Sources/SwiftUIHTML/HTMLMinifier.swift
@@ -3,6 +3,11 @@ import Foundation
 
 /// Class that provides HTML document compression functionality
 public enum HTMLMinifier {
+    private static let whitespaceBetweenTagsRegex: NSRegularExpression? = try? NSRegularExpression(
+        pattern: ">([\\s]+)<",
+        options: []
+    )
+
     /// Removes unnecessary whitespace from HTML documents and optimizes them.
     /// - Parameter html: Original HTML string
     /// - Returns: Optimized HTML string
@@ -15,19 +20,24 @@ public enum HTMLMinifier {
         result = result.replacingOccurrences(of: ">\\s*[\\n\\r]\\s*<", with: "><", options: .regularExpression)
 
         // 3. Convert only pure whitespace between tags to &nbsp; (when no line breaks)
-        let pattern = ">([\\s]+)<"
-
-        while let range = result.range(of: pattern, options: .regularExpression) {
-            let spacesRange = result.index(after: range.lowerBound)..<result.index(before: range.upperBound)
-            let spaces = result[spacesRange]
-
-            // Replace with &nbsp; only when whitespace has no line breaks
-            let nbspString = String(repeating: "&nbsp;", count: spaces.count)
-            result.replaceSubrange(range, with: ">" + nbspString + "<")
+        if let regex = whitespaceBetweenTagsRegex {
+            let fullRange = NSRange(result.startIndex..<result.endIndex, in: result)
+            let matches = regex.matches(in: result, range: fullRange)
+            for match in matches.reversed() {
+                guard match.numberOfRanges > 1,
+                      let matchRange = Range(match.range(at: 0), in: result),
+                      let spacesRange = Range(match.range(at: 1), in: result) else {
+                    continue
+                }
+                let spacesCount = result[spacesRange].count
+                let nbspString = String(repeating: "&nbsp;", count: spacesCount)
+                result.replaceSubrange(matchRange, with: ">" + nbspString + "<")
+            }
         }
 
         // 4. Remove all remaining line breaks and tabs (excluding inside tags)
         result = result.replacingOccurrences(of: ">([^<]*?)[\\n\\r\\t]+([^<]*?)<", with: ">$1 $2<", options: .regularExpression)
+        result = result.replacingOccurrences(of: "\t", with: " ")
 
         return result
     }
diff --git a/Sources/SwiftUIHTML/Tag/Attachment/ImageTag.swift b/Sources/SwiftUIHTML/Tag/Attachment/ImageTag.swift
index 2107a93..23c39ba 100644
--- a/Sources/SwiftUIHTML/Tag/Attachment/ImageTag.swift
+++ b/Sources/SwiftUIHTML/Tag/Attachment/ImageTag.swift
@@ -1,5 +1,6 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import SwiftUI
+import NukeUI
 
 
 struct ImageTag: InlineAttachmentTag {
@@ -9,18 +10,54 @@ struct ImageTag: InlineAttachmentTag {
         self.attributes = attributes
     }
     var body: some View {
-        AsyncImage(url: attributes["src"]?.url) { phase in
-            switch phase {
-            case .success(let image):
-                ImageContainer(
-                    image: image,
-                    size: ElementSize(attributes: attributes)
-                )
-            default:
-                Color.clear
-                    .frame(width: 1, height: 1)
+        let size = ElementSize(attributes: attributes)
+        let url = attributes["src"]?.url
+        LazyImage(url: url, transaction: Transaction(animation: nil)) { state in
+            if let image = state.image {
+                ImageContainer(image: image, size: size)
+                    .onAppear {
+                        recordImageEvent("success", size: size)
+                    }
+            } else if state.error != nil {
+                ImagePlaceholder(size: size)
+                    .onAppear {
+                        recordImageEvent("failure", size: size)
+                    }
+            } else {
+                ImagePlaceholder(size: size)
+                    .onAppear {
+                        recordImageEvent("empty", size: size)
+                    }
             }
         }
+        .onStart { _ in
+            ImageLoadTracker.shared.begin(url: url)
+        }
+        .onCompletion { _ in
+            ImageLoadTracker.shared.end(url: url)
+        }
+        .modifier(SizeModifier(size: size))
+    }
+
+    private func recordImageEvent(_ state: String, size: ElementSize) {
+        let src = attributes["src"]?.string ?? "-"
+        let width = attributes["width"]?.string ?? "-"
+        let height = attributes["height"]?.string ?? "-"
+        AttachmentDebugLogger.recordOnce(
+            "ImageTag:\(state):\(src)",
+            message: "[ImageTag] \(state) src=\(src) width=\(width) height=\(height) resolvedWidth=\(String(describing: size.width)) resolvedHeight=\(String(describing: size.height))"
+        )
+    }
+}
+
+private struct ImagePlaceholder: View {
+    let size: ElementSize
+    var body: some View {
+        if size.width == nil && size.height == nil {
+            Color.clear.frame(width: 1, height: 1)
+        } else {
+            Color.clear.modifier(SizeModifier(size: size))
+        }
     }
 }
 
diff --git a/Sources/SwiftUIHTML/Tag/Inline/RubyTag.swift b/Sources/SwiftUIHTML/Tag/Inline/RubyTag.swift
new file mode 100644
index 0000000..727d027
--- /dev/null
+++ b/Sources/SwiftUIHTML/Tag/Inline/RubyTag.swift
@@ -0,0 +1,551 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import SwiftUI
+import CoreText
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+
+public struct RubyTag: InlineAttachmentTag {
+    public let attributes: [String: AttributeValue]
+    @HTMLEnvironment(\.styleContainer) private var styleContainer
+
+    public init(attributes: [String : AttributeValue]) {
+        self.attributes = attributes
+    }
+
+    public var body: some View {
+        RubyInlineLabel(
+            baseText: baseText,
+            rubyText: rubyText,
+            font: baseFont,
+            rubyFont: rubyFont,
+            rubyPosition: rubyPosition,
+            rubyScale: rubyScale,
+            foregroundColor: foregroundColor,
+            rubyAnnotationColor: rubyAnnotationColor,
+            hasExplicitRubyAnnotationFont: hasExplicitRubyAnnotationFont
+        )
+    }
+}
+
+private extension RubyTag {
+    var cssStyle: CSSStyle {
+        attributes["style"]?.cssStyle ?? .empty
+    }
+
+    var baseText: String {
+        attributes["ruby-base"]?.string ?? ""
+    }
+
+    var rubyText: String {
+        attributes["ruby-text"]?.string ?? ""
+    }
+
+    var rubyPosition: CTRubyPosition {
+        let raw = attributes["ruby-position"]?.string ?? cssStyle["ruby-position"]?.string
+        switch raw?.lowercased() {
+        case "over": return .before
+        case "under": return .after
+        case "inter-character": return .interCharacter
+        case "intercharacter": return .interCharacter
+        case "alternate": return .before
+        case "alternate over": return .before
+        case "alternate under": return .after
+        case "after": return .after
+        case "before": return .before
+        case "inline": return .inline
+        default: return .before
+        }
+    }
+
+    var rubyScale: CGFloat {
+        if let explicit = attributes["ruby-scale"]?.cgFloat {
+            return explicit
+        }
+        if attributes["ruby-annotation-font-size"] != nil || attributes["ruby-annotation-font-name"] != nil {
+            return 1.0
+        }
+        return 0.5
+    }
+
+    var foregroundColor: Color? {
+        if let color = cssStyle["color"]?.toColor() {
+            return color
+        }
+        if let color = attributes["ruby-color"]?.toColor() {
+            return color
+        }
+        return nil
+    }
+
+    var baseFont: PlatformFont? {
+        if let size = attributes["ruby-font-size"]?.cgFloat {
+            if let fontName = attributes["ruby-font-name"]?.string {
+                if fontName.hasPrefix(".") || fontName.contains("SFUI") || fontName.contains("SFNS") {
+                    let weight = rubyFontWeight()
+                    let italic = rubyFontItalic()
+                    let system = PlatformFont.systemFont(ofSize: size, weight: weight)
+                    if italic, let withItalic = system.withItalicTrait() {
+                        return withItalic
+                    }
+                    return system
+                }
+                if let font = PlatformFont(name: fontName, size: size) {
+                    return font
+                }
+            }
+            if let envFont = styleContainer.uiFont {
+                return envFont.withSize(size)
+            }
+            let weight = rubyFontWeight()
+            let italic = rubyFontItalic()
+            let system = PlatformFont.systemFont(ofSize: size, weight: weight)
+            if italic, let withItalic = system.withItalicTrait() {
+                return withItalic
+            }
+            return system
+        }
+
+        let hasCSSFont = cssStyle["font"] != nil
+            || cssStyle["font-size"] != nil
+            || cssStyle["font-family"] != nil
+        if hasCSSFont,
+           let font = CSSFontUtility.createFont(fromCSSStyle: cssStyle, currentFont: styleContainer.uiFont) {
+            return font
+        }
+
+        if let size = cssStyle["font-size"]?.string {
+            let resolvedSize = CSSFontUtility.parseSize(fromFontSize: size, baseSize: PlatformFont.systemFontSize)
+            return PlatformFont.systemFont(ofSize: resolvedSize)
+        }
+
+        if let envFont = styleContainer.uiFont {
+            return envFont
+        }
+        return PlatformFont.systemFont(ofSize: PlatformFont.systemFontSize)
+    }
+
+    var rubyFont: PlatformFont? {
+        if let size = attributes["ruby-annotation-font-size"]?.cgFloat {
+            if let fontName = attributes["ruby-annotation-font-name"]?.string,
+               let font = PlatformFont(name: fontName, size: size) {
+                return font
+            }
+            if let baseFont {
+                return baseFont.withSize(size)
+            }
+            return PlatformFont.systemFont(ofSize: size)
+        }
+        if let baseFont {
+            return baseFont.withSize(baseFont.pointSize * rubyScale)
+        }
+        return PlatformFont.systemFont(ofSize: PlatformFont.systemFontSize * rubyScale)
+    }
+
+    var rubyAnnotationColor: Color? {
+        if let color = attributes["ruby-annotation-color"]?.toColor() {
+            return color
+        }
+        return nil
+    }
+
+    var hasExplicitRubyAnnotationFont: Bool {
+        attributes["ruby-annotation-font-name"] != nil
+    }
+
+    func rubyFontWeight() -> PlatformFont.Weight {
+        guard let raw = attributes["ruby-font-weight"]?.string,
+              let value = Double(raw) else {
+            return .regular
+        }
+#if os(macOS)
+        return PlatformFont.Weight(value)
+#else
+        return PlatformFont.Weight(rawValue: CGFloat(value))
+#endif
+    }
+
+    func rubyFontItalic() -> Bool {
+        attributes["ruby-font-italic"]?.string == "1"
+    }
+}
+
+private struct RubyInlineLabel: View {
+    let baseText: String
+    let rubyText: String
+    let font: PlatformFont?
+    let rubyFont: PlatformFont?
+    let rubyPosition: CTRubyPosition
+    let rubyScale: CGFloat
+    let foregroundColor: Color?
+    let rubyAnnotationColor: Color?
+    let hasExplicitRubyAnnotationFont: Bool
+
+    var body: some View {
+#if os(macOS)
+        RubyTextRepresentable(
+            attributedText: attributedText,
+            rubyText: rubyText,
+            baseFont: font,
+            rubyFont: rubyFont,
+            rubyPosition: rubyPosition
+        )
+            .fixedSize()
+#else
+        RubyTextRepresentable(
+            attributedText: attributedText,
+            rubyText: rubyText,
+            baseFont: font,
+            rubyFont: rubyFont,
+            rubyPosition: rubyPosition
+        )
+            .fixedSize()
+#endif
+    }
+
+    private var attributedText: NSAttributedString {
+        let base = baseText.isEmpty ? rubyText : baseText
+        guard !base.isEmpty else { return NSAttributedString(string: "") }
+        guard !rubyText.isEmpty else {
+            logRubyDiagnostics(base: base, ruby: rubyText)
+            return NSAttributedString(string: base, attributes: baseAttributes)
+        }
+
+        let baseFont = font
+        let sizeFactor: CGFloat
+        if let rubyFont, let baseFont, baseFont.pointSize > 0 {
+            sizeFactor = rubyFont.pointSize / baseFont.pointSize
+        } else {
+            sizeFactor = rubyScale
+        }
+
+        var rubyAttributes: [CFString: Any] = [
+            kCTRubyAnnotationSizeFactorAttributeName: sizeFactor,
+            kCTRubyAnnotationScaleToFitAttributeName: false,
+        ]
+        if let rubyAnnotationColor {
+#if os(macOS)
+            rubyAttributes[kCTForegroundColorAttributeName] = NSColor(rubyAnnotationColor).cgColor
+#else
+            rubyAttributes[kCTForegroundColorAttributeName] = UIColor(rubyAnnotationColor).cgColor
+#endif
+        }
+        if hasExplicitRubyAnnotationFont, let rubyFont {
+            rubyAttributes[kCTFontAttributeName] = rubyFont.manabiCTFont
+        }
+
+        let annotation = CTRubyAnnotationCreateWithAttributes(
+            .auto,
+            .auto,
+            rubyPosition,
+            rubyText as CFString,
+            rubyAttributes as CFDictionary
+        )
+
+        var attributes = baseAttributes
+        attributes[kCTRubyAnnotationAttributeName as NSAttributedString.Key] = annotation
+        logRubyDiagnostics(base: base, ruby: rubyText)
+        return NSAttributedString(string: base, attributes: attributes)
+    }
+
+    private var baseAttributes: [NSAttributedString.Key: Any] {
+        var attributes: [NSAttributedString.Key: Any] = [:]
+        if let font {
+            attributes[.font] = font
+            attributes[kCTFontAttributeName as NSAttributedString.Key] = font.manabiCTFont
+        }
+        if let foregroundColor {
+#if os(macOS)
+            attributes[.foregroundColor] = NSColor(foregroundColor)
+#else
+            attributes[.foregroundColor] = UIColor(foregroundColor)
+#endif
+        }
+        return attributes
+    }
+
+    private func logRubyDiagnostics(base: String, ruby: String) {
+        let baseFontName = font?.fontName ?? "nil"
+        let baseFontSize = font.map { "\($0.pointSize)" } ?? "nil"
+        let rubyFontName = rubyFont?.fontName ?? "nil"
+        let rubyFontSize = rubyFont.map { "\($0.pointSize)" } ?? "nil"
+        let color = resolvedForegroundColor() ?? "nil"
+        let key = "ruby-\(base)-\(ruby)-\(rubyPosition.rawValue)-\(rubyScale)-\(baseFontName)-\(rubyFontName)"
+        AttachmentDebugLogger.recordOnce(
+            key,
+            message: "[Ruby] base='\(base)' ruby='\(ruby)' position=\(rubyPosition) scale=\(rubyScale) baseFont=\(baseFontName)@\(baseFontSize) rubyFont=\(rubyFontName)@\(rubyFontSize) color=\(color)"
+        )
+    }
+
+    private func resolvedForegroundColor() -> String? {
+        guard let foregroundColor else { return nil }
+#if os(macOS)
+        let nsColor = NSColor(foregroundColor)
+        guard let rgb = nsColor.usingColorSpace(.sRGB) else { return nil }
+        return String(format: "rgba(%.3f,%.3f,%.3f,%.3f)", rgb.redComponent, rgb.greenComponent, rgb.blueComponent, rgb.alphaComponent)
+#else
+        let uiColor = UIColor(foregroundColor)
+        var r: CGFloat = 0
+        var g: CGFloat = 0
+        var b: CGFloat = 0
+        var a: CGFloat = 0
+        guard uiColor.getRed(&r, green: &g, blue: &b, alpha: &a) else { return nil }
+        return String(format: "rgba(%.3f,%.3f,%.3f,%.3f)", r, g, b, a)
+#endif
+    }
+
+}
+
+#if os(macOS)
+private struct RubyTextRepresentable: NSViewRepresentable {
+    let attributedText: NSAttributedString
+    let rubyText: String
+    let baseFont: PlatformFont?
+    let rubyFont: PlatformFont?
+    let rubyPosition: CTRubyPosition
+
+    func makeNSView(context: Context) -> RubyTextView {
+        let view = RubyTextView()
+        view.setContentHuggingPriority(.required, for: .horizontal)
+        view.setContentHuggingPriority(.required, for: .vertical)
+        view.setContentCompressionResistancePriority(.required, for: .horizontal)
+        view.setContentCompressionResistancePriority(.required, for: .vertical)
+        view.attributedText = attributedText
+        view.rubyText = rubyText
+        view.baseFont = baseFont
+        view.rubyFont = rubyFont
+        view.rubyPosition = rubyPosition
+        return view
+    }
+
+    func updateNSView(_ nsView: RubyTextView, context: Context) {
+        nsView.attributedText = attributedText
+        nsView.rubyText = rubyText
+        nsView.baseFont = baseFont
+        nsView.rubyFont = rubyFont
+        nsView.rubyPosition = rubyPosition
+    }
+}
+#else
+private struct RubyTextRepresentable: UIViewRepresentable {
+    let attributedText: NSAttributedString
+    let rubyText: String
+    let baseFont: PlatformFont?
+    let rubyFont: PlatformFont?
+    let rubyPosition: CTRubyPosition
+
+    func makeUIView(context: Context) -> RubyTextView {
+        let view = RubyTextView()
+        view.setContentHuggingPriority(.required, for: .horizontal)
+        view.setContentHuggingPriority(.required, for: .vertical)
+        view.setContentCompressionResistancePriority(.required, for: .horizontal)
+        view.setContentCompressionResistancePriority(.required, for: .vertical)
+        view.attributedText = attributedText
+        view.rubyText = rubyText
+        view.baseFont = baseFont
+        view.rubyFont = rubyFont
+        view.rubyPosition = rubyPosition
+        return view
+    }
+
+    func updateUIView(_ uiView: RubyTextView, context: Context) {
+        uiView.attributedText = attributedText
+        uiView.rubyText = rubyText
+        uiView.baseFont = baseFont
+        uiView.rubyFont = rubyFont
+        uiView.rubyPosition = rubyPosition
+    }
+}
+#endif
+
+private final class RubyTextView: PlatformView {
+    var rubyText: String = "" {
+        didSet {
+            guard oldValue != rubyText else { return }
+#if os(macOS)
+            needsDisplay = true
+            invalidateIntrinsicContentSize()
+#else
+            setNeedsDisplay()
+            invalidateIntrinsicContentSize()
+#endif
+        }
+    }
+    var baseFont: PlatformFont?
+    var rubyFont: PlatformFont?
+    var rubyPosition: CTRubyPosition = .before
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        configureForTransparentRendering()
+    }
+
+    required init?(coder: NSCoder) {
+        super.init(coder: coder)
+        configureForTransparentRendering()
+    }
+
+    var attributedText: NSAttributedString? {
+        didSet {
+            guard oldValue != attributedText else { return }
+#if os(macOS)
+            needsDisplay = true
+            invalidateIntrinsicContentSize()
+#else
+            setNeedsDisplay()
+            invalidateIntrinsicContentSize()
+#endif
+        }
+    }
+
+#if os(macOS)
+    private func configureForTransparentRendering() {
+        wantsLayer = true
+        layer?.backgroundColor = NSColor.clear.cgColor
+    }
+#else
+    private func configureForTransparentRendering() {
+        backgroundColor = .clear
+        isOpaque = false
+    }
+#endif
+
+#if os(macOS)
+    override func draw(_ dirtyRect: CGRect) {
+        super.draw(dirtyRect)
+        guard let context = NSGraphicsContext.current?.cgContext else { return }
+        drawText(in: context, rect: bounds)
+    }
+#else
+    override func draw(_ rect: CGRect) {
+        guard let context = UIGraphicsGetCurrentContext() else { return }
+        drawText(in: context, rect: rect)
+    }
+#endif
+
+    override var intrinsicContentSize: CGSize {
+        guard let attributedText, attributedText.length > 0 else {
+            return .zero
+        }
+        let line = CTLineCreateWithAttributedString(attributedText as CFAttributedString)
+        var ascent: CGFloat = 0
+        var descent: CGFloat = 0
+        var leading: CGFloat = 0
+        let idealWidth = CGFloat(CTLineGetTypographicBounds(line, &ascent, &descent, &leading)).rounded(.up)
+        let baseMetrics = baseFontMetrics()
+        let baseAscent = baseMetrics.ascent ?? ascent
+        let baseDescent = baseMetrics.descent ?? descent
+        let baseLeading = baseMetrics.leading ?? leading
+        let baseHeight = (baseAscent + baseDescent + baseLeading)
+        let rubyHeight = resolvedRubyHeight()
+        let extraAbove: CGFloat
+        let extraBelow: CGFloat
+        switch rubyPosition {
+        case .before:
+            extraAbove = rubyHeight
+            extraBelow = 0
+        case .after:
+            extraAbove = 0
+            extraBelow = rubyHeight
+        default:
+            extraAbove = rubyHeight / 2
+            extraBelow = rubyHeight / 2
+        }
+        let height = (baseHeight + extraAbove + extraBelow).rounded(.up)
+        if ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+            || NSClassFromString("XCTestCase") != nil {
+            let bounds = CTLineGetBoundsWithOptions(
+                line,
+                [.useGlyphPathBounds, .useOpticalBounds]
+            )
+            AttachmentDebugLogger.recordOnce(
+                "ruby-view-metrics-\(attributedText.string.hashValue)",
+                message: "[RubyView] text='\(attributedText.string)' ascent=\(ascent) descent=\(descent) leading=\(leading) bounds=\(bounds) rubyH=\(rubyHeight) position=\(rubyPosition.rawValue) intrinsic=\(CGSize(width: idealWidth, height: height))"
+            )
+        }
+        return CGSize(width: idealWidth, height: height)
+    }
+
+    private func resolvedRubyHeight() -> CGFloat {
+        if let rubyFont, !rubyText.isEmpty {
+            let attributed = NSAttributedString(string: rubyText, attributes: [.font: rubyFont])
+            let line = CTLineCreateWithAttributedString(attributed as CFAttributedString)
+            var ascent: CGFloat = 0
+            var descent: CGFloat = 0
+            var leading: CGFloat = 0
+            _ = CTLineGetTypographicBounds(line, &ascent, &descent, &leading)
+            return max(0, ascent + descent + leading)
+        }
+        if let baseFont {
+            return baseFont.manabiFontHeight * 0.5
+        }
+        return 0
+    }
+
+    private func rubyExtraBelow() -> CGFloat {
+        let rubyHeight = resolvedRubyHeight()
+        switch rubyPosition {
+        case .after: return rubyHeight
+        case .before: return 0
+        default: return rubyHeight / 2
+        }
+    }
+
+    private func rubyExtraAbove() -> CGFloat {
+        let rubyHeight = resolvedRubyHeight()
+        switch rubyPosition {
+        case .before: return rubyHeight
+        case .after: return 0
+        default: return rubyHeight / 2
+        }
+    }
+
+    private func drawText(in context: CGContext, rect: CGRect) {
+        guard let attributedText, attributedText.length > 0 else { return }
+
+        context.saveGState()
+#if os(macOS)
+        let ctm = context.ctm
+        let isFlipped = ctm.d < 0
+        if !isFlipped {
+            context.translateBy(x: 0, y: rect.height)
+            context.scaleBy(x: 1.0, y: -1.0)
+        }
+#else
+        context.translateBy(x: 0, y: rect.height)
+        context.scaleBy(x: 1.0, y: -1.0)
+#endif
+
+        let line = CTLineCreateWithAttributedString(attributedText as CFAttributedString)
+
+        let endAttributes = attributedText.attributes(at: max(0, attributedText.length - 1), effectiveRange: nil)
+        let token = NSAttributedString(string: "\u{2026}", attributes: endAttributes)
+        let tokenLine = CTLineCreateWithAttributedString(token as CFAttributedString)
+
+        let truncated = CTLineCreateTruncatedLine(line, Double(rect.width), .end, tokenLine) ?? line
+
+        let glyphBounds = CTLineGetBoundsWithOptions(truncated, [.useGlyphPathBounds])
+        var ascent: CGFloat = 0
+        var descent: CGFloat = 0
+        var leading: CGFloat = 0
+        _ = CTLineGetTypographicBounds(truncated, &ascent, &descent, &leading)
+        let baselineX = rect.minX - glyphBounds.origin.x
+        let baselineY = rect.minY + rubyExtraBelow()
+        context.textPosition = CGPoint(x: baselineX, y: baselineY)
+
+        CTLineDraw(truncated, context)
+        context.restoreGState()
+    }
+
+    private func baseFontMetrics() -> (ascent: CGFloat?, descent: CGFloat?, leading: CGFloat?) {
+        guard let baseFont else { return (nil, nil, nil) }
+        let ctFont = baseFont.manabiCTFont
+        let ascent = CTFontGetAscent(ctFont)
+        let descent = CTFontGetDescent(ctFont)
+        let leading = CTFontGetLeading(ctFont)
+        return (ascent, descent, leading)
+    }
+}
diff --git a/Sources/SwiftUIHTML/Tag/Inline/UnderlineTag.swift b/Sources/SwiftUIHTML/Tag/Inline/UnderlineTag.swift
index 2281f0c..97218b7 100644
--- a/Sources/SwiftUIHTML/Tag/Inline/UnderlineTag.swift
+++ b/Sources/SwiftUIHTML/Tag/Inline/UnderlineTag.swift
@@ -7,8 +7,7 @@ struct UnderlineTag: InlineTag {
         styleContainer.underlineStyle = .single
 
         if let underlineColor = attributes["underline-color"]?.toColor() {
-            styleContainer.underlineColor = UIColor(underlineColor)
+            styleContainer.underlineColor = PlatformColor(underlineColor)
         }
     }
 }
-
diff --git a/Sources/SwiftUIHTML/ValueType/AttributeValue.swift b/Sources/SwiftUIHTML/ValueType/AttributeValue.swift
index 70624e5..1c12042 100644
--- a/Sources/SwiftUIHTML/ValueType/AttributeValue.swift
+++ b/Sources/SwiftUIHTML/ValueType/AttributeValue.swift
@@ -4,6 +4,10 @@ import SwiftUI
 
 public struct AttributeValue: Sendable, Hashable {
     let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
     
     public func convert<T: RawRepresentable>(to type: T.Type) -> T? where T.RawValue == String {
         type.init(rawValue: rawValue)
@@ -24,7 +28,7 @@ public struct AttributeValue: Sendable, Hashable {
     }
     
     public var int: Int? {
-        Int(rawValue.replacingOccurrences(of: "px", with: ""))
+        return Int(rawValue.replacingOccurrences(of: "px", with: ""))
     }
     
     public var url: URL? {
@@ -32,7 +36,8 @@ public struct AttributeValue: Sendable, Hashable {
     }
     
     public var cssStyle: CSSStyle? {
-        CSSStyle(style: rawValue)
+        let hasColon = rawValue.utf8.contains(0x3A)
+        return CSSStyle.cached(style: rawValue, hasColon: hasColon)
     }
     
     public func toBool() -> Bool? {
diff --git a/Sources/SwiftUIHTML/ValueType/CSSStyle.swift b/Sources/SwiftUIHTML/ValueType/CSSStyle.swift
index aeaac18..1d062b5 100644
--- a/Sources/SwiftUIHTML/ValueType/CSSStyle.swift
+++ b/Sources/SwiftUIHTML/ValueType/CSSStyle.swift
@@ -4,22 +4,65 @@ import Foundation
 
 public struct CSSStyle: Sendable {
     private let styles: [String: AttributeValue]
+    private nonisolated(unsafe) static let cache: NSCache<NSString, CSSStyleBox> = {
+        let cache = NSCache<NSString, CSSStyleBox>()
+        cache.countLimit = 256
+        return cache
+    }()
 
     init(styles: [String: AttributeValue]) {
         self.styles = styles
     }
 
     public init?(style: String) {
-        styles = Dictionary(
-            uniqueKeysWithValues: style
-                .split(separator: ";")
-                .compactMap {
-                    let keyValue = $0.split(separator: ":")
-                    guard let key = keyValue.first?.trimmingCharacters(in: .whitespaces),
-                          let value = keyValue.last?.trimmingCharacters(in: .whitespaces) else { return nil }
-                    return (String(key), AttributeValue(rawValue: value))
-                }
-        )
+        if style.isEmpty {
+            return nil
+        }
+        if ASCIIWhitespace.trim(style).isEmpty {
+            styles = ["": AttributeValue(rawValue: "")]
+            return
+        }
+        if !style.utf8.contains(0x3A) {
+            return nil
+        }
+        var parsed: [String: AttributeValue] = [:]
+        parsed.reserveCapacity(8)
+
+        let utf8 = style.utf8
+        var segmentStart = utf8.startIndex
+        var index = segmentStart
+
+        func processSegment(start: String.UTF8View.Index, end: String.UTF8View.Index) {
+            guard start < end else { return }
+            let startIndex = String.Index(start, within: style) ?? style.startIndex
+            let endIndex = String.Index(end, within: style) ?? style.endIndex
+            let component = style[startIndex..<endIndex]
+            let componentUTF8 = component.utf8
+            guard let colonIndex = componentUTF8.firstIndex(of: 0x3A) else { return } // ":"
+
+            let keyStart = component.startIndex
+            let keyEnd = String.Index(colonIndex, within: component) ?? component.endIndex
+            let valueStartUTF8 = componentUTF8.index(after: colonIndex)
+            let valueStart = String.Index(valueStartUTF8, within: component) ?? component.endIndex
+
+            let keySlice = ASCIIWhitespace.trim(component[keyStart..<keyEnd])
+            let valueSlice = ASCIIWhitespace.trim(component[valueStart..<component.endIndex])
+            guard !keySlice.isEmpty, !valueSlice.isEmpty else { return }
+            parsed[String(keySlice)] = AttributeValue(rawValue: String(valueSlice))
+        }
+
+        while index < utf8.endIndex {
+            if utf8[index] == 0x3B { // ";"
+                processSegment(start: segmentStart, end: index)
+                segmentStart = utf8.index(after: index)
+            }
+            index = utf8.index(after: index)
+        }
+        if segmentStart < utf8.endIndex {
+            processSegment(start: segmentStart, end: utf8.endIndex)
+        }
+
+        styles = parsed
         
         if styles.isEmpty {
             return nil
@@ -29,13 +72,43 @@ public struct CSSStyle: Sendable {
     public subscript(_ key: String) -> AttributeValue? {
         styles[key]
     }
+
+    var isEmpty: Bool {
+        styles.isEmpty
+    }
     
     public func forEach(_ body: ((key: String, value: AttributeValue)) -> Void) {
         styles.forEach(body)
     }
 }
 
+
+
 extension CSSStyle {
     static let empty = CSSStyle(styles: [:])
+
+    static func cached(style: String) -> CSSStyle? {
+        let hasColon = style.utf8.contains(0x3A)
+        return cached(style: style, hasColon: hasColon)
+    }
+
+    @inline(__always)
+    static func cached(style: String, hasColon: Bool) -> CSSStyle? {
+        guard hasColon else { return nil }
+        let key = style as NSString
+        if let cached = cache.object(forKey: key) {
+            return cached.value
+        }
+        guard let parsed = CSSStyle(style: style) else { return nil }
+        cache.setObject(CSSStyleBox(parsed), forKey: key)
+        return parsed
+    }
 }
 
+private final class CSSStyleBox {
+    let value: CSSStyle
+
+    init(_ value: CSSStyle) {
+        self.value = value
+    }
+}
diff --git a/Sources/SwiftUIHTML/ValueType/LineBreakMode.swift b/Sources/SwiftUIHTML/ValueType/LineBreakMode.swift
index d6de507..21ba02f 100644
--- a/Sources/SwiftUIHTML/ValueType/LineBreakMode.swift
+++ b/Sources/SwiftUIHTML/ValueType/LineBreakMode.swift
@@ -16,7 +16,7 @@ extension LineBreakMode {
             return text.byCharWrapping()
         case .byWordWrapping:
             return text
-        case .custom(let id, let transform):
+        case .custom(_, let transform):
             return transform(text)
         }
     }
@@ -40,3 +40,17 @@ extension LineBreakMode: Equatable, CustomStringConvertible {
         }
     }
 }
+
+extension LineBreakMode: Hashable {
+    public func hash(into hasher: inout Hasher) {
+        switch self {
+        case .byCharWrapping:
+            hasher.combine(0)
+        case .byWordWrapping:
+            hasher.combine(1)
+        case .custom(let id, _):
+            hasher.combine(2)
+            hasher.combine(id)
+        }
+    }
+}
diff --git a/Sources/SwiftUIHTML/View/HTMLBlock.swift b/Sources/SwiftUIHTML/View/HTMLBlock.swift
index 64adf6b..25e8049 100644
--- a/Sources/SwiftUIHTML/View/HTMLBlock.swift
+++ b/Sources/SwiftUIHTML/View/HTMLBlock.swift
@@ -11,22 +11,114 @@ public struct HTMLBlock: View {
     let element: BlockElement
 
     @HTMLEnvironment(\._configuration) var configuration
+    private var shouldLogMargins: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_MARGIN_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_MARGIN_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+    }
+    private var shouldLogBlocks: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_BLOCK_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_BLOCK_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+    }
+    private var shouldLogLayout: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_LAYOUT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_LAYOUT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+    }
 
     public init(element: BlockElement) {
         self.element = element
     }
 
     public var body: some View {
-        ForEach(groupContents(contents: element.contents).indicesCollection, id: \.0) { _, groupContent in
-            renderContent(groupContent)
+        let groups = groupContents(contents: element.contents)
+        let margins = groups.map { group in
+            switch group {
+            case .block(let child):
+                return Self.blockMargins(for: child.attributes)
+            case .inline:
+                return (top: CGFloat.zero, bottom: CGFloat.zero)
+            }
+        }
+        let collapseEnabled = configuration.collapseBlockMargins
+        let isBodyRoot = element.tag.lowercased() == "body"
+        let canCollapseParentEdges = collapseEnabled && !isBodyRoot && !Self.hasPaddingOrBorder(attributes: element.attributes)
+        if shouldLogMargins {
+            for (index, group) in groups.enumerated() {
+                guard case let .block(child) = group else { continue }
+                let prevIndex = Self.previousBlockIndex(before: index, in: groups)
+                let nextIndex = Self.nextBlockIndex(after: index, in: groups)
+                let isFirstBlock = Self.isFirstContentBlock(at: index, in: groups)
+                let isLastBlock = Self.isLastContentBlock(at: index, in: groups)
+                let prevBottom = prevIndex.map { margins[$0].bottom } ?? 0
+                let collapseTop = canCollapseParentEdges
+                    ? (isFirstBlock ? margins[index].top : (prevIndex != nil ? Self.collapseAmount(prevBottom: prevBottom, currentTop: margins[index].top) : 0))
+                    : 0
+                let dropBottom = canCollapseParentEdges && isLastBlock ? margins[index].bottom : 0
+                AttachmentDebugLogger.record(
+                    "[Margin] tag=\(child.tag) index=\(index) top=\(margins[index].top) bottom=\(margins[index].bottom) collapseTop=\(collapseTop) dropBottom=\(dropBottom) prevBottom=\(prevBottom) collapseEdges=\(canCollapseParentEdges)"
+                )
+            }
         }
+        return VStack(alignment: .leading, spacing: .zero) {
+            ForEach(Array(groups.indices), id: \.self) { index in
+                let group = groups[index]
+                let prevIndex = Self.previousBlockIndex(before: index, in: groups)
+                let nextIndex = Self.nextBlockIndex(after: index, in: groups)
+                let isFirstBlock = Self.isFirstContentBlock(at: index, in: groups)
+                let isLastBlock = Self.isLastContentBlock(at: index, in: groups)
+                let prevBottom = prevIndex.map { margins[$0].bottom } ?? 0
+                let collapseTop = canCollapseParentEdges
+                    ? (isFirstBlock ? margins[index].top : (prevIndex != nil ? Self.collapseAmount(prevBottom: prevBottom, currentTop: margins[index].top) : 0))
+                    : 0
+                let dropBottom = canCollapseParentEdges && isLastBlock ? margins[index].bottom : 0
+                renderContent(
+                    group,
+                    applyTopPadding: true,
+                    applyBottomPadding: true,
+                    collapseTop: collapseTop,
+                    dropBottom: dropBottom,
+                    logBlock: shouldLogBlocks,
+                    blockIndex: index
+                )
+            }
+        }
+        .background(
+            GeometryReader { proxy in
+                let size = proxy.size
+                Color.clear
+                    .hidden()
+                    .onAppear {
+                        if shouldLogLayout {
+                            AttachmentDebugLogger.record("[Layout][BlockRoot] tag=\(element.tag) size=\(size)")
+                        }
+                    }
+                    .onChange(of: size) { newValue in
+                        if shouldLogLayout {
+                            AttachmentDebugLogger.record("[Layout][BlockRoot] tag=\(element.tag) size=\(newValue)")
+                        }
+                    }
+            }
+        )
     }
 }
 
 // MARK: - private
 private extension HTMLBlock {
     @ViewBuilder
-    func renderContent(_ groupContent: GroupContent) -> some View {
+    func renderContent(
+        _ groupContent: GroupContent,
+        applyTopPadding: Bool,
+        applyBottomPadding: Bool,
+        collapseTop: CGFloat,
+        dropBottom: CGFloat,
+        logBlock: Bool,
+        blockIndex: Int
+    ) -> some View {
         switch groupContent {
         case .block(let childElement):
             VStack(alignment: .leading, spacing: .zero) {
@@ -37,48 +129,352 @@ private extension HTMLBlock {
                 configuration.attributeStyle
                     .eraseToAnyLayoutModifier(attributes: childElement.attributes)
             )
+            .padding(.top, -collapseTop)
+            .padding(.bottom, -dropBottom)
+            .background(
+                GeometryReader { proxy in
+                    let frame = proxy.frame(in: .global)
+                    let size = proxy.size
+                    Color.clear
+                        .hidden()
+                        .onAppear {
+                            AttachmentDebugLogger.record(
+                                "[BlockFrame] tag=\(childElement.tag) index=\(blockIndex) global=\(frame)"
+                            )
+                            if logBlock {
+                                AttachmentDebugLogger.record(
+                                    "[Layout][Block] tag=\(childElement.tag) index=\(blockIndex) size=\(size)"
+                                )
+                            }
+                        }
+                        .onChange(of: frame) { newValue in
+                            AttachmentDebugLogger.record(
+                                "[BlockFrame] tag=\(childElement.tag) index=\(blockIndex) global=\(newValue)"
+                            )
+                        }
+                }
+            )
         case .inline(let elements):
-            renderInline(elements: elements)
+            renderInline(
+                elements: elements,
+                applyTopPadding: true,
+                applyBottomPadding: true
+            )
         }
     }
 
     @ViewBuilder
-    func renderInline(elements: [InlineElement]) -> some View {
+    func renderInline(
+        elements: [InlineElement],
+        applyTopPadding: Bool,
+        applyBottomPadding: Bool
+    ) -> some View {
         // attachment 만 독립적으로 있는경우는 Inline 말고 View로 render
-        if elements.count == 1, let element = elements.first, case .attachment = element.type {
-            configuration.createAttachment(for: element.tag, with: element.attributes)
-                .modifier(LinkModifier(link: element.styleContainer.link))
+        if let attachmentElement = Self.singleAttachment(in: elements) {
+            let size = ElementSize(attributes: attachmentElement.attributes)
+            let _ = shouldLogLayout ? AttachmentDebugLogger.record(
+                "[Layout][InlineSingleAttachment] tag=\(attachmentElement.tag) size=\(String(describing: size.width))x\(String(describing: size.height))"
+            ) : ()
+            if let attachment = configuration.createAttachment(
+                for: attachmentElement.tag,
+                with: attachmentElement.attributes
+            ) {
+                let attachmentView = attachment
+                    .modifier(LinkModifier(link: attachmentElement.styleContainer.link))
+                if let width = size.width, let height = size.height {
+                    attachmentView.frame(width: width, height: height, alignment: .topLeading)
+                } else if let width = size.width {
+                    attachmentView.aspectRatio(contentMode: .fit).frame(width: width)
+                } else if let height = size.height {
+                    attachmentView.aspectRatio(contentMode: .fit).frame(height: height)
+                } else {
+                    attachmentView
+                }
+            } else {
+                EmptyView()
+            }
         } else {
-            HTMLInline(elements: elements)
+            HTMLInline(
+                elements: elements,
+                applyTopPadding: applyTopPadding,
+                applyBottomPadding: applyBottomPadding
+            )
+            .background(
+                GeometryReader { proxy in
+                    let size = proxy.size
+                    Color.clear
+                        .hidden()
+                        .onAppear {
+                            if shouldLogLayout {
+                                AttachmentDebugLogger.record("[Layout][Inline] size=\(size)")
+                            }
+                        }
+                        .onChange(of: size) { newValue in
+                            if shouldLogLayout {
+                                AttachmentDebugLogger.record("[Layout][Inline] size=\(newValue)")
+                            }
+                        }
+                }
+            )
         }
     }
 
     func groupContents(contents: [TagElement]) -> [GroupContent] {
         var result: [GroupContent] = []
+        result.reserveCapacity(contents.count)
         var currentInlineGroup: [InlineElement] = []
 
-        contents.forEach { content in
+        for content in contents {
             switch content {
             case let .block(blockElement):
                 if !currentInlineGroup.isEmpty {
-                    result.append(.inline(currentInlineGroup))
-                    currentInlineGroup.removeAll()
+                    if !Self.isTrimmableWhitespaceInlineGroup(currentInlineGroup) {
+                        result.append(.inline(currentInlineGroup))
+                    }
+                    currentInlineGroup.removeAll(keepingCapacity: true)
                 }
-                result += [.block(blockElement)]
+                result.append(.block(blockElement))
 
             case let .inline(inlineElement):
-                currentInlineGroup += [inlineElement]
+                currentInlineGroup.append(inlineElement)
             }
         }
 
-        if !currentInlineGroup.isEmpty {
+        if !currentInlineGroup.isEmpty,
+           !Self.isTrimmableWhitespaceInlineGroup(currentInlineGroup) {
             result.append(.inline(currentInlineGroup))
         }
-
         return result
     }
 }
 
+private extension HTMLBlock.GroupContent {
+    var isBlock: Bool {
+        if case .block = self {
+            return true
+        }
+        return false
+    }
+}
+
+private extension HTMLBlock {
+    static func blockMargins(for attributes: [String: AttributeValue]) -> (top: CGFloat, bottom: CGFloat) {
+        let cssStyle = attributes["style"]?.cssStyle ?? .empty
+        if let insets = cssStyle["margin"]?.toEdgeInsets() {
+            return (insets.top, insets.bottom)
+        } else if let value = cssStyle["margin"]?.cgFloat {
+            return (value, value)
+        }
+        let top = cssStyle["margin-top"]?.cgFloat ?? 0
+        let bottom = cssStyle["margin-bottom"]?.cgFloat ?? 0
+        return (top, bottom)
+    }
+
+    static func collapseAmount(prevBottom: CGFloat, currentTop: CGFloat) -> CGFloat {
+        if prevBottom >= 0, currentTop >= 0 {
+            return max(prevBottom, currentTop)
+        }
+        if prevBottom <= 0, currentTop <= 0 {
+            return min(prevBottom, currentTop)
+        }
+        return 0
+    }
+
+    static func hasPaddingOrBorder(attributes: [String: AttributeValue]) -> Bool {
+        let cssStyle = attributes["style"]?.cssStyle ?? .empty
+        return hasPadding(cssStyle) || hasBorder(cssStyle)
+    }
+
+    static func hasPadding(_ cssStyle: CSSStyle) -> Bool {
+        if let insets = cssStyle["padding"]?.toEdgeInsets() {
+            return insets.top != 0 || insets.leading != 0 || insets.bottom != 0 || insets.trailing != 0
+        }
+        if let value = cssStyle["padding"]?.cgFloat, value != 0 {
+            return true
+        }
+        if let top = cssStyle["padding-top"]?.cgFloat, top != 0 { return true }
+        if let right = cssStyle["padding-right"]?.cgFloat, right != 0 { return true }
+        if let bottom = cssStyle["padding-bottom"]?.cgFloat, bottom != 0 { return true }
+        if let left = cssStyle["padding-left"]?.cgFloat, left != 0 { return true }
+        return false
+    }
+
+    static func hasBorder(_ cssStyle: CSSStyle) -> Bool {
+        if let value = cssStyle["border-width"]?.cgFloat, value != 0 {
+            return true
+        }
+        if let top = cssStyle["border-top-width"]?.cgFloat, top != 0 { return true }
+        if let right = cssStyle["border-right-width"]?.cgFloat, right != 0 { return true }
+        if let bottom = cssStyle["border-bottom-width"]?.cgFloat, bottom != 0 { return true }
+        if let left = cssStyle["border-left-width"]?.cgFloat, left != 0 { return true }
+        if let shorthand = cssStyle["border"]?.string,
+           let numeric = shorthand.split(separator: " ").first,
+           let width = Double(numeric.replacingOccurrences(of: "px", with: "")),
+           width != 0 {
+            return true
+        }
+        return false
+    }
+
+    static func isWhitespaceOnlyInlineGroup(_ elements: [InlineElement]) -> Bool {
+        for element in elements {
+            switch element.type {
+            case .attachment:
+                return false
+            case let .text(string):
+                if !ASCIIWhitespace.trim(string).isEmpty {
+                    return false
+                }
+            }
+        }
+        return true
+    }
+
+    static func singleAttachment(in elements: [InlineElement]) -> InlineElement? {
+        var attachment: InlineElement?
+        for element in elements {
+            switch element.type {
+            case .attachment:
+                if attachment != nil {
+                    return nil
+                }
+                attachment = element
+            case let .text(string):
+                if !ASCIIWhitespace.trim(string).isEmpty {
+                    return nil
+                }
+            }
+        }
+        return attachment
+    }
+
+    static func isTrimmableWhitespaceInlineGroup(_ elements: [InlineElement]) -> Bool {
+        for element in elements {
+            switch element.type {
+            case .attachment:
+                return false
+            case let .text(string):
+                if !ASCIIWhitespace.trim(string).isEmpty {
+                    return false
+                }
+            }
+        }
+        return true
+    }
+
+    static func isFirstInlineGroup(at index: Int, in groups: [GroupContent]) -> Bool {
+        guard index >= 0, index < groups.count else { return false }
+        guard case let .inline(elements) = groups[index],
+              !isWhitespaceOnlyInlineGroup(elements) else { return false }
+        var cursor = index - 1
+        while cursor >= 0 {
+            switch groups[cursor] {
+            case .block:
+                return false
+            case .inline(let prevElements):
+                if !isWhitespaceOnlyInlineGroup(prevElements) {
+                    return false
+                }
+            }
+            cursor -= 1
+        }
+        return true
+    }
+
+    static func isLastInlineGroup(at index: Int, in groups: [GroupContent]) -> Bool {
+        guard index >= 0, index < groups.count else { return false }
+        guard case let .inline(elements) = groups[index],
+              !isWhitespaceOnlyInlineGroup(elements) else { return false }
+        var cursor = index + 1
+        while cursor < groups.count {
+            switch groups[cursor] {
+            case .block:
+                return false
+            case .inline(let nextElements):
+                if !isWhitespaceOnlyInlineGroup(nextElements) {
+                    return false
+                }
+            }
+            cursor += 1
+        }
+        return true
+    }
+
+    static func previousBlockIndex(before index: Int, in groups: [GroupContent]) -> Int? {
+        guard index > 0 else { return nil }
+        var cursor = index - 1
+        while cursor >= 0 {
+            switch groups[cursor] {
+            case .block:
+                return cursor
+            case .inline(let elements):
+                if isWhitespaceOnlyInlineGroup(elements) {
+                    cursor -= 1
+                    continue
+                }
+                return nil
+            }
+        }
+        return nil
+    }
+
+    static func nextBlockIndex(after index: Int, in groups: [GroupContent]) -> Int? {
+        guard index + 1 < groups.count else { return nil }
+        var cursor = index + 1
+        while cursor < groups.count {
+            switch groups[cursor] {
+            case .block:
+                return cursor
+            case .inline(let elements):
+                if isWhitespaceOnlyInlineGroup(elements) {
+                    cursor += 1
+                    continue
+                }
+                return nil
+            }
+        }
+        return nil
+    }
+
+    static func isFirstContentBlock(at index: Int, in groups: [GroupContent]) -> Bool {
+        guard case .block = groups[index] else { return false }
+        guard index > 0 else { return true }
+        var cursor = index - 1
+        while cursor >= 0 {
+            switch groups[cursor] {
+            case .block:
+                return false
+            case .inline(let elements):
+                if !isWhitespaceOnlyInlineGroup(elements) {
+                    return false
+                }
+            }
+            cursor -= 1
+        }
+        return true
+    }
+
+    static func isLastContentBlock(at index: Int, in groups: [GroupContent]) -> Bool {
+        guard case .block = groups[index] else { return false }
+        guard index + 1 < groups.count else { return true }
+        var cursor = index + 1
+        while cursor < groups.count {
+            switch groups[cursor] {
+            case .block:
+                return false
+            case .inline(let elements):
+                if !isWhitespaceOnlyInlineGroup(elements) {
+                    return false
+                }
+            }
+            cursor += 1
+        }
+        return true
+    }
+}
+
+private extension HTMLBlock {}
+
 extension HTMLBlock: @preconcurrency Equatable {
     public static func == (lhs: Self, rhs: Self) -> Bool {
         lhs.element == rhs.element
diff --git a/Sources/SwiftUIHTML/View/HTMLInline.swift b/Sources/SwiftUIHTML/View/HTMLInline.swift
index 5ef2d6c..59a4126 100644
--- a/Sources/SwiftUIHTML/View/HTMLInline.swift
+++ b/Sources/SwiftUIHTML/View/HTMLInline.swift
@@ -9,21 +9,84 @@ struct HTMLInline: View {
     }
 
     let texts: [TextType]
+    let hasAttachment: Bool
+    let textLine: TextLine
+    let applyTopPadding: Bool
+    let applyBottomPadding: Bool
     @StateObject var attachmentManager = AttachmentManager()
+    @HTMLEnvironment(\.styleContainer) private var styleContainer
 
-    init(elements: [InlineElement]) {
-        self.init(texts: elements.toHTMLTextType())
+    init(
+        elements: [InlineElement],
+        applyTopPadding: Bool = true,
+        applyBottomPadding: Bool = true
+    ) {
+        self.init(
+            texts: elements.toHTMLTextType(),
+            applyTopPadding: applyTopPadding,
+            applyBottomPadding: applyBottomPadding
+        )
     }
 
-    init(texts: [TextType]) {
-        self.texts = texts.trimmingNewLines()
+    init(
+        texts: [TextType],
+        applyTopPadding: Bool = true,
+        applyBottomPadding: Bool = true
+    ) {
+        if Self.shouldLogInline() {
+            Self.logLeadingWhitespace(texts: texts)
+        }
+        let trimmed = texts
+            .trimmingNewLines()
+            .trimmingLeadingWhitespace()
+            .coalescingTextRuns()
+        if trimmed.isEmpty, Self.shouldLogInline() {
+            AttachmentDebugLogger.record("[Inline] empty after trimming")
+        }
+        self.texts = trimmed
+        self.hasAttachment = trimmed.contains(where: \.hasAttachment)
+        self.textLine = Self.resolveTextLine(texts: trimmed)
+        self.applyTopPadding = applyTopPadding
+        self.applyBottomPadding = applyBottomPadding
     }
 
     var body: some View {
-        content
-            .fixedSize(horizontal: false, vertical: true)
-            .overlay(alignment: .topLeading) { htmlTextLayout }
-            .modifier(TextLineModifier(textLine: textLine))
+        if texts.isEmpty {
+            EmptyView()
+        } else {
+            content
+                .fixedSize(horizontal: false, vertical: true)
+                .overlay(alignment: .topLeading) { htmlTextLayout }
+                .modifier(TextLineModifier(
+                    textLine: textLine,
+                    applyTopPadding: applyTopPadding,
+                    applyBottomPadding: applyBottomPadding
+                ))
+                .onAppear {
+                    let styleLineSpacing = styleContainer.textLine?.lineSpacing ?? 0
+                    let styleVerticalPadding = styleContainer.textLine?.verticalPadding ?? 0
+                    let effectiveLineSpacing = max(textLine.lineSpacing, styleLineSpacing)
+                    let effectiveVerticalPadding = max(textLine.verticalPadding, styleVerticalPadding)
+                    AttachmentDebugLogger.record(
+                        "[Inline] textLine spacing=\(textLine.lineSpacing) verticalPadding=\(textLine.verticalPadding) styleLineSpacing=\(styleLineSpacing) styleVerticalPadding=\(styleVerticalPadding) effectiveLineSpacing=\(effectiveLineSpacing) effectiveVerticalPadding=\(effectiveVerticalPadding)"
+                    )
+                    if let font = styleContainer.uiFont {
+                        AttachmentDebugLogger.recordOnce(
+                            "inline-font-\(font.fontName)-\(font.pointSize)",
+                            message: "[InlineFont] name=\(font.fontName) size=\(font.pointSize)"
+                        )
+                    }
+                }
+                .background(
+                    GeometryReader { proxy in
+                        Color.clear
+                            .hidden()
+                            .modifier(OnChangeViewModifier(of: proxy.size, initial: true) { _, newValue in
+                                AttachmentDebugLogger.record("[Inline] contentSize=\(newValue)")
+                            })
+                    }
+                )
+        }
     }
 
     @ViewBuilder
@@ -36,52 +99,94 @@ struct HTMLInline: View {
         }
     }
 
-    var hasAttachment: Bool {
-        !texts.lazy.filter(\.hasAttachment).isEmpty
-    }
-  
     var content: some View {
-        texts
-            .reduce(Text("")) { result, type in
-                switch type {
-                case let .text(string, container):
-                    return result + Text(AttributedString(
-                        string,
-                        attributes: container.toAttributeContainer()
-                    ))
-                case let .newLine(container):
-                    return result + Text(AttributedString(
-                        "\n",
-                        attributes: container.toAttributeContainer()
-                    ))
-                    
-                case let .attachment(_, _, _, styleContainer):
-                    return result + (
-                        Text(
-                            Image(uiImage: attachmentManager.sizeImage(
-                                key: type,
-                                styleContainer: styleContainer
-                            ))
-                        ).font(.system(size: 1))
-                    )
-                }
+        var result = Text("")
+        for type in texts {
+            let next: Text
+            switch type {
+            case let .text(string, container):
+                next = Text(AttributedString(
+                    string,
+                    attributes: container.toAttributeContainer()
+                ))
+            case let .newLine(container):
+                next = Text(AttributedString(
+                    "\n",
+                    attributes: container.toAttributeContainer()
+                ))
+            case let .attachment(_, _, _, styleContainer):
+                let imageText = Text(
+                    attachmentImage(for: type, styleContainer: styleContainer)
+                )
+                next = imageText.font(.system(size: 1))
             }
+            result = result + next
+        }
+        return result
     }
 
 }
 
-extension HTMLInline {
-    var textLine: TextLine {
-        let result: [HTMLStyleContainer.TextLineAttribute] = texts.compactMap {
-            guard case .text(_, let attributes) = $0, let textLine = attributes.textLine else { return nil }
-            return textLine
+private extension HTMLInline {
+    static func shouldLogInline() -> Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_INLINE_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_INLINE_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+    }
+
+    static func resolveTextLine(texts: [TextType]) -> TextLine {
+        var maxLineSpacing: CGFloat = 0
+        var maxVerticalPadding: CGFloat = 0
+
+        for text in texts {
+            guard case .text(_, let attributes) = text,
+                  let textLine = attributes.textLine else { continue }
+            maxLineSpacing = max(maxLineSpacing, textLine.lineSpacing)
+            if let verticalPadding = textLine.verticalPadding {
+                maxVerticalPadding = max(maxVerticalPadding, verticalPadding)
+            }
         }
 
         return TextLine(
-            lineSpacing: result.compactMap(\.lineSpacing).max() ?? 0,
-            verticalPadding: result.compactMap(\.verticalPadding).max() ?? 0
+            lineSpacing: maxLineSpacing,
+            verticalPadding: maxVerticalPadding
         )
     }
+
+    func attachmentImage(for type: TextType, styleContainer: HTMLStyleContainer) -> Image {
+#if os(macOS)
+        return Image(nsImage: attachmentManager.sizeImage(
+            key: type,
+            styleContainer: styleContainer
+        ))
+#else
+        let image = attachmentManager.sizeImage(
+            key: type,
+            styleContainer: styleContainer
+        )
+        return Image(uiImage: image.withRenderingMode(.alwaysOriginal))
+#endif
+    }
+
+    static func logLeadingWhitespace(texts: [TextType]) {
+        guard let first = texts.first else { return }
+        switch first {
+        case .newLine:
+            AttachmentDebugLogger.record("[Inline] leading newLine")
+        case let .text(string, _):
+            let leading = ASCIIWhitespace.trimLeading(string)
+            let trimmedCount = string.count - leading.count
+            if trimmedCount > 0 {
+                AttachmentDebugLogger.record("[Inline] leadingWhitespace count=\(trimmedCount) sample=\(String(string.prefix(min(24, string.count))))")
+            }
+        case .attachment:
+            break
+        }
+    }
+}
+
+extension HTMLInline {
 }
 
 extension HTMLInline: @preconcurrency Equatable {
@@ -101,4 +206,49 @@ private extension Array where Element == TextType {
         }
         return self
     }
+
+    func trimmingLeadingWhitespace() -> [Element] {
+        var result = self
+        var index = 0
+        while index < result.count {
+            switch result[index] {
+            case let .text(string, styleContainer):
+                let trimmed = ASCIIWhitespace.trimLeading(string)
+                if trimmed.isEmpty {
+                    result.remove(at: index)
+                    continue
+                }
+                if trimmed.count != string.count {
+                    result[index] = .text(String(trimmed), styleContainer: styleContainer)
+                }
+                return result
+            case .newLine:
+                result.remove(at: index)
+                continue
+            case .attachment:
+                return result
+            }
+        }
+        return result
+    }
+
+    func coalescingTextRuns() -> [Element] {
+        var result: [Element] = []
+        result.reserveCapacity(count)
+
+        for element in self {
+            switch element {
+            case let .text(string, styleContainer):
+                guard !string.isEmpty else { continue }
+                if let last = result.last, case let .text(existing, existingStyle) = last, existingStyle == styleContainer {
+                    result[result.count - 1] = .text(existing + string, styleContainer: existingStyle)
+                } else {
+                    result.append(.text(string, styleContainer: styleContainer))
+                }
+            default:
+                result.append(element)
+            }
+        }
+        return result
+    }
 }
diff --git a/Sources/SwiftUIHTML/View/HTMLNodeView.swift b/Sources/SwiftUIHTML/View/HTMLNodeView.swift
index 35d01d6..dad5728 100644
--- a/Sources/SwiftUIHTML/View/HTMLNodeView.swift
+++ b/Sources/SwiftUIHTML/View/HTMLNodeView.swift
@@ -13,12 +13,15 @@ public struct HTMLNodeView: View {
     }
     
     public var body: some View {
-        HTMLBlock(
-            element: node.toElement(
-                configuration: configuration,
-                with: styleContainer
-            )
+        let element = node.toElement(
+            configuration: configuration,
+            with: styleContainer
         )
+        return HTMLBlock(element: element)
+            .modifier(
+                configuration.attributeStyle
+                    .eraseToAnyLayoutModifier(attributes: element.attributes)
+            )
     }
 }
 
diff --git a/Sources/SwiftUIHTML/View/HTMLText.swift b/Sources/SwiftUIHTML/View/HTMLText.swift
index d33627d..40591d3 100644
--- a/Sources/SwiftUIHTML/View/HTMLText.swift
+++ b/Sources/SwiftUIHTML/View/HTMLText.swift
@@ -4,11 +4,13 @@ import SwiftUI
 
 public struct HTMLText: View {
     let text: String
+    let applyVerticalPadding: Bool
 
     @HTMLEnvironment(\.styleContainer) var styleContainer
 
-    public init(_ text: String) {
+    public init(_ text: String, applyVerticalPadding: Bool = true) {
         self.text = text
+        self.applyVerticalPadding = applyVerticalPadding
     }
 
     public var body: some View {
@@ -19,6 +21,6 @@ public struct HTMLText: View {
         .modifier(TextLineModifier(textLine: HTMLInline.TextLine(
             lineSpacing: styleContainer.textLine?.lineSpacing ?? .zero,
             verticalPadding: styleContainer.textLine?.verticalPadding ?? .zero
-        )))
+        ), applyTopPadding: applyVerticalPadding, applyBottomPadding: applyVerticalPadding))
     }
 }
diff --git a/Sources/SwiftUIHTML/View/HTMLTextLayout/HTMLTextLayout.swift b/Sources/SwiftUIHTML/View/HTMLTextLayout/HTMLTextLayout.swift
index c448205..88740bd 100644
--- a/Sources/SwiftUIHTML/View/HTMLTextLayout/HTMLTextLayout.swift
+++ b/Sources/SwiftUIHTML/View/HTMLTextLayout/HTMLTextLayout.swift
@@ -1,16 +1,32 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import SwiftUI
+#if canImport(os)
+import os
+#endif
 
 struct HTMLTextLayout: View {
-    var texts: [TextType]
+    let texts: [TextType]
+    let attachmentTexts: [TextType]
     
     @ObservedObject var attachmentManager: AttachmentManager
     @HTMLEnvironment(\._configuration) var configuration
+    private var shouldLog: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_LOGS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_LOGS")
+            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil
+            || NSClassFromString("XCTestCase") != nil
+    }
+#if canImport(os)
+    private static let logger = Logger(subsystem: "SwiftUIHTML", category: "HTMLTextLayout")
+#endif
 
     init(attachmentManager: AttachmentManager, texts: [TextType]) {
         self.texts = texts
+        self.attachmentTexts = texts.filter(\.hasAttachment)
         self.attachmentManager = attachmentManager
         attachmentManager.setTexts(texts)
+        logAttachmentDiagnostics()
     }
 
     var body: some View {
@@ -19,23 +35,26 @@ struct HTMLTextLayout: View {
                 .hidden()
                 .modifier(OnChangeViewModifier(of: proxy.size, initial: true) { _, newValue in
                     attachmentManager.setContainer(size: proxy.size)
+                    log("containerSize=\(newValue)")
                 })
-            ForEach(attachmentTexts, id: \.hashValue) { text in
+            ForEach(attachmentTexts, id: \.self) { text in
                 attachmentView(for: text)
             }
         }
-    }
-
-    private var attachmentTexts: [TextType] {
-        texts.filter(\.hasAttachment)
+        .coordinateSpace(name: "HTMLTextLayoutSpace")
     }
 
     @ViewBuilder
     private func attachmentView(for text: TextType) -> some View {
         if let info = extractAttachmentInfo(from: text) {
+            let offset = attachmentManager.offset(key: text)
             info.view
                 .modifier(LinkModifier(link: info.link))
-                .offset(attachmentManager.offset(key: text))
+                .offset(offset)
+                .onAppear {
+                    logAttachmentLayoutSummary(text: text, offset: offset)
+                }
+                .background(attachmentFrameReader(for: text, offset: offset))
                 .background(attachmentSizeReader(for: text, styleContainer: info.styleContainer))
         }
     }
@@ -58,7 +77,148 @@ struct HTMLTextLayout: View {
                         size: newValue,
                         styleContainer: styleContainer
                     )
+                    logAttachmentSize(text: text, size: newValue)
                 })
         }
     }
+
+    private func attachmentFrameReader(for text: TextType, offset: CGSize) -> some View {
+        GeometryReader { proxy in
+            Color.clear
+                .hidden()
+                .modifier(OnChangeViewModifier(of: proxy.frame(in: .named("HTMLTextLayoutSpace")), initial: true) { _, newValue in
+                    logAttachmentFrame(text: text, frame: newValue, offset: offset)
+                })
+        }
+    }
+
+    private func attachmentDebugInfo(for text: TextType) -> (id: AnyHashable, tag: String, attributes: [String: AttributeValue])? {
+        switch text {
+        case let .attachment(id, tag, attributes, _):
+            return (id, tag, attributes)
+        default:
+            return nil
+        }
+    }
+
+    private func logAttachmentDiagnostics() {
+        guard shouldLog else { return }
+        let total = attachmentTexts.count
+        let unique = Set(attachmentTexts).count
+        log("attachmentCount total=\(total) unique=\(unique)")
+        guard unique != total else { return }
+        var counts: [String: Int] = [:]
+        counts.reserveCapacity(total)
+        for text in attachmentTexts {
+            let key = attachmentSummary(for: text)
+            counts[key, default: 0] += 1
+        }
+        let duplicates = counts
+            .filter { $0.value > 1 }
+            .sorted { $0.value > $1.value }
+            .map { "\($0.key)x\($0.value)" }
+        if !duplicates.isEmpty {
+            log("attachmentDuplicates \(duplicates.joined(separator: " | "))")
+        }
+    }
+
+    private func attachmentSummary(for text: TextType) -> String {
+        guard let info = attachmentDebugInfo(for: text) else {
+            return "unknown"
+        }
+        let src = info.attributes["src"]?.string ?? "-"
+        let width = info.attributes["width"]?.string ?? "-"
+        let height = info.attributes["height"]?.string ?? "-"
+        return "id=\(info.id) tag=\(info.tag) src=\(src) w=\(width) h=\(height)"
+    }
+
+    private func log(_ message: @autoclosure () -> String) {
+        guard shouldLog else { return }
+        let rendered = message()
+        AttachmentDebugLogger.record("[HTMLTextLayout] \(rendered)")
+#if canImport(os)
+        if #available(iOS 14.0, macOS 11.0, *) {
+            HTMLTextLayout.logger.debug("\(rendered, privacy: .public)")
+        }
+#endif
+        NSLog("[SwiftUIHTML][HTMLTextLayout] %@", rendered)
+        print("[SwiftUIHTML][HTMLTextLayout] \(rendered)")
+    }
+
+    private func logAttachmentSize(text: TextType, size: CGSize) {
+        guard shouldLog else { return }
+        if let info = attachmentDebugInfo(for: text) {
+            let alt = info.attributes["alt"]?.string ?? "-"
+            let src = info.attributes["src"]?.string ?? "-"
+            let width = info.attributes["width"]?.string ?? "-"
+            let height = info.attributes["height"]?.string ?? "-"
+            log(
+                "attachmentSize id=\(info.id) tag=\(info.tag) size=\(size) alt=\(alt) src=\(src) w=\(width) h=\(height)"
+            )
+        } else {
+            log("attachmentSize size=\(size)")
+        }
+    }
+
+    private func logAttachmentFrame(text: TextType, frame: CGRect, offset: CGSize) {
+        guard shouldLog else { return }
+        if let info = attachmentDebugInfo(for: text) {
+            let alt = info.attributes["alt"]?.string ?? "-"
+            let src = info.attributes["src"]?.string ?? "-"
+            let width = info.attributes["width"]?.string ?? "-"
+            let height = info.attributes["height"]?.string ?? "-"
+            log(
+                "attachmentFrame id=\(info.id) tag=\(info.tag) frame=\(frame) offset=\(offset) alt=\(alt) src=\(src) w=\(width) h=\(height)"
+            )
+            if let expected = attachmentManager.frame(key: text) {
+                let renderedX = frame.origin.x + offset.width
+                let renderedY = frame.origin.y + offset.height
+                let deltaX = renderedX - expected.origin.x
+                let deltaY = renderedY - expected.origin.y
+                log(
+                    "attachmentFrameDelta id=\(info.id) tag=\(info.tag) rendered=(\(renderedX), \(renderedY)) actual=\(frame) expected=\(expected) delta=(\(deltaX), \(deltaY))"
+                )
+            }
+            if info.tag == "img",
+               let metrics = attachmentManager.lineMetrics(key: text) {
+                let renderedRect = CGRect(
+                    x: frame.origin.x + offset.width,
+                    y: frame.origin.y + offset.height,
+                    width: frame.size.width,
+                    height: frame.size.height
+                )
+                let baselineOrigin = metrics.lineOrigin
+                let lineRectOrigin = CGPoint(
+                    x: metrics.lineOrigin.x,
+                    y: metrics.lineOrigin.y - metrics.descent
+                )
+                let baselineRelative = CGRect(
+                    x: renderedRect.origin.x - baselineOrigin.x,
+                    y: renderedRect.origin.y - baselineOrigin.y,
+                    width: renderedRect.size.width,
+                    height: renderedRect.size.height
+                )
+                let lineRectRelative = CGRect(
+                    x: renderedRect.origin.x - lineRectOrigin.x,
+                    y: renderedRect.origin.y - lineRectOrigin.y,
+                    width: renderedRect.size.width,
+                    height: renderedRect.size.height
+                )
+                log(
+                    "attachmentLineRelative id=\(info.id) tag=\(info.tag) lineIndex=\(metrics.lineIndex) lineOrigin=\(metrics.lineOrigin) ascent=\(metrics.ascent) descent=\(metrics.descent) lineRect=\(metrics.lineRect) rendered=\(renderedRect) baselineRelative=\(baselineRelative) lineRectRelative=\(lineRectRelative)"
+                )
+            }
+        } else {
+            log("attachmentFrame frame=\(frame) offset=\(offset)")
+        }
+    }
+
+    private func logAttachmentLayoutSummary(text: TextType, offset: CGSize) {
+        guard shouldLog else { return }
+        guard let info = attachmentDebugInfo(for: text) else { return }
+        let src = info.attributes["src"]?.string ?? "-"
+        let width = info.attributes["width"]?.string ?? "-"
+        let height = info.attributes["height"]?.string ?? "-"
+        log("attachmentLayout id=\(info.id) tag=\(info.tag) src=\(src) w=\(width) h=\(height) offset=\(offset)")
+    }
 }
diff --git a/Sources/SwiftUIHTML/View/HTMLTextLayout/TextAttachment.swift b/Sources/SwiftUIHTML/View/HTMLTextLayout/TextAttachment.swift
index eca99fb..ca23e51 100644
--- a/Sources/SwiftUIHTML/View/HTMLTextLayout/TextAttachment.swift
+++ b/Sources/SwiftUIHTML/View/HTMLTextLayout/TextAttachment.swift
@@ -1,10 +1,15 @@
 //  Copyright © 2025 PRND. All rights reserved.
+import Foundation
+#if os(macOS)
+import AppKit
+#else
 import UIKit
+#endif
 
 final class TextAttachment: NSTextAttachment {
 
     let key: AnyHashable
-    let font: UIFont?
+    let font: PlatformFont?
     let textLine: HTMLStyleContainer.TextLineAttribute?
 
     init(
@@ -15,7 +20,7 @@ final class TextAttachment: NSTextAttachment {
         self.font = styleContainer.uiFont
         self.textLine = styleContainer.textLine
         super.init(data: nil, ofType: nil)
-        self.image = UIImage()
+        self.image = PlatformImage.manabiEmpty(size: .zero)
     }
 
     required init?(coder: NSCoder) {
@@ -32,44 +37,170 @@ final class TextAttachment: NSTextAttachment {
 
     func getAdjustedSize() -> CGSize {
         guard let font else { return bounds.size }
-        let targetHeight = round(CTFontGetBoundingBox(font).maxY)
+#if os(macOS)
+        if bounds.size.width <= 1 || bounds.size.height <= 1 {
+            return bounds.size
+        }
+        let targetHeight = round(max(font.manabiBoundingBoxMaxY, font.manabiLineHeight))
+#else
+        let targetHeight = round(font.manabiBoundingBoxMaxY)
+#endif
         var adjustedHeight = bounds.size.height
 
         switch textLine {
         case let .lineHeight(_, lineHeight):
+#if os(macOS)
+            if lineHeight > 0, bounds.size.height / lineHeight >= 1.6 {
+                adjustedHeight += targetHeight - font.manabiLineHeight
+            } else {
+                adjustedHeight += targetHeight - lineHeight
+            }
+#else
             adjustedHeight += targetHeight - lineHeight
+#endif
         case .lineSpacing, .none:
-            adjustedHeight += targetHeight - font.lineHeight
+            adjustedHeight += targetHeight - font.manabiLineHeight
         }
-        
-        return CGSize(
+
+        let finalHeight: CGFloat
+#if os(macOS)
+        finalHeight = max(bounds.size.height, targetHeight, adjustedHeight)
+#else
+        finalHeight = max(targetHeight, adjustedHeight)
+#endif
+        let final = CGSize(
             width: bounds.size.width,
-            height: max(targetHeight, adjustedHeight)
+            height: finalHeight
         )
+        if ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+            || NSClassFromString("XCTestCase") != nil {
+            AttachmentDebugLogger.record(
+                "[Attachment] size key=\(key) bounds=\(bounds.size) targetHeight=\(targetHeight) adjustedHeight=\(adjustedHeight) lineHeight=\(textLine?.lineHeight ?? -1) final=\(final)"
+            )
+        }
+        return final
     }
 
-    func getAdjustedOffset(point: CGPoint) -> CGPoint {
+    func getAdjustedOffset(point: CGPoint, lineHeightOverride: CGFloat? = nil) -> CGPoint {
         guard let font else { return point }
-        let fontHeight = font.ascender + font.descender
-
-        let boundHeight = bounds.size.height
-        let lineHeight = textLine?.lineHeight ?? fontHeight
+        if bounds.size.width <= 1 || bounds.size.height <= 1 {
+            return point
+        }
+        if isRubyAttachment {
+            let metrics = rubyMetrics()
+            let fontHeight = font.manabiFontHeight
+            let lineHeight = lineHeightOverride ?? textLine?.lineHeight ?? fontHeight
+            let ascent = metrics?.ascent ?? fontHeight
+            let descent = metrics?.descent ?? max(0, fontHeight - ascent)
+            let extraBelow: CGFloat
+            if let metrics {
+                switch metrics.position {
+                case .after: extraBelow = metrics.extra
+                case .before: extraBelow = 0
+                default: extraBelow = metrics.extra / 2
+                }
+            } else {
+                extraBelow = 0
+            }
+            let adjusted = CGPoint(x: point.x, y: point.y - extraBelow)
+            if ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS"] == "1"
+                || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+                || NSClassFromString("XCTestCase") != nil {
+                let rubyPosition = metrics.map { Int($0.position.rawValue) } ?? -1
+                AttachmentDebugLogger.record(
+                    "[Attachment][Ruby] offset key=\(key) point=\(point) boundsH=\(bounds.size.height) fontHeight=\(fontHeight) lineHeight=\(lineHeight) ascent=\(ascent) descent=\(descent) extra=\(metrics?.extra ?? -1) position=\(rubyPosition) extraBelow=\(extraBelow) adjusted=\(adjusted)"
+                )
+            }
+            return adjusted
+        }
+#if os(macOS)
+        let fontHeight = font.manabiFontHeight
+        let boundHeight = getAdjustedSize().height
+#else
+        let fontHeight = font.manabiFontHeight
+        let boundHeight = getAdjustedSize().height
+#endif
+        let lineHeight = lineHeightOverride ?? textLine?.lineHeight ?? fontHeight
+        let centerOffset = boundHeight / 2
+        let heightDelta = max(0, boundHeight - lineHeight)
+        let verticalOffset = centerOffset - heightDelta / 2
+        let adjusted = CGPoint(x: point.x, y: point.y - boundHeight + verticalOffset)
+        if ProcessInfo.processInfo.environment["SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS"] == "1"
+            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+            || NSClassFromString("XCTestCase") != nil {
+            AttachmentDebugLogger.record(
+                "[Attachment] offset key=\(key) point=\(point) boundsH=\(bounds.size.height) adjustedH=\(boundHeight) fontHeight=\(fontHeight) lineHeight=\(lineHeight) lineHeightOverride=\(lineHeightOverride ?? -1) verticalOffset=\(verticalOffset) adjusted=\(adjusted)"
+            )
+        }
+        return adjusted
+    }
 
-        var verticalOffset = (boundHeight - fontHeight) / 2
+}
 
-        if lineHeight < boundHeight {
-            verticalOffset -= (boundHeight - lineHeight) / 2
-        }
+extension TextAttachment {
+    var isRubyAttachment: Bool {
+        guard let textType = key.base as? TextType else { return false }
+        guard case let .attachment(_, tag, _, _) = textType else { return false }
+        return tag == "ruby"
+    }
 
-        return CGPoint(x: point.x, y: point.y - boundHeight + verticalOffset)
+    struct RubyMetrics {
+        let ascent: CGFloat
+        let descent: CGFloat
+        let extra: CGFloat
+        let position: CTRubyPosition
     }
 
+    func rubyMetrics() -> RubyMetrics? {
+        guard isRubyAttachment, let font else { return nil }
+        let ctFont = font.manabiCTFont
+        let baseAscent = CTFontGetAscent(ctFont)
+        let baseDescent = CTFontGetDescent(ctFont)
+        let baseLeading = CTFontGetLeading(ctFont)
+        let baseHeight = baseAscent + baseDescent + baseLeading
+        let extra = max(0, bounds.size.height - baseHeight)
+        let position = rubyPosition
+        let extraAbove: CGFloat
+        let extraBelow: CGFloat
+        switch position {
+        case .before:
+            extraAbove = extra
+            extraBelow = 0
+        case .after:
+            extraAbove = 0
+            extraBelow = extra
+        default:
+            extraAbove = extra / 2
+            extraBelow = extra / 2
+        }
+        return RubyMetrics(
+            ascent: baseAscent + extraAbove,
+            descent: baseDescent + extraBelow,
+            extra: extra,
+            position: position
+        )
+    }
 }
 
-private extension UIFont {
-    var fontHeight: CGFloat {
-        let ascent = CTFontGetAscent(self)
-        let descent = CTFontGetDescent(self)
-        return ascent + descent
+private extension TextAttachment {
+    var rubyPosition: CTRubyPosition {
+        guard let textType = key.base as? TextType else { return .before }
+        guard case let .attachment(_, _, attributes, _) = textType else { return .before }
+        let cssStyle = attributes["style"]?.cssStyle ?? .empty
+        let raw = attributes["ruby-position"]?.string ?? cssStyle["ruby-position"]?.string
+        switch raw?.lowercased() {
+        case "over": return .before
+        case "under": return .after
+        case "inter-character": return .interCharacter
+        case "intercharacter": return .interCharacter
+        case "alternate": return .before
+        case "alternate over": return .before
+        case "alternate under": return .after
+        case "after": return .after
+        case "before": return .before
+        case "inline": return .inline
+        default: return .before
+        }
     }
 }
diff --git a/Sources/SwiftUIHTML/View/HTMLView.swift b/Sources/SwiftUIHTML/View/HTMLView.swift
index a6eb9ec..7ced9ba 100644
--- a/Sources/SwiftUIHTML/View/HTMLView.swift
+++ b/Sources/SwiftUIHTML/View/HTMLView.swift
@@ -1,13 +1,45 @@
 //  Copyright © 2024 PRND. All rights reserved.
 import SwiftUI
+#if canImport(os)
+import os
+#endif
 
 
-public struct HTMLView: View, Equatable {
+public struct HTMLView: View {
     let html: String
 
     @HTMLEnvironment(\._configuration) var configuration
+    @HTMLEnvironment(\.styleContainer) var styleContainer
 
     let parser: () -> HTMLParserable
+    @State private var parsedNode: HTMLNode?
+    @State private var renderedElement: BlockElement?
+#if canImport(Foundation)
+    private final class HTMLNodeBox: NSObject {
+        let node: HTMLNode
+        init(_ node: HTMLNode) {
+            self.node = node
+        }
+    }
+
+    private static let parseCache: NSCache<NSString, HTMLNodeBox> = {
+        let cache = NSCache<NSString, HTMLNodeBox>()
+        cache.countLimit = 64
+        return cache
+    }()
+#endif
+#if DEBUG
+    @State private var didParse = false
+    @State private var debugChildCount = 0
+    private var shouldShowDebugOverlay: Bool {
+        ProcessInfo.processInfo.environment["SWIFTUIHTML_DEBUG_OVERLAY"] == "1"
+    }
+#endif
+#if canImport(os)
+    private static let signposter = OSSignposter(
+        logHandle: OSLog(subsystem: "SwiftUIHTML", category: "HTMLView")
+    )
+#endif
 
     public init(html: String, parser: @autoclosure @escaping () -> HTMLParserable) {
         self.html = html
@@ -15,15 +47,141 @@ public struct HTMLView: View, Equatable {
     }
 
     public var body: some View {
-        if !html.isEmpty {
-            HTMLNodeView(node: parser().parse(html: html))
+        Group {
+            if let renderedElement {
+                HTMLBlock(element: renderedElement)
+                    .modifier(
+                        configuration.attributeStyle
+                            .eraseToAnyLayoutModifier(attributes: renderedElement.attributes)
+                    )
+            } else if let parsedNode {
+                HTMLNodeView(node: parsedNode)
+            } else {
+                Color.clear
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .topLeading)
+        .background(
+            GeometryReader { proxy in
+                let size = proxy.size
+                Color.clear
+                    .hidden()
+                    .onAppear {
+                        if ProcessInfo.processInfo.environment["SWIFTUIHTML_LAYOUT_LOGS"] == "1"
+                            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_LAYOUT_LOGS")
+                            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+                            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil {
+                            AttachmentDebugLogger.record("[Layout][HTMLView] size=\(size)")
+                        }
+                    }
+                    .onChange(of: size) { newValue in
+                        if ProcessInfo.processInfo.environment["SWIFTUIHTML_LAYOUT_LOGS"] == "1"
+                            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_LAYOUT_LOGS")
+                            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+                            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil {
+                            AttachmentDebugLogger.record("[Layout][HTMLView] size=\(newValue)")
+                        }
+                    }
+            }
+        )
+        .background(
+            GeometryReader { proxy in
+                let frame = proxy.frame(in: .global)
+                Color.clear
+                    .hidden()
+                    .onAppear {
+                        if ProcessInfo.processInfo.environment["SWIFTUIHTML_LAYOUT_LOGS"] == "1"
+                            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_LAYOUT_LOGS")
+                            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+                            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil {
+                            AttachmentDebugLogger.record("[Layout][HTMLView] globalFrame=\(frame)")
+                        }
+                    }
+                    .onChange(of: frame) { newValue in
+                        if ProcessInfo.processInfo.environment["SWIFTUIHTML_LAYOUT_LOGS"] == "1"
+                            || UserDefaults.standard.bool(forKey: "SWIFTUIHTML_LAYOUT_LOGS")
+                            || ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+                            || ProcessInfo.processInfo.environment["XCTestBundlePath"] != nil {
+                            AttachmentDebugLogger.record("[Layout][HTMLView] globalFrame=\(newValue)")
+                        }
+                    }
+            }
+        )
+#if DEBUG
+        .overlay(alignment: .topLeading) {
+            if shouldShowDebugOverlay {
+                Text("\(didParse ? "HTMLView parsed" : "HTMLView pending") children=\(debugChildCount)")
+                    .font(.caption2)
+                    .foregroundColor(.secondary)
+            }
+        }
+#endif
+        .task(id: html) {
+            guard !html.isEmpty else {
+                parsedNode = nil
+                renderedElement = nil
+#if DEBUG
+                didParse = false
+#endif
+                return
+            }
+#if canImport(Foundation)
+            let cacheDisabled = ProcessInfo.processInfo.environment["SWIFTUIHTML_DISABLE_PARSE_CACHE"] == "1"
+            let parserInstance = parser()
+            let parserTypeName = String(describing: type(of: parserInstance))
+            let cacheKey = "\(parserTypeName)::\(html)" as NSString
+            if !cacheDisabled, let cached = Self.parseCache.object(forKey: cacheKey) {
+                parsedNode = cached.node
+#if DEBUG
+                didParse = true
+                debugChildCount = cached.node.children.count
+#endif
+                return
+            }
+#else
+            let parserInstance = parser()
+#endif
+#if canImport(os)
+            let shouldSignpost = ProcessInfo.processInfo.environment["SWIFTUIHTML_SIGNPOSTS"] == "1"
+            let signpostID = shouldSignpost ? Self.signposter.makeSignpostID() : OSSignpostID.invalid
+            var intervalState: OSSignpostIntervalState?
+            if shouldSignpost {
+                intervalState = Self.signposter.beginInterval("HTML parse", id: signpostID, "\(html.count) chars")
+            }
+#endif
+            AttachmentIDGenerator.reset()
+            let parsed = parserInstance.parse(html: html)
+            parsedNode = parsed
+            renderedElement = parsed.toElement(configuration: configuration, with: styleContainer)
+#if canImport(Foundation)
+            if !cacheDisabled {
+                Self.parseCache.setObject(HTMLNodeBox(parsed), forKey: cacheKey, cost: html.count)
+            }
+#endif
+#if DEBUG
+            didParse = true
+            debugChildCount = parsed.children.count
+#endif
+#if DEBUG
+            if let parsedNode {
+                print("# RESULT parsed tag=\(parsedNode.tag) children=\(parsedNode.children.count)")
+            } else {
+                print("# RESULT parsed nil")
+            }
+#endif
+#if canImport(os)
+            if let intervalState {
+                Self.signposter.endInterval("HTML parse", intervalState)
+            }
+#endif
+        }
+        .onChange(of: styleContainer) { _ in
+            guard let parsedNode else { return }
+            renderedElement = parsedNode.toElement(configuration: configuration, with: styleContainer)
+        }
+        .onChange(of: configuration.cacheKey()) { _ in
+            guard let parsedNode else { return }
+            renderedElement = parsedNode.toElement(configuration: configuration, with: styleContainer)
         }
     }
 }
-
-extension HTMLView {
-    nonisolated public static func == (lhs: Self, rhs: Self) -> Bool {
-        lhs.html == rhs.html
-    }
-}
-
diff --git a/Sources/SwiftUIHTML/ViewModifier/TextLineModifier.swift b/Sources/SwiftUIHTML/ViewModifier/TextLineModifier.swift
index f952720..71221c0 100644
--- a/Sources/SwiftUIHTML/ViewModifier/TextLineModifier.swift
+++ b/Sources/SwiftUIHTML/ViewModifier/TextLineModifier.swift
@@ -6,18 +6,31 @@ struct TextLineModifier: ViewModifier {
     typealias TextLine = HTMLInline.TextLine
     @HTMLEnvironment(\.styleContainer) var styleContainer
     let textLine: TextLine
+    let applyTopPadding: Bool
+    let applyBottomPadding: Bool
+
+    init(
+        textLine: TextLine,
+        applyTopPadding: Bool = true,
+        applyBottomPadding: Bool = true
+    ) {
+        self.textLine = textLine
+        self.applyTopPadding = applyTopPadding
+        self.applyBottomPadding = applyBottomPadding
+    }
 
     func body(content: Content) -> some View {
         content
             .lineSpacing(lineSpacing)
-            .padding(.vertical, verticalPadding)
+            .padding(.top, applyTopPadding ? verticalPadding : 0)
+            .padding(.bottom, applyBottomPadding ? verticalPadding : 0)
     }
 
     var lineSpacing: CGFloat {
-        max(textLine.lineSpacing, styleContainer.textLine?.lineSpacing ?? 0)
+        max(0, max(textLine.lineSpacing, styleContainer.textLine?.lineSpacing ?? 0))
     }
 
     var verticalPadding: CGFloat {
-        max(textLine.verticalPadding, styleContainer.textLine?.verticalPadding ?? 0)
+        max(0, max(textLine.verticalPadding, styleContainer.textLine?.verticalPadding ?? 0))
     }
 }
diff --git a/SwiftUIHTMLExample.xcodeproj/project.pbxproj b/SwiftUIHTMLExample.xcodeproj/project.pbxproj
index 47dbd12..8366d0a 100644
--- a/SwiftUIHTMLExample.xcodeproj/project.pbxproj
+++ b/SwiftUIHTMLExample.xcodeproj/project.pbxproj
@@ -7,11 +7,14 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		261846002DBF67F7001739B1 /* Fuzi in Frameworks */ = {isa = PBXBuildFile; productRef = 261845FF2DBF67F7001739B1 /* Fuzi */; };
+		261846002DBF67F7001739B1 /* SwiftSoup in Frameworks */ = {isa = PBXBuildFile; productRef = 261845FF2DBF67F7001739B1 /* SwiftSoup */; };
 		261CAB2B2DBB7BBF0015BD7E /* SnapshotTesting in Frameworks */ = {isa = PBXBuildFile; productRef = 261CAB2A2DBB7BBF0015BD7E /* SnapshotTesting */; };
-		261CAB2E2DBB7BCF0015BD7E /* Fuzi in Frameworks */ = {isa = PBXBuildFile; productRef = 261CAB2D2DBB7BCF0015BD7E /* Fuzi */; };
+		261CAB2E2DBB7BCF0015BD7E /* SwiftSoup in Frameworks */ = {isa = PBXBuildFile; productRef = 261CAB2D2DBB7BCF0015BD7E /* SwiftSoup */; };
 		26F6EF122DC1E8E400024B85 /* SwiftUIHTML in Frameworks */ = {isa = PBXBuildFile; productRef = 26F6EF112DC1E8E400024B85 /* SwiftUIHTML */; };
 		26F6EF142DC1E8F600024B85 /* SwiftUIHTML in Frameworks */ = {isa = PBXBuildFile; productRef = 26F6EF132DC1E8F600024B85 /* SwiftUIHTML */; };
+		27585C06A5564924A5E83908 /* SwiftUIHTML in Frameworks */ = {isa = PBXBuildFile; productRef = 26F6EF132DC1E8F600024B85 /* SwiftUIHTML */; };
+		2FFF49397FD849E7A06FC80A /* SnapshotTesting in Frameworks */ = {isa = PBXBuildFile; productRef = 261CAB2A2DBB7BBF0015BD7E /* SnapshotTesting */; };
+		48D828A9F4CE40D88A69C059 /* SwiftSoup in Frameworks */ = {isa = PBXBuildFile; productRef = 261CAB2D2DBB7BCF0015BD7E /* SwiftSoup */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXContainerItemProxy section */
@@ -25,10 +28,14 @@
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXFileReference section */
+		02EE68CE6E9340E5B60E57CF /* SwiftUIHTMLExampleMacOS.xctestplan */ = {isa = PBXFileReference; lastKnownFileType = text; path = SwiftUIHTMLExampleMacOS.xctestplan; sourceTree = "<group>"; };
 		261CA9C22DBB7ADD0015BD7E /* SwiftUIHTMLExample.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = SwiftUIHTMLExample.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		261CAB1C2DBB7B840015BD7E /* SwiftUIHTMLExampleTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = SwiftUIHTMLExampleTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 		269A4B682DC1F79200E54076 /* SwiftUIHTMLExample.xctestplan */ = {isa = PBXFileReference; lastKnownFileType = text; path = SwiftUIHTMLExample.xctestplan; sourceTree = "<group>"; };
 		26FC51D22DCB43E3005B4BD3 /* SwiftUIHTMLExample-Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist; path = "SwiftUIHTMLExample-Info.plist"; sourceTree = "<group>"; };
+		7B8C9D0E1F2031425364758E /* SwiftUIHTMLExampleMacOSUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = SwiftUIHTMLExampleMacOSUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		9A1B2C3D4E5F60718293A4BD /* SwiftUIHTMLExampleUITests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = SwiftUIHTMLExampleUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		E5E45B1DB81A46819201D9EB /* SwiftUIHTMLExampleMacOSTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = SwiftUIHTMLExampleMacOSTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
 
 /* Begin PBXFileSystemSynchronizedRootGroup section */
@@ -42,6 +49,21 @@
 			path = SwiftUIHTMLExampleTests;
 			sourceTree = "<group>";
 		};
+		37FE6D108A4A4185A8E85107 /* SwiftUIHTMLExampleMacOSTests */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = SwiftUIHTMLExampleMacOSTests;
+			sourceTree = "<group>";
+		};
+		7B8C9D0E1F2031425364758D /* SwiftUIHTMLExampleMacOSUITests */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = SwiftUIHTMLExampleMacOSUITests;
+			sourceTree = "<group>";
+		};
+		9A1B2C3D4E5F60718293A4BC /* SwiftUIHTMLExampleUITests */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = SwiftUIHTMLExampleUITests;
+			sourceTree = "<group>";
+		};
 /* End PBXFileSystemSynchronizedRootGroup section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -49,7 +71,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				261846002DBF67F7001739B1 /* Fuzi in Frameworks */,
+				261846002DBF67F7001739B1 /* SwiftSoup in Frameworks */,
 				26F6EF122DC1E8E400024B85 /* SwiftUIHTML in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -58,12 +80,36 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				261CAB2E2DBB7BCF0015BD7E /* Fuzi in Frameworks */,
+				261CAB2E2DBB7BCF0015BD7E /* SwiftSoup in Frameworks */,
 				26F6EF142DC1E8F600024B85 /* SwiftUIHTML in Frameworks */,
 				261CAB2B2DBB7BBF0015BD7E /* SnapshotTesting in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		7B8C9D0E1F2031425364758B /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		9A1B2C3D4E5F60718293A4BA /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		E2F57790BBD346D689B33974 /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				48D828A9F4CE40D88A69C059 /* SwiftSoup in Frameworks */,
+				27585C06A5564924A5E83908 /* SwiftUIHTML in Frameworks */,
+				2FFF49397FD849E7A06FC80A /* SnapshotTesting in Frameworks */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXFrameworksBuildPhase section */
 
 /* Begin PBXGroup section */
@@ -79,8 +125,12 @@
 			children = (
 				26FC51D22DCB43E3005B4BD3 /* SwiftUIHTMLExample-Info.plist */,
 				269A4B682DC1F79200E54076 /* SwiftUIHTMLExample.xctestplan */,
+				02EE68CE6E9340E5B60E57CF /* SwiftUIHTMLExampleMacOS.xctestplan */,
 				261CA9C42DBB7ADD0015BD7E /* Example */,
 				261CAB1D2DBB7B840015BD7E /* SwiftUIHTMLExampleTests */,
+				9A1B2C3D4E5F60718293A4BC /* SwiftUIHTMLExampleUITests */,
+				37FE6D108A4A4185A8E85107 /* SwiftUIHTMLExampleMacOSTests */,
+				7B8C9D0E1F2031425364758D /* SwiftUIHTMLExampleMacOSUITests */,
 				261CA9C32DBB7ADD0015BD7E /* Products */,
 				261845FE2DBF67F7001739B1 /* Frameworks */,
 			);
@@ -91,6 +141,9 @@
 			children = (
 				261CA9C22DBB7ADD0015BD7E /* SwiftUIHTMLExample.app */,
 				261CAB1C2DBB7B840015BD7E /* SwiftUIHTMLExampleTests.xctest */,
+				9A1B2C3D4E5F60718293A4BD /* SwiftUIHTMLExampleUITests.xctest */,
+				E5E45B1DB81A46819201D9EB /* SwiftUIHTMLExampleMacOSTests.xctest */,
+				7B8C9D0E1F2031425364758E /* SwiftUIHTMLExampleMacOSUITests.xctest */,
 			);
 			name = Products;
 			sourceTree = "<group>";
@@ -115,7 +168,7 @@
 			);
 			name = SwiftUIHTMLExample;
 			packageProductDependencies = (
-				261845FF2DBF67F7001739B1 /* Fuzi */,
+				261845FF2DBF67F7001739B1 /* SwiftSoup */,
 				26F6EF112DC1E8E400024B85 /* SwiftUIHTML */,
 			);
 			productName = SwiftUIHTML;
@@ -141,13 +194,85 @@
 			name = SwiftUIHTMLExampleTests;
 			packageProductDependencies = (
 				261CAB2A2DBB7BBF0015BD7E /* SnapshotTesting */,
-				261CAB2D2DBB7BCF0015BD7E /* Fuzi */,
+				261CAB2D2DBB7BCF0015BD7E /* SwiftSoup */,
 				26F6EF132DC1E8F600024B85 /* SwiftUIHTML */,
 			);
 			productName = SwiftUIHTMLTests;
 			productReference = 261CAB1C2DBB7B840015BD7E /* SwiftUIHTMLExampleTests.xctest */;
 			productType = "com.apple.product-type.bundle.unit-test";
 		};
+		7B8C9D0E1F20314253647586 /* SwiftUIHTMLExampleMacOSUITests */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 7B8C9D0E1F20314253647587 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleMacOSUITests" */;
+			buildPhases = (
+				7B8C9D0E1F2031425364758A /* Sources */,
+				7B8C9D0E1F2031425364758B /* Frameworks */,
+				7B8C9D0E1F2031425364758C /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+				7B8C9D0E1F2031425364758F /* PBXTargetDependency */,
+			);
+			fileSystemSynchronizedGroups = (
+				7B8C9D0E1F2031425364758D /* SwiftUIHTMLExampleMacOSUITests */,
+			);
+			name = SwiftUIHTMLExampleMacOSUITests;
+			packageProductDependencies = (
+			);
+			productName = SwiftUIHTMLExampleMacOSUITests;
+			productReference = 7B8C9D0E1F2031425364758E /* SwiftUIHTMLExampleMacOSUITests.xctest */;
+			productType = "com.apple.product-type.bundle.ui-testing";
+		};
+		8654A28F6ECF41C8B9CCED96 /* SwiftUIHTMLExampleMacOSTests */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 992017C20FAE49F19FEB0F43 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleMacOSTests" */;
+			buildPhases = (
+				B7531A2BADFF4DF2AB734195 /* Sources */,
+				E2F57790BBD346D689B33974 /* Frameworks */,
+				B44562C4FB84419EB6FFBA5E /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+				AE5B6A76B6A846F3899E6CB5 /* PBXTargetDependency */,
+			);
+			fileSystemSynchronizedGroups = (
+				37FE6D108A4A4185A8E85107 /* SwiftUIHTMLExampleMacOSTests */,
+			);
+			name = SwiftUIHTMLExampleMacOSTests;
+			packageProductDependencies = (
+				261CAB2A2DBB7BBF0015BD7E /* SnapshotTesting */,
+				261CAB2D2DBB7BCF0015BD7E /* SwiftSoup */,
+				26F6EF132DC1E8F600024B85 /* SwiftUIHTML */,
+			);
+			productName = SwiftUIHTMLExampleMacOSTests;
+			productReference = E5E45B1DB81A46819201D9EB /* SwiftUIHTMLExampleMacOSTests.xctest */;
+			productType = "com.apple.product-type.bundle.unit-test";
+		};
+		9A1B2C3D4E5F60718293A4B5 /* SwiftUIHTMLExampleUITests */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 9A1B2C3D4E5F60718293A4B6 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleUITests" */;
+			buildPhases = (
+				9A1B2C3D4E5F60718293A4B9 /* Sources */,
+				9A1B2C3D4E5F60718293A4BA /* Frameworks */,
+				9A1B2C3D4E5F60718293A4BB /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+				9A1B2C3D4E5F60718293A4BE /* PBXTargetDependency */,
+			);
+			fileSystemSynchronizedGroups = (
+				9A1B2C3D4E5F60718293A4BC /* SwiftUIHTMLExampleUITests */,
+			);
+			name = SwiftUIHTMLExampleUITests;
+			packageProductDependencies = (
+			);
+			productName = SwiftUIHTMLExampleUITests;
+			productReference = 9A1B2C3D4E5F60718293A4BD /* SwiftUIHTMLExampleUITests.xctest */;
+			productType = "com.apple.product-type.bundle.ui-testing";
+		};
 /* End PBXNativeTarget section */
 
 /* Begin PBXProject section */
@@ -165,6 +290,18 @@
 						CreatedOnToolsVersion = 16.2;
 						TestTargetID = 261CA9C12DBB7ADD0015BD7E;
 					};
+					7B8C9D0E1F20314253647586 = {
+						CreatedOnToolsVersion = 16.2;
+						TestTargetID = 261CA9C12DBB7ADD0015BD7E;
+					};
+					8654A28F6ECF41C8B9CCED96 = {
+						CreatedOnToolsVersion = 16.2;
+						TestTargetID = 261CA9C12DBB7ADD0015BD7E;
+					};
+					9A1B2C3D4E5F60718293A4B5 = {
+						CreatedOnToolsVersion = 16.2;
+						TestTargetID = 261CA9C12DBB7ADD0015BD7E;
+					};
 				};
 			};
 			buildConfigurationList = 261CA9BD2DBB7ADD0015BD7E /* Build configuration list for PBXProject "SwiftUIHTMLExample" */;
@@ -178,7 +315,7 @@
 			minimizedProjectReferenceProxies = 1;
 			packageReferences = (
 				261CAB292DBB7BBF0015BD7E /* XCRemoteSwiftPackageReference "swift-snapshot-testing" */,
-				261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "Fuzi" */,
+				261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "SwiftSoup" */,
 				26F6EF102DC1E8E400024B85 /* XCLocalSwiftPackageReference "../SwiftUIHTML" */,
 			);
 			preferredProjectObjectVersion = 77;
@@ -188,6 +325,9 @@
 			targets = (
 				261CA9C12DBB7ADD0015BD7E /* SwiftUIHTMLExample */,
 				261CAB1B2DBB7B840015BD7E /* SwiftUIHTMLExampleTests */,
+				8654A28F6ECF41C8B9CCED96 /* SwiftUIHTMLExampleMacOSTests */,
+				9A1B2C3D4E5F60718293A4B5 /* SwiftUIHTMLExampleUITests */,
+				7B8C9D0E1F20314253647586 /* SwiftUIHTMLExampleMacOSUITests */,
 			);
 		};
 /* End PBXProject section */
@@ -207,6 +347,27 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		7B8C9D0E1F2031425364758C /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		9A1B2C3D4E5F60718293A4BB /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		B44562C4FB84419EB6FFBA5E /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXResourcesBuildPhase section */
 
 /* Begin PBXSourcesBuildPhase section */
@@ -224,6 +385,27 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
+		7B8C9D0E1F2031425364758A /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		9A1B2C3D4E5F60718293A4B9 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		B7531A2BADFF4DF2AB734195 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXSourcesBuildPhase section */
 
 /* Begin PBXTargetDependency section */
@@ -232,6 +414,21 @@
 			target = 261CA9C12DBB7ADD0015BD7E /* SwiftUIHTMLExample */;
 			targetProxy = 261CAB202DBB7B840015BD7E /* PBXContainerItemProxy */;
 		};
+		7B8C9D0E1F2031425364758F /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 261CA9C12DBB7ADD0015BD7E /* SwiftUIHTMLExample */;
+			targetProxy = 261CAB202DBB7B840015BD7E /* PBXContainerItemProxy */;
+		};
+		9A1B2C3D4E5F60718293A4BE /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 261CA9C12DBB7ADD0015BD7E /* SwiftUIHTMLExample */;
+			targetProxy = 261CAB202DBB7B840015BD7E /* PBXContainerItemProxy */;
+		};
+		AE5B6A76B6A846F3899E6CB5 /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 261CA9C12DBB7ADD0015BD7E /* SwiftUIHTMLExample */;
+			targetProxy = 261CAB202DBB7B840015BD7E /* PBXContainerItemProxy */;
+		};
 /* End PBXTargetDependency section */
 
 /* Begin XCBuildConfiguration section */
@@ -354,12 +551,17 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				"CODE_SIGNING_ALLOWED[sdk=macosx*]" = NO;
+				"CODE_SIGNING_REQUIRED[sdk=macosx*]" = NO;
 				CODE_SIGN_ENTITLEMENTS = Example/SwiftUIHTMLExample.entitlements;
+				"CODE_SIGN_IDENTITY[sdk=macosx*]" = "";
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
 				DEVELOPMENT_ASSET_PATHS = "\"Example/Preview Content\"";
-				DEVELOPMENT_TEAM = ZLQVH78B5Q;
+				DEVELOPMENT_TEAM = 8Y769YTXHF;
+				"DEVELOPMENT_TEAM[sdk=macosx*]" = "";
 				ENABLE_HARDENED_RUNTIME = YES;
+				"ENABLE_HARDENED_RUNTIME[sdk=macosx*]" = NO;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = "SwiftUIHTMLExample-Info.plist";
@@ -381,7 +583,7 @@
 				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTML;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = auto;
-				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx";
 				SUPPORTS_MACCATALYST = NO;
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;
@@ -395,12 +597,17 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				"CODE_SIGNING_ALLOWED[sdk=macosx*]" = NO;
+				"CODE_SIGNING_REQUIRED[sdk=macosx*]" = NO;
 				CODE_SIGN_ENTITLEMENTS = Example/SwiftUIHTMLExample.entitlements;
+				"CODE_SIGN_IDENTITY[sdk=macosx*]" = "";
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
 				DEVELOPMENT_ASSET_PATHS = "\"Example/Preview Content\"";
-				DEVELOPMENT_TEAM = ZLQVH78B5Q;
+				DEVELOPMENT_TEAM = 8Y769YTXHF;
+				"DEVELOPMENT_TEAM[sdk=macosx*]" = "";
 				ENABLE_HARDENED_RUNTIME = YES;
+				"ENABLE_HARDENED_RUNTIME[sdk=macosx*]" = NO;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = "SwiftUIHTMLExample-Info.plist";
@@ -422,7 +629,7 @@
 				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTML;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = auto;
-				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx";
 				SUPPORTS_MACCATALYST = NO;
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;
@@ -472,6 +679,138 @@
 			};
 			name = Release;
 		};
+		5BA626ACB55042B69251B76F /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGNING_ALLOWED = NO;
+				CODE_SIGNING_REQUIRED = NO;
+				CODE_SIGN_IDENTITY = "";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = "";
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 15.2;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLMacOSTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = macosx;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/SwiftUIHTMLExample.app/Contents/MacOS/SwiftUIHTMLExample";
+			};
+			name = Debug;
+		};
+		7B8C9D0E1F20314253647588 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CODE_SIGNING_ALLOWED = NO;
+				CODE_SIGNING_REQUIRED = NO;
+				CODE_SIGN_IDENTITY = "";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = "";
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 15.2;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLMacOSUITests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = macosx;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TEST_TARGET_NAME = SwiftUIHTMLExample;
+				UITargetAppPath = "$(BUILT_PRODUCTS_DIR)/SwiftUIHTMLExample.app";
+			};
+			name = Debug;
+		};
+		7B8C9D0E1F20314253647589 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CODE_SIGNING_ALLOWED = NO;
+				CODE_SIGNING_REQUIRED = NO;
+				CODE_SIGN_IDENTITY = "";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = "";
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 15.2;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLMacOSUITests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = macosx;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TEST_TARGET_NAME = SwiftUIHTMLExample;
+				UITargetAppPath = "$(BUILT_PRODUCTS_DIR)/SwiftUIHTMLExample.app";
+				VALIDATE_PRODUCT = YES;
+			};
+			name = Release;
+		};
+		9A1B2C3D4E5F60718293A4B7 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = ZLQVH78B5Q;
+				GENERATE_INFOPLIST_FILE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 16;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLUITests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = iphoneos;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+				TEST_TARGET_NAME = SwiftUIHTMLExample;
+			};
+			name = Debug;
+		};
+		9A1B2C3D4E5F60718293A4B8 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = ZLQVH78B5Q;
+				GENERATE_INFOPLIST_FILE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 16;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLUITests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = iphoneos;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TARGETED_DEVICE_FAMILY = "1,2";
+				TEST_TARGET_NAME = SwiftUIHTMLExample;
+				VALIDATE_PRODUCT = YES;
+			};
+			name = Release;
+		};
+		C08F0646B2E948B1A46BAB72 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGNING_ALLOWED = NO;
+				CODE_SIGNING_REQUIRED = NO;
+				CODE_SIGN_IDENTITY = "";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = "";
+				GENERATE_INFOPLIST_FILE = YES;
+				MACOSX_DEPLOYMENT_TARGET = 15.2;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = prnd.co.kr.SwiftUIHTMLMacOSTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = macosx;
+				SUPPORTED_PLATFORMS = macosx;
+				SWIFT_EMIT_LOC_STRINGS = NO;
+				SWIFT_VERSION = 5.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/SwiftUIHTMLExample.app/Contents/MacOS/SwiftUIHTMLExample";
+			};
+			name = Release;
+		};
 /* End XCBuildConfiguration section */
 
 /* Begin XCConfigurationList section */
@@ -502,6 +841,33 @@
 			defaultConfigurationIsVisible = 0;
 			defaultConfigurationName = Release;
 		};
+		7B8C9D0E1F20314253647587 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleMacOSUITests" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				7B8C9D0E1F20314253647588 /* Debug */,
+				7B8C9D0E1F20314253647589 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+		992017C20FAE49F19FEB0F43 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleMacOSTests" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				5BA626ACB55042B69251B76F /* Debug */,
+				C08F0646B2E948B1A46BAB72 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+		9A1B2C3D4E5F60718293A4B6 /* Build configuration list for PBXNativeTarget "SwiftUIHTMLExampleUITests" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				9A1B2C3D4E5F60718293A4B7 /* Debug */,
+				9A1B2C3D4E5F60718293A4B8 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
 /* End XCConfigurationList section */
 
 /* Begin XCLocalSwiftPackageReference section */
@@ -520,31 +886,31 @@
 				minimumVersion = 1.18.3;
 			};
 		};
-		261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "Fuzi" */ = {
+		261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "SwiftSoup" */ = {
 			isa = XCRemoteSwiftPackageReference;
-			repositoryURL = "https://github.com/rinsuki/Fuzi";
+			repositoryURL = "https://github.com/scinfu/SwiftSoup.git";
 			requirement = {
-				branch = "rename-to-parse-from-init";
+				branch = master;
 				kind = branch;
 			};
 		};
 /* End XCRemoteSwiftPackageReference section */
 
 /* Begin XCSwiftPackageProductDependency section */
-		261845FF2DBF67F7001739B1 /* Fuzi */ = {
+		261845FF2DBF67F7001739B1 /* SwiftSoup */ = {
 			isa = XCSwiftPackageProductDependency;
-			package = 261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "Fuzi" */;
-			productName = Fuzi;
+			package = 261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "SwiftSoup" */;
+			productName = SwiftSoup;
 		};
 		261CAB2A2DBB7BBF0015BD7E /* SnapshotTesting */ = {
 			isa = XCSwiftPackageProductDependency;
 			package = 261CAB292DBB7BBF0015BD7E /* XCRemoteSwiftPackageReference "swift-snapshot-testing" */;
 			productName = SnapshotTesting;
 		};
-		261CAB2D2DBB7BCF0015BD7E /* Fuzi */ = {
+		261CAB2D2DBB7BCF0015BD7E /* SwiftSoup */ = {
 			isa = XCSwiftPackageProductDependency;
-			package = 261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "Fuzi" */;
-			productName = Fuzi;
+			package = 261CAB2C2DBB7BCF0015BD7E /* XCRemoteSwiftPackageReference "SwiftSoup" */;
+			productName = SwiftSoup;
 		};
 		26F6EF112DC1E8E400024B85 /* SwiftUIHTML */ = {
 			isa = XCSwiftPackageProductDependency;
diff --git a/SwiftUIHTMLExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved b/SwiftUIHTMLExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
index 1d4bf35..a867924 100644
--- a/SwiftUIHTMLExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
+++ b/SwiftUIHTMLExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
@@ -1,13 +1,31 @@
 {
-  "originHash" : "877a82bf992e98fa11e61d7d05c9ce59144ea67c2e5f8a5a7447b25211cdfa6b",
+  "originHash" : "61e1deeb353cfdfd6e5a461e093cf455086c7d1e74a41d702b8900e9c06812d6",
   "pins" : [
     {
-      "identity" : "fuzi",
+      "identity" : "lrucache",
       "kind" : "remoteSourceControl",
-      "location" : "https://github.com/rinsuki/Fuzi",
+      "location" : "https://github.com/nicklockwood/LRUCache.git",
       "state" : {
-        "branch" : "rename-to-parse-from-init",
-        "revision" : "4092585ab3eea9de6c2a92024d3ab5ec3bfc4785"
+        "revision" : "cb5b2bd0da83ad29c0bec762d39f41c8ad0eaf3e",
+        "version" : "1.2.1"
+      }
+    },
+    {
+      "identity" : "nuke",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/kean/Nuke.git",
+      "state" : {
+        "branch" : "main",
+        "revision" : "88849b71eda654a2f4326801d96cc3b01d0d7efa"
+      }
+    },
+    {
+      "identity" : "swift-atomics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-atomics.git",
+      "state" : {
+        "revision" : "b601256eab081c0f92f059e12818ac1d4f178ff7",
+        "version" : "1.3.0"
       }
     },
     {
@@ -37,6 +55,15 @@
         "version" : "601.0.1"
       }
     },
+    {
+      "identity" : "swiftsoup",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/scinfu/SwiftSoup.git",
+      "state" : {
+        "branch" : "master",
+        "revision" : "cd950c96d1d2ae53068828f1f394178afbc4d83a"
+      }
+    },
     {
       "identity" : "xctest-dynamic-overlay",
       "kind" : "remoteSourceControl",
diff --git a/SwiftUIHTMLExample.xcodeproj/xcshareddata/xcschemes/SwiftUIHTMLExampleMacOS.xcscheme b/SwiftUIHTMLExample.xcodeproj/xcshareddata/xcschemes/SwiftUIHTMLExampleMacOS.xcscheme
new file mode 100644
index 0000000..402c9c8
--- /dev/null
+++ b/SwiftUIHTMLExample.xcodeproj/xcshareddata/xcschemes/SwiftUIHTMLExampleMacOS.xcscheme
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1620"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "261CA9C12DBB7ADD0015BD7E"
+               BuildableName = "SwiftUIHTMLExample.app"
+               BlueprintName = "SwiftUIHTMLExample"
+               ReferencedContainer = "container:SwiftUIHTMLExample.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:SwiftUIHTMLExampleMacOS.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
+      <Testables>
+         <TestableReference
+            skipped = "NO"
+            parallelizable = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "8654A28F6ECF41C8B9CCED96"
+               BuildableName = "SwiftUIHTMLExampleMacOSTests.xctest"
+               BlueprintName = "SwiftUIHTMLExampleMacOSTests"
+               ReferencedContainer = "container:SwiftUIHTMLExample.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "261CA9C12DBB7ADD0015BD7E"
+            BuildableName = "SwiftUIHTMLExample.app"
+            BlueprintName = "SwiftUIHTMLExample"
+            ReferencedContainer = "container:SwiftUIHTMLExample.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "261CA9C12DBB7ADD0015BD7E"
+            BuildableName = "SwiftUIHTMLExample.app"
+            BlueprintName = "SwiftUIHTMLExample"
+            ReferencedContainer = "container:SwiftUIHTMLExample.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/SwiftUIHTMLExample.xctestplan b/SwiftUIHTMLExample.xctestplan
index 514f0c6..878263f 100644
--- a/SwiftUIHTMLExample.xctestplan
+++ b/SwiftUIHTMLExample.xctestplan
@@ -23,6 +23,14 @@
         "identifier" : "261CAB1B2DBB7B840015BD7E",
         "name" : "SwiftUIHTMLExampleTests"
       }
+    },
+    {
+      "parallelizable" : true,
+      "target" : {
+        "containerPath" : "container:SwiftUIHTMLExample.xcodeproj",
+        "identifier" : "9A1B2C3D4E5F60718293A4B5",
+        "name" : "SwiftUIHTMLExampleUITests"
+      }
     }
   ],
   "version" : 1
diff --git a/SwiftUIHTMLExampleMacOS.xctestplan b/SwiftUIHTMLExampleMacOS.xctestplan
new file mode 100644
index 0000000..a99e0b8
--- /dev/null
+++ b/SwiftUIHTMLExampleMacOS.xctestplan
@@ -0,0 +1,37 @@
+{
+  "configurations" : [
+    {
+      "id" : "BBD6E8F9-5B05-4CDE-8A67-24C5D8D8F836",
+      "name" : "Test Scheme Action",
+      "options" : {
+
+      }
+    }
+  ],
+  "defaultOptions" : {
+    "targetForVariableExpansion" : {
+      "containerPath" : "container:SwiftUIHTMLExample.xcodeproj",
+      "identifier" : "261CA9C12DBB7ADD0015BD7E",
+      "name" : "SwiftUIHTMLExample"
+    }
+  },
+  "testTargets" : [
+    {
+      "parallelizable" : true,
+      "target" : {
+        "containerPath" : "container:SwiftUIHTMLExample.xcodeproj",
+        "identifier" : "8654A28F6ECF41C8B9CCED96",
+        "name" : "SwiftUIHTMLExampleMacOSTests"
+      }
+    },
+    {
+      "parallelizable" : true,
+      "target" : {
+        "containerPath" : "container:SwiftUIHTMLExample.xcodeproj",
+        "identifier" : "7B8C9D0E1F20314253647586",
+        "name" : "SwiftUIHTMLExampleMacOSUITests"
+      }
+    }
+  ],
+  "version" : 1
+}
diff --git a/SwiftUIHTMLExampleMacOSTests/MacViewSnapshotTester.swift b/SwiftUIHTMLExampleMacOSTests/MacViewSnapshotTester.swift
new file mode 100644
index 0000000..a7ed40c
--- /dev/null
+++ b/SwiftUIHTMLExampleMacOSTests/MacViewSnapshotTester.swift
@@ -0,0 +1,1310 @@
+//  Copyright © 2026 PRND. All rights reserved.
+#if os(macOS)
+import AppKit
+import CryptoKit
+import SwiftUI
+@_spi(Internals) import SnapshotTesting
+import Vision
+import XCTest
+import QuartzCore
+
+@testable import SwiftUIHTML
+
+/// Utility class for rendering SwiftUI views in AppKit and generating snapshots.
+class MacViewSnapshotTester {
+    private static let diagnosticLogDirectory: URL = {
+        URL(fileURLWithPath: "/tmp/swiftuihtml-macos-diag", isDirectory: true)
+    }()
+    private static let artifactsDirectory: URL = {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyyMMdd-HHmmss"
+        let stamp = formatter.string(from: Date())
+        return URL(fileURLWithPath: "/tmp/swiftuihtml-macos-artifacts-\(stamp)", isDirectory: true)
+    }()
+
+    static func iosSnapshotDirectory(filePath: StaticString = #filePath) -> String {
+        let url = URL(fileURLWithPath: "\(filePath)", isDirectory: false)
+        let root = url.deletingLastPathComponent().deletingLastPathComponent()
+        return root
+            .appendingPathComponent("SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests")
+            .path
+    }
+
+    private static func sanitizePathComponent(_ string: String) -> String {
+        let sanitized = string.replacingOccurrences(
+            of: "\\W+",
+            with: "-",
+            options: .regularExpression
+        )
+        return sanitized.replacingOccurrences(
+            of: "^-|-$",
+            with: "",
+            options: .regularExpression
+        )
+    }
+
+    private static func baselineExists(
+        snapshotDirectory: String?,
+        testName: String,
+        name: String?
+    ) -> Bool {
+        guard let snapshotDirectory else { return false }
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let url = URL(fileURLWithPath: snapshotDirectory, isDirectory: true)
+            .appendingPathComponent("\(safeTestName).\(identifier)")
+            .appendingPathExtension("png")
+        return FileManager.default.fileExists(atPath: url.path)
+    }
+
+    private static func resolveBaselineTestName(
+        snapshotDirectory: String?,
+        testName: String,
+        name: String?
+    ) -> String {
+        guard let snapshotDirectory else { return testName }
+        let normalized = normalizeTestName(testName)
+        if normalized.hasSuffix("MacOS") {
+            let trimmed = String(normalized.dropLast("MacOS".count))
+            if baselineExists(snapshotDirectory: snapshotDirectory, testName: trimmed, name: name) {
+                return trimmed
+            }
+        }
+        if normalized.hasSuffix("macOS") {
+            let trimmed = String(normalized.dropLast("macOS".count))
+            if baselineExists(snapshotDirectory: snapshotDirectory, testName: trimmed, name: name) {
+                return trimmed
+            }
+        }
+        if baselineExists(snapshotDirectory: snapshotDirectory, testName: normalized, name: name) {
+            return normalized
+        }
+        return normalized
+    }
+
+    private static func normalizeTestName(_ raw: String) -> String {
+        if let paren = raw.firstIndex(of: "(") {
+            return String(raw[..<paren])
+        }
+        return raw
+    }
+
+    private static func referencePixelSize(
+        snapshotDirectory: String?,
+        testName: String,
+        name: String?
+    ) -> CGSize? {
+        guard let snapshotDirectory else { return nil }
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let url = URL(fileURLWithPath: snapshotDirectory, isDirectory: true)
+            .appendingPathComponent("\(safeTestName).\(identifier)")
+            .appendingPathExtension("png")
+        if !FileManager.default.fileExists(atPath: url.path) {
+            AttachmentDebugLogger.record("[Snapshot] baseline missing \(url.path)")
+            return nil
+        }
+        guard
+            let image = NSImage(contentsOf: url),
+            let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil)
+        else {
+            AttachmentDebugLogger.record("[Snapshot] baseline load failed \(url.path)")
+            return nil
+        }
+        AttachmentDebugLogger.record("[Snapshot] baseline found \(url.lastPathComponent) px=\(cgImage.width)x\(cgImage.height)")
+        return CGSize(width: cgImage.width, height: cgImage.height)
+    }
+
+    private static func makeSnapshotImage(
+        of view: NSView,
+        size: CGSize,
+        scale: CGFloat
+    ) -> NSImage {
+        let pixelsWide = max(1, Int(size.width * scale))
+        let pixelsHigh = max(1, Int(size.height * scale))
+        if let rep = NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: pixelsWide,
+            pixelsHigh: pixelsHigh,
+            bitsPerSample: 8,
+            samplesPerPixel: 4,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bytesPerRow: 0,
+            bitsPerPixel: 0
+        ) {
+            rep.size = size
+            view.cacheDisplay(in: CGRect(origin: .zero, size: size), to: rep)
+            let image = NSImage(size: size)
+            image.addRepresentation(rep)
+            AttachmentDebugLogger.record("[Snapshot] render=cacheDisplay px=\(pixelsWide)x\(pixelsHigh)")
+            return image
+        }
+
+        if let layer = view.layer {
+            let rep = NSBitmapImageRep(
+                bitmapDataPlanes: nil,
+                pixelsWide: pixelsWide,
+                pixelsHigh: pixelsHigh,
+                bitsPerSample: 8,
+                samplesPerPixel: 4,
+                hasAlpha: true,
+                isPlanar: false,
+                colorSpaceName: .deviceRGB,
+                bytesPerRow: 0,
+                bitsPerPixel: 0
+            )
+            rep?.size = size
+            let image = NSImage(size: size)
+            if let rep, let context = NSGraphicsContext(bitmapImageRep: rep) {
+                NSGraphicsContext.saveGraphicsState()
+                NSGraphicsContext.current = context
+                context.cgContext.scaleBy(x: scale, y: scale)
+                context.cgContext.translateBy(x: 0, y: size.height)
+                context.cgContext.scaleBy(x: 1, y: -1)
+                layer.render(in: context.cgContext)
+                NSGraphicsContext.restoreGraphicsState()
+                image.addRepresentation(rep)
+                AttachmentDebugLogger.record("[Snapshot] render=layerRender px=\(pixelsWide)x\(pixelsHigh)")
+            }
+            return image
+        }
+
+        let fallback = NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: pixelsWide,
+            pixelsHigh: pixelsHigh,
+            bitsPerSample: 8,
+            samplesPerPixel: 4,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bytesPerRow: 0,
+            bitsPerPixel: 0
+        )
+        fallback?.size = size
+        let image = NSImage(size: size)
+        if let fallback {
+            view.cacheDisplay(in: CGRect(origin: .zero, size: size), to: fallback)
+            image.addRepresentation(fallback)
+            AttachmentDebugLogger.record("[Snapshot] render=fallbackCache px=\(pixelsWide)x\(pixelsHigh)")
+        }
+        return image
+    }
+
+    @MainActor
+    @available(macOS 13.0, *)
+    private static func makeSnapshotImageUsingRenderer<V: View>(
+        of view: V,
+        size: CGSize,
+        scale: CGFloat
+    ) -> NSImage? {
+        let renderer = ImageRenderer(content: view)
+        renderer.proposedSize = ProposedViewSize(width: size.width, height: size.height)
+        renderer.scale = scale
+        renderer.isOpaque = true
+        if let image = renderer.nsImage {
+            let pixelsWide = max(1, Int(size.width * scale))
+            let pixelsHigh = max(1, Int(size.height * scale))
+            AttachmentDebugLogger.record("[Snapshot] render=imageRenderer px=\(pixelsWide)x\(pixelsHigh)")
+            return image
+        }
+        return nil
+    }
+
+    private static func renderPDFImage(of view: NSView, size: CGSize) -> NSImage? {
+        let pdfData = view.dataWithPDF(inside: view.bounds)
+        guard let pdfImage = NSPDFImageRep(data: pdfData) else { return nil }
+        pdfImage.size = size
+        let image = NSImage(size: size)
+        image.addRepresentation(pdfImage)
+        return image
+    }
+
+    private static func logPaddingDiagnostics(
+        image: NSImage,
+        testName: String,
+        name: String?,
+        snapshotDirectory: String?,
+        baselineTestName: String
+    ) {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let baseImage = loadBaselineImage(
+            snapshotDirectory: snapshotDirectory,
+            testName: sanitizePathComponent(baselineTestName),
+            identifier: identifier
+        )
+        if let newMetrics = nonWhiteMetrics(for: image) {
+            if let baseImage, let baseMetrics = nonWhiteMetrics(for: baseImage) {
+                let deltaTop = newMetrics.topPadding - baseMetrics.topPadding
+                let deltaBottom = newMetrics.bottomPadding - baseMetrics.bottomPadding
+                AttachmentDebugLogger.record(
+                    "[Padding] test=\(safeTestName).\(identifier) newTop=\(newMetrics.topPadding) newBottom=\(newMetrics.bottomPadding) baseTop=\(baseMetrics.topPadding) baseBottom=\(baseMetrics.bottomPadding) deltaTop=\(deltaTop) deltaBottom=\(deltaBottom) newNonWhiteRatio=\(newMetrics.nonWhiteRatio) baseNonWhiteRatio=\(baseMetrics.nonWhiteRatio)"
+                )
+            } else {
+                AttachmentDebugLogger.record(
+                    "[Padding] test=\(safeTestName).\(identifier) newTop=\(newMetrics.topPadding) newBottom=\(newMetrics.bottomPadding) newNonWhiteRatio=\(newMetrics.nonWhiteRatio) baselineMissing"
+                )
+            }
+        }
+    }
+
+    private struct NonWhiteMetrics {
+        let topPadding: Int
+        let bottomPadding: Int
+        let nonWhiteRatio: Double
+    }
+
+    private static func nonWhiteMetrics(for image: NSImage) -> NonWhiteMetrics? {
+        let size = image.size
+        let width = max(1, Int(size.width))
+        let height = max(1, Int(size.height))
+        let bytesPerPixel = 4
+        let bytesPerRow = width * bytesPerPixel
+        guard let rep = NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: width,
+            pixelsHigh: height,
+            bitsPerSample: 8,
+            samplesPerPixel: bytesPerPixel,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bytesPerRow: bytesPerRow,
+            bitsPerPixel: 0
+        ) else {
+            return nil
+        }
+        rep.size = size
+        NSGraphicsContext.saveGraphicsState()
+        if let context = NSGraphicsContext(bitmapImageRep: rep) {
+            NSGraphicsContext.current = context
+            context.cgContext.setFillColor(NSColor.white.cgColor)
+            context.cgContext.fill(CGRect(origin: .zero, size: size))
+            image.draw(in: CGRect(origin: .zero, size: size))
+        }
+        NSGraphicsContext.restoreGraphicsState()
+        guard let bytes = rep.bitmapData else { return nil }
+        let dataLength = bytesPerRow * height
+        let threshold: UInt8 = 245
+        var top = height
+        var bottom = 0
+        var nonWhiteCount = 0
+        let total = width * height
+        for y in 0..<height {
+            var rowHasContent = false
+            let rowStart = y * bytesPerRow
+            for x in 0..<width {
+                let offset = rowStart + x * bytesPerPixel
+                if offset + 3 >= dataLength { break }
+                let r = bytes[offset]
+                let g = bytes[offset + 1]
+                let b = bytes[offset + 2]
+                let isNonWhite = (r < threshold || g < threshold || b < threshold)
+                if isNonWhite {
+                    nonWhiteCount += 1
+                    rowHasContent = true
+                }
+            }
+            if rowHasContent {
+                top = min(top, y)
+                bottom = max(bottom, y)
+            }
+        }
+        if top == height {
+            return NonWhiteMetrics(topPadding: height, bottomPadding: 0, nonWhiteRatio: 0)
+        }
+        let topPadding = top
+        let bottomPadding = max(0, height - 1 - bottom)
+        let ratio = total > 0 ? Double(nonWhiteCount) / Double(total) : 0
+        return NonWhiteMetrics(topPadding: topPadding, bottomPadding: bottomPadding, nonWhiteRatio: ratio)
+    }
+
+    private struct TrimMetrics {
+        let width: Int
+        let height: Int
+        let x: Int
+        let y: Int
+        let imageWidth: Int
+        let imageHeight: Int
+        var bottom: Int { max(0, imageHeight - height - y) }
+    }
+
+    private static func logTrimDiagnostics(
+        image: NSImage,
+        testName: String,
+        name: String?,
+        snapshotDirectory: String?,
+        baselineTestName: String
+    ) {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        guard let pngData = pngData(from: image) else { return }
+        let tmpURL = URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent("swiftuihtml-macos-trim-\(safeTestName)-\(identifier).png")
+        do {
+            try pngData.write(to: tmpURL)
+        } catch {
+            AttachmentDebugLogger.record("[Trim] write failed \(error.localizedDescription)")
+            return
+        }
+
+        let newTrim = runTrimDiagnostics(
+            imageURL: tmpURL,
+            label: "new",
+            testName: safeTestName,
+            identifier: identifier
+        )
+        if let snapshotDirectory {
+            let baseURL = URL(fileURLWithPath: snapshotDirectory, isDirectory: true)
+                .appendingPathComponent("\(sanitizePathComponent(baselineTestName)).\(identifier)")
+                .appendingPathExtension("png")
+            if FileManager.default.fileExists(atPath: baseURL.path) {
+                let baseTrim = runTrimDiagnostics(
+                    imageURL: baseURL,
+                    label: "base",
+                    testName: safeTestName,
+                    identifier: identifier
+                )
+                if let newTrim, let baseTrim {
+                    let deltaTop = newTrim.y - baseTrim.y
+                    let deltaBottom = newTrim.bottom - baseTrim.bottom
+                    AttachmentDebugLogger.record(
+                        "[TrimDelta] test=\(safeTestName).\(identifier) deltaTop=\(deltaTop) deltaBottom=\(deltaBottom)"
+                    )
+                }
+            } else {
+                AttachmentDebugLogger.record("[Trim] baseline missing for \(safeTestName).\(identifier)")
+            }
+        }
+        try? FileManager.default.removeItem(at: tmpURL)
+    }
+
+    private static func runTrimDiagnostics(
+        imageURL: URL,
+        label: String,
+        testName: String,
+        identifier: String
+    ) -> TrimMetrics? {
+        let magickPath = "/opt/homebrew/bin/magick"
+        let convertPath = "/opt/homebrew/bin/convert"
+        let tool: String
+        let usesMagick: Bool
+        if FileManager.default.fileExists(atPath: magickPath) {
+            tool = magickPath
+            usesMagick = true
+        } else if FileManager.default.fileExists(atPath: convertPath) {
+            tool = convertPath
+            usesMagick = false
+        } else {
+            tool = "magick"
+            usesMagick = true
+        }
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: tool)
+        var arguments: [String] = []
+        if usesMagick {
+            arguments.append("convert")
+        }
+        arguments.append(contentsOf: [
+            imageURL.path,
+            "-alpha", "remove",
+            "-background", "white",
+            "-flatten",
+            "-fuzz", "1%",
+            "-trim",
+            "-format", "%w %h %X %Y",
+            "info:"
+        ])
+        process.arguments = arguments
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = pipe
+        do {
+            try process.run()
+            process.waitUntilExit()
+        } catch {
+            AttachmentDebugLogger.record("[Trim] \(label) convert failed \(error.localizedDescription)")
+            return nil
+        }
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        let output = String(data: data, encoding: .utf8) ?? ""
+        let lastLine = output
+            .split(separator: "\n")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .last { !$0.isEmpty } ?? ""
+        let parts = lastLine.split(separator: " ")
+        guard parts.count == 4,
+              let trimW = Int(parts[0]),
+              let trimH = Int(parts[1]),
+              let trimX = Int(parts[2]),
+              let trimY = Int(parts[3]) else {
+            AttachmentDebugLogger.record("[Trim] \(label) parse failed output='\(output.trimmingCharacters(in: .whitespacesAndNewlines))'")
+            return nil
+        }
+        let imageRep = NSImage(contentsOf: imageURL)
+        let size = imageRep?.cgImage(forProposedRect: nil, context: nil, hints: nil)
+            .map { (w: $0.width, h: $0.height) }
+            ?? (w: 0, h: 0)
+        let metrics = TrimMetrics(
+            width: trimW,
+            height: trimH,
+            x: trimX,
+            y: trimY,
+            imageWidth: size.w,
+            imageHeight: size.h
+        )
+        AttachmentDebugLogger.record(
+            "[Trim] \(label) test=\(testName).\(identifier) trimX=\(metrics.x) trimY=\(metrics.y) trimW=\(metrics.width) trimH=\(metrics.height) imgW=\(metrics.imageWidth) imgH=\(metrics.imageHeight) bottom=\(metrics.bottom)"
+        )
+        return metrics
+    }
+
+    @MainActor
+    static func snapshot<V: View>(
+        of view: V,
+        width: CGFloat,
+        height: CGFloat? = nil,
+        named name: String? = nil,
+        record recording: Bool? = nil,
+        snapshotDirectory: String? = nil,
+        precision: Float = 0.9,
+        perceptualPrecision: Float = 0.85,
+        scale: CGFloat = 3,
+        sleep sleepDuration: Duration = .seconds(2),
+        fileID: StaticString = #fileID,
+        file filePath: StaticString = #filePath,
+        testName: String = #function,
+        line: UInt = #line,
+        column: UInt = #column
+    ) async throws {
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_ATTACHMENT_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+        let textKitEnvValue = ProcessInfo.processInfo.environment["SWIFTUIHTML_USE_TEXTKIT_LAYOUT"]
+        let requestedTextKit = textKitEnvValue == "1"
+        let effectiveTextKit = textKitEnvValue ?? "0"
+        setenv("SWIFTUIHTML_USE_TEXTKIT_LAYOUT", effectiveTextKit, 1)
+        let requestedRawOffset = ProcessInfo.processInfo.environment["SWIFTUIHTML_MACOS_USE_RAW_OFFSET"] == "1"
+        setenv("SWIFTUIHTML_MACOS_USE_RAW_OFFSET", requestedRawOffset ? "1" : "0", 1)
+        let textKitEnv = ProcessInfo.processInfo.environment["SWIFTUIHTML_USE_TEXTKIT_LAYOUT"] ?? "nil"
+        let rawOffsetEnv = ProcessInfo.processInfo.environment["SWIFTUIHTML_MACOS_USE_RAW_OFFSET"] ?? "nil"
+        AttachmentDebugLogger.record("[Snapshot] env textKit=\(textKitEnv) rawOffset=\(rawOffsetEnv)")
+        let allowHeightOverride = ProcessInfo.processInfo.environment["SWIFTUIHTML_MACOS_USE_FITTING_HEIGHT"] == "1"
+        AttachmentDebugLogger.clear()
+        let identifier = name ?? "1"
+        let shouldRecord = recording ?? (ProcessInfo.processInfo.environment["SNAPSHOT_RECORD"] == "1")
+        let recordOverride: SnapshotTestingConfiguration.Record? = snapshotDirectory == nil ? nil : .never
+        let recordFlag: Bool? = snapshotDirectory == nil ? shouldRecord : nil
+        let baselineTestName = resolveBaselineTestName(
+            snapshotDirectory: snapshotDirectory,
+            testName: testName,
+            name: name
+        )
+        AttachmentDebugLogger.record(
+            "[Snapshot] start test=\(testName) name=\(identifier) baseline=\(baselineTestName)"
+        )
+        defer {
+            AttachmentDebugLogger.record("[Snapshot] end test=\(testName) name=\(identifier)")
+        }
+        let referenceSize = referencePixelSize(
+            snapshotDirectory: snapshotDirectory,
+            testName: baselineTestName,
+            name: name
+        )
+        var targetScale = scale
+        if let referenceSize, width > 0 {
+            let candidate = referenceSize.width / width
+            if candidate > 0.5 {
+                targetScale = candidate
+            }
+        }
+        AttachmentDebugLogger.record("[Snapshot] baselineTestName=\(baselineTestName) scale requested=\(scale) targetScale=\(targetScale)")
+
+        let rootView = view
+            .environment(\.colorScheme, .light)
+            .background(Color.white)
+            .ignoresSafeArea()
+        let hostingView = NSHostingView(rootView: rootView)
+
+        let initialHeight: CGFloat = height ?? 1000
+        let initialSize = NSSize(width: width, height: initialHeight)
+        let container = NSView(frame: NSRect(origin: .zero, size: initialSize))
+        container.wantsLayer = true
+        container.addSubview(hostingView)
+        hostingView.wantsLayer = true
+        hostingView.frame = container.bounds
+        hostingView.autoresizingMask = [.width, .height]
+
+        container.layoutSubtreeIfNeeded()
+
+        if let referenceSize {
+            let targetWidth = referenceSize.width / targetScale
+            var targetHeight: CGFloat
+            if let height {
+                targetHeight = height
+            } else {
+                targetHeight = max(1, ceil(referenceSize.height / targetScale))
+            }
+            let finalSize = NSSize(width: targetWidth, height: targetHeight)
+            container.setFrameSize(finalSize)
+            hostingView.frame = container.bounds
+            container.layoutSubtreeIfNeeded()
+            AttachmentDebugLogger.record("[Snapshot] referenceSize=on finalSize=\(finalSize)")
+        } else if height == nil {
+            let fittingSize = hostingView.fittingSize
+            let finalHeight = max(1, ceil(fittingSize.height))
+            let finalSize = NSSize(width: width, height: finalHeight)
+            if allowHeightOverride {
+                container.setFrameSize(finalSize)
+                hostingView.frame = container.bounds
+                container.layoutSubtreeIfNeeded()
+                AttachmentDebugLogger.record("[Snapshot] heightOverride=on finalHeight=\(finalHeight)")
+            } else {
+                AttachmentDebugLogger.record("[Snapshot] heightOverride=off finalHeight=\(finalHeight)")
+            }
+        }
+
+        let window = NSWindow(
+            contentRect: container.frame,
+            styleMask: [.titled, .closable],
+            backing: .buffered,
+            defer: false
+        )
+        window.contentView = container
+        window.appearance = NSAppearance(named: .aqua)
+        window.makeKeyAndOrderFront(nil)
+
+        try await Task.sleep(for: sleepDuration)
+
+        container.layoutSubtreeIfNeeded()
+
+        let fittingSize = hostingView.fittingSize
+        AttachmentDebugLogger.record("[Snapshot] fittingSize=\(fittingSize) containerSize=\(container.frame.size) hostFrame=\(hostingView.frame.size)")
+        AttachmentDebugLogger.record("[Snapshot] intrinsicContentSize=\(hostingView.intrinsicContentSize)")
+
+        let waitImages = await ImageLoadTracker.shared.waitUntilIdle(timeoutSeconds: 5)
+        AttachmentDebugLogger.record("[Snapshot] imageLoadIdle=\(waitImages)")
+        let waitLayout = await AttachmentLayoutTracker.shared.waitUntilIdle(timeoutSeconds: 3)
+        AttachmentDebugLogger.record("[Snapshot] layoutIdle=\(waitLayout)")
+        try await Task.sleep(for: .milliseconds(800))
+        container.layoutSubtreeIfNeeded()
+        container.needsLayout = true
+        if height == nil, referenceSize == nil {
+            let fittingSize = hostingView.fittingSize
+            let updatedHeight = max(1, ceil(fittingSize.height))
+            if abs(updatedHeight - container.frame.height) > 1 {
+                let updatedSize = NSSize(width: container.frame.width, height: updatedHeight)
+                container.setFrameSize(updatedSize)
+                hostingView.frame = container.bounds
+                container.layoutSubtreeIfNeeded()
+                window.setContentSize(updatedSize)
+                AttachmentDebugLogger.record("[Snapshot] postLoadHeight=\(updatedHeight)")
+            }
+        }
+        window.displayIfNeeded()
+        hostingView.displayIfNeeded()
+        NSApp.updateWindows()
+#if canImport(CoreAnimation)
+        CATransaction.flush()
+#endif
+        let attachmentCounts = await AttachmentLayoutTracker.shared.snapshotCounts()
+        logImageViewDiagnostics(in: container, attachmentCounts: attachmentCounts)
+
+
+        let snapshotSize = container.frame.size
+        let renderScale = targetScale
+        let backingScale = window.backingScaleFactor
+        AttachmentDebugLogger.record("[Snapshot] backingScale=\(backingScale) renderScale=\(renderScale)")
+
+        let image: NSImage
+        if ProcessInfo.processInfo.environment["SWIFTUIHTML_MACOS_USE_IMAGE_RENDERER"] == "1",
+           #available(macOS 13.0, *),
+           let rendered = makeSnapshotImageUsingRenderer(
+            of: rootView,
+            size: snapshotSize,
+            scale: renderScale
+           ) {
+            image = rendered
+        } else {
+            image = makeSnapshotImage(
+                of: hostingView,
+                size: snapshotSize,
+                scale: renderScale
+            )
+        }
+        let finalImage = image
+        ensureSnapshotArtifactsDirectory()
+        writeArtifactImage(
+            finalImage,
+            testName: baselineTestName,
+            name: name,
+            filePath: filePath
+        )
+        performOCRDebug(
+            image: finalImage,
+            testName: testName,
+            name: name,
+            scale: targetScale,
+            snapshotDirectory: snapshotDirectory,
+            baselineTestName: baselineTestName
+        )
+        logPaddingDiagnostics(
+            image: finalImage,
+            testName: testName,
+            name: name,
+            snapshotDirectory: snapshotDirectory,
+            baselineTestName: baselineTestName
+        )
+        logTrimDiagnostics(
+            image: finalImage,
+            testName: testName,
+            name: name,
+            snapshotDirectory: snapshotDirectory,
+            baselineTestName: baselineTestName
+        )
+        let failure = withSnapshotTesting(record: recordOverride) {
+            verifySnapshot(
+                of: finalImage,
+                as: snapshottingForImages(
+                    precision: precision,
+                    perceptualPrecision: perceptualPrecision
+                ),
+                named: name,
+                record: recordFlag,
+                snapshotDirectory: snapshotDirectory,
+                fileID: fileID,
+                file: filePath,
+                testName: baselineTestName,
+                line: line,
+                column: column
+            )
+        }
+        if let message = failure {
+            recordIssue(
+                message,
+                fileID: fileID,
+                filePath: filePath,
+                line: line,
+                column: column
+            )
+        }
+        attachDebugLogs(testName: baselineTestName, name: name)
+    }
+
+    private static func ensureSnapshotArtifactsDirectory() {
+        if let existing = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"] {
+            let url = URL(fileURLWithPath: existing, isDirectory: true)
+            if !FileManager.default.fileExists(atPath: url.path) {
+                try? FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+                AttachmentDebugLogger.record("[Snapshot] SNAPSHOT_ARTIFACTS=\(url.path)")
+            }
+            return
+        }
+        let artifactsUrl = artifactsDirectory
+        do {
+            try FileManager.default.createDirectory(at: artifactsUrl, withIntermediateDirectories: true)
+            setenv("SNAPSHOT_ARTIFACTS", artifactsUrl.path, 1)
+            AttachmentDebugLogger.record("[Snapshot] SNAPSHOT_ARTIFACTS=\(artifactsUrl.path)")
+        } catch {
+            // Continue without overriding SNAPSHOT_ARTIFACTS.
+        }
+    }
+
+    private static func writeArtifactImage(
+        _ image: NSImage,
+        testName: String,
+        name: String?,
+        filePath: StaticString
+    ) {
+        guard let root = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"] else {
+            AttachmentDebugLogger.record("[Snapshot] artifact skip: SNAPSHOT_ARTIFACTS not set")
+            return
+        }
+        let fileURL = URL(fileURLWithPath: "\(filePath)", isDirectory: false)
+        let group = sanitizePathComponent(fileURL.deletingPathExtension().lastPathComponent)
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let artifactDir = URL(fileURLWithPath: root, isDirectory: true)
+            .appendingPathComponent(group)
+        let pngURL = artifactDir
+            .appendingPathComponent("\(safeTestName).\(identifier)")
+            .appendingPathExtension("png")
+        guard let tiff = image.tiffRepresentation,
+              let bitmap = NSBitmapImageRep(data: tiff),
+              let png = bitmap.representation(using: .png, properties: [:]) else {
+            AttachmentDebugLogger.record("[Snapshot] artifact skip: PNG encoding failed")
+            return
+        }
+        do {
+            try FileManager.default.createDirectory(
+                at: artifactDir,
+                withIntermediateDirectories: true
+            )
+            try png.write(to: pngURL)
+            AttachmentDebugLogger.record("[Snapshot] artifact wrote \(pngURL.path)")
+        } catch {
+            AttachmentDebugLogger.record("[Snapshot] artifact write failed \(error.localizedDescription)")
+        }
+    }
+
+
+    private static func logImageViewDiagnostics(
+        in rootView: NSView,
+        attachmentCounts: AttachmentLayoutTracker.AttachmentCounts?
+    ) {
+        let imageViews = allDescendants(of: rootView).compactMap { $0 as? NSImageView }
+        let visibleImages = imageViews.filter { view in
+            guard let image = view.image else { return false }
+            let size = view.bounds.size
+            return image.size.width > 0 && image.size.height > 0 && size.width > 1 && size.height > 1
+        }
+        let layeredViews = allDescendants(of: rootView).filter { $0.layer?.contents != nil }
+        let layerContentsCount = layerContentsTotal(in: rootView.layer)
+        let layerImageHashes = layerContentsHashes(in: rootView.layer)
+        if let attachmentCounts {
+            AttachmentDebugLogger.record(
+                "[Snapshot] imageViews total=\(imageViews.count) visible=\(visibleImages.count) layerContents=\(layeredViews.count) layerTreeContents=\(layerContentsCount) layerImageHashes=\(layerImageHashes.count) expectedAttachments=\(attachmentCounts.expected) expectedImages=\(attachmentCounts.expectedImages) prepared=\(attachmentCounts.prepared) uniqueKeys=\(attachmentCounts.uniqueKeys)"
+            )
+        } else {
+            AttachmentDebugLogger.record(
+                "[Snapshot] imageViews total=\(imageViews.count) visible=\(visibleImages.count) layerContents=\(layeredViews.count) layerTreeContents=\(layerContentsCount) layerImageHashes=\(layerImageHashes.count)"
+            )
+        }
+        if let attachmentCounts, attachmentCounts.expectedImages > 0 {
+            if layerContentsCount == 0 {
+                AttachmentDebugLogger.record("[Snapshot][Heuristic] no layer contents but expectedImages=\(attachmentCounts.expectedImages)")
+            } else if layerImageHashes.count > 0 && layerImageHashes.count < attachmentCounts.expectedImages {
+                AttachmentDebugLogger.record(
+                    "[Snapshot][Heuristic] layerImageHashes (\(layerImageHashes.count)) < expectedImages (\(attachmentCounts.expectedImages))"
+                )
+            }
+        }
+        guard !visibleImages.isEmpty else {
+            AttachmentDebugLogger.record("[Snapshot][Heuristic] no visible NSImageView instances (attachments may not be rendering)")
+            return
+        }
+        let frames = visibleImages.prefix(32).map { view in
+            view.convert(view.bounds, to: rootView)
+        }
+        let summary = frames.map { "\($0.integral)" }.joined(separator: " | ")
+        AttachmentDebugLogger.record("[Snapshot] imageViewFrames \(summary)")
+        if !frames.isEmpty {
+            let frameKeys = frames.map { "\($0.integral)" }
+            let frameCounts = frameKeys.reduce(into: [String: Int]()) { counts, key in
+                counts[key, default: 0] += 1
+            }
+            let uniqueFrames = frameCounts.count
+            if let maxFrameDup = frameCounts.max(by: { $0.value < $1.value }) {
+                AttachmentDebugLogger.record("[Snapshot] imageFrameDuplicates total=\(frames.count) unique=\(uniqueFrames) maxDup=\(maxFrameDup.value) sample=\(maxFrameDup.key)")
+                if maxFrameDup.value > 1 && uniqueFrames <= max(1, frames.count / 2) {
+                    AttachmentDebugLogger.record("[Snapshot][Heuristic] many images share the same frame (possible stacking or offset bug)")
+                }
+            }
+        }
+
+        let hashes: [String] = visibleImages.compactMap { view -> String? in
+            guard let image = view.image else { return nil }
+            return imageHash(for: image)
+        }
+        guard !hashes.isEmpty else { return }
+        let counts = hashes.reduce(into: [String: Int]()) { counts, hash in
+            counts[hash, default: 0] += 1
+        }
+        let uniqueCount = counts.count
+        let maxDup = counts.max(by: { $0.value < $1.value })
+        if let maxDup {
+            AttachmentDebugLogger.record("[Snapshot] imageHashes total=\(hashes.count) unique=\(uniqueCount) maxDup=\(maxDup.value) sample=\(maxDup.key)")
+            if maxDup.value > 1 && uniqueCount == 1 {
+                AttachmentDebugLogger.record("[Snapshot][Heuristic] all images identical (possible stacking or reuse bug)")
+            }
+            if uniqueCount > 1 && uniqueCount <= max(1, hashes.count / 2) {
+                AttachmentDebugLogger.record("[Snapshot][Heuristic] many images are duplicates (possible missing or repeated image bug)")
+            }
+        }
+    }
+
+    private static func imageHash(for image: NSImage) -> String? {
+        guard let data = image.tiffRepresentation else { return nil }
+        let digest = SHA256.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func resizedImage(image: NSImage, pixelSize: CGSize) -> NSImage? {
+        let targetWidth = max(1, Int(pixelSize.width.rounded()))
+        let targetHeight = max(1, Int(pixelSize.height.rounded()))
+        guard let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+            return nil
+        }
+        let colorSpace = CGColorSpace(name: CGColorSpace.sRGB) ?? CGColorSpaceCreateDeviceRGB()
+        let bitmapInfo = CGImageAlphaInfo.premultipliedLast.rawValue
+        guard let context = CGContext(
+            data: nil,
+            width: targetWidth,
+            height: targetHeight,
+            bitsPerComponent: 8,
+            bytesPerRow: 0,
+            space: colorSpace,
+            bitmapInfo: bitmapInfo
+        ) else {
+            return nil
+        }
+        context.interpolationQuality = .high
+        context.setShouldAntialias(true)
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: targetWidth, height: targetHeight))
+        guard let resizedCG = context.makeImage() else { return nil }
+        let resized = NSImage(cgImage: resizedCG, size: NSSize(width: targetWidth, height: targetHeight))
+        return resized
+    }
+
+    private static func pixelSize(of image: NSImage) -> CGSize? {
+        guard let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+            return nil
+        }
+        return CGSize(width: cgImage.width, height: cgImage.height)
+    }
+
+    private static func snapshottingForImages(
+        precision: Float,
+        perceptualPrecision: Float
+    ) -> Snapshotting<NSImage, NSImage> {
+        let base = Snapshotting<NSImage, NSImage>.image(
+            precision: precision,
+            perceptualPrecision: perceptualPrecision
+        )
+        let diffing = Diffing<NSImage>(
+            toData: base.diffing.toData,
+            fromData: base.diffing.fromData,
+            diff: { oldImage, newImage in
+                let preparedOld = preparedForComparison(oldImage)
+                let preparedNew = preparedForComparison(newImage)
+                guard let targetSize = pixelSize(of: preparedOld) else {
+                    return base.diffing.diff(preparedOld, preparedNew)
+                }
+                if let newSize = pixelSize(of: preparedNew), newSize != targetSize,
+                   let resized = resizedImage(image: preparedNew, pixelSize: targetSize) {
+                    AttachmentDebugLogger.record(
+                        "[Snapshot] scaled new image from \(Int(newSize.width))x\(Int(newSize.height)) to \(Int(targetSize.width))x\(Int(targetSize.height))"
+                    )
+                    return base.diffing.diff(preparedOld, resized)
+                }
+                return base.diffing.diff(preparedOld, preparedNew)
+            }
+        )
+        return Snapshotting<NSImage, NSImage>(
+            pathExtension: base.pathExtension,
+            diffing: diffing
+        )
+    }
+
+    private static func preparedForComparison(_ image: NSImage) -> NSImage {
+        guard let cropped = croppedContentImage(image) else {
+            return image
+        }
+        return cropped
+    }
+
+    private static func croppedContentImage(_ image: NSImage) -> NSImage? {
+        guard let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+            return nil
+        }
+        guard let rect = contentCropRect(for: cgImage) else {
+            return nil
+        }
+        guard let cropped = cgImage.cropping(to: rect) else {
+            return nil
+        }
+        let result = NSImage(cgImage: cropped, size: NSSize(width: rect.width, height: rect.height))
+        AttachmentDebugLogger.record(
+            "[Snapshot] contentCrop rect=\(Int(rect.origin.x)),\(Int(rect.origin.y)) \(Int(rect.width))x\(Int(rect.height))"
+        )
+        return result
+    }
+
+    private static func contentCropRect(for cgImage: CGImage) -> CGRect? {
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 1, height > 1 else { return nil }
+
+        let bytesPerRow = width * 4
+        var buffer = [UInt8](repeating: 0, count: bytesPerRow * height)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpace(name: CGColorSpace.sRGB) ?? CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else {
+            return nil
+        }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        let whiteThreshold: UInt8 = 245
+        let alphaThreshold: UInt8 = 5
+        var minX = width
+        var minY = height
+        var maxX = 0
+        var maxY = 0
+        var found = false
+
+        for y in 0..<height {
+            let rowStart = y * bytesPerRow
+            for x in 0..<width {
+                let idx = rowStart + (x * 4)
+                let r = buffer[idx]
+                let g = buffer[idx + 1]
+                let b = buffer[idx + 2]
+                let a = buffer[idx + 3]
+                if a > alphaThreshold && (r < whiteThreshold || g < whiteThreshold || b < whiteThreshold) {
+                    if x < minX { minX = x }
+                    if y < minY { minY = y }
+                    if x > maxX { maxX = x }
+                    if y > maxY { maxY = y }
+                    found = true
+                }
+            }
+        }
+
+        guard found else { return nil }
+        return CGRect(
+            x: minX,
+            y: minY,
+            width: max(1, maxX - minX + 1),
+            height: max(1, maxY - minY + 1)
+        )
+    }
+
+    private static func imageHash(for cgImage: CGImage) -> String? {
+        let rep = NSBitmapImageRep(cgImage: cgImage)
+        guard let data = rep.representation(using: .png, properties: [:]) else { return nil }
+        let digest = SHA256.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func layerContentsHashes(in layer: CALayer?) -> [String] {
+        guard let layer else { return [] }
+        var hashes: [String] = []
+        var stack: [CALayer] = [layer]
+        while let current = stack.popLast() {
+            if let contents = current.contents {
+                if let nsImage = contents as? NSImage, let hash = imageHash(for: nsImage) {
+                    hashes.append(hash)
+                }
+            }
+            if let sublayers = current.sublayers {
+                stack.append(contentsOf: sublayers)
+            }
+        }
+        if !hashes.isEmpty {
+            let counts = hashes.reduce(into: [String: Int]()) { counts, hash in
+                counts[hash, default: 0] += 1
+            }
+            let uniqueCount = counts.count
+            let maxDup = counts.max(by: { $0.value < $1.value })
+            if let maxDup {
+                AttachmentDebugLogger.record("[Snapshot] layerImageHashStats total=\(hashes.count) unique=\(uniqueCount) maxDup=\(maxDup.value)")
+                if uniqueCount == 1 && maxDup.value > 1 {
+                    AttachmentDebugLogger.record("[Snapshot][Heuristic] all layer images identical (possible stacking or reuse bug)")
+                }
+            }
+        }
+        return hashes
+    }
+
+    private static func attachDebugLogs(testName: String, name: String?) {
+        let logs = AttachmentDebugLogger.dump()
+        guard !logs.isEmpty else { return }
+        print("SWIFTUIHTML_ATTACHMENT_LOGS_BEGIN")
+        print(logs)
+        print("SWIFTUIHTML_ATTACHMENT_LOGS_END")
+        let logURL = snapshotLogURL(testName: testName, name: name)
+        appendDiagnosticLog(logs, to: logURL)
+        let attachment = XCTAttachment(string: logs)
+        attachment.name = "SwiftUIHTML Attachment Layout Logs"
+        attachment.lifetime = .keepAlways
+        XCTContext.runActivity(named: "SwiftUIHTML Attachment Layout Logs") { activity in
+            activity.add(attachment)
+        }
+        AttachmentDebugLogger.clear()
+    }
+
+    private static func snapshotLogURL(testName: String, name: String?) -> URL {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let filename = "\(safeTestName).\(identifier).log"
+        return diagnosticLogDirectory.appendingPathComponent(filename)
+    }
+
+    private static func appendDiagnosticLog(_ logs: String, to url: URL) {
+        let payload = logs + "\n"
+        do {
+            if !FileManager.default.fileExists(atPath: diagnosticLogDirectory.path) {
+                try FileManager.default.createDirectory(
+                    at: diagnosticLogDirectory,
+                    withIntermediateDirectories: true
+                )
+            }
+            if !FileManager.default.fileExists(atPath: url.path) {
+                try "".write(to: url, atomically: true, encoding: .utf8)
+            }
+            let handle = try FileHandle(forWritingTo: url)
+            try handle.seekToEnd()
+            if let data = payload.data(using: .utf8) {
+                try handle.write(contentsOf: data)
+            }
+            try handle.close()
+        } catch {
+            print("SWIFTUIHTML_DIAG_WRITE_FAILED: \(error.localizedDescription)")
+        }
+    }
+
+    private static func allDescendants(of rootView: NSView) -> [NSView] {
+        var result: [NSView] = []
+        var stack: [NSView] = [rootView]
+        while let view = stack.popLast() {
+            result.append(view)
+            stack.append(contentsOf: view.subviews)
+        }
+        return result
+    }
+
+    private static func layerContentsTotal(in layer: CALayer?) -> Int {
+        guard let layer else { return 0 }
+        var count = layer.contents == nil ? 0 : 1
+        if let sublayers = layer.sublayers {
+            for sublayer in sublayers {
+                count += layerContentsTotal(in: sublayer)
+            }
+        }
+        return count
+    }
+
+    private static func applyContentsScale(_ layer: CALayer?, scale: CGFloat) {
+        guard let layer else { return }
+        layer.contentsScale = scale
+        if let sublayers = layer.sublayers {
+            for sublayer in sublayers {
+                applyContentsScale(sublayer, scale: scale)
+            }
+        }
+    }
+
+    private static func performOCRDebug(
+        image: NSImage,
+        testName: String,
+        name: String?,
+        scale: CGFloat,
+        snapshotDirectory: String?,
+        baselineTestName: String
+    ) {
+        guard NSClassFromString("XCTestCase") != nil else { return }
+        let shouldOCR = ProcessInfo.processInfo.environment["SWIFTUIHTML_OCR_DEBUG"] != "0"
+        guard shouldOCR else { return }
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        guard let newStats = ocrStats(for: image, label: "new") else { return }
+        let newLog = "[OCR] new textRectCount=\(newStats.count) topPadding=\(newStats.topPadding) bottomPadding=\(newStats.bottomPadding) imageSize=\(newStats.imageSize)"
+        print("[SwiftUIHTML]\(newLog)")
+        AttachmentDebugLogger.record(newLog)
+
+        saveOCROverlay(
+            image: image,
+            cgImage: newStats.cgImage,
+            rects: newStats.drawRects,
+            scale: scale,
+            outputDir: "/tmp/swiftuihtml-ocr/macos",
+            filename: "\(safeTestName).\(identifier).ocr.png"
+        )
+
+        if let baselineImage = loadBaselineImage(
+            snapshotDirectory: snapshotDirectory,
+            testName: sanitizePathComponent(baselineTestName),
+            identifier: identifier
+        ), let baselineStats = ocrStats(for: baselineImage, label: "baseline") {
+            let deltaTop = newStats.topPadding - baselineStats.topPadding
+            let deltaBottom = newStats.bottomPadding - baselineStats.bottomPadding
+            let baselineLog = "[OCR] baseline textRectCount=\(baselineStats.count) topPadding=\(baselineStats.topPadding) bottomPadding=\(baselineStats.bottomPadding) imageSize=\(baselineStats.imageSize) deltaTop=\(deltaTop) deltaBottom=\(deltaBottom)"
+            print("[SwiftUIHTML]\(baselineLog)")
+            AttachmentDebugLogger.record(baselineLog)
+            saveOCROverlay(
+                image: baselineImage,
+                cgImage: baselineStats.cgImage,
+                rects: baselineStats.drawRects,
+                scale: scale,
+                outputDir: "/tmp/swiftuihtml-ocr/macos-baseline",
+                filename: "\(safeTestName).\(identifier).baseline.ocr.png"
+            )
+        } else {
+            let missingLog = "[OCR] baseline image missing for \(safeTestName).\(identifier)"
+            print("[SwiftUIHTML]\(missingLog)")
+            AttachmentDebugLogger.record(missingLog)
+        }
+    }
+
+    private static func ocrStats(for image: NSImage, label: String) -> OCRStats? {
+        guard let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+            print("[SwiftUIHTML][OCR] missing CGImage (\(label))")
+            return nil
+        }
+
+        let request = VNRecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        request.usesLanguageCorrection = false
+        request.recognitionLanguages = ["en-US", "ja-JP", "ko-KR", "zh-Hans", "zh-Hant"]
+
+        let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+        do {
+            try handler.perform([request])
+        } catch {
+            print("[SwiftUIHTML][OCR] request failed \(error.localizedDescription)")
+            return nil
+        }
+
+        let observations = request.results ?? []
+        if observations.isEmpty {
+            return OCRStats(
+                drawRects: [],
+                topPadding: 0,
+                bottomPadding: 0,
+                imageSize: CGSize(width: cgImage.width, height: cgImage.height),
+                cgImage: cgImage
+            )
+        }
+
+        let imageWidth = CGFloat(cgImage.width)
+        let imageHeight = CGFloat(cgImage.height)
+
+        var drawRects: [CGRect] = []
+        var topLeftRects: [CGRect] = []
+        drawRects.reserveCapacity(observations.count)
+        topLeftRects.reserveCapacity(observations.count)
+
+        for observation in observations {
+            let bbox = observation.boundingBox
+            let drawRect = CGRect(
+                x: bbox.minX * imageWidth,
+                y: bbox.minY * imageHeight,
+                width: bbox.width * imageWidth,
+                height: bbox.height * imageHeight
+            )
+            let topLeftRect = CGRect(
+                x: bbox.minX * imageWidth,
+                y: (1 - bbox.maxY) * imageHeight,
+                width: bbox.width * imageWidth,
+                height: bbox.height * imageHeight
+            )
+            drawRects.append(drawRect)
+            topLeftRects.append(topLeftRect)
+        }
+
+        let minY = topLeftRects.map(\.minY).min() ?? 0
+        let maxY = topLeftRects.map(\.maxY).max() ?? 0
+        let topPadding = minY
+        let bottomPadding = max(0, imageHeight - maxY)
+        return OCRStats(
+            drawRects: drawRects,
+            topPadding: topPadding,
+            bottomPadding: bottomPadding,
+            imageSize: CGSize(width: imageWidth, height: imageHeight),
+            cgImage: cgImage
+        )
+    }
+
+    private static func saveOCROverlay(
+        image: NSImage,
+        cgImage: CGImage,
+        rects: [CGRect],
+        scale: CGFloat,
+        outputDir: String,
+        filename: String
+    ) {
+        let overlay = drawOCR(image: image, cgImage: cgImage, rects: rects, scale: scale)
+        let outputURL = URL(fileURLWithPath: outputDir, isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
+        } catch {
+            print("[SwiftUIHTML][OCR] create dir failed \(error.localizedDescription)")
+        }
+        let fileURL = outputURL.appendingPathComponent(filename)
+        if let data = pngData(from: overlay) {
+            do {
+                try data.write(to: fileURL)
+                print("[SwiftUIHTML][OCR] overlay saved \(fileURL.path)")
+            } catch {
+                print("[SwiftUIHTML][OCR] write failed \(error.localizedDescription)")
+            }
+        }
+    }
+
+    private static func drawOCR(
+        image: NSImage,
+        cgImage: CGImage,
+        rects: [CGRect],
+        scale: CGFloat
+    ) -> NSImage {
+        let pixelsWide = max(1, cgImage.width)
+        let pixelsHigh = max(1, cgImage.height)
+        let rep = NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: pixelsWide,
+            pixelsHigh: pixelsHigh,
+            bitsPerSample: 8,
+            samplesPerPixel: 4,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bytesPerRow: 0,
+            bitsPerPixel: 0
+        )
+        rep?.size = NSSize(width: CGFloat(pixelsWide) / scale, height: CGFloat(pixelsHigh) / scale)
+
+        let output = NSImage(size: rep?.size ?? image.size)
+        if let rep {
+            NSGraphicsContext.saveGraphicsState()
+            if let context = NSGraphicsContext(bitmapImageRep: rep) {
+                NSGraphicsContext.current = context
+                context.cgContext.draw(cgImage, in: CGRect(x: 0, y: 0, width: CGFloat(pixelsWide), height: CGFloat(pixelsHigh)))
+                context.cgContext.setStrokeColor(NSColor.systemRed.withAlphaComponent(0.7).cgColor)
+                context.cgContext.setLineWidth(2.0)
+                rects.forEach { rect in
+                    context.cgContext.stroke(rect)
+                }
+            }
+            NSGraphicsContext.restoreGraphicsState()
+            output.addRepresentation(rep)
+        }
+        return output
+    }
+
+    private static func loadBaselineImage(
+        snapshotDirectory: String?,
+        testName: String,
+        identifier: String
+    ) -> NSImage? {
+        guard let snapshotDirectory else { return nil }
+        let fileURL = URL(fileURLWithPath: snapshotDirectory, isDirectory: true)
+            .appendingPathComponent("\(testName).\(identifier)")
+            .appendingPathExtension("png")
+        return NSImage(contentsOf: fileURL)
+    }
+
+    private static func pngData(from image: NSImage) -> Data? {
+        guard let tiff = image.tiffRepresentation else { return nil }
+        guard let rep = NSBitmapImageRep(data: tiff) else { return nil }
+        return rep.representation(using: .png, properties: [:])
+    }
+
+    private struct OCRStats {
+        let drawRects: [CGRect]
+        let topPadding: CGFloat
+        let bottomPadding: CGFloat
+        let imageSize: CGSize
+        let cgImage: CGImage
+
+        var count: Int { drawRects.count }
+    }
+}
+#endif
diff --git a/SwiftUIHTMLExampleMacOSTests/YomitanSnapshotTests.swift b/SwiftUIHTMLExampleMacOSTests/YomitanSnapshotTests.swift
new file mode 100644
index 0000000..320e72f
--- /dev/null
+++ b/SwiftUIHTMLExampleMacOSTests/YomitanSnapshotTests.swift
@@ -0,0 +1,620 @@
+//  Copyright © 2026 PRND. All rights reserved.
+#if os(macOS)
+import SwiftUI
+import Testing
+import SnapshotTesting
+
+@testable import SwiftUIHTML
+@testable import SwiftUIHTMLExample
+
+private let iosSnapshotDirectory = MacViewSnapshotTester.iosSnapshotDirectory()
+
+struct HTMLBasicMacOSTests {
+    @MainActor
+    @Test(arguments: [LineBreakMode.byWordWrapping, LineBreakMode.byCharWrapping])
+    func testingBasicHTMLElements(lineBreakMode: LineBreakMode) async throws {
+        let html = """
+        <header>
+            <h1>Testing Basic HTML Elements</h1>
+            <p>This is an example showcasing various fundamental HTML elements.</p>
+        </header>
+        
+        <main>
+            <section>
+                <h2>Text-related Elements</h2>
+                <p>Testing <strong>strong</strong> and <em>emphasized</em> text.<br>Also, checking line breaks (`&lt;br&gt;`).</p>
+                <p>Testing multiple line breaks:<br><br>Text remains visible after two line breaks.</p>
+            </section>
+        
+            <section>
+                <h2>Links and Styles</h2>
+                <p>Here's text with <span style="color: blue;">applied styles</span> and <a href="https://example.com" target="_blank">a link that opens in a new tab</a>.</p>
+            </section>
+        
+            <section>
+                <h2>List-related Elements</h2>
+                <p>An example of an unordered list:</p>
+                <ul>
+                    <li>First item</li>
+                    <li>Second item</li>
+                    <li>Third item</li>
+                </ul>
+            </section>
+        
+            <section>
+                <h2>Inline Elements Test</h2>
+                <p>Testing the rendering of multiple inline elements (<span>span</span>, <strong>strong</strong>, <em>em</em>) used consecutively.</p>
+            </section>
+        </main>
+        
+        <footer>
+            <p>&copy; 2025 Basic HTML Test Page</p>
+        </footer>
+        """
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
+            .frame(width: 375)
+            .fixedSize(horizontal: true, vertical: false)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            named: "\(lineBreakMode)",
+            snapshotDirectory: iosSnapshotDirectory
+        )
+    }
+
+    @MainActor
+    @Test(arguments: [LineBreakMode.byCharWrapping, LineBreakMode.byWordWrapping])
+    func testingLineBreak(lineBreakMode: LineBreakMode) async throws {
+        let html = """
+        <p>1인 소유, 파노라믹 글라스 루프, 열선핸들
+        롱 레인지 트림으로 더욱 긴 거리를 운행할 수 있습니다.
+        외관과 실내 컨디션이 깔끔한 차량입니다.
+        파노라믹 글라스 루프가 적용되어 개방감 있는 가능합니다.</p>
+        <p>1인 소유, 파노라믹 글라스 루프, 열선핸들
+        롱 레인지 트림으로 더욱 긴 거리를 운행할 수 있습니다?
+        외관과 실내 컨디션이 깔끔한 차량입니다.
+        파노라믹 글라스 루프가 적용되어 개방감 있는 가능합니다.</p>
+        <p>1인 소유, 파노라믹 글라스 루프, 열선핸들
+        롱 레인지 트림으로 더욱 긴 거리를 운행할 수 있습니다.
+        외관과 실내 컨디션이 깔끔한 차량입니다.
+        파노라믹 글라스 루프가 적용되어 개방감 있는 가능합니다.</p>
+        """
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
+            .frame(width: 233, alignment: .leading)
+            .fixedSize(horizontal: true, vertical: false)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 233,
+            named: "\(lineBreakMode)",
+            snapshotDirectory: iosSnapshotDirectory
+        )
+    }
+
+    @MainActor
+    @Test(arguments: [(375, LineBreakMode.byCharWrapping), (375, LineBreakMode.byWordWrapping)])
+    func testHTMLImageAndNesting(width: CGFloat, lineBreakMode: LineBreakMode) async throws {
+        let html = """
+        <header>
+            <h1>Testing HTML Structure with Image and Nesting</h1>
+            <p>This example includes an image and demonstrates block and inline element nesting.</p>
+        </header>
+        
+        <main>
+            <section>
+                <h2>Image Element</h2>
+                <p>Here's an image:</p>
+                <!-- <img src="https://picsum.photos/id/237/200/300" width="200"> -->
+                <p>The image should appear above this text.</p>
+            </section>
+        
+            <section>
+                <h2>Inline Image Element</h2>
+                <p>This text contains an inline image: <img src="https://picsum.photos/id/237/50/50" width="8" height="8" alt="Small inline image"> This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: Thinline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: Thinline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: This text contains an inline image: <img src="https://picsum.photos/id/237/50/50" width="50" height="50" alt="Small inline image"> and continues after it.</p>
+                <p>Another paragraph with an inline image <img src="https://picsum.photos/id/100/50/50" width="50" height="50" alt="Another small inline image"> within the text flow. This text contains an inline image: <img src="https://picsum.photos/id/237/50/50" width="50" height="50" alt="Small inline image"> and continues after it. Another paragraph with an inline image <img src="https://picsum.photos/id/100/50/50" width="50" height="50" alt="Another small inline image"> within the text flow.</p> 
+            </section>
+        
+           <section>
+               <h2>Block inside Inline (with markers)</h2>
+               <p>Inline start <span>contains block <div>This is a block inside an inline.</div></span> inline end.</p>
+               <p>This tests how inline elements handle nested block elements with visual markers.</p>
+           </section>
+        
+           <section>
+               <h2>Inline inside Block inside Inline (with markers)</h2>
+               <p>Inline start <span>contains block <div>which contains inline <em>This is inline inside block inside inline.</em></div></span> inline end.</p>
+               <p>This tests deeper nesting with visual markers.</p>
+           </section>
+        
+            <section>
+                <h2>List with Inline Elements</h2>
+                <p>A list containing inline elements:</p>
+                <ul>
+                    <li>First item with <strong>strong</strong> text.</li>
+                    <li>Second item with <em>emphasized</em> text and a <span>styled</span> part.</li>
+                    <li>Third item with a <a href="#">link</a>.</li>
+                </ul>
+            </section>
+        </main>
+        
+        <footer>
+            <p>&copy; 2025 HTML Nesting Test Page</p>
+        </footer>
+        """
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
+            .frame(width: width)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: width,
+            named: "\(Int(width)),\(lineBreakMode)",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test()
+    func testHTMLImageWithLineHeight() async throws {
+        let html = """
+        <p>
+        <span style="font-family: 'SpoqaHanSansNeo-Regular'"> 가나다라ja <img src="https://picsum.photos/id/237/24/24" width="24" height="32" > </span>
+        <span style="font-family: 'SpoqaHanSansNeo-Regular'"> 가나다라ja <img src="https://picsum.photos/id/237/24/24" width="24" height="24" > </span>
+        <span style="font-family: 'SpoqaHanSansNeo-Regular'"> 가나다라ja12 <img src="https://picsum.photos/id/237/12/12" width="12" height="12" > </span>
+        </p>
+        """
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byCharWrapping))
+            .frame(width: 375)
+            .background(alignment: .top) {
+                ZStack(alignment: .topLeading) {
+                    Color.yellow.frame(height: 24).opacity(0.4)
+                    Color.red.frame(height: 32).opacity(0.4)
+                    Color.green.frame(height: 24).opacity(0.4)
+                        .padding(.top, 8)
+                }
+            }
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(3)
+        )
+    }
+
+    @MainActor
+    @Test(arguments: [LineBreakMode.byWordWrapping, LineBreakMode.byCharWrapping])
+    func testingStyleHTMLElements(lineBreakMode: LineBreakMode) async throws {
+        let html = """
+        <header>
+            <h1>Testing <span style="color: yellow; font-family: 'serif'">Basic</span> HTML Elements</h1>
+            <p>This is an example showcasing various fundamental HTML elements.</p>
+        </header>
+        
+        <main>
+            <section style="padding: 10px; margin: 20px 20px 20px 20px; background: red;">
+                <h2 style="padding: 10px; margin: 8px; background: green; color: white;">Text-related Elements</h2>
+                <p>Testing <strong>strong</strong> and <em>emphasized</em> text.<br>Also, checking line breaks (`&lt;br&gt;`).</p>
+                <p>Testing multiple line breaks:<br><br>Text remains visible after two line breaks.</p>
+            </section>
+        
+            <section style="background-color: #f5f5f5; border: 1px solid #ddd; border-radius: 8px; padding: 20px;">
+                <h2>Links and Styles</h2>
+                <p>Here's text with <span style="color: red; background-color: #ffeeee; border-radius: 4px; padding: 2px 5px;">applied styles</span> and <a href="https://example.com" target="_blank" style="background-color: #e0f0ff; border: 1px solid #0066cc; border-radius: 3px; padding: 2px 6px; text-decoration: none; color: #0066cc;">a link that opens in a new tab</a>.</p>
+            </section>
+        
+            <section style="background-color: #f9f9f9; box-shadow: 0 4px 8px rgba(0,0,0,0.1); border-radius: 8px; padding: 20px; margin: 15px 0;">
+               <h2 style="color: #333; border-bottom: 2px solid #eaeaea; padding-bottom: 10px;">List-related Elements</h2>
+               <p>An example of an unordered list:</p>
+               <ul style="background-color: white; border-radius: 6px; padding: 8px 16px; box-shadow: inset 0 0 5px rgba(0,0,0,0.5); margin-top: 16px;">
+                   <li style="padding: 8px 0;">First item</li>
+                   <li style="padding: 8px 0;">Second item</li>
+                   <li style="padding: 8px 0;">Third item</li>
+               </ul>
+            </section>
+        
+            <section>
+                <h2>Inline Elements Test</h2>
+                <p>Testing the rendering of multiple inline elements (<span>span</span>, <strong>strong</strong>, <em>em</em>) used consecutively.</p>
+            </section>
+        </main>
+        
+        <footer>
+            <p>&copy; 2025 Basic HTML Test Page</p>
+        </footer>
+        """
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
+            .frame(width: 375)
+            .fixedSize(horizontal: true, vertical: false)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            named: "\(lineBreakMode)",
+            snapshotDirectory: iosSnapshotDirectory
+        )
+    }
+
+    @MainActor
+    @Test("Image Position and Line Height Test")
+    func testImagePositionAndLineHeight() async throws {
+        let html = """
+        <h2>Image Position and Line Height Test</h2>
+        
+        <p>Various sized inline image test:
+        Text with <img src="https://picsum.photos/id/100/8/8" width="8" height="8" /> 8px image,
+        <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> 16px image,
+        <img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> 24px image,
+        <img src="https://picsum.photos/id/108/32/32" width="32" height="32" /> 32px image embedded naturally.</p>
+        
+        <p style="line-height: 24px;">Line height 24px test:
+        <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> 16px image and
+        <img src="https://picsum.photos/id/108/32/32" width="32" height="32" /> 32px image
+        to verify how they affect line height alignment.</p>
+        
+        <p>Consecutive images: <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /><img src="https://picsum.photos/id/104/20/20" width="20" height="20" /><img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> positioned adjacently like this.</p>
+        """
+        
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 375)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            named: "imagePositionAndLineHeight",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Non-English Text with Images")
+    func testNonEnglishTextWithImages() async throws {
+        let html = """
+        <h2>Non-English Text with Images</h2>
+        
+        <p>Korean sentences with <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> small icons and <img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> larger icons naturally integrated, plus bigger <img src="https://picsum.photos/id/108/32/32" width="32" height="32" /> images aligned to line height.</p>
+        
+        <p>Mixed language characters: abcdefghijk <img src="https://picsum.photos/id/103/18/18" width="18" height="18" /> lmnopqrstuv 
+        wxyzabcdefg <img src="https://picsum.photos/id/104/20/20" width="20" height="20" /> hijklmnopqr 
+        stuvwxyzabc <img src="https://picsum.photos/id/105/22/22" width="22" height="22" /> defghijklmn.</p>
+        
+        <p>Consecutive images with long text: 
+        <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /><img src="https://picsum.photos/id/103/18/18" width="18" height="18" /><img src="https://picsum.photos/id/104/20/20" width="20" height="20" />
+        Thisishowaverylongtextwithconsecutiveimageswillbehaveinlinebreakingscenarios.</p>
+        """
+        
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byCharWrapping))
+            .frame(width: 350)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 350,
+            named: "nonEnglishTextWithImages",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(3)
+        )
+    }
+
+    @MainActor
+    @Test(arguments: [LineBreakMode.byWordWrapping, LineBreakMode.byCharWrapping])
+    func testLongWordsWithImages(lineBreakMode: LineBreakMode) async throws {
+        let html = """
+        <h2>Long Words and Images Test</h2>
+        
+        <p>Long English words: Supercalifragilisticexpialidocious<img src="https://picsum.photos/id/104/20/20" width="20" height="20" />
+        and pneumonoultramicroscopicsilicovolcanoconiosis<img src="https://picsum.photos/id/102/16/16" width="16" height="16" />
+        extremelylongwordswithoutspaces<img src="https://picsum.photos/id/103/18/18" width="18" height="18" />includedintextcontent</p>
+        
+        <p>This is a verylongwordthatwillnotfitinasingleline and
+        verylongEnglishwordsthatwillneedtobreakacrosslinesexample with <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> images included in the middle.</p>
+        """
+        
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
+            .frame(width: 280)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 280,
+            named: "longWordsWithImages_\(lineBreakMode)",
+            snapshotDirectory: iosSnapshotDirectory
+        )
+    }
+
+    @MainActor
+    @Test("Complex Image Layout")
+    func testComplexImageLayout() async throws {
+        let html = """
+        <section>
+            <h2>Complex Image Layout Test</h2>
+            
+            <p>First line: <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> small image</p>
+            <p>Second line: <img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> medium image</p>
+            <p>Third line: <img src="https://picsum.photos/id/108/32/32" width="32" height="32" /> large image</p>
+            
+            <p>Consecutive images: <img src="https://picsum.photos/id/104/20/20" width="20" height="20" /><img src="https://picsum.photos/id/104/20/20" width="20" height="20" /><img src="https://picsum.photos/id/104/20/20" width="20" height="20" /></p>
+            
+            <p>Text <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> between <img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> image <img src="https://picsum.photos/id/104/20/20" width="20" height="20" /> placement</p>
+            
+            <p>Mixed sizes: 
+            <img src="https://picsum.photos/id/100/8/8" width="8" height="8" />
+            <img src="https://picsum.photos/id/101/12/12" width="12" height="12" />
+            <img src="https://picsum.photos/id/102/16/16" width="16" height="16" />
+            <img src="https://picsum.photos/id/104/20/20" width="20" height="20" />
+            <img src="https://picsum.photos/id/106/24/24" width="24" height="24" />
+            <img src="https://picsum.photos/id/107/28/28" width="28" height="28" />
+            <img src="https://picsum.photos/id/108/32/32" width="32" height="32" />
+            various sized consecutive images</p>
+        </section>
+        """
+        
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 375)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            named: "complexImageLayout",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(3)
+        )
+    }
+
+    @MainActor
+    @Test
+    func testingWordBrek() async throws {
+        let html = """
+        <body style="font-family: Arial, sans-serif; margin: 20px;">
+            <h1>Word Break Test Examples</h1>
+            
+            <!-- 일반 케이스 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Default/Normal:</p>
+                <p>This paragraph contains some normal text with spaces and then a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow to demonstrate line breaking behavior. We also include pneumonoultramicroscopicsilicovolcanoconiosis which is a very long word.</p>
+            </div>
+            
+            <!-- break-all 케이스 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">word-break: break-all</p>
+                <p style="word-break: break-all;">This paragraph contains some normal text with spaces and then a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow to demonstrate line breaking behavior. We also include pneumonoultramicroscopicsilicovolcanoconiosis which is a very long word.</p>
+            </div>
+            
+            <!-- keep-all 케이스 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">word-break: keep-all</p>
+                <p style="word-break: keep-all;">This paragraph contains some normal text with spaces and then a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow to demonstrate line breaking behavior. We also include pneumonoultramicroscopicsilicovolcanoconiosis which is a very long word.</p>
+            </div>
+            
+            <!-- break-word 케이스 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">word-break: break-word</p>
+                <p style="word-break: break-word;">This paragraph contains some normal text with spaces and then a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow to demonstrate line breaking behavior. We also include pneumonoultramicroscopicsilicovolcanoconiosis which is a very long word.</p>
+            </div>
+            
+            <!-- 상속 테스트 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8; word-break: break-all;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Parent: break-all</p>
+                <p>This text inherits parent break-all setting with a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow. The inheritance should apply automatically.</p>
+                <p style="word-break: inherit;">This text explicitly uses word-break: inherit with a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow which should result in the same behavior as the parent.</p>
+            </div>
+            
+            <!-- initial 테스트 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8; word-break: break-all;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Parent: break-all, Child: initial</p>
+                <p style="word-break: initial;">This text uses word-break: initial with a verylongwordthatwillnotfitonasinglelineandwillneedtobreaksomehow which should ignore the parent's break-all setting and use the default behavior instead.</p>
+            </div>
+            
+            <!-- 다국어 테스트 - 한국어 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Korean Text - Default:</p>
+                <p>이것은한국어로된매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우긴단어입니다 그리고 다음은 약간의 영어 텍스트입니다 with some long words interspersed.</p>
+            </div>
+            
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Korean Text - break-all:</p>
+                <p style="word-break: break-all;">이것은한국어로된매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우긴단어입니다 그리고 다음은 약간의 영어 텍스트입니다 with some long words interspersed.</p>
+            </div>
+            
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Korean Text - keep-all:</p>
+                <p style="word-break: keep-all;">이것은한국어로된매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우매우긴단어입니다 그리고 다음은 약간의 영어 텍스트입니다 with some long words interspersed.</p>
+            </div>
+            
+            <!-- 중국어 테스트 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Chinese Text - Default:</p>
+                <p>这是一个非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常长的中文单词示例 mixed with some English text to see how it breaks.</p>
+            </div>
+            
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Chinese Text - break-all:</p>
+                <p style="word-break: break-all;">这是一个非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常长的中文单词示例 mixed with some English text to see how it breaks.</p>
+            </div>
+            
+            <!-- 특수 문자 테스트 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">URL - Default:</p>
+                <p>Please visit https://www.thisisaverylongdomainnamethatwillnotfitonasingleline.com/path/to/resource?param=value&anotherparam=test&evenmoreparam=value for more information.</p>
+            </div>
+            
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">URL - break-all:</p>
+                <p style="word-break: break-all;">Please visit https://www.thisisaverylongdomainnamethatwillnotfitonasingleline.com/path/to/resource?param=value&anotherparam=test&evenmoreparam=value for more information.</p>
+            </div>
+            
+            <!-- 이메일 테스트 -->
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Email - Default:</p>
+                <p>Please contact verylongemailaddressthatwillnotfitonasingleline@extremelylongdomainname.com for assistance.</p>
+            </div>
+            
+            <div style="width: 200px; margin: 20px 0; padding: 10px; border: 1px solid #ccc; background-color: #f8f8f8;">
+                <p style="font-weight: bold; margin-bottom: 5px;">Email - break-all:</p>
+                <p style="word-break: break-all;">Please contact verylongemailaddressthatwillnotfitonasingleline@extremelylongdomainname.com for assistance.</p>
+            </div>
+        </body>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 375)
+            .fixedSize(horizontal: true, vertical: false)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 375,
+            snapshotDirectory: iosSnapshotDirectory
+        )
+    }
+
+    @MainActor
+    @Test("Yomitan entry snapshot (macOS)")
+    func testYomitanEntrySnapshotMacOS() async throws {
+        let html = """
+        <div class="yomitan-entry" style="line-height: 1.4">
+            <div class="yomitan-headword" style="margin-bottom: 4">
+                <span class="yomitan-expression">場面</span>
+                <span class="yomitan-reading" style="margin-left: 4">[ばめん]</span>
+            </div>
+            <div class="yomitan-dictionary-title" style="margin-bottom: 4">JMdict [2026-01-17]</div>
+            <div class="yomitan-glossary">
+                <div class="yomitan-glossary-item" style="margin-bottom: 4">
+                    <ul lang="en" data-content="glossary" style="list-style-type:circle;">
+                        <li>scene</li>
+                        <li>setting</li>
+                        <li>place (where something happens)</li>
+                        <li>scenario</li>
+                        <li>case</li>
+                    </ul>
+                </div>
+            </div>
+        </div>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 320,
+            named: "yomitanEntry",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Ruby annotation snapshot (macOS)")
+    func testRubyAnnotationSnapshotMacOS() async throws {
+        setenv("SNAPSHOT_ARTIFACTS", "/private/tmp/swiftuihtml-macos-artifacts-current", 1)
+        let html = """
+        <div style="font-size: 26px; line-height: 1.5;">
+            <p style="margin: 0 0 8px 0; font-weight: 600;">Ruby annotation demo</p>
+            <p style="margin: 0 0 10px 0;">
+                <ruby style="ruby-position: over;">
+                    漢字<rt style="font-size: 0.6em; color: #1b5e20;">かんじ</rt>
+                </ruby>
+                を読む
+            </p>
+            <p style="margin: 0;">
+                <ruby style="ruby-position: under;">
+                    東京<rt style="font-size: 0.55em; color: #0d47a1;">とうきょう</rt>
+                </ruby>
+                <span style="font-size: 20px;">travel</span>
+            </p>
+        </div>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320)
+            .fixedSize(horizontal: false, vertical: true)
+
+        writeHTMLArtifact(
+            html,
+            testName: "testRubyAnnotationSnapshot",
+            name: "rubyAnnotation"
+        )
+        try await MacViewSnapshotTester.snapshot(
+            of: view,
+            width: 320,
+            named: "rubyAnnotation",
+            snapshotDirectory: iosSnapshotDirectory,
+            sleep: .seconds(2),
+            testName: "testRubyAnnotationSnapshot"
+        )
+    }
+}
+
+private func writeHTMLArtifact(_ html: String, testName: String, name: String) {
+    let root: String
+    if let existing = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"] {
+        root = existing
+    } else {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyyMMdd-HHmmss"
+        let stamp = formatter.string(from: Date())
+        root = "/tmp/swiftuihtml-macos-artifacts-\(stamp)"
+        setenv("SNAPSHOT_ARTIFACTS", root, 1)
+    }
+    let safeTestName = sanitizeSnapshotComponent(testName)
+    let safeName = sanitizeSnapshotComponent(name)
+    let artifactDir = URL(fileURLWithPath: root, isDirectory: true)
+        .appendingPathComponent("YomitanSnapshotTests")
+    let htmlURL = artifactDir
+        .appendingPathComponent("\(safeTestName).\(safeName)")
+        .appendingPathExtension("html")
+    do {
+        try FileManager.default.createDirectory(
+            at: artifactDir,
+            withIntermediateDirectories: true
+        )
+        try html.write(to: htmlURL, atomically: true, encoding: .utf8)
+    } catch {
+        AttachmentDebugLogger.record("[Snapshot] html artifact write failed \(error.localizedDescription)")
+    }
+}
+
+private func sanitizeSnapshotComponent(_ string: String) -> String {
+    let sanitized = string.replacingOccurrences(
+        of: "\\W+",
+        with: "-",
+        options: .regularExpression
+    )
+    return sanitized.replacingOccurrences(
+        of: "^-|-$",
+        with: "",
+        options: .regularExpression
+    )
+}
+#endif
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testComplexImageLayout.complexImageLayout.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testComplexImageLayout.complexImageLayout.png
new file mode 100644
index 0000000..1bd9258
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testComplexImageLayout.complexImageLayout.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byCharWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byCharWrapping.png
new file mode 100644
index 0000000..75d8107
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byWordWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byWordWrapping.png
new file mode 100644
index 0000000..04636c5
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageAndNesting-width-lineBreakMode.375-byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageWithLineHeight.1.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageWithLineHeight.1.png
new file mode 100644
index 0000000..38a8602
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testHTMLImageWithLineHeight.1.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testImagePositionAndLineHeight.imagePositionAndLineHeight.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testImagePositionAndLineHeight.imagePositionAndLineHeight.png
new file mode 100644
index 0000000..1d05c24
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testImagePositionAndLineHeight.imagePositionAndLineHeight.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png
new file mode 100644
index 0000000..4e17587
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png
new file mode 100644
index 0000000..985bf50
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testNonEnglishTextWithImages.nonEnglishTextWithImages.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testNonEnglishTextWithImages.nonEnglishTextWithImages.png
new file mode 100644
index 0000000..897b387
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testNonEnglishTextWithImages.nonEnglishTextWithImages.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png
new file mode 100644
index 0000000..73294e4
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byCharWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byCharWrapping.png
new file mode 100644
index 0000000..3976e57
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byWordWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byWordWrapping.png
new file mode 100644
index 0000000..29d298c
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingBasicHTMLElements-lineBreakMode.byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byCharWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byCharWrapping.png
new file mode 100644
index 0000000..96b8c81
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byWordWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byWordWrapping.png
new file mode 100644
index 0000000..96b8c81
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingLineBreak-lineBreakMode.byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byCharWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byCharWrapping.png
new file mode 100644
index 0000000..5ef6320
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byWordWrapping.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byWordWrapping.png
new file mode 100644
index 0000000..0ca700e
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingStyleHTMLElements-lineBreakMode.byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingWordBrek.1.png b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingWordBrek.1.png
new file mode 100644
index 0000000..981ecf7
Binary files /dev/null and b/SwiftUIHTMLExampleMacOSTests/__Snapshots__/YomitanSnapshotTests/testingWordBrek.1.png differ
diff --git a/SwiftUIHTMLExampleMacOSUITests/SwiftUIHTMLExampleMacOSUITests.swift b/SwiftUIHTMLExampleMacOSUITests/SwiftUIHTMLExampleMacOSUITests.swift
new file mode 100644
index 0000000..a8f247e
--- /dev/null
+++ b/SwiftUIHTMLExampleMacOSUITests/SwiftUIHTMLExampleMacOSUITests.swift
@@ -0,0 +1,55 @@
+import XCTest
+
+final class SwiftUIHTMLExampleMacOSUITests: XCTestCase {
+    override func setUp() {
+        continueAfterFailure = false
+    }
+
+    func testRenderingResultShowsSnapshotHTML() {
+        let app = XCUIApplication()
+        app.launch()
+
+        let snapshotCell = app.descendants(matching: .any)
+            .matching(NSPredicate(format: "label == %@", "Snapshot Test Preview"))
+            .firstMatch
+        if !snapshotCell.waitForExistence(timeout: 10) {
+            if app.outlines.firstMatch.exists {
+                app.outlines.firstMatch.scrollToElement(snapshotCell)
+            } else if app.tables.firstMatch.exists {
+                app.tables.firstMatch.scrollToElement(snapshotCell)
+            } else if app.scrollViews.firstMatch.exists {
+                app.scrollViews.firstMatch.scrollToElement(snapshotCell)
+            }
+        }
+        assertExists(snapshotCell, timeout: 10, name: "Snapshot Test Preview")
+        snapshotCell.click()
+
+        assertExists(app.staticTexts["Rendering Result"], timeout: 10, name: "Rendering Result")
+    }
+
+    private func assertExists(_ element: XCUIElement, timeout: TimeInterval, name: String) {
+        if element.waitForExistence(timeout: timeout) {
+            return
+        }
+
+        print("Missing \(name). App hierarchy:\n\(XCUIApplication().debugDescription)")
+        let screenshot = XCUIScreen.main.screenshot()
+        let attachment = XCTAttachment(screenshot: screenshot)
+        attachment.name = "Missing-\(name)"
+        attachment.lifetime = .keepAlways
+        add(attachment)
+
+        XCTFail("Expected to find \(name).")
+    }
+}
+
+private extension XCUIElement {
+    func scrollToElement(_ element: XCUIElement) {
+        var attempts = 0
+        while !element.exists && attempts < 12 {
+            let coord = coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5))
+            coord.scroll(byDeltaX: 0, deltaY: -400)
+            attempts += 1
+        }
+    }
+}
diff --git a/SwiftUIHTMLExampleTests/HTMLBasicTests.swift b/SwiftUIHTMLExampleTests/HTMLBasicTests.swift
index fc89a27..bd20538 100644
--- a/SwiftUIHTMLExampleTests/HTMLBasicTests.swift
+++ b/SwiftUIHTMLExampleTests/HTMLBasicTests.swift
@@ -1,10 +1,10 @@
 //  Copyright © 2025 PRND. All rights reserved.
+#if os(iOS)
 import SwiftUI
 import Testing
 
 @testable import SwiftUIHTML
 @testable import SwiftUIHTMLExample
-import SnapshotTesting
 
 class HTMLBasicTests {
     
@@ -49,13 +49,18 @@ class HTMLBasicTests {
             <p>&copy; 2025 Basic HTML Test Page</p>
         </footer>
         """
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
             .frame(width: 375)
             .fixedSize(horizontal: true, vertical: false)
 
-        assertSnapshot(of: view, as: .image, named: "\(lineBreakMode)")
+        try? await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "\(lineBreakMode)",
+            html: html,
+            sleep: .seconds(2)
+        )
     }
 
     @MainActor
@@ -75,12 +80,17 @@ class HTMLBasicTests {
         외관과 실내 컨디션이 깔끔한 차량입니다.
         파노라믹 글라스 루프가 적용되어 개방감 있는 가능합니다.</p>
         """
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
             .frame(width: 233, alignment: .leading)
             .fixedSize(horizontal: true, vertical: false)
-        assertSnapshot(of: view, as: .image, named: "\(lineBreakMode)")
+        try? await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "\(lineBreakMode)",
+            html: html,
+            sleep: .seconds(2)
+        )
     }
 
     @MainActor
@@ -133,7 +143,7 @@ class HTMLBasicTests {
             <p>&copy; 2025 HTML Nesting Test Page</p>
         </footer>
         """
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
             .frame(width: width)
@@ -142,6 +152,7 @@ class HTMLBasicTests {
         try? await ViewSnapshotTester.snapshot(
             of: view,
             named: "\(Int(width)),\(lineBreakMode)",
+            html: html,
             sleep: .seconds(2)
         )
     }
@@ -156,7 +167,7 @@ class HTMLBasicTests {
         <span style="font-family: 'SpoqaHanSansNeo-Regular'"> 가나다라ja12 <img src="https://picsum.photos/id/237/12/12" width="12" height="12" > </span>
         </p>
         """
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: .byCharWrapping))
             .frame(width: 375)
@@ -172,6 +183,7 @@ class HTMLBasicTests {
 
         try? await ViewSnapshotTester.snapshot(
             of: view,
+            html: html,
             sleep: .seconds(3)
         )
     }
@@ -218,12 +230,17 @@ class HTMLBasicTests {
             <p>&copy; 2025 Basic HTML Test Page</p>
         </footer>
         """
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
             .frame(width: 375)
             .fixedSize(horizontal: true, vertical: false)
-        assertSnapshot(of: view, as: .image, named: "\(lineBreakMode)")
+        try? await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "\(lineBreakMode)",
+            html: html,
+            sleep: .seconds(2)
+        )
     }
 
     @MainActor
@@ -246,7 +263,7 @@ class HTMLBasicTests {
         <p>Consecutive images: <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /><img src="https://picsum.photos/id/104/20/20" width="20" height="20" /><img src="https://picsum.photos/id/106/24/24" width="24" height="24" /> positioned adjacently like this.</p>
         """
         
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
             .frame(width: 375)
@@ -255,6 +272,7 @@ class HTMLBasicTests {
         try? await ViewSnapshotTester.snapshot(
             of: view,
             named: "imagePositionAndLineHeight",
+            html: html,
             sleep: .seconds(2)
         )
     }
@@ -276,7 +294,7 @@ class HTMLBasicTests {
         Thisishowaverylongtextwithconsecutiveimageswillbehaveinlinebreakingscenarios.</p>
         """
         
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: .byCharWrapping))
             .frame(width: 350)
@@ -285,6 +303,7 @@ class HTMLBasicTests {
         try? await ViewSnapshotTester.snapshot(
             of: view,
             named: "nonEnglishTextWithImages",
+            html: html,
             sleep: .seconds(3)
         )
     }
@@ -303,13 +322,18 @@ class HTMLBasicTests {
         verylongEnglishwordsthatwillneedtobreakacrosslinesexample with <img src="https://picsum.photos/id/102/16/16" width="16" height="16" /> images included in the middle.</p>
         """
         
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: lineBreakMode))
             .frame(width: 280)
             .fixedSize(horizontal: false, vertical: true)
 
-        assertSnapshot(of: view, as: .image, named: "longWordsWithImages_\(lineBreakMode)")
+        try? await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "longWordsWithImages_\(lineBreakMode)",
+            html: html,
+            sleep: .seconds(2)
+        )
     }
 
     @MainActor
@@ -339,7 +363,7 @@ class HTMLBasicTests {
         </section>
         """
         
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
             .frame(width: 375)
@@ -348,6 +372,7 @@ class HTMLBasicTests {
         try? await ViewSnapshotTester.snapshot(
             of: view,
             named: "complexImageLayout",
+            html: html,
             sleep: .seconds(3)
         )
     }
@@ -447,15 +472,319 @@ class HTMLBasicTests {
         </body>
         """
 
-        let view = HTMLView(html: html, parser: HTMLFuziParser())
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
             .htmlEnvironment(\.configuration, .sample)
             .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
             .frame(width: 375)
             .fixedSize(horizontal: true, vertical: false)
-        assertSnapshot(of: view, as: .image)
+            .background(WordBrekFrameReporter(label: "HTMLView"))
+            .coordinateSpace(name: "WordBrekSpace")
+            .background(WordBrekFrameReporter(label: "Root"))
+        try? await ViewSnapshotTester.snapshot(
+            of: view,
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Yomitan entry snapshot")
+    func testYomitanEntrySnapshot() async throws {
+        let html = """
+        <div class="yomitan-entry" style="line-height: 1.4">
+            <div class="yomitan-headword" style="margin-bottom: 4">
+                <span class="yomitan-expression">場面</span>
+                <span class="yomitan-reading" style="margin-left: 4">[ばめん]</span>
+            </div>
+            <div class="yomitan-dictionary-title" style="margin-bottom: 4">JMdict [2026-01-17]</div>
+            <div class="yomitan-glossary">
+                <div class="yomitan-glossary-item" style="margin-bottom: 4">
+                    <ul lang="en" data-content="glossary" style="list-style-type:circle;">
+                        <li>scene</li>
+                        <li>setting</li>
+                        <li>place (where something happens)</li>
+                        <li>scenario</li>
+                        <li>case</li>
+                    </ul>
+                </div>
+            </div>
+        </div>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "yomitanEntry",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Ruby annotation snapshot")
+    func testRubyAnnotationSnapshot() async throws {
+        let html = """
+        <div style="font-size: 26px; line-height: 1.5;">
+            <p style="margin: 0 0 8px 0; font-weight: 600;">Ruby annotation demo</p>
+            <p style="margin: 0 0 10px 0;">
+                <ruby style="ruby-position: over;">
+                    漢字<rt style="font-size: 0.6em; color: #1b5e20;">かんじ</rt>
+                </ruby>
+                を読む
+            </p>
+            <p style="margin: 0;">
+                <ruby style="ruby-position: under;">
+                    東京<rt style="font-size: 0.55em; color: #0d47a1;">とうきょう</rt>
+                </ruby>
+                <span style="font-size: 20px;">travel</span>
+            </p>
+        </div>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320)
+            .fixedSize(horizontal: false, vertical: true)
+
+        writeHTMLArtifact(
+            html,
+            testName: "testRubyAnnotationSnapshot",
+            name: "rubyAnnotation"
+        )
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "rubyAnnotation",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Ruby annotation snapshot (vanilla)")
+    func testRubyAnnotationSnapshotVanilla() async throws {
+        let html = """
+        <div style="font-size: 22px; line-height: 1.5;">
+            <p style="margin: 0 0 8px 0;">Ruby annotation vanilla</p>
+            <p style="margin: 0 0 8px 0;">
+                <ruby>漢字<rt>かんじ</rt></ruby>を読む
+            </p>
+            <p style="margin: 0;">
+                <ruby>東京<rt>とうきょう</rt></ruby>travel
+            </p>
+        </div>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320)
+            .fixedSize(horizontal: false, vertical: true)
+
+        writeHTMLArtifact(
+            html,
+            testName: "testRubyAnnotationSnapshotVanilla",
+            name: "rubyAnnotationVanilla"
+        )
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "rubyAnnotationVanilla",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Margin square snapshot")
+    func testMarginSquareSnapshot() async throws {
+        let font = UIFont.systemFont(ofSize: 12)
+        var style = HTMLStyleContainer()
+        style.uiFont = font
+        style.textLine = .lineSpacing(spacing: 0)
+        style.lineBreakMode = .byWordWrapping
+        let html = "<body style=\"margin: 20px;\"><div style=\"width: 20px; height: 20px; background-color: black\"></div></body>"
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, style)
+            .frame(width: 200, alignment: .topLeading)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "marginSquare",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Double margin square stack")
+    func testDoubleMarginSquares() async throws {
+        let html = """
+        <body style="margin: 20px;">
+            <div style="width: 200px; height: 200px; margin: 20px 0; background-color: black"></div>
+            <div style="width: 200px; height: 200px; margin: 20px 0; background-color: black"></div>
+        </body>
+        """
+
+        let configuration = HTMLConfiguration.sample.collapsingBlockMargins(true)
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, configuration)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 240, alignment: .topLeading)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "doubleMarginSquares",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("List item square snapshot")
+    func testListItemSquareSnapshot() async throws {
+        let html = "<body><ul><li><img src=\"https://dummyimage.com/10x10/000/000.png\" width=\"10\" height=\"10\" /></li></ul></body>"
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 200, alignment: .topLeading)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "listItemSquare",
+            html: html,
+            sleep: .seconds(2)
+        )
+    }
+
+    @MainActor
+    @Test("Bullet image alignment")
+    func testBulletImageAlignment() async throws {
+        let html = """
+        <main>
+            <section>
+                <ul>
+                    <li>O&nbsp;<a href=\"#\" style=\"text-decoration:none\">O</a></li>
+                </ul>
+            </section>
+        </main>
+        """
+
+        let view = HTMLView(html: html, parser: HTMLSwiftSoupParser())
+            .htmlEnvironment(\.configuration, .sample)
+            .htmlEnvironment(\.styleContainer, .sample(by: .byWordWrapping))
+            .frame(width: 320, alignment: .topLeading)
+            .fixedSize(horizontal: false, vertical: true)
+
+        try await ViewSnapshotTester.snapshot(
+            of: view,
+            named: "bulletImageAlignment",
+            html: html,
+            sleep: .seconds(2)
+        )
     }
 }
 
+private struct WordBrekFrameReporter: View {
+    let label: String
+
+    var body: some View {
+        GeometryReader { proxy in
+            let snapshot = WordBrekFrameSnapshot(
+                size: proxy.size,
+                local: proxy.frame(in: .local),
+                named: proxy.frame(in: .named("WordBrekSpace")),
+                global: proxy.frame(in: .global)
+            )
+            Color.clear
+                .modifier(OnChangeViewModifier(of: snapshot, initial: true) { _, newValue in
+                    AttachmentDebugLogger.record(
+                        "[WordBrek] \(label) size=\(newValue.size) local=\(newValue.local) named=\(newValue.named) global=\(newValue.global)"
+                    )
+                })
+        }
+    }
+}
+
+private struct WordBrekAttributeStyler: AttributeStyleable {
+    private let fallback = DefaultAttributeStyler()
+
+    func layoutStyle(attributes: [String : AttributeValue]) -> some ViewModifier {
+        fallback.layoutStyle(attributes: attributes)
+    }
+
+    func applyStyles(attributes: [String : AttributeValue], to styleContainer: inout HTMLStyleContainer) {
+        guard let cssStyle = attributes["style"]?.cssStyle else { return }
+
+        if let color = cssStyle["color"]?.toColor() {
+            styleContainer.foregroundColor = color
+        }
+
+        if let color = cssStyle["background-color"]?.toColor() {
+            styleContainer.backgroundColor = color
+        }
+
+        if let rawLineHeight = cssStyle["line-height"]?.string,
+           let font = styleContainer.uiFont,
+           let lineHeight = resolveLineHeightWordBrek(rawLineHeight, font: font) {
+            styleContainer.textLine = .lineHeight(font: font, lineHeight: lineHeight)
+        } else if let lineSpacing = cssStyle["line-spacing"]?.cgFloat {
+            styleContainer.textLine = .lineSpacing(spacing: lineSpacing)
+        }
+
+        if cssStyle["font-family"]?.string != nil,
+           let current = styleContainer.uiFont,
+           let arial = PlatformFont(name: "ArialMT", size: current.pointSize) {
+            styleContainer.uiFont = arial
+        }
+
+        // Intentionally ignore word-break for WordBrek baseline alignment.
+    }
+}
+
+private func resolveLineHeightWordBrek(_ rawValue: String, font: PlatformFont) -> CGFloat? {
+    let trimmed = ASCIIWhitespace.trim(rawValue)
+    guard !trimmed.isEmpty else { return nil }
+    let value = String(trimmed)
+    let lowered = value.lowercased()
+
+    if lowered == "normal" || lowered == "inherit" || lowered == "initial" || lowered == "unset" {
+        return font.manabiLineHeight
+    }
+
+    if lowered.hasSuffix("px")
+        || lowered.hasSuffix("pt")
+        || lowered.hasSuffix("em")
+        || lowered.hasSuffix("rem")
+        || lowered.hasSuffix("%") {
+        return CSSFontUtility.parseSize(fromFontSize: value, baseSize: font.pointSize)
+    }
+
+    if let multiplier = Double(lowered) {
+        return font.pointSize * CGFloat(multiplier)
+    }
+
+    return nil
+}
+
+private struct WordBrekFrameSnapshot: Equatable {
+    let size: CGSize
+    let local: CGRect
+    let named: CGRect
+    let global: CGRect
+}
+#endif
+
 
 extension UIView {
     func pinToTopLeading(of superview: UIView, topInset: CGFloat = 0, leadingInset: CGFloat = 0) {
@@ -468,6 +797,40 @@ extension UIView {
     }
 }
 
+private func writeHTMLArtifact(_ html: String, testName: String, name: String) {
+    let root = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"]
+        ?? "/tmp/swiftuihtml-ios-artifacts"
+    let safeTestName = sanitizeSnapshotComponent(testName)
+    let safeName = sanitizeSnapshotComponent(name)
+    let artifactDir = URL(fileURLWithPath: root, isDirectory: true)
+        .appendingPathComponent("HTMLBasicTests")
+    let htmlURL = artifactDir
+        .appendingPathComponent("\(safeTestName).\(safeName)")
+        .appendingPathExtension("html")
+    do {
+        try FileManager.default.createDirectory(
+            at: artifactDir,
+            withIntermediateDirectories: true
+        )
+        try html.write(to: htmlURL, atomically: true, encoding: .utf8)
+    } catch {
+        AttachmentDebugLogger.record("[Snapshot] html artifact write failed \(error.localizedDescription)")
+    }
+}
+
+private func sanitizeSnapshotComponent(_ string: String) -> String {
+    let sanitized = string.replacingOccurrences(
+        of: "\\W+",
+        with: "-",
+        options: .regularExpression
+    )
+    return sanitized.replacingOccurrences(
+        of: "^-|-$",
+        with: "",
+        options: .regularExpression
+    )
+}
+
 extension HTMLStyleContainer {
     static func totalInfo() -> HTMLStyleContainer {
         var style = HTMLStyleContainer()
diff --git a/SwiftUIHTMLExampleTests/HTMLBasicXCTest.swift b/SwiftUIHTMLExampleTests/HTMLBasicXCTest.swift
new file mode 100644
index 0000000..f39847b
--- /dev/null
+++ b/SwiftUIHTMLExampleTests/HTMLBasicXCTest.swift
@@ -0,0 +1,100 @@
+//  Copyright © 2025 PRND. All rights reserved.
+#if os(iOS)
+import XCTest
+
+@testable import SwiftUIHTML
+@testable import SwiftUIHTMLExample
+
+@MainActor
+final class HTMLBasicXCTest: XCTestCase {
+    private let sut = HTMLBasicTests()
+
+    func testTestingBasicHTMLElements_byWordWrapping() async throws {
+        try await sut.testingBasicHTMLElements(lineBreakMode: .byWordWrapping)
+    }
+
+    func testTestingBasicHTMLElements_byCharWrapping() async throws {
+        try await sut.testingBasicHTMLElements(lineBreakMode: .byCharWrapping)
+    }
+
+    func testTestingLineBreak_byCharWrapping() async throws {
+        try await sut.testingLineBreak(lineBreakMode: .byCharWrapping)
+    }
+
+    func testTestingLineBreak_byWordWrapping() async throws {
+        try await sut.testingLineBreak(lineBreakMode: .byWordWrapping)
+    }
+
+    func testHTMLImageAndNesting_375_byCharWrapping() async throws {
+        try await sut.testHTMLImageAndNesting(width: 375, lineBreakMode: .byCharWrapping)
+    }
+
+    func testHTMLImageAndNesting_375_byWordWrapping() async throws {
+        try await sut.testHTMLImageAndNesting(width: 375, lineBreakMode: .byWordWrapping)
+    }
+
+    func testHTMLImageWithLineHeight() async throws {
+        try await sut.testHTMLImageWithLineHeight()
+    }
+
+    func testTestingStyleHTMLElements_byWordWrapping() async throws {
+        try await sut.testingStyleHTMLElements(lineBreakMode: .byWordWrapping)
+    }
+
+    func testTestingStyleHTMLElements_byCharWrapping() async throws {
+        try await sut.testingStyleHTMLElements(lineBreakMode: .byCharWrapping)
+    }
+
+    func testImagePositionAndLineHeight() async throws {
+        try await sut.testImagePositionAndLineHeight()
+    }
+
+    func testNonEnglishTextWithImages() async throws {
+        try await sut.testNonEnglishTextWithImages()
+    }
+
+    func testLongWordsWithImages_byWordWrapping() async throws {
+        try await sut.testLongWordsWithImages(lineBreakMode: .byWordWrapping)
+    }
+
+    func testLongWordsWithImages_byCharWrapping() async throws {
+        try await sut.testLongWordsWithImages(lineBreakMode: .byCharWrapping)
+    }
+
+    func testComplexImageLayout() async throws {
+        try await sut.testComplexImageLayout()
+    }
+
+    func testTestingWordBrek() async throws {
+        try await sut.testingWordBrek()
+    }
+
+    func testYomitanEntrySnapshot() async throws {
+        try await sut.testYomitanEntrySnapshot()
+    }
+
+    func testRubyAnnotationSnapshot() async throws {
+        try await sut.testRubyAnnotationSnapshot()
+    }
+
+    func testRubyAnnotationSnapshotVanilla() async throws {
+        try await sut.testRubyAnnotationSnapshotVanilla()
+    }
+
+    func testMarginSquareSnapshot() async throws {
+        try await sut.testMarginSquareSnapshot()
+    }
+
+    func testDoubleMarginSquares() async throws {
+        try await sut.testDoubleMarginSquares()
+    }
+
+    func testListItemSquareSnapshot() async throws {
+        try await sut.testListItemSquareSnapshot()
+    }
+
+    func testBulletImageAlignment() async throws {
+        try await sut.testBulletImageAlignment()
+    }
+}
+#endif
diff --git a/SwiftUIHTMLExampleTests/ViewSnapshotTester.swift b/SwiftUIHTMLExampleTests/ViewSnapshotTester.swift
index 9fad0c4..3dcea43 100644
--- a/SwiftUIHTMLExampleTests/ViewSnapshotTester.swift
+++ b/SwiftUIHTMLExampleTests/ViewSnapshotTester.swift
@@ -1,16 +1,59 @@
 //  Copyright © 2025 PRND. All rights reserved.
+#if os(iOS)
+import CryptoKit
 import SwiftUI
 import UIKit
+import XCTest
+import Vision
 
-import SnapshotTesting
+@testable import SwiftUIHTML
+@_spi(Internals) import SnapshotTesting
 
 /// Utility class for rendering SwiftUI views in UIKit environment and generating snapshots
 class ViewSnapshotTester {
+    private final class SizeObserver: ObservableObject {
+        @Published var size: CGSize = .zero
+    }
+
+    private struct SnapshotSizePreferenceKey: PreferenceKey {
+        static var defaultValue: CGSize = .zero
+        static func reduce(value: inout CGSize, nextValue: () -> CGSize) {
+            let next = nextValue()
+            if next.width > 1 && next.height > 1 {
+                value = next
+            }
+        }
+    }
+
+    private struct SnapshotProbeView<Content: View>: View {
+        @ObservedObject var observer: SizeObserver
+        let content: Content
+
+        var body: some View {
+            content
+                .background(
+                    GeometryReader { proxy in
+                        Color.clear
+                            .preference(key: SnapshotSizePreferenceKey.self, value: proxy.size)
+                    }
+                )
+                .onPreferenceChange(SnapshotSizePreferenceKey.self) { newValue in
+                    if newValue.width > 1 && newValue.height > 1 {
+                        observer.size = newValue
+                    }
+                }
+        }
+    }
+
+    private static var diagnosticLogDirectory: URL {
+        artifactsRootURL().appendingPathComponent("diag", isDirectory: true)
+    }
 
     @MainActor
     static func snapshot<V: View>(
         of view: V,
         named name: String? = nil,
+        html: String? = nil,
         record recording: Bool? = nil,
         sleep sleepDuration: Duration = .seconds(2),
         fileID: StaticString = #fileID,
@@ -19,52 +62,152 @@ class ViewSnapshotTester {
         line: UInt = #line,
         column: UInt = #column
     ) async throws {
-        // Wrap SwiftUI view as UIKit view
-        let rootView = view.background(Color.white).compositingGroup().ignoresSafeArea()
-        let hostingView = UIHostingController(rootView: rootView).view!
-
-        // Create container view controller
-        let viewController = UIViewController()
-        viewController.view.addSubview(hostingView)
-        
-        // Setup auto layout
-        hostingView.translatesAutoresizingMaskIntoConstraints = false
-        NSLayoutConstraint.activate([
-            hostingView.topAnchor.constraint(equalTo: viewController.view.topAnchor),
-            hostingView.leadingAnchor.constraint(equalTo: viewController.view.leadingAnchor)
-        ])
-
-        // Create and display window
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_ATTACHMENT_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_MARGIN_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_INLINE_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_PARSER_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_BLOCK_LOGS")
+        UserDefaults.standard.set(true, forKey: "SWIFTUIHTML_FONT_LOGS")
+        setenv("SWIFTUIHTML_ATTACHMENT_LOGS", "1", 1)
+        setenv("SWIFTUIHTML_ATTACHMENT_DIAGNOSTICS", "1", 1)
+        setenv("SWIFTUIHTML_MARGIN_LOGS", "1", 1)
+        setenv("SWIFTUIHTML_INLINE_LOGS", "1", 1)
+        setenv("SWIFTUIHTML_PARSER_LOGS", "1", 1)
+        setenv("SWIFTUIHTML_BLOCK_LOGS", "1", 1)
+        setenv("SWIFTUIHTML_FONT_LOGS", "1", 1)
+        let artifactsURL = ensureSnapshotArtifactsDirectory(filePath: filePath)
+        AttachmentDebugLogger.record("[Snapshot] artifactsRoot=\(artifactsURL.path)")
+        rawLog("[Raw] artifactsRoot=\(artifactsURL.path)")
+        setenv(
+            "SWIFTUIHTML_ATTACHMENT_LOG_PATH",
+            artifactsURL.appendingPathComponent("swiftuihtml-attachment.log").path,
+            1
+        )
+        setenv("SWIFTUIHTML_ATTACHMENT_LOG_PRESERVE", "1", 1)
+        AttachmentDebugLogger.clear()
+        rawLog("[Raw] snapshot start: \(testName)")
+        rawLog("[Raw] SNAPSHOT_ARTIFACTS=\(ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"] ?? "nil")")
+        writeProbeFile(testName: testName, name: name)
+        writeLocationProbe(testName: testName, name: name)
+        AttachmentDebugLogger.record("[TestHarness] snapshot start: \(testName)")
+        let sizeObserver = SizeObserver()
+        let rootView = SnapshotProbeView(
+            observer: sizeObserver,
+            content: view.background(Color.white).compositingGroup()
+        )
+        let hostingController = UIHostingController(rootView: rootView)
+        let hostingView = hostingController.view!
+        hostingView.insetsLayoutMarginsFromSafeArea = false
+        hostingView.preservesSuperviewLayoutMargins = false
+        hostingView.layoutMargins = .zero
+        if #available(iOS 11.0, *) {
+            hostingView.directionalLayoutMargins = .zero
+        }
+
         let window = UIWindow(frame: UIScreen.main.bounds)
-        window.rootViewController = viewController
+        window.rootViewController = hostingController
         window.makeKeyAndVisible()
-        
-        // Wait for layout calculation time
+
         try await Task.sleep(for: sleepDuration)
 
-        // Force layout update
         await MainActor.run {
-            viewController.view.layoutIfNeeded()
-            viewController.view.setNeedsLayout()
+            hostingController.view.layoutIfNeeded()
+            hostingController.view.setNeedsLayout()
             hostingView.invalidateIntrinsicContentSize()
         }
-        
-        // Find rendered view
+
+        let observedSize = await MainActor.run { sizeObserver.size }
+        AttachmentDebugLogger.record("[Snapshot] observedSize=\(observedSize)")
+        rawLog("[Raw] observedSize=\(observedSize)")
+        let resolvedSize = resolvedSize(
+            for: hostingController,
+            fallbackView: hostingView,
+            observedSize: observedSize
+        )
+        AttachmentDebugLogger.record("[Snapshot] resolvedSize=\(resolvedSize)")
+        rawLog("[Raw] resolvedSize=\(resolvedSize)")
+        hostingView.frame = CGRect(origin: .zero, size: resolvedSize)
+        hostingView.bounds = CGRect(origin: .zero, size: resolvedSize)
+        hostingController.view.layoutIfNeeded()
+        AttachmentDebugLogger.record(
+            "[Snapshot] hostingView bounds=\(hostingView.bounds) frame=\(hostingView.frame)"
+        )
+        rawLog("[Raw] hostingView bounds=\(hostingView.bounds) frame=\(hostingView.frame)")
+
         guard let renderedView = findActualRenderedView(in: hostingView) else {
             throw SnapshotError.viewNotFound
         }
+        renderedView.layoutIfNeeded()
+        AttachmentDebugLogger.record(
+            "[Snapshot] renderedView type=\(String(describing: type(of: renderedView))) bounds=\(renderedView.bounds) frame=\(renderedView.frame)"
+        )
+        rawLog("[Raw] renderedView type=\(String(describing: type(of: renderedView))) bounds=\(renderedView.bounds) frame=\(renderedView.frame)")
+        let bounds = contentBounds(in: hostingView)
+        rawLog("[Raw] contentBounds=\(bounds)")
+        writeMetricsArtifact(
+            testName: testName,
+            name: name,
+            metrics: "resolvedSize=\(resolvedSize)\nhostingViewBounds=\(hostingView.bounds)\ncontentBounds=\(bounds)\n"
+        )
+
+        let waitImages = await ImageLoadTracker.shared.waitUntilIdle(timeoutSeconds: 5)
+        AttachmentDebugLogger.record("[Snapshot] imageLoadIdle=\(waitImages)")
+        let waitLayout = await AttachmentLayoutTracker.shared.waitUntilIdle(timeoutSeconds: 3)
+        AttachmentDebugLogger.record("[Snapshot] layoutIdle=\(waitLayout)")
+        logImageViewDiagnostics(in: hostingView)
 
-        assertSnapshot(
+        let snapshotting = Snapshotting<UIView, UIImage>.image()
+        let image = await snapshotImage(
             of: renderedView,
-            as: .image,// (traits: .init(displayScale: 1))
-            named: name,
-            record: recording,
-            fileID: fileID,
-            file: filePath,
+            snapshotting: snapshotting
+        )
+        rawLog("[Raw] captured image size=\(image.size) cg=\(image.cgImage != nil)")
+        logPixelMetrics(image: image, testName: testName, name: name)
+        logMarginSquareSpacing(image: image, testName: testName, name: name)
+        logDoubleMarginSquaresSpacing(image: image, testName: testName, name: name)
+        logListItemSquareMetrics(image: image, testName: testName, name: name)
+        logBulletImageAlignment(image: image, testName: testName, name: name)
+        logWordBrekBoxMetrics(image: image, testName: testName, name: name, filePath: filePath)
+        writeSnapshotArtifact(
+            image: image,
+            testName: testName,
+            name: name,
+            html: html,
+            filePath: filePath
+        )
+        performOCRDebug(
+            image: image,
             testName: testName,
-            line: line,
-            column: column
+            name: name,
+            filePath: filePath
         )
+        let shouldRecord = recording ?? (ProcessInfo.processInfo.environment["SWIFTUIHTML_SNAPSHOT_RECORD"] == "1")
+        let failure = await MainActor.run {
+            verifySnapshot(
+                of: renderedView,
+                as: snapshotting,
+                named: name,
+                record: shouldRecord,
+                fileID: fileID,
+                file: filePath,
+                testName: testName,
+                line: line,
+                column: column
+            )
+        }
+        if let message = failure {
+            recordIssue(
+                message,
+                fileID: fileID,
+                filePath: filePath,
+                line: line,
+                column: column
+            )
+        }
+        AttachmentDebugLogger.record("[TestHarness] snapshot end: \(testName)")
+        rawLog("[Raw] snapshot end: \(testName)")
+        attachDebugLogs(testName: testName, name: name)
     }
 
     /// Snapshot error type
@@ -74,11 +217,1707 @@ class ViewSnapshotTester {
     
     /// Find actual rendered view 
     private static func findActualRenderedView(in hostingView: UIView) -> UIView? {
-        // Find the actual rendered view inside UIHostingView
-        // Usually the first child view or may vary depending on specific hierarchy structure
         if let contentView = hostingView.subviews.first {
             return contentView
         }
         return hostingView
     }
+
+    private static func makeSnapshotImage(of view: UIView, scale: CGFloat) -> UIImage {
+        let size = view.bounds.size
+        if size.width <= 1 || size.height <= 1 {
+            return UIImage()
+        }
+        let format = UIGraphicsImageRendererFormat(for: UITraitCollection(displayScale: scale))
+        format.scale = scale
+        format.opaque = true
+        let renderer = UIGraphicsImageRenderer(size: size, format: format)
+        var image = renderer.image { _ in
+            view.drawHierarchy(in: view.bounds, afterScreenUpdates: true)
+        }
+        if image.cgImage == nil {
+            image = renderer.image { ctx in
+                view.layer.render(in: ctx.cgContext)
+            }
+        }
+        if image.cgImage != nil {
+            return image
+        }
+        if let ciImage = image.ciImage {
+            let context = CIContext(options: nil)
+            if let cgImage = context.createCGImage(ciImage, from: ciImage.extent) {
+                return UIImage(cgImage: cgImage, scale: scale, orientation: .up)
+            }
+        }
+        print("Snapshot image missing CGImage. size=\(size) scale=\(scale)")
+        return image
+    }
+
+    private static func contentBounds(in rootView: UIView) -> CGRect {
+        var unionRect: CGRect = .null
+        for view in allDescendants(of: rootView) {
+            let size = view.bounds.size
+            guard size.width > 1, size.height > 1 else { continue }
+            let rect = view.convert(view.bounds, to: rootView)
+            unionRect = unionRect.union(rect)
+        }
+        if unionRect.isNull {
+            return .zero
+        }
+        return unionRect.integral
+    }
+
+    private static func allDescendants(of rootView: UIView) -> [UIView] {
+        var result: [UIView] = []
+        var stack: [UIView] = [rootView]
+        while let view = stack.popLast() {
+            if view !== rootView {
+                result.append(view)
+            }
+            stack.append(contentsOf: view.subviews)
+        }
+        return result
+    }
+
+    private static func cropImage(_ image: UIImage, to rect: CGRect) -> UIImage {
+        guard let cgImage = image.cgImage else { return image }
+        let scale = image.scale
+        let pixelRect = CGRect(
+            x: rect.origin.x * scale,
+            y: rect.origin.y * scale,
+            width: rect.size.width * scale,
+            height: rect.size.height * scale
+        ).integral
+        guard let cropped = cgImage.cropping(to: pixelRect) else { return image }
+        return UIImage(cgImage: cropped, scale: scale, orientation: .up)
+    }
+
+    private static func logPixelMetrics(image: UIImage, testName: String, name: String?) {
+        guard let cgImage = image.cgImage else { return }
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 1 && height > 1 else { return }
+
+        let bytesPerPixel = 4
+        let bytesPerRow = bytesPerPixel * width
+        let totalBytes = bytesPerRow * height
+        var buffer = [UInt8](repeating: 0, count: totalBytes)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        var minX = width
+        var minY = height
+        var maxX = -1
+        var maxY = -1
+        var nonWhiteCount = 0
+        let threshold: UInt8 = 250
+        for y in 0..<height {
+            let rowOffset = y * bytesPerRow
+            for x in 0..<width {
+                let offset = rowOffset + x * bytesPerPixel
+                let r = buffer[offset]
+                let g = buffer[offset + 1]
+                let b = buffer[offset + 2]
+                let a = buffer[offset + 3]
+                if a <= 10 { continue }
+                if r < threshold || g < threshold || b < threshold {
+                    nonWhiteCount += 1
+                    if x < minX { minX = x }
+                    if x > maxX { maxX = x }
+                    if y < minY { minY = y }
+                    if y > maxY { maxY = y }
+                }
+            }
+        }
+
+        let label = sanitizePathComponent(testName)
+        let ident = sanitizePathComponent(name ?? "1")
+        if maxX >= minX && maxY >= minY {
+            let top = minY
+            let left = minX
+            let bottom = (height - 1) - maxY
+            let right = (width - 1) - maxX
+            let inkRatio = Double(nonWhiteCount) / Double(width * height)
+            let inkString = String(format: "%.4f", inkRatio)
+            let line = "[PixelMetrics] \(label).\(ident) size=\(width)x\(height) top=\(top) left=\(left) bottom=\(bottom) right=\(right) ink=\(inkString)"
+            print(line)
+            AttachmentDebugLogger.record(line)
+        } else {
+            let line = "[PixelMetrics] \(label).\(ident) size=\(width)x\(height) no-nonwhite"
+            print(line)
+            AttachmentDebugLogger.record(line)
+        }
+    }
+
+    private static func logMarginSquareSpacing(image: UIImage, testName: String, name: String?) {
+        guard testName.contains("MarginSquareSnapshot") else { return }
+        guard let bounds = nonWhiteBounds(in: image) else { return }
+        let scale = image.scale
+        let topPoints = CGFloat(bounds.top) / scale
+        let leftPoints = CGFloat(bounds.left) / scale
+        let bottomPoints = CGFloat(bounds.bottom) / scale
+        let widthPoints = CGFloat(bounds.width) / scale
+        let expectedBox: CGFloat = 20
+        let tolerance: CGFloat = 1.5
+        let label = sanitizePathComponent(testName)
+        let ident = sanitizePathComponent(name ?? "1")
+        let summary = String(
+            format: "%.1fpt top, %.1fpt left, %.1fpt bottom, %.1fpt box",
+            topPoints,
+            leftPoints,
+            bottomPoints,
+            widthPoints
+        )
+        let logLine = "[MarginSquare] \(label).\(ident) \(summary)"
+        print(logLine)
+        AttachmentDebugLogger.record(logLine)
+
+        XCTAssertLessThanOrEqual(abs(topPoints - leftPoints), tolerance, "Margin square top/left mismatch \(summary)")
+        XCTAssertLessThanOrEqual(abs(bottomPoints - leftPoints), tolerance, "Margin square bottom/left mismatch \(summary)")
+        XCTAssertLessThanOrEqual(abs(widthPoints - expectedBox), tolerance, "Margin square box size changed \(summary)")
+        XCTAssertLessThanOrEqual(abs(leftPoints - expectedBox), tolerance, "Margin square left margin drift \(summary)")
+    }
+
+    private static func logDoubleMarginSquaresSpacing(image: UIImage, testName: String, name: String?) {
+        guard testName.contains("DoubleMarginSquares") else { return }
+        guard let cgImage = image.cgImage else { return }
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 1, height > 1 else { return }
+
+        let bytesPerPixel = 4
+        let bytesPerRow = bytesPerPixel * width
+        var buffer = [UInt8](repeating: 0, count: bytesPerRow * height)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        let threshold: UInt8 = 250
+        var inkRows: [Bool] = Array(repeating: false, count: height)
+        for y in 0..<height {
+            let rowOffset = y * bytesPerRow
+            for x in 0..<width {
+                let offset = rowOffset + x * bytesPerPixel
+                let r = buffer[offset]
+                let g = buffer[offset + 1]
+                let b = buffer[offset + 2]
+                if r < threshold || g < threshold || b < threshold {
+                    inkRows[y] = true
+                    break
+                }
+            }
+        }
+
+        var ranges: [(start: Int, end: Int)] = []
+        var currentStart: Int?
+        for y in 0..<height {
+            if inkRows[y] {
+                if currentStart == nil {
+                    currentStart = y
+                }
+            } else if let start = currentStart {
+                ranges.append((start, y - 1))
+                currentStart = nil
+            }
+        }
+        if let start = currentStart {
+            ranges.append((start, height - 1))
+        }
+        guard ranges.count >= 2 else { return }
+        let first = ranges[0]
+        let second = ranges[1]
+
+        func boundsX(for range: (start: Int, end: Int)) -> (minX: Int, maxX: Int)? {
+            var minX = width
+            var maxX = -1
+            for y in range.start...range.end {
+                let rowOffset = y * bytesPerRow
+                for x in 0..<width {
+                    let offset = rowOffset + x * bytesPerPixel
+                    let r = buffer[offset]
+                    let g = buffer[offset + 1]
+                    let b = buffer[offset + 2]
+                    if r < threshold || g < threshold || b < threshold {
+                        if x < minX { minX = x }
+                        if x > maxX { maxX = x }
+                    }
+                }
+            }
+            guard maxX >= minX else { return nil }
+            return (minX, maxX)
+        }
+
+        guard let xBounds = boundsX(for: first) else { return }
+        let scale = image.scale
+        let squareHeight = CGFloat(first.end - first.start + 1) / scale
+        let squareWidth = CGFloat(xBounds.maxX - xBounds.minX + 1) / scale
+        let topMargin = CGFloat(first.start) / scale
+        let between = CGFloat(second.start - first.end - 1) / scale
+        let bottomMargin = CGFloat((height - 1) - second.end) / scale
+        let leftMargin = CGFloat(xBounds.minX) / scale
+
+        let expectedTopBottom = squareHeight * 0.2
+        let expectedLeft = squareWidth * 0.1
+        let expectedBetween = squareHeight * 0.1
+        let tolerance: CGFloat = 2
+
+        let label = sanitizePathComponent(testName)
+        let ident = sanitizePathComponent(name ?? "1")
+        let summary = String(
+            format: "%.1fpt top, %.1fpt left, %.1fpt between, %.1fpt bottom, square=%.1fx%.1f",
+            topMargin,
+            leftMargin,
+            between,
+            bottomMargin,
+            squareWidth,
+            squareHeight
+        )
+        let logLine = "[DoubleMarginSquares] \(label).\(ident) \(summary)"
+        print(logLine)
+        AttachmentDebugLogger.record(logLine)
+
+        XCTAssertLessThanOrEqual(abs(topMargin - expectedTopBottom), tolerance, "Top margin drift \(summary)")
+        XCTAssertLessThanOrEqual(abs(bottomMargin - expectedTopBottom), tolerance, "Bottom margin drift \(summary)")
+        XCTAssertLessThanOrEqual(abs(leftMargin - expectedLeft), tolerance, "Left margin drift \(summary)")
+        XCTAssertLessThanOrEqual(abs(between - expectedBetween), tolerance, "Between margin drift \(summary)")
+    }
+
+    private static func logWordBrekBoxMetrics(
+        image: UIImage,
+        testName: String,
+        name: String?,
+        filePath: StaticString
+    ) {
+        guard sanitizePathComponent(testName).contains("testingWordBrek") else { return }
+        let identifier = sanitizePathComponent(name ?? "1")
+        guard let baselineImage = loadBaselineImage(
+            filePath: filePath,
+            testName: sanitizePathComponent(testName),
+            identifier: identifier
+        ) else {
+            AttachmentDebugLogger.record("[WordBrekBoxes] baseline missing for \(testName).\(identifier)")
+            return
+        }
+
+        let (newBoxes, newSize) = wordBrekBoxes(in: image)
+        let (baselineBoxes, baseSize) = wordBrekBoxes(in: baselineImage)
+        AttachmentDebugLogger.record("[WordBrekBoxes] new=\(newBoxes.count) baseline=\(baselineBoxes.count)")
+        XCTAssertEqual(newBoxes.count, baselineBoxes.count, "WordBrek box count mismatch new=\(newBoxes.count) baseline=\(baselineBoxes.count)")
+        guard !newBoxes.isEmpty, !baselineBoxes.isEmpty else { return }
+
+        let pairedCount = min(newBoxes.count, baselineBoxes.count)
+        let tolerance: CGFloat = 0.02
+        for index in 0..<pairedCount {
+            let newRect = newBoxes[index]
+            let baseRect = baselineBoxes[index]
+            let newNorm = CGRect(
+                x: newRect.minX / max(newSize.width, 1),
+                y: newRect.minY / max(newSize.height, 1),
+                width: newRect.width / max(newSize.width, 1),
+                height: newRect.height / max(newSize.height, 1)
+            )
+            let baseNorm = CGRect(
+                x: baseRect.minX / max(baseSize.width, 1),
+                y: baseRect.minY / max(baseSize.height, 1),
+                width: baseRect.width / max(baseSize.width, 1),
+                height: baseRect.height / max(baseSize.height, 1)
+            )
+            let dx = newNorm.minX - baseNorm.minX
+            let dy = newNorm.minY - baseNorm.minY
+            let dw = newNorm.width - baseNorm.width
+            let dh = newNorm.height - baseNorm.height
+            let summary = String(
+                format: "box[%d] new=(%.4f,%.4f %.4fx%.4f) base=(%.4f,%.4f %.4fx%.4f) delta=(%.4f,%.4f %.4fx%.4f)",
+                index,
+                newNorm.minX,
+                newNorm.minY,
+                newNorm.width,
+                newNorm.height,
+                baseNorm.minX,
+                baseNorm.minY,
+                baseNorm.width,
+                baseNorm.height,
+                dx,
+                dy,
+                dw,
+                dh
+            )
+            AttachmentDebugLogger.record("[WordBrekBoxes] \(summary)")
+            XCTAssertLessThanOrEqual(abs(dx), tolerance, "WordBrek box x drift \(summary)")
+            XCTAssertLessThanOrEqual(abs(dy), tolerance, "WordBrek box y drift \(summary)")
+            XCTAssertLessThanOrEqual(abs(dw), tolerance, "WordBrek box width drift \(summary)")
+            XCTAssertLessThanOrEqual(abs(dh), tolerance, "WordBrek box height drift \(summary)")
+        }
+    }
+
+    private static func wordBrekBoxes(in image: UIImage) -> ([CGRect], CGSize) {
+        guard let cgImage = image.cgImage else { return ([], image.size) }
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 1, height > 1 else { return ([], image.size) }
+        let bytesPerPixel = 4
+        let bytesPerRow = bytesPerPixel * width
+        var buffer = [UInt8](repeating: 0, count: bytesPerRow * height)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return ([], CGSize(width: width, height: height)) }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        let target: UInt8 = 248
+        let tolerance: Int = 4
+        func isBoxBackground(_ r: UInt8, _ g: UInt8, _ b: UInt8) -> Bool {
+            abs(Int(r) - Int(target)) <= tolerance
+                && abs(Int(g) - Int(target)) <= tolerance
+                && abs(Int(b) - Int(target)) <= tolerance
+        }
+
+        var visited = [Bool](repeating: false, count: width * height)
+        var rects: [CGRect] = []
+        rects.reserveCapacity(16)
+        func index(_ x: Int, _ y: Int) -> Int { y * width + x }
+        let minArea = 5000
+        for y in 0..<height {
+            for x in 0..<width {
+                let idx = index(x, y)
+                if visited[idx] { continue }
+                let offset = idx * bytesPerPixel
+                let r = buffer[offset]
+                let g = buffer[offset + 1]
+                let b = buffer[offset + 2]
+                if !isBoxBackground(r, g, b) {
+                    visited[idx] = true
+                    continue
+                }
+                var stack = [(x, y)]
+                visited[idx] = true
+                var minX = x
+                var maxX = x
+                var minY = y
+                var maxY = y
+                var count = 0
+                while let (cx, cy) = stack.popLast() {
+                    count += 1
+                    if cx < minX { minX = cx }
+                    if cx > maxX { maxX = cx }
+                    if cy < minY { minY = cy }
+                    if cy > maxY { maxY = cy }
+                    let neighbors = [
+                        (cx - 1, cy),
+                        (cx + 1, cy),
+                        (cx, cy - 1),
+                        (cx, cy + 1)
+                    ]
+                    for (nx, ny) in neighbors {
+                        guard nx >= 0, nx < width, ny >= 0, ny < height else { continue }
+                        let nidx = index(nx, ny)
+                        if visited[nidx] { continue }
+                        let noffset = nidx * bytesPerPixel
+                        let nr = buffer[noffset]
+                        let ng = buffer[noffset + 1]
+                        let nb = buffer[noffset + 2]
+                        if isBoxBackground(nr, ng, nb) {
+                            visited[nidx] = true
+                            stack.append((nx, ny))
+                        } else {
+                            visited[nidx] = true
+                        }
+                    }
+                }
+                if count < minArea { continue }
+                let rect = CGRect(
+                    x: CGFloat(minX),
+                    y: CGFloat(minY),
+                    width: CGFloat(maxX - minX + 1),
+                    height: CGFloat(maxY - minY + 1)
+                )
+                rects.append(rect)
+            }
+        }
+        return (rects.sorted { $0.minY < $1.minY }, CGSize(width: width, height: height))
+    }
+
+    private static func nonWhiteBounds(in image: UIImage) -> (top: Int, left: Int, bottom: Int, right: Int, width: Int, height: Int)? {
+        guard let cgImage = image.cgImage else { return nil }
+        let width = cgImage.width
+        let height = cgImage.height
+        let bytesPerPixel = 4
+        let bytesPerRow = bytesPerPixel * width
+        let totalBytes = bytesPerRow * height
+        var buffer = [UInt8](repeating: 0, count: totalBytes)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else {
+            return nil
+        }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        var minX = width
+        var minY = height
+        var maxX = -1
+        var maxY = -1
+        let threshold: UInt8 = 250
+        for y in 0..<height {
+            let rowOffset = y * bytesPerRow
+            for x in 0..<width {
+                let offset = rowOffset + x * bytesPerPixel
+                let r = buffer[offset]
+                let g = buffer[offset + 1]
+                let b = buffer[offset + 2]
+                let a = buffer[offset + 3]
+                if a <= 10 { continue }
+                if r < threshold || g < threshold || b < threshold {
+                    if x < minX { minX = x }
+                    if x > maxX { maxX = x }
+                    if y < minY { minY = y }
+                    if y > maxY { maxY = y }
+                }
+            }
+        }
+        guard maxX >= minX, maxY >= minY else { return nil }
+        let top = minY
+        let left = minX
+        let bottom = (height - 1) - maxY
+        let right = (width - 1) - maxX
+        return (top: top, left: left, bottom: bottom, right: right, width: maxX - minX + 1, height: maxY - minY + 1)
+    }
+
+    private struct DarkComponent {
+        let minX: Int
+        let minY: Int
+        let maxX: Int
+        let maxY: Int
+        let count: Int
+
+        var width: Int { maxX - minX + 1 }
+        var height: Int { maxY - minY + 1 }
+        var area: Int { count }
+        var rect: CGRect {
+            CGRect(
+                x: CGFloat(minX),
+                y: CGFloat(minY),
+                width: CGFloat(width),
+                height: CGFloat(height)
+            )
+        }
+
+        var center: CGPoint {
+            CGPoint(
+                x: CGFloat(minX + maxX) / 2,
+                y: CGFloat(minY + maxY) / 2
+            )
+        }
+    }
+
+    private struct ImageAnalysis {
+        let width: Int
+        let height: Int
+        let components: [DarkComponent]
+        let minX: Int?
+        let minY: Int?
+        let maxX: Int?
+        let maxY: Int?
+    }
+
+    private static func analyzeDarkImage(_ cgImage: CGImage) -> ImageAnalysis? {
+        let width = cgImage.width
+        let height = cgImage.height
+        guard width > 1 && height > 1 else { return nil }
+        let bytesPerPixel = 4
+        let bytesPerRow = bytesPerPixel * width
+        let totalBytes = bytesPerRow * height
+        var buffer = [UInt8](repeating: 0, count: totalBytes)
+        guard let context = CGContext(
+            data: &buffer,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: bytesPerRow,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return nil }
+        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        let whiteThreshold: UInt8 = 245
+        let alphaThreshold: UInt8 = 10
+        var visited = [Bool](repeating: false, count: width * height)
+        var components: [DarkComponent] = []
+        var overallMinX = width
+        var overallMinY = height
+        var overallMaxX = -1
+        var overallMaxY = -1
+
+        func isInk(x: Int, y: Int) -> Bool {
+            let idx = y * bytesPerRow + x * bytesPerPixel
+            let r = buffer[idx]
+            let g = buffer[idx + 1]
+            let b = buffer[idx + 2]
+            let a = buffer[idx + 3]
+            guard a > alphaThreshold else { return false }
+            return r < whiteThreshold || g < whiteThreshold || b < whiteThreshold
+        }
+
+        for y in 0..<height {
+            for x in 0..<width {
+                let flat = y * width + x
+                if visited[flat] || !isInk(x: x, y: y) { continue }
+                var stack = [(x, y)]
+                visited[flat] = true
+                var cminX = x
+                var cmaxX = x
+                var cminY = y
+                var cmaxY = y
+                var count = 0
+                while let (cx, cy) = stack.popLast() {
+                    count += 1
+                    cminX = min(cminX, cx)
+                    cmaxX = max(cmaxX, cx)
+                    cminY = min(cminY, cy)
+                    cmaxY = max(cmaxY, cy)
+                    let neighbors = [
+                        (cx - 1, cy), (cx + 1, cy),
+                        (cx, cy - 1), (cx, cy + 1)
+                    ]
+                    for (nx, ny) in neighbors where nx >= 0 && ny >= 0 && nx < width && ny < height {
+                        let nflat = ny * width + nx
+                        if visited[nflat] { continue }
+                        if isInk(x: nx, y: ny) {
+                            visited[nflat] = true
+                            stack.append((nx, ny))
+                        }
+                    }
+                }
+                components.append(DarkComponent(
+                    minX: cminX,
+                    minY: cminY,
+                    maxX: cmaxX,
+                    maxY: cmaxY,
+                    count: count
+                ))
+                overallMinX = min(overallMinX, cminX)
+                overallMinY = min(overallMinY, cminY)
+                overallMaxX = max(overallMaxX, cmaxX)
+                overallMaxY = max(overallMaxY, cmaxY)
+            }
+        }
+
+        let minX = overallMaxX >= 0 ? overallMinX : nil
+        let minY = overallMaxY >= 0 ? overallMinY : nil
+        let maxX = overallMaxX >= 0 ? overallMaxX : nil
+        let maxY = overallMaxY >= 0 ? overallMaxY : nil
+
+        return ImageAnalysis(
+            width: width,
+            height: height,
+            components: components,
+            minX: minX,
+            minY: minY,
+            maxX: maxX,
+            maxY: maxY
+        )
+    }
+
+    private static func logListItemSquareMetrics(image: UIImage, testName: String, name: String?) {
+        let label = sanitizePathComponent(testName)
+        let ident = sanitizePathComponent(name ?? "1")
+        let shouldMeasure = testName.contains("testListItemSquareSnapshot") || ident == "listItemSquare"
+        guard shouldMeasure, let cgImage = image.cgImage else { return }
+        guard let analysis = analyzeDarkImage(cgImage) else { return }
+        guard let minX = analysis.minX,
+              let minY = analysis.minY,
+              let maxX = analysis.maxX,
+              let maxY = analysis.maxY else {
+            let line = "[ListSquareMetrics] \(label).\(ident) no-dark-components"
+            print(line)
+            AttachmentDebugLogger.record(line)
+            return
+        }
+
+        let squareCandidate = analysis.components
+            .filter {
+                let w = $0.width
+                let h = $0.height
+                return w >= 8 && w <= 14 && h >= 8 && h <= 14
+            }
+            .max { $0.count < $1.count }
+
+        if let square = squareCandidate {
+            let overallCenterY = Double(minY + maxY) / 2.0
+            let squareCenterY = Double(square.minY + square.maxY) / 2.0
+            let delta = squareCenterY - overallCenterY
+            let squareW = square.width
+            let squareH = square.height
+            let bulletCandidates = analysis.components.filter {
+                $0.width <= 12 && $0.height <= 12 && CGFloat($0.maxX) < CGFloat(square.minX) - 1
+            }
+            var line = "[ListSquareMetrics] \(label).\(ident) overall=(\(minX),\(minY),\(maxX),\(maxY)) square=(\(square.minX),\(square.minY),\(square.maxX),\(square.maxY)) squareSize=\(squareW)x\(squareH) deltaCenterY=\(String(format: "%.2f", delta))"
+            if let bullet = bulletCandidates.max(by: { $0.area < $1.area }) {
+                let bulletCenterY = Double(bullet.rect.midY)
+                let deltaBullet = bulletCenterY - squareCenterY
+                let gapToSquare = Double(square.minX) - Double(bullet.rect.maxX)
+                let scaledDelta = deltaBullet / Double(image.scale)
+                let gapPoints = gapToSquare / Double(image.scale)
+                line += " bulletSquareDelta=\(String(format: "%.2f", deltaBullet)) gap=\(String(format: "%.2f", gapPoints))"
+                XCTAssertLessThanOrEqual(abs(scaledDelta), 4.0, "Bullet not aligned with square (\(scaledDelta))")
+                XCTAssertGreaterThan(gapPoints, 1.0, "Bullet overlaps square (\(gapPoints))")
+            } else {
+                line += " bulletMissing"
+                XCTFail("[ListSquareMetrics] \(label).\(ident) bullet missing")
+            }
+            print(line)
+            AttachmentDebugLogger.record(line)
+        } else {
+            let line = "[ListSquareMetrics] \(label).\(ident) squareNotFound overall=\(minX),\(minY),\(maxX),\(maxY)) components=\(analysis.components.count)"
+            print(line)
+            AttachmentDebugLogger.record(line)
+            XCTFail("[ListSquareMetrics] \(label).\(ident) square missing")
+        }
+    }
+
+    private static func logBulletImageAlignment(image: UIImage, testName: String, name: String?) {
+        guard testName.contains("BulletImageAlignment") else { return }
+        guard let cgImage = image.cgImage else { return }
+        guard let analysis = analyzeDarkImage(cgImage) else {
+            let message = "[BulletAlignment] \(sanitizePathComponent(testName)) no dark components"
+            print(message)
+            AttachmentDebugLogger.record(message)
+            XCTFail(message)
+            return
+        }
+        let bulletCandidates = analysis.components.filter {
+            $0.width <= 14 && $0.height <= 14 && $0.minX < analysis.width / 2
+        }
+        guard let bullet = bulletCandidates.max(by: { $0.area < $1.area }) else {
+            let message = "[BulletAlignment] \(sanitizePathComponent(testName)) bullet not found"
+            print(message)
+            AttachmentDebugLogger.record(message)
+            XCTFail(message)
+            return
+        }
+        let bulletRect = bullet.rect
+        let canvasSize = CGSize(width: CGFloat(analysis.width), height: CGFloat(analysis.height))
+        let letterRects = detectCharacterRects(in: cgImage, canvasSize: canvasSize, characters: ["O"])
+        let visibleLetters = letterRects.filter { $0.minX > bulletRect.maxX }
+        guard visibleLetters.count >= 2 else {
+            let message = "[BulletAlignment] \(sanitizePathComponent(testName)) expected 2 letter O but found \(visibleLetters.count)"
+            print(message)
+            AttachmentDebugLogger.record(message)
+            XCTFail(message)
+            return
+        }
+        let sortedLetters = visibleLetters.sorted { $0.minX < $1.minX }
+        let firstO = sortedLetters[0]
+        let secondO = sortedLetters[1]
+
+        let bulletCenterY = bulletRect.midY
+        let firstCenterY = firstO.midY
+        let secondCenterY = secondO.midY
+        let firstGap = firstO.minX - bulletRect.maxX
+        let interLetterGap = secondO.minX - firstO.maxX
+        let delta1 = String(format: "%.2f", bulletCenterY - firstCenterY)
+        let delta2 = String(format: "%.2f", bulletCenterY - secondCenterY)
+        let gapToBulletStr = String(format: "%.2f", firstGap)
+        let interGapStr = String(format: "%.2f", interLetterGap)
+        let line = "[BulletAlignment] bullet=\(bulletRect) firstO=\(firstO) secondO=\(secondO) centerDelta1=\(delta1) centerDelta2=\(delta2) gapToBullet=\(gapToBulletStr) interLetterGap=\(interGapStr)"
+        print(line)
+        AttachmentDebugLogger.record(line)
+
+        let scale = image.scale
+        let pointCenterDelta1 = (bulletCenterY - firstCenterY) / scale
+        let pointCenterDelta2 = (bulletCenterY - secondCenterY) / scale
+        let pointGapToBullet = firstGap / scale
+        let pointInterLetterGap = interLetterGap / scale
+
+        XCTAssertLessThanOrEqual(abs(pointCenterDelta1), 4.0, "Bullet and first letter misaligned (\(pointCenterDelta1))")
+        XCTAssertLessThanOrEqual(abs(pointCenterDelta2), 4.0, "Bullet and linked letter misaligned (\(pointCenterDelta2))")
+        XCTAssertGreaterThan(pointGapToBullet, 0.5, "First letter overlaps bullet (\(pointGapToBullet))")
+        XCTAssertGreaterThan(pointInterLetterGap, 4.0, "Letters appear collapsed (\(pointInterLetterGap))")
+    }
+
+    private static func detectCharacterRects(in cgImage: CGImage, canvasSize: CGSize, characters: Set<String>) -> [CGRect] {
+        let request = VNRecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        request.usesLanguageCorrection = false
+        request.minimumTextHeight = 0.01
+        let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+        do {
+            try handler.perform([request])
+        } catch {
+            let message = "[BulletAlignment] text recognition failed \(error.localizedDescription)"
+            print(message)
+            AttachmentDebugLogger.record(message)
+            return []
+        }
+        guard let results = request.results as? [VNRecognizedTextObservation] else { return [] }
+        var rects: [CGRect] = []
+        for observation in results {
+            guard let candidate = observation.topCandidates(1).first else { continue }
+            let trimmed = candidate.string.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard lettersContains(characters, text: trimmed) else { continue }
+            let bounding = observation.boundingBox
+            rects.append(CGRect(
+                x: bounding.minX * canvasSize.width,
+                y: (1 - bounding.maxY) * canvasSize.height,
+                width: bounding.width * canvasSize.width,
+                height: bounding.height * canvasSize.height
+            ))
+        }
+        return rects
+    }
+
+    private static func lettersContains(_ characters: Set<String>, text: String) -> Bool {
+        let filtered = text.replacingOccurrences(of: " ", with: "")
+            .filter { !$0.isWhitespace }
+        guard let single = filtered.first, filtered.count == 1 else { return false }
+        return characters.contains(String(single))
+    }
+
+    private static func recordIssue(
+        _ message: String,
+        fileID: StaticString,
+        filePath: StaticString,
+        line: UInt,
+        column: UInt
+    ) {
+        XCTFail(message, file: filePath, line: line)
+    }
+
+    @MainActor
+    private static func snapshotImage<Value>(
+        of value: Value,
+        snapshotting: Snapshotting<Value, UIImage>
+    ) async -> UIImage {
+        let expectation = XCTestExpectation(description: "snapshot image")
+        var result = UIImage()
+        snapshotting.snapshot(value).run { image in
+            result = image
+            expectation.fulfill()
+        }
+        _ = await XCTWaiter.fulfillment(of: [expectation], timeout: 5)
+        return result
+    }
+
+    private static func logImageViewDiagnostics(in rootView: UIView) {
+        let imageViews = allDescendants(of: rootView).compactMap { $0 as? UIImageView }
+        let visibleImages = imageViews.filter { view in
+            guard let image = view.image else { return false }
+            let size = view.bounds.size
+            return image.size.width > 0 && image.size.height > 0 && size.width > 1 && size.height > 1
+        }
+        let layeredViews = allDescendants(of: rootView).filter { $0.layer.contents != nil }
+        AttachmentDebugLogger.record("[Snapshot] imageViews total=\(imageViews.count) visible=\(visibleImages.count) layerContents=\(layeredViews.count)")
+        guard !visibleImages.isEmpty else { return }
+        let frames = visibleImages.prefix(32).map { view in
+            view.convert(view.bounds, to: rootView)
+        }
+        let summary = frames.map { "\($0.integral)" }.joined(separator: " | ")
+        AttachmentDebugLogger.record("[Snapshot] imageViewFrames \(summary)")
+        if !frames.isEmpty {
+            let frameKeys = frames.map { "\($0.integral)" }
+            let frameCounts = frameKeys.reduce(into: [String: Int]()) { counts, key in
+                counts[key, default: 0] += 1
+            }
+            let uniqueFrames = frameCounts.count
+            if let maxFrameDup = frameCounts.max(by: { $0.value < $1.value }) {
+                AttachmentDebugLogger.record("[Snapshot] imageFrameDuplicates total=\(frames.count) unique=\(uniqueFrames) maxDup=\(maxFrameDup.value) sample=\(maxFrameDup.key)")
+                if maxFrameDup.value > 1 && uniqueFrames <= max(1, frames.count / 2) {
+                    AttachmentDebugLogger.record("[Snapshot][Heuristic] many images share the same frame (possible stacking or offset bug)")
+                }
+            }
+        }
+
+        let hashes: [String] = visibleImages.compactMap { view in
+            guard let image = view.image else { return nil }
+            return imageHash(for: image)
+        }
+        guard !hashes.isEmpty else { return }
+        let counts = hashes.reduce(into: [String: Int]()) { counts, hash in
+            counts[hash, default: 0] += 1
+        }
+        let uniqueCount = counts.count
+        let maxDup = counts.max(by: { $0.value < $1.value })
+        if let maxDup {
+            AttachmentDebugLogger.record("[Snapshot] imageHashes total=\(hashes.count) unique=\(uniqueCount) maxDup=\(maxDup.value) sample=\(maxDup.key)")
+            if maxDup.value > 1 && uniqueCount == 1 {
+                AttachmentDebugLogger.record("[Snapshot][Heuristic] all images identical (possible stacking or reuse bug)")
+            }
+            if uniqueCount > 1 && uniqueCount <= max(1, hashes.count / 2) {
+                AttachmentDebugLogger.record("[Snapshot][Heuristic] many images are duplicates (possible missing or repeated image bug)")
+            }
+        }
+    }
+
+    private static func imageHash(for image: UIImage) -> String? {
+        guard let data = image.pngData() ?? image.jpegData(compressionQuality: 1) else { return nil }
+        let digest = SHA256.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func resolvedSize<V: View>(
+        for hostingController: UIHostingController<V>,
+        fallbackView: UIView,
+        observedSize: CGSize
+    ) -> CGSize {
+        var proposedWidth = UIScreen.main.bounds.width
+        if observedSize.width > 1 && observedSize.height > 1 {
+            proposedWidth = observedSize.width
+        }
+        if #available(iOS 16.0, *) {
+            let unconstrained = CGSize(
+                width: CGFloat.greatestFiniteMagnitude,
+                height: CGFloat.greatestFiniteMagnitude
+            )
+            let proposedSize = hostingController.sizeThatFits(in: unconstrained)
+            AttachmentDebugLogger.record("[Snapshot] sizeThatFits unconstrained=\(proposedSize)")
+            if proposedSize.width > 1 {
+                proposedWidth = proposedSize.width
+            }
+        }
+
+        let measuringSize = CGSize(width: proposedWidth, height: 10000)
+        let measuringBounds = CGRect(origin: .zero, size: measuringSize)
+        fallbackView.bounds = measuringBounds
+        fallbackView.frame = measuringBounds
+        fallbackView.layoutIfNeeded()
+
+        var measured = CGSize.zero
+        if #available(iOS 16.0, *) {
+            let proposed = CGSize(width: proposedWidth, height: CGFloat.greatestFiniteMagnitude)
+            measured = hostingController.sizeThatFits(in: proposed)
+            AttachmentDebugLogger.record("[Snapshot] sizeThatFits proposed=\(proposed) measured=\(measured)")
+        }
+
+        let layoutSize = fallbackView.systemLayoutSizeFitting(
+            CGSize(width: proposedWidth, height: UIView.layoutFittingCompressedSize.height),
+            withHorizontalFittingPriority: .required,
+            verticalFittingPriority: .fittingSizeLevel
+        )
+        if layoutSize.width > 1 && layoutSize.height > 1 {
+            AttachmentDebugLogger.record("[Snapshot] systemLayoutSizeFitting=\(layoutSize)")
+        }
+
+        var candidates: [CGSize] = []
+        if observedSize.width > 1 && observedSize.height > 1 {
+            candidates.append(observedSize)
+        }
+        let descendantSize = largestDescendantSize(in: fallbackView)
+        if descendantSize.width > 1 && descendantSize.height > 1 {
+            AttachmentDebugLogger.record("[Snapshot] descendantSize=\(descendantSize)")
+            candidates.append(descendantSize)
+        }
+        if measured.width > 1 && measured.height > 1 {
+            candidates.append(measured)
+        }
+        if layoutSize.width > 1 && layoutSize.height > 1 {
+            candidates.append(layoutSize)
+        }
+        let intrinsicSize = fallbackView.intrinsicContentSize
+        if intrinsicSize.width > 1 && intrinsicSize.height > 1 {
+            AttachmentDebugLogger.record("[Snapshot] intrinsicContentSize=\(intrinsicSize)")
+            candidates.append(intrinsicSize)
+        }
+        if let best = candidates.max(by: { ($0.width * $0.height) < ($1.width * $1.height) }) {
+            AttachmentDebugLogger.record("[Snapshot] resolvedSize candidates=\(candidates) selected=\(best)")
+            return best
+        }
+        let screen = UIScreen.main.bounds.size
+        AttachmentDebugLogger.record("[Snapshot] fallback screenSize=\(screen)")
+        return screen
+    }
+
+    private static func largestDescendantSize(in rootView: UIView) -> CGSize {
+        var best = CGSize.zero
+        for view in allDescendants(of: rootView) {
+            let size = view.bounds.size
+            guard size.width > 1 && size.height > 1 else { continue }
+            if size.width >= best.width && size.height >= best.height {
+                best = size
+            }
+        }
+        return best
+    }
+
+
+    private static func ensureSnapshotArtifactsDirectory(filePath: StaticString) -> URL {
+        if let existing = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"],
+           !existing.isEmpty {
+            return URL(fileURLWithPath: existing, isDirectory: true)
+        }
+        let artifactsUrl = artifactsRootURL()
+        do {
+            try FileManager.default.createDirectory(at: artifactsUrl, withIntermediateDirectories: true)
+            setenv("SNAPSHOT_ARTIFACTS", artifactsUrl.path, 1)
+        } catch {
+            // If we cannot create the folder, continue without overriding SNAPSHOT_ARTIFACTS.
+            AttachmentDebugLogger.record("[Snapshot] artifactsRoot create failed \(error.localizedDescription) path=\(artifactsUrl.path)")
+            rawLog("[Raw] artifactsRoot create failed \(error.localizedDescription) path=\(artifactsUrl.path)")
+        }
+        return artifactsUrl
+    }
+
+    private static func artifactsRootURL() -> URL {
+        if let existing = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"],
+           !existing.isEmpty {
+            return URL(fileURLWithPath: existing, isDirectory: true)
+        }
+        if let documents = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first {
+            return documents.appendingPathComponent("swiftuihtml-ios-artifacts", isDirectory: true)
+        }
+        let tempRoot = FileManager.default.temporaryDirectory
+        if !tempRoot.path.isEmpty {
+            return tempRoot.appendingPathComponent("swiftuihtml-ios-artifacts", isDirectory: true)
+        }
+        return URL(fileURLWithPath: "/tmp/swiftuihtml-ios-artifacts", isDirectory: true)
+    }
+
+    private static func attachDebugLogs(testName: String, name: String?) {
+        let bufferLogs = AttachmentDebugLogger.dump()
+        let fileLogs = AttachmentDebugLogger.readLogFile()
+        let logs = bufferLogs.isEmpty ? (fileLogs ?? "") : bufferLogs
+        guard !logs.isEmpty else { return }
+        print("SWIFTUIHTML_ATTACHMENT_LOGS_BEGIN")
+        print(logs)
+        print("SWIFTUIHTML_ATTACHMENT_LOGS_END")
+        let logURL = snapshotLogURL(testName: testName, name: name)
+        appendDiagnosticLog(logs, to: logURL)
+        if let artifactsPath = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"] {
+            let artifactsURL = URL(fileURLWithPath: artifactsPath, isDirectory: true)
+            let safeTestName = sanitizePathComponent(testName)
+            let identifier = sanitizePathComponent(name ?? "1")
+            let filename = "\(safeTestName).\(identifier).attachment.log"
+            let artifactURL = artifactsURL.appendingPathComponent(filename)
+            appendDiagnosticLog(logs, to: artifactURL)
+            writeAttachmentFrameLog(
+                logs: logs,
+                testName: safeTestName,
+                identifier: identifier,
+                artifactsURL: artifactsURL
+            )
+        }
+        let attachment = XCTAttachment(string: logs)
+        attachment.name = "SwiftUIHTML Attachment Layout Logs"
+        attachment.lifetime = .keepAlways
+        XCTContext.runActivity(named: "SwiftUIHTML Attachment Layout Logs") { activity in
+            activity.add(attachment)
+        }
+        AttachmentDebugLogger.clear()
+    }
+
+    private static func snapshotLogURL(testName: String, name: String?) -> URL {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let filename = "\(safeTestName).\(identifier).log"
+        return diagnosticLogDirectory.appendingPathComponent(filename)
+    }
+
+    private static func appendDiagnosticLog(_ logs: String, to url: URL) {
+        let payload = logs + "\n"
+        do {
+            if !FileManager.default.fileExists(atPath: diagnosticLogDirectory.path) {
+                try FileManager.default.createDirectory(
+                    at: diagnosticLogDirectory,
+                    withIntermediateDirectories: true
+                )
+            }
+            if !FileManager.default.fileExists(atPath: url.path) {
+                try "".write(to: url, atomically: true, encoding: .utf8)
+            }
+            let handle = try FileHandle(forWritingTo: url)
+            try handle.seekToEnd()
+            if let data = payload.data(using: .utf8) {
+                try handle.write(contentsOf: data)
+            }
+            try handle.close()
+        } catch {
+            print("SWIFTUIHTML_DIAG_WRITE_FAILED: \(error.localizedDescription)")
+        }
+    }
+
+    private static func writeAttachmentFrameLog(
+        logs: String,
+        testName: String,
+        identifier: String,
+        artifactsURL: URL
+    ) {
+        let filtered = logs
+            .split(separator: "\n")
+            .filter {
+                $0.contains("attachmentFrame id=")
+                    || $0.contains("attachmentLineRelative id=")
+                    || $0.contains("attachmentSize id=")
+            }
+        guard !filtered.isEmpty else { return }
+        let filename = "\(testName).\(identifier).attachment.frames.log"
+        let url = artifactsURL.appendingPathComponent(filename)
+        let payload = filtered.joined(separator: "\n") + "\n"
+        do {
+            try payload.write(to: url, atomically: true, encoding: .utf8)
+        } catch {
+            AttachmentDebugLogger.record("[Snapshot] attachment frame log write failed \(error.localizedDescription)")
+        }
+    }
+
+    private static func rawLog(_ message: String) {
+        let line = message + "\n"
+        if let data = line.data(using: .utf8) {
+            try? FileHandle.standardError.write(contentsOf: data)
+            let url = artifactsRootURL().appendingPathComponent("swiftuihtml-raw.log")
+            if let handle = try? FileHandle(forWritingTo: url) {
+                handle.seekToEndOfFile()
+                try? handle.write(contentsOf: data)
+                try? handle.close()
+            } else {
+                try? data.write(to: url)
+            }
+            if let artifactsPath = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"], !artifactsPath.isEmpty {
+                let artifactsURL = URL(fileURLWithPath: artifactsPath, isDirectory: true)
+                try? FileManager.default.createDirectory(at: artifactsURL, withIntermediateDirectories: true)
+                let rawURL = artifactsURL.appendingPathComponent("swiftuihtml-raw.log")
+                if let handle = try? FileHandle(forWritingTo: rawURL) {
+                    handle.seekToEndOfFile()
+                    try? handle.write(contentsOf: data)
+                    try? handle.close()
+                } else {
+                    try? data.write(to: rawURL)
+                }
+            }
+        }
+    }
+
+    private static func writeProbeFile(testName: String, name: String?) {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let timestamp = Int(Date().timeIntervalSince1970)
+        let dir = artifactsRootURL()
+            .appendingPathComponent("HTMLBasicTests")
+        let url = dir.appendingPathComponent("_probe_\(safeTestName).\(identifier).\(timestamp).txt")
+        do {
+            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+            try "probe \(timestamp)".write(to: url, atomically: true, encoding: .utf8)
+        } catch {
+            rawLog("[Raw] probe write failed \(error.localizedDescription)")
+        }
+    }
+
+    private static func writeLocationProbe(testName: String, name: String?) {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let timestamp = Int(Date().timeIntervalSince1970)
+        let filename = "_location_probe_\(safeTestName).\(identifier).\(timestamp).txt"
+        var locations: [URL] = []
+        let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent(filename)
+        locations.append(tempURL)
+        if let documents = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first {
+            locations.append(documents.appendingPathComponent(filename))
+        }
+        for url in locations {
+            do {
+                try "probe \(timestamp)".write(to: url, atomically: true, encoding: .utf8)
+                AttachmentDebugLogger.record("[Snapshot] locationProbe wrote \(url.path)")
+                rawLog("[Raw] locationProbe wrote \(url.path)")
+                print("SWIFTUIHTML_LOCATION_PROBE_WROTE \(url.path)")
+            } catch {
+                AttachmentDebugLogger.record("[Snapshot] locationProbe failed \(error.localizedDescription) path=\(url.path)")
+                rawLog("[Raw] locationProbe failed \(error.localizedDescription) path=\(url.path)")
+                print("SWIFTUIHTML_LOCATION_PROBE_FAILED \(error.localizedDescription) path=\(url.path)")
+            }
+        }
+    }
+
+    private static func writeMetricsArtifact(testName: String, name: String?, metrics: String) {
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let root = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"]
+            ?? "/tmp/swiftuihtml-ios-artifacts"
+        let dir = URL(fileURLWithPath: root, isDirectory: true)
+            .appendingPathComponent("HTMLBasicTests")
+        let url = dir.appendingPathComponent("\(safeTestName).\(identifier).metrics.txt")
+        do {
+            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+            try metrics.write(to: url, atomically: true, encoding: .utf8)
+        } catch {
+            rawLog("[Raw] metrics write failed \(error.localizedDescription)")
+        }
+        guard NSClassFromString("XCTestCase") != nil else { return }
+        let attachment = XCTAttachment(string: metrics)
+        attachment.name = "\(safeTestName).\(identifier).metrics"
+        attachment.lifetime = .keepAlways
+        XCTContext.runActivity(named: "Snapshot Metrics") { activity in
+            activity.add(attachment)
+        }
+    }
+
+    private static func performOCRDebug(
+        image: UIImage,
+        testName: String,
+        name: String?,
+        filePath: StaticString
+    ) {
+        guard NSClassFromString("XCTestCase") != nil else { return }
+        let shouldOCR = ProcessInfo.processInfo.environment["SWIFTUIHTML_OCR_DEBUG"] != "0"
+        guard shouldOCR else { return }
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let ocrRoot: String = {
+            let root = artifactsRootURL()
+            return root.appendingPathComponent("ocr", isDirectory: true).path
+        }()
+
+        guard let newStats = ocrStats(for: image, label: "new") else { return }
+        AttachmentDebugLogger.record(
+            "[OCR] new textRectCount=\(newStats.count) topPadding=\(newStats.topPadding) bottomPadding=\(newStats.bottomPadding) leftPadding=\(newStats.leftPadding) rightPadding=\(newStats.rightPadding) imageSize=\(newStats.imageSize)"
+        )
+        writeOCRDump(stats: newStats, testName: safeTestName, identifier: identifier, label: "new", outputDir: ocrRoot)
+        saveOCROverlay(
+            image: image,
+            rects: newStats.rects,
+            outputDir: ocrRoot,
+            filename: "\(safeTestName).\(identifier).ocr.png"
+        )
+        if let newRectStats = textRectStats(for: image, label: "new-rects") {
+            AttachmentDebugLogger.record(
+                "[OCR] new-rects count=\(newRectStats.count) topPadding=\(newRectStats.topPadding) bottomPadding=\(newRectStats.bottomPadding) leftPadding=\(newRectStats.leftPadding) rightPadding=\(newRectStats.rightPadding) imageSize=\(newRectStats.imageSize)"
+            )
+            writeOCRDump(stats: newRectStats, testName: safeTestName, identifier: identifier, label: "new-rects", outputDir: ocrRoot)
+        }
+
+        if let baselineImage = loadBaselineImage(
+            filePath: filePath,
+            testName: safeTestName,
+            identifier: identifier
+        ), let baselineStats = ocrStats(for: baselineImage, label: "baseline") {
+            let deltaTop = newStats.topPadding - baselineStats.topPadding
+            let deltaBottom = newStats.bottomPadding - baselineStats.bottomPadding
+            let deltaLeft = newStats.leftPadding - baselineStats.leftPadding
+            let deltaRight = newStats.rightPadding - baselineStats.rightPadding
+            AttachmentDebugLogger.record(
+                "[OCR] baseline textRectCount=\(baselineStats.count) topPadding=\(baselineStats.topPadding) bottomPadding=\(baselineStats.bottomPadding) leftPadding=\(baselineStats.leftPadding) rightPadding=\(baselineStats.rightPadding) imageSize=\(baselineStats.imageSize) deltaTop=\(deltaTop) deltaBottom=\(deltaBottom) deltaLeft=\(deltaLeft) deltaRight=\(deltaRight)"
+            )
+            writeOCRDump(stats: baselineStats, testName: safeTestName, identifier: identifier, label: "baseline", outputDir: ocrRoot)
+            logOCRLineDeltas(newStats: newStats, baselineStats: baselineStats)
+            writeOCRLineDeltaReport(
+                newStats: newStats,
+                baselineStats: baselineStats,
+                testName: safeTestName,
+                identifier: identifier,
+                outputDir: ocrRoot
+            )
+            saveOCROverlay(
+                image: baselineImage,
+                rects: baselineStats.rects,
+                outputDir: ocrRoot + "-baseline",
+                filename: "\(safeTestName).\(identifier).baseline.ocr.png"
+            )
+            if let baseRectStats = textRectStats(for: baselineImage, label: "baseline-rects") {
+                AttachmentDebugLogger.record(
+                    "[OCR] baseline-rects count=\(baseRectStats.count) topPadding=\(baseRectStats.topPadding) bottomPadding=\(baseRectStats.bottomPadding) leftPadding=\(baseRectStats.leftPadding) rightPadding=\(baseRectStats.rightPadding) imageSize=\(baseRectStats.imageSize)"
+                )
+                writeOCRDump(stats: baseRectStats, testName: safeTestName, identifier: identifier, label: "baseline-rects", outputDir: ocrRoot)
+            }
+        } else {
+            AttachmentDebugLogger.record("[OCR] baseline image missing for \(safeTestName).\(identifier)")
+        }
+    }
+
+    private static func ocrStats(for image: UIImage, label: String) -> OCRStats? {
+        guard let cgImage = image.cgImage else {
+            AttachmentDebugLogger.record("[OCR] missing CGImage (\(label))")
+            return nil
+        }
+
+        let request = VNRecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        request.usesLanguageCorrection = false
+        request.recognitionLanguages = ["en-US", "ja-JP", "ko-KR", "zh-Hans", "zh-Hant"]
+
+        let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+        do {
+            try handler.perform([request])
+        } catch {
+            AttachmentDebugLogger.record("[OCR] request failed \(error.localizedDescription)")
+            return nil
+        }
+
+        let observations = request.results ?? []
+        if observations.isEmpty {
+            return OCRStats(
+                rects: [],
+                texts: [],
+                topPadding: 0,
+                bottomPadding: 0,
+                leftPadding: 0,
+                rightPadding: 0,
+                imageSize: CGSize(width: cgImage.width, height: cgImage.height)
+            )
+        }
+
+        let imageWidth = CGFloat(cgImage.width)
+        let imageHeight = CGFloat(cgImage.height)
+
+        var rects: [CGRect] = []
+        var texts: [String] = []
+        rects.reserveCapacity(observations.count)
+        texts.reserveCapacity(observations.count)
+        for observation in observations {
+            let bbox = observation.boundingBox
+            let rect = CGRect(
+                x: bbox.minX * imageWidth,
+                y: (1 - bbox.maxY) * imageHeight,
+                width: bbox.width * imageWidth,
+                height: bbox.height * imageHeight
+            )
+            rects.append(rect)
+            if let candidate = observation.topCandidates(1).first {
+                texts.append(candidate.string)
+            } else {
+                texts.append("")
+            }
+        }
+
+        let minY = rects.map(\.minY).min() ?? 0
+        let maxY = rects.map(\.maxY).max() ?? 0
+        let minX = rects.map(\.minX).min() ?? 0
+        let maxX = rects.map(\.maxX).max() ?? 0
+        let topPadding = minY
+        let bottomPadding = max(0, imageHeight - maxY)
+        let leftPadding = minX
+        let rightPadding = max(0, imageWidth - maxX)
+        return OCRStats(
+            rects: rects,
+            texts: texts,
+            topPadding: topPadding,
+            bottomPadding: bottomPadding,
+            leftPadding: leftPadding,
+            rightPadding: rightPadding,
+            imageSize: CGSize(width: imageWidth, height: imageHeight)
+        )
+    }
+
+    private static func textRectStats(for image: UIImage, label: String) -> OCRStats? {
+        guard let cgImage = image.cgImage else {
+            AttachmentDebugLogger.record("[OCR] missing CGImage (\(label))")
+            return nil
+        }
+
+        let request = VNDetectTextRectanglesRequest()
+        request.reportCharacterBoxes = false
+
+        let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+        do {
+            try handler.perform([request])
+        } catch {
+            AttachmentDebugLogger.record("[OCR] rect request failed \(error.localizedDescription)")
+            return nil
+        }
+
+        let observations = request.results as? [VNTextObservation] ?? []
+        if observations.isEmpty {
+            return OCRStats(
+                rects: [],
+                texts: [],
+                topPadding: 0,
+                bottomPadding: 0,
+                leftPadding: 0,
+                rightPadding: 0,
+                imageSize: CGSize(width: cgImage.width, height: cgImage.height)
+            )
+        }
+
+        let imageWidth = CGFloat(cgImage.width)
+        let imageHeight = CGFloat(cgImage.height)
+
+        var rects: [CGRect] = []
+        rects.reserveCapacity(observations.count)
+        for observation in observations {
+            let bbox = observation.boundingBox
+            let rect = CGRect(
+                x: bbox.minX * imageWidth,
+                y: (1 - bbox.maxY) * imageHeight,
+                width: bbox.width * imageWidth,
+                height: bbox.height * imageHeight
+            )
+            rects.append(rect)
+        }
+
+        let minX = rects.map(\.minX).min() ?? 0
+        let minY = rects.map(\.minY).min() ?? 0
+        let maxX = rects.map(\.maxX).max() ?? 0
+        let maxY = rects.map(\.maxY).max() ?? 0
+        let topPadding = minY
+        let bottomPadding = max(0, imageHeight - maxY)
+        let leftPadding = minX
+        let rightPadding = max(0, imageWidth - maxX)
+
+        return OCRStats(
+            rects: rects,
+            texts: Array(repeating: "", count: rects.count),
+            topPadding: topPadding,
+            bottomPadding: bottomPadding,
+            leftPadding: leftPadding,
+            rightPadding: rightPadding,
+            imageSize: CGSize(width: imageWidth, height: imageHeight)
+        )
+    }
+
+    private static func saveOCROverlay(
+        image: UIImage,
+        rects: [CGRect],
+        outputDir: String,
+        filename: String
+    ) {
+        let overlay = drawOCR(image: image, rects: rects)
+        let outputURL = URL(fileURLWithPath: outputDir, isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
+        } catch {
+            AttachmentDebugLogger.record("[OCR] create dir failed \(error.localizedDescription)")
+        }
+        let fileURL = outputURL.appendingPathComponent(filename)
+        if let data = overlay.pngData() {
+            do {
+                try data.write(to: fileURL)
+                AttachmentDebugLogger.record("[OCR] overlay saved \(fileURL.path)")
+            } catch {
+                AttachmentDebugLogger.record("[OCR] write failed \(error.localizedDescription)")
+            }
+        }
+    }
+
+    private static func drawOCR(image: UIImage, rects: [CGRect]) -> UIImage {
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = image.scale
+        format.opaque = true
+        let renderer = UIGraphicsImageRenderer(size: image.size, format: format)
+        return renderer.image { ctx in
+            image.draw(in: CGRect(origin: .zero, size: image.size))
+            ctx.cgContext.setStrokeColor(UIColor.red.withAlphaComponent(0.7).cgColor)
+            ctx.cgContext.setLineWidth(2.0)
+            for rect in rects {
+                let scaledRect = CGRect(
+                    x: rect.minX / image.scale,
+                    y: rect.minY / image.scale,
+                    width: rect.width / image.scale,
+                    height: rect.height / image.scale
+                )
+                ctx.cgContext.stroke(scaledRect)
+            }
+        }
+    }
+
+    private static func sanitizePathComponent(_ string: String) -> String {
+        let sanitized = string.replacingOccurrences(
+            of: "\\W+",
+            with: "-",
+            options: .regularExpression
+        )
+        return sanitized.replacingOccurrences(
+            of: "^-|-$",
+            with: "",
+            options: .regularExpression
+        )
+    }
+
+    private static func writeSnapshotArtifact(
+        image: UIImage,
+        testName: String,
+        name: String?,
+        html: String?,
+        filePath: StaticString
+    ) {
+        let artifactRoot = ProcessInfo.processInfo.environment["SNAPSHOT_ARTIFACTS"]
+            ?? "/tmp/swiftuihtml-ios-artifacts"
+        let safeTestName = sanitizePathComponent(testName)
+        let identifier = sanitizePathComponent(name ?? "1")
+        let artifactDir = URL(fileURLWithPath: artifactRoot, isDirectory: true)
+            .appendingPathComponent("HTMLBasicTests")
+        let artifactURL = artifactDir
+            .appendingPathComponent("\(safeTestName).\(identifier)")
+            .appendingPathExtension("png")
+        let htmlURL = artifactDir
+            .appendingPathComponent("\(safeTestName).\(identifier)")
+            .appendingPathExtension("html")
+        do {
+            try FileManager.default.createDirectory(
+                at: artifactDir,
+                withIntermediateDirectories: true
+            )
+            if let data = image.pngData() {
+                try data.write(to: artifactURL)
+            }
+            let htmlCount = html?.count ?? 0
+            AttachmentDebugLogger.record("[Snapshot] artifact html length=\(htmlCount) path=\(htmlURL.path)")
+            if let html, !html.isEmpty {
+                try html.write(to: htmlURL, atomically: true, encoding: .utf8)
+            }
+        } catch {
+            AttachmentDebugLogger.record("[Snapshot] artifact write failed \(error.localizedDescription)")
+        }
+        guard NSClassFromString("XCTestCase") != nil else { return }
+        if let data = image.pngData() {
+            let attachment = XCTAttachment(data: data, uniformTypeIdentifier: "public.png")
+            attachment.name = "\(safeTestName).\(identifier).png"
+            attachment.lifetime = .keepAlways
+            XCTContext.runActivity(named: "Snapshot Image") { activity in
+                activity.add(attachment)
+            }
+        }
+        if let html, !html.isEmpty {
+            let attachment = XCTAttachment(string: html)
+            attachment.name = "\(safeTestName).\(identifier).html"
+            attachment.lifetime = .keepAlways
+            XCTContext.runActivity(named: "Snapshot HTML") { activity in
+                activity.add(attachment)
+            }
+        }
+    }
+
+    private static func loadBaselineImage(
+        filePath: StaticString,
+        testName: String,
+        identifier: String
+    ) -> UIImage? {
+        let url = URL(fileURLWithPath: "\(filePath)", isDirectory: false)
+        let testsDir = url.deletingLastPathComponent()
+        let snapshotDir = testsDir
+            .appendingPathComponent("__Snapshots__")
+            .appendingPathComponent("HTMLBasicTests")
+        let fileURL = snapshotDir
+            .appendingPathComponent("\(testName).\(identifier)")
+            .appendingPathExtension("png")
+        return UIImage(contentsOfFile: fileURL.path)
+    }
+
+    private struct OCRStats {
+        let rects: [CGRect]
+        let texts: [String]
+        let topPadding: CGFloat
+        let bottomPadding: CGFloat
+        let leftPadding: CGFloat
+        let rightPadding: CGFloat
+        let imageSize: CGSize
+
+        var count: Int { rects.count }
+    }
+
+    private struct OCRLine: Codable {
+        let index: Int
+        let rect: RectDTO
+        let text: String
+    }
+
+    private struct RectDTO: Codable {
+        let x: Double
+        let y: Double
+        let w: Double
+        let h: Double
+    }
+
+    private struct OCRDump: Codable {
+        let label: String
+        let imageWidth: Double
+        let imageHeight: Double
+        let topPadding: Double
+        let bottomPadding: Double
+        let leftPadding: Double
+        let rightPadding: Double
+        let lines: [OCRLine]
+    }
+
+    private struct OCRLineDeltaReport: Codable {
+        let label: String
+        let count: Int
+        let deltas: [OCRLineDelta]
+    }
+
+    private struct OCRLineDelta: Codable {
+        let index: Int
+        let newRect: RectDTO
+        let baselineRect: RectDTO
+        let deltaX: Double
+        let deltaY: Double
+        let text: String
+    }
+
+    private static func writeOCRDump(
+        stats: OCRStats,
+        testName: String,
+        identifier: String,
+        label: String,
+        outputDir: String
+    ) {
+        let lines = clusterLines(rects: stats.rects, texts: stats.texts)
+        let payload = OCRDump(
+            label: label,
+            imageWidth: Double(stats.imageSize.width),
+            imageHeight: Double(stats.imageSize.height),
+            topPadding: Double(stats.topPadding),
+            bottomPadding: Double(stats.bottomPadding),
+            leftPadding: Double(stats.leftPadding),
+            rightPadding: Double(stats.rightPadding),
+            lines: lines.enumerated().map { index, line in
+                OCRLine(
+                    index: index,
+                    rect: RectDTO(
+                        x: Double(line.rect.origin.x),
+                        y: Double(line.rect.origin.y),
+                        w: Double(line.rect.size.width),
+                        h: Double(line.rect.size.height)
+                    ),
+                    text: line.text
+                )
+            }
+        )
+        let outputURL = URL(fileURLWithPath: outputDir, isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
+            let fileURL = outputURL.appendingPathComponent("\(testName).\(identifier).\(label).lines.json")
+            let data = try JSONEncoder().encode(payload)
+            try data.write(to: fileURL, options: .atomic)
+            AttachmentDebugLogger.record("[OCR] lines json saved \(fileURL.path)")
+        } catch {
+            AttachmentDebugLogger.record("[OCR] lines json write failed \(error.localizedDescription)")
+        }
+    }
+
+    private static func logOCRLineDeltas(newStats: OCRStats, baselineStats: OCRStats) {
+        let newLines = clusterLines(rects: newStats.rects, texts: newStats.texts)
+        let baseLines = clusterLines(rects: baselineStats.rects, texts: baselineStats.texts)
+        guard !newLines.isEmpty, !baseLines.isEmpty else { return }
+        let count = min(newLines.count, baseLines.count)
+        var samples: [String] = []
+        for index in 0..<min(count, 8) {
+            let newRect = newLines[index].rect
+            let baseRect = baseLines[index].rect
+            let delta = newRect.minY - baseRect.minY
+            samples.append("line\(index) dy=\(String(format: "%.2f", delta))")
+        }
+        AttachmentDebugLogger.record("[OCR] lineDeltaSamples \(samples.joined(separator: ", ")) totalNew=\(newLines.count) totalBase=\(baseLines.count)")
+    }
+
+    private static func writeOCRLineDeltaReport(
+        newStats: OCRStats,
+        baselineStats: OCRStats,
+        testName: String,
+        identifier: String,
+        outputDir: String
+    ) {
+        let newLines = clusterLines(rects: newStats.rects, texts: newStats.texts)
+        let baseLines = clusterLines(rects: baselineStats.rects, texts: baselineStats.texts)
+        guard !newLines.isEmpty, !baseLines.isEmpty else { return }
+        let count = min(newLines.count, baseLines.count)
+        let deltas: [OCRLineDelta] = (0..<count).map { index in
+            let newLine = newLines[index]
+            let baseLine = baseLines[index]
+            return OCRLineDelta(
+                index: index,
+                newRect: RectDTO(
+                    x: Double(newLine.rect.origin.x),
+                    y: Double(newLine.rect.origin.y),
+                    w: Double(newLine.rect.size.width),
+                    h: Double(newLine.rect.size.height)
+                ),
+                baselineRect: RectDTO(
+                    x: Double(baseLine.rect.origin.x),
+                    y: Double(baseLine.rect.origin.y),
+                    w: Double(baseLine.rect.size.width),
+                    h: Double(baseLine.rect.size.height)
+                ),
+                deltaX: Double(newLine.rect.minX - baseLine.rect.minX),
+                deltaY: Double(newLine.rect.minY - baseLine.rect.minY),
+                text: newLine.text
+            )
+        }
+        let payload = OCRLineDeltaReport(
+            label: "line-deltas",
+            count: count,
+            deltas: deltas
+        )
+        let outputURL = URL(fileURLWithPath: outputDir, isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
+            let fileURL = outputURL.appendingPathComponent("\(testName).\(identifier).line-deltas.json")
+            let data = try JSONEncoder().encode(payload)
+            try data.write(to: fileURL, options: .atomic)
+            AttachmentDebugLogger.record("[OCR] line-deltas json saved \(fileURL.path)")
+        } catch {
+            AttachmentDebugLogger.record("[OCR] line-deltas json write failed \(error.localizedDescription)")
+        }
+    }
+
+    private struct LineCluster {
+        let rect: CGRect
+        let text: String
+    }
+
+    private static func clusterLines(rects: [CGRect], texts: [String]) -> [LineCluster] {
+        guard !rects.isEmpty else { return [] }
+        let pairs = zip(rects, texts)
+            .map { (rect: $0.0, text: $0.1) }
+            .sorted { $0.rect.minY < $1.rect.minY }
+        var lines: [LineCluster] = []
+        var currentRects: [CGRect] = []
+        var currentTexts: [String] = []
+        var currentMidY: CGFloat?
+        for pair in pairs {
+            let midY = pair.rect.midY
+            if let current = currentMidY {
+                let threshold = max(4, pair.rect.height * 0.6)
+                if abs(midY - current) <= threshold {
+                    currentRects.append(pair.rect)
+                    currentTexts.append(pair.text)
+                } else {
+                    lines.append(makeLineCluster(rects: currentRects, texts: currentTexts))
+                    currentRects = [pair.rect]
+                    currentTexts = [pair.text]
+                    currentMidY = midY
+                }
+            } else {
+                currentRects = [pair.rect]
+                currentTexts = [pair.text]
+                currentMidY = midY
+            }
+        }
+        if !currentRects.isEmpty {
+            lines.append(makeLineCluster(rects: currentRects, texts: currentTexts))
+        }
+        return lines
+    }
+
+    private static func makeLineCluster(rects: [CGRect], texts: [String]) -> LineCluster {
+        var union = rects.first ?? .zero
+        for rect in rects.dropFirst() {
+            union = union.union(rect)
+        }
+        let joined = texts
+            .filter { !$0.isEmpty }
+            .joined(separator: " | ")
+        return LineCluster(rect: union, text: joined)
+    }
 }
+#endif
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.html b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.html
new file mode 100644
index 0000000..12049dd
--- /dev/null
+++ b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.html
@@ -0,0 +1,7 @@
+<main>
+    <section>
+        <ul>
+            <li>| <a href="#"><img src="https://picsum.photos/20/20.jpg" width="20" height="20"></a></li>
+        </ul>
+    </section>
+</main>
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.png
new file mode 100644
index 0000000..d425c89
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testBulletImageAlignment.bulletImageAlignment.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.html b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.html
new file mode 100644
index 0000000..7a5a189
--- /dev/null
+++ b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.html
@@ -0,0 +1,4 @@
+<body style="margin: 20px;">
+    <div style="width: 200px; height: 200px; margin: 20px 0; background-color: black"></div>
+    <div style="width: 200px; height: 200px; margin: 20px 0; background-color: black"></div>
+</body>
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.png
new file mode 100644
index 0000000..16f0ff4
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testDoubleMarginSquares.doubleMarginSquares.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testHTMLImageWithLineHeight.2.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testHTMLImageWithLineHeight.2.png
new file mode 100644
index 0000000..874ed6e
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testHTMLImageWithLineHeight.2.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testListItemSquareSnapshot.listItemSquare.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testListItemSquareSnapshot.listItemSquare.png
new file mode 100644
index 0000000..f84e4fc
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testListItemSquareSnapshot.listItemSquare.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png
index efcf937..77015e3 100644
Binary files a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byCharWrapping.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png
index 61eae36..d4d0663 100644
Binary files a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testLongWordsWithImages-lineBreakMode.longWordsWithImages_byWordWrapping.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testMarginSquareSnapshot.marginSquare.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testMarginSquareSnapshot.marginSquare.png
new file mode 100644
index 0000000..3418e0f
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testMarginSquareSnapshot.marginSquare.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.html b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.html
new file mode 100644
index 0000000..6e233c9
--- /dev/null
+++ b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.html
@@ -0,0 +1,11 @@
+<div style="font-size: 26px; line-height: 1.5;">
+    <p style="margin: 0 0 8px 0; font-weight: 600;">Ruby annotation demo</p>
+    <p style="margin: 0 0 10px 0;">
+        <ruby ruby-annotation-font-size="14" ruby-scale="0.72" ruby-color="#1b5e20">漢字<rt>かんじ</rt></ruby>
+        を読む
+    </p>
+    <p style="margin: 0;">
+        <ruby ruby-annotation-font-size="12" ruby-position="after" ruby-color="#0d47a1">東京<rt>とうきょう</rt></ruby>
+        <span style="font-size: 20px;">travel</span>
+    </p>
+</div>
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.png
new file mode 100644
index 0000000..fb942c1
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshot.rubyAnnotation.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshotVanilla.rubyAnnotationVanilla.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshotVanilla.rubyAnnotationVanilla.png
new file mode 100644
index 0000000..4ece377
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testRubyAnnotationSnapshotVanilla.rubyAnnotationVanilla.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshot.yomitanEntry.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshot.yomitanEntry.png
new file mode 100644
index 0000000..0cd9a89
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshot.yomitanEntry.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png
new file mode 100644
index 0000000..27395d7
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testYomitanEntrySnapshotMacOS.yomitanEntry.png differ
diff --git a/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testingWordBrek.2.png b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testingWordBrek.2.png
new file mode 100644
index 0000000..db856bc
Binary files /dev/null and b/SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests/testingWordBrek.2.png differ
diff --git a/SwiftUIHTMLExampleUITests/SwiftUIHTMLExampleUITests.swift b/SwiftUIHTMLExampleUITests/SwiftUIHTMLExampleUITests.swift
new file mode 100644
index 0000000..f46a838
--- /dev/null
+++ b/SwiftUIHTMLExampleUITests/SwiftUIHTMLExampleUITests.swift
@@ -0,0 +1,64 @@
+import XCTest
+
+final class SwiftUIHTMLExampleUITests: XCTestCase {
+    override func setUp() {
+        continueAfterFailure = false
+    }
+
+    func testRenderingResultShowsSnapshotHTML() {
+        let app = XCUIApplication()
+        app.launch()
+
+        let snapshotCell = app.buttons["Snapshot Test Preview"].exists
+            ? app.buttons["Snapshot Test Preview"]
+            : app.staticTexts["Snapshot Test Preview"]
+        if !snapshotCell.waitForExistence(timeout: 10) {
+            if app.collectionViews.firstMatch.exists {
+                app.collectionViews.firstMatch.scrollToElement(snapshotCell)
+            } else if app.tables.firstMatch.exists {
+                app.tables.firstMatch.scrollToElement(snapshotCell)
+            } else if app.scrollViews.firstMatch.exists {
+                app.scrollViews.firstMatch.scrollToElement(snapshotCell)
+            }
+        }
+        assertExists(snapshotCell, timeout: 10, name: "Snapshot Test Preview")
+        snapshotCell.tap()
+
+        assertExists(app.staticTexts["Rendering Result"], timeout: 10, name: "Rendering Result")
+        let parseStatus = app.staticTexts.matching(NSPredicate(format: "label BEGINSWITH %@", "Parse ok")).firstMatch
+        assertExists(parseStatus, timeout: 10, name: "Parse ok")
+        print("Parse status label: \(parseStatus.label)")
+        XCTAssertFalse(parseStatus.label.contains("children=0"), "Parse result has zero children: \(parseStatus.label)")
+
+        let renderSizeLabel = app.staticTexts.matching(NSPredicate(format: "label BEGINSWITH %@", "Render size:")).firstMatch
+        assertExists(renderSizeLabel, timeout: 10, name: "Render size")
+        print("Render size label: \(renderSizeLabel.label)")
+        XCTAssertFalse(renderSizeLabel.label.contains("0x0"), "Render size is zero: \(renderSizeLabel.label)")
+        assertExists(app.staticTexts["Snapshot Test HTML"], timeout: 10, name: "Rendered HTML title")
+    }
+
+    private func assertExists(_ element: XCUIElement, timeout: TimeInterval, name: String) {
+        if element.waitForExistence(timeout: timeout) {
+            return
+        }
+
+        print("Missing \(name). App hierarchy:\n\(XCUIApplication().debugDescription)")
+        let screenshot = XCUIScreen.main.screenshot()
+        let attachment = XCTAttachment(screenshot: screenshot)
+        attachment.name = "Missing-\(name)"
+        attachment.lifetime = .keepAlways
+        add(attachment)
+
+        XCTFail("Expected to find \(name).")
+    }
+}
+
+private extension XCUIElement {
+    func scrollToElement(_ element: XCUIElement, maxSwipes: Int = 12) {
+        var attempts = 0
+        while !element.exists && attempts < maxSwipes {
+            swipeUp()
+            attempts += 1
+        }
+    }
+}
diff --git a/Tests/SwiftUIHTMLTests/HTMLMinifierTests.swift b/Tests/SwiftUIHTMLTests/HTMLMinifierTests.swift
new file mode 100644
index 0000000..d83582f
--- /dev/null
+++ b/Tests/SwiftUIHTMLTests/HTMLMinifierTests.swift
@@ -0,0 +1,176 @@
+//  Copyright © 2025 PRND. All rights reserved.
+import SwiftUI
+import Testing
+@testable import SwiftUIHTML
+
+struct HTMLMinifierTests {
+    @Test("Minify removes line breaks after <br>")
+    func minify_removesLineBreaksAfterBR() {
+        let html = "<p>Hello<br>   \nWorld</p>"
+        let result = HTMLMinifier.minify(html)
+        #expect(result == "<p>Hello<br>World</p>")
+    }
+
+    @Test("Minify removes tag-only newlines")
+    func minify_removesNewlinesBetweenTags() {
+        let html = "<p>One</p>\n   <p>Two</p>"
+        let result = HTMLMinifier.minify(html)
+        #expect(result == "<p>One</p><p>Two</p>")
+    }
+
+    @Test("Minify replaces pure whitespace between tags with &nbsp;")
+    func minify_replacesWhitespaceBetweenTagsWithNbsp() {
+        let html = "<div>   </div>"
+        let result = HTMLMinifier.minify(html)
+        #expect(result == "<div>&nbsp;&nbsp;&nbsp;</div>")
+    }
+
+    @Test("Minify replaces inline line breaks with a space")
+    func minify_replacesInlineLineBreaks() {
+        let html = "<p>Hello\nWorld\tTab</p>"
+        let result = HTMLMinifier.minify(html)
+        #expect(result == "<p>Hello World Tab</p>")
+    }
+
+    @Test("Minify preserves short input", arguments: ["", "a", "ab", "abc"])
+    func minify_preservesShortInput(_ html: String) {
+        #expect(HTMLMinifier.minify(html) == html)
+    }
+}
+
+struct CSSFontUtilityTests {
+    @Test(
+        "parseSize handles keywords and units",
+        arguments: [
+            ("large", 10.0, 12.0),
+            ("16px", 10.0, 16.0),
+            ("12pt", 10.0, 12.0),
+            ("1.5em", 10.0, 15.0),
+            ("2rem", 10.0, 20.0),
+            ("150%", 10.0, 15.0),
+            ("0.5", 10.0, 0.5)
+        ]
+    )
+    func parseSize_handlesKeywordAndUnits(_ fontSize: String, baseSize: Double, expected: Double) {
+        let result = Double(CSSFontUtility.parseSize(fromFontSize: fontSize, baseSize: baseSize))
+        #expect(abs(result - expected) < 0.0001)
+    }
+}
+
+struct AttributeValueTests {
+    @Test("AttributeValue parses numeric and boolean helpers")
+    func attributeValue_parsingHelpers() {
+        #expect(AttributeValue(rawValue: "12px").int == 12)
+        #expect(AttributeValue(rawValue: "12px").float == 12)
+        #expect(AttributeValue(rawValue: "infinity").cgFloat == .infinity)
+        #expect(AttributeValue(rawValue: "true").toBool() == true)
+        #expect(AttributeValue(rawValue: "0").toBool() == false)
+    }
+
+    @Test("AttributeValue parses URL and CSS style")
+    func attributeValue_urlAndCssStyle() {
+        #expect(AttributeValue(rawValue: "https://example.com").url?.host == "example.com")
+        let style = AttributeValue(rawValue: "color: red; line-height: 20").cssStyle
+        #expect(style?["color"]?.string == "red")
+        #expect(style?["line-height"]?.cgFloat == 20)
+    }
+}
+
+struct CSSStyleTests {
+    @Test("CSSStyle handles empty and whitespace-only inputs")
+    func cssStyle_emptyString() {
+        #expect(CSSStyle(style: "") == nil)
+        let whitespaceStyle = CSSStyle(style: "   ")
+        #expect(whitespaceStyle != nil)
+        #expect(whitespaceStyle?[""]?.string == "")
+    }
+}
+
+struct EdgeInsetsParsingTests {
+    @Test("EdgeInsets parses 1-4 value CSS shorthands")
+    func edgeInsets_cssShorthand() {
+        let one = EdgeInsets(cssString: "10px")
+        #expect(one?.top == 10)
+        #expect(one?.leading == 10)
+        #expect(one?.bottom == 10)
+        #expect(one?.trailing == 10)
+
+        let two = EdgeInsets(cssString: "10px 20px")
+        #expect(two?.top == 10)
+        #expect(two?.leading == 20)
+        #expect(two?.bottom == 10)
+        #expect(two?.trailing == 20)
+
+        let three = EdgeInsets(cssString: "10px 20px 30px")
+        #expect(three?.top == 10)
+        #expect(three?.leading == 20)
+        #expect(three?.bottom == 30)
+        #expect(three?.trailing == 20)
+
+        let four = EdgeInsets(cssString: "10px 20px 30px 40px")
+        #expect(four?.top == 10)
+        #expect(four?.leading == 40)
+        #expect(four?.bottom == 30)
+        #expect(four?.trailing == 20)
+    }
+}
+
+struct ColorParsingTests {
+    @Test("Color parses hex, rgb, and named values")
+    func color_cssString() {
+        #expect(Color(cssString: "#ff0000") != nil)
+        #expect(Color(cssString: "rgb(255, 0, 0)") != nil)
+        #expect(Color(cssString: "red") != nil)
+        #expect(Color(cssString: "not-a-color") == nil)
+    }
+}
+
+struct LineBreakModeTests {
+    @Test("Custom line-break modes compare by id")
+    func lineBreakMode_customEquality() {
+        let left = LineBreakMode.custom(id: "alpha", transform: { $0 })
+        let right = LineBreakMode.custom(id: "alpha", transform: { $0 + "x" })
+        let other = LineBreakMode.custom(id: "beta", transform: { $0 })
+        #expect(left == right)
+        #expect(left != other)
+    }
+
+    @Test("LineBreakMode description is stable")
+    func lineBreakMode_description() {
+        #expect(LineBreakMode.byWordWrapping.description == "byWordWrapping")
+        #expect(LineBreakMode.byCharWrapping.description == "byCharWrapping")
+        #expect(LineBreakMode.custom(id: "custom-id", transform: { $0 }).description == "custom-id")
+    }
+
+    @Test("LineBreakMode callAsFunction applies byCharWrapping")
+    func lineBreakMode_callAsFunction() {
+        let result = LineBreakMode.byCharWrapping("ab")
+        #expect(result == "a\u{200B}b")
+    }
+}
+
+struct HTMLConfigurationTests {
+    private struct TestInlineTag: InlineTag {
+        init() {}
+        static func applyStyles(with attributes: [String : AttributeValue], to styleContainer: inout HTMLStyleContainer) {
+            styleContainer.lineBreakMode = .byCharWrapping
+        }
+    }
+
+    @MainActor
+    @Test("HTMLConfiguration register/remove updates tag type and styles")
+    func configuration_registerRemove() {
+        let config = HTMLConfiguration()
+            .removeAll()
+            .register(tag: "test-inline", renderer: TestInlineTag.self)
+
+        #expect(config.tagType(of: "test-inline") == .inline)
+
+        var container = HTMLStyleContainer()
+        config.applyStyles(tag: "test-inline", attributes: [:], to: &container)
+        #expect(container.lineBreakMode == .byCharWrapping)
+
+        let removed = config.remove(tag: "test-inline")
+        #expect(removed.tagType(of: "test-inline") == nil)
+    }
+}
diff --git a/Tests/SwiftUIHTMLTests/PerformanceTests.swift b/Tests/SwiftUIHTMLTests/PerformanceTests.swift
new file mode 100644
index 0000000..661f65f
--- /dev/null
+++ b/Tests/SwiftUIHTMLTests/PerformanceTests.swift
@@ -0,0 +1,1055 @@
+//  Copyright © 2026 PRND. All rights reserved.
+
+import Foundation
+import Testing
+import SwiftUI
+@testable import SwiftUIHTML
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+
+struct PerformanceTests {
+    @Test
+    func parseSyntheticHTMLPerformanceSmoke() throws {
+        let html = syntheticHTML(sectionCount: 12, includeMedia: false)
+        let parser = SimpleHTMLParser()
+
+        let median = measureMedian {
+            _ = parser.parse(html: html)
+        }
+        print("SwiftUIHTML parse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func parseSyntheticHTMLWithSwiftSoupPerformanceSmoke() throws {
+        let html = syntheticHTML(sectionCount: 8, includeMedia: false)
+        let parser = HTMLSwiftSoupParser()
+
+        let median = measureMedian {
+            _ = parser.parse(html: html)
+        }
+        print("SwiftSoup parse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func textLayoutPerformanceSmoke() throws {
+        let font = PlatformFont.systemFont(ofSize: 14)
+        let text = String(repeating: "SwiftUIHTML layout performance ", count: 80)
+        let attributes: [NSAttributedString.Key: Any] = [.font: font]
+        let attributed = NSMutableAttributedString(string: text, attributes: attributes)
+        let calculator = TextRangeFrameCalculator()
+        let prepared = calculator.prepareCoreTextString(attributed)
+        let ranges = [
+            NSRange(location: 0, length: min(40, attributed.length)),
+            NSRange(location: max(0, attributed.length / 3), length: min(60, attributed.length / 2)),
+            NSRange(location: max(0, attributed.length - 80), length: min(80, attributed.length))
+        ]
+        let containerSize = CGSize(width: 320, height: 800)
+
+        let median = measureMedian {
+            _ = calculator.measureLayout(for: prepared, in: containerSize, by: ranges)
+        }
+        print("Text layout median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func rangeScanBenchmark() throws {
+        let font = PlatformFont.systemFont(ofSize: 13)
+        let line = "SwiftUIHTML range scan text for layout.\n"
+        let text = String(repeating: line, count: 400)
+        let attributed = NSMutableAttributedString(string: text, attributes: [.font: font])
+
+        let strideSize = 12
+        let ranges: [NSRange] = stride(from: 0, to: attributed.length, by: strideSize).map { location in
+            NSRange(location: location, length: min(6, attributed.length - location))
+        }
+        let containerSize = CGSize(width: 320, height: 1800)
+        let calculator = TextRangeFrameCalculator()
+        let prepared = calculator.prepareCoreTextString(attributed)
+        let median = measureMedian {
+            _ = calculator.measureLayout(for: prepared, in: containerSize, by: ranges)
+        }
+
+        print("Range scan median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func inlineTextCoalescingPerformanceSmoke() throws {
+        let style = HTMLStyleContainer()
+        let elements = (0..<2000).map { _ in
+            InlineElement(tag: "_text", attributes: [:], text: "SwiftUIHTML ", styleContainer: style)
+        }
+
+        let median = measureMedian {
+            let inline = HTMLInline(elements: elements)
+            _ = inline.texts.count
+        }
+        print("Inline merge baseline (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s, count \(elements.count)")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func cssStyleParsingPerformanceSmoke() throws {
+        let styles = (0..<2000).map { index in
+            "font-size: \(12 + index % 6)px; color: #333; margin: 4px 8px; padding: 2px; line-height: 1.4; border: 1px solid #eee;"
+        }
+
+        let median = measureMedian {
+            for style in styles {
+                _ = CSSStyle.cached(style: style)
+            }
+        }
+        print("CSSStyle parse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func cssStyleParsingBenchmark() throws {
+        let styles = (0..<6000).map { index in
+            "font-size: \(12 + index % 6)px; color: #333; margin: 4px 8px; padding: 2px; line-height: 1.4; border: 1px solid #eee;"
+        }
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            var total = 0
+            for style in styles {
+                total += parseCSSStyleBaseline(style)
+            }
+            _ = total
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            var total = 0
+            for style in styles {
+                if let parsed = CSSStyle(style: style) {
+                    parsed.forEach { _ in
+                        total += 1
+                    }
+                }
+            }
+            _ = total
+        }
+
+        print("CSS parse baseline: \(String(format: "%.4f", baseline))s")
+        print("CSS parse optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+
+    @Test
+    func attributeCSSStyleBenchmark() throws {
+        let values = (0..<8000).map { index -> String in
+            if index.isMultiple(of: 3) {
+                return "color: #333; font-size: \(12 + index % 6)px;"
+            }
+            return index.isMultiple(of: 2) ? "bold" : "inherit"
+        }
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            var total = 0
+            for value in values {
+                if let parsed = CSSStyle.cached(style: value) {
+                    parsed.forEach { _ in total += 1 }
+                }
+            }
+            _ = total
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            var total = 0
+            for value in values {
+                let attr = AttributeValue(rawValue: value)
+                if let parsed = attr.cssStyle {
+                    parsed.forEach { _ in total += 1 }
+                }
+            }
+            _ = total
+        }
+
+        print("Attribute cssStyle baseline: \(String(format: "%.4f", baseline))s")
+        print("Attribute cssStyle optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+
+
+    @Test
+    @MainActor
+    func heavyTextLayoutBenchmark() throws {
+        let font = PlatformFont.systemFont(ofSize: 13)
+        let paragraph = "SwiftUIHTML heavy layout benchmark line with mixed width words and glyphs.\n"
+        let text = String(repeating: paragraph, count: 1800)
+        let attributed = NSMutableAttributedString(string: text, attributes: [.font: font])
+
+        let ranges: [NSRange] = stride(from: 0, to: attributed.length, by: 7).map { location in
+            NSRange(location: location, length: min(5, attributed.length - location))
+        }
+        let containerSize = CGSize(width: 420, height: 8000)
+
+        let calculator = TextRangeFrameCalculator()
+        let prepared = calculator.prepareCoreTextString(attributed)
+        let median = measureMedian {
+            _ = calculator.measureLayout(for: prepared, in: containerSize, by: ranges)
+        }
+
+        print("Heavy layout median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func heavyCSSParsingBenchmark() throws {
+        let styles = (0..<12000).map { index in
+            "font-size: \(12 + index % 6)px; color: #333; margin: 4px 8px; padding: 2px; line-height: 1.4; border: 1px solid #eee; letter-spacing: 0.\(index % 7)em; background-color: #fafafa;"
+        }
+
+        let median = measureMedian {
+            for style in styles {
+                _ = CSSStyle.cached(style: style)
+            }
+        }
+        print("Heavy CSSStyle parse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func listParsingBenchmark() throws {
+        guard let parser = makeSwiftSoupParserIfAvailable() else {
+            print("SwiftSoup parser not available; skipping listParsingBenchmark")
+            #expect(true)
+            return
+        }
+
+        let html = listHeavyHTML(itemCount: 2000, depth: 3)
+        let median = measureMedian {
+            _ = parser.parse(html: html)
+        }
+        print("List HTML parse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func htmlViewLifecycleBenchmark() throws {
+        guard let parser = makeSwiftSoupParserIfAvailable() else {
+            print("SwiftSoup parser not available; skipping htmlViewLifecycleBenchmark")
+            #expect(true)
+            return
+        }
+
+        let html = listHeavyHTML(itemCount: 2000, depth: 3)
+        let configuration = HTMLConfiguration()
+        let styleContainer = HTMLStyleContainer()
+
+        let median = measureMedian {
+            AttachmentIDGenerator.reset()
+            let node = parser.parse(html: html)
+            _ = node.toElement(configuration: configuration, with: styleContainer)
+        }
+
+        print("HTML view lifecycle median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func htmlViewReRenderBenchmark() throws {
+        guard let parser = makeSwiftSoupParserIfAvailable() else {
+            print("SwiftSoup parser not available; skipping htmlViewReRenderBenchmark")
+            #expect(true)
+            return
+        }
+
+        let html = listHeavyHTML(itemCount: 2000, depth: 3)
+        let configuration = HTMLConfiguration()
+        let styleContainer = HTMLStyleContainer()
+        let node = parser.parse(html: html)
+        let cachedElement = node.toElement(configuration: configuration, with: styleContainer)
+
+        let rebuild = measureMedian {
+            _ = node.toElement(configuration: configuration, with: styleContainer)
+        }
+
+        let reuse = measureMedian {
+            _ = cachedElement.contents.count
+        }
+
+        print("HTML view rebuild median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", rebuild))s")
+        print("HTML view reuse median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.6f", reuse))s")
+
+        #expect(rebuild > 0)
+        #expect(reuse >= 0)
+    }
+
+    @Test
+    @MainActor
+    func listElementBuildBenchmark() throws {
+        guard let parser = makeSwiftSoupParserIfAvailable() else {
+            print("SwiftSoup parser not available; skipping listElementBuildBenchmark")
+            #expect(true)
+            return
+        }
+
+        let html = listHeavyHTML(itemCount: 900, depth: 2)
+        let node = parser.parse(html: html)
+        let configuration = HTMLConfiguration().attributeStyler(DefaultAttributeStyler())
+        let baseStyle = HTMLStyleContainer()
+
+        let median = measureMedian {
+            let element = node.toElement(configuration: configuration, with: baseStyle)
+            _ = element.contents.count
+        }
+        print("List element build median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    @MainActor
+    func elementBuildBenchmarkAB() throws {
+        let node = makeListNodeTree(itemCount: 220, depth: 2)
+        let configuration = HTMLConfiguration().attributeStyler(DefaultAttributeStyler())
+        let baseStyle = HTMLStyleContainer()
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            _ = toElementBaseline(node: node, configuration: configuration, styleContainer: baseStyle)
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            _ = node.toElement(configuration: configuration, with: baseStyle)
+        }
+
+        print("Element build baseline: \(String(format: "%.4f", baseline))s")
+        print("Element build optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+    @Test
+    @MainActor
+    func rubyPipelineBenchmark() throws {
+        guard let parser = makeSwiftSoupParserIfAvailable() else {
+            print("SwiftSoup parser not available; skipping rubyPipelineBenchmark")
+            #expect(true)
+            return
+        }
+
+        let html = rubyHeavyHTML(count: 600)
+        let node = parser.parse(html: html)
+        let configuration = HTMLConfiguration().attributeStyler(DefaultAttributeStyler())
+        let baseStyle = HTMLStyleContainer()
+
+        let median = measureMedian {
+            let element = node.toElement(configuration: configuration, with: baseStyle)
+            _ = element.contents.count
+        }
+        print("Ruby pipeline median (>=\(benchmarkMinimumSeconds())s): \(String(format: "%.4f", median))s")
+
+        #expect(median > 0)
+    }
+
+    @Test
+    func rubyExtractionBenchmarkAB() throws {
+        let children = makeRubyChildren(count: 800)
+        let baseFont = PlatformFont.systemFont(ofSize: 14)
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            _ = rubyExtractionBaseline(children: children, baseFont: baseFont)
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            _ = rubyExtractionOptimized(children: children, baseFont: baseFont)
+        }
+
+        print("Ruby extract baseline: \(String(format: "%.4f", baseline))s")
+        print("Ruby extract optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+    @Test
+    func rgbParsingBenchmark() throws {
+        let inputs = (0..<5000).map { index in
+            let r = index % 255
+            let g = (index * 2) % 255
+            let b = (index * 3) % 255
+            let a = Double((index % 10)) / 10.0
+            return index.isMultiple(of: 2)
+                ? "rgb(\(r), \(g), \(b))"
+                : "rgba(\(r), \(g), \(b), \(a))"
+        }
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            for value in inputs {
+                _ = parseRGBRegex(value)
+            }
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            for value in inputs {
+                _ = Color(cssString: value)
+            }
+        }
+
+        print("RGB parse baseline: \(String(format: "%.4f", baseline))s")
+        print("RGB parse optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+    @Test
+    func htmlChildTrimmingBenchmarkAB() throws {
+        let values = (0..<12000).map { index -> String in
+            if index.isMultiple(of: 3) {
+                return "  Trim me \(index)  "
+            }
+            return "NoTrim\(index)"
+        }
+
+        let baseline = measureMedian(minSeconds: 2.0) {
+            for value in values {
+                _ = trimmingTextBaseline(value)
+            }
+        }
+
+        let optimized = measureMedian(minSeconds: 2.0) {
+            for value in values {
+                _ = HTMLChild.trimmingText(value)
+            }
+        }
+
+        print("HTMLChild trim baseline: \(String(format: "%.4f", baseline))s")
+        print("HTMLChild trim optimized: \(String(format: "%.4f", optimized))s")
+
+        #expect(baseline > 0)
+        #expect(optimized > 0)
+    }
+
+}
+
+private struct SimpleHTMLParser: HTMLParserable {
+    func parse(html: String) -> HTMLNode {
+        let stripped = html
+            .replacingOccurrences(of: "<[^>]+>", with: "", options: .regularExpression)
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if stripped.isEmpty {
+            return HTMLNode(tag: "div", attributes: [:], children: [])
+        }
+        return HTMLNode(tag: "div", attributes: [:], children: [.text(stripped)])
+    }
+}
+
+// Inline coalescing removed after stress benchmarking showed it was slower at scale.
+
+#if canImport(SwiftSoup)
+import SwiftSoup
+
+private struct HTMLSwiftSoupParser: HTMLParserable {
+    func parse(html: String) -> HTMLNode {
+        do {
+            let document = try SwiftSoup.parse(html)
+            if let body = document.body() {
+                return try buildHTMLNode(from: body)
+            } else if let wrapper = try document.select("*").first() {
+                return try buildHTMLNode(from: wrapper)
+            }
+        } catch {
+            return HTMLNode(tag: "div", attributes: [:], children: [.text("Parse error: \(error.localizedDescription)")])
+        }
+        return HTMLNode(tag: "div", attributes: [:], children: [])
+    }
+}
+
+private struct HTMLSwiftSoupParserBench: HTMLParserable {
+    func parse(html: String) -> HTMLNode {
+        do {
+            let document = try SwiftSoup.parse(html)
+            if let body = document.body() {
+                return try buildHTMLNode(from: body)
+            } else if let wrapper = try document.select("*").first() {
+                return try buildHTMLNode(from: wrapper)
+            }
+        } catch {
+            return HTMLNode(tag: "div", attributes: [:], children: [.text("Parse error: \(error.localizedDescription)")])
+        }
+        return HTMLNode(tag: "div", attributes: [:], children: [])
+    }
+}
+
+private func buildHTMLNode(from root: Element) throws -> HTMLNode {
+    try buildHTMLNodeIterative(from: root)
+}
+
+private final class SwiftSoupNodeBuilder {
+    private static let emptyAttributes: [String: AttributeValue] = [:]
+
+    let tag: String
+    let attributes: [String: AttributeValue]
+    let childNodes: [Node]
+    let capacityHint: Int
+    var childIndex: Int
+    var children: [HTMLChild]?
+
+    init(element: Element) {
+        let tag = element.tagName()
+        self.tag = tag
+        if let rawAttributes = element.getAttributes(), rawAttributes.size() > 0 {
+            var attributes: [String: AttributeValue] = [:]
+            attributes.reserveCapacity(rawAttributes.size())
+            for attribute in rawAttributes {
+                attributes[attribute.getKey()] = AttributeValue(rawValue: attribute.getValue())
+            }
+            self.attributes = attributes
+        } else {
+            self.attributes = Self.emptyAttributes
+        }
+        let count = element.childNodeSize()
+        self.capacityHint = count
+        if count > 0 {
+            self.childNodes = element.getChildNodes()
+        } else {
+            self.childNodes = []
+        }
+        self.childIndex = 0
+        self.children = nil
+    }
+
+    func appendChild(_ child: HTMLChild) {
+        if children == nil {
+            var storage: [HTMLChild] = []
+            if capacityHint > 0 {
+                storage.reserveCapacity(capacityHint)
+            }
+            children = storage
+        }
+        children?.append(child)
+    }
+}
+
+private func buildHTMLNodeIterative(from root: Element) throws -> HTMLNode {
+    var stack: [SwiftSoupNodeBuilder] = []
+    stack.reserveCapacity(64)
+    stack.append(SwiftSoupNodeBuilder(element: root))
+
+    while let current = stack.last {
+        if current.childIndex < current.capacityHint {
+            let child = current.childNodes[current.childIndex]
+            current.childIndex += 1
+
+            if let textNode = child as? TextNode {
+                let text = textNode.text()
+                if !text.isEmpty {
+                    current.appendChild(.text(text))
+                }
+                continue
+            }
+            if let elementNode = child as? Element {
+                if isBRTag(elementNode.tagName()) {
+                    current.appendChild(.newLine)
+                    continue
+                }
+                stack.append(SwiftSoupNodeBuilder(element: elementNode))
+            }
+        } else {
+            _ = stack.popLast()
+            let built = HTMLNode(
+                tag: current.tag,
+                attributes: current.attributes,
+                children: current.children ?? []
+            )
+            if stack.isEmpty {
+                return built
+            }
+            stack[stack.count - 1].appendChild(.node(built))
+        }
+    }
+
+    return HTMLNode(tag: "div", attributes: [:], children: [])
+}
+
+@inline(__always)
+private func isBRTag(_ raw: String) -> Bool {
+    var iterator = raw.utf8.makeIterator()
+    guard let first = iterator.next(), let second = iterator.next() else { return false }
+    if iterator.next() != nil { return false }
+    let isB = first == 0x62 || first == 0x42
+    let isR = second == 0x72 || second == 0x52
+    return isB && isR
+}
+#endif
+private func syntheticHTML(sectionCount: Int, includeMedia: Bool) -> String {
+    var chunks: [String] = []
+    chunks.reserveCapacity(sectionCount * 6)
+
+    chunks.append("""
+        <body style=\"margin: 0; padding: 0;\">
+            <header style=\"background-color: #f0f0f0; padding: 16px; border-radius: 8px; margin-bottom: 12px;\">
+                <h1 style=\"color: #333;\">SwiftUIHTML Stress Test</h1>
+                <p style=\"color: #666;\">Synthetic HTML payload exercising tags, CSS, and attachments.</p>
+            </header>
+            <main>
+        """)
+
+    for index in 1...sectionCount {
+        let mediaHTML: String
+        if includeMedia {
+            mediaHTML = """
+                <p>
+                    <img src=\"https://picsum.photos/seed/\(index)/80/60\" width=\"80\" height=\"60\" />
+                    <video src=\"https://example.com/video\(index).mp4\" />
+                </p>
+                """
+        } else {
+            mediaHTML = ""
+        }
+
+        chunks.append("""
+            <section style=\"margin: 12px 0; padding: 12px; border: 1px solid #ddd; border-radius: 6px;\">
+                <h2 style=\"color: #1a4; font-size: 18px;\">Section \(index)</h2>
+                <p style=\"line-height: 20px;\">
+                    Inline styles: <span style=\"color: #c33;\">red</span>,
+                    <span style=\"background-color: #ff0;\">yellow</span>,
+                    <strong>bold</strong>, <em>italic</em>, <u>underline</u>.
+                </p>
+                <p>
+                    Ruby: <ruby ruby-position=\"after\" ruby-scale=\"0.5\">漢字<rt>かんじ</rt></ruby>.
+                </p>
+                <ul>
+                    <li>Item \(index).1</li>
+                    <li>Item \(index).2 with <span style=\"color: #05a;\">color</span></li>
+                    <li>Item \(index).3</li>
+                </ul>
+                \(mediaHTML)
+            </section>
+            """)
+    }
+
+    chunks.append("""
+            </main>
+            <footer style=\"margin-top: 16px; padding: 12px; background-color: #333; color: white;\">
+                <p>Footer content for synthetic payload.</p>
+            </footer>
+        </body>
+        """)
+
+    return chunks.joined(separator: "\n")
+}
+
+private func parseRGBRegex(_ rgbString: String) -> Color? {
+    let rgbPattern = "rgba?\\((\\d+),\\s*(\\d+),\\s*(\\d+)(?:,\\s*([0-9.]+))?\\)"
+    guard let regex = try? NSRegularExpression(pattern: rgbPattern, options: []),
+          let match = regex.firstMatch(in: rgbString, options: [], range: NSRange(rgbString.startIndex..<rgbString.endIndex, in: rgbString)) else {
+        return nil
+    }
+
+    var components: [Double] = []
+    for i in 1..<match.numberOfRanges {
+        if let range = Range(match.range(at: i), in: rgbString),
+           !rgbString[range].isEmpty {
+            if let value = Double(rgbString[range]) {
+                components.append(value)
+            } else if i == 4 {
+                components.append(1.0)
+            } else {
+                return nil
+            }
+        } else if i == 4 {
+            components.append(1.0)
+        } else {
+            return nil
+        }
+    }
+
+    guard components.count >= 3 else { return nil }
+    let r = min(max(components[0] / 255.0, 0), 1)
+    let g = min(max(components[1] / 255.0, 0), 1)
+    let b = min(max(components[2] / 255.0, 0), 1)
+    let a = min(max(components.count >= 4 ? components[3] : 1.0, 0), 1)
+    return Color(.sRGB, red: r, green: g, blue: b, opacity: a)
+}
+
+private func parseCSSStyleBaseline(_ style: String) -> Int {
+    var count = 0
+    for component in style.split(separator: ";", omittingEmptySubsequences: true) {
+        let keyValue = component.split(separator: ":", maxSplits: 1)
+        guard keyValue.count == 2 else { continue }
+        let key = keyValue[0].trimmingCharacters(in: .whitespaces)
+        let value = keyValue[1].trimmingCharacters(in: .whitespaces)
+        guard !key.isEmpty, !value.isEmpty else { continue }
+        count += 1
+    }
+    return count
+}
+
+private func trimmingTextBaseline(_ string: String) -> HTMLChild {
+    let trimmed = ASCIIWhitespace.trim(string)
+    if trimmed.startIndex == string.startIndex && trimmed.endIndex == string.endIndex {
+        return .text(string)
+    }
+    return .text(String(trimmed))
+}
+
+@MainActor
+private func toElementBaseline(node: HTMLNode, configuration: HTMLConfiguration, styleContainer: HTMLStyleContainer) -> BlockElement {
+    var contents: [TagElement] = []
+    contents.reserveCapacity(node.children.count)
+    for child in node.children {
+        contents.append(contentsOf: childElementsBaseline(child, configuration: configuration, styleContainer: styleContainer))
+    }
+    return BlockElement(
+        tag: node.tagName,
+        attributes: node.attributes,
+        contents: contents,
+        styleContainer: styleContainer
+    )
+}
+
+@MainActor
+private func childElementsBaseline(_ child: HTMLChild, configuration: HTMLConfiguration, styleContainer: HTMLStyleContainer) -> [TagElement] {
+    switch child {
+    case let .text(text) where text.isEmpty:
+        return []
+    case let .text(text):
+        return [
+            .inline(InlineElement(
+                tag: "_text",
+                attributes: [:],
+                text: text,
+                styleContainer: styleContainer
+            ))
+        ]
+    case let .node(childNode):
+        return makeElementBaseline(node: childNode, configuration: configuration, styleContainer: styleContainer)
+    }
+}
+
+@MainActor
+private func makeElementBaseline(node: HTMLNode, configuration: HTMLConfiguration, styleContainer: HTMLStyleContainer) -> [TagElement] {
+    var _styleContainer = styleContainer
+    configuration.applyStyles(tag: node.tagName, attributes: node.attributes, to: &_styleContainer)
+
+    switch configuration.tagType(of: node.tagName) {
+    case .inline:
+        var contents: [TagElement] = []
+        contents.reserveCapacity(node.children.count)
+        for child in node.children {
+            contents.append(contentsOf: childElementsBaseline(child, configuration: configuration, styleContainer: _styleContainer))
+        }
+        return contents
+
+    case .attachment:
+        return [
+            .inline(InlineElement(
+                tag: node.tagName,
+                attributes: node.attributes,
+                type: .attachment,
+                styleContainer: _styleContainer
+            ))
+        ]
+
+    case .block, .none:
+        return [
+            .block(toElementBaseline(node: node, configuration: configuration, styleContainer: _styleContainer))
+        ]
+    }
+}
+
+private func rubyPlainText(_ node: HTMLNode) -> String {
+    var result = ""
+    for child in node.children {
+        switch child {
+        case let .text(text):
+            result.append(text)
+        case let .node(node):
+            result.append(rubyPlainText(node))
+        }
+    }
+    return result
+}
+
+private func makeListNodeTree(itemCount: Int, depth: Int) -> HTMLNode {
+    func buildList(level: Int) -> HTMLNode {
+        var items: [HTMLChild] = []
+        items.reserveCapacity(itemCount)
+        let nestedStride = max(1, itemCount / 5)
+
+        for index in 1...itemCount {
+            var liChildren: [HTMLChild] = [
+                .text("Item \(index) with "),
+                .node(HTMLNode(
+                    tag: "span",
+                    attributes: ["style": "font-weight: 600; color: #05a;"],
+                    children: [.text("bold")]
+                )),
+                .text(" text.")
+            ]
+            if level > 0, index.isMultiple(of: nestedStride) {
+                liChildren.append(.node(buildList(level: level - 1)))
+            }
+            let li = HTMLNode(
+                tag: "li",
+                attributes: ["style": "margin: 2px 0; padding-left: 8px;"],
+                children: liChildren
+            )
+            items.append(.node(li))
+        }
+
+        return HTMLNode(tag: "ul", children: items)
+    }
+
+    return HTMLNode(
+        tag: "div",
+        attributes: ["style": "padding: 12px; border: 1px solid #ddd;"],
+        children: [.node(buildList(level: depth))]
+    )
+}
+
+private func makeRubyChildren(count: Int) -> [HTMLChild] {
+    var children: [HTMLChild] = []
+    children.reserveCapacity(count * 2)
+    for index in 1...count {
+        let base = HTMLChild.text("漢字\(index)")
+        let rt = HTMLChild.node(
+            HTMLNode(
+                tag: "rt",
+                attributes: ["style": "font-size: \(10 + index % 4)px; font-family: Helvetica;"],
+                children: [.text("かんじ\(index)")]
+            )
+        )
+        children.append(base)
+        children.append(rt)
+    }
+    return children
+}
+
+private func rubyExtractionBaseline(children: [HTMLChild], baseFont: PlatformFont?) -> (base: String?, ruby: String?, annotationSize: CGFloat?, annotationName: String?) {
+    var baseText = ""
+    var rubyText = ""
+    var hasBase = false
+    var hasRuby = false
+
+    for child in children {
+        switch child {
+        case let .text(text):
+            if !text.isEmpty {
+                baseText.append(text)
+                hasBase = true
+            }
+        case let .node(node):
+            switch node.tag {
+            case "rt":
+                let trimmedText = rubyPlainText(node).trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmedText.isEmpty {
+                    if hasRuby {
+                        rubyText.append(" ")
+                    }
+                    rubyText.append(trimmedText)
+                    hasRuby = true
+                }
+            case "rp", "rtc":
+                continue
+            case "rb":
+                let text = rubyPlainText(node)
+                if !text.isEmpty {
+                    baseText.append(text)
+                    hasBase = true
+                }
+            default:
+                let text = rubyPlainText(node)
+                if !text.isEmpty {
+                    baseText.append(text)
+                    hasBase = true
+                }
+            }
+        }
+    }
+
+    var size: CGFloat?
+    var name: String?
+    for child in children {
+        guard case let .node(node) = child, node.tag == "rt" else { continue }
+        guard let cssStyle = node.attributes["style"]?.cssStyle else { continue }
+        if size == nil, let fontSize = cssStyle["font-size"]?.string {
+            let baseSize = baseFont?.pointSize ?? PlatformFont.systemFontSize
+            size = CSSFontUtility.parseSize(fromFontSize: fontSize, baseSize: baseSize)
+        }
+        if name == nil, let font = CSSFontUtility.createFont(fromCSSStyle: cssStyle, currentFont: baseFont) {
+            name = font.fontName
+        }
+        if size != nil && name != nil {
+            break
+        }
+    }
+
+    return (
+        base: hasBase ? baseText : nil,
+        ruby: hasRuby ? rubyText : nil,
+        annotationSize: size,
+        annotationName: name
+    )
+}
+
+private func rubyExtractionOptimized(children: [HTMLChild], baseFont: PlatformFont?) -> (base: String?, ruby: String?, annotationSize: CGFloat?, annotationName: String?) {
+    var baseText = ""
+    var rubyText = ""
+    var hasBase = false
+    var hasRuby = false
+    var annotationSize: CGFloat?
+    var annotationName: String?
+
+    for child in children {
+        switch child {
+        case let .text(text):
+            if !text.isEmpty {
+                baseText.append(text)
+                hasBase = true
+            }
+        case let .node(node):
+            switch node.tag {
+            case "rt":
+                let trimmedText = ASCIIWhitespace.trim(rubyPlainText(node)).trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmedText.isEmpty {
+                    if hasRuby {
+                        rubyText.append(" ")
+                    }
+                    rubyText.append(contentsOf: trimmedText)
+                    hasRuby = true
+                }
+                if annotationSize == nil || annotationName == nil {
+                    if let cssStyle = node.attributes["style"]?.cssStyle {
+                        if annotationSize == nil, let fontSize = cssStyle["font-size"]?.string {
+                            let baseSize = baseFont?.pointSize ?? PlatformFont.systemFontSize
+                            annotationSize = CSSFontUtility.parseSize(fromFontSize: fontSize, baseSize: baseSize)
+                        }
+                        if annotationName == nil, let font = CSSFontUtility.createFont(fromCSSStyle: cssStyle, currentFont: baseFont) {
+                            annotationName = font.fontName
+                        }
+                    }
+                }
+            case "rp", "rtc":
+                continue
+            case "rb":
+                let text = rubyPlainText(node)
+                if !text.isEmpty {
+                    baseText.append(text)
+                    hasBase = true
+                }
+            default:
+                let text = rubyPlainText(node)
+                if !text.isEmpty {
+                    baseText.append(text)
+                    hasBase = true
+                }
+            }
+        }
+    }
+
+    return (
+        base: hasBase ? baseText : nil,
+        ruby: hasRuby ? rubyText : nil,
+        annotationSize: annotationSize,
+        annotationName: annotationName
+    )
+}
+
+
+
+
+
+private func listHeavyHTML(itemCount: Int, depth: Int) -> String {
+    var items: [String] = []
+    items.reserveCapacity(itemCount)
+    for index in 1...itemCount {
+        let style = "style=\"margin: 2px 0; padding-left: 8px; color: #\(String(format: "%03x", index % 0xfff))\""
+        items.append("<li \(style)>Item \(index) with <span style=\"font-weight: 600;\">bold</span> text.</li>")
+    }
+
+    func nestedList(level: Int) -> String {
+        if level <= 0 {
+            return "<ul>\(items.joined())</ul>"
+        }
+        return "<ul>\(items.prefix(max(20, itemCount / (level + 1))).joined())<li>Nested\(nestedList(level: level - 1))</li></ul>"
+    }
+
+    return """
+    <body>
+        <section style="padding: 12px; border: 1px solid #ddd;">
+            <h2>List Benchmark</h2>
+            \(nestedList(level: depth))
+        </section>
+    </body>
+    """
+}
+
+private func rubyHeavyHTML(count: Int) -> String {
+    var chunks: [String] = []
+    chunks.reserveCapacity(count)
+    for index in 1...count {
+        let base = "漢字\(index)"
+        let rt = "かんじ\(index)"
+        let style = "style=\"ruby-position: after; ruby-scale: 0.55; color: #333;\""
+        let rtStyle = "style=\"font-size: \(10 + index % 4)px; font-family: Helvetica;\""
+        chunks.append("<ruby \(style)>\(base)<rt \(rtStyle)>\(rt)</rt></ruby>")
+    }
+    return "<body><p>\(chunks.joined(separator: " "))</p></body>"
+}
+
+@MainActor
+private func makeSwiftSoupParserIfAvailable() -> HTMLParserable? {
+#if canImport(SwiftSoup)
+    return HTMLSwiftSoupParserBench()
+#else
+    return nil
+#endif
+}
+
+@inline(__always)
+private func benchmarkMinimumSeconds() -> TimeInterval {
+    4.0
+}
+
+@inline(__always)
+private func measureMedian(minSeconds: TimeInterval? = nil, _ block: () -> Void) -> TimeInterval {
+    let minSeconds = minSeconds ?? benchmarkMinimumSeconds()
+    var durations: [TimeInterval] = []
+    durations.reserveCapacity(64)
+
+    let warmupCount = 8
+    for _ in 0..<warmupCount {
+        block()
+    }
+
+    let deadline = CFAbsoluteTimeGetCurrent() + minSeconds
+    repeat {
+        let start = CFAbsoluteTimeGetCurrent()
+        block()
+        durations.append(CFAbsoluteTimeGetCurrent() - start)
+    } while CFAbsoluteTimeGetCurrent() < deadline
+
+    let sorted = durations.sorted()
+    return sorted[sorted.count / 2]
+}
diff --git a/Tests/SwiftUIHTMLTests/RubyTagTests.swift b/Tests/SwiftUIHTMLTests/RubyTagTests.swift
new file mode 100644
index 0000000..81fffea
--- /dev/null
+++ b/Tests/SwiftUIHTMLTests/RubyTagTests.swift
@@ -0,0 +1,288 @@
+import SwiftUI
+import Testing
+@testable import SwiftUIHTML
+
+@MainActor
+struct RubyTagTests {
+    @Test
+    func rubyNodeCreatesInlineAttachment() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .text("base"),
+                .node(HTMLNode(tag: "rt", children: [.text("ruby")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.tag == "ruby")
+        #expect(inline.attributes["ruby-base"]?.string == "base")
+        #expect(inline.attributes["ruby-text"]?.string == "ruby")
+    }
+
+    @Test
+    func rubyNodeIgnoresRpAndUsesRbAndRt() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .node(HTMLNode(tag: "rb", children: [.text("漢字")])),
+                .node(HTMLNode(tag: "rp", children: [.text("(")])),
+                .node(HTMLNode(tag: "rt", children: [.text("かんじ")])),
+                .node(HTMLNode(tag: "rp", children: [.text(")")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-base"]?.string == "漢字")
+        #expect(inline.attributes["ruby-text"]?.string == "かんじ")
+    }
+
+    @Test
+    func rubyNodePropagatesBaseFontIntoAttributes() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .text("猫"),
+                .node(HTMLNode(tag: "rt", children: [.text("ねこ")]))
+            ]
+        )
+
+        var container = HTMLStyleContainer()
+#if os(macOS)
+        let font = NSFont.systemFont(ofSize: 17)
+#else
+        let font = UIFont.systemFont(ofSize: 17)
+#endif
+        container.uiFont = font
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: container)
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-font-name"]?.string == font.fontName)
+        #expect(inline.attributes["ruby-font-size"]?.string == "\(font.pointSize)")
+    }
+
+    @Test
+    func rubyNodeFlattensNestedInlineText() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .node(HTMLNode(tag: "span", children: [.text("漢")])),
+                .text("字"),
+                .node(HTMLNode(tag: "rt", children: [.text("かん")])),
+                .node(HTMLNode(tag: "rt", children: [.text("じ")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-base"]?.string == "漢字")
+        #expect(inline.attributes["ruby-text"]?.string == "かん じ")
+    }
+
+    @Test
+    func rubyNodeWithoutRtOmitsRubyText() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .text("漢字")
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-base"]?.string == "漢字")
+        #expect(inline.attributes["ruby-text"] == nil)
+    }
+
+    @Test
+    func rubyAttributesPreservePositionAndScale() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            attributes: [
+                "ruby-position": "after",
+                "ruby-scale": "0.5"
+            ],
+            children: [
+                .text("今日"),
+                .node(HTMLNode(tag: "rt", children: [.text("きょう")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-position"]?.string == "after")
+        #expect(inline.attributes["ruby-scale"]?.string == "0.5")
+    }
+
+    @Test
+    func rubyNodeKeepsOriginalAttributes() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            attributes: [
+                "style": "color: #f00;",
+                "data-test": "ruby"
+            ],
+            children: [
+                .text("漢字"),
+                .node(HTMLNode(tag: "rt", children: [.text("かんじ")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["style"]?.string == "color: #f00;")
+        #expect(inline.attributes["data-test"]?.string == "ruby")
+        #expect(inline.attributes["ruby-base"]?.string == "漢字")
+        #expect(inline.attributes["ruby-text"]?.string == "かんじ")
+    }
+
+    @Test
+    func rubyNodeWithOnlyRtDoesNotCreateRubyBase() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .node(HTMLNode(tag: "rt", children: [.text("かんじ")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-base"] == nil)
+        #expect(inline.attributes["ruby-text"] == nil)
+    }
+
+    @Test
+    func rubyNodePreservesBaseWhitespace() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .text(" 漢字 "),
+                .node(HTMLNode(tag: "rt", children: [.text("かんじ")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-base"]?.string == " 漢字 ")
+        #expect(inline.attributes["ruby-text"]?.string == "かんじ")
+    }
+
+    @Test
+    func rubyNodeTrimsRtWhitespace() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            children: [
+                .text("漢字"),
+                .node(HTMLNode(tag: "rt", children: [.text("  かんじ \n")])),
+                .node(HTMLNode(tag: "rt", children: [.text("\tけんじ ")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-text"]?.string == "かんじ けんじ")
+    }
+
+    @Test
+    func rubyNodePreservesRubyFontAttributes() {
+        let rubyNode = HTMLNode(
+            tag: "ruby",
+            attributes: [
+                "ruby-font-name": "HelveticaNeue",
+                "ruby-font-size": "22",
+                "ruby-annotation-font-name": "HiraginoSans-W3",
+                "ruby-annotation-font-size": "12"
+            ],
+            children: [
+                .text("明日"),
+                .node(HTMLNode(tag: "rt", children: [.text("あした")]))
+            ]
+        )
+
+        let root = HTMLNode(tag: "div", children: [.node(rubyNode)])
+        let element = root.toElement(configuration: .default, with: HTMLStyleContainer())
+
+        #expect(element.contents.count == 1)
+        guard case let .inline(inline) = element.contents[0] else {
+            Issue.record("Expected inline element for ruby attachment")
+            return
+        }
+
+        #expect(inline.attributes["ruby-font-name"]?.string == "HelveticaNeue")
+        #expect(inline.attributes["ruby-font-size"]?.string == "22")
+        #expect(inline.attributes["ruby-annotation-font-name"]?.string == "HiraginoSans-W3")
+        #expect(inline.attributes["ruby-annotation-font-size"]?.string == "12")
+    }
+}
diff --git a/Tests/SwiftUIHTMLTests/SwiftSoupParserTests.swift b/Tests/SwiftUIHTMLTests/SwiftSoupParserTests.swift
new file mode 100644
index 0000000..ff87d14
--- /dev/null
+++ b/Tests/SwiftUIHTMLTests/SwiftSoupParserTests.swift
@@ -0,0 +1,263 @@
+//  Copyright © 2026 PRND. All rights reserved.
+
+import Testing
+import SwiftSoup
+@testable import SwiftUIHTML
+
+struct SwiftSoupParserTests {
+    @Test
+    func swiftSoupParserMapsNodesAttributesAndLineBreaks() {
+        let html = """
+        <body>
+            <p data-x=\"1\">Hello<br>World</p>
+            <ruby ruby-position=\"after\">漢字<rt>かんじ</rt></ruby>
+        </body>
+        """
+        let parser = HTMLSwiftSoupParser()
+        let root = parser.parse(html: html)
+
+        #expect(root.tag == "body")
+
+        let paragraph = firstNode(tag: "p", in: root)
+        #expect(paragraph?.attributes["data-x"]?.string == "1")
+        let paragraphText = paragraph?.children.compactMap(textValue(from:)) ?? []
+        #expect(paragraphText.contains("Hello"))
+        #expect(paragraphText.contains("\n"))
+        #expect(paragraphText.contains("World"))
+
+        let rubyNode = firstNode(tag: "ruby", in: root)
+        #expect(rubyNode?.attributes["ruby-position"]?.string == "after")
+        #expect(rubyNode?.children.contains(where: { child in
+            if case let .text(text) = child { return text.contains("漢字") }
+            return false
+        }) == true)
+        let rtNode = rubyNode.flatMap { firstNode(tag: "rt", in: $0) }
+        #expect(rtNode?.children.compactMap(textValue(from:)).contains("かんじ") == true)
+    }
+
+    @Test
+    func swiftSoupParserDropsEmptyTextNodes() {
+        let html = """
+        <body>
+            <div>    </div>
+            <div>Value</div>
+        </body>
+        """
+        let parser = HTMLSwiftSoupParser()
+        let root = parser.parse(html: html)
+
+        let emptyDiv = firstNode(tag: "div", in: root)
+        let emptyText = emptyDiv?.children.compactMap(textValue(from:)) ?? []
+        let trimmedEmptyText = emptyText.joined().trimmingCharacters(in: .whitespacesAndNewlines)
+        #expect(trimmedEmptyText.isEmpty)
+
+        let secondDiv = secondNode(tag: "div", in: root)
+        let text = secondDiv?.children.compactMap(textValue(from:)) ?? []
+        #expect(text == ["Value"])
+    }
+
+    @Test
+    func swiftSoupParserNormalizesWhitespaceAndNestedEmphasis() {
+        let html = """
+        <body>
+            <p>Alpha <em>beta <strong>gamma</strong></em> delta</p>
+            <p>  spaced   text </p>
+        </body>
+        """
+        let parser = HTMLSwiftSoupParser()
+        let root = parser.parse(html: html)
+
+        let firstParagraph = firstNode(tag: "p", in: root)
+        let firstParagraphText = allText(in: firstParagraph)
+        #expect(firstParagraphText.contains("Alpha"))
+        #expect(firstParagraphText.contains("beta"))
+        #expect(firstParagraphText.contains("gamma"))
+        #expect(firstParagraphText.contains("delta"))
+
+        let secondParagraph = secondNode(tag: "p", in: root)
+        let secondText = secondParagraph?.children.compactMap(textValue(from:)).joined() ?? ""
+        let normalized = secondText.replacingOccurrences(of: "\\s+", with: " ", options: .regularExpression).trimmingCharacters(in: .whitespacesAndNewlines)
+        #expect(normalized == "spaced text")
+    }
+
+    @Test
+    func swiftSoupParserHandlesAttributesAndInlineTags() {
+        let html = """
+        <body>
+            <p data-id="42"><span style="color: #f00;">Red</span> <a href="https://example.com">Link</a></p>
+        </body>
+        """
+        let parser = HTMLSwiftSoupParser()
+        let root = parser.parse(html: html)
+
+        let paragraph = firstNode(tag: "p", in: root)
+        #expect(paragraph?.attributes["data-id"]?.string == "42")
+
+        let spanNode = firstNode(tag: "span", in: root)
+        #expect(spanNode?.attributes["style"]?.string.contains("color") == true)
+
+        let linkNode = firstNode(tag: "a", in: root)
+        #expect(linkNode?.attributes["href"]?.string == "https://example.com")
+    }
+
+}
+
+private struct HTMLSwiftSoupParser: HTMLParserable {
+    func parse(html: String) -> HTMLNode {
+        do {
+            let document = try SwiftSoup.parse(html)
+            if let body = document.body() {
+                return try buildHTMLNode(from: body)
+            } else if let wrapper = try document.select("*").first() {
+                return try buildHTMLNode(from: wrapper)
+            } else {
+                return HTMLNode(tag: "div", attributes: [:], children: [])
+            }
+        } catch {
+            return HTMLNode(tag: "div", attributes: [:], children: [.text("Parse error: \(error.localizedDescription)")])
+        }
+    }
+
+    private func buildHTMLNode(from root: Element) throws -> HTMLNode {
+        let visitor = SwiftSoupHTMLNodeVisitor()
+        try NodeTraversor(visitor).traverse(root)
+        return visitor.root ?? HTMLNode(tag: "div", attributes: [:], children: [])
+    }
+}
+
+private final class SwiftSoupHTMLNodeVisitor: NodeVisitor {
+    private struct Builder {
+        let tag: String
+        let attributes: [String: String]
+        var children: [HTMLChild]
+    }
+
+    private var stack: [Builder] = []
+    private(set) var root: HTMLNode?
+
+    func head(_ node: Node, _ depth: Int) throws {
+        if let textNode = node as? TextNode {
+            let whole = textNode.getWholeText()
+            if whole.isEmpty {
+                return
+            }
+            let text: String
+            if hasASCIIWhitespace(whole) {
+                text = TextNode.normaliseWhitespace(whole)
+            } else {
+                text = whole
+            }
+            if !text.isEmpty, !stack.isEmpty {
+                stack[stack.count - 1].children.append(.text(text))
+            }
+            return
+        }
+        guard let element = node as? Element else { return }
+        let rawTag = element.tagName()
+        if isBRTag(rawTag) {
+            if !stack.isEmpty {
+                stack[stack.count - 1].children.append(.newLine)
+            }
+            return
+        }
+
+        var attributes: [String: String] = [:]
+        if let rawAttributes = element.getAttributes() {
+            attributes.reserveCapacity(rawAttributes.size())
+            for attribute in rawAttributes {
+                attributes[attribute.getKey()] = attribute.getValue()
+            }
+        }
+
+        var children: [HTMLChild] = []
+        children.reserveCapacity(element.childNodeSize())
+        stack.append(Builder(tag: rawTag, attributes: attributes, children: children))
+    }
+
+    func tail(_ node: Node, _ depth: Int) throws {
+        guard let element = node as? Element else { return }
+        let rawTag = element.tagName()
+        if isBRTag(rawTag) {
+            return
+        }
+        guard let finished = stack.popLast() else { return }
+        let built = HTMLNode(tag: finished.tag, attributes: finished.attributes, children: finished.children)
+        if stack.isEmpty {
+            root = built
+        } else {
+            stack[stack.count - 1].children.append(.node(built))
+        }
+    }
+}
+
+@inline(__always)
+private func isBRTag(_ raw: String) -> Bool {
+    var iterator = raw.utf8.makeIterator()
+    guard let first = iterator.next(), let second = iterator.next() else { return false }
+    if iterator.next() != nil { return false }
+    let isB = first == 0x62 || first == 0x42
+    let isR = second == 0x72 || second == 0x52
+    return isB && isR
+}
+
+@inline(__always)
+private func hasASCIIWhitespace(_ value: String) -> Bool {
+    for byte in value.utf8 {
+        if ASCIIWhitespace.isWhitespace(byte) {
+            return true
+        }
+    }
+    return false
+}
+
+private func firstNode(tag: String, in node: HTMLNode) -> HTMLNode? {
+    for child in node.children {
+        if case let .node(childNode) = child {
+            if childNode.tag == tag {
+                return childNode
+            }
+            if let found = firstNode(tag: tag, in: childNode) {
+                return found
+            }
+        }
+    }
+    return nil
+}
+
+private func secondNode(tag: String, in node: HTMLNode) -> HTMLNode? {
+    var matches: [HTMLNode] = []
+    collectNodes(tag: tag, in: node, results: &matches)
+    return matches.count > 1 ? matches[1] : nil
+}
+
+private func collectNodes(tag: String, in node: HTMLNode, results: inout [HTMLNode]) {
+    for child in node.children {
+        if case let .node(childNode) = child {
+            if childNode.tag == tag {
+                results.append(childNode)
+            }
+            collectNodes(tag: tag, in: childNode, results: &results)
+        }
+    }
+}
+
+private func textValue(from child: HTMLChild) -> String? {
+    if case let .text(text) = child {
+        return text
+    }
+    return nil
+}
+
+private func allText(in node: HTMLNode?) -> String {
+    guard let node else { return "" }
+    var result = ""
+    for child in node.children {
+        switch child {
+        case let .text(text):
+            result.append(text)
+        case let .node(inner):
+            result.append(allText(in: inner))
+        }
+    }
+    return result
+}
diff --git a/Tests/SwiftUIHTMLTests/UTF8ParsingTests.swift b/Tests/SwiftUIHTMLTests/UTF8ParsingTests.swift
new file mode 100644
index 0000000..57e9b6a
--- /dev/null
+++ b/Tests/SwiftUIHTMLTests/UTF8ParsingTests.swift
@@ -0,0 +1,57 @@
+//  Copyright © 2026 PRND. All rights reserved.
+
+import Testing
+import SwiftUI
+@testable import SwiftUIHTML
+
+struct UTF8ParsingTests {
+    @Test
+    func asciiWhitespaceTrim() throws {
+        let input = " \t\nHello\r "
+        let trimmed = ASCIIWhitespace.trim(input)
+        #expect(trimmed == "Hello")
+    }
+
+    @Test
+    func asciiWhitespaceTrimPreservesNBSP() throws {
+        let nbsp = "\u{00A0}"
+        let input = "\(nbsp)Hello\(nbsp)"
+        let trimmed = ASCIIWhitespace.trim(input)
+        #expect(trimmed == input)
+    }
+
+    @Test
+    func cssStyleParsingUsesSlices() throws {
+        let style = "  color :  #fff ;  "
+        let parsed = CSSStyle(style: style)
+        #expect(parsed?["color"]?.string == "#fff")
+    }
+
+    @Test
+    func cssFontSizeParsingAsciiTrim() throws {
+        let size = CSSFontUtility.parseSize(fromFontSize: " 12px ", baseSize: 10)
+        #expect(size == 12)
+    }
+
+    @Test
+    func hexColorParsingAsciiTrim() throws {
+        let color = Color(cssString: "  #abc ")
+        #expect(color != nil)
+    }
+
+    @Test
+    func htmlChildTrimmingTextAscii() throws {
+        let child = HTMLChild.trimmingText("  hello \n")
+        #expect(child == .text("hello"))
+    }
+
+    @Test
+    func attributeValueNumericParsing() throws {
+        let intValue = AttributeValue(rawValue: "12px").int
+        let floatValue = AttributeValue(rawValue: "12.5px").float
+        let negative = AttributeValue(rawValue: "-3").int
+        #expect(intValue == 12)
+        #expect(floatValue == 12.5)
+        #expect(negative == -3)
+    }
+}
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 0000000..70ff1e3
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,29 @@
+[tasks.ios-snapshots]
+description = "Run all iOS snapshot tests on the booted simulator, record artifacts, and generate the HTML report."
+run = [
+  "bash scripts/run_ios_snapshots.sh all"
+]
+
+[tasks.ios-snapshots-htmlbasic]
+description = "Run only HTMLBasicTests snapshots on the booted simulator, record artifacts, and regenerate the report."
+run = [
+  "bash scripts/run_ios_snapshots.sh htmlbasic"
+]
+
+[tasks.ios-snapshot-single]
+description = "Run a single snapshot test (set TEST_ONLY to e.g. SwiftUIHTMLExampleTests/HTMLBasicTests/testHTMLImageWithLineHeight) and emit the mini report."
+run = [
+  "bash scripts/run_ios_snapshots.sh single"
+]
+
+[tasks.ios-snapshots-report]
+description = "Generate HTML snapshot report from /tmp/swiftuihtml-ios-artifacts and include the last ios test log."
+run = [
+  "set -euo pipefail; python3 \"scripts/snapshot_report.py\" --artifacts \"/tmp/swiftuihtml-ios-artifacts/HTMLBasicTests\" --baseline \"SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests\" --title \"SwiftUIHTML iOS Snapshot Report\" --out-prefix \"/tmp/swiftuihtml-ios-snapshot-report\" --test-log \"/tmp/swiftuihtml-ios-xcodebuild.log\""
+]
+
+[tasks.macos-snapshots-report]
+description = "Generate HTML snapshot report from the latest /tmp/swiftuihtml-macos-artifacts*"
+run = [
+  "set -euo pipefail; artifacts_root=$(ls -1dt /tmp/swiftuihtml-macos-artifacts-* /tmp/swiftuihtml-macos-artifacts 2>/dev/null | head -n 1 || true); if [ -z \"$artifacts_root\" ]; then echo \"No macOS snapshot artifacts found\"; exit 1; fi; python3 \"scripts/snapshot_report.py\" --artifacts \"$artifacts_root\" --baseline \"SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests\" --title \"SwiftUIHTML macOS Snapshot Report\" --out-prefix \"/tmp/swiftuihtml-macos-snapshot-report\""
+]
diff --git a/scripts/measure_margin.py b/scripts/measure_margin.py
new file mode 100755
index 0000000..9eb1c3e
--- /dev/null
+++ b/scripts/measure_margin.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+import subprocess
+import sys
+from pathlib import Path
+
+def run_magick(args):
+    candidates = [
+        ("/opt/homebrew/bin/magick", True),
+        ("magick", True),
+        ("/opt/homebrew/bin/convert", False),
+        ("convert", False),
+    ]
+    for tool, uses_magick in candidates:
+        cmd = [tool] + (["convert"] if uses_magick else []) + args
+        try:
+            out = subprocess.check_output(cmd, stderr=subprocess.STDOUT, text=True).strip()
+            return out
+        except FileNotFoundError:
+            continue
+        except subprocess.CalledProcessError:
+            continue
+    return None
+
+def parse_geom(value):
+    if not value or "+" not in value or "x" not in value:
+        return None
+    size, x, y = value.split("+")
+    w, h = size.split("x")
+    return int(w), int(h), int(x), int(y)
+
+if len(sys.argv) < 2:
+    print("usage: measure_margin.py <image.png>")
+    sys.exit(2)
+
+path = Path(sys.argv[1])
+if not path.exists():
+    print(f"missing: {path}")
+    sys.exit(1)
+
+info = run_magick([str(path), "-format", "%w %h", "info:"])
+trim = run_magick([str(path), "-trim", "-format", "%@", "info:"])
+if not info or not trim:
+    print("magick output missing")
+    sys.exit(1)
+
+w, h = map(int, info.split())
+geom = parse_geom(trim)
+if not geom:
+    print("failed to parse trim geometry")
+    sys.exit(1)
+
+trim_w, trim_h, x, y = geom
+right = max(0, w - (x + trim_w))
+bottom = max(0, h - (y + trim_h))
+
+print(f"image={w}x{h}")
+print(f"trim={trim_w}x{trim_h}+{x}+{y}")
+print(f"margins top={y} left={x} bottom={bottom} right={right}")
diff --git a/scripts/ocr_compare.swift b/scripts/ocr_compare.swift
new file mode 100755
index 0000000..64de407
--- /dev/null
+++ b/scripts/ocr_compare.swift
@@ -0,0 +1,215 @@
+#!/usr/bin/env swift
+import Foundation
+import Vision
+import ImageIO
+import CoreGraphics
+
+struct LineBox: Codable {
+    let text: String
+    let x: CGFloat
+    let y: CGFloat
+    let width: CGFloat
+    let height: CGFloat
+}
+
+struct OCRReport: Codable {
+    let imagePath: String
+    let imageWidth: Int
+    let imageHeight: Int
+    let lineCount: Int
+    let topPadding: CGFloat
+    let bottomPadding: CGFloat
+    let leftPadding: CGFloat
+    let rightPadding: CGFloat
+    let lines: [LineBox]
+}
+
+struct LineDelta: Codable {
+    let index: Int
+    let textNew: String
+    let textBase: String
+    let dx: CGFloat
+    let dy: CGFloat
+    let dWidth: CGFloat
+    let dHeight: CGFloat
+}
+
+struct DeltaReport: Codable {
+    let newPath: String
+    let baselinePath: String
+    let count: Int
+    let deltas: [LineDelta]
+}
+
+func usage() -> Never {
+    fputs("Usage: ocr_compare.swift <baseline.png> <new.png> [outputDir]\n", stderr)
+    exit(2)
+}
+
+func loadCGImage(path: String) -> CGImage {
+    let url = URL(fileURLWithPath: path)
+    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+          let image = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
+        fatalError("Failed to load image at \(path)")
+    }
+    return image
+}
+
+func recognizeText(image: CGImage) -> [(CGRect, String)] {
+    let request = VNRecognizeTextRequest()
+    request.recognitionLevel = .accurate
+    request.usesLanguageCorrection = false
+    request.minimumTextHeight = 0.01
+    let handler = VNImageRequestHandler(cgImage: image, options: [:])
+    do {
+        try handler.perform([request])
+    } catch {
+        fatalError("Vision request failed: \(error)")
+    }
+    let observations = request.results ?? []
+    let width = CGFloat(image.width)
+    let height = CGFloat(image.height)
+    return observations.compactMap { obs in
+        guard let candidate = obs.topCandidates(1).first else { return nil }
+        let rect = VNImageRectForNormalizedRect(obs.boundingBox, Int(width), Int(height))
+        // Convert to top-left coordinate space for easier comparison.
+        let topLeftY = height - rect.maxY
+        let converted = CGRect(x: rect.minX, y: topLeftY, width: rect.width, height: rect.height)
+        return (converted, candidate.string)
+    }
+}
+
+func clusterLines(rects: [CGRect], texts: [String]) -> [(CGRect, String)] {
+    guard !rects.isEmpty else { return [] }
+    let pairs = zip(rects, texts)
+        .map { (rect: $0.0, text: $0.1) }
+        .sorted { $0.rect.minY < $1.rect.minY }
+    var lines: [(CGRect, String)] = []
+    var currentRects: [CGRect] = []
+    var currentTexts: [String] = []
+    var currentMidY: CGFloat?
+    for pair in pairs {
+        let midY = pair.rect.midY
+        if let current = currentMidY {
+            let threshold = max(4, pair.rect.height * 0.6)
+            if abs(midY - current) <= threshold {
+                currentRects.append(pair.rect)
+                currentTexts.append(pair.text)
+            } else {
+                lines.append(makeLineCluster(rects: currentRects, texts: currentTexts))
+                currentRects = [pair.rect]
+                currentTexts = [pair.text]
+                currentMidY = midY
+            }
+        } else {
+            currentRects = [pair.rect]
+            currentTexts = [pair.text]
+            currentMidY = midY
+        }
+    }
+    if !currentRects.isEmpty {
+        lines.append(makeLineCluster(rects: currentRects, texts: currentTexts))
+    }
+    return lines
+}
+
+func makeLineCluster(rects: [CGRect], texts: [String]) -> (CGRect, String) {
+    var union = rects.first ?? .zero
+    for rect in rects.dropFirst() {
+        union = union.union(rect)
+    }
+    let joined = texts.filter { !$0.isEmpty }.joined(separator: " | ")
+    return (union, joined)
+}
+
+func buildReport(imagePath: String) -> OCRReport {
+    let image = loadCGImage(path: imagePath)
+    let results = recognizeText(image: image)
+    let rects = results.map { $0.0 }
+    let texts = results.map { $0.1 }
+    let lines = clusterLines(rects: rects, texts: texts)
+    let union = rects.reduce(CGRect.null) { $0.union($1) }
+    let width = CGFloat(image.width)
+    let height = CGFloat(image.height)
+    let leftPadding = union.isNull ? 0 : union.minX
+    let rightPadding = union.isNull ? 0 : max(0, width - union.maxX)
+    let topPadding = union.isNull ? 0 : union.minY
+    let bottomPadding = union.isNull ? 0 : max(0, height - union.maxY)
+    let lineBoxes = lines.map { line in
+        LineBox(
+            text: line.1,
+            x: line.0.minX,
+            y: line.0.minY,
+            width: line.0.width,
+            height: line.0.height
+        )
+    }
+    return OCRReport(
+        imagePath: imagePath,
+        imageWidth: image.width,
+        imageHeight: image.height,
+        lineCount: lineBoxes.count,
+        topPadding: topPadding,
+        bottomPadding: bottomPadding,
+        leftPadding: leftPadding,
+        rightPadding: rightPadding,
+        lines: lineBoxes
+    )
+}
+
+func writeJSON<T: Encodable>(_ value: T, to url: URL) throws {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    let data = try encoder.encode(value)
+    try data.write(to: url)
+}
+
+let args = CommandLine.arguments
+if args.count < 3 { usage() }
+let baselinePath = args[1]
+let newPath = args[2]
+let outputDir = args.count > 3 ? args[3] : "/tmp/swiftuihtml-ocr"
+
+let outputURL = URL(fileURLWithPath: outputDir, isDirectory: true)
+try? FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
+
+let baseReport = buildReport(imagePath: baselinePath)
+let newReport = buildReport(imagePath: newPath)
+
+let baseURL = outputURL.appendingPathComponent("baseline.lines.json")
+let newURL = outputURL.appendingPathComponent("new.lines.json")
+do {
+    try writeJSON(baseReport, to: baseURL)
+    try writeJSON(newReport, to: newURL)
+} catch {
+    fatalError("Failed to write reports: \(error)")
+}
+
+let count = min(baseReport.lines.count, newReport.lines.count)
+let deltas = (0..<count).map { index -> LineDelta in
+    let base = baseReport.lines[index]
+    let new = newReport.lines[index]
+    return LineDelta(
+        index: index,
+        textNew: new.text,
+        textBase: base.text,
+        dx: new.x - base.x,
+        dy: new.y - base.y,
+        dWidth: new.width - base.width,
+        dHeight: new.height - base.height
+    )
+}
+let deltaReport = DeltaReport(
+    newPath: newPath,
+    baselinePath: baselinePath,
+    count: count,
+    deltas: deltas
+)
+let deltaURL = outputURL.appendingPathComponent("line-deltas.json")
+do {
+    try writeJSON(deltaReport, to: deltaURL)
+} catch {
+    fatalError("Failed to write deltas: \(error)")
+}
+
+print("Wrote OCR reports to \(outputURL.path)")
diff --git a/scripts/pull_ios_artifacts.sh b/scripts/pull_ios_artifacts.sh
new file mode 100755
index 0000000..01b551f
--- /dev/null
+++ b/scripts/pull_ios_artifacts.sh
@@ -0,0 +1,30 @@
+#!/bin/sh
+set -euo pipefail
+root="${1:-/tmp/swiftuihtml-ios-artifacts}"
+# Find the newest artifacts directory under any simulator app container.
+core_sim="$HOME/Library/Developer/CoreSimulator/Devices"
+xctest_devices="$HOME/Library/Developer/XCTestDevices"
+latest_path=""
+latest_mtime=0
+while IFS= read -r -d '' dir; do
+  mtime=$(stat -f %m "$dir" 2>/dev/null || echo 0)
+  if [ "$mtime" -gt "$latest_mtime" ]; then
+    latest_mtime="$mtime"
+    latest_path="$dir"
+  fi
+done <<EOF
+$(find "$core_sim" "$xctest_devices" \
+  \( -path "*/data/Containers/Data/Application/*/Documents/swiftuihtml-ios-artifacts" -o \
+     -path "*/data/Containers/Data/Application/*/tmp/swiftuihtml-ios-artifacts" \) \
+  -type d -print0 2>/dev/null)
+EOF
+
+if [ -z "$latest_path" ]; then
+  echo "No simulator artifacts found."
+  exit 1
+fi
+
+mkdir -p "$root"
+rsync -a "$latest_path/" "$root/"
+echo "Copied iOS artifacts from: $latest_path"
+echo "Into: $root"
diff --git a/scripts/render_html.swift b/scripts/render_html.swift
new file mode 100644
index 0000000..0100d6b
--- /dev/null
+++ b/scripts/render_html.swift
@@ -0,0 +1,70 @@
+import Foundation
+import WebKit
+#if canImport(AppKit)
+import AppKit
+#endif
+
+final class Renderer: NSObject, WKNavigationDelegate {
+    private let htmlPath: String
+    private let outputPath: String
+    private let width: CGFloat
+    private let height: CGFloat
+    private let webView: WKWebView
+    private var finished = false
+
+    init(htmlPath: String, outputPath: String, width: CGFloat, height: CGFloat) {
+        self.htmlPath = htmlPath
+        self.outputPath = outputPath
+        self.width = width
+        self.height = height
+        let config = WKWebViewConfiguration()
+        self.webView = WKWebView(frame: CGRect(x: 0, y: 0, width: width, height: height), configuration: config)
+        super.init()
+        webView.navigationDelegate = self
+    }
+
+    func start() {
+        let url = URL(fileURLWithPath: htmlPath)
+        webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
+    }
+
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        guard !finished else { return }
+        finished = true
+        let config = WKSnapshotConfiguration()
+        config.rect = CGRect(x: 0, y: 0, width: width, height: height)
+        webView.takeSnapshot(with: config) { image, _ in
+            guard let image else {
+                exit(3)
+            }
+#if canImport(AppKit)
+            guard let tiff = image.tiffRepresentation,
+                  let bitmap = NSBitmapImageRep(data: tiff),
+                  let png = bitmap.representation(using: .png, properties: [:]) else {
+                exit(4)
+            }
+            do {
+                try png.write(to: URL(fileURLWithPath: self.outputPath))
+            } catch {
+                exit(5)
+            }
+#endif
+            exit(0)
+        }
+    }
+}
+
+let args = CommandLine.arguments
+guard args.count >= 3 else {
+    fputs("usage: render_html.swift <html-file> <output-png> [width] [height]\n", stderr)
+    exit(1)
+}
+
+let htmlPath = args[1]
+let outputPath = args[2]
+let width = CGFloat(Double(args.count > 3 ? args[3] : "600") ?? 600)
+let height = CGFloat(Double(args.count > 4 ? args[4] : "220") ?? 220)
+
+let renderer = Renderer(htmlPath: htmlPath, outputPath: outputPath, width: width, height: height)
+renderer.start()
+RunLoop.main.run()
diff --git a/scripts/run_benchmarks.sh b/scripts/run_benchmarks.sh
new file mode 100644
index 0000000..619ce74
--- /dev/null
+++ b/scripts/run_benchmarks.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+workdir="$(cd "$(dirname "$0")/.." && pwd)"
+tmpdir="$(mktemp -d /tmp/swiftuihtml-bench.XXXXXX)"
+log="$tmpdir/bench.log"
+
+cleanup() {
+  rm -rf "$tmpdir"
+}
+trap cleanup EXIT
+
+cd "$workdir"
+
+swift test --filter PerformanceTests >"$log" 2>&1
+
+echo "Benchmark summary:"
+rg -n "baseline|optimized|enabled|median" "$log" | sed -E 's/^[0-9]+://'
diff --git a/scripts/run_ios_snapshots.sh b/scripts/run_ios_snapshots.sh
new file mode 100755
index 0000000..689b57b
--- /dev/null
+++ b/scripts/run_ios_snapshots.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+usage() {
+  cat <<'USAGE'
+Usage: $0 <mode>
+Modes:
+  all          - run all snapshot tests
+  htmlbasic    - run only HTMLBasicTests snapshots
+  single       - run exactly one snapshot test (requires TEST_ONLY or second arg)
+USAGE
+  exit 1
+}
+if [ $# -lt 1 ]; then usage; fi
+mode=$1
+target_test=""
+if [ "$mode" = "single" ]; then
+  if [ $# -ge 2 ]; then
+    target_test=$2
+  elif [ -n "${TEST_ONLY:-}" ]; then
+    target_test=${TEST_ONLY}
+  else
+    echo "single mode requires TEST_ONLY env or argument" >&2
+    exit 1
+  fi
+fi
+find_simulator_uudid() {
+  python3 - <<'PY'
+import json, subprocess, sys
+raw = subprocess.check_output(["xcrun", "simctl", "list", "devices", "booted", "-j"], text=True)
+data = json.loads(raw)
+for devices in data.get("devices", {}).values():
+    for device in devices:
+        if device.get("state") == "Booted" and device.get("isAvailable", True):
+            print(device.get("udid"))
+            sys.exit(0)
+sys.exit(1)
+PY
+}
+if ! sim_udid=$(find_simulator_uudid); then
+  echo "No booted simulator found. Set SIM_ID or boot one." >&2
+  exit 1
+fi
+cmd_args=("-project" "SwiftUIHTMLExample.xcodeproj" "-scheme" "SwiftUIHTMLExample" "-testPlan" "SwiftUIHTMLExample" "-destination" "platform=iOS Simulator,id=$sim_udid" "-configuration" "Debug" "-parallel-testing-enabled" "NO" "-maximum-concurrent-test-simulator-destinations" "1" "-maximum-parallel-testing-workers" "1" "-resultBundlePath" "/tmp/swiftuihtml-ios-latest.xcresult")
+case "$mode" in
+  all)
+    report_prefix="/tmp/swiftuihtml-ios-snapshot-report"
+    snapshot_root="/tmp/swiftuihtml-ios-artifacts"
+    log_path="/tmp/swiftuihtml-ios-xcodebuild.log"
+    ;;
+  htmlbasic)
+    report_prefix="/tmp/swiftuihtml-ios-snapshot-report"
+    snapshot_root="/tmp/swiftuihtml-ios-artifacts"
+    log_path="/tmp/swiftuihtml-ios-htmlbasic.log"
+    cmd_args+=("-only-testing:SwiftUIHTMLExampleTests/HTMLBasicTests")
+    ;;
+  single)
+    report_prefix="/tmp/swiftuihtml-ios-single-report"
+    snapshot_root="/tmp/swiftuihtml-ios-artifacts-single"
+    log_path="/tmp/swiftuihtml-ios-single.log"
+    cmd_args+=("-only-testing:${target_test}")
+    ;;
+  *)
+    usage
+    ;;
+esac
+echo "Launching tests on simulator $sim_udid"
+rm -rf "$snapshot_root" "$log_path"
+rm -rf /tmp/swiftuihtml-ios-latest.xcresult
+set +e
+SWIFTUIHTML_SNAPSHOT_RECORD=1 SNAPSHOT_ARTIFACTS="$snapshot_root" xcodebuild test "${cmd_args[@]}" | tee "$log_path" | xcbeautify --renderer terminal
+status=$?
+set -e
+artifact_root=$(grep -a -m1 "artifactsRoot=" "$log_path" | sed -n 's/.*artifactsRoot=//p' | head -n 1)
+if [[ -n "${artifact_root:-}" && -d "$artifact_root" ]]; then
+  mkdir -p "$snapshot_root"
+  rm -rf "${snapshot_root:?}/HTMLBasicTests"
+  cp -a "$artifact_root/HTMLBasicTests" "$snapshot_root/."
+fi
+python3 scripts/snapshot_report.py --artifacts "$snapshot_root/HTMLBasicTests" --baseline "SwiftUIHTMLExampleTests/__Snapshots__/HTMLBasicTests" --title "SwiftUIHTML iOS Snapshot Report" --out-prefix "$report_prefix" --test-log "$log_path"
+exit $status
diff --git a/scripts/snapshot_report.py b/scripts/snapshot_report.py
new file mode 100644
index 0000000..552778c
--- /dev/null
+++ b/scripts/snapshot_report.py
@@ -0,0 +1,682 @@
+#!/usr/bin/env python3
+import argparse
+import html
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+
+BASE_CSS = (
+    "html,body{margin:0;padding:0;font-family:-apple-system,Helvetica,Arial,sans-serif;"
+    "font-size:16px;line-height:1.4;background:#fff;color:#111;}"
+    ".snapshot-root{padding:12px;}"
+)
+
+
+def run_magick(args):
+    candidates = [
+        ("/opt/homebrew/bin/magick", True),
+        ("/opt/homebrew/bin/convert", False),
+        ("magick", True),
+        ("convert", False),
+    ]
+    for tool, uses_magick in candidates:
+        cmd = [tool] + (["convert"] if uses_magick else []) + args
+        try:
+            output = subprocess.check_output(cmd, stderr=subprocess.STDOUT, text=True).strip()
+            if output:
+                return output
+        except FileNotFoundError:
+            continue
+        except subprocess.CalledProcessError:
+            continue
+    return None
+
+
+def run_compare(base_path, new_path, output_path):
+    candidates = [
+        ("/opt/homebrew/bin/magick", True),
+        ("/opt/homebrew/bin/compare", False),
+        ("magick", True),
+        ("compare", False),
+    ]
+    for tool, uses_magick in candidates:
+        cmd = [tool]
+        if uses_magick:
+            cmd.append("compare")
+        cmd += ["-metric", "AE", str(base_path), str(new_path), str(output_path)]
+        try:
+            result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+            metric = (result.stderr or result.stdout).strip()
+            return metric
+        except FileNotFoundError:
+            continue
+    return None
+
+
+def run_vision_ocr(image_path):
+    script = Path(__file__).parent / "vision_ocr.swift"
+    if not script.exists():
+        return None
+    tool = ensure_swift_tool(script, "vision_ocr", ["Vision", "AppKit"])
+    if not tool:
+        return None
+    try:
+        result = subprocess.run(
+            [str(tool), str(image_path)],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    output = result.stdout.strip()
+    if not output and result.stderr.strip():
+        output = f"error: {result.stderr.strip()}"
+    if not output:
+        return None
+    return output
+
+
+def parse_trim_geometry(value):
+    if not value:
+        return None
+    # format: WxH+X+Y
+    if "+" not in value or "x" not in value:
+        return None
+    try:
+        size, x, y = value.split("+")
+        w, h = size.split("x")
+        return {
+            "trim_width": int(w),
+            "trim_height": int(h),
+            "trim_x": int(x),
+            "trim_y": int(y),
+        }
+    except ValueError:
+        return None
+
+
+def parse_test_log(path_value):
+    if not path_value:
+        return {}
+    path = Path(path_value)
+    if not path.exists():
+        return {}
+    try:
+        text = path.read_text()
+    except OSError:
+        return {}
+    statuses = {}
+    matcher = re.compile(r"Test case '([^']+)' (passed|failed)")
+    for match in matcher.finditer(text):
+        raw_test = match.group(1)
+        status_raw = match.group(2)
+        simple = raw_test.replace("/", ".")
+        if "." in simple:
+            simple = simple.split(".")[-1]
+        simple = simple.split("(", 1)[0]
+        statuses[simple] = status_raw
+    case_matcher = re.compile(r"Test Case '-\[[^ ]+ ([^]]+)\]' (passed|failed)")
+    for match in case_matcher.finditer(text):
+        method_name = match.group(1)
+        status_raw = match.group(2)
+        statuses[method_name] = status_raw
+        if method_name.startswith("test") and len(method_name) > 4:
+            trimmed = method_name[4:]
+            if trimmed:
+                trimmed = trimmed[0].lower() + trimmed[1:]
+                statuses[trimmed] = status_raw
+                base_name = trimmed
+            else:
+                base_name = method_name
+        else:
+            base_name = method_name
+        base_key = base_name.split("_", 1)[0]
+        statuses[base_key] = status_raw
+    return statuses
+
+
+def load_ocr_metrics(ocr_dir, base_name, label):
+    if not ocr_dir:
+        return None
+    path = ocr_dir / f"{base_name}.{label}.lines.json"
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    lines = data.get("lines") or []
+    heights = []
+    char_widths = []
+    for line in lines:
+        rect = line.get("rect") or {}
+        text = line.get("text") or ""
+        h = rect.get("h")
+        w = rect.get("w")
+        if isinstance(h, (int, float)):
+            heights.append(float(h))
+        if isinstance(w, (int, float)) and text:
+            char_widths.append(float(w) / max(1, len(text)))
+    def median(values):
+        if not values:
+            return None
+        values = sorted(values)
+        mid = len(values) // 2
+        if len(values) % 2:
+            return values[mid]
+        return (values[mid - 1] + values[mid]) / 2
+    return {
+        "ocr_top": data.get("topPadding"),
+        "ocr_bottom": data.get("bottomPadding"),
+        "ocr_left": data.get("leftPadding"),
+        "ocr_right": data.get("rightPadding"),
+        "ocr_lines": len(lines),
+        "ocr_line_height_median": median(heights),
+        "ocr_char_width_median": median(char_widths),
+    }
+
+
+def render_html_preview(html_payload, out_path, width=600, height=220):
+    script = Path(__file__).parent / "render_html.swift"
+    if not script.exists():
+        return False
+    tool = ensure_swift_tool(script, "render_html", ["WebKit", "AppKit"])
+    if not tool:
+        return False
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    html_path = out_path.with_suffix(".html")
+    payload = (
+        "<!doctype html><html><head><meta charset='utf-8'>"
+        f"<style>{BASE_CSS}</style></head><body>"
+        f"<div class='snapshot-root'>{html_payload}</div></body></html>"
+    )
+    html_path.write_text(payload, encoding="utf-8")
+    try:
+        result = subprocess.run(
+            [str(tool), str(html_path), str(out_path), str(width), str(height)],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return False
+    return result.returncode == 0 and out_path.exists()
+
+
+def ensure_swift_tool(script_path, name, frameworks):
+    tools_dir = Path("/tmp/swiftuihtml-report-tools")
+    tools_dir.mkdir(parents=True, exist_ok=True)
+    binary = tools_dir / name
+    script_mtime = script_path.stat().st_mtime
+    if binary.exists() and binary.stat().st_mtime >= script_mtime:
+        return binary
+    cmd = ["swiftc", str(script_path), "-o", str(binary)]
+    for framework in frameworks:
+        cmd += ["-framework", framework]
+    try:
+        result = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    return binary
+
+
+def image_metrics(path):
+    if not path.exists():
+        return {}
+    out = run_magick([str(path), "-format", "%w %h %k", "info:"])
+    if not out:
+        return {}
+    parts = out.split()
+    if len(parts) < 3:
+        return {}
+    try:
+        width = int(parts[0])
+        height = int(parts[1])
+        unique = int(float(parts[2]))
+    except ValueError:
+        return {}
+    sat_out = run_magick([
+        str(path),
+        "-colorspace",
+        "HSL",
+        "-channel",
+        "G",
+        "-separate",
+        "-format",
+        "%[fx:mean]",
+        "info:",
+    ])
+    saturation = None
+    if sat_out:
+        try:
+            saturation = float(sat_out.split()[0])
+        except ValueError:
+            saturation = None
+    lum_out = run_magick([
+        str(path),
+        "-colorspace",
+        "Gray",
+        "-format",
+        "%[fx:mean]",
+        "info:",
+    ])
+    luminance = None
+    if lum_out:
+        try:
+            luminance = float(lum_out.split()[0])
+        except ValueError:
+            luminance = None
+    dark_out = run_magick([
+        str(path),
+        "-colorspace",
+        "Gray",
+        "-threshold",
+        "95%",
+        "-format",
+        "%[fx:mean]",
+        "info:",
+    ])
+    dark_ratio = None
+    if dark_out:
+        try:
+            dark_ratio = 1.0 - float(dark_out.split()[0])
+        except ValueError:
+            dark_ratio = None
+    nonwhite_out = run_magick([
+        str(path),
+        "-colorspace",
+        "Gray",
+        "-threshold",
+        "99%",
+        "-format",
+        "%[fx:mean]",
+        "info:",
+    ])
+    nonwhite_ratio = None
+    if nonwhite_out:
+        try:
+            nonwhite_ratio = 1.0 - float(nonwhite_out.split()[0])
+        except ValueError:
+            nonwhite_ratio = None
+    edge_out = run_magick([
+        str(path),
+        "-colorspace",
+        "Gray",
+        "-edge",
+        "1",
+        "-format",
+        "%[fx:mean]",
+        "info:",
+    ])
+    edge_mean = None
+    if edge_out:
+        try:
+            edge_mean = float(edge_out.split()[0])
+        except ValueError:
+            edge_mean = None
+    trim_out = run_magick([str(path), "-trim", "-format", "%@", "info:"])
+    trim = parse_trim_geometry(trim_out)
+    metrics = {
+        "width": width,
+        "height": height,
+        "unique": unique,
+        "saturation": saturation,
+        "luminance": luminance,
+        "dark_ratio": dark_ratio,
+        "nonwhite_ratio": nonwhite_ratio,
+        "edge_mean": edge_mean,
+    }
+    if trim:
+        metrics.update(trim)
+        metrics["trim_left"] = trim["trim_x"]
+        metrics["trim_top"] = trim["trim_y"]
+        metrics["trim_right"] = max(0, width - (trim["trim_x"] + trim["trim_width"]))
+        metrics["trim_bottom"] = max(0, height - (trim["trim_y"] + trim["trim_height"]))
+    return metrics
+
+
+def heuristic_flags(base, new):
+    flags = []
+    if not base or not new:
+        return flags
+    base_unique = base.get("unique")
+    new_unique = new.get("unique")
+    base_sat = base.get("saturation")
+    new_sat = new.get("saturation")
+    base_lum = base.get("luminance")
+    new_lum = new.get("luminance")
+    base_dark = base.get("dark_ratio")
+    new_dark = new.get("dark_ratio")
+    base_edge = base.get("edge_mean")
+    new_edge = new.get("edge_mean")
+    base_nonwhite = base.get("nonwhite_ratio")
+    new_nonwhite = new.get("nonwhite_ratio")
+    if base_unique and new_unique and base_unique > 2000 and new_unique < base_unique * 0.5:
+        flags.append("low color variety vs baseline")
+    if base_sat is not None and new_sat is not None and base_sat > 0.02 and new_sat < base_sat * 0.6:
+        flags.append("low saturation vs baseline")
+    if base_lum is not None and new_lum is not None and base_lum < 0.98 and new_lum > base_lum + 0.02:
+        flags.append("brighter vs baseline")
+    if base_nonwhite is not None and new_nonwhite is not None and base_nonwhite > 0.02 and new_nonwhite < base_nonwhite * 0.6:
+        flags.append("low nonwhite coverage vs baseline")
+    if base_dark is not None and new_dark is not None and base_dark > 0.02 and new_dark < base_dark * 0.6:
+        flags.append("low ink coverage vs baseline")
+    if base_edge is not None and new_edge is not None and base_edge > 0.01 and new_edge < base_edge * 0.6:
+        flags.append("low edge detail vs baseline")
+    if (
+        base_nonwhite is not None and new_nonwhite is not None
+        and base_edge is not None and new_edge is not None
+        and base_nonwhite > 0.05
+        and new_nonwhite < base_nonwhite * 0.5
+        and new_edge < base_edge * 0.5
+    ):
+        flags.append("possible missing images (low nonwhite + low edge)")
+    if (
+        base_sat is not None and new_sat is not None
+        and base_edge is not None and new_edge is not None
+        and base_sat > 0.03
+        and new_sat < base_sat * 0.5
+        and new_edge < base_edge * 0.7
+    ):
+        flags.append("possible missing images (low saturation + low edge)")
+    if (
+        base_unique is not None and new_unique is not None
+        and base_edge is not None and new_edge is not None
+        and base_unique > 1500
+        and new_unique < base_unique * 0.5
+        and new_edge < base_edge * 0.6
+    ):
+        flags.append("possible missing images (low color variety + low edge)")
+    return flags
+
+
+def format_metrics(metrics):
+    if not metrics:
+        return "metrics unavailable"
+    width = metrics.get("width")
+    height = metrics.get("height")
+    unique = metrics.get("unique")
+    sat = metrics.get("saturation")
+    lum = metrics.get("luminance")
+    dark = metrics.get("dark_ratio")
+    nonwhite = metrics.get("nonwhite_ratio")
+    edge = metrics.get("edge_mean")
+    sat_str = "n/a" if sat is None else f"{sat:.4f}"
+    lum_str = "n/a" if lum is None else f"{lum:.4f}"
+    dark_str = "n/a" if dark is None else f"{dark:.4f}"
+    nonwhite_str = "n/a" if nonwhite is None else f"{nonwhite:.4f}"
+    edge_str = "n/a" if edge is None else f"{edge:.4f}"
+    trim_left = metrics.get("trim_left")
+    trim_top = metrics.get("trim_top")
+    trim_right = metrics.get("trim_right")
+    trim_bottom = metrics.get("trim_bottom")
+    trim_str = ""
+    if None not in (trim_left, trim_top, trim_right, trim_bottom):
+        trim_str = f", trim(T/L/B/R)={trim_top}/{trim_left}/{trim_bottom}/{trim_right}"
+    ocr_top = metrics.get("ocr_top")
+    ocr_bottom = metrics.get("ocr_bottom")
+    ocr_left = metrics.get("ocr_left")
+    ocr_right = metrics.get("ocr_right")
+    ocr_lines = metrics.get("ocr_lines")
+    ocr_line_h = metrics.get("ocr_line_height_median")
+    ocr_char_w = metrics.get("ocr_char_width_median")
+    ocr_str = ""
+    if None not in (ocr_top, ocr_bottom, ocr_left, ocr_right, ocr_lines):
+        ocr_str = (
+            f", ocr(T/L/B/R)={ocr_top:.1f}/{ocr_left:.1f}/{ocr_bottom:.1f}/{ocr_right:.1f}"
+            f", lines={ocr_lines}"
+        )
+        if ocr_line_h is not None:
+            ocr_str += f", lineH~{ocr_line_h:.1f}"
+        if ocr_char_w is not None:
+            ocr_str += f", charW~{ocr_char_w:.2f}"
+    return (
+        f"{width}x{height} px, unique={unique}, sat={sat_str}, lum={lum_str}, "
+        f"dark={dark_str}, nonwhite={nonwhite_str}, edge={edge_str}"
+        f"{trim_str}{ocr_str}"
+    )
+
+
+def is_snapshot_image(name: str) -> bool:
+    lower = name.lower()
+    if lower.startswith(("reference_", "failure_", "difference_", "diff-")):
+        return False
+    if lower.startswith("_probe_"):
+        return False
+    if ".baseline." in lower or ".ocr." in lower:
+        return False
+    if lower.endswith(".render.png"):
+        return False
+    return True
+
+
+def build_report(artifacts_dir, baseline_dir, title, out_prefix, test_log=None):
+    if not artifacts_dir.exists():
+        raise SystemExit("No artifacts found at " + str(artifacts_dir))
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    report_dir = Path(f"{out_prefix}-{stamp}")
+    report_dir.mkdir(parents=True, exist_ok=True)
+    ocr_dir = artifacts_dir.parent / "ocr"
+    test_statuses = parse_test_log(test_log)
+    test_log_path = Path(test_log) if test_log else None
+    test_log_available = bool(test_log_path and test_log_path.exists())
+
+    rows = []
+    artifacts = list(artifacts_dir.rglob("*.png"))
+    artifacts.sort(key=lambda path: path.stat().st_mtime, reverse=True)
+    for artifact in artifacts:
+        name = artifact.name
+        group = artifact.parent.relative_to(artifacts_dir).as_posix() or "."
+        if not is_snapshot_image(name):
+            continue
+        baseline = baseline_dir / group
+        baseline = baseline / name
+        rows.append((group, name, baseline, artifact))
+
+    css = """
+body { font-family: -apple-system, Helvetica, Arial, sans-serif; margin: 24px; background: #f7f7f7; }
+.header { margin-bottom: 16px; }
+.group { margin-top: 28px; }
+.card { background: #fff; border-radius: 12px; padding: 16px; margin: 16px 0; box-shadow: 0 3px 18px rgba(0,0,0,0.08); }
+.title { font-weight: 600; margin-bottom: 12px; }
+.grid { display: grid; grid-template-columns: repeat(3, minmax(220px, 1fr)); gap: 12px; width: 100%; }
+.details { margin-top: 12px; }
+.details-toggle-row { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; justify-content: space-between; }
+.details-content { display: none; margin-top: 12px; }
+.details-columns { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }
+.details-column { background: #fafafa; border: 1px solid #eee; border-radius: 10px; padding: 12px; display: flex; flex-direction: column; gap: 8px; }
+.label { font-size: 12px; color: #666; margin-bottom: 6px; }
+.toggle { margin-top: 8px; font-size: 12px; padding: 6px 10px; border-radius: 8px; border: 1px solid #ddd; background: #f5f5f5; cursor: pointer; }
+.html-block { margin: 0; background: #fff; color: #111; padding: 10px; border-radius: 8px; border: 1px solid #e5e5e5; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; white-space: pre-wrap; }
+.html-preview { border-radius: 8px; overflow: hidden; border: 1px solid #e5e5e5; }
+.html-preview iframe { width: 100%; height: 220px; border: 0; }
+.html-render img { width: 100%; height: auto; border-radius: 8px; border: 1px solid #e5e5e5; }
+.ocr-block { margin: 8px 0 0; background: #111; color: #eaeaea; padding: 10px; border-radius: 8px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; white-space: pre-wrap; }
+img { width: 100%; height: auto; border: 1px solid #eee; background: #fff; border-radius: 6px; }
+.path { font-size: 11px; color: #999; word-break: break-all; }
+.missing { color: #b00020; font-size: 12px; }
+.metrics { font-size: 11px; color: #666; margin-top: 6px; }
+.flag { color: #b00020; font-size: 12px; font-weight: 600; margin-top: 6px; }
+.test-result { font-size: 12px; font-weight: 600; margin-top: 6px; }
+.test-result.passed { color: #2e7d32; }
+.test-result.failed { color: #d32f2f; }
+.test-result.unknown { color: #6c6c6c; }
+"""
+
+    script = """
+<script>
+function toggleHtml(id) {
+  var detail = document.getElementById(id + "-details");
+  if (!detail) return;
+  var show = (detail.style.display !== "block");
+  detail.style.display = show ? "block" : "none";
+}
+</script>
+"""
+
+    parts = ["<!doctype html>", "<html><head><meta charset='utf-8'>", f"<style>{css}</style>", script, "</head><body>"]
+    parts.append(
+        f"<div class='header'><h2>{html.escape(title)}</h2><div>Artifacts: {html.escape(str(artifacts_dir))}</div></div>"
+    )
+
+    current_group = None
+    for group, name, baseline, artifact in rows:
+        if group != current_group:
+            current_group = group
+            parts.append(f"<div class='group'><h3>{html.escape(group)}</h3></div>")
+        snapshot_id = artifact.stem.split(".", 1)[0]
+        lookup_key = snapshot_id.split("-", 1)[0]
+        test_status = test_statuses.get(lookup_key)
+        parts.append("<div class='card'>")
+        parts.append(f"<div class='title'>{html.escape(name)}</div>")
+        parts.append("<div class='grid'>")
+
+        base_metrics = image_metrics(baseline) if baseline.exists() else {}
+        new_metrics = image_metrics(artifact) if artifact.exists() else {}
+        base_name = artifact.stem
+        base_ocr = load_ocr_metrics(ocr_dir, base_name, "baseline") if ocr_dir.exists() else None
+        new_ocr = load_ocr_metrics(ocr_dir, base_name, "new") if ocr_dir.exists() else None
+        if base_ocr:
+            base_metrics.update(base_ocr)
+        if new_ocr:
+            new_metrics.update(new_ocr)
+        flags = heuristic_flags(base_metrics, new_metrics)
+
+        parts.append("<div>")
+        parts.append("<div class='label'>Baseline</div>")
+        if baseline.exists():
+            parts.append(f"<img src='file://{baseline}' />")
+            parts.append(f"<div class='path'>{html.escape(str(baseline))}</div>")
+            parts.append(f"<div class='metrics'>{html.escape(format_metrics(base_metrics))}</div>")
+        else:
+            parts.append("<div class='missing'>Missing baseline</div>")
+            parts.append(f"<div class='path'>{html.escape(str(baseline))}</div>")
+        parts.append("</div>")
+        parts.append("<div>")
+        parts.append("<div class='label'>New</div>")
+        parts.append(f"<img src='file://{artifact}' />")
+        parts.append(f"<div class='path'>{html.escape(str(artifact))}</div>")
+        parts.append(f"<div class='metrics'>{html.escape(format_metrics(new_metrics))}</div>")
+        if flags:
+            parts.append(f"<div class='flag'>Possible missing images: {html.escape(', '.join(flags))}</div>")
+        if test_status:
+            status_label = test_status.capitalize()
+            status_class = "failed" if test_status == "failed" else "passed"
+            parts.append(f"<div class='test-result {status_class}'>Test result ({html.escape(snapshot_id)}): {html.escape(status_label)}</div>")
+        elif test_log_available:
+            parts.append(f"<div class='test-result unknown'>Test result ({html.escape(snapshot_id)}): log recorded but test missing</div>")
+        parts.append("</div>")
+
+        parts.append("<div>")
+        parts.append("<div class='label'>Diff</div>")
+        diff_name = f"diff-{group.replace('/', '_')}-{name}"
+        diff_path = report_dir / diff_name
+        diff_metric = None
+        if baseline.exists():
+            diff_metric = run_compare(baseline, artifact, diff_path)
+        if diff_path.exists():
+            parts.append(f"<img src='file://{diff_path}' />")
+            if diff_metric:
+                parts.append(f"<div class='metrics'>diff AE={html.escape(diff_metric)}</div>")
+        else:
+            parts.append("<div class='missing'>Diff unavailable</div>")
+        parts.append("</div>")
+
+        parts.append("</div>")  # grid
+
+        html_path = artifact.with_suffix(".html")
+        if not html_path.exists():
+            html_path = baseline.with_suffix(".html")
+        html_id = f"html-{group.replace('/', '_')}-{name}"
+        try:
+            html_payload = html_path.read_text(encoding="utf-8") if html_path.exists() else ""
+        except OSError:
+            html_payload = ""
+        if not html_payload:
+            html_payload = "No HTML input captured for this snapshot."
+        iframe_doc = (
+            "<!doctype html><html><head><meta charset='utf-8'>"
+            f"<style>{BASE_CSS}</style></head><body>"
+            f"<div class='snapshot-root'>{html_payload}</div></body></html>"
+        )
+        parts.append("<div class='details'>")
+        parts.append("<div class='details-toggle-row'>")
+        parts.append(f"<button class='toggle' onclick=\"toggleHtml('{html_id}')\">Toggle HTML input / preview</button>")
+        parts.append("<div class='label'>HTML input + iframe + snapshot</div>")
+        parts.append("</div>")
+        parts.append(f"<div class='details-content' id='{html_id}-details'>")
+        parts.append("<div class='details-columns'>")
+        parts.append("<div class='details-column'>")
+        parts.append("<div class='label'>HTML Input</div>")
+        parts.append(f"<pre id='{html_id}' class='html-block'>{html.escape(html_payload)}</pre>")
+        parts.append("</div>")
+        parts.append("<div class='details-column'>")
+        parts.append("<div class='label'>HTML iframe</div>")
+        parts.append(f"<div id='{html_id}-preview' class='html-preview'><iframe srcdoc=\"{html.escape(iframe_doc)}\"></iframe></div>")
+        parts.append("</div>")
+
+        ocr_payloads = []
+        if baseline.exists():
+            ocr_payloads.append(("baseline", run_vision_ocr(baseline)))
+        if artifact.exists():
+            ocr_payloads.append(("new", run_vision_ocr(artifact)))
+        render_path = report_dir / f"render-{group.replace('/', '_')}-{name}"
+        if render_html_preview(html_payload, render_path):
+            parts.append("<div class='details-column html-render'>")
+            parts.append("<div class='label'>Rendered Snapshot</div>")
+            parts.append(f"<img src='file://{render_path}' />")
+            parts.append("</div>")
+            ocr_payloads.append(("html", run_vision_ocr(render_path)))
+
+        parts.append("</div>")  # details-columns
+
+        ocr_lines = []
+        for label, payload in ocr_payloads:
+            if not payload:
+                ocr_lines.append(f"{label}: (ocr unavailable)")
+            else:
+                ocr_lines.append(f"{label}:\n{payload}")
+        if ocr_lines:
+            parts.append(f"<pre id='{html_id}-ocr' class='ocr-block'>{html.escape('\\n\\n'.join(ocr_lines))}</pre>")
+
+        parts.append("</div>")  # details-content
+        parts.append("</div>")  # details
+        parts.append("</div>")  # card
+
+    parts.append("</body></html>")
+
+    report_path = report_dir / "index.html"
+    report_path.write_text("\n".join(parts), encoding="utf-8")
+    print(report_path)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--artifacts", required=True)
+    parser.add_argument("--baseline", required=True)
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--out-prefix", required=True)
+    parser.add_argument("--test-log", default="", help="Optional xcodebuild log used to summarize test results")
+    args = parser.parse_args()
+
+    artifacts_dir = Path(args.artifacts).resolve()
+    baseline_dir = Path(args.baseline).resolve()
+    build_report(artifacts_dir, baseline_dir, args.title, args.out_prefix, args.test_log)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/vision_ocr.swift b/scripts/vision_ocr.swift
new file mode 100644
index 0000000..e0e0429
--- /dev/null
+++ b/scripts/vision_ocr.swift
@@ -0,0 +1,58 @@
+import Foundation
+import Vision
+#if canImport(AppKit)
+import AppKit
+#endif
+
+struct OCRResult: Codable {
+    let text: String
+    let lines: [String]
+}
+
+func loadCGImage(path: String) -> CGImage? {
+#if canImport(AppKit)
+    guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)),
+          let rep = NSBitmapImageRep(data: data) else {
+        return nil
+    }
+    return rep.cgImage
+#else
+    return nil
+#endif
+}
+
+func recognizeText(from imagePath: String) -> OCRResult? {
+    guard let cgImage = loadCGImage(path: imagePath) else { return nil }
+    let request = VNRecognizeTextRequest()
+    request.recognitionLevel = .accurate
+    request.usesLanguageCorrection = true
+    let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+    do {
+        try handler.perform([request])
+    } catch {
+        return nil
+    }
+    let observations = (request.results as? [VNRecognizedTextObservation]) ?? []
+    let lines = observations.compactMap { observation in
+        observation.topCandidates(1).first?.string
+    }
+    return OCRResult(text: lines.joined(separator: "\n"), lines: lines)
+}
+
+let args = CommandLine.arguments
+if args.count < 2 {
+    fputs("usage: vision_ocr.swift <image-path>\n", stderr)
+    exit(1)
+}
+
+let path = args[1]
+guard let result = recognizeText(from: path) else {
+    print("error: failed to OCR image")
+    exit(0)
+}
+
+if result.text.isEmpty {
+    print("(no text found)")
+} else {
+    print(result.text)
+}