{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"cursor-mask-reveal","type":"registry:component","title":"Cursor Mask Reveal","description":"A feathered hole that trails the pointer through one layer to expose a different one beneath, like a finished UI over its construction drawing. Drifts at rest, drag on touch, arrow keys on a keyboard. No dependencies.","dependencies":[],"registryDependencies":[],"files":[{"path":"components/viberdy/cursor-mask-reveal.tsx","content":"\"use client\";\n\nimport { useEffect, useRef, type CSSProperties, type ReactNode } from \"react\";\n\nconst IDLE_X = 0.387; // idle path start (fraction of width) - matches the server-rendered mask\nconst IDLE_Y = 0.5;\nconst IDLE_SHARE = 0.85; // idle hole = this share of `radius`\nconst PRESS_GROW = 1.15;\nconst TOUCH_LIFT = 0.55; // touch: the hole sits this many radii above the finger\nconst KEY_STEP = 32;\n\ntype Mode = \"idle\" | \"pointer\" | \"key\";\n\nexport function CursorMaskReveal({\n  base,\n  top,\n  radius = 72,\n  feather = 30,\n  showRing = true,\n  lag = 0.1,\n  idle = false,\n  mode = \"reveal\",\n  label = \"Interactive reveal. Move the pointer, drag, or use the arrow keys to uncover the layer beneath.\",\n  className,\n  style,\n}: {\n  /** The layer revealed under the pointer. */\n  base: ReactNode;\n  /** The layer the pointer punches a hole through. */\n  top: ReactNode;\n  /** Hole radius in px. */\n  radius?: number;\n  /** 0-100. How soft the edge of the hole is. */\n  feather?: number;\n  /** Outline the hole so its edge is legible over busy content. */\n  showRing?: boolean;\n  /** Seconds the hole trails the pointer (0 = glued to it). */\n  lag?: number;\n  /** Park a slowly drifting circle when nothing is pointing at the box, so the effect shows at rest. */\n  idle?: boolean;\n  /** \"reveal\" (default): the top layer shows only inside the circle and is whole at rest. \"hole\": the circle is cut out of the top layer to expose the base. */\n  mode?: \"reveal\" | \"hole\";\n  /** Accessible name of the region. */\n  label?: string;\n  className?: string;\n  style?: CSSProperties;\n}) {\n  const rootRef = useRef<HTMLDivElement>(null);\n  const ringRef = useRef<HTMLSpanElement>(null);\n  const opts = useRef({ radius, lag, idle });\n  const wakeRef = useRef<() => void>(() => {});\n\n  const f = Math.min(100, Math.max(0, feather));\n  const r0 = idle ? Math.round(radius * IDLE_SHARE) : 0;\n  const stop = (1 - f / 100).toFixed(3);\n  const at = \"circle var(--cmr-r) at var(--cmr-x) var(--cmr-y)\";\n  const mask =\n    mode === \"hole\"\n      ? \"radial-gradient(\" + at + \", transparent calc(var(--cmr-r) * \" + stop + \"), #000 var(--cmr-r))\"\n      : \"radial-gradient(\" + at + \", #000 calc(var(--cmr-r) * \" + stop + \"), transparent var(--cmr-r)), linear-gradient(rgba(0,0,0,var(--cmr-a)), rgba(0,0,0,var(--cmr-a)))\";\n\n  useEffect(() => {\n    const root = rootRef.current;\n\n    if (!root) return;\n    const mq = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    let reduced = mq.matches;\n    let W = root.offsetWidth;\n    let H = root.offsetHeight;\n    const s = {\n      x: W * IDLE_X,\n      y: H * IDLE_Y,\n      r: opts.current.idle ? opts.current.radius * IDLE_SHARE : 0,\n      tx: W * IDLE_X,\n      ty: H * IDLE_Y,\n      mode: \"idle\" as Mode,\n      pressed: false,\n      touch: false,\n      vis: true,\n      raf: 0,\n      last: 0,\n      t0: -1,\n      ready: W > 0,\n    };\n\n    const targets = (now: number) => {\n      const o = opts.current;\n      if (s.mode !== \"idle\") {\n        const k = s.pressed ? PRESS_GROW : 1;\n        return { x: s.tx, y: s.ty, r: o.radius * k };\n      }\n      if (!o.idle) return { x: s.x, y: s.y, r: 0 };\n      if (reduced) return { x: W * IDLE_X, y: H * IDLE_Y, r: o.radius * IDLE_SHARE };\n      if (s.t0 < 0) s.t0 = now;\n      const t = (now - s.t0) / 1000;\n      return {\n        x: W * (0.5 + 0.2 * Math.sin(t * 0.5 - 0.6)),\n        y: H * (0.5 + 0.16 * Math.sin(t * 0.37)),\n        r: o.radius * IDLE_SHARE,\n      };\n    };\n\n    const paint = () => {\n      const o = opts.current;\n      root.style.setProperty(\"--cmr-x\", s.x.toFixed(1) + \"px\");\n      root.style.setProperty(\"--cmr-y\", s.y.toFixed(1) + \"px\");\n      root.style.setProperty(\"--cmr-r\", Math.max(0, s.r).toFixed(1) + \"px\");\n      root.style.setProperty(\"--cmr-a\", Math.max(0, 1 - s.r / Math.max(1, o.radius * 0.6)).toFixed(3));\n      const ring = ringRef.current;\n      if (ring) {\n        const k = o.radius > 0 ? s.r / o.radius : 0;\n        ring.style.opacity = String(Math.min(1, Math.max(0, k * 1.6)));\n        ring.style.transform =\n          \"translate3d(\" + (s.x - o.radius).toFixed(1) + \"px,\" + (s.y - o.radius).toFixed(1) + \"px,0) scale(\" + Math.max(0.001, k).toFixed(3) + \")\";\n      }\n    };\n\n    const frame = (now: number) => {\n      s.raf = 0;\n      const dt = s.last ? Math.min(0.05, (now - s.last) / 1000) : 1 / 60;\n      s.last = now;\n      const g = targets(now);\n      const o = opts.current;\n      const aPos = reduced || o.lag <= 0 ? 1 : 1 - Math.exp(-dt / Math.max(0.005, o.lag));\n      const aRad = reduced ? 1 : 1 - Math.exp(-dt / 0.085);\n      s.x += (g.x - s.x) * aPos;\n      s.y += (g.y - s.y) * aPos;\n      s.r += (g.r - s.r) * aRad;\n      const drifting = s.mode === \"idle\" && o.idle && !reduced;\n      const settled = Math.abs(g.x - s.x) < 0.1 && Math.abs(g.y - s.y) < 0.1 && Math.abs(g.r - s.r) < 0.1;\n      if (settled && !drifting) {\n        s.x = g.x;\n        s.y = g.y;\n        s.r = g.r;\n        paint();\n        s.last = 0;\n        return;\n      }\n      paint();\n      if (s.vis && !document.hidden) s.raf = requestAnimationFrame(frame);\n      else s.last = 0;\n    };\n\n    const wake = () => {\n      if (!s.raf && s.vis && !document.hidden) s.raf = requestAnimationFrame(frame);\n    };\n    wakeRef.current = wake;\n\n    const place = (e: PointerEvent) => {\n      const rect = root.getBoundingClientRect();\n      const kx = rect.width ? root.offsetWidth / rect.width : 1;\n      const ky = rect.height ? root.offsetHeight / rect.height : 1;\n      s.tx = (e.clientX - rect.left) * kx;\n      s.ty = (e.clientY - rect.top) * ky - (s.touch ? opts.current.radius * TOUCH_LIFT : 0);\n    };\n    const onEnter = (e: PointerEvent) => {\n      if (e.pointerType === \"touch\") return;\n      s.touch = false;\n      s.mode = \"pointer\";\n      place(e);\n      wake();\n    };\n    const onMove = (e: PointerEvent) => {\n      if (e.pointerType === \"touch\" && !s.pressed) return;\n      s.touch = e.pointerType === \"touch\";\n      s.mode = \"pointer\";\n      place(e);\n      wake();\n    };\n    const onDown = (e: PointerEvent) => {\n      s.touch = e.pointerType === \"touch\";\n      s.pressed = true;\n      s.mode = \"pointer\";\n      place(e);\n      wake();\n    };\n    const onUp = (e: PointerEvent) => {\n      s.pressed = false;\n      if (e.pointerType === \"touch\") s.mode = \"idle\";\n      wake();\n    };\n    const onLeave = (e: PointerEvent) => {\n      if (e.pointerType === \"touch\") return;\n      s.pressed = false;\n      if (s.mode === \"pointer\") s.mode = \"idle\";\n      wake();\n    };\n    const onKey = (e: KeyboardEvent) => {\n      if (e.target !== root) return;\n      const step = e.shiftKey ? KEY_STEP * 3 : KEY_STEP;\n      let dx = 0;\n      let dy = 0;\n      if (e.key === \"ArrowLeft\") dx = -step;\n      else if (e.key === \"ArrowRight\") dx = step;\n      else if (e.key === \"ArrowUp\") dy = -step;\n      else if (e.key === \"ArrowDown\") dy = step;\n      else if (e.key === \"Escape\" && s.mode === \"key\") {\n        s.mode = \"idle\";\n        wake();\n        return;\n      } else return;\n      e.preventDefault();\n      if (s.mode !== \"key\") {\n        s.mode = \"key\";\n        s.tx = s.x;\n        s.ty = s.y;\n      }\n      s.tx = Math.min(W, Math.max(0, s.tx + dx));\n      s.ty = Math.min(H, Math.max(0, s.ty + dy));\n      wake();\n    };\n    const onFocus = () => {\n      if (!root.matches(\":focus-visible\") || s.mode === \"pointer\") return;\n      s.mode = \"key\";\n      s.tx = s.x;\n      s.ty = s.y;\n      wake();\n    };\n    const onBlur = () => {\n      if (s.mode === \"key\") s.mode = \"idle\";\n      wake();\n    };\n\n    const ro = new ResizeObserver(() => {\n      W = root.offsetWidth;\n      H = root.offsetHeight;\n      if (!s.ready && W > 0) {\n        s.ready = true;\n        s.x = s.tx = W * IDLE_X;\n        s.y = s.ty = H * IDLE_Y;\n      }\n      s.tx = Math.min(W, s.tx);\n      s.ty = Math.min(H, s.ty);\n      wake();\n    });\n    ro.observe(root);\n    const io = new IntersectionObserver(\n      (en) => {\n        s.vis = en.some((x) => x.isIntersecting);\n        if (s.vis) wake();\n      },\n      { rootMargin: \"200px\" },\n    );\n    io.observe(root);\n    const onVis = () => wake();\n    const onMq = () => {\n      reduced = mq.matches;\n      wake();\n    };\n    document.addEventListener(\"visibilitychange\", onVis);\n    mq.addEventListener(\"change\", onMq);\n    root.addEventListener(\"pointerenter\", onEnter);\n    root.addEventListener(\"pointermove\", onMove);\n    root.addEventListener(\"pointerdown\", onDown);\n    root.addEventListener(\"pointerup\", onUp);\n    root.addEventListener(\"pointercancel\", onUp);\n    root.addEventListener(\"pointerleave\", onLeave);\n    root.addEventListener(\"keydown\", onKey);\n    root.addEventListener(\"focus\", onFocus);\n    root.addEventListener(\"blur\", onBlur);\n    paint();\n    wake();\n    return () => {\n      cancelAnimationFrame(s.raf);\n      s.raf = 0;\n      ro.disconnect();\n      io.disconnect();\n      document.removeEventListener(\"visibilitychange\", onVis);\n      mq.removeEventListener(\"change\", onMq);\n      root.removeEventListener(\"pointerenter\", onEnter);\n      root.removeEventListener(\"pointermove\", onMove);\n      root.removeEventListener(\"pointerdown\", onDown);\n      root.removeEventListener(\"pointerup\", onUp);\n      root.removeEventListener(\"pointercancel\", onUp);\n      root.removeEventListener(\"pointerleave\", onLeave);\n      root.removeEventListener(\"keydown\", onKey);\n      root.removeEventListener(\"focus\", onFocus);\n      root.removeEventListener(\"blur\", onBlur);\n    };\n  }, []);\n\n  useEffect(() => {\n    opts.current = { radius, lag, idle };\n    wakeRef.current();\n  }, [radius, lag, idle]);\n\n  return (\n    <div\n      ref={rootRef}\n      role=\"group\"\n      aria-label={label}\n      tabIndex={0}\n      className={\"group relative touch-pan-y overflow-hidden outline-none focus-visible:!outline-0 \" + (className ?? \"\")}\n      style={\n        {\n          \"--cmr-x\": (IDLE_X * 100).toFixed(1) + \"%\",\n          \"--cmr-y\": IDLE_Y * 100 + \"%\",\n          \"--cmr-r\": r0 + \"px\",\n          \"--cmr-a\": Math.max(0, 1 - r0 / Math.max(1, radius * 0.6)).toFixed(3),\n          ...style,\n        } as CSSProperties\n      }\n    >\n      <div className=\"absolute inset-0\">{base}</div>\n\n      {/* The top layer carries a real CSS mask, so the base can be any markup. The engine writes only\n          the --cmr-* custom properties; the mask string itself never changes per frame. */}\n      <div className=\"absolute inset-0\" style={{ maskImage: mask, WebkitMaskImage: mask }}>\n        {top}\n      </div>\n\n      {showRing && (\n        <span\n          ref={ringRef}\n          aria-hidden\n          className=\"pointer-events-none absolute left-0 top-0 rounded-full opacity-0 will-change-transform\"\n          style={{\n            width: radius * 2,\n            height: radius * 2,\n            boxShadow:\n              \"inset 0 0 0 1px rgba(255,255,255,0.62), 0 0 0 1px rgba(0,0,0,0.3), inset 0 0 26px rgba(255,255,255,0.12), 0 18px 40px -12px rgba(0,0,0,0.5)\",\n          }}\n        />\n      )}\n\n      <span\n        aria-hidden\n        className=\"pointer-events-none absolute inset-0 rounded-[inherit] opacity-0 ring-2 ring-inset ring-sky-400 transition-opacity duration-150 group-focus-visible:opacity-100\"\n      />\n    </div>\n  );\n}\n","type":"registry:component","target":"components/viberdy/cursor-mask-reveal.tsx"}],"meta":{"tier":"free","tags":["cursor","mask","reveal","hover","spotlight","x-ray"],"href":"https://viberdy.dev/library/cursor-mask-reveal","aiPrompt":"Create a single-file React + Tailwind component named CursorMaskReveal (a \"use client\" file, React only, no animation library): the pointer cuts a soft hole through a top layer to reveal a different layer underneath.\n\nProps: base (ReactNode, required, the revealed layer), top (ReactNode, required, the layer that gets the hole); radius 72 (px); feather 30 (0-100, share of the radius that is soft edge); showRing true; mode \"reveal\" | \"hole\" (default \"reveal\"); lag 0.1 (seconds the hole trails the pointer, 0 = glued); idle false (park a drifting circle when nothing points at the box); label (accessible name, default \"Interactive reveal. Move the pointer, drag, or use the arrow keys to uncover the layer beneath.\"); className; style.\n\nStructure: root div \"group relative touch-pan-y overflow-hidden outline-none focus-visible:!outline-0\" plus className, role group, aria-label, tabIndex 0, inline custom properties --cmr-x (38.7%), --cmr-y (50%), --cmr-r (idle ? round(radius*0.85) : 0)px and --cmr-a (as defined below) so the server render already shows the parked hole. Children: base in \"absolute inset-0\"; top in \"absolute inset-0\" carrying a REAL CSS mask on both maskImage and WebkitMaskImage. mode hole: radial-gradient(circle var(--cmr-r) at var(--cmr-x) var(--cmr-y), transparent calc(var(--cmr-r) * (1 - feather/100)), #000 var(--cmr-r)) (a hole cut in top). mode reveal (default, the original look): radial-gradient(same circle, #000 calc(var(--cmr-r) * (1 - feather/100)), transparent var(--cmr-r)), linear-gradient(rgba(0,0,0,var(--cmr-a)), rgba(0,0,0,var(--cmr-a))) so top shows only inside the circle but is whole at rest; --cmr-a = max(0, 1 - r / (radius*0.6)) is written with the other vars. It is a mask, not a tinted gradient: the base can be any markup. The mask string never changes per frame; only the custom properties do. If showRing: an aria-hidden span (pointer-events none, absolute, left/top 0, rounded-full, width/height radius*2) with box-shadow inset 0 0 0 1px rgba(255,255,255,.62), 0 0 0 1px rgba(0,0,0,.3), inset 0 0 26px rgba(255,255,255,.12), 0 18px 40px -12px rgba(0,0,0,.5), positioned by transform translate3d(x - radius, y - radius, 0) scale(r / radius) and opacity min(1, 1.6 * r / radius). Last, a focus ring: an aria-hidden absolute inset-0 span, rounded-[inherit], ring-2 ring-inset ring-sky-400, opacity 0, group-focus-visible:opacity-100.\n\nMotion: ONE requestAnimationFrame loop in a mount effect writes --cmr-x/y/r and the ring transform directly (never React state per pixel; props the loop reads go through a ref synced in an effect). Position eases with a = 1 - exp(-dt / lag) (dt clamped to 50 ms), radius with time constant 85 ms. Target radius is radius while a pointer/finger/key owns the hole (x1.15 while pressed), radius*0.85 when idle, 0 when idle is off. Idle path: x = W*(0.5 + 0.2*sin(0.5 t - 0.6)), y = H*(0.5 + 0.16*sin(0.37 t)), t seconds since the first idle frame, so it starts at 38.7% / 50%. The loop sleeps when settled (and not drifting), when the root is off-screen (IntersectionObserver, rootMargin 200px) and when the tab is hidden; a ResizeObserver tracks the layout size. Pointer coordinates are mapped to layout px: (clientX - rect.left) * offsetWidth / rect.width.\n\nInput (native pointer listeners on the root): mouse and pen follow on enter/move and release to idle on leave; touch follows only while pressed, the hole lifted 0.55 radius above the finger, back to idle on release or cancel (touch-action pan-y keeps vertical scrolling). Keyboard: when the root itself is focused, arrows move the hole 32px (Shift 96), clamped to the box, Escape returns to idle; focus-visible opens the hole at its current spot, blur closes it. Ignore keys whose target is a child.\n\nprefers-reduced-motion (matchMedia, live): no easing and no drift; the idle circle parks at 38.7% / 50% and the hole snaps to the pointer. Output one self-contained file.","license":"https://viberdy.dev/license"}}