panelui-native 0.82.0 → 0.84.0

package/src/components/bottom-sheet/index.tsx

@@ -38,7 +38,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { tv } from 'tailwind-variants';
-import { getNativeUI } from '../../native';
+import { getComposeModifiers, getNativeUI, getSwiftUIModifiers } from '../../native';
 import { XIcon } from '../../icons';
 import { ModalPortal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
@@ -149,6 +149,22 @@ export interface BottomSheetProps {
    * nearest of `half` / `full`.
    */
   snapPoints?: ('half' | 'full' | { fraction: number } | { height: number })[];
+  /**
+   * Paint the native sheet a solid colour instead of the material the platform
+   * draws it in by default.
+   *
+   * The platform's sheet is translucent — on iOS 26 that is Liquid Glass — and
+   * what is behind it shows through. That is right for a sheet laid over
+   * content worth glimpsing and wrong for one that is a surface of the app's
+   * own, where the app's ground shifting under it reads as a mistake.
+   *
+   * `true` uses the theme's popover surface, so the sheet matches the rest of
+   * the app in both schemes. A string paints that colour exactly.
+   *
+   * It only reaches the platform's sheet, so it does nothing without `native`.
+   * On iOS below 16.4 the sheet keeps its material.
+   */
+  nativeBackground?: boolean | string;
 }
 
 /**
@@ -158,6 +174,22 @@ export interface BottomSheetProps {
  */
 const DETENT_FRACTION = { half: 0.5, full: 0.9 } as const;
 
+/**
+ * How long to treat a dismissal *we* asked for as still in flight.
+ *
+ * A timer, because there is nothing to wait on. The platform reports a
+ * dismissal the reader performed — that report is the binding writing its new
+ * value back — but not one we asked for, where the binding already holds the
+ * value it would have written and the change is suppressed at the source. So
+ * the only sheet whose departure can be observed is the one we did not ask to
+ * leave.
+ *
+ * Comfortably past the system's own sheet transition, since the cost of being
+ * late is a present held a little longer than it needed to be, and the cost of
+ * being early is the platform dropping it and no sheet at all.
+ */
+const NATIVE_DISMISS_MS = 400;
+
 /**
  * The height the content should at least fill for a given set of detents.
  *
@@ -191,6 +223,29 @@ export function bottomSheetDetentHeight(
   return undefined;
 }
 
+/**
+ * The modifier that paints a native sheet's own surface, for whichever toolkit
+ * is drawing it — or nothing, where neither is reachable.
+ *
+ * A sheet's surface is not the background of anything hosted in it. The
+ * grabber's strip at the top and the safe-area inset at the bottom are the
+ * sheet's own chrome, and a colour put behind the content stops short of both
+ * of them — so the sheet arrives two-tone, and shifts as it moves between
+ * detents. These two reach the surface itself.
+ *
+ * The toolkits do not share a vocabulary, so the question is asked of each in
+ * its own terms rather than one answer being sent to both.
+ */
+function nativeSheetSurface(color: string): unknown[] | undefined {
+  const swiftUI = getSwiftUIModifiers();
+  if (swiftUI) return [swiftUI.presentationBackground(color)];
+
+  const compose = getComposeModifiers();
+  if (compose) return [compose.background(color)];
+
+  return undefined;
+}
+
 /**
  * Set by the root so Content knows the platform is drawing the sheet, and with
  * which detents. Null means the styled sheet renders.
@@ -198,6 +253,7 @@ export function bottomSheetDetentHeight(
 const NativeSheetContext = createContext<{
   nativeUI: NonNullable<ReturnType<typeof getNativeUI>>;
   snapPoints: BottomSheetProps['snapPoints'];
+  background: BottomSheetProps['nativeBackground'];
 } | null>(null);
 
 /**
@@ -225,6 +281,7 @@ function BottomSheetRoot({
   defaultOpen = false,
   native,
   snapPoints,
+  nativeBackground,
 }: BottomSheetProps) {
   const [internalOpen, setInternalOpen] = useState(defaultOpen);
   const isControlled = open !== undefined;
@@ -245,8 +302,8 @@ function BottomSheetRoot({
 
   const nativeUI = native ? getNativeUI() : null;
   const nativeSheet = useMemo(
-    () => (nativeUI ? { nativeUI, snapPoints } : null),
-    [nativeUI, snapPoints]
+    () => (nativeUI ? { nativeUI, snapPoints, background: nativeBackground } : null),
+    [nativeBackground, nativeUI, snapPoints]
   );
 
   return (
@@ -352,6 +409,10 @@ function BottomSheetContent({
   const insets = useSafeAreaInsets();
   const translateY = useSharedValue(0);
   const closeTint = useCSSVariable('--color-muted-foreground');
+  // Read unconditionally, used only by the native branch: the platform draws
+  // that sheet's container, so a token can only reach it as a colour handed
+  // over, never as a class.
+  const popoverSurface = useCSSVariable('--color-popover');
 
   /*
    * The scrolling body's gesture, if there is one. It is built here rather
@@ -428,41 +489,86 @@ function BottomSheetContent({
    * sees a sheet that "took a moment" or never came at all.
    *
    * `isPresented` is therefore driven from here rather than straight from
-   * `open`. A present that arrives during a dismissal is held, and replayed
-   * from the platform's own `onDismiss`, which is the only signal that says the
-   * previous sheet has finished going away.
+   * `open`: a present that arrives during a dismissal is held, and let through
+   * once that dismissal is over.
+   *
+   * Knowing when it is over is the hard half, because it depends on who asked.
+   * A dismissal the reader performed is reported — that report is the platform
+   * writing the new value back to us. One we asked for is not: the value is
+   * already what the platform would have written, so the change is suppressed
+   * at the source and no report is ever sent. A queue that waits for one
+   * regardless waits for ever, and every present after the first is held —
+   * which is a sheet that opens once and then never again, whether the flag was
+   * raised by the reader's swipe or by a Close button inside the sheet.
+   *
+   * So the two are ended by their own means: the reader's by the report, ours
+   * by {@link NATIVE_DISMISS_MS} — and by the report as well, if one turns up,
+   * since arriving early is only ever an improvement.
    */
   const [nativePresented, setNativePresented] = useState(open);
+  const nativeOnScreen = useRef(open);
   const nativeDismissing = useRef(false);
+  const nativeDismissTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const openRef = useRef(open);
   openRef.current = open;
 
+  /** The dismissal is over: let a held present through, if one is waiting. */
+  const endNativeDismissal = useCallback(() => {
+    if (nativeDismissTimer.current !== null) {
+      clearTimeout(nativeDismissTimer.current);
+      nativeDismissTimer.current = null;
+    }
+    if (!nativeDismissing.current) return;
+    nativeDismissing.current = false;
+
+    if (openRef.current) {
+      nativeOnScreen.current = true;
+      setNativePresented(true);
+    }
+  }, []);
+
   useEffect(() => {
     if (!nativeSheet) return;
 
     if (open) {
       if (nativeDismissing.current) return;
+      nativeOnScreen.current = true;
       setNativePresented(true);
       return;
     }
 
-    if (nativePresented) nativeDismissing.current = true;
+    // Only a sheet the platform still has on screen can be in the middle of
+    // leaving. One the reader already swiped away has reported itself gone.
+    if (nativeOnScreen.current) {
+      nativeOnScreen.current = false;
+      nativeDismissing.current = true;
+      if (nativeDismissTimer.current !== null) clearTimeout(nativeDismissTimer.current);
+      nativeDismissTimer.current = setTimeout(endNativeDismissal, NATIVE_DISMISS_MS);
+    }
     setNativePresented(false);
-  }, [nativePresented, nativeSheet, open]);
+  }, [endNativeDismissal, nativeSheet, open]);
 
