vireglass 0.1.0

package/src/native/lens.ts

@@ -0,0 +1,106 @@
+import type { ComponentType, ReactNode } from 'react';
+import { Platform, type StyleProp, type ViewStyle } from 'react-native';
+// Through `expo`, not directly from `expo-modules-core`: in this layout the latter is a
+// transitive dependency, and pnpm doesn't hoist it into the app's node_modules.
+import { requireNativeModule, requireNativeView } from 'expo';
+
+/**
+ * Props of the native lens. Names MUST match the `Prop("…")` calls in `GlassLensModule.kt`:
+ * Expo swallows an unknown prop silently, and the lens just doesn't turn on — that's exactly how
+ * refraction ended up disabled in production for an entire phase. Parity is pinned down by a
+ * consuming app's own material-parity test.
+ *
+ * Material values aren't assembled here by hand — they come from `toLensProps` (`adapters.ts`).
+ */
+export type GlassLensProps = {
+  /** Tag of the GlassBackdrop whose frame snapshot the lens uses for refraction. */
+  backdropId?: number | null;
+  /** AGSL source. Assembled in JS so the lens and the surface share one geometry string. */
+  shaderSource: string;
+  /** Size of the VISIBLE glass, in dp. The view itself must be bigger than it: the rim gathers
+   *  light from OUTSIDE the shape, and scattering blurs the backdrop around a point — without
+   *  the margin the shader has nothing there to sample. The lightness probe's rectangle is taken
+   *  from the same size. */
+  glassWidth: number;
+  glassHeight: number;
+  /** Material uniforms as one channel (`toLensProps`): name ↔ size ↔ values. There used to be a
+   *  separate prop per value, and a typo would silently turn the whole lens off. */
+  uniformNames: string[];
+  uniformSizes: number[];
+  /** Values arrive through the animated prop: the pull worklet substitutes them in. They CANNOT
+   *  also be sent through the ordinary prop at the same time — on frequent repaints it
+   *  overwrites what was substituted in. */
+  uniformValues?: number[];
+  /** Lightness, variegation and average color of the backdrop UNDER the glass. The app listens
+   *  to this to recolor the ink once the glass has worked past its own limit. */
+  onBackdropSample?: (e: {
+    nativeEvent: {
+      luma: number;
+      busy: number;
+      lo: number;
+      hi: number;
+      r: number;
+      g: number;
+      b: number;
+    };
+  }) => void;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+};
+
+
+const native = (() => {
+  if (Platform.OS !== 'android') return null;
+  try {
+    const view = requireNativeView('GlassLens', 'GlassLensView') as ComponentType<GlassLensProps>;
+    const constants = requireNativeModule('GlassLens') as { isSupported?: boolean };
+    return { view, supported: constants.isSupported === true };
+  } catch (e) {
+    console.warn('GlassLens: native view failed to load', e);
+    return null;
+  }
+})();
+
+export type GlassBackdropProps = { style?: StyleProp<ViewStyle>; children?: ReactNode };
+
+/**
+ * Backdrop capture WITHOUT blur. expo-blur hands back a dithered copy: on Android 13+ it routes
+ * the capture through `createBlurEffect`, and Skia dithers the blur's output (measured in the
+ * lab, see `docs/benchmarks.md`).
+ */
+export const GlassBackdrop: ComponentType<GlassBackdropProps> | null =
+  Platform.OS === 'android'
+    ? (() => {
+        try {
+          return requireNativeView('GlassLens', 'GlassBackdropView') as ComponentType<GlassBackdropProps>;
+        } catch {
+          return null;
+        }
+      })()
+    : null;
+
+/** Diagnostic probe: exactly what arrives in `createRuntimeShaderEffect`.
+ *  Lab-only, not used in production UI. */
+export type GlassProbeProps = {
+  /** 0 — raw sample, 1 — sample + a shader-liveness marker, 2 — alpha map. */
+  mode?: number;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+};
+
+export const GlassProbe: ComponentType<GlassProbeProps> | null =
+  Platform.OS === 'android'
+    ? (() => {
+        try {
+          return requireNativeView('GlassLens', 'GlassProbeView') as ComponentType<GlassProbeProps>;
+        } catch {
+          return null;
+        }
+      })()
+    : null;
+
+/** `RenderEffect.createRuntimeShaderEffect` — Android 13+. Below it, the caller must stay on the
+ *  previous affine magnification: the view there just works as an ordinary container. */
+export const isGlassLensSupported: boolean = native?.supported ?? false;
+
+export const GlassLens: ComponentType<GlassLensProps> | null = native?.view ?? null;

