# RichTextEditor — project guide

A from-scratch **WYSIWYG rich-text editor for iOS** (UIKit; TextKit 2 on iOS 16+, TextKit 1 on iOS 13–15;
floor **iOS 13**) with images
(captions), lists, tables, links, inline custom emoji, and Telegram-style spoilers. The **defining
requirement** is **continuous selection across the whole document, including partial selection
*through* table cells** — which (per verified spike research) is only achievable with a **custom
`UITextInput` view owning one global position model**, NOT nested text views.

## Location & status in the monorepo

Moved in-tree **2026-06-09** to `submodules/TelegramUI/Components/RichTextEditor`; the standalone
`~/Documents/RichTextEditor` repo is the **pre-move archive** — it still holds the full per-phase
spec/plan/spike/handoff history and the project's original git log, none of which migrated in-tree.
Development continues here via **SwiftPM** exactly as before.

**Now wired into the app.** `ChatTextInputPanelNode` depends on `:RichTextEditorUIKit`, so both Bazel
targets — `//submodules/TelegramUI/Components/RichTextEditor:RichTextEditorCore` and
`:RichTextEditorUIKit` — **fully compile and run down to iOS 13** as part of the app build.

**Dual layout-engine back-port (2026-06-17).** TextKit was quarantined behind a one-method-per-call seam,
`protocol BlockLayoutEngine` (`Layout/BlockLayoutEngine.swift`), so the layout engine is swappable:
`BlockLayout` (TextKit 2, `@available(iOS 16.0, *)`) on iOS 16+, and **`BlockLayoutTK1`** (TextKit 1, iOS 7+,
ungated) on iOS 13–15. `makeBlockLayout(...)` picks TK2 on iOS 16+ / TK1 below; the runtime debug toggle
`BlockLayoutBackend.forceTextKit1` forces TK1 on any OS for testing the back-port (currently `#if DEBUG &&
false` → **off** even in debug, so the running app uses TK2 on iOS 16+; flip the `&& false` to opt in). The
system edit menu likewise falls back from `UIEditMenuInteraction` (iOS 16+) to **`UIMenuController`** (iOS
13–15) — see `DocumentCanvasView+EditMenu` (shared responder actions; custom items become flat `UIMenuItem`s).

**InstantPage V2 layout parity (2026-08-14).** The editor lays text out **pixel-identically to the
InstantPage V2 renderer**, so what an author types reads like the message the recipient sees. This
REPLACED the earlier `lineHeightMultiple` + glyph-centering model described here before; that model
cannot express V2's geometry at all (see "Why not a multiple" below). Both editor hosts opt in.

**The contract.** `RichTextRenderMetrics` (`Mapping/RichTextRenderMetrics.swift`) is a host-supplied
value set — per-style `(family, size, weight, lineSpacingFactor)` plus the block-rhythm scalars and
`edgeSpacingReduction` — and it **owns V2's line formulas as functions**:

```
L(F)      = floor(F.ascender + F.descender)     // V2's "fontLineHeight": a REDUCED box, not lineHeight
S(F,f)    = floor(L · f)                        // V2's "fontLineSpacing"; f scales L, NOT the point size
pitch     = L + S                               // baseline-to-baseline advance; always integral
firstBaseline(F) = F.ascender
textHeight(F,f,n) = ceil(A + |D|) + (n−1)·pitch
```

`StyleSheet` is a projection of it (`metrics`), so the heading ladder is V2's **22 / 20 / 18 / 17 / 16 /
15 serif medium** (retuned 2026-08-17 from 24 / 22 / 20 / 19 / 18 / 17; see the note under
`InstantPageTheme.headingTextAttributes` on why H1/H2 no longer borrow the `header` / `subheader`
categories). `RichTextRenderMetrics.default` is the chat-message look; hosts set
`RichTextEditorView.renderMetrics`. This retired `TextLayoutMetrics`/`textLayoutMetrics`,
`blockVerticalInset`, and `StyleSheet.bodyBaseSize` (now `metrics.body.size`;
`AttributedStringMapper.withBodyBaseSize` → `withBodyFontSize`).

**The `ceil` is load-bearing.** `layoutTextItem` returns `ceil(height)` because callers stack blocks by
adding sizes to a running origin, so one fractional box makes every later origin fractional. Omitting it
left every editor block ~0.7pt short and the error accumulated down the document — caught by the parity
test, not by inspection. The pitch is integral by construction, which is *why* the per-paragraph
correction stays independent of the line count.

**Why not a multiple.** `lineHeightMultiple` cannot express this: at the Instant Page reader's heading
factor (0.685) V2 wants a pitch TIGHTER than the font's natural line height, and
`NSParagraphStyle.lineSpacing` cannot go negative. So `StyleSheet.paragraphStyle` pins
`minimumLineHeight == maximumLineHeight == pitch` — one mechanism for both directions. An explicit
model-level `lineHeightMultiple` is user content and takes over instead; the two must never combine.

**Baseline placement is MEASURED, not derived.** `BlockLayoutEngine.baselineDelta` (a shared extension,
so the two engines cannot drift — each supplies only `rawFirstBaselineFromTop`) reads the baseline
TextKit actually produced and corrects it to `F.ascender`, V2's position. TextKit's placement inside a
pinned box is undocumented, so an analytic formula would silently drift across OS versions. Applied at
glyph-draw / `attachmentBox` / `firstLineBaselineFromTop`; caret/selection rects keep the full box.
**Not** the `baselineOffset` attribute — that is a real `CharacterAttributes` field (sub/superscript)
and would round-trip into the model. (The TK1 `NSLayoutManagerDelegate.shouldSetLineFragmentRect…`
baseline hook is **NOT invoked** under the TextKit-2-backed `NSLayoutManager` on modern iOS — verified
at runtime — so TK1 shifts manually too.) **The empty-line fallbacks must mirror it:** an empty
paragraph lays out no fragment, so `BlockBox.listMarkerBaselineFromTop` and `placeholderDraw` compute
the baseline analytically, and under this model that is simply `firstBaselineFromTop` — no shift.
Guarded by `LineHeightCenteringTests`, `ListRenderingTests`, `CanvasDecorationsTests`.

**Every height consumer goes through `correctedBoundingHeight`, never `boundingHeight`.** It lives on
the engine seam precisely so no call site can forget: the correction was first applied at one site
(`BlockBox`) and **four** other height paths — the collapsed-quote preview, the pull quote, the media
caption, code blocks — silently disagreed, which two existing height-parity tests caught.

**Font families are load-bearing, not stylistic.** `FontResolver.font(spec:bold:italic:family:)` mirrors
`InstantPageTextStyleStack`: **Georgia** for regular-weight serif, the **system serif design** (New York)
for weighted serif — bold there is a WEIGHT, not a symbolic trait — **Menlo** for monospace, system sans
otherwise. Every line formula is a function of `ascender`/`descender`, so resolving New York where the
renderer resolves Georgia shifts every line while type-checking perfectly.

**Block rhythm mirrors `spacingBetweenBlocks`.** `richTextSpacingBetweenBlocks`
(`Canvas/BlockSpacing.swift`) is a transcription over `RichTextBlockSpacingKind`, the InstantPage cases
the editor can produce; **rule ORDER is load-bearing** (several arms would otherwise both match). Two
body paragraphs sit **1pt** apart, a heading takes both paddings, two bare images butt at 1pt.
`CanvasBlock.spacingKind` has **no default implementation** on purpose — a conservative default would
compile everywhere while silently giving a new block type the wrong rhythm. Adjacent list items collapse
into the single virtual `.list` block the renderer sees, mirroring `buildListBlocks`; the shared
`ParagraphBlock.standaloneFormulaLatex` predicate lives in Core so the classification cannot drift from
what `InstantPageBuilder` emits.

**GAP OWNERSHIP IS LOAD-BEARING.** V2's gap is ONE quantity between two blocks, not two facing insets,
and it is carried by whichever neighbour can own it — preferring the lower, falling back to the
paragraph above. A framed atom (table / code / quote / details) fills its own frame and has no external
inset, so giving it the gap leaves **unowned dead space**; the arrow-key escape probe in `+Navigation`
(`owner.frame.minY − step/2`) then lands in nothing and **the caret cannot leave a table**
(`CanvasTableNavTests` caught exactly this). Only where no paragraph can own it — a non-`BlockBox` at a
sequence edge, or two such neighbours — is the gap laid down as bare space. Side effect to know: a tap in
a gap resolves to the block below.

**A BARE GAP BELONGS TO NO BOX FRAME, so no height may be summed from box heights.** `BlockStack` owns the
ownership rule in exactly one place — `bareGapAbove(_:_:)` / `bareTrailingGap(_:)` — read by BOTH `layout`
and the live `currentHeight`, because the two silently disagreed: `DocumentCanvasView.intrinsicContentSize`
(what `performLayout` feeds to `scrollView.contentSize`) summed box heights and so under-reported the
laid-out extent by **4pt per bare gap, accumulating** (36pt for five non-paragraph blocks). The trailing
blocks then sat outside the scrollable range — unreachable, overlapping the host's bottom inset band. A
paragraphs-only document has no bare gaps, which is why it stayed hidden; the stateless
`measuredHeight`/`measuredContentHeight` path was correct all along, so measure and commit disagreed.
Guarded by the three `RichTextEditorViewTests.test_document*_scrollContentCoversEveryBlock` cases, which
assert the scroll content EQUALS `root.contentHeight` + margins. Related: every height path calls
`applyRootSpacingConfig()` rather than inheriting the last one's rhythm state — `intrinsicContentSize` is
read BEFORE the layout pass, so it cannot assume `layoutContent` ran first.

**Scope.** Only the document's TOP-LEVEL sequence is on V2's rhythm (`BlockStack.spacingModel ==
.instantPageV2`). Stacks nested in a container — table cells, details, block-quote children — keep the
pre-parity facing-inset model verbatim (`.containerInterior`), and author-line placement in both quote
types deliberately measures the RAW line box. Those interiors have no V2 reference yet.

**Deferred:** container interiors (block quote incl. V2's `quoteScale` 15/17 content scaling, pull
quote, code-block insets), list marker geometry, table cell insets, media captions/credits, details
chrome — and inline-attachment line inflation (V2 inflates `lineAscent` for formulas/buttons and adds
`extraDescent` for tall inline images; a pinned `maximumLineHeight` clips that, so plain text and custom
emoji are exact while those are not).

**Verification.** `//submodules/InstantPageUI:InstantPageUITests` holds both parity layers:
`RichTextV2MetricsParityTests` calls `layoutTextItem` and `spacingBetweenBlocks` directly and pins the
formulas, the resolved font faces, and the **whole** pairwise gap table plus both edges (and pins
`RichTextRenderMetrics.default` against the adapted theme — the composer depends on that default because
it cannot import `InstantPageUI`, which would be a cycle); `RichTextV2FrameParityTests` pins the
composition via the DEBUG-only `RichTextEditorView.layoutSnapshot()`. Line-break agreement between
TextKit and `CTTypesetterSuggestLineBreak` was measured at **50/50** over a 10-string corpus × 5 widths
(CJK, RTL, hyphens, trailing spaces, emoji), which is why the wrapped-text parity assertions are
unconditional. **Runtime-checked in the chat composer**, which is what surfaced the outer-padding
problem the `edgeSpacingReduction` trim above fixes — a reminder that measured parity against the
renderer's functions does not by itself mean a host's field reads right. **Still unverified on screen:**
the composer-vs-sent-bubble and article-editor-vs-sent-message side-by-side comparisons. If you have the
`mcp__XcodeBuildMCP__*` tools, those are the two screenshots worth taking; a code block still will not
match exactly (the editor draws `monospacedSystemFont` where the renderer uses Menlo, and nothing reads
`metrics.codeBlock` yet) — though its GEOMETRY is now shared, via `metrics.code` (see below).

So **the UIKit target is gated `@available(iOS 13.0, *)`** (`RichTextEditorCore` is pure-Foundation,
always-available), with only genuine higher-OS APIs kept at their real floor: the TK2 `BlockLayout` type + the
4 `UIEditMenuInteraction` touch-points at **iOS 16**; the magnifier loupe (`UITextLoupeSession`) +
`inlinePredictionType` at **iOS 17**; Translate at **17.4**; `isEditable` at **18**. **TK1 trade-offs on iOS
13–15** (deliberate): no spoiler text-hiding (UIKit `NSLayoutManager` has no rendering/temporary-attribute
analog), no loupe, no inline predictions — everything else (editing, tables, lists, links, emoji, selection,
IME, edit menu) works. Full SwiftPM suite is green on both engines (TK1 via the DEBUG `forceTextKit1`). The
app-side consumers (`RichTextEditorChatInputNode`, `RichTextAttachmentScreen` + its helpers,
`StandaloneInstantPageImageView`) are also lowered to iOS 13; the editor is the native chat-composer backend,
**opted into** via the `forceNewTextInput` ("Force Text Field v2") experimental flag. By default the composer is a
dual-field switch — the legacy input, latching to the native editor only when content becomes legacy-non-representable
(`ChatTextInputPanelNode`; `ios_rich_input_mode` server flag). (Inverted the earlier default + `forceLegacyTextInput` opt-out.)

**Spoiler-texture resource access is build-system-split (via `#if SWIFT_PACKAGE`).** `SpoilerDustView`
resolves the particle texture two ways: under **SwiftPM** it uses `UIImage(named: "TextSpeckle", in:
.module, …)` (the generated `.module` accessor); under **Bazel** it uses the app's **`AppBundle`** —
`UIImage(bundleImageName: "Components/TextSpeckle")`, with `//submodules/AppBundle` in the UIKit
target's Bazel `deps` — because `.module` only exists under SwiftPM (it failed the Bazel compile).
`import AppBundle` is likewise gated `#if !SWIFT_PACKAGE`. So **both build systems compile**: the
Bazel/app build *and* the SwiftPM workflow (`swift test`, `Scripts/iostest.sh`, the `Demo/` app). When
editing this resource path, keep both `#if` branches in sync.

## Build & test (SwiftPM, not Bazel) — all from this directory

- **Core (UIKit-free) tests, fast:** `swift test` (runs on macOS).
- **UIKit tests, iOS simulator:** `Scripts/iostest.sh [Class/Test filter]` — wraps
  `xcodebuild test -scheme RichTextEditor-Package -destination 'platform=iOS Simulator,name=iPhone 17 Pro'`.
  Expects an "iPhone 17 Pro" simulator booted; override with `DEVICE=…`.
- **Demo app (visual check):** `cd Demo && xcodegen generate && xcodebuild …` then
  `xcrun simctl install/launch/io screenshot`. The generated `RichTextEditorDemo.xcodeproj` is gitignored.

All UIKit sources/tests are wrapped in `#if canImport(UIKit) … #endif` so `swift test` keeps compiling
Core on macOS while the UIKit suite runs only on the simulator. The suite is ~690 tests (Core + UIKit);
the exact number is one `grep -r 'func test' Tests` away — it isn't tracked here.

## Architecture & conventions

**Two SwiftPM targets:**
- `RichTextEditorCore` — **no UIKit**: the model (`Document`/`Block`/`TextRun`/`CharacterAttributes`/…),
  JSON (`DocumentCodec`) and `.rtdoc`-package (`DocumentPackage`) serialization, the ProseMirror-style
  **global position model** (`DocumentTree` + `PositionResolver`), the selection model (`RTSelection`),
  `TableMap`, and list numbering (`ListNumbering`). Core stays UIKit-free so it's shareable and
  `swift test`-able on macOS.
- `RichTextEditorUIKit` — the views (depends on Core).

**Public surface.** `RichTextEditorView` is the **only public** type (the façade), with the small value type
`RichTextEditorPlaceholders` (a config struct, below). `DocumentCanvasView` (the multi-block editing surface)
and everything else are **internal** — keeping them internal lets their `UITextInput` witnesses stay internal
(a public type conforming to public `UITextInput` would force every witness `public`).

**Compact-host (chat-composer) configuration knobs (added 2026-06-16, `RichTextEditorView+ComposerHost.swift`).**
The editor's defaults assume a full-page document; a compact host (the chat composer,
`ChatRichTextEditorComposer`) tunes these via the façade. **Every knob defaults to the document-editor
behavior, so the attachment screen / Demo / SwiftPM tests are unchanged.** The composer sets each in `didLoad`
*before* seeding the document so the first layout picks them up:
- `contentPageMargin` (default `CanvasMetrics.pageMargin` = 16) — the built-in horizontal page margin on each
  side (`DocumentCanvasView.pageMargin`, used by `contentLeftPad`/`contentRightPad`; media bleed is governed
  separately by the `mediaBlockStyle` knob). Composer → 0.
- `minimumContentHeight` (default 44) — the floor `performLayout` applies to the returned content height.
  Composer → 0 (the height hugs the text; the host owns the min field height).
- `placeholders` (`RichTextEditorPlaceholders`, default = "Type something…" + the two list hints) — the empty-
  paragraph placeholder strings, stamped onto top-level boxes in `stampListMarkers`; an empty string for a case
  draws nothing. Composer → all "".
- `canvasBackgroundColor` (default `.systemBackground`, the document "page") — the canvas background; the
  scroll view + `BlockBackingView`s are already clear. Composer → `nil` (transparent over the input panel).
- `tapBelowAddsTrailingParagraph` (default `true`) — whether a tap in the empty area below the document's last
  block appends a new empty body paragraph there (the `point.y > boxes.last.frame.maxY` affordance in
  `+Interaction.swift`; see the quote-escape note below). The full-page article editor keeps it on; the compact
  composer has no "empty area below the content" to grow into, so **Composer → `false`** (a tap there just places
  the caret in the trailing paragraph). Unlike the other knobs the composer sets this in `didLoad` purely for
  behavior — it doesn't affect layout, so its timing vs. the document seed is immaterial.
