If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Cocoanetics/DTCoreText shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3w ago
• 9 active contributors
• BSD-2-Clause licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 86% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Cocoanetics/DTCoreText repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Cocoanetics/DTCoreText.

What it runs against: a local clone of Cocoanetics/DTCoreText — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Cocoanetics/DTCoreText | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Cocoanetics/DTCoreText. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Cocoanetics/DTCoreText.git
#   cd DTCoreText
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Cocoanetics/DTCoreText and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Cocoanetics/DTCoreText(\\.git)?\\b" \\
  && ok "origin remote is Cocoanetics/DTCoreText" \\
  || miss "origin remote is not Cocoanetics/DTCoreText (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "Sources/DTCoreText/CoreTextLayouter.swift" \\
  && ok "Sources/DTCoreText/CoreTextLayouter.swift" \\
  || miss "missing critical file: Sources/DTCoreText/CoreTextLayouter.swift"
test -f "Sources/DTCoreText/CoreTextLayoutFrame.swift" \\
  && ok "Sources/DTCoreText/CoreTextLayoutFrame.swift" \\
  || miss "missing critical file: Sources/DTCoreText/CoreTextLayoutFrame.swift"
test -f "Sources/DTCoreText/AttributedTextContentView.swift" \\
  && ok "Sources/DTCoreText/AttributedTextContentView.swift" \\
  || miss "missing critical file: Sources/DTCoreText/AttributedTextContentView.swift"
test -f "Sources/DTCoreText/CSSStylesheet.swift" \\
  && ok "Sources/DTCoreText/CSSStylesheet.swift" \\
  || miss "missing critical file: Sources/DTCoreText/CSSStylesheet.swift"
test -f "Sources/DTCoreText/CoreTextParagraphStyle.swift" \\
  && ok "Sources/DTCoreText/CoreTextParagraphStyle.swift" \\
  || miss "missing critical file: Sources/DTCoreText/CoreTextParagraphStyle.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Cocoanetics/DTCoreText"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

DTCoreText converts HTML directly into NSAttributedString (and SwiftUI AttributedString) using Apple's CoreText framework for low-level text layout and rendering on iOS, macOS, and tvOS. It eliminates the need for WebView by parsing HTML/CSS and mapping styles to CoreText attributes, giving you programmatic control over rich text display. Single-package structure: Core parsing/layout logic lives in main source (HTML→CoreText pipeline), UI components (DTAttributedTextView, DTAttributedLabel) layer on top. Demo/ contains runnable example apps for iOS/macOS with test HTML files in Demo/Resources/ (APOD.html, EmojiTest.html, etc.). All tied together in single Xcode project (DTCoreText.xcodeproj) with separate schemes for iOS, Mac, tvOS, and tests.

iOS/macOS/tvOS developers who need to render rich HTML content (emails, articles, formatted text) without embedding a full WebView, and who want fine-grained control over typography, links, and custom styling through CoreText.

Production-ready. The project is actively maintained with recent Swift modernization (Swift package support, SwiftUI AttributedString integration), has comprehensive demo apps and test suites (DTCoreTextTests.xcscheme), and runs CI via GitHub Actions (.github/workflows/swift.yml). It's been battle-tested across iOS 6+ evolution and now targets modern platforms.

Low risk but narrow bus factor: single primary maintainer (Cocoanetics). The project has minimal external dependencies (pure CoreText/Foundation usage is a strength), and breaking changes are rare—version is at 2.0.0 indicating stable API. However, CoreText itself is lower-level than some alternatives, requiring solid understanding of CTLine, CTFrame, and font management.

Active modernization to Swift 5.9+ and SwiftUI compatibility. Recent work includes AttributedString bridging (native SwiftUI support), GitHub Actions CI setup, and Swift Package Manager full integration (.spi.yml present). The .claude/plan.md suggests ongoing refinement of the parsing pipeline and feature expansion.

Clone and open in Xcode: git clone https://github.com/Cocoanetics/DTCoreText.git && cd DTCoreText && open DTCoreText.xcodeproj. Select the 'DTCoreText (iOS)' scheme and build, or run 'DemoApp' scheme to see live HTML rendering. For SPM integration into another project, use: .package(url: "https://github.com/Cocoanetics/DTCoreText.git", from: "2.0.0").

Daily commands: In Xcode: Cmd+B to build for active scheme, Cmd+R to run DemoApp. On command line: xcodebuild -scheme 'DTCoreText (iOS)' -sdk iphonesimulator. Run unit tests via: xcodebuild -scheme 'UnitTest' test.

