Skip to content

Open source CapCut alternative.

TypeScript
43.9 KB
Raw Blame
/**
 * Overlay animation: preset In / Out / Loop slots evaluated by one pure
 * function. The DOM preview applies the result as a per-frame CSS transform;
 * the export samples the same function into rasterized frames — a single
 * evaluator is what keeps the two in lockstep.
 *
 * None of the motion lives here. Every entrance, exit, loop and hold move is
 * keyframe data under motion/, written in the After Effects
 * text-animator shape (keyframed properties plus a range selector) that
 * Lottie serializes. This module is the adapter: it names the slots, holds
 * the ids saved in project docs, and folds the evaluator's per-unit poses
 * into the shapes the renderers already draw.
 */

import {
  edgePreset,
  EDGE_IDS,
  hitPreset,
  HIT_IDS,
  holdPreset,
  loopPreset,
  LOOP_IDS,
  MOTION,
  PER_UNIT_EDGE_IDS,
  PER_UNIT_LOOP_IDS,
} from "./motion/catalog";
import { evalPreset, evalWhole, presetExtent, sampleProperties } from "./motion/evaluate";
import type { OverlayFontCycle } from "./fontCycle";
import type { MotionPose, MotionPreset } from "./motion/types";
import type { OverlayWords } from "./words";
import { splitScale } from "./stretch";
import { capStreak, ELEMENT_BLUR_MAX } from "./camera";
import { EASE_BEZIER, easeAt, type EaseId } from "./ease";
import { SLOT_PITCH, type ReelDirection, type ReelShape } from "./dive";

export type OverlayAnimStyle =
  | "fade"
  | "pop"
  | "zoom"
  | "slideleft"
  | "slideright"
  | "slideup"
  | "slidedown"
  | "typewriter" // text only; other kinds render it as a fade
  | "count" // text only, like typewriter
  | "wipe"
  | "dive"
  | "disintegrate"
  // Per-glyph styles: on text each character runs the ramp on its own delay
  // (the preset carries a range selector); on every other kind the whole
  // element runs it once.
  | "rise"
  | "drop"
  | "grow"
  | "flip"
  | "swivel"
  | "bounce"
  | "wave"
  | "converge"
  | "streak"
  | "tumble"
  | "scatter"
  | "slot"
  | "blur"
  | "glitch"
  | "flicker";

export type OverlayLoopStyle =
  | "pulse"
  | "heartbeat"
  | "float"
  | "sway"
  | "spin"
  | "wiggle"
  | "shake"
  | "flicker"
  // Per-glyph loops: on text each character runs the cycle on its own delay;
  // on every other kind the whole element runs it as one piece.
  | "wave"
  | "bounce"
  | "flip"
  | "flutter";

/** The loops that move each character on its own delay. */
export type GlyphLoopStyle = "wave" | "bounce" | "flip" | "flutter";

/** The styles that move each character on its own delay. Text plays them
 * glyph by glyph; anything else plays the same motion as one piece. */
export type GlyphAnimStyle =
  | "rise"
  | "drop"
  | "grow"
  | "flip"
  | "swivel"
  | "bounce"
  | "wave"
  | "converge"
  | "streak"
  | "tumble"
  | "scatter"
  | "slot"
  | "blur"
  | "glitch"
  | "flicker";

/**
 * A ramp at one end of the element.
 *
 * `preset` is a composed animation the project carries itself, in the same
 * shape as a catalog entry — the evaluator cannot tell the two apart, so
 * anything a composer writes plays everywhere a catalog preset does. When it
 * is set it is what plays, and `style` stays the nearest catalog name so
 * menus, tools and prompts still have something to call it.
 */
export interface OverlayEdge {
  style: OverlayAnimStyle;
  seconds: number;
  preset?: MotionPreset;
  /** The typing bar, on an entrance that types (typewriter). Every other
   * entrance ignores it. */
  caret?: OverlayCaret;
  /** A per-letter style's hand-off, 0..1: the share of the ramp spent
   * passing the motion from the first letter to the last (0 = every letter
   * together, near 1 = one at a time). Absent = the style's own. */
  stagger?: number;
  /** The order a per-letter style deals the letters their turns: "shuffle"
   * plays them in a fixed scattered order (After Effects' Randomize Order);
   * a list names the characters by index (the glyph count: spaces and line
   * breaks included) in the order they go, an order read off a reference.
   * Absent = the style's own, reading order for most. */
  order?: EdgeOrder | number[];
  /** With an order named as a list: when each of its characters starts, as a
   * share of the hand-off (0 the first, 1 the last), for letters read off a
   * reference that do not go evenly spaced. Absent = evenly spaced. */
  orderAt?: number[];
  /** How far the style travels from rest at its far end, design px (1080
   * short side): a drop from high above the frame, a long slide. Absent =
   * the style's own reach. */
  distance?: number;
  /** The curve the move travels on, over the style's own: a letter falling
   * at a steady pace is linear, one that brakes into place an ease out. */
  ease?: EaseId;
  /** false: no fade — the element (each letter) stays solid the whole way
   * in or out, as a letter falling in from beyond the frame does. A share of
   * the move, 0..1: it fades up over that much of its move and holds solid
   * after. Absent or true = the style's own. */
  fade?: boolean | number;
  /** Defocus at the far end, design px: each letter (the element) comes in
   * that soft and sharpens as it lands, on the move's own curve — a letter
   * falling out of focus. 0 takes a soft style's own blur away. Absent = the
   * style's own. */
  blur?: number;
  /** Slot only: which way the reel turns (up brings each character in from
   * below, down from above). Absent = up. */
  reel?: ReelDirection;
  /** Slot only: how far apart the reel's characters sit, em of the type
   * size. Absent = the style's own, tighter than a line. */
  pitch?: number;
  /** Slot only: how far the band the reel shows through reaches either side
   * of the line's middle, em. Absent = the line itself. */
  band?: number;
  /** Slot only: how far, em, the reel runs past each character's slot before
   * it settles back into it — a reel that lands with a bounce. */
  overshoot?: number;
  /** Slot only, with an overshoot: the share of each character's move spent
   * settling back from the far side, 0..0.6. Absent = 0.3. */
  settle?: number;
  /** Dive only: the point the view zooms about, design px (1080 short side)
   * from the element's center at rest. It holds where it stands, as a zoom
   * about a fixed point does, instead of the deepest ink flying to the
   * frame's center. Absent = the deepest ink of the last letter. */
  anchor?: { x: number; y: number };
}

