axiom-textkit-ref

# TextKit 2 Reference

Complete reference for TextKit 2 covering architecture, migration from TextKit 1, Writing Tools integration, and SwiftUI TextEditor with AttributedString through iOS 26.

## Architecture

TextKit 2 uses MVC pattern with new classes optimized for correctness, safety, and performance.

### Model Layer

**NSTextContentManager** (abstract)
- Generates NSTextElement objects from backing store
- Tracks element ranges within document
- Default implementation: NSTextContentStorage

**NSTextContentStorage**
- Uses NSTextStorage as backing store
- Automatically divides content into NSTextParagraph elements
- Generates updated elements when text changes

**NSTextElement** (abstract)
- Represents portion of content (paragraph, attachment, custom type)
- Immutable value semantics
- Properties cannot change after creation
- Default implementation: NSTextParagraph

**NSTextParagraph**
- Represents single paragraph
- Contains range within document

### Controller Layer

**NSTextLayoutManager**
- Replaces TextKit 1's NSLayoutManager
- **NO glyph APIs** (abstracts away glyphs entirely)
- Takes elements, lays out into container, generates layout fragments
- Always uses noncontiguous layout

**NSTextLayoutFragment**
- Immutable layout information for one or more elements
- Key properties:
  - `textLineFragments` — array of NSTextLineFragment
  - `layoutFragmentFrame` — layout bounds within container
  - `renderingSurfaceBounds` — actual drawing bounds (can exceed frame)

**NSTextLineFragment**
- Measurement info for single line of text
- Used for line counting and geometric queries

### View Layer

**NSTextViewportLayoutController**
- Source of truth for viewport layout
- Coordinates visible-only layout
- Calls delegate methods: `willLayout`, `configureRenderingSurface`, `didLayout`

**NSTextContainer**
- Provides geometric information for layout destination
- Can define exclusion paths (non-rectangular layout)

### Object-Based Ranges

**NSTextLocation** (protoc