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

package/src/internal/auto-scroll.ts

@@ -0,0 +1,176 @@
+/**
+ * The DOM's **Auto-scroll** (ADR-0020, grill decision 16): Motion's
+ * (Reorder/utils/auto-scroll.ts at 16c61222c4166bbef5ff6ab0051192faa79fa8c8,
+ * https://github.com/motiondivision/motion/blob/16c61222c4166bbef5ff6ab0051192faa79fa8c8/packages/framer-motion/src/components/Reorder/utils/auto-scroll.ts)
+ * over core's pure `AutoScroll.step`. While a **Reorder group**'s item is dragged near
+ * the visible edge of the group's scroller, moving toward it, each drag update scrolls
+ * the scroller; the scroll then moves the held pointer (a synthetic move), whose update
+ * scrolls again, so it keeps scrolling while the pointer holds still in the zone.
+ */
+import * as AutoScroll from "@wardic/core/AutoScroll"
+import type * as Point from "@wardic/core/Point"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Equal from "effect/Equal"
+import { constVoid } from "effect/Function"
+import * as Match from "effect/Match"
+import * as Option from "effect/Option"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { heldScrollShift } from "./input.ts"
+
+/** The overflow values Motion's auto-scroll scrolls (auto-scroll.ts:4). */
+const SCROLLS: ReadonlySet<string> = new Set(["auto", "scroll"])
+
+type Axis = "x" | "y"
+
+/** A scroller on one axis: an element, or the document (the window's scroll). */
+type Scroller = { readonly kind: "element"; readonly el: HTMLElement } | { readonly kind: "document"; readonly win: Window }
+
+/** A scroller's extent on one axis: its visible edges in viewport px, its scroll, and how far it can scroll. */
+interface View {
+  readonly start: number
+  readonly end: number
+  readonly scroll: number
+  readonly maxScroll: () => number
+}
+
+/**
+ * The **Auto-scroll** of one group. `update(pointer, axis, velocity, item?)` takes the
+ * pointer in viewport px, the axis to scroll and the pointer's velocity on it; given
+ * the dragged item's element, `pointer` may instead be its drag point, which carries
+ * the scroll since the hold began (ADR-0019 *Amendment (Reorder)*), and the scroller
+ * takes that back out. `reset()` ends the gesture: the next update finds the scroller
+ * afresh and needs velocity toward an edge again.
+ */
+export interface AutoScroller {
+  readonly update: (pointer: Point.Point, axis: Axis, velocity: number, item?: Element) => void
+  readonly reset: () => void
+}
+
+const ZERO: Point.Point = { x: 0, y: 0 }
+
+/**
+ * The nearest ancestor of `group` that scrolls on `axis` (`overflow` `auto | scroll`),
+ * or the document once the walk reaches `body` (Motion's `findScrollableAncestor`).
+ */
+const findScroller = (group: Element, axis: Axis): Option.Option<Scroller> => {
+  const doc = group.ownerDocument
+  const from = (cur: HTMLElement | null): Option.Option<Scroller> =>
+    Option.flatMap(Option.fromNullOr(cur), (el) =>
+      Bool.match(el === doc.body || el === doc.documentElement, {
+        onTrue: () => Option.map(Option.fromNullOr(doc.defaultView), (win): Scroller => ({ kind: "document", win })),
+        onFalse: () => {
+          const style = getComputedStyle(el)
+          return Bool.match(SCROLLS.has({ x: style.overflowX, y: style.overflowY }[axis]), {
+            onTrue: () => Option.some<Scroller>({ kind: "element", el }),
+            onFalse: () => from(el.parentElement),
+          })
+        },
+      })
+    )
+  return from(group.parentElement)
+}
+
+/** `scroller`'s extent on `axis`: an element's visible edges are clamped to the viewport, as Motion's `getScrollAmount`. */
+const viewOf = (scroller: Scroller, axis: Axis): View =>
+  Match.value(scroller).pipe(
+    Match.when({ kind: "document" }, ({ win }): View => {
+      const root = win.document.documentElement
+      return {
+        start: 0,
+        end: { x: win.innerWidth, y: win.innerHeight }[axis],
+        scroll: { x: win.scrollX, y: win.scrollY }[axis],
+        maxScroll: { x: () => root.scrollWidth - win.innerWidth, y: () => root.scrollHeight - win.innerHeight }[axis],
+      }
+    }),
+    Match.when({ kind: "element" }, ({ el }): View => {
+      const rect = el.getBoundingClientRect()
+      const win = Option.fromNullOr(el.ownerDocument.defaultView)
+      const viewport = {
+        x: Option.match(win, { onNone: () => rect.right, onSome: (w) => w.innerWidth }),
+        y: Option.match(win, { onNone: () => rect.bottom, onSome: (w) => w.innerHeight }),
+      }
+      return {
+        start: Math.max(0, { x: rect.left, y: rect.top }[axis]),
+        end: Math.min(viewport[axis], { x: rect.right, y: rect.bottom }[axis]),
+        scroll: { x: el.scrollLeft, y: el.scrollTop }[axis],
+        maxScroll: { x: () => el.scrollWidth - el.clientWidth, y: () => el.scrollHeight - el.clientHeight }[axis],
+      }
+    }),
+    Match.exhaustive,
+  )
+
+/** Scroll `scroller` by `amount` on `axis`. */
+const scrollBy = (scroller: Scroller, axis: Axis, amount: number): void =>
+  Match.value(scroller).pipe(
+    Match.when({ kind: "document" }, ({ win }) => win.scrollBy({ x: { left: amount }, y: { top: amount } }[axis])),
+    Match.when({ kind: "element" }, ({ el }) =>
+      Match.value(axis).pipe(
+        Match.when("x", () => {
+          el.scrollLeft += amount
+        }),
+        Match.orElse(() => {
+          el.scrollTop += amount
+        }),
+      )
+    ),
+    Match.exhaustive,
+  )
+
+const edgeOf = (state: AutoScroll.State): AutoScroll.State["edge"] => state.edge
+
+/**
+ * Build the **Auto-scroll** for `group` (the Reorder group's element). The scroller on
+ * each axis is found once per gesture, at its first update. Each update reads the
+ * scroller's visible edges (clamped to the viewport, as Motion's `getScrollAmount`), runs
+ * core's `AutoScroll.step`, and scrolls by its amount. `debug` receives `auto-scroll
+ * start` and `auto-scroll stop` { axis, edge } when an edge starts and ends scrolling.
+ */
+export const makeAutoScroller = (
+  group: Element,
+  debug?: (event: string, annotations: Record<string, unknown>) => void,
+): AutoScroller => {
+  const log = UndefinedOr.match(debug, { onUndefined: () => constVoid, onDefined: (d) => d })
+  // Each axis's scroller, found at the gesture's first update (`None` when there is none).
+  const scrollers = new Map<Axis, Option.Option<Scroller>>()
+  const states = new Map<Axis, AutoScroll.State>()
+
+  const setState = (axis: Axis, next: Option.Option<AutoScroll.State>): void => {
+    const prev = Option.fromUndefinedOr(states.get(axis))
+    const edgeChanged = Bool.not(Equal.equals(Option.map(prev, edgeOf), Option.map(next, edgeOf)))
+    if (edgeChanged && Option.isSome(prev)) log("auto-scroll stop", { axis, edge: prev.value.edge })
+    Option.match(next, {
+      onNone: () => states.delete(axis),
+      onSome: (state) => states.set(axis, state),
+    })
+    if (edgeChanged && Option.isSome(next)) log("auto-scroll start", { axis, edge: next.value.edge })
+  }
+
+  return {
+    update: (pointer, axis, velocity, item) => {
+      const scroller = Option.getOrElse(Option.fromUndefinedOr(scrollers.get(axis)), () => {
+        const found = findScroller(group, axis)
+        scrollers.set(axis, found)
+        return found
+      })
+      if (Option.isNone(scroller)) return
+      const shift = UndefinedOr.match(item, { onUndefined: () => ZERO, onDefined: heldScrollShift })
+      const view = viewOf(scroller.value, axis)
+      const step = AutoScroll.step(Option.fromUndefinedOr(states.get(axis)), {
+        pointer: pointer[axis] - shift[axis],
+        start: view.start,
+        end: view.end,
+        velocity,
+        scroll: view.scroll,
+        maxScroll: view.maxScroll,
+      })
+      setState(axis, step.state)
+      if (step.amount === 0) return
+      scrollBy(scroller.value, axis, step.amount)
+    },
+    reset: () => {
+      Arr.forEach(Arr.fromIterable(states.keys()), (axis) => setState(axis, Option.none()))
+      scrollers.clear()
+    },
+  }
+}