export type EdgeOrder = "reading" | "shuffle";
export const EDGE_ORDERS: readonly EdgeOrder[] = ["reading", "shuffle"];
/** The farthest an edge's distance may send it, design px: past any frame. */
export const EDGE_DISTANCE_MAX = 4000;
/** The softest an edge's far end may be, design px: an element's own blur cap. */
export const EDGE_BLUR_MAX = ELEMENT_BLUR_MAX;
/** Seeds the shuffled order, so the same title always scatters the same way. */
const EDGE_SHUFFLE_SEED = 5;

/**
 * The bar at the end of the typed text. It holds solid while the entrance
 * types, then blinks for the rest of the element's life, or for `blinks`
 * blinks and then stays lit (or goes, with `hide`). With `blink` off it
 * holds solid after typing, or goes with `hide`.
 */
export interface OverlayCaret {
  blink: boolean;
  /** How many times it blinks once typing stops; absent = for as long as
   * the element is up. */
  blinks?: number;
  /** Gone after its last blink (or right after typing, with blink off). */
  hide?: boolean;
  /** Hex; absent = the text's own color. */
  color?: string;
}

/** Half a blink: the bar is lit this long, then dark this long — the rate a
 * desktop text field blinks at. */
export const CARET_BLINK_SECONDS = 0.53;
/** Bar geometry in em of the type size: its width, its height, and the gap
 * between the last character and the bar. Both painters read these. */
export const CARET_WIDTH_EM = 0.07;
export const CARET_HEIGHT_EM = 1;
export const CARET_GAP_EM = 0.04;
/** The most blinks the panel and the tools offer. */
export const CARET_BLINKS_MAX = 20;

/**
 * A one-shot hit: a catalog motion played once, over `seconds`, starting `at`
 * seconds into the element (a button press). Unlike the edges it sits inside
 * the element's life, and unlike a loop it plays exactly once. `darken` lets
 * the preset's brightness track through; off, the hit only moves.
 */
export interface OverlayHit {
  style: string;
  at: number;
  seconds: number;
  darken?: boolean;
}

/** The cycle an element runs for its whole duration; `speed` multiplies the
 * base rate (1 = default, 2 = twice as fast). Carries its own preset on the
 * same terms as an edge. */
export interface OverlayLoop {
  style: OverlayLoopStyle;
  speed: number;
  preset?: MotionPreset;
}

/** What the element does while it holds — the push that never stops, the
 * drift across the frame. A hold-catalog id evaluated across the element's
 * whole span; `strength` scales every offset from rest and leaves the timing
 * alone. The keyframe pose track stays the user's own tier: a move never
 * writes keys. */
export interface OverlayMove {
  style: string;
  strength: number;
}

export interface OverlayAnim {
  in?: OverlayEdge;
  out?: OverlayEdge;
  loop?: OverlayLoop;
  move?: OverlayMove;
  /** Word-by-word emphasis (see words.ts). Text only: every other kind
   * ignores it, the way typewriter is offered on titles alone. */
  words?: OverlayWords;
  hit?: OverlayHit;
  /** A stretch of typefaces the title cycles through (see fontCycle.ts).
   * Text only, like the word effects. */
  fonts?: OverlayFontCycle;
}

/** The motion a slot plays: the one it carries, or the catalog entry it
 * names. Everything downstream reads the preset, never the id. */
export const edgeMotion = (slot: OverlayEdge | undefined): MotionPreset | undefined => {
  if (!slot) return undefined;
  const base = slot.preset ?? edgePreset(slot.style);
  const plain =
    slot.order === undefined &&
    !(slot.distance! > 0) &&
    !slot.ease &&
    (slot.fade === undefined || slot.fade === true) &&
    slot.blur === undefined &&
    !hasReelShape(slot);
  if (!base || plain) return base;
  let made = shaped.get(slot);
  if (!made) {
    made = shapeEdge(base, slot);
    shaped.set(slot, made);
  }
  return made;
};

/** How far a preset's motion travels from rest, design px: the reach an
 * edge's `distance` replaces. 0 for a style that never moves. */
export function presetReach(preset: MotionPreset): number {
  const reach = (props: MotionPreset["animate"] | undefined) =>
    Math.max(0, ...(props?.position ?? []).map((k) => Math.max(Math.abs(k.v[0]), Math.abs(k.v[1]))));
  return Math.max(reach(preset.animate), reach(preset.animateOut));
}

/** The style's own reach under a slot, before its distance: what the slot
 * plays with no distance set. */
export const edgeOwnReach = (slot: OverlayEdge | undefined): number => {
  const base = slot ? (slot.preset ?? edgePreset(slot.style)) : undefined;
  return base ? presetReach(base) : 0;
};

/** Glyph indices for letters counted the way a person reads them: `letters`
 * numbers the text's characters from 0, skipping spaces and line breaks;
 * the glyph count the renderers walk includes both. Out-of-range numbers
 * drop out. */
export function letterSequence(text: string, letters: number[]): number[] {
  const at: number[] = [];
  let gi = 0;
  for (const line of text.split("\n")) {
    for (const ch of line) {
      if (!/\s/.test(ch)) at.push(gi);
      gi++;
    }
    gi++; // the line break takes a turn too
  }
  const seen = new Set<number>();
  return letters.filter((k) => Number.isInteger(k) && k >= 0 && k < at.length && !seen.has(k) && seen.add(k)).map((k) => at[k]);
}

/** Slots are replaced, never edited, so a shaped preset stays good for as
 * long as its slot lives. */
const shaped = new WeakMap<OverlayEdge, MotionPreset>();

/** The slot's own order and reach written into its preset, so every reader —
 * the glyph evaluator, the crop padding, both renderers — plays them. */