package/src/native/provider.tsx

@@ -0,0 +1,58 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { mergeAccessibility, useSystemAccessibility } from './system-accessibility';
+import type { VireGlassAccessibility } from '../accessibility';
+
+/**
+ * Host app policy for VireGlass, provided once at the root.
+ *
+ * `glassEnabled` is the app's escape hatch: the performance envelope here was measured on one
+ * flagship device, and behaviour on weak hardware is unknown, so the host must be able to turn
+ * all glass off at once. `backdropAllowed` lets the host suppress live backdrops on its own terms
+ * (e.g. while a sheet is open) — without it, `glassEnabled` is the fallback for that too.
+ */
+type VireGlassContextValue = {
+  glassEnabled: boolean;
+  reduceMotion: boolean;
+  backdropAllowed?: (topLayer: boolean) => boolean;
+};
+
+const DEFAULT_CONTEXT: VireGlassContextValue = {
+  glassEnabled: true,
+  reduceMotion: false,
+};
+
+/** A default value, not a throw: a host that hasn't mounted the provider still gets working
+ *  glass with sane defaults, rather than a crash on first render. */
+const VireGlassContext = createContext<VireGlassContextValue>(DEFAULT_CONTEXT);
+
+export function VireGlassProvider({
+  glassEnabled = true,
+  reduceMotion = false,
+  backdropAllowed,
+  children,
+}: {
+  glassEnabled?: boolean;
+  reduceMotion?: boolean;
+  backdropAllowed?: (topLayer: boolean) => boolean;
+  children: ReactNode;
+}) {
+  const value = useMemo<VireGlassContextValue>(
+    () => ({ glassEnabled, reduceMotion, backdropAllowed }),
+    [glassEnabled, reduceMotion, backdropAllowed],
+  );
+  return <VireGlassContext.Provider value={value}>{children}</VireGlassContext.Provider>;
+}
+
+/** System accessibility settings merged with the host's own motion toggle. Memoized, as the
+ *  original store-backed version was: it feeds shader uniforms downstream, and an unstable
+ *  reference there would recompute them on every render for no reason. */
+export function useAccessibilityModifiers(): VireGlassAccessibility {
+  const { reduceMotion } = useContext(VireGlassContext);
+  const system = useSystemAccessibility();
+  return useMemo(() => mergeAccessibility(system, reduceMotion), [system, reduceMotion]);
+}
+
+export function useBackdropEnabled(topLayer?: boolean): boolean {
+  const { glassEnabled, backdropAllowed } = useContext(VireGlassContext);
+  return backdropAllowed?.(topLayer ?? false) ?? glassEnabled;
+}

package/src/native/surface-registry.ts

@@ -0,0 +1,51 @@
+import { useEffect } from 'react';
+
+/**
+ * Budget of simultaneous glass surfaces.
+ *
+ * Measured on the reference device (Xiaomi 2311DRK48G, Android 16, release, 120 Hz — an 8.33 ms
+ * frame budget): about 0.8 ms of GPU per surface, growing linearly with no threshold — 4 ms at
+ * one, 5 at two, 7 at three, 8 at six. Six is where the budget runs out, not where a measured
+ * cliff is: the saturation point was never found, because the lab scene lays surfaces out in a
+ * column and at six they already hit the screen edge.
+ *
+ * The cost also depends on the scene, not just the count: the same six surfaces over a patterned
+ * canvas with motion cost 20 ms. One, two and three agree across runs.
+ *
+ * See docs/benchmarks.md. Anything measured before 2026-08-31 is void — the capture node had no
+ * bounds and the lens was sampling emptiness.
+ */
+export const GLASS_GREEN_MAX = 6;
+
+/**
+ * Counter of live glass surfaces — dev only.
+ *
+ * A consuming app's own test can guard its **declared** budget model; this counter guards the
+ * **actual** one and catches drift between the two: a new screen, one panel too many, a
+ * suppression under a sheet that got forgotten.
+ */
+let live = 0;
+let peak = 0;
+
+export function useGlassSurfaceRegistration(active: boolean): void {
+  useEffect(() => {
+    if (!__DEV__ || !active) return;
+    live += 1;
+    if (live > peak) peak = live;
+    if (live > GLASS_GREEN_MAX) {
+      console.warn(
+        `[vireglass] simultaneous surfaces with a live backdrop: ${live} — past the measured ` +
+          `green zone (${GLASS_GREEN_MAX}), where the frame budget is already spent. Beyond it ` +
+          `nothing is measured.`,
+      );
+    }
+    return () => {
+      live -= 1;
+    };
+  }, [active]);
+}
+
+/** For manual diagnostics from the lab and from logs. */
+export function glassSurfaceStats(): { live: number; peak: number } {
+  return { live, peak };
+}

