iris: add positioned text overflow

docs/PLAN.md

@@ -847,6 +847,27 @@ such as corner radius and text's position within horizontal overflow use
 `Len`. Flexible padding participates in the same proportional allocation as a
 span rather than silently discarding its `rest` component.
 
+**Text overflow is treatment plus position, not alignment** (2026-09-12).
+`TextOverflow` selects `Visible`, `Wrap`, `Hidden`, or the single `Ellipsis`
+treatment. Unwrapped hidden and ellipsized text retains one canonical shaped
+layout and is translated behind a retained mask; the ellipsis is a separately
+shaped presentation glyph, never a byte in the source buffer. Consequently it
+cannot be copied or activate a source span. Selecting the marker selects the
+omitted source range. `overflow_position: Len` places the canonical text only
+when it exceeds its viewport: zero keeps the text start at the viewport start,
+`rel(1)` keeps the text end at the viewport end, and intermediate or animated
+values expose both ends. This is independent of alignment when the viewport is
+spacious. An editable caret that enters clipped content writes the needed
+absolute position back into this same public field; callers animating it own
+stopping their animation when editing begins. Position changes and changes
+among the unwrapped treatments reuse shaping; entering or leaving `Wrap`
+reshapes at the viewport width, while content, font, spans, or density retain
+the normal shape invalidation path.
+An ellipsis marker maps its visually omitted side to one contiguous source
+range. This is exact for ordinary LTR and RTL runs; mixed-bidi text can place
+discontiguous logical ranges on one visual side, which Iris's deliberately
+single-range selection model cannot represent exactly.
+
 `cargo-iris` is an installable Cargo subcommand, rather than a script callers
 must find inside an Iris checkout. `cargo iris apk` builds the Rust `cdylib`
 with cargo-ndk and packages it directly with the installed Android SDK tools: