@solidrt/core 0.0.60 → 0.0.62

package/src/text-input.ts

@@ -5,7 +5,7 @@
 // are policy and belong to the component (the "skin") that composes these.
 
 import { createMemo, createSignal, flush, untrack } from "@solidjs/signals"
-import { getBoundingBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
+import { getLayoutBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
 import type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
 import { onLayout } from "./window"
 
@@ -247,50 +247,111 @@ export type TextEditorLayout = {
  *
  * 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.
+ * jump. They derive from the caret, the lines and the viewport size, so a
+ * frame that changes none of them does no scroll work. The viewport size is
+ * the node's layout box (the untransformed solved box: the lines are drawn in
+ * the node's own frame, so an ancestor's scale must not change the wrap
+ * width), read in onLayout; the post-layout flush drains the update before
+ * paint, so lines and scroll track a caret, text or size change in the same
+ * frame. A size change that re-breaks nothing (an empty field, lines that
+ * still fit, a height-only change) stops at the line placement: the lines,
+ * the caret and everything the caller derives from them keep their values
+ * and re-run nothing, and the placement reads the break inputs through a
+ * memo of its own rather than `input()` (which a caller builds per read),
+ * so a field inside a resizing box costs one placement of its units per
+ * frame, not a flush of its whole graph. Pure geometry: no caret rendering
+ * and no placeholder/visual policy.
  */
 export function createTextEditorLayout(
   viewport: () => { id: number } | undefined,
   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)
+  // Width and height apart: wrapping depends on the width alone, so a
+  // height-only change (a field growing with its content) re-breaks nothing.
+  let [viewportWidth, setViewportWidth] = createSignal(0)
+  let [viewportHeight, setViewportHeight] = createSignal(0)
+
+  // The font as a value: input() builds a fresh options object per read, so
+  // field equality is what lets the metrics below key on the font itself.
+  let font = createMemo(() => input().font, { equals: sameOptions })
+
+  // One space in the font: its height sits the synthesized blank line, its
+  // width is the selection's break sliver. Measured once per font, not once
+  // per placement.
+  let space = createMemo(() => measureText(" ", font()))
 
   let prepared = createMemo(() => {
-    let { text, font, runs } = input()
-    return prepareText(text, { ...font, runs, carets: true })
+    let { text, runs } = input()
+    return prepareText(text, { ...font(), runs, carets: true })
   })
 
+  // What the breaks depend on, apart from the rest of the input: the caller
+  // builds input() per read (a field's value, font, caret and runs - some
+  // twenty reactive reads), and a placement re-run for a viewport width
+  // change must not pay for that. Equal by field, so only a real change
+  // reaches the placement.
+  let breaking = createMemo(
+    (): BreakInput => {
+      let { text, wrap, caretWidth = 0 } = input()
+      return { text, wrap, caretWidth }
+    },
+    { equals: sameBreakInput },
+  )
+
   // 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 }
-  })
+  // Equal placements (same units, same breaks and metrics) keep the previous
+  // value, so nothing downstream re-runs for a width change that changed
+  // no line. Within a changed placement, a line equal to its predecessor
+  // keeps the previous object: a row bound to it (a non-keyed <For> item)
+  // sees no change and writes nothing, so a moved break costs the lines it
+  // touched, not every line of the field.
+  type PlacedLine = EditorLine & { from: number; to: number; hardBreak: boolean }
+  // `holds` is the range of wrap widths [min, max) the breaker yields these
+  // same lines at (see holdRange); the layout handler skips a width inside it.
+  type Placement = { units: TextUnit[]; lines: PlacedLine[]; holds: [number, number] }
+  let placed = createMemo(
+    (prev): Placement => {
+      let { text, wrap, caretWidth } = breaking()
+      // 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, viewportWidth() - 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,
+          hardBreak: line.hardBreak,
+        })
+        y += line.height
+        hardBreak = line.hardBreak
+        line = layoutNextLine(units, line.cursor, width)
+      }
+      if (out.length === 0 || hardBreak) {
+        let n = units.units.length
+        out.push({ start: text.length, end: text.length, y, height: space().height, width: 0, from: n, to: n, hardBreak: false })
+      }
+      if (prev && prev.units === units.units) {
+        for (let i = 0; i < out.length && i < prev.lines.length; i++) {
+          if (sameLine(prev.lines[i]!, out[i]!)) out[i] = prev.lines[i]!
+        }
+      }
+      // Split units are the width's own (a unit wider than it), so those
+      // lines hold for no other width.
+      let holds: [number, number] = units.units === prepared().units ? holdRange(units.units, out) : [Infinity, Infinity]
+      return { units: units.units, lines: out, holds }
+    },
+    { equals: samePlacement },
+  )
   let lines = createMemo((): EditorLine[] => placed().lines)
 
   // The caret stops of a line, left to right, with the pen advanced per unit;