function shapeEdge(base: MotionPreset, slot: OverlayEdge): MotionPreset {
  let preset = base;
  if (Array.isArray(slot.order) && base.selector) {
    const timed = slot.orderAt?.length === slot.order.length ? { sequenceAt: slot.orderAt } : {};
    preset = { ...preset, selector: { ...base.selector, randomize: false, sequence: slot.order, ...timed } };
  } else if (slot.order && base.selector) {
    const randomize = slot.order === "shuffle";
    preset = {
      ...preset,
      selector: { ...base.selector, randomize, ...(randomize ? { seed: base.selector.seed ?? EDGE_SHUFFLE_SEED } : {}) },
    };
  }
  const own = presetReach(base);
  if (slot.distance! > 0 && own > 0) {
    const k = Math.min(EDGE_DISTANCE_MAX, slot.distance!) / own;
    const scaled = (props: MotionPreset["animate"]): MotionPreset["animate"] =>
      props.position
        ? { ...props, position: props.position.map((key) => ({ ...key, v: [key.v[0] * k, key.v[1] * k] as [number, number] })) }
        : props;
    preset = {
      ...preset,
      animate: scaled(preset.animate),
      ...(preset.animateOut ? { animateOut: scaled(preset.animateOut) } : {}),
    };
  }
  if (slot.ease || slot.fade === false || typeof slot.fade === "number" || slot.blur !== undefined) {
    const curve = slot.ease ? EASE_BEZIER[slot.ease] : undefined;
    const soft = slot.blur === undefined ? undefined : Math.min(EDGE_BLUR_MAX, Math.max(0, slot.blur));
    const reshaped = (props: MotionPreset["animate"]): MotionPreset["animate"] => {
      const next = { ...props };
      if (curve && next.position)
        next.position = next.position.map((key, k, all) => (k < all.length - 1 ? { ...key, ease: curve } : key));
      if (slot.fade === false) delete next.opacity;
      // A fade over the first share of the move, solid after.
      else if (typeof slot.fade === "number" && next.opacity)
        next.opacity = [
          { t: 0, v: 0, ease: EASE_BEZIER.linear },
          { t: Math.min(1, Math.max(0.01, slot.fade)), v: 1 },
          { t: 1, v: 1 },
        ];
      // The defocus clears on the move's own curve, so it is sharp as it lands.
      if (soft === 0) delete next.blur;
      else if (soft !== undefined)
        next.blur = [{ t: 0, v: soft, ease: curve ?? next.position?.[0]?.ease ?? EASE_BEZIER.linear }, { t: 1, v: 0 }];
      return next;
    };
    preset = {
      ...preset,
      animate: reshaped(preset.animate),
      ...(preset.animateOut ? { animateOut: reshaped(preset.animateOut) } : {}),
    };
  }
  if (preset.animate.roll && (slot.ease || hasReelShape(slot) || slot.fade === false)) {
    preset = reelEdge(preset, slot);
  }
  return preset;
}

/** The share of a character's move an overshoot spends settling back, when
 * the edge names none, and the most it may take. */
const SETTLE_DEFAULT = 0.3;
export const EDGE_SETTLE_MAX = 0.6;
/** The widest a slot reel's pitch, band or overshoot may be set, em. */
export const EDGE_REEL_EM_MAX = 4;
/** The style's own pitch in em, at the editor's default line height (render.ts
 * LINE_HEIGHT): what an overshoot is counted in characters against when the
 * edge names no pitch. */
const SLOT_PITCH_EM = SLOT_PITCH * 1.25;

/** Whether an edge sets any part of a slot's reel. */
const hasReelShape = (slot: OverlayEdge): boolean =>
  slot.reel !== undefined ||
  slot.pitch !== undefined ||
  slot.band !== undefined ||
  slot.overshoot !== undefined ||
  slot.settle !== undefined;

/** A slot edge's reel written into its preset: the roll on the edge's curve,
 * run past the slot and settled back when it overshoots, and the reel's shape
 * for the renderers to draw it by. */
function reelEdge(preset: MotionPreset, slot: OverlayEdge): MotionPreset {
  const keys = preset.animate.roll!;
  const from = keys[0].v;
  const curve = slot.ease ? EASE_BEZIER[slot.ease] : keys[0].ease;
  let roll = keys.map((key, k) => (k < keys.length - 1 && curve ? { ...key, ease: curve } : key));
  // An overshoot: the reel comes to rest past the slot, then glides back.
  const past = slot.overshoot! > 0 ? slot.overshoot! / (slot.pitch! > 0 ? slot.pitch! : SLOT_PITCH_EM) : 0;
  if (past > 0) {
    const settle = Math.min(EDGE_SETTLE_MAX, Math.max(0.05, slot.settle ?? SETTLE_DEFAULT));
    roll = [
      { t: 0, v: from, ...(curve ? { ease: curve } : {}) },
      { t: 1 - settle, v: -past, ease: EASE_BEZIER["sine.inOut"] },
      { t: 1, v: 0 },
    ];
  }
  const shape: ReelShape = {
    ...(slot.reel ? { dir: slot.reel } : {}),
    ...(slot.pitch! > 0 ? { pitch: slot.pitch } : {}),
    ...(slot.band! > 0 ? { band: slot.band } : {}),
    ...(slot.fade === false ? { solid: true } : {}),
  };
  // A solid reel is still out of sight before its turn: it shows whole the
  // moment it starts to roll, not standing still while it waits.
  const opacity = slot.fade === false ? [{ t: 0, v: 0, ease: EASE_BEZIER.linear }, { t: 0.001, v: 1 }, { t: 1, v: 1 }] : preset.animate.opacity;
  return {
    ...preset,
    animate: { ...preset.animate, roll, ...(opacity ? { opacity } : {}) },
    ...(Object.keys(shape).length ? { reel: shape } : {}),
  };
}

export const loopMotion = (slot: OverlayLoop | undefined): MotionPreset | undefined =>
  slot ? (slot.preset ?? loopPreset(slot.style)) : undefined;

export const moveMotion = (slot: OverlayMove | undefined): MotionPreset | undefined =>
  slot ? holdPreset(slot.style) : undefined;