package/src/native/system-accessibility.ts

@@ -0,0 +1,90 @@
+// System accessibility settings (reference `docs/reference.md` §9): the material has to listen
+// to them on its own, without help from screens. This module only READS the system; the host
+// app's own toggle is mixed in by the provider (`provider.tsx`), so this module knows nothing
+// about the app.
+import { useSyncExternalStore } from 'react';
+import { AccessibilityInfo, Platform } from 'react-native';
+import type { VireGlassAccessibility } from '../accessibility';
+
+export type SystemAccessibility = {
+  reduceMotion: boolean;
+  reduceTransparency: boolean;
+  increaseContrast: boolean;
+};
+
+const OFF: SystemAccessibility = {
+  reduceMotion: false,
+  reduceTransparency: false,
+  increaseContrast: false,
+};
+
+let state: SystemAccessibility = OFF;
+const listeners = new Set<() => void>();
+let subscriptions: { remove: () => void }[] = [];
+
+function put(key: keyof SystemAccessibility, value: boolean): void {
+  if (state[key] === value) return;
+  state = { ...state, [key]: value };
+  for (const notify of listeners) notify();
+}
+
+/** Contrast is named differently per system: on Android it's high-contrast text, on iOS it's
+ *  darker system colors. The signal is one and the same, and the material responds to it
+ *  identically. */
+const CONTRAST =
+  Platform.OS === 'ios'
+    ? { read: () => AccessibilityInfo.isDarkerSystemColorsEnabled(), event: 'darkerSystemColorsChanged' as const }
+    : { read: () => AccessibilityInfo.isHighTextContrastEnabled(), event: 'highTextContrastChanged' as const };
+
+function start(): void {
+  // The first answer arrives as a promise, later ones as an event: without the first, a setting
+  // only gets picked up after someone toggles it — i.e. never, on a screen that's already open.
+  AccessibilityInfo.isReduceMotionEnabled().then((on) => put('reduceMotion', on)).catch(() => {});
+  AccessibilityInfo.isReduceTransparencyEnabled().then((on) => put('reduceTransparency', on)).catch(() => {});
+  CONTRAST.read().then((on) => put('increaseContrast', on)).catch(() => {});
+  subscriptions = [
+    AccessibilityInfo.addEventListener('reduceMotionChanged', (on) => put('reduceMotion', on)),
+    AccessibilityInfo.addEventListener('reduceTransparencyChanged', (on) => put('reduceTransparency', on)),
+    AccessibilityInfo.addEventListener(CONTRAST.event, (on) => put('increaseContrast', on)),
+  ];
+}
+
+function stop(): void {
+  for (const subscription of subscriptions) subscription.remove();
+  subscriptions = [];
+}
+
+/**
+ * ONE subscription per app, not per surface: a screen can hold up to a dozen glass elements at
+ * once, and a pair of bridge requests for each of them would be a real cost for no reason.
+ * Native listeners live as long as there's at least one reader.
+ */
+export function subscribeToSystemAccessibility(listener: () => void): () => void {
+  if (listeners.size === 0) start();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) stop();
+  };
+}
+
+const read = (): SystemAccessibility => state;
+
+export function useSystemAccessibility(): SystemAccessibility {
+  return useSyncExternalStore(subscribeToSystemAccessibility, read, read);
+}
+
+/**
+ * The app's own setting combines with the system one and can only TIGHTEN it: someone who asked
+ * the system to remove motion shouldn't get it back because of a toggle inside the kit.
+ */
+export function mergeAccessibility(
+  system: SystemAccessibility,
+  appReduceMotion: boolean,
+): VireGlassAccessibility {
+  return {
+    reduceTransparency: system.reduceTransparency,
+    increaseContrast: system.increaseContrast,
+    reduceMotion: system.reduceMotion || appReduceMotion,
+  };
+}

package/src/optics.ts