package/src/internal/clock.ts

@@ -0,0 +1,45 @@
+/**
+ * `ClockDomLive` — the browser realization of `Clock` and of the Environment's
+ * `RefreshFrameSource` (ADR-0031): `requestAnimationFrame`, whose callbacks are the browser's
+ * Refresh frames, as the member, and core's shared `Clock.layer` built from it. The flush gate
+ * requests its flushes from the same member, so the Clock and the gate share the browser's
+ * frames. Everything else — the ref-counted Refresh frame loop, the `dt` computation and the
+ * `wardic.clock` span — lives in core, so every Environment's Clock behaves the same (ADR-0004).
+ */
+import * as Clock from "@wardic/core/Clock"
+import * as RefreshFrameSource from "@wardic/core/RefreshFrameSource"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Predicate from "effect/Predicate"
+import { requireGlobal } from "./require-global.ts"
+
+/**
+ * The browser's Refresh frames: `requestAnimationFrame` itself, so the Clock and the gate make
+ * the browser's own calls, in the order they make them (ADR-0031, decision 7). `cancelFrame`
+ * wraps `cancelAnimationFrame` for the member's `unknown` handle; it runs only on a cancel. Both
+ * are read when the Layer builds, after the client-only check.
+ */
+const frames: Layer.Layer<RefreshFrameSource.RefreshFrameSource> = Layer.effect(RefreshFrameSource.RefreshFrameSource)(
+  requireGlobal("DomClock.layer", "requestAnimationFrame").pipe(
+    Effect.map((): RefreshFrameSource.Shape => {
+      const cancel = cancelAnimationFrame
+      return {
+        requestFrame: requestAnimationFrame,
+        cancelFrame: (handle: unknown) => {
+          if (Predicate.isNumber(handle)) cancel(handle)
+        },
+      }
+    }),
+  ),
+)
+
+/**
+ * Core's `Clock` and the Environment's `RefreshFrameSource`, from one `requestAnimationFrame`, needing
+ * nothing: the frame loop runs in the Layer's own scope. It reads `requestAnimationFrame` when the Layer
+ * is built, not when `@wardic/dom` is imported, so a test that stubs it first drives this Clock. Building
+ * it on a server fails, with an error that says it's client-only.
+ */
+// ADR-0021, decision 7: the client-only error.
+export const ClockDomLive: Layer.Layer<Clock.Clock | RefreshFrameSource.RefreshFrameSource> = Clock.layer.pipe(
+  Layer.provideMerge(frames),
+)