const hitMotion = (slot: OverlayHit | undefined): MotionPreset | undefined =>
  slot ? hitPreset(slot.style) : undefined;

// ── the registries, read from the catalog ─────────────────────────────────
// A preset added to the motion catalog appears in every menu, tool enum and prompt
// without being named anywhere else. The unions above stay hand-written:
// they are the ids saved in project docs, and a test holds them to the data.

export const OVERLAY_ANIM_STYLE_IDS = EDGE_IDS as OverlayAnimStyle[];
export const OVERLAY_LOOP_STYLE_IDS = LOOP_IDS as OverlayLoopStyle[];
export const GLYPH_ANIM_STYLE_IDS = PER_UNIT_EDGE_IDS as GlyphAnimStyle[];
export const GLYPH_LOOP_STYLE_IDS = PER_UNIT_LOOP_IDS as GlyphLoopStyle[];
export const OVERLAY_HIT_STYLE_IDS = HIT_IDS;
export const OVERLAY_HIT_STYLE_LABELS: Record<string, string> = Object.fromEntries(
  HIT_IDS.map((id) => [id, MOTION.hits[id].label])
);
/** Each hit as "id: note", what tool schemas and prompts teach them from. */
export const hitNotes = (): string =>
  HIT_IDS.map((id) => `${id}: ${MOTION.hits[id].note ?? MOTION.hits[id].label}`).join(" ");

/** Hit length bounds, seconds. */
export const OVERLAY_HIT_MIN_SECONDS = 0.1;
export const OVERLAY_HIT_MAX_SECONDS = 1;
export const OVERLAY_HIT_DEFAULT_SECONDS = 0.3;

/** The edges that only play on characters — typing them out, rolling each up
 * a reel, counting the numbers up. Every other kind is offered the rest. */
export const TEXT_ONLY_ANIM_STYLE_IDS = EDGE_IDS.filter(
  (id) =>
    !!MOTION.edges[id].animate.typed ||
    !!MOTION.edges[id].animate.roll ||
    !!MOTION.edges[id].animate.counted
) as OverlayAnimStyle[];
/** The edges that fly the view into the element's ink until it fills the
 * frame. */
export const DIVE_ANIM_STYLE_IDS = EDGE_IDS.filter((id) => !!MOTION.edges[id].animate.dive) as OverlayAnimStyle[];

/** Each catalog edge that carries a note, as "id: note" lines — what tool
 * schemas and prompts teach the edges from. */
export const edgeNotes = (): string =>
  EDGE_IDS.filter((id) => MOTION.edges[id].note)
    .map((id) => `${id}: ${MOTION.edges[id].note}`)
    .join(" ");

const GLYPH_STYLES: Set<string> = new Set(GLYPH_ANIM_STYLE_IDS);
const GLYPH_LOOPS: Set<string> = new Set(GLYPH_LOOP_STYLE_IDS);

export function isGlyphAnimStyle(style: OverlayAnimStyle): style is GlyphAnimStyle {
  return GLYPH_STYLES.has(style);
}

export function isGlyphLoopStyle(style: OverlayLoopStyle): style is GlyphLoopStyle {
  return GLYPH_LOOPS.has(style);
}

export const OVERLAY_ANIM_STYLE_LABELS = Object.fromEntries(
  EDGE_IDS.map((id) => [id, MOTION.edges[id].label])
) as Record<OverlayAnimStyle, string>;

export const OVERLAY_LOOP_STYLE_LABELS = Object.fromEntries(
  LOOP_IDS.map((id) => [id, MOTION.loops[id].label])
) as Record<OverlayLoopStyle, string>;

/** Base loop periods in seconds at speed 1. */
export const LOOP_PERIODS = Object.fromEntries(
  LOOP_IDS.map((id) => [id, MOTION.loops[id].period ?? 1])
) as Record<OverlayLoopStyle, number>;

/** Ramp length bounds, seconds (mirrors clip animations). */
export const OVERLAY_ANIM_MIN_SECONDS = 0.1;
export const OVERLAY_ANIM_MAX_SECONDS = 2;
export const OVERLAY_ANIM_DEFAULT_SECONDS = 0.5;
/** A per-letter ramp hands its motion along a whole line, so it may run
 * longer: a long title landing a letter at a time takes a few seconds. */
export const OVERLAY_GLYPH_ANIM_MAX_SECONDS = 4;

/** The longest ramp a style may run: its own cap, else the per-letter one,
 * else the shared one. */
export const edgeMaxSeconds = (style: string | undefined): number => {
  const preset = style ? edgePreset(style) : undefined;
  return preset?.maxSeconds ?? (preset?.selector ? OVERLAY_GLYPH_ANIM_MAX_SECONDS : OVERLAY_ANIM_MAX_SECONDS);
};

/** The most of a ramp the letter hand-off may take: at 1 each letter would
 * get no time of its own to move. */
export const EDGE_STAGGER_MAX = 0.95;

/** The hand-off a per-letter edge plays with — its own, else its style's;
 * undefined for a style that moves the element as one piece. */
export const edgeStagger = (slot: OverlayEdge | undefined): number | undefined => {
  const sel = edgeMotion(slot)?.selector;
  if (!sel) {
    return undefined;
  }
  return slot?.stagger ?? sel.spread;
};

/**
 * Whether a style changes the element's pixels rather than moving them as one
 * picture. A cached bitmap under a transform can't express these, so both
 * renderers bake them frame by frame.
 */
export function bakesPixels(slot: OverlayEdge | undefined, isText: boolean): boolean {
  const preset = edgeMotion(slot);
  if (!preset) return false;
  if (preset.animate.reveal) return true; // a wipe clips whatever it is over
  if (preset.animate.erode) return true; // and a disintegration eats it
  if (!isText) return false;
  // A typewriter types characters, a count rewrites its numbers; a selector
  // moves them one at a time.
  return !!preset.animate.typed || !!preset.animate.counted || !!preset.selector;
}

/**
 * How far a loop strays from rest, in design px, and whether it turns. The
 * frame sampler crops an element to the box it lives in, so a loop that
 * travels has to say so or the sampler clips the motion off.
 */