@@ -0,0 +1,177 @@
+// Deriving optics from the medium's properties. The material describes CAUSES (index of
+// refraction, thickness, bevel, roughness); the shaders need EFFECTS — this file translates one
+// into the other. Pure functions, no imports: the physics is checked by tests, not on a device.
+//
+// There are normalization constants here, and they're honestly labeled as such: the rendering is
+// stylized, and literal physical values (glass reflects 4% at normal incidence) produce effects
+// right at the threshold of visibility. Each normalization is monotonic in its own cause, so
+// "denser medium → more visible rim" always holds, and no impossible combination can arise.
+
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);
+const clamp01 = (v: number) => clamp(v, 0, 1);
+
+/** Reflectance at normal incidence: ((n−1)/(n+1))². For glass, n=1.5 gives 0.04. */
+export const fresnelF0 = (ior: number) => ((ior - 1) / (ior + 1)) ** 2;
+
+/** Translation of the physical 4% into the render's working range. */
+const FRESNEL_GAIN = 17.5;
+
+export const fresnelStrength = (ior: number) => clamp01(fresnelF0(ior) * FRESNEL_GAIN);
+
+/** Exponent in the Schlick approximation — a constant of the model, not a knob. */
+export const FRESNEL_EXPONENT = 5;
+
+/** Strength of ray bending. As n→1 the medium is indistinguishable from air; n=1.6 is taken as
+ *  full strength. */
+export const refractionStrength = (ior: number) => clamp01((ior - 1) / 0.6);
+
+/** Magnification behind a plane-parallel plate: grows with thickness and with (1 − 1/n). */
+const MAGNIFY_PER_DP = 0.006;
+
+export const refractionScale = (ior: number, thicknessDp: number) =>
+  1 + MAGNIFY_PER_DP * thicknessDp * (1 - 1 / Math.max(ior, 1));
+
+/** In ordinary glasses the Abbe number falls as n rises — dispersion grows along with it. */
+const DISPERSION_PER_IOR = 1.1;
+
+export const dispersion = (ior: number) => clamp01((ior - 1) * DISPERSION_PER_IOR);
+
+/** Spread of the index between the red and blue channels. The physical value (~0.01 at an Abbe
+ *  number of 55) sits at the threshold of visibility — a stylization of the same monotonicity as
+ *  Fresnel's. */
+const IOR_SPREAD_PER_DISPERSION = 0.045;
+
+export const iorSpread = (ior: number) => dispersion(ior) * IOR_SPREAD_PER_DISPERSION;
+
+/** Beer–Lambert: how much the medium absorbs over a path of length `pathDp`. */
+const ABSORB_PER_DP = 0.017;
+
+export const absorption = (pathDp: number) => 1 - Math.exp(-ABSORB_PER_DP * Math.max(pathDp, 0));
+
+/**
+ * Density at the bevel relative to the body. Not a separate quantity: at the rim the ray travels
+ * LONGER through the medium by the bevel's width, and absorption over that path is greater. This
+ * used to be a separate `edgeDensity` slider, which is how a thin bevel with a milky rim got
+ * built — a state that doesn't occur in real glass.
+ */
+export const edgeDensity = (thicknessDp: number, bevelDp: number) => {
+  const body = absorption(thicknessDp);
+  if (body <= 0) return 1;
+  return clamp(absorption(thicknessDp + bevelDp) / body, 1, 4);
+};
+
+/**
+ * Backdrop haziness — surface roughness, not a separate blur setting.
+ *
+ * The ceiling is deliberately low. Blur in this model is a SUPPORTING device: it helps ink sit
+ * over glass, but doesn't improve the picture on its own. Past roughly a dozen dp, letters under
+ * the glass stop being letters and turn into a mush of pixels — no amount of legibility justifies
+ * that. Separating content from the ink is body density's job, not blur's.
+ */
+const BLUR_MAX = 12;
+
+export const blur = (roughness: number) => clamp01(roughness) * BLUR_MAX;
+
+/** A smooth surface gives a narrow highlight, a rough one a spread-out one. */
+export const specularPower = (roughness: number) => 160 - clamp01(roughness) * 152;
+
+/** Highlight brightness — the same reflectance as Fresnel, damped by roughness. */
+export const specularStrength = (ior: number, roughness: number) =>
+  clamp01(fresnelStrength(ior) * (1 - clamp01(roughness) * 0.6));
+
+/**
+ * Color of the medium. Never set by hand: in transparent media, hue is tied to density. Water
+ * absorbs red and skews cool, ordinary glass is nearly neutral with a faint green, dense
+ * high-index media skew warm. Lightness follows reflectance: the denser the medium, the more of
+ * its surroundings it returns, and the lighter its body reads.
+ */
+const COOL = { r: 0.86, g: 1.0, b: 1.08 };
+const NEUTRAL = { r: 1.0, g: 1.02, b: 0.99 };
+const WARM = { r: 1.08, g: 1.0, b: 0.88 };
+
+const mixHue = (a: typeof COOL, b: typeof COOL, t: number) => ({
+  r: a.r + (b.r - a.r) * t,
+  g: a.g + (b.g - a.g) * t,
+  b: a.b + (b.b - a.b) * t,
+});
+
+export function mediumTint(ior: number): { r: number; g: number; b: number } {
+  const t = clamp01((ior - 1.2) / 0.55);
+  const hue = t < 0.5 ? mixHue(COOL, NEUTRAL, t * 2) : mixHue(NEUTRAL, WARM, (t - 0.5) * 2);
+  const lift = 0.34 + fresnelF0(ior) * 2.4;
+  return { r: clamp01(hue.r * lift), g: clamp01(hue.g * lift), b: clamp01(hue.b * lift) };
+}
+
+/**
+ * How far the rim gathers light AROUND the element.
+ *
+ * On real glass, at a grazing angle the eye receives not what's under the glass but the
+ * surroundings: an object on a black table next to a lamp catches the lamp. So the radius is
+ * noticeably larger than the bevel — it's the element's vicinity, not its rim. Without this,
+ * glass on an empty black background has no source at all and honestly disappears.
+ */
+const GATHER_PER_BEVEL = 4;
+
+/**
+ * Ceiling on the radius. Without it, a wide bevel would gather its surroundings from fifty-odd dp
+ * away, and a READABLE copy of whatever sits nearby would appear inside the glass: eight samples
+ * aren't enough to blur a disc that large (E-33, E-37). Real rims also gather light mostly from
+ * nearby — an unbounded radius was a modeling mistake.
+ */
+const GATHER_MAX = 28;
+
+export const gatherRadius = (bevelDp: number) =>
+  clamp(Math.max(bevelDp, 1) * GATHER_PER_BEVEL, 4, GATHER_MAX);
+
+/**
+ * The body's own density from absorption through its thickness. Small: glass has no color of its
+ * own, the body only moves toward the tint under the legibility requirement (HIG "Color"),
+ * otherwise it dims the content.
+ */
+const BODY_DENSITY = 0.05;
+
+export const bodyDensity = (thicknessDp: number) => BODY_DENSITY * absorption(thicknessDp);
+
+/**
+ * Highlight normalization. `fresnelStrength`'s ×17.5 factor is tuned for the rim highlight's
+ * visibility and saturates at one for dense media; applying it to the highlight too would raise
+ * body lightness harder than the glass had just separated it from the ink — eating its own
+ * legibility work. This uses the physical scale instead.
+ */
+const EDGE_LIGHT_GAIN = 6;
+
+/** How much the rim picks up the light and color of its surroundings. The same reflectance as
+ *  Fresnel: no separate knob — a dense medium returns more of its surroundings by construction. */
+
+export const edgeLight = (ior: number) => clamp01(fresnelF0(ior) * EDGE_LIGHT_GAIN);
+
+/**
+ * THE SPECTRAL PART. Three phenomena — dispersion, diffraction and interference — share one
+ * cause: index of refraction and phase both depend on wavelength. So there are no separate
+ * "rainbow strength" knobs here: everything is derived from the medium's density and film
+ * thickness.
+ */
+
+/**
+ * Rim iridescence is visible exactly as much as the REFLECTION is bright: interference lives in
+ * the reflected ray, not the transmitted one. Hence the tie to Fresnel — there's no strength knob
+ * of its own.
+ */
+export const iridescence = (ior: number, filmNm: number) =>
+  filmNm <= 0 ? 0 : clamp01(fresnelStrength(ior) * 1.6);
+
+/**
+ * Edge diffraction. Same λ-dependence as dispersion, so it shares its strength; the bevel sets
+ * the fringe frequency — wide bevels give sparse fringes, sharp ones frequent (in the shader this
+ * is divided by bevel width). The 0.5 normalization reflects the stylized render: at the physical
+ * amplitude the fringes aren't visible at all.
+ */
+export const diffraction = (ior: number) => clamp01(dispersion(ior) * 0.5);
+
+/**
+ * How much the body picks up the COLOR of its surroundings. This is multiple internal reflection:
+ * the denser the medium, the more light it circulates inside itself, and the more strongly it's
+ * tinted by what's around it. The ceiling is deliberately low — the tint has to stay a medium, not
+ * become a flat color fill.
+ */
+export const colorPickup = (ior: number) => clamp(fresnelStrength(ior) * 0.9, 0, 0.42);