package/src/internal/colors.ts

@@ -0,0 +1,258 @@
+/**
+ * The DOM Environment's colours (ADR-0036; ADR-0026 for the Interpolator's shape): CSS Color syntax,
+ * parsed through culori, and blended in sRGB by Wardic's own lerp and format, which write culori's
+ * strings (ADR-0026 *Amendment (#156)*). Core names no colour syntax; `@wardic/dom` registers its
+ * colour Interpolator in its registry (`interpolators.ts`) and names a colour inside a complex value
+ * as a kind of token (`COLOR_TOKEN`, #61).
+ *
+ * Read through `culori/fn`, which registers no colour space by itself (#511, ADR-0067 decision 5):
+ * sRGB's syntaxes, a hex, `rgb()`, `hsl()` and the colour names, are registered here, and every other
+ * CSS colour space (`oklch()`, `lab()`, `color(display-p3 …)`, `hwb()` …) by {@link registerSpaces},
+ * which the bindings' `colors` Feature calls. culori keeps its spaces in one registry for the page, so
+ * a space registered once is read everywhere from then on.
+ *
+ * @module
+ */
+/// <reference path="./culori.d.ts" />
+import {
+  formatRgb,
+  getMode,
+  interpolate as culoriInterpolate,
+  modeA98,
+  modeHsl,
+  modeHwb,
+  modeLab,
+  modeLch,
+  modeLrgb,
+  modeOklab,
+  modeOklch,
+  modeP3,
+  modeProphoto,
+  modeRec2020,
+  modeRgb,
+  modeXyz50,
+  modeXyz65,
+  parse as culoriParse,
+  useMode,
+} from "culori/fn"
+import type * as Interpolator from "@wardic/core/Interpolator"
+import * as Scalar from "@wardic/core/Scalar"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import { identity } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Str from "effect/String"
+import * as UndefinedOr from "effect/UndefinedOr"
+
+/** A colour as culori holds it: its colour space (`mode`) and its channels. */
+// The DOM's own type, so the declarations it emits don't lean on `culori.d.ts`.
+export type Color = { readonly mode: string; readonly [channel: string]: number | string | undefined }
+
+/** A culori colour: an object tagged with its colour space. */
+const isColor = (value: unknown): value is Color => Predicate.hasProperty(value, "mode")
+
+/**
+ * culori's `parse`, with a throw read as no colour. It throws on a CSS function holding a length,
+ * `blur(4px)`, `inset(10px)`, `drop-shadow(0px 0px 4px red)`, and the throw escaped the colour's
+ * decode at `resolve`, so the leg failed (#154).
+ */
+const culoriParseOption = Option.liftThrowable(culoriParse)
+
+/** Parse a colour string, trimmed, or `None` when culori rejects it (`"auto"`, `"#zzz"`) or throws on it (`"blur(4px)"`). */
+const parseColorString = (input: string): Option.Option<Color> =>
+  Option.filter(Option.flatMap(culoriParseOption(Str.trim(input)), Option.fromUndefinedOr), isColor)
+
+/** A colour string read: a culori colour, or `None` for any other value. A string is a colour when culori reads it, trimmed. */
+// ADR-0026; CONTEXT.md's "color string". `Color.parse`, and the colour Interpolator's `parse` (plain
+// functions since #511, where they were a Schema codec, `ColorString`).
+export const parseColor = (value: unknown): Option.Option<Color> => {
+  if (!Predicate.isString(value)) return Option.none()
+  return parseColorString(value)
+}
+
+/**
+ * A colour written as `rgb(…)` or `rgba(…)`, as culori's `formatRgb` writes it, so `"#fff"` reads and
+ * writes back as `"rgb(255, 255, 255)"`: what a blend's every frame writes.
+ */
+// `Color.format`, and the colour Interpolator's `format`.
+export const formatColor = (color: Color): string => formatRgb(color)
+
+// --- sRGB, Wardic's own (#156, ADR-0026 *Amendment (#156)*) ------------------------------------
+//
+// culori's `formatRgb(interpolate([from, to], "rgb")(t))`, string for string, without a colour
+// object per frame. Its path, at culori 4.0.2: `t` clamped to [0, 1]; at `t <= 0` the start as
+// converted; a channel one end lacks (CSS `none`) takes the other end's; an alpha one end lacks is
+// 1 when the other has one (`fixupAlpha`); each channel lerped `a + t * (b - a)` (`Scalar.lerp`'s
+// `a + (b - a) * t`, the same bits: multiplication commutes); then each channel byte is
+// `round(clamp(v || 0) * 255)`, and `rgb()` is written when alpha is absent or exactly 1, else
+// `rgba()` with alpha clamped and rounded to two places, so 0.999 writes `rgba(…, 1)`. A seeded
+// differential test against culori pins it (`colors.node.test.ts`).
+
+// sRGB's syntaxes, read by every app (#511): `rgb`'s parsers take a hex, `rgb()` and `rgba()`, the
+// colour names and `transparent`; `hsl`'s take `hsl()` and `hsla()`. Registered once, when this module
+// loads, as culori's own bundle registers its spaces.
+const toRgb = useMode(modeRgb)
+useMode(modeHsl)
+
+/**
+ * Registers every CSS colour space beyond sRGB's syntaxes: `lab()`, `lch()`, `oklab()`, `oklch()`,
+ * `hwb()`, and `color()`'s `display-p3`, `rec2020`, `a98-rgb`, `prophoto-rgb`, `srgb-linear`, `xyz`,
+ * `xyz-d50` and `xyz-d65`. From then on such a string is a colour everywhere on the page; before, it
+ * isn't one, and a `lab()` value's numbers blend as written. Calling it again does nothing new.
+ */
+// #511, ADR-0067 decision 5: the spaces culori's `culori/css` registers but for its non-CSS `hsv`, `lab65`
+// and `lch65`. The `colors` Feature's.
+export const registerSpaces = (): void => {
+  Arr.forEach(CSS_SPACES, (mode) => {
+    useMode(mode)
+  })
+}
+
+/**
+ * Whether the spaces `registerSpaces` registers are registered on the page: by it, or by culori's own
+ * bundle, which registers every space as it loads.
+ */
+// Asked of culori's registry, the page's.
+export const spacesRegistered = (): boolean => Predicate.isNotUndefined(getMode("oklch"))
+
+const CSS_SPACES = [modeA98, modeHwb, modeLab, modeLch, modeLrgb, modeOklab, modeOklch, modeP3, modeProphoto, modeRec2020, modeXyz50, modeXyz65]
+
+/** A colour's four channels, resolved once: what the frame lerps. */
+interface Channels {
+  readonly r: number
+  readonly g: number
+  readonly b: number
+  readonly alpha: number
+}
+
+/**
+ * One channel of a pair, as culori's piecewise interpolator reads it: both ends, or the end that
+ * has it, twice. One neither end has is 0 on both: culori leaves it out, and its format writes 0.
+ */
+const channelPair = (a: number | undefined, b: number | undefined): readonly [number, number] =>
+  UndefinedOr.match(a, {
+    onUndefined: () => UndefinedOr.match(b, { onUndefined: () => [0, 0] as const, onDefined: (y) => [y, y] as const }),
+    onDefined: (x) => UndefinedOr.match(b, { onUndefined: () => [x, x] as const, onDefined: (y) => [x, y] as const }),
+  })
+
+/** An alpha one end lacks is 1, culori's `fixupAlpha`; with neither, 1 on both writes `rgb()`, as culori does. */
+const alphaOf = (alpha: number | undefined): number => UndefinedOr.match(alpha, { onUndefined: () => 1, onDefined: identity })
+
+/** A channel's value at 0–1, as culori's format reads it: NaN as 0, then clamped. Per frame: an early return. */
+const unitOf = (value: number): number => {
+  if (Number.isNaN(value)) return 0
+  return Math.max(0, Math.min(1, value))
+}
+
+/** A channel as a byte, as culori's `formatRgb` writes it. */
+const byteOf = (value: number): number => Math.round(unitOf(value) * 255)
+
+/** An alpha as culori's `formatRgb` writes it: clamped, two decimal places. */
+const alphaText = (alpha: number): number => Math.round(unitOf(alpha) * 100) / 100
+
+/** Four channels as culori's `formatRgb` writes them. Per frame: an early return. */
+const formatChannels = (r: number, g: number, b: number, alpha: number): string => {
+  if (alpha === 1) return `rgb(${byteOf(r)}, ${byteOf(g)}, ${byteOf(b)})`
+  return `rgba(${byteOf(r)}, ${byteOf(g)}, ${byteOf(b)}, ${alphaText(alpha)})`
+}
+
+/**
+ * Two colours' blend in sRGB, on the per-frame path (ADR-0025): `t` clamped as culori clamps it,
+ * the start as written at `t <= 0`, and the four lerps formatted. Nothing allocated but the string.
+ */
+const blendChannels =
+  (atStart: string, from: Channels, to: Channels) =>
+  (t: number): string => {
+    const at = Math.min(Math.max(0, t), 1)
+    if (at <= 0) return atStart
+    return formatChannels(
+      Scalar.lerp(from.r, to.r, at),
+      Scalar.lerp(from.g, to.g, at),
+      Scalar.lerp(from.b, to.b, at),
+      Scalar.lerp(from.alpha, to.alpha, at),
+    )
+  }
+
+/**
+ * Two ends with the same channels: every `t` past 0 writes one string, since `a + t * (a - a)` is
+ * `a` (#156). Per frame: an early return.
+ */
+const holdChannels =
+  (atStart: string, same: string) =>
+  (t: number): string => {
+    if (t <= 0) return atStart
+    return same
+  }
+
+/** Two channels that are the same on both ends. */
+const isSame = ([a, b]: readonly [number, number]): boolean => a === b
+
+/**
+ * Two colours' sRGB blend, resolved once when a stream is built: each end converted to sRGB by
+ * culori, its channels paired as culori pairs them, and the start's own string for `t <= 0`, by
+ * culori's `formatRgb` itself. Two ends with the same channels hold one string.
+ */
+const srgb = (from: Color, to: Color): ((t: number) => string) => {
+  const a = toRgb(from)
+  const b = toRgb(to)
+  const pairs = [
+    channelPair(a.r as number | undefined, b.r as number | undefined),
+    channelPair(a.g as number | undefined, b.g as number | undefined),
+    channelPair(a.b as number | undefined, b.b as number | undefined),
+    [alphaOf(a.alpha as number | undefined), alphaOf(b.alpha as number | undefined)] as const,
+  ] as const
+  const [[fr, tr], [fg, tg], [fb, tb], [fa, ta]] = pairs
+  const atStart = formatRgb(a)
+  return Bool.match(Arr.every(pairs, isSame), {
+    onTrue: () => holdChannels(atStart, formatChannels(fr, fg, fb, fa)),
+    onFalse: () => blendChannels(atStart, { r: fr, g: fg, b: fb, alpha: fa }, { r: tr, g: tg, b: tb, alpha: ta }),
+  })
+}
+
+/** Two colours' blend through culori in `mode`: `interpolate` once, then a colour object and `formatRgb` per frame. */
+const throughCulori = (mode: string, from: Color, to: Color): ((t: number) => string) => {
+  const at = culoriInterpolate([from, to], mode)
+  return (t: number) => formatRgb(at(t))
+}
+
+/**
+ * Blends colours in the colour space `mode`: `"rgb"` by default, sRGB, as the browser's own animations
+ * blend. `"oklch"` or `"lab"` blend perceptually, once `registerSpaces` has registered them. A string is
+ * a colour when culori reads it, trimmed, so a keyword like `"auto"` isn't, and named colours and the
+ * modern forms culori knows are. Past the end of a blend a colour holds at its target.
+ *
+ * @example
+ * Color.registerSpaces()
+ * yield* registry.register(Color.interpolator("oklch")) // colours now blend in OKLCH
+ */
+// ADR-0026. A factory, so an app can register the space it prefers over the one `parseColor` and
+// `formatColor` use; the DOM's registry uses `"rgb"` (`cssColor`). `blend` resolves the pair once, when a
+// stream is built, and the frame writes the string `format` (`formatRgb`) would:
+// - `"rgb"` blends with Wardic's own lerp and format (#156, ADR-0026 *Amendment (#156)*), the strings
+//   culori writes, with no colour object per frame; two ends of the same colour write one string.
+// - Any other mode goes through culori's interpolator, which returns a new colour object on each call.
+// Either clamps `t` to [0, 1], as culori does (ADR-0024, decision 5).
+export const color = (mode = "rgb"): Interpolator.Entry<Color, string> => ({
+  name: `color(${mode})`,
+  parse: parseColor,
+  format: formatColor,
+  blend: (from, to) =>
+    Option.some(
+      Bool.match(mode === "rgb", {
+        onTrue: () => srgb(from, to),
+        onFalse: () => throughCulori(mode, from, to),
+      }),
+    ),
+})
+
+/**
+ * A colour inside a longer value: a hex, or an `rgb()`, `rgba()`, `hsl()` or `hsla()`, as Motion's colour
+ * token is. A named colour, `red`, isn't one: it stays part of the text around the tokens.
+ */
+// Motion's motion-dom value/types/utils/color-regex.ts at 16c6122; #61.
+export const COLOR_TOKEN = /#[\da-f]{3,8}|(?:rgb|hsl)a?\((?:-?[\d.]+%?[,\s]+){2}-?[\d.]+%?\s*(?:[,/]\s*)?(?:\b\d+(?:\.\d+)?|\.\d+)?%?\)/
+
+/** The DOM's colours: CSS's colour syntax, blended in sRGB, as the browser's own animations blend. Its registry's colour kind. */
+// ADR-0024: as WAAPI blends.
+export const cssColor: Interpolator.Entry<Color, string> = color("rgb")