- `renderMetrics` (`RichTextRenderMetrics`, default `.default` = the chat-message look) — the whole
  font + line-geometry + block-rhythm contract; see the V2 layout-parity note above. Applied via
  `applyRenderMetrics` → mapper rebuild + reload (mirrors `quoteStyle`). **BOTH hosts pass V2 metrics**:
  the composer assigns `RichTextRenderMetrics.default` (it cannot import `InstantPageUI` — that edge is a
  cycle, and the default is pinned equal to the adapted theme by test), the article editor calls
  `InstantPageTheme.chatMessageRenderMetrics()`. This replaced `textLayoutMetrics`, whose per-style
  `lineHeightMultiple` + paragraph-spacing model is gone: V2 keeps ALL inter-block spacing in the rhythm
  table and its strings carry none, so a residual per-style spacing would double-count every gap. It also
  replaced `blockVerticalInset` — the rhythm is the contract's now, and a host that needs tighter outer
  padding trims `edgeSpacingReduction` (V2's own parameter; the bubble passes 1.0) rather than
  reintroducing a compact knob. **The composer does exactly that, trimming 6 (`composerEdgeSpacingReduction`).**
  V2 gives a top-level paragraph `blockVerticalPadding + 2` = 6pt at each SEQUENCE EDGE — not to be
  confused with the 1pt inter-paragraph gap — so an untrimmed one-line field measured 33pt against the
  text's own 21pt, which read as too much padding in the input panel. In a page that padding IS the page
  margin; in the composer the panel already owns the padding around the field, which is why the
  pre-parity config zeroed the block inset for the same reason. The trim touches only the edges, so the
  interior rhythm stays V2-exact. An explicit per-paragraph `lineHeightMultiple` in the model still
  overrides the pinned box.
- `mediaBlockStyle` (`MediaBlockStyle`, default `.default` = `horizontalBleed` 16 == `CanvasMetrics.pageMargin`,
  the document edge-to-edge look) — how far a top-level media block bleeds beyond the text content strip on each
  side; applied via `applyMediaBlockStyle` (pure geometry, no mapper rebuild) and read at `MediaBlockBox` creation
  (`setBlocks`/`insertMedia`); table-cell media always passes `horizontalBleed: 0`. Composer →
  `MediaBlockStyle(horizontalBleed: 0)` so media insets like the text paragraphs.

Two host-side runtime contracts the composer had to honor (apply to any non-attachment host): **seed an initial
`document`** (the canvas starts with ZERO blocks; nothing renders/edits until the `document` setter runs), and
**re-run `update(...)` in response to `onChange`** (the view is parent-driven and does not self-layout on a
content change — without this, typed text is never laid out).

**Keyboard input language (added 2026-06-26).** `RichTextEditorView` exposes
`inputPrimaryLanguage` (read the live keyboard language back), `initialInputPrimaryLanguage`
(seed the language the keyboard opens in next focus), and `resetInputPrimaryLanguage()`,
forwarding to a one-time `textInputMode` override on `DocumentCanvasView` (the actual first
responder) — a verbatim port of the legacy `ChatInputTextView` mechanism so the chat composer
repopulates `interfaceState.inputLanguage` (emoji-keyword search + draft persistence).
LOAD-BEARING: the override is single-shot (first `textInputMode` query consumes the
pre-selection); UIKit queries it on `becomeFirstResponder` before any host read-back, so do not
add a separate non-side-effecting read path.

**Dynamic theme (added 2026-06-17, `Theme/RichTextEditorTheme.swift`).** `RichTextEditorView.theme:
RichTextEditorTheme` is a host-settable struct of eleven UIColors; assigning it updates the mapper, pushes the
accent to the caret/selection-handles/blockquote views, reloads — **only when the view is sized (`bounds.width >
0`)** — so boxes rebuild with the themed mapper, and redraws. **`.default` reproduces the editor's prior hardcoded colors exactly, so the look is unchanged until a
host sets a theme.** Host wiring: the **chat composer** wires it — `ChatTextInputPanelNode` maps
`PresentationTheme` → `ChatRichTextThemeColors` (a `UIColor`-only seam type in `ChatInputTextNode`) and pushes
it via `ChatRichTextInputNode.applyRichTextTheme`, which `RichTextEditorChatInputNode` maps to this `theme`.
`RichTextAttachmentScreen` now also wires a theme. What each color drives:
- `primaryText` (default `.black`) — default foreground for runs with no explicit color.
- `secondaryText` (default `.black`) — default foreground for `.caption`-style runs.
- `placeholder` (default `.placeholderText`) — empty-paragraph, marked-text ghost, and media placeholder text.
- `accent` (default `.link`) — link text, the blockquote bar + fill, the caret, the selection visuals
  (handles via a pushed `accentColor`; the body/cell selection *wash* reads `mapper.theme.accent` live),
  the table-control resize knobs, the selection-outline stroke, and the active-handle pill fill.
- `tableBorder` (default the prior dynamic grid color) / `tableHeaderBackground` (default `white 0.5/0.1`) — the
  table grid stroke and header-row fill (the former `TableBlockBox.gridColor`/`headerRowBackground` statics).
- `codeBackground` (default prior dynamic color) — the code band's plain fill, painted by `CodeBlockBox`
  itself. Both hosts set it to the same value as `tableHeaderBackground`, so a code block reads as a
  highlighted table row. (Declared but unread until 2026-08-18.)
- `listMarker` (default `.label`) — list bullet/number marker color.
- `inlineCodeBackground` (default `.systemGray5`) — inline-code run background pill.
- `markedTextUnderline` (default `.label`) — IME marked-text (composing) underline.
- `spoilerDust` (default `.secondaryLabel`) — spoiler particle ("dust") tint.

**Apply the theme BEFORE seeding the `document` (host-ordering invariant).** The `document` setter builds each
block's attributed string with the mapper's *current* theme (baking in the foreground color), and — per above —
the `theme` setter re-maps already-built boxes only when `bounds.width > 0`. So a host that assigns `theme`
*after* `document` while the view is still unsized (its frame set later in the same layout pass) leaves
pre-existing text in the `.default` foreground; an empty document is unaffected (later typed text uses the
by-then-themed mapper). Both hosts therefore theme before seeding — the composer in `didLoad`,
`RichTextAttachmentScreen` in its `if component == nil` init block (before `editor.document = …`). (Regressed
once: pre-existing text rendered black in dark mode, fixed 2026-06-26.)

**Round-trip invariant (load-bearing):** theme colors are applied at render time only and **never persist into the
`Document`**. `AttributedStringMapper` is symmetric — the forward pass injects the per-style default
(`secondaryText` for `.caption`, else `primaryText`) for un-colored runs; the reverse (`characterAttributes(from:
style:)` / `runs(from:style:)`) strips a foreground equal to that per-style default back to `nil`. Every
reverse-mapper caller MUST pass the run's paragraph style (`BlockBox` → its style, `MediaBlockBox` captions →
`.caption`, `+Editing` → the start box's style; `+State` reads only format flags, so its `.body` default is fine)
— a wrong style compares against the wrong default and pollutes the model. An explicit user color exactly equal to
the style default is also stripped (visually identical, re-themable). Known limitation: removing a link inside
a `.caption` run under a theme where `primaryText != secondaryText` leaves an explicit foreground (latent; see
`removeLink`).

**Host input hooks (added 2026-06-12 for the emoji keyboard).** The façade exposes three generic, UIKit-only
input hooks so a consumer can drive a custom input panel: `insertText(_:)` (plain text at the caret, one undo
step), `deleteBackward()`, and `customInputView: UIView?` (forwarded to the canvas's `inputView` +
`reloadInputViews()` — set an `EmptyInputView` to suppress the system keyboard *while the canvas stays first
responder*, so the caret keeps rendering under a separate panel). The actual Telegram **emoji keyboard** is
wired **consumer-side** in `RichTextAttachmentScreen` (`RichTextEmojiKeyboardController`, hosting
`ChatEntityKeyboardInputNode`) — the package itself stays free of `AccountContext`/TelegramUI. Custom emoji
insert via the existing `insertEmoji(id:altText:)` (id = the Telegram fileId string) + a host
`registerEmojiViewProvider` that renders an `InlineStickerItemLayer`.

**Emoji-view template tinting (`RichTextEmojiView`, added 2026-07-17).** `registerEmojiViewProvider` returns a
`(UIView & RichTextEmojiView)?` (not a bare `UIView?`) — `RichTextEmojiView` (in `DocumentCanvasView.swift`,
alongside `RichTextChecklistMarkerView`) requires one settable `var dynamicColor: UIColor?`. The editor keeps it
synced to the current text color (`mapper.theme.primaryText`) on **every** `syncEmojiViews` pass (cheap — the
host setter no-ops on an unchanged value; self-healing across theme changes, since a theme reload relays out), so
a Telegram **custom *template* emoji** (single-color, `file.isCustomTemplateEmoji`) mask-tints to the surrounding
text — matching the legacy input. Both hosts conform their view: the **chat composer** builds an
`EmojiTextAttachmentView` (which gained a `dynamicColor` property forwarding to its `InlineStickerItemLayer`;
the `RichTextEmojiView` conformance is declared retroactively in `ChatTextInputPanelNode`, the one module importing
both — so `EmojiTextAttachmentView` stays free of a rich-text-editor dep). The `ChatRichTextInputNode` protocol
seam that carries the provider stays `-> UIView?` (unchanged; the legacy backend shares it), so
`RichTextEditorChatInputNode`'s registration closure `as?`-casts the returned view to the conforming type (the
runtime finds the panel-module conformance in the linked app). The **article editor**
(`RichTextEmojiKeyboardController.customEmojiView`) returns a small `RichTextInlineEmojiView` wrapper forwarding
`dynamicColor` to its `InlineStickerItemLayer`. A non-template (full-color) emoji ignores `dynamicColor`.