export function loopExtent(slot: OverlayLoop | undefined): {
  travel: number;
  rotates: boolean;
} {
  const preset = loopMotion(slot);
  return preset ? presetExtent(preset) : { travel: 0, rotates: false };
}

/** How far a move strays from rest at its strength — travel in design px,
 * whether it turns, and the largest scale it reaches. The frame sampler pads
 * its crop by all three. */
export function moveExtent(slot: OverlayMove | undefined): {
  travel: number;
  rotates: boolean;
  scale: number;
} {
  const preset = moveMotion(slot);
  if (!preset || !slot) return { travel: 0, rotates: false, scale: 1 };
  const k = slot.strength > 0 ? slot.strength : 1;
  const base = presetExtent(preset);
  let s = 1;
  for (const key of preset.animate.scale ?? []) s = Math.max(s, key.v[0], key.v[1]);
  return { travel: base.travel * k, rotates: base.rotates, scale: 1 + (s - 1) * k };
}

/** Where a per-glyph ramp stands. Renderers walk the element's characters and
 * ask `glyphAnimAt` where each one sits. */
export interface GlyphPhase {
  style: OverlayAnimStyle;
  /** The slot's own preset, carried through so a composed animation reaches
   * the characters the same way a catalog one does. */
  preset?: MotionPreset;
  /** 0 at the far end of the ramp, 1 at rest. */
  p: number;
  exiting: boolean;
  /** The slot's own hand-off, over the style's (see `OverlayEdge.stagger`). */
  stagger?: number;
  /** The ramp's length, seconds. */
  seconds?: number;
  /** The share of the ramp the shutter stays open, when the element wears
   * motion blur: each letter then streaks along its own move. */
  exposure?: number;
  /** The element's shutter, frames (caps the streak's length). */
  shutter?: number;
}

/** Where a per-glyph loop stands: one number, 0 to 1 around the cycle. Each
 * character reads it at its own delay. */
export interface GlyphLoopPhase {
  style: GlyphLoopStyle;
  preset?: MotionPreset;
  phase: number;
}

/** The transform an animation contributes at one moment. dx/dy are design px
 * (1080 short side); rotate is degrees; alpha multiplies the element opacity;
 * textProgress (0..1, typewriter only) is the share of characters shown;
 * countProgress (0..1, count only) is the share of its value each number shows;
 * reveal (0..1, wipe) is the share of the box uncovered from its left edge;
 * glyphs and glyphLoop replace the whole-element transform with a
 * per-character one, and both apply at once (a title can fly its letters in
 * and then keep them waving). */
export interface OverlayAnimState {
  dx: number;
  dy: number;
  /** The larger axis; `sx`/`sy` stretch each axis over it (see stretch.ts),
   * so a whole-element flip turns one axis through zero. */
  scale: number;
  sx?: number;
  sy?: number;
  rotate: number;
  alpha: number;
  textProgress?: number;
  countProgress?: number;
  reveal?: number;
  /** 0..1 share of the ink eaten away (disintegrate). */
  erode?: number;
  /** 0..1 strength of the electric arcs over the element (zap hit). */
  zap?: number;
  glyphs?: GlyphPhase;
  glyphLoop?: GlyphLoopPhase;
  /** How far the view has flown into the element's deepest ink, 0..1 (dive).
   * Renderers turn it into a view with `diveView`, which needs the drawn
   * geometry this evaluator never sees. */
  dive?: number;
  /** The diving edge, when it zooms about its own anchor. */
  diveEdge?: "in" | "out";
  /** Whether the typing bar is lit (typewriter with a caret); absent when the
   * element has none. */
  caret?: boolean;
  /** Multiplies the element's colors (a hit that darkens); absent = 1. */
  brightness?: number;
  /** Defocus the ramp adds over the element's own, design px (blur). */
  blur?: number;
}

/** How one character sits at a moment: offsets in design px, a scale per axis
 * (a flip runs its axis through zero), degrees, and its own opacity. */
export interface GlyphAnimState {
  dx: number;
  dy: number;
  sx: number;
  sy: number;
  rotate: number;
  alpha: number;
  /** Characters its reel still rolls past before it lands (slot); absent or
   * 0 = the character alone. `slotReel` says what to draw. */
  roll?: number;
  /** The reel's shape while it rolls, when its edge sets one. */
  reel?: ReelShape;
  /** Defocus, design px; absent = sharp. */
  blur?: number;
  /** How far a red and a cyan copy pull apart either side, design px; absent
   * = one copy. */
  split?: number;
  /** The motion blur streak: how far the letter travels while the shutter
   * is open, design px, centered on this moment. Absent = sharp. */
  streak?: { x: number; y: number };
}

const IDLE: OverlayAnimState = { dx: 0, dy: 0, scale: 1, rotate: 0, alpha: 1 };
const GLYPH_IDLE: GlyphAnimState = { dx: 0, dy: 0, sx: 1, sy: 1, rotate: 0, alpha: 1 };

const wrap01 = (v: number) => v - Math.floor(v);

/** A unit's share of the line's spread: -1 at the head, +1 at the tail. This
 * is what turns the tracking property into a per-character offset. */
const trackShare = (index: number, count: number) =>
  count > 1 ? (index / (count - 1)) * 2 - 1 : 0;

/** An evaluator pose as the per-glyph state the renderers draw. */
function asGlyph(pose: MotionPose, index: number, count: number): GlyphAnimState {
  return {
    dx: pose.dx + trackShare(index, count) * pose.tracking,
    dy: pose.dy,
    sx: pose.sx,
    sy: pose.sy,
    rotate: pose.rotate,
    alpha: pose.alpha,
    ...(pose.roll ? { roll: pose.roll } : {}),
    ...(pose.blur ? { blur: pose.blur } : {}),
    ...(pose.split ? { split: pose.split } : {}),
  };
}

/**
 * Where character `index` of `count` sits when its element's ramp stands at
 * `p`. Glyphs start in order and overlap, so the motion sweeps the line; an
 * exit sweeps out the way it came in.
 */
