react-x11 2.51.0 → 2.52.0

package/docs/architecture/animation.md

@@ -0,0 +1,707 @@
+# Animation in styles: timelines, opacity, transforms, and who interpolates
+
+_Design document, 2026-09-06. Written against master at c9ce902 (react-x11
+2.6.1, ntk ^8.7.0, `@windowkit/appkit` ^0.4.0). File:line references will
+drift with the code; the shape of the argument should not._
+
+---
+
+## 0. TL;DR
+
+The style vocabulary already has two animation shapes — `transition` (a
+change, over so many ms) and `animation` (a loop between two values) — and
+one runtime that drives both: the window's frame clock, JS interpolation,
+a damage claim per frame. That runtime is correct on every backend and is
+the fallback everything below degrades to.
+
+What an author cannot write today, in order of how often it comes up:
+
+1. **A fade.** There is no `opacity`. The ecosystem page opens by saying so.
+2. **A move that does not reflow.** There is no `translate`/`rotate`/`scale`;
+   the Switch thumb slides on `start` and pays a yoga pass per frame for it.
+3. **A timeline that ends.** `animation` loops forever by definition; an
+   entrance, a shake, a pulse-three-times have no spelling.
+4. **More than two stops**, an easing on a transition, a delay, a spring.
+5. **Motion that survives a busy JS thread.** On macOS the retained layer
+   presenter can hand a transition to Core Animation and stop scheduling
+   frames for it; today it sets layer properties per frame like everything
+   else.
+
+The proposal is one vocabulary, four additions, and one execution rule:
+
+- **Easing** becomes cubic-bezier control points under the hood, with names
+  as aliases and springs as a second kind. This is the load-bearing change:
+  it is what lets a JS evaluator and Core Animation agree on the same
+  declaration (§3.1 has the numbers — mapping today's ease-out to CA's
+  _named_ ease-out is 22% off at the peak; to control points it is 0.3%).
+- **`transition`** grows a per-property object form with `easing` and
+  `delay`, and `all` for the shorthand's slot.
+- **`animation`** grows `keyframes`, `repeat` (default `Infinity`, so every
+  existing loop keeps its meaning), `delay`, and `key` to re-trigger. A
+  finite one rests at the declared value when it ends — the rule loops
+  already follow, which turns out to be CSS's `fill-mode: none` for free.
+- **`opacity`, `translateX`, `translateY`, `rotate`, `scaleX`, `scaleY`** as
+  paint-only style properties on both backends. Free on a layer; an
+  offscreen composite on X11, bounded to the subtree, with fast paths for
+  the common cases (a leaf's opacity, a pure translate).
+- **The presenter decides who interpolates.** The node model stays the one
+  source of truth for _what_ is animating and _when it ends_. A presenter
+  may take a property it can express on the node's own layer; anything it
+  declines runs on the JS loop exactly as now. The layer presenter takes
+  paint properties, opacity and transforms; layout properties stay on the
+  JS loop everywhere, because yoga has to run.
+
+Five bridge verbs stand between the layer presenter and that offload
+(§4.4). The first — control-point timing functions — is a prerequisite,
+not an enhancement: without it every existing transition would change its
+look the day it moved to the render server.
+
+**Status, 2026-09-06.** Bridge items 1–8 shipped in `@windowkit/appkit`
+0.5.0 (§4.4). Landed in react-x11 on top of it: the presenter seam of §4.1
+and the PropBox rows of §4.2 (`animate`/`cancel` in
+src/cocoa/presenter.js, the `offloaded` entries in src/nodes/animation.js), with additive
+retargets for lengths and presentation-value retargets for colours, and
+reduce motion on the Cocoa backend (src/desktopsettings.js's `fromMacOS`).
+The vocabulary of §3 — easing, timelines, `opacity`, transforms — is still
+to come; the control-point tables it needs exist (`EASING_CONTROL_POINTS`).
+
+_Since then, `opacity` has landed (#601) — on Cocoa an opacity transition
+or loop runs in the render server (#818) — and so has a loop's `delay`
+(#605). Transform style properties, keyframes and finite timelines have
+not._
+
+## 1. What exists
+
+### 1.1 The vocabulary
+
+`transition: number | { [prop]: ms }` — a number covers every animatable
+property, an object picks them (docs/styling.md "Transitions"). One fixed
+ease-out cubic (`ease`, src/styles.js:1121). A transition starts from what
+is on screen, so an interrupted one reverses from where it got to
+(`_retarget`, src/nodes/animation.js), and it starts at `now()` rather than the
+last frame's timestamp, so an idle window does not find it already over
+(#80). Nothing before a node's first frame transitions — an inserted
+element appears at its style (`_placed`, test/transition-mount.test.js).
+Layout properties may transition and cost a layout pass per frame; enums,
+`zIndex`, `boxShadow` and `backgroundImage` snap (`NOT_ANIMATABLE`,
+src/styles.js:726).
+
+`animation: { [prop]: { from?, to, duration, easing?, alternate? } }` — a
+loop (#352). `from` defaults to the declared value, which is also where the
+property rests whenever the loop is not running. Four named easings,
+`linear` by default because a cycle that eases out stutters at the wrap.
+Phase is a modulo of elapsed time (`animationValueAt`, src/styles.js:965).
+An equal declaration keeps its phase across re-renders (`sameAnimation`).
+It stops when the window is unmapped, minimized or obscured, when anything
+above the node hides it, when the node unmounts or the style drops it, and
+under reduced motion (`_loopsAllowed`, src/nodes/animation.js) — and every one
+of those restarts it from the top when it goes away.
+
+### 1.2 The runtime
+
+One path for both shapes. `_retarget` puts an entry per property into
+`node._anim` and the node into `root._animating`; `flush` calls
+`_advanceAnimations(now())` (src/nodes/animation.js), which claims each
+animating node where it stands, ticks it, and sets `needsPaint`. That claim
+is where the node _was_; a tick on a layout property asks for a layout pass,
+and the pass claims the old and new rect of every node it moves — the
+animating one and whatever it pushed, in flow or not (`_assignAbs`,
+src/nodes/layout.js) — so a layout animation repaints what it moves rather
+than the window (#603). A box that moved and changed nothing else is one
+claim at each end for its whole subtree, clipped to the boxes that clip it
+(`_beginRigidMove`), and the nodes under it that yoga did not lay out again
+are moved with it rather than read back out of yoga (`_followParent`). The
+window keeps asking for frames while `_animating` is non-empty; the
+animation _is_ the repaint loop. `interpolate` (src/styles.js:990) lerps
+numbers, percentages of the same unit, and colours — premultiplied, so a
+fade from `transparent` does not pass through grey.
+
+`withFrameClock` in `react-x11/test` freezes the clock; the loop tests
+(test/animation-loop.test.js) and the transition tests in test/style.test.js
+drive it by hand.
+
+### 1.3 Where the pixels come from
+
+Three presentation paths, and the animation runtime is identical on all of
+them:
+
+| backend                                      | a frame is                                                             | can anything interpolate for us?                      |
+| -------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
+| X11 (ntk / XRender)                          | damage rects → paint walk → XRender                                    | no                                                    |
+| Cocoa, `surface` presenter (**the default**) | the same paint walk into an IOSurface swapchain                        | no — one bitmap per window                            |
+| Cocoa, `layers` presenter (opt-in)           | dirty nodes → per-node visuals → one `CATransaction` of property diffs | **yes** — the render server animates layer properties |
+
+The layer presenter (src/cocoa/presenter.js) keeps a visual per drawn node:
+a **PropBox** for a plain `<box>` (frame, zPosition, hidden, masksToBounds,
+cornerRadius, backgroundColor, borderWidth, borderColor — zero raster), a
+**Raster** for everything else (the node's own paint replayed into a bitmap
+that becomes the layer's `contents`), shape layers for `<svg>`, an overlay
+for scrollbars, and a clip host whose `bounds.origin` is the scroll offset.
+A JS-driven transition on this presenter works today by construction: each
+tick invalidates the node, the frame re-diffs its properties and sends the
+changed ones under `disableActions`. It is the same cost model as X11 with
+a cheaper sink.
+
+It is opt-in — `createRoot({ cocoa: { presenter: 'layers' } })` or
+`REACT_X11_COCOA_PRESENTER=layers` — while docs/macos.md's measure-first
+gate is open. Everything in §4 is about that presenter; on the surface
+presenter there is nothing to hand an animation to.
+
+### 1.4 What the bridge can already do
+
+`@windowkit/appkit`'s verbs, as react-x11 reaches them through `native`
+(src/cocoa/native.js):
+
+- `addAnimation(layer, keyPath, opts, key)` — a `CABasicAnimation`:
+  `from`/`to` (numbers, `[x, y]` points, `[r, g, b, a]` colours), `duration`
+  in **seconds**, `repeat` (a count, or `Infinity`), `autoreverse`, `timing`
+  as one of four **named** curves (`linear`, `easeIn`, `easeOut`,
+  `easeInEaseOut`; anything else is CA's default), and `hold` for
+  `fillMode: forwards` + `removedOnCompletion: NO`.
+- `removeAnimation(layer, key)`, `removeAllAnimations(layer)`.
+- `txBegin({ duration, timing, disableActions })` / `txCommit()` — the
+  implicit-animation route: set a property inside a transaction with a
+  duration and CA animates it.
+- `setLayerProps` accepts `opacity`, `anchorPoint`, `position`, `bounds`,
+  the shadow quartet, and `transform` as
+  `{ translateX, translateY, rotate (radians), scale | scaleX, scaleY }`,
+  composed translate → rotate → scale — CSS's order for the individual
+  transform properties, and the shape §3.4 proposes.
+
+What it cannot do, each of which §4.4 turns into an issue: a timing function
+from control points; a keyframe animation; a spring; a delay (`beginTime`);
+an additive animation; a completion callback; reading a presentation value;
+and the desktop's reduce-motion switch, which on Cocoa never reaches
+`desktopSettings().animations` at all (src/desktopsettings.js reads
+XSETTINGS and nothing else, so a mac reports `animations: true` whatever
+the user set).
+
+## 2. What cannot be said
+
+Concrete, from the examples and the widget set:
+
+- **Fade in a tooltip, a toast, a menu.** No `opacity`. The ecosystem page
+  tells people to animate a colour instead, and every entry on that page
+  exists partly because of this hole.
+- **Hover lift.** `':hover': { scaleX: 1.02, scaleY: 1.02 }` — a paint-only
+  state change that today has no property to change. A state block cannot
+  touch layout, so growing the box is not an option either.
+- **The Switch thumb.** `transition: { start: 120 }` is a layout pass per
+  frame on every backend and can never be offloaded, because `start` is
+  yoga's. As `translateX` it is a paint property: no layout on X11, a
+  `transform.translation.x` animation in the render server on layers.
+- **A shake on a bad password.** Six stops in 300ms, once, and again on the
+  next attempt. Neither shape has a spelling for "once" or for "again".
+- **An entrance.** Slide up and fade in on mount. Nothing may transition
+  before the first frame (correctly — the mount rule), and the loop shape
+  never ends.
+- **A spinner.** `rotate` from 0 to 360, forever — the one loop that is
+  obviously a transform, and the one with no property to loop.
+- **A staggered list.** Delay per row. No `delay`.
+- **A transition with a curve.** `ease-in-out` on a panel slide; a spring on
+  a drag release so it carries the velocity. One fixed curve.
+- **"It kept animating while the app was busy."** Any transition on macOS
+  stalls with the JS thread. docs/macos.md calls this the qualitative gap
+  Tier L exists for; it is not reachable until the presenter takes the
+  animation.
+
+Out of scope here, so nobody expects them: **exit animations** (keeping a
+node mounted after React removed it is a reconciler feature — a deferred
+`removeChild` — and deserves its own design; `onAnimationEnd` below is the
+seam it will need), and **window-level opacity** (a `<popup>` fade is
+`_NET_WM_WINDOW_OPACITY` on X11 and `NSWindow.alphaValue` on Cocoa, a
+different mechanism from a node's).
+
+## 3. The vocabulary
+
+### 3.1 Easing, shared
+
+```ts
+type Easing =
+  | 'linear'
+  | 'ease'
+  | 'ease-in'
+  | 'ease-out'
+  | 'ease-in-out'
+  | [x1: number, y1: number, x2: number, y2: number] // cubic-bezier
+  | {
+      spring: {
+        stiffness?: number;
+        damping?: number;
+        mass?: number;
+        velocity?: number;
+      };
+    };
+```
+
+**The canonical form is the four control points.** Names are aliases
+resolved once, in `styles.js`, to the beziers they already are:
+
+| name          | control points         | today                                   |
+| ------------- | ---------------------- | --------------------------------------- |
+| `linear`      | `[0, 0, 1, 1]`         | `t`                                     |
+| `ease-out`    | `[0.33, 1, 0.68, 1]`   | `1 - (1 - t)^3`, the transition default |
+| `ease-in`     | `[0.32, 0, 0.67, 0]`   | `t^3`                                   |
+| `ease-in-out` | `[0.65, 0, 0.35, 1]`   | the piecewise cubic                     |
+| `ease`        | `[0.25, 0.1, 0.25, 1]` | — (CSS's default, new)                  |
+
+Why this and not the polynomials: **the two evaluators have to agree.** A
+declaration that runs on the JS loop on X11 and in the render server on
+layers must look the same, and CA's only timing primitive is a cubic
+bezier. Sampled at a thousand points (scratch script, not committed), the
+existing curves against their bezier twins differ by at most 0.003
+(ease-out, ease-in) and 0.0095 (ease-in-out) — invisible. The existing
+ease-out against CA's **named** `easeOut` (`[0, 0, 0.58, 1]`) differs by
+**0.216** at t = 0.35 — a visibly different animation. So the bridge's four
+named curves are not a mapping target; control points are, and the JS side
+gets a bezier solver (Newton with a bisection fallback, the shape every
+browser ships, ~40 lines, pure, pinned by a table test against CSS's
+published samples).
+
+**Springs** are the second kind, not a curve: no duration, a settling time
+derived from the physics, and the reason they exist is interruption — a
+retarget carries the current velocity, which is what makes a dragged thing
+let go feel like it was let go. CA's names (`mass`, `stiffness`,
+`damping`, `initialVelocity`) are physical units and are also popmotion's
+and Framer's; use them. A spring is only ever between two values, so it is
+an easing for `transition` and for a two-stop `animation`; a keyframe
+timeline takes beziers per segment. The JS evaluator is the closed-form
+damped oscillator, settling at a displacement threshold; CA's is
+`CASpringAnimation` and reports `settlingDuration`, which is what the
+completion timer uses. Springs are the last thing to land (§7); the
+vocabulary is fixed now so nothing built before them has to move.
+
+### 3.2 `transition`
+
+```js
+transition: 120                                          // as today: everything, ease-out
+transition: { backgroundColor: 120, borderColor: 120 }   // as today
+transition: {
+  all: 120,                                              // the shorthand's slot
+  start: { duration: 160, easing: 'ease-in-out', delay: 40 },
+  scaleX: { easing: { spring: { stiffness: 400, damping: 30 } } },
+}
+```
+
+A property's value is `ms | { duration?, easing?, delay? }`; `all` is the
+default for every animatable property not named, and is not a style
+property, so the object stays one grammar. `duration` may be omitted only
+with a spring. The default easing stays `ease-out` — a change that ends
+looks right slowing into its value — and the default delay is 0.
+
+`transitionFor` returns `{ duration, easing, delay }` instead of a number.
+(The `.d.ts` already declares that shape — `{ duration; delay? } | null`,
+src/style.d.ts:93 — and the JavaScript returns a number: one of #120's
+drifts, closed by this change rather than by editing the declaration.)
+
+`delay` is a start time, nothing more: the transition still reads its
+`from` from what is on screen _when it starts_, so a retarget during the
+delay is a retarget of a transition that has not moved.
+
+### 3.3 `animation`: a timeline, which may end
+
+```js
+animation: {
+  // today's loop, unchanged
+  backgroundColor: { to: '$accent', duration: 900, alternate: true },
+  // an entrance: from somewhere, to the declared value, once
+  opacity:    { from: 0, duration: 200, repeat: 1 },
+  translateY: { from: 8, duration: 200, repeat: 1, easing: 'ease-out' },
+  // a shake, and again on the next attempt
+  translateX: { keyframes: [0, -6, 6, -6, 6, 0], duration: 300, repeat: 1, key: attempt },
+  // a spinner
+  rotate: { from: 0, to: 360, duration: 800 },
+  // a staggered pulse
+  scaleX: { to: 1.1, duration: 600, alternate: true, delay: index * 80 },
+}
+```
+
+Per property, as now — CA needs one animation per key path too, and CSS's
+one-`@keyframes`-many-properties shape would only be a way to write the
+same duration several times. Options:
+
+| key          |                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `from`, `to` | the two-stop form. **Exactly one may be omitted** and defaults to the declared value                                                        |
+| `keyframes`  | the many-stop form, instead of `from`/`to`: values evenly spaced, or `{ at: 0..1, value, easing? }` for placed stops and per-segment curves |
+| `duration`   | one pass, ms                                                                                                                                |
+| `easing`     | over the pass; `linear` default, as now                                                                                                     |
+| `delay`      | before the first pass only                                                                                                                  |
+| `repeat`     | passes; **`Infinity` by default**, so a declaration written today means what it meant                                                       |
+| `alternate`  | as now                                                                                                                                      |
+| `key`        | identity: a changed `key` restarts the timeline from the top, which is how a finite one is played again                                     |
+
+**Where it rests is the declared value — and that is the whole fill-mode
+story.** Loops already have this rule: the property is at its declared
+value before the first frame, off screen, under reduced motion. A finite
+timeline ends and the property is at its declared value. So an entrance is
+"declare the end state, arrive from somewhere else"; a shake ends where it
+began because the author wrote `0` at both ends. There is no `fill:
+'forwards'`, deliberately: a held last frame means the style lies about the
+property from then on, and the author who wants that value can write it.
+A finite timeline whose last stop is not the declared value snaps at the
+end, visibly — which is the declaration being honest, not a bug.
+
+**Start and restart.** A timeline starts on the style swap that introduces
+it — a mount, or a later change — the same moment loops start today. An
+equal declaration keeps its phase (`sameAnimation`, extended to
+`keyframes`, `repeat`, `delay`, `key`); a changed one restarts. A finished
+finite timeline stays finished across re-renders of the same declaration;
+`key` is the one field whose only job is to differ. (`key` reads well in a
+React codebase; `run` was the alternative.)
+
+**Completion.** `onTransitionEnd({ property })` and `onAnimationEnd({
+property })` as element props, per property, fired when the JS clock says
+so — on every presenter, including one that offloaded the pixels, so a
+component can chain or unmount without knowing where the animation ran.
+Loops never fire it. An interrupted transition does not fire it either
+(CSS agrees: `transitioncancel` is a different event, and nothing here
+needs it yet).
+
+**Reduced motion.** The existing split holds and is the simple rule:
+**`animation` is motion for its own sake and never starts under reduced
+motion, finite or not; `transition` is the answer to an input and always
+runs.** A shake and an entrance are the kind of thing the switch exists
+for, and the still frame is the declared value — the same design decision
+`<ProgressBar indeterminate>` already makes for its loop.
+
+### 3.4 `opacity` and the individual transforms
+
+Six paint-only style properties, on both backends:
+
+| property                   | value      | notes                                                      |
+| -------------------------- | ---------- | ---------------------------------------------------------- |
+| `opacity`                  | 0..1       | **group** opacity of the subtree, CSS semantics            |
+| `translateX`, `translateY` | logical px |                                                            |
+| `rotate`                   | degrees    | the bridge takes radians; the presenter converts           |
+| `scaleX`, `scaleY`         | factor     | no `scale` — `<box scale>` is already the zoom (see below) |
+
+Composed translate → rotate → scale about the box centre — CSS's order for
+its individual transform properties and exactly what the bridge's
+`transform` object does. A `transformOrigin` is the obvious later seam;
+centre is CA's default anchor and the case every hover lift and spinner
+wants.
+
+Paint-only means: **state blocks may set them.** A `:hover` that scales a
+card by 2% is a repaint of one node, no layout — the property that was
+missing from the "hover is a repaint, not a render" story. It also means
+layout is untouched: the box yoga computed is where the node _is_; the
+transform is where it is _drawn_, and where the pointer finds it. Hit
+testing maps the point through the inverse (the walk in `events.js` tests
+node rects; a transformed node tests the inverse-mapped point against its
+own rect and passes the mapped point to its children). `paintBounds()` is
+the transformed box's bounding rect, which is what damage, culling and
+`_subtreeBounds()` already consume. `opacity: 0` still hits, as in CSS;
+`pointerEvents: 'none'` is the property for not hitting.
+
+**Not the zoom.** `<box scale={2}>` multiplies every length in the subtree
+and reshapes text at the size it will be drawn at (src/nodes/cascade.js,
+docs/scale.md); it is layout, and it is expensive to change. `scaleX` is
+paint: the rasterized subtree stretched. They are two different tools and
+the transform is the one that animates cheaply; the docs say so in one
+place so the names stop looking like a mistake.
+
+Both animate (they are numbers), both may transition, both go in
+timelines. That is the whole point of choosing individual properties over
+a `transform: 'rotate(45deg) …'` string: the per-property machinery
+interpolates them with no matrix decomposition, and each is one CA key
+path (`opacity`, `transform.translation.x`, `transform.rotation.z`,
+`transform.scale.x`).
+
+### 3.5 Deliberately not proposed
+
+- **CSS strings** (`'200ms ease-in-out'`, `'rotate(45deg)'`). The style
+  language here is numbers and objects; a second grammar inside strings is
+  a parser and a source of errors that arrive as a thing that does not move.
+- **`fill-mode`.** §3.3.
+- **A per-frame callback in the style.** `animation` describes the motion
+  and the renderer runs it — the offload in §4 depends on that being true.
+  The imperative seam for a 2D per-frame draw is still open
+  (docs/styling.md, last paragraph of "Loops"); a `<canvas>` with a value
+  from popmotion is the answer meanwhile, and this proposal makes that
+  cheaper rather than replacing it.
+- **Exit animations.** §2.
+
+## 4. Who interpolates
+
+### 4.1 The rule
+
+**The node model is the source of truth for what is animating and when it
+ends. A presenter may take the pixels.** Concretely, `_retarget` and
+`_updateLoops` keep doing everything they do — the `_anim` entry, the
+start time, `sameAnimation`, the loop-stop rules — and then ask:
+
+```js
+presenter.animate?.(node, prop, entry); // → true: the presenter interpolates
+```
+
+A presenter that answers `true` owns the frames for that entry: the node
+is **not** added to `root._animating` for it, no damage is claimed per
+frame, and the window's frame clock stays idle. The model value goes out
+as it does now — the resolved target, in the disabled-actions transaction
+— and the presenter has attached the motion to the layer. Completion is a
+timer at `delay + duration` (or the spring's settling time), which fires
+`onTransitionEnd`/`onAnimationEnd` and, for a finite timeline, lets the
+property rest. A presenter that answers `false`, has no `animate`, or is the
+X11 painter, gets the JS loop exactly as today. **Every entry has the JS
+loop as its fallback**, so correctness never depends on coverage — the
+same rule the layer presenter already applies to painting (raster per node
+when the property vocabulary runs out).
+
+Retarget and stop go through the same seam: `presenter.cancel(node, prop)`
+before a new `animate`, and from every loop-stop path.
+
+### 4.2 What the layer presenter takes
+
+A property qualifies when it maps to a property **of the node's own layer**
+and changing it does not re-raster that layer:
+
+| style property                                | key path                         | PropBox | Raster         |
+| --------------------------------------------- | -------------------------------- | ------- | -------------- |
+| `backgroundColor`, `borderColor`              | `backgroundColor`, `borderColor` | yes     | no — re-raster |
+| `borderWidth`, `borderRadius`                 | `borderWidth`, `cornerRadius`    | yes     | no             |
+| `opacity`                                     | `opacity`                        | yes     | **yes**        |
+| `translateX/Y`, `rotate`, `scaleX/Y`          | `transform.*`                    | yes     | **yes**        |
+| `boxShadow` components (once it interpolates) | `shadowOpacity/Radius/Offset`    | later   | —              |
+| `color` on `<text>`                           | —                                | —       | no             |
+| any layout property                           | —                                | no      | no             |
+
+The last row is the important one. **Layout properties stay on the JS loop
+on every presenter**, because yoga has to run for the frame to be right —
+a `width` that grows moves its siblings. The one tempting exception, an
+absolutely positioned node's `left`/`top`/`start` as the layer's
+`position`, is deferred: once `translateX` exists, the Switch thumb and
+its kind have a paint property to slide on, which is cheaper on X11 too
+and needs no exception. The `Raster` rows are what make transforms and
+opacity worth more than they look: a paragraph, an image or a registered
+element fades and moves in the render server with its bitmap untouched.
+
+**Mechanics** (per property, inside the frame's transaction):
+
+1. Model value out as today: `visual.set({ backgroundColor: to })` under
+   `disableActions`.
+2. `addAnimation(layer, keyPath, { from, to, duration: ms / 1000, timing:
+[x1, y1, x2, y2], delay }, key)`. CA renders `from` → `to` over the
+   model value and removes itself on completion, leaving the model showing
+   — the standard explicit-animation pattern, no `hold`.
+3. Timer for completion.
+
+**Loops** are `repeat: Infinity` with `autoreverse` for `alternate`, and
+cost **zero JS frames** — the spinner, the pulse and the indeterminate bar
+become a render-server timer. The loop-stop rules still run (they are the
+one truth about whether a loop may run), and each one is a
+`removeAnimation`; a resume is a fresh `addAnimation`, phase reset, as the
+JS loop does now. CA stops compositing an occluded window on its own, so
+the rule costs nothing there and keeps the two backends identical in what
+they promise.
+
+**Interruption** — the "reverse from where it got to" property, which
+test/style.test.js pins for the JS loop and which has to hold here:
+
+- Numeric key paths (`opacity`, `transform.*`, `borderWidth`,
+  `cornerRadius`): **additive** animations, CA's own idiom. The model goes
+  straight to the new target; the animation is `from: old − new, to: 0,
+additive: true`. Several in flight sum, so a retarget mid-flight is
+  continuous and carries its shape — with no readback of anything. This
+  needs the bridge's `additive` flag (§4.4).
+- Colours (CA cannot add colours): the JS side computes where the running
+  animation is from its own clock and the same bezier — within a frame of
+  CA's truth, since both evaluate the same curve — and starts the next one
+  there. `presentationValue(layer, keyPath)` (§4.4) makes it exact later;
+  it is not on the critical path.
+
+**What the presenter needs from the node** is what `_syncPropBox` already
+reads plus the animated entry; the table above is a static map from style
+property to key path plus a check of `visual.isRaster`. It is a small
+addition to src/cocoa/presenter.js, and the cocoa-mock presenter in the
+tests records `addAnimation` calls the same way it records `setLayerProps`.
+
+### 4.3 The surface presenter, and X11
+
+X11 has nothing to offload: one bitmap per window, painted by the X11
+walk, and the JS loop runs. The surface presenter started there too, and
+now takes the same table as §4.2 by **layer promotion** (issue #483,
+docs/macos.md §"Layer promotion"): a plain box with a transition or a loop
+on an offloadable property gets a CALayer of its own above the window's
+bitmap for as long as it animates, where nothing is painted over it, and
+the same `LayerAnimations` books run it in the render server. The bitmap
+keeps the frame for everything else. What this moved in the measure-first
+gate's argument is recorded there, measured. `opacity` is in the table on
+both presenters since #817, on a plain box: its layer is its group, since
+Core Animation fades a layer and its sublayers as one, and promotion keeps
+a box inside a faded one off a layer of its own, which would be outside
+the group. The `Raster` column of §4.2 is not taken by either yet. An
+element that draws its own scene hands over parts of it instead (#819,
+`Node.sprites()`): each a layer under promotion's rules, its `opacity` and
+`transform` animated as keyframes the element computed — a CSS transform
+sampled into matrices, so that the element's interpolation, not Core
+Animation's, is what the render server plays.
+
+### 4.4 Bridge additions (`@windowkit/appkit`)
+
+In the order the offload needs them:
+
+1. **`timing: [x1, y1, x2, y2]`** on `addAnimation` and `txBegin` —
+   `CAMediaTimingFunction functionWithControlPoints:`. **Prerequisite**:
+   §3.1's numbers say the named curves would change every existing
+   transition's look.
+2. **`additive: true`** — one line on the `CABasicAnimation`. What makes
+   retargeting continuous without readback.
+3. **`delay`** — `beginTime = CACurrentMediaTime() + delay`, with
+   `fillMode: backwards` so the layer shows `from` during the delay.
+4. **Keyframes** — `values`, `keyTimes`, `timingFunctions` (one bezier per
+   segment), `calculationMode: linear` (a `CAKeyframeAnimation`).
+5. **Springs** — `CASpringAnimation` with `mass`/`stiffness`/`damping`/
+   `initialVelocity`, returning `settlingDuration` so JS can time completion.
+6. **`presentationValue(layer, keyPath)`** — `presentationLayer` readback;
+   exactness for colour retargets.
+7. **Completion callback** — the animation delegate's `animationDidStop:
+finished:` forwarded through the event callback; makes
+   `onTransitionEnd` exact rather than timer-derived. Optional.
+8. **Reduce motion** — `NSWorkspace.accessibilityDisplayShouldReduceMotion`
+   plus its notification, into `desktopSettings().animations` on the Cocoa
+   app. Independent of this design and already wrong without it.
+
+Each is a verb, not policy, which is the shape the bridge's contract asks
+for (docs/macos.md, "The channel is already node-granular").
+
+Filed as [windowkit/appkit#29](https://github.com/windowkit/appkit/issues/29);
+[windowkit/appkit#30](https://github.com/windowkit/appkit/pull/30) implements
+items 1–7 plus `speed`/`timeOffset` (merged); item 8 is
+[windowkit/appkit#31](https://github.com/windowkit/appkit/issues/31), implemented
+by [windowkit/appkit#32](https://github.com/windowkit/appkit/pull/32). Two
+things the bridge work found that the presenter has to know: CA interpolates
+colours in the display's space, so a colour read back mid-flight is not the
+component midpoint; and a paused animation sampled at exactly its duration
+reads as its start, so an end is sampled a millisecond early.
+
+## 5. What `opacity` and transforms cost on X11
+
+Both are **group** operations on a subtree, and a group needs an offscreen:
+per-op alpha on overlapping children double-blends where they overlap, and
+per-op transforms would rotate each child about its own centre. So:
+
+1. Paint the subtree into an ntk `Surface` the size of `paintBounds()` in
+   device pixels — the same surface family the paint cache and #433's
+   `CocoaSurface` use, behind `app.createSurface` on the Cocoa surface
+   backend and ntk's pixmap on X11.
+2. Composite it back with `ctx.globalAlpha = opacity` and the transform set
+   on the context. ntk's `drawImage` already routes a transformed draw
+   through `SetPictureTransform` with a filter and scales the composite by
+   `globalAlpha` (node_modules/ntk/lib/renderingcontext_2d.js:2046,
+   :4599) — server-side, no readback. Rotation's filter quality and the
+   transformed bounding box are the two things to verify with a pixel test
+   rather than assume.
+
+Per animated frame that is one pixmap the size of the subtree plus one
+composite — bounded to the thing that moves, the way every claim here is.
+Two fast paths cover most of what apps write and skip the offscreen
+entirely:
+
+- **A pure translate**: `ctx.translate` and paint the subtree through it.
+  Every child paints through the same context, clips included. That is
+  the shake, the slide, the entrance, the Switch thumb.
+- **Opacity on a leaf** (a `<box>` with no children, or a `<text>`):
+  multiply the alpha into the fill, border and ink. One node, no group.
+
+`opacity: 1` and identity transforms cost nothing, which keeps the
+properties safe to leave in a style. The offscreen surface is per node,
+kept between frames of one animation and dropped when it ends, and it is
+the paint cache's budget that bounds it (src/paintcache.js's byte budget
+is the pattern; the surface here is not content-keyed, it is a frame
+scratch).
+
+Damage: `_advanceAnimations` already claims the node before the tick, which
+is the old bounding rect. A transform moves nothing in layout, so no pass
+claims the new one for it: the tick claims that too, the pair a layout
+transition gets from the layout pass's diff (`_assignAbs`).
+
+## 6. Where the code goes
+
+- **src/styles.js** — `resolveEasing` (names → control points → a bezier
+  function; the spring solver), `transitionFor` → `{ duration, easing,
+delay }`, `parseAnimation` (`keyframes`, `repeat`, `delay`, `key`; the
+  validation messages name the option and the property as now),
+  `animationValueAt` over a keyframe list (segment lookup, per-segment
+  easing, `repeat` as a cap on the cycle count), `sameAnimation` over the
+  new fields, and the six new properties in `PAINT_PROPS` — which puts
+  them in state blocks and out of `NOT_ANIMATABLE` for free.
+- **src/nodes/** — `_retarget` (easing and delay on the entry; the
+  presenter seam), `_tickAnimations` (finite end → rest at the target,
+  completion events), `_updateLoops` (cancel through the presenter),
+  `paint` (the group path and its two fast paths around
+  `_paintBackground`/`paintContent`/`_paintChildren`), `paintBounds()`
+  and `_subtreeBounds()` (transformed boxes), `_advanceAnimations` (the
+  claim for where a transform moved the box).
+- **src/events.js** — the inverse-mapped hit test.
+- **src/cocoa/presenter.js** — `animate`/`cancel`, the key-path table,
+  `opacity` and `transform` on both visual kinds; the mock presenter
+  records them.
+- **src/types/style.d.ts, src/style.d.ts, test/types/api.tsx** — `Easing`,
+  `Transition`, `AnimationSpec`, the six properties, the two events.
+- **docs/styling.md** ("Transitions", "Loops" → "Timelines"),
+  **docs/macos.md** (the "Animations and transforms" section becomes a
+  pointer here plus the measured result), **docs/ecosystem/animation.md**
+  (delete the "no opacity" constraint; the page shrinks), **docs/system.md**
+  (reduced motion covers finite timelines), **docs/elements.md** (`scale`
+  vs `scaleX`, the events).
+- **Widgets and examples** — Switch on `translateX`; Tooltip fades;
+  ProgressBar unchanged; a shake in the configurator's password field;
+  the website demos that use `transition` still pass `check-demos`.
+- **Tests** — bezier table vs CSS samples and vs the polynomials
+  (test/style.test.js); finite timelines, keyframes, `key` restart, rest at
+  the declared value, `delay` (test/animation-loop.test.js); the mock
+  presenter: a `backgroundColor` transition on a PropBox schedules zero
+  frames and one `addAnimation` with control points, `color` on a `<text>`
+  falls back to the loop, a loop stop removes the animation; pixels: group
+  opacity over overlapping children against a reference composite, a
+  rotate against a pre-rotated reference, the translate fast path
+  byte-identical to the offscreen path (the differential oracle
+  test/dirty-rect.test.js already has, applied here); the hit test through
+  a transform. And a **structural** row in `scripts/bench/presenters-gate.json`:
+  JS frames scheduled per 120ms hover transition on layers — 0 with the
+  offload, ~8 without — the same kind of number the gate already judges.
+
+## 7. Sequencing
+
+Each step ships on both backends and is useful alone; the offload is
+additive on top and can proceed in parallel from step 1.
+
+1. **Easing vocabulary and the `transition` object form** (`all`, per-property
+   `{ duration, easing, delay }`). Small; the bezier solver and its table
+   test are most of it.
+2. **Timelines**: `keyframes`, `repeat`, `delay`, `key`, the completion
+   events, reduced motion over finite timelines.
+3. **`opacity`**: the group path with the leaf fast path on X11 and the
+   surface presenter; `opacity` on both visuals on layers.
+4. **Transforms**: translate first (fast path only, no offscreen — most of
+   the value for a fraction of the work), then rotate and scale over the
+   offscreen with the inverse hit test. Switch moves to `translateX`.
+5. **Layer offload**: bridge items 1–3 (`windowkit/appkit` PRs), then the
+   presenter seam and its mock tests, the gate row, and a measured
+   before/after on a real display the way docs/macos.md "Measured" records
+   them. Items 4–7 follow as the timeline and spring features reach the
+   presenter.
+6. **Springs**: the JS solver, bridge item 5, `easing: { spring }` on
+   transitions.
+
+## 8. Open questions
+
+- **`key` vs `run`** for the restart token (§3.3). Cheap to decide, hard to
+  rename later.
+- **Should a finite timeline snap or ease into the declared value** when its
+  last stop differs? This document says snap, because it is honest and CSS
+  does the same; the alternative — an implicit last stop at the declared
+  value — hides a mismatch behind a nicer default.
+- **Additive colours.** CA cannot; the clock-estimated `from` is within a
+  frame, and the readback verb closes it. Decide whether a frame's error
+  on a 120ms colour retarget is ever visible before building the verb.
+- **Transforms and text selection, carets, scroll**: a transformed
+  `<textinput>` maps its pointer through the inverse like everything else,
+  but its caret and selection geometry are computed in layout space. The
+  first cut may reject transforms on nodes that own an editing surface, or
+  accept a documented gap; a real display will say which.
+- **Whether `opacity` on X11 should take the offscreen at all** for a
+  subtree above a size, or fall back to per-node alpha with the
+  double-blend documented. The paint cache's item cap (`MAX_ITEM_PIXELS`)
+  is the precedent for "past this size, do the simple thing".