package/src/internal/complex.ts

@@ -0,0 +1,29 @@
+/**
+ * The DOM Environment's complex values (ADR-0035 *Amendment (#158)*, ADR-0036): core's complex tier,
+ * given CSS's `var()` as a span of text (#158) and a colour as a kind of token (#61, #160). Core
+ * names neither.
+ *
+ * @module
+ */
+import * as Interpolator from "@wardic/core/Interpolator"
+import { COLOR_TOKEN, cssColor } from "./colors.ts"
+
+/**
+ * A reference to a custom property, `var(--name)`, with a fallback one bracket level deep (Motion's
+ * var token, motion-dom value/types/complex/index.ts `complexRegex` at 16c6122). Inside a complex
+ * value it's text: the digits in its name (`--gray-500`) are never numbers (#158).
+ */
+export const VARIABLE_REFERENCE = /var\s*\(\s*--(?:[\w-]+\s*|[\w-]+\s*,(?:\s*[^)(\s]|\s*\((?:[^)(]|\([^)(]*\))*\))+\s*)\)/
+
+/**
+ * Core's complex Interpolator with the DOM's syntax:
+ * - a `var()` is text (#158): a lone `var()` isn't a complex value, and two blend only with the same
+ *   count of `var()`s, the target's written as it stands;
+ * - a colour is a token (#61, #160) that blends through `cssColor`, in sRGB, so a shadow's colour
+ *   fades: two blend only with the same count of colours, the n-th with the n-th, and a lone colour
+ *   is `cssColor`'s, not a complex value.
+ */
+export const cssComplex: Interpolator.Entry<Interpolator.Complex, string> = Interpolator.complexWith({
+  text: [VARIABLE_REFERENCE],
+  tokens: [{ pattern: COLOR_TOKEN, entry: cssColor }],
+})