export function glyphAnimAt(phase: GlyphPhase, index: number, count: number): GlyphAnimState {
  const { p, exiting } = phase;
  const preset = phase.preset ?? edgePreset(phase.style);
  // Only a preset with a selector has anything to say per character; a
  // whole-element style leaves its glyphs where they are.
  if (!preset?.selector) return GLYPH_IDLE;
  const n = Math.max(1, count);
  const at = (q: number) => asGlyph(evalPreset(preset, q, index, n, exiting, 0, phase.stagger), index, n);
  const rolled = at(p);
  const g = rolled.roll && preset.reel ? { ...rolled, reel: preset.reel } : rolled;
  const e = phase.exposure ?? 0;
  if (!(e > 0)) return g;
  // The letter's travel over the part of the exposure inside the ramp,
  // scaled to the whole exposure, the way an element's own streak is.
  const p0 = Math.max(0, p - e / 2);
  const p1 = Math.min(1, p + e / 2);
  if (p1 - p0 < 1e-6) return g;
  const a = at(p0);
  const b = at(p1);
  const k = e / (p1 - p0);
  const streak = capStreak((b.dx - a.dx) * k, (b.dy - a.dy) * k, phase.shutter ?? 1);
  return streak ? { ...g, streak } : g;
}

/** Where character `index` of `count` sits with everything applied — the edge
 * ramp it is playing and the loop it is running, folded into one transform.
 * Every renderer that draws a title letter by letter calls this. */
export function glyphStateAt(
  state: { glyphs?: GlyphPhase; glyphLoop?: GlyphLoopPhase },
  index: number,
  count: number
): GlyphAnimState {
  const ramp = state.glyphs ? glyphAnimAt(state.glyphs, index, count) : GLYPH_IDLE;
  if (!state.glyphLoop) return ramp;
  const preset = state.glyphLoop.preset ?? loopPreset(state.glyphLoop.style);
  if (!preset) return ramp;
  const n = Math.max(1, count);
  const loop = asGlyph(evalPreset(preset, state.glyphLoop.phase, index, n, false), index, n);
  const roll = (ramp.roll ?? 0) + (loop.roll ?? 0);
  const blur = (ramp.blur ?? 0) + (loop.blur ?? 0);
  const split = (ramp.split ?? 0) + (loop.split ?? 0);
  return {
    dx: ramp.dx + loop.dx,
    dy: ramp.dy + loop.dy,
    sx: ramp.sx * loop.sx,
    sy: ramp.sy * loop.sy,
    rotate: ramp.rotate + loop.rotate,
    alpha: ramp.alpha * loop.alpha,
    ...(roll ? { roll } : {}),
    ...(roll && ramp.reel ? { reel: ramp.reel } : {}),
    ...(blur ? { blur } : {}),
    ...(split ? { split } : {}),
    ...(ramp.streak ? { streak: ramp.streak } : {}),
  };
}

/** Whether this moment draws the element letter by letter. */
export function hasGlyphMotion(state: {
  glyphs?: GlyphPhase;
  glyphLoop?: GlyphLoopPhase;
}): boolean {
  return !!state.glyphs || !!state.glyphLoop;
}

/** One edge ramp. `p` runs 0→1 over the window in play direction for "in";
 * for "out" the caller feeds remaining-share so the motion mirrors. Text hands
 * the per-glyph styles to the renderer as a phase; every other kind plays the
 * same motion as one piece. */
function edgeState(
  slot: OverlayEdge,
  p: number,
  exiting: boolean,
  isText: boolean,
  seconds: number
): OverlayAnimState {
  const preset = edgeMotion(slot);
  if (!preset) return { ...IDLE };
  const clamped = Math.min(1, Math.max(0, p));
  if (preset.selector && isText)
    return {
      ...IDLE,
      glyphs: {
        style: slot.style,
        preset,
        p: clamped,
        exiting,
        seconds,
        ...(slot.stagger !== undefined ? { stagger: slot.stagger } : {}),
      },
    };
  // Anything with no characters to hand the motion to plays it once over the
  // whole box.
  const pose = evalWhole(preset, clamped, exiting);
  const state: OverlayAnimState = {
    dx: pose.dx,
    dy: pose.dy,
    ...splitScale(pose.sx, pose.sy),
    rotate: pose.rotate,
    alpha: pose.alpha,
  };
  // A typewriter on anything but text has no characters to reveal, so the
  // element just holds — the same as it always did.
  if (pose.typed !== undefined) state.textProgress = pose.typed;
  if (pose.counted !== undefined) state.countProgress = pose.counted;
  if (pose.reveal !== undefined) state.reveal = pose.reveal;
  if (pose.erode !== undefined) state.erode = pose.erode;
  if (pose.dive !== undefined) state.dive = pose.dive;
  // A dive's ease is the flight's own curve on the edge's own clock: an
  // ease-in on an exit holds back early and rushes into the ink at the end.
  if (pose.dive !== undefined && slot.ease) state.dive = exiting ? easeAt(slot.ease, 1 - clamped) : 1 - easeAt(slot.ease, clamped);
  if (pose.dive !== undefined && slot.anchor) state.diveEdge = exiting ? "out" : "in";
  if (pose.blur) state.blur = pose.blur;
  return state;
}

/** The loop's contribution at `phase`, written onto the state the edge ramps
 * left. A per-glyph loop hands the characters their own cycle; on any other
 * kind it folds back into the one transform the element has. */
function applyLoop(
  state: OverlayAnimState,
  slot: OverlayLoop,
  phase: number,
  isText: boolean
): void {
  const preset = loopMotion(slot);
  if (!preset) return;
  if (preset.selector && isText) {
    state.glyphLoop = { style: slot.style as GlyphLoopStyle, preset: slot.preset, phase };
    return;
  }
  const pose = evalPreset(preset, phase, 0, 1, false);
  state.dx += pose.dx;
  state.dy += pose.dy;
  state.rotate += pose.rotate;
  foldAxes(state, pose.sx, pose.sy);
  state.alpha *= pose.alpha;
}

/**
 * Evaluate an element's animation at `tLocal` seconds into its [0, dur]
 * window. Pure and deterministic — the preview, the export frame renderer,
 * and the browser compositor all call this same function.
 */
