# Sapling Renderer Notes

## Overview

Sapling keeps Markdown source as the editable buffer and renders inactive lines with attributed styling. This document is a compact technical note for checking whether common documentation patterns feel readable while editing.

> Rendering can improve scanning, but the active line must always remain exact Markdown source.

## Goals

- Preserve native cursor movement.
- Keep typing latency independent from total document size.
- Make inactive lines easier to read.
  - Headings should create a clear hierarchy.
  - Lists should show nested structure.
  - Inline code should stand apart from prose.
- Defer rich embeds until the editor can support them without offset mapping.

## API Sketch

```swift
let renderer = HybridMarkdownLineRenderer()
let plans = renderer.renderPlans(for: lines)
```

The renderer returns line-level plans. The native text view applies attributes to the canonical source text.

## Supported Inline Forms

Use **strong emphasis** for important terms, *light emphasis* for nuance, and `inline code` for identifiers. Links such as [Swift Package Manager](https://swift.org/package-manager/) should be visually distinct.

Automatic links should also be recognizable: https://example.com/sapling/rendering

## Tradeoffs

| Choice | Result |
| ---- | ----- |
| Single source buffer | Stable cursor offsets |
| Attributed rendering | Fast dirty-line updates |
| No text replacement | Markdown markers remain part of layout |

---

## Checklist

- [x] Headings
- [x] Emphasis
- [x] Lists
- [x] Code blocks
- [ ] Images
- [ ] Wikilinks

