{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"cursor-track","type":"registry:component","title":"Cursor Track","description":"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.","dependencies":["remotion"],"docs":"Needs a Remotion project. If a frame renders black, the component is drawing on a transparent layer: put a background behind it, e.g. <AbsoluteFill style={{ background: \"#faf9f6\" }}><Component /></AbsoluteFill>. Pass mode=\"dark\" for dark frames.","registryDependencies":["https://kuchi.kalarislabs.com/r/kuchi-ui.json"],"files":[{"path":"components/kuchi/cursor-track.tsx","type":"registry:component","target":"components/kuchi/cursor-track.tsx","content":"/*! Portions Copyright (c) 2026 Sri Nath (snap-cn). MIT License. See THIRD_PARTY_LICENSES. */\n\"use client\";\r\n\r\nimport { type ReactNode, useId } from \"react\";\r\nimport {\r\n  AbsoluteFill,\r\n  Easing,\r\n  getRemotionEnvironment,\r\n  interpolate,\r\n  useCurrentFrame,\r\n  useVideoConfig,\r\n} from \"remotion\";\r\nimport { type KuchiTheme, useKuchiTheme, withAlpha } from \"@/lib/kuchi-ui\";\r\n\r\nexport type CursorVariant = \"arrow\" | \"dot\";\r\n\r\nexport interface CursorWaypoint {\r\n  /**\r\n   * Frame the cursor starts travelling TOWARDS this point, on this component's\r\n   * own clock (i.e. against `useCurrentFrame() * speed`). Absolute, not\r\n   * relative to the previous waypoint. Waypoints are sorted by `at`; ties break\r\n   * on array order and the last one wins.\r\n   *\r\n   * The FIRST waypoint has nothing to travel from, so it places the cursor\r\n   * rather than moving it — give it an off-frame `x` to have the cursor walk in.\r\n   */\r\n  at: number;\r\n  /**\r\n   * Destination, normalized: 0 -> 1 left to right across the composition,\r\n   * origin top-left. FRAME coordinates — a camera move inside a child\r\n   * `<ScreenRecording>` does not move the cursor. Values outside 0-1 are legal\r\n   * and mean off-frame, so a cursor entering from the left starts at `x: -0.1`.\r\n   */\r\n  x: number;\r\n  /** Destination, normalized: 0 -> 1 top to bottom. */\r\n  y: number;\r\n  /**\r\n   * Frames the travel takes. Default 14. The cursor then RESTS here until the\r\n   * next waypoint's `at` — there is no hold field, the hold is the gap. On the\r\n   * first waypoint there is no travel, so this is the fade-up window instead.\r\n   */\r\n  duration?: number;\r\n  /**\r\n   * Pulse a click ring on ARRIVAL, i.e. at `at + duration`. To click twice\r\n   * without moving, add a second waypoint at the same `x`/`y`.\r\n   */\r\n  click?: boolean;\r\n}\r\n\r\nexport interface CursorTrackProps {\r\n  /**\r\n   * What the cursor moves over — anything. Rendered full-bleed underneath it.\r\n   * Put the `<ScreenRecording>` (or the UI sim) in here, not this inside that:\r\n   * the cursor has to be the top layer to read as a cursor.\r\n   */\r\n  children?: ReactNode;\r\n  /**\r\n   * The path, in any order. Defaults to `DEMO_PATH` so the component is worth\r\n   * looking at with no props; pass `[]` and it renders nothing at all, i.e. it\r\n   * becomes a no-op wrapper.\r\n   */\r\n  path?: CursorWaypoint[];\r\n  /** `arrow` (default) is a pointer; `dot` is a touch/tap puck. */\r\n  variant?: CursorVariant;\r\n  /**\r\n   * Cursor height in px. Omit it and the component computes 3.9% of the\r\n   * composition height, so it stays the size a real cursor looks at any crop.\r\n   */\r\n  size?: number;\r\n  /**\r\n   * Cursor fill. Defaults to the theme's `foreground` — so pass `mode=\"dark\"`\r\n   * when the recording underneath is dark, and the cursor and its outline swap\r\n   * together.\r\n   */\r\n  color?: string;\r\n  /**\r\n   * The outline that keeps the cursor readable over arbitrary footage. Defaults\r\n   * to the theme's `background`, the opposite end of `color`.\r\n   */\r\n  outlineColor?: string;\r\n  /** The click ring. Defaults to the theme's `primary`. */\r\n  ringColor?: string;\r\n  /** Frames a click ring lives for. Default 14. */\r\n  clickFrames?: number;\r\n  /**\r\n   * Show the cursor parked at the first waypoint before its `at`. Default\r\n   * false — it fades in as the first move starts, which is what stops a cursor\r\n   * sitting inertly on frame 0.\r\n   */\r\n  showBefore?: boolean;\r\n  /** Design-system token overrides. */\r\n  theme?: Partial<KuchiTheme>;\r\n  mode?: \"light\" | \"dark\";\r\n  /** Time multiplier. Every `at` is measured against `useCurrentFrame() * speed`. */\r\n  speed?: number;\r\n  className?: string;\r\n}\r\n\r\n// --- Constants -------------------------------------------------------------\r\n\r\n/**\r\n * Cursor travel, and deliberately NOT the camera curve. A pointer accelerates\r\n * and decelerates; a camera decelerate on a cursor reads robotic. Same curve\r\n * the notch morph and the showcase crane already use.\r\n */\r\nexport const CURSOR_EASE = Easing.inOut(Easing.cubic);\r\n\r\n/** Click ring growth. Opacity fades linearly under it. */\r\nexport const RING_EASE = Easing.out(Easing.cubic);\r\n\r\nexport const TRAVEL_FRAMES = 14;\r\nexport const CLICK_FRAMES = 14;\r\nexport const TAIL_FRAMES = 18;\r\n\r\n/** Cursor height as a fraction of the composition height, when `size` is omitted. */\r\nexport const CURSOR_HEIGHT_RATIO = 0.039;\r\n\r\n/** Ring radius at birth and at death, as multiples of the cursor height. */\r\nexport const RING_START = 0.18;\r\nexport const RING_END = 1.1;\r\n\r\n/**\r\n * The site's own pointer (app/globals.css): a rounded arrow, ink with a rim and\r\n * a soft shadow, in a 24-unit box with its hotspot — the tip — at (5.5, 5.5).\r\n * An SVG and not an emoji or a font glyph: a glyph is whatever face the\r\n * renderer happens to resolve, and it would carry the hinting problems the\r\n * motion-quality skill is about into the one element that moves every frame.\r\n */\r\nconst ARROW_VIEW = 24;\r\nconst ARROW_TIP = 5.5;\r\n/** The arrow's ink spans 14 of the 24 units; `size` is that span. */\r\nconst ARROW_INK = 14;\r\nconst ARROW_PATH = \"M5.5 5.5 19 11l-5.6 1.45a2 2 0 0 0-1.45 1.45L10.5 19.5z\";\r\n\r\n/** The `dot` puck's diameter, as a multiple of the cursor height. */\r\nconst DOT_RATIO = 0.62;\r\n\r\n/**\r\n * A short demo path: in from off-frame bottom-left, click, cross the frame,\r\n * click, then move off to the top-right. Carries the customizer preview and the\r\n * MCP skeleton, because `ControlType` has no array control to expose `path`\r\n * through — the same way `terminal-simulator` handles `lines`.\r\n */\r\nexport const DEMO_PATH: CursorWaypoint[] = [\r\n  { at: 0, x: -0.06, y: 0.86, duration: 6 },\r\n  { at: 8, x: 0.34, y: 0.44, duration: 22, click: true },\r\n  { at: 52, x: 0.68, y: 0.62, duration: 20, click: true },\r\n  { at: 96, x: 0.82, y: 0.28, duration: 18 },\r\n];\r\n\r\n// --- Pure helpers (unit-tested) -------------------------------------------\r\n\r\nexport interface CursorPose {\r\n  /** Position, normalized to the frame, origin top-left. */\r\n  x: number;\r\n  y: number;\r\n  /** Click-ring progress, 0 -> 1, or 0 when no ring is up. */\r\n  click: number;\r\n  /** 0 before the cursor has appeared, 1 once it has. */\r\n  opacity: number;\r\n}\r\n\r\nconst CLAMP = {\r\n  extrapolateLeft: \"clamp\",\r\n  extrapolateRight: \"clamp\",\r\n} as const;\r\n\r\n/**\r\n * Waypoints in the order they actually play. Same-`at` ties: the later array\r\n * entry wins and the earlier tied entries never display, so they can never act\r\n * as a leg's origin — the rule `useStateTransition` already uses for `Step`.\r\n */\r\nfunction ordered(path: CursorWaypoint[]): CursorWaypoint[] {\r\n  return path\r\n    .map((w, index) => ({ w, index }))\r\n    .sort((a, b) => a.w.at - b.w.at || a.index - b.index)\r\n    .filter((e, i, arr) => i === arr.length - 1 || arr[i + 1].w.at !== e.w.at)\r\n    .map((e) => e.w);\r\n}\r\n\r\n/**\r\n * The cursor's pose at `frame`, folding the path forward so a waypoint that\r\n * starts mid-travel takes over from where the cursor actually is. Pure: same\r\n * frame, same answer, whatever order Remotion renders in.\r\n *\r\n * ponytail: straight-line travel. If it reads robotic, add a per-leg arc here,\r\n * not a prop.\r\n */\r\nexport function cursorPoseAt(\r\n  frame: number,\r\n  path: CursorWaypoint[] = [],\r\n  clickFrames: number = CLICK_FRAMES,\r\n): CursorPose {\r\n  const moves = ordered(path);\r\n  if (moves.length === 0) return { x: 0.5, y: 0.5, click: 0, opacity: 0 };\r\n\r\n  // The cursor fades up over the first waypoint's own `duration`, so a track\r\n  // tunes its arrival without another prop. `showBefore` overrides this.\r\n  const first = moves[0];\r\n  const firstDur = first.duration ?? TRAVEL_FRAMES;\r\n  const opacity =\r\n    firstDur > 0\r\n      ? interpolate(frame, [first.at, first.at + firstDur], [0, 1], {\r\n          ...CLAMP,\r\n          easing: RING_EASE,\r\n        })\r\n      : frame >= first.at\r\n        ? 1\r\n        : 0;\r\n\r\n  // The first waypoint places the cursor — there is nothing to travel from.\r\n  let x = first.x;\r\n  let y = first.y;\r\n  for (let i = 1; i < moves.length; i++) {\r\n    const m = moves[i];\r\n    if (frame < m.at) break;\r\n    const dur = m.duration ?? TRAVEL_FRAMES;\r\n    // Truncated, never blended: a leg that overruns the next move's `at` stops\r\n    // contributing there, so the next leg starts from the pose actually on\r\n    // screen and the cursor never averages two destinations.\r\n    const until =\r\n      i + 1 < moves.length ? Math.min(frame, moves[i + 1].at) : frame;\r\n    const p =\r\n      dur > 0\r\n        ? interpolate(until, [m.at, m.at + dur], [0, 1], {\r\n            ...CLAMP,\r\n            easing: CURSOR_EASE,\r\n          })\r\n        : 1;\r\n    x += (m.x - x) * p;\r\n    y += (m.y - y) * p;\r\n  }\r\n\r\n  // The latest ring still alive wins, so two clicks close together do not stack\r\n  // two circles on one point. Progress is measured from the frame AFTER the\r\n  // click so `click === 0` reads as \"no ring up\" and the caller needs no second\r\n  // flag; one frame of a 14-frame ring is not something you can see.\r\n  let click = 0;\r\n  if (clickFrames > 0) {\r\n    for (const m of moves) {\r\n      if (!m.click) continue;\r\n      const at = m.at + (m.duration ?? TRAVEL_FRAMES);\r\n      if (frame >= at && frame < at + clickFrames) {\r\n        click = (frame - at + 1) / clickFrames;\r\n      }\r\n    }\r\n  }\r\n\r\n  return { x, y, click, opacity };\r\n}\r\n\r\n/**\r\n * Natural length of the cursor track — the last waypoint's `at + duration`,\r\n * plus `clickFrames` if it clicks, plus `TAIL_FRAMES`. A wrapper cannot see how\r\n * long its children run, so a scene's length is\r\n * `Math.max(childFrames, cursorTrackFrames(...))`.\r\n */\r\nexport function cursorTrackFrames(\r\n  path: CursorWaypoint[] = [],\r\n  clickFrames: number = CLICK_FRAMES,\r\n): number {\r\n  if (path.length === 0) return 0;\r\n  let last = 0;\r\n  for (const w of path) {\r\n    const end =\r\n      w.at + (w.duration ?? TRAVEL_FRAMES) + (w.click ? clickFrames : 0);\r\n    if (end > last) last = end;\r\n  }\r\n  return last + TAIL_FRAMES;\r\n}\r\n\r\n// --- Component -------------------------------------------------------------\r\n\r\nexport function CursorTrack({\r\n  children,\r\n  path = DEMO_PATH,\r\n  variant = \"arrow\",\r\n  size,\r\n  color,\r\n  outlineColor,\r\n  ringColor,\r\n  clickFrames = CLICK_FRAMES,\r\n  showBefore = false,\r\n  theme,\r\n  mode,\r\n  speed = 1,\r\n  className,\r\n}: CursorTrackProps) {\r\n  const frame = useCurrentFrame() * speed;\r\n  const t = useKuchiTheme(theme, mode);\r\n  const { width, height } = useVideoConfig();\r\n  const isRendering = getRemotionEnvironment().isRendering;\r\n  const shadowId = `cursor-shadow-${useId().replace(/:/g, \"\")}`;\r\n\r\n  const h = size ?? height * CURSOR_HEIGHT_RATIO;\r\n  const ink = color ?? t.foreground;\r\n  const outline = outlineColor ?? t.background;\r\n  const ring = ringColor ?? t.primary;\r\n\r\n  const pose = cursorPoseAt(frame, path, clickFrames);\r\n  const opacity = showBefore ? 1 : pose.opacity;\r\n  const hidden = path.length === 0 || opacity <= 0;\r\n\r\n  // Ring: eased radius, linear opacity. It is a circle, not type, so scaling it\r\n  // has none of the glyph-snapping failure modes the motion-quality skill warns\r\n  // about — and it rides the cursor, so a ring never detaches from the pointer.\r\n  const ringRadius = interpolate(\r\n    pose.click,\r\n    [0, 1],\r\n    [h * RING_START, h * RING_END],\r\n    {\r\n      ...CLAMP,\r\n      easing: RING_EASE,\r\n    },\r\n  );\r\n  const ringOpacity = 1 - pose.click;\r\n  const ringStroke = Math.max(1.5, h * 0.07);\r\n\r\n  return (\r\n    <AbsoluteFill className={className}>\r\n      {children}\r\n      {!hidden && (\r\n        <AbsoluteFill style={{ pointerEvents: \"none\" }}>\r\n          {/* The one element that transforms every frame, so the one place\r\n              will-change belongs — and only outside a render, where a stale\r\n              raster is inherited across parallel tabs (motion-quality skill). */}\r\n          <div\r\n            style={{\r\n              position: \"absolute\",\r\n              left: 0,\r\n              top: 0,\r\n              opacity,\r\n              transform: `translate(${pose.x * width}px, ${pose.y * height}px)`,\r\n              ...(isRendering ? {} : { willChange: \"transform\" as const }),\r\n            }}\r\n          >\r\n            {pose.click > 0 && (\r\n              <div\r\n                style={{\r\n                  position: \"absolute\",\r\n                  left: -ringRadius,\r\n                  top: -ringRadius,\r\n                  width: ringRadius * 2,\r\n                  height: ringRadius * 2,\r\n                  borderRadius: \"50%\",\r\n                  border: `${ringStroke}px solid ${ring}`,\r\n                  backgroundColor: withAlpha(ring, 0.12),\r\n                  opacity: ringOpacity,\r\n                }}\r\n              />\r\n            )}\r\n            {variant === \"dot\" ? (\r\n              <div\r\n                style={{\r\n                  position: \"absolute\",\r\n                  left: (-h * DOT_RATIO) / 2,\r\n                  top: (-h * DOT_RATIO) / 2,\r\n                  width: h * DOT_RATIO,\r\n                  height: h * DOT_RATIO,\r\n                  borderRadius: \"50%\",\r\n                  backgroundColor: withAlpha(ink, 0.42),\r\n                  border: `${Math.max(1.5, h * 0.05)}px solid ${outline}`,\r\n                }}\r\n              />\r\n            ) : (\r\n              <svg\r\n                viewBox={`0 0 ${ARROW_VIEW} ${ARROW_VIEW}`}\r\n                width={(h * ARROW_VIEW) / ARROW_INK}\r\n                height={(h * ARROW_VIEW) / ARROW_INK}\r\n                style={{\r\n                  // The hotspot is the tip, not the box's corner.\r\n                  position: \"absolute\",\r\n                  left: (-h * ARROW_TIP) / ARROW_INK,\r\n                  top: (-h * ARROW_TIP) / ARROW_INK,\r\n                  display: \"block\",\r\n                  overflow: \"visible\",\r\n                }}\r\n              >\r\n                <title>Pointer</title>\r\n                <defs>\r\n                  <filter\r\n                    id={shadowId}\r\n                    x=\"-30%\"\r\n                    y=\"-30%\"\r\n                    width=\"160%\"\r\n                    height=\"160%\"\r\n                  >\r\n                    <feDropShadow\r\n                      dx={0}\r\n                      dy={1}\r\n                      stdDeviation={0.8}\r\n                      floodOpacity={0.35}\r\n                    />\r\n                  </filter>\r\n                </defs>\r\n                {/* Rim first, then the ink over it: the site cursor, stroke\r\n                    for stroke. The rim is what carries it over footage. */}\r\n                <g filter={`url(#${shadowId})`}>\r\n                  <path\r\n                    d={ARROW_PATH}\r\n                    fill={outline}\r\n                    stroke={outline}\r\n                    strokeWidth={5}\r\n                    strokeLinejoin=\"round\"\r\n                  />\r\n                  <path\r\n                    d={ARROW_PATH}\r\n                    fill={ink}\r\n                    stroke={ink}\r\n                    strokeWidth={2}\r\n                    strokeLinejoin=\"round\"\r\n                  />\r\n                </g>\r\n              </svg>\r\n            )}\r\n          </div>\r\n        </AbsoluteFill>\r\n      )}\r\n    </AbsoluteFill>\r\n  );\r\n}\r\n"}]}