Cursor Track
Cursor click animation: a mouse pointer that moves and clicks over any UI. A synthetic cursor that walks a path of normalized waypoints over any children and pulses a click ring on arrival.
Source
components/kuchi/cursor-track.tsx
1"use client";23import { type ReactNode, useId } from "react";4import {5 AbsoluteFill,6 Easing,7 getRemotionEnvironment,8 interpolate,9 useCurrentFrame,10 useVideoConfig,11} from "remotion";12import { type KuchiTheme, useKuchiTheme, withAlpha } from "@/lib/kuchi-ui";1314export type CursorVariant = "arrow" | "dot";1516export interface CursorWaypoint {17 /**18 * Frame the cursor starts travelling TOWARDS this point, on this component's19 * own clock (i.e. against `useCurrentFrame() * speed`). Absolute, not20 * relative to the previous waypoint. Waypoints are sorted by `at`; ties break21 * on array order and the last one wins.22 *23 * The FIRST waypoint has nothing to travel from, so it places the cursor24 * rather than moving it — give it an off-frame `x` to have the cursor walk in.25 */26 at: number;27 /**28 * Destination, normalized: 0 -> 1 left to right across the composition,29 * origin top-left. FRAME coordinates — a camera move inside a child30 * `<ScreenRecording>` does not move the cursor. Values outside 0-1 are legal31 * and mean off-frame, so a cursor entering from the left starts at `x: -0.1`.32 */33 x: number;34 /** Destination, normalized: 0 -> 1 top to bottom. */35 y: number;36 /**37 * Frames the travel takes. Default 14. The cursor then RESTS here until the38 * next waypoint's `at` — there is no hold field, the hold is the gap. On the39 * first waypoint there is no travel, so this is the fade-up window instead.40 */41 duration?: number;42 /**43 * Pulse a click ring on ARRIVAL, i.e. at `at + duration`. To click twice44 * without moving, add a second waypoint at the same `x`/`y`.45 */46 click?: boolean;47}4849export interface CursorTrackProps {50 /**51 * What the cursor moves over — anything. Rendered full-bleed underneath it.52 * Put the `<ScreenRecording>` (or the UI sim) in here, not this inside that:53 * the cursor has to be the top layer to read as a cursor.54 */55 children?: ReactNode;56 /**57 * The path, in any order. Defaults to `DEMO_PATH` so the component is worth58 * looking at with no props; pass `[]` and it renders nothing at all, i.e. it59 * becomes a no-op wrapper.60 */61 path?: CursorWaypoint[];62 /** `arrow` (default) is a pointer; `dot` is a touch/tap puck. */63 variant?: CursorVariant;64 /**65 * Cursor height in px. Omit it and the component computes 3.9% of the66 * composition height, so it stays the size a real cursor looks at any crop.67 */68 size?: number;69 /**70 * Cursor fill. Defaults to the theme's `foreground` — so pass `mode="dark"`71 * when the recording underneath is dark, and the cursor and its outline swap72 * together.73 */74 color?: string;75 /**76 * The outline that keeps the cursor readable over arbitrary footage. Defaults77 * to the theme's `background`, the opposite end of `color`.78 */79 outlineColor?: string;80 /** The click ring. Defaults to the theme's `primary`. */81 ringColor?: string;82 /** Frames a click ring lives for. Default 14. */83 clickFrames?: number;84 /**85 * Show the cursor parked at the first waypoint before its `at`. Default86 * false — it fades in as the first move starts, which is what stops a cursor87 * sitting inertly on frame 0.88 */89 showBefore?: boolean;90 /** Design-system token overrides. */91 theme?: Partial<KuchiTheme>;92 mode?: "light" | "dark";93 /** Time multiplier. Every `at` is measured against `useCurrentFrame() * speed`. */94 speed?: number;95 className?: string;96}9798// --- Constants -------------------------------------------------------------99100/**101 * Cursor travel, and deliberately NOT the camera curve. A pointer accelerates102 * and decelerates; a camera decelerate on a cursor reads robotic. Same curve103 * the notch morph and the showcase crane already use.104 */105export const CURSOR_EASE = Easing.inOut(Easing.cubic);106107/** Click ring growth. Opacity fades linearly under it. */108export const RING_EASE = Easing.out(Easing.cubic);109110export const TRAVEL_FRAMES = 14;111export const CLICK_FRAMES = 14;112export const TAIL_FRAMES = 18;113114/** Cursor height as a fraction of the composition height, when `size` is omitted. */115export const CURSOR_HEIGHT_RATIO = 0.039;116117/** Ring radius at birth and at death, as multiples of the cursor height. */118export const RING_START = 0.18;119export const RING_END = 1.1;120121/**122 * The site's own pointer (app/globals.css): a rounded arrow, ink with a rim and123 * a soft shadow, in a 24-unit box with its hotspot — the tip — at (5.5, 5.5).124 * An SVG and not an emoji or a font glyph: a glyph is whatever face the125 * renderer happens to resolve, and it would carry the hinting problems the126 * motion-quality skill is about into the one element that moves every frame.127 */128const ARROW_VIEW = 24;129const ARROW_TIP = 5.5;130/** The arrow's ink spans 14 of the 24 units; `size` is that span. */131const ARROW_INK = 14;132const ARROW_PATH = "M5.5 5.5 19 11l-5.6 1.45a2 2 0 0 0-1.45 1.45L10.5 19.5z";133134/** The `dot` puck's diameter, as a multiple of the cursor height. */135const DOT_RATIO = 0.62;136137/**138 * A short demo path: in from off-frame bottom-left, click, cross the frame,139 * click, then move off to the top-right. Carries the customizer preview and the140 * MCP skeleton, because `ControlType` has no array control to expose `path`141 * through — the same way `terminal-simulator` handles `lines`.142 */143export const DEMO_PATH: CursorWaypoint[] = [144 { at: 0, x: -0.06, y: 0.86, duration: 6 },145 { at: 8, x: 0.34, y: 0.44, duration: 22, click: true },146 { at: 52, x: 0.68, y: 0.62, duration: 20, click: true },147 { at: 96, x: 0.82, y: 0.28, duration: 18 },148];149150// --- Pure helpers (unit-tested) -------------------------------------------151152export interface CursorPose {153 /** Position, normalized to the frame, origin top-left. */154 x: number;155 y: number;156 /** Click-ring progress, 0 -> 1, or 0 when no ring is up. */157 click: number;158 /** 0 before the cursor has appeared, 1 once it has. */159 opacity: number;160}161162const CLAMP = {163 extrapolateLeft: "clamp",164 extrapolateRight: "clamp",165} as const;166167/**168 * Waypoints in the order they actually play. Same-`at` ties: the later array169 * entry wins and the earlier tied entries never display, so they can never act170 * as a leg's origin — the rule `useStateTransition` already uses for `Step`.171 */172function ordered(path: CursorWaypoint[]): CursorWaypoint[] {173 return path174 .map((w, index) => ({ w, index }))175 .sort((a, b) => a.w.at - b.w.at || a.index - b.index)176 .filter((e, i, arr) => i === arr.length - 1 || arr[i + 1].w.at !== e.w.at)177 .map((e) => e.w);178}179180/**181 * The cursor's pose at `frame`, folding the path forward so a waypoint that182 * starts mid-travel takes over from where the cursor actually is. Pure: same183 * frame, same answer, whatever order Remotion renders in.184 *185 * ponytail: straight-line travel. If it reads robotic, add a per-leg arc here,186 * not a prop.187 */188export function cursorPoseAt(189 frame: number,190 path: CursorWaypoint[] = [],191 clickFrames: number = CLICK_FRAMES,192): CursorPose {193 const moves = ordered(path);194 if (moves.length === 0) return { x: 0.5, y: 0.5, click: 0, opacity: 0 };195196 // The cursor fades up over the first waypoint's own `duration`, so a track197 // tunes its arrival without another prop. `showBefore` overrides this.198 const first = moves[0];199 const firstDur = first.duration ?? TRAVEL_FRAMES;200 const opacity =201 firstDur > 0202 ? interpolate(frame, [first.at, first.at + firstDur], [0, 1], {203 ...CLAMP,204 easing: RING_EASE,205 })206 : frame >= first.at207 ? 1208 : 0;209210 // The first waypoint places the cursor — there is nothing to travel from.211 let x = first.x;212 let y = first.y;213 for (let i = 1; i < moves.length; i++) {214 const m = moves[i];215 if (frame < m.at) break;216 const dur = m.duration ?? TRAVEL_FRAMES;217 // Truncated, never blended: a leg that overruns the next move's `at` stops218 // contributing there, so the next leg starts from the pose actually on219 // screen and the cursor never averages two destinations.220 const until =221 i + 1 < moves.length ? Math.min(frame, moves[i + 1].at) : frame;222 const p =223 dur > 0224 ? interpolate(until, [m.at, m.at + dur], [0, 1], {225 ...CLAMP,226 easing: CURSOR_EASE,227 })228 : 1;229 x += (m.x - x) * p;230 y += (m.y - y) * p;231 }232233 // The latest ring still alive wins, so two clicks close together do not stack234 // two circles on one point. Progress is measured from the frame AFTER the235 // click so `click === 0` reads as "no ring up" and the caller needs no second236 // flag; one frame of a 14-frame ring is not something you can see.237 let click = 0;238 if (clickFrames > 0) {239 for (const m of moves) {240 if (!m.click) continue;241 const at = m.at + (m.duration ?? TRAVEL_FRAMES);242 if (frame >= at && frame < at + clickFrames) {243 click = (frame - at + 1) / clickFrames;244 }245 }246 }247248 return { x, y, click, opacity };249}250251/**252 * Natural length of the cursor track — the last waypoint's `at + duration`,253 * plus `clickFrames` if it clicks, plus `TAIL_FRAMES`. A wrapper cannot see how254 * long its children run, so a scene's length is255 * `Math.max(childFrames, cursorTrackFrames(...))`.256 */257export function cursorTrackFrames(258 path: CursorWaypoint[] = [],259 clickFrames: number = CLICK_FRAMES,260): number {261 if (path.length === 0) return 0;262 let last = 0;263 for (const w of path) {264 const end =265 w.at + (w.duration ?? TRAVEL_FRAMES) + (w.click ? clickFrames : 0);266 if (end > last) last = end;267 }268 return last + TAIL_FRAMES;269}270271// --- Component -------------------------------------------------------------272273export function CursorTrack({274 children,275 path = DEMO_PATH,276 variant = "arrow",277 size,278 color,279 outlineColor,280 ringColor,281 clickFrames = CLICK_FRAMES,282 showBefore = false,283 theme,284 mode,285 speed = 1,286 className,287}: CursorTrackProps) {288 const frame = useCurrentFrame() * speed;289 const t = useKuchiTheme(theme, mode);290 const { width, height } = useVideoConfig();291 const isRendering = getRemotionEnvironment().isRendering;292 const shadowId = `cursor-shadow-${useId().replace(/:/g, "")}`;293294 const h = size ?? height * CURSOR_HEIGHT_RATIO;295 const ink = color ?? t.foreground;296 const outline = outlineColor ?? t.background;297 const ring = ringColor ?? t.primary;298299 const pose = cursorPoseAt(frame, path, clickFrames);300 const opacity = showBefore ? 1 : pose.opacity;301 const hidden = path.length === 0 || opacity <= 0;302303 // Ring: eased radius, linear opacity. It is a circle, not type, so scaling it304 // has none of the glyph-snapping failure modes the motion-quality skill warns305 // about — and it rides the cursor, so a ring never detaches from the pointer.306 const ringRadius = interpolate(307 pose.click,308 [0, 1],309 [h * RING_START, h * RING_END],310 {311 ...CLAMP,312 easing: RING_EASE,313 },314 );315 const ringOpacity = 1 - pose.click;316 const ringStroke = Math.max(1.5, h * 0.07);317318 return (319 <AbsoluteFill className={className}>320 {children}321 {!hidden && (322 <AbsoluteFill style={{ pointerEvents: "none" }}>323 {/* The one element that transforms every frame, so the one place324 will-change belongs — and only outside a render, where a stale325 raster is inherited across parallel tabs (motion-quality skill). */}326 <div327 style={{328 position: "absolute",329 left: 0,330 top: 0,331 opacity,332 transform: `translate(${pose.x * width}px, ${pose.y * height}px)`,333 ...(isRendering ? {} : { willChange: "transform" as const }),334 }}335 >336 {pose.click > 0 && (337 <div338 style={{339 position: "absolute",340 left: -ringRadius,341 top: -ringRadius,342 width: ringRadius * 2,343 height: ringRadius * 2,344 borderRadius: "50%",345 border: `${ringStroke}px solid ${ring}`,346 backgroundColor: withAlpha(ring, 0.12),347 opacity: ringOpacity,348 }}349 />350 )}351 {variant === "dot" ? (352 <div353 style={{354 position: "absolute",355 left: (-h * DOT_RATIO) / 2,356 top: (-h * DOT_RATIO) / 2,357 width: h * DOT_RATIO,358 height: h * DOT_RATIO,359 borderRadius: "50%",360 backgroundColor: withAlpha(ink, 0.42),361 border: `${Math.max(1.5, h * 0.05)}px solid ${outline}`,362 }}363 />364 ) : (365 <svg366 viewBox={`0 0 ${ARROW_VIEW} ${ARROW_VIEW}`}367 width={(h * ARROW_VIEW) / ARROW_INK}368 height={(h * ARROW_VIEW) / ARROW_INK}369 style={{370 // The hotspot is the tip, not the box's corner.371 position: "absolute",372 left: (-h * ARROW_TIP) / ARROW_INK,373 top: (-h * ARROW_TIP) / ARROW_INK,374 display: "block",375 overflow: "visible",376 }}377 >378 <title>Pointer</title>379 <defs>380 <filter381 id={shadowId}382 x="-30%"383 y="-30%"384 width="160%"385 height="160%"386 >387 <feDropShadow388 dx={0}389 dy={1}390 stdDeviation={0.8}391 floodOpacity={0.35}392 />393 </filter>394 </defs>395 {/* Rim first, then the ink over it: the site cursor, stroke396 for stroke. The rim is what carries it over footage. */}397 <g filter={`url(#${shadowId})`}>398 <path399 d={ARROW_PATH}400 fill={outline}401 stroke={outline}402 strokeWidth={5}403 strokeLinejoin="round"404 />405 <path406 d={ARROW_PATH}407 fill={ink}408 stroke={ink}409 strokeWidth={2}410 strokeLinejoin="round"411 />412 </g>413 </svg>414 )}415 </div>416 </AbsoluteFill>417 )}418 </AbsoluteFill>419 );420}









