@labpics/colors 0.1.0 → 0.2.0

package/adapt-theme.js

@@ -1,431 +1,431 @@
-// Adaptive theme controller — the lazy debounced-re-solve runtime. Zero dependencies.
-//
-// `watchTheme` re-resolves the whole set whenever the background changes. For a
-// CONTINUOUSLY changing background (animation/scroll/blur) that is both expensive
-// (a full solve every frame) and jittery (colours twitch frame to frame).
-//
-// `adaptTheme` is the elegant alternative, and the way real systems behave: it
-// does NOT re-solve per frame. Each frame it cheaply RE-CHECKS whether the
-// current colours still pass their contrast against the (new) background — one
-// perceptual-model forward for the background plus one per role, no solve. While they pass
-// it does nothing (no churn, no jitter). Only when a role's perceptual contrast
-// stays below target for a sustained moment does it re-solve and **ease** to the
-// fresh colours over a short transition. The result: fewer computations, no
-// flicker, and a smooth, calm adaptation.
-//
-// Control law (principled defaults; all tunable):
-//   * Margin threshold — re-solve only when a role's achieved |Lc| falls below
-//     `(1 - dropFraction)` of its target |Lc| (a `dropFraction` margin under the
-//     target), not merely when it touches the line. This is a SINGLE-threshold
-//     detector: the same level gates entering and leaving the breach state — NOT a
-//     Schmitt trigger, which would need two distinct levels. The margin keeps a
-//     background sitting right at the target from counting as a breach, but it
-//     does NOT by itself stop chatter for values straddling the threshold.
-//   * Debounce — the breach must persist `sustainMs` before acting, so a dark
-//     object scrolling past for a couple of frames never triggers. Together with
-//     min-dwell this is what actually prevents oscillation near the threshold.
-//   * Min dwell — at least `dwellMs` between re-solves, capping the effective
-//     transition rate well under the flash threshold.
-//   * Ease — a non-overshooting ease-out crossfade of `easeMs`; under
-//     `prefers-reduced-motion` a gentle short fade (NOT a jarring snap — an
-//     instant state change is more stressful than a soft one, and a colour
-//     crossfade is not "motion").
-//   * Theme switches are a deliberate INTENT, not a drift: applied instantly
-//     (a single quick crossfade), never run through the debounce/dwell machinery.
-//
-// Floor-clamp modes:
-//   * Default (free ease): the crossfade does not floor-clamp each frame.
-//     Reading comprehension is far slower than a ~300ms transition and surfaces
-//     usually sit on a substrate, so a brief dip of the aesthetic *surplus*
-//     during the ease is imperceptible while the freshly-solved destination is
-//     always legal.
-//   * Strict (`strict: true`): the WCAG legal floor is HELD every frame. For
-//     text directly on animated content or under `prefers-contrast`, an
-//     intermediate colour is only shown while it still clears the role's
-//     `legalFloor` against the live background; a role whose eased intermediate
-//     would dip below its floor is advanced (monotonically) to the least blend
-//     that stays legal — never below the line, never a backwards flicker. Roles
-//     with no legal floor (decorative) ease freely either way.
-
-import { applyTheme } from "./apply-theme.js";
-import { effectiveBackground, parseCssColor, oklabLerp } from "./effective-bg.js";
-
-/** Cubic ease-out: fast start, gentle settle, no overshoot. A non-finite `t`
- * (e.g. a NaN clock making `(now - easeStart) / easeMs` NaN) is treated as a
- * completed ease (1), so the crossfade can never emit `#NANNANNAN` CSS. */
-function easeOut(t) {
-  const clamped = Number.isFinite(t) ? Math.min(1, Math.max(0, t)) : 1;
-  const u = 1 - clamped;
-  return 1 - u * u * u;
-}
-
-/** WCAG 2.1 relative luminance of `#RRGGBB` — a faithful transcription of the
- * normative definition (0.03928 split, 2.4 exponent), so the strict floor-clamp
- * agrees byte-for-byte with the core's `legalFloor` semantics. */
-function relativeLuminanceHex(hex) {
-  const rgb = parseCssColor(hex) ?? [0, 0, 0, 1];
-  const lin = (c) => {
-    const s = c / 255;
-    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
-  };
-  return 0.2126 * lin(rgb[0]) + 0.7152 * lin(rgb[1]) + 0.0722 * lin(rgb[2]);
-}
-
-/** WCAG contrast ratio from two relative luminances: `(L+0.05)/(L+0.05)`. */
-function wcagRatio(lumA, lumB) {
-  const hi = Math.max(lumA, lumB);
-  const lo = Math.min(lumA, lumB);
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-/** Interpolate two `#RRGGBB` hexes at `t ∈ [0,1]` in Oklab, so the crossfade is
- * perceptually even (no lingering-bright sRGB midpoint, no muddy chroma path). */
-function lerpHex(from, to, t) {
-  return oklabLerp(from, to, t);
-}
-
-/**
- * @typedef {object} AdaptController
- * @property {(now?: number) => void} tick  Drive one step (call from rAF, or let
- *   `start()` do it). Cheap: a re-check; a re-solve only on a sustained breach.
- * @property {(theme: string) => void} setTheme  Switch theme INSTANTLY (intent,
- *   not drift) — re-resolve and apply, bypassing the debounce/dwell machinery.
- * @property {() => void} start  Begin an internal requestAnimationFrame loop.
- * @property {() => void} stop   Stop the loop and disconnect.
- * @property {() => Record<string,string>} current  The currently-applied vars.
- */
-
-/**
- * Keep an element's `--lab-*` variables adapting to its (changing) background
- * lazily and smoothly. Applies the resolved set immediately, then holds it while
- * it still passes, re-solving + easing only when contrast stably degrades.
- *
- * @param {*} element
- * @param {object} options
- * @param {{ resolveTheme: (bg:string,theme:string)=>any, recheckContrast:(bg:string,fgs:string[],theme:string)=>ArrayLike<number> }} options.colors
- * @param {string} options.theme
- * @param {string | string[] | (() => string | string[])} [options.background]
- *   explicit effective background. An ARRAY (or a function returning one) is a
- *   set of worst-case samples of a varying backdrop (gradient / image): the
- *   colours are held legible against the hardest sample. The caller does the
- *   pixel sampling; this consumes the samples worst-case.
- * @param {*} [options.target=element]  element to write vars onto
- * @param {string} [options.fallback="#FFFFFF"]
- * @param {number} [options.dropFraction=0.2]  surplus fraction lost before re-solve
- * @param {number} [options.sustainMs=120]  breach must persist this long
- * @param {number} [options.dwellMs=250]  minimum between re-solves
- * @param {number} [options.easeMs=280]  crossfade duration
- * @param {boolean} [options.strict=false]  hold each role's WCAG legal floor
- *   every frame of the ease (for text on animated content / `prefers-contrast`)
- * @param {boolean} [options.reducedMotion]  override; default reads matchMedia
- * @param {() => number} [options.now]  clock (default performance.now/Date.now)
- * @param {*} [options.win=globalThis]
- * @param {(el:*)=>*} [options.getStyle]  effectiveBackground seam (testing)
- * @param {(el:*)=>*} [options.parentOf]  effectiveBackground seam (testing)
- * @returns {AdaptController}
- */
-export function adaptTheme(element, options) {
-  if (
-    !options ||
-    typeof options.colors?.resolveTheme !== "function" ||
-    typeof options.colors?.recheckContrast !== "function"
-  ) {
-    throw new TypeError("adaptTheme: options.colors needs resolveTheme + recheckContrast");
-  }
-  const colors = options.colors;
-  const target = options.target ?? element;
-  const fallback = options.fallback ?? "#FFFFFF";
-  const dropFraction = options.dropFraction ?? 0.2;
-  const sustainMs = options.sustainMs ?? 120;
-  const dwellMs = options.dwellMs ?? 250;
-  const strict = options.strict ?? false;
-  const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
-  const reducedMotion =
-    options.reducedMotion ??
-    (win?.matchMedia ? win.matchMedia("(prefers-reduced-motion: reduce)").matches : false);
-  // Reduced motion → a gentle SHORT fade, never a hard snap.
-  const easeMs = reducedMotion ? Math.min(options.easeMs ?? 280, 80) : (options.easeMs ?? 280);
-  const clock = options.now ?? (() => (win?.performance?.now ? win.performance.now() : Date.now()));
-
-  let theme = options.theme;
-  /** @type {{ cssVar: string, key: string, lc: number, hex: string, legalFloor: number|null }[]} stable role order */
-  let roles = [];
-  /** @type {Map<string,{from:string,to:string}>} in-flight ease per cssVar */
-  let easing = new Map();
-  let easeStart = 0;
-  let breachSince = null;
-  let lastSolveAt = -Infinity;
-  let lastKey = null;
-
-  const readBackground = () => {
-    const b = options.background;
-    if (typeof b === "function") return b();
-    if (typeof b === "string" || Array.isArray(b)) return b;
-    return effectiveBackground(element, {
-      fallback,
-      getStyle: options.getStyle,
-      parentOf: options.parentOf,
-    });
-  };
-
-  // The background is a SET of samples. A solid surface is one sample; a varying
-  // backdrop (gradient / image / video the caller sampled) is several. Every
-  // decision is worst-case over the set: a role "passes" only if it passes
-  // against EVERY sample, and we re-solve against the HARDEST sample. With one
-  // sample this collapses to plain single-background behaviour, bit-for-bit.
-  const readSamples = () => {
-    const v = readBackground();
-    const arr = Array.isArray(v) ? v.filter((s) => typeof s === "string" && s.length > 0) : [v];
-    return arr.length > 0 ? arr : [fallback];
-  };
-
-  // Recheck the current colours against every sample. A role breaches if its
-  // achieved |Lc| drops below its single-threshold margin (`|lc| * (1 -
-  // dropFraction)`) against ANY sample. `worstIdx` is the sample with the least
-  // set-wide margin — the one to re-solve against, so the constraint we solve to
-  // is the same constraint we check hardest.
-  const recheckSamples = (fgs, samples) => {
-    let breached = false;
-    let worstIdx = 0;
-    let worstMargin = Infinity;
-    for (let s = 0; s < samples.length; s++) {
-      const flat = colors.recheckContrast(samples[s], fgs, theme);
-      let sampleMargin = Infinity;
-      for (let i = 0; i < roles.length; i++) {
-        const want = Math.abs(roles[i].lc) * (1 - dropFraction);
-        const lcNow = Math.abs(flat[2 * i]);
-        if (lcNow < want) breached = true;
-        const margin = want > 0 ? lcNow / want : Infinity;
-        if (margin < sampleMargin) sampleMargin = margin;
-      }
-      if (sampleMargin < worstMargin) {
-        worstMargin = sampleMargin;
-        worstIdx = s;
-      }
-    }
-    return { breached, worstIdx };
-  };
-
-  // Resolve a fresh set and adopt it as the current colours (no ease).
-  const solveAndAdopt = (bg, now) => {
-    const result = colors.resolveTheme(bg, theme);
-    roles = Object.entries(result.roles)
-      .filter(([, r]) => r && r.kind === "color")
-      .map(([key, r]) => ({
-        cssVar: r.cssVar,
-        key,
-        lc: r.lc,
-        hex: r.hex,
-        legalFloor: typeof r.legalFloor === "number" ? r.legalFloor : null,
-      }));
-    lastSolveAt = now;
-    breachSince = null;
-    return result;
-  };
-
-  // Solve+adopt against the hardest of `samples`. With one sample this is a
-  // single solve; with several it does a provisional solve to learn the role
-  // colours, picks the worst sample for them, and re-solves against it if that
-  // is not the one already chosen — so the adopted set is the strongest the
-  // backdrop demands. Used where there is no current set to recheck (initial
-  // apply, theme switch); the tick path already knows the worst sample from its
-  // own recheck and calls `solveAndAdopt` directly.
-  const solveAndAdoptWorst = (samples, now) => {
-    solveAndAdopt(samples[0], now);
-    if (samples.length > 1) {
-      const { worstIdx } = recheckSamples(
-        roles.map((r) => r.hex),
-        samples,
-      );
-      if (worstIdx !== 0) solveAndAdopt(samples[worstIdx], now);
-    }
-  };
-
-  const applyHexes = (hexByVar) => applyTheme(target, { vars: hexByVar });
-
-  const applyRolesDirect = () => {
-    const vars = {};
-    for (const r of roles) vars[r.cssVar] = r.hex;
-    applyHexes(vars);
-  };
-
-  // Begin an ease from the currently-applied colours toward the role colours.
-  // `held` latches the per-role displayed blend so it only ever advances toward
-  // the destination (strict mode) — see `stepEase`.
-  const beginEase = (fromByVar, now) => {
-    easing = new Map();
-    for (const r of roles) {
-      const from = fromByVar[r.cssVar] ?? r.hex;
-      if (from !== r.hex) easing.set(r.cssVar, { from, to: r.hex, held: 0 });
-    }
-    easeStart = now;
-    if (easing.size === 0) applyRolesDirect();
-  };
-
-  // Strict mode: the least blend in [e, 1] whose interpolated colour clears
-  // `floor` against EVERY background sample in `bgLums`. The destination (`to`,
-  // blend 1) is a freshly-solved legal colour, so it anchors the search; we
-  // bisect toward it from the natural ease value `e`. Returns `e` unchanged when
-  // the eased colour is already legal everywhere (the common case — no
-  // intervention). The returned blend is always floor-legal against the worst
-  // sample, except in the unavoidable case where even `to` is illegal against a
-  // sample that drifted further this frame — then it returns 1 (the most-legal
-  // colour we have) and the recheck loop re-solves.
-  const floorBlend = (seg, e, bgLums, floor) => {
-    const legalAt = (blend) => {
-      const lum = relativeLuminanceHex(lerpHex(seg.from, seg.to, blend));
-      return bgLums.every((L) => wcagRatio(lum, L) >= floor);
-    };
-    if (legalAt(e)) return e;
-    let lo = e;
-    let hi = 1;
-    for (let k = 0; k < 14; k++) {
-      const mid = (lo + hi) / 2;
-      if (legalAt(mid)) hi = mid;
-      else lo = mid;
-    }
-    return hi; // hi is always legal (or blend 1, the most-legal we have)
-  };
-
-  const stepEase = (now, samples) => {
-    const t = easeMs <= 0 ? 1 : (now - easeStart) / easeMs;
-    const e = easeOut(t);
-    const bgLums = strict ? samples.map(relativeLuminanceHex) : null;
-    const vars = {};
-    for (const r of roles) {
-      const seg = easing.get(r.cssVar);
-      if (!seg) {
-        vars[r.cssVar] = r.hex;
-        continue;
-      }
-      let blend = e;
-      if (strict && r.legalFloor != null) {
-        // Hold the floor (against the worst sample), then LATCH: the displayed
-        // blend may only advance toward the destination, never retreat.
-        // `floorBlend` is stateless and depends on the live (drifting) samples,
-        // so on a frame where they drift favourably it could return a *lower*
-        // blend than last frame — a backwards step toward the old colour, the
-        // precise jarring reversal this mode exists to avoid. `held` clamps that
-        // out: the colour progresses monotonically from→to and never below the
-        // legal line on any sample.
-        blend = Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held);
-        seg.held = blend;
-      }
-      vars[r.cssVar] = lerpHex(seg.from, seg.to, blend);
-    }
-    applyHexes(vars);
-    if (t >= 1) easing = new Map();
-  };
-
-  const currentApplied = () => {
-    const vars = {};
-    for (const r of roles) {
-      const seg = easing.get(r.cssVar);
-      vars[r.cssVar] = seg ? seg.to : r.hex; // logical target during/after ease
-    }
-    return vars;
-  };
-
-  // The colour each role is PAINTED right now — exactly what `stepEase` writes
-  // this frame: an in-flight segment sampled at `now` (with the SAME strict
-  // floor-hold + latch against the worst sample when `strict`), else the static
-  // hex. Mirrors `stepEase`'s blend math byte-for-byte so the begin-from value
-  // equals what is on screen, including the strict-mode `held` clamp — otherwise
-  // an overlapping re-solve in strict mode would start one frame BELOW the
-  // painted (floored) colour.
-  const paintedNow = (now, samples) => {
-    const t = easeMs <= 0 ? 1 : (now - easeStart) / easeMs;
-    const e = easeOut(t);
-    const bgLums = strict ? samples.map(relativeLuminanceHex) : null;
-    const vars = {};
-    for (const r of roles) {
-      const seg = easing.get(r.cssVar);
-      if (!seg) {
-        vars[r.cssVar] = r.hex;
-        continue;
-      }
-      const blend =
-        strict && r.legalFloor != null
-          ? Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held)
-          : e;
-      vars[r.cssVar] = lerpHex(seg.from, seg.to, blend);
-    }
-    return vars;
-  };
-
-  const tick = (nowArg) => {
-    const now = nowArg ?? clock();
-    const samples = readSamples();
-    // Advance any in-flight ease first (against the live samples, so strict mode
-    // holds the legal floor every frame as the backdrop keeps drifting under it).
-    if (easing.size > 0) stepEase(now, samples);
-
-    // Steady state: a static backdrop with no in-flight ease and no pending
-    // breach needs no work. A PENDING breach keeps us live even on a static
-    // backdrop, so the sustain timer can fire on one that changed once to a
-    // failing value and then held.
-    const key = samples.join("|");
-    if (key === lastKey && easing.size === 0 && breachSince === null) return;
-    lastKey = key;
-    if (roles.length === 0) return;
-
-    // Cheap worst-case re-check: do the current colours still pass against every
-    // sample? `worstIdx` is the hardest sample, the one to re-solve against.
-    const { breached, worstIdx } = recheckSamples(
-      roles.map((r) => r.hex),
-      samples,
-    );
-
-    if (!breached) {
-      breachSince = null;
-      return; // hold — the common case for a slowly-drifting backdrop
-    }
-    if (breachSince === null) breachSince = now;
-    if (now - breachSince < sustainMs || now - lastSolveAt < dwellMs) return; // debounce / dwell
-
-    // Sustained breach: re-solve against the worst sample and ease toward fresh,
-    // starting from the colour each role is PAINTED right now (the in-flight ease
-    // sampled at `now`) — never the in-flight TARGET. Starting from the target
-    // would SNAP the element to the old target for one frame before easing,
-    // reintroducing flicker when a re-solve overlaps a previous ease.
-    const fromByVar = paintedNow(now, samples);
-    solveAndAdopt(samples[worstIdx], now);
-    beginEase(fromByVar, now);
-    stepEase(now, samples);
-  };
-
-  let rafId = null;
-  const loop = () => {
-    tick();
-    if (win?.requestAnimationFrame) rafId = win.requestAnimationFrame(loop);
-  };
-
-  // Apply the initial set immediately (against the worst sample of the backdrop).
-  {
-    const samples = readSamples();
-    lastKey = samples.join("|");
-    solveAndAdoptWorst(samples, clock());
-    applyRolesDirect();
-  }
-
-  return {
-    tick,
-    setTheme(next) {
-      theme = next;
-      const samples = readSamples();
-      lastKey = samples.join("|");
-      easing = new Map();
-      solveAndAdoptWorst(samples, clock());
-      applyRolesDirect(); // instant — a theme switch is intent, not drift
-    },
-    start() {
-      if (rafId == null && win?.requestAnimationFrame) rafId = win.requestAnimationFrame(loop);
-    },
-    stop() {
-      if (rafId != null && win?.cancelAnimationFrame) win.cancelAnimationFrame(rafId);
-      rafId = null;
-      easing = new Map();
-    },
-    current: currentApplied,
-  };
-}
+// Adaptive theme controller — the lazy debounced-re-solve runtime. Zero dependencies.
+//
+// `watchTheme` re-resolves the whole set whenever the background changes. For a
+// CONTINUOUSLY changing background (animation/scroll/blur) that is both expensive
+// (a full solve every frame) and jittery (colours twitch frame to frame).
+//
+// `adaptTheme` is the elegant alternative, and the way real systems behave: it
+// does NOT re-solve per frame. Each frame it cheaply RE-CHECKS whether the
+// current colours still pass their contrast against the (new) background — one
+// perceptual-model forward for the background plus one per role, no solve. While they pass
+// it does nothing (no churn, no jitter). Only when a role's perceptual contrast
+// stays below target for a sustained moment does it re-solve and **ease** to the
+// fresh colours over a short transition. The result: fewer computations, no
+// flicker, and a smooth, calm adaptation.
+//
+// Control law (principled defaults; all tunable):
+//   * Margin threshold — re-solve only when a role's achieved |Lc| falls below
+//     `(1 - dropFraction)` of its target |Lc| (a `dropFraction` margin under the
+//     target), not merely when it touches the line. This is a SINGLE-threshold
+//     detector: the same level gates entering and leaving the breach state — NOT a
+//     Schmitt trigger, which would need two distinct levels. The margin keeps a
+//     background sitting right at the target from counting as a breach, but it
+//     does NOT by itself stop chatter for values straddling the threshold.
+//   * Debounce — the breach must persist `sustainMs` before acting, so a dark
+//     object scrolling past for a couple of frames never triggers. Together with
+//     min-dwell this is what actually prevents oscillation near the threshold.
+//   * Min dwell — at least `dwellMs` between re-solves, capping the effective
+//     transition rate well under the flash threshold.
+//   * Ease — a non-overshooting ease-out crossfade of `easeMs`; under
+//     `prefers-reduced-motion` a gentle short fade (NOT a jarring snap — an
+//     instant state change is more stressful than a soft one, and a colour
+//     crossfade is not "motion").
+//   * Theme switches are a deliberate INTENT, not a drift: applied instantly
+//     (a single quick crossfade), never run through the debounce/dwell machinery.
+//
+// Floor-clamp modes:
+//   * Default (free ease): the crossfade does not floor-clamp each frame.
+//     Reading comprehension is far slower than a ~300ms transition and surfaces
+//     usually sit on a substrate, so a brief dip of the aesthetic *surplus*
+//     during the ease is imperceptible while the freshly-solved destination is
+//     always legal.
+//   * Strict (`strict: true`): the WCAG legal floor is HELD every frame. For
+//     text directly on animated content or under `prefers-contrast`, an
+//     intermediate colour is only shown while it still clears the role's
+//     `legalFloor` against the live background; a role whose eased intermediate
+//     would dip below its floor is advanced (monotonically) to the least blend
+//     that stays legal — never below the line, never a backwards flicker. Roles
+//     with no legal floor (decorative) ease freely either way.
+
+import { applyTheme } from "./apply-theme.js";
+import { effectiveBackground, parseCssColor, oklabLerp } from "./effective-bg.js";
+
+/** Cubic ease-out: fast start, gentle settle, no overshoot. A non-finite `t`
+ * (e.g. a NaN clock making `(now - easeStart) / easeMs` NaN) is treated as a
+ * completed ease (1), so the crossfade can never emit `#NANNANNAN` CSS. */
+function easeOut(t) {
+  const clamped = Number.isFinite(t) ? Math.min(1, Math.max(0, t)) : 1;
+  const u = 1 - clamped;
+  return 1 - u * u * u;
+}
+
+/** WCAG 2.1 relative luminance of `#RRGGBB` — a faithful transcription of the
+ * normative definition (0.03928 split, 2.4 exponent), so the strict floor-clamp
+ * agrees byte-for-byte with the core's `legalFloor` semantics. */
+function relativeLuminanceHex(hex) {
+  const rgb = parseCssColor(hex) ?? [0, 0, 0, 1];
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(rgb[0]) + 0.7152 * lin(rgb[1]) + 0.0722 * lin(rgb[2]);
+}
+
+/** WCAG contrast ratio from two relative luminances: `(L+0.05)/(L+0.05)`. */
+function wcagRatio(lumA, lumB) {
+  const hi = Math.max(lumA, lumB);
+  const lo = Math.min(lumA, lumB);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Interpolate two `#RRGGBB` hexes at `t ∈ [0,1]` in Oklab, so the crossfade is
+ * perceptually even (no lingering-bright sRGB midpoint, no muddy chroma path). */
+function lerpHex(from, to, t) {
+  return oklabLerp(from, to, t);
+}
+
+/**
+ * @typedef {object} AdaptController
+ * @property {(now?: number) => void} tick  Drive one step (call from rAF, or let
+ *   `start()` do it). Cheap: a re-check; a re-solve only on a sustained breach.
+ * @property {(theme: string) => void} setTheme  Switch theme INSTANTLY (intent,
+ *   not drift) — re-resolve and apply, bypassing the debounce/dwell machinery.
+ * @property {() => void} start  Begin an internal requestAnimationFrame loop.
+ * @property {() => void} stop   Stop the loop and disconnect.
+ * @property {() => Record<string,string>} current  The currently-applied vars.
+ */
+
+/**
+ * Keep an element's `--lab-*` variables adapting to its (changing) background
+ * lazily and smoothly. Applies the resolved set immediately, then holds it while
+ * it still passes, re-solving + easing only when contrast stably degrades.
+ *
+ * @param {*} element
+ * @param {object} options
+ * @param {{ resolveTheme: (bg:string,theme:string)=>any, recheckContrast:(bg:string,fgs:string[],theme:string)=>ArrayLike<number> }} options.colors
+ * @param {string} options.theme
+ * @param {string | string[] | (() => string | string[])} [options.background]
+ *   explicit effective background. An ARRAY (or a function returning one) is a
+ *   set of worst-case samples of a varying backdrop (gradient / image): the
+ *   colours are held legible against the hardest sample. The caller does the
+ *   pixel sampling; this consumes the samples worst-case.
+ * @param {*} [options.target=element]  element to write vars onto
+ * @param {string} [options.fallback="#FFFFFF"]
+ * @param {number} [options.dropFraction=0.2]  surplus fraction lost before re-solve
+ * @param {number} [options.sustainMs=120]  breach must persist this long
+ * @param {number} [options.dwellMs=250]  minimum between re-solves
+ * @param {number} [options.easeMs=280]  crossfade duration
+ * @param {boolean} [options.strict=false]  hold each role's WCAG legal floor
+ *   every frame of the ease (for text on animated content / `prefers-contrast`)
+ * @param {boolean} [options.reducedMotion]  override; default reads matchMedia
+ * @param {() => number} [options.now]  clock (default performance.now/Date.now)
+ * @param {*} [options.win=globalThis]
+ * @param {(el:*)=>*} [options.getStyle]  effectiveBackground seam (testing)
+ * @param {(el:*)=>*} [options.parentOf]  effectiveBackground seam (testing)
+ * @returns {AdaptController}
+ */
+export function adaptTheme(element, options) {
+  if (
+    !options ||
+    typeof options.colors?.resolveTheme !== "function" ||
+    typeof options.colors?.recheckContrast !== "function"
+  ) {
+    throw new TypeError("adaptTheme: options.colors needs resolveTheme + recheckContrast");
+  }
+  const colors = options.colors;
+  const target = options.target ?? element;
+  const fallback = options.fallback ?? "#FFFFFF";
+  const dropFraction = options.dropFraction ?? 0.2;
+  const sustainMs = options.sustainMs ?? 120;
+  const dwellMs = options.dwellMs ?? 250;
+  const strict = options.strict ?? false;
+  const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
+  const reducedMotion =
+    options.reducedMotion ??
+    (win?.matchMedia ? win.matchMedia("(prefers-reduced-motion: reduce)").matches : false);
+  // Reduced motion → a gentle SHORT fade, never a hard snap.
+  const easeMs = reducedMotion ? Math.min(options.easeMs ?? 280, 80) : (options.easeMs ?? 280);
+  const clock = options.now ?? (() => (win?.performance?.now ? win.performance.now() : Date.now()));
+
+  let theme = options.theme;
+  /** @type {{ cssVar: string, key: string, lc: number, hex: string, legalFloor: number|null }[]} stable role order */
+  let roles = [];
+  /** @type {Map<string,{from:string,to:string}>} in-flight ease per cssVar */
+  let easing = new Map();
+  let easeStart = 0;
+  let breachSince = null;
+  let lastSolveAt = -Infinity;
+  let lastKey = null;
+
+  const readBackground = () => {
+    const b = options.background;
+    if (typeof b === "function") return b();
+    if (typeof b === "string" || Array.isArray(b)) return b;
+    return effectiveBackground(element, {
+      fallback,
+      getStyle: options.getStyle,
+      parentOf: options.parentOf,
+    });
+  };
+
+  // The background is a SET of samples. A solid surface is one sample; a varying
+  // backdrop (gradient / image / video the caller sampled) is several. Every
+  // decision is worst-case over the set: a role "passes" only if it passes
+  // against EVERY sample, and we re-solve against the HARDEST sample. With one
+  // sample this collapses to plain single-background behaviour, bit-for-bit.
+  const readSamples = () => {
+    const v = readBackground();
+    const arr = Array.isArray(v) ? v.filter((s) => typeof s === "string" && s.length > 0) : [v];
+    return arr.length > 0 ? arr : [fallback];
+  };
+
+  // Recheck the current colours against every sample. A role breaches if its
+  // achieved |Lc| drops below its single-threshold margin (`|lc| * (1 -
+  // dropFraction)`) against ANY sample. `worstIdx` is the sample with the least
+  // set-wide margin — the one to re-solve against, so the constraint we solve to
+  // is the same constraint we check hardest.
+  const recheckSamples = (fgs, samples) => {
+    let breached = false;
+    let worstIdx = 0;
+    let worstMargin = Infinity;
+    for (let s = 0; s < samples.length; s++) {
+      const flat = colors.recheckContrast(samples[s], fgs, theme);
+      let sampleMargin = Infinity;
+      for (let i = 0; i < roles.length; i++) {
+        const want = Math.abs(roles[i].lc) * (1 - dropFraction);
+        const lcNow = Math.abs(flat[2 * i]);
+        if (lcNow < want) breached = true;
+        const margin = want > 0 ? lcNow / want : Infinity;
+        if (margin < sampleMargin) sampleMargin = margin;
+      }
+      if (sampleMargin < worstMargin) {
+        worstMargin = sampleMargin;
+        worstIdx = s;
+      }
+    }
+    return { breached, worstIdx };
+  };
+
+  // Resolve a fresh set and adopt it as the current colours (no ease).
+  const solveAndAdopt = (bg, now) => {
+    const result = colors.resolveTheme(bg, theme);
+    roles = Object.entries(result.roles)
+      .filter(([, r]) => r && r.kind === "color")
+      .map(([key, r]) => ({
+        cssVar: r.cssVar,
+        key,
+        lc: r.lc,
+        hex: r.hex,
+        legalFloor: typeof r.legalFloor === "number" ? r.legalFloor : null,
+      }));
+    lastSolveAt = now;
+    breachSince = null;
+    return result;
+  };
+
+  // Solve+adopt against the hardest of `samples`. With one sample this is a
+  // single solve; with several it does a provisional solve to learn the role
+  // colours, picks the worst sample for them, and re-solves against it if that
+  // is not the one already chosen — so the adopted set is the strongest the
+  // backdrop demands. Used where there is no current set to recheck (initial
+  // apply, theme switch); the tick path already knows the worst sample from its
+  // own recheck and calls `solveAndAdopt` directly.
+  const solveAndAdoptWorst = (samples, now) => {
+    solveAndAdopt(samples[0], now);
+    if (samples.length > 1) {
+      const { worstIdx } = recheckSamples(
+        roles.map((r) => r.hex),
+        samples,
+      );
+      if (worstIdx !== 0) solveAndAdopt(samples[worstIdx], now);
+    }
+  };
+
+  const applyHexes = (hexByVar) => applyTheme(target, { vars: hexByVar });
+
+  const applyRolesDirect = () => {
+    const vars = {};
+    for (const r of roles) vars[r.cssVar] = r.hex;
+    applyHexes(vars);
+  };
+
+  // Begin an ease from the currently-applied colours toward the role colours.
+  // `held` latches the per-role displayed blend so it only ever advances toward
+  // the destination (strict mode) — see `stepEase`.
+  const beginEase = (fromByVar, now) => {
+    easing = new Map();
+    for (const r of roles) {
+      const from = fromByVar[r.cssVar] ?? r.hex;
+      if (from !== r.hex) easing.set(r.cssVar, { from, to: r.hex, held: 0 });
+    }
+    easeStart = now;
+    if (easing.size === 0) applyRolesDirect();
+  };
+
+  // Strict mode: the least blend in [e, 1] whose interpolated colour clears
+  // `floor` against EVERY background sample in `bgLums`. The destination (`to`,
+  // blend 1) is a freshly-solved legal colour, so it anchors the search; we
+  // bisect toward it from the natural ease value `e`. Returns `e` unchanged when
+  // the eased colour is already legal everywhere (the common case — no
+  // intervention). The returned blend is always floor-legal against the worst
+  // sample, except in the unavoidable case where even `to` is illegal against a
+  // sample that drifted further this frame — then it returns 1 (the most-legal
+  // colour we have) and the recheck loop re-solves.
+  const floorBlend = (seg, e, bgLums, floor) => {
+    const legalAt = (blend) => {
+      const lum = relativeLuminanceHex(lerpHex(seg.from, seg.to, blend));
+      return bgLums.every((L) => wcagRatio(lum, L) >= floor);
+    };
+    if (legalAt(e)) return e;
+    let lo = e;
+    let hi = 1;
+    for (let k = 0; k < 14; k++) {
+      const mid = (lo + hi) / 2;
+      if (legalAt(mid)) hi = mid;
+      else lo = mid;
+    }
+    return hi; // hi is always legal (or blend 1, the most-legal we have)
+  };
+
+  const stepEase = (now, samples) => {
+    const t = easeMs <= 0 ? 1 : (now - easeStart) / easeMs;
+    const e = easeOut(t);
+    const bgLums = strict ? samples.map(relativeLuminanceHex) : null;
+    const vars = {};
+    for (const r of roles) {
+      const seg = easing.get(r.cssVar);
+      if (!seg) {
+        vars[r.cssVar] = r.hex;
+        continue;
+      }
+      let blend = e;
+      if (strict && r.legalFloor != null) {
+        // Hold the floor (against the worst sample), then LATCH: the displayed
+        // blend may only advance toward the destination, never retreat.
+        // `floorBlend` is stateless and depends on the live (drifting) samples,
+        // so on a frame where they drift favourably it could return a *lower*
+        // blend than last frame — a backwards step toward the old colour, the
+        // precise jarring reversal this mode exists to avoid. `held` clamps that
+        // out: the colour progresses monotonically from→to and never below the
+        // legal line on any sample.
+        blend = Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held);
+        seg.held = blend;
+      }
+      vars[r.cssVar] = lerpHex(seg.from, seg.to, blend);
+    }
+    applyHexes(vars);
+    if (t >= 1) easing = new Map();
+  };
+
+  const currentApplied = () => {
+    const vars = {};
+    for (const r of roles) {
+      const seg = easing.get(r.cssVar);
+      vars[r.cssVar] = seg ? seg.to : r.hex; // logical target during/after ease
+    }
+    return vars;
+  };
+
+  // The colour each role is PAINTED right now — exactly what `stepEase` writes
+  // this frame: an in-flight segment sampled at `now` (with the SAME strict
+  // floor-hold + latch against the worst sample when `strict`), else the static
+  // hex. Mirrors `stepEase`'s blend math byte-for-byte so the begin-from value
+  // equals what is on screen, including the strict-mode `held` clamp — otherwise
+  // an overlapping re-solve in strict mode would start one frame BELOW the
+  // painted (floored) colour.
+  const paintedNow = (now, samples) => {
+    const t = easeMs <= 0 ? 1 : (now - easeStart) / easeMs;
+    const e = easeOut(t);
+    const bgLums = strict ? samples.map(relativeLuminanceHex) : null;
+    const vars = {};
+    for (const r of roles) {
+      const seg = easing.get(r.cssVar);
+      if (!seg) {
+        vars[r.cssVar] = r.hex;
+        continue;
+      }
+      const blend =
+        strict && r.legalFloor != null
+          ? Math.max(floorBlend(seg, e, bgLums, r.legalFloor), seg.held)
+          : e;
+      vars[r.cssVar] = lerpHex(seg.from, seg.to, blend);
+    }
+    return vars;
+  };
+
+  const tick = (nowArg) => {
+    const now = nowArg ?? clock();
+    const samples = readSamples();
+    // Advance any in-flight ease first (against the live samples, so strict mode
+    // holds the legal floor every frame as the backdrop keeps drifting under it).
+    if (easing.size > 0) stepEase(now, samples);
+
+    // Steady state: a static backdrop with no in-flight ease and no pending
+    // breach needs no work. A PENDING breach keeps us live even on a static
+    // backdrop, so the sustain timer can fire on one that changed once to a
+    // failing value and then held.
+    const key = samples.join("|");
+    if (key === lastKey && easing.size === 0 && breachSince === null) return;
+    lastKey = key;
+    if (roles.length === 0) return;
+
+    // Cheap worst-case re-check: do the current colours still pass against every
+    // sample? `worstIdx` is the hardest sample, the one to re-solve against.
+    const { breached, worstIdx } = recheckSamples(
+      roles.map((r) => r.hex),
+      samples,
+    );
+
+    if (!breached) {
+      breachSince = null;
+      return; // hold — the common case for a slowly-drifting backdrop
+    }
+    if (breachSince === null) breachSince = now;
+    if (now - breachSince < sustainMs || now - lastSolveAt < dwellMs) return; // debounce / dwell
+
+    // Sustained breach: re-solve against the worst sample and ease toward fresh,
+    // starting from the colour each role is PAINTED right now (the in-flight ease
+    // sampled at `now`) — never the in-flight TARGET. Starting from the target
+    // would SNAP the element to the old target for one frame before easing,
+    // reintroducing flicker when a re-solve overlaps a previous ease.
+    const fromByVar = paintedNow(now, samples);
+    solveAndAdopt(samples[worstIdx], now);
+    beginEase(fromByVar, now);
+    stepEase(now, samples);
+  };
+
+  let rafId = null;
+  const loop = () => {
+    tick();
+    if (win?.requestAnimationFrame) rafId = win.requestAnimationFrame(loop);
+  };
+
+  // Apply the initial set immediately (against the worst sample of the backdrop).
+  {
+    const samples = readSamples();
+    lastKey = samples.join("|");
+    solveAndAdoptWorst(samples, clock());
+    applyRolesDirect();
+  }
+
+  return {
+    tick,
+    setTheme(next) {
+      theme = next;
+      const samples = readSamples();
+      lastKey = samples.join("|");
+      easing = new Map();
+      solveAndAdoptWorst(samples, clock());
+      applyRolesDirect(); // instant — a theme switch is intent, not drift
+    },
+    start() {
+      if (rafId == null && win?.requestAnimationFrame) rafId = win.requestAnimationFrame(loop);
+    },
+    stop() {
+      if (rafId != null && win?.cancelAnimationFrame) win.cancelAnimationFrame(rafId);
+      rafId = null;
+      easing = new Map();
+    },
+    current: currentApplied,
+  };
+}