package/src/internal/content-watch.ts

@@ -0,0 +1,84 @@
+/**
+ * Watching a container's content for size changes: its direct children on a `ResizeObserver`, each
+ * observed now and as it's added, and let go as it's removed. A deep change counts once it resizes
+ * the direct child it sits in.
+ *
+ * - `Probe.scroll` watches a container's (the page's: the body's), so its range follows its content
+ *   (#239, ADR-0043 *Amendment (#239)*).
+ * - The Projection system watches the page's, so a node that content elsewhere moved is measured again
+ *   (#261, ADR-0018 *Amendment (#261)*).
+ *
+ * The observer is shared by count: a box watched for two reasons (a scroll target that is also a
+ * child, a layout node that is also a page box) stays watched until both let go.
+ */
+import * as Arr from "effect/Array"
+import { constVoid } from "effect/Function"
+import * as Option from "effect/Option"
+
+/** Observing and letting go of boxes on one observer, each counted by the reasons it's watched for. */
+export interface Watched {
+  readonly observe: (box: Element) => void
+  readonly unobserve: (box: Element) => void
+}
+
+/** {@link Watched} over `observer`, every box observed with `options`. */
+export const counted = (observer: ResizeObserver, options?: ResizeObserverOptions): Watched => {
+  const counts = new Map<Element, number>()
+  const countOf = (box: Element): number => Option.getOrElse(Option.fromUndefinedOr(counts.get(box)), () => 0)
+  return {
+    observe: (box) => {
+      const count = countOf(box)
+      counts.set(box, count + 1)
+      if (count === 0) observer.observe(box, options)
+    },
+    unobserve: (box) => {
+      const count = countOf(box)
+      if (count === 0) return
+      if (count > 1) {
+        counts.set(box, count - 1)
+        return
+      }
+      counts.delete(box)
+      observer.unobserve(box)
+    },
+  }
+}
+
+/**
+ * Watch `parent`'s direct children on `watched`, kept current by a `MutationObserver` on its child list.
+ * `onChildren` runs after each change to the list, its children watched by then. Returns the stop; the
+ * observer's own disconnect lets go of the boxes.
+ */
+export const watchChildren = (parent: Element, watched: Watched, onChildren: () => void): (() => void) => {
+  Arr.forEach(Array.from(parent.children), watched.observe)
+  const children = new MutationObserver((records) => {
+    Arr.forEach(records, (record) => {
+      Arr.forEach(Array.from(record.addedNodes), (node) => {
+        if (node instanceof Element) watched.observe(node)
+      })
+      Arr.forEach(Array.from(record.removedNodes), (node) => {
+        if (node instanceof Element) watched.unobserve(node)
+      })
+    })
+    onChildren()
+  })
+  children.observe(parent, { childList: true })
+  return () => children.disconnect()
+}
+
+/**
+ * Watch the page's content on `watched`: the body and its direct children (a body sized to the window
+ * doesn't grow with what overflows it), as {@link watchChildren} watches a container's. None with no
+ * body (a server, a document not parsed that far). Returns the stop.
+ */
+export const watchPage = (watched: Watched, onChildren: () => void): (() => void) =>
+  Option.match(
+    Option.flatMap(Option.fromUndefinedOr((globalThis as { readonly document?: Document }).document), (page) => Option.fromNullOr(page.body)),
+    {
+      onNone: () => constVoid,
+      onSome: (body) => {
+        watched.observe(body)
+        return watchChildren(body, watched, onChildren)
+      },
+    },
+  )