package/src/react.ts

@@ -0,0 +1,102 @@
+// The React binding for backdrop adaptation. It lives behind its own entry point (`vireglass/react`)
+// so that the core stays dependency-free: the decision itself is a pure function in
+// `adaptation.ts`, and only the confirmation policy and the fade need hooks.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { VireGlassOptics } from './material';
+import {
+  CONFIRMATIONS,
+  FADE_MS,
+  shouldInkBeLight,
+  type BackdropSample,
+} from './adaptation';
+export type GlassAdaptation = {
+  /** Ink polarity: 1 light, 0 dark. Travels smoothly between the ends. */
+  ink: number;
+  /** The latest backdrop sample — used for the accent and for debug hints. */
+  sample: BackdropSample | null;
+  /** Pass to `VireGlassSurface`. */
+  onBackdropSample: (e: { nativeEvent: BackdropSample }) => void;
+};
+
+/**
+ * Content polarity that follows the backdrop under the glass on its own.
+ *
+ * `initial` — the polarity the screen starts with (usually light ink on a dark theme).
+ * `enabled = false` freezes it: a screen that already knows its own content is entitled to not
+ * hand the decision to the automation.
+ */
+export function useGlassAdaptation(
+  optics: Pick<VireGlassOptics, 'legibility' | 'bodyDensity' | 'ink' | 'edgeLight'>,
+  options: { enabled?: boolean } = {},
+): GlassAdaptation {
+  const enabled = options.enabled ?? true;
+  const [ink, setInk] = useState(optics.ink);
+  const [sample, setSample] = useState<BackdropSample | null>(null);
+
+  const target = useRef(optics.ink > 0.5 ? 1 : 0);
+  // The current value also lives in a ref: without it the callback would depend on state and get
+  // recreated on EVERY frame of the fade, meaning the native view's prop would change identity 60
+  // times a second for no reason but that.
+  const current = useRef(optics.ink);
+  const lastSample = useRef<BackdropSample | null>(null);
+  const pending = useRef(0);
+  const from = useRef(optics.ink);
+  const startedAt = useRef(0);
+  const raf = useRef<ReturnType<typeof requestAnimationFrame> | null>(null);
+
+  // The fade runs frame by frame, not on a worklet spring: the value feeds not only text color
+  // but also the lens uniform, and that's set through a prop — i.e. from a React render.
+  const animate = useCallback(() => {
+    const step = () => {
+      const t = Math.min((Date.now() - startedAt.current) / FADE_MS, 1);
+      // Cosine easing: a linear transition reads as motion, this one doesn't.
+      const e = 0.5 - 0.5 * Math.cos(Math.PI * t);
+      current.current = from.current + (target.current - from.current) * e;
+      setInk(current.current);
+      raf.current = t < 1 ? requestAnimationFrame(step) : null;
+    };
+    if (raf.current !== null) cancelAnimationFrame(raf.current);
+    raf.current = requestAnimationFrame(step);
+  }, []);
+
+  useEffect(() => () => {
+    if (raf.current !== null) cancelAnimationFrame(raf.current);
+  }, []);
+
+  const onBackdropSample = useCallback(
+    (e: { nativeEvent: BackdropSample }) => {
+      const next = e.nativeEvent;
+      // The sample arrives several times a second. It only lands in state when it actually
+      // moved: otherwise every sample would drag a consumer repaint behind it.
+      const prev = lastSample.current;
+      if (
+        prev === null ||
+        Math.abs(prev.luma - next.luma) > 0.01 ||
+        Math.abs(prev.busy - next.busy) > 0.02
+      ) {
+        lastSample.current = next;
+        setSample(next);
+      }
+      if (!enabled) return;
+
+      const wasLight = target.current === 1;
+      // The actual decision lives in `shouldInkBeLight`: one place for every platform. What's
+      // left here is just the confirmation policy, and that's the app's own.
+      const wants = shouldInkBeLight(next, wasLight) !== wasLight;
+      if (!wants) {
+        pending.current = 0;
+        return;
+      }
+      pending.current += 1;
+      if (pending.current < CONFIRMATIONS) return;
+      pending.current = 0;
+      from.current = current.current;
+      target.current = wasLight ? 0 : 1;
+      startedAt.current = Date.now();
+      animate();
+    },
+    [enabled, animate],
+  );
+
+  return { ink, sample, onBackdropSample };
+}