**Parent-driven layout + state query (added 2026-06-12, branch `feature/richtext-message-serialization`).**
The façade is now driven by its host rather than self-laying-out:
- `update(size:insets:) -> CGFloat` — the parent supplies the frame `size` and scroll `insets` (it owns the
  keyboard/panel inset, e.g. from `environment.inputHeight`); returns the measured content height. The view
  set `scrollView.contentInsetAdjustmentBehavior = .never` and **removed all `UIResponder` keyboard
  observation**. A private `performLayout(size:)` sizes the scroll view/canvas; only `update` writes insets
  (so a system `layoutSubviews` pass can't clobber the parent inset). Caret-follow scrolling stays internal.
  **A CHANGED TOP inset re-seats a scroll view that is resting at the top** (`contentOffset.y = −insets.top`,
  applied after `performLayout` so the new content size is in place; gated on the top inset actually changing,
  so a keyboard-driven bottom inset or a post-edit re-layout never moves a scroll the user owns). UIKit only
  CLAMPS the offset on an inset change and `contentInsetAdjustmentBehavior` is `.never`, so nothing else does
  it: a SHORT document is clamped into place for free (the visible-height floor makes `−top` its only valid
  offset) but a document TALLER than the viewport leaves offset 0 in range — which is why the article editor
  opened with its first screenful hidden under the navigation bar while the composer looked fine (its top inset
  is 0). Guarded by `RichTextEditorViewTests.test_update_tallDocument_restsBelowTheTopInset` +
  `…_doesNotResetAScrolledOffset`.
- `height(forWidth:contentMargins:) -> CGFloat` — a side-effect-free content-height measure (the Phase-2
  follow-up to the composer's `textHeightForWidth`). Mirrors what `update(...)` returns at that width
  (same `minimumContentHeight` floor + `contentMargins`) but reflows NOTHING live: the per-block
  `measuredHeight(forWidth:)` chain reads structural insets and measures text via a reused per-engine
  scratch layout (`BlockLayoutEngine.boundingHeight(forWidth:)`). De-stateful-ized `TableBlockBox.height`
  in passing (it no longer resizes cell layouts to measure; `recompute()` owns cell layout).
  **LOAD-BEARING — the measure must be PURE w.r.t. the live `contentMargins`, not just the live layout
  (2026-06-30).** `measuredContentHeight` derives the content WIDTH from the margins (`contentWidth` =
  `width − contentLeftPad − contentRightPad`), so reading the live `canvas.contentMargins` makes the result
  depend on whether `update(...)` has run yet. A host that sizes its field from this BEFORE the first
  `update(...)` (the chat composer when a draft is applied before the editor is framed — `bounds.width == 0`,
  so `setInputContent` skips the corrective `update`) then measures the text at the FULL width (the right-inset
  reservation is still 0 → fewer wrapped lines → a too-short height), and the field visibly GROWS one pass
  later when the real margins land — the device-verified "pre-set draft text jumps on open, not every time"
  bug (the intermittency is the async draft-push racing the first layout). Fix: `height(forWidth:contentMargins:)`
  + `measuredContentHeight(forWidth:contentMargins:)` take the intended margins explicitly; the composer's
  `textHeightForWidth` passes its `trackedContentMargins` (the value the next `update` will apply), so the
  measure is correct on the first pass regardless of the race. `nil` keeps the live-margins behavior for hosts
  that always `update` before measuring (`RichTextAttachmentScreen`), so they're byte-unchanged.
- `onChange: (() -> Void)?` — payload-free; fires on any edit, content-size change, or selection move
  (funneled from the canvas's `onContentSizeChange` + `onSelectionChange`, the latter fired unconditionally by
  `editing { }`). The host re-runs its layout (→ `update`) in response. **`update` must NOT synchronously fire
  `onChange`** (would recurse) — guarded by a regression test.
- `currentState() -> EditorState` — a pure read (bold/italic/underline/strikethrough/code, paragraphStyle,
  listMarker, link, hasSelection, isInTable, canUndo, canRedo) built from canvas internals; drives a host
  toolbar's per-action availability + selected state. Inline flags are uniform-over-selection, or the caret's
  inherited run format when collapsed. The 5 format predicates are extracted (`rangeIsBold` etc.) and shared
  by the `toggle*` commands and `currentState`.
- `deleteTable()` — removes the caret's table (one undo step; caret lands on the successor block, or a fresh
  empty paragraph if it was the only block). No-op when not in a table. (This is the handle-menu "Delete Table"
  / caret-based path, which *joins* the surrounding content.)
- **Backspace with a table structural (row/column) selection** (`deleteTableStructuralSelection`, hooked at the
  top of `deleteBackward` since the parked caret would otherwise hit the in-cell delete) deletes the selected
  rows / columns — routing to the existing `deleteTableRow` / `deleteTableColumn` (which already read
  `structuralRowRange()` / `structuralColumnRange()`). When the selection covers EVERY row or EVERY column
  (`lowerBound <= 0 && upperBound >= rowCount/columnCount − 1`) — which would empty the table — it removes the
  whole table block instead, replacing it **in place** with an empty body paragraph (caret there). Distinct from
  `deleteTable()` above (which joins): full-selection backspace leaves an empty paragraph where the table was.
  The structural selection is cleared afterward (mirrors the handle menu's `structuralAction`).
- `composerSelectedRange: NSRange { get set }` — the selection in the **chat composer's flat UTF-16
  coordinate space** (the document's top-level paragraphs joined by `"\n"`, exactly the
  `ComposerDocumentBridge` flattening; non-paragraph blocks contribute nothing). Maps that flat offset
  to/from the editor's global selection axis (which carries non-renderable structural slots between blocks),
  collapsing each paragraph break to one `"\n"` so a multi-UTF-16-unit emoji + the separators line up 1:1
  with what `ChatTextInputPanelNode` inserts. **This is load-bearing for the chat composer:**
  `RichTextEditorChatInputNode.selectedRange` forwards to it, and the panel drives ALL insert/replace/caret
  moves off `selectedRange`. While it was a stub (getter = end-of-text, setter = no-op) the panel was
  selection-blind — the caret never advanced after a programmatic insert and a surrogate-pair emoji was split
  on a delete/insert cycle, leaving a stray code unit (a "service character"). The setter brackets
  `selectionWillChange/DidChange` (programmatic move). Implemented in `DocumentCanvasView+ComposerSelection`.

**Host edit-menu hook (added 2026-06-17, `RichTextEditorView` + `DocumentCanvasView+EditMenuActions`).**
`contextMenuItemsProvider: ((_ defaultElements: [UIMenuElement]) -> [UIMenuElement])?` lets a host **transform**
the iOS-16 edit menu. The editor calls it from `editMenuInteraction(_:menuFor:suggestedActions:)` with
`defaultElements` = the system suggested actions (Cut/Copy/Paste/Select + Writing Tools) **followed by the
editor's own custom items** (the built-in "Format" submenu + Look Up / Translate / Share); the host returns the
final children. Consulted **only for a non-collapsed selection** (matches `customEditMenuElements()`' own gating)
and **only on iOS 16+** — on iOS 13–15 (`UIMenuController`) host items are NOT injected (a `UIMenuItem` needs an
Obj-C `#selector` and can't carry a closure; `UIAction` hides its handler, so the closure-based host items can't
be bridged). `nil` ⇒ the editor's default menu, unchanged. The chat composer (`ChatTextInputPanelNode`) uses it
to drop the editor's 3-item built-in Format submenu and splice in its richer 10-item one (Bold/Italic/Monospace/
Link/Strikethrough/Underline/Quote/Spoiler/Date/Code, secret-chat gated), routing each to the editor's native
engine (`toggleBold()` etc.; Quote → `setParagraphStyle(.quote)`; Date/Code are deferred no-ops); Link reuses the
host link UI (a branched `openLinkEditing` in `ChatControllerLoadDisplayNode`, using `currentLink()` /
`selectedText()` / `setLink`/`removeLink`). `selectedText() -> String` is the selected substring (for that link
editor). Spec/plan for this work were intentionally not retained in-tree.

**Composer bridge round-trip — custom emoji / mention / date (added 2026-06-19, `feature/richtext-composer-bridge-gaps`).**
`ComposerDocumentBridge` (`ChatRichTextEditorComposer`) and `EntityMessageBuilder` (`RichTextEditorMessageConversion`)
convert the composer's `Document` to/from the chat `NSAttributedString` currency. They now round-trip three inline
features that previously dropped: **custom emoji** (`ChatTextInputAttributes.customEmoji` ↔ `CharacterAttributes.emoji`
as a one-`U+FFFC` run; the original placeholder text is kept in `EmojiRef.altText` and re-emitted, since the Document
interior must stay a single `U+FFFC`), and **mention/date**, which are stored in the Document's existing
`CharacterAttributes.link` field as `tg://user?id=` / `tg://timestamp?t=` markers — **no new `CharacterAttributes`
field** (keeps Core markdown-clean). The encode/decode + the chat-attribute emit are centralized in the shared
`TextFormat` codec `MentionDateMarkers.swift` (`mentionMarkdownURL`/`parseMentionPeerId`, `dateMarkdownURL`/`parseDate`,
`classifyChatLink`, `chatInputLinkAttribute`) so the three sites (`document(from:)` / `attributedString(from:)` /
`buildEntityMessage`) + `composerContentEqual` can't drift; unit-tested in `//submodules/TextFormat:TextFormatTests`
(the repo's first `ios_unit_test`). The send path is automatic — the builder stamps the chat attributes and
`generateChatInputTextEntities` already emits `.CustomEmoji`/`.TextMention`/`.FormattedDate`. **Creation is unchanged**
(the Date menu item remains a no-op — this is preservation only; **code-block round-tripping + creation landed in the
follow-up note below**). **Known accepted limitation:** a `textUrl` whose string equals a
`tg://` marker (via markdown/paste/edit) is reinterpreted as a mention/date on round-trip — low-probability,
documented in `MentionDateMarkers.swift`. Spec/plan in `docs/superpowers/{specs,plans}/2026-06-18-richtext-composer-bridge-gaps*`.

**Load-bearing invariant — the iOS-16 edit menu needs `Display.Window1.hitTest` to forward to it.**
`UIEditMenuInteraction` hosts its menu in a top-level `_UIEditMenuContainerView` subview of the app window.
Telegram's `Window1.hitTest` (`submodules/Display/Source/WindowContent.swift`) only forwards touches to window
subviews whose class matches an allow-list; it was extended (2026-06-17) to match `"EditMenu"` (alongside the
pre-iOS-16 `"UITransitionView"` / `"ContextMenuContainerView"`). **Without that match, taps on the menu fall
through to the content below and every item is inert** — the symptom that surfaced first here because this is a
custom `UITextInput` presenting `UIEditMenuInteraction` directly. Any editor change that relies on the system
edit menu being interactive in the Telegram app depends on this allow-list entry.

**Deferred:** pending caret formatting (inline toggles at a *collapsed* caret are currently inert — they show
the inherited state but don't affect the next typed char). (Table structural row/column selection + its
delete-via-Backspace now landed — see `deleteTableStructuralSelection` above.) **Code blocks landed**
(2026-06-19, `feature/richtext-code-block`) as a first-class multi-line `Block.code` — see the dedicated note
below; they now losslessly round-trip and Format▸Code creates one. Dates now *round-trip* via the link scheme
(see the composer-bridge note above), but the Date menu item remains a creation no-op (no native
timestamp-creation UI yet).

**Composer code blocks — first-class `Block.code` (added 2026-06-19, `feature/richtext-code-block`).** A
multi-line code block is now a first-class `Block.code(CodeBlock)` (`Core/Model/CodeBlock.swift`: `id` +
`language: String?` + plain `runs` whose text may contain interior `"\n"`), rendered by a new
`CodeBlockBox: CanvasBlock` (`Canvas/CodeBlockBox.swift`) — a monospace `BlockLayoutEngine` inside a band the
box paints ITSELF (see the edge-to-edge note below; it shared the quote's `BlockquoteUnderlay` until
2026-08-18). **It reuses the
existing position model unchanged:** `Block.code` maps to a `.paragraph` `DocNode` carrying a `TextNodeRef.code`
leaf, sized `content + 2` exactly like a wrap-heavy paragraph — multi-line interior `"\n"`s need **no** new
position/selection/tokenizer machinery (they're a linear UTF-16 range TextKit wraps). `currentBlock()` reads
back the **plain** layout string (display-only monospace attrs never enter the model). Editing affordances
mirror quotes (`+UITextInput`/`+Editing`/`+Interaction`): **Enter** inserts an interior newline via
`insertCodeBlockNewline()` (replacing any selection); **double-return** (Enter on an empty line —
`codeBlockDoubleReturnExit`) EXITS — a **trailing** blank line → body paragraph *after*
(`exitCodeBlockToBodyParagraph`), the **first** blank line → body *before* (`exitCodeBlockToBodyParagraphBefore`; fires at local 0 OR local 1 — the
start of content right after a leading blank — so **two newlines at the beginning** break out above),
a **wholly-empty** block → un-code (`uncodeEmptyCodeBlock`); a MIDDLE blank line just inserts another newline.
**Backspace** in a fully-empty code block un-codes it to body;
a **tap below** a trailing code block appends a body paragraph; **cross-block** edits treat a code endpoint
like media (truncate-and-keep partial coverage, drop full coverage) in `applyReplaceOutcome`. **Creation:**
`makeCodeBlock()` (`+ParagraphFormat`, façade-forwarded) toggles the touched top-level paragraphs into one code
block (joining BOTH paragraph and existing-code text, refusing a selection that spans a non-text block) and
toggles back to body paragraphs split on `"\n"`; wired to the composer's Format▸Code via
`performFormatAction(.code)`. The chat round-trip is the **bridge** (`ComposerDocumentBridge` two-pass
`document(from:)` + emit) and **send** (`EntityMessageBuilder` → `.Pre`), centralized through `TextFormat`
`CodeBlockMarkers.swift` (`chatInputCodeBlockAttribute` / `codeBlockRanges`, unit-tested); the `composerParagraphs`
flat-mapping counts a code block's interior. Full SwiftPM suite green (Core 102 + UIKit 714); the app build +
`TextFormatTests` are green; **no logged-in-sim pass yet** (non-gating). The composer flat-coordinate mapping
and the position axis were the load-bearing reuse points — code blocks added zero new invariants there. Spec/plan:
`docs/superpowers/{specs/2026-06-19-richtext-code-block-design.md,plans/2026-06-19-richtext-code-block.md}`.

**Code-block LANGUAGE field + syntax highlighting (added 2026-08-25).** A code block's language is
**authored in an always-visible, editable line at the top of the band**, and code is syntax-highlighted in
both editor hosts. `CodeBlock.language` and its whole serialization path already existed; this added the
authoring UI and wired the highlighter.

**The language line is a second LEAF REGION on `CodeBlockBox`** — its own `BlockLayoutEngine`
(`languageLayout`), its own `TextNodeRef.codeLanguage`, and a `DocumentTree` shape change: `.code` maps to a
CONTAINER of two paragraph children, `[language, code]`. It mirrors a pull quote's `[text, author]`, with
the extra region LEADING and **never content-gated** (a quote author appears only once its quote has
content; the language field is always visible, which is also what keeps the code text's offset stable).
`nodeSize` is `len + langLen + 6`; the language text sits at `nodeStart + 1`, the code text at
`nodeStart + langLen + 3`. The value is stored AS TYPED, trimmed, empty → nil; only the renderer lowercases.

- **`textStart`/`textLength`/`textRef` still mean the CODE region, and `activeStack` resolves a box by that
  PRIMARY region** (`leafRegions().first(where: { $0.globalStart == b.textStart })`, plus a fallback that
  refuses a position inside one of the box's own non-primary regions). This is the load-bearing part: a
  caret in the language line otherwise resolved to the code box with a LANGUAGE-relative offset, which
  callers applied to the CODE layout — `insertCodeBlockNewline` spliced a newline into the code at the
  wrong offset. It compiles and reads correctly at every call site. With the guard, every legacy
  `box is CodeBlockBox` branch is inert in the language line **by construction** rather than by each site
  remembering to ask which region it is in. NB the naive `pos >= textStart, pos <= textStart + textLength`
  is NOT equivalent — containers report a degenerate `textStart == nodeStart`, so it would newly match them.
- **`leafRegions()` is DOCUMENT order** (navigation indexes `allLeafRegions()` positionally), so a code
  box's `.first` is now its LANGUAGE line. Every consumer that means "the box's primary text" must use
  `textStart`. `+ComposerSelection`'s flat mapping did not, and flattened a code block to its language,
  dropping the code from the composer axis entirely.
- **A range edit inside the language line routes region-aware.** iOS delivers a backspace there as a RANGE,
  which resolves to no `activeStack`, so the top-level engine returned `.unchanged` — the character was
  selected and never deleted. `applySelectionReplaceOutcome` asks `regionIsOffTheTopLevelEngine(_:)`
  (exhaustive over `TextNodeRef`, no `default`) and routes author AND language through
  `applyLeafReplaceOutcome`.
- **Editing semantics:** Return moves to the code start (a `.Pre` language has no second line — this is
  where it diverges from the trailing author, which splits); Backspace at the start un-makes a wholly-empty
  block or steps out without deleting; inline formats, emoji and links are inert; text services are off in
  BOTH code regions (`caretIsInCodeRegion`), because iOS capitalizes `let` to `Let` and autocorrects
  identifiers. That made `autocapitalizationType` the SEVENTH `UITextInputTraits` member the canvas
  implements — the differential harness censuses that set, so adding one moves those tests. UIKit caches
  traits, so `refreshSelectionUI` reloads them when the caret crosses into or out of a code block.
- **`sameOwningStack` needed its own resolver.** It asked `activeStack` "which box + local" when it only
  wanted "which stack", so once the guard above refused author/language positions, Select-All over a pull
  quote (whose end endpoint lands on the empty author region) stopped toggling. `owningStack(at:)` answers
  the narrower question. This is now the third narrow resolver in the `resolveBox` family the tech-debt
  note above describes — the generalization it asks for is still owed.

**Syntax highlighting is HOST-PROVIDED, because this package cannot see the highlighter.**
`RichTextEditorUIKit` depends only on `RichTextEditorCore`, `AppBundle` and `MosaicLayout`, and must keep
doing so to stay SwiftPM-testable and to keep the Demo app buildable — libprisma lives behind
`TextFormat`/`TelegramCore`. So the editor owns detection, debounce, cache and apply, and the host answers
`(language, text) -> [RichTextSyntaxToken]` through `registerSyntaxHighlighter(_:)`, the same seam pattern
as `registerEmojiViewProvider` / `mapper.formulaRenderer`. Package tests inject a stub, so `swift test`
never needs libprisma. Both hosts answer via `asyncStanaloneSyntaxHighlight`, baking the LIGHT palette —
the palette decision lives host-side, so what the editor shows is what the sent message shows.

- **Highlighting is inert until a language is typed** (an empty one is skipped), and an unknown language
  yields an empty token list that is cached like any other answer, so it is attempted once per
  (language, text) rather than every pass.
- **The pass is debounced ~300ms** from `performEditing` and `setBlocks`, never from a selection change: the
  caret moving through code changes no spec.
- **`CodeBlockBox.applySyntaxHighlight` rebuilds the block's string with the colours baked in**, which is
  lossless HERE ONLY because a code block's runs are plain by construction — no link, emoji, inline-code or
  spoiler attribute lives inside one. It re-assigns `layout.attributedString` only when the result differs
  (the idempotence rule), and drops a token set WHOLE when any range no longer fits the text. Colours never
  reach `Document`: `currentCode()` reads the plain string back.
- **Repaint the BLOCK VIEW, not the canvas.** A code block draws into a pooled `BlockBackingView`, so
  `setNeedsDisplay()` on the canvas leaves its bitmap stale until some unrelated layout pass happens to run
  `syncBlockViews()`. That is why highlighting first appeared only after the caret left the block. The pass
  calls `blockViews[box.id]?.setNeedsDisplay()` and deliberately does NOT call `notifyContentSizeChanged()`
  — colours never change metrics, and firing it would ask the host to re-lay-out on every arrival.
- **A rebuild re-applies from cache SYNCHRONOUSLY.** A theme / quote-style change or an undo restore
  reconstructs every box from the model, which carries no colours, so waiting for the debounced pass showed
  a plain frame — the "text loses highlight when the device changes theme" report. `setBlocks` calls
  `reapplyCachedSyntaxHighlights()` before the new boxes are first laid out.
- **Painting rebuilds the block's text storage**, which would pull the rug from under an IME composition.
  Safe today only because marked text is confined to top-level body paragraphs
  (`isBodyParagraphPosition` requires `box is BlockBox`); if IME support ever reaches code blocks, that
  needs a guard.

Three defects OUTSIDE this package had to be fixed before any of it was visible, all pre-existing and all
silent: `InstantPageBlock(apiBlock:)` hard-coded `language: nil` when decoding `pageBlockPreformatted`, so
every page decoded from the API came back language-less; `generateMessageSyntaxHighlight` passed the raw
language to libprisma, whose grammar lookup is an exact lowercase-keyed map, so `"Swift"` produced zero
tokens; and V2's `layoutCodeBlock` never read the `cachedMessageSyntaxHighlight` its layout context has
always carried. See `docs/instantpage-richtext.md`.

**Floating cursor — hold-spacebar-to-move-cursor (added 2026-06-23, runtime-verified 2026-06-24, `feature/richtext-floating-cursor`, phase 1 of 2).**
The iOS keyboard-as-trackpad gesture is implemented on the canvas (the bare sole `UITextInput`, which own-draws
everything and installs NO `UITextSelectionDisplayInteraction`) via the three optional `UITextInput` methods
`begin`/`update`/`endFloatingCursor` (`DocumentCanvasView+FloatingCursor.swift`). **Two runtime discoveries
corrected the original spec's assumptions** (the spec's relative-delta + hide-steady-caret design did NOT match
how iOS actually drives a bare `UITextInput` — both are wrong; see the spec's "Runtime corrections" addendum):

1. **The `point` is an ABSOLUTE canvas (content) coordinate**, not a relative delta — it already tracks the cursor
   across the whole document. So `update` feeds it straight to `closestGlobalPosition` (no delta, no viewport
   clamp). The clamp in the first cut froze the caret mid-text and couldn't reach the document start.
2. **`begin`/`update` fire fine on the bare `UITextInput` (no `UITextInteraction` needed), BUT during the gesture
   iOS ALSO pushes selection RANGES** (anchored at the gesture-start position) through the **`selectedTextRange`
   setter**; applying them turns the cursor MOVE into a text SELECTION (the headline bug). The setter therefore
   **ignores writes while `floatingCursorActive`** (`DocumentCanvasView+UITextInput`) — the floating handlers own
   the caret. **This is the load-bearing invariant of the feature.**

Visual model (matches iOS): a **bright gliding shadow** (`TransientCaretView`) follows the finger **continuously**
(`moveFloatingCaret(toGlobal:shadowX:)` positions it at the raw `point.x`, clamped to host bounds — only the
*underlying* caret snaps to a grapheme position), while the **steady `CaretView` becomes a dimmed (alpha 0.4)
"landing" indicator** at the snapped position via the `floatingCursorActive` branch in `updateCaretView` (NOT
hidden — the early design hid it, leaving no landing cue). On `end` the shadow fades and the steady caret returns
to full alpha + blink at the landing. Each `update` moves the caret through a **lightweight bracketed path**
(`moveFloatingCaret`) that brackets `inputDelegate.selectionWillChange/DidChange` but **deliberately suppresses
the host scroll-follow** (`onSelectionChange`/`scrollCaretIntoViewIfNeeded`) per-update — the gesture owns
scrolling via a `CADisplayLink` **vertical auto-scroll** driver (mirrors the table-drag auto-scroll, advances the
stored `floatingCursorPoint` by the scroll delta); `onSelectionChange` fires once on `end`. `TransientCaretView`
and the steady caret both host via the extracted `caretHostPlacement(forGlobal:)`/`hostOverlay(_:at:)`, so they
ride table-cell horizontal scroll. Document-wide landing (body/caption/code/table cells). An interrupted gesture
(resign-FR / window-removal) is torn down by `cancelFloatingCursor` (invalidates the self-retaining display link).
**`TransientCaretView` is built generically so phase 2 (text drag-and-drop drop caret via
`UITextCursorDropPositionAnimator`, iOS 17+, a separate cycle) can adopt it as the animator's `cursorView`.**
Status: **runtime-verified in the chat composer** (smooth glide, visible landing caret, reaches both ends, no
stray selection); full SwiftPM suite green (Core 102 + UIKit; incl. `TransientCaretViewTests` + the rewritten
`FloatingCursorTests`) and the full Bazel app build is green. (Per the module convention, the per-phase
design spec/plan are not retained in-tree; this note is the in-tree record.)

**Loupe grow-from-cursor + gliding shadow caret (added 2026-07-06, runtime-verified, squashed to master, `feature/richtext-loupe-grow-cursor`).**
The long-press magnifier (`UITextLoupeSession`) now **animates from the caret** and drags with the floating-cursor
visual. **This is the ONE scoped exception to "no `UITextSelectionDisplayInteraction`":** the loupe's grow
animation IGNORES a bare/own caret view passed as `fromSelectionWidgetView` — device-verified, a bare `UIView`,
a frozen-solid one, AND even a `UITextCursorView`-conforming view all fail (the loupe grows at the *touch*, not
the widget). It only honors a real system `cursorView`, which is owned by a `UITextSelectionDisplayInteraction`.
So `handleLongPress` **creates a FRESH interaction per drag and tears it down on release** (`removeInteraction`),
borrowing `interaction.cursorView` as the widget. **Per-drag lifecycle is load-bearing:** a PERSISTENT interaction
goes stale against the canvas's view virtualization and crashes with a use-after-free in
`-[UITextSelectionDisplayInteraction setActivated:]` (`objc_retain` on a freed selection view) on a SUBSEQUENT
drag after intervening edits (device-log-verified). Its injected chrome (cursor / lollipops / accessory, ~26
views) is corralled in a dedicated `selectionChromeContainer` (returned from the `selectionContainerViewBelowText`
delegate) that the block-view reload loop never frees, and `removeInteraction` clears it on release — no
orphaned-lollipop leak.

**Visual during the drag** (the spacebar floating-cursor look): the **accent** `TransientCaretView` glides at the
raw finger x (unsnapped, `positionLoupeShadow`); OUR own `CaretView` is the desaturated **"shadow"** at the
snapped real-caret position (`RichTextEditorTheme.shadowCursor`, a light **HSL-lightness** gray — NOT HSB
`saturation:0`, which whitens a bright accent; recolored for the drag and restored on `.ended` via
`loupeSavedCaretAccent`); the borrowed system cursor is kept **near-invisible** (`alpha 0.01`, grow anchor only)
so its native blink can't flicker through. On release the widget is **snapped to the final caret**
(`setNeedsSelectionUpdate`+`layoutManagedSubviews`) BEFORE `invalidate()`, so the loupe animates OUT onto the
caret, not the finger (the loupe's `move(to: finger)` had been dragging the widget along). `CaretView`
**conforms to `UITextCursorView`** (`isBlinking`/`resetBlinkAnimation`) so a future non-interaction path could
hand it directly, but the loupe still needs the interaction-owned cursor today.

**The gray shadow shows only once the accent glider diverges from it by ≥ `loupeShadowMinSeparation` (14pt, added
2026-07-06).** While the finger sits on top of the snapped caret the shadow is redundant clutter, so `CaretView` is
hidden until the accent (finger x) and the snapped caret separate (mid-character / between snap points), then it
appears to cue where the caret will land. `positionLoupeShadow` sets `caretView.isHidden` per frame from the pure
`loupeShadowShouldShow(accentX:snappedX:)` (both in the shared overlay-container space); `updateCaretView`'s
`loupeDragActive` branch defaults it VISIBLE each refresh so the terminal `setCaret` (no following
`positionLoupeShadow`) leaves the final caret shown. Guarded by
`SelectionInteractionTests.test_loupeShadowShouldShow_onlyBeyondMinSeparation`.

**The drag reports the selection ONCE, at the final position — not per frame (added 2026-07-06).** Both report
channels are deferred to the drag's end, each by its own "fire once" mechanism:
- **Host report** (`onSelectionChange` → the composer's `onChange`: interface-state selection commit + re-layout).
  `handleLongPress` moves the caret each frame with `setCaret(global:reportSelectionChange:false)`, which
  SUPPRESSES `onSelectionChange`. It fires once on the terminal state: `.ended` re-runs the default `setCaret`
  (reports); `.cancelled`/`.failed` call `onSelectionChange?()` directly so the host isn't left stale.
- **OS input-delegate bracket** (`selectionWillChange/DidChange` → the keyboard's autocorrect/candidate bar).
  Left un-coalesced, a per-frame bracket makes the **keyboard suggestions visibly JUMP** on every move. The drag
  reuses the selection-handle-drag coalescing: `.began` calls `beginCoalescedSelectionDrag()`, `setCaret` now
  skips the bracket while `coalescingSelectionNotifications` is set (mirroring `setSelectionHead`), and the
  terminal `endCoalescedSelectionDrag()` fires exactly ONE bracket for the final caret. (The `selectedTextRange`
  getter stays live throughout; the keyboard only recomputes on a bracket.)

This is the same "report once at the end" model the floating cursor (spacebar-trackpad, `moveFloatingCaret` +
`endFloatingCursor`) uses for the host report, and it's the ONE loupe caret-move exception to the repo-wide
*"any caret-moving op must fire `onSelectionChange`"* invariant. NOTE the loupe goes further than the floating
cursor, which still brackets the input delegate per frame (its keyboard shows no suggestion bar during the
trackpad gesture, so it doesn't churn visibly). Trade-off: the outer-document scroll-follow (bundled into the
composer's `onSelectionChange` closure) is likewise deferred to the drag's end — negligible in the compact
composer; a dedicated per-drag auto-scroll driver (like the floating cursor's) is the follow-up if a tall
full-page editor needs edge auto-scroll during a loupe drag. Guarded by
`SelectionInteractionTests.test_setCaret_withReportSuppressed_defersHostReport_untilTheDragEnds` (host) +
`…test_loupeDrag_coalescesInputDelegate_soKeyboardSuggestionsDoNotChurn` (keyboard).

**Proximity-adaptive long-press delay** (`LocationAdaptiveLongPressGestureRecognizer` — sets `minimumPressDuration`
per-touch in `touchesBegan` before `super`): near-instant (`loupeDelayNearCursor`) when the touch starts within
`loupeNearCursorRadius` of the caret ("grab the cursor"), longer (`loupeDelayFarFromCursor`) otherwise. A literal
`0` is unusable — tap and long-press share touches, so `0` fires the loupe on every quick tap.

**`inputHitTestSlop` (composer, `RichTextEditorChatInputNode`).** The panel's negative slop (a bigger tap target)
is now applied by a `hitTest(_:with:)` override on the node, routing a touch in the slop ring around `editorView`
into the editor's canvas — `ASDisplayNode.hitTest` is forwarded to by `_ASDisplayView` when overridden (with a
re-entrancy guard, so `super.hitTest` is the standard UIView pass). Build-verified only.

The host action bar (12 icon actions + ContextUI context menus) lives in the separate `RichTextAttachmentScreen`
module, not this package. Full session handoff: `~/Documents/RichTextEditor/docs/superpowers/handoffs/2026-06-12-richtext-session-handoff.md`.

**Session updates (2026-06-13 → 06-16, branch `feature/richtext-message-serialization`).** All TDD'd, full
SwiftPM suite green (657 UIKit tests + Core). No runtime/app pass yet; the conversion + `RichTextAttachmentScreen`
+ Demo edits are Bazel/xcodegen (not SwiftPM-compiled) so verified by inspection only. The later items
(edit-menu auto-dismiss, Select-All-image delete, quote affordances, content margins, the parent-driven layout
sweep) extend this block below; the layout sweep also has a spec/plan pair in
`docs/superpowers/{specs,plans}/2026-06-16-richtext-parent-driven-layout*`.
- **Type scale + `Title` removed.** `ParagraphStyleName` is now `heading1, heading2, heading3, body, caption,
  quote` (no `title`; no backwards-compat decode shim — a persisted `"title"` simply fails to decode). Sizes
  (`StyleSheet`, as of 2026-06-13): H1 24 / H2 21 / H3 19 **serif**, Body 17 sans, Caption 15 sans, Quote 17
  sans — **superseded 2026-08-14 by V2 parity, retuned 2026-08-17** (H1 22 / H2 20 / H3 18 / H4 17 / H5 16 /
  H6 15 serif MEDIUM, from `RichTextRenderMetrics`; see the layout-parity note near the top). **`caption`
  is a render-only style** (media-block captions, 15pt) — never offered in the picker, never persists as a
  paragraph style (a caption serializes as the MediaBlock's runs); `MediaBlockBox` lays the caption out as
  `.caption`. Exhaustive `switch ParagraphStyleName` sites (StyleSheet ×2, conversion ×2) all carry `.caption`.
  **Table cells render body/quote at a smaller base — 15pt, not 17 (2026-06-26).** `StyleSheet` gained a
  `bodyBaseSize` (default 17) read by `baseSize(.body/.quote)` and a `static let tableCells` variant (15);
  `AttributedStringMapper.tableCellVariant()` copies a mapper onto it preserving theme/emojiScale. Each
  `TableBlockBox` derives a cell mapper once and builds every cell box with it. To keep edits consistent, a
  box created as a split/merge replacement **inherits its source box's mapper** (`CanvasBlock` now exposes
  `mapper { get }`; the three cell-capable creators — `applyReplaceOutcome` merge, `insertParagraphBreak` split,
  `mergeParagraphsOutcome` — pass `start.box.mapper`/`p.mapper`/`upper.mapper` instead of the canvas mapper), and the
  empty-cell typing path (`typingAttributeDict`'s empty-storage branch) resolves the owning box via
  `activeStack` and uses **its** mapper — so an empty cell's first typed character is 15pt too. Headings keep
  their fixed sizes in cells. (An explicit run `fontSize` still wins; read-back pins the rendered 15pt.)
  **Paired cell-padding mechanism fix.** Cell vertical padding is now an explicit cell metric
  (`TableBlockBox.cellVerticalPadding = 14`) applied at the CELL level (`recompute` content origin +
  row-height math), parallel to the horizontal `cellPadding` (6) — and the cell `BlockStack` carries NO block
  inset (`verticalInsetBase = 0`). Previously the cell's 14pt vertical gap came *incorrectly* from
  `cellPadding` (6) + the document's 8pt inter-block inset (`BlockBox.defaultVerticalInset`) leaking into the
  cell stack; that coupling tied cell padding to document-body block spacing (font-independent), so the
  smaller 15pt text looked under-filled / vertically centered. The **visual is unchanged from before the font
  change** (14pt top/bottom), but it's now decoupled from `defaultVerticalInset` and lives in one cell metric.
- **`DocumentMetadata` removed entirely** → `Document { schemaVersion, blocks }` (it had become a vestigial
  single-`title` wrapper that nothing read; the doc's title is a `.heading1` block). `DocumentCodec` dropped
  its now-dead ISO-8601 date strategy.
- **First-responder callbacks** on the façade: `onBecameFirstResponder` / `onResignedFirstResponder`, each
  fires **once on the genuine transition** (the canvas `becomeFirstResponder()`/`resignFirstResponder()`
  capture `wasFirstResponder` before `super`), so a repeat tap while already focused doesn't re-fire.
- **Taps land anywhere in the unobscured editor**, not only on text. `performLayout` floors the canvas height
  at the **visible** viewport (`size.height − contentInset.top − bottom`, read from the just-applied insets),
  so the canvas (which owns the tap/long-press/loupe recognizers) covers the empty area below a short doc;
  `closestGlobalPosition` maps such taps to the nearest position (doc end), matching UITextView. Flooring at
  the *visible* (not full-frame) height keeps `scrollView.contentSize == visible area` for a short doc → zero
  scrollable range (no phantom bounce over the inset bands) and it re-flows when insets change. `update`
  returns the real **content** height (unchanged contract).
- **`contentMargins` (`UIEdgeInsets`) is distinct from the scroll insets.** Insets are non-interactable bands
  the content scrolls UNDER (nav bar / keyboard / input panel, applied via `update(size:insets:)` →
  `scrollView.contentInset`). Margins are interior padding that is PART of the content: on the canvas, the text
  lays out inset by them — `root.layout(origin: (pageMargin + margins.left, margins.top), …)`, content width
  `= bounds.width − (pageMargin + left) − (pageMargin + right)` (additive to the built-in 16pt `pageMargin`),
  and `intrinsicContentSize.height` grows by `top + bottom`. Because the margin sits INSIDE the canvas, its
  area still hit-tests (a tap there places the caret at the nearest position) — unlike an inset. Both
  `setParagraphsWidthIfNeeded` and `layoutSubviews` derive width from the shared `contentWidth(forWidth:)`
  helper so they can't drift. **Applied via `RichTextEditorView.update(size:insets:contentMargins: = .zero)`**,
  alongside `insets` — NOT a side-effecting property. General rule (project convention): any setting that
  triggers re-load / re-layout / re-draw belongs in `update`, not a property whose setter hides a layout pass.
  `contentMargins` is a **plain stored value** on the canvas (read by `layoutContent()` / `intrinsicContentSize`,
  persisted across system passes); the setter does NOT `setNeedsLayout()` and does NOT fire
  `onContentSizeChange`/`onChange`. Instead the `update` that sets it re-runs `performLayout`, which lays the
  canvas out **explicitly** via `canvas.layoutContent()` (the body of `layoutSubviews`, factored out) rather
  than `layoutIfNeeded()` — so the new value takes effect even when the canvas frame is unchanged (e.g. a short
  doc whose height is floored to the viewport, where only top/bottom margins changed). A test asserts
  `update(...contentMargins:)` does not synchronously fire `onChange`.

  **Layout convention.** The parent drives layout explicitly (`performLayout` → `canvas.layoutContent()`)
  and a view never `setNeedsLayout()`s itself for a content-height change — it calls `notifyContentSizeChanged()`
  (fires `onContentSizeChange` → the host's `onChange`, which re-calls `update`). Every height-affecting path
  follows this: `editing { }`, the IME marked-text commit/update, `setBlocks`, and the undo block call
  `notifyContentSizeChanged()` only; the façade's `onContentSizeChange` is a **pure relay** (`onChange` only),
  and where the façade needs fresh geometry synchronously it lays out explicitly — `scrollCaretIntoView` and
  the `document` setter call `performLayout(size: bounds.size)`. The old `invalidateIntrinsicContentSize()`
  override is gone (its only job was firing `onContentSizeChange`, and it carried an implicit UIKit layout
  schedule). **Canvas-direct tests** that read post-edit geometry install `simulateParentLayout()` (a test-only
  hook that re-lays-out on the content-size notification, simulating the real parent) instead of relying on the
  UIKit `needsLayout` flag. **Out of scope** (do NOT affect content height, kept as UIKit-internal mechanism):
  `setNeedsDisplay` (repaint), `syncSpoilers`' reveal re-layout, and the parent→child `view.setNeedsLayout()` /
  `tv.layoutIfNeeded()` on block/table backing views.
- **`MediaBlock` is a multi-media container** (added 2026-07-08): `items: [MediaItem]` holds one or more
  photos/videos with one shared caption (additive/back-compat — a convenience single-item initializer +
  back-compat Codable decode keep every existing call site and persisted document unchanged). It stays
  **one atom** in the position model regardless of item count (`DocumentTree` still emits one `.mediaAtom`
  per block), so `nodeSize`/`textStart`/caret/select-all/covered-delete below are unaffected —
  multiplicity lives only in `items` and the mosaic render (`RichTextEditorMediaView`'s `CLAUDE.md`;
  send/edit round-trip in `docs/richtext-composer.md` §4 and `docs/instantpage-richtext.md`).
- **`MediaItem.isSpoiler` — per-item media spoiler** (added 2026-07-08): optional-Codable `Bool` (absent ⇒
  `false`, back-compat). Toggled by `DocumentCanvasView.toggleMediaSpoiler(blockID:itemIndex:)` (in-place
  `MediaBlockBox` rebuild, ONE undo step — same mechanism as `deleteMediaItem`); `itemIndex` in range flips
  that one cell, nil/out-of-range flips the whole block to `!first.isSpoiler`. Surfaced via the façade
  `RichTextEditorView.toggleMediaSpoiler(itemIndex:)` → `toggleSelectedMediaSpoiler` (reads `imageSelection`).
  **Authoring:** the single-media tap-select edit menu (`imageSelectionMenu` gains a "Spoiler" `UIAction`)
  and, for albums, the per-cell "•••" menu (via `MediaControlRequest.isSpoiler`/`toggleSpoiler`, host-built).
  **In-editor render is a NON-revealable cover:** `MediaProviderItem.isSpoiler` is folded into the
  `syncMediaItemViews` items-signature (so a toggle re-provides the cell), and `MediaItemNodeView`
  (`RichTextEditorMediaView`) hosts a `MediaDustNode` per spoiler cell with `revealOnTap = false`,
  non-interactive so taps still select. The revealable message-side render + wire/persistence round-trip are
  in `docs/instantpage-richtext.md` + `docs/richtext-composer.md` §4. Design/plan:
  `docs/superpowers/{specs,plans}/2026-07-08-richtext-media-spoiler*`.
- **Backspace targeting a media block replaces it with an empty body paragraph IN PLACE** (2026-06-27, supersedes
  the older per-case media-backspace rules). `replaceMediaWithEmptyParagraphOutcome(at:)` removes the media block and
  drops a fresh empty `.body` paragraph in its slot, caret there — NOT the old delete-and-merge-into-the-block-above
  (`deleteImageBox`) nor the old "act on the previous paragraph" gap behavior. It unifies every way a Backspace
  "lands on" a media block, reached on FOUR paths in `deleteBackward` / `applySelectionReplaceOutcome`:
  - **collapsed caret at the media's leading gap** (`mediaBox(atGap: head)` branch) — **NOTE: narrowed
    2026-07-21** to the TAP-SELECTED case only (`imageSelection == img.id`); a plain non-selected gap caret now
    acts on the PREVIOUS block instead (see the "Backspace at a media block's leading gap" note below);
  - **collapsed caret at the start of the caption** (`pos.box is MediaBlockBox, pos.local == 0`) — empty OR
    non-empty caption (the caption text is **discarded**);
  - **a selection whose bounds EXACTLY equal a media node's span** (`from == nodeStart && to == textStart +
    textLength`) in `applySelectionReplaceOutcome` (deliberate select-the-image-then-delete);
  - **the iOS object-replacement RANGE of a tap-selected media — the LOAD-BEARING, compiler-invisible case**
    (device-log-verified). Tapping a media runs `selectImage` (collapsed caret at the gap, `imageSelection` set),
    but the `selectedTextRange` setter clears `imageSelection` and, right before Backspace, **iOS OVERRIDES the
    selection to a RANGE whose head sits at the media's gap yet ANCHORS IN THE PRECEDING BLOCK** — iOS's
    object-replacement geometry is offset from our position model, so the range does NOT cover the media node. A
    naive `selFrom != selTo` delete erases the *preceding* text and KEEPS the media ("cursor moves into the
    paragraph above"). So the setter stashes the just-cleared image into **`imageObjectDeletePending`** (a
    `BlockID?` on the canvas), and `deleteBackward` consumes it at the top — when the selection touches that
    media's gap — to replace the media. `insertText` and any non-matching `deleteBackward` clear the flag so it
    can't go stale. **Lesson (reinforced): a bare custom `UITextInput` receives OS-driven `selectedTextRange`
    writes that turn a tap into an *offset* object-replacement range — unit tests that set the caret/selection
    directly miss it; capture the real sequence from the device (`NSLog` + `xcrun simctl spawn <udid> log
    stream`), don't hypothesise twice.**

  A media delete never leaves a zero-block document (a lone-block replace yields the empty paragraph). The image
  edit-menu **"Delete"** still fully REMOVES the block — only Backspace was respecified. (`deleteBlock(at:parkingCaretAtGapOf:)`
  was removed with its sole caller.) **Name corrected 2026-08-21 (Task 36c), behaviour VERIFIED not inherited:**
  this said `deleteImageBox`, which no longer exists under that spelling and was not this path's callee anyway.
  The menu's Delete closure is `+Media.swift`'s `MediaControlRequest.delete` → `deleteMediaBlock(id:)`
  (whole block) or `deleteMediaItem(blockID:itemIndex:)` (one album cell). `deleteImageBoxOutcome`'s own doc
  comment in `+Editing.swift` is where this whole class of mis-attribution is described — including why its
  count is deliberately not written down anywhere. Do not restate it here.

**Backspace at a media block's leading gap (2026-07-21).** A plain, NON-tap-selected caret at a media
block's leading gap (`nodeStart`, the slot to the LEFT of the image) now acts on the PREVIOUS block
rather than the media: it deletes the previous block's last grapheme (caret moves into that block), or,
if the previous block is empty, deletes the empty block (caret stays at the image's shifted gap); a
non-text previous atom (table / block quote whose boundary isn't renderable) is a safe no-op with the
caret left at the gap; a LEADING image (no previous block) is a no-op. A TAP-SELECTED image (the tint;
`imageSelection == img.id`, or the `imageObjectDeletePending` range path) still replaces the media with
an empty paragraph on Backspace, as does Backspace at CAPTION start (offset 0). Both the collapsed-caret
gap Backspace and the OS object-replacement RANGE `[prevEnd … gap]` (collapsed to a gap caret before the
gap branch) route through the same logic. This keys on `mediaBox(atGap:)`, so it applies to EVERY
`MediaBlockBox` including caption-less **audio** (`MediaKind.audio`) — consistent with images; audio stays
deletable via tap-select + Backspace through the `imageSelection == img.id` branch. See `deleteBackward`
(`DocumentCanvasView+UITextInput.swift`) and `CanvasImageEditTests` (`test_backspaceAtGap_*`).

- **Backspace at the start of a paragraph AFTER a non-text block deletes the empty paragraph, never the block**
  (`deleteBackward`, the mirror of the leading-gap rule above). A collapsed caret at the start (`local == 0`) of
  a paragraph whose previous block is a non-text **atom** — an image (`MediaBlockBox`), a table (`TableBlockBox`),
  or a code block (`CodeBlockBox`), unified via `isNonParagraphAtom(_:)` — must NOT delete that block (you can't
  merge text into it): an **empty** paragraph is removed (`removeBlockOutcome(at:parkingCaretAt:)`, so *"deleting the
  last paragraph" is always possible*), a **non-empty** one is kept; either way the caret steps back to the
  block's nearest text slot via `prevTextPosition` (an image's caption end, a table's last cell end, a code
  block's end) — never the block's degenerate node-start boundary. Previously the image branch called
  `deleteImageBox(at: pos.index - 1)` and silently destroyed the image; the table branch moved the caret but
  *kept* the empty paragraph (undeletable); the code branch left the empty paragraph in place. Text blocks
  (body/heading/quote/list paragraphs) still take the normal merge path below. (Select All + backspace still
  removes a covered image — that goes through `applyReplaceOutcome`, below.)
- **An audio media block (`MediaKind.audio`) is a CAPTION-LESS atom** (2026-06-27) — unlike image/video/location it
  has **no caption** (not rendered, editable, or in the position model). `DocumentTree` emits `mediaBlock([mediaAtom])`
  (nodeSize 3, no caption paragraph), and `MediaBlockBox` is **dual-moded on `kind == .audio`** — `textLayout` →
  `emptyLayout`, `textLength 0`, `nodeSize 3`, `textStart == nodeStart`, `leafRegions() == []` (the FIRST block with
  zero leaf text regions — the caret/nav/selection machinery routes media via `mediaBox(atGap:)`/`isGapPosition`, not
  caption regions, so an empty `leafRegions` is tolerated), `height == verticalInset + audioRowHeight + verticalInset`,
  `closestPosition → nodeStart`, `currentBlock()` caption `[]` (an incoming caption is dropped), and no caption
  draw/placeholder. The non-audio (captioned) path is byte-unchanged. `insertMedia(kind: .audio)` lands the caret in a
  **following body paragraph** (created if the audio is last / followed by a non-paragraph atom) since there's no
  caption to land in. The Select-All / covered-range delete checks (`endpointFullyCovered`, the exact-node-span
  backspace) route through `coverableContentEnd(_:)` — audio → `nodeStart + 1` (the atom span), else
  `textStart + textLength` — because audio's `textStart + textLength` collapses to `nodeStart`. Backspace targeting
  audio still replaces it with an empty paragraph via the gap path (below); the caption-start branch never fires
  (no caption position exists).

  **Generalised to documents (2026-07-31).** The predicate is now `MediaKind.isCaptionless` (`.audio ||
  .document`), mirrored by `MediaBlock.isCaptionless` / `MediaBlockBox.isCaptionless`; every former `isAudio`
  branch above — plus `DocumentTree` and the three `DocumentCanvasView+Editing` sites (`coverableContentEnd`,
  the media-caption Enter guard, `insertMedia`'s caret landing) — keys on it. The ONE kind-specific value is
  the row height: `audioRowHeight` 44 vs `documentRowHeight` **52**, selected by `MediaBlockBox.rowHeight`.
  **Both must equal the matching V2 frame height in `InstantPageV2Layout`** (the box reserves the slot, the
  renderer fills it), or the editor preview stops matching the sent bubble. The narrower `isAudio` accessor
  survives on BOTH `MediaBlock` and `MediaBlockBox` for callers that mean audio *specifically* (several tests
  assert audio identity — `isCaptionless` would silently also accept a document). Gap-caret Backspace,
  tap-select delete, vertical nav and Select-All coverage needed no change at all: they key on
  `mediaBox(atGap:)`, not the kind. Round-trip + recipient rendering: `docs/richtext-composer.md` §4 and
  `docs/instantpage-richtext.md`.
- **Inserting a table or image on an EMPTY paragraph replaces it; mid-paragraph it splits** (`insertTable`,
  `insertMedia`). Both share one branch order: an **empty** caret paragraph (`pos.box as? BlockBox` with
  `textLength == 0`) is **replaced** by the new block (`replaceSubrange(pos.index...pos.index)`) so no stray
  empty paragraph is left beside it — even between content (`A | empty | B` → `A | block | B`); a caret strictly
  **interior** to a non-empty paragraph (`0 < local < textLength`) **splits** it into upper + block + lower;
  caret at the **start** of a non-empty paragraph inserts the block **before** it, at the **end** inserts
  **after**. The empty-replace check must run FIRST (an empty paragraph is both `local == 0` and
  `local == textLength`, so it would otherwise fall into the insert-before branch and survive). Replacing the
  document's only block is fine — a lone `[table]`/`[image]` is a valid document (the caret lands in the first
  cell / caption; tap-below re-adds a paragraph). The empty-replace only targets `BlockBox` paragraphs, so it
  never replaces an image caption / code block the caret happens to sit in.
- **Select All + backspace removes a covered image, even a leading/trailing one** (`applyReplaceOutcome` cross-block).
  A media endpoint is now dropped when the selection covers its **whole node** (leading gap + entire caption:
  `lo <= box.nodeStart && hi >= box.textStart + box.textLength`), so the merge path's `replaceSubrange(start...
  end)` clears it like a covered MIDDLE image already was. A **partially**-covered media endpoint (selection
  starts/ends partway through a caption) still truncates-and-keeps (the Phase 2c behavior). Previously only
  middle images were dropped; an image at a selection endpoint (which Select All always makes of the first/last
  block) was truncate-kept, so CMD+A then Backspace left the image behind. The paragraph↔paragraph merge is the
  same path generalized: a fully-covered media endpoint contributes no runs, and the merged paragraph inherits
  the start block's style (else the end's, else a fresh body paragraph when both endpoints were media).
- **Quote-block escape/delete affordances** (a `quote` is a `BlockBox` with `style == .quote`). Three behaviors,
  each top-level only (an in-table quote keeps the cell behaviors): **(A)** Backspace in an **empty** quote
  un-quotes it (`style = .body; restyle`) instead of doing nothing — an empty quote, especially the document's
  FIRST block, otherwise matched no `deleteBackward` branch and was undeletable. Mirrors empty-list-item Return.
  A non-empty quote's backspace still just deletes a char. **(B)** Tapping in the empty area **below the
  document's last block** (`point.y > boxes.last.frame.maxY`) inserts a new empty body paragraph after it
  (`insertEmptyBodyParagraph(at:)`) — so you can always start a normal paragraph below the final block, whatever
  its type (image / table / quote / code / non-empty paragraph). **The one exception:** when the last block is
  ALREADY an empty body paragraph, the tap is let through to the normal caret-placement path (no redundant empty
  is stacked). This started as a quote/code-only escape hatch and was generalized 2026-06-25 (paired with the
  *"deleting the last paragraph"* backspace rule above, so a tapped-in trailing paragraph is also removable).
  **Gated on `tapBelowAddsTrailingParagraph` (added 2026-06-28, default `true`):** the article editor keeps it;
  the chat composer sets it `false` (a compact field has no empty area below the content to grow into) — see the
  compact-host knob list above.
  **(C)** **Double-return** (Enter on an empty line inside a quote or code block — added 2026-06-30, replacing
  the earlier Shift+Return) EXITS the block with a new empty body paragraph (caret there): the run's **last /
  wholly-empty** line → **after**, its **first** line → **before**, a wholly-empty block → un-quote / un-code;
  a MIDDLE empty line splits normally (no exit). For a quote *run*, first/last = the first/last consecutive
  `.quote` paragraph (`emptyQuoteIsRunEdge` → `exitQuoteToBodyParagraph`, which replaces the edge empty quote
  line with a body so the before/after side follows from which edge it sat on). **Reachability (2026-06-30):**
  after the first Enter at the start of a block the caret lands on the content line (past the new break), so the
  *before*-exit also fires from the start of content with an empty line directly above — code via the local-1
  branch of `codeBlockDoubleReturnExit`, quotes via `quoteDoubleReturnExitIndex` (caret at content start with an
  empty quote line above) — so **two newlines at the beginning** break out *above* instead of stacking blank
  lines. The old Shift+Return path (its `UIKeyCommand` + `performShiftReturn` + `caretIsOnFirstLine`) was removed.
- **"Type something…" placeholder shows only on the document's LAST block** (`BlockBox.isLastBlock`, stamped
  in `stampListMarkers` like `isTopLevelBlock`); an empty body paragraph elsewhere shows no placeholder (list
  hints are unaffected). An empty non-last paragraph still reserves its line + caret — only the hint is gone.
- **Selection highlight is UITextView-style** via a NEW draw-only `DocumentCanvasView.selectionHighlightRects`
  + `BlockLayout.selectionFillRects(start:end:fillTrailingLine:)` (used ONLY by `drawNonTableSelectionHighlight`).
  A line covered to its end fills to the container trailing edge; a line covered from its beginning fills to
  the leading edge (x=0) — so an indented quote/list fills full-width on covered lines (first line included,
  via `start == 0`) instead of hugging the indent; an empty line spanned by the selection gets a synthesized
  full-width row. The glyph-hugging **`selectionRects` is unchanged** — it still feeds the OS witness,
  edit-menu position, spoiler-dust geometry, and marked-text underline. (Body/caption only; table-cell
  selection still uses glyph-hugging rects — a deferred consistency follow-up.)
- **Edit menu auto-dismisses on any text/selection change** (native UITextView behavior). The canvas owns its
  own `UIEditMenuInteraction`, which — once presented — does NOT self-dismiss on a selection change (it just
  repositions via `targetRectFor`), so the canvas must call `dismissMenu()` itself. A new
  `dismissEditMenuForSelectionOrTextChange()` is called from the three selection setters (`setCaret` /
  `setSelectionHead` / `setSelectionAnchor`), the UITextInput **`selectedTextRange` setter** (the system path:
  keyboard cursor-drag / autocorrect / predictive text), and the `editing { }` text-mutation wrapper — so
  typing, deleting, programmatic + gesture + system caret moves, and boundary-move backspaces all close the menu.
  The dismiss is **UNCONDITIONAL — NOT gated on `editMenuVisible`**: the system flips that flag to false on a
  touch-down BEFORE the gesture's setter runs, so gating on it skipped the dismiss exactly when the user moved
  the cursor (the bug); `dismissMenu()` on a non-presented interaction is a harmless no-op. The
  present-after-change gesture flows — Select / Select All / double-/triple-tap / handle-drag `.ended` /
  long-press `.ended` — are unaffected because they change the selection via `applySelection` (deliberately
  NOT a dismiss point) and call `presentEditMenu()` AFTER any setter. `applySelection` stays out of the hook
  for exactly this reason.

**Compiler-invisible invariant (block-view repaint gate).** `bindRealizedView` forces a repaint when the box
**instance** bound to a realized view changes (`view.box !== box`), in addition to the `renderSignature` gate.
A structural edit (Enter-split / Backspace-merge) keeps a surviving block's `BlockID` but swaps its `BlockBox`
for a brand-new one whose fresh `BlockLayout` resets `renderVersion` to 0 — and `renderVersion` is per-instance,
so comparing it across the replacement is meaningless (a same-height/style upper half collided with the old
signature and skipped the repaint, leaving the pre-split full-text bitmap). The lower half always gets a new
`BlockID` → fresh view → always repaints, which is why only the surviving (upper) half went stale.

**The block model.** The canvas holds a `[CanvasBlock]`; conformers are `BlockBox` (paragraph),
`ImageBlockBox` (image + a first-class caption text region), and `TableBlockBox` (grid of `[[BlockStack]]`
cells). A `BlockStack` is a vertical run of blocks that backs both the document root **and each table
cell** (so the same split/merge/edit engine serves top-level and in-cell). `leafRegions()` /
`allLeafRegions()` is the recursion workhorse — selection, caret, text, and draw all iterate it,
recursing into cells.

**`+UITextInput` compile gotcha.** Any `UITextInputStringTokenizer(textInput: self)` /
`inputDelegate?.…change(self)` needs the `UITextInput` conformance to type-check, so the view class and
its `+UITextInput` extension are co-dependent and land together. Remember `import RichTextEditorCore` in
UIKit files.

## RTL / writing direction (added 2026-06-28)

RTL paragraphs (Arabic/Hebrew/…) lay out per-paragraph, **auto-detected by default**, with a persisted
**whole-document override**. Auto-detected direction is **render-only**; only the override persists.

- **Model.** `TextAlignment` gained `.natural` (leading) and it is the **default** for new paragraphs (absolute
  `.left/.center/.right/.justified` stay explicit overrides). `Document.layoutDirection`
  (`.auto/.leftToRight/.rightToLeft`, default `.auto`) is the override (Core; `DocumentCodec` defaulted decode →
  `.auto`). Both pure-Foundation; the Core→UIKit `NSWritingDirection` mapping is UIKit-side.
- **Detection.** `BlockLayoutEngine.baseDirection(atOffset:)` — one protocol-extension default impl over the
  engine's `attributedString` using `CTRunGetStatus(firstRun).contains(.rightToLeft)` (the same first-run
  heuristic as `TextNode`/`InstantPageV2Layout`, so the editor agrees with how the sent message renders). Both
  engines inherit it; nil on empty.
- **Resolution + reporting** (`DocumentCanvasView+WritingDirection.swift`): `resolvedDirection(forGlobal:)` =
  forced override → content detection → `typingWritingDirection`; `typingWritingDirection` = forced → keyboard
  language (`Locale.characterDirection`) → app `effectiveUserInterfaceLayoutDirection`. `applyWritingDirectionOverride`
  sets `layoutDirectionModel` + `mapper.baseWritingDirection` (`.auto`→`.natural`). `baseWritingDirection(for:in:)`
  returns the resolved direction; **`setBaseWritingDirection` is a deliberate no-op** — the whole-document override
  is the single manual control (per-range UIKit writes are ignored).
- **Layout.** `StyleSheet.paragraphStyle(…baseWritingDirection:)` sets `ps.baseWritingDirection` (threaded via
  `AttributedStringMapper.baseWritingDirection`; 11 call sites). `selectionFillRects(…isRTL:)` flips the
  leading/trailing physical edge for RTL lines (both engines; `isRTL:false` is byte-identical to the old LTR math).
- **Empty-paragraph caret** follows `typingWritingDirection`: `refreshEmptyBoxWritingDirections()` sets
  `BlockBox.writingDirectionOverride` on empty top-level boxes (all modes), whose `didSet` pushes
  `BlockLayoutEngine.emptyTextCaretDirection`; both engines' `caretRect(atOffset:)` return `x ≈ containerWidth-2`
  for empty + `.rightToLeft` (LTR/non-empty unchanged). Refreshed from `reload`, `becomeFirstResponder`,
  **`UITextInputMode.currentInputModeDidChangeNotification`** (so the caret re-flips live on a keyboard/globe-key
  change or first keyboard appearance), **and after every edit (the `editing {}` wrapper, added 2026-06-29)** —
  a structural edit can CREATE an empty paragraph (Enter for a new line) or EMPTY one (delete its last char),
  and without re-deriving the hint the new RTL line kept its caret on the LEFT until the next reload/refocus
  (the reported "empty line cursor on the left" bug). The in-`editing` call is empty-box-only work (`restyle`
  no-ops on empty storage) and the `writingDirectionOverride != desired` guard makes it a cheap no-op when no
  box changed emptiness. Regression-guarded by `RTLEmptyLineCaretTests`.
- **LOAD-BEARING (TK2) — the non-empty caret uses the `.selection` text segment, NOT `.standard`** (2026-06-29,
  `BlockLayout.caretRect(atOffset:)`). For an RTL paragraph the `.standard` segment reports the caret x in a
  non-right-aligned coordinate (text measured from a left origin), so it sits left of the glyphs by the line's
  right-alignment displacement and — the headline symptom — **FREEZES the end-of-text caret on a wrapped RTL line**
  (it doesn't track the text growing leftward as you type past the first line). `.selection` is the glyph-accurate
  geometry the selection wash already trusts (`selectionRects`/`selectionFillRects`); for a zero-width (caret)
  range it returns a zero-width segment at the true insertion point. **LTR is byte-identical** (the two segment
  types agree there), so this only moves the RTL caret. Regression-guarded by `RTLCaretTrackingTests` (caret tracks
  leftward while typing on line 2; caret-at-0 sits at the container right edge = the rendered glyph edge; interior
  caret sits on the glyph boundary). **`BlockLayoutTK1` (iOS 13–15) got the matching fix (2026-06-29):** its
  `caretRect` placed the caret at the glyph's LTR pen origin (`location.x`) for every offset and the last glyph's
  INK right edge at end-of-text — both wrong for RTL (the caret sat a glyph off and the end caret overshot the
  container / jumped on trailing spaces). It now places the caret on the **direction-correct edge of the glyph's
  ADVANCE (enclosing) box** — leading edge before a char (`minX` LTR / `maxX` RTL), trailing edge at end
  (`maxX` LTR / `minX` RTL). Direction comes from `resolvedCaretDirection()` (forced override baked in the
  paragraph style; `.natural` → `baseDirection` content detection), cached per `renderVersion` since
  `closestOffset` calls `caretRect` per offset. `TK1RTLCaretTests` pins TK1 to TK2 at every offset (RTL + LTR).
  Limitation (shared with TK2's first-run heuristic): a paragraph mixing an embedded opposite-direction run is
  positioned by its base direction. The running app uses TK2 on iOS 16+; TK1 is the iOS 13–15 / `forceTextKit1` path.
- **Façade + host.** `RichTextEditorView.layoutDirectionOverride` (modeled like `theme`; round-trips through
  `document`). `RichTextAttachmentScreen` has an Auto/LTR/RTL action-bar control; the chat composer relies on
  auto-detect (no manual toggle this round).
- **LOAD-BEARING — font FAMILY is display-only and must NOT round-trip.** `NSTextStorage` font-fixing substitutes a
  script font into a run's `.font` **in storage** when the style font can't render the glyphs (Arabic/Hebrew/CJK).
  `characterAttributes(from:)` must therefore **not** capture `fontFamily` from the rendered font — it once did, so
  the substituted family round-tripped and the font visibly changed on a backspace **merge** (`mergeParagraphsOutcome` →
  `currentParagraph()`). Font **size** IS still pinned on read-back (the 15pt table-cell round-trip needs it);
  bold/italic round-trip via font traits; forward `font(for:)` still honors an explicit import-set `fontFamily`.
- **LOAD-BEARING — bold is a user-intent MARKER (`.rtBold`), not the rendered trait (2026-06-29).** The iOS
  **"Bold Text" accessibility setting** stamps `.traitBold` onto the script font TextKit substitutes for Arabic/
  Hebrew/CJK (verified: under the setting `systemFont` itself stays non-bold, so Latin is fine, but the
  substituted `.SF Arabic` is `.traitBold` whether or not the user bolded — the rendered font alone can't tell
  user-bold from ambient-bold). So model bold rides a private render-only `NSAttributedString.Key` **`.rtBold`**
  (the `rtInlineCode`/`rtSpoiler` precedent): set by the forward mapper (`attributes(for:)`) + `toggleBold`, read
  by `characterAttributes` + `rangeIsBold` — decoupling model bold from the ambiguous font trait. **Marker-less**
  storage (e.g. an RTF-imported `NSAttributedString`) falls back to the **ambient-stripped** `.traitBold`
  (`boldIsAmbient`: re-substitute the non-bold style base for the run's `text` via `CTFontCreateForString` — which
  matches TextKit's fixing — and if THAT is also bold, drop `ca.bold`; `runs(from:)` passes the run text). Never
  persisted to the Core model (read back to `CharacterAttributes.bold`). Without this, backspace-merging an Arabic
  line under Bold Text baked `bold=true` into the model ("the whole previous line becomes bold") AND the toolbar
  toggle couldn't apply persistent bold to a substituted script (it read the ambient trait, so the first tap
  *removed* bold). Guarded by `RTLBoldReadbackTests`. **Limitation:** under Bold Text the OS erases the
  user-vs-ambient distinction in the *rendered* font, so a bold toggle on a substituted script may not visibly
  change on-screen — the *model* is correct (what a sent message carries).
- **Deferred:** gutter-ornament mirroring (list markers / quote bar / checklist / indents to the right gutter),
  table-column direction, a composer override UI, and mapping the override → rich-message `InstantPage.rtl`.

## Text checking — native `UITextCheckingController` engine (rewritten 2026-07-14; supersedes the public-`UITextChecker` pass)

Spelling + **grammar** underlines + tap-to-fix + **autocorrect-revert**, driven by iOS's **private**
`UITextCheckingController` hosted with the **canvas as its client**, with our **own-drawn** underline. This
**replaced** the earlier public-`UITextChecker` pass (2026-07-12): that engine (`SpellChecking`/
`UITextCheckerAdapter`/`runSpellCheckPass`/`scheduleSpellCheck`/`resolveSpellLanguage`) is **deleted**; the
rendering, `spellResults` store, and tap-to-fix menu are **reused**. Default **on**
(`RichTextEditorView.isSpellCheckingEnabled`, gates `spellCheckingType`).

**⚠️ SHIPS PRIVATE API IN RELEASE, by owner decision.** `UITextCheckingController` is resolved via
`NSClassFromString` — App Store Guideline **2.5.1** risk (a static binary scan for the private class/selector
*strings* can bounce the whole app submission). Mitigation: every private symbol WE **send** (the class name, the
selectors we call — `initWithClient:`/`preheatTextChecker`/`checkSpellingForWordInRange:`/
`checkGrammarForSentenceInRange:onPause:`/`invalidate` — and the `NSTextAlternatives*` attribute keys + KVC
accessors) is **obfuscated** (XOR-0x5A byte arrays decoded at runtime, `ObfuscatedStrings` in
`NativeTextChecking.swift`). **No fallback** — if the class won't resolve (future iOS), checking is simply off.
All private-API *dispatch* is **confined to `NativeTextChecking.swift`**. **Residual, unavoidable plaintext:** the
private `UITextChecking` **client-protocol** selectors the controller **calls back on us** —
`@objc(replaceRange:withAnnotatedString:relativeReplacementRange:)` / `@objc(removeAnnotation:forRange:)` /
`@objc(annotatedSubstringForRange:)` / `validAnnotations` in `DocumentCanvasView+NativeTextCheckingClient.swift`
— MUST keep their exact fixed selector names (the controller messages them by name), so they land in the binary's
`__objc_methname` as plaintext and can't be obfuscated on a Swift `@objc` method. So the obfuscation covers the
*sent* surface, not the *vended* client selectors; a thorough scanner could still recognize the client-protocol
conformance. (`smart*Type` are public `UITextInputTraits`; `nativeTextRangeForGlobalLocation:length:` is our own.)

**RE + driving model (the plan's original driving was WRONG — verified live via disassembly + a sim probe):**
- The controller's `didChange*`/`consider*`/`inserted*` **notify methods are no-op stubs** on modern iOS
  (`considerTextCheckingForRange:` = bare `ret`). Real driving is **synchronous per-word
  `checkSpellingForWordInRange:`** (`NativeTextChecker.checkSpellingForWord`) + per-sentence
  `checkGrammarForSentenceInRange:onPause:`, from `driveNativeChecking()` — word/sentence-enumerated via
  `NSString.enumerateSubstrings(.byWords/.bySentences)`, debounced ~0.35s, rebuilding each region's flags.
- `-textChecker` is **lazy + async** (`_initWithAsynchronousLoading:1`, nil until `_doneLoading`) → `preheat()`
  then let the runloop spin.
- **Bridging (LOAD-BEARING):** the controller reads text via the canvas's public `UITextInput` methods, but
  driving needs a `UITextRange` from a global offset. `perform(_:with:with:)` would box the scalar offset as a
  pointer (garbage), and `positionFromPosition:offset:` is relative to `beginningOfDocument` (global **1** on this
  1-based axis → off-by-one). Fixed by a canvas converter `nativeTextRangeForGlobalLocation:length:` (wraps
  `DocumentTextPosition` directly) called through an **IMP cast** (`@convention(c)`).

**Delivery + translation.** The controller flags a range by calling back the client's
`replaceRange:withAnnotatedString:relativeReplacementRange:` with an `NSTextAlternativesDisplayStyle` attribute
(and `NSTextAlternatives` for a correction), and `removeAnnotation:forRange:` to clear. `nativeReplace` translates
the global `DocumentTextRange` → region-local (`clampedSpellRegionLocal`, shared with the stash — **clamps to the
region**, since a grammar range can span a boundary and overrun `enumerateAttributes`) → `spellResults[BlockID]`
(now `[(range, style)]`). **Style** (`SpellStyle` .spelling/.grammar/.correction) from `style(from:)`: alternatives
present ⇒ `.correction`; `NSTextAlternativesDisplayStyle == 2` (live-observed) ⇒ `.spelling`; else ⇒ `.grammar`.
- **Style-aware render:** `drawSpellingUnderlines`/`drawCellSpelling` group flags by style and stroke each with its
  themed color — `misspellingUnderline` (red) / `grammarUnderline` (green) / `correctionUnderline` (blue).
- **Tap-to-fix guesses** come by style: `.spelling`/`.grammar` from a **public `UITextChecker.guesses`** call
  (candidate lookup only — the checking PASS stays native; the deleted `SpellChecking` seam was NOT re-added);
  `.correction` from the stashed `NSTextAlternatives` (read via guarded KVC on the delivered instance —
  `alternativeStrings`/`primaryString`). A `.correction` also offers **"Revert to '<original>'"**
  (`pendingSpellingMenu.revertTo` → `applySpellingReplacement(primary)`, one undo step).

**Runtime status (2026-07-14):** spelling is **live-proven** — `NativeTextCheckingLiveTests` drives a real
`DocumentCanvasView` client and the controller flags `{0,6}`+`{7,5}` for "helllo wrold today" ("today" not
flagged). Full Bazel build green; SwiftPM suite green (1392, incl. `NativeTextChecking*Tests` + the reused
`SpellCheck*Tests`); app smoke-launch stable with native checking wired. **Grammar + correction are UNVERIFIED
in-app:** grammar checking did NOT fire in the unit-test host (OS-grammar-service-dependent/async), and corrections
are keyboard-driven — both are ready infrastructure, to confirm **on-device**. Also **the sim test account's chat
composer is the LEGACY `UITextView` input** (RTE not active there), so there is no in-composer visual confirmation
yet — verify via an RTE-active composer (`forceNewTextInput` ON — Debug Settings ▸ "Force Text Field v2") or the attachment editor.

- **Exclusions** (`isExcludedSpellRange`, applied in `clampedSpellRegionLocal`): a flagged range overlapping a `.link` / `.rtInlineCode` / **`.rtSpoiler`**
  run, the active IME `markedRange` (clamped to the region), or the caret's in-progress word is dropped. Emoji/
  spoiler `U+FFFC` atoms are word boundaries so never inside a flagged word. **`.rtSpoiler` MUST stay excluded** —
  else a squiggle draws over hidden-spoiler dust and leaks the word (found in final review).
- **Own-drawn, both TextKit engines.** Rects come from the shared `selectionRects`/`layout.selectionRects` (no
  TK2-only API). Body/caption/quote/list draw via `drawSpellingUnderlines(in:)` in `SelectionHighlightView.draw`
  (filtered `!isInsideTable`); **table cells** draw via `drawCellSpelling(in:)` in the per-table `CellSelectionView`
  (rides horizontal scroll). Color: `RichTextEditorTheme.misspellingUnderline` (default `.systemRed`).
  **LOAD-BEARING:** `drawCellSpelling` mirrors `drawCellSelection`'s `-box.blockViewFrame.origin` translate + raw
  `region.canvasOrigin` (NOT `canvas.selectionRects`, which subtracts scroll → double-count). `drawCellSelection`
  had to gain a `saveGState`/`restoreGState` bracket around its own translate — once a second draw call
  (`drawCellSpelling`) chained after it in the same context, its un-popped CTM double-translated the underline
  (invisible for any off-origin table). Any future third draw in that overlay must keep every drawer GState-balanced.
- **Tap-to-fix.** `misspelledWord(atCanvasPoint:)` (unfiltered for tables — `selectionRects` folds cell h-scroll,
  so tap-to-fix works in cells too) → `beginSpellingCorrection` selects the word (reuses `applySelection` for the
  `onSelectionChange` + input-delegate bracket) and clears any stale `tableSelection` (**after** the hit-guard, so
  a stray Backspace can't then delete table rows), sets `pendingSpellingMenu`, presents the menu. The iOS-16
  `menuFor` short-circuits to the guesses `UIMenu` when `pendingSpellingMenu != nil` (bypasses the host
  `contextMenuItemsProvider`); iOS 13–15 uses `UIMenuController` + fixed `spellGuess0…3` selectors. Replace =
  `editing { applySelectionReplaceOutcome(...) }` (one undo step) then re-check. Gated on `wasFirstResponder` (a focusing
  tap only places the caret). `pendingSpellingMenu` cleared at the top of `dismissEditMenuForSelectionOrTextChange`.
- **Display-only** — nothing spell-related enters `Document`; **no `RichTextEditorCore` change**.
- **LOAD-BEARING (kept from the public feature):** `drawCellSpelling` mirrors `drawCellSelection`'s
  `-box.blockViewFrame.origin` translate + raw `region.canvasOrigin` (NOT `canvas.selectionRects`, which subtracts
  scroll); `drawCellSelection` keeps its `saveGState`/`restoreGState` bracket so its CTM translate doesn't
  double-translate the chained `drawCellSpelling`. `.rtSpoiler` MUST stay excluded (else a squiggle leaks a hidden
  word). The global position axis is **1-based** (first paragraph `textStart == 1`).
- **On-device / follow-up verification (non-blocking):** confirm grammar underlines fire on a real device (green,
  `.grammar`) + the `.correction`/autocorrect-revert path (blue + Revert) with a live autocorrection; confirm the
  in-composer visual with an RTE-active composer. Async-grammar staleness (a late grammar callback landing after a
  newer edit rebuilt the region — bounded/non-crashing via the clamp, self-corrects next edit); UITextChecker
  cold-start may leave the FIRST tap-to-fix guesses empty (separate engine from the native preheat); the
  `.correction` stash + revert are best-effort infra. Minor cleanups: share the `stashedAlternatives` lookup
  between `spellingGuesses`/`revertTarget`; `if let` the legacy `revertTo!`. Spec/plan:
  `docs/superpowers/{specs/2026-07-14-richtext-native-textchecking-design.md,plans/2026-07-14-richtext-native-textchecking.md}`;
  the RE + spike record is the `project_uitextcheckingcontroller_spike` memory.

## DEBUG layout overlay (added 2026-06-28, `RichTextEditorView+DebugOverlay.swift`)

`RichTextEditorView.debugShowLayoutOverlay` (`#if DEBUG`, **ON by default in DEBUG**; set `false` to hide) draws a
non-interactive topmost overlay: the field frame (red outline), scroll insets (blue bands), content margins (green
ring), and per-block frames (orange, indexed), with inset/margin numeric labels. Refreshed from `performLayout` /
`scrollViewDidScroll`; reads geometry via `bounds` / `debugContentInset` / `canvas`. Compiled out of release entirely.

## TECH DEBT — `resolveBox` degenerate-container misroute (needs generalization; may require re-architecture)

**Status: known-brittle. The current fixes are point-patches, not a design. Generalize this — changing the
architecture if that's what it takes.**

**Root cause (one bug, many faces).** Position→box resolution has TWO mechanisms that disagree:
- `activeStack(at:)` / `leafRegion(containingGlobal:)` — **container-aware**: they descend into
  `BlockQuoteBox.children` / table cells and resolve the real leaf.
- `resolveBox(at:)` / `box(containingGlobal:)` — **NOT** container-aware: a `BlockQuoteBox`/`TableBlockBox`
  has a *degenerate* `CanvasBlock` text extent (`textStart == nodeStart`, `textLength == 0`; the real text is
  in children), so a position **inside** such a container matches no top-level box and the fallback loop
  returns the **following top-level block** (`pos < nextBox.textStart`). A quote/pull-quote **author** region
  is the same trap from the other side: it's a *second* leaf region off `activeStack`'s child-descent, so
  `activeStack`'s own resolveBox-based fallback mis-resolves it too.

So **any code that calls `resolveBox`/`box(containingGlobal:)` with a position that can be container-interior,
and then ACTS on the result, edits/reads the wrong (following) block.** This produced a whole family of device
bugs, each fixed individually (see git log ~2026-07-05): in-text/first-line/sibling/mid-text Backspace, the
object-replacement-range Backspace (`sel=a..b`), Return-in-author, the empty-paragraph-after-atom handler
(line ~530, twice), `insertTable`/`insertMedia`, `currentState()` toolbar state, and IME
`isBodyParagraphPosition`.

**How they were patched (the brittle part).** Two ad-hoc moves, applied per call site: (a) swap `resolveBox`
→ `activeStack`/`leafRegion`; or (b) bolt on a `!isInsideBlockQuote(pos)` / `!isInsideTable(pos)` guard. There
is **no invariant** preventing the next `resolveBox` consumer from re-introducing the bug — every new call
site is a fresh landmine, and the guards are easy to forget. `RTEDBG q0705*` instrumentation (now stripped)
was needed twice because unit tests with a *non-empty* following block hid the misroute (line ~530 only fires
when the following block is empty).

**The real fix (do this).** Make position resolution container-aware **by construction** so a single resolver
cannot mis-resolve a container-interior position:
- Unify on ONE descending resolver (fold `resolveBox`/`box(containingGlobal:)` into the `activeStack` descent,
  or give containers a non-degenerate `CanvasBlock` extent so the fallback loop can't skip them), and retire
  the degenerate-`textLength` fallback that returns the following block.
- Represent the author as a first-class leaf on the child axis (or make `activeStack` descend to it) so it
  stops being a special-cased "second region."
- Then delete the scattered `!isInsideBlockQuote`/`!isInsideTable` guards and the `resolveBox`→`activeStack`
  swaps — they become unnecessary once resolution can't misroute.
- Guardrail until then: a new `resolveBox`/`box(containingGlobal:)` call site that acts on the result is a
  code smell — prefer `activeStack`/`leafRegion`, and if you must use `resolveBox`, guard the container cases.

## TECH DEBT — display-only font size is PINNED into runs on read-back (needs a style-inheritance re-think)

**Status: known-brittle. The style-transition font fixes are point-patches. Generalize this.**

**Root cause.** A run's rendered font SIZE is display-derived from the paragraph style (heading1 = 24, body =
17, table cells = 15 via the `tableCells` mapper variant), NOT stored per-run — EXCEPT that
`AttributedStringMapper.characterAttributes(from:)` **unconditionally PINS** the rendered size into
`CharacterAttributes.fontSize` on read-back (`currentParagraph()` / `runs(from:)`). That pin exists so a
non-default size survives being moved between contexts (the "15pt table-cell round-trip": copy a cell, paste
elsewhere, keep 15pt). But it means **any run that moves to a paragraph with a DIFFERENT style keeps its old
size, overriding the new style** — because the pinned `fontSize` beats the style default at layout time. Font
FAMILY does NOT have this problem (it's deliberately not round-tripped — see the RTL font-family invariant).

**Where it bites (patched ~2026-07-05):**
- **MERGE across styles is handled centrally in `ParagraphBlock.merging`** (Core): when the two paragraphs'
  styles differ, the appended (other) runs get their `fontSize` cleared so they inherit the surviving style's
  size. This covers every merge path at once — `deleteBackward`'s top-level `applyReplaceOutcome` merge (Backspace at
  a body paragraph's start into a preceding heading — reached as a RANGE `[prevEnd, thisStart]`, NOT a
  collapsed caret, so it goes through `applySelectionReplaceOutcome` → `applyReplaceOutcome` → `merging`) and
  `mergeParagraphsOutcome`. Same-style merges keep the pin (preserving the 15pt table-cell round-trip).
- **SPLIT (`insertParagraphBreak`) is still a separate patch**: Return in a heading makes the tail a body
  paragraph and clears the tail runs' `fontSize` (a split is not a `merging` call, so it needs its own sweep).

**Still ad-hoc on the split side and anywhere else runs cross a style boundary WITHOUT going through
`merging`** — paste, RTF import, format-menu style change, list/quote wraps, drag are each a fresh place the
pinned size can leak the wrong value. There is **no invariant** enforcing "a run's size follows its paragraph
style unless the user explicitly overrode it." (**Lesson:** the merge fix was first written as scattered
per-call-site patches AND a collapsed-caret-only unit test; both missed that iOS delivers Backspace-at-start as
a RANGE. Centralizing in `merging` + testing the range form fixed it.)

**The real fix (do this).** Separate *style-derived* size from a *user-explicit* size override:
- Do NOT pin the style-default size on read-back; only pin a size that DIFFERS from the run's paragraph-style
  default (mirrors how foreground color is stripped when it equals the style default — see the round-trip
  invariant). Then a heading run reads back with `fontSize == nil` and inherits whatever paragraph style it
  lands in; the 15pt cell case is handled by resolving the size against the *cell's* style at pin time (pin
  only when 15 ≠ the destination style's default), or by carrying the cell size as context, not per-run.
- Then delete the scattered `fontSize = nil` patches in `insertParagraphBreak` / `mergeParagraphsOutcome` — they
  become unnecessary once size inherits the style by construction.
- Guardrail until then: any new code path that moves runs into a different-styled paragraph must strip the
  runs' pinned `fontSize` (or it will render at the wrong size).

## Load-bearing invariants (compiler-invisible — violating these silently breaks the editor)

- **One flat global `(anchor, head)` range, coordinate-free.** Selection is a single linear range over one
  global position axis spanning the whole document (including non-renderable structural token slots); it's
  clamped per block and the per-block `enumerateTextSegments` rects are unioned for the highlight. The
  editing engine resolves endpoints through `activeStack` / `allLeafRegions()` and is **coordinate-free** —
  all position math is validated against Core's `PositionResolver`. Geometry (views, scroll offsets,
  culling) never feeds back into the position/selection/editing model.
- **The canvas is the SOLE `UITextInput`.** Image/table/paragraph blocks render via their own pooled,
  **non-focusable** `BlockBackingView`s (the ProseMirror node-view split) — render surfaces only, never
  first responders. `caretRect`/`closestPosition`/`selectionRects`/`contentSize` derive from **box frames
  over ALL boxes**, never the realized (possibly culled) views, so off-screen view virtualization changes
  no editing/selection/nav/hit-test behavior.
- **No PERSISTENT `UITextSelectionDisplayInteraction`; everything is own-drawn.** The canvas installs none
  persistently and has **no `draw(_:)` override** — it is a pure container of bounded subviews (a single
  CALayer/CGContext can't back an arbitrarily tall document; GPU max-texture ~16K px). Caret (`CaretView`),
  selection wash (`SelectionHighlightView` + per-table `CellSelectionView`), and handles (`SelectionHandleView`)
  are dedicated on-top layers/views, hosted in a table's scrolling content view for cell endpoints so they
  **ride horizontal overscroll**. (Un-clamping a table's `contentOffsetX` so the OS selection UI could ride
  the bounce makes the OS text system *fight* the caret — rejected; the clamp stays and we own-draw.)
  `caretRect(for:)` must still report a **real** position even when the visible caret is hidden — it feeds
  the OS's nav/scroll/loupe/edit-menu. **The ONE scoped exception:** a FRESH interaction is created per
  long-press loupe drag and torn down on release, borrowed only to hand the loupe a real `cursorView` widget
  (a bare/own caret is ignored by the grow animation) — per-drag, or it crashes against the view virtualization.
  See the "Loupe grow-from-cursor" note above.
- **`caretRect` is OS-facing nav geometry.** Hardware vertical arrows are driven by the OS via
  `position(from:in:direction:)` + the `selectedTextRange` setter — **not** `keyCommands` (arrow
  `keyCommands` never fire here). Vertical-nav results are `snapToRenderable`'d so the caret can't strand
  on a non-renderable structural slot.
- **Any pure `anchor`/`head` change must bracket `inputDelegate.selectionWillChange/DidChange`** — else the
  OS keeps a stale `selectedTextRange` and the next hardware arrow navigates from the wrong spot.
  (memory: `selection-changes-need-inputdelegate-bracket`) **This includes EDITS**, not just pure selection
  moves: `editing { }` and the undo closure bracket BOTH `text*` and `selection*` (like `reload`), because
  every edit also moves the caret. Omitting the selection bracket is invisible under system-keyboard typing
  (UIKit owns the selection there) but breaks **programmatic** inserts — e.g. the custom emoji keyboard:
  the caret appeared not to advance and a re-insert dropped a stray bare `U+FFFC` "service character".
- **Any caret-moving op must fire `onSelectionChange`** so the host can scroll-follow the caret (the
  façade's `scrollCaretIntoView`). Over-firing is safe — it early-returns when already visible and scrolls
  **non-animated** (an animated scroll races the OS arrow dispatch → nondeterministic geometry).
  (memory: `caret-moves-fire-onselectionchange-for-scroll`)
- **Display-only attributes never enter the Core model.** Inline-code, link styling, the inline-prediction
  ghost, spoiler-hide, and emoji are applied as TextKit **rendering attributes** or private storage markers
  (`.rtInlineCode` / `.rtSpoiler` / `.link`); `characterAttributes(from:)` / `currentBlock()` strip them on
  read-back so the model stays markdown-clean. The two `.foregroundColor` consumers (prediction-ghost vs
  spoiler-hide) each track + remove only their own ranges so they never clobber. A render-only display
  override (`applyDisplayOverride`, the table column-alignment / header-bold pass) **must be idempotent** —
  unconditionally re-assigning `layout.attributedString` resets the spoiler-hide ranges every layout pass
  → an infinite `layoutIfNeeded` loop; only assign when the rebuilt string actually differs.
- **Emoji and the spoiler atom are a single `U+FFFC`** carrying their ref in `CharacterAttributes` — exactly
  1 UTF-16 position, so `DocumentTree`/`PositionResolver`/the editing engine/tokenizer are untouched.
  Host-provided `UIView`s are pooled by `instanceID`, hosted in the canvas overlay (body/caption) or the
  table's content view (cells, ride H-scroll), and culled.
- **Caret placement snaps to composed-character boundaries — never mid-emoji.** `closestOffset(toPoint:)`
  (both `BlockLayout` and `BlockLayoutTK1`) skips offsets INSIDE a composed character sequence (surrogate
  pair / ZWJ / variation-selector emoji), so a tap can only land on a grapheme boundary. Without this a tap
  near an emoji places the caret mid-cluster, and the next insert/delete (incl. via the chat composer's
  `selectedRange`) splits the cluster → a stray code unit (the "service character"). Pairs with the
  grapheme-aware `deleteBackward` below — both keep the editor surrogate-safe.
- **Range delete/replace expands to whole grapheme clusters.** `applySelectionReplaceOutcome` (THE chokepoint for
  every selection-replacing edit — delete, type-over, paste, `replace(_:withText:)`) runs
  `rangeExpandedToGraphemeBoundaries` first, so a range covering only PART of a composed sequence is widened
  to the whole cluster. This is load-bearing for the **chat composer**: the OS delivers backspace there as a
  RANGE delete (`selFrom≠selTo`) that can cover just one half of a surrogate-pair emoji — deleting it verbatim
  left a lone surrogate (rendered `U+FFFD`), the composer "service character". The collapsed-caret
  `deleteBackward` grapheme snap did NOT cover this path; the expansion does.
- **Left/right arrow navigation moves a whole grapheme, not one UTF-16 unit.** The OS drives horizontal
  arrows through `position(from:in:direction:)` → `nextTextPosition`/`prevTextPosition`; the within-region
  step advances by `rangeOfComposedCharacterSequence`, so one press crosses a whole emoji. Stepping one
  UTF-16 unit lands the caret mid-surrogate (renders at the same glyph edge → looks stuck), so crossing an
  emoji took two presses. (The OS also *probes* `position(from:offset:±1)`, which is NOT grapheme-aware and
  can return a mid-surrogate offset, but it doesn't drive the caret — the move is `position(in:direction:)` +
  the `selectedTextRange` setter with grapheme-aligned values. A latent follow-up if shift+arrow selection
  ever needs sub-grapheme hardening.)
- **Backspace deletes a whole grapheme cluster, not one UTF-16 unit.** `deleteBackward`'s in-place delete
  (both the top-level and in-cell branches) removes `graphemeClusterLengthBeforeCaret(global:)` units, not a
  hardcoded 1 — so a *standard* Unicode emoji typed from the system keyboard (surrogate-pair scalar, ZWJ
  sequence, skin-tone / flag / variation-selector combo, all multi-UTF-16-unit) is removed as one unit
  instead of leaving an orphaned half. Computed via `rangeOfComposedCharacterSequence` on the leaf region's
  own string (the global axis is 1:1 with UTF-16 inside a region; a grapheme never spans regions). A
  custom-emoji `U+FFFC` and any plain BMP char are single-unit clusters, so it's a no-op for them.
- **Gesture arbitration is gate-only.** Handle/knob pan vs scroll pan is resolved *only* via
  `gestureRecognizerShouldBegin` — never `require(toFail:)` or forced simultaneous recognition. The
  single-tap recognizer fires immediately with manual multi-tap escalation in `handleTap` (no
  double-tap-failure delay); the host scroll view sets `delaysContentTouches = false`. **Both scroll views
  yield near a grip** via `GripYieldingScrollView` (a `UIScrollView` subclass overriding
  `gestureRecognizerShouldBegin` to return `false` when `canvas.isSelectionDragTouch(point)` — its testable
  seam is `yieldsToGrip(at:)`): used for the per-table inner scroll AND the **outer** document scroll
  (`RichTextEditorView.scrollView`, `canvas` wired in init). Before the outer scroll adopted it, a vertical
  knob pull raced the document scroll and the knob "felt dead" (2026-06-29).
- **The single-tap "inside the selection/caret" test (`tapOutcome`) is VISUAL, not offset-based.** A tap
  toggles the edit menu only when its *point* lands on the rendered selection (`selectionRects().contains`)
  — NOT merely when `closestGlobalPosition` resolves to an offset within `[selFrom, selTo]`. A tap in the
  empty area beside a selection resolves to a *boundary* offset inside the range but is visually outside, so
  it must collapse the selection + place the caret (the composer "tap-to-deselect doesn't work" bug). The
  collapsed-caret branch keeps the offset test (`resolved == head`).
- **A FOCUSING tap only places the caret — it never opens the menu** (`menuToggleAction`'s `wasFirstResponder`
  gate). The focus transition is captured by `didJustBecomeFirstResponder` (set in `becomeFirstResponder`,
  consumed by the next `performSingleTap`), **not** by reading `isFirstResponder` at touch-up: the chat
  composer focuses the editor on touch-**down** (`ChatTextInputPanelNode`'s `ensureFocusedOnTap`), so by the
  time the tap handler runs `isFirstResponder` is already true and can't distinguish the focusing tap.
  Otherwise the empty composer (caret at 0, a focusing tap resolves to 0 == `head` → `.toggleMenu`) pops the
  menu on the first tap. A second tap on the caret of the now-focused field toggles it normally.
- **Gesture-driven RANGE selections fire `onSelectionChange`** (`applySelection`, shared by `selectWord` /
  `selectParagraph` / `selectAllText`), exactly like `setCaret`. The chat composer tracks the editor selection
  through this hook; without it a double-tap word-selection never reaches the panel's interface state and the
  next `setInputContent` re-apply collapses it back to the stale caret (the double-tap "flash then deselect"
  bug). Pairs with the repo-wide invariant *"any caret-moving op must fire `onSelectionChange`."*
- **Word/paragraph boundaries come from the custom `DocumentTokenizer`**, which scans each leaf region's OWN
  string — not the global axis (whose structural slots the stock tokenizer mis-reads, gluing regions with
  no separator).
- **Marked text / IME is storage-backed** (body paragraphs only today): composing text is applied
  **outside** `editing{}` with one undo per composition; a system inline prediction (signalled by
  `setMarkedText` `sel:{0,0}`, ghost trailing) is **dismissed, never committed**, by our finalize
  chokepoints so the keyboard's own accept lands clean.
- **A gesture selection fires the OS input-delegate bracket exactly ONCE — no autocorrect "jiggle" (removed
  2026-07-06).** A short-lived experiment (added then removed the same day) tried to DISMISS the keyboard's pending
  autocorrect on a deliberate selection/cursor-move (⌘A especially) by bracketing a fake→real selection round-trip
  (`autocorrectDismissJiggle`) under an `isDroppingPendingAutocorrection` window that no-op'd the four text-mutation
  entry points. **It was removed because it was the dominant selection-latency cost:** each `selectionDidChange`
  drives the keyboard's synchronous `updateForChangedSelection` (~25ms on device — the ONE required bracket is
  already that expensive), and the jiggle added TWO more, so a double-tap word-select went from ~33ms to ~90ms
  (device-measured with `RTEDBG perf` timing). It was also non-standard — a stock `UITextView` simply lets a pending
  correction COMMIT when the selection moves. So `applySelection` (word / paragraph / Select-All) now brackets
  `selectionWillChange/DidChange` **once** around the range set, with no block and no jiggle; a pending correction
  commits on selection-move like any text view. `dropPendingAutocorrection` / `autocorrectDismissJiggle` /
  `isDroppingPendingAutocorrection` and the loupe/handle-drag `dropPendingAutocorrection()` calls are all gone.
  Guarded by `SelectionInteractionTests.test_applySelection_firesASingleSelectionBracket_noAutocorrectJiggle`. (The
  loupe/handle-drag input-delegate **coalescing** — `beginCoalescedSelectionDrag`, a separate feature — is unaffected.)
- **The undo buffer is a PRIVATE, per-canvas `UndoManager`, NOT the responder-chain `UIResponder.undoManager`**
  (`DocumentCanvasView.effectiveUndoManager = undoManagerOverride ?? ownUndoManager`, the latter a private
  `UndoManager()`). The responder-chain manager is shared app-wide, so other responders' (and the system
  text-input subsystem's) selection/typing undo registrations would surface in the editor's `canUndo` /
  `undo()` — the device-observed "a selection change is undoable / undo is active on the FIRST tap before any
  content edit" bug (fixed 2026-06-30). Only the editor's own `registerUndo` (every content `editing{}` + the
  composition commit) may enter this buffer. Tests inject their own via `undoManagerOverride` (every undo test
  already did — production simply never wired a private manager until this fix). Regression-guarded by
  `UndoBufferIsolationTests`. **The private manager is EXPOSED to the responder chain** via
  `override var undoManager { effectiveUndoManager }` (added 2026-07-01), so the SYSTEM undo affordances —
  hardware ⌘Z / ⌘⇧Z, shake-to-undo, and the Edit-menu Undo/Redo — act on our edits. They were DEAD between the
  2026-06-30 private-manager switch and this fix, because the responder chain exposed the app-wide *shared*
  manager (which our edits never touch). Safe by construction: the override changes only WHO can call `undo()`
  on our manager, not WHAT is registered into it (still only `registerUndo` content edits — nothing on
  selection), and it's a private instance no other responder holds, so the foreign-entry pollution above (which
  lived in the shared instance) cannot reappear; UIKit records no cursor movements / typing undos into a bare
  custom `UITextInput`. The `RichTextAttachmentScreen` nav-bar pill drives the same `undo()`/`redo()`.
  (⌘Z runtime-verified 2026-07-01.)
- **`undo()`/`redo()` fire a trailing `onChange` AFTER the manager settles** (`RichTextEditorView`). The undo/redo
  closure's own refresh (`notifyContentSizeChanged`) runs WHILE STILL INSIDE `UndoManager.undo()/redo()`, so a
  host that re-reads `currentState().canUndo/canRedo` synchronously from it sees the stack BEFORE the group is
  finalized — stale for the LAST undo/redo only (intermediate steps read the same value either way). Symptom:
  the undo (or redo) control stays enabled after the final undo (redo) until an unrelated `update()` (e.g. a
  rotation) re-reads state. The explicit trailing `onChange?()` refreshes the host with the settled availability.
  Regression-guarded by `UndoBufferIsolationTests.test_undoRedo_fireOnChange_soHostRefreshesAvailability`.
- **Typing/deleting undo COALESCES into whole runs** (`editing(coalescing:)`, added 2026-07-01). Every edit
  still snapshots the whole document, but `editing` SKIPS `registerUndo` when this edit CONTINUES an open run —
  same kind (`.typing`/`.deleting`), collapsed caret, landing exactly where the last keystroke left off
  (`openUndoRun.caret`) — so one undo reverts the whole uninterrupted run (like an iOS composer), not one char
  per step. The run-start snapshot already captures the pre-run doc, so skipping registration is all it takes;
  redo is unchanged (the closure lazily captures the post-run doc). A run BREAKS on: a caret move / a
  typing↔deleting switch / a selection-replace (all caught by the contiguity check), any structural / format /
  paste edit (the default `coalescing: .none`), and IME composition commit + resign-first-responder + `setBlocks`
  (which call `breakUndoCoalescing()`; `setBlocks` also covers the undo/redo restore). Only the 3 char-insert
  `insertText` sites pass `.typing` and the 3 plain-delete `deleteBackward` sites pass `.deleting`; every
  structural delete (paragraph merge / `removeBlockOutcome` / media-replace / un-quote / un-code / cross-block merge)
  stays `.none`. Scope note: system replacements via `replace(_:withText:)` (autocorrect/dictation) stay
  `.none`, so a dictation utterance is its own undo step. `undoRegistrationCount` is a test seam counting new
  steps; `UndoCoalescingTests`.
- **Undo restores a CARET for content edits, the SELECTION for formatting** (`editing`, added 2026-07-01). The
  undo closure restores the pre-edit `anchor`/`head` — which for a selection-delete/replace would re-select the
  restored text. Instead, when the edit COLLAPSED the caret (post-`body()` `anchor == head` — every content
  edit: delete / type-over / paste) the registration collapses the restored selection to a caret at the END of
  the pre-edit span (`max(beforeAnchor, beforeHead)`); a selection-preserving edit (formatting — bold/italic/
  link/style leaves a range post-`body()`) restores the pre-edit SELECTION so you still see what was
  un-formatted. Matches an iOS composer (macOS/VSCode re-select the restored text; iOS uses a plain caret).
  `UndoCoalescingTests`.
- **`text(in:)` MUST emit a `"\n"` at every top-level paragraph boundary** (`DocumentCanvasView+UITextInput`),
  exactly like a `UITextView` over a `"\n"`-joined string — because the global axis carries NO newline char
  between blocks, only a structural token gap. The system keyboard reads document context through `text(in:)`,
  and **not every IME drives `setMarkedText` on this view** — the Hangul (and other CJK) keyboard composes via
  `insertText` + a ranged `selectedTextRange`-set + `deleteBackward` + `insertText`, tracking positions itself
  and reading `text(in:)` for context. Without the separator it sees two stacked paragraphs as ONE continuous
  line and recomposes a syllable **across the invisible line break** — the trailing consonant of the lower line
  migrates onto the line above (the reported Korean-deletion bug). The `"\n"` is emitted for each crossed
  boundary, **including a range that lands entirely inside the inter-block gap** (the read the keyboard makes
  immediately before a lower line's first character). **Table-cell boundaries stay glued** (a table is one
  editing surface; cells don't compose marked text, and `CanvasCrossCellEditTests`/`test_copy_acrossCells…`
  rely on the un-separated cross-cell read). Covered by `CanvasTextInputTests.test_textInRange_*`.
- **PRIVATE API risk:** `SpoilerDustView` uses `CAEmitterBehavior` (`createEmitterBehavior`) for the
  twinkle + finger-attractor explosion — App-Store-review risk, guarded by a live canary test.
- **View-frame ownership** (the repo-wide rule applies here too): a reusable component lays out against
  `self.bounds`; it never writes `self.frame` — the parent positions it.

## Known render-only trade-offs

These keep the model markdown-clean at the cost of not separately preserving a user override: **(1)** a
link run's `foreground`/`underline` styling is render-only (suppressed on read-back); **(2)** table
**header-row** bold is render-only, so user-bold inside a header cell isn't separately preserved.

Headings are **regular weight by default** (`StyleSheet.font` does not force bold for them — they read as
larger serif); bold is a pure user-emphasis toggle that round-trips uniformly across every style. (This
replaced the earlier behavior where headings baked bold into their font, which leaked `**bold**` into the
model and left residual bold on a heading→body down-convert.) Type scale (2026-06-13; sizes since superseded
by V2 parity — see the layout-parity note): H1 24 / H2 21 / H3 19
serif, Body 17 sans, Caption 15 sans, Quote 17 sans — see the 2026-06-13 session block above. **Inside table
cells body/quote drop to a 15pt base (2026-06-26)** via a per-cell `StyleSheet.tableCells` mapper variant — see
the type-scale bullet in that session block.

**Interactive checklist / task list (added 2026-06-26).** A first-class checklist marker
(`ListMarker.checklist` + `ListMembership.checked: Bool?`, Core). **Creation:** the list picker offers
"Checklist"; `setList(.checklist)` seeds `checked: false` (re-applying `.checklist` to an already-checked item
PRESERVES its state). **Interactive checkbox — `CheckNode` via a host hook (the editor package stays
`CheckNode`/AsyncDisplayKit-free):** `RichTextEditorView.registerChecklistMarkerViewProvider(_ : (checked, size)
-> (UIView & RichTextChecklistMarkerView)?)` supplies a `CheckNode`-backed checkbox; both hosts wire it — the chat
composer threads checkbox colors through the `ChatRichTextThemeColors` seam (sourced from
`theme.list.itemCheckColors` in `ChatTextInputPanelNode.makeRichTextThemeColors`), `RichTextAttachmentScreen`
reads `appliedTheme.list.itemCheckColors`. The editor hosts/pools/culls the view in the marker gutter (mirrors the
inline-emoji machinery, `DocumentCanvasView+ChecklistMarkers.swift`), SUPPRESSES the Unicode glyph for `.checklist`
(`BlockBox.hostsChecklistCheckbox`, stamped in `stampListMarkers` + folded into `renderSignature` so a late
provider repaints), and a tap on the marker hit-rect toggles `checked` as ONE undo step (`toggleChecklistItem`,
caret-neutral, animates the hosted view). **Marker geometry** (`BlockBox.checklistMarkerCanvasRect()`): side =
`StyleSheet.checklistMarkerSize(for:)` (`font.capHeight.rounded()`) × `checklistMarkerScale` (1.4), bottom on the
text baseline (grows top/bottom/right, left edge anchored at the gutter), `floorToScreenPixels`-snapped; the list
text inset reserves the scaled width + a gap. **Return** continues the list with a fresh `checked:false` item
(empty-item Return exits the list; indent/outdent preserve `checked`). **Message round-trip (composer):** sends as
a rich message — `ChatInputContent` gained `.checklist` + `checked: Bool?` (the draft currency → draft persistence
free; raw enum value appended, optional Codable back-compat), threaded through `DocumentChatInputContentBridge`
(both directions) and BOTH `Document→InstantPage` builders (`ChatInputContentInstantPage` for the composer +
`RichTextEditorMessageConversion/InstantPageBuilder` for the attachment-screen send) into `InstantPageListItem.checked`.
Recipient checkboxes are display-only/static; the SENDER can re-edit (falls out of the reverse bridge). No
strikethrough on checked text (matches the InstantPage rendering). Active when the native composer is (opt-in via `forceNewTextInput`); runtime-verified.

**Quote + list combine as a container (added 2026-07-02).** A paragraph can be BOTH `style == .quote` AND a
list item (`setParagraphStyle`/`setList` never clear each other), i.e. a list *inside* a quote. Two subsystems
that used to ignore the quote in that case now treat it as a proper container: **(1) inset** — the quote's
leading inset (`quoteIndent`, the bar→text gap) now **STACKS on top of** the list marker inset rather than being
skipped (`StyleSheet.paragraphStyle` — the old mutually-exclusive `else if style == .quote` became an additive
`indent`), and the marker/checkbox columns add the same `quoteLeadingInset` (`BlockBox.listMarkerDraw` /
`checklistMarkerCanvasRect`) so a quoted list clears the bar instead of drawing over it; **(2) numbering** —
`ListNumbering.labels` now resets its counters at a quote boundary (a quote is its own numbering scope, exactly
like a non-list paragraph resets), so a quoted run numbers `1,2,…` independently and the surrounding list
restarts after the quote. This required forwarding each box's `style` into `ListNumbering` via `listMarkerLabels`
(previously only `list` was passed). Guarded by `ListRenderingTests` (inset/marker/caret) + `ListNumberingTests`
(quote-scope). This deliberately reverses the earlier "quote's flat +16 must NOT stack" decision — do not re-revert.

**Inter-block vertical spacing — two follow-on fixes (`BlockStack`, added 2026-07-02).** The gap between two
adjacent blocks is `boxes[i].bottomInset + boxes[i+1].topInset`, computed by `facingInset` — but only for
`BlockBox`es. Two cases had no gap: **(a)** a plain list item next to a *quoted* list item — the "two list items
stack tight (`return 0`)" rule fired even though they sit in different containers, so `facingInset` now guards
that rule on same-quote-ness (`(box.style == .quote) == (n.style == .quote)`); a body↔quote list pair falls
through to the framed-neighbor margin. **(b)** two adjacent **framed atoms** that are NOT `BlockBox`es
(code / table / collapsed-quote — `isFramedAtom`): each fills its whole frame and its own insets are INTERNAL
padding, and `facingInset` never runs for them, so their fills sat flush. `layout` (and, in lockstep,
`measuredHeight`) now inserts an external `verticalInsetBase + framedNeighborMargin` gap between two such atoms —
a bare gap belonging to no block's frame (tolerated by `closestPosition`, which maps a tap there to the block
below). An expanded quote is a `BlockBox` (consecutive quotes still merge into one fill; a quote↔non-quote gap is
reserved by the non-quote neighbor via `facingInset`), so it is deliberately excluded from `isFramedAtom`.
Guarded by `QuoteVerticalInsetTests`.

**Double-return on a list inside a quote — end the list first, THEN exit (`insertParagraphBreak` /
`quoteDoubleReturnExitIndex`, added 2026-07-02).** Ending a list is a two-step exit when the list is inside a
quote: Return on an empty quoted list item ENDS THE LIST but stays in the quote (an empty quote line), and only a
FURTHER Return leaves the quote. Two coordinated changes: `insertParagraphBreak`'s empty-list-item branch keeps
the paragraph's style (`if p.style != .quote { p.style = .body }`) instead of always forcing `.body`, so a quoted
list item becomes an empty **quote** line; and `quoteDoubleReturnExitIndex` returns nil while the empty quote line
still has a `listMembership` (both the on-line and the line-above cases), so the quote-exit dispatch doesn't fire
until the list has ended. Guarded by `DoubleReturnExitTests`.

**Backspace on an empty quoted list item → a plain empty paragraph (`deleteBackward`, added 2026-07-02).** The
empty-quote Backspace branch (un-quote → body) now also clears `listMembership`, so an empty **quoted list item**
(e.g. the first, empty line of a list inside a quote) collapses ALL the way to a plain empty paragraph rather than
leaving a body list item with a stray marker. `listMembership = nil` is a no-op for a plain (non-list) quote, so
that case is unchanged. Guarded by `CanvasQuoteEditTests`. (Backspace is a one-step full exit here, unlike Return's
two-step end-list-then-exit — Backspace is a delete gesture and matches the pre-existing empty-quote/empty-code
Backspace-to-body behavior.)

**Backspace at the START of a list item → outdent, or break the list (`deleteBackward`, added 2026-07-02).** A
collapsed caret at `local == 0` of ANY list item (empty or not) now: **nested (`level > 0`)** → `outdent()` (cancel
one indent level, stays a list item); **top-level (`level == 0`)** → break the list here — the item becomes a body
paragraph keeping its contents (`listMembership = nil; style = .body`), so items before it stay a list and items
after start a fresh one (numbering resets across the non-list gap). This branch sits right after `resolveBox` and
takes priority over the merge-into-previous and empty-quote branches, so it replaces the old "backspace at a list
item start merges into the previous block" behavior. Non-list paragraphs still merge (the branch is gated on
`listMembership != nil`). A quoted list item breaks straight to a **body** paragraph (un-quotes), consistent with
the one-step empty-quote Backspace above. Guarded by `CanvasStructuralTests` + `CanvasQuoteEditTests`.

## Configurable quote geometry + collapsed quotes (added 2026-06-28)

Two related quote features. **(1) Per-host quote geometry** — a `QuoteStyle` value (leading/trailing inset,
spacing before/after, bar width, corner radius, fill alpha) set via `RichTextEditorView.quoteStyle` and applied
through `DocumentCanvasView.applyQuoteStyle` (rebuilds the mapper stylesheet); the full-page article editor and the
compact chat composer pass different values. **(2) Collapsed quotes** — a first-class
`Block.collapsedQuote(CollapsedQuote)` atom (legacy chat-input parity) reusing the AUDIO-media DocNode shape
(`mediaBlock`+`mediaAtom`, nodeSize 3, caption-less; the leading gap is the caret slot). `CollapsedQuoteBox` draws
the folded preview + a corner expand glyph; `collapseQuoteRun(atIndex:)` folds a run of consecutive quotes into one
atom, `expandCollapsedQuote(atIndex:)` restores them — caret relocation on collapse/expand is conditional (only a
caret that was INSIDE the run moves). Composer round-trip: one flat char + `ChatTextInputTextQuoteAttribute(
isCollapsed: true)` via `ComposerDocumentBridge`, sent through the InstantPage builder. Available in both hosts
(the native composer is opt-in via `forceNewTextInput`). Runtime-verified.

**Collapsed-quote atom — caret/nav/delete invariants (compiler-invisible, device-log-verified).** The collapsed
quote behaves like a caption-less media atom: it owns NO leaf region (`leafRegions() == []`), so it routes through
the same gap machinery as audio media via `collapsedQuoteBox(atGap:)` (mirroring `mediaBox(atGap:)`).
- **Caret** at the gap draws at the quote's leading edge (`caretRect` / `caretHostPlacement`); a range covers it
  (`coverableContentEnd == nodeStart + 1`). **Tap** the body to place the caret at the gap; tap the corner glyph to
  expand.
- **Horizontal nav** stops on the gap (`nextTextPosition` / `prevTextPosition` via `atomGap`); `snapToRenderable`
  treats the gap as renderable.
- **Vertical nav MUST step THROUGH the gap** — `verticalPosition` has an explicit `collapsedQuoteBox(atGap:)` branch
  (Down → block after, Up → end of block above), mirroring the media-gap branch. Without it a multi-line move (the
  OS's `position(from:in:.up/.down, offset: 2)`) STALLS on the gap (offset:2 == offset:1); the OS reads "no
  progress", abandons `position(from:in:)`, and falls back to its own line geometry that SKIPS the captionless atom
  (the intermittent "arrow jumps over the quote" bug).
- **Backspace** at the gap acts on the PREVIOUS block, never the quote: a non-empty previous paragraph loses its
  last grapheme, an EMPTY one is removed (caret stays on the quote's gap), a LEADING collapsed quote (nothing
  before) expands. LOAD-BEARING: iOS delivers this Backspace as an object-replacement RANGE anchored at the
  previous block's end (`selFrom = prevTextPosition(before: gap)`, `selTo = gap`) — exactly like a media atom — so
  the handler fires on `selTo` being a collapsed gap AND `selFrom >= prevTextPosition(before: selTo)` (admits the
  range AND the collapsed caret; excludes a genuine selection that merely ends at the gap), NOT on `selFrom ==
  selTo`. (Same "capture the device log, don't hypothesise twice" lesson as the media object-replacement-range case.)

## Selection-handle drag — touch offset, outer-scroll yield, host knob config (added 2026-06-29)

Three fixes to the selection-handle ("knob") drag, runtime-verified in the chat composer.

- **The drag keeps its starting touch→knob offset (not line-centered).** The knob is drawn OFFSET from the text
  line (`SelectionHandleView.boundingFrame`: a knob 2·`knobRadius` past the caret's open end), so mapping the raw
  finger point snapped the dragged endpoint to whatever line sat under the finger. `handleSelectionHandlePan`
  `.began` now captures `selectionDragGrabOffset = caretCenter(draggedEndpoint) − touch`
  (`captureSelectionDragOffset`), and every drag map — the `.changed` branch AND the auto-scroll re-extend tick —
  goes through `selectionDragPosition(forTouch:)` = `closestGlobalPosition(to: touch + offset)`. Anchoring on the
  caret CENTER makes the first map (touch ≈ grab point) land exactly on the grabbed endpoint (no jump at grab) and
  the constant offset is preserved for the rest of the drag — the iOS handle-tracking feel.

- **`GripYieldingScrollView` (generalized from the old `TableScrollView`).** See the gesture-arbitration invariant
  above: the OUTER document scroll now yields its pan near a grip (it never did before — the root cause of the
  "knobs feel dead, only the line drags" report; the gate was already covering the knobs, but the un-gated outer
  scroll won the vertical pull). Same class backs the per-table inner scroll.

- **Handle views are hit-testable + host-configurable, so a knob drag isn't hijacked by interactive
  dismiss/transition gestures.** `SelectionHandleView` is now `isUserInteractionEnabled = true` with a
  `point(inside:)` hit area = `caretLocalRect.insetBy(-dragHitTolerance)` (the SAME ±22pt zone as
  `isSelectionDragTouch`, fed via `setCaretLocalRect` in `positionHandle`) — **it adds NO recognizers; the drag is
  still the canvas pan, which receives the touch as an ancestor.** Being the window hit-test result for a knob
  touch lets a host set Display's gesture flags on it (Display walks UP from the hit-test view), scoping the effect
  to knob interaction — NOT the whole editor surface (setting them there was rejected). The package can't import
  Display, so the new façade hook `RichTextEditorView.configureSelectionHandleView: ((UIView) -> Void)?` (invoked
  once per handle view, applied in the canvas `didSet`) lets the host apply them. The three flags:
  `disablesInteractiveTransitionGestureRecognizer` (the navigation back-swipe a HORIZONTAL knob drag triggers — the
  load-bearing one, gated at `WindowContent.doesViewTreeDisableInteractiveTransitionGestureRecognizer`, distinct
  from the keyboard check), `disablesInteractiveModalDismiss` (the attachment sheet), and
  `disablesInteractiveKeyboardGestureRecognizer`. **Scope differs by host:** the **compact composer**
  (`RichTextEditorChatInputNode`) uses ONLY the per-knob hook (editor-wide was rejected — it would kill normal
  scroll/dismiss in the small field); the **full-page attachment editor** (`RichTextAttachmentScreen`) sets the
  hook AND the same three flags editor-wide on `editor` (a full-page editor shouldn't back-swipe/dismiss from any
  in-editor interaction while editing). **Compiler-invisible:** the per-knob flag is consulted only when the knob
  is the window hit-test result, so the handle MUST stay hit-testable and its hit area MUST track the caret —
  verified on device (the hit test lands on `SelectionHandleView`).

**Code blocks are edge-to-edge plain bands (2026-08-18, `feature/code-block-edge-to-edge`).** A code block
stopped being a quote variant: no accent bar, no tint, no corner radius. Its band is a plain
`RichTextEditorTheme.codeBackground` rectangle spanning its container's interior edge to edge, and its code
text — plus a **bold, lowercased language line above it** — sits at exactly the x a paragraph occupies at
that nesting level. So the band's interior side padding IS the paragraph inset; it is no longer a constant.

- **`CodeBlockBox` paints its own fill** and left `blockquoteDecorations()`, which was deleted with its
  struct (the code case was its only producer). That is also the FIX for a live bug: the quote underlay's
  feed walks top-level boxes only, so a code block inside a quote or a table cell previously had **no fill
  at all**.
- **`blockViewFrame` outsets `frame` by `horizontalBleed`** — geometric sides (`minXSide` is the smaller-x
  edge), mirroring the renderer's `InstantPageV2ChildBleed`. `BlockBackingView` clips to `blockViewFrame`, so
  a bleed missing there renders as a band clipped back to the text column. It is assigned by
  `BlockStack.layout(origin:width:codeBleed:)` at LAYOUT time, not at construction: it moves with the host's
  content margins while the box does not. Root → the canvas edge by default, or `CodeStyle.horizontalBleed`
  when a host sets one; block quote → just inside the accent bar, so the bar stays continuous; details /
  table cells / list items → none, conservatively.
- **A COMPACT host bleeds NOTHING and indents the text instead.** The composer's canvas sits INSIDE the
  input field's rounded background (inset by the panel's `textInputViewInternalInsets`, 12 left / 11 right)
  and its right `contentMargins` additionally reserves the accessory + send button strip — so any outward
  bleed reads as spilling past what the field shows. The composer therefore sets
  `CodeStyle(horizontalBleed: 0, horizontalInset: 8, cornerRadius: 4)`: the band spans exactly the text
  column, and `horizontalInset` moves the code IN from its edges — the inward counterpart of the outward
  bleed. **`horizontalBleed` and `horizontalInset` are alternatives**; a host sets one or the other, never
  both to non-zero. The inset narrows the text MEASURE as well as its origin (`setWidth` /
  `measuredHeight(forWidth:)` / the init layout all subtract it twice), or the code would wrap at the
  band's full width and overrun its trailing edge. **Deliberately NOT WYSIWYG** against the sent bubble
  (full-bleed, square) — a compact field is a different container shape from a message bubble, the same
  reason the composer zeroes `mediaBlockStyle.horizontalBleed`.
- **`CodeStyle` (host knob) + `StyleSheet.codeVerticalInset` / `codeLanguageSpacing`** replaced the borrowed
  `quoteIndent` / `quoteTrailingInset` / `quoteTopInset` / `quoteBottomInset`. Both fields are optional and
  resolve against `RichTextRenderMetrics.code` (`RichTextCodeMetrics`), so an unset host renders the
  renderer's own numbers. `applyRenderMetrics` MUST re-resolve them — `metrics.code` is the fallback, so a
  host setting `renderMetrics` after `codeStyle` would otherwise keep stale defaults.
- This closed two real parity breaks: interior padding was 9/**22** here (it read `quoteTrailingInset`)
  against the renderer's 9/9, and vertical padding a raw 3pt against its font-box-corrected 6pt.

Renderer side + the design record: `docs/superpowers/specs/2026-08-18-code-block-edge-to-edge-design.md`.


## Status

**Done** (model + editing + rendering all in place): the Core model, global position model, and JSON/`.rtdoc`
serialization; continuous **cross-block and partial-cross-cell selection + editing** — the headline
requirement, incl. editing across stacks via `applyReplaceOutcome` / `applyMultiRegionClearOutcome`; structural editing
(Enter splits / Backspace merges / cross-block delete) with snapshot undo; **lists** (rendering +
`setList` / indent / outdent, incl. an **interactive checklist** — tappable `CheckNode` checkbox + message
round-trip + emoji external share, see the note above), **images** (caption + gap cursor + selection highlight), **tables**
(rendering, cross-cell caret & Tab nav, in-cell editing, row/column insert-delete + per-column alignment +
header row, in-canvas row/column controls + multi-row/column range selection); **formatting**
(bold/italic/strike/inline-code/underline, paragraph styles H1–H3/Body/Quote, alignment, links);
**insert** table/image; the **iOS-standard touch model** (tap-caret, double/triple select, long-press
loupe, handle-drag) + **system edit menu** (Look Up / Translate / Share / Format / basic Writing Tools);
**visual design alignment**; **inline predictive text + marked-text/IME**; **inline custom emoji**; the
**block-view architecture** (every block in its own bounded layer; per-table horizontal scroll; off-screen
**view virtualization**); and the **Telegram-style spoiler effect**.

**The editor is full-WYSIWYG — markdown abandoned.** There is no markdown serializer, and none is planned. Cross-app interchange uses **RTF** (see Phase 5d below).

**Phase 5d rich copy/paste — done.** Within-app fidelity via the private pasteboard UTI `org.telegram.richtexteditor.fragment` carrying a JSON-encoded `Document` fragment (inline formatting incl. custom emoji / mention / date, and paragraph/quote/code/list block structure — preserved across any editor instance, including between chat composers). Cross-app via **RTF** read+write (`public.rtf`) plus a plain-text fallback (`public.utf8-plain-text`) always written/accepted. Multi-line plain paste splits into paragraphs (replaced the old newline→space flattening). Fragment scope = paragraph family + inline; tables and media (images) are NOT carried in a fragment (deferred); image-paste-to-attachment in the composer is a host concern, wired via the paste-media hooks (see below). The extract/splice are pure Core (`Document.extractFragment` / `Document.insertingFragment` in `RichTextEditorCore/Model/DocumentFragment.swift`); the `copy`/`cut`/`paste` responders + the three-representation pasteboard write are in `DocumentCanvasView+Clipboard.swift`; RTF conversion is `RTFConversion.swift`.

**Checklist external share — emoji (added 2026-06-26).** Checklist items serialize to the EXTERNAL RTF +
plain-text reps as an emoji checkbox prefix (`⬜ ` U+2B1C unchecked / `✅ ` U+2705 checked) and are auto-detected
(emoji-only, optional VS16, strips exactly one) on import/paste, via the pure-Core `ChecklistEmojiMarker` codec
(`prefix(checked:)` / `strippingMarker(_:)`) + `externalChecklistPlainText([Block])`. Injected at the export sites
(`RTFConversion.rtfData` prefix + the `NSAttributedString`-fallback per-line detect; the plain rep via
`pasteboardItem` → `externalChecklistPlainText`) and the import sites (`RTFImport.flushParagraph` text + `\listtext`
detect; `plainTextFragment` per-line detect). The in-app private fragment round-trips `checked` losslessly
(`blockPlainText` / `text(in:)` stay marker-free). Accepted limitation: a paragraph the user literally typed
starting with `✅ `/`⬜ ` is read as a checklist on external paste.

**Inline-merging a pasted paragraph is DIRECTIONAL — it keeps the HOST's style, so it must not swallow a
heading (`isInlineMergeable`, fixed 2026-08-17).** The predicate accepted every heading level, so a fragment
whose first (or only) block was a heading folded into the split half of the host paragraph and came out
retyped as the host's style. In the chat composer the host is always a body paragraph, so **pasting a copied
rich message silently lost its headings** — the reported "headings are not pasted". The two directions are not
symmetric and the predicate now takes the host style:
- a plain **body** fragment paragraph carries no block structure, so folding it loses nothing → always folds.
  This one MUST keep folding: pasting text into a heading has to stay in the heading.
- a **heading** fragment paragraph loses its level when folded → folds only into a host of that same style
  (`# X` pasted inside an H1 must not shatter it into three blocks). Anywhere else it stands as its own block,
  and the split-and-assemble path below places it — including mid-paragraph, which now splits the host rather
  than dissolving the heading into it.

`Document.replacingRange` delegates its splice to `insertingFragment`, so the markdown-on-paste two-step path
inherits the same rule. Guarded by `DocumentFragmentHeadingPasteTests` (Core).

**Paste never leaves a spurious empty paragraph (load-bearing, `Document.insertingFragment`).** The multi-block
splice assembles `[headBlock] + middle + [tailPara]`, where head/tail are the host paragraph split at the caret;
it inline-merges a fragment block into a split half only per the directional rule above (`isInlineMergeable`).
Pasting a NON-inline-mergeable LAST block — a **list item (checklists), quote, or code block** — at a paragraph
END (empty tail) would otherwise leave the empty host tail as a trailing empty paragraph (symmetric leading case at
a paragraph start). It now drops an empty OUTERMOST split-half (`headBlock`/`tailPara` only — keyed on
`text.isEmpty`, keeps ≥1 block; INTERIOR fragment empties live in `middle` and are preserved), with the caret →
end of the last pasted block when the tail is dropped. This is the true fix for the "paste adds a trailing empty
paragraph" bug (a trailing empty *in the fragment* — handled earlier at higher layers — was a different, narrower
case; the host-tail empty is the general one and lives here in Core, shared by both editors).

**Paste-media-to-send is host-delegated (2026-06-25).** The editor never embeds pasted media inline — images/GIF/video/stickers go to the chat *send* flow. Two façade hooks (`RichTextEditorView.canPasteMedia` / `onPasteMedia`, both `(() -> Bool)?`, forwarded to `DocumentCanvasView`): `paste(_:)` pastes a TEXT rep if one exists (fragment/RTF/plain — **text wins**), else calls `onPasteMedia?()`; `clipboardCanPerformAction(.paste)` also offers Paste when `canPasteMedia?()` is true (so the menu shows for an image-only clipboard). The editor stays Telegram-UTI-agnostic — the hooks are plain closures the host fills. The chat composer wires them (`ChatTextInputPanelNode.loadTextInputNode`) to a shared `handlePastedMedia(perform:)` (the gif/mp4/heics/png-sticker/jpeg detection extracted from the legacy `chatInputTextNodeShouldPaste`, so both the old and new composers route media identically), restoring the legacy paste-to-send the new composer had lost.

**Host plain-text transform hook + two-step paste (2026-07-24, markdown-on-paste).** `RichTextEditorView.plainTextFragmentTransformer: ((String) -> Document?)?` (forwarded to `DocumentCanvasView`) lets a host convert pasted PLAIN text into a rich `Document` — the editor stays markdown-agnostic (the composer/article hosts inject a CommonMark parser; see `docs/richtext-composer.md` §7). `paste(_:)` consults it only when the pasteboard has **no** richer rep (fragment/RTF) and it returns a non-empty `Document`, then runs `pasteMarkdownTwoStep(plainText:rich:)`: step 1 splices the RAW text (`spliceFragmentInEditing`, one undo step), step 2 — **deferred to the next run-loop cycle** — `replaceRange`s it with `rich`. Two events are REQUIRED for two undo groups: the private `UndoManager` uses default `groupsByEvent`, so a synchronous step 2 would coalesce into one group (one undo would wipe the paste instead of reverting rich→plain). Step 1 sets **`suppressHostChangeNotification`** so `notifyContentSizeChanged()` (gated at its definition — `setBlocks` also calls it) and the `editing {}` trailing `refreshSelectionUI()`/`onSelectionChange()` no-op, keeping the intermediate raw-text state off-screen (no text flash, no caret jump — the caret moves once, in step 2). Undo therefore steps rich → plain → gone.

**RTF export is hand-rolled and emits real tables (2026-06-25, `RTFConversion.swift`).** iOS has **no `NSTextTable` / `NSParagraphStyle.textBlocks`** (AppKit-only) — confirmed by spike — so `NSAttributedString` cannot represent or round-trip a real RTF table; a genuine table can only be produced by emitting the control words by hand. So `rtfData(from:)` now builds the **entire** RTF document by hand for ALL documents (one path; the old `NSAttributedString` export is gone) via one shared inline-run encoder (`inlineRTF`) + `escapeRTFText` (UTF-16 `\u<signed-16>?` escaping). Tables emit `\trowd`/`\trhdr`/`\cellx<cumulative-twips>`/`\intbl`/`\cell`/`\row` (`tableRTF`), so a Telegram table copied into Word/Pages/Notes becomes a **real table**. Parity kept on export (not added): no list markers, no foreground/theme colors, media-in-cell dropped, cell background colors dropped. Custom emoji ride the `tg://emoji?id=<id>&n=<seq>` hyperlink marker (the `&n=` per-export sequence stops adjacent identical emoji from coalescing). Spec/plan: `docs/superpowers/{specs/2026-06-25-richtext-rtf-tables-design.md,plans/2026-06-25-richtext-rtf-tables.md}`.

**RTF import is a custom pure-Foundation parser in Core (2026-06-25, `RichTextEditorCore/Serialization/RTFTokenizer.swift` + `RTFImport.swift`).** Because iOS `NSAttributedString` flattens all block structure (no `NSTextTable`/`textLists`), a custom lexer (`RTFTokenizer`: groups, control words, `\'XX` cp1252, `\uN` signed-16 + surrogate + `\uc` skip, escapes) feeds a group-state document builder (`RTFDocumentParser`) that **reconstructs tables / headings / code / lists** + inline runs/links/emoji from third-party RTF (Word/Pages/web). `fragment(fromRTF:)` (UIKit) tries `RTFImport.document(fromRTF:)` **first** and falls back to the old `NSAttributedString` path only on hard failure (not-RTF / zero blocks) — so exotic RTF is never worse than the flatten, and the editor's own export→import now **round-trips structure losslessly** (the `RTFConversionTests` round-trip suite is the parse-compat gate; pure-Foundation parser is `swift test`-able on macOS via `RTFImportTests`/`RTFImportCorpusTests`). Heuristics (text always survives, only block style may differ): heading by font size (`\fsN/2` ≥23→H1/20–22→H2/18–19→H3), all-mono paragraph→code block, best-effort lists (`\ilvl`/`\listtext` marker→`.bullet`/`.ordered`+level). **Imported links whose anchor text IS their own URL are stripped to plain text** — `fragment(fromRTF:)` runs
`Document.strippingSelfReferentialLinks()` on BOTH the custom-parser and `NSAttributedString`-fallback results.
A copied web link usually has the URL as its label; carrying it as a link run pins a destination the plain URL
already gives, and the sent message would become a `textUrl` instead of a plain, auto-detected URL. A genuine
text link (a label that differs from its target) is kept, as is anything pasted through the private fragment UTI
(no importer involved). The predicate `linkIsSelfReferential(text:url:)` (Core) tolerates the normalizations a
producer applies — an added `mailto:` / `http(s)://` scheme (the latter only when the text carries no scheme of
its own), a percent-encoded path, a trailing `/` — and is a **deliberate duplicate** of `TextFormat`'s
`chatInputLinkIsSelfReferential` (Core cannot import app modules; keep the two rules in step). The composer's
markdown-on-paste path applies the same rule host-side — see `docs/richtext-composer.md` §7.
Non-goals: colors, nested tables, full Word list-table fidelity, images, codepage beyond cp1252. Graceful degradation: unknown control words → no-op; unknown/`{\*\…}` destinations consumed to their `}`; never crashes. **Paragraph breaks (load-bearing, fixed 2026-06-26 — the "pasting removes newlines" bug):** Cocoa/AppKit (TextEdit, Notes, Safari, Mail, Pages — i.e. *every* rich-app copy) serializes a paragraph break as a **backslash immediately followed by a literal CR/LF** (`a\⏎b`), which the RTF spec defines as equivalent to `\par` — NOT a literal `\par` (only the editor's own export and hand-written test RTF use literal `\par`, which is why this slipped the original suite). `RTFTokenizer` therefore maps `\`+CR/LF (CRLF collapsed to one) to a `\par` token; without it every cross-app paste glued all paragraphs into one. **Empty paragraphs survive:** an explicit `\par` is a paragraph *terminator*, so `flushParagraph(allowEmpty:)` emits an empty body paragraph for two consecutive `\par` (a blank line); the implicit end-of-document flush passes `allowEmpty:false`, so a doc with no trailing `\par` gains no spurious empty final paragraph. (Raw, un-backslashed CR/LF stays ignored per spec; `\line` is still a soft in-paragraph break.) Regression-guarded by `RTFImportTests.test_backslash*`/`test_*Par*` + `RTFImportCorpusTests.test_cocoaStyle_*`. Spec/plan: `docs/superpowers/{specs/2026-06-25-richtext-rtf-import-design.md,plans/2026-06-25-richtext-rtf-import.md}`.

**Other open work:** Phase 5e images toolbar (Photos/Files picker, alignment toggle, interactive drag-resize); Phase 6b new
paragraph styles (Subtitle / Code) + a Dash list marker (Caption landed 2026-06-13 as a render-only style); Phase 6c floating pill keyboard toolbar
with active-state (`currentFormatState()`), replacing the crude demo toolbar; block-view **Step 3**
(arbitrary non-focusable embeds); perf follow-ups (viewport-size the wash/chrome overlays; incremental
layout; emoji count-virtualization); spoiler a11y (VoiceOver hiding of unrevealed text) + markdown
`||spoiler||`.

## Workflow

Phase-by-phase, each its own cycle: **brainstorm (`superpowers:brainstorming`) → spec → plan → TDD /
`superpowers:subagent-driven-development` (test after each task) → holistic review →
`superpowers:finishing-a-development-branch`** on a feature branch. Commit messages end with the
`Co-Authored-By` trailer.

**Design docs are not in-tree.** The per-phase specs, plans, spike findings, and handoffs live only in the
pre-move archive at `~/Documents/RichTextEditor/docs/superpowers/{specs,plans,spikes,handoffs}/`. The
foundational two: the main design spec (`2026-05-30-ios-rich-text-editor-design.md`) and the
table-selection **spike findings** (`2026-05-30-table-selection-spike-findings.md` — the API learnings that
drove the single-`UITextInput` architecture and its caveats).

## Verification traps in this package (earned, 2026-08)

Six measurement traps that cost real time during the input-backend seam work. Each is specific to this
package or this repo, and each produced a **green result that meant nothing** until it was caught.

- **`Scripts/iostest.sh` prints one `Executed …` summary PER TARGET, and the LAST is Core's.** Tailing the
  log gives you the Core number (a few hundred) and reads as the whole suite (a few thousand). Always record
  the decomposition: `N executed (UIKit X / S skipped + Core Y), exit 0`.
- **`swift test --filter <Suite>` selects nothing here** and prints `Executed 0 tests, with 0 failures` — a
  vacuous pass. Use `Scripts/iostest.sh <Target>/<Suite>` instead.
- **`swift test` compiles NO canvas code.** All 67 `Canvas/*.swift` files are `#if canImport(UIKit)`-guarded
  and the SwiftPM test build targets macOS, so a mutation planted in one of them proves nothing about
  compilation. Build for the simulator when the claim is "this would/wouldn't compile".
- **`sysctlbyname("kern.osversion")` in a simulator returns the HOST MAC's build** (e.g. `25G76`), not the
  simulated iOS build. Use `ProcessInfo.operatingSystemVersionString`. This matters because two iOS 26.5
  runtimes can be installed (`23F73` and a beta) sharing one identifier, and `device.plist` records only the
  identifier.
- **The `UITextInput` position axis is SPARSE**: a top-level paragraph boundary occupies TWO position slots
  where the text projection emits one `"\n"`. Offsets are NOT character indices. `positionFromPosition:offset:`
  does raw arithmetic then snaps, so aiming at a character index lands one character early past every
  boundary. See `DocumentCanvasView+ComposerSelection.swift` for the existing global↔flat mapper.
- **`BlockLayoutEngine.attributedString` returns the LIVE storage.** `let before = layout.attributedString`
  and comparing it after a mutation compares the object with ITSELF, so the assertion passes no matter what
  happened. A formatting lock-out test passed before its guard existed this way; only a control asserting
  the same gesture DOES change an unguarded block caught it. Copy first
  (`NSAttributedString(attributedString:)`), and commit the control alongside.
- **A canvas nobody retains is deallocated before a debounced pass fires.** `_ = makeCanvas(...)` in a test
  leaves the scheduled work item's `[weak self]` nil, so the pass never runs — and a test asserting
  "nothing was requested" then passes against a dead canvas rather than against the rule. Hold the canvas,
  and give any "nothing happens" test a positive control in the same document.
- **`DispatchQueue.main.async { fulfill }` is not a way to wait for `asyncAfter`.** The timer-backed work
  can land after the plain async block, so the wait returns before the pass has run. Spin the runloop
  (`RunLoop.current.run(until:)`).
- **Never `pgrep -f "<pattern>"` from a watcher whose own command line contains that pattern** — it matches
  itself and the loop never exits. Wait on a PID or a sentinel file. (Cost 42 minutes once.)

**And the general form of all six:** before recording an empty or zero result as evidence, prove the
instrument can produce a non-empty one. A count from an unvalidated command is not a measurement.