@@ -375,7 +436,7 @@ export function createTextEditorLayout(
     let ls = lines()
     let first = lineOf(start)
     let last = lineOf(end)
-    let breakWidth = measureText(" ", input().font).width
+    let breakWidth = space().width
     let out: SelectionRect[] = []
     for (let i = first; i <= last; i++) {
       let line = ls[i]!
@@ -416,22 +477,60 @@ export function createTextEditorLayout(
     return 0
   }
 
-  onLayout(() => {
-    let node = viewport()
-    if (!node) return
-    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()
+  // Each offset follows from its own previous value: `follow` moves it only
+  // when the caret has left the visible range, so the memo carries the
+  // retained position across recomputes.
+  let scrollX = createMemo((prev: number | undefined): number => {
+    let { caretWidth, wrap } = breaking()
+    if (wrap) return 0
+    let contentWidth = lines().reduce((w, l) => Math.max(w, l.width), 0)
+    let c = caret()
+    return follow(prev ?? 0, c.x, caretWidth, viewportWidth(), contentWidth + caretWidth)
+  })
+  let scrollY = createMemo((prev: number | undefined): number => {
     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()
+    return follow(prev ?? 0, c.y, c.height, viewportHeight(), last.y + last.height)
+  })
 
-    setScrollX(wrap ? 0 : follow(scrollX(), c.x, caretWidth, vw, contentWidth + caretWidth))
-    setScrollY(follow(scrollY(), c.y, c.height, vh, contentHeight))
+  // Whether the lines placed at the last written width are what the breaker
+  // yields at `width` too. Such a width is not written: the write would mark
+  // the whole graph below the placement for a re-check that finds nothing,
+  // which is what a field inside a resizing box paid per frame. So
+  // viewportWidth lags the box by less than a break while wrapping, and a
+  // placement re-run for a text change at the lagging width is checked here
+  // again on that frame and corrected before paint (writes from onLayout
+  // land in the same frame's re-layout; the same holds for the height
+  // below). Unwrapped, the width is the horizontal scroll's extent and is
+  // always written.
+  let keepsBreaks = (width: number): boolean => {
+    let { wrap, caretWidth } = breaking()
+    if (!wrap) return false
+    let [min, max] = placed().holds
+    let w = Math.max(0, width - caretWidth)
+    return w >= min && w < max
+  }
+
+  // The same for the height: a height at which the retained scroll offset
+  // still keeps the caret in view is not written, so the scroll graph stays
+  // untouched while a short field's box grows and shrinks.
+  let keepsScroll = (height: number): boolean => {
+    let ls = lines()
+    let last = ls[ls.length - 1]!
+    let c = caret()
+    let current = scrollY()
+    return follow(current, c.y, c.height, height, last.y + last.height) === current
+  }
+
+  onLayout(() => {
+    let node = viewport()
+    if (!node) return
+    let box = getLayoutBox(node)
+    let width = box?.width ?? 0
+    let height = box?.height ?? 0
+    if (!keepsBreaks(width)) setViewportWidth(width)
+    if (!keepsScroll(height)) setViewportHeight(height)
   })
 
   return { lines, caret, caretLine, offsetAtX, selectionRects, lineAtY, step, scrollX, scrollY }
@@ -480,6 +579,52 @@ function splitWide(prepared: PreparedText, width: number): PreparedText {
   return { text: prepared.text, units }
 }
 
+// The wrap widths [min, max) at which the greedy breaker yields exactly
+// `lines` over `units`: every line's ink fits (min), and no line's first
+// unit fits at the end of the line before it (max), except across a hard
+// break, where it never joins. Greedy breaking is decided line by line on
+// just those two tests, so inside the range the placement is unchanged.
+function holdRange(units: TextUnit[], lines: { from: number; to: number; width: number; hardBreak: boolean }[]): [number, number] {
+  let min = 0
+  let max = Infinity
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i]!
+    if (line.width > min) min = line.width
+    let next = lines[i + 1]
+    if (!next || line.hardBreak || next.from >= units.length) continue
+    let pen = 0
+    for (let u = line.from; u < line.to; u++) pen += units[u]!.advance
+    let join = pen + unitInk(units, next.from)
+    if (join < max) max = join
+  }
+  return [min, max]
+}
+
+type BreakInput = { text: string; wrap: boolean; caretWidth: number }
+
+function sameBreakInput(a: BreakInput, b: BreakInput): boolean {
+  return a.text === b.text && a.wrap === b.wrap && a.caretWidth === b.caretWidth
+}
+
+// Font options compared field by field: the same keys with the same values.
+function sameOptions(a: MeasureTextOptions, b: MeasureTextOptions): boolean {
+  let ka = Object.keys(a) as (keyof MeasureTextOptions)[]
+  let kb = Object.keys(b) as (keyof MeasureTextOptions)[]
+  return ka.length === kb.length && ka.every((k) => a[k] === b[k])
+}
+
+// The same break (text range) at the same place with the same metrics.
+function sameLine(a: EditorLine, b: EditorLine): boolean {
+  return a.start === b.start && a.end === b.end && a.y === b.y && a.height === b.height && a.width === b.width
+}
+
+// Two placements of the same units with the same lines, break for break and
+// metric for metric.
+function samePlacement(a: { units: TextUnit[]; lines: EditorLine[] }, b: { units: TextUnit[]; lines: EditorLine[] }): boolean {
+  if (a.units !== b.units || a.lines.length !== b.lines.length) return false
+  return a.lines.every((l, i) => sameLine(l, b.lines[i]!))
+}
+
 // 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.

package/src/transform.ts

@@ -2,6 +2,8 @@ import { onSettled } from "@solidjs/signals"
 import { on } from "srt:events"
 import type { PointerEvent } from "./types"
 import { arena, type ArenaOwner } from "./arena"
+import { createVelocityTracker, flingVelocity } from "./velocity"
+import type { Velocity } from "./velocity"
 
 // Focal travel or span change in logical pixels before the transform
 // activates; the same threshold createPan uses, so the two race fairly.
@@ -53,7 +55,10 @@ export interface TransformOptions {
   onTransformStart?: () => void
   /** Streams one delta per frame; compose them multiplicatively (scale) / additively (dx, dy, rotation). */
   onTransformMove?: (t: TransformDelta) => void
-  onTransformEnd?: () => void
+  /** The last finger's lift, with the focal point's velocity at it in
+   * parent-frame pixels per second (velocity.ts; zero after a rest or
+   * under the fling minimum). */
+  onTransformEnd?: (velocity: Velocity) => void
 }
 
 // The merged transform recognizer: pan + pinch + rotate as ONE gesture over
@@ -147,6 +152,10 @@ export function createTransform(options: TransformOptions) {
   // immediately would bake a jolt into the next delta. A rebase frame
   // emits nothing.
   let rebase = false
+  // Parent-frame focal positions per delivering flush, for the lift's
+  // velocity; a rebase translates the history by the focal jump so a
+  // finger joining or leaving keeps it continuous.
+  let tracker = createVelocityTracker()
 
   // Centroids in all three frames, the span in window pixels (it feeds the
   // finger-travel gates), the pair angle in the parent frame.
@@ -193,6 +202,7 @@ export function createTransform(options: TransformOptions) {
     pinch = false
     dirty = false
     rebase = false
+    tracker.reset()
   }
   let cancel = reset
   let owner: ArenaOwner = { cancel }
@@ -204,8 +214,12 @@ export function createTransform(options: TransformOptions) {
     if (rebase) {
       // Anchor from same-age positions; emits nothing - an activation or
       // set change must not produce a jump delta. Motion that arrived in
-      // the same batch folds into the anchor.
+      // the same batch folds into the anchor (and into the velocity
+      // history's shift, one frame the fit never sees).
+      let prev = ref
       ref = measure()
+      if (prev) tracker.shift(ref.px - prev.px, ref.py - prev.py)
+      tracker.push(ref.px, ref.py)
       spanBase = ref.span
       smoothSpan = ref.span
       rebase = false
@@ -215,6 +229,7 @@ export function createTransform(options: TransformOptions) {
     if (!dirty || !ref) return
     dirty = false
     let m = measure()
+    tracker.push(m.px, m.py)
     let prevSpan = smoothSpan
     smoothSpan += (m.span - smoothSpan) * SPAN_SMOOTH
     spanRate += (Math.abs(smoothSpan - prevSpan) - spanRate) * QUIET_SMOOTH
@@ -299,6 +314,7 @@ export function createTransform(options: TransformOptions) {
         pinch = Math.abs(m.span - ref.span) >= SLOP
         spanRate = pinch ? 1 : 0
         rebase = true
+        tracker.reset()
         options.onTransformStart?.()
         return
       }
@@ -310,12 +326,16 @@ export function createTransform(options: TransformOptions) {
         arena.release(e.pointerId, owner)
         pointers.delete(e.pointerId)
         if (pointers.size === 0) {
+          // The lift's own position is not measured (no terminator
+          // follows it); the fit over the delivered frames is the speed.
+          let velocity = flingVelocity(tracker.velocity())
           active = false
           ref = null
           pinch = false
           dirty = false
           rebase = false
-          options.onTransformEnd?.()
+          tracker.reset()
+          options.onTransformEnd?.(velocity)
         } else {
           rebase = true
           pinch = pinch && pointers.size >= 2

package/src/types.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="./runtime-modules.d.ts" />
 
 import type { Gradient } from "./color"
+import type { CursorId, CursorName } from "./cursor"
 import type { ProgramId, TextureBindings, TextureId } from "flux:gpu"
 import type { TextInputHints } from "flux:rendertree"
 import type { Element } from "solid-js"
@@ -172,6 +173,11 @@ export interface PaintProps {
   strokeCap?: StrokeCap
   strokeJoin?: StrokeJoin
   strokeMiter?: number
+  /**
+   * Stroke thickness in logical px; default 1 (SVG's). 0 draws no stroke at
+   * all, like CSS `border-width: 0` - never a hairline - so a stroke-only
+   * shape (or a line) at 0 draws nothing.
+   */
   strokeWidth?: number
 }
 
@@ -380,6 +386,13 @@ export interface PointerProps {
    */
   focusable?: boolean
   pointerEvents?: "auto" | "none" | "all"
+  /**
+   * The mouse cursor while this element is hovered: a platform shape by its
+   * CSS name, `"none"` to hide it, or a createCursor handle for an image.
+   * The innermost hovered element that sets one wins; none on the path
+   * means the default arrow. Mouse and pen; touch shows no cursor.
+   */
+  cursor?: CursorName | CursorId
 }
 
 /**
@@ -643,17 +656,22 @@ export interface TransitionProps {
          */
         stagger?: number
         /**
-         * Layout slide: when a layout moves this element (a row removed
-         * above it, one inserted, a `<For>` reorder, a resize), it slides
-         * from where it was painted to its new box on this motion instead
-         * of jumping, and is hit-tested where it is drawn. A reflow
+         * Layout slide: when a layout moves or resizes this element (a row
+         * removed above it, one inserted, a `<For>` reorder, a card growing
+         * to fit more content, a window resize), it slides from the box it
+         * was painted at to its new box on this motion instead of jumping,
+         * position and size, and is painted, clipped, hit-tested and
+         * backdrop-filtered at the box it is drawn at. While its size is in
+         * flight its children are laid out against that box every frame
+         * (text re-wraps, rows re-flow), as under a CSS width transition; a
+         * child's own `layout` slide yields to the parent's motion. A reflow
          * mid-slide retargets (a spring keeps its velocity). Its first
          * layout, a reparent and a `display: none` toggle snap. The slide is
          * parent-relative: a parent that moves carries its children at
          * once, so declare it on every level that should glide. `true`
          * borrows the `all` entry's motion (an error without one); `all`
-         * alone never slides. Position only today: a size change snaps.
-         * Settles with onTransitionEnd property `"layout"`.
+         * alone never slides. Settles with onTransitionEnd property
+         * `"layout"`.
          */
         layout?: Omit<TransitionSpring, "from" | "exit"> | Omit<TransitionTween, "from" | "exit"> | TransitionShorthand | boolean
       } & {
@@ -804,7 +822,16 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * pixels beneath at that point in the frame, so treat it as a deliberate
    * panel, not a casual style. Inside a `repaintBoundary="snapshot"`
    * subtree it sees only that boundary's own offscreen content, never what
-   * is behind the boundary (the same containment `blendMode` has there).
+   * is behind the boundary (the same containment `blendMode` has there),
+   * and under an ancestor with a `filter` it sees that ancestor's
+   * composited layer. An ancestor's `opacity` is not a containment: the
+   * glass keeps its blur through the fade (the runtime re-filters the
+   * window ahead of the fading group at the group's opacity), so a panel
+   * entering with `from: { opacity: 0 }` frosts in as it appears. That
+   * re-filter is an approximation: the group's sharp pixels then draw over
+   * the blurred ones at its opacity, so mid-fade the glass reads partly
+   * sharp, most at a low opacity; exact group blending would need the
+   * capture inside the group's layer, which the renderer cannot do.
    */
   backdropFilter?: FilterProps
 }
@@ -1052,6 +1079,16 @@ export interface TextProps extends PaintProps, PointerProps, TextRunProps {
  */
 export interface TextureProps extends PaintProps, PointerProps {
   src?: TextureId
+  /**
+   * Corner radius, as on a rect: the image is drawn as a rounded rect filled
+   * with the texture, in one draw and with no clip, so a frosted or image
+   * pane keeps rounded corners at the cost of the plain draw (a rounded
+   * `clipRadius` around it costs a tiled GPU a third of the frame per ten
+   * panes while the box is in flight). A single number rounds all four
+   * corners; an array is [top-left, top-right, bottom-right, bottom-left].
+   * Animatable in its single-number form, like a rect's.
+   */
+  radius?: number | [number, number, number, number]
   /**
    * How the texture's pixels map to the element box (CSS object-fit).
    * "fill" (default) stretches; "cover" and "none" crop; "contain" and

package/src/velocity.ts

@@ -0,0 +1,134 @@
+// The velocity tracker every recognizer reads at a lift: the pointer's
+// speed from the positions of its last VELOCITY_WINDOW_MS as a
+// least-squares line, not the last two samples. The final sample before a
+// lift is often stationary, and frame batching makes the last delta a
+// whole frame old, so a two-point estimate reads anything from zero to a
+// jolt; a fit over the window reads the finger's actual speed. One
+// estimator whatever recognizer asks (createPan, createTransform, the
+// pointer feed), so the 2d camera and a control after it never re-derive
+// their own.
+//
+// Samples are positions in whatever frame the caller measures (the
+// recognizers push the node's parent frame, so the velocity applies 1:1
+// as their deltas do; a swipe classifier pushes window pixels, the
+// finger's own travel) with performance.now() at handler time, the
+// precedent in transform.ts: PointerEvent carries no timestamp.
+
+// Fit horizon: Flutter's and Android's VelocityTracker window.
+const VELOCITY_WINDOW_MS = 100
+// Largest speed reported, px/s (Flutter's kMaxFlingVelocity): a sensor
+// glitch cannot launch the content across the world.
+const VELOCITY_MAX = 8000
+// A position unchanged for this long at the read means the finger rested
+// before lifting: the velocity is zero, whatever the window still holds.
+// Measured from the last sample that MOVED, not the newest sample's age:
+// the runtime's resampler delivers an extrapolated step and its correction
+// up to two frames after the finger stopped, and any same-position
+// re-delivery must not restart the clock either.
+const VELOCITY_REST_MS = 50
+// Ring capacity: a 100 ms window holds 12 samples at 120 Hz; the rest is
+// room for a burst of same-frame samples.
+const VELOCITY_SAMPLES = 20
+/** Release speeds under this (px/s, Flutter's kMinFlingVelocity) are not a
+ * fling: a recognizer delivers zero for them, so a finger that slowed to a
+ * stop leaves the content where it is. */
+export const FLING_MIN_VELOCITY = 50
+
+export type Velocity = { vx: number; vy: number }
+
+export interface VelocityTracker {
+  /** Record a position; `at` defaults to performance.now(). */
+  push(x: number, y: number, at?: number): void
+  /** Translate every sample: a recognizer rebasing its reference point
+   * (a finger joining or leaving a transform) keeps the history
+   * continuous instead of dropping it. */
+  shift(dx: number, dy: number): void
+  reset(): void
+  /** The speed at `at` (default now), px/s per axis: a least-squares fit
+   * over the window, zero after a rest, clamped to VELOCITY_MAX. */
+  velocity(at?: number): Velocity
+}
+
+const ZERO: Velocity = { vx: 0, vy: 0 }
+
+/** Zero under FLING_MIN_VELOCITY, else the velocity itself. */
+export let flingVelocity = (v: Velocity): Velocity => (Math.hypot(v.vx, v.vy) < FLING_MIN_VELOCITY ? ZERO : v)
+
+export function createVelocityTracker(): VelocityTracker {
+  let xs = new Float64Array(VELOCITY_SAMPLES)
+  let ys = new Float64Array(VELOCITY_SAMPLES)
+  let ts = new Float64Array(VELOCITY_SAMPLES)
+  // Ring: `count` samples ending at index `head - 1`.
+  let head = 0
+  let count = 0
+  // When the position last changed (the rest rule's clock).
+  let movedAt = -Infinity
+  return {
+    push(x, y, at = performance.now()) {
+      if (count === 0) movedAt = at
+      else {
+        let last = (head - 1 + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+        if (xs[last] !== x || ys[last] !== y) movedAt = at
+      }
+      xs[head] = x
+      ys[head] = y
+      ts[head] = at
+      head = (head + 1) % VELOCITY_SAMPLES
+      if (count < VELOCITY_SAMPLES) count++
+    },
+    shift(dx, dy) {
+      for (let i = 0; i < count; i++) {
+        let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+        xs[k] = xs[k]! + dx
+        ys[k] = ys[k]! + dy
+      }
+    },
+    reset() {
+      head = 0
+      count = 0
+    },
+    velocity(at = performance.now()) {
+      if (count < 2) return ZERO
+      if (at - movedAt > VELOCITY_REST_MS) return ZERO
+      // Means over the window, then the slope of each axis against time.
+      let n = 0
+      let tm = 0
+      let xm = 0
+      let ym = 0
+      for (let i = 0; i < count; i++) {
+        let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+        if (at - ts[k]! > VELOCITY_WINDOW_MS) break
+        n++
+        tm += ts[k]!
+        xm += xs[k]!
+        ym += ys[k]!
+      }
+      if (n < 2) return ZERO
+      tm /= n
+      xm /= n
+      ym /= n
+      let tt = 0
+      let tx = 0
+      let ty = 0
+      for (let i = 0; i < n; i++) {
+        let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+        let dt = ts[k]! - tm
+        tt += dt * dt
+        tx += dt * (xs[k]! - xm)
+        ty += dt * (ys[k]! - ym)
+      }
+      // Every sample the same age (one batched frame): no slope to read.
+      if (tt === 0) return ZERO
+      // Slopes are px per ms; the result is px per second.
+      let vx = (tx / tt) * 1000
+      let vy = (ty / tt) * 1000
+      let speed = Math.hypot(vx, vy)
+      if (speed > VELOCITY_MAX) {
+        let f = VELOCITY_MAX / speed
+        vx *= f
+        vy *= f
+      }
+      return { vx, vy }
+    },
+  }
+}

package/src/video.ts

@@ -8,9 +8,11 @@
 // A plane player (`present: "plane"`, Android) has no texture: the platform
 // composites the picture fullscreen beneath the UI on the video's own clock,
 // and the UI simply draws over it. It exists from open until the owner is
-// disposed, and it streams: the source may be a URL, read as it plays. On a
-// platform without a plane the open fails (error() with kind "no-plane"),
-// and an app that runs everywhere falls back to a texture player itself.
+// disposed. On a platform without a plane the open fails (error() with kind
+// "no-plane"), and an app that runs everywhere falls back to a texture
+// player itself. Both players stream (the source may be a URL, read as it
+// plays) and both run off the frame loop: a texture player's frames are
+// decoded on their own thread and shown at the UI's cadence.
 //
 // The imperative primitive lives in the `flux:video` module; import { open }
 // from "flux:video" for non-reactive use.
@@ -56,9 +58,8 @@ export type VideoStream = {
   /** Pause playback; the current frame stays displayed. */
   pause(): void
   /**
-   * Seek to a time in seconds. A no-op while opening, on a texture player,
-   * and on a source that cannot seek (see `seekable`). While paused the
-   * target frame is shown.
+   * Seek to a time in seconds. A no-op while opening and on a source that
+   * cannot seek (see `seekable`). While paused the target frame is shown.
    */
   seek(seconds: number): void
   /** Whether `seek` does anything (plain read, not a signal). */