export function evalOverlayAnim(
  anim: OverlayAnim | undefined,
  tLocal: number,
  dur: number,
  isText = false
): OverlayAnimState {
  if (!anim) return IDLE;
  let state = { ...IDLE };

  const inSecs = anim.in ? Math.min(anim.in.seconds, dur) : 0;
  const outSecs = anim.out ? Math.min(anim.out.seconds, Math.max(0, dur - inSecs)) : 0;

  if (anim.in && tLocal < inSecs) {
    state = edgeState(anim.in, tLocal / inSecs, false, isText, inSecs);
  } else if (anim.out && tLocal > dur - outSecs) {
    state = edgeState(anim.out, (dur - tLocal) / outSecs, true, isText, outSecs);
  }

  if (anim.loop) {
    const period = loopPeriod(anim) ?? 1;
    applyLoop(state, anim.loop, wrap01(tLocal / period), isText);
  }
  if (anim.move) applyMove(state, anim.move, tLocal, dur);
  if (anim.hit) applyHit(state, anim.hit, tLocal);
  if (isText) {
    const caret = caretOn(anim, tLocal, dur);
    if (caret !== undefined) state.caret = caret;
  }
  return state;
}

/** How long the hit plays: a stored hit without seconds plays the default,
 * the length the inspector shows for it. */
const hitSeconds = (slot: OverlayHit): number => (slot.seconds > 0 ? slot.seconds : OVERLAY_HIT_DEFAULT_SECONDS);

/** The hit's contribution at `tLocal`: nothing outside its window; inside,
 * the preset's pose folded onto what the other slots left, as one piece. */
function applyHit(state: OverlayAnimState, slot: OverlayHit, tLocal: number): void {
  const preset = hitMotion(slot);
  const q = (tLocal - slot.at) / hitSeconds(slot);
  if (!preset || !(q > 0 && q < 1)) return;
  const pose = evalWhole(preset, q, false);
  state.dx += pose.dx;
  state.dy += pose.dy;
  state.rotate += pose.rotate;
  foldAxes(state, pose.sx, pose.sy);
  state.alpha *= pose.alpha;
  if (slot.darken && pose.brightness !== undefined && pose.brightness !== 1)
    state.brightness = (state.brightness ?? 1) * pose.brightness;
  if (pose.zap !== undefined) {
    state.zap = pose.zap;
  }
}

/** Where the hit plays inside [0, dur], or null when there is none. The frame
 * samplers draw this window frame by frame. */
export function hitWindow(
  anim: OverlayAnim | undefined,
  dur: number
): { start: number; end: number } | null {
  const slot = anim?.hit;
  if (!slot || !hitMotion(slot)) return null;
  const start = Math.max(0, Math.min(dur, slot.at));
  const end = Math.max(start, Math.min(dur, slot.at + hitSeconds(slot)));
  return end - start > 1e-3 ? { start, end } : null;
}

/** Whether the hit paints arcs (zap): pixels the stamped export bakes frame
 * by frame across the hit's window. */
export const hitZaps = (anim: OverlayAnim | undefined): boolean => !!hitMotion(anim?.hit)?.animate.zap;

/** The largest scale a hit reaches, so the frame sampler can pad its crop. */
export function hitScale(anim: OverlayAnim | undefined): number {
  const preset = hitMotion(anim?.hit);
  let s = 1;
  for (const key of preset?.animate.scale ?? []) s = Math.max(s, key.v[0], key.v[1]);
  return s;
}

/** The typing bar an entrance keeps when it changes to `style`: the bar stays
 * while the new entrance still types. */
export function keepCaret(edge: OverlayEdge | undefined, style: string): OverlayCaret | undefined {
  return edgePreset(style)?.animate.typed ? edge?.caret : undefined;
}

/** The element's typing bar, when its entrance types and carries one. */
export function typeCaret(anim: OverlayAnim | undefined): OverlayCaret | undefined {
  const edge = anim?.in;
  if (!edge?.caret) return undefined;
  return edgeMotion(edge)?.animate.typed ? edge.caret : undefined;
}

/**
 * Whether the typing bar is lit at `tLocal`: solid while the entrance types,
 * then lit and dark by turns, CARET_BLINK_SECONDS each, starting lit.
 * Undefined when the element has no bar. Pure, so every renderer and every
 * sampler reads the same blink.
 */
export function caretOn(
  anim: OverlayAnim | undefined,
  tLocal: number,
  dur: number
): boolean | undefined {
  const caret = typeCaret(anim);
  if (!caret) return undefined;
  const typedBy = Math.min(anim!.in!.seconds, dur);
  if (tLocal < typedBy) return true;
  if (!caret.blink) return !caret.hide;
  const u = tLocal - typedBy;
  const cycle = CARET_BLINK_SECONDS * 2;
  if (caret.blinks !== undefined && caret.blinks > 0 && u >= caret.blinks * cycle) return !caret.hide;
  return u % cycle < CARET_BLINK_SECONDS;
}

/** The moments inside (0, dur) where the bar turns on or off, in order. The
 * frame samplers cut their still windows here, so a blink costs two pictures
 * and never a frame-by-frame run. */
export function caretToggles(anim: OverlayAnim | undefined, dur: number): number[] {
  const caret = typeCaret(anim);
  if (!caret) return [];
  const typedBy = Math.min(anim!.in!.seconds, dur);

  // A bar that holds after typing turns off once, when it hides.
  if (!caret.blink) return caret.hide && typedBy > 0 && typedBy < dur ? [typedBy] : [];

  // A blink flips every CARET_BLINK_SECONDS once typing stops, lit first. A
  // counted blink ends dark, then lights again for good unless it hides:
  // two blinks flip at 1, 2, 3 (hide) or 1, 2, 3, 4 (stay) half-cycles.
  const flips = caret.blinks !== undefined && caret.blinks > 0 ? caret.blinks * 2 - (caret.hide ? 1 : 0) : Infinity;
  const out: number[] = [];
  for (let k = 1; k <= flips; k++) {
    const t = typedBy + k * CARET_BLINK_SECONDS;
    if (t >= dur) break;
    out.push(t);
  }
  return out;
}

