@solidrt/core 0.0.50 → 0.0.51

package/src/text-input.ts

@@ -1,11 +1,12 @@
 // Headless text-input mechanism. These primitives own the objective parts of
-// an editable single-line field -- the value buffer (text + caret/selection)
-// and the scroll-to-caret geometry -- and nothing with a UI opinion. Caret
-// blink, keybindings, placeholder and styling are policy and belong to the
-// component (the "skin") that composes these.
+// an editable field -- the value buffer (text + caret/selection) and the line
+// and caret geometry with the scroll that keeps the caret in view -- and
+// nothing with a UI opinion. Caret blink, keybindings, placeholder and styling
+// are policy and belong to the component (the "skin") that composes these.
 
-import { createSignal, flush } from "@solidjs/signals"
-import { getBoundingBox, measureText } from "./core"
+import { createMemo, createSignal, flush, untrack } from "@solidjs/signals"
+import { getBoundingBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
+import type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
 import { onLayout } from "./window"
 
 /**
@@ -31,6 +32,20 @@ export type TextBufferOptions = {
   onInput?: (value: string) => void
   /** Max length; inserts past it are clamped. */
   maxLength?: () => number | undefined
+  /**
+   * The offset one caret step left/right of `offset` in `text`: what a
+   * single Left/Right, Backspace or Delete moves over. Defaults to one code
+   * unit, which splits surrogate pairs and combining marks; an editor with
+   * grapheme geometry (createTextEditorLayout.step) supplies the real one.
+   */
+  step?: (text: string, offset: number, direction: "left" | "right") => number
+  /**
+   * Called before every edit with the range it replaces and the text going
+   * in (already clamped to maxLength), for owners that keep parallel state
+   * over the text (a rich text document's attributed runs). setValue/clear
+   * report a whole-text replace.
+   */
+  onReplace?: (start: number, end: number, text: string) => void
 }
 
 export type TextBuffer = {
@@ -71,8 +86,10 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
   let initial = options.defaultValue ?? ""
   let [internalValue, setInternalValue] = createSignal(initial)
   // The caret starts at the end of the current text: for a controlled buffer
-  // that is the owner's value, which defaultValue does not reflect.
-  let initialCaret = (options.value?.() ?? initial).length
+  // that is the owner's value, which defaultValue does not reflect. A
+  // one-shot read by design, so untracked (the buffer is created in a
+  // component body, where a bare reactive read is flagged).
+  let initialCaret = untrack(() => options.value?.() ?? initial).length
   let [selectionState, setSelectionState] = createSignal<Selection>({
     anchor: initialCaret,
     focus: initialCaret,
@@ -94,18 +111,26 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
 
   let setCaret = (offset: number) => setSelectionState({ anchor: offset, focus: offset })
 
-  // Apply a text edit and place the caret, clamping to maxLength. The flush
+  let step = (text: string, offset: number, direction: "left" | "right"): number => {
+    if (options.step) return Math.max(0, Math.min(options.step(text, offset, direction), text.length))
+    return direction === "left" ? Math.max(0, offset - 1) : Math.min(text.length, offset + 1)
+  }
+
+  // Every edit is a replace of [start, end) by `text`, caret after it. The
+  // inserted text is clamped to what maxLength leaves room for. The flush
   // commits the writes (including a controlled owner's from onInput) before
   // returning: edits must observe each other within one task, because event
   // bursts can dispatch several handlers with no microtask between them
   // (Android IME input arrives as backspace+commit bursts; see
   // okf/backlog/event-burst-stale-signal-reads.md).
-  let apply = (next: string, caret: number) => {
+  let replace = (start: number, end: number, text: string) => {
+    let v = value()
     let max = options.maxLength?.()
-    if (max != null && next.length > max) next = next.slice(0, max)
-    caret = Math.min(caret, next.length)
+    if (max != null) text = text.slice(0, Math.max(0, max - (v.length - (end - start))))
+    options.onReplace?.(start, end, text)
+    let next = v.slice(0, start) + text + v.slice(end)
     if (options.value?.() == null) setInternalValue(next)
-    setCaret(caret)
+    setCaret(start + text.length)
     options.onInput?.(next)
     flush()
   }
@@ -116,23 +141,21 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
     caret: () => selection().focus,
 
     insertText: (text) => {
-      let v = value()
       let [start, end] = range()
-      apply(v.slice(0, start) + text + v.slice(end), start + text.length)
+      replace(start, end, text)
     },
 
     deleteBackward: () => {
-      let v = value()
       let [start, end] = range()
-      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
-      else if (start > 0) apply(v.slice(0, start - 1) + v.slice(start), start - 1)
+      if (start !== end) replace(start, end, "")
+      else if (start > 0) replace(step(value(), start, "left"), start, "")
     },
 
     deleteForward: () => {
       let v = value()
       let [start, end] = range()
-      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
-      else if (end < v.length) apply(v.slice(0, end) + v.slice(end + 1), end)
+      if (start !== end) replace(start, end, "")
+      else if (end < v.length) replace(end, step(v, end, "right"), "")
     },
 
     move: (direction, opts) => {
@@ -146,8 +169,8 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
         return
       }
       let next = focus
-      if (direction === "left") next = Math.max(0, focus - 1)
-      else if (direction === "right") next = Math.min(len, focus + 1)
+      if (direction === "left") next = step(value(), focus, "left")
+      else if (direction === "right") next = step(value(), focus, "right")
       else if (direction === "start") next = 0
       else if (direction === "end") next = len
       setSelectionState({ anchor: extend ? anchor : next, focus: next })
@@ -160,62 +183,276 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
       flush()
     },
 
-    setValue: (next) => apply(next, next.length),
-    clear: () => apply("", 0),
+    setValue: (next) => replace(0, value().length, next),
+    clear: () => replace(0, value().length, ""),
   }
 }
 
-export type CaretScrollInput = {
+export type TextEditorLayoutInput = {
   text: string
-  fontSize: number
-  /** Caret offset into `text`. Defaults to the text end. */
-  caret?: number
+  font: MeasureTextOptions
+  /** Styled ranges over `text` (prepareText `runs`): the geometry then follows per-run fonts. */
+  runs?: TextRunRange[]
+  /** Caret offset into `text`. */
+  caret: number
   /** Px reserved so the caret stays visible at the viewport edge. Default 0. */
   caretWidth?: number
+  /** Break lines at the viewport width; else one line per hard break. */
+  wrap: boolean
+}
+
+/** One drawn line of an editor: `text.slice(start, end)` at `y`, `height` tall. */
+export type EditorLine = {
+  start: number
+  end: number
+  y: number
+  height: number
+  /** Ink width. */
+  width: number
+}
+
+/** The caret's box in content coordinates (before scroll). */
+export type CaretRect = { x: number; y: number; height: number }
+
+export type TextEditorLayout = {
+  lines(): EditorLine[]
+  caret(): CaretRect
+  /** Index into lines() of the line the caret sits on. */
+  caretLine(): number
+  /** The caret position (grapheme boundary) on line `line` nearest to content x. */
+  offsetAtX(line: number, x: number): number
+  /** Index of the line at content y (clamped to the first/last line). */
+  lineAtY(y: number): number
+  /** The caret position one grapheme left/right of `offset`; a break sequence is one step. For createTextBuffer's `step`. */
+  step(offset: number, direction: "left" | "right"): number
+  scrollX(): number
+  scrollY(): number
 }
 
 /**
- * Returns the horizontal scroll offset that keeps the caret within the viewport
- * node. The offset is retained between frames and only adjusted when the caret
- * would fall outside the visible range (scrolled left when the caret runs past
- * the right edge, right when it moves before the left edge), so stationary text
- * does not jump. The viewport width and offset are computed in onLayout and the
- * synchronous flush drains the update before paint, so the scroll tracks a caret
- * or width change in the same frame. Pure geometry: no caret rendering and no
+ * The line and caret geometry of an editable text, plus the scroll offsets
+ * that keep the caret within the viewport node. Lines come from prepareText
+ * (with caret stops) + layoutNextLine at the viewport width (or unbounded
+ * when not wrapping) and are drawn by the caller, one d-text per line. A unit
+ * wider than the wrap width is split into its graphemes first, so long
+ * unbroken text wraps instead of overflowing. An empty text, or one ending in
+ * a hard break, still gets a (blank) last line to sit the caret on. Caret
+ * positions are the units' grapheme stops: the caret x, the nearest position
+ * to an x, and a caret step all come from the same shaping that is drawn.
+ *
+ * The scroll offsets are retained between frames and only adjusted when the
+ * caret would fall outside the visible range, so stationary text does not
+ * jump. The viewport size is read in onLayout and the synchronous flush
+ * drains the update before paint, so lines and scroll track a caret, text or
+ * size change in the same frame. Pure geometry: no caret rendering and no
  * placeholder/visual policy.
  */
-export function createCaretScroll(
+export function createTextEditorLayout(
   viewport: () => { id: number } | undefined,
-  input: () => CaretScrollInput,
-): () => number {
+  input: () => TextEditorLayoutInput,
+): TextEditorLayout {
+  let [viewportSize, setViewportSize] = createSignal({ width: 0, height: 0 }, { equals: (a, b) => a.width === b.width && a.height === b.height })
   let [scrollX, setScrollX] = createSignal(0)
+  let [scrollY, setScrollY] = createSignal(0)
+
+  let prepared = createMemo(() => {
+    let { text, font, runs } = input()
+    return prepareText(text, { ...font, runs, carets: true })
+  })
+
+  // Lines carry their unit range so the caret math walks only their units.
+  type PlacedLine = EditorLine & { from: number; to: number }
+  let placed = createMemo((): { units: TextUnit[]; lines: PlacedLine[] } => {
+    let { text, font, wrap, caretWidth = 0 } = input()
+    // Wrapped lines leave room for the caret at the end of a full line, so a
+    // wrapping editor never scrolls horizontally.
+    let width = wrap ? Math.max(0, viewportSize().width - caretWidth) : Infinity
+    let units = wrap ? splitWide(prepared(), width) : prepared()
+    let out: PlacedLine[] = []
+    let y = 0
+    let cursor = 0
+    let line = layoutNextLine(units, cursor, width)
+    let hardBreak = false
+    while (line) {
+      out.push({ start: line.start, end: line.end, y, height: line.height, width: line.width, from: line.from, to: line.to })
+      y += line.height
+      hardBreak = line.hardBreak
+      line = layoutNextLine(units, line.cursor, width)
+    }
+    if (out.length === 0 || hardBreak) {
+      let height = measureText(" ", font).height
+      let n = units.units.length
+      out.push({ start: text.length, end: text.length, y, height, width: 0, from: n, to: n })
+    }
+    return { units: units.units, lines: out }
+  })
+  let lines = createMemo((): EditorLine[] => placed().lines)
+
+  // The caret stops of a line, left to right, with the pen advanced per unit;
+  // duplicates at unit seams (a unit's end is the next one's start) skipped.
+  let lineStops = (index: number): { offset: number; x: number }[] => {
+    let { units, lines } = placed()
+    let line = lines[index]
+    if (!line) return []
+    let stops: { offset: number; x: number }[] = []
+    let pen = 0
+    for (let u = line.from; u < line.to; u++) {
+      let unit = units[u]!
+      for (let stop of unit.carets ?? []) {
+        let x = pen + stop.x
+        if (stops.length && stops[stops.length - 1]!.offset === stop.offset) continue
+        stops.push({ offset: stop.offset, x })
+      }
+      pen += unit.advance
+    }
+    if (stops.length === 0) stops.push({ offset: line.start, x: 0 })
+    return stops
+  }
+
+  // The line an offset sits on: the first whose range extends past it, so an
+  // offset on a soft-wrap boundary is the start of the next line (one offset
+  // is one position; a caret does not hang after the wrap space, which would
+  // take an affinity flag). The very end of the text is on the last line.
+  let lineOf = (offset: number): number => {
+    let ls = lines()
+    for (let i = 0; i < ls.length; i++) {
+      if (offset < ls[i]!.end) return i
+    }
+    return ls.length - 1
+  }
+  let caretLine = createMemo(() => lineOf(input().caret))
+
+  // The caret sits at the last stop at or before its offset (an offset inside
+  // a grapheme, e.g. from a controlled value, snaps back).
+  let caret = createMemo((): CaretRect => {
+    let offset = input().caret
+    let index = caretLine()
+    let line = lines()[index]!
+    let x = 0
+    for (let stop of lineStops(index)) {
+      if (stop.offset > offset) break
+      x = stop.x
+    }
+    return { x, y: line.y, height: line.height }
+  })
+
+  // Only positions that show on this line are candidates: a boundary offset
+  // that displays on the next line is that line's start, not this one's end.
+  let offsetAtX = (index: number, x: number): number => {
+    let best = lines()[index]?.start ?? 0
+    let bestDistance = Infinity
+    for (let stop of lineStops(index)) {
+      if (lineOf(stop.offset) !== index) continue
+      let d = Math.abs(stop.x - x)
+      if (d < bestDistance) {
+        best = stop.offset
+        bestDistance = d
+      }
+    }
+    return best
+  }
+
+  let lineAtY = (y: number): number => {
+    let ls = lines()
+    let index = 0
+    while (index + 1 < ls.length && ls[index + 1]!.y <= y) index++
+    return index
+  }
+
+  let step = (offset: number, direction: "left" | "right"): number => {
+    let { units } = placed()
+    let text = input().text
+    if (direction === "right") {
+      for (let unit of units) {
+        if (unit.end <= offset) continue
+        for (let stop of unit.carets ?? []) if (stop.offset > offset) return stop.offset
+        // Past the unit's shaped text: over its break characters in one step.
+        return unit.end
+      }
+      return text.length
+    }
+    for (let u = units.length - 1; u >= 0; u--) {
+      let unit = units[u]!
+      if (unit.start >= offset) continue
+      let stops = unit.carets ?? []
+      for (let i = stops.length - 1; i >= 0; i--) if (stops[i]!.offset < offset) return stops[i]!.offset
+      return unit.start
+    }
+    return 0
+  }
 
   onLayout(() => {
     let node = viewport()
     if (!node) return
-    let vw = getBoundingBox(node)?.width ?? 0
-    let { text, fontSize, caret, caretWidth = 0 } = input()
-    let len = text.length
-    let c = caret == null ? len : Math.max(0, Math.min(caret, len))
-
-    let totalWidth = measureText(text, { fontSize }).width
-    let caretX = c >= len ? totalWidth : measureText(text.slice(0, c), { fontSize }).width
-    let maxScroll = Math.max(0, totalWidth + caretWidth - vw)
-
-    let cur = scrollX()
-    let next = cur
-    if (vw <= 0) {
-      next = 0
-    } else if (caretX < cur) {
-      next = caretX
-    } else if (caretX + caretWidth > cur + vw) {
-      next = caretX + caretWidth - vw
-    }
-    next = Math.max(0, Math.min(next, maxScroll))
+    let box = getBoundingBox(node)
+    setViewportSize({ width: box?.width ?? 0, height: box?.height ?? 0 })
+    flush()
+    let { width: vw, height: vh } = viewportSize()
+    let { caretWidth = 0, wrap } = input()
+    let ls = lines()
+    let contentWidth = ls.reduce((w, l) => Math.max(w, l.width), 0)
+    let last = ls[ls.length - 1]!
+    let contentHeight = last.y + last.height
+    let c = caret()
 
-    if (next !== cur) setScrollX(next)
+    setScrollX(wrap ? 0 : follow(scrollX(), c.x, caretWidth, vw, contentWidth + caretWidth))
+    setScrollY(follow(scrollY(), c.y, c.height, vh, contentHeight))
     flush()
   })
 
-  return scrollX
-}
+  return { lines, caret, caretLine, offsetAtX, lineAtY, step, scrollX, scrollY }
+}
+
+// Wrap units wider than `width` (through their glued pieces) split into one
+// unit per grapheme (from their caret stops), so the greedy breaker wraps
+// them like `<text>`'s overflowWrap "anywhere". Everything else is passed
+// through as is.
+function splitWide(prepared: PreparedText, width: number): PreparedText {
+  let all = prepared.units
+  if (!all.some((u, i) => !u.glue && unitInk(all, i) > width)) return prepared
+  let wide = false
+  let units: TextUnit[] = []
+  for (let u = 0; u < all.length; u++) {
+    let unit = all[u]!
+    if (!unit.glue) wide = unitInk(all, u) > width
+    let stops = unit.carets
+    if (!wide || !stops || stops.length <= 2) {
+      units.push(unit)
+      continue
+    }
+    for (let i = 1; i < stops.length; i++) {
+      let a = stops[i - 1]!
+      let b = stops[i]!
+      let last = i === stops.length - 1
+      let advance = last ? unit.advance - a.x : b.x - a.x
+      units.push({
+        text: prepared.text.slice(a.offset, b.offset),
+        start: a.offset,
+        end: last ? unit.end : b.offset,
+        advance,
+        width: Math.max(0, Math.min(b.x, unit.width) - a.x),
+        ascent: unit.ascent,
+        descent: unit.descent,
+        hardBreak: last && unit.hardBreak,
+        glue: i === 1 && unit.glue,
+        run: unit.run,
+        carets: [
+          { offset: a.offset, x: 0 },
+          { offset: b.offset, x: b.x - a.x },
+        ],
+      })
+    }
+  }
+  return { text: prepared.text, units }
+}
+
+// The scroll offset along one axis that keeps [pos, pos + size] within a
+// viewport of `extent`, moved only when it is out of view and clamped to the
+// content.
+function follow(current: number, pos: number, size: number, extent: number, content: number): number {
+  if (extent <= 0) return 0
+  let next = current
+  if (pos < current) next = pos
+  else if (pos + size > current + extent) next = pos + size - extent
+  return Math.max(0, Math.min(next, Math.max(0, content - extent)))
+}

package/src/types.d.ts

@@ -236,6 +236,14 @@ export interface PointerEvent {
    */
   parentX: number
   parentY: number
+  /**
+   * Pointer movement since the previous move event, in logical pixels. Mouse
+   * reports hardware deltas (summed, never lost, and the only motion signal
+   * while the pointer is locked); touch reports position diffs. 0 on
+   * non-move events.
+   */
+  movementX: number
+  movementY: number
   /** Node id whose handler is currently running (bubbling changes it per call). */
   currentTarget: number
   /** Deepest node id of the event's path (the hit leaf). */
@@ -366,6 +374,154 @@ export interface LineGeometryProps {
   y2?: number
 }
 
+// Native transitions (okf/done/native-transitions.md): declared once on
+// the element, applied by the runtime to every later write of the covered
+// properties. JS hands over targets; Rust interpolates every frame, so a
+// running animation costs no JS per frame.
+
+/** A cubic-bezier timing curve: a CSS name or [x1, y1, x2, y2] control values. */
+export type TransitionCurve = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+
+/**
+ * A perceptual spring - the default kind: a bare `{ duration }` is a
+ * critically damped spring. `duration` (ms) is the perceptual settling
+ * time, `bounce` in (-1, 1] the springiness - 0 (the default) settles
+ * without overshoot, positive values overshoot, negative values settle
+ * sluggishly. A new target while the spring runs keeps position and
+ * velocity, so the motion stays continuous - use springs for anything
+ * retargeted while moving.
+ */
+export interface TransitionSpring {
+  duration: number
+  bounce?: number
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * A duration/curve tween, opted into by naming the curve (a tween is
+ * always a specific curve; without one the spec reads as a spring).
+ * Duration in ms. A new target while the tween runs restarts it from the
+ * current value with the full duration (CSS semantics) - designer-timed,
+ * one-shot motion.
+ */
+export interface TransitionTween {
+  duration: number
+  curve: TransitionCurve
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * The shorthand string: `"<duration>ms [curve] [<delay>ms]"` - `"300ms"` is
+ * a bounce-0 spring, `"300ms ease-out"` a tween, `"300ms ease-out 100ms"`
+ * delayed (first time value the duration, second the delay; ms only).
+ * Bounce, bezier control values and `from` need the object form.
+ */
+export type TransitionShorthand = string
+
+export type Transition = TransitionSpring | TransitionTween | TransitionShorthand
+
+/** The property names a transition can cover (numeric scalars). */
+export type TransitionPropName =
+  | "x"
+  | "y"
+  | "w"
+  | "h"
+  | "x1"
+  | "y1"
+  | "x2"
+  | "y2"
+  | "opacity"
+  | "rotate"
+  | "rotateX"
+  | "rotateY"
+  | "scale"
+  | "scaleX"
+  | "scaleY"
+  | "strokeWidth"
+  | "radius"
+  | "color"
+
+/** Payload of onTransitionEnd: which animated property finished. */
+export interface TransitionEndEvent {
+  property: TransitionPropName
+}
+
+export interface TransitionProps {
+  /**
+   * A runtime-side transition of one of this element's properties reached
+   * its target (natural settles only; a cancelled or retargeted animation
+   * does not fire until it finally settles). Delivered to this element
+   * only, no bubbling.
+   */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  /**
+   * Animate later writes of the listed properties instead of snapping:
+   * `transition={{ x: { duration: 400, bounce: 0.2 }, opacity: "200ms ease-out" }}`.
+   * `all` covers every animatable property the element has, and a bare
+   * string is shorthand for it: `transition="300ms ease-out"`. Only
+   * properties the element carries animate (a d-rect has x, a view's x is
+   * its transform); the initial value never animates unless the entry sets
+   * `from` (an enter animation), and a non-numeric write (e.g. null)
+   * cancels the running animation and snaps. `null` clears the
+   * declaration; already-running animations finish.
+   */
+  transition?:
+    | ({
+        all?: Omit<TransitionSpring, "from" | "exit"> | Omit<TransitionTween, "from" | "exit"> | TransitionShorthand
+        /**
+         * Group stagger (ms): every descendant enter (`from`) or exit that
+         * begins in the same frame under this element gets `index * stagger`
+         * of extra delay, in occurrence order (enters and exits cascade
+         * separately). Nearest declaring ancestor wins; it orchestrates
+         * descendants only - ordinary writes and this element's own
+         * lifecycle are unaffected. Adds on top of a per-entry `delay`.
+         */
+        stagger?: number
+      } & {
+        [P in TransitionPropName]?: Transition
+      })
+    | TransitionShorthand
+    | null
+}
+
 // Primitives
 
 export interface WindowProps extends LayoutProps, PointerProps {
@@ -462,9 +618,10 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
   repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
   /**
    * Run this view's rasterized subtree through a GPU program and composite
-   * the result in its place. Requires repaintBoundary="snapshot" (the cost
-   * is snapshot semantics, kept explicit; declared without it the shader is
-   * ignored with a warning). The pass is region-sized and split from content
+   * the result in its place. Requires a snapshot boundary
+   * (repaintBoundary="snapshot" or "snapshot-no-aa"; the cost is snapshot
+   * semantics, kept explicit; declared without one the shader is ignored
+   * with a warning). The pass is region-sized and split from content
    * invalidation: a params-only change re-runs just the pass against the
    * cached snapshot, so animating an effect over a static subtree never
    * re-rasterizes it.
@@ -576,6 +733,17 @@ export interface TextRunProps {
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+  /**
+   * Underline in the run's own color, drawn straight through descenders
+   * (no skip-ink). Position and thickness come from the font's own metrics
+   * unless overridden; a font Impeller resolves through the system fallback
+   * gets the shipped Noto values.
+   */
+  textDecoration?: "none" | "underline"
+  /** Pixels from the baseline to the top of the underline. */
+  textUnderlineOffset?: number
+  /** Underline thickness in pixels. */
+  textDecorationThickness?: number
 }
 
 /**