• Sources/DTCoreText/CoreTextLayouter.swift — Core HTML-to-AttributedString parser that translates HTML into CoreText layout structures; every layout feature depends on this.
• Sources/DTCoreText/CoreTextLayoutFrame.swift — Represents the final layout frame from CoreText; used by all rendering components to draw attributed text.
• Sources/DTCoreText/AttributedTextContentView.swift — Primary UIView for rendering rich text output; entry point for most UI consumers of the library.
• Sources/DTCoreText/CSSStylesheet.swift — CSS parsing and style application layer; controls font sizes, colors, alignment, and all visual attributes from HTML.
• Sources/DTCoreText/CoreTextParagraphStyle.swift — Paragraph-level styling wrapper around CoreText paragraph styles; manages line spacing, alignment, and indentation.
• Sources/DTCoreText/AttributedString+DTCoreText.swift — SwiftUI AttributedString bridge; enables modern Swift concurrency and native SwiftUI integration.
• Sources/DTCoreText/DTColorFunctions.swift — Color parsing from CSS/HTML values; used throughout the codebase for text and background colors.

Add support for a new HTML tag

1. Create a new HTMLElement subclass in Sources/DTCoreText/ (e.g., VideoHTMLElement.swift) following the pattern of AnchorHTMLElement.swift or BreakHTMLElement.swift. (Sources/DTCoreText/AnchorHTMLElement.swift)
2. Implement parseattributes() and register the tag name in the parser's tag dispatcher within CoreTextLayouter.swift. (Sources/DTCoreText/CoreTextLayouter.swift)
3. Apply styling rules for the new tag by adding CSS selectors and font/color attributes in the BuilderState.swift attribute accumulation logic. (Sources/DTCoreText/BuilderState.swift)
4. Update CSSStylesheet.swift to define default styles for the new tag (font size, weight, color, etc.). (Sources/DTCoreText/CSSStylesheet.swift)
5. If the tag requires custom rendering or link handling, implement the DTAttributedTextContentViewDelegate.swift callbacks in your view controller. (Sources/DTCoreText/DTAttributedTextContentViewDelegate.swift)

Customize font resolution and fallbacks

1. Subclass CoreTextFontDescriptor.swift or override its font matching logic to intercept font family name resolution. (Sources/DTCoreText/CoreTextFontDescriptor.swift)
2. Register custom fonts by loading them into CoreTextFontCollection.swift and updating the family registry. (Sources/DTCoreText/CoreTextFontCollection.swift)
3. Define fallback font families in CSSStylesheet.swift default rules to ensure graceful degradation. (Sources/DTCoreText/CSSStylesheet.swift)

Add custom styling or post-processing to rendered text

1. Extend CoreTextLayoutFrame.swift with custom drawing or measurement methods to access CTFrame and CTLine primitives. (Sources/DTCoreText/CoreTextLayoutFrame.swift)
2. Override or subclass AttributedTextContentView.swift and implement custom draw() or layout logic using CoreTextLayoutLine.swift and CoreTextGlyphRun.swift for per-glyph control. (Sources/DTCoreText/AttributedTextContentView.swift)
3. Use CoreTextLayoutFrameDrawingOptions.swift to enable debug overlays or custom rendering flags and pass them to the layout renderer. (Sources/DTCoreText/CoreTextLayoutFrameDrawingOptions.swift)

Handle interactive elements (links, attachments, custom objects)

1. Implement DTAttributedTextContentViewDelegate.swift methods (didClickOnLink, attributedTextView:didClickOnAttachment) in your view controller. (Sources/DTCoreText/DTAttributedTextContentViewDelegate.swift)
2. Parse attachment or link metadata in your HTML element handler (extending AnchorHTMLElement.swift pattern) and store in NSAttributedString attributes. (Sources/DTCoreText/AnchorHTMLElement.swift)
3. Query CoreTextLayoutFrame.swift for link frames and positions using frameForAttachmentAtIndex() or character range lookups to determine tap targets. (Sources/DTCoreText/CoreTextLayoutFrame.swift)

• CoreText (Apple low-level text layout) — Provides precise control over typography, line breaking, and glyph positioning without WebView overhead; critical for rendering complex HTML with custom styles.
• NSAttributedString / AttributedString — Standard Apple abstraction for rich text; bridges HTML parsing and CoreText rendering; native SwiftUI support in modern versions.
• CSS stylesheet parsing — Enables HTML documents to include style rules; allows cascading style resolution matching browser behavior for font, color, and layout.
• Swift Package Manager (SPM) — Modern dependency management; supports iOS, macOS, tvOS simultaneously; cleaner than CocoaPods for multi-platform frameworks.

• CoreText instead of TextKit / TextKit 2

  • Why: CoreText offers lower-level glyph control; compatibility with older iOS versions; direct CTFrame access for custom rendering.
  • Consequence: More manual layout management; less automatic re-layout on size changes; developer must handle text metrics explicitly.

• Custom HTML parser instead of Foundation's NSHTMLParser or libxml2

  • Why: Tighter integration with HTML element model (tags
  • Consequence: undefined

CoreText coordinate system: Origin at bottom-left (flipped from UIView); layout code must account for this. Font fallback: Missing system fonts in Demo resources may cause rendering differences across simulators. Memory management: CTFrame and CTLine objects must be explicitly released; check for leaks when iterating large text blocks. CSS limitations: Only subset of CSS properties supported (no flexbox, grid, or advanced selectors)—unsupported rules silently ignored. Image sizing: Images embedded via HTML require explicit width/height in CSS or HTML attributes; missing dimensions may crash layout.

• CoreText — DTCoreText's foundation—you must understand CTFrame, CTLine, CTRun objects and how they represent hierarchical text layout primitives to debug rendering or extend the library
• NSAttributedString attribute mapping — Converting HTML style properties to CoreText attributes (CTFont, CTColor, CTParagraphStyle) is the core translation layer; understanding attribute keys and their CoreText equivalents is essential for adding CSS feature support
• CSS cascade and specificity — DTCoreText's parser must resolve CSS rules in cascade order to determine final styles; understanding selector specificity and inheritance rules helps predict why certain styles apply or don't
• HTML tokenization and parse trees — The parser builds an in-memory DOM-like structure from raw HTML; understanding how tags nest and attributes attach is crucial for fixing parsing bugs or adding HTML element support
• Vertical text metrics (ascender, descender, x-height) — CoreText uses font metrics (CTFontGetAscent, CTFontGetDescent) for baseline alignment and line spacing; misunderstanding these leads to incorrect paragraph layout or line-height bugs
• Unicode and bidirectional text (BIDI) — DTCoreText must handle RTL languages (Arabic, Hebrew) and emoji correctly; the BIDI algorithm determines text direction at paragraph level, critical for languages in Demo/Resources/Languages.html
• Image embedding in text layout — Inline images in HTML require special CTAttachment handling to position them within the CTFrame; understanding how images anchor to baselines and interact with line height prevents rendering corruption

• wordpress-mobile/WordPress-iOS — Large production app using DTCoreText for rich text rendering in articles and comments without WebView overhead
• apple/swift-markdown — Modern Swift-native markdown parsing alternative; useful reference for how structured text parsing integrates with AttributedString in Swift 5.9+
• nicklockwood/RIPE — Complementary rich-text library providing additional text styling primitives; can be layered on top of DTCoreText output
• pointfreeco/swift-composable-architecture — Reference for modern SwiftUI state management patterns applicable if DTCoreText UI components migrate to SwiftUI fully
• web-platform-tests/wpt — Web Platform Tests repository; useful for validating HTML/CSS parsing compliance against web standards that DTCoreText aims to support

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for HTML parsing edge cases in DTCoreText

The repo has test schemes (DTCoreTextTests.xcscheme, UnitTest.xcscheme) but the test directory is not visible in the file structure. Given the complexity of HTML-to-NSAttributedString conversion (handling Arabic, emoji, custom fonts, line heights, alignment, lists), there are likely untested edge cases. New contributors could add focused unit tests for specific parsing scenarios demonstrated in Demo/Resources (ArabicTest.html, EmojiTest.html, ListTest.html, LineHeight.html) to catch regressions and document expected behavior.

• [ ] Create unit tests in Tests/ directory for DTHTMLParser with test cases from Demo/Resources/ArabicTest.html
• [ ] Add tests for emoji handling using Demo/Resources/EmojiTest.html test cases
• [ ] Add tests for list parsing (ordered/unordered) using Demo/Resources/ListTest.html
• [ ] Add tests for line height and alignment using Demo/Resources/Alignment.html and LineHeight.html
• [ ] Ensure tests run in swift.yml GitHub workflow

Add GitHub Actions workflow for tvOS and macOS platform testing

The repo supports iOS, macOS, and tvOS (evidenced by DTCoreText (Mac).xcscheme, DTCoreText (tvOS).xcscheme, and DTCoreText (iOS).xcscheme), but .github/workflows/swift.yml likely only tests iOS. Adding explicit test workflows for macOS and tvOS will catch platform-specific bugs early and ensure the multi-platform promise is maintained.

• [ ] Review current .github/workflows/swift.yml to understand iOS test setup
• [ ] Create or extend workflow to include macOS (using macos-latest) with DTCoreText (Mac).xcscheme
• [ ] Create or extend workflow to include tvOS (using macOS runner with -destination 'generic/platform=tvOS')
• [ ] Ensure all three platforms run their respective schemes: DTCoreText (iOS).xcscheme, DTCoreText (Mac).xcscheme, DTCoreText (tvOS).xcscheme
• [ ] Test that SwiftUI AttributedString generation works on all platforms

Document DTHTMLParser and DTAttributedTextView/DTAttributedLabel public API surface

The README mentions documentation is available online but DTCoreText's core classes (DTHTMLParser, DTAttributedTextView, DTAttributedLabel) likely lack inline documentation or the docs are incomplete. New contributors could add comprehensive DocC comments to public methods in core classes, matching the .spi.yml configuration and enabling better SwiftUI integration documentation (given the README mentions both NSAttributedString and SwiftUI AttributedString support).

• [ ] Identify all public methods in DTHTMLParser (or equivalent HTML parsing class)
• [ ] Add DocC-formatted comments (/// and related markup) for each public method with examples
• [ ] Add DocC comments to DTAttributedTextView public API
• [ ] Add DocC comments to DTAttributedLabel public API
• [ ] Document the SwiftUI AttributedString integration mentioned in README
• [ ] Verify documentation builds with .spi.yml configuration

• Add unit tests for CSS color parsing (hex, rgb, named colors) to Tests/DTCoreTextTests/—currently only spot-checked in demo apps. See DTHTMLParser.swift color handling ~line 180.
• Expand Demo/Resources/ with accessibility test HTML (alt text, ARIA labels) and add DTAttributedTextView accessibility delegate hooks—currently missing voiceover support for links and images.
• Document CoreText coordinate system gotchas in Documentation/Programming Guide-template.markdown with code examples showing how to convert CTFrame coordinates to UIView bounds for hit-testing; currently underdocumented.

DTCoreText is a rendering library with moderate security concerns. Primary risks stem from HTML parsing without apparent built-in sanitization (XSS/injection vectors), unsafe URL handling for links and embedded resources, and lack of security documentation. The Swift/iOS platform provides some inherent protections, but developers using this library with untrusted HTML input must implement their own sanitization. No secrets or hardcoded credentials were detected. No critical infrastructure misconfigurations identified. The codebase appears well-maintained but would benefit from explicit security guidelines and input validation mechanisms.

• High · HTML Parsing and XSS Risk — Sources/DTCoreText/ (HTML parsing components). DTCoreText converts HTML to NSAttributedString using CoreText. If user-supplied or untrusted HTML is processed without proper sanitization, it could lead to XSS-like attacks through embedded content (images, links, scripts). The library appears to parse arbitrary HTML and render it, which poses risks if the HTML source is not validated. Fix: Implement strict HTML sanitization and validation. Use an allowlist approach for permitted HTML tags and attributes. Validate all URLs before processing. Consider adding security guidelines in documentation warning about untrusted HTML sources.
• Medium · Unsafe URL Handling in Link Processing — Sources/DTCoreText/AnchorHTMLElement.swift. The AnchorHTMLElement.swift and link processing mechanisms may not properly validate or sanitize URLs. Malicious URLs (javascript:, data:, file:) could be embedded in HTML and executed or accessed inappropriately. Fix: Implement strict URL validation using URLComponents. Maintain a blocklist of dangerous URL schemes (javascript:, data:, file:, etc.). Use allowlist approach for permitted schemes (http, https). Validate and encode URLs before rendering.
• Medium · Resource Loading Without Validation — Demo/Resources/ (HTML files with external references). The Demo app includes resources like APOD.html, Image.html, and Video.html that may load remote content. If the library doesn't validate or sandbox remote resource loading (images, videos from URLs), it could lead to SSRF, data exfiltration, or loading of malicious content. Fix: Implement resource loading validation. Verify domain allowlists for remote resources. Use secure image loading with certificate validation. Implement timeout limits for resource fetching. Consider sandboxing external content loading.
• Low · Demo App Hardcoded Resources — Demo/Resources/ (multiple HTML test files). Demo app contains multiple hardcoded HTML files and test resources that reference external content. While not a direct vulnerability, this could obscure security testing and provide vectors for testing XSS payloads. Fix: Ensure test resources are clearly marked as such. Do not use test fixtures in production code. Add comments indicating security-sensitive test data.
• Low · Missing Security Documentation — Readme.markdown and Documentation/. The README and public-facing documentation do not include security guidelines for handling untrusted HTML input or recommendations for sanitization. Fix: Add a Security section to README warning about XSS risks with untrusted HTML. Document recommended sanitization practices. Provide security guidelines for library usage with user-supplied content.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.