/** The move's contribution at `tLocal`: the hold preset sampled across the
 * element's whole [0, dur] span, every offset from rest scaled by strength,
 * folded onto the state the ramps and the loop left. */
function applyMove(state: OverlayAnimState, slot: OverlayMove, tLocal: number, dur: number): void {
  const preset = moveMotion(slot);
  if (!preset || dur <= 0) return;
  const k = slot.strength > 0 ? slot.strength : 1;
  const pose = sampleProperties(preset.animate, tLocal / dur, dur);
  state.dx += pose.dx * k;
  state.dy += pose.dy * k;
  state.rotate += pose.rotate * k;
  foldAxes(state, 1 + (pose.sx - 1) * k, 1 + (pose.sy - 1) * k);
  state.alpha *= 1 + (pose.alpha - 1) * k;
}

/** Multiply a per-axis scale into the state, axis by axis, and split the
 * result back into its uniform scale and stretch. */
function foldAxes(state: OverlayAnimState, ax: number, ay: number): void {
  const next = splitScale(state.scale * (state.sx ?? 1) * ax, state.scale * (state.sy ?? 1) * ay);
  state.scale = next.scale;
  delete state.sx;
  delete state.sy;
  if (next.sx !== undefined) {
    state.sx = next.sx;
    state.sy = next.sy;
  }
}

/** The loop's exact cycle length in seconds (frame sequences render one cycle
 * and repeat it), or null when the element has no loop. */
export function loopPeriod(anim: OverlayAnim | undefined): number | null {
  if (!anim?.loop) return null;
  const speed = anim.loop.speed > 0 ? anim.loop.speed : 1;
  const base = loopMotion(anim.loop)?.period ?? LOOP_PERIODS[anim.loop.style] ?? 1;
  return base / speed;
}

/** Whether any slot is set (an element with an empty anim object is static). */
export function hasOverlayAnim(anim: OverlayAnim | undefined): boolean {
  return (
    !!anim &&
    (!!anim.in || !!anim.out || !!anim.loop || !!anim.move || !!anim.words || !!anim.hit || !!anim.fonts)
  );
}

/**
 * A hold move sampled into an element pose track: absolute poses at seconds
 * from its start. Moves used to ship this way — written onto `kf` — and docs
 * saved then still carry these tracks; the loader regenerates them through
 * here to recognize which move wrote one and lift it into `anim.move`.
 */
export function holdMoveKeys(
  id: string,
  rest: { x: number; y: number; rotation: number },
  dur: number,
  /** Multiplies every offset from rest. 1 is the move as written; below it
   * the same shape reads quieter, above it harder. The timing never changes,
   * so a move stays on the beat whatever it is scaled to. */
  strength = 1,
  frameShortSide = 1080
): { t: number; x: number; y: number; scale: number; rotation: number; opacity: number }[] | undefined {
  const preset = holdPreset(id);
  if (!preset || dur <= 0.15) return undefined;
  const pose = (t: number) => sampleProperties(preset.animate, t, dur);
  const seeds = new Set<number>([0, 1]);
  for (const track of Object.values(preset.animate))
    for (const k of track) seeds.add(k.tMax === undefined ? k.t : Math.min(k.t, k.tMax / dur));
  const times = [...seeds].sort((a, b) => a - b);
  // The preset's own keys are not enough by themselves: a pose track runs
  // straight between its keys, so an eased push would arrive at a constant
  // rate and a circling move would draw a polygon. Each gap is halved until
  // the straight line across it matches the curve, which leaves an even move
  // at its two keys and spends keys only where there is a bend.
  const track: number[] = [times[0]];
  const fill = (a: number, b: number, depth: number): void => {
    if (depth < SUBDIVIDE_MAX && bends(a, b, pose)) {
      const m = (a + b) / 2;
      fill(a, m, depth + 1);
      fill(m, b, depth + 1);
    } else track.push(b);
  };
  for (let i = 0; i < times.length - 1; i++) fill(times[i], times[i + 1], 0);
  const px = 1 / frameShortSide;
  const k = strength;
  const keys = track
    .map((t) => {
      const p = pose(t);
      // Baked axes keep a hold's squash: the key's scale is the larger axis
      // and scaleX/scaleY stretch each one over it.
      const size = splitScale(1 + (p.sx - 1) * k, 1 + (p.sy - 1) * k);
      return {
        t: Math.round(t * dur * 1000) / 1000,
        x: rest.x + p.dx * px * k,
        y: rest.y + p.dy * px * k,
        scale: size.scale,
        ...(size.sx !== undefined ? { scaleX: size.sx, scaleY: size.sy } : {}),
        rotation: rest.rotation + p.rotate * k,
        opacity: 1 + (p.alpha - 1) * k,
      };
    })
    .filter((key, i, all) => i === 0 || key.t > all[i - 1].t + 1e-3);
  return keys.length > 1 ? keys : undefined;
}

/** How many times a gap may be halved before the curve across it is called
 * close enough. */
const SUBDIVIDE_MAX = 4;

/** Whether the motion across a gap leaves the straight line between its ends
 * by enough to see. Three points are checked rather than one, because the
 * ease most of these presets are written with is symmetric: it is exactly on
 * the line at the middle and furthest off it at the quarters. Tolerances are
 * design px of travel, degrees of turn, and shares of scale and opacity. */
function bends(a: number, b: number, pose: (t: number) => MotionPose): boolean {
  const pa = pose(a);
  const pb = pose(b);
  for (const f of [0.25, 0.5, 0.75]) {
    const p = pose(a + (b - a) * f);
    const off = (u: number, w: number, v: number) => Math.abs(u + (w - u) * f - v);
    if (
      off(pa.dx, pb.dx, p.dx) > 1.5 ||
      off(pa.dy, pb.dy, p.dy) > 1.5 ||
      off(pa.rotate, pb.rotate, p.rotate) > 0.5 ||
      off(pa.sx, pb.sx, p.sx) > 0.006 ||
      off(pa.sy, pb.sy, p.sy) > 0.006 ||
      off(pa.alpha, pb.alpha, p.alpha) > 0.015
    )
      return true;
  }
  return false;
}