cursor-puppet

name	cursor-puppet
description	motion-graphic primitive — fake macos-style mouse cursor that moves along a bezier path and clicks ui affordances. paired with prompt-typewriter in sp-f product demos. feels like real product capture, not motion-graphic puppetry.

cursor-puppet

Purpose

Render a fake mouse cursor (typically the macOS arrow) that moves along a defined path and performs click gestures at specific frames. Implies "the user is actually using this product" rather than "we made a motion graphic".

Params

{
  "cursor_svg_src": "assets/cursor-macos.svg",
  "cursor_size_px": 18,

  "path": [
    { "frame": 0,  "x": 400, "y": 1200 },
    { "frame": 24, "x": 720, "y": 1100 }   // travel
  ],
  "movement_easing": "bezier(0.4, 0, 0.2, 1)",

  "clicks": [
    {
      "frame": 30,
      "scale_overshoot": 1.4,
      "recover_frames": 6,
      "click_target_id": "submit-button"   // optional — for visual sync
    }
  ],

  "z_index": 10000                        // always above everything
}

Behaviour

1. Render the cursor SVG at its path-interpolated position per frame.
2. Movement: bezier easing along the path keyframes.
3. At click frames: scale-bounce the cursor (1.0 → 1.4 → 1.0) over recover_frames.
4. Optionally trigger a visual effect on click_target_id (e.g. button press-state).

Style pack overrides

• SP-F (product-demo) — canonical use, paired with prompt-typewriter (A15 archetype).

Quality Checks

• Movement uses bezier (not linear) — feels human.
• Click scale-bounce is visible (≥1.3x overshoot).
• Cursor is small (16-20px) — not oversized.
• Cursor renders ABOVE all other content.

Failure Modes

• Movement linear / robotic. Switch to bezier.
• Click invisible. Increase overshoot to 1.4+.
• Cursor lags below other layers. Ensure z-index is highest.
• Cursor SVG renders pixelated. Use vector SVG, not raster PNG, at the rendered size.