-  const onNativeDismiss = useCallback(() => {
-    // Ours, or the reader's? A dismissal we asked for has to hand the queue
-    // back; one the reader performed has to be reported as a close.
-    const wasOurs = nativeDismissing.current;
-    nativeDismissing.current = false;
+  useEffect(
+    () => () => {
+      if (nativeDismissTimer.current !== null) clearTimeout(nativeDismissTimer.current);
+    },
+    []
+  );
 
-    if (wasOurs) {
-      if (openRef.current) setNativePresented(true);
+  const onNativeDismiss = useCallback(() => {
+    // The platform reporting that its sheet has gone. Whatever asked for it,
+    // there is nothing on screen now.
+    nativeOnScreen.current = false;
+
+    // Ours, or the reader's? A dismissal we asked for hands the queue back
+    // ahead of its window; one the reader performed is a close to report.
+    if (nativeDismissing.current) {
+      endNativeDismissal();
       return;
     }
 
     if (dismissible) close();
-  }, [close, dismissible]);
+  }, [close, dismissible, endNativeDismissal]);
 
   const pan = useMemo(
     () =>
@@ -571,6 +677,22 @@ function BottomSheetContent({
      */
     const snapPoints =
       nativeSheet.snapPoints ?? (size === 'auto' ? undefined : [size]);
+    /*
+     * `true` means the theme's surface, and a string means itself. A token
+     * that did not resolve is dropped rather than passed on — an unresolved
+     * colour reaching the platform is a sheet painted some default, which is
+     * further from the material than leaving the material alone.
+     */
+    const requested = nativeSheet.background;
+    const surface =
+      requested === true
+        ? typeof popoverSurface === 'string'
+          ? popoverSurface
+          : undefined
+        : typeof requested === 'string'
+          ? requested
+          : undefined;
+    const modifiers = surface ? nativeSheetSurface(surface) : undefined;
     // The platform owns presentation, so this stays mounted and toggles
     // isPresented rather than unmounting on close.
     //
@@ -583,6 +705,7 @@ function BottomSheetContent({
           isPresented={nativePresented}
           onDismiss={onNativeDismiss}
           snapPoints={snapPoints}
+          modifiers={modifiers}
         >
           <RNHostView matchContents>
             <BottomSheetContext.Provider value={context}>

package/src/components/circular-text/circular-text-geometry.ts

@@ -0,0 +1,80 @@
+/**
+ * Where each character sits on the ring, kept out of the component so it can
+ * be tested without rendering one.
+ *
+ * Every number here reaches a transform, and a transform treats `NaN` and
+ * `Infinity` as a frame that never resolves rather than as an error — a ring
+ * handed a bad radius should draw nothing, not wedge. So the guards live at
+ * the boundary, once, instead of at each use.
+ */
+
+/** Points from the centre to the baseline the characters sit on. */
+export const DEFAULT_CIRCULAR_TEXT_RADIUS = 90;
+
+/** Milliseconds for one full turn. Slow: it is decoration, not a spinner. */
+export const DEFAULT_CIRCULAR_TEXT_DURATION = 20000;
+
+/** Degrees of the circle the text is spread across. The whole way round. */
+export const DEFAULT_CIRCULAR_TEXT_SPREAD = 360;
+
+export function normalizeRadius(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_CIRCULAR_TEXT_RADIUS;
+  return Math.max(value, 0);
+}
+
+export function normalizeDuration(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_CIRCULAR_TEXT_DURATION;
+  return Math.max(value, 0);
+}
+
+export function normalizeSpread(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_CIRCULAR_TEXT_SPREAD;
+  // Clamped rather than wrapped: past a full turn the characters would overlap
+  // the ones already there, and a spread of -40 is a spread of 40 the other
+  // way round, which `reverse` is the prop for.
+  return Math.min(Math.abs(value), 360);
+}
+
+export interface CircularTextGlyph {
+  /** The character itself. */
+  character: string;
+  /** Its place in the string, which is what makes a stable key. */
+  index: number;
+  /** Degrees clockwise from the top, before any rotation of the ring. */
+  angle: number;
+}
+
+/**
+ * One entry per character, evenly spaced around the arc.
+ *
+ * The step is measured between characters rather than across them, and which
+ * of the two you divide by is the whole difference between a closed ring and
+ * one with a visible seam. A full turn has no last gap — the end of the string
+ * is adjacent to its start — so `n` characters make `n` gaps and the step is
+ * `spread / n`. Anything less than a full turn has one gap fewer than it has
+ * characters, so the step is `spread / (n - 1)` and the text reaches both ends
+ * of the arc it was given instead of stopping short of the second one.
+ */
+export function circularTextGlyphs(
+  text: string,
+  spread: number,
+  startAngle: number
+): CircularTextGlyph[] {
+  const characters = Array.from(text);
+  if (characters.length === 0) return [];
+
+  const arc = normalizeSpread(spread);
+  const from = Number.isFinite(startAngle) ? startAngle : 0;
+  const closed = arc >= 360;
+
+  // One character cannot be spread across anything, and dividing by the zero
+  // gaps it has would put it nowhere.
+  const step =
+    characters.length === 1 ? 0 : arc / (closed ? characters.length : characters.length - 1);
+
+  return characters.map((character, index) => ({
+    character,
+    index,
+    angle: from + step * index,
+  }));
+}

package/src/components/circular-text/index.tsx

@@ -0,0 +1,217 @@
+import { useEffect, useMemo } from 'react';
+import { View, type ViewProps } from 'react-native';
+import Animated, {
+  Easing,
+  cancelAnimation,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { tv } from 'tailwind-variants';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import {
+  DEFAULT_CIRCULAR_TEXT_DURATION,
+  DEFAULT_CIRCULAR_TEXT_RADIUS,
+  DEFAULT_CIRCULAR_TEXT_SPREAD,
+  circularTextGlyphs,
+  normalizeDuration,
+  normalizeRadius,
+  normalizeSpread,
+} from './circular-text-geometry';
+
+const circularTextVariants = tv({
+  base: 'items-center justify-center',
+});
+
+const glyphVariants = tv({
+  /*
+   * Every character gets a box the size of the ring, laid over the same point,
+   * with the character at the top edge of it. Rotating the box about its own
+   * centre — which is the ring's centre — is what swings the character round
+   * the circle, and it means no per-character arithmetic reaches the transform
+   * beyond the one angle.
+   *
+   * The box's size is set inline rather than by a utility, and that is not
+   * decoration: a box that states its own width and height cannot end up with
+   * a different one, and one glyph sitting at twice the radius of the rest is
+   * exactly what a box of the wrong size looks like.
+   */
+  base: 'items-center justify-start',
+});
+
+/**
+ * The glyph size the ring is drawn at unless the caller says otherwise.
+ *
+ * A step up from the body default. Text bent round a circle is read a letter
+ * at a time rather than as a word, and at body size the letters are small
+ * enough that the ring reads as a texture instead of as a phrase.
+ */
+const GLYPH_TEXT = 'text-lg';
+
+export interface CircularTextProps extends Omit<ViewProps, 'children'> {
+  /**
+   * The text to set around the circle. A string, not elements: each character
+   * is placed and turned on its own, so there is nothing for markup inside it
+   * to apply to.
+   */
+  children: string;
+  /**
+   * Points from the centre of the ring to the outside of the text.
+   *
+   * It is also half the component's width and height — the ring is a square
+   * that measures `radius * 2` on both axes, and the characters hang inside
+   * its edge. Nothing is laid out around it, so give the space it needs.
+   */
+  radius?: number;
+  /**
+   * Milliseconds for one full turn. Slow by default: it is decoration, and a
+   * ring that turns at the speed of a spinner reads as something loading.
+   */
+  spinDuration?: number;
+  /** Turn anticlockwise. */
+  reverse?: boolean;
+  /**
+   * Hold the ring where it is.
+   *
+   * It stops in place rather than returning to the top, and resumes from
+   * there, so a ring paused mid-word is still on that word when it starts
+   * again.
+   */
+  paused?: boolean;
+  /**
+   * Degrees of the circle the text is spread across. The whole way round by
+   * default.
+   *
+   * A full turn has no last gap, since the end of the string is adjacent to
+   * its start. Anything less is an arc with two ends, and the text reaches
+   * both of them.
+   */
+  spread?: number;
+  /** Degrees clockwise from the top that the first character sits at. */
+  startAngle?: number;
+  /** Classes for the ring's own box. */
+  className?: string;
+  /** Classes for the characters — size, weight, colour, tracking. */
+  textClassName?: string;
+}
+
+/**
+ * Text set around a circle, turning.
+ *
+ * For a badge, a seal, a mark around a logo: decoration whose job is to be a
+ * shape first and a sentence second. The characters are placed one at a time
+ * and each is turned to sit square on the curve, so the ring closes and the
+ * text at the bottom is upside down — which is what makes it read as a
+ * circle rather than as a sentence bent into one.
+ *
+ * The centre is left empty and nothing is laid out inside it. Put a logo
+ * there by stacking the two, rather than by passing it as a child.
+ *
+ * The turn runs entirely on the UI thread, and under the platform's
+ * reduce-motion setting the ring is drawn once and held still. Not a slower
+ * turn — none. The shape carries the whole meaning; the rotation is the part
+ * that setting exists to remove.
+ */
+export function CircularText({
+  children,
+  radius = DEFAULT_CIRCULAR_TEXT_RADIUS,
+  spinDuration = DEFAULT_CIRCULAR_TEXT_DURATION,
+  reverse = false,
+  paused = false,
+  spread = DEFAULT_CIRCULAR_TEXT_SPREAD,
+  startAngle = 0,
+  className,
+  textClassName,
+  style,
+  ...props
+}: CircularTextProps) {
+  const reducedMotion = useReducedMotion();
+  const rotation = useSharedValue(0);
+
+  const size = normalizeRadius(radius) * 2;
+  const duration = normalizeDuration(spinDuration);
+  const arc = normalizeSpread(spread);
+
+  const glyphs = useMemo(
+    () => circularTextGlyphs(children, arc, startAngle),
+    [children, arc, startAngle]
+  );
+
+  // A duration of zero is a timing that never advances, so it is a held ring
+  // rather than an infinitely fast one.
+  const turning = !paused && !reducedMotion && duration > 0 && glyphs.length > 0;
+
+  useEffect(() => {
+    if (!turning) {
+      // Leaves the value where it reached. Zeroing here would send a ring
+      // paused mid-word back to the top, and the pause would read as a reset.
+      cancelAnimation(rotation);
+      return undefined;
+    }
+
+    /*
+     * From wherever it already is, one turn, forever.
+     *
+     * The repeat restarts each cycle at the value it began on, and the state
+     * at `from + 360` is the state at `from`, so the seam between cycles is
+     * arithmetic rather than something to see. Taking the remainder first
+     * keeps the number from growing without bound over a long session.
+     */
+    const from = rotation.value % 360;
+    const to = reverse ? from - 360 : from + 360;
+    rotation.value = from;
+    rotation.value = withRepeat(
+      withTiming(to, { duration, easing: Easing.linear }),
+      -1,
+      false
+    );
+
+    return () => cancelAnimation(rotation);
+  }, [rotation, turning, duration, reverse]);
+
+  const ringStyle = useAnimatedStyle(() => ({
+    transform: [{ rotate: `${rotation.value}deg` }],
+  }));
+
+  return (
+    <View
+      accessible
+      accessibilityRole="text"
+      accessibilityLabel={children}
+      className={cn(circularTextVariants(), className)}
+      style={[{ width: size, height: size }, style]}
+      {...props}
+    >
+      {/* Hidden from assistive technology as a group: the label above already
+          says what it reads, and a ring announced character by character is a
+          string spelled out one letter at a time. */}
+      <Animated.View
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        style={[{ width: size, height: size }, ringStyle]}
+      >
+        {glyphs.map((glyph) => (
+          <View
+            key={`${glyph.character}-${glyph.index}`}
+            className={glyphVariants()}
+            style={{
+              position: 'absolute',
+              left: 0,
+              top: 0,
+              width: size,
+              height: size,
+              transform: [{ rotate: `${glyph.angle}deg` }],
+            }}
+          >
+            <Text className={cn(GLYPH_TEXT, textClassName)}>{glyph.character}</Text>
+          </View>
+        ))}
+      </Animated.View>
+    </View>
+  );
+}
+
+CircularText.displayName = 'CircularText';

package/src/components/image-generation/dot-field.ts

@@ -25,6 +25,15 @@ export const DOT_LIT_RADIUS = 1.9;
 /** How visible the resting grid is, under everything. */
 export const DOT_REST_OPACITY = 0.16;
 
+/**
+ * How visible the lit dots are, together.
+ *
+ * "Together" is the operative word: they are drawn as two layers fading into
+ * one another, and this is what the pair composites to, not what either one
+ * carries. {@link crossfadeAlphas} is what holds that true.
+ */
+export const LIT_OPACITY = 0.9;
+
 /** How many still frames one loop is drawn as. */
 export const FRAMES = 24;
 
@@ -118,11 +127,20 @@ export function influenceAt(distance: number, radius: number): number {
 /**
  * Where the light is at a phase of the loop, and how wide it reaches.
  *
- * `drift` wanders around the middle — two periods that do not divide into each
- * other, so the path never closes into a loop the eye can learn, and small
- * amplitudes because a light that reaches the corners stops reading as one
- * source. `pulse` is a ring leaving the centre. `scan` crosses as a band, which
- * is the same maths with the light infinitely tall.
+ * `drift` wanders around the middle on a figure-eight: one horizontal pass to
+ * two vertical, so the path arrives back where it started and the loop has no
+ * seam in it. The amplitudes are small because a light that reaches the corners
+ * stops reading as one source.
+ *
+ * The two frequencies used not to divide into each other, on the reasoning that
+ * a path which never closes is one the eye cannot learn. It closes anyway —
+ * every animation here restarts at the end of its period — so all that bought
+ * was a jump of four normal steps, once a pass. A figure-eight is not a shape
+ * anybody follows over four seconds of soft light on a dot grid.
+ *
+ * `pulse` is a ring leaving the centre, and has expanded past the last dot
+ * before it restarts, so it fades out rather than snapping back. `scan` crosses
+ * as a band, which is the same maths with the light infinitely tall.
  */
 function lightAt(
   animation: DotFieldAnimation,
@@ -157,7 +175,7 @@ function lightAt(
 
   return {
     x: width / 2 + Math.sin(turn) * width * 0.26,
-    y: height / 2 + Math.cos(turn * 1.37) * height * 0.22,
+    y: height / 2 + Math.cos(turn * 2) * height * 0.22,
     radius: short * 0.42,
     ring: 0,
   };
@@ -169,19 +187,25 @@ function lightAt(
  * Only the dots the light actually reaches are in it — the rest are already
  * drawn by the resting grid underneath, so this is a fraction of the field
  * rather than all of it.
+ *
+ * `points` is the same grid {@link anchors} would build, passed in by a caller
+ * that is about to ask for every frame of a loop. Building it here instead cost
+ * a fresh array of several hundred pairs per frame, to arrive at the identical
+ * grid twenty-four times over.
  */
 export function litPath(
   width: number,
   height: number,
   phase: number,
-  animation: DotFieldAnimation = 'drift'
+  animation: DotFieldAnimation = 'drift',
+  points?: [number, number][]
 ): string {
   if (width <= 0 || height <= 0) return '';
 
   const light = lightAt(animation, phase, width, height);
   let path = '';
 
-  for (const [x, y] of anchors(width, height)) {
+  for (const [x, y] of points ?? anchors(width, height)) {
     const deltaX = x - light.x;
     const deltaY = Number.isNaN(light.y) ? 0 : y - light.y;
     const distance = Math.abs(
@@ -206,8 +230,9 @@ export function litFrames(
   height: number,
   animation: DotFieldAnimation = 'drift'
 ): string[] {
+  const points = width > 0 && height > 0 ? anchors(width, height) : [];
   return Array.from({ length: FRAMES }, (_unused, index) =>
-    litPath(width, height, index / FRAMES, animation)
+    litPath(width, height, index / FRAMES, animation, points)
   );
 }
 
@@ -224,3 +249,34 @@ export function frameAt(time: number, animation: DotFieldAnimation): number {
   const phase = (time % PERIOD[animation]) / PERIOD[animation];
   return Math.min(FRAMES - 1, Math.floor(phase * FRAMES));
 }
+
+/**
+ * Where a moment falls in the loop, as a frame index with its fraction kept.
+ *
+ * {@link frameAt} rounds this down, and rounding it down is what made the field
+ * a flipbook: twenty-four pictures spread over the period, which on the slowest
+ * animation is a new one every 175ms however fast the screen refreshes. The
+ * fraction is what the two layers cross-fade on, so the light moves at the rate
+ * the display can draw rather than the rate the frames were built at.
+ */
+export function framePhase(time: number, animation: DotFieldAnimation): number {
+  'worklet';
+  return ((time % PERIOD[animation]) / PERIOD[animation]) * FRAMES;
+}
+
+/**
+ * What the outgoing and incoming layers are worth, a fraction `t` of the way
+ * from one frame to the next.
+ *
+ * Not `[1 - t, t]`. The layers are drawn over one another, so a dot lit in both
+ * of them composites to `1 - (1-a)(1-b)`, and two half-strength copies of it
+ * come to 0.70 rather than 0.90 — the field dips a fifth in the middle of every
+ * step, which six steps a second turns into a flicker. So only the outgoing
+ * layer ramps, and the incoming one is solved for: whatever leaves the pair at
+ * {@link LIT_OPACITY} the whole way across.
+ */
+export function crossfadeAlphas(t: number): [number, number] {
+  'worklet';
+  const out = LIT_OPACITY * (1 - t);
+  return [out, 1 - (1 - LIT_OPACITY) / (1 - out)];
+}