@wardic/dom 0.0.0-stage → 1.0.0-rc.2

package/src/internal/measure.ts

@@ -0,0 +1,357 @@
+/**
+ * The DOM reads the Projection system takes at measure time (ADR-0005 / ADR-0009 /
+ * ADR-0012). Two box readers: {@link readLayoutBox} is the raw rect the projection
+ * pass uses (it owns the transform reset at pass level), {@link measureLayoutBox}
+ * a self-resetting single-element read for a lone caller. No framework or Effect dependency — pure DOM — so
+ * this lives in `@wardic/dom` alongside the Projection system that consumes it (a
+ * binding imports it from here).
+ *
+ * It's the surface of the port the engine would move into `@wardic/core` behind (#16, parked
+ * until a non-DOM Environment exists): a DOM read the engine newly needs is added here, named,
+ * rather than written inline in `projection.ts`, measure-time or not: the tree's `contains` too
+ * (#618). #16 maps the reads that file made inline before this rule.
+ */
+import * as Drag from "@wardic/core/Drag"
+import type * as Point from "@wardic/core/Point"
+import type * as Probe from "@wardic/core/Probe"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import { constVoid } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Str from "effect/String"
+import { pending as appearRuns } from "./appear.ts"
+
+/**
+ * Read `el`'s box AS IT CURRENTLY RENDERS — a raw `getBoundingClientRect`, no
+ * transform reset. The projection measure pass uses this because it resets the
+ * whole tree's transforms in its own WRITE phase first, so by the time it reads,
+ * nothing is transformed (see `runMeasurePass`). A lone caller wants
+ * {@link measureLayoutBox} instead.
+ */
+export const readLayoutBox = (el: HTMLElement): Probe.Bounds => {
+  const r = el.getBoundingClientRect()
+  return {
+    x: r.x,
+    y: r.y,
+    width: r.width,
+    height: r.height,
+    top: r.top,
+    right: r.right,
+    bottom: r.bottom,
+    left: r.left,
+  }
+}
+
+/**
+ * Measures `el`'s box where the layout puts it: its own `transform` is cleared for the read and put
+ * back, so an animation running on it doesn't move the reading. Its ancestors' transforms still
+ * count. The box is in the viewport: `x`, `y`, `width`, `height`, and its edges.
+ *
+ * @example
+ * const box = measureLayoutBox(card)
+ * @see https://wardic.dev/reference/solid/layout/measure-layout-box
+ */
+// The inline transform is blanked, the rect read, and the exact prior value restored in a `finally`, so
+// a throwing getBoundingClientRect can't leave the element reset. For one element only: inside a tree
+// pass an ancestor's transform pollutes the reading too, and the `finally` restores before the next
+// element is read, which is why the projection pass hoists the reset out to pass level instead.
+export const measureLayoutBox = (el: HTMLElement): Probe.Bounds => {
+  const saved = el.style.transform
+  el.style.transform = ""
+  // An Appear animation not yet handed off (#245): its CSS transform beats an inline one, not an important one.
+  if (appearRuns(el)) el.style.setProperty("transform", "none", "important")
+  try {
+    return readLayoutBox(el)
+  } finally {
+    el.style.transform = saved
+  }
+}
+
+/**
+ * The bounds on `element`'s x/y that keep it inside `container` (Motion's element `dragConstraints`):
+ * `element` measured without its own transform (its layout box, as Motion's projection measures it),
+ * `container` as it renders. With `mapPoint` (Motion's `transformPagePoint`), each box's corners are
+ * mapped through it first, as Motion's `measurePageBox` maps them: a container inside a zoomed parent
+ * bounds the element in its own pixels.
+ */
+// #273, ADR-0047; #443.
+export const dragBoundsWithin = (element: HTMLElement, container: Element, mapPoint?: (point: Point.Point) => Point.Point): Drag.Bounds =>
+  Drag.boundsWithin(mappedEdges(measureLayoutBox(element), mapPoint), mappedEdges(container.getBoundingClientRect(), mapPoint))
+
+/** A box's edges, its top-left and bottom-right corners mapped through `mapPoint` when given (#443, Motion's `transformBoxPoints`). */
+const mappedEdges = (box: Drag.Edges, mapPoint: ((point: Point.Point) => Point.Point) | undefined): Drag.Edges => {
+  if (Predicate.isUndefined(mapPoint)) return box
+  const topLeft = mapPoint({ x: box.left, y: box.top })
+  const bottomRight = mapPoint({ x: box.right, y: box.bottom })
+  return { left: topLeft.x, top: topLeft.y, right: bottomRight.x, bottom: bottomRight.y }
+}
+
+/** A box's size, in CSS px. */
+export interface BoxSize {
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * A page box's size as it renders (#261, ADR-0018 *Amendment (#261)*): a raw `getBoundingClientRect`,
+ * so a transformed one reads as painted, which the observer's border box doesn't (its echo then reads
+ * as a change, and costs one refresh).
+ */
+export const readBoxSize = (el: Element): BoxSize => {
+  const r = el.getBoundingClientRect()
+  return { width: r.width, height: r.height }
+}
+
+/** The positions that take a box out of its parent's flow, where its size moves nothing else. */
+const OUT_OF_FLOW: ReadonlyArray<string> = ["absolute", "fixed"]
+
+/** Whether `el` takes space in its parent's flow (#261): it isn't absolutely or fixed positioned. */
+export const takesFlowSpace = (el: Element): boolean => Bool.not(Arr.contains(OUT_OF_FLOW, getComputedStyle(el).position))
+
+/** An element's scroll offset (ADR-0012, Motion's `measureScroll`). */
+export const measureScroll = (el: HTMLElement): Point.Point => ({ x: el.scrollLeft, y: el.scrollTop })
+
+/**
+ * Whether `el` is a scroll ROOT (ADR-0012, Motion's `checkIsScrollRoot`): a
+ * `position: fixed` element establishes a viewport-relative frame, so its subtree
+ * doesn't fold in page (or outer-container) scroll.
+ */
+export const isScrollRoot = (el: HTMLElement): boolean => getComputedStyle(el).position === "fixed"
+
+
+/** The properties that move an element on screen without moving its layout (ADR-0012, *Amendment (#136)*). */
+const TRANSFORM_PROPERTIES = ["transform", "translate", "scale", "rotate"] as const
+type TransformProperty = (typeof TRANSFORM_PROPERTIES)[number]
+
+/**
+ * Each property's identity that isn't `none`. An element held at it keeps the containing
+ * block and stacking context its transform gives it, so nothing inside lays out
+ * differently while it's held.
+ */
+const IDENTITY: Readonly<Record<TransformProperty, string>> = {
+  transform: "translate(0px)",
+  translate: "0px",
+  scale: "1",
+  rotate: "0deg",
+}
+
+const isTransformProperty = (property: string): property is TransformProperty =>
+  Arr.contains(TRANSFORM_PROPERTIES as ReadonlyArray<string>, property)
+
+/** A transition on a transform property: `all`, or one of them by name. */
+const transitionsTransform = (property: string): boolean => Bool.or(property === "all", isTransformProperty(property))
+
+/** A CSS time (`0.3s`, `200ms`) in seconds. */
+const seconds = (time: string): number =>
+  Bool.match(Str.endsWith("ms")(time), { onTrue: () => Number.parseFloat(time) / 1000, onFalse: () => Number.parseFloat(time) })
+
+/** The list a computed `transition-*` value holds, one entry per transition. */
+const entries = (value: string): Array<string> => Arr.map(value.split(","), Str.trim)
+
+/**
+ * Whether `style` declares a transition that would run on one of the transform
+ * properties: its name or `all`, with a combined duration (`max(duration, 0) + delay`)
+ * above 0. The durations and delays repeat to the properties' length, as CSS does.
+ */
+const declaresTransformTransition = (style: CSSStyleDeclaration): boolean => {
+  const durations = entries(style.transitionDuration)
+  const delays = entries(style.transitionDelay)
+  return Arr.some(entries(style.transitionProperty), (property, i) =>
+    Bool.and(
+      transitionsTransform(property),
+      Math.max(seconds(durations[i % durations.length]), 0) + seconds(delays[i % delays.length]) > 0,
+    ))
+}
+
+/** A computed transform property that moves its element: set, and not `none` (`""` is unsupported, or no style). */
+const isMoving = (value: string): boolean => Bool.and(Str.isNonEmpty(value), value !== "none")
+
+/** What the Measure pass needs from an element's style to hold its transform. */
+export interface TransformStyle {
+  /** The transform properties that aren't `none`. Empty: nothing moves it. */
+  readonly moved: ReadonlyArray<TransformProperty>
+  /** Whether a CSS transition is declared on one of them. */
+  readonly transitioned: boolean
+}
+
+/**
+ * Whether one of `style`'s transform properties moves its element. Read through the
+ * properties' accessors, which cost less than `getPropertyValue` (0.57 against 0.70 µs for
+ * the four in Chromium 147), and nothing is allocated.
+ */
+const movesAny = (style: CSSStyleDeclaration): boolean =>
+  Bool.or(Bool.or(isMoving(style.transform), isMoving(style.translate)), Bool.or(isMoving(style.scale), isMoving(style.rotate)))
+
+/**
+ * {@link TransformStyle} from an element's computed style. `getComputedStyle` returns a
+ * live declaration, so a caller that keeps one per element reads the current values each
+ * time without calling it again.
+ */
+export const transformStyleFrom = (style: CSSStyleDeclaration): TransformStyle => {
+  // Most elements carry none: they cost the four reads, and nothing else.
+  if (Bool.not(movesAny(style))) return UNMOVED
+  return {
+    moved: Arr.filter(TRANSFORM_PROPERTIES, (property) => isMoving(style[property])),
+    transitioned: declaresTransformTransition(style),
+  }
+}
+
+/** The answer for an element no transform moves, shared. */
+const UNMOVED: TransformStyle = { moved: [], transitioned: false }
+
+/**
+ * Whether a CSS transition is running on one of `el`'s transform properties. Holding it
+ * would cancel or restart that transition, so the pass leaves it as it is: its offset
+ * stays in the box (the documented limit).
+ */
+export const transitionRunning = (el: Element): boolean =>
+  Arr.some(el.getAnimations(), (animation) => Bool.and(animation instanceof CSSTransition, isTransformProperty((animation as CSSTransition).transitionProperty)))
+
+/** An element the pass can hold: one with an inline style. */
+export type Holdable = Element & ElementCSSInlineStyle
+
+/** Whether `el` has an inline style the pass can hold its transform through. */
+export const isHoldable = (el: Element): el is Holdable => Predicate.hasProperty(el, "style")
+
+/** An element held at its transform's identity for a read, and what to put back. */
+export interface TransformHold {
+  readonly element: Holdable
+  /** Each held property's own inline value and priority (`""` for none). */
+  readonly saved: ReadonlyArray<readonly [TransformProperty, string, string]>
+  /** The inline `transition-property` and priority, when the hold turned transitions off. */
+  readonly transition: Option.Option<readonly [string, string]>
+}
+
+/** Put an inline property back as it was: removed when it had no inline value. */
+const restoreProperty = (inline: CSSStyleDeclaration, property: string, value: string, priority: string): void =>
+  Bool.match(Str.isEmpty(value), {
+    onTrue: () => {
+      inline.removeProperty(property)
+    },
+    onFalse: () => inline.setProperty(property, value, priority),
+  })
+
+/**
+ * Hold `el`'s transform properties at their identity (ADR-0012, *Amendment (#136)*):
+ * inline and `!important`, so a stylesheet rule, a CSS animation and a Web Animation
+ * all give way. An element with a transition declared on one of them also gets
+ * `transition-property: none` for the hold, so it starts none.
+ */
+export const holdTransform = (el: Holdable, style: TransformStyle): TransformHold => {
+  const inline = el.style
+  const saved = Arr.map(style.moved, (property) => [property, inline.getPropertyValue(property), inline.getPropertyPriority(property)] as const)
+  const transition = Bool.match(style.transitioned, {
+    onFalse: () => Option.none<readonly [string, string]>(),
+    onTrue: () => Option.some([inline.getPropertyValue("transition-property"), inline.getPropertyPriority("transition-property")] as const),
+  })
+  if (Option.isSome(transition)) inline.setProperty("transition-property", "none", "important")
+  Arr.forEach(style.moved, (property) => inline.setProperty(property, IDENTITY[property], "important"))
+  return { element: el, saved, transition }
+}
+
+/**
+ * Put back what {@link holdTransform} replaced. The elements whose transitions it turned
+ * off get their transform back first, then a style read, then their transition, so the
+ * return from identity starts no transition either.
+ */
+export const releaseTransforms = (holds: ReadonlyArray<TransformHold>): void => {
+  Arr.forEach(holds, (hold) => Arr.forEach(hold.saved, ([property, value, priority]) => restoreProperty(hold.element.style, property, value, priority)))
+  const transitioned = Arr.filter(holds, (hold) => Option.isSome(hold.transition))
+  Arr.forEach(transitioned, (hold) => getComputedStyle(hold.element).getPropertyValue("transform"))
+  Arr.forEach(transitioned, (hold) =>
+    Option.match(hold.transition, {
+      onNone: constVoid,
+      onSome: ([value, priority]) => restoreProperty(hold.element.style, "transition-property", value, priority),
+    }))
+}
+
+/** The inline properties a sticky element is held unstuck through (#578). */
+const UNSTUCK: ReadonlyArray<readonly [string, string]> = [
+  ["position", "relative"],
+  ["top", "auto"],
+  ["right", "auto"],
+  ["bottom", "auto"],
+  ["left", "auto"],
+]
+
+/** A `position: sticky` element held at its static place for a read (#578), and what to put back. */
+export interface StickyHold {
+  readonly element: Holdable
+  /** Each held property's own inline value and priority (`""` for none). */
+  readonly saved: ReadonlyArray<readonly [string, string, string]>
+}
+
+/**
+ * Hold a `position: sticky` element at its static place (ADR-0012, *Amendment (#578)*):
+ * `position: relative` with every inset `auto`, inline and `!important`, so it's offset by
+ * nothing and still positioned, the containing block of what's absolute inside it. Neither
+ * the flow around it nor the scroll moves: a sticky element's offset takes no space.
+ */
+export const holdUnstuck = (el: Holdable): StickyHold => {
+  const inline = el.style
+  const saved = Arr.map(UNSTUCK, ([property]) => [property, inline.getPropertyValue(property), inline.getPropertyPriority(property)] as const)
+  Arr.forEach(UNSTUCK, ([property, value]) => inline.setProperty(property, value, "important"))
+  return { element: el, saved }
+}
+
+/** Put back what {@link holdUnstuck} replaced. */
+export const releaseUnstuck = (holds: ReadonlyArray<StickyHold>): void =>
+  Arr.forEach(holds, (hold) => Arr.forEach(hold.saved, ([property, value, priority]) => restoreProperty(hold.element.style, property, value, priority)))
+
+/**
+ * The document's scroll offset (the page/window scroll, ADR-0012, Motion's
+ * `DocumentProjectionNode` root). Folded into every box unless it sits in a scroll
+ * root. SSR-safe (returns origin when there is no document).
+ */
+export const measureDocumentScroll = (): Point.Point => {
+  const page = (globalThis as { readonly document?: Document }).document
+  if (Predicate.isUndefined(page)) return { x: 0, y: 0 }
+  const doc = page.documentElement
+  // In quirks mode the body scrolls, and `documentElement` reads 0. Per pass: plain reads.
+  const body = page.body as HTMLElement | null
+  if (Predicate.isNull(body)) return { x: doc.scrollLeft, y: doc.scrollTop }
+  return { x: doc.scrollLeft || body.scrollLeft, y: doc.scrollTop || body.scrollTop }
+}
+
+export { readScrollStyle, scrollersOf, scrollStyleFrom, type ScrollStyle } from "./scrollers.ts"
+
+/** Whether `inner` is `outer` or inside it, in the DOM's tree: the engine's one question of the tree (#618). */
+export const contains = (outer: Node, inner: Node): boolean => outer.contains(inner)
+
+/** `el`'s computed opacity, as a number: a Crossfade's fade from where its leaver is drawn (#618). */
+export const readOpacity = (el: Element): number => Number(getComputedStyle(el).opacity)
+
+/** A scale corrector's key and the CSS property it reads (#443). */
+export interface CorrectedKey {
+  readonly key: string
+  readonly cssKey: string
+}
+
+/** The computed values of `keys` on `el` (#443), by key: an empty one, or `none`, left out. One style read. */
+export const readCustomBases = (el: Element, keys: ReadonlyArray<CorrectedKey>): Readonly<Record<string, string>> => {
+  const style = getComputedStyle(el)
+  const out: Record<string, string> = {}
+  for (const corrected of keys) {
+    const value = style.getPropertyValue(corrected.cssKey).trim()
+    if (value !== "" && value !== "none") out[corrected.key] = value
+  }
+  return out
+}
+
+/**
+ * Each of `els`' offsets from its static place (#578): its box as it's drawn, less its box held
+ * unstuck. All held at once, so it costs one layout for them all, then one more after the release.
+ */
+export const readStickyShifts = (els: Iterable<HTMLElement>): Map<Element, Point.Point> => {
+  const list = Arr.fromIterable(els)
+  const stuck = Arr.map(list, (el) => el.getBoundingClientRect())
+  const holds = Arr.map(list, holdUnstuck)
+  let unstuck: ReadonlyArray<DOMRect> = []
+  try {
+    unstuck = Arr.map(list, (el) => el.getBoundingClientRect())
+  } finally {
+    releaseUnstuck(holds)
+  }
+  return new Map(Arr.map(list, (el, i) => [el, { x: stuck[i].left - unstuck[i].left, y: stuck[i].top - unstuck[i].top }] as const))
+}

package/src/internal/measured-pairs.ts

@@ -0,0 +1,297 @@
+/**
+ * **Measured pairs** (#430, CONTEXT.md; Motion's `DOMKeyframesResolver`, `.reference/motion` at
+ * `16c6122`): a positional key whose start and target differ in type (`"auto"`, `"50%"` against a
+ * length in px, a `calc()` on one side) is measured in px at both ends, its leg runs between them,
+ * and it lands on its target as given.
+ *
+ * - **Which keys:** `width`, `height`, `top`, `left`, `right`, `bottom`, and the translates `x`, `y`,
+ *   `translateX`, `translateY`: Motion's `positionalKeys` with a measurement (`positionalValues`).
+ * - **When** (#430's Q2): every pair a task asks for is measured in one batch, in a microtask at the
+ *   end of that task, before its paint (ADR-0018's timing): each start read, each target written
+ *   inline, the page laid out once, each target read, every style restored. Motion's
+ *   `measureAllKeyframes`. Nothing paints the target, and a `ResizeObserver` never reports it.
+ * - **An end already in px** (a number, a px length) is taken as given: only `auto`, a percentage, a
+ *   `calc()` or another unit is read from the layout.
+ * - **The reads:** a size from the computed style, which a transform doesn't change, else from the
+ *   box (an element with none of its own, inline: Motion's `measureDimension`); an inset from the
+ *   computed style, else, for `right` and `bottom`, Motion's sum from `top` or `left` and the box,
+ *   read with the element's transform off; a translate from the computed transform's matrix.
+ *
+ * A binding asks with {@link measure} at a Retarget, which returns each pair as asked
+ * ({@link Requested}), and its leg reads each one {@link measured} at its first step, a tick after the
+ * batch: a new record with its px, none if the batch couldn't read it.
+ */
+import * as Interpolator from "@wardic/core/Interpolator"
+import type * as Values from "@wardic/core/Values"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Rec from "effect/Record"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { project } from "./renderer.ts"
+
+/** The keys a Measured pair can be on (Motion's positional keys with a measurement). */
+const SIZES: ReadonlySet<string> = new Set(["width", "height"])
+const INSETS: ReadonlySet<string> = new Set(["top", "left", "right", "bottom"])
+const TRANSLATES: ReadonlySet<string> = new Set(["x", "y", "translateX", "translateY"])
+
+/** Every key a Measured pair can be on: one lookup per key, per Retarget (#460). */
+const MEASURABLE: ReadonlySet<string> = new Set([...SIZES, ...INSETS, ...TRANSLATES])
+
+/** Whether `key` can be a Measured pair. */
+const isMeasurable = (key: string): boolean => MEASURABLE.has(key)
+
+/**
+ * A value's type, as a Measured pair compares them: a number or a px length is `px`; `auto`; a
+ * `calc()` or `var()`; any other unit; `undefined` for what isn't a length. Per key, per Retarget: a
+ * number, nearly every translate's, makes nothing.
+ */
+const kindOf = (value: number | string): string | undefined => {
+  if (Predicate.isNumber(value)) return "px"
+  const text = value.trim()
+  if (text === "auto") return "auto"
+  if (/^(calc|var|min|max|clamp)\(/.test(text)) return "calc"
+  return Option.getOrUndefined(Option.map(Interpolator.unitOf(text), (unit) => Bool.match(Bool.or(unit === "", unit === "px"), { onTrue: () => "px", onFalse: () => unit })))
+}
+
+/**
+ * Whether `key` from `from` to `to` needs measuring, a Measured pair: a key that can be measured, whose
+ * two ends are lengths, `auto` or a `calc()`, of different types. Two of one type blend as ever.
+ */
+// #430; `needs`, not a type guard's `is…` name (#618, A3).
+export const needs = (key: string, from: number | string, to: number | string): boolean => {
+  if (Bool.not(isMeasurable(key))) return false
+  const a = kindOf(from)
+  if (Predicate.isUndefined(a)) return false
+  const b = kindOf(to)
+  if (Predicate.isUndefined(b)) return false
+  return a !== b
+}
+
+/** One Measured pair as asked for: its key, and its ends as given. */
+// #430; split from the measured one (#618, A1): the batch wrote its px into the asker's record.
+export interface Requested {
+  /** The key. */
+  readonly key: string
+  /** Its start, as given. */
+  readonly from: number | string
+  /** Its target, as given. */
+  readonly to: number | string
+}
+
+/** One Measured pair its batch has read: as asked, with each end in px. */
+export interface Measured extends Requested {
+  /** Its start in px. */
+  readonly fromPx: number
+  /** Its target in px. */
+  readonly toPx: number
+}
+
+/** A pair as its batch reads it: each end's px so far. */
+interface Slot {
+  readonly pair: Requested
+  fromPx: number | undefined
+  toPx: number | undefined
+}
+
+/** An element's pairs in a batch, and the values it draws now, which a translate's transform is built from. */
+interface Request {
+  readonly element: HTMLElement
+  readonly slots: ReadonlyArray<Slot>
+  readonly values: Values.Values
+}
+
+// Module state (#460, Q7): each pair its batch has read, by the pair as asked, kept as long as its asker
+// keeps that pair.
+const read = new WeakMap<Requested, Measured>()
+
+/**
+ * `pair` with its px, once its end-of-task batch has read both its ends: none before that batch, and
+ * none if it couldn't read one, which the animation takes as a switch.
+ */
+// #618 (A1).
+export const measured = (pair: Requested): Option.Option<Measured> => Option.fromUndefinedOr(read.get(pair))
+
+/** The pairs this task asked for, measured at its end. */
+// Module state (#460, Q7): the page's one batch, so every provider's pairs share one read pass a task.
+let queued: Array<Request> = []
+// Module state (#460, Q7): the page's one end-of-task batch across providers.
+let scheduled = false
+
+/**
+ * Measures `pairs` on `element` at the end of this task, with every other element's in the same batch:
+ * each pair, as asked, {@link measured} before the next tick. `values` are what the element draws now,
+ * its other transforms among them.
+ */
+// #430's Q2.
+export const measure = (
+  element: HTMLElement,
+  pairs: Readonly<Record<string, { readonly from: number | string; readonly to: number | string }>>,
+  values: Values.Values,
+): Readonly<Record<string, Requested>> => {
+  const made = Rec.map(pairs, ({ from, to }, key): Requested => ({ key, from, to }))
+  queued.push({ element, slots: Arr.map(Rec.values(made), (pair): Slot => ({ pair, fromPx: undefined, toPx: undefined })), values })
+  if (Bool.not(scheduled)) {
+    scheduled = true
+    queueMicrotask(flush)
+  }
+  return made
+}
+
+/** A length's CSS text, as a style property takes it: a number in px. */
+const cssOf = (value: number | string): string => Bool.match(Predicate.isNumber(value), { onTrue: () => `${value as number}px`, onFalse: () => value as string })
+
+/**
+ * An end already in px (#430): a number, or a px length, taken as given, not read from the layout.
+ * So an explicit first stop (`[0, "auto"]`) starts at it, where Motion's `measureInitialState` reads
+ * the element over it, and a target in px is never written to be read.
+ */
+const givenPx = (value: number | string): number | undefined => {
+  if (kindOf(value) !== "px") return undefined
+  if (Predicate.isNumber(value)) return value
+  return Option.getOrUndefined(pxOf(value))
+}
+
+/** A number read from CSS text, `None` when it isn't one (`auto`). */
+const pxOf = (text: string): Option.Option<number> => Option.liftPredicate(Number.parseFloat(text), Number.isFinite)
+
+/** A size read from the box, as Motion's `measureDimension`: the border box, less the padding for a content box. */
+const sizeFromBox = (element: HTMLElement, style: CSSStyleDeclaration, key: string): number => {
+  const box = element.getBoundingClientRect()
+  const size = Bool.match(key === "width", { onTrue: () => box.width, onFalse: () => box.height })
+  if (style.boxSizing === "border-box") return size
+  const [start, end] = Bool.match(key === "width", {
+    onTrue: () => [style.paddingLeft, style.paddingRight] as const,
+    onFalse: () => [style.paddingTop, style.paddingBottom] as const,
+  })
+  return size - Option.getOrElse(pxOf(start), () => 0) - Option.getOrElse(pxOf(end), () => 0)
+}
+
+/** An inset Motion reads from the box (`right`, `bottom`): its opposite inset and the box's size, the element's transform off. */
+const insetFromBox = (element: HTMLElement, style: CSSStyleDeclaration, key: string): number => {
+  const transform = element.style.transform
+  element.style.transform = "none"
+  const box = element.getBoundingClientRect()
+  element.style.transform = transform
+  const [opposite, size] = Bool.match(key === "right", { onTrue: () => [style.left, box.width] as const, onFalse: () => [style.top, box.height] as const })
+  return Option.getOrElse(pxOf(opposite), () => 0) + size
+}
+
+/** A translate read from the computed transform's matrix. */
+const translateOf = (style: CSSStyleDeclaration, key: string): number => {
+  const matrix = new DOMMatrix(Bool.match(style.transform === "none", { onTrue: () => "matrix(1, 0, 0, 1, 0, 0)", onFalse: () => style.transform }))
+  return Bool.match(Bool.or(key === "x", key === "translateX"), { onTrue: () => matrix.m41, onFalse: () => matrix.m42 })
+}
+
+/** `key`'s value in px as `element` lays out now. */
+const readPx = (element: HTMLElement, style: CSSStyleDeclaration, key: string): number => {
+  if (TRANSLATES.has(key)) return translateOf(style, key)
+  const read = pxOf(style.getPropertyValue(key))
+  if (Option.isSome(read)) return read.value
+  if (SIZES.has(key)) return sizeFromBox(element, style, key)
+  if (Bool.or(key === "right", key === "bottom")) return insetFromBox(element, style, key)
+  return 0
+}
+
+/** An inline property as it was before a batch wrote its target, to put back. */
+interface Saved {
+  readonly element: HTMLElement
+  readonly property: string
+  readonly value: string
+  readonly priority: string
+}
+
+/** An inline property as it is now, to put back. */
+const savedOf = (element: HTMLElement, property: string): Saved => ({ element, property, value: element.style.getPropertyValue(property), priority: element.style.getPropertyPriority(property) })
+
+/**
+ * Write `pairs`' translates at their `end` through the element's whole transform, keeping what was
+ * there: the browser lays out any unit, `-100%` included (#594).
+ */
+const writeTranslates = (request: Request, slots: ReadonlyArray<Slot>, end: "from" | "to"): ReadonlyArray<Saved> => {
+  if (slots.length === 0) return []
+  const { element, values } = request
+  const saved = savedOf(element, "transform")
+  const transform = project({ ...values, ...Rec.fromEntries(Arr.map(slots, ({ pair }) => [pair.key, pair[end]] as const)) })["transform"]
+  element.style.setProperty("transform", UndefinedOr.match(transform as string | undefined, { onUndefined: () => "none", onDefined: String }))
+  return [saved]
+}
+
+/** Write each pair's target inline on its element, keeping what was there; a translate through the element's whole transform. */
+const writeTargets = (request: Request): ReadonlyArray<Saved> => {
+  const unread = Arr.filter(request.slots, (slot) => Predicate.isUndefined(slot.toPx))
+  const saved: Array<Saved> = [...writeTranslates(request, Arr.filter(unread, (slot) => TRANSLATES.has(slot.pair.key)), "to")]
+  Arr.forEach(unread, ({ pair }) => {
+    if (TRANSLATES.has(pair.key)) return
+    saved.push(savedOf(request.element, pair.key))
+    request.element.style.setProperty(pair.key, cssOf(pair.to))
+  })
+  return saved
+}
+
+/**
+ * Write each translate pair's start not in px, as a target is (#594): a layout element's transform at
+ * this moment is its projection's, or held off for its Measure pass, so reading it as it is gave 0.
+ */
+const writeTranslateStarts = (request: Request): ReadonlyArray<Saved> =>
+  writeTranslates(request, Arr.filter(request.slots, (slot) => Bool.and(TRANSLATES.has(slot.pair.key), Predicate.isUndefined(slot.fromPx))), "from")
+
+/** Put back what {@link writeTargets} replaced. */
+const restore = (saved: ReadonlyArray<Saved>): void =>
+  Arr.forEach(saved, ({ element, property, value, priority }) =>
+    Bool.match(value === "", {
+      onTrue: () => void element.style.removeProperty(property),
+      onFalse: () => element.style.setProperty(property, value, priority),
+    }))
+
+/**
+ * The batch (#430's Q2): every start read, every target written, every target read, every style
+ * restored, so the page is laid out once for all of them and paints none. A page scrolled by a target
+ * (a height growing above the view) is scrolled back, as Motion's `suspendedScrollY`.
+ */
+const flush = (): void => {
+  const batch = queued
+  queued = []
+  scheduled = false
+  const styles = Arr.map(batch, ({ element }) => getComputedStyle(element))
+  // Each end in px as given.
+  Arr.forEach(batch, (request) => Arr.forEach(request.slots, (slot) => {
+    slot.toPx = givenPx(slot.pair.to)
+    slot.fromPx = givenPx(slot.pair.from)
+  }))
+  // WRITE, READ, WRITE: each translate's start not in px, written alone and read (#594).
+  const starts = Arr.flatMap(batch, writeTranslateStarts)
+  if (Arr.isArrayNonEmpty(starts)) {
+    try {
+      Arr.forEach(batch, (request, i) => Arr.forEach(request.slots, (slot) => {
+        if (Bool.and(TRANSLATES.has(slot.pair.key), Predicate.isUndefined(slot.fromPx))) slot.fromPx = readPx(request.element, UndefinedOr.getOrThrow(styles[i]), slot.pair.key)
+      }))
+    } finally {
+      restore(starts)
+    }
+  }
+  // READ: each other start not already in px, as the element lays out now.
+  Arr.forEach(batch, (request, i) => Arr.forEach(request.slots, (slot) => {
+    if (Predicate.isUndefined(slot.fromPx)) slot.fromPx = readPx(request.element, UndefinedOr.getOrThrow(styles[i]), slot.pair.key)
+  }))
+  const scrollY = globalThis.scrollY
+  // WRITE: each target, inline.
+  const saved = Arr.flatMap(batch, writeTargets)
+  try {
+    // READ: each target not already in px, laid out once.
+    Arr.forEach(batch, (request, i) => Arr.forEach(request.slots, (slot) => {
+      if (Predicate.isUndefined(slot.toPx)) slot.toPx = readPx(request.element, UndefinedOr.getOrThrow(styles[i]), slot.pair.key)
+    }))
+  } finally {
+    // WRITE: every style as it was.
+    restore(saved)
+    if (globalThis.scrollY !== scrollY) globalThis.scrollTo(globalThis.scrollX, scrollY)
+  }
+  // Each pair read at both ends, as a record of its own.
+  Arr.forEach(batch, (request) => Arr.forEach(request.slots, ({ pair, fromPx, toPx }) => {
+    if (Predicate.isUndefined(fromPx)) return
+    if (Predicate.isUndefined(toPx)) return
+    if (Bool.and(Number.isFinite(fromPx), Number.isFinite(toPx))) read.set(pair, { ...pair, fromPx, toPx })
+  }))
+}