package/src/internal/culori.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Minimal ambient types for the subset of `culori` the color interpolator uses: `culori/fn` (#511),
+ * which registers no colour space by itself, and the `culori` bundle the tests compare against.
+ * `culori` v4 ships no TypeScript types and `@types/culori` lags its API, so we
+ * declare exactly what we touch here. Widen this if we start using more of culori.
+ */
+declare module "culori" {
+  export type Color = Record<string, number | string | undefined>
+
+  export function interpolate(
+    colors: ReadonlyArray<string | Color>,
+    mode?: string,
+    overrides?: unknown,
+  ): (t: number) => Color
+
+  export function formatRgb(color: Color | string): string
+  export function formatHex(color: Color | string): string
+  export function parse(color: string): Color | undefined
+  export function converter(mode: string): (color: Color) => Color
+}
+
+declare module "culori/fn" {
+  export type Color = Record<string, number | string | undefined>
+
+  /** A colour space's definition, as `useMode` takes it. */
+  export interface Mode {
+    readonly mode: string
+  }
+
+  export function interpolate(
+    colors: ReadonlyArray<string | Color>,
+    mode?: string,
+    overrides?: unknown,
+  ): (t: number) => Color
+
+  export function formatRgb(color: Color | string): string
+  export function parse(color: string): Color | undefined
+  export function converter(mode: string): (color: Color) => Color
+  /** A registered colour space's definition, or `undefined` for one not registered. */
+  export function getMode(mode: string): Mode | undefined
+  /** Register a colour space (its parsers, its conversions): a converter to it. */
+  export function useMode(mode: Mode): (color: Color) => Color
+
+  export const modeA98: Mode
+  export const modeHsl: Mode
+  export const modeHwb: Mode
+  export const modeLab: Mode
+  export const modeLch: Mode
+  export const modeLrgb: Mode
+  export const modeOklab: Mode
+  export const modeOklch: Mode
+  export const modeP3: Mode
+  export const modeProphoto: Mode
+  export const modeRec2020: Mode
+  export const modeRgb: Mode
+  export const modeXyz50: Mode
+  export const modeXyz65: Mode
+}