What I wanted to build

The starting point was a visual interaction: a clean hero scene where one image is always visible and a second image appears only through a soft cursor trail. Not a hard hover magnifier. Not a simple before/after slider. A wide, fading, painterly reveal that follows the pointer and leaves a temporary trace.

The live result is here: Mouse Trail Masking Reveal project page. The standalone interactive demo is here: open live demo.

Video: Final implementation demo by @sergekost.

The public repository is sergekostenchuk/mouse-trail-masking-reveal.

The design reference was manual

The idea was inspired by a manual Figma workflow shared by @thedesignely. The important part was not to copy a file or a brand style. The useful part was the interaction pattern: one layer stays stable, another layer appears through a controlled mask.

Video: Reference video by @thedesignely that inspired the layer-mask direction.

That is exactly the kind of effect that looks simple from the outside and becomes fragile during implementation. The images have to match. The mask has to be soft. The trail has to fade. The canvas has to stay sharp on desktop and mobile. The controls have to change the actual parameters, not just move sliders.

Why I split it into two skills

The first lesson was that the frontend effect cannot solve a bad image pair.

If the base image and reveal image are not aligned, the cursor trail exposes the mistake immediately. A face shifts. A helmet jumps. A background object breaks the illusion. No amount of CSS polish fixes that reliably.

So the package became two skills instead of one:

  • image-layer-alignment-validator checks whether the base and reveal raster layers are spatially compatible.
  • cursor-reveal-hero builds, repairs, tunes, and validates the interactive canvas reveal.

That split is the architecture. First validate the source layers, then implement the interaction.

The core formula

The effect is built around one simple formula:

final = baseImage + revealImage * softCursorTrailMask

The visible canvas draws the base image every frame. The reveal image is drawn into an offscreen canvas. A separate mask canvas stores the cursor trail. The reveal layer is clipped by that mask and then drawn over the base.

The important canvas pieces are:

canvas / ctx          - visible output
maskCanvas / maskCtx  - grayscale alpha map for cursor trail
revealCanvas / revealCtx - temporary reveal layer before masking
baseImage             - always visible
revealImage           - visible only through the mask

The key compositing step is destination-in. It keeps only the part of the reveal layer where the mask has alpha.

The interaction had to feel soft

The first version of this kind of effect can easily become a rigid circular flashlight. That was not the goal.

The settings that control the feel are:

const settings = {
  radius: 245,
  feather: 0.8,
  fade: 0.028,
  strength: 0.82,
  opacity: 0.78,
  lerp: 0.14,
  idleStrength: 0
};

radius controls the reveal zone. feather controls the softness of the edge. fade controls how quickly old trail content disappears. opacity controls how strongly the reveal layer sits over the base. lerp gives the mask momentum, so the reveal does not feel glued to the pointer.

The FX panel on the demo page exists because these values are not abstract. They have to be tuned by eye.

The agent skill is more useful than the demo

The demo is the visible artifact. The skill package is the reusable part.

The repository contains:

  • two SKILL.md files;
  • a vanilla HTML/CSS/JS starter;
  • canvas compositing notes;
  • tuning and failure-mode notes;
  • browser validation notes;
  • provider adapters for different coding agents;
  • media attribution and privacy/security notes.

That matters because the goal is not "make this one page". The goal is to give a coding agent enough structure to recreate, repair, and validate the effect in another frontend project.

What I learned

The main lesson is that creative frontend work needs a pipeline, not only inspiration.

For this effect, the pipeline is:

  1. check whether the image layers can be composited;
  2. build the canvas compositor;
  3. tune the mask radius, feather, fade, strength, opacity, and momentum;
  4. validate that the canvas is nonblank and pointer movement changes pixels;
  5. inspect the result visually because smoke checks do not prove taste.

That is the same pattern I keep seeing in agent-assisted work. A good skill does not just tell the model what to do. It gives the model a sequence, evidence, checks, and failure modes.

Mouse Trail Masking Reveal started as a visual experiment. It became a small example of how to turn a fragile creative workflow into